@reticlehq/server 3.3.0 → 3.5.0

package/docs/architecture.md

@@ -14,7 +14,7 @@ Reticle has three moving parts: a dev-only **SDK** inside your page that instrum
 
 Your app, in dev, embeds a tiny **SDK** that instruments the page (DOM, network, console, routing, framework state) and opens a WebSocket to a local **bridge**. The bridge runs inside the Reticle **server**, which also exposes an **MCP server**, the standard protocol AI agents speak.
 
-Your coding agent calls MCP tools (`reticle_query`, `reticle_act`, `reticle_assert`, …); the server turns them into commands over the WebSocket; the SDK executes them in the page and streams back structured events. The agent thus **looks, acts, observes, and asserts** on the real running app, never on a screenshot.
+Your coding agent calls MCP tools (`reticle_look { action: "find" }`, `reticle_act`, `reticle_assert`, …); the server turns them into commands over the WebSocket; the SDK executes them in the page and streams back structured events. The agent thus **looks, acts, observes, and asserts** on the real running app, never on a screenshot.
 
 ```mermaid
 flowchart LR
@@ -23,7 +23,7 @@ flowchart LR
     B["@reticlehq/browser<br/>SDK in your app<br/>(the DOM)"]
     D[(".reticle/<br/>flows · baselines<br/>runs · contract")]
 
-    A -- "MCP (stdio/SSE)<br/>reticle_query / act / assert" --> S
+    A -- "MCP (stdio/SSE)<br/>reticle_look / act / assert" --> S
     S -- "tool results" --> A
     S <-- "WebSocket<br/>commands / events" --> B
     S <--> D
@@ -37,7 +37,7 @@ Reticle is a pnpm + Turborepo monorepo. The split is not cosmetic: each boundary
 
 | Package | Runs in | Responsibility | Hard rule |
 | --- | --- | --- | --- |
-| `@reticlehq/core` | both | The **wire contract**: every constant + zod schema crossing any boundary | Depends only on `zod` |
+| `@reticlehq/core` | both | The **wire contract**: every constant + zod schema crossing any boundary | Depends only on `zod` and `open-verification` |
 | `@reticlehq/browser` | the browser | Instrument the page; execute commands; emit events | Never imports Node APIs |
 | `@reticlehq/server` | Node | The bridge, the MCP server, the `reticle` CLI, flow/run storage | Never imports DOM APIs |
 | `@reticlehq/react` | the browser | The SDK **kit** you install in a browser app: re-exports the browser sensor (so one install gives both `reticle` and `install`) and maps a DOM node → React component → source `file:line` | Core works without the source-mapping half |
@@ -59,8 +59,8 @@ The browser and server both import it; neither can invent a message the other do
 
 1. **Connect.** In dev, your app calls `reticle.connect({ session })`. The SDK opens a WebSocket to the bridge (`ws://localhost:4400/reticle` by default) and sends a `HELLO` carrying the session id, protocol version, and (if configured) a pairing token. Each browser tab uses `SESSION_AUTO` (a unique id), so multiple apps/tabs never collide.
 2. **Capture.** The SDK installs observers: a `MutationObserver` for DOM changes, wrappers around `fetch`/`XHR` for network, a console hook, a history hook for routing, and registries the app opts into (`registerStore`, `registerCapabilities`, `reticle.signal`). Events flow into a bounded **ring buffer**, so recent history is always available and memory is capped.
-3. **Look / act.** The agent calls an MCP tool. `reticle_query` finds an element by role/text/testid/ component and returns a stable **ref**. `reticle_act` dispatches an action against that ref and returns an **effect** report (did it land, did the DOM mutate, did focus move…). The server sends the command over the WebSocket; the SDK runs it and replies.
-4. **Observe.** After an action, the agent reads what happened with `reticle_network`, `reticle_console`, `reticle_state`, or the reaction digest from `reticle_act_and_wait`. The server pulls the relevant slice of the ring buffer (scoped to a cursor so stale events can't leak in) and returns a compact summary.
+3. **Look / act.** The agent calls an MCP tool. `reticle_look { action: "find" }` finds an element by role/text/testid/ component and returns a stable **ref**. `reticle_act` dispatches an action against that ref and returns an **effect** report (did it land, did the DOM mutate, did focus move…). The server sends the command over the WebSocket; the SDK runs it and replies.
+4. **Observe.** After an action, the agent reads what happened with `reticle_observe { action: "network" }`, `reticle_observe { action: "console" }`, `reticle_look { action: "state" }`, or the reaction digest from `reticle_act_and_wait`. The server pulls the relevant slice of the ring buffer (scoped to a cursor so stale events can't leak in) and returns a compact summary.
 5. **Assert.** `reticle_assert` (and a flow's declared `success`) evaluates a **predicate** over program truth (a network call that returned 200, a store value, a `signal` the app emitted), not just "an element exists." This is the difference between "looks done" and "is done."
 
 ---
@@ -87,7 +87,7 @@ The same verification runs over and over, every commit, every CI run. Reticle re
 
 ### 4. Dev-only, localhost-only, your app data stays local
 
-The SDK is tree-shaken out of production builds and connects only to a local bridge. The bridge binds to loopback by default; exposing it beyond localhost _requires_ a pairing token (the server refuses to bind a non-loopback host without one). Every environment variable that gates a security control is a single named constant, so a typo can't silently disable auth. Nothing from the app under test ever leaves your machine: no DOM, network, console, state, or source. The CLI reports anonymous, opt-out usage metrics only (a random id + event names like `invoke`/`session_start`; no code, no PII; see [telemetry](telemetry.md)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. The one thing that carries free text is feedback you or your agent deliberately send (`reticle feedback` / `reticle_feedback`). It is never collected passively, it is redacted before sending, and it is disabled separately with `RETICLE_FEEDBACK=0`.
+The SDK is tree-shaken out of production builds and connects only to a local bridge. The bridge binds to loopback by default; exposing it beyond localhost _requires_ a pairing token (the server refuses to bind a non-loopback host without one). Every environment variable that gates a security control is a single named constant, so a typo can't silently disable auth. Nothing from the app under test ever leaves your machine: no DOM, network, console, state, or source. The CLI reports anonymous, opt-out usage metrics only (a random id + event names like `invoke`/`session_start`; no code, no PII; see [telemetry](telemetry.md)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. The one thing that carries free text is feedback you or your agent deliberately send (`reticle feedback` / `reticle_session { action: "feedback" }`). It is never collected passively, it is redacted before sending, and it is disabled separately with `RETICLE_FEEDBACK=0`.
 
 ---
 

package/docs/best-practices.mdx

@@ -196,7 +196,7 @@ Sessions accumulate. Four stale ones pointing at dev servers you restarted an ho
 
 ## Confirm a navigation landed
 
-`reticle_navigate` returns `confirmed: false` by design. A navigation destroys the document the SDK lives in, so it can only report dispatch. Check [`reticle_sessions`](/tools/sessions) for a session at the new URL before acting, and re-snapshot: refs do not survive a new document.
+`reticle_navigate` returns `confirmed: false` by design. A navigation destroys the document the SDK lives in, so it can only report dispatch. Check [`reticle_session { action: "list" }`](/tools/sessions) for a session at the new URL before acting, and re-snapshot: refs do not survive a new document.
 
 ## Start with what the app says about itself
 

package/docs/capabilities.mdx

@@ -55,7 +55,7 @@ Useful at the end of a drive, when the agent is about to report success. "I veri
 }
 ```
 
-Note the token redaction. Credential-shaped values are stripped here exactly as they are in [`reticle_network`](/tools/network), so reading storage never puts a session token in your context.
+Note the token redaction. Credential-shaped values are stripped here exactly as they are in [`reticle_observe { action: "network" }`](/tools/network), so reading storage never puts a session token in your context.
 
 localStorage, sessionStorage and readable cookies.
 
@@ -87,6 +87,24 @@ Toasts that auto-dismiss, debounced search, polling, session timeouts, retry bac
 
 Freeze the clock, advance it by exactly the interval, assert the consequence. No sleeping, no guessing, and the same result on a fast laptop and a loaded CI runner.
 
+<Warning>
+Freeze the clock **before** the action that schedules the timer. Reticle replaces the page's
+`setTimeout` and `setInterval` when the clock is frozen, so timers that already exist keep running
+on the browser's real clock and are not fired by `advanceMs`.
+
+If a timer is created during page mount, freeze the clock first and then reload the page so the mount-time timer is created under the fake clock.
+
+</Warning>
+
+The clock virtualizes `Date.now()`, but not every time API. `new Date()` and `performance.now()` continue to use real time. `performance.now()` is intentionally left real because React's scheduler depends on it.
+
+The reliable pattern is:
+
+1. Freeze the clock.
+2. Perform the action that schedules the timer, or reload the page if the timer is created during mount.
+3. Advance by the required interval.
+4. Assert the consequence.
+
 ### Crawl: click everything, report anomalies
 
 ```json
@@ -123,6 +141,19 @@ This is the tool for an app you did not write and do not understand yet.
   25.
 </Warning>
 
+Controls Reticle judges destructive are blocked unless you pass `confirmDangerous: true`. That covers the controls on the page the crawl started on. A control one of its clicks revealed, such as the "Yes, delete" behind a "Delete", stays blocked, so one crawl cannot finish a deletion you did not look at.
+
+### Covering everything: `exhaustive`
+
+`{ "action": "crawl", "exhaustive": true }` goes past one page. It walks every state reachable from where you start, reaching each one by replaying the path that found it from a fresh load, so it never depends on "back" working. It fills text fields before it tries a form's buttons (from `RETICLE_SECRET_<FIELD>` when set, so it gets past a login, and only on the origin the crawl started on), and treats controls that differ only by a number, like table rows, as one. A control with the same name on a different screen is tried again there. Every write it finds is then driven again with the request failing. A write counts as **branched** only when the request was actually sent and broken. With the write failing, the app must not end up where it goes when the write succeeds; if it does, you get `failure-unhandled`. That part needs a browser Reticle drives (`reticle drive`).
+
+The run folds into the app-wide coverage ledger, which `reticle_verify { action: "coverage", app: true }` also reports. It has six levels, each with what is missing: routes **reached**, controls **touched**, controls **proved** (an `act_and_wait` came back `yes`), journeys **completed**, writes **branched** (failure path driven), and app functions **executed** (V8 coverage, driven browser only, collected from the first coverage request or exhaustive crawl onward, so an ordinary drive pays nothing for it). `frontier` is the number of states found and not yet explored. Zero means every state the explorer could tell apart was explored, not that every reachable state was: a state is its route plus the names of its controls, so two screens that differ only in field values, in how many of a control they show, or in what the same controls do count as one, and the second is never visited. `reticle gate` blocks when a level falls below the best it has reached, and when a changed file never ran. A changed file whose coverage was taken before the edit is reported as `coverageStale` instead, because its counts describe the old code. When a drop was intended, `reticle gate --accept-coverage` records today's levels as the new best.
+
+<Warning>
+  Exhaustive really does click everything, repeatedly, and submits forms. `maxSteps` bounds it,
+  defaulting to 400 actions.
+</Warning>
+
 ### Reconcile: what the API said versus what rendered
 
 ```json

package/docs/cli/cloud.mdx

@@ -1,16 +1,18 @@
 ---
 title: reticle cloud commands
-description: Sign in, link a repository, and read runs and regressions from Reticle Cloud.
+description: Connect a project in one command, then read runs and regressions from Reticle Cloud.
 icon: cloud
 ---
 
-Ten subcommands bind this repository to Reticle Cloud so runs and flows land on a dashboard. They dispatch before the local parser, so `reticle login` is one tool, not a second binary.
+From your app directory, `reticle connect --project "My App"` wires the app, opens browser sign-in approval if needed, links the named cloud project, and syncs the local history already on this machine. Run the [installer](/quickstart) once on the machine first. The commands below remain available when you need to sign in or link separately.
 
 ```bash
-npx @reticlehq/server <login|logout|whoami|link|project|config|push|runs|regression|share>
+npx @reticlehq/server connect --project "My App"
 ```
 
-These are thin clients over the `/v1` API. The logic is server-side; these verbs surface it.
+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. 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 whoami` to check the binding and `reticle push` to send anything still pending.
+
+The other cloud commands are thin clients over the `/v1` API. Their logic is server-side.
 
 ## Where credentials live
 
@@ -20,7 +22,13 @@ These are thin clients over the `/v1` API. The logic is server-side; these verbs
 | `~/.reticle/credentials.json` | Project-scoped API keys from `reticle link`, keyed by `projectId` | Yes |
 | `<repo>/.reticle/cloud.json` | `{ projectId, projectName, url, sync, verify }`. The non-secret binding | No, commit it |
 
-Auth for any command is `RETICLE_API_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`. When a command falls back to that default without `RETICLE_CLOUD_URL` (or a saved session URL), it prints a one-line notice on stderr; stdout stays pure JSON for agents.
+Auth for any command is `RETICLE_API_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` (or its short form `RETICLE_URL`) overrides the endpoint; without it, a command uses the saved session's host, and otherwise the hosted service, `https://app.reticle.sh`.
+
+## In CI
+
+CI needs `RETICLE_API_KEY` and nothing else: no `login`, no `link`. Commit `.reticle/cloud.json`, store the key as a secret, and the daemon and `reticle push` sync to the project the binding names. A key stored in `credentials.json` wins over the environment when both exist.
+
+The environment key is only sent to the host it belongs to: `RETICLE_CLOUD_URL` when set, otherwise the hosted service. A repo linked to a self-hosted install therefore also needs `RETICLE_CLOUD_URL` set to that install in CI. A repo with no `cloud.json` and a key in the environment syncs to the hosted service, or to `RETICLE_CLOUD_URL`.
 
 ## The commands
 
@@ -101,9 +109,13 @@ reticle: no .reticle/cloud.json here ... run `reticle link` first
 
 ### `reticle push`
 
-Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy. With `sync.runs` off it does nothing and says so. Prints `{ ok, project, sent, pulled }`, where `sent` carries the accepted counts and, when the server refused anything, a `rejected` array naming each artifact's index and reason.
+Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy. With `sync.runs` off it does nothing and says so. 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.
+
+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 push.** If the server refuses any artifact, `ok` is `false` and the command exits `1`, even when other artifacts in the same bundle landed. 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 push is visible as one.
+**A rejection is a failed push.** 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 `sync.lastError` in `reticle whoami`, 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 push is visible as one.
 
 ### `reticle runs`
 
@@ -130,7 +142,7 @@ reticle: usage: reticle share <runId>
 `push`, `runs` and `regression` all need a project to talk to. Without one they exit `1` with the same line on stderr, measured:
 
 ```
-reticle: cloud not attached here ... run `reticle link` (or set RETICLE_CLOUD_URL/KEY)
+reticle: cloud not attached here ... run `reticle link` (or set RETICLE_API_KEY)
 ```
 
 ## Exit codes

package/docs/cli/doctor.mdx

@@ -72,6 +72,10 @@ All three captures below are real, taken by pointing `PLAYWRIGHT_BROWSERS_PATH`
   chromium     ✓ installed (chromium-1234)
 ```
 
+**`✓ using the installed Google Chrome`** (or Microsoft Edge) means the pinned build is absent and Reticle drives the browser you already have instead, through Playwright's channel. Nothing to do: the line also names the command that adds Playwright's own build, if you want it.
+
+When neither is there, Reticle does not refuse. The first command that needs a browser (a lease, `verify`, a drive) runs the bundled Playwright's own pinned install for you, announced on stderr so `reticle mcp`'s stdout stays clean. The two `✗` lines below are what you see when that has not happened yet, or failed.
+
 **`✗ wrong revision`** means builds are installed and none of them is the wanted one. One pinned download away. The line names the revision Playwright wants, then every revision the root actually holds, then the exact command:
 
 ```

package/docs/cli/feedback.mdx

@@ -11,7 +11,7 @@ npx @reticlehq/server feedback [--rating 1-5] [--bug] "what worked, what didn't"
 npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"
 ```
 
-The `--agent` form is for an agent that cannot reach the `reticle_feedback` tool: during `init`, while instrumentation is half wired, or when the daemon will not start. Those are the reports that are hardest to hear and most needed, because every other path requires the tool surface to already work.
+The `--agent` form is for an agent that cannot reach the `reticle_session { action: "feedback" }` tool: during `init`, while instrumentation is half wired, or when the daemon will not start. Those are the reports that are hardest to hear and most needed, because every other path requires the tool surface to already work.
 
 ## Flags
 
@@ -63,5 +63,5 @@ npx @reticlehq/server feedback --agent --kind gap \
   icon="comments"
   href="/tools/session-and-feedback"
 >
-  `reticle_feedback` when the tools are reachable.
+  `reticle_session { action: "feedback" }` when the tools are reachable.
 </Card>

package/docs/cli/gate.mdx

@@ -7,7 +7,7 @@ icon: shield-halved
 `reticle gate` is what makes verification unavoidable. It computes the [affected](/cli/affected) flows, looks for a passing artifact for each, and fails the command if any is missing. An agent that edits a covered file cannot call itself finished without re-verifying.
 
 ```bash
-npx @reticlehq/server gate [--since <ref>] [file...]
+npx @reticlehq/server gate [--since <ref>] [--accept-coverage] [file...]
 ```
 
 ## Arguments and flags
@@ -16,6 +16,7 @@ npx @reticlehq/server gate [--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 |
+| `--accept-coverage` | boolean | off | Accept today's coverage levels as the new best before judging. Use it when a drop was intended, such as a control you removed on purpose. The run reports what it accepted as `coverageAccepted` |
 
 ## What blocks and what does not
 
@@ -24,6 +25,10 @@ npx @reticlehq/server gate [--since <ref>] [file...]
 | `uncovered` | Yes | An affected flow with no passing artifact |
 | `downgraded` | Yes | A flow whose assertions were weakened since its last passing run. A green bought by weakening the test is the gaming move this exists to stop |
 | `deletedCoverage` | Yes | A flow that covered a changed file and has since vanished. Coverage deleted, not satisfied |
+| `unflowed` | Yes | A changed interactive component that no saved flow drives. Only once the project has saved flows, so a first day never blocks |
+| `coverageRegressed` | Yes | A [coverage](/capabilities) level fell below the best it has reached: something new appeared that nothing covers. Cover it, or accept the drop with `--accept-coverage` |
+| `unexecuted` | Yes | A changed file the browser loaded during a drive and never ran a function of |
+| `coverageStale` | No | A changed file whose code coverage was taken before its last edit. Its counts describe the old code, so `unexecuted` cannot judge it either way. Take coverage again after driving the change to measure it |
 | `quarantined` | No | Flows the flake ledger has quarantined. Surfaced, never blocking, because one unexplained flake that blocks a merge destroys trust in the red |
 
 ## What it prints
@@ -41,14 +46,14 @@ One `reticle_gate` line. Real capture from this repository, with the flow lists
 }
 ```
 
-`downgraded` and `deletedCoverage` appear only when they are non-empty, and neither was present in that run. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
+`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.
 
 ## Exit codes
 
 | Code | Meaning |
 | --- | --- |
-| `0` | Every affected, non-flaky flow has a passing artifact and nothing was weakened or deleted |
-| `1` | Something is uncovered, downgraded or deleted. Also `1` on any internal fault: the gate fails closed |
+| `0` | Every affected, non-flaky flow has a passing artifact, nothing was weakened or deleted, and coverage held |
+| `1` | Something is uncovered, downgraded, deleted, unflowed, unexecuted, or coverage fell. Also `1` on any internal fault: the gate fails closed |
 
 Measured on this repository, `npx @reticlehq/server gate --since HEAD~1` exited `1` with the output above: 0 of 47 flows covered, 39 uncovered and 8 quarantined.
 

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

@@ -13,13 +13,9 @@ npx @reticlehq/server <command>
 ```
 
 <Warning>
-  **Always invoke it as `npx @reticlehq/server <command>`.** The tables below name the commands as
-  `reticle <command>`, because `reticle` is the bin this package installs and that is what the CLI
-  prints about itself. It is **not** a package on npm: the bare name `reticle` belongs to an
-  unrelated author, so putting `npx` in front of it downloads and runs their code instead of ours.
-  Once
-  `@reticlehq/server` is a dependency of your project, `reticle <command>` works from an npm script
-  or with the bin on your PATH.
+  If you used the installer, run `reticle <command>`: it put that bin on your PATH. Otherwise use
+  `npx @reticlehq/server <command>`. Do not put `npx` before the bare `reticle` bin name: the npm
+  package with that name belongs to an unrelated author.
 </Warning>
 
 <Note>
@@ -30,6 +26,16 @@ npx @reticlehq/server <command>
 
 ## Setup and diagnosis
 
+### `reticle connect`
+
+From an app directory, one command wires an unwired app, proves a browser session, signs in through browser approval if needed, links the chosen cloud project, and syncs existing local history. A saved sign-in is reused only after the intended cloud host accepts it. Run `reticle init` instead for local-only verification.
+
+```bash
+npx @reticlehq/server connect --project "My App"
+```
+
+For a self-hosted cloud, add `--url <cloud origin>`. If the app was already wired, `connect` keeps its local setup and refreshes the cloud link. A fresh app has no run to send until you verify a flow with your agent.
+
 ### `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>"`.
@@ -112,6 +118,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.3"
+reticle-tauri = "3.5"
 ```
 
 ```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>