docs(cli): the README states the global flags and the os plugin group that the built os registers

[objectstack-fleet]

Fixes #21310

Clause-②: no

What changes

packages/cli/README.md now says what the built os does. Every claim below was read off the built entry (packages/cli/bin/run.js, @oclif/core 5.1.2), run from an empty cwd: os --help, os plugin --help, every topic's --help and each documented command's --help. The credential sources were also measured against a local echo server.

• ### Global lists --version and --help only. It says there is no short form: os -h and os -v exit 2. It also names the commands where -v is the command's own flag.
• ### Plugin Management drops "There is no os plugin command group in v1". It lists the registered group instead: os plugin build, os plugin sign and os plugin publish. It notes that the group has no install (per ADR-0025's status line), and that os plugin is unrelated to os plugins.
• Two command-table rows were wrong: os init [name] and os dev [package]. Both are rewritten.
• Cloud credentials and flags (patch round 1). The Cloud section said every cloud command reads os cloud login's session, or --token / OS_CLOUD_API_KEY and --server / OS_CLOUD_URL. A new #### Credentials and server URL table states, per command, the server-URL flag, the token flag and the stored session it uses. The typical publish flow now says that its os environments create step does not read the os cloud login session.
• os serve --ui (patch round 1) now uses the --help wording: "Enable the bundled Console portal", in place of "Enable Studio UI".
• .changeset/21310-cli-readme-flags.md is a patch for @objectstack/cli, because README.md is in the package's files. It now counts five false claims.

No code, flag, environment variable, exit code or help page changes. packages/cli/package.json is untouched.

Short flags: the README route (docs follow the implementation)

Readings on the built entry from an empty cwd. "Before" is at 1caa60373, the branch point after #21167 landed. "After" is at 9bdb092ca, this head.

argv	before	after
os -h	exit 2, command -h not found	exit 2, command -h not found (unchanged by design)
os -v	exit 2, command -v not found	exit 2, command -v not found (unchanged by design)
os --help	exit 0, 3712 bytes, md5 1855676fe5a2bb87aa5871fc1bed196f	byte-identical, same md5
os --version	exit 0, @objectstack/cli/17.6.0 linux-x64 node-v22.22.0	same

The ruling's check. The ruling: "show that no command already uses -h / -v as its own flag. If one does, choose the README route and say why."

Six commands already own -v. Found by git grep for char: 'v' in packages/cli/src, then read back in each command's --help:

• -v is --verbose on os dev (dev.ts:212), os serve (serve.ts:1209), os start (start.ts:93) and os doctor (doctor.ts:1905).
• -v is --version VALUE on os package publish (package/publish.ts:315) and os package install (package/install.ts:57).

No command owns -h. So the ruling sends -v down the README route. -h was eligible on its own, and it is dropped too, for the reasons in the four axes below.

What the alternative would have done. These rows come from oclif's own predicates, versionAddition and helpAddition in @oclif/core 5.1.2 lib/main.js. They were evaluated in memory on this package's loaded Config, with additionalVersionFlags: ["-v"] and additionalHelpFlags: ["-h"] set on it. No file was written.

argv	today	with the two keys
-v serve	exit 2, command -v not found	version check true: prints the version, exits 0, and serve never runs
serve -v	--verbose	--verbose (oclif checks only argv[0] for a version flag)
serve -h	exit 2, Nonexistent flag: -h	help check true: prints help

The four axes.

• 实际业务需求. There is no measured pull. git grep for os -h, os -v and objectstack -h|-v over the whole tree (content/docs, skills, examples, packages, scripts) finds no occurrence. This README's ### Global was the only text that named the short forms.
• 项目长远合理性. -v already has two meanings inside this CLI: verbose on four commands and a package version on two. Adding a third that applies only at argv[0] (print the CLI version) makes the flag's meaning depend on where it appears. Making the docs follow the implementation removes the false claim with no runtime change.
• 防 AI 写代码犯错. Today a mistaken os -v serve fails loudly with exit 2. With the key set, it would print a version line, exit 0 and start nothing, so a loud failure would become a silent one. The README now says the short forms do not exist, so an agent reading it uses --help and --version, which work in every position.
• 创业阶段不扩散需求. New flags would be a new capability with no measured pull, and the default is to keep scope tight. Making only -h work would also leave ### Global asymmetric, with no measured user who needs it.

os plugin — the commands, verbatim

os plugin --help at 9bdb092ca, exit 0. The output is byte-identical at 1caa60373.

Compile a plugin into a signed-ready `.osplugin` artifact (ADR-0025 §3.4)

USAGE
  $ os plugin COMMAND

COMMANDS
  plugin build    Compile a plugin into a signed-ready `.osplugin` artifact
                  (ADR-0025 §3.4)
  plugin publish  Publish a signed .osplugin to ObjectStack Cloud (ADR-0025
                  §3.4)
  plugin sign     Sign a built .osplugin with a publisher Ed25519 key (ADR-0025
                  §3.4)

Usage lines: os plugin build [DIR] [-e VALUE] [-o VALUE] [--minify], os plugin sign ARTIFACT -k VALUE [--key-id VALUE] [-o VALUE] and os plugin publish [ARTIFACT] …. There is no install, and that matches ADR-0025's status line, which says the code-plugin install half is unimplemented.

Every README command-table row against --help

Placeholders are spelled in capitals here (TYPE, NAME, ID).

Section	Row	Conclusion
Development	os init [name]	Changed. It said "in the current directory". os init --help says: "When provided, a new directory with this name is created; otherwise the current directory is used." The Quick Start's own os init my-app was a counterexample.
Development	os dev [package]	Changed. It said "with hot reload". os dev --help says: "watch sources, rebuild the artifact, and restart the server on change". dev.ts records that the old "server will auto-reload" line "advertised a hot reload the runtime only partially performs".
Development	os serve [config]	Already true. For "plugin auto-detection": serve.ts:11 imports isHostConfig / shouldBootWithLibrary from utils/plugin-detection.ts, which detect a host config that carries instantiated plugins. The row leaves out the artifact fallback that --help leads with, but that is an omission, not a false claim.
Build & Validate	os compile [config]	Already true. -o defaults to dist/objectstack.json.
Build & Validate	os validate [config]	Already true. --help also mentions CEL expressions and widget bindings, which the row leaves out.
Build & Validate	os info [config]	Already true. info.ts:117 prints agents.
Scaffolding	os generate TYPE NAME	Left alone, per the ruling (these rows are #21167's, which landed as bcd68a29f before this branch's base). It is also already true: --help marks NAME optional, but generate.ts refuses a metadata type without a name ("Missing required argument"). NAME is optional only for the types, client and migration routes.
Scaffolding	os create TYPE [name]	Already true. --help says "Create a new standalone kernel code plugin from a built-in template", with TYPE = plugin.
Cloud	os cloud login	Already true. -e/--email and -p/--password skip the browser flow, and credentials go to ~/.objectstack/cloud.json.
Cloud	os cloud whoami / os cloud logout	Already true. Both are listed in os cloud --help.
Cloud	os environments create --org ID --name N	Already true. Both flags are required in the usage line. There is no projects topic in os --help.
Cloud	os environments list / show ID	Already true.
Cloud	os package publish [artifact]	Already true. ARTIFACT defaults to dist/objectstack.json.
Plugin Management	(prose)	Changed (see above).
Quality	os test [files], os doctor, os lint [config], os diff [before] [after]	Already true. The usage lines match.
Reference	os explain [schema]	Already true.
CLI Options	### Global	Changed (see above).
CLI Options	os plugins and os help (not commands)	Already true since #21306; not re-edited. os plugins exits 2 with command plugins not found, and os help exits 2 with command help not found. package.json has no oclif.plugins and no @oclif/plugin-* dependency.
Cloud	lead sentence: credentials from os cloud login, or --token / OS_CLOUD_API_KEY and --server / OS_CLOUD_URL	Changed (patch round 1). This holds only for os package publish and os plugin publish. The new per-command table is below.
Cloud	typical flow: os cloud login, then os environments create	Changed (patch round 1). With only the os cloud login session present, os environments create exits 1 with Authentication required. Please run os login or set OS_TOKEN environment variable. The flow now says so at that step and names what the step reads instead.
Cloud	"Set OS_CLOUD_URL (or --server)"	Changed (patch round 1). os cloud login, os package publish and os environments read OS_CLOUD_URL. The flag is --server on os package publish and --url on the other two. os cloud whoami / logout read neither.
CLI Options	### os serve --ui	Changed (patch round 1). It said "Enable Studio UI". It now uses the --help wording: "Enable the bundled Console portal at /_console/ when @object-ui/console is installed (default: true)".

Cloud commands: flags, env vars and stored session, per command

Read off each command's --help at 9bdb092ca. The "stored session" column was measured, not taken from the help: HOME pointed at a temp dir holding only a cloud.json, or only a credentials.json, whose URL was a local echo server that logged each request's path and bearer.

Command	Server URL flag (env)	Token flag (env)	Stored session it authenticates with
os cloud login	-u, --url (OS_CLOUD_URL, default https://cloud.objectos.ai)	none: -e, --email / -p, --password, or the browser device flow	writes ~/.objectstack/cloud.json
os cloud whoami, os cloud logout	none (--json only)	none	read / delete cloud.json (cloud/whoami.ts:26, cloud/logout.ts:29,39)
os package publish	-s, --server (OS_CLOUD_URL, default https://cloud.objectos.ai; with neither set, the URL in cloud.json)	-t, --token (OS_CLOUD_API_KEY, then OS_TOKEN)	cloud.json. With only credentials.json: exit 1, "Not logged in to ObjectStack Cloud. Run os cloud login first", and 0 requests. With only cloud.json: the request goes to its URL with its bearer. With OS_CLOUD_API_KEY or OS_TOKEN: the request carries that bearer.
os plugin publish	-s, --server (OS_CLOUD_URL)	-t, --token (OS_CLOUD_API_KEY)	cloud.json, by the same precedence code as package publish (plugin/publish.ts:170-178). Code-read only; not run, because it needs a built .osplugin.
os environments list / show / create / bind / switch	-u, --url (OS_CLOUD_URL); else the URL in credentials.json; else http://localhost:3000	-t, --token (OS_TOKEN)	credentials.json, the os login session. With only cloud.json, all five exit 1 with Authentication required, before any request. With only credentials.json, list sends GET /api/v1/cloud/environments with its bearer. OS_TOKEN works, and OS_CLOUD_API_KEY alone does not.
os package install (a runtime command, not a cloud one)	-r, --runtime (OS_RUNTIME_URL, default http://localhost:3000)	none: --email / --password (OS_RUNTIME_EMAIL / OS_RUNTIME_PASSWORD)	none
Also read, not in the README's Cloud section: os whoami, os data *, os meta list/get/register/delete	-u, --url (OS_CLOUD_URL)	-t, --token (OS_TOKEN)	credentials.json, through the same createApiClient (code-read)
Also read: os datasource introspect/list-tables/validate	-u, --url (OS_CLOUD_URL, else http://localhost:3000)	-t, --token (OS_TOKEN)	none. These use flags and env only (datasource/introspect.ts:10-13, code-read).
Also measured: os login / os register	-u, --url (OS_RUNTIME_URL for login, OS_CLOUD_URL for register; default http://localhost:3000)	none (email/password, or the device flow for login)	writes credentials.json

Acceptance notes

These are out of scope. The last one is filed as #21360; the others are not filed.

• Registered commands with no README row. build, start, verify, login, logout, register, whoami, migrate, data, datasource, db, i18n, meta, secret, storage, package install and environments bind/switch have no row. These are omissions, not mismatches: the README does not claim to be complete, and content/docs/deployment/cli.mdx is the full reference.
• "Runtime plugins are bundled into the build artifact" is kept as written. I did not re-measure it. Only the false clause in front of it was removed.
• For the seat — the README is now true, but the flow it documents has a gap. After only os cloud login, os environments create refuses and says to run os login. os login --help says "For the hosted package registry, use os cloud login instead." This round changes no code, so the README states the gap rather than closing it. The seat filed it as cli: os environments * never read the os cloud login session, while os login --help sends hosted users to os cloud login — the documented cloud flow loops #21360.

Verification

• Build. pnpm turbo run build --filter=!@objectstack/docs --concurrency=2 at 9bdb092ca: 72/72 tasks, verify-lock VERDICT command-exit 0.
• Derived gates. node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at 9bdb092ca gives 52 commands; the merged main added check-dts-emitted.mjs --self-test. All 52 exited 0 at 9bdb092ca, each exit code captured before any pipe. The --ran reconciliation reads "52 derived, 52 run, 0 NOT-MEASURED, 0 UNRUN", and that zero is derived from recorded exit codes.
• main moved again after the last merge. That happened while the gates ran: 96b12b589 (a pm-roster step in lint.yml) and 23365eaed (spec). Neither touches packages/cli or this changeset. The merge queue rebuilds the PR on current main.
• Runtime unchanged. os --help is byte-identical at 9bdb092ca and at 1caa60373: exit 0, 3712 bytes, md5 1855676fe5a2bb87aa5871fc1bed196f. os -h and os -v still exit 2.
• CLI unit tier. pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2: 244 files and 3461 tests passed, VERDICT command-exit 0, at 4e7e91fd2. Since then, git diff 4e7e91fd2 9bdb092ca -- packages/cli touches only packages/cli/README.md, and no CLI test reads that file. The tests that mention a README read the README that os create emits. The integration tier is left to CI.
• CLI typecheck. pnpm --filter @objectstack/cli typecheck: exit 0 at 4e7e91fd2.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/cli/README.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/cli/README.md) — pages documenting those are invisible to this run
• 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 26 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 f9bcd08befe570333ca631bbc983e05f02947752 → packageMentionDocs.

[objectstack-fleet]

Review: REWORK, patch round 1, PR #21354 (head a5f7446f29), card #21310

Reviewed 2026-10-02T06:35Z by the PM seat (session_018gA1pE6eJtwHhqx72G8U9X) against GitHub and the branch.

What holds, verified at the head:

• Shape and scope. The PR is a draft against main, first line Fixes #21310, subscribed to the dispatching session. Its 2 files are packages/cli/README.md and .changeset/21310-cli-readme-flags.md. packages/cli/package.json is untouched. One commit plus two clean merges of main; feat(cli,create-objectstack): os generate picklist, the src/picklists starter barrel, and a Picklists count in the metadata summary #21167's os generate rows are left alone, as ruled.
• The short-flag route is right. -v is already a per-command flag on six commands: --verbose on dev, serve, start and doctor, and --version <semver> on package publish and package install. The order's own condition therefore picks the README route for -v. The os-dev measured that a global additionalVersionFlags: ["-v"] would make os -v serve print a version, exit 0 and start nothing, turning a loud failure into a silent one. -h was declined for symmetry, with zero measured pull: no text in the tree uses os -h/os -v. os --help stays byte-identical (md5 1855676f…).
• ### Plugin Management now lists the registered os plugin build|sign|publish, read off os plugin --help, and states there is no install (ADR-0025) and that it differs from os plugins.
• The two command rows (os init [name], os dev [package]) now match their --help.
• Docs site. content/docs carries no os -h / os -v claim. Its only -v, --version rows are os package publish/install's per-command --version <semver>, which are true.

The REWORK items. These are two README sentences that the os-dev measured as false and logged as out of scope. They sit in the file this PR makes true, so they are folded in here instead of filed:

1. Cloud auth flags (README line 86, and lines 110-111). The README says cloud commands take --token / OS_CLOUD_API_KEY and --server / OS_CLOUD_URL. At the head every os environments command (list, show, create, bind, switch) declares -t, --token (env OS_TOKEN) and -u, --url (env OS_CLOUD_URL). Read each cloud-facing command's --help (cloud login, environments *, package publish, and any other cloud command) and state the flags and env vars each one really takes. If commands genuinely differ, say so per command. ⛔ Do not change any flag; this is a README fact.
2. os serve --ui (README line 218). It says "Enable Studio UI"; --help says "Enable the bundled Console portal". Use the help's wording.
3. Update the changeset's "Three of its claims were false" paragraph to cover these two, and re-run the gates the README and changeset paths derive.

Not owed this round: a pin test for the no-short-flag state. The PR changes no behaviour, and the os-dev's before/after reading is the evidence.

After the patch round: the diff carries .changeset prose, a contract-review surface, so a CONTRACT_REVIEW_TIER record is owed on the patched head before it queues.

---

Generated by Claude Code

[objectstack-fleet]

Review: ACCEPT, patch round 1, PR #21354 (head 9bdb092ca0), card #21310

Reviewed 2026-10-02T07:18Z by the PM seat (session_018gA1pE6eJtwHhqx72G8U9X) against GitHub and the branch.

The REWORK items (5946805321) are done, verified at the head:

• Cloud credentials and flags. The false lead sentence ("credentials from os cloud login or --token / OS_CLOUD_API_KEY and --server / OS_CLOUD_URL") is replaced by a per-command #### Credentials and server URL table. It agrees with source: every os environments subcommand declares -u, --url (env OS_CLOUD_URL) and -t, --token (env OS_TOKEN). The os-dev also measured each stored-session column against a local echo server (round report 5947221232):

  • with only the os cloud login session (cloud.json) present, the os environments commands exit 1 with Authentication required before any request;
  • os package publish sends that session's bearer.

  The typical flow now says so at the step that breaks. No flag or env var changes in code.

• os serve --ui uses the --help wording: "Enable the bundled Console portal at /_console/ when @object-ui/console is installed (default: true)".

• Changeset. patch for @objectstack/cli, now one bullet per false claim (five). It states that no command, flag, env var, exit code or help page changes.

• Runtime unchanged. os --help is byte-identical to the branch-point capture (md5 1855676f…). os -h / os -v still exit 2.

• CI on 9bdb092ca. ci-failure reads GREEN. The two reds on the superseded head ebe37973 (TypeScript Type Check, Test Core) were lanes cancelled by the newer push; every lane that ran was success.

• PR body refreshed by the seat to this head. The repo squash-merges with the PR body as the commit message.

Finding filed: the gap the README now documents is filed as #21360: os environments never reads the os cloud login session, while os login --help sends hosted users to os cloud login. The remedy is a product decision, not this PR's.

Still owed: the diff carries .changeset prose, a contract-review surface. The PR carries needs:contract-review until a CONTRACT_REVIEW_TIER record for this head reads PASS.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 9bdb092ca051734c96beefbcb1f2534dbed205ee
Local-runs: none

Scope read, at 2026-10-02T07:26Z: card #21310 (body and all three comments: the Claim 5945814810, the round-0 report 5946785715, the round-1 report 5947221232); PR #21354 (body, the two-file list, all three comments: docs-drift 5946760338, REWORK 5946805321, ACCEPT 5947260207); the net three-dot diff against main at merge-base f9bcd08befe5 (64 insertions, 13 deletions, in .changeset/21310-cli-readme-flags.md and packages/cli/README.md); the CLI sources at the head read through git show; and the 45 check-run rows on the head (34 names after grouping). Nothing was built, run or re-run.

① Derived judgments

The diff touches no schema, no command, no flag, no env var and no exit code, so it implies no accept-set change. The one public-surface change it implies is the text of packages/cli/README.md, which packages/cli/package.json lists in files, so it ships in the @objectstack/cli tarball. Each claim the new text makes, judged against the sources at the head:

• ### Global lists --version and --help only and says os -h / os -v exit 2 — right. packages/cli/package.json oclif sets neither additionalHelpFlags nor additionalVersionFlags, and the only oclif dependency is @oclif/core.
• "-v is a command's own flag instead: --verbose on os dev, os serve, os start, os doctor; --version on os package publish and os package install" — right. git grep "char: 'v'" over packages/cli/src at the head returns exactly those six declarations (dev.ts:212, serve.ts:1209, start.ts:93, doctor.ts:1905, package/publish.ts:315, package/install.ts:57), and no file declares char: 'h'. One nit, not a falsehood: the README spells install's value as --version SEMVER, while package/install.ts:56-59 also accepts the tag latest (its default). The flag is named correctly; the placeholder is narrower than the accepted value.
• The short-flag route (README follows the implementation; package.json untouched) — right. The card offered either route and asked for the four-axis reasoning on the one chosen; the PR body carries it. The -v ownership reading above is the decisive fact: a global additionalVersionFlags would make os -v serve print a version and exit 0 without starting anything, a loud failure turned silent. os --help cannot have moved, because no oclif config moved.
• ### Plugin Management now lists os plugin build [dir], os plugin sign ARTIFACT --key PEM and os plugin publish [artifact] — right. src/commands/plugin/build.ts, sign.ts and publish.ts exist at the head: build declares an optional dir, -e/--entry, -o/--out and --minify; sign declares a required artifact, a required -k/--key, --key-id, and -o/--out defaulting to the artifact path plus .sig; publish declares an optional artifact, -s/--server (env OS_CLOUD_URL) and -t/--token (env OS_CLOUD_API_KEY). build loads objectstack.plugin.json (utils/osplugin.ts:77, MANIFEST_FILENAME), which is the manifest the README names.
• "The group has no install: ADR-0025 records the code-plugin install half (download, verify, materialize, load) as not yet implemented" — right. The status line of docs/adr/0025-plugin-package-distribution.md reads "§3.5 steps 4–7: download / verify / materialize / load ... remain unimplemented ... there is no os plugin install command", and its §3.4 is the build → sign → publish pipeline the README cites.
• "os plugin (singular) is unrelated to os plugins (plural), oclif's plugin manager, which this package does not ship" — right. No oclif.plugins key and no @oclif/plugin-* dependency at the head; the existing os plugins / os help section is left as fix(cli): drop the never-loaded oclif.plugins entries and correct the text that says os plugins works #21306 wrote it.
• os init [name] row — right. init.ts:1102: "When provided, a new directory with this name is created; otherwise the current directory is used."
• os dev [package] row — right. dev.ts:191-192 is the README's sentence verbatim, and restart defaults to true (dev.ts:231-236), so "restart the server on change" is what ships.
• The Cloud lead sentence replaced, and the new #### Credentials and server URL table — right, row by row. cloud/login.ts declares -u/--url (env OS_CLOUD_URL, default DEFAULT_CLOUD_URL = https://cloud.objectos.ai at utils/cloud-config.ts:30), -e/--email, -p/--password, and writes cloud.json. cloud/whoami.ts and cloud/logout.ts declare --json only and read / delete cloud.json. package/publish.ts:299-308,510-520 and plugin/publish.ts:60-61,170-178 share one precedence: token = --token (env OS_CLOUD_API_KEY), then OS_TOKEN, then cloud.json; URL = --server / OS_CLOUD_URL, then cloud.json, then the default. Every environments/*.ts declares -u/--url (env OS_CLOUD_URL) and -t/--token (env OS_TOKEN) and goes through createApiClient (utils/api-client.ts:54-96), which falls back to readAuthConfig() = ~/.objectstack/credentials.json (utils/auth-config.ts:47) and then http://localhost:3000, and never reads cloud.json.
• "os environments create does not use the session os cloud login stored ... Without either it exits 1 with Authentication required" — right. environments/create.ts:82-83 calls createApiClient and then requireAuth(token) before any request, and requireAuth throws "Authentication required. Please run os login or set OS_TOKEN environment variable." (api-client.ts:101-107). The dev's echo-server measurement agrees, and the ACCEPT review re-verified it.
• "os package install is not a cloud command: -r, --runtime (env OS_RUNTIME_URL, default http://localhost:3000), --email / --password (env OS_RUNTIME_EMAIL / OS_RUNTIME_PASSWORD)" — right (package/install.ts:50-67).
• os serve --ui row — right. serve.ts:1193 is the README's sentence verbatim.
• Nothing in the diff touches content/docs/references/, content/docs/releases/ or any CHANGELOG.md; no governed surface is on the file list (Governed Surface Queue Guard is success); two files, 77 changed lines; the head repo is the base repo, not a fork.
• The card's three instructions are each met: ### Global made true with the four-axis reasoning in the PR body; ### Plugin Management read off os plugin --help and quoted verbatim; every other command-table row given a conclusion in the PR body's per-row table, with the os generate rows left to feat(cli,create-objectstack): os generate picklist, the src/picklists starter barrel, and a Picklists count in the metadata summary #21167 as the Claim ruled.

② Semver level

.changeset/21310-cli-readme-flags.md declares '@objectstack/cli': patch and carries Clause-②: no; the PR body carries Clause-②: no; the Claim predicted exactly this changeset. Right on both counts. README.md is in the package's files, so the diff publishes from a released package and skip-changeset would be wrong; nothing an author can write is added, removed or renamed, so no minor, no breaking marker and no ADR-0087 disposition is owed (Check Changeset and Lint & Repo Gates are both success on the head). The changeset body states "Nothing at runtime" and names the five corrected claims, each one matching a hunk in the diff.

Clause-②: no — correct; no accept set widens or narrows.

③ Boundary flags

Dev flags from the two round reports (comments 5946785715 and 5947221232), each answered:

• Round 0: a model-bearing Co-Authored-By trailer on the first commit, amended before any push — closed. Both non-merge commits (4e7e91fd2, ebe379735) carry only the model-free pair Claude-Session: plus Co-authored-by: Claude; no pushed commit carries a model identifier.
• Round 0: one build attempt killed by the dev's own timeout and re-run — closed; a process note with no artefact, and the head's check-runs are the gate verdicts.
• Round 1: the PR body not PATCHed by the dev (standing os-dev rule) — closed. The seat refreshed it: the body names 9bdb092ca in its before/after table, carries the verbatim os plugin --help, the credentials table and the --ui row, and ends in the session-URL footer.
• Round 1: the merge chase stopped after one merge while main moved by two commits (96b12b589, 23365eaed) — closed. Neither touches packages/cli or .changeset; GitHub reports the PR mergeable: clean; the queue rebuilds on current main.
• open_questions: [] in both rounds — nothing to answer.
• Out-of-scope findings. The two round-0 README sentences (cloud flag spelling, --ui wording) were folded in by REWORK 5946805321 and are now in the diff — closed. The os environments vs os cloud login session gap is filed as cli: os environments * never read the os cloud login session, while os login --help sends hosted users to os cloud login — the documented cloud flow loops #21360 by the seat — closed as filed. The round-1 note that os package publish, against an echo server answering without a package id, POSTs to .../packages/undefined/versions (package/publish.ts:720 reads pkg.id unchecked) — not escalated: the probe server broke the control-plane contract, no reproduction against the real control plane is in hand, and a defensive id check is a hardening nit for a card of its own, not a finding against this diff.
• Docs Drift Check (comment 5946760338): advisory, not a gate. It says packages/cli/README.md yields no anchor, so it covered nothing — which is why every claim above was read against source by hand.

Check-runs on the head: all 34 grouped names have concluded and none failed (ci-failure exit 0, GREEN). The seven required contexts are success: Lint & Repo Gates, TypeScript Type Check, Test Core, Dogfood Regression Gate, Build Core, Temporal Conformance (live PG + MySQL), Governed Surface Queue Guard. Latest-per-name conclusions of skipped, none a failure: Auto Label (re-trigger rows; the first run is success), Build Docs, Check PR Size (re-trigger rows; the first run is success and size/s is applied), Console Pin Gate (no pin change), Packed-tarball smoke (opt-in). The 11 superseded rows are not read.

Implemented-by: claude/issue-21310-cli-readme-flags
Reviewed-by: session_018gA1pE6eJtwHhqx72G8U9X

VERDICT: PASS

---

Generated by Claude Code