@reticlehq/server 3.2.0 → 3.4.0

package/docs/cli/report.mdx

@@ -0,0 +1,44 @@
+---
+title: reticle report
+description: What the latest session claimed, and what held. Also a print-only Stop hook for Claude Code.
+icon: clipboard-check
+---
+
+`reticle report` reads this project's most recent session from `.reticle/` and says how many of its claims held, how many failed, how many came back `unknown` and who can act on each, and how many proved nothing. It reads the journal on disk, so no daemon has to be running.
+
+```bash
+npx @reticlehq/server report [--session <id>] [--hook]
+```
+
+## Arguments and flags
+
+| Flag | Default | What it does |
+| --- | --- | --- |
+| `--session <id>` | the newest session | Report a specific session |
+| `--hook` | off | Print one line, and only when the working tree changed and no claim held |
+
+## What it prints
+
+```text
+session lease-85f8191b-3874-457b-973b-8ee365e5acfb
+2 of 4 claims held
+1 failed, 1 of them a green a channel contradicted
+1 unknown (environment: 1)
+  ✗ signal order:placed
+```
+
+An `unknown` is never counted as held. It is Reticle saying it could not tell, and the owner beside it says what to do next.
+
+## As a Claude Code Stop hook
+
+With `--hook` it prints nothing when a claim held or nothing in the tree changed, and otherwise one line, such as `Reticle: not verified. 3 claims: 1 failed, 2 unknown`. It prints Claude Code's `systemMessage` shape and always exits `0`: you see the line when the agent stops, and the agent is never blocked by it. `reticle init --hooks` adds it for you, merged into whatever `.claude/settings.json` already holds. By hand:
+
+```json
+{
+  "hooks": {
+    "Stop": [{ "hooks": [{ "type": "command", "command": "npx @reticlehq/server report --hook" }] }]
+  }
+}
+```
+
+A session last written more than an hour ago does not count as this turn, so a morning drive cannot answer for an afternoon edit. If you want the stop blocked until the change is verified, use [`reticle gate --hook`](/cli/gate) instead.

package/docs/cli/update.mdx

@@ -31,6 +31,16 @@ No flags.
 
 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.
 
+## Stuck on an older Windows release
+
+Reticle 3.1.0 and older cannot apply this update on Windows and may fail with `spawn EINVAL`. Those releases run their own outdated updater, so retrying the command will not help. Run the installer directly from PowerShell instead:
+
+```powershell
+irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex
+```
+
+This installs the current server without going through the old updater.
+
 ## Exit codes
 
 | Code | Meaning                                                              |

package/docs/cli.mdx

@@ -112,6 +112,15 @@ policy       https://github.com/reticlehq/reticle/blob/main/docs/telemetry.md
 
 A bare `reticle` with no arguments is not help. It is `reticle serve`.
 
+<Note>
+  When the Reticle SDK installed in the project is a different **major** version from the CLI you ran,
+  the CLI hands the same command to `npx @reticlehq/server@<that version>`, so an unpinned
+  `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.
+</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

package/docs/desktop.mdx

@@ -88,7 +88,7 @@ The rows in **bold** are re-proven by a committed battery on every change, `pnpm
 | Capability | Electron | Tauri | Note |
 | --- | --- | --- | --- |
 | sessions, snapshot, query, inspect | yes | yes | `inspect` returns `src/App.tsx:104` in a dev build; a packaged production renderer has no source map, so it reports `n/a` |
-| capabilities, state (live store) | yes | yes | `reticle_state` reads the real store |
+| capabilities, state (live store) | yes | yes | `reticle_look { action: "state" }` reads the real store |
 | act (click/fill/type/select) | yes | yes |  |
 | **act_and_wait, wait_for, assert** | yes | yes | signal / state / route / net / console predicates |
 | console errors | yes | yes | catches what the UI never shows |
@@ -133,7 +133,7 @@ export default defineConfig({
 });
 ```
 
-`desktop: true` does the two things a desktop shell needs and a web app must never get: the plugin also runs for `vite build` (a packaged renderer is a production build with **no dev server**, so the default serve-only gating would ship an app with no `connect()` at all), and `connect()` is called with `allowInProduction` so the SDK's production backstop does not refuse to start. Keep it behind your own dev-only build so an instrumented bundle can never reach a release binary.
+`desktop: true` does two things a desktop shell needs: `connect()` is injected into the renderer's entry module, so a renderer loaded with no dev server still resolves it, and it is called with `allowInProduction`, because a packaged renderer reports `NODE_ENV=production` and the SDK's production backstop would otherwise refuse to start. It instruments the dev server, and a `vite build` **only when that build runs in a non-production mode**: `vite build --mode development`, for a packaged renderer you want to drive with no dev server. A production-mode build, which is what `vite build` and `electron-vite build` do by default, is stubbed exactly like a web bundle: it carries no SDK and never dials `ws://localhost`, so a release binary built the normal way is clean.
 
 Nothing to add in your app code. You can still call `reticle.connect()` by hand and pass `inject: false` if you want control.
 
@@ -157,10 +157,12 @@ That line is what makes your main-process calls visible. It has to live in the p
 
 **Preload sandboxing.** A sandboxed preload cannot resolve `node_modules`, so the bare `require` above fails with `module not found: @reticlehq/electron/preload`. Either bundle your preload (electron-vite and Electron Forge do this by default; the require is inlined at build time and sandboxing stays on), or set `sandbox: false` in `webPreferences`.
 
-**Packaged renderers.** An app that loads its renderer with `loadFile` runs on `file://`, which is a production Vite build. Pass `allowInProduction: true` to `connect()` for that mode, or keep the SDK gated behind `import.meta.env.DEV` so it never enters the shipped binary at all.
+**Packaged renderers.** An app that loads its renderer with `loadFile` runs on `file://` with no dev server. To drive one, build its renderer with `vite build --mode development` (the plugin then instruments it, `allowInProduction` included). The default production-mode build ships no Reticle code at all.
 
 Working example: [`apps/electron-smoke`](https://github.com/reticlehq/reticle/tree/main/apps/electron-smoke).
 
+**Electron Forge.** `reticle init` recognises Forge's Vite template (`vite.renderer.config.*` and no `vite.config.*`) and wires it the same three ways: `reticle()` in the renderer config, the preload shim, and `installReticleCapture` in main. The plugin goes in **without** `desktop: true`, because `electron-forge start` serves the renderer through a real Vite dev server, so the ordinary serve-time injection reaches the window and `electron-forge package` ships a renderer with no Reticle code. `init` starts the app with the script that runs `electron-forge start`, not the renderer's dev script. A vanilla renderer gets `@reticlehq/browser` rather than the React kit.
+
 ## Tauri setup
 
 Frontend side, nothing desktop-specific:
@@ -214,7 +216,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "3.2"
+reticle-tauri = "3.4"
 ```
 
 ```rust
@@ -283,12 +285,12 @@ A packaged renderer runs on `file://`, where `pushState('/settings')` rewrites t
 
 ## What IPC looks like to an agent
 
-A desktop app reaches its backend over IPC, not HTTP. `fetch`/`XHR` patching cannot see that, so without the IPC observer every backend call in your app is a blind spot: `reticle_network` returns nothing, `act_and_wait` has no in-flight request to settle on, and `assert { net }` is vacuously true. That is a false green by construction.
+A desktop app reaches its backend over IPC, not HTTP. `fetch`/`XHR` patching cannot see that, so without the IPC observer every backend call in your app is a blind spot: `reticle_observe { action: "network" }` returns nothing, `act_and_wait` has no in-flight request to settle on, and `assert { net }` is vacuously true. That is a false green by construction.
 
 Reticle records each IPC call as an ordinary request, so the tools you already use work unchanged:
 
 ```jsonc
-// reticle_network { urlContains: "ipc://" }
+// reticle_observe { action: "network", urlContains: "ipc://" }
 {
   "calls": [
     { "method": "ipc", "url": "ipc://todos:load", "status": 200, "ms": 134 },
@@ -297,7 +299,7 @@ Reticle records each IPC call as an ordinary request, so the tools you already u
 }
 ```
 
-IPC has no status code. `200`/`500` are synthetic, mapped from whether the call succeeded or failed, precisely so that `reticle_network { status: 500 }` and `assert { kind: "net", status: 500 }` keep working. On Tauri you will see `status: 500` next to `statusText: "OK"`. That is not a bug: the transport really did answer 200, and the 500 is the command's own verdict. `ok` is authoritative, and on Electron `error` carries the message your main process returned:
+IPC has no status code. `200`/`500` are synthetic, mapped from whether the call succeeded or failed, precisely so that `reticle_observe { action: "network", status: 500 }` and `assert { kind: "net", status: 500 }` keep working. On Tauri you will see `status: 500` next to `statusText: "OK"`. That is not a bug: the transport really did answer 200, and the 500 is the command's own verdict. `ok` is authoritative, and on Electron `error` carries the message your main process returned:
 
 ```jsonc
 // reticle_assert { predicate: { kind: "net", urlContains: "ipc://todos:archive", status: 500 } }
@@ -363,9 +365,11 @@ Playwright MCP is faster. It is also structurally unable to see an IPC failure,
     Tauri, no: WKWebView exposes no CDP endpoint, so Playwright cannot attach at all.
   </Accordion>
   <Accordion title="Does the SDK end up in my shipped binary?">
-    Only if you put it there. Keep the plugin behind a dev-only build, or gate `connect()` on
-    `import.meta.env.DEV`. `desktop: true` exists because a packaged renderer is a production build,
-    so it opts that one build into instrumentation deliberately.
+    No, not from a normal build. With `desktop: true` a production-mode `vite build` or
+    `electron-vite build` is stubbed like a web bundle: no SDK, no `ws://localhost` dial. Only a
+    build you run in another mode (`vite build --mode development`) is instrumented, which is how
+    you drive a packaged renderer with no dev server. A `connect()` you wrote by hand is yours to
+    gate on `import.meta.env.DEV`.
   </Accordion>
   <Accordion title="Why does a Tauri response show status 500 with statusText OK?">
     The IPC transport really did answer HTTP 200. The 500 is Reticle translating the Rust command's

package/docs/environment.mdx

@@ -0,0 +1,87 @@
+---
+title: Environment variables
+description: Every environment variable Reticle reads, what it changes, and which process reads it.
+icon: sliders
+---
+
+Reticle works with none of these set. Each one changes a single behaviour, and most are read once, by the process named in the table: the daemon at startup, the CLI command you run, or a build plugin when your dev server starts. A daemon that is already running keeps the values it started with, so after changing a daemon setting run `npx @reticlehq/server restart`.
+
+## Connection and ports
+
+| Variable | Read by | What it does |
+| --- | --- | --- |
+| `RETICLE_PORT` | daemon, CLI, build plugins | The bridge and daemon port. `.reticle.json`'s `port` sets it per project; this overrides it. |
+| `RETICLE_HOST` | daemon | The bridge bind host. Loopback by default. Anything else exposes the bridge beyond this machine, so it is opt-in. |
+| `RETICLE_TOKEN` | daemon | A shared secret the page must present when it connects. The pairing token covers this automatically; set it only for a hand-wired setup. |
+| `RETICLE_PAIRING_TOKEN_DIR` | daemon, `init`, build plugins | Where the auto-provisioned pairing token lives. Defaults to `~/.reticle`. Relocate it for CI or a read-only home directory. |
+| `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_DEV` | `@reticlehq/next` | Instrument even when `NODE_ENV` says production, for `NODE_ENV=production next dev`. |
+
+## Daemon lifetime
+
+| Variable | Read by | What it does |
+| --- | --- | --- |
+| `RETICLE_IDLE_SHUTDOWN_MS` | daemon | How long the daemon waits with no agent, no page and no lease before it exits. `0` keeps it running. |
+| `RETICLE_IDLE_ATTACHED_MS` | daemon | The same wait while an agent is attached, which is longer so a slow install or a thinking human is not cut off. Derived from the base when unset. |
+| `RETICLE_MCP_PROXY_IDLE_MS` | MCP proxy | How long an abandoned MCP stdio proxy waits before it exits. `0` disables the watcher. |
+| `RETICLE_JOURNAL` | daemon | Turns the causal journal off (`0`, `false`, `off`) or on. On by default. |
+
+## Browser
+
+| 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_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. |
+
+## Tools and output
+
+| 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_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. |
+| `RETICLE_NO_UPSELL` | daemon | Silences every upgrade hint. |
+
+## Gate and CI
+
+| Variable | Read by | What it does |
+| --- | --- | --- |
+| `RETICLE_SKIP_GATE` | `reticle gate --hook` | Lets an agent's stop hook proceed past a failing gate. The skip is printed and recorded, never silent. It does not affect `reticle gate` without `--hook`, which is what CI runs. |
+| `RETICLE_VERIFY_TOKEN` | `reticle serve --http` | The bearer token the optional HTTP verify endpoint requires. |
+| `RETICLE_SECRET_<FIELD>` | replay, verify, crawl | The value typed into a password or secret field at replay. A recorded flow never stores it. See [what is recorded](/what-is-recorded). |
+
+## Cloud and the autonomous drive
+
+| Variable | Read by | What it does |
+| --- | --- | --- |
+| `RETICLE_API_KEY` | CLI, daemon | The API key minted on the platform. |
+| `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. |
+
+## Licensing
+
+| Variable | Read by | What it does |
+| --- | --- | --- |
+| `RETICLE_LICENSE_KEY` | daemon | The Enterprise licence key. See [licence activation](/license-activation). |
+
+## Telemetry and feedback
+
+| Variable | Read by | What it does |
+| --- | --- | --- |
+| `RETICLE_TELEMETRY` | CLI, daemon | `0`, `false` or `off` turns anonymous usage telemetry off. `DO_NOT_TRACK` is honoured too. See [telemetry](/telemetry). |
+| `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_TRACE` | daemon, CLI | Verbose internal tracing for people working on Reticle itself. Off by default. |

package/docs/faq.mdx

@@ -23,22 +23,16 @@ You get considerably better results by adding `data-testid` attributes and by [e
 </Accordion>
 
 <Accordion title="Does it work without React?">
-  The core is framework-agnostic: DOM, network, routing, console, animations, snapshots and actions are gated against a vanilla TypeScript app.
+  Yes. The core is framework-agnostic: DOM, network, routing, console, animations, snapshots and actions are gated against a vanilla TypeScript app. What varies by framework is how `connect()` gets in and whether you get a source pointer on top.
 
-Support beyond that is uneven, and we would rather say so than let you find out:
-
-| Framework | Status |
-| --- | --- |
-| React, Next.js, Remix, Astro | Supported, each with an app and a CI gate |
-| SvelteKit | Wired end to end. `init` writes the client hook, the plugin stamps `.svelte` source. But **no CI gate**, so unverified rather than supported |
-| Vue | A Pinia store adapter and nothing else. No detection, no `.vue` stamping, no gate |
+[Frameworks](/frameworks) is the one list of what is proven for each, from "driven to a verdict in CI" to "install gated" to "wired, unverified".
 
 </Accordion>
 
 <Accordion title="Can it tell me whether my UI looks good?">
-  No. Reticle verifies behaviour, not aesthetics. Visual correctness and "does this feel right" remain a human job, or a visual-diff tool's.
+  Reticle verifies behaviour, not aesthetics. Visual correctness and "does this feel right" remain a human job, or a visual-diff tool's, and Reticle pairs well with one.
 
-It does read design tokens. [`reticle_inspect`](/tools/inspect) reports whether a colour came from your theme or from someone's clipboard. But that is a consistency check, not taste.
+It does read design tokens. [`reticle_look { action: "element" }`](/tools/inspect) reports whether a colour came from your theme or from someone's clipboard. But that is a consistency check, not taste.
 
 </Accordion>
 
@@ -58,7 +52,7 @@ Measured on the same app: Reticle caught 10 of 10 injected bugs, Playwright MCP
 </Accordion>
 
 <Accordion title="Can I run several apps or tabs at once?">
-  Yes. Each is a session. Pass `sessionId` to any tool when more than one is connected, and [`reticle_sessions`](/tools/sessions) lists them.
+  Yes. Each is a session. Pass `sessionId` to any tool when more than one is connected, and [`reticle_session { action: "list" }`](/tools/sessions) lists them.
 
 Reticle scopes to your project and prefers the active tab, and it **refuses rather than guesses** when the choice is ambiguous. A refusal you can act on beats a silent pick of the wrong tab.
 
@@ -74,9 +68,9 @@ 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, localhost-only and offline. Credential-shaped values are redacted before they leave the page. You will see `[REDACTED]` in request bodies without configuring anything.
+  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.
 
-Anonymous usage telemetry is sent separately and can be turned off with `reticle telemetry disable`.
+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.
 
   <Card title="Exactly what is collected" icon="chart-line" href="/telemetry">
     The complete list. If it is not on that page, it is not sent.
@@ -85,7 +79,7 @@ Anonymous usage telemetry is sent separately and can be turned off with `reticle
 
 <Accordion title="Does it work with WebGL / react-three-fiber?">
   Partially. Reticle's model of an app is DOM + store + network. A WebGL or react-three-fiber
-  subtree is a single `<canvas>` to `reticle_query` / `reticle_snapshot`: Reticle cannot pick faces
+  subtree is a single `<canvas>` to `reticle_look { action: "find" }` / `reticle_look { action: "page" }`: Reticle cannot pick faces
   or drive the camera inside the scene.
 
 DOM, registered store state, and network **around** the canvas still work, and that is often where the consequential bugs live (import counts, mesh stats, solver results that contradict the UI). `init` prints this limit when it detects react-three-fiber so an adopting team does not discover it only after trying to verify the feature they care about.
@@ -93,9 +87,9 @@ DOM, registered store state, and network **around** the canvas still work, and t
 </Accordion>
 
 <Accordion title="Is Reticle proven to make agents fix more bugs?">
-  No, and we are not going to claim it. A controlled test of fix-rate did **not** show an improvement. The benchmark was confounded in ways we can point at, and we consider the question open.
+  No. A fix-loop test on a small fixture found the same fix rate with and without Reticle, at two model tiers, and the Reticle arm made more tool calls. The fixture was small enough to read whole and the pass check looked for a string rather than behaviour, so the question is open. [Why Reticle](/why-reticle#what-the-fix-rate-test-measured) has the details.
 
-What is measured is detection: 10 of 10 injected regressions caught, with zero false alarms on a known-good control, against 9 and 8 for the alternatives.
+What Reticle is built to improve is the verdict: in the 88-bug head-to-head against a Playwright script it reported one false green to the script's 29, and on a known-good control it raised no false alarms.
 
 </Accordion>
 
@@ -108,4 +102,12 @@ What is measured is detection: 10 of 10 injected regressions caught, with zero f
     Which tools are advertised directly, and why each earned its slot.
   </Card>
 </Accordion>
+
+<Accordion title="Can I use it for security, accessibility, performance or SEO checks?">
+  Yes, for how your own running app behaves: access control by role, calls that must never fire, CSP violations, roles and focus, request counts and long tasks, titles, headings, links and redirects. It pairs with a vulnerability scanner, an accessibility audit tool such as axe and an SEO crawler, which cover what an in-app check does not.
+
+  <Card title="Use cases" icon="list-check" href="/use-cases">
+    What each one checks, with a call you can run.
+  </Card>
+</Accordion>
 </AccordionGroup>

package/docs/first-drive.md

@@ -46,18 +46,10 @@ If `~/.reticle/pairing-token` does not exist yet, run any `reticle` command once
 
 This is the shortest path to seeing Reticle work, and it needs no MCP client at all.
 
-Open the app in a browser. Use a real one, or:
+Ask for a verdict, naming the app's url. With no tab open on that origin, Reticle opens one in a browser it drives (Playwright's Chromium, or an installed Chrome or Edge when that is missing) and closes it afterwards; a tab you already have open is used instead:
 
 ```bash
-node -e "require('playwright').chromium.launch({headless:true})
-  .then(b=>b.newPage().then(p=>p.goto('http://localhost:4310/')
-  .then(()=>new Promise(r=>setTimeout(r,60000)))))" &
-```
-
-Then ask for a verdict:
-
-```bash
-node server/dist/command/cli.js verify "" --port 4400 \
+node server/dist/command/cli.js verify http://localhost:4310/ --port 4400 \
   --expect '{"kind":"text","contains":"Reticle"}'
 ```
 
@@ -72,7 +64,7 @@ That is the whole product in one line: a claim, checked against a running page,
 Try making it fail, because a tool that only ever says yes is not telling you anything:
 
 ```bash
-node server/dist/command/cli.js verify "" --port 4400 \
+node server/dist/command/cli.js verify http://localhost:4310/ --port 4400 \
   --expect '{"kind":"text","contains":"definitely not on this page"}'
 ```
 
@@ -80,8 +72,8 @@ node server/dist/command/cli.js verify "" --port 4400 \
 
 If your editor has the Reticle MCP server, the same app is now drivable. The four calls worth knowing, in the order you actually use them:
 
-- `reticle_snapshot`: what is on the page
-- `reticle_query { by: "testid", value: "..." }`: find one thing, cheaply
+- `reticle_look { action: "page" }`: what is on the page
+- `reticle_look { action: "find", by: "testid", value: "..." }`: find one thing, cheaply
 - `reticle_act_and_wait { ref, action, until }` (**the one that produces a verdict**)
 - `reticle_observe`: everything the page did, when you need the evidence
 

package/docs/flows.md

@@ -87,6 +87,35 @@ reticle_flow {action:"load"}({ flowName: "create-task" })   // → the flow JSON
 reticle_flow_replay({ flowName: "create-task" }) // re-resolve each anchor against the LIVE DOM, run it
 ```
 
+### Resume from a step
+
+```jsonc
+reticle_flow_replay({ flowName: "create-task", from: 3 })          // by 0-based index
+reticle_flow_replay({ flowName: "create-task", from: "submit" })   // or by a step's `id`
+```
+
+There is no state to restore, so the steps before `from` run again quickly as setup: their actions run, their `expect`s are not checked, and they are not reported. Replay is then checked and reported from `from` on. If a setup step fails, it is reported, because the resume never reached the step you asked for. A setup step declared `"effect": "commits"` refuses the resume and the whole flow replays, so resuming never re-sends a payment or a message silently. A `from` that names no step is an error, not a full replay.
+
+## Flows saved from a drive
+
+Every session's driving is saved as a flow at teardown when it declared a consequence. These flows:
+
+- are named from the `intent` you pass to `reticle_act_and_wait` (`drive-close-an-issue`), and carry it as the flow's `intent`;
+- merge: another drive that starts on the same page and takes the same steps updates the existing file instead of adding a copy. The existing flow keeps its name and everything it already says; the new drive only fills gaps. Flows you named yourself are never merged;
+- record, on every step, the `page` it ran on and the `endPage` it led to;
+- declare `requires` (the start page) and `ensures` (the end page) as route claims, so `canFollow` can tell which flows chain. Replay treats a required start page as met by navigating there;
+- carry `author: { agent, person }`: the MCP client that drove it and the email of whoever ran `reticle login` on that machine. Either is left out when it is not known.
+
+## Delete a flow
+
+```jsonc
+reticle_flow {action:"delete"}({ flowName: "create-task" })  // → { deleted: true }
+```
+
+A renamed or obsolete flow otherwise lingers in `reticle_flow {action:"list"}` and in every `reticle_verify {action:"flows"}` suite run, where it fails forever against a screen nobody intends to keep.
+
+**Deleting a flow that is not there is an error, not a no-op.** It answers `{ error, code: "not_found" }` rather than `{ deleted: true }`, so a mistyped name cannot read as a completed cleanup while the real flow stays in the suite. Check the spelling against `reticle_flow {action:"list"}` and try again.
+
 **Watch it replay on the page.** When the presenter is on (`present: true`), a replay isn't silent. Each step drives the real page, so the synthetic cursor flies to the element, the focus ring lands, and the activity log streams the journey live. You (or a teammate) literally watch the saved journey re-walk itself on your app, then see the verdict land. It's the fastest way to _see_ that a flow still works, not just read a green checkmark.
 
 `reticle_flow_replay` returns a status:
@@ -95,7 +124,7 @@ reticle_flow_replay({ flowName: "create-task" }) // re-resolve each anchor again
 - `drift`: an anchor missed (a testid was renamed, or a signal never fired). The result is **legible**, never a blind failure: `{ step, anchor, drift: { reasonKind: "testid_not_found", nearest: "send-message" } }`. (This is the "whose fault is it" principle.)
 - `error`: the flow file is missing/invalid, or a resolved action failed. Runtime failures include the failed step and a top-level error envelope.
 
-A testid-_preserving_ refactor (you moved markup but kept the testids) still replays green. A step whose element has **no testid** is anchored on its component + source location (`{ kind: "component", component, source: { file, line } }`), an auto-derived stable anchor, so a flow records cleanly with zero hand-added testids and replay re-resolves it via `reticle_query by:'component'`.
+A testid-_preserving_ refactor (you moved markup but kept the testids) still replays green. A step whose element has **no testid** is anchored on its component + source location (`{ kind: "component", component, source: { file, line } }`), an auto-derived stable anchor, so a flow records cleanly with zero hand-added testids and replay re-resolves it via `reticle_look { action: "find" } by:'component'`.
 
 ### The decision envelope: what to do next, not just pass/fail
 
@@ -164,7 +193,8 @@ With `apply: false` the flow file is **never modified**; you get the proposed di
 | `reticle_flow_save_recorded` | `{ flowName? }` | persist a human-recorded (toolbar) flow |
 | `reticle_flow {action:"list"}` | `{}` | flows on disk |
 | `reticle_flow {action:"load"}` | `{ flowName }` | the flow JSON |
-| `reticle_flow_replay` | `{ flowName }` | `{ status, steps, decision? }` (decision on drift/fail) |
+| `reticle_flow {action:"delete"}` | `{ flowName }` | `{ deleted: true }`, or `{ error, code }` (`not_found` when no such flow) |
+| `reticle_flow_replay` | `{ flowName, from?, sweep? }` | `{ status, steps, decision? }` (decision on drift/fail); `from` resumes at a step |
 | `reticle_verify {action:"flows"}` | `{ names?, sessionId? }` | suite verdict `{ status, passed, failed, failures[] }` |
 | `reticle_verify { action: "heal" }` | `{ flowName, apply? }` | propose / apply nearest-match rebind |
 | `reticle_annotate` | `{ kind, … }` | compile a structured annotation into the flow |