@vimoxshah/tokenflow 1.1.2 → 1.2.0

package/docs/roadmap.md

@@ -0,0 +1,182 @@
+# Roadmap — TokenFlow after the pivot
+
+Written 2026-09-05. This is the ambitious version. Everything here keeps the one
+promise the product is built on: **your data stays on machines you own.** A folder
+you already sync and a server you run on your own network are in. A hosted
+service that holds anyone's usage is out, for now, and the line is drawn in
+section 9.
+
+The spine is three products on one engine. Every other item exists to show,
+capture, or distribute one of them.
+
+| | Receipts | Guard | Ledger |
+|---|---|---|---|
+| Question it answers | What did this branch / PR cost? | Is the session I am in getting expensive? | What does our team's AI spend buy, per merged PR? |
+| Who reads it | the whole team, in the PR | the developer, mid-session | the engineering manager, the FinOps lead |
+| State today | CLI `tokenflow receipt`, merge-bounded, worktree-aware | CLI `tokenflow guard`, Claude Code hook, incremental | `tokenflow team` over a shared folder or `tokenflow team serve`; receipts joined per branch, the PR join still needs a cached PR list |
+
+---
+
+## 1. Design system — one source, three surfaces (now)
+
+Done first because every item below renders through it.
+
+- `design/tokens.yaml` is the single source: roles not values, two axes (mode ×
+  skin), type scale with size-specific tracking, a 4-pt space scale, radii, two
+  motion tiers, status colors, authored chart ramps.
+- `scripts/design-build.js` compiles it into the dashboard CSS, the landing CSS
+  and the menu bar's Swift constants, and refuses to emit anything that fails
+  the gates: ink contrast, series-on-surface contrast, adjacent-series
+  perceptual distance, sequential monotonicity, status-vs-series distinctness.
+- A test regenerates and diffs, so a hand edit to a generated block fails CI.
+- Doctrine lives in `docs/design-system.md`.
+
+## 2. Dashboard — from "a dashboard" to "it told me something" (now → next)
+
+**Now**
+
+- **Story strip.** The Overview opens with the three sentences that matter this
+  week, each with its number, generated from `insights.js` — not a grid of
+  KPIs you have to interpret.
+- **Receipts view.** Per repository, per branch: spend, context share, sessions,
+  turns, subagent share, vs-median. Click a branch for the PR-comment receipt
+  and a copy button. Works in the offline snapshot because receipts ship in
+  the bundle.
+- **Polish pass** through the tokens: press feedback on every pressable,
+  popovers that scale from their trigger, tooltips that are instant once one is
+  open, a short stagger only when a view changes, translucent header, hover
+  states gated to pointer devices, reduced-motion that degrades to a complete
+  state.
+
+**Next**
+
+- **Session anatomy.** Pick a session and see its turn-by-turn cost waterfall,
+  its context growing turn over turn, its subagent fan-out as a tree, and the
+  moment its per-turn cost stepped up. This is the flame graph for agent
+  spend; nothing else draws it.
+- **Live sessions.** Transcripts modified in the last few minutes, each with a
+  running cost ticker, a context gauge and the guard's verdict. The dashboard
+  becomes something you leave open.
+- **Cache health.** Cache-write churn (a system prompt change invalidating the
+  cache), 5-minute vs 1-hour write split, hit-rate over time, and the dollar
+  cost of each churn event.
+- **Model what-if.** Re-price the same tokens at another model's rates and show
+  the difference, labelled as a what-if about price, never a claim about
+  quality.
+- **Compare v2.** Any two windows or any two branches side by side, with the
+  diverging ramp doing the work.
+- **Rhythm and focus.** Deep-work sessions, project switching per day, the
+  hour your marginal cost per turn is highest.
+- **Command palette (⌘K)** for every filter, tab and export; no animation on
+  keyboard actions.
+- **First-run screen.** "Here is what we found on this machine, here is what we
+  did not, here is why." Sets expectations before the first chart.
+- **Annotations.** Mark a day ("switched to Opus 5", "started using
+  subagents") and see it on every time series.
+
+## 3. Menu bar — the glanceable surface (now → next)
+
+**Now**
+
+- Consume the generated Swift tokens; retire the hardcoded gradients (the
+  streak banner's saturated fill breaks the system's own rule that a gradient
+  sits only behind a single number).
+
+**Next**
+
+- **Live session ticker.** The session running right now: spend, context size,
+  guard state. Updates every refresh cycle.
+- **Today's receipts.** The three branches that cost most today.
+- **Guard state.** Thresholds, last verdict, one click to raise or clear a cap.
+- **Transient alert.** When a session crosses a declared cap, a small
+  notification-style card slides in from the status item and leaves the same
+  way it came. Spatially consistent, interruptible, never modal.
+- **Density modes.** Compact for a laptop screen, comfortable for a display.
+- **Keyboard shortcut** to open the popover; no open/close animation on it.
+- **Sparklines** for the last 24 hours of spend, by source.
+
+## 4. Capture — read more, still read nothing sensitive (next)
+
+New adapters, each ~80 lines plus a fixture, each reading counts and metadata
+and discarding content:
+
+- Gemini CLI, GitHub Copilot CLI, Aider, Antigravity, Zed, Windsurf, JetBrains
+  AI Assistant, Continue, Ollama (measured local tokens), LM Studio,
+  LiteLLM/OpenRouter local logs.
+- **Codex branch capture** so Codex work can be attributed to a PR (today its
+  records carry no branch).
+- Fix the two attribution defects in the adapters: git worktrees counted as
+  separate repositories, and `project` set to the working directory's basename.
+
+Hooks and integrations that run on the developer's machine:
+
+- **Receipt on push.** A `pre-push` hook writes the branch receipt to
+  `.tokenflow/receipts/<branch>.json` and adds an `AI-Cost:` commit trailer.
+- **GitHub Action `tokenflow/receipt-comment`.** Reads that file on
+  `pull_request` and posts the markdown block. No server involved.
+- **Codex guard.** The same circuit breaker for Codex sessions.
+- **Per-repo policy file** `.tokenflow/policy.yaml`, committed with the code,
+  so a team's caps travel with the repository.
+- **Receipt schema v0**, published, so FinOps tools can ingest receipts.
+
+## 5. Ledger — the buyer's view (next → later)
+
+- Join receipts into the team rollup: cost per merged PR by team, repo and
+  month; the concentration curve for the team; orphan (after-merge) spend.
+- **Self-hosted team server.** One process on a machine the team owns (LAN,
+  Docker), fed by the same per-machine rollups the folder sync uses today.
+  Per-developer names remain opt-in per person. Still no cloud.
+- **Exports that travel.** A receipt as a PNG card for Slack or a PR; a weekly
+  "your AI week" card; CSV of receipts.
+- **Budgets per repo and per team**, using the existing budget engine.
+
+## 6. Landing page and story (now)
+
+- Rewrite around the finding, not the features: the cost of every PR, the
+  turn-50 step in marginal cost, the guard that acts on it, and the honesty
+  caveats that come with each number.
+- Self-hosted fonts, no third-party requests, no decorative 3D background.
+- The live demo shows a Receipts view with synthetic branches.
+
+## 7. Platform reach (later)
+
+- **Windows and Linux tray apps.** Same status file, same tokens; native per
+  platform rather than a web wrapper, to keep the zero-dependency promise.
+- **Browser extension** that reads token counts from chat UIs' own responses,
+  locally, and writes them into the store. Counts only.
+- **Signed macOS build** once there is an Apple Developer account behind the
+  project; the Gatekeeper dance is the first thing every new user hits.
+
+## 8. Data quality and trust (continuous)
+
+- Price table refresh flow that shows the diff and its sources before applying.
+- Coverage shown on every receipt and every total, as now.
+- Hermes and other session-level sources labelled as such in per-turn views.
+- A `tokenflow doctor` check for every defect found in the 2026-09 audit.
+
+## 9. The line we do not cross yet
+
+| In | Out, for now |
+|---|---|
+| Folder sync you already run (iCloud, Dropbox, Syncthing, a git repo) | Any hosted service that stores usage |
+| A server you run on your own network | Telemetry of any kind |
+| Receipts you choose to push to your own repository | Prompt or code content in any store |
+| Exports you choose to share | Default-on names in team views |
+
+---
+
+## Sequencing
+
+| Window | Ships |
+|---|---|
+| **Now** (this release) | Design system + compiler + gates (shipped) · dashboard polish (shipped) · story strip (shipped) · Receipts view (shipped) · menu bar on tokens (shipped) · landing v2 (shipped) |
+| **Next** (weeks 2-6) | Session anatomy (shipped) · live sessions (shipped) · receipt-on-push hook + GitHub Action (shipped) · Codex branch capture (shipped) · attribution defect fixes (shipped) · cache health (shipped) · guard state in menu bar (shipped) |
+| **Later** (quarter) | Ledger join + self-hosted team server (shipped) · model what-if (shipped) · new adapters in batches (otel shipped; the rest still need a sample, see docs/providers-otel.md) · Windows/Linux trays (not started) · signed build (not started) |
+
+**Status 2026-09-06:** everything in the Now and Next rows above has shipped, along with the
+Ledger, the self-hosted team server, model what-if, and the otel adapter from Later. The six
+views named in section 2's Next list (Session anatomy, Cache health, Model what-if, Compare v2,
+Rhythm and focus, Annotations) all landed as registered modules, plus Compare branches as a
+seventh. Remaining open items: Windows/Linux trays, the browser extension, a signed macOS build,
+and adapters for Aider/Ollama/LM Studio/Zed/Windsurf/JetBrains/Continue/Copilot CLI/Antigravity
+(each needs a sample before it can be verified).

package/docs/team-server.md

@@ -0,0 +1,170 @@
+# Team server (self-hosted)
+
+`tokenflow team serve` runs one process on a machine your team owns — a spare
+box on the LAN, or a container — and lets every teammate's `tokenflow sync`
+push its daily rollup there instead of writing into a shared folder
+(iCloud/Dropbox/Syncthing). It is a second transport for the exact same data
+the folder-sync `tokenflow team` view already reads: the aggregation logic
+(`src/core/team.js`) and the plain-text renderer are unchanged.
+
+Nothing here reads prompt or code content. Each machine sends the same
+coarse daily rollup the folder sync already produces — tokens, requests,
+estimated cost, and (only if that developer opted in locally) their chosen
+name. Request bodies are never logged.
+
+## Run it
+
+```
+tokenflow team serve
+```
+
+Defaults: binds `127.0.0.1:7790`, stores uploads under
+`<TOKENFLOW_HOME>/team` (created if missing).
+
+```
+tokenflow team serve --host 0.0.0.0 --port 7790 --token <shared-secret>
+```
+
+A **non-loopback** `--host` always requires a token — the server refuses to
+start without one, so an operator cannot accidentally expose an open write
+endpoint to the network. The token can also come from the
+`TOKENFLOW_TEAM_TOKEN` environment variable instead of `--token` (handy for
+Docker/systemd where flags end up in `ps` output).
+
+| flag | default | meaning |
+| --- | --- | --- |
+| `--host` | `127.0.0.1` | bind address |
+| `--port` | `7790` | bind port |
+| `--dir` | `<TOKENFLOW_HOME>/team` | where uploaded rollups are stored |
+| `--token` | — (falls back to `TOKENFLOW_TEAM_TOKEN`) | shared bearer token |
+
+## Auth model
+
+There is exactly one shared secret — no per-person accounts, the same token
+for every machine that pushes and every teammate who reads.
+
+- **Writes** — `POST /api/rollup` requires `Authorization: Bearer <token>`
+  **whenever a token is configured.**
+- **Reads** — `GET /api/team` and `GET /` require the token too, once
+  configured: the aggregate carries repo names, branch names, machine names
+  and costs, and a LAN peer should not see any of that without the secret.
+  Two ways to authenticate a read:
+  - `Authorization: Bearer <token>`, same as writes, or
+  - a `tf_token` cookie. Visit `/?token=<token>` once from a browser you
+    trust; the server mints the cookie (`HttpOnly`, `SameSite=Strict`,
+    `Path=/`) and immediately redirects to `/` with the query string
+    stripped, so the token never lingers in the address bar or browser
+    history. Every subsequent `GET /` from that browser is authenticated
+    automatically.
+  - Without either, `GET /api/team` returns a 401 JSON error and `GET /`
+    returns a minimal "a token is required" page with **no aggregate
+    content** — not even a hint of machine names or numbers.
+- **`GET /health`** always answers (so a liveness check never needs the
+  token), but the payload depends on auth: `{ "ok": true }` only when
+  unauthenticated, the full `{ "ok": true, "machines": <n>, "updatedAt":
+  "<iso|null>" }` once authenticated.
+- **No token configured** (the loopback default) — every route stays open,
+  unchanged from a server with no auth story at all. There is no per-viewer
+  identity to check on a machine only its owner can reach.
+- Put this server on a private network (LAN, VPN, or a Docker network with
+  no public port mapping) regardless — the token protects the data, not the
+  network path to it.
+
+## Routes
+
+- `POST /api/rollup` — body `{ "machineId": "<id>", "files": { "<name>": "<text>" } }`.
+  - `machineId` must match `^[A-Za-z0-9_-]{8,64}$` (the same id
+    `tokenflow sync` already generates per machine).
+  - Every key in `files` must equal exactly `<machineId>.jsonl` or
+    `<machineId>.receipts.json` — nothing else is accepted, and nothing is
+    ever written outside the server's storage directory.
+  - The whole request body is capped at 8 MB.
+  - `.jsonl` content is validated line by line (each non-blank line must
+    parse as JSON); `.receipts.json` content must parse as JSON as a whole.
+  - Files are written atomically (temp file + rename) so a reader never sees
+    a partial upload.
+  - Response: `{ "ok": true, "files": ["<name>", ...] }`. Invalid requests
+    get a short JSON error and a 400/401/413.
+- `GET /api/team` — `aggregate(dir)` as JSON (same shape `tokenflow team
+  --json` prints). 401 JSON error when a token is configured and the request
+  isn't authenticated (see "Auth model").
+- `GET /health` — counted directly from the uploaded `.jsonl` files (not the
+  aggregate), so it reflects what the server has actually received.
+  Unauthenticated response is `{ "ok": true }`; authenticated (or no token
+  configured) response is `{ "ok": true, "machines": <n>, "updatedAt":
+  "<iso|null>" }`.
+- `GET /` — a self-contained HTML page (no external requests, no scripts):
+  the dashboard's generated design tokens inlined so colours/fonts match the
+  rest of TokenFlow, a heading, machine count and freshness, and the same
+  plain-text view `tokenflow team` prints. A "top repositories" table is
+  added once the aggregate exposes `receipts.byRepo`; today `aggregate()`
+  only reads the `.jsonl` files, so the page shows the `<pre>` view alone
+  until the receipts pipeline lands (see "Open questions" below) — the page
+  degrades to that automatically, no error either way. When a token is
+  configured and the request isn't authenticated, this route instead
+  returns a minimal "token required" page with no aggregate content, unless
+  the request is `/?token=<token>` (see "Auth model").
+
+## Example: pushing from a machine
+
+```bash
+curl -X POST http://team-box.local:7790/api/rollup \
+  -H "authorization: Bearer $TOKENFLOW_TEAM_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{
+    "machineId": "m-a1b2c3d4",
+    "files": {
+      "m-a1b2c3d4.jsonl": "{\"machineId\":\"m-a1b2c3d4\",\"date\":\"2026-09-05\",\"inputTokens\":1000,\"outputTokens\":200,\"requests\":5,\"estCostUsd\":1.23}\n",
+      "m-a1b2c3d4.receipts.json": "{}"
+    }
+  }'
+```
+
+## Safety notes
+
+- The server never serves files from its storage directory directly — only
+  through `aggregate()`/`renderText()`, and never logs request bodies.
+- Only `POST /api/rollup` is rate-capped (by body size, not frequency) —
+  nothing else limits request rate. Keep the server on a network only your
+  team can reach.
+- `Cache-Control: no-store` is set on every response.
+- The `tf_token` cookie has no `Secure` attribute, since this server is
+  typically plain HTTP on a LAN/Docker network rather than behind TLS; if you
+  do put it behind HTTPS, note that a plain-HTTP fallback path on the same
+  host would still see the cookie (`SameSite=Strict` limits cross-site use,
+  not cross-scheme use on the same site).
+
+## Docker
+
+`Dockerfile.team` builds a tiny `node:22-alpine` image with no `npm install`
+step (zero runtime dependencies — the whole app is already plain ESM). Set
+`TOKENFLOW_TEAM_TOKEN` and mount a volume for the storage directory:
+
+```bash
+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
+```
+
+Inside the container the server binds `0.0.0.0` (so Docker's port mapping can
+reach it), which is why `TOKENFLOW_TEAM_TOKEN` is mandatory there.
+
+## Open questions
+
+- The exact shape of `receipts.byRepo` on the `aggregate()` result is owned
+  by the in-progress receipts pipeline (see `src/core/team.js`,
+  `src/core/sync.js` module headers). This page reads `repo`/`name`,
+  `tokens`, and `estCostUsd`/`cost` off each entry defensively and skips the
+  table entirely if the shape isn't there yet; once that pipeline lands, the
+  table may need its column list revisited against the real field names.
+- `--port` with a non-numeric value is passed straight to `server.listen()`,
+  which fails with Node's own error rather than a friendly CLI hint.
+- A client that declares a huge `Content-Length` but never times out its
+  upload is read to completion (bounded memory, unbounded time) before the
+  413 is returned — see the comment on `readBodyLimited` in
+  `src/commands/team-serve.js` for why closing the connection early instead
+  resets it. There is deliberately no request-rate limiting; per the task's
+  own scope this is body-size-only.

package/docs/ui-views.md

@@ -0,0 +1,322 @@
+# Dashboard views and server routes
+
+Add a tab to the dashboard, and an API endpoint to serve it, without editing
+`src/ui/app.js` or `src/server/server.js`.
+
+Two registries do this:
+
+| Registry | File | Adds |
+| --- | --- | --- |
+| Views | `src/ui/views/index.js` | a tab in the dashboard |
+| Routes | `src/server/routes/index.js` | an endpoint on the local server |
+
+`src/ui/views/live.js` is the worked example. Read it next to this page.
+
+## Add a view in four steps
+
+1. Write `src/ui/views/<name>.js` with the exports below.
+2. Write `src/ui/styles/<name>.css` if the tab needs styles of its own.
+3. Import the module in `src/ui/views/index.js` and add it to `VIEWS`.
+4. Run the dashboard and open `#tab=<your id>`.
+
+Nothing else changes. app.js merges your tab into the tab bar, links your
+stylesheet in development, inlines it into the offline snapshot, and routes the
+deep link to you.
+
+## The view module
+
+```js
+import { el } from '../charts.js';
+
+export const id = 'burn';            // required, unique
+export const label = 'Burn rate';    // required, the tab caption
+export const order = 45;             // required, position in the tab bar
+export const css = './styles/burn.css';  // optional, relative to src/ui/
+
+export function view(ctx) {          // required, returns one element
+  return el('div', { class: 'grid' }, [ctx.sectionTitle('Burn rate')]);
+}
+
+export function onEnter(ctx) {}      // optional, the tab became active
+export function onLeave(ctx) {}      // optional, the tab stopped being active
+```
+
+**`id`** must not collide with a built-in tab or another view. app.js drops a
+module with a duplicate or missing id, logs to the console, and keeps every
+other tab working.
+
+**`order`** places the tab. The built-in tabs hold these numbers:
+
+| Order | Tab | | Order | Tab |
+| --- | --- | --- | --- | --- |
+| 10 | Overview | | 95 | Cache health (registered) |
+| 20 | Receipts | | 100 | Cost |
+| 25 | Session anatomy (registered) | | 105 | What-if (registered) |
+| 30 | Live (registered) | | 110 | Productivity |
+| 40 | Providers | | 115 | Rhythm (registered) |
+| 50 | Models | | 120 | Compare |
+| 60 | Interfaces | | 125 | Compare branches (registered) |
+| 70 | Time patterns | | 130 | Data explorer |
+| 80 | Peaks | | 135 | Annotations (registered) |
+| 90 | Efficiency | | 140 | Data health |
+
+They are spaced by 10, so pick a number between two of them. Ties break on id.
+
+**`view(ctx)`** returns one `HTMLElement`. It runs on every render, which means
+on every filter change, every theme change, and every tab entry. Keep it a pure
+function of `ctx` and cheap. If it throws, app.js shows a banner in that tab
+only and logs the error, so a broken view costs its own tab and nothing else.
+
+**`onEnter` / `onLeave`** fire when the active tab changes, including on the
+first paint and on a deep link. Use them for work that should happen once per
+visit rather than once per render.
+
+**Never import `src/ui/app.js`.** Everything you may use arrives in `ctx`. The
+offline snapshot bundler needs an acyclic module graph, and a view that imports
+app.js makes it cyclic. Importing `../charts.js`, `../../core/units.js`, or any
+other leaf module is fine.
+
+## The ViewContext
+
+app.js builds a fresh `ctx` for every render. `bundle`, `view` and `filters` are
+getters over live state, so a `ctx` you keep in a closure never goes stale.
+
+### State
+
+| Field | What it is |
+| --- | --- |
+| `S` | the whole dashboard state. Read freely. Write only fields you own. |
+| `bundle` | the aggregate bundle the page loaded. |
+| `view` | the computed analytics view for the current filters. This is what most tabs read. |
+| `filters` | the active filter object, the same object as `S.filters`. |
+| `snapshot` | `true` when the page is a saved offline file. |
+
+### Building the page
+
+| Helper | Use |
+| --- | --- |
+| `el(tag, attrs, kids)` | build an element. `text:` sets textContent, never HTML. |
+| `card(title, hint, body, actions)` | the standard card. |
+| `chartCard(id, title, hint, renderChart, tableSpec, extraActions)` | a chart with its table twin. Every chart needs one. |
+| `btn(label, onClick, cls, id)` | a button. |
+| `kpi(label, value, sub, opt)` | a KPI tile. |
+| `deltaChip(change, opt)` | the up/down/flat change chip. |
+| `sectionTitle(text)` | a section heading. |
+| `emptyCard(text, detail)` | the empty state. |
+| `openModal(title, body, foot)` / `closeModal()` | the shared dialog. |
+| `drillTo(key, value)` | filter to one value and repaint. |
+| `charts` | everything in `src/ui/charts.js` as a namespace. |
+
+### Formatting
+
+`ctx.fmt` holds the formatters from `src/core/units.js`, the same ones the CLI
+uses: `compact`, `int`, `usd`, `pct`, `signedPct`, `shortDate`, `longDate`,
+`hourLabel`, `hourWindow`, `relativeTime`, `humanDuration`, `countdown`, `DOW`.
+
+Use them. A number formatted by hand will disagree with `tokenflow status`
+sooner or later.
+
+### Doing things
+
+| Helper | Behaviour |
+| --- | --- |
+| `fetchJson(path, opt)` | resolves to the parsed JSON. In a snapshot it resolves to `null` instead of throwing. In the live dashboard it still rejects on an HTTP error, so catch it. |
+| `schedule(fn, ms)` | an interval app.js clears for you. See the lifetimes below. |
+| `rerender(opt)` | recompute the analytics view, then repaint. Pass `{ recompute: false }` to repaint only. |
+
+`schedule` has two lifetimes, and which one you get depends on where you call it:
+
+* Called from `onEnter`, the interval runs until the tab is left.
+* Called from `view()`, the interval is replaced on the next render. That is
+  deliberate: `view()` runs again on every filter change, and a single-lifetime
+  timer would stack a duplicate each time.
+
+Both are cleared when the tab is left. You never call `clearInterval` yourself.
+
+**Register `ctx.schedule` synchronously in `onEnter`, before any `await`.** app.js decides which
+interval belongs to which tab visit at the moment `onEnter` is called, not when it eventually
+finishes, so a call made after an `await` may register against a tab the user has already left.
+`src/ui/views/live.js` is the one registered view that polls, and it calls `ctx.schedule` as the
+very first thing its synchronous (non-`async`) `onEnter` does, before starting its own fetch.
+`cache.js` and `anatomy.js` also keep `onEnter` synchronous, though neither calls `schedule`;
+`annotations.js`'s `onEnter` is `async` but never calls `schedule` either, so the ordering hazard
+does not apply to it. A view that needs both `async` work and a recurring poll should call
+`ctx.schedule` before its first `await`, not after a fetch resolves.
+
+## Working offline
+
+Half the value of this dashboard is the saved HTML file. `tokenflow export
+--html` writes one self-contained page that opens from `file://` with no server
+and no network. Your view is inside it, so it must work there.
+
+The rule is simple: **anything that needs the server must be optional.**
+
+`ctx.snapshot` tells you which world you are in. Follow the Data explorer
+(`viewExplorer` and `loadExplorer` in app.js), which is the reference pattern:
+
+```js
+let rows = [];
+
+export async function onEnter(ctx) {
+  if (ctx.snapshot) {
+    // Read what the exporter embedded. Never call the API.
+    rows = (window.__TOKENFLOW_RECORDS__ || []).slice(0, 50);
+  } else {
+    const res = await ctx.fetchJson('/api/records?limit=50');
+    rows = res.rows;
+  }
+  ctx.rerender({ recompute: false });
+}
+```
+
+Three things fall out of that:
+
+* **Branch on `ctx.snapshot` before the call, not in a `catch`.** A snapshot has
+  no server. Trying and failing is slow and noisy.
+* **Hide controls that cannot work.** The Live view drops its "Manage limits"
+  button in a snapshot, because saving writes to the API. Live also hides the
+  whole "Real-time engine" card, because a file has no watcher.
+* **Everything in `ctx.bundle` and `ctx.view` is already there.** The exporter
+  embeds the bundle, so any tab computed purely from it works offline with no
+  extra effort.
+
+If a whole tab is meaningless offline, render `ctx.emptyCard()` with a sentence
+saying why. Do not render a dead control.
+
+## CSS
+
+**One file per view, at `src/ui/styles/<view>.css`.** Name it after the view.
+Set `css: './styles/<view>.css'` in the module. Do not add rules to
+`src/ui/styles.css`.
+
+* In development app.js injects one `<link>` per view, once, before the data
+  loads.
+* In a snapshot `src/export/html-snapshot.js` inlines `styles.css` first, then
+  every file in `src/ui/styles/` in name order.
+
+Both paths pick your file up automatically. There is no list to update.
+
+**Use the token variables only.** They come from the generated block at the top
+of `src/ui/styles.css`, which is built from `design/tokens.yaml`. No raw hex, no
+`rgb()` literals. Colours carry meaning across three skins and two modes, and a
+literal breaks in five of the six combinations.
+
+* surfaces: `--surface-1`, `--surface-2`, `--border`, `--hairline`
+* text: `--text-primary`, `--text-muted`
+* data series: `--series-1` to `--series-8`, `--seq-1` to `--seq-7`
+* status only: `--good`, `--warning`, `--critical`
+
+Status colours mark status. A chart series never uses one.
+
+Keep motion at 300ms or less, and ease out.
+
+Prefix your class names with the view id if there is any chance of a clash. All
+view stylesheets load together, in every mode, so `.row` will find someone
+else's `.row`.
+
+## Server routes
+
+`src/server/routes/index.js` exports `ROUTES`. Push an entry and the local
+server serves it:
+
+```js
+export const ROUTES = [
+  {
+    method: 'GET',
+    path: '/api/burn',
+    handler: (req, res, url, ctx) => ctx.json({ rate: 42 }),
+  },
+];
+```
+
+`path` is matched exactly. `method` is matched case insensitively. There is no
+pattern syntax: use a query string, which `url.searchParams` already parsed for
+you. The handler owns the response from the moment it is called, and nothing
+after it runs.
+
+On disk, a route module exports either one `Route` object or an array named
+`<NAME>_ROUTES`, and `src/server/routes/index.js` spreads it into `ROUTES`:
+
+```js
+// src/server/routes/index.js
+import { ANNOTATIONS_ROUTES } from './annotations.js';
+import { SESSION_ROUTE } from './session.js';
+
+export const ROUTES = [...ANNOTATIONS_ROUTES, SESSION_ROUTE];
+```
+
+### A worked example: `GET /api/session`
+
+`src/server/routes/session.js` is the reference a request-level route follows. It backs the
+Session anatomy tab, which needs one session's turn-by-turn records — the one thing the bundle
+never carries, because request-level data is too large to ship on every page load.
+
+```js
+// GET /api/session?id=<sessionId>
+export const SESSION_ROUTE = {
+  method: 'GET',
+  path: '/api/session',
+  handler: (req, res, url, ctx) => {
+    const id = url.searchParams.get('id');
+    if (!id) return ctx.json({ error: 'id is required' }, 400);
+    // ...find the session's date range, scan only the months it touches,
+    // slim each record to an allow-listed shape, then:
+    ctx.json({ id, session, months, scanned, total, returned, cap, truncated, records });
+  },
+};
+```
+
+Three things worth copying: the response body is an **allow-list** of fields (`slim()` in
+`session.js` names each one explicitly, so a metadata field added upstream later cannot leak in by
+default); the record count is **capped** (`RECORD_CAP`, 5000) and the cap, the true total and
+whether it was hit all travel in the body rather than silently truncating; and the store scan is
+**narrowed** to only the months the session's own date range touches, never the whole store.
+
+### Handler ctx
+
+| Field | What it does |
+| --- | --- |
+| `json(body, code)` | send JSON, default 200. |
+| `send(code, type, body)` | send anything else. |
+| `sendFile(file)` | stream a file from disk. |
+| `readBody()` | resolves to the request body as text. |
+| `config` | the loaded config. Read lazily and cached for this request. |
+| `paths` | the resolved store paths. Same. |
+| `buildBundle()` | the aggregate bundle the UI loads. |
+| `queryRecords(query)` | the record query behind `/api/records`. |
+| `root` | the repository root. |
+| `host`, `port` | what the server actually bound, correct even for port 0. |
+
+Throwing from a handler is safe. The server logs it and answers 500.
+
+### Rules
+
+* **Do not take a built-in path.** Registered routes are dispatched first, so a
+  clash would silently shadow `/api/bundle` or `/api/config` and break the whole
+  page. The server prints a warning at startup if you do. Reserved: `/`,
+  `/index.html`, everything under `/src/`, and `/api/bundle`, `/api/health`,
+  `/api/ping`, `/api/providers`, `/api/records`, `/api/live`, `/api/geo`,
+  `/api/config`, `/api/export.csv`, `/api/refresh`, `/api/pricing`,
+  `/api/prefs`.
+* **Anything that changes state must be POST.** The server applies its
+  same-origin and token check to every non-GET request, before dispatch.
+  Registered GET routes get exactly what inline GET routes get, which is
+  loopback binding and nothing more. A GET that mutates is unprotected.
+* **Stay local.** No outbound network calls, no telemetry, and never read prompt
+  or code content. These hold everywhere in this product and a route is not an
+  exception.
+* **A route is never the only way to get the data.** The snapshot has no server.
+  If your tab needs a route to say anything at all, it is a tab that does not
+  work offline, so make it degrade as described above.
+
+## Checklist before you hand a view over
+
+* [ ] `id`, `label`, `order`, `view` exported. `id` unique.
+* [ ] Module added to `VIEWS` in `src/ui/views/index.js`.
+* [ ] No import of `src/ui/app.js`.
+* [ ] Styles in `src/ui/styles/<view>.css`, token variables only.
+* [ ] Every chart has a table twin through `chartCard`.
+* [ ] Opens correctly from `#tab=<id>`.
+* [ ] `tokenflow export --html`, then open the file from `file://`. The tab
+      renders, with no console errors.
+* [ ] `npm run lint` and `node --test test/<yours>.test.js` pass.