diff --git a/PRODUCT.md b/PRODUCT.md
index db18c1f..499fcf6 100644
--- a/PRODUCT.md
+++ b/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.
diff --git a/README.md b/README.md
index 9d23c92..d687132 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,17 @@
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:
@@ -11,53 +21,28 @@ Run from a Git checkout:
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,10 +51,10 @@ 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`. |
@@ -77,10 +62,42 @@ Arguments:
| `--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
diff --git a/docs/content/agent-notes.mdx b/docs/content/agent-notes.mdx
index 99199e8..d9dc646 100644
--- a/docs/content/agent-notes.mdx
+++ b/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
diff --git a/docs/content/cli.mdx b/docs/content/cli.mdx
index 1c28ab7..7bf8262 100644
--- a/docs/content/cli.mdx
+++ b/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`,
diff --git a/docs/content/data.mdx b/docs/content/data.mdx
index cf1fc63..6cf0146 100644
--- a/docs/content/data.mdx
+++ b/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
diff --git a/docs/content/development.mdx b/docs/content/development.mdx
index a6b0714..3657da9 100644
--- a/docs/content/development.mdx
+++ b/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.
diff --git a/docs/content/index.mdx b/docs/content/index.mdx
index e9f6c36..257350e 100644
--- a/docs/content/index.mdx
+++ b/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
diff --git a/docs/content/mobile.mdx b/docs/content/mobile.mdx
index 6d55330..93eac26 100644
--- a/docs/content/mobile.mdx
+++ b/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
diff --git a/site/index.html b/site/index.html
index bc30be1..b1f27d7 100644
--- a/site/index.html
+++ b/site/index.html
@@ -12,7 +12,7 @@
@@ -107,7 +107,7 @@