@reticlehq/server 3.5.0 → 3.7.0

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

@@ -16,10 +16,10 @@ All three are the same command. No flags.
 
 ## What it prints
 
-One `reticle_version` line. Real capture:
+The version, and nothing else, on stdout, so `V=$(reticle version)` works:
 
-```json
-{ "t": "2026-08-15T18:42:26.275Z", "event": "reticle_version", "version": "2.8.0" }
+```text
+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>

package/docs/cli.mdx

@@ -4,7 +4,7 @@ description: Every reticle command. What it does, what it prints, and what it ex
 icon: terminal
 ---
 
-The `reticle` CLI installs Reticle into a project and proves the install works (`init`), runs and diagnoses the daemon your app connects to (`serve`, `status`, `doctor`, `kill`, `restart`), and gates a build on verification in CI (`verify`, `affected`, `gate`). This page is the index; each command has its own page with real captured output and measured exit codes.
+The `reticle` CLI installs Reticle into a project and proves the install works (`init`), runs and diagnoses the daemon your app connects to (`status`, `doctor`, `stop`, `restart`), and gates a build on verification in CI (`verify`, `affected`, `gate`). This page is the index; each command has its own page with real captured output and measured exit codes.
 
 The CLI is mostly for you, not your agent. Your agent talks MCP; you use these to set things up, work out why nothing connected, and wire verification into CI.
 
@@ -24,6 +24,82 @@ npx @reticlehq/server <command>
   below are pretty-printed so you can read them, and long lists are trimmed where the label says so.
 </Note>
 
+## Every command
+
+`reticle --help` prints the short list, grouped the way you meet the commands. `reticle help all` prints every command, and `reticle <command> --help` prints one command's detail.
+
+### Get started
+
+| Command | What it does | Page |
+| --- | --- | --- |
+| `reticle init` | Wire Reticle into this project, boot the app, prove a session connected | [init](/cli/init) |
+| `reticle connect [--project <name\|id>] [--workspace <name\|id>] [--url <origin>]` | Wire if needed, sign in, link this folder to a cloud project (created if it does not exist) in the workspace named (else the one you are signed in to, said when you belong to several), send local history | [cloud](/cli/cloud) |
+| `reticle try <url> [--persona <who>]` | Signed in: one free Harness drive of a URL, in a window you watch, then which journeys work | [try](/cli/try) |
+
+### Check your app
+
+| Command | What it does | Page |
+| --- | --- | --- |
+| `reticle verify <url>` | One-shot: drive the URL, verify saved flows or one predicate, exit 0 on pass | [verify](/cli/verify) |
+| `reticle gate [--since <ref>] [--accept-coverage] [--hook]` | Exit non-zero unless passing artifacts cover the affected flows | [gate](/cli/gate) |
+
+### Reticle on this machine
+
+| Command | What it does | Page |
+| --- | --- | --- |
+| `reticle status [--json]` | Is the daemon up, which pages connected, who is signed in, is this repo linked | [status](/cli/status) |
+| `reticle doctor` | Diagnose setup: Chromium, daemon, port | [doctor](/cli/doctor) |
+| `reticle open [url]` | Show the app: reuse the connected tab, else open one | [open](/cli/open) |
+| `reticle stop [--force]` | Stop the daemon we started; `--force` frees the port by its listener, never the agent's MCP proxy | [stop](/cli/stop) |
+| `reticle restart` | Free the port, then start a daemon and wait for a real bind | [restart](/cli/restart) |
+| `reticle update` | Install the latest server version and restart | [update](/cli/update) |
+
+### Account
+
+| Command | What it does | Page |
+| --- | --- | --- |
+| `reticle logout [--url <u>]` | Sign out of one host; others stay signed in | [cloud](/cli/cloud#reticle-logout) |
+| `reticle feedback` | Tell us what worked and what did not | [feedback](/cli/feedback) |
+| `reticle telemetry [status\|enable\|disable]` | Anonymous usage metrics: what is sent, and the switch | [telemetry](/cli/telemetry) |
+
+### More commands (`reticle help all`)
+
+| Command | What it does | Page |
+| --- | --- | --- |
+| `reticle sync [--watch] [--move-history]` | Send what has not synced yet; `--watch` keeps going; `--move-history` also sends the runs, flows and records made under the folder's previous link | [cloud](/cli/cloud#reticle-sync) |
+| `reticle runs [<runId>]` | The linked project's recent runs, or one of them | [cloud](/cli/cloud#reticle-runs) |
+| `reticle runs regression` | Which flows broke; exits `3` if any did | [cloud](/cli/cloud#reticle-runs-regression) |
+| `reticle runs share <runId>` | Mint a public proof link for one run | [cloud](/cli/cloud#reticle-runs-share) |
+| `reticle runs issues [--fix <fp>]` | The triage queue; `--fix` prints one issue's fix prompt | [cloud](/cli/cloud#reticle-runs-issues) |
+| `reticle runs memory` | What the linked project has learned | [cloud](/cli/cloud#reticle-runs-memory) |
+| `reticle config` | Choose what syncs: runs, memory, flows; where verification runs | [cloud](/cli/cloud#reticle-config) |
+| `reticle setup mcp` | Register the MCP server with your coding agents (the installer's registration half) | [setup](/cli/setup) |
+| `reticle serve` | Start the daemon and wait for it to bind | [serve](/cli/serve) |
+| `reticle mcp` | The MCP stdio proxy your agent runs; starts the daemon if needed | [mcp](/cli/mcp) |
+| `reticle drive <url>` | Foreground mode, for debugging | [drive](/cli/drive) |
+| `reticle affected [--since <ref>]` | Which saved flows must re-verify for the changed files | [affected](/cli/affected) |
+| `reticle context --compact [--session <id>]` | Resume after a compaction: what was proved, failed and is still owed | none |
+| `reticle report [--session <id>] [--hook]` | What the latest session claimed, and what held | [report](/cli/report) |
+| `reticle rollback` | Restore the previous server version and restart | [rollback](/cli/rollback) |
+| `reticle license` | Enterprise license status: active, eval or missing | [license](/cli/license) |
+| `reticle version` | Print the version | [version](/cli/version) |
+| `reticle help [all\|<command>]` | Usage: the short list, every command, or one command | [help](/cli/help) |
+
+### Renamed and removed
+
+The old names below still work for one release and print one line naming the new one.
+
+| Old | Now |
+| --- | --- |
+| `reticle kill` | `reticle stop --force` |
+| `reticle login`, `reticle link` | `reticle connect` |
+| `reticle project` | `reticle connect --project <name\|id>` |
+| `reticle whoami` | `reticle status` |
+| `reticle push` | `reticle sync` |
+| `reticle regression`, `share`, `issues`, `memory` | `reticle runs regression`, `runs share`, `runs issues`, `runs memory` |
+
+`hunt`, `watch`, `capsules`, `tutorial` and `identify` were removed. Each prints what to use instead and exits `1`: `reticle affected` or `reticle gate` for `watch`, `reticle init` or `reticle try <url>` for `tutorial`, `reticle feedback` for `identify`. Saved capsules stay in `.reticle/capsules`.
+
 ## Setup and diagnosis
 
 ### `reticle connect`
@@ -38,18 +114,20 @@ For a self-hosted cloud, add `--url <cloud origin>`. If the app was already wire
 
 ### `reticle init`
 
-Wires Reticle into the project in the current directory, then boots the app and proves a session connected. It exits non-zero if nothing connected, and prints what is left to do. It does not drive: proving a flow is the FIRST RUN, `reticle verify <url> --explore --persona "<who does what>"`.
+Wires Reticle into the project in the current directory, then boots the app and proves a session connected. It exits non-zero if nothing connected, and prints what is left to do. It does not drive: proving a flow is the FIRST RUN, which your agent drives with `reticle_act_and_wait` and an `until` on its last step, or, with a linked project, `reticle verify <url> --explore --persona "<who does what>"`.
 
 ```
 reticle init  [--env KEY=VALUE]... [--app <dir>] [--license <key>]
-              [--json] [--files-only] [--no-open] [--dry-run]
-              [--port N] [--no-mcp] [--no-install] [--timeout S]
+              [--json] [--files-only] [--relaunch] [--no-open] [--no-agents]
+              [--url <app url>] [--timeout S] [--dry-run] [--hooks]
+              [--port N] [--no-mcp] [--no-install] [--start]
+              [--capture-bodies] [--no-first-run]
 ```
 
 `--env` and `--app` are the answers the command cannot work out for itself: what the app needs to reach a usable state, and which app in a monorepo. Which journey proves what you care about is asked on the first run, as `--persona`. `--files-only` is what `init` did before it learned to boot the app: it still registers the MCP server and pre-approves Reticle's tools, so it doubles as the upgrade path for an existing install.
 
 <Card title="Full walkthrough with real output" icon="wand-magic-sparkles" href="/install-agentic">
-  What it writes, and how to read its four status marks.
+  What it writes, and how to read its five status marks.
 </Card>
 
 ### `reticle doctor`
@@ -64,9 +142,11 @@ npx @reticlehq/server doctor
 reticle doctor
   node         v22.14.0
   chromium     ✓ installed (chromium-1234)
-  daemon       ✓ running on :4400 (pid 72698, v2.8.0)
+  daemon       ✓ running on :4400 (pid 72698, v3.7.0)
   sessions     ✓ 1 page connected
   bridge port  4400  (your app must dial THIS port, not your dev-server port)
+  agent link   ✓ an MCP client attached here and called tools before (a record, not a live check)
+  project      ✓ wired here (my-app)
   daemon log   /Users/you/.reticle/daemon-4400.log
   tracing      RETICLE_TRACE=1 on the daemon for per-stage timings in that log
 ```
@@ -75,7 +155,7 @@ Exits `0`. That parenthetical about the bridge port is doing a lot of work. Mixi
 
 ### `reticle status`
 
-Whether the daemon is up and which apps have connected.
+Whether the daemon is up, which apps have connected, who is signed in, and whether this repo is linked to a cloud project.
 
 ```text
 reticle status
@@ -87,7 +167,7 @@ reticle status
 
 Add `--json` for the same facts as one machine-readable event line. See [`reticle status`](/cli/status) for the fields.
 
-Exits `0`. A session in the list is the install genuinely finished. Not a tick in a checklist, a connected app.
+Exits `0`. A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
 
 ### `reticle telemetry [status|enable|disable]`
 
@@ -110,8 +190,8 @@ policy       https://github.com/reticlehq/reticle/blob/main/docs/telemetry.md
 | --- | --- |
 | `reticle serve` | Start the daemon and wait for it to bind. `--drive <url>`, `--headless`, `--headed`, `--http`, `--http-port N`, `--http-token T` |
 | `reticle stop` | Stop the daemon we started, by its recorded pid. `--quiet` |
-| `reticle kill` | Free the port by asking who is **listening** on it. `--force` |
-| `reticle restart` | Kill, then start a daemon and wait for a real bind. `--force` |
+| `reticle stop --force` | Free the port by asking who is **listening** on it |
+| `reticle restart` | Free the port, then start a daemon and wait for a real bind. `--force` |
 | `reticle open [url]` | Show the app. Reuse the connected tab, or open one |
 | `reticle drive <url>` | Foreground mode, for debugging |
 | `reticle mcp` | The MCP stdio proxy. Auto-starts the daemon if needed. This is what your agent runs |
@@ -124,15 +204,17 @@ A bare `reticle` with no arguments is not help. It is `reticle serve`.
   `npx @reticlehq/server` never pairs a daemon with an SDK it cannot talk to. `init`, `update`,
   `rollback`, `setup install`, `version` and `help` always run as typed, and so does a command whose
   version you pinned yourself (`npx @reticlehq/server@<version> …`). Set `RETICLE_NO_VERSION_MATCH=1` to
-  turn it off.
+  turn it off. Because `--help` runs as typed too, it describes the CLI you ran. When the command it
+  describes would run at the project's version instead, the help opens with a line naming that version.
 </Note>
 
-<Warning>
-  `reticle verify` binds the bridge port itself, so it fails if a daemon is already listening, which
-  is the normal state once your agent has started one. Stop the daemon first, or point it elsewhere
-  with `RETICLE_PORT`. `reticle mcp` reuses a running daemon, and `reticle drive` attaches to one
-  (see [drive](/cli/drive)) rather than competing for the port.
-</Warning>
+<Note>
+  `reticle verify` works whether or not a daemon is running. With none, it starts its own browser on
+  the bridge port. With one, it replays the saved flows (or answers `--expect`) through that daemon.
+  Only `--headed` and `--storage-state` need their own browser, so with a daemon running those two
+  refuse and say so. Do not stop the daemon to get around it: that cuts your agent's MCP link. Point
+  `verify` at a free port with `--port N` instead.
+</Note>
 
 ## Verification
 
@@ -144,7 +226,16 @@ One-shot: drive the URL, replay the saved flows, exit `0` on pass. This is the c
 npx @reticlehq/server verify http://localhost:5173 --timeout 60000
 ```
 
-Options: `--headed`, `--timeout N`, `--storage-state <file>`. That last one is how you verify flows behind a login without scripting the login every time.
+Options:
+
+- `--headed`, `--timeout N`, `--port N`.
+- `--storage-state <file>`: verify flows behind a login without scripting the login every time.
+- `--session-id <id>`: use a tab that is already connected.
+- `--select <label>`: verify only flows carrying this label. Repeatable.
+- `--expect '<json predicate>'` or `--expect-file <path>`: one verdict, no saved flows needed. Asks the running daemon; with none, it refuses. Exits `0` only on `verified: "yes"`.
+- `--explore` with `--persona "<who does what>"`: no saved flows yet? The Harness drives the app and records them. Needs a linked project (`reticle connect`).
+- `--results-json <file>`: also write one verdict per journey as JSON, for CI.
+- `--confirm-dangerous`: let this run press what the replay guard holds as destructive.
 
 ### `reticle affected`
 
@@ -196,18 +287,6 @@ Measured exit code: **`1`**, with the flow lists trimmed above. That run genuine
 
 `quarantined` flows are excluded from the pass/fail decision. Quarantine is for a flow that is known flaky and being fixed; it is not a place to hide failures, because the list is printed on every run.
 
-### `reticle watch [url]`
-
-On save, report which saved flows must re-verify. The interactive companion to `affected`. Long-running; stop it with `Ctrl+C`.
-
-### `reticle capsules`
-
-List the saved fail-to-pass bug capsules in `.reticle/capsules`. No flags. See [capsules](/cli/capsules).
-
-### `reticle hunt <dir>`
-
-Aggregate a directory of crawl reports into one false-green rate. See [hunt](/cli/hunt).
-
 ## Maintenance
 
 | Command            | What it does                                        |
@@ -216,7 +295,7 @@ Aggregate a directory of crawl reports into one false-green rate. See [hunt](/cl
 | `reticle rollback` | Restore the previous version and restart            |
 | `reticle license`  | Enterprise license status: active, eval, or missing |
 | `reticle version`  | Print the version                                   |
-| `reticle help`     | Usage for everything                                |
+| `reticle help`     | The short list; `help all` for every command        |
 
 <Tip>
   `rollback` exists because an auto-updating dev tool that cannot go back is a dev tool that can
@@ -230,7 +309,7 @@ Aggregate a directory of crawl reports into one false-green rate. See [hunt](/cl
 npx @reticlehq/server feedback "what worked, what didn't"
 
 # agents, including from a setup that never finished
-npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"
+npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "what happened"
 ```
 
 The `--agent` form matters more than it looks: the setup that failed halfway is exactly the setup worth hearing about, and in that state the MCP tools do not exist yet.
@@ -238,13 +317,3 @@ The `--agent` form matters more than it looks: the setup that failed halfway is
 <Card title="How feedback is handled" icon="comments" href="/tools/session-and-feedback">
   What each kind means, and what happens when a report cannot be delivered.
 </Card>
-
-## `reticle identify`
-
-Opt-in, and off by default:
-
-```bash
-npx @reticlehq/server identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
-```
-
-Only useful if you want support or an enterprise trial. `--forget` removes it.

package/docs/debugging.md

@@ -12,7 +12,7 @@ Reticle produces four different signals and they answer four different questions
 
 | Question | Signal | Where |
 | --- | --- | --- |
-| What did the **agent** do to the app, and what did the app do back? | the journal | `reticle_observe` (the event window), `reticle_run_export` (a saved run), `~/.reticle/journal/` |
+| What did the **agent** do to the app, and what did the app do back? | the journal | `reticle_observe` (the event window), `reticle_run_export` (a saved run), `.reticle/sessions/<id>/` in the project |
 | What did **Reticle** do internally to answer that call? | the **trace** | daemon log, with `RETICLE_TRACE=1` |
 | What happened at a milestone (daemon start, skew, refusal)? | structured log lines | daemon log |
 | How much is this being used, and does it work? | telemetry | [telemetry.md](telemetry.md) |
@@ -36,7 +36,7 @@ tail -f ~/.reticle/daemon-4400.log | jq .
 Off by default, because a trace on every tool call is a cost on the hot path, and a verification loop is 50 to 200 calls. Measured, so the claim is checkable: a disabled span costs **126ns** per site (against ~9ns for a bare call), which is under a microsecond per tool call and not the literal zero it is tempting to write. Turn it on **for the daemon** (the flag is read per call, but the daemon is the process doing the work, so it has to be set where the daemon starts):
 
 ```bash
-RETICLE_TRACE=1 reticle serve --port 4400
+RETICLE_TRACE=1 npx @reticlehq/server serve --port 4400
 ```
 
 Every instrumented stage then emits one line **when it ends**, carrying its own duration:
@@ -95,7 +95,7 @@ init.write        1ms  target=.reticle.json
 init.apply      262ms  steps=5
 ```
 
-Two things that trace makes visible and nothing else did. Planning is ~2ms, so init's wall-clock is essentially all subprocess: the package manager, and `claude mcp add` when MCP registration is on. And when the pinned install is refused, the unpinned **retry is a second full package-manager run**, so init legitimately takes about twice as long on that path. Every `--local` fixture run takes it, because the version being installed is not published yet.
+Two things that trace makes visible and nothing else did. Planning is ~2ms, so init's wall-clock is essentially all subprocess: the package manager, and `claude mcp add` when MCP registration is on. And when the pinned install is refused, the unpinned **retry is a second full package-manager run**, so init legitimately takes about twice as long on that path. An install of a version that is not published yet always takes it.
 
 ### Adding a span
 

package/docs/deploy-checks.md

@@ -91,7 +91,7 @@ Both. For a non-loopback origin Reticle injects `reticle.connect()` with a one-t
 
 ### One of my flows logs in and the next one starts logged in. How do I stop that?
 
-`verify` replays flows sequentially against one tab, so leftover state carries. Either author each flow to be self-contained, or use `reticle_verify { action: "flows", parallel: true }`, which gives every flow its own isolated browser context with its own cookies and storage.
+`verify` replays flows sequentially against one tab, so leftover state carries. Either author each flow to be self-contained, or use `reticle_verify { action: "flows", parallel: 4 }` (`parallel` is how many flows run at once), which gives every flow its own isolated browser context with its own cookies and storage.
 
 ### Should I run reticle gate as well as reticle verify?
 

package/docs/desktop.mdx

@@ -210,13 +210,15 @@ installReticleCapture(win);
 
 That is all: no CDP flag, no extra packages, and it works on a packaged `file://` renderer. `reticle_screenshot` and `reticle_visual_diff` then work on your app.
 
+In a multi-window app, name each window: `installReticleCapture(win, { label: 'settings' })`. The session list then shows `window: "settings"`. Electron windows have no name of their own, and two of them often share a url.
+
 Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-port=9222` plus `RETICLE_CDP_URL=http://127.0.0.1:9222` also works and additionally enables `fullPage` (the main-process route captures the window as composited, so it cannot scroll-stitch).
 
 **Tauri: one Rust command.** The crate is versioned independently of the npm packages:
 
 ```toml
 [dependencies]
-reticle-tauri = "3.5"
+reticle-tauri = "3.7"
 ```
 
 ```rust
@@ -225,6 +227,8 @@ tauri::Builder::default()
     .on_page_load(reticle_tauri::on_page_load)
 ```
 
+**Dev builds only.** In a release build the crate is inert: `reticle_capture` refuses and `on_page_load` does nothing, so the binary you sign and ship carries no Reticle capability. A release build you test with Reticle (a CI fixture) turns it on with `reticle-tauri = { version = "3.7", features = ["in-release"] }`.
+
 Nothing on the JavaScript side: the SDK invokes the command through Tauri's own internals, because Tauri has no preload stage where a shim could be installed.
 
 ### Why the backing store, and not a screen capture
@@ -245,7 +249,7 @@ All three capture the visible viewport by default, so a baseline taken on a deve
 
 **`{ fullPage: true }` works on Tauri/Linux only.** WebKitGTK can render the whole document offscreen; `takeSnapshot` (macOS) and `CapturePreview` (Windows) only give what is composited, and Electron's `capturePage()` is the same. Asked for a full page they cannot produce, all of them return `{ ok: false, reason: 'full-page-unsupported' }` rather than quietly handing back the viewport, which would be a baseline that omits everything below the fold while every later diff of it reports green about a region that was never captured. No baseline is written on a refusal.
 
-An app that already has its own capture can expose `window.__reticleIpc.capture()` returning a PNG path instead; the SDK prefers it over the built-in command.
+An app that already has its own capture can expose `window.__reticleIpc.capture()` returning a PNG path instead; the SDK prefers it over the built-in command. The daemon reads only a file in the OS temp directory whose name starts with `reticle-capture-`, so write the PNG there.
 
 <Warning>
   One honest caveat. A fully occluded or minimized window is only partially composited, so parts of
@@ -322,7 +326,7 @@ Without `@reticlehq/electron/preload`, every IPC call is invisible to Reticle. A
 
 ## How it compares to Playwright MCP
 
-Both attached to the same running Electron app, same task ("archive a todo, then verify it worked"):
+Both attached to the same running Electron app, same task ("archive a todo, then verify it worked"). Measured by hand, with Reticle's `lean` tool profile, which has since been retired:
 
 | tool                    | ~tokens | ms      | verdict                                   |
 | ----------------------- | ------- | ------- | ----------------------------------------- |
@@ -344,6 +348,8 @@ Playwright MCP is faster. It is also structurally unable to see an IPC failure,
 
 **`reticle open` says there is nothing to open.** That is correct for a desktop app. There is no URL, and there is no `reticle drive` for desktop either. Both launch a browser, which is not what you are testing.
 
+**Several windows, and the wrong one gets driven.** Every window that loads the SDK is its own session, and `reticle_session { action: "list" }` names each (`window: "main"`: Tauri's label, or the `label` you gave `installReticleCapture` on Electron) with whether it is `hidden`. A page served as an error (a dev server's 404 for a static page, say) carries `documentStatus` and is never auto-selected ahead of a working one. To drive a specific window, pass its `sessionId`. To get rid of a stray hidden window for good, call `reticle_session { action: "end", sessionId, disconnect: true }`. It stays detached across its own reloads until the daemon restarts.
+
 **A screenshot came back partly blank.** The window is occluded or minimized, so it is only partially composited. Bring it forward and capture again.
 
 **`{ ok: false, reason: 'full-page-unsupported' }`.** You asked for `fullPage: true` on a platform that cannot render offscreen. Only Tauri on Linux (WebKitGTK) can. Capture the viewport instead, or scroll and capture in sections.

package/docs/enterprise.md

@@ -4,7 +4,7 @@ description: 'Premium access and activation, what is gated, the security and dat
 icon: building
 ---
 
-Enterprise features ship inside the open package and are unlocked by a signed license key you set as `RETICLE_LICENSE_KEY`. Activation is verified locally with Ed25519 and makes **no network call**, so nothing about your usage leaves your machine. Run `npx @reticlehq/server license` to see whether you are `active`, `eval`, `missing` or `expired`.
+Enterprise features ship inside the open package and are unlocked by a signed license key you set as `RETICLE_LICENSE_KEY`. Activation is verified locally with Ed25519 and makes **no network call**, so nothing about your usage leaves your machine. Run `npx @reticlehq/server license` to see whether you are `active`, `eval`, `missing`, `expired` or `invalid`.
 
 > Premium access (how you get + activate it), what's gated, the security/data-handling posture, and the licensing model. Integration mechanics live in [`platform-integration.md`](./platform-integration.md).
 
@@ -22,19 +22,20 @@ Enterprise (`ee/`) features ship **inside the open package**; they're source-ava
    export RETICLE_LICENSE_KEY="<your key>"
    # the release already bakes the issuer public key (RETICLE_LICENSE_PUBLIC_KEY)
    ```
-3. **Verify.** `reticle license` shows your status:
+3. **Verify.** `reticle license` prints one JSON line whose `status` and `detail` say where you stand:
 
    ```
-   active    licensed to Acme Corp (enterprise), expires 2027-06-20 · features: sso, audit
+   active    licensed to Acme Corp (enterprise), expires 2027-06-20T00:00:00.000Z
    eval      evaluation mode: enterprise features run free (no issuer key configured)
    missing   set RETICLE_LICENSE_KEY to activate enterprise features in production. Request a key from hey@reticle.sh
    expired   license expired. Renew with hey@reticle.sh to keep using enterprise features
+   invalid   license key rejected (<reason>). hey@reticle.sh can re-issue it
    ```
 
    Every status reports `contact`, so a reader who is stuck always has somebody to write to. An unlicensed status also reports `gated`, what a licence unlocks in the build you are running, so the command answers "what would this buy me, and how do I get one" without anybody having to find this page first. It is derived from the features the gate actually enforces, so it names what your build will really refuse rather than a roadmap. An `active` licence does not report it: that reader has already bought, and listing feature names at them answers nothing they asked.
 
-4. **Unlock.** Enterprise features now run in production; without a valid key they refuse to run there (a clear error, never a silent half-feature). In eval/dev they always run free.
-5. **Renew.** Keys carry an expiry; `reticle license` warns before it lapses.
+4. **Unlock.** Enterprise features now run; without a valid key they refuse to run (a clear error, never a silent half-feature). A published release has the issuer key baked in, so it enforces the key everywhere. Only a build without one (from source) runs in `eval` mode, where the features run free outside `NODE_ENV=production`.
+5. **Renew.** Keys carry an expiry, shown as `expiresAt`; once it passes, the status is `expired`.
 
 > Procuring a license: contact **[hey@reticle.sh](mailto:hey@reticle.sh)**. Keys are issued offline and signed with Ed25519; the activation you run (`reticle license`) verifies them locally with no network call.
 
@@ -42,26 +43,26 @@ Enterprise (`ee/`) features ship **inside the open package**; they're source-ava
 
 The licensing **mechanism** is open core (inspectable, FSL). Only the **features** under `ee/` are gated:
 
-- **Today:** the activation gate + an example gated feature (audit event recording).
+- **Today:** the activation gate + one gated feature (audit event recording, `audit-log`).
 - **Roadmap** (the reliably enterprise-only set): **SSO/SAML, SCIM, RBAC / team permissions, audit logs, multi-org management, verify-before-merge policy gates, and the hosted control-plane connectors.** These are the things a security/compliance org pays for; the core verification engine stays free forever.
 
 > What's premium vs free, and pricing, are business decisions for the owner; this doc describes the _mechanism_, not the price list.
 
 ## Security & data handling
 
-The honest one-pager a security review needs. Reticle is built so the answer to "where does our data go?" is **nowhere. It runs on your machine, in your infra.**
+The honest one-pager a security review needs. Reticle is built so the answer to "where does our data go?" is **nowhere, unless you link a project to the dashboard. It runs on your machine, in your infra.**
 
 | Question | Answer |
 | --- | --- |
 | Does the SDK ship to production? | **No.** Dev/preview-only, tree-shaken from production builds. |
 | Where does the server run? | **Localhost.** The bridge binds `127.0.0.1`; the verify endpoint is localhost-bound + token-guarded (constant-time), with request/body-size/timeout limits. |
-| Does anything phone home? | **No app data, ever.** License checks are offline (Ed25519). The CLI sends anonymous, opt-out usage metrics only (random id + event names, no code, no PII; see [telemetry](telemetry.md)); disable fleet-wide with `RETICLE_TELEMETRY=0` or per-machine with `reticle telemetry disable`. Feedback your team explicitly sends us (`reticle feedback`) is the only free text that ever leaves; it is never collected passively, is redacted client-side, and is disabled fleet-wide with `RETICLE_FEEDBACK=0`. |
+| Does anything phone home? | **No app data unless you opt in.** Linking a project to the dashboard (`reticle connect`) sends its runs there; see [what is recorded](what-is-recorded.md) and `reticle config` for what it sends. License checks are offline (Ed25519). The CLI sends anonymous, opt-out usage metrics only (random id + event names, no code, no PII; see [telemetry](telemetry.md)); disable fleet-wide with `RETICLE_TELEMETRY=0` or per-machine with `reticle telemetry disable`. Feedback your team explicitly sends us (`reticle feedback`) is the only free text that ever leaves; it is never collected passively, is redacted client-side, and is disabled fleet-wide with `RETICLE_FEEDBACK=0`. |
 | Where do artifacts live? | Your disk: `.reticle/runs/<id>.json` (atomic writes, bounded retention), `.reticle/flows/`, `.reticle/contract.json`. You own them. |
 | What can the server read? | The DOM/network/console/routing/state of the app under test, locally. |
 | Leak risk downstream? | The **`prod-preview` profile** redacts source `file:line`, raw bodies, and app-state values. |
 | Path safety | Run/flow ids are validated as single path segments on read **and** write (no traversal). |
 
-**Verify it yourself:** the SDK + server are source-available, so read the tree-shaking, the `127.0.0.1` bind, and the offline license verify. `SECURITY.md` has the disclosure process; an SBOM is available on request. SOC 2 is a GA-stage item (no Reticle-hosted data exists today to certify); the posture above is the honest current state.
+**Verify it yourself:** the SDK + server are source-available, so read the tree-shaking, the `127.0.0.1` bind, and the offline license verify. `SECURITY.md` has the disclosure process; an SBOM is available on request. SOC 2 is not in place; the posture above is the honest current state.
 
 ## Licensing model (per package)
 
@@ -69,7 +70,7 @@ The honest one-pager a security review needs. Reticle is built so the answer to
 | --- | --- | --- |
 | The protocol and the rules (`open-verification`, `core`, `engine`) | **Apache-2.0** | the part that DECIDES a verdict, auditable and reimplementable by anyone |
 | Embeddable SDK (`browser`, `react`, `babel-plugin`, `next`, `vite-plugin`, `electron`, `eslint-plugin`) | **Apache-2.0** | safe to ship inside your customers' apps; explicit patent grant |
-| Server / CLI / MCP (`server`, `test`, umbrella) | **FSL-1.1-ALv2** | free for any use except reselling Reticle itself; converts to Apache after 2 years |
+| Server / CLI / MCP (`server`, `init`, `test`) | **FSL-1.1-ALv2** | free for any use except reselling Reticle itself; converts to Apache after 2 years |
 | Enterprise features (`server/src/features/ee/`) | **Reticle Enterprise License** | source-available; free for dev/eval, license key required in production |
 
 Embedding / OEM / enterprise: **[hey@reticle.sh](mailto:hey@reticle.sh)**.

package/docs/environment.mdx

@@ -17,6 +17,7 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | `RETICLE_ALLOWED_ORIGINS` | daemon | Comma-separated WebSocket origins the bridge accepts. |
 | `RETICLE_STATE_DIR` | daemon, CLI | Daemon state: pid files, the discovery registry and logs. Defaults to `~/.reticle`. |
 | `RETICLE_DAEMON_READY_TIMEOUT_MS` | MCP proxy | How long the MCP proxy waits for a daemon to come up before reporting it unreachable. |
+| `RETICLE_NO_VERSION_MATCH` | CLI | `1` turns off version matching: when the project's SDK is a different major version from the CLI you ran, the CLI normally hands the command to the matching server version. |
 | `RETICLE_DEV` | `@reticlehq/next` | Instrument even when `NODE_ENV` says production, for `NODE_ENV=production next dev`. |
 
 ## Daemon lifetime
@@ -33,6 +34,7 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | Variable | Read by | What it does |
 | --- | --- | --- |
 | `RETICLE_CDP_URL` | daemon | Attach to a browser that is already running, over CDP, instead of launching one. |
+| `RETICLE_CHROMIUM_PATH` | daemon, `drive`, `verify`, `doctor` | The Chromium executable to launch, for a machine where Playwright's own build is missing and cannot be installed and there is no Chrome or Edge in the usual place. When set, nothing else is tried: no Playwright build, no Chrome or Edge, no install. A path that does not exist, is not a file, or is not executable is refused with a message naming it and saying which. `doctor` reports on this path instead of the bundled build. |
 | `RETICLE_MAX_CONTEXTS` | daemon | The most leased headless browser contexts the pool runs at once. |
 | `RETICLE_MAX_MESSAGES_PER_SECOND` | daemon | Events per second a page may send before the bridge starts sampling them. It never disconnects. Raise it for a legitimately busy app, such as a streaming dashboard. |
 
@@ -40,7 +42,7 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 
 | Variable | Read by | What it does |
 | --- | --- | --- |
-| `RETICLE_ADVERTISE_ALL_TOOLS` | daemon | Advertise every tool directly instead of the default surface. Everything is reachable either way, through `reticle_run`. |
+| `RETICLE_ADVERTISE_ALL_TOOLS` | daemon | Advertise 30 tools directly instead of the default ten, under their unmerged names (`reticle_snapshot` instead of `reticle_look { action: "page" }`, and so on). Everything is reachable either way, through `reticle_run`. |
 | `RETICLE_VERIFY_SURFACE` | daemon | Advertise the smallest surface that can still produce a verdict. |
 | `RETICLE_TOOL_PROFILE` | daemon | Retired. Any value it used to accept still resolves to a sensible surface, and the daemon says which one it used instead. |
 | `RETICLE_ENCODING` | daemon | How tool results are written for the agent. Compact JSON by default; `pretty` indents it, and `toon` is a denser tabular form. The typed result is the same in every encoding. |
@@ -62,13 +64,9 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | `RETICLE_CLOUD_KEY` | CLI, daemon | The key's earlier name. Still honoured. |
 | `RETICLE_CLOUD_URL`, `RETICLE_URL` | CLI, daemon | The platform host. `RETICLE_CLOUD_URL` wins when both are set. |
 | `RETICLE_SYNC_INTERVAL_MS` | `reticle sync --watch` | How often the watching sync runs. Every 60 seconds by default. |
-| `ANTHROPIC_API_KEY` | autonomous drive | The key the drive's model uses when no coding agent is in the loop. Without it, the drive is unavailable and everything else is unaffected. |
-| `RETICLE_HARNESS_MODEL` | autonomous drive | The model the drive uses. A small one by default. |
-| `RETICLE_HARNESS_BASE_URL` | autonomous drive | A proxy or gateway in front of the model API. |
-| `RETICLE_HARNESS_MAX_STEPS` | autonomous drive | A hard ceiling on model turns in one drive. It bounds cost. |
-| `RETICLE_HARNESS_DRIVER` | autonomous drive | Which model drives: `anthropic` (the default) or `jev`. |
-| `JEV_API_KEY`, `RETICLE_HARNESS_JEV_URL` | autonomous drive | A direct key and base URL for the `jev` driver. The usual path is `RETICLE_API_KEY` through the platform. |
-| `OPENAI_API_KEY`, `RETICLE_HARNESS_OPENAI_MODEL` | autonomous drive | A direct key and model for the OpenAI driver. |
+| `RETICLE_HARNESS_MAX_STEPS` | autonomous drive | A hard ceiling on steps in one drive. It bounds cost. The drive itself runs on the platform and needs a linked project; each drive spends credits from the workspace's allowance. |
+| `RETICLE_DRIVE_ID` | autonomous drive | The free drive the platform granted, sent with every Harness call. `reticle try` sets it; you do not need to. |
+| `RETICLE_SECRET_<FIELD>` | autonomous drive, replay | The value of a secret field, typed in on this machine. Only the field's name goes to the platform. |
 
 ## Licensing
 
@@ -84,4 +82,5 @@ Reticle works with none of these set. Each one changes a single behaviour, and m
 | `RETICLE_TELEMETRY_FILE` | CLI, daemon | Write telemetry to a local JSONL file and send nothing, so you can read exactly what would be sent. |
 | `RETICLE_TELEMETRY_URL`, `RETICLE_TELEMETRY_KEY` | CLI, daemon | Send telemetry to a different host or project, such as an EU region or your own instance. |
 | `RETICLE_FEEDBACK` | daemon | Turns off the feedback channel only. Usage telemetry follows `RETICLE_TELEMETRY`. |
+| `RETICLE_INSTALL_SOURCE` | `init`, installer, plugin | Names the published route an install came through (`docs_site`, `skill_file`, `plugin`). Self-declared, carries nothing about you, and changes nothing about the install. |
 | `RETICLE_TRACE` | daemon, CLI | Verbose internal tracing for people working on Reticle itself. Off by default. |

package/docs/faq.mdx

@@ -11,8 +11,8 @@ Reticle is a dev-only, localhost-only verification layer an AI coding agent uses
 
 <Accordion title="Does this run in production?">
   No, and it is built so that it cannot easily be made to. Keep `reticle.connect()` behind a dev
-  guard; the SDK is side-effect-free and tree-shakes out of production builds. The Vite plugin uses
-  `apply: 'serve'`, which means it is not part of a production build at all.
+  guard; the SDK is side-effect-free and tree-shakes out of production builds. In a production `vite
+  build`, the Vite plugin swaps the SDK for an inert stub and injects nothing.
 </Accordion>
 
 <Accordion title="Do I have to change my components?">
@@ -68,7 +68,7 @@ If you believe an `unknown` is wrong, report it. Reticle's own response says as
 </Accordion>
 
 <Accordion title="Does my data leave the machine?">
-  Your app's data, no. Reticle is dev-only and localhost-only, and nothing from the app under test (DOM, network bodies, console, state, source) is sent. Credential-shaped values are redacted before they leave the page. You will see `[REDACTED]` in request bodies without configuring anything.
+  Reticle is dev-only and localhost-only. Nothing from your app leaves the machine until you link a project (`reticle connect`, or `RETICLE_API_KEY` in CI). After that, what syncs is set by `reticle config`, and when the Harness drives, the platform sees the steps it drives. Secret values never leave. Credential-shaped values are redacted before they leave the page. You will see `[REDACTED]` in request bodies without configuring anything.
 
 Anonymous usage counts are sent by default, separately, and carry nothing from your app. `reticle telemetry disable`, `RETICLE_TELEMETRY=0` or `DO_NOT_TRACK=1` turns them off.