@reticlehq/server 3.5.0 → 3.7.0

package/docs/skill.md

@@ -0,0 +1,200 @@
+---
+name: reticle
+description: Install, instrument and verify this running web app from the inside (DOM, network, routing, console and framework state) instead of screenshots or guessing. Drives one real flow end to end and returns a verdict with the file:line to fix. Use when the user asks to set up or install Reticle, when a user-facing change needs proving before you call it done, when a test passes but the UI is broken, or when the user types /reticle.
+license: Apache-2.0
+metadata:
+  version: 3.7.0
+  homepage: https://docs.reticle.sh
+  repository: https://github.com/reticlehq/reticle
+---
+
+# Reticle
+
+Reticle is the proof layer for AI coding agents. A dev-only SDK inside the user's running app exposes the DOM, network, routing, console and framework state to you as `reticle_*` MCP tools. You act on the real app and get a verdict: `yes`, `no`, or `unknown` (could not tell), with evidence and the `file:line` to open. No screenshots and no vision model: it drives the tab the user already has open.
+
+Why it matters: an agent that reads its own diff cannot tell a working change from a silent `500`, a double submit, or a store that never committed. Reticle reads what the app actually DID. This file is everything you need; each section links the page with the detail.
+
+**How it fits together.** The SDK in the page (`@reticlehq/browser`, wired by `reticle init`, absent from production builds) dials a local daemon on `localhost:4400` with a pairing token. Your client reaches that daemon through `npx @reticlehq/server mcp`. Verdicts are computed by the daemon from what the page reported, never from your reasoning. Journeys you drive are saved under `.reticle/flows/` and replay later with no model. The optional platform (`app.reticle.sh`) adds a dashboard, run history and the Harness. Nothing from the app leaves the machine unless you link it; there is no tool that evaluates arbitrary JavaScript, and passwords, tokens and card numbers are `[REDACTED]` before you see them. Detail: `https://docs.reticle.sh/what-is-recorded.md`.
+
+## Your first action
+
+**`reticle_*` tools visible?** In the project, call `reticle_session { action: "list" }` and do its `next_action`. On a never-connected project that call runs `init` itself and lists what it changed under `wired`; tell the user. If it answers `run_init`, run this in the app's folder:
+
+```bash
+RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init
+```
+
+**Not visible?** Hand the user one line for a terminal, outside this client, and stop:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
+irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex   # Windows
+```
+
+It registers Reticle with every coding agent it finds and prints the next steps: restart the agent (a client loads MCP servers only at start, so a prompt cannot replace this command), then paste the prompt it printed. Do not register the server yourself and work around your client not having reloaded. If your client did register mid-session, `npx @reticlehq/server init --relaunch` prints the command that resumes this conversation with the tools.
+
+**Done means a verdict.** `init` exiting 0, the tools appearing, a session listed: each proves wiring, not that anything works. Do not tell the user Reticle is set up until one real flow in their app returned a verdict.
+
+## The rules, every call
+
+1. Only `verified: "yes"` passes. `"unknown"` (could not tell) and `"no-fault"` (nothing was declared) are not proved, never "failed" and never "working". `"no"` names what it found instead.
+2. Name the consequence BEFORE acting: `reticle_act_and_wait { target, action, until }`. `durable: true` re-checks it after a reload.
+3. Verdicts come only from `reticle_act_and_wait`, `reticle_assert`, `reticle_act { steps }` with an `expect`, and `reticle_verify` (`change`/`flows`). `look`, `navigate`, `observe` and a bare `act` prove nothing.
+4. **Never weaken a check to make it pass.** On a `no`, read `expected` / `observed` / the nearest candidates, then fix the app or the target.
+5. Target by `{ testid }`, `{ role, name }`, `{ label }` or `{ text }`; an ambiguous target is refused, a missing one says what is there.
+6. Diagnosing a bug? Read the source first. Reticle proves what the app does, not why; drive to confirm a fix.
+7. Write the text that you save (flow names, notes, feedback, plans) in ASD-STE100 Simplified Technical English: short sentences, active voice, one meaning for each word, no idioms.
+
+## The tools you have
+
+The advertised surface is deliberately small (`default` 10, `all` 30 behind `RETICLE_ADVERTISE_ALL_TOOLS=1`). `reticle_tools` lists every registered tool, `reticle_tools { names: [...] }` loads its full arguments, and `reticle_run { tool, args }` calls any of them.
+
+| Tool | Use it to | Key arguments |
+| --- | --- | --- |
+| `reticle_session` | list tabs, end, hand back, tune the HUD, report feedback | `action`: `list` `yield` `end` `tune` `feedback` `account` |
+| `reticle_navigate` | go to a URL or reload | `url`, `reload`, `hard` |
+| `reticle_look` | see the page, find refs, inspect one, read a store | `action`: `page` (`mode: "interactive"`) `find` `element` `state` |
+| `reticle_act_and_wait` | act and prove the consequence in one call | `ref`/`target`, `action`, `args`, `until`, `durable`, `intent` |
+| `reticle_act` | act without a verdict, or a whole journey as `steps` | `steps: [{ target, action, args, expect }]` |
+| `reticle_assert` | prove a predicate `now`, or `wait` for one | `predicate`, `timeout_ms`, `since` |
+| `reticle_observe` | what the app did since a cursor | `action`: `events` `network` `console`; `since` |
+| `reticle_verify` | replay, coverage, Harness | `action`: `change` `flows` `affected` `coverage` `crawl` `explore` `mutate` `heal` |
+| `reticle_tools` / `reticle_run` | everything else (below) | `names`; `tool`, `args` |
+
+Actions: `click` `dblclick` `hover` `focus` `blur` `fill` `type` `clear` `select` `check` `uncheck` `submit` `press` `upload` `scrollIntoView` `scroll` `drag` `tap` `zoom`. `args`: `{ value }` for fill/select, `{ text: "Enter" }` for press, `{ toRef }` for drag, `{ path }` for upload, `{ native: true }` for a trusted click. A control whose label reads as destructive is refused until you pass `args.confirmDangerous: true`, and only do that when the user asked for it. Full reference: `https://docs.reticle.sh/actions.md`, `https://docs.reticle.sh/tools/overview.md`.
+
+Beyond the advertised set, one hop each:
+
+- `reticle_run({ tool: "reticle_screenshot" })`: pixels, when the look itself matters
+- `reticle_run({ tool: "reticle_network_mock", args: { mocks } })`: stub or fail a request
+- `reticle_run({ tool: "reticle_clock", args: { freeze: true } })`: freeze, then `advanceMs`, timers
+- `reticle_run({ tool: "reticle_storage" })`: localStorage, sessionStorage, readable cookies
+- `reticle_run({ tool: "reticle_viewport", args: { width, height } })`: a fixed size
+- `reticle_run({ tool: "reticle_lease", args: { action: "acquire" } })`: an isolated headless tab
+- `reticle_run({ tool: "reticle_context" })`: what this run already established, after a compaction
+
+## Predicates
+
+Every `until`, `predicate` and `expect` is `{ kind, ...fields }`; unknown fields are refused, so nothing silently passes.
+
+| kind | fields |
+| --- | --- |
+| `element` | `query: { testid \| role+name \| text \| label \| placeholder \| alt \| component, scope? }`, `state?`: `visible` `hidden` `enabled` `disabled` `checked` `expanded` `pressed` `focused` `present` `inViewport`, `absent?` |
+| `text` | `contains`, `scope?`, `visible?`, `absent?`, `ignoreCase?`, `satisfies?` |
+| `net` | `method`, `urlContains`, `status`, `ok`, `count` (exact: catches a double submit), `bodyContains`, `bodyMatches`, `requestBodyMatches`, `repeatable` |
+| `route` | `pathname` or `contains` |
+| `signal` | `name`, `dataMatches?`, `count?` |
+| `state` | `store`, `path`, `equals` or `satisfies` |
+| `console` | `level`, `contains?`, `absent?` |
+| `settled` / `animation` / `compare` | `quietMs` / `name`, `completed` / `left`, `right`, `as` |
+| `allOf` / `anyOf` / `not` | `predicates: [...]` / `predicates: [...]` / `predicate` |
+
+`satisfies` asserts a property when the exact value varies: `nonEmpty`, `oneOf`, `withinTolerance`, `matchesPattern`, `type`, `changed`, `unchanged`, `increased`, `decreased`. Composites hold only predicates: `absent` belongs inside a child, and an `element` takes a `query`, never a `ref`. A bare `route` or `state` is already true before the action and proves nothing; pair it with what the action causes. Grammar: `https://docs.reticle.sh/predicates.md`.
+
+## Feedback is first-class
+
+Reticle is built for agents, so your experience decides what gets fixed, and it is lost when your context is. The moment Reticle broke, lied, could not see something, cost too many calls, or setup gave you trouble, file it and carry on:
+
+```
+reticle_session { action: "feedback", kind, text }
+```
+
+`kind`: `bug`, `gap`, `ambiguity`, `feature_request`, `improvement`, `experience`. Tools unreachable? `npx @reticlehq/server feedback --agent --kind <kind> "what happened"`. A bug in the app under test is Reticle working: it belongs in your answer. Never put app source, secrets or user data in a report.
+
+---
+
+# SETUP
+
+Two places always need the user:
+
+1. **No recognisable dev script in `package.json`.** Say so; do not invent one.
+2. **Your host asks the human to approve a command.** That prompt belongs to the host. Never bypass or suppress it, and take a refusal as the answer. `init` writing a pre-approval rule for the `reticle` server is not that: it is a scoped, announced config change the human asked for by running the command, and it covers only Reticle's own tools.
+
+Everything else (running `init`, starting the dev server, opening the browser) is a setup step, not a decision. A dev server that was running when `init` ran must be restarted once. When `init` cannot finish alone, read `docs/skill-setup.md`, which ships beside this file (`https://docs.reticle.sh/skill-setup.md`).
+
+# VERIFY
+
+## Take the cheapest path that answers the question
+
+Stop at the first row that fits. Replaying a saved journey costs a few hundred tokens; driving it again costs tens of thousands.
+
+| The question | The call |
+| --- | --- |
+| "Did my edit break anything?" | `reticle_verify { action: "change", files: ["src/App.tsx"] }` |
+| "Does every saved journey still work?" | `reticle_verify { action: "flows" }` |
+| "Does this new behaviour work?" | `reticle_act_and_wait` on the step that ENDS the journey |
+| No MCP at all | `npx @reticlehq/server verify <url> --expect '<predicate JSON>'` |
+
+`change` answers `unknown` when no saved flow covers your files: nothing ran, so drive it yourself and never read it as a pass. A locator that was renamed rather than broken: `{ action: "heal" }` rebinds it, re-proving the saved consequence first.
+
+## Drive it by hand
+
+```
+reticle_session()                                   // connected? empty: read `why`, it names the fix
+reticle_look({ action: "page", mode: "interactive" })   // the controls, with refs
+reticle_act_and_wait({ target: { testid: "pay" }, action: "click", until: { kind: "allOf", predicates: [
+  { kind: "net", method: "POST", urlContains: "/api/order", status: 200, count: 1 },
+  { kind: "element", query: { role: "dialog", name: "Order confirmed" }, state: "visible" },
+  { kind: "console", level: "error", absent: true },
+]}})                                                // the verdict
+```
+
+A journey in one call: `reticle_act { steps: [{ target, action, args?, expect? }] }`; the last `expect` is the end state. Refs (`e42`) die when their element re-renders: re-find by `target` rather than retrying a ref. Declare what a change is meant to make true with `intent` on the verdict call, so it is checked against more than itself.
+
+**Saved automatically.** When the session ends, what you drove is saved as a flow if at least one step declared a consequence; a bare `act` replays as a click that passes even when the feature is broken. Name it yourself: `reticle_run({ tool: "reticle_record", args: { action: "start", name } })`, drive, then `reticle_run({ tool: "reticle_flow_save", args: { name } })`. Flows: `https://docs.reticle.sh/flows.md`.
+
+## The Harness: let Reticle drive
+
+The Harness drives the app for you through the same tools, decides on the Reticle platform, records what it drove as flows, and answers in a few lines instead of a context full of snapshots. It spends credits (`reticle connect` signs in and grants free ones) and unlocks at 80% instrumentation:
+
+```
+reticle_verify { action: "explore", persona: "a returning customer checking out" }
+```
+
+It answers within `wait` seconds, or `{ status: "running", runId }`: poll `reticle_verify { action: "explore", runId }`, never start a second. Without the Harness you drive with the calls above; everything else works the same.
+
+**Instrumentation**, which `reticle doctor` and the HUD score with a fix per gap: the page connected, DOM actions, network, console (all from `init`); `file:line` source mapping (keep the build plugin `init` added); `data-testid` on every control a flow uses; app state via `registerStore(name, store)` from `@reticlehq/browser`, passing the store rather than a getter; and `reticle.signal("order:placed", { id })` once each user-visible outcome commits. List them in `registerCapabilities` in the `reticle-dev` file `init` wrote. Detail: `https://docs.reticle.sh/instrumentation.md`.
+
+## When it goes wrong
+
+| You see | Do |
+| --- | --- |
+| no session | `reticle_session { action: "list" }` and its `next_action`; restart a dev server that predates `init` |
+| target matched no element | `reticle_look { action: "page" }`, then target what is really there |
+| ref no longer resolves | the DOM re-rendered: target by `testid` or `role`+`name` |
+| predicate did not parse | it names the field: fix the shape against the table above |
+| destructive action blocked | `args.confirmDangerous: true`, only if the user wants that press |
+| version skew | `npx @reticlehq/server stop`, then retry |
+| port held by a non-Reticle process | stop that process, or run Reticle on another `--port` |
+
+More: `https://docs.reticle.sh/troubleshooting.md`.
+
+## The CLI, for humans and CI
+
+Every command works as `npx @reticlehq/server <command>`; once installed, `reticle <command>`. Never npx the bare name `reticle`: that is somebody else's package.
+
+| Command | Does |
+| --- | --- |
+| `init` | wire this app, boot it, prove a page connected (`--dry-run`, `--app <dir>`, `--relaunch`) |
+| `status` / `doctor` | is it running and connected / what is wrong and what coverage is missing |
+| `verify <url>` | replay saved flows; `--expect '<json>'` for one verdict; `--results-json <file>` for CI |
+| `gate --since HEAD~1` | fail unless passing runs cover every saved flow your edit affects |
+| `connect` | sign in and link this project to the dashboard; runs sync from then on |
+| `try <url>` | watch the Harness drive a URL once (signed in) |
+| `stop` / `restart` | stop or restart the daemon |
+
+Reference: `https://docs.reticle.sh/cli.md`, `https://docs.reticle.sh/cli/cloud.md`.
+
+## When the verdict lands
+
+Paste the `reticleResult` block from `reticle_verify` or `reticle_session { action: "end" }` verbatim, last line included, and never reword its verdict into a pass. Add the `file:line` for anything broken. If Reticle caught what reading the code missed, say Reticle found it. Before you stop driving, `reticle_session { action: "yield" }` hands the tab back to the human.
+
+## Find the rest
+
+Append `.md` to any docs URL for the source without site chrome; `https://docs.reticle.sh/llms.txt` lists every page.
+
+- Learn: `quickstart.md`, `what-is-reticle.md`, `use-cases.md` (security, accessibility, performance, SEO, personas), `vs-playwright-mcp.md`, `benchmarks.md`
+- Wire: `frameworks.md`, `install-manual.md`, `state-management.md`, `desktop.md` (Electron, Tauri)
+- Verify: `agent-cheatsheet.md`, `testing.md`, `deploy-checks.md`, `capabilities.md`
+- Teams and agents: `multi-agent-testing.md`, `human-control.md`, `http-transport.md`, `platform-integration.md`
+- Trust: `what-is-recorded.md`, `telemetry.md`

package/docs/system-map.md

@@ -56,13 +56,13 @@ Three different counts, all measured, and the difference between them matters:
 
 | Count | What it is |
 | --- | --- |
-| **76** | name constants in `ReticleTool` |
+| **77** | name constants in `ReticleTool` |
 | **30** | tools advertised under `RETICLE_ADVERTISE_ALL_TOOLS=1`, i.e. what `tool-surface-sweep-test` drives |
 | **10** | advertised by default; the rest are reached through `reticle_run { tool, args }` |
 
 The middle number is **family folding**: `reticle_baseline`, `reticle_session`, `reticle_record`, `reticle_flow` and `reticle_lease` each absorb their members behind an `action` parameter. So "every tool is callable" is asserted over the advertised surfaces, not over every named behaviour; a family member reachable only through an `action` value the sweep never passes is not covered by it. Worth closing when the per-tool budget lands (see [`gate-plan.md`](https://github.com/reticlehq/reticle/blob/main/docs/gate-plan.md), Phase 4).
 
-These three were each wrong by the time somebody checked: the table read 68 / 48 / 19 against a measured 76 / 30 / 10, and the middle one had a derived token cost hanging off it. `surface-sizes.test.ts` is the authority and fails when a surface changes size, so prefer reading it to trusting this row.
+These three were each wrong by the time somebody checked: the table read 68 / 48 / 19 against a measured 76 / 30 / 10 (77 constants since), and the middle one had a derived token cost hanging off it. `surface-sizes.test.ts` is the authority and fails when a surface changes size, so prefer reading it to trusting this row.
 
 | Token | Produced by | Consumed by | Invalidated by |
 | --- | --- | --- | --- |
@@ -89,7 +89,7 @@ Two structural facts:
 
 | Failure | Silent | Guarded by |
 | --- | --- | --- |
-| proxy killed externally (the `lsof -ti` recipe) | **yes, total** | `reticle kill` frees the port and leaves the agent's own proxy alone. See [harness rule 1](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md) |
+| proxy killed externally (the `lsof -ti` recipe) | **yes, total** | `reticle stop --force` frees the port and leaves the agent's own proxy alone. See [harness rule 1](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md) |
 | proxy uncaught exception | no | `installProxyResilience` + `proxyLog` |
 | proxy exits when the reconnect budget is spent | _was the worst bug in the product_ | `onReconnectBudgetSpent` → DORMANT, never exit |
 | client closes stdin with calls in flight | no | `SHUTDOWN_DRAIN_MS` (5s) |
@@ -117,7 +117,7 @@ Still fragile:
 | Failure | Silent | Note |
 | --- | --- | --- |
 | `serve` exits 0 on `EADDRINUSE` | **yes** | #115: the parent reports the spawn, the child reports the bind, nothing joins them |
-| liveness is the pid file, never the port | **yes** | `daemon/daemon.ts:156` |
+| liveness is the pid file, never the port | **yes** | `isRunning` in `server/src/command/daemon/daemon.ts` |
 | idle shutdown fires mid-install | **yes** | 5min base / 30min attached; already scored three fixtures as install failures |
 | `isUselessDaemon` ends a daemon that served nothing | **yes** | lifetime facts, but a gate that installs for six minutes before its first call is that daemon |
 | a daemon spawned inside a tool call is reaped when the call ends | **yes** | `SIGTERM` within ~1s, `detached` or not |
@@ -138,7 +138,7 @@ Still fragile:
 
 | Failure | Silent | Note |
 | --- | --- | --- |
-| fixed 1s reconnect, no backoff, unbounded | **yes** | and the noise lands in the console channel we report to the agent (#116) |
+| reconnect noise | **fixed** | was a fixed 1s retry with no backoff (#116); now doubles from 1s to a 30s ceiling and resets on recovery |
 | `onUnreachable` suppressed after the first success | **yes** | a **mid-session** outage never warns at all |
 | offline queue overflow (`MAX_QUEUE = 500`) | no | gap marker stamped at the **oldest** drop, the honest floor for where the hole starts |
 | `sessionStorage` throws in a sandboxed iframe | no | falls back; a session must still start |
@@ -155,10 +155,10 @@ Still fragile:
 | tools | surface, schema, refusals | `tool-surface-sweep-test`, `tool-fuzz-test` | latency/failure budget |
 | verdict | honesty | `release-smoke-test` | transport ≠ app (#124); false-green rate |
 | telemetry | silent absence | `telemetry-events-test`, `telemetry-contract.test.ts` | chokepoint coverage |
-| install | pristine-surface wiring | nothing | the whole class |
+| install | pristine-surface wiring | `pnpm gate:install` (thirteen pristine scaffolds) | apps with many plugins: the `reticle-fixtures` repo |
 | client | per-agent MCP compatibility | nothing | the whole class |
 
-Nine of eleven layers have a gate. The two that do not are exactly the two that need a second repo and a human. The plan for both is in [`gate-plan.md`](https://github.com/reticlehq/reticle/blob/main/docs/gate-plan.md).
+Nine of ten layers have a gate. The one that does not, per-agent MCP compatibility, needs a human driving each client. The plan for both is in [`gate-plan.md`](https://github.com/reticlehq/reticle/blob/main/docs/gate-plan.md).
 
 ## 6. Traces already encode the invariants
 

package/docs/telemetry.md

@@ -21,7 +21,7 @@ This page is the complete description of what is collected. If something is not
 
 ## What is sent
 
-Eighteen kinds of events, each a single small JSON object. This is the whole list, and it is the same list the code enumerates:
+Twenty-two kinds of events, each a single small JSON object. This is the whole list, and it is the same list the code enumerates:
 
 | Event | When | Extra data |
 | --- | --- | --- |
@@ -42,19 +42,23 @@ Eighteen kinds of events, each a single small JSON object. This is the whole lis
 | `bug_found` | Reticle finds a defect in the app under test | The **kind** of defect (`signal-contradicted`, `console-error`, …) and how it was found, never what it was found in |
 | `tool_refused` | A tool cannot do what an agent asked | Which tool, why (one of six buckets: no session, no match, unsupported, bad arguments, not ready, other), and whether the same call was retried. **Never the message**, because a refusal interpolates whatever you asked for, so only the tool name and the bucket are sent. Capped at 50 per daemon run |
 | `feedback_submitted` | **Only** when you or your agent explicitly send feedback | The report; see [Feedback](#feedback). The AGENT's call does not wait for the network: the receipt says `accepted` (validated, redacted, queued), never `sent`, and a delivery that then fails is reported back on the agent's next tool result. `reticle feedback` typed by a human still waits, because a person at a terminal is owed the real answer |
-| `identified` | **Only** when you run `reticle identify` | What you chose to tell us; see [Telling us who you are](#telling-us-who-you-are) |
+| `hud_viewed` | You open a page of the in-page HUD (Agent Log, Flows, Notes, Harness, Impact, Settings) or its account menu | Which page, from a closed list, and how many tabs had a HUD (a bucket: `1`, `2-3`, and so on). The same page reopened in the same tab within 30 seconds counts once |
+| `hud_signin_prompted` | The HUD shows you a sign-in or "link this project" prompt | Which prompt (`rail`, `harness` or `header`), once per prompt per tab |
+| `platform_linked` | A project on this machine is linked to a Reticle workspace | How (`connect`, `hud` or `link`) and the workspace's id; see [The platform side](#the-platform-side) |
+| `harness_run` | A Reticle Harness run starts, and again when it ends | Who started it (`agent`, `hud`, `dashboard`, `cli_try`, `plan`), whether the platform drove it, and at the end how it went (`proved`, `not_proved`, `failed`, `blocked`, `stopped`) and how many journeys it answered and replayed, as buckets |
+| `identified` | **Never** from this version. Only an earlier version's `reticle identify`, which has been removed | What you chose to tell us then; see [Telling us who you are](#telling-us-who-you-are) |
 
 **There is no per-tool-call event.** Tool usage is counted in memory and leaves once, inside `daemon_stopped`, as a histogram like `{"reticle_act": 40, "reticle_assert": 12}`. That is counts of tool NAMES from a fixed list we define, never arguments, results, selectors, or URLs.
 
 **Parameter and flag NAMES are collected; their VALUES are not.** We record that `reticle_act` was called with `ref` and `action`, and that you ran `reticle serve --headed --port`. We do not record what you set them to. This distinction is the whole safety property, and it is absolute for CLI flags: `--http-token` holds a secret, `--drive` holds a URL, `--storage-state` holds a file path, so no flag value is ever sent. For tool parameters there is one narrow exception: a short, explicit allowlist of parameters whose values are enums _we_ defined (`action: "click"`), listed in [`argument-shape.ts`](https://github.com/reticlehq/reticle/blob/main/server/src/telemetry/argument-shape.ts). A value outside that allowlist reports as `other`, so a future schema change cannot quietly start forwarding free text. `reticle_act`'s `args` (the text being typed into your app, which on a login form is a password) is **never** in that allowlist.
 
-`daemon_stopped` carries: how long the session ran, how many tool calls and of which tools, how long each tool took (total and worst case), how many failed, how many verifications ran, browser/lease connection attempts with their failure causes, and which MCP clients connected (`claude-code`, `cursor`).
+`daemon_stopped` carries: how long the session ran, how many tool calls and of which tools, how long each tool took (total and worst case), how many failed, how many verifications ran, browser/lease connection attempts with their failure causes, and which MCP clients connected (`claude-code`, `cursor`). It also carries how the in-page HUD was used: presses per control (`hudControls`, by the control's name from a closed list Reticle defines, a toggle as `name:on` / `name:off`), how long the HUD sat as a bubble, collapsed or open and on which page (`hudViewMs`, `hudPanelMs`), which rail slides were shown (`hudSlides`), and the order of those presses and views, cut at 60 (`hudJourney`). Control names, never anything typed or shown on the page.
 
 It also carries a snapshot of the **machine's** state (our own process's memory, free and total system RAM, load average and CPU count), taken at shutdown and again on any crash. This is what separates "your machine ran out of memory" from "Reticle has a bug", which otherwise produce identical-looking failures. No hostname, no username, no paths, no process list.
 
 ### Why a verdict came out that way
 
-`verification_completed` carries the **clause** that decided the verdict, from a fixed list we define: `proved`, `contradicted`, `assertion_failed`, `already_true`, `unclean_capture`, `vacuous_grade`, `outcome_pending`, `outcome_unread`, `unsettled`, `evidence_incomplete`, `observation_lost`, `window_closed_early`, `inconclusive`.
+`verification_completed` carries the **clause** that decided the verdict, from a fixed list we define: `proved`, `contradicted`, `assertion_failed`, `already_true`, `hidden_match`, `unclean_capture`, `vacuous_grade`, `nothing_declared`, `outcome_pending`, `outcome_unread`, `unsettled`, `evidence_incomplete`, `absence_blind_spot`, `observation_lost`, `window_closed_early`, `inconclusive`, `version_skew`, `capability-absent`.
 
 It exists because `verified: "unknown"` covered seven different situations belonging to three different owners (your app, your agent, and Reticle's own blind spots), and they arrived as one value. It is a **name from our own vocabulary**, never a description of your app: `contradicted` says two channels disagreed, not which ones, about what, or on which page.
 
@@ -97,6 +101,10 @@ Every event carries the same few fields:
 | `projectId` | A one-way SHA-256 hash of the git origin URL, or of the directory path outside a repo | Not reversible: we can count _distinct_ projects, but not learn any project's name, URL, or location. Hashing the origin means one repo counts once instead of once per teammate and per clone |
 | `actor` | Whether a person or an agent caused this: a typed `reticle` command is a person, an MCP tool call is the agent | Not a claim about _why_. Whether you asked your agent to verify, or it decided to, lives in a prompt Reticle never sees, and we do not guess |
 | `sessionId` | A random id for this daemon run, held in memory and never written to disk | Not a device id and not persistent: a restarted daemon gets a new one. It only groups one run's own events together |
+| `accountState` / `linked` | Whether this machine is signed out, signed in, or signed in with this project linked to a workspace | Not who is signed in: read from whether a sign-in file exists, never from what is in it |
+| `workspaceId` | Only once this project is linked: the Reticle workspace's id, the `orgId` in `.reticle/cloud.json` | Not the workspace's name and not your email. It is the one key the Reticle platform can join this usage to the workspace you created there; see [The platform side](#the-platform-side) |
+| `client` | Which coding agent the event came from, from a closed list (`claude_code`, `cursor`, `codex`, and so on, or `other`) | Not the name your agent sent: a name we do not list arrives as `other` |
+| `launch` | How `reticle` was started: `npx`, `global`, `project` or `other` | Not the path it was started from; only the bucket leaves |
 | `projectIdSource` | Whether `projectId` came from a shared git origin or from the local directory path | Not the origin or the path. It exists so we can tell when "how many people share this project" is a real measurement. Outside a pushed repo there is nothing shared to hash, so those rows always show one user |
 | `version` | The Reticle version running | n/a |
 | `os` | The platform (`darwin` / `linux` / `win32`) | Not the OS version, hostname, or hardware |
@@ -104,14 +112,20 @@ Every event carries the same few fields:
 
 There are no IP-based profiles, no cookies, no fingerprinting, and no person profiles: events are processed in "personless" mode, so they are never joined into an identity.
 
+## The platform side
+
+When you sign in to Reticle and link a project, the platform (a separate service, with its own analytics) knows your email and your workspace, because you gave them to it. The open-source runtime never sends either. Once a project is linked, its events carry the workspace's id and nothing else about the account, so the two sides can be joined per workspace on that id. Emails stay on the platform side only. Unlinked, nothing in these events refers to an account at all.
+
+The sign-in page Reticle opens also says where the sign-in started (`from=terminal` or `from=hud`), so the platform can tell which one brought you in.
+
 ## What is never sent
 
-Your code. Your app's DOM, network requests or responses, console logs, application state, or screenshots. File paths, project names, or git remote URLs. Your name, email, employer, or any account identifier. Environment variables. Anything typed into the app under test. The names of your flows, baselines, or tests. Error messages, and any stack frame belonging to your application.
+Your code. Your app's DOM, network requests or responses, console logs, application state, or screenshots. File paths, project names, or git remote URLs. Your name, email or employer. Any account identifier, with one exception you opt into by linking a project: the workspace id, above. Environment variables. Anything typed into the app under test. The names of your flows, baselines, or tests. Error messages, and any stack frame belonging to your application.
 
 A few of these are worth being explicit about, because they are the ones a product team is most tempted by:
 
 - **We do not send your project's name or its GitHub URL.** `projectId` is a one-way hash. It lets us count distinct projects and see that a project came back next week; it cannot be turned back into a repository, and we cannot look you up from it.
-- **We do not try to work out who you work for.** No domain sniffing, no email inference, no matching a repo against a company. If you _want_ us to know, [`reticle identify`](#telling-us-who-you-are) exists and you decide what it says.
+- **We do not try to work out who you work for.** No domain sniffing, no email inference, no matching a repo against a company. If you _want_ us to know, [email us](#telling-us-who-you-are).
 - **We do not record what you asked your agent to verify.** The `verification_completed` event knows that a verification happened and how it turned out. The prompt behind it is not something Reticle can see, and we do not reconstruct it.
 
 ## Feedback
@@ -124,7 +138,7 @@ Reticle verifies apps for AI agents, and for a long time it had no way to hear w
 | --- | --- | --- |
 | Your agent | Calls the `reticle_session { action: "feedback" }` MCP tool (after a failure, **or to ask for a feature**) | What it wrote: an analysis, or a request with the goal behind it, what would improve, and how it works around the gap today. Plus the model it is running, which it tells us because MCP cannot |
 | You | Run `npx @reticlehq/server feedback [--rating 1-5] [--bug] "your words"` | Your words and your rating |
-| Your agent, before Reticle works | Runs `reticle feedback --agent --kind <bug\|gap\|ambiguity\|feature_request\|improvement> "what happened"` | The same words, filed from the shell. This exists for the phase where there is no daemon and no MCP tools (a failed `init`, half-finished wiring), which is the failure we are otherwise never told about |
+| Your agent, before Reticle works | Runs `npx @reticlehq/server feedback --agent --kind <bug\|gap\|ambiguity\|feature_request\|improvement\|experience> "what happened"` | The same words, filed from the shell. This exists for the phase where there is no daemon and no MCP tools (a failed `init`, half-finished wiring), which is the failure we are otherwise never told about |
 
 Agents are instructed, in the tool description itself, never to include app source, secrets, or user data, and to describe the failure in their own words instead.
 
@@ -156,25 +170,9 @@ Every switch in [Your choices](#your-choices) disables feedback too. If telemetr
 
 ## Telling us who you are
 
-Everything above is anonymous, and stays that way unless you decide otherwise. If you want us to know who you are (to get support, to ask about an enterprise licence, or to be a design partner), there is one command, and running it is the only way it ever happens:
-
-```bash
-npx @reticlehq/server identify --context company --company "Acme" --email you@acme.com
-```
-
-`--context` is the only required part, and `company | side_project | open_source | learning` is the whole vocabulary. You can say "this is a company" without naming it, or name it without leaving an email.
-
-Before it sends anything, it prints what it will send and one thing worth reading carefully: **the identity is linked to this machine's anonymous id, so identifying yourself also connects the anonymous usage already recorded from this machine to what you enter.** That is what makes it useful to us, and it is why you are told before choosing rather than after.
-
-**One place mentions it to you.** After you send feedback as a human (never as an agent, and never if you have already identified or already declined), the receipt prints one line offering this command, because a bug report we cannot reply to is a conversation that ends after one sentence. Your feedback has already been sent by then: the line is an offer, not a question, and nothing is gated on it. **No address is ever attached to the feedback itself**: it would put personal data on the anonymous stream, which is exactly what the rest of this page promises not to do.
-
-To undo it:
-
-```bash
-npx @reticlehq/server identify --forget
-```
+Everything above is anonymous, and stays that way. There is no command that sends who you are: `reticle identify`, which used to, has been removed, and this version never sends an `identified` event. If you want support, an enterprise licence, or to be a design partner, email support@reticlehq.com.
 
-That deletes the local file and stops any further sends. To have what was already sent removed, email support@reticlehq.com.
+An identity sent by an earlier version with `reticle identify` stays linked to that machine's anonymous id until you ask for it to be removed: email support@reticlehq.com.
 
 ## Where it goes
 

package/docs/testing.md

@@ -11,7 +11,7 @@ That makes this page two things at once, and both are the same code:
 - **You decide what "verified" means for your app**, in a file you own, in code you can read and keep in version control.
 - **Those same checks run in CI**, so the thing you wrote by hand is the thing that guards the branch.
 
-You will need `@reticlehq/test` installed, and your app already running. Write checks with `reticleTest(name, async (t) => …)`, open a headless session with `bootSession({ driveUrl, headless: true })`, and run them with `runSpecs`. Exit non-zero when `summary.failed` is not `0`.
+You will need `@reticlehq/test` installed, and your app already running. Write checks with `reticleTest(name, async (t) => …)`, open a headless session with `bootSession({ driveUrl, headless: true })`, and run them with `runSpecs`. Exit non-zero unless `summary.ok` is `true`.
 
 Checks bind to **signals and testids, never DOM structure**, so they survive the refactors that break selector-based suites.
 
@@ -74,7 +74,7 @@ const { summary } = await runSpecs({
   print: (line) => process.stdout.write(line + '\n'),
 });
 await booted.close();
-process.exit(summary.failed === 0 ? 0 : 1);
+process.exit(summary.ok ? 0 : 1);
 ```
 
 Each spec reports `pass` | `fail` (with evidence) | `skip` (with reason). For CI, emit JUnit:
@@ -107,10 +107,10 @@ No. `runSpecs` is its own runner: it takes the specs registered by `reticleTest`
 `runSpecs` never throws on a failing spec, so you have to read the summary and exit yourself:
 
 ```ts
-process.exit(summary.failed === 0 ? 0 : 1);
+process.exit(summary.ok ? 0 : 1);
 ```
 
-`summary` carries `{ total, passed, failed, skipped, ok }`. Note that **skipped is not failed**: a spec that skipped with a reason (see `t.expectInputModeReal()`) leaves `failed` at `0`.
+`summary` carries `{ total, passed, failed, skipped, ok }`. Branch on `ok`, not on `failed === 0`. **Skipped is not failed**: a spec that skipped with a reason (see `t.expectInputModeReal()`) leaves `failed` at `0`, but a suite in which every spec skipped verified nothing, so `ok` is `false` for it.
 
 ### Why did my hover or drag spec skip instead of running?
 

package/docs/token-efficiency.md

@@ -16,13 +16,13 @@ Measured against the bench dashboard (`apps/bench-app`) **with a 1,000-item list
 | ----------------------------------------------------------------------------- | ---------: |
 | **Playwright MCP**, with-refs snapshot (the real payload it sends every step) | **~7,300** |
 | Playwright MCP, bare accessibility tree (what we measured directly)           |     ~6,856 |
-| Reticle `snapshot` `full` (whole page, incl. all 1,000 items)                 |     ~4,144 |
-| Reticle `snapshot` `interactive` (actionable elements only)                   |       ~110 |
-| Reticle `snapshot` `status` (route / dialogs / counters)                      |        ~31 |
-| Reticle `query`, one element                                                  |        ~28 |
+| Reticle `look` page, mode `full` (whole page, incl. all 1,000 items)          |     ~4,144 |
+| Reticle `look` page, mode `interactive` (actionable elements only)            |       ~110 |
+| Reticle `look` page, mode `status` (route / dialogs / counters)               |        ~31 |
+| Reticle `look` find, one element                                              |        ~28 |
 | Reticle `observe` (reaction after an action)                                  |        ~39 |
 | Reticle `assert` verdict                                                      |        ~33 |
-| **Reticle, a full verify loop** (`query` + `observe` + `assert`)              |   **~100** |
+| **Reticle, a full verify loop** (`look` find + `observe` + `assert`)          |   **~100** |
 
 **Result on this page:** the common Reticle loop is **~73× leaner** than Playwright MCP's per-step snapshot (100 vs ~7,300 tokens). The bare a11y tree we measured directly is 6,856; Playwright MCP's actual payload adds a `[ref=…]` to every node, pushing it to ~7,300. On the complex pages Playwright's ecosystem cites (50k+), the gap widens to **~100× to 500×**.
 
@@ -50,25 +50,25 @@ Measured live, all servers in one run, same tokenizer (`bench/harness/schema-tax
 
 | MCP server                               | tools | schema tokens |
 | ---------------------------------------- | ----: | ------------: |
-| **Reticle, the tool surface**            |    18 |    **~4,930** |
+| **Reticle, the default surface**         |    10 |    **~4,650** |
 | Playwright MCP                           |    23 |         3,725 |
 | Chrome DevTools MCP                      |    29 |         5,116 |
-| Reticle, `RETICLE_ADVERTISE_ALL_TOOLS=1` |    30 |       ~30,200 |
+| Reticle, `RETICLE_ADVERTISE_ALL_TOOLS=1` |    30 |       ~35,000 |
 
-_Measured 2026-08-12 (`bench/raw/schema-tax.json`). Reticle's default surface has gained a tool since, so treat the first row as a floor._
+_Reticle rows measured 2026-10-08 with `node bench/harness/schema-tax.mjs reticle`. The Playwright and Chrome DevTools rows are from the full run of 2026-08-12 (`bench/raw/schema-tax.json`) and were not re-measured. Re-derive before quoting._
 
-The default surface is the verify loop plus `reticle_tools` and `reticle_run`. The cold tail is un-advertised rather than unreachable: `reticle_run { tool, args }` calls any registered tool by name, and `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises the whole table outright for suites that prefer that. Dropping the hatch was tried, and it left eleven registered tools callable by nothing at all.
+The default surface is the verify loop plus `reticle_tools` and `reticle_run`: ten tools, under merged names (`reticle_look { action }`, `reticle_observe { action }`). Examples in these docs use that spelling. The cold tail is un-advertised rather than unreachable: `reticle_run { tool, args }` calls any registered tool by name, and `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises 30 of them outright for suites that prefer that. Dropping the hatch was tried, and it left eleven registered tools callable by nothing at all.
 
-`RETICLE_ADVERTISE_ALL_TOOLS=1` advertises everything WITH output schemas. It is a verification switch for suites that call by name, not a mode to run agents in. It is roughly 7x the per-turn cost, which is why it is opt-in.
+`RETICLE_ADVERTISE_ALL_TOOLS=1` advertises 30 tools WITH output schemas, and switches to the unmerged spelling: `reticle_snapshot`/`reticle_query`/`reticle_inspect`/`reticle_state` replace `reticle_look`, `reticle_network`/`reticle_console` replace `reticle_observe { action }`, `reticle_wait_for` replaces `reticle_assert { action: "wait" }`, `reticle_sessions`/`reticle_feedback` replace `reticle_session` list/feedback, and `reticle_act_sequence` replaces `reticle_act { steps }`. It is a verification switch for suites that call by name, not a mode to run agents in. It is roughly 7x the per-turn cost, which is why it is opt-in.
 
-**Every absolute number in this section is a dated reading, not a current value.** The table above was measured on 2026-08-12; a later `tools/list` read on 2026-08-14 put the default surface at 21,468 bytes and the full one at 134,368. The surface has grown a tool since, so both readings are already low. The _shape_ of the gap is the durable claim; the counts themselves are asserted by `surface-sizes.test.ts`, which reads them off the live surface, and that is the only place to trust them.
+**Every absolute number in this section is a dated reading, not a current value.** The _shape_ of the gap is the durable claim; the tool counts are asserted by `server/src/surface/tools/surface-sizes.test.ts`, which reads them off the live surface.
 
 The typed result object still travels as `structuredContent` either way; the default surface simply does not advertise the output schema, which an agent reading the `text` block never consumed.
 
 ## The honest version
 
 - **Full-tree vs full-tree, the gap is modest (~1.8×):** Reticle `full` (4,144) vs Playwright's with-refs snapshot (~7,300). Reticle collapses generic wrapper nodes, but both include every list item. If you force Reticle to dump the whole page each step, you don't save much.
-- **The savings come from _not needing_ the full tree.** Playwright MCP's primary perception primitive is "return the accessibility tree"; Reticle's is "answer a specific question" (`query`/`assert`/`observe`/scoped or interactive `snapshot`). The win is architectural, not a cleverer serializer.
+- **The savings come from _not needing_ the full tree.** Playwright MCP's primary perception primitive is "return the accessibility tree"; Reticle's is "answer a specific question" (`reticle_look` find, `reticle_assert`, `reticle_observe`, or a scoped or interactive page read). The win is architectural, not a cleverer serializer.
 - **Cost scales with interactive elements + what you look at, not total DOM.** The 1,000 list items cost ~0 in `interactive` mode because they aren't interactive.
 - **This is tool-output tokens only.** The agent's own reasoning tokens dominate either way, which is the point: keep observation cheap so the budget goes to thinking.
 

package/docs/tools/act-and-wait.mdx

@@ -4,7 +4,7 @@ description: Act on an element and wait for a named consequence in one call. Thi
 icon: circle-check
 ---
 
-`reticle_act_and_wait` performs one action on an element and waits for a named consequence, returning a verdict in the same call. Reach for it whenever an action is supposed to cause something: it is one of only two Reticle tools that produce a verdict, the other being [`reticle_assert`](/tools/assert).
+`reticle_act_and_wait` performs one action on an element and waits for a named consequence, returning a verdict in the same call. Reach for it whenever an action is supposed to cause something: it produces a verdict. Verdicts come from `reticle_act_and_wait`, [`reticle_assert`](/tools/assert), `reticle_act { steps }` when a step declares `expect`, and `reticle_verify` (`change`/`flows`). Everything else moves or reads the app and proves nothing. Only `verified: "yes"` is a pass: `unknown` means Reticle could not tell, and `no-fault` means nothing was declared to prove.
 
 This is the tool Reticle exists for. It does the act, observe and assert steps in one round trip, and it makes you name the expected consequence **before** the action runs.
 
@@ -111,6 +111,7 @@ Real response. The `initiatorStack`, `storageDiffs` and per-event trace detail a
 | `console`                 | Something logged; `absent: true` asserts a clean console       |
 | `animation`               | An animation ran or finished                                   |
 | `settled`                 | The page went quiet                                            |
+| `compare`                 | Two readings agree                                             |
 | `allOf` / `anyOf` / `not` | Combine the above                                              |
 
 ### Predicates that catch real bugs
@@ -135,7 +136,7 @@ The app itself declared success. This is the highest grade of evidence, and it r
 
 ## Reading `verified`
 
-<CardGroup cols={3}>
+<CardGroup cols={2}>
   <Card title="yes" icon="circle-check">
     The named consequence happened, with evidence attached.
   </Card>
@@ -145,6 +146,10 @@ The app itself declared success. This is the highest grade of evidence, and it r
   <Card title="unknown" icon="circle-question">
     Reticle could not tell. **Not a pass.** Report it as unknown.
   </Card>
+  <Card title="no-fault" icon="circle-minus">
+    The page settled with nothing wrong, but nothing was declared to prove. **Not a pass.** Add an
+    `until` the action changes.
+  </Card>
 </CardGroup>
 
 ## The `honesty` block
@@ -158,10 +163,12 @@ A verification tool that cannot describe the quality of its own evidence is aski
 | Argument | What it does |
 | --- | --- |
 | `ref`, `action`, `args` | As [`reticle_act`](/tools/act) |
+| `target` | Find the element and act in one call, instead of a `ref`: `{ testid }`, `{ text }`, `{ role, name }` or `{ label }`. Refuses if it matches more than one |
 | `until` | The predicate to wait for. Omit it to wait for the page to settle |
 | `predicate` | Alias for `until`, the name `assert` and `wait_for` use |
 | `timeout_ms` | Maximum wait, defaulting to 4000. `0` evaluates the predicate once, no wait |
 | `refuseWhenThrottled` | Throw rather than act on a throttled tab |
+| `intent` | What the change is supposed to make true, in prose, or the id of an intent declared earlier. Recorded on the verdict |
 | `durable` | After a `yes`, reload the page and require the element, text and state parts of `until` to hold again. A consequence that is gone after the reload turns the verdict into `no`: the UI advanced, the change did not persist |
 
 Omitting `until` waits for network and DOM idle, which is the deterministic replacement for a fixed sleep. To assert a consequence **and** settle, combine them:

package/docs/tools/act-sequence.mdx

@@ -11,7 +11,7 @@ icon: layer-group
   `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
 </Warning>
 
-`reticle_act_sequence` runs several actions in order in a single round trip. Reach for it whenever a journey needs more than one step, such as fill, fill, submit, and then prove the outcome once with [`reticle_act_and_wait`](/tools/act-and-wait), because a sequence itself produces no verdict.
+`reticle_act_sequence` runs several actions in order in a single round trip. Reach for it whenever a journey needs more than one step, such as fill, fill, submit. A step that carries an `expect` (the same predicate shape as `until`) proves its consequence: the result then carries `verified`, and `stopped_at` plus the un-run `tail` if a step's `expect` did not hold. With `onDeviation: "continue"` it drives every step and reports every miss instead of stopping. A sequence with no `expect` anywhere proves nothing.
 
 A login is three actions. Driving it one call at a time costs three round trips and three turns of context. `reticle_act_sequence` does it in one.
 
@@ -29,7 +29,7 @@ This tool exists because of a measured problem: agents were driving forms one ca
 }
 ```
 
-Steps may also name a `target` instead of a `ref`, the same locator [`reticle_act`](/tools/act) takes. The sequence resolves each one before dispatch, so a login does not need a query round trip per field:
+Steps may also name a `target` instead of a `ref`, the same locator [`reticle_act`](/tools/act) takes. The sequence resolves each one when that step runs (waiting up to `timeout_ms` for it to appear), so a login does not need a query round trip per field, and a control an earlier step opens is still addressable:
 
 ```json
 {
@@ -109,10 +109,9 @@ Real response. Each `effects[]` entry also carries `targetMatched`, `visible`, `
 That password was wrong. The app rejected it. And this tool still reported `ok: true`, correctly, because `ok` means _the three actions were dispatched_, which they were.
 
 <Warning>
-  This is the whole reason `act` and `act_sequence` do not produce verdicts. `ok: true` is a
-  statement about the input, not about the outcome. Follow a sequence with
-  [`reticle_act_and_wait`](/tools/act-and-wait) on the final step, or with an
-  [`reticle_assert`](/tools/assert), or you have proved nothing.
+  `ok: true` is a statement about the input, not about the outcome. A step with no `expect` proves
+  nothing. Put an `expect` on the step that ends the journey, or finish with
+  [`reticle_act_and_wait`](/tools/act-and-wait) or [`reticle_assert`](/tools/assert).
 </Warning>
 
 The honest pattern is: batch the setup, prove the outcome.
@@ -132,7 +131,7 @@ then
 { "ref": "e605", "action": "click", "until": { "kind": "signal", "name": "auth:granted" } }
 ```
 
-which returns the verdict the sequence could not:
+which returns the verdict. Putting `"expect": { "kind": "signal", "name": "auth:granted" }` on the click step inside the sequence gets the same verdict in one call:
 
 ```json
 {

package/docs/tools/act.mdx

@@ -59,14 +59,14 @@ Real response:
 
 ## Actions
 
-`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag`
+`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `scroll` · `drag` · `tap` · `zoom`
 
 | Action           | Arguments                                                       |
 | ---------------- | --------------------------------------------------------------- |
 | `fill`, `select` | `{ value }`                                                     |
 | `type`, `press`  | `{ text }`. For `press`, the key _name_, e.g. `Escape` or `Tab` |
 | `drag`           | `{ toRef }`. The ref to drop onto                               |
-| `upload`         | file arguments                                                  |
+| `upload`         | `{ path }` (a file on disk) or `{ name, content?, type? }`      |
 
 ## Reading the effect block