Skip to content

feat(runner): move the runner guide into the CLI's help - #1652

Merged
Erzhan Torokulov (erzhtor) merged 1 commit into
mainfrom
erzhan/age-5384-runner-guide-in-help
Oct 6, 2026
Merged

Erzhan Torokulov (erzhtor) merged 1 commit into
mainfrom
erzhan/age-5384-runner-guide-in-help

Conversation

@erzhtor

@erzhtor Erzhan Torokulov (erzhtor) commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Relates to AGE-5384. Stacked on #1651. Supersedes #1649.

Overview of Changes

references/runner.md was a 668-line hand-written guide next to the commands it described, so it drifted. Its runner actions section still said sequences take no tap, swipe or fill after 1.39.0 shipped them (fixed in #1649, which this folds in). Tester never read it at all: its platform skill restates the rules instead.

This PR moves that knowledge into the CLI, so it ships with the version that runs it:

  • Each section that belongs to one command is now that command's --help, after its examples (exec says the value never comes back and how to read it from events console, run covers what travels, env vars and the unreachable-runner trap, and so on). Sources are unwrapped text files in src/commands/runner/guides/, laid out like the rest of --help by formatGuide.
  • What spans commands (which runner a command reaches, why the first call must be a run, exit codes, end-to-end example) is workflow.md. declareReferenceGuide attaches it to runner, and only qawolf help ref runner prints it, so qawolf runner --help stays short.
  • references/runner.md is now generated from qawolf help ref runner by bun run generate, and a test fails if it drifts. It stays in place for agents that can't run the CLI and for the GitHub URL older skills link to.
  • The skill template tells agents to run qawolf help ref runner first, with the file and URL as fallbacks.
  • Folded in from docs(runner): mobile actions in runner actions sequences (AGE-5384) #1649: runner actions takes tap, swipe, fill and type on mobile, and on mobile, send tap and swipe, never click or drag.

Size: help ref runner is about 62 KB, up from 25 KB of help plus a 39 KB runner.md read separately.

Stack:

# PR Contribution
1 #1651 qawolf help ref [command...] prints a command subtree's full help as Markdown
2 #1652 (this PR) runner.md's knowledge moves into each runner command's --help; runner.md is generated from qawolf help ref runner
3 qawolf/platform#34845 Tester's qawolf-cli skill points at the CLI's help instead of restating it

Merge after #1651; both ship together in 1.40.0. qawolf/platform#34845 waits for that release.

Testing

bun run typecheck && bun run lint && bun run format:check && bun run knip && bun run test && bun run build
node dist/cli.js runner exec --help   # the guide text is bundled

The --help snapshots changed only by the appended guides. New tests cover formatGuide, the ref-only guide and its heading levels, and the drift check between runner.md and help ref runner. The generated runner.md is stable under oxfmt. All tests pass except 3 keychain tests that also fail on main on this machine.

Checklist

  • Changes follow the code style of this project
  • Self-review completed
  • Tests added/updated (or not applicable)
  • No breaking changes (or described below)

Base automatically changed from erzhan/age-5384-help-ref to main October 6, 2026 15:22
@erzhtor
Erzhan Torokulov (erzhtor) force-pushed the erzhan/age-5384-runner-guide-in-help branch from f51557b to e18d76c Compare October 6, 2026 15:22
@erzhtor
Erzhan Torokulov (erzhtor) merged commit bced9bb into main Oct 6, 2026
6 checks passed
@erzhtor
Erzhan Torokulov (erzhtor) deleted the erzhan/age-5384-runner-guide-in-help branch October 6, 2026 15:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants