docs(help): write the CLI help and command metadata in ASD-STE100

[thymikee]

Summary

Rewrites the versioned CLI help in ASD-STE100 Simplified Technical English: the root help, all help topics, the MCP guide, and the command, flag, and input metadata that help and MCP render. This is a language change; the meaning of each rule is frozen. Command lines, flags, enums, defaults, limits, and error codes are unchanged. One commit per topic or metadata module.

• New gate src/commands/schema/cli-help-first-screen.test.ts: each topic and the root help declare their key rules, which must stay in the first 30 rendered lines. A new topic must declare its rules. Detection is proved: a moved rule, a missing entry, and the earlier regressions all fail it.
• Three fix(help) commits correct facts: the launchConsole and jitterPx input descriptions, the MCP help-tool description ("root decision card"), and a topic that listed itself in its Related footer.
• The workflow Escalate list no longer lists debugging, tv, react-native, and remote, to fit the 9,100-byte workflow budget. The workflow topic body still points to each of these topics.

Review rounds

• Round 1 (independent; Codex reviewed the Claude-written text): 5 high, 7 medium; fixed.
• Round 2 (Codex): 2 medium; fixed. All metadata families and the other topics are equivalent to base.

Not changed (pre-existing)

• react-native points to Expo URL command shapes that the workflow topic does not have (test-pinned).
• A "Device busy and ownership" section sits in the react-devtools topic.

Validation

• pnpm check:affected --run --head 3e7f1efce6: passed, exactCommit=true.
• pnpm bench:help-conformance (31 cases, claude-haiku-4-5 and gpt-5.6-luna, 3 repeats): base 111/186, head 111/186. A Codex drop on one case did not repeat in a parallel 10-repeat run (base 4/10, head 4/10). The default Codex runner is now gpt-5.6-luna; gpt-5.4-mini does not work with a ChatGPT login.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.38 MB	5.39 MB	+7.8 kB
Package (unpacked)	5.38 MB	5.39 MB	+7.8 kB
Package (download)	1.62 MB	1.62 MB	+1.6 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	29.0 ms	28.8 ms	-0.1 ms
CLI --help	80.5 ms	79.6 ms	-1.0 ms

[cubic-dev-ai]

All reported issues were addressed across 53 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

The rewrite keeps the meaning in the hunks I checked, and one Cubic thread still needs a fix at 9c7d260. The --pixel-density sentence in screenshot.ts now reads as if it applies to every platform. The base text tied it to the iOS simulator default. Please restore that scope (#3735 (comment)). Smoke Tests are failing. The non-test diff changes only help strings, metadata and the Related-footer renderer, so the failure looks unrelated. I had no failure excerpt, so please check that no smoke step matches on help text, or show that the failure is unrelated. The open Cubic thread on the --settle-quiet sentence length in flag-definitions-action.ts (#3735 (comment)) still applies. It is style only.

Not blocking: cli-help.ts grows from 985 to 1021 lines, partly from new code (the RELATED_HELP_LINES table and filter), so moving the topic bodies or the Related-footer renderer to their own module, or opening a follow-up issue, would fit AGENTS.md. Also, commit 8e0ba61 and later commits drop the debugging, tv, react-native, remote and scripting lines from the workflow Escalate list to fit the byte budget, so one line about that in the PR Summary would help. You can take or leave both.

These Cubic threads do not apply, so please resolve them. The base text had the same gap or the same meaning in each case:

• settings-catalog.ts:106: the rewrite keeps the meaning, and adding the contract would add new meaning (docs(help): write the CLI help and command metadata in ASD-STE100 #3735 (comment)).
• system/index.ts:241: the base said the same thing about the hinge angle (docs(help): write the CLI help and command metadata in ASD-STE100 #3735 (comment)).
• interaction/metadata.ts:59: head keeps the target_still_moving meaning (docs(help): write the CLI help and command metadata in ASD-STE100 #3735 (comment)).
• cli-help-workflows.ts:55: the base keyboard rule had no evidence-state contract either (docs(help): write the CLI help and command metadata in ASD-STE100 #3735 (comment)).
• server-guide.ts:18: each tool maps to the CLI command of the same name (docs(help): write the CLI help and command metadata in ASD-STE100 #3735 (comment)).
• management/app.ts:202: neither version mentions a reboot exception (docs(help): write the CLI help and command metadata in ASD-STE100 #3735 (comment)).
• interaction/index.ts:470: the base had the same reading (docs(help): write the CLI help and command metadata in ASD-STE100 #3735 (comment)).
• capture/wait.ts:63: stable is the literal wait kind value (docs(help): write the CLI help and command metadata in ASD-STE100 #3735 (comment)).

I did not compare all 53 files sentence by sentence, so meaning drift outside those threads and the hunks I sampled (workflow, metro reload, settle, fold, open) is not verified. I also did not re-run the check:affected gate, the first-screen mutation proofs or the help-conformance bench. Before merge, please restore the iOS-simulator scope on the --pixel-density sentence and get Smoke Tests green or show that the failure is unrelated.

[thymikee]

One more thing: main moved after my review, and 9c7d260 now has merge conflicts with main. Please rebase and resolve them together with the findings above.

[thymikee]

Thanks for the update. The earlier Smoke Tests failure does not recur: the six checks at 9245e80 show no failures, and the change since the last review only touches a bench script that CI does not run. One finding from the 9c7d260 review is still open, and the PR has merge conflicts with main.

The --pixel-density sentence in screenshot.ts is unchanged. The base text said "iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density." The semicolon tied the flag to iOS simulators. The new split makes "To request a different screenshot density, use --pixel-density." read as a rule for every platform. At runtime, screenshot-density.ts rejects the flag on everything except iOS-family simulators. An agent that reads help screenshot may pass the flag on Android, macOS or web and get an unsupported error. Every split sentence should keep the platform qualifier that the base clause carried. For this one, something like "On iOS simulators, use --pixel-density to request a different screenshot density." would do.

Not blocking: the change to DEFAULT_RUNNERS in help-conformance-bench.mjs is a tooling change inside a help-text PR, and you can keep it as the PR body explains or move it to a small chore PR.

On the open inline threads, the --pixel-density thread still stands and is the same issue as above. The --settle-quiet wording thread also still applies. It is style only, with sentences of about 27 to 30 words. These threads do not apply, so you can resolve them:

• settings-catalog.ts:106: the base airplane line also had no failure contract, and adding one would add meaning.
• system/index.ts:241: the base said the same about the fold angle.
• interaction/metadata.ts:59: the new text keeps the base target_still_moving meaning.
• cli-help-workflows.ts:55: the base keyboard rule also had no evidence-state contract.
• server-guide.ts:18: each tool maps to the CLI command of the same name, and the base made the same claim.
• management/app.ts:202: neither version mentions a reboot exception.
• interaction/index.ts:470: the base had the same reading.
• capture/wait.ts:63: stable is the literal wait-kind value.

I reviewed the code at 9245e80 and found one remaining defect. Before merge, please restore the iOS-simulator scope on the --pixel-density sentence and rebase onto main to clear the conflicts. Neither change is in the 9c7d260..9245e80 delta.

I could not verify that the gpt-5.6-luna model exists or that the 111/186 bench parity holds, since both come only from the PR body. I did not re-check meaning drift sentence by sentence outside the new delta, because the earlier review sampled hunks and commits 1-65 are unchanged in the range-diff. I also did not re-run the check:affected gate or the first-screen gate mutation proofs.

[thymikee]

Follow-up at 3e7f1ef:

• Rebased on main and resolved the conflicts in alert.ts, install.ts, client-app.ts, and system/index.ts. Main's alert-decline rule (fix(ios): alert dismiss picks a listed decline, never a guessed one #3715), uninstall command (feat(apps): add standalone uninstall command #3720), and telephony command (feat(android): simulate an incoming call or SMS on an emulator #3724) are kept.
• 6dda7ef, bf472ce, 3e7f1ef: each split sentence keeps the platform qualifier that its base clause had. This includes --pixel-density ("On iOS simulators, …"), the macOS --fullscreen sentence, the iOS scope in --settle-quiet (now short sentences), and the iOS simulator, Android, and backend scope in the debugging topic and the cli-help sentences.
• The DEFAULT_RUNNERS bench change stays (b0b85b4).

Threads: 2 fixed (pixel-density, settle-quiet), 8 do not apply because the base text had the same meaning (resolved, as asked). None are rejected and open.

CI: the earlier Smoke Tests failure did not recur at 9245e80. Checks for 3e7f1ef are pending.

Validation: pnpm check:affected --run --head 3e7f1efce6 passed, exactCommit=true. Schema help tests pass (124), including the first-screen gate. Root help is 2,961 bytes. The workflow topic is 9,065 bytes.

Not done: the cli-help.ts split (985 → 1,021 lines) is outside this PR's scope.

[thymikee]

The PR is ready. At 3e7f1ef, the follow-up changes fix the two points from the earlier review at 9245e80 (#3735 (comment)): the screenshot help now scopes --pixel-density to iOS simulators, and the action flag text is split into short sentences that keep the iOS scope. Not blocking: the merge conflict resolution kept some main text in the old wording (the alert-decline sentence and the new telephony and uninstall descriptions, starting at https://github.com/callstack/agent-device/blob/3e7f1ef/src/commands/capture/alert.ts#L1), so you can rewrite them in STE here or in a follow-up, or leave them.

Of the open inline threads, the two on #3735 (comment) and #3735 (comment) are fixed at this commit, so you can resolve them. The other eight do not need changes because the base text said the same: #3735 (comment) (the base airplane line also had no failure contract), #3735 (comment) (the base said the same), #3735 (comment) (keeps the base target_still_moving meaning), #3735 (comment) (the base keyboard rule also had no evidence-state contract), #3735 (comment) (each tool maps to the CLI command of the same name, as in the base), #3735 (comment) (neither version mentions a reboot exception), #3735 (comment) (the base reads the same), and #3735 (comment) (stable is the literal wait-kind value).

CI is green: 17 checks, none failing at 3e7f1ef. There are no conflicts. I did not re-audit commits 1-66 sentence by sentence for meaning drift, because they are unchanged in the range-diff. I did not check that the Android-scoped formatting rule in cli-help-workflows.ts holds for both the ADB and Appium backends. It sat in the Android bullet in the base too, so this change makes no new claim. I did not re-run the gates or the help-conformance bench locally. Nothing else blocks human review.

[thymikee]

The code review at 3e7f1ef is still clean, but the branch now conflicts with main after the latest merges. Please rebase onto main and resolve the conflicts. I removed the ready-for-human label until the branch merges cleanly again.

[thymikee]

Rebased onto origin/main (92db564a30) and resolved the conflicts. Head: 26e696ddca.

Conflicts and how main's changes were merged:

• cli-help.ts physical-device topic: kept the PR's STE list form for the runner startup reasons and added main's new reasons simulator_service_hub_unavailable and simulator_set_destination_not_found in STE. Added main's new daemon ensure/replace paragraph (daemonLifecycle, ensureDaemon(), daemon-busy, daemon-incompatible) as short STE sentences. No rule dropped.
• cli-help.ts remote topic: added main's new provider-not-registered lease rule in STE between the credential-comparison and direct-provider rules.
• command-overrides.ts: kept main's new facts (plugins list offline behavior, daemon status action and summary) written in the PR's STE form; kept main's usage/flagsByAction changes byte-identical.
• The commit "restore the frozen meaning in the command overrides" became empty (main's new summary already carries its meaning) and was dropped: 68 commits.
• Main's new help prose outside conflicts (telephony, uninstall, alert-decline sentence) is unchanged, as before.

Budgets after rebase: root help 2,961 bytes (≤ 3,000), workflow topic 9,065 bytes (< 9,100), MCP instructions and 72-char summaries verified by their tests. First-30-lines gate passes.

Validation: pnpm install --frozen-lockfile && pnpm build, pnpm format, pnpm vitest run src/commands/schema (124 passed), plus the MCP/summary budget suites (74 passed). pnpm check:affected --run --head 26e696ddca: all runnable checks passed, exactCommit=true.

No new comments on any surface. Not merged, not approved.

[thymikee]

Coverage failure — root cause and fix (900dc7f). Not a hang: the rerun job log (job 117407587662) ends with 1 failed | 15802 passed and ##[error]Process completed with exit code 1. The failed test is test/repo-guards/runner-startup-reason-docs.test.ts: cli-help.ts must document the bundle_identifier_already_registered reason. The STE rewrite split the runner-startup sentence into the vertical list under iOS runner startup reasons (details.reason): (STE rule: vertical lists for >3 items), while the guard still read only the first line naming error.details.reason — a line that now names no reasons. The rebase brought in main's guard (#3739), which passed pre-rebase only because the old single sentence was there. Fix: the guard now reads the enumeration from either shape — the STE list block under its heading, or the single sentence — scoped to that block, never the whole file, and asserts the list is not shorter than the union. Verified locally: guard fails on head before the fix, passes after; deleting a list entry still fails with the intended reason. Reproduced on test/repo-guards + first-screen help tests and pnpm check:affected --run --head 900dc7f514 (exactCommit=true, all checks passed).

[thymikee]

Rebased onto origin/main (d17f710053, #3714). New head: 9ba5212ffc (force-with-lease pushed).

One conflict, in src/commands/schema/cli-help.ts (react-devtools topic, "Device busy and ownership"). Main reworded the DEVICE_IN_USE second flavor to name its real owner:

"owned by session X in workspace Y" is the host-global device claim another session — from this daemon or another worktree's daemon — or an in-flight command holds; there may be no session to close, and it is never retriable, so run the error's exact recovery command instead of retrying.

Merged as STE sentences with the same facts (owner = another session or an in-flight command, either daemon, no session to close, never retriable, run the error's recovery command):

"owned by session X in workspace Y" means that another session or an in-flight command holds the host-global device claim. That session is from this daemon or from another worktree's daemon. There may be no session to close. This error is never retriable. Run the exact recovery command from the error. Do not retry.

Budgets unchanged and green: root help 2,969 ≤ 3,000 bytes, workflow topic 9,065 < 9,100, MCP instructions under 2,048, summaries ≤ 72 chars, first-30-lines gate and the runner-startup-reason docs guard pass. No budget raised.

Receipt: pnpm check:affected --run --head 9ba5212ffc — all runnable checks passed, exactCommit=true. Focused: pnpm vitest run src/commands/schema (124 passed), pnpm exec vitest run --project unit-core test/repo-guards (54 passed).

[thymikee]

Rebased 900dc7f514 onto origin/main d17f710053 and pushed 9ba5212ffc. The only conflict was in cli-help.ts, from #3714. Main's new DEVICE_IN_USE text is now in STE with the same meaning: another session or an in-flight command holds the host-global device claim; that session is from this daemon or from another worktree's daemon; there may be no session to close; the error is never retriable. Local gate: pnpm check:affected --run --head 9ba5212ffc passed (run-whQtc2, exactCommit=true).

[thymikee]

Rebased 9ba5212ffc onto origin/main a60fe5a64e (#3783, #3762) and pushed 4b4a206230 (--force-with-lease).

One conflict, in src/commands/schema/cli-help.ts. Main's new drain sentence (#3783):

A daemon that agreed to leave is waited for up to 60 s and never signaled while it drains; one still running then fails with details.reason daemon-drain-timeout unless it answers nothing and is provably a daemon process, which is force-retired.

Written in STE with the same facts (60 s wait, no signal while draining, daemon-drain-timeout, the one force-retire exception):

The command waits up to 60 s for a daemon that agreed to leave. It sends no signal while the daemon drains. If the daemon still runs after that wait, the command fails with details.reason daemon-drain-timeout. The one exception: if the daemon answers nothing and the command can prove it is a daemon process, the command force-retires it instead.

No command examples changed by main; none touched. Budgets unchanged, no budget raised: root help 2,960 ≤ 3,000 bytes, workflow topic 9,065 < 9,100, MCP instructions < 2,048, summaries ≤ 72 chars, first-30-lines gate and runner-startup-reason-docs.test.ts pass.

Receipt: pnpm check:affected --run --head 4b4a206230 — all runnable checks passed, exactCommit=true. Focused: pnpm vitest run src/commands/schema (124 passed), pnpm exec vitest run --project unit-core test/repo-guards (54 passed).

[thymikee]

The code is ready for review at 4b4a206. The conflict from the earlier review (3e7f1ef) is gone, so there are no conflicts, and all checks pass. This change touches docs and help text only.

Not blocking, and you can take or leave it: cli-help.ts grew from 987 to 1030 lines, and AGENTS.md asks us to split a file before adding behavior past 1,000 lines. The new related-help table and footer filter add that behavior. Moving one topic family out of the help topics into its own module, as cli-help-workflows.ts and cli-help-overview.ts already do, would bring it back under the limit. Please also add scripting to the list of removed Escalate entries in the PR body.

I did not find any open threads from other reviewers. The 10 resolved threads are not checked against the head. I only checked the drain and lifecycle block in cli-help.ts in detail. I did not diff every rewritten line for a changed flag or default, and I did not search the tree for other copies of the help text.

Nothing else must happen before merge.

[thymikee]

Closing by maintainer decision: the STE rewrite adds text (+7.8 kB) and does not give enough confidence, and the existing help was mostly good. The help stays as it is on main. The branch stays for reference.