@reticlehq/server 3.5.0 → 3.7.0

package/docs/packages/tauri.mdx

@@ -6,25 +6,20 @@ icon: rust
 
 `reticle-tauri` is a Rust crate on crates.io, not an npm package. You need it only if your Tauri app should answer `reticle_screenshot`, or run headless in CI. Everything else about a Tauri app, including IPC observation, works without it.
 
-It is versioned **independently** of the ten npm packages. **MIT licensed, unlike the Apache 2.0 npm packages. Edition 2021.**
+It is versioned in **lockstep** with the `@reticlehq/*` npm packages, so `3.7` here and there is the same release. **MIT licensed, unlike the npm packages. Edition 2021.**
 
 ## Why it exists, and why it is small
 
 Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')` already reaches Reticle as `ipc://load_todos` through the SDK in the webview. You only need this crate for two things: screenshots, and headless mode.
 
-<Warning>
-  Do not expect this to match the npm version. Doing so would imply a release cadence the crate does
-  not have, and it would make every npm release a crates.io release for no reason.
-</Warning>
-
 ## Install
 
 ```toml
 [dependencies]
-reticle-tauri = "3.5"
+reticle-tauri = "3.7"
 ```
 
-Its own dependencies are `tauri = "2"` plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.
+Its own dependencies are `tauri = "2.12"` (the Windows backend must use the same `webview2-com` and `windows` versions Tauri does, so it follows Tauri's minor version) plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.
 
 ## Wiring
 
@@ -34,6 +29,8 @@ tauri::Builder::default()
     .on_page_load(reticle_tauri::on_page_load)
 ```
 
+**Dev builds only.** In a release build the crate is inert: `reticle_capture` refuses and `on_page_load` does nothing, so the binary you sign and ship carries no Reticle capability. A release build you test with Reticle (a CI fixture) turns it on with `reticle-tauri = { version = "3.7", features = ["in-release"] }`.
+
 Nothing is needed on the JavaScript side. Tauri has no preload stage, so the SDK reaches `reticle_capture` through Tauri's own internals.
 
 ## The public API
@@ -43,6 +40,9 @@ Nothing is needed on the JavaScript side. Tauri has no preload stage, so the SDK
 | `reticle_capture` | `#[tauri::command] pub async fn reticle_capture(window: tauri::WebviewWindow, full_page: Option<bool>) -> Result<String, String>` |
 | `on_page_load` | `pub fn on_page_load<R: Runtime>(webview: &Webview<R>, payload: &tauri::webview::PageLoadPayload<'_>)` |
 | `FULL_PAGE_UNSUPPORTED` | `pub const FULL_PAGE_UNSUPPORTED: &str = "full-page-unsupported"` |
+| `ACTIVE` | `pub const ACTIVE: bool`: true in a debug build, or a release build with `in-release` |
+| `INERT_IN_RELEASE` | `pub const INERT_IN_RELEASE: &str`: what `reticle_capture` answers when the crate is inert |
+| `inert_refusal` | `pub fn inert_refusal() -> Option<&'static str>` |
 
 There are no public traits and no macros.
 
@@ -52,7 +52,7 @@ Runs on a blocking thread, writes a PNG into a per-process `0700` directory unde
 
 ### `on_page_load`
 
-Hides the window on `PageLoadEvent::Finished` when the environment variable `RETICLE_HEADLESS=1` is set. That ordering matters: the window exists and renders, then it is hidden, so the capture path still works.
+Hides the window on `PageLoadEvent::Finished` when the environment variable `RETICLE_HEADLESS=1` is set. That ordering matters: the window exists and renders, then it is hidden, so the capture path still works. On macOS it also keeps every window's webview scheduling while it is behind other windows (macOS 14 and later); on older macOS, headless moves the window offscreen instead of hiding it.
 
 ## The silent failure to know about
 

package/docs/packages/test.mdx

@@ -6,7 +6,7 @@ icon: vial
 
 `@reticlehq/test` is Reticle's spec runner for CI. It turns an interactive session into a suite that runs on every pull request, without an agent and without paying model tokens to re-derive the same checks. Install it when you want unattended verification; skip it if you only ever drive Reticle interactively through MCP.
 
-**Licensed under `SEE LICENSE IN LICENSE`. Depends on `@reticlehq/core` and `@reticlehq/server`. Optional peer dependency: `vitest ^3.2.6`.**
+**Licensed under `FSL-1.1-ALv2`. Depends on `@reticlehq/core` and `@reticlehq/server`. Optional peer dependency: `vitest ^3.2.6 || ^4.0.0`.**
 
 ```bash
 npm i -D @reticlehq/test
@@ -47,10 +47,9 @@ await run.close();
 ## Writing specs
 
 ```ts
-import { reticleTest, type TestContext } from '@reticlehq/test';
+import { reticleTest } from '@reticlehq/test';
 
-reticleTest('login grants a session', async (spec) => {
-  const t = spec as TestContext;
+reticleTest('login grants a session', async (t) => {
   await t.fill('email', 'user@example.com');
   await t.fill('password', 'hunter2');
   await t.actAndWait('login-submit', 'click', { kind: 'signal', name: 'auth:granted' });
@@ -61,12 +60,7 @@ reticleTest('login grants a session', async (spec) => {
 
 `reticleTest(name: string, fn: SpecFn): void` registers into a module-level registry. `register`, `getRegistered` and `clearRegistry` are exported for anyone driving it themselves.
 
-<Note>
-  `SpecFn` types its argument as `SpecContext`, which declares only `invoke`. The runner actually
-  hands the spec whatever `buildContext` returned, which is a `TestContext`. In plain JavaScript
-  this is invisible; in TypeScript you get `Property 'fill' does not exist on type 'SpecContext'`
-  unless you narrow it as above.
-</Note>
+`SpecFn` types its argument as `SpecContext`, which is `TestContext`, so the methods below are typed without a cast.
 
 ## The test context
 

package/docs/packages/vite-plugin.mdx

@@ -35,7 +35,7 @@ Set `RETICLE_PORT` in the dev server or desktop build environment to use the sam
 
 ## Why it exists
 
-`apply: 'serve'` means it never reaches a production build. That is the guarantee that lets you leave it in the config permanently: there is no way to ship Reticle to your users by forgetting to remove a line.
+In a production `vite build` the plugin injects nothing and swaps the browser SDK for an inert stub, so the bundle carries no Reticle runtime code. That is the guarantee that lets you leave it in the config permanently: there is no way to ship Reticle to your users by forgetting to remove a line.
 
 ## What it injects
 
@@ -45,8 +45,11 @@ A virtual module at `/@reticle-connect`, added to the HTML, whose contents are:
 import { reticle, install } from '@reticlehq/react';
 install();
 reticle.connect({/* resolved args */});
+if (import.meta.hot) reticle.observeHotUpdates(import.meta.hot);
 ```
 
+An app with `@reticlehq/browser` and no `@reticlehq/react` (Vue, Svelte, plain TypeScript) gets the same module importing `reticle` from `@reticlehq/browser`, without `install()`.
+
 Plus a dynamic import of your dev module if one exists. It looks for `src/reticle-dev.ts`, `.js`, `.tsx` or `.jsx`, in that order, and leaves the file alone if you have one: that file is yours to edit.
 
 ## Options
@@ -55,31 +58,56 @@ Plus a dynamic import of your dev module if one exists. It looks for `src/reticl
 
 | Option | Type | Default |
 | --- | --- | --- |
-| `port` | `number` | Discovered from the daemon registry for this project, falling back to `4400` |
+| `port` | `number` | Used only when the daemon registry and `.reticle.json` name no port; otherwise `4400`. `RETICLE_PORT` overrides all of them |
 | `root` | `string` | Vite's `root`, else `process.cwd()` |
 | `sdkVersion` | `string` | Read from the installed `@reticlehq/react` |
 | `session` | `string` | Omitted, so the SDK generates one |
 | `projectId` | `string` | Derived from the package name plus the root path |
 | `token` | `string` | `readPairingToken()`, from `~/.reticle/pairing-token` |
+| `present` | `boolean` | `true`. Set `false` to hide Reticle's presenter while keeping the agent connection active |
 | `sourceMapping` | `boolean` | `true`. Set `false` to skip the Babel pass |
 | `inject` | `boolean` | `true`. Set `false` to call `connect()` yourself |
 | `desktop` | `boolean` | `false`. When `true` the connect passes `allowInProduction: true`, which an Electron or Tauri renderer needs, and a `vite build` in a non-production mode (`--mode development`) is instrumented too. A production-mode build is stubbed like a web build |
 | `captureNetworkBodies` | `boolean` | `false`. Also enabled by `VITE_RETICLE_CAPTURE_BODIES=1` |
+| `networkBodyMaxChars` | `number` | `8192`, clamped to 256 to 262144. Also `VITE_RETICLE_BODY_MAX_CHARS` |
+| `captureErrorBodies` | `boolean` | `true`: a failed response keeps its body. `VITE_RETICLE_NO_ERROR_BODIES=1` turns it off |
+| `testIdAttribute` | `string` | `.reticle.json`'s `testIdAttribute`, else `data-testid` |
+| `allowNonLocalhost` | `boolean` | `false`. Lets Reticle run off localhost; a pairing token is still required. Also `VITE_RETICLE_ALLOW_NON_LOCALHOST=1` |
+| `exposePresenter` | `boolean` | `false`. Contributors only: makes Reticle's own presenter visible to its tools |
 | `onWarn` | `(message: string) => void` | `console.warn` |
 
+`reticle({ present: false })` still lets the plugin create and configure the connection; it only hides Reticle's visible presenter. `reticle({ inject: false })` disables that generated connection, so your application must call `connect()` itself. In that manual call, pass the pairing token explicitly:
+
+```ts
+reticle.connect({
+  token: __RETICLE_TOKEN__,
+  root: __RETICLE_ROOT__,
+  sdkVersion: __RETICLE_SDK_VERSION__,
+});
+```
+
+Add ambient declarations for these identifiers to `src/vite-env.d.ts` (or another included `.d.ts`) in a TypeScript app:
+
+```ts
+declare const __RETICLE_TOKEN__: string;
+declare const __RETICLE_ROOT__: string;
+declare const __RETICLE_SDK_VERSION__: string;
+```
+
+Vite replaces these `define` identifiers in application source at build time; the declarations let TypeScript typecheck them and do not create runtime globals. The SDK does not discover the pairing token, so pass it explicitly in a hand-written connection.
+
 ## Other exports
 
 | Export | Type | What it is |
 | --- | --- | --- |
 | `RETICLE_VITE_PLUGIN_NAME` | `'reticle'` | The plugin name |
-| `RETICLE_TOKEN_GLOBAL` | `'__RETICLE_TOKEN__'` | The global the token is stamped onto |
+| `RETICLE_TOKEN_GLOBAL` | `'__RETICLE_TOKEN__'` | The Vite `define` identifier replaced with the pairing token |
 | `RETICLE_CONNECT_MODULE` | `'/@reticle-connect'` | The virtual module id |
 | `RENDER_PREHOOK_SOURCE` | `string` | The inline render prehook snippet |
 | `RETICLE_DEV_MODULE_CANDIDATES` | readonly tuple | The four dev-module paths it looks for |
 | `readPairingToken` | `() => string \| undefined` | Read the pairing token from disk |
 | `findDevModule` | `(root: string, exists: (p: string) => boolean) => string \| null` | Locate the dev module |
 | `connectModuleSource` | `(options: ReticleVitePluginOptions, devModule?: string \| null) => string` | Build the injected module source |
-| `cjsDepIncludes` | `(appRoot: string, canResolve?: (dep: string) => boolean) => string[]` | CommonJS deps to add to `optimizeDeps` |
 
 Types: `ReticleVitePluginOptions`, `ReticleVitePlugin`, `ViteDevServerLike`.
 

package/docs/packages.mdx

@@ -5,11 +5,12 @@ description: Every Reticle package. What it does, why it exists, when you actual
 icon: cubes
 ---
 
-Reticle is twelve packages, and most people install two. This page exists so you can tell which two, and so that the ones you skip stop looking mysterious.
+Reticle is fourteen packages (thirteen on npm, one Rust crate), and most people install two. This page exists so you can tell which two, and so that the ones you skip stop looking mysterious.
 
 <Note>
   Everything ships together at one version: whatever `npm view @reticlehq/core version` says, every
-  other `@reticlehq/*` package says too, and so does the `reticle-tauri` crate on crates.io.
+  other `@reticlehq/*` package says too, and so does the `reticle-tauri` crate on crates.io. The
+  one exception is `open-verification`, the specification, which carries its own version.
 
 It was versioned independently until 2.12.0, and that turned out to mean _stuck_: the crate sat at `0.1.0` from the day it was written, the publish job skipped it every release because that version already existed, and no Rust-side fix reached anybody. Lockstep costs one line in the bump script and cannot fail that way.
 
@@ -55,7 +56,7 @@ Those rules are why the browser SDK cannot accidentally pull in a filesystem cal
 
 **Why it exists:** without one shared definition, the browser and the server drift. One renames a field, the other keeps reading the old one, and the failure is silent. A verdict that quietly stops carrying evidence. Core makes that a type error instead.
 
-**Depends on:** `zod`, and nothing else. That is the whole point; it sits at the bottom of the graph so everything can depend on it without cycles.
+**Depends on:** `zod` and `open-verification`, which itself depends only on `zod`. That is the whole point; it sits at the bottom of the graph so everything can depend on it without cycles.
 
 **Do you install it?** No. It arrives as a dependency of whatever you did install.
 
@@ -89,7 +90,7 @@ if (import.meta.env.DEV) reticle.connect();
 
 **Why it exists:** agents speak MCP; browsers speak WebSocket; somebody has to be fluent in both and own the `.reticle/` directory where flows, baselines and runs are stored.
 
-**Depends on:** `@modelcontextprotocol/sdk`, `@reticlehq/core`, `@reticlehq/init`, `ws`, `zod`.
+**Depends on:** `@modelcontextprotocol/sdk`, `@reticlehq/browser`, `@reticlehq/core`, `@reticlehq/engine`, `@reticlehq/init`, `open-verification`, `ws`, `zod`, `zod-to-json-schema`. **Peer:** `playwright`.
 
 **Do you install it?** Not into your project. Your agent launches it:
 
@@ -129,7 +130,7 @@ npm i -D @reticlehq/react
 
 **One line in `vite.config.ts`, two jobs.** It stamps source locations onto your JSX and injects `connect()` so you cannot forget to.
 
-**Why it exists:** the two things everyone forgets are wiring the SDK and enabling source mapping. This does both, and `apply: 'serve'` guarantees it never reaches a production build.
+**Why it exists:** the two things everyone forgets are wiring the SDK and enabling source mapping. This does both, and in a production `vite build` it swaps the SDK for an inert stub, so it never reaches a production bundle.
 
 **Depends on:** `@babel/core`, `@reticlehq/babel-plugin`, `@reticlehq/core`. **Peer:** `vite`.
 
@@ -149,7 +150,7 @@ export default defineConfig({ plugins: [reticle(), react()] });
 
 **Why it exists:** React 19 dropped `_debugSource`, which is what source mapping used to rely on. This plugin puts the information back, at build time, in dev only. Without it, `reticle_look { action: "element" }` can still tell you the component name but not the file.
 
-**Depends on:** nothing. **Peer:** `@babel/core`.
+**Depends on:** `@reticlehq/core`. **Peer:** `@babel/core`.
 
 **Do you install it?** Only directly if you are wiring Babel yourself. The Vite and Next packages both pull it in.
 
@@ -191,7 +192,7 @@ module.exports = withReticle({/* your config */});
 
 **Why it exists:** the decision and the machinery that feeds it are different jobs with different reasons to change. Carved out of `@reticlehq/server` so the part that judges can be read, tested and reused without starting anything.
 
-**Depends on:** `@reticlehq/core`, `zod`.
+**Depends on:** `@reticlehq/core`, `open-verification`, `zod`.
 
 ---
 
@@ -211,7 +212,7 @@ module.exports = withReticle({/* your config */});
 
 ## @reticlehq/eslint-plugin
 
-**Two rules, the main one being: state changed, so a signal must fire.**
+**Three rules, the main one being: state changed, so a signal must fire.**
 
 **Why it exists:** signals are the strongest evidence Reticle can use, and they rot the way all conventions rot. Someone adds a mutation, forgets the signal, and every verdict for that flow quietly drops a grade. Nothing breaks. The tests still pass. The evidence just gets weaker.
 
@@ -233,20 +234,15 @@ A lint rule makes the signal layer self-enforcing, which is the only way a conve
 
 ## reticle-tauri
 
-**The Rust crate**, on crates.io. Versioned in lockstep with the npm packages, so `2.11` here and `2.11` there mean the same release.
+**The Rust crate**, on crates.io. Versioned in lockstep with the npm packages, so `3.7` here and `3.7` there mean the same release.
 
 **Why it exists:** Tauri IPC observation needs nothing on the Rust side; an `invoke('load_todos')` already reaches Reticle as `ipc://load_todos`. You only need this crate for screenshots and headless mode.
 
 ```toml
 [dependencies]
-reticle-tauri = "3.5"
+reticle-tauri = "3.7"
 ```
 
-<Warning>
-  Do not expect this to match the npm version. Doing so would imply a release cadence the crate does
-  not have, and it would make every npm release a crates.io release for no reason.
-</Warning>
-
 <Card title="Desktop setup in full" icon="display" href="/desktop">
   Electron and Tauri wiring, including the Tauri CSP whose failure is silent.
 </Card>

package/docs/platform-integration.md

@@ -4,7 +4,7 @@ description: 'Adopt Reticle on your own codebase, or embed it inside an AI app-b
 icon: plug
 ---
 
-Two ways in. **A team** runs `npx @reticlehq/server init` once and points its coding agent at the MCP server. **A platform** adds the dev-only SDK to its generated-app template, runs `npx @reticlehq/server serve --http --drive <preview-url>` beside each preview, and `POST`s to `/verify` after every generate or edit, gating the ship on `run.verdict.status === 'pass'` and feeding `run.repair.failurePackets[]` back to a fixer agent.
+Two ways in. **A team** runs the install script once, which registers the MCP server with its coding agents, and follows the next steps it prints. **A platform** adds the dev-only SDK to its generated-app template, runs `npx @reticlehq/server serve --http --drive <preview-url>` beside each preview, and `POST`s to `/verify` after every generate or edit, gating the ship on `run.verdict.status === 'pass'` and feeding `run.repair.failurePackets[]` back to a fixer agent.
 
 > The one guide for adopting Reticle, both for a team using a coding agent on its own app and for an AI app-builder platform (Lovable / Emergent / Bolt) embedding Reticle in its generation pipeline. Reticle reads the program from _inside_ a running app and returns a **verdict with evidence** ("did it actually work?"), not a screenshot. Enterprise/premium access lives in [`enterprise.md`](./enterprise.md).
 
@@ -29,10 +29,11 @@ One call replays the app's key journeys and asserts **program truth** (network c
 ### A. A team, agent on your own app (~10 min)
 
 ```bash
-npx @reticlehq/server init   # auto-detects your framework, installs the kit + build plugin
+curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
+irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex   # Windows
 ```
 
-Paste to your agent (Claude Code / Cursor / any MCP agent): `Follow https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md` It runs the wizard once (Vite/Next plugin + SDK init + MCP config), then verifies on every change. Run your dev server, then ask the agent to _"verify it with Reticle."_
+It puts the CLI on the machine and registers the MCP server with the coding agents it finds. Then do what it prints: restart your coding agent so it loads Reticle's tools, and paste the prompt the script prints into it. The agent runs `reticle init` in your app (build plugin, SDK connect file, agent rules), then proves one flow. No agent? Run `reticle init` in the app yourself.
 
 ### B. A platform / CI, driven from your pipeline (no MCP, no human)
 
@@ -87,7 +88,7 @@ Copyable patterns: `apps/bench-app/src/reticle-dev.ts`, `apps/next-smoke/app/ret
 | Missing validation (`"abc"` becomes data) | flow oracle (error shown AND nothing created) |
 | Silent console error (logged, UI still renders) | `console { absent: true }` |
 | UI-vs-store desync (the total lies) | reads the store, contradicts the display |
-| Blast-radius (an action corrupts unrelated state) | `state { hold:true }` invariant |
+| Blast-radius (an action corrupts unrelated state) | a `state { path, equals }` invariant on the unrelated value |
 
 Live, clickable demo of each: `apps/vibe-builder-demo/` (set `BUG_MODE=…`). Proven in CI: `server/src/judgement/runs/generated-app-bugs.test.ts`.
 
@@ -133,7 +134,7 @@ The shape is identical (in-app SDK in the template → verify in the sandbox →
 2. Since the runtime is in-browser, drive via the connected session (the SDK dials the bridge) rather than `--drive`; call verify from the Bolt agent after a build.
 3. Same act-on-verdict: gate + self-heal with the repair packets. (Bolt already detects terminal/compile errors; Reticle adds the _runtime program-truth_ layer it's blind to.)
 
-> Honest note: a platform can build a verification step itself. Reticle's case is the depth (program-state and source mapping), the determinism (0% flake, no LLM in the loop), the un-hallucinatable verdict, and a stable drop-in artifact. The reproducible benchmark in [`bench/`](https://github.com/reticlehq/reticle/blob/main/bench/README.md) measures the observation-cost and detection differences against other browser-automation MCPs.
+> Honest note: a platform can build a verification step itself. Reticle's case is the depth (program-state and source mapping), the determinism (no LLM in the loop), the un-hallucinatable verdict, and a stable drop-in artifact. The reproducible benchmark in [`bench/`](https://github.com/reticlehq/reticle/blob/main/bench/README.md) measures the observation-cost and detection differences against other browser-automation MCPs.
 
 ---
 

package/docs/predicates.mdx

@@ -5,7 +5,7 @@ description: The grammar for declaring what should be true. Every kind, every fi
 icon: filter
 ---
 
-A predicate declares what should be true, as `{ kind, ...fields }`. Reticle has twelve kinds: `signal`, `state`, `net`, `route`, `element`, `text`, `console`, `animation`, `settled`, and the combinators `allOf`, `anyOf` and `not`. Which one you pick decides whether a green means anything.
+A predicate declares what should be true, as `{ kind, ...fields }`. Reticle has thirteen kinds: `signal`, `state`, `net`, `route`, `element`, `text`, `console`, `animation`, `settled`, `compare`, and the combinators `allOf`, `anyOf` and `not`. Which one you pick decides whether a green means anything.
 
 It is the argument to `until` on [`reticle_act_and_wait`](/tools/act-and-wait), and to `predicate` on [`reticle_assert`](/tools/assert) and [`reticle_assert { action: "wait" }`](/tools/wait-for).
 
@@ -25,17 +25,19 @@ Reticle grades them, and it will tell you when you have chosen a weak one. This
 
 Take the advice. `element` and `text` are convenient and weak; `signal`, `state` and `net` are what make a green trustworthy.
 
-| Kind               | Grade     | Proves                                                 |
-| ------------------ | --------- | ------------------------------------------------------ |
-| `signal`           | strongest | The app declared success in its own words              |
-| `state`            | strong    | A registered store actually changed                    |
-| `net`              | strong    | A specific request fired, with a countable cardinality |
-| `route`            | medium    | Navigation happened                                    |
-| `console`          | medium    | Something logged, or nothing did                       |
-| `element` / `text` | weak      | Something rendered. A mock renders too                 |
-| `animation`        | weak      | An animation ran or finished                           |
-| `settled`          | timing    | The page went quiet. A precondition, not a proof       |
-| `compare`          | its sides | Two readings agree: the stronger side's grade          |
+The verdict reports the grade it proved, strongest first: `signal`, `net`, `state`, then `presence`.
+
+| Kind               | Grade      | Proves                                                 |
+| ------------------ | ---------- | ------------------------------------------------------ |
+| `signal`           | `signal`   | The app declared success in its own words              |
+| `net`              | `net`      | A specific request fired, with a countable cardinality |
+| `state`            | `state`    | A registered store actually changed                    |
+| `route`            | `presence` | Navigation happened                                    |
+| `console`          | `presence` | Something logged, or nothing did                       |
+| `element` / `text` | `presence` | Something rendered. A mock renders too                 |
+| `animation`        | `presence` | An animation ran or finished                           |
+| `settled`          | `presence` | The page went quiet. A precondition, not a proof       |
+| `compare`          | its sides  | Two readings agree: the stronger side's grade          |
 
 ## The leaves
 
@@ -49,7 +51,7 @@ Take the advice. `element` and `text` are convenient and weak; `signal`, `state`
 }
 ```
 
-`query` accepts `role`, `name`, `text`, `label`, `placeholder`, `testid`, `alt`, `value`, `by`, `component`, `source`, `scope`, `self`, `attrs`. `state` is one of `visible`, `hidden`, `enabled`, `disabled`, `checked`, `expanded`, `pressed`, `focused`, `inViewport`, `present`.
+`query` accepts `role`, `name`, `text`, `label`, `placeholder`, `testid`, `alt`, `value`, `by`, `component`, `source`, `scope`, `self`, `attrs`, `matchCase`. Written flat on the predicate instead of under `query`, these fields are moved into `query` for you. `state` is one of `visible`, `hidden`, `enabled`, `disabled`, `checked`, `expanded`, `pressed`, `focused`, `inViewport`, `present`.
 
 `value` is the one worth knowing about. `{ "role": "textbox", "name": "Amount" }` collapses to "a textbox called Amount exists", which passes against an empty field; adding `value` is what makes it an assertion about what the user will actually send. `by` selects the locator strategy explicitly, `component` and `source` match React component identity and source location, and `self` restricts a scoped match to the scope element itself rather than its descendants.
 
@@ -69,7 +71,7 @@ Add `"absent": true` to assert something is **gone**. The predicate for a remova
 { "kind": "text", "contains": "Saved successfully", "visible": true }
 ```
 
-`contains` is the field the published schema declares. `value` and `text` are accepted as aliases and rewritten to it. `absent: true` asserts the text is not present, and `visible: true` requires it to be on screen rather than merely in the DOM.
+`contains` is the field the published schema declares. `value`, `text` and `query` are accepted as aliases and rewritten to it. The match is case-sensitive; `ignoreCase: true` relaxes that. `absent: true` asserts the text is not present, and `visible: true` requires it to be on screen rather than merely in the DOM.
 
 Use `scope` to restrict the search to a CSS selector or element ref. If Reticle reports that the text is split across the scope's children, retry its generated predicate with `"self": true`; that checks the scope root's combined subtree text while still enforcing `contains`.
 
@@ -121,7 +123,17 @@ Two fields read the RESPONSE BODY, so a request that succeeded with the wrong nu
 
 `bodyMatches` is a field match, keyed like `signal.dataMatches` and taking the same operators (`*`, `$gte`, `$contains`). A key can be a dotted path into a wrapped answer: `{ "data.status": "completed" }`, `{ "items.0.id": "a1" }`, `{ "items.length": 3 }`. A nested object written out as a value is compared whole, so use the path to match one field inside it. Reach for it whenever the value is an enum, because that is the case a substring cannot decide: `bodyContains: "completed"` passes on a body carrying `"completedAt": null`, where the needle matched the KEY and the job was still queued. `completed`/`completedAt`, `success`/`successRate`, `sent`/`unsent` all have that shape.
 
-Both require body capture, `reticle({ captureNetworkBodies: true })`, and say so when the body was never recorded rather than reporting an ordinary mismatch.
+Two more read the REQUEST body, what the UI sent: `requestBodyContains` (a substring) and `requestBodyMatches` (a field match, same operators). They are separate fields so neither can be satisfied by the wrong half of the exchange.
+
+All four require body capture, `reticle.connect({ captureNetworkBodies: true })`, and say so when the body was never recorded rather than reporting an ordinary mismatch.
+
+Some endpoints read over POST: a GraphQL query, a tRPC batch, a query bus, a Server Action that loads a list. When one runs twice in an action window, which React StrictMode does in development, the second call looks like a double submit and the verdict comes back `unknown` with `duplicate-request`. Declare the endpoint a read on its clause:
+
+```json
+{ "kind": "net", "method": "POST", "urlContains": "/graphql", "repeatable": true }
+```
+
+`repeatable: true` keeps that endpoint out of `duplicate-request` for this verdict only. The request is still waited for and still counted, so `count` keeps its meaning. It needs a non-empty `urlContains`, and a clause without one is refused, because it would excuse every request in the window. When the clause names a `method`, only calls with that method are excused: a repeatable `GET` never excuses a `POST` to the same URL. Leave it off for an endpoint that writes: there, the second call is the bug.
 
 ### route
 
@@ -129,7 +141,7 @@ Both require body capture, `reticle({ captureNetworkBodies: true })`, and say so
 { "kind": "route", "pathname": "/success" }
 ```
 
-`pathname` matches the path exactly. `contains` matches anywhere in the whole route, path, query and fragment together. `path` is accepted as an alias for `pathname`, and `url` and `urlContains` as aliases for `contains`, but the canonical spellings are the ones above.
+`pathname` matches the path exactly. `contains` matches anywhere in the whole route, path, query and fragment together. `path` is accepted as an alias for `pathname`, and `url`, `urlContains` and `pathContains` as aliases for `contains`, but the canonical spellings are the ones above.
 
 A passing route verdict quotes the transition itself:
 
@@ -143,10 +155,12 @@ A passing route verdict quotes the transition itself:
 }
 ```
 
-<Warning>
-  `route` asserts the route **changed**. Asserting the route you are already on always fails, and
-  the response says so: `expected: "a route change to /"`, `assertion: "route.changed"`.
-</Warning>
+<Note>
+  `route` reads the last route change in the window. When there was none, it reads the session's
+  current URL instead, and the evidence says `decidedBy: "current-route"`. Only when neither exists
+  does it fail, and the response says so: `expected: "a route change to /"`, `assertion:
+  "route.changed"`.
+</Note>
 
 ### console
 
@@ -156,6 +170,8 @@ A passing route verdict quotes the transition itself:
 
 "The flow completed and logged nothing." Worth attaching to most actions. Plenty of features work while quietly throwing.
 
+`contains` narrows it to one message: with `absent: true` it asserts THIS message did not appear, rather than that nothing was logged at all. `textContains` is accepted as an alias.
+
 ### signal
 
 ```json
@@ -269,7 +285,7 @@ A number is read out of displayed text, so `"$1,234.50"` compares as `1234.5`. A
 
 These only work where a before-reading was taken, which today is `reticle_act_and_wait`. Asked anywhere else they report `unknown` with "no before-reading was taken", never a failure, because nothing was compared and a `false` would blame the app for a reading nobody took. For the same reason a relative property is never `already_true`: `unchanged` is trivially true against a baseline taken a microsecond earlier, so the pre-action check skips it and lets the action decide.
 
-A saved flow cannot keep one yet: `FlowExpect` has no slot for `satisfies`, and rather than record a weaker assertion than the one you made, the converter records none.
+A saved flow keeps it: a step's `expect` is a full predicate, `satisfies` included.
 
 A miss quotes the real value back at you:
 
@@ -398,7 +414,7 @@ A combinator needs its own `kind`, and the children go in `predicates`, or in `o
 accepted as an alias for it. `not` takes a single child in `predicate`, or in `of`. A bare
 `{ "allOf": [ … ] }` does not parse, and neither does `{ "kind": "allOf", "allOf": [ … ] }`.
 
-Reticle refuses the call rather than running half of it. The real refusal names the field, the fix and the consequence: _"predicates: Required; unknown field allOf. Nothing ran, the predicate was not evaluated, so no verdict was produced. allOf accepts: predicates."_ Better to be told than to get a green from an assertion that never executed.
+Reticle refuses the call rather than running half of it. The refusal names the field, says that nothing ran and no verdict was produced, lists the fields `allOf` accepts, and shows a valid example. Better to be told than to get a green from an assertion that never executed.
 
 </Warning>
 
@@ -433,10 +449,10 @@ On a failure each child reports separately too, so you can see which one broke:
 
 | Field | Where | What it does |
 | --- | --- | --- |
-| `timeout_ms` | `assert`, `wait_for`, `act_and_wait` | Wait up to N ms for it to become true |
+| `timeout_ms` | `reticle_assert` (both actions), `reticle_act_and_wait` | Wait up to N ms for it to become true |
 | `since` | `net`, `route`, `console`, `animation` and `signal` leaves, and the call itself | Only consider events after this cursor |
 
-The `since` cursor comes from a prior `reticle_act` response. Use it whenever you are asserting something an action was supposed to cause. Without it, an assertion can pass on an event from two clicks ago. That applies to every one of the five kinds above, not only to network calls: an unscoped `signal` matches a fire from an earlier action just as readily.
+The `since` cursor comes from a prior `reticle_act` or `reticle_observe` response. Use it whenever you are asserting something an action was supposed to cause. Without it, an assertion can pass on an event from two clicks ago. That applies to every one of the five kinds above, not only to network calls: an unscoped `signal` matches a fire from an earlier action just as readily.
 
 <Card title="Where predicates get used" icon="circle-check" href="/tools/act-and-wait">
   Naming the consequence before the action is the whole point.