@reticlehq/server 3.1.0 → 3.3.0

package/docs/cli.mdx

@@ -71,26 +71,16 @@ Exits `0`. That parenthetical about the bridge port is doing a lot of work. Mixi
 
 Whether the daemon is up and which apps have connected.
 
-```json
-{
-  "t": "2026-08-15T18:45:58.190Z",
-  "event": "reticle_status",
-  "port": 4400,
-  "running": true,
-  "pid": 72698,
-  "sessionCount": 1,
-  "sessions": [
-    {
-      "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
-      "url": "http://localhost:4310/",
-      "throttled": false,
-      "stale": false,
-      "pendingMarks": 0
-    }
-  ]
-}
+```text
+reticle status
+  daemon       ✓ running on :4400 (pid 90790)
+  sessions     ✓ 1 page connected
+               http://localhost:4310/
+  agent link   enumerated
 ```
 
+Add `--json` for the same facts as one machine-readable event line. See [`reticle status`](/cli/status) for the fields.
+
 Exits `0`. A session in the list is the install genuinely finished. Not a tick in a checklist, a connected app.
 
 ### `reticle telemetry [status|enable|disable]`

package/docs/desktop.mdx

@@ -214,7 +214,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "3.1"
+reticle-tauri = "3.3"
 ```
 
 ```rust

package/docs/faq.mdx

@@ -102,7 +102,7 @@ What is measured is detection: 10 of 10 injected regressions caught, with zero f
 <Accordion title="Why does my agent only see some of Reticle's tools?">
   Because MCP re-sends every advertised tool definition on **every turn**, so the tool list is rent, not a one-time cost. Reticle advertises the verify loop directly and keeps the cold tail one call away.
 
-`reticle_tools` lists every tool (pass `names: [...]` for full parameters), but on the default surface listing is all it does: that surface is closed and ships no `reticle_run`, so a name outside the nine cannot be called until the daemon advertises it. If you want the whole surface advertised directly, set `RETICLE_ADVERTISE_ALL_TOOLS=1` in the **daemon's** environment and restart it, which costs roughly seven times the per-turn schema tax and is meant for suites that call by name rather than for running agents.
+`reticle_tools` lists every registered tool (pass `names: [...]` for full parameters), and `reticle_run { tool, args }` calls any of them by name, whether or not it is advertised. That hatch is what makes a trimmed surface honest: a tool it does not show is one hop away rather than out of reach. If you want the whole surface advertised directly, set `RETICLE_ADVERTISE_ALL_TOOLS=1` in the **daemon's** environment and restart it, which costs roughly seven times the per-turn schema tax and is meant for suites that call by name rather than for running agents.
 
   <Card title="The surface, explained" icon="wrench" href="/tools/overview">
     Which tools are advertised directly, and why each earned its slot.

package/docs/flows.md

@@ -87,6 +87,16 @@ reticle_flow {action:"load"}({ flowName: "create-task" })   // → the flow JSON
 reticle_flow_replay({ flowName: "create-task" }) // re-resolve each anchor against the LIVE DOM, run it
 ```
 
+## Delete a flow
+
+```jsonc
+reticle_flow {action:"delete"}({ flowName: "create-task" })  // → { deleted: true }
+```
+
+A renamed or obsolete flow otherwise lingers in `reticle_flow {action:"list"}` and in every `reticle_verify {action:"flows"}` suite run, where it fails forever against a screen nobody intends to keep.
+
+**Deleting a flow that is not there is an error, not a no-op.** It answers `{ error, code: "not_found" }` rather than `{ deleted: true }`, so a mistyped name cannot read as a completed cleanup while the real flow stays in the suite. Check the spelling against `reticle_flow {action:"list"}` and try again.
+
 **Watch it replay on the page.** When the presenter is on (`present: true`), a replay isn't silent. Each step drives the real page, so the synthetic cursor flies to the element, the focus ring lands, and the activity log streams the journey live. You (or a teammate) literally watch the saved journey re-walk itself on your app, then see the verdict land. It's the fastest way to _see_ that a flow still works, not just read a green checkmark.
 
 `reticle_flow_replay` returns a status:
@@ -164,6 +174,7 @@ With `apply: false` the flow file is **never modified**; you get the proposed di
 | `reticle_flow_save_recorded` | `{ flowName? }` | persist a human-recorded (toolbar) flow |
 | `reticle_flow {action:"list"}` | `{}` | flows on disk |
 | `reticle_flow {action:"load"}` | `{ flowName }` | the flow JSON |
+| `reticle_flow {action:"delete"}` | `{ flowName }` | `{ deleted: true }`, or `{ error, code }` (`not_found` when no such flow) |
 | `reticle_flow_replay` | `{ flowName }` | `{ status, steps, decision? }` (decision on drift/fail) |
 | `reticle_verify {action:"flows"}` | `{ names?, sessionId? }` | suite verdict `{ status, passed, failed, failures[] }` |
 | `reticle_verify { action: "heal" }` | `{ flowName, apply? }` | propose / apply nearest-match rebind |

package/docs/frameworks.mdx

@@ -35,6 +35,7 @@ Two columns say different things and it is worth keeping them apart. **CI gate**
 | **Plain HTML** | yes | no | no | no | Wired, unverified |
 | **Vue (non-Nuxt)** | as Vite | no | install only | no | Install gated, drive unverified |
 | **Preact** | as Vite | no | no | unproven | Sensor, React adapter via `preact/compat` |
+| **Server-rendered (Django, Flask, FastAPI, Streamlit, Rails)** | yes | no | no | no | Wired, unverified |
 
 <Warning>
   "Wired, unverified" means exactly that. The recipe exists and was written from a real integration,
@@ -85,7 +86,41 @@ module.exports = withReticle({/* your config */});
 
 ## Remix and Astro
 
-Both run on Vite, so both use the Vite plugin exactly as React does. Astro needs the React integration if you want component identity in `.jsx` islands. Static `.astro` markup gets DOM, network and routing without it.
+Remix uses the Vite plugin with `inject: false`: Remix SSRs its own HTML, so the plugin's connect-injection does not fire, but the stamping half still puts `file:line` on a verdict.
+
+Astro is the same on the plugin (wire it with `inject: false` if you want source pointers on JSX islands) and uses a different channel for the pairing token. `vite.define` does not reach Astro's client pipeline on 7.2+, so the identifier stays literal and the bridge refuses the dial. `init` reads the token in frontmatter and puts it on a `<meta name="reticle-pairing-token">`. Reading it per request also means a token written after the dev server started is picked up on the next load, with no restart.
+
+Use a processed page `<script>` with a static SDK import. Vite owns that module graph from the first transform:
+
+```astro
+---
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const pairingToken = (() => {
+  if (!import.meta.env.DEV) return '';
+  const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+  try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
+})();
+const pairingRoot = import.meta.env.DEV ? process.cwd() : '';
+---
+<meta name="reticle-pairing-token" content={pairingToken} />
+<meta name="reticle-pairing-root" content={pairingRoot} />
+<script>
+  import { reticle, install } from '@reticlehq/react';
+  if (import.meta.env.DEV) {
+    const token = document.querySelector('meta[name="reticle-pairing-token"]')?.getAttribute('content') ?? '';
+    const root = document.querySelector('meta[name="reticle-pairing-root"]')?.getAttribute('content') ?? '';
+    install();
+    reticle.connect({
+      ...(0 < token.length ? { token } : {}),
+      ...(0 < root.length ? { root } : {}),
+    });
+  }
+</script>
+```
+
+The `<script>` tag must not sit inside a conditional. Astro hoists them statically, so `{isDev && (<script />)}` is never hoisted. `init` writes the same `<meta>` tags and a local `src/components/ReticleDev.ts` that the script statically imports. It also raises `vite.build.target` to `es2022` (Astro's default down-levels the SDK), declares the SDK in `optimizeDeps.include`, and keeps `.reticle/` out of the watcher. Static `.astro` markup still gets DOM, network and routing without the React integration.
 
 ## SvelteKit
 
@@ -205,6 +240,83 @@ The same shape works for webpack, Parcel, and the Vue and Svelte CLIs.
 
 Keep it out of your production template. Reticle self-disables when the build reports `NODE_ENV=production`, but a second lock on a door leading to your users is a reasonable number.
 
+## Server-rendered apps (Django, Flask, FastAPI, Rails)
+
+There is no JS build to import the SDK from, and no single template to paste a script tag into: an app has many templates and may not have a base one. The SDK loads from a URL instead, so a page with no build step is not a blocker.
+
+`reticle init` detects these and prints the right thing for the stack it found, writing `.reticle.json` as it goes. What follows is the same wiring, written down so you can read it before running anything, or wire it by hand.
+
+### Django
+
+Middleware is the Django-shaped answer: one place, runs for every page, no template to find.
+
+```python
+# reticle_dev.py: add to MIDDLEWARE while DEBUG is on:
+#   MIDDLEWARE = [..., "reticle_dev.ReticleDevMiddleware"]
+from django.conf import settings
+
+_SNIPPET = """<script type="module">
+  import { reticle } from 'https://cdn.jsdelivr.net/npm/@reticlehq/browser@<version>/+esm';
+  reticle.connect({ projectId: '<your-project-id>', token: '<pairing token>' });
+</script>"""
+
+
+class ReticleDevMiddleware:
+    """Inject the Reticle SDK into HTML responses during development only."""
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+        if not settings.DEBUG:
+            return response
+        if "text/html" not in response.get("Content-Type", ""):
+            return response
+        # Streaming responses have no .content to rewrite; leave them alone.
+        if getattr(response, "streaming", False):
+            return response
+        body = response.content.decode(response.charset)
+        if "</body>" not in body:
+            return response
+        response.content = body.replace("</body>", _SNIPPET + "</body>", 1).encode(
+            response.charset
+        )
+        if response.has_header("Content-Length"):
+            response["Content-Length"] = str(len(response.content))
+        return response
+```
+
+`reticle init` emits this with your real version, project id and pairing token filled in. Copy it from there rather than from this page: the placeholders above are the three things that have to be right.
+
+Four details in that middleware are load-bearing, and each is there because the obvious version is wrong:
+
+- **`settings.DEBUG`** is the guard. Reticle is dev-only, and this is the lock that cannot be forgotten at deploy time.
+- **the `text/html` check** keeps it from corrupting a JSON API response or a file download.
+- **the `streaming` check** exists because a `StreamingHttpResponse` has no `.content` to rewrite, and touching it raises.
+- **`</body>`, not `<head>`** so the SDK sees a parsed document.
+
+Re-setting `Content-Length` matters for the same reason: the body grew, and a stale length truncates the page in the browser rather than failing loudly.
+
+### Flask and FastAPI with Jinja
+
+Same shape, one hook instead of a middleware class: an `@app.after_request` in Flask, or a middleware in FastAPI, with the same four guards: a debug flag, `text/html` only, not streaming, and injected before `</body>`.
+
+### Streamlit
+
+Different again: Streamlit owns the top-level document, so there is no served template, and scripts passed to `st.markdown` do not run. Use `st.html` on Streamlit 1.63 or newer. `reticle init` prints the helper, which also guards against connecting twice across reruns.
+
+### What you get, and what you do not
+
+Everything that comes from reading the live page works: queries, snapshots, actions, network and console channels, verdicts.
+
+What is missing is the **source pointer**. `file:line` on a verdict comes from the build plugin stamping `data-reticle-source`, and there is no build step here to stamp it. You get every other signal and no `source` field, the same way a Vue single-file component does.
+
+<Warning>
+  Wired, unverified. No app in CI drives one of these to a verdict, so nothing will tell us if it
+  breaks. If a page does not register a session, that is worth reporting.
+</Warning>
+
 ## Desktop is a different shape
 
 Electron and Tauri invert the direction: your app dials the daemon, and there is no URL for an agent to open. Reticle also reaches the main-process and Rust IPC boundary, which the renderer cannot see.

package/docs/install-agentic.mdx

@@ -150,6 +150,42 @@ Four files in your project, none of them mysterious.
     ```
     The `projectId` is how Reticle scopes sessions to this project, so two apps running at once
     don't get confused for each other.
+
+    **Keeping `.reticle/` small.** Reticle bounds the directory for you, by count and by total size.
+    Add a `retain` block to change what it keeps:
+
+    ```json
+    {
+      "retain": { "sessions": 20, "visual": 10, "feedback": 20, "budgetMb": 512 }
+    }
+    ```
+
+    Those are the defaults, and every field is optional. `sessions` is how many session journals
+    survive, `visual` how many overlay diffs (pixel baselines are never deleted, because the next
+    comparison needs them), `feedback` how many local copies of reports already sent, and `budgetMb`
+    the total the whole evidence tier may occupy. `0` means keep none, and `"sessions": 0` also stops
+    journals being written in the first place.
+
+    Saved flows, capsules, baselines, the contract and the intent ledger are not touched by any of
+    this. They are the part meant to be committed, and a bound that deleted them would be deleting
+    the regression checks your team shares.
+
+    **Your app's own background calls.** An analytics or heartbeat endpoint on your app's own host
+    looks exactly like the app's work, so Reticle never guesses. If one of them keeps a verdict
+    waiting, or fails and gets blamed on an unrelated action, name it:
+
+    ```json
+    {
+      "background": ["/api/analytics/events", "/api/heartbeat"]
+    }
+    ```
+
+    Each entry is matched the way `urlContains` is. A listed request stops holding the wait open and
+    stops contradicting a claim; when a contradiction is still reported, it lists what was set aside.
+    It is never hidden from an assertion that names it: `net { urlContains: "/api/heartbeat" }` still
+    sees it. Keep entries specific: `/api` would set aside your whole backend.
+    Third-party calls (another site's beacon or SDK) need no entry; they are already set aside.
+
   </Accordion>
 
   <Accordion title="vite.config.ts (the plugin)">

package/docs/install-manual.mdx

@@ -175,7 +175,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "3.1"
+reticle-tauri = "3.3"
 ```
 
 ```rust

package/docs/packages/tauri.mdx

@@ -21,7 +21,7 @@ Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')`
 
 ```toml
 [dependencies]
-reticle-tauri = "3.1"
+reticle-tauri = "3.3"
 ```
 
 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.

package/docs/packages.mdx

@@ -239,7 +239,7 @@ A lint rule makes the signal layer self-enforcing, which is the only way a conve
 
 ```toml
 [dependencies]
-reticle-tauri = "3.1"
+reticle-tauri = "3.3"
 ```
 
 <Warning>

package/docs/predicates.mdx

@@ -48,7 +48,17 @@ Take the advice. `element` and `text` are convenient and weak; `signal`, `state`
 }
 ```
 
-`query` accepts `role`, `name`, `text`, `label`, `placeholder`, `testid`, `alt`, `scope`. `state` is one of `visible`, `hidden`, `enabled`, `disabled`, `checked`, `expanded`, `focused`, `present`.
+`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`, `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.
+
+`attrs` is a list of attribute **names**, such as `["href", "data-status"]`. It **projects** those attributes onto each match so you can read them back, and it does not filter. `["data-status=complete"]` is refused: it would otherwise look up an attribute literally named `data-status=complete`, find none, and leave the predicate resting on the locator alone, which is a green for any value the element happens to hold.
+
+To READ the values, call `reticle_query` with `attrs` and look at the `attrs` map on each match. To ASSERT one: a form field's value goes in the query as `value`, while a state expressed as a data attribute is better asserted as the consequence it stands for, such as a `signal`, a `net` call, or the text the user actually sees.
+
+```json
+{ "kind": "element", "query": { "role": "textbox", "name": "Amount", "value": "274.58" } }
+```
 
 Add `"absent": true` to assert something is **gone**. The predicate for a removal, a dismissed toast, or a regression check.
 
@@ -62,6 +72,26 @@ Add `"absent": true` to assert something is **gone**. The predicate for a remova
 
 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`.
 
+`satisfies` asserts a PROPERTY of the rendered text instead of its exact bytes: the same shape and the same properties [`state` accepts](#satisfies-asserting-a-property-instead-of-exact-bytes), applied where the user actually reads the value:
+
+```json
+{
+  "kind": "text",
+  "scope": "[data-testid=\"release-note\"]",
+  "self": true,
+  "satisfies": { "property": "nonEmpty" }
+}
+```
+
+That is the assertion a generated feature can pass twice. `contains` demands bytes a model's output does not repeat, so it either fails on correct output or gets weakened to a word so common it proves nothing; "the box rendered and there is something in it" is the failure the feature actually has.
+
+Two rules, both refusals rather than guesses:
+
+- **One of `contains` or `satisfies` is required.** With neither, the predicate matches any element with any text and cannot fail.
+- **`satisfies` on its own needs a `scope`** (the element whose text is read, with `self: true` for the root's own subtree). Without one the locator is every element on the page, and the property would run against whichever matched first.
+
+Both may be given, and then both must hold. `satisfies` narrows, it never excuses.
+
 ### net
 
 ```json
@@ -76,6 +106,22 @@ The one that catches the expensive bug:
 
 **Exactly one.** Double-submit fails at two, and nothing on screen would have told you.
 
+Two fields read the RESPONSE BODY, so a request that succeeded with the wrong number is still a failure:
+
+```json
+{ "kind": "net", "urlContains": "/api/refund", "bodyContains": "\"refunded\":11.87" }
+```
+
+`bodyContains` is a substring test over the response body. It is deliberately not a JSON path: the string above is the whole assertion, it needs no schema, and it behaves the same on JSON, form encoding and plain text.
+
+```json
+{ "kind": "net", "urlContains": "/api/job", "bodyMatches": { "status": "completed" } }
+```
+
+`bodyMatches` is a shallow field match, keyed like `signal.dataMatches` and taking the same operators (`*`, `$gte`, `$contains`). 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.
+
 ### route
 
 ```json
@@ -158,6 +204,72 @@ Omit `equals` entirely to assert presence. A real `$length` check against this f
 
 Note `grade: state` in the `because` line, and that the evidence collapses each row to a size marker rather than returning forty objects.
 
+#### satisfies: asserting a property instead of exact bytes
+
+`equals` cannot express output that is right differently every run. A generated summary, a classification, a computed total: each is correct without being predictable, and an assertion that demands exact bytes either fails on correct output or gets weakened until it proves nothing. `satisfies` is the other half of `state`, and it stays decidable here with no model and no network.
+
+```json
+{ "kind": "state", "store": "app", "path": "summary.text", "satisfies": { "property": "nonEmpty" } }
+```
+
+| `property` | Extra fields | Holds when |
+| --- | --- | --- |
+| `nonEmpty` | none | it produced something at all, the honest floor for any output |
+| `oneOf` | `values` | it landed inside the allowed set, exact membership, no coercion |
+| `withinTolerance` | `of`, `tolerance` | a number near enough to the expected one, inclusive on the bound |
+| `matchesPattern` | `pattern` | its string form matches that regular expression |
+| `type` | `is` | it is that kind of thing; `array` and `object` are distinguished, which `typeof` cannot do |
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [
+    {
+      "kind": "state",
+      "path": "invoice.total",
+      "satisfies": { "property": "withinTolerance", "of": 274.58, "tolerance": 0.01 }
+    },
+    {
+      "kind": "state",
+      "path": "invoice.status",
+      "satisfies": { "property": "oneOf", "values": ["draft", "sent"] }
+    },
+    { "kind": "state", "path": "invoice.lines", "satisfies": { "property": "type", "is": "array" } }
+  ]
+}
+```
+
+`equals` and `satisfies` may both be given, and then both must hold. A failing check always says what it saw, because an assertion that reports only `false` sends you back for another call to find out why, and that round trip is most of what a verdict costs.
+
+#### The relative properties: comparing with before
+
+The properties above read the present tense. Four read the past one. They compare this value with the reading taken **before the action**, which is the window a verdict is already scoped to:
+
+| property    | holds when                  |
+| ----------- | --------------------------- |
+| `unchanged` | the value is the one it was |
+| `changed`   | it is not                   |
+| `increased` | the number went up          |
+| `decreased` | the number went down        |
+
+```json
+{
+  "kind": "state",
+  "path": "cart.total",
+  "satisfies": { "property": "decreased", "by": { "op": "equals", "value": 12 } }
+}
+```
+
+`increased` and `decreased` take an optional `by`, in the protocol's own comparison vocabulary: `op` is `equals`, `at-least` or `at-most`, with an optional `tolerance` on all three. Without `by`, any movement in the right direction holds.
+
+**Give a money assertion a tolerance.** `100 - 88.13` is `11.870000000000005`, so `{ "op": "equals", "value": 11.87 }` misses by a rounding error and reads as the app charging the wrong amount. `"tolerance": 0.01` is the fix; the failure message says so when the miss is that small.
+
+A number is read out of displayed text, so `"$1,234.50"` compares as `1234.5`. A reading with no digits in it is **not** zero. `"sold out"` reports that nothing was subtracted rather than pretending the total fell to nothing.
+
+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 miss quotes the real value back at you:
 
 ```json
@@ -191,6 +303,33 @@ This is the predicate that catches a UI-versus-store desync. A deploy that only
 
 Network and DOM idle. This is the deterministic replacement for a fixed sleep, not a proof of anything: combine it with a real consequence rather than asserting it alone. Omitting `until` on [`reticle_act_and_wait`](/tools/act-and-wait) waits for exactly this.
 
+## Asserting a failure on purpose
+
+A fault-injection test (mock a 500, check the error UI) is asserting that a request **fails**. Say so in the predicate, or the verdict will disagree with you:
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [
+    { "kind": "text", "contains": "Something went wrong" },
+    { "kind": "net", "method": "POST", "urlContains": "/api/save", "status": 503 }
+  ]
+}
+```
+
+Asserting only the error text is not enough, and this is the most common way to get a confusing `verified: "no"`. Reticle watches for "the UI moved forward while a request failed", a swallowed rejection, and one of the most expensive bugs it catches. A fault-injection test looks **exactly** like that bug from the outside: a request failed, the screen changed, nothing said that was the plan.
+
+Naming the failing call is what tells the two apart. A `net` clause with `status` of 400 or more, or `"ok": false`, which is the honest field for IPC, where there is no status code, marks that call as expected to fail, and a failure there stops being a disagreement.
+
+<Warning>
+  Declare it in the top level or inside `allOf`. A declaration inside `anyOf` is deliberately
+  ignored: only one branch of an `anyOf` has to hold, so honouring it would suppress a real
+  contradiction on the strength of a branch that never ran. `not` is ignored for the same reason in
+  reverse: `not { net status: 500 }` asserts the call did *not* fail.
+</Warning>
+
+One case is inferred for you: an `element` or `text` clause naming an access denial ("not authorised", "sign in to continue") marks the auth statuses as expected, because a denial screen is a correct outcome rather than a fault. Everything else has to be named.
+
 ## Combinators
 
 ```json
@@ -210,7 +349,8 @@ Network and DOM idle. This is the deterministic replacement for a fixed sleep, n
 ```
 
 <Warning>
-A combinator needs its own `kind`, and the children go in `predicates`. A bare
+A combinator needs its own `kind`, and the children go in `predicates`, or in `of`, which is
+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.
@@ -249,9 +389,9 @@ 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 |
-| `since` | `net` and `console` leaves, and the call itself | Only consider events after this cursor |
+| `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.
+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.
 
 <Card title="Where predicates get used" icon="circle-check" href="/tools/act-and-wait">
   Naming the consequence before the action is the whole point.

package/docs/system-map.md

@@ -56,11 +56,13 @@ Three different counts, all measured, and the difference between them matters:
 
 | Count | What it is |
 | --- | --- |
-| **68** | name constants in `ReticleTool` |
-| **48** | tools advertised under `RETICLE_ADVERTISE_ALL_TOOLS=1`, i.e. what `tool-surface-sweep-test` drives (51 calls) |
-| **19** | advertised by default; the rest are reached through `reticle_run` |
+| **76** | name constants in `ReticleTool` |
+| **30** | tools advertised under `RETICLE_ADVERTISE_ALL_TOOLS=1`, i.e. what `tool-surface-sweep-test` drives |
+| **10** | advertised by default; the rest are reached through `reticle_run { tool, args }` |
 
-68 → 48 is **family folding**: `reticle_baseline`, `reticle_session`, `reticle_record`, `reticle_flow` and `reticle_lease` each absorb their members behind an `action` parameter. So "every tool is callable" is asserted over 48 surfaces, not 68 behaviours; a family member reachable only through an `action` value the sweep never passes is not covered by it. Worth closing when the per-tool budget lands (see [`gate-plan.md`](https://github.com/reticlehq/reticle/blob/main/docs/gate-plan.md), Phase 4).
+The middle number is **family folding**: `reticle_baseline`, `reticle_session`, `reticle_record`, `reticle_flow` and `reticle_lease` each absorb their members behind an `action` parameter. So "every tool is callable" is asserted over the advertised surfaces, not over every named behaviour; a family member reachable only through an `action` value the sweep never passes is not covered by it. Worth closing when the per-tool budget lands (see [`gate-plan.md`](https://github.com/reticlehq/reticle/blob/main/docs/gate-plan.md), Phase 4).
+
+These three were each wrong by the time somebody checked: the table read 68 / 48 / 19 against a measured 76 / 30 / 10, and the middle one had a derived token cost hanging off it. `surface-sizes.test.ts` is the authority and fails when a surface changes size, so prefer reading it to trusting this row.
 
 | Token | Produced by | Consumed by | Invalidated by |
 | --- | --- | --- | --- |

package/docs/telemetry.md

@@ -37,6 +37,7 @@ Eighteen kinds of events, each a single small JSON object. This is the whole lis
 | `runtime_crashed` | The daemon hits an uncaught error | The error's type, **Reticle's own** stack frames, and the message with variables stripped; see below |
 | `mcp_client_connected` | An agent attaches to the daemon | Whether it is a reconnect, and how long the daemon had been idle |
 | `mcp_connection_lost` | The agent's MCP tools go away | Which stage (`first`, or `budget_spent` when it stopped retrying), the cause, and the attempt count. **At most twice per session**, because a reconnect loop can fire many times in a row and an event each would bill for the pathology instead of measuring it |
+| `onboarding_step` | One step of getting set up begins, finishes, fails, is skipped, or is walked away from | Which phase (`install`, `onboard`, `first_run`), which step, what became of it, how long it took, and the framework. The step name comes from a closed list we define -- it can only ever be one of the names in `core/src/onboarding.ts`, so nothing you typed or any path on your disk can arrive in it. `unattended` says whether anybody was asked anything |
 | `init_completed` | `reticle init` finishes | Whether it worked, a classified reason when it did not, and which published install route you came through, DECLARED by that route via `RETICLE_INSTALL_SOURCE` and never inferred, and `unknown` when nothing declared one |
 | `bug_found` | Reticle finds a defect in the app under test | The **kind** of defect (`signal-contradicted`, `console-error`, …) and how it was found, never what it was found in |
 | `tool_refused` | A tool cannot do what an agent asked | Which tool, why (one of six buckets: no session, no match, unsupported, bad arguments, not ready, other), and whether the same call was retried. **Never the message**, because a refusal interpolates whatever you asked for, so only the tool name and the bucket are sent. Capped at 50 per daemon run |
@@ -57,7 +58,7 @@ It also carries a snapshot of the **machine's** state (our own process's memory,
 
 It exists because `verified: "unknown"` covered seven different situations belonging to three different owners (your app, your agent, and Reticle's own blind spots), and they arrived as one value. It is a **name from our own vocabulary**, never a description of your app: `contradicted` says two channels disagreed, not which ones, about what, or on which page.
 
-When the clause is `unclean_capture`, one further name says which of our three losses caused it: `buffer_loss` (our server's event buffer), `transport_gap` (our browser-side queue), `blind_spot` (a boundary in the page, such as a cross-origin frame), or `other`. All four are facts about **Reticle's** ability to observe, not about what it observed. This field is how we found that Reticle was refusing to answer over windows that were completely intact.
+When the clause is `unclean_capture`, one further name says which of our losses caused it: `buffer_loss` (our server's event buffer), `transport_gap` (our browser-side queue), `journal_loss` (our on-disk event ledger reached its size cap), `blind_spot` (a boundary in the page, such as a cross-origin frame), or `other`. All five are facts about **Reticle's** ability to observe, not about what it observed. This field is how we found that Reticle was refusing to answer over windows that were completely intact.
 
 ### Bugs Reticle finds
 

package/docs/token-efficiency.md

@@ -53,11 +53,11 @@ Measured live, all servers in one run, same tokenizer (`bench/harness/schema-tax
 | **Reticle, the tool surface**            |    18 |    **~4,930** |
 | Playwright MCP                           |    23 |         3,725 |
 | Chrome DevTools MCP                      |    29 |         5,116 |
-| Reticle, `RETICLE_ADVERTISE_ALL_TOOLS=1` |    48 |       ~30,200 |
+| Reticle, `RETICLE_ADVERTISE_ALL_TOOLS=1` |    30 |       ~30,200 |
 
 _Measured 2026-08-12 (`bench/raw/schema-tax.json`). Reticle's default surface has gained a tool since, so treat the first row as a floor._
 
-The default surface is the verify loop plus `reticle_tools`, and it is CLOSED: those nine names are the whole of what can be called. There is no `reticle_run` dispatch hatch on it, so the cold tail is not merely un-advertised, it is unreachable until the daemon is started with `RETICLE_ADVERTISE_ALL_TOOLS=1`.
+The default surface is the verify loop plus `reticle_tools` and `reticle_run`. The cold tail is un-advertised rather than unreachable: `reticle_run { tool, args }` calls any registered tool by name, and `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises the whole table outright for suites that prefer that. Dropping the hatch was tried, and it left eleven registered tools callable by nothing at all.
 
 `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises everything WITH output schemas. It is a verification switch for suites that call by name, not a mode to run agents in. It is roughly 7x the per-turn cost, which is why it is opt-in.
 

package/docs/tools/overview.mdx

@@ -13,7 +13,7 @@ That is not a limitation, it's the design. MCP re-sends every advertised tool de
 
 A wider surface costs tokens on every message. Less obviously, it makes the model wander: give it fifty ways to look at a page and it will try several before doing anything useful.
 
-What the nine do **not** reach are the specialised tools: `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock`, `reticle_clock`. There is no dispatch hatch on this surface by design, so those need a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1`.
+What the verify loop does **not** advertise are the specialised tools: `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock`, `reticle_clock`. Each is one `reticle_run { tool, args }` hop away, and a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises them outright.
 
 <Note>
   Measured off the real wire on 2026-09-16, by reading `tools/list` from a fresh daemon: the default

package/docs/tools/query.mdx

@@ -52,16 +52,16 @@ Seven buttons, each with a `ref` to act on and a source file to open, for 236 to
 
 ## Arguments
 
-| Argument     | What it does                                                               |
-| ------------ | -------------------------------------------------------------------------- |
-| `by`         | `role` · `text` · `label` · `placeholder` · `testid` · `alt` · `component` |
-| `value`      | The query value for that strategy                                          |
-| `name`       | Accessible-name filter. Narrows a broad `role` query                       |
-| `scope`      | CSS selector or ref, to search inside a subtree                            |
-| `limit`      | Cap the descriptors returned. Cuts tokens hard on broad queries            |
-| `count_only` | Return just `{ count }`, around 30x smaller                                |
-| `attrs`      | Extra attributes per match, e.g. `['href']` to inventory links             |
-| `self`       | Return the `scope` element itself instead of searching inside it           |
+| Argument | What it does |
+| --- | --- |
+| `by` | `role` · `text` · `label` · `placeholder` · `testid` · `alt` · `component` |
+| `value` | The query value for that strategy |
+| `name` | Accessible-name filter. Narrows a broad `role` query |
+| `scope` | CSS selector or ref, to search inside a subtree |
+| `limit` | Cap the descriptors returned. Cuts tokens hard on broad queries |
+| `count_only` | Return just `{ count }`, around 30x smaller |
+| `attrs` | Attribute NAMES to project per match, e.g. `['href']` to inventory links. The values come back in each match's `attrs` map. It does not filter, so `name=value` is refused |
+| `self` | Return the `scope` element itself instead of searching inside it |
 
 Every argument also has a predicate spelling, so `{ "role": "button" }` works as shorthand for `{ "by": "role", "value": "button" }`.
 

package/docs/troubleshooting.mdx

@@ -39,7 +39,7 @@ By far the most common. Reticle's own diagnostic is unusually good here. It tell
 ```json
 {
   "sessionCount": 0,
-  "why": "no browser session connected, but one WAS connected to this daemon earlier, so the wiring is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen the app (or run `reticle open`), or reload the tab. You do not have to wait for the human: reticle_lease {action:\"acquire\", url} opens a browser Reticle drives itself, and returns a sessionId you can use immediately (reach it with reticle_run {tool:\"reticle_lease\"} if it is not advertised directly; release it when you finish). Then call reticle_session { action: "list" } again."
+  "why": "no browser session connected, but one WAS connected to this daemon earlier, so the wiring is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen the app (or run `reticle open`), or reload the tab. You do not have to wait for the human: reticle_lease {action:\"acquire\", url} opens a browser Reticle drives itself, and returns a sessionId you can use immediately (reach it with reticle_run {tool:\"reticle_lease\"} if it is not advertised directly; release it when you finish). Then call reticle_session { action: \"list\" } again."
 }
 ```
 
@@ -186,7 +186,7 @@ The usual cause is a throttled tab: throttling suppresses the quiescence detecti
 If it persists on an unthrottled context, that is worth reporting. Reticle's own response says so:
 
 ```json
-"feedback_invite": "Reticle could not tell what happened here. If you expected otherwise, reticle_session { action: "feedback" }. An unknown verdict is our defect, not yours"
+"feedback_invite": "Reticle could not tell what happened here. If you expected otherwise, reticle_session { action: \"feedback\" }. An unknown verdict is our defect, not yours"
 ```
 
 ## A negative result you are not sure about
@@ -227,6 +227,12 @@ React 19 dropped `_debugSource`. Wire up `@reticlehq/babel-plugin`. Or just use
 
 `@reticlehq/next` declares `peer next >=13` and `@reticlehq/react` declares `peer react >=18`. On a Next canary or React RC, npm refuses. See [the prerelease notes](/getting-started#installing-alongside-a-nextjs-or-react-prerelease).
 
+## The tool list is empty
+
+Some clients read their MCP tool list once, at startup, and never again. Cursor Cloud Agent is the usual report: the daemon is listening on port 4400, the app is instrumented, and `reticle_*` is absent for the whole session. Restarting the client picks the tools up when a restart is possible. When it is not, the same tools are on the HTTP transport.
+
+`GET /mcp/sse` opens the session. The first SSE frame is an `endpoint` event whose data is the path to POST to, including the session id. POST JSON-RPC there. The POST answers `202` with an empty body, and the result comes back on the SSE stream. The handshake and a working client are in [HTTP transport](/http-transport).
+
 ## Restarting things
 
 ```bash