@reticlehq/server 3.5.0 → 3.7.0

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 with Reticle Cloud: run the installer, then `reticle connect --project "My App"` 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. `connect` wires your app, checks that a browser session connected, opens sign-in approval if needed, links the named cloud project, and syncs existing 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. For local-only verification without an account, use `reticle init` instead. 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,23 +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).
 
 ---
 
-## Cloud setup: `reticle connect`
+## Step 1: Connect your coding agent (MCP), once
 
-After the one-time [installer](/quickstart), run this in your app directory:
+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
-npx @reticlehq/server connect --project "My App"
+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"] },
+  },
+}
 ```
 
-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.
+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`
 
-## Local-only path: `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. 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:
 
@@ -78,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,42 +136,15 @@ If you ran `--files-only` with a dev server already running, restart it, then sk
 
 ---
 
-## 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.
+## Add a cloud dashboard: `reticle connect`
 
-**The installer does this for every agent on the machine**, which is why it is the first thing on the [quickstart](/quickstart):
+Optional. Instead of, or after, `init`, run this in your app directory:
 
 ```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"] },
-  },
-}
+npx @reticlehq/server connect --project "My App"
 ```
 
-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
 
@@ -166,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>
@@ -181,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(
@@ -201,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
 
@@ -254,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).
 
@@ -367,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:
 
@@ -387,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.
@@ -433,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).
 
@@ -531,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?
 
@@ -543,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?
 
@@ -555,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`?
 

package/docs/human-control.md

@@ -4,9 +4,9 @@ description: 'Watch the agent’s live transcript, steer it mid-run, or end the
 icon: hand
 ---
 
-With the presenter on (`reticle.connect({ present: true })`), the floating panel in your page lets you watch the agent's live transcript and steer it: **pause** it (its next action tool refuses and returns your guidance), **send** it a correction that rides back on its next tool result, or **end** the session. You can also point at a broken element with **Flag a bug** and hand the agent the element plus its source `file:line`.
+With the presenter on (`reticle.connect({ present: true })`), the floating panel in your page lets you watch the agent's live transcript and steer it: **pause** it (its next action tool refuses until you resume) or **end** the session. You can also point at a broken element with **Flag a bug** and hand the agent the element plus its source `file:line`.
 
-When you run with the presenter on (`reticle.connect({ present: true })`), the floating panel is a **two-way control surface**. You watch the agent's live transcript _and_ can steer it (pause it, send it a correction, or end the session) without leaving the page. There's also a clean, unmistakable "session ended" signal for both you and the agent.
+When you run with the presenter on (`reticle.connect({ present: true })`), the floating panel is a **two-way control surface**. You watch the agent's live transcript _and_ can steer it (pause it or end the session) without leaving the page. To tell the agent something, talk to it in its own window: the panel sends it no text. There's also a clean, unmistakable "session ended" signal for both you and the agent.
 
 ## Watch the testing score climb (the live verdict tally)
 
@@ -16,8 +16,7 @@ The panel header shows a running **✓N ✗M** tally: the verdict score, live. I
 
 MCP is **pull-based**: the agent only receives data when it calls a tool. Reticle can't freeze the model mid-thought, but it **intercepts the agent's next tool call**, which is exactly when the agent would touch the page. That makes steering reliable:
 
-- **Nudge** (a message, no pause). Your text is queued and rides back on the agent's **next** tool result as `guidance` (delivered once). The agent reads it and adjusts.
-- **Pause.** The agent's next `reticle_act` (single or `steps`) / `reticle_act_and_wait` **refuses to execute** and returns `{ paused: true, guidance: ["<your message>"], hint: "…" }`. The page is untouched until resume. _Read-only tools (snapshot/query/observe) still work_, so the agent can look while paused.
+- **Pause.** The agent's next `reticle_act` (single or `steps`) / `reticle_act_and_wait` **refuses to execute** and returns `{ paused: true, guidance: […], hint: "…" }`. The page is untouched until resume. _Read-only tools (`reticle_look`, `reticle_observe`) still work_, so the agent can look while paused.
 - **End.** The session is over; the panel shows "Session ended" and clears.
 
 ## From the panel (the human)
@@ -25,36 +24,37 @@ MCP is **pull-based**: the agent only receives data when it calls a tool. Reticl
 The floating panel (bottom-center, `present: true`) gives you:
 
 - **Pause / Resume**: one toggle. Paused turns the panel + page border **amber** with a `PAUSED` badge.
-- **Message box + send.** Type a correction ("check the error state first"), hit Send (or Enter). Your message shows as a `🧑 you:` bubble in the transcript **and** is delivered to the agent.
 - **End** ends the session: panel turns **emerald**, shows `Session ended · <summary>`, then fades away.
+- **Coding agent.** The Agent Log names the coding agent attached to Reticle (`Claude Code connected`, read from the MCP handshake). With no agent attached it says `No coding agent connected` and offers **Copy prompt**, a prompt to paste into one.
+- **Run Harness**, on the Harness page, drives the page as a person you pick: First-time visitor (the default), Returning power user, On a phone, slow connection, Keyboard only, Careless user (bad and unexpected input), Admin / settings, or Custom… in your own words. The pick is remembered per project. The agent hears about the drive on its next tool call (`harness`), with the `runId` to follow it.
 - **Minimise (▾)** collapses the panel to a bar that streams only the live line; click the bar to restore.
-- **Flag a bug**, the button in the corner. Toggle it on, click the element that looks wrong, type what's wrong (⌘/Ctrl+Enter to send, Esc to back out). Reticle pins a numbered marker, logs your flag in the panel, and hands the agent a structured mark.
+- **Flag a bug**, the button in the corner. Toggle it on, click the element that looks wrong, type what's wrong (⌘/Ctrl+Enter to send, Esc to back out). Reticle pins a numbered marker, logs your flag in the panel, and hands the agent a structured mark. Notes are kept in `.reticle/notes.json` (pending and resolved), so a reload or a daemon restart does not lose them, and a linked project syncs them to the dashboard.
 
 ## Flag a bug: annotate the mistake where you see it
 
 You don't have to describe a bug in prose. **Point at it.** The flag captures the element's re-resolvable anchor _and_ the source `file:line` (when the framework stamped one), so the agent fixes the exact element and code, not a guess. The loop:
 
 1. **You** flag the element and type the problem → Reticle emits a `HUMAN_MARK`.
-2. **The agent** drains it with `reticle_session {action:"review"}`, getting note + element label + `source: { file, line }` + a ready-to-act `fix` hint. `reticle_session { action: "list" }` also reports `pendingMarks` so the agent notices flags.
-3. **The agent** opens the file, fixes it, and calls `reticle_session {action:"review"}({ resolve: "m1" })`.
+2. **The agent** drains it with `reticle_session { action: "review" }`, getting note + element label + `source: { file, line }` + a ready-to-act `fix` hint. `reticle_session { action: "list" }` also reports `pendingMarks` so the agent notices flags.
+3. **The agent** opens the file, fixes it, and calls `reticle_session({ action: "review", resolve: "m1" })`.
 4. **You** see **"✓ fixed: \<your note\>"** land in the panel. Flag → fix → confirmation.
 
-See [`reticle_session {action:"review"}` in the usage guide](/usage) for the tool shape. Suppress the button with `annotate: false` if you don't want it.
+See [`reticle_session { action: "review" }` in the usage guide](/usage) for the tool shape. Suppress the button with `annotate: false` if you don't want it.
 
 ## From the agent (the tools)
 
 | Tool | Args | Effect |
 | --- | --- | --- |
-| `reticle_session {action:"end"}` | `{ summary?, sessionId? }` | end the session; the panel shows "Session ended · summary" |
-| `reticle_session {action:"resume"}` | `{ sessionId? }` | clear a pause and continue |
-| `reticle_session {action:"messages"}` | `{ sessionId? }` | drain + read pending human messages (explicit poll) |
-| `reticle_session {action:"review"}` | `{ resolve?, all?, sessionId? }` | list the bugs the human flagged; resolve one once fixed |
+| `reticle_session { action: "end" }` | `{ summary?, sessionId? }` | end the session; the panel shows "Session ended · summary" |
+| `reticle_session { action: "resume" }` | `{ sessionId? }` | clear a pause and continue |
+| `reticle_session { action: "messages" }` | `{ sessionId? }` | drain + read pending human messages (explicit poll) |
+| `reticle_session { action: "review" }` | `{ resolve?, all?, sessionId? }` | list the bugs the human flagged; resolve one once fixed |
 
-When paused, every action tool short-circuits with the human's guidance, so the agent learns of the pause on its very next action. The agent's expected behavior: **read the guidance, adjust the plan, then call `reticle_session {action:"resume"}`** (or wait for the human to click Resume). The agent can also end the run itself with `reticle_session {action:"end"}({ summary })` when it's done. Either path shows the same "ended" state.
+When paused, every action tool short-circuits with the human's guidance, so the agent learns of the pause on its very next action. The agent's expected behavior: **read the guidance, adjust the plan, then call `reticle_session { action: "resume" }`** (or wait for the human to click Resume). The agent can also end the run itself with `reticle_session({ action: "end", summary })` when it's done. Either path shows the same "ended" state.
 
 ## Piggybacked guidance
 
-Even without a pause, action/observe/assert results carry a `control` block when there's something to tell the agent:
+Even without a pause, any Reticle tool result carries a `control` block when there's something to tell the agent:
 
 ```jsonc
 { since, dispatched, settled, result, control: { state: "active", guidance: ["looks good, keep going"] } }
@@ -66,4 +66,4 @@ Even without a pause, action/observe/assert results carry a `control` block when
 
 Add this to your operating prompt / `CLAUDE.md` (see the [agent cheat-sheet](agent-cheatsheet.md)):
 
-> The human may pause you or send guidance from the Reticle panel. On any `reticle_act` result with `paused: true`, stop, read `guidance`, adjust, then call `reticle_session {action:"resume"}`. Treat a `control.guidance` field on any result as a live instruction from the human.
+> The human may pause you from the Reticle panel. On any `reticle_act` result with `paused: true`, stop, read `guidance`, adjust, then call `reticle_session { action: "resume" }`. Treat a `control.guidance` field on any result as a live instruction from the human.

package/docs/index.mdx

@@ -14,63 +14,36 @@ It answers the only question that matters: did the change actually work? On Reac
 
 ## Install it
 
-Two commands. The first goes in a terminal, before you open your coding agent:
+Four steps. Each command says what it did and is safe to run twice. Needs Node 20.11 or newer.
 
-<CodeGroup>
+| Step | Command | Once per | It worked when |
+| --- | --- | --- | --- |
+| 1. Install | `curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh \| sh` | machine | it says Reticle is on this machine, not in your app yet |
+| 2. Wire your app | `reticle init` (in your app's folder) | project | it lists the files it changed and reports a connected session |
+| 3. Connect _(optional)_ | `reticle connect --project "My App"` | project | `reticle status` shows this folder linked |
+| 4. Sync _(optional)_ | `reticle sync` | whenever you like | your runs show on the dashboard |
 
-```bash macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
-```
-
-```powershell Windows
-irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex
-```
-
-</CodeGroup>
-
-That registers the MCP server with every coding agent it can reach, so the `reticle_*` tools are there the next time you open one. Then, in your project, `npx @reticlehq/server init` wires the app. The [quickstart](/quickstart) walks both.
+On Windows, step 1 is `irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex`. The installer puts `reticle` on your PATH, registers it with every coding agent it finds. It does not wire your app: that is step 2. Skip step 2 and your agent's first `reticle_session` call wires the app instead. The [quickstart](/quickstart) walks every step.
 
-### Or hand the whole thing to your agent
+A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
 
-Copy the block below into Claude Code, Cursor, Copilot, Codex, Windsurf, OpenCode, or any MCP agent. It ends with the only definition of "installed" that counts: one real flow driven, one real verdict returned.
+### Then hand it to your agent
 
-```text
-Reticle is the proof layer for AI coding agents. It runs a dev-only SDK inside my
-running web app, so instead of guessing whether your change worked, you can drive
-the real app and read what actually happened: the network calls, the store, the
-console, the routes, the DOM. You get back pass, fail, or "couldn't tell", with
-the file:line to fix. No screenshots, no vision model, no test syntax.
+The installer ends with **Next steps**. Do them in order:
 
-Use it because you cannot otherwise tell whether your own code works. Reading the
-diff proves nothing, and unit tests do not run the app. Reticle is how you check
-your work before telling me it is done, and how you stop reporting "fixed" over a
-silent 500.
-
-Install it now:
-
-  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init
-
-That one command wires the project, starts the dev server, opens the app and
-waits for it to connect. Do not walk it by hand: read what it prints, do anything
-it says is outstanding, and re-run it, which is safe. It exits non-zero until the
-app connects, and that connection, not a config file, is what "installed" means.
-Then prove a flow, which is a separate call:
-reticle_verify { action: "explore", persona: "<who does what>" }. Only if it could not run at all, follow
-https://docs.reticle.sh/install-manual.md.
-
-Afterwards, use it whenever you change any user-facing behaviour.
-```
+1. **Restart your coding agent.** An agent loads its MCP tools only when it starts, so one that was open during the install cannot see Reticle yet. That restart is why setup begins with a command, not a prompt.
+2. **Paste the prompt the installer printed** into the agent, opened in your app's folder. The agent runs `reticle init`, wires your app, and drives one real flow to a verdict.
 
 <Tip>
   The plugin and the skills CLI are alternatives to the *registration* half only, not to `init`:
-  neither one touches your app, so you still run the command above afterwards to instrument it. On
+  neither one touches your app, so you still run `reticle init` afterwards to instrument it. On
   Claude Code, `/plugin marketplace add reticlehq/reticle` then `/plugin install reticle@reticlehq`
   registers the MCP server and the skills in one step; on most other agents, `npx skills add
   reticlehq/reticle`.
 </Tip>
 
 <Card title="What that command actually changes" icon="wand-magic-sparkles" href="/install-agentic">
-  The four files it writes, the marks it prints, and how to read its report.
+  The files it writes, the marks it prints, and how to read its report.
 </Card>
 
 <CardGroup cols={3}>

package/docs/install-agentic.mdx

@@ -29,43 +29,27 @@ The install is designed for the agent to run rather than you. The agent is about
   bin name on your PATH, which is the only context where the unscoped name is ours.
 </Warning>
 
-## What do I paste into my coding agent to install Reticle?
+## What do I give my coding agent?
 
-Copy this whole block into Claude Code, Cursor, Copilot, Codex, Windsurf, OpenCode, or any MCP agent. It tells the agent what Reticle is, why it should want it, and what counts as finished. That last part is the one that matters.
+Not a prompt first: a command. Run the installer in a terminal:
 
-```text
-Reticle is the proof layer for AI coding agents. It runs a dev-only SDK inside my
-running web app, so instead of guessing whether your change worked, you can drive
-the real app and read what actually happened: the network calls, the store, the
-console, the routes, the DOM. You get back pass, fail, or "couldn't tell", with
-the file:line to fix. No screenshots, no vision model, no test syntax.
-
-Use it because you cannot otherwise tell whether your own code works. Reading the
-diff proves nothing, and unit tests do not run the app. Reticle is how you check
-your work before telling me it is done, and how you stop reporting "fixed" over a
-silent 500.
-
-Install it now:
+```bash
+curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
+```
 
-  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init
+On Windows: `irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex`.
 
-Then follow https://docs.reticle.sh/install-agentic.md and, if anything needs a
-manual edit, https://docs.reticle.sh/install-manual.md. Do not stop until you have
-driven one real flow in my app and produced a verdict. That, not a config file, is
-what "installed" means.
+It registers Reticle with every coding agent it finds and closes with **Next steps**: restart your agent if it is already open, then paste the prompt it printed. That prompt is the one to give the agent. It has the agent run `init`, close the coverage gaps `reticle doctor` lists, and sets what counts as finished: one real flow in your app driven to a verdict, not a config file.
 
-Afterwards, use it whenever you change any user-facing behaviour.
-```
+The order matters. An agent reads its MCP server list when it starts, so a prompt pasted into an agent that is already running has no `reticle_*` tools to call until that agent restarts.
 
 <Tip>
   Prefer installing the skills instead? `npx skills add reticlehq/reticle` on most agents, or
   `/plugin marketplace add reticlehq/reticle` then `/plugin install reticle@reticlehq` on Claude
-  Code, which registers the MCP server and all eleven skills in one step. Then type `/reticle` and
+  Code, which registers the MCP server and the Reticle skill in one step. Then type `/reticle` and
   the agent runs this same setup from the skill.
 </Tip>
 
-The `RETICLE_INSTALL_SOURCE=docs_site` marker is how we tell which published route an install came through. It is self-declared by this page and never inferred, it carries no information about you or your project, and dropping it changes nothing about the install.
-
 <Note>
   Everything on this page is real output. It was captured by scaffolding a pristine `npm create
   vite` React app and running `init` inside it while writing this.
@@ -122,8 +106,9 @@ There are five, and they mean different things. This is the part worth understan
 | `ℹ`  | Done, but incomplete in a way that matters                  | **Yes, read it**    |
 
 <Warning>
-  A `⚠` is not cosmetic. In the run above, Reticle could not write the Codex CLI's TOML config, so
-  it printed the exact block to paste. Leave it and Codex simply never sees the tools.
+  A `⚠` is not cosmetic. In the run above, Reticle could not write the Codex CLI's TOML config (the
+  `codex` command was not installed to do it), so it printed the exact block to paste. Leave it and
+  Codex simply never sees the tools.
 </Warning>
 
 That `ℹ` line is the one people skim past, so here it is in full:
@@ -138,7 +123,7 @@ That `ℹ` line is the one people skim past, so here it is in full:
 
 ## What it actually changes
 
-Four files in your project, none of them mysterious.
+The files it writes in your project, none of them mysterious.
 
 <AccordionGroup>
   <Accordion title=".reticle.json (project config)">
@@ -206,7 +191,7 @@ Four files in your project, none of them mysterious.
 
   <Accordion title="src/reticle-dev.ts (your capabilities)">
     ```ts
-    // Dev-only. Imported automatically by @reticlehq/vite-plugin, so you do not need to import it.
+    // Dev-only. Loaded for you after connect() by @reticlehq/vite-plugin's injected connect, so you do not import it.
     // Self-guards on import.meta.env.DEV, so it is a no-op in a production build.
     import { registerCapabilities } from '@reticlehq/react';
 
@@ -244,9 +229,9 @@ Three of these are answers only the caller has. `init` reads your repository; it
 
 | Flag | When you want it |
 | --- | --- |
-| `persona: "<what>"` | **Name the journey worth proving**, on the FIRST RUN (`reticle_verify { action: "explore", persona: "<the journey worth proving>" }`), not on `init`, which does not drive. Reticle can list the buttons on a page; it cannot know that checkout matters and the theme toggle does not. Naming it is the difference between a drive that finishes and one that spends its budget looking for something to do. |
+| `persona: "<what>"` | **Name the journey worth proving**, on the FIRST RUN (`reticle_verify { action: "explore", persona: "<the journey worth proving>" }`, on a project linked with `reticle connect`; otherwise drive it with `reticle_act_and_wait`), not on `init`, which does not drive. Reticle can list the buttons on a page; it cannot know that checkout matters and the theme toggle does not. Naming it is the difference between a drive that finishes and one that spends its budget looking for something to do. |
 | `--env KEY=VALUE` | What the app needs to reach a usable state: the key from `.env.example`, the mock backend, the variable that skips an auth wall. Repeatable, and a value may contain spaces and equals signs. Without it a real app sits on a login screen and there is no flow to drive. |
-| `--app <dir>` | Monorepos. `init` can find the apps that are servable; only your request says which one you are working in. |
+| `--app <dir>` | Monorepos. `init` can find the apps that are servable; only your request says which one you are working in. It writes that app's files only; add `--start` to boot it too. |
 | `--license <key>` | Writes `RETICLE_LICENSE_KEY` to `.env` and keeps `.env` out of git. Do not do those two by hand. |
 | `--json` | One result object on stdout; progress and package-manager output go to stderr. Default init reports runtime setup and connection. `--files-only` and `--dry-run` report the wiring result. Init does not drive a flow or produce a verification verdict. |
 | `--files-only` | Write the files, register the MCP server with every agent on the machine, pre-approve Reticle's tools, and stop: no dev server, no drive. What `init` did before it learned to boot the app, and the upgrade path for a machine that installed Reticle on an earlier version. |
@@ -270,16 +255,16 @@ That writes the files, registers the MCP server with every agent it finds, pre-a
 
 Two things to know afterwards:
 
-- **A GUI client reads its config at startup.** Cursor, Antigravity, Claude Desktop and VS Code need a window reload before the new rules take effect. The CLIs pick them up on their next run.
+- **A GUI client reads its config at startup.** Cursor, Antigravity and VS Code need a window reload before the new server or rules take effect. The CLIs pick them up on their next run.
 - **The pre-approval is scoped to `reticle` alone**, never a blanket rule for every MCP server, and never a global auto-run switch. If a client's approval file did not exist before, `init` says so in a line, because in Cursor's case that file supersedes what you had approved inside the app.
 
-Drop `--files-only` to get the full run: boot the app, drive a flow, return a verdict.
+Drop `--files-only` for the full run: boot the app and wait for a session to connect. Proving a flow is the first run, a separate call.
 
-## The two restarts you no longer have to think about
+## The two restarts, and when you need them
 
-**Your dev server: `init` handles it.** A dev server that was already running read your build config before `init` edited it, so it keeps serving the old bundle and nothing connects. `init` restarts it and waits for the port to answer, rather than telling you to.
+**Your dev server: restart it once.** One that was already running read your build config before `init` edited it, so it keeps serving a bundle without the SDK. Restart it and hard-reload the tab. `init` names this case when it finds it.
 
-**Your agent: not on the critical path any more.** Your agent read its MCP server list at startup, before Reticle existed, and no slash command re-reads it. `/mcp` manages servers already loaded, so it cannot pick up a new one. That used to mean stopping the install to restart. It does not now: the flow is driven by a child agent process started after registration, which reads the list `init` just wrote. Your own session picks the tools up whenever you next start it, and nothing is waiting on that. This is a once-per-machine annoyance in any case, because Reticle registers globally.
+**Your agent: restart it once, if the tools are missing.** An agent reads its MCP server list when it starts. If it started before Reticle was registered, the `reticle_*` tools are not in this session, and no slash command re-reads the list (`/mcp` manages servers already loaded). Restart the agent once. `reticle init --relaunch` prints the exact command that resumes this conversation with the tools loaded. Until then, `npx @reticlehq/server verify <url> --expect '<predicate JSON>'` proves a flow from the shell. Reticle registers globally, so this happens once per machine.
 
 ## Confirm it worked
 
@@ -287,7 +272,7 @@ Drop `--files-only` to get the full run: boot the app, drive a flow, return a ve
 npx @reticlehq/server status
 ```
 
-It confirms the app connected, or tells you exactly why it hasn't. A session in the list is the install actually finished. Not a green tick. A connected app.
+It confirms the app connected, or tells you exactly why it hasn't. A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
 
 <Card title="Something marked ⚠?" icon="screwdriver-wrench" href="/install-manual">
   The manual install covers every step `init` can't automate, per agent and per framework.