@reticlehq/server 2.7.0 → 2.9.0

package/docs/human-control.md

@@ -1,39 +1,45 @@
-# Human-in-the-loop control — watch, steer, end the session
+---
+title: 'Human-in-the-loop control'
+description: 'Watch the agent’s live transcript, steer it mid-run, or end the session, all from inside the page itself.'
+icon: hand
+---
 
-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.
+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`.
+
+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.
 
 ## Watch the testing score climb (the live verdict tally)
 
-The panel header shows a running **✓N ✗M** tally — the verdict score, live. It's hidden until the first verdict lands, then climbs as the agent verifies: every `reticle_assert`, every replayed flow step, every pass/fail outcome bumps it, and the side that just grew **pops** so you _feel_ the green (or red) arrive. The cursor flies, the log streams the journey, and the score ticks up — you see the agent working and the result landing, not just a final checkmark. It persists when the session ends, so the last thing on screen is what this run actually verified. Green that's earned, not asserted.
+The panel header shows a running **✓N ✗M** tally: the verdict score, live. It's hidden until the first verdict lands, then climbs as the agent verifies: every `reticle_assert`, every replayed flow step, every pass/fail outcome bumps it, and the side that just grew **pops** so you _feel_ the green (or red) arrive. The cursor flies, the log streams the journey, and the score ticks up. You see the agent working and the result landing, not just a final checkmark. It persists when the session ends, so the last thing on screen is what this run actually verified. Green that's earned, not asserted.
 
 ## The constraint that shapes the design
 
-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:
+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` / `reticle_act_and_wait` / `reticle_act_sequence` **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.
-- **End** — the session is over; the panel shows "Session ended" and clears.
+- **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` / `reticle_act_and_wait` / `reticle_act_sequence` **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.
+- **End.** The session is over; the panel shows "Session ended" and clears.
 
 ## From the panel (the human)
 
 The floating panel (bottom-center, `present: true`) gives you:
 
-- **Pause / Resume** — one toggle. Paused turns the panel + page border **amber** with a `PAUSED` badge.
-- **Message box + send** — type a correction ("check the error state first"), hit Send (or Enter). Your message shows as a `🧑 you:` bubble in the transcript **and** is delivered to the agent.
-- **End** — ends the session: panel turns **emerald**, shows `Session ended · <summary>`, then fades away.
-- **Minimise (▾)** — collapse 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.
+- **Pause / Resume**: one toggle. Paused turns the panel + page border **amber** with a `PAUSED` badge.
+- **Message box + send.** Type a correction ("check the error state first"), hit Send (or Enter). Your message shows as a `🧑 you:` bubble in the transcript **and** is delivered to the agent.
+- **End** ends the session: panel turns **emerald**, shows `Session ended · <summary>`, then fades away.
+- **Minimise (▾)** collapses the panel to a bar that streams only the live line; click the bar to restore.
+- **Flag a bug**, the button in the corner. Toggle it on, click the element that looks wrong, type what's wrong (⌘/Ctrl+Enter to send, Esc to back out). Reticle pins a numbered marker, logs your flag in the panel, and hands the agent a structured mark.
 
-## Flag a bug — annotate the mistake where you see it
+## Flag a bug: annotate the mistake where you see it
 
-You don't have to describe a bug in prose. **Point at it.** The flag captures the element's re-resolvable anchor _and_ the source `file:line` (when the framework stamped one), so the agent fixes the exact element and code — not a guess. The loop:
+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"}` — note + element label + `source: { file, line }` + a ready-to-act `fix` hint. `reticle_sessions` also reports `pendingMarks` so the agent notices flags.
+2. **The agent** drains it with `reticle_session {action:"review"}`, getting note + element label + `source: { file, line }` + a ready-to-act `fix` hint. `reticle_sessions` 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.md#reticle_session {action:"review"}--drain-the-bugs-the-human-flagged-on-the-page) 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)
 
@@ -44,7 +50,7 @@ See [`reticle_session {action:"review"}` in the usage guide](usage.md#reticle_se
 | `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
 
@@ -54,7 +60,7 @@ Even without a pause, action/observe/assert results carry a `control` block when
 { since, dispatched, settled, result, control: { state: "active", guidance: ["looks good, keep going"] } }
 ```
 
-`guidance` is drained (delivered once), so a hint never repeats. When the session is clean and the inbox empty, no `control` field is added — zero overhead on the happy path.
+`guidance` is drained (delivered once), so a hint never repeats. When the session is clean and the inbox empty, no `control` field is added: zero overhead on the happy path.
 
 ## Tell your agent to honor it
 

package/docs/index.mdx

@@ -0,0 +1,143 @@
+---
+title: Verification for AI coding agents
+description: Reticle is the proof layer for AI coding agents. It verifies a running web app from the inside and returns a verdict with evidence, not a screenshot.
+mode: wide
+---
+
+Your agent says it works. Reticle checks.
+
+AI-written code has a specific failure mode: it looks right and silently doesn't work. The POST returns 200 and nothing persists. The button is wired to a handler that never fires. One click sends two requests. A screenshot shows all of this as a perfectly nice page.
+
+Reticle reads the program from **inside** your running app. Network, state, console, routing, framework internals.
+
+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
+
+You do not install Reticle by hand. Copy the block below into Claude Code, Cursor, Copilot, Codex, Windsurf, OpenCode, or any MCP agent, and let the agent wire its own workspace. 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
+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:
+
+  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init
+
+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.
+
+Afterwards, use it whenever you change any user-facing behaviour.
+```
+
+<Tip>
+  On Claude Code the plugin is shorter still: `/plugin marketplace add reticlehq/reticle` then
+  `/plugin install reticle@reticlehq`, which 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.
+</Card>
+
+<CardGroup cols={2}>
+  <Card title="Quickstart" icon="rocket" href="/quickstart">
+    Install, connect your agent, and get a real verdict. Five minutes.
+  </Card>
+  <Card title="Why Reticle" icon="lightbulb" href="/why-reticle">
+    The false-green problem, and the evidence that this fixes it.
+  </Card>
+</CardGroup>
+
+<CardGroup cols={3}>
+  <Card title="Desktop apps" icon="display" href="/desktop">
+    Electron and Tauri, including the IPC boundary nothing else can see.
+  </Card>
+  <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">
+    Every tool, with a real request and a real response.
+  </Card>
+  <Card title="Run it in CI" icon="circle-check" href="/testing">
+    Turn a session into a suite that blocks a bad merge.
+  </Card>
+</CardGroup>
+
+## What it looks like
+
+Your agent names the expected consequence _before_ it acts. That ordering is the whole trick. It is the difference between a check and a rationalisation.
+
+```json
+{
+  "ref": "e4",
+  "action": "click",
+  "until": { "kind": "net", "method": "POST", "urlContains": "/api/todos" }
+}
+```
+
+Reticle clicks, watches, and reports what actually happened. A verdict of `unknown` is not a pass; it means Reticle drove the app and could not tell. It says so rather than guessing, which is a rarer quality in software than it should be.
+
+## What makes it different
+
+<CardGroup cols={2}>
+  <Card title="No screenshots" icon="eye-slash">
+    No vision model, no pixel guessing. Reticle reads program truth, so the answer is deterministic
+    and the same every run.
+  </Card>
+  <Card title="Points at the source" icon="crosshairs">
+    On React, a DOM node maps back to `src/App.tsx:104`. Finding the bug is half the job; knowing
+    which file to open is the half that makes an agent useful.
+  </Card>
+  <Card title="Cheap to ask" icon="coins">
+    Narrow questions instead of dumping the whole accessibility tree into the context window every
+    single step.
+  </Card>
+  <Card title="Yours, locally" icon="lock">
+    Dev-only, localhost-only, offline. Your app's data never leaves the machine.
+  </Card>
+</CardGroup>
+
+## The evidence
+
+We publish the losses too. Reticle is not the right tool for driving a site you don't own, and it does not see pixels.
+
+![One honest test, two apps: Reticle has the highest Verification Efficiency on the controlled app and the lowest observation cost on the real dashboard](/images/bench-two-apps.png)
+
+<Card title="Read the full benchmark" icon="chart-column" href="/benchmarks">
+  How every number was measured, what it means, and where Reticle comes second.
+</Card>
+
+## Built for agents, readable by humans
+
+Reticle is used by a coding agent far more often than by a person, so these docs are built to be fetched by one. Every page has a plain-Markdown twin, and the whole site collapses into a single file when an agent wants the lot.
+
+<Card title="Docs for agents" icon="robot" href="/for-agents">
+  Markdown endpoints, `llms.txt`, and which page answers which question.
+</Card>
+
+## Build with us
+
+Reticle is early, and the sharp edges get filed down fastest when someone tells us where they are.
+
+<CardGroup cols={2}>
+  <Card title="Join the Discord" icon="discord" href="https://discord.gg/BwAbzv9ZRz">
+    Ask questions, show us what you are verifying, and tell us what broke. The roadmap moves on what
+    people actually hit.
+  </Card>
+  <Card title="Star the repo" icon="star" href="https://github.com/reticlehq/reticle">
+    It is the cheapest way to help, and it is genuinely how other people find this.
+  </Card>
+</CardGroup>
+
+Found a bug, or something you wished existed? `reticle_feedback` sends it in one call, from wherever you are. If Reticle could not tell you what happened, that is our defect and we want to know.

package/docs/install-agentic.mdx

@@ -0,0 +1,224 @@
+---
+title: 'Agentic install: let the agent do it'
+sidebarTitle: Agentic install
+description: Run npx @reticlehq/server init and let your coding agent wire Reticle into the project. What it changes, what it asks, and how to read its report.
+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.
+
+```bash
+npx @reticlehq/server init
+```
+
+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>
+  Always write the package scope: `npx @reticlehq/server <command>` is the CLI. Dropping the scope
+  and npx-ing the bare, unscoped `reticle` name fetches a different package published by somebody
+  else, which will not give you Reticle. Once `@reticlehq/server` is installed, `reticle` works as a
+  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?
+
+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.
+
+```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:
+
+  RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server@latest init
+
+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.
+
+Afterwards, use it whenever you change any user-facing behaviour.
+```
+
+<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
+  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.
+</Note>
+
+## See the plan before anything is written
+
+`--dry-run` prints exactly what would happen and touches nothing:
+
+```bash
+npx @reticlehq/server init --dry-run
+```
+
+On a fresh Vite + React + TypeScript app, that produced:
+
+```
+reticle init (dry run, no files written)
+  in /tmp/initdemo
+
+  [·] MCP server (Claude, global) → global (claude user scope)
+      reticle already registered (install once, used by every project)
+  [·] MCP server (Cursor, global) → /Users/you/.cursor/mcp.json
+      reticle already in Cursor global config
+  [⚠] MCP server (Codex CLI) → /Users/you/.codex/config.toml
+      add this to /Users/you/.codex/config.toml by hand:
+      [mcp_servers.reticle]
+      command = "npx"
+      args = ["@reticlehq/server", "mcp"]
+
+  [✓] Agent verification rule → CLAUDE.md
+      teach the agent to verify features with Reticle after building them
+  [✓] The /reticle command → .claude/commands/reticle.md
+      type /reticle to verify one flow in the browser
+  [✓] Install dependencies → package.json
+      npm i -D @reticlehq/react@<version> @reticlehq/vite-plugin@<version>
+  [✓] Reticle config → .reticle.json
+      write project config (framework + port)
+  [✓] Vite plugin → vite.config.ts
+      add reticle() to plugins (also injects connect())
+  [✓] Capabilities + store → src/reticle-dev.ts
+      no data-testid values yet; no state library detected
+```
+
+## Reading the marks
+
+There are five, and they mean different things. This is the part worth understanding, because a run full of green ticks can still leave you with a broken install. Two of the five ask something of you.
+
+| Mark | Meaning                                                     | Do you need to act? |
+| ---- | ----------------------------------------------------------- | ------------------- |
+| `✓`  | Done, or would be done                                      | No                  |
+| `·`  | Already in place from a previous run or another project     | No                  |
+| `–`  | Deliberately skipped, usually by a flag you passed          | No                  |
+| `⚠`  | Could not be done automatically, with the exact fix printed | **Yes**             |
+| `ℹ`  | 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.
+</Warning>
+
+That `ℹ` line is the one people skim past, so here it is in full:
+
+```
+  [ℹ] AGENT: finish the capabilities file → src/reticle-dev.ts
+      src/reticle-dev.ts was written but registers nothing, so `hasCapabilities` stays false
+      and reticle_state has nothing to read.
+```
+
+`init` wrote the file, but a brand-new Vite template has no testids and no state library, so there was nothing to register. Reticle tells you this instead of counting it as a win. See [Instrument your app](/instrumentation) for what to put in it.
+
+## What it actually changes
+
+Four files in your project, none of them mysterious.
+
+<AccordionGroup>
+  <Accordion title=".reticle.json (project config)">
+    ```json
+    {
+      "framework": "vite",
+      "projectId": "initdemo-308da9fe"
+    }
+    ```
+    The `projectId` is how Reticle scopes sessions to this project, so two apps running at once
+    don't get confused for each other.
+  </Accordion>
+
+  <Accordion title="vite.config.ts (the plugin)">
+    ```ts
+    import { defineConfig } from 'vite'
+    import react from '@vitejs/plugin-react'
+    import { reticle } from '@reticlehq/vite-plugin';
+
+    export default defineConfig({
+      plugins: [reticle(), react()],
+    })
+    ```
+    One import, one entry. The plugin stamps source locations onto your elements, which is what turns a DOM node into
+
+`src/components/Login.tsx:81`. It also injects `connect()` so you don't have to remember to.
+
+  </Accordion>
+
+  <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.
+    // Self-guards on import.meta.env.DEV, so it is a no-op in a production build.
+    import { registerCapabilities } from '@reticlehq/react';
+
+    if (import.meta.env.DEV) {
+      registerCapabilities({
+        testids: [], // none found; add data-testid to your key elements
+        signals: [], // names you pass to reticle.signal()
+        stores: [],  // the keys you registered above
+      });
+    }
+    ```
+    This is the file that decides how good your verdicts get. Empty, you still get DOM, network and
+    console. Filled in, your agent can check what the app *believes*, not just what it rendered.
+
+  </Accordion>
+
+  <Accordion title="CLAUDE.md and the /reticle command (agent rules)">
+    A rule telling your agent to verify features after building them, and a `/reticle` command that
+    drives one flow. Skipped entirely with `--no-mcp`, because rules for tools the agent can't reach
+    are just noise in the context window.
+  </Accordion>
+</AccordionGroup>
+
+## Flags
+
+```
+reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+              --app picks WHICH app in a monorepo, when several are found
+              --no-mcp skips MORE than the server registration: also the agent rule files
+              (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
+              only make sense once the tools are reachable.
+```
+
+| Flag           | When you want it                                                           |
+| -------------- | -------------------------------------------------------------------------- |
+| `--dry-run`    | Always, the first time.                                                    |
+| `--app <dir>`  | Monorepos. Without it, `init` finds several apps and asks which you meant. |
+| `--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.           |
+| `--port N`     | Something else already owns the default port.                              |
+
+## Then restart two things
+
+This trips up almost everyone, so `init` says it twice and so will we.
+
+**Restart your dev server.** The Vite plugin is new; the running process doesn't have it.
+
+**Restart your agent.** Claude Code, or reload the window in Cursor, or hit Start in `.vscode/mcp.json` in VS Code. Your agent read its 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. This is a once-per-machine annoyance: Reticle registers globally, so every later project starts with the tools already there.
+
+## Confirm it worked
+
+```bash
+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.
+
+<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.
+</Card>

package/docs/install-manual.mdx

@@ -0,0 +1,196 @@
+---
+title: 'Manual install: by hand, on purpose'
+sidebarTitle: Manual install
+description: Wire Reticle by hand. Register the MCP server for your agent, add the SDK, and connect it. Every step init automates, written out.
+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.
+
+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.
+
+<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>
+
+## Part 1. Register the MCP server
+
+There is no config file that all agents share. Each harness has its own path and its own schema, so write only the one you actually use.
+
+| Tool | File | Root key | `type` needed? |
+| --- | --- | --- | --- |
+| Claude Code | `~/.claude.json` (prefer the CLI below) | `mcpServers` | no |
+| 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 |
+| Zed | `~/.config/zed/settings.json` | `context_servers` | no |
+
+### Claude Code
+
+Register once, globally, and every project has it:
+
+```bash
+claude mcp add reticle -s user -- npx @reticlehq/server mcp
+```
+
+Confirm with `claude mcp list`. `reticle` should be there.
+
+If the `claude` CLI isn't available, merge one key into `mcpServers` in `~/.claude.json`. It is a large stateful file, so **merge, never rewrite**:
+
+```json
+{
+  "mcpServers": {
+    "reticle": {
+      "command": "npx",
+      "args": ["@reticlehq/server", "mcp"]
+    }
+  }
+}
+```
+
+### Cursor, VS Code, Windsurf
+
+Same shape, different file and root key. Cursor and Windsurf use `mcpServers`; VS Code uses `servers`:
+
+```json
+{
+  "mcpServers": {
+    "reticle": {
+      "command": "npx",
+      "args": ["@reticlehq/server", "mcp"]
+    }
+  }
+}
+```
+
+### Codex CLI
+
+TOML, in `.codex/config.toml`. This is the one `init` cannot write for you:
+
+```toml
+[mcp_servers.reticle]
+command = "npx"
+args = ["@reticlehq/server", "mcp"]
+```
+
+### OpenCode
+
+Note the flat command array and the required `type`:
+
+```json
+{
+  "mcp": {
+    "reticle": {
+      "type": "local",
+      "command": ["npx", "@reticlehq/server", "mcp"]
+    }
+  }
+}
+```
+
+<Warning>
+  **Restart your agent afterwards.** It read its server list at startup and nothing re-reads it.
+  `/mcp` manages servers that are already loaded, so it cannot discover a new one. Restart Claude
+  Code, reload the Cursor window, or press Start in `.vscode/mcp.json`.
+</Warning>
+
+## Part 2. Wire the SDK into your app
+
+### Vite
+
+```bash
+npm i -D @reticlehq/react @reticlehq/vite-plugin
+```
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { reticle } from '@reticlehq/vite-plugin';
+
+export default defineConfig({
+  plugins: [reticle(), react()],
+});
+```
+
+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.
+
+### Anything without the plugin
+
+If you're not on Vite or Next, call `connect()` yourself, guarded so it never reaches production:
+
+```ts
+import { reticle } from '@reticlehq/browser';
+
+if (import.meta.env.DEV) reticle.connect();
+```
+
+<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
+
+The frontend is identical to any web app. The CSP is not optional:
+
+```json
+{
+  "app": {
+    "security": {
+      "csp": "default-src 'self' ipc: http://ipc.localhost; connect-src 'self' ipc: http://ipc.localhost ws://localhost:4400 ws://127.0.0.1:4400"
+    }
+  }
+}
+```
+
+<Warning>
+  Tauri's default CSP blocks the bridge WebSocket **before it opens**. Your app runs perfectly and
+  simply never connects, with no error to go on. Keep `ipc: http://ipc.localhost` in `connect-src`,
+  Tauri v2 needs it for `invoke` itself. And drop the `ws://` entries from your release config.
+</Warning>
+
+Screenshots and headless mode need the Rust crate, which is versioned independently of the npm packages:
+
+```toml
+[dependencies]
+reticle-tauri = "0.1"
+```
+
+```rust
+tauri::Builder::default()
+    .invoke_handler(tauri::generate_handler![reticle_tauri::reticle_capture])
+    .on_page_load(reticle_tauri::on_page_load)
+```
+
+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">
+  Main-process and renderer wiring, IPC observation, and what differs from the web install.
+</Card>
+
+## Part 3. Prove it
+
+```bash
+npx @reticlehq/server status
+```
+
+A session in the output means the app connected. That. Not a tick in a checklist, is the install finished.
+
+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 })`.
+
+Still stuck? `npx @reticlehq/server doctor` checks Chromium, the daemon and the port in one command.
+
+<CardGroup cols={2}>
+  <Card title="Instrument your app" icon="wrench" href="/instrumentation">
+    Register stores, signals and testids so your verdicts get stronger than "the DOM changed".
+  </Card>
+  <Card title="Quickstart" icon="rocket" href="/quickstart">
+    Drive your first flow and read a real verdict.
+  </Card>
+</CardGroup>