@@ -0,0 +1,10 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): the platform skill says how `os deploy` exits 1 on a self-hosted runtime target
+
+Clause-②: no
+Metadata-protocol: none
+
+`objectstack-platform`'s operations reference scopes its `os deploy` exit-1 paragraph to ObjectOS Cloud and adds one for a target `os environments use-runtime` remembered: it asks for no cloud login, and it exits 1 on a failed build, a dry run the runtime refuses, cannot serve or ignores (an older runtime installed anyway), an install refusal (rerun with the `--confirm-access-upgrade` or `--confirm-upgrade` token it printed), or a package the running kernel did not load (live after a restart). The `os deploy` row's use-runtime tail moves into that paragraph, and a pitfalls row that only pointed to the data skill's permission-set assignment is cut. The CLI behaviour already shipped; this release only teaches it.
@@ -96,7 +96,7 @@ Per client:
 
 | Client | How to connect |
 |---|---|
-| **Claude Code** | `claude mcp add --transport http objectstack https://<your-deployment>/api/v1/mcp` — a browser login opens on first use. Headless alternative: add `--header "x-api-key: osk_..."`. |
+| **Claude Code** | [`os mcp connect`](/docs/deployment/cli#os-mcp-connect) registers your ObjectOS Cloud environment; `os mcp connect --url <base>` registers a self-hosted or local server as `objectstack`. Without the CLI: `claude mcp add --transport http objectstack https://<your-deployment>/api/v1/mcp`. Either way a browser login opens on first use. Headless alternative: add `--header "x-api-key: osk_..."` to the `claude mcp add` line (`os mcp connect` stores no token). |
 | **Claude Desktop** | Settings → Connectors → *Add custom connector* → paste the MCP URL → sign in when prompted. Connects from Anthropic's servers — needs public HTTPS (see below). |
 | **claude.ai (web)** | Settings → Connectors → *Add custom connector* → paste the MCP URL. Connects from Anthropic's servers — needs public HTTPS (see below). |
 | **Other MCP clients** | Any client implementing MCP authorization discovers the flow automatically; header-based clients can send the API key instead. |
 
@@ -167,9 +167,11 @@ Starts development mode. Three usage shapes:
 3. **Monorepo root** (cwd has `pnpm-workspace.yaml`) — orchestrates `pnpm -r dev` across packages.
 
 Once the local server is up, `os dev` in an interactive terminal offers
-**`d` to deploy**: it runs [`os deploy`](#os-deploy) in the same terminal, and
-when you are not logged in to ObjectOS Cloud the same key runs `os cloud login`
-first. Saving a file never deploys.
+**`d` to deploy**: it runs [`os deploy`](#os-deploy) in the same terminal. When
+the target is ObjectOS Cloud and you are not logged in, the same key runs
+`os cloud login` first. When the target is a runtime
+[`os environments use-runtime`](#deploy-to-a-self-hosted-runtime) remembered, the
+key deploys there and asks for no cloud login. Saving a file never deploys.
 
 ```bash
 os dev                     # Auto-compile cwd config, then start
 
@@ -474,14 +474,23 @@ browser login (you connect as yourself, no admin-minted credentials):
 
 ```bash
 # the dev server you just booted in step 5
-claude mcp add --transport http support-desk http://localhost:3000/api/v1/mcp
+npx os mcp connect --url http://localhost:3000
 
-# or a deployed instance
-claude mcp add --transport http support-desk https://your-deployment.example.com/api/v1/mcp
+# or a deployed instance: your ObjectOS Cloud environment, or a self-hosted server
+npx os mcp connect
+npx os mcp connect --url https://your-deployment.example.com
 
 # first tool use opens a browser login — you're connected as yourself
 ```
 
+[`os mcp connect`](/docs/deployment/cli#os-mcp-connect) runs the `claude mcp add`
+line for you and stores no token. Without the CLI, type the line yourself:
+
+```bash
+claude mcp add --transport http support-desk http://localhost:3000/api/v1/mcp
+claude mcp add --transport http support-desk https://your-deployment.example.com/api/v1/mcp
+```
+
 Or install the [official plugin](https://github.com/objectstack-ai/claude-plugin) —
 it bundles the portable ObjectStack agent skill and a guided `/objectstack:connect`
 command (one plugin serves every deployment; the URL is the only input):
 
@@ -1130,7 +1130,21 @@ export const CEILINGS = new Map([
   // measured, raises the row, pinned at the measurement. Same maintainer
   // ruling, verbatim and untranslated: 「A:先削重复,余额按实测提高」 (ruling
   // record 6513306068 on #27847).
-  ['skills/objectstack-platform/references/operations.md', 3340],
+  // 3340 -> 3375: the `os deploy` exit-1 paragraph is scoped to the cloud and
+  // a `use-runtime` target's own paragraph follows: no cloud login, and its
+  // exit 1 (a failed build; a dry run refused, unserved or ignored; an install
+  // refusal with `--confirm-access-upgrade` / `--confirm-upgrade`; installed
+  // but not loaded). Paid first by deleting restatement in the same file
+  // (-262 bytes): the `os deploy` row's use-runtime tail (home: the new
+  // paragraph, which carries each of its facts) and the Common ops pitfalls
+  // row on a declared permission set that grants nobody anything (home:
+  // objectstack-data rules/security.md § Assigning a permission set to a
+  // user). 13360 -> 13500 bytes (+140 net: -262 cut, +402 added)
+  // -> ceil(13500 / 4) = 3375; headroom was 0, so
+  // the remainder, +35 measured, raises the row, pinned at the measurement.
+  // Same maintainer ruling, verbatim and untranslated:
+  // 「A:先削重复,余额按实测提高」 (ruling record 6513306068 on #27847).
+  ['skills/objectstack-platform/references/operations.md', 3375],
   ['skills/objectstack-platform/references/plugin-development.md', 3137],
   ['skills/objectstack-upgrade/references/examples-upgrade.md', 1197],
 
 
@@ -92,12 +92,14 @@ Port resolution is the same for `os dev` and `os start` (both spawn `os serve`):
 | `os environments list` / `create` / `switch` | Manage cloud environments (prod/staging/dev) |
 | `os environments use-runtime <url> --token <key>` | Deploy to a self-hosted runtime instead: the key (one it issued) is tried first (`--no-verify` skips), then kept in `~/.objectstack/cloud.json` (0600) across cloud login/logout. `--forget` or `os environments switch` targets the cloud again |
 | `os cloud login` / `logout` / `whoami` | Cloud auth subcommands (these three only — there are no `os cloud logs/metrics/status`) |
-| `os deploy` (or `npm run deploy`, or `d` in `os dev`) | See an edit on your org's ObjectOS Cloud environment: build, publish `<manifest.version>-dev.<timestamp>`, install, wait until served. Environment: `--env <id>`, else the one `os environments switch` recorded (kept across `os cloud login`), else your organization's only one. `--no-wait`; `--wait-timeout <seconds>` (600). A `use-runtime` target, no `--env`: build, dry-run plan, install, live on `hotLoaded`; `--confirm-access-upgrade <token>` |
+| `os deploy` (or `npm run deploy`, or `d` in `os dev`) | See an edit on your org's ObjectOS Cloud environment: build, publish `<manifest.version>-dev.<timestamp>`, install, wait until served. Environment: `--env <id>`, else the one `os environments switch` recorded (kept across `os cloud login`), else your organization's only one. `--no-wait`; `--wait-timeout <seconds>` (600). A `use-runtime` target: below |
 | `os package publish [dist/objectstack.json] [--env … --install --visibility org]` | Upload the compiled artifact as a versioned package to the cloud catalog (ADR-0008 P3). Listing file, README, review and every screen the customer's administrator meets: [Marketplace handbook](https://objectstack.ai/docs/deployment/marketplace-handbook) |
 | `os package install <manifest-id │ ./dist/objectstack.json> [--version │ -u/--url]` | Install a package into a **running** runtime. Catalog mode (by manifest id) or air-gapped local-artifact mode. Auths as a **target runtime** user (`-t/--token` or `--email/--password`; env `OS_RUNTIME_TOKEN` or `OS_RUNTIME_EMAIL`/`OS_RUNTIME_PASSWORD`), not the cloud login. No `-u`: the `use-runtime` runtime and, with no `-t`/`--email`, its key; else `http://localhost:3000` |
 | `os mcp connect` | Register the cloud environment's MCP server (picked as `os deploy` picks it) with Claude Code (`claude mcp add`); `--url <base>` for a self-hosted or local server (named `objectstack`); `--name`; `--print` runs nothing (other clients). Stores no token: the client runs the server's own OAuth |
 
-**`os deploy` exit 1:** a refusal before any write publishes nothing: log in (`os cloud login`), pick an environment (`--env`; none: create one in the ObjectOS Cloud console), or fix the local build or `manifest.version`. `could not build …: <reason>`: the environment's build failed, it keeps serving the previous one; fix and deploy again. `Timed out after …`: the install is recorded and a failing build reads as pending for minutes; deploy again with a longer `--wait-timeout`, or see the build in the ObjectOS Cloud console.
+**`os deploy` exit 1, cloud:** a refusal before any write publishes nothing: log in (`os cloud login`), pick an environment (`--env`; none: create one in the ObjectOS Cloud console), or fix the local build or `manifest.version`. `could not build …: <reason>`: the environment's build failed, it keeps serving the previous one; fix and deploy again. `Timed out after …`: the install is recorded and a failing build reads as pending for minutes; deploy again with a longer `--wait-timeout`, or see the build in the ObjectOS Cloud console.
+
+**A `use-runtime` target** (no `--env`) asks for no cloud login: build, dry-run plan, install, live on `hotLoaded`. Exit 1: a failed build; a dry run refused, unserved (no install-local) or ignored (an older runtime installed: upgrade it); an install refusal (rerun with the `--confirm-access-upgrade` / `--confirm-upgrade <token>` it printed); installed but not loaded (live after a restart).
 
 > **Cloud connection & marketplace (`@objectstack/cloud-connection`, ADR-0008/0009):**
 > the open runtime-side cloud client; its `MarketplaceInstallLocalPlugin` serves the
@@ -175,5 +177,4 @@ the other imports: [Using Plugins](./plugin-development.md#using-plugins).
 | LiteKernel test passes, ObjectKernel boot fails | Test missed a plugin the CLI auto-registers — compare your test's `use()` list against the `os dev` boot log |
 | Hot reload misses new objects | Barrel `src/objects/index.ts` not re-exporting — check the file |
 | Login works but **Setup / Studio missing** | The logged-in user isn't a platform admin. Setup/Studio are gated by `setup.access` / `studio.access` on `admin_full_access`, auto-granted only to the first registered **human** (`bootstrapPlatformAdmin`). The `usr_system` seed identity is skipped, so it can't steal the grant. Either sign up first (`--seed-admin`/`--fresh` does this) or check `sys_user_permission_set` for a cross-tenant (`organization_id = NULL`) `admin_full_access` link on your user. Don't edit nav code first. |
-| A permission set is declared but grants nobody anything | Declaring a set is not assigning it — see "Assigning a permission set to a user" in **objectstack-data**. |
 | The official image exits at start naming `OS_DATABASE_URL` / `OS_AUTH_SECRET` / `OS_SECRET_KEY` | The image presets `OS_DEPLOYMENT_DURABILITY_CHECK_ENABLED=true`: with any of the three unset, `os start` exits 1 before it writes a database file or a secret. Set the named ones on the run command. Upgrading a container that ran on the image's defaults? **Keep its generated values**, read from the old container's `/home/node/.objectstack` (`docker exec <container> cat <file>`, or its volume): `OS_AUTH_SECRET` is the contents of `auth-secret`, `OS_SECRET_KEY` the contents of `dev-crypto-key`, and the data is `data/objectstack.db` (`OS_DATABASE_URL=file:…` on the kept volume, or migrate it). Fresh values leave every saved credential unreadable and sign everyone out. |