@reticlehq/server 2.7.0 → 2.8.0

package/docs/instrumentation.mdx

@@ -0,0 +1,232 @@
+---
+title: Instrument your app so it can testify
+sidebarTitle: Instrument
+description: Register stores, emit signals, add testids. The three things that decide whether your verdicts say "the DOM changed" or "the app succeeded".
+icon: wrench
+---
+
+Reticle works with zero instrumentation. You get DOM, network, console and routing out of the box, and that is already more than a screenshot can tell you.
+
+But there is a ceiling, and this page is about raising it. Instrumentation is the difference between a verdict that says _something appeared_ and one that says _the application declared success_.
+
+## The grade ladder
+
+Every verdict carries an `honesty.grade`. How strong the evidence actually was.
+
+<CardGroup cols={3}>
+  <Card title="presence" icon="eye">
+    An element appeared, or text showed up. True, and weak: a mock renders exactly the same.
+  </Card>
+  <Card title="state" icon="database">
+    A registered store changed. Now you know the app accepted it, not just drew it.
+  </Card>
+  <Card title="signal" icon="tower-broadcast">
+    The app fired a named signal. The app itself declaring success. Nothing beats this.
+  </Card>
+</CardGroup>
+
+Here is the same login, verified two ways. First with a network predicate and no instrumentation leaned on:
+
+```json
+"honesty": { "grade": "presence", "coverage": { "pct": 100 }, "integrity": { "clean": true } }
+```
+
+Then with a signal predicate, against the same app:
+
+```json
+"honesty": { "grade": "signal", "coverage": { "pct": 100 }, "integrity": { "clean": true } }
+```
+
+Same click. Better evidence. The only difference is that somebody spent ten minutes emitting a signal.
+
+## Three things to add
+
+Everything lives in `src/reticle-dev.ts`, which `reticle init` creates for you and which is dev-only, it self-guards on `import.meta.env.DEV` and is a no-op in a production build.
+
+### 1. Register your store
+
+```ts
+import { registerStore, registerCapabilities, tanstackQueryStore } from '@reticlehq/browser';
+
+registerStore('app', useApp);
+registerStore('queries', tanstackQueryStore(queryClient));
+```
+
+<Warning>
+Pass the **store**, not `() => store.getState()`. The store form wires `subscribe`, so every mutation
+emits a state diff. The getter form is read-only and silently produces empty `stateDiffs`, which
+reads as "nothing changed" and actually means "I was never watching".
+</Warning>
+
+That single line is what turns this up in a verdict:
+
+```json
+"stateDiffs": [
+  { "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}", "atMs": 833326 }
+]
+```
+
+A mock that returns `200` without touching state gets caught precisely there, and nowhere else.
+
+<Tip>
+  Register your server-state cache too. "The screen is plausible and the network is silent" is the
+  normal failure with query caches: a mutation forgets to invalidate, the UI keeps rendering a
+  number that was true a minute ago, and nothing fires for anyone to notice. The cache's freshness
+  metadata is the only witness.
+</Tip>
+
+### 2. Emit signals
+
+A signal is your app saying "this specific thing succeeded". Define the names in one place so they cannot drift:
+
+```ts
+import { reticle } from '@reticlehq/browser';
+
+export const Sig = {
+  AUTH_GRANTED: 'auth:granted',
+  AUTH_DENIED: 'auth:denied',
+  DEPLOY_CREATED: 'deploy:created',
+  MODAL_OPENED: 'modal:opened',
+  TOAST_SHOWN: 'toast:shown',
+} as const;
+
+const isDev = import.meta.env.DEV;
+
+/** Emit a Reticle signal (dev only, no-op in production). */
+export function emit(name: Sig, data: Record<string, unknown> = {}): void {
+  if (isDev) reticle.signal(name, data);
+}
+```
+
+Then call `emit(Sig.AUTH_GRANTED, { email })` where the thing actually succeeds. Not where you _think_ it succeeds. In the success branch, after the state update, not in the click handler.
+
+**Emit the failures too.** `auth:denied` is as valuable as `auth:granted`, for a reason the next section demonstrates.
+
+### 3. Advertise the surface
+
+```ts
+registerCapabilities({
+  testids: TESTIDS,
+  signals: Object.values(Sig),
+  stores: ['app'],
+  flows: FLOWS,
+});
+```
+
+This is what [`reticle_capabilities`](/tools-tools-and-run) returns. The app telling an agent what it considers testable, before the agent has looked at a single element. It is the cheapest and most truthful first call on an unfamiliar codebase.
+
+## Why emitting failure signals pays off
+
+Here is a real failed login, from an app that emits both signals:
+
+```json
+{
+  "verified": "no",
+  "verdict": {
+    "pass": false,
+    "failureReason": "no signal matched {\"kind\":\"signal\",\"name\":\"auth:granted\"}",
+    "observed": "signal 'auth:granted' never fired; signals seen in this window: auth:denied",
+    "expected": "signal 'auth:granted' to fire"
+  },
+  "summary": {
+    "net": { "total": 1, "errors": 1, "headline": "POST http://localhost:8787/api/login 401" },
+    "stateDiffs": [],
+    "signals": ["auth:denied"]
+  },
+  "honesty": { "grade": "signal", "integrity": { "clean": true } },
+  "capsule": {
+    "firstDivergence": {
+      "expected": { "kind": "signal", "name": "auth:granted" },
+      "observed": "signal \"auth:granted\" never fired"
+    },
+    "blastRadius": ["signal auth:denied"]
+  }
+}
+```
+
+Read `observed` again:
+
+> signal 'auth:granted' never fired; **signals seen in this window: auth:denied**
+
+Without the failure signal, that line would have stopped at "never fired", and the agent would be guessing between a network problem, a broken handler and a wrong password.
+
+With it, the app has named its own outcome: the credentials were rejected. The 401 headline confirms it, `stateDiffs: []` proves nothing was written, and the whole diagnosis arrives in one response.
+
+<Note>
+  `capsule.firstDivergence` and `blastRadius` are saved to disk automatically on a failure, so the
+  evidence survives the agent's context window. Look for `capsuleSaved` in the response.
+</Note>
+
+## When Reticle refuses to call it a pass
+
+This is the one that surprises people, so here it is in full. A successful login, on a backgrounded tab:
+
+```json
+{
+  "verified": "unknown",
+  "verifiedReason": "unsettled",
+  "because": "the page never settled, so the reaction window may have closed before the app finished",
+  "verdict": {
+    "pass": true,
+    "evidence": { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } }
+  },
+  "summary": {
+    "stateDiffs": [{ "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}" }],
+    "signals": ["auth:granted"]
+  },
+  "honesty": { "grade": "signal", "integrity": { "clean": true } },
+  "feedback_invite": "Reticle could not tell what happened here. If you expected otherwise, reticle_feedback. An unknown verdict is our defect, not yours"
+}
+```
+
+The signal fired. State changed. `verdict.pass` is `true`. And `verified` is **`unknown`**, because the page never went quiet inside the observation window, so Reticle cannot promise it saw the whole story.
+
+That is the design working as intended. A tool that reports "pass" whenever it happens to catch a matching event, without knowing whether it saw everything, is how you get a confident wrong answer.
+
+<Warning>
+  The usual cause is a **throttled tab**. A backgrounded browser tab has its timers suppressed,
+  which suppresses the quiescence detection Reticle uses to decide the page has settled. Focus the
+  tab, or drive a dedicated context. The response tells you: look for `session.throttled` and the
+  accompanying `warning`.
+</Warning>
+
+Note the last field. When Reticle cannot tell what happened, it invites a bug report and calls the ambiguity its own defect rather than yours. If you hit an `unknown` you believe is wrong, that is worth [sending](/tools-session-and-feedback).
+
+## Testids, briefly
+
+```tsx
+<button data-testid="login-submit">Sign in</button>
+```
+
+Role and text queries survive refactors well. Testids survive redesigns, translations, and the day marketing rewrites every button label. Add them to the elements your important flows actually touch. Not to everything, which is a chore nobody finishes.
+
+## Keeping it honest
+
+Signals rot the way every convention rots: someone adds a mutation, forgets the signal, and every verdict for that flow quietly drops from `signal` to `presence`. Nothing goes red. The tests pass. The evidence just gets weaker, invisibly.
+
+```bash
+npm i -D @reticlehq/eslint-plugin
+```
+
+One rule. State changed, so a signal must fire, makes the signal layer self-enforcing. It is the only mechanism we have found that survives contact with a deadline.
+
+## Start with one flow
+
+You do not need to describe the whole app, and trying to is the slow path that gets abandoned halfway.
+
+1. Pick your most important flow. The one that would be embarrassing to break.
+2. Register the store it reads.
+3. Emit a signal where it succeeds, and one where it fails.
+4. Add testids to the elements it touches.
+5. Drive it, and check `honesty.grade` says `signal`.
+
+Then stop. Add more when a flow you actually replay needs it.
+
+<CardGroup cols={2}>
+  <Card title="Prove it" icon="circle-check" href="/tools-act-and-wait">
+    Use your new signals as predicates and watch the grade climb.
+  </Card>
+  <Card title="Lock it in" icon="vial" href="/testing">
+    Turn the instrumented flow into a spec that runs on every pull request.
+  </Card>
+</CardGroup>

package/docs/integration-patterns.md

@@ -1,24 +1,28 @@
-# Reticle Integration Patterns
+---
+title: Integration patterns
+description: 'The recommended shape for a real codebase: a minimal production footprint and a signal layer that cannot silently drift.'
+icon: shapes
+---
 
-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.
+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, with 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)
+- [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, use `reticle drive`](#6-limitation-un-scriptable-tabs-use-reticle-drive)
 - [Checklist](#checklist)
 
 ---
 
-## 1 — Start here: reuse what you already have
+## 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.
+**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.
+**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';
@@ -31,7 +35,7 @@ registerCapabilities({
 });
 ```
 
-**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.
+**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';
@@ -39,36 +43,36 @@ 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.
+That's day-one usefulness with no rewrite. The rest of this doc is how to do steps 2 and 3 _well_ so the signal layer stays honest as the app grows.
 
-## 2 — Inject the emitter (zero prod bundle)
+## 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.**
+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
+// 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
+// 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.
+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
+## 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.
+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.
+**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
+// 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>]> = {
@@ -83,7 +87,7 @@ function dispatch(action: keyof typeof signalFor, run: () => State): void {
 }
 ```
 
-**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.
+**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';
@@ -97,18 +101,18 @@ const next = commitAndSignal(
 );
 ```
 
-If `mutate` throws, the mutation never happened — so **the signal is not emitted and the error propagates** unchanged.
+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.
+> **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`)
+## 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.
+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
+// 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;
@@ -127,11 +131,11 @@ 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.")
+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`, with the 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`)
+## 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.
+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`):
 
@@ -154,11 +158,11 @@ export default [
 
 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`
+## 6. Limitation: un-scriptable tabs, use `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`.
+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**: a backgrounded tab, say, 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.
+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
 

package/docs/local-registry.md

@@ -1,8 +1,12 @@
-# Test unpublished Reticle changes in a real app (local registry)
+---
+title: Local registry
+description: 'Exercise local, unpublished Reticle changes in a real external app before they ship.'
+icon: box
+---
 
-> **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.
+> **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.
+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
 
@@ -16,7 +20,7 @@ This starts a **fresh** Verdaccio on `http://localhost:4873`, creates a user/tok
 
 | 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/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`) |
@@ -47,18 +51,18 @@ npm i -D @reticlehq/react @reticlehq/vite-plugin
 # 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).
+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`:
+> **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 with `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:
+**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
+// .mcp.json: point npx at the local registry so it fetches @reticlehq/server from Verdaccio
 {
   "mcpServers": {
     "reticle": {
@@ -86,7 +90,7 @@ Mount the SDK from a dev-only client component (see the Next.js section in [Gett
 
 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):
+- **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
@@ -107,16 +111,16 @@ Synthetic events can't trigger native `onMouseEnter`/pointer state (hover menus,
   }
   ```
 
-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).
+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).
+- **Specs:** with `@reticlehq/test`, turn checks into `reticleTest("…", async t => { await t.act(...); await t.expectSignal(...) })`. They are signal/testid-bound, `reticle_clock` for determinism, `t.expectInputModeReal()` to skip-with-reason when real input isn't active. Run them headless via `reticle drive` (the same path CI uses).
 - **Flows:** record a flow once and Reticle writes it to a git-checked `.reticle/flows/<name>.json` (anchored on testid/signal); `reticle_flow_replay` re-resolves anchors at run time and reports **legible drift** with a nearest-match; `reticle_flow_heal` proposes/applies the rebind. A fresh agent reads `.reticle/contract.json` to learn your testable surface without grepping source.
 
 ## 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.
+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
 

package/docs/multi-agent-testing.md

@@ -1,22 +1,26 @@
-# Multi-agent & multi-project testing
+---
+title: 'Multi-agent and multi-project'
+description: 'Several apps at once, ports that shift between runs, and many agents driving the same app in parallel without a Chromium each.'
+icon: users
+---
 
-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.
+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.
+- **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). They are 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
+## 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.
+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
+## Agent testing: ~2 minutes
 
 With the app running and instrumented, an agent drives a flow end to end:
 
@@ -28,7 +32,7 @@ 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.
+`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
 
@@ -36,7 +40,7 @@ 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`.
+- 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.
@@ -46,10 +50,10 @@ This is the design target, and it needs no special setup:
 | 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). |
+| `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.
+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.
+**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.

package/docs/packages/babel-plugin.mdx

@@ -0,0 +1,70 @@
+---
+title: '@reticlehq/babel-plugin'
+description: A Babel plugin that stamps data-reticle-source on JSX host elements so Reticle can name the file a node came from.
+icon: file-code
+---
+
+`@reticlehq/babel-plugin` puts the source location back. React 19 dropped `_debugSource`, which is what source mapping used to rely on, so without this the tools can tell you the component name but not the file.
+
+**Version 2.8.0. Apache 2.0. CommonJS. No runtime dependencies. Peer dependency: `@babel/core ^7`.**
+
+## What it stamps
+
+```jsx
+<button onClick={submit}>Sign in</button>
+```
+
+becomes, in dev only:
+
+```jsx
+<button onClick={submit} data-reticle-source="src/components/Login.tsx:81:6">
+  Sign in
+</button>
+```
+
+The path is relative to `process.cwd()`, with backslashes normalized to forward slashes. A file with no name stamps `unknown`.
+
+## What it skips
+
+- Component tags. Only lowercase host elements are stamped, because a component's own JSX gets stamped where it is defined.
+- Elements that already carry the attribute.
+- Nodes with no location information.
+- Anything whose tag name is not a plain `JSXIdentifier`.
+
+## Do you install it?
+
+Only if you are wiring Babel yourself. [`@reticlehq/vite-plugin`](/packages/vite-plugin) and [`@reticlehq/next`](/packages/next) both pull it in.
+
+```bash
+npm i -D @reticlehq/babel-plugin
+```
+
+## The export
+
+One export, via `export =`. There are no named exports and no `default` interop wrapper, because Babel `require()`s the module and takes the object directly.
+
+```ts
+function reticleSourcePlugin({ types }: { types: typeof BabelTypes }): PluginObj<PluginPass>;
+```
+
+The Babel plugin name is `reticle-source`. Its visitor handles `JSXOpeningElement` only.
+
+**It takes no options.** The plugin reads nothing from `state.opts`.
+
+## Wiring it by hand
+
+```js
+// babel.config.cjs
+module.exports = {
+  plugins: process.env.NODE_ENV === 'development' ? [require('@reticlehq/babel-plugin')] : [],
+};
+```
+
+<Warning>
+  Do not write `require('@reticlehq/babel-plugin').default`. With `export =` there is no `.default`,
+  and an old README example got this wrong.
+</Warning>
+
+## Why an attribute rather than a runtime lookup
+
+The stamp survives minification of everything else, costs nothing at runtime, and is readable from the DOM node itself. That is what lets [`reticle_inspect`](/tools-inspect) answer with a file and a line rather than a component name and a shrug.