@reticlehq/server 2.7.0 → 2.8.0

package/docs/desktop-apps.md

@@ -1,6 +1,11 @@
-# Desktop apps: Electron & Tauri
+---
+title: Wiring up Electron and Tauri
+sidebarTitle: Electron and Tauri setup
+description: 'Install and wire Reticle into an Electron or Tauri app, drive the IPC boundary, and read the troubleshooting for each runtime.'
+icon: plug
+---
 
-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.
+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)
@@ -12,13 +17,17 @@ Reticle verifies desktop apps the same way it verifies web apps — from **insid
 
 ## 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:
+The usual question is _"it's a desktop app, so what URL does the agent open?"_ None. The direction is reversed from what browser tooling trains you to expect:
+
+```mermaid
+flowchart LR
+    A["coding agent"]
+    D["reticle daemon<br/>localhost:4400"]
+    W["your Electron / Tauri<br/>window + the SDK"]
 
-```text
-┌──────────────┐   MCP     ┌───────────────────┐   WebSocket    ┌───────────────────────┐
-│ coding agent │◀────────▶│  reticle daemon    │◀──────────────▶│ your Electron/Tauri   │
-│              │  stdio   │  (localhost:4400)  │   the app      │ window + the SDK      │
-└──────────────┘          └───────────────────┘   dials OUT    └───────────────────────┘
+    A <-- "MCP over stdio" --> D
+    W -- "the app dials OUT<br/>over WebSocket" --> D
+    D -- "commands" --> W
 ```
 
 Your app **connects to the daemon**, not the other way round. So the workflow is:
@@ -27,13 +36,13 @@ Your app **connects to the daemon**, not the other way round. So the workflow is
 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.
+`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.
+The rows in **bold** are the ones a committed battery re-proves on every change with `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 |
 | --- | --- | --- | --- |
@@ -42,13 +51,13 @@ The rows in **bold** are the ones a committed battery re-proves on every change
 | 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 |
+| 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 |
+| **screenshot / visual_diff** | ✅ | ✅ | one line in Electron's main process; one Rust command in Tauri (both 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 |
@@ -64,11 +73,11 @@ 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.
+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.
+**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. It is never the wrong window.
 
 **Tauri: one Rust command.**
 
@@ -80,19 +89,19 @@ tauri::Builder::default()
 
 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:
+`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** |
+| 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.
+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.
+**`{ 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, which would be 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.
 
@@ -108,9 +117,9 @@ The lesson generalises past this document: four experiments agreeing does not ma
 
 ### 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.
+**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.**
+**Tauri: yes. Show, load, then hide.**
 
 ```rust
 .on_page_load(reticle_tauri::on_page_load)   // hides the window when RETICLE_HEADLESS=1
@@ -118,7 +127,7 @@ The lesson generalises past this document: four experiments agreeing does not ma
 
 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.
+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.
 
@@ -126,23 +135,23 @@ The ordering is the whole trick. Hiding the window during `setup` hides it befor
 
 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)        |
+| 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 | n/a     | n/a     | 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.
+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:
+**1. The renderer.** One line in `vite.config.ts`, exactly like a web app:
 
 ```ts
 import { reticle } from '@reticlehq/vite-plugin';
@@ -157,7 +166,7 @@ export default defineConfig({
 
 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:
+**2. The preload.** One line, before you expose anything:
 
 ```bash
 npm i -D @reticlehq/electron
@@ -175,7 +184,7 @@ contextBridge.exposeInMainWorld('api', {
 
 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`.
+**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.
 
@@ -192,7 +201,7 @@ 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.
+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`:
 
@@ -206,13 +215,13 @@ The one required step is **CSP**. Tauri ships a restrictive default that blocks
 }
 ```
 
-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.
+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.
+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:
 
@@ -226,7 +235,7 @@ Reticle records each IPC call as an ordinary request, so the tools you already u
 }
 ```
 
-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:
+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 } }
@@ -241,16 +250,16 @@ IPC has no status code; `200`/`500` are synthetic, mapped from whether the call
 }
 ```
 
-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.
+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.
+**`reticle status` shows no session.** Check the app's console (Electron: devtools, or forward `console-message` to your terminal, since 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).
+**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.
+**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/desktop.mdx

@@ -0,0 +1,188 @@
+---
+title: Desktop apps: no browser required
+sidebarTitle: Desktop apps
+description: Reticle verifies Electron and Tauri apps from inside, including the IPC boundary the renderer cannot see. No browser, no screenshot, no URL to open.
+icon: display
+---
+
+Ask most browser tooling to test a desktop app and the first question is "what URL do I open?".
+
+There isn't one. That is the whole problem, and it is why desktop verification is mostly unserved.
+
+Reticle inverts the direction. Your app dials the local daemon, the agent drives it through the same tools it uses for the web, and the verdicts read the same. No Chromium to launch, no screenshot to interpret.
+
+## The thing nobody else does
+
+A desktop app's most interesting failures happen at the **IPC boundary**. The renderer asks the main process for something, and the main process quietly fails.
+
+The renderer cannot see that. A screenshot certainly cannot. Reticle records it as a request:
+
+```json
+{ "method": "ipc", "url": "ipc://todos:archive", "status": 500, "ms": 82 }
+```
+
+Then it contradicts a UI that moved on regardless:
+
+```json
+{
+  "kind": "signal-contradicted",
+  "claim": "the app fired \"todos:loaded\"",
+  "counter": "1 request(s) in the same window failed",
+  "detail": "IPC ipc://todos:archive → 500"
+}
+```
+
+The app said it loaded. One IPC call in the same window returned 500. Reticle puts both in front of the agent instead of believing the happier one.
+
+![Left, an app window showing three synced todo items and nothing wrong. Right, Reticle's view of the same moment: the todos:loaded signal, an ipc://todos:archive call returning 500, and a signal-contradicted finding naming both](/images/desktop-ipc.png)
+
+<Note>
+  The window on the left is an illustration. The JSON on the right is real output from the desktop
+  battery, which starts a real Electron main process and a **packaged** Tauri binary and drives them
+  headless on every change.
+</Note>
+
+## What works, and what is proven
+
+| Capability                                    | Electron | Tauri |
+| --------------------------------------------- | :------: | :---: |
+| sessions, snapshot, query, inspect            |   yes    |  yes  |
+| capabilities, live store state                |   yes    |  yes  |
+| act: click, fill, type, select                |   yes    |  yes  |
+| **act_and_wait, wait_for, assert**            |   yes    |  yes  |
+| console errors                                |   yes    |  yes  |
+| network over HTTP                             |   yes    |  yes  |
+| **network over IPC**                          |   yes    |  yes  |
+| route (use a hash router)                     |   yes    |  yes  |
+| storage, animations, observe, explore         |   yes    |  yes  |
+| baselines, record and replay, crawl           |   yes    |  yes  |
+| **screenshot and visual diff**                |   yes    |  yes  |
+| **drivable while occluded or minimized**      |   yes    |  yes  |
+| **headless**                                  |   yes    |  yes  |
+| **a missing preload is declared, not silent** |   yes    |  n/a  |
+| network mocking, viewport pinning             |    no    |  no   |
+
+Bold rows are re-proven by `pnpm test:e2e:desktop` on every change. The rest were measured by hand.
+
+That distinction is deliberate. This table used to report a hand-run score with nothing in the repo reproducing it, so it could go stale without anything failing.
+
+## Three things that are genuinely different
+
+<CardGroup cols={3}>
+  <Card title="It works occluded" icon="eye-slash">
+    Minimized, app-hidden, behind a fullscreen app on another Space. The agent keeps driving.
+  </Card>
+  <Card title="Screenshots cannot lie" icon="camera">
+    Captured from the window's own backing store, never the screen.
+  </Card>
+  <Card title="Missing wiring is declared" icon="triangle-exclamation">
+    Electron without the preload reports `coverage: partial`, not a clean pass.
+  </Card>
+</CardGroup>
+
+### Why screenshots read the backing store
+
+`webContents.capturePage()` reads the window's own pixels. Capturing a screen _region_ was tried and deliberately rejected.
+
+A region capture photographs whatever is on top. 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.
+
+<Warning>
+  One honest caveat. A fully occluded or minimized window is only partially composited, so parts of
+  a capture may come back blank. Bring the window forward for a complete image. It is never the
+  wrong window.
+</Warning>
+
+### Why a missing preload is not a silent pass
+
+Without `@reticlehq/electron/preload`, every IPC call is invisible to Reticle.
+
+A tool that just reported clean there would be telling you the IPC layer is fine when it never looked. Instead verdicts carry `coverage: partial` and name the missing line.
+
+## Getting started
+
+The workflow has no browser step in it at all.
+
+1. **Start the daemon once.**
+
+   ```bash
+   npx @reticlehq/server serve
+   ```
+
+2. **Start your app exactly as you always do.**
+
+   ```bash
+   npm run dev        # or: electron .   |   cargo tauri dev
+   ```
+
+3. **Confirm it connected.**
+
+   ```bash
+   npx @reticlehq/server status
+   ```
+
+   Your window appears as a session, and the agent can drive it.
+
+### Electron
+
+Screenshots are one line in the main process:
+
+```js
+const { installReticleCapture } = require('@reticlehq/electron/main');
+
+const win = new BrowserWindow({
+  /* … */
+});
+installReticleCapture(win);
+```
+
+No CDP flag, no extra packages, and it works on a packaged `file://` renderer.
+
+### Tauri
+
+The frontend is identical to any web app. The CSP is not optional:
+
+```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"
+    }
+  }
+}
+```
+
+<Warning>
+Tauri's default CSP blocks the bridge WebSocket **before it opens**. Your app runs perfectly and
+simply never connects, with no error to go on.
+
+Keep `ipc: http://ipc.localhost` in `connect-src`, because Tauri v2 needs it for `invoke` itself. Drop the `ws://` entries from your release config.
+
+</Warning>
+
+IPC observation needs nothing on the Rust side. An `invoke('load_todos')` already reaches Reticle as `ipc://load_todos`.
+
+Screenshots and headless mode need the crate, which is versioned independently of the npm packages:
+
+```toml
+[dependencies]
+reticle-tauri = "0.1"
+```
+
+```rust
+tauri::Builder::default()
+    .invoke_handler(tauri::generate_handler![reticle_tauri::reticle_capture])
+    .on_page_load(reticle_tauri::on_page_load)
+```
+
+## Keep reading
+
+<CardGroup cols={2}>
+  <Card title="Full desktop guide" icon="book" href="/desktop-apps">
+    Every capability in detail, what IPC looks like to an agent, and desktop troubleshooting.
+  </Card>
+  <Card title="Manual install" icon="screwdriver-wrench" href="/install-manual">
+    The wiring for both runtimes, step by step.
+  </Card>
+</CardGroup>