@reticlehq/server 2.7.0 → 2.8.0

package/docs/cli/doctor.mdx

@@ -0,0 +1,76 @@
+---
+title: reticle doctor
+description: Diagnose the Reticle setup in one command: Chromium, daemon, bridge port, logs, and desktop wiring.
+icon: stethoscope
+---
+
+`reticle doctor` collapses the setup failure modes into one command. It is the first thing to run when something is wrong.
+
+```bash
+npx @reticlehq/server doctor [--port N]
+```
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which bridge port to diagnose |
+
+## What it prints
+
+Human-readable lines on stdout, not the JSON log. Real capture:
+
+```
+reticle doctor
+  node         v22.14.0
+  chromium     ✓ installed (chromium-1223)
+  daemon       ✓ running on :4400 (pid 4795, 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
+```
+
+| Line | What it checks |
+| --- | --- |
+| `node` | The Node version running the CLI |
+| `chromium` | Whether the exact Chromium revision the bundled Playwright wants is on disk. The most common silent failure |
+| `daemon` | Whether the port holds a Reticle daemon, a foreign process (named where possible), or nothing. Adds a `version` line when the daemon's version or contract fingerprint disagrees with the CLI's |
+| `sessions` | Whether any page has actually connected. Zero is a FAILING check rather than a neutral note, because it is the state the setup most often stalls in: wired correctly, daemon up, nothing dialled in. When it is zero the daemon's own no-session diagnosis prints below the checklist |
+| `bridge port` | The port your app must dial, spelled out because mixing it up with the dev server port is the most common setup failure |
+| `daemon log` | Where the structured daemon log lives |
+| `tracing` | How to turn that log into a per-stage trace |
+| `desktop` | Only on a desktop project. Every Electron and Tauri misconfiguration here fails silently, so it is diagnosed explicitly |
+
+## The chromium line
+
+Playwright pins one Chromium revision per version, and the daemon launches that one and no other. So the check is not "is a Chromium there" but "is _this_ revision there", and the three answers have three different fixes.
+
+| Verdict | Real capture | What it means |
+| --- | --- | --- |
+| installed | `chromium     ✓ installed (chromium-1223)` | The wanted revision is on disk. Nothing to do |
+| wrong revision | `chromium     ✗ wrong revision — the bundled playwright wants chromium-1223; /tmp/pwroot holds chromium-1194, chromium-1208. run: npx playwright@1.60.0 install chromium` | Builds are installed, none of them the wanted one. One pinned download away |
+| missing | `chromium     ✗ missing — looked for /tmp/emptyroot/chromium-1223/chrome-mac-arm64/…; run: npx playwright@1.60.0 install chromium` | The browsers root holds no Chromium at all. If that root is not where your browsers live, `PLAYWRIGHT_BROWSERS_PATH` is what moves it |
+
+The wanted revision and the root are both read back off the path Playwright itself resolves, so `PLAYWRIGHT_BROWSERS_PATH` and every platform default (including `%LOCALAPPDATA%\ms-playwright` on Windows) are honoured without this command keeping its own table of roots.
+
+<Warning>
+  Run the command `doctor` prints, not `npx playwright install chromium`. The unpinned form resolves
+  the newest Playwright, downloads *its* revision, and leaves the check saying exactly what it said
+  before. That loop is why the line names the version to pin to.
+</Warning>
+
+## Exit codes
+
+Always `0`. `doctor` reports; it does not gate.
+
+## Worked example
+
+```bash
+npx @reticlehq/server doctor
+# then run the chromium command doctor printed, verbatim
+```
+
+<Card title="Deeper debugging" icon="bug" href="/debugging">
+  Reading the daemon log, and what `RETICLE_TRACE=1` adds to it.
+</Card>

package/docs/cli/drive.mdx

@@ -0,0 +1,55 @@
+---
+title: reticle drive
+description: Run Reticle in the foreground against a URL, with the browser visible, for debugging.
+icon: gauge-high
+---
+
+`reticle drive` runs the engine in the foreground and launches a browser at the URL you give it. It exists for debugging: you watch the run happen.
+
+```bash
+npx @reticlehq/server drive <url> [--headless] [--headed]
+```
+
+## Arguments and flags
+
+| Argument     | Type                             | Default                  | What it does      |
+| ------------ | -------------------------------- | ------------------------ | ----------------- |
+| `url`        | string, positional, **required** | none                     | The page to drive |
+| `--headed`   | boolean                          | on by default outside CI | Show the browser  |
+| `--headless` | boolean                          | on when `CI` is set      | Hide it           |
+
+`drive` is the one interactive command in the family, so it is the one that shows the browser by default. `serve`, `mcp` and the internal daemon own the pooled browser behind leases, which is batch work, and hide theirs.
+
+## What it prints
+
+`reticle_started` with the port on success, `reticle_start_failed` with the error otherwise.
+
+Omitting the URL is a usage error. Real capture:
+
+```
+{"t":"2026-08-14T19:38:46.975Z","event":"reticle_usage_error","message":"drive needs a url"}
+drive needs a url
+
+usage:
+  reticle init  [--dry-run] [--port N] ...
+```
+
+## Exit codes
+
+| Code | Meaning                                                |
+| ---- | ------------------------------------------------------ |
+| `0`  | Running in the foreground                              |
+| `1`  | No URL, an unknown flag, or the engine failed to start |
+
+<Warning>
+  `drive` binds the bridge port itself. If a daemon is already listening, it fails with an
+  `EADDRINUSE` stack trace, which is the normal state once your agent has started one. [`reticle
+  mcp`](/cli/mcp) reuses a running daemon; `drive` does not.
+</Warning>
+
+## Worked example
+
+```bash
+npx @reticlehq/server stop
+npx @reticlehq/server drive http://localhost:5173
+```

package/docs/cli/feedback.mdx

@@ -0,0 +1,67 @@
+---
+title: reticle feedback
+description: Send a report to the Reticle maintainers from the shell, including from a setup that never finished.
+icon: comment
+---
+
+`reticle feedback` is the feedback channel as a command: no prompts, no editor, no account. It exists so the cost of telling the maintainers something is lower than the cost of shrugging and moving on.
+
+```bash
+npx @reticlehq/server feedback [--rating 1-5] [--bug] "what worked, what didn't"
+npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"
+```
+
+The `--agent` form is for an agent that cannot reach the `reticle_feedback` tool: during `init`, while instrumentation is half wired, or when the daemon will not start. Those are the reports that are hardest to hear and most needed, because every other path requires the tool surface to already work.
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--rating N` | integer 1 to 5 | unset | A human's overall take. A bare rating with no words is a valid report |
+| `--bug` | boolean | `false` | Shorthand for `--kind bug` |
+| `--kind K` | one of `bug`, `gap`, `ambiguity`, `feature_request`, `improvement`, `experience` | `experience`, or `bug` with `--bug` | The report's class. Wins over `--bug` |
+| `--agent` | boolean | `false` | File as the agent, so agent reports never dilute the human rating signal |
+
+Everything that is not a flag or a flag's value becomes the message, joined with spaces. Quoting is still your job for shell reasons.
+
+## What it prints
+
+The payload is printed **before** it is sent, every time. A channel that carries free text and does not show you what it sends is asking for trust it has not earned.
+
+```
+sending      {"source":"human","kind":"experience","stack":"vite","runtime":"web"}
+redacted     email (removed before sending)
+thanks       your feedback is in. it genuinely changes what gets built next.
+```
+
+`not sent` replaces the last line when the send failed or telemetry is off, and names the reason. Humans who have never identified also get an offer of a reply route, printed after the receipt rather than as a prompt.
+
+Run with no message and no rating, it prints usage and exits `1`. Real capture:
+
+```
+usage: reticle feedback [--rating 1-5] [--bug] "what worked, what didn't"
+       agents: reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "what happened"
+       your words go to the maintainers; nothing from your app is ever included.
+```
+
+## Exit codes
+
+| Code | Meaning                                                         |
+| ---- | --------------------------------------------------------------- |
+| `0`  | The report was submitted, or attempted and reported as not sent |
+| `1`  | No message and no rating, or an invalid `--rating` or `--kind`  |
+
+## Worked example
+
+```bash
+npx @reticlehq/server feedback --agent --kind gap \
+  "no way to drive a contenteditable rich-text editor; had to skip the flow"
+```
+
+<Card
+  title="The same channel from inside a session"
+  icon="comments"
+  href="/tools-session-and-feedback"
+>
+  `reticle_feedback` when the tools are reachable.
+</Card>

package/docs/cli/gate.mdx

@@ -0,0 +1,64 @@
+---
+title: reticle gate
+description: Exit non-zero unless passing verification artifacts cover every flow the changed files affect.
+icon: shield-halved
+---
+
+`reticle gate` is what makes verification unavoidable. It computes the [affected](/cli/affected) flows, looks for a passing artifact for each, and fails the command if any is missing. An agent that edits a covered file cannot call itself finished without re-verifying.
+
+```bash
+npx @reticlehq/server gate [--since <ref>] [file...]
+```
+
+## Arguments and flags
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `file...` | strings, positional | none | Explicit changed files |
+| `--since <ref>` | string | `HEAD` when no files are given | Also include files git reports as changed since this ref |
+
+## What blocks and what does not
+
+| Category | Blocking | Why |
+| --- | --- | --- |
+| `uncovered` | Yes | An affected flow with no passing artifact |
+| `downgraded` | Yes | A flow whose assertions were weakened since its last passing run. A green bought by weakening the test is the gaming move this exists to stop |
+| `deletedCoverage` | Yes | A flow that covered a changed file and has since vanished. Coverage deleted, not satisfied |
+| `quarantined` | No | Flows the flake ledger has quarantined. Surfaced, never blocking, because one unexplained flake that blocks a merge destroys trust in the red |
+
+## What it prints
+
+One `reticle_gate` line. Real capture from this repository, with the flow lists trimmed for length:
+
+```json
+{
+  "t": "2026-08-14T19:38:56.353Z",
+  "event": "reticle_gate",
+  "pass": false,
+  "uncovered": ["deploy-journey", "verify-route", "verify-500"],
+  "quarantined": ["asserted-demo", "blast-radius-compose"],
+  "coverage": { "pct": 28, "covered": 13, "total": 47 }
+}
+```
+
+`downgraded` and `deletedCoverage` appear only when they are non-empty.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Every affected, non-flaky flow has a passing artifact and nothing was weakened or deleted |
+| `1` | Something is uncovered, downgraded or deleted. Also `1` on any internal fault: the gate fails closed |
+
+Measured on this repository, `npx @reticlehq/server gate --since HEAD~1` exited `1` with the output above.
+
+## Worked example
+
+```yaml
+- run: npx @reticlehq/server verify http://localhost:4173
+- run: npx @reticlehq/server gate --since ${{ github.event.pull_request.base.sha }}
+```
+
+<Card title="Wiring this into CI" icon="rocket" href="/deploy-checks">
+  Where the gate sits relative to build, verify, and merge.
+</Card>

package/docs/cli/help.mdx

@@ -0,0 +1,92 @@
+---
+title: reticle help
+description: Print the complete Reticle command grammar, every command and every flag, on one screen.
+icon: circle-question
+---
+
+`reticle help` prints the whole usage block to stdout and exits `0`.
+
+```bash
+npx @reticlehq/server help
+npx @reticlehq/server --help
+npx @reticlehq/server -h
+```
+
+All three are the same command.
+
+<Warning>
+  There is no per-command help. `reticle init --help` is not a help request, it is an unknown
+  argument: the parser rejects it, prints `unknown argument '--help'`, and exits `1`. This page and
+  the rest of this section are the per-command reference.
+</Warning>
+
+## What it prints
+
+Real capture, in full:
+
+```
+usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)
+
+  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)
+                --app picks WHICH app in a monorepo, when several are found
+                --no-mcp skips MORE than the server registration: also the agent rule files
+                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
+                only make sense once the tools are reachable.
+  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]
+  reticle stop  [--port N] [--quiet]
+  reticle status [--port N]
+  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
+  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
+  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
+  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
+  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)
+  reticle watch [url]                                  (on save, report which saved flows must re-verify)
+  reticle drive <url> [--headless]                     (foreground mode, for debugging)
+  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)
+  reticle update                                       (install the latest server version and restart)
+  reticle rollback                                     (restore the previous server version and restart)
+  reticle license                                      (show enterprise license status: active | eval | missing)
+  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)
+  reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't; prints exactly what it sends)
+  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "message"
+                                                       (agents: file from anywhere, including a setup that never finished)
+  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
+                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
+
+Cloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):
+  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)
+  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)
+  reticle whoami                                        (who am I signed in as, and is this repo attached?)
+  reticle project <ls|create <name>>                   (list or create cloud projects)
+  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
+  reticle push                                          (send local run artifacts to the dashboard)
+  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)
+
+'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay
+and the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.
+```
+
+## Errors print it too
+
+Any usage error prints the offending thing first, then this same block on stderr, and exits `1`:
+
+```
+{"t":"2026-08-14T19:38:47.402Z","event":"reticle_usage_error","message":"unknown command 'nonsense-cmd'"}
+unknown command 'nonsense-cmd'
+
+usage:
+  ...
+```
+
+Two audiences, two channels: the structured line for logs and scripts, the plain text for the person who just typed the command.
+
+## Exit codes
+
+| Code | Meaning                                           |
+| ---- | ------------------------------------------------- |
+| `0`  | Help was requested                                |
+| `1`  | Help was printed because something else was wrong |
+
+<Note>
+  A bare `reticle` with no arguments is **not** help. It is [`reticle serve`](/cli/serve).
+</Note>

package/docs/cli/hunt.mdx

@@ -0,0 +1,57 @@
+---
+title: reticle hunt
+description: Aggregate many crawl reports into one false-green rate across already-merged changes.
+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?
+
+```bash
+npx @reticlehq/server hunt <dir-of-crawl-reports>
+```
+
+No control arm is needed. Those changes shipped, so the counterfactual is already established.
+
+## Arguments
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `<dir>` | string, positional, **required** | none | Directory of `*.json` crawl reports. Each file is one crawl over one checkout |
+
+Each input file is read for `label` (falling back to the filename), `anomalies[]`, and `stepsRun`.
+
+## What it prints
+
+One `reticle_hunt` line with the summary:
+
+| Field | Meaning |
+| --- | --- |
+| `runs` | Report files read |
+| `runsWithCoverage` | Runs that drove at least one control. The only honest denominator: a run that drove nothing is not evidence of cleanliness |
+| `runsWithContradictions` | Runs with at least one cross-channel contradiction |
+| `contradictions` | Total contradictions. The kinds are `ui-advanced-request-failed`, `signal-contradicted`, `response-ignored`, `duplicate-request`, `request-never-settled`, `failure-misattributed` |
+| `singleChannelFaults` | Everything else: console errors, failed requests, dead controls. Context, not the claim |
+| `byKind` | Counts per anomaly kind |
+| `flagged` | The labels with contradictions, so each can be confirmed by hand |
+| `headline` | A sentence phrased so it cannot overstate itself. It says "candidate", because every flag still needs manual confirmation |
+
+## Exit codes
+
+Always `0`. A read failure is logged as `reticle_hunt_failed`. Omitting the directory is a usage error:
+
+```
+{"t":"2026-08-14T19:38:47.116Z","event":"reticle_usage_error","message":"usage: reticle hunt <dir-of-crawl-reports>"}
+```
+
+That path exits `1`.
+
+## Worked example
+
+```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:
+  # .../reports/$sha.json
+done
+npx @reticlehq/server hunt ./reports
+```

package/docs/cli/identify.mdx

@@ -0,0 +1,62 @@
+---
+title: reticle identify
+description: Opt in to telling the Reticle maintainers who you are, and undo it at any time.
+icon: id-card
+---
+
+`reticle identify` is opt-in and deliberately not interactive. A prompt in the middle of someone's work is pressure, and this is the one command where the choice has to be free. You type what you want to share, or you never run it at all.
+
+```bash
+npx @reticlehq/server identify --context <company|side_project|open_source|learning> [--company "Acme"] [--email you@acme.com] [--forget]
+```
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--context K` | one of `company`, `side_project`, `open_source`, `learning` | none. Required unless `--forget` | What Reticle is being used for |
+| `--company N` | string | unset | Your company name. Optional |
+| `--email E` | string | unset | An address to reach you on. Optional |
+| `--forget` | boolean | `false` | Delete the local identity file and stop sending it |
+
+Every field except the context is optional, so you can say "this is a company" without saying which, or name the company without leaving an address.
+
+## What it prints
+
+The consent notice, then the exact payload, then the result:
+
+```
+sending      {"context":"company","company":"Acme","email":"you@acme.com"}
+thanks       saved and sent. we may reach out; `reticle identify --forget` undoes this.
+```
+
+`not sent` replaces the last line when telemetry is disabled on the machine, in which case the identity is saved locally only.
+
+With `--forget`:
+
+```
+forgotten    the local identity file is deleted; nothing further is sent.
+             to have what was already sent removed, email support@reticlehq.com
+```
+
+Run with no valid `--context`, it prints the current identity (if any), the usage, and the full consent notice.
+
+<Warning>
+  Identifying links this machine's anonymous id to what you type, which also connects the anonymous
+  usage already recorded from this machine to that identity. The command says so before it sends
+  anything. Nothing about your app, your code, or your repository is ever included.
+</Warning>
+
+## Exit codes
+
+| Code | Meaning                                                                        |
+| ---- | ------------------------------------------------------------------------------ |
+| `0`  | Identity saved, or forgotten, or usage printed when an identity already exists |
+| `1`  | No valid `--context` and no identity on file                                   |
+
+## Worked example
+
+```bash
+npx @reticlehq/server identify --context open_source --email maintainer@example.com
+npx @reticlehq/server identify --forget
+```

package/docs/cli/init.mdx

@@ -0,0 +1,94 @@
+---
+title: reticle init
+description: Wire Reticle into the project in the current directory, registering the MCP server and installing the SDK.
+icon: wand-magic-sparkles
+---
+
+`reticle init` is the one command a person runs before anything else. It inspects the directory it is standing in, works out the framework, and writes every piece of wiring Reticle needs: the MCP server registration, the agent rule files, the dev dependencies, `.reticle.json`, and the bundler plugin.
+
+```bash
+npx @reticlehq/server init [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>] [--yes]
+```
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--dry-run` | boolean | `false` | Print the full plan and write nothing |
+| `--port N` | number | unset (resolves to `4400`) | Bridge port to write into the config |
+| `--no-mcp` | boolean | `false` (MCP is registered) | Skip the MCP registration **and** the agent rule files (`CLAUDE.md`, `AGENTS.md`, `.cursor`) and the `/reticle` command |
+| `--no-install` | boolean | `false` (deps are installed) | Skip the dependency install step |
+| `--app <dir>` | string | unset | Pick which app to wire in a monorepo, without changing directory |
+| `--yes` | boolean | `false` | Accepted for scripting. `init` has no interactive prompts today, so it is a no-op |
+
+<Warning>
+  `--no-mcp` skips more than the server registration. The agent rule files and the `/reticle`
+  command go with it, because all three only make sense once the tools are reachable.
+</Warning>
+
+## What it prints
+
+A plan, one line per step, each with a status mark: `✓` written, `·` already in place or left alone, `⚠` needs a hand. Captured from a real run inside `apps/bench-app`:
+
+```
+reticle init (dry run, no files written)
+  in /Users/you/reticle/apps/bench-app
+
+  [·] MCP server (Claude, global) → global (claude user scope)
+      reticle already registered (install once, used by every project)
+  [·] MCP server (Cursor, global) → /Users/you/.cursor/mcp.json
+      reticle already in Cursor global config
+  [⚠] MCP server (Codex CLI) → /Users/you/.codex/config.toml
+      add this to /Users/you/.codex/config.toml by hand:
+      [mcp_servers.reticle]
+      command = "npx"
+      args = ["@reticlehq/server", "mcp"]
+
+  [✓] Agent verification rule → CLAUDE.md
+      teach the agent to verify features with Reticle after building them
+  [✓] The /reticle command → .claude/commands/reticle.md
+      type /reticle to verify one flow in the browser
+  [✓] Install dependencies → package.json
+      pnpm add -D @reticlehq/react@2.8.0 @reticlehq/vite-plugin@2.8.0
+  [✓] Reticle config → .reticle.json
+      write project config (framework + port)
+  [✓] Vite plugin → vite.config.ts
+      add reticle() to plugins (also injects connect())
+  [·] Capabilities + store → src/reticle-dev.ts
+      file exists, left alone, it is yours to edit
+
+Restart `vite`.
+```
+
+Run from a workspace root with several apps, it refuses to guess and names them instead:
+
+```
+Several apps found in this workspace. Re-run `reticle init` inside the one you want:
+  packages/next
+  packages/vite-plugin
+  apps/atlas
+  apps/bench-app
+  ...
+
+Or name one without changing directory:  reticle init --app packages/next
+```
+
+## Exit codes
+
+| Code | Meaning                                                                      |
+| ---- | ---------------------------------------------------------------------------- |
+| `0`  | The plan ran. Steps marked `⚠` still need a hand, and do not change the code |
+| `1`  | Init failed, or an unknown flag was passed                                   |
+
+## Worked example
+
+```bash
+cd apps/web
+npx @reticlehq/server init --dry-run     # read the plan first
+npx @reticlehq/server init               # then run it
+npx @reticlehq/server status             # confirm the app actually connected
+```
+
+<Card title="The install, step by step" icon="wand-magic-sparkles" href="/install-agentic">
+  What each step writes and how to read the four status marks.
+</Card>

package/docs/cli/kill.mdx

@@ -0,0 +1,91 @@
+---
+title: reticle kill
+description: Free the bridge port by killing its listener, without touching the agent's own MCP proxy.
+icon: skull
+---
+
+`reticle kill` frees the bridge port. It asks **who is listening** on the port and signals that one process, which is the whole difference between this command and the shell pipeline everybody reaches for.
+
+```bash
+npx @reticlehq/server kill [--port N] [--force]
+```
+
+<Warning>
+  Never free the port with `lsof -ti tcp:4400 | xargs kill -9`. `reticle mcp` holds a **client**
+  socket on that port, so `-ti` lists the proxy right beside the daemon and the pipeline kills both.
+  When the proxy dies, the agent's next tool calls get no reply at all: not an error, not a timeout.
+  Nothing is written to the proxy log either, because the process that writes it is the one that
+  died. That is the mechanism behind most "my MCP disconnected" reports.
+</Warning>
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which port to free |
+| `--force` | boolean | `false` | Kill the listener even when it is not a Reticle daemon |
+
+## kill or stop?
+
+They target different things, and the distinction matters exactly when you are stuck.
+
+|  | `reticle stop` | `reticle kill` |
+| --- | --- | --- |
+| Finds the process by | the pid recorded in Reticle's own state | the **listener** on the port |
+| Works when the pid file is stale or was never written | no | yes |
+| Works on a daemon from another checkout | no | yes |
+| Works without `lsof` (Windows, slim containers) | yes | yes, falling back to the recorded pid and saying so |
+
+Reach for `stop` in a script that shuts down a daemon it started. Reach for `kill` when the port is held and you want it back.
+
+## How it decides
+
+1. Look up the listener with `lsof -nP -iTCP:<port> -sTCP:LISTEN`. Client sockets are excluded by construction, so the proxy is never a candidate.
+2. It is Reticle's if it answers `/status`, **or** if it is the pid Reticle recorded for the port. `/status` outranks the pid file, so a daemon started from another checkout is still recognised as ours.
+3. Anything else is refused, by name, unless `--force`.
+4. `SIGTERM`, then `SIGKILL` after 5 seconds, then report that it survived and exit `1`.
+
+## What it prints
+
+Real captures.
+
+Killed:
+
+```
+{"event":"reticle_killed","port":4499,"pid":84420,"escalated":true,"listenerIdentified":true,"note":"only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, not the port, and was left alone — it goes dormant and starts a fresh daemon on the next tool call."}
+```
+
+Refused, because the listener is not ours:
+
+```
+{"event":"reticle_kill_refused","port":4498,"reason":"pid 84346 (\"Python\") is listening, and it is not a Reticle daemon — it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. Run it again with --force if that is what you meant, or start Reticle on another port.","holder":"Python"}
+```
+
+Nothing to free:
+
+```
+{"event":"reticle_kill_nothing_to_do","port":4499,"presence":"free"}
+```
+
+| Event | When |
+| --- | --- |
+| `reticle_killed` | The listener is gone. `escalated: true` means it took a `SIGKILL`; `forced: true` means `--force` overrode a refusal |
+| `reticle_kill_refused` | The listener is not a Reticle daemon and `--force` was not given. Exits `1` |
+| `reticle_kill_survived` | It survived `SIGKILL`. The port is still held. Exits `1` |
+| `reticle_kill_nothing_to_do` | No listener, and no live recorded pid |
+
+`listenerIdentified: false` means `lsof` could not run and the pid came from Reticle's records rather than from an observed listener. Those are different claims, so the field says which one you got.
+
+## Exit codes
+
+| Code | Meaning                                                            |
+| ---- | ------------------------------------------------------------------ |
+| `0`  | The port is free                                                   |
+| `1`  | The port is still held: refused, or the process survived `SIGKILL` |
+
+## Worked example
+
+```bash
+npx @reticlehq/server kill            # free 4400
+npx @reticlehq/server status          # confirm
+```