docs: document optimize classes, provenance, and what --apply writes

Adds docs/optimize.md (what optimize scans, the three classes, the exact
files --apply may touch plus undo, measured vs estimated, the health
grade bands, the --yes CLAUDE.md guardrail), links it from the README
waste section, and corrects the detector count in docs/architecture.md
(14 -> 19).

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- **Optimize findings say what to do with them and where their number came from.** Every finding now carries a class and a basis, and every surface groups by it: `Fix now (apply-able)` for findings `codeburn optimize --apply` can write itself, `Habits` for the behavioural ones, `FYI` for informational ones whose cost may be justified. A finding only counts as apply-able when a plan can actually be built for that instance, so an `mcp-deferral-off` caused by Vertex policy or a shell-profile override is grouped as a habit rather than promising a fix that does not exist. Alongside it, each finding is marked `measured` (summed from provider-counted usage) or `estimated` (a schema-size or recovery-fraction model), with the split reported in the header as `N measured · M estimated` in place of the blanket "Estimates only." footer. Sessions whose cost the provider never reported are kept out of the `cost-outliers` peer comparison, and a provider that only ever estimates gets the finding marked `estimated` rather than dropped. `--format json` gains `class` and `basis` per finding plus `summary.measuredSavingsUSD` (existing fields unchanged), and the new `docs/optimize.md` covers what is scanned, exactly what `--apply` may write, and how to read the health grade.
+
 ### Added (CLI)
 - **DeepSeek Harness (`dsh`) is now a supported provider.** Reads DeepSeek's open-source agent harness from `~/.dsh/sessions` (`DSH_HOME` relocates the root), both the default zstd logs and the uncompressed `session.jsonl` variant. A `.zstd` log is a concatenation of independent zstd frames, one per write batch, so it is decoded frame by frame behind a structural frame scan and a torn trailing frame from a crashed writer is ignored rather than failing the file (needs Node 22.15+ for `zlib` zstd; below that dsh is skipped with a notice instead of counted as $0). One call per `(turn, step)`, with the step's final `assistant/message` usage superseding the streamed `assistant/chunk` sample of the same call rather than adding to it, the model taken from the message that served the step, and reasoning tokens billed at the output rate. DSH records tokens but no cost, so calls are priced from the shared tables. The events a forked session replays from its parent are skipped, since codeburn already counts the parent's own log. The session format is pinned at version 0 upstream with no compatibility implied, so a log stamped with any other version is skipped with a notice instead of read under today's assumptions.
 

README.md

@@ -167,6 +167,12 @@ codeburn optimize --format json         # setup health + findings as JSON
 - Possibly low-worth expensive sessions with no edit turns or repeated retries
   when no `git`/`gh` delivery command is observed
 
+Findings are grouped into three classes: **Fix now** (CodeBurn can apply it for you), **Habits**
+(you change how you drive the next session), and **FYI** (informational, the cost may be justified).
+Each one says whether its savings number is `measured` from provider-counted usage or `estimated`
+from a model. See [docs/optimize.md](docs/optimize.md) for what is scanned, what `--apply` may write,
+and how to read the health grade.
+
 Each finding shows the estimated token and dollar savings plus a ready-to-paste fix: a `CLAUDE.md` line, an environment variable, or a `mv` command to archive unused items. Findings are ranked by urgency (impact weighted against observed waste) and rolled up into an A to F setup health grade. Repeat runs classify each finding as new, improving, or resolved against a 48-hour recent window.
 
 You can also open it inline from the dashboard: press `o` when a finding count appears in the status bar, `b` to return.

docs/architecture.md

@@ -144,7 +144,7 @@ All three use atomic write (temp file + `rename`) and write with mode `0o600`. A
 
 ### Optimize Detectors
 
-`src/optimize.ts` exports 14 detectors. Each returns a `WasteFinding | null`. They are composed by `runOptimize()` which collects findings, ranks them by impact, and returns them with `WasteAction` objects (paste-to-CLAUDE.md, paste-to-session-opener, prompt-now, edit shell config).
+`src/optimize.ts` exports 19 detectors. Each returns a `WasteFinding | null`. They are composed by `runOptimize()` which collects findings, ranks them by impact, and returns them with `WasteAction` objects (paste-to-CLAUDE.md, paste-to-session-opener, prompt-now, edit shell config).
 
 | Detector | Line | What it catches |
 |---|---|---|

docs/optimize.md

@@ -0,0 +1,104 @@
+# optimize
+
+`codeburn optimize` scans your Claude Code sessions and your `~/.claude/` setup, reports what is
+costing tokens without earning them, and grades the setup A to F.
+
+## What it scans
+
+- **Session transcripts** for the selected period: tool calls, per-call token usage, turn retries,
+  per-session cost. This is where re-reads, junk directory reads, low read:edit ratios, warmup
+  overhead, retries, and expensive or context-heavy sessions come from.
+- **Your configuration**: `~/.claude.json`, user and project `settings.json` / `settings.local.json`,
+  `.mcp.json`, `CLAUDE.md` (including `@`-imports), and the `skills/`, `agents/`, `commands/`
+  directories. This is where unused MCP servers, MCP deferral gaps, ghost skills/agents/commands,
+  the bash output cap, and oversized `CLAUDE.md` files come from.
+
+Nothing is written during a scan. Only `--apply` writes.
+
+## The three classes
+
+Every finding carries a `class`, and both the CLI and the apps group by it:
+
+| Class | Header | Meaning |
+|---|---|---|
+| `fix` | Fix now (apply-able) | CodeBurn can make this change for you: `codeburn optimize --apply` |
+| `nudge` | Habits | Behavioural. Nothing to edit; the fix is how you drive the next session |
+| `keep` | FYI | Informational. The cost may well be justified; decide for yourself |
+
+A finding is `fix` only when a plan can actually be built for that instance. The same detector can
+report a `fix` in one run and a `nudge` in another: `mcp-deferral-off` is appliable when the cause is
+an `ENABLE_TOOL_SEARCH` override in a settings file, but manual when the cause is Vertex AI policy,
+an outdated Claude Code, or an override that lives in your shell profile.
+
+## What `--apply` may write
+
+`--apply` builds a plan per finding, shows you the exact files it will touch, and asks before
+writing. `--dry-run` prints the plan and stops.
+
+| Finding | File it edits |
+|---|---|
+| `unused-mcp`, `mcp-low-coverage` | `~/.claude.json`, project `.mcp.json` / `settings.json` (removes the server entry) |
+| `mcp-project-scope` | moves a global server entry into the keeper project's `.mcp.json` |
+| `mcp-deferral-off` | the settings file carrying the `ENABLE_TOOL_SEARCH` override |
+| `mcp-alwaysload-hygiene` | the config files carrying `"alwaysLoad": true` |
+| `mcp-defer-threshold` | the settings file carrying the `auto:N` threshold |
+| `unused-agents`, `unused-skills`, `unused-commands` | moves the files into `~/.claude/<kind>/.archived/` |
+| `bash-output-cap` | appends a marker block to `~/.zshrc` / `~/.bashrc` |
+| `read-edit-ratio`, `build-folder-reads` | appends a marker block to the current project's `CLAUDE.md` |
+
+Every write is backed up and journaled first:
+
+```bash
+codeburn act list             # every change CodeBurn has made
+codeburn act undo <id>        # restore the original files
+codeburn act undo --last
+```
+
+Undo refuses if a file changed after the apply, unless you pass `--force`.
+
+### The `--yes` CLAUDE.md guardrail
+
+`--apply --yes` skips the prompt for every plan except `CLAUDE.md` rule blocks. Those land in the
+`CLAUDE.md` of whatever directory you happen to be in, so a blanket `--yes` from an unrelated
+directory would write advice into the wrong project. To apply one anyway, use the interactive picker
+or name it explicitly:
+
+```bash
+codeburn optimize --apply --only read-edit-ratio
+```
+
+## measured vs estimated
+
+Each finding also carries a `basis`, printed next to its savings and summarised in the header as
+`N measured · M estimated`:
+
+- **measured** — the token number is summed from provider-counted usage on your own calls. Today
+  that is `context-heavy-sessions` and `cost-outliers`.
+- **estimated** — the token number comes from a model: a per-tool schema size, a per-line `CLAUDE.md`
+  cost, an average read size, a recovery fraction applied to real turn tokens. A detector that mixes
+  counted tokens with a model counts as estimated.
+
+Sessions whose cost the provider never reported (Kiro, Cursor, some Cline sessions price from
+modelled token counts) are kept out of the `cost-outliers` peer comparison, so a modelled cost is
+never called an outlier against provider-reported ones. When a provider only ever estimates, the
+comparison falls back to those sessions and the finding reports itself as `estimated`.
+
+In `--format json`, `summary.measuredSavingsUSD` is the share of `summary.potentialSavingsCostUSD`
+that comes from measured findings.
+
+## Reading the health grade
+
+Health starts at 100 and loses points per finding: 15 for a high-impact one, 7 for medium, 3 for low.
+The total penalty is capped at 80, so a long tail of small findings cannot sink the score to zero on
+its own. The grade is a band over that score:
+
+| Grade | Score |
+|---|---|
+| A | 90-100 |
+| B | 75-89 |
+| C | 55-74 |
+| D | 30-54 |
+| F | below 30 |
+
+The grade rates your setup, not your spending: an expensive month with a clean configuration still
+scores an A.