@qawolf/cli 1.38.0 → 1.40.0

package/skills/qawolf-cli/references/runner.md

@@ -1,662 +1,1213 @@
-# Driving a runner from the terminal
-
-An interactive runner is a live pod with a browser in it. You launch one, look
-at it, act on it, run flows on it, and read what it recorded. Everything is a
-plain request to one host, so there is no connection to hold open.
-
-## Getting one
-
-Runner ids are yours to choose and are scoped to your team, so `agent-1` is a
-fine id. Launching an id that is already running attaches to that runner instead
-of starting and billing a second one, and the answer says which happened: read
-`alreadyRunning`. Reusing one id is therefore the
-cheap and safe pattern, and the same id with a different `--name` is refused
-rather than silently ignored.
-
-Either answer carries a `url`, which `qawolf runner launch` prints, as does a command that launched its own runner. It is a QA Wolf page showing what the runner is doing, where a person can also take over with their own mouse and keyboard. Hand it to a person who asks what your runner is up to. The page opens for anyone on the runner's team, however the runner was launched. There is nothing to see until the runner's first run starts its screen, so the page waits until then. You read the screen with `screenshot`, not with the page.
-
-Commands that target a runner find one in this order: `--runner`, then
-`QAWOLF_RUNNER_ID`, then the runner stored for the current directory (which
-`qawolf runner launch` sets). Setting the environment variable once is the most
-robust for a harness whose working directory may not be stable, but it comes
-with three catches worth knowing before you rely on it.
-
-`qawolf runner launch` is not in that order: it takes its id from `--id` and
-never reads `QAWOLF_RUNNER_ID`. Bare `qawolf runner launch` invents a random id,
-bills a pod under it and stores it, so a harness that exported the variable and
-then launched without `--id` ends up with a pod it is not addressing. Pass
-`--id` whenever you have an id in mind.
-
-And a runner id that is set is treated as found, whether or not anything is
-running under it. So exporting `QAWOLF_RUNNER_ID=agent-1` turns off the
-auto-launch described next: instead of starting `agent-1`, commands try to reach
-it and fail with exit code `8`, naming the id and saying the variable is what
-chose it. Launch that id once yourself and the rest follows.
-
-And launching an id that differs from `QAWOLF_RUNNER_ID` prints a warning on
-stderr naming both ids: the variable still outranks the directory default, so
-commands that omit `--runner` keep going to whatever it names, not the runner
-you just launched. Expected when you are launching an additional runner on
-purpose — address that one with `--runner` rather than re-exporting the
-variable, which would repoint every other runner-less command too.
-
-If nothing names a runner, the commands that change something will launch one
-and say so on stderr, naming it: `run`, `act` and `exec`. **Read that
-announcement.** The browser it just started is fresh: nothing has been run on it,
-nothing is signed in, and no page is open. Acting as though your earlier setup
-survived is the single most likely way to drive the wrong page.
-
-No `read` command ever launches a runner. `screenshot`, `events` and `keepalive`
-tell you there is no runner rather than quietly billing one, and so does
-`terminate`, since starting a pod in order to end it would be absurd.
-
-`--name` also chooses between a browser and a mobile device:
-`qawolf runner launch --name android` or `--name ios` starts an Appium session
-instead of a browser. A command built for the other kind answers a
-`failureReason` naming the mismatch rather than doing something approximate —
-`runner-is-not-mobile` from `inspect session`/`contexts`/`page-source`/`elements`
-on a browser runner, `runner-is-not-a-browser` from `inspect element-html`/
-`page-html` on a mobile one — so launch the right family up front rather than
-discovering it from a refusal mid-session.
-
-## Knowing what you are holding
-
-`qawolf runner list` names the runners this directory has launched that are
-still running, and marks the one a command with no `--runner` would reach:
+<!-- Generated by `bun run generate` from `qawolf help ref runner`, do not edit. Edit the runner commands' help under src/commands/runner instead. -->
 
-```text
-id                   family      default
-tester-abc-main      playwright  yes
-tester-abc-checkout  playwright
-```
+# qawolf runner
 
-Every runner is looked up before it is listed, so a runner that idled out is
-absent rather than reported. The lookup neither starts a runner nor resets an
-inactivity clock, which is what separates `list` from `keepalive`: listing tells
-you what is there and changes nothing, and holding a runner open is still
-`keepalive`'s job. A lookup that cannot be answered fails the command rather
-than returning a shorter list, because a short list reads as the whole truth.
+An interactive runner is a live pod with a browser or a mobile device in it. You launch one, look at it, act on it, run flows on it, and read what it recorded. Everything is a plain request to one host, so there is no connection to hold open. This guide covers what spans commands; each command's own help below covers the rest.
 
-Nothing is billed by listing, but everything in the list is billing. Terminate
-what you are done with.
+## Which runner a command reaches
 
-The list includes the runner named by `QAWOLF_RUNNER_ID` even though this
-directory did not launch it, so a harness handed a runner sees it alongside the
-ones it started itself. Use the `id` column with `--runner` to address any of
-them; addressing one does not make it the default.
+Commands that target a runner find one in this order: `--runner`, then `QAWOLF_RUNNER_ID`, then the runner stored for the current directory, which `qawolf runner launch` sets. Setting the environment variable once is the most robust for a harness whose working directory may not be stable, with two catches:
 
-The table leaves out the page address, which beside a 63-character id outgrows a terminal. `--json` carries it as `url` on every runner:
+- `qawolf runner launch` is not in that order: it takes its id from `--id` and never reads `QAWOLF_RUNNER_ID`. Pass `--id` whenever you have an id in mind.
+- A runner id that is set is treated as found, whether or not anything is running under it. Exporting `QAWOLF_RUNNER_ID=agent-1` turns off the auto-launch described next: instead of starting `agent-1`, commands try to reach it and fail with exit code `8`, naming the id and saying the variable is what chose it. Launch that id once yourself and the rest follows.
 
-```sh
-qawolf runner list --json | jq -r '.[] | [.id, .url] | @tsv'
-```
+If nothing names a runner, the commands that change something launch one and say so on stderr, naming it: `run`, `act` and `exec`. Read that announcement. The browser it just started is fresh: nothing has been run on it, nothing is signed in, and no page is open. Acting as though your earlier setup survived is the single most likely way to drive the wrong page.
+
+No read command ever launches a runner. `screenshot`, `events` and `keepalive` tell you there is no runner rather than quietly billing one, and so does `terminate`.
 
 ## The order that matters
 
-A freshly launched runner has no screen. The virtual desktop starts with the
-runner's **first run** and nothing else starts it, so until you have run
-something:
+A freshly launched runner has no screen. The virtual desktop starts with the runner's first run and nothing else starts it, so until you have run something:
 
-- `screenshot` and `act` fail with exit code `2`, except `navigate`, which
-  fails with exit code `1` (`action-failed`): it skips the screen but still
-  needs the runner to have run something
+- `screenshot` and `act` fail with exit code `2`, except `navigate`, which fails with exit code `1` (`action-failed`): it skips the screen but still needs the runner to have run something
 - `exec` fails with exit code `2`
 - `events recorder` reads as empty
 
-None of that is a fault, and none of it clears on its own. **Only
-`qawolf runner run <flow>` starts the screen.** A bare navigate does not: it
-fails until the first run, however long you wait.
+None of that is a fault, and none of it clears on its own. Only `qawolf runner run <flow>` starts the screen. A bare navigate does not: it fails until the first run, however long you wait.
 
-So the first thing you do to a new runner has to put a browser on it. That means
-a flow file and a `package.json` on disk, even if all you want is to drive the
-browser by hand; there is no "just give me a screen" call. Once one run has
-happened, the screenshot-and-act loop below works for the rest of the runner's
-life.
+So the first thing you do to a new runner has to put a browser on it. That means a flow file and a `package.json` on disk, even if all you want is to drive the browser by hand; there is no "just give me a screen" call. Once one run has happened, the screenshot-and-act loop works for the rest of the runner's life. A `--lines` selection is the one call that does not need a run first.
 
-A `--lines` selection is the one call that does not need a run first. Sent to a
-runner with no browser, the runner starts one and runs your lines against it,
-and says so on stderr. Everything else on this page waits for a run.
+## Exit codes
 
 Retry on the exit code, not on the message text:
 
-- `4` is transient, with one exception. The screen is up but cannot serve this instant: restarting after a display-size change, or busy with another request. Retry in a second or two, and bound the retries. The exception is a command that changes something, where a `4` can instead mean the answer was lost with the work in flight. For `act` and `actions`, take a screenshot first and repeat only what the screen says did not happen. For `run`, poll `run-status` instead of submitting again, since a second submission risks a second billed run (see Running a flow). For `exec`, check the effect the snippet was meant to have before running it again.
-- `6` means the work ran out of the time it is given. A `runner actions` sequence leaves by the worst thing that happened to any one of its actions — an effect nobody can confirm (`4`) first, then running out of time (`6`), then a refusal (`2`), then an action that plainly did not happen (`1`) — so a sequence that did not reach every action exits `6` only when nothing worse also went wrong. Whatever the code, the message names the last action that took effect, and only what follows it goes in a new request.
-- `8` means there is no such runner. It was never launched, or it was
-  terminated, or it idled out. Retrying never brings one back, so stop and
-  launch the id or name one that is running. The message says which runner was
-  meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored
-  default chose it — read that line before you pick an id to launch.
-- `2` will not clear on its own. Nothing has run on this runner yet, so run a flow; or the runner has no browser at all, so launch with `--name playwright` instead; or the action belongs to the other runner family, so send `tap`, `swipe` or `fill` to a mobile runner and the browser actions to a browser runner. A `runner actions` sequence also exits `2` before it sends anything, for an argument that is not a JSON array, an array of more than ten actions, and `--screenshot` flags that contradict each other. The message says which.
-
-## Seeing and acting: the loop is yours
-
-Two primitives, and you close the loop with your own model. There is no hosted
-vision loop on this surface.
-
-`qawolf runner screenshot --out page.jpg` writes a real JPEG to disk, decoded,
-because every coding harness can open an image file. Read it with whatever
-vision you have. `--out -` writes the JPEG bytes to stdout instead, on their own,
-for a caller that is a process rather than an agent: the confirmation, and the
-JSON line under `--json`, goes to stderr so nothing follows the image on stdout.
-A terminal on stdout is refused: redirect or pipe it.
-
-`qawolf runner act <action>` performs exactly one action per call, in the
-computer-use tool vocabulary a vision model already emits: `click`,
-`double_click`, `scroll`, `move`, `drag`, `keypress`, `navigate`, `type`. The
-names and the field names are unchanged from that vocabulary on purpose, so you
-can forward a tool call rather than translate it:
+- `4` is transient, with one exception. The screen is up but cannot serve this instant: restarting after a display-size change, or busy with another request. Retry in a second or two, and bound the retries. The exception is a command that changes something, where a `4` can instead mean the answer was lost with the work in flight. For `act` and `actions`, take a screenshot first and repeat only what the screen says did not happen. For `run`, poll `run-status` instead of submitting again, since a second submission risks a second billed run. For `exec`, check the effect the snippet was meant to have before running it again.
+- `6` means the work ran out of the time it is given.
+- `8` means there is no such runner. It was never launched, or it was terminated, or it idled out. Retrying never brings one back, so stop and launch the id or name one that is running. The message says which runner was meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored default chose it; read that line before you pick an id to launch.
+- `2` will not clear on its own. Nothing has run on this runner yet, so run a flow; or the runner has no browser at all, so launch with `--name playwright` instead; or the action belongs to the other runner family, so send `tap`, `swipe` or `fill` to a mobile runner and the browser actions to a browser runner. The message says which.
 
-```sh
-echo '{"type":"click","button":"left","x":480,"y":260}' | qawolf runner act -
-```
+`act`, `actions`, `run` and `exec` are the commands whose lost answer may still have taken effect.
 
-Every action in a see-and-act loop is followed by a look at the result, so ask
-for it in the same call: `act ... --screenshot step-1.jpg` (or `--screenshot -`
-for stdout) performs the action and writes the screen the runner answers with.
-Prefer it over `act` and then `screenshot`: each step is one call instead of
-two, with no delay to guess at between them. The screen the runner answers with
-is taken once it has changed from just before the action or half a second has
-passed, whichever comes first. An action that reached the screen and did not
-take effect answers with one too, so a `1` from `act --screenshot` still leaves
-you a picture of why the click missed. A `4` whose message starts with
-"Performed" means the action happened and only the picture is missing: take a
-`screenshot`, never send the action again to get it. As with
-`screenshot --out -`, a terminal on stdout is refused.
+## End to end
 
-Coordinates are pixels on the same screenshot you just read. The runner serves one see-or-act request at a time, so never have two in flight; when the next few steps are already known, send them as one `runner actions` sequence instead of one request after another. Bounds are checked before anything is sent, so an over-long `--text` or an out-of-range coordinate comes back immediately naming the limit instead of occupying the runner and then failing.
+Run from a directory holding a flow and a `package.json`. The run is what starts the screen, so it is not optional even though the goal here is to drive by hand.
 
-`act`, `actions`, `run` and `exec` are the commands whose lost answer may still have taken effect. On a `4` from `act` or `actions`, take a screenshot before repeating a click. `exec`'s message says the snippet could not be evaluated, but a lost answer looks the same from outside, so treat a `4` from a snippet that changes something as "may have run" rather than "did not run".
+```sh
+export QAWOLF_API_KEY=...          # the only credential
+export QAWOLF_RUNNER_ID=agent-1    # so no command below needs --runner
 
-A mobile runner has a touchscreen, not a mouse, so it has actions of its own:
+qawolf runner launch --id agent-1 --json          # --id, not the variable; read .alreadyRunning and .url
+qawolf runner run flows/smoke.flow.ts --follow    # starts the screen; exit 1 if it failed
 
-- `tap` touches a point (`--x`, `--y`) or the element `--selector` names. Check the selector first with `inspect elements --selector`, and pass `--strategy ios-predicate` or `shadow` when it is not XPath.
-- `swipe --from x,y --to x,y` moves in a straight line between two points. `--duration-ms` sets how long it takes, up to 10000: a slow swipe scrolls, a fast one flings.
-- `fill --selector ... --text ...` replaces the value of that field, and `--text ""` clears it. To add to what a field already holds, `tap` it and then `type`.
-- `type` types into whatever the last tap focused, the same as on a browser.
+qawolf runner act navigate --url https://example.com/login --screenshot step-1.jpg   # then read step-1.jpg yourself
+qawolf runner act click --button left --x 480 --y 260 --screenshot step-2.jpg
+qawolf runner act type --text "someone@example.com" --screenshot step-3.jpg
 
-The browser actions `double_click`, `scroll`, `move`, `keypress` and `navigate` answer `action-not-supported-on-mobile` rather than doing something approximate. `navigate` is the one to watch for, since it works on a browser runner without a run first but has no meaning on mobile at all. `click` with `button: "left"` and `drag` still tap and swipe on mobile, but they are deprecated there, so send `tap` and `swipe`. A browser runner answers `tap`, `swipe` and `fill` with `action-not-supported-on-browser`.
+qawolf runner inspect element-html --selector "#email"
+qawolf runner inspect variable --name cart | jq .total
 
-### Several steps in one request: `runner actions`
+qawolf runner run flows/smoke.flow.ts --lines 12-40 --follow   # just those lines
+qawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'
+qawolf runner terminate
+```
 
-`qawolf runner actions '<json array>'` performs up to ten of the browser actions back to back in one request (not `tap`, `swipe` or `fill`), for the steps you already know: click the field, type into it, press Enter. One round trip instead of three, with no delay to guess at between them, and `-` reads the array from stdin the way `act -` reads one action.
+On a mobile runner, launch with `--name android` or `--name ios`, and drive it with `tap`, `swipe`, `fill` and `type` instead of the browser actions.
 
-```sh
-qawolf runner actions '[{"type":"click","button":"left","x":480,"y":260},{"type":"type","text":"me@example.com"},{"type":"keypress","keys":["Enter"]}]' --screenshot after-login.jpg
+```text
+Usage: qawolf runner [options] [command]
+
+Drive an interactive runner on the QA Wolf platform
+
+Options:
+  -h, --help                               display help for command
+
+Commands:
+  launch [options]                         Launch an interactive runner and make it this directory's
+                                           default
+  list [options]                           List the runners running on your team
+  terminate [options]                      End an interactive runner, and the pod it runs on with it
+  stop-run [options]                       Stop what a runner is currently executing, leaving the
+                                           runner up
+  keepalive [options]                      Reset a runner's inactivity clock, for a caller that
+                                           pauses between actions
+  run [options] <flowFile>                 Run a flow on an interactive runner, shipping the flow
+                                           and what it imports
+  events [options] <stream>                Print a runner's journal, one entry per line. QA Wolf
+                                           writes console, recorder, run-events, run-logs,
+                                           run-status
+  screenshot [options]                     Save a JPEG of an interactive runner's screen to a file,
+                                           or write it to stdout with --out -
+  act [options] <action>                   Perform one raw action on a runner's screen. A browser
+                                           runner takes click, double_click, scroll, move, drag,
+                                           keypress, navigate and type; a mobile runner takes tap,
+                                           swipe, fill and type. A browser runner answers mobile
+                                           actions with action-not-supported-on-browser; a mobile
+                                           runner answers the other browser actions with
+                                           action-not-supported-on-mobile. Use - to read a whole
+                                           action as JSON from stdin
+  actions [options] <sequence>             Perform a sequence of up to ten raw actions on a runner's
+                                           screen in one request, as a JSON array of the same
+                                           actions `runner act` takes. Use - to read the array from
+                                           stdin. Actions run back to back, so batch only steps
+                                           whose targets are on the screen you last saw, and end the
+                                           sequence at the step that changes the page. Each result
+                                           carries an effect: performed, not-performed, or unknown
+                                           when the runner stopped answering and the action may have
+                                           landed
+  exec [options] <file>                    Evaluate a snippet against a runner's live page. Use - to
+                                           read the snippet from stdin
+  inspect                                  Read one thing off a runner's live page (browser) or
+                                           Appium session (mobile)
+  import-package [options] <name>          Install a package into a runner's live run, so a snippet
+                                           or a selection can import it
+  highlight-selector [options] [selector]  Highlight what a selector matches on a runner's live
+                                           page, so the next screenshot shows it. Omit the selector
+                                           to clear the highlight
+  promote-snapshot [options]               Accept a run's screenshot as the new baseline for an
+                                           image diff, on the runner that produced it
+  record                                   Control video recording on a Playwright runner
+  list-recordings [options]                Read a page of published video recordings, including
+                                           after the runner terminates. Platform URLs persist; video
+                                           URLs expire
+  help [command]                           display help for command
 ```
 
-Batch only steps whose targets are all on the screen you last saw and are not moved by the steps before them, and make the step that changes the page — a submit, a navigation, opening a menu — the last one. Then read the frame and decide the next batch from it.
+## qawolf runner launch
 
-`--screenshot after.jpg` writes the screen after the last action, as `act --screenshot` does, and `-` puts those bytes on stdout with the confirmation on stderr. Stdout then carries the image and nothing else, so `-` trades the per-action results below for the frame: give `--screenshot` a file path whenever you need to read `effect` per action. `--screenshot-mode each --screenshot step.jpg` writes one frame per action instead, `step-0.jpg`, `step-1.jpg` and so on; each is a full image, so keep those sequences short.
+```text
+Usage: qawolf runner launch [options]
+
+Launch an interactive runner and make it this directory's default
+
+Options:
+  --id <id>        Id to launch under. Relaunching an id attaches to that runner
+  --name <family>  Runner family to run, e.g. playwright
+  -h, --help       display help for command
+
+Examples:
+  $ qawolf runner launch
+  $ qawolf runner launch --name android
+  $ qawolf runner launch --id ci
+
+Ids:
+  Runner ids are yours to choose and are scoped to your team, so agent-1 is a
+  fine id. Launching an id that is already running attaches to that runner
+  instead of starting and billing a second one, and the answer says which
+  happened: read `alreadyRunning`. Reusing one id is therefore the cheap and
+  safe pattern. The same id with a different --name is refused rather than
+  silently ignored.
+
+  launch takes its id from --id and never reads QAWOLF_RUNNER_ID. A bare `qawolf
+  runner launch` invents a random id, bills a pod under it and stores it, so a
+  harness that exported the variable and then launched without --id ends up with
+  a pod it is not addressing. Pass --id whenever you have an id in mind.
+
+  Launching an id that differs from QAWOLF_RUNNER_ID prints a warning on stderr
+  naming both ids: the variable still outranks the directory default, so
+  commands that omit --runner keep going to whatever it names, not the runner
+  you just launched. That is expected when you launch an additional runner on
+  purpose. Address that one with --runner rather than re-exporting the variable,
+  which would repoint every other runner-less command too.
+
+The page:
+  Either answer carries a `url`, which launch prints, as does a command that
+  launched its own runner. It is a QA Wolf page showing what the runner is
+  doing, where a person can also take over with their own mouse and keyboard.
+  Hand it to a person who asks what your runner is up to. The page opens for
+  anyone on the runner's team, however the runner was launched. There is nothing
+  to see until the runner's first run starts its screen, so the page waits until
+  then. You read the screen with `screenshot`, not with the page.
+
+Browser or mobile:
+  --name also chooses between a browser and a mobile device: --name android or
+  --name ios starts an Appium session instead of a browser. A command built for
+  the other kind answers a failureReason naming the mismatch rather than doing
+  something approximate: runner-is-not-mobile from inspect session, contexts,
+  page-source and elements on a browser runner, and runner-is-not-a-browser from
+  inspect element-html and page-html on a mobile one. Launch the right family up
+  front rather than discovering it from a refusal mid-session.
+```
 
-The answer holds one entry per action reached, and the field to read on each is `effect`:
+## qawolf runner list
 
-- `performed` means the runner did it.
-- `not-performed` means the runner answered that it did not take effect.
-- `unknown` means the runner stopped answering with the action in flight, or its screen went quiet mid-action, so it may have taken effect. Take a screenshot before repeating anything from that step on, and never send it again blind.
+```text
+Usage: qawolf runner list [options]
 
-The sequence stops at the first action that fails. `--continue-on-failure` carries on past one that reached the runner and did not take effect, which is only safe for actions that do not depend on each other: a `type` after a failed `click` goes to whatever has focus. A runner that cannot be reached, a screen that cannot serve, or running out of time ends the sequence either way, and the message names every action that did not succeed.
+List the runners running on your team
 
-## Video recording
+Options:
+  --here      Only the runners this directory launched
+  -h, --help  display help for command
 
-Use `record` to control video capture on a Playwright runner. Start a flow first
-so the runner has a screen, then start a manual capture:
+Examples:
+  $ qawolf runner list
+  $ qawolf runner list --here
+  $ qawolf runner list --json
 
-```sh
-qawolf runner record start --runner ci --json
-# Keep result.state.active.id from the response and use it to stop this capture:
-qawolf runner record stop <recording-id> --runner ci
-qawolf runner record status --runner ci
-qawolf runner record auto on --runner ci
-qawolf runner record auto off --runner ci
-```
+What the list holds:
+  The list names the runners this directory has launched that are still running,
+  and marks the one a command with no --runner would reach. It also includes the
+  runner named by QAWOLF_RUNNER_ID even though this directory did not launch it,
+  so a harness handed a runner sees it alongside the ones it started itself. Use
+  the id column with --runner to address any of them; addressing one does not
+  make it the default.
 
-Start generates a UUID unless you pass `--recording-id <uuid>`. If a start
-response is lost, the error includes that UUID: check `record status` and reuse
-the UUID when retrying. Stop always names a specific recording, so retrying it
-cannot stop a later capture. Manual recordings span runs and suppress automatic
-capture until stopped. The auto setting affects subsequent full runs.
-An active automatic recording ends with its run; `record stop` cannot interrupt
-it. If a stop publishes a recording with `status: "failed"`, the CLI returns
-exit code 1 and still prints the manifest so callers can inspect it.
+  Every runner is looked up before it is listed, so a runner that idled out is
+  absent rather than reported. The lookup neither starts a runner nor resets an
+  inactivity clock, which is what separates list from keepalive: listing tells
+  you what is there and changes nothing. A lookup that cannot be answered fails
+  the command rather than returning a shorter list, because a short list reads
+  as the whole truth.
 
-Published recordings remain accessible after the runner terminates:
+  Nothing is billed by listing, but everything in the list is billing. Terminate
+  what you are done with.
 
-```sh
-qawolf runner list-recordings --runner ci --json
-qawolf runner list-recordings --runner ci --recording-id <uuid> --json
-qawolf runner list-recordings --runner ci --page-token '<nextPageToken>' --json
+  The table leaves out the page address, which beside a 63-character id outgrows
+  a terminal. --json carries it as `url` on every runner:
+
+  $ qawolf runner list --json | jq -r '.[] | [.id, .url] | @tsv'
 ```
 
-Each response is one page with `recordings` and an optional `nextPageToken`.
-Follow that token for more; the order is storage-key order, not newest-first.
-Entries include status, run ids, a stable platform `url`, and an expiring
-`videoUrl` when video is available. An empty lookup means the recording has not
-been published or does not exist. Abrupt runner loss may leave video unavailable.
-Keep the runner id for history lookups after termination clears the local default.
+## qawolf runner terminate
 
-## The recorder: what you cannot get from pixels
+```text
+Usage: qawolf runner terminate [options]
+
+End an interactive runner, and the pod it runs on with it
+
+Options:
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
+
+Stopping a run or ending a runner:
+  Two different things, and the names are the only warning you get:
+  - stop-run stops what the runner is executing and leaves the runner up, its
+    browser on whatever page the run reached. The run settles as stopped rather
+    than passed or failed. Use it to abandon a run and keep the browser you were
+    working against.
+  - terminate ends the runner and the pod with it. Everything on it is gone, and
+    the next command under that id launches and bills a new one.
+
+  Both succeed when there was nothing to do, and say which: `wasRunning` is
+  false when no run was going, and when no runner was running. Neither is an
+  error, so a retry needs no special handling. terminate never launches a runner
+  in order to end it.
+```
 
-`qawolf runner events recorder` is the capability that has no equivalent in a
-screenshot. As you drive the browser, the runner records each interaction and
-publishes `locator` (the real Playwright locator it resolved), `alternates` (the
-others that matched the same element) and `code` (the generated Playwright call),
-alongside `type`, `sourceUrl` and `timestamp`.
+## qawolf runner stop-run
 
-```sh
-qawolf runner events recorder --tail 5 | jq -r '.code // .type'          # what happened
-qawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'
+```text
+Usage: qawolf runner stop-run [options]
+
+Stop what a runner is currently executing, leaving the runner up
+
+Options:
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
+
+Stopping a run or ending a runner:
+  Two different things, and the names are the only warning you get:
+  - stop-run stops what the runner is executing and leaves the runner up, its
+    browser on whatever page the run reached. The run settles as stopped rather
+    than passed or failed. Use it to abandon a run and keep the browser you were
+    working against.
+  - terminate ends the runner and the pod with it. Everything on it is gone, and
+    the next command under that id launches and bills a new one.
+
+  Both succeed when there was nothing to do, and say which: `wasRunning` is
+  false when no run was going, and when no runner was running. Neither is an
+  error, so a retry needs no special handling. terminate never launches a runner
+  in order to end it.
 ```
 
-`code` is absent on events with no call of their own, such as a navigation, which
-is why the first line falls back to `type`. Use these to turn a session you drove
-by pixel coordinates into durable selectors, and to check that a click landed on
-the element you meant rather than near it. The stream is empty until the session
-has a browser context, so an early empty answer means "not yet", not "broken".
-Do not add `--json` here: it wraps each line in an envelope and these field paths
-stop matching.
+## qawolf runner keepalive
 
-## Reading the page: `inspect`
+```text
+Usage: qawolf runner keepalive [options]
+
+Reset a runner's inactivity clock, for a caller that pauses between actions
+
+Options:
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
+
+Examples:
+  $ qawolf runner keepalive
+  $ qawolf runner keepalive --runner ci
+
+When to call it:
+  A runner is reaped after a period of inactivity, and every command that talks
+  to the runner counts as activity, including a journal read. keepalive exists
+  for the gap that creates: a harness that thinks, or waits on a human, for
+  minutes between actions would otherwise come back to a pod that is gone. It
+  resets the clock and tells you the runner is still there. It never launches a
+  runner.
+
+  It is a read with a cost: keeping the clock reset keeps a billed pod alive.
+  Call it while you are genuinely still working, not on a timer you forget, and
+  call `qawolf runner terminate` when you are done rather than leaving a pod to
+  time out. A loop that keeps a runner alive and never stops it bills until
+  someone notices.
+```
 
-`qawolf runner inspect` answers one question about the live page and prints the
-answer on stdout by itself, so you can redirect or pipe it:
+## qawolf runner run
 
-```sh
-qawolf runner inspect element-html --selector "#email"
-qawolf runner inspect page-html > page.html
-qawolf runner inspect page-html --selector "#cart"      # just that subtree
-qawolf runner inspect variable --name cart | jq .total
+```text
+Usage: qawolf runner run [options] <flowFile>
+
+Run a flow on an interactive runner, shipping the flow and what it imports
+
+Options:
+  --follow             Report the run's status until it settles: in progress, then passed or failed
+                       (default: false)
+  --logs               Stream every log line the run produces while following. Implies --follow
+                       (default: false)
+  --run-events         Stream the run's progress events as JSON lines while following. Implies
+                       --follow (default: false)
+  --recorder-events    Stream the browser actions the runner records as JSON lines while following,
+                       from an anchor taken just before submission: the recorder is runner-wide, not
+                       run-scoped. Implies --follow (default: false)
+  --env-id <env>       QA Wolf environment whose variables the run is given, by id or alias.
+                       Defaults to QAWOLF_ENVIRONMENT. QA Wolf reads and decrypts them itself, so
+                       they never leave the server and no size limit applies to them
+  --env-file <path>    Dotenv file on this machine whose variables the run is given. Pass this or
+                       --env-id, not both
+  --lines <start-end>  Run only these 1-indexed lines against the browser as it stands, instead of
+                       the whole flow from a fresh one
+  --lines-file <path>  File the --lines range lives in. Defaults to <flowFile>; pass it only when
+                       the lines are in another file, such as a page object
+  --runner <id>        Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored
+                       runner
+  --timeout <seconds>  Give up following after this long. Following keeps the runner alive, so a run
+                       that never settles would otherwise bill until the terminal closed (default:
+                       "3600")
+  -h, --help           display help for command
+
+Examples:
+  $ qawolf runner run flows/checkout.flow.ts
+  $ qawolf runner run flows/checkout.flow.ts --follow
+  $ qawolf runner run flows/checkout.flow.ts --follow --logs
+  $ qawolf runner run flows/checkout.flow.ts --lines 12-40
+  $ qawolf runner run flows/checkout.flow.ts --lines 4-9 --lines-file pages/login.ts
+  $ qawolf runner run flows/checkout.flow.ts --env-id staging
+
+What travels:
+  run ships the flow file, everything it imports, and your package.json and
+  tsconfig.json. Nothing else travels, so you can run from the root of a large
+  project without sending it. The runner holds no copy of your project, so what
+  runs is exactly what is on disk at that moment, uncommitted edits included.
+
+  Imports are followed the same way a run from the QA Wolf app follows them:
+  relative paths and tsconfig.json path aliases, resolving .ts and .js. An
+  `export ... from` re-export is not followed, and neither is require(), so a
+  barrel file does not pull in what it re-exports. A package.json has to be
+  there, since the run reads its npm dependencies from it, and the files may
+  carry at most 30 MiB in total. A missing file, a missing package.json and
+  files over the cap are all refused before any runner is resolved or launched,
+  so a typo costs nothing.
+
+  After the first run on a runner, later runs send only the files whose content
+  changed, so iterating on one flow costs a small request rather than the whole
+  graph again. --json reports which happened in `fileSync`: delta or full.
+  Nothing about this needs managing: the baseline lives in
+  .qawolf/runner-files.json, a switch to another runner ignores it, and a runner
+  that turns out not to hold what was claimed gets the whole set resent
+  automatically.
+
+Waiting for the outcome:
+  The call answers with a run id as soon as the run is accepted. The outcome is
+  not in that answer; it is in the run-status stream, whose entries carry
+  `runId`, `status` and an `errorMessage` when there is one.
+
+  Pass --follow and let run wait for you. It reports the run's status, in
+  progress, then passed or failed, and ends on the settled status. Exit 1 means
+  the run did not pass. --logs, --run-events and --recorder-events mirror more
+  streams into the follow, and each implies --follow on its own. The recorder is
+  runner-wide rather than run-scoped, so --recorder-events carries whatever is
+  recorded after an anchor taken just before submission. Whatever mirrors are
+  on, the follow still ends on the status, never on them, so a run that prints
+  nothing still ends the follow and a run that dies mid-sentence still reports
+  how. Combining mirror flags interleaves their lines with nothing saying which
+  stream a line came from: fine for eyeballs; when parsing, follow one stream at
+  a time.
+
+  To submit and come back later, poll with the same rule the CLI uses: `status`
+  is in-progress while the run is going, and any other value means it has
+  settled. `events --follow` does not end when the run settles, so it cannot be
+  used to wait for one.
+
+  $ qawolf runner run flows/checkout.flow.ts --json
+  $ qawolf runner events run-status --run <runId> --tail 1 | jq -r '.status'
+
+When the runner could not be reached:
+  If run reports that the runner could not be reached, that does not mean the
+  run did not start. The runner may have accepted it and been too slow to
+  answer, and resubmitting bills and journals a second run.
+
+  There is no clean recovery. The journal lives on the same pod, so while the
+  runner stays unreachable a run-status read fails the same way. Wait for the
+  runner to answer again, then read run-status without --run and look at the
+  newest `runId`. Nothing ties that id back to your submission, and a runner
+  takes work from anyone addressing it, so treat the newest id as your run only
+  if you know nothing else submits to this runner. An empty read is not proof
+  the run did not start either: run returns the moment the run is accepted, and
+  its first run-status entry may not be written yet. A resubmit always risks a
+  second billed run, so prefer polling run-status a while longer, and only
+  submit again once you are willing to accept that risk.
+
+Running part of a flow:
+  --lines 12-40 runs those lines against the browser as it stands, so nothing is
+  re-navigated and nothing is signed in again. Use it to iterate on a step
+  without paying for the whole flow to reach it again.
+
+  The two file paths are the thing to get right, because getting them backwards
+  runs the wrong code and nothing reports it:
+  - the positional is always the flow file. It is the run's entry point, and it
+    is required for every run, selection or not.
+  - --lines-file is where the lines live. It defaults to the positional, so pass
+    it only when the range is in another file, typically a page object whose
+    method you want to run against the instance your last run left alive.
+
+  The lines-file has to be one of the files that travel, so it lives under the
+  directory you run from. A range whose file is not collected is refused before
+  a runner is addressed, naming the path.
+
+  A --lines selection is the one call that does not need a run first. If the
+  runner had no browser, one is started before your lines run, and the command
+  says so on stderr. Those lines then ran against a fresh page rather than the
+  one an earlier run left, which is worth reading before you act on what you
+  see.
+
+Environment variables:
+  A run takes one of two. --env-id names a QA Wolf environment by id or alias,
+  the same reference `qawolf flows` takes as --env. --env-file .env gives the
+  run the variables in a dotenv file, in the format `qawolf flows pull` writes.
+  Passing both is refused: each gives the run its whole environment, so there is
+  no order in which they would combine.
+
+  A run with neither flag falls back to QAWOLF_ENVIRONMENT, the same variable
+  `qawolf flows` reads, so one export covers both. The run says on stderr which
+  environment it picked up, because those variables reach your flow's code and a
+  run should never be given an environment silently. --env-id wins over it, and
+  --env-file suppresses it, so a run reading a dotenv file is not handed a
+  second environment on top.
+
+  Prefer --env-id. QA Wolf reads and decrypts the environment itself, so the
+  values never leave the server, nothing has to be pulled to disk first, and no
+  size limit applies to them. It is the only way to run a flow whose environment
+  holds something large, such as a session cookie.
+
+  A run that sends its own variables with --env-file may carry at most 200 of
+  them, each value at most 16 KiB. Names follow what a shell accepts, and
+  QAWOLF_TEAM_ID is reserved because QA Wolf sets it from the key you
+  authenticated with. All of that is refused before a runner is addressed,
+  naming the variable at fault.
 ```
 
-`page-html` is simplified for a model to read rather than being the browser's
-exact markup. `variable` reads a top-level variable of the running workflow and
-prints it as JSON, which is how you see what your own code computed rather than
-what the page shows.
+## qawolf runner events
 
-One failure covers three causes, because a runner cannot tell them apart: no
-live page, no element matching the selector, no variable under that name. All
-three exit `2` and none clears by waiting, so read the message, which carries
-whatever the runner said. An unreachable runner exits `4` and is worth retrying;
-a runner that is not running at all exits `8` and is not.
+```text
+Usage: qawolf runner events [options] <stream>
+
+Print a runner's journal, one entry per line. QA Wolf writes console, recorder, run-events,
+run-logs, run-status
+
+Options:
+  --follow             Keep reading as new entries arrive. Reading counts as activity, so a follow
+                       left open keeps the runner alive and billing (default: false)
+  --run <id>           Restrict run-scoped streams to one run
+  --runner <id>        Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored
+                       runner
+  --since <sequence>   Read entries after this sequence
+  --tail <count>       Read only the newest <count> entries
+  --timeout <seconds>  Give up following after this long. Reading keeps the runner alive, so a
+                       follow left open would otherwise bill until the terminal closed (default:
+                       "3600")
+  -h, --help           display help for command
+
+Examples:
+  $ qawolf runner events recorder --tail 5
+  $ qawolf runner events run-logs --run <runId> --follow
+  $ qawolf runner events console --since 120 --json
+
+Streams:
+  Everything observable is an append-only stream on the pod, read by cursor or
+  tail rather than subscribed to, so attaching late still gets you the history
+  that is still there. QA Wolf writes recorder, console, run-events, run-logs
+  and run-status; a stream nobody has written reads as empty rather than as an
+  error, and a stream this CLI version does not know about is still readable by
+  name. One payload per line, so shell tools compose:
+
+  $ qawolf runner events console --tail 20 | jq -r '.message'
+  $ qawolf runner events run-logs --run <runId> --follow > run.log
+
+  --tail N takes the newest N, --since <sequence> reads everything after a
+  cursor, and --run <id> narrows the run-scoped streams.
+
+  History is not unbounded: a size cap drops the oldest entries on a long-lived
+  runner, and a --tail N read can stop early and hand back fewer than N even
+  when more matched. Both are warned about on stderr, dropped entries only once
+  a read holds a cursor, a stopped-early read with a pointer at --since. Watch
+  stderr, treat a short answer as "at least this" rather than "all there was",
+  and read what you care about as you go rather than at the end.
+
+The recorder:
+  `events recorder` is what has no equivalent in a screenshot. As you drive the
+  browser, the runner records each interaction and publishes `locator` (the real
+  Playwright locator it resolved), `alternates` (the others that matched the
+  same element) and `code` (the generated Playwright call), alongside `type`,
+  `sourceUrl` and `timestamp`:
+
+  $ qawolf runner events recorder --tail 5 | jq -r '.code // .type'
+  $ qawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'
+
+  `code` is absent on events with no call of their own, such as a navigation,
+  which is why the first line falls back to `type`. Use these to turn a session
+  you drove by pixel coordinates into durable selectors, and to check that a
+  click landed on the element you meant rather than near it. The stream is empty
+  until the runner's first run gives it a browser context, so an early empty
+  answer means "not yet", not "broken". Do not add --json here: it wraps each
+  line in an envelope and these field paths stop matching.
+
+Following:
+  --follow polls and prints as entries arrive. It is tail -f with a bound: it
+  ends only at its --timeout (an hour by default, exit 6), because reading keeps
+  the runner alive and billing. It does not end when a run settles, so it cannot
+  be used to wait for a run: use `runner run --follow`, or poll run-status.
+  Redirect it to a file and stop it yourself, or use repeated --since reads when
+  you need the command to end sooner.
+
+  Where --follow wins is the cursor. The pod reports how far a read scanned
+  rather than how far it matched, and --follow carries that number, so a
+  filtered read that matched nothing still moves forward. A caller paging by
+  hand cannot see it, because the CLI does not print it, and the best available
+  substitute is the highest `sequence` you actually saw. So a narrow --run
+  filter over a busy stream stalls: with nothing matching, there is no new
+  `sequence` to move on to, and you re-read the same window until something
+  matches.
+
+  events never launches a runner.
+```
 
-Use `inspect` before reaching for `exec`. Reading a value through a snippet
-means printing it and then fishing it back out of the `console` stream, which is
-two calls and a marker; `inspect variable` is one call and the value.
+## qawolf runner screenshot
 
-## Reading a mobile screen: `inspect session`/`contexts`/`page-source`/`elements`
+```text
+Usage: qawolf runner screenshot [options]
+
+Save a JPEG of an interactive runner's screen to a file, or write it to stdout with --out -
+
+Options:
+  --out <path>   File to write the image to. - writes the JPEG bytes to stdout on their own and
+                 moves the confirmation, JSON included, to stderr (default: "screenshot.jpg")
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
+
+Examples:
+  $ qawolf runner screenshot
+  $ qawolf runner screenshot --out screens/step-3.jpg
+  $ qawolf runner screenshot --out - > step-3.jpg
+  $ qawolf runner screenshot --out - | my-vision-tool
+
+Reading the screen:
+  The image is a real JPEG on disk, decoded, because every coding harness can
+  open an image file. Read it with whatever vision you have. --out - writes the
+  JPEG bytes to stdout instead, on their own, for a caller that is a process
+  rather than an agent: the confirmation, and the JSON line under --json, goes
+  to stderr so nothing follows the image on stdout. A terminal on stdout is
+  refused: redirect or pipe it.
+
+  A runner has no screen until its first run, so until then screenshot exits 2.
+  It never launches a runner. When you are about to act anyway, `act
+  --screenshot` performs the action and returns the screen in one call.
+```
 
-`element-html`, `page-html` and `variable` are a browser's shapes. A mobile
-runner answers four different ones instead, one subcommand per question:
+## qawolf runner act
 
-```sh
-qawolf runner inspect session
-qawolf runner inspect contexts
-qawolf runner inspect page-source
-qawolf runner inspect page-source --context WEBVIEW_1     # a specific context, not the current one
-qawolf runner inspect elements --x 240 --y 480
-qawolf runner inspect elements --text "Sign in" --partial
-qawolf runner inspect elements --selector "//android.widget.Button[@text='Sign in']"
-qawolf runner inspect elements --selector "@label == 'Sign in'" --strategy ios-predicate
+```text
+Usage: qawolf runner act [options] <action>
+
+Perform one raw action on a runner's screen. A browser runner takes click, double_click, scroll,
+move, drag, keypress, navigate and type; a mobile runner takes tap, swipe, fill and type. A browser
+runner answers mobile actions with action-not-supported-on-browser; a mobile runner answers the
+other browser actions with action-not-supported-on-mobile. Use - to read a whole action as JSON from
+stdin
+
+Options:
+  --button <button>      click: left, right, wheel, back or forward
+  --duration-ms <ms>     swipe: how long it takes, up to 10000. Slow scrolls, fast flings
+  --from <x,y>           swipe: the point it starts at
+  --keys <keys...>       keypress: modifiers and the key, e.g. Control a
+  --path <json>          drag: JSON array of points to drag through
+  --runner <id>          Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's
+                         stored runner
+  --screenshot <path>    Also save a JPEG of the screen, taken after the action, to this file, in
+                         place of a separate screenshot. An action that did not take effect answers
+                         with one too. - writes it to stdout and moves the confirmation, JSON
+                         included, to stderr
+  --scroll-x <delta>     scroll: horizontal wheel delta
+  --scroll-y <delta>     scroll: vertical wheel delta
+  --selector <selector>  tap or fill: the element to act on, as a screen object would find it. tap
+                         takes it in place of --x and --y
+  --strategy <strategy>  how --selector is resolved: xpath (default), ios-predicate or shadow
+  --text <text>          type: the text to type into what has focus. fill: the field's new value
+  --to <x,y>             swipe: the point it ends at
+  --url <url>            navigate: the http or https URL to go to
+  --x <pixels>           click, tap and the like: x, in screenshot pixels
+  --y <pixels>           click, tap and the like: y, in screenshot pixels
+  -h, --help             display help for command
+
+Examples:
+  $ qawolf runner act click --button left --x 480 --y 260
+  $ qawolf runner act type --text "hello@example.com"
+  $ qawolf runner act keypress --keys Control a
+  $ qawolf runner act navigate --url https://example.com
+  $ qawolf runner act drag --path '[{"x":10,"y":20},{"x":80,"y":90}]'
+  $ qawolf runner act click --button left --x 480 --y 260 --screenshot step-4.jpg
+  $ echo '{"type":"click","button":"left","x":1,"y":2}' | qawolf runner act -
+  $ echo '{"type":"click","button":"left","x":1,"y":2}' | qawolf runner act - --screenshot - > step-5.jpg
+
+Mobile:
+  $ qawolf runner act tap --x 540 --y 1200
+  $ qawolf runner act tap --selector '//*[@content-desc="Continue"]'
+  $ qawolf runner act fill --selector 'name == "Postal code"' --strategy ios-predicate --text 94107
+  $ qawolf runner act swipe --from 540,1600 --to 540,600 --duration-ms 1500
+
+Seeing and acting:
+  There is no hosted vision loop: you look with screenshot, decide with your own
+  model, and act. act performs exactly one action per call, in the computer-use
+  tool vocabulary a vision model already emits. The names and the field names
+  are unchanged from that vocabulary on purpose, so you can forward a tool call
+  rather than translate it with `act -`.
+
+  Every action in a see-and-act loop is followed by a look at the result, so ask
+  for it in the same call with --screenshot. Prefer it over act and then
+  screenshot: each step is one call instead of two, with no delay to guess at
+  between them. The screen the runner answers with is taken once it has changed
+  from just before the action or half a second has passed, whichever comes
+  first. An action that reached the screen and did not take effect answers with
+  one too, so an exit 1 still leaves you a picture of why the click missed. A 4
+  whose message starts with "Performed" means the action happened and only the
+  picture is missing: take a screenshot, never send the action again to get it.
+  As with `screenshot --out -`, a terminal on stdout is refused.
+
+  Coordinates are pixels on the same screenshot you just read. The runner serves
+  one see-or-act request at a time, so never have two in flight; when the next
+  few steps are already known, send them as one `runner actions` sequence
+  instead. Bounds are checked before anything is sent, so an over-long --text or
+  an out-of-range coordinate comes back immediately naming the limit.
+
+  On a 4, the answer may have been lost with the action in flight: take a
+  screenshot before repeating a click, and repeat only what the screen says did
+  not happen.
+
+Mobile:
+  A mobile runner has a touchscreen, not a mouse, so it has actions of its own:
+  - tap touches a point (--x, --y) or the element --selector names. Check the
+    selector first with `inspect elements --selector`, and pass --strategy
+    ios-predicate or shadow when it is not XPath.
+  - swipe --from x,y --to x,y moves in a straight line between two points.
+    --duration-ms sets how long it takes, up to 10000: a slow swipe scrolls, a
+    fast one flings.
+  - fill --selector ... --text ... replaces the value of that field, and --text
+    "" clears it. To add to what a field already holds, tap it and then type.
+  - type types into whatever the last tap focused, the same as on a browser.
+
+  On mobile, send tap and swipe, never click or drag. The other browser actions,
+  double_click, scroll, move, keypress and navigate, answer
+  action-not-supported-on-mobile rather than doing something approximate.
+  navigate is the one to watch for, since it works on a browser runner without a
+  run first but has no meaning on mobile at all. A browser runner answers tap,
+  swipe and fill with action-not-supported-on-browser.
+
+Before the first run:
+  A runner has no screen until its first run, so act exits 2 until then, except
+  navigate, which exits 1 (action-failed): it skips the screen but still needs
+  the runner to have run something. With no runner named at all, act launches
+  one and says so on stderr.
 ```
 
-`session` prints one summary line — ready, or why not — because that line is
-the whole answer. `contexts`, `page-source` and `elements` instead print their
-answer as JSON on stdout, on its own like `inspect element-html`, so you can
-redirect or pipe it (`| jq .current`, `| jq .matches`, `| jq .pageSource`)
-rather than getting a count with no way to see what was actually found.
-
-`session` is also the one subcommand that never answers `screen-needs-a-run`:
-readiness is the question it exists to answer, so it reports one of `ready`
-(with the platform, device and session id), `unreachable`, `ambiguous` (more
-than one session is somehow live) or `no-session`, rather than refusing until a
-run has happened. The other three need a live session first and share the same
-readiness contract `act` and `screenshot` use on a browser runner:
-`screen-needs-a-run` exits `2` and means no Appium session has started on this
-runner yet — run a flow that opens one, then inspect again; `screen-not-ready`
-exits `4` and means the session exists but did not answer this instant, or more
-than one is somehow live — retry once, and relaunch the runner if it persists.
-
-`elements` takes one of three ways to search: whole-pixel `--x`/`--y` on the
-device's own screen, the same coordinates a screenshot is measured in;
-`--text`, which matches exactly unless `--partial` is passed; or `--selector`,
-resolved the same way a screen object's own selector is, with `--strategy`
-naming how (`xpath`, `ios-predicate` or `shadow`; defaults to `xpath`). Prefer
-`--selector` when checking a selector you are about to write: it answers what
-that exact string resolves to, where `--text`/`--x`/`--y` only approximate it.
-The three do not mix — passing flags from more than one at once is refused
-before a runner is addressed rather than silently searching by whichever one
-it picked. An unparseable selector answers `invalid-selector`, exit `2`,
-distinctly from a selector that parsed fine but matched nothing, which answers
-an empty `matches` list, exit `0` — the same distinction `highlight-selector`
-draws on a browser runner. `--context` on `page-source` or `elements` reads a
-context other than the current one — useful once `contexts` has told you which
-are available.
-
-A browser runner answers `runner-is-not-mobile` to all four, exit `2`, since
-retrying never helps: launch with `--name android` or `--name ios` instead.
-`runner-unreachable` exits `4` and is worth retrying, same as everywhere else
-on this surface.
-
-## Checking a selector: `highlight-selector`
-
-`inspect element-html` tells you what a selector matched. `highlight-selector`
-shows you _where_ it is, by drawing on the page itself:
+## qawolf runner actions
 
-```sh
-qawolf runner highlight-selector "text=Sign in"
-qawolf runner screenshot                          # the highlight is in this
-qawolf runner highlight-selector                  # omit the selector to clear
+```text
+Usage: qawolf runner actions [options] <sequence>
+
+Perform a sequence of up to ten raw actions on a runner's screen in one request, as a JSON array of
+the same actions `runner act` takes. Use - to read the array from stdin. Actions run back to back,
+so batch only steps whose targets are on the screen you last saw, and end the sequence at the step
+that changes the page. Each result carries an effect: performed, not-performed, or unknown when the
+runner stopped answering and the action may have landed
+
+Options:
+  --continue-on-failure     Carry on past an action that reached the runner and did not take effect;
+                            a runner that cannot be reached or a screen that cannot serve still ends
+                            the sequence
+  --runner <id>             Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's
+                            stored runner
+  --screenshot <path>       Save a JPEG of the screen after the last action to this file. With
+                            --screenshot-mode each, one file per action, with the action's index
+                            before the extension. - writes the final frame to stdout and moves the
+                            confirmation to stderr
+  --screenshot-mode <mode>  Defaults to final when --screenshot is given, none otherwise (choices:
+                            "none", "final", "each")
+  -h, --help                display help for command
+
+Examples:
+  $ qawolf runner actions '[{"type":"click","button":"left","x":480,"y":260},{"type":"type","text":"hello@example.com"},{"type":"keypress","keys":["Enter"]}]' --screenshot after-login.jpg
+  $ echo '[{"type":"click","button":"left","x":1,"y":2},{"type":"type","text":"hi"}]' | qawolf runner actions -
+  $ qawolf runner actions '[{"type":"click","button":"left","x":480,"y":260},{"type":"type","text":"hello"}]' --screenshot-mode each --screenshot step.jpg
+  $ qawolf runner actions '[{"type":"scroll","x":480,"y":260,"scroll_x":0,"scroll_y":600},{"type":"click","button":"left","x":120,"y":700}]' --continue-on-failure
+
+Mobile:
+  $ qawolf runner actions '[{"type":"tap","selector":"//*[@content-desc=\"Email\"]"},{"type":"type","text":"hello@example.com"},{"type":"tap","x":540,"y":1650}]' --screenshot after-login.jpg
+  $ qawolf runner actions '[{"type":"fill","selector":"name == \"Postal code\"","strategy":"ios-predicate","text":"94107"},{"type":"swipe","from":{"x":540,"y":1600},"to":{"x":540,"y":600}}]'
+
+Batching:
+  Use a sequence for the steps you already know: click the field, type into it,
+  press Enter. One round trip instead of three, with no delay to guess at
+  between them. On a mobile runner the steps are tap, swipe, fill and type, the
+  same as act, and a step the runner does not take fails with the same reason
+  act would give, action-not-supported-on-mobile or
+  action-not-supported-on-browser.
+
+  Batch only steps whose targets are all on the screen you last saw and are not
+  moved by the steps before them, and make the step that changes the page, a
+  submit, a navigation, opening a menu, the last one. Then read the frame and
+  decide the next batch from it.
+
+Screenshots:
+  --screenshot after.jpg writes the screen after the last action, as `act
+  --screenshot` does, and - puts those bytes on stdout with the confirmation on
+  stderr. Stdout then carries the image and nothing else, so - trades the
+  per-action results for the frame: give --screenshot a file path whenever you
+  need to read `effect` per action. --screenshot-mode each --screenshot step.jpg
+  writes one frame per action instead, step-0.jpg, step-1.jpg and so on; each is
+  a full image, so keep those sequences short.
+
+Reading the answer:
+  The answer holds one entry per action reached, and the field to read on each
+  is `effect`:
+  - performed means the runner did it.
+  - not-performed means the runner answered that it did not take effect.
+  - unknown means the runner stopped answering with the action in flight, or its
+    screen went quiet mid-action, so it may have taken effect. Take a screenshot
+    before repeating anything from that step on, and never send it again blind.
+
+  The sequence stops at the first action that fails. --continue-on-failure
+  carries on past one that reached the runner and did not take effect, which is
+  only safe for actions that do not depend on each other: a type after a failed
+  click goes to whatever has focus. A runner that cannot be reached, a screen
+  that cannot serve, or running out of time ends the sequence either way, and
+  the message names every action that did not succeed.
+
+Exit codes:
+  A sequence exits by the worst thing that happened to any one of its actions:
+  an effect nobody can confirm (4) first, then running out of time (6), then a
+  refusal (2), then an action that plainly did not happen (1). Whatever the
+  code, the message names the last action that took effect, and only what
+  follows it goes in a new request. A sequence also exits 2 before it sends
+  anything for an argument that is not a JSON array, an array of more than ten
+  actions, and --screenshot flags that contradict each other.
 ```
 
-The highlight stays until it is replaced or cleared, which is the point: you
-cannot see the runner's screen, so the only way to read the result is the next
-screenshot.
+## qawolf runner exec
 
-Three answers are worth telling apart. A selector that matched prints how many
-elements it hit and exits `0`. A selector the page read fine but that matched
-nothing also exits `0`, because the call did what was asked and the count is the
-answer; the message says the syntax was fine so you look at the page, not the
-locator. A selector the page could not read at all exits `2`, because that one
-is yours to correct and retrying will not change it.
+```text
+Usage: qawolf runner exec [options] <file>
+
+Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin
+
+Options:
+  --file <path>  File whose scope the snippet is evaluated in; it and the directory's other files
+                 travel with it
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
+
+Examples:
+  $ qawolf runner exec snippet.ts
+  $ echo 'console.log(await page.title())' | qawolf runner exec -
+  $ qawolf runner exec snippet.ts --file flows/checkout.flow.ts
+
+Getting a value back:
+  exec does not return what the snippet evaluated to, only whether it ran. To
+  get a value back, print it and read the `console` stream with `qawolf runner
+  events console`. Print it behind a marker you chose, and match on that rather
+  than taking the newest line: the page logs to the same stream, so anything it
+  prints after your snippet would be what --tail 1 hands back. Entries carry
+  `source`, which is `serverConsole` for your snippet and `browserConsole` for
+  the page, so filtering on both is what pins the value down:
+
+  $ echo 'console.log("qw-title:", await page.title())' | qawolf runner exec -
+  $ qawolf runner events console --tail 20 | jq -r 'select(.source == "serverConsole" and (.message | contains("qw-title:"))) | .message'
+
+  To read a top-level variable of the running workflow, `qawolf runner inspect
+  variable` is one call and the value, where exec is two calls and a marker.
+
+Scope:
+  The snippet imports nothing of yours by default. Pass --file <path> to
+  evaluate it in that file's scope, which also ships the directory's other
+  files, so the snippet can use your own page objects and helpers.
+
+Failures:
+  exec exits 2 until the runner's first run, since there is no page to evaluate
+  against. On a 4 the message says the snippet could not be evaluated, but a
+  lost answer looks the same from outside, so treat a 4 from a snippet that
+  changes something as "may have run" rather than "did not run", and check its
+  effect before running it again. With no runner named at all, exec launches one
+  and says so on stderr.
+```
 
-`runner-cannot-highlight-selectors` exits `2` and means the runner has no
-browser to draw on. `no-answer` exits `4`: a highlight runs inside the page, so
-a page that is gone or mid-navigation does not answer at all rather than
-answering slowly.
+## qawolf runner inspect
 
-## Accepting a new baseline: `promote-snapshot`
+```text
+Usage: qawolf runner inspect [options] [command]
+
+Read one thing off a runner's live page (browser) or Appium session (mobile)
+
+Options:
+  -h, --help              display help for command
+
+Commands:
+  element-html [options]  Print the HTML of the first element a selector matches
+  page-html [options]     Print the page's HTML, simplified for a model to read
+  variable [options]      Print a top-level variable's value from the running workflow
+  session [options]       Print the Appium session's status: ready, or why not
+  contexts [options]      List the WebView contexts available, and which is current
+  page-source [options]   Print the current context's page source, as a tree
+  elements [options]      Find elements at a screen point, carrying some text, or matching a
+                          selector
+  help [command]          display help for command
+
+Examples:
+  $ qawolf runner inspect element-html --selector "#email"
+  $ qawolf runner inspect page-html > page.html
+  $ qawolf runner inspect variable --name cart | jq .total
+  $ qawolf runner inspect session
+  $ qawolf runner inspect contexts
+  $ qawolf runner inspect page-source --context WEBVIEW_1
+  $ qawolf runner inspect elements --x 200 --y 400
+  $ qawolf runner inspect elements --text "Sign in" --partial
+  $ qawolf runner inspect elements --selector "//android.widget.Button[@text='Sign in']"
+
+Browser:
+  inspect answers one question about the live page and prints the answer on
+  stdout by itself, so you can redirect or pipe it. `page-html` is simplified
+  for a model to read rather than being the browser's exact markup, and
+  --selector narrows it to one subtree. `variable` reads a top-level variable of
+  the running workflow and prints it as JSON, which is how you see what your own
+  code computed rather than what the page shows. Use it before reaching for
+  exec: reading a value through a snippet means printing it and then fishing it
+  back out of the console stream, which is two calls and a marker.
+
+  One failure covers three causes, because a runner cannot tell them apart: no
+  live page, no element matching the selector, no variable under that name. All
+  three exit 2 and none clears by waiting, so read the message, which carries
+  whatever the runner said. An unreachable runner exits 4 and is worth retrying;
+  a runner that is not running at all exits 8 and is not.
+
+Mobile:
+  element-html and page-html are a browser's shapes, and a mobile runner answers
+  them with runner-is-not-a-browser. It answers session, contexts, page-source
+  and elements instead, and variable works on both.
+
+  session prints one summary line, ready or why not, because that line is the
+  whole answer. contexts, page-source and elements print their answer as JSON on
+  stdout, on its own, so you can pipe it (| jq .current, | jq .matches, | jq
+  .pageSource) rather than getting a count with no way to see what was found.
+
+  session is the one subcommand that never answers screen-needs-a-run: readiness
+  is the question it exists to answer, so it reports ready (with the platform,
+  device and session id), unreachable, ambiguous (more than one session is
+  somehow live) or no-session. The other three need a live session first.
+  screen-needs-a-run exits 2 and means no Appium session has started on this
+  runner yet: run a flow that opens one, then inspect again. screen-not-ready
+  exits 4 and means the session exists but did not answer this instant, or more
+  than one is somehow live: retry once, and relaunch the runner if it persists.
+
+  elements takes one of three ways to search: whole-pixel --x/--y on the
+  device's own screen, the same coordinates a screenshot is measured in; --text,
+  which matches exactly unless --partial is passed; or --selector, resolved the
+  same way a screen object's own selector is, with --strategy naming how (xpath,
+  ios-predicate or shadow; defaults to xpath). Prefer --selector when checking a
+  selector you are about to write: it answers what that exact string resolves
+  to, where --text and --x/--y only approximate it. The three do not mix: flags
+  from more than one are refused before a runner is addressed. An unparseable
+  selector answers invalid-selector, exit 2, distinctly from a selector that
+  parsed fine but matched nothing, which answers an empty `matches` list, exit
+  0. --context on page-source or elements reads a context other than the current
+  one, once contexts has told you which are available.
+
+  A browser runner answers runner-is-not-mobile to session, contexts,
+  page-source and elements, exit 2, since retrying never helps: launch with
+  --name android or --name ios instead. runner-unreachable exits 4 and is worth
+  retrying.
+```
 
-When a run's image diff fails and the new screenshot is the one you want, this
-replaces the baseline on the runner that produced it:
+### qawolf runner inspect element-html
 
-```sh
-qawolf runner events run-events --tail 20 | jq 'select(.type == "imageDiffArtifact")'
-qawolf runner promote-snapshot --screenshot checkout-1-actual.png --baseline checkout-1.png
-```
+```text
+Usage: qawolf runner inspect element-html [options]
 
-Both paths are the ones the diff reported, and both are named rather than
-positional, because two paths with one unlabelled is easy to get backwards and
-swapping them promotes the wrong image. They are paths inside the run's own
-screenshot storage, not files on your machine.
+Print the HTML of the first element a selector matches
 
-`snapshot-not-found` exits `2` and means the run wrote no screenshot at that
-path, which nearly always means the paths did not come from a diff this run
-produced. Nothing is changed, so correcting the path and repeating is safe.
-Promoting twice is also safe, so an unreachable runner is worth retrying.
+Options:
+  --selector <selector>  Playwright selector to inspect
+  --runner <id>          Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's
+                         stored runner
+  -h, --help             display help for command
+```
 
-## Installing a package mid-session
+### qawolf runner inspect page-html
 
-`qawolf runner import-package <name>` installs a package into the runner's live
-run, so a snippet or a selection can import it without a whole run to reinstall
-dependencies:
+```text
+Usage: qawolf runner inspect page-html [options]
 
-```sh
-qawolf runner import-package dayjs
-qawolf runner import-package dayjs --package-version 1.11.13
+Print the page's HTML, simplified for a model to read
+
+Options:
+  --selector <selector>  Limit the output to this subtree
+  --runner <id>          Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's
+                         stored runner
+  -h, --help             display help for command
 ```
 
-The version defaults to `latest`, and the flag is `--package-version` because
-`--version` belongs to the CLI itself. The install resolves against your
-project's own dependencies, read from `package.json`, so it needs a run already
-going: there is no live run on a runner that has not run anything. npm's own
-refusal comes back verbatim on an exit `2`, which is a name or a version to
-correct rather than something to retry.
+### qawolf runner inspect variable
+
+```text
+Usage: qawolf runner inspect variable [options]
+
+Print a top-level variable's value from the running workflow
 
-## Reading the page: `exec`
+Options:
+  --name <name>  Name of the variable to read
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
+```
 
-`qawolf runner exec <file>` evaluates a snippet against whatever the runner's
-browser is showing, which is how you read a value out of the page rather than
-looking at it. Two things to know, because neither is guessable:
+### qawolf runner inspect session
 
-It does not return what the snippet evaluated to, only whether it ran. To get a
-value back, print it and read the `console` stream. Print it behind a marker you
-chose, and match on that rather than taking the newest line: the page logs to the
-same stream, so anything it prints after your snippet would be what `--tail 1`
-hands back. Entries carry `source`, which is `serverConsole` for your snippet and
-`browserConsole` for the page, so filtering on both is what pins the value down.
+```text
+Usage: qawolf runner inspect session [options]
 
-```sh
-echo 'console.log("qw-title:", await page.title())' | qawolf runner exec -
-qawolf runner events console --tail 20 \
-  | jq -r 'select(.source == "serverConsole" and (.message | contains("qw-title:"))) | .message'
+Print the Appium session's status: ready, or why not
+
+Options:
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
 ```
 
-And the snippet imports nothing of yours by default. Pass `--file <path>` to
-evaluate it in that file's scope, which also ships the directory's other files,
-so the snippet can use your own page objects and helpers.
-
-## Running a flow
-
-`qawolf runner run <flowFile>` ships the flow file, everything it imports, and
-your `package.json` and `tsconfig.json`. Nothing else travels, so you can run
-from the root of a large project without sending it. The runner holds no copy of
-your project, so what runs is exactly what is on disk at that moment,
-uncommitted edits included.
-
-Imports are followed the same way a run from the QA Wolf app follows them:
-relative paths and `tsconfig.json` path aliases, resolving `.ts` and `.js`. An
-`export ... from` re-export is not followed, and neither is `require()`, so a
-barrel file does not pull in what it re-exports. A `package.json` has to be
-there, since the run reads its npm dependencies from it, and the files may carry
-at most 30 MiB in total. A missing file, a missing `package.json` and files over
-the cap are all refused before any runner is resolved or launched, so a typo
-costs nothing.
-
-After the first run on a runner, later runs send only the files whose content
-changed, so iterating on one flow costs a small request rather than the whole
-graph again. `--json` reports which happened as `fileSync`, `delta` or `full`.
-Nothing about this needs managing: the baseline lives in `.qawolf/runner-files.json`,
-a switch to another runner ignores it, and a runner that turns out not to hold
-what was claimed gets the whole set resent automatically.
-
-The call answers with a run id as soon as the run is accepted. **The outcome is
-not in that answer**, it is in the `run-status` stream, whose entries carry
-`runId`, `status` and an `errorMessage` when there is one.
-
-### Running part of a flow
-
-`--lines 12-40` runs those lines against the browser as it stands, so nothing is
-re-navigated and nothing is signed in again. Use it to iterate on a step without
-paying for the whole flow to reach it again.
-
-The two file paths are the thing to get right, because getting them backwards
-runs the wrong code and nothing reports it:
-
-- the positional is **always the flow file**. It is the run's entry point, and it
-  is required for every run, selection or not.
-- `--lines-file` is **where the lines live**. It defaults to the positional, so
-  pass it only when the range is in another file, typically a page object whose
-  method you want to run against the instance your last run left alive.
+### qawolf runner inspect contexts
 
-```sh
-qawolf runner run flows/checkout.flow.ts --lines 12-40          # lines in the flow file
-qawolf runner run flows/checkout.flow.ts --lines 4-9 \
-  --lines-file pages/login.ts                                   # lines in a page object
+```text
+Usage: qawolf runner inspect contexts [options]
+
+List the WebView contexts available, and which is current
+
+Options:
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
 ```
 
-The lines-file has to be one of the files that travel, so it lives under the
-directory you run from. A range whose file is not collected is refused before a
-runner is addressed, naming the path.
+### qawolf runner inspect page-source
 
-### Giving the run environment variables
+```text
+Usage: qawolf runner inspect page-source [options]
 
-There are two ways, and a run takes one of them. `--env-id` names a QA Wolf
-environment by id or alias, the same reference `qawolf flows` takes as `--env`.
-`--env-file .env` gives the run the variables in a dotenv file, in the format
-`qawolf flows pull` writes.
+Print the current context's page source, as a tree
 
-```sh
-qawolf runner run flows/checkout.flow.ts --env-id staging
-qawolf runner run flows/checkout.flow.ts --env-file .env
+Options:
+  --context <name>  Read this context instead of the current one
+  --runner <id>     Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored
+                    runner
+  -h, --help        display help for command
 ```
 
-**A run with neither flag falls back to `QAWOLF_ENVIRONMENT`**, the same
-variable `qawolf flows` reads, so one export covers both. The run says on
-stderr which environment it picked up, because those variables reach your flow's
-code and a run should never be given an environment silently. `--env-id` wins
-over it, and `--env-file` suppresses it, so a run reading a dotenv file is not
-handed a second environment on top.
+### qawolf runner inspect elements
 
-```sh
-export QAWOLF_ENVIRONMENT=staging
-qawolf runner run flows/checkout.flow.ts     # runs against staging
+```text
+Usage: qawolf runner inspect elements [options]
+
+Find elements at a screen point, carrying some text, or matching a selector
+
+Options:
+  --context <name>       Read this context instead of the current one
+  --partial              text: match text containing this, rather than exactly this
+  --runner <id>          Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's
+                         stored runner
+  --selector <selector>  Resolved the same way a screen object's own selector is
+  --strategy <strategy>  selector: xpath, ios-predicate, or shadow (defaults to xpath)
+  --text <text>          text: the text to match
+  --x <pixels>           point: whole pixels on the device's own screen
+  --y <pixels>           point: whole pixels on the device's own screen
+  -h, --help             display help for command
 ```
 
-**Prefer `--env-id`.** QA Wolf reads and decrypts the environment itself, so the
-values never leave the server, nothing has to be pulled to disk first, and no
-size limit applies to them. It is the only way to run a flow whose environment
-holds something large, such as a session cookie.
-
-A run that sends its own variables with `--env-file` may carry at most 200 of
-them, each value at most 16 KiB. Names follow what a shell accepts, and
-`QAWOLF_TEAM_ID` is reserved because QA Wolf sets it from the key you
-authenticated with. All of that is refused before a runner is addressed, naming
-the variable at fault.
-
-Passing both flags is refused. They each give the run its whole environment, so
-there is no order in which they would combine.
-
-If the runner had no browser, one is started before your lines run, and the
-command says so on stderr. Those lines then ran against a fresh page rather than
-the one an earlier run left, which is worth reading before you act on what you
-see.
-
-**Pass `--follow` to `run` and let it wait for you.** It reports the run's
-status — in progress, then passed or failed — and ends on the settled status.
-Exit code `1` means the run did not pass. Three flags mirror more streams into
-the follow, and each implies `--follow` on its own: `--logs` streams every log
-line the run produces, `--run-events` streams the run's progress events as JSON
-lines, and `--recorder-events` streams the browser actions the runner records
-as JSON lines — the recorder is runner-wide rather than run-scoped, so that one
-carries whatever is recorded after an anchor taken just before submission. Whatever mirrors are on, the
-follow still ends on the status, never on them, so a run that prints nothing
-still terminates the follow and a run that dies mid-sentence still reports how.
-Combining mirror flags interleaves their lines with nothing saying which stream
-a line came from — fine for eyeballs; when parsing, follow one stream at a time.
+## qawolf runner import-package
 
-```sh
-qawolf runner run flows/checkout.flow.ts --follow
-qawolf runner run flows/checkout.flow.ts --follow --logs
-qawolf runner run flows/checkout.flow.ts --follow --recorder-events
+```text
+Usage: qawolf runner import-package [options] <name>
+
+Install a package into a runner's live run, so a snippet or a selection can import it
+
+Options:
+  --package-version <version>  Version to install (default: "latest")
+  --runner <id>                Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's
+                               stored runner
+  -h, --help                   display help for command
+
+Examples:
+  $ qawolf runner import-package dayjs
+  $ qawolf runner import-package dayjs --package-version 1.11.13
+
+Installing mid-session:
+  The package goes into the runner's live run, so a snippet or a selection can
+  import it without a whole run to reinstall dependencies. The flag is
+  --package-version because --version belongs to the CLI itself. The install
+  resolves against your project's own dependencies, read from package.json, so
+  it needs a run already going: there is no live run on a runner that has not
+  run anything. npm's own refusal comes back verbatim on an exit 2, which is a
+  name or a version to correct rather than something to retry.
 ```
 
-If you would rather submit and come back later, note that `--follow` on `events`
-does not end when the run settles — it runs until its own `--timeout`, an hour
-by default — so it cannot be used to wait for a run. Poll instead, and decide
-with the same rule the CLI uses: `status` is `in-progress` while the run is
-going, and any other value means it has settled.
+## qawolf runner highlight-selector
 
-```sh
-qawolf runner run flows/checkout.flow.ts --json     # -> {"runId":"...","runnerId":"..."}
-qawolf runner events run-status --run <runId> --tail 1 | jq -r '.status'
+```text
+Usage: qawolf runner highlight-selector [options] [selector]
+
+Highlight what a selector matches on a runner's live page, so the next screenshot shows it. Omit the
+selector to clear the highlight
+
+Options:
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
+
+Examples:
+  $ qawolf runner highlight-selector "text=Sign in"
+  $ qawolf runner highlight-selector "#checkout" && qawolf runner screenshot
+  $ qawolf runner highlight-selector
+
+Reading the result:
+  `inspect element-html` tells you what a selector matched; highlight-selector
+  shows you where it is, by drawing on the page itself. The highlight stays
+  until it is replaced or cleared, which is the point: you cannot see the
+  runner's screen, so the only way to read the result is the next screenshot.
+
+  Three answers are worth telling apart. A selector that matched prints how many
+  elements it hit and exits 0. A selector the page read fine but that matched
+  nothing also exits 0, because the call did what was asked and the count is the
+  answer; the message says the syntax was fine so you look at the page, not the
+  locator. A selector the page could not read at all exits 2, because that one
+  is yours to correct and retrying will not change it.
+
+  runner-cannot-highlight-selectors exits 2 and means the runner has no browser
+  to draw on. no-answer exits 4: a highlight runs inside the page, so a page
+  that is gone or mid-navigation does not answer at all rather than answering
+  slowly.
 ```
 
-The one expensive mistake on this surface: **if `run` reports that the runner
-could not be reached, that does not mean the run did not start.** The runner may
-have accepted it and been too slow to answer, and resubmitting bills and journals
-a second run.
-
-There is no clean recovery here, so it is worth being plain about it. The journal
-lives on the same pod, so while the runner stays unreachable a `run-status` read
-fails the same way and cannot tell you whether a run is going. Wait for the
-runner to answer again, then read `run-status` without `--run` and look at the
-newest `runId`. Nothing ties that id back to your submission: `run` never
-answered, so you have no id to match it against, and a runner takes work from
-anyone addressing it. Treat the newest id as your run only if you know nothing
-else submits to this runner; otherwise follow it to see what it is before acting
-on it. An empty read is not proof the run did not start, though:
-`run` returns the moment the run is accepted, and its first `run-status` entry
-may not be written yet, so a run accepted just before the runner went quiet can
-still be in flight with nothing to show. `runFlow` has no idempotency key, so a
-resubmit always risks a second billed run. Prefer polling `run-status` a while
-longer over resubmitting; only submit again once you are willing to accept that
-risk.
-
-## Reading history
-
-Everything observable is an append-only stream on the pod, read by cursor or
-tail rather than subscribed to, so attaching late still gets you the history that
-is still there. It is not unbounded: a size cap drops the oldest entries on a
-long-lived runner, and a `--tail N` read can stop early and hand back fewer than
-N even when more matched. Both are warned about on stderr — dropped entries only
-once a read holds a cursor, a stopped-early read with a pointer at `--since` —
-so watch stderr, treat a short answer as "at least this" rather than "all there
-was", and read what you care about as you go rather than at the end. QA Wolf writes `recorder`, `console`, `run-events`,
-`run-logs` and `run-status`; a stream nobody has written reads as empty rather
-than as an error, and a stream this CLI version does not know about is still
-readable by name.
-
-One payload per line, so shell tools compose:
+## qawolf runner promote-snapshot
 
-```sh
-qawolf runner events console --tail 20 | jq -r '.message'
-qawolf runner events run-logs --run <runId> --follow > run.log
+```text
+Usage: qawolf runner promote-snapshot [options]
+
+Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it
+
+Options:
+  --screenshot <path>  The screenshot to promote, as the image diff named it
+  --baseline <path>    The baseline to replace, as the image diff named it
+  --runner <id>        Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored
+                       runner
+  -h, --help           display help for command
+
+Examples:
+  $ qawolf runner promote-snapshot --screenshot checkout-1-actual.png --baseline checkout-1.png
+  $ qawolf runner events run-events --tail 20 | jq 'select(.type == "imageDiffArtifact")'
+
+Paths:
+  Use it when a run's image diff fails and the new screenshot is the one you
+  want. Both paths are the ones the diff reported in its imageDiffArtifact run
+  event, and both are named rather than positional, because two paths with one
+  unlabelled is easy to get backwards and swapping them promotes the wrong
+  image. They are paths inside the run's own screenshot storage, not files on
+  your machine.
+
+  snapshot-not-found exits 2 and means the run wrote no screenshot at that path,
+  which nearly always means the paths did not come from a diff this run
+  produced. Nothing is changed, so correcting the path and repeating is safe.
+  Promoting twice is also safe, so an unreachable runner is worth retrying.
 ```
 
-`--tail N` takes the newest N, `--since <sequence>` reads everything after a
-cursor, and `--run <id>` narrows the run-scoped streams.
+## qawolf runner record
 
-`--follow` polls and prints as entries arrive. It is `tail -f` with a bound: it
-ends only at its `--timeout` (an hour by default, exit `6`), because reading
-keeps the runner alive and billing. Redirect it to a file and stop it yourself,
-or use repeated `--since` reads when you need the command to end sooner.
+```text
+Usage: qawolf runner record [options] [command]
+
+Control video recording on a Playwright runner
+
+Options:
+  -h, --help                     display help for command
+
+Commands:
+  start [options]                Start manual video capture across runs. Requires a ready screen and
+                                 suppresses automatic capture until stopped
+  stop [options] <recording-id>  Stop the recording with this UUID and publish it. Retrying cannot
+                                 stop a later recording
+  status [options]               Show the active recording and automatic recording setting
+  auto [options] <setting>       Enable or disable automatic recording for subsequent full runs
+  help [command]                 display help for command
+
+Recording:
+  Start a flow first so the runner has a screen, then start a manual capture and
+  keep `result.state.active.id` from the `record start --json` answer to stop
+  that capture:
+
+  $ qawolf runner record start --runner ci --json
+  $ qawolf runner record stop <recording-id> --runner ci
+  $ qawolf runner record status --runner ci
+  $ qawolf runner record auto on --runner ci
+
+  Start generates a UUID unless you pass --recording-id <uuid>. If a start
+  response is lost, the error includes that UUID: check `record status` and
+  reuse the UUID when retrying. Stop always names a specific recording, so
+  retrying it cannot stop a later capture. Manual recordings span runs and
+  suppress automatic capture until stopped. The auto setting affects subsequent
+  full runs. An active automatic recording ends with its run; `record stop`
+  cannot interrupt it. If a stop publishes a recording with status "failed", the
+  CLI exits 1 and still prints the manifest so callers can inspect it.
+
+  Published recordings stay readable after the runner terminates, with `qawolf
+  runner list-recordings`.
+```
 
-Where it does win is the cursor. The pod reports how far a read scanned rather
-than how far it matched, and `--follow` carries that number, so a filtered read
-that matched nothing still moves forward. A caller paging by hand cannot see it,
-because the CLI does not print it, and the best available substitute is the
-highest `sequence` you actually saw. So a narrow `--run` filter over a busy
-stream stalls: with nothing matching, there is no new `sequence` to move on to,
-and you re-read the same window until something matches (NOVA-1397).
+### qawolf runner record start
 
-## Staying alive
+```text
+Usage: qawolf runner record start [options]
 
-A runner is reaped after a period of inactivity, and every command that talks to
-the runner counts as activity, including a journal read.
-`qawolf runner keepalive` exists for the gap that creates: a harness that thinks,
-or waits on a human, for minutes between actions would otherwise come back to a
-pod that is gone. It resets the clock and tells you the runner is still there.
+Start manual video capture across runs. Requires a ready screen and suppresses automatic capture
+until stopped
 
-It is listed as a `read`, but it is the one read with a cost: keeping the clock
-reset keeps a billed pod alive. Call it while you are genuinely still working, not
-on a timer you forget, and call `qawolf runner terminate` when you are done rather
-than leaving a pod to time out. A loop that keeps a runner alive and never stops
-it bills until someone notices.
+Options:
+  --recording-id <uuid>  Recording UUID. Generated when omitted; reuse it when retrying this start
+  --runner <id>          Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's
+                         stored runner
+  -h, --help             display help for command
+```
 
-## Stopping a run vs ending a runner
+### qawolf runner record stop
 
-Two different things, and the names are the only warning you get:
+```text
+Usage: qawolf runner record stop [options] <recording-id>
 
-- `qawolf runner stop-run` stops what the runner is executing and leaves the
-  runner up, its browser on whatever page the run reached. The run settles as
-  stopped rather than passed or failed. Use it to abandon a run and keep the
-  browser you were working against.
-- `qawolf runner terminate` ends the runner and the pod with it. Everything on
-  it is gone, and the next command under that id launches and bills a new one.
+Stop the recording with this UUID and publish it. Retrying cannot stop a later recording
 
-Both succeed when there was nothing to do, and say which: `wasRunning` is
-`false` when no run was going, and when no runner was running. Neither is an
-error, so a retry needs no special handling.
+Options:
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
+```
 
-## End to end
+### qawolf runner record status
 
-Run from a directory holding a flow and a `package.json`. The run is what starts
-the screen, so it is not optional even though the goal here is to drive by hand.
+```text
+Usage: qawolf runner record status [options]
 
-```sh
-export QAWOLF_API_KEY=...          # the only credential
-export QAWOLF_RUNNER_ID=agent-1    # so no command below needs --runner
+Show the active recording and automatic recording setting
 
-qawolf runner launch --id agent-1 --json          # --id, not the variable; read .alreadyRunning and .url
-qawolf runner run flows/smoke.flow.ts --follow    # starts the screen; exit 1 if it failed
+Options:
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
+```
 
-qawolf runner act navigate --url https://example.com/login --screenshot step-1.jpg   # then read step-1.jpg yourself
-qawolf runner act click --button left --x 480 --y 260 --screenshot step-2.jpg
-qawolf runner act type --text "someone@example.com" --screenshot step-3.jpg
+### qawolf runner record auto
 
-qawolf runner inspect element-html --selector "#email"
-qawolf runner inspect variable --name cart | jq .total
+```text
+Usage: qawolf runner record auto [options] <setting>
 
-qawolf runner run flows/smoke.flow.ts --lines 12-40 --follow   # just those lines
-qawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'
-qawolf runner terminate
+Enable or disable automatic recording for subsequent full runs
+
+Arguments:
+  setting        Automatic recording setting (choices: "on", "off")
+
+Options:
+  --runner <id>  Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's stored runner
+  -h, --help     display help for command
+```
+
+## qawolf runner list-recordings
+
+```text
+Usage: qawolf runner list-recordings [options]
+
+Read a page of published video recordings, including after the runner terminates. Platform URLs
+persist; video URLs expire
+
+Options:
+  --runner <id>          Runner to target. Defaults to QAWOLF_RUNNER_ID, then this directory's
+                         stored runner
+  --recording-id <uuid>  Look up one recording; an empty result means it is not published or does
+                         not exist
+  --page-token <token>   Continue from nextPageToken returned by the previous page
+  -h, --help             display help for command
+
+Reading pages:
+  $ qawolf runner list-recordings --runner ci --json
+  $ qawolf runner list-recordings --runner ci --recording-id <uuid> --json
+  $ qawolf runner list-recordings --runner ci --page-token '<nextPageToken>' --json
+
+  Each response is one page with `recordings` and an optional `nextPageToken`.
+  Follow that token for more; the order is storage-key order, not newest-first.
+  Entries include status, run ids, a stable platform `url`, and an expiring
+  `videoUrl` when video is available. An empty lookup means the recording has
+  not been published or does not exist. Abrupt runner loss may leave video
+  unavailable. Keep the runner id for history lookups after termination clears
+  the local default.
 ```