@reticlehq/server 2.11.0 → 2.12.0

package/dist/tools/tool-surface.js

@@ -70,6 +70,45 @@ export const TOOL_SURFACE = {
      * supplies the evidence the surface would otherwise have to go and find.
      */
     VERIFY: 'verify',
+    /**
+     * EXPERIMENTAL, opt-in, and UNDER MEASUREMENT. Not a recommendation, and not on a path to becoming
+     * the default until it has a number of its own.
+     *
+     * It exists because of the finding recorded on VERIFY above, read forwards instead of backwards.
+     * That surface cut the bill 37% and TRIPLED false alarms, and the five new false alarms were not
+     * scattered: every one of them was a defect whose evidence lives in `reticle_state`,
+     * `reticle_network` or `reticle_observe`. So the token saving and the accuracy loss came from two
+     * different cuts, and only one of them has to be paid for. `lean` keeps every observation tool and
+     * cuts the rest.
+     *
+     * What stays, and why each one is not a candidate for removal:
+     *   SNAPSHOT / QUERY   look. Without them the agent cannot name an element it did not already know.
+     *   STATE / NETWORK / CONSOLE / OBSERVE   the four evidence tools. Dropping these is the MEASURED
+     *                      cause of the tripled false-alarm rate. They are the point of the profile.
+     *   ACT_AND_WAIT       the only tool that acts AND returns a verdict. Omitting `until` makes it
+     *                      act-then-settle, which is what `reticle_act` does, so `act` is redundant here.
+     *   ASSERT             the only way to get a verdict WITHOUT acting. `act_and_wait` requires an
+     *                      `action`, so this is a capability it genuinely cannot express, not a synonym.
+     *
+     * What goes, and what it costs (one `reticle_run` hop each — `unadvertisedToolHelp` hands the agent
+     * the exact call, so a dropped name never comes back as "not found"):
+     *   ACT                subsumed: `act_and_wait` with `until` omitted is act-then-settle.
+     *   WAIT_FOR           subsumed: `act_and_wait { until }` takes the same PredicateSchema.
+     *   ACT_SEQUENCE       batching is a cost optimisation on top of a surface built to be cheap.
+     *   NAVIGATE           once per run, not once per turn — the wrong thing to pay for every turn.
+     *   SESSIONS           the CLI answers this (`reticle status`) without spending any turn budget.
+     *   INSPECT            fix-side, not verdict-side: it is called once a bug is FOUND, so its hop is
+     *                      paid once per finding rather than once per turn. Nothing else maps a node to
+     *                      a source file, which is why it is a hop and not a deletion.
+     *   SESSION            the lease block and the pause hint name it in prose, which is what made it
+     *                      load-bearing on the default surface. Under a trimmed surface the
+     *                      unadvertised-tool help turns that into a working `reticle_run` call.
+     *   FEEDBACK           the one drop with a KNOWN CEILING: an unadvertised feedback channel collects
+     *                      little to nothing, so a long-lived profile must not ship without it. Acceptable
+     *                      only because this profile is opt-in and short-lived by construction; if it
+     *                      ever stops being an experiment, feedback comes back first.
+     */
+    LEAN: 'lean',
 };
 /**
  * The switch that turns on the full, output-schema-carrying surface. A boolean, not a menu.
@@ -79,7 +118,7 @@ export const TOOL_SURFACE = {
  */
 export const ADVERTISE_ALL_ENV = 'RETICLE_ADVERTISE_ALL_TOOLS';
 /** Opt into the smallest verdict-capable surface. Read by the DAEMON at startup, like the others. */
-export const VERIFY_SURFACE_ENV = 'RETICLE_VERIFY_SURFACE';
+const VERIFY_SURFACE_ENV = 'RETICLE_VERIFY_SURFACE';
 /**
  * The retired setting, still read so nobody's shell profile breaks.
  *
@@ -185,6 +224,17 @@ export const CORE_TOOL_NAMES = new Set([
  * 48 by itself can push a user's other servers out or be dropped wholesale. The budget is a count,
  * so no amount of trimming parameter prose buys anything back — only advertising fewer names does.
  *
+ * That is true of the COUNT cap and false of everything else, which is worth separating here before
+ * somebody reads it as "prose is free". Measured against two competitor MCP servers on the same
+ * agent loop: this server advertises the FEWEST tools of the three and ships the HEAVIEST schema
+ * block, and 83% of that weight is parameter descriptions, not tool descriptions. The block is
+ * re-sent every turn, so it is multiplied by turn count before one byte of evidence is counted, and
+ * it was most of the gap in that run.
+ *
+ * Which does NOT license trimming by eye. Those descriptions are what make a tool get called
+ * correctly, and one malformed call costs a whole extra turn — more than the bytes saved. The
+ * outcome to measure is turn count and error rate, not size.
+ *
  * Everything omitted stays in the registry, stays catalogued by `reticle_tools`, and stays callable
  * by name through `reticle_run { tool, args }`. The cost is one discovery hop on the cold tail, which
  * is the same trade the default surface has always made, applied one level further out.
@@ -206,6 +256,13 @@ export const EXTENDED_TOOL_NAMES = new Set([
     ReticleTool.CAPABILITIES,
     ReticleTool.FLOW_SAVE,
     ReticleTool.FLOW_REPLAY,
+    // New and unproven, so it does not take a default-surface slot under the cap. Same terms the
+    // capabilities demotion set: reachable in one reticle_run hop by any agent that wants it.
+    ReticleTool.INTENT,
+    // Same terms again, plus one argument specific to it: its caller is BY CONSTRUCTION an agent that
+    // just lost its context and is re-reading the tool list, so the discovery hop it costs is a call
+    // that caller was already going to make. See context-tools.ts for the full argument.
+    ReticleTool.CONTEXT,
     ReticleTool.RECORD,
     ReticleTool.SCREENSHOT,
     ReticleTool.VISUAL_DIFF,
@@ -220,7 +277,53 @@ export const EXTENDED_TOOL_NAMES = new Set([
  * everything else. `act_and_wait` can resolve its own target, so no query tool is needed to name an
  * element — that round trip was half the token cost of a verification.
  */
-export const VERIFY_TOOL_NAMES = new Set([ReticleTool.ACT_AND_WAIT]);
+const VERIFY_TOOL_NAMES = new Set([ReticleTool.ACT_AND_WAIT]);
+/**
+ * The lean surface: look, observe, act-with-a-verdict, assert. Pinned by lean-surface.test.ts,
+ * because an experiment whose independent variable drifts mid-flight measures nothing. Every
+ * inclusion and every exclusion is argued at TOOL_SURFACE.LEAN.
+ *
+ * ## MEASURED: it is cheaper and less correct. Do not promote it to the default.
+ *
+ * Run as its own arm of the fix-and-verify benchmark — same five bugs, same model, same budget, the
+ * full surface as its control:
+ *
+ * | | full surface | lean |
+ * |---|---|---|
+ * | bugs fixed | **5/5** | **3/5** |
+ * | FALSE GREENS | **0** | **1** |
+ *
+ * The false green is the finding, and it is the first this benchmark has ever produced. On
+ * `broken-form-validation` the lean agent finished in SIX turns and 62k tokens — the cheapest cell
+ * of the whole run, a fifth of what the full surface spent — edited the file, took one snapshot,
+ * and ended with a hypothetical walkthrough: "Enter spaces + valid name -> spaces are trimmed,
+ * valid part is used. VERDICT: FIXED". The submit button was still enabled for a whitespace-only
+ * service. It reasoned about what its own code would now do instead of driving it, which is exactly
+ * the failure this product exists to catch, produced by our own surface.
+ *
+ * The other loss has the same root from the other side. On `cross-component-regression` the agent
+ * called `reticle_tools` three times and `reticle_run` eight, saying "since Reticle isn't
+ * connecting, let me see what reticle_tools offers" — it spent the run hunting for capabilities
+ * this surface does not advertise instead of using them, and never fixed the bug.
+ *
+ * That is the same result the `verify` surface already recorded — dropping the observation tools
+ * TRIPLED false alarms — arriving from the other direction: strip the surface and the agent stops
+ * verifying, then claims anyway. The known ceiling written here was that `reticle_feedback` goes
+ * uncollected. This is a bigger one and it was not predicted.
+ *
+ * It stays opt-in and it stays measured. The one thing it genuinely bought — the ceiling-bound cell
+ * halved, 30 turns to 14 — is not worth a verdict that lies, because the product is the verdict.
+ */
+export const LEAN_TOOL_NAMES = new Set([
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.ASSERT,
+    ReticleTool.OBSERVE,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.STATE,
+]);
 /** Is the truthy form of a boolean env var set? `1`, `true`, `yes` — anything else is off. */
 function envFlagOn(raw) {
     if (raw === undefined)
@@ -235,6 +338,8 @@ function envFlagOn(raw) {
  * switch decides, and the retired setting is honoured last so an old shell profile still works.
  */
 export function resolveToolSurface(explicit) {
+    if (explicit === TOOL_SURFACE.LEAN)
+        return TOOL_SURFACE.LEAN;
     if (explicit === TOOL_SURFACE.VERIFY)
         return TOOL_SURFACE.VERIFY;
     if (explicit === TOOL_SURFACE.ALL)
@@ -244,6 +349,11 @@ export function resolveToolSurface(explicit) {
     const retiredExplicit = explicit === undefined ? undefined : RETIRED_PROFILE_VALUES[explicit];
     if (retiredExplicit !== undefined)
         return retiredExplicit;
+    // The one LIVE value of the otherwise-retired setting. It rides there rather than on a switch of
+    // its own because the experiment is an A/B between two surfaces, and a boolean cannot name an arm.
+    if (TOOL_SURFACE.LEAN === process.env[TOOL_PROFILE_ENV]?.trim().toLowerCase()) {
+        return TOOL_SURFACE.LEAN;
+    }
     if (envFlagOn(process.env[VERIFY_SURFACE_ENV]))
         return TOOL_SURFACE.VERIFY;
     if (envFlagOn(process.env[ADVERTISE_ALL_ENV]))
@@ -262,6 +372,14 @@ export function resolveToolSurface(explicit) {
  */
 export function describeToolSurface(active, requested) {
     const retired = requested ?? process.env[TOOL_PROFILE_ENV];
+    // `lean` is the one value of this setting that is NOT retired. Reporting it as retired would tell
+    // an agent its arm did not take, which on an A/B is worse than saying nothing.
+    if (TOOL_SURFACE.LEAN === active) {
+        return {
+            active,
+            source: `${TOOL_PROFILE_ENV}=${TOOL_SURFACE.LEAN} — an EXPERIMENTAL surface under measurement; unadvertised tools stay callable via ${ReticleTool.RUN}`,
+        };
+    }
     if (retired !== undefined && retired in RETIRED_PROFILE_VALUES) {
         return {
             active,
@@ -293,6 +411,8 @@ export function filterTools(tools, surface) {
     // interesting thing about the `core` PROFILE, whose only distinction was a second name for this.
     if (surface === TOOL_SURFACE.VERIFY)
         return tools.filter((t) => VERIFY_TOOL_NAMES.has(t.name));
+    if (surface === TOOL_SURFACE.LEAN)
+        return tools.filter((t) => LEAN_TOOL_NAMES.has(t.name));
     if (surface === TOOL_SURFACE.DEFAULT)
         return tools.filter((t) => CORE_TOOL_NAMES.has(t.name));
     // `all` is the extended surface, not the whole registry — the cap is a hard budget shared with

package/dist/tools/tools.js

@@ -21,11 +21,13 @@ import { CONTRACT_TOOLS } from './contract-tools.js';
 import { DOMAIN_TOOLS } from '../domain/domain-tools.js';
 import { BROWSER_TOOLS } from './browser-tools.js';
 import { FLOW_TOOLS } from '../flows/flow-tools.js';
+import { INTENT_TOOLS } from '../intent/intent-tools.js';
+import { CONTEXT_TOOLS } from '../runs/context-tools.js';
 import { PROJECT_TOOLS } from '../project/project-tools.js';
 import { RUN_TOOLS } from '../runs/run-tools.js';
 import { VISUAL_TOOLS } from '../visual/visual-tools.js';
 import { AFFECTED_TOOLS } from '../flows/affected-tools.js';
-import { COVERAGE_TOOLS } from './coverage-tools.js';
+import { buildCoverageTools } from './coverage-tools.js';
 import { VERIFY_CHANGE_TOOLS } from '../flows/verify-change-tools.js';
 import { CRAWL_TOOLS } from '../crawl/crawl-tools.js';
 import { SCROLL_TOOLS } from '../input/scroll-tools.js';
@@ -47,7 +49,7 @@ const SNAPSHOT_CACHE = new SnapshotCache();
 const RAW_TOOLS = [
     {
         name: ReticleTool.SESSIONS,
-        description: 'List connected browser sessions (tab url/title, sessionId, last-seen, health: hidden/focused/throttled, and `realInputAvailable` — true when native CDP/launched real input is driving this tab), plus a `recommendation` pointing to `reticle drive` when a tab is hidden/throttled and may be un-scriptable from here.',
+        description: 'List connected browser sessions (tab url/title, sessionId, last-seen, health: hidden/focused/throttled, and `realInputAvailable` — true when native CDP/launched real input is driving this tab), plus a `recommendation` naming the in-protocol escape hatch (`reticle_run { tool: "reticle_lease" }`, with `reticle drive` as the human-side equivalent) when a tab is hidden/throttled and may be un-scriptable from here.',
         inputSchema: {},
         outputSchema: {
             sessions: z
@@ -76,6 +78,18 @@ const RAW_TOOLS = [
                 pendingMarks: z.number().optional(),
                 review_suggestion: z.string().optional(),
                 recommendation: z.string().optional(),
+                // Attached by SessionManager.list() (#117): whether this tab ever dropped and came back,
+                // how often, and how long the last drop lasted. Undeclared here, a validating client
+                // stripped the outage history while the row still looked complete — a verdict over a
+                // window with a four-second blind gap read as trustworthy.
+                attachment: z
+                    .object({
+                    connectedSinceMs: z.number(),
+                    outages: z.number(),
+                    lastOutage: z.object({ startedMs: z.number(), durationMs: z.number() }).optional(),
+                })
+                    .optional()
+                    .describe('Present only when this tab has dropped and reconnected at least once: how long it has been attached in total, how many outages occurred, and when the last one started and how long it lasted. A verdict over this window spans a gap where nothing was observed.'),
             }))
                 .describe('Connected browser sessions with health state. `projectId` groups sessions by app (stable across port changes); `leased` marks a pool-managed headless context vs a human tab.'),
             why: z
@@ -218,7 +232,7 @@ const RAW_TOOLS = [
     {
         name: ReticleTool.QUERY,
         example: { by: 'testid', value: 'todo-list' },
-        description: `Find elements by Testing-Library semantics, INCLUDING open shadow roots — \`count_only:true\` gives just the count (~30x smaller); \`limit\` caps descriptors. Pass \`by\` (${QUERY_BY_LIST}) and \`value\` (the query string). Returns matching refs + descriptors + visibility. Pass \`attrs:["href"]\` to project attributes (link/image URLs) onto each match. Pass \`limit\` to cap descriptors (broad role queries can be large) or \`count_only:true\` for just the match count — both cut tokens. On zero matches, also returns hint:{ route, presentRegions[], knownEmptyState } so you can distinguish an empty state from a missing element WITHOUT taking a snapshot.`,
+        description: `Find elements by Testing-Library semantics, INCLUDING open shadow roots — \`count_only:true\` gives just the count (~30x smaller); \`limit\` caps descriptors. Pass \`by\` (${QUERY_BY_LIST}) and \`value\` (the query string). Returns matching refs + descriptors + visibility. Pass \`attrs:["href"]\` to project attributes (link/image URLs) onto each match. Pass \`limit\` to cap descriptors (broad role queries can be large) or \`count_only:true\` for just the match count — both cut tokens. On zero matches, also returns hint:{ route, presentRegions[], knownEmptyState } so you can distinguish an empty state from a missing element WITHOUT taking a snapshot. ASKING SEVERAL QUESTIONS ABOUT THE PAGE? One reticle_snapshot answers them all at once — a run of queries costs a round trip each and returns what the snapshot already held.`,
         inputSchema: {
             // Constrained to the enum, NOT z.string(). A free string let `by:'css'` through to the
             // browser's `default: return []`, so an unsupported strategy answered "0 matches" — which
@@ -446,6 +460,8 @@ const RAW_TOOLS = [
     // reticle_capabilities (live | fromDisk) + reticle_contract_save. See contract-tools.ts.
     ...RECONCILE_TOOLS,
     ...CONTRACT_TOOLS,
+    ...INTENT_TOOLS,
+    ...CONTEXT_TOOLS,
     ...DOMAIN_TOOLS,
     // reticle_flow_save / reticle_flow_list / reticle_flow_load. See flow-tools.ts.
     ...FLOW_TOOLS,
@@ -469,7 +485,9 @@ const RAW_TOOLS = [
     // reachable through reticle_run. See affected-tools.ts.
     ...AFFECTED_TOOLS,
     // reticle_coverage — which controls were driven vs never touched. Unadvertised; via reticle_run.
-    ...COVERAGE_TOOLS,
+    // The table is passed as a thunk so the coverage tool can report which of it was called without
+    // importing it back — see buildCoverageTools. Called from the handler, long after TOOLS exists.
+    ...buildCoverageTools(() => TOOLS.map((t) => t.name)),
     // reticle_verify_change — "did my change break anything" in one call. See verify-change-tools.ts.
     ...VERIFY_CHANGE_TOOLS,
     // Live-control: reticle_end_session / reticle_resume / reticle_messages. See live-control-tools.ts.

package/dist/tools/unadvertised-help.js

@@ -1,10 +1,10 @@
 /**
  * What to say when an agent calls a real Reticle tool that this profile does not advertise.
  *
- * The default surface advertises 18 of 48 tools, and the extended one 30. That is deliberate — every
- * advertised tool's schema is re-sent on every turn, and editors budget MCP tools as a COUNT shared
- * across every connected server — and everything omitted stays fully callable through `reticle_run`,
- * which `surface-reachability.test.ts` guards.
+ * The default surface is the verify loop plus the two meta-tools; the extended one is larger but
+ * still capped. Counts live in `surface-sizes.test.ts` — restating them here is how they drift.
+ * Everything omitted stays fully callable through `reticle_run`, which `surface-reachability.test.ts`
+ * guards.
  *
  * The gap was in the ERROR. The MCP SDK answers `Tool <name> not found`, which is indistinguishable
  * from "this tool does not exist", so an agent that trusts it stops trying. Reported from a real

package/dist/tools/verify-next-baton.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The verdict nudge, as a call the agent can make rather than a sentence it has to translate.
+ *
+ * `verify_next` already fires when an agent has driven the page several times and asked for no
+ * verdict, which is the commonest shape of a wasted session: almost every verdict-less session in
+ * the field never called a verdict-producing tool once. What it carried was prose. Prose has to be
+ * turned back into a call, and the translation is exactly where the agent was already going wrong —
+ * `until` omitted, arguments flat instead of nested under `args`, a predicate written as a bare
+ * array.
+ *
+ * So it carries the call. `ref` and `action` come from the act that actually dispatched, so the
+ * suggestion is about the element the agent really touched rather than a worked example from a
+ * document. `until` is deliberately left as a placeholder the agent must replace: naming the
+ * consequence is the one part nothing but the agent can know, and filling it in with a guess would
+ * be Reticle inventing the assertion — the failure `no-fault` exists to prevent.
+ *
+ * Emitted only when there is a real call to suggest. A baton with nothing behind it is the router
+ * failure in miniature: an agent that follows a fabricated next step follows it confidently.
+ */
+/**
+ * Set to `1` to withhold the baton from tool results — the control arm of its A/B, and nothing else.
+ *
+ * A measurement flag, not a product setting: it is read at one call site, documented here, and named
+ * loudly enough that nobody sets it by accident. It exists because this feature has shipped, been
+ * declared the largest lever on whether a session verifies at all, and never been measured — and a
+ * control arm is the only way to tell "agents that see it verify" from "agents that were going to
+ * verify anyway also saw it".
+ */
+export declare const SUPPRESS_VERIFY_NEXT_ENV = "RETICLE_SUPPRESS_VERIFY_NEXT";
+/** What the agent must supply itself. Phrased as an instruction so it cannot be sent verbatim. */
+export declare const UNTIL_PLACEHOLDER = "<name the consequence this action causes>";
+export interface VerifyNextBaton {
+    /** The fact that produced this, in the agent's own terms. */
+    why: string;
+    /** A call, ready to make once `until` is filled in. */
+    call?: {
+        tool: string;
+        args: Record<string, unknown>;
+    };
+    /** Where the argument shapes are stated, on disk and version-exact rather than on the web. */
+    docs?: string;
+}
+/**
+ * Build the baton from what the session actually did.
+ *
+ * `ref` absent means no act dispatched under a ref this session — a navigation, or a run that only
+ * read. There is then no honest call to name, so the prose stands alone rather than pointing at an
+ * element nobody touched.
+ */
+export declare function verifyNextBaton(prose: string, lastAct: {
+    action?: string | undefined;
+    ref?: string | undefined;
+}): VerifyNextBaton;

package/dist/tools/verify-next-baton.js

@@ -0,0 +1,52 @@
+/**
+ * The verdict nudge, as a call the agent can make rather than a sentence it has to translate.
+ *
+ * `verify_next` already fires when an agent has driven the page several times and asked for no
+ * verdict, which is the commonest shape of a wasted session: almost every verdict-less session in
+ * the field never called a verdict-producing tool once. What it carried was prose. Prose has to be
+ * turned back into a call, and the translation is exactly where the agent was already going wrong —
+ * `until` omitted, arguments flat instead of nested under `args`, a predicate written as a bare
+ * array.
+ *
+ * So it carries the call. `ref` and `action` come from the act that actually dispatched, so the
+ * suggestion is about the element the agent really touched rather than a worked example from a
+ * document. `until` is deliberately left as a placeholder the agent must replace: naming the
+ * consequence is the one part nothing but the agent can know, and filling it in with a guess would
+ * be Reticle inventing the assertion — the failure `no-fault` exists to prevent.
+ *
+ * Emitted only when there is a real call to suggest. A baton with nothing behind it is the router
+ * failure in miniature: an agent that follows a fabricated next step follows it confidently.
+ */
+import { ReticleTool } from './tool-names.js';
+/**
+ * Set to `1` to withhold the baton from tool results — the control arm of its A/B, and nothing else.
+ *
+ * A measurement flag, not a product setting: it is read at one call site, documented here, and named
+ * loudly enough that nobody sets it by accident. It exists because this feature has shipped, been
+ * declared the largest lever on whether a session verifies at all, and never been measured — and a
+ * control arm is the only way to tell "agents that see it verify" from "agents that were going to
+ * verify anyway also saw it".
+ */
+export const SUPPRESS_VERIFY_NEXT_ENV = 'RETICLE_SUPPRESS_VERIFY_NEXT';
+/** What the agent must supply itself. Phrased as an instruction so it cannot be sent verbatim. */
+export const UNTIL_PLACEHOLDER = '<name the consequence this action causes>';
+/**
+ * Build the baton from what the session actually did.
+ *
+ * `ref` absent means no act dispatched under a ref this session — a navigation, or a run that only
+ * read. There is then no honest call to name, so the prose stands alone rather than pointing at an
+ * element nobody touched.
+ */
+export function verifyNextBaton(prose, lastAct) {
+    const { ref, action } = lastAct;
+    if (ref === undefined || action === undefined)
+        return { why: prose };
+    return {
+        why: prose,
+        call: {
+            tool: ReticleTool.ACT_AND_WAIT,
+            args: { ref, action, until: { kind: 'text', value: UNTIL_PLACEHOLDER } },
+        },
+        docs: `reticle_tools { names: ["${ReticleTool.ACT_AND_WAIT}"] }`,
+    };
+}

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

@@ -1,13 +1,3 @@
-/**
- * Is `candidate` a strictly NEWER release than `current`?
- *
- * Replaces a plain `!==`, which told anyone on a version newer than the published one — a
- * prerelease, a local build, a rollback in progress — to "update" to something older. A nudge that
- * prompts a downgrade is one people learn to ignore, and this is the mechanism the entire adoption
- * story rests on. Numeric per segment, so 2.10.0 correctly beats 2.9.0 (string order does not), and
- * a bare release beats its own prerelease.
- */
-export declare function isNewerVersion(candidate: string, current: string): boolean;
 interface UpdateNudge {
     /** The version available, so the agent can tell the human what they would be moving to. */
     latestVersion: string;
@@ -30,6 +20,13 @@ interface UpdateNudge {
  *
  * Bounded on purpose: this rides on a tool result every turn until it is delivered, so a long
  * changelog is a per-turn tax. The count of anything elided is stated rather than silently dropped.
+ *
+ * It also names what `update` does to the RULE FILES, which is the half nobody would guess. A new
+ * release changes what the always-loaded instructions should say — that is the whole reason
+ * `refreshAgentRules` exists — and an agent that reads "it restarts the daemon" has no reason to
+ * think its CLAUDE.md is now a release behind. Saying so costs one clause on a message that is
+ * delivered once per daemon, and it is the difference between a fleet that upgrades its rules and
+ * one that upgrades its binary and keeps last release's instructions forever.
  */
 export declare function buildNudge(latestVersion: string, currentVersion: string, release?: {
     changelog?: string;

package/dist/update/update-nudge.js

@@ -29,7 +29,7 @@ import { creditNudge } from './nudge-credit.js';
  * story rests on. Numeric per segment, so 2.10.0 correctly beats 2.9.0 (string order does not), and
  * a bare release beats its own prerelease.
  */
-export function isNewerVersion(candidate, current) {
+function isNewerVersion(candidate, current) {
     const parse = (v) => {
         const [core = '', ...rest] = v.split(/[-+]/);
         return { parts: core.split('.').map((n) => Number.parseInt(n, 10) || 0), pre: rest.length > 0 };
@@ -72,6 +72,13 @@ const MAX_LISTED_BREAKING = 4;
  *
  * Bounded on purpose: this rides on a tool result every turn until it is delivered, so a long
  * changelog is a per-turn tax. The count of anything elided is stated rather than silently dropped.
+ *
+ * It also names what `update` does to the RULE FILES, which is the half nobody would guess. A new
+ * release changes what the always-loaded instructions should say — that is the whole reason
+ * `refreshAgentRules` exists — and an agent that reads "it restarts the daemon" has no reason to
+ * think its CLAUDE.md is now a release behind. Saying so costs one clause on a message that is
+ * delivered once per daemon, and it is the difference between a fleet that upgrades its rules and
+ * one that upgrades its binary and keeps last release's instructions forever.
  */
 export function buildNudge(latestVersion, currentVersion, release) {
     const changelog = (release?.changelog ?? '').trim();
@@ -89,8 +96,10 @@ export function buildNudge(latestVersion, currentVersion, release) {
                 : `This release has BREAKING changes: ${listed.join('; ')}` +
                     (0 < rest ? ` (+${String(rest)} more — see the changelog)` : '') +
                     '. Read them before updating. ') +
-            `Tell the human, and run \`${UPDATE_COMMAND}\` if they agree — it restarts the daemon, ` +
-            'so do it between tasks rather than mid-verification. Continue your current task first.',
+            `Tell the human, and run \`${UPDATE_COMMAND}\` if they agree — it upgrades the packages, ` +
+            "refreshes the Reticle rules in this project's CLAUDE.md / AGENTS.md, and restarts the " +
+            'daemon, so do it between tasks rather than mid-verification. Continue your current task ' +
+            'first.',
     };
 }
 export function startUpdateCheck(now = () => Date.now()) {

package/dist/update/updater.d.ts

@@ -3,7 +3,7 @@ declare const VersionChangeDirection: {
     readonly UPDATE: "update";
     readonly ROLLBACK: "rollback";
 };
-export type VersionChangeDirection = (typeof VersionChangeDirection)[keyof typeof VersionChangeDirection];
+type VersionChangeDirection = (typeof VersionChangeDirection)[keyof typeof VersionChangeDirection];
 /**
  * Report a completed version move. Never throws — an install that worked must still be reported done.
  *

package/docs/README.md

@@ -26,7 +26,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [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 testing-library semantics |
+| [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 |
@@ -46,6 +46,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [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 |
 | [platform-integration.md](platform-integration.md) | Vite, Next, Remix, Astro, plain HTML |

package/docs/cli/cloud.mdx

@@ -20,7 +20,7 @@ These are thin clients over the `/v1` API. The moat is the server, not the verbs
 | `~/.reticle/credentials.json` | Project-scoped API keys from `reticle link`, keyed by `projectId` | Yes |
 | `<repo>/.reticle/cloud.json` | `{ projectId, projectName, url, sync, verify }`. The non-secret binding | No, commit it |
 
-Auth for any command is `RETICLE_CLOUD_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`.
+Auth for any command is `RETICLE_CLOUD_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`. When a command falls back to that default without `RETICLE_CLOUD_URL` (or a saved session URL), it prints a one-line notice on stderr; stdout stays pure JSON for agents.
 
 ## The commands
 

package/docs/cli/doctor.mdx

@@ -53,6 +53,7 @@ When nothing has connected, the `sessions` line fails and the daemon's own diagn
 | `sessions` | Whether any page has actually connected. Zero is a FAILING check rather than a neutral note, because it is the state the setup most often stalls in: wired correctly, daemon up, nothing dialled in. When it is zero the daemon's own no-session diagnosis prints below the checklist |
 | `bridge port` | The port your app must dial, spelled out because mixing it up with the dev server port is the most common setup failure |
 | `port check` | Only when your project's configured port disagrees with the one the daemon is on. Prints the mismatch rather than leaving you to spot it across two lines |
+| `sibling` | Only when a well-known Reticle port other than this daemon's has a listener. An observation, not a diagnosis: that listener may or may not be related |
 | `daemon log` | Where the structured daemon log lives |
 | `tracing` | How to turn that log into a per-stage trace |
 | `desktop` | Only on a desktop project. Every Electron and Tauri misconfiguration here fails silently, so it is diagnosed explicitly |

package/docs/cli/verify.mdx

@@ -50,11 +50,10 @@ Call log:
 
 <Warning>
   `verify` binds the bridge port itself and has **no `--port` flag**: passing one is rejected as
-  `unknown argument '--port'`. If a daemon is already on the port, `verify` dies with a raw `Error:
-  listen EADDRINUSE: address already in use 127.0.0.1:4400` stack trace before it drives anything.
-  Stop the daemon first, or move `verify` with the `RETICLE_PORT` environment variable. This bites
-  most often on a developer machine, where an agent has usually left a daemon running; in CI the
-  port is normally free.
+  `unknown argument '--port'`. If a daemon is already on the port, `verify` does not start a second
+  one: it prints three ways out (ask the running daemon via `reticle_run`, stop it, or move with
+  `RETICLE_PORT`) rather than a raw listen error. This bites most often on a developer machine,
+  where an agent has usually left a daemon running; in CI the port is normally free.
 </Warning>
 
 ## Exit codes

package/docs/desktop.mdx

@@ -214,7 +214,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "0.1"
+reticle-tauri = "2.12"
 ```
 
 ```rust

package/docs/docs.json

@@ -32,7 +32,7 @@
   "navigation": {
     "versions": [
       {
-        "version": "2.11.0",
+        "version": "2.12.0",
         "default": true,
         "tabs": [
           {
@@ -153,7 +153,7 @@
               },
               {
                 "group": "Long form",
-                "pages": ["agent-cheatsheet", "usage", "faq"]
+                "pages": ["agent-cheatsheet", "reticle-manual", "usage", "faq"]
               }
             ]
           },

package/docs/gates.md

@@ -69,7 +69,7 @@ Each gate exists because the ones above it are blind to something. That blindnes
 | **Integration** | `pnpm test:integration` | real headless Chromium: browser pool, crash isolation, framework adapters, `withReticle` | the MCP surface, the daemon | `e2e` |
 | **Web e2e battery** | `pnpm test:e2e` | 32 specs against 3 booted servers and a real browser (the tool surface, the daemon lifecycle, transport faults, telemetry, trace shape), plus the soak | desktop runtimes; the install | `e2e` |
 | **Desktop battery** | `pnpm test:e2e:desktop` | a real Electron main process and a **packaged** Tauri binary, driven headless | web-only paths | `desktop-e2e` |
-| **Install gate** | `pnpm gate:install` | scaffolds 3 pristine apps, publishes this checkout to a local Verdaccio, lets `init` install itself, boots each app in a real browser, polls for a session | install _complexity_; see [`fixtures.md`](./fixtures.md) | `install-gate` |
+| **Install gate** | `pnpm gate:install` | scaffolds 3 pristine apps, publishes this checkout to a local Verdaccio, lets `init` install itself, boots each app in a real browser, polls for a session that advertised capabilities | install _complexity_; see [`fixtures.md`](./fixtures.md) | `install-gate` |
 | **Matrix records** | `pnpm matrix:validate` | every submitted client-compat record is well-formed | whether the client actually works | `matrix-records` |
 | **Windows** | (CI only) | that the code runs at all on the majority platform | e2e; Windows is unit-only | `windows` |
 | **Rust** | `cargo fmt/clippy/check` | `packages/tauri` compiles and lints on Linux, macOS, and cross-checks Windows | everything JS | `rust`, `rust-macos` |

package/docs/install-manual.mdx

@@ -159,7 +159,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "0.1"
+reticle-tauri = "2.12"
 ```
 
 ```rust

package/docs/packages/browser.mdx

@@ -6,13 +6,13 @@ icon: window
 
 `@reticlehq/browser` is the Reticle SDK that runs inside your page. It installs the observers, builds semantic snapshots, executes actions, and talks to the bridge. Install it directly only if you are **not** on React or want to call `connect()` yourself, because [`@reticlehq/react`](/packages/react) already re-exports all of it.
 
-**Apache 2.0. Depends on `@reticlehq/core` and `@testing-library/dom`.**
+**Apache 2.0. Depends on `@reticlehq/core`.**
 
 ## Why it exists
 
 This is what makes Reticle different from a browser-automation tool. Because it runs _inside_ the app rather than driving it from outside, it can see a state mutation and a fired signal, not just a rendered pixel. It never imports a Node API; that boundary is enforced by the dependency graph.
 
-`@testing-library/dom` is why [`reticle_query`](/tools-query) speaks role, label and testid instead of CSS selectors.
+[`reticle_query`](/tools-query) speaks role, label and testid instead of CSS selectors through its own local accessibility engine: one engine computes both what elements are called and what they match by, so a reported identity always round-trips.
 
 ## When you need it directly
 

package/docs/packages/server.mdx

@@ -64,7 +64,7 @@ await server.close();
 | `reticleRoot` | `string` | `cwd()/.reticle` |
 | `pairingTokenDir` | `string` | `~/.reticle` |
 | `now` | `() => number` | `Date.now` |
-| `toolProfile` | `string` | `RETICLE_TOOL_PROFILE`, else `full`. `core` serves the lean surface |
+| `toolProfile` | `string` | retired names (`core`/`full`/…) still map. Live switch is `RETICLE_ADVERTISE_ALL_TOOLS=1`. Default is the lean surface |
 | `httpVerify` | `boolean` | `false` |
 | `httpVerifyPort` | `number` | `RETICLE_VERIFY_DEFAULT_PORT` (`7331`) |
 | `httpVerifyToken` | `string` | `RETICLE_VERIFY_TOKEN` |

package/docs/packages.mdx

@@ -8,9 +8,11 @@ icon: cubes
 Reticle is eleven packages, and most people install two. This page exists so you can tell which two, and so that the ones you skip stop looking mysterious.
 
 <Note>
-  The ten npm packages ship together at one version: whatever `npm view @reticlehq/core version`
-  says, every other `@reticlehq/*` package says too. The Rust crate `reticle-tauri` is versioned
-  **independently**. That is deliberate, not drift.
+  Everything ships together at one version: whatever `npm view @reticlehq/core version` says, every
+  other `@reticlehq/*` package says too, and so does the `reticle-tauri` crate on crates.io.
+
+It was versioned independently until 2.12.0, and that turned out to mean _stuck_: the crate sat at `0.1.0` from the day it was written, the publish job skipped it every release because that version already existed, and no Rust-side fix reached anybody. Lockstep costs one line in the bump script and cannot fail that way.
+
 </Note>
 
 ## Which ones do I need?
@@ -70,7 +72,7 @@ Those rules are why the browser SDK cannot accidentally pull in a filesystem cal
 
 **Why it exists:** this is the part that makes Reticle different from a browser-automation tool. Because it runs _inside_ the app rather than driving it from outside, it can see a state mutation and a fired signal, not just a rendered pixel.
 
-**Depends on:** `@reticlehq/core`, `@testing-library/dom`. The latter is why [`reticle_query`](/tools-query) speaks role, label and testid rather than CSS selectors.
+**Depends on:** `@reticlehq/core`. [`reticle_query`](/tools-query) speaks role, label and testid rather than CSS selectors through its own local accessibility engine, so what a snapshot reports is exactly what a query matches.
 
 **Install it directly when** you are not on React, or you want `connect()` under your own control:
 
@@ -199,13 +201,13 @@ A lint rule makes the signal layer self-enforcing, which is the only way a conve
 
 ## reticle-tauri
 
-**The Rust crate**, on crates.io. Versioned independently of the npm packages.
+**The Rust crate**, on crates.io. Versioned in lockstep with the npm packages, so `2.11` here and `2.11` there mean the same release.
 
 **Why it exists:** Tauri IPC observation needs nothing on the Rust side; an `invoke('load_todos')` already reaches Reticle as `ipc://load_todos`. You only need this crate for screenshots and headless mode.
 
 ```toml
 [dependencies]
-reticle-tauri = "0.1"
+reticle-tauri = "2.12"
 ```
 
 <Warning>