@reticlehq/server 2.14.0 → 3.2.0

package/docs/tools/inspect.mdx

@@ -0,0 +1,95 @@
+---
+title: reticle_inspect
+description: Everything about one element. Accessibility properties, geometry, computed styles, design tokens, React component stack, and the exact source file and line.
+icon: crosshairs
+---
+
+<Warning>
+  **reticle_inspect is not advertised.** The default surface is the merged nine, so an agent does not see
+  this name. Call **`reticle_look { action: "element" }`** instead. Everything below describes what that call does;
+  only the spelling changed. A call to the old name is answered with the new one, but an
+  `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
+</Warning>
+
+`reticle_query` finds elements. `reticle_inspect` tells you everything about one of them. It is the tool that turns a finding into an edit, because it ends with a file and a line number.
+
+## Example
+
+```json
+{ "ref": "e120" }
+```
+
+Real response:
+
+```json
+{
+  "ref": "e120",
+  "role": "button",
+  "name": "Compose",
+  "visible": true,
+  "source": "src/components/Sidebar.tsx:41",
+  "tag": "button",
+  "occluded": false,
+  "states": ["present", "visible", "enabled"],
+  "box": { "x": 14, "y": 212.75, "width": 219, "height": 38 },
+  "styles": {
+    "color": "rgb(147, 152, 168)",
+    "backgroundColor": "rgba(0, 0, 0, 0)",
+    "opacity": "1",
+    "cursor": "pointer",
+    "display": "flex",
+    "visibility": "visible"
+  },
+  "scroll": { "scrollTop": 0, "scrollHeight": 36, "clientHeight": 36, "overflowY": "visible" },
+  "theme": {
+    "colorToken": "--muted",
+    "backgroundToken": null,
+    "offTheme": false,
+    "tokenCount": 18,
+    "themeScope": null,
+    "colorTokens": ["--muted"],
+    "backgroundTokens": []
+  },
+  "component": {
+    "componentStack": ["Sidebar", "App", "QueryClientProvider"],
+    "source": { "file": "src/components/Sidebar.tsx", "line": 41, "column": 8 }
+  }
+}
+```
+
+## What each block is for
+
+**`component`** is the payoff. The stack `["Sidebar", "App", "QueryClientProvider"]` tells your agent where this element lives in the tree, and `source` tells it which file to open. This needs `@reticlehq/react`; without it you still get everything else.
+
+**`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. 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.
+
+**`box`** is geometry in CSS pixels. Useful for layout assertions and for working out whether something is off-screen rather than hidden.
+
+## When to reach for it
+
+<CardGroup cols={2}>
+  <Card title="A click did nothing" icon="hand-pointer">
+    Check `occluded` and `states` before assuming the handler is broken. Very often the handler is
+    fine and something is sitting on top of it.
+  </Card>
+  <Card title="You need to edit the code" icon="file-pen">
+    `component.source` is the file and line. This is the fastest path from symptom to diff.
+  </Card>
+  <Card title="A style looks wrong" icon="palette">
+    `theme.offTheme` tells you whether the value came from your tokens or from somebody's clipboard.
+  </Card>
+  <Card title="Layout is suspicious" icon="ruler">
+    `box` gives you real geometry, no screenshot and no vision model required.
+  </Card>
+</CardGroup>
+
+<Note>
+  `inspect` returns one element in detail. If you find yourself inspecting six things in a row, you
+  probably want [`reticle_query`](/tools/query) with `attrs` instead, one call, six answers.
+</Note>

package/docs/tools/navigate.mdx

@@ -0,0 +1,107 @@
+---
+title: reticle_navigate
+description: Move the connected tab to a URL or reload it, and understand why ok does not mean the page arrived.
+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, with the throttled-tab `session` and `warning` fields trimmed off:
+
+```json
+{
+  "ok": true,
+  "url": "http://localhost:4310/deployments",
+  "confirmed": false,
+  "waitedMs": 5000,
+  "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, and no session reconnected at the new URL within 5000ms. A slow app may still be on its way (an SPA reattaching under HMR can take 30-60s): navigate again with a larger timeout_ms, or call reticle_sessions to confirm a session reconnected 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 up to `timeout_ms` (default 5000) 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.
+
+Most tools would return `ok: true` and let you assume arrival. When the page then fails to load, or loads without instrumentation, you get a confusing cascade of "element not found" errors several calls later, with nothing pointing at the real cause.
+
+`waitedMs` says which of two things you are looking at. Reticle stopped waiting at the budget it had, or the page never came back. The first is fixed by asking for more: a single-page app reattaching under HMR has been measured at 30–60s, which no default should wait for on every call, but which the caller who knows the app can grant.
+
+```json
+{ "url": "/deployments", "timeout_ms": 45000 }
+```
+
+## The pattern after navigating
+
+```json
+{ "url": "/deployments" }
+```
+
+then confirm a session reconnected:
+
+```json
+{}
+```
+
+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. 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
+
+| Argument | What it does |
+| --- | --- |
+| `url` | Where to go. Relative paths work |
+| `reload` | Reload in place instead of navigating |
+| `hard` | With `reload`, bypass the cache |
+| `timeout_ms` | How long to wait for the page to come back before `confirmed: false`. Default 5000; 0 looks once |
+
+## Client-side routing is different
+
+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": "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

@@ -0,0 +1,126 @@
+---
+title: reticle_network
+description: A filtered log of every request the app made, with bodies, status, timing, automatic credential redaction, and an honest note when evidence has expired.
+icon: satellite-dish
+---
+
+<Warning>
+  **reticle_network is not advertised.** The default surface is the merged nine, so an agent does not see
+  this name. Call **`reticle_observe { action: "network" }`** instead. Everything below describes what that call does;
+  only the spelling changed. A call to the old name is answered with the new one, but an
+  `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
+</Warning>
+
+`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
+
+```json
+{ "limit": 3 }
+```
+
+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",
+      "status": 200,
+      "statusText": "OK",
+      "contentType": "application/json; charset=utf-8",
+      "responseSize": 67,
+      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}",
+      "responseBody": "{\"token\":\"[REDACTED]\",\"user\":{\"email\":\"admin@reticle.dev\"}}",
+      "ms": 4
+    }
+  ],
+  "buffer": {
+    "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": 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 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": 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."
+
+Most tools would return an empty array and let you draw the wrong conclusion. This one tells you the result may be a false negative and suggests grading sooner or widening the buffer. Take that note seriously: a confident "no requests fired" built on evicted evidence is exactly the kind of false green Reticle exists to prevent.
+
+## Filters
+
+| Argument          | What it does                                                           |
+| ----------------- | ---------------------------------------------------------------------- |
+| `urlContains`     | Substring the URL must contain                                         |
+| `method`          | `GET` · `POST` · `PUT` · `DELETE` · `PATCH`                            |
+| `status`          | Exact status code, e.g. `500`                                          |
+| `ok`              | `false` keeps only failures. The fastest way to "did anything break?"  |
+| `limit`           | Most recent N. Older matches are dropped and counted                   |
+| `actionId`        | Only requests attributed to one action: "what did that click request?" |
+| `since` / `until` | Cursors from a prior act, to scope to a window between two actions     |
+
+## Catching a double submit
+
+The bug where one click fires two POSTs is invisible on screen and obvious here:
+
+```json
+{ "urlContains": "/api/orders", "method": "POST" }
+```
+
+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 }` 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
+  `reticle_act_and_wait` instead.
+</Card>

package/docs/tools/observe.mdx

@@ -0,0 +1,145 @@
+---
+title: reticle_observe
+description: The full timeline of everything the app did in a window. DOM, network, routing, console, animations and signals, with a summary.
+icon: timeline
+---
+
+`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
+
+```json
+{ "window_ms": 4000, "max_events": 4 }
+```
+
+Real response:
+
+```json
+{
+  "window_ms": 4000,
+  "events": [
+    {
+      "t": 69964,
+      "type": "page.health",
+      "seq": 544,
+      "data": {
+        "hidden": false,
+        "focused": true,
+        "runtime": "web",
+        "engine": "blink",
+        "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": 2,
+    "network": 0,
+    "domAdded": 0,
+    "domRemoved": 0,
+    "domChanged": 0,
+    "routeChanges": 0,
+    "consoleErrors": 0,
+    "animations": 0,
+    "signals": 0
+  },
+  "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. The `headers` block on that `net.detail` event is trimmed out for length.
+
+## Read the summary first
+
+The `summary` block is the cheap answer. `consoleErrors: 0` and `network: 0` tells you most of what you need without reading a single event. Pull the timeline only when the summary says something interesting happened.
+
+## Arguments
+
+| Argument          | What it does                                                       |
+| ----------------- | ------------------------------------------------------------------ |
+| `window_ms`       | How far back to look                                               |
+| `since` / `until` | Cursors from a prior act. The precise way to scope                 |
+| `actionId`        | Only events attributed to one action: "what did that click cause?" |
+| `filters`         | Event-type allowlist. The cheapest way to shrink a big timeline    |
+| `max_events`      | Cap the timeline to the most recent N                              |
+
+## Scope by cursor, not by clock
+
+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": 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.
+
+<CardGroup cols={2}>
+  <Card title="Good use" icon="circle-check">
+    "Something broke after that click, show me everything that happened."
+  </Card>
+  <Card title="Wasteful use" icon="circle-xmark">
+    "Did a POST fire?" [`reticle_network`](/tools/network) answers that far more cheaply.
+  </Card>
+</CardGroup>
+
+<Note>`observe` reads. It does not produce a verdict. It is for diagnosis, not proof.</Note>

package/docs/tools/overview.mdx

@@ -0,0 +1,163 @@
+---
+title: Reticle tools overview
+sidebarTitle: Tools overview
+description: The tools your agent sees every turn, the many more it can reach on demand, and why the advertised surface is deliberately small.
+icon: wrench
+---
+
+Reticle's table holds 45 tools. Your agent is shown **nine**: `reticle_act`, `reticle_act_and_wait`, `reticle_assert`, `reticle_look`, `reticle_navigate`, `reticle_observe`, `reticle_session`, `reticle_tools` and `reticle_verify`. Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.
+
+Most of the rest were not removed. They were **merged**. `reticle_snapshot` is `reticle_look { action: "page" }`; `reticle_console` is `reticle_observe { action: "console" }`. One tool, one action argument, same work. Calling a retired name returns the call that replaced it, and `reticle_tools` prints the whole mapping.
+
+That is not a limitation, it's the design. MCP re-sends every advertised tool definition to the model on **every single turn**, so the tool list is not a menu you pay for once. It's rent.
+
+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 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
+  surface is **9 tools at 17,663 bytes**, against **30 tools at 126,954 bytes** when
+  `RETICLE_ADVERTISE_ALL_TOOLS` is set, 7.2x more and charged on every message.
+  [`bench/harness/schema-tax.mjs`](/token-efficiency) converts those bytes to tokens by putting
+  every server through one tokenizer in a single pass. Re-measure before quoting any of it; the
+  surface grows, and the figures this note replaced were a year out of date and described a surface
+  that no longer existed.
+</Note>
+
+## The default 19
+
+Grouped by the job they do in the verify loop.
+
+<CardGroup cols={2}>
+  <Card title="Look" icon="magnifying-glass">
+    `reticle_snapshot` · `reticle_query` · `reticle_inspect` · `reticle_sessions` ·
+    `reticle_capabilities`
+  </Card>
+  <Card title="Act" icon="hand-pointer">
+    `reticle_act` · `reticle_act_and_wait` · `reticle_act_sequence` · `reticle_navigate`
+  </Card>
+  <Card title="Observe" icon="satellite-dish">
+    `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_state` · `reticle_wait_for`
+  </Card>
+  <Card title="Prove & discover" icon="circle-check">
+    `reticle_assert` · `reticle_tools` · `reticle_run`
+  </Card>
+  <Card title="Session & feedback" icon="comment">
+    `reticle_session` · `reticle_feedback`
+  </Card>
+</CardGroup>
+
+<Warning>
+  Only **`reticle_act_and_wait`** and **`reticle_assert`** produce a verdict. Everything else moves
+  or reads the app and proves nothing. A drive that ends without one of those two has no result,
+  however many tools it used and however confident the summary sounds.
+</Warning>
+
+## Why these and not others
+
+Each one earned its slot, and a couple are there because of measured mistakes.
+
+`reticle_inspect` maps a DOM node to `src/components/Sidebar.tsx:41`. Finding a bug is half the job. Knowing which file to open is the half that makes an agent useful.
+
+It used to be reachable only through `reticle_run`, which meant an agent had to already know it existed to use it.
+
+`reticle_act_sequence` batches a multi-step interaction into one round trip. It was also reachable only through `reticle_run`, and the consequence is a login form driven one call at a time, over and over.
+
+Those repeats were not retries. The calls succeeded and got repeated, because the batching tool was invisible. A tool an agent must already know about is a tool that never gets called.
+
+Direct `reticle_network` and `reticle_console` stay advertised even though `reticle_observe` can filter for both, because two obvious tools beat one clever tool with a filter grammar.
+
+<Tip>
+  Trimming further has a floor. An eight-tool cut measurably dropped real-agent accuracy, because
+  the model loses scaffolding and wanders on harder flows. That reading is old enough to be dated
+  evidence rather than proof, and a fresh A/B against a leaner surface is still unrun. Small is
+  good; empty is not.
+</Tip>
+
+## Reaching the other 29
+
+```json
+{ "tool": "reticle_verify", "args": { "action": "flows" } }
+```
+
+`reticle_run` takes a tool name and its arguments. `reticle_tools` lists what's available and returns the full argument grammar for any of them, so your agent can discover a tool mid-task without you having pre-loaded its schema.
+
+Notable residents of the cold tail: flow recording and replay, visual diffing and screenshots, network mocking, viewport pinning, coverage, autonomous crawling, and the human-in-the-loop session controls.
+
+## Every response carries its cost
+
+Reticle tells you what each answer cost, because a verification tool that quietly eats your context window is not saving you anything:
+
+```json
+"cost": { "bytes": 944, "tokens": 236 }
+```
+
+That is a real `reticle_query` response: seven buttons found, with source pointers, for 236 tokens.
+
+## Every response tells you when not to trust it
+
+This is the part we're proudest of and the part that makes demos slightly less shiny.
+
+When the browser tab is backgrounded, every response says so:
+
+```json
+"warning": "tab throttled; timer/rAF/pointer gestures may silently no-op; refocus before driving"
+```
+
+When the event buffer has evicted old events, a negative result might be a false negative, and it says that too:
+
+```json
+"buffer": {
+  "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."
+}
+```
+
+A tool that says "no requests found" when it actually means "I lost the ones you asked about" is worse than useless. It is confidently wrong. Reticle would rather tell you its memory is imperfect.
+
+## Reference
+
+### Look
+
+| Tool | Answers |
+| --- | --- |
+| [`reticle_snapshot`](/tools/snapshot) | What is on this page? Three modes, from full tree to a 25-token route check |
+| [`reticle_query`](/tools/query) | Where is the thing I mean? |
+| [`reticle_inspect`](/tools/inspect) | Everything about one element, down to source and design tokens |
+| [`reticle_sessions`](/tools/sessions) | Which tabs are connected, and can they actually be driven? |
+| [`reticle_capabilities`](/tools/tools-and-run) | What does this app say is testable? Testids, signals, stores, flows |
+
+### Act
+
+| Tool | Answers |
+| --- | --- |
+| [`reticle_act`](/tools/act) | Do this. Proves nothing, and says so |
+| [`reticle_act_and_wait`](/tools/act-and-wait) | Do this, and prove the consequence. **Produces a verdict** |
+| [`reticle_act_sequence`](/tools/act-sequence) | Do these three things in one round trip |
+| [`reticle_navigate`](/tools/navigate) | Go here. Dispatched, not confirmed |
+
+### Observe
+
+| Tool                                  | Answers                                         |
+| ------------------------------------- | ----------------------------------------------- |
+| [`reticle_observe`](/tools/observe)   | Everything that happened in a window            |
+| [`reticle_network`](/tools/network)   | Which requests fired, with bodies and timings   |
+| [`reticle_console`](/tools/console)   | What was logged, and whether the read was real  |
+| [`reticle_state`](/tools/state)       | What the app believes, not what it drew         |
+| [`reticle_wait_for`](/tools/wait-for) | Block until something you did not cause happens |
+
+### Prove and discover
+
+| Tool | Answers |
+| --- | --- |
+| [`reticle_assert`](/tools/assert) | Did the named consequence hold? **Produces a verdict** |
+| [`reticle_tools`](/tools/tools-and-run) | What else is available, and what are its arguments? |
+| [`reticle_run`](/tools/tools-and-run) | Invoke any of the other 29 |
+| [`reticle_session`](/tools/session-and-feedback) | Hand control back to the human |
+| [`reticle_feedback`](/tools/session-and-feedback) | Tell the maintainers Reticle got something wrong |
+
+<Card title="The complete reference" icon="book" href="/usage">
+  Every tool, every argument, including the 29 in the cold tail.
+</Card>