docs: marketplace client is the open @objectstack/cloud-connection package + os package install (ADR-0008) (#22)

- marketplace.mdx: 'How it works' reflects the post-ADR-0008 reality —
  the client is the open cloud-connection package, wired explicitly
  (snippet included); installed apps run cloud-independent. New
  'Installing from the CLI' section (catalog + air-gapped modes).
- packages.mdx: Installing table gains the two CLI rows; note that
  install commands take the stable manifest id, never pkg_ row ids.
- reference/cli.mdx: document os package install.
- deploy/air-gapped.mdx: inline-install section for running instances.

English masters only; locale variants follow the translation pipeline.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

content/docs/build/marketplace.mdx

@@ -11,10 +11,38 @@ fastest way to put real software in front of users on day one.
 
 ## How it works
 
-Every ObjectOS runtime ships with the `MarketplaceProxy` and
-`MarketplaceInstallLocal` plugins enabled by default. When you open
-Console (`/_console/`), the marketplace tab queries the configured app
-catalog and shows installable apps.
+The marketplace client is the open-source `@objectstack/cloud-connection`
+package. Cloud-managed environments and the self-hosted ObjectOS image
+ship it wired up out of the box; a stack you assemble yourself enables
+it with a few lines of config:
+
+```ts
+import {
+  MarketplaceProxyPlugin,
+  MarketplaceInstallLocalPlugin,
+  RuntimeConfigPlugin,
+  resolveCloudUrl,
+} from '@objectstack/cloud-connection';
+
+const catalogUrl = resolveCloudUrl(); // OS_CLOUD_URL; 'off' disables
+
+plugins: [
+  ...(catalogUrl ? [
+    new MarketplaceProxyPlugin({ controlPlaneUrl: catalogUrl }),
+    new MarketplaceInstallLocalPlugin({ controlPlaneUrl: catalogUrl }),
+  ] : []),
+  new RuntimeConfigPlugin({ controlPlaneUrl: '', singleEnvironment: true, installLocal: true }),
+]
+```
+
+The browse/install *mechanism* is open; the catalog *service* (org
+catalogs, review, paid distribution) is provided by whichever control
+plane `OS_CLOUD_URL` points at. Once an app is installed it lives in
+your runtime's own kernel — nothing at runtime depends on the catalog
+staying reachable.
+
+When you open Console (`/_console/`), the marketplace tab queries the
+configured app catalog and shows installable apps.
 
 ```text
 You ─→ Console ─→ Marketplace tab ─→ pick app ─→ Install
@@ -101,6 +129,24 @@ runtime tracks installed version + available updates per app. Users see
 an "Update available" badge in Console when a new version is published
 to a catalog they're tracking.
 
+## Installing from the CLI
+
+Console is the primary install surface, but the same install-local
+endpoint is scriptable for CI and air-gapped operations:
+
+```bash
+# Catalog mode — the runtime resolves the package from its configured catalog
+os package install com.acme.crm --runtime http://localhost:3000 \
+  --email admin@example.com --password …
+
+# Air-gapped mode — send a compiled artifact inline, no catalog round-trip
+os package install ./dist/objectstack.json --runtime http://localhost:3000 \
+  --email admin@example.com --password …
+```
+
+The credentials are an account on the **target runtime** (not your
+cloud login) — the same authorization Console install uses.
+
 ## Permissions
 
 Installing apps requires the `manage_marketplace` system permission —

content/docs/build/packages.mdx

@@ -120,8 +120,13 @@ environment login. You never need to know an environment id to install.
 | Path | How |
 |---|---|
 | Console (recommended) | Sign in to the environment → **Marketplace** → pick the package → **Install**. Installs into the current environment. |
-| REST | `POST /api/v1/marketplace/install-local` (body: `{ packageId, versionId? }`) |
-| Air-gapped | Mount the compiled `dist/objectstack.json` artifact (see [Air-gapped](/docs/deploy/air-gapped)) |
+| CLI → running runtime | `os package install com.acme.crm --runtime <url>` — the runtime resolves the package from its configured catalog and merges it into its own kernel |
+| CLI air-gapped | `os package install ./dist/objectstack.json --runtime <url>` — compiled artifact sent inline, no catalog round-trip |
+| REST | `POST /api/v1/marketplace/install-local` (body: `{ packageId, versionId? }` or `{ manifest }`) |
+| Air-gapped (boot-time) | Mount the compiled `dist/objectstack.json` artifact (see [Air-gapped](/docs/deploy/air-gapped)) |
+
+Package ids in install commands are the stable manifest id
+(`com.acme.crm`) — you never need the internal `pkg_…` row id.
 
 > **CI shortcut.** Pipelines that deploy to a *known* environment can publish
 > and install in one step: `os package publish --env <id> --install

content/docs/deploy/air-gapped.mdx

@@ -56,6 +56,20 @@ If the customer uses OIDC/SSO, the identity provider must be reachable
 from the air-gapped network. If not, use local email/password auth or an
 identity provider hosted inside the same network.
 
+## Installing additional packages
+
+A running air-gapped instance can take additional packages without any
+catalog connectivity — hand the compiled artifact to the install CLI
+and it is sent inline and merged into the live kernel (no restart):
+
+```bash
+os package install ./dist/objectstack.json --runtime https://os.internal.example \
+  --email admin@example.com --password …
+```
+
+The manifest is cached on the runtime host under
+`.objectstack/installed-packages/` and re-registers on every boot.
+
 ## Upgrade process
 
 Treat artifacts as immutable:

content/docs/reference/cli.mdx

@@ -160,6 +160,10 @@ os cloud login | logout | whoami
 
 ```bash
 os package publish            # publish artifact as a versioned package
+os package install <id|file>  # install into a RUNNING runtime: catalog id
+                              # (com.acme.crm) or a compiled artifact JSON
+                              # (air-gapped, inline). --runtime / --email /
+                              # --password identify the runtime to install into
 os publish                    # publish to ObjectStack Cloud
 os rollback <revision>        # activate a previous artifact revision
 ```