@reticlehq/server 3.7.0 → 3.8.1

package/docs/getting-started.md

@@ -12,15 +12,15 @@ icon: rocket
 
 This walks you from zero to your agent verifying your app, step by step, with real code for real frameworks. ~10 minutes.
 
-- [What you're setting up](#what-youre-setting-up)
+- [What you set up](#what-you-set-up)
 - [Prerequisites](#prerequisites)
-- [Step 1: Connect your coding agent (MCP), once](#step-1-connect-your-coding-agent-mcp-once)
+- [Step 1: Connect your coding agent to the MCP server](#step-1-connect-your-coding-agent-to-the-mcp-server)
 - [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)
-  - [Plain / other frameworks](#plain--other-frameworks)
+  - [Vite and React](#vite-and-react)
+  - [Next.js](#next-js)
+  - [Plain HTML and other frameworks](#plain-html-and-other-frameworks)
 - [Step 3: (React) component and source-file mapping](#step-3-react-component-and-source-file-mapping)
 - [Step 4: Run it and verify the connection](#step-4-run-it-and-verify-the-connection)
 - [Step 5: Your first verification](#step-5-your-first-verification)
@@ -30,7 +30,7 @@ This walks you from zero to your agent verifying your app, step by step, with re
 
 ---
 
-## What you're setting up
+## What you set up
 
 Three pieces, each tiny:
 
@@ -50,7 +50,7 @@ Three pieces, each from the package for its audience:
 2. **The SDK**: `import { reticle } from '@reticlehq/react'`, a few lines in your app's dev entry point.
 3. **(Optional) React adapter + source-mapping**, so `reticle_look { action: "element" }` can tell the agent which component/file to edit (also from `@reticlehq/react`).
 
-Everything is **dev-only** and **localhost-only**. It's tree-shaken out of production builds.
+By default, everything is **dev-only** and **localhost-only**, and it is removed from production builds. [Production mode](/production-mode) is a separate opt-in.
 
 ## Prerequisites
 
@@ -60,7 +60,7 @@ Everything is **dev-only** and **localhost-only**. It's tree-shaken out of produ
 
 ---
 
-## Step 1: Connect your coding agent (MCP), once
+## Step 1: Connect your coding agent to the MCP server
 
 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.
 
@@ -99,7 +99,7 @@ Other MCP clients (Windsurf, Claude Desktop, …) use the same `command`/`args`
 
 ## 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. 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).
+Installing Reticle changes nothing in your project, and your agent's Reticle calls do not wire it either. In a project that has never connected, the first `reticle_session { action: "list" }` changes no file. It names the zero-install lease, which checks the running app now with nothing installed, and it tells the agent to ask you before it runs `init`. `init` changes files, so it runs only when you agree. Run `init` yourself to wire a project ahead of time or to preview the changes.
 
 From your project root:
 
@@ -116,11 +116,11 @@ It detects your framework, package manager, and React version, then:
 - **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.
+The MCP registration is the same command for every project, so it is registered at **user scope**, not in a per-project `.mcp.json`. Reticle starts a daemon for each project when an agent needs one. Only the SDK (the `reticle()` plugin or the 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: 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.
+`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 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:
 
@@ -144,7 +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 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.
+The browser opens. Sign in with Google or GitHub, or create a free account at app.reticle.sh, then approve the short code that the browser and the terminal show. A new account gets 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
 
@@ -157,7 +157,7 @@ npm i -D @reticlehq/react @reticlehq/vite-plugin     # Vite; or: pnpm add -D …
 
 Then call `reticle.connect()` once, in dev only. Where you put it depends on your framework.
 
-### Vite + React
+### Vite and React
 
 **Recommended: the Vite plugin (one line, does everything).** Add `reticle()` to your `vite.config.ts`:
 
@@ -206,12 +206,24 @@ On React 19 you then also need the source-mapping Babel plugin from Step 3. The
 The daemon auto-generates a **pairing token** on first run and stores it at `~/.reticle/pairing-token` (owner-only, `0600`). The bridge requires it, so another app running on `http://localhost:<some-other-port>` can't quietly register or drive your session. Only code that can read that file (your dev server, not a web page) can present it.
 
 - **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.
+- **Next.js:** wrap `next.config` in `withReticle` from `@reticlehq/next` (see [Next.js](#next-js) below). It reads the token on the server and gives it to the browser as `NEXT_PUBLIC_RETICLE_TOKEN`, which the `ReticleDev` component passes to `connect()`. You do not set the token yourself.
+- **Hand-wired `connect()` (no plugin):** run `npx @reticlehq/server init`. It writes the token to a git-ignored `reticle.local.js` and prints a snippet that imports it (see [Plain HTML and other frameworks](#plain-html-and-other-frameworks)).
 - **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
 
-Create a tiny client component and mount it in your root layout, dev-only:
+First wrap `next.config` in `withReticle`. It reads the pairing token on the server and passes it to the browser. Without it, the bridge refuses the connect:
+
+```ts
+// next.config.ts
+import { withReticle } from '@reticlehq/next';
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {};
+export default withReticle(nextConfig); // no-op in production
+```
+
+Then create a small client component and mount it in your root layout, in development only:
 
 ```tsx
 // app/reticle-dev.tsx
@@ -253,26 +265,31 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 Streamlit owns the top-level HTML document, so it has no template where the plain script tag below can be added. Scripts passed through `st.markdown(..., unsafe_allow_html=True)` are rendered but do not execute.
 
-With Streamlit 1.63 or newer, run `npx @reticlehq/server init` from the project. It detects a `streamlit` dependency or import and prints a copy-pasteable `st.html(..., unsafe_allow_javascript=True)` helper that loads Reticle once in the app document. Keep that helper development-only and do not commit the pairing token printed inside it.
+With Streamlit 1.63 or newer, run `npx @reticlehq/server init` from the project. It detects a `streamlit` dependency or import and prints a copy-pasteable `st.html(..., unsafe_allow_javascript=True)` helper that loads Reticle once in the app document. The helper reads this machine's pairing token from `~/.reticle/pairing-token` when the page is served, so the token is not in the code you paste. Keep the helper development-only.
 
-### Plain / other frameworks
+### Plain HTML and other frameworks
 
 Anywhere your app boots in dev:
 
 ```ts
-import { reticle, SESSION_AUTO } from '@reticlehq/react';
-// 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 });
+// What `reticle init` prints for a bundled app with no Vite or Next plugin.
+// reticle.local.js holds this machine's pairing token. Init writes it and adds it to .gitignore.
+if (process.env.NODE_ENV !== 'production') {
+  void Promise.all([
+    import('@reticlehq/react'),
+    import('./reticle.local.js').catch(() => ({})),
+  ]).then(([{ reticle, install }, local]) => {
+    install();
+    reticle.connect({ token: local.token });
+  });
 }
 ```
 
-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.
+Change the `./reticle.local.js` path so that it points to the project root from your entry module. Do not commit `reticle.local.js`: the token is for this machine only. A teammate runs `reticle init` to get their own.
 
 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).
+> **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).
 
 ### Running multiple apps at once
 
@@ -442,9 +459,9 @@ registerCapabilities({
 
 > **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).
+> **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).
 
 ---
 
@@ -494,7 +511,7 @@ Everything below comes from the `@reticlehq/react` kit plus your framework's bui
 - Port mismatch? If you set `RETICLE_PORT`, pass the same URL to `reticle.connect({ url: 'ws://localhost:<port>/reticle' })`.
 - Need to restart the daemon? **`reticle stop`** cleans it up, no `pkill` needed.
 
-The errors Reticle returns to the agent now carry a `recovery` hint for this exact situation (and for multiple/unknown sessions, a throttled tab, a missing baseline), so the agent knows the next move.
+The errors that Reticle returns to the agent carry a `recovery` hint for this case, and for several or unknown sessions, a throttled tab and a missing baseline. The hint tells the agent what to do next.
 
 **The agent can't find an element**
 
@@ -539,7 +556,7 @@ A handful of files, none of them mysterious: a `.reticle.json` project config, y
 
 ### Do I have to re-register the MCP server for every project?
 
-No. The bridge and MCP server are a single process serving all your projects, so `init` registers it at user scope. Every later project starts with the tools already there. Only the SDK wiring is per project.
+No. The registration is one command, `npx @reticlehq/server mcp`, for every project, so `init` registers it at user scope. Every later project starts with the tools already there. Only the SDK wiring is per project.
 
 ### Why do the Reticle tools not appear after installing?
 
@@ -563,4 +580,4 @@ No. Keep `connect()` behind a dev guard (`import.meta.env.DEV` or a `NODE_ENV` c
 
 ### Why is my install failing with `ERESOLVE`?
 
-You are almost certainly on a Next.js canary or a React RC. That is npm's semver rule for prereleases, not a Reticle restriction. Install with `--legacy-peer-deps`, or use pnpm, whose peer resolution does not hard-fail here. See [Installing alongside a Next.js or React prerelease](#installing-alongside-a-nextjs-or-react-prerelease) above.
+You are almost certainly on a Next.js canary or a React RC. That is npm's semver rule for prereleases, not a Reticle restriction. Install with `--legacy-peer-deps`, or use pnpm, whose peer resolution does not hard-fail here. See [Installing alongside a Next.js or React prerelease](#installing-alongside-a-next-js-or-react-prerelease) above.

package/docs/http-transport.md

@@ -17,7 +17,7 @@ It is the same tool surface. Not a subset, not a simplified one. `reticle_look {
 | `GET` | `/mcp/sse` | Opens a session. The response is an SSE stream that stays open, and every reply the server sends comes back on it. |
 | `POST` | `/mcp/message?sessionId=<id>` | Sends one JSON-RPC message into an open session. |
 
-The daemon listens on port **4400** by default (`RETICLE_PORT`, or `reticle serve --port N`). Run `reticle status` to confirm which port is live.
+The daemon port comes from `reticle serve --port N`, else `RETICLE_PORT`, else `port` in `.reticle.json`, else **4400**. Run `reticle status` to see which port is live.
 
 ## The handshake
 
@@ -64,7 +64,7 @@ Authorization: Bearer <token>
 /mcp/sse?token=<token>
 ```
 
-Set it with `RETICLE_TOKEN`. With no token configured, the daemon binds loopback-only and non-local requests are refused outright rather than falling back to trust.
+The daemon uses `RETICLE_TOKEN` when it is set. Otherwise it uses the token it writes to `~/.reticle/pairing-token` (or `$RETICLE_PAIRING_TOKEN_DIR/pairing-token`). Read the token from there for a remote client, and do not paste it into a file that git tracks.
 
 ## A minimal client
 

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 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`.
+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 open **Notes**, select **Add notes**, and click a broken element. The agent gets the element and 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 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.
+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 give the agent an instruction, talk to it in its own window. The panel sends only notes pinned to elements, and the pause and end controls. There's also a clean, unmistakable "session ended" signal for both you and the agent.
 
 ## Watch the testing score climb (the live verdict tally)
 
@@ -28,16 +28,16 @@ The floating panel (bottom-center, `present: true`) gives you:
 - **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. 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.
+- **Notes.** Open the Notes page and select **Add notes**. Click the element that looks wrong and type what is wrong (⌘/Ctrl+Enter sends, Esc backs out). Reticle pins a numbered marker and gives 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. A linked project syncs them to the dashboard.
 
-## Flag a bug: annotate the mistake where you see it
+## Notes: 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:
+You don't have to describe a bug in prose. **Point at it.** The note 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.
+1. **You** add a note on 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 notes.
 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.
+4. **You** see **"✓ fixed: \<your note\>"** land in the panel. Note → 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.
 

package/docs/index.mdx

@@ -23,7 +23,7 @@ Four steps. Each command says what it did and is safe to run twice. Needs Node 2
 | 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 |
 
-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.
+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 can still check the app with the zero-install lease, which installs nothing. It asks you before it wires the app. The [quickstart](/quickstart) walks every step.
 
 A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
 
@@ -39,7 +39,7 @@ The installer ends with **Next steps**. Do them in order:
   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`.
+  reticlehq/reticle --skill reticle`.
 </Tip>
 
 <Card title="What that command actually changes" icon="wand-magic-sparkles" href="/install-agentic">

package/docs/install-agentic.mdx

@@ -44,10 +44,10 @@ It registers Reticle with every coding agent it finds and closes with **Next ste
 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 the Reticle skill in one step. Then type `/reticle` and
-  the agent runs this same setup from the skill.
+  Prefer installing the skill instead? `npx skills add reticlehq/reticle --skill reticle` on most
+  agents, or `/plugin marketplace add reticlehq/reticle` then `/plugin install reticle@reticlehq` on
+  Claude 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>
 
 <Note>
@@ -70,27 +70,18 @@ reticle init (dry run, no files written)
   in /tmp/initdemo
 
   [·] MCP server (Claude, global) → global (claude user scope)
-      reticle already registered (install once, used by every project)
-  [·] MCP server (Cursor, global) → /Users/you/.cursor/mcp.json
-      reticle already in Cursor global config
+  [·] MCP server (Cursor) → /Users/you/.cursor/mcp.json
   [⚠] MCP server (Codex CLI) → /Users/you/.codex/config.toml
       add this to /Users/you/.codex/config.toml by hand:
       [mcp_servers.reticle]
       command = "npx"
       args = ["@reticlehq/server", "mcp"]
-
   [✓] Agent verification rule → CLAUDE.md
-      teach the agent to verify features with Reticle after building them
   [✓] The /reticle command → .claude/commands/reticle.md
-      type /reticle to verify one flow in the browser
   [✓] Install dependencies → package.json
-      npm i -D @reticlehq/react@<version> @reticlehq/vite-plugin@<version>
   [✓] Reticle config → .reticle.json
-      write project config (framework + port)
   [✓] Vite plugin → vite.config.ts
-      add reticle() to plugins (also injects connect())
   [✓] Capabilities + store → src/reticle-dev.ts
-      no data-testid values yet; no state library detected
 ```
 
 ## Reading the marks
@@ -111,15 +102,17 @@ There are five, and they mean different things. This is the part worth understan
   Codex simply never sees the tools.
 </Warning>
 
-That `ℹ` line is the one people skim past, so here it is in full:
+An `ℹ` line is the one people skim past. Init prints this one when it finds a state library that it cannot register for you (punctuation changed to fit these docs):
 
 ```
   [ℹ] AGENT: finish the capabilities file → src/reticle-dev.ts
-      src/reticle-dev.ts was written but registers nothing, so `hasCapabilities` stays false
-      and reticle_look { action: "state" } has nothing to read.
+      This app's state lives in a library nothing in the running app points at, so it is the one thing Reticle cannot find for itself: reticle_state will not see it until you say where it is.
+      Do this now, before driving anything:
+        1. In src/reticle-dev.ts, uncomment the suggested line and complete it: <the hint for your library>.
+        2. Prove it: drive one flow and check reticle_state returns your key. An empty state read means the line is still not doing anything, whatever else went green.
 ```
 
-`init` wrote the file, but a brand-new Vite template has no testids and no state library, so there was nothing to register. Reticle tells you this instead of counting it as a win. See [Instrument your app](/instrumentation) for what to put in it.
+Do the two steps. Reticle tells you this instead of counting the file as a win. See [Instrument your app](/instrumentation) for what to put in the file.
 
 ## What it actually changes
 
@@ -190,12 +183,17 @@ The files it writes in your project, none of them mysterious.
   </Accordion>
 
   <Accordion title="src/reticle-dev.ts (your capabilities)">
+    Trimmed, with the punctuation changed to fit these docs: the real file also has a comment block about where to start and a `declare global` block for the `DEV` type.
+
     ```ts
-    // Dev-only. Loaded for you after connect() by @reticlehq/vite-plugin's injected connect, so you do not import it.
+    // Dev-only. Loaded for you after connect() (by @reticlehq/vite-plugin's injected connect, or by
+    // the connect file init wrote for a framework that connects itself), 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';
 
     if (import.meta.env.DEV) {
+      // No state library detected. If you add one, register it here. See https://docs.reticle.sh/state-management
+
       registerCapabilities({
         testids: [], // none found; add data-testid to your key elements
         signals: [], // names you pass to reticle.signal()
@@ -219,6 +217,7 @@ The files it writes in your project, none of them mysterious.
 
 ```
 reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+              [--env KEY=VALUE]... [--files-only] [--json] [--relaunch]
               --app picks WHICH app in a monorepo, when several are found
               --no-mcp skips MORE than the server registration: also the agent rule files
               (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three

package/docs/install-manual.mdx

@@ -7,7 +7,7 @@ icon: screwdriver-wrench
 
 **Installing Reticle by hand is two independent halves: register the MCP server so your agent gets the `reticle_*` tools, then add the SDK to your app so there is something for those tools to talk to.** You need both, in that order.
 
-Do only the first half and the tools appear but every call reports no session. Do only the second and your app connects to a daemon nobody is asking questions. Stop after the first half and your agent's first Reticle call wires the app itself when you ask it to verify something, and offers to otherwise.
+Do only the first half and the tools appear but every call reports no session. Do only the second and your app connects to a daemon nobody is asking questions. Stop after the first half and your agent can still check the running app with the zero-install lease, which installs nothing. It asks you before it runs `init`.
 
 <Warning>
   **You probably do not need this page.** Two commands do all of it:
@@ -19,7 +19,7 @@ npx @reticlehq/server init                      # in your project
 
 The first registers the MCP server with every agent it can reach. The second wires the app. See the [quickstart](/quickstart).
 
-This page is for the cases those cannot cover: a machine where piping a script is not allowed, an agent Reticle does not know, or a step the installer reported as needing a hand (Codex CLI is the usual one when the `codex` command is not installed, because its config is TOML that Reticle will not rewrite itself).
+This page is for the cases those cannot cover: a machine where piping a script is not allowed, an agent Reticle does not know, or a step the installer reported as needing a hand (Codex CLI is the usual one when the `codex` command is not installed, because only `codex mcp add` registers a server in its TOML config).
 
 </Warning>
 
@@ -94,6 +94,8 @@ command = "npx"
 args = ["@reticlehq/server", "mcp"]
 ```
 
+When the `[mcp_servers.reticle]` table is there, Reticle adds one line under it: `default_tools_approval_mode = "approve"`. This line approves Reticle's own tools, so Codex does not ask before each call. Reticle changes no other line, and it keeps a mode that you set. To undo it, change that line to `default_tools_approval_mode = "prompt"`. Reticle does not change a mode that is already there.
+
 ### OpenCode
 
 Note the flat command array and the required `type`:
@@ -141,6 +143,8 @@ Run `npx @reticlehq/server init` even here: it wires plain HTML, Angular, Remix,
 
 If you really are wiring `connect()` by hand, pass the token. The daemon writes it to `~/.reticle/pairing-token` on first start and refuses a page that does not present it, on localhost too. Without it the page console says `bridge refused the connection: authentication failed: no pairing token on the page…`.
 
+`init` gives you a module for this: it writes the token to `reticle.local.js` at the project root, adds that file to `.gitignore`, and prints a snippet that imports it. To do it without `init`, pass the token yourself:
+
 ```ts
 import { reticle, SESSION_AUTO } from '@reticlehq/browser';
 
@@ -183,7 +187,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "3.7"
+reticle-tauri = "3.8"
 ```
 
 ```rust
@@ -192,7 +196,7 @@ tauri::Builder::default()
     .on_page_load(reticle_tauri::on_page_load)
 ```
 
-**Dev builds only.** In a release build the crate is inert: `reticle_capture` refuses and `on_page_load` does nothing, so the binary you sign and ship carries no Reticle capability. A release build you test with Reticle (a CI fixture) turns it on with `reticle-tauri = { version = "3.7", features = ["in-release"] }`.
+**Dev builds only.** In a release build the crate is inert: `reticle_capture` refuses and `on_page_load` does nothing, so the binary you sign and ship carries no Reticle capability. A release build you test with Reticle (a CI fixture) turns it on with `reticle-tauri = { version = "3.8", features = ["in-release"] }`.
 
 IPC observation needs nothing on the Rust side. An `invoke('load_todos')` already reaches Reticle as `ipc://load_todos`.
 

package/docs/integration-patterns.md

@@ -4,7 +4,7 @@ description: 'The recommended shape for a real codebase: a minimal production fo
 icon: shapes
 ---
 
-The recommended shape for a real codebase is three decisions: put `createReticleEmitter()` in one `app/emit.ts` so components depend on an interface and `@reticlehq/browser` is imported in exactly one place; emit signals from the **store layer** rather than from N call sites; and let each feature self-register its testids and signals with `registerReticleDomain`. Then turn on `reticle/require-signal-on-mutation` so the signal layer cannot silently rot.
+The recommended shape for a real codebase is three decisions: put `createReticleEmitter()` in one `app/emit.ts` so components depend on an interface and `@reticlehq/browser` stays out of your components; emit signals from the **store layer** rather than from N call sites; and let each feature self-register its testids and signals with `registerReticleDomain`. Then turn on `reticle/require-signal-on-mutation` so the signal layer cannot silently rot.
 
 The basics in [Getting Started](getting-started.md) work with **zero app changes**. This doc is the _recommended_ shape for a real codebase: a minimal production footprint, a signal layer that can't silently drift, and an adoption path that starts paying off on day one, with no rewrite required.
 
@@ -12,7 +12,7 @@ The basics in [Getting Started](getting-started.md) work with **zero app changes
 - [2. Inject the emitter (zero prod bundle)](#2-inject-the-emitter-zero-prod-bundle)
 - [3. Emit signals from the store layer, not N call sites](#3-emit-signals-from-the-store-layer-not-n-call-sites)
 - [4. Self-registering domains (`registerReticleDomain`)](#4-self-registering-domains-registerreticledomain)
-- [5. Keep the signal layer from rotting (`@reticlehq/eslint-plugin`)](#5-keep-the-signal-layer-from-rotting-reticleeslint-plugin)
+- [5. Keep the signal layer from rotting (`@reticlehq/eslint-plugin`)](#5-keep-the-signal-layer-from-rotting-@reticlehq/eslint-plugin)
 - [6. Limitation: un-scriptable tabs, use `reticle drive`](#6-limitation-un-scriptable-tabs-use-reticle-drive)
 - [Checklist](#checklist)
 
@@ -158,17 +158,17 @@ export default [
 ];
 ```
 
-Or turn it on with the shipped preset: `plugin.configs.recommended`, which sets `reticle/require-signal-on-mutation` to `warn` (with empty no-op defaults you then configure) and the plugin's other two rules, `reticle/no-internal-tags` and `reticle/no-runaway-comment`, to `error`. A function that calls a mutator and a signal together passes; a mutator with no signal reports `store mutation without a mapped Reticle signal`. The documented view-level exceptions from §3 simply don't list those view callees as `mutators`, so they never fire.
+Or turn it on with the shipped preset: `plugin.configs.recommended`, which sets `reticle/require-signal-on-mutation` to `warn` (with empty no-op defaults you then configure) and the plugin's other two rules to `error`. `reticle/no-internal-tags` reports design-document codes (such as `N5` or `§4.3`) and version strings (such as `v2.2.0`) in comments, test names and file names. `reticle/no-runaway-comment` reports a block comment of more than 60 lines. If your code base uses either pattern, turn the rule off in your config, or enable only `reticle/require-signal-on-mutation`. A function that calls a mutator and a signal together passes; a mutator with no signal reports `store mutation without a mapped Reticle signal`. The documented view-level exceptions from §3 simply don't list those view callees as `mutators`, so they never fire.
 
 ## 6. Limitation: un-scriptable tabs, use `reticle drive`
 
 Reticle observes and drives a tab through the in-page SDK plus (optionally) CDP. It **cannot bring to front or recover a browser tab the OS won't let it script**: a backgrounded tab, say, or a non-default browser (Dia, etc.) reporting `hidden:true` / `throttled:true`.
 
-When that happens, `reticle_session { action: "list" }` and every act/assert result carry a `session.recommendation` saying so. The escape hatch is **`reticle drive <url>`**, which opens in the foreground (`--headless` hides it). Reticle launches and owns a guaranteed-scriptable browser. See [usage §18](usage.md#18-real-input-mode-native-hover--drag) for the full note.
+When that happens, `reticle_session { action: "list" }` and every act/assert result carry a `session.recommendation` saying so. The agent's way out is a lease: `reticle_run({ tool: "reticle_lease", args: { action: "acquire", url } })` opens a tab that Reticle owns. A person can run **`reticle drive <url>`**, which opens a browser in the foreground (`--headless` hides it). The person who watches sees nothing of a lease, so prefer the open tab while someone follows along. See [usage §18](usage.md#18-real-input-mode-native-hover-&-drag) for the full note.
 
 ## Checklist
 
-- [ ] One `app/emit.ts` is the **only** module importing `@reticlehq/browser`; components import the emitter.
+- [ ] Components import the emitter from `app/emit.ts`, never `@reticlehq/browser`. Only `app/emit.ts`, the store layer and the `reticle.ts` domain files import the SDK.
 - [ ] `reticle.connect()` is dev-gated; the prod bundle has no `@reticlehq/browser`.
 - [ ] Signals fire from the store layer (middleware or `commitAndSignal`); view-level exceptions are explicit.
 - [ ] Each domain self-registers via `registerReticleDomain`; `reticle_run({ tool: "reticle_capabilities", args: {} })` returns the full surface.

package/docs/multi-agent-testing.md

@@ -4,15 +4,15 @@ description: 'Several apps at once, ports that shift between runs, and many agen
 icon: users
 ---
 
-Many agents can drive the same app at once without a browser each: `reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` hands each one an **isolated context** (its own cookies, storage and DOM) from a single shared headless Chromium. One daemon per machine, and identity is the **app** (a stable `projectId` stamped by the build plugin), not the port, so an app that boots on `:3001` today is still the same app.
+Many agents can drive the same app at once without a browser each: `reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` hands each one an **isolated context** (its own cookies, storage and DOM) from a single shared headless Chromium. One daemon for each project, and identity is the **app** (a stable `projectId` stamped by the build plugin), not the port, so an app that boots on `:3001` today is still the same app.
 
 Reticle is built for the messy real world: several apps running at once, ports that shift between runs, and many agents driving different flows of the same app in parallel, without each one spinning up its own Chromium. This page explains how that works and how to use it.
 
 ## The mental model
 
-- **One daemon per machine.** `reticle mcp` discovers a running daemon (via `~/.reticle`) or starts one. A crashed daemon's stale pidfile is reclaimed automatically, so you never chase "port already in use" or a zombie server.
+- **One daemon for each project.** `reticle mcp` finds this project's daemon through `~/.reticle`, or starts one. When another project's daemon holds the port, it starts one on a free port. A crashed daemon's stale pidfile is reclaimed automatically, so you never chase "port already in use" or a zombie server.
 - **Identity is the app, not the port.** The build plugin stamps a stable `projectId` that travels in every connection. If your Next app usually runs on `:3000` but boots on `:3001` today, Reticle still knows which app it is, and an agent scoped to project A will never accidentally drive project B's tab. Origin is only a fallback hint.
-- **One browser, many contexts.** When agents need their own headless tabs, the daemon's **browser pool** launches a single Chromium and hands out isolated contexts (one per flow). They are cheap, and capped so a big fan-out can't exhaust the machine. Over-cap requests queue.
+- **One browser, many contexts.** When agents need their own headless tabs, the daemon's **browser pool** launches a single Chromium and hands out isolated contexts (one per flow). They are cheap, and capped so a big fan-out can't exhaust the machine. An acquire over the cap is refused at once and names the cap.
 - **Attach-only daemon.** The daemon never starts your dev server. It connects to an app that is running (or opens a headless tab pointed at it). When nothing is running, the agent starts your project's own dev script in the background and tells you. A build process spawned by a background daemon would be invisible, unconsented, and orphaned when the daemon exits.
 
 ## Manual testing: ~5 minutes
@@ -20,7 +20,7 @@ Reticle is built for the messy real world: several apps running at once, ports t
 1. Add the plugin (Vite/Next) or one `reticle.connect()` call. (See [getting-started](./getting-started.md).)
 2. Start your app as you normally do.
 3. Open it in a browser; the in-page panel shows Reticle is connected.
-4. Click around; flag anything that looks wrong with the "Flag a bug" annotator. The agent drains those with `reticle_session { action: "review" }`.
+4. Click around. To report something that looks wrong, open **Notes** in the panel, select **Add notes**, and click the element. The agent drains those with `reticle_session { action: "review" }`.
 
 ## Agent testing: ~2 minutes
 
@@ -36,6 +36,8 @@ reticle_run { tool: "reticle_lease", args: { action: "release", sessionId } }
 
 `reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` opens a fresh isolated headless context against your **already-running** app, stamps the lease identity into the URL so the app's own SDK registers under a sessionId you can target, and waits until that tab has connected (`ready: true`) before returning, so the sessionId is usable immediately. Release when the flow finishes.
 
+**Lease the exact host that the dev server binds.** `http://localhost:3000` and `http://127.0.0.1:3000` are two origins, and they are not the same address. A dev server that binds only `::1` (Vite can do this for `localhost`) refuses a lease on `127.0.0.1`, and a server that binds only `127.0.0.1` does not answer on `::1`. The two origins also have their own cookies and storage, and a lease is reused for each origin. Copy the url that the dev server prints, host and port included.
+
 ## Permissions
 
 A lease starts with every permission undecided. Pass `permissions` to grant some on the app's origin before the first navigation, so the first render already sees them:
@@ -59,7 +61,7 @@ The headless shell has no notification support, so a notifications grant never r
 This is the design target, and it needs no special setup:
 
 - Each agent calls `reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` for the same dashboard URL → its own isolated context (own cookies/storage) in the **one** shared Chromium.
-- The pool caps simultaneous contexts (`RETICLE_MAX_CONTEXTS`, default scales with CPU under a ceiling); extra acquires queue and proceed as slots free.
+- The pool caps simultaneous contexts (`RETICLE_MAX_CONTEXTS`, default scales with CPU under a ceiling). An acquire, or a `reticle drive`, that finds every slot taken is refused at once with `all N lease slots are in use`, naming the release and the override, so an agent knows to release a lease or wait rather than retry into the same full pool. The parallel flow runner queues instead, since it holds its own slots and frees them as each flow ends.
 - Flows can't bleed into each other: contexts are isolated and every session is scoped by `projectId`.
 - A single crashed page is reclaimed on its own, and if an agent crashes or hangs its lease stops being touched and the **lease reaper** reclaims the context after a TTL, freeing the slot. One dead agent never starves the others.
 

package/docs/packages/browser.mdx

@@ -24,9 +24,31 @@ npm i -D @reticlehq/browser
 
 ```ts
 import { reticle } from '@reticlehq/browser';
-if (import.meta.env.DEV) reticle.connect();
+
+if (import.meta.env.DEV) {
+  // reticle.local.js holds this machine's pairing token. Do not commit it.
+  import('./reticle.local.js')
+    .catch(() => ({}))
+    .then((local) => reticle.connect({ token: local.token }));
+}
+```
+
+The bridge refuses a connect without the pairing token, also on localhost. `reticle init` writes `reticle.local.js` at the project root and adds it to `.gitignore`. Change the import path so that it points to that file. If you did not run `reticle init`, make the file yourself from the token that the daemon keeps in `~/.reticle/pairing-token`:
+
+```bash
+printf "export const token = '%s';\n" "$(cat ~/.reticle/pairing-token)" > reticle.local.js
+echo reticle.local.js >> .gitignore
 ```
 
+With the Vite plugin and `inject: false`, pass `token: __RETICLE_TOKEN__` instead. See [the Vite plugin](/packages/vite-plugin).
+
+## Subpaths
+
+| Subpath | What it is |
+| --- | --- |
+| `./activate` | `activate({ publicKey })`. Connects the SDK on a staging or production deployment, but only when the page URL carries a valid signed ticket in the `reticle_activate` parameter. Without the parameter it does nothing. See [Production mode](/production-mode) |
+| `./inject` | The SDK build that a hosted verifier puts into a page from outside. An app does not import it |
+
 ## The `reticle` singleton
 
 One instance, memoized on `globalThis` so hot module replacement does not create a second one.
@@ -36,6 +58,8 @@ One instance, memoized on `globalThis` so hot module replacement does not create
 | `connect`           | `(options?: ReticleConnectOptions) => void`                |
 | `connected`         | `get connected(): boolean`                                 |
 | `signal`            | `(name: string, data?: Record<string, unknown>) => void`   |
+| `routes`            | `(patterns: readonly string[]) => void`                    |
+| `busy`              | `<T>(work: Promise<T>) => Promise<T>`                      |
 | `state`             | `(name: string, value: unknown) => void`                   |
 | `renderCommit`      | `(commits: number) => void`                                |
 | `describe`          | `(input: CapabilitiesInput) => void`                       |
@@ -43,8 +67,12 @@ One instance, memoized on `globalThis` so hot module replacement does not create
 | `disconnect`        | `() => void`                                               |
 | `observeHotUpdates` | `(hot: unknown) => void` (called by the build integration) |
 
+`routes` declares the app's route patterns (`/runs/:id`, `*` for the rest), so each route change names its screen. `busy` declares work that only the app can see, such as a debounced save. A settle waits for it, and it returns `work`.
+
 Everything else on the class is private. `Reticle` itself is exported for typing.
 
+`trackShortTimers(maxMs?: number): () => void` is a separate export. It counts every short `setTimeout` (one second or less by default) as busy work, so a settle waits through a debounce. It returns the function that turns it off. It is off until you call it.
+
 ## `ReticleConnectOptions`
 
 Every field is optional.
@@ -54,9 +82,11 @@ Every field is optional.
 | `url` | `string` | Bridge URL, when you are not on the default port |
 | `session` | `string` | Session id. Defaults to the auto id (`SESSION_AUTO` is re-exported here) |
 | `projectId` | `string` | Project identity stamped on the handshake |
-| `token` | `string` | Pairing token, required for a non-loopback page |
+| `token` | `string` | Pairing token. Required on every page, also on localhost, because the daemon makes one on its first start. The build plugins pass it for you |
 | `allowNonLocalhost` | `boolean` | Opt in to connecting from a non-localhost origin |
 | `allowInProduction` | `boolean` | Opt in to connecting from a production build. Desktop apps need this |
+| `env` | `'development' \| 'production'` | Where the page runs. `production` needs a session nonce as `token`. Absent: development. The [production loader](/production-mode) sets it |
+| `scope` | `'observe' \| 'act'` | What a drive may do. Required with `env: 'production'` |
 | `testIdAttribute` | `string` | The attribute the app marks controls with, when it is not `data-testid` |
 | `overlay` | `boolean` | The in-page overlay |
 | `captureNetworkBodies` | `boolean` | Record request and response bodies |
@@ -77,6 +107,8 @@ Every field is optional.
 | `idleEndMs` | `number` | Idle timeout before the session ends itself |
 | `redact` | `RedactionConfig` | Redaction policy, from core |
 
+Reticle itself sets two more fields, `injected` and `lease`. Do not set them in an app.
+
 ## Capabilities
 
 Declaring a capability surface is what lets an agent discover what your app can do without guessing.