token-studio 4.8.0

package/config/collectors.json

@@ -0,0 +1,54 @@
+{
+  "enabledCollectors": [
+    "claude",
+    "codex",
+    "gemini",
+    "opencode",
+    "openclaw",
+    "hermes"
+  ],
+  "scheduledCollect": {
+    "enabled": false,
+    "intervalSeconds": 300,
+    "runOnStart": false,
+    "device": null
+  },
+  "collectors": {
+    "claude": {
+      "roots": [
+        "~/.config/claude",
+        "~/.claude"
+      ],
+      "includeDesktopLocalAgent": true,
+      "desktopLocalAgentBase": "~/Library/Application Support/Claude/local-agent-mode-sessions"
+    },
+    "codex": {
+      "homes": [
+        "~/.codex"
+      ],
+      "sessionSubdirs": [
+        "sessions",
+        "archived_sessions"
+      ],
+      "headlessRoots": [
+        "~/.config/token-studio-roi/headless",
+        "~/Library/Application Support/token-studio-roi/headless"
+      ]
+    },
+    "hermes": {
+      "dbPath": "~/.hermes/state.db"
+    },
+    "opencode": {
+      "dataDir": "~/.local/share/opencode",
+      "extraDbPaths": []
+    },
+    "openclaw": {
+      "agentRoots": [
+        "~/.openclaw/agents",
+        "~/.clawdbot/agents",
+        "~/.moltbot/agents",
+        "~/.moldbot/agents"
+      ]
+    }
+  }
+}

package/data/.gitkeep

@@ -0,0 +1 @@
+

package/docker-compose.yml

@@ -0,0 +1,17 @@
+services:
+  token-studio-roi:
+    build: .
+    ports:
+      - "4173:4173"
+    environment:
+      HOST: "0.0.0.0"
+      PORT: "4173"
+      INGEST_TOKEN: "${INGEST_TOKEN:?Set INGEST_TOKEN before starting the hub}"
+      HOME: /collector-home
+      SCHEDULED_COLLECT_ENABLED: "${SCHEDULED_COLLECT_ENABLED:-false}"
+      SCHEDULED_COLLECT_INTERVAL_SECONDS: "${SCHEDULED_COLLECT_INTERVAL_SECONDS:-${COLLECT_INTERVAL_SECONDS:-300}}"
+      SCHEDULED_COLLECT_RUN_ON_START: "${SCHEDULED_COLLECT_RUN_ON_START:-false}"
+      COLLECT_DEVICE: "${COLLECT_DEVICE:-docker-collector}"
+    volumes:
+      - ./data:/app/data
+      - "${TOKEN_STUDIO_COLLECTOR_HOME:-.}:/collector-home:ro"

package/docs/assets/.gitkeep

@@ -0,0 +1 @@
+

package/docs/blog-case-study.md

@@ -0,0 +1,34 @@
+# Blog Case Study Notes
+
+## Positioning
+
+Token Studio ROI turns local AI coding usage into a private weekly review loop: cost, projects, work attribution, output evidence, ROI advice, and model policy.
+
+## Problem
+
+Most token dashboards answer "how much did I use?" Token Studio ROI asks "what did that usage produce, and how should I change my model strategy next week?"
+
+## Product Decisions
+
+- Local-first by default.
+- No conversation content storage.
+- Official-price conversion only.
+- Unpriced models stay unpriced.
+- Demo mode uses synthetic data.
+- Experimental collectors are opt-in and skip rows without explicit token fields.
+
+## Engineering Highlights
+
+- Node.js `node:sqlite` local data store.
+- Collector registry with stable, experimental, detected-only, and unsupported states.
+- Lightweight `/live` monitor for recent burn rate without transcript access.
+- Loopback-only local write APIs.
+- Privacy scanner for public readiness.
+- ROI Evidence Score for evidence completeness.
+- Markdown model policy export.
+
+## Honest Limits
+
+- Cost conversion is not a provider invoice.
+- Rules do not understand task quality like a human reviewer.
+- Real ROI improves only when sessions have real attribution and output links.

package/docs/collector-support-matrix.md

@@ -0,0 +1,65 @@
+# Collector Support Matrix
+
+Token Studio ROI prefers trustworthy token metadata over broad but unreliable coverage.
+
+| Source | Status | Data source | Reads conversation content | Token reliability | Default |
+|---|---|---|---:|---|---:|
+| Claude Code | stable | local metadata/log files | No | native token fields | Yes |
+| Codex CLI | stable | local JSONL session metadata | No | native token fields | Yes |
+| Gemini CLI | stable | local session metadata | No | native token fields | Yes |
+| OpenCode | stable | local data directory | No | native token fields | Yes |
+| OpenClaw | stable | local agent metadata | No | native token fields | Yes |
+| Hermes Agent | stable | local SQLite metadata | No | native token fields | Yes |
+| Cursor | experimental | explicit structured usage JSON/JSONL only | No | explicit token fields only | No |
+| GitHub Copilot CLI | experimental | explicit structured usage JSON/JSONL only | No | explicit token fields only | No |
+| Qwen Code | experimental | explicit structured usage JSON/JSONL only | No | explicit token fields only | No |
+| Kimi / Moonshot Coding CLI | experimental | explicit structured usage JSON/JSONL only | No | explicit token fields only | No |
+| Goose | experimental | explicit structured usage JSON/JSONL only | No | explicit token fields only | No |
+| ccusage JSON / CLI Bridge | import-only | documented ccusage JSON output or explicit `ccusage --json --no-cost` bridge | No | external structured token fields | No |
+| Amp | detected-only | local path detection only | No | unknown; no usage import | No |
+| Droid | detected-only | local path detection only | No | unknown; no usage import | No |
+| Codebuff | detected-only | local path detection only | No | unknown; no usage import | No |
+| pi-agent | detected-only | local path detection only | No | unknown; no usage import | No |
+| Roo Code | detected-only | local path detection only | No | unknown; no usage import | No |
+| Zed Agent | detected-only | local path detection only | No | unknown; no usage import | No |
+| Antigravity | detected-only | local path detection only | No | unknown; no usage import | No |
+| Cline | detected-only | local path detection only | No | unknown; no usage import | No |
+| Kiro | detected-only | local path detection only | No | unknown; no usage import | No |
+| Grok Build | detected-only | local path detection only | No | unknown; no usage import | No |
+| Kilo | detected-only | local path detection only | No | unknown; no usage import | No |
+
+Experimental collectors are opt-in. They skip records without explicit token fields and never infer usage from message text, prompts, responses, diffs, or full file paths.
+
+Import-only sources are explicit. Saved ccusage JSON does not scan local logs. The CLI bridge runs ccusage as an external local scanner only after confirmation or `--yes`; Token Studio receives structured JSON, rejects conversation-like fields, and recomputes official-price costs:
+
+```bash
+npx token-studio import-usage --format=ccusage-json --file ccusage.json --dry-run
+npx token-studio import-usage --format=ccusage-json --file ccusage.json --apply
+npx token-studio import-usage --format=ccusage-cli --report=session --dry-run --yes
+npx token-studio import-usage --format=ccusage-cli --report=blocks --apply --yes
+```
+
+The Dashboard ccusage CLI Bridge panel only builds these copyable commands. It does not run ccusage from the browser or through a new server-side scanner API.
+
+Detected-only sources only report whether likely local paths exist. They do not write `daily_usage`, `session_usage`, or `token_events` until a later audit proves reliable token/model/time/session metadata.
+
+## Collector Audit
+
+Token Studio collector audit provides:
+
+```bash
+npx token-studio collectors --audit --json
+```
+
+The audit checks experimental collector roots and returns only safe counts:
+
+- candidate files
+- usable structured token records
+- skipped records with no token fields
+- skipped conversation-like records
+- skipped oversized files
+- parse errors
+
+It does not write SQLite, does not print full paths, and does not output prompt, response, diff, transcript, or message content. A collector should only move from experimental to stable after audit results show reliable token/model/time/session metadata on real local files. Detected-only collectors must first move to experimental with fixture coverage before they can ever become stable.
+
+From a cloned repository, replace `npx token-studio` with `node src/cli.mjs` for local development.

package/docs/competitive-notes.md

@@ -0,0 +1,87 @@
+# Competitive Notes
+
+Token Studio ROI is positioned as a local AI coding ROI review system, not only a token counter.
+
+## Referenced Projects
+
+| Project | Public focus | Coverage strength | Launch strength | Token Studio ROI difference |
+|---|---|---|---|---|
+| [ccusage](https://ccusage.com/) | Local CLI usage and estimated cost across many coding agents | Broad collector coverage, offline pricing, cache token accounting | Strong CLI workflow | Token Studio ROI adds work attribution, output links, ROI evidence score, and weekly review exports. |
+| [CodeBurn](https://github.com/getagentseal/codeburn) | Interactive TUI for Claude Code, Codex, and Cursor cost observability | Claude, Codex, Cursor oriented | Fast `npx` terminal experience | Token Studio ROI uses a browser review workspace with work items and advisor actions. |
+| [token-dashboard](https://github.com/nateherkai/token-dashboard) | Local Claude Code JSONL dashboard with cost analytics, heatmaps, and tips | Deep Claude Code analytics | Clear dashboard story | Token Studio ROI keeps transcript content out of the product and focuses on project/task/output ROI. |
+| [Claude Code Usage Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor) | Real-time terminal monitoring with burn rate and prediction | Claude Code focused | Strong live monitoring | Token Studio ROI treats live monitoring as a lightweight guardrail and keeps weekly ROI review as the main surface. |
+| [TokenTracker](https://github.com/mm7894215/TokenTracker) | Local-first dashboard, native tray/menu bar, widgets, many coding tools | Very broad tool coverage | Desktop packaging and zero-config story | Token Studio ROI is lighter-weight today but has deeper work/output attribution and publishable review artifacts. |
+
+## Differentiation
+
+- Work attribution: project alias, task type, output status, work purpose, stage, value, and notes.
+- Output evidence: PR, commit, article, deploy, document, screenshot, or other URL without fetching linked content.
+- Work item layer: multiple sessions can roll up into one deliverable.
+- ROI Evidence Score: separates manually confirmed work, auto/high-confidence work, missing fields, output links, and high-cost gaps.
+- ROI Savings Simulator: compares model switching scenarios for exploration, testing, context prep, low-value, and abandoned work using official-price conversion, not invoice claims.
+- ROI Advisor: local explainable rules that recommend annotation, model switching, context compression, stop-loss, output links, and policy changes.
+- Advisor Action Loop: recommendations can become open/done/dismissed actions and appear in weekly reports.
+- Model Policy export: produces a reusable Markdown strategy for when to use light, mid, or heavy models.
+- ccusage JSON Import: uses ccusage documented output as an import bridge for broader structured coverage while recomputing official-price costs locally.
+- Budget Guardrails: custom source-level token/cost windows, burn projection, and near/over/exceeded warnings without pretending to know provider subscription quotas.
+- Collector Audit: safely checks experimental collector viability before upgrading support level, instead of inflating source count with unreliable estimates.
+- Terminal ROI Report: quick CLI summary of total tokens, official-price cost, project/model ranking, budget risks, and Advisor Actions.
+- Public safety: demo mode, privacy-check, `NOTICE.md`, no real SQLite in git, no prompt/response export.
+- Launch path: `npx token-studio demo` after npm publication, with `git clone && npm run demo` kept as the source checkout path.
+- v4.1 coverage path: experimental Cursor, Copilot CLI, Qwen Code, Kimi, and Goose collectors skip records without explicit token fields.
+
+## v4.3 High-ROI Product Bet
+
+The fastest way to improve Token Studio ROI is to close the biggest visible gaps without diluting the ROI product wedge. ccusage, tokscale, and TokenTracker still lead on breadth and quick-start monitoring. CodeBurn and Claude Code Usage Monitor remain stronger in terminal-first live burn-rate workflows.
+
+v4.3 narrows that gap by using ccusage JSON as an import bridge, adding source-level budget guardrails, and adding terminal reports. It still deepens the question those tools usually stop short of: **what should I change next week to spend fewer tokens on low-value work and preserve expensive models for high-value output?**
+
+v4.3 therefore prioritizes:
+
+- ccusage import before reimplementing every collector.
+- Custom budget guardrails before claiming exact subscription limits.
+- Advisor Actions before generic tips.
+- Terminal ROI report before a full TUI.
+- Collector matrix breadth with detected-only/import-only honesty before fake stable support.
+
+## v4.6 Bridge And Statusline Bet
+
+The remaining gap after v4.5 is not the browser review workflow; it is quick terminal access and broad source ingestion. ccusage already documents JSON reports for daily, weekly, monthly, session, and blocks, and it can be run directly with `npx ccusage@latest`. Token Studio ROI should not duplicate every collector immediately.
+
+v4.6 therefore adds:
+
+- ccusage CLI Bridge: run ccusage explicitly, request `--json --no-cost`, reject unsafe conversation-like fields, and recompute costs with Token Studio official-price logic.
+- Statusline Guardrails: a compact read-only summary for terminal prompt, tmux, or Claude Code statusline use.
+- No desktop widget, leaderboard, subscription-quota prediction, account system, or background daemon.
+
+This narrows the most visible competitive gap while keeping Token Studio ROI focused on work evidence, model strategy, and Advisor Actions.
+
+## v4.7 Usability Catch-Up
+
+v4.7 keeps the same product wedge but makes the catch-up features easier to use:
+
+- ccusage Bridge UX: the Dashboard generates copyable commands for saved JSON or CLI bridge workflows, but the browser never runs external scanners.
+- Quota Profiles v2: custom guardrails now support rolling and fixed reset windows, reset countdowns, and editable warning thresholds.
+- Statusline Integration Pack: documented snippets for Claude Code statusline, tmux, PowerShell prompts, and JSON scripts.
+- ROI Playbook Export: `token-studio policy --format=markdown|claude-md|agents-md` turns Model Policy into copyable operating rules without editing user files.
+
+This closes practical gaps with terminal-first competitors while preserving the main differentiation: ROI evidence, work outputs, and explicit action loops.
+
+## v4.8 npm And Source Health Bet
+
+v4.8 makes the public launch path easier to try and easier to explain:
+
+- npm one-command launch: `npx token-studio demo` should get a new user into synthetic demo data within 30 seconds.
+- Source Health Center: show native stable, experimental, detected-only, and ccusage import-bridge support honestly, including detected status, recent rows, token-field trust, and privacy boundaries.
+- ccusage bridge as coverage shortcut: use ccusage's broad ecosystem through explicit JSON/CLI import while still recomputing costs with Token Studio official-price logic.
+- README first screen: position Token Studio ROI around Work Evidence, Savings Simulator, and Model Policy instead of competing only as a token meter.
+
+This narrows the most visible competitor gap, one-command startup and coverage clarity, without pretending that detected-only sources are real collectors.
+
+## Remaining Gaps
+
+- Collector depth is still behind the broadest multi-tool products. v4.8 improves breadth through Source Health plus ccusage JSON/CLI bridge and detected-only coverage, but Token Studio's own stable collectors remain narrower than ccusage or TokenTracker.
+- Live monitoring is intentionally lightweight; it is a guardrail for current burn rate, not an exact subscription predictor.
+- Desktop packaging is not included. Keep the public story focused on local browser + CLI first.
+- Automatic attribution is rule-based and should always display provenance and confidence.
+- Savings simulation depends on official public token prices and structured metadata; it is useful for strategy, not proof of actual invoice savings.

package/docs/demo-data/README.md

@@ -0,0 +1,12 @@
+# Token Studio ROI Demo Data
+
+`token-studio-v2-demo.json` contains synthetic data for screenshots, blog posts, and local demos.
+
+It is not real local AI usage data. It contains no conversation content.
+
+The file has two sections:
+
+- `usageSeed`: synthetic daily/session usage rows that mirror the local collector shape.
+- `annotationBackup`: import/export-shaped annotations, output links, and project alias rules.
+
+The import API expects matching sessions to already exist in SQLite because annotations are keyed by `device + source + session_id`.

package/docs/demo-data/token-studio-v2-demo.json

@@ -0,0 +1,146 @@
+{
+  "version": 2,
+  "synthetic": true,
+  "generatedFor": "Token Studio ROI public demo",
+  "notes": [
+    "This file contains synthetic demo records only.",
+    "It does not contain real local AI session data or conversation content.",
+    "annotationBackup can be used as the shape for /api/import/annotations after matching sessions exist in the local SQLite database."
+  ],
+  "usageSeed": {
+    "daily": [
+      {
+        "device": "demo-laptop",
+        "source": "Codex CLI",
+        "usageDate": "2026-06-10",
+        "model": "codex-mini",
+        "inputTokens": 180000,
+        "outputTokens": 62000,
+        "cacheCreationTokens": 9000,
+        "cacheReadTokens": 54000,
+        "reasoningOutputTokens": 12000,
+        "totalTokens": 317000,
+        "costUSD": 5.84
+      },
+      {
+        "device": "demo-laptop",
+        "source": "Claude Code",
+        "usageDate": "2026-06-09",
+        "model": "claude-sonnet",
+        "inputTokens": 220000,
+        "outputTokens": 71000,
+        "cacheCreationTokens": 16000,
+        "cacheReadTokens": 61000,
+        "reasoningOutputTokens": 0,
+        "totalTokens": 368000,
+        "costUSD": 8.15
+      }
+    ],
+    "sessions": [
+      {
+        "device": "demo-laptop",
+        "source": "Codex CLI",
+        "sessionId": "demo:codex:token-studio-roi",
+        "lastActivity": "2026-06-10T09:20:00.000Z",
+        "projectPath": "D:/Projects/token-studio-roi-demo",
+        "inputTokens": 180000,
+        "outputTokens": 62000,
+        "cacheCreationTokens": 9000,
+        "cacheReadTokens": 54000,
+        "reasoningOutputTokens": 12000,
+        "totalTokens": 317000,
+        "costUSD": 5.84
+      },
+      {
+        "device": "demo-laptop",
+        "source": "Claude Code",
+        "sessionId": "demo:claude:resume-polish",
+        "lastActivity": "2026-06-09T16:40:00.000Z",
+        "projectPath": "D:/Projects/resume-roi-demo",
+        "inputTokens": 220000,
+        "outputTokens": 71000,
+        "cacheCreationTokens": 16000,
+        "cacheReadTokens": 61000,
+        "reasoningOutputTokens": 0,
+        "totalTokens": 368000,
+        "costUSD": 8.15
+      },
+      {
+        "device": "demo-laptop",
+        "source": "Codex CLI",
+        "sessionId": "demo:codex:abandoned-spike",
+        "lastActivity": "2026-06-08T12:10:00.000Z",
+        "projectPath": "D:/Projects/abandoned-spike-demo",
+        "inputTokens": 90000,
+        "outputTokens": 24000,
+        "cacheCreationTokens": 5000,
+        "cacheReadTokens": 22000,
+        "reasoningOutputTokens": 3000,
+        "totalTokens": 144000,
+        "costUSD": 2.12
+      }
+    ]
+  },
+  "annotationBackup": {
+    "version": 2,
+    "sessionAnnotations": [
+      {
+        "device": "demo-laptop",
+        "source": "Codex CLI",
+        "sessionId": "demo:codex:token-studio-roi",
+        "projectAlias": "Token Studio",
+        "taskType": "功能开发",
+        "outputStatus": "已发布",
+        "note": "v2 本地 ROI 复盘闭环"
+      },
+      {
+        "device": "demo-laptop",
+        "source": "Claude Code",
+        "sessionId": "demo:claude:resume-polish",
+        "projectAlias": "简历优化工具",
+        "taskType": "问题修复",
+        "outputStatus": "已完成",
+        "note": "修复结果页证据展示"
+      },
+      {
+        "device": "demo-laptop",
+        "source": "Codex CLI",
+        "sessionId": "demo:codex:abandoned-spike",
+        "projectAlias": "废弃 Spike",
+        "taskType": "技术调研",
+        "outputStatus": "已废弃",
+        "note": "方向不值得继续投入"
+      }
+    ],
+    "sessionOutputs": [
+      {
+        "device": "demo-laptop",
+        "source": "Codex CLI",
+        "sessionId": "demo:codex:token-studio-roi",
+        "outputUrl": "https://github.com/example/token-studio/pull/12",
+        "outputLabel": "v2 PR"
+      },
+      {
+        "device": "demo-laptop",
+        "source": "Claude Code",
+        "sessionId": "demo:claude:resume-polish",
+        "outputUrl": "https://example.com/resume-demo",
+        "outputLabel": "Demo 页面"
+      }
+    ],
+    "projectAliasRules": [
+      {
+        "pattern": "D:/Projects/token-studio-roi-demo",
+        "matchType": "prefix",
+        "projectAlias": "Token Studio",
+        "enabled": true
+      },
+      {
+        "pattern": "D:/Projects/resume-roi-demo",
+        "matchType": "prefix",
+        "projectAlias": "简历优化工具",
+        "enabled": true
+      }
+    ]
+  }
+}

package/docs/demo-flow.md

@@ -0,0 +1,39 @@
+# Token Studio ROI Demo Flow
+
+This flow is for public GitHub screenshots, blog posts, and resume walkthroughs.
+
+## 1. Start Synthetic Demo
+
+```bash
+npm install
+npm run demo
+```
+
+The demo command seeds `data/demo.sqlite` from `docs/demo-data/token-studio-v2-demo.json` and starts the local UI.
+
+## 2. Show The Story
+
+1. Open the dashboard and point out the `Demo Mode` badge.
+2. Show source/model filtering and project/session attribution.
+3. Open `/review`.
+4. Show ROI Evidence Score before the detailed sections.
+5. Show ROI Advisor and model strategy.
+6. Export the Markdown review report.
+7. Open `/api/model-policy.md` to show the generated model policy.
+
+## 3. Privacy Script
+
+Run:
+
+```bash
+npm run privacy:check
+```
+
+The public demo should not include real SQLite databases, local AI log directories, `.env` files, generated exports, personal paths, or raw conversation content.
+
+## Demo Boundary
+
+- Synthetic demo data is not real usage history.
+- Real local mode requires explicit collection confirmation.
+- Token Studio ROI does not read conversation content.
+- Official-price conversion is not a provider invoice.

package/docs/first-run.md

@@ -0,0 +1,95 @@
+# First Run Guide
+
+This guide gets a new user from an empty checkout to a useful ROI review in about five minutes.
+
+## 1. Start Safely With Demo Data
+
+```bash
+npx token-studio demo
+```
+
+Demo mode uses synthetic data and does not scan `.claude`, `.codex`, Cursor, Copilot, or any other local AI logs.
+
+From a cloned repository, use:
+
+```bash
+npm install
+npm run demo
+```
+
+## 2. Try The Import Flow Without Writing
+
+Open the Dashboard and choose **导入/预算**.
+
+Paste ccusage JSON or choose a local JSON file, then click **Dry-run 预检**. Token Studio reports the detected shape, daily rows, sessions, token events, ignored third-party cost fields, and unsafe conversation-like fields.
+
+Only click **Apply 写入 SQLite** after the dry-run looks correct. Apply creates a SQLite backup before writing.
+
+CLI equivalent:
+
+```bash
+npx token-studio import-usage --format=ccusage-json --file ccusage.json --dry-run
+```
+
+If you already use ccusage and want Token Studio to invoke it for you, use the explicit bridge:
+
+```bash
+npx token-studio import-usage --format=ccusage-cli --report=session --dry-run --yes
+```
+
+This runs `ccusage session --json --no-cost` through the configured bridge. Token Studio rejects conversation-like fields, ignores ccusage cost fields, and only writes SQLite when you switch from `--dry-run` to `--apply`.
+
+The Dashboard also has a **ccusage CLI Bridge** command builder. It only generates a copyable terminal command; the browser does not run ccusage or any external scanner.
+
+## 3. Create A Custom Budget Window
+
+In **导入/预算**, create a source-level budget such as:
+
+- source: `Codex CLI`
+- window type: `rolling` or `fixed`
+- window: `60` minutes, `300` minutes, or your own target
+- reset anchor: fixed windows only
+- warning threshold: for example `0.75`
+- token budget: your own target
+- USD budget: optional official-price conversion target
+
+Token Studio does not ship provider subscription quota presets. Budgets are your own guardrails, not vendor plan limits.
+
+## 4. Review ROI
+
+Open `/review` and check:
+
+- ROI Evidence Score
+- Savings Simulator
+- ROI Advisor
+- Advisor Actions
+- Markdown report export
+
+The first useful action is usually to add one or two recommendations to the action list, then review whether similar work uses fewer tokens next week.
+
+## 5. Optional Terminal Statusline
+
+For a compact live guardrail in a terminal prompt, tmux bar, or Claude Code statusline:
+
+```bash
+npx token-studio statusline --format=text --window-minutes=15
+npx token-studio statusline --format=json --window-minutes=15
+```
+
+The statusline command only reads SQLite. It does not scan logs or start a background process. Copyable Claude Code, tmux, and PowerShell snippets are in [statusline.md](statusline.md).
+
+## 6. Optional ROI Playbook Export
+
+Export a model-use playbook without editing `CLAUDE.md`, `AGENTS.md`, or project files:
+
+```bash
+npx token-studio policy --format=markdown
+npx token-studio policy --format=claude-md
+npx token-studio policy --format=agents-md
+```
+
+Use the output as a review artifact or copy the relevant section manually into your local project rules.
+
+## Privacy Boundary
+
+Token Studio does not store prompts, responses, transcripts, command bodies, diffs, or full file paths. Costs are official public token-price conversions and simulations, not provider invoices.

package/docs/local-collectors.md

@@ -0,0 +1,49 @@
+# Local Collectors
+
+Token Studio ROI uses a collector registry instead of ad-hoc collector labels.
+
+## Stable v4.0 Sources
+
+- Claude Code
+- Codex CLI
+- Gemini CLI
+- OpenCode
+- OpenClaw
+- Hermes Agent
+
+These sources can produce normalized `daily_usage` and `session_usage` rows when their local metadata stores exist.
+
+## Experimental v4.1 Sources
+
+- Cursor
+- GitHub Copilot CLI
+- Qwen Code
+- Kimi / Moonshot Coding CLI
+- Goose
+
+Experimental sources are opt-in. They import only explicit structured token fields from JSON/JSONL metadata and skip records without reliable token fields.
+
+See [collector-support-matrix.md](collector-support-matrix.md) for status, privacy, and token reliability.
+
+## Commands
+
+```bash
+node src/cli.mjs doctor
+node src/cli.mjs collectors
+node src/cli.mjs collect --sources=claude,codex
+node src/cli.mjs collect --sources=cursor --yes
+```
+
+`collect` requires explicit confirmation. Non-interactive shells refuse to scan local AI logs unless `--yes` is provided.
+
+## Environment
+
+- `TOKEN_STUDIO_COLLECTORS=claude,codex,gemini`
+- `TOKEN_STUDIO_CONFIG=config/collectors.json`
+- `TOKEN_STUDIO_HEADLESS_DIR=/path/to/headless/events`
+
+Older `AI_TOKEN_DASHBOARD_*` variables are accepted only as backward-compatible fallbacks.
+
+## Privacy
+
+Collectors should normalize token metadata only. They must not store prompt text, response text, full transcripts, full file paths, command bodies, or diff content.