@reticlehq/server 3.5.0 → 3.7.0

package/docs/cli/init.mdx

@@ -7,7 +7,10 @@ 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]
+npx @reticlehq/server init [--env KEY=VALUE]... [--app <dir>] [--license <key>] [--json]
+                           [--files-only] [--relaunch] [--no-open] [--no-agents] [--url <app url>]
+                           [--timeout S] [--dry-run] [--hooks] [--port N] [--no-mcp] [--no-install]
+                           [--start] [--capture-bodies] [--no-first-run]
 ```
 
 ## Flags
@@ -17,9 +20,21 @@ npx @reticlehq/server init [--dry-run] [--port N] [--no-mcp] [--no-install] [--a
 | `--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) | Do not run the install. The step becomes `[⚠]` and prints the `add -D` command for you to run by hand, rather than vanishing from the plan |
-| `--app <dir>` | string | unset | Pick which app to wire in a monorepo, without changing directory |
+| `--no-install` | boolean | `false` (deps are installed) | Do not run the install. The step becomes `[–]` ("skipped (--no-install); install them yourself: …") with the install command for you to run by hand, rather than vanishing from the plan |
+| `--app <dir>` | string | unset | Pick which app to wire in a monorepo, without changing directory. On its own it implies `--files-only` |
+| `--start` | boolean | `false` | With `--app`, also boot the app the way a plain `init` does |
+| `--capture-bodies` | boolean | `false` | Write `captureNetworkBodies: true` into the Vite plugin call, so request and response bodies are captured |
+| `--no-first-run` | boolean | `false` | Connect and stop, without the coverage summary |
 | `--hooks` | boolean | `false` | Also add a print-only Stop hook to `.claude/settings.json`, merged into what is there. When the agent stops without a claim that held, it prints one line; it never blocks. See [`reticle report`](/cli/report) |
+| `--env KEY=VALUE` | string, repeatable | none | What the app needs to reach a usable state: a key from `.env.example`, a mock backend, a variable that skips an auth wall. A value may contain spaces and `=` |
+| `--license <key>` | string | unset | Write an enterprise license key to `.env` and keep `.env` out of git |
+| `--json` | boolean | `false` | Put the result on stdout as one object, for an agent to read |
+| `--files-only` | boolean | `false` | Write the files, register the MCP server and pre-approve the tools, then stop: no dev server, no browser. Also the upgrade path for an existing install |
+| `--relaunch` | boolean | `false` | Print the exact command that restarts this agent conversation with the `reticle_*` tools loaded. Refuses when the session has no transcript behind it. Works with `--files-only` |
+| `--no-open` | boolean | `false` | Do not open a browser window. The connect is checked in a hidden tab instead |
+| `--no-agents` | boolean | `false` | Do not register the MCP server with the other agents on this machine |
+| `--url <app url>` | string | unset | The app is already running at this URL: use it instead of starting a dev server |
+| `--timeout S` | seconds | the framework's own budget | How long to wait for the dev server and for a session to connect |
 | `--yes` | boolean | `false` | Accepted for scripting. `init` has no interactive prompts today, so it is a no-op |
 
 <Warning>
@@ -29,7 +44,7 @@ npx @reticlehq/server init [--dry-run] [--port N] [--no-mcp] [--no-install] [--a
 
 ## What it prints
 
-A plan, one line per step, each with a status mark: `✓` written, `·` already in place or left alone, `⚠` needs a hand, `–` deliberately skipped by a flag. Captured from a real `--dry-run` inside `apps/bench-app`:
+A plan, one line per step, each with a status mark: `✓` written, `·` already in place or left alone, `⚠` needs a hand, `–` deliberately skipped by a flag, `ℹ` done, but incomplete in a way that matters. Captured from a real `--dry-run` inside `apps/bench-app`:
 
 ```
 reticle init (dry run, no files written)
@@ -37,8 +52,8 @@ reticle init (dry run, no files written)
 
   [·] 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 (Cursor) → /Users/you/.cursor/mcp.json
+      reticle already registered with Cursor
   [⚠] MCP server (Codex CLI) → /Users/you/.codex/config.toml
       add this to /Users/you/.codex/config.toml by hand:
       [mcp_servers.reticle]
@@ -54,7 +69,7 @@ reticle init (dry run, no files written)
   [✓] 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
+      pnpm add -D @reticlehq/react@3.7.0 @reticlehq/vite-plugin@3.7.0
   [✓] Reticle config → .reticle.json
       write project config (framework + port)
   [✓] Vite plugin → vite.config.ts
@@ -62,9 +77,11 @@ reticle init (dry run, no files written)
   [·] Capabilities + store → src/reticle-dev.ts
       file exists, left alone, it is yours to edit
 
-Restart `vite`.
+Restart your dev server (`vite`).
 ```
 
+The install line pins the packages to the version of Reticle you are running. When the `codex` binary is on your PATH, the Codex row is not a hand edit: it reads `[✓] MCP server (Codex CLI)` and registers through `codex mcp add reticle -- npx @reticlehq/server mcp`.
+
 Below the plan it also prints the two things that actually finish the install: restart your agent so it re-reads its MCP server list, then run `npx @reticlehq/server status` to confirm the app connected.
 
 With `--no-mcp`, the whole MCP and rules group collapses into one skipped line:
@@ -74,24 +91,22 @@ With `--no-mcp`, the whole MCP and rules group collapses into one skipped line:
       --no-mcp ... also skips the agent rule files (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command
 ```
 
-Run from a workspace root with several apps, it refuses to guess, names them, and exits `1`:
+Run from a workspace root with several apps, it refuses to guess, prints a command for each one, and exits `1`:
 
 ```
-Several apps found in this workspace. Re-run `reticle init` inside the one you want:
-  adapters/build/next
-  adapters/build/vite
-  apps/atlas
-  apps/bench-app
-  apps/electron-smoke
-  apps/large-dom-bench
-  apps/next-smoke
-  apps/tauri-smoke
-  apps/vibe-builder-demo
-
-Or name one without changing directory:  reticle init --app apps/next-smoke
+Several apps found in this workspace. Re-run `reticle init` for the one you want:
+  reticle init --app adapters/build/next
+  reticle init --app adapters/build/vite
+  reticle init --app apps/atlas
+  reticle init --app apps/bench-app
+  reticle init --app apps/electron-smoke
+  reticle init --app apps/large-dom-bench
+  reticle init --app apps/next-smoke
+  reticle init --app apps/tauri-smoke
+  reticle init --app apps/vibe-builder-demo
 ```
 
-Given `--app`, it says which directory it moved to before printing the plan:
+Given `--app`, it writes that app's files and starts nothing: no daemon and no dev server, since a monorepo app's dev server is often run from the root. Add `--start` to boot it the way a plain `init` does. It says which directory it moved to before printing the plan:
 
 ```
 No app in this directory ... wiring apps/bench-app instead.
@@ -101,12 +116,12 @@ In the two captures above, the punctuation that separates the two halves of the
 
 ## Exit codes
 
-| Code | Meaning                                                                                 |
-| ---- | --------------------------------------------------------------------------------------- |
-| `0`  | The plan ran. Steps marked `⚠` still need a hand, and do not change the code            |
-| `1`  | Init failed, an unknown flag was passed, or several apps were found and none was chosen |
+| Code | Meaning |
+| --- | --- |
+| `0` | The app connected. Steps marked `⚠` still need a hand, and do not change the code |
+| `1` | No session connected, init failed, an unknown flag was passed, or several apps were found and none was chosen |
 
-An unknown flag is rejected by name: `reticle init --bogus` prints `unknown argument '--bogus'`, then the full usage block, and exits `1`.
+An unknown flag is rejected by name: `reticle init --bogus` prints `unknown argument '--bogus'`, then the short usage (`reticle --help`), and exits `1`.
 
 ## Worked example
 
@@ -118,5 +133,5 @@ 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.
+  What each step writes and how to read the five status marks.
 </Card>

package/docs/cli/license.mdx

@@ -14,24 +14,28 @@ No flags.
 
 ## What it prints
 
-One `reticle_license` line. Real capture on a checkout with no issuer key configured:
+One `reticle_license` JSON line, on stderr. On a checkout with no issuer key configured:
 
 ```json
 {
   "t": "2026-08-15T18:42:26.758Z",
   "event": "reticle_license",
+  "gated": ["audit-log"],
+  "contact": "hey@reticle.sh",
   "status": "eval",
   "detail": "evaluation mode: enterprise features run free (no issuer key configured)"
 }
 ```
 
-| `status`  | Meaning                                       |
-| --------- | --------------------------------------------- |
-| `active`  | A valid license is present                    |
-| `eval`    | Evaluation mode. Enterprise features run free |
-| `missing` | No license, and the build expects one         |
+| `status`  | Meaning                                             |
+| --------- | --------------------------------------------------- |
+| `active`  | A valid license is present                          |
+| `eval`    | Evaluation mode. Enterprise features run free       |
+| `missing` | No license, and the build expects one               |
+| `expired` | The key verified, but its expiry has passed         |
+| `invalid` | The key was rejected, or the build is misconfigured |
 
-`detail` is a sentence explaining the status.
+`detail` is a sentence explaining the status. An active license also carries `licenseId`, `org`, `plan` and `expiresAt`.
 
 ## Exit codes
 
@@ -40,7 +44,7 @@ Always `0`.
 ## Worked example
 
 ```bash
-npx @reticlehq/server license | jq -r .status
+npx @reticlehq/server license 2>&1 | jq -r .status
 ```
 
 <Card title="What enterprise covers" icon="building" href="/enterprise">

package/docs/cli/mcp.mdx

@@ -18,15 +18,15 @@ This is what `reticle init` registers, so you rarely type it yourself.
 | --- | --- | --- | --- |
 | `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Bridge port |
 | `--drive <url>` | string | unset | Have the daemon launch its own browser at this URL, so the agent has autonomous control without relying on your tab |
-| `--headless` | boolean | `true` for `mcp` | Hide that browser |
-| `--headed` | boolean | `false` | Show it |
+| `--headless` | boolean | on when `CI` or `RETICLE_HEADLESS` is set, or on Linux with no display | Hide that browser |
+| `--headed` | boolean | on otherwise | Show it |
 | `--http` | boolean | `false` | Forward the HTTP verify endpoint flags to the daemon it spawns |
 | `--http-port N` | number | unset | Port for that endpoint |
 | `--http-token T` | string | unset | Bearer token for it |
 
 ## The rule this command lives by
 
-The proxy **is** the MCP server the editor launched. Nothing respawns it, so an uncaught throw here is what a user experiences as "the MCP server disconnected". Three behaviours follow from that:
+The proxy **is** the MCP server the editor launched. Nothing respawns it, so an uncaught throw here is what a user experiences as "the MCP server disconnected". Four behaviours follow from that:
 
 - Crash handlers write to the proxy's own log file, not just stderr, because the editor swallows stderr.
 - A daemon that is not there is not fatal. The proxy answers `initialize` itself, serves the cached tool catalog, and retries a daemon on every client request. Present and complaining beats absent, because absent needs a human.
@@ -35,7 +35,7 @@ The proxy **is** the MCP server the editor launched. Nothing respawns it, so an
 
 ## What it prints
 
-Structured lines to the proxy log (`~/.reticle/`), not to your terminal, since stdout is the MCP transport.
+Structured JSON lines on stderr, never stdout, since stdout is the MCP transport. Most editors swallow stderr, so the idle exit and the crash handlers also write to the proxy log, `~/.reticle/proxy-<port>.log`.
 
 | Event | Meaning |
 | --- | --- |

package/docs/cli/open.mdx

@@ -1,10 +1,10 @@
 ---
 title: reticle open
-description: Show the app in a browser, reusing the already-connected tab when there is one.
+description: Open the app in your default browser, or reuse a tab that is already connected.
 icon: window-maximize
 ---
 
-`reticle open` is the one-command "show me the app". It resolves the port, makes sure a daemon is up, and then either reuses the tab that is already connected or opens a new one.
+`reticle open` is the one-command "show me the app". It resolves the port, makes sure a daemon is up, and then either reuses the tab that is already connected or hands the URL to your operating system's default browser. It never opens the browser Reticle drives.
 
 ```bash
 npx @reticlehq/server open [url] [--port N]
@@ -27,7 +27,7 @@ One `reticle_open` line, whose fields say which of four things happened.
 | --- | --- |
 | `reusing` | A connected tab was already on the right page. Nothing was opened |
 | `reusing` + `requested` + `note` | A tab is connected on that origin but sitting on a different page. It was **left there**, not navigated. Drive it with `reticle_navigate` or open the URL yourself |
-| `opened` + `connected: true` | A browser was launched and a Reticle session appeared |
+| `opened` + `connected: true` | The URL went to the system default browser and a new Reticle session appeared within 8 seconds |
 | `opened` + `connected: false` + `note` | The URL went to the system default browser and no session showed up within 8 seconds. Almost always means the app carries no SDK, or dials a different port |
 | `error` | No app connected and no URL given, or the browser could not be launched |
 

package/docs/cli/report.mdx

@@ -15,7 +15,7 @@ npx @reticlehq/server report [--session <id>] [--hook]
 | Flag | Default | What it does |
 | --- | --- | --- |
 | `--session <id>` | the newest session | Report a specific session |
-| `--hook` | off | Print one line, and only when the working tree changed and no claim held |
+| `--hook` | off | Print a short message, and only when the working tree changed and no claim held |
 
 ## What it prints
 
@@ -27,11 +27,13 @@ session lease-85f8191b-3874-457b-973b-8ee365e5acfb
   ✗ signal order:placed
 ```
 
+The report ends with one more line, an invitation to talk to the founder or leave an email. A session with no claims prints `no claims this session, so nothing was verified`.
+
 An `unknown` is never counted as held. It is Reticle saying it could not tell, and the owner beside it says what to do next.
 
 ## As a Claude Code Stop hook
 
-With `--hook` it prints nothing when a claim held or nothing in the tree changed, and otherwise one line, such as `Reticle: not verified. 3 claims: 1 failed, 2 unknown`. It prints Claude Code's `systemMessage` shape and always exits `0`: you see the line when the agent stops, and the agent is never blocked by it. `reticle init --hooks` adds it for you, merged into whatever `.claude/settings.json` already holds. By hand:
+With `--hook` it prints nothing when a claim held or nothing in the tree changed, and otherwise one line, such as `Reticle: not verified. 3 claims: 1 failed, 2 unknown`, followed by the same invitation line. It prints Claude Code's `systemMessage` shape and always exits `0`: you see the line when the agent stops, and the agent is never blocked by it. `reticle init --hooks` adds it for you, merged into whatever `.claude/settings.json` already holds. By hand:
 
 ```json
 {

package/docs/cli/restart.mdx

@@ -4,7 +4,7 @@ description: Free the bridge port and put a daemon back on it, reporting each ha
 icon: rotate
 ---
 
-`reticle restart` is [`reticle kill`](/cli/kill) followed by a daemon start that waits for a real bind.
+`reticle restart` is [`reticle stop --force`](/cli/stop#freeing-the-port-force) followed by a daemon start that waits for a real bind.
 
 ```bash
 npx @reticlehq/server restart [--port N] [--force]
@@ -55,6 +55,6 @@ npx @reticlehq/server restart         # after an upgrade, so the new version is
 npx @reticlehq/server status
 ```
 
-<Card title="Why not lsof" icon="skull" href="/cli/kill">
+<Card title="Why not lsof" icon="skull" href="/cli/stop#freeing-the-port-force">
   The pipeline everyone reaches for kills the agent's own MCP proxy along with the daemon.
 </Card>

package/docs/cli/rollback.mdx

@@ -1,10 +1,10 @@
 ---
 title: reticle rollback
-description: Restore the previously installed Reticle server version and restart.
+description: Reinstall the previously installed Reticle server version, then exit so your agent restarts it.
 icon: arrow-rotate-left
 ---
 
-`reticle rollback` is the undo for [`reticle update`](/cli/update). It restores the previous server version and restarts.
+`reticle rollback` is the undo for [`reticle update`](/cli/update). It reinstalls the version `update` replaced (recorded in the update manifest), then exits so the next start runs it.
 
 ```bash
 npx @reticlehq/server rollback
@@ -14,7 +14,11 @@ No flags.
 
 ## What it prints
 
-Nothing on the happy path: `rollback()` replaces the process. A failure logs `reticle_rollback_failed` with the error message.
+Two structured lines on the happy path, `reticle_rollback_applying` and `reticle_rollback_applied`, each with the `version` and the `executionKind` (`global`, `local` or `npx`). A failure logs `reticle_rollback_failed` with the error message.
+
+<Warning>
+  Run from a one-off `npx` download (no global or project install), there is nothing to reinstall. It logs `reticle_rollback_npx_strategy` with a note to pin the version in your MCP config (for example `@reticlehq/server@<version>` in `.mcp.json`), and does not exit. Pin the version there yourself.
+</Warning>
 
 Telemetry records the move as a `version_changed` event with `direction: "rollback"`, which is treated as a release-quality alarm rather than a routine version move.
 
@@ -22,14 +26,16 @@ Telemetry records the move as a `version_changed` event with `direction: "rollba
 
 | Code | Meaning                                                     |
 | ---- | ----------------------------------------------------------- |
-| `0`  | The previous version was restored (the process is replaced) |
+| `0`  | The previous version was reinstalled and the process exited |
 | `1`  | There was nothing to roll back to, or the restore threw     |
 
 ## Worked example
 
-```bash
-npx @reticlehq/server update
+On the global install the installer puts on your PATH (under `npx` there is nothing to roll back):
+
+```text
+reticle update
 # the new build misbehaves:
-npx @reticlehq/server rollback
-npx @reticlehq/server version
+reticle rollback
+reticle version
 ```

package/docs/cli/serve.mdx

@@ -16,10 +16,10 @@ Most people never type this. Your agent runs [`reticle mcp`](/cli/mcp), which st
 
 | Flag | Type | Default | What it does |
 | --- | --- | --- | --- |
-| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Bridge port to bind |
+| `--port N` | number | `RETICLE_PORT`, else the port in `.reticle.json`, else the daemon already serving this project, else `4400` | Bridge port to bind |
 | `--drive <url>` | string | unset | Launch Reticle's own browser at this URL instead of waiting for your tab |
-| `--headless` | boolean | `true` for `serve` | Hide the browser |
-| `--headed` | boolean | `false` | Show it. `serve` owns the pooled browser behind leases, which is batch work, so it hides by default |
+| `--headless` | boolean | on when `CI` or `RETICLE_HEADLESS` is set (and not `0` or `false`), or on Linux with no display | Hide the browser |
+| `--headed` | boolean | on otherwise | Show it, so you can watch the run |
 | `--http` | boolean | `false` | Also expose the HTTP verify endpoint |
 | `--http-port N` | number | unset (`7331`) | Port for that endpoint. Requires `--http`. |
 | `--http-token T` | string | unset | Bearer token the endpoint requires. Requires `--http`. |
@@ -34,7 +34,7 @@ One structured line. When a daemon already owns the port, it says so and does no
 { "t": "2026-08-15T18:43:33.065Z", "event": "reticle_daemon_already_running", "port": 4499 }
 ```
 
-A successful spawn logs `reticle_daemon_spawned` with the port:
+Once the spawned daemon answers, it logs `reticle_daemon_spawned` with the port:
 
 ```json
 { "t": "2026-08-15T18:43:32.604Z", "event": "reticle_daemon_spawned", "port": 4499 }

package/docs/cli/setup.mdx

@@ -0,0 +1,23 @@
+---
+title: reticle setup mcp
+description: Register the Reticle MCP server with every coding agent on this machine.
+icon: plug
+---
+
+`reticle setup mcp` registers the Reticle MCP server with the coding agents on this machine, so the `reticle_*` tools are there the next time each one starts. It is the registration half of the [installer](/quickstart), and you rarely need to run it yourself.
+
+```bash
+npx @reticlehq/server setup mcp
+```
+
+No flags, and nothing is asked. It works for your user account, not for one project, so it does not touch your app. To wire an app, run [`reticle init`](/cli/init).
+
+## What it prints
+
+One line per agent: `✓ <agent>` for a new registration, `✓ <agent> (already set up)` when Reticle was there already, `⚠ <agent>: Reticle registration failed…` when a registration failed (the command then exits `1`), and `⚠ <agent>: add the reticle entry to <path> by hand` for a config it will not rewrite. If it finds no agent, it names every agent it looked for.
+
+## How you know it worked
+
+Restart your coding agent. An agent reads its server list only when it starts. After the restart, the `reticle_*` tools are listed.
+
+Codex CLI keeps a TOML config that Reticle does not rewrite. When the `codex` binary is on your PATH, Reticle registers through `codex mcp add` instead; otherwise it prints the hand-edit line above.

package/docs/cli/status.mdx

@@ -1,10 +1,10 @@
 ---
 title: reticle status
-description: Ask whether the Reticle daemon is up and which app sessions have connected to it.
+description: Ask whether the Reticle daemon is up, which app sessions have connected, who is signed in, and whether this folder is linked.
 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.
+`reticle status` tells you whether the daemon is up and which pages connected, who you are signed in to Reticle Cloud as, and whether this folder is linked to a cloud project. The account facts come from local files; no network call is made. A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
 
 ```bash
 npx @reticlehq/server status [--port N] [--json]
@@ -19,6 +19,13 @@ npx @reticlehq/server status [--port N] [--json]
 
 ## What it prints
 
+The block also carries an account row: who you are signed in as and the cloud project this folder is linked to, or what to run (`reticle connect`) when it is not. `reticle whoami` is the old name for this question; it still works for one release.
+
+```text
+  account      ✓ signed in as Acme
+               this repo is not linked: run `reticle connect`
+```
+
 A short block, for whoever is reading the terminal. Real capture, daemon up with two apps connected:
 
 ```text
@@ -35,6 +42,7 @@ And with no daemon on the port:
 ```text
 reticle status
   daemon       ✗ not running on :4999
+               port presence: free
   agent link   never-attached
   next         no daemon is running on this port, which is normal. An agent starts it when it
                first calls a Reticle tool, and it exits again when idle. Ask your agent to verify
@@ -45,7 +53,11 @@ A session's parenthesised notes are the ones that explain an answer you would ot
 
 ### `--json`
 
-The same facts as one event line on stderr, for a caller that parses rather than reads:
+The same facts as one JSON line on stdout, so a caller can pipe it to a parser:
+
+```bash
+npx @reticlehq/server status --json | jq '.running, .sessionCount'
+```
 
 ```json
 {
@@ -67,6 +79,7 @@ It is one line in the terminal, pretty-printed here, with `why` trimmed at the e
   "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
   "url": "http://localhost:4310/",
   "throttled": false,
+  "hidden": false,
   "stale": false,
   "pendingMarks": 0
 }
@@ -75,9 +88,9 @@ It is one line in the terminal, pretty-printed here, with `why` trimmed at the e
 | 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 |
+| `presence` | Present when no usable daemon answered: `foreign` (something else holds the port) or `free`. 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` |
+| `sessionCount` / `sessions` | Connected app sessions, each with `sessionId`, `url`, `throttled`, `hidden`, `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 |
 

package/docs/cli/stop.mdx

@@ -1,21 +1,24 @@
 ---
 title: reticle stop
-description: Stop the Reticle daemon on a port, escalating from SIGTERM to SIGKILL if it will not go.
+description: Stop the Reticle daemon on a port, or free the port by its listener with --force, never touching the agent's MCP proxy.
 icon: circle-stop
 ---
 
-`reticle stop` reads the pid recorded for the port and stops that process.
+`reticle stop` reads the pid recorded for the port and stops that process. `reticle stop --force` asks **who is listening** on the port instead, and frees it.
 
 ```bash
-npx @reticlehq/server stop [--port N] [--quiet]
+npx @reticlehq/server stop [--port N] [--quiet] [--force]
 ```
 
+`reticle kill` is the old name for `stop --force`. It still works for one release and prints one line naming the new spelling.
+
 ## 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 |
+| `--force` | boolean | `false` | Find the process by the **listener** on the port, not by the recorded pid. See [Freeing the port](#freeing-the-port-force) |
 
 ## How it stops
 
@@ -28,7 +31,7 @@ npx @reticlehq/server stop [--port N] [--quiet]
 | 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_not_running` | No live pid for that port, and nothing answers `/status` on it. 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:
@@ -48,17 +51,73 @@ With `--quiet` that same run prints nothing at all and still exits `0`.
 
 <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).
+  own `reticle mcp` proxy as well as the daemon and takes both down. Use this command, or `reticle
+  stop --force`.
+</Warning>
+
+## Freeing the port: `--force`
+
+`stop` starts from the pid Reticle recorded. When that pid is dead or missing but a Reticle daemon still answers `/status` on the port (a stale pid file, or a daemon from another checkout), plain `stop` frees that listener the same way `--force` does. When nothing answers `/status`, plain `stop` reports `reticle_daemon_not_running`. `stop --force` always asks the **port** first, and is the command to reach for when the pid file and the port disagree.
+
+<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>
 
-## When this is not enough
+|  | `reticle stop` | `reticle stop --force` |
+| --- | --- | --- |
+| 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 | yes, when the daemon answers `/status` | yes |
+| Works on a daemon from another checkout | yes, when it answers `/status` | yes |
+| Works without `lsof` (Windows, slim containers) | yes | yes, falling back to the recorded pid and saying so |
+
+### How `--force` 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: it is someone else's process.
+4. `SIGTERM`, then `SIGKILL` after 5 seconds, then report that it survived and exit `1`.
+
+### What `--force` prints
+
+Real captures, taken against a daemon started on a scratch port. The long `note` and `reason` strings are trimmed at the ellipsis. Measured exit codes: `0` for killed and nothing-to-do, `1` for refused.
+
+Killed:
+
+```
+{"t":"2026-08-15T18:43:43.590Z","event":"reticle_killed","port":4499,"pid":78621,"escalated":false,"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 ..."}
+```
+
+Refused, because the listener is not ours. This one was captured with `python3 -m http.server 4498` holding the port:
+
+```
+{"t":"2026-08-15T18:43:57.128Z","event":"reticle_kill_refused","port":4498,"reason":"pid 78795 (\"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:
+
+```
+{"t":"2026-08-15T18:43:43.784Z","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` |
+| `reticle_kill_refused`       | The listener is not a Reticle daemon. 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.
 
-`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.
+With `--force`, exit `0` means the port is free and `1` means it is still held: refused, or the process survived `SIGKILL`.
 
 ## 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
+npx @reticlehq/server stop --force          # the port is held and the pid file says nothing
 ```

package/docs/cli/try.mdx

@@ -0,0 +1,62 @@
+---
+title: reticle try
+description: Sign in, then watch Reticle drive any URL once and say which journeys work.
+icon: play
+---
+
+`reticle try` is the fastest way to see Reticle on your own app. It drives a URL once with the Reticle Harness, in a browser window you can watch, and ends with a list of the journeys it tried and how each one ended.
+
+```bash
+npx @reticlehq/server try <url> [--persona <who>]
+```
+
+The app needs nothing installed. A page with no Reticle SDK gets one supplied for the drive, so verdicts cover the DOM, network, console and routes. There is no component state and no source `file:line` until you run [`reticle init`](/cli/init).
+
+## Sign in first
+
+The drive runs on the Reticle platform, so `try` needs a linked folder. On a machine that is not linked it drives nothing and says:
+
+```
+Sign in first: reticle connect (it is free, no card)
+```
+
+Run [`reticle connect`](/cli/cloud) in the folder, then run `try` again. It exits `1` in this case.
+
+## Arguments and flags
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `url` | string, positional, **required** | none | The page to drive. It must already be running |
+| `--persona <who>` | string | unset | Who to be, or what to get done ("a returning customer checking out"). Without it, the platform plans the journeys from what the page offers |
+
+## What happens
+
+1. `try` asks the platform for one free drive. If the workspace needs a card first, it prints the platform's message and the plan page, then exits `1` without opening anything.
+2. It opens the URL in a window you can watch, through the Reticle daemon, and starting one if none is running.
+3. The Harness drives for up to two minutes and 40 steps, and records what it drove as saved flows.
+4. It prints the result and sends the run to your dashboard, the same way [`reticle sync`](/cli/cloud#reticle-sync) does.
+
+## What it prints
+
+A `Driving <url>` line first, telling you to watch the window, then:
+
+```
+Tried 3 journeys: 1 work, 1 broken, 1 not proved
+  ✓ works: Shopper: checks out
+  ✗ broken: Shopper: applies a coupon
+  ? not proved (blocked): Admin: refunds
+See it in your dashboard: <the run's page>
+```
+
+There is one `See it in your dashboard` line per run. When the dashboard address is not known, a single `Saved to your dashboard: <url>` line takes their place.
+
+Each verdict comes from the engine. A journey that neither passed nor failed is reported as **not proved**. It is never counted as working.
+
+If the run could not be sent, `try` says so, keeps the run on this machine and tells you to run `reticle sync`. It never prints a dashboard line in that case.
+
+## Exit codes
+
+| Code | When                                                                       |
+| ---- | -------------------------------------------------------------------------- |
+| `0`  | The drive ran. Broken journeys are a finding, not a failure of the command |
+| `1`  | Not signed in, no free drive granted, or the drive could not run           |