@reticlehq/server 2.8.0 → 2.9.0

package/docs/tools-act.mdx

@@ -15,37 +15,48 @@ icon: hand-pointer
 ## Example
 
 ```json
-{ "ref": "e102", "action": "fill", "args": { "value": "reticle" } }
+{ "ref": "e104", "action": "fill", "args": { "value": "reticle" } }
 ```
 
 Real response:
 
 ```json
 {
-  "since": 28123,
+  "since": 27544,
   "inputMode": "synthetic",
+  "inputModeReason": "not-a-pointer-action",
   "dispatched": true,
-  "settled": false,
-  "settleReason": "timeout",
+  "settled": true,
+  "settleReason": null,
   "result": {
     "ok": true,
-    "ref": "e102",
+    "ref": "e104",
     "action": "fill",
+    "dispatched": true,
+    "settled": true,
+    "settleReason": null,
     "testid": "login-password",
     "component": "Login",
     "role": "textbox",
     "name": "Password",
     "effect": {
-      "visible": false,
-      "focusMoved": "null->e102",
+      "focusMoved": "null->e104",
       "valueChanged": true,
-      "domMutatedWithin": 15
+      "domMutatedWithin": 9
     },
     "source": { "file": "src/components/Login.tsx", "line": 59, "column": 8 }
   }
 }
 ```
 
+<Note>
+  The `effect` block only lists what is worth knowing. Fields sitting at their uninformative default
+  are **omitted**, so a clean action collapses to its consequence. An absent `dispatched`,
+  `targetMatched`, `visible` or `enabled` means `true`; an absent `occluded`, `scrolledIntoView`,
+  `valueChanged` or `defaultPrevented` means `false`; an absent `focusMoved` or `occludedBy` means
+  `null`. Do not read a missing field as a failure.
+</Note>
+
 ## Actions
 
 `click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag` · `webmcp`
@@ -62,19 +73,21 @@ Real response:
 This is where `act` earns its place even though it proves nothing.
 
 - **`valueChanged: true`**. The field actually took the value. `false` on a `fill` usually means the input is controlled and rejected it, or it's readonly.
-- **`focusMoved: "null->e102"`**, focus went where you expected.
-- **`domMutatedWithin: 15`**, something re-rendered within 15ms. A `fill` that mutates nothing often means no handler is attached.
+- **`focusMoved: "null->e104"`**, focus went where you expected.
+- **`domMutatedWithin: 9`**, something re-rendered within 9ms. A `fill` that mutates nothing often means no handler is attached.
 - **`defaultPrevented`**. A handler called `preventDefault()`, which is why your form didn't submit.
 - **`occluded` / `occludedBy`**. The click landed on something else. This is the answer to at least half of all "the button doesn't work" reports.
 
 ## `settled: false` is not a failure
 
-`settleReason: "timeout"` means the page was still busy when Reticle stopped watching. On a `fill` that's normal and uninteresting. On a click you expected to complete something, it's a hint that you wanted `act_and_wait` with an explicit `until`.
+`settled: true` with `settleReason: null`, as above, means a real frame flushed before Reticle stopped watching. `settled: false` with `settleReason: "timeout"` means the page was still busy. On a `fill` that's normal and uninteresting. On a click you expected to complete something, it's a hint that you wanted `act_and_wait` with an explicit `until`. A settle timeout never fails the tool.
 
 ## `inputMode` tells you how real the input was
 
 `synthetic` means Reticle dispatched events programmatically. `real` means native CDP input, available under `reticle drive`. Synthetic input is fine for the overwhelming majority of apps; a few drag-and-drop and pointer-gesture libraries only respond to the real thing.
 
+`inputModeReason` explains any choice Reticle made on your behalf, so it is never silent. `not-a-pointer-action` above means a `fill` has no pointer path to take, not that real input was unavailable. Clicks default to the occlusion-honest synthetic path even when CDP is configured; pass `args.native: true` to force a trusted native click for file pickers and clipboard access.
+
 <Warning>
   When the tab is backgrounded, synthetic timers and pointer gestures can silently no-op. Every
   response carries a `warning` when the tab is throttled. Pass `refuseWhenThrottled: true` to make

package/docs/tools-assert.mdx

@@ -4,14 +4,16 @@ description: Evaluate a predicate against what the app actually did, and get a v
 icon: gavel
 ---
 
-`reticle_assert` is the second of the two tools that produce a verdict. It takes the same predicate grammar as [`reticle_act_and_wait`](/tools-act-and-wait) and evaluates it against what already happened.
+`reticle_assert` evaluates a predicate against what the app actually did and returns a verdict: `verified` plus `pass`, evidence when it holds, and `expected` versus `observed` when it does not. Reach for it when you want a verdict on something you did not just cause, or on several actions at once.
+
+It is the second of the two tools that produce a verdict, the other being [`reticle_act_and_wait`](/tools-act-and-wait). It takes the same predicate grammar and evaluates it against what already happened.
 
 ## A real failure
 
 Failures are more instructive than passes, so here is one. I asserted a route change to `/` on a page that was already at `/`:
 
 ```json
-{ "predicate": { "kind": "route", "path": "/" } }
+{ "predicate": { "kind": "route", "pathname": "/" } }
 ```
 
 ```json
@@ -24,10 +26,20 @@ Failures are more instructive than passes, so here is one. I asserted a route ch
   "observed": "no route change in the window",
   "expected": "a route change to /",
   "assertion": "route.changed",
-  "source": "src/components/Login.tsx:81"
+  "source": "src/components/Login.tsx:81",
+  "buffer": {
+    "held": 536,
+    "dropped": 11,
+    "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
+  }
 }
 ```
 
+<Note>
+  The route predicate's field is `pathname`. `path` is accepted as an alias and rewritten, but
+  `pathname` is what the published schema declares, so it is the one to write.
+</Note>
+
 <Warning>
   Read `assertion: "route.changed"` carefully. The `route` predicate asserts that the route
   **changed**, not that it currently equals a value. Asserting the route you are already on will
@@ -37,20 +49,67 @@ Failures are more instructive than passes, so here is one. I asserted a route ch
 
 Note also `expected` and `observed` side by side. A verdict that says only "failed" makes you go digging; this one tells you what it wanted, what it saw, and where in your source the relevant element lives.
 
+## A failure that names the real value
+
+The same shape on a store read, which is the strongest kind of failure you can get, because it quotes the app's own data back at you:
+
+```json
+{
+  "predicate": { "kind": "state", "store": "app", "path": "deployments.0.status", "equals": "live" }
+}
+```
+
+```json
+{
+  "verified": "no",
+  "verifiedReason": "assertion_failed",
+  "because": "the declared consequence did not hold",
+  "pass": false,
+  "failureReason": "state 'deployments.0.status' is \"queued\", expected \"live\"",
+  "observed": "deployments.0.status = \"queued\"",
+  "expected": "deployments.0.status = \"live\"",
+  "assertion": "state.equals",
+  "evidence": { "store": "app", "path": "deployments.0.status", "value": "queued" },
+  "source": "src/components/Login.tsx:81"
+}
+```
+
+## A pass can still come with a warning
+
+A presence-only predicate passes and tells you not to trust it much:
+
+```json
+{
+  "verified": "yes",
+  "pass": true,
+  "evidence": [
+    {
+      "ref": "e606",
+      "role": "alert",
+      "name": "Invalid email or password",
+      "visible": true,
+      "source": "src/components/Login.tsx:72",
+      "states": ["present", "visible", "enabled"]
+    }
+  ],
+  "advice": "This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked."
+}
+```
+
 ## Arguments
 
-| Argument                 | What it does                                               |
-| ------------------------ | ---------------------------------------------------------- |
-| `predicate` (or `until`) | `{ kind, ...fields }`                                      |
-| `timeout_ms`             | If above zero, wait this long before failing               |
-| `since`                  | Cursor from a prior act. Scope to events after that action |
+| Argument                 | What it does                                                      |
+| ------------------------ | ----------------------------------------------------------------- |
+| `predicate` (or `until`) | `{ kind, ...fields }`. See the [predicate reference](/predicates) |
+| `timeout_ms`             | If above zero, wait this long before failing. Default `0`         |
+| `since`                  | Cursor from a prior act. Scope to events after that action        |
 
 ## Scope it with `since`
 
-Without `since`, an assertion evaluates against the recent buffer, which may contain events from before your action. That can pass for the wrong reason. The request you are asserting fired, but it fired two clicks ago.
+By default an assertion already counts only events since your last act, so a signal buffered before the action cannot fake a pass. Pass `since` when you want to set that window explicitly: to scope to one particular earlier action, or to widen it deliberately across several.
 
 ```json
-{ "predicate": { "kind": "net", "method": "POST" }, "since": 28123 }
+{ "predicate": { "kind": "net", "method": "POST" }, "since": 44395 }
 ```
 
 The cursor comes from the preceding `reticle_act` response. Use it whenever you are asserting something an action was supposed to cause.

package/docs/tools-console.mdx

@@ -4,6 +4,8 @@ description: The console log, filtered by level, and an empty result that tells
 icon: terminal
 ---
 
+`reticle_console` returns the app's console log, filtered by level, and tells you whether an empty result is a real reading or a missing one. Reach for it as the fast triage read after something goes wrong, and assert `{ "kind": "console", "absent": true }` when you want a clean console to be part of the pass.
+
 ```json
 { "limit": 3 }
 ```
@@ -14,13 +16,13 @@ Real response from a page with a clean console:
 {
   "logs": [],
   "buffer": {
-    "held": 15,
-    "dropped": 571,
+    "held": 535,
+    "dropped": 10,
     "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
   },
   "observed": true,
   "note": "no console lines; the observation ran and found none, which is a result, not a missing reading",
-  "cost": { "bytes": 340, "tokens": 85 }
+  "cost": { "bytes": 338, "tokens": 85 }
 }
 ```
 
@@ -29,9 +31,9 @@ Real response from a page with a clean console:
 An empty array is ambiguous in almost every tool that returns one. Did nothing happen, or did the observation not run? Reticle answers both:
 
 - **`observed: true`** with that `note`. The observation ran and genuinely found nothing. You may treat a clean console as a fact.
-- **`buffer.dropped: 571`**, older events were evicted. If you are asking about something from a while ago, the honest answer is "not in what I still have", not "it didn't happen".
+- **`buffer.dropped: 10`**, older events were evicted. If you are asking about something from a while ago, the honest answer is "not in what I still have", not "it didn't happen".
 
-Read both fields together. `observed: true` with a large `dropped` count means _recently_ clean, which is usually what you wanted but is not the same as _always_ clean.
+Read both fields together. `observed: true` with a non-zero `dropped` count means _recently_ clean, which is usually what you wanted but is not the same as _always_ clean.
 
 ## Arguments
 
@@ -47,7 +49,7 @@ Read both fields together. `observed: true` with a large `dropped` count means _
 Plenty of features "work" while quietly throwing. Assert the clean console as part of the action rather than checking afterwards:
 
 ```json
-{ "ref": "e103", "action": "click", "until": { "kind": "console", "absent": true } }
+{ "ref": "e605", "action": "click", "until": { "kind": "console", "absent": true } }
 ```
 
 That fails if the click succeeds _and_ logs an error, which is exactly the case a human reviewer tends to wave through.
@@ -55,5 +57,7 @@ That fails if the click succeeds _and_ logs an error, which is exactly the case
 <Tip>
   `level: "error"` is the fast triage read. If it comes back empty with `observed: true`, stop
   looking at the console and go look at [`reticle_network`](/tools-network) or
-  [`reticle_state`](/tools-state) instead.
+  [`reticle_state`](/tools-state) instead. That is a real capture from this fixture:
+  `{"logs":[],"observed":true,"cost":{"bytes":337,"tokens":85}}`, eighty-five tokens to rule out a
+  whole class of bug.
 </Tip>

package/docs/tools-inspect.mdx

@@ -9,14 +9,14 @@ icon: crosshairs
 ## Example
 
 ```json
-{ "ref": "e20" }
+{ "ref": "e120" }
 ```
 
 Real response:
 
 ```json
 {
-  "ref": "e20",
+  "ref": "e120",
   "role": "button",
   "name": "Compose",
   "visible": true,
@@ -24,7 +24,7 @@ Real response:
   "tag": "button",
   "occluded": false,
   "states": ["present", "visible", "enabled"],
-  "box": { "x": 14, "y": 211.75, "width": 219, "height": 37.5 },
+  "box": { "x": 14, "y": 212.75, "width": 219, "height": 38 },
   "styles": {
     "color": "rgb(147, 152, 168)",
     "backgroundColor": "rgba(0, 0, 0, 0)",
@@ -33,14 +33,15 @@ Real response:
     "display": "flex",
     "visibility": "visible"
   },
+  "scroll": { "scrollTop": 0, "scrollHeight": 36, "clientHeight": 36, "overflowY": "visible" },
   "theme": {
     "colorToken": "--muted",
-    "colorTokens": ["--muted"],
     "backgroundToken": null,
-    "backgroundTokens": [],
     "offTheme": false,
-    "tokenCount": 17,
-    "themeScope": ":root"
+    "tokenCount": 18,
+    "themeScope": null,
+    "colorTokens": ["--muted"],
+    "backgroundTokens": []
   },
   "component": {
     "componentStack": ["Sidebar", "App", "QueryClientProvider"],
@@ -55,7 +56,9 @@ Real response:
 
 **`theme`** catches a bug class most tools cannot see. `colorToken: "--muted"` means this colour came from your design system. `offTheme: false` means nothing here is a hardcoded hex that slipped past review. An agent that pastes `color: #939AA8` instead of using the token produces a change that looks identical and quietly forks your design system. This field is how that gets caught.
 
-Read `colorTokens` rather than `colorToken` when it matters. Design systems routinely give several tokens the same value, and the singular field is `null` whenever more than one matches, because naming an arbitrary winner is worse than admitting the palette cannot tell them apart. `themeScope` says which theme the reading was taken under, so two inspects either side of a theme toggle are comparable instead of quietly contradictory.
+Read `colorTokens` rather than `colorToken` when it matters. Design systems routinely give several tokens the same value, and the singular field is `null` whenever more than one matches, because naming an arbitrary winner is worse than admitting the palette cannot tell them apart. `themeScope` says which theme the reading was taken under, so two inspects either side of a theme toggle are comparable instead of quietly contradictory. It is `null`, as above, when the element sits under no scoped theme at all.
+
+**`scroll`** reports the element's own scroll box. `scrollHeight` above `clientHeight` means there is content below the fold inside this element, which is a different problem from the page being scrolled wrong.
 
 **`occluded`** is the difference between "visible" and "actually clickable". An element can be present, visible and enabled while sitting under a modal overlay. `states` will look perfect; `occluded: true` is the honest answer.
 

package/docs/tools-navigate.mdx

@@ -4,21 +4,37 @@ description: Move the connected tab to a URL or reload it, and understand why ok
 icon: compass
 ---
 
+`reticle_navigate` moves the connected browser tab to a URL, or reloads it in place with `{ "reload": true }`. Reach for it for a genuine document load: a deep link, a hard refresh, or the first visit. Clicking a link inside a single-page app is a route change, not a navigation, and does not need this tool.
+
 ```json
 { "url": "/deployments" }
 ```
 
-Real response:
+Real response, with the throttled-tab `session` and `warning` fields trimmed off:
 
 ```json
 {
   "ok": true,
-  "url": "http://localhost:4312/deployments",
+  "url": "http://localhost:4310/deployments",
   "confirmed": false,
   "note": "ok means the navigation was DISPATCHED, not that the page arrived. The SDK is torn down by the navigation itself, so nothing here can see the new document. Call reticle_sessions to confirm a session reconnected at the new URL before acting; if none appears, the page did not load or is not instrumented."
 }
 ```
 
+## `confirmed: true` when the page comes back in time
+
+The daemon waits briefly for the SDK to re-announce itself. When it does, you are told so and can act immediately without a `reticle_sessions` round trip. This is a real reload response:
+
+```json
+{
+  "ok": true,
+  "confirmed": true,
+  "note": "the page came back and re-announced itself under the same session id, so this session is live again. Anything captured before the reload is gone with the old document."
+}
+```
+
+Read the second sentence, which is the one that costs people a turn. `confirmed: true` restores the session, not the evidence: every event, network call and console line captured before the reload went with the old document.
+
 ## `confirmed: false` is the honest part
 
 A full navigation destroys the document the SDK was living in. Reticle cannot report on the new page from inside the old one, because the old one no longer exists. So it tells you what it actually knows: the navigation was dispatched.
@@ -40,8 +56,10 @@ then confirm a session reconnected:
 with [`reticle_sessions`](/tools-sessions), and only then snapshot. If no session appears at the new URL, the page did not load or is not instrumented. And you know that immediately rather than three calls later.
 
 <Warning>
-  **Refs do not survive a navigation.** A new document means new refs. The same "Sign in" button was
-  `e5` before a navigation and `e103` after. Re-snapshot; never carry refs across.
+  **Refs do not survive a navigation.** A new document means new refs. Across one afternoon on the
+  same fixture, the same "Sign in" button was `e105`, then `e305`, then `e3`. Re-snapshot; never
+  carry refs across. Reticle refuses a stale ref rather than clicking whatever now occupies the
+  slot, so the failure is loud, but it still costs you a turn.
 </Warning>
 
 ## Arguments
@@ -57,7 +75,25 @@ with [`reticle_sessions`](/tools-sessions), and only then snapshot. If no sessio
 In a single-page app, clicking a link usually changes the route without destroying the document. That is a route change, not a navigation. Refs survive, and you can assert it directly:
 
 ```json
-{ "ref": "e19", "action": "click", "until": { "kind": "route", "path": "/deployments" } }
+{ "ref": "e618", "action": "click", "until": { "kind": "route", "pathname": "/deployments" } }
+```
+
+That is a verified call. Its verdict quotes the transition itself:
+
+```json
+{
+  "verified": "yes",
+  "verdict": {
+    "pass": true,
+    "evidence": {
+      "from": "http://localhost:4310/",
+      "to": "http://localhost:4310/deployments",
+      "pathname": "/deployments",
+      "search": "",
+      "hash": ""
+    }
+  }
+}
 ```
 
 Use `reticle_navigate` for a genuine document load. A deep link, a hard reload, or the first visit.

package/docs/tools-network.mdx

@@ -4,7 +4,7 @@ description: A filtered log of every request the app made, with bodies, status,
 icon: satellite-dish
 ---
 
-`reticle_network` is how an agent checks the thing a screenshot fundamentally cannot show: whether the request actually happened, what it sent, and what came back.
+`reticle_network` returns a filtered log of every request the app made, with request and response bodies, status, timing, and automatic credential redaction. Reach for it to answer "did that call actually fire, and what came back?", which is the thing a screenshot fundamentally cannot show.
 
 ## Example
 
@@ -12,11 +12,22 @@ icon: satellite-dish
 { "limit": 3 }
 ```
 
-Real response:
+Real response, with the second call's `headers` block trimmed off:
 
 ```json
 {
   "calls": [
+    {
+      "method": "POST",
+      "url": "http://localhost:8787/api/login",
+      "status": 401,
+      "statusText": "Unauthorized",
+      "contentType": "application/json; charset=utf-8",
+      "responseSize": 37,
+      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}",
+      "responseBody": "{\"error\":\"invalid email or password\"}",
+      "ms": 23
+    },
     {
       "method": "POST",
       "url": "http://localhost:8787/api/login",
@@ -26,28 +37,30 @@ Real response:
       "responseSize": 67,
       "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}",
       "responseBody": "{\"token\":\"[REDACTED]\",\"user\":{\"email\":\"admin@reticle.dev\"}}",
-      "ms": 67
+      "ms": 4
     }
   ],
   "buffer": {
-    "held": 15,
-    "dropped": 529,
+    "held": 535,
+    "dropped": 10,
     "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
   },
-  "cost": { "bytes": 547, "tokens": 137 }
+  "cost": { "bytes": 1133, "tokens": 284 }
 }
 ```
 
+Two attempts at the same login, the first rejected and the second accepted, with the server's own error text attached to the failure. That is the whole diagnosis in one read.
+
 ## Redaction is automatic
 
-Look at `requestBody`. The password is `[REDACTED]` and so is the returned token, without anyone configuring anything. Reticle strips credential-shaped values before they leave the page, so your agent's context. And any transcript of it, never holds them.
+Look at `requestBody`. The password is `[REDACTED]` and so is the returned token, without anyone configuring anything. Reticle strips credential-shaped values before they leave the page, so neither your agent's context nor any transcript of it ever holds them.
 
 The email is not redacted, because an email is not a credential. The line is drawn at secrets.
 
 ## The buffer note is the important bit
 
 ```json
-"buffer": { "held": 15, "dropped": 529, "note": "…the evidence may have expired…" }
+"buffer": { "held": 535, "dropped": 10, "note": "…the evidence may have expired…" }
 ```
 
 Reticle keeps a bounded event buffer. When it overflows, older events are evicted. And if you then ask "did a POST to `/api/orders` happen?", the honest answer is not "no". It is "not in what I still have."
@@ -76,9 +89,29 @@ The bug where one click fires two POSTs is invisible on screen and obvious here:
 
 If `calls` has two entries with near-identical timestamps, you have found it. Better still, assert it up front so the agent cannot rationalise it afterwards. `reticle_act_and_wait` accepts an exact count predicate, which turns "roughly one request" into a check that fails at two.
 
+## A zero-match filter says what did fire
+
+That exact call, on a fixture that never touches `/api/orders`, comes back diagnosable rather than blank:
+
+```json
+{
+  "calls": [],
+  "hint": {
+    "totalInWindow": 1,
+    "present": [{ "method": "POST", "url": "http://localhost:8787/api/login", "status": 200 }]
+  },
+  "buffer": { "held": 1, "dropped": 281, "note": "…the evidence may have expired…" },
+  "cost": { "bytes": 328, "tokens": 82 }
+}
+```
+
+`hint.present` is the difference between "your endpoint never fired" and "you filtered on the wrong URL". Read it before you go looking in the app.
+
 ## Checking that nothing fired
 
-`ok: false` on an empty result is a genuinely useful answer. Provided the buffer note says nothing was dropped. Read both.
+`{ "ok": false }` keeps only the calls that failed, so an empty result there is a genuinely useful answer: nothing broke. Provided the buffer note says nothing was dropped. Read both.
+
+Desktop IPC (`ipc://`) has no status code, so its 200 and 500 are derived. Filter those on `ok` rather than `status`.
 
 <Card title="Prove it, don't just look at it" icon="circle-check" href="/quickstart">
   `reticle_network` reads. It does not produce a verdict. Name the expected request in

package/docs/tools-observe.mdx

@@ -4,7 +4,9 @@ description: The full timeline of everything the app did in a window. DOM, netwo
 icon: timeline
 ---
 
-`reticle_observe` is the wide-angle lens. Where `reticle_network` and `reticle_console` answer one question each, `observe` returns everything that happened in a window, in order.
+`reticle_observe` returns the full timeline of everything the app did in a window: DOM, network, routing, console, animations and signals, in order, with a summary on top. Reach for it when you do not yet know what went wrong. It reads and diagnoses; it does not produce a verdict.
+
+It is the wide-angle lens. Where `reticle_network` and `reticle_console` answer one question each, `observe` returns everything.
 
 ## Example
 
@@ -19,21 +21,32 @@ Real response:
   "window_ms": 4000,
   "events": [
     {
-      "t": 925870,
+      "t": 69964,
       "type": "page.health",
-      "seq": 586,
+      "seq": 544,
       "data": {
-        "hidden": true,
-        "focused": false,
+        "hidden": false,
+        "focused": true,
         "runtime": "web",
         "engine": "blink",
-        "brand": "chrome",
+        "brand": "other",
         "reason": "heartbeat"
       }
+    },
+    {
+      "t": 1282696,
+      "type": "net.detail",
+      "data": {
+        "url": "http://localhost:4310/",
+        "method": "GET",
+        "status": 200,
+        "resourceType": "document",
+        "pageUrl": "http://localhost:4310/"
+      }
     }
   ],
   "summary": {
-    "total": 1,
+    "total": 2,
     "network": 0,
     "domAdded": 0,
     "domRemoved": 0,
@@ -43,11 +56,16 @@ Real response:
     "animations": 0,
     "signals": 0
   },
-  "cost": { "events": 1, "bytes": 374 }
+  "cost": { "events": 2, "bytes": 845 },
+  "buffer": {
+    "held": 536,
+    "dropped": 11,
+    "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
+  }
 }
 ```
 
-A quiet window, honestly reported as quiet.
+A quiet window, honestly reported as quiet. The `headers` block on that `net.detail` event is trimmed out for length.
 
 ## Read the summary first
 
@@ -68,11 +86,49 @@ The `summary` block is the cheap answer. `consoleErrors: 0` and `network: 0` tel
 Every `reticle_act` response includes a `since` cursor. Passing it to `observe` scopes the timeline to exactly what followed that action, with no guessing about how many milliseconds to look back:
 
 ```json
-{ "since": 28123 }
+{ "since": 30224, "filters": ["signal", "net"] }
 ```
 
 This is more precise than `window_ms` and it does not drift when the machine is slow. Which matters, because a timing-based window that works on your laptop and fails in CI is a flaky test waiting to happen.
 
+Every event scoped this way carries its `actionId` and `attribution`, so you can tell what the action caused from what merely happened alongside it:
+
+```json
+{
+  "events": [
+    {
+      "t": 30691,
+      "type": "signal",
+      "seq": 29,
+      "data": { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } },
+      "actionId": "a1",
+      "attribution": "window"
+    }
+  ],
+  "summary": { "total": 3, "network": 1, "consoleErrors": 0, "signals": 1 },
+  "cost": { "events": 3, "bytes": 1457 }
+}
+```
+
+## `contradictions` is the field to read first
+
+When two channels disagree, `observe` says so without being asked:
+
+```json
+"contradictions": [
+  {
+    "kind": "response-ignored",
+    "claim": "1 write(s) succeeded on the server",
+    "counter": "nothing on the client changed, no DOM, store or route movement",
+    "detail": "POST http://localhost:8787/api/login 200"
+  }
+]
+```
+
+Punctuation in that block is lightly normalised for the docs; the field names and values are verbatim.
+
+A successful write that moved nothing on the client is the exact shape of a false green. Note that this one was a false alarm caused by a narrow filter: the same window's DOM and state did change, and the filtered read simply could not see it. Widen the window before you act on a contradiction.
+
 ## When to use it
 
 Use `observe` when you do not yet know what went wrong. Use the narrow tools when you do.