@vimoxshah/tokenflow 1.1.2 → 1.2.0

package/design/tokens.yaml

@@ -0,0 +1,330 @@
+# TokenFlow design tokens — the single source every surface compiles from.
+#
+#   npm run design          compile → src/ui/styles.css (generated block),
+#                                     site/styles.css   (generated block),
+#                                     menubar/TokenFlow/DesignTokens.swift
+#   npm run design:check    compile in memory, diff against the files, run gates
+#
+# Roles, not values: --plane / --text-muted / --accent stay true when a skin
+# flips mode. Hex values are quoted because `#` starts a YAML comment.
+# Doctrine and the reasoning behind every rule: docs/design-system.md.
+
+version: 1
+name: tokenflow
+
+# ------------------------------------------------------------------ fonts ---
+# The dashboard and the menu bar stay on the platform's own faces: they ship
+# optical sizing and tracking tables, and the offline snapshot must open from
+# file:// with nothing to fetch. The landing page self-hosts its faces (below).
+fonts:
+  sans: "system-ui, -apple-system, 'Segoe UI', sans-serif"
+  mono: "ui-monospace, SFMono-Regular, 'SF Mono', Menlo, monospace"
+  serif: "'Iowan Old Style', 'Palatino Linotype', Palatino, 'Book Antiqua', Georgia, serif"
+
+# ------------------------------------------------------------------- type ---
+# Size-specific tracking and leading: large text tightens, small text opens.
+# One letter-spacing for every size is wrong somewhere.
+type:
+  micro:
+    size: 10.5
+    tracking: ".02em"
+    leading: 1.3
+  label:
+    size: 11.5
+    tracking: ".012em"
+    leading: 1.35
+  caption:
+    size: 12.5
+    tracking: ".004em"
+    leading: 1.4
+  body:
+    size: 13.5
+    tracking: "0"
+    leading: 1.45
+  title:
+    size: 15
+    tracking: "-.006em"
+    leading: 1.3
+  figure:
+    size: 25
+    tracking: "-.015em"
+    leading: 1.12
+  hero:
+    size: 42
+    tracking: "-.025em"
+    leading: 1.05
+  display:
+    size: 60
+    tracking: "-.03em"
+    leading: 1.0
+
+# ------------------------------------------------------------------ space ---
+# A 4-pt scale with the two half-steps the dense layouts actually use.
+space: [2, 4, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 56, 72]
+
+radius:
+  xs: 5
+  sm: 8
+  md: 12
+  lg: 16
+  pill: 999
+
+# ----------------------------------------------------------------- motion ---
+# Two tiers. `ui` governs the dashboard and menu bar: nothing over 300ms, press
+# feedback instant, no animation on keyboard-initiated actions. `narrative`
+# governs the landing page and other reading surfaces, where a reveal may take
+# a beat. Under prefers-reduced-motion every primitive degrades to an instant,
+# complete state — never to a half-state.
+motion:
+  ui:
+    press: 120ms
+    fast: 160ms
+    base: 220ms
+    slow: 300ms
+    ease-out: "cubic-bezier(.23, 1, .32, 1)"
+    ease-in-out: "cubic-bezier(.77, 0, .175, 1)"
+    ease-drawer: "cubic-bezier(.32, .72, 0, 1)"
+    stagger: 40ms
+    stagger-max: 6
+  narrative:
+    fast: 180ms
+    base: 320ms
+    slow: 700ms
+    ease: "cubic-bezier(.2, .7, .3, 1)"
+    ease-out: "cubic-bezier(.16, 1, .3, 1)"
+    stagger: 85ms
+    stagger-max: 7
+
+# ----------------------------------------------------------------- status ---
+# Reserved for state. Never a series colour, never themed, always paired with
+# an icon or a word. Values are the dataviz reference status palette.
+status:
+  good: "#0ca30c"
+  warning: "#fab219"
+  serious: "#ec835a"
+  critical: "#d03b3b"
+  # On light surfaces `warning` sits near series-4 (yellow) and `critical` near
+  # series-8 (red). Status is never drawn as a chart mark and always travels
+  # with an icon or a word, so the two can share a hue family without one
+  # impersonating the other. The compiler reports these as warnings, not passes.
+  relief:
+    light: [warning, critical]
+
+# ----------------------------------------------------------------- charts ---
+# Authored ramps, never derived. The categorical steps belong to the MODE, not
+# the skin, and were validated against every skin's chart surface, so a skin
+# restyles the room and never the data. Fixed order, assigned by entity: a
+# filter that removes a series must not repaint the survivors. Past eight,
+# fold into "Other".
+series:
+  dark:  ["#3987e5", "#d95926", "#199e70", "#c98500", "#d55181", "#008300", "#9085e9", "#e66767"]
+  light: ["#2a78d6", "#eb6834", "#1baf7a", "#eda100", "#e87ba4", "#008300", "#4a3aa7", "#e34948"]
+  # Slots documented under 3:1 on light chart surfaces. The relief ships with
+  # every chart: a table twin and direct labels, so colour never carries the
+  # value alone. The compiler warns on these instead of failing.
+  relief:
+    light: [3, 4, 5]
+
+# One hue, light → dark, for magnitude.
+sequential:
+  dark:  ["#184f95", "#1c5cab", "#256abf", "#2a78d6", "#3987e5", "#5598e7", "#86b6ef"]
+  light: ["#cde2fb", "#9ec5f4", "#6da7ec", "#3987e5", "#2a78d6", "#1c5cab", "#104281"]
+
+# Two hues and a neutral grey midpoint, for polarity (period compare, vs-median).
+# Never a hue at the midpoint.
+diverging:
+  dark:  ["#d95926", "#e39a78", "#6b7385", "#7fb0f0", "#3987e5"]
+  light: ["#eb6834", "#f2b28f", "#9aa2b3", "#8dbaf0", "#2a78d6"]
+
+# ------------------------------------------------------------------ skins ---
+# A skin restyles the room: surfaces, ink, borders, accent, density, the faces
+# used for headings and figures. It never touches the series steps above.
+# Hierarchy is carried by lightness, never by hue; the accent is an accent.
+skins:
+  aurora:
+    label: Aurora
+    note: "Indigo-slate, layered, luminous"
+    default: true
+    display: sans
+    figure: sans
+    density:
+      radius: 14
+      radius-sm: 9
+      pad-card: "14px 16px"
+      gap-grid: 14px
+      fig-scale: 1
+      sec-space: 26px
+      tracking-h: "-0.015em"
+    dark:
+      plane: "#0a0d14"
+      surface-1: "#111624"
+      surface-2: "#171d2e"
+      surface-3: "#1f2637"
+      text-primary: "#f3f6fc"
+      text-secondary: "#a7b2c9"
+      text-muted: "#7d879e"
+      grid: "#1e2436"
+      axis: "#2b3348"
+      border: "rgba(154, 172, 255, 0.11)"
+      border-strong: "rgba(154, 172, 255, 0.20)"
+      hairline: "rgba(154, 172, 255, 0.066)"
+      accent: "#8f9dff"
+      accent-solid: "#4a5ae0"
+      accent-ink: "#ffffff"
+      shadow: "0 1px 2px rgba(0, 0, 0, .45), 0 14px 40px rgba(4, 8, 20, .45)"
+      glow: "radial-gradient(1100px 460px at 8% -10%, rgba(94, 114, 255, .17), transparent 62%), radial-gradient(820px 420px at 92% -14%, rgba(25, 158, 112, .11), transparent 60%)"
+      hero-glow: "radial-gradient(460px 220px at 8% 0%, rgba(94, 114, 255, .22), transparent 72%)"
+    light:
+      plane: "#f5f7fc"
+      surface-1: "#ffffff"
+      surface-2: "#f1f4fa"
+      surface-3: "#e6eaf4"
+      text-primary: "#0d1220"
+      text-secondary: "#4b5468"
+      text-muted: "#6c7488"
+      grid: "#e4e8f1"
+      axis: "#c7cddb"
+      border: "rgba(13, 18, 32, 0.09)"
+      border-strong: "rgba(13, 18, 32, 0.17)"
+      hairline: "rgba(13, 18, 32, 0.054)"
+      accent: "#3d4dd6"
+      accent-solid: "#3d4dd6"
+      accent-ink: "#ffffff"
+      shadow: "0 1px 2px rgba(16, 24, 48, .06), 0 12px 32px rgba(16, 24, 48, .08)"
+      glow: "radial-gradient(1100px 460px at 8% -10%, rgba(94, 114, 255, .10), transparent 62%)"
+      hero-glow: "radial-gradient(420px 180px at 12% 0%, rgba(94, 114, 255, .09), transparent 70%)"
+
+  terminal:
+    label: Terminal
+    note: "Near-black, hairlines, mono"
+    display: mono
+    figure: mono
+    density:
+      radius: 5
+      radius-sm: 4
+      pad-card: "11px 13px"
+      gap-grid: 9px
+      fig-scale: 0.94
+      sec-space: 20px
+      tracking-h: "0.01em"
+    dark:
+      plane: "#06070a"
+      surface-1: "#0c0e13"
+      surface-2: "#11141a"
+      surface-3: "#171b22"
+      text-primary: "#eef2f6"
+      text-secondary: "#9aa4ad"
+      text-muted: "#737b85"
+      grid: "#171b22"
+      axis: "#262c34"
+      border: "rgba(255, 255, 255, 0.09)"
+      border-strong: "rgba(255, 255, 255, 0.16)"
+      hairline: "rgba(255, 255, 255, 0.054)"
+      accent: "#24d67e"
+      accent-solid: "#24d67e"
+      accent-ink: "#04140b"
+      shadow: "0 0 0 1px rgba(255, 255, 255, .05), 0 10px 26px rgba(0, 0, 0, .55)"
+      glow: "none"
+      hero-glow: "none"
+    light:
+      plane: "#f7f8f9"
+      surface-1: "#ffffff"
+      surface-2: "#f2f4f5"
+      surface-3: "#e8eaec"
+      text-primary: "#0a0c0f"
+      text-secondary: "#494f57"
+      text-muted: "#666d75"
+      grid: "#e8eaec"
+      axis: "#c9cdd2"
+      border: "rgba(10, 12, 15, 0.10)"
+      border-strong: "rgba(10, 12, 15, 0.18)"
+      hairline: "rgba(10, 12, 15, 0.06)"
+      accent: "#0b6b3d"
+      accent-solid: "#0b6b3d"
+      accent-ink: "#ffffff"
+      shadow: "0 0 0 1px rgba(10, 12, 15, .05), 0 8px 20px rgba(10, 12, 15, .07)"
+      glow: "none"
+      hero-glow: "none"
+
+  editorial:
+    label: Editorial
+    note: "Warm charcoal, serif figures"
+    display: serif
+    figure: serif
+    density:
+      radius: 8
+      radius-sm: 6
+      pad-card: "20px 22px"
+      gap-grid: 18px
+      fig-scale: 1.12
+      sec-space: 38px
+      tracking-h: "-0.005em"
+    dark:
+      plane: "#16130c"
+      surface-1: "#201c13"
+      surface-2: "#282318"
+      surface-3: "#322b1f"
+      text-primary: "#f8f4ec"
+      text-secondary: "#c4bcab"
+      text-muted: "#998f7d"
+      grid: "#262218"
+      axis: "#3a3529"
+      border: "rgba(255, 240, 214, 0.10)"
+      border-strong: "rgba(255, 240, 214, 0.18)"
+      hairline: "rgba(255, 240, 214, 0.06)"
+      accent: "#e0a852"
+      accent-solid: "#e0a852"
+      accent-ink: "#1a1409"
+      shadow: "0 1px 2px rgba(0, 0, 0, .4), 0 12px 34px rgba(20, 14, 4, .38)"
+      glow: "radial-gradient(900px 420px at 88% -12%, rgba(224, 168, 82, .11), transparent 60%)"
+      hero-glow: "none"
+    light:
+      plane: "#f9f6ef"
+      surface-1: "#fffdf8"
+      surface-2: "#f4f0e6"
+      surface-3: "#eae5d8"
+      text-primary: "#1a1712"
+      text-secondary: "#544e42"
+      text-muted: "#736c60"
+      grid: "#e8e2d4"
+      axis: "#cbc4b2"
+      border: "rgba(26, 23, 18, 0.10)"
+      border-strong: "rgba(26, 23, 18, 0.18)"
+      hairline: "rgba(26, 23, 18, 0.06)"
+      accent: "#8a5514"
+      accent-solid: "#8a5514"
+      accent-ink: "#ffffff"
+      shadow: "0 1px 2px rgba(60, 45, 20, .06), 0 12px 30px rgba(60, 45, 20, .08)"
+      glow: "radial-gradient(900px 420px at 88% -12%, rgba(224, 168, 82, .13), transparent 60%)"
+      hero-glow: "none"
+
+# ---------------------------------------------------------------- landing ---
+# The landing page is a single-world dark surface in the Aurora room, with the
+# instrument-panel voice of design-kit's `house-plex` pairing: a geometric
+# grotesque for display, IBM Plex Sans for body, and the same tabular Plex Mono
+# the receipts use for figures. A sans display is the default for a developer
+# tool; a serif would need a brand reason this product does not have. Faces are
+# self-hosted under site/fonts/ (OFL-1.1, copied from the design-kit cache); a
+# product that promises nothing leaves your machine does not load fonts from a
+# third party.
+landing:
+  world: aurora
+  mode: dark
+  pairing: house-plex
+  fonts:
+    display:
+      family: Space Grotesk
+      file: space-grotesk
+      weights: [500, 600, 700]
+      fallback: sans
+      tracking: "-.018em"
+    body:
+      family: IBM Plex Sans
+      file: ibm-plex-sans
+      weights: [400, 500, 600]
+      fallback: sans
+    mono:
+      family: IBM Plex Mono
+      file: ibm-plex-mono
+      weights: [400, 500, 600]
+      fallback: mono

package/docs/architecture.md

@@ -180,8 +180,9 @@ Every chart ships a **table twin** toggled per card, so no value is reachable on
 
 ## Privacy by construction
 
-There is no HTTP client anywhere in this codebase — not for telemetry, not for pricing, not for
-updates. The server binds to loopback and refuses non-GET requests from a foreign origin without a
+The product makes no network call on its own. The only outbound HTTP is the opt-in
+`tokenflow sync --to`, which posts your two sync files to a team server you run, and the GitHub
+Action, which runs in CI. Nothing for telemetry, pricing, or updates. The server binds to loopback and refuses non-GET requests from a foreign origin without a
 token. Adapters read token counts and metadata and discard content; the schema has nowhere to put
 a prompt. SQLite sources are read from a temp snapshot so a live editor is never disturbed.
 
@@ -189,5 +190,5 @@ a prompt. SQLite sources are read from a temp snapshot so a live editor is never
 
 `user`, `machine`, `session_id`, `project` and `repository` are first-class, and the cube is
 additive — so cubes from several machines can be merged by concatenating rows and re-summing
-duplicated dimension tuples. V1 ships no identity, auth or sync, deliberately. Nothing here makes
-them impossible to add.
+duplicated dimension tuples. Identity stays opt-in per person. Sync is file-based, or to a server you run
+(`tokenflow team serve`) behind a shared token. No hosted service holds anyone's usage.

package/docs/cli.md

@@ -142,6 +142,143 @@ tokenflow digest --out week.md        # write instead of print
 
 ---
 
+### `receipt`
+What a branch or pull request cost. Spend is attributed per turn to the branch checked out when
+the turn ran, so a long session that moves across branches is split across them. Repositories are
+identified by walking up from each recorded working directory to `.git` and following a worktree's
+`gitdir:` pointer back to the main checkout — every `.worktrees/<x>` counts as the repo it belongs
+to. With `--gh`, merged pull requests are fetched through the GitHub CLI and joined by head branch;
+each matched receipt then carries `+/−` lines and cost per 100 changed lines.
+
+Each receipt also splits the estimate into **context** dollars (cache reads + writes: the cost of
+re-sending the conversation so far) and **work** dollars (fresh input + output). Context is the
+cheap path per token — a high share is not waste, it is where the lever is.
+
+```bash
+tokenflow receipt                              # every repo, top branches by spend
+tokenflow receipt --repo ~/code/api --gh       # one repo, joined to its merged PRs
+tokenflow receipt --repo api --branch feat/x   # one branch as a PR-comment receipt
+tokenflow receipt --repo ~/code/api --gh --pr 478 --md
+tokenflow receipt --prs prs.json               # PR list you exported yourself:
+   # gh pr list --state merged --json number,headRefName,additions,deletions,title,mergedAt
+tokenflow receipt --sessions                   # where the money goes across sessions
+tokenflow receipt --sessions --cap 25,100,500  # dollars above each candidate per-session cap
+tokenflow receipt --from 2026-06-01 --top 30 --automated '^release/'   # flag automated PRs
+tokenflow receipt --json                       # everything, machine-readable
+tokenflow receipt --csv > receipts.csv          # one row per branch, every repository
+tokenflow receipt --branch feat/x --svg r.svg --png r.png   # a shareable receipt card
+```
+
+A merged PR owns the turns on its branch **up to the merge**, including work done before the PR
+was opened (that work is how the PR came to exist). Turns *after* the merge are follow-up on a
+checkout that kept the old branch name; they appear beside the receipt as "After the merge, same
+branch" and are never counted inside it. A branch with several merged PRs attributes each turn to
+the PR it shipped in. Long-lived branches (`main`, `staging`, …) are flagged: a receipt there is
+for a period of work, not one change. A branch name that is deleted and reused inherits the
+earlier branch's pre-merge turns under this rule; give reused names a suffix if that matters.
+
+Sessions on a detached `HEAD` or with no branch recorded are reported as *unattributed*, never
+guessed. Unpriced turns are counted and excluded from the total, never shown as `$0`.
+`--sessions` labels its cap table as an upper bound: the dollars above a cap are what a guard could
+have held back at most, not a saving.
+
+`--csv` writes one row per branch (`repo, branch, costUsd, contextShare, sessions, turns,
+subagentTurns, first, last, longLived, prNumber, mergedAt, changedLines, costPer100Lines`) across
+every repository the plain-text table would show; combine with `--repo` to scope it to one. `--svg`
+writes a shareable card built from a single branch or PR receipt (`--branch` or `--pr`); add `--png`
+to also render a PNG through a local Chromium/Chrome (the SVG is still written if none is found).
+Every colour on the card comes from `design/tokens.yaml`, so it matches the configured skin and
+mode. See [exports-and-budgets.md](exports-and-budgets.md).
+
+### `week`
+"Your AI week": spend this calendar week (Monday through today) against last week, context share,
+turns, sessions, the three costliest branches, and the single most expensive session, computed
+from the same store as everything else.
+
+```bash
+tokenflow week                          # text summary
+tokenflow week --svg week.svg           # a shareable card
+tokenflow week --svg week.svg --png week.png   # card + a local screenshot
+tokenflow week --json                   # everything, machine-readable
+```
+
+See [exports-and-budgets.md](exports-and-budgets.md).
+
+### `budget`
+Monthly spend cap with projected-overrun alerts, deduplicated so a state only alerts once.
+
+```bash
+tokenflow budget --set 200     # $200/month, warn at 80% projected
+tokenflow budget               # current state: safe / approaching / over
+```
+
+A `budgets:` list in `config.yaml` adds caps scoped to one repository or to the whole team,
+alongside the single monthly cap above; `tokenflow budget` prints both when any are configured. See
+[configuration.md](configuration.md) for the `budgets:` shape and
+[exports-and-budgets.md](exports-and-budgets.md) for how each scope's spend is computed.
+
+---
+
+### `guard`
+A circuit breaker for the session you are in, run as a Claude Code hook. It reads the live
+transcript with the same adapter and price table as everything else, then reports the running
+spend, the size of the prompt now being re-sent, and the median cost of the last ten turns — and
+warns or blocks against thresholds **you** declared. With none declared it is informational and
+never blocks.
+
+```bash
+tokenflow guard --install                        # print the settings.json hooks block (not written)
+tokenflow guard --set warnCostUsd=25,maxCostUsd=200,warnContextTokens=200000
+tokenflow guard --set maxCostUsd=                # clear one threshold
+tokenflow guard --session ~/.claude/projects/<slug>/<id>.jsonl   # judge one transcript
+```
+
+Hook contract: stdin carries `{session_id, transcript_path, hook_event_name, …}`. A warning is
+returned as JSON — `hookSpecificOutput.additionalContext` reaches the model,
+`systemMessage` reaches you. A declared cap that is reached exits `2`, which blocks a
+`PreToolUse` tool call or rejects a `UserPromptSubmit` prompt with the reason on stderr; `Stop`
+and `SessionStart` are never blocked. The read is incremental: each session's byte offset and open
+streaming groups are kept under `~/.tokenflow/guard/`, so a large transcript is read once.
+
+Keys: `warnCostUsd`, `maxCostUsd`, `warnContextTokens`, `maxContextTokens`, `warnMarginalUsd`.
+
+A repository can declare its own caps in `.tokenflow/policy.yaml`, committed with the code; a
+declared key there wins over the personal config, key by key.
+
+```bash
+tokenflow guard --policy                  # effective policy for the current directory
+tokenflow guard --policy --cwd <dir>      # for some other directory / repository
+```
+
+Codex CLI has no blocking hook, so its integration only warns, through an OS notification:
+
+```bash
+tokenflow guard --install --codex            # print the notify = [...] line for config.toml
+tokenflow guard --install --codex --apply    # append it, only if safe to do so
+```
+
+See [guard-codex.md](guard-codex.md) for the policy file shape and the Codex `notify` contract.
+
+---
+
+### `hooks`
+Installs a `pre-push` git hook that attaches a receipt to the pushed commit as a git note under
+`refs/notes/tokenflow`, so the receipt travels with the code instead of living only on this
+machine. The [GitHub Action](../action/README.md) reads that note on a pull request and posts or
+updates one comment.
+
+```bash
+tokenflow hooks install      # write .git/hooks/pre-push
+tokenflow hooks uninstall    # remove it, restoring anything it replaced
+tokenflow hooks status       # installed? chained? where?
+```
+
+The hook never blocks a push: every failure is reported on stderr with exit `0`. A hook it
+replaces is kept as `pre-push.tokenflow-chained` and always runs first, keeping its own exit
+code, so a pre-existing gate still gates. See [receipt-schema.md](receipt-schema.md).
+
+---
+
 ### `providers`
 What is detected, connected, or disabled, with the reason for each. `--json`.
 
@@ -168,6 +305,50 @@ Missing values are written as empty cells, never as `0`.
 
 ---
 
+## Team & sync
+
+### `sync`
+Optional, off by default: exchange daily rollups (and, unless disabled, a branch/PR receipt
+ledger) between machines through a folder you already sync, or by pushing to a server you run.
+
+```bash
+tokenflow sync                          # push this machine's files, then show the merged view
+tokenflow sync --pull                   # merged view only, no push
+tokenflow sync --off                    # disable sync entirely
+tokenflow sync --to <url> --token <t>   # push both files to a team server instead of a folder
+```
+
+`--to` (or `sync.to` in `config.yaml`) sends the exact same two files to
+`tokenflow team serve` (or any server that speaks its `/api/rollup` contract) instead of writing
+them into `sync.dir`; there is no merged view to pull from a server, so this only pushes. The
+token can come from `--token`, `sync.token`, or the `TOKENFLOW_SYNC_TOKEN` environment variable.
+`sync.receipts: false` skips the ledger file. See [ledger.md](ledger.md) and
+[team-server.md](team-server.md).
+
+### `team`
+Per-developer usage, joined from every machine's synced rollups, plus the branch/PR cost ledger
+once any machine has pushed one.
+
+```bash
+tokenflow team                    # aggregated view from the shared sync folder
+tokenflow team --json             # machine-readable
+tokenflow team serve              # self-hosted server: same aggregate, over HTTP
+```
+
+`team serve` runs one process on a machine the team owns (LAN or Docker) so every machine can push
+with `sync --to` instead of writing into a shared folder.
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--host` | `127.0.0.1` | bind address; non-loopback requires a token |
+| `--port` | `7790` | bind port |
+| `--dir` | `<TOKENFLOW_HOME>/team` | where uploaded rollups are stored |
+| `--token` | — (falls back to `TOKENFLOW_TEAM_TOKEN`) | shared bearer token |
+
+See [team-server.md](team-server.md) for the auth model and routes.
+
+---
+
 ## Live
 
 These four read the watcher's snapshot (`data/status.json`) when it is fresh
@@ -261,6 +442,22 @@ fetched, and whether the source is official or third-party — plus the service-
 that get applied per request, and the one premium tier that is deliberately *not* applied
 (long-context).
 
+### `pricing diff`
+Compares a candidate price table to the current effective one (the overrides file layered on the
+built-in table, same as every other command resolves it) and prints what would change: models
+added, rates changed with the percent change per field, and current overrides the candidate says
+nothing about.
+
+```bash
+tokenflow pricing diff table.json              # print the diff only
+tokenflow pricing diff table.json --apply      # print, then confirm interactively (y/N)
+tokenflow pricing diff table.json --apply --yes   # print and apply, no prompt (scripts, CI)
+```
+
+`--apply` merges the candidate's models into the overrides file; it never replaces it, and a
+model the candidate does not mention keeps its existing override untouched. Refused when the
+candidate has an invalid entry, or (without `--yes`) when stdin is not an interactive terminal.
+
 ### `import <file>`
 Generic import for CSV / TSV / JSON / JSONL / SQLite. With no `--field` flags it prints the
 columns it found, infers a mapping, and previews five normalized rows.
@@ -328,6 +525,13 @@ tokenflow config import backup.json      # restore on another machine
 Runtime, `node:sqlite` availability, timezone, every path, store size, cube rows, sessions,
 pending compaction, and every adapter's detection status. Start here when something is off.
 
+After the Store section, an **Audit** block runs seven data-quality checks over the last three
+months of records: git worktrees fragmenting a repository's spend, a recorded cwd outside any
+repository, Codex records with no git branch, unpriced models, a stale built-in price table,
+session-level sources present in per-turn views, and records explicitly marked
+`metadata.repoResolved === false`. Each line names the check, its severity (`ok` / `info` / `warn`
+/ `fail`), and a one-line fix when it is not clean.
+
 ### `validate`
 Re-validates every stored record against the schema and reports the failure modes by frequency.
 Exits non-zero if anything is invalid.