[objectstack-fleet]

Requested by Irene · project thread

Fixes #31235

Clause-②: no
Metadata-protocol: none

dispatch-gates --tier reads a contract-review model mandate for skills/** (clause ①). That mandate is waived by the maintainer's standing order in this project (2026-11-03). This card ran on the project's default model, and the dispatching seat (domain:skills#3) runs the contract review.

维护者速读

• 改了什么：三个文档页与平台技能跟上 PR docs(skills): teach os environments use-runtime and os mcp connect #31225 已发布的 CLI。ai/agents.mdx 的 Claude Code 行和 build-with-claude-code.mdx 的连接步骤先教 os mcp connect（自托管或本地用 --url <base>），手敲的 claude mcp add 留作没有 CLI 时的备选，无头 --header 写法不变；deployment/cli.mdx § os dev 说明 d 键只在云目标下先跑 os cloud login，use-runtime 目标直接部署到该运行时、不要云登录；operations.md 的 os deploy 退出码 1 段限定为云路径，新增一段写 use-runtime 目标的退出码 1 情形。
• 为什么改：这几处仍只教旧路径，照着做的作者会手敲 CLI 已经替他执行的命令，还会以为自托管部署需要云登录（Docs and skill still type the MCP connect line by hand and describe os deploy as cloud-only #31235，来自 docs(skills): teach os environments use-runtime and os mcp connect #31225 契约复核第 9 项与 N8）。
• 风险与回滚：纯文档与技能文字，不动代码；operations.md 先删同文件重复内容（-262 字节），余额 +35 tokens 按常设裁定 6513306068 抬高该行棘轮（3340 → 3375）；发版 @objectstack/skills patch；回滚即 revert。
• 先看：skills/objectstack-platform/references/operations.md L95–L102；然后 content/docs/deployment/cli.mdx L169–L174。
• 两分钟验证：node scripts/check-skills-token-ratchet.mjs（3375 / 3375）；对照 packages/cli/src/commands/deploy.ts L301–L355 读新段的每个退出情形；packages/cli/src/utils/dev-deploy-key.ts L26–L30 读 d 键不要云登录。
• 需要你做的：check-governed-merges 判为 Tier H（skills/**），需 os-zhuang 或 hotlong 批准；当前 head 尚无席位契约复核 PASS，契约复核待做，请先不要批。

What changes

The four sites, before and after

Site	Before	After
content/docs/ai/agents.mdx L99, Claude Code row	only the typed claude mcp add --transport http objectstack https://<your-deployment>/api/v1/mcp, with the headless --header alternative	names os mcp connect first (your ObjectOS Cloud environment) and os mcp connect --url <base> (a self-hosted or local server, registered as objectstack); the typed line stays as the fallback "Without the CLI"; the headless --header alternative stays, attached to the typed line, with the reason (os mcp connect stores no token)
content/docs/getting-started/build-with-claude-code.mdx L477, L480	two typed claude mcp add … support-desk … lines (local, deployed)	npx os mcp connect --url http://localhost:3000 (the step-5 dev server), npx os mcp connect and npx os mcp connect --url https://your-deployment.example.com (a deployed instance); one sentence links os mcp connect and says it stores no token; the two typed lines follow as the fallback, byte-identical. L502 (now L511, the headless --header form) is unchanged
content/docs/deployment/cli.mdx § os dev L169-L172	"when you are not logged in to ObjectOS Cloud the same key runs os cloud login first"	the cloud login is for a cloud target; with a runtime os environments use-runtime remembered, the key deploys there and asks for no cloud login
skills/objectstack-platform/references/operations.md L100	one os deploy exit-1 paragraph, all cloud-path refusals	that paragraph is scoped "exit 1, cloud", and a new paragraph gives the use-runtime target's path and exit-1 cases (below)

npx os matches the page's own step 5 (npx os dev --ui, L361). No --name support-desk: no later step on the page uses the server's name (the only other support-desk server line is the headless alternative at L511, a separate registration), so the CLI's own names stand.

The new operations.md paragraph, and where each case comes from

-**`os deploy` exit 1:** a refusal before any write publishes nothing: …
+**`os deploy` exit 1, cloud:** a refusal before any write publishes nothing: …
+
+**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).

Case	cli.mdx § To a self-hosted runtime	Source on main
no --env, no cloud login	L3253-L3255, L3274-L3275	deploy.ts L162-L166 (flags.env ? undefined : activeRuntimeTarget()); dev-deploy-key.ts L26-L30
failed build	step 1	deploy.ts L310-L314
dry run refused or unserved	step 2	deploy.ts L329-L334
dry run ignored by an older runtime, which installed	step 2	package/install.ts L545-L561 (does not support a dry run: it ignored --dry-run and INSTALLED); then deploy.ts L330-L334 exits 1
install refusal, --confirm-access-upgrade / --confirm-upgrade	step 3 (names only --confirm-access-upgrade)	deploy.ts L140-L155 (both flags), L337-L344
installed but not loaded	not listed	deploy.ts L346-L352 ("it loads when the runtime restarts")

Token readings (scripts/check-skills-token-ratchet.mjs, tokens = ceil(bytes / 4))

File	main 604a2b3	This PR	Ceiling
skills/objectstack-platform/references/operations.md	13360 B = 3340	13500 B = 3375	3340 → 3375

The order read 3285 / 3287; the seat re-measured 3340 / 3340 on main (PR #31225 raised the row) and that reading stands.

Deletions, each with its surviving home (-262 bytes):

1. The os deploy row's tail "A use-runtime target, no --env: build, dry-run plan, install, live on hotLoaded; --confirm-access-upgrade <token>" becomes "A use-runtime target: below" (-92 B). Facts it held: the use-runtime target applies with no --env; the sequence build, dry-run plan, install, live on hotLoaded; --confirm-access-upgrade <token>. Home: the new paragraph two lines down, which carries every one of them.
2. The Common ops pitfalls row "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." (-170 B). Facts it held: the symptom, declaring is not assigning, the pointer. Home: skills/objectstack-data/rules/security.md § Assigning a permission set to a user (L35-L37: "Declaring a set grants nobody anything — an assignment is data"). No script, test or platform eval pins it.

Added: +402 B (the ", cloud" scope and the new paragraph). Net +140 B → 3375 tokens, remainder +35 over the 0-headroom ceiling. Only that row moves, pinned at the measurement, under the standing ruling quoted in the script beside it: maintainer ruling 2026-10-27, verbatim and untranslated, 「A:先削重复,余额按实测提高」 (ruling record 6513306068 on #27847). The seat ruled on these cuts and the +35 before the script was touched. No rewrap: every untouched line is byte-identical to main.

Eval cases

skills/objectstack-platform/evals/config-plugins-ops.json swept for "hand-typed only" and "deploy needs a cloud login": none touched.

• Case 17 asks how to see an edit "on my ObjectOS Cloud environment"; its "log in with os cloud login" is right for that cloud-only prompt.
• Case 21 (use-runtime) and case 22 (os mcp connect) already teach the new paths; their must_not_contain (os deploy --url, --client cursor) do not contradict their expected_output.

Other sites found (not edited)

• content/docs/deployment/cli.mdx § os deploy flag table (≈L3240-L3246) lists --confirm-access-upgrade but not --confirm-upgrade (deploy.ts L149-L155, added by feat(cloud-connection)!: refuse a managed upgrade that renames or retypes a stored field until it is declared or confirmed #31243); § To a self-hosted runtime step 3 (L3267) names only --confirm-access-upgrade, and step 4 (L3270) omits the not-loaded exit 1 (deploy.ts L346-L352).
• skills/objectstack-platform/evals/config-plugins-ops.json case 21 expected_output names only --confirm-access-upgrade. Not an old-claim case; left alone.
• content/docs/ai/connect-mcp.mdx L45, L48, L68: typed claude mcp add lines, already under "Or type the line yourself" after os mcp connect (L27-L38). Already the order's shape.
• content/docs/ai/agents.mdx L108 (private-deployment callout): "Claude Code (claude mcp add, or the plugin) dials the endpoint from your own machine". Still true, since os mcp connect runs that line.
• No other "deploy needs os cloud login" claim in content/docs/** or skills/**. cli.mdx L3216 (os cloud login # once per machine) is the cloud example in § os deploy, correct for that path.
• Left alone by order: content/docs/releases/v16.mdx L76, L468; blog posts; CHANGELOGs.

Changeset

.changeset/31235-platform-skill-use-runtime-deploy-exit.md: '@objectstack/skills': patch, with Clause-②: no and Metadata-protocol: none.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 88 commands against merge base 604a2b3b9. All 88 ran on head a082087b after a full pnpm build (exit 0), under NODE_OPTIONS=--max-old-space-size=8192: 88 × exit 0, 0 NOT MEASURED among the listed commands. The CI-only families dispatch-gates names as not locally measurable (shard attestation, Build Core / Build Docs steps, type-check lanes) are left to CI.

The order's named checks are all in that list and exit 0: pnpm --filter @objectstack/spec run check:skill-examples, pnpm check:skill-identifier-liveness, pnpm --filter @objectstack/spec run check:skill-refs, pnpm check:doc-authoring, node scripts/check-skills-token-ratchet.mjs (operations.md 3375 / 3375). Also node scripts/check-commit-card-trailers.mjs --range origin/main..HEAD exit 0 and node scripts/pm/check-governed-merges.mjs --branch HEAD exit 0 (Tier H). Per-command record: project file card-31235/gates-a082087b.txt.

🤖 Generated with Claude Code

https://claude.ai/code/session_01J8VVAntMdbEQxYFD6N2ePk

[objectstack-fleet]

domain:skills#3 · huangyiirene · session_01J8VVAj7CvjkGXvgXzd6RZ7

Contract-review-claim: session_01J8VVAj7CvjkGXvgXzd6RZ7 · head a082087 · 2026-11-08T02:38Z

Full contract review of PR #31335 (#31235, claim 6716023699). The seat review runs at CONTRACT_REVIEW_TIER in an isolated subagent.

[objectstack-fleet]

domain:skills#3 · huangyiirene · session_01J8VVAj7CvjkGXvgXzd6RZ7

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: a082087b6e2506d5d7047e3c3e2ed45859bea029
Local-runs: none
Scope: skills/objectstack-platform/references/operations.md + scripts/check-skills-token-ratchet.mjs, content/docs/ai/agents.mdx, content/docs/deployment/cli.mdx, content/docs/getting-started/build-with-claude-code.mdx, .changeset/31235-platform-skill-use-runtime-deploy-exit.md, packages/cli/src/commands/deploy.ts, packages/cli/src/commands/package/install.ts, packages/cli/src/commands/mcp/connect.ts, packages/cli/src/utils/dev-deploy-key.ts, packages/cli/package.json, packages/mcp/src/skill-md.ts, skills/objectstack-data/rules/security.md, skills/objectstack-data/SKILL.md, skills/objectstack-platform/evals/config-plugins-ops.json

Inputs read: card #31235 body, triage 6712265901 and claim 6716023699; PR #31335 body and its six-file list; the net diff against merge base 604a2b3b9. origin/main (now f5e23e2f7) has not touched any changed or cited file since that base, so every line number below holds on both. Ruling 6513306068 (on #27847) was read at its source.

Check-runs on this head, read 2026-11-08T02:40Z: 38 in all. 10 success (Check Changeset, Check Documentation Links, Governed Surface Queue Guard, PR-body guards, Check PR Size, Spec property liveness, Dogfood Regression Gate, Test UI, filter, Auto Label), 12 skipped (UI-only and opt-in lanes), 16 in progress (Build Core, Build Docs, every Lint lane including docs and code guards and PM dispatch-gates, every Type Check lane, Plan Test Core shards, Live E2E UI). None failed. This verdict judges the contract. The in-progress gates give their own verdicts at merge.

The face is set by the committed tree. operations.md is a governed path, so the record is at CONTRACT_REVIEW_TIER and carries Scope and ④. I widened the scope to the whole diff. No part of it is left to the lane seat.

① Derived judgments

The diff adds nothing to any accept set and changes no public surface. No schema, export, flag or command changes. It is teaching text, a changeset and one ratchet row. Each claim, checked against main:

1. os mcp connect and --url: right. The command is packages/cli/src/commands/mcp/connect.ts. The CLI bin is os (packages/cli/package.json L23-26), so npx os mcp connect resolves in a scaffolded project, as npx os dev --ui already does in step 5 (build-with-claude-code.mdx L361). --url is declared at L140-142, and a --url server takes the name OBJECTSTACK_MCP_SERVER_NAME (L190), which is 'objectstack' (packages/mcp/src/skill-md.ts L51). Without --url, the command needs a cloud credential (L193-197) and picks the environment (L235), so "registers your ObjectOS Cloud environment" is right.
2. "Stores no token", and where --header goes: right. connect.ts L25-30 says the command stores no MCP token and writes none into a client config. claudeMcpAddArgs (L62-65) builds mcp add --transport http NAME URL with no header. So the headless x-api-key header can only ride on a hand-typed claude mcp add line. agents.mdx now ties it to that line and says why. build-with-claude-code.mdx L511-512 is unchanged, as the card asked.
3. The d key on a use-runtime target asks for no cloud login: right. dev-deploy-key.ts L26-31 says so, L118 skips runLogin when a runtime target is set, and L188 wires activeRuntimeTarget. The new cli.mdx sentence matches the existing § To a self-hosted runtime, L3272-3273. Both anchors exist: #deploy-to-a-self-hosted-runtime at L3160 and os mcp connect at L3277. Check Documentation Links passed.
4. Every use-runtime exit 1 in operations.md: right, all in deploy.ts:
   • The runtime path runs only with no --env (L164). It never resolves a cloud credential (L301-355).
   • A failed build (L310-314).
   • A dry run refused or not served (L329-334, through package/install.ts).
   • A dry run an older runtime ignores, which then installs (install.ts L545-555, which says to upgrade the runtime).
   • An install refusal. The embedded install's retry is os deploy (deploy.ts L321, install.ts L323), and it prints os deploy --confirm-access-upgrade FINDINGSET (L468) or os deploy --confirm-upgrade FINDINGSET (L489). Both flags exist on os deploy (L140-155) and pass through (L337-340).
   • Installed but not loaded (L346-352: "it loads when the runtime restarts").
     The paragraph is more complete than cli.mdx itself, which leaves out --confirm-upgrade and the not-loaded exit. It does not contradict that page.
5. The cloud paragraph: right. It is unchanged apart from the ", cloud" scope label.
6. Cut 1, the os deploy row's use-runtime tail (-92 B): nothing lost. The tail said: no --env; build, dry-run plan, install, live on hotLoaded; --confirm-access-upgrade TOKEN. The new paragraph two lines down states every one of these, plus --confirm-upgrade. The row now points to it with "A use-runtime target: below".
7. Cut 2, the permission-set pitfall row (-170 B): nothing lost. The row only pointed elsewhere. Its fact lives in skills/objectstack-data/rules/security.md § Assigning a permission set to a user (L35-37: "Declaring a set grants nobody anything — an assignment is data"). A reader gets there through the data skill: its description lists security and permission, and its SKILL.md L48 links that rules file for "permission sets, assignment rows". The platform skill keeps its own permission-set teaching (SKILL.md L123, L127, L383-386).
8. Platform evals: none relies on the cut text. The skill has one eval file, config-plugins-ops.json. No case mentions "grants nobody" or declaring versus assigning a permission set. Case 7 asks for demoStaff plus permissionSets, which SKILL.md still teaches. Case 17 is cloud-only, and the cloud paragraph still answers it. Case 21's expected output (dry-run plan, inline install, hotLoaded, --confirm-access-upgrade TOKEN, no --env) is fully in the new paragraph and the unchanged use-runtime row. Case 22 is about os mcp connect, and the row at L100 is unchanged. The PR changes no eval, which is correct.
9. Ratchet: right. git show | wc -c reads operations.md at 13360 B on main and 13500 B on this head. That is ceil/4 = 3340 and 3375, matching the script's ceil(utf8 bytes / 4). Line by line: the row is -92 and the pitfall -170, for -262. Added: ", cloud" +7, the new paragraph +394, its blank line +1, for +402. Net +140 B, +35 tokens over a row that had 0 headroom, pinned at the measurement. Only that one CEILINGS row moves. The comment quotes 「A:先削重复,余额按实测提高」 verbatim and names record 6513306068 on [Decision] skills token ratchet: price evals/** out (they never enter a customer context), and make the standing 「先削重复,余额按实测提高」 ruling the gate-recognised path for teaching text — or keep the per-raise ruling round #27847, which is the recognised path that ruling sets out (part 2): same-file deletion shown and the ruling quoted. The PR body carries the ruling id and the measured delta.

② Semver level

'@objectstack/skills': patch matches what the diff publishes. packages/skills/package.json ships the skills tree, and only teaching text in one reference file changes. No API, flag or schema moves. The three content/docs/** pages publish no package. The changeset and the PR body both carry Clause-②: no and Metadata-protocol: none. Both are right: no published contract widens or narrows, and no metadata protocol is involved. The claim 6716023699 carries the same two lines. The PR body says Fixes #31235. Check Changeset passed.

③ Boundary flags

• The card's four sites: all addressed. Site 2's headless line (L511) and the historical pages are left alone, as the card says. Every edit stays inside the claim's file surface. The ratchet row moves only under ruling 6513306068 and only for the measured remainder, as the claim set out.
• Seat rulings the claim waits on (the cuts and the +35): the PR body says the seat ruled before the script was touched. Whether or not that ruling is on the record, this review rules on the merits: both cuts and the +35 are sound (items 6, 7 and 9).
• Model-mandate waiver: the PR body cites the maintainer's standing order of 2026-11-03, the same one the claim cites. That is outside a contract verdict. It is not escalated here.
• "Other sites found (not edited)" in the PR body: these are real and outside this card. On main, cli.mdx § os deploy's flag table (L3237-3244) has no --confirm-upgrade row, step 3 (L3265-3267) names only --confirm-access-upgrade, and step 4 (L3268-3270) leaves out the not-loaded exit 1. Escalated: they need their own docs card, because no card holds them yet. The rest (connect-mcp.mdx and agents.mdx L108) are true as written.
• Found in review, outside this card: an embedded install's unique-scope refusal prints os deploy --confirm-global-uniques (install.ts L453, retry = os deploy). os deploy declares no such flag (deploy.ts L109-155), so the printed retry cannot run on a use-runtime target. This is a CLI gap that predates this PR. The new paragraph's install-refusal clause names only the two token flags os deploy takes, so it teaches nothing false. Escalated as a separate CLI card.
• Dev open_questions: none raised. No dev flag is left open.

④ Design judgment

operations.md, held against the card's site 3 and the spec it teaches on main. The fix keeps the paragraph short, as an agent-facing reference should be. The cloud paragraph is labelled as such and left word for word, so eval case 17 still holds. The use-runtime paragraph teaches the order and the exits from the code, not from cli.mdx, so it adds the two cases that page lacks without going beyond deploy.ts. Every refusal names its fix: upgrade the runtime, rerun with the printed token, or restart. The os deploy row pointing "below" and the cross-skill cut both follow the ruling's "cut duplication first" rule. Neither leaves a fact without a home that the skill router reaches. Nothing in the change is untrue against main, and nothing true is lost.

No must-fix. Should-fix, neither on this PR: open a docs card for the cli.mdx § os deploy gaps, and a CLI card for --confirm-global-uniques on os deploy.

Implemented-by: claude/project-thread-g0jint
Reviewed-by: session_01J8VVAj7CvjkGXvgXzd6RZ7

VERDICT: PASS

[objectstack-fleet]

domain:skills#3 · huangyiirene · session_01J8VVAj7CvjkGXvgXzd6RZ7

维护者速读

• 改了什么: 三个文档页把 os mcp connect(自托管或本地用 --url)放在手敲 claude mcp add 之前，手敲行留作后备，无头 --header 行保留;cli.mdx 的 os dev 一节写明 d 键只在云目标时才先 os cloud login;平台技能 operations.md 的 os deploy 退出码段限定为云路径，并新增 use-runtime 目标的退出码段。6 个文件,+47/−11。
• 为什么改: Docs and skill still type the MCP connect line by hand and describe os deploy as cloud-only #31235。PR docs(skills): teach os environments use-runtime and os mcp connect #31225 已上线这两条路径，这四处仍只教旧路径，还会让自托管部署的作者以为必须先登录云。
• 风险与回滚: 只改文字;operations.md 删两处重复后仍余 +35 token,按常规裁决 6513306068 只把该行上限 3340→3375,其余行不动。可整 PR revert。
• 先看: skills/objectstack-platform/references/operations.md L100-L102;content/docs/ai/agents.mdx L99。
• 两分钟验证: 对照 packages/cli/src/commands/deploy.ts L140-L155、L301-L355 读新的 use-runtime 段;node scripts/check-skills-token-ratchet.mjs 全绿。
• 需要你做的: 批准。check-governed-merges 判为 GOVERNED Tier H(skills/**),需 os-zhuang 或 hotlong 批准;契约复审 PASS 6716322584,Head-sha a082087b。
• 席位意见: ACCEPT。

席位核对 — ACCEPT · domain:skills#3 · head a082087b6e2506d5d7047e3c3e2ed45859bea029

1. 形态: draft → main,Fixes #31235;changeset '@objectstack/skills': patch,Clause-②: no,Metadata-protocol: none;assignee huangyiirene(认领 Account:);6 个文件，均在认领面内(认领 6716023699)。模型豁免句不点模型名。
2. 前提实测: main 604a2b3b9 上 agents.mdx L99、build-with-claude-code.mdx L477/L480 只有手敲行;deployment/cli.mdx L169-L172 无 use-runtime 例外;operations.md L100 只列云路径退出码。
3. 门禁(钉 head a082087b): dispatch-gates 派生 88 条，连同指定的额外检查共 91 次运行，全部 exit 0(/mnt/project-files/card-31235/gates-a082087b.txt);token ratchet:operations.md 13500 B = 3375/3375;trailers exit 0;check-runs 47 条全部完成:35 success、12 skip、0 失败;check-governed-merges --pr 31335 exit 3:GOVERNED Tier H。复核：全量 6716322584 PASS,无 must-fix。
4. 接受的偏差: 令牌余量 +35 由本席在线程内按裁决 6513306068 放行(order 中 3285/3287 是本席的过期本地读数，主干实为 3340/3340)。两处删减：部署行的 use-runtime 尾句整句移入新段;权限集陷阱行的事实在 objectstack-data rules/security.md L35-L37,data SKILL.md L48 有链接，无平台 eval 依赖。build-with-claude-code.mdx 用 npx os mcp connect,与该页 npx os dev 一致，后续步骤不依赖服务器名，故不加 --name。
5. 范围外去向: 复核的两条 should-fix 各自立卡:cli: a use-runtime os deploy stopped on installation-wide uniques prints os deploy --confirm-global-uniques, a flag os deploy does not declare #31338(use-runtime 部署在全安装唯一约束处停下时打印 os deploy --confirm-global-uniques,而 os deploy 没有这个参数),docs: cli.mdx os deploy flag table and § To a self-hosted runtime omit --confirm-upgrade and the "installed but not loaded" exit #31339(cli.mdx 的部署参数表与「To a self-hosted runtime」一节缺 --confirm-upgrade 和「已安装未加载」退出码)。eval 21 只提 --confirm-access-upgrade,仍为真，并入 docs: cli.mdx os deploy flag table and § To a self-hosted runtime omit --confirm-upgrade and the "installed but not loaded" exit #31339。
6. 落地条款: Tier H。保持 draft;批准后由维护者翻 ready 入队，或按 landing-operations.md 由本席落地。