@reticlehq/server 3.6.0 → 3.7.0

package/dist/telemetry/telemetry.js

@@ -16,16 +16,23 @@
 import { spawn } from 'node:child_process';
 import { randomUUID, createHash } from 'node:crypto';
 import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, } from 'node:fs';
-import { homedir, platform } from 'node:os';
+import { homedir, platform, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, isSessionScoped, } from '@reticlehq/core/telemetry';
+import { TelemetryAccountState, TelemetryEventKind, TELEMETRY_EVENT_VERSION, TelemetryEventSchema, ProjectIdSource, isSessionScoped, } from '@reticlehq/core/telemetry';
 import { ReticleEnv } from '@reticlehq/core';
 import { SERVER_VERSION } from '../command/version/identity/server-version.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
-const ID_FILE = join(RETICLE_DIR, 'telemetry-id');
-const NOTICE_FILE = join(RETICLE_DIR, 'telemetry-notice-shown');
+const ID_FILE_NAME = 'telemetry-id';
+const ID_FILE = join(RETICLE_DIR, ID_FILE_NAME);
+const NOTICE_FILE_NAME = 'telemetry-notice-shown';
 /** Presence of this file = a persistent, machine-wide opt-out (`reticle telemetry disable`). */
-const OPT_OUT_FILE = join(RETICLE_DIR, 'telemetry-opt-out');
+const OPT_OUT_FILE_NAME = 'telemetry-opt-out';
+/**
+ * Presence of this file marks the MACHINE as the Reticle team's own: every event carries
+ * `internal: true`. The persistent twin of `RETICLE_INTERNAL=1`, for a dev machine where setting a
+ * variable in every shell would be forgotten once and pollute the numbers for good.
+ */
+export const INTERNAL_MARKER_FILE = 'telemetry-internal';
 /** Where the full disclosure lives — printed in the first-run notice and `reticle telemetry status`. */
 const POLICY_URL = 'https://github.com/reticlehq/reticle/blob/main/docs/telemetry.md';
 /** PostHog batch-capture endpoint (US cloud). `RETICLE_TELEMETRY_URL` overrides the host (EU/self-host). */
@@ -91,15 +98,28 @@ const FEEDBACK_RETRY_BACKOFF_MS = 750;
  * likely to be dropped, and it fails silently like everything else here.
  */
 const DETACHED_SEND_TIMEOUT_MS = 15_000;
-const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'content-type':'application/json'}," +
-    `body:process.argv[2],signal:AbortSignal.timeout(${DETACHED_SEND_TIMEOUT_MS})})` +
+/**
+ * The body never rides in argv: argv is readable by every user on the machine through `ps`, and
+ * the body is the whole event. It is handed over in a file only its owner can read, which the child
+ * reads and deletes before sending. A file rather than a stdin pipe because the parent is a
+ * short-lived CLI that may `process.exit` the moment this returns, and an unflushed pipe write dies
+ * with it; a file is on disk before `spawn` is even called.
+ */
+const DETACHED_SEND_SCRIPT = "const fs=require('fs');const f=process.argv[2];let b='';" +
+    'try{b=fs.readFileSync(f,"utf8")}catch{}try{fs.unlinkSync(f)}catch{}' +
+    "fetch(process.argv[1],{method:'POST',headers:{'content-type':'application/json'}," +
+    `body:b,signal:AbortSignal.timeout(${DETACHED_SEND_TIMEOUT_MS})})` +
     '.catch(()=>{}).finally(()=>process.exit(0))';
+/** Owner read/write only: the body file must not be readable by anyone else on the machine. */
+const BODY_FILE_MODE = 0o600;
 /** Env var names — mirror cloud-sync's `RETICLE_*` convention. */
 import { isReticleSourceCheckout } from './dev-repo.js';
 import { projectInstallSource } from './install-source.js';
 import { licenseFacts } from './license-activation.js';
 import { gitFacts } from './git-facts.js';
 import { currentAutomationHint } from './automation-hint.js';
+import { accountEnvelope } from './account-envelope.js';
+import { currentAgentClient, launchMethodOf } from './agent-client.js';
 const Env = {
     DISABLE: ReticleEnv.TELEMETRY, // "0" / "false" / "off" → disabled
     DO_NOT_TRACK: ReticleEnv.DO_NOT_TRACK, // the cross-tool opt-out convention (any truthy value)
@@ -107,6 +127,7 @@ const Env = {
     FILE: 'RETICLE_TELEMETRY_FILE', // record to a local JSONL file and send NOTHING — see the sink note
     KEY: 'RETICLE_TELEMETRY_KEY', // override the PostHog project key
     CI: 'CI', // presence marks a CI environment
+    INTERNAL: 'RETICLE_INTERNAL', // "1" marks the run as the Reticle team's own (dogfooding, sweeps)
     VITEST: 'VITEST', // set by vitest — unit tests must never phone home
 };
 const isDisabled = (env, cwd = process.cwd()) => {
@@ -183,8 +204,9 @@ export const resolveIdentity = (file = ID_FILE) => {
         return { anonymousId: id, firstRun: true };
     }
     catch {
-        // Can't persist (read-only home, sandbox): still report, just as a fresh ephemeral id each time.
-        return { anonymousId: randomUUID(), firstRun: false };
+        // Can't persist (read-only home, sandbox): still report, as a fresh id each process, and SAY so —
+        // otherwise every process on that machine reads as a new user.
+        return { anonymousId: randomUUID(), firstRun: false, ephemeral: true };
     }
 };
 /**
@@ -236,12 +258,12 @@ const packageRoot = (cwd) => {
     return null;
 };
 /** Print the opt-out notice exactly once per machine (honest disclosure, the OSS-trust bar). */
-const showNoticeOnce = () => {
+const showNoticeOnce = (dir) => {
     try {
-        mkdirSync(RETICLE_DIR, { recursive: true });
+        mkdirSync(dir, { recursive: true });
         // Exclusive create IS the "once": it throws when the file is already there, so the check and
         // the write cannot be split by a second process printing the notice too.
-        writeFileSync(NOTICE_FILE, '1', { encoding: 'utf8', flag: 'wx' });
+        writeFileSync(join(dir, NOTICE_FILE_NAME), '1', { encoding: 'utf8', flag: 'wx' });
         process.stderr.write('reticle: anonymous usage telemetry helps improve reticle — no code, no PII, ' +
             `and your app's data never leaves your machine (${POLICY_URL}). ` +
             'Opt out any time: reticle telemetry disable\n');
@@ -264,7 +286,7 @@ export const describeTelemetry = (env = process.env, dir = RETICLE_DIR, cwd = pr
     if (isDisabled(env, cwd)) {
         return { enabled: false, reason: 'disabled by environment variable', policyUrl: POLICY_URL };
     }
-    if (existsSync(join(dir, 'telemetry-opt-out'))) {
+    if (existsSync(join(dir, OPT_OUT_FILE_NAME))) {
         return {
             enabled: false,
             reason: 'disabled via `reticle telemetry disable`',
@@ -279,7 +301,7 @@ export const describeTelemetry = (env = process.env, dir = RETICLE_DIR, cwd = pr
 };
 /** Persist (or lift) the machine-wide opt-out — `reticle telemetry disable` / `enable`. */
 export const setTelemetryEnabled = (enabled, dir = RETICLE_DIR) => {
-    const optOutFile = join(dir, 'telemetry-opt-out');
+    const optOutFile = join(dir, OPT_OUT_FILE_NAME);
     if (enabled) {
         rmSync(optOutFile, { force: true });
         return;
@@ -296,6 +318,7 @@ const NOOP = { emit: () => Promise.resolve(false), enabled: false, firstRun: fal
  * injected so this is testable without a clock or network.
  */
 export const createTelemetry = (opts) => {
+    const reticleDir = opts.reticleDir ?? RETICLE_DIR;
     const env = opts.env ?? process.env;
     const cwd = opts.cwd ?? process.cwd();
     // A source checkout silences metrics but must not silence FEEDBACK — see onlyBlockedBySourceCheckout.
@@ -303,7 +326,7 @@ export const createTelemetry = (opts) => {
     if (isDisabled(env, cwd) && !feedbackOnly)
         return NOOP;
     try {
-        if (existsSync(OPT_OUT_FILE))
+        if (existsSync(join(reticleDir, OPT_OUT_FILE_NAME)))
             return NOOP; // the persistent `reticle telemetry disable` opt-out
     }
     catch {
@@ -322,7 +345,14 @@ export const createTelemetry = (opts) => {
     const os = platform();
     // Negated so it reads the way people say it: UTC+2 is +120, not -120.
     const tzOffsetMin = -new Date().getTimezoneOffset();
-    const { anonymousId, firstRun } = resolveIdentity();
+    // Feedback-only (a source checkout) sends one kind of event, typed by a person: it borrows an
+    // existing id but never MINTS one, because minting spends `firstRun` and the machine's real first
+    // run would then never report its install.
+    const idFile = join(reticleDir, ID_FILE_NAME);
+    const { anonymousId, firstRun, ephemeral } = feedbackOnly
+        ? { anonymousId: readIdFile(idFile) ?? randomUUID(), firstRun: false, ephemeral: undefined }
+        : resolveIdentity(idFile);
+    const internal = isInternal(env, reticleDir);
     /**
      * One id per PROCESS, minted in memory and never persisted — which is exactly right: a daemon run
      * IS the session, and a restarted daemon is genuinely a new one. Ephemeral by construction, so it
@@ -336,10 +366,16 @@ export const createTelemetry = (opts) => {
     // was unknown for every event that could show whether they got anywhere. Reading it here puts it
     // on all of them, which is the only shape in which the question can be asked.
     const installSource = projectInstallSource(opts.cwd ?? process.cwd());
-    showNoticeOnce();
+    // How this process was launched: a property of the process, so read once. Only the bucket leaves.
+    const launch = launchMethodOf(process.argv[1]);
+    const home = opts.home ?? homedir();
+    if (!feedbackOnly)
+        showNoticeOnce(reticleDir);
     const spawnDetached = opts.spawnImpl ??
-        ((command, args) => {
-            spawn(command, args, { detached: true, stdio: 'ignore' }).unref();
+        ((command, args, input) => {
+            const bodyFile = join(tmpdir(), `reticle-telemetry-${randomUUID()}.json`);
+            writeFileSync(bodyFile, input, { encoding: 'utf8', mode: BODY_FILE_MODE, flag: 'wx' });
+            spawn(command, [...args, bodyFile], { detached: true, stdio: 'ignore' }).unref();
         });
     /**
      * Returns whether the event was actually DELIVERED.
@@ -372,6 +408,9 @@ export const createTelemetry = (opts) => {
             // A SCALAR, so it needs the event build and the wire schema and no `blocks` entry — the same
             // three-place trap `outage` fell into, and `installSource` documents below.
             ...(automation !== undefined ? { automation } : {}),
+            // Two SCALARS, like `automation`: event build + wire schema, no `blocks` entry.
+            ...(internal ? { internal: true } : {}),
+            ...(true === ephemeral ? { idEphemeral: true } : {}),
             os,
             tzOffsetMin,
             projectIdSource,
@@ -406,13 +445,35 @@ export const createTelemetry = (opts) => {
             // the ambient one here would silently ignore it. Identical in production, wrong everywhere the
             // seam is actually used.
             ...licenseFacts(eventTs, env),
+            // Account, workspace and client: SCALARS on every event, so the event build and the wire
+            // schema and no `blocks` entry. Account and client are read per event: a HUD sign-in changes
+            // the first mid-session, and the second is whichever agent's call is in flight.
+            ...accountEnvelope(cwd, env, home),
+            ...(extra?.workspaceId !== undefined
+                ? {
+                    workspaceId: extra.workspaceId,
+                    linked: true,
+                    accountState: TelemetryAccountState.LINKED,
+                }
+                : {}),
+            ...((client) => (client === undefined ? {} : { client }))(currentAgentClient(env)),
+            launch,
+            ...(extra?.hud !== undefined ? { hud: extra.hud } : {}),
+            ...(extra?.link !== undefined ? { link: extra.link } : {}),
+            ...(extra?.harness !== undefined ? { harness: extra.harness } : {}),
         };
+        // The wire schema's caps are only real if something applies them. An event that fails is
+        // DROPPED, never sent and never repaired: the payload is exactly what the caps exist to stop.
+        if (!TelemetryEventSchema.safeParse(event).success) {
+            invalidDropped += 1;
+            return false;
+        }
         // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
         // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, onboarding, bug, refusal, outage, instrumentation, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, onboarding, bug, refusal, outage, instrumentation, hud, link, harness, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
         // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
@@ -444,6 +505,9 @@ export const createTelemetry = (opts) => {
             refusal,
             outage,
             instrumentation,
+            hud,
+            link,
+            harness,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {
@@ -480,7 +544,7 @@ export const createTelemetry = (opts) => {
         }
         try {
             if (true === extra?.detach && opts.fetchImpl === undefined) {
-                spawnDetached(process.execPath, ['-e', DETACHED_SEND_SCRIPT, url, body]);
+                spawnDetached(process.execPath, ['-e', DETACHED_SEND_SCRIPT, url], body);
                 return false; // handed off, outcome unknowable from here
             }
             // Feedback is slower and retried; everything else keeps the fire-and-forget budget.
@@ -517,6 +581,23 @@ export const createTelemetry = (opts) => {
     };
     return { emit, enabled: true, firstRun };
 };
+/**
+ * Events dropped because they failed the wire schema, this process. Local only: the bad payload is
+ * the thing that must not leave, so not even a count of it is sent from here.
+ */
+let invalidDropped = 0;
+export const droppedInvalidEvents = () => invalidDropped;
+/** `RETICLE_INTERNAL=1`, or the machine-wide marker file. Unreadable home → not internal. */
+const isInternal = (env, dir) => {
+    if ('1' === env[Env.INTERNAL] || 'true' === env[Env.INTERNAL])
+        return true;
+    try {
+        return existsSync(join(dir, INTERNAL_MARKER_FILE));
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * The process-wide emitter. One identity resolution + one opt-out check per process; both the CLI
  * lifecycle (install/invoke/session) and the per-tool hook in `runTool` share it.

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

@@ -17,4 +17,6 @@ import { type BrowserBrand, type Verification } from '@reticlehq/core';
  * `falseGreenCaught` is the one that matters: the assertion PASSED and Reticle still refused to call
  * it verified. That is the product's thesis reduced to a boolean.
  */
-export declare function verificationOf(toolName: string, result: Record<string, unknown>, durationMs: number, brand?: BrowserBrand): Verification | undefined;
+export declare function verificationOf(toolName: string, result: Record<string, unknown>, durationMs: number, brand?: BrowserBrand, 
+/** The call ran inside a Harness drive's async context (`currentDrivenBy()`), read by the caller. */
+drivenByHarness?: boolean): Verification | undefined;

package/dist/telemetry/verification-of.js

@@ -13,7 +13,6 @@
 import { CaptureLoss, ReplayStatus, ReticleTool, VerificationDriver, Verified, VerifiedReason, } from '@reticlehq/core';
 import { VERDICT_TOOLS } from '../surface/tools/feedback-tools.js';
 import { getBrowserMode } from './browser-mode.js';
-import { harnessDriving } from './harness-drive.js';
 /**
  * The deciding clause, read off the result `decideVerified` wrote it onto.
  *
@@ -115,7 +114,9 @@ function passedOf(result, status) {
  * `falseGreenCaught` is the one that matters: the assertion PASSED and Reticle still refused to call
  * it verified. That is the product's thesis reduced to a boolean.
  */
-export function verificationOf(toolName, result, durationMs, brand) {
+export function verificationOf(toolName, result, durationMs, brand, 
+/** The call ran inside a Harness drive's async context (`currentDrivenBy()`), read by the caller. */
+drivenByHarness = false) {
     if (!VERDICT_TOOLS.has(toolName))
         return undefined;
     // A paused session REFUSES the call — nothing driven, nothing asserted. The refusal carries a
@@ -123,6 +124,11 @@ export function verificationOf(toolName, result, durationMs, brand) {
     // here for work that happened.
     if (true === result['paused'])
         return undefined;
+    // A wait that stopped at the per-call limit is "not yet", not a verdict: it answers `pass: false`
+    // with `resume_ms`, and read here that became `verified: "no"`, so every paused wait was recorded
+    // as a red and advanced the feedback-prompt counter (#1119).
+    if ('number' === typeof result['resume_ms'])
+        return undefined;
     const replay = replayVerdict(toolName, result['status']);
     const verified = 'string' === typeof result['verified'] ? result['verified'] : (replay?.verified ?? undefined);
     // flow_verify reports `status: pass|fail|unverifiable`; assert reports a boolean `pass`. Accept
@@ -169,7 +175,9 @@ export function verificationOf(toolName, result, durationMs, brand) {
         // WHAT was lost, when the reason was that something was. Three owners, three fixes, one bar
         // until now.
         ...(uncleanLoss === undefined ? {} : { uncleanLoss }),
-        // WHOSE drive this was. Absent is the ordinary case — the agent called the tool itself.
-        ...(harnessDriving() ? { driven: VerificationDriver.HARNESS } : {}),
+        // WHOSE drive this was, read per call by the caller: a drive runs in the background while the
+        // agent keeps calling tools, so a process-wide flag credited the agent's verdicts too. Absent is
+        // the ordinary case — the agent called the tool itself.
+        ...(drivenByHarness ? { driven: VerificationDriver.HARNESS } : {}),
     };
 }

package/dist/wire-journal.d.ts

@@ -19,7 +19,7 @@ export declare function attachJournal(bridge: Bridge, deps: {
     fs: FileSystemPort;
     reticleRoot: string;
     enabled: boolean;
-    takeAmbientTape?: () => {
+    takeAmbientTape?: (sessionId: string) => {
         steps: readonly TapeStep[];
         startPath?: string;
     } | undefined;
@@ -31,4 +31,4 @@ export declare function attachJournal(bridge: Bridge, deps: {
     author?: () => FlowFile['author'];
     /** What this project is willing to keep — the `retain` block of its `.reticle.json`. */
     retain?: PruneWorkspaceOptions;
-}): void;
+}): () => Promise<void>;

package/dist/wire-journal.js

@@ -8,12 +8,13 @@
  * the 1000-line backstop is what asked for the split.
  */
 import { artifactRootResolver } from './memory/project/artifact-root-resolver.js';
+import { claimedArtifactRoot } from './memory/project/root-claims.js';
 import { servingDirectoryOf } from './portal/session/serving-directory.js';
 import { originOf } from './portal/session/session-manager.js';
 import { Bridge } from './portal/bridge/bridge.js';
 import { FlowStore } from './language/flows/flows.js';
 import { makeJournalAttach } from './memory/journal/attach-journal.js';
-import { makeSessionEnd, recordDriveRun } from './memory/journal/session-end.js';
+import { endLiveSessions, makeSessionEnd, recordDriveRun } from './memory/journal/session-end.js';
 import { attachDriveRunFlush } from './memory/journal/drive-run-flush.js';
 import { AmbientStore } from './memory/journal/ambient-store.js';
 import { ensureWorkspaceGitignore } from './memory/journal/on-disk/workspace-gitignore.js';
@@ -45,7 +46,11 @@ export function attachJournal(bridge, deps) {
         // reached a different account's production dashboard.
         // The origin is passed for the case where the page never stamped a project id: it is the only
         // distinguishing fact left, and without it every such app shares one bucket.
-        session.artifactRoot = resolveArtifactRoot(session.projectId, originOf(session.url)).root;
+        // A lease opened by `try`, a chat drive or `verify` carries the root of whoever opened it; the
+        // resolver would send a page with no project id to `unmatched/`, which nothing syncs.
+        session.artifactRoot =
+            claimedArtifactRoot(session.id, session.url) ??
+                resolveArtifactRoot(session.projectId, originOf(session.url)).root;
         // The project's config sits beside its `.reticle/`, so the declaration is read from the tab's
         // own project rather than from wherever the daemon was started.
         session.background = readBackgroundTraffic(findProjectConfig(dirname(session.artifactRoot)));
@@ -66,17 +71,20 @@ export function attachJournal(bridge, deps) {
         }
     });
     // Teardown: flush the journal tail to disk + persist what this session learned.
-    bridge.attachSessionEnd(makeSessionEnd({
+    const teardown = makeSessionEnd({
         ...deps,
         // A drive is saved in the session's own project, where replay will look for it.
         ...(deps.flows === undefined
             ? {}
-            : { flowsAt: (root) => new FlowStore(deps.fs, root, { now: Date.now }) }),
+            : {
+                flowsAt: (root) => new FlowStore(deps.fs, root, { now: Date.now }, deps.onRunPersisted === undefined ? {} : { onWrote: deps.onRunPersisted }),
+            }),
         ...(deps.retain === undefined ? {} : { retain: deps.retain }),
         // Retention runs from teardown, and it must not delete the journal of a session that is still
         // being written. The registry is the only thing that knows which those are.
         liveSessionIds: () => new Set(bridge.sessions.all().map((s) => s.id)),
-    }));
+    });
+    bridge.attachSessionEnd(teardown);
     /*
      * And the same write, DURING the session rather than only at the end of it.
      *
@@ -92,6 +100,7 @@ export function attachJournal(bridge, deps) {
     if (deps.enabled) {
         attachDriveRunFlush({
             resolve: (sessionId) => bridge.sessions.get(sessionId),
+            all: () => bridge.sessions.all(),
             write: (session) => recordDriveRun(deps, session),
         });
     }
@@ -104,4 +113,6 @@ export function attachJournal(bridge, deps) {
     // under which nothing ever deleted what was already there. Visual diffs, feedback copies and run
     // artifacts do not need the journal to be written at all and kept accumulating regardless.
     void pruneWorkspace(deps.fs, deps.reticleRoot, new Set(bridge.sessions.all().map((s) => s.id)), deps.retain ?? {});
+    // For a closing daemon: tear down the tabs still open, awaited, before its last sync.
+    return () => endLiveSessions(bridge.sessions, teardown);
 }

package/docs/README.md

@@ -27,7 +27,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [actions.mdx](actions.mdx) | every action and its arguments, including `press` and its history |
 | [environment.mdx](environment.mdx) | every environment variable Reticle reads, what it changes, and which process reads it |
 | [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/overview.mdx](tools/overview.mdx) | the ten advertised tools, the rest reachable on demand, and why |
 | [tools/snapshot.mdx](tools/snapshot.mdx) | `reticle_look { action: "page" }`: three modes, from full tree to a 25-token route check |
 | [tools/query.mdx](tools/query.mdx) | `reticle_look { action: "find" }` finds elements by their reported roles, names and labels |
 | [tools/inspect.mdx](tools/inspect.mdx) | `reticle_look { action: "element" }`: one element, down to source and design tokens |
@@ -42,7 +42,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [tools/wait-for.mdx](tools/wait-for.mdx) | `reticle_assert { action: "wait" }`, for consequences you did not cause |
 | [tools/assert.mdx](tools/assert.mdx) | `reticle_assert`: verdicts, and a real failure explained |
 | [tools/sessions.mdx](tools/sessions.mdx) | `reticle_session { action: "list" }`: the health fields that decide if driving works |
-| [tools/tools-and-run.mdx](tools/tools-and-run.mdx) | `reticle_tools` / `reticle_run`, reaching the other 30 |
+| [tools/tools-and-run.mdx](tools/tools-and-run.mdx) | `reticle_tools` / `reticle_run`, reaching the tools that are not advertised |
 | [tools/session-and-feedback.mdx](tools/session-and-feedback.mdx) | `reticle_session` / `reticle_session { action: "feedback" }`, the human boundary |
 | [packages.mdx](packages.mdx) | every library at a glance: what it does, why it exists, when you need it |
 | [packages/](packages/) | one page per published package, with its real exported API and dependencies |

package/docs/actions.mdx

@@ -22,8 +22,11 @@ Every action Reticle can perform takes the same shape: a `ref` from [`reticle_lo
 | `select` | `{ value }` | For `<select>` |
 | `check` / `uncheck` | none | Checkbox and radio, or a `role="checkbox"`/`role="switch"` element (fails if `aria-checked` does not change) |
 | `submit` | none | Submits the element's `<form>` |
-| `press` | `{ text }` | The key **name**: `Escape`, `Tab`, `Enter` |
+| `press` | `{ text, modifiers?, holdMs?, keys?, code? }` | `text` is the key **name**: `Escape`, `Tab`, `Enter`. `key` is an accepted alias. `modifiers` is an array of `Meta`, `Control`, `Shift`, `Alt`. `holdMs` holds the key down; `keys` holds several together; `code` names the physical key |
 | `scrollIntoView` | none |  |
+| `scroll` | `{ dy?, dx?, fraction? }` | Scrolls the nearest scrollable container (or the page, with no `ref`) by `dy`/`dx` pixels, either direction. `fraction` (0 to 1) jumps to that point of the height. No args steps down most of a screen |
+| `tap` | `{ holdMs? }` | A touch tap: pointer and touch events, then `click`. `holdMs` makes it a long press |
+| `zoom` | none | Page zoom. Refused inside the page, because CSS zoom changes how a page looks without changing its layout, and a passing check on it would be false |
 | `upload` | `{ content?, name?, type?, path? }` | Sets a file on `<input type="file">`. Inline bytes default to `"reticle test file"` / `"file.txt"` / `"text/plain"`. `path` reads a file from disk, scoped to the project root plus any opt-in directories listed in `.reticle.json` as `"uploadRoots": ["~/Downloads", "/Volumes/fixtures"]`. A refusal names every allowed root. |
 | `drag` | `{ toRef }` | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD. `target` is an alias |
 
@@ -71,7 +74,7 @@ This one has history worth knowing. The implementation used to read `args.key` a
 
 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`.
+This is often misdiagnosed as "synthetic events don't reach the app". That is the wrong root cause: the event reached the app perfectly well and simply said `Enter`.
 
 </Warning>
 
@@ -112,7 +115,7 @@ Several actions in one round trip:
 
 Fields sitting at their uninformative default are **omitted**, so a clean action collapses to its consequence. A missing `visible` means `true`, not `false`. Read an absence as "nothing to report" rather than as a failure.
 
-`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.
+`occluded` is often the answer to "the button doesn't work": 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.

package/docs/adapters.md

@@ -72,4 +72,4 @@ A **realm adapter** teaches Reticle about a kind of app that is not a browser ta
 
 If you want to write either, open an issue and say what you are building. The interfaces exist; what is missing is the door.
 
-A template for each of the four kinds, including the two that are contributable today, is in [`adapters/CONTRIBUTING.md`](https://github.com/reticlehq/reticle/blob/main/adapters/CONTRIBUTING.md). It carries the rules each adapter kind must hold to, and why each rule exists.
+A template for each kind is in [`adapters/CONTRIBUTING.md`](https://github.com/reticlehq/reticle/blob/main/adapters/CONTRIBUTING.md). It also covers a fourth kind, lint (an ordinary ESLint plugin such as `@reticlehq/eslint-plugin`, which needs no registration and so is also contributable today), and carries the rules each kind must hold to, and why each rule exists.