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

* docs(cli): fix two stale `os …` invocations, docblock the two deliberate ones

`os projects switch` (utils/api-client.ts) and `os packages install`
(commands/environments/create.ts) name ids the CLI does not register:
`projects` became `environments` in v5.0 with no aliases (ADR-0006), and the
package topic is singular. Both corrected against the ids read from the built
oclif `Config`.

The other two documented invocations in this package that do not resolve are
correct prose, not defects, so they are annotated rather than changed:
`os publish` / `os rollback` in commands/package/publish.ts name commands that
were deliberately removed, and `os datasource` in utils/response-envelope.ts
names a real topic whose three subcommands are the runnable ids. Each now says
so in place, so a future reader — or a future sweep author — does not "fix"
accurate prose.

Comment text only; no command id, flag, or behaviour changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HbG3rGVLjZStHQxHDtzJdJ

* docs(cli): word the two notes so they do not plant new unresolved spans

Re-running the sweep this card measures showed the notes had added three
sweep hits of their own: each contained a literal backticked `os …` span,
which the sweep reads as an invocation that resolves to nothing. A note whose
purpose is to keep a future sweep honest should not inflate that sweep's own
numbers, so both now describe the sweep without spelling a placeholder
invocation. The retired ids they deliberately name are unchanged.

Measured after: 583 invocations across 109 non-test sources, 5 unresolved —
the two genuinely stale ones are gone, and every remaining hit is one of the
retired/topic names these two notes exist to declare.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HbG3rGVLjZStHQxHDtzJdJ

---------

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

Author: os-trump

packages/cli/src/commands/environments/create.ts

@@ -36,7 +36,7 @@ export default class EnvironmentsCreate extends Command {
     // the `blank`/`crm`/`todo` registry it named died with the `apps/server`
     // templates route. Removed in #3731: an accepted-and-dropped flag reports
     // success for work that never happened. Starter content is installed from
-    // the App Marketplace instead (`os packages install`, `sys_package` with
+    // the App Marketplace instead (`os package install`, `sys_package` with
     // `is_starter = true`).
     artifact: Flags.string({
       description: 'Path to a locally-compiled objectstack.json artifact to bind into this project',

packages/cli/src/commands/package/publish.ts

@@ -16,6 +16,14 @@
  * way to publish. (The legacy direct-to-environment `os publish` / `os
  * rollback` commands, which wrote sys_environment_revision, have been
  * removed.)
+ *
+ * NOTE — `os publish` and `os rollback` above are RETIRED ids, named here on
+ * purpose: the sentence is *about* their removal, and neither resolves today.
+ * Measured against the built oclif `Config`: the registered `publish` ids are
+ * `package publish` and `plugin publish`, and no `rollback` id exists at all.
+ * A sweep over the documented CLI invocations in this package will flag both
+ * of them as unresolved — leave them. Re-spelling either to a live id would make the
+ * sentence false, and deleting the sentence would drop accurate history.
  */
 
 import { readFile } from 'node:fs/promises';

packages/cli/src/utils/api-client.ts

@@ -17,7 +17,7 @@ export interface ApiClientOptions {
   token?: string;
   /**
    * Explicit project id. Overrides the stored `activeEnvironmentId` from
-   * `~/.objectstack/credentials.json` (written by `os projects switch`).
+   * `~/.objectstack/credentials.json` (written by `os environments switch`).
    */
   environmentId?: string;
   /**

packages/cli/src/utils/response-envelope.ts

@@ -23,6 +23,15 @@
  * drifts three times, and the three commands are how a human learns the server
  * disagrees with them.
  *
+ * (`datasource` is a TOPIC, not a runnable command id: the three subcommands
+ * are `datasource introspect`, `datasource list-tables` and `datasource
+ * validate` — verified against the built oclif `Config`, where `datasource`
+ * appears among the topics and not among the commands. The prose above names
+ * the topic, and naming it is correct; a sweep over the documented CLI
+ * invocations in this package flags `os datasource` as unresolved, and that
+ * flag is a false positive — do not rewrite the sentence around one
+ * subcommand, which would say something narrower and untrue.)
+ *
  * ## Why an unreadable body is an ERROR here, never an empty payload
  *
  * That is the same defect generalised. The severe half was never the crash on