@reticlehq/server 2.6.0 → 2.8.0

package/dist/tools/tool-kit.js

@@ -14,32 +14,63 @@ export const sessionIdShape = {
         .describe('OMIT THIS unless you mean a specific tab — Reticle scopes to your project, prefers the active one, and refuses rather than guesses when ambiguous. Pass an id from reticle_sessions only to target a particular tab. The previous wording ("omit when only ONE session is open") was wrong and cost real turns: with three sessions connected — an app plus two pool leases — resolution is still unambiguous, but that sentence sent the agent off to list and filter sessions by hand before every single call.'),
 };
 /**
- * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime
- * (health, pool lease reminder, age cleanup nudge, and the delivered-once human-control envelope).
- * They are declared here and merged into each session-bound tool's outputSchema so a schema-strict
- * client (structuredContent validation) keeps them instead of silently dropping them — the `control`
- * envelope is the human-in-the-loop guidance channel, so losing it is a safety failure, not cosmetic.
+ * Every key `runTool` splices onto a session-bound result, as a closed list.
+ *
+ * These are wire strings and were inlined at the splice sites, which is exactly how four of them
+ * came to be spliced and never declared. `sessionEnvelopeShape` is derived from this object and
+ * `envelope-keys-declared.test.ts` fails if a member is missing from it, so the two cannot drift.
+ *
+ * Each of these is a channel that exists BECAUSE the agent had no other way to learn the fact.
+ * Undeclared, a schema-strict client validating `structuredContent` drops it, and the channel is
+ * indistinguishable from never having been built.
  */
-export const sessionEnvelopeShape = {
-    session: z.unknown().optional(),
-    session_lease: z.unknown().optional(),
-    session_age_warning: z.unknown().optional(),
-    control: z.unknown().optional(),
-    // `warning` rides alongside `session` whenever the tab is THROTTLED (healthEnvelope splices both).
-    // It was declared on reticle_act's schema but nowhere else, so on a validating profile every other
-    // session-bound tool (observe, assert, wait_for, act_sequence, act_and_wait, snapshot, query, …)
-    // silently dropped it — a throttled tab, where drives can no-op, returned a healthy-looking result.
-    // That is exactly what invoke-tool.ts's health splice exists to prevent, so it belongs in the shared
-    // envelope, not per-tool.
-    warning: z.string().optional(),
-    // The one-shot "ask the human how this went" envelope. Undeclared, a validating profile would strip
-    // it — and a feedback prompt that never reaches the agent is a feedback prompt that never reaches
-    // the person, which is the entire failure mode this channel exists to fix.
-    feedback_prompt: z.unknown().optional(),
-    // One-shot "a newer Reticle exists" notice. Undeclared, a validating profile would strip it and the
-    // agent would never learn an update was waiting.
-    update_available: z.unknown().optional(),
+export const EnvelopeKey = {
+    /** Session health — which tab, how fresh. */
+    SESSION: 'session',
+    /** One-shot pool-lease reminder. */
+    SESSION_LEASE: 'session_lease',
+    /** One-shot "these sessions are old, clean them up". */
+    SESSION_AGE_WARNING: 'session_age_warning',
+    /** The delivered-once human-in-the-loop guidance envelope. Losing it is a safety failure. */
+    CONTROL: 'control',
+    /**
+     * Rides alongside `session` whenever the tab is THROTTLED. It was declared on `reticle_act`'s
+     * schema and nowhere else, so on a validating profile every other session-bound tool silently
+     * dropped it — a throttled tab, where drives can no-op, returned a healthy-looking result.
+     */
+    WARNING: 'warning',
+    /** One-shot "ask the human how this went". */
+    FEEDBACK_PROMPT: 'feedback_prompt',
+    /** One-shot "a newer Reticle exists". */
+    UPDATE_AVAILABLE: 'update_available',
+    /**
+     * "You have driven this page N times without asking for a verdict."
+     *
+     * The largest known lever on the metric this product is judged by: verdict-less sessions
+     * overwhelmingly never call a verdict-producing tool at all. It was spliced undeclared, so on a
+     * validating client the nudge was built, fired, and thrown away before any agent saw it.
+     */
+    VERIFY_NEXT: 'verify_next',
+    /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
+    FEEDBACK_INVITE: 'feedback_invite',
+    /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
+    VERSION_SKEW: 'version_skew',
+    /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
+    FEEDBACK_UNDELIVERED: 'feedback_undelivered',
 };
+/**
+ * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.
+ * Merged into each session-bound tool's outputSchema so a schema-strict client (structuredContent
+ * validation) keeps them instead of silently dropping them.
+ *
+ * Derived from `EnvelopeKey` rather than re-listed: this shape and the splice sites disagreed for a
+ * whole release, and every key that went missing was a channel nobody could see was missing.
+ */
+export const sessionEnvelopeShape = Object.fromEntries(Object.values(EnvelopeKey).map((key) => [
+    key,
+    // `warning` is the one with a narrower type; the rest are opaque envelopes the client forwards.
+    EnvelopeKey.WARNING === key ? z.string().optional() : z.unknown().optional(),
+]));
 /** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
 export async function commandOrThrow(deps, sessionId, 
 // ReticleCommand, not string: the union already exists and every caller passes a member. Typed as

package/dist/tools/tool-surface.js

@@ -100,16 +100,16 @@ export const CORE_TOOL_NAMES = new Set([
     ReticleTool.ACT_AND_WAIT,
     // ACT_SEQUENCE is here because its absence was measurably CAUSING the biggest loop in the data.
     //
-    // Measured 2026-08-10/11 (non-CI): `reticle_act` 319 calls, `reticle_act_sequence` **7**. `act`
-    // also leads the repeat table at 110 consecutive-repeat runs, and inside those sessions the
-    // repeated calls are 98 clicks and 21 fills — a login form driven one round trip at a time, which
-    // is exactly the antipattern SKILL.md warns about and exactly what this tool exists to collapse.
+    // In the field `reticle_act` is called overwhelmingly more often than `reticle_act_sequence`, and
+    // `act` leads the repeat table by a wide margin — inside those sessions the repeated calls are
+    // clicks and fills, a login form driven one round trip at a time, which is exactly the antipattern
+    // SKILL.md warns about and exactly what this tool exists to collapse.
     //
-    // The repeats are NOT retries: looping sessions have a lower error rate (0.051) than non-looping
-    // ones (0.078). The calls succeed and get repeated, because the batching tool was reachable only
-    // through `reticle_run` — so an agent had to already know it existed to use it, and 7-vs-319 says
-    // essentially nobody did. A tool an agent must already know about is a tool that never gets
-    // called; the same argument that put INSPECT and FEEDBACK here.
+    // The repeats are NOT retries: looping sessions have a LOWER error rate than non-looping ones. The
+    // calls succeed and get repeated, because the batching tool was reachable only through
+    // `reticle_run` — so an agent had to already know it existed to use it, and essentially nobody
+    // did. A tool an agent must already know about is a tool that never gets called; the same argument
+    // that put INSPECT and FEEDBACK here.
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.OBSERVE,
     ReticleTool.NETWORK,
@@ -144,6 +144,25 @@ export const CORE_TOOL_NAMES = new Set([
     // deleting the instruction from the lease and the pause hint — deletes the handback protocol,
     // because there is nowhere else those two calls are ever named.
     ReticleTool.SESSION,
+    // CAPABILITIES is the highest orientation-per-token tool on the surface: one call returns the app's
+    // whole testable surface — its testids, signals, stores and named flows — and `{fromDisk:true}`
+    // returns the same from a checked-in contract with NO browser attached, so an agent with zero
+    // context starts oriented instead of exploring.
+    //
+    // Same argument as the four above, and it is the fifth time this file has made it: a tool an agent
+    // must already know about, and reach through reticle_run, is a tool that never gets called.
+    //
+    // The cost is real and is NOT the bargain #262 claimed. That issue argued the marginal cost sits
+    // "well below the 274-token average" because the input schema is small; measured, its description
+    // plus schema is closer to 325 tokens, which is above the average rather than below it. This is
+    // also a straight +1 rather than a swap: the tools that write-up proposed demoting (`project`,
+    // `domain`) were never in the default set to begin with.
+    //
+    // So it is a deliberate bet, taken with that correction on the table: that orientation replaces
+    // exploratory snapshots, which are among the most expensive calls an agent makes. The measurement
+    // that settles it is whether sessions calling this early take fewer and cheaper snapshots than
+    // those that do not. If that does not show up, this is the entry to revert.
+    ReticleTool.CAPABILITIES,
 ]);
 /** Is the truthy form of a boolean env var set? `1`, `true`, `yes` — anything else is off. */
 function envFlagOn(raw) {

package/dist/tools/tools.js

@@ -78,6 +78,10 @@ const RAW_TOOLS = [
                 recommendation: z.string().optional(),
             }))
                 .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
+                .string()
+                .optional()
+                .describe('Present ONLY when `sessions` is empty: why nothing is connected, and the next action that fixes it. An empty list is never the end of the road — read this before concluding the app cannot be driven.'),
         },
         handler: async (deps) => {
             const provider = deps.realInput;
@@ -87,6 +91,14 @@ const RAW_TOOLS = [
                 realInputAvailable: provider !== undefined ? await provider.isAvailableFor(s.url) : false,
                 leased: leasedIds.has(s.sessionId),
             })));
+            // An empty list is the most common thing this tool ever returns, and on its own it is a dead
+            // end: the agent asked the one question it knows to ask, got a confident-looking answer with
+            // no next step, and stopped. The daemon already knows WHY nothing is connected — say it here
+            // rather than only when a later tool fails for want of a session.
+            if (0 === sessions.length) {
+                const why = deps.sessions.noSessionHint();
+                return { sessions, ...(why === undefined ? {} : { why }) };
+            }
             return { sessions };
         },
     },
@@ -193,6 +205,10 @@ const RAW_TOOLS = [
                 .string()
                 .optional()
                 .describe('CSS selector or element ref to restrict the search to a subtree.'),
+            self: z
+                .boolean()
+                .optional()
+                .describe('Return the `scope` element ITSELF instead of searching inside it. Use when the target is a plain layout container with no role, name, testid or text of its own — which is routinely the element that carries the handler, and is otherwise unreachable because every query excludes its own scope root. Requires `scope`.'),
             attrs: z
                 .array(z.string())
                 .optional()
@@ -297,7 +313,13 @@ const RAW_TOOLS = [
                 // The handler forwards an explicit allowlist, so a new input is silently dropped unless it is
                 // added here — the browser saw no `attrs` and returned undefined while the unit tests, which
                 // call matchQuery directly, passed. Schema plus implementation is not the whole wire.
+                //
+                // It happened again with `self`, in the same session that wrote this comment: declared on the
+                // tool, implemented in the browser, verified by unit tests that call `runQuery` directly, and
+                // dropped here — so the live call returned zero matches with no error. `query-forwarding.test.ts`
+                // now asserts the payload, because a comment is not a guard.
                 attrs: args['attrs'],
+                self: args['self'],
             }).then((result) => withSizeCost(paginateQueryResult(result, asNumber(args['limit']), true === args['count_only'])));
         },
     },
@@ -336,10 +358,22 @@ const RAW_TOOLS = [
             })
                 .partial()
                 .optional(),
-            // Theme compliance vs the app's design tokens: { colorToken, backgroundToken (null = off-palette),
-            // offTheme, tokenCount }. Kept as unknown — the structured-content serializer can truncate a
-            // large inspect payload's fields to strings, which a strict shape would reject; the full object
-            // is always present in the text content the agent reads.
+            scroll: z
+                .object({
+                scrollTop: z.number(),
+                scrollHeight: z.number(),
+                clientHeight: z.number(),
+                overflowY: z.string(),
+            })
+                .optional(),
+            // Theme compliance vs the app's design tokens: { colorToken, colorTokens, backgroundToken,
+            // backgroundTokens, offTheme, tokenCount, themeScope }. The plural fields carry EVERY token
+            // matching the resolved colour; the singular ones abstain (null) when several tokens share it,
+            // because returning an arbitrary winner was the defect (#313). `themeScope` names the theme
+            // that was active at capture, so two inspects minutes apart are comparable at all.
+            // Kept as unknown — the structured-content serializer can truncate a large inspect payload's
+            // fields to strings, which a strict shape would reject; the full object is always present in
+            // the text content the agent reads.
             theme: z.unknown().optional(),
             /**
              * Where this element is written, as `file:line`. Present when the app is built with the

package/dist/visual/capture-cleanup.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Remember the private parent of a capture after the daemon has read it.
+ *
+ * Legacy captures live directly in `tmpdir()` and therefore have no directory to reclaim. The
+ * caller has already applied the capture-path trust-boundary check; this second exact parent check
+ * keeps the cleanup set limited to the one-level private layout.
+ */
+export declare function trackCaptureDirectory(path: string): void;
+/**
+ * Remove empty private capture directories during the daemon's existing awaited shutdown path.
+ *
+ * Deliberately `rmdir`, never recursive removal: captures are unlinked after reading, so a genuine
+ * directory is empty by shutdown. If anything unexpected remains, refusing to remove the directory
+ * is safer than widening a renderer-supplied path into a recursive delete.
+ */
+export declare function cleanupCaptureDirectories(): Promise<void>;

package/dist/visual/capture-cleanup.js

@@ -0,0 +1,39 @@
+import { rmdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname } from 'node:path';
+import { RETICLE_CAPTURE_FILE_PREFIX } from '@reticlehq/core';
+/** Private shell directories whose captures this daemon has successfully consumed. */
+const captureDirectories = new Set();
+/**
+ * Remember the private parent of a capture after the daemon has read it.
+ *
+ * Legacy captures live directly in `tmpdir()` and therefore have no directory to reclaim. The
+ * caller has already applied the capture-path trust-boundary check; this second exact parent check
+ * keeps the cleanup set limited to the one-level private layout.
+ */
+export function trackCaptureDirectory(path) {
+    const parent = dirname(path);
+    if (dirname(parent) === tmpdir() && basename(parent).startsWith(RETICLE_CAPTURE_FILE_PREFIX)) {
+        captureDirectories.add(parent);
+    }
+}
+/**
+ * Remove empty private capture directories during the daemon's existing awaited shutdown path.
+ *
+ * Deliberately `rmdir`, never recursive removal: captures are unlinked after reading, so a genuine
+ * directory is empty by shutdown. If anything unexpected remains, refusing to remove the directory
+ * is safer than widening a renderer-supplied path into a recursive delete.
+ */
+export async function cleanupCaptureDirectories() {
+    await Promise.all([...captureDirectories].map(async (dir) => {
+        try {
+            await rmdir(dir);
+        }
+        catch {
+            // Best-effort shutdown housekeeping. A non-empty or already-removed directory is harmless.
+        }
+        finally {
+            captureDirectories.delete(dir);
+        }
+    }));
+}

package/dist/visual/visual-tools.d.ts

@@ -1,4 +1,22 @@
 import type { ToolDef } from '../tools/tools.js';
+/**
+ * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
+ * become a file-read oracle for whatever a compromised renderer names.
+ *
+ * Two layouts are accepted, and the pair is the whole subtlety:
+ *
+ * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
+ *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
+ * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
+ *   SEPARATE package on the user's own upgrade schedule: an app still on the older
+ *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
+ *   start returning no image. It grants the daemon nothing it did not already have.
+ *
+ * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
+ * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
+ * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
+ */
+export declare function isCapturePath(path: string): boolean;
 /**
  * The opt-in pixel layer. Both tools require a DRIVEN browser (reticle drive /
  * RETICLE_CDP_URL) — the always-on SDK ships no screenshotter — and return a structured NO_PROVIDER

package/dist/visual/visual-tools.js

@@ -5,6 +5,7 @@ import { sessionIdShape } from '../tools/tool-kit.js';
 import { asNumber, asRecord, asString } from '../tools/tools-helpers.js';
 import { diffPng } from './visual-diff.js';
 import { VisualStore } from './visual-store.js';
+import { trackCaptureDirectory } from './capture-cleanup.js';
 import { readFile, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname } from 'node:path';
@@ -87,6 +88,7 @@ async function desktopCapture(deps, sessionId, fullPage) {
     try {
         const bytes = await readFile(path);
         await unlink(path).catch(() => undefined);
+        trackCaptureDirectory(path);
         return isCompletePng(bytes) ? { png: new Uint8Array(bytes) } : {};
     }
     catch {
@@ -94,12 +96,29 @@ async function desktopCapture(deps, sessionId, fullPage) {
     }
 }
 /**
- * Only read a capture the shell wrote: inside the OS temp dir, with Reticle's own filename prefix.
- * The path arrives from the PAGE, and the daemon must not become a file-read oracle for whatever a
- * compromised renderer names.
+ * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
+ * become a file-read oracle for whatever a compromised renderer names.
+ *
+ * Two layouts are accepted, and the pair is the whole subtlety:
+ *
+ * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
+ *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
+ * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
+ *   SEPARATE package on the user's own upgrade schedule: an app still on the older
+ *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
+ *   start returning no image. It grants the daemon nothing it did not already have.
+ *
+ * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
+ * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
+ * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
  */
-function isCapturePath(path) {
-    return dirname(path) === tmpdir() && basename(path).startsWith(RETICLE_CAPTURE_FILE_PREFIX);
+export function isCapturePath(path) {
+    if (!basename(path).startsWith(RETICLE_CAPTURE_FILE_PREFIX))
+        return false;
+    const parent = dirname(path);
+    if (parent === tmpdir())
+        return true;
+    return dirname(parent) === tmpdir() && basename(parent).startsWith(RETICLE_CAPTURE_FILE_PREFIX);
 }
 /**
  * A PNG is complete only if it ends with IEND. This check exists because a truncated image once

package/docs/README.md

@@ -1,31 +1,73 @@
 # Docs index
 
-Two audiences share this directory, which is why it looked like twenty-five unsorted files. Every page states its own audience in the first blockquote; this index is the shortcut.
+Two audiences share this directory: people using Reticle and people working on it. Every page carries a `description` in its frontmatter saying what it answers; this index is the shortcut when you want to scan all of them at once.
 
-**User docs are published** to [reticle.sh](https://reticle.sh) via `mint.json`. **Contributor docs are not** — they are for people working _on_ Reticle, and they live here because they belong next to what they describe.
+Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `docs.json`, which is the Mintlify config for this directory. Five tabs. **Guides** to learn in order, grouped by what you are doing (get started, install, instrument, verify and ship, work with agents, and when it goes wrong). **Reference** to look one thing up. **Desktop** because Electron and Tauri are a different shape of problem and deserve their own front door, **Resources** to decide or to check a claim, and **Contributing** for people working on Reticle. Contributor docs sit in a tab rather than hidden, since they were reachable by URL anyway, and an unlisted page is a page nobody finds.
 
 ---
 
 ## For people using Reticle
 
-**Start:** [getting-started.md](getting-started.md) → [usage.md](usage.md) (the full tool reference).
+**Start:** [quickstart.mdx](quickstart.mdx) → [usage.md](usage.md) (the full tool reference).
 
 | Page | What it answers |
 | --- | --- |
+| [quickstart.mdx](quickstart.mdx) | five minutes to a real verdict; every response on it was captured live |
+| [what-is-reticle.mdx](what-is-reticle.mdx) | the definition, what Reticle is NOT, and what it needs to run |
+| [why-reticle.mdx](why-reticle.mdx) | the false-green problem, the measured case, and where we lose |
+| [install-agentic.mdx](install-agentic.mdx) | what `npx @reticlehq/server init` writes, and how to read its marks |
+| [install-manual.mdx](install-manual.mdx) | wiring the MCP server and SDK by hand, per agent and framework |
 | [getting-started.md](getting-started.md) | install it, connect an agent, verify something |
-| [usage.md](usage.md) | every tool, every argument — the reference |
+| [usage.md](usage.md) | the long-form narrative; most of it now has a focused page, and it says so at the top |
+| [predicates.mdx](predicates.mdx) | the predicate grammar, and which kinds actually prove something |
+| [capabilities.mdx](capabilities.mdx) | coverage, storage, fake clocks, crawl, visual diff, network mocking |
+| [recipes.mdx](recipes.mdx) | worked examples for real situations, with the response each returned |
+| [actions.mdx](actions.mdx) | every action and its arguments, including `press` and its history |
+| [faq.mdx](faq.mdx) | production, frameworks, comparisons, and the honest limits |
+| [tools-overview.mdx](tools-overview.mdx) | the 18 advertised tools, the 30 in the cold tail, and why |
+| [tools-snapshot.mdx](tools-snapshot.mdx) | `reticle_snapshot`: three modes, from full tree to a 25-token route check |
+| [tools-query.mdx](tools-query.mdx) | `reticle_query` finds elements by testing-library semantics |
+| [tools-inspect.mdx](tools-inspect.mdx) | `reticle_inspect`: one element, down to source and design tokens |
+| [tools-navigate.mdx](tools-navigate.mdx) | `reticle_navigate`, and why `ok` does not mean the page arrived |
+| [tools-act.mdx](tools-act.mdx) | `reticle_act` acts, proves nothing, and says so |
+| [tools-act-and-wait.mdx](tools-act-and-wait.mdx) | `reticle_act_and_wait`, the tool that produces a verdict |
+| [tools-act-sequence.mdx](tools-act-sequence.mdx) | `reticle_act_sequence`: batch a form into one round trip |
+| [tools-observe.mdx](tools-observe.mdx) | `reticle_observe`, the whole timeline when you don't know what broke |
+| [tools-network.mdx](tools-network.mdx) | `reticle_network`: the request log, redaction, and buffer honesty |
+| [tools-console.mdx](tools-console.mdx) | `reticle_console`, and an empty result that proves it looked |
+| [tools-state.mdx](tools-state.mdx) | `reticle_state`: what the app believes, not what it drew |
+| [tools-wait-for.mdx](tools-wait-for.mdx) | `reticle_wait_for`, for consequences you did not cause |
+| [tools-assert.mdx](tools-assert.mdx) | `reticle_assert`: verdicts, and a real failure explained |
+| [tools-sessions.mdx](tools-sessions.mdx) | `reticle_sessions`: the health fields that decide if driving works |
+| [tools-tools-and-run.mdx](tools-tools-and-run.mdx) | `reticle_tools` / `reticle_run`, reaching the other 30 |
+| [tools-session-and-feedback.mdx](tools-session-and-feedback.mdx) | `reticle_session` / `reticle_feedback`, the human boundary |
+| [packages.mdx](packages.mdx) | every library at a glance: what it does, why it exists, when you need it |
+| [packages/](packages/) | one page per published package, with its real exported API and dependencies |
+| [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 |
+| [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 |
-| [desktop-apps.md](desktop-apps.md) | Electron and Tauri |
+| [desktop.mdx](desktop.mdx) | why desktop is different, and what only Reticle does there |
+| [desktop-apps.md](desktop-apps.md) | Electron and Tauri, in full |
+| [frameworks.mdx](frameworks.mdx) | what is supported, what is wired-but-unverified, and the wiring |
+| [state-management.mdx](state-management.mdx) | zustand, Redux, and eight adapters |
+| [instrumentation.mdx](instrumentation.mdx) | stores, signals, testids, and how verdicts get stronger |
+| [troubleshooting.mdx](troubleshooting.mdx) | nothing connected, click did nothing, verdict says unknown |
+| [cli.mdx](cli.mdx) | the CLI at a glance, with real output and measured exit codes |
+| [cli/](cli/) | one page per command: every flag, what it prints, and its exit codes |
 | [integration-patterns.md](integration-patterns.md) | wiring it into a real codebase |
 | [flows.md](flows.md) | record → save → replay → heal |
-| [testing.md](testing.md) | `@reticlehq/test` — turning a session into a CI suite |
+| [testing.md](testing.md) | `@reticlehq/test`, turning a session into a CI suite |
 | [multi-agent-testing.md](multi-agent-testing.md) | more than one agent on one app |
 | [human-control.md](human-control.md) | taking the wheel back from the agent |
 | [deploy-checks.md](deploy-checks.md) | running Reticle against a deployed build |
 | [token-efficiency.md](token-efficiency.md) | why it costs less than a screenshot loop |
 | [benchmarks.md](benchmarks.md) | how the numbers were measured, including where Reticle loses |
+| [vs-playwright-mcp.mdx](vs-playwright-mcp.mdx) | outside-in vs inside-out, and when Playwright is right |
+| [vs-chrome-devtools-mcp.mdx](vs-chrome-devtools-mcp.mdx) | cheaper per look, catches less: the trade, measured |
+| [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 |
 | [enterprise.md](enterprise.md) | the licensed surface |
@@ -36,20 +78,23 @@ Two audiences share this directory, which is why it looked like twenty-five unso
 
 | Page | What it answers |
 | --- | --- |
-| [gates.md](gates.md) | **I changed some files — which gate do I run?** |
+| [gates.md](gates.md) | **I changed some files. Which gate do I run?** |
 | [gate-plan.md](gate-plan.md) | why the gates are shaped this way, and what is still unbuilt |
 | [system-map.md](system-map.md) | how a tool call reaches the app, and which failures are silent |
 | [telemetry-contract.md](telemetry-contract.md) | required reading before touching anything that emits |
-| [debugging.md](debugging.md) | debugging Reticle itself — the four signals and what each answers |
+| [telemetry-events.mdx](telemetry-events.mdx) | every event kind and its payload, and the question each one exists to answer |
+| [debugging.md](debugging.md) | debugging Reticle itself: the four signals and what each answers |
 | [fixtures.md](fixtures.md) | the sibling `reticle-fixtures` repo: install complexity, not regressions |
-| [matrix/README.md](matrix/README.md) | submitting an MCP-client compatibility record — the best first contribution |
+| [matrix/README.md](matrix/README.md) | submitting an MCP-client compatibility record, the best first contribution |
 | [matrix/MATRIX.md](matrix/MATRIX.md) | which clients are known to work (generated; do not hand-edit) |
 | [`../apps/README.md`](../apps/README.md) | what belongs in `apps/`, and what does not |
 | [`../apps/e2e/harness-rules.md`](../apps/e2e/harness-rules.md) | the four rules every gate obeys, and the incident behind each |
 | [`../bench/README.md`](../bench/README.md) | what in `bench/` is live and what is a kept one-off study |
 
-`fixtures-dispatch-receiver.yml` is not a doc — it is the workflow template `reticle-fixtures` needs, kept in this repo so the two ends of the contract cannot drift apart.
+`fixtures-dispatch-receiver.yml` is not a doc; it is the workflow template `reticle-fixtures` needs, kept in this repo so the two ends of the contract cannot drift apart.
 
 ---
 
-**Adding a page?** Put it in the right table above. If it is user-facing, add it to `mint.json` too — a page that is published but unlisted is a page nobody finds, and a page listed here but absent from `mint.json` is one users cannot reach at all.
+**Adding a page?** Three things, all required. Give it `title` + `description` frontmatter and no `# H1`. Mintlify renders the frontmatter title as the heading, so an H1 shows up twice. Add its slug to the right tab in `docs.json`. Add a row to the right table above. A page missing from `docs.json` is one nobody can reach; a page missing from this index is one no contributor knows exists.
+
+**Adding a second product?** Do not nest these files under a product folder pre-emptively; that renames every live URL to buy nothing. Mintlify supports `navigation.products`, where each product declares its own `directory`. When the second product exists, put its pages in `docs/<product>/`, switch `docs.json` from `tabs` to `products`, and give this product `"directory": ""` so today's URLs keep working.

package/docs/actions.mdx

@@ -0,0 +1,87 @@
+---
+title: Action reference: lights, camera, click
+sidebarTitle: Actions
+description: Every action reticle_act and reticle_act_and_wait can perform, with its arguments and the one that has a history.
+icon: hand-pointer
+---
+
+```json
+{ "ref": "e42", "action": "fill", "args": { "value": "hello" } }
+```
+
+| Action | Arguments | Notes |
+| --- | --- | --- |
+| `click` / `dblclick` | none | Dispatches a real click |
+| `hover` | none | `mouseover` + `mouseenter`, so JS hover state triggers |
+| `focus` / `blur` | none |  |
+| `fill` | `{ value }` | Sets value via a React-safe native setter, then `input` and `change` |
+| `type` | `{ text }` | **Appends** to the current value |
+| `clear` | none | Empties an input |
+| `select` | `{ value }` | For `<select>` |
+| `check` / `uncheck` | none | Checkbox and radio |
+| `submit` | none | Submits the element's `<form>` |
+| `press` | `{ text }` | The key **name**: `Escape`, `Tab`, `Enter` |
+| `scrollIntoView` | none |  |
+| `upload` | `{ name, content?, type? }` | Sets a file on `<input type="file">` |
+| `drag` | `{ toRef }` | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD |
+| `webmcp` | `{ tool, params }` | Calls a `navigator.modelContext` tool, if the site exposes one |
+
+## `fill` versus `type`
+
+`fill` replaces. `type` appends. Reaching for `type` when you meant `fill` is how a field ends up containing `hellohello`, and neither call will complain.
+
+## `press` takes `text`, not `key`
+
+Both are accepted today, and `text` wins when both are present. Use `text`. It is what the tool description documents.
+
+<Warning>
+This one has history worth knowing. The implementation used to read `args.key` and **default to
+`Enter`**, so the documented call, `{ action: "press", args: { text: "Escape" } }`, silently sent
+`Enter` and reported success.
+
+Three consequences, worst last: the requested key never arrived, so Escape-to-close and Tab-traversal went unverified while looking verified; nothing in the result said the argument had been ignored; and `Enter` is not a neutral substitute. On a focused field inside a form it **submits it**. A request to close a dialog could file the form behind it.
+
+Two field reports were exactly this, both diagnosed as "synthetic events don't reach the app". Wrong root cause: the event reached the app perfectly well and simply said `Enter`.
+
+</Warning>
+
+That bug is fixed, and the reason it is written down here is that it is the exact shape of failure Reticle exists to catch. An action that reports success while doing something else.
+
+## Batching
+
+Several actions in one round trip:
+
+```json
+{
+  "steps": [
+    { "ref": "e101", "action": "fill", "args": { "value": "admin@reticle.dev" } },
+    { "ref": "e102", "action": "fill", "args": { "value": "hunter2" } },
+    { "ref": "e103", "action": "click" }
+  ]
+}
+```
+
+<Warning>
+  [`reticle_act_sequence`](/tools-act-sequence) returns `ok: true` when the steps were
+  **dispatched**, not when they worked. Batch the setup, then prove the outcome with
+  [`reticle_act_and_wait`](/tools-act-and-wait) on the final step.
+</Warning>
+
+## Real versus synthetic input
+
+`inputMode` in the response says which you got. `synthetic` means events dispatched programmatically. Correct for the overwhelming majority of apps. `real` means native CDP input, available under `reticle drive`, and needed by a few drag-and-drop and pointer-gesture libraries.
+
+<Warning>
+  On a throttled tab, synthetic timers and pointer gestures can silently no-op. Pass
+  `refuseWhenThrottled: true` to fail loudly instead of acting into a tab the browser has paused.
+</Warning>
+
+## What every action reports
+
+`valueChanged`, `focusMoved`, `domMutatedWithin`, `defaultPrevented`, `occluded` and `occludedBy`. Plus the element's `testid`, `component` and `source` file and line.
+
+`occluded` is the answer to a large share of "the button doesn't work" reports: the click landed on the modal overlay sitting on top of it.
+
+<Card title="Full field-by-field walkthrough" icon="hand-pointer" href="/tools-act">
+  What each effect field tells you, with a real response.
+</Card>