diff --git a/packages/cli/src/commands/environments/create.ts b/packages/cli/src/commands/environments/create.ts
index 3d1fe9bfe3..c0f166b88d 100644
--- a/packages/cli/src/commands/environments/create.ts
+++ b/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',
diff --git a/packages/cli/src/commands/package/publish.ts b/packages/cli/src/commands/package/publish.ts
index c1be9ba559..c171e26f41 100644
--- a/packages/cli/src/commands/package/publish.ts
+++ b/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';
diff --git a/packages/cli/src/utils/api-client.ts b/packages/cli/src/utils/api-client.ts
index 2025fb8c06..6213c0d7bf 100644
--- a/packages/cli/src/utils/api-client.ts
+++ b/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;
   /**
diff --git a/packages/cli/src/utils/response-envelope.ts b/packages/cli/src/utils/response-envelope.ts
index 16351e8557..1c4123c439 100644
--- a/packages/cli/src/utils/response-envelope.ts
+++ b/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