cli: fix two stale os … invocations, and declare the two deliberate ones in place

[os-trump]

Fixes#11465

Triage ruled option A on that card (fix the two stale invocations, docblock the two true negatives, no gate over the class), and this implements exactly that. Comment text only: 4 files, +19/-2, and every changed line is inside a comment — git diff -U0 against the recorded base, filtered to lines that are not * / // comment lines, returns nothing.

The id set was re-measured, not transcribed

The card's spellings were treated as leads. packages/cli and its 58-package dependency closure were built, then the ids were read from the built oclif Config (topicSeparator = " ", so canonical : ids convert to the user-typed form):

claim	measurement
environments switch is the live id	present; 0 registered ids contain project — no projects topic, no alias
package install is the live id	present; 0 registered ids contain packages
os publish / os rollback are retired	neither is a registered id; the only publish ids are package publish and plugin publish, and there is no rollback id at all
datasource is a topic, not a runnable id	present among topics, absent from commands; its three subcommands are datasource introspect / list-tables / validate

All four line offsets on the card also still hold at the base this branch was cut from (a11c1a57): api-client.ts:20, create.ts:39, publish.ts:16, response-envelope.ts:14.

The four sites

Fixed — genuinely stale:

1. src/utils/api-client.ts:20 — os projects switch → os environments switch. Confirmed accurate beyond the spelling: src/commands/environments/switch.ts:58 is what persists activeEnvironmentId into ~/.objectstack/credentials.json.
2. src/commands/environments/create.ts:39 — os packages install → os package install (a plural typo, never a rename).

Declared in place — the prose is correct and had to survive:

3. src/commands/package/publish.ts — the sentence is aboutos publish / os rollback being removed. The sentence is untouched; a note underneath states that these are retired ids named on purpose, gives the measurement that says so, and tells the next reader (and any future sweep author) that re-spelling them would make the sentence false while deleting it would drop accurate history.
4. src/utils/response-envelope.ts — a note states that datasource is a topic rather than a runnable id, names the three subcommands, and marks a sweep hit on os datasource as a false positive so nobody narrows the sentence to one subcommand.

The card's own sweep, re-run on this branch

Re-running the sweep the card describes (ids from the built Config; backticked and quoted os … spans in the non-test sources under src/**):

before: scanned files: 107 | invocations found: 536 | unresolved: 6 (the card, at filing)
after: scanned files: 109 | invocations found: 583 | unresolved: 5

Both genuinely stale invocations are gone. Every remaining unresolved hit is a retired-or-topic name inside the two files annotated above — the ones the notes exist to declare.

That measurement also caught something in the first draft of those notes: each had spelled a literal `os …` placeholder, which the sweep reads as one more invocation resolving to nothing. A note written to keep a future sweep honest should not inflate that sweep's numbers, so the second commit rewords both to describe the sweep without spelling a placeholder invocation (7 unresolved → 5). The retired ids they deliberately name are unchanged.

Verification, at 6fe142ce

• Targeted suite green: pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 over the 6 test files that read the touched modules — src/utils/response-envelope.test.ts, src/commands/environments/environments.test.ts, test/remote-api-utils.test.ts, test/package-publish-error-envelope.test.ts, test/package-publish-namespace.test.ts, test/commands.test.ts → Test Files 6 passed (6), Tests 127 passed (127); pnpm --filter @objectstack/cli typecheck (tsc --noEmit) green.
• Declared narrowing: the wholepackages/cli suite (178 test files, several booting real kernels) does not fit this container's ~10-minute foreground cap while the shared verify lock is contended — one attempt acquired the lock and was SIGTERMed mid-run at the cap. The narrowing is declared rather than silent; CI runs the full farm regardless.
• Anchored greps, both directions: os projects switch 1→0 and os environments switch 0→1 in api-client.ts; os packages install 1→0 and os package install 0→1 in create.ts; both original sentences still present at sites 3 and 4, each now with its note.
• Gate families re-derived from the actual change set with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (12 families) plus check:nul-bytes — all 13 green at this head, each exit code captured before any pipe.
• pnpm lint full-repo, not narrowed: eslint . --no-inline-config → exit 0, no findings.
• One local red on the way was diagnosed rather than absorbed: check:i18n-coverage reported its own COULD NOT MEASURE because three connectors the showcase config imports had no build output in this worktree. After building them it reads OK (12 config(s), 657 baselined untranslated string(s), none new). Same cause for a serve-capability-identity.test.ts failure seen mid-run, green once connector-mcp was built.
• The #10967 pin is not cited as evidence here: it reads static override examples via the TypeScript AST under src/commands/** only, so it cannot see any of these four sites.

Fence honoured

src/utils/response-envelope.ts also carries the blocked card #10938 (retiring the flat fail() accommodation in readErrorMessage). That function is untouched — it appears in no diff hunk — and #10938 remains open and blocked on its own dependency. Retiring that branch early would restore the defect that #10763 closed on the most common failure path, and the CLI suite would stay green through it.

skip-changeset

Documentation text inside source comments: no command id, flag, description string, or behaviour changes, and nothing here reaches a released artifact's behaviour or --help output. There is nothing for release notes to say, so this PR declares no release of its own.

Out of scope, filed

#12153 — the os environments command family's own --help text and console output still call the entity a "project" (21 user-visible string literals across the same five files). Deduped against #10967, which corrected the command name in examples/JSDoc/class names but not the entity noun in description strings. Unlabelled, no assignee. Not addressed in this PR.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 3 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/cli/src/utils/response-envelope.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

9 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx(via os package publish (command))
• content/docs/deployment/cli.mdx(via os environments create (command), os package publish (command))
• content/docs/deployment/index.mdx(via os package publish (command))
• content/docs/deployment/publish-and-preview.mdx(via os package publish (command))
• content/docs/protocol/kernel/index.mdx(via os package publish (command))
• content/docs/protocol/kernel/lifecycle.mdx(via os package publish (command))
• content/docs/protocol/kernel/metadata-service.mdx(via os package publish (command))
• content/docs/protocol/objectql/index.mdx(via os package publish (command))
• content/docs/protocol/objectql/schema.mdx(via os package publish (command))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via os environments create (command))
• content/docs/releases/v9.mdx(via os package publish (command))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/cli/src/utils/response-envelope.ts) — pages documenting those are invisible to this run
• 1 name(s) were too generic to anchor anything (single lowercase words)
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 23 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 2c4c59ed20caf4f6cde3c979ae9205ee69e04256 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 7b7c2214d3dc33e138e6220e66be35b9501cb793 — the merge of head 479f5c4e1b64778d48c7b0f1fd0d687c06ae9918 into base 2c4c59ed20caf4f6cde3c979ae9205ee69e04256, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 7b7c2214d3dc33e138e6220e66be35b9501cb793 && git checkout 7b7c2214d3dc33e138e6220e66be35b9501cb793
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 2c4c59ed20caf4f6cde3c979ae9205ee69e04256 479f5c4e1b64778d48c7b0f1fd0d687c06ae9918 && git checkout -B drift-repro 2c4c59ed20caf4f6cde3c979ae9205ee69e04256 && git merge --no-ff 479f5c4e1b64778d48c7b0f1fd0d687c06ae9918
node scripts/docs-audit/affected-docs.mjs --json 2c4c59ed20caf4f6cde3c979ae9205ee69e04256

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 2c4c59ed20caf4f6cde3c979ae9205ee69e04256 → pass the list as
args.docs, on the commit named under Which tree this was computed on.