@reticlehq/server 2.4.0 → 2.5.0

package/docs/desktop-apps.md

@@ -0,0 +1,256 @@
+# Desktop apps: Electron & Tauri
+
+Reticle verifies desktop apps the same way it verifies web apps — from **inside** the app, over a localhost WebSocket. There is no browser to open and no screenshot to interpret.
+
+- [How you actually test a desktop app](#how-you-actually-test-a-desktop-app)
+- [Electron](#electron)
+- [Tauri](#tauri)
+- [What IPC looks like to an agent](#what-ipc-looks-like-to-an-agent)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## How you actually test a desktop app
+
+The usual question is _"it's a desktop app — what URL does the agent open?"_ None. The direction is reversed from what browser tooling trains you to expect:
+
+```text
+┌──────────────┐   MCP     ┌───────────────────┐   WebSocket    ┌───────────────────────┐
+│ coding agent │◀────────▶│  reticle daemon    │◀──────────────▶│ your Electron/Tauri   │
+│              │  stdio   │  (localhost:4400)  │   the app      │ window + the SDK      │
+└──────────────┘          └───────────────────┘   dials OUT    └───────────────────────┘
+```
+
+Your app **connects to the daemon**, not the other way round. So the workflow is:
+
+1. Start the daemon once: `npx @reticlehq/server serve`
+2. Start your app exactly as you always do: `npm run dev`, `electron .`, `cargo tauri dev`.
+3. That's it. `reticle status` now lists your window as a session, and the agent drives it.
+
+`reticle open` has nothing to open for a desktop app and will say so, and there is no `reticle drive` for desktop — those launch a browser, which is not what you are testing. Headless works on both runtimes; see below.
+
+## What works, measured
+
+Every tool below was run against both demo apps against a live daemon.
+
+The rows in **bold** are the ones a committed battery re-proves on every change — `pnpm test:e2e:desktop`, which starts a real Electron main process and a **packaged** Tauri binary (`tauri://localhost`, not `tauri dev`) and drives them headless. The rest were measured by hand. That distinction matters: this table used to report a hand-run score with nothing in the repo that reproduced it, so it could go stale without anything failing.
+
+| Capability | Electron | Tauri | Note |
+| --- | --- | --- | --- |
+| sessions, snapshot, query, inspect | ✅ | ✅ | `inspect` returns `src/App.tsx:104` in a dev build; a packaged production renderer has no source map, so it reports `n/a` |
+| capabilities, state (live store) | ✅ | ✅ | `reticle_state` reads the real store |
+| act (click/fill/type/select) | ✅ | ✅ |  |
+| **act_and_wait, wait_for, assert** | ✅ | ✅ | signal / state / route / net / console predicates |
+| console errors | ✅ | ✅ | catches what the UI never shows |
+| network — HTTP | ✅ | ✅ | on `file://` a relative URL has no origin; use an absolute one |
+| **network — IPC** | ✅ | ✅ | `ipc://<channel>`, incl. failures. Electron: `invoke` and `sendSync` carry a verdict; a one-way `send` is recorded as `oneWay: true` with NO status, because the renderer never learns the outcome. Tauri: both the `ipc://` (macOS/Linux) and `http://ipc.localhost` (Windows) transports |
+| route | ✅ | ✅ | use a **hash** router — see below |
+| storage, animations, observe, explore | ✅ | ✅ |  |
+| baseline (semantic), record → replay, crawl | ✅ | ✅ | `crawl` found real anomalies in both |
+| navigate (reload) | ✅ | ✅ |  |
+| **screenshot / visual_diff** | ✅ | ✅ | one line in Electron's main process; one Rust command in Tauri — see below. Reticle's own presenter panel is hidden for the shot, so a baseline records your app and not the instrument |
+| **drivable while window occluded** | ✅ | ✅ | including minimized, app-hidden, and behind a fullscreen app on another Space |
+| **headless** | ✅ | ✅ | Electron never shows the window; Tauri shows, loads, then hides |
+| **a missing preload is DECLARED, not silent** | ✅ | n/a | without `@reticlehq/electron/preload` every IPC call is invisible, so verdicts carry `coverage: partial` naming the missing line instead of reading clean |
+| network_mock, viewport | ❌ | ❌ | need a Reticle-driven browser |
+
+### Screenshots
+
+**Electron: one line in the main process.**
+
+```js
+const { installReticleCapture } = require('@reticlehq/electron/main');
+const win = new BrowserWindow({ ... });
+installReticleCapture(win);
+```
+
+That is all — no CDP flag, no extra packages, works on a packaged `file://` renderer. `reticle_screenshot` and `reticle_visual_diff` then work on your app.
+
+Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-port=9222` + `RETICLE_CDP_URL=http://127.0.0.1:9222` also works and additionally enables `fullPage` (the main-process route captures the window as composited, so it cannot scroll-stitch).
+
+**Why the main process, and not a screen capture.** `webContents.capturePage()` reads the window's own backing store. Capturing a screen _region_ instead was tried and deliberately rejected: it photographs whatever is on top, so an app window behind your editor yields a picture of the editor — saved as a visual baseline that a later diff would trust. A screenshot tool that can silently return another window's pixels manufactures exactly the false green Reticle exists to eliminate. One caveat remains: a fully occluded or minimized window is only partially composited, so parts of the capture may come back blank. Bring the window forward for a complete image — but it is never the wrong window.
+
+**Tauri: one Rust command.**
+
+```rust
+tauri::Builder::default()
+    .invoke_handler(tauri::generate_handler![reticle_tauri::reticle_capture])
+    .on_page_load(reticle_tauri::on_page_load)
+```
+
+Nothing on the JavaScript side: the SDK invokes the command through Tauri's own internals, because Tauri has no preload stage where a shim could be installed. `reticle_screenshot` and `reticle_visual_diff` then work on your app, including headless.
+
+`reticle_capture` renders the webview rather than reading the screen — like Electron's `capturePage()` — so it needs no screen-recording permission, cannot return another window's pixels, and is correct with nothing on screen at all. Each platform uses its own webview API:
+
+| Platform | API | Status |
+| --- | --- | --- |
+| macOS | `WKWebView.takeSnapshot` | Verified against a running app |
+| Linux, BSD | WebKitGTK `webkit_web_view_get_snapshot` | Snapshot + PNG encoding verified under `xvfb`; not yet driven through a full Tauri app |
+| Windows | WebView2 `CapturePreview` | **Untested — compiles, never executed** |
+
+The Windows path is written and type-checked against the real `webview2-com` API (which caught two genuine type errors), but nobody has run it on Windows. CI now re-checks it against that target on every PR (`cargo check --target x86_64-pc-windows-msvc`), so "compiles" is a gate rather than a claim — it had been asserted for months by a workflow comment while no such job existed. Executed is still a different word from compiled: it is shipped rather than withheld so it can be tried, and labelled rather than listed flatly so that trying it is a choice. If it works for you, say so and this row changes; treat a green from it as unconfirmed until then.
+
+All three capture the visible viewport by default, so a baseline taken on a developer's Mac is comparable against the same app in Linux CI. On a platform with no webview API to call, capture reports no-provider rather than returning a plausible wrong image.
+
+**`{ fullPage: true }` works on Tauri/Linux only.** WebKitGTK can render the whole document offscreen; `takeSnapshot` (macOS) and `CapturePreview` (Windows) only give what is composited, and Electron's `capturePage()` is the same. Asked for a full page they cannot produce, all of them return `{ ok:false, reason:'full-page-unsupported' }` rather than quietly handing back the viewport — a baseline that omits everything below the fold, while every later diff of it reports green about a region that was never captured. No baseline is written on a refusal.
+
+An app that already has its own capture can expose `window.__reticleIpc.capture()` returning a PNG path instead; the SDK prefers it over the built-in command.
+
+### A correction: the Tauri macOS "liveness constraint" was wrong
+
+Earlier versions of this document said a Tauri app on macOS is only drivable while its window is on the active Space and unoccluded, and that hiding it suspends the webview. **That is not true, and the mistake is worth recording because it cost three features.**
+
+Re-measured against the live app, a loaded Tauri webview answers Reticle commands at full speed while: minimized, app-hidden with Cmd-H, fully occluded, on another Space behind a fullscreen app, and with no window on screen at all. A full 43-tool drive passes in every one of those states.
+
+What actually failed was narrower: **a webview that has never been presented never loads its page.** Every "suspension" experiment hid or moved the window from `setup`, i.e. before the first present, so the page never ran and every command timed out at 8s. The timeouts were real; the diagnosis was not. The `alwaysOnTop` workaround was then built to fix a problem that did not exist, measured as "still broken" for the same reason, and deleted.
+
+The lesson generalises past this document: four experiments agreeing does not make a conclusion controlled, if all four share the same confound.
+
+### Headless
+
+**Electron: yes.** `show: false` plus `backgroundThrottling: false` in `webPreferences`. The second one is load-bearing — Chromium runs an unshown window's timers in slow motion, which turns every settle wait into a flake. Screenshots still work, because `capturePage` reads the backing store rather than the screen. Verified with a full tool drive against a window that was never shown.
+
+**Tauri: yes — show, load, then hide.**
+
+```rust
+.on_page_load(reticle_tauri::on_page_load)   // hides the window when RETICLE_HEADLESS=1
+```
+
+Run with `RETICLE_HEADLESS=1 pnpm tauri dev`. Nothing ends up on screen, and screenshots keep working because the capture renders the webview rather than the screen.
+
+The ordering is the whole trick. Hiding the window during `setup` hides it before the webview has ever been presented, and a webview that has never been presented never loads its page — which is what made headless Tauri look impossible. Hiding it after its first page load leaves everything running. Verified with a full 43-tool drive plus a screenshot and a visual diff against a window that is not on screen.
+
+`xvfb-run -a pnpm tauri dev` also works on Linux and needs no app-side change at all.
+
+### How it compares to Playwright MCP
+
+Both attached to the same running Electron app, same task ("archive a todo, then verify it worked"):
+
+| tool                   | ~tokens | ms      | verdict                                    |
+| ---------------------- | ------- | ------- | ------------------------------------------ |
+| reticle (lean)         | **350** | 1364    | caught the failure                         |
+| playwright-mcp         | 1069    | **980** | blind to it — no network/IPC in its output |
+| playwright-mcp → Tauri | —       | —       | cannot attach (no CDP in WKWebView)        |
+
+Playwright MCP is faster. It is also structurally unable to see an IPC failure, because its channel is the accessibility tree. Full method, numbers and caveats: [`bench/desktop`](../bench/desktop).
+
+### Routing: use a hash router
+
+A packaged renderer runs on `file://`, where `pushState('/settings')` rewrites the URL to `file:///settings` — a path that does not exist, so the next reload lands on a blank page and the app is gone. This is why HashRouter is the standard choice for packaged Electron/Tauri apps. Reticle's route observer handles both, and a `{ kind: 'route', contains: … }` assertion matches the fragment.
+
+## Electron
+
+Two steps. The first is the ordinary web setup; the second is the only desktop-specific part.
+
+**1. The renderer** — one line in `vite.config.ts`, exactly like a web app:
+
+```ts
+import { reticle } from '@reticlehq/vite-plugin';
+
+export default defineConfig({
+  base: './', // file:// needs relative asset paths
+  plugins: [react(), reticle({ desktop: true })],
+});
+```
+
+`desktop: true` does the two things a desktop shell needs and a web app must never get: the plugin also runs for `vite build` (a packaged renderer is a production build with **no dev server**, so the default serve-only gating would ship an app with no `connect()` at all), and `connect()` is called with `allowInProduction` so the SDK's production backstop does not refuse to start. Keep it behind your own dev-only build so an instrumented bundle can never reach a release binary.
+
+Nothing to add in your app code. (You can still call `reticle.connect()` by hand and pass `inject: false` if you want control.)
+
+**2. The preload** — one line, before you expose anything:
+
+```bash
+npm i -D @reticlehq/electron
+```
+
+```js
+// electron/preload.cjs
+require('@reticlehq/electron/preload');
+
+const { contextBridge, ipcRenderer } = require('electron');
+contextBridge.exposeInMainWorld('api', {
+  loadTodos: () => ipcRenderer.invoke('todos:load'),
+});
+```
+
+That line is what makes your main-process calls visible. It has to live in the preload, and it is not a stylistic choice: `contextBridge.exposeInMainWorld` hands the renderer a **deeply frozen, non-configurable** object, so nothing running in the page can instrument `window.api`. The preload is the last point where `ipcRenderer.invoke` is still an ordinary, writable function. Patching there covers every channel you go on to expose, whatever you named it.
+
+**Preload sandboxing.** A sandboxed preload can't resolve `node_modules`, so the bare `require` above fails. Either bundle your preload (electron-vite and Electron Forge do this by default — the require is inlined at build time and sandboxing stays on), or set `sandbox: false` in `webPreferences`.
+
+**Packaged renderers.** An app that loads its renderer with `loadFile` runs on `file://`, which is a production Vite build. Pass `allowInProduction: true` to `connect()` for that mode, or keep the SDK gated behind `import.meta.env.DEV` so it never enters the shipped binary at all.
+
+Working example: [`apps/electron-smoke`](../apps/electron-smoke).
+
+## Tauri
+
+Frontend side, nothing desktop-specific:
+
+```ts
+// src/main.tsx
+import { reticle } from '@reticlehq/browser';
+
+if (import.meta.env.DEV) reticle.connect();
+```
+
+Nothing else is needed for IPC. A Tauri `invoke` travels as a real `fetch` to Tauri's `ipc://` custom protocol, so Reticle already sees it; every `invoke('load_todos')` shows up as `ipc://load_todos`. Reticle also reads Tauri's `Tauri-Response` header, because the transport answers **HTTP 200 whether the Rust command returned `Ok` or `Err`** — without that translation a failed command would be recorded as a successful request.
+
+The one required step is **CSP**. Tauri ships a restrictive default that blocks the bridge WebSocket before it opens, and the failure is silent from the app's side. In `src-tauri/tauri.conf.json`:
+
+```json
+{
+  "app": {
+    "security": {
+      "csp": "default-src 'self' ipc: http://ipc.localhost; connect-src 'self' ipc: http://ipc.localhost ws://localhost:4400 ws://127.0.0.1:4400"
+    }
+  }
+}
+```
+
+Keep `ipc: http://ipc.localhost` in `connect-src` — Tauri v2 needs it for `invoke` itself. Add your dev-server origin too if you use `devUrl`. This is a dev-only config; drop the `ws://` entries from your release config.
+
+Working example: [`apps/tauri-smoke`](../apps/tauri-smoke).
+
+## What IPC looks like to an agent
+
+A desktop app reaches its backend over IPC, not HTTP. `fetch`/`XHR` patching cannot see that, so without the IPC observer every backend call in your app is a blind spot — `reticle_network` returns nothing, `act_and_wait` has no in-flight request to settle on, and `assert { net }` is vacuously true. That is a false green by construction.
+
+Reticle records each IPC call as an ordinary request, so the tools you already use work unchanged:
+
+```jsonc
+// reticle_network { urlContains: "ipc://" }
+{
+  "calls": [
+    { "method": "ipc", "url": "ipc://todos:load", "status": 200, "ms": 134 },
+    { "method": "ipc", "url": "ipc://todos:archive", "status": 500, "ms": 83 },
+  ],
+}
+```
+
+IPC has no status code; `200`/`500` are synthetic, mapped from whether the call succeeded or failed, precisely so that `reticle_network { status: 500 }` and `assert { kind: "net", status: 500 }` keep working. On Tauri you will see `status: 500` next to `statusText: "OK"` — that is not a bug: the transport really did answer 200, and the 500 is the command's own verdict. `ok` is authoritative, and on Electron `error` carries the message your main process returned:
+
+```jsonc
+// reticle_assert { predicate: { kind: "net", urlContains: "ipc://todos:archive", status: 500 } }
+{
+  "pass": true,
+  "evidence": {
+    "url": "ipc://todos:archive",
+    "ok": false,
+    "status": 500,
+    "error": "archive is not implemented in the backend",
+  },
+}
+```
+
+Both example apps ship a planted false green — an Archive button that updates the UI optimistically and swallows the rejection. The screen says "archived", a screenshot agrees, a DOM assertion agrees. Only the IPC record disagrees. That is the case desktop support exists for.
+
+## Troubleshooting
+
+**`reticle status` shows no session.** Check the app's console (Electron: devtools, or forward `console-message` to your terminal — a desktop renderer has no visible console otherwise). A refused connect always logs why.
+
+**Tauri: nothing connects and the app console shows a CSP violation.** The `connect-src` above is missing or does not include your daemon's port.
+
+**Electron: `module not found: @reticlehq/electron/preload`.** The preload is sandboxed. Bundle it, or set `sandbox: false` — see [Electron](#electron).
+
+**IPC calls do not appear, but the app works.** Electron: the shim's `require` must run _before_ your preload captures its own reference to `ipcRenderer`. Put it on the first line. Tauri: `invoke` imported from `@tauri-apps/api/core` is observed; a hand-rolled `postMessage` protocol is not, and neither is Tauri's `postMessage` transport fallback on platforms where the `ipc://` custom protocol is unavailable.
+
+**Why not just patch `invoke` / `window.api` directly?** Because neither can be. Tauri defines `__TAURI_INTERNALS__.invoke` as `writable: false, configurable: false`, and Electron's `contextBridge` object is deeply frozen and installed non-configurably. Both were verified, not assumed — which is why the two runtimes use the two different mechanisms above rather than one uniform monkey-patch.

package/docs/enterprise.md

@@ -0,0 +1,62 @@
+# Reticle for enterprises
+
+> Premium access (how you get + activate it), what's gated, the security/data-handling posture, and the licensing model. Integration mechanics live in [`platform-integration.md`](./platform-integration.md).
+
+## How premium access works (offline, no phone-home)
+
+Enterprise (`ee/`) features ship **inside the open package** — they're source-available (free for development, testing, and evaluation). A **license key activates them in production**. Activation is verified locally with Ed25519; nothing about your usage ever leaves your machine.
+
+**The flow, end to end:**
+
+1. **Buy** — contact **[hey@reticle.sh](mailto:hey@reticle.sh)**; we issue you a signed license key (org, plan, expiry, feature set).
+2. **Install** — set it on the machine running the Reticle server:
+   ```bash
+   export RETICLE_LICENSE_KEY="<your key>"
+   # the release already bakes the issuer public key (RETICLE_LICENSE_PUBLIC_KEY)
+   ```
+3. **Verify** — `reticle license` shows your status:
+   ```
+   active    licensed to Acme Corp (enterprise), expires 2027-06-20 · features: sso, audit
+   eval      evaluation mode — enterprise features run free (no issuer key configured)
+   missing   set RETICLE_LICENSE_KEY to activate enterprise features in production
+   expired   renew to keep using enterprise features
+   ```
+4. **Unlock** — enterprise features now run in production; without a valid key they refuse to run there (a clear error, never a silent half-feature). In eval/dev they always run free.
+5. **Renew** — keys carry an expiry; `reticle license` warns before it lapses.
+
+> Procuring a license: contact **[hey@reticle.sh](mailto:hey@reticle.sh)**. Keys are issued offline and signed with Ed25519; the activation you run (`reticle license`) verifies them locally with no network call.
+
+## What's gated (and the roadmap)
+
+The licensing **mechanism** is open core (inspectable, FSL) — only the **features** under `ee/` are gated:
+
+- **Today:** the activation gate + an example gated feature (audit event recording).
+- **Roadmap** (the reliably enterprise-only set): **SSO/SAML, SCIM, RBAC / team permissions, audit logs, multi-org management, verify-before-merge policy gates, and the hosted control-plane connectors.** These are the things a security/compliance org pays for; the core verification engine stays free forever.
+
+> What's premium vs free, and pricing, are business decisions for the owner — this doc describes the _mechanism_, not the price list.
+
+## Security & data handling
+
+The honest one-pager a security review needs. Reticle is built so the answer to "where does our data go?" is **nowhere — it runs on your machine, in your infra.**
+
+| Question | Answer |
+| --- | --- |
+| Does the SDK ship to production? | **No** — dev/preview-only, tree-shaken from production builds. |
+| Where does the server run? | **Localhost** — the bridge binds `127.0.0.1`; the verify endpoint is localhost-bound + token-guarded (constant-time), with request/body-size/timeout limits. |
+| Does anything phone home? | **No app data, ever.** License checks are offline (Ed25519). The CLI sends anonymous, opt-out usage metrics only (random id + event names — no code, no PII; see [telemetry](telemetry.md)); disable fleet-wide with `RETICLE_TELEMETRY=0` or per-machine with `reticle telemetry disable`. Feedback your team explicitly sends us (`reticle feedback`) is the only free text that ever leaves; it is never collected passively, is redacted client-side, and is disabled fleet-wide with `RETICLE_FEEDBACK=0`. |
+| Where do artifacts live? | Your disk: `.reticle/runs/<id>.json` (atomic writes, bounded retention), `.reticle/flows/`, `.reticle/contract.json`. You own them. |
+| What can the server read? | The DOM/network/console/routing/state of the app under test — locally. |
+| Leak risk downstream? | The **`prod-preview` profile** redacts source `file:line`, raw bodies, and app-state values. |
+| Path safety | Run/flow ids are validated as single path segments on read **and** write (no traversal). |
+
+**Verify it yourself:** the SDK + server are source-available — read the tree-shaking, the `127.0.0.1` bind, and the offline license verify. `SECURITY.md` has the disclosure process; an SBOM is available on request. SOC 2 is a GA-stage item (no Reticle-hosted data exists today to certify); the posture above is the honest current state.
+
+## Licensing model (per package)
+
+| Scope | License | Why |
+| --- | --- | --- |
+| Embeddable SDK (`browser`, `protocol`, `react`, `babel-plugin`, `next`, `vite-plugin`, `eslint-plugin`) | **Apache-2.0** | safe to ship inside your customers' apps; explicit patent grant |
+| Server / CLI / MCP (`server`, `test`, umbrella) | **FSL-1.1-ALv2** | free for any use except reselling Reticle itself; converts to Apache after 2 years |
+| Enterprise features (`packages/server/src/ee/`) | **Reticle Enterprise License** | source-available; free for dev/eval, license key required in production |
+
+Embedding / OEM / enterprise: **[hey@reticle.sh](mailto:hey@reticle.sh)**.

package/docs/fixtures.md

@@ -0,0 +1,28 @@
+# Fixture apps
+
+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)**.
+
+## Why it is a separate repo
+
+Three reasons, each of which bit us before the split:
+
+- **They are somebody else's package managers.** `react-admin` is a yarn monorepo. Putting it under `apps/*` makes it a member of this pnpm workspace and breaks `pnpm install` for everyone.
+- **They need a branch model this repo cannot give them.** A fresh install is only meaningful on a surface that has never been instrumented. Re-running `init` over an already-wired app reports `·` (already wired) for every step and proves nothing — which is exactly how an install regression ships unnoticed. `reticle-fixtures` keeps a pristine `clean` branch for that, plus `main` at the latest version and `reticle/<version>` per release.
+- **They are large.** The upstream checkouts were eight gigabytes of somebody else's git history sitting gitignored inside this repo.
+
+## What runs there
+
+```bash
+node scripts/materialise.mjs   # build apps/ from fixtures.json at pinned refs
+node scripts/verify.mjs        # install into every clean app, boot it, assert a session connects
+```
+
+The last step is the one that earns its keep. Every install bug found so far has been silent: the app boots, the `init` report reads clean, and nothing connects. Next.js shipped in that state through a whole release — three independent defects, none visible to any check short of opening a browser and looking at `reticle status`.
+
+## What stays here
+
+`apps/` — bench-app, next-smoke, the Remix and Astro examples, the Electron and Tauri smoke apps, atlas, and the API. These are the CI gates (`pnpm test:e2e`, `pnpm test:e2e:desktop`), and `integration-coverage.test.ts` fails if one of them goes missing while `SKILL.md` still offers its framework.
+
+The split is: **`apps/` proves the tools work. `reticle-fixtures` proves the install works.**

package/docs/flows.md

@@ -0,0 +1,166 @@
+# Flows, the recorder & self-healing — record once, run forever
+
+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.
+
+## The `.reticle/` directory
+
+When you record or save a contract, Reticle writes a git-checked workspace next to your app:
+
+```
+.reticle/
+  contract.json            # the app's testable surface (testids, signals, stores)
+  flows/
+    create-drop.json       # a recorded, anchored, replayable flow
+  baselines/               # snapshot baselines (co-located)
+```
+
+The server resolves `.reticle/` from the working directory it runs in (your project root). A fresh agent can read `.reticle/contract.json` to learn the testable surface **without grepping your source**.
+
+## The contract — advertise the testable surface
+
+In your app, declare what's testable (see [Step 6 in Getting Started](getting-started.md)):
+
+```ts
+import { registerCapabilities } from '@reticlehq/react';
+registerCapabilities({
+  testids: ['add-task', 'checkout'],
+  signals: ['order:saved'],
+  stores: ['cart'],
+});
+```
+
+Then persist it to disk so it's committed and any agent can read it:
+
+| Tool | What it does |
+| --- | --- |
+| `reticle_capabilities()` | the live testable surface `{ testids, signals, stores, flows }` |
+| `reticle_contract_save()` | write the live capabilities to `.reticle/contract.json` (versioned, diffable) |
+
+## Create a flow
+
+**(a) Agent-recorded** — the agent drives, then saves:
+
+```jsonc
+reticle_record {action:"start"}({ recordingName: "create-task" })
+reticle_act({ ref: "e7", action: "click" })        // … drive the golden path …
+reticle_record {action:"stop"}({ recordingName: "create-task" })
+reticle_flow_save({ flowName: "create-task" })          // → .reticle/flows/create-task.json
+```
+
+**(b) Human-recorded (the recorder toolbar)** — with the presenter on (`present: true`), the floating panel hosts a recorder: a human clicks the golden path in the page and Reticle captures each interaction as a **semantic-anchored** step (testid, else role+name), then persists it via `reticle_flow_save_recorded`. The agent then runs and maintains it. _(First cut: structured annotations only — see below; free natural-language annotations are future work.)_
+
+### What a flow file looks like
+
+```jsonc
+{
+  "version": 1,
+  "name": "create-task",
+  "steps": [
+    { "tool": "reticle_act", "anchor": { "testid": "add-task" }, "action": "click" },
+    {
+      "tool": "reticle_act",
+      "anchor": { "testid": "add-task" },
+      "action": "click",
+      "expect": { "signal": "task:added" },
+    },
+  ],
+  "dynamic": [], // anchors whose CONTENT must not be asserted (LLM output)
+  "success": { "signal": "saved" },
+}
+```
+
+Each step binds to a **semantic anchor**, never a `eXX` ref: a `testid`/`signal` when available, else an auto-derived `component` anchor (component name + source `file:line`) for an element with no testid — so the flow stays stable with zero hand-added testids. Only when none of those resolve is a step kept `degraded: true` (a last-resort "add a testid here" marker) rather than silently dropped.
+
+## Run a flow
+
+```jsonc
+reticle_flow {action:"list"}()                                    // → flows on disk
+reticle_flow {action:"load"}({ flowName: "create-task" })   // → the flow JSON
+reticle_flow_replay({ flowName: "create-task" }) // re-resolve each anchor against the LIVE DOM, run it
+```
+
+**Watch it replay on the page.** When the presenter is on (`present: true`), a replay isn't silent — each step drives the real page, so the synthetic cursor flies to the element, the focus ring lands, and the activity log streams the journey live. You (or a teammate) literally watch the saved journey re-walk itself on your app, then see the verdict land. It's the fastest way to _see_ that a flow still works — not just read a green checkmark.
+
+`reticle_flow_replay` returns a status:
+
+- `ok` — every anchor resolved and every `expect` held.
+- `drift` — an anchor missed (a testid was renamed, or a signal never fired). The result is **legible**: `{ step, anchor, drift: { reasonKind: "testid_not_found", nearest: "send-message" } }` — never a blind failure. (This is the "whose fault is it" principle.)
+- `error` — the flow file is missing/invalid, or a resolved action failed. Runtime failures include the failed step and a top-level error envelope.
+
+A testid-_preserving_ refactor (you moved markup but kept the testids) still replays green. A step whose element has **no testid** is anchored on its component + source location (`{ kind: "component", component, source: { file, line } }`) — an auto-derived stable anchor, so a flow records cleanly with zero hand-added testids and replay re-resolves it via `reticle_query by:'component'`.
+
+### The decision envelope — what to do next, not just pass/fail
+
+On a `drift` or `error`, the replay result carries a `decision` an agent can act on directly:
+
+```jsonc
+decision: {
+  verdict: "drift",
+  whatChanged: "testid \"fault-500\" not found",
+  whereInSource: "src/Diagnostics.tsx:16",   // file:line, from the component/source anchor
+  suggestedFix: "rebind the anchor to \"fault-404\" (closest survivor)",
+  nextAction: "rebind the anchor to \"fault-404\", or update the flow if the change was intended."
+}
+```
+
+This is the feedback a human reviewer used to give — made machine-actionable, so the agent decides its next move without one.
+
+## Verify the whole suite in one call
+
+`reticle_flow_verify` replays **every** saved flow (or a named subset) deterministically — no LLM per flow — and returns one consolidated verdict. This is the regression check to run after any change:
+
+```jsonc
+reticle_flow_verify()
+// → { status: "fail", total: 4, passed: 3, failed: 1,
+//     summary: "3/4 flows pass — 1 needs attention: ship-deploy",
+//     failures: [{ flow: "ship-deploy", verdict: "drift",
+//                  whatChanged: "...", whereInSource: "src/...:NN", nextAction: "..." }] }
+```
+
+Passing flows are counted; only failures carry detail (token-cheap). Build → `reticle_flow_verify` → fix from each failure's `nextAction` → repeat — the autonomous regression loop.
+
+## Self-healing — the agent maintains the flow
+
+When a testid is renamed, the flow drifts. `reticle_flow_heal` proposes — and optionally applies — the nearest-match rebind, so flows don't rot:
+
+```jsonc
+reticle_flow_heal({ flowName: "create-task" })               // PROPOSE only — never writes
+// → { status: "drift", applied: false,
+//     proposals: [{ step: 0, from: "add-tassk", to: "add-task", confidence: 0.8 }] }
+
+reticle_flow_heal({ flowName: "create-task", apply: true })  // rewrite the anchor on disk
+// → { status: "healed", applied: true, proposals: [...] }
+```
+
+With `apply: false` the flow file is **never modified** — you get the proposed diff to review. With `apply: true` Reticle rewrites the drifted anchor(s) to the confident nearest match and a subsequent replay passes. A drift with **no** confident nearest match leaves the file untouched.
+
+## Annotations (structured)
+
+`reticle_annotate` attaches a structured annotation that compiles into the flow, so replay is a _checked_ re-run, not a blind macro:
+
+- `assert-signal` / `assert-visible` → a step `expect` predicate (the invariant).
+- `mark-dynamic` → a `flow.dynamic[]` entry — replay asserts the region's _presence_ but **not its words** (the LLM-output case: assert `caption:generated`, ignore the caption text).
+- `success-state` → `flow.success` (the golden end condition). Pass `signal`/`testid`, or `statePath` (+ `store`, `equals`) to make the golden condition a **store-truth** assertion — the app's own source of truth, which no DOM read can reach (e.g. `statePath: "deployments.0.status", equals: "live"` fails the flow if a deploy only _looks_ shipped on screen). State assertions are graded as consequences, so they satisfy the business-outcome oracle.
+
+## Flows are your test suite
+
+`.reticle/` flows can be executed as CI specs — replayed with their `expect`/`success` predicates, skipping `dynamic` regions — via `@reticlehq/test`'s `flowsAsSpecs`. See [Testing with Reticle](testing.md).
+
+## Tool reference
+
+| Tool | Args | Returns |
+| --- | --- | --- |
+| `reticle_contract_save` | `{ sessionId? }` | writes `.reticle/contract.json` |
+| `reticle_record {action:"start"}` / `reticle_record {action:"stop"}` | `{ recordingName }` | start/stop capturing the agent's acts |
+| `reticle_flow_save` | `{ flowName }` | persist the recording → `.reticle/flows/<flowName>.json` |
+| `reticle_flow_save_recorded` | `{ flowName? }` | persist a human-recorded (toolbar) flow |
+| `reticle_flow {action:"list"}` | `{}` | flows on disk |
+| `reticle_flow {action:"load"}` | `{ flowName }` | the flow JSON |
+| `reticle_flow_replay` | `{ flowName }` | `{ status, steps, decision? }` (decision on drift/fail) |
+| `reticle_flow_verify` | `{ names?, sessionId? }` | suite verdict `{ status, passed, failed, failures[] }` |
+| `reticle_flow_heal` | `{ flowName, apply? }` | propose / apply nearest-match rebind |
+| `reticle_annotate` | `{ kind, … }` | compile a structured annotation into the flow |
+
+> Flow `name` must be a single safe path segment (no `/`, `\`, `..`, or leading dot).