@reticlehq/server 2.7.0 → 2.9.0

package/docs/recipes.mdx

@@ -0,0 +1,282 @@
+---
+title: 'Recipes: copy, paste, verify'
+sidebarTitle: Recipes
+description: Worked examples for the situations you are actually in, with the real response each one returned.
+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.
+
+## "Did the login actually work?"
+
+One call, three conditions. The signal fired, exactly one request went out, and nothing was logged.
+
+```json
+{
+  "ref": "e605",
+  "action": "click",
+  "until": {
+    "kind": "allOf",
+    "predicates": [
+      { "kind": "signal", "name": "auth:granted" },
+      { "kind": "net", "method": "POST", "urlContains": "/api/login", "count": 1 },
+      { "kind": "console", "level": "error", "absent": true }
+    ]
+  }
+}
+```
+
+```json
+{
+  "verified": "yes",
+  "because": "assertion held at signal grade over a clean capture with no channel disagreeing",
+  "verdict": {
+    "pass": true,
+    "evidence": [
+      { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } },
+      { "matched": 1 },
+      { "absent": true }
+    ]
+  },
+  "summary": {
+    "stateDiffs": [{ "path": "auth", "from": null, "to": "{…}" }],
+    "storageKeysChanged": ["reticle.bench.authToken", "reticle.bench.sessionId"]
+  },
+  "honesty": { "grade": "signal", "coverage": { "pct": 100, "partial": false } }
+}
+```
+
+Each child predicate reports its own evidence, in order. `count: 1` is the part that catches double-submit, and it costs nothing to ask for.
+
+## "Did navigating actually change the view?"
+
+```json
+{ "ref": "e618", "action": "click", "until": { "kind": "signal", "name": "nav:changed" } }
+```
+
+```json
+{
+  "verified": "yes",
+  "verdict": {
+    "pass": true,
+    "evidence": { "name": "nav:changed", "data": { "view": "deployments" } }
+  },
+  "summary": {
+    "statePathsChanged": ["app"],
+    "stateDiffs": [{ "path": "view", "from": "overview", "to": "deployments", "atMs": 49084 }],
+    "signals": ["nav:changed"]
+  },
+  "honesty": { "grade": "signal", "coverage": { "pct": 100, "partial": false } }
+}
+```
+
+The signal carries the destination in its payload, so one predicate proves both that navigation happened and that it went to the right place.
+
+## "Did the modal open?" and the lesson in getting it wrong
+
+Here is a real failure, kept because it teaches more than another pass.
+
+```json
+{
+  "ref": "e623",
+  "action": "click",
+  "args": { "confirmDangerous": true },
+  "until": {
+    "kind": "allOf",
+    "predicates": [
+      { "kind": "element", "query": { "role": "dialog" }, "state": "visible" },
+      { "kind": "console", "level": "error", "absent": true }
+    ]
+  }
+}
+```
+
+```json
+{
+  "verified": "no",
+  "verdict": {
+    "pass": false,
+    "evidence": [
+      {
+        "pass": false,
+        "expected": "an element matching {\"role\":\"dialog\"} in state 'visible'",
+        "observed": "no matching element on the page",
+        "assertion": "element.present",
+        "evidence": {
+          "presentTestids": ["deploy-table", "filter-search", "env-filter", "sign-out", "…"]
+        }
+      },
+      { "pass": true, "evidence": { "absent": true } }
+    ]
+  },
+  "summary": {
+    "stateDiffs": [{ "path": "newDeployOpen", "from": false, "to": true, "atMs": 60862 }],
+    "signals": ["modal:opened"]
+  },
+  "capsule": { "blastRadius": ["state app", "signal modal:opened"], "firstDivergence": null }
+}
+```
+
+Read the `summary`. The modal **did** open. `newDeployOpen` went `false` to `true` and the app fired `modal:opened`. `capsule.blastRadius` says the same thing as a list: the click moved the `app` store and fired `modal:opened`, and nothing else.
+
+The assertion was wrong, not the app. That modal is a `div` with no `role="dialog"`, so a role query could never match it. (Which is also an accessibility bug worth fixing, found for free.)
+
+The right predicate was sitting in the response the whole time:
+
+```json
+{ "until": { "kind": "signal", "name": "modal:opened" } }
+```
+
+<Tip>
+  When an assertion fails, read `summary.signals` and `summary.stateDiffs` before you assume the
+  feature is broken. They tell you what actually happened, and usually hand you the predicate you
+  should have written.
+</Tip>
+
+## "Nothing matched, and I do not know why"
+
+An empty `reticle_query` result tells you what _is_ there:
+
+```json
+{
+  "count": 0,
+  "elements": [],
+  "hint": {
+    "route": "/hostile",
+    "knownEmptyState": true,
+    "presentTestids": ["nav-overview", "nav-deployments", "hostile-view", "hostile-ticker", "…"],
+    "presentRegions": [{ "role": "list", "childCount": 0, "name": "hostile-feed", "sample": [] }]
+  },
+  "cost": { "bytes": 402, "tokens": 101 }
+}
+```
+
+The testid existed, on another route. `hint.route` says where you actually are and `presentTestids` says what is here instead, for 101 tokens and no snapshot. `presentRegions` is the other half: a list with `childCount: 0` is an empty state, which is a different bug from a list that failed to render at all.
+
+## "Is this button destructive?"
+
+Reticle refuses controls that look destructive, before acting:
+
+```json
+{
+  "error": "potentially destructive action blocked; retry with args.confirmDangerous=true",
+  "recovery": "Reticle blocked a potentially destructive control (delete, remove, revoke…) on purpose. If you mean it, retry the same action with args.confirmDangerous set to true. This is a deliberate refusal, not a defect: there is nothing to report."
+}
+```
+
+Confirm it explicitly when you mean it:
+
+```json
+{ "ref": "e623", "action": "click", "args": { "confirmDangerous": true }, "until": { … } }
+```
+
+<Note>
+  The matcher is conservative and will occasionally stop something harmless. A button labelled "New
+  deploy" trips it. That is the trade: a false stop costs you one argument, and a false start costs
+  you a deleted record.
+</Note>
+
+## "Did my change break anything else?"
+
+```json
+{ "tool": "reticle_verify_change", "args": { "since": "HEAD~1" } }
+```
+
+Give it the files you edited, or a git ref. It works out which saved flows cover them and replays only those.
+
+## "What is even testable in this app?"
+
+The best first call on an unfamiliar codebase:
+
+```json
+{ "tool": "reticle_capabilities" }
+```
+
+```json
+{
+  "testids": ["login-email", "login-submit", "new-deploy", "deploy-submit", "…"],
+  "signals": ["auth:granted", "auth:denied", "deploy:created", "modal:opened", "…"],
+  "stores": ["app"],
+  "flows": [
+    {
+      "name": "ship-a-deploy",
+      "steps": ["nav-deployments", "new-deploy", "deploy-name", "deploy-submit"]
+    }
+  ],
+  "source": "live"
+}
+```
+
+That is the app stating what it considers testable, which beats snapshotting the DOM and inferring it from element names.
+
+## "The error state has never been tested"
+
+Most error states have never run. Force one:
+
+```json
+{
+  "tool": "reticle_network_mock",
+  "args": { "mocks": [{ "urlContains": "/api/deploys", "status": 500 }] }
+}
+```
+
+Then drive the flow and assert the error UI appears. Pass `clear: true` to turn mocking off.
+
+<Warning>
+This one needs a **Reticle-driven browser**, because mocks are applied through CDP and the always-on
+SDK cannot do that. A pooled lease is **not** enough. Re-verified on 2026-08-16: calling it against a
+tab from `reticle_lease` returns
+
+```json
+{
+  "applied": false,
+  "count": 0,
+  "ok": false,
+  "reason": "no-cdp-provider",
+  "recommendation": "this needs a Reticle-driven browser (it is applied through CDP, which the always-on SDK cannot do), start with `reticle drive <url>` or set RETICLE_CDP_URL"
+}
+```
+
+Under a driven browser the same call answers `{ "applied": true, "count": 1 }`. The same rule applies to `reticle_screenshot`, `reticle_visual_diff` and `reticle_viewport`, which report `no-visual-provider` instead.
+
+</Warning>
+
+## "I want this to run on every PR"
+
+Record it once, replay it forever:
+
+```json
+{ "tool": "reticle_flow_verify", "args": { "names": ["docs-check"] } }
+```
+
+Omit `names` to replay every saved flow. Either way you get one consolidated verdict, and only the failures carry detail:
+
+```json
+{
+  "status": "fail",
+  "total": 1,
+  "passed": 0,
+  "failed": 1,
+  "summary": "0/1 flows pass, 1 need attention: docs-check",
+  "failures": [
+    {
+      "flow": "docs-check",
+      "verdict": "drift",
+      "whatChanged": "testid \"login-submit\" not found",
+      "whereInSource": "src/components/Login.tsx:81",
+      "nextAction": "rebind the anchor to \"sign-out\" (closest survivor), or update the flow if the change was intended."
+    }
+  ]
+}
+```
+
+It also returns `flaky`, the flows it has seen both pass and fail on unchanged code. Treat that list as a bug in the flow, not in the app.
+
+<CardGroup cols={2}>
+  <Card title="The predicate grammar" icon="filter" href="/predicates">
+    Every kind, every field, and which ones actually prove something.
+  </Card>
+  <Card title="Best practices" icon="star" href="/best-practices">
+    The habits behind these recipes, and the mistakes that produce a confident wrong pass.
+  </Card>
+</CardGroup>

package/docs/skill-file.mdx

@@ -0,0 +1,107 @@
+---
+title: 'The SKILL file: paste and go'
+sidebarTitle: SKILL file
+description: One URL you paste into any coding agent to teach it Reticle. How it works, what it contains, and when you need it at all.
+icon: graduation-cap
+---
+
+Paste `https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md` into any coding agent and say "read this and set up Reticle". The document installs Reticle, wires it into your app, and then drives a proper verification loop, choosing setup mode or test mode itself based on whether `.reticle.json` already exists. You often do not need it: `npx @reticlehq/server init` configures Claude Code and Cursor directly.
+
+`SKILL.md` is a single document you hand to a coding agent. It teaches the agent to install Reticle, wire it into your app, and then drive a verification loop properly. Without you explaining any of it.
+
+```
+https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md
+```
+
+That URL is live and returns the current version. Paste it into your agent and say "read this and set up Reticle".
+
+<Note>
+  You often do not need it. `npx @reticlehq/server init` writes a `/reticle` slash command for
+  Claude Code automatically, and installs agent rule files for Claude and Cursor. The SKILL file is
+  for agents that `init` cannot configure, for a from-scratch install, or when you want the agent to
+  have the full protocol in context rather than a summary.
+</Note>
+
+## It has two modes, and it picks one itself
+
+The first thing the document tells an agent to do is check which situation it is in:
+
+```bash
+cat .reticle.json 2>/dev/null || echo "NOT_FOUND"
+```
+
+- **Not found** → run **Setup mode**: register the MCP server, install the SDK, wire the entry point, validate the connection, and prove it on one flow while the user watches.
+- **Found** → run **Test mode**: connect, orient, decide what to test, drive it, report.
+
+One document, two jobs, no flag for you to remember. The second time you invoke it, it skips straight to the useful part.
+
+## What Setup mode actually does
+
+| Phase | What the agent does |
+| --- | --- |
+| Save the skill | Store it as `/reticle` so the loop is one word away from then on |
+| Run `init` | Without asking you questions it can answer itself |
+| Manual fallbacks | Per-agent MCP config, per-framework SDK wiring, for anything `init` marked `⚠` |
+| Validate | Confirm a session actually connected. Not that a checklist went green |
+| Prove it | Drive one real flow while you watch, so the install ends in evidence |
+
+That last row is the one that matters. Plenty of installs "succeed" and then nothing works. The skill does not consider itself finished until a real flow has produced a real verdict.
+
+## What Test mode actually does
+
+Five phases: connect, orient, decide what to test, run the tests, report. The reporting format is specified, which matters more than it sounds. An agent left to summarise freely will summarise optimistically.
+
+The rules it operates under are the same ones these docs keep repeating:
+
+- Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.
+- `verified: "unknown"` is not a pass.
+- Never weaken a check to make it pass.
+
+## Feedback is the first section, on purpose
+
+Before setup, before anything, the document tells the agent that reporting problems is part of the job. And that this applies **during** setup, which is where Reticle is most likely to break and least likely to hear about it.
+
+It even covers the case where nothing is installed yet:
+
+```bash
+npx @reticlehq/server feedback --agent --kind gap "init finished but no session ever connected"
+```
+
+That works with no daemon running, which is the entire point. The install that failed halfway is the one worth hearing about, and in that state the MCP tools do not exist.
+
+<Tip>
+  It also draws a line that saves everyone time: report defects in **Reticle**. A bug found in the
+  app under test is Reticle working correctly, and belongs in the answer to the user.
+</Tip>
+
+## It ships inside the package too
+
+`SKILL.md` is bundled into `@reticlehq/server` at publish time, alongside a copy of this entire documentation site. So an agent that has already installed Reticle can read it from disk without a network round trip:
+
+```
+node_modules/@reticlehq/server/SKILL.md
+node_modules/@reticlehq/server/docs/
+```
+
+Handy in a sandbox with no outbound network, which is an increasingly common place for an agent to live.
+
+## Should you read it?
+
+Probably not, unless you are curious. It is roughly 60 KB and written for an agent, which means it is exhaustive in the way a runbook is exhaustive. Every fallback, every framework, every failure mode spelled out rather than summarised.
+
+If you want the human version of the same material, you are already in it:
+
+<CardGroup cols={2}>
+  <Card title="Agentic install" icon="wand-magic-sparkles" href="/install-agentic">
+    What `reticle init` does, with real output.
+  </Card>
+  <Card title="Manual install" icon="screwdriver-wrench" href="/install-manual">
+    Every step `init` cannot automate.
+  </Card>
+  <Card title="Agent cheat sheet" icon="bolt" href="/agent-cheatsheet">
+    The one-screen version of the drive loop.
+  </Card>
+  <Card title="Best practices" icon="star" href="/best-practices">
+    The habits that make verdicts worth trusting.
+  </Card>
+</CardGroup>

package/docs/state-management.mdx

@@ -0,0 +1,199 @@
+---
+title: State management
+description: Register any store so Reticle can read what your app believes. Zustand and Redux work natively, and eight more have adapters.
+icon: database
+---
+
+**Reticle reads any store that has `getState()` and `subscribe()`, which covers Zustand and Redux with no adapter at all. TanStack Query, Pinia, Svelte stores, Jotai, Valtio, MobX, XState and Recoil each have a one-line adapter, and `pushStore` covers anything else.** Register one with `registerStore('app', myStore)` in your dev-only `src/reticle-dev.ts`.
+
+Reading application state is what separates a verdict from a screenshot. A `200` proves the server was reachable. A rendered row proves React ran. Only state proves your app accepted the change.
+
+Reticle needs one thing from your store: a way to read it, and a way to know when it changed.
+
+## The contract
+
+```ts
+interface StoreLike {
+  getState(): unknown;
+  subscribe(listener: () => void): () => void;
+}
+```
+
+Anything with that shape registers directly, with no adapter.
+
+```ts
+import { registerStore } from '@reticlehq/browser';
+
+registerStore('app', myStore);
+```
+
+<Warning>
+Pass the **store**, not `() => store.getState()`. The store form wires `subscribe`, so every mutation
+emits a state diff. The getter form still works for compatibility but leaves the store on pull-only
+reads: no change events, and an empty `stateDiffs` in every verdict.
+
+That reads as "nothing changed" and actually means "I was never watching". It is the most common instrumentation mistake there is.
+
+</Warning>
+
+## Works natively
+
+<CardGroup cols={2}>
+  <Card title="Zustand" icon="bolt">
+    A zustand hook already has `getState` and `subscribe`. Pass it straight in.
+  </Card>
+  <Card title="Redux" icon="boxes-stacked">
+    A Redux store is `StoreLike` by definition. Same one-liner.
+  </Card>
+</CardGroup>
+
+```ts
+registerStore('app', useApp); // zustand
+registerStore('app', store); // redux
+```
+
+This is what the Reticle fixture app does, and it is why its verdicts carry `stateDiffs: [{ "path": "auth", "from": null, "to": "…" }]`.
+
+## Adapters
+
+Eight libraries do not fit `StoreLike` for a reason specific to each. Every adapter returns a `StoreLike` you hand straight to `registerStore`.
+
+Each example below is the one documented in the adapter's own source.
+
+### TanStack Query
+
+```ts
+import { tanstackQueryStore } from '@reticlehq/browser';
+
+registerStore('queries', tanstackQueryStore(queryClient));
+```
+
+<Tip>
+  Register your server cache even if you already register a client store. "The screen is plausible
+  and the network is silent" is the normal failure with query caches: a mutation forgets to
+  invalidate, the UI keeps rendering a number that was true a minute ago, and nothing fires for
+  anyone to notice. The cache's freshness metadata is the only witness.
+</Tip>
+
+### Pinia
+
+```ts
+import { piniaStore } from '@reticlehq/browser';
+
+registerStore('cart', piniaStore(useCartStore()));
+```
+
+### Svelte stores
+
+```ts
+import { svelteStore } from '@reticlehq/browser';
+
+registerStore('cart', svelteStore(cartStore));
+```
+
+### Jotai
+
+Atoms are not a store, so you name the ones you care about.
+
+```ts
+import { jotaiStore } from '@reticlehq/browser';
+import { getDefaultStore } from 'jotai';
+
+registerStore('app', jotaiStore(getDefaultStore(), { cart: cartAtom, user: userAtom }));
+```
+
+### Valtio
+
+```ts
+import { valtioStore } from '@reticlehq/browser';
+import { snapshot, subscribe } from 'valtio/vanilla';
+
+registerStore('app', valtioStore(state, snapshot, subscribe));
+```
+
+### MobX
+
+```ts
+import { mobxStore } from '@reticlehq/browser';
+import { reaction, toJS } from 'mobx';
+
+registerStore('app', mobxStore(store, toJS, reaction));
+```
+
+You pass `toJS` and `reaction` in rather than Reticle importing MobX. The SDK stays free of your state library, and your bundle stays free of a copy it did not ask for.
+
+### XState
+
+```ts
+import { xstateStore } from '@reticlehq/browser';
+
+registerStore('machine', xstateStore(actor));
+```
+
+An XState actor's `subscribe` returns a subscription object rather than an unsubscribe function, which is the single reason it does not satisfy `StoreLike` already.
+
+### Recoil
+
+The most involved, because Recoil has no store object to hand over.
+
+```ts
+import { recoilStore } from '@reticlehq/browser';
+
+const latest = useRef(snapshot_UNSTABLE());
+const listeners = useRef(new Set<() => void>()).current;
+
+useRecoilTransactionObserver_UNSTABLE(({ snapshot }) => {
+  latest.current = snapshot;
+  for (const l of listeners) l();
+});
+
+registerStore(
+  'recoil',
+  recoilStore(
+    { cart: cartAtom },
+    () => latest.current,
+    (l) => {
+      listeners.add(l);
+      return () => listeners.delete(l);
+    },
+  ),
+);
+```
+
+### Anything else
+
+`pushStore` gives you a store plus the `push` that updates it, so you own the write side. Useful for state that lives somewhere Reticle cannot reach: a web worker, a websocket, a third-party SDK.
+
+```ts
+import { pushStore } from '@reticlehq/browser';
+
+const { store, push } = pushStore({ status: 'idle' });
+registerStore('worker', store);
+
+worker.onmessage = (e) => push(e.data);
+```
+
+## Reading it back
+
+```json
+{ "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.
+
+You can also assert on it directly, which is stronger than reading it afterwards:
+
+```json
+{ "kind": "state", "store": "app", "path": "deployments.0.status", "equals": "live" }
+```
+
+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">
+    Arguments, depth control, and reading a component's hook state.
+  </Card>
+  <Card title="Instrument your app" icon="wrench" href="/instrumentation">
+    Stores are one of three things worth registering. The other two are signals and testids.
+  </Card>
+</CardGroup>

package/docs/style.css

@@ -0,0 +1,14 @@
+/* Any .css file at the docs root is auto-loaded by Mintlify; docs.json has no field for it.
+   Tagline under the footer logo: the footer schema is {socials, links} and takes no text. */
+#footer a.select-none::after {
+  content: 'Your agent says it works. Reticle checks.';
+  display: block;
+  margin-top: 0.75rem;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  color: rgb(var(--gray-500));
+}
+
+.dark #footer a.select-none::after {
+  color: rgb(var(--gray-400));
+}