@reticlehq/server 2.14.0 → 3.2.0

package/docs/getting-started.md

@@ -4,7 +4,7 @@ description: 'Zero to your agent verifying your real app, step by step, with wor
 icon: rocket
 ---
 
-**To get started with Reticle: run `npx @reticlehq/server init --flow "<the journey worth proving>"` in your project root.** That one command wires your project, starts your dev server, opens the app, waits for it to connect, and drives that flow to a verdict. You do not restart anything and you do not drive it yourself. Reticle is a verification layer that embeds a dev-only SDK in your running web app so an AI coding agent can prove a change works instead of guessing. It needs Node 20 or newer, an app you run locally, and an agent that speaks MCP.
+**To get started with Reticle: run the installer, open your coding agent, then run `npx @reticlehq/server init` in your project root.** Getting started is three stages. **Installation** is one command in a terminal, `curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh` (or `irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex` on Windows): it puts the CLI on the machine and registers the MCP server with every agent it can reach, so the tools are there the next time you open your agent. **Onboarding** is `init`: it wires your project, starts your dev server, opens the app and waits for it to connect. **The first run** is what proves anything: `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`, or from a terminal `npx @reticlehq/server verify <url> --explore --persona "<the journey worth proving>"`. A connected app is not a verified one. Reticle is a verification layer that embeds a dev-only SDK in your running web app so an AI coding agent can prove a change works instead of guessing. It needs Node 20 or newer, an app you run locally, and an agent that speaks MCP.
 
 > **Looking for the fast path?** [Quickstart](/quickstart) gets you to a real verdict in five minutes, and every response on it was captured live. [Agentic install](/install-agentic) and [Manual install](/install-manual) cover setup in detail, per agent and per framework.
 >
@@ -46,7 +46,7 @@ Three pieces, each from the package for its audience:
 
 1. **The MCP server.** Your agent launches it with `npx @reticlehq/server mcp`; it hosts the tools _and_ the WebSocket bridge your app connects to. You don't run it by hand; the agent does.
 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_inspect` can tell the agent which component/file to edit (also from `@reticlehq/react`).
+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.
 
@@ -78,17 +78,17 @@ The bridge + MCP server is a single process that serves all your projects, so it
 
 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 (restarting one whose bundle predates the config edit), opens the app, waits for a session to connect from inside it, and drives one flow to a verdict, which it saves so later checks are a single call with no model involved. It exits non-zero if no verdict was produced and prints what is left to do.
+`init` does not stop at writing files. It starts your dev server (restarting one whose bundle predates the config edit), opens the app, and waits for a session to connect from inside it. That connection is the whole proof that onboarding worked. It exits non-zero if nothing connected and prints what is left to do. It does NOT drive. Then prove a flow. That is the FIRST RUN, and it is a separate call: `reticle_verify { action: "explore", persona: "<who does what>" }`. It drives with a model inside the daemon and records what it drove, so later checks replay it with no model in the loop.
 
-Three flags carry what the command cannot work out for itself:
+These carry what the command cannot work out for itself:
 
 | Flag | What only you know |
 | --- | --- |
-| `--flow "<what>"` | Which journey proves the thing you care about. It can list the buttons on your page; it cannot know that checkout matters and the theme toggle does not. |
+| `persona: "<what>"` | Belongs to the first run, not to `init`. Which journey proves the thing you care about: Reticle can list the buttons on your page; it cannot know that checkout matters and the theme toggle does not. |
 | `--env KEY=VALUE` | What your app needs to reach a usable state: the key from `.env.example`, the mock backend, the variable that skips an auth wall. Repeatable. |
 | `--app <dir>` | Which app in a monorepo. It finds the servable ones; only you know which you are working in. |
 
-The rest are dials: `--license <key>` (writes it to `.env` and keeps `.env` out of git), `--json` (one object for an agent to read), `--files-only` (write, register, pre-approve, and stop, which is what `init` did before it learned to boot the app, and what an existing install re-runs to pick up new wiring), `--relaunch` (prints the command that restarts the conversation you are in, with the tools loaded: the restart step most installs stall on, and it composes with `--files-only`), `--no-open`, `--no-drive`, `--dry-run`, `--port N`, `--no-mcp`, `--no-install`.
+The rest are dials: `--license <key>` (writes it to `.env` and keeps `.env` out of git), `--json` (one object for an agent to read), `--files-only` (write, register, pre-approve, and stop, which is what `init` did before it learned to boot the app, and what an existing install re-runs to pick up new wiring), `--relaunch` (prints the command that restarts the conversation you are in, with the tools loaded: the restart step most installs stall on, and it composes with `--files-only`), `--no-open`, `--dry-run`, `--port N`, `--no-mcp`, `--no-install`.
 
 Then restart your dev server and skip to [Step 4](#step-4-run-it-and-verify-the-connection). The manual steps below explain what `init` sets up, if you prefer to wire it yourself.
 
@@ -98,13 +98,22 @@ Then restart your dev server and skip to [Step 4](#step-4-run-it-and-verify-the-
 
 You don't start the server manually; your agent starts it via MCP. Register Reticle **once, at the user (global) scope** so every project picks it up. There's nothing to add per project.
 
+**The installer does this for every agent on the machine**, which is why it is the first thing on the [quickstart](/quickstart):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh     # macOS, Linux
+irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex          # Windows PowerShell
+```
+
+Run it in a terminal before you open your agent and there is nothing to restart. The rest of this section is what it writes, for a machine where you would rather do it by hand.
+
 **Claude Code**, one command:
 
 ```bash
 claude mcp add reticle -s user -- npx @reticlehq/server mcp
 ```
 
-(`reticle init` runs exactly this for you. `-s user` is what makes it global; drop it for a project-local registration instead.)
+(`reticle setup mcp` and `reticle init` both run exactly this for you. `-s user` is what makes it global; drop it for a project-local registration instead.)
 
 **Cursor**: add to your global `~/.cursor/mcp.json` (not per-project; `reticle init` writes this for you):
 
@@ -116,7 +125,7 @@ claude mcp add reticle -s user -- npx @reticlehq/server mcp
 }
 ```
 
-Other MCP clients (Windsurf, Claude Desktop, …) use the same `command`/`args` shape. Restart the agent so it picks up the new server. When it launches Reticle, the bridge starts listening on `ws://localhost:4400`.
+Other MCP clients (Windsurf, Claude Desktop, …) use the same `command`/`args` shape. An agent that was already open reads its server list at startup, so reopen it once. When it launches Reticle, the bridge starts listening on `ws://localhost:4400`.
 
 > Want a different port? Set `RETICLE_PORT` in the server `env` and pass the same URL to `reticle.connect({ url })` in Step 2.
 
@@ -288,7 +297,7 @@ Either way, the rule is the same: **the app's bridge port must equal the daemon'
 
 ## Step 3: (React) component and source-file mapping
 
-This is optional but high-value: it lets `reticle_inspect` map a DOM element back to the **React component and the source file:line**, so when the agent finds a problem, it knows which file to edit. (The React adapter ships in `@reticlehq/react`; nothing extra to install.)
+This is optional but high-value: it lets `reticle_look { action: "element" }` map a DOM element back to the **React component and the source file:line**, so when the agent finds a problem, it knows which file to edit. (The React adapter ships in `@reticlehq/react`; nothing extra to install.)
 
 ```ts
 import { install as installReticleReact } from '@reticlehq/react';
@@ -309,7 +318,7 @@ export default defineConfig({
 });
 ```
 
-> **Next.js:** verified on **Next.js 15 / React 19 (app router, SWC)**. For source-file mapping, use `@reticlehq/next` instead of the Babel plugin. It adds a **dev-only webpack pre-loader that keeps SWC** and stamps `data-reticle-source` so `reticle_inspect` returns `file:line` (e.g. `app/page.tsx:30`):
+> **Next.js:** verified on **Next.js 15 / React 19 (app router, SWC)**. For source-file mapping, use `@reticlehq/next` instead of the Babel plugin. It adds a **dev-only webpack pre-loader that keeps SWC** and stamps `data-reticle-source` so `reticle_look { action: "element" }` returns `file:line` (e.g. `app/page.tsx:30`):
 >
 > ```ts
 > // next.config.ts
@@ -336,7 +345,7 @@ export default defineConfig({
 
 > "List Reticle sessions."
 
-The agent calls `reticle_sessions` and should see your tab:
+The agent calls `reticle_session { action: "list" }` and should see your tab:
 
 ```jsonc
 { "sessions": [{ "sessionId": "my-app", "url": "http://localhost:3000/", "title": "…" }] }
@@ -348,7 +357,7 @@ If the list is empty, see [Troubleshooting](#troubleshooting).
 
 ## Step 5: Your first verification
 
-> `reticle init --flow "<what>"` drives this for you and saves the flow. This section is what it does, for when you want to do it yourself.
+> `reticle_verify { action: "explore", persona: "<what>" }` drives this for you and saves the flow. This section is what it does, for when you want to do it yourself.
 
 Now just talk to your agent in plain language. For example:
 
@@ -358,7 +367,7 @@ What the agent does under the hood:
 
 ```jsonc
 // finds the button it just added
-reticle_query({ by: "role", value: "button", name: "Refresh" })   // → ref e12
+reticle_look({ action: "find", by: "role", value: "button", name: "Refresh" })   // → ref e12
 
 // clicks it
 reticle_act({ ref: "e12", action: "click" })                       // → { since: 920 }
@@ -397,12 +406,12 @@ onSaved(() => reticle.signal('order:saved', { id, total }));
 
 > **Recommended:** instead of importing `reticle` into components, inject a `createReticleEmitter()` emitter and pair each commit with `commitAndSignal(...)` so the mutation↔signal can't drift. `reticle.signal` stays the primitive underneath. See [integration-patterns.md](integration-patterns.md).
 
-**3. `registerStore` so the agent reads state directly.** No need to broadcast a signal for every fact: expose the store and the agent reads it via `reticle_state`.
+**3. `registerStore` so the agent reads state directly.** No need to broadcast a signal for every fact: expose the store and the agent reads it via `reticle_look { action: "state" }`.
 
 ```ts
 import { registerStore } from '@reticlehq/react';
 registerStore('cart', useCart); // pass the store itself → auto STATE_CHANGE diffs
-// agent: reticle_state({ store: 'cart' })  → { stores: { cart: {...} } }
+// agent: reticle_look({ action: "state", store: 'cart' })  → { stores: { cart: {...} } }
 ```
 
 **4. `registerCapabilities` so a fresh agent learns the surface without reading source.**
@@ -429,7 +438,7 @@ registerCapabilities({
 
 Once the loop works, these turn ad-hoc runs into a maintained suite:
 
-- **[Flows, recorder & self-healing](flows.md)**: record a golden path once; Reticle saves it to a git-checked `.reticle/` flow anchored on testid+signal, replays it (with legible drift), and `reticle_flow_heal` repairs renamed anchors.
+- **[Flows, recorder & self-healing](flows.md)**: record a golden path once; Reticle saves it to a git-checked `.reticle/` flow anchored on testid+signal, replays it (with legible drift), and `reticle_verify { action: "heal" }` repairs renamed anchors.
 - **[Testing with `@reticlehq/test`](testing.md)** gives you declarative `reticleTest` specs you run headless / in CI; flows can _become_ the specs.
 - **[Human-in-the-loop control](human-control.md)**: with `present: true`, pause / message / end the agent from the floating panel.
 - **[Integration patterns](integration-patterns.md)** covers the recommended zero-prod-bundle emit adapter, store-layer signals, and incremental adoption.
@@ -463,7 +472,7 @@ Everything below comes from the `@reticlehq/react` kit plus your framework's bui
 
 ## Troubleshooting
 
-**`reticle_sessions` is empty / "no browser session connected"**
+**`reticle_session { action: "list" }` is empty / "no browser session connected"**
 
 - Run **`reticle status`**. It shows whether the daemon is up and which tabs are connected (url, health, pending flagged bugs) at a glance. No connected sessions means the SDK isn't reaching the bridge.
 - Is your app actually running and open in a browser tab?
@@ -475,13 +484,13 @@ The errors Reticle returns to the agent now carry a `recovery` hint for this exa
 
 **The agent can't find an element**
 
-- Ask it to `reticle_snapshot({ mode: "interactive" })` to see what's actionable.
+- Ask it to `reticle_look({ action: "page", mode: "interactive" })` to see what's actionable.
 - Add a `data-testid` to the element for a stable handle.
 - Narrow with `scope` (a CSS selector or a ref).
 
 **Assertions are flaky on async UIs**
 
-- Use `timeout_ms` on `reticle_assert` / `reticle_wait_for`.
+- Use `timeout_ms` on `reticle_assert` / `reticle_assert { action: "wait" }`.
 - Pass the `since` cursor returned by `reticle_act` so only post-action events count.
 
 **Source file isn't resolving on React 19**
@@ -512,7 +521,7 @@ pnpm add @reticlehq/next
 
 ### What exactly does `reticle init` change in my project?
 
-Four files, and none of them are mysterious: a `.reticle.json` project config, your build config (the `reticle()` Vite plugin, or `withReticle` in `next.config`), a dev-only capabilities file at `src/reticle-dev.ts` (or `app/reticle-dev.tsx` on Next.js), and your agent's rule files. It then starts your dev server, opens the app and drives one flow, none of which changes your source: the dev server is left running for you afterwards, and the only file the drive may edit is the capabilities file, and only when your app registers none. It also registers the MCP server globally, which is a once-per-machine step rather than a per-project one. Run `npx @reticlehq/server init --dry-run` first to see the exact plan before anything is written.
+Four files, and none of them are mysterious: a `.reticle.json` project config, your build config (the `reticle()` Vite plugin, or `withReticle` in `next.config`), a dev-only capabilities file at `src/reticle-dev.ts` (or `app/reticle-dev.tsx` on Next.js), and your agent's rule files. It then starts your dev server and opens the app, neither of which changes your source: the dev server is left running for you afterwards. It also registers the MCP server globally, which is a once-per-machine step rather than a per-project one. Run `npx @reticlehq/server init --dry-run` first to see the exact plan before anything is written.
 
 ### Do I have to re-register the MCP server for every project?
 
@@ -528,7 +537,7 @@ Node 20 or newer.
 
 ### Do I need the React adapter?
 
-No, it is optional enrichment and the core works without it. What it adds is component identity, meaning `reticle_inspect` can say which React component rendered an element. Combined with a build plugin that stamps source, that is what turns a DOM node into `src/components/Login.tsx:81`, which is the difference between an agent knowing something failed and knowing which file to open.
+No, it is optional enrichment and the core works without it. What it adds is component identity, meaning `reticle_look { action: "element" }` can say which React component rendered an element. Combined with a build plugin that stamps source, that is what turns a DOM node into `src/components/Login.tsx:81`, which is the difference between an agent knowing something failed and knowing which file to open.
 
 ### Can I run several apps against Reticle at once?
 

package/docs/http-transport.md

@@ -161,4 +161,4 @@ The `202` comes back here; the tool list appears in the first shell.
 
 The transport carries the tools. It does not replace the rest of the setup. The app still has to be instrumented and connected, and `reticle_sessions` is still what tells you whether a session is there to drive. A verdict reached over HTTP is a verdict reached the usual way: only `verified: "yes"` is a pass.
 
-The endpoints, the handshake, the three status codes and the `202`-then-SSE shape are pinned by `packages/server/src/mcp-http-transport.test.ts`, which drives them over raw HTTP with no client library, so the contract this page describes fails the build if it changes.
+The endpoints, the handshake, the three status codes and the `202`-then-SSE shape are pinned by `server/src/mcp-http-transport.test.ts`, which drives them over raw HTTP with no client library, so the contract this page describes fails the build if it changes.

package/docs/index.mdx

@@ -12,9 +12,27 @@ Reticle reads the program from **inside** your running app. Network, state, cons
 
 It answers the only question that matters: did the change actually work? On React it also tells your agent which file to open.
 
-## Install it: paste this into your coding agent
+## Install it
 
-You do not install Reticle by hand, and neither does your agent: it runs one command that does the whole thing. Copy the block below into Claude Code, Cursor, Copilot, Codex, Windsurf, OpenCode, or any MCP agent, and let it wire its own workspace. It ends with the only definition of "installed" that counts: one real flow driven, one real verdict returned.
+Two commands. The first goes in a terminal, before you open your coding agent:
+
+<CodeGroup>
+
+```bash macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
+```
+
+```powershell Windows
+irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex
+```
+
+</CodeGroup>
+
+That registers the MCP server with every coding agent it can reach, so the `reticle_*` tools are there the next time you open one. Then, in your project, `npx @reticlehq/server init` wires the app. The [quickstart](/quickstart) walks both.
+
+### Or hand the whole thing to your agent
+
+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.
 
 ```text
 Reticle is the proof layer for AI coding agents. It runs a dev-only SDK inside my
@@ -30,14 +48,14 @@ silent 500.
 
 Install it now:
 
-  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init \
-    --flow "<pick the journey that matters in my app and name it here>"
+  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init
 
-That one command wires the project, starts the dev server, opens the app, waits
-for it to connect and drives that flow to a verdict. 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 a verdict exists, and that, not a config file, is what
-"installed" means. Only if it could not run at all, follow
+That one command wires the project, starts the dev server, opens the app and
+waits for it to connect. Do not walk it by hand: read what it prints, do anything
+it says is outstanding, and re-run it, which is safe. It exits non-zero until the
+app connects, and that connection, not a config file, is what "installed" means.
+Then prove a flow, which is a separate call:
+reticle_verify { action: "explore", persona: "<who does what>" }. Only if it could not run at all, follow
 https://docs.reticle.sh/install-manual.md.
 
 Afterwards, use it whenever you change any user-facing behaviour.
@@ -71,7 +89,7 @@ Afterwards, use it whenever you change any user-facing behaviour.
   <Card title="Install" icon="download" href="/install-agentic">
     Let your agent do it, or wire it by hand.
   </Card>
-  <Card title="Tools" icon="wrench" href="/tools-overview">
+  <Card title="Tools" icon="wrench" href="/tools/overview">
     Every tool, with a real request and a real response.
   </Card>
   <Card title="Run it in CI" icon="circle-check" href="/testing">

package/docs/install-agentic.mdx

@@ -1,16 +1,25 @@
 ---
 title: 'Agentic install: let the agent do it'
 sidebarTitle: Agentic install
-description: One command wires Reticle into your project, boots the app, proves a session connected and drives one flow to a verdict. What it changes, what you pass it, and how to read what it returns.
+description: One command wires Reticle into your project, boots the app and proves a session connected. What it changes, what you pass it, and how to read what it returns.
 icon: wand-magic-sparkles
 ---
 
-**Run `npx @reticlehq/server init` in your project root.** It registers the MCP server for every agent it finds, installs the SDK, wires your build config, writes the agent rule files, and prints a plan you can read. It is idempotent, so running it twice is safe.
+**Run `npx @reticlehq/server init` in your project root.** It installs the SDK, wires your build config, writes the agent rule files, boots the app, and prints a plan you can read. It is idempotent, so running it twice is safe.
 
 ```bash
 npx @reticlehq/server init
 ```
 
+<Note>
+  This is the PROJECT step. The machine step comes first and is one command in a terminal, `curl
+  -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh`, which
+  registers the MCP server with every agent it can reach so the tools are there when you open your
+  agent. `init` will register the server itself if nobody has, but doing it from inside an agent
+  that has already read its server list means the tools cannot appear until that agent restarts.
+  Terminal first, then open the agent, then `init`. See the [quickstart](/quickstart).
+</Note>
+
 The install is designed for the agent to run rather than you. The agent is about to be the primary user of this tool, so it may as well set up its own workspace.
 
 <Warning>
@@ -199,14 +208,13 @@ Three of these are answers only the caller has. `init` reads your repository; it
 
 | Flag | When you want it |
 | --- | --- |
-| `--flow "<what>"` | **Name the journey worth proving.** `init` 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>" }`), 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. |
 | `--license <key>` | Writes `RETICLE_LICENSE_KEY` to `.env` and keeps `.env` out of git. Do not do those two by hand. |
 | `--json` | One object on stdout: what was wired, what connected, the verdict, and an `agentTodo` array. For agents. |
 | `--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. |
 | `--no-open` | Do not open a browser: CI, a container, an SSH session, or a tab you already have. |
-| `--no-drive` | Stop once a session connects and leave the verdict to you. The only honest way to skip it. |
 | `--dry-run` | See the plan before anything is written. |
 | `--no-mcp` | Your MCP config is managed elsewhere (dotfiles, a team template). |
 | `--no-install` | You want to add the dependencies yourself, at your own versions. |

package/docs/install-manual.mdx

@@ -5,16 +5,32 @@ description: Wire Reticle by hand. Register the MCP server for your agent, add t
 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. `npx @reticlehq/server init` automates all of it, so use this page for the steps it marked `⚠`, or for an agent it does not know how to register.
+**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.
 
-You want both. Take them in that order.
+<Warning>
+  **You probably do not need this page.** Two commands do all of it:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh   # or: irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex
+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).
+
+</Warning>
+
+If you want the CLI without the script:
+
+```bash
+npm install -g @reticlehq/server
+npx @reticlehq/server setup mcp
+```
 
-<Tip>
-  You only need this page for steps [`reticle init`](/install-agentic) marked `⚠`, or for an agent
-  it doesn't register automatically. It handles Claude Code and Cursor on its own.
-</Tip>
+`reticle setup mcp` is exactly the registration half of the installer, and it prints any client it could not write for you.
 
 ## Part 1. Register the MCP server
 
@@ -159,7 +175,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "2.14"
+reticle-tauri = "3.2"
 ```
 
 ```rust

package/docs/instrumentation.mdx

@@ -119,7 +119,7 @@ registerCapabilities({
 });
 ```
 
-This is what [`reticle_capabilities`](/tools-tools-and-run) returns. The app telling an agent what it considers testable, before the agent has looked at a single element. It is the cheapest and most truthful first call on an unfamiliar codebase.
+This is what [`reticle_capabilities`](/tools/tools-and-run) returns. The app telling an agent what it considers testable, before the agent has looked at a single element. It is the cheapest and most truthful first call on an unfamiliar codebase.
 
 ## Why emitting failure signals pays off
 
@@ -196,7 +196,7 @@ That is the design working as intended. A tool that reports "pass" whenever it h
   accompanying `warning`.
 </Warning>
 
-Note the last field. When Reticle cannot tell what happened, it invites a bug report and calls the ambiguity its own defect rather than yours. If you hit an `unknown` you believe is wrong, that is worth [sending](/tools-session-and-feedback).
+Note the last field. When Reticle cannot tell what happened, it invites a bug report and calls the ambiguity its own defect rather than yours. If you hit an `unknown` you believe is wrong, that is worth [sending](/tools/session-and-feedback).
 
 ## Testids, briefly
 
@@ -229,7 +229,7 @@ You do not need to describe the whole app, and trying to is the slow path that g
 Then stop. Add more when a flow you actually replay needs it.
 
 <CardGroup cols={2}>
-  <Card title="Prove it" icon="circle-check" href="/tools-act-and-wait">
+  <Card title="Prove it" icon="circle-check" href="/tools/act-and-wait">
     Use your new signals as predicates and watch the grade climb.
   </Card>
   <Card title="Lock it in" icon="vial" href="/testing">

package/docs/local-registry.md

@@ -4,7 +4,7 @@ description: 'Exercise local, unpublished Reticle changes in a real external app
 icon: box
 ---
 
-To test unpublished `@reticlehq/*` changes in a real external app, publish the workspace to a local Verdaccio with `bash scripts/local-registry.sh`, then point that app's `.npmrc` at `http://localhost:4873/` for the `@reticlehq` scope. That is the whole procedure; the rest of this page is the detail.
+To test unpublished `@reticlehq/*` changes in a real external app, publish the workspace to a local Verdaccio with `bash scripts/local-registry.sh`, then point that app's `.npmrc` at `http://localhost:4873/` as the **default** registry, not scoped to `@reticlehq`, for the reason in step 2. That is the whole procedure; the rest of this page is the detail.
 
 > **For normal use, Reticle is on public npm.** Just `npm i -D @reticlehq/react @reticlehq/vite-plugin` (see [Getting Started](getting-started.md)). You only need this guide to test **local, unpublished changes** to the Reticle packages in a real external app before they ship.
 
@@ -37,12 +37,23 @@ For a browser app, install `@reticlehq/react` plus the build plugin for your fra
 
 ## 2. Point your app at the local registry
 
-In your app's project root, add an `.npmrc`. The scope is **`@reticlehq`**, not `@reticle`: a scope typo here does not error, it silently resolves the PUBLISHED packages from npm, so you measure shipped code and think you tested your branch. Everything outside that scope still comes from npm:
+In your app's project root, add an `.npmrc` pointing the **default** registry at Verdaccio. Verdaccio proxies npm for everything it does not hold, so the rest of your dependencies still resolve normally:
 
 ```ini
-@reticlehq:registry=http://localhost:4873/
+registry=http://localhost:4873/
 ```
 
+**A scope-only line does not work, and fails in a way that reads as a Reticle bug.** `@reticlehq/core` depends on **`open-verification`**, the protocol package, which is deliberately _unscoped_ because the protocol is not ours to namespace. With `@reticlehq:registry=…` npm sends that one request to npmjs and the install dies:
+
+```
+npm error 404 Not Found - GET https://registry.npmjs.org/open-verification
+npm error 404  The requested resource 'open-verification@3.1.0' could not be found
+```
+
+`reticle init` then correctly reports `⚠ Install dependencies` and skips wiring the build plugin, so the app is left un-instrumented by a registry mistake two steps earlier.
+
+There is no scoped form that fixes this: npm's per-registry setting is `@scope:registry`, and an unscoped package has no scope to key on. The default-registry line above is the only thing that works. Point it back at npm (`npm config delete registry`, or delete the `.npmrc`) when you are done testing.
+
 ## 3. Install + wire it up
 
 Install the SDK kit plus the Vite build plugin (source mapping + `connect()` injection):
@@ -118,7 +129,7 @@ With neither set, Reticle stays synthetic (zero extra deps) and says so via `inp
 ## Write replayable specs + git-checked flows
 
 - **Specs:** with `@reticlehq/test`, turn checks into `reticleTest("…", async t => { await t.act(...); await t.expectSignal(...) })`. They are signal/testid-bound, `reticle_clock` for determinism, `t.expectInputModeReal()` to skip-with-reason when real input isn't active. Run them headless via `reticle drive` (the same path CI uses).
-- **Flows:** record a flow once and Reticle writes it to a git-checked `.reticle/flows/<name>.json` (anchored on testid/signal); `reticle_flow_replay` re-resolves anchors at run time and reports **legible drift** with a nearest-match; `reticle_flow_heal` proposes/applies the rebind. A fresh agent reads `.reticle/contract.json` to learn your testable surface without grepping source.
+- **Flows:** record a flow once and Reticle writes it to a git-checked `.reticle/flows/<name>.json` (anchored on testid/signal); `reticle_flow_replay` re-resolves anchors at run time and reports **legible drift** with a nearest-match; `reticle_verify { action: "heal" }` proposes/applies the rebind. A fresh agent reads `.reticle/contract.json` to learn your testable surface without grepping source.
 
 ## When you're ready for real npm
 

package/docs/packages/babel-plugin.mdx

@@ -76,4 +76,4 @@ module.exports = {
 
 ## Why an attribute rather than a runtime lookup
 
-The stamp survives minification of everything else, costs nothing at runtime, and is readable from the DOM node itself. That is what lets [`reticle_inspect`](/tools-inspect) answer with a file and a line rather than a component name and a shrug.
+The stamp survives minification of everything else, costs nothing at runtime, and is readable from the DOM node itself. That is what lets [`reticle_inspect`](/tools/inspect) answer with a file and a line rather than a component name and a shrug.

package/docs/packages/browser.mdx

@@ -12,7 +12,7 @@ icon: window
 
 This is what makes Reticle different from a browser-automation tool. Because it runs _inside_ the app rather than driving it from outside, it can see a state mutation and a fired signal, not just a rendered pixel. It never imports a Node API; that boundary is enforced by the dependency graph.
 
-[`reticle_query`](/tools-query) speaks role, label and testid instead of CSS selectors through its own local accessibility engine: one engine computes both what elements are called and what they match by, so a reported identity always round-trips.
+[`reticle_query`](/tools/query) speaks role, label and testid instead of CSS selectors through its own local accessibility engine: one engine computes both what elements are called and what they match by, so a reported identity always round-trips.
 
 ## When you need it directly
 
@@ -90,7 +90,7 @@ Also exported: `getCapabilities()`, `hasCapabilities()`, `setCapabilitiesListene
 
 ## State adapters
 
-Register a store and its contents become readable through [`reticle_state`](/tools-state).
+Register a store and its contents become readable through [`reticle_state`](/tools/state).
 
 `registerStore`, `unregisterStore`, `storeNames`, `readStores`, `readStoresWithTruncation`.
 

package/docs/packages/core.mdx

@@ -6,13 +6,13 @@ icon: cube
 
 `@reticlehq/core` is the shared wire contract at the bottom of Reticle's dependency graph. Every message that crosses a boundary, browser to bridge, bridge to agent, is defined here as a named constant plus a zod schema. **You almost certainly do not need to install it**: it arrives with whatever Reticle package you did install, and you only reach for it directly if you are building your own integration against the wire format.
 
-**Apache 2.0. Depends on `zod` and nothing else.**
+**Apache 2.0. Depends on `zod` and on [`open-verification`](/packages/open-verification), the protocol whose vocabulary the contract is written in.**
 
 ## Why it exists
 
 Without one shared definition the browser and the server drift. One side renames a field, the other keeps reading the old one, and the failure is silent: a verdict that quietly stops carrying its evidence. Core makes that a type error instead.
 
-The single dependency is the point. Everything can depend on core without cycles, and nothing core does can drag a filesystem call into the browser bundle.
+The narrow dependency list is the point. `open-verification` itself depends on `zod` alone, so the graph stays acyclic: everything can depend on core, and nothing core does can drag a filesystem call into the browser bundle. This page said "depends on `zod` and nothing else" until v3 extracted the protocol and nobody updated the sentence.
 
 ## Do you install it?
 

package/docs/packages/engine.mdx

@@ -0,0 +1,40 @@
+---
+title: '@reticlehq/engine'
+description: 'The rules that decide a verdict, with no browser, daemon or CLI attached. Evidence in, verdict out.'
+icon: gavel
+---
+
+`@reticlehq/engine` is the part of Reticle that DECIDES. It reads what happened in a running app and says whether the declared consequence held. It has no browser, no daemon and no command line: evidence goes in, a verdict comes out.
+
+**Apache 2.0. Depends on [`@reticlehq/core`](/packages/core) and `zod`.**
+
+## Why it is a separate package
+
+It was nine thousand lines in the middle of the server, which meant the rules that decide a verdict could only be read, tested or trusted by running the whole daemon. Carving it out has three consequences that matter more than tidiness:
+
+- **It can be audited.** The verdict is the product, so the code that produces one is the code a sceptical reader most wants to see. It is Apache 2.0 for that reason, carved out of an otherwise source-available server.
+- **It can be reused.** Anything that has evidence in the protocol's shape can reach a verdict without Reticle in the loop.
+- **It cannot quietly depend on the daemon.** A rule that needs a browser to decide something is not a rule, it is a measurement, and the package boundary is what makes that confusion a compile error.
+
+## What is in it
+
+| Subpath | What it decides |
+| --- | --- |
+| `./question/*` | Predicates: what a claim means and whether the evidence satisfies it. |
+| `./evidence/*` | What a run proved, how strongly, and what it failed to observe. Includes the honesty grades a verdict is qualified by, and the learned guards a flow earns. |
+| `./disagreement/*` | Contradictions: two of the app's own channels saying different things. |
+| `./window/*` | What counts as "during" an action, and what is ambient noise. |
+
+Absence is treated as evidence with care, and that is most of the difficulty: a thing that did not happen is only meaningful if something was watching, so the engine distinguishes "it did not happen" from "nothing was looking".
+
+## Do you install it?
+
+Only if you are building your own verification tool on top of the protocol. It arrives as a dependency of `@reticlehq/server`.
+
+```bash
+npm install @reticlehq/engine
+```
+
+## Relationship to the protocol
+
+[`open-verification`](/packages/open-verification) states the rules; this package implements them for a real runtime and adds the machinery a real app needs, such as windowing and contradiction detection. `pnpm gate:conformance` is what keeps the two honest: it scores this implementation using the specification's own adjudicator rather than its own.

package/docs/packages/open-verification.mdx

@@ -0,0 +1,40 @@
+---
+title: 'open-verification'
+description: 'The Open Verification Protocol: the vocabulary a verdict is stated in, the rules that decide one, and the adjudicator that applies them.'
+icon: scale-balanced
+---
+
+`open-verification` is the specification Reticle implements, published as a package so it can be read, depended on and implemented by somebody else. It holds the vocabulary a verdict is stated in, the rules for deciding one, the `Realm` interface a runtime satisfies, and `adjudicate()`, which applies the rules to evidence.
+
+**Apache 2.0. Depends on `zod` and nothing else.** It is the floor of the dependency graph: [`@reticlehq/core`](/packages/core) sits on it, and everything else sits on core.
+
+## Why it is a separate package
+
+A verdict is the product. If the rules that decide one live inside the tool that also gathers the evidence, then "is this implementation correct?" has no answer that is not circular: scoring an implementation against its own rules makes every implementation conformant by construction.
+
+Separating them makes the question answerable. `pnpm gate:conformance` drives the specification's own scenarios against Reticle on a real browser and a real Electron shell, and every verdict is decided by the spec's `adjudicate` rather than by Reticle's kernel. A scenario Reticle answers wrongly is a failure Reticle cannot define away.
+
+It also means the part that DECIDES is auditable and reimplementable by anyone, which is why it is Apache 2.0 while the server is not.
+
+## What is in it
+
+| Export | What it is |
+| --- | --- |
+| Vocabulary | The named values a verdict and its evidence are made of: grades, refusal reasons, close conditions, channels. |
+| `Realm` | What a runtime must be able to do to be verifiable. A browser is one realm; a desktop shell is another. |
+| `adjudicate()` | Evidence in, verdict out, by the published rules. |
+| Vectors | Machine-readable fixtures under `vectors/`, so a second implementation can check itself. |
+
+`SPEC.md`, `CONFORMANCE.md`, `VERSIONING.md`, `GOVERNANCE.md` and `CHANGE-PROCESS.md` ship inside the package: the normative text travels with the code that implements it.
+
+## Do you install it?
+
+No, unless you are implementing the protocol yourself or writing something that reasons about verdicts without going through Reticle. It arrives as a dependency of `@reticlehq/core`.
+
+```bash
+npm install open-verification
+```
+
+## Versioning
+
+The protocol has its own compatibility rules, stated in `VERSIONING.md` inside the package. It is versioned in lockstep with the `@reticlehq/*` packages today; that is a release convenience, not a promise that the protocol changes whenever Reticle does.

package/docs/packages/tauri.mdx

@@ -21,7 +21,7 @@ Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')`
 
 ```toml
 [dependencies]
-reticle-tauri = "2.14"
+reticle-tauri = "3.2"
 ```
 
 Its own dependencies are `tauri = "2"` plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.

package/docs/packages.mdx

@@ -72,7 +72,7 @@ Those rules are why the browser SDK cannot accidentally pull in a filesystem cal
 
 **Why it exists:** this is the part that makes Reticle different from a browser-automation tool. Because it runs _inside_ the app rather than driving it from outside, it can see a state mutation and a fired signal, not just a rendered pixel.
 
-**Depends on:** `@reticlehq/core`. [`reticle_query`](/tools-query) speaks role, label and testid rather than CSS selectors through its own local accessibility engine, so what a snapshot reports is exactly what a query matches.
+**Depends on:** `@reticlehq/core`. [`reticle_query`](/tools/query) speaks role, label and testid rather than CSS selectors through its own local accessibility engine, so what a snapshot reports is exactly what a query matches.
 
 **Install it directly when** you are not on React, or you want `connect()` under your own control:
 
@@ -175,6 +175,26 @@ module.exports = withReticle({/* your config */});
 
 ---
 
+## open-verification
+
+**The specification, as a package.** The vocabulary a verification is described in (subject, channel, intent, claim, window, observation, evidence, coverage, verdict), plus `Realm`, the interface an implementation answers, and `adjudicate()`, the function that turns evidence into a verdict. It ships `SPEC.md`, a JSON Schema for every noun, and a conformance suite that scores an implementation against the rules.
+
+**Why it exists:** Reticle's rules about what may buy a green were real and were scattered. The independence rule lived in a channel table, the four verdict values in an enum, the blind-spot idea in a coverage type, and nothing said they were one contract that something other than Reticle could implement. You do not need this package to use Reticle. You need it to write something else that can be checked the same way, or to check what Reticle's verdicts actually mean.
+
+**Depends on:** `zod`, and nothing else. Deliberately: implementing the contract must not require installing the product.
+
+---
+
+## @reticlehq/engine
+
+**The rules that decide a verdict, with nothing attached.** Give it what happened in a running app (the clicks, the network calls, the state changes, the console) together with a statement about what should have followed, and it answers whether that statement held. No browser, no daemon, no command line, no storage.
+
+**Why it exists:** the decision and the machinery that feeds it are different jobs with different reasons to change. Carved out of `@reticlehq/server` so the part that judges can be read, tested and reused without starting anything.
+
+**Depends on:** `@reticlehq/core`, `zod`.
+
+---
+
 ## @reticlehq/test
 
 **The spec runner for CI.** `reticleTest` registers declarative specs and runs them against Reticle's tools directly, with no MCP or stdio in the loop.
@@ -219,7 +239,7 @@ A lint rule makes the signal layer self-enforcing, which is the only way a conve
 
 ```toml
 [dependencies]
-reticle-tauri = "2.14"
+reticle-tauri = "3.2"
 ```
 
 <Warning>