@reticlehq/server 3.2.0 → 3.4.0

package/docs/predicates.mdx

@@ -7,7 +7,7 @@ icon: filter
 
 A predicate declares what should be true, as `{ kind, ...fields }`. Reticle has twelve kinds: `signal`, `state`, `net`, `route`, `element`, `text`, `console`, `animation`, `settled`, and the combinators `allOf`, `anyOf` and `not`. Which one you pick decides whether a green means anything.
 
-It is the argument to `until` on [`reticle_act_and_wait`](/tools/act-and-wait), and to `predicate` on [`reticle_assert`](/tools/assert) and [`reticle_wait_for`](/tools/wait-for).
+It is the argument to `until` on [`reticle_act_and_wait`](/tools/act-and-wait), and to `predicate` on [`reticle_assert`](/tools/assert) and [`reticle_assert { action: "wait" }`](/tools/wait-for).
 
 Every predicate is `{ kind, ...fields }`.
 
@@ -35,6 +35,7 @@ Take the advice. `element` and `text` are convenient and weak; `signal`, `state`
 | `element` / `text` | weak      | Something rendered. A mock renders too                 |
 | `animation`        | weak      | An animation ran or finished                           |
 | `settled`          | timing    | The page went quiet. A precondition, not a proof       |
+| `compare`          | its sides | Two readings agree: the stronger side's grade          |
 
 ## The leaves
 
@@ -48,7 +49,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`, `pressed`, `focused`, `inViewport`, `present`.
+
+`value` is the one worth knowing about. `{ "role": "textbox", "name": "Amount" }` collapses to "a textbox called Amount exists", which passes against an empty field; adding `value` is what makes it an assertion about what the user will actually send. `by` selects the locator strategy explicitly, `component` and `source` match React component identity and source location, and `self` restricts a scoped match to the scope element itself rather than its descendants.
+
+`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_look { action: "find" }` 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 +73,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
@@ -88,7 +119,7 @@ Two fields read the RESPONSE BODY, so a request that succeeded with the wrong nu
 { "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.
+`bodyMatches` is a field match, keyed like `signal.dataMatches` and taking the same operators (`*`, `$gte`, `$contains`). A key can be a dotted path into a wrapped answer: `{ "data.status": "completed" }`, `{ "items.0.id": "a1" }`, `{ "items.length": 3 }`. A nested object written out as a value is compared whole, so use the path to match one field inside it. Reach for it whenever the value is an enum, because that is the case a substring cannot decide: `bodyContains: "completed"` passes on a body carrying `"completedAt": null`, where the needle matched the KEY and the job was still queued. `completed`/`completedAt`, `success`/`successRate`, `sent`/`unsent` all have that shape.
 
 Both require body capture, `reticle({ captureNetworkBodies: true })`, and say so when the body was never recorded rather than reporting an ordinary mismatch.
 
@@ -131,7 +162,7 @@ A passing route verdict quotes the transition itself:
 { "kind": "signal", "name": "webhook:received", "dataMatches": { "provider": "stripe", "id": "*" } }
 ```
 
-The app emitted a named signal via `reticle.signal()`. `dataMatches` is shallow JSON matching, and `*` means "present, any value".
+The app emitted a named signal via `reticle.signal()`. `dataMatches` matches field by field, a key can be a dotted path (`"order.total"`), and `*` means "present, any value".
 
 `count` works here exactly as it does on `net`:
 
@@ -174,6 +205,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
@@ -207,6 +304,77 @@ 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.
 
+### compare
+
+```json
+{
+  "kind": "compare",
+  "left": { "from": "text", "scope": "#refunded" },
+  "right": { "from": "net", "urlContains": "/api/refund", "path": "refunded" },
+  "as": "number"
+}
+```
+
+Two observed values must agree, and you do not have to know either one. Every other predicate checks one reading against a value you write down. That cannot catch a page that echoes the user's input instead of the server's answer unless you already know the right answer: a refund of `1187.01` that the server read as paise answered `{"refunded":11.87}`, the page showed `₹1,187.01`, and every other channel was green.
+
+Each side reads one value from a source:
+
+| `from` | Fields | Reads |
+| --- | --- | --- |
+| `net` | `urlContains`, `path`, `method?`, `body?` | A field of the LAST matching call's body. `body` is `response` (default) or `request` |
+| `signal` | `name`, `path` | A field of the last `name` signal's payload |
+| `state` | `path`, `store?` | A store value, as `state` reads it |
+| `text` | `scope` | The whole text of the element `scope` names (a CSS selector) |
+
+A `path` is a field name or a dotted path into nested data (`data.total`, `items.0.price`), and it must end on a single value, not an object.
+
+`as` is `value` (the default) or `number`:
+
+- `value` is strict equality. The text `"11.87"` and the number `11.87` are different, and the failure says so and suggests `as: "number"`.
+- `number` reads one number from each side. A JSON number is used as it is; a string contributes its only number, so `"Refunded ₹1,187.01"` reads as `1187.01`. A string holding two numbers is unknown rather than guessed at, so scope the text to the one value. Add `tolerance` for a band.
+
+A side nobody could read is never a pass. A call that never happened, a missing element or a missing field fails. A body that was not recorded, was truncated before the field, or had the field redacted is unknown. Comparing a source with itself is refused before it runs, because it would agree on every page.
+
+Two live sides (`text`, `state`) are also read before the action. If they already agreed, the result is `already_true`, because their agreement says nothing about what the action did. Put a `net` or `signal` side in the comparison to tie it to the action.
+
+Comparing request with response on the same call is legitimate, and it is the direct check for a unit mismatch:
+
+```json
+{
+  "kind": "compare",
+  "left": { "from": "net", "urlContains": "/api/refund", "body": "request", "path": "amount" },
+  "right": { "from": "net", "urlContains": "/api/refund", "path": "refunded" },
+  "as": "number"
+}
+```
+
+## 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
@@ -226,7 +394,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.
@@ -265,9 +434,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/quickstart.mdx

@@ -61,7 +61,7 @@ The `reticle_*` tools are already there. In your project directory:
 npx @reticlehq/server init
 ```
 
-Like `npm init` or `git init`, this is the per-project step: it installs the SDK, wires it into your app's entry point, restarts your dev server and then opens your app to prove a session connected. It is idempotent. Run it twice and the second run reports what was already done rather than doing it again.
+Like `npm init` or `git init`, this is the per-project step: it installs the SDK, wires it into your app's entry point, starts your dev server and then opens your app to prove a session connected. It is idempotent. Run it twice and the second run reports what was already done rather than doing it again.
 
 Step 1 is once per machine. This step is once per project.
 
@@ -236,7 +236,7 @@ That third state is the one that matters. Most tools have two outcomes and quiet
   <Accordion title="How long does it actually take to install Reticle?">
     Two commands, and no restart if you run them in order. The installer registers the MCP server
     with every agent on the machine, so opening your agent afterwards is all that is needed. Then
-    `npx @reticlehq/server init` wires the project and restarts your dev server for you. The MCP
+    `npx @reticlehq/server init` wires the project, starts your dev server and opens the app for you. The MCP
     registration is global, so every later project starts with the tools already there.
   </Accordion>
 

package/docs/recipes.mdx

@@ -5,7 +5,7 @@ description: Worked examples for the situations you are actually in, with the re
 icon: book-open
 ---
 
-Each recipe is a situation, the call that verifies it, and what came back. Every response on this page was captured from a running app on 2026-08-16. Refs like `e605` are session-specific: take your own from [`reticle_query`](/tools/query) before copying a call.
+Each recipe is a situation, the call that verifies it, and what came back. Every response on this page was captured from a running app on 2026-08-16. Refs like `e605` are session-specific: take your own from [`reticle_look { action: "find" }`](/tools/query) before copying a call.
 
 ## "Did the login actually work?"
 
@@ -135,7 +135,7 @@ The right predicate was sitting in the response the whole time:
 
 ## "Nothing matched, and I do not know why"
 
-An empty `reticle_query` result tells you what _is_ there:
+An empty `reticle_look { action: "find" }` result tells you what _is_ there:
 
 ```json
 {

package/docs/state-management.mdx

@@ -179,7 +179,7 @@ worker.onmessage = (e) => push(e.data);
 { "store": "app", "path": "cart.items.0.qty" }
 ```
 
-`reticle_state` walks a dot-path with numeric array indices. `depth` collapses anything deeper to a size marker, which is the difference between a cheap look and a very expensive one on a large store.
+`reticle_look { action: "state" }` walks a dot-path with numeric array indices. `depth` collapses anything deeper to a size marker, which is the difference between a cheap look and a very expensive one on a large store.
 
 You can also assert on it directly, which is stronger than reading it afterwards:
 
@@ -190,7 +190,7 @@ You can also assert on it directly, which is stronger than reading it afterwards
 That catches a UI-versus-store desync, a deploy that only looks shipped, deterministically and with no model involved.
 
 <CardGroup cols={2}>
-  <Card title="reticle_state" icon="database" href="/tools/state">
+  <Card title='reticle_look { action: "state" }' icon="database" href="/tools/state">
     Arguments, depth control, and reading a component's hook state.
   </Card>
   <Card title="Instrument your app" icon="wrench" href="/instrumentation">

package/docs/system-map.md

@@ -66,7 +66,7 @@ These three were each wrong by the time somebody checked: the table read 68 / 48
 
 | Token | Produced by | Consumed by | Invalidated by |
 | --- | --- | --- | --- |
-| `sessionId` | `reticle_sessions`, HELLO | ~every tool | tab close; **survives reload** via `sessionStorage` |
+| `sessionId` | `reticle_session { action: "list" }`, HELLO | ~every tool | tab close; **survives reload** via `sessionStorage` |
 | `ref` (`e115`) | `snapshot`, `query`, `scroll_to` | `inspect`, `act`, `act_and_wait`, `state` | any re-render; refuses cleanly rather than clicking the new occupant |
 | `actionId` (`a2`) | `act`, `act_and_wait` | `observe`, `network`, `console` filters | window expiry |
 | `since` cursor | every read | every read | ring-buffer eviction |

package/docs/telemetry.md

@@ -122,7 +122,7 @@ Reticle verifies apps for AI agents, and for a long time it had no way to hear w
 
 | Who | How | What it carries |
 | --- | --- | --- |
-| Your agent | Calls the `reticle_feedback` MCP tool (after a failure, **or to ask for a feature**) | What it wrote: an analysis, or a request with the goal behind it, what would improve, and how it works around the gap today. Plus the model it is running, which it tells us because MCP cannot |
+| Your agent | Calls the `reticle_session { action: "feedback" }` MCP tool (after a failure, **or to ask for a feature**) | What it wrote: an analysis, or a request with the goal behind it, what would improve, and how it works around the gap today. Plus the model it is running, which it tells us because MCP cannot |
 | You | Run `npx @reticlehq/server feedback [--rating 1-5] [--bug] "your words"` | Your words and your rating |
 | Your agent, before Reticle works | Runs `reticle feedback --agent --kind <bug\|gap\|ambiguity\|feature_request\|improvement> "what happened"` | The same words, filed from the shell. This exists for the phase where there is no daemon and no MCP tools (a failed `init`, half-finished wiring), which is the failure we are otherwise never told about |
 

package/docs/token-efficiency.md

@@ -4,7 +4,7 @@ description: Why asking narrow questions costs a fraction of feeding the whole a
 icon: coins
 ---
 
-A full Reticle verify loop costs about **100 tokens**, against roughly **7,300** for a full-tree accessibility snapshot on the same page: about 73x leaner, because Reticle asks a narrow question instead of returning the page. If you re-look after an action with `reticle_snapshot({ diff: true })`, the re-read costs about 99% less again.
+A full Reticle verify loop costs about **100 tokens**, against roughly **7,300** for a full-tree accessibility snapshot on the same page: about 73x leaner, because Reticle asks a narrow question instead of returning the page. If you re-look after an action with `reticle_look({ action: "page", diff: true })`, the re-read costs about 99% less again.
 
 Agent browser tools that feed the **whole accessibility tree** to the model every step get expensive fast. Playwright MCP's own ecosystem notes its snapshots _"can exceed 50,000 tokens on complex pages,"_ with a _typical task ~114,000 tokens through MCP._ Reticle is built to ask **narrow questions** instead, so the per-interaction cost stays tiny.
 
@@ -28,7 +28,7 @@ Measured against the bench dashboard (`apps/bench-app`) **with a 1,000-item list
 
 ## Diffed snapshots: pay once, then only for changes
 
-After the first snapshot, pass `reticle_snapshot({ diff: true })` to get back **only what changed** since your last look of the same scope/mode (`mode:delta` with added/removed lines, or `mode:unchanged`). A route change auto-resets to a full snapshot, so you never read a misleading cross-page diff.
+After the first snapshot, pass `reticle_look({ action: "page", diff: true })` to get back **only what changed** since your last look of the same scope/mode (`mode:delta` with added/removed lines, or `mode:unchanged`). A route change auto-resets to a full snapshot, so you never read a misleading cross-page diff.
 
 Measured on a representative 150-row dashboard (the shipped regression benchmark `server/src/surface/tools/snapshot-cost.test.ts`, char/4 proxy):
 
@@ -40,7 +40,7 @@ Measured on a representative 150-row dashboard (the shipped regression benchmark
 
 **~99% fewer tokens** to re-look after an action, and because a `delta` carries no stale full tree, it also removes the 60K to 80K-token stale-context buildup that makes long-running agents start hallucinating selectors that no longer exist.
 
-Every `reticle_snapshot`/`reticle_query` result also carries `cost:{ bytes, tokens }` (estimated) so you can **re-scope before reading** a large body (`mode:interactive`/`status`, a tighter `scope`, or a narrower `query`) instead of paying for it first.
+Every `reticle_look { action: "page" }`/`reticle_look { action: "find" }` result also carries `cost:{ bytes, tokens }` (estimated) so you can **re-scope before reading** a large body (`mode:interactive`/`status`, a tighter `scope`, or a narrower `query`) instead of paying for it first.
 
 ## The other tax: tool schemas, paid on every request
 

package/docs/tools/act-and-wait.mdx

@@ -162,6 +162,7 @@ A verification tool that cannot describe the quality of its own evidence is aski
 | `predicate` | Alias for `until`, the name `assert` and `wait_for` use |
 | `timeout_ms` | Maximum wait, defaulting to 4000. `0` evaluates the predicate once, no wait |
 | `refuseWhenThrottled` | Throw rather than act on a throttled tab |
+| `durable` | After a `yes`, reload the page and require the element, text and state parts of `until` to hold again. A consequence that is gone after the reload turns the verdict into `no`: the UI advanced, the change did not persist |
 
 Omitting `until` waits for network and DOM idle, which is the deterministic replacement for a fixed sleep. To assert a consequence **and** settle, combine them:
 

package/docs/tools/act-sequence.mdx

@@ -5,7 +5,7 @@ icon: layer-group
 ---
 
 <Warning>
-  **reticle_act_sequence is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_act_sequence is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_act { steps: [...] }`** instead: the same call, routed on the steps array. 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.

package/docs/tools/console.mdx

@@ -5,7 +5,7 @@ icon: terminal
 ---
 
 <Warning>
-  **reticle_console is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_console is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_observe { action: "console" }`** 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.

package/docs/tools/inspect.mdx

@@ -5,7 +5,7 @@ icon: crosshairs
 ---
 
 <Warning>
-  **reticle_inspect is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_inspect is not advertised.** The default surface is the merged ten, 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.

package/docs/tools/network.mdx

@@ -5,7 +5,7 @@ icon: satellite-dish
 ---
 
 <Warning>
-  **reticle_network is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_network is not advertised.** The default surface is the merged ten, 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.

package/docs/tools/query.mdx

@@ -5,7 +5,7 @@ icon: magnifying-glass
 ---
 
 <Warning>
-  **reticle_query is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_query is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_look { action: "find" }`** 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.
@@ -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/tools/sessions.mdx

@@ -5,7 +5,7 @@ icon: list-check
 ---
 
 <Warning>
-  **reticle_sessions is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_sessions is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_session { action: "list" }`** 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.

package/docs/tools/snapshot.mdx

@@ -5,7 +5,7 @@ icon: camera
 ---
 
 <Warning>
-  **reticle_snapshot is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_snapshot is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_look { action: "page" }`** 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.

package/docs/tools/state.mdx

@@ -5,7 +5,7 @@ icon: database
 ---
 
 <Warning>
-  **reticle_state is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_state is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_look { action: "state" }`** 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.

package/docs/tools/wait-for.mdx

@@ -5,7 +5,7 @@ icon: hourglass
 ---
 
 <Warning>
-  **reticle_wait_for is not advertised.** The default surface is the merged nine, so an agent does not see
+  **reticle_wait_for is not advertised.** The default surface is the merged ten, so an agent does not see
   this name. Call **`reticle_assert { action: "wait" }`** 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.

package/docs/usage.md

@@ -4,7 +4,7 @@ description: 'The full reference and cookbook: every tool, flag, and workflow, w
 icon: book
 ---
 
-Every Reticle drive is the same four steps: **look** (`reticle_look { action: "page" }` / `reticle_look { action: "find" }`), **act** (`reticle_act` / `reticle_act { steps: [...] }`), **observe** (`reticle_observe` / `reticle_observe { action: "network" }` / `reticle_look { action: "state" }`), **assert** (`reticle_assert`). Only `reticle_act_and_wait` and `reticle_assert` produce a verdict, so a run that ends anywhere else proved nothing. This page is the full reference for every tool, predicate, action and flag in that loop.
+Every Reticle drive is the same four steps: **look** (`reticle_look { action: "page" }` / `reticle_look { action: "find" }`), **act** (`reticle_act` / `reticle_act { steps: [...] }`), **observe** (`reticle_observe` / `reticle_observe { action: "network" }` / `reticle_look { action: "state" }`), **assert** (`reticle_assert`). Verdicts come from `reticle_act_and_wait`, `reticle_assert`, and `reticle_act { steps }` when a step declares `expect`, so a run that ends anywhere else proved nothing. This page is the full reference for every tool, predicate, action and flag in that loop.
 
 If you haven't set up Reticle yet, start with [Getting Started](getting-started.md).
 
@@ -183,7 +183,7 @@ The timeline + summary of what happened.
 
 Act, then wait for a predicate: the whole act→observe→assert loop in one hop.
 
-- **args:** `ref`, `action`, `args?`, `until: <predicate>`, `timeout_ms?` (default 4000; 0 = evaluate once), `refuseWhenThrottled?`, `intent?`, `sessionId?`.
+- **args:** `ref`, `action`, `args?`, `until: <predicate>`, `timeout_ms?` (default 4000; 0 = evaluate once), `refuseWhenThrottled?`, `intent?`, `durable?` (after a yes, reload and require `until`'s element/text/state parts to hold again), `sessionId?`.
 - **returns:** `{ effect, verdict, trace, session, warning? }`. `effect` is the action result (`{ ok, ref, action }`), `verdict` is `{ pass, evidence?, failureReason? }`, `trace` is the reaction report of everything the app did after the action, and `session` is the tab-health block `{ lastSeenMs, throttled, focused }` (with a `warning` when throttled). A failing `verdict` still returns `effect` + `trace` so you can see what _did_ happen. The predicate is automatically floored at this act's cursor, so it only matches events the action actually caused.
 
 ### `reticle_assert { action: "wait" }`
@@ -200,7 +200,7 @@ Verify a predicate; optionally wait for it.
 - **args:** `predicate`, `timeout_ms?` (0 = evaluate once), `since?`, `intent?`, `sessionId?`.
 - Same `since` default as `reticle_assert { action: "wait" }`: scoped to your last act so a stale buffered event can't fake a pass; override with an explicit `since`.
 - **returns:** `{ verified, because, pass, evidence, contradictions?, coverage?, failureReason?, session, warning? }`. On failure includes a **near-miss** (e.g. "found the dialog but not visible", or "no button named 'Submit'; saw: Cancel"). The `session` block `{ lastSeenMs, throttled, focused }` reports tab health on every assert; when throttled a `warning` is attached so you never assert against a tab that is silently no-oping.
-- **`intent` declares what the change was FOR, inline.** Pass a sentence in your own words and it lands in `.reticle/intent.json`, the same git-checked ledger `reticle_intent` writes, before the verdict is drawn; a green verdict then marks it proved and names itself as the proof. Pass the **id** of an intent you already declared instead, to point several verdicts at one statement rather than restating it. `reticle_act_and_wait` takes the same argument. Omit it and nothing is written.
+- **`intent` declares what the change was FOR, inline.** Pass a sentence in your own words and it lands in `.reticle/intent/` (one directory per subject, a flow's name being its subject), the same git-checked ledger `reticle_intent` writes, before the verdict is drawn; a green verdict then marks it proved and names itself as the proof. Pass the **id** of an intent you already declared instead, to point several verdicts at one statement rather than restating it. `reticle_act_and_wait` takes the same argument. Omit it and nothing is written.
 - **Read `verified`, not `pass`.** `pass` says the predicate held; `verified` says whether that means anything. It is `"no"` when a channel contradicts the assertion (a failed write under a green screen, a batch whose body reports per-item failures, a request still in flight), and `"unknown"` when the outcome could not be known yet: a `202 Accepted` that has not reconciled, or a write whose response body was never recorded. `because` names the deciding evidence in one sentence.
 
 ### `reticle_reconcile`
@@ -350,7 +350,7 @@ A **predicate** declares what should be true. `reticle_assert` / `reticle_assert
 // An element exists / is in a state
 { "kind": "element", "query": { "role": "dialog", "name": "Confirm" }, "state": "visible" }
 // query supports: role, name, text, label, placeholder, testid, alt, scope
-// state: visible | hidden | enabled | disabled | checked | expanded | focused | present | inViewport
+// state: visible | hidden | enabled | disabled | checked | expanded | pressed | focused | present | inViewport
 // inViewport asserts the element is in the viewport NOW (not just in the DOM), so a scrollIntoView is gradeable
 // add "absent": true to assert it is NOT there (regression / removal)
 
@@ -396,7 +396,7 @@ A `state` assertion is graded as a **consequence** (a wrong element or stale ren
 - `timeout_ms` (on `assert`/`wait_for`): wait up to N ms for it to become true.
 - `since` (on `net`/`console` leaves): only consider events after this cursor (from `act`).
 
-`dataMatches` uses shallow JSON matching; `*` means "present, any value".
+`dataMatches` matches field by field; a key can be a dotted path (`"order.total"`, `"items.0.id"`), and `*` means "present, any value".
 
 ---
 
@@ -640,7 +640,7 @@ Capture everything that happens across a span. Useful for "run my whole checkout
 
 ```jsonc
 reticle_record {action:"start"}({ recordingName: "checkout" })
-// …agent performs the flow (reticle_act / reticle_act_sequence)…
+// …agent performs the flow (reticle_act, single or with steps)…
 reticle_record {action:"stop"}({ recordingName: "checkout" })
 // → {
 //     recordingName,
@@ -732,7 +732,7 @@ No, for basic look/act/observe. You'll get better results by adding `data-testid
 
 ### Does it work without React?
 
-The core (DOM/network/route/console/animation/snapshot/actions) is framework-agnostic and is gated against a vanilla-TS app. React, Next.js, Remix and Astro each have an app and a CI gate. SvelteKit is wired end-to-end. `reticle init` writes the client hook and the Vite plugin, and the plugin stamps `data-reticle-source` into `.svelte` components so verdicts carry `file:line`. But there is still no SvelteKit app in CI, so it is unverified rather than supported. Vue has a Pinia store adapter and nothing else: no detection, no `.vue` stamping, no gate. See [what Svelte support is and is not](getting-started.md#what-svelte-support-is-and-what-it-is-not).
+The core (DOM/network/route/console/animation/snapshot/actions) is framework-agnostic and is gated against a vanilla-TS app. What is proven for each framework, from driven to a verdict in CI to install-gated to wired but unverified, is listed once in [Frameworks](frameworks.mdx). See also [what Svelte support is and is not](getting-started.md#what-svelte-support-is-and-what-it-is-not).
 
 ### Can it judge whether my UI looks good?
 
@@ -858,6 +858,7 @@ It does **not** freeze `requestAnimationFrame`/microtasks (React's scheduler kee
   "dataMatches": { "count": { "$gte": 1 }, "sections": { "$contains": "hook" } },
 }
 // operators: $gte $lte $gt $lt $contains (array/substring) $length ; "*" = present
+// keys: a field name, or a dotted path into nested data ("order.total", "items.0.id")
 ```
 
 On a failed signal assert, the result includes a **near-miss**: the signals that _did_ fire with that name + their data. And `reticle_observe`'s summary now includes `domChanged` (in-place text/attribute re-renders, not just added/removed nodes).