Skip to content

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

Open
thymikee wants to merge 69 commits into
mainfrom
docs/help-ste100
Open

thymikee wants to merge 69 commits into
mainfrom
docs/help-ste100

Conversation

@thymikee

@thymikee thymikee commented Oct 16, 2026 •

Copy link
Copy Markdown
Member

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

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 5.32 MB 5.33 MB +7.6 kB
Package (unpacked) 5.32 MB 5.33 MB +7.6 kB
Package (download) 1.60 MB 1.60 MB +1.6 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 27.9 ms 28.4 ms +0.5 ms
CLI --help 78.4 ms 79.9 ms +1.5 ms

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 53 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/contracts/src/settings-catalog.ts
Comment thread src/commands/capture/screenshot.ts Outdated
Comment thread src/commands/system/index.ts
Comment thread src/commands/interaction/metadata.ts
Comment thread src/commands/schema/cli-help-workflows.ts
Comment thread src/mcp/server-guide.ts
Comment thread src/commands/management/app.ts
Comment thread src/commands/interaction/index.ts
Comment thread packages/command-registry/src/flag-definitions-action.ts Outdated
Comment thread src/commands/capture/wait.ts
@thymikee

Copy link
Copy Markdown
Member Author

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:

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

Copy link
Copy Markdown
Member Author

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

Copy link
Copy Markdown
Member Author

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:

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.

…ves inline

The debugging, tv, react-native, remote, and macos routes stay in the
workflow topic as inline pointers. The deletion makes room for the
ASD-STE100 rewrite inside the 9,100-byte workflow budget.
The workflow and manual-qa topics listed themselves in the shared
Related footer. The self-link repeats the topic that the reader is on.
Restore the routes that the deleted Escalate entries gave:
- alerts: help debugging
- RN hazards and routing: help react-native
- remote config, leases, tunnels: help remote
- desktop, frontmost-app, menu bar: help macos

Delete the duplicate 'snapshot -i is for refs.' sentence to keep the
topic below the 9,100-byte budget.
callHelpTool returns buildUsageText() when the topic is absent, and
buildUsageText() renders renderCliHelpOverview(), the root decision card.
The description said that it returns the full workflow card.
launchConsole said 'Launch console mode.', but the value is a file path:
- packages/platform-apple/src/core/app-launch.ts runIosSimulatorConsoleLaunch
  calls ensureHostDirectory(path.dirname(logPath)) and writes the launch
  stdout/stderr to that path (simctl launch --console-pty).
- openIosApp and assertOpenDeviceSupport refuse it off an iOS simulator
  (LAUNCH_CONSOLE_IOS_SIMULATOR_ONLY_MESSAGE).
- invokeApplicationUrlOpen and invokeApplicationTargetOpen refuse it for URL
  opens (LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE).
- The --launch-console flag text already says 'open: capture the initial iOS
  simulator launch console window to a file'.

jitterPx said 'Randomization radius in pixels.', but the offsets are
deterministic: packages/contracts/src/touch-runtime.ts pressJitter(index,
amount) cycles the fixed PRESS_JITTER table by press index and scales it by
amount. The --jitter-px flag text already says 'deterministic coordinate
jitter'.
Base named the platform scope of help tv (Android TV, tvOS, Vega VVD
remote). Put the scope back inline in the Snapshots and refs section.
Delete the Escalate entry for help scripting: the Validation and evidence
section gives the same route with the same scope, so the topic stays
inside the 9,100-byte budget.
…vice first screen

Base line 26 told the Mac DevToolsSecurity reason apart from the device
Developer Mode reason, gave the device-state gating conditions, and said
that the two device reasons are never inferred. The rewrite moved these
rules below line 30. Put compact versions back on line 26 and move the
never-inferred rule there. The reason list below keeps the details.
The rest of the help uses examine for this concept. The macOS topic and
the network command summary still used inspect. Keep "Do not write
inspect as a command": there, inspect is the literal command word.
Agents often read only the first screen of a help text, and the help
benchmark caps the root help at 30 lines. Several rewrites moved safety
rules below that screen. Declare, for the root help and for every topic
id, the key rules from the base rendering that must stay in lines 1-30:
prerequisites, refusals, verification steps, and recovery. A topic id
without an entry fails the test.
gpt-5.4-mini is not available when Codex runs with a ChatGPT login, so every
Codex call in a default run failed. gpt-5.6-luna is the small model that the
base and head runs for this PR used.
…e sentences

Restores the platform qualifier that the base clause carried:
- screenshot --pixel-density applies only to iOS simulators.
- screenshot --fullscreen for the full desktop applies to macOS.
- --settle-quiet: the tab-switch exception applies on iOS; split the long sentences.

#3735 (comment)
#3735 (comment)
…g sentences

The base tied the logs-over-simctl rule to iOS simulators and the IME retry rule to the Android Gboard bullet.
… sentences

- macOS: the XCTest-backend rule also scopes interactions that bring the app forward.
- gestures: the metric rule applies to the iOS simulator transform/pinch/rotate gestures.
- react-native: keep the worktree build reuse as a capability, not an instruction.
@thymikee

Copy link
Copy Markdown
Member Author

Follow-up at 3e7f1ef:

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

Copy link
Copy Markdown
Member Author

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 thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Oct 17, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant