@reticlehq/server 2.7.0 → 2.9.0

package/docs/cli/status.mdx

@@ -0,0 +1,88 @@
+---
+title: reticle status
+description: Ask whether the Reticle daemon is up and which app sessions have connected to it.
+icon: heart-pulse
+---
+
+`reticle status` is the command that tells you whether the install actually finished. Not a tick in a checklist: a connected app.
+
+```bash
+npx @reticlehq/server status [--port N]
+```
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which daemon to ask |
+
+## What it prints
+
+One JSON line on stdout. Real capture, daemon up and no app connected:
+
+```json
+{
+  "t": "2026-08-15T18:43:33.724Z",
+  "event": "reticle_status",
+  "port": 4499,
+  "running": true,
+  "pid": 78137,
+  "sessionCount": 0,
+  "sessions": [],
+  "why": "no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is listening on the ports Reticle scans (3000, 3001, 4200, 4321, 5000, 5173, 5174, 8000, 8080, 8100, 9000, 1420, 3100, 4173, 5175, 7860, 8501), so the dev server may not be running ... (2) There is no `.reticle.json` in the directory this daemon is running in ..."
+}
+```
+
+With an app connected, `why` is absent and each session carries its own fields:
+
+```json
+{
+  "t": "2026-08-15T18:45:58.190Z",
+  "event": "reticle_status",
+  "port": 4400,
+  "running": true,
+  "pid": 72698,
+  "sessionCount": 1,
+  "sessions": [
+    {
+      "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
+      "url": "http://localhost:4310/",
+      "throttled": false,
+      "stale": false,
+      "pendingMarks": 0
+    }
+  ]
+}
+```
+
+Both are one line of JSON in the terminal, pretty-printed here, with `why` trimmed at the ellipses.
+
+| Field | Meaning |
+| --- | --- |
+| `running` | Whether a usable daemon owns the port |
+| `presence` | Present when the pid file is dead: `daemon`, `foreign`, or `absent`. The port is asked, not just the pid file |
+| `pid` | The daemon process |
+| `sessionCount` / `sessions` | Connected app sessions, each with `sessionId`, `url`, `throttled`, `stale`, `pendingMarks` |
+| `why` | Present when zero sessions connected. Names the two likely causes and refuses to assert either |
+| `updateAvailable` | Present when a newer server version is on the registry |
+
+<Note>
+  `status` asks the **port**, not only the pid file. `running: false` used to be printed about a
+  port that was demonstrably occupied, which sent the reader off to start a daemon that could never
+  bind.
+</Note>
+
+## Exit codes
+
+Always `0`. This command answers a question; it does not judge the answer.
+
+## Worked example
+
+```bash
+npx @reticlehq/server init
+npx @reticlehq/server status    # a session in the list means the app is genuinely wired
+```
+
+<Card title="Nothing connected?" icon="triangle-exclamation" href="/troubleshooting">
+  The bridge port is not your dev server port, and that is the most common cause.
+</Card>

package/docs/cli/stop.mdx

@@ -0,0 +1,64 @@
+---
+title: reticle stop
+description: Stop the Reticle daemon on a port, escalating from SIGTERM to SIGKILL if it will not go.
+icon: circle-stop
+---
+
+`reticle stop` reads the pid recorded for the port and stops that process.
+
+```bash
+npx @reticlehq/server stop [--port N] [--quiet]
+```
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which daemon to stop |
+| `--quiet` | boolean | `false` | Print nothing. For scripts that stop a daemon that may not be running |
+
+## How it stops
+
+1. `SIGTERM` first, then poll every 100ms.
+2. Still alive after 5 seconds: `SIGKILL`. A daemon that ignores `SIGTERM` is wedged, which is the one situation this command exists for, and giving up there left the port held and a human reaching for `kill -9`.
+3. Still alive 2 seconds after that: report `reticle_daemon_stop_timeout` with the pid and exit `1`. Surviving `SIGKILL` means the pid is not yours to kill, or it is an unkillable zombie. Neither is retryable.
+
+## What it prints
+
+| Event | When |
+| --- | --- |
+| `reticle_daemon_stopped` | It stopped. Carries `port`, `pid`, and `escalated: true` if it took a `SIGKILL` |
+| `reticle_daemon_not_running` | No live pid for that port. The stale pid file is removed |
+| `reticle_daemon_stop_timeout` | It survived everything. Exits `1` |
+
+Real capture, stopping a port with no live pid recorded for it. It exits `0`, because "already not running" is the state you asked for:
+
+```
+{"t":"2026-08-15T18:43:43.943Z","event":"reticle_daemon_not_running","port":4499}
+```
+
+With `--quiet` that same run prints nothing at all and still exits `0`.
+
+## Exit codes
+
+| Code | Meaning                        |
+| ---- | ------------------------------ |
+| `0`  | Stopped, or was not running    |
+| `1`  | The process survived `SIGKILL` |
+
+<Warning>
+  Do not stop a daemon with `lsof -ti tcp:4400 | xargs kill -9`. That pattern matches the agent's
+  own `reticle mcp` proxy as well as the daemon and takes both down. Use this command, or [`reticle
+  kill`](/cli/kill).
+</Warning>
+
+## When this is not enough
+
+`stop` needs the pid Reticle recorded. If the pid file is stale, was never written, or the port is held by a daemon from another checkout, `stop` reports `reticle_daemon_not_running` about a port that is demonstrably occupied. [`reticle kill`](/cli/kill) asks the **port** instead and is the command for that case.
+
+## Worked example
+
+```bash
+npx @reticlehq/server stop --port 4400 --quiet && npx @reticlehq/server serve --port 4400
+npx @reticlehq/server restart --port 4400   # the same thing, honest about each half
+```

package/docs/cli/telemetry.mdx

@@ -0,0 +1,57 @@
+---
+title: reticle telemetry
+description: Show, enable, or disable Reticle's anonymous usage metrics on this machine.
+icon: chart-line
+---
+
+`reticle telemetry` is the user-facing control for anonymous usage metrics.
+
+```bash
+npx @reticlehq/server telemetry [status|enable|disable]
+```
+
+## Sub-actions
+
+| Action | Default | What it does |
+| --- | --- | --- |
+| `status` | yes, when nothing is given | Report the current state, why it is that state, and where the policy lives |
+| `enable` |  | Turn metrics on for this machine |
+| `disable` |  | Persist a machine-wide opt-out. Unlike `RETICLE_TELEMETRY=0`, this survives shells |
+
+Any other word is a usage error: `unknown telemetry action: <word>`, exit `1`.
+
+## What it prints
+
+Human-readable lines on stdout, like [`doctor`](/cli/doctor). Real capture inside a Reticle source checkout:
+
+```
+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
+```
+
+When it is enabled, a third line names every way to turn it off:
+
+```
+opt out      reticle telemetry disable  (or RETICLE_TELEMETRY=0 / DO_NOT_TRACK=1)
+```
+
+## Exit codes
+
+| Code | Meaning                              |
+| ---- | ------------------------------------ |
+| `0`  | Status shown, or the setting changed |
+| `1`  | Unknown sub-action                   |
+
+## Worked example
+
+```bash
+npx @reticlehq/server telemetry status
+npx @reticlehq/server telemetry disable
+```
+
+<Card title="Exactly what is collected" icon="shield-check" href="/telemetry">
+  The complete list, in plain language, and every way to switch it off.
+</Card>
+<Card title="Every event, in schema detail" icon="database" href="/telemetry-events">
+  The contributor reference: payload blocks, field types, and what each event exists to answer.
+</Card>

package/docs/cli/update.mdx

@@ -0,0 +1,52 @@
+---
+title: reticle update
+description: Install the latest Reticle server version, sync the project SDK to match, and restart.
+icon: arrow-up
+---
+
+`reticle update` moves the installed server forward and brings the app's SDK with it.
+
+```bash
+npx @reticlehq/server update
+```
+
+No flags.
+
+## What it does, in order
+
+1. Ask the registry what is available.
+2. Compare by **direction**, not inequality. A registry version that merely differs is not a newer one, and the old check happily installed a downgrade.
+3. Nothing newer: log `reticle_update` with `ok: false` and `message: "already on the latest version"`, then stop.
+4. Otherwise sync the **app's SDK first**. `reticle update` used to swap only the CLI, so the command whose job is keeping an install current was itself a way to produce a version-skewed pair.
+5. Then apply the CLI update, which execs and exits. Your agent client restarts it.
+
+## What it prints
+
+| Event | Fields |
+| --- | --- |
+| `reticle_update` | `ok`, and either `from` and `to`, or `message` and `version` |
+| `reticle_update_sdk` | `synced`, `packages`, `to`, `packageManager`. Or `synced: false` with `reason: "no @reticlehq packages in this project"` |
+| `reticle_update_sdk_failed` | A `hint` naming the exact command to run by hand |
+| `reticle_update_failed` | The error |
+
+The SDK sync is best effort and non-fatal on purpose. This command gets run from wherever the human happens to be standing, which is often not an app at all.
+
+## Exit codes
+
+| Code | Meaning                                                              |
+| ---- | -------------------------------------------------------------------- |
+| `0`  | Already current, or the update was applied (the process is replaced) |
+| `1`  | The update check or install threw                                    |
+
+## Worked example
+
+```bash
+npx @reticlehq/server version     # 2.8.0
+npx @reticlehq/server update
+```
+
+<Warning>
+  Attaching to a running daemon is what a daemon is for, which means an upgrade does not take effect
+  until that daemon dies. Run [`reticle stop`](/cli/stop) afterwards if you need the new build
+  serving immediately.
+</Warning>

package/docs/cli/verify.mdx

@@ -0,0 +1,76 @@
+---
+title: reticle verify
+description: Drive a URL once, replay every saved flow, and exit zero only on a real pass.
+icon: circle-check
+---
+
+`reticle verify` is the CI command: no model in the loop, no MCP. It boots the engine in drive mode, waits for the in-page SDK to dial back, replays every saved flow, renders the verdict, and exits.
+
+```bash
+npx @reticlehq/server verify <url> [--headed] [--timeout N] [--storage-state <file>]
+```
+
+It uses the same runner and the same verdict as the MCP and HTTP paths, so a platform agent that can only run a shell command gets a byte-identical artifact.
+
+## Arguments and flags
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `url` | string, positional, **required** | none | The preview URL to drive |
+| `--headed` | boolean | `false` (headless) | Show the browser |
+| `--timeout N` | number, ms | `15000` | How long to wait for a browser session to dial back |
+| `--storage-state <file>` | string | unset | A Playwright storage state file. This is how you verify flows behind a login without scripting the login every time |
+
+## What it prints
+
+The rendered run report on stdout. On failure it names the cause on stderr instead, and there are two refusals worth knowing:
+
+```
+No app connected: Reticle drove the URL but no @reticlehq/browser session dialed back.
+  Make sure the SDK is in the build and reticle.connect() runs on the preview page (for a non-localhost preview: allowNonLocalhost + a pairing token).
+```
+
+```
+No saved flows to verify (.reticle/flows is empty), so refusing to report a pass for verifying nothing.
+  Flows are recorded interactively by an agent (reticle_record{action:"start"} → act → reticle_flow_save via the
+  MCP tools), then committed to .reticle/flows/. In CI, check those files in and re-run `reticle verify`.
+```
+
+<Warning>
+  Both of those are honesty guards, and both exit `1`. Verifying nothing is never a pass.
+</Warning>
+
+A URL that does not answer is not one of those two. It surfaces as the underlying Playwright error, prefixed with `verify failed:`, and also exits `1`. Real capture:
+
+```
+verify failed: page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:59999/
+Call log:
+  - navigating to "http://localhost:59999/", waiting until "domcontentloaded"
+```
+
+<Warning>
+  `verify` binds the bridge port itself and has **no `--port` flag**: passing one is rejected as
+  `unknown argument '--port'`. If a daemon is already on the port, `verify` dies with a raw `Error:
+  listen EADDRINUSE: address already in use 127.0.0.1:4400` stack trace before it drives anything.
+  Stop the daemon first, or move `verify` with the `RETICLE_PORT` environment variable. This bites
+  most often on a developer machine, where an agent has usually left a daemon running; in CI the
+  port is normally free.
+</Warning>
+
+## Exit codes
+
+| Code | Meaning                                                           |
+| ---- | ----------------------------------------------------------------- |
+| `0`  | The verdict was a pass                                            |
+| `1`  | Failed, or no session, or no flows, or the engine could not start |
+
+## Worked example
+
+```bash
+npm run build && npm run preview &
+npx @reticlehq/server verify http://localhost:4173 --timeout 60000
+```
+
+<Card title="Recording the flows this replays" icon="vial" href="/testing">
+  Flows are recorded interactively, then committed to `.reticle/flows/`.
+</Card>

package/docs/cli/version.mdx

@@ -0,0 +1,39 @@
+---
+title: reticle version
+description: Print the version of the Reticle server that is actually executing.
+icon: tag
+---
+
+`reticle version` prints the running package version. It is the diagnostic to reach for when you need to know which build `npx` actually resolved, which is not always the one you expected.
+
+```bash
+npx @reticlehq/server version
+npx @reticlehq/server --version
+npx @reticlehq/server -v
+```
+
+All three are the same command. No flags.
+
+## What it prints
+
+One `reticle_version` line. Real capture:
+
+```json
+{ "t": "2026-08-15T18:42:26.275Z", "event": "reticle_version", "version": "2.8.0" }
+```
+
+## Exit codes
+
+Always `0`.
+
+## Worked example
+
+```bash
+npx @reticlehq/server version | jq -r .version
+```
+
+<Note>
+  The version here is the CLI's. A daemon that was already running keeps serving its own build until
+  it exits, so [`reticle doctor`](/cli/doctor) is the command that compares the two and names a
+  skew.
+</Note>

package/docs/cli/watch.mdx

@@ -0,0 +1,62 @@
+---
+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-15T18:44:08.930Z","event":"reticle_watch_started","cwd":"/Users/you/reticle"}
+{"t":"2026-08-15T18:44:09.104Z","event":"reticle_buddy","status":"✓ 0/47 flows nominal · 9 flaky quarantined"}
+```
+
+A save then produces a `reticle_watch_affected` line naming the changed files and the flows they put at risk, followed by a refreshed buddy line. Real capture, with both lists trimmed:
+
+```json
+{"t":"2026-08-15T18:44:09.317Z","event":"reticle_watch_affected","changed":["packages/server/src/init/cursor.ts"],"affected":["WEB-flow","deploy-journey","verify-route"]}
+{"t":"2026-08-15T18:44:09.355Z","event":"reticle_buddy","status":"✗ 39 deviations: ELECTRON-1LINE-flow, ELECTRON-COLD-flow +37 more · 0 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,241 @@
+---
+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 `reticle` CLI wires Reticle into a project (`init`), runs and diagnoses the daemon your app connects to (`serve`, `status`, `doctor`, `kill`, `restart`), and gates a build on verification in CI (`verify`, `affected`, `gate`). This page is the index; each command has its own page with real captured output and measured exit codes.
+
+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. The CLI emits each structured line as one line of JSON; the blocks
+  below are pretty-printed so you can read them, and long lists are trimmed where the label says so.
+</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 (chromium-1234)
+  daemon       ✓ running on :4400 (pid 72698, 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
+{
+  "t": "2026-08-15T18:45:58.190Z",
+  "event": "reticle_status",
+  "port": 4400,
+  "running": true,
+  "pid": 72698,
+  "sessionCount": 1,
+  "sessions": [
+    {
+      "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
+      "url": "http://localhost:4310/",
+      "throttled": false,
+      "stale": false,
+      "pendingMarks": 0
+    }
+  ]
+}
+```
+
+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 and wait for it to bind. `--drive <url>`, `--headless`, `--headed`, `--http`, `--http-port N`, `--http-token T` |
+| `reticle stop` | Stop the daemon we started, by its recorded pid. `--quiet` |
+| `reticle kill` | Free the port by asking who is **listening** on it. `--force` |
+| `reticle restart` | Kill, then start a daemon and wait for a real bind. `--force` |
+| `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 |
+
+A bare `reticle` with no arguments is not help. It is `reticle serve`.
+
+<Warning>
+  `reticle verify` binds the bridge port itself, so it fails if a daemon is already listening, which
+  is the normal state once your agent has started one. Stop the daemon first, or point it elsewhere
+  with `RETICLE_PORT`. `reticle mcp` reuses a running daemon, and `reticle drive` attaches to one
+  (see [drive](/cli/drive)) rather than competing for the port.
+</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
+{
+  "t": "2026-08-15T18:42:57.431Z",
+  "event": "reticle_affected",
+  "changedFiles": ["SKILL.md", "docs/cli/doctor.mdx", "packages/server/src/init/agent-rules.ts"],
+  "affected": ["WEB-flow", "deploy-journey", "verify-modal", "verify-route"],
+  "unknownProvenance": ["WEB-flow", "deploy-journey", "verify-modal", "verify-route"]
+}
+```
+
+Both lists are trimmed here; the real run named 47 flows.
+
+<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
+{
+  "t": "2026-08-15T18:42:58.434Z",
+  "event": "reticle_gate",
+  "pass": false,
+  "uncovered": ["WEB-flow", "deploy-journey", "verify-modal", "verify-route"],
+  "quarantined": ["asserted-demo", "blast-radius-compose", "drift-demo", "qa2-flow"],
+  "coverage": { "pct": 0, "covered": 0, "total": 47 }
+}
+```
+
+Measured exit code: **`1`**, with the flow lists trimmed above. That run genuinely failed, with 0 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`. Long-running; stop it with `Ctrl+C`.
+
+### `reticle capsules`
+
+List the saved fail-to-pass bug capsules in `.reticle/capsules`. No flags. See [capsules](/cli/capsules).
+
+### `reticle hunt <dir>`
+
+Aggregate a directory of crawl reports into one false-green rate. See [hunt](/cli/hunt).
+
+## 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 [--company N] [--email E] [--forget]
+```
+
+Only useful if you want support or an enterprise trial. `--forget` removes it.