@reticlehq/server 2.10.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 |
@@ -69,6 +70,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [vs-screenshots.mdx](vs-screenshots.mdx) | why a better vision model does not fix a non-visual bug |
 | [telemetry.md](telemetry.md) | what is collected, and how to turn it off |
 | [local-registry.md](local-registry.md) | installing an unpublished build |
+| [license-activation.mdx](license-activation.mdx) | you have a key: where to set it, how to confirm it, what to do when it fails |
 | [enterprise.md](enterprise.md) | the licensed surface |
 
 ## For people working on Reticle

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.10.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"]
               }
             ]
           },
@@ -183,7 +183,7 @@
               },
               {
                 "group": "Trust & licensing",
-                "pages": ["telemetry", "enterprise"]
+                "pages": ["telemetry", "license-activation", "enterprise"]
               }
             ]
           },

package/docs/enterprise.md

@@ -8,6 +8,8 @@ Enterprise features ship inside the open package and are unlocked by a signed li
 
 > Premium access (how you get + activate it), what's gated, the security/data-handling posture, and the licensing model. Integration mechanics live in [`platform-integration.md`](./platform-integration.md).
 
+> **Already have a key and just need to switch it on?** [Activating a license key](./license-activation) is the step-by-step version: where to set it on each platform, the editor and CI cases, how to read every status, and what to do when it does not work.
+
 ## How premium access works (offline, no phone-home)
 
 Enterprise (`ee/`) features ship **inside the open package**; they're source-available (free for development, testing, and evaluation). A **license key activates them in production**. Activation is verified locally with Ed25519; nothing about your usage ever leaves your machine.
@@ -29,7 +31,7 @@ Enterprise (`ee/`) features ship **inside the open package**; they're source-ava
    expired   license expired. Renew with hey@reticle.sh to keep using enterprise features
    ```
 
-   Every status also reports `gated` (what a licence unlocks in the build you are running) and `contact`, so the command answers "what would this buy me, and how do I get one" without anybody having to find this page first. `gated` is derived from the features the gate actually enforces, so it lists what your build will really refuse rather than a roadmap.
+   Every status reports `contact`, so a reader who is stuck always has somebody to write to. An unlicensed status also reports `gated`, what a licence unlocks in the build you are running, so the command answers "what would this buy me, and how do I get one" without anybody having to find this page first. It is derived from the features the gate actually enforces, so it names what your build will really refuse rather than a roadmap. An `active` licence does not report it: that reader has already bought, and listing feature names at them answers nothing they asked.
 
 4. **Unlock.** Enterprise features now run in production; without a valid key they refuse to run there (a clear error, never a silent half-feature). In eval/dev they always run free.
 5. **Renew.** Keys carry an expiry; `reticle license` warns before it lapses.

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