@vimoxshah/tokenflow 1.1.0

package/docs/data-model.md

@@ -0,0 +1,213 @@
+# Data model
+
+Every adapter emits the same record shape. Nothing downstream — analytics, UI, export — knows
+anything about a specific vendor. This document is the contract.
+
+## The normalized record
+
+```ts
+interface NormalizedUsageRecord {
+  id: string;                 // stable dedup key
+  timestamp: string;          // ISO-8601, UTC
+  date: string;               // YYYY-MM-DD in the capture timezone
+  hour: number;               // 0-23 in the capture timezone
+  dow: number;                // 0=Mon .. 6=Sun in the capture timezone
+  tz_offset: number;          // capture tz offset, minutes
+
+  provider: string;           // canonical vendor slug: anthropic | openai | deepseek | zai | ...
+  provider_label: string;
+  gateway: string | null;     // routing layer (proxy/router), if any — NOT the vendor
+  model: string;              // raw model identifier from the source
+  model_family: string;       // human tier, e.g. "Claude Opus 5", "GPT 5.6 (sol)"
+
+  client: string;             // tool that made the call: claude-code | codex | cline | cursor
+  application: string;        // human label for the client
+  interface: Interface;       // CLI | IDE | Desktop App | Web | API | SDK | Extension | Unknown
+
+  input_tokens:         number | null;   // fresh prompt tokens, EXCLUDING cache
+  cache_read_tokens:    number | null;   // prompt tokens served from cache
+  cache_write_tokens:   number | null;   // prompt tokens written into cache
+  output_tokens:        number | null;   // generated tokens
+  cache_refresh_tokens: number | null;   // SUBSET of cache_write (long-TTL / refreshed)
+  reasoning_tokens:     number | null;   // SUBSET of output (thinking / reasoning)
+  total_tokens:         number | null;   // derived, never trusted from the source
+  total_is_partial:     boolean;         // some billable field was not available
+
+  session_id: string | null;
+  conversation_id: string | null;
+  request_id: string | null;
+
+  project: string | null;
+  repository: string | null;
+  git_branch: string | null;
+  category: string | null;    // main | subagent | commit | ai-edit:* | ...
+
+  estimated_cost: number | null;
+  cost_basis: 'measured' | 'estimated' | null;
+
+  source: string;             // adapter id
+  measurement: Measurement;   // primary | overlay | activity
+  user: string | null;        // multi-user ready
+  machine: string | null;
+  duration_ms: number | null;
+  metadata: object;           // source-specific, never interpreted by analytics
+}
+```
+
+## Missing-value contract
+
+This is the load-bearing rule of the whole project.
+
+| Value | Meaning |
+|---|---|
+| `null` | the source does not report this field — **not available** |
+| `undefined` | normalised to `null` on construction |
+| `0` | the source reported zero — a real, **measured** zero |
+
+Analytics **never** coerce `null` to `0`. Sums skip nulls and carry a parallel not-available
+counter per field (`naIn`, `naOut`, `naCr`, `naCw`), which is why the UI can say
+"cache tokens unreported by 22% of records in this slice" instead of drawing a confident zero.
+The linter enforces this: `|| 0` on a line mentioning a token field is a build error.
+
+Practical consequence: Cline logs sessions but no token counts, so **every** Cline token field is
+`null`, the record is `measurement: activity`, and its sessions count towards activity metrics
+without dragging every token average towards zero.
+
+## Token accounting
+
+### The four billable buckets are mutually exclusive
+
+```
+total_tokens = input_tokens + cache_read_tokens + cache_write_tokens + output_tokens
+```
+
+### The two breakdown fields are subsets and are never added again
+
+```
+cache_refresh_tokens ⊆ cache_write_tokens      (long-TTL / refreshed cache writes)
+reasoning_tokens     ⊆ output_tokens           (thinking / reasoning)
+```
+
+`validateUsage` rejects a record where a subset exceeds its parent, and the test suite asserts
+both invariants.
+
+### Vendors disagree about `input_tokens`
+
+| Vendor | What the source calls `input_tokens` | Adapter must |
+|---|---|---|
+| Anthropic | fresh prompt tokens, **excluding** cache read and cache creation | pass through |
+| OpenAI / Codex | prompt tokens **including** `cached_input_tokens` | subtract: `fresh = input − cached` |
+
+Getting this wrong double-counts every cached prompt token — once as fresh input and once as
+cache read. Each adapter's test asserts its own convention.
+
+### Ratios and what they actually divide by
+
+| Metric | Formula | Read it as |
+|---|---|---|
+| Output / input | `out / in` | generated per **fresh** prompt token. With a cache-heavy agent, `in` is tiny, so this number is large and not very meaningful on its own. |
+| Output / prompt sent | `out / (in + cr + cw)` | generated per prompt token **actually sent**. This is the honest "prompt-heavy vs output-heavy" measure. |
+| Cache / total | `(cr + cw) / total` | share of all token activity that was cache traffic |
+| Cache hit rate | `cr / (in + cr)` | share of prompt tokens served from cache rather than re-sent |
+| Fresh per cached prompt | `in / cr` | below 1 means the cache is carrying the context |
+
+## Cost, and what an estimate is allowed to claim
+
+`estimated_cost` + `cost_basis` are the only cost fields, and they mean two different things:
+
+| `cost_basis` | Meaning |
+|---|---|
+| `measured` | a source actually billed this request (a gateway's own `cost_usd`) |
+| `estimated` | computed here, from a published rate table |
+| `null` | the model has no configured rate — **and no number is shown** |
+
+Three things make the estimate defensible rather than decorative:
+
+1. **Every rate names a source.** Each entry in the built-in table carries a `src` key into
+   `PRICING_SOURCES`, which records the URL, the date it was fetched, and whether the source is
+   official or third-party. `tokenflow pricing --sources` prints it; the Cost page shows it.
+2. **Service tier is a multiplier, not a label.** OpenAI's Fast mode (renamed from "priority" on
+   2026-07-30) bills at **4x** standard; Anthropic's Batch API at 0.5x. `service_tier` is a
+   first-class field and a cube dimension, and the multiplier is applied per request. Ignoring it
+   under-reports a Fast-mode-heavy workload by up to 4x.
+3. **The cache write tiers are priced separately.** `cache_refresh_tokens` (the long-TTL subset) is
+   billed at the 1-hour rate and the remainder at the 5-minute rate — for Claude Opus 5 that is
+   $10 vs $6.25 per MTok, so on a cache-heavy workload the split is worth real money.
+
+**Known gap, stated rather than hidden:** long-context premium tiers (Anthropic above 200K,
+OpenAI's long-context rows) are *not* applied, because doing so needs a per-request prompt size
+plus a per-model threshold and premium that are not uniformly published. A long-context-heavy
+workload is therefore **under**-estimated, and the Cost page says so.
+
+## Measurement kinds
+
+| `measurement` | Meaning | Counted in token totals? |
+|---|---|---|
+| `primary` | authoritative per-request usage from the model API | yes |
+| `overlay` | a second view of traffic a client adapter already recorded (gateway/proxy logs) | **no** by default — it would double count. Used for measured cost. |
+| `activity` | AI activity with no token accounting at all (IDE edits, sessions without a usage block, commits) | never — activity and correlation only |
+
+Both non-primary kinds are toggleable in the filter bar, and the Data Health page explains each
+one in place.
+
+## Provider vs gateway
+
+A local proxy or router is **not** a model vendor. When Codex reports
+`model_provider: "headroom"`, the record gets `gateway: "headroom"` and `provider: "openai"` —
+the vendor is derived from the model string, which is the only real evidence of who made the
+model. This keeps "who served this request" and "who built this model" as separate, filterable
+dimensions, and lets you answer "how much of my OpenAI traffic goes through the proxy?".
+
+A provider hint from a source **never** overrides evidence in the model name.
+
+## Interface classification
+
+`interface` is derived **only** from an explicit surface field in the source record — `entrypoint`,
+`originator`, `source`, an IDE marker, a client name. It is never inferred from the model or the
+provider: "it's a Claude model so it must be Claude Desktop" is exactly the mistake this rule
+exists to prevent. With no signal, the value is `Unknown` and the UI says what share that is.
+
+`interfaceClass()` groups the eight values into the four buckets the CLI-vs-GUI comparison uses:
+`CLI / headless` (CLI, SDK), `IDE` (IDE, Extension), `Desktop / Web`, `API`.
+
+## Time and timezone
+
+`date`, `hour` and `dow` are resolved **once at ingest**, in the capture timezone
+(`config.timezone`, defaulting to the machine's zone), and stored. The UI never re-derives them,
+so "my peak hour" means your local peak hour and a late-evening UTC event is filed on the right
+local day. `dow` is Monday-first (0=Mon), matching how the charts are labelled.
+
+## Dedup and identity
+
+`id` is a stable 64-bit hash of `(source, session, request||timestamp, model, sequence)`.
+
+Dedup is **structural**, not probabilistic: ingest resumes at a per-file byte offset, so a byte is
+never read twice and a record cannot be ingested twice. That is why the Data Health page can state
+`Duplicate records: 0` as a fact about the design rather than an estimate. Streaming duplicates
+*within* a source file are a different problem, solved inside each adapter — see
+[providers.md](providers.md).
+
+## Storage layout
+
+```
+data/records/YYYY-MM.jsonl   request-level facts, short-key codec, nulls omitted
+data/cube.json               pre-aggregated fact table (dims + measures), what the browser loads
+data/sessions.json           one row per session
+data/activity.json           daily work-activity rollup (commits, churn, AI edits)
+data/state.json              per-file {size, mtime, offset, gen} — the incremental engine
+```
+
+The cube's dimensions are `date, hour, dow, provider, model, model_family, client, interface,
+gateway, project, repository, measurement`; its measures are the six token fields plus
+`requests`, `cost`, `costMeasured`, `costReq` and the four not-available counters. It is
+**additive**, which is what lets an incremental refresh update it without a rebuild.
+
+Set `store.keepRaw: false` to skip the request-level shards entirely — the cube, sessions and the
+whole dashboard still work; only the Data Explorer and full CSV export need the raw facts.
+
+## Multi-user readiness
+
+`user`, `machine` and `session_id` are first-class fields, and `project` / `repository` are
+dimensions. A future team deployment can aggregate the same records across machines without a
+schema change. V1 deliberately ships no server-side identity, auth or sync — but nothing here
+makes those impossible to add later.

package/docs/getting-started.md

@@ -0,0 +1,266 @@
+# Getting started
+
+## Requirements
+
+- **Node 22.5 or newer.** 22.5 is where `node:sqlite` and the built-in test runner landed; both
+  are used. Check with `node -v`.
+- Nothing else. This project has **zero runtime dependencies** — `npm install` does nothing and
+  is not required.
+
+## Install
+
+**macOS, from a DMG:** download `TokenFlow-<version>.dmg` from the
+[latest release](https://github.com/vimoxshah/tokenflow/releases/latest), open it, drag
+**TokenFlow.app** to Applications, launch from Launchpad. The app builds and launches everything
+it needs — refresh, watcher, dashboard. It is unsigned and not notarized, so macOS shows a
+security warning on first launch:
+
+1. If launch is blocked with *"Apple cannot check it for malicious software"*:
+   open **System Settings → Privacy & Security**, scroll to **Security**, click
+   **Open Anyway** next to the blocked-app message, then confirm **Open**.
+2. Alternatively right-click `TokenFlow.app` → **Open** → **Open**.
+
+This one-time approval is needed because the project has no paid Apple Developer signature;
+the app runs entirely locally either way.
+
+The DMG is produced by [`scripts/build-dmg.sh`](../scripts/build-dmg.sh) and attached to releases
+automatically by [`.github/workflows/release.yml`](../.github/workflows/release.yml). Releases
+also carry `tokenflow-dashboard-demo.html` — a fully offline demo dashboard you can open in any
+browser without installing anything.
+
+**From source (all platforms):**
+
+```bash
+git clone <this repo> tokenflow
+cd tokenflow
+node bin/tokenflow.js --help
+```
+
+To get a global `tokenflow` command:
+
+```bash
+npm link          # or: npm i -g .
+tokenflow --help
+```
+
+Everything below works either way; `npm run <script>` wrappers exist for `setup`, `refresh`,
+`status`, `dashboard`, and `demo`. The bare `tokenflow <command>` examples throughout this doc
+assume the global command from `npm link`; otherwise substitute
+`node bin/tokenflow.js <command>` or the matching `npm run` script.
+
+## 1. Look around first (optional)
+
+```bash
+npm run demo
+```
+
+Generates deterministic synthetic data and opens the dashboard. Every demo record is flagged, and
+the dashboard shows a red **DEMO DATA** banner for as long as any of it is in scope, so it can
+never be mistaken for your own usage. To clear it later:
+
+```bash
+tokenflow provider remove mock
+tokenflow refresh --full
+```
+
+## 2. Detect your tools
+
+```bash
+tokenflow setup
+```
+
+```
+Tokenflow — setup
+config home: /Users/you/.tokenflow
+
+  ✓ Anthropic (Claude Code / Agent SDK)      ~/.claude, ~/.claude-work
+  ✓ OpenAI (Codex CLI / IDE / Desktop)       /Users/you/.codex
+  ✓ Cline CLI                                22 session directories · no token fields reported
+  ✓ Cursor (AI code activity)                activity source — AI-authored edits + commits
+  ○ Headroom gateway (overlay)               No ~/.headroom/savings_events.jsonl found
+  ○ Git activity (correlation)               no repositories found — set sources.git.scanRoots
+
+✓ wrote /Users/you/.tokenflow/config.yaml
+```
+
+`setup` only writes config. It reads no usage data yet.
+
+**Nothing detected?** That is a normal answer, not a failure. Either the tools store their logs
+somewhere non-standard (point at it: `sources.<id>.paths`), or you want
+[`tokenflow import`](cli.md#import) for an export file, or `tokenflow demo` to explore.
+
+## 3. Ingest
+
+```bash
+tokenflow refresh
+```
+
+```
+  ✓ anthropic    44,820 new records · 5,110 files read, 0 unchanged of 5,110 found · 1.4 GB
+  ✓ openai        4,460 new records · 625 files read, 0 unchanged of 625 found · 3.8 GB
+  ✓ cline            22 new records · 22 files read, 0 unchanged of 22 found · 92.2 KB
+  ✓ cursor       12,480 new records
+  ○ git          no repositories found — set sources.git.repos or sources.git.scanRoots
+
+  61,782 new records · 5.2 GB read · 0 files skipped as unchanged · 29s
+```
+
+Run it again and it costs almost nothing — unchanged files are skipped without being read:
+
+```
+  0 new records · 0 B read · 5,757 files skipped as unchanged · 2s
+```
+
+If a first ingest is too big for the time you have, cap it and resume:
+
+```bash
+tokenflow refresh --budget 30    # stop cleanly after ~30s
+tokenflow refresh --budget 30    # continue exactly where it stopped
+```
+
+## 4. Open the dashboard
+
+```bash
+tokenflow dashboard
+```
+
+The server binds to `127.0.0.1` only. The browser downloads one pre-aggregated bundle and then
+does every filter and aggregation locally, so filtering is instant and offline.
+
+Click **↻ Refresh data** any time — it re-ingests, streams progress, and keeps your filters.
+
+### The one-command version
+
+```bash
+npm start            # = tokenflow up
+```
+
+On macOS you can double-click **`Refresh & Open Dashboard.command`** in the project folder
+instead (it is a bash script, so on Windows stay with `npm start`). Either way it refreshes, rebuilds the offline `tokenflow-dashboard.html` beside it, and
+opens the live dashboard. That is the thing to use when you come back after a few days.
+
+The offline file, opened on its own, states how old its data is and looks for a live dashboard on
+loopback; if it finds one it offers to hand over and refresh there. To keep the file current
+without thinking about it, schedule `tokenflow up --no-serve` (see
+[cli.md § up](cli.md#up-alias-open) for a ready-made launchd plist and cron line).
+
+## 5. Pick a look (optional)
+
+Three skins, each with a dark and a light mode. Switch from the header (**◑ Aurora**), or set the
+default:
+
+```yaml
+# ~/.tokenflow/config.yaml
+ui:
+  skin: aurora    # aurora | terminal | editorial
+  mode: dark      # dark | light
+  port: 7799
+```
+
+Series colours belong to the mode, not the skin, and were validated for colour-blind separation
+against every skin's chart surface — so changing the look never changes what a colour means.
+
+Every field is documented in **[configuration.md](configuration.md)** — that is the page to open
+when you want to change something and are not sure what it affects.
+
+## 6. Set the default window (optional)
+
+If your store contains older records you don't normally want in scope:
+
+```yaml
+# ~/.tokenflow/config.yaml
+ui:
+  defaultRange: all       # all | 7d | 30d | 90d | mtd
+  defaultFrom: "2026-03-14"
+```
+
+`defaultFrom` is a floor for the default view, not a filter on the data — everything stays in the
+store and in `--all` exports.
+
+## 7. Turn on cost (optional)
+
+Cost is blank until a model has a price. See what is missing:
+
+```bash
+tokenflow pricing
+```
+
+```
+  MODEL                              TOKENS     STATUS
+  claude-opus-5                      6.35B      no price
+  gpt-5.6-luna                       1.71B      no price
+  claude-3-5-sonnet-20241022         88.1M      priced  $264.30 est.
+```
+
+Add rates in USD per million tokens — `input,output[,cacheRead[,cacheWrite]]`:
+
+```bash
+tokenflow pricing --set "claude-opus-5=15,75,1.5,18.75"
+tokenflow refresh --full          # re-cost the history
+```
+
+Or use the **Pricing** dialog in the dashboard, which lists your models by volume and saves +
+re-costs in one step. Anything you leave blank stays unpriced — the dashboard shows "no price"
+rather than a plausible-looking `$0`.
+
+## 8. Correlate with your actual work (optional)
+
+```yaml
+sources:
+  git:
+    scanRoots: ["~/code", "~/work"]
+    autoFromUsage: true    # also use the working directories seen in usage records
+```
+
+```bash
+tokenflow provider add git && tokenflow refresh
+```
+
+The Productivity page will then correlate daily AI usage with commits, files changed and line
+churn — over the overlapping days only, with `n` reported, and labelled as a correlation. With
+fewer than 10 overlapping days it tells you that instead of showing a number.
+
+## 9. Export
+
+```bash
+tokenflow export --csv                # the current filter
+tokenflow export --csv --all          # everything
+tokenflow export --html               # one self-contained offline dashboard file
+```
+
+## Where everything lives
+
+```
+~/.tokenflow/
+  config.yaml        providers, source paths, preferences
+  pricing.json       your rate overrides
+  mappings/          saved generic-import field mappings
+  providers/         your own adapters (*.js), loaded automatically
+  data/
+    records/         YYYY-MM.jsonl — request-level facts
+    cube.json        the pre-aggregated table the dashboard loads
+    sessions.json    one row per session
+    activity.json    daily work-activity rollup
+    state.json       per-file ingest offsets (this is what makes refresh incremental)
+  cache/
+```
+
+Move it with `TOKENFLOW_HOME=/some/path tokenflow ...`, back it up with
+`tokenflow config export`, and restore with `tokenflow config import`.
+
+## Verify the install
+
+```bash
+npm run validate
+```
+
+Checks the runtime, the config, every adapter's `detect()`, and — importantly — that the
+aggregates still agree with the stored records. If they have drifted, it tells you to run
+`tokenflow compact`.
+
+## Next
+
+- Numbers look wrong? → [troubleshooting.md](troubleshooting.md)
+- Want another source? → [providers.md](providers.md), [creating-provider.md](creating-provider.md)
+- Want an agent to set this up on a new machine? → [skill.md](skill.md)
+- Changing a setting? → [configuration.md](configuration.md)

package/docs/live-mode.md

@@ -0,0 +1,199 @@
+# Live mode — the watcher, the native menu bar app, capacity and alerts
+
+Everything in this document runs **locally**. The watcher reads your logs, the
+menu bar app reads one JSON file, notifications come from your operating
+system. No network client exists anywhere in the codebase.
+
+```
+tokenflow watch  ──every N s──▶  incremental refresh
+        │
+        ▼
+data/status.json   ◀── read by ──▶  TokenFlow.app (native macOS menu bar)
+        │                            tokenflow usage / cost / capacity / forecast
+        │                            tokenflow status --bar
+        ▼                            dashboard header pill + Live tab
+OS notifications (opt-in): limit crossings, same-day high-severity anomalies
+```
+
+## The watcher
+
+```bash
+tokenflow watch              # start; Ctrl+C stops it
+tokenflow watch --interval 30
+tokenflow watch --once       # one cycle and exit — what cron wants
+tokenflow watch --status     # running? how fresh is the data?
+tokenflow watch --stop       # stop a running watcher
+tokenflow watch --notify     # enable OS notifications for this run
+```
+
+Properties that matter:
+
+- **Single instance.** A pidfile guards the store. A crashed run leaves a dead
+  pid behind; the next start detects it and takes over.
+- **Failure isolation with backoff.** A failing refresh doubles the interval,
+  up to a 15-minute ceiling, and records `lastError` in the status file
+  instead of crashing or spamming.
+- **Sleep/wake is free.** Each tick reschedules from wall-clock reality, so a
+  laptop that slept for three hours wakes to exactly one refresh, never a
+  catch-up burst.
+- **Honest freshness.** Every surface recomputes "stale?" at *read* time from
+  `lastRefresh`, against `watch.staleAfterSeconds` (default 600). Old data
+  says so; nothing silently pretends to be real-time.
+
+Defaults live in `config.yaml`:
+
+```yaml
+watch:
+  intervalSeconds: 120
+  notifications: false     # or pass --notify per run
+  staleAfterSeconds: 600
+```
+
+`tokenflow up` remains the pull-based path (`refresh → snapshot → open`); the
+watcher is the push-based one. They share the same incremental engine and can
+interleave safely — a manual refresh during a watched cycle simply coalesces.
+
+## Capacity & budgets
+
+TokenFlow **never invents vendor quota data** — there is no network client, so
+no screen claims to know what Anthropic or OpenAI think your balance is.
+Instead you declare caps, and the engine evaluates them against measured
+consumption:
+
+```yaml
+limits:
+  - id: anthropic-monthly
+    provider: anthropic      # optional filters: provider | model | project
+    scope: month             # day | week | month  (your local calendar)
+    metric: tokens           # tokens | input | output | requests | cost
+    cap: 120000000           # tokens — or dollars when metric is cost
+    warnAt: 0.8              # optional: when "approaching" starts
+```
+
+For each limit the Live tab and `tokenflow capacity` derive:
+
+| Field | Meaning |
+|---|---|
+| used / remaining | consumption inside the current window |
+| % / bar | fraction of cap consumed |
+| burn/hour | today's pace so far (local wall clock) |
+| burn/day | trailing 7 calendar days, trimmed to dataset coverage |
+| ETA | projected exhaustion at the faster of the two paces |
+| resets in | deterministic countdown to local midnight / Monday / 1st |
+
+Limits evaluate against the whole primary dataset regardless of dashboard
+filters — quota windows are facts about your accounts, not filter states.
+Invalid definitions are reported (`tokenflow capacity --json` → `invalid`),
+never silently dropped. Edit them in the dashboard's **Live → Manage limits**
+or by hand in `config.yaml`.
+
+## Forecasting
+
+`tokenflow forecast` fits a conservative linear trend over the last 14 days
+(minimum 5), reports tomorrow's likely range, next-7-days and month-end totals
+with cost, and states its confidence (high / medium / low) plus sample size.
+Month-to-date is always shown separately from the projection. Thin or volatile
+history degrades confidence honestly instead of producing confident nonsense.
+
+## Anomalies
+
+Detection uses robust statistics (median / MAD, Iglewicz–Hoaglin modified
+z-score ≥ 3.5):
+
+- token, cost and request-volume spikes (and weekday collapses)
+- possible ingestion gaps — a zero weekday between two active days
+- models/providers appearing for the first time this week
+
+Every alert carries its own arithmetic — observed value, trailing median,
+ratio, z-score — so you can check it rather than trust it. Notifications fire
+only for **same-day high-severity** anomalies; history replaying as alerts on
+a first run would be noise, so it doesn't happen.
+
+## Menu bar — TokenFlow.app (native, macOS)
+
+TokenFlow ships its own menu bar application: a ~370 KB native binary compiled
+on your machine from [`menubar/TokenFlow/main.swift`](../menubar/TokenFlow/main.swift)
+with `swiftc` (Xcode Command Line Tools). No Electron, no third-party bar, no
+network. It reads `data/status.json` every 5 seconds and rebuilds its dropdown
+every time it opens.
+
+```bash
+tokenflow menubar --app             # build → ~/Applications/TokenFlow.app → launch
+tokenflow menubar --app --login-item
+                                    # …and start it on every login
+```
+
+**Status item (adaptive, most-urgent signal wins):**
+
+| Situation | Menu bar shows |
+|---|---|
+| a limit exceeded | `✗ 105%` in red |
+| a limit approaching | `▲ 82%` in orange |
+| healthy limit | `● 42%` in green |
+| no limits, priced usage | `$4.83` |
+| unpriced day | today's tokens |
+
+**The dropdown contains everything — no browser hop required:**
+
+- header: live/watcher badge + data freshness ("live · data updated just now")
+- Today / Week / Month rows — tokens, requests, estimated cost
+- Today by provider — inline share bars (▰▱), tokens and cost per provider
+- Today by source — the app that wrote the log (claude-code, opencode,
+  hermes, git…). Provider attribution names the model's vendor, so Hermes
+  traffic appears under each model's vendor there; this section shows it as
+  "hermes"
+- Top models today — token and cost leaders per model
+- Capacity — a real meter per declared limit with %, exhaustion ETA and reset
+  countdown; "first projected hit" callout when one will cross before reset
+- Forecast — tomorrow / 7-day projections, month-end spend, confidence
+- Alerts — high-severity anomalies with their arithmetic
+- Actions — `Refresh now` (⌘R, runs a watch cycle), `Open Dashboard`,
+  `Start/Stop watcher`, `Quit`
+- Appearance button (◐) — cycles system → light → dark; persisted across
+  launches in `defaults` under `appearanceOverride`
+
+Dark/light follows the appearance override (◐ button, persisted) or the system
+appearance when set to follow; all figures use monospaced digits.
+
+## Menu bar — other platforms (SwiftBar/xbar text protocol)
+
+For Linux bars or if you prefer SwiftBar on macOS:
+
+```bash
+tokenflow menubar --swiftbar          # install for SwiftBar (~/Library/Plugins)
+tokenflow menubar --xbar              # xbar's plugin directory instead
+tokenflow menubar --out <dir>         # any compatible bar
+tokenflow menubar --render            # print the text protocol (debug)
+tokenflow menubar --mode cost         # auto | tokens | cost | limit
+```
+
+The generated script shells to `tokenflow menubar --render` every couple of
+minutes (filename convention). The title adapts automatically — the most
+urgent signal wins:
+
+| Situation | Title shows |
+|---|---|
+| a limit approaching | `TF ⚠ anthropic-monthly 82% · 4h 12m` |
+| a limit exceeded | `TF ✗ anthropic-monthly 105% · resets 3d` |
+| no limits, priced usage | `TF $4.83` |
+| unpriced day, week has data | `TF 7d 5.04B` |
+
+Any bar speaking the same text protocol (Argos, Waybar custom modules) works
+via `--out`.
+
+The SwiftBar dropdown carries the same breakdowns as the native popover:
+today/week/month totals, **by source** (claude-code, hermes, opencode… —
+provider rows name each model's vendor, so this is where Hermes appears under
+its own name), **top models**, limits, forecast and alerts. Appearance is the
+one thing a text-protocol plugin cannot control: SwiftBar renders plain text,
+so its light/dark look follows SwiftBar's own settings — use the native app's
+◐ button for an in-app toggle.
+
+## Data flow guarantees
+
+- `data/status.json` is written atomically (tmp + rename). A reader never sees
+  a half-file; a corrupt file degrades to "recompute fresh".
+- Estimated and measured cost stay separate everywhere, including the bar line
+  and the dropdown.
+- A one-shot cycle (`--once`) never leaves the file claiming a watcher is
+  running; liveness is verified against the pid, not assumed.