@reticlehq/server 2.7.0 → 2.9.0

package/docs/cli/cloud.mdx

@@ -0,0 +1,153 @@
+---
+title: reticle cloud commands
+description: Sign in, link a repository, and read runs and regressions from Reticle Cloud.
+icon: cloud
+---
+
+Ten subcommands bind this repository to Reticle Cloud so runs and flows land on a dashboard. They dispatch before the local parser, so `reticle login` is one tool, not a second binary.
+
+```bash
+npx @reticlehq/server <login|logout|whoami|link|project|config|push|runs|regression|share>
+```
+
+These are thin clients over the `/v1` API. The moat is the server, not the verbs.
+
+## Where credentials live
+
+| Path | Contents | Secret |
+| --- | --- | --- |
+| `~/.reticle/session.json` | `{ url, token, orgName }` from `reticle login` | Yes |
+| `~/.reticle/credentials.json` | Project-scoped API keys from `reticle link`, keyed by `projectId` | Yes |
+| `<repo>/.reticle/cloud.json` | `{ projectId, projectName, url, sync, verify }`. The non-secret binding | No, commit it |
+
+Auth for any command is `RETICLE_CLOUD_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`.
+
+## The commands
+
+### `reticle login`
+
+```bash
+npx @reticlehq/server login                                    # browser device flow (the default)
+npx @reticlehq/server login --email you@acme.com               # headless: requests a code
+npx @reticlehq/server login --email you@acme.com --code 123456 # headless: exchanges it
+npx @reticlehq/server login --email you@acme.com --org "Acme"  # --org is consulted only for a brand new account
+```
+
+With no `--email`, it runs a browser device flow like `gh auth login`: fetch a device and user code, open the browser to approve, poll until confirmed. With `--email` it keeps the two-step code path for CI and servers, because it proves you own the inbox before handing out a session. A local cloud whose dev mailer cannot deliver echoes the code back and completes in one command.
+
+### `reticle logout`
+
+Empties `session.json`. Per-project keys in `credentials.json` stay. Prints `{ "loggedOut": true }`.
+
+### `reticle whoami`
+
+The one call to make when you do not know your state. Real capture:
+
+```json
+{
+  "loggedInAs": "acme",
+  "repo": {
+    "attached": false,
+    "projectId": null,
+    "url": null,
+    "sync": { "runs": true, "memory": true, "flows": true },
+    "verify": "local"
+  }
+}
+```
+
+An unattached repo also gets a next-step nudge on stderr, telling you to run `reticle link`:
+
+```
+→ this repo is not attached ... run `reticle link`
+```
+
+`whoami` exits `0` either way. Throughout this page, the punctuation joining the two halves of a message is shown as `...`.
+
+### `reticle link`
+
+```bash
+npx @reticlehq/server link [--project <name|id>]
+```
+
+Binds this repository to a cloud project. With a login token it **mints** a project-scoped key, so there is nothing to paste. With `RETICLE_CLOUD_KEY` already set, it resolves that key's project instead. `--project` accepts a slug id or a display name; omitted, it uses the `default` project. Writes `cloud.json` and the key.
+
+### `reticle project`
+
+```bash
+npx @reticlehq/server project ls
+npx @reticlehq/server project create "My App"
+npx @reticlehq/server project rename <projectId> "New name"
+npx @reticlehq/server project rm <projectId>
+```
+
+`rename` and `rm` work but are missing from the top-level `reticle help` block, which lists only `<ls|create <name>>`. The command's own usage error names all four. Missing or malformed arguments exit `2`:
+
+```
+reticle: usage: reticle project <ls|create <name>|rename <id> <name>|rm <id>>
+```
+
+### `reticle config`
+
+```bash
+npx @reticlehq/server config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
+```
+
+Edits `.reticle/cloud.json` in place. Any value other than `on` or `off` (or `local` or `server` for `--verify`) exits `2`. Requires the repo to be linked; run in an unlinked repo it exits `2` before it looks at the flags at all:
+
+```
+reticle: no .reticle/cloud.json here ... run `reticle link` first
+```
+
+### `reticle push`
+
+Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy. With `sync.runs` off it does nothing and says so. Prints `{ pushed, failed, total, project }`.
+
+### `reticle runs`
+
+The linked project's recent run artifacts. The key scopes the query server-side.
+
+### `reticle regression`
+
+The CI gate: which flows broke relative to before. **Exits `3`** when any flow regressed, which is the whole point of it being a separate command.
+
+### `reticle share`
+
+```bash
+npx @reticlehq/server share <runId>
+```
+
+Mints a public proof link for one run. A missing `runId` exits `2`:
+
+```
+reticle: usage: reticle share <runId>
+```
+
+## When the repo is not attached
+
+`push`, `runs` and `regression` all need a project to talk to. Without one they exit `1` with the same line on stderr, measured:
+
+```
+reticle: cloud not attached here ... run `reticle link` (or set RETICLE_CLOUD_URL/KEY)
+```
+
+## Exit codes
+
+| Code | Meaning                                                                             |
+| ---- | ----------------------------------------------------------------------------------- |
+| `0`  | Success                                                                             |
+| `1`  | The API call failed, or the repository is not attached where attachment is required |
+| `2`  | Usage error, or not signed in and no `RETICLE_CLOUD_KEY`                            |
+| `3`  | `regression` only: at least one flow broke                                          |
+
+Output is pretty-printed JSON on stdout. Errors and next-step nudges go to stderr, so an agent parsing stdout is unaffected.
+
+## Worked example
+
+```bash
+npx @reticlehq/server login
+npx @reticlehq/server project create "Checkout"
+npx @reticlehq/server link --project "Checkout"
+npx @reticlehq/server verify http://localhost:4173   # runs auto-push once linked
+npx @reticlehq/server regression                      # exit 3 fails the pipeline
+```

package/docs/cli/doctor.mdx

@@ -0,0 +1,109 @@
+---
+title: reticle doctor
+description: 'Diagnose the Reticle setup in one command: Chromium, daemon, bridge port, logs, and desktop wiring.'
+icon: stethoscope
+---
+
+`reticle doctor` collapses the setup failure modes into one command. It is the first thing to run when something is wrong.
+
+```bash
+npx @reticlehq/server doctor [--port N]
+```
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which bridge port to diagnose |
+
+## What it prints
+
+Human-readable lines on stdout, not the JSON log. Real capture:
+
+```
+reticle doctor
+  node         v22.14.0
+  chromium     ✓ installed (chromium-1234)
+  daemon       ✓ running on :4400 (pid 72698, v2.8.0)
+  sessions     ✓ 1 page connected
+  bridge port  4400  (your app must dial THIS port, not your dev-server port)
+  daemon log   /Users/you/.reticle/daemon-4400.log
+  tracing      RETICLE_TRACE=1 on the daemon for per-stage timings in that log
+```
+
+When nothing has connected, the `sessions` line fails and the daemon's own diagnosis is appended under the checklist. Real capture, against a daemon on a scratch port that no app had dialled, with the diagnosis wrapped for width and trimmed at the ellipsis:
+
+```
+  sessions     ✗ no page has connected to this daemon
+  bridge port  4499  (your app must dial THIS port, not your dev-server port)
+  daemon log   /Users/you/.reticle/daemon-4499.log
+  tracing      RETICLE_TRACE=1 on the daemon for per-stage timings in that log
+
+  nothing has connected. What the daemon can tell from here:
+    no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is
+    listening on the ports Reticle scans (3000, 3001, 4200, 4321, 5000, 5173, 5174, 8000, 8080, 8100,
+    9000, 1420, 3100, 4173, 5175, 7860, 8501), so the dev server may not be running ...
+```
+
+| Line | What it checks |
+| --- | --- |
+| `node` | The Node version running the CLI |
+| `chromium` | Whether the exact Chromium revision the bundled Playwright wants is on disk. The most common silent failure |
+| `daemon` | Whether the port holds a Reticle daemon, a foreign process (named where possible), or nothing. Adds a `version` line when the daemon's version or contract fingerprint disagrees with the CLI's |
+| `sessions` | Whether any page has actually connected. Zero is a FAILING check rather than a neutral note, because it is the state the setup most often stalls in: wired correctly, daemon up, nothing dialled in. When it is zero the daemon's own no-session diagnosis prints below the checklist |
+| `bridge port` | The port your app must dial, spelled out because mixing it up with the dev server port is the most common setup failure |
+| `port check` | Only when your project's configured port disagrees with the one the daemon is on. Prints the mismatch rather than leaving you to spot it across two lines |
+| `daemon log` | Where the structured daemon log lives |
+| `tracing` | How to turn that log into a per-stage trace |
+| `desktop` | Only on a desktop project. Every Electron and Tauri misconfiguration here fails silently, so it is diagnosed explicitly |
+
+## The chromium line
+
+Playwright pins one Chromium revision per version, and the daemon launches that one and no other. So the check is not "is a Chromium there" but "is _this_ revision there", and the three answers have three different fixes.
+
+All three captures below are real, taken by pointing `PLAYWRIGHT_BROWSERS_PATH` at a full root, a stale root, and an empty one.
+
+**`✓ installed`** means the wanted revision is on disk. Nothing to do.
+
+```
+  chromium     ✓ installed (chromium-1234)
+```
+
+**`✗ wrong revision`** means builds are installed and none of them is the wanted one. One pinned download away. The line names the revision Playwright wants, then every revision the root actually holds, then the exact command:
+
+```
+  chromium     ✗ wrong revision ... the bundled playwright wants chromium-1234;
+  /tmp/pwroot holds chromium-1194, chromium-1208. run: npx playwright@1.62.1 install chromium
+```
+
+**`✗ missing`** means the browsers root holds no Chromium at all. It prints the full executable path it looked for, so you can see which root it searched. If that is not where your browsers live, `PLAYWRIGHT_BROWSERS_PATH` is what moves it:
+
+```
+  chromium     ✗ missing ... looked for /tmp/emptyroot/chromium-1234/chrome-mac-arm64/Google Chrome
+  for Testing.app/Contents/MacOS/Google Chrome for Testing; run: npx playwright@1.62.1 install chromium
+```
+
+Both failing lines are one line in the terminal, wrapped here for width, and the punctuation that separates the verdict from its explanation is shown as `...`. The revision number and the pinned Playwright version come from the build you are running, so yours may differ from these; use the ones your own `doctor` prints.
+
+The wanted revision and the root are both read back off the path Playwright itself resolves, so `PLAYWRIGHT_BROWSERS_PATH` and every platform default (including `%LOCALAPPDATA%\ms-playwright` on Windows) are honoured without this command keeping its own table of roots.
+
+<Warning>
+  Run the command `doctor` prints, not `npx playwright install chromium`. The unpinned form resolves
+  the newest Playwright, downloads *its* revision, and leaves the check saying exactly what it said
+  before. That loop is why the line names the version to pin to.
+</Warning>
+
+## Exit codes
+
+Always `0`. `doctor` reports; it does not gate.
+
+## Worked example
+
+```bash
+npx @reticlehq/server doctor
+# then run the chromium command doctor printed, verbatim
+```
+
+<Card title="Deeper debugging" icon="bug" href="/debugging">
+  Reading the daemon log, and what `RETICLE_TRACE=1` adds to it.
+</Card>

package/docs/cli/drive.mdx

@@ -0,0 +1,74 @@
+---
+title: reticle drive
+description: Run Reticle in the foreground against a URL, with the browser visible, for debugging.
+icon: gauge-high
+---
+
+`reticle drive` runs the engine in the foreground and launches a browser at the URL you give it. It exists for debugging: you watch the run happen.
+
+```bash
+npx @reticlehq/server drive <url> [--headless] [--headed]
+```
+
+## Arguments and flags
+
+| Argument     | Type                             | Default                  | What it does      |
+| ------------ | -------------------------------- | ------------------------ | ----------------- |
+| `url`        | string, positional, **required** | none                     | The page to drive |
+| `--headed`   | boolean                          | on by default outside CI | Show the browser  |
+| `--headless` | boolean                          | on when `CI` is set      | Hide it           |
+
+`drive` is the one interactive command in the family, so it is the one that shows the browser by default. `serve`, `mcp` and the internal daemon own the pooled browser behind leases, which is batch work, and hide theirs.
+
+## What it prints
+
+`reticle_started` with the port on success, `reticle_start_failed` with the error otherwise. When a daemon already owns the port it prints `reticle_drive_attached` with the session it opened instead. See [When a daemon already has the port](#when-a-daemon-already-has-the-port).
+
+Omitting the URL is a usage error. Real capture, with the usage block that follows it trimmed:
+
+```
+{"t":"2026-08-15T18:43:06.977Z","event":"reticle_usage_error","message":"drive needs a url"}
+drive needs a url
+
+usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)
+  ...
+```
+
+<Note>
+  `drive` takes **no `--port` flag**. Any flag other than `--headed` or `--headless` is rejected as
+  `unknown argument '--port'`. To drive on a different port, set `RETICLE_PORT` or put the port in
+  `.reticle.json`.
+</Note>
+
+## Exit codes
+
+| Code | Meaning                                                               |
+| ---- | --------------------------------------------------------------------- |
+| `0`  | Running in the foreground, or attached with a connected session       |
+| `1`  | No URL, an unknown flag, the engine failed to start, or attach failed |
+
+## When a daemon already has the port
+
+A daemon on `:4400` is the normal state the moment any agent connects, and `drive` does not fight it for the port: it **asks that daemon** for a browser instead. The daemon opens a fresh isolated, never-throttled context, the same one `reticle_lease` hands an agent, and `drive` prints the session id and exits.
+
+```bash
+$ npx @reticlehq/server drive http://localhost:5173
+{"event":"reticle_drive_attached","port":4400,"url":"http://localhost:5173","sessionId":"lease-9f2b…","ready":true}
+```
+
+A plain-text line follows it naming the same session, how long it survives untouched (any tool call against it resets that), and, if the page never dialled the bridge, why.
+
+That session lives in the daemon, so the tools your agent already has open can address it by id. You do **not** need `reticle stop` first, and should not use it: the MCP proxy respawns a daemon as soon as the next tool call arrives, which is a race a manual `stop` loses.
+
+Attaching means the browser is the daemon's pooled, headless one, so `--headed` cannot apply. To watch a browser instead, drive on a port no daemon owns (`RETICLE_PORT=4460`).
+
+<Note>
+  If the port is held by something that is **not** a Reticle daemon, `drive` refuses and names the
+  holder. It can neither bind nor attach. [`reticle verify`](/cli/verify) still binds its own port.
+</Note>
+
+## Worked example
+
+```bash
+npx @reticlehq/server drive http://localhost:5173
+```

package/docs/cli/feedback.mdx

@@ -0,0 +1,67 @@
+---
+title: reticle feedback
+description: Send a report to the Reticle maintainers from the shell, including from a setup that never finished.
+icon: comment
+---
+
+`reticle feedback` is the feedback channel as a command: no prompts, no editor, no account. It exists so the cost of telling the maintainers something is lower than the cost of shrugging and moving on.
+
+```bash
+npx @reticlehq/server feedback [--rating 1-5] [--bug] "what worked, what didn't"
+npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"
+```
+
+The `--agent` form is for an agent that cannot reach the `reticle_feedback` tool: during `init`, while instrumentation is half wired, or when the daemon will not start. Those are the reports that are hardest to hear and most needed, because every other path requires the tool surface to already work.
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--rating N` | integer 1 to 5 | unset | A human's overall take. A bare rating with no words is a valid report |
+| `--bug` | boolean | `false` | Shorthand for `--kind bug` |
+| `--kind K` | one of `bug`, `gap`, `ambiguity`, `feature_request`, `improvement`, `experience` | `experience`, or `bug` with `--bug` | The report's class. Wins over `--bug` |
+| `--agent` | boolean | `false` | File as the agent, so agent reports never dilute the human rating signal |
+
+Everything that is not a flag or a flag's value becomes the message, joined with spaces. Quoting is still your job for shell reasons.
+
+## What it prints
+
+The payload is printed **before** it is sent, every time. A channel that carries free text and does not show you what it sends is asking for trust it has not earned.
+
+```
+sending      {"source":"human","kind":"experience","stack":"vite","runtime":"web"}
+redacted     email (removed before sending)
+thanks       your feedback is in. it genuinely changes what gets built next.
+```
+
+`not sent` replaces the last line when the send failed or telemetry is off, and names the reason. Humans who have never identified also get an offer of a reply route, printed after the receipt rather than as a prompt.
+
+Run with no message and no rating, it prints usage and exits `1`. Real capture:
+
+```
+usage: reticle feedback [--rating 1-5] [--bug] "what worked, what didn't"
+       agents: reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "what happened"
+       your words go to the maintainers; nothing from your app is ever included.
+```
+
+## Exit codes
+
+| Code | Meaning                                                         |
+| ---- | --------------------------------------------------------------- |
+| `0`  | The report was submitted, or attempted and reported as not sent |
+| `1`  | No message and no rating, or an invalid `--rating` or `--kind`  |
+
+## Worked example
+
+```bash
+npx @reticlehq/server feedback --agent --kind gap \
+  "no way to drive a contenteditable rich-text editor; had to skip the flow"
+```
+
+<Card
+  title="The same channel from inside a session"
+  icon="comments"
+  href="/tools-session-and-feedback"
+>
+  `reticle_feedback` when the tools are reachable.
+</Card>

package/docs/cli/gate.mdx

@@ -0,0 +1,64 @@
+---
+title: reticle gate
+description: Exit non-zero unless passing verification artifacts cover every flow the changed files affect.
+icon: shield-halved
+---
+
+`reticle gate` is what makes verification unavoidable. It computes the [affected](/cli/affected) flows, looks for a passing artifact for each, and fails the command if any is missing. An agent that edits a covered file cannot call itself finished without re-verifying.
+
+```bash
+npx @reticlehq/server gate [--since <ref>] [file...]
+```
+
+## Arguments and flags
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `file...` | strings, positional | none | Explicit changed files |
+| `--since <ref>` | string | `HEAD` when no files are given | Also include files git reports as changed since this ref |
+
+## What blocks and what does not
+
+| Category | Blocking | Why |
+| --- | --- | --- |
+| `uncovered` | Yes | An affected flow with no passing artifact |
+| `downgraded` | Yes | A flow whose assertions were weakened since its last passing run. A green bought by weakening the test is the gaming move this exists to stop |
+| `deletedCoverage` | Yes | A flow that covered a changed file and has since vanished. Coverage deleted, not satisfied |
+| `quarantined` | No | Flows the flake ledger has quarantined. Surfaced, never blocking, because one unexplained flake that blocks a merge destroys trust in the red |
+
+## What it prints
+
+One `reticle_gate` line. Real capture from this repository, with the flow lists trimmed for length:
+
+```json
+{
+  "t": "2026-08-15T18:42:58.434Z",
+  "event": "reticle_gate",
+  "pass": false,
+  "uncovered": ["WEB-flow", "deploy-journey", "verify-route", "verify-500"],
+  "quarantined": ["asserted-demo", "blast-radius-compose", "drift-demo", "qa2-flow"],
+  "coverage": { "pct": 0, "covered": 0, "total": 47 }
+}
+```
+
+`downgraded` and `deletedCoverage` appear only when they are non-empty, and neither was present in that run. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Every affected, non-flaky flow has a passing artifact and nothing was weakened or deleted |
+| `1` | Something is uncovered, downgraded or deleted. Also `1` on any internal fault: the gate fails closed |
+
+Measured on this repository, `npx @reticlehq/server gate --since HEAD~1` exited `1` with the output above: 0 of 47 flows covered, 39 uncovered and 8 quarantined.
+
+## Worked example
+
+```yaml
+- run: npx @reticlehq/server verify http://localhost:4173
+- run: npx @reticlehq/server gate --since ${{ github.event.pull_request.base.sha }}
+```
+
+<Card title="Wiring this into CI" icon="rocket" href="/deploy-checks">
+  Where the gate sits relative to build, verify, and merge.
+</Card>

package/docs/cli/help.mdx

@@ -0,0 +1,94 @@
+---
+title: reticle help
+description: Print the complete Reticle command grammar, every command and every flag, on one screen.
+icon: circle-question
+---
+
+`reticle help` prints the whole usage block to stdout and exits `0`.
+
+```bash
+npx @reticlehq/server help
+npx @reticlehq/server --help
+npx @reticlehq/server -h
+```
+
+All three are the same command.
+
+<Warning>
+  There is no per-command help. `reticle init --help` is not a help request, it is an unknown
+  argument: the parser rejects it, prints `unknown argument '--help'` followed by this same block,
+  and exits `1`. This page and the rest of this section are the per-command reference.
+</Warning>
+
+## What it prints
+
+Real capture, in full:
+
+```
+usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)
+
+  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)
+                --app picks WHICH app in a monorepo, when several are found
+                --no-mcp skips MORE than the server registration: also the agent rule files
+                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
+                only make sense once the tools are reachable.
+  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]
+  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)
+  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)
+  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)
+  reticle status [--port N]
+  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
+  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
+  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
+  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
+  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)
+  reticle watch [url]                                  (on save, report which saved flows must re-verify)
+  reticle drive <url> [--headless]                     (foreground mode, for debugging)
+  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)
+  reticle update                                       (install the latest server version and restart)
+  reticle rollback                                     (restore the previous server version and restart)
+  reticle license                                      (show enterprise license status: active | eval | missing)
+  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)
+  reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't; prints exactly what it sends)
+  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "message"
+                                                       (agents: file from anywhere, including a setup that never finished)
+  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
+                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
+
+Cloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):
+  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)
+  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)
+  reticle whoami                                        (who am I signed in as, and is this repo attached?)
+  reticle project <ls|create <name>>                   (list or create cloud projects)
+  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
+  reticle push                                          (send local run artifacts to the dashboard)
+  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)
+
+'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay
+and the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.
+```
+
+## Errors print it too
+
+Any usage error prints the offending thing first, then this same block on stderr, and exits `1`:
+
+```
+{"t":"2026-08-15T18:42:48.476Z","event":"reticle_usage_error","message":"unknown command 'nonsense-cmd'"}
+unknown command 'nonsense-cmd'
+
+usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)
+  ... the whole block above ...
+```
+
+Two audiences, two channels: the structured line for logs and scripts, the plain text for the person who just typed the command.
+
+## Exit codes
+
+| Code | Meaning                                           |
+| ---- | ------------------------------------------------- |
+| `0`  | Help was requested                                |
+| `1`  | Help was printed because something else was wrong |
+
+<Note>
+  A bare `reticle` with no arguments is **not** help. It is [`reticle serve`](/cli/serve).
+</Note>

package/docs/cli/hunt.mdx

@@ -0,0 +1,73 @@
+---
+title: reticle hunt
+description: Aggregate many crawl reports into one false-green rate across already-merged changes.
+icon: crosshairs
+---
+
+`reticle hunt` is arithmetic, not driving. You point it at a directory of crawl reports (one JSON file per checkout, each produced by `reticle_crawl`) and it turns the pile into the one number the core claim needs: across N already-merged, already-green changes, how many carried a candidate false green?
+
+```bash
+npx @reticlehq/server hunt <dir-of-crawl-reports>
+```
+
+No control arm is needed. Those changes shipped, so the counterfactual is already established.
+
+## Arguments
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `<dir>` | string, positional, **required** | none | Directory of `*.json` crawl reports. Each file is one crawl over one checkout |
+
+Each input file is read for `label` (falling back to the filename), `anomalies[]`, and `stepsRun`.
+
+## What it prints
+
+One `reticle_hunt` line with the summary. Real capture over a directory of two reports, one of them carrying a contradiction and a console error, with the `headline` sentence trimmed at the ellipsis:
+
+```json
+{
+  "t": "2026-08-15T18:43:18.333Z",
+  "event": "reticle_hunt",
+  "runs": 2,
+  "runsWithCoverage": 2,
+  "runsWithContradictions": 1,
+  "contradictions": 1,
+  "singleChannelFaults": 1,
+  "byKind": { "ui-advanced-request-failed": 1, "console-error": 1 },
+  "flagged": ["abc123"],
+  "headline": "1 of 2 merged, already-green changes carried a candidate false green (1 contradictions) ..."
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `runs` | Report files read |
+| `runsWithCoverage` | Runs that drove at least one control. The only honest denominator: a run that drove nothing is not evidence of cleanliness |
+| `runsWithContradictions` | Runs with at least one cross-channel contradiction |
+| `contradictions` | Total contradictions. The kinds are `ui-advanced-request-failed`, `signal-contradicted`, `response-ignored`, `duplicate-request`, `request-never-settled`, `failure-misattributed` |
+| `singleChannelFaults` | Everything else: console errors, failed requests, dead controls. Context, not the claim |
+| `byKind` | Counts per anomaly kind |
+| `flagged` | The labels with contradictions, so each can be confirmed by hand |
+| `headline` | A sentence phrased so it cannot overstate itself. It says "candidate", because every flag still needs manual confirmation |
+
+## Exit codes
+
+Always `0`. A read failure is logged as `reticle_hunt_failed`. Omitting the directory is a usage error:
+
+```
+{"t":"2026-08-15T18:43:06.525Z","event":"reticle_usage_error","message":"usage: reticle hunt <dir-of-crawl-reports>"}
+usage: reticle hunt <dir-of-crawl-reports>
+```
+
+That path exits `1`.
+
+## Worked example
+
+```bash
+for sha in $(git log --format=%H -n 30 main); do
+  git checkout "$sha" && npm run dev &
+  # drive reticle_crawl over the app, write the JSON:
+  # .../reports/$sha.json
+done
+npx @reticlehq/server hunt ./reports
+```