@reticlehq/server 2.7.0 → 2.8.0

package/docs/index.mdx

@@ -0,0 +1,101 @@
+---
+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.
+
+<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": { "network": "POST /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,215 @@
+---
+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
+---
+
+The install is one command, and it's 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.
+
+```bash
+npx @reticlehq/server init
+```
+
+## 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@2.8.0 @reticlehq/vite-plugin@2.8.0
+  [✓] 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 four, 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.
+
+| 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,194 @@
+---
+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
+---
+
+Two halves, and they are independent. **Your agent** needs the MCP server registered so the `reticle_*` tools exist. **Your app** needs the SDK so there is something for those tools to talk to. Do one and the tools appear but every call reports no session. Do the other 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-apps">
+  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 name the exact port 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>