token-studio 4.8.0

package/.nvmrc

@@ -0,0 +1 @@
+24

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+## 4.8.0
+
+- Renamed the npm package to `token-studio` with `npx token-studio demo` as the primary public entry.
+- Updated CLI path handling so npm-installed commands run package files from the installed package while writing demo/usage SQLite data into the caller's working directory.
+- Added Source Health Center data and UI for native stable, experimental, detected-only, and ccusage import-bridge sources without exposing full local paths.
+- Added `GET /api/source-health` and included source health metadata in `/api/data`.
+- Updated README quick start and public docs around npm launch, ccusage bridge coverage, privacy boundaries, and official-price/non-invoice wording.
+
+## 4.7.0
+
+- Added Dashboard ccusage CLI Bridge UX that only generates copyable local commands; the browser never runs external scanners.
+- Extended budget profiles to support `rolling` and `fixed` windows with `reset_anchor` and editable `warning_threshold`.
+- Updated `/live` and `token-studio statusline` to show quota window type, reset countdown, warning thresholds, and budget usage.
+- Added `docs/statusline.md` plus `token-studio statusline --help` integration snippets for Claude Code statusline, tmux, PowerShell, and JSON scripts.
+- Added `token-studio policy --format=markdown|claude-md|agents-md` to export a reusable ROI model-use playbook without editing project files.
+
+## 4.6.0
+
+- Added `token-studio import-usage --format=ccusage-cli` to explicitly run `ccusage <report> --json --no-cost` and reuse the existing privacy-safe ccusage import planner.
+- Added non-interactive `--yes` gating for the ccusage CLI bridge; dry-run remains default, apply creates a SQLite backup, and unsafe conversation-like fields are rejected.
+- Added `token-studio statusline --format=text|json` for terminal/Claude Code/tmux status bars with recent-window tokens, burn rate, cache hit, budget usage, reset countdown, unpriced-model warnings, and open Advisor Actions.
+- Added weekly ccusage JSON shape support and kept imported third-party cost fields ignored in favor of Token Studio official-price conversion.
+- Updated documentation to position v4.6 as a bridge/statusline catch-up release, not a desktop widget, leaderboard, or full TUI rewrite.
+
+## 4.5.0
+
+- Added first-run onboarding on the Dashboard, derived from existing usage, budget, advisor action, and token event data without adding schema.
+- Added empty-state guidance for no data, data without Advisor actions, and budgets without recent event-level live data.
+- Added `token-studio open` to start the local UI and open the browser.
+- Added `token-studio import-usage --help` with ccusage JSON examples, supported shapes, and privacy boundaries.
+- Added `docs/first-run.md` with a 5-minute demo/import/budget/review flow.
+
+## 4.4.0
+
+- Added a Dashboard “导入/预算” wizard for ccusage JSON paste/upload dry-run and explicit SQLite apply.
+- Added `POST /api/import/ccusage-json` so the UI can reuse the privacy-safe ccusage import planner; unsafe conversation-like fields are rejected and apply creates a SQLite backup.
+- Added Budget Wizard UI for source-level custom token/cost windows and linked `/live` budget guardrails.
+- Added `/review` Advisor Action Summary page with open/done/dismissed counts and standalone Markdown action export.
+- Fixed `/review` mobile bottom spacing so fixed previous/next page controls do not cover the last visible content.
+- Added demo-mode public screenshot assets under `docs/assets/`.
+
+## 4.3.0
+
+- Added `token-studio import-usage --format=ccusage-json` for documented ccusage JSON import with dry-run by default, unsafe conversation-field rejection, and Token Studio official-price recomputation.
+- Added local `budget_profiles`, budget APIs, `token-studio budget`, and `/live` budget windows with near/over/exceeded guardrail warnings.
+- Added `advisor_actions`, action APIs, `/review` action buttons, and Markdown report action status output.
+- Added `token-studio report --period=week --format=table|markdown|json` for terminal ROI review summaries.
+- Extended collector matrix with `import-only` ccusage and detected-only entries for Amp, Droid, Codebuff, pi-agent, Roo Code, Zed Agent, Antigravity, Cline, Kiro, Grok Build, and Kilo.
+- Kept v4.3 broad coverage privacy-safe: no fake token rows, no prompt/response/transcript/diff/full-path storage, and no real collect in automated tests.
+
+## 4.2.0
+
+- Added ROI Savings Simulator on `/review` to compare official-price model switching scenarios for low-value, exploration, testing, and context-prep work.
+- Added savings simulation output to Markdown weekly review reports with explicit non-invoice wording.
+- Extended `/api/live` with guardrail thresholds and warning cards for high burn rate, low cache hit, low output/input ratio, and active unpriced models.
+- Added `token-studio collectors --audit [--json]` for safe experimental collector audits without SQLite writes or full-path output.
+- Extended collector metadata with `auditRecommended` and `lastAudit` placeholders.
+- Kept v4.2 focused on product differentiation; npm release packaging and screenshots remain a later launch gate.
+
+## 4.1.0
+
+- Added `/live` lightweight local monitor for recent token burn rate, cache hit, active sessions, sources, and models.
+- Added `token-studio live` and `token-studio collectors`.
+- Upgraded Cursor, GitHub Copilot CLI, Qwen Code, Kimi, and Goose to opt-in experimental collectors.
+- Added fixture-backed structured usage parsing that skips rows without explicit token fields.
+- Extended `GET /api/collectors` with privacy, token reliability, data field, and fixture metadata.
+- Added public launch checklist and collector support matrix.
+- Expanded competitive notes and README differentiation against token-meter style tools.
+
+## 4.0.0
+
+- Repackaged the project as `@ryan/token-studio-roi` with the `token-studio` CLI.
+- Added standalone demo mode backed by synthetic SQLite data.
+- Added collector registry and source detection for six stable local collectors.
+- Added detected-only entries for Cursor, GitHub Copilot CLI, Qwen Code, Kimi, and Goose.
+- Added privacy check for publish readiness.
+- Added `token_events`, `work_items`, and `work_item_sessions` schema.
+- Added ROI Evidence Score on `/review`.
+- Added model policy Markdown API.
+- Added `GET /api/collectors`, `GET /api/privacy-check`, `GET /api/model-policy.md`, and work item APIs.
+- Kept local write APIs loopback-only, local-Origin-only, and JSON-only.
+
+## Notes
+
+- Real collection is never run by automated tests.
+- Demo data is synthetic and must not be described as real user history.
+- Official-price conversion is not a provider invoice.

package/Dockerfile

@@ -0,0 +1,17 @@
+FROM node:22-alpine
+
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY src ./src
+COPY config ./config
+COPY data/pricing-litellm.json data/pricing-openrouter.json ./data/
+COPY index.html vite.config.js ./
+RUN npm run build && npm prune --omit=dev
+
+ENV PORT=4173
+ENV HOST=0.0.0.0
+EXPOSE 4173
+
+CMD ["node", "src/server.mjs"]

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 AI Token Dashboard contributors
+Copyright (c) 2026 Token Studio ROI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,21 @@
+# Notice
+
+Token Studio ROI is a standalone public packaging and productization effort by ryan.
+
+The project preserves attribution for an earlier MIT-licensed AI token dashboard prototype. The original MIT copyright notice is kept in `LICENSE`.
+
+Token Studio ROI adds and productizes the following first-class features:
+
+- standalone `token-studio` CLI
+- demo mode with synthetic data
+- collector registry and source detection
+- privacy scanner for public readiness
+- session attribution and provenance
+- work item model for grouping sessions into outputs
+- ROI Evidence Score
+- local ROI Advisor rules
+- model policy Markdown export
+- official-price conversion boundaries
+- loopback-only local write API hardening
+
+The project does not claim provider-invoice accuracy and does not read, store, display, or export conversation content.

package/PRIVACY.md

@@ -0,0 +1,68 @@
+# Privacy
+
+Token Studio ROI is designed as a local-first AI coding review tool.
+
+## Default Behavior
+
+- No cloud sync.
+- No account system.
+- No remote telemetry.
+- No automatic scan of local AI tool logs on startup.
+- Demo mode uses synthetic records only.
+
+## Real Collection
+
+Real collection runs only after explicit confirmation through the CLI or local UI.
+
+Supported v4.0 stable collectors read local structured usage metadata from:
+
+- Claude Code
+- Codex CLI
+- Gemini CLI
+- OpenCode
+- OpenClaw
+- Hermes Agent
+
+Detected-only sources such as Cursor, GitHub Copilot CLI, Qwen Code, Kimi, and Goose are not written as usage rows until reliable token fixtures exist.
+
+## Data Not Stored
+
+Token Studio ROI does not store:
+
+- prompts
+- responses
+- full transcripts
+- full file paths
+- command bodies
+- diff content
+- fetched PR, commit, article, or deployment content
+
+Output links store only URL, label, and type.
+
+## Local Data
+
+Local SQLite files live under `data/` by default and are ignored by Git.
+
+Before publishing or sharing the repository, run:
+
+```bash
+npm run privacy:check
+```
+
+The privacy check looks for real SQLite databases, AI log directories, `.env` files, generated exports, personal paths, and likely secrets in tracked files.
+
+## Network Boundary
+
+The local server binds to `127.0.0.1` by default.
+
+All write APIs require:
+
+- loopback request address
+- local or empty Origin
+- `Content-Type: application/json`
+
+The server does not trust `X-Forwarded-For` for local access checks.
+
+## Cost Boundary
+
+Dollar values are official public token-price conversions. They are useful for trend review and model strategy, but they are not provider invoices or financial reconciliation.

package/README.en.md

@@ -0,0 +1,220 @@
+# Token Studio ROI
+
+**English** | [中文](README.md)
+
+**Local AI Coding ROI Studio.** Token Studio ROI is a local, privacy-first AI coding review tool. It does more than count tokens: it connects official-price token usage to projects, tasks, work stages, output evidence, and model strategy.
+
+```bash
+npx token-studio demo
+```
+
+Remember three differences:
+
+- **Work Evidence**: see where tokens went and which project/task/stage/output they belong to.
+- **Savings Simulator**: simulate model-switching savings with official public token prices.
+- **Model Policy**: turn usage history into next week's light/mid/heavy model strategy.
+
+By default it does not read, display, or upload conversation content. Real collection requires explicit confirmation.
+
+## Why Not ccusage / CodeBurn?
+
+| Tool | Strength | Token Studio ROI difference |
+|---|---|---|
+| ccusage | Broad coverage and mature JSON output | Token Studio ROI uses the bridge for coverage, then focuses on outputs and review |
+| CodeBurn | `npx` TUI and local cost observation | Token Studio ROI focuses on weekly reports, action loops, and model policy |
+| TokenTracker / CodexBar | Desktop visibility and quota surfaces | Token Studio ROI focuses on local ROI decisions and work evidence |
+
+See [docs/competitive-notes.md](docs/competitive-notes.md) for the fuller competitor reference and differentiation notes.
+
+## What Makes ROI Different?
+
+v4.8 focuses on decisions, not only metering, and uses npm one-command launch, Source Health, a small CLI bridge, quota profiles, and statusline integrations to close coverage and live-entry gaps without turning Token Studio into a desktop widget or TUI clone:
+
+- **ROI Savings Simulator**: compares official-price model switching scenarios for exploration, testing, context prep, low-value, and abandoned work.
+- **ccusage JSON Import**: imports documented ccusage JSON output for broader structured usage coverage while recomputing costs with Token Studio official pricing.
+- **ccusage CLI Bridge UX**: the Dashboard only generates copyable local commands; the browser never runs external scanners.
+- **Source Health Center**: shows native stable, experimental, detected-only, and ccusage import-bridge status, recent usage, token-field trust, and privacy boundaries without exposing full local paths.
+- **Import / Budget Wizard**: paste or upload ccusage JSON in the Dashboard, dry-run first, inspect shape/session/event counts, unsafe fields, and unpriced models, then explicitly apply to SQLite.
+- **Quota Profiles v2**: supports rolling/fixed custom guardrail windows, reset anchors, warning thresholds, burn projection, reset countdown, and near/over/exceeded warnings on `/live`.
+- **Statusline Guardrails**: `token-studio statusline` prints recent-window tokens, burn rate, cache, budget usage, unpriced-model warnings, and open actions for terminal prompts, tmux, or Claude Code statusline.
+- **ROI Playbook Export**: `token-studio policy` exports Markdown, Claude Code, or AGENTS-style model-use snippets without editing project files.
+- **Advisor Action Loop**: turns Savings Simulator and ROI Advisor recommendations into open/done/dismissed actions and includes them in weekly Markdown reports.
+- **Collector Audit**: audits experimental collectors before upgrading support, without SQLite writes or full-path output.
+- **Work Evidence**: connects usage to projects, tasks, stages, value, output links, and work items.
+
+All dollar values are official-price conversions or simulations, not provider invoices.
+
+## Quick Start
+
+Recommended Node.js: 24. Minimum: `>=22.12.0`.
+
+```bash
+npx token-studio demo
+```
+
+Expected output:
+
+```text
+[demo] seeded 3 sessions and 2 daily rows into .../data/demo.sqlite
+[token-studio] UI  http://127.0.0.1:5173/  (Demo Mode)
+[token-studio] API http://127.0.0.1:4173
+```
+
+Common commands:
+
+```bash
+npx token-studio start
+npx token-studio import-usage --format=ccusage-cli --report=session --dry-run --yes
+npx token-studio statusline --format=text
+npx token-studio collectors
+npx token-studio privacy-check
+```
+
+From source:
+
+```bash
+git clone https://github.com/RyanCoreAI/token-studio-roi.git
+cd token-studio-roi
+npm install
+npm run demo
+```
+
+`demo` uses synthetic data and does not scan real `.claude`, `.codex`, Cursor, or Copilot logs. `start` reads an existing SQLite database and does not collect automatically. The `ccusage-cli` bridge explicitly runs the external ccusage local scanner; Token Studio only accepts structured JSON, rejects conversation-like fields, and ignores third-party cost fields.
+
+See [docs/first-run.md](docs/first-run.md) for the first-run flow. The Dashboard also derives first-run guidance from the current database: no data points to demo/import, data without actions points to `/review`, and budgets without event-level live data explain the `/live` window behavior.
+
+## Screenshots
+
+These screenshots are from demo mode or sanitized synthetic data, not real local logs.
+
+![Token Studio ROI dashboard](docs/assets/token-studio-v45-dashboard.png)
+
+![Token Studio ROI review](docs/assets/token-studio-v45-review.png)
+
+![Token Studio ROI live guardrails](docs/assets/token-studio-v45-live.png)
+
+Real collection requires explicit confirmation:
+
+```bash
+npx token-studio collect --sources=claude,codex
+```
+
+Non-interactive shells refuse collection unless `--yes` is passed.
+
+## Core Features
+
+- Collector registry: Claude Code, Codex CLI, Gemini CLI, OpenCode, OpenClaw, and Hermes Agent are v4.0 stable sources.
+- Experimental sources: Cursor, GitHub Copilot CLI, Qwen Code, Kimi, and Goose import only explicit token fields and never produce fake token rows.
+- Official-price conversion: published provider token prices only; unpriced models stay unpriced.
+- Work attribution: project, task type, output status, purpose, stage, value, and notes.
+- Output evidence: stores only URL, label, and output type.
+- ROI Evidence Score: checks whether attribution, outputs, manual confirmation, and work items are strong enough for ROI decisions.
+- ROI Savings Simulator: simulates model switching savings with official prices and keeps unpriced models out of dollar decisions.
+- ROI Advisor: local rules only, no LLM calls and no extra token usage.
+- Advisor Action Loop: add recommendations to an action list, mark them done or dismissed, and review trends without claiming causal savings.
+- Model Policy / ROI Playbook export: generates Markdown, Claude Code, or AGENTS-style strategy snippets from local structured history without writing files.
+- ccusage Import Bridge: `token-studio import-usage --format=ccusage-json` imports saved structured JSON, and `--format=ccusage-cli` explicitly invokes ccusage CLI; both avoid conversation content and third-party cost estimates.
+- Source Health Center: the Dashboard and `/api/source-health` show support tier, detected status, recent import/collection summary, and token-field trust without leaking full local paths.
+- Import / Budget Wizard: dashboard entry for ccusage JSON dry-run/apply, ccusage CLI Bridge command generation, and budget-window creation.
+- Quota Profiles v2: source-level custom token/cost guardrails with rolling/fixed windows, reset anchors, warning thresholds, and near/over/exceeded warnings.
+- Live Monitor: `/live` shows recent 15-minute token, model, cache, burn-rate metadata, budget windows, and guardrail warnings.
+- Statusline Guardrails: `token-studio statusline --format=text|json` reads SQLite only and prints recent-window tokens, burn rate, cache, budget usage, reset countdown, unpriced-model warnings, and open Advisor Actions; integration examples are in [docs/statusline.md](docs/statusline.md).
+- Collector Audit: `token-studio collectors --audit` returns a safe experimental-source summary without writing SQLite.
+- Terminal Report: `token-studio report --period=week --format=table|markdown|json` prints a quick ROI review summary.
+- Privacy check: scans for real DBs, AI log directories, `.env`, generated exports, personal paths, and likely secrets.
+- Demo mode: public demos use synthetic data and show a Demo Mode badge.
+- First-run onboarding: empty-data, import, budget, and review-action guidance without cloud sync or accounts.
+
+## Why Not Just ccusage / CodeBurn?
+
+ccusage, CodeBurn, TokenTracker, and token-dashboard are closer to token meters, TUIs, live burn-rate monitors, or broad collector dashboards. Token Studio ROI is not trying to replace those tools. It turns local token usage into reviewable work evidence: projects, tasks, purpose, stage, value, output links, work items, ROI Evidence, Advisor actions, and Model Policy.
+
+If you only need to know how many tokens you used today, ccusage or CodeBurn may be lighter. If you want to understand what those tokens produced and how to change next week's model strategy, Token Studio ROI is the better fit.
+
+## Privacy Boundary
+
+Token Studio ROI does not store:
+
+- prompts
+- responses
+- full transcripts
+- full file paths
+- command bodies
+- diff content
+
+Fine-grained analysis may store only token structure, source, model, timestamp, tool category, file extension, repo path hash, and privacy level.
+
+Run the publish gate:
+
+```bash
+npm run privacy:check
+```
+
+## API
+
+Stable interfaces:
+
+- `GET /api/data`
+- `GET /api/collectors`
+- `GET /api/source-health`
+- `GET /api/live`
+- `GET /api/budget-profiles`
+- `POST /api/budget-profiles`
+- `DELETE /api/budget-profiles`
+- `POST /api/import/ccusage-json`
+- `GET /api/advisor-actions`
+- `POST /api/advisor-actions`
+- `DELETE /api/advisor-actions/:id`
+- `GET /api/privacy-check`
+- `GET /api/model-policy.md`
+- `POST /api/collect`
+- `POST /api/session-annotations`
+- `POST /api/session-annotations/batch`
+- `POST /api/session-outputs`
+- `GET /api/auto-attribution/suggestions`
+- `POST /api/auto-attribution/apply`
+- `POST /api/auto-attribution/undo`
+- `POST /api/work-items`
+- `POST /api/work-items/link-sessions`
+- `DELETE /api/work-items/:id`
+
+All local write APIs remain loopback-only, local-Origin-only, and JSON-only. The server does not trust `X-Forwarded-For` for local access checks.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+npm run privacy:check
+```
+
+Development mode:
+
+```bash
+npm run dev
+```
+
+Default URLs:
+
+- UI: `http://127.0.0.1:5173`
+- API: `http://127.0.0.1:4173`
+
+## Public Readiness Checklist
+
+- [ ] `npm test`
+- [ ] `npm run build`
+- [ ] `npm run privacy:check`
+- [ ] demo screenshots come from demo mode
+- [ ] `/live` loads from demo mode or temporary SQLite
+- [ ] no real `data/usage.sqlite`
+- [ ] no `.claude/`, `.codex/`, `.env`
+- [ ] no raw conversation content
+- [ ] README says official-price conversion is not a provider invoice
+- [ ] NOTICE preserves attribution for the MIT prototype
+
+## License / Attribution
+
+MIT licensed. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md).
+
+Token Studio ROI is a standalone public packaging and productization effort by ryan. It preserves attribution for the earlier MIT prototype while making the public product, CLI, collector registry, privacy scanner, ROI evidence layer, work item model, advisor, and model policy workflow first-class Token Studio ROI features.

package/README.md

@@ -0,0 +1,220 @@
+# Token Studio ROI
+
+[English](README.en.md) | **中文**
+
+**Local AI Coding ROI Studio.** Token Studio ROI 不只是 token meter，而是一个本地隐私优先的 AI 编程复盘工具：记录 token 和官方价换算成本，连接项目、任务、工作阶段、产出证据和模型策略。
+
+```bash
+npx token-studio demo
+```
+
+首屏只需要记住三个差异：
+
+- **Work Evidence**：回答 token 花在哪、对应什么项目/任务/阶段/产出。
+- **Savings Simulator**：按官方公开 token 价格模拟模型切换后的节省空间。
+- **Model Policy**：把历史用量转成下周轻量/中等/重模型使用策略。
+
+默认不读取、不展示、不上传对话正文。真实采集必须显式确认。
+
+## Why Not ccusage / CodeBurn?
+
+| 工具 | 强项 | Token Studio ROI 的差异 |
+|---|---|---|
+| ccusage | 覆盖广、JSON 输出成熟 | Token Studio ROI 用 ccusage bridge 补覆盖，但重点做产出和复盘 |
+| CodeBurn | `npx` TUI 和本地成本观测 | Token Studio ROI 做周报、行动闭环和模型策略 |
+| TokenTracker / CodexBar | 桌面组件、限额可见性 | Token Studio ROI 做本地 ROI 决策和工作证据 |
+
+更完整的竞品参考和差异化记录见 [docs/competitive-notes.md](docs/competitive-notes.md)。
+
+## What Makes ROI Different?
+
+Token Studio ROI 的 v4.8 重点不是再堆一个 token meter，而是把统计结果转成可执行决策，并用 npm 一键启动、Source Health、CLI bridge、quota profiles 和 statusline integration 补齐竞品的覆盖面和实时入口：
+
+- **ROI Savings Simulator**：模拟“探索、测试、上下文整理、低价值或废弃任务从重模型切到轻量/中模型”时，按官方公开 token 价格可能少花多少。
+- **ccusage JSON Import**：兼容 ccusage documented JSON output，借它的多源生态导入结构化 token 数据，但成本仍由 Token Studio 官方价函数重算。
+- **ccusage CLI Bridge UX**：Dashboard 只生成可复制命令，不从浏览器运行外部扫描器；真实 bridge 仍由用户在本地终端显式执行。
+- **Source Health Center**：显示 native stable、experimental、detected-only、ccusage import-bridge 的状态、最近用量、token 字段可信度和隐私边界，不输出完整本机路径。
+- **Import / Budget Wizard**：在 Dashboard 里粘贴或上传 ccusage JSON，先 dry-run 看 shape、session/event 数、unsafe 字段和未定价模型，确认后才写 SQLite。
+- **Quota Profiles v2**：支持 rolling/fixed 自定义限额窗口、reset anchor、warning threshold，在 `/live` 看到 burn projection、reset countdown 和 near/over/exceeded warnings。
+- **Statusline Guardrails**：`token-studio statusline` 输出最近窗口 token、burn rate、cache、预算使用率、未定价模型提示和 open actions，适配终端 prompt、tmux 或 Claude Code statusline。
+- **ROI Playbook Export**：`token-studio policy` 导出 Markdown、Claude Code 或 AGENTS 风格模型使用策略片段，不自动修改项目文件。
+- **Advisor Action Loop**：把 Savings Simulator / ROI Advisor 建议加入行动清单，标记完成或忽略，并写入 Markdown 周报。
+- **Collector Audit**：先审计 experimental collector 是否真的有可靠 token 字段，再决定是否升级支持级别，不用估算值伪造用量。
+- **Work Evidence**：把 session 连接到项目、任务、阶段、价值、产出链接和 work item，回答“token 换来了什么”。
+
+所有 ROI 金额都写作“官方价换算 / 节省模拟”，不能当供应商账单或财务对账。
+
+## Quick Start
+
+推荐 Node.js 24，最低 Node.js `>=22.12.0`。
+
+```bash
+npx token-studio demo
+```
+
+预期输出类似：
+
+```text
+[demo] seeded 3 sessions and 2 daily rows into .../data/demo.sqlite
+[token-studio] UI  http://127.0.0.1:5173/  (Demo Mode)
+[token-studio] API http://127.0.0.1:4173
+```
+
+常用命令：
+
+```bash
+npx token-studio start
+npx token-studio import-usage --format=ccusage-cli --report=session --dry-run --yes
+npx token-studio statusline --format=text
+npx token-studio collectors
+npx token-studio privacy-check
+```
+
+从源码运行：
+
+```bash
+git clone https://github.com/RyanCoreAI/token-studio-roi.git
+cd token-studio-roi
+npm install
+npm run demo
+```
+
+`demo` 使用合成数据，不扫描真实 `.claude`、`.codex`、Cursor 或 Copilot 日志。`start` 只读取已有 SQLite，不自动采集。`ccusage-cli` bridge 会显式运行外部 ccusage 本地扫描器；Token Studio 只接收结构化 JSON，拒绝 conversation-like 字段，并忽略第三方 cost 字段。
+
+首次使用流程见 [docs/first-run.md](docs/first-run.md)。Dashboard 也会根据当前数据状态显示“首次使用”引导：无数据时提示 demo/import，有数据但无 action 时提示去 `/review`，有预算但无事件级 live 数据时解释 `/live` 的窗口口径。
+
+## Screenshots
+
+这些截图来自 demo mode 或脱敏合成数据，不包含真实本机日志。
+
+![Token Studio ROI dashboard](docs/assets/token-studio-v45-dashboard.png)
+
+![Token Studio ROI review](docs/assets/token-studio-v45-review.png)
+
+![Token Studio ROI live guardrails](docs/assets/token-studio-v45-live.png)
+
+真实采集需要显式确认：
+
+```bash
+npx token-studio collect --sources=claude,codex
+```
+
+非交互环境不会自动扫描本机日志；需要显式 `--yes` 才会继续。
+
+## Core Features
+
+- Collector registry：Claude Code、Codex CLI、Gemini CLI、OpenCode、OpenClaw、Hermes Agent 作为 v4.0 stable 来源。
+- Experimental sources：Cursor、GitHub Copilot CLI、Qwen Code、Kimi、Goose 仅在存在明确 token 字段时导入，不伪造 token 或费用。
+- Official-price conversion：按官方公开 token 单价换算，未公开美元价的模型保持未定价。
+- Work attribution：项目、任务类型、产出状态、工作目的、阶段、价值、备注。
+- Output evidence：只保存 URL、标签和类型，不抓取链接内容。
+- ROI Evidence Score：检查归因、产出、人工确认和 work item 是否足够支撑 ROI 判断。
+- ROI Savings Simulator：按官方价模拟模型切换后的节省空间，不把未定价模型算作 $0。
+- ROI Advisor：本地规则建议，不调用 LLM，不额外消耗 token。
+- Advisor Action Loop：把建议加入行动清单、标为完成或忽略；只做趋势复盘，不声称因果节省。
+- Model Policy / ROI Playbook：导出 Markdown、Claude Code 或 AGENTS 风格策略片段，把历史用量转成下周模型使用策略，不自动写文件。
+- ccusage Import Bridge：`token-studio import-usage --format=ccusage-json` 导入保存的结构化 JSON，`--format=ccusage-cli` 显式调用 ccusage CLI；两者都不保存正文，不采用第三方估算成本。
+- Source Health Center：Dashboard 和 `/api/source-health` 展示来源支持级别、检测状态、最近导入/采集摘要和 token 字段可信度，不泄露完整本机路径。
+- Import / Budget Wizard：Dashboard 内置 ccusage JSON dry-run/apply、ccusage CLI Bridge 命令生成器和预算窗口创建入口。
+- Quota Profiles v2：自定义 source 级 token/cost 预算窗口，支持 rolling/fixed、reset anchor 和 warning threshold，`/live` 显示 near/over/exceeded warnings。
+- Live Monitor：`/live` 轻量监控最近 15 分钟 token、模型、cache、burn rate、预算窗口和 guardrail warnings。
+- Statusline Guardrails：`token-studio statusline --format=text|json` 只读 SQLite，输出最近窗口 token、burn rate、cache、预算使用率、reset countdown、未定价模型提示和 open Advisor Actions；集成示例见 [docs/statusline.md](docs/statusline.md)。
+- Collector Audit：`token-studio collectors --audit` 只输出实验来源安全摘要，不写 SQLite。
+- Terminal Report：`token-studio report --period=week --format=table|markdown|json` 快速查看 ROI 复盘摘要。
+- Privacy check：公开前扫描真实 DB、AI 日志目录、`.env`、导出文件和个人路径。
+- Demo mode：公开演示默认使用合成数据并显示 Demo Mode 标识。
+- First-run onboarding：空数据、导入、预算、复盘 action 的首次使用引导，不新增云同步或账号。
+
+## Why Not Just ccusage / CodeBurn?
+
+ccusage、CodeBurn、TokenTracker 和 token-dashboard 更偏 token meter、TUI、实时 burn rate 或工具覆盖。Token Studio ROI 的核心不是替代这些统计器，而是把本地 token 消耗变成可复盘的工作证据：项目、任务、目的、阶段、价值、产出链接、work item、ROI Evidence、Advisor 行动项和 Model Policy。
+
+如果你只想知道今天用了多少 token，ccusage 或 CodeBurn 会更轻。如果你想知道这些 token 换来了什么产出、下周该怎么换模型策略，Token Studio ROI 更适合。
+
+## Privacy Boundary
+
+Token Studio ROI 不保存：
+
+- prompt
+- response
+- full transcript
+- full file path
+- command body
+- diff content
+
+细粒度分析只允许保存 token 结构、来源、模型、时间、tool category、文件扩展名、repo path hash 和 privacy level。
+
+运行公开检查：
+
+```bash
+npm run privacy:check
+```
+
+## API
+
+稳定接口：
+
+- `GET /api/data`
+- `GET /api/collectors`
+- `GET /api/source-health`
+- `GET /api/live`
+- `GET /api/budget-profiles`
+- `POST /api/budget-profiles`
+- `DELETE /api/budget-profiles`
+- `POST /api/import/ccusage-json`
+- `GET /api/advisor-actions`
+- `POST /api/advisor-actions`
+- `DELETE /api/advisor-actions/:id`
+- `GET /api/privacy-check`
+- `GET /api/model-policy.md`
+- `POST /api/collect`
+- `POST /api/session-annotations`
+- `POST /api/session-annotations/batch`
+- `POST /api/session-outputs`
+- `GET /api/auto-attribution/suggestions`
+- `POST /api/auto-attribution/apply`
+- `POST /api/auto-attribution/undo`
+- `POST /api/work-items`
+- `POST /api/work-items/link-sessions`
+- `DELETE /api/work-items/:id`
+
+所有写接口继续限制为 loopback、local Origin、JSON。服务端不信任 `X-Forwarded-For` 作为本机判断。
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+npm run privacy:check
+```
+
+开发模式：
+
+```bash
+npm run dev
+```
+
+默认地址：
+
+- UI: `http://127.0.0.1:5173`
+- API: `http://127.0.0.1:4173`
+
+## Public Readiness Checklist
+
+- [ ] `npm test`
+- [ ] `npm run build`
+- [ ] `npm run privacy:check`
+- [ ] demo screenshots come from demo mode
+- [ ] `/live` loads from demo mode or temporary SQLite
+- [ ] no real `data/usage.sqlite`
+- [ ] no `.claude/`, `.codex/`, `.env`
+- [ ] no raw conversation content
+- [ ] README explains official-price conversion is not a provider invoice
+- [ ] NOTICE keeps attribution for the MIT prototype
+
+## License / Attribution
+
+MIT licensed. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md).
+
+Token Studio ROI is a standalone public packaging and productization effort by ryan. It preserves attribution for the earlier MIT prototype while making the public product, CLI, collector registry, privacy scanner, ROI evidence layer, work item model, advisor, and model policy workflow first-class Token Studio ROI features.