@reticlehq/server 2.10.0 → 2.12.0

package/docs/license-activation.mdx

@@ -0,0 +1,145 @@
+---
+title: 'Activating a license key'
+description: 'Set your key, confirm it worked, and fix it when it did not. Everything an activation needs, with no account and no call.'
+icon: key
+---
+
+If your organisation has a Reticle license key, this page is everything you need to put it in place. There is no account to create, no login, and no call with us required.
+
+Do not have a key? Write to [hey@reticle.sh](mailto:hey@reticle.sh).
+
+## One key per organisation
+
+A key covers your whole organisation. Every developer and every machine uses the same one, so share it the way you would share any other build-time credential: your secrets manager, your onboarding doc, your CI configuration.
+
+## Set it
+
+Reticle reads one environment variable, `RETICLE_LICENSE_KEY`. Set it everywhere Reticle runs, which is usually more than one place.
+
+<CodeGroup>
+
+```bash macOS / Linux
+# In ~/.zshrc, ~/.bashrc, or your team's equivalent.
+export RETICLE_LICENSE_KEY="your-key-here"
+```
+
+```powershell Windows
+[Environment]::SetEnvironmentVariable('RETICLE_LICENSE_KEY', 'your-key-here', 'User')
+```
+
+```yaml GitHub Actions
+env:
+  RETICLE_LICENSE_KEY: ${{ secrets.RETICLE_LICENSE_KEY }}
+```
+
+```bash Docker
+docker run -e RETICLE_LICENSE_KEY="your-key-here" your-image
+```
+
+</CodeGroup>
+
+An export only affects shells started after it, so open a new terminal or `source` your profile.
+
+### Editors and agents that launch Reticle themselves
+
+<Warning>
+  This is the step teams most often miss. Claude Desktop, Cursor and similar tools launch from the
+  desktop rather than from a terminal, so they never read your shell profile. An `export` that
+  plainly works in your terminal is invisible to them, and Reticle reports itself unlicensed.
+</Warning>
+
+Put the key in the MCP server's own `env` block instead, then restart the editor. Configuration is read at startup.
+
+```json
+{
+  "mcpServers": {
+    "reticle": {
+      "command": "npx",
+      "args": ["@reticlehq/server", "mcp"],
+      "env": {
+        "RETICLE_LICENSE_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+## Confirm it worked
+
+```bash
+npx @reticlehq/server license
+```
+
+You do not need `NODE_ENV` set, a project, a dev server, or a running app. This reads the key and nothing else.
+
+| `status` | What it means | What to do |
+| --- | --- | --- |
+| `active` | Valid and in date. | Nothing. You are done. |
+| `missing` | Reticle found no key in its environment. | The variable is not visible to this process. See below. |
+| `expired` | The key was valid and its term has ended. | Contact us to renew. |
+| `invalid` | The key was not accepted. | Usually a copy or paste problem. See below. |
+| `eval` | This build has no licensing configured. | You are on a build older than licensing. Update. |
+
+## Over time
+
+Your key carries an expiry, shown in the `license` output. A renewal is a new key for the same organisation: replace the value everywhere you set it, and nothing else changes.
+
+Nothing breaks without warning. An expired key reports `expired` rather than failing silently, and you can check at any time with the command above.
+
+Activation is **offline**. Reticle verifies your key cryptographically on your own machine, so there is no license server to reach. It works behind a firewall, on an air-gapped machine, and during any outage on our side.
+
+## When it does not work
+
+<AccordionGroup>
+
+<Accordion title="It says missing, but the variable is definitely set">
+The commonest cause by a distance is that Reticle is being launched by something that does not
+inherit your shell environment: an editor, a desktop agent, a systemd unit, a container. Run
+`echo $RETICLE_LICENSE_KEY` in the same context Reticle runs in, not just in your own terminal. If
+an editor launches it, use the MCP `env` block above.
+
+Second commonest: the variable was set in a shell that was already open. Environment variables are read when a process starts, so open a new terminal and restart anything long-running.
+
+</Accordion>
+
+<Accordion title="It says invalid">
+The key changed between us sending it and Reticle reading it. Almost always one of:
+
+- truncated, most often by a line wrap when pasted into a config file or a chat client
+- a character dropped or added while copying by hand
+- quoted in a way that swallowed a character
+
+Surrounding whitespace and a trailing newline are tolerated, so neither is the cause. Copy the key again in one piece. If it still reports `invalid`, write to us and we will re-issue it.
+
+</Accordion>
+
+<Accordion title="command not found: reticle">
+  Use the `npx @reticlehq/server ...` form shown on this page. It runs without a global install, and
+  it is the form we support.
+</Accordion>
+
+</AccordionGroup>
+
+## What a licensed deployment reports
+
+Stated plainly, because a security review will ask.
+
+Activation itself makes **no network request**. Your key is verified on your machine with public key cryptography.
+
+Separately, Reticle sends anonymous usage metrics, as it does for every user. On a licensed deployment these carry your **license id**, an opaque identifier that means nothing without our own records, so we can tell your organisation's usage apart from everyone else's and know when to talk to you about renewal.
+
+Never sent, licensed or not: your source code, your application's data, your users' data, URLs, selectors, page content, file contents, or your organisation's name.
+
+The kill switch has no exception for licensed installations:
+
+```bash
+export RETICLE_TELEMETRY=0
+```
+
+`DO_NOT_TRACK=1` is honoured identically. If your policy forbids outbound telemetry, set it. Your activation is unaffected, because activation never needed the network. To keep your own usage data without sending it, `RETICLE_TELEMETRY_FILE=/path/to/file.jsonl` records the same stream locally and sends nothing.
+
+## Getting help
+
+[hey@reticle.sh](mailto:hey@reticle.sh) for activation problems, renewals and re-issues.
+
+Include the output of `npx @reticlehq/server license`. It carries your license id and no secrets, and it usually tells us the answer immediately.

package/docs/packages/browser.mdx

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

package/docs/packages/server.mdx

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

package/docs/packages.mdx

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

package/docs/platform-integration.md

@@ -93,6 +93,23 @@ Live, clickable demo of each: `apps/vibe-builder-demo/` (set `BUG_MODE=…`). Pr
 
 ---
 
+## The minimal attach contract (for a harness or MCP host)
+
+Reticle is a stdio MCP server. A host that wires it correctly does four things, and each one is a step Reticle can see:
+
+1. **Spawn it.** `npx @reticlehq/server mcp`, over stdio, one process per host. That process is the proxy: it starts the local daemon on demand, reconnects on its own when the stream drops, and answers from cache while a daemon comes back.
+2. **Complete `initialize`.** Reticle answers the handshake itself when the daemon is slow, so a host that waits for a reply gets one either way.
+3. **Send `tools/list`, and send it again on `notifications/tools/list_changed`.** This is the step hosts skip. Registering a server is not the same as enumerating it: a host can register Reticle and never ask for the tool list until the client is restarted, and the model then has no Reticle tools at all while the install looks healthy from every other angle. Reticle declares `tools.listChanged` so a host that honours the notification recovers without a restart.
+4. **Call the tools.** `tools/call`, with the tool name and its arguments.
+
+`reticle status` reports how far a host has got. `mcpClient: "never-attached"` means no client has started the server on this port. `mcpClient: "never-enumerated"` means one started it and never asked for the tool list, which is the state a client restart fixes. `mcpClient: "enumerated"` means the client side is done, and anything still missing is the app rather than the host. The record is per port rather than per client, and it begins the first time a client starts a Reticle version that keeps it, so `status` says both of those out loud instead of naming a client it cannot see.
+
+### Hosts that cap the number of tools
+
+Some editors cap the total tool count across every MCP server, which is why Reticle advertises a small surface instead of everything it can do. Nothing is out of reach: `reticle_tools { names: [...] }` lists the tools and returns the full argument grammar for the ones you name, and `reticle_run { tool, args }` invokes any of them, advertised or not. A host that is short on tool slots pays for the advertised handful and still reaches the whole surface through that pair. See [`reticle_tools` and `reticle_run`](/tools-tools-and-run).
+
+---
+
 ## Exact steps per platform
 
 The shape is identical (in-app SDK in the template → verify in the sandbox → act on the verdict); the specifics differ by where each platform runs the preview.

package/docs/predicates.mdx

@@ -115,6 +115,14 @@ A passing route verdict quotes the transition itself:
 
 The app emitted a named signal via `reticle.signal()`. `dataMatches` is shallow JSON matching, and `*` means "present, any value".
 
+`count` works here exactly as it does on `net`:
+
+```json
+{ "kind": "signal", "name": "order:placed", "count": 1 }
+```
+
+**Exactly once.** A handler wired twice fires the signal twice and leaves the store in the right shape either way, so every state-only check stays green. `count: 0` is a claim of its own (the signal never fired) and is not the same as leaving `count` out, which asserts presence.
+
 Nothing outranks this. A `200` proves the server was reachable; a rendered row proves React ran. A signal is the application itself saying the thing succeeded. See [instrumentation](/instrumentation) for how to emit them.
 
 ### state

package/docs/reticle-manual.md

@@ -0,0 +1,106 @@
+---
+title: 'Reticle: what each tool actually does'
+description: Generated from real calls against a running app. Every row is a probe that ran and the answer it got.
+icon: table-list
+---
+
+**Generated by `bench/harness/behaviour-matrix.mjs`. Do not edit by hand.**
+
+Every row below is a call that was made against a running app and the answer that came back. Nothing here is described from the source or from intent. If a claim has no probe behind it, it is not in this file. That is the whole point: the hand-written guides drifted, and the drift was invisible because nobody ran them.
+
+`refused (names the fix)` means the error told you what to call instead, so you can correct without reading anything else. `refused (no fix named)` means it did not.
+
+## reticle_snapshot
+
+| you call it with | you get back | bytes |
+| --- | --- | --- |
+| an argument the tool does not declare: `{"thisArgDoesNotExist":1}` | refused (names the fix) | 273 |
+| the documented call: `{"mode":"interactive"}` | ran | 434 |
+| a value outside the allowed set: `{"mode":"not-a-mode"}` | refused (names the fix) | 236 |
+
+## reticle_query
+
+| you call it with | you get back | bytes |
+| --- | --- | --- |
+| an argument the tool does not declare: `{"thisArgDoesNotExist":1}` | refused (names the fix) | 368 |
+| the documented call: `{"by":"role","value":"button"}` | ran | 200 |
+| a value outside the allowed set: `{"by":"telepathy","value":"x"}` | refused (names the fix) | 290 |
+
+## reticle_network
+
+| you call it with | you get back | bytes |
+| --- | --- | --- |
+| an argument the tool does not declare: `{"thisArgDoesNotExist":1}` | refused (names the fix) | 354 |
+| the documented call: `{"limit":5}` | ran | 1175 |
+| a number outside its range: `{"limit":-1}` | refused (names the fix) | 222 |
+
+## reticle_console
+
+| you call it with | you get back | bytes |
+| --- | --- | --- |
+| an argument the tool does not declare: `{"thisArgDoesNotExist":1}` | refused (names the fix) | 293 |
+
+## reticle_state
+
+| you call it with | you get back | bytes |
+| --- | --- | --- |
+| an argument the tool does not declare: `{"thisArgDoesNotExist":1}` | refused (names the fix) | 268 |
+| a number outside its range: `{"depth":-5}` | refused (names the fix) | 173 |
+| the documented call: `{"depth":2}` | ran | 210 |
+
+- a negative depth was silently ignored before v2.12.0
+
+## reticle_observe
+
+| you call it with | you get back | bytes |
+| --- | --- | --- |
+| an argument the tool does not declare: `{"thisArgDoesNotExist":1}` | refused (names the fix) | 305 |
+
+## reticle_act_and_wait
+
+| you call it with | you get back | bytes |
+| --- | --- | --- |
+| no expectation declared: `{"ref":"e1005","action":"click"}` | verified:no-fault | 1343 |
+| the documented call: `{"ref":"e1105","action":"click","until":{"kind":"text","value":"Invalid email or password"},"timeout_ms":6000}` | verified:yes | 1297 |
+| no expectation declared: `{"ref":"e1205","action":"click","until":{"kind":"settled"}}` | verified:no-fault | 1343 |
+| a value outside the allowed set: `{"ref":"e903","action":"click","until":[{"kind":"text","value":"x"}]}` | refused (names the fix) | 399 |
+| a ref that no longer resolves: `{"ref":"e999999","action":"click"}` | refused (names the fix) | 519 |
+
+- no `until`: this returned verified:"yes" before v2.12.0
+
+- a consequence the click CAUSES: the shape that earns verified:"yes"
+
+- an explicit `{kind:"settled"}` is the idle wait, not a declaration, so it grades no-fault too
+
+- a bare array is not a predicate
+
+## reticle_act
+
+| you call it with | you get back | bytes |
+| --- | --- | --- |
+| a required argument omitted: `{"ref":"e901"}` | refused (names the fix) | 192 |
+| a value outside the allowed set: `{"ref":"e901","action":"teleport"}` | refused (names the fix) | 415 |
+| an argument the tool does not declare: `{"ref":"e901","action":"fill","value":"x"}` | refused (names the fix) | 314 |
+| the documented call: `{"ref":"e901","action":"fill","args":{"value":"probe"}}` | refused (names the fix) | 516 |
+
+- action arguments nest under `args`
+
+## reticle_assert
+
+| you call it with | you get back | bytes |
+| --- | --- | --- |
+| a required argument omitted: `{}` | refused (names the fix) | 592 |
+| the documented call: `{"predicate":{"kind":"text","value":"Sign in"},"timeout_ms":3000}` | verified:yes | 794 |
+
+## reticle_tools
+
+| you call it with          | you get back            | bytes |
+| ------------------------- | ----------------------- | ----- |
+| the documented call: `{}` | refused (names the fix) | 246   |
+
+## reticle_run
+
+| you call it with | you get back | bytes |
+| --- | --- | --- |
+| a value outside the allowed set: `{"tool":"reticle_nope","args":{}}` | refused (names the fix) | 894 |
+| the documented call: `{"tool":"reticle_context","args":{}}` | ran | 54 |

package/docs/telemetry-contract.md

@@ -103,7 +103,6 @@ The single exception is `daemon_stopped`, which is **awaited**, because the proc
 | `identified` | `reticle identify` | joins anonymous machine ids to a person who volunteered one |
 | `mcp_client_connected` | an MCP client attached | how many sessions are agent-driven at all |
 | `app_instrumented` | the first app carrying the SDK reached this daemon | **the funnel step everything turns on**; see below |
-| `instrumentation_stalled` | the daemon waited and no app ever arrived | the same funnel step, seen from the failure side; see below |
 | `mcp_connection_lost` | the proxy lost its daemon | **the transport-stability metric.** The disconnect that makes a user reopen `/mcp` is invisible without it |
 | `init_completed` | `reticle init` finished | does install actually work, outside the fixtures gate |
 | `bug_found` | a defect was detected in the app under test | the value delivered, as opposed to the work done |
@@ -117,17 +116,7 @@ Nothing measured the second. `daemon_started` and `mcp_client_connected` describ
 
 `app_instrumented` fires **once per daemon run**, on the first session-ready only, so `daemon_started` → `app_instrumented` is a rate rather than an inference and a reloading page cannot inflate it. It carries `initialized` (had `init` run here), `agentAttached` (was an agent already waiting), and `msToFirstApp` (how long the daemon sat with nothing wired). It deliberately carries no stack and no framework: `project_profiled` already reports both for the same run, and the two join on `sessionId`.
 
-### The counterpart: `instrumentation_stalled`
-
-`app_instrumented` fires on success and only on success, so the larger population, runs where no app ever arrives, exists in the data as an **absence**. An absence is the one thing telemetry cannot interpret: it cannot separate "nothing was ever wired" from "the process was killed before it could say so" from "we never sent the event". Since the funnel breaks at this step and nowhere else, this is the one silence worth converting into a signal.
-
-`instrumentation_stalled` fires **once per daemon run**, only after the daemon has been up past a generous threshold, and **never once an app has connected**. A run that starts slowly and then works reports nothing at all. It carries the same three facts as its success counterpart so the two are directly comparable, with `msWaited` in place of `msToFirstApp`.
-
-Read it against `agentAttached`, which is what makes it actionable rather than merely sad. A stalled daemon with no agent attached is somebody who installed and walked away, and is not a defect. A stalled daemon **with** an agent attached is the failure the product actually has: the tools are loaded, something is asking for them, and there is nothing on the other end to drive.
-
-It deliberately carries no diagnosis. Whether a dev server is listening is a live probe, and running one on a timer to enrich a metric would be collecting for the metric's sake. The diagnosis belongs where a human or an agent asks for it.
-
-What neither event can see is **why** an app never connected. Every cause for that is page-side (the non-localhost gate, a port mismatch, a stale build, a dev server never restarted), where the daemon has no visibility. That needs the SDK to report its own refusals, and it is the next thing to build.
+The failure side is a **set difference**, not an event: `daemon_started` minus `app_instrumented`, joined on `sessionId`. There used to be an `instrumentation_stalled` event for it, and it was removed because the derivation is strictly more complete. The event could only fire on a flush tick or a graceful shutdown, so a killed daemon never produced one and landed in the absence anyway, while the set difference catches it. Two ways to compute one number, disagreeing with each other, is worse than one way.
 
 ## Sessions: `daemon_stopped` vs `session_progress`
 

package/docs/telemetry-events.mdx

@@ -55,7 +55,7 @@ Plus `installSource`, which is not a block. It is resolved once per process and
 
 `isSessionScoped(kind)` decides whether `sessionId` is attached. Twelve kinds are session-scoped:
 
-`daemon_started`, `daemon_stopped`, `session_progress`, `mcp_client_connected`, `app_instrumented`, `instrumentation_stalled`, `project_profiled`, `verification_completed`, `bug_found`, `tool_refused`, `runtime_crashed`, `feedback_submitted`.
+`daemon_started`, `daemon_stopped`, `session_progress`, `mcp_client_connected`, `app_instrumented`, `project_profiled`, `verification_completed`, `bug_found`, `tool_refused`, `runtime_crashed`, `feedback_submitted`.
 
 `mcp_connection_lost` is deliberately **not** on that list even though it feels session-shaped. It fires from the proxy process rather than the daemon, so it carries no `sessionId` and cannot be joined to a session at all.
 
@@ -341,39 +341,6 @@ Fired **once per daemon run**, on the first connect only, so `daemon_started` to
 
 ---
 
-## instrumentation_stalled
-
-**Wire name:** `instrumentation_stalled`. **Emitted from:** `packages/server/src/telemetry/instrumentation-stall.ts:73`, called from `daemon-telemetry.ts:105`. **Session-scoped:** yes. **Payload block:** `stall`.
-
-The failure side of `app_instrumented`, and the reason the funnel has a denominator at all. A daemon that runs for ten minutes without a single SDK-carrying page is an install that half worked, and until this event existed that outcome was pure silence: indistinguishable from a machine nobody touched.
-
-| Field | Type | Meaning |
-| --- | --- | --- |
-| `initialized` | boolean | Has `init` run in this working directory (`readProjectId(cwd)` resolves). False means the daemon is running somewhere `init` never wrote a project id, which is usually a wrong-directory problem rather than a wiring one |
-| `agentAttached` | boolean | Was an agent connected at the moment the check ran. **This is the field that decides whether the row is a defect.** False means somebody installed and walked away, which is not a bug. True means an agent was sitting there with tools it could not use, which is the failure the product actually has |
-| `msWaited` | int | Milliseconds since the daemon started, from the clock marked at `daemon-telemetry.ts:84` |
-
-Deliberately the same three facts as `app_instrumented`, with `msWaited` standing in for `msToFirstApp`, so the success and failure rows are directly comparable without reshaping either.
-
-**When it fires:** on every flush tick, but only once all four guards at `instrumentation-stall.ts:64` pass: it has not already been reported this run, no app has ever connected, the clock was marked, and at least `STALL_AFTER_MS` (10 minutes) has elapsed. It is checked **before** the empty-window early return in `flushWindow`, which is not an accident: a stalled install produces an empty window by definition, so checking after the return would blind the event to the exact condition it exists to report.
-
-**The question it answers:** of the installs that never reach a verdict, how many had an agent present and waiting? That is the difference between a distribution problem and a wiring problem, and they need opposite responses.
-
-**What it is blind to:**
-
-- **Any diagnosis.** It never says whether a dev server is listening, because that is a live probe, and probing a user's machine to enrich a metric is collecting for the metric's sake.
-- **Slow starts.** A run that connects at minute eleven reports nothing at all, and neither does the recovery. The event answers "did this run stall", not "how long do installs take".
-- **The page side.** Every real cause (a non-localhost gate, a port mismatch, a stale build, a dev server never restarted) lives where the daemon cannot see. Attributing a stall needs the SDK to report its own refusals, and that is not built.
-- **Repeats.** Once per daemon run, so a user stuck for a week contributes one row per daemon start, not one per hour.
-
-<Warning>
-  This kind has no live check in `apps/e2e/specs/telemetry-events-test.mjs`, and neither do
-  `session_progress` and `app_instrumented`. Those three are the funnel, and the funnel is the part
-  of the wire nothing fires end to end. Adding one is the highest-value thing left in this file.
-</Warning>
-
----
-
 ## mcp_connection_lost
 
 **Wire name:** `mcp_connection_lost`. **Emitted from:** `packages/server/src/mcp/mcp-outage.ts:53`. **Session-scoped:** no. **Payload block:** `outage`.

package/docs/telemetry.md

@@ -31,7 +31,6 @@ Eighteen kinds of events, each a single small JSON object. This is the whole lis
 | `daemon_stopped` | The local daemon stops | A summary of the session; see below |
 | `session_progress` | Periodically, from a daemon that is still running | The same summary as `daemon_stopped`, marked `final: false`. It exists so a long session is not invisible until it exits |
 | `app_instrumented` | The first time your app's SDK connects in a given daemon run | Nothing beyond the common fields. It is the second half of the install funnel: registering the MCP server is one thing, getting the SDK into a running page is another |
-| `instrumentation_stalled` | Ten minutes into a daemon run in which your app has still never connected | The same three facts as `app_instrumented`, with how long it waited instead of how long it took. It fires at most once per daemon run, and a run that starts slowly and then works reports nothing at all. It carries no diagnosis: whether a dev server is listening would need a live probe, and probing your machine to enrich a metric is collecting for the metric's sake |
 | `verification_completed` | A verification produces a verdict | Whether it passed, whether Reticle refused to call a passing check verified, and **why** the verdict came out that way; see below |
 | `project_profiled` | Once per daemon start | The shape of the project; see below |
 | `version_changed` | You update or roll back | The two version numbers, and which direction |

package/docs/tools-tools-and-run.mdx

@@ -6,9 +6,7 @@ icon: boxes-stacked
 
 `reticle_tools` lists every Reticle tool and, on request, returns the full argument grammar for the ones you name. `reticle_run` then invokes any of them. Reach for the pair whenever you need a capability that is not in the default advertised surface, which is most of what Reticle can do.
 
-Reticle ships 46 tools plus these two meta-tools. On the default profile your agent is shown 17 of them plus the meta pair, so 29 sit in the cold tail. These two are how it reaches those 29 without paying for their schemas on every turn.
-
-`reticle_tools` discovers. `reticle_run` invokes. Together they cost two tool definitions instead of twenty-nine.
+`reticle_tools` discovers. `reticle_run` invokes. Together they cost two tool definitions instead of the rest of the catalog.
 
 ## Discovering what exists
 
@@ -41,7 +39,7 @@ The response also tells you which surface is active:
   "profile": {
     "active": "all",
     "source": "RETICLE_ADVERTISE_ALL_TOOLS set in the DAEMON's environment at startup",
-    "note": "The profile is read once at daemon startup: change RETICLE_TOOL_PROFILE and restart the daemon, or it has no effect. Under this profile every unadvertised tool is reachable through reticle_run; under `full` there are no meta-tools because every tool is advertised directly."
+    "note": "The surface is read once at daemon startup: set RETICLE_ADVERTISE_ALL_TOOLS=1 and restart the daemon, or it has no effect. No surface advertises every tool: the advertised count is capped because editors budget tools across all connected MCP servers. Every tool listed here is callable through reticle_run { tool, args } whether or not it is advertised."
   },
   "next": "Load params with reticle_tools { names:[…] }, then call reticle_run { tool, args }."
 }

package/docs/troubleshooting.mdx

@@ -83,6 +83,15 @@ the URL explicitly (Vite: VITE_RETICLE_WS_URL, or reticle.connect({ url })). An
 open a ws:// socket at all. Still retrying…
 ```
 
+**You should not have to read this page to find that out.** If the agent opened the app with `reticle_lease`, which is the path `init` steers it to, the daemon reads that address off the page's own console, compares it with the port it is bound to, and puts the mismatch in the tool result:
+
+```
+The page dialled ws://localhost:4460/reticle (port 4460) and this daemon is on
+4400, so the dial never reached it. Nothing about the app's wiring is in question.
+```
+
+Neither side can work that out alone: the page cannot see the daemon, and the daemon never saw a dial that went somewhere else. The rest of this section covers what the lease cannot: a tab you opened yourself, or an app the pool cannot reach.
+
 That message names the exact address it tried. Compare its port with `bridge port` from `doctor` and set whichever is wrong:
 
 ```bash

package/docs/usage.md

@@ -183,7 +183,7 @@ The timeline + summary of what happened.
 
 Act, then wait for a predicate: the whole act→observe→assert loop in one hop.
 
-- **args:** `ref`, `action`, `args?`, `until: <predicate>`, `timeout_ms?` (default 4000; 0 = evaluate once), `refuseWhenThrottled?`, `sessionId?`.
+- **args:** `ref`, `action`, `args?`, `until: <predicate>`, `timeout_ms?` (default 4000; 0 = evaluate once), `refuseWhenThrottled?`, `intent?`, `sessionId?`.
 - **returns:** `{ effect, verdict, trace, session, warning? }`. `effect` is the action result (`{ ok, ref, action }`), `verdict` is `{ pass, evidence?, failureReason? }`, `trace` is the reaction report of everything the app did after the action, and `session` is the tab-health block `{ lastSeenMs, throttled, focused }` (with a `warning` when throttled). A failing `verdict` still returns `effect` + `trace` so you can see what _did_ happen. The predicate is automatically floored at this act's cursor, so it only matches events the action actually caused.
 
 ### `reticle_wait_for`
@@ -197,9 +197,10 @@ Block until a predicate holds (or time out). Looks both backward (recent buffer)
 
 Verify a predicate; optionally wait for it.
 
-- **args:** `predicate`, `timeout_ms?` (0 = evaluate once), `since?`, `sessionId?`.
+- **args:** `predicate`, `timeout_ms?` (0 = evaluate once), `since?`, `intent?`, `sessionId?`.
 - Same `since` default as `reticle_wait_for`: scoped to your last act so a stale buffered event can't fake a pass; override with an explicit `since`.
 - **returns:** `{ verified, because, pass, evidence, contradictions?, coverage?, failureReason?, session, warning? }`. On failure includes a **near-miss** (e.g. "found the dialog but not visible", or "no button named 'Submit'; saw: Cancel"). The `session` block `{ lastSeenMs, throttled, focused }` reports tab health on every assert; when throttled a `warning` is attached so you never assert against a tab that is silently no-oping.
+- **`intent` declares what the change was FOR, inline.** Pass a sentence in your own words and it lands in `.reticle/intent.json`, the same git-checked ledger `reticle_intent` writes, before the verdict is drawn; a green verdict then marks it proved and names itself as the proof. Pass the **id** of an intent you already declared instead, to point several verdicts at one statement rather than restating it. `reticle_act_and_wait` takes the same argument. Omit it and nothing is written.
 - **Read `verified`, not `pass`.** `pass` says the predicate held; `verified` says whether that means anything. It is `"no"` when a channel contradicts the assertion (a failed write under a green screen, a batch whose body reports per-item failures, a request still in flight), and `"unknown"` when the outcome could not be known yet: a `202 Accepted` that has not reconciled, or a write whose response body was never recorded. `because` names the deciding evidence in one sentence.
 
 ### `reticle_reconcile`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "Reticle bridge + MCP server. Hosts the browser WS endpoint and exposes MCP tools to the coding agent.",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "ws": "^8.21.3",
     "zod": "^3.24.1",
-    "@reticlehq/core": "2.10.0"
+    "@reticlehq/core": "2.12.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",

package/dist/session/session-readiness.d.ts

@@ -1,34 +0,0 @@
-/**
- * First-run readiness: the agent often issues its first tool call in the window between `reticle init`
- * and the app's SDK actually connecting its WebSocket — so a naive resolve throws "no session". This
- * lets the agent (via reticle_wait_ready) BLOCK briefly until a session appears instead of failing the
- * race, smoothing the most common first-5-minutes footgun.
- *
- * Pure control loop: the session count, clock, and sleep are all injected, so it is unit-tested with
- * no real timers — and in production it polls a real `setTimeout` sleep.
- */
-interface WaitForReadyOptions {
-    /** Live count of connected sessions (SessionManager.count). */
-    count: () => number;
-    /** Give up after this much elapsed time. */
-    timeoutMs: number;
-    /** Injected monotonic clock (ms). */
-    now: () => number;
-    /** Injected delay between polls. */
-    sleep: (ms: number) => Promise<void>;
-    /** Poll interval (ms). Default 25 — see DEFAULT_POLL_MS. */
-    pollMs?: number;
-}
-/**
- * One-line orientation for a FRESH agent — the Reticle loop, returned by reticle_wait_ready (the first call)
- * so an agent learns how to drive Reticle without reading docs. Named so it is not a free string; kept
- * terse on purpose (it rides the first response, where token budget is tightest).
- */
-export declare const RETICLE_LOOP_GUIDE: string;
-/**
- * Resolve `true` as soon as at least one session is connected, or `false` if the timeout elapses
- * first. Returns immediately when a session is already connected (the common, already-ready case —
- * so this never adds latency on the happy path, including the benchmark which always has a session).
- */
-export declare function waitForReady(opts: WaitForReadyOptions): Promise<boolean>;
-export {};

package/dist/session/session-readiness.js

@@ -1,36 +0,0 @@
-/**
- * Same reasoning as session-reconnect: the check is an in-memory lookup and the thing awaited is an
- * event (a session registering), so a coarse grid only adds latency to the first call an agent
- * makes. Four times the checks of something with no I/O costs nothing measurable.
- */
-const DEFAULT_POLL_MS = 25;
-/**
- * One-line orientation for a FRESH agent — the Reticle loop, returned by reticle_wait_ready (the first call)
- * so an agent learns how to drive Reticle without reading docs. Named so it is not a free string; kept
- * terse on purpose (it rides the first response, where token budget is tightest).
- */
-export const RETICLE_LOOP_GUIDE = 'Reticle loop — LOOK: reticle_snapshot / reticle_query / reticle_inspect · ACT: reticle_act (or reticle_act_and_wait) · ' +
-    'OBSERVE: reticle_observe / reticle_wait_for / reticle_network / reticle_console · ASSERT: reticle_assert over program ' +
-    'truth, not just the DOM · REGRESS: reticle_record{action:"start"} → reticle_replay, or reticle_verify{action:"flows"} for the whole ' +
-    'suite. The human can flag bugs from the panel — drain them with reticle_session{action:"review"} and resolve each once fixed. ' +
-    'MANDATORY: the moment you stop driving — finishing your reply or waiting on the human — call reticle_session {action:"yield"} ' +
-    '(mode:"waiting", or mode:"ask" with the question) so the panel shows your real state; reticle_session{action:"end"} ' +
-    'only when the whole task is done. Never leave the panel reading "live" when you have actually stopped.';
-/**
- * Resolve `true` as soon as at least one session is connected, or `false` if the timeout elapses
- * first. Returns immediately when a session is already connected (the common, already-ready case —
- * so this never adds latency on the happy path, including the benchmark which always has a session).
- */
-export async function waitForReady(opts) {
-    if (opts.count() > 0)
-        return true;
-    const start = opts.now();
-    const poll = opts.pollMs ?? DEFAULT_POLL_MS;
-    for (;;) {
-        if (opts.now() - start >= opts.timeoutMs)
-            return opts.count() > 0;
-        await opts.sleep(poll);
-        if (opts.count() > 0)
-            return true;
-    }
-}