@reticlehq/server 2.6.0 → 2.8.0

package/docs/packages/tauri.mdx

@@ -0,0 +1,63 @@
+---
+title: 'reticle-tauri'
+description: The Rust crate that gives a Tauri app Reticle screenshots and headless mode.
+icon: rust
+---
+
+`reticle-tauri` is a Rust crate on crates.io, not an npm package. It is versioned **independently** of the ten npm packages, and is currently **0.1.0**.
+
+**MIT licensed, unlike the Apache 2.0 npm packages. Edition 2021.**
+
+## Why it exists, and why it is small
+
+Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')` already reaches Reticle as `ipc://load_todos` through the SDK in the webview. You only need this crate for two things: screenshots, and headless mode.
+
+<Warning>
+  Do not expect this to be version `2.7`. Matching the npm version would imply a release cadence the
+  crate does not have, and it would make every npm release a crates.io release for no reason.
+</Warning>
+
+## Install
+
+```toml
+[dependencies]
+reticle-tauri = "0.1"
+```
+
+Its own dependencies are `tauri = "2"` plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.
+
+## Wiring
+
+```rust
+tauri::Builder::default()
+    .invoke_handler(tauri::generate_handler![reticle_tauri::reticle_capture])
+    .on_page_load(reticle_tauri::on_page_load)
+```
+
+Nothing is needed on the JavaScript side. Tauri has no preload stage, so the SDK reaches `reticle_capture` through Tauri's own internals.
+
+## The public API
+
+| Item | Signature |
+| --- | --- |
+| `reticle_capture` | `#[tauri::command] pub async fn reticle_capture(window: tauri::WebviewWindow, full_page: Option<bool>) -> Result<String, String>` |
+| `on_page_load` | `pub fn on_page_load<R: Runtime>(webview: &Webview<R>, payload: &tauri::webview::PageLoadPayload<'_>)` |
+| `FULL_PAGE_UNSUPPORTED` | `pub const FULL_PAGE_UNSUPPORTED: &str = "full-page-unsupported"` |
+
+There are no public traits and no macros.
+
+### `reticle_capture`
+
+Runs on a blocking thread, writes a PNG into a temporary directory as `reticle-capture-<nanos>.png`, and returns the **path**, not the bytes. Full-page capture is supported on Linux only; elsewhere it returns `FULL_PAGE_UNSUPPORTED`, which is pinned to core's `VisualReason` value so the refusal is the same string everywhere.
+
+### `on_page_load`
+
+Hides the window on `PageLoadEvent::Finished` when the environment variable `RETICLE_HEADLESS=1` is set. That ordering matters: the window exists and renders, then it is hidden, so the capture path still works.
+
+## The silent failure to know about
+
+A Tauri app with the default CSP runs perfectly and never connects to Reticle, with nothing said anywhere. [`reticle doctor`](/cli/doctor) diagnoses this explicitly on a desktop project, because it is invisible otherwise.
+
+<Card title="Desktop setup in full" icon="display" href="/desktop-apps">
+  The CSP entry, the headless flag, and how capture differs from a browser screenshot.
+</Card>

package/docs/packages/test.mdx

@@ -0,0 +1,108 @@
+---
+title: '@reticlehq/test'
+description: The Reticle spec runner for CI, driving the tools directly with no MCP or stdio in the loop.
+icon: vial
+---
+
+`@reticlehq/test` turns an interactive session into a suite that runs on every pull request, without an agent and without paying model tokens to re-derive the same checks.
+
+**Version 2.8.0. Licensed under `SEE LICENSE IN LICENSE`. Depends on `@reticlehq/core` and `@reticlehq/server`. Optional peer dependency: `vitest ^3.2.6`.**
+
+```bash
+npm i -D @reticlehq/test
+```
+
+## Why it exists
+
+Driving interactively is reconnaissance. At some point you want the same checks to run unattended. This package invokes the tool layer directly, so a spec is the same evidence an agent would have gathered, minus the model.
+
+## Booting a session
+
+```ts
+import { bootSession, createTestContext, runSpecs, printSummary } from '@reticlehq/test';
+
+const run = await bootSession({ driveUrl: 'http://localhost:5173' });
+const { results, summary } = await runSpecs({
+  invoke: run.invoke,
+  buildContext: (invoke) => createTestContext(invoke),
+  now: () => Date.now(),
+});
+printSummary(summary);
+await run.close();
+```
+
+### `BootOptions`
+
+| Option        | Type                                  | Default                 |
+| ------------- | ------------------------------------- | ----------------------- |
+| `driveUrl`    | `string`                              | required                |
+| `headless`    | `boolean`                             | `true`                  |
+| `port`        | `number`                              | the default bridge port |
+| `reticleRoot` | `string`                              | `cwd()/.reticle`        |
+| `now`         | `() => number`                        | `Date.now`              |
+| `buildDeps`   | `(server: RunningServer) => ToolDeps` | built in                |
+
+`bootSession` resolves to `BootedRun`: `{ invoke: ToolInvoker; close: () => Promise<void> }`.
+
+## Writing specs
+
+```ts
+import { reticleTest } from '@reticlehq/test';
+
+reticleTest('login grants a session', async (t) => {
+  await t.fill('email', 'user@example.com');
+  await t.fill('password', 'hunter2');
+  await t.actAndWait('login-submit', 'click', { kind: 'signal', name: 'auth:granted' });
+  await t.expectNet('POST', '/api/session', 200);
+  await t.expectNoConsoleErrors();
+});
+```
+
+`reticleTest(name: string, fn: SpecFn): void` registers into a module-level registry. `register`, `getRegistered` and `clearRegistry` are exported for anyone driving it themselves.
+
+## The test context
+
+`createTestContext(invoke: ToolInvoker, options?: TestContextOptions): TestContext`, where `TestContextOptions` is `{ sessionId?: string; defaultTimeoutMs?: number }` and the timeout defaults to `DEFAULT_ASSERT_TIMEOUT_MS`.
+
+| Method | Signature |
+| --- | --- |
+| `act` | `(testid: string, action: ActionType, args?: Record<string, unknown>) => Promise<void>` |
+| `fill` | `(testid: string, value: string) => Promise<void>` |
+| `actAndWait` | `(testid: string, action: ActionType, until: Predicate) => Promise<void>` |
+| `expectSignal` | `(name: string, dataMatches?: Record<string, unknown>) => Promise<void>` |
+| `expectNet` | `(method: string, urlContains: string, status?: number) => Promise<void>` |
+| `expectElement` | `(query: ElementQuery, state?: ElementState) => Promise<void>` |
+| `expectText` | `(contains: string) => Promise<void>` |
+| `expectAbsent` | `(query: ElementQuery) => Promise<void>` |
+| `expectNoConsoleErrors` | `() => Promise<void>` |
+| `state` | `(storeOrRef: string) => Promise<unknown>` |
+| `expectInputModeReal` | `() => Promise<void>` |
+| `invoke` | The raw `ToolInvoker` |
+| `clock` | `TestClock` |
+
+## Running and reporting
+
+| Export | Signature |
+| --- | --- |
+| `runOne` | `(spec: ReticleSpec, opts: RunnerOptions) => Promise<SpecResult>` |
+| `runSpecs` | `(opts: RunnerOptions) => Promise<{ results: SpecResult[]; summary: RunSummary }>` |
+| `summarize` / `printSummary` | Build and print the summary |
+| `toJUnitXml` / `writeJUnit` | JUnit output for CI |
+
+`RunnerOptions` is `{ invoke; buildContext; now; print?; specs? }`. `RunSummary` is `{ total, passed, failed, skipped, ok }`.
+
+## Saved flows as specs
+
+A recorded flow becomes a spec without being rewritten:
+
+`flowToSpec`, `flowsAsSpecs`, `registerFlowSpecs`, with `assertSuccess`, `successToPredicate`, and the `FlowSpec`, `FlowSpecOptions` and `FlowsAsSpecsOptions` types. Malformed flows raise `FlowMalformedError`.
+
+## Errors and control flow
+
+`ReticleSkip` and `isSkip` for skipping, `ReticleAssertionError` with an `AssertionDetail`, `ReticleQueryEmptyError` when a query matched nothing.
+
+Constants: `TestStatus`, `SpecKind`, `SpecOutcome`, `SpecMessage`, `PredicateKind`, `STATUS_GLYPH`, `JUnit`, `SKIP_REASON_REAL_INPUT`, `PROBE_TESTID`.
+
+<Card title="Turning a session into a suite" icon="flask" href="/testing">
+  Writing specs that bind to signals rather than DOM structure.
+</Card>

package/docs/packages/vite-plugin.mdx

@@ -0,0 +1,96 @@
+---
+title: '@reticlehq/vite-plugin'
+description: One line in vite.config.ts that stamps source locations on your JSX and auto-injects reticle.connect().
+icon: bolt
+---
+
+`@reticlehq/vite-plugin` does the two things everyone forgets: wiring the SDK, and enabling source mapping.
+
+**Version 2.8.0. Apache 2.0. Depends on `@babel/core`, `@reticlehq/babel-plugin` and `@reticlehq/core`. Optional peer dependency: `vite >= 4`.**
+
+## Install and use
+
+```bash
+npm i -D @reticlehq/vite-plugin @reticlehq/react
+```
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { reticle } from '@reticlehq/vite-plugin';
+
+export default defineConfig({
+  plugins: [reticle(), react()],
+});
+```
+
+<Warning>
+  The import specifier is `@reticlehq/vite-plugin` and the export is `reticle`. An old README
+  documented `@reticlehq/core/vite`; that subpath has never existed in core's exports map, and `npx
+  @reticlehq/core init` is not a command either. The binary is `reticle`, from
+  [`@reticlehq/server`](/packages/server).
+</Warning>
+
+## Why it exists
+
+`apply: 'serve'` means it never reaches a production build. That is the guarantee that lets you leave it in the config permanently: there is no way to ship Reticle to your users by forgetting to remove a line.
+
+## What it injects
+
+A virtual module at `/@reticle-connect`, added to the HTML, whose contents are:
+
+```ts
+import { reticle, install } from '@reticlehq/react';
+install();
+reticle.connect({
+  /* resolved args */
+});
+```
+
+Plus a dynamic import of your dev module if one exists. It looks for `src/reticle-dev.ts`, `.js`, `.tsx` or `.jsx`, in that order, and leaves the file alone if you have one: that file is yours to edit.
+
+## Options
+
+`reticle(options?: ReticleVitePluginOptions): ReticleVitePlugin`. Every option is optional.
+
+| Option | Type | Default |
+| --- | --- | --- |
+| `port` | `number` | Discovered from the daemon registry for this project, falling back to `4400` |
+| `root` | `string` | Vite's `root`, else `process.cwd()` |
+| `sdkVersion` | `string` | Read from the installed `@reticlehq/react` |
+| `session` | `string` | Omitted, so the SDK generates one |
+| `projectId` | `string` | Derived from the package name plus the root path |
+| `token` | `string` | `readPairingToken()`, from `~/.reticle/pairing-token` |
+| `sourceMapping` | `boolean` | `true`. Set `false` to skip the Babel pass |
+| `inject` | `boolean` | `true`. Set `false` to call `connect()` yourself |
+| `desktop` | `boolean` | `false`. When `true` the plugin also applies to `vite build` and passes `allowInProduction: true`, which is what an Electron or Tauri renderer needs |
+| `captureNetworkBodies` | `boolean` | `false`. Also enabled by `VITE_RETICLE_CAPTURE_BODIES=1` |
+| `onWarn` | `(message: string) => void` | `console.warn` |
+
+## Other exports
+
+| Export | Type | What it is |
+| --- | --- | --- |
+| `RETICLE_VITE_PLUGIN_NAME` | `'reticle'` | The plugin name |
+| `RETICLE_TOKEN_GLOBAL` | `'__RETICLE_TOKEN__'` | The global the token is stamped onto |
+| `RETICLE_CONNECT_MODULE` | `'/@reticle-connect'` | The virtual module id |
+| `RENDER_PREHOOK_SOURCE` | `string` | The inline render prehook snippet |
+| `RETICLE_DEV_MODULE_CANDIDATES` | readonly tuple | The four dev-module paths it looks for |
+| `readPairingToken` | `() => string \| undefined` | Read the pairing token from disk |
+| `findDevModule` | `(root: string, exists: (p: string) => boolean) => string \| null` | Locate the dev module |
+| `connectModuleSource` | `(options: ReticleVitePluginOptions, devModule?: string \| null) => string` | Build the injected module source |
+| `cjsDepIncludes` | `(appRoot: string, canResolve?: (dep: string) => boolean) => string[]` | CommonJS deps to add to `optimizeDeps` |
+
+Types: `ReticleVitePluginOptions`, `ReticleVitePlugin`, `ViteDevServerLike`.
+
+## Desktop
+
+```ts
+reticle({ desktop: true });
+```
+
+A packaged Electron or Tauri renderer is a production build loaded from a custom protocol, so the default guards would refuse. This one flag drops `apply: 'serve'` and opts the connect call into production.
+
+<Card title="Desktop wiring in full" icon="display" href="/desktop-apps">
+  Including the Tauri CSP whose failure is completely silent.
+</Card>

package/docs/packages.mdx

@@ -0,0 +1,217 @@
+---
+title: Packages: what is in the box
+sidebarTitle: Packages
+description: Every Reticle package. What it does, why it exists, when you actually need it, and what it depends on.
+icon: cubes
+---
+
+Reticle is eleven packages, and most people install two. This page exists so you can tell which two, and so that the ones you skip stop looking mysterious.
+
+<Note>
+  Ten npm packages ship together at the same version, all at **2.8.0**, verified against the
+  registry. The Rust crate is versioned **independently** and is currently **0.1.0**. That is
+  deliberate, not drift.
+</Note>
+
+## Which ones do I need?
+
+<CardGroup cols={2}>
+  <Card title="A React app on Vite" icon="bolt">
+    `@reticlehq/react` + `@reticlehq/vite-plugin`. That's it, two dev dependencies.
+  </Card>
+  <Card title="A React app on Next.js" icon="n">
+    `@reticlehq/react` + `@reticlehq/next`. Keeps SWC; no Babel migration.
+  </Card>
+  <Card title="Not React, or no bundler plugin" icon="code">
+    `@reticlehq/browser` alone, and call `connect()` yourself.
+  </Card>
+  <Card title="Electron or Tauri" icon="display">
+    The web packages, plus `@reticlehq/electron` or the `reticle-tauri` crate.
+  </Card>
+</CardGroup>
+
+You never install `@reticlehq/server`. Your agent runs it with `npx`.
+
+## The architecture in one rule
+
+The package split is not cosmetic. Each boundary enforces something:
+
+| Package   | Runs in     | Hard rule                                              |
+| --------- | ----------- | ------------------------------------------------------ |
+| `core`    | both        | Depends only on `zod`. Sits at the bottom of the graph |
+| `browser` | the browser | Never imports a Node API                               |
+| `server`  | Node        | Never imports a DOM API                                |
+| `react`   | the browser | Optional. Core must work without it                    |
+
+Those rules are why the browser SDK cannot accidentally pull in a filesystem call, and why the server cannot accidentally depend on `window`. They are enforced by the dependency graph, not by discipline.
+
+---
+
+## @reticlehq/core
+
+**The wire contract.** Every constant and zod schema that crosses a boundary. Browser to bridge, bridge to agent, is defined here.
+
+**Why it exists:** without one shared definition, the browser and the server drift. One renames a field, the other keeps reading the old one, and the failure is silent. A verdict that quietly stops carrying evidence. Core makes that a type error instead.
+
+**Depends on:** `zod`, and nothing else. That is the whole point; it sits at the bottom of the graph so everything can depend on it without cycles.
+
+**Do you install it?** No. It arrives as a dependency of whatever you did install.
+
+<Note>
+  Before 2.0, `@reticlehq/core` was an umbrella package re-exporting everything under subpaths. That
+  was retired: the umbrella meant every consumer pulled the whole world to get one constant.
+</Note>
+
+---
+
+## @reticlehq/browser
+
+**The SDK that lives in your page.** It installs the observers (DOM, network, console, routing, animations), builds semantic snapshots, executes actions, and talks to the bridge.
+
+**Why it exists:** this is the part that makes Reticle different from a browser-automation tool. Because it runs _inside_ the app rather than driving it from outside, it can see a state mutation and a fired signal, not just a rendered pixel.
+
+**Depends on:** `@reticlehq/core`, `@testing-library/dom`. The latter is why [`reticle_query`](/tools-query) speaks role, label and testid rather than CSS selectors.
+
+**Install it directly when** you are not on React, or you want `connect()` under your own control:
+
+```ts
+import { reticle } from '@reticlehq/browser';
+if (import.meta.env.DEV) reticle.connect();
+```
+
+---
+
+## @reticlehq/server
+
+**The bridge, the MCP server, and the `reticle` CLI.** Hosts the WebSocket your app dials into and exposes the tools your agent calls.
+
+**Why it exists:** agents speak MCP; browsers speak WebSocket; somebody has to be fluent in both and own the `.reticle/` directory where flows, baselines and runs are stored.
+
+**Depends on:** `@modelcontextprotocol/sdk`, `@reticlehq/core`, `ws`, `zod`.
+
+**Do you install it?** Not into your project. Your agent launches it:
+
+```bash
+npx @reticlehq/server mcp
+```
+
+---
+
+## @reticlehq/react
+
+**The kit most React users install.** It re-exports the browser sensor. So one install gives you both `reticle` and `registerCapabilities`. And maps a DOM node to its React component and source file through the fiber tree.
+
+**Why it exists:** this is the package that turns "the button is broken" into `src/components/Login.tsx:81`. Finding a bug is half the job. Reticle's answer to the other half lives here.
+
+**Depends on:** `@reticlehq/browser`, `@reticlehq/core`. **Peer:** `react`.
+
+```bash
+npm i -D @reticlehq/react
+```
+
+---
+
+## @reticlehq/vite-plugin
+
+**One line in `vite.config.ts`, two jobs.** It stamps source locations onto your JSX and injects `connect()` so you cannot forget to.
+
+**Why it exists:** the two things everyone forgets are wiring the SDK and enabling source mapping. This does both, and `apply: 'serve'` guarantees it never reaches a production build.
+
+**Depends on:** `@babel/core`, `@reticlehq/babel-plugin`, `@reticlehq/core`. **Peer:** `vite`.
+
+```ts
+import { reticle } from '@reticlehq/vite-plugin';
+export default defineConfig({ plugins: [reticle(), react()] });
+```
+
+---
+
+## @reticlehq/babel-plugin
+
+**Stamps `data-reticle-source="file:line:col"` onto JSX host elements.**
+
+**Why it exists:** React 19 dropped `_debugSource`, which is what source mapping used to rely on. This plugin puts the information back, at build time, in dev only. Without it, `reticle_inspect` can still tell you the component name but not the file.
+
+**Depends on:** nothing. **Peer:** `@babel/core`.
+
+**Do you install it?** Only directly if you are wiring Babel yourself. The Vite and Next packages both pull it in.
+
+---
+
+## @reticlehq/next
+
+**Next.js source mapping without giving up SWC.**
+
+**Why it exists:** Next users are on SWC, and telling them to switch to Babel for a dev tool would be a rude trade. This adds a dev-only webpack pre-loader that stamps the same attribute, and leaves your build pipeline alone.
+
+**Depends on:** `@babel/core`, `@reticlehq/babel-plugin`. **Peer:** `next`.
+
+```js
+const { withReticle } = require('@reticlehq/next');
+module.exports = withReticle({
+  /* your config */
+});
+```
+
+<Note>
+  This one is CommonJS on purpose. `next.config.js` is loaded by Node before any ESM transform, so
+  an ESM-only helper would fail at the least helpful moment.
+</Note>
+
+---
+
+## @reticlehq/test
+
+**The spec runner for CI.** `reticleTest` registers declarative specs and runs them against Reticle's tools directly, with no MCP or stdio in the loop.
+
+**Why it exists:** driving interactively is reconnaissance. At some point you want the same checks to run on every pull request without an agent. And without paying model tokens to re-derive them.
+
+**Depends on:** `@reticlehq/core`, `@reticlehq/server`. **Peer:** `vitest`.
+
+<Card title="Turn a session into a suite" icon="vial" href="/testing">
+  Writing specs that bind to signals rather than DOM structure.
+</Card>
+
+---
+
+## @reticlehq/eslint-plugin
+
+**One rule: state changed, so a signal must fire.**
+
+**Why it exists:** signals are the strongest evidence Reticle can use, and they rot the way all conventions rot. Someone adds a mutation, forgets the signal, and every verdict for that flow quietly drops a grade. Nothing breaks. The tests still pass. The evidence just gets weaker.
+
+A lint rule makes the signal layer self-enforcing, which is the only way a convention survives contact with a deadline.
+
+**Depends on:** `@typescript-eslint/utils`. **Peer:** `eslint`.
+
+---
+
+## @reticlehq/electron
+
+**Reaches the two places the renderer cannot.**
+
+**Why it exists:** in Electron, the interesting failures often happen across the IPC boundary. The renderer asks the main process for something and the main process quietly fails. The renderer-side SDK cannot see that. This package makes main-process IPC observable and the window screenshottable.
+
+**Depends on:** `@reticlehq/core`. **Peer:** `electron`.
+
+---
+
+## reticle-tauri
+
+**The Rust crate**, on crates.io, currently **0.1.0**. Versioned independently of the npm packages.
+
+**Why it exists:** Tauri IPC observation needs nothing on the Rust side; an `invoke('load_todos')` already reaches Reticle as `ipc://load_todos`. You only need this crate for screenshots and headless mode.
+
+```toml
+[dependencies]
+reticle-tauri = "0.1"
+```
+
+<Warning>
+  Do not expect this to be `2.7`. Matching the npm version would imply a release cadence the crate
+  does not have, and it would make every npm release a crates.io release for no reason.
+</Warning>
+
+<Card title="Desktop setup in full" icon="display" href="/desktop-apps">
+  Electron and Tauri wiring, including the Tauri CSP whose failure is silent.
+</Card>

package/docs/platform-integration.md

@@ -1,17 +1,24 @@
-# Integrating Reticle
+---
+title: Integrating Reticle
+description: 'Adopt Reticle on your own codebase, or embed it inside an AI app-builder’s generation pipeline.'
+icon: plug
+---
 
-> 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 one guide for adopting Reticle, both 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
+```mermaid
+flowchart TB
+    G["generate / edit"] --> B["boot the preview"]
+    B --> V["Reticle verifies<br/>the critical flows"]
+    V --> R{"verdict + evidence"}
+    R -- "PASS" --> S["ship, and attach<br/>the verified marker"]
+    R -- "FAIL" --> F["gate the deploy<br/>feed repair packets<br/>to the fixer agent"]
+    F --> G
 ```
 
-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.
+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.
 
 ---
 
@@ -28,7 +35,7 @@ Paste to your agent (Claude Code / Cursor / any MCP agent): `Follow https://raw.
 ### B. A platform / CI, driven from your pipeline (no MCP, no human)
 
 ```bash
-reticle serve --http --http-token "$TOKEN" --drive "$PREVIEW_URL"   # localhost:7331
+npx @reticlehq/server serve --http --http-token "$TOKEN" --drive "$PREVIEW_URL"   # localhost:7331
 ```
 
 ```js
@@ -49,21 +56,21 @@ if (run.verdict.status !== 'pass') {
 } 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).
+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
+## 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 |
+| **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 to 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.
+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 and 3 are what no out-of-page tool can see.
 
 ---
 
@@ -71,14 +78,14 @@ Copyable patterns: `apps/bench-app/src/reticle-dev.ts`, `apps/next-smoke/app/ret
 
 | 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 |
+| 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`.
 
@@ -97,8 +104,8 @@ The shape is identical (in-app SDK in the template → verify in the sandbox →
 
 ### 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.
+1. Add the Reticle Vite plugin + dev-only `reticle.connect` to the project template (Lovable already templates Vite/React, so it's one plugin line + the connect file).
+2. Run `npx @reticlehq/server 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)
@@ -115,7 +122,7 @@ The shape is identical (in-app SDK in the template → verify in the sandbox →
 
 `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`.
+**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