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

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