@vimoxshah/tokenflow 1.1.0

package/docs/architecture.md

@@ -0,0 +1,193 @@
+# Architecture
+
+```
+Data sources            ~/.claude*  ~/.codex  ~/.cline  ~/.cursor  ~/.headroom  git  *.csv
+      │
+      ▼
+Ingestion layer         src/providers/*/index.js        ← adapters PARSE, nothing else
+      │                 src/core/registry.js            ← discovery + contract validation
+      ▼
+Normalization layer     src/core/ingest.js  (enrich)    ← classify, date, price, id, dedup
+      │                 src/core/schema.js              ← the unified record + null contract
+      ▼
+Store                   src/core/store.js
+      │                   data/records/YYYY-MM.jsonl      request-level facts
+      │                   data/cube.json                  additive pre-aggregate
+      │                   data/sessions.json               one row per session
+      │                   data/activity.json               daily work rollup
+      │                   data/state.json                  per-file offsets (incremental engine)
+      ▼
+Analytics engine        src/analytics/*.js              ← pure, no Node imports
+      │                   computeView(bundle, filters)    the single entry point
+      ▼
+Live intelligence       src/analytics/{forecast,anomalies,capacity}.js
+      │                 (pure too — same modules in CLI, server and browser)
+      ▼
+Live snapshot           src/core/live-status.js         data/status.json
+      │                   written by `tokenflow watch` (src/core/watch.js),
+      ▼                   read by menu bar / --bar commands / dashboard pill
+Filtering / aggregation in-process, in the browser      ← zero API calls per filter change
+      │
+      ▼
+Dashboard UI            src/ui/{index.html,app.js,charts.js,styles.css}
+      │
+      ▼
+Export                  src/export/{csv.js,html-snapshot.js,bundler.js,menubar.js}
+```
+
+## Layer boundaries, and why they hold
+
+**Adapters parse; the engine enriches.** An adapter emits a partial record and nothing else. The
+engine does model→vendor classification, interface classification, timezone resolution, cost
+estimation, id assignment, dedup bookkeeping, and every rollup. That is why an adapter is ~80
+lines and why adding one cannot change how anything is counted.
+
+**Analytics are pure and Node-free.** `src/analytics/*` imports only from `src/core/schema.js` and
+`src/core/pricing.js` — no `fs`, no `path`. That is what lets the **exact same modules** run in the
+CLI, in the API, and in the browser. There is no "backend calculation" and "frontend calculation"
+to drift apart: `tokenflow status` and the dashboard cannot disagree, because they call the same
+function.
+
+**No logic in UI components.** `src/ui/app.js` renders `computeView()` output. It contains no
+arithmetic beyond formatting. Every number on screen has a named function behind it —
+`calculateDailyUsage`, `calculateProviderUsage`, `calculatePeakUsage`,
+`calculateAverageUsage`, `calculateCacheRatio`, `calculateUsageTrend`, `calculateHourlyUsage`,
+`calculateInterfaceUsage`, `calculatePeriodComparison`, `calculateCorrelations`,
+`generateInsights` — and each is unit-tested against its formula.
+
+## The live layer keeps the same discipline
+
+`forecast.js`, `anomalies.js` and `capacity.js` import nothing from Node —
+they are analytics like any other, so `tokenflow forecast`, the Live tab and
+the menu bar literally cannot disagree. Wall-clock facts enter as arguments
+(`today`, `nowMs`, timezone offset), which is what makes reset countdowns
+testable and identical across surfaces. The watcher (`src/core/watch.js`) is
+the only writer of `data/status.json`; it is single-instanced per data home,
+backs off exponentially on failure, and never lets one bad provider stop the
+loop. Staleness is a property of *reading*, not of writing: every consumer
+recomputes it against the current clock.
+
+## Why a cube
+A dashboard that filters must either round-trip to a server on every interaction or hold the data
+locally. Holding a million request-level records in a browser tab is not viable; holding a
+pre-aggregated fact table is.
+
+```
+dims:     date, hour, dow, provider, model, model_family, client,
+          interface, gateway, project, repository, measurement
+measures: in, out, cr, cw, cf, rs, req, cost, costMeasured, costReq,
+          naIn, naOut, naCr, naCw
+```
+
+Properties that matter:
+
+- **Additive.** An incremental refresh adds into cells; no rebuild needed. This is what makes a
+  2-second no-op refresh possible on a multi-gigabyte corpus.
+- **Small.** Real cardinality on a heavy 8-month corpus of 69,520 records: **2,470 rows**. The whole
+  bundle, including 4,359 sessions, is a few hundred KB.
+- **Complete for every question the UI asks.** Every filter dimension is a column, so any
+  combination of filters is one linear scan — microseconds, in the browser, offline.
+- **Honest.** The four `na*` counters travel with the measures, so "not reported" survives
+  aggregation instead of being flattened into a zero.
+
+Request-level facts stay on disk for the Data Explorer and full CSV export, streamed and filtered
+server-side with a bounded top-K buffer so a 100-row page never materialises a million objects.
+
+## Why incremental refresh is exact
+
+Session transcripts are append-only, so `state.json` remembers each file's
+`{size, mtimeMs, offset, gen}`:
+
+| Observation | Action |
+|---|---|
+| same size **and** mtime | skip entirely — zero reads |
+| grew | resume reading at `offset`; ingested bytes are never re-read |
+| shrank / rewritten | bump `gen`; the old generation's records become stale |
+
+Dedup is therefore **structural**, not probabilistic — there is no hash index to size, tune or
+outgrow, and "duplicate records: 0" is a property of the design rather than a measurement.
+
+Two refinements make it airtight:
+
+1. `readLines` returns the offset of the last **complete** line, so a partially-written trailing
+   line is never consumed.
+2. An adapter whose logical unit can straddle EOF (a streaming message, an in-flight turn)
+   persists what it already emitted in `ref.state`, and emits only the **delta** when the unit
+   continues. Without this, every settled file silently lost its last record forever — which is
+   exactly the bug this mechanism was built to fix.
+
+A scoped `--full` (one adapter) marks that adapter's generations stale, re-ingests, compacts the
+shards, and rebuilds the aggregates from the surviving facts — so one adapter can be re-read from
+scratch without disturbing any other adapter's numbers. A test asserts three consecutive scoped
+re-ingests leave the totals unchanged.
+
+## Time budget and resumability
+
+`refresh({ deadlineMs })` checks the clock on every file boundary, persists state, and returns
+`done: false`. The CLI, the HTTP endpoint and CI all use the same path. This is what lets a 5 GB
+first ingest complete inside 45-second shells, or a browser request, without ever leaving the
+store in a half-written condition.
+
+## Plugin points
+
+Four extension seams, none of which require touching the core:
+
+| Extend | How | Discovered from |
+|---|---|---|
+| **Sources** | `createProvider({...})` | `src/providers/*/index.js`, `$TOKENFLOW_HOME/providers/*.js` |
+| **Metrics** | `registerAnalytics({id, compute})` | result appears at `view.plugins.<id>` |
+| **Model → vendor** | `modelMappings:` in config | prepended to the built-in ruleset |
+| **Prices** | `pricing.json` / `tokenflow pricing --set` | overrides the built-in table |
+
+A user adapter shadows a built-in with the same id, which makes local experimentation cheap and
+reversible.
+
+## Zero dependencies, on purpose
+
+Not minimalism for its own sake — three concrete properties:
+
+- **It installs and runs where a package manager can't.** Sandboxes, air-gapped machines, and
+  short-lived shells with no network. A tool for auditing your own data should not need to phone
+  a registry first.
+- **There is no supply chain.** A dashboard that reads your session logs is exactly the wrong
+  place for 400 transitive packages.
+- **There is no build step in the dev path.** The browser imports the same ES modules the CLI
+  does, straight from `src/`. Edit, reload, done.
+
+The cost is a hand-written SVG chart library (`src/ui/charts.js`, ~800 lines) and a ~100-line
+ES-module bundler used *only* for the offline HTML snapshot. Both are honest trades. `node:sqlite`
+covers SQLite sources; `node:test` covers testing.
+
+The snapshot bundler keeps each module in its own function scope and wires exports through a tiny
+require registry, rather than renaming identifiers — which is where naive concatenating bundlers
+break. `buildSnapshot` parses the result with `vm.Script` before writing, because a snapshot that
+doesn't parse is worse than a failed export.
+
+## Charts
+
+`src/ui/charts.js` implements the mark specs directly: thin marks, hairline solid gridlines, a 2px
+surface gap between touching fills, a 2px surface ring on overlapping markers, selective direct
+labels, hit targets larger than the marks, and a crosshair that snaps to the nearest X.
+
+Colour is assigned **by entity, in fixed order, never by rank**, so filtering a series out never
+repaints the survivors. Past eight keys everything folds into one muted "Other" rather than
+generating a ninth hue. Scatter and bubble forms cap colour groups at three, because they need
+all-pairs colour separation rather than adjacent-pair. Both palettes (dark primary, light
+selected) were checked against the lightness band, chroma floor, adjacent-pair CVD separation,
+normal-vision floor and surface contrast before being written down.
+
+Every chart ships a **table twin** toggled per card, so no value is reachable only by hovering.
+
+## Privacy by construction
+
+There is no HTTP client anywhere in this codebase — not for telemetry, not for pricing, not for
+updates. The server binds to loopback and refuses non-GET requests from a foreign origin without a
+token. Adapters read token counts and metadata and discard content; the schema has nowhere to put
+a prompt. SQLite sources are read from a temp snapshot so a live editor is never disturbed.
+
+## Team-readiness without team infrastructure
+
+`user`, `machine`, `session_id`, `project` and `repository` are first-class, and the cube is
+additive — so cubes from several machines can be merged by concatenating rows and re-summing
+duplicated dimension tuples. V1 ships no identity, auth or sync, deliberately. Nothing here makes
+them impossible to add.

package/docs/cli.md

@@ -0,0 +1,390 @@
+# CLI reference
+
+```
+tokenflow <command> [flags]
+```
+
+Every command is safe to run repeatedly, writes only inside `$TOKENFLOW_HOME` (default
+`~/.tokenflow`), and makes no network requests.
+
+Global flags: `--json`, `--quiet`, `--debug`, `--help`, `--version`.
+
+---
+
+## Getting started
+
+### `setup`
+Runs every adapter's `detect()`, writes `config.yaml` with what was found, and sets the timezone
+and identity. Reads no usage data. Safe to re-run — it refreshes the detected provider list
+without discarding your source paths or pricing.
+
+### `up` (alias: `open`)
+The "I just want to look at it" command, and what `npm start` and the double-clickable
+`Refresh & Open Dashboard.command` both run.
+
+```
+refresh (budgeted, looped until the engine reports done)
+  → rebuild tokenflow-dashboard.html beside it
+  → serve + open the live dashboard
+```
+
+| Flag | Effect |
+|---|---|
+| `--budget <seconds>` | per-pass ingest budget (default 60) |
+| `--passes <n>` | maximum ingest passes before giving up (default 20) |
+| `--no-refresh` | skip the ingest, just rebuild + serve |
+| `--no-snapshot` | skip rebuilding the offline HTML file |
+| `--snapshot <file>` | write the offline file somewhere else |
+| `--port`, `--host`, `--no-open` | passed through to `dashboard` |
+
+**Keeping it fresh unattended.** `tokenflow up --no-serve` does the refresh and rebuilds the
+offline file without starting a server, which is the thing to schedule. macOS (`launchd`), saved
+as `~/Library/LaunchAgents/com.local.tokenflow.plist` and loaded with
+`launchctl load ~/Library/LaunchAgents/com.local.tokenflow.plist`:
+
+```xml
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.local.tokenflow</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/node</string>
+    <string>/path/to/tokenflow/bin/tokenflow.js</string>
+    <string>up</string><string>--no-serve</string>
+  </array>
+  <key>WorkingDirectory</key><string>/path/to/tokenflow</string>
+  <key>StartCalendarInterval</key><dict><key>Hour</key><integer>9</integer><key>Minute</key><integer>0</integer></dict>
+  <key>RunAtLoad</key><false/>
+</dict></plist>
+```
+
+Linux (systemd user timer) or plain cron works the same way:
+
+```cron
+0 9 * * * cd /path/to/tokenflow && node bin/tokenflow.js up --no-serve >/dev/null 2>&1
+```
+
+Windows, with Task Scheduler:
+
+```bat
+schtasks /create /tn "Tokenflow daily" /sc daily /st 09:00 ^
+  /tr "cmd /c cd /d C:\path\to\tokenflow && node bin\tokenflow.js up --no-serve"
+```
+
+### `refresh`
+Ingests new usage. Incremental by default: unchanged files are skipped without being read.
+
+| Flag | Effect |
+|---|---|
+| `--provider <id[,id]>` | only these adapters |
+| `--full` | re-ingest from scratch. With `--provider`, scoped: that adapter's old records are superseded, compacted away, and the aggregates rebuilt — other adapters are untouched. Without `--provider`, everything is reset. Refuses to run if a source that contributed stored records is not reachable right now (see below). |
+| `--force` | with `--full`, proceed even though an unreachable source's records will be dropped and cannot be rebuilt |
+| `--budget <seconds>` | stop cleanly on a file boundary and report `done: false`; run again to continue |
+| `--strict` | validate every record as it is written (slower; use when developing an adapter) |
+| `--quiet` | no progress line |
+| `--json` | machine-readable report |
+
+```bash
+tokenflow refresh
+tokenflow refresh --provider anthropic --full
+tokenflow refresh --budget 30           # then run it again
+```
+
+**Why `--full` can refuse.** A full re-ingest drops the stored records for the sources in
+scope and rebuilds them from the source logs. That is only safe if those logs are reachable.
+Run the same command on another machine, inside a sandbox, or after the log directory has
+moved, and the adapter simply detects as unavailable — an unguarded reset would delete a
+corpus it cannot rebuild. So detection runs *before* anything destructive, and the command
+exits non-zero with the record count at risk and the reason each source is unreachable.
+Fix the path and retry, run an incremental `refresh`, restore from an export, or pass
+`--force` if you really do mean discard.
+
+### `dashboard` (aliases: `serve`, `ui`)
+Starts the local server and opens a browser.
+
+| Flag | Default |
+|---|---|
+| `--port <n>` | `7799` |
+| `--host <addr>` | `127.0.0.1` — loopback only |
+| `--no-open` | don't launch a browser |
+
+### `demo`
+Generates deterministic synthetic data and opens the dashboard. `--days <n>`, `--seed <n>`,
+`--no-dashboard`. Everything it produces is labelled as demo data in the UI.
+
+---
+
+## Everyday
+
+### `status`
+Totals, coverage, composition, peak, cost, data health and the top insights — the same numbers
+the dashboard shows, from the same analytics code. `--json` for scripting.
+
+| Flag | Effect |
+|---|---|
+| `--bar` | print only the one-line menu-bar summary (see `menubar`) |
+| `--mode <m>` | with `--bar`: `auto` (default) / `tokens` / `cost` / `limit` |
+| `--prefix <s>` | with `--bar`: leading label (default `TF`) |
+
+---
+
+### `digest`
+A shareable summary of a usage window, rendered from the same cube as everything else: headline
+tokens/cost/requests, by source, by provider, top models, pace vs your 14-day average, nearest
+capacity limit and any high-severity alerts. Markdown by default; paste it into Slack, an issue,
+or a stand-up note.
+
+```bash
+tokenflow digest                       # last 7 days, markdown to stdout
+tokenflow digest --format text         # plain text
+tokenflow digest --from 2026-08-01 --to 2026-08-07
+tokenflow digest --out week.md        # write instead of print
+```
+
+---
+
+### `providers`
+What is detected, connected, or disabled, with the reason for each. `--json`.
+
+### `provider add|remove|list <id>`
+Enable or disable an adapter in `config.yaml`.
+
+### `export`
+| Flag | Effect |
+|---|---|
+| `--csv [file]` | request-level CSV; default name `tokenflow-usage-YYYY-MM-DD.csv` |
+| `--all` | every record, ignoring filters |
+| `--from` / `--to` / `--provider` / `--model` / `--client` / `--interface` / `--project` | filter the export |
+| `--html [file]` | one self-contained offline dashboard file |
+| `--maxRecords <n>` | records embedded in the HTML snapshot (default 20,000) |
+| `--out <dir>` | output directory when no filename is given |
+
+```bash
+tokenflow export --csv --from 2026-03-14 --provider anthropic
+tokenflow export --csv --all
+tokenflow export --html ~/Desktop/tokenflow.html
+```
+
+Missing values are written as empty cells, never as `0`.
+
+---
+
+## Live
+
+These four read the watcher's snapshot (`data/status.json`) when it is fresh
+and compute on the spot otherwise — so they are fast to run repeatedly and
+always agree with the dashboard.
+
+### `usage`
+Today / yesterday / week-to-date / month-to-date: tokens by bucket, requests,
+sessions, estimated cost, plus today's top providers and models. `--json`
+returns the full slices.
+
+### `cost`
+Estimated vs measured spend for the same windows, today's spend by provider,
+and the month-end projection with its confidence. `--json`.
+
+### `capacity`
+Every configured limit (see [live-mode.md](live-mode.md#capacity--budgets) and
+[configuration.md](configuration.md)): bar, % of cap, burn rate, projected
+exhaustion ETA, reset countdown, sorted most-urgent first. With no limits
+configured it prints the exact YAML to paste instead of pretending to know
+vendor quotas. `--json` includes validation errors for bad definitions.
+
+### `forecast`
+Tomorrow (with likely range), next 7 days, month-end projection, confidence,
+sample size — followed by active anomaly alerts with their arithmetic.
+`--json` returns `{ forecast, anomalies }`.
+
+### `watch`
+The background refresher. One cycle = incremental refresh → rebuild
+`data/status.json` → (opt-in) notify transitions.
+
+```bash
+tokenflow watch                 # every watch.intervalSeconds (default 120)
+tokenflow watch --interval 30   # this run only
+tokenflow watch --once          # single cycle, exit (cron-friendly)
+tokenflow watch --notify        # OS notifications for threshold crossings
+tokenflow watch --status        # running? pid? how fresh is the data?
+tokenflow watch --stop          # stop a running watcher
+```
+
+Single-instance per data home; failures back off exponentially (15-minute
+ceiling) and land in `lastError`. See [live-mode.md](live-mode.md).
+
+### `menubar`
+Menu bar surfaces. On macOS the primary is **TokenFlow's own native app**:
+
+```bash
+tokenflow menubar --app               # build TokenFlow.app (swiftc), install
+                                      # to ~/Applications and launch it
+tokenflow menubar --app --login-item  # also add it to Login Items
+```
+
+The app shows an adaptive status item (limit % with state color > today's
+cost > today's tokens). Its dropdown carries today/week/month usage, a
+per-provider breakdown, capacity meters with reset countdowns and ETAs, the
+forecast with confidence, high-severity anomaly alerts, freshness/watcher
+badges, and Refresh-now / Open-Dashboard / Start-Stop-watcher actions.
+
+Cross-platform text protocol for other bars:
+
+```bash
+tokenflow menubar --render            # print xbar/SwiftBar-format text
+tokenflow menubar --swiftbar          # install into ~/Library/Plugins
+tokenflow menubar --xbar              # install into xbar's plugin dir
+tokenflow menubar --out <dir>         # any compatible bar's plugin dir
+tokenflow menubar --mode <m>          # auto | tokens | cost | limit
+```
+
+Requires `swiftc` for `--app` (`xcode-select --install` provides it).
+
+---
+
+## Configure
+
+### `pricing`
+With no flags: every model in the store, its token volume, estimated cost, effective $/1M, and
+which source its rate came from.
+
+```bash
+tokenflow pricing
+tokenflow pricing --sources                               # provenance + tier multipliers
+tokenflow pricing --set "claude-opus-5=5,25,0.5,6.25"     # input,output[,cacheRead[,cacheWrite]]
+tokenflow pricing --unset claude-opus-5
+```
+
+Rates are USD per 1,000,000 tokens. Run `tokenflow refresh --full` afterwards to re-cost history.
+Anything left unpriced shows as "no price", never as `$0`.
+
+`--sources` prints, for every group of built-in rates, the URL it was taken from, the date it was
+fetched, and whether the source is official or third-party — plus the service-tier multipliers
+that get applied per request, and the one premium tier that is deliberately *not* applied
+(long-context).
+
+### `import <file>`
+Generic import for CSV / TSV / JSON / JSONL / SQLite. With no `--field` flags it prints the
+columns it found, infers a mapping, and previews five normalized rows.
+
+| Flag | Effect |
+|---|---|
+| `--name <n>` | mapping name (default: the filename) |
+| `--format csv\|tsv\|json\|jsonl\|sqlite` | override detection |
+| `--table <t>` / `--query <sql>` | SQLite source |
+| `--field <schemaField>=<column>` | repeatable |
+| `--default <field>=<value>` | repeatable, e.g. `--default client=openrouter` |
+| `--timestamp-format iso\|epoch_ms\|epoch_s` | |
+| `--dry-run` | preview only, save nothing |
+
+```bash
+tokenflow import ~/Downloads/usage.csv --dry-run
+tokenflow import ~/Downloads/usage.csv --field timestamp=created_at --field input_tokens=prompt_tokens
+```
+
+### `restore <file.csv>`
+Rebuilds the store from a full export (`tokenflow export --csv --all`) and re-prices every
+*estimated* cost with the current price table. Measured costs — a gateway's own billing
+numbers — are preserved verbatim and never re-estimated.
+
+| Flag | Effect |
+|---|---|
+| `--yes` | required when the store already holds records; a restore replaces the dataset |
+| `--no-reprice` | keep the costs exactly as exported |
+
+```bash
+tokenflow export --csv --all             # on the machine that has the logs
+tokenflow restore tokenflow-usage-2026-08-20.csv --yes
+```
+
+Three reasons to reach for it:
+
+- **portability** — move a dataset between machines, or into a team roll-up, without
+  shipping the vendors' raw session logs. The CSV holds counts and identifiers; prompts,
+  conversations and source code never leave the machine that produced them.
+- **recovery** — rebuild after the source logs have been rotated, pruned, or moved.
+- **re-pricing** — apply a price-table update to all of history without re-reading
+  gigabytes of logs.
+
+What restore cannot recover: per-record `metadata` (working directory, streaming audit
+trail, price provenance) is not part of the CSV contract. Restored records carry
+`metadata.restored_from` instead.
+
+A restored slice is provisional. The next `refresh` that actually reaches a source's logs
+marks the restored records for that source stale, compacts them away and rebuilds the
+aggregates — so a restore and a real re-read can never be double counted.
+
+### `config show|path|export|import`
+```bash
+tokenflow config show                    # effective config as YAML
+tokenflow config path                    # the data home
+tokenflow config export backup.json      # config + pricing + mappings (no usage data)
+tokenflow config import backup.json      # restore on another machine
+```
+
+---
+
+## Maintain
+
+### `doctor`
+Runtime, `node:sqlite` availability, timezone, every path, store size, cube rows, sessions,
+pending compaction, and every adapter's detection status. Start here when something is off.
+
+### `validate`
+Re-validates every stored record against the schema and reports the failure modes by frequency.
+Exits non-zero if anything is invalid.
+
+### `compact`
+Rewrites the record shards without superseded generations and rebuilds the aggregates. Normally
+automatic after a scoped `--full` or after a restored slice is superseded; run it manually if
+`doctor` reports pending stale generations.
+
+| Flag | Effect |
+|---|---|
+| `--recount` | rebuild and re-derive the record counts even when there is nothing to compact |
+
+Record counts in `state.json` accumulate as records are ingested. After a restore, a scoped
+re-ingest, or a compaction they are re-derived from the records that actually survived — so the
+stored count is the store's real size, not a lifetime total. `--recount` forces that derivation
+on demand.
+
+### `reset --yes`
+Deletes ingested data. Config, pricing and mappings are kept.
+
+---
+
+## npm script wrappers
+
+```bash
+npm run setup       npm run refresh     npm run status
+npm run dashboard   npm run demo
+npm test            npm run lint        npm run typecheck   npm run validate
+```
+
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `TOKENFLOW_HOME` | data + config directory (default `~/.tokenflow`) |
+| `TOKENFLOW_DEMO=1` | enable the mock provider |
+| `CLAUDE_CONFIG_DIR` | extra Claude Code home(s) for the anthropic adapter |
+| `CODEX_HOME` | extra Codex home for the openai adapter |
+| `NO_COLOR` | plain output |
+
+## Exit codes
+
+`0` success · `1` a command failed, or `validate` found invalid records.
+
+## Scripting
+
+`--json` on `refresh`, `status` and `providers` emits machine-readable output:
+
+```bash
+tokenflow refresh --json | jq '.newRecords, .done'
+tokenflow status --json  | jq '.health.grade, .meta.coverage'
+tokenflow providers --json | jq '.[] | select(.available) | .id'
+```
+
+A nightly refresh needs nothing more than:
+
+```cron
+17 3 * * *  cd ~/tokenflow && node bin/tokenflow.js refresh --quiet
+```