@reticlehq/server 2.7.0 → 2.9.0

package/docs/docs.json

@@ -0,0 +1,364 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Reticle",
+  "description": "Reticle is the proof layer for AI agents: it verifies a running web app from the inside, without screenshots, and returns a verdict with evidence.",
+  "colors": {
+    "primary": "#ff9d86",
+    "light": "#ffbcac",
+    "dark": "#d04425"
+  },
+  "logo": {
+    "light": "/logo/wordmark-black.svg",
+    "dark": "/logo/wordmark-white.svg"
+  },
+  "favicon": {
+    "light": "/favicon/mark-black.svg",
+    "dark": "/favicon/mark-white.svg"
+  },
+  "appearance": {
+    "default": "system"
+  },
+  "styling": {
+    "eyebrows": "breadcrumbs",
+    "codeblocks": "dark"
+  },
+  "search": {
+    "prompt": "Search the Reticle docs"
+  },
+  "metadata": {
+    "timestamp": true
+  },
+  "navigation": {
+    "versions": [
+      {
+        "version": "2.9.0",
+        "default": true,
+        "tabs": [
+          {
+            "tab": "Guides",
+            "groups": [
+              {
+                "group": "Get started",
+                "pages": [
+                  "quickstart",
+                  "what-is-reticle",
+                  "why-reticle",
+                  "getting-started",
+                  "for-agents"
+                ]
+              },
+              {
+                "group": "Install",
+                "pages": ["install-agentic", "install-manual", "frameworks"]
+              },
+              {
+                "group": "Instrument",
+                "pages": ["instrumentation", "state-management"]
+              },
+              {
+                "group": "Verify and ship",
+                "pages": ["flows", "testing", "deploy-checks", "integration-patterns"]
+              },
+              {
+                "group": "Working with agents",
+                "pages": ["multi-agent-testing", "human-control", "platform-integration"]
+              },
+              {
+                "group": "When it goes wrong",
+                "pages": ["troubleshooting", "debugging"]
+              }
+            ]
+          },
+          {
+            "tab": "Reference",
+            "groups": [
+              {
+                "group": "Tools",
+                "pages": [
+                  "tools-overview",
+                  "tools-snapshot",
+                  "tools-query",
+                  "tools-inspect",
+                  "tools-navigate",
+                  "tools-act",
+                  "tools-act-and-wait",
+                  "tools-act-sequence",
+                  "tools-observe",
+                  "tools-network",
+                  "tools-console",
+                  "tools-state",
+                  "tools-wait-for",
+                  "tools-assert",
+                  "tools-sessions",
+                  "tools-tools-and-run",
+                  "tools-session-and-feedback"
+                ]
+              },
+              {
+                "group": "Beyond the loop",
+                "pages": ["capabilities"]
+              },
+              {
+                "group": "CLI commands",
+                "pages": [
+                  "cli",
+                  "cli/init",
+                  "cli/doctor",
+                  "cli/status",
+                  "cli/serve",
+                  "cli/stop",
+                  "cli/kill",
+                  "cli/restart",
+                  "cli/mcp",
+                  "cli/open",
+                  "cli/drive",
+                  "cli/verify",
+                  "cli/affected",
+                  "cli/gate",
+                  "cli/watch",
+                  "cli/capsules",
+                  "cli/hunt",
+                  "cli/update",
+                  "cli/rollback",
+                  "cli/license",
+                  "cli/version",
+                  "cli/telemetry",
+                  "cli/feedback",
+                  "cli/identify",
+                  "cli/help",
+                  "cli/cloud"
+                ]
+              },
+              {
+                "group": "Packages",
+                "pages": [
+                  "packages",
+                  "packages/core",
+                  "packages/browser",
+                  "packages/server",
+                  "packages/react",
+                  "packages/vite-plugin",
+                  "packages/babel-plugin",
+                  "packages/next",
+                  "packages/test",
+                  "packages/eslint-plugin",
+                  "packages/electron",
+                  "packages/tauri"
+                ]
+              },
+              {
+                "group": "Grammar",
+                "pages": ["predicates", "actions", "recipes"]
+              },
+              {
+                "group": "Long form",
+                "pages": ["agent-cheatsheet", "usage", "faq"]
+              }
+            ]
+          },
+          {
+            "tab": "Desktop",
+            "groups": [
+              {
+                "group": "Electron and Tauri",
+                "pages": ["desktop"]
+              }
+            ]
+          },
+          {
+            "tab": "Resources",
+            "groups": [
+              {
+                "group": "How it works",
+                "pages": ["architecture", "benchmarks", "token-efficiency"]
+              },
+              {
+                "group": "Compare",
+                "pages": ["vs-playwright-mcp", "vs-chrome-devtools-mcp", "vs-screenshots"]
+              },
+              {
+                "group": "Practice",
+                "pages": ["best-practices", "skill-file"]
+              },
+              {
+                "group": "Trust & licensing",
+                "pages": ["telemetry", "enterprise"]
+              }
+            ]
+          },
+          {
+            "tab": "Contributing",
+            "groups": [
+              {
+                "group": "Working on Reticle",
+                "pages": ["gates", "gate-plan", "fixtures", "local-registry"]
+              },
+              {
+                "group": "Internals",
+                "pages": ["system-map", "telemetry-contract", "telemetry-events"]
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    "global": {
+      "anchors": [
+        {
+          "anchor": "GitHub",
+          "href": "https://github.com/reticlehq/reticle",
+          "icon": "github"
+        },
+        {
+          "anchor": "Discord",
+          "href": "https://discord.gg/BwAbzv9ZRz",
+          "icon": "discord"
+        },
+        {
+          "anchor": "npm",
+          "href": "https://www.npmjs.com/org/reticlehq",
+          "icon": "npm"
+        },
+        {
+          "anchor": "Changelog",
+          "href": "https://github.com/reticlehq/reticle/blob/main/CHANGELOG.md",
+          "icon": "clock-rotate-left"
+        }
+      ]
+    }
+  },
+  "navbar": {
+    "links": [
+      {
+        "type": "github",
+        "href": "https://github.com/reticlehq/reticle"
+      }
+    ],
+    "primary": {
+      "type": "button",
+      "label": "Get started",
+      "href": "/quickstart"
+    }
+  },
+  "footer": {
+    "socials": {
+      "x": "https://x.com/reticle_hq",
+      "github": "https://github.com/reticlehq/reticle",
+      "linkedin": "https://www.linkedin.com/company/reticlehq",
+      "discord": "https://discord.gg/BwAbzv9ZRz"
+    },
+    "links": [
+      {
+        "header": "Docs",
+        "items": [
+          {
+            "label": "Quickstart",
+            "href": "/quickstart"
+          },
+          {
+            "label": "Usage guide",
+            "href": "/usage"
+          },
+          {
+            "label": "Agent cheat sheet",
+            "href": "/agent-cheatsheet"
+          },
+          {
+            "label": "For agents",
+            "href": "/for-agents"
+          }
+        ]
+      },
+      {
+        "header": "Project",
+        "items": [
+          {
+            "label": "Contributing",
+            "href": "https://github.com/reticlehq/reticle/blob/main/CONTRIBUTING.md"
+          },
+          {
+            "label": "Security",
+            "href": "https://github.com/reticlehq/reticle/blob/main/SECURITY.md"
+          },
+          {
+            "label": "License",
+            "href": "https://github.com/reticlehq/reticle/blob/main/LICENSE"
+          }
+        ]
+      },
+      {
+        "header": "Community",
+        "items": [
+          {
+            "label": "Discord",
+            "href": "https://discord.gg/BwAbzv9ZRz"
+          },
+          {
+            "label": "Star on GitHub",
+            "href": "https://github.com/reticlehq/reticle"
+          },
+          {
+            "label": "X",
+            "href": "https://x.com/reticle_hq"
+          },
+          {
+            "label": "LinkedIn",
+            "href": "https://www.linkedin.com/company/reticlehq"
+          }
+        ]
+      }
+    ]
+  },
+  "redirects": [
+    {
+      "source": "/README",
+      "destination": "/getting-started",
+      "permanent": true
+    },
+    {
+      "source": "/desktop-apps",
+      "destination": "/desktop",
+      "permanent": true
+    }
+  ],
+  "contextual": {
+    "options": ["copy", "view", "claude", "chatgpt", "cursor", "vscode", "mcp", "add-mcp"]
+  },
+  "markdown": {
+    "instructions": [
+      "Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library.",
+      "Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.",
+      "A verdict of `verified: \"unknown\"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass.",
+      "Package names are scoped `@reticlehq/*`. Run every CLI command as `npx @reticlehq/server <command>`, for example `npx @reticlehq/server init`. `reticle` is a bin name that `@reticlehq/server` installs once it is on your PATH, NOT a package on npm: `npx reticle` fetches an unrelated package published by somebody else, so never run that. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version."
+    ]
+  },
+  "seo": {
+    "metatags": {
+      "og:site_name": "Reticle Docs",
+      "og:type": "website",
+      "og:title": "Reticle Docs: verification for AI coding agents",
+      "og:description": "Reticle verifies a running web app from the inside and returns a verdict with evidence, not a screenshot. Install it, instrument it, and read the full tool reference.",
+      "og:url": "https://docs.reticle.sh",
+      "og:image": "https://docs.reticle.sh/images/og.png",
+      "og:image:alt": "Reticle: your agent says it works. Reticle checks.",
+      "twitter:card": "summary_large_image",
+      "twitter:site": "@reticle_hq",
+      "twitter:creator": "@reticle_hq",
+      "twitter:image": "https://docs.reticle.sh/images/og.png"
+    },
+    "organization": {
+      "name": "Reticle",
+      "url": "https://docs.reticle.sh",
+      "logo": "https://docs.reticle.sh/images/og.png",
+      "sameAs": ["https://github.com/reticlehq/reticle", "https://www.npmjs.com/org/reticlehq"]
+    }
+  },
+  "errors": {
+    "404": {
+      "redirect": false,
+      "title": "No such page",
+      "description": "That page moved or never existed. Start at [Getting started](/getting-started), or search above."
+    }
+  }
+}

package/docs/enterprise.md

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

package/docs/faq.mdx

@@ -0,0 +1,102 @@
+---
+title: 'FAQ: frequently asserted questions'
+sidebarTitle: FAQ
+description: Does it run in production, does it need React, does it replace Playwright, and the other questions people actually ask.
+icon: circle-question
+---
+
+Reticle is a dev-only, localhost-only verification layer an AI coding agent uses to prove a change actually worked in your running app. It does not run in production, it does not need React, and it does not replace Playwright. The rest of the questions people actually ask are below.
+
+<AccordionGroup>
+
+<Accordion title="Does this run in production?">
+  No, and it is built so that it cannot easily be made to. Keep `reticle.connect()` behind a dev
+  guard; the SDK is side-effect-free and tree-shakes out of production builds. The Vite plugin uses
+  `apply: 'serve'`, which means it is not part of a production build at all.
+</Accordion>
+
+<Accordion title="Do I have to change my components?">
+  No, for look, act and observe. You get DOM, network, console and routing with zero changes.
+
+You get considerably better results by adding `data-testid` attributes and by [emitting signals](/instrumentation). That is the difference between a verdict that says "something appeared" and one that says "the app declared success".
+
+</Accordion>
+
+<Accordion title="Does it work without React?">
+  The core is framework-agnostic: DOM, network, routing, console, animations, snapshots and actions are gated against a vanilla TypeScript app.
+
+Support beyond that is uneven, and we would rather say so than let you find out:
+
+| Framework | Status |
+| --- | --- |
+| React, Next.js, Remix, Astro | Supported, each with an app and a CI gate |
+| SvelteKit | Wired end to end. `init` writes the client hook, the plugin stamps `.svelte` source. But **no CI gate**, so unverified rather than supported |
+| Vue | A Pinia store adapter and nothing else. No detection, no `.vue` stamping, no gate |
+
+</Accordion>
+
+<Accordion title="Can it tell me whether my UI looks good?">
+  No. Reticle verifies behaviour, not aesthetics. Visual correctness and "does this feel right" remain a human job, or a visual-diff tool's.
+
+It does read design tokens. [`reticle_inspect`](/tools-inspect) reports whether a colour came from your theme or from someone's clipboard. But that is a consistency check, not taste.
+
+</Accordion>
+
+<Accordion title="Does it replace Playwright or Cypress?">
+  No. Those are your scripted CI suite. Reticle is for in-loop verification while an agent is coding, and for the flows you never got round to automating. They compose.
+
+  <Card title="The full comparison" icon="masks-theater" href="/vs-playwright-mcp">
+    Where Playwright is the right choice, stated plainly.
+  </Card>
+</Accordion>
+
+<Accordion title="How does it compare to Playwright MCP or Chrome DevTools MCP?">
+  Those drive a **separate** browser from the outside. Reticle verifies your **own running app** from the inside, with your real session and auth, and with assertions and regression as first-class.
+
+Measured on the same app: Reticle caught 10 of 10 injected bugs, Playwright MCP 9, Chrome DevTools MCP 8. DevTools MCP is about 7% cheaper per look on a simple page, and more expensive on a real one.
+
+</Accordion>
+
+<Accordion title="Can I run several apps or tabs at once?">
+  Yes. Each is a session. Pass `sessionId` to any tool when more than one is connected, and [`reticle_sessions`](/tools-sessions) lists them.
+
+Reticle scopes to your project and prefers the active tab, and it **refuses rather than guesses** when the choice is ambiguous. A refusal you can act on beats a silent pick of the wrong tab.
+
+</Accordion>
+
+<Accordion title="Why did I get `verified: \"unknown\"` on something that clearly worked?">
+  Because Reticle could not confirm it saw the whole story, and it will not call that a pass.
+
+The most common cause is a **throttled tab**: a backgrounded browser tab has its timers suppressed, which suppresses the quiescence detection used to decide the page has settled. Focus the tab, or drive a dedicated context.
+
+If you believe an `unknown` is wrong, report it. Reticle's own response says as much: "an unknown verdict is our defect, not yours".
+
+</Accordion>
+
+<Accordion title="Does my data leave the machine?">
+  Your app's data, no. Reticle is dev-only, localhost-only and offline. Credential-shaped values are redacted before they leave the page. You will see `[REDACTED]` in request bodies without configuring anything.
+
+Anonymous usage telemetry is sent separately and can be turned off with `reticle telemetry disable`.
+
+  <Card title="Exactly what is collected" icon="chart-line" href="/telemetry">
+    The complete list. If it is not on that page, it is not sent.
+  </Card>
+</Accordion>
+
+<Accordion title="Is Reticle proven to make agents fix more bugs?">
+  No, and we are not going to claim it. A controlled test of fix-rate did **not** show an improvement. The benchmark was confounded in ways we can point at, and we consider the question open.
+
+What is measured is detection: 10 of 10 injected regressions caught, with zero false alarms on a known-good control, against 9 and 8 for the alternatives.
+
+</Accordion>
+
+<Accordion title="Why does my agent only see some of Reticle's tools?">
+  Because MCP re-sends every advertised tool definition on **every turn**, so the tool list is rent, not a one-time cost. Reticle advertises the verify loop directly and keeps the cold tail one call away.
+
+Nothing is unreachable. `reticle_tools` lists every tool (pass `names: [...]` for full parameters) and `reticle_run({ tool, args })` invokes any of them by name. If you want the whole surface advertised directly, set `RETICLE_ADVERTISE_ALL_TOOLS=1` in the **daemon's** environment and restart it, which costs roughly seven times the per-turn schema tax and is meant for suites that call by name rather than for running agents.
+
+  <Card title="The surface, explained" icon="wrench" href="/tools-overview">
+    Which tools are advertised directly, and why each earned its slot.
+  </Card>
+</Accordion>
+</AccordionGroup>

package/docs/fixtures.md

@@ -1,6 +1,12 @@
-# Fixture apps
+---
+title: Fixture apps
+description: 'Why the apps in apps/ cannot answer the one question that matters before a release, and what does.'
+icon: cubes
+---
 
-The apps in `apps/` are ours. We chose their defects, so passing against them says less than it looks like — and they are all wired to Reticle already, which makes them useless for the one question that matters before a release: **does the install still work on an app that has never seen Reticle?**
+The apps in `apps/` cannot tell you whether the install still works, because every one of them is already wired to Reticle. That question is answered in a separate repo, **[`reticle-fixtures`](https://github.com/reticlehq/reticle-fixtures)**, which keeps a pristine `clean` branch of real third-party apps and runs `node scripts/verify.mjs` to install into each one and assert a session actually connects.
+
+The apps in `apps/` are ours. We chose their defects, so passing against them says less than it looks like, and they are all wired to Reticle already, which makes them useless for the one question that matters before a release: **does the install still work on an app that has never seen Reticle?**
 
 That question is answered in a separate repo: **[`reticle-fixtures`](https://github.com/reticlehq/reticle-fixtures)**.
 
@@ -9,7 +15,7 @@ That question is answered in a separate repo: **[`reticle-fixtures`](https://git
 Three reasons, each of which bit us before the split:
 
 - **They are somebody else's package managers.** `react-admin` is a yarn monorepo. Putting it under `apps/*` makes it a member of this pnpm workspace and breaks `pnpm install` for everyone.
-- **They need a branch model this repo cannot give them.** A fresh install is only meaningful on a surface that has never been instrumented. Re-running `init` over an already-wired app reports `·` (already wired) for every step and proves nothing — which is exactly how an install regression ships unnoticed. `reticle-fixtures` keeps a pristine `clean` branch for that, plus `main` at the latest version and `reticle/<version>` per release.
+- **They need a branch model this repo cannot give them.** A fresh install is only meaningful on a surface that has never been instrumented. Re-running `init` over an already-wired app reports `·` (already wired) for every step and proves nothing, which is exactly how an install regression ships unnoticed. `reticle-fixtures` keeps a pristine `clean` branch for that, plus `main` at the latest version and `reticle/<version>` per release.
 - **They are large.** The upstream checkouts were eight gigabytes of somebody else's git history sitting gitignored inside this repo.
 
 ## What runs there
@@ -19,21 +25,21 @@ node scripts/materialise.mjs   # build apps/ from fixtures.json at pinned refs
 node scripts/verify.mjs        # install into every clean app, boot it, assert a session connects
 ```
 
-The last step is the one that earns its keep. Every install bug found so far has been silent: the app boots, the `init` report reads clean, and nothing connects. Next.js shipped in that state through a whole release — three independent defects, none visible to any check short of opening a browser and looking at `reticle status`.
+The last step is the one that earns its keep. Every install bug found so far has been silent: the app boots, the `init` report reads clean, and nothing connects. Next.js shipped in that state through a whole release: three independent defects, none visible to any check short of opening a browser and looking at `reticle status`.
 
 ## What stays here
 
-`apps/` — bench-app, next-smoke, the Remix and Astro examples, the Electron and Tauri smoke apps, atlas, and the API. These are the CI gates (`pnpm test:e2e`, `pnpm test:e2e:desktop`), and `integration-coverage.test.ts` fails if one of them goes missing while `SKILL.md` still offers its framework.
+`apps/` holds bench-app, next-smoke, the Remix and Astro examples, the Electron and Tauri smoke apps, atlas, and the API. These are the CI gates (`pnpm test:e2e`, `pnpm test:e2e:desktop`), and `integration-coverage.test.ts` fails if one of them goes missing while `SKILL.md` still offers its framework.
 
 The split is: **`apps/` proves the tools work. `reticle-fixtures` proves the install works.**
 
 ## Wiring Tier 2 (not yet live)
 
-CI can ask this repo to verify a Reticle commit automatically — the [`vite-ecosystem-ci`](https://github.com/vitejs/vite-ecosystem-ci) shape, where a separate repo holds the downstream apps and the main repo asks it to run. The sending half is built (`fixtures-dispatch` in `.github/workflows/ci.yml`); the receiving half is a template at [`docs/fixtures-dispatch-receiver.yml`](./fixtures-dispatch-receiver.yml).
+CI can ask this repo to verify a Reticle commit automatically, in the [`vite-ecosystem-ci`](https://github.com/vitejs/vite-ecosystem-ci) shape, where a separate repo holds the downstream apps and the main repo asks it to run. The sending half is built (`fixtures-dispatch` in `.github/workflows/ci.yml`); the receiving half is a template at [`docs/fixtures-dispatch-receiver.yml`](./fixtures-dispatch-receiver.yml).
 
 **It is inert until two things happen, and neither can be done from inside this repository:**
 
-1. A fine-grained PAT with **Actions: write** on `reticlehq/reticle-fixtures`, added to `reticlehq/reticle` as the secret `FIXTURES_DISPATCH_TOKEN`. Until it exists the job logs that Tier 2 is unwired and exits 0 — it never reddens CI, because a dispatch failure has nothing to do with the change being pushed.
+1. A fine-grained PAT with **Actions: write** on `reticlehq/reticle-fixtures`, added to `reticlehq/reticle` as the secret `FIXTURES_DISPATCH_TOKEN`. Until it exists the job logs that Tier 2 is unwired and exits 0. It never reddens CI, because a dispatch failure has nothing to do with the change being pushed.
 2. The template copied into `reticle-fixtures` as `.github/workflows/verify-on-dispatch.yml`.
 
 The template lives in the _sending_ repo deliberately: the two halves must agree on an event name and payload shape, and a contract whose ends live in different repositories drifts the first time somebody edits one of them.