Align documentation with current CLI behavior

PRODUCT.md

@@ -20,22 +20,25 @@ Diffsplain runs on a PR and pairs each unified diff with agent-written context a
 
 ## Operating Context
 
-Developers run `npx diffsplain` in a Git checkout. With no arguments, it compares the checkout with its default branch. They can also pass a repo path, URL, or `owner/name`, then choose a branch or pull request. Developers move through changed files, search the file list, and expand long patches when needed. The page updates when the diff or agent notes change.
+Developers run `npx diffsplain` in a Git checkout. With no target, it shows staged, unstaged, and untracked changes against `HEAD`. They can also pass a repo path, URL, or `owner/name`, then choose a branch or pull request. Developers move through changed files, search the file list, and expand long patches when needed. The page updates when the diff or agent notes change.
 
 ## Capabilities and Constraints
 
 - Show GitHub pull requests without changing the local checkout.
-- Compare the current checkout with its default branch when no target is passed.
+- Show staged, unstaged, and untracked changes against `HEAD` when no target is passed.
 - Accept local paths, Git URLs, and GitHub `owner/name` repo names.
 - Report local dependency paths, versions, and readiness with `diffsplain doctor`.
-- Try Codex, Claude, Copilot, Cursor, then OpenCode when no agent is chosen.
+- Use the explicit agent or configured default. With neither set, let an
+  interactive user choose from usable agents in this order: Codex, Claude,
+  Copilot, Cursor, then OpenCode. Non-interactive runs need a configured
+  default, `--agent NAME`, or `--no-agent`.
   Use Cursor when version 2026.08.11 or newer is installed. Run the signed-in
   Cursor CLI in the user's home, in non-interactive Ask mode, with `--trust`
   and `--workspace` pointed at the selected repo for local checkout access or
   at Diffsplain's temporary snapshot folder for snapshot-only access.
   Cursor still contacts its service. Once Diffsplain chooses an agent, do not
   switch agents after a failed check or run.
-- Show tracked and untracked worktree changes, exact local ranges, and remote branches as secondary targets.
+- Support worktree changes, a base through the working tree, exact local ranges, and remote branches.
 - Present full or shortened unified diffs, including binary-file metadata.
 - Pair the whole change and each file with agent-written summaries, reasons, details, and risks.
 - Keep local review read-only: the app must not change the target repo.

README.md

@@ -3,61 +3,46 @@
 Review a Git diff one file at a time, with a short coding agent note beside each
 patch.
 
-## Use
+## Prerequisites
+
+- Node.js 22.13 or newer and Git.
+- For agent notes: a signed-in Codex, Claude, Copilot, Cursor, or OpenCode CLI.
+  Cursor Agent requires version 2026.08.11 or newer.
+- For pull requests: a signed-in GitHub CLI (`gh auth login`).
+
+Check your setup with `npx diffsplain doctor`. See [Agent notes](docs/content/agent-notes.mdx)
+for provider access and login details.
+
+## Quick start
 
 Run from a Git checkout:
 
 ```sh
 npx diffsplain
 ```
 
-The command opens a local page showing staged, unstaged, and untracked changes
-against `HEAD`, the same as `--worktree`. It starts at port `2299` and uses the
-next free port when needed. You
-need Node.js 22.13 or newer and a signed-in Codex, Claude, Copilot, Cursor, or
-OpenCode CLI. Set a default with `diffsplain config agent NAME`, or choose one
-run with `--agent NAME`. If neither is set, an interactive terminal lists
-usable agents in that order and asks you to choose one. `--no-agent` always
-starts a plain review. Cursor Agent must be version 2026.08.11 or newer. It
-uses the signed-in Cursor CLI in the user's home and still contacts the Cursor
-service.
-Pull requests also need a signed-in GitHub CLI. Once Diffsplain chooses an
-agent, a failed check or run ends the command; it does not switch agents.
-
-Common targets:
+Choose an agent when prompted, or use `--no-agent` for a plain diff. The page
+shows staged, unstaged, and untracked changes against `HEAD` and updates as
+files change. It starts at port `2299`, using the next free port if needed.
+Press Ctrl-C to stop.
+
+Other targets:
 
 ```sh
 npx diffsplain --pr 198
 npx diffsplain owner/repo --branch feature/my-change
-npx diffsplain --worktree
 npx diffsplain --base BASE_REF
 npx diffsplain --base BASE_REF --head HEAD_REF
 ```
 
-Check Git, the GitHub CLI, and each supported coding agent:
-
-```sh
-npx diffsplain doctor
-```
-
-Show, set, or unset the default coding agent:
-
-```sh
-npx diffsplain config agent
-npx diffsplain config agent claude
-npx diffsplain config agent --unset
-```
-
-An explicit `--agent` overrides the configured default, and `--no-agent`
-overrides both. A damaged, unsupported, or unavailable configured agent stops
-the command instead of switching providers; use either explicit option as a
-recovery path. The two per-run options cannot be combined.
+## Full arguments
 
-Arguments:
+See the [CLI reference](docs/content/cli.mdx) for details.
 
 | Argument | Use |
 | --- | --- |
-| `doctor` | Show dependency paths, versions, and readiness. |
+| `doctor [--json] [--deep]` | Check local review, agent note, and pull request capabilities. |
+| `cache [status\|prune --age DAYS\|prune --size BYTES\|clear --yes]` | Inspect or remove inactive saved notes. |
 | `config agent [NAME\|--unset]` | Show, set, or unset the default coding agent. |
 | `REPO`, `--repo PATH\|URL\|OWNER/REPO` | Select a local or remote repo. |
 | `--pr NUMBER\|URL` | Review a GitHub pull request. |
@@ -66,21 +51,53 @@ Arguments:
 | `--base REF` | Compare that exact commit with the live working tree. |
 | `--base REF --head REF` | Review an exact local range. |
 | `--agent NAME`, `--no-agent` | Choose a coding agent, or show a plain diff. |
-| `--no-checkout-access` | Limit agent notes to the supplied snapshot. |
+| `--no-checkout-access` | Limit agent notes and Review chat to the supplied snapshot. |
 | `--exclude PATTERN` | Keep matching files out of automatic agent input. Repeat rules in gitignore order; the diff still shows them. |
 | `--model NAME` | Choose the model used for notes. |
-| `--reasoning LEVEL` | Set `minimal`, `low`, `medium`, `high`, or `xhigh`. |
+| `--reasoning LEVEL` | Set `minimal`, `low`, `medium`, `high`, or `xhigh` for Codex or OpenCode. |
 | `--fast` | Enable provider Fast mode for agent notes and Review chat. |
 | `--batch-size COUNT` | Set the most files per agent pass. The default is `12`; large patches use smaller batches. |
 | `--jobs COUNT` | Set agent passes to run at once. The default is `3`. |
 | `--force` | Regenerate all agent notes instead of using cached notes. |
 | `--support-record` | Print a safe JSON record if the review fails. |
 | `--support-record-file FILE` | Write one safe JSON record if the review fails. |
 | `--remote NAME\|URL` | Choose the Git remote. The default is `origin`. |
-| `--port NUMBER` | Choose an exact local port. The default starts at `2299`. |
+| `--summaries FILE` | Choose the saved agent-note file. |
+| `--output FILE` | Choose a live snapshot file that remains after shutdown. |
+| `--cache-dir PATH` | Choose the bare Git cache folder. |
+| `--codex-bin PATH` | Choose the Codex executable. |
+| `--port NUMBER` | Choose a port; `0` asks the OS for a free port. The default starts at `2299`. |
+| `--host ADDRESS` | Choose the page bind address. The default is `localhost`. |
+| `--no-browser` | Print the page URL without opening a browser. |
 | `-h`, `--help` | Show command help. |
 | `-v`, `--version` | Show the installed version. |
 
+### Default agent
+
+```sh
+npx diffsplain config agent          # Show the default
+npx diffsplain config agent claude   # Set it
+npx diffsplain config agent --unset  # Remove it
+```
+
+Use `--agent NAME` to override the default or `--no-agent` for a plain diff;
+the two flags cannot be combined. Without a choice, an interactive terminal
+asks you to pick a usable agent. Scripts need a default or one of these flags.
+A failed agent check or run stops the command; Diffsplain does not switch
+agents.
+
+### Saved notes
+
+```sh
+npx diffsplain cache status
+npx diffsplain cache prune --age 30
+npx diffsplain cache prune --size 104857600
+npx diffsplain cache clear --yes
+```
+
+Cleanup keeps notes in active use. These commands manage the default note
+cache, not the bare Git cache selected by `--cache-dir`.
+
 ## Local development
 
 ```sh

docs/content/agent-notes.mdx

@@ -103,6 +103,18 @@ page. A missing or old token cannot read or change its threads. Review-wide
 questions respect `--exclude` rules. A direct question about an excluded file
 may include that file, but this does not change the rules for review-wide chat.
 
+## Agent usage
+
+Open **Agent usage** on the review page to see separate totals for notes and
+chat, plus their combined use. Counts cover provider-reported input, output,
+cache reads, and cache writes for this review. They do not show prices or your
+account-wide history.
+
+**Partial** means some calls did not report use; **Unavailable** means none
+did. Missing reports do not mean zero tokens. A review that makes no agent
+calls reports zero input and output tokens. Reusing saved notes does not add
+the tokens spent creating them in an earlier run.
+
 ## Exclude files from automatic notes
 
 `--exclude PATTERN` controls prepared agent context. Repeat gitignore-style
@@ -144,8 +156,10 @@ pnpm run summarize -- --repo /path/to/repo --pr 198
 ```
 
 The same command accepts branch, worktree, checkout, and exact-range targets.
-The command reuses complete notes for files whose patches have not changed.
-Pass `--force` to replace every note:
+The command reuses complete notes when the file patches, agent, model,
+reasoning, and access mode still match. Changing those settings starts a new
+pass even when the patches stay the same. Pass `--force` to replace every
+non-excluded note:
 
 ```sh
 pnpm run summarize -- --repo /path/to/repo --pr 198 --force
@@ -195,6 +209,12 @@ npx diffsplain cache prune --size 104857600
 npx diffsplain cache clear --yes
 ```
 
+These commands manage the default note cache, not fetched Git objects or
+custom `--summaries` files outside that cache. `--cache-dir` selects the bare
+Git cache and does not change the note cache.
+
+## Note file format
+
 The file has one change note and notes keyed by file path:
 
 ```json

docs/content/cli.mdx

@@ -137,7 +137,7 @@ temporary review input and must use only that input; it must not run commands
 or read other files.
 
 Pass `--no-checkout-access` to use `snapshot-only` access for any target. This
-option affects agent notes only. It does not change the diff or the page.
+option limits both agent notes and Review chat. It does not change the diff.
 
 ## Exclude files from agent context
 
@@ -192,6 +192,30 @@ The normal check does not send prompts to a provider. `--deep` runs local
 `--help` checks for installed providers after a warning; it does not send a
 provider prompt.
 
+## Saved note cache
+
+Inspect the default note cache, or remove inactive notes:
+
+```sh
+npx diffsplain cache
+npx diffsplain cache status
+npx diffsplain cache prune --age 30
+npx diffsplain cache prune --size 104857600
+npx diffsplain cache clear --yes
+```
+
+`cache` and `cache status` show the cache location, byte count, oldest entry,
+and active targets. `prune --age DAYS` removes notes older than that many days.
+`prune --size BYTES` removes the oldest notes first until the cache fits the
+limit or only active notes remain. Pass one limit at a time; both accept
+non-negative numbers. `clear` requires `--yes`. All cleanup keeps notes under
+an active lease.
+
+These commands manage the default user note cache. They do not remove fetched
+Git objects or custom `--summaries` files outside that cache. `--cache-dir`
+chooses the bare Git cache for reviews, not the note cache. See
+[Agent notes](/agent-notes/#cache-control) for storage details.
+
 ## First run and shutdown
 
 Run the setup check through `npx`, which installs the package if needed:
@@ -230,7 +254,8 @@ pnpm run doctor
 
 | Argument | Use |
 | --- | --- |
-| `doctor` | Show dependency paths, versions, and readiness. |
+| `doctor [--json] [--deep]` | Check local review, agent note, and pull request capabilities. |
+| `cache [status\|prune --age DAYS\|prune --size BYTES\|clear --yes]` | Inspect or remove inactive saved notes. |
 | `config agent [NAME\|--unset]` | Show, set, or unset the default coding agent. |
 | `REPO`, `--repo PATH\|URL\|OWNER/REPO` | Select a local path, Git URL, or GitHub repo. |
 | `--pr NUMBER\|URL` | Review a GitHub pull request. |
@@ -240,7 +265,7 @@ pnpm run doctor
 | `--base REF --head REF` | Review an exact local range. |
 | `--agent NAME` | Use `codex`, `claude`, `copilot`, `cursor`, or `opencode`. |
 | `--no-agent` | Show the diff without agent notes. |
-| `--no-checkout-access` | Limit agent notes to the supplied snapshot. |
+| `--no-checkout-access` | Limit agent notes and Review chat to the supplied snapshot. |
 | `--exclude PATTERN` | Keep matching files out of automatic agent input. Repeat in gitignore order. |
 | `--model NAME` | Choose the model used for notes. |
 | `--reasoning LEVEL` | Set `minimal`, `low`, `medium`, `high`, or `xhigh`. |
@@ -261,7 +286,8 @@ pnpm run doctor
 | `-h`, `--help` | Show command help. |
 | `-v`, `--version` | Show the installed version. |
 
-Remote repos need `--branch` or `--pr`. You cannot combine two target options.
+Remote repos need `--branch` or `--pr`. `--pr` cannot use `--branch`, `--base`,
+or `--head`. `--branch` can use `--base`, but not `--head`.
 `--head` requires `--base`. Without `--head`, local `--base` compares that
 exact commit with the live working tree; a branch can also use `--base` as its
 remote base. `--worktree` cannot use another target. `--no-agent` cannot use
@@ -282,7 +308,10 @@ entitlement errors come from the provider.
 `--batch-size` defaults to `12` and accepts `1` through `50`. `--jobs` defaults
 to `3` and accepts `1` through `8`. `--port` accepts `0` through `65535`. When
 you omit it, Diffsplain starts at `2299` and increments until it finds a free
-port. When you omit `--agent` and have no configured default in an interactive
+port. An explicit occupied port stops the command; `--port 0` asks the OS for
+a free port.
+
+When you omit `--agent` and have no configured default in an interactive
 terminal, Diffsplain lists the usable choices in this order: Codex, Claude,
 Copilot, Cursor, then OpenCode. Choose one before the review starts. In a
 script or other non-interactive run, configure a default, pass `--agent NAME`,

docs/content/data.mdx

@@ -69,6 +69,15 @@ screen while the page reconnects.
 
 In watch mode, remote pull requests and branches update every 30 seconds.
 
+## Agent usage
+
+The served snapshot includes `usage.agentNotes`, `usage.reviewChat`, and
+`usage.combined`. Each reports its call count and whether token counts are
+complete, partial, or unavailable. Counts cover provider-reported input,
+output, cache reads, and cache writes for the current review. They do not
+include account-wide history or the past work that produced cached notes.
+See [Agent usage](/agent-notes/#agent-usage).
+
 ## Chat state and refresh
 
 When a review has a selected coding agent, the local server also keeps its

docs/content/development.mdx

@@ -166,8 +166,10 @@ corepack pnpm run cloud:check
 `cloud:check` runs the clean-checkout gate and the provider/browser tests.
 Those tests use fake coding providers and a fake browser command. Real Codex,
 Claude, Copilot, Cursor, OpenCode, GitHub, or browser login is optional and is
-needed only for a live integration task. Diffsplain tries Codex, Claude,
-Copilot, Cursor, then OpenCode for notes. Cursor Agent 2026.08.11 or newer uses
+needed only for a live integration task. Without a configured default or
+`--agent`, an interactive terminal lists usable agents in this order: Codex,
+Claude, Copilot, Cursor, then OpenCode. You choose one. Non-interactive runs need a configured default,
+`--agent NAME`, or `--no-agent`. Cursor Agent 2026.08.11 or newer uses
 the signed-in Cursor CLI in the user's home. It still contacts the Cursor
 service. Keep credentials in Codex environment settings, not checked-in rules
 or scripts.

docs/content/index.mdx

@@ -11,11 +11,15 @@ patch on the left and a short coding agent note on the right.
 
 ## Start a review
 
-You need Node.js 22.13 or newer and a signed-in Codex, Claude, Copilot, Cursor,
-or OpenCode CLI. Diffsplain tries Codex, Claude, Copilot, Cursor, then OpenCode
-when you do not choose one. Cursor Agent must be version 2026.08.11 or newer.
-It uses the signed-in Cursor CLI in the user's home. Cursor still contacts its
-service.
+You need Node.js 22.13 or newer and Git. For agent notes, you also need a
+signed-in coding agent CLI. Set a default with `diffsplain config agent NAME`
+or choose one run with `--agent NAME`. With neither set, an interactive
+terminal lists usable agents in this order: Codex, Claude, Copilot, Cursor,
+then OpenCode. You choose one; Diffsplain does not switch agents if it fails.
+In scripts, set a default, pass `--agent NAME`, or use `--no-agent` for a plain review.
+
+Cursor Agent must be version 2026.08.11 or newer. It uses the signed-in Cursor
+CLI in the user's home. Cursor still contacts its service.
 
 ```sh
 npx diffsplain

docs/content/mobile.mdx

@@ -126,9 +126,12 @@ Use `http://localhost:2299` in an iOS Simulator. On Android Emulator, use
 Do not expose a real review through a public tunnel: its diff data may contain
 private source code.
 
-The packaged `npx diffsplain` server binds to `localhost`. It is for the
-computer that starts the review, not for direct phone review. That boundary
-keeps the local review local.
+The packaged `npx diffsplain` server binds to `localhost` by default. For a
+phone on the same trusted network, use `--host 0.0.0.0 --no-browser`, then
+replace the host in the printed URL with the computer’s LAN address. Keep the
+port and access token in the URL. Anyone with that token and network access
+can read the review and use its chat, so share it only with trusted reviewers
+and stop the server when done.
 
 For cloud browser checks, use BrowserStack Local or an equivalent private
 tunnel with a non-sensitive fixture. Test current Chrome on Android and Safari