@reticlehq/server 2.4.0 → 2.6.0

package/docs/integration-patterns.md

@@ -0,0 +1,171 @@
+# Reticle Integration Patterns
+
+The basics in [Getting Started](getting-started.md) work with **zero app changes**. This doc is the _recommended_ shape for a real codebase: a minimal production footprint, a signal layer that can't silently drift, and an adoption path that starts paying off on day one — no rewrite required.
+
+- [1 — Start here: reuse what you already have](#1--start-here-reuse-what-you-already-have)
+- [2 — Inject the emitter (zero prod bundle)](#2--inject-the-emitter-zero-prod-bundle)
+- [3 — Emit signals from the store layer, not N call sites](#3--emit-signals-from-the-store-layer-not-n-call-sites)
+- [4 — Self-registering domains (`registerReticleDomain`)](#4--self-registering-domains-registerreticledomain)
+- [5 — Keep the signal layer from rotting (`@reticlehq/eslint-plugin`)](#5--keep-the-signal-layer-from-rotting-reticleeslint-plugin)
+- [6 — Limitation: un-scriptable tabs → `reticle drive`](#6--limitation-un-scriptable-tabs--reticle-drive)
+- [Checklist](#checklist)
+
+---
+
+## 1 — Start here: reuse what you already have
+
+Adoption is **free → cheap → targeted**. You don't instrument everything; you reuse what you have, then add the handful of facts the DOM can't express.
+
+**1. Reuse your existing `data-testid` (free).** If you already test with Playwright or Cypress, your testids work in Reticle unchanged — `reticle_query({ by: 'testid', value: 'checkout' })` matches them exactly. No new markup, no new code.
+
+**2. Advertise the surface from your existing constants (cheap).** You already keep a `TestIds` constant object for your E2E suite — pass it straight in. Now `reticle_capabilities()` tells a fresh agent your whole surface without reading source.
+
+```ts
+import { registerCapabilities } from '@reticlehq/browser';
+import { TestIds } from '../e2e/test-ids'; // the same constants your Playwright suite uses
+
+registerCapabilities({
+  testids: Object.values(TestIds),
+  signals: ['order:saved'],
+  stores: ['cart'],
+});
+```
+
+**3. Add signals only at the ~20 commit points that matter (targeted).** Emit `reticle.signal(name, data)` at the moments the DOM can't show — a save committed, a webhook arrived, an edit applied, an async generation finished. You instrument the off-DOM facts you'd otherwise eyeball, not every line.
+
+```ts
+import { reticle } from '@reticlehq/browser';
+onSaved(() => reticle.signal('order:saved', { id, total }));
+// agent: reticle_assert({ predicate: { kind: 'signal', name: 'order:saved', dataMatches: { id: '*' } } })
+```
+
+That's day-one usefulness with no rewrite. The rest of this doc is how to do steps 2–3 _well_ so the signal layer stays honest as the app grows.
+
+## 2 — Inject the emitter (zero prod bundle)
+
+The #1 objection: _"I don't want a test tool in my production bundle."_ The answer: components never import `@reticlehq/browser`. They depend on a tiny structural interface, `ReticleEmitter` (`{ signal, state }`), and the real emitter is injected once at the top. `createReticleEmitter()` returns an emitter that proxies to the connected `reticle` singleton and is a **safe no-op** until `reticle.connect()` runs — so nothing breaks in production or before connect, and **`@reticlehq/browser` stays out of the prod bundle.**
+
+```ts
+// app/emit.ts — the one place that touches @reticlehq/browser
+import { createReticleEmitter } from '@reticlehq/browser';
+export const emit = createReticleEmitter(); // no-op until reticle.connect()
+```
+
+```ts
+// any component — depends on the interface, not the SDK
+import { emit } from '../emit';
+function onSaved(id: string, total: number) {
+  emit.signal('order:saved', { id, total });
+}
+```
+
+The emitter re-checks the connection on every call, so you can create it at module load — before `reticle.connect()` — and it starts forwarding the moment Reticle connects. (See [getting-started Step 2](getting-started.md#step-2--embed-the-sdk-in-your-app) for where `reticle.connect()` goes.) This is the single highest-leverage decision; everything below assumes it.
+
+## 3 — Emit signals from the store layer, not N call sites
+
+The smell: every store mutation hand-emits a signal right after it, and over dozens of call sites the two **drift** — a new mutation path forgets the emit and the contract silently breaks. Drive the signal from where the state actually changes instead.
+
+**Pattern A — store middleware (sketch).** One audited map from action → signal lives next to the store, so _state changed ⇒ signal fired_ is structural, not a thing each call site remembers.
+
+```ts
+// store-with-reticle.ts — sketch: one audited transition map, not N call sites
+import { emit } from './emit';
+
+const signalFor: Record<string, (next: State) => readonly [string, Record<string, unknown>]> = {
+  reorderSections: (s) => ['section:reordered', { order: s.order }],
+  addSection: (s) => ['section:added', { count: s.sections.length }],
+};
+
+function dispatch(action: keyof typeof signalFor, run: () => State): void {
+  const next = run();
+  const make = signalFor[action];
+  if (make !== undefined) emit.signal(...make(next));
+}
+```
+
+**Pattern B — `commitAndSignal` (lighter).** When you don't want a middleware, pair the mutation and its signal in one call that can't drift. It runs `mutate()`, emits the signal exactly once, and returns the mutation's value.
+
+```ts
+import { commitAndSignal } from '@reticlehq/browser';
+import { emit } from '../emit';
+
+const next = commitAndSignal(
+  emit,
+  () => store.reorderSections(fromId, toId),
+  'section:reordered',
+  deriveOrder(store.getState()),
+);
+```
+
+If `mutate` throws, the mutation never happened — so **the signal is not emitted and the error propagates** unchanged.
+
+> **The documented exception:** genuinely view-level signals — render or async completions like `diff:shown` or `caption:generated`, which aren't store state — legitimately stay in your components. Only commit-point signals belong in the store layer.
+
+Pair this with store registration so the agent can _read_ state instead of you emitting a signal per fact: `registerStore('workspace', useWorkspace)`, then `reticle_state({ store: 'workspace' })`.
+
+## 4 — Self-registering domains (`registerReticleDomain`)
+
+Rather than maintaining one central flat-map of the whole testable surface (and remembering to wire each new area into it), co-locate one `reticle.ts` per domain that exports its `{ testids, signals, stores }` and self-registers. The capability registry assembles itself from every domain — later calls accumulate as a union, with no duplicates.
+
+```ts
+// features/sections/reticle.ts — co-locate a domain's testids + signals in one module
+import { registerReticleDomain } from '@reticlehq/browser';
+
+export const SectionTestIds = { list: 'section-list', add: 'section-add' } as const;
+export const SectionSignals = { reordered: 'section:reordered' } as const;
+
+registerReticleDomain({
+  testids: Object.values(SectionTestIds),
+  signals: Object.values(SectionSignals),
+  stores: ['workspace'],
+});
+```
+
+```ts
+// features/search/reticle.ts
+import { registerReticleDomain } from '@reticlehq/browser';
+registerReticleDomain({ testids: ['search-input'], signals: ['search:ran'] });
+```
+
+Importing both modules in dev makes `reticle_capabilities()` return the merged surface (`testids: ['section-list', 'section-add', 'search-input']`, `signals: ['section:reordered', 'search:ran']`, `stores: ['workspace']`). `registerReticleDomain` is a thin convenience over `registerCapabilities` — same merge-idempotent, HMR-safe semantics — so it composes with §1's "use your existing constants." (Named flows stay an explicit `registerCapabilities({ flows })` concern — their last-writer-wins semantics don't fit "accumulate from many domains.")
+
+## 5 — Keep the signal layer from rotting (`@reticlehq/eslint-plugin`)
+
+A signal layer silently rots: someone adds a mutation path and forgets the signal, and the agent's contract breaks with no error. The lint rule catches it at the only moment that's cheap — review.
+
+The rule **`reticle/require-signal-on-mutation`** flags a function that calls a configured store mutator but emits no signal in the same function. It is a **safe no-op until you tell it which calls mutate state** (`mutators`) and which call emits a signal (`signalCallee`, default `signal` / `reticleSignal`):
+
+```js
+// eslint.config.js (flat config)
+import reticle from '@reticlehq/eslint-plugin';
+
+export default [
+  {
+    plugins: { reticle },
+    rules: {
+      'reticle/require-signal-on-mutation': [
+        'warn',
+        { mutators: ['set', 'reorderSections', 'addSection'], signalCallee: 'signal' },
+      ],
+    },
+  },
+];
+```
+
+Or turn it on with the shipped preset (warns, with empty no-op defaults you then configure): `plugin.configs.recommended`. A function that calls a mutator and a signal together passes; a mutator with no signal reports `store mutation without a mapped Reticle signal`. The documented view-level exceptions from §3 simply don't list those view callees as `mutators`, so they never fire.
+
+## 6 — Limitation: un-scriptable tabs → `reticle drive`
+
+Reticle observes and drives a tab through the in-page SDK plus (optionally) CDP. It **cannot bring to front or recover a browser tab the OS won't let it script** — e.g. a backgrounded tab, or a non-default browser (Dia, etc.) reporting `hidden:true` / `throttled:true`.
+
+When that happens, `reticle_sessions` and every act/assert result carry a `session.recommendation` saying so. The escape hatch is **`reticle drive <url>`** (add `--headed` to watch) — Reticle launches and owns a guaranteed-scriptable browser. See [usage §18](usage.md#18-real-input-mode--native-hover--drag) for the full note.
+
+## Checklist
+
+- [ ] One `app/emit.ts` is the **only** module importing `@reticlehq/browser`; components import the emitter.
+- [ ] `reticle.connect()` is dev-gated; the prod bundle has no `@reticlehq/browser`.
+- [ ] Signals fire from the store layer (middleware or `commitAndSignal`); view-level exceptions are explicit.
+- [ ] Each domain self-registers via `registerReticleDomain`; `reticle_capabilities()` returns the full surface.
+- [ ] Existing Playwright/Cypress testids are reused, not duplicated.
+- [ ] `reticle/require-signal-on-mutation` is enabled with your `mutators` + `signalCallee`.
+- [ ] The team knows `reticle drive <url>` for un-scriptable tabs.

package/docs/local-registry.md

@@ -0,0 +1,126 @@
+# Test unpublished Reticle changes in a real app (local registry)
+
+> **For normal use, Reticle is on public npm** — just `npm i -D @reticlehq/react @reticlehq/vite-plugin` (see [Getting Started](getting-started.md)). You only need this guide to test **local, unpublished changes** to the Reticle packages in a real external app before they ship.
+
+Because the `@reticlehq/*` packages depend on each other via the workspace protocol, plain `npm pack` tarballs don't resolve cleanly. The reliable way to exercise your in-progress changes in a real app is a tiny **local registry** (Verdaccio) — the same path CI uses to validate a publish.
+
+## 1. Publish @reticlehq/\* to a local registry
+
+From the Reticle repo:
+
+```bash
+bash scripts/local-registry.sh
+```
+
+This starts a **fresh** Verdaccio on `http://localhost:4873`, creates a user/token, and publishes all `@reticlehq/*` packages there at the current workspace version:
+
+| Package | What you install it for |
+| --- | --- |
+| **`@reticlehq/react`** | **install this** — the browser SDK kit you embed (re-exports the browser sensor, so one install gives both `reticle` and `install`) |
+| `@reticlehq/vite-plugin` | dev-only source mapping + `connect()` injection (Vite) |
+| `@reticlehq/next` | Next.js build wrapper (`withReticle`) |
+| `@reticlehq/server` | the bridge + MCP server (your agent runs it, `npx @reticlehq/server mcp`) |
+| `@reticlehq/babel-plugin` | React 19 source stamping (Babel) |
+| `@reticlehq/test` | write declarative, signal-bound specs (`reticleTest`) |
+| `@reticlehq/eslint-plugin` | the `require-signal-on-mutation` lint rule |
+| `@reticlehq/core` | shared wire contract (pulled in automatically) |
+
+For a browser app, install `@reticlehq/react` plus the build plugin for your framework (`@reticlehq/vite-plugin` or `@reticlehq/next`); `@reticlehq/server` is what your agent runs. (Verified: an external `npm i @reticlehq/react` resolves its graph, including `@reticlehq/core`, and imports correctly.) Leave the registry running.
+
+> Note: pre-2.0 docs used a single `@reticlehq/core` umbrella package that re-exported everything; it's been split into the audience-scoped packages above.
+
+## 2. Point your app at the local registry
+
+In your app's project root, add an `.npmrc` (scopes only `@reticle` to the local registry; everything else still comes from npm):
+
+```ini
+@reticlehq:registry=http://localhost:4873/
+```
+
+## 3. Install + wire it up
+
+Install the SDK kit plus the Vite build plugin (source mapping + `connect()` injection):
+
+```bash
+npm i -D @reticlehq/react @reticlehq/vite-plugin
+# Next.js instead of Vite? npm i -D @reticlehq/react @reticlehq/next
+# optional: npm i -D @reticlehq/eslint-plugin   # require-signal-on-mutation lint rule
+```
+
+Then follow [Getting Started](getting-started.md): embed `reticle.connect()` (dev only) from `@reticlehq/react`, add the MCP server to your agent, and (React) `install()` the adapter from `@reticlehq/react`. For the fastest agent loop, also do [Step 6 — make your app agent-legible](getting-started.md) (testids, `reticle.signal`, `registerStore`, `registerCapabilities`) and the [integration patterns](integration-patterns.md) (`createReticleEmitter` for zero prod-bundle cost).
+
+> **Upgrading.** The packages are currently **1.2.0**; new tools land as minor bumps. `scripts/local-registry.sh` resets Verdaccio and republishes the current version, so pull the latest in your app explicitly — `npm install @reticlehq/react@latest`:
+>
+> ```bash
+> npm i -D @reticlehq/react@latest @reticlehq/vite-plugin@latest @reticlehq/eslint-plugin@latest
+> ```
+
+**Run the MCP server** from the local registry too — `npx @reticlehq/server` _is_ the server:
+
+```jsonc
+// .mcp.json — point npx at the local registry so it fetches @reticlehq/server from Verdaccio
+{
+  "mcpServers": {
+    "reticle": {
+      "command": "npx",
+      "args": ["--registry", "http://localhost:4873/", "@reticlehq/server", "mcp"],
+    },
+  },
+}
+```
+
+## Next.js specifics (verified on Next 15 / React 19)
+
+`next.config.mjs`:
+
+```js
+import reticleNext from '@reticlehq/next';
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+export default reticleNext.withReticle(nextConfig); // dev-only; keeps SWC; adds file:line mapping
+```
+
+Mount the SDK from a dev-only client component (see the Next.js section in [Getting Started](getting-started.md)).
+
+## Real input for hover/drag (optional)
+
+Synthetic events can't trigger native `onMouseEnter`/pointer state (hover menus, tooltips, pointer drag). Enable **real input** so the server drives genuine pointer input and `reticle_act` reports `inputMode:"real"`:
+
+- **Easiest — `reticle drive`:** Reticle launches its own scriptable, headless-capable browser at your app URL (no flags to juggle):
+
+  ```bash
+  npx --registry http://localhost:4873/ @reticlehq/server drive http://localhost:4310   # add --headed to watch
+  ```
+
+- **Or attach to your own browser:** launch it with `--remote-debugging-port=9222`, then point the MCP server at it via `env`:
+
+  ```jsonc
+  // .mcp.json
+  {
+    "mcpServers": {
+      "reticle": {
+        "command": "npx",
+        "args": ["--registry", "http://localhost:4873/", "@reticlehq/server", "mcp"],
+        "env": { "RETICLE_CDP_URL": "http://localhost:9222" },
+      },
+    },
+  }
+  ```
+
+With neither set, Reticle stays synthetic (zero extra deps) and says so via `inputMode`. See [usage §18](usage.md#18-real-input-mode--native-hover--drag).
+
+## Write replayable specs + git-checked flows
+
+- **Specs:** with `@reticlehq/test`, turn checks into `reticleTest("…", async t => { await t.act(...); await t.expectSignal(...) })` — signal/testid-bound, `reticle_clock` for determinism, `t.expectInputModeReal()` to skip-with-reason when real input isn't active. Run them headless via `reticle drive` (the same path CI uses).
+- **Flows:** record a flow once and Reticle writes it to a git-checked `.reticle/flows/<name>.json` (anchored on testid/signal); `reticle_flow_replay` re-resolves anchors at run time and reports **legible drift** with a nearest-match; `reticle_flow_heal` proposes/applies the rebind. A fresh agent reads `.reticle/contract.json` to learn your testable surface without grepping source.
+
+## When you're ready for real npm
+
+The same packages publish to public npm unchanged — `pnpm -r publish --access public` after `npm login`. The Verdaccio run above is a faithful rehearsal of that.
+
+## Cleanup
+
+```bash
+pkill -f verdaccio     # stop the local registry
+# remove the line from your app's .npmrc when you switch to published packages
+```

package/docs/matrix/2.5.0/claude-code-machine.json

@@ -0,0 +1,19 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "claude-code"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "snippet": true
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/codex-machine.json

@@ -0,0 +1,20 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "codex"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": false,
+    "snippet": true
+  },
+  "verdict": "manual-snippet",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/cursor-machine.json

@@ -0,0 +1,22 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "cursor"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": true,
+    "parses": true,
+    "initialize": true,
+    "tools": 17
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/gemini-machine.json

@@ -0,0 +1,22 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "gemini"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": true,
+    "parses": true,
+    "initialize": true,
+    "tools": 17
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/opencode-machine.json

@@ -0,0 +1,22 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "opencode"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": true,
+    "parses": true,
+    "initialize": true,
+    "tools": 17
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/vscode-machine.json

@@ -0,0 +1,22 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "vscode"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": true,
+    "parses": true,
+    "initialize": true,
+    "tools": 17
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/windsurf-machine.json

@@ -0,0 +1,22 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "windsurf"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": true,
+    "parses": true,
+    "initialize": true,
+    "tools": 17
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/MATRIX.md

@@ -0,0 +1,26 @@
+# Client matrix
+
+> Which MCP clients Reticle is known to work in, and on whose machine that was measured.
+> Generated by `node apps/e2e/matrix.mjs` — do not edit by hand.
+
+| | meaning |
+| --- | --- |
+| ✅ | a human ran the real client and the tools were usable |
+| ◐ | `init` wrote a runnable entry where the client documents it — **nobody has run that client** |
+| ✎ | `init` will not write this format (TOML); the user pastes a block |
+| ❌ | somebody ran it and it did not work — the most useful row here |
+
+**◐ is not a tick.** It means the half a machine can check passed. Only ✅ means somebody saw
+Reticle working in that client.
+
+## 2.5.0
+
+| client | verdict | tools | os | submitted by |
+| --- | --- | --- | --- | --- |
+| claude-code | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| codex | ✎ manual-snippet | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| cursor | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| gemini | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| opencode | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| vscode | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| windsurf | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |

package/docs/matrix/README.md

@@ -0,0 +1,59 @@
+# Submitting a client-matrix record
+
+[`MATRIX.md`](./MATRIX.md) says which MCP clients Reticle is known to work in. Right now most rows are **◐** — `init` writes a runnable entry where that client documents it, and **nobody has run that client**. Turning a ◐ into a ✅ takes about three minutes and is the single most useful thing an outside contributor can do for this project.
+
+You do not tell us it works. You **run one command, run your client, and submit what came out** — the same shape as [CNCF's Kubernetes conformance](https://github.com/cncf/k8s-conformance), and for the same reason: a claim nobody can trace back to a machine and a commit cannot gate anything.
+
+## 1. The machine half (no client needed)
+
+```bash
+pnpm build
+node apps/e2e/client-compat.mjs --only <client> --json /tmp/compat.json
+```
+
+That checks `init` writes a config where your client documents it, that it parses under **that client's own key**, and that the command inside it starts and advertises tools. It does **not** check that your client reads it — which is the whole reason step 2 exists.
+
+## 2. The human half (this is the part that matters)
+
+1. Run `npx @reticlehq/server init` in a real project.
+2. **Restart your client.** Every one of them reads MCP config at startup; this is the step people skip and then report a bug about.
+3. Ask it to list Reticle's tools. Note **how many** it lists.
+4. Kill the daemon (`lsof -nP -iTCP:4400 -sTCP:LISTEN -t | xargs kill`) and use a Reticle tool again. Does the client recover on its own, or does it need a manual reconnect?
+5. If anything failed, copy your client's error text **verbatim**. That sentence is worth more than the rest of the record put together — it is the only thing that says what your client actually thinks went wrong.
+
+## 3. Submit it
+
+Write `docs/matrix/<reticle-version>/<client>-<yourhandle>.json`:
+
+```json
+{
+  "reticle": { "version": "2.5.0", "commit": "abc1234" },
+  "client": { "id": "windsurf", "version": "1.2.3" },
+  "host": { "os": "darwin 25.5.0", "node": "v22.14.0" },
+  "checks": {
+    "registered": true,
+    "toolsVisible": 17,
+    "survivedDaemonRestart": true,
+    "clientError": ""
+  },
+  "verdict": "works",
+  "by": "your-github-handle"
+}
+```
+
+Validate it, regenerate the table, open a PR:
+
+```bash
+node apps/e2e/matrix.mjs --validate docs/matrix/<version>/<file>.json
+node apps/e2e/matrix.mjs        # regenerates MATRIX.md
+```
+
+CI runs the same validator on every PR, so a malformed record fails before a human reads it.
+
+## What the validator insists on, and why
+
+- **`works` requires `checks.toolsVisible > 0`.** "It works" with no number is the self-report this whole flow exists to replace.
+- **`broken` requires `checks.clientError`** — your client's own words, verbatim. A failure nobody can act on is worse than no record.
+- **Every record needs a host and a version.** A cell nobody can place is decoration.
+
+**A `broken` record is as welcome as a `works` one and passes exactly the same checks.** It is usually more useful: it is how we find out that a client changed its config path, or that our entry shape stopped being read. If your client does not work, that is the record we most want.

package/docs/mint.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://mintlify.com/schema.json",
+  "name": "Reticle",
+  "logo": {
+    "light": "/logo/light.svg",
+    "dark": "/logo/dark.svg"
+  },
+  "favicon": "/favicon.svg",
+  "colors": {
+    "primary": "#8b7bff",
+    "light": "#a99bff",
+    "dark": "#6b5bdf",
+    "background": {
+      "dark": "#0b0d12"
+    }
+  },
+  "topbarLinks": [
+    {
+      "name": "GitHub",
+      "url": "https://github.com/reticlehq/reticle"
+    }
+  ],
+  "topbarCtaButton": {
+    "name": "npm",
+    "url": "https://www.npmjs.com/package/@reticlehq/react"
+  },
+  "navigation": [
+    {
+      "group": "Get started",
+      "pages": ["getting-started", "local-registry"]
+    },
+    {
+      "group": "Integrate",
+      "pages": [
+        "platform-integration",
+        "desktop-apps",
+        "integration-patterns",
+        "flows",
+        "testing",
+        "multi-agent-testing",
+        "human-control",
+        "deploy-checks"
+      ]
+    },
+    {
+      "group": "Concepts",
+      "pages": ["architecture", "benchmarks", "token-efficiency"]
+    },
+    {
+      "group": "Reference",
+      "pages": ["usage", "agent-cheatsheet", "telemetry"]
+    },
+    {
+      "group": "Enterprise",
+      "pages": ["enterprise"]
+    }
+  ],
+  "footerSocials": {
+    "github": "https://github.com/reticlehq/reticle"
+  }
+}

package/docs/multi-agent-testing.md

@@ -0,0 +1,55 @@
+# Multi-agent & multi-project testing
+
+Reticle is built for the messy real world: several apps running at once, ports that shift between runs, and many agents driving different flows of the same app in parallel — without each one spinning up its own Chromium. This page explains how that works and how to use it.
+
+## The mental model
+
+- **One daemon per machine.** `reticle mcp` discovers a running daemon (via `~/.reticle`) or starts one. A crashed daemon's stale pidfile is reclaimed automatically, so you never chase "port already in use" or a zombie server.
+- **Identity is the app, not the port.** The build plugin stamps a stable `projectId` that travels in every connection. If your Next app usually runs on `:3000` but boots on `:3001` today, Reticle still knows which app it is — and an agent scoped to project A will never accidentally drive project B's tab. Origin is only a fallback hint.
+- **One browser, many contexts.** When agents need their own headless tabs, the daemon's **browser pool** launches a single Chromium and hands out isolated contexts (one per flow) — cheap, and capped so a big fan-out can't exhaust the machine. Over-cap requests queue.
+- **Attach-only.** Reticle never starts your dev server. It connects to an app you're already running (or opens a headless tab pointed at it).
+
+## Manual testing — ~5 minutes
+
+1. Add the plugin (Vite/Next) or one `reticle.connect()` call. (See [getting-started](./getting-started.md).)
+2. Start your app as you normally do.
+3. Open it in a browser — the in-page panel shows Reticle is connected.
+4. Click around; flag anything that looks wrong with the "Flag a bug" annotator. The agent drains those with `reticle_session {action:"review"}`.
+
+## Agent testing — ~2 minutes
+
+With the app running and instrumented, an agent drives a flow end to end:
+
+```text
+reticle_lease {action:"acquire"} { url: "http://localhost:3000/dashboard" }
+  → { sessionId: "lease-…", ready: true, leased: 1, queued: 0 }
+reticle_act    { sessionId, ... }      # drive the flow
+reticle_assert { sessionId, ... }      # verify intent
+reticle_lease {action:"release"} { sessionId }    # free the slot
+```
+
+`reticle_lease {action:"acquire"}` opens a fresh isolated headless context against your **already-running** app, stamps the lease identity into the URL so the app's own SDK registers under a sessionId you can target, and waits until that tab has connected (`ready: true`) before returning — so the sessionId is usable immediately. Release when the flow finishes.
+
+## 10 agents, 10 flows, one dashboard
+
+This is the design target, and it needs no special setup:
+
+- Each agent calls `reticle_lease {action:"acquire"}` for the same dashboard URL → its own isolated context (own cookies/storage) in the **one** shared Chromium.
+- The pool caps simultaneous contexts (`RETICLE_MAX_CONTEXTS`, default scales with CPU under a ceiling); extra acquires queue and proceed as slots free.
+- Flows can't bleed into each other — contexts are isolated and every session is scoped by `projectId`.
+- A single crashed page is reclaimed on its own, and if an agent crashes or hangs its lease stops being touched and the **lease reaper** reclaims the context after a TTL, freeing the slot. One dead agent never starves the others.
+
+`reticle_sessions` lists everything with `projectId` (group by app) and `leased` (pool context vs a human tab), so an orchestrator can see the whole fleet at a glance.
+
+## Knobs
+
+| Env | Default | Effect |
+| --- | --- | --- |
+| `RETICLE_MAX_CONTEXTS` | `min(8, cpus-1)` | Max simultaneous leased headless contexts. |
+| `RETICLE_PORT` | from `.reticle.json`, else `4400` | Daemon port (rarely needed — discovery handles it). |
+
+## Why not just open many browsers?
+
+Ten Chromiums is hundreds of MB each and will thrash a laptop. Ten contexts in one browser is a few MB apiece and fully isolated — same correctness, a fraction of the cost. That's the whole point of the pool.
+
+**Measured** (`bench/harness/multi-agent-throughput.mjs`): 16 verification flows that take **35.4s** one-at-a-time finish in **5.2s** across 8 leased contexts on a single Chromium — **6.78× faster**, ~30s saved per batch, with all 8 contexts live at peak. The speed-up scales with agent count up to the cap; the win over launching a browser per agent grows with how much per-agent browser startup you avoid.