@reticlehq/server 3.6.0 → 3.7.0

package/docs/cli/license.mdx

@@ -14,24 +14,28 @@ No flags.
 
 ## What it prints
 
-One `reticle_license` line. Real capture on a checkout with no issuer key configured:
+One `reticle_license` JSON line, on stderr. On a checkout with no issuer key configured:
 
 ```json
 {
   "t": "2026-08-15T18:42:26.758Z",
   "event": "reticle_license",
+  "gated": ["audit-log"],
+  "contact": "hey@reticle.sh",
   "status": "eval",
   "detail": "evaluation mode: enterprise features run free (no issuer key configured)"
 }
 ```
 
-| `status`  | Meaning                                       |
-| --------- | --------------------------------------------- |
-| `active`  | A valid license is present                    |
-| `eval`    | Evaluation mode. Enterprise features run free |
-| `missing` | No license, and the build expects one         |
+| `status`  | Meaning                                             |
+| --------- | --------------------------------------------------- |
+| `active`  | A valid license is present                          |
+| `eval`    | Evaluation mode. Enterprise features run free       |
+| `missing` | No license, and the build expects one               |
+| `expired` | The key verified, but its expiry has passed         |
+| `invalid` | The key was rejected, or the build is misconfigured |
 
-`detail` is a sentence explaining the status.
+`detail` is a sentence explaining the status. An active license also carries `licenseId`, `org`, `plan` and `expiresAt`.
 
 ## Exit codes
 
@@ -40,7 +44,7 @@ Always `0`.
 ## Worked example
 
 ```bash
-npx @reticlehq/server license | jq -r .status
+npx @reticlehq/server license 2>&1 | jq -r .status
 ```
 
 <Card title="What enterprise covers" icon="building" href="/enterprise">

package/docs/cli/mcp.mdx

@@ -18,15 +18,15 @@ This is what `reticle init` registers, so you rarely type it yourself.
 | --- | --- | --- | --- |
 | `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Bridge port |
 | `--drive <url>` | string | unset | Have the daemon launch its own browser at this URL, so the agent has autonomous control without relying on your tab |
-| `--headless` | boolean | `true` for `mcp` | Hide that browser |
-| `--headed` | boolean | `false` | Show it |
+| `--headless` | boolean | on when `CI` or `RETICLE_HEADLESS` is set, or on Linux with no display | Hide that browser |
+| `--headed` | boolean | on otherwise | Show it |
 | `--http` | boolean | `false` | Forward the HTTP verify endpoint flags to the daemon it spawns |
 | `--http-port N` | number | unset | Port for that endpoint |
 | `--http-token T` | string | unset | Bearer token for it |
 
 ## The rule this command lives by
 
-The proxy **is** the MCP server the editor launched. Nothing respawns it, so an uncaught throw here is what a user experiences as "the MCP server disconnected". Three behaviours follow from that:
+The proxy **is** the MCP server the editor launched. Nothing respawns it, so an uncaught throw here is what a user experiences as "the MCP server disconnected". Four behaviours follow from that:
 
 - Crash handlers write to the proxy's own log file, not just stderr, because the editor swallows stderr.
 - A daemon that is not there is not fatal. The proxy answers `initialize` itself, serves the cached tool catalog, and retries a daemon on every client request. Present and complaining beats absent, because absent needs a human.
@@ -35,7 +35,7 @@ The proxy **is** the MCP server the editor launched. Nothing respawns it, so an
 
 ## What it prints
 
-Structured lines to the proxy log (`~/.reticle/`), not to your terminal, since stdout is the MCP transport.
+Structured JSON lines on stderr, never stdout, since stdout is the MCP transport. Most editors swallow stderr, so the idle exit and the crash handlers also write to the proxy log, `~/.reticle/proxy-<port>.log`.
 
 | Event | Meaning |
 | --- | --- |

package/docs/cli/open.mdx

@@ -1,10 +1,10 @@
 ---
 title: reticle open
-description: Show the app in a browser, reusing the already-connected tab when there is one.
+description: Open the app in your default browser, or reuse a tab that is already connected.
 icon: window-maximize
 ---
 
-`reticle open` is the one-command "show me the app". It resolves the port, makes sure a daemon is up, and then either reuses the tab that is already connected or opens a new one.
+`reticle open` is the one-command "show me the app". It resolves the port, makes sure a daemon is up, and then either reuses the tab that is already connected or hands the URL to your operating system's default browser. It never opens the browser Reticle drives.
 
 ```bash
 npx @reticlehq/server open [url] [--port N]
@@ -27,7 +27,7 @@ One `reticle_open` line, whose fields say which of four things happened.
 | --- | --- |
 | `reusing` | A connected tab was already on the right page. Nothing was opened |
 | `reusing` + `requested` + `note` | A tab is connected on that origin but sitting on a different page. It was **left there**, not navigated. Drive it with `reticle_navigate` or open the URL yourself |
-| `opened` + `connected: true` | A browser was launched and a Reticle session appeared |
+| `opened` + `connected: true` | The URL went to the system default browser and a new Reticle session appeared within 8 seconds |
 | `opened` + `connected: false` + `note` | The URL went to the system default browser and no session showed up within 8 seconds. Almost always means the app carries no SDK, or dials a different port |
 | `error` | No app connected and no URL given, or the browser could not be launched |
 

package/docs/cli/report.mdx

@@ -15,7 +15,7 @@ npx @reticlehq/server report [--session <id>] [--hook]
 | Flag | Default | What it does |
 | --- | --- | --- |
 | `--session <id>` | the newest session | Report a specific session |
-| `--hook` | off | Print one line, and only when the working tree changed and no claim held |
+| `--hook` | off | Print a short message, and only when the working tree changed and no claim held |
 
 ## What it prints
 
@@ -27,11 +27,13 @@ session lease-85f8191b-3874-457b-973b-8ee365e5acfb
   ✗ signal order:placed
 ```
 
+The report ends with one more line, an invitation to talk to the founder or leave an email. A session with no claims prints `no claims this session, so nothing was verified`.
+
 An `unknown` is never counted as held. It is Reticle saying it could not tell, and the owner beside it says what to do next.
 
 ## As a Claude Code Stop hook
 
-With `--hook` it prints nothing when a claim held or nothing in the tree changed, and otherwise one line, such as `Reticle: not verified. 3 claims: 1 failed, 2 unknown`. It prints Claude Code's `systemMessage` shape and always exits `0`: you see the line when the agent stops, and the agent is never blocked by it. `reticle init --hooks` adds it for you, merged into whatever `.claude/settings.json` already holds. By hand:
+With `--hook` it prints nothing when a claim held or nothing in the tree changed, and otherwise one line, such as `Reticle: not verified. 3 claims: 1 failed, 2 unknown`, followed by the same invitation line. It prints Claude Code's `systemMessage` shape and always exits `0`: you see the line when the agent stops, and the agent is never blocked by it. `reticle init --hooks` adds it for you, merged into whatever `.claude/settings.json` already holds. By hand:
 
 ```json
 {

package/docs/cli/restart.mdx

@@ -4,7 +4,7 @@ description: Free the bridge port and put a daemon back on it, reporting each ha
 icon: rotate
 ---
 
-`reticle restart` is [`reticle kill`](/cli/kill) followed by a daemon start that waits for a real bind.
+`reticle restart` is [`reticle stop --force`](/cli/stop#freeing-the-port-force) followed by a daemon start that waits for a real bind.
 
 ```bash
 npx @reticlehq/server restart [--port N] [--force]
@@ -55,6 +55,6 @@ npx @reticlehq/server restart         # after an upgrade, so the new version is
 npx @reticlehq/server status
 ```
 
-<Card title="Why not lsof" icon="skull" href="/cli/kill">
+<Card title="Why not lsof" icon="skull" href="/cli/stop#freeing-the-port-force">
   The pipeline everyone reaches for kills the agent's own MCP proxy along with the daemon.
 </Card>

package/docs/cli/rollback.mdx

@@ -1,10 +1,10 @@
 ---
 title: reticle rollback
-description: Restore the previously installed Reticle server version and restart.
+description: Reinstall the previously installed Reticle server version, then exit so your agent restarts it.
 icon: arrow-rotate-left
 ---
 
-`reticle rollback` is the undo for [`reticle update`](/cli/update). It restores the previous server version and restarts.
+`reticle rollback` is the undo for [`reticle update`](/cli/update). It reinstalls the version `update` replaced (recorded in the update manifest), then exits so the next start runs it.
 
 ```bash
 npx @reticlehq/server rollback
@@ -14,7 +14,11 @@ No flags.
 
 ## What it prints
 
-Nothing on the happy path: `rollback()` replaces the process. A failure logs `reticle_rollback_failed` with the error message.
+Two structured lines on the happy path, `reticle_rollback_applying` and `reticle_rollback_applied`, each with the `version` and the `executionKind` (`global`, `local` or `npx`). A failure logs `reticle_rollback_failed` with the error message.
+
+<Warning>
+  Run from a one-off `npx` download (no global or project install), there is nothing to reinstall. It logs `reticle_rollback_npx_strategy` with a note to pin the version in your MCP config (for example `@reticlehq/server@<version>` in `.mcp.json`), and does not exit. Pin the version there yourself.
+</Warning>
 
 Telemetry records the move as a `version_changed` event with `direction: "rollback"`, which is treated as a release-quality alarm rather than a routine version move.
 
@@ -22,14 +26,16 @@ Telemetry records the move as a `version_changed` event with `direction: "rollba
 
 | Code | Meaning                                                     |
 | ---- | ----------------------------------------------------------- |
-| `0`  | The previous version was restored (the process is replaced) |
+| `0`  | The previous version was reinstalled and the process exited |
 | `1`  | There was nothing to roll back to, or the restore threw     |
 
 ## Worked example
 
-```bash
-npx @reticlehq/server update
+On the global install the installer puts on your PATH (under `npx` there is nothing to roll back):
+
+```text
+reticle update
 # the new build misbehaves:
-npx @reticlehq/server rollback
-npx @reticlehq/server version
+reticle rollback
+reticle version
 ```

package/docs/cli/serve.mdx

@@ -16,10 +16,10 @@ Most people never type this. Your agent runs [`reticle mcp`](/cli/mcp), which st
 
 | Flag | Type | Default | What it does |
 | --- | --- | --- | --- |
-| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Bridge port to bind |
+| `--port N` | number | `RETICLE_PORT`, else the port in `.reticle.json`, else the daemon already serving this project, else `4400` | Bridge port to bind |
 | `--drive <url>` | string | unset | Launch Reticle's own browser at this URL instead of waiting for your tab |
-| `--headless` | boolean | `true` for `serve` | Hide the browser |
-| `--headed` | boolean | `false` | Show it. `serve` owns the pooled browser behind leases, which is batch work, so it hides by default |
+| `--headless` | boolean | on when `CI` or `RETICLE_HEADLESS` is set (and not `0` or `false`), or on Linux with no display | Hide the browser |
+| `--headed` | boolean | on otherwise | Show it, so you can watch the run |
 | `--http` | boolean | `false` | Also expose the HTTP verify endpoint |
 | `--http-port N` | number | unset (`7331`) | Port for that endpoint. Requires `--http`. |
 | `--http-token T` | string | unset | Bearer token the endpoint requires. Requires `--http`. |
@@ -34,7 +34,7 @@ One structured line. When a daemon already owns the port, it says so and does no
 { "t": "2026-08-15T18:43:33.065Z", "event": "reticle_daemon_already_running", "port": 4499 }
 ```
 
-A successful spawn logs `reticle_daemon_spawned` with the port:
+Once the spawned daemon answers, it logs `reticle_daemon_spawned` with the port:
 
 ```json
 { "t": "2026-08-15T18:43:32.604Z", "event": "reticle_daemon_spawned", "port": 4499 }

package/docs/cli/setup.mdx

@@ -0,0 +1,23 @@
+---
+title: reticle setup mcp
+description: Register the Reticle MCP server with every coding agent on this machine.
+icon: plug
+---
+
+`reticle setup mcp` registers the Reticle MCP server with the coding agents on this machine, so the `reticle_*` tools are there the next time each one starts. It is the registration half of the [installer](/quickstart), and you rarely need to run it yourself.
+
+```bash
+npx @reticlehq/server setup mcp
+```
+
+No flags, and nothing is asked. It works for your user account, not for one project, so it does not touch your app. To wire an app, run [`reticle init`](/cli/init).
+
+## What it prints
+
+One line per agent: `✓ <agent>` for a new registration, `✓ <agent> (already set up)` when Reticle was there already, `⚠ <agent>: Reticle registration failed…` when a registration failed (the command then exits `1`), and `⚠ <agent>: add the reticle entry to <path> by hand` for a config it will not rewrite. If it finds no agent, it names every agent it looked for.
+
+## How you know it worked
+
+Restart your coding agent. An agent reads its server list only when it starts. After the restart, the `reticle_*` tools are listed.
+
+Codex CLI keeps a TOML config that Reticle does not rewrite. When the `codex` binary is on your PATH, Reticle registers through `codex mcp add` instead; otherwise it prints the hand-edit line above.

package/docs/cli/status.mdx

@@ -1,10 +1,10 @@
 ---
 title: reticle status
-description: Ask whether the Reticle daemon is up and which app sessions have connected to it.
+description: Ask whether the Reticle daemon is up, which app sessions have connected, who is signed in, and whether this folder is linked.
 icon: heart-pulse
 ---
 
-`reticle status` is the command that tells you whether the install actually finished. Not a tick in a checklist: a connected app.
+`reticle status` tells you whether the daemon is up and which pages connected, who you are signed in to Reticle Cloud as, and whether this folder is linked to a cloud project. The account facts come from local files; no network call is made. A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
 
 ```bash
 npx @reticlehq/server status [--port N] [--json]
@@ -19,6 +19,13 @@ npx @reticlehq/server status [--port N] [--json]
 
 ## What it prints
 
+The block also carries an account row: who you are signed in as and the cloud project this folder is linked to, or what to run (`reticle connect`) when it is not. `reticle whoami` is the old name for this question; it still works for one release.
+
+```text
+  account      ✓ signed in as Acme
+               this repo is not linked: run `reticle connect`
+```
+
 A short block, for whoever is reading the terminal. Real capture, daemon up with two apps connected:
 
 ```text
@@ -35,6 +42,7 @@ And with no daemon on the port:
 ```text
 reticle status
   daemon       ✗ not running on :4999
+               port presence: free
   agent link   never-attached
   next         no daemon is running on this port, which is normal. An agent starts it when it
                first calls a Reticle tool, and it exits again when idle. Ask your agent to verify
@@ -71,6 +79,7 @@ It is one line in the terminal, pretty-printed here, with `why` trimmed at the e
   "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
   "url": "http://localhost:4310/",
   "throttled": false,
+  "hidden": false,
   "stale": false,
   "pendingMarks": 0
 }
@@ -79,9 +88,9 @@ It is one line in the terminal, pretty-printed here, with `why` trimmed at the e
 | 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 |
+| `presence` | Present when no usable daemon answered: `foreign` (something else holds the port) or `free`. The port is asked, not just the pid file |
 | `pid` | The daemon process |
-| `sessionCount` / `sessions` | Connected app sessions, each with `sessionId`, `url`, `throttled`, `stale`, `pendingMarks` |
+| `sessionCount` / `sessions` | Connected app sessions, each with `sessionId`, `url`, `throttled`, `hidden`, `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

@@ -1,21 +1,24 @@
 ---
 title: reticle stop
-description: Stop the Reticle daemon on a port, escalating from SIGTERM to SIGKILL if it will not go.
+description: Stop the Reticle daemon on a port, or free the port by its listener with --force, never touching the agent's MCP proxy.
 icon: circle-stop
 ---
 
-`reticle stop` reads the pid recorded for the port and stops that process.
+`reticle stop` reads the pid recorded for the port and stops that process. `reticle stop --force` asks **who is listening** on the port instead, and frees it.
 
 ```bash
-npx @reticlehq/server stop [--port N] [--quiet]
+npx @reticlehq/server stop [--port N] [--quiet] [--force]
 ```
 
+`reticle kill` is the old name for `stop --force`. It still works for one release and prints one line naming the new spelling.
+
 ## Flags
 
 | Flag | Type | Default | What it does |
 | --- | --- | --- | --- |
 | `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which daemon to stop |
 | `--quiet` | boolean | `false` | Print nothing. For scripts that stop a daemon that may not be running |
+| `--force` | boolean | `false` | Find the process by the **listener** on the port, not by the recorded pid. See [Freeing the port](#freeing-the-port-force) |
 
 ## How it stops
 
@@ -28,7 +31,7 @@ npx @reticlehq/server stop [--port N] [--quiet]
 | Event | When |
 | --- | --- |
 | `reticle_daemon_stopped` | It stopped. Carries `port`, `pid`, and `escalated: true` if it took a `SIGKILL` |
-| `reticle_daemon_not_running` | No live pid for that port. The stale pid file is removed |
+| `reticle_daemon_not_running` | No live pid for that port, and nothing answers `/status` on it. 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:
@@ -48,17 +51,73 @@ With `--quiet` that same run prints nothing at all and still exits `0`.
 
 <Warning>
   Do not stop a daemon with `lsof -ti tcp:4400 | xargs kill -9`. That pattern matches the agent's
-  own `reticle mcp` proxy as well as the daemon and takes both down. Use this command, or [`reticle
-  kill`](/cli/kill).
+  own `reticle mcp` proxy as well as the daemon and takes both down. Use this command, or `reticle
+  stop --force`.
+</Warning>
+
+## Freeing the port: `--force`
+
+`stop` starts from the pid Reticle recorded. When that pid is dead or missing but a Reticle daemon still answers `/status` on the port (a stale pid file, or a daemon from another checkout), plain `stop` frees that listener the same way `--force` does. When nothing answers `/status`, plain `stop` reports `reticle_daemon_not_running`. `stop --force` always asks the **port** first, and is the command to reach for when the pid file and the port disagree.
+
+<Warning>
+  Never free the port with `lsof -ti tcp:4400 | xargs kill -9`. `reticle mcp` holds a **client**
+  socket on that port, so `-ti` lists the proxy right beside the daemon and the pipeline kills both.
+  When the proxy dies, the agent's next tool calls get no reply at all: not an error, not a timeout.
+  Nothing is written to the proxy log either, because the process that writes it is the one that
+  died. That is the mechanism behind most "my MCP disconnected" reports.
 </Warning>
 
-## When this is not enough
+|  | `reticle stop` | `reticle stop --force` |
+| --- | --- | --- |
+| Finds the process by | the pid recorded in Reticle's own state | the **listener** on the port |
+| Works when the pid file is stale or was never written | yes, when the daemon answers `/status` | yes |
+| Works on a daemon from another checkout | yes, when it answers `/status` | yes |
+| Works without `lsof` (Windows, slim containers) | yes | yes, falling back to the recorded pid and saying so |
+
+### How `--force` decides
+
+1. Look up the listener with `lsof -nP -iTCP:<port> -sTCP:LISTEN`. Client sockets are excluded by construction, so the proxy is never a candidate.
+2. It is Reticle's if it answers `/status`, **or** if it is the pid Reticle recorded for the port. `/status` outranks the pid file, so a daemon started from another checkout is still recognised as ours.
+3. Anything else is refused, by name: it is someone else's process.
+4. `SIGTERM`, then `SIGKILL` after 5 seconds, then report that it survived and exit `1`.
+
+### What `--force` prints
+
+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:
+
+```
+{"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. This one was captured with `python3 -m http.server 4498` holding the port:
+
+```
+{"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:
+
+```
+{"t":"2026-08-15T18:43:43.784Z","event":"reticle_kill_nothing_to_do","port":4499,"presence":"free"}
+```
+
+| Event                        | When                                                              |
+| ---------------------------- | ----------------------------------------------------------------- |
+| `reticle_killed`             | The listener is gone. `escalated: true` means it took a `SIGKILL` |
+| `reticle_kill_refused`       | The listener is not a Reticle daemon. Exits `1`                   |
+| `reticle_kill_survived`      | It survived `SIGKILL`. The port is still held. Exits `1`          |
+| `reticle_kill_nothing_to_do` | No listener, and no live recorded pid                             |
+
+`listenerIdentified: false` means `lsof` could not run and the pid came from Reticle's records rather than from an observed listener. Those are different claims, so the field says which one you got.
 
-`stop` needs the pid Reticle recorded. If the pid file is stale, was never written, or the port is held by a daemon from another checkout, `stop` reports `reticle_daemon_not_running` about a port that is demonstrably occupied. [`reticle kill`](/cli/kill) asks the **port** instead and is the command for that case.
+With `--force`, exit `0` means the port is free and `1` means it is still held: refused, or the process survived `SIGKILL`.
 
 ## Worked example
 
 ```bash
 npx @reticlehq/server stop --port 4400 --quiet && npx @reticlehq/server serve --port 4400
 npx @reticlehq/server restart --port 4400   # the same thing, honest about each half
+npx @reticlehq/server stop --force          # the port is held and the pid file says nothing
 ```

package/docs/cli/try.mdx

@@ -0,0 +1,62 @@
+---
+title: reticle try
+description: Sign in, then watch Reticle drive any URL once and say which journeys work.
+icon: play
+---
+
+`reticle try` is the fastest way to see Reticle on your own app. It drives a URL once with the Reticle Harness, in a browser window you can watch, and ends with a list of the journeys it tried and how each one ended.
+
+```bash
+npx @reticlehq/server try <url> [--persona <who>]
+```
+
+The app needs nothing installed. A page with no Reticle SDK gets one supplied for the drive, so verdicts cover the DOM, network, console and routes. There is no component state and no source `file:line` until you run [`reticle init`](/cli/init).
+
+## Sign in first
+
+The drive runs on the Reticle platform, so `try` needs a linked folder. On a machine that is not linked it drives nothing and says:
+
+```
+Sign in first: reticle connect (it is free, no card)
+```
+
+Run [`reticle connect`](/cli/cloud) in the folder, then run `try` again. It exits `1` in this case.
+
+## Arguments and flags
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `url` | string, positional, **required** | none | The page to drive. It must already be running |
+| `--persona <who>` | string | unset | Who to be, or what to get done ("a returning customer checking out"). Without it, the platform plans the journeys from what the page offers |
+
+## What happens
+
+1. `try` asks the platform for one free drive. If the workspace needs a card first, it prints the platform's message and the plan page, then exits `1` without opening anything.
+2. It opens the URL in a window you can watch, through the Reticle daemon, and starting one if none is running.
+3. The Harness drives for up to two minutes and 40 steps, and records what it drove as saved flows.
+4. It prints the result and sends the run to your dashboard, the same way [`reticle sync`](/cli/cloud#reticle-sync) does.
+
+## What it prints
+
+A `Driving <url>` line first, telling you to watch the window, then:
+
+```
+Tried 3 journeys: 1 work, 1 broken, 1 not proved
+  ✓ works: Shopper: checks out
+  ✗ broken: Shopper: applies a coupon
+  ? not proved (blocked): Admin: refunds
+See it in your dashboard: <the run's page>
+```
+
+There is one `See it in your dashboard` line per run. When the dashboard address is not known, a single `Saved to your dashboard: <url>` line takes their place.
+
+Each verdict comes from the engine. A journey that neither passed nor failed is reported as **not proved**. It is never counted as working.
+
+If the run could not be sent, `try` says so, keeps the run on this machine and tells you to run `reticle sync`. It never prints a dashboard line in that case.
+
+## Exit codes
+
+| Code | When                                                                       |
+| ---- | -------------------------------------------------------------------------- |
+| `0`  | The drive ran. Broken journeys are a finding, not a failure of the command |
+| `1`  | Not signed in, no free drive granted, or the drive could not run           |

package/docs/cli/update.mdx

@@ -16,8 +16,8 @@ No flags.
 
 1. Ask the registry what is available.
 2. Compare by **direction**, not inequality. A registry version that merely differs is not a newer one, and the old check happily installed a downgrade.
-3. Nothing newer: log `reticle_update` with `ok: false` and `message: "already on the latest version"`, then stop.
-4. Otherwise sync the **app's SDK first**. `reticle update` used to swap only the CLI, so the command whose job is keeping an install current was itself a way to produce a version-skewed pair.
+3. Nothing newer: if this project's SDK is older than the CLI, bring it up to the CLI's version; then log `reticle_update` with `ok: false` and `message: "already on the latest version"`, and stop.
+4. Otherwise refresh the Reticle block in agent rule files that already carry one, then sync the **app's SDK first**. `reticle update` used to swap only the CLI, so the command whose job is keeping an install current was itself a way to produce a version-skewed pair.
 5. Then apply the CLI update, which execs and exits. Your agent client restarts it.
 
 ## What it prints
@@ -27,6 +27,7 @@ No flags.
 | `reticle_update` | `ok`, and either `from` and `to`, or `message` and `version` |
 | `reticle_update_sdk` | `synced`, `packages`, `to`, `packageManager`. Or `synced: false` with `reason: "no @reticlehq packages in this project"` |
 | `reticle_update_sdk_failed` | A `hint` naming the exact command to run by hand |
+| `reticle_rules_refreshed` | `files`, `to`: the agent rule files whose Reticle block was brought up to the new version |
 | `reticle_update_failed` | The error |
 
 The SDK sync is best effort and non-fatal on purpose. This command gets run from wherever the human happens to be standing, which is often not an app at all.
@@ -51,7 +52,7 @@ This installs the current server without going through the old updater.
 ## Worked example
 
 ```bash
-npx @reticlehq/server version     # 2.8.0
+npx @reticlehq/server version     # 3.6.0
 npx @reticlehq/server update
 ```
 

package/docs/cli/verify.mdx

@@ -4,7 +4,7 @@ description: Drive a URL once, replay every saved flow, and exit zero only on a
 icon: circle-check
 ---
 
-`reticle verify` is the CI command: no model in the loop, no MCP. It boots the engine in drive mode, waits for the in-page SDK to dial back, replays every saved flow, renders the verdict, and exits.
+`reticle verify` is the CI command: no model in the loop, no MCP. On a free port it boots the engine in drive mode, waits for the in-page SDK to dial back, replays every saved flow, renders the verdict, and exits. When a Reticle daemon already owns the port, it asks that daemon to replay the flows instead.
 
 ```bash
 npx @reticlehq/server verify <url> [--headed] [--timeout N] [--storage-state <file>]
@@ -20,6 +20,13 @@ It uses the same runner and the same verdict as the MCP and HTTP paths, so a pla
 | `--headed` | boolean | `false` (headless) | Show the browser |
 | `--timeout N` | number, ms | `15000` | How long to wait for a browser session to dial back |
 | `--storage-state <file>` | string | unset | A Playwright storage state file. This is how you verify flows behind a login without scripting the login every time |
+| `--results-json <file>` | string | unset | Also write one verdict per journey to this file: `{ verdict, results: [{ journey, verdict, reason? }] }`, each verdict `yes`, `no` or `unknown`. A skipped journey is `unknown`, and the run is `yes` only when every journey is. Written when verify boots its own browser and a run finishes; a refusal before that writes nothing. The [GitHub Action](https://github.com/reticlehq/reticle/tree/main/action) posts this file |
+| `--port N` | number | `RETICLE_PORT`, else the project's port, else `4400` | The bridge port the app dials |
+| `--session-id <id>` | string | unset | Use a tab that is already connected |
+| `--select <label>` | string, repeatable | unset | Verify only flows carrying this label |
+| `--expect '<json predicate>'` / `--expect-file <path>` | string | unset | One verdict on one predicate, no saved flows needed. Asks the daemon that owns the port and never starts one; with no daemon it refuses. Exits `0` only on `verified: "yes"`. Cannot be combined with `--storage-state` |
+| `--explore` / `--persona "<who does what>"` | boolean / string | off | No saved flows yet? The Harness drives the app and records them. `--persona` implies `--explore` |
+| `--confirm-dangerous` | boolean | off | Let this run press the controls the replay guard holds as destructive, such as a "Place order" or "Delete" button in a saved flow. Without it such a step is refused, so a checkout flow cannot pass. It covers this run only and is never saved into a flow. |
 
 ## What it prints
 
@@ -34,6 +41,8 @@ No app connected: Reticle drove the URL but no @reticlehq/browser session dialed
 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`.
+  Or let Reticle record them for you: `reticle verify <url> --explore` drives the app itself and saves what it
+  drove, so every run after the first one replays with no model in the loop.
 ```
 
 <Warning>
@@ -49,11 +58,13 @@ Call log:
 ```
 
 <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` does not start a second
-  one: it prints three ways out (ask the running daemon via `reticle_run`, stop it, or move with
-  `RETICLE_PORT`) rather than a raw listen error. This bites most often on a developer machine,
-  where an agent has usually left a daemon running; in CI the port is normally free.
+  `verify` never starts a second daemon on a port that already has one. With a daemon there, it
+  replays the saved flows (or answers `--expect`, or runs `--explore`) through that daemon. Only
+  `--headed` and `--storage-state` need a browser of its own, so with a daemon on the port those
+  refuse and print the ways out (drive through the running daemon, ask it via `reticle_run`, move
+  both to another port with `--port` or `RETICLE_PORT`, or stop it). 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

package/docs/cli/version.mdx

@@ -19,7 +19,7 @@ All three are the same command. No flags.
 The version, and nothing else, on stdout, so `V=$(reticle version)` works:
 
 ```text
-3.6.0
+3.7.0
 ```
 
 ## Exit codes
@@ -29,7 +29,8 @@ Always `0`.
 ## Worked example
 
 ```bash
-npx @reticlehq/server version | jq -r .version
+V=$(npx @reticlehq/server version)
+echo "$V"
 ```
 
 <Note>