@reticlehq/server 2.14.0 → 3.2.0

package/docs/tools-network.mdx

@@ -1,119 +0,0 @@
----
-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
----
-
-`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

@@ -1,145 +0,0 @@
----
-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

@@ -1,160 +0,0 @@
----
-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 ships 46 tools plus two meta-tools. On the default profile your agent is shown **19** of them: 17 that do the work, plus `reticle_tools` and `reticle_run`, which reach the other 29 on demand. Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.
-
-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.
-
-The other 29 are one call away, never unreachable. `reticle_tools` lists them and `reticle_run` invokes them.
-
-<Note>
-  Measured off the real wire on 2026-08-16, by reading `tools/list` from a fresh daemon: the default
-  surface is **19 tools at 22,023 bytes**, against **48 tools at 134,992 bytes** when
-  `RETICLE_ADVERTISE_ALL_TOOLS` is set. That is 6.1x more, 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.
-</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 sit in the cold tail, which meant an agent had to already know it existed to use it. So essentially nobody did.
-
-`reticle_act_sequence` batches a multi-step interaction into one round trip. It was also in the cold tail, and the consequence showed up in the data: agents drove login forms 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>

package/docs/tools-query.mdx

@@ -1,126 +0,0 @@
----
-title: reticle_query
-description: Find elements by Testing-Library semantics. Role, text, label, placeholder, testid, alt, or React component, including inside open shadow roots.
-icon: magnifying-glass
----
-
-`reticle_query` answers "where is the thing I mean?" without dumping the whole page into your context window. It queries the way a testing library does. By role, label, text, testid. So your agent binds to meaning rather than to DOM structure that a refactor will move.
-
-## Example
-
-```json
-{ "by": "role", "value": "button", "limit": 6 }
-```
-
-Real response from a running app, with four of the six elements trimmed out for length:
-
-```json
-{
-  "count": 7,
-  "elements": [
-    {
-      "ref": "e118",
-      "role": "button",
-      "name": "Overview",
-      "visible": true,
-      "source": "src/components/Sidebar.tsx:41",
-      "states": ["present", "visible", "enabled"]
-    },
-    {
-      "ref": "e120",
-      "role": "button",
-      "name": "Compose",
-      "visible": true,
-      "source": "src/components/Sidebar.tsx:41",
-      "states": ["present", "visible", "enabled"]
-    }
-  ],
-  "total": 7,
-  "truncated": true,
-  "cost": { "bytes": 944, "tokens": 236 }
-}
-```
-
-Seven buttons, each with a `ref` to act on and a source file to open, for 236 tokens.
-
-## 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           |
-
-Every argument also has a predicate spelling, so `{ "role": "button" }` works as shorthand for `{ "by": "role", "value": "button" }`.
-
-## Use `count_only` when you only need a number
-
-"Are there still three rows?" does not require three row descriptors:
-
-```json
-{ "by": "testid", "value": "login-submit", "count_only": true }
-```
-
-```json
-{ "count": 1, "cost": { "bytes": 11, "tokens": 3 } }
-```
-
-Three tokens. Note that `total` is not emitted on this path, because `count` already is the total.
-
-## A zero-match result tells you what _is_ there
-
-```json
-{ "by": "testid", "value": "compose-prompt" }
-```
-
-```json
-{
-  "count": 0,
-  "elements": [],
-  "hint": {
-    "route": "/hostile",
-    "knownEmptyState": true,
-    "presentTestids": [
-      "brand",
-      "nav-overview",
-      "nav-deployments",
-      "nav-compose",
-      "nav-diagnostics",
-      "nav-hostile",
-      "session-pill",
-      "cmdk-open",
-      "sign-out",
-      "hostile-view",
-      "hostile-ticker",
-      "hostile-feed-count"
-    ],
-    "presentRegions": [
-      { "role": "list", "childCount": 0, "name": "hostile-feed", "sample": [] },
-      { "role": "banner", "childCount": 0, "sample": [] }
-    ]
-  },
-  "cost": { "bytes": 402, "tokens": 101 }
-}
-```
-
-The testid existed, on another route. `hint.route` says where you actually are, `presentTestids` says what is on this page instead, and `presentRegions` distinguishes an empty list from a missing one. All of it without paying for a snapshot.
-
-## Reading the response
-
-`ref` is the handle for every other tool: `act`, `inspect`, `state`. It stays valid until the element leaves the DOM, so you do not need to re-snapshot between actions on the same element.
-
-`source` appears when `@reticlehq/react` is installed. Note that both sidebar buttons above report `Sidebar.tsx:41`, and so do the three trimmed out of the example. That is the line where the component renders all five in a loop, which is exactly the line you want to edit.
-
-`truncated: true` with `total: 7` means `limit` cut the list, not that Reticle ran out of room. Neither field is emitted when nothing was cut, so their absence is itself the signal that you are looking at every match.
-
-`states` distinguishes `present` from `visible` from `enabled`. An element can be all three and still be covered by a modal. [`reticle_inspect`](/tools-inspect) reports `occluded` for that.
-
-<Tip>
-  Query by `testid` when you can. Role and text queries survive refactors well; testids survive
-  redesigns, translations, and the day someone rewrites your button labels for the marketing team.
-</Tip>

package/docs/tools-sessions.mdx

@@ -1,94 +0,0 @@
----
-title: reticle_sessions
-description: List every connected browser tab, with the health fields that tell you whether it can actually be driven.
-icon: list-check
----
-
-`reticle_sessions` lists every browser tab currently connected to the Reticle daemon, with the health fields that decide whether it can actually be driven. Reach for it first when a tool says no session is connected, and after every [`reticle_navigate`](/tools-navigate) that came back `confirmed: false`.
-
-```json
-{}
-```
-
-Real response from a healthy session:
-
-```json
-{
-  "sessions": [
-    {
-      "sessionId": "sba6117a6-24ec-494d-8c2c-e2958cff2e7f",
-      "url": "http://localhost:4310/",
-      "title": "Reticle · Mission Control",
-      "adapters": ["react"],
-      "hasCapabilities": true,
-      "hidden": false,
-      "lastSeenMs": 155,
-      "throttled": false,
-      "focused": true,
-      "attachment": { "connectedSinceMs": 18654, "outages": 0 },
-      "realInputAvailable": false,
-      "leased": false
-    }
-  ]
-}
-```
-
-A backgrounded tab adds a `recommendation` telling you what to do about it, and `attachment` grows a `lastOutage` once the connection has dropped at least once:
-
-```json
-{
-  "hidden": false,
-  "throttled": true,
-  "attachment": {
-    "connectedSinceMs": 1217047,
-    "outages": 3,
-    "lastOutage": { "startedMs": 1786818483776, "durationMs": 967 }
-  },
-  "recommendation": "tab hidden/throttled and may be un-focusable from here; refocus it, or run `reticle drive <url>` for a guaranteed scriptable context"
-}
-```
-
-## When nothing is connected
-
-An empty list is not silent. It comes back with a `why` that separates the two causes, and refuses to guess between them:
-
-```json
-{
-  "sessions": [],
-  "why": "no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is listening on the ports Reticle scans, so the dev server may not be running. That scan is narrow though: a server on any other port is invisible to it, so if the app IS running, ask for its URL rather than assuming it is down, and open it with `reticle open <url>`. (2) There is no `.reticle.json` in the directory this daemon is running in. That is the file `reticle init` writes, so the app may carry no Reticle SDK."
-}
-```
-
-That string is trimmed. The full text also lists the exact ports it scanned and warns that in a monorepo the daemon often runs at the root while the app lives in a subdirectory, so you should check the app's own directory before re-running `init`.
-
-## The fields that decide whether driving will work
-
-| Field | Why it matters |
-| --- | --- |
-| `throttled` | The browser is deprioritising a background tab. Synthetic timers and pointer gestures may silently no-op |
-| `hidden` / `focused` | Why it's throttled, and what to do about it |
-| `hasCapabilities` | Whether the app registered testids, signals and stores. `false` means [`reticle_state`](/tools-state) has nothing to read |
-| `adapters` | `["react"]` means you get component names and source pointers |
-| `realInputAvailable` | `true` when native CDP input is available, under `reticle drive` |
-| `outages` | How often the connection has dropped. Non-zero is worth investigating |
-
-<Warning>
-  `throttled: true` is the most common cause of "the click did nothing". Focus the tab, or drive a
-  dedicated context. It is not your app being broken. It is the browser saving battery on a tab
-  nobody is looking at.
-</Warning>
-
-## Confirm after navigating
-
-[`reticle_navigate`](/tools-navigate) can only report that a navigation was dispatched. `sessions` is how you confirm one arrived: a session at the new URL means the page loaded **and** is instrumented. No session means one of those two is false, and you find out now rather than after three confusing failures.
-
-## Scoping
-
-You rarely need to pass `sessionId` to other tools. Reticle scopes to your project, prefers the active tab, and refuses rather than guesses when the choice is ambiguous. A refusal you can act on beats a silent pick of the wrong tab.
-
-Pass it explicitly when you genuinely mean one specific tab, such as when testing two apps at once.
-
-<Note>
-Sessions accumulate. A stale entry pointing at a dev server you have since restarted will sit there
-looking plausible. `reticle_session { action: "end" }` clears one out.
-</Note>