@reticlehq/server 2.8.0 → 2.10.0

package/docs/cli/doctor.mdx

@@ -1,6 +1,6 @@
 ---
 title: reticle doctor
-description: Diagnose the Reticle setup in one command: Chromium, daemon, bridge port, logs, and desktop wiring.
+description: 'Diagnose the Reticle setup in one command: Chromium, daemon, bridge port, logs, and desktop wiring.'
 icon: stethoscope
 ---
 
@@ -23,14 +23,28 @@ Human-readable lines on stdout, not the JSON log. Real capture:
 ```
 reticle doctor
   node         v22.14.0
-  chromium     ✓ installed (chromium-1223)
-  daemon       ✓ running on :4400 (pid 4795, v2.8.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 |
@@ -38,6 +52,7 @@ reticle doctor
 | `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 |
@@ -46,11 +61,29 @@ reticle doctor
 
 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.
 
-| Verdict | Real capture | What it means |
-| --- | --- | --- |
-| installed | `chromium     ✓ installed (chromium-1223)` | The wanted revision is on disk. Nothing to do |
-| wrong revision | `chromium     ✗ wrong revision — the bundled playwright wants chromium-1223; /tmp/pwroot holds chromium-1194, chromium-1208. run: npx playwright@1.60.0 install chromium` | Builds are installed, none of them the wanted one. One pinned download away |
-| missing | `chromium     ✗ missing — looked for /tmp/emptyroot/chromium-1223/chrome-mac-arm64/…; run: npx playwright@1.60.0 install chromium` | The browsers root holds no Chromium at all. If that root is not where your browsers live, `PLAYWRIGHT_BROWSERS_PATH` is what moves it |
+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.
 

package/docs/cli/drive.mdx

@@ -22,34 +22,53 @@ npx @reticlehq/server drive <url> [--headless] [--headed]
 
 ## What it prints
 
-`reticle_started` with the port on success, `reticle_start_failed` with the error otherwise.
+`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:
+Omitting the URL is a usage error. Real capture, with the usage block that follows it trimmed:
 
 ```
-{"t":"2026-08-14T19:38:46.975Z","event":"reticle_usage_error","message":"drive needs a url"}
+{"t":"2026-08-15T18:43:06.977Z","event":"reticle_usage_error","message":"drive needs a url"}
 drive needs a url
 
-usage:
-  reticle init  [--dry-run] [--port N] ...
+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                              |
-| `1`  | No URL, an unknown flag, or the engine failed to start |
+| 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`).
 
-<Warning>
-  `drive` binds the bridge port itself. If a daemon is already listening, it fails with an
-  `EADDRINUSE` stack trace, which is the normal state once your agent has started one. [`reticle
-  mcp`](/cli/mcp) reuses a running daemon; `drive` does not.
-</Warning>
+<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 stop
 npx @reticlehq/server drive http://localhost:5173
 ```

package/docs/cli/gate.mdx

@@ -32,16 +32,16 @@ One `reticle_gate` line. Real capture from this repository, with the flow lists
 
 ```json
 {
-  "t": "2026-08-14T19:38:56.353Z",
+  "t": "2026-08-15T18:42:58.434Z",
   "event": "reticle_gate",
   "pass": false,
-  "uncovered": ["deploy-journey", "verify-route", "verify-500"],
-  "quarantined": ["asserted-demo", "blast-radius-compose"],
-  "coverage": { "pct": 28, "covered": 13, "total": 47 }
+  "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.
+`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
 
@@ -50,7 +50,7 @@ One `reticle_gate` line. Real capture from this repository, with the flow lists
 | `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.
+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
 

package/docs/cli/help.mdx

@@ -16,8 +16,8 @@ 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'`, and exits `1`. This page and
-  the rest of this section are the per-command reference.
+  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
@@ -33,7 +33,9 @@ usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin i
                 (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]
+  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)
@@ -71,11 +73,11 @@ and the spec runner: batch work). --headed opts any of them in, --headless hides
 Any usage error prints the offending thing first, then this same block on stderr, and exits `1`:
 
 ```
-{"t":"2026-08-14T19:38:47.402Z","event":"reticle_usage_error","message":"unknown command 'nonsense-cmd'"}
+{"t":"2026-08-15T18:42:48.476Z","event":"reticle_usage_error","message":"unknown command 'nonsense-cmd'"}
 unknown command 'nonsense-cmd'
 
-usage:
-  ...
+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.

package/docs/cli/hunt.mdx

@@ -4,7 +4,7 @@ description: Aggregate many crawl reports into one false-green rate across alrea
 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?
+`reticle hunt` is arithmetic, not driving. You point it at a directory of crawl reports (one JSON file per checkout, each produced by `reticle_verify {action:"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>
@@ -22,7 +22,22 @@ Each input file is read for `label` (falling back to the filename), `anomalies[]
 
 ## What it prints
 
-One `reticle_hunt` line with the summary:
+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 |
 | --- | --- |
@@ -40,7 +55,8 @@ One `reticle_hunt` line with the summary:
 Always `0`. A read failure is logged as `reticle_hunt_failed`. Omitting the directory is a usage error:
 
 ```
-{"t":"2026-08-14T19:38:47.116Z","event":"reticle_usage_error","message":"usage: reticle hunt <dir-of-crawl-reports>"}
+{"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`.
@@ -50,7 +66,7 @@ That path exits `1`.
 ```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:
+  # drive reticle_verify {action:"crawl"} over the app, write the JSON:
   # .../reports/$sha.json
 done
 npx @reticlehq/server hunt ./reports

package/docs/cli/identify.mdx

@@ -4,7 +4,9 @@ description: Opt in to telling the Reticle maintainers who you are, and undo it
 icon: id-card
 ---
 
-`reticle identify` is opt-in and deliberately not interactive. A prompt in the middle of someone's work is pressure, and this is the one command where the choice has to be free. You type what you want to share, or you never run it at all.
+`reticle identify` attaches a name, a company, an email and a usage context to this machine's Reticle install and sends them to the maintainers, so support or an enterprise trial has someone to talk to. It is off unless you run it, and `reticle identify --forget` undoes it.
+
+It is opt-in and deliberately not interactive. A prompt in the middle of someone's work is pressure, and this is the one command where the choice has to be free. You type what you want to share, or you never run it at all.
 
 ```bash
 npx @reticlehq/server identify --context <company|side_project|open_source|learning> [--company "Acme"] [--email you@acme.com] [--forget]
@@ -39,7 +41,19 @@ forgotten    the local identity file is deleted; nothing further is sent.
              to have what was already sent removed, email support@reticlehq.com
 ```
 
-Run with no valid `--context`, it prints the current identity (if any), the usage, and the full consent notice.
+Run with no valid `--context`, it prints the current identity (if any), the usage, and the full consent notice, and exits `1`. Real capture on a machine with no identity on file:
+
+```
+usage: reticle identify --context <company|side_project|open_source|learning>
+       [--company "Acme"] [--email you@acme.com] [--forget]
+
+This sends the details you type here to the Reticle maintainers, so we can contact you and
+understand how teams use Reticle. It is linked to this machine's anonymous id, which means it
+also connects the anonymous usage already recorded from this machine to what you enter now.
+Nothing about your app, your code, or your repository is included, and nothing else changes.
+Undo it any time with `reticle identify --forget` (that stops future sends and deletes the local file;
+email support@reticlehq.com to have what was already sent removed).
+```
 
 <Warning>
   Identifying links this machine's anonymous id to what you type, which also connects the anonymous

package/docs/cli/init.mdx

@@ -17,7 +17,7 @@ npx @reticlehq/server init [--dry-run] [--port N] [--no-mcp] [--no-install] [--a
 | `--dry-run` | boolean | `false` | Print the full plan and write nothing |
 | `--port N` | number | unset (resolves to `4400`) | Bridge port to write into the config |
 | `--no-mcp` | boolean | `false` (MCP is registered) | Skip the MCP registration **and** the agent rule files (`CLAUDE.md`, `AGENTS.md`, `.cursor`) and the `/reticle` command |
-| `--no-install` | boolean | `false` (deps are installed) | Skip the dependency install step |
+| `--no-install` | boolean | `false` (deps are installed) | Do not run the install. The step becomes `[⚠]` and prints the `add -D` command for you to run by hand, rather than vanishing from the plan |
 | `--app <dir>` | string | unset | Pick which app to wire in a monorepo, without changing directory |
 | `--yes` | boolean | `false` | Accepted for scripting. `init` has no interactive prompts today, so it is a no-op |
 
@@ -28,7 +28,7 @@ npx @reticlehq/server init [--dry-run] [--port N] [--no-mcp] [--no-install] [--a
 
 ## What it prints
 
-A plan, one line per step, each with a status mark: `✓` written, `·` already in place or left alone, `⚠` needs a hand. Captured from a real run inside `apps/bench-app`:
+A plan, one line per step, each with a status mark: `✓` written, `·` already in place or left alone, `⚠` needs a hand, `–` deliberately skipped by a flag. Captured from a real `--dry-run` inside `apps/bench-app`:
 
 ```
 reticle init (dry run, no files written)
@@ -46,6 +46,10 @@ reticle init (dry run, no files written)
 
   [✓] Agent verification rule → CLAUDE.md
       teach the agent to verify features with Reticle after building them
+  [✓] Agent verification rule → AGENTS.md
+      teach the agent to verify features with Reticle after building them
+  [✓] Full agent rules → RETICLE.md
+      the reference the always-loaded rule points at (when NOT to verify, recovery, feedback)
   [✓] The /reticle command → .claude/commands/reticle.md
       type /reticle to verify one flow in the browser
   [✓] Install dependencies → package.json
@@ -60,7 +64,16 @@ reticle init (dry run, no files written)
 Restart `vite`.
 ```
 
-Run from a workspace root with several apps, it refuses to guess and names them instead:
+Below the plan it also prints the two things that actually finish the install: restart your agent so it re-reads its MCP server list, then run `npx @reticlehq/server status` to confirm the app connected.
+
+With `--no-mcp`, the whole MCP and rules group collapses into one skipped line:
+
+```
+  [–] MCP server (global) → global (claude user scope)
+      --no-mcp ... also skips the agent rule files (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command
+```
+
+Run from a workspace root with several apps, it refuses to guess, names them, and exits `1`:
 
 ```
 Several apps found in this workspace. Re-run `reticle init` inside the one you want:
@@ -68,17 +81,31 @@ Several apps found in this workspace. Re-run `reticle init` inside the one you w
   packages/vite-plugin
   apps/atlas
   apps/bench-app
-  ...
+  apps/electron-smoke
+  apps/large-dom-bench
+  apps/next-smoke
+  apps/tauri-smoke
+  apps/vibe-builder-demo
 
 Or name one without changing directory:  reticle init --app packages/next
 ```
 
+Given `--app`, it says which directory it moved to before printing the plan:
+
+```
+No app in this directory ... wiring apps/bench-app instead.
+```
+
+In the two captures above, the punctuation that separates the two halves of the sentence is shown as `...`.
+
 ## Exit codes
 
-| Code | Meaning                                                                      |
-| ---- | ---------------------------------------------------------------------------- |
-| `0`  | The plan ran. Steps marked `⚠` still need a hand, and do not change the code |
-| `1`  | Init failed, or an unknown flag was passed                                   |
+| Code | Meaning                                                                                 |
+| ---- | --------------------------------------------------------------------------------------- |
+| `0`  | The plan ran. Steps marked `⚠` still need a hand, and do not change the code            |
+| `1`  | Init failed, an unknown flag was passed, or several apps were found and none was chosen |
+
+An unknown flag is rejected by name: `reticle init --bogus` prints `unknown argument '--bogus'`, then the full usage block, and exits `1`.
 
 ## Worked example
 

package/docs/cli/kill.mdx

@@ -47,24 +47,24 @@ Reach for `stop` in a script that shuts down a daemon it started. Reach for `kil
 
 ## What it prints
 
-Real captures.
+Real captures, taken against a daemon started on a scratch port. The long `note` and `reason` strings are trimmed at the ellipsis. Measured exit codes: `0` for killed and nothing-to-do, `1` for refused.
 
 Killed:
 
 ```
-{"event":"reticle_killed","port":4499,"pid":84420,"escalated":true,"listenerIdentified":true,"note":"only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, not the port, and was left alone — it goes dormant and starts a fresh daemon on the next tool call."}
+{"t":"2026-08-15T18:43:43.590Z","event":"reticle_killed","port":4499,"pid":78621,"escalated":false,"listenerIdentified":true,"note":"only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, not the port, and was left alone ..."}
 ```
 
-Refused, because the listener is not ours:
+Refused, because the listener is not ours. This one was captured with `python3 -m http.server 4498` holding the port:
 
 ```
-{"event":"reticle_kill_refused","port":4498,"reason":"pid 84346 (\"Python\") is listening, and it is not a Reticle daemon — it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. Run it again with --force if that is what you meant, or start Reticle on another port.","holder":"Python"}
+{"t":"2026-08-15T18:43:57.128Z","event":"reticle_kill_refused","port":4498,"reason":"pid 78795 (\"Python\") is listening, and it is not a Reticle daemon ... it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. Run it again with --force if that is what you meant, or start Reticle on another port.","holder":"Python"}
 ```
 
 Nothing to free:
 
 ```
-{"event":"reticle_kill_nothing_to_do","port":4499,"presence":"free"}
+{"t":"2026-08-15T18:43:43.784Z","event":"reticle_kill_nothing_to_do","port":4499,"presence":"free"}
 ```
 
 | Event | When |

package/docs/cli/license.mdx

@@ -18,7 +18,7 @@ One `reticle_license` line. Real capture on a checkout with no issuer key config
 
 ```json
 {
-  "t": "2026-08-14T19:38:38.331Z",
+  "t": "2026-08-15T18:42:26.758Z",
   "event": "reticle_license",
   "status": "eval",
   "detail": "evaluation mode: enterprise features run free (no issuer key configured)"

package/docs/cli/open.mdx

@@ -40,6 +40,12 @@ One `reticle_open` line, whose fields say which of four things happened.
 {"event":"reticle_open","port":4499,"error":"could not launch a browser: spawn open ENOENT","recovery":"Nothing was opened. This command asks the OS to open a url in your default browser (`open` on this platform) and that failed, so the fix is on the OS side: open the url yourself, or set a default browser."}
 ```
 
+Calling it with no URL when nothing has connected is the other `error` shape. It exits `0`, because reporting "there is nothing to show you" is a complete answer. Real capture, with the sentence break shown as `...`:
+
+```
+{"t":"2026-08-15T18:43:41.651Z","event":"reticle_open","port":4499,"error":"no app connected ... pass a url: reticle open <url>. Desktop app (Electron/Tauri)? There is no url to open: start it as you normally would and it connects to this bridge itself."}
+```
+
 </Note>
 
 <Warning>

package/docs/cli/restart.mdx

@@ -21,18 +21,18 @@ npx @reticlehq/server restart [--port N] [--force]
 
 A restart that killed the old daemon and then could not start a new one leaves you somewhere quite different from one that could not kill anything at all, and a single `ok: false` cannot tell you which happened. So each half prints its own line.
 
-Real capture, restarting over a running daemon:
+Real capture, restarting over a running daemon (exit `0`), with the long `note` trimmed at the ellipsis:
 
 ```
-{"event":"reticle_killed","port":4499,"pid":84513,"escalated":false,"listenerIdentified":true,"note":"only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, not the port, and was left alone — it goes dormant and starts a fresh daemon on the next tool call."}
-{"event":"reticle_daemon_spawned","port":4499}
+{"t":"2026-08-15T18:43:41.949Z","event":"reticle_killed","port":4499,"pid":78137,"escalated":false,"listenerIdentified":true,"note":"only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, not the port, and was left alone ..."}
+{"t":"2026-08-15T18:43:42.258Z","event":"reticle_daemon_spawned","port":4499}
 ```
 
-Real capture, when the port is held by something that is not ours:
+Real capture, when the port is held by something that is not ours (exit `1`). Both `reason` strings are trimmed at the ellipsis:
 
 ```
-{"event":"reticle_kill_refused","port":4498,"reason":"pid 84537 (\"Python\") is listening, and it is not a Reticle daemon — it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. Run it again with --force if that is what you meant, or start Reticle on another port.","holder":"Python"}
-{"event":"reticle_restart_aborted","port":4498,"reason":"the port was not freed, so nothing was started — the old holder is still there"}
+{"t":"2026-08-15T18:43:57.317Z","event":"reticle_kill_refused","port":4498,"reason":"pid 78795 (\"Python\") is listening, and it is not a Reticle daemon ... it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. Run it again with --force if that is what you meant, or start Reticle on another port.","holder":"Python"}
+{"t":"2026-08-15T18:43:57.318Z","event":"reticle_restart_aborted","port":4498,"reason":"the port was not freed, so nothing was started ... the old holder is still there"}
 ```
 
 <Note>

package/docs/cli/serve.mdx

@@ -29,13 +29,20 @@ Most people never type this. Your agent runs [`reticle mcp`](/cli/mcp), which st
 One structured line. When a daemon already owns the port, it says so and does nothing:
 
 ```json
-{ "t": "2026-08-14T19:39:13.230Z", "event": "reticle_daemon_already_running", "port": 4400 }
+{ "t": "2026-08-15T18:43:33.065Z", "event": "reticle_daemon_already_running", "port": 4499 }
 ```
 
-A successful spawn logs `reticle_daemon_spawned` with the port. A port held by something that is not a Reticle daemon is refused up front rather than spawned into:
+A successful spawn logs `reticle_daemon_spawned` with the port:
+
+```json
+{ "t": "2026-08-15T18:43:32.604Z", "event": "reticle_daemon_spawned", "port": 4499 }
+```
+
+A port held by something that is not a Reticle daemon is refused up front rather than spawned into. The reason is repeated as plain text on stderr for the person who typed the command. Real capture, with `python3 -m http.server 4498` holding the port and the punctuation between the two halves of the reason shown as `...`:
 
 ```
-reticle_daemon_start_refused
+{"t":"2026-08-15T18:43:57.478Z","event":"reticle_daemon_start_refused","port":4498,"presence":"foreign","reason":"port 4498 is held by another process that is not a Reticle daemon ... a daemon cannot bind it. Stop that process, or run Reticle on a different port (`--port`), then retry."}
+port 4498 is held by another process that is not a Reticle daemon ... a daemon cannot bind it. Stop that process, or run Reticle on a different port (`--port`), then retry.
 ```
 
 ## Exit codes

package/docs/cli/status.mdx

@@ -22,23 +22,47 @@ One JSON line on stdout. Real capture, daemon up and no app connected:
 
 ```json
 {
-  "t": "2026-08-14T19:38:37.737Z",
+  "t": "2026-08-15T18:43:33.724Z",
   "event": "reticle_status",
-  "port": 4400,
+  "port": 4499,
   "running": true,
-  "pid": 4795,
+  "pid": 78137,
   "sessionCount": 0,
   "sessions": [],
-  "why": "no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is listening on the ports Reticle scans ... (2) There is no `.reticle.json` in the directory this daemon is running in ..."
+  "why": "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 ... (2) There is no `.reticle.json` in the directory this daemon is running in ..."
 }
 ```
 
+With an app connected, `why` is absent and each session carries its own fields:
+
+```json
+{
+  "t": "2026-08-15T18:45:58.190Z",
+  "event": "reticle_status",
+  "port": 4400,
+  "running": true,
+  "pid": 72698,
+  "sessionCount": 1,
+  "sessions": [
+    {
+      "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
+      "url": "http://localhost:4310/",
+      "throttled": false,
+      "stale": false,
+      "pendingMarks": 0
+    }
+  ]
+}
+```
+
+Both are one line of JSON in the terminal, pretty-printed here, with `why` trimmed at the ellipses.
+
 | Field | Meaning |
 | --- | --- |
 | `running` | Whether a usable daemon owns the port |
 | `presence` | Present when the pid file is dead: `daemon`, `foreign`, or `absent`. The port is asked, not just the pid file |
 | `pid` | The daemon process |
-| `sessionCount` / `sessions` | Connected app sessions, each with `sessionId`, `url`, `throttled`, `stale` |
+| `sessionCount` / `sessions` | Connected app sessions, each with `sessionId`, `url`, `throttled`, `stale`, `pendingMarks` |
 | `why` | Present when zero sessions connected. Names the two likely causes and refuses to assert either |
 | `updateAvailable` | Present when a newer server version is on the registry |
 

package/docs/cli/stop.mdx

@@ -31,6 +31,14 @@ npx @reticlehq/server stop [--port N] [--quiet]
 | `reticle_daemon_not_running` | No live pid for that port. The stale pid file is removed |
 | `reticle_daemon_stop_timeout` | It survived everything. Exits `1` |
 
+Real capture, stopping a port with no live pid recorded for it. It exits `0`, because "already not running" is the state you asked for:
+
+```
+{"t":"2026-08-15T18:43:43.943Z","event":"reticle_daemon_not_running","port":4499}
+```
+
+With `--quiet` that same run prints nothing at all and still exits `0`.
+
 ## Exit codes
 
 | Code | Meaning                        |

package/docs/cli/verify.mdx

@@ -27,17 +27,36 @@ The rendered run report on stdout. On failure it names the cause on stderr inste
 
 ```
 No app connected: Reticle drove the URL but no @reticlehq/browser session dialed back.
-  Make sure the SDK is in the build and reticle.connect() runs on the preview page
+  Make sure the SDK is in the build and reticle.connect() runs on the preview page (for a non-localhost preview: allowNonLocalhost + a pairing token).
 ```
 
 ```
 No saved flows to verify (.reticle/flows is empty), so refusing to report a pass for verifying nothing.
+  Flows are recorded interactively by an agent (reticle_record{action:"start"} → act → reticle_flow_save via the
+  MCP tools), then committed to .reticle/flows/. In CI, check those files in and re-run `reticle verify`.
 ```
 
 <Warning>
   Both of those are honesty guards, and both exit `1`. Verifying nothing is never a pass.
 </Warning>
 
+A URL that does not answer is not one of those two. It surfaces as the underlying Playwright error, prefixed with `verify failed:`, and also exits `1`. Real capture:
+
+```
+verify failed: page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:59999/
+Call log:
+  - navigating to "http://localhost:59999/", waiting until "domcontentloaded"
+```
+
+<Warning>
+  `verify` binds the bridge port itself and has **no `--port` flag**: passing one is rejected as
+  `unknown argument '--port'`. If a daemon is already on the port, `verify` dies with a raw `Error:
+  listen EADDRINUSE: address already in use 127.0.0.1:4400` stack trace before it drives anything.
+  Stop the daemon first, or move `verify` with the `RETICLE_PORT` environment variable. This bites
+  most often on a developer machine, where an agent has usually left a daemon running; in CI the
+  port is normally free.
+</Warning>
+
 ## Exit codes
 
 | Code | Meaning                                                           |

package/docs/cli/version.mdx

@@ -19,7 +19,7 @@ All three are the same command. No flags.
 One `reticle_version` line. Real capture:
 
 ```json
-{ "t": "2026-08-14T19:38:37.595Z", "event": "reticle_version", "version": "2.8.0" }
+{ "t": "2026-08-15T18:42:26.275Z", "event": "reticle_version", "version": "2.8.0" }
 ```
 
 ## Exit codes