@reticlehq/server 3.6.0 → 3.7.0

package/docs/flows.md

@@ -41,18 +41,18 @@ Then persist it to disk so it's committed and any agent can read it:
 
 | Tool | What it does |
 | --- | --- |
-| `reticle_capabilities()` | the live testable surface `{ testids, signals, stores, flows }` |
-| `reticle_contract_save()` | write the live capabilities to `.reticle/contract.json` (versioned, diffable) |
+| `reticle_run({ tool: "reticle_capabilities", args: {} })` | the live testable surface `{ testids, signals, stores, flows }` |
+| `reticle_run({ tool: "reticle_contract_save", args: {} })` | write the live capabilities to `.reticle/contract.json` (versioned, diffable) |
 
 ## Create a flow
 
 **(a) Agent-recorded.** The agent drives, then saves:
 
 ```jsonc
-reticle_record {action:"start"}({ recordingName: "create-task" })
+reticle_run({ tool: "reticle_record", args: { action: "start", recordingName: "create-task" } })
 reticle_act({ ref: "e7", action: "click" })        // … drive the golden path …
-reticle_record {action:"stop"}({ recordingName: "create-task" })
-reticle_flow_save({ flowName: "create-task" })          // → .reticle/flows/create-task.json
+reticle_run({ tool: "reticle_record", args: { action: "stop", recordingName: "create-task" } })
+reticle_run({ tool: "reticle_flow_save", args: { flowName: "create-task" } })          // → .reticle/flows/create-task.json
 ```
 
 **(b) Human-recorded (the recorder toolbar).** With the presenter on (`present: true`), the floating panel hosts a recorder: a human clicks the golden path in the page and Reticle captures each interaction as a **semantic-anchored** step (testid, else role+name), then persists it via `reticle_flow_save_recorded`. The agent then runs and maintains it. _(First cut: structured annotations only, see below; free natural-language annotations are future work.)_
@@ -61,19 +61,24 @@ reticle_flow_save({ flowName: "create-task" })          // → .reticle/flows/cr
 
 ```jsonc
 {
-  "version": 1,
+  "version": 2,
   "name": "create-task",
+  "createdAt": 1760000000000,
   "steps": [
-    { "tool": "reticle_act", "anchor": { "testid": "add-task" }, "action": "click" },
     {
       "tool": "reticle_act",
-      "anchor": { "testid": "add-task" },
+      "anchor": { "kind": "testid", "value": "task-input" },
       "action": "click",
-      "expect": { "signal": "task:added" },
+    },
+    {
+      "tool": "reticle_act",
+      "anchor": { "kind": "testid", "value": "add-task" },
+      "action": "click",
+      "expect": { "kind": "signal", "name": "task:added" },
     },
   ],
   "dynamic": [], // anchors whose CONTENT must not be asserted (LLM output)
-  "success": { "signal": "saved" },
+  "success": { "kind": "signal", "name": "saved" },
 }
 ```
 
@@ -82,16 +87,16 @@ Each step binds to a **semantic anchor**, never a `eXX` ref: a `testid`/`signal`
 ## Run a flow
 
 ```jsonc
-reticle_flow {action:"list"}()                                    // → flows on disk
-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
+reticle_run({ tool: "reticle_flow", args: { action: "list" } })                                    // → flows on disk
+reticle_run({ tool: "reticle_flow", args: { action: "load", flowName: "create-task" } })   // → the flow JSON
+reticle_run({ tool: "reticle_flow_replay", args: { 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`
+reticle_run({ tool: "reticle_flow_replay", args: { flowName: "create-task", from: 3 } })          // by 0-based index
+reticle_run({ tool: "reticle_flow_replay", args: { 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.
@@ -104,17 +109,17 @@ Every session's driving is saved as a flow at teardown when it declared a conseq
 - 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.
+- carry `author: { agent, person }`: the MCP client that drove it and the email of whoever signed in with `reticle connect` 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 }
+reticle_run({ tool: "reticle_flow", args: { 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.
+A renamed or obsolete flow otherwise lingers in `reticle_run { tool: "reticle_flow", args: { 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.
+**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_run { tool: "reticle_flow", args: { 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.
 
@@ -123,6 +128,7 @@ A renamed or obsolete flow otherwise lingers in `reticle_flow {action:"list"}` a
 - `ok`: every anchor resolved and every `expect` held.
 - `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.
+- `unverifiable`: the flow could not be graded (missing secrets, an unmet precondition, a lost document). Neither a pass nor a fail: treat it as unknown.
 
 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'`.
 
@@ -144,7 +150,7 @@ This is the feedback a human reviewer used to give, made machine-actionable, so
 
 ## Verify the whole suite in one call
 
-`reticle_verify {action:"flows"}` replays **every** saved flow (or a named subset) deterministically, with no LLM per flow, and returns one consolidated verdict. This is the regression check to run after any change:
+`reticle_verify { action: "flows" }` replays **every** saved flow (or a named subset) deterministically, with no LLM per flow, and returns one consolidated verdict. This is the regression check to run after any change:
 
 ```jsonc
 reticle_verify({ action: "flows" })
@@ -154,7 +160,7 @@ reticle_verify({ action: "flows" })
 //                  whatChanged: "...", whereInSource: "src/...:NN", nextAction: "..." }] }
 ```
 
-Passing flows are counted; only failures carry detail (token-cheap). Build → `reticle_verify {action:"flows"}` → fix from each failure's `nextAction` → repeat: the autonomous regression loop.
+Passing flows are counted; only failures carry detail (token-cheap). Build → `reticle_verify { action: "flows" }` → fix from each failure's `nextAction` → repeat: the autonomous regression loop.
 
 ## Self-healing: the agent maintains the flow
 
@@ -185,17 +191,19 @@ With `apply: false` the flow file is **never modified**; you get the proposed di
 
 ## Tool reference
 
+Of the tools on this page, only `reticle_verify` is advertised by default. Call every other tool here as `reticle_run({ tool: "<name>", args: { … } })`, with the args shown.
+
 | Tool | Args | Returns |
 | --- | --- | --- |
 | `reticle_contract_save` | `{ sessionId? }` | writes `.reticle/contract.json` |
-| `reticle_record {action:"start"}` / `reticle_record {action:"stop"}` | `{ recordingName }` | start/stop capturing the agent's acts |
+| `reticle_run { tool: "reticle_record", args: { action: "start" } }` / `reticle_run { tool: "reticle_record", args: { action: "stop" } }` | `{ recordingName }` | start/stop capturing the agent's acts |
 | `reticle_flow_save` | `{ flowName }` | persist the recording → `.reticle/flows/<flowName>.json` |
 | `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 {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_run { tool: "reticle_flow", args: { action: "list" } }` | `{}` | flows on disk |
+| `reticle_run { tool: "reticle_flow", args: { action: "load" } }` | `{ flowName }` | the flow JSON |
+| `reticle_run { tool: "reticle_flow", args: { action: "delete" } }` | `{ flowName }` | `{ deleted: true }`, or `{ error, code }` (`not_found` when no such flow) |
+| `reticle_flow_replay` | `{ flowName, from?, sweep? }` | `{ name, 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 |
 

package/docs/for-agents.md

@@ -29,15 +29,14 @@ Every Markdown page is prepended with two things before its content, so a single
 
 > ## Agent Instructions
 > Reticle is a dev-only, localhost-only verification layer for AI coding agents...
-> Only `reticle_act_and_wait` and `reticle_assert` produce a verdict...
-> A verdict of `verified: "unknown"` is not a pass...
-> Package names are scoped `@reticlehq/*` and the CLI is `reticle`...
+> Verdicts come from `reticle_act_and_wait`, `reticle_assert`, `reticle_act { steps }` when a step declares `expect`, and `reticle_verify`...
+> Package names are scoped `@reticlehq/*`. Run every CLI command as `npx @reticlehq/server <command>`...
 
 # reticle_query
 ...
 ```
 
-The four rules are the ones worth knowing before you drive anything, and they arrive whether or not you asked for them. You do not have to read this page first.
+These instructions are the ones worth knowing before you drive anything, and they arrive whether or not you asked for them. You do not have to read this page first.
 
 The slug is the filename in [`docs/`](https://github.com/reticlehq/reticle/tree/main/docs), so `docs/token-efficiency.md` in the repo is `/token-efficiency` on the site and `/token-efficiency.md` as raw text.
 
@@ -54,7 +53,7 @@ Start with `llms.txt`. It is small enough to read in full and tells you which si
 
 Every page has a menu in its top-right corner: copy the page as Markdown, or open it directly in Claude, ChatGPT, Cursor or VS Code with the source already attached. That is the fastest route when a human is driving and wants the agent to have the page.
 
-> None of this is Reticle itself. These endpoints serve the **documentation**. Reticle runs on your machine and verifies your app; you get it with `npx @reticlehq/server init`. See [Getting started](/getting-started).
+> None of this is Reticle itself. These endpoints serve the **documentation**. Reticle runs on your machine and verifies your app; you install it with the installer script (`curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh`), which prints the next steps. See [Getting started](/getting-started).
 
 ## Which page to read
 

package/docs/frameworks.mdx

@@ -5,7 +5,7 @@ description: Which frameworks Reticle supports, which are wired but unverified,
 icon: layer-group
 ---
 
-**React + Vite, Next.js, Remix and Astro are fully supported, each with an example app driven to a verdict in CI. Astro, SvelteKit, Nuxt, React Router framework mode, Create React App, Vue and Angular have their INSTALL gated: the install gate scaffolds each from scratch on every change and requires a real session, but no gate drives them to a verdict. TanStack Start, Preact and plain HTML are wired by `init` and documented but not gated at all, so treat them as plausible rather than proven.** The exact wiring for each is below.
+**React + Vite, Next.js, Remix and Astro are fully supported, each with an example app in CI: React + Vite and Next.js are driven to a verdict by the e2e battery, and the Remix and Astro examples are booted and must register a session. SvelteKit, Nuxt, React Router framework mode, Create React App, Vue and Angular have their INSTALL gated: the install gate scaffolds each from scratch whenever the install path changes and requires a real session, but no gate drives them to a verdict. TanStack Start, Preact and plain HTML are wired by `init` and documented but not gated at all, so treat them as plausible rather than proven.** The exact wiring for each is below.
 
 Reticle is a verification layer that embeds a dev-only SDK in your running web app so an AI coding agent can prove a change works. Its core is framework-neutral: DOM, network, console, routing, animations and source mapping work anywhere JavaScript runs.
 
@@ -17,7 +17,7 @@ What varies is two things: how `connect()` gets into your app, and whether you g
 
 We separate "we tested this" from "this should work". Four frameworks have an example app and a CI gate. The rest are wired and documented but nothing proves they still work.
 
-Two columns say different things and it is worth keeping them apart. **CI gate** `yes` means an example app is driven to a verdict on every change. **install only** means the install gate scaffolds that stack from scratch, runs `init`, boots it and waits for a session, so the setup is proven and the drive is not. Vue is there because a release once nearly shipped an installer that left a Vue app connecting 0% of the time, and the gate that exists for exactly that had only React scaffolds.
+Two columns say different things and it is worth keeping them apart. **CI gate** `yes` means an example app runs in CI: React + Vite and Next.js are driven to a verdict, Remix and Astro are booted and must register a session. **install only** means the install gate scaffolds that stack from scratch, runs `init`, boots it and waits for a session, so the setup is proven and the drive is not. Vue is there because a release once nearly shipped an installer that left a Vue app connecting 0% of the time, and the gate that exists for exactly that had only React scaffolds.
 
 **Source pointer** is the `file:line` on a verdict. It needs the build plugin to stamp the source, which it does for JSX and, separately, for Svelte components. Vue single-file components are neither, so a Vue app gets every other signal and no `source` field. Measured, not assumed: a Svelte counter returns `src/lib/Counter.svelte:5` and the same drive on Vue returns none.
 
@@ -29,7 +29,7 @@ Two columns say different things and it is worth keeping them apart. **CI gate**
 | **Astro** | yes | yes | yes | yes | Supported |
 | **SvelteKit** | yes | no | install only | unproven | Install gated, drive unverified |
 | **TanStack Start** | yes | no | no | unproven | Wired, unverified |
-| **Nuxt** | yes | no | install only | unproven | Install gated, drive unverified |
+| **Nuxt** | yes | no | install only | no | Install gated, drive unverified |
 | **React Router (framework mode)** | yes | no | install only | yes | Install gated, drive unverified |
 | **Create React App** | yes | no | install only | unproven | Install gated, drive unverified |
 | **Angular 17+** | yes | no | install only | no | Install gated, drive unverified |
@@ -128,10 +128,14 @@ The `<script>` tag must not sit inside a conditional. Astro hoists them statical
 SvelteKit renders through `app.html` and never triggers Vite's `index.html` injection, so the plugin cannot auto-connect. A client hook is the reliable path, and it is what `init` writes.
 
 ```ts
-// src/hooks.client.ts
-import { reticle } from '@reticlehq/browser';
-
-if (import.meta.env.DEV) reticle.connect();
+// src/hooks.client.ts (abridged)
+if (import.meta.env.DEV) {
+  void import('@reticlehq/browser').then(({ reticle }) => {
+    // Inlined by @reticlehq/vite-plugin. The bridge refuses a connect with no token, even on localhost.
+    const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+    reticle.connect({ ...(token.length > 0 ? { token } : {}) });
+  });
+}
 ```
 
 The Vite plugin still stamps `data-reticle-source` into `.svelte` components, so verdicts carry `file:line`.
@@ -163,11 +167,17 @@ useEffect(() => {
 Nuxt owns its own Vite instance and renders its own HTML. There is no `vite.config` to patch and no `index.html` to inject into, so `reticle init` writes a dev-only client plugin and adds a `vite.define` block to `nuxt.config`. That block is the only place a Nuxt app can inline the pairing token, which the bridge requires even on localhost. What it writes is this, and the notes below are why each line is the way it is.
 
 ```ts
-// app/plugins/reticle.client.ts (Nuxt 3: plugins/reticle.client.ts)
+// app/plugins/reticle.client.ts (Nuxt 3: plugins/reticle.client.ts), abridged
 export default defineNuxtPlugin(() => {
   if (!import.meta.dev) return;
   void import('@reticlehq/browser').then(({ reticle }) => {
-    reticle.connect();
+    // Both inlined by the vite.define block init adds to nuxt.config.
+    const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+    const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+    reticle.connect({
+      ...(token.length > 0 ? { token } : {}),
+      ...(root.length > 0 ? { root } : {}),
+    });
   });
 });
 ```
@@ -190,7 +200,7 @@ Three traps, all reported from the field rather than imagined:
   </Accordion>
 </AccordionGroup>
 
-Use `@reticlehq/browser`, the framework-neutral sensor. You get DOM, network, console, routing and source `file:line`. What you do not get is React component identity, which is the only thing the React adapter adds.
+Use `@reticlehq/browser`, the framework-neutral sensor. You get DOM, network, console and routing. You do not get React component identity (the React adapter adds that) or a `source` field: Vue single-file components are not stamped.
 
 <Tip>
   Developing on something other than `localhost`? Add `allowNonLocalhost: true` to the connect call.
@@ -199,16 +209,13 @@ Use `@reticlehq/browser`, the framework-neutral sensor. You get DOM, network, co
 
 ## Vue
 
-Vue apps outside Nuxt are Vite apps, so `init` finds them. Install the sensor rather than the React kit.
+Vue apps outside Nuxt are Vite apps, so `init` finds them. It installs the sensor rather than the React kit, plus the Vite plugin:
 
 ```bash
-npm i -D @reticlehq/browser
+npm i -D @reticlehq/browser @reticlehq/vite-plugin
 ```
 
-```ts
-import { reticle } from '@reticlehq/browser';
-if (import.meta.env.DEV) reticle.connect();
-```
+Add `reticle()` to the `plugins` of your Vite config, as in the React example above. The plugin injects `connect()` with the pairing token, so there is no connect line to write.
 
 Pinia is a first-class store. See [State management](/state-management).
 
@@ -229,10 +236,13 @@ No config file to patch, so `connect()` goes in your entry module.
 ```ts
 // src/index.tsx
 import { reticle } from '@reticlehq/browser';
-if (process.env.NODE_ENV !== 'production') reticle.connect();
+if (process.env.NODE_ENV !== 'production') {
+  // The bridge refuses a connect with no pairing token, even on localhost.
+  reticle.connect({ token: '<pairing token>' });
+}
 ```
 
-The same shape works for webpack, Parcel, and the Vue and Svelte CLIs.
+The token is the contents of `~/.reticle/pairing-token`; do not commit it. On Create React App, `init` writes this for you: a dev-only connect module that reads the token from `REACT_APP_RETICLE_TOKEN`, which it puts in the gitignored `.env.development.local`. The same shape works for webpack, Parcel, and the Vue and Svelte CLIs.
 
 ## Plain HTML
 
@@ -257,7 +267,7 @@ Angular 17 and later, on the Vite-based `@angular/build` dev server. `init` inst
 
 The token takes that route because the Angular CLI has no config file that runs code: a literal in `angular.json` commits a per-machine secret, and a gitignored module imported from `main.ts` is bundled into `ng build` whether or not anything can reach it. An existing `proxyConfig` is yours and is never replaced: the step goes manual and names the entry to add to it. A workspace with several served applications is also manual, because which one is the app is not `init`'s to guess.
 
-You get DOM, network, console, routing and state tools. You do not get component identity (that is the React adapter) or a `source` field (the stamper covers JSX and Svelte). The install gate scaffolds an Angular app (no SSR) on every change and requires a session; SSR was proven by hand, and nothing drives an Angular app to a verdict.
+You get DOM, network, console, routing and state tools. You do not get component identity (that is the React adapter) or a `source` field (the stamper covers JSX and Svelte). The install gate scaffolds an Angular app (no SSR) whenever the install path changes and requires a session; SSR was proven by hand, and nothing drives an Angular app to a verdict.
 
 ## Server-rendered apps (Django, Flask, FastAPI, Rails)
 
@@ -367,8 +377,9 @@ Solid appears in dependency detection but has no wiring, no adapter and no gate.
 
 <Accordion title="Which framework should I pick if I want the strongest verdicts?">
   React on Vite. It is the shortest install, and it is the only combination that gives you all three
-  of component identity, `file:line` source pointers and a CI-gated example app. If you are already
-  on Next.js, Remix or Astro, you get the same guarantees.
+  of component identity, `file:line` source pointers and an example app driven to a verdict in CI.
+  Next.js gives you the same. On Remix or Astro you get the same identity and source pointers, but
+  their example apps are only checked for a session in CI, not driven to a verdict.
 </Accordion>
 
 <Accordion title="My framework is not listed at all. Will it work?">

package/docs/getting-started.md

@@ -4,7 +4,7 @@ description: 'Zero to your agent verifying your real app, step by step, with wor
 icon: rocket
 ---
 
-**To get started: run the installer, then `reticle init` in your app directory before opening your coding agent.** The installer puts the CLI on the machine and registers its MCP tools with supported agents. `init` wires your app and checks that a browser session connected; without it the agent has the tools and nothing to point them at. For a cloud dashboard, use `reticle connect --project "My App"`, which does the same and also links a cloud project and syncs history. The first run is what proves anything: ask your agent to verify one journey in your app, or use `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`. A connected app is not a verified one. You need Node 20.11 or newer, an app you run locally, and an agent that speaks MCP.
+**To get started: run the installer, then `reticle init` in your app directory before opening your coding agent.** The installer puts the CLI on the machine and registers its MCP tools with supported agents. `init` wires your app and checks that a browser session connected; without it the agent has the tools and nothing to point them at. For a cloud dashboard, use `reticle connect --project "My App"`, which does the same and also links a cloud project and syncs history. The first run is what proves anything: ask your agent to verify one journey in your app, or, on a project linked with `reticle connect`, use `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`. A connected app is not a verified one. You need Node 20.11 or newer, an app you run locally, and an agent that speaks MCP.
 
 > **Looking for the fast path?** [Quickstart](/quickstart) gets you to a real verdict in five minutes, and every response on it was captured live. [Agentic install](/install-agentic) and [Manual install](/install-manual) cover setup in detail, per agent and per framework.
 >
@@ -14,7 +14,9 @@ This walks you from zero to your agent verifying your app, step by step, with re
 
 - [What you're setting up](#what-youre-setting-up)
 - [Prerequisites](#prerequisites)
-- [Step 1: Connect your coding agent (MCP)](#step-1-connect-your-coding-agent-mcp)
+- [Step 1: Connect your coding agent (MCP), once](#step-1-connect-your-coding-agent-mcp-once)
+- [Wire your app: on the first run, or `reticle init`](#wire-your-app-on-the-first-run-or-reticle-init)
+- [Add a cloud dashboard: `reticle connect`](#add-a-cloud-dashboard-reticle-connect)
 - [Step 2: Embed the SDK in your app](#step-2-embed-the-sdk-in-your-app)
   - [Vite + React](#vite--react)
   - [Next.js](#nextjs)
@@ -52,15 +54,52 @@ Everything is **dev-only** and **localhost-only**. It's tree-shaken out of produ
 
 ## Prerequisites
 
-- Node 20 or newer, and a package manager (npm/pnpm/yarn).
+- Node 20.11 or newer, and a package manager (npm/pnpm/yarn).
 - A coding agent that speaks MCP: Claude Code, Cursor, Windsurf, Claude Desktop, etc.
 - A web app you run locally in dev (any framework; React gets the richest features).
 
 ---
 
+## Step 1: Connect your coding agent (MCP), once
+
+You don't start the server manually; your agent starts it via MCP. Register Reticle **once, at the user (global) scope** so every project picks it up. There's nothing to add per project.
+
+**The installer does this for every agent on the machine**, which is why it is the first thing on the [quickstart](/quickstart):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh     # macOS, Linux
+irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex          # Windows PowerShell
+```
+
+Run it in a terminal before you open your agent and there is nothing to restart. The rest of this section is what it writes, for a machine where you would rather do it by hand.
+
+**Claude Code**, one command:
+
+```bash
+claude mcp add reticle -s user -- npx @reticlehq/server mcp
+```
+
+(`reticle setup mcp` and `reticle init` both run exactly this for you. `-s user` is what makes it global; drop it for a project-local registration instead.)
+
+**Cursor**: add to your global `~/.cursor/mcp.json` (not per-project; `reticle init` writes this for you):
+
+```jsonc
+{
+  "mcpServers": {
+    "reticle": { "command": "npx", "args": ["@reticlehq/server", "mcp"] },
+  },
+}
+```
+
+Other MCP clients (Windsurf, Claude Desktop, …) use the same `command`/`args` shape. An agent that was already open reads its server list at startup, so reopen it once. When it launches Reticle, the bridge starts listening on `ws://localhost:4400`.
+
+> Want a different port? Set `RETICLE_PORT` in the server `env` and pass the same URL to `reticle.connect({ url })` in Step 2.
+
+---
+
 ## Wire your app: on the first run, or `reticle init`
 
-Installing Reticle changes nothing in your project. The first time your agent uses Reticle in a project that has never connected (its first `reticle_session { action: "list" }`), Reticle runs `init` there itself and returns the files it changed under `wired`, so you can skip straight to asking your agent to verify a flow. Run `init` yourself to wire a project ahead of time, to preview the changes, or when the agent's MCP server was started outside the project (the call then answers `run_init` with this same command).
+Installing Reticle changes nothing in your project. The first time your agent uses Reticle in a project that has never connected (its first `reticle_session { action: "list" }`), Reticle runs `init` there itself and returns the files it changed under `wired`, so you can skip straight to asking your agent to verify a flow. That call wires the project the agent is in, including a second project on a machine where Reticle is already running for another one. Run `init` yourself to wire a project ahead of time, to preview the changes, or when the agent's MCP server was started outside the project (the call then answers `run_init` with this same command).
 
 From your project root:
 
@@ -70,17 +109,18 @@ RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server init
 
 It detects your framework, package manager, and React version, then:
 
-- **registers the Reticle MCP server once, globally, for each agent you have installed** (Claude Code via `claude mcp add reticle -s user`, and/or Cursor via `~/.cursor/mcp.json`), so every project on this machine gets it; you never re-add it per project,
+- **registers the Reticle MCP server once, globally, for each agent you have installed** (Claude Code via `claude mcp add reticle -s user`, plus every other agent config it finds: Cursor, Windsurf, VS Code, Gemini CLI, OpenCode and Antigravity; Codex CLI through `codex mcp add`, or the lines to paste when that command is missing), so every project on this machine gets it; you never re-add it per project,
 - **writes a verification rule into your agent's instruction file** (`CLAUDE.md`, `.cursor/rules/reticle.mdc`, or `AGENTS.md`), so the agent knows to verify a feature with Reticle _after building it_, not only when you remember to ask (idempotent; appended below anything you already have),
 - installs the SDK kit (`@reticlehq/react`) and the right build plugin (`@reticlehq/vite-plugin` or `@reticlehq/next`) as dev dependencies,
 - **Vite:** adds the `reticle()` plugin to your config, which wires source mapping _and_ `reticle.connect()` for you, so there is nothing else to edit,
-- **Next / other:** creates the dev component and prints the exact `withReticle` / mount / connect snippets to paste (it never half-edits a build config).
+- **Next:** wraps `next.config` in `withReticle` and mounts a generated `<ReticleDev />` component in your root layout; on a config shape it does not recognise it prints the snippet to paste instead (it never half-edits a build config).
+- **Other frameworks:** writes or prints the connect wiring for that framework (see [Frameworks](/frameworks)).
 
 The bridge + MCP server is a single process that serves all your projects, so it's registered at **user scope**, not in a per-project `.mcp.json`. Only the SDK (the `reticle()` plugin / connect call) is added per project.
 
 Re-running is safe: already-registered and already-patched steps are skipped, and on a wired project it goes straight to proving the app still works. Preview without writing via `npx @reticlehq/server init --dry-run`.
 
-`init` does not stop at writing files. It starts your dev server, opens the app, and waits for a session to connect from inside it. That connection is the whole proof that onboarding worked. If a dev server was already running without Reticle, restart it once: it read the build config before `init` edited it. It exits non-zero if nothing connected and prints what is left to do. It does NOT drive. Then prove a flow. That is the FIRST RUN, and it is a separate call: `reticle_verify { action: "explore", persona: "<who does what>" }`. It drives with a model inside the daemon and records what it drove, so later checks replay it with no model in the loop.
+`init` does not stop at writing files. It starts your dev server, opens the app, and waits for a session to connect from inside it. That connection is the whole proof that onboarding worked. If a dev server was already running without Reticle, restart it once: it read the build config before `init` edited it. It exits non-zero if nothing connected and prints what is left to do. It does NOT drive. Then prove a flow. That is the FIRST RUN, and it is a separate call: drive one journey with `reticle_act_and_wait` and an `until` on its last step. On a project linked with `reticle connect`, `reticle_verify { action: "explore", persona: "<who does what>" }` lets the Reticle Harness drive it on the platform instead (every plan includes Harness credits, Free too). Either way what was driven is saved as a flow, so later checks replay it with no model in the loop.
 
 These carry what the command cannot work out for itself:
 
@@ -104,44 +144,7 @@ Optional. Instead of, or after, `init`, run this in your app directory:
 npx @reticlehq/server connect --project "My App"
 ```
 
-Approve the short browser code if Reticle asks you to sign in. The command then links this folder and sends any history already on the machine. Open or restart your coding agent and ask it to verify one real journey. For a new project, the dashboard has no result until that first run is recorded.
-
-## Step 1: Connect your coding agent (MCP), once
-
-You don't start the server manually; your agent starts it via MCP. Register Reticle **once, at the user (global) scope** so every project picks it up. There's nothing to add per project.
-
-**The installer does this for every agent on the machine**, which is why it is the first thing on the [quickstart](/quickstart):
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh     # macOS, Linux
-irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex          # Windows PowerShell
-```
-
-Run it in a terminal before you open your agent and there is nothing to restart. The rest of this section is what it writes, for a machine where you would rather do it by hand.
-
-**Claude Code**, one command:
-
-```bash
-claude mcp add reticle -s user -- npx @reticlehq/server mcp
-```
-
-(`reticle setup mcp` and `reticle init` both run exactly this for you. `-s user` is what makes it global; drop it for a project-local registration instead.)
-
-**Cursor**: add to your global `~/.cursor/mcp.json` (not per-project; `reticle init` writes this for you):
-
-```jsonc
-{
-  "mcpServers": {
-    "reticle": { "command": "npx", "args": ["@reticlehq/server", "mcp"] },
-  },
-}
-```
-
-Other MCP clients (Windsurf, Claude Desktop, …) use the same `command`/`args` shape. An agent that was already open reads its server list at startup, so reopen it once. When it launches Reticle, the bridge starts listening on `ws://localhost:4400`.
-
-> Want a different port? Set `RETICLE_PORT` in the server `env` and pass the same URL to `reticle.connect({ url })` in Step 2.
-
----
+Approve the short browser code if Reticle asks you to sign in. 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 the Harness. What syncs, and how to switch each part off, is in [What is recorded](what-is-recorded.md). The command then links this folder and sends any history already on the machine. Open or restart your coding agent and ask it to verify one real journey. For a new project, the dashboard has no result until that first run is recorded.
 
 ## Step 2: Embed the SDK in your app
 
@@ -168,7 +171,7 @@ export default defineConfig({
 });
 ```
 
-This injects `reticle.connect()` for you _and_ handles React 19 source mapping (Step 3), so there's no entry-file edit and no separate Babel setup. `apply: 'serve'` means it's dropped from `vite build` entirely, so it can never reach production. (This is exactly what `reticle init` adds.)
+This injects `reticle.connect()` for you _and_ handles React 19 source mapping (Step 3), so there's no entry-file edit and no separate Babel setup. A production `vite build` injects nothing and replaces the SDK with an inert stub, so it can never reach production. (This is exactly what `reticle init` adds.)
 
 <details>
 <summary>Prefer to wire it by hand instead of the plugin?</summary>
@@ -183,7 +186,8 @@ import { App } from './App';
 
 if (import.meta.env.DEV) {
   // SESSION_AUTO gives this tab a unique session id, so multiple apps/tabs never collide.
-  reticle.connect({ session: SESSION_AUTO }); // connects to ws://localhost:4400 by default
+  // The token is the contents of ~/.reticle/pairing-token; see "The pairing token" below.
+  reticle.connect({ session: SESSION_AUTO, token: import.meta.env.VITE_RETICLE_TOKEN }); // ws://localhost:4400 by default
 }
 
 createRoot(document.getElementById('root')!).render(
@@ -203,6 +207,7 @@ The daemon auto-generates a **pairing token** on first run and stores it at `~/.
 
 - **Vite plugin users:** nothing to do. The plugin reads the token server-side and injects it into `connect()` for you.
 - **Next.js / hand-wired `connect()`:** your `connect()` runs in the browser and can't read the file, so pass the token in yourself. The simplest path is a shared secret: set `RETICLE_TOKEN` for the daemon (it uses that instead of auto-generating) and expose the same value to the client as `NEXT_PUBLIC_RETICLE_TOKEN`, then pass it to `connect({ token })` (see below). On a single-user machine you can also just read `~/.reticle/pairing-token` in your dev tooling and forward it the same way.
+- **Keep the token out of `.env` files.** Pass it on the dev command (`VITE_RETICLE_TOKEN="$(cat ~/.reticle/pairing-token)" npm run dev`). A production build reads `.env` too, and would write the token into the JavaScript it ships.
 
 ### Next.js
 
@@ -256,19 +261,16 @@ Anywhere your app boots in dev:
 
 ```ts
 import { reticle, SESSION_AUTO } from '@reticlehq/react';
-// Pass the pairing token (see "The pairing token" above); on a hand-wired setup you supply it yourself.
-if (location.hostname === 'localhost')
+// A dev-only guard the bundler strips from production builds (Vite shown), and the pairing token
+// (see "The pairing token" above) passed in on the dev command line only.
+if (import.meta.env.DEV) {
   reticle.connect({ session: SESSION_AUTO, token: import.meta.env.VITE_RETICLE_TOKEN });
+}
 ```
 
-Or, with no build step, a script tag pointed at the bridge:
+Not on Vite? Use your bundler's dev-only flag and its way of passing a value to the browser at dev time. Or run `npx @reticlehq/server init`, which wires the token for every supported stack.
 
-```html
-<script type="module">
-  import { reticle, SESSION_AUTO } from 'https://esm.sh/@reticlehq/react';
-  reticle.connect({ session: SESSION_AUTO });
-</script>
-```
+Plain HTML with no build step: run `npx @reticlehq/server init` in the folder that holds `index.html`. It adds a dev-only snippet that connects only on localhost, and puts this machine's pairing token in a gitignored `reticle.local.js` beside the page, so the token never lands in anything you publish. A hand-written script tag without that token is refused by the bridge.
 
 > **Want to watch the agent work?** Add `present: true` to `reticle.connect()` for a glowing border, a synthetic cursor that flies to targets, click/hover effects, and a narration HUD. See [usage §16](usage.md#16-presenter-mode-narration--fake-clock-watch--control).
 
@@ -369,7 +371,7 @@ If the list is empty, see [Troubleshooting](#troubleshooting).
 
 ## Step 5: Your first verification
 
-> `reticle_verify { action: "explore", persona: "<what>" }` drives this for you and saves the flow. This section is what it does, for when you want to do it yourself.
+> On a project linked with `reticle connect`, `reticle_verify { action: "explore", persona: "<what>" }` drives this for you on the platform and saves the flow. This section is what it does, for when you want to do it yourself.
 
 Now just talk to your agent in plain language. For example:
 
@@ -389,7 +391,7 @@ reticle_assert({ timeout_ms: 2000, predicate: { kind: "allOf", predicates: [
   { kind: "net", method: "GET", urlContains: "/api/dashboard", status: 200, since: 920 },
   { kind: "console", level: "error", absent: true }
 ]}})
-// → { pass: true }
+// → { verified: "yes", verdict: { pass: true, … } }
 ```
 
 You get a real, evidence-backed answer. If it fails, the agent sees the reason (e.g. the call 404'd, or a `TypeError` in `Dashboard.tsx:88`) and can fix it and re-check.
@@ -435,12 +437,12 @@ registerCapabilities({
   signals: ['order:saved', 'cart:updated'],
   stores: ['cart'],
 });
-// agent: reticle_capabilities()  → the whole testable surface
+// agent: reticle_run({ tool: "reticle_capabilities", args: {} })  → the whole testable surface
 ```
 
-> **Multi-domain apps:** prefer `registerReticleDomain({ testids, signals, stores })` co-located in one `reticle.ts` per domain. Each self-registers and `reticle_capabilities()` assembles the union, so there's no central map to forget. See [integration-patterns.md](integration-patterns.md).
+> **Multi-domain apps:** prefer `registerReticleDomain({ testids, signals, stores })` co-located in one `reticle.ts` per domain. Each self-registers and `reticle_run({ tool: "reticle_capabilities", args: {} })` assembles the union, so there's no central map to forget. See [integration-patterns.md](integration-patterns.md).
 
-> Watch the agent work: pass `present: true` to `reticle.connect()` for a glowing border, a cursor that flies to targets, and a HUD; the agent can call `reticle_session {action:"narrate"}({ text })` to show its intent. See [usage §16](usage.md#16-presenter-mode-narration--fake-clock-watch--control).
+> Watch the agent work: pass `present: true` to `reticle.connect()` for a glowing border, a cursor that flies to targets, and a HUD; the agent can call `reticle_session({ action: "narrate", text })` to show its intent. See [usage §16](usage.md#16-presenter-mode-narration--fake-clock-watch--control).
 
 > **Hover-gated UI (tooltips, hover menus, pointer drag)?** Synthetic events can't trigger native `onMouseEnter`. Enable **real input** by launching your browser with `--remote-debugging-port=9222` and setting `RETICLE_CDP_URL` in the MCP server `env`. Reticle then drives real pointer input and `reticle_act` reports `inputMode:"real"`. See [usage §18](usage.md#18-real-input-mode-native-hover--drag).
 
@@ -533,7 +535,7 @@ pnpm add @reticlehq/next
 
 ### What exactly does `reticle init` change in my project?
 
-Four files, and none of them are mysterious: a `.reticle.json` project config, your build config (the `reticle()` Vite plugin, or `withReticle` in `next.config`), a dev-only capabilities file at `src/reticle-dev.ts` (or `app/reticle-dev.tsx` on Next.js), and your agent's rule files. It then starts your dev server and opens the app, neither of which changes your source: the dev server is left running for you afterwards. It also registers the MCP server globally, which is a once-per-machine step rather than a per-project one. Run `npx @reticlehq/server init --dry-run` first to see the exact plan before anything is written.
+A handful of files, none of them mysterious: a `.reticle.json` project config, your build config (the `reticle()` Vite plugin, or `withReticle` in `next.config`), `package.json` (two dev dependencies), a dev-only capabilities file at `src/reticle-dev.ts` (or `app/reticle-dev.tsx` on Next.js), and your agent's rule files (`CLAUDE.md`, `AGENTS.md`, `RETICLE.md`, `.claude/commands/reticle.md`). It then starts your dev server and opens the app, neither of which changes your source: the dev server is left running for you afterwards. It also registers the MCP server globally, which is a once-per-machine step rather than a per-project one. Run `npx @reticlehq/server init --dry-run` first to see the exact plan before anything is written.
 
 ### Do I have to re-register the MCP server for every project?
 
@@ -545,7 +547,7 @@ Because your agent read its MCP server list at startup, before Reticle existed,
 
 ### Which Node version do I need?
 
-Node 20 or newer.
+Node 20.11 or newer.
 
 ### Do I need the React adapter?
 
@@ -557,7 +559,7 @@ Yes, as long as each connection has a unique session id, which `SESSION_AUTO` gi
 
 ### Will Reticle end up in my production bundle?
 
-No. Keep `connect()` behind a dev guard (`import.meta.env.DEV` or a `NODE_ENV` check); the packages are side-effect free and tree-shake out when unused. The Vite plugin uses `apply: 'serve'`, so it is dropped from `vite build` entirely. As a backstop, `connect()` also self-disables when the build reports `NODE_ENV=production`.
+No. Keep `connect()` behind a dev guard (`import.meta.env.DEV` or a `NODE_ENV` check); the packages are side-effect free and tree-shake out when unused. A production `vite build` with the Vite plugin injects nothing and replaces the SDK with an inert stub. As a backstop, `connect()` also self-disables when the build reports `NODE_ENV=production`.
 
 ### Why is my install failing with `ERESOLVE`?