@reticlehq/server 2.9.0 → 2.10.0

package/dist/tools/feedback-tools.js

@@ -12,9 +12,9 @@
  * tokens on that and not on politeness.
  */
 import { z } from 'zod';
-import { FeedbackKind, FeedbackSource } from '@reticlehq/core';
+import { FeedbackKind, FeedbackSource, FEEDBACK_RATING_MAX, FEEDBACK_RATING_MIN, } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
-import { asString } from './tools-helpers.js';
+import { asNumber, asString } from './tools-helpers.js';
 import { submitFeedback, feedbackDisabled } from '../telemetry/feedback.js';
 import { getTelemetry } from '../telemetry/telemetry.js';
 /** One optional string arg, present only when the agent actually supplied it. */
@@ -22,6 +22,19 @@ function optionalText(args, key) {
     const value = asString(args[key]);
     return value !== undefined && value !== '' ? { [key]: value } : {};
 }
+/**
+ * The star rating, present only when the agent actually supplied one, and only when it is on the
+ * scale core defines. Bounds-checked HERE as well as in the schema because a number that survives
+ * to the wire off-scale is worse than an absent one: it still averages.
+ */
+function optionalRating(args) {
+    const value = asNumber(args['rating']);
+    if (value === undefined || !Number.isInteger(value))
+        return {};
+    if (value < FEEDBACK_RATING_MIN || value > FEEDBACK_RATING_MAX)
+        return {};
+    return { rating: value };
+}
 /** Read the connected session's self-reported facts, or nothing when no app is attached. */
 function sessionFacts(deps, sessionId) {
     const driven = deps.realInput !== undefined;
@@ -45,7 +58,7 @@ function sessionFacts(deps, sessionId) {
 export const FEEDBACK_TOOLS = [
     {
         name: ReticleTool.FEEDBACK,
-        description: "Tell the Reticle maintainers something — a failure, OR a feature you wish existed. Reticle is built FOR agents, so your experience is the one that decides what gets built, and this is the only channel that reaches us. File a `bug` when a tool returned something wrong, a `gap` when Reticle could not observe what you needed, an `ambiguity` when a verdict was not decidable, a `feature_request` when you thought 'I wish Reticle could do X', or an `improvement` when something works but is awkward (too many calls, a confusing shape, a slow path). Do not save these up or judge them as too minor — file it the moment you notice, then carry on with your task. For a failure, write `text` as a root-cause analysis (what you called, expected, got). For a request, write what you want and use `need` for the GOAL behind it, `impact` for what gets better, and `currentApproach` for how you are working around it today — that workaround is usually the most useful thing in the report. Set `model` to the model you are running. Never include app source, secrets, user data, or customer records. Do NOT use this for bugs you found in the app under test — that is a successful verification, which is Reticle working.",
+        description: "Tell the Reticle maintainers something — a failure, OR a feature you wish existed. Reticle is built FOR agents, so your experience is the one that decides what gets built, and this is the only channel that reaches us. File a `bug` when a tool returned something wrong, a `gap` when Reticle could not observe what you needed, an `ambiguity` when a verdict was not decidable, a `feature_request` when you thought 'I wish Reticle could do X', an `improvement` when something works but is awkward (too many calls, a confusing shape, a slow path), or an `experience` when something worked notably WELL (carry `rating` 1-5). File that one unprompted, when you actually notice it, and say which call and what it saved you — every other kind here is a complaint, so it is the only evidence for what is worth protecting when we change things. Do not save these up or judge them as too minor — file it the moment you notice, then carry on with your task. For a failure, write `text` as a root-cause analysis (what you called, expected, got). For a request, write what you want and use `need` for the GOAL behind it, `impact` for what gets better, and `currentApproach` for how you are working around it today — that workaround is usually the most useful thing in the report. Set `model` to the model you are running. Never include app source, secrets, user data, or customer records. Do NOT use this for bugs you found in the app under test — that is a successful verification, which is Reticle working.",
         inputSchema: {
             kind: z
                 .enum([
@@ -54,8 +67,9 @@ export const FEEDBACK_TOOLS = [
                 FeedbackKind.AMBIGUITY,
                 FeedbackKind.FEATURE_REQUEST,
                 FeedbackKind.IMPROVEMENT,
+                FeedbackKind.EXPERIENCE,
             ])
-                .describe('bug = a Reticle tool returned a wrong or broken result; gap = Reticle could not observe something you needed at all; ambiguity = the verification ran but you could not tell pass from fail; feature_request = something that does not exist and would have helped; improvement = something that exists but is awkward or inefficient.'),
+                .describe('bug = a Reticle tool returned a wrong or broken result; gap = Reticle could not observe something you needed at all; ambiguity = the verification ran but you could not tell pass from fail; feature_request = something that does not exist and would have helped; improvement = something that exists but is awkward or inefficient; experience = something worked notably well and is worth keeping (pair it with `rating`).'),
             text: z
                 .string()
                 .min(1)
@@ -72,6 +86,13 @@ export const FEEDBACK_TOOLS = [
                 .string()
                 .optional()
                 .describe('How you work around it TODAY. Usually the most useful field in the report: it proves the need is real, and often shows a cheaper fix than the feature being asked for.'),
+            rating: z
+                .number()
+                .int()
+                .min(FEEDBACK_RATING_MIN)
+                .max(FEEDBACK_RATING_MAX)
+                .optional()
+                .describe(`How well it worked, ${FEEDBACK_RATING_MIN}-${FEEDBACK_RATING_MAX}, with an \`experience\`. Only when you formed the judgement while working, never because you were asked: an agreeable number and an earned one are indistinguishable once both sit in the same column. The \`text\` is the part we can act on.`),
             model: z
                 .string()
                 .optional()
@@ -112,6 +133,7 @@ export const FEEDBACK_TOOLS = [
                 ...optionalText(args, 'impact'),
                 ...optionalText(args, 'currentApproach'),
                 ...optionalText(args, 'model'),
+                ...optionalRating(args),
             }, {
                 session: sessionFacts(deps, asString(args['sessionId'])),
                 // The AGENT does not wait for the network. `reticle feedback` (a human, at a terminal,
@@ -154,8 +176,11 @@ export const FEEDBACK_PROMPT = {
 export const VERIFICATION_TOOLS = new Set([
     ReticleTool.ACT_AND_WAIT,
     ReticleTool.ASSERT,
-    ReticleTool.FLOW_VERIFY,
-    ReticleTool.VERIFY_CHANGE,
+    // Merged: `flow_verify` and `verify_change` are actions on this tool now. Naming the merged tool
+    // does NOT make every action a verification — `verificationOf` still requires the result to carry
+    // a `verified` or a pass/fail `status`, so `coverage` and `crawl` contribute nothing and cannot
+    // inflate the count.
+    ReticleTool.VERIFY,
     ReticleTool.RECONCILE,
 ]);
 /**

package/dist/tools/invoke-tool.d.ts

@@ -7,4 +7,4 @@ export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
  * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
  */
 export declare const SESSION_EXEMPT_TOOLS: ReadonlySet<string>;
-export declare function runTool(tool: ToolDef, deps: ToolDeps, args: Record<string, unknown>): Promise<unknown>;
+export declare function runTool<Ext>(tool: ToolDef<Ext>, deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;

package/dist/tools/invoke-tool.js

@@ -47,14 +47,21 @@ const REF_MINTING_TOOLS = new Set([
     ReticleTool.QUERY,
     ReticleTool.INSPECT,
     ReticleTool.EXPLORE,
-    ReticleTool.CRAWL,
+    // `crawl` mints refs for the controls it drives and `coverage` for the ones it reports untouched.
+    // Both are actions on the merged verify tool now.
+    ReticleTool.VERIFY,
 ]);
 export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
     ReticleTool.QUERY,
     ReticleTool.INSPECT,
-    ReticleTool.COVERAGE,
-    ReticleTool.VERIFY_CHANGE,
+    // Merged change/flows/affected/coverage/crawl. Its members were SPLIT across bound and exempt —
+    // coverage/change/crawl bound, flow_verify exempt because it returns its own suite contract — and
+    // a merged tool has to be one or the other. Bound is the right side: `crawl` drives the app
+    // itself, so a throttled or event-dropping tab is exactly the condition its verdict depends on,
+    // and dropping the health disclosure there to protect a sibling's output shape would trade an
+    // honesty signal for a formatting preference.
+    ReticleTool.VERIFY,
     ReticleTool.ACT,
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.ACT_AND_WAIT,
@@ -74,7 +81,6 @@ export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.STATE,
     ReticleTool.STORAGE,
     ReticleTool.EXPLORE,
-    ReticleTool.CRAWL,
     ReticleTool.SCROLL_TO,
     ReticleTool.NAVIGATE,
 ]);
@@ -90,7 +96,6 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     ReticleTool.FLOW_SAVE, // sessionId only scopes the write to the app's flow subdir; disk-side
     ReticleTool.FLOW, // merged list/load/delete — sessionId only scopes the project; all disk-side
     ReticleTool.FLOW_REPLAY, // returns its own FlowReplayResult contract (+ auto-records a run)
-    ReticleTool.FLOW_VERIFY, // returns its own SuiteVerdict contract (replays the whole suite)
     ReticleTool.FLOW_SAVE_RECORDED, // reads the recording buffer, writes disk
     ReticleTool.FLOW_HEAL, // returns its own FlowHealResult contract
     ReticleTool.PROJECT, // reads .reticle/project.json

package/dist/tools/tool-kit.d.ts

@@ -16,7 +16,7 @@ import type { ProjectStore } from '../project/project-store.js';
 import type { AnnotationStore } from '../flows/annotation-store.js';
 import type { BrowserPool } from '../pool/browser-pool.js';
 import type { ChromiumProbe } from '../cli/chromium-hint.js';
-export interface ToolDeps {
+export interface ToolDeps<Ext = unknown> {
     sessions: SessionManager;
     /** shared one-browser/N-context pool for headless leases. undefined ⇒ lease tools report unavailable. */
     pool?: BrowserPool;
@@ -59,8 +59,23 @@ export interface ToolDeps {
      * ToolDeps keeps working; absent falls back to the default port.
      */
     bridgePort?: number;
+    /**
+     * A consumer's OWN dependencies, carried through untouched.
+     *
+     * Nothing in this package reads it. It exists so a consumer embedding the engine can add tools of
+     * its own — answering out of a store this package has never heard of — without either widening the
+     * fields above with a stranger's vocabulary or forking to get a handle through.
+     *
+     * The type parameter, rather than `unknown`, is what keeps the seam typed: a consumer writes
+     * `ToolDef<TheirExt>` once and their handlers see their own type. Casting out of `unknown` in every
+     * handler is how a typed seam quietly becomes an untyped one.
+     *
+     * Optional, and defaulted to `unknown`, so every existing construction of this bag — and every test
+     * that builds one — is unchanged.
+     */
+    ext?: Ext;
 }
-export interface ToolDef {
+export interface ToolDef<Ext = unknown> {
     name: string;
     description: string;
     inputSchema: z.ZodRawShape;
@@ -86,7 +101,19 @@ export interface ToolDef {
      * example that does not validate is worse than none at all.
      */
     example?: Record<string, unknown>;
-    handler: (deps: ToolDeps, args: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Declared method-style, not as a property, and that is load-bearing rather than stylistic.
+     *
+     * Under `strictFunctionTypes` a property holding a function has CONTRAVARIANT parameters, so
+     * `ToolDef<TheirExt>` and `ToolDef<unknown>` become mutually unassignable and a consumer composing
+     * `[...TOOLS, ...theirTools]` needs a cast — as does every internal helper that then touches the
+     * array. Method-style parameters are checked bivariantly, which collapses all of that.
+     *
+     * The unsoundness bivariance admits is that a handler written against `ToolDeps<TheirExt>` could be
+     * handed a bag carrying no `ext` at all. That costs nothing here, because `ext` is optional by
+     * design: any handler reading it already has to survive `undefined`.
+     */
+    handler(deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;
 }
 export declare const sessionIdShape: {
     sessionId: z.ZodOptional<z.ZodString>;

package/dist/tools/tool-names.d.ts

@@ -46,6 +46,8 @@ export declare const ReticleTool: {
     readonly AFFECTED: "reticle_affected";
     readonly COVERAGE: "reticle_coverage";
     readonly VERIFY_CHANGE: "reticle_verify_change";
+    /** Merged: change/flows/affected/coverage/crawl — "what is proved, and what is not". */
+    readonly VERIFY: "reticle_verify";
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     readonly PROJECT: "reticle_project";
     /** explicitly record a run outcome (the manual companion to auto-recording). */

package/dist/tools/tool-names.js

@@ -47,6 +47,8 @@ export const ReticleTool = {
     AFFECTED: 'reticle_affected',
     COVERAGE: 'reticle_coverage',
     VERIFY_CHANGE: 'reticle_verify_change',
+    /** Merged: change/flows/affected/coverage/crawl — "what is proved, and what is not". */
+    VERIFY: 'reticle_verify',
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     PROJECT: 'reticle_project',
     /** explicitly record a run outcome (the manual companion to auto-recording). */

package/dist/tools/tool-surface.js

@@ -206,15 +206,14 @@ export const EXTENDED_TOOL_NAMES = new Set([
     ReticleTool.CAPABILITIES,
     ReticleTool.FLOW_SAVE,
     ReticleTool.FLOW_REPLAY,
-    ReticleTool.FLOW_VERIFY,
     ReticleTool.RECORD,
     ReticleTool.SCREENSHOT,
     ReticleTool.VISUAL_DIFF,
     ReticleTool.CLOCK,
     ReticleTool.NETWORK_MOCK,
     ReticleTool.STORAGE,
-    ReticleTool.VERIFY_CHANGE,
-    ReticleTool.CRAWL,
+    // Merged change/flows/affected/coverage/crawl — one name where three of these used to sit.
+    ReticleTool.VERIFY,
 ]);
 /**
  * The verify surface: one acting tool that returns a verdict, plus the two meta-tools that reach

package/dist/tools/tools.js

@@ -508,7 +508,7 @@ export const MERGE_PLANS = [
     },
     {
         name: ReticleTool.FLOW,
-        description: 'Saved-flow management: { action: "list" } names every saved flow, "load" reads+validates one by flowName, "delete" removes one. The hot verbs (flow_save, flow_replay, flow_verify, flow_heal) stay separate.',
+        description: 'Saved-flow management: { action: "list" } names every saved flow, "load" reads+validates one by flowName, "delete" removes one. The hot verbs (flow_save, flow_replay, flow_heal) stay separate; whole-suite replay is reticle_verify { action: "flows" }.',
         members: {
             list: ReticleTool.FLOW_LIST,
             load: ReticleTool.FLOW_LOAD,
@@ -531,6 +531,21 @@ export const MERGE_PLANS = [
         // is the one that must not need a schema lookup first.
         example: { action: 'yield', mode: 'waiting' },
     },
+    {
+        name: ReticleTool.VERIFY,
+        description: 'What is proved, and what is not — by action. Start from a change: { action: "affected" } names which saved flows must re-verify for the files you edited (pass `files`, and/or `since` for a git ref), and "change" goes further and actually replays them, answering with one `verified` plus `because`. `unknown` there is the honest answer when NO saved flow covers the change: nothing ran, so nothing was proved, and it is never reported as green. Without a change to start from: "flows" replays every saved flow for one consolidated suite verdict (deterministic, no LLM per flow), and "coverage" lists the interactive controls you have and have NOT driven this session — an untouched list still holding the controls your change affects means you are not done. "crawl" is the no-script option: it drives every reachable control itself and reports single-channel faults (console errors, failed requests, dead controls) and CONTRADICTIONS, two channels disagreeing about the same click — the false greens a human cannot see, because a human watches the screen and the screen looks correct. DESTRUCTIVE: crawl really clicks, and may navigate or mutate state.',
+        members: {
+            change: ReticleTool.VERIFY_CHANGE,
+            flows: ReticleTool.FLOW_VERIFY,
+            affected: ReticleTool.AFFECTED,
+            coverage: ReticleTool.COVERAGE,
+            crawl: ReticleTool.CRAWL,
+        },
+        // No default action ON PURPOSE. The name implies no single member, and one of them really
+        // clicks: a fallthrough that guessed wrong would drive the app rather than read it. Every action
+        // is explicit, which for `crawl` is the whole safety story.
+        example: { action: 'change', files: ['src/App.tsx'] },
+    },
     {
         name: ReticleTool.LEASE,
         description: 'Isolated headless contexts from the shared pool: { action: "acquire" } leases one and navigates it to the app URL, "release" closes it and frees the slot.',

package/docs/agent-cheatsheet.md

@@ -115,7 +115,7 @@ The tools advertised DIRECTLY, i.e. what you'll use 90% of the time. Everything
 
 Frequently useful but NOT core, so reach them through `reticle_run({ tool, args })`: `reticle_capabilities` (the app's whole testable surface in one call; `{fromDisk:true}` needs no browser), `reticle_domain` (learn the app + gaps), `reticle_baseline {action:"diff"}`, `reticle_project` (run history).
 
-**Reach past core when…** you need to record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_flow_heal`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_crawl` clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_query` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven mode), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
+**Reach past core when…** you need to record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_flow_heal`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify {action:"crawl"}` clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_query` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven mode), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
 
 ## flows vs baselines vs project.json (the persistence layers)
 
@@ -160,4 +160,4 @@ Recent additions, each of which answers a question agents were previously asking
 - **Cap broad reads.** `reticle_query` takes `limit` (caps descriptors; reports `total`/`truncated`) and `count_only` (just the match count). `reticle_network` / `reticle_console` take `limit` (most-recent-N, reports `droppedOldest`) and carry the same `cost` hint, so a busy page or wide window never floods your context unnoticed.
 - **A saved flow tells you if it's a real test.** `reticle_flow_save` returns `assertions.grade` (`asserted` / `presence-only` / `assertion-free`); if it's not `asserted`, add a consequence (`reticle_annotate` assert-signal/assert-net or a success-state) so it can't pass while broken. On replay, an ambiguous heal (two testids tie) is surfaced, never auto-applied. And an `apply` heal re-replays the rebound flow and **refuses to write** if the success consequence no longer fires (`status:consequence_broken`): it heals the locator, never the intent.
 - **Predicate schema is not bloated.** The recursive predicate DSL used by `reticle_assert` / `reticle_wait_for` / `reticle_act_and_wait` is **factored, not inlined**: when converted to the JSON Schema MCP sends, the predicate body is emitted **once** (~2.7k chars ≈ **~685 tokens** per tool) and recursion is handled by self-`$ref` (`#/properties/predicate`), with no per-recursion duplication. No action needed.
-- **One tool surface.** Reticle advertises the core set directly (sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state/inspect/feedback/session: the whole detect loop, plus the file-pointer, the feedback channel and the handback) PLUS two meta-tools that keep every other tool one call away: `reticle_tools` (discover; no args lists every tool name + summary, `names:[…]` loads full params on demand) and `reticle_run({ tool, args })` (invoke any tool by name; a top-level `sessionId` is forwarded to the target, so you need not nest it in `args`). So to record/replay/verify a flow, call `reticle_run({ tool:"reticle_flow_verify", sessionId })` (or `reticle_tools` first to see params). There is nothing to pick. `RETICLE_ADVERTISE_ALL_TOOLS=1` (read by the daemon at startup, so restart it) advertises everything with output schemas: a verification switch for suites, not a way to run agents. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.
+- **One tool surface.** Reticle advertises the core set directly (sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state/inspect/feedback/session: the whole detect loop, plus the file-pointer, the feedback channel and the handback) PLUS two meta-tools that keep every other tool one call away: `reticle_tools` (discover; no args lists every tool name + summary, `names:[…]` loads full params on demand) and `reticle_run({ tool, args })` (invoke any tool by name; a top-level `sessionId` is forwarded to the target, so you need not nest it in `args`). So to record/replay/verify a flow, call `reticle_run({ tool:"reticle_verify", args:{ action:"flows" }, sessionId })` (or `reticle_tools` first to see params). There is nothing to pick. `RETICLE_ADVERTISE_ALL_TOOLS=1` (read by the daemon at startup, so restart it) advertises everything with output schemas: a verification switch for suites, not a way to run agents. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.

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.10.0",
         "default": true,
         "tabs": [
           {

package/docs/enterprise.md

@@ -14,19 +14,23 @@ Enterprise (`ee/`) features ship **inside the open package**; they're source-ava
 
 **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 also reports `gated` (what a licence unlocks in the build you are running) and `contact`, so the command answers "what would this buy me, and how do I get one" without anybody having to find this page first. `gated` is derived from the features the gate actually enforces, so it lists what your build will really refuse rather than a roadmap.
+
 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/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

@@ -156,11 +156,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/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.10.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.10.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",