@reticlehq/server 2.4.0 → 2.5.0

package/dist/version/peer-announce.d.ts

@@ -0,0 +1,4 @@
+export declare const PEER_VERSION_PARAM = "peerVersion";
+export declare const PEER_CONTRACT_PARAM = "peerContract";
+/** Compare an attaching agent process against this daemon, and queue the nudge when they disagree. */
+export declare function noteAgentPeer(version: string | null, contract: string | null): void;

package/dist/version/peer-announce.js

@@ -0,0 +1,30 @@
+/**
+ * How another Reticle PROCESS announces itself to the daemon.
+ *
+ * The SDK announces in HELLO and the CLI reads /status, but the MCP server an agent spawns had no
+ * announcement at all — and it is the piece the user actually hits: `npx @reticlehq/server mcp`
+ * resolves from a cache, so an agent can be running a months-old MCP package against a current
+ * daemon with nothing anywhere saying so.
+ *
+ * It rides the SSE connect the proxy already makes, as two query params. Query params rather than a
+ * new message because the connection happens before any protocol exchange, and because an older
+ * proxy that sends neither is handled correctly by describeSkew (absent contract + differing version
+ * = a build that predates the field).
+ */
+import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
+import { SERVER_VERSION } from './server-version.js';
+import { describeSkew, DAEMON_FIX, SkewPair } from './version-skew.js';
+import { noteVersionSkew } from './version-nudge.js';
+export const PEER_VERSION_PARAM = 'peerVersion';
+export const PEER_CONTRACT_PARAM = 'peerContract';
+/** Compare an attaching agent process against this daemon, and queue the nudge when they disagree. */
+export function noteAgentPeer(version, contract) {
+    const skew = describeSkew({
+        what: "the agent's MCP server",
+        version: version ?? undefined,
+        contract: contract ?? undefined,
+        fix: DAEMON_FIX,
+    }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
+    if (skew !== undefined)
+        noteVersionSkew(SkewPair.DAEMON, skew);
+}

package/dist/{server-version.js → version/server-version.js}

@@ -1,5 +1,9 @@
 import { createRequire } from 'node:module';
-const _pkg = createRequire(import.meta.url)('../package.json');
+// NOTE: a RUNTIME path, not an import — `tsc` does not check it and a file move will not rewrite
+// it. Two levels up because this file sits in `version/`: from `src/version/` and from
+// `dist/version/` alike, `../../package.json` is the package manifest. Moving this file again means
+// changing this line by hand; nothing else will tell you.
+const _pkg = createRequire(import.meta.url)('../../package.json');
 /** The Reticle server version, read from package.json at startup. */
 export const SERVER_VERSION = _pkg.version;
 /**

package/dist/version/version-nudge.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Getting skew in front of the AGENT, on whatever tool it happens to be calling.
+ *
+ * Every check built before this reported into a place nobody looks: SDK skew landed in
+ * `reticle_sessions.versionSkew`, which an agent driving a flow never calls, and daemon skew went to
+ * a CLI log line no agent reads. So an agent could work an entire session against a mismatched pair,
+ * watch tools behave oddly, and never be told the one fact that explains it.
+ *
+ * This is the delivery channel — the same one the update nudge uses, for the same reason: an
+ * out-of-date install is worth mentioning whatever the agent is doing. It rides out on the next tool
+ * result, then goes quiet until the skew CHANGES. Told, not nagged: a banner on every call is one an
+ * agent learns to skip, and it would cost those tokens on every call for the rest of the session.
+ */
+import type { SkewPair } from './version-skew.js';
+interface VersionSkewNudge {
+    pair: SkewPair;
+    action: string;
+}
+/**
+ * Record a skew for delivery. Re-arms only when the message DIFFERS from the one already delivered:
+ * a second tab on a third version is news; the same tab reconnecting is not.
+ */
+export declare function noteVersionSkew(pair: SkewPair, action: string): void;
+/** The next undelivered skew, once. */
+export declare function takeVersionSkew(): VersionSkewNudge | undefined;
+/** Tests only — drop the module state so each case starts clean. */
+export declare function resetVersionSkew(): void;
+export {};

package/dist/version/version-nudge.js

@@ -0,0 +1,40 @@
+/**
+ * Getting skew in front of the AGENT, on whatever tool it happens to be calling.
+ *
+ * Every check built before this reported into a place nobody looks: SDK skew landed in
+ * `reticle_sessions.versionSkew`, which an agent driving a flow never calls, and daemon skew went to
+ * a CLI log line no agent reads. So an agent could work an entire session against a mismatched pair,
+ * watch tools behave oddly, and never be told the one fact that explains it.
+ *
+ * This is the delivery channel — the same one the update nudge uses, for the same reason: an
+ * out-of-date install is worth mentioning whatever the agent is doing. It rides out on the next tool
+ * result, then goes quiet until the skew CHANGES. Told, not nagged: a banner on every call is one an
+ * agent learns to skip, and it would cost those tokens on every call for the rest of the session.
+ */
+/** Pending per pair — the SDK and the daemon are different upgrades and each is worth saying once. */
+const pending = new Map();
+/** The last message delivered for each pair, so the same skew is never repeated. */
+const delivered = new Map();
+/**
+ * Record a skew for delivery. Re-arms only when the message DIFFERS from the one already delivered:
+ * a second tab on a third version is news; the same tab reconnecting is not.
+ */
+export function noteVersionSkew(pair, action) {
+    if (delivered.get(pair) === action)
+        return;
+    pending.set(pair, action);
+}
+/** The next undelivered skew, once. */
+export function takeVersionSkew() {
+    for (const [pair, action] of pending) {
+        pending.delete(pair);
+        delivered.set(pair, action);
+        return { pair, action };
+    }
+    return undefined;
+}
+/** Tests only — drop the module state so each case starts clean. */
+export function resetVersionSkew() {
+    pending.clear();
+    delivered.clear();
+}

package/dist/version/version-skew.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Does this peer speak our contract? The daemon is the only thing that asks.
+ *
+ * Reticle is three separately-installed pieces — the SDK in the page, this daemon, and the MCP
+ * server the agent spawns — upgraded independently and therefore drifting constantly. Each pair
+ * fails the same silent way: `protocolVersion` still matches, the connection succeeds, and only
+ * BEHAVIOUR disagrees. A user hit exactly that with a 2.2.1 SDK against a 2.3.0 daemon and saw a
+ * bare `-32000` with nothing on either side naming a version.
+ *
+ * Two decisions shape this file.
+ *
+ * The daemon is the SINGLE judge. Every piece announces itself at a connect it already makes — the
+ * SDK in HELLO, the CLI and the MCP server over /status — and comparing happens here, once. Three
+ * independent pairwise checks would be three copies to keep in step and three separate complaints
+ * about one upgrade; a table in one place can say what is actually true: which pieces disagree, and
+ * which one is behind.
+ *
+ * The signal is the CONTRACT FINGERPRINT, not the version. Version equality is wrong in both
+ * directions: it fires on 2.4.0-vs-2.4.1 where nothing changed — so every patch release makes every
+ * un-upgraded app cry wolf, and the warning becomes noise — and it cannot fire at all for two
+ * different BUILDS of one version number, which is exactly what a stale daemon and a cached npx
+ * install are. The fingerprint is derived from core's wire vocabulary, so it moves when a name on
+ * the wire changes and stays put when internals do. Versions still ride along, because they are what
+ * a human acts on.
+ */
+/** Which pair disagreed. Named so the nudge can report each independently. */
+export declare const SkewPair: {
+    /** The SDK in the page vs this daemon. */
+    readonly SDK: "sdk";
+    /** Another Reticle process — a CLI, or the MCP server an agent spawned — vs this daemon. */
+    readonly DAEMON: "daemon";
+};
+export type SkewPair = (typeof SkewPair)[keyof typeof SkewPair];
+/** What a piece says about itself when it connects. */
+export interface PeerIdentity {
+    /** Human-readable subject for the message: "the page", "the daemon on this port". */
+    what: string;
+    /** Package version, when the peer supplied one. Undefined on a hand-wired connect. */
+    version: string | undefined;
+    /** Contract fingerprint. Undefined means the peer predates the field — itself evidence of age. */
+    contract: string | undefined;
+    /** What the human runs to bring this piece into line. */
+    fix: string;
+}
+/** Everything a build knows about itself. */
+interface SelfIdentity {
+    version: string;
+    contract: string;
+}
+/**
+ * The one sentence to tell the agent, or undefined when the pair agrees.
+ *
+ * Silent when the fingerprints MATCH, whatever the versions say — that is the point: a patch bump
+ * that changed no wire name is not skew, and warning about it is how a real warning gets ignored.
+ *
+ * A peer with no fingerprint is treated as skewed ONLY when its version also differs from ours: the
+ * field is absent exactly on builds that predate it, so "no fingerprint AND a different version" is
+ * a build provably older than this daemon. With neither signal there is nothing to go on, and
+ * inventing a warning would be as dishonest as staying silent about a real one.
+ */
+export declare function describeSkew(peer: PeerIdentity, self: SelfIdentity): string | undefined;
+/** The fix line for a page whose SDK disagrees with this daemon. */
+export declare function sdkFix(daemonVersion: string): string;
+/** The fix line for another Reticle process that disagrees with the daemon it attached to. */
+export declare const DAEMON_FIX: string;
+export {};

package/dist/version/version-skew.js

@@ -0,0 +1,71 @@
+/**
+ * Does this peer speak our contract? The daemon is the only thing that asks.
+ *
+ * Reticle is three separately-installed pieces — the SDK in the page, this daemon, and the MCP
+ * server the agent spawns — upgraded independently and therefore drifting constantly. Each pair
+ * fails the same silent way: `protocolVersion` still matches, the connection succeeds, and only
+ * BEHAVIOUR disagrees. A user hit exactly that with a 2.2.1 SDK against a 2.3.0 daemon and saw a
+ * bare `-32000` with nothing on either side naming a version.
+ *
+ * Two decisions shape this file.
+ *
+ * The daemon is the SINGLE judge. Every piece announces itself at a connect it already makes — the
+ * SDK in HELLO, the CLI and the MCP server over /status — and comparing happens here, once. Three
+ * independent pairwise checks would be three copies to keep in step and three separate complaints
+ * about one upgrade; a table in one place can say what is actually true: which pieces disagree, and
+ * which one is behind.
+ *
+ * The signal is the CONTRACT FINGERPRINT, not the version. Version equality is wrong in both
+ * directions: it fires on 2.4.0-vs-2.4.1 where nothing changed — so every patch release makes every
+ * un-upgraded app cry wolf, and the warning becomes noise — and it cannot fire at all for two
+ * different BUILDS of one version number, which is exactly what a stale daemon and a cached npx
+ * install are. The fingerprint is derived from core's wire vocabulary, so it moves when a name on
+ * the wire changes and stays put when internals do. Versions still ride along, because they are what
+ * a human acts on.
+ */
+/** Which pair disagreed. Named so the nudge can report each independently. */
+export const SkewPair = {
+    /** The SDK in the page vs this daemon. */
+    SDK: 'sdk',
+    /** Another Reticle process — a CLI, or the MCP server an agent spawned — vs this daemon. */
+    DAEMON: 'daemon',
+};
+function versionPhrase(peer, self) {
+    return peer.version === undefined
+        ? `${peer.what} is on an unknown version; this daemon is ${self.version}`
+        : `${peer.what} is ${peer.version}; this daemon is ${self.version}`;
+}
+/**
+ * The one sentence to tell the agent, or undefined when the pair agrees.
+ *
+ * Silent when the fingerprints MATCH, whatever the versions say — that is the point: a patch bump
+ * that changed no wire name is not skew, and warning about it is how a real warning gets ignored.
+ *
+ * A peer with no fingerprint is treated as skewed ONLY when its version also differs from ours: the
+ * field is absent exactly on builds that predate it, so "no fingerprint AND a different version" is
+ * a build provably older than this daemon. With neither signal there is nothing to go on, and
+ * inventing a warning would be as dishonest as staying silent about a real one.
+ */
+export function describeSkew(peer, self) {
+    if (peer.contract !== undefined && peer.contract === self.contract)
+        return undefined;
+    if (peer.contract === undefined) {
+        if (peer.version === undefined || peer.version === self.version)
+            return undefined;
+        return (`version skew: ${versionPhrase(peer, self)}, and it is too old to report which wire contract ` +
+            `it speaks. They connect anyway and then disagree about behaviour, which usually surfaces as ` +
+            `a bare -32000 with nothing naming a version. ${peer.fix}`);
+    }
+    return (`version skew: ${versionPhrase(peer, self)}, and they speak DIFFERENT wire contracts ` +
+        `(${peer.contract} vs ${self.contract}) — so this is a real mismatch, not a harmless patch ` +
+        `difference. Tools will behave in ways neither side reports. ${peer.fix}`);
+}
+/** The fix line for a page whose SDK disagrees with this daemon. */
+export function sdkFix(daemonVersion) {
+    return (`Tell the human to install the matching SDK (\`npm i -D @reticlehq/react@${daemonVersion}\`) ` +
+        'or run `reticle update`, then restart their dev server so the page reloads with it.');
+}
+/** The fix line for another Reticle process that disagrees with the daemon it attached to. */
+export const DAEMON_FIX = 'A daemon outlives the agents attached to it, so it keeps serving its OWN code until it restarts ' +
+    '— anything fixed in the newer package is simply absent. Run `reticle stop` and retry to replace ' +
+    'it (other agents on that daemon will need to reconnect).';

package/dist/visual/visual-diff.js

@@ -32,7 +32,7 @@ function changedRegion(out, width, height) {
         for (let x = 0; x < width; x += 1) {
             const i = (y * width + x) * RGBA;
             // pixelmatch marks a changed pixel solid red (default diffColor) at full alpha.
-            if (out[i] === 255 && out[i + 1] === 0 && out[i + 2] === 0 && out[i + 3] === 255) {
+            if (255 === out[i] && 0 === out[i + 1] && 0 === out[i + 2] && 255 === out[i + 3]) {
                 if (x < minX)
                     minX = x;
                 if (y < minY)
@@ -80,7 +80,7 @@ export async function diffPng(baselineBytes, currentBytes, opts = {}) {
     const threshold = opts.threshold ?? VISUAL_PIXEL_THRESHOLD;
     const changedPixels = pixelmatch(a.data, b.data, out.data, width, height, { threshold });
     const totalPixels = width * height;
-    const ratio = totalPixels === 0 ? 0 : changedPixels / totalPixels;
+    const ratio = 0 === totalPixels ? 0 : changedPixels / totalPixels;
     const maxRatio = opts.maxRatio ?? 0;
     const region = changedPixels > 0 ? changedRegion(out.data, width, height) : undefined;
     const result = {

package/dist/visual/visual-tools.js

@@ -16,7 +16,7 @@ const rectShape = z.object({
 });
 function screenshotProvider(deps) {
     const p = deps.realInput;
-    return p !== undefined && typeof p.screenshot === 'function'
+    return p !== undefined && 'function' === typeof p.screenshot
         ? p
         : undefined;
 }
@@ -55,7 +55,7 @@ async function buildOpts(deps, sessionId, args) {
         if (box !== undefined)
             return { clip: box };
     }
-    return args['fullPage'] === true ? { fullPage: true } : {};
+    return true === args['fullPage'] ? { fullPage: true } : {};
 }
 /**
  * Ask the desktop shell to photograph its own window.
@@ -110,7 +110,7 @@ function isCapturePath(path) {
 function isCompletePng(bytes) {
     if (bytes.byteLength < 12)
         return false;
-    return bytes.subarray(bytes.byteLength - 8, bytes.byteLength - 4).toString('ascii') === 'IEND';
+    return 'IEND' === bytes.subarray(bytes.byteLength - 8, bytes.byteLength - 4).toString('ascii');
 }
 /**
  * Get pixels for a session, by whichever route exists.
@@ -137,7 +137,7 @@ async function capture(deps, sessionId, args) {
         if (png !== undefined)
             return { png };
     }
-    const desktop = await desktopCapture(deps, sessionId, args['fullPage'] === true);
+    const desktop = await desktopCapture(deps, sessionId, true === args['fullPage']);
     if (desktop.png !== undefined)
         return { png: desktop.png };
     if (desktop.reason !== undefined)

package/docs/agent-cheatsheet.md

@@ -0,0 +1,85 @@
+# Reticle — agent cheat-sheet
+
+One screen to get fluent. Reticle is the **proof layer for AI agents** — no screenshots, no vision model, evidence not prose. Everything below returns structured data. Full guide: [usage.md](usage.md).
+
+## The core loop: look → act → observe → assert
+
+| Verb | Tool | One-liner |
+| --- | --- | --- |
+| **look** | `reticle_snapshot` / `reticle_query` | See the page (semantic tree) / find one specific element. |
+| **act** | `reticle_act` / `reticle_act_and_wait` | Click/fill a `ref` / act + wait for a predicate in one hop. |
+| **observe** | `reticle_observe` / `reticle_wait_for` | Everything the app did after `since` / block until true. |
+| **assert** | `reticle_assert` | Evaluate a predicate → `{ pass, evidence, failureReason? }`. The end of every loop. |
+
+`reticle_act` returns a `since` cursor — pass it to `reticle_observe({ since })` to scope the window. Elements are addressed by stable refs (`e7`) from `snapshot`/`query`; they re-resolve across re-renders.
+
+**`assert`/`wait_for` are auto-scoped to your last act.** By default they only count events buffered _since_ the most recent act, so a stale signal from a previous step can't fake a pass — pass an explicit `since` to override. **Clicks run the code, not pixels:** `reticle_act` click fires the full pointer sequence on the element (no coordinate gesture for the HUD to intercept), reports `occluded:true` when something covers the target, and stays synthetic even with CDP configured (use `args:{ native:true }` for a trusted native click).
+
+**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 } })`.
+- 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.
+
+**Assert a consequence, not just presence.** `{ signal }` / `{ net }` prove the feature actually did something; `{ element }` / `{ text }` only prove something is on screen — which a stale render or a locator healed to the wrong element can fake. A _passing_ presence-only `reticle_assert` returns `advice` nudging you to a consequence; heed it on anything that matters.
+
+## The 4-layer cross-check — never trust a green the state contradicts
+
+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? |
+| **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? |
+
+> **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.
+
+> Store reads (`reticle_state`) are the reliable path; the DOM can lie (optimistic UI, stale render).
+
+**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.
+
+**Charts report their own geometry faults.** Any element descriptor containing a broken plot carries `chart: [{ kind, tag, attr, sample }]` — `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.
+
+## Core tool set
+
+The tools advertised DIRECTLY — what you'll use 90% of the time. Everything else is one `reticle_run` away (see Token note below).
+
+`reticle_sessions` · `reticle_navigate` · `reticle_snapshot` · `reticle_query` · `reticle_act` · `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).
+
+Frequently useful but NOT core, so reach them through `reticle_run({ tool, args })`: `reticle_domain` (learn the app + gaps), `reticle_capabilities` (the app's declared testable surface), `reticle_baseline {action:"diff"}`, `reticle_project` (run history).
+
+**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_crawl` clicks them all and reports anomalies — **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to` — 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 mode), 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. |
+| **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`. |
+
+> `reticle_project` / `project.json` are the **run-history layer**. flows answer "does the journey still work?"; baselines answer "did the structure change?"; project.json answers "is this run consistent with prior runs?".
+
+**Visual layer (opt-in).** `reticle_screenshot` saves a PNG baseline to `.reticle/visual/<name>.png`; `reticle_visual_diff` perceptually compares the live page to it (`{ masks }` to ignore volatile regions, `{ maxRatio }` tolerance) → `{ matched, changedPixels, ratio, region, diffPath }`. It answers "does it **look** right" — complementary to the behavioral layers, never a replacement. Both need a **driven browser** (`reticle drive <url>` / `RETICLE_CDP_URL`); without one they return `{ ok:false, reason:"no-visual-provider" }` (the always-on SDK ships no screenshotter).
+
+## 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` — find the connected tab (omit `sessionId` if there's only one).
+2. `reticle_domain` — learn the app BEFORE testing: the saved flows, what each asserts, and the **gaps** (declared signals/testids that no flow verifies — 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 }` — 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.
+- **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`) — 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 — the whole detect loop, plus the file-pointer, the feedback channel and the handback) 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/verify a flow, call `reticle_run({ tool:"reticle_flow_verify", sessionId })` (or `reticle_tools` first to see params). 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.

package/docs/architecture.md

@@ -0,0 +1,113 @@
+# Reticle architecture — how it works and why it's built this way
+
+> For engineers evaluating Reticle, integrating it at scale, or contributing. It explains the moving parts, the data flow, and the design decisions behind them. If you just want to get running, start with [getting-started.md](getting-started.md); come back here when you want to know _why_.
+
+---
+
+## The one-paragraph model
+
+Your app, in dev, embeds a tiny **SDK** that instruments the page (DOM, network, console, routing, framework state) and opens a WebSocket to a local **bridge**. The bridge runs inside the Reticle **server**, which also exposes an **MCP server** — the standard protocol AI agents speak. Your coding agent calls MCP tools (`reticle_query`, `reticle_act`, `reticle_assert`, …); the server turns them into commands over the WebSocket; the SDK executes them in the page and streams back structured events. The agent thus **looks, acts, observes, and asserts** on the real running app — never on a screenshot.
+
+```
+┌─────────────────┐     MCP (stdio/SSE)     ┌──────────────────────────┐     WebSocket      ┌────────────────────┐
+│   AI agent      │ ──────────────────────► │   @reticlehq/server     │ ◄────────────────► │  @reticlehq/browser│
+│ (Claude Code,   │   reticle_query/act/...    │   bridge + MCP + CLI      │   commands/events  │  (SDK in your app)  │
+│  Cursor, ...)   │ ◄────────────────────── │   (Node)                 │                    │   (the DOM)         │
+└─────────────────┘     tool results        └──────────────────────────┘                    └────────────────────┘
+                                                       │
+                                              reads/writes .reticle/  (flows, baselines, runs, contract)
+```
+
+---
+
+## The packages (and the boundaries between them)
+
+Reticle is a pnpm + Turborepo monorepo. The split is not cosmetic — each boundary enforces a rule.
+
+| Package | Runs in | Responsibility | Hard rule |
+| --- | --- | --- | --- |
+| `@reticlehq/core` | both | The **wire contract**: every constant + zod schema crossing any boundary | Depends only on `zod` |
+| `@reticlehq/browser` | the browser | Instrument the page; execute commands; emit events | Never imports Node APIs |
+| `@reticlehq/server` | Node | The bridge, the MCP server, the `reticle` CLI, flow/run storage | Never imports DOM APIs |
+| `@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 |
+
+> Note: pre-2.0, `@reticlehq/core` was a single umbrella package that re-exported all of the above under subpaths. In 2.0 the umbrella was retired and `@reticlehq/core` became the bottom-of-graph wire contract.
+
+**Why core-as-contract matters:** because the browser and the server are two different runtimes (a DOM and a Node process) that must agree exactly on every message, the temptation is to inline a string like `"net.request"` in both. That's how drift and silent breakage start. Instead, every such string and shape lives once in `@reticlehq/core` as a named constant + a zod schema. The browser and server both import it; neither can invent a message the other doesn't understand. The server zod-parses **every** inbound WebSocket message — malformed input closes the socket rather than flowing into logic.
+
+---
+
+## The data flow, end to end
+
+1. **Connect.** In dev, your app calls `reticle.connect({ session })`. The SDK opens a WebSocket to the bridge (`ws://localhost:4400/reticle` by default) and sends a `HELLO` carrying the session id, protocol version, and (if configured) a pairing token. Each browser tab uses `SESSION_AUTO` — a unique id — so multiple apps/tabs never collide.
+2. **Capture.** The SDK installs observers: a `MutationObserver` for DOM changes, wrappers around `fetch`/`XHR` for network, a console hook, a history hook for routing, and registries the app opts into (`registerStore`, `registerCapabilities`, `reticle.signal`). Events flow into a bounded **ring buffer** — recent history is always available, memory is capped.
+3. **Look / act.** The agent calls an MCP tool. `reticle_query` finds an element by role/text/testid/ component and returns a stable **ref**. `reticle_act` dispatches an action against that ref and returns an **effect** report (did it land, did the DOM mutate, did focus move…). The server sends the command over the WebSocket; the SDK runs it and replies.
+4. **Observe.** After an action, the agent reads what happened — `reticle_network`, `reticle_console`, `reticle_state`, or the reaction digest from `reticle_act_and_wait`. The server pulls the relevant slice of the ring buffer (scoped to a cursor so stale events can't leak in) and returns a compact summary.
+5. **Assert.** `reticle_assert` (and a flow's declared `success`) evaluates a **predicate** over program truth — a network call that returned 200, a store value, a `signal` the app emitted — not just "an element exists." This is the difference between "looks done" and "is done."
+
+---
+
+## The four design decisions that define Reticle
+
+### 1. Assert the consequence, not the appearance
+
+Most agent-browser tools can confirm "an element matching X is present." That's the weakest possible oracle: a wrong or healed-to-wrong element satisfies it, and the regression ships anyway. Reticle grades evidence in tiers:
+
+- **Tier 1 — an app signal** (`reticle.signal('order:placed')`): the strongest, because a wrong element can't fake it. Available when the app emits it (a ~30-second opt-in).
+- **Tier 2 — network + route + state**: a POST returned 200, the URL changed, a store value updated. Strong, and works on most SPAs with no setup.
+- **Tier 3 — DOM/text presence**: the weak fallback Reticle nudges _away_ from.
+
+Reticle is honest about which tier a given assertion used, so "green" carries its own confidence.
+
+### 2. Structured reads, not screenshots
+
+A screenshot is ~1,365 image tokens per look, slow, non-deterministic, and **blind to everything non-visual** — the failed request, the console error, the route that didn't change. Reticle reads the accessibility tree, the network log, the console, and framework state as compact structured data. That's an order of magnitude cheaper _and_ it sees the bugs pixels can't. See [benchmarks.md](benchmarks.md) for the measured comparison.
+
+### 3. Record once, replay deterministically
+
+The same verification runs over and over — every commit, every CI run. Reticle records a **flow** once, then replays it with **no AI model**: it re-resolves each element's durable anchor against the live DOM and re-asserts the declared consequence. A CI gate diffs the verdict exactly, at ~0% flake, for a couple hundred tokens — versus an agent re-driving the whole flow with the model every time. Self- healing rebinds a drifted anchor **only if the consequence still fires**, so it never "heals to the wrong element and ships the regression."
+
+### 4. Dev-only, localhost-only, your app data stays local
+
+The SDK is tree-shaken out of production builds and connects only to a local bridge. The bridge binds to loopback by default; exposing it beyond localhost _requires_ a pairing token (the server refuses to bind a non-loopback host without one). Every environment variable that gates a security control is a single named constant, so a typo can't silently disable auth. Nothing from the app under test — no DOM, network, console, state, or source — ever leaves your machine. The CLI reports anonymous, opt-out usage metrics only (a random id + event names like `invoke`/`session_start`; no code, no PII — see [telemetry](telemetry.md)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. The one thing that carries free text is feedback you or your agent deliberately send (`reticle feedback` / `reticle_feedback`) — never collected passively, redacted before sending, and separately disabled with `RETICLE_FEEDBACK=0`.
+
+---
+
+## State on disk: the `.reticle/` workspace
+
+The server persists project state under `.reticle/` in your repo:
+
+- **`flows/`** — recorded, replayable flows (the golden journeys).
+- **`baselines/`** — saved snapshots for diffing.
+- **`runs/`** — verification run artifacts (the evidence trail; writes are atomic and bounded so a crash never leaves a half-written artifact, and the directory is pruned).
+- **the capabilities contract** — the testids/signals/stores/flows the app advertises, frozen under a version so the public artifact can't break silently.
+
+This is plain, reviewable, version-controllable data — not a black box.
+
+---
+
+## Running at scale (multiple apps, multiple projects)
+
+- **Multiple apps / tabs on one bridge:** fine — each connection has a unique `SESSION_AUTO` id; a tool call targets the focused/most-recent session, or you pass an explicit `sessionId`.
+- **Multiple isolated projects:** give each project its own bridge port via `RETICLE_PORT` (set it in the MCP config and dial the same port from the app). A port already in use fails fast with a clear error rather than hanging. See [getting-started.md → Running multiple apps](getting-started.md#running-multiple-apps-at-once).
+- **CI / no MCP:** `reticle verify <url>` replays the saved flows headlessly and exits non-zero on failure — the same verdict artifact the MCP path produces, with no agent in the loop.
+
+---
+
+## 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 **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.
+
+See [LICENSE](../LICENSE) and each package's own `LICENSE` file. The licensing _mechanism_ is open and inspectable; activation is offline (no phone-home).
+
+---
+
+## Where to go next
+
+- [getting-started.md](getting-started.md) — wire Reticle into your app in a couple of minutes.
+- [benchmarks.md](benchmarks.md) — how we measure, and the honest results vs the alternatives.
+- [usage.md](usage.md) — the full tool reference and advanced modes.
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — the development loop and the rules.