docs: align repository documentation with source

.changeset/jolly-pens-design.md

@@ -0,0 +1,2 @@
+---
+---

README.md

@@ -4,7 +4,7 @@
 
 **Review your git branch in a [cmux](https://cmux.com) browser split, with inline comments you can hand to an agent**
 
-Run one command inside any git repository and DiffHub serves a GitHub-style diff of your branch at `localhost:2047`.
+Run one command inside any git repository and DiffHub serves a GitHub-style diff of your working tree at `localhost:2047`.
 
 <p align="center">
   <a href="https://www.npmjs.com/package/diffhub">
@@ -55,7 +55,7 @@ diffhub cmux --base develop
 diffhub cmux --repo ~/Code/mblode/cmux
 ```
 
-DiffHub diffs your branch against the merge-base with the detected base branch, preferring `origin/main` so unpushed commits still show up. It watches the repository and refreshes as you work.
+The default view is `touched`: `HEAD` versus the working tree, including untracked files. Merge-base scopes (`all`, `committed`) are available from the status bar, and `--base` still selects the comparison branch, preferring `origin/main` so unpushed commits show up. A watcher marks updates available; press `r` to refresh. `diffhub cmux` uses a repo-derived port in 20000–29999 instead of 2047.
 
 ## Commands
 
@@ -85,17 +85,20 @@ DiffHub diffs your branch against the merge-base with the detected base branch,
 
 ## Keyboard shortcuts
 
-| Key       | Action                            |
-| --------- | --------------------------------- |
-| `j` / `k` | Next / previous file              |
-| `s`       | Toggle split / stacked view       |
-| `c`       | Collapse or expand the whole file |
-| `/`       | Focus the file filter             |
-| `r`       | Refresh the diff                  |
+| Key         | Action                                      |
+| ----------- | ------------------------------------------- |
+| `j` / `k`   | Next / previous file                        |
+| `s`         | Toggle split / stacked view                 |
+| `c`         | Collapse or expand the selected file        |
+| `Shift+C`   | Collapse all files                          |
+| `Shift+E`   | Expand all files                            |
+| `/` or `t`  | Focus the file filter                       |
+| `r`         | Refresh the diff                            |
+| `F2`        | Toggle the Diff stats panel                 |
 
 ## Notes
 
-- Node.js 20.11+ or Bun 1.0.23+, and a git repository with at least one commit on the current branch.
+- Node.js 20.11+ or Bun 1.0.23+, and a git repository (`git rev-parse --show-toplevel` must succeed).
 - cmux mode expects `cmux.app` installed on macOS at `/Applications/cmux.app`.
 - Comments live in `.git/diffhub-comments.json` in the repository you are reviewing, and copy out as a markdown review prompt for a coding agent.
 

apps/cli/AGENTS.md

@@ -55,8 +55,8 @@ Without it, `lib/git.ts` falls back to `process.cwd()` — the Next.js server di
 **Page-level repo resolution must use the same resolver as the server helpers.**
 `app/page.tsx`, `lib/git.ts`, and `lib/comments.ts` should all read the same configured repo path so localStorage keys, context-menu open actions, and comment storage stay aligned.
 
-**Whitespace filtering is wired through both diff routes.**
-`/api/diff` and `/api/files` both accept `ws=ignore`, and `DiffApp` is responsible for keeping the current whitespace mode in sync across file stats and the selected-file patch fetch.
+**Whitespace filtering is on the diff routes, not the UI.**
+`/api/diff` and `/api/files` both accept `ws=ignore` and pass `-w` to git. The status bar does not send that query param today.
 
 **`outputFileTracingRoot` must be the monorepo root, not the app directory.**
 `next.config.ts` sets `outputFileTracingRoot: join(import.meta.dirname, "../..")`. Using the app directory breaks module resolution for packages hoisted to the root `node_modules`. The monorepo root value causes the standalone server to land at `.next/standalone/apps/cli/server.js` — not a flat `server.js`.
@@ -75,7 +75,7 @@ The diff view targets Safari, which has no native `overflow-anchor` ([WebKit #17
 - API routes (`app/api/*/route.ts`) are server-only — no `"use client"` directive there
 - Icons come from `blode-icons-react`, not `lucide-react`
 - Comments are stored in `.git/diffhub-comments.json` (gitignored in the target repo, not this one)
-- Diff defaults to merge-base changes, with a UI toggle for uncommitted-only changes
+- Diff defaults to `touched` (`HEAD` vs working tree). Status-bar scopes are `all`, `committed`, `staged`, `unstaged`, and `touched`.
 - Base branch prefers `origin/main` over local `main` so unpushed commits are visible even when on main
 
 ## Available Context

apps/cli/README.md

@@ -4,7 +4,7 @@
 [![Node.js 20.11+](https://img.shields.io/badge/node-20.11+-green)](https://nodejs.org)
 [![Bun 1.0.23+](https://img.shields.io/badge/bun-1.0.23+-green)](https://bun.sh)
 
-Git diff viewer for cmux. Opens in a browser split and shows tracked changes relative to your merge-base by default, with a UI toggle for uncommitted-only changes, split/unified diff views, inline comments, and live auto-refresh.
+Git diff viewer for cmux. Opens in a browser split and shows `HEAD` versus the working tree by default (`touched`), with status-bar scopes for merge-base and staged/unstaged views, split/unified diffs, and inline comments. A watcher marks updates; refresh is manual (`r`).
 
 ## Install
 
@@ -26,7 +26,7 @@ Run inside any git repository:
 diffhub
 ```
 
-Opens `http://localhost:2047` and shows tracked changes relative to your branch merge-base (`main`, `master`, `develop`, or `dev`, auto-detected).
+Opens `http://localhost:2047` and shows `HEAD` versus the working tree. Use `--base` to pick the comparison branch (`main`, `master`, `develop`, or `dev`, auto-detected). Switch scopes in the status bar: `all`, `committed`, `staged`, `unstaged`, `touched`.
 
 ```bash
 # Use a different base branch
@@ -44,13 +44,12 @@ diffhub --no-open
 
 ## Features
 
-- **PR-style diff** — defaults to merge-base diffs and also supports an uncommitted-only mode from the UI
+- **Working-tree diff** — defaults to `touched` (`git diff HEAD` plus untracked); status bar switches `all` / `committed` / `staged` / `unstaged` / `touched`
 - **Split and unified views** — toggle with `s`, keyboard-navigable with `j` / `k`
-- **Whitespace filtering** — ignore whitespace-only changes from the top bar when reviewing formatting-heavy diffs
-- **Inline AI comments** — add `[must-fix]`, `[suggestion]`, `[nit]`, or `[question]` notes on any diff line; copy all comments as a formatted prompt
-- **"Open in" context menu** — right-click any file to open in Zed, VS Code, Ghostty, Terminal, Finder, or copy the path
-- **Live refresh** — watches local file changes and updates the diff automatically; force refresh with `r`
-- **File sidebar** — filter files with `/`, see per-file `+`/`-` stats at a glance
+- **Inline comments** — add `[must-fix]`, `[suggestion]`, `[nit]`, or `[question]` notes on any diff line; copy all comments as a formatted prompt
+- **Copy path** — file headers expose a copy-path control
+- **Manual refresh** — watches local file changes and marks updates available; press `r` or the status-bar refresh control
+- **File sidebar** — filter files with `/` or `t`, see per-file `+`/`-` stats at a glance
 
 ## Development notes
 
@@ -60,12 +59,16 @@ diffhub --no-open
 
 ## Keyboard shortcuts
 
-| Key       | Action                      |
-| --------- | --------------------------- |
-| `j` / `k` | Next / previous file        |
-| `s`       | Toggle split / unified view |
-| `/`       | Focus file filter           |
-| `r`       | Force refresh diff          |
+| Key         | Action                               |
+| ----------- | ------------------------------------ |
+| `j` / `k`   | Next / previous file                 |
+| `s`         | Toggle split / unified view          |
+| `c`         | Collapse or expand the selected file |
+| `Shift+C`   | Collapse all files                   |
+| `Shift+E`   | Expand all files                     |
+| `/` or `t`  | Focus file filter                    |
+| `r`         | Refresh the diff                     |
+| `F2`        | Toggle the Diff stats panel          |
 
 ## Options
 
@@ -79,7 +82,7 @@ diffhub --no-open
 ## Requirements
 
 - Node.js 20.11+ or Bun 1.0.23+
-- A git repository with at least one commit on your current branch
+- A git repository (`git rev-parse --show-toplevel` must succeed)
 
 ## License