@reticlehq/server 2.7.0 → 2.8.0

package/docs/cli/watch.mdx

@@ -0,0 +1,55 @@
+---
+title: reticle watch
+description: Watch the working tree and report which saved flows must re-verify on every save.
+icon: eye
+---
+
+`reticle watch` is the buddy loop. It watches the current directory and, on every save of a source file, reports which saved flows the change puts at risk. It runs in the environment, so it costs your agent nothing per turn.
+
+```bash
+npx @reticlehq/server watch [url]
+```
+
+Long-running. Stop it with `Ctrl+C`.
+
+## Arguments
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `url` | string, positional, optional | unset | Accepted by the parser and reserved for the increment that replays the affected flows against a live app. The current version detects and reports only |
+
+## What it watches
+
+The working directory, recursively, filtered to `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.vue` and `.svelte`. Changes are batched with a 200ms debounce.
+
+## What it prints
+
+Real capture, the first two lines of a run in this repository:
+
+```json
+{"t":"2026-08-14T19:39:09.196Z","event":"reticle_watch_started","cwd":"/Users/you/reticle"}
+{"t":"2026-08-14T19:39:09.278Z","event":"reticle_buddy","status":"✓ 13/47 flows nominal · 9 flaky quarantined"}
+```
+
+| Event | When |
+| --- | --- |
+| `reticle_watch_started` | Once, at startup, with the directory being watched |
+| `reticle_buddy` | Once at startup and after every batch. One ambient line, designed to be parked in a status line |
+| `reticle_watch_affected` | After a batch, when at least one flow is affected. Carries `changed` and `affected` |
+| `reticle_watch_failed` | A flow load error. Never fatal |
+
+<Note>
+  The buddy line is deliberately best-effort and silent on failure. A status line that throws is
+  worse than no status line, and it must never interfere with the watch loop it rides on.
+</Note>
+
+## Exit codes
+
+Runs until interrupted.
+
+## Worked example
+
+```bash
+npx @reticlehq/server watch &
+# edit src/components/Login.tsx, and the affected flows are named on save
+```

package/docs/cli.mdx

@@ -0,0 +1,219 @@
+---
+title: CLI reference
+description: Every reticle command. What it does, what it prints, and what it exits with. Captured from real runs.
+icon: terminal
+---
+
+The CLI is mostly for you, not your agent. Your agent talks MCP; you use these to set things up, work out why nothing connected, and wire verification into CI.
+
+```bash
+npx @reticlehq/server <command>
+```
+
+<Warning>
+  **Always invoke it as `npx @reticlehq/server <command>`.** The tables below name the commands as
+  `reticle <command>`, because `reticle` is the bin this package installs and that is what the CLI
+  prints about itself. It is **not** a package on npm: the bare name `reticle` belongs to an
+  unrelated author, so putting `npx` in front of it downloads and runs their code instead of ours.
+  Once
+  `@reticlehq/server` is a dependency of your project, `reticle <command>` works from an npm script
+  or with the bin on your PATH.
+</Warning>
+
+<Note>
+  Every output block on this page was captured by running the command. Where an exit code is quoted,
+  it was measured, not assumed.
+</Note>
+
+## Setup and diagnosis
+
+### `reticle init`
+
+Wires Reticle into the project in the current directory.
+
+```
+reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+```
+
+<Card title="Full walkthrough with real output" icon="wand-magic-sparkles" href="/install-agentic">
+  What it writes, and how to read its four status marks.
+</Card>
+
+### `reticle doctor`
+
+The first thing to run when something is wrong. One command, the whole setup.
+
+```bash
+npx @reticlehq/server doctor
+```
+
+```
+reticle doctor
+  node         v22.14.0
+  chromium     ✓ installed
+  daemon       ✓ running on :4400 (pid 24735, v2.8.0)
+  sessions     ✓ 1 page connected
+  bridge port  4400  (your app must dial THIS port, not your dev-server port)
+  daemon log   /Users/you/.reticle/daemon-4400.log
+  tracing      RETICLE_TRACE=1 on the daemon for per-stage timings in that log
+```
+
+Exits `0`. That parenthetical about the bridge port is doing a lot of work. Mixing it up with the dev-server port is the most common setup failure there is.
+
+### `reticle status`
+
+Whether the daemon is up and which apps have connected.
+
+```json
+{
+  "event": "reticle_status",
+  "port": 4400,
+  "running": true,
+  "pid": 24735,
+  "sessionCount": 1,
+  "sessions": [
+    {
+      "sessionId": "sece96901…",
+      "url": "http://localhost:4312/",
+      "throttled": true,
+      "stale": false
+    }
+  ]
+}
+```
+
+Exits `0`. A session in the list is the install genuinely finished. Not a tick in a checklist, a connected app.
+
+### `reticle telemetry [status|enable|disable]`
+
+```bash
+npx @reticlehq/server telemetry status
+```
+
+```
+telemetry    disabled  (this is a Reticle source checkout; developing it is not using it)
+policy       https://github.com/reticlehq/reticle/blob/main/docs/telemetry.md
+```
+
+<Card title="Exactly what is collected" icon="chart-line" href="/telemetry">
+  The complete list, and how to turn it off.
+</Card>
+
+## Running the app
+
+| Command | What it does |
+| --- | --- |
+| `reticle serve` | Start the daemon in the foreground. `--drive <url>`, `--headless`, `--http` |
+| `reticle stop` | Stop it |
+| `reticle open [url]` | Show the app. Reuse the connected tab, or open one |
+| `reticle drive <url>` | Foreground mode, for debugging |
+| `reticle mcp` | The MCP stdio proxy. Auto-starts the daemon if needed. This is what your agent runs |
+
+<Warning>
+  `reticle drive` will fail with an `EADDRINUSE` stack trace if a daemon is already listening on the
+  port. Which is the normal state once your agent has started one. `reticle mcp` reuses a running
+  daemon; `drive` currently does not.
+</Warning>
+
+## Verification
+
+### `reticle verify <url>`
+
+One-shot: drive the URL, replay the saved flows, exit `0` on pass. This is the command for CI when you do not want a model in the loop.
+
+```bash
+npx @reticlehq/server verify http://localhost:5173 --timeout 60000
+```
+
+Options: `--headed`, `--timeout N`, `--storage-state <file>`. That last one is how you verify flows behind a login without scripting the login every time.
+
+### `reticle affected`
+
+Which saved flows must re-verify for a set of changed files.
+
+```bash
+npx @reticlehq/server affected --since HEAD~1
+```
+
+```json
+{
+  "event": "reticle_affected",
+  "changedFiles": ["docs/README.md", "packages/server/src/tools/docs-index-coverage.test.ts"],
+  "affected": ["deploy-journey", "verify-modal", "verify-route", "…"],
+  "unknownProvenance": ["deploy-journey", "verify-modal", "…"]
+}
+```
+
+<Note>
+  `unknownProvenance` lists flows Reticle could not map to source files, so it includes them to be
+  safe. A flow recorded before provenance tracking existed has no file list, and Reticle would
+  rather re-run it than skip it and miss a regression. A large `unknownProvenance` means your flows
+  predate the feature. Re-record the ones you care about to get precise selection.
+</Note>
+
+### `reticle gate`
+
+The CI gate. Exits non-zero unless passing artifacts cover the affected flows.
+
+```bash
+npx @reticlehq/server gate --since HEAD~1
+```
+
+```json
+{
+  "event": "reticle_gate",
+  "pass": false,
+  "uncovered": ["deploy-journey", "verify-modal", "…"],
+  "quarantined": ["drift-demo", "qa2-flow"],
+  "coverage": { "pct": 9, "covered": 4, "total": 47 }
+}
+```
+
+Measured exit code: **`1`**. That run genuinely failed, with 4 of 47 flows covered, which is what a gate is supposed to do when you have not verified anything yet.
+
+`quarantined` flows are excluded from the pass/fail decision. Quarantine is for a flow that is known flaky and being fixed; it is not a place to hide failures, because the list is printed on every run.
+
+### `reticle watch [url]`
+
+On save, report which saved flows must re-verify. The interactive companion to `affected`.
+
+## Maintenance
+
+| Command            | What it does                                        |
+| ------------------ | --------------------------------------------------- |
+| `reticle update`   | Install the latest server version and restart       |
+| `reticle rollback` | Restore the previous version and restart            |
+| `reticle license`  | Enterprise license status: active, eval, or missing |
+| `reticle version`  | Print the version                                   |
+| `reticle help`     | Usage for everything                                |
+
+<Tip>
+  `rollback` exists because an auto-updating dev tool that cannot go back is a dev tool that can
+  ruin your afternoon. It restores the previous version and restarts in one step.
+</Tip>
+
+## Feedback
+
+```bash
+# humans
+npx @reticlehq/server feedback "what worked, what didn't"
+
+# agents, including from a setup that never finished
+npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"
+```
+
+The `--agent` form matters more than it looks: the setup that failed halfway is exactly the setup worth hearing about, and in that state the MCP tools do not exist yet.
+
+<Card title="How feedback is handled" icon="comments" href="/tools-session-and-feedback">
+  What each kind means, and what happens when a report cannot be delivered.
+</Card>
+
+## `reticle identify`
+
+Opt-in, and off by default:
+
+```bash
+npx @reticlehq/server identify --context company|side_project|open_source|learning [--email E] [--forget]
+```
+
+Only useful if you want support or an enterprise trial. `--forget` removes it.

package/docs/debugging.md

@@ -1,6 +1,10 @@
-# Debugging Reticle itself
+---
+title: Debugging Reticle
+description: For people working on Reticle itself. How to work out why a flow behaved the way it did.
+icon: bug
+---
 
-> For people working **on** Reticle — and for an agent asked to explain why a flow behaved the way it did. If you are debugging **your app** with Reticle, you want [usage.md](usage.md) instead.
+> For people working **on** Reticle, and for an agent asked to explain why a flow behaved the way it did. If you are debugging **your app** with Reticle, you want [usage.md](usage.md) instead.
 
 Reticle produces four different signals and they answer four different questions. Reaching for the wrong one is why investigations here have historically started by reading source.
 
@@ -27,7 +31,7 @@ tail -f ~/.reticle/daemon-4400.log | jq .
 
 ## Verbose flow tracing
 
-Off by default, because a trace on every tool call is a cost on the hot path — a verification loop is 50–200 calls. Measured, so the claim is checkable: a disabled span costs **126ns** per site (against ~9ns for a bare call), which is under a microsecond per tool call and not the literal zero it is tempting to write. Turn it on **for the daemon** (the flag is read per call, but the daemon is the process doing the work, so it has to be set where the daemon starts):
+Off by default, because a trace on every tool call is a cost on the hot path, and a verification loop is 50 to 200 calls. Measured, so the claim is checkable: a disabled span costs **126ns** per site (against ~9ns for a bare call), which is under a microsecond per tool call and not the literal zero it is tempting to write. Turn it on **for the daemon** (the flag is read per call, but the daemon is the process doing the work, so it has to be set where the daemon starts):
 
 ```bash
 RETICLE_TRACE=1 reticle serve --port 4400
@@ -42,10 +46,10 @@ Every instrumented stage then emits one line **when it ends**, carrying its own
 
 Read it like this:
 
-- **`callId`** groups every stage of one tool call, and is prefixed with the daemon's pid so two daemons (or one that restarted) can never claim the same id. Several agents can be inside the daemon at once, so lines interleave — the id is the only thing that makes the output a tree instead of a pile.
+- **`callId`** groups every stage of one tool call, and is prefixed with the daemon's pid so two daemons (or one that restarted) can never claim the same id. Several agents can be inside the daemon at once, so lines interleave; the id is the only thing that makes the output a tree instead of a pile.
 - **`depth`** is the nesting level. `0` is the tool handler; anything deeper ran inside it.
 - **`ms`** is that stage's own wall-clock. A parent's `ms` includes its children's.
-- **`ok:false`** carries an `error` field. A stage that threw is still traced — otherwise the trace would show a call that entered a stage and never left, which reads as a hang.
+- **`ok:false`** carries an `error` field. A stage that threw is still traced; otherwise the trace would show a call that entered a stage and never left, which reads as a hang.
 
 One line per stage, at the end, is deliberate: a start line as well would double the volume to say something the end line already implies.
 
@@ -61,7 +65,7 @@ The spans that ship today:
 | `crawl.step` | one control the crawl clicked, including its settle budget |
 | `init.plan` / `init.apply` / `init.exec` / `init.exec.retry` / `init.write` | the install, phase by phase |
 
-The first two answer _"is this slow because of us or because of the app under test?"_ —
+The first two answer _"is this slow because of us or because of the app under test?"_
 
 `browser.command` close to `tool.handler` means the app is taking the time. A large gap between them is Reticle's own overhead, and that is a performance bug of ours.
 
@@ -79,7 +83,7 @@ grep '"event":"trace"' ~/.reticle/daemon-4400.log | jq -sc 'sort_by(-.ms)[:10] |
 
 ### The init flow
 
-`reticle init` is synchronous end to end, so it uses `spanSync` — same line, same tree:
+`reticle init` is synchronous end to end, so it uses `spanSync`: same line, same tree:
 
 ```
 init.plan        2ms
@@ -89,7 +93,7 @@ init.write        1ms  target=.reticle.json
 init.apply      262ms  steps=5
 ```
 
-Two things that trace makes visible and nothing else did. Planning is ~2ms, so init's wall-clock is essentially all subprocess: the package manager, and `claude mcp add` when MCP registration is on. And when the pinned install is refused, the unpinned **retry is a second full package-manager run** — init legitimately takes about twice as long on that path. Every `--local` fixture run takes it, because the version being installed is not published yet.
+Two things that trace makes visible and nothing else did. Planning is ~2ms, so init's wall-clock is essentially all subprocess: the package manager, and `claude mcp add` when MCP registration is on. And when the pinned install is refused, the unpinned **retry is a second full package-manager run**, so init legitimately takes about twice as long on that path. Every `--local` fixture run takes it, because the version being installed is not published yet.
 
 ### Adding a span
 
@@ -99,4 +103,4 @@ import { span } from '../trace.js';
 const result = await span('predicate.eval', { kind: predicate.kind }, () => evaluate(predicate));
 ```
 
-Wrap a stage worth a line in a bottleneck hunt — a session resolve, a browser round-trip, a predicate evaluation. Not every function: the trace earns its keep by being faster to read than the code, and that stops being true somewhere around one line per statement. Nesting needs no plumbing — the call id and depth ride in `AsyncLocalStorage`, so a span added five frames down still lands in the right tree without changing anyone's signature.
+Wrap a stage worth a line in a bottleneck hunt: a session resolve, a browser round-trip, a predicate evaluation. Not every function: the trace earns its keep by being faster to read than the code, and that stops being true somewhere around one line per statement. Nesting needs no plumbing: the call id and depth ride in `AsyncLocalStorage`, so a span added five frames down still lands in the right tree without changing anyone's signature.

package/docs/deploy-checks.md

@@ -1,8 +1,12 @@
-# Verification at the deploy choke point (Vercel / Netlify)
+---
+title: Deploy checks
+description: 'Enforce verification at the moment code becomes a preview URL, as a Vercel or Netlify check on the PR.'
+icon: circle-check
+---
 
-The strongest place to enforce verification is the moment code becomes a preview URL. Every deploy already produces one, and both Vercel and Netlify let a third party attach a **check** to it — pass/fail, shown on the PR, with no workflow file to write.
+The strongest place to enforce verification is the moment code becomes a preview URL. Every deploy already produces one, and both Vercel and Netlify let a third party attach a **check** to it: pass/fail, shown on the PR, with no workflow file to write.
 
-That makes the non-developer story complete: the SDK is auto-injected by the build plugin, flows are minted from toolbar recordings with auto-proposed consequences, and verification runs at publish — **without anyone writing a test.**
+That makes the non-developer story complete: the SDK is auto-injected by the build plugin, flows are minted from toolbar recordings with auto-proposed consequences, and verification runs at publish, **without anyone writing a test.**
 
 > Docs-only in v2.2.0. The pieces below all ship today (`reticle verify` exits 0/1 and persists a run artifact); what is _not_ built is a hosted Reticle app that registers itself as a provider. Wire it with the CI recipe until that exists.
 
@@ -14,11 +18,11 @@ git push → preview deploy → Reticle verifies the preview URL → check passe
 
 `reticle verify <preview-url>` is the whole integration surface:
 
-- exits **0** when every saved flow passes, **1** otherwise — the only contract a check needs,
+- exits **0** when every saved flow passes, **1** otherwise (the only contract a check needs),
 - prints a legible ✓/✗ report for the PR log,
 - persists a `ReticleVerificationRun` artifact (`.reticle/runs/<id>.json`) so `reticle gate` and `reticle_run_export` can consume the same verdict.
 
-## Recipe A — CI (works today, any provider)
+## Recipe A: CI (works today, any provider)
 
 ```yaml
 # .github/workflows/verify.yml
@@ -34,14 +38,14 @@ jobs:
       - run: pnpm install --frozen-lockfile
       - run: npx playwright install --with-deps chromium
       # Reticle drives the preview and owns its own browser + daemon.
-      - run: npx reticle verify "${{ github.event.deployment_status.target_url }}" --timeout 60000
+      - run: npx @reticlehq/server verify "${{ github.event.deployment_status.target_url }}" --timeout 60000
 ```
 
 The job's own pass/fail becomes the PR check. Nothing else is required.
 
-**Non-loopback previews need pairing.** For a real preview URL (not `localhost`), Reticle injects `reticle.connect()` with a one-time token and allow-lists the preview origin — so the app does not need to be rebuilt per environment. Confirm the SDK actually runs on the deployed build: a production build that tree-shakes the dev-only SDK will connect to nothing, and `verify` will (correctly) fail with _"no app connected."_
+**Non-loopback previews need pairing.** For a real preview URL (not `localhost`), Reticle injects `reticle.connect()` with a one-time token and allow-lists the preview origin, so the app does not need to be rebuilt per environment. Confirm the SDK actually runs on the deployed build: a production build that tree-shakes the dev-only SDK will connect to nothing, and `verify` will (correctly) fail with _"no app connected."_
 
-## Recipe B — the Checks API pattern (what a hosted Reticle would do)
+## Recipe B: the Checks API pattern (what a hosted Reticle would do)
 
 Both providers expose the same shape, which is why this is one integration rather than two:
 
@@ -54,10 +58,10 @@ The flow is: receive the deploy webhook → `reticle verify <target_url>` → po
 
 ## Pair it with the local gate
 
-The deploy check catches what reaches a preview. `reticle gate` catches it earlier — an agent that edits a covered file cannot "finish" without re-verifying:
+The deploy check catches what reaches a preview. `reticle gate` catches it earlier: an agent that edits a covered file cannot "finish" without re-verifying:
 
 ```bash
-reticle gate --since origin/main    # exit 1 unless passing artifacts cover the affected flows
+npx @reticlehq/server gate --since origin/main    # exit 1 unless passing artifacts cover the affected flows
 ```
 
 Use both: `gate` in the agent's Stop hook (see `agent-cheatsheet`), `verify` at the deploy. They read the same run artifacts, so a green gate locally and a green check on the PR mean the same thing.
@@ -66,4 +70,4 @@ Use both: `gate` in the agent's Stop hook (see `agent-cheatsheet`), `verify` at
 
 - **`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.
-- **No saved flows means nothing to verify** — `verify` fails rather than reporting a vacuous pass.
+- **No saved flows means nothing to verify.** `verify` fails rather than reporting a vacuous pass.