@reticlehq/server 2.8.0 → 2.9.0

package/docs/cli.mdx

@@ -4,6 +4,8 @@ description: Every reticle command. What it does, what it prints, and what it ex
 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
@@ -22,7 +24,8 @@ npx @reticlehq/server <command>
 
 <Note>
   Every output block on this page was captured by running the command. Where an exit code is quoted,
-  it was measured, not assumed.
+  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
@@ -50,8 +53,8 @@ npx @reticlehq/server doctor
 ```
 reticle doctor
   node         v22.14.0
-  chromium     ✓ installed
-  daemon       ✓ running on :4400 (pid 24735, v2.8.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
@@ -66,17 +69,19 @@ 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": 24735,
+  "pid": 72698,
   "sessionCount": 1,
   "sessions": [
     {
-      "sessionId": "sece96901…",
-      "url": "http://localhost:4312/",
-      "throttled": true,
-      "stale": false
+      "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
+      "url": "http://localhost:4310/",
+      "throttled": false,
+      "stale": false,
+      "pendingMarks": 0
     }
   ]
 }
@@ -103,16 +108,21 @@ policy       https://github.com/reticlehq/reticle/blob/main/docs/telemetry.md
 
 | Command | What it does |
 | --- | --- |
-| `reticle serve` | Start the daemon in the foreground. `--drive <url>`, `--headless`, `--http` |
-| `reticle stop` | Stop it |
+| `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 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.
+  `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
@@ -137,13 +147,16 @@ npx @reticlehq/server affected --since HEAD~1
 
 ```json
 {
+  "t": "2026-08-15T18:42:57.431Z",
   "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", "…"]
+  "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
@@ -161,21 +174,30 @@ npx @reticlehq/server gate --since HEAD~1
 
 ```json
 {
+  "t": "2026-08-15T18:42:58.434Z",
   "event": "reticle_gate",
   "pass": false,
-  "uncovered": ["deploy-journey", "verify-modal", "…"],
-  "quarantined": ["drift-demo", "qa2-flow"],
-  "coverage": { "pct": 9, "covered": 4, "total": 47 }
+  "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`**. 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.
+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`.
+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
 
@@ -213,7 +235,7 @@ The `--agent` form matters more than it looks: the setup that failed halfway is
 Opt-in, and off by default:
 
 ```bash
-npx @reticlehq/server identify --context company|side_project|open_source|learning [--email E] [--forget]
+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.

package/docs/debugging.md

@@ -4,6 +4,8 @@ description: For people working on Reticle itself. How to work out why a flow be
 icon: bug
 ---
 
+**To debug Reticle itself, start with the daemon log at `~/.reticle/daemon-<port>.log`, and turn on `RETICLE_TRACE=1` for the daemon when you need per-stage timings.** `reticle doctor` prints the exact log path for your port. Reticle produces four distinct signals and they answer four different questions, so the first step is picking the right one.
+
 > 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.
@@ -39,7 +41,7 @@ RETICLE_TRACE=1 reticle serve --port 4400
 
 Every instrumented stage then emits one line **when it ends**, carrying its own duration:
 
-```json
+```jsonl
 {"event":"trace","span":"browser.command","ms":412,"depth":1,"callId":"p8123-c7","ok":true,"command":"act"}
 {"event":"trace","span":"tool.handler","ms":430,"depth":0,"callId":"p8123-c7","ok":true,"tool":"reticle_act"}
 ```

package/docs/deploy-checks.md

@@ -4,11 +4,13 @@ description: 'Enforce verification at the moment code becomes a preview URL, as
 icon: circle-check
 ---
 
+To gate a PR on Reticle, run `npx @reticlehq/server verify <preview-url>` in CI when the preview deploy succeeds. It exits **0** when every saved flow passes and **1** otherwise, so the job's own pass/fail becomes the check on the PR. There is no workflow-level integration to write beyond that one command.
+
 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.**
 
-> 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.
+> **Recipe A works today; Recipe B does not exist yet.** `reticle verify` exits 0/1 and persists a run artifact right now. What is _not_ built is a hosted Reticle app that registers itself as a Vercel or Netlify check provider. Until it exists, use the CI recipe.
 
 ## The shape
 
@@ -35,6 +37,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
+      # setup-node must come AFTER pnpm/action-setup, or its pnpm cache has no pnpm to find.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
       - run: pnpm install --frozen-lockfile
       - run: npx playwright install --with-deps chromium
       # Reticle drives the preview and owns its own browser + daemon.
@@ -71,3 +78,25 @@ 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.
+
+## FAQ
+
+### verify says 'no app connected' on my preview URL. Why?
+
+Almost always because the deployed build tree-shook the dev-only SDK out, so there is nothing in the page dialling the bridge. `reticle.connect()` is meant to be dev-gated, and a production build honours that gate. Either build the preview with the dev guard satisfied, or accept that `verify` is correctly reporting that it cannot see the app. It is not a false alarm: with no SDK there is no program to read.
+
+### Does it work on a real preview URL, or only localhost?
+
+Both. For a non-loopback origin Reticle injects `reticle.connect()` with a one-time pairing token and allow-lists the preview origin, so you do not rebuild per environment. The bridge refuses to bind a non-loopback host without a token, which is the point.
+
+### 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.
+
+### Should I run reticle gate as well as reticle verify?
+
+If you want an agent to be unable to call a change finished without re-verifying, yes. They catch the same regression at different moments: `gate` runs locally against the files the agent just edited, `verify` runs against the deployed preview. They read the same run artifacts, so a green gate locally and a green check on the PR mean the same thing.
+
+### verify exited 1 but I cannot see which flow failed.
+
+The verdict is in the run artifact, not only in the log. Each run writes `.reticle/runs/<id>.json` with `repair.failurePackets[]` naming what broke and where; `reticle_run_export { format: "report" }` renders it legibly. The artifact is stable and versioned precisely so a CI surface can render it without parsing log lines.