@reticlehq/server 3.6.0 → 3.7.0

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)
@@ -26,6 +25,8 @@ The floating panel (bottom-center, `present: true`) gives you:
 
 - **Pause / Resume**: one toggle. Paused turns the panel + page border **amber** with a `PAUSED` badge.
 - **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. 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.
 
@@ -34,26 +35,26 @@ The floating panel (bottom-center, `present: true`) gives you:
 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"] } }
@@ -65,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,64 +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 ask your agent to verify something in your app: its first Reticle call wires the app and lists the files it changed (`npx @reticlehq/server init` does the same by hand). 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: drive the journey with
-reticle_act_and_wait and an `until` on its last step (or, with a linked project,
-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.

package/docs/install-manual.mdx

@@ -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, because its config is TOML that Reticle will not rewrite).
+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).
 
 </Warning>
 
@@ -42,8 +42,8 @@ There is no config file that all agents share. Each harness has its own path and
 | Cursor | `~/.cursor/mcp.json` | `mcpServers` | no |
 | VS Code | `.vscode/mcp.json` | `servers` | no |
 | Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` | no |
-| OpenCode | `opencode.json` | `mcp` | `"local"` required |
-| Codex CLI | `.codex/config.toml` | `[mcp_servers.reticle]` | no |
+| OpenCode | `~/.config/opencode/opencode.jsonc` | `mcp` | `"local"` required |
+| Codex CLI | `~/.codex/config.toml` | `[mcp_servers.reticle]` | no |
 | Zed | `~/.config/zed/settings.json` | `context_servers` | no |
 
 ### Claude Code
@@ -86,7 +86,7 @@ Same shape, different file and root key. Cursor and Windsurf use `mcpServers`; V
 
 ### Codex CLI
 
-TOML, in `.codex/config.toml`. This is the one `init` cannot write for you:
+TOML, in `~/.codex/config.toml`. With the `codex` command installed, `init` runs `codex mcp add reticle -- npx @reticlehq/server mcp` for you, and only when the file has no `reticle` entry yet, because that command replaces one without asking. Without the command, `init` cannot write it for you:
 
 ```toml
 [mcp_servers.reticle]
@@ -133,25 +133,33 @@ export default defineConfig({
 });
 ```
 
-That's the whole web install. The plugin stamps source locations onto elements. The thing that turns a DOM node into `src/components/Login.tsx:81`. And injects `connect()` so you can't forget it.
+That's the whole web install. The plugin stamps source locations onto elements. That is what turns a DOM node into `src/components/Login.tsx:81`. It also injects `connect()` with the pairing token, so you can't forget either.
 
 ### Anything without the plugin
 
-If you're not on Vite or Next, call `connect()` yourself, guarded so it never reaches production:
+Run `npx @reticlehq/server init` even here: it wires plain HTML, Angular, Remix, Astro, SvelteKit and the rest, and it is the part that gets the **pairing token** to the page without writing it into anything you ship.
+
+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…`.
 
 ```ts
-import { reticle } from '@reticlehq/browser';
+import { reticle, SESSION_AUTO } from '@reticlehq/browser';
 
-if (import.meta.env.DEV) reticle.connect();
+if (import.meta.env.DEV) {
+  // The contents of ~/.reticle/pairing-token, supplied at dev time (here as a Vite env var).
+  // Never commit it, and never let it reach a production build.
+  reticle.connect({ session: SESSION_AUTO, token: import.meta.env.VITE_RETICLE_TOKEN });
+}
 ```
 
+Start the dev server with `VITE_RETICLE_TOKEN="$(cat ~/.reticle/pairing-token)"`, or pin your own secret with `RETICLE_TOKEN=<secret>` in the MCP server's environment and give the page the same value. Set it on the dev command only, never in a `.env` file: a production build reads `.env` and would embed the token in the JavaScript it ships. Not on Vite? Do the same with your bundler's dev-only flag and its way of passing a value to the browser.
+
 <Note>
   `connect()` is dev-only by design. Guard it with whatever your bundler gives you:
   `import.meta.env.DEV`, `process.env.NODE_ENV !== 'production'`, or a build flag. Reticle also
   self-guards, but two locks on a door that leads to your users is a reasonable number.
 </Note>
 
-### Tauri. and the step whose failure is silent
+### Tauri, and the step whose failure is silent
 
 The frontend is identical to any web app. The CSP is not optional:
 
@@ -175,7 +183,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "3.6"
+reticle-tauri = "3.7"
 ```
 
 ```rust
@@ -184,6 +192,8 @@ 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"] }`.
+
 IPC observation needs nothing on the Rust side. An `invoke('load_todos')` already reaches Reticle as `ipc://load_todos`.
 
 <Card title="Electron, and the rest of desktop" icon="display" href="/desktop">
@@ -196,9 +206,9 @@ IPC observation needs nothing on the Rust side. An `invoke('load_todos')` alread
 npx @reticlehq/server status
 ```
 
-A session in the output means the app connected. That. Not a tick in a checklist, is the install finished.
+A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
 
-If it says nothing connected, the usual cause is a port disagreement between your app and the daemon. The browser console will carry `[Reticle] this page could not open a websocket to …` naming the exact address it tried; set it explicitly with `VITE_RETICLE_WS_URL=ws://localhost:4400/reticle` or `reticle.connect({ url })`.
+If it says nothing connected, the usual causes are a port disagreement between your app and the daemon, or a hand-wired `connect()` without the pairing token. The browser console will carry `[Reticle] this page could not open a websocket to …` naming the exact address it tried; set it explicitly with `RETICLE_PORT=4400 pnpm dev` (Vite plugin), `reticle({ port: 4400 })` in `vite.config`, or `reticle.connect({ url: 'ws://localhost:4400/reticle' })` by hand.
 
 Still stuck? `npx @reticlehq/server doctor` checks Chromium, the daemon and the port in one command.
 

package/docs/instrumentation.mdx

@@ -27,7 +27,9 @@ Every verdict carries an `honesty.grade`. How strong the evidence actually was.
   </Card>
 </CardGroup>
 
-Here is the same login, verified two ways. First with a network predicate and no instrumentation leaned on:
+The full ladder, strongest first, is `signal`, `net`, `state`, `presence`, `none`: a matched request grades `net`, between a signal and a store change.
+
+Here is the same login, verified two ways. First with an element predicate and no instrumentation leaned on:
 
 ```json
 "honesty": { "grade": "presence", "coverage": { "pct": 100 }, "integrity": { "clean": true } }
@@ -181,7 +183,7 @@ This is the one that surprises people, so here it is in full. A successful login
     "signals": ["auth:granted"]
   },
   "honesty": { "grade": "signal", "integrity": { "clean": true } },
-  "feedback_invite": "Reticle could not tell what happened here. If you expected otherwise, reticle_feedback. An unknown verdict is our defect, not yours"
+  "feedback_invite": "Reticle could not tell what happened here. If you expected otherwise, reticle_session { action: \"feedback\" }. An unknown verdict is our defect, not yours"
 }
 ```
 
@@ -214,7 +216,7 @@ Signals rot the way every convention rots: someone adds a mutation, forgets the
 npm i -D @reticlehq/eslint-plugin
 ```
 
-One rule. State changed, so a signal must fire, makes the signal layer self-enforcing. It is the only mechanism we have found that survives contact with a deadline.
+One rule, `require-signal-on-mutation` (state changed, so a signal must fire), makes the signal layer self-enforcing. It is the only mechanism we have found that survives contact with a deadline.
 
 ## Start with one flow
 

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` never reaches your production bundle; 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` 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 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.
 
@@ -24,7 +24,7 @@ Adoption is **free → cheap → targeted**. You don't instrument everything; yo
 
 **1. Reuse your existing `data-testid` (free).** If you already test with Playwright or Cypress, your testids work in Reticle unchanged; `reticle_look({ action: "find", by: 'testid', value: 'checkout' })` matches them exactly. No new markup, no new code.
 
-**2. Advertise the surface from your existing constants (cheap).** You already keep a `TestIds` constant object for your E2E suite. Pass it straight in. Now `reticle_capabilities()` tells a fresh agent your whole surface without reading source.
+**2. Advertise the surface from your existing constants (cheap).** You already keep a `TestIds` constant object for your E2E suite. Pass it straight in. Now `reticle_run({ tool: "reticle_capabilities", args: {} })` tells a fresh agent your whole surface without reading source.
 
 ```ts
 import { registerCapabilities } from '@reticlehq/browser';
@@ -49,7 +49,7 @@ That's day-one usefulness with no rewrite. The rest of this doc is how to do ste
 
 ## 2. Inject the emitter (zero prod bundle)
 
-The #1 objection: _"I don't want a test tool in my production bundle."_ The answer: components never import `@reticlehq/browser`. They depend on a tiny structural interface, `ReticleEmitter` (`{ signal, state }`), and the real emitter is injected once at the top. `createReticleEmitter()` returns an emitter that proxies to the connected `reticle` singleton and is a **safe no-op** until `reticle.connect()` runs, so nothing breaks in production or before connect, and **`@reticlehq/browser` stays out of the prod bundle.**
+The #1 objection: _"I don't want a test tool in my production bundle."_ The answer: components never import `@reticlehq/browser`. They depend on a tiny structural interface, `ReticleEmitter` (`{ signal, state }`), and the real emitter is injected once at the top. `createReticleEmitter()` returns an emitter that proxies to the connected `reticle` singleton and is a **safe no-op** until `reticle.connect()` runs, so nothing breaks in production or before connect. With the Vite plugin, a production build replaces `@reticlehq/browser` with an inert stub, so **the SDK stays out of the prod bundle**; with another bundler, `app/emit.ts` is the one import to gate.
 
 ```ts
 // app/emit.ts: the one place that touches @reticlehq/browser
@@ -133,7 +133,7 @@ import { registerReticleDomain } from '@reticlehq/browser';
 registerReticleDomain({ testids: ['search-input'], signals: ['search:ran'] });
 ```
 
-Importing both modules in dev makes `reticle_capabilities()` return the merged surface (`testids: ['section-list', 'section-add', 'search-input']`, `signals: ['section:reordered', 'search:ran']`, `stores: ['workspace']`). `registerReticleDomain` is a thin convenience over `registerCapabilities`, with the same merge-idempotent, HMR-safe semantics, so it composes with §1's "use your existing constants." (Named flows stay an explicit `registerCapabilities({ flows })` concern: their last-writer-wins semantics don't fit "accumulate from many domains.")
+Importing both modules in dev makes `reticle_run({ tool: "reticle_capabilities", args: {} })` return the merged surface (`testids: ['section-list', 'section-add', 'search-input']`, `signals: ['section:reordered', 'search:ran']`, `stores: ['workspace']`). `registerReticleDomain` is a thin convenience over `registerCapabilities`, with the same merge-idempotent, HMR-safe semantics, so it composes with §1's "use your existing constants." (Named flows stay an explicit `registerCapabilities({ flows })` concern: their last-writer-wins semantics don't fit "accumulate from many domains.")
 
 ## 5. Keep the signal layer from rotting (`@reticlehq/eslint-plugin`)
 
@@ -158,20 +158,20 @@ 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 rule, `reticle/no-internal-tags`, 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, `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.
 
 ## 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>`** (add `--headed` to watch). 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 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.
 
 ## Checklist
 
 - [ ] One `app/emit.ts` is the **only** module importing `@reticlehq/browser`; components import the emitter.
 - [ ] `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_capabilities()` returns the full surface.
+- [ ] Each domain self-registers via `registerReticleDomain`; `reticle_run({ tool: "reticle_capabilities", args: {} })` returns the full surface.
 - [ ] Existing Playwright/Cypress testids are reused, not duplicated.
 - [ ] `reticle/require-signal-on-mutation` is enabled with your `mutators` + `signalCallee`.
 - [ ] The team knows `reticle drive <url>` for un-scriptable tabs.

package/docs/license-activation.mdx

@@ -78,7 +78,7 @@ You do not need `NODE_ENV` set, a project, a dev server, or a running app. This
 | `missing` | Reticle found no key in its environment. | The variable is not visible to this process. See below. |
 | `expired` | The key was valid and its term has ended. | Contact us to renew. |
 | `invalid` | The key was not accepted. | Usually a copy or paste problem. See below. |
-| `eval` | This build has no licensing configured. | You are on a build older than licensing. Update. |
+| `eval` | This build has no issuer key: a source build or a dev checkout. | Install the published `@reticlehq/server` package. |
 
 ## Over time
 

package/docs/multi-agent-testing.md

@@ -4,7 +4,7 @@ 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_lease {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 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.
 
 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.
 
@@ -20,27 +20,45 @@ 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; flag anything that looks wrong with the "Flag a bug" annotator. The agent drains those with `reticle_session { action: "review" }`.
 
 ## Agent testing: ~2 minutes
 
 With the app running and instrumented, an agent drives a flow end to end:
 
 ```text
-reticle_lease {action:"acquire"} { url: "http://localhost:3000/dashboard" }
+reticle_run { tool: "reticle_lease", args: { action: "acquire", url: "http://localhost:3000/dashboard" } }
   → { sessionId: "lease-…", ready: true, leased: 1, queued: 0 }
 reticle_act    { sessionId, ... }      # drive the flow
 reticle_assert { sessionId, ... }      # verify intent
-reticle_lease {action:"release"} { sessionId }    # free the slot
+reticle_run { tool: "reticle_lease", args: { action: "release", sessionId } }    # free the slot
 ```
 
-`reticle_lease {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.
+`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.
+
+## 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:
+
+```text
+reticle_run { tool: "reticle_lease", args: { action: "acquire", url: "http://localhost:3000/map", permissions: ["geolocation"] } }
+```
+
+Acquiring again on an origin that already has a lease returns that lease, and its grants never change there, because it may be another agent's live tab. The same list is a plain reuse and a different one is refused. To change them, release the lease and acquire again. Names are Playwright's, such as `geolocation`, `clipboard-read`, `clipboard-write` and `notifications`; one the browser does not know is refused with its reason.
+
+| What the page reads | Without `permissions` | After a grant |
+| --- | --- | --- |
+| `navigator.permissions.query({ name })` | `prompt` | `granted` |
+| `Notification.permission`, in Playwright's headless shell (the default) | `denied` | still `denied` |
+| `Notification.permission`, in an installed Chrome the pool falls back to | `default` | `granted` |
+
+The headless shell has no notification support, so a notifications grant never reaches `Notification.permission` there. When you ask for `notifications`, the lease reads the value back from the page and says so in `hint` whenever the page cannot see the grant.
 
 ## 10 agents, 10 flows, one dashboard
 
 This is the design target, and it needs no special setup:
 
-- Each agent calls `reticle_lease {action:"acquire"}` for the same dashboard URL → its own isolated context (own cookies/storage) in the **one** shared Chromium.
+- 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.
 - 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/babel-plugin.mdx

@@ -8,7 +8,7 @@ icon: file-code
 
 React 19 dropped `_debugSource`, which is what source mapping used to rely on, so without this the tools can tell you the component name but not the file.
 
-**Apache 2.0. CommonJS. No runtime dependencies. Peer dependency: `@babel/core ^7`.**
+**Apache 2.0. CommonJS. One runtime dependency, `@reticlehq/core` (for the attribute name). Peer dependency: `@babel/core ^7`.**
 
 ## What it stamps
 
@@ -36,6 +36,8 @@ The path is relative to `process.cwd()`, with backslashes normalized to forward
 ## What it skips
 
 - Component tags. Only lowercase host elements are stamped, because a component's own JSX gets stamped where it is defined.
+- Lowercase tags that are not HTML or SVG elements, such as react-three-fiber's `<mesh>`. Only known DOM tags are stamped, because a custom renderer can crash on the attribute.
+- Files whose first non-empty line is a comment holding exactly `@reticle-ignore`.
 - Elements that already carry the attribute.
 - Nodes with no location information.
 - Anything whose tag name is not a plain `JSXIdentifier`.
@@ -56,7 +58,7 @@ One export, via `export =`. There are no named exports and no `default` interop
 function reticleSourcePlugin({ types }: { types: typeof BabelTypes }): PluginObj<PluginPass>;
 ```
 
-The Babel plugin name is `reticle-source`. Its visitor handles `JSXOpeningElement` only.
+The Babel plugin name is `reticle-source`. Its visitor handles `Program` (to read the ignore marker) and `JSXOpeningElement`.
 
 **It takes no options.** The plugin reads nothing from `state.opts`.