@vimoxshah/tokenflow 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,186 @@
 All notable changes to TokenFlow are recorded here. Versions follow
 [semantic versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.2.0 — 2026-09-06
+
+Spend attributed to the unit of work, a guard that acts while a session is
+still running, and a design system that every surface compiles from. Nothing
+here reads prompt or code content.
+
+### Added
+
+- **Command palette.** ⌘K or Ctrl+K, or the "⌘K" chip at the end of the tab
+  bar: every tab, the quick ranges, each skin and mode, export, refresh and
+  clear filters, matched by subsequence or word prefix, with the last eight
+  commands first. It opens and closes with no animation because it is used
+  dozens of times a day. Works from the offline snapshot too. Inside a text
+  field, Ctrl+K keeps its editing meaning and ⌘K still opens the palette.
+- **First-run screen.** The first time the live dashboard opens, and again
+  after an upgrade, one screen says what was found on this machine: what each
+  source contributed, which detected adapters have read nothing yet, and why.
+  Never shown from a saved snapshot.
+- **Tab bar that wraps.** Twenty tabs wrap to two rows at 1280 and 1024 pixels
+  with the active tab always visible.
+- **A `--hairline` token.** The subtlest divider now has its own colour role in
+  `design/tokens.yaml` for every skin and mode, so views stop guessing.
+- **A design system with a compiler.** `design/tokens.yaml` is the single
+  source for colour roles, the two axes (mode × skin), a type scale with
+  size-specific tracking, a 4-pt space scale, radii, two motion tiers and the
+  authored chart ramps. `npm run design` compiles it into a generated block in
+  the dashboard stylesheet, a generated block in the landing stylesheet and
+  `menubar/TokenFlow/DesignTokens.swift`, and refuses to write when a gate
+  fails: ink contrast, series-on-surface contrast, adjacent-series perceptual
+  distance, sequential monotonicity, status-vs-series distinctness, the 300ms
+  ceiling on UI motion. `test/design.test.js` fails the build when a generated
+  block is hand-edited or stale. Doctrine in `docs/design-system.md`.
+- **Receipts view** in the dashboard: spend per repository and branch, with
+  context share, sessions, turns, subagent share and rank against the repo's
+  median. Click a branch for the receipt and copy it as a PR comment. Receipts
+  ship inside the data bundle, computed once per refresh and streamed rather
+  than materialized, so the offline snapshot has them too. The scan costs
+  about two seconds on a 160K-turn store, so the watcher's status snapshot
+  and the one-line CLI summaries opt out of it.
+- **Story strip** on the Overview: the three insights that matter for the
+  current slice, as sentences, with their numbers set in the figure face.
+- **Deep links**: `#tab=receipts&skin=terminal&mode=light` opens the dashboard
+  on that view and look. The tab is reflected in the URL as you switch.
+- **Motion and type polish through the tokens**: feedback on press for every
+  pressable, popovers that scale from their trigger, tooltips that respond in
+  a frame, cards that stagger in only when the view changes, a translucent
+  header material, hover states gated to pointer devices, and reduced-motion
+  and reduced-transparency that degrade to a complete state. Muted ink was
+  nudged in every skin to clear 4.5:1 on cards.
+- **Menu bar on the same tokens.** Accent, status colours and the categorical
+  palette now come from the generated Swift file; the saturated gradients on
+  the brand mark and the milestone banner became solid accent surfaces, per the
+  system's own rule that a gradient sits only behind a single number.
+- **Landing page rewritten around the finding, not the features**: a real
+  receipt in the hero, the three numbers from nine weeks of logs, the
+  marginal-cost curve, the receipt rules with the correction that produced
+  them, the guard, and the cap table with its upper-bound caveat. Built on the
+  same tokens, with self-hosted fonts and no third-party requests; the GSAP
+  and three.js dependencies are gone.
+
+- **`tokenflow receipt`** — what a branch or pull request cost. Each turn is
+  attributed to the branch checked out when it ran, so one long session that
+  moved across branches is split across them. Repositories are identified by
+  walking up from the recorded working directory to `.git` and following a
+  worktree's `gitdir:` pointer home, so `.worktrees/<x>` no longer counts as
+  its own project. `--gh` joins merged pull requests by head branch and prices
+  each at `$ per 100 changed lines`; `--md` renders a PR-comment receipt. A PR
+  owns the turns on its branch up to the merge; turns after the merge are
+  follow-up on a checkout that kept the branch name and are shown beside the
+  receipt, never inside it. Long-lived branches are flagged as such. The
+  estimate is split into *context* dollars (cache reads + writes: re-sending
+  the conversation so far) and *work* dollars (fresh input + output).
+  `--sessions` reports how concentrated spend is across sessions, the median
+  cost of a turn by how deep into a session it is, and the dollars above each
+  candidate per-session cap — labelled an upper bound, not a saving.
+- **`tokenflow guard`** — a Claude Code hook that reads the live transcript,
+  prices it, and reports running spend, current prompt size and the median cost
+  of the last ten turns, then warns or blocks against thresholds you declared
+  with `guard --set`. Nothing declared means informational only, never a
+  block. Reads are incremental per session. `--install` prints the hooks block
+  and does not write your settings.
+- **`tokenflow team serve`.** A self-hosted team server for the folder-sync
+  rollups: one process on a machine your team owns, fed by the same
+  per-machine files (`<id>.jsonl`, `<id>.receipts.json`) the folder sync
+  already writes. A single shared bearer token gates writes and reads once
+  configured; a non-loopback host always requires one. `GET /health` always
+  answers; `GET /api/team` and `GET /` return the same aggregate `tokenflow
+  team` prints. See `docs/team-server.md` and `Dockerfile.team`.
+- **The Ledger: cost per branch and per merged PR, across the team.**
+  `sync.push()` now also writes `<machineId>.receipts.json`, a whole-state,
+  opt-in-anonymous ledger of branch receipts (unless `sync.receipts: false`).
+  `tokenflow team` joins every synced ledger into `receipts.totals`,
+  `byRepo`, `byMonth`, `perMergedPr`, `concentration` and `longLivedShare`.
+  `sync.to` (plus `sync.token` or `TOKENFLOW_SYNC_TOKEN`) pushes both files to
+  a server instead of a shared folder; `tokenflow sync --to <url> --token
+  <t>` runs it from the CLI. See `docs/ledger.md`.
+- **Receipts travel with the code.** `tokenflow hooks install` writes a
+  `pre-push` hook that attaches a receipt to the pushed commit as a git note
+  under `refs/notes/tokenflow`. The hook never blocks: every failure is
+  reported on stderr with exit 0, and a hook it replaces is kept and chained,
+  running first and keeping its own exit code. Receipt schema v0
+  (`schemas/receipt.v0.json`, `src/analytics/receipt-schema.js`) makes the
+  note machine readable. A zero-dependency GitHub Action (`action/`) reads
+  the note on a pull request and posts or updates one PR comment. See
+  `docs/receipt-schema.md`.
+- **Per-repository guard policy and a Codex guard.** `.tokenflow/policy.yaml`
+  declares guard thresholds that travel with a repository and win over the
+  personal config, key by key; `tokenflow guard --policy [--cwd <dir>]`
+  shows the effective policy and each value's source. Codex CLI has no
+  blocking hook, so `tokenflow guard --install --codex [--apply]` wires up
+  its `notify` setting instead: it reads only `thread-id` and `cwd` from
+  Codex's payload and sends one OS notification on warn or block, never a
+  block itself. See `docs/guard-codex.md`.
+- **Exports that travel, and budgets per repo and per team.** `tokenflow
+  receipt` gains `--svg`, `--png` and `--csv`: a shareable receipt card, or
+  one CSV row per branch across every repository. `tokenflow week` builds
+  "your AI week" as text, JSON, or the same kind of card (`--svg`, `--png`).
+  A `budgets:` list in `config.yaml` adds caps scoped to one repository or to
+  the whole team, alongside the existing monthly budget; `tokenflow budget`
+  prints both. See `docs/exports-and-budgets.md`.
+- **`tokenflow doctor` data-quality audit and `tokenflow pricing diff`.**
+  Doctor now runs seven checks over the last three months of records:
+  worktree-split spend, cwd outside any repository, Codex records with no
+  git branch, unpriced models, a stale price table, session-level sources in
+  per-turn views, and `metadata.repoResolved === false`. `tokenflow pricing
+  diff <table.json> [--apply] [--yes]` compares a candidate price table to
+  the current effective one and merges it in only on explicit confirmation.
+- **Live status carries sessions, receipts, guard state and sparklines.**
+  `data/status.json` now includes `liveSessions` (up to 8 sessions active
+  within 10 minutes of the last refresh), `receiptsToday` (the top 3
+  branches by spend today), `guard` (declared thresholds plus the last
+  verdict, sourced `cache` or `derived`) and `sparklines` (24 hourly buckets
+  per source). The xbar/SwiftBar text shows a "Live now" line and a "Guard:"
+  line from the same data.
+- **The native menu bar shows the same live state.** A "Live, as of" section
+  lists running sessions with a context gauge and the guard's colour dot;
+  "Today's receipts" lists the day's top branches; "Guard" shows the
+  declared caps, the last verdict, and Raise-cap / Clear-caps buttons that
+  write through `tokenflow guard --set`, never by editing config.yaml
+  directly; a "Last 24 hours by source" sparkline section closes it out. A
+  transient card slides in from the status item only when a live session's
+  guard level rises, never on a recovery, and only one shows at a time.
+  Density (compact/comfortable) and the popover's global keyboard shortcut
+  are now preferences.
+- **Demo data is schema-complete.** The synthetic dataset now has a hot
+  repository and branch, five repositories, and volume that stays within
+  10% across weekdays, so every new view has something realistic to render
+  offline.
+- **`otel`, an OpenTelemetry (GenAI) adapter.** Reads a standards-based
+  OTLP JSON export (`resourceSpans`/`resourceLogs`, `gen_ai.usage.*`
+  attributes) from any tool's file exporter, and Gemini CLI's own file
+  telemetry (`~/.gemini/telemetry.log` by default, or `sources.otel.paths`),
+  deduplicating Gemini's paired usage events. See `docs/providers-otel.md`.
+- **Seven new dashboard views, each a registered module, not an app.js
+  edit.** Session anatomy: a session's turn-by-turn cost waterfall, growing
+  context and subagent fan-out, backed by `GET /api/session`. Live v2: the
+  four "right now" sections above, as its own tab. Cache health: hit rate,
+  write split and churn events with their dollar cost. What-if: reprice the
+  same tokens at another model's rates, labelled as a price-only comparison.
+  Compare branches: any two branch receipts on a symmetric log scale.
+  Rhythm: deep-work sessions, project switching, and the hour marginal cost
+  peaks. Annotations: mark a day and see it on every daily chart, stored in
+  `annotations.json`. All seven route through the view registry
+  (`src/ui/views/index.js`) and the route registry
+  (`src/server/routes/index.js`) documented in `docs/ui-views.md`.
+
+### Fixed
+
+- **Git worktrees no longer split one repository's spend.** A session in
+  `<repo>/.worktrees/<x>` used to file under `x`; ingestion now resolves
+  `project` and `repository` through the main checkout at ingest time
+  (`src/core/repo.js`, `metadata.repoResolved`), and `tokenflow doctor`
+  flags any repository still fragmented across worktree names. Repair
+  existing history with `tokenflow refresh --full`.
+- **Codex sessions now carry a branch and a repository name.** CLI builds
+  0.149 and later report a `git` block on `session_meta` (`branch`,
+  `repository_url`); the openai adapter sets `git_branch` and `repository`
+  from it, falling back to the cwd basename exactly as before when the block
+  is absent.
+
 ## 1.1.2 — 2026-09-03
 
 Makes the downloadable app usable on a machine that is not the one that built

package/Dockerfile.team

@@ -0,0 +1,20 @@
+# TokenFlow team server — tiny image, zero runtime dependencies, no `npm install`.
+# See docs/team-server.md.
+#
+#   docker build -f Dockerfile.team -t tokenflow-team .
+#   docker run -d -e TOKENFLOW_TEAM_TOKEN=<shared-secret> -p 7790:7790 \
+#     -v tokenflow-team-data:/data tokenflow-team
+FROM node:22-alpine
+
+WORKDIR /app
+COPY package.json ./
+COPY bin ./bin
+COPY src ./src
+
+ENV TOKENFLOW_HOME=/data
+VOLUME ["/data"]
+EXPOSE 7790
+
+# --host 0.0.0.0 so the container's port mapping can reach the server; a
+# non-loopback bind requires TOKENFLOW_TEAM_TOKEN to be set at `docker run`.
+CMD ["node", "bin/tokenflow.js", "team", "serve", "--host", "0.0.0.0", "--port", "7790"]

package/README.md

@@ -39,12 +39,12 @@ per-source and per-model usage, capacity meters and forecast, in light and dark.
 
 | Layer | What's inside |
 |---|---|
-| **Ingestion** | 10 adapters (Anthropic, OpenAI/Codex, OpenCode, Hermes, Cline, Cursor, Headroom gateway, git, generic CSV/JSONL/SQLite import, demo). Incremental byte-offset resumes, re-read windows for upserted rows, budgeted refresh that stops cleanly mid-corpus |
+| **Ingestion** | 11 adapters (Anthropic, OpenAI/Codex, OpenCode, Hermes, Cline, Cursor, Headroom gateway, git, OpenTelemetry/GenAI (otel), generic CSV/JSONL/SQLite import, demo). Incremental byte-offset resumes, re-read windows for upserted rows, budgeted refresh that stops cleanly mid-corpus |
 | **Correctness** | Cache read/write/input kept as mutually exclusive buckets; vendor convention differences handled; streaming re-reports collapsed to max-of-run; `null` never coerced to 0; measured gateway cost kept separate from estimates |
 | **Costing** | Versioned price table with per-entry source URLs and fetch dates; service-tier multipliers; long-TTL cache-write tier priced separately; unpriced models surface as `null` with a configure action — never silent `$0` |
-| **Analytics** | 12 views: overview KPIs, composition, provider/model intelligence, interfaces, hour×weekday heatmap + calendar, peaks, efficiency ratios, cost with coverage, git correlations (labelled), period compare, searchable data explorer, per-field data health |
-| **Live mode** | Watcher daemon, native Swift menu bar app (provider/source/model breakdowns, capacity meters with reset countdowns & ETAs, forecast with stated confidence, MAD-based anomaly alerts, appearance toggle), SwiftBar/xbar plugin |
-| **Engineering** | Zero runtime dependencies · 145 tests · lint invariants (e.g. "no `\|\| 0` on a token field") · tsc-clean JSDoc types · CI on macOS/Linux/Windows × Node 22/24 |
+| **Analytics** | 20 views: overview KPIs with a story strip, receipts per branch and pull request, session anatomy, live, composition, provider/model intelligence, interfaces, hour×weekday heatmap + calendar, peaks, efficiency ratios, cache health, cost with coverage, model what-if, git correlations (labelled), rhythm and focus, period compare, compare branches, searchable data explorer, annotations, per-field data health |
+| **Live mode** | Watcher daemon, native Swift menu bar app (live sessions, today's receipts, guard state, provider/source/model breakdowns, capacity meters with reset countdowns & ETAs, forecast with stated confidence, MAD-based anomaly alerts, per-source sparklines, appearance toggle), SwiftBar/xbar plugin |
+| **Engineering** | Zero runtime dependencies · 520 tests · lint invariants (e.g. "no `\|\| 0` on a token field") · tsc-clean JSDoc types · CI on macOS/Linux/Windows × Node 22/24 |
 
 Zero runtime dependencies. Nothing leaves your machine. No API keys, no accounts, no telemetry.
 
@@ -121,7 +121,8 @@ dashboard.
 
 | Question | Where |
 |---|---|
-| How much AI did I use, and how has that changed? | Overview — KPIs, daily series, trend |
+| What did this branch or pull request cost? | Receipts — spend per repository and branch, context share, copy as a PR comment |
+| How much AI did I use, and how has that changed? | Overview — the three insights that matter, then KPIs, daily series, trend |
 | Input vs output vs cache? | Token composition — four buckets that sum to the total |
 | Which provider and model do I rely on? | Provider & model share, growth, per-model efficiency |
 | When do I use AI most? | Time patterns — hour/weekday profiles, heatmap, calendar |
@@ -133,9 +134,14 @@ dashboard.
 <details>
 <summary>All pages</summary>
 
-Overview · Token composition · Providers & models · Interfaces · Time patterns · Peaks ·
-Efficiency · Cost · Productivity · Compare · Data explorer (searchable/sortable/exportable) ·
-Data health
+Overview · Receipts · Session anatomy · Live · Token composition · Providers & models · Interfaces ·
+Time patterns · Peaks · Efficiency · Cache health · Cost · What-if · Productivity · Rhythm · Compare ·
+Compare branches · Data explorer (searchable/sortable/exportable) · Annotations · Data health.
+Deep-link any of them: `#tab=receipts&skin=terminal&mode=light`.
+
+Press ⌘K (or Ctrl+K) anywhere in the dashboard for the command palette: jump to a tab, change the
+range, skin or mode, export, refresh or clear filters without touching the mouse. The first time
+the live dashboard opens it explains what was found on this machine and what was not, and why.
 
 </details>
 
@@ -196,12 +202,23 @@ node bin/tokenflow.js dashboard      # live UI at http://127.0.0.1:7799 (loopbac
 node bin/tokenflow.js watch          # auto-refresh every N seconds (default 120)
 node bin/tokenflow.js import f.csv   # CSV/JSONL/SQLite via saved field mapping
 node bin/tokenflow.js export --csv   # --all for everything; --html for offline snapshot
-node bin/tokenflow.js digest         # shareable markdown summary (--format text, --from/--to, --out f.md)
+node bin/tokenflow.js digest         # shareable weekly digest (--format text, --from/--to, --out f.md)
+node bin/tokenflow.js week           # this week's spend vs last week (--svg/--png card, --json)
 node bin/tokenflow.js models-compare # cost/usage efficiency per model — your data
 node bin/tokenflow.js budget --set 200   # monthly cap + forecast alerts (fires once per state/month)
 node bin/tokenflow.js schedule --install --at "Monday 09:00"  # weekly digest via launchd
 node bin/tokenflow.js diagnostics    # local observability — nothing transmitted
 node bin/tokenflow.js team           # per-developer team view (needs sync + opt-in names)
+node bin/tokenflow.js team serve     # self-hosted team server (LAN/Docker), no shared folder needed
+node bin/tokenflow.js sync --to <url> --token <t>   # push this machine's rollups to a team server
+node bin/tokenflow.js receipt --repo . --gh   # what each branch / merged PR cost (sees through worktrees)
+node bin/tokenflow.js receipt --sessions      # where the money goes: concentration, context vs work, marginal cost/turn
+node bin/tokenflow.js receipt --csv           # one row per branch, every repository
+node bin/tokenflow.js hooks install           # pre-push git hook: attach a receipt note, never blocks
+node bin/tokenflow.js guard --install         # Claude Code hook: warn/block a session against caps you declare
+node bin/tokenflow.js guard --install --codex # same circuit breaker for Codex CLI (warns only)
+node bin/tokenflow.js pricing diff table.json --apply   # merge a candidate price table in
+node bin/tokenflow.js doctor         # environment, store, adapters, and a data-quality audit
 node bin/tokenflow.js up             # refresh → rebuild offline HTML → serve + open
 
 npm link                             # optional: global `tokenflow` command
@@ -247,7 +264,7 @@ from `file://` with no server. A full CSV export doubles as a portable dataset:
 ## Contributing
 
 ```bash
-npm test               # 102 tests: normalization, adapters, analytics, store, formatting
+npm test               # 520 tests: normalization, adapters, analytics, store, receipts, guard
 npm run lint           # project invariants (incl. "no || 0 on a token field")
 npm run typecheck      # tsc over JSDoc types — must be zero errors
 npm run validate       # self-check: runtime, adapters, store↔cube agreement
@@ -276,8 +293,10 @@ Easiest contribution: an adapter (`src/providers/<id>/index.js`) plus a fixture
 
 Local data → local normalization → local analytics → local dashboard. The server binds to
 `127.0.0.1`. No prompt text, code, or file content is ever stored — adapters read token counts and
-discard the rest. No telemetry. Two features can touch the network, both strictly opt-in:
+discard the rest. No telemetry. Three features can touch the network, all strictly opt-in:
 
+- **Team server push** (`sync.to` in config, or `tokenflow sync --to <url>`) sends the same two
+  sync files to a server you run with `tokenflow team serve`, behind a bearer token. Nothing else.
 - **Digest delivery** (`delivery:` in config) — sends the digest you generate to your own
   Telegram chat, email, or webhook. Credentials live only in `~/.tokenflow/config.yaml`.
 - **Multi-machine sync** (`sync:` in config) — exchanges daily totals (date, tokens, requests,

package/bin/tokenflow.js

@@ -80,12 +80,16 @@ async function main() {
     case 'forecast': return cmdForecast();
     case 'menubar': return cmdMenubar();
     case 'digest': return cmdDigest();
+    case 'week': return cmdWeek();
     case 'schedule': return cmdSchedule();
     case 'budget': return cmdBudget();
     case 'sync': return cmdSync();
     case 'models-compare': return cmdModelsCompare();
     case 'diagnostics': return cmdDiagnostics();
     case 'team': return cmdTeam();
+    case 'receipt': case 'receipts': return cmdReceipt();
+    case 'hooks': return cmdHooks();
+    case 'guard': return cmdGuard();
     default:
       console.error(`${C.red}Unknown command "${cmd}".${C.r}\n`);
       return help(1);
@@ -264,7 +268,7 @@ async function cmdStatus() {
     const line = barLine(st, String(flags.mode || 'auto'), String(flags.prefix || 'TF'));
     return console.log(flags.json ? JSON.stringify(line, null, 2) : line.text);
   }
-  const b = buildBundle();
+  const b = buildBundle({ receipts: false });
   if (flags.json) return console.log(JSON.stringify({ meta: b.meta, health: b.health }, null, 2));
   const h = b.health;
   if (!h.records) {
@@ -446,6 +450,16 @@ async function cmdExport() {
 // ================================================================== pricing ==
 
 async function cmdPricing() {
+  if (argv[1] === 'diff') {
+    const { run } = await import('../src/commands/pricing-diff.js');
+    const file = argv[2];
+    if (!file) throw new Error('usage: tokenflow pricing diff <file.json|-> [--apply] [--yes]');
+    const res = await run({ file, apply: !!flags.apply, yes: !!flags.yes });
+    if (res.stdout) console.log(res.stdout);
+    if (res.stderr) console.error(res.stderr);
+    if (res.exitCode) process.exitCode = res.exitCode;
+    return;
+  }
   const p = paths();
   const cur = readJson(p.pricing, { models: {} });
   if (flags.set) {
@@ -488,7 +502,7 @@ async function cmdPricing() {
     return;
   }
 
-  const b = buildBundle();
+  const b = buildBundle({ receipts: false });
   const v = computeView(b, {});
   const book = buildPriceBook(readJson(p.pricing, {}));
   console.log(`\n  ${C.b}Pricing${C.r}  ${C.dim}built-in table ${PRICING_TABLE_VERSION} · overrides in ${p.pricing}${C.r}\n`);
@@ -747,6 +761,9 @@ async function cmdDoctor() {
   console.log(`   cube          ${int(store.cube().rows.length)} rows`);
   console.log(`   sessions      ${int(Object.keys(store.sessions().rows).length)}`);
   console.log(`   stale gens    ${(store.state.stale || []).length}${(store.state.stale || []).length ? `  ${C.y}run 'tokenflow compact'${C.r}` : ''}`);
+  const { auditChecks, renderChecks } = await import('../src/commands/doctor-checks.js');
+  console.log(`\n  ${C.b}Audit${C.r}  ${C.dim}data-quality checks over the last 3 months${C.r}`);
+  renderChecks(auditChecks({ store, config: cfg, now: new Date() }));
   console.log(`\n  ${C.b}Providers${C.r}`);
   await cmdProviders();
   console.log(`  ${C.dim}Troubleshooting guide: docs/troubleshooting.md${C.r}\n`);
@@ -1166,6 +1183,49 @@ async function cmdDigest() {
   }
 }
 
+/** `tokenflow week` — "Your AI week": this week's spend vs last week, as text, JSON, or a card. */
+async function cmdWeek() {
+  const { run } = await import('../src/commands/week.js');
+  const out = run(flags);
+  if (flags.json) return console.log(JSON.stringify(out.json, null, 2));
+  console.log(out.text);
+}
+
+/** `tokenflow receipt` — AI spend attributed to a branch / pull request. */
+async function cmdReceipt() {
+  const { run } = await import('../src/commands/receipt.js');
+  const out = run(flags);
+  if (flags.json) return console.log(JSON.stringify(out.json, null, 2));
+  if (typeof flags.out === 'string') {
+    fs.writeFileSync(flags.out, out.text + '\n');
+    return console.log(`${C.g}✓${C.r} wrote ${flags.out}`);
+  }
+  console.log(out.text);
+}
+
+/** `tokenflow hooks` — install/uninstall the pre-push git hook that attaches a receipt note. */
+async function cmdHooks() {
+  const { run } = await import('../src/commands/hooks.js');
+  const action = argv[1];
+  const out = run({ ...flags, action, args: argv.slice(2) });
+  if (out.stdout) process.stdout.write(out.stdout + '\n');
+  if (out.stderr) process.stderr.write(out.stderr + '\n');
+  process.exitCode = out.exitCode;
+}
+
+/** `tokenflow guard` — the in-session circuit breaker, run as a Claude Code hook. */
+async function cmdGuard() {
+  const { run } = await import('../src/commands/guard.js');
+  // Hooks run in a shell whose PATH may not include this node (nvm, asdf), so
+  // the printed command pins the interpreter and the CLI that are running now.
+  // `run()` is synchronous except for the `--codex-notify` branch, which
+  // returns a Promise — awaiting unconditionally handles both.
+  const out = await run({ ...flags, bin: `${process.execPath} ${path.join(root(), 'bin', 'tokenflow.js')}` });
+  if (out.stdout) process.stdout.write(out.stdout + '\n');
+  if (out.stderr) process.stderr.write(out.stderr + '\n');
+  process.exitCode = out.exitCode;
+}
+
 /** `tokenflow schedule` — install/remove the weekly digest LaunchAgent. */
 async function cmdSchedule() {
   const sched = await import('../src/core/schedule.js');
@@ -1191,9 +1251,19 @@ async function cmdBudget() {
     saveConfig(merge(cfg, { budget }));
     console.log(`${C.g}✓${C.r} monthly budget set to $${v.toLocaleString('en-US')}`);
   }
+  // Scoped budgets (repo | team) are independent of the single monthly cap
+  // below, so they are evaluated once and printed either way — a user who
+  // only declared `budgets:` and never set a monthly cap must still see them.
+  const { evaluateScopedBudgets, renderScopedBudgets } = await import('../src/commands/budget-scopes.js');
+  const scopedRows = evaluateScopedBudgets({ config: cfg });
+
   if (!budget.monthly) {
     console.log('No monthly budget configured. Set one:');
     console.log(`  ${C.b}tokenflow budget --set 200${C.r}   # $200/month, warn at 80% projected`);
+    if (scopedRows.length) {
+      console.log(`\n${C.b}Scoped budgets${C.r}`);
+      console.log(renderScopedBudgets(scopedRows));
+    }
     return;
   }
 
@@ -1204,7 +1274,14 @@ async function cmdBudget() {
   const today = new Date().toISOString().slice(0, 10);
 
   const st = computeBudgetState(status, { monthly: budget.monthly, warnAtPct: budget.warnAtPct }, today);
-  if (!st) { console.log('No usage data yet.'); return; }
+  if (!st) {
+    console.log('No usage data yet.');
+    if (scopedRows.length) {
+      console.log(`\n${C.b}Scoped budgets${C.r}`);
+      console.log(renderScopedBudgets(scopedRows));
+    }
+    return;
+  }
 
   const { fire } = shouldAlert(st, { force: !!flags.force });
 
@@ -1228,6 +1305,11 @@ async function cmdBudget() {
   } else if (st.state !== 'safe' && st.state !== 'unknown') {
     console.log(C.dim + '  (already alerted for this state this month — no spam)');
   }
+
+  if (scopedRows.length) {
+    console.log(`\n${C.b}Scoped budgets${C.r}`);
+    console.log(renderScopedBudgets(scopedRows));
+  }
 }
 
 /** `tokenflow sync` — optional multi-machine aggregation via a shared folder. */
@@ -1241,6 +1323,25 @@ async function cmdSync() {
     return;
   }
 
+  // A team server is a separate destination from the folder-sync `isEnabled`
+  // gate below: `push()`'s remote branch needs only `sync.enabled`, never
+  // `sync.dir`, so `--to` must not be blocked by "no folder configured". This
+  // path only ever pushes — there is no merged view to pull from a server.
+  const id = machineId();
+  const to = typeof flags.to === 'string' ? flags.to : (cfg.sync?.to || null);
+  const token = typeof flags.token === 'string' ? flags.token : undefined;
+  if (to) {
+    try {
+      const r = await push({ config: cfg, to, token });
+      if ('pushedTo' in r) console.log(`${C.g}✓${C.r} pushed → ${r.pushedTo}`);
+      else console.log(r.days ? `${C.g}✓${C.r} pushed ${r.days} days` : `${C.dim}nothing to push yet${C.r}`);
+      console.log(C.dim + `  this machine's id: ${id}${C.r}`);
+    } catch (e) {
+      throw Object.assign(new Error(e.message), { exitCode: 1 });
+    }
+    return;
+  }
+
   if (!isEnabled(cfg)) {
     console.log(`Multi-machine sync is ${C.b}OFF${C.r} by default. To enable it:
 
@@ -1253,22 +1354,21 @@ async function cmdSync() {
          dir: ~/Sync/TokenFlow        # that shared folder
          machineName: MacBook Pro     # label shown in aggregated views
 
-  3. Run ${C.b}tokenflow sync --push${C.r} on each machine.
+  3. Run ${C.b}tokenflow sync${C.r} on each machine.
+
+  A shared folder is not the only option: ${C.b}tokenflow sync --to <url> --token <t>${C.r}
+  pushes to a self-hosted team server instead — see docs/team-server.md.
 
 What is shared: daily totals only (date, tokens, requests, est. cost).
 What is never shared: prompts, code, file paths, credentials.`);
     return;
   }
 
-  const id = machineId();
-  if (flags.push || flags.pull === undefined) {
-    // default action with no sub-flag = push + pull
-  }
   try {
     if (!flags.pull) {
-      const r = push({ config: cfg });
+      const r = await push({ config: cfg });
       console.log(r.days
-        ? `${C.g}✓${C.r} pushed ${r.days} days → ${path.basename(r.file)}`
+        ? `${C.g}✓${C.r} pushed ${r.days} days → ${path.basename(r.file || '')}`
         : `${C.dim}nothing to push yet${C.r}`);
     }
     const merged = pull({ config: cfg });
@@ -1312,6 +1412,13 @@ async function cmdDiagnostics() {
 
 /** `tokenflow team` — per-developer usage from the shared sync folder (P4-B). */
 async function cmdTeam() {
+  // `team serve` runs a self-hosted server for machines that push with
+  // `--to` instead of writing into a shared folder — it needs no `sync.dir`
+  // of its own, so this must not fall through to the folder-sync gate below.
+  if (argv[1] === 'serve') {
+    const { run } = await import('../src/commands/team-serve.js');
+    return run(flags);
+  }
   const cfg = loadConfig();
   if (!cfg.sync?.enabled || !cfg.sync?.dir) {
     console.error(`${C.red}Team view reads the shared sync folder.${C.r}
@@ -1460,28 +1567,56 @@ function help(code = 0) {
   ${C.b}Intelligence${C.r}
     tokenflow models-compare        cost/request, tokens/request, cache-hit% per model
                                    (--from/--to <date> to pick the window)
+    tokenflow week                  this week's spend vs last week (--svg/--png card, --json)
     tokenflow budget --set 200      monthly cap → projected-overrun alerts (dedup'd)
     tokenflow budget                current state: safe / approaching / over
-    tokenflow digest --deliver      build "Your AI Week" and send via configured channels
+                                   (also evaluates any scoped budgets: repo | team)
+    tokenflow digest --deliver      build the weekly digest and send via configured channels
     tokenflow schedule --install --at "Monday 09:00"   weekly digest via launchd
     tokenflow schedule --status     is the digest schedule installed?
     tokenflow team                  per-developer usage from the shared sync folder
+    tokenflow team serve            self-hosted team server for the folder-sync rollups (--host --port --token --dir; non-loopback host needs a token)
     tokenflow diagnostics           version, providers, store freshness, feature states
 
+  ${C.b}Receipts & guard${C.r}
+    tokenflow receipt               spend per branch, per repository (sees through worktrees)
+    tokenflow receipt --repo <path> --gh
+                                   join branches to merged pull requests via gh
+    tokenflow receipt --repo <path> --gh --pr 478 --md
+                                   one PR-comment receipt (cost, context share, $/100 lines)
+    tokenflow receipt --csv         one row per branch, every repository, as CSV
+    tokenflow receipt --branch <b> --svg r.svg [--png r.png]
+                                   a shareable receipt card (SVG, or SVG + PNG)
+    tokenflow receipt --sessions    where the money goes: concentration, context vs work,
+                                   marginal cost per turn, dollars above a per-session cap
+    tokenflow hooks install|uninstall|status
+                                   pre-push git hook that attaches a receipt note (never blocks)
+    tokenflow guard --install       print the Claude Code hooks block for the circuit breaker
+    tokenflow guard --set warnCostUsd=25,maxCostUsd=200
+                                   declare thresholds (none declared = informational only)
+    tokenflow guard --session <f>   judge one transcript file
+    tokenflow guard --policy [--cwd <dir>]
+                                   effective guard policy for a directory, and each value's source
+    tokenflow guard --install --codex [--apply]
+                                   wire up Codex CLI's notify hook (warns only, never blocks)
+
   ${C.b}Sync (optional, off by default)${C.r}
     tokenflow sync                  push this machine's daily rollups + show merged view
     tokenflow sync --off            disable sync entirely
+    tokenflow sync --to <url> --token <t>   push both sync files to a team server
 
   ${C.b}Configure${C.r}
     tokenflow pricing               show which models have a price, and from where
     tokenflow pricing --sources     provenance of every built-in rate + tier multipliers
     tokenflow pricing --set "m=3,15,0.3,3.75"
+    tokenflow pricing diff <table.json> [--apply] [--yes]
+                                   compare a candidate price table to the current one
     tokenflow import <file>         CSV / JSON / JSONL / SQLite with field mapping
     tokenflow restore <file.csv>    rebuild the store from a full export, re-priced
     tokenflow config show|path|export|import
 
   ${C.b}Maintain${C.r}
-    tokenflow doctor                environment, paths, store, adapters
+    tokenflow doctor                environment, paths, store, adapters, data-quality audit
     tokenflow validate              re-validate every stored record
     tokenflow compact               drop superseded records after a rewrite
     tokenflow reset --yes           delete ingested data (keeps config)