@reticlehq/server 2.14.0 → 3.2.0

package/dist/telemetry/verification-of.d.ts

@@ -1,16 +1,14 @@
 /**
  * Which tool results count as a completed verification, as one pure rule.
  *
- * It used to live inline in `runTool` and read `status === 'pass'`, mapping everything else to
- * "no verdict". That was wrong in both directions at once, and the shape of the error is visible in
- * the production data:
+ * A verdict is not `status === 'pass'`. That reading is wrong in both directions at once:
  *
- *   - a FAILING suite emitted nothing, so `verification_completed` only ever fired on greens while
- *     `bugsInResult` fired on the reds — bugs with no verifications to divide them by;
- *   - an EMPTY suite ("all 0 flows pass") emitted `verified: yes, passed: true`.
+ *   - a FAILING suite emits nothing, so `verification_completed` fires only on greens while
+ *     `bugsInResult` fires on the reds — bugs with no verifications to divide them by;
+ *   - an EMPTY suite ("all 0 flows pass") emits `verified: yes, passed: true`.
  *
- * Extracted because a rule this easy to get wrong, feeding the one number shown to investors, should
- * be readable and testable on its own rather than inferred from a ternary inside a dispatcher.
+ * Kept in one place, out of `runTool`, because a rule this easy to get wrong should be readable and
+ * testable on its own rather than inferred from a ternary inside a dispatcher.
  */
 import { type BrowserBrand, type Verification } from '@reticlehq/core';
 /**

package/dist/telemetry/verification-of.js

@@ -1,20 +1,19 @@
 /**
  * Which tool results count as a completed verification, as one pure rule.
  *
- * It used to live inline in `runTool` and read `status === 'pass'`, mapping everything else to
- * "no verdict". That was wrong in both directions at once, and the shape of the error is visible in
- * the production data:
+ * A verdict is not `status === 'pass'`. That reading is wrong in both directions at once:
  *
- *   - a FAILING suite emitted nothing, so `verification_completed` only ever fired on greens while
- *     `bugsInResult` fired on the reds — bugs with no verifications to divide them by;
- *   - an EMPTY suite ("all 0 flows pass") emitted `verified: yes, passed: true`.
+ *   - a FAILING suite emits nothing, so `verification_completed` fires only on greens while
+ *     `bugsInResult` fires on the reds — bugs with no verifications to divide them by;
+ *   - an EMPTY suite ("all 0 flows pass") emits `verified: yes, passed: true`.
  *
- * Extracted because a rule this easy to get wrong, feeding the one number shown to investors, should
- * be readable and testable on its own rather than inferred from a ternary inside a dispatcher.
+ * Kept in one place, out of `runTool`, because a rule this easy to get wrong should be readable and
+ * testable on its own rather than inferred from a ternary inside a dispatcher.
  */
-import { CaptureLoss, VerifiedReason } from '@reticlehq/core';
-import { VERDICT_TOOLS } from '../tools/feedback-tools.js';
+import { CaptureLoss, ReplayStatus, ReticleTool, VerificationDriver, Verified, VerifiedReason, } from '@reticlehq/core';
+import { VERDICT_TOOLS } from '../surface/tools/feedback-tools.js';
 import { getBrowserMode } from './browser-mode.js';
+import { harnessDriving } from './harness-drive.js';
 /**
  * The deciding clause, read off the result `decideVerified` wrote it onto.
  *
@@ -53,6 +52,30 @@ const SuiteStatus = {
     PASS: 'pass',
     FAIL: 'fail',
 };
+/**
+ * A flow replay's verdict, in the vocabulary the rest of this file speaks.
+ *
+ * `ReplayStatus` spells itself `ok | drift | error`, so a reader looking for `pass`/`fail` found
+ * neither and every replay emitted nothing at all — on the tool documented as the single-flow
+ * companion to the whole-suite replay, i.e. a verdict in no numerator and no denominator.
+ *
+ * `error` maps to UNKNOWN rather than to a fail. It is the flow failing to LOAD or an action failing
+ * to run, which is Reticle not being able to tell — publishing that as the app's defect is exactly
+ * the mistake the suite reader made the first time.
+ *
+ * Read for the REPLAY TOOL ONLY. `ok` is not a verdict word anywhere else in this surface, and a
+ * merged action that happens to answer with one must not be counted as a verification it never made.
+ */
+const REPLAY_VERDICTS = new Map([
+    [ReplayStatus.OK, { verified: Verified.YES, passed: true }],
+    [ReplayStatus.DRIFT, { verified: Verified.NO, passed: false }],
+    [ReplayStatus.ERROR, { verified: Verified.UNKNOWN, passed: false }],
+]);
+function replayVerdict(toolName, status) {
+    if (ReticleTool.FLOW_REPLAY !== toolName || 'string' !== typeof status)
+        return undefined;
+    return REPLAY_VERDICTS.get(status);
+}
 /**
  * Did the assertion itself pass, across three tool shapes that spell it three ways.
  *
@@ -99,13 +122,14 @@ export function verificationOf(toolName, result, durationMs, brand) {
     // here for work that happened.
     if (true === result['paused'])
         return undefined;
-    const verified = 'string' === typeof result['verified'] ? result['verified'] : undefined;
+    const replay = replayVerdict(toolName, result['status']);
+    const verified = 'string' === typeof result['verified'] ? result['verified'] : (replay?.verified ?? undefined);
     // flow_verify reports `status: pass|fail|unverifiable`; assert reports a boolean `pass`. Accept
     // either shape so the whole family is covered without normalizing four tools' contracts for a
     // metric's convenience — but a status that is neither pass nor fail is NOT a verdict, and an empty
     // suite reports exactly that.
     const status = result['status'];
-    const passed = passedOf(result, status);
+    const passed = passedOf(result, status) ?? replay?.passed;
     if (verified === undefined && passed === undefined)
         return undefined;
     const reason = reasonOf(result);
@@ -144,5 +168,7 @@ export function verificationOf(toolName, result, durationMs, brand) {
         // WHAT was lost, when the reason was that something was. Three owners, three fixes, one bar
         // until now.
         ...(uncleanLoss === undefined ? {} : { uncleanLoss }),
+        // WHOSE drive this was. Absent is the ordinary case — the agent called the tool itself.
+        ...(harnessDriving() ? { driven: VerificationDriver.HARNESS } : {}),
     };
 }

package/dist/workspace-packages.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Every package this repository publishes, and where it lives.
+ *
+ * Several checks need this list: the one that says every integration has an app proving it, the one
+ * that keeps the build cache honest, the one that finds slow tests, the one that checks the commands
+ * in our own README files. Each used to find the list by reading one directory, `packages/`.
+ *
+ * That stopped being true. The specification, the rules that decide a verdict and the adapters are
+ * grouped by what they are, so a check that reads one directory now sees about half of them -- and
+ * goes on passing, which reads as "these are all fine" when it means "most were not looked at". The
+ * same mistake was made four separate times in one afternoon.
+ *
+ * So the list comes from the pnpm workspace file, which is the one place that cannot quietly go
+ * stale: it is what the package manager installs from, so a package missing from it does not go
+ * unchecked, it stops working.
+ *
+ * The local fixture apps are left out on purpose. They are never published and are deliberately
+ * allowed to depend on anything, which is what makes them useful as fixtures.
+ */
+export declare function publishedPackageDirs(): string[];
+/** The same list, as the last part of each path: `core`, `server`, `dom`, and so on. */
+export declare function publishedPackageNames(): string[];

package/dist/workspace-packages.js

@@ -0,0 +1,57 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { workspaceGlobs } from '../../scripts/check-boundaries.mjs';
+import { REPO_ROOT } from './machine/repo-root.js';
+/**
+ * Every package this repository publishes, and where it lives.
+ *
+ * Several checks need this list: the one that says every integration has an app proving it, the one
+ * that keeps the build cache honest, the one that finds slow tests, the one that checks the commands
+ * in our own README files. Each used to find the list by reading one directory, `packages/`.
+ *
+ * That stopped being true. The specification, the rules that decide a verdict and the adapters are
+ * grouped by what they are, so a check that reads one directory now sees about half of them -- and
+ * goes on passing, which reads as "these are all fine" when it means "most were not looked at". The
+ * same mistake was made four separate times in one afternoon.
+ *
+ * So the list comes from the pnpm workspace file, which is the one place that cannot quietly go
+ * stale: it is what the package manager installs from, so a package missing from it does not go
+ * unchecked, it stops working.
+ *
+ * The local fixture apps are left out on purpose. They are never published and are deliberately
+ * allowed to depend on anything, which is what makes them useful as fixtures.
+ */
+export function publishedPackageDirs() {
+    const yaml = readFileSync(join(REPO_ROOT, 'pnpm-workspace.yaml'), 'utf8');
+    const found = [];
+    for (const glob of workspaceGlobs(yaml)) {
+        if (glob.startsWith('apps'))
+            continue;
+        const [head, ...rest] = glob.split('/');
+        const start = join(REPO_ROOT, head ?? '');
+        if (!existsSync(start))
+            continue;
+        collect(start, rest.length, found);
+    }
+    return found;
+}
+/** Walk exactly `levels` directories down, keeping anything that has a manifest. */
+function collect(dir, levels, into) {
+    if (0 === levels) {
+        if (existsSync(join(dir, 'package.json')))
+            into.push(dir);
+        return;
+    }
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory())
+            collect(join(dir, entry.name), levels - 1, into);
+    }
+}
+/** The same list, as the last part of each path: `core`, `server`, `dom`, and so on. */
+export function publishedPackageNames() {
+    // `basename`, not `split('/')`: these directories are built with `join`, so on Windows they hold
+    // backslashes and contain no forward slash at all — the split then returns the WHOLE ABSOLUTE
+    // PATH as the package name. Every caller comparing a name against a real one silently stops
+    // matching, which is the same defect that reported fourteen packages as uncovered.
+    return publishedPackageDirs().map((dir) => basename(dir));
+}

package/docs/README.md

@@ -17,6 +17,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [why-reticle.mdx](why-reticle.mdx) | the false-green problem, the measured case, and where we lose |
 | [install-agentic.mdx](install-agentic.mdx) | what `npx @reticlehq/server init` writes, and how to read its marks |
 | [install-manual.mdx](install-manual.mdx) | wiring the MCP server and SDK by hand, per agent and framework |
+| [skill-setup.md](skill-setup.md) | the setup half of SKILL.md: what to pass `init`, reading its report, and what to do when it cannot finish |
 | [getting-started.md](getting-started.md) | install it, connect an agent, verify something |
 | [usage.md](usage.md) | the long-form narrative; most of it now has a focused page, and it says so at the top |
 | [predicates.mdx](predicates.mdx) | the predicate grammar, and which kinds actually prove something |
@@ -24,31 +25,33 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [recipes.mdx](recipes.mdx) | worked examples for real situations, with the response each returned |
 | [actions.mdx](actions.mdx) | every action and its arguments, including `press` and its history |
 | [faq.mdx](faq.mdx) | production, frameworks, comparisons, and the honest limits |
-| [tools-overview.mdx](tools-overview.mdx) | the 18 advertised tools, the 30 in the cold tail, and why |
-| [tools-snapshot.mdx](tools-snapshot.mdx) | `reticle_snapshot`: three modes, from full tree to a 25-token route check |
-| [tools-query.mdx](tools-query.mdx) | `reticle_query` finds elements by their reported roles, names and labels |
-| [tools-inspect.mdx](tools-inspect.mdx) | `reticle_inspect`: one element, down to source and design tokens |
-| [tools-navigate.mdx](tools-navigate.mdx) | `reticle_navigate`, and why `ok` does not mean the page arrived |
-| [tools-act.mdx](tools-act.mdx) | `reticle_act` acts, proves nothing, and says so |
-| [tools-act-and-wait.mdx](tools-act-and-wait.mdx) | `reticle_act_and_wait`, the tool that produces a verdict |
-| [tools-act-sequence.mdx](tools-act-sequence.mdx) | `reticle_act_sequence`: batch a form into one round trip |
-| [tools-observe.mdx](tools-observe.mdx) | `reticle_observe`, the whole timeline when you don't know what broke |
-| [tools-network.mdx](tools-network.mdx) | `reticle_network`: the request log, redaction, and buffer honesty |
-| [tools-console.mdx](tools-console.mdx) | `reticle_console`, and an empty result that proves it looked |
-| [tools-state.mdx](tools-state.mdx) | `reticle_state`: what the app believes, not what it drew |
-| [tools-wait-for.mdx](tools-wait-for.mdx) | `reticle_wait_for`, for consequences you did not cause |
-| [tools-assert.mdx](tools-assert.mdx) | `reticle_assert`: verdicts, and a real failure explained |
-| [tools-sessions.mdx](tools-sessions.mdx) | `reticle_sessions`: the health fields that decide if driving works |
-| [tools-tools-and-run.mdx](tools-tools-and-run.mdx) | `reticle_tools` / `reticle_run`, reaching the other 30 |
-| [tools-session-and-feedback.mdx](tools-session-and-feedback.mdx) | `reticle_session` / `reticle_feedback`, the human boundary |
+| [tools/overview.mdx](tools/overview.mdx) | the 18 advertised tools, the 30 in the cold tail, and why |
+| [tools/snapshot.mdx](tools/snapshot.mdx) | `reticle_look { action: "page" }`: three modes, from full tree to a 25-token route check |
+| [tools/query.mdx](tools/query.mdx) | `reticle_look { action: "find" }` finds elements by their reported roles, names and labels |
+| [tools/inspect.mdx](tools/inspect.mdx) | `reticle_look { action: "element" }`: one element, down to source and design tokens |
+| [tools/navigate.mdx](tools/navigate.mdx) | `reticle_navigate`, and why `ok` does not mean the page arrived |
+| [tools/act.mdx](tools/act.mdx) | `reticle_act` acts, proves nothing, and says so |
+| [tools/act-and-wait.mdx](tools/act-and-wait.mdx) | `reticle_act_and_wait`, the tool that produces a verdict |
+| [tools/act-sequence.mdx](tools/act-sequence.mdx) | `reticle_act { steps: [...] }`: batch a form into one round trip |
+| [tools/observe.mdx](tools/observe.mdx) | `reticle_observe`, the whole timeline when you don't know what broke |
+| [tools/network.mdx](tools/network.mdx) | `reticle_observe { action: "network" }`: the request log, redaction, and buffer honesty |
+| [tools/console.mdx](tools/console.mdx) | `reticle_observe { action: "console" }`, and an empty result that proves it looked |
+| [tools/state.mdx](tools/state.mdx) | `reticle_look { action: "state" }`: what the app believes, not what it drew |
+| [tools/wait-for.mdx](tools/wait-for.mdx) | `reticle_assert { action: "wait" }`, for consequences you did not cause |
+| [tools/assert.mdx](tools/assert.mdx) | `reticle_assert`: verdicts, and a real failure explained |
+| [tools/sessions.mdx](tools/sessions.mdx) | `reticle_session { action: "list" }`: the health fields that decide if driving works |
+| [tools/tools-and-run.mdx](tools/tools-and-run.mdx) | `reticle_tools` / `reticle_run`, reaching the other 30 |
+| [tools/session-and-feedback.mdx](tools/session-and-feedback.mdx) | `reticle_session` / `reticle_session { action: "feedback" }`, the human boundary |
 | [packages.mdx](packages.mdx) | every library at a glance: what it does, why it exists, when you need it |
 | [packages/](packages/) | one page per published package, with its real exported API and dependencies |
+| [autodrive.md](autodrive.md) | letting Reticle drive the app itself, and keeping the flows it records |
 | [best-practices.mdx](best-practices.mdx) | the habits that make a verdict worth trusting |
 | [skill-file.mdx](skill-file.mdx) | the paste-one-URL skill that teaches an agent Reticle |
 | [agent-cheatsheet.md](agent-cheatsheet.md) | the condensed version an agent keeps in context |
 | [reticle-manual.md](reticle-manual.md) | GENERATED: what each tool actually returned when it was called, per argument shape |
 | [for-agents.md](for-agents.md) | how to fetch these docs as Markdown or `llms.txt` |
 | [architecture.md](architecture.md) | how it works, and why it is built this way |
+| [protocol.mdx](protocol.mdx) | the Open Verification Protocol: the rules Reticle decides by, published separately so you can check them |
 | [platform-integration.md](platform-integration.md) | Vite, Next, Remix, Astro, plain HTML |
 | [http-transport.md](http-transport.md) | driving the tools over plain HTTP/SSE, for clients that cannot reload MCP |
 | [desktop.mdx](desktop.mdx) | Electron and Tauri in full: setup, IPC, screenshots, headless, troubleshooting |
@@ -76,18 +79,21 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 
 ## For people working on Reticle
 
-**Start:** [`CONTRIBUTING.md`](https://github.com/reticlehq/reticle/blob/main/CONTRIBUTING.md) → [gates.md](gates.md).
+**Start:** [`CONTRIBUTING.md`](https://github.com/reticlehq/reticle/blob/main/CONTRIBUTING.md) → [gates.md](https://github.com/reticlehq/reticle/blob/main/docs/gates.md).
 
 | Page | What it answers |
 | --- | --- |
-| [gates.md](gates.md) | **I changed some files. Which gate do I run?** |
-| [gate-plan.md](gate-plan.md) | why the gates are shaped this way, and what is still unbuilt |
+| [gates.md](https://github.com/reticlehq/reticle/blob/main/docs/gates.md) | **I changed some files. Which gate do I run?** |
+| [gate-plan.md](https://github.com/reticlehq/reticle/blob/main/docs/gate-plan.md) | why the gates are shaped this way, and what is still unbuilt |
+| [required-checks.md](required-checks.md) | which checks actually block a merge, and which only look like they do |
+| [adapters.md](adapters.md) | what an adapter is, the three kinds, and how to write one |
+| [state-files.md](state-files.md) | what to do when a file on disk came from a different version of Reticle |
 | [system-map.md](system-map.md) | how a tool call reaches the app, and which failures are silent |
-| [telemetry-contract.md](telemetry-contract.md) | required reading before touching anything that emits |
-| [telemetry-events.mdx](telemetry-events.mdx) | every event kind and its payload, and the question each one exists to answer |
+| [telemetry-contract.md](https://github.com/reticlehq/reticle/blob/main/docs/telemetry-contract.md) | required reading before touching anything that emits |
+| [telemetry-events.mdx](https://github.com/reticlehq/reticle/blob/main/docs/telemetry-events.mdx) | every event kind and its payload, and the question each one exists to answer |
 | [first-drive.md](first-drive.md) | clone to a real verdict in about fifteen minutes, and the traps on the way |
 | [debugging.md](debugging.md) | debugging Reticle itself: the four signals and what each answers |
-| [fixtures.md](fixtures.md) | the sibling `reticle-fixtures` repo: install complexity, not regressions |
+| [fixtures.md](https://github.com/reticlehq/reticle/blob/main/docs/fixtures.md) | the sibling `reticle-fixtures` repo: install complexity, not regressions |
 | [matrix/README.md](https://github.com/reticlehq/reticle/blob/main/docs/matrix/README.md) | submitting an MCP-client compatibility record, the best first contribution |
 | [matrix/MATRIX.md](https://github.com/reticlehq/reticle/blob/main/docs/matrix/MATRIX.md) | which clients are known to work (generated; do not hand-edit) |
 | [`../apps/README.md`](https://github.com/reticlehq/reticle/blob/main/apps/README.md) | what belongs in `apps/`, and what does not |

package/docs/actions.mdx

@@ -5,7 +5,7 @@ description: Every action reticle_act and reticle_act_and_wait can perform, with
 icon: hand-pointer
 ---
 
-Every action Reticle can perform takes the same shape: a `ref` from [`reticle_snapshot`](/tools-snapshot) or [`reticle_query`](/tools-query), an `action` name, and an optional `args` object. The same seventeen actions are available on [`reticle_act`](/tools-act), which proves nothing, and on [`reticle_act_and_wait`](/tools-act-and-wait), which returns a verdict.
+Every action Reticle can perform takes the same shape: a `ref` from [`reticle_snapshot`](/tools/snapshot) or [`reticle_query`](/tools/query), an `action` name, and an optional `args` object. The same seventeen actions are available on [`reticle_act`](/tools/act), which proves nothing, and on [`reticle_act_and_wait`](/tools/act-and-wait), which returns a verdict.
 
 ```json
 { "ref": "e104", "action": "fill", "args": { "value": "reticle" } }
@@ -93,9 +93,9 @@ Several actions in one round trip:
 ```
 
 <Warning>
-  [`reticle_act_sequence`](/tools-act-sequence) returns `ok: true` when the steps were
+  [`reticle_act_sequence`](/tools/act-sequence) returns `ok: true` when the steps were
   **dispatched**, not when they worked. Batch the setup, then prove the outcome with
-  [`reticle_act_and_wait`](/tools-act-and-wait) on the final step.
+  [`reticle_act_and_wait`](/tools/act-and-wait) on the final step.
 </Warning>
 
 ## Real versus synthetic input
@@ -115,6 +115,6 @@ Fields sitting at their uninformative default are **omitted**, so a clean action
 
 `occluded` is the answer to a large share of "the button doesn't work" reports: the click landed on the modal overlay sitting on top of it.
 
-<Card title="Full field-by-field walkthrough" icon="hand-pointer" href="/tools-act">
+<Card title="Full field-by-field walkthrough" icon="hand-pointer" href="/tools/act">
   What each effect field tells you, with a real response.
 </Card>

package/docs/adapters.md

@@ -0,0 +1,75 @@
+---
+title: Writing an adapter
+description: What an adapter is, which kinds exist, and how to build one of your own.
+---
+
+Reticle watches an app from the inside. Most of what it does is the same everywhere: a click is a click, a failed request is a failed request. A few things are not, and those are what adapters are for.
+
+There are three kinds, and they answer three different questions.
+
+| kind | the question it answers | example |
+| --- | --- | --- |
+| **framework** | given an element on the page, which component is it and which file is that written in? | `@reticlehq/react` |
+| **build** | how does the SDK get into the page, and how does an element learn which file it came from? | `@reticlehq/vite-plugin` |
+| **realm** | how do we watch this kind of app's own traffic and take its picture? | `@reticlehq/electron` |
+
+You almost certainly want the first one. It is the only kind you can write today without changing Reticle itself, and it is the one that makes a failing check say `src/CartRow.tsx:42` instead of "something on the page".
+
+## Writing a framework adapter
+
+An adapter is an object with a name and one required function. Register it once, when your module loads.
+
+```ts
+import { registerAdapter } from '@reticlehq/browser';
+
+registerAdapter({
+  name: 'solid',
+  identify(element) {
+    const owner = findSolidOwner(element); // your framework's own lookup
+    if (owner === null) return null; // not ours: let another adapter answer
+    return {
+      componentStack: ['CartRow', 'Cart', 'App'], // innermost first
+      source: { file: 'src/CartRow.tsx', line: 42 },
+    };
+  },
+});
+```
+
+That is the whole required surface. Two optional functions add more:
+
+```ts
+registerAdapter({
+  name: 'solid',
+  identify,
+  readState: (element) => currentSignalsFor(element), // what the component is holding
+  hasHoverHandlers: (element) => hasOnEnter(element), // hover may need a real mouse
+});
+```
+
+### The rules, and why each exists
+
+**Return `null` when the element is not yours.** Adapters are asked in turn and the first real answer wins, so `null` means "ask the next one" rather than "there is no answer". An adapter that returns a guess for everything makes every other adapter unreachable.
+
+**`componentStack` runs innermost first.** The element's own component, then its parent, and so on. It is used to name what was clicked, and the closest name is the useful one.
+
+**`source.file` should be relative to the project root** if you can manage it. An absolute path from the machine that built the bundle means nothing on the machine reading the verdict, and Reticle cannot tell one from the other.
+
+**Nothing you return is trusted as a verdict.** An adapter says what an element _is_. Whether a check passed is decided elsewhere, from what the page actually did, and there is no field you can set that changes it. This is deliberate: a verdict that could be supplied by the thing being verified is not a verdict.
+
+**Throwing is contained but not free.** A throw is caught rather than allowed to take the page down. It is still a bad outcome, because the element goes unidentified and every verdict about it loses its source pointer. Return `null` when you do not know, rather than raising.
+
+### Registering more than once
+
+Registration is idempotent by name: registering `solid` twice leaves one. The registry also survives a hot reload, because a module re-evaluated by the dev server would otherwise drop its adapter and source mapping would quietly degrade until the next full refresh.
+
+## The other two kinds
+
+Honest about where things stand: **build and realm adapters are not yet something you can add from outside.** Both exist, both work, and both are wired in by name rather than registered.
+
+A **build adapter** is a plugin for your build tool. It does two things: make sure `connect()` runs in the page, and stamp each element with the file it came from. `@reticlehq/vite-plugin` is the one to read. Adding another today means a change to Reticle's own installer, because the installer has to know which projects need which plugin.
+
+A **realm adapter** teaches Reticle about a kind of app that is not a browser tab: an Electron window, a Tauri window. It supplies the shell's own message traffic and a way to photograph the window. `@reticlehq/electron` is the one to read. What a realm _is_ now lives in one table (`core/src/realm/registry.ts`), so the facts are in one place; what a realm _does_ is still code inside Reticle.
+
+If you want to write either, open an issue and say what you are building. The interfaces exist; what is missing is the door.
+
+A template for each of the four kinds, including the two that are contributable today, is in [`adapters/CONTRIBUTING.md`](https://github.com/reticlehq/reticle/blob/main/adapters/CONTRIBUTING.md). It carries the rules each adapter kind must hold to, and why each rule exists.

package/docs/agent-cheatsheet.md

@@ -12,9 +12,9 @@ One screen to get fluent. Reticle is the **proof layer for AI agents**: no scree
 
 | Verb | Tool | One-liner |
 | --- | --- | --- |
-| **look** | `reticle_snapshot` / `reticle_query` | See the page (semantic tree) / find one specific element. |
-| **act** | **`reticle_act_and_wait`** / `reticle_act_sequence` / `reticle_act` | **Act + name the consequence, one hop. Reach for this first.** / batch a whole journey in one hop / move the app and prove nothing. |
-| **observe** | `reticle_observe` / `reticle_wait_for` | Everything the app did after `since` / block until true. |
+| **look** | `reticle_look { action: "page" }` / `reticle_look { action: "find" }` | See the page (semantic tree) / find one specific element. |
+| **act** | **`reticle_act_and_wait`** / `reticle_act { steps: [...] }` / `reticle_act` | **Act + name the consequence, one hop. Reach for this first.** / batch a whole journey in one hop / move the app and prove nothing. |
+| **observe** | `reticle_observe` / `reticle_assert { action: "wait" }` | Everything the app did after `since` / block until true. |
 | **assert** | `reticle_assert` | Evaluate a predicate → `{ pass, evidence, failureReason? }`. The end of every loop. |
 
 > **Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** Everything else moves or reads the app and proves nothing, so a drive ending without one of those two has no result however many tools it used. `reticle_act` is the tool agents reach for by habit and it catches nothing; `act_and_wait` is where defects actually surface. And `verified: "unknown"` is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.
@@ -26,7 +26,7 @@ One screen to get fluent. Reticle is the **proof layer for AI agents**: no scree
 **Never sleep. Wait deterministically.** Fixed sleeps are the #1 cause of flaky agent tests. Instead:
 
 - `reticle_act_and_wait({ ref, action })` with **no `until`** waits for the page to _settle_ (network + structural DOM idle; ambient count-up/spinner churn is ignored so an animated page still settles) before returning: the one-call replacement for "click then sleep 500ms".
-- Need to wait without acting? `reticle_wait_for({ predicate: { kind: "settled", quietMs } })`.
+- Need to wait without acting? `reticle_assert({ action: "wait", predicate: { kind: "settled", quietMs } })`.
 - Waiting for a specific outcome? Pass that consequence as the predicate (`{ signal }` / `{ net }`), or `allOf` it with `{ kind: "settled" }` to wait for both the event _and_ the page going quiet.
 
 **A predicate that does not parse produces NO verdict, not a failing one.** Nothing runs, so the drive ends with no result at all, which is strictly worse than a failure. The shapes below are the ones agents reach for most; the first column now works, but knowing the second saves you the round trip:
@@ -48,7 +48,7 @@ One screen to get fluent. Reticle is the **proof layer for AI agents**: no scree
 
 Two consequences worth knowing before you write your next predicate:
 
-- **You can now assert what a field contains.** That was not possible before; agents worked around it by reading the value out of band with `reticle_query` and comparing in prose, which produces no verdict and therefore does not count as verification.
+- **You can now assert what a field contains.** That was not possible before; agents worked around it by reading the value out of band with `reticle_look { action: "find" }` and comparing in prose, which produces no verdict and therefore does not count as verification.
 - **`{ role, text }` now checks the text.** It used to match on role alone, so it matched every button on the page. If an assertion you have used for months starts failing, that is the likely reason, and the failure is the truth arriving late.
 
 Fields that nothing can check are refused rather than ignored: `by` without a `value`, and `label`, `placeholder`, `testid`, `alt` or `component` when a higher-precedence field already selected the element. An element query is a first-match dispatch, not a conjunction.
@@ -90,40 +90,50 @@ A claim is real only when the layers agree. Check more than the UI:
 
 | Layer | Tool(s) | Question it answers |
 | --- | --- | --- |
-| **UI** | `reticle_snapshot` / `reticle_query` | Is it on screen / in the right state? |
+| **UI** | `reticle_look { action: "page" }` / `reticle_look { action: "find" }` | Is it on screen / in the right state? |
 | **signal** | `reticle_capabilities` / `reticle_observe` | Did the app emit the intent it advertised? |
-| **network** | `reticle_network` | Did `POST /x` actually fire and return 200? |
-| **store** | `reticle_state` | Does live framework/store state match? |
+| **network** | `reticle_observe { action: "network" }` | Did `POST /x` actually fire and return 200? |
+| **store** | `reticle_look { action: "state" }` | Does live framework/store state match? |
 
 > **Rule:** a passing UI assert that the store, network, or signal contradicts is a **false green**.
 
-**Session health is universal.** Every live-session tool result carries a `session` block (`throttled`, `focused`, `lastSeenMs`); when `throttled:true` it also adds a `warning` + `recommendation` (refocus, or `reticle drive`). A throttled/backgrounded tab can silently no-op timers/rAF/pointer gestures. If you see `session.throttled`, distrust a green and refocus first.
+**Session health is universal.** Every live-session tool result carries a `session` block (`throttled`, `focused`, `lastSeenMs`); when `throttled:true` it also adds a `warning` + `recommendation`. Read the `recommendation`: it differs by cause, and the two causes have different fixes.
 
-> Store reads (`reticle_state`) are the reliable path; the DOM can lie (optimistic UI, stale render).
+`throttled` is `hidden || stale`, and it is not a verdict that the tab cannot be driven. A tab that is **hidden** does clamp timers and rAF, so an action can land on a page that never advances. A tab that is merely **stale**, meaning no health heartbeat arrived inside the window, is usually just a quiet page, and is very often still driveable; a session flagged this way has taken a sign-in and two clean net-grade verdicts with no retries. Try the drive before you conclude anything, and reach for `refuseWhenThrottled: true` when the work is timing-sensitive (animations, debounces, gestures), which is what actually degrades.
 
-**Truncation and coverage are declared, never silent.** A big `reticle_state` read carries `truncation` when the transport caps dropped items; its presence means "this is NOT the whole value", so an absence assertion over a truncated read proves nothing; scope with `path`/`depth` instead. A `reticle_assert` verdict carries `coverage` when part of the page was unobservable (cross-origin iframe, closed shadow root); a green then means "nothing failed in the part I could see", not "the page is correct". Both fields are **omitted when everything was fine**, so their presence is the warning.
+**Leasing is not a free upgrade.** `reticle_lease` gives a guaranteed scriptable context, and it is a _separate_ one: the HUD lives in the human's tab, so everything you do in a lease is invisible to the person watching. Taking that advice with someone sitting in front of the app makes the product look broken while it works correctly. Working alone, lease and do not think about it; with an audience, spend a slower tab to stay visible.
+
+> Store reads (`reticle_look { action: "state" }`) are the reliable path; the DOM can lie (optimistic UI, stale render).
+
+**Truncation and coverage are declared, never silent.** A big `reticle_look { action: "state" }` read carries `truncation` when the transport caps dropped items; its presence means "this is NOT the whole value", so an absence assertion over a truncated read proves nothing; scope with `path`/`depth` instead. A `reticle_assert` verdict carries `coverage` when part of the page was unobservable (cross-origin iframe, closed shadow root); a green then means "nothing failed in the part I could see", not "the page is correct". Both fields are **omitted when everything was fine**, so their presence is the warning.
 
 **Charts report their own geometry faults.** Any element descriptor containing a broken plot carries `chart: [{ kind, tag, attr, sample }]`, one of `non-finite-coordinates` (a zero-range scale divided by zero; always a bug), `empty-geometry` (mounted but no data reached it), `degenerate-geometry` (every point identical). No extra call and no flag: query the chart as you would anyway. A healthy chart adds nothing. This matters because a chart is the one widget whose correctness is _geometry_: the store can be right while the polyline is blank, and neither a state read nor a screenshot catches it. Canvas charts are pixels, not DOM: read their data with `canvasChartData(canvasEl, window)` instead.
 
-**Reads never go silently empty.** A zero-result read returns a `hint`, not a bare `[]`: `reticle_query` → `{ route, presentTestids, knownEmptyState }`; `reticle_network` → `{ totalInWindow, present[] }` (what DID fire); `reticle_console` → `{ totalInWindow, byLevel }` (so "0 errors" ≠ "silent page"); `reticle_state` lists `storeNames` when a store isn't found. Read the hint before assuming "not there." Scope big stores with `reticle_state({ store, path:"a.b.0", depth })` instead of paying for the whole tree; a wrong `path` returns `{ found:false, availableKeys }` so it's self-correcting.
+**Reads never go silently empty.** A zero-result read returns a `hint`, not a bare `[]`: `reticle_look { action: "find" }` → `{ route, presentTestids, knownEmptyState }`; `reticle_observe { action: "network" }` → `{ totalInWindow, present[] }` (what DID fire); `reticle_observe { action: "console" }` → `{ totalInWindow, byLevel }` (so "0 errors" ≠ "silent page"); `reticle_look { action: "state" }` lists `storeNames` when a store isn't found. Read the hint before assuming "not there." Scope big stores with `reticle_look({ action: "state", store, path:"a.b.0", depth })` instead of paying for the whole tree; a wrong `path` returns `{ found:false, availableKeys }` so it's self-correcting.
 
 ## Core tool set
 
-The tools advertised DIRECTLY, i.e. what you'll use 90% of the time. Everything else is one `reticle_run` away (see Token note below).
+The tools you are shown, plus `reticle_run`, which calls any registered tool by name whether or not it is advertised.
+
+`reticle_navigate` · `reticle_act` · `reticle_act_and_wait` · `reticle_assert` · `reticle_look` · `reticle_observe` · `reticle_session` · `reticle_verify` · `reticle_tools`
+
+Most of what used to be a tool of its own is now an action on one of them:
+
+`reticle_look { action: "page" }` (was `reticle_snapshot`) · `{ action: "find" }` (`reticle_query`) · `{ action: "element" }` (`reticle_inspect`, DOM node → `src/App.tsx:104`) · `{ action: "state" }` (`reticle_state`) · `reticle_observe { action: "network" }` · `{ action: "console" }` · `reticle_assert { action: "wait" }` (`reticle_wait_for`) · `reticle_act { steps: [...] }` (`reticle_act_sequence`) · `reticle_session { action: "list" }` (`reticle_sessions`) · `{ action: "feedback" }` (tell the maintainers what is missing) · `{action:"yield"}` the moment you stop driving · `{action:"resume"}` after a human pause.
 
-`reticle_sessions` · `reticle_navigate` · `reticle_snapshot` · `reticle_query` · `reticle_act` · `reticle_act_sequence` · `reticle_act_and_wait` · `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_wait_for` · `reticle_assert` · `reticle_state` · `reticle_inspect` (DOM node → `src/App.tsx:104`) · `reticle_feedback` (tell the maintainers what is missing) · `reticle_session` (hand back: `{action:"yield"}` the moment you stop driving, `{action:"resume"}` after a human pause).
+Call an old name and you are told the new one. `reticle_tools` prints the live surface and every mapping.
 
 - `reticle_verify`: **the only core tool that CONCLUDES.** `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call (destructive: it really clicks). `{ action:"flows" }` replays every saved flow with no model in the loop. Reach for it when you think you are done: every other tool here answers "here is more to look at".
 
-Frequently useful but NOT core, so reach them through `reticle_run({ tool, args })`: `reticle_capabilities` (the app's whole testable surface in one call; `{fromDisk:true}` needs no browser), `reticle_domain` (learn the app + gaps), `reticle_baseline {action:"diff"}`, `reticle_project` (run history).
+Not on this surface at all, and NOT reachable by any call from it: `reticle_capabilities` (the app's whole testable surface in one call), `reticle_domain` (learn the app + gaps), `reticle_baseline {action:"diff"}`, `reticle_project` (run history), `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock`, `reticle_clock`. They need a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1`, which advertises the full table.
 
-**Reach past core when…** you need to record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_flow_heal`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify {action:"crawl"}` is now advertised directly, clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_query` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven or leased), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
+**What the wider surface adds, if you start the daemon with `RETICLE_ADVERTISE_ALL_TOOLS=1`:** record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_verify { action: "heal" }`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify {action:"crawl"}` is now advertised directly, clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_look { action: "find" }` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven or leased), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
 
 ## flows vs baselines vs project.json (the persistence layers)
 
 | Artifact | Tool(s) | What it is |
 | --- | --- | --- |
-| **flows** | `reticle_flow_save*` / `reticle_flow_replay` / `reticle_flow_heal` | Replayable **golden journeys**, anchored to testids/signals; drift is legible and self-heals. |
+| **flows** | `reticle_flow_save*` / `reticle_flow_replay` / `reticle_verify { action: "heal" }` | Replayable **golden journeys**, anchored to testids/signals; drift is legible and self-heals. |
 | **baselines** | `reticle_baseline {action:"save"}` / `reticle_baseline {action:"diff"}` | Structural **"before" snapshots**; `reticle_baseline {action:"diff"}` flags regressions against them. |
 | **project.json** | `reticle_project` | Cross-run **run-history**: "did it behave like last run?" read via `reticle_project`. |
 
@@ -138,11 +148,11 @@ Recent additions, each of which answers a question agents were previously asking
 | Field | On | What it tells you |
 | --- | --- | --- |
 | `expiresInMs` | `reticle_lease { action: "acquire" }` | How long the lease lives if untouched, reset by every call that targets it. Plan a pass to finish inside it, or re-acquire deliberately, rather than losing a measurement to a silent expiry. |
-| `scroll` | `reticle_inspect` | `scrollTop`, `scrollHeight`, `clientHeight`, `overflowY`. Whether the element scrolls, which you cannot infer from geometry alone. |
+| `scroll` | `reticle_look { action: "element" }` | `scrollTop`, `scrollHeight`, `clientHeight`, `overflowY`. Whether the element scrolls, which you cannot infer from geometry alone. |
 | `timeline_omitted` | `reticle_record { action: "stop" }` | The raw event timeline is not in the response. It says how many events there were and names the call that returns them, with the cursor filled in. |
 | `elided` | `reticle_act_and_wait` | Some diff arrays were capped. The count is real even when the list is trimmed, so a small array does not mean a quiet app. |
-| `colorTokens`, `themeScope` | `reticle_inspect` | Every design token matching a colour, not one arbitrary winner, and which theme the reading was taken under. The singular `colorToken` is `null` when several tokens share a colour, because naming one of them was the defect. |
-| `why` | `reticle_sessions`, when the list is empty | Why nothing is connected, and the next action. An empty list is never the end of the road. |
+| `colorTokens`, `themeScope` | `reticle_look { action: "element" }` | Every design token matching a colour, not one arbitrary winner, and which theme the reading was taken under. The singular `colorToken` is `null` when several tokens share a colour, because naming one of them was the defect. |
+| `why` | `reticle_session { action: "list" }`, when the list is empty | Why nothing is connected, and the next action. An empty list is never the end of the road. |
 
 **When a verdict comes back `unsettled`,** it now names what it was waiting for and what the window actually held. Read those before retrying: an `unknown` that explains itself is a retry with a better `until`, and one that does not is a dead end.
 
@@ -150,16 +160,16 @@ Recent additions, each of which answers a question agents were previously asking
 
 ## Start here
 
-0. Just ran `reticle init` / started the dev server? Poll `reticle_sessions()` until your tab appears. Readiness is server-internal now, so the first live call already blocks until the SDK connects.
-1. `reticle_sessions` finds the connected tab (omit `sessionId` if there's only one). **An empty list is not a dead end: read the `why` field.** It names which case this is (no app running, an app running that has never dialled this daemon, a project that never went through `init`, or a tab that closed) and the fix for each. Do not fall back to static reasoning until you have read it.
+0. Just ran `reticle init` / started the dev server? Poll `reticle_session({ action: "list" })` until your tab appears. Readiness is server-internal now, so the first live call already blocks until the SDK connects.
+1. `reticle_session { action: "list" }` finds the connected tab (omit `sessionId` if there's only one). **An empty list is not a dead end: read the `why` field.** It names which case this is (no app running, an app running that has never dialled this daemon, a project that never went through `init`, or a tab that closed) and the fix for each. Do not fall back to static reasoning until you have read it.
 2. `reticle_domain` learns the app BEFORE testing: the saved flows, what each asserts, and the **gaps** (declared signals/testids that no flow verifies, i.e. untested intent). Tells you what to test and where the real risk is without crawling the whole app. Falls back to `reticle_capabilities` for the raw testable surface (`testids`, `signals`, `stores`, `flows`).
 3. Run the loop: **look → act → observe → assert**, cross-checking the 4 layers on anything that matters.
 
 ## Token note
 
-- **Keep observation cheap.** Prefer `reticle_query` / scoped or `interactive` `reticle_snapshot` / `reticle_assert` over dumping the full tree. A full verify loop is ~100 tokens; see [token-efficiency.md](token-efficiency.md) (~73× leaner than full-tree snapshots).
-- **Re-look with `reticle_snapshot({ diff:true })`** after an action; it returns only what changed (`mode:delta`/`unchanged`), ~99% fewer tokens than a full re-snapshot and no stale tree to mis-read. Every snapshot/query result carries `cost:{ bytes, tokens }`, so re-scope before reading if it's large.
-- **Cap broad reads.** `reticle_query` takes `limit` (caps descriptors; reports `total`/`truncated`) and `count_only` (just the match count). `reticle_network` / `reticle_console` take `limit` (most-recent-N, reports `droppedOldest`) and carry the same `cost` hint, so a busy page or wide window never floods your context unnoticed.
+- **Keep observation cheap.** Prefer `reticle_look { action: "find" }` / scoped or `interactive` `reticle_look { action: "page" }` / `reticle_assert` over dumping the full tree. A full verify loop is ~100 tokens; see [token-efficiency.md](token-efficiency.md) (~73× leaner than full-tree snapshots).
+- **Re-look with `reticle_look({ action: "page", diff:true })`** after an action; it returns only what changed (`mode:delta`/`unchanged`), ~99% fewer tokens than a full re-snapshot and no stale tree to mis-read. Every snapshot/query result carries `cost:{ bytes, tokens }`, so re-scope before reading if it's large.
+- **Cap broad reads.** `reticle_look { action: "find" }` takes `limit` (caps descriptors; reports `total`/`truncated`) and `count_only` (just the match count). `reticle_observe { action: "network" }` / `reticle_observe { action: "console" }` take `limit` (most-recent-N, reports `droppedOldest`) and carry the same `cost` hint, so a busy page or wide window never floods your context unnoticed.
 - **A saved flow tells you if it's a real test.** `reticle_flow_save` returns `assertions.grade` (`asserted` / `presence-only` / `assertion-free`); if it's not `asserted`, add a consequence (`reticle_annotate` assert-signal/assert-net or a success-state) so it can't pass while broken. On replay, an ambiguous heal (two testids tie) is surfaced, never auto-applied. And an `apply` heal re-replays the rebound flow and **refuses to write** if the success consequence no longer fires (`status:consequence_broken`): it heals the locator, never the intent.
-- **Predicate schema is not bloated.** The recursive predicate DSL used by `reticle_assert` / `reticle_wait_for` / `reticle_act_and_wait` is **factored, not inlined**: when converted to the JSON Schema MCP sends, the predicate body is emitted **once** (~2.7k chars ≈ **~685 tokens** per tool) and recursion is handled by self-`$ref` (`#/properties/predicate`), with no per-recursion duplication. No action needed.
-- **One tool surface.** Reticle advertises the core set directly (sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state/inspect/feedback/session/verify: the whole detect loop, plus the file-pointer, the feedback channel, the handback, plus the one tool that CONCLUDES) PLUS two meta-tools that keep every other tool one call away: `reticle_tools` (discover; no args lists every tool name + summary, `names:[…]` loads full params on demand) and `reticle_run({ tool, args })` (invoke any tool by name; a top-level `sessionId` is forwarded to the target, so you need not nest it in `args`). So to record/replay a flow, call `reticle_run({ tool:"reticle_record", args:{ action:"start" }, sessionId })` (or `reticle_tools` first to see params). `reticle_verify` is advertised directly: `{ action:"flows" }` replays every saved flow with no model in the loop, and `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call. There is nothing to pick. `RETICLE_ADVERTISE_ALL_TOOLS=1` (read by the daemon at startup, so restart it) advertises everything with output schemas: a verification switch for suites, not a way to run agents. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.
+- **Predicate schema is not bloated.** The recursive predicate DSL used by `reticle_assert` / `reticle_assert { action: "wait" }` / `reticle_act_and_wait` is **factored, not inlined**: when converted to the JSON Schema MCP sends, the predicate body is emitted **once** (~2.7k chars ≈ **~685 tokens** per tool) and recursion is handled by self-`$ref` (`#/properties/predicate`), with no per-recursion duplication. No action needed.
+- **One tool surface, and a hatch behind it.** Reticle advertises navigate/act/act_and_wait/assert/look/observe/session/verify, plus `reticle_tools` and `reticle_run`. That is the whole detect loop, the file-pointer, the feedback channel, the handback, and the one tool that CONCLUDES, reached by an `action` argument rather than by a name each. `reticle_tools` discovers: no args lists every registered tool name and summary, `names:[…]` loads full params on demand. `reticle_run { tool, args }` then calls any of them, advertised or not, which is what keeps recording a flow, screenshots, visual diff, storage, network mocking and the clock reachable without spending a slot on each. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read at startup, so restart it) advertises the full table outright, with output schemas. `reticle_verify` is advertised: `{ action:"flows" }` replays every saved flow with no model in the loop, and `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.

package/docs/architecture.md

@@ -43,7 +43,7 @@ Reticle is a pnpm + Turborepo monorepo. The split is not cosmetic: each boundary
 | `@reticlehq/react` | the browser | The SDK **kit** you install in a browser app: re-exports the browser sensor (so one install gives both `reticle` and `install`) and maps a DOM node → React component → source `file:line` | Core works without the source-mapping half |
 | `@reticlehq/babel-plugin`, `@reticlehq/next`, `@reticlehq/vite-plugin` | build time | Stamp `data-reticle-source` for source mapping (and, for Vite, inject `connect()`) | Plain tooling |
 | `@reticlehq/electron` | Electron main process | Adapter for the desktop runtime: IPC observer, main-process capture | Desktop-only, outside the web gates |
-| `packages/tauri` (`reticle-tauri`) | Tauri (Rust) | Capture backend for the Tauri desktop runtime | Rust, outside every JS gate; compiled by CI's `rust`/`rust-macos` jobs |
+| `adapters/realm/tauri` (`reticle-tauri`) | Tauri (Rust) | Capture backend for the Tauri desktop runtime | Rust, outside every JS gate; compiled by CI's `rust`/`rust-macos` jobs |
 | `@reticlehq/test` | Node (dev dependency) | Spec runner + matchers used by CI's own test suites | Peer dependency on `vitest` |
 | `@reticlehq/eslint-plugin` | dev tooling | Repo-internal lint rule: a state change must fire a signal | Dev-only, never shipped in a user's bundle |
 
@@ -114,7 +114,8 @@ This is plain, reviewable, version-controllable data, not a black box.
 
 ## Open-core licensing (what's free, what's protected)
 
-- The embeddable **SDK** (`-core`, `-browser`, `-react`) is **Apache-2.0**, safe to ship inside your own app.
+- The **protocol and the rules** (`open-verification`, `@reticlehq/core`, `@reticlehq/engine`) are **Apache-2.0**. The part that decides a verdict is the part a sceptical reader most wants to audit, so it is the part with no licence in the way.
+- The embeddable **SDK** (`@reticlehq/browser`, `@reticlehq/react` and the build adapters) is **Apache-2.0**, safe to ship inside your own app.
 - The **server / CLI** is under the **Functional Source License (FSL-1.1, Apache-2.0 future)**: source-available, converts to Apache-2.0 over time.
 - Enterprise-only features live behind a license gate and are clearly separated.