@vimoxshah/tokenflow 1.1.2 → 1.2.0

package/docs/ledger.md

@@ -0,0 +1,144 @@
+# The Ledger — team cost per branch and per merged PR
+
+The Ledger joins everyone's local branch-cost receipts (`src/analytics/receipt.js`)
+across every machine that syncs, so a team lead can see "what did this branch
+cost" and "what did merged PRs typically cost" without anyone reading anyone
+else's session transcripts. It rides the same file sync as the rest of
+`tokenflow sync` / `tokenflow team` — see [`configuration.md`](configuration.md)
+for the `sync:` block and [`team-server.md`](team-server.md) if you push to a
+self-hosted server instead of a shared folder.
+
+Two files travel per machine, both written by `sync.push()`
+(`src/core/sync.js`):
+
+| file | shape | conflict rule |
+| --- | --- | --- |
+| `<machineId>.jsonl` | one line per day, coarse tokens/requests/cost | append-only, last-write-wins per line |
+| `<machineId>.receipts.json` | one entry per (repo, branch) this machine has session history for | whole-state, last-write-wins |
+
+The second file is the Ledger's input. It is written on every push unless you
+set `sync.receipts: false`.
+
+## What leaves the machine
+
+Per branch, exactly these fields — nothing else:
+
+| Field | Meaning |
+| --- | --- |
+| `repo` | The repository's name — **basename only**, never a path. |
+| `branch` | The branch name. |
+| `costUsd` | Estimated spend on this branch (`null` if nothing was priced — never `0`). |
+| `turns` | LLM requests attributed to this branch. |
+| `sessions` | Distinct sessions that touched it. |
+| `subagentTurns` | Of `turns`, how many ran as a subagent. |
+| `contextShare` | Share of `costUsd` that re-sent prior context vs. fresh work. |
+| `first` / `last` | ISO timestamps bounding the branch's activity. |
+| `longLived` | True for `main` / `staging` / `develop`-style names — this is a receipt for a period of work, not one change. |
+| `pr` | `null`, or `{ number, mergedAt }` for the PR this branch shipped in. |
+
+The whole file also carries `schema` (currently `1`), `machineId`,
+`generatedAt`, and — **only if you set `sync.machineName` yourself** —
+`machineName`. Unlike the daily jsonl (which always falls back to the
+hostname), the ledger stays anonymous by default: it joins branch and PR
+identity, which is more identifying than a coarse daily total, so machine
+labelling here is opt-in on top of opt-in.
+
+Never included, at any level: file paths, commit hashes, PR titles, diffs or
+line counts, prompts, or any model/code text. The data comes entirely from
+`buildReceiptsForStore()` (`src/core/bundle.js`) — this module does not
+re-derive cost or open a session transcript itself.
+
+**Known gap:** `buildReceiptsForStore()` has no PR source wired in yet (PR
+matching today only happens through `tokenflow receipt --gh`, a separate CLI
+path). That means `pr` is `null` on every real push right now. The field
+exists so a future cached PR list needs no format change — `perMergedPr` and
+the `mergedPrCount` in `byMonth` will be empty until that lands.
+
+## Sending it to a server instead of a folder
+
+```yaml
+sync:
+  enabled: true
+  to: https://team-box.example.com     # or your self-hosted `tokenflow team serve`
+  token: <shared-secret>               # or set TOKENFLOW_SYNC_TOKEN in the env
+```
+
+With `sync.to` set, `push()` POSTs the exact same two files' text to
+`<to>/api/rollup` as `{ machineId, files: { "<machineId>.jsonl": "…", "<machineId>.receipts.json": "…" } }`
+with an `Authorization: Bearer <token>` header, instead of writing them into
+`sync.dir`. A non-2xx response is reported as an error with the status line
+only (`sync push to <to> failed: 401 Unauthorized`) — the response body is
+never printed, since a server's error page is not this tool's to surface.
+See [`team-server.md`](team-server.md) for the receiving end's contract
+(path, auth model, file-name allowlist, size cap).
+
+`push()` stays synchronous when writing to a folder (matches every existing
+caller). The moment a destination server is configured it necessarily makes
+a network call, so that branch returns a Promise — `await push(...)` works
+either way.
+
+## The join: `team.aggregate(dir)`
+
+`tokenflow team` (`src/core/team.js`) reads every sibling `*.receipts.json`
+alongside the `*.jsonl` files it already merges for per-developer rows, and
+adds a `receipts` section to its result:
+
+- **`receipts.totals`** — `{ cost, branches, repos }` across every merged
+  (repo, branch).
+- **`receipts.byRepo`** — `[{ repo, cost, branches, sessions }]`, sorted by
+  cost descending.
+- **`receipts.byMonth`** — `[{ month, cost, mergedPrCount }]`, bucketed by the
+  month of each branch's `last` activity, sorted ascending. `mergedPrCount`
+  counts branches in that month whose `pr.mergedAt` is known.
+- **`receipts.perMergedPr`** — `{ median, p90, sampleSize }` cost across
+  branches with a known `pr.mergedAt`. `p90` follows the same convention as
+  `sessionStats()`'s `p90SessionCost` in `receipt.js`: sort branch costs
+  descending, take the value 10% of the way down (10% of branches cost more
+  than this).
+- **`receipts.concentration`** — `{ top10Share, top5 }`: the share of total
+  receipt cost held by the most expensive 10% of branches (at least one
+  branch), and the five most expensive branches as `{ repo, branch, cost }`.
+- **`receipts.longLivedShare`** — `{ cost, share }`: how much of total
+  receipt cost sits on `longLived` branches — work that a PR never bounded,
+  labelled that way because it is a different kind of spend to reason about
+  than a feature branch that shipped and closed.
+
+Merging across machines, per (repo, branch): **sum** `costUsd`/`turns`/
+`sessions`; take the **earliest** `first` and **latest** `last`; keep
+whichever machine's view of the PR **knows a `mergedAt`** (a machine that
+hasn't re-synced since the merge only sees an open PR, or none — the merged
+view wins once any machine has it). `longLived` is true if any machine
+reports it true (the branch-name pattern is deterministic, so this only
+matters for split-second sync races).
+
+Receipts are **not** filtered by the `from`/`to` window `aggregate()` accepts
+for the daily rollup: a receipt is a lifetime-of-the-branch ledger entry, not
+a per-day bucket, so there is no single day to test it against. If a team
+needs a windowed view of the Ledger later, that is a follow-on, not this
+join.
+
+`renderText(aggregate(dir))` prints a "Receipts (branch × PR cost ledger)"
+section using all of the above; with no `*.receipts.json` files synced yet it
+prints one line saying so, rather than an empty table.
+
+## Example
+
+```
+Receipts (branch × PR cost ledger)
+  Total receipt cost   $43.00 across 3 branch(es) in 2 repo(s)
+
+  By repo
+    demo-repo               $23.00    2 branch(es)     4 session(s)
+    other-repo               $20.00    1 branch(es)     3 session(s)
+
+  Cost per merged PR   median $19.00 · p90 $20.00   (n=2)
+  Concentration        top 10% of branches hold 46.5% of receipt cost
+    other-repo/feature-y  $20.00
+    demo-repo/feature-x  $18.00
+    demo-repo/main  $5.00
+  Long-lived branches  11.6% of receipt cost ($5.00) sits on long-lived branches — work not bounded by a PR
+
+  By month
+    2026-07       $20.00   1 merged PR(s)
+    2026-08       $23.00   1 merged PR(s)
+```

package/docs/live-mode.md

@@ -109,6 +109,29 @@ 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.
 
+## Live status: sessions, receipts, guard, sparklines
+
+Alongside the totals above, `data/status.json` carries four sections built from a second,
+record-level scan of the store — the cube the rest of this file describes is pre-aggregated and
+carries no session id, branch, or per-turn guard verdict. All four anchor on `lastRefresh` (the
+store's last completed refresh), never the real clock, so a reader is only ever as current as the
+last refresh cycle said.
+
+| Section | What it carries |
+|---|---|
+| `liveSessions` | Up to 8 sessions with activity in the last 10 minutes of `lastRefresh`: source, model, project/repository/branch, turns, subagent turns, running cost, context tokens and share, and that session's own guard verdict. |
+| `receiptsToday` | The 3 highest-cost (repo, branch) pairs with spend dated `lastRefresh`'s day, plus the total across all of them. |
+| `guard` | The declared thresholds (from `~/.tokenflow/config.yaml`, overridden per repository by `.tokenflow/policy.yaml`) and the last guard verdict, with its `source`: `cache` when a session's own guard cache holds one, `derived` when it is inferred from the worst `liveSessions` entry instead (today the cache stores no verdict, so this is `derived` on every run). |
+| `sparklines` | 24 hourly token/cost buckets per source, covering the 24 hours up to `lastRefresh`. |
+
+### The Live tab
+
+The dashboard's **Live** tab (a registered view, `src/ui/views/live.js`) renders these same four
+sections, polling `/api/live` every 30 seconds while the tab is open. Nothing on it animates
+toward a number it was not given: every value is the last thing `data/status.json` said, and it
+changes only when that file changes. In an offline snapshot the tab shows the numbers captured at
+export time and hides the controls (like "Manage limits") that need a live server.
+
 ## Menu bar — TokenFlow.app (native, macOS)
 
 TokenFlow ships its own menu bar application: a ~370 KB native binary compiled
@@ -137,11 +160,19 @@ tokenflow menubar --app --login-item
 
 - header: live/watcher badge + data freshness ("live · data updated just now")
 - Today / Week / Month rows — tokens, requests, estimated cost
+- **Live, as of `<time>`** — up to 3 sessions active in the last 10 minutes, each with a
+  context gauge, its own guard-coloured dot, and running cost
+- **Today's receipts** — the day's top 3 (repo, branch) pairs by spend, and the total
+- **Guard** — the declared caps, the last verdict, and two buttons: **Raise cost cap** and
+  **Clear caps**, both of which write through `tokenflow guard --set` (never by editing
+  `config.yaml` directly) and then run one refresh cycle so the popover reflects the change
 - 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"
+- **Last 24 hours by source** — a small sparkline per source, tokens and cost, drawn only
+  when its data is present so an older status file shows exactly what it always showed
 - 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
@@ -149,12 +180,21 @@ tokenflow menubar --app --login-item
 - Alerts — high-severity anomalies with their arithmetic
 - Actions — `Refresh now` (⌘R, runs a watch cycle), `Open Dashboard`,
   `Start/Stop watcher`, `Quit`
+- **Density** — Comfortable or Compact, a persisted preference that tightens row spacing
+  and type size for a laptop screen
+- **Shortcut** — a global keyboard shortcut that toggles the popover from any app,
+  persisted and re-registered immediately on change
 - 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.
 
+**Transient guard alert.** When a live session's guard level rises to warn or block since the
+last load, a small card slides in from the status item to announce it — never on the first load,
+and never on a recovery back down, so it only ever interrupts for something new. One card at a
+time; clicking it opens the popover on the section that explains why.
+
 ## Menu bar — other platforms (SwiftBar/xbar text protocol)
 
 For Linux bars or if you prefer SwiftBar on macOS:

package/docs/providers-otel.md

@@ -0,0 +1,179 @@
+# `otel` — OpenTelemetry (GenAI)
+
+A machine sweep of common local coding-agent tools found none that write per-request token
+counts to disk in a proprietary format for several of them — Gemini CLI among them. Several of
+them CAN write [OpenTelemetry](https://opentelemetry.io/) data to a local file, though, so this
+adapter reads that instead: point a tool's OTLP file exporter, or Gemini CLI's own file
+telemetry, at a file this adapter can see, and it becomes a TokenFlow source with zero
+vendor-specific code on the tool's side.
+
+| | |
+|---|---|
+| Reads | `~/.gemini/telemetry.log` (best-effort default — see below) and `~/.tokenflow/otel/*.{jsonl,ndjson,json,log}` |
+| Measurement | `primary` |
+| Reports | `input`, `output`, `cache_read`, `cache_write` (standards-based path only), `reasoning`, session/conversation id, request id (span id), duration, model, provider |
+| Cannot know | interface/surface (no OTel GenAI attribute carries it — every record classifies as `Unknown` unless a resource attribute happens to match a known IDE/CLI name) |
+
+## What actually lands on disk — two shapes, not one
+
+This adapter reads two genuinely different file shapes, and it matters which one a given tool
+produces:
+
+**A. Standards-based OTLP JSON.** A compliant OTLP file exporter (for example the [OpenTelemetry
+Collector's `file` exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib))
+writes the real wire protocol: `resourceSpans[].scopeSpans[].spans[]` or
+`resourceLogs[].scopeLogs[].logRecords[]`, with attributes as
+`[{key, value: {stringValue|intValue|doubleValue|boolValue}}]`. Usage lives under
+`gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` / `gen_ai.usage.cache_read.input_tokens`
+/ `gen_ai.usage.cache_write.input_tokens` / `gen_ai.usage.reasoning.output_tokens`, per the
+[GenAI spans semantic conventions](https://raw.githubusercontent.com/open-telemetry/semantic-conventions-genai/main/docs/gen-ai/gen-ai-spans.md).
+This is the shape any *other* instrumented tool should target if you want it to show up here.
+
+**B. Gemini CLI's own file telemetry.** Verified against Gemini CLI's source
+(`packages/core/src/telemetry/file-exporters.ts`), Gemini CLI does **not** write the OTLP wire
+format to its outfile. Its `FileLogExporter`/`FileSpanExporter` pretty-print
+(`JSON.stringify(record, null, 2)`) the OpenTelemetry JS SDK's own internal `ReadableLogRecord`/
+`ReadableSpan` objects, one JSON value per flush — so a "record" in that file can span many text
+lines, and the file is not, strictly, JSON Lines. This adapter's `ingestFile` scans for balanced
+top-level JSON values by brace/bracket depth (not by newline), so both shapes are read correctly
+from the same file, including a file that is a single JSON document with no line breaks at all.
+
+## Enabling Gemini CLI's file telemetry
+
+Quoting the setting names from Gemini CLI's own docs
+(`docs/cli/telemetry.md`, `GEMINI_TELEMETRY_*` env vars):
+
+```json
+{
+  "telemetry": {
+    "enabled": true,
+    "target": "local",
+    "outfile": ".gemini/telemetry.log"
+  }
+}
+```
+
+in `.gemini/settings.json` (or the equivalent `GEMINI_TELEMETRY_ENABLED=true`,
+`GEMINI_TELEMETRY_TARGET=local`, `GEMINI_TELEMETRY_OUTFILE=...` environment variables). The docs'
+own worked example uses `.gemini/telemetry.log`, a path **relative to the CLI's working
+directory** — the setting has no fixed default (`-` in the settings table until you set it), so
+there is no single home-level location TokenFlow can rely on. This adapter's best-effort default
+looks for `~/.gemini/telemetry.log`, but the reliable setup is either:
+
+- an **absolute** `outfile` path pointed at the drop folder below, or
+- `sources.otel.paths` in your TokenFlow config, pointed at wherever your project's
+  `outfile` actually is.
+
+```yaml
+sources:
+  otel:
+    paths: ["~/code/my-project/.gemini/telemetry.log"]
+```
+
+Gemini CLI logs two records per API call to the same file when telemetry is on: the
+`gemini_cli.api_response` event (all the token fields) and a semantic twin,
+`gen_ai.client.inference.operation.details`, that repeats the same usage under the
+standards-based attribute names. This adapter recognizes the pairing and counts the call once,
+from `gemini_cli.api_response` only.
+
+## Pointing another tool's OTLP file exporter here
+
+Any tool whose OpenTelemetry SDK setup lets you choose a file-based (or a `file://`) exporter for
+traces or logs can use the same drop folder:
+
+```
+~/.tokenflow/otel/<anything>.jsonl
+```
+
+Anything ending in `.jsonl`, `.ndjson`, `.json`, or `.log` under that folder is picked up. Point
+the OTel Collector's `file` exporter, or an OTLP/HTTP exporter aimed at a local static file
+server that happens to append to disk, at a file under that folder, and it becomes a TokenFlow
+source with no code change here — that is the point of reading the standards-based shape.
+
+## Token semantics
+
+**Standards-based (`gen_ai.usage.*`).** Per the GenAI semantic conventions' own notes,
+`gen_ai.usage.input_tokens` is documented to *include* both `cache_read.input_tokens` and
+`cache_write.input_tokens` (the same inclusive convention OpenAI/Codex uses) — this adapter
+subtracts both to get the schema's exclusive `input_tokens`. `reasoning.output_tokens` is
+documented as already included in `output_tokens`, so it is copied through unmodified as a
+subset.
+
+**Gemini's own event.** Verified against
+[the Generate Content API reference](https://ai.google.dev/api/generate-content):
+`promptTokenCount` "is still the total effective prompt size ... includes the number of tokens
+in the cached content" (inclusive of the cache, like the standards-based path), and
+`totalTokenCount` is "prompt + thoughts + response candidates" — three **separate**, additive
+terms. That second fact matters: it means the candidate/output count does NOT already include
+thinking tokens, so to keep `reasoning_tokens` a subset of `output_tokens` (a schema invariant),
+this adapter reports `output_tokens = output_token_count + thoughts_token_count` and
+`reasoning_tokens = thoughts_token_count`.
+
+**Left unverified, on purpose.** Whether `toolUsePromptTokenCount` is already folded into
+`promptTokenCount`, or is additive and simply omitted from the documented `totalTokenCount`
+formula, is not stated anywhere in the sources checked for this adapter. `tool_token_count` is
+therefore recorded only in `metadata` (for a manual audit against `total_token_count`), never
+added into `input_tokens` or `output_tokens`.
+
+## Privacy
+
+OTel GenAI attributes, and Gemini CLI's own events, can carry full prompt/response text
+(`gen_ai.input.messages`, `gen_ai.output.messages`, `response_text`, a human-readable log `body`
+describing the call). This adapter never reads those keys, and never spreads a source record's
+attributes into `metadata` — every metadata field is written one at a time, from an explicit
+allow-list (`model`/`provider`/`operation`/`status`/`session_id`/`conversation_id`, matching this
+product's data-collection rule for OTel sources specifically). Fields present on the source but
+NOT retained include `auth_type`, `finish_reasons`, `installation.id`, and `user.email` — those
+are on the wire, but not on the allow-list, so they are dropped even though nothing forces you to
+turn on `telemetry.logPrompts: false` upstream.
+
+## `docs/providers.md` integration
+
+Row for the provider table (`docs/providers.md` is not edited by this change — see the
+CHANGELOG/report for the exact snippet a maintainer can paste in):
+
+````markdown
+## `otel` — OpenTelemetry (GenAI)
+
+| | |
+|---|---|
+| Reads | `~/.gemini/telemetry.log` (best-effort) and `~/.tokenflow/otel/*.{jsonl,ndjson,json,log}` |
+| Measurement | `primary` |
+| Reports | `input`, `output`, `cache_read`, `cache_write`, `reasoning`, session/conversation id, request id, duration, model, provider |
+| Cannot know | interface/surface (no OTel GenAI attribute carries it) |
+
+Standards-based: point any tool's OTLP file/collector exporter at the drop folder. Gemini-CLI
+specific: enable `telemetry.enabled`/`target: "local"`/`outfile` in `.gemini/settings.json`; see
+[docs/providers-otel.md](providers-otel.md) for the field mapping, the double-count-avoidance
+rule for Gemini's paired events, and the privacy allow-list.
+
+### Configuration
+
+```yaml
+sources:
+  otel:
+    paths: ["~/code/my-project/.gemini/telemetry.log", "~/.tokenflow/otel"]
+```
+
+---
+````
+
+## Tools with no known on-disk usage log (needs a sample)
+
+These tools were not verified for this adapter — either they have no documented local usage
+export, or checking would have required an account/install this task didn't have. If you run one
+of these and can point it at an OTLP file exporter (or find where it already writes per-request
+token counts), a fixture line from a **synthetic** run is what turns this from a guess into a
+supported source.
+
+| Tool | Status |
+|---|---|
+| Aider | No documented on-disk per-request usage log found; Aider prints session totals to the terminal. Needs a sample. |
+| Ollama | No documented usage-log file; token counts are only in the API response body, not persisted. Needs a sample. |
+| LM Studio | No documented on-disk usage log found. Needs a sample. |
+| Zed | Connects to Gemini CLI via ACP (surface tag `zed` per Gemini CLI's telemetry docs) but Zed itself was not checked for its own OTel/usage export. Needs a sample. |
+| Windsurf / Codeium | No documented on-disk usage log found. Needs a sample. |
+| JetBrains AI Assistant | Gemini CLI's ACP integration reports a `jetbrains` surface tag, but the JetBrains plugin's own usage/telemetry export was not checked. Needs a sample. |
+| Continue | No documented on-disk usage log found. Needs a sample. |
+| Copilot CLI | No documented on-disk usage log found. Needs a sample. |
+| Antigravity | No public documentation found for this task; needs a sample or a pointer to its docs. |

package/docs/providers.md

@@ -57,7 +57,7 @@ sources:
 |---|---|
 | Reads | `~/.codex/sessions/**/*.jsonl` and `~/.codex/archived_sessions/**` (`$CODEX_HOME` respected) |
 | Measurement | `primary` |
-| Reports | fresh `input`, `cache_read`, `cache_write`, `output`, `reasoning`, session, thread, turn id, project (from `cwd`), interface (from `source` / `originator`), gateway, reasoning effort, service tier, context window, time-to-first-token, subagent role |
+| Reports | fresh `input`, `cache_read`, `cache_write`, `output`, `reasoning`, session, thread, turn id, project (from `cwd`), git branch and repository (from `session_meta.git`, CLI 0.149+), interface (from `source` / `originator`), gateway, reasoning effort, service tier, context window, time-to-first-token, subagent role |
 | Cannot know | cost; `cache_write` on older CLI builds that never emitted the field (recorded as `null`, not `0`) |
 
 ### Token semantics
@@ -95,6 +95,15 @@ reconstruction is auditable rather than a hidden fudge.
 `model_provider: "headroom"` (or any non-vendor value) is recorded as `gateway`, not as the
 vendor. The vendor comes from the model name.
 
+### Repository identity from `session_meta.git`
+
+Recent CLIs (cli_version 0.149+ observed) include a `git` block on `session_meta`:
+`{ commit_hash, branch, repository_url }`. `branch` becomes `git_branch`; `repository_url` is
+reduced to its basename with any `.git` suffix stripped and becomes `repository`, falling back to
+the cwd basename (same as `project`) when the block is absent — the pre-existing behaviour. Only
+the derived name is kept: the commit hash and the URL itself are never stored, and no message
+content is read.
+
 ---
 
 ## `cline` — Cline CLI
@@ -224,6 +233,50 @@ estimate instead of a single unverifiable number.
 
 ---
 
+## `otel` — OpenTelemetry (GenAI)
+
+| | |
+|---|---|
+| Reads | `~/.gemini/telemetry.log` (best-effort default) and `~/.tokenflow/otel/*.{jsonl,ndjson,json,log}` |
+| Measurement | `primary` |
+| Reports | `input`, `output`, `cache_read`, `cache_write` (standards-based path only), `reasoning`, session/conversation id, request id (span id), duration, model, provider |
+| Cannot know | interface/surface (no OTel GenAI attribute carries it) |
+
+Standards-based: point any tool's OTLP file/collector exporter at the drop folder
+(`~/.tokenflow/otel/`) and it becomes a source with no code change here. Gemini-CLI specific:
+enable `telemetry.enabled` / `target: "local"` / `outfile` in `.gemini/settings.json`; this
+adapter recognizes and de-duplicates Gemini's paired usage events (`gemini_cli.api_response` and
+its standards-based twin) so a call is counted once.
+
+```yaml
+sources:
+  otel:
+    paths: ["~/code/my-project/.gemini/telemetry.log", "~/.tokenflow/otel"]
+```
+
+See [providers-otel.md](providers-otel.md) for the field mapping, the two on-disk shapes this
+adapter reads, and the privacy allow-list.
+
+### Tools with no known on-disk usage log (needs a sample)
+
+These were not verified for this adapter, either because they have no documented local usage
+export or because checking would have needed an account this project does not have. A fixture
+line from a **synthetic** run turns any of these from a guess into a supported source:
+
+| Tool | Status |
+|---|---|
+| Aider | No documented on-disk per-request usage log found; prints session totals to the terminal. |
+| Ollama | No documented usage-log file; token counts are only in the API response body. |
+| LM Studio | No documented on-disk usage log found. |
+| Zed | Connects to Gemini CLI via ACP (surface tag `zed`); Zed's own OTel/usage export not checked. |
+| Windsurf / Codeium | No documented on-disk usage log found. |
+| JetBrains AI Assistant | Gemini CLI's ACP integration reports a `jetbrains` surface tag; the plugin's own export not checked. |
+| Continue | No documented on-disk usage log found. |
+| Copilot CLI | No documented on-disk usage log found. |
+| Antigravity | No public documentation found; needs a sample or a pointer to its docs. |
+
+---
+
 ## `git` — activity correlation
 
 | | |

package/docs/receipt-schema.md

@@ -0,0 +1,74 @@
+# Receipt schema v0
+
+A branch receipt that travels with the code — no server. `tokenflow hooks install`
+attaches one to the local commit sha on every `git push`, as a git note under
+`refs/notes/tokenflow`. The [GitHub Action](../action/README.md) reads that note back
+on a pull request and posts (or updates) it as a comment.
+
+The machine-readable shape is `schemas/receipt.v0.json` (JSON Schema, draft 2020-12).
+`src/analytics/receipt-schema.js` provides:
+
+- `toReceiptV0(branchReceipt, meta)` — maps one `buildReceipts()` branch entry into
+  this shape.
+- `validateReceiptV0(obj)` — a small hand-written validator (no dependencies),
+  returns `{ ok, errors[] }`.
+- `renderReceiptV0Markdown(receipt)` — the PR-comment table, with a leading
+  `<!-- tokenflow-receipt -->` marker so CI can find and update its own comment.
+
+## The estimated-vs-measured caveat
+
+**Every dollar figure in this receipt is an estimate**, computed locally from token
+counts against a local price table (`~/.tokenflow/pricing.json` plus TokenFlow's
+built-in table) — never measured billing pulled from a vendor, and never a network
+call. Two things follow from that:
+
+- A model with no configured price contributes turns (counted in `turns`,
+  `subagentTurns`, `sessions`) but not dollars — `costUsd` reflects only the priced
+  turns, and `coverage` says what share of turns that was. A branch with **zero**
+  priced turns reports `costUsd: null`, never `0`.
+- `contextShare` splits `costUsd` into what paid to re-send prior context (cache
+  reads + writes) versus fresh input/output. A high share is not waste — it is the
+  price of a long session — but it is where the lever is if you want a cheaper one.
+
+`notes` carries these caveats (and others — a long-lived branch, work that predates
+a matched pull request, earlier merged PRs on the same branch) as plain sentences,
+so a reader of the JSON alone — not just the markdown table — sees them.
+
+## Fields
+
+| Field | Type | Nullable | Meaning |
+|---|---|---|---|
+| `schemaVersion` | integer (`0`) | no | Which version of this document the receipt follows. |
+| `generatedAt` | string (date-time) | no | When this receipt was computed, in UTC ISO-8601. |
+| `toolVersion` | string | no | The TokenFlow package version that computed it. |
+| `repo` | string | no | The repository's name — the basename of its **main checkout**, resolved through git worktrees (never a full path, never a worktree leaf's own directory name). |
+| `branch` | string | no | The branch this receipt attributes spend to. |
+| `headSha` | string | no | The commit sha this receipt is attached to (7-40 lowercase hex characters). |
+| `window` | object or `null` | yes | `{ first, last }` — the first and last timestamp of a priced turn on this branch. `null` when there were none. |
+| `window.first` / `window.last` | string (date-time) or `null` | yes | Endpoints of the window. |
+| `costUsd` | number | yes | Estimated spend attributed to this branch, in US dollars. `null` — never `0` — when nothing on this branch was priced. |
+| `contextShare` | number (0–1) | yes | Share of `costUsd` that re-sent prior context rather than doing fresh work. |
+| `turns` | integer | no | Turns (LLM requests) attributed to this branch, priced or not. |
+| `sessions` | integer | no | Distinct sessions that touched this branch. |
+| `subagentTurns` | integer | no | Of `turns`, how many ran as a subagent. |
+| `models` | array | no | `{ model, costUsd, share }` per model family, most expensive first. |
+| `coverage` | number (0–1) | yes | Share of `turns` priced (i.e. counted in `costUsd`). |
+| `largestPromptTokens` | integer | yes | The largest single prompt (input + cache read + cache write) seen on this branch. |
+| `changedLines` | integer | yes | Additions + deletions of the matched pull request. `null` with no matched PR. |
+| `pr` | object or `null` | yes | `{ number, mergedAt }` of the pull request this receipt's headline is scoped to. |
+| `longLived` | boolean | no | True for branch names like `main` / `staging` / `develop` — this receipt covers a period of work, not one change. |
+| `costPer100Lines` | number | yes | `costUsd` scaled to 100 changed lines. `null` with no matched PR, no changed lines, or no priced turns. |
+| `notes` | array of strings | no | Honesty caveats — see above. |
+
+## Design notes
+
+- `repo` is the repository's **name only** — never a filesystem path — because the
+  receipt is meant to be read on a different machine (a CI runner, a teammate's
+  laptop) than the one that produced it.
+- A receipt with no local sessions for a branch is not produced at all
+  (`buildBranchReceipt()` in `src/core/receipt-note.js` returns `null`); there is
+  nothing to attach as a note.
+- `pr` and `changedLines` are `null` for every receipt written by the pre-push hook,
+  because attaching a note happens at push time, before any PR exists to look up —
+  they are populated only when a receipt is built through `tokenflow receipt --gh`
+  (or an equivalent supplied `--prs` list) and re-serialized through `toReceiptV0()`.