@reticlehq/server 2.7.0 → 2.9.0

package/docs/platform-integration.md

@@ -1,17 +1,26 @@
-# 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).
+Two ways in. **A team** runs `npx @reticlehq/server init` once and points its coding agent at the MCP server. **A platform** adds the dev-only SDK to its generated-app template, runs `npx @reticlehq/server serve --http --drive <preview-url>` beside each preview, and `POST`s to `/verify` after every generate or edit, gating the ship on `run.verdict.status === 'pass'` and feeding `run.repair.failurePackets[]` back to a fixer agent.
+
+> 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 +37,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 +58,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 +80,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 +106,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 +124,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
 

package/docs/predicates.mdx

@@ -0,0 +1,248 @@
+---
+title: 'Predicate reference: the grammar of green'
+sidebarTitle: Predicates
+description: The grammar for declaring what should be true. Every kind, every field, and which ones actually prove something.
+icon: filter
+---
+
+A predicate declares what should be true, as `{ kind, ...fields }`. Reticle has twelve kinds: `signal`, `state`, `net`, `route`, `element`, `text`, `console`, `animation`, `settled`, and the combinators `allOf`, `anyOf` and `not`. Which one you pick decides whether a green means anything.
+
+It is the argument to `until` on [`reticle_act_and_wait`](/tools-act-and-wait), and to `predicate` on [`reticle_assert`](/tools-assert) and [`reticle_wait_for`](/tools-wait-for).
+
+Every predicate is `{ kind, ...fields }`.
+
+## Not all predicates prove the same thing
+
+Reticle grades them, and it will tell you when you have chosen a weak one. This is a real response from a `text` assertion:
+
+```json
+{
+  "verified": "yes",
+  "pass": true,
+  "advice": "This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked."
+}
+```
+
+Take the advice. `element` and `text` are convenient and weak; `signal`, `state` and `net` are what make a green trustworthy.
+
+| Kind               | Grade     | Proves                                                 |
+| ------------------ | --------- | ------------------------------------------------------ |
+| `signal`           | strongest | The app declared success in its own words              |
+| `state`            | strong    | A registered store actually changed                    |
+| `net`              | strong    | A specific request fired, with a countable cardinality |
+| `route`            | medium    | Navigation happened                                    |
+| `console`          | medium    | Something logged, or nothing did                       |
+| `element` / `text` | weak      | Something rendered. A mock renders too                 |
+| `animation`        | weak      | An animation ran or finished                           |
+| `settled`          | timing    | The page went quiet. A precondition, not a proof       |
+
+## The leaves
+
+### element
+
+```json
+{
+  "kind": "element",
+  "query": { "role": "dialog", "name": "Confirm" },
+  "state": "visible"
+}
+```
+
+`query` accepts `role`, `name`, `text`, `label`, `placeholder`, `testid`, `alt`, `scope`. `state` is one of `visible`, `hidden`, `enabled`, `disabled`, `checked`, `expanded`, `focused`, `present`.
+
+Add `"absent": true` to assert something is **gone**. The predicate for a removal, a dismissed toast, or a regression check.
+
+### text
+
+```json
+{ "kind": "text", "contains": "Saved successfully", "visible": true }
+```
+
+`contains` is the field the published schema declares. `value` and `text` are accepted as aliases and rewritten to it. `absent: true` asserts the text is not present, and `visible: true` requires it to be on screen rather than merely in the DOM.
+
+### net
+
+```json
+{ "kind": "net", "method": "POST", "urlContains": "/api/order", "status": 200 }
+```
+
+The one that catches the expensive bug:
+
+```json
+{ "kind": "net", "method": "POST", "urlContains": "/api/order", "count": 1 }
+```
+
+**Exactly one.** Double-submit fails at two, and nothing on screen would have told you.
+
+### route
+
+```json
+{ "kind": "route", "pathname": "/success" }
+```
+
+`pathname` matches the path exactly. `contains` matches anywhere in the whole route, path, query and fragment together. `path` is accepted as an alias for `pathname`, and `url` and `urlContains` as aliases for `contains`, but the canonical spellings are the ones above.
+
+A passing route verdict quotes the transition itself:
+
+```json
+"evidence": {
+  "from": "http://localhost:4310/",
+  "to": "http://localhost:4310/deployments",
+  "pathname": "/deployments",
+  "search": "",
+  "hash": ""
+}
+```
+
+<Warning>
+  `route` asserts the route **changed**. Asserting the route you are already on always fails, and
+  the response says so: `expected: "a route change to /"`, `assertion: "route.changed"`.
+</Warning>
+
+### console
+
+```json
+{ "kind": "console", "level": "error", "absent": true }
+```
+
+"The flow completed and logged nothing." Worth attaching to most actions. Plenty of features work while quietly throwing.
+
+### signal
+
+```json
+{ "kind": "signal", "name": "webhook:received", "dataMatches": { "provider": "stripe", "id": "*" } }
+```
+
+The app emitted a named signal via `reticle.signal()`. `dataMatches` is shallow JSON matching, and `*` means "present, any value".
+
+Nothing outranks this. A `200` proves the server was reachable; a rendered row proves React ran. A signal is the application itself saying the thing succeeded. See [instrumentation](/instrumentation) for how to emit them.
+
+### state
+
+```json
+{ "kind": "state", "store": "app", "path": "deployments.0.status", "equals": "live" }
+```
+
+Walks a dot-path, with numeric array indices. `equals` takes a literal, or an operator pattern:
+
+| Operator                  | Meaning                       |
+| ------------------------- | ----------------------------- |
+| `$gte` `$lte` `$gt` `$lt` | numeric comparison            |
+| `$contains`               | substring or array membership |
+| `$length`                 | collection size               |
+
+Omit `equals` entirely to assert presence. A real `$length` check against this fixture:
+
+```json
+{ "kind": "state", "store": "app", "path": "deployments", "equals": { "$length": 40 } }
+```
+
+```json
+{
+  "verified": "yes",
+  "because": "assertion held at state grade over a clean capture with no channel disagreeing",
+  "pass": true,
+  "evidence": { "store": "app", "path": "deployments", "value": ["{…11 keys}", "…"] }
+}
+```
+
+Note `grade: state` in the `because` line, and that the evidence collapses each row to a size marker rather than returning forty objects.
+
+A miss quotes the real value back at you:
+
+```json
+{
+  "pass": false,
+  "failureReason": "state 'deployments.0.status' is \"queued\", expected \"live\"",
+  "observed": "deployments.0.status = \"queued\"",
+  "expected": "deployments.0.status = \"live\"",
+  "assertion": "state.equals",
+  "evidence": { "store": "app", "path": "deployments.0.status", "value": "queued" }
+}
+```
+
+`store` is optional. Leave it out and the path picks the store: if exactly one registered store exposes it, that one is read. Registering several is normal, so this is the common case rather than a shortcut. Name a store when two of them genuinely expose the same path, which is the only situation Reticle cannot resolve on its own. If no store exposes it, that is a failure rather than a question, and the miss names the stores it searched.
+
+This is the predicate that catches a UI-versus-store desync. A deploy that only _looks_ shipped. Deterministically, in one call, with no model involved. On a miss it names the real store value and the keys that were available, so a failure is legible rather than a blind "no".
+
+### animation
+
+```json
+{ "kind": "animation", "name": "dialog-in", "completed": true }
+```
+
+`target` narrows it to one element. `completed: false` matches an animation that is still running.
+
+### settled
+
+```json
+{ "kind": "settled", "quietMs": 500 }
+```
+
+Network and DOM idle. This is the deterministic replacement for a fixed sleep, not a proof of anything: combine it with a real consequence rather than asserting it alone. Omitting `until` on [`reticle_act_and_wait`](/tools-act-and-wait) waits for exactly this.
+
+## Combinators
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [
+    { "kind": "signal", "name": "auth:granted" },
+    { "kind": "net", "method": "POST", "urlContains": "/api/login", "count": 1 },
+    { "kind": "console", "level": "error", "absent": true }
+  ]
+}
+```
+
+```json
+{ "kind": "anyOf", "predicates": [ … ] }
+{ "kind": "not", "predicate": { … } }
+```
+
+<Warning>
+A combinator needs its own `kind`, and the children go in `predicates`. A bare
+`{ "allOf": [ … ] }` does not parse, and neither does `{ "kind": "allOf", "allOf": [ … ] }`.
+
+Reticle refuses the call rather than running half of it. The real refusal names the field, the fix and the consequence: _"predicates: Required; unknown field allOf. Nothing ran, the predicate was not evaluated, so no verdict was produced. allOf accepts: predicates."_ Better to be told than to get a green from an assertion that never executed.
+
+</Warning>
+
+`allOf` is the workhorse. "The signal fired **and** exactly one request went out **and** the console stayed clean" is a genuinely strong check, and it is one call.
+
+Each child reports its own evidence, in order. That is a real verdict for exactly the `allOf` above:
+
+```json
+"evidence": [
+  { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } },
+  { "matched": 1 },
+  { "absent": true }
+]
+```
+
+On a failure each child reports separately too, so you can see which one broke:
+
+```json
+"evidence": [
+  {
+    "pass": false,
+    "expected": "an element matching {\"role\":\"dialog\"} in state 'visible'",
+    "observed": "no matching element on the page",
+    "assertion": "element.present",
+    "evidence": { "presentTestids": ["deploy-table", "filter-search", "env-filter"] }
+  },
+  { "pass": true, "evidence": { "absent": true } }
+]
+```
+
+## Timing and scoping
+
+| Field | Where | What it does |
+| --- | --- | --- |
+| `timeout_ms` | `assert`, `wait_for`, `act_and_wait` | Wait up to N ms for it to become true |
+| `since` | `net` and `console` leaves, and the call itself | Only consider events after this cursor |
+
+The `since` cursor comes from a prior `reticle_act` response. Use it whenever you are asserting something an action was supposed to cause. Without it, an assertion can pass on an event from two clicks ago.
+
+<Card title="Where predicates get used" icon="circle-check" href="/tools-act-and-wait">
+  Naming the consequence before the action is the whole point.
+</Card>

package/docs/quickstart.mdx

@@ -0,0 +1,257 @@
+---
+title: 'Quickstart: proof in five minutes'
+sidebarTitle: Quickstart
+description: Install Reticle, connect your coding agent, and get a real verdict with evidence in about five minutes.
+icon: rocket
+---
+
+**Run `npx @reticlehq/server init` in your project, restart your dev server and your agent, then ask your agent to drive a flow.** That is the whole install. Reticle is a verification layer for AI coding agents: it embeds a dev-only SDK in your running web app so an agent can prove a change works instead of guessing.
+
+By the end of this page your agent will click a button in your app and prove what happened: the request that fired, the state that changed, and the file to open if it didn't.
+
+<Note>
+  Every response on this page is real output, captured against a running app while writing it.
+  Nothing here is illustrative.
+</Note>
+
+## Prerequisites
+
+- Node 20 or newer
+- A web app you can run locally, and its dev server
+- A coding agent that speaks MCP (Claude Code, Cursor, Codex, OpenCode, Windsurf, VS Code)
+
+## Step 1. Let your agent install it
+
+The fastest path is to hand the job to the agent that will use it. In your project directory:
+
+```bash
+npx @reticlehq/server init
+```
+
+This registers the MCP server, installs the SDK, wires it into your app's entry point, and writes the agent rule files. It is idempotent. Run it twice and the second run reports what was already done rather than doing it again.
+
+Prefer to install the skill and let the agent run setup itself? On Claude Code the plugin registers the MCP server and the skill in one step:
+
+```text
+/plugin marketplace add reticlehq/reticle
+/plugin install reticle@reticlehq
+```
+
+On Cursor, Codex, Copilot, Gemini and anything else the skills CLI supports:
+
+```bash
+npx skills add reticlehq/reticle
+```
+
+Then type `/reticle` and the agent runs the install from the skill.
+
+Useful flags, from `reticle init` itself:
+
+```
+reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+              --app picks WHICH app in a monorepo, when several are found
+              --no-mcp skips MORE than the server registration: also the agent rule files
+              (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
+              only make sense once the tools are reachable.
+```
+
+Start with `--dry-run` if you want to see the plan before anything is written.
+
+<Tip>
+  In a monorepo, `init` will find several apps and ask which one you mean. `--app packages/web`
+  skips the question.
+</Tip>
+
+Prefer to wire it yourself? See [Manual install](/install-manual). It is about ten lines, and worth reading once even if you let the agent do it, because it explains what the agent actually changed.
+
+## Step 2. Check the setup
+
+```bash
+npx @reticlehq/server doctor
+```
+
+`doctor` diagnoses the whole setup in one command: Chromium, the daemon, the port. If something is wrong this is the page you want before you start debugging your app instead.
+
+## Step 3. Start your app and open it
+
+Start your dev server as usual, then:
+
+```bash
+npx @reticlehq/server open
+```
+
+This reuses the tab you already have open, or opens one if you don't. The SDK connects to the local daemon over a WebSocket, and your agent can now see the app.
+
+<Warning>
+  If the browser console says `[Reticle] this page could not open a websocket to …`, your app and
+  the daemon disagree about the port. Set it explicitly:
+  `VITE_RETICLE_WS_URL=ws://localhost:4400/reticle` for Vite, or `reticle.connect({url})`. This is
+  the single most common setup problem, and the console message names the exact address it tried.
+</Warning>
+
+## Step 4. Look at the page
+
+Ask your agent to take a snapshot. This is what came back from a real app:
+
+```json
+{
+  "tree": "- textbox \"Email\" (ref=e3) [value=\"admin@reticle.dev\"]\n- textbox \"Password\" (ref=e4) [value=\"[REDACTED]\"]\n- button \"Sign in\" (ref=e5)",
+  "nodes": 3,
+  "truncated": false,
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 243, "tokens": 61 }
+}
+```
+
+Three things to notice.
+
+The password is already `[REDACTED]`. Reticle redacts credential-shaped values before they leave the page, so your agent's context never holds your test password, let alone your real one.
+
+The whole snapshot cost **61 tokens**. This is `mode: "interactive"`, which returns only the controls. A full accessibility-tree dump of a comparable page runs to thousands. Reticle is built to ask narrow questions, because the answer gets re-sent to the model on every turn.
+
+Each control has a `ref` like `e5`. That's the handle for the next step, and it stays valid until the element leaves the DOM, so you don't re-snapshot between actions.
+
+## Step 5. Act, and prove it
+
+Here is the whole idea of Reticle in one call. Your agent names the expected consequence **before** it acts:
+
+```json
+{
+  "ref": "e5",
+  "action": "click",
+  "until": { "kind": "net", "method": "POST" }
+}
+```
+
+Stating the expectation up front is the difference between a check and a rationalisation. An agent that clicks first and then decides what counts as success will always find something that counts.
+
+The real response, trimmed for length:
+
+```json
+{
+  "verified": "yes",
+  "verifiedReason": "proved",
+  "because": "assertion held at presence grade over a clean capture with no channel disagreeing",
+  "effect": {
+    "ok": true,
+    "testid": "login-submit",
+    "component": "Login",
+    "name": "Sign in",
+    "effect": { "domMutatedWithin": 7, "appeared": "Signing in…" },
+    "source": { "file": "src/components/Login.tsx", "line": 81, "column": 8 }
+  },
+  "verdict": {
+    "pass": true,
+    "evidence": {
+      "method": "POST",
+      "url": "http://localhost:8787/api/login",
+      "status": 200,
+      "durationMs": 67,
+      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}",
+      "responseBody": "{\"token\":\"[REDACTED]\",\"user\":{\"email\":\"admin@reticle.dev\"}}"
+    }
+  },
+  "summary": {
+    "net": { "total": 1, "errors": 0 },
+    "consoleErrors": 0,
+    "stateDiffs": [{ "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}" }],
+    "signals": ["auth:granted"]
+  },
+  "honesty": {
+    "grade": "presence",
+    "coverage": { "pct": 100, "partial": false },
+    "integrity": { "clean": true, "issues": [] }
+  }
+}
+```
+
+![A real act_and_wait verdict, annotated. The verdict, the source pointer, the request evidence, the request count, the state diff, and the app's own signal](/images/verdict-annotated.png)
+
+Read what that actually proves:
+
+| Field | What it tells you |
+| --- | --- |
+| `verified: "yes"` | The named consequence happened. Not "the page looks different", the specific thing. |
+| `source.file` / `line` | The button lives at `src/components/Login.tsx:81`. If this had failed, your agent knows which file to open. |
+| `verdict.evidence` | The exact request: one `POST /api/login`, `200`, 67ms. Not a summary of it. The request. |
+| `stateDiffs` | Application state moved from `null` to a real user. A mock that returns 200 without changing state is caught right here. |
+| `signals` | The app's own `auth:granted` fired. This is the strongest signal available, because the app declared success itself. |
+| `net.total: 1` | Exactly one request. Double-submit bugs show up as `2`. |
+| `integrity.clean` | Nothing interfered with the capture, so the verdict is trustworthy. |
+
+## What "verified" can say
+
+<CardGroup cols={3}>
+  <Card title="yes" icon="circle-check">
+    The consequence you named actually happened, and the evidence is attached.
+  </Card>
+  <Card title="no" icon="circle-xmark">
+    It did not happen. This is a finding, with the source pointer to go fix it.
+  </Card>
+  <Card title="unknown" icon="circle-question">
+    Reticle drove the app and could not tell. **This is not a pass.** Report it as unknown.
+  </Card>
+</CardGroup>
+
+That third state is the one that matters. Most tools have two outcomes and quietly file "I couldn't tell" under "fine". A verification layer that cannot admit uncertainty is just a very confident random number generator.
+
+## Frequently asked questions
+
+<AccordionGroup>
+  <Accordion title="How long does it actually take to install Reticle?">
+    One command and two restarts. `npx @reticlehq/server init` registers the MCP server, installs
+    the SDK, wires your build config and writes the agent rules. Then restart your dev server, so it
+    picks up the new build plugin, and restart your agent, so it re-reads its MCP server list. The
+    MCP registration is global, so every later project starts with the tools already there.
+  </Accordion>
+
+<Accordion title="Do I need to write tests or learn a query syntax?">
+  No. You talk to your agent in plain language and it calls the tools. There is no spec file, no
+  selector language and no test runner involved in the loop on this page. If you later want the same
+  flow to block a bad merge, you can save it and run it in CI, but that is a separate step.
+</Accordion>
+
+<Accordion title="Will any of this end up in my production build?">
+  No. The SDK is dev-only. The Vite plugin declares `apply: 'serve'`, so it is dropped from `vite
+  build` entirely, and `connect()` self-disables when the build reports `NODE_ENV=production`. The
+  recommended wiring also guards the call behind `import.meta.env.DEV`, so there are two independent
+  locks.
+</Accordion>
+
+<Accordion title="Does my code or my app's data leave my machine?">
+  No. The daemon runs on your machine and the SDK runs in your browser. No application code, DOM,
+  network traffic or console output leaves it. Anonymous product analytics are sent unless you opt
+  out with `npx @reticlehq/server telemetry disable`, and they never include your code or your app's
+  data.
+</Accordion>
+
+<Accordion title="What if my framework is not React or Next.js?">
+  The core is framework-neutral, so DOM, network, console, routing and source mapping work anywhere
+  JavaScript runs. What varies is how `connect()` gets into your app and whether you get component
+  identity on top. See [Frameworks](/frameworks) for the exact wiring per stack and an honest table
+  of what is gated in CI versus wired but unverified.
+</Accordion>
+
+  <Accordion title="Nothing connected. What is the first thing to check?">
+    Run `npx @reticlehq/server doctor`. If it shows the daemon running but `sessions` at zero, your
+    app is not reaching the bridge, and the usual cause is a port mismatch. The bridge port is not
+    your dev-server port. See [Troubleshooting](/troubleshooting).
+  </Accordion>
+</AccordionGroup>
+
+## Where to go next
+
+<CardGroup cols={2}>
+  <Card title="Instrument your app" icon="wrench" href="/instrumentation">
+    Emit signals like `auth:granted` so your verdicts get stronger than "the DOM changed".
+  </Card>
+  <Card title="Every tool" icon="list" href="/tools-overview">
+    The 18 tools your agent sees by default, and the 30 more it can reach on demand.
+  </Card>
+  <Card title="Run it in CI" icon="circle-check" href="/testing">
+    Turn this session into a suite that blocks a bad merge.
+  </Card>
+  <Card title="Why Reticle" icon="lightbulb" href="/why-reticle">
+    The false-green problem, and the measured case that this fixes it.
+  </Card>
+</CardGroup>