@reticlehq/server 3.7.0 → 3.8.1

package/docs/cli/affected.mdx

@@ -17,7 +17,7 @@ npx @reticlehq/server affected [--since <ref>] [file...]
 | `file...` | strings, positional | none | Explicit changed files |
 | `--since <ref>` | string | `HEAD` when no files are given | Also include files git reports as changed since this ref |
 
-With nothing after it, `reticle affected` means the working tree against `HEAD`. It used to be a usage error, while the rule `reticle init` writes into the agent's own instruction file told the agent to run it.
+With nothing after it, `reticle affected` compares the working tree with `HEAD`.
 
 ## What it prints
 

package/docs/cli/cloud.mdx

@@ -12,7 +12,7 @@ npx @reticlehq/server connect --project "My App"
 
 If your daemon is not on the default port 4400, run `npx @reticlehq/server init --port <N>` first: `connect` takes no `--port`, and the `init` it runs for an unwired app uses the default.
 
-Use `--url https://your-cloud-origin` for a self-hosted cloud. `connect` checks a saved sign-in against that exact host before reuse; if it has expired, the browser approval opens again. It mints or reuses a project-scoped key, so there is no key to paste. The browser asks you to sign in, or to create a free account at app.reticle.sh. A new account gets 10 free credits to try Harness; adding a card starts a 14-day trial with 500 credits, and the paid plan includes 1,000 credits per seat each month. Harness drives and chat checks spend credits; storing and syncing runs is free. What syncs, and how to switch each part off, is in [What is recorded](/what-is-recorded). A newly wired app may have no run to sync yet: ask your agent to verify one flow and the linked daemon will sync the result. Run `reticle status` to check who is signed in and whether this folder is linked, and `reticle sync` to send anything still pending.
+Use `--url https://your-cloud-origin` for a self-hosted cloud. `connect` checks a saved sign-in against that exact host before reuse; if it has expired, the browser approval opens again. It mints or reuses a project-scoped key, so there is no key to paste. The browser asks you to sign in, or to create a free account at app.reticle.sh. A new account gets free credits to try Harness; adding a card starts a 14-day trial with 500 credits, and the paid plan includes 1,000 credits per seat each month. Harness drives and chat checks spend credits; storing and syncing runs is free. What syncs, and how to switch each part off, is in [What is recorded](/what-is-recorded). A newly wired app may have no run to sync yet: ask your agent to verify one flow and the linked daemon will sync the result. Run `reticle status` to check who is signed in and whether this folder is linked, and `reticle sync` to send anything still pending.
 
 The other cloud commands are thin clients over the `/v1` API. Their logic is server-side.
 
@@ -42,7 +42,7 @@ npx @reticlehq/server connect [--project <name|id>] [--workspace <name|id>] [--u
 
 Signs in if needed (a browser device flow like `gh auth login`: approve in the browser, the CLI polls until confirmed), then binds this repository to a cloud project and sends local history. It **mints** a project-scoped key, so there is nothing to paste; with `RETICLE_API_KEY` already set, it resolves that key's project instead. `--project` accepts a slug id or a display name, and creates the project when no project has that name. Omitted, the project is named after the `projectId` in `.reticle.json`, else after this folder. `--workspace` picks the workspace to link in when you belong to more than one. `--no-install` is passed to the `init` it runs for an unwired app. Writes `cloud.json` and the key.
 
-`reticle login`, `reticle link` and `reticle project` are the old spellings. They still work for one release and print one line naming `connect`. To sign in without a browser (an agent, a server), `login` keeps a two-step email path: `reticle login --email <e> [--org <name>]` mails a 6-digit code, then `reticle login --email <e> --code <123456>` signs in and links this repo. For CI, use `RETICLE_API_KEY` rather than any sign-in.
+`reticle login`, `reticle link` and `reticle project` are the old spellings. They still work for one release and print one line naming `connect`. Sign-in is with Google or GitHub, in the browser. Email sign-in is gone: `reticle login --email` stops and says so. Without a browser (CI, an agent, a server), set `RETICLE_API_KEY` to a key from Settings > API keys.
 
 ### `reticle logout`
 
@@ -59,10 +59,10 @@ Signs out of ONE host. Which host: `--url`, else `RETICLE_CLOUD_URL`, else the a
 ### `reticle config`
 
 ```bash
-npx @reticlehq/server config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
+npx @reticlehq/server config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server] [--harness on|off]
 ```
 
-Edits `.reticle/cloud.json` in place. Any value other than `on` or `off` (or `local` or `server` for `--verify`) exits `2`. Requires the repo to be linked; run in an unlinked repo it exits `2` before it looks at the flags at all:
+Edits `.reticle/cloud.json` in place. Any value other than `on` or `off` (or `local` or `server` for `--verify`) exits `2`. `--harness on|off` switches the Harness for this project on the platform, not in `cloud.json`. Each drive spends the workspace's credits. It exits `1` when the platform did not switch it (locked, no access, or offline). Requires the repo to be linked; run in an unlinked repo it exits `2` before it looks at the flags at all:
 
 ```
 reticle: no .reticle/cloud.json here ... run `reticle connect` first
@@ -70,7 +70,7 @@ reticle: no .reticle/cloud.json here ... run `reticle connect` first
 
 ### `reticle sync`
 
-Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy, and collects decisions made on the dashboard. Each switch removes only its own part: with `sync.runs` off no runs are sent, but flows and records still go unless they are off too. Prints `{ ok, project, sent, pulled }`, where `sent` carries the accepted counts and, when the server refused anything, a `rejected` array naming each run's index and reason and a `refused` array for flows, capsules and derived records. `sent.records` lists only the records the server accepted.
+Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy, and collects decisions made on the dashboard. Each switch removes only its own part: with `sync.runs` off no runs are sent, but flows and records still go unless they are off too. `sync.screenshots` sends the screenshot of each step, and follows `sync.runs` when unset. `sync.video` sends the frames that Reticle takes about once a second between steps while it drives a tab, and follows `sync.screenshots` when unset. Set `"video": false` under `sync` to keep the frames on this machine and still send the step screenshots. Prints `{ ok, project, sent, pulled }`, where `sent` carries the accepted counts and, when the server refused anything, a `rejected` array naming each run's index and reason and a `refused` array for flows, capsules and derived records. `sent.records` lists only the records the server accepted.
 
 Runs go up in batches, so a large backlog is never one oversized request.
 
@@ -82,7 +82,7 @@ npx @reticlehq/server sync --watch
 
 What the platform cannot read is not sent at all, and a `notSent` array says why: a record kind an older platform does not know yet (this one alone leaves `ok` true), or a flow or run in a file version it does not read. Sending those would only be refused again on every cycle.
 
-**A rejection is a failed sync.** If the server refuses any artifact, `ok` is `false` and the command exits `1`, even when other artifacts in the same bundle landed. The reason is kept as the last sync error, which `reticle status` reports, and the background daemon logs it once, until a cycle refuses nothing. A refused run is not offered again until its file changes or the platform reports that it reads more: until then it is listed under `notRetried`, and the summary reads `refused, not retried: N run(s) (reason)`. A refused artifact never reaches the dashboard and is re-offered on every cycle, so partial loss is still loss. `ok: true` and exit `0` mean everything offered was accepted, which includes the common case of a repo that was already up to date. The accepted counts still report what did land, so a partial sync is visible as one.
+**A rejection is a failed sync.** If the server refuses any artifact, `ok` is `false` and the command exits `1`, even when other artifacts in the same bundle landed. The reason is kept as the last sync error, which `reticle status` reports, and the background daemon logs it once, until a cycle refuses nothing. A refused run, flow set or capsule set is not offered again until its file changes, the platform reports that it reads more, the CLI version changes, or seven days pass. Each of these offers it once more. Until then it is listed under `notRetried`, and the summary reads `refused, not retried: N run(s) (reason)`. A refused artifact never reaches the dashboard and is re-offered on every cycle, so partial loss is still loss. `ok: true` and exit `0` mean everything offered was accepted, which includes the common case of a repo that was already up to date. The accepted counts still report what did land, so a partial sync is visible as one.
 
 ### `reticle runs`
 

package/docs/cli/doctor.mdx

@@ -24,7 +24,7 @@ Human-readable lines on stdout, not the JSON log. A healthy setup (rows that pri
 reticle doctor
   node         v22.14.0
   chromium     ✓ installed (chromium-1234)
-  daemon       ✓ running on :4400 (pid 72698, v3.7.0)
+  daemon       ✓ running on :4400 (pid 72698, v3.8.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)
@@ -64,6 +64,8 @@ When nothing has connected, the `sessions` line fails and the daemon's own diagn
 | `desktop` | Only on a desktop project. Every Electron and Tauri misconfiguration here fails silently, so it is diagnosed explicitly |
 | `coverage` | Only with a connected app. What Reticle sees in it, out of eight capabilities: what is missing, what is not seen yet, and, once a verdict recorded a gap, a prompt to paste into your coding agent |
 | `unsynced` | Only when a project folder holds runs the platform never got. Names the folder and the command that sends them, usually `reticle connect` run there |
+| `prompts` | For each agent used here, whether its prompt hook saves each prompt to `.reticle/`, and which agents rely on the MCP instructions instead. Says so when capture is off for the project or the machine |
+| `sync` | Whether the daemon sends this project's work in the background, and why not when it does not: switched off, not linked, or nobody signed in. Adds the last push time and the last error |
 
 ## The chromium line
 

package/docs/cli/feedback.mdx

@@ -7,7 +7,7 @@ icon: comment
 `reticle feedback` is the feedback channel as a command: no prompts, no editor, no account. It exists so the cost of telling the maintainers something is lower than the cost of shrugging and moving on.
 
 ```bash
-npx @reticlehq/server feedback [--rating 1-5] [--bug] "what worked, what didn't"
+npx @reticlehq/server feedback [--rating 1-5] [--bug] [--contact you@example.com] "what worked, what didn't"
 npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "what happened"
 ```
 
@@ -21,6 +21,7 @@ The `--agent` form is for an agent that cannot reach the `reticle_session { acti
 | `--bug` | boolean | `false` | Shorthand for `--kind bug` |
 | `--kind K` | one of `bug`, `gap`, `ambiguity`, `feature_request`, `improvement`, `experience` | `experience`, or `bug` with `--bug` | The report's class. Wins over `--bug` |
 | `--agent` | boolean | `false` | File as the agent, so agent reports never dilute the human rating signal |
+| `--contact EMAIL` | one email address, at most 254 characters | unset | An address for a reply from the maintainers. Sent only when you give it. Anything that is not one plain address is refused |
 
 Everything that is not a flag or a flag's value becomes the message, joined with spaces. Quoting is still your job for shell reasons.
 
@@ -29,27 +30,30 @@ Everything that is not a flag or a flag's value becomes the message, joined with
 The payload is printed **before** it is sent, every time. A channel that carries free text and does not show you what it sends is asking for trust it has not earned.
 
 ```
-sending      {"stack":"vite","version":"3.7.0","os":"darwin","ci":false}
+sending      {"stack":"vite","version":"3.8.0","os":"darwin","ci":false}
 redacted     email (removed before sending)
 thanks       your feedback is in. it genuinely changes what gets built next.
 ```
 
+With `--contact`, one more line names the address, after the `sending` line: `contact      you@example.com (sent so that the maintainers can answer you)`.
+
 `not sent` replaces the last line when the send failed or telemetry is off, and names the reason. Nothing is lost either way: a failed send is kept on disk and retried, and with telemetry off the report is written to disk instead.
 
 Run with no message and no rating, it prints usage and exits `1`. Real capture:
 
 ```
-usage: reticle feedback [--rating 1-5] [--bug] "what worked, what didn't"
+usage: reticle feedback [--rating 1-5] [--bug] [--contact you@example.com] "what worked, what didn't"
        agents: reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "what happened"
        your words go to the maintainers; nothing from your app is ever included.
+       --contact adds an address for a reply. It is sent only when you give it.
 ```
 
 ## Exit codes
 
-| Code | Meaning                                                         |
-| ---- | --------------------------------------------------------------- |
-| `0`  | The report was submitted, or attempted and reported as not sent |
-| `1`  | No message and no rating, or an invalid `--rating` or `--kind`  |
+| Code | Meaning                                                                     |
+| ---- | --------------------------------------------------------------------------- |
+| `0`  | The report was submitted, or attempted and reported as not sent             |
+| `1`  | No message and no rating, or an invalid `--rating`, `--kind` or `--contact` |
 
 ## Worked example
 

package/docs/cli/gate.mdx

@@ -49,7 +49,7 @@ One `reticle_gate` line. Real capture from this repository, with the flow lists
 }
 ```
 
-`downgraded`, `deletedCoverage`, `unflowed`, `coverageRegressed`, `unexecuted`, `coverageStale` and `coverageAccepted` appear only when they are non-empty, and none was present in that run. The coverage categories need a coverage ledger, which a project gets from `reticle_verify { action: "crawl", exhaustive: true }` or `reticle_verify { action: "coverage", app: true }`; without one they never fire. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
+`downgraded`, `deletedCoverage`, `unflowed`, `coverageRegressed`, `unexecuted`, `coverageStale` and `coverageAccepted` appear only when they are non-empty, `flowsWithoutSources` only when it is `true`, and none was present in that run. The coverage categories need a coverage ledger, which a project gets from `reticle_verify { action: "crawl", exhaustive: true }` or `reticle_verify { action: "coverage", app: true }`; without one they never fire. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
 
 ## Exit codes
 

package/docs/cli/help.mdx

@@ -61,7 +61,7 @@ All commands: reticle help all     One command: reticle <command> --help
 
 ## Only in `help all`
 
-`sync`, `runs`, `config`, `affected`, `report`, `context`, `mcp`, `serve`, `drive`, `setup`, `license`, `rollback` and `version`. They all work the same as always; they are left out of the short list because most people never type them. See the [CLI reference](/cli) for one row per command, including the renamed and removed ones.
+`sync`, `runs`, `config`, `affected`, `report`, `context`, `hook`, `mcp`, `serve`, `drive`, `setup`, `license`, `rollback` and `version`. They all work the same as always; they are left out of the short list because most people never type them. See the [CLI reference](/cli) for one row per command, including the renamed and removed ones.
 
 ## Errors print it too
 

package/docs/cli/init.mdx

@@ -10,7 +10,7 @@ icon: wand-magic-sparkles
 npx @reticlehq/server init [--env KEY=VALUE]... [--app <dir>] [--license <key>] [--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]
+                           [--start] [--capture-bodies] [--no-first-run] [--new-id] [--no-prompt-capture]
 ```
 
 ## Flags
@@ -21,10 +21,12 @@ npx @reticlehq/server init [--env KEY=VALUE]... [--app <dir>] [--license <key>]
 | `--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) | Do not run the install. The step becomes `[–]` ("skipped (--no-install); install them yourself: …") with the install command for you to run by hand, rather than vanishing from the plan |
+| `--new-id` | boolean | `false` | Give this checkout a project id of its own. A copied repository keeps the original's `.reticle.json`, and Reticle refuses a session from a second checkout of one id as ambiguous. This replaces `projectId` in this checkout's `.reticle.json` (and in the agent-root copy that names the same id) with the id derived for this folder, and keeps every other field. Nothing in the original checkout changes |
 | `--app <dir>` | string | unset | Pick which app to wire in a monorepo, without changing directory. On its own it implies `--files-only` |
 | `--start` | boolean | `false` | With `--app`, also boot the app the way a plain `init` does |
 | `--capture-bodies` | boolean | `false` | Write `captureNetworkBodies: true` into the Vite plugin call, so request and response bodies are captured |
 | `--no-first-run` | boolean | `false` | Connect and stop, without the coverage summary |
+| `--no-prompt-capture` | boolean | `false` (the hook is installed) | Do not install the prompt hook in each agent's project config. See [prompt capture](/prompt-capture) |
 | `--hooks` | boolean | `false` | Also add a print-only Stop hook to `.claude/settings.json`, merged into what is there. When the agent stops without a claim that held, it prints one line; it never blocks. See [`reticle report`](/cli/report) |
 | `--env KEY=VALUE` | string, repeatable | none | What the app needs to reach a usable state: a key from `.env.example`, a mock backend, a variable that skips an auth wall. A value may contain spaces and `=` |
 | `--license <key>` | string | unset | Write an enterprise license key to `.env` and keep `.env` out of git |
@@ -42,47 +44,50 @@ npx @reticlehq/server init [--env KEY=VALUE]... [--app <dir>] [--license <key>]
   command go with it, because all three only make sense once the tools are reachable.
 </Warning>
 
+## When init runs, and when it asks for a hand
+
+Your agent runs `init` only when you agree. The first `reticle_session` call in a project that was never wired changes no file. It offers the zero-install lease, which checks the running app with nothing installed. `reticle init`, `reticle connect` and a setup request from you still wire the app.
+
+Some apps get a `⚠` manual step instead of an edit:
+
+- **An Electron app with a static `index.html`.** A packaged renderer can also run on `localhost`, so init does not write the localhost-only snippet or `reticle.local.js`. Connect only in development, for example only when `!app.isPackaged`. Keep `reticle.local.js` out of the package: electron-builder `files: ["!reticle.local.js"]`, or Electron Forge `packagerConfig.ignore: [/reticle\.local\.js$/]`.
+- **A Vite config whose `plugins` is a call or the shorthand `{ plugins }`.** Init leaves the config unchanged and tells you where to add `reticle()`.
+
+When `~/.reticle` cannot be written (a sandboxed agent host), init writes the dev server log to `.reticle/logs/` in the project and prints where it is.
+
 ## What it prints
 
-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, `ℹ` done, but incomplete in a way that matters. Captured from a real `--dry-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, `ℹ` done, but incomplete in a way that matters. Captured from a real `--dry-run` inside `apps/bench-app`, trimmed to one row of each kind:
 
 ```
 reticle init (dry run, no files written)
   in /Users/you/reticle/apps/bench-app
 
   [·] MCP server (Claude, global) → global (claude user scope)
-      reticle already registered (install once, used by every project)
   [·] MCP server (Cursor) → /Users/you/.cursor/mcp.json
-      reticle already registered with Cursor
   [⚠] MCP server (Codex CLI) → /Users/you/.codex/config.toml
       add this to /Users/you/.codex/config.toml by hand:
       [mcp_servers.reticle]
       command = "npx"
       args = ["@reticlehq/server", "mcp"]
-
   [✓] 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
+  [✓] Claude Code resume-after-compaction hook → .claude/settings.json
+  [✓] Prompt capture: Claude Code → .claude/settings.json
+  [ℹ] Prompt capture → .reticle/request.json
   [✓] Install dependencies → package.json
-      pnpm add -D @reticlehq/react@3.7.0 @reticlehq/vite-plugin@3.7.0
   [✓] Reticle config → .reticle.json
-      write project config (framework + port)
   [✓] Vite plugin → vite.config.ts
-      add reticle() to plugins (also injects connect())
   [·] Capabilities + store → src/reticle-dev.ts
-      file exists, left alone, it is yours to edit
 
 Restart your dev server (`vite`).
 ```
 
-The install line pins the packages to the version of Reticle you are running. When the `codex` binary is on your PATH, the Codex row is not a hand edit: it reads `[✓] MCP server (Codex CLI)` and registers through `codex mcp add reticle -- npx @reticlehq/server mcp`.
+`init` pins the packages to the version of Reticle you are running. When the `codex` binary is on your PATH, the Codex row is not a hand edit: it reads `[✓] MCP server (Codex CLI)` and registers through `codex mcp add reticle -- npx @reticlehq/server mcp`.
 
-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.
+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. A successful run ends with one more line, `Tell us what you are building: https://discord.gg/BwAbzv9ZRz`. A dry run and a failed run do not print it.
 
 With `--no-mcp`, the whole MCP and rules group collapses into one skipped line:
 
@@ -103,7 +108,6 @@ Several apps found in this workspace. Re-run `reticle init` for the one you want
   reticle init --app apps/large-dom-bench
   reticle init --app apps/next-smoke
   reticle init --app apps/tauri-smoke
-  reticle init --app apps/vibe-builder-demo
 ```
 
 Given `--app`, it writes that app's files and starts nothing: no daemon and no dev server, since a monorepo app's dev server is often run from the root. Add `--start` to boot it the way a plain `init` does. It says which directory it moved to before printing the plan:

package/docs/cli/mcp.mdx

@@ -16,7 +16,7 @@ This is what `reticle init` registers, so you rarely type it yourself.
 
 | Flag | Type | Default | What it does |
 | --- | --- | --- | --- |
-| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Bridge port |
+| `--port N` | number | `RETICLE_PORT`, else the port in `.reticle.json`, else `4400` | The preferred bridge port. When this project's daemon runs, the proxy uses it on any port. When another project's daemon holds the preferred port, the proxy uses a free port. A wake resolves the port again |
 | `--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 | on when `CI` or `RETICLE_HEADLESS` is set, or on Linux with no display | Hide that browser |
 | `--headed` | boolean | on otherwise | Show it |
@@ -26,11 +26,14 @@ This is what `reticle init` registers, so you rarely type it yourself.
 
 ## 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". Four 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". Seven 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.
 - Reconnect is self-healing: if the daemon exited, crashed, was stopped, or shut itself down as idle, the reconnect path spawns a new one rather than retrying a dead port until the budget runs out.
+- A wake resolves the port again. When another project's daemon took the port after an idle exit, the proxy finds this project's daemon where it moved, or starts one on a free port, and connects there.
+- After an update, a proxy that meets an older daemon with no tab and no other agent attached stops it and starts the daemon of its own release. When a tab or another agent is attached, or the daemon is older than 3.6.0, the daemon stays and the proxy describes the version difference.
+- A short drop of the link does not end your session. Each proxy sends a fixed id on every connect, so it keeps its identity, its leases and its tab. The daemon waits 10 seconds after the last agent detaches before it ends the browser sessions. A daemon that has served a tool call counts an agent that attached in the last 30 minutes as attached, so a client that starts a new proxy for each turn (Codex) does not wait for a cold start.
 - A proxy with no client traffic and no work in flight exits after 24 hours, so abandoned editor sessions do not leave process pairs behind forever. Set `RETICLE_MCP_PROXY_IDLE_MS=0` to disable that watcher, or set an explicit millisecond window.
 
 ## What it prints

package/docs/cli/open.mdx

@@ -7,7 +7,7 @@ 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 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]
+npx @reticlehq/server open [url] [--port N] [--navigate]
 ```
 
 ## Arguments and flags
@@ -16,17 +16,20 @@ npx @reticlehq/server open [url] [--port N]
 | --- | --- | --- | --- |
 | `url` | string, positional, optional | unset | The URL to open. Omit it to reuse a connected tab |
 | `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Bridge port. If nothing is on it, `open` discovers a running daemon rather than making you hunt |
+| `--navigate` | flag | off | When a tab of this project on the url's origin is connected but on another page, move that tab to the url and wait for it to arrive. Exits `1` when the move fails. Without it the tab is left where it is |
 
 It is idempotent. Re-running never piles up duplicate tabs.
 
 ## What it prints
 
-One `reticle_open` line, whose fields say which of four things happened.
+One `reticle_open` line, whose fields say which of these happened.
 
 | Fields | Meaning |
 | --- | --- |
 | `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 |
+| `navigated` + `sessionId` (+ `landedOn`) | With `--navigate`: that tab was moved to the url and arrived. `sessionId` is the session it reconnected as, and `landedOn` names a redirect when the page ended somewhere else |
+| `requested` + `note` (with `--navigate`) | The browser accepted the navigation but no page on the url reconnected in the wait window, so arrival was not observed |
 | `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

@@ -33,7 +33,7 @@ An `unknown` is never counted as held. It is Reticle saying it could not tell, a
 
 ## 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`, 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:
+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`, so you see the line when the agent stops. It blocks the stop in one case only: a Harness drive that the agent started is still running (for at most 30 minutes from its start). Then it prints `{ "decision": "block", "reason": … }`, and the reason tells the agent to poll the drive until it ends. `reticle init --hooks` adds it for you, merged into whatever `.claude/settings.json` already holds. By hand:
 
 ```json
 {

package/docs/cli/restart.mdx

@@ -31,7 +31,7 @@ Real capture, restarting over a running daemon (exit `0`), with the long `note`
 Real capture, when the port is held by something that is not ours (exit `1`). Both `reason` strings are trimmed at the ellipsis:
 
 ```
-{"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.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. If that is what you meant, `reticle restart --force` stops it and starts Reticle there (`stop --force` never does); 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"}
 ```
 

package/docs/cli/rollback.mdx

@@ -24,10 +24,10 @@ Telemetry records the move as a `version_changed` event with `direction: "rollba
 
 ## Exit codes
 
-| Code | Meaning                                                     |
-| ---- | ----------------------------------------------------------- |
-| `0`  | The previous version was reinstalled and the process exited |
-| `1`  | There was nothing to roll back to, or the restore threw     |
+| Code | Meaning |
+| --- | --- |
+| `0` | The previous version was reinstalled and the process exited. Also `0` under `npx`, where nothing is reinstalled: see the warning above |
+| `1` | There was nothing to roll back to, or the restore threw |
 
 ## Worked example
 

package/docs/cli/serve.mdx

@@ -24,7 +24,9 @@ Most people never type this. Your agent runs [`reticle mcp`](/cli/mcp), which st
 | `--http-port N` | number | unset (`7331`) | Port for that endpoint. Requires `--http`. |
 | `--http-token T` | string | unset | Bearer token the endpoint requires. Requires `--http`. |
 
-The HTTP flags are honoured or refused, never silently dropped: against an already-running daemon that does not serve the requested verify port, `serve --http` exits 1 and names both ports. A running daemon keeps the flags it was started with, so `reticle stop`, then serve again. A verify port that cannot be bound fails the daemon start with a `reticle_daemon_start_failed` line naming that port.
+The HTTP flags and `--drive` are honoured or refused, never silently dropped: against an already-running daemon that does not serve the requested verify port, `serve --http` exits 1 and names both ports. A running daemon keeps the flags it was started with, so `reticle stop`, then serve again. A verify port that cannot be bound fails the daemon start with a `reticle_daemon_start_failed` line naming that port.
+
+When `serve --drive <url>` finds a running daemon, it exits `1` rather than silently ignoring the URL. Its stderr includes a copyable `reticle drive` command with the requested URL. On a non-default bridge port it prefixes the command with `RETICLE_PORT=N` to select the existing daemon. The `drive` command does not support a `--port` flag; see [`reticle drive`](/cli/drive).
 
 ## What it prints
 
@@ -49,10 +51,10 @@ port 4498 is held by another process that is not a Reticle daemon ... a daemon c
 
 ## Exit codes
 
-| Code | Meaning                                                                           |
-| ---- | --------------------------------------------------------------------------------- |
-| `0`  | A daemon is up on the port, whether this run started it or found it               |
-| `1`  | The port is held by a foreign process, or the child never bound within 15 seconds |
+| Code | Meaning |
+| --- | --- |
+| `0` | A daemon is up on the port and no incompatible flags were supplied |
+| `1` | The port is held by a foreign process, the child never bound, or `--drive` was refused on an existing daemon |
 
 <Note>
   `serve` reports the **bind**, not the spawn. It used to exit `0` the moment it forked, while the

package/docs/cli/setup.mdx

@@ -20,4 +20,4 @@ One line per agent: `✓ <agent>` for a new registration, `✓ <agent> (already
 
 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.
+Codex CLI keeps a TOML config. When the `codex` binary is on your PATH, Reticle registers through `codex mcp add`. Otherwise it prints the hand-edit lines above. Reticle then adds one line, `default_tools_approval_mode = "approve"`, under `[mcp_servers.reticle]` in `~/.codex/config.toml`. This line approves Reticle's own tools, so Codex does not ask before each call. Reticle changes no other line, and it keeps a mode that you set. To undo it, change that line to `default_tools_approval_mode = "prompt"`. Reticle does not change a mode that is already there.

package/docs/cli/status.mdx

@@ -34,7 +34,7 @@ reticle status
   sessions     ✓ 2 pages connected
                http://localhost:5173/  (throttled, hidden)
                http://localhost:7699/  (throttled, hidden)
-  agent link   enumerated
+  agent link   ✓ your agent has read and used Reticle's tools
 ```
 
 And with no daemon on the port:
@@ -43,7 +43,11 @@ And with no daemon on the port:
 reticle status
   daemon       ✗ not running on :4999
                port presence: free
-  agent link   never-attached
+  agent link   no agent has started Reticle on this port yet
+               no MCP client has started Reticle on this port, so either the server is not
+               registered with your client or nothing has attached since this record began:
+               register it with `npx @reticlehq/server init`, then restart your MCP client and
+               run status again.
   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
                something, then run status again.

package/docs/cli/stop.mdx

@@ -22,7 +22,7 @@ npx @reticlehq/server stop [--port N] [--quiet] [--force]
 
 ## How it stops
 
-1. `SIGTERM` first, then poll every 100ms.
+1. Ask the daemon to stop with `POST /shutdown` on loopback, with the pairing token. The daemon then runs its normal shutdown path on every OS, Windows included. An older daemon without the route, or a refused request, gets `SIGTERM` instead. Then poll every 100ms.
 2. Still alive after 5 seconds: `SIGKILL`. A daemon that ignores `SIGTERM` is wedged, which is the one situation this command exists for, and giving up there left the port held and a human reaching for `kill -9`.
 3. Still alive 2 seconds after that: report `reticle_daemon_stop_timeout` with the pid and exit `1`. Surviving `SIGKILL` means the pid is not yours to kill, or it is an unkillable zombie. Neither is retryable.
 
@@ -79,7 +79,7 @@ With `--quiet` that same run prints nothing at all and still exits `0`.
 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`.
+4. For a Reticle daemon, `POST /shutdown` first, as above; else `SIGTERM`. Then `SIGKILL` after 5 seconds, then report that it survived and exit `1`.
 
 ### What `--force` prints
 
@@ -94,7 +94,7 @@ Killed:
 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"}
+{"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. If that is what you meant, `reticle restart --force` stops it and starts Reticle there (`stop --force` never does); or start Reticle on another port.","holder":"Python"}
 ```
 
 Nothing to free:

package/docs/cli/telemetry.mdx

@@ -52,6 +52,10 @@ npx @reticlehq/server telemetry disable
 <Card title="Exactly what is collected" icon="shield-check" href="/telemetry">
   The complete list, in plain language, and every way to switch it off.
 </Card>
-<Card title="Every event, in schema detail" icon="database" href="/telemetry-events">
+<Card
+  title="Every event, in schema detail"
+  icon="database"
+  href="https://github.com/reticlehq/reticle/blob/main/contributing/telemetry/events.md"
+>
   The contributor reference: payload blocks, field types, and what each event exists to answer.
 </Card>

package/docs/cli/try.mdx

@@ -12,12 +12,12 @@ 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
+## Link the folder 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:
+The drive runs on the Reticle platform, so `try` needs a linked folder. Being signed in is not enough. In a folder that is not linked it drives nothing and says:
 
 ```
-Sign in first: reticle connect (it is free, no card)
+Link this folder first: reticle connect. It signs you in if you are not, and it is free, no card.
 ```
 
 Run [`reticle connect`](/cli/cloud) in the folder, then run `try` again. It exits `1` in this case.
@@ -32,7 +32,7 @@ Run [`reticle connect`](/cli/cloud) in the folder, then run `try` again. It exit
 ## 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.
+2. It opens the URL in a window that you can watch, through the Reticle daemon. It starts the daemon 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.
 
@@ -56,7 +56,7 @@ If the run could not be sent, `try` says so, keeps the run on this machine and t
 
 ## 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           |
+| Code | When |
+| --- | --- |
+| `0` | The drive ran. Broken journeys are a finding, not a failure of the command |
+| `1` | The folder is not linked, no free drive was granted, the drive could not run, or an argument was wrong |

package/docs/cli/update.mdx

@@ -15,9 +15,9 @@ No flags.
 ## What it does, in order
 
 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.
+2. Compare by **direction**. Reticle installs a registry version only when it is newer than the running version. It never installs an older one.
 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.
+4. Otherwise, update the Reticle block in the agent rule files that already have one. Then update the **app's SDK first**, so that the CLI and the SDK stay on the same version.
 5. Then apply the CLI update, which execs and exits. Your agent client restarts it.
 
 ## What it prints
@@ -27,6 +27,8 @@ 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_update_applying`, `reticle_update_applied` | `version`, `executionKind` (`global`, `local` or `npx`) |
+| `reticle_update_npx_strategy` | `note`: under `npx` nothing is installed; the next start fetches the new version |
 | `reticle_rules_refreshed` | `files`, `to`: the agent rule files whose Reticle block was brought up to the new version |
 | `reticle_update_failed` | The error |
 
@@ -57,7 +59,8 @@ npx @reticlehq/server update
 ```
 
 <Warning>
-  Attaching to a running daemon is what a daemon is for, which means an upgrade does not take effect
-  until that daemon dies. Run [`reticle stop`](/cli/stop) afterwards if you need the new build
-  serving immediately.
+  A daemon that is already running keeps its own version. When no tab and no other agent is attached
+  to it, your agent's new MCP server stops it and starts the new version. When a tab or another
+  agent is attached, the old daemon keeps running. Run [`reticle restart`](/cli/restart) to start
+  the new version now.
 </Warning>

package/docs/cli/verify.mdx

@@ -7,7 +7,7 @@ icon: circle-check
 `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>]
+npx @reticlehq/server verify <url> [--headed] [--timeout N] [--storage-state <file>] [--expect <json> | --expect-file <path>]
 ```
 
 It uses the same runner and the same verdict as the MCP and HTTP paths, so a platform agent that can only run a shell command gets a byte-identical artifact.
@@ -18,16 +18,23 @@ It uses the same runner and the same verdict as the MCP and HTTP paths, so a pla
 | --- | --- | --- | --- |
 | `url` | string, positional, **required** | none | The preview URL to drive |
 | `--headed` | boolean | `false` (headless) | Show the browser |
-| `--timeout N` | number, ms | `15000` | How long to wait for a browser session to dial back |
+| `--timeout N` | number, ms | `15000` | How long to wait for a browser session to dial back. With `--expect`, how long the predicate may take to come true instead, default `4000` |
 | `--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 |
+| `--results-json <file>` | string | unset | Also write one verdict per journey to this file: `{ verdict, results: [{ journey, verdict, reason?, runId? }] }`, each verdict `yes`, `no` or `unknown`. A skipped journey is `unknown`, and the run is `yes` only when every journey is. `runId` names the run the journey came from, and is set only when that run reached the platform. 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` |
+| `--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. Waits up to `--timeout` for the predicate, the way `reticle_assert { action: "wait" }` does, so a request still in flight after the page loads is waited for. 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`. Needs a linked project (`reticle connect`, or `RETICLE_API_KEY` in CI). It runs at any instrumentation score |
 | `--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. |
 
+On Windows PowerShell, write the predicate to a file and pass `--expect-file` so the JSON never goes through shell quoting:
+
+```powershell
+'{"kind":"text","contains":"Saved"}' | Set-Content expect.json
+npx @reticlehq/server verify http://localhost:3000 --expect-file expect.json
+```
+
 ## What it prints
 
 The rendered run report on stdout. On failure it names the cause on stderr instead, and there are two refusals worth knowing:

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.7.0
+3.8.0
 ```
 
 ## Exit codes