@reticlehq/server 2.9.0 → 2.11.0

package/docs/capabilities.mdx

@@ -15,7 +15,7 @@ These work through the always-on SDK, in any connected session.
 ### Coverage: what you have not driven yet
 
 ```json
-{ "tool": "reticle_coverage" }
+{ "tool": "reticle_verify", "args": { "action": "coverage" } }
 ```
 
 ```json
@@ -90,7 +90,7 @@ Freeze the clock, advance it by exactly the interval, assert the consequence. No
 ### Crawl: click everything, report anomalies
 
 ```json
-{ "tool": "reticle_crawl", "args": { "maxSteps": 6 } }
+{ "tool": "reticle_verify", "args": { "action": "crawl", "maxSteps": 6 } }
 ```
 
 ```json
@@ -327,7 +327,7 @@ The loop closer, and the reason Reticle is not only an interactive tool.
 { "tool": "reticle_record", "args": { "action": "start", "recordingName": "ship-a-deploy" } }
 { "tool": "reticle_record", "args": { "action": "stop", "recordingName": "ship-a-deploy" } }
 { "tool": "reticle_flow_save", "args": { "flowName": "ship-a-deploy" } }
-{ "tool": "reticle_flow_verify" }
+{ "tool": "reticle_verify", "args": { "action": "flows" } }
 ```
 
 <Warning>
@@ -396,7 +396,7 @@ Nine hundred and fifty-three bytes for 445 recorded events. `timeline_omitted` h
 
 Reticle grades the flow as you save it, and tells you when you have just created a test that cannot fail. Take the warning seriously: an assertion-free flow replays green whatever the app does.
 
-A replay against a drifted app names what moved and where. This is `reticle_flow_verify` reporting the same flow after the app changed underneath it:
+A replay against a drifted app names what moved and where. This is `reticle_verify {action:"flows"}` reporting the same flow after the app changed underneath it:
 
 ```json
 {

package/docs/cli/hunt.mdx

@@ -4,7 +4,7 @@ description: Aggregate many crawl reports into one false-green rate across alrea
 icon: crosshairs
 ---
 
-`reticle hunt` is arithmetic, not driving. You point it at a directory of crawl reports (one JSON file per checkout, each produced by `reticle_crawl`) and it turns the pile into the one number the core claim needs: across N already-merged, already-green changes, how many carried a candidate false green?
+`reticle hunt` is arithmetic, not driving. You point it at a directory of crawl reports (one JSON file per checkout, each produced by `reticle_verify {action:"crawl"}`) and it turns the pile into the one number the core claim needs: across N already-merged, already-green changes, how many carried a candidate false green?
 
 ```bash
 npx @reticlehq/server hunt <dir-of-crawl-reports>
@@ -66,7 +66,7 @@ That path exits `1`.
 ```bash
 for sha in $(git log --format=%H -n 30 main); do
   git checkout "$sha" && npm run dev &
-  # drive reticle_crawl over the app, write the JSON:
+  # drive reticle_verify {action:"crawl"} over the app, write the JSON:
   # .../reports/$sha.json
 done
 npx @reticlehq/server hunt ./reports

package/docs/deploy-checks.md

@@ -76,7 +76,7 @@ Use both: `gate` in the agent's Stop hook (see `agent-cheatsheet`), `verify` at
 ## Honest limits
 
 - **`verify` needs one connected session.** If several tabs of the app are open against the same daemon it refuses rather than guessing which to drive.
-- **It replays flows sequentially against one tab**, so flows must not depend on each other's leftover state (a flow that logs in contaminates the next one). Author self-contained flows, or use `reticle_flow_verify { parallel }`, which gives each flow an isolated context.
+- **It replays flows sequentially against one tab**, so flows must not depend on each other's leftover state (a flow that logs in contaminates the next one). Author self-contained flows, or use `reticle_verify { action: "flows", parallel }`, which gives each flow an isolated context.
 - **No saved flows means nothing to verify.** `verify` fails rather than reporting a vacuous pass.
 
 ## FAQ
@@ -91,7 +91,7 @@ Both. For a non-loopback origin Reticle injects `reticle.connect()` with a one-t
 
 ### One of my flows logs in and the next one starts logged in. How do I stop that?
 
-`verify` replays flows sequentially against one tab, so leftover state carries. Either author each flow to be self-contained, or use `reticle_flow_verify { parallel: true }`, which gives every flow its own isolated browser context with its own cookies and storage.
+`verify` replays flows sequentially against one tab, so leftover state carries. Either author each flow to be self-contained, or use `reticle_verify { action: "flows", parallel: true }`, which gives every flow its own isolated browser context with its own cookies and storage.
 
 ### Should I run reticle gate as well as reticle verify?
 

package/docs/docs.json

@@ -32,7 +32,7 @@
   "navigation": {
     "versions": [
       {
-        "version": "2.9.0",
+        "version": "2.11.0",
         "default": true,
         "tabs": [
           {
@@ -183,7 +183,7 @@
               },
               {
                 "group": "Trust & licensing",
-                "pages": ["telemetry", "enterprise"]
+                "pages": ["telemetry", "license-activation", "enterprise"]
               }
             ]
           },

package/docs/enterprise.md

@@ -8,25 +8,31 @@ Enterprise features ship inside the open package and are unlocked by a signed li
 
 > Premium access (how you get + activate it), what's gated, the security/data-handling posture, and the licensing model. Integration mechanics live in [`platform-integration.md`](./platform-integration.md).
 
+> **Already have a key and just need to switch it on?** [Activating a license key](./license-activation) is the step-by-step version: where to set it on each platform, the editor and CI cases, how to read every status, and what to do when it does not work.
+
 ## How premium access works (offline, no phone-home)
 
 Enterprise (`ee/`) features ship **inside the open package**; they're source-available (free for development, testing, and evaluation). A **license key activates them in production**. Activation is verified locally with Ed25519; nothing about your usage ever leaves your machine.
 
 **The flow, end to end:**
 
-1. **Buy.** Contact **[hey@reticle.sh](mailto:hey@reticle.sh)**; we issue you a signed license key (org, plan, expiry, feature set).
+1. **Buy.** Contact **[hey@reticle.sh](mailto:hey@reticle.sh)**; we issue you a signed license key (license id, org, plan, expiry, feature set). The **license id** is the stable handle on your subscription: it survives a rename, and it is what a renewal continues.
 2. **Install.** Set it on the machine running the Reticle server:
    ```bash
    export RETICLE_LICENSE_KEY="<your key>"
    # the release already bakes the issuer public key (RETICLE_LICENSE_PUBLIC_KEY)
    ```
 3. **Verify.** `reticle license` shows your status:
+
    ```
    active    licensed to Acme Corp (enterprise), expires 2027-06-20 · features: sso, audit
    eval      evaluation mode: enterprise features run free (no issuer key configured)
-   missing   set RETICLE_LICENSE_KEY to activate enterprise features in production
-   expired   renew to keep using enterprise features
+   missing   set RETICLE_LICENSE_KEY to activate enterprise features in production. Request a key from hey@reticle.sh
+   expired   license expired. Renew with hey@reticle.sh to keep using enterprise features
    ```
+
+   Every status reports `contact`, so a reader who is stuck always has somebody to write to. An unlicensed status also reports `gated`, what a licence unlocks in the build you are running, so the command answers "what would this buy me, and how do I get one" without anybody having to find this page first. It is derived from the features the gate actually enforces, so it names what your build will really refuse rather than a roadmap. An `active` licence does not report it: that reader has already bought, and listing feature names at them answers nothing they asked.
+
 4. **Unlock.** Enterprise features now run in production; without a valid key they refuse to run there (a clear error, never a silent half-feature). In eval/dev they always run free.
 5. **Renew.** Keys carry an expiry; `reticle license` warns before it lapses.
 

package/docs/flows.md

@@ -115,17 +115,17 @@ This is the feedback a human reviewer used to give, made machine-actionable, so
 
 ## Verify the whole suite in one call
 
-`reticle_flow_verify` replays **every** saved flow (or a named subset) deterministically, with no LLM per flow, and returns one consolidated verdict. This is the regression check to run after any change:
+`reticle_verify {action:"flows"}` replays **every** saved flow (or a named subset) deterministically, with no LLM per flow, and returns one consolidated verdict. This is the regression check to run after any change:
 
 ```jsonc
-reticle_flow_verify()
+reticle_verify({ action: "flows" })
 // → { status: "fail", total: 4, passed: 3, failed: 1,
 //     summary: "3/4 flows pass, 1 needs attention: ship-deploy",
 //     failures: [{ flow: "ship-deploy", verdict: "drift",
 //                  whatChanged: "...", whereInSource: "src/...:NN", nextAction: "..." }] }
 ```
 
-Passing flows are counted; only failures carry detail (token-cheap). Build → `reticle_flow_verify` → fix from each failure's `nextAction` → repeat: the autonomous regression loop.
+Passing flows are counted; only failures carry detail (token-cheap). Build → `reticle_verify {action:"flows"}` → fix from each failure's `nextAction` → repeat: the autonomous regression loop.
 
 ## Self-healing: the agent maintains the flow
 
@@ -165,7 +165,7 @@ With `apply: false` the flow file is **never modified**; you get the proposed di
 | `reticle_flow {action:"list"}` | `{}` | flows on disk |
 | `reticle_flow {action:"load"}` | `{ flowName }` | the flow JSON |
 | `reticle_flow_replay` | `{ flowName }` | `{ status, steps, decision? }` (decision on drift/fail) |
-| `reticle_flow_verify` | `{ names?, sessionId? }` | suite verdict `{ status, passed, failed, failures[] }` |
+| `reticle_verify {action:"flows"}` | `{ names?, sessionId? }` | suite verdict `{ status, passed, failed, failures[] }` |
 | `reticle_flow_heal` | `{ flowName, apply? }` | propose / apply nearest-match rebind |
 | `reticle_annotate` | `{ kind, … }` | compile a structured annotation into the flow |
 

package/docs/gates.md

@@ -31,7 +31,7 @@ Every gate below was executed end to end against `main` on **2026-08-12** (macOS
 | `pnpm matrix:compat --only cursor` | ✅ 4/4 | ~10s |
 | `pnpm bench` | ✅ 10/10 (**was failing before this sweep**, see below) | 279s |
 
-**`pnpm bench` was broken and nobody knew.** `suite-rre.mjs` recorded four flows that asserted no observable consequence and then demanded a `pass` verdict from `reticle_flow_verify`, which correctly grades an assertion-free suite `unverifiable`. The product got more honest about false greens; the benchmark measuring it did not follow, so the whole run aborted at script 9 of 10 and `replay-determinism` never ran at all. Each flow now carries a success oracle. This is the failure mode `bench/` is most exposed to: **nothing in CI runs it**, so it can only rot silently.
+**`pnpm bench` was broken and nobody knew.** `suite-rre.mjs` recorded four flows that asserted no observable consequence and then demanded a `pass` verdict from whole-suite replay, which correctly grades an assertion-free suite `unverifiable`. The product got more honest about false greens; the benchmark measuring it did not follow, so the whole run aborted at script 9 of 10 and `replay-determinism` never ran at all. Each flow now carries a success oracle. This is the failure mode `bench/` is most exposed to: **nothing in CI runs it**, so it can only rot silently.
 
 `pnpm gate:install` (~15 min) and the Windows / Rust jobs were **not** run in this sweep; they are CI-only or network-bound. They are green on `main` per the last CI run, which is a weaker claim than every row above, and is stated that way on purpose.
 

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/recipes.mdx

@@ -179,7 +179,7 @@ Confirm it explicitly when you mean it:
 ## "Did my change break anything else?"
 
 ```json
-{ "tool": "reticle_verify_change", "args": { "since": "HEAD~1" } }
+{ "tool": "reticle_verify", "args": { "action": "change", "since": "HEAD~1" } }
 ```
 
 Give it the files you edited, or a git ref. It works out which saved flows cover them and replays only those.
@@ -246,7 +246,7 @@ Under a driven browser the same call answers `{ "applied": true, "count": 1 }`.
 Record it once, replay it forever:
 
 ```json
-{ "tool": "reticle_flow_verify", "args": { "names": ["docs-check"] } }
+{ "tool": "reticle_verify", "args": { "action": "flows", "names": ["docs-check"] } }
 ```
 
 Omit `names` to replay every saved flow. Either way you get one consolidated verdict, and only the failures carry detail:

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`
 
@@ -156,11 +145,28 @@ Four counters and one flag were added because the data could not answer question
 | `bug.attribution` | `bug_found` | `app` \| `request` \| `reticle`: whose fault the defect was. **Absent means unclassified**, never `app`. See below. |
 | `outage.stage` / `outage.reason` / `outage.attempts` | `mcp_connection_lost` | which stage of the outage, why the stream went away (closed `OutageReason`, `other` for anything unnamed), and how many reconnects had been tried. See below. |
 | `installSource` | `reticle_installed`, `init_completed` | WHICH published route brought this install in, from core's closed `InstallSource`. Read from one self-declared marker (`RETICLE_INSTALL_SOURCE`) and NEVER inferred, so `unknown` is expected to dominate until every channel's own copy of the install command carries it. See below. |
+| `licenseId` / `licenseStatus` | every event, on a licensed build | Enterprise activation. `licenseStatus` is core's closed `LicenseActivation` (`active` \| `missing` \| `invalid` \| `expired`) and rides through the FAILURE states too, which is what makes a lapse distinguishable from a churn. `licenseId` is present only while a key verifies, so on identity alone a customer whose key expired and one who left are the same silence. `licenseId` is an opaque uuid that resolves to a company only against the issuance ledger held locally, so the analytics backend never holds a customer list. The organisation NAME is never sent. **All three absent on a build with no issuer key baked**, which is every OSS install, so absence means "not a licensed build" and costs nothing to say. See below. |
 | `init.confirmation` | `init_completed` | what `init` SAW after writing, from core's closed `InitConfirmation`: `connected` (an app carrying the SDK reached the daemon while it watched, and it is the only value that means installed) \| `no_daemon` (nothing was listening, so no session could arrive) \| `no_session` (a daemon was up and no app connected inside the window). **Absent means it never looked**, which is every scripted run: `init` waits only when a human is at the terminal. Read absent as "not measured", never as a failure to connect. |
 | `automation` | every event | ADVISORY hint that the run looks automated when `CI` does not say so, from core's closed `AutomationHint`: `container` \| `hosted_workspace` \| `no_tty`. `ci` reads one environment variable set only by a runner, so a gate driven from a cloud sandbox lands as a human at a machine. **Never a filter**: people work in containers, in Codespaces, and over ssh with no terminal, and dropping a row because this is set drops real users. Absent means nothing looked automated, not that a human was present. |
 | `tzOffsetMin` | every event | minutes offset from UTC. One integer, no location. |
 | `versionChange.nudged` | `version_changed` | an agent had been told about exactly this version recently, so the nudge plausibly caused the update. The daemon that nudges and the `reticle update` that acts are different processes, so a marker file joins them. |
 
+## Enterprise activation: `licenseId`, `licenseStatus`
+
+A licensed deployment reports which licence it is running under, so per-customer usage can be answered at all. Three things make this different from every other property here, and all three are deliberate:
+
+**It is on every event, not on an activation event.** The questions a licensed customer generates are "how much is this org using it", "what is breaking for them", "did their key lapse", and every one of those is answered by an event that has nothing to do with licensing. A status riding only its own event would say a key verified once and nothing about the sessions it covered.
+
+**Status is separate from identity, and reports failures.** `licenseId` exists only while a key verifies. If that were the whole signal, a lapse would look exactly like a departure, and the renewal conversation would start after the customer noticed rather than before. `licenseStatus` keeps arriving through `expired` and `invalid`. A mis-built release (production with no issuer key baked) reports `invalid` rather than staying quiet, because that one is ours to fix.
+
+**The plan is not sent, and neither is the organisation name.** They are left out for different reasons and both are worth stating. The name is free text somebody typed when the key was signed, so rule 3 forbids it. The plan is merely redundant, which is the quieter reason and the easier one to lose sight of: the issuance ledger already holds it against this same id, so sending it would be a per-event cost, from every machine, forever, for something the join that resolves the id resolves at the same moment. `reticle license` still reports it locally, where it costs nothing.
+
+**The organisation name never goes on the wire.** It is free text somebody typed when the key was signed, so it falls under rule 3. The id is opaque; the map from id to company is a local ledger. An analytics-side breach therefore cannot expose who is evaluating Reticle.
+
+Resolution reads the EVENT's clock, not one captured at daemon start: sessions here run to eleven hours, and a key that expires mid-session has to start reporting `expired` from the event it expired on.
+
+> **This changes what a licensed deployment sends, so it is a contract term, not a quiet addition.** The enterprise agreement has to say that licensed deployments report usage attributed to their licence id, and list these fields. `RETICLE_TELEMETRY=0` and `DO_NOT_TRACK` still switch it off exactly as they switch off everything else. There is no exception for licensed installs, and adding one would put a hole in the kill switch that a security review is entitled to find.
+
 ## Why they stopped: `tool_refused`
 
 The refusal path computes a precise diagnosis, hands it to the agent as prose, and throws it away. So the biggest cohort in the funnel, the users who attach an agent and never drive, emitted nothing at all and was reachable only by subtracting two other numbers. Half of issue #172.

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-overview.mdx

@@ -75,7 +75,7 @@ Direct `reticle_network` and `reticle_console` stay advertised even though `reti
 ## Reaching the other 29
 
 ```json
-{ "tool": "reticle_flow_verify", "args": {} }
+{ "tool": "reticle_verify", "args": { "action": "flows" } }
 ```
 
 `reticle_run` takes a tool name and its arguments. `reticle_tools` lists what's available and returns the full argument grammar for any of them, so your agent can discover a tool mid-task without you having pre-loaded its schema.

package/docs/tools-session-and-feedback.mdx

@@ -70,6 +70,11 @@ Reticle is built for agents, which creates an unusual problem: the primary user'
 | `ambiguity`       | The check ran but you could not tell what the answer meant |
 | `feature_request` | You wished a capability existed                            |
 | `improvement`     | It works, but costs too many calls                         |
+| `experience`      | Something worked notably well (pair it with `rating`, 1-5) |
+
+`experience` is the only kind here that is not a complaint, and that is why it exists. Every other row grows the corpus into a defect list, which says nothing about which parts are worth protecting when we change them. File it unprompted, when you actually notice it, and name the concrete moment: which call, what it saved you, what you would have done instead.
+
+The `rating` is secondary to that text on purpose. A score produced because something asked for one is indistinguishable from a score that was earned, and once both sit in the same column neither means anything. The text is the part that can be acted on or quoted.
 
 ### It will tell you when it cannot send
 

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

@@ -18,21 +18,21 @@ Reticle ships 46 tools plus these two meta-tools. On the default profile your ag
 
 Returns every tool with a one-line summary. A sample of what lives in the cold tail:
 
-| Tool                    | What it does                                                           |
-| ----------------------- | ---------------------------------------------------------------------- |
-| `reticle_capabilities`  | The app's advertised testable surface, testids, signals, stores, flows |
-| `reticle_flow_verify`   | Replay every saved flow, return one consolidated suite verdict         |
-| `reticle_screenshot`    | Pixel screenshot of the driven page, saved as a visual baseline        |
-| `reticle_visual_diff`   | Perceptually diff the live page against that baseline                  |
-| `reticle_network_mock`  | Force a 500, go offline, or delay a response                           |
-| `reticle_viewport`      | Pin the viewport so screenshots are reproducible across machines       |
-| `reticle_crawl`         | Click every reachable control and report anomalies, with no script     |
-| `reticle_clock`         | Freeze time or fast-forward timers, toasts, debounces, auto-dismiss    |
-| `reticle_storage`       | localStorage, sessionStorage and readable cookies                      |
-| `reticle_coverage`      | Which controls you have driven this session, and which you have not    |
-| `reticle_verify_change` | Give it the files you edited; it replays the flows that cover them     |
-| `reticle_reconcile`     | Compare what the API returned against what the page actually renders   |
-| `reticle_scroll_to`     | Find a row in a virtualised list that has not rendered yet             |
+| Tool | What it does |
+| --- | --- |
+| `reticle_capabilities` | The app's advertised testable surface, testids, signals, stores, flows |
+| `reticle_verify` (`flows`) | Replay every saved flow, return one consolidated suite verdict |
+| `reticle_screenshot` | Pixel screenshot of the driven page, saved as a visual baseline |
+| `reticle_visual_diff` | Perceptually diff the live page against that baseline |
+| `reticle_network_mock` | Force a 500, go offline, or delay a response |
+| `reticle_viewport` | Pin the viewport so screenshots are reproducible across machines |
+| `reticle_verify` (`crawl`) | Click every reachable control and report anomalies, with no script |
+| `reticle_clock` | Freeze time or fast-forward timers, toasts, debounces, auto-dismiss |
+| `reticle_storage` | localStorage, sessionStorage and readable cookies |
+| `reticle_verify` (`coverage`) | Which controls you have driven this session, and which you have not |
+| `reticle_verify` (`change`) | Give it the files you edited; it replays the flows that cover them |
+| `reticle_reconcile` | Compare what the API returned against what the page actually renders |
+| `reticle_scroll_to` | Find a row in a virtualised list that has not rendered yet |
 
 The response also tells you which surface is active:
 

package/docs/usage.md

@@ -286,10 +286,10 @@ List interactive elements + console-error count for autonomous exploration. See
 
 ### Flows, recorder & self-healing (`.reticle/`)
 
-`reticle_contract_save`, `reticle_flow_save` / `reticle_flow_save_recorded` / `reticle_flow {action:"list"}` / `reticle_flow {action:"load"}` / `reticle_flow_replay` / `reticle_flow_verify`, `reticle_flow_heal`, `reticle_annotate`: record once, replay forever (anchored on testid/signal, or on an auto-derived component/source anchor when there's no testid), with legible drift + self-heal. Full guide: [Flows, the recorder & self-healing](flows.md).
+`reticle_contract_save`, `reticle_flow_save` / `reticle_flow_save_recorded` / `reticle_flow {action:"list"}` / `reticle_flow {action:"load"}` / `reticle_flow_replay` / `reticle_verify {action:"flows"}`, `reticle_flow_heal`, `reticle_annotate`: record once, replay forever (anchored on testid/signal, or on an auto-derived component/source anchor when there's no testid), with legible drift + self-heal. Full guide: [Flows, the recorder & self-healing](flows.md).
 
-- **`reticle_flow_verify({ names?, sessionId? })`** is the regression-suite call: it replays EVERY saved flow (or a subset) deterministically and returns one verdict `{ status, passed, failed, failures: [{ flow, verdict, whatChanged, whereInSource, nextAction }] }`. Passing flows are counted; only failures carry detail. Run it after any change: one call, no LLM per flow.
-- **Decision envelope:** on a drift/fail, `reticle_flow_replay` (and each `reticle_flow_verify` failure) returns the actionable fix: `whatChanged`, `whereInSource` (`file:line`), and a one-line `nextAction` (e.g. "rebind the anchor to 'new-deploy', or update the flow if intended").
+- **`reticle_verify({ action: "flows", names?, sessionId? })`** is the regression-suite call: it replays EVERY saved flow (or a subset) deterministically and returns one verdict `{ status, passed, failed, failures: [{ flow, verdict, whatChanged, whereInSource, nextAction }] }`. Passing flows are counted; only failures carry detail. Run it after any change: one call, no LLM per flow.
+- **Decision envelope:** on a drift/fail, `reticle_flow_replay` (and each `reticle_verify {action:"flows"}` failure) returns the actionable fix: `whatChanged`, `whereInSource` (`file:line`), and a one-line `nextAction` (e.g. "rebind the anchor to 'new-deploy', or update the flow if intended").
 
 ### Human-in-the-loop control
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "2.9.0",
+  "version": "2.11.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.9.0"
+    "@reticlehq/core": "2.11.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",

package/dist/telemetry/instrumentation-stall.d.ts

@@ -1,50 +0,0 @@
-/**
- * When a daemon has waited long enough that no app is coming.
- *
- * `app_instrumented` fires on success and only on success, so the population that matters most —
- * daemons that never get an app wired at all — exists in the data only 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". The funnel breaks at
- * exactly this step and nowhere else, which makes it the one silence worth converting into a signal.
- *
- * Once per daemon run, and never after an app has connected. A daemon that takes a while and then
- * works reports nothing at all: the question is "did this run ever get an app", and a run that did
- * is not stalled no matter how long it took.
- *
- * The threshold is a judgement, not a measurement, and it is deliberately generous. Someone running
- * `init` and then going to make coffee has not hit a defect, and calling that a stall would drown
- * the real signal in ordinary human latency.
- *
- * Read the result against `agentAttached`, which is what makes it actionable: a stalled daemon with
- * no agent 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.
- */
-/**
- * How long a daemon may sit with no app before it counts as stalled.
- *
- * Ten minutes sits well past setup latency — reading a doc, restarting a dev server, opening a tab —
- * and well short of the half-hour idle windows that dominate the field, so a stall is reported while
- * the session is still alive rather than inferred from its corpse.
- */
-export declare const STALL_AFTER_MS: number;
-/** Start the clock. Called from the same place the instrumentation clock is marked. */
-export declare function markStallClock(now: number): void;
-export interface StallFacts {
-    /** Whether this project has a projectId stamped — i.e. `init` has run here. */
-    initialized: boolean;
-    /** Whether an MCP client is attached right now. */
-    agentAttached: boolean;
-}
-/**
- * Report a stalled install, at most once per daemon run.
- *
- * Returns whether it emitted, so the caller's test can assert the once-only rule without reaching
- * into the telemetry client. Best-effort like every other metric here: it must never be the reason
- * a daemon misbehaves.
- */
-export declare function reportInstrumentationStall(facts: StallFacts, now?: () => number, opts?: {
-    atShutdown?: boolean;
-}): boolean;
-/** Tests only. */
-export declare function resetInstrumentationStall(): void;