@reticlehq/server 2.4.0 → 2.6.0

package/docs/deploy-checks.md

@@ -0,0 +1,69 @@
+# Verification at the deploy choke point (Vercel / Netlify)
+
+The strongest place to enforce verification is the moment code becomes a preview URL. Every deploy already produces one, and both Vercel and Netlify let a third party attach a **check** to it — pass/fail, shown on the PR, with no workflow file to write.
+
+That makes the non-developer story complete: the SDK is auto-injected by the build plugin, flows are minted from toolbar recordings with auto-proposed consequences, and verification runs at publish — **without anyone writing a test.**
+
+> Docs-only in v2.2.0. The pieces below all ship today (`reticle verify` exits 0/1 and persists a run artifact); what is _not_ built is a hosted Reticle app that registers itself as a provider. Wire it with the CI recipe until that exists.
+
+## The shape
+
+```
+git push → preview deploy → Reticle verifies the preview URL → check passes/fails on the PR
+```
+
+`reticle verify <preview-url>` is the whole integration surface:
+
+- exits **0** when every saved flow passes, **1** otherwise — the only contract a check needs,
+- prints a legible ✓/✗ report for the PR log,
+- persists a `ReticleVerificationRun` artifact (`.reticle/runs/<id>.json`) so `reticle gate` and `reticle_run_export` can consume the same verdict.
+
+## Recipe A — CI (works today, any provider)
+
+```yaml
+# .github/workflows/verify.yml
+name: reticle
+on: [deployment_status]
+jobs:
+  verify:
+    if: github.event.deployment_status.state == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - run: pnpm install --frozen-lockfile
+      - run: npx playwright install --with-deps chromium
+      # Reticle drives the preview and owns its own browser + daemon.
+      - run: npx reticle verify "${{ github.event.deployment_status.target_url }}" --timeout 60000
+```
+
+The job's own pass/fail becomes the PR check. Nothing else is required.
+
+**Non-loopback previews need pairing.** For a real preview URL (not `localhost`), Reticle injects `reticle.connect()` with a one-time token and allow-lists the preview origin — so the app does not need to be rebuilt per environment. Confirm the SDK actually runs on the deployed build: a production build that tree-shakes the dev-only SDK will connect to nothing, and `verify` will (correctly) fail with _"no app connected."_
+
+## Recipe B — the Checks API pattern (what a hosted Reticle would do)
+
+Both providers expose the same shape, which is why this is one integration rather than two:
+
+| Provider | Hook | Result surface |
+| --- | --- | --- |
+| Vercel | Deployment webhook → run the check → report back | Checks on the deployment / PR |
+| Netlify | Deploy-succeeded webhook → run the check → report back | Deploy summary / PR |
+
+The flow is: receive the deploy webhook → `reticle verify <target_url>` → post the verdict (and the `repair.failurePackets[]` from the run artifact) back as the check output. The artifact is stable and versioned precisely so a host platform can render it without parsing logs.
+
+## Pair it with the local gate
+
+The deploy check catches what reaches a preview. `reticle gate` catches it earlier — an agent that edits a covered file cannot "finish" without re-verifying:
+
+```bash
+reticle gate --since origin/main    # exit 1 unless passing artifacts cover the affected flows
+```
+
+Use both: `gate` in the agent's Stop hook (see `agent-cheatsheet`), `verify` at the deploy. They read the same run artifacts, so a green gate locally and a green check on the PR mean the same thing.
+
+## Honest limits
+
+- **`verify` needs one connected session.** If several tabs of the app are open against the same daemon it refuses rather than guessing which to drive.
+- **It replays flows sequentially against one tab**, so flows must not depend on each other's leftover state (a flow that logs in contaminates the next one). Author self-contained flows, or use `reticle_flow_verify { parallel }`, which gives each flow an isolated context.
+- **No saved flows means nothing to verify** — `verify` fails rather than reporting a vacuous pass.

package/docs/desktop-apps.md

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

package/docs/enterprise.md

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

package/docs/fixtures-dispatch-receiver.yml

@@ -0,0 +1,76 @@
+# Copy this into `reticle-fixtures` as `.github/workflows/verify-on-dispatch.yml`.
+#
+# It is kept HERE, in the repo that sends the dispatch, on purpose: the two halves have to agree on
+# an event name and a payload shape, and a contract whose two ends live in different repositories
+# drifts the first time somebody edits one of them. This file is the sending end's statement of what
+# the receiving end must look like.
+#
+# It has never run. Nothing in this repository can verify it — the dispatch needs a token that does
+# not exist yet, and the receiver needs to be committed to another repository. Treat every line as
+# unverified until somebody has watched one green run, and do not let its presence here be mistaken
+# for Tier 2 being live.
+name: Verify a Reticle commit against the fixtures
+
+on:
+  repository_dispatch:
+    types: [reticle-commit]
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: Reticle commit to verify
+        required: true
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    # Nine real apps, each installed and booted. This is why Tier 2 cannot block a merge.
+    timeout-minutes: 90
+    steps:
+      - name: Check out the fixtures (the pristine surface)
+        uses: actions/checkout@v4
+        with:
+          # `clean` is the branch that has NEVER been instrumented. 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.
+          ref: clean
+
+      - name: Check out the Reticle commit under test
+        uses: actions/checkout@v4
+        with:
+          repository: reticlehq/reticle
+          ref: ${{ github.event.client_payload.sha || inputs.sha }}
+          path: reticle
+
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Build the release candidate
+        working-directory: reticle
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm build
+
+      - run: npx playwright install --with-deps chromium
+
+      - name: Materialise the fixture apps
+        run: node scripts/materialise.mjs
+
+      - name: Install into every fixture and open each one in a browser
+        # `--local` is the whole point: without it the gate can only confirm what already shipped,
+        # which is the wrong half of the question before a release.
+        run: node scripts/verify.mjs --local ./reticle
+        env:
+          # The fixtures gate's own idle shutdown once fired mid-install and scored three fixtures as
+          # install failures. A gate owns its daemon for the whole run — see the reticle repo's
+          # apps/e2e/harness-rules.md, rule 2.
+          RETICLE_IDLE_SHUTDOWN_MS: '0'
+
+      - name: Upload the run
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fixtures-run
+          path: runs/
+          if-no-files-found: ignore

package/docs/fixtures.md

@@ -0,0 +1,45 @@
+# Fixture apps
+
+The apps in `apps/` are ours. We chose their defects, so passing against them says less than it looks like — and they are all wired to Reticle already, which makes them useless for the one question that matters before a release: **does the install still work on an app that has never seen Reticle?**
+
+That question is answered in a separate repo: **[`reticle-fixtures`](https://github.com/reticlehq/reticle-fixtures)**.
+
+## Why it is a separate repo
+
+Three reasons, each of which bit us before the split:
+
+- **They are somebody else's package managers.** `react-admin` is a yarn monorepo. Putting it under `apps/*` makes it a member of this pnpm workspace and breaks `pnpm install` for everyone.
+- **They need a branch model this repo cannot give them.** A fresh install is only meaningful on a surface that has never been instrumented. Re-running `init` over an already-wired app reports `·` (already wired) for every step and proves nothing — which is exactly how an install regression ships unnoticed. `reticle-fixtures` keeps a pristine `clean` branch for that, plus `main` at the latest version and `reticle/<version>` per release.
+- **They are large.** The upstream checkouts were eight gigabytes of somebody else's git history sitting gitignored inside this repo.
+
+## What runs there
+
+```bash
+node scripts/materialise.mjs   # build apps/ from fixtures.json at pinned refs
+node scripts/verify.mjs        # install into every clean app, boot it, assert a session connects
+```
+
+The last step is the one that earns its keep. Every install bug found so far has been silent: the app boots, the `init` report reads clean, and nothing connects. Next.js shipped in that state through a whole release — three independent defects, none visible to any check short of opening a browser and looking at `reticle status`.
+
+## What stays here
+
+`apps/` — bench-app, next-smoke, the Remix and Astro examples, the Electron and Tauri smoke apps, atlas, and the API. These are the CI gates (`pnpm test:e2e`, `pnpm test:e2e:desktop`), and `integration-coverage.test.ts` fails if one of them goes missing while `SKILL.md` still offers its framework.
+
+The split is: **`apps/` proves the tools work. `reticle-fixtures` proves the install works.**
+
+## 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).
+
+**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.
+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.
+
+**Nothing here has ever run.** Treat every line as unverified until somebody has watched one green run. Tier 2 being present in the plan is not Tier 2 being live.
+
+### Why Tier 2 exists when Tier 1 already passes
+
+`pnpm gate:install` (Tier 1) scaffolds pristine apps and catches install **regressions**. It cannot catch install **complexity**: `rowy` is 70 dependencies of somebody else's product, `phanpy` has a 130-line vite config holding ten plugins inside a `defineConfig` callback. That is where install bugs actually hide, and a scaffold deliberately has none of it. The two tiers answer different questions and neither substitutes for the other.