@reticlehq/server 2.3.0 → 2.5.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
+@reticle: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/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"]
+    },
+    {
+      "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.

package/docs/platform-integration.md

@@ -0,0 +1,122 @@
+# Integrating Reticle
+
+> The one guide for adopting Reticle — for a team using a coding agent on its own app, and for an AI app-builder platform (Lovable / Emergent / Bolt) embedding Reticle in its generation pipeline. Reticle reads the program from _inside_ a running app and returns a **verdict with evidence** ("did it actually work?"), not a screenshot. Enterprise/premium access lives in [`enterprise.md`](./enterprise.md).
+
+## The loop
+
+```
+generate / edit  →  boot the preview  →  Reticle verifies the critical flows  →  verdict + evidence + repair
+                                                                                │
+                                         PASS → ship & attach "verified ✓"      │
+                                         FAIL → gate the deploy, feed repair packets to the fixer agent
+```
+
+One call replays the app's key journeys and asserts **program truth** — network cardinality, store/state, emitted signals, console — then returns a deterministic, un-hallucinatable verdict.
+
+---
+
+## Quickstart
+
+### A. A team, agent on your own app (~10 min)
+
+```bash
+npx @reticlehq/server init   # auto-detects your framework, installs the kit + build plugin
+```
+
+Paste to your agent (Claude Code / Cursor / any MCP agent): `Follow https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md` It runs the wizard once (Vite/Next plugin + SDK init + MCP config), then verifies on every change. Run your dev server, then ask the agent to _"verify it with Reticle."_
+
+### B. A platform / CI, driven from your pipeline (no MCP, no human)
+
+```bash
+reticle serve --http --http-token "$TOKEN" --drive "$PREVIEW_URL"   # localhost:7331
+```
+
+```js
+const { run } = await (
+  await fetch('http://127.0.0.1:7331/verify', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-reticle-token': process.env.TOKEN },
+    body: JSON.stringify({
+      project: { name, framework, previewUrl },
+      trigger: { kind: 'oem', diffRef },
+    }),
+  })
+).json();
+
+if (run.verdict.status !== 'pass') {
+  for (const p of run.repair?.failurePackets ?? []) fixerAgent.send(p.suggestedPrompt); // self-heal
+  blockDeploy(run);
+} else attachToDeploy(run); // "verified ✓"; set profile:"prod-preview" to redact internals downstream
+```
+
+Or skip the HTTP server entirely with the one-shot CLI — `reticle verify <preview-url>` drives the preview, replays the saved flows, prints the verdict, and exits non-zero on fail (ideal for a CI step).
+
+---
+
+## In-app SDK integration — the effort, by layer
+
+Reticle embeds a **dev/preview-only** SDK (`@reticlehq/browser`, Apache-2.0, tree-shaken from production). For a platform you add this **once to your generated-app template** → every generated app is verifiable.
+
+| Layer | What you add | Unlocks | Effort |
+| --- | --- | --- | --- |
+| **1 — drive + DOM/network/console** | 1 build-plugin line + ~10-line dev-only `reticle.connect({…})` file (`npx @reticlehq/server init` does it) | broken routes, network status/cardinality (double-submit), console errors, persistence-after-reload | **Easy** (~15 min) |
+| **2 — program-state truth** | `registerStore('app', store)` (1/store, pass the store itself so mutations emit diffs) + `reticle.signal('order:saved', …)` (1/consequence) + `data-testid`s | UI-vs-store desync, dead handlers, blast-radius, source mapping | **Easy–Medium** (an afternoon, once) |
+| **3 — governance (optional)** | `registerCapabilities(...)` (signals/stores/risk zones) + recorded flows with success oracles | risk policy + sharper verdicts | **Medium**, optional |
+
+Copyable patterns: `apps/bench-app/src/reticle-dev.ts`, `apps/next-smoke/app/reticle-dev.tsx`. Without instrumentation, Layer-1 checks still work via the driven browser; Layers 2–3 are what no out-of-page tool can see.
+
+---
+
+## What it catches that a screenshot can't
+
+| Silent failure (a generated app ships it) | How Reticle catches it |
+| --- | --- |
+| Mock data — POST 200, row shows, nothing persists | persistence/`state` oracle (doesn't survive reload) |
+| Dead handler — looks done, store never changed | `state` desync |
+| Double-submit — one click, two POSTs | `net { count: 1 }` |
+| Forbidden call — a must-never-fire endpoint fired | `net { count: 0 }` |
+| Missing validation — `"abc"` becomes data | flow oracle (error shown AND nothing created) |
+| Silent console error — logged, UI still renders | `console { absent: true }` |
+| UI-vs-store desync — the total lies | reads the store, contradicts the display |
+| Blast-radius — an action corrupts unrelated state | `state { hold:true }` invariant |
+
+Live, clickable demo of each: `apps/vibe-builder-demo/` (set `BUG_MODE=…`). Proven in CI: `packages/server/src/runs/generated-app-bugs.test.ts`.
+
+---
+
+## Exact steps per platform
+
+The shape is identical (in-app SDK in the template → verify in the sandbox → act on the verdict); the specifics differ by where each platform runs the preview.
+
+### Emergent (Kubernetes pod per build, reverse-proxied preview URL)
+
+1. Add `@reticlehq/browser` + `registerStore`/`reticle.signal` to the generated-app **scaffold** (one time).
+2. In the build pod, alongside the preview: `reticle serve --http --http-token "$POD_TOKEN" --drive "$PREVIEW_URL"` (or import `ReticleRunner` in-process).
+3. In the orchestrator's generate→test→iterate loop, `POST /verify` after the preview boots.
+4. FAIL → route `repair.failurePackets[].suggestedPrompt` to the fixer subagent → re-verify (closes the loop). PASS → publish + attach the `prod-preview` run as the user-facing "verified ✓".
+
+### Lovable (Vite/React generated apps, hosted preview)
+
+1. Add the Reticle Vite plugin + dev-only `reticle.connect` to the project template (Lovable already templates Vite/React — it's one plugin line + the connect file).
+2. Run `reticle serve --http --drive <preview-url>` against the preview build in the generation worker.
+3. Call `/verify` after each generate/edit; gate the "your app is ready" signal on `verdict.status === 'pass'`; feed repair packets back into the edit agent.
+
+### Bolt.new / StackBlitz (WebContainer, in-browser runtime)
+
+1. Add the SDK to the WebContainer app template; the app + Reticle bridge run in the WebContainer.
+2. Since the runtime is in-browser, drive via the connected session (the SDK dials the bridge) rather than `--drive`; call verify from the Bolt agent after a build.
+3. Same act-on-verdict: gate + self-heal with the repair packets. (Bolt already detects terminal/compile errors; Reticle adds the _runtime program-truth_ layer it's blind to.)
+
+> Honest note: a platform can build a verification step itself. Reticle's case is the depth (program-state and source mapping), the determinism (0% flake, no LLM in the loop), the un-hallucinatable verdict, and a stable drop-in artifact. The reproducible benchmark in [`bench/`](../bench/README.md) measures the observation-cost and detection differences against other browser-automation MCPs.
+
+---
+
+## The verdict artifact
+
+`POST /verify` (and `reticle_run_export`) return a stable, versioned `ReticleVerificationRun` (defined in `@reticlehq/core`): `verdict` (pass/fail/partial, confidence, blockingRisks), `flows[]`, `checks[]`, `risks[]` (auth/payment/db/…), `repair.failurePackets[]` (what + where to fix), `evidence`. Render a legible report with `renderRunReport()` or `reticle_run_export { format: "report" }`. Profiles: `dev` (full) vs `prod-preview` (source + state redacted for downstream sharing).
+
+**Why trust it:** the verdict is mechanical — derived only from observed outcomes — so it can't report green for something it never ran (a severed backend reads as _fail_, never a confident pass). Proof: `packages/server/src/runs/false-green.test.ts`.
+
+## Licensing for embedding
+
+The embeddable SDK is **Apache-2.0** (ship it in your customers' apps). The server/CLI is **FSL** (free, no competing resale). Enterprise features + the premium-access flow: [`enterprise.md`](./enterprise.md). OEM terms: **[hey@reticle.sh](mailto:hey@reticle.sh)**.