@reticlehq/server 2.8.0 → 2.9.0

package/docs/faq.mdx

@@ -1,23 +1,29 @@
 ---
-title: FAQ: frequently asserted questions
+title: 'FAQ: frequently asserted questions'
 sidebarTitle: FAQ
 description: Does it run in production, does it need React, does it replace Playwright, and the other questions people actually ask.
 icon: circle-question
 ---
 
-## Does this run in production?
+Reticle is a dev-only, localhost-only verification layer an AI coding agent uses to prove a change actually worked in your running app. It does not run in production, it does not need React, and it does not replace Playwright. The rest of the questions people actually ask are below.
 
-No, and it is built so that it cannot easily be made to. Keep `reticle.connect()` behind a dev guard; the SDK is side-effect-free and tree-shakes out of production builds. The Vite plugin uses `apply: 'serve'`, which means it is not part of a production build at all.
+<AccordionGroup>
 
-## Do I have to change my components?
+<Accordion title="Does this run in production?">
+  No, and it is built so that it cannot easily be made to. Keep `reticle.connect()` behind a dev
+  guard; the SDK is side-effect-free and tree-shakes out of production builds. The Vite plugin uses
+  `apply: 'serve'`, which means it is not part of a production build at all.
+</Accordion>
 
-No, for look, act and observe. You get DOM, network, console and routing with zero changes.
+<Accordion title="Do I have to change my components?">
+  No, for look, act and observe. You get DOM, network, console and routing with zero changes.
 
 You get considerably better results by adding `data-testid` attributes and by [emitting signals](/instrumentation). That is the difference between a verdict that says "something appeared" and one that says "the app declared success".
 
-## Does it work without React?
+</Accordion>
 
-The core is framework-agnostic: DOM, network, routing, console, animations, snapshots and actions are gated against a vanilla TypeScript app.
+<Accordion title="Does it work without React?">
+  The core is framework-agnostic: DOM, network, routing, console, animations, snapshots and actions are gated against a vanilla TypeScript app.
 
 Support beyond that is uneven, and we would rather say so than let you find out:
 
@@ -27,62 +33,70 @@ Support beyond that is uneven, and we would rather say so than let you find out:
 | SvelteKit | Wired end to end. `init` writes the client hook, the plugin stamps `.svelte` source. But **no CI gate**, so unverified rather than supported |
 | Vue | A Pinia store adapter and nothing else. No detection, no `.vue` stamping, no gate |
 
-## Can it tell me whether my UI looks good?
+</Accordion>
 
-No. Reticle verifies behaviour, not aesthetics. Visual correctness and "does this feel right" remain a human job, or a visual-diff tool's.
+<Accordion title="Can it tell me whether my UI looks good?">
+  No. Reticle verifies behaviour, not aesthetics. Visual correctness and "does this feel right" remain a human job, or a visual-diff tool's.
 
 It does read design tokens. [`reticle_inspect`](/tools-inspect) reports whether a colour came from your theme or from someone's clipboard. But that is a consistency check, not taste.
 
-## Does it replace Playwright or Cypress?
+</Accordion>
 
-No. Those are your scripted CI suite. Reticle is for in-loop verification while an agent is coding, and for the flows you never got round to automating. They compose.
+<Accordion title="Does it replace Playwright or Cypress?">
+  No. Those are your scripted CI suite. Reticle is for in-loop verification while an agent is coding, and for the flows you never got round to automating. They compose.
 
-<Card title="The full comparison" icon="masks-theater" href="/vs-playwright-mcp">
-  Where Playwright is the right choice, stated plainly.
-</Card>
+  <Card title="The full comparison" icon="masks-theater" href="/vs-playwright-mcp">
+    Where Playwright is the right choice, stated plainly.
+  </Card>
+</Accordion>
 
-## How does it compare to Playwright MCP or Chrome DevTools MCP?
-
-Those drive a **separate** browser from the outside. Reticle verifies your **own running app** from the inside, with your real session and auth, and with assertions and regression as first-class.
+<Accordion title="How does it compare to Playwright MCP or Chrome DevTools MCP?">
+  Those drive a **separate** browser from the outside. Reticle verifies your **own running app** from the inside, with your real session and auth, and with assertions and regression as first-class.
 
 Measured on the same app: Reticle caught 10 of 10 injected bugs, Playwright MCP 9, Chrome DevTools MCP 8. DevTools MCP is about 7% cheaper per look on a simple page, and more expensive on a real one.
 
-## Can I run several apps or tabs at once?
+</Accordion>
 
-Yes. Each is a session. Pass `sessionId` to any tool when more than one is connected, and [`reticle_sessions`](/tools-sessions) lists them.
+<Accordion title="Can I run several apps or tabs at once?">
+  Yes. Each is a session. Pass `sessionId` to any tool when more than one is connected, and [`reticle_sessions`](/tools-sessions) lists them.
 
 Reticle scopes to your project and prefers the active tab, and it **refuses rather than guesses** when the choice is ambiguous. A refusal you can act on beats a silent pick of the wrong tab.
 
-## Why did I get `verified: "unknown"` on something that clearly worked?
+</Accordion>
 
-Because Reticle could not confirm it saw the whole story, and it will not call that a pass.
+<Accordion title="Why did I get `verified: \"unknown\"` on something that clearly worked?">
+  Because Reticle could not confirm it saw the whole story, and it will not call that a pass.
 
 The most common cause is a **throttled tab**: a backgrounded browser tab has its timers suppressed, which suppresses the quiescence detection used to decide the page has settled. Focus the tab, or drive a dedicated context.
 
 If you believe an `unknown` is wrong, report it. Reticle's own response says as much: "an unknown verdict is our defect, not yours".
 
-## Does my data leave the machine?
+</Accordion>
 
-Your app's data, no. Reticle is dev-only, localhost-only and offline. Credential-shaped values are redacted before they leave the page. You will see `[REDACTED]` in request bodies without configuring anything.
+<Accordion title="Does my data leave the machine?">
+  Your app's data, no. Reticle is dev-only, localhost-only and offline. Credential-shaped values are redacted before they leave the page. You will see `[REDACTED]` in request bodies without configuring anything.
 
 Anonymous usage telemetry is sent separately and can be turned off with `reticle telemetry disable`.
 
-<Card title="Exactly what is collected" icon="chart-line" href="/telemetry">
-  The complete list. If it is not on that page, it is not sent.
-</Card>
-
-## Is Reticle proven to make agents fix more bugs?
+  <Card title="Exactly what is collected" icon="chart-line" href="/telemetry">
+    The complete list. If it is not on that page, it is not sent.
+  </Card>
+</Accordion>
 
-No, and we are not going to claim it. A controlled test of fix-rate did **not** show an improvement. The benchmark was confounded in ways we can point at, and we consider the question open.
+<Accordion title="Is Reticle proven to make agents fix more bugs?">
+  No, and we are not going to claim it. A controlled test of fix-rate did **not** show an improvement. The benchmark was confounded in ways we can point at, and we consider the question open.
 
 What is measured is detection: 10 of 10 injected regressions caught, with zero false alarms on a known-good control, against 9 and 8 for the alternatives.
 
-## Why are there 48 tools but only 18 in my agent?
+</Accordion>
 
-MCP re-sends every advertised tool definition on every turn, so the tool list is rent rather than a one-time cost. Measured: 18 tools is about 5,400 tokens per turn; all 48 is about 33,600.
+<Accordion title="Why does my agent only see some of Reticle's tools?">
+  Because MCP re-sends every advertised tool definition on **every turn**, so the tool list is rent, not a one-time cost. Reticle advertises the verify loop directly and keeps the cold tail one call away.
 
-The other 30 are one call away via `reticle_tools` and `reticle_run`.
+Nothing is unreachable. `reticle_tools` lists every tool (pass `names: [...]` for full parameters) and `reticle_run({ tool, args })` invokes any of them by name. If you want the whole surface advertised directly, set `RETICLE_ADVERTISE_ALL_TOOLS=1` in the **daemon's** environment and restart it, which costs roughly seven times the per-turn schema tax and is meant for suites that call by name rather than for running agents.
 
-<Card title="The surface, explained" icon="wrench" href="/tools-overview">
-  Which 18, and why each earned its slot.
-</Card>
+  <Card title="The surface, explained" icon="wrench" href="/tools-overview">
+    Which tools are advertised directly, and why each earned its slot.
+  </Card>
+</Accordion>
+</AccordionGroup>

package/docs/fixtures.md

@@ -4,6 +4,8 @@ description: 'Why the apps in apps/ cannot answer the one question that matters
 icon: cubes
 ---
 
+The apps in `apps/` cannot tell you whether the install still works, because every one of them is already wired to Reticle. That question is answered in a separate repo, **[`reticle-fixtures`](https://github.com/reticlehq/reticle-fixtures)**, which keeps a pristine `clean` branch of real third-party apps and runs `node scripts/verify.mjs` to install into each one and assert a session actually connects.
+
 The apps in `apps/` are ours. We chose their defects, so passing against them says less than it looks like, and they are all wired to Reticle already, which makes them useless for the one question that matters before a release: **does the install still work on an app that has never seen Reticle?**
 
 That question is answered in a separate repo: **[`reticle-fixtures`](https://github.com/reticlehq/reticle-fixtures)**.

package/docs/flows.md

@@ -4,6 +4,8 @@ description: 'Record an interactive run once and replay it forever as a git-chec
 icon: repeat
 ---
 
+A **flow** is a recorded interactive run that Reticle stores as JSON under `.reticle/flows/` and replays forever with no AI model in the loop. Steps are anchored on **meaning** (a testid, a signal, or an auto-derived component + source location), never on a `eXX` ref or a coordinate, so they survive refactors; when an anchor does drift, `reticle_flow_replay` names what changed and `reticle_flow_heal` can rebind it.
+
 Reticle turns an interactive run into a **git-checked, replayable program** stored under `.reticle/`. Flows are anchored on **meaning** (testid + signal), not volatile element refs or coordinates, so they survive refactors, and when an anchor does drift, Reticle tells you _why_ and can repair it. This is what makes Reticle "the project's living test suite a human seeds and an agent maintains."
 
 > All of this is on-disk and human-readable, so flows are reviewed in PRs and diffed like code.
@@ -118,7 +120,7 @@ This is the feedback a human reviewer used to give, made machine-actionable, so
 ```jsonc
 reticle_flow_verify()
 // → { status: "fail", total: 4, passed: 3, failed: 1,
-//     summary: "3/4 flows pass — 1 needs attention: ship-deploy",
+//     summary: "3/4 flows pass, 1 needs attention: ship-deploy",
 //     failures: [{ flow: "ship-deploy", verdict: "drift",
 //                  whatChanged: "...", whereInSource: "src/...:NN", nextAction: "..." }] }
 ```

package/docs/for-agents.md

@@ -4,9 +4,9 @@ description: Fetch any page as plain Markdown, pull the whole site as one file,
 icon: robot
 ---
 
-These docs are built to be read by a program, not just a person. Nothing here needs an API key, a scraper, or an HTML parser. Every page has a plain-text form at a predictable URL.
+Append `.md` to any Reticle docs URL to get that page as plain Markdown, or fetch [`https://docs.reticle.sh/llms.txt`](https://docs.reticle.sh/llms.txt) for the index of every page. No API key, no scraper, no HTML parser.
 
-The site lives at **`https://docs.reticle.sh`**.
+The site lives at **`https://docs.reticle.sh`**. Everything below is a plain HTTP GET.
 
 ## Fetch one page
 
@@ -66,6 +66,6 @@ You rarely need more than one.
 | Get fluent in one screen | [Agent cheat sheet](/agent-cheatsheet) |
 | Look up a specific tool, flag, or workflow | [Complete usage guide](/usage) |
 | Understand what Reticle is doing under the hood | [Architecture](/architecture) |
-| Wire it into a desktop app | [Desktop apps](/desktop-apps) |
+| Wire it into a desktop app | [Desktop apps](/desktop) |
 | Make the checks repeatable in CI | [Specs for CI](/testing) |
 | Work on Reticle itself | [Gates](/gates), then [System map](/system-map) |

package/docs/frameworks.mdx

@@ -1,10 +1,13 @@
 ---
-title: Frameworks
-description: Which frameworks Reticle supports, which are wired but unverified, and the exact wiring for each one.
+title: 'Frameworks: proven, wired, and the difference'
+sidebarTitle: Frameworks
+description: Which frameworks Reticle supports, which are wired but unverified, and the exact wiring for each one. React, Next.js, Remix, Astro, SvelteKit, Nuxt, Vue and plain HTML.
 icon: layer-group
 ---
 
-The core of Reticle is framework-neutral. DOM, network, console, routing, animations and source mapping work anywhere JavaScript runs.
+**React + Vite, Next.js, Remix and Astro are fully supported, each with an example app driven to a verdict in CI. SvelteKit, Nuxt, Vue, Preact, Create React App and plain HTML are wired and documented but not gated, so treat them as plausible rather than proven.** The exact wiring for each is below.
+
+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. Its core is framework-neutral: DOM, network, console, routing, animations and source mapping work anywhere JavaScript runs.
 
 What varies is two things: how `connect()` gets into your app, and whether you get component identity on top.
 
@@ -14,7 +17,7 @@ What varies is two things: how `connect()` gets into your app, and whether you g
 
 We separate "we tested this" from "this should work". Four frameworks have an example app and a CI gate. The rest are wired and documented but nothing proves they still work.
 
-Two columns say different things and it is worth keeping them apart. **CI gate** `yes` means an example app is driven to a verdict on every change. **install only** means the install gate scaffolds that stack from scratch, runs `init`, boots it and waits for a session, so the setup is proven and the drive is not. Vue is there because 2.8.0 nearly shipped an installer that left a Vue app connecting 0% of the time, and the gate that exists for exactly that had only React scaffolds.
+Two columns say different things and it is worth keeping them apart. **CI gate** `yes` means an example app is driven to a verdict on every change. **install only** means the install gate scaffolds that stack from scratch, runs `init`, boots it and waits for a session, so the setup is proven and the drive is not. Vue is there because a release once nearly shipped an installer that left a Vue app connecting 0% of the time, and the gate that exists for exactly that had only React scaffolds.
 
 **Source pointer** is the `file:line` on a verdict. It needs the build plugin to stamp the source, which it does for JSX and, separately, for Svelte components. Vue single-file components are neither, so a Vue app gets every other signal and no `source` field. Measured, not assumed: a Svelte counter returns `src/lib/Counter.svelte:5` and the same drive on Vue returns none.
 
@@ -70,9 +73,7 @@ npm i -D @reticlehq/react @reticlehq/next
 ```js
 const { withReticle } = require('@reticlehq/next');
 
-module.exports = withReticle({
-  /* your config */
-});
+module.exports = withReticle({/* your config */});
 ```
 
 <Note>
@@ -194,6 +195,44 @@ Electron and Tauri invert the direction: your app dials the daemon, and there is
 
 Angular and Solid appear in dependency detection but have no wiring, no adapter and no gate. The sensor may work if you call `connect()` yourself. Nothing proves it, so we are not going to list them as supported.
 
+## Frequently asked questions
+
+<AccordionGroup>
+  <Accordion title="Does Reticle work with Next.js?">
+    Yes, and it keeps SWC. Install `@reticlehq/react` and `@reticlehq/next`, then wrap your config
+    with `withReticle`. There is no Babel migration. Next.js has an example app and a CI gate, so it
+    is supported rather than merely wired, and you get component identity and `file:line` source
+    pointers.
+  </Accordion>
+
+<Accordion title="Does Reticle work with Vue?">
+  Partly, and the limit is specific. Install `@reticlehq/browser` rather than the React kit, and you
+  get DOM, network, console, routing, actions and Pinia state. What you do not get is a `source`
+  field: source stamping covers JSX and Svelte components, and a Vue single-file component is
+  neither. The install path is covered by a gate; the drive is not.
+</Accordion>
+
+<Accordion title="Which framework should I pick if I want the strongest verdicts?">
+  React on Vite. It is the shortest install, and it is the only combination that gives you all three
+  of component identity, `file:line` source pointers and a CI-gated example app. If you are already
+  on Next.js, Remix or Astro, you get the same guarantees.
+</Accordion>
+
+<Accordion title="My framework is not listed at all. Will it work?">
+  Probably, with one line. `@reticlehq/browser` is the framework-neutral sensor: call
+  `reticle.connect()` behind a dev guard anywhere your app boots, and you get DOM, network, console
+  and routing. What you lose is component identity and, unless a build plugin stamps your source,
+  the `file:line` pointer. If it does not register a session, that is a bug worth reporting.
+</Accordion>
+
+  <Accordion title="What does 'wired, unverified' actually mean for me?">
+    The recipe on this page was written from a real integration and is expected to work, but no app
+    in CI exercises it, so nothing will tell us when it breaks. If you depend on one of these, the
+    useful thing you can do is report it when it stops working, since that is the only signal there
+    is.
+  </Accordion>
+</AccordionGroup>
+
 <Card title="Something missing?" icon="comments" href="/tools-session-and-feedback">
   A framework you need is a `gap` report. It is the signal that decides what gets built.
 </Card>

package/docs/gate-plan.md

@@ -4,6 +4,8 @@ description: 'What has to be true before a PR merges and before a release ships,
 icon: list-check
 ---
 
+Two gates, not one: a **merge gate** that answers "does this PR break anything" and runs on every PR in minutes, and a **release gate** that answers "does this version work in the clients people use" and runs on a release candidate over hours. Phases 0, 1, 2 and 4 are built; Phase 3 (the client matrix) is blocked on `init` learning each client, and Tier 2 is blocked on a token that cannot be created from inside this repo.
+
 > What has to be true before a PR merges and before a release ships, why each piece exists, and what is built so far. Derived from [`system-map.md`](./system-map.md); the harness rules every tier obeys are in [`harness-rules.md`](../apps/e2e/harness-rules.md).
 
 ## Two gates, not one
@@ -76,12 +78,12 @@ Nothing below is trustworthy until a gate result can be distinguished from a gat
 
 ### Phase 3: the client matrix
 
-**Blocked on `init` learning each client.** Today only Claude Code (`claude mcp add`) and Cursor (`~/.cursor/mcp.json`) are first-class; everything else gets a printed JSON snippet, so a `v2.5.0-<client>` artifact would measure the contributor's copy-paste rather than the product.
+**Blocked on `init` learning each client.** Today only Claude Code (`claude mcp add`) and Cursor (`~/.cursor/mcp.json`) are first-class; everything else gets a printed JSON snippet, so a per-client release artifact would measure the contributor's copy-paste rather than the product.
 
 - [x] **`init` support per client**: `init/mcp-clients.ts` registers Reticle with **seven** clients, not two. Every path and shape was read from that client's own documentation rather than recalled: Cursor/Windsurf/Gemini share `mcpServers`, VS Code uses `servers`, OpenCode uses `mcp` with the command as an **array**, Codex is TOML. A single "write mcp.json" assuming the Cursor shape produces a file three of them ignore: an install that reports success and registers nothing.
   - Detection is conservative and one-directional: we write into a config a client **already has**, never creating `~/.gemini` or `~/.codeium` for somebody who does not use them.
   - Codex is deliberately not auto-written. Editing TOML without a parser risks every _other_ server in the user's file; it returns MANUAL with an exact block.
-- [x] **Per-client compat script**: `apps/e2e/client-compat.mjs`. Extracts the command from the config **exactly the way that client would**, runs it, and speaks MCP to it. 7/7 clients, 23 assertions, each advertising 18 tools.
+- [x] **Per-client compat script**: `apps/e2e/client-compat.mjs`. Extracts the command from the config **exactly the way that client would**, runs it, and speaks MCP to it. 7/7 clients, 23 assertions, each advertising the default surface (the count is asserted in `surface-sizes.test.ts`, never restated here).
   - It proves only the half a machine can prove, and the verdict is named `runnable-unverified` so the distinction survives into the matrix. Whether the client _reads_ that path needs the real client, which is the submitted half.
 - [x] **Submission flow**: `apps/e2e/matrix.mjs --validate`, run by CI's `matrix-records` job on every PR. The validator refuses what cannot be acted on: `works` without `checks.toolsVisible` (the self-report the flow exists to replace), `broken` without the client's verbatim error, or any record with no host or version. Its self-check runs first, because a validator that has never refused anything is not a validator. Contributor guide in [`docs/matrix/README.md`](./matrix/README.md).
 - [x] **Generated `MATRIX.md`**: built from submitted records, prettier-ignored because a generated file that fails `format:check` teaches people to skip the gate. **The current honest state is seven clients and ZERO ticks**: `◐` means a runnable entry was written where the client documents it and _nobody has run that client_, and the generated legend says so rather than rounding `◐` up to `✅`.

package/docs/gates.md

@@ -4,6 +4,8 @@ description: 'I changed some files. Which command do I run before I push?'
 icon: shield-check
 ---
 
+If you changed anything at all, run `pnpm format:check && pnpm lint && pnpm typecheck && pnpm test:unit` (about two minutes). If you also touched the tool surface, install, desktop or Rust, section 1 below names the one extra command your change needs. CI runs everything regardless, so routing costs you a slower red, never a missed one.
+
 > **One question this file answers:** _I changed some files. Which command do I run?_
 >
 > The _why_ behind the gate design (tiers, the merge-gate/release-gate split, what is still unbuilt) lives in [`gate-plan.md`](./gate-plan.md). This file is the routing table.
@@ -19,11 +21,11 @@ Every gate below was executed end to end against `main` on **2026-08-12** (macOS
 | `pnpm build` | ✅ | ~40s |
 | `pnpm lint` (+ both guard self-tests) | ✅ | ~15s |
 | `pnpm typecheck` | ✅ | ~10s |
-| `pnpm test:unit` | ✅ 4,315 tests / 461 files across 8 packages | ~45s |
+| `pnpm test:unit` | ✅ 5,725 tests / 613 files across 8 packages | ~45s |
 | `pnpm format:check` | ✅ | ~10s |
 | `pnpm test:integration` | ✅ 12/12 | 17s |
-| `pnpm test:e2e` | ✅ 32/32 specs + soak 60/60 answered | **490s** |
-| `pnpm test:e2e:desktop` | ✅ 2/2 (Electron 20, Tauri 14) | 58s |
+| `pnpm test:e2e` | ✅ 33/33 specs + soak 60/60 answered | **490s** |
+| `pnpm test:e2e:desktop` | ✅ 2/2 (Electron 20, Tauri 17) | 58s |
 | `node apps/e2e/soak.mjs --self-check` | ✅ | `<1s` |
 | `node apps/e2e/matrix.mjs --self-check` | ✅ | `<1s` |
 | `pnpm matrix:compat --only cursor` | ✅ 4/4 | ~10s |
@@ -41,7 +43,7 @@ Find the row that matches what you changed. Run its commands. That is the whole
 
 | You changed | Run | Cost |
 | --- | --- | --- |
-| **Anything at all** | `pnpm lint && pnpm typecheck && pnpm test:unit` | ~2 min |
+| **Anything at all** | `pnpm format:check && pnpm lint && pnpm typecheck && pnpm test:unit` | ~2 min |
 | The tool surface, the wire contract (`packages/core`), or an observer | ↑ **and** `pnpm test:e2e` | +~8 min |
 | `reticle init`, `@reticlehq/vite-plugin`, `@reticlehq/next`, `@reticlehq/babel-plugin`, anything a user runs before their first session | ↑ **and** `pnpm gate:install` | +~15 min |
 | `@reticlehq/electron`, `packages/tauri`, the IPC observer, desktop capture | ↑ **and** `pnpm test:e2e:desktop` | +~3 min |
@@ -65,7 +67,7 @@ Each gate exists because the ones above it are blind to something. That blindnes
 | **Unit** | `pnpm test:unit` | 4,315 tests, per-package, no browser | anything crossing a package boundary at runtime | `verify` |
 | **Format** | `pnpm format:check` | Prettier | n/a | `verify` |
 | **Integration** | `pnpm test:integration` | real headless Chromium: browser pool, crash isolation, framework adapters, `withReticle` | the MCP surface, the daemon | `e2e` |
-| **Web e2e battery** | `pnpm test:e2e` | 30 specs against 3 booted servers and a real browser (the tool surface, the daemon lifecycle, transport faults, telemetry, trace shape), plus the soak | desktop runtimes; the install | `e2e` |
+| **Web e2e battery** | `pnpm test:e2e` | 32 specs against 3 booted servers and a real browser (the tool surface, the daemon lifecycle, transport faults, telemetry, trace shape), plus the soak | desktop runtimes; the install | `e2e` |
 | **Desktop battery** | `pnpm test:e2e:desktop` | a real Electron main process and a **packaged** Tauri binary, driven headless | web-only paths | `desktop-e2e` |
 | **Install gate** | `pnpm gate:install` | scaffolds 3 pristine apps, publishes this checkout to a local Verdaccio, lets `init` install itself, boots each app in a real browser, polls for a session | install _complexity_; see [`fixtures.md`](./fixtures.md) | `install-gate` |
 | **Matrix records** | `pnpm matrix:validate` | every submitted client-compat record is well-formed | whether the client actually works | `matrix-records` |

package/docs/getting-started.md

@@ -4,6 +4,8 @@ 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` in your project root, restart your dev server, restart your coding agent, then open your app in a browser and ask the agent to drive a flow.** 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.
 >
 > This page is the long-form walkthrough: the same ground, more slowly, plus per-framework wiring, multi-app setups and prerelease notes. Start here if you want the whole picture in one file rather than the fast route.
@@ -50,7 +52,7 @@ Everything is **dev-only** and **localhost-only**. It's tree-shaken out of produ
 
 ## Prerequisites
 
-- Node 18+ and a package manager (npm/pnpm/yarn).
+- Node 20 or newer, and a package manager (npm/pnpm/yarn).
 - A coding agent that speaks MCP: Claude Code, Cursor, Windsurf, Claude Desktop, etc.
 - A web app you run locally in dev (any framework; React gets the richest features).
 
@@ -74,7 +76,7 @@ It detects your framework, package manager, and React version, then:
 
 The bridge + MCP server is a single process that serves all your projects, so it's registered at **user scope**, not in a per-project `.mcp.json`. Only the SDK (the `reticle()` plugin / connect call) is added per project.
 
-Re-running is safe (already-registered/already-patched steps are skipped). Preview without writing via `npx @reticlehq/server init --dry-run`. Flags: `--port N`, `--no-mcp`, `--no-install`, `--yes`.
+Re-running is safe (already-registered/already-patched steps are skipped). Preview without writing via `npx @reticlehq/server init --dry-run`. Flags: `--dry-run`, `--port N`, `--no-mcp`, `--no-install`, `--app <dir>`.
 
 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.
 
@@ -129,7 +131,7 @@ import react from '@vitejs/plugin-react';
 import { reticle } from '@reticlehq/vite-plugin';
 
 export default defineConfig({
-  plugins: [react(), reticle()],
+  plugins: [reticle(), react()],
 });
 ```
 
@@ -140,7 +142,7 @@ This injects `reticle.connect()` for you _and_ handles React 19 source mapping (
 
 In your entry file (`src/main.tsx`), call `connect()` in dev only:
 
-```ts
+```tsx
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 import { reticle, SESSION_AUTO } from '@reticlehq/react';
@@ -259,7 +261,7 @@ reticle.connect({ session: SESSION_AUTO, url: 'ws://localhost:4401/reticle' });
 
 ```ts
 // project-b/vite.config.ts
-plugins: [react(), reticle({ port: 4401 })],
+plugins: [reticle({ port: 4401 }), react()],
 ```
 
 Either way, the rule is the same: **the app's bridge port must equal the daemon's `RETICLE_PORT`**, and it's the Reticle bridge port, never your dev-server port. Project A stays on the default `4400`, project B on `4401`; they never touch each other. (A port that is already in use now fails fast with a clear error instead of hanging, so a misconfiguration is obvious.)
@@ -291,14 +293,17 @@ 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`):
 >
-> ```js
-> // next.config.mjs
-> import reticleNext from '@reticlehq/next';
-> /** @type {import('next').NextConfig} */
-> const nextConfig = {};
-> export default reticleNext.withReticle(nextConfig); // no-op in production
+> ```ts
+> // next.config.ts
+> import { withReticle } from '@reticlehq/next';
+> import type { NextConfig } from 'next';
+>
+> const nextConfig: NextConfig = {};
+> export default withReticle(nextConfig); // no-op in production
 > ```
 >
+> This is exactly what `reticle init` writes. `@reticlehq/next` is CommonJS, so a default import (`import reticleNext from '@reticlehq/next'` then `reticleNext.withReticle(...)`) and a CJS `const { withReticle } = require('@reticlehq/next')` both work too, if your config is `.mjs` or `.js`.
+>
 > Component identity works with or without it (Next's internal wrappers are filtered out so you see your components, e.g. just `Page`).
 
 ---
@@ -430,7 +435,7 @@ Everything below comes from the `@reticlehq/react` kit plus your framework's bui
 
 **It is still unverified.** There is no SvelteKit app in `apps/` and no CI gate for one, so nothing would tell us when this breaks; `reticle init` says so out loud in its plan. React, Next.js, Remix and Astro each have an app and a gate. Treat SvelteKit as wired and plausible, not as supported.
 
-**Vue is not supported.** The SDK is framework-agnostic so `connect()` may work, and `piniaStore` will read a Pinia store, but there is no detection, no `.vue` source stamping and no CI gate.
+**Vue is install-gated, drive-unverified.** `init` detects a Vue app (as a Vite app with Vue as the UI library) and the install gate scaffolds one from scratch, runs `init`, boots it and waits for a session, so the setup is proven. What is not proven is the drive: there is no Vue example app in CI. `piniaStore` reads a Pinia store, and everything the framework-neutral core provides works. What you do not get is a `source` field, because source stamping covers JSX and Svelte components and a `.vue` single-file component is neither. See [Frameworks](/frameworks) for the full status table.
 
 ---
 
@@ -478,3 +483,39 @@ npm install @reticlehq/next --legacy-peer-deps
 # or use pnpm, whose peer resolution does not hard-fail here
 pnpm add @reticlehq/next
 ```
+
+---
+
+## Frequently asked questions
+
+### What exactly does `reticle init` change in my project?
+
+Four things, 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 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?
+
+No. The bridge and MCP server are a single process serving all your projects, so `init` registers it at user scope. Every later project starts with the tools already there. Only the SDK wiring is per project.
+
+### Why do the Reticle tools not appear after installing?
+
+Because your agent read its MCP server list at startup, before Reticle existed, and no slash command re-reads it. Restart the agent process: quit and reopen Claude Code, reload the window in Cursor, or press Start in `.vscode/mcp.json` in VS Code. `/mcp` only manages servers that are already loaded, so it cannot discover a new one.
+
+### Which Node version do I need?
+
+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.
+
+### Can I run several apps against Reticle at once?
+
+Yes, as long as each connection has a unique session id, which `SESSION_AUTO` gives you automatically. Tool calls target the focused or most recently active app, or you can pass an explicit `sessionId`. If you want two projects fully isolated, give each its own bridge port and set the same port in both the MCP server config and the app's connection.
+
+### Will Reticle end up in my production bundle?
+
+No. Keep `connect()` behind a dev guard (`import.meta.env.DEV` or a `NODE_ENV` check); the packages are side-effect free and tree-shake out when unused. The Vite plugin uses `apply: 'serve'`, so it is dropped from `vite build` entirely. As a backstop, `connect()` also self-disables when the build reports `NODE_ENV=production`.
+
+### Why is my install failing with `ERESOLVE`?
+
+You are almost certainly on a Next.js canary or a React RC. That is npm's semver rule for prereleases, not a Reticle restriction. Install with `--legacy-peer-deps`, or use pnpm, whose peer resolution does not hard-fail here. See [Installing alongside a Next.js or React prerelease](#installing-alongside-a-nextjs-or-react-prerelease) above.

package/docs/human-control.md

@@ -4,6 +4,8 @@ description: 'Watch the agent’s live transcript, steer it mid-run, or end the
 icon: hand
 ---
 
+With the presenter on (`reticle.connect({ present: true })`), the floating panel in your page lets you watch the agent's live transcript and steer it: **pause** it (its next action tool refuses and returns your guidance), **send** it a correction that rides back on its next tool result, or **end** the session. You can also point at a broken element with **Flag a bug** and hand the agent the element plus its source `file:line`.
+
 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)

package/docs/index.mdx

@@ -12,6 +12,44 @@ 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
+
+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.
@@ -41,7 +79,11 @@ It answers the only question that matters: did the change actually work? On Reac
 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" } }
+{
+  "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.

package/docs/install-agentic.mdx

@@ -1,16 +1,25 @@
 ---
-title: Agentic install: let the agent do it
+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.
+**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.
@@ -82,7 +91,7 @@ reticle init (dry run, no files written)
   [✓] 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
+      npm i -D @reticlehq/react@<version> @reticlehq/vite-plugin@<version>
   [✓] Reticle config → .reticle.json
       write project config (framework + port)
   [✓] Vite plugin → vite.config.ts
@@ -93,7 +102,7 @@ reticle init (dry run, no files written)
 
 ## 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.
+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? |
 | ---- | ----------------------------------------------------------- | ------------------- |