agent-usage-all-in-one 0.8.1 → 0.9.0

package/CONTRIBUTING.md

@@ -6,7 +6,9 @@ accounting are release requirements rather than optional polish.
 
 ## Development
 
-Use macOS, Node.js 24+, and pnpm 10.33.3.
+Use macOS, Node.js 24+, and pnpm 10.33.3. That runtime is the product boundary
+(ADR 017); do not add Linux CI or a second install channel without superseding
+it.
 
 ```bash
 pnpm install

package/README.md

@@ -8,23 +8,37 @@
 [![npm](https://img.shields.io/npm/v/agent-usage-all-in-one.svg)](https://www.npmjs.com/package/agent-usage-all-in-one)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+> **Local multi-agent usage center on macOS — one dashboard, no cloud, no auto-switch.**
+
 Agent Usage is a macOS-first, fully local usage center for Codex, Claude Code,
-OpenCode, Grok, dsh, and Antigravity. One command opens a dashboard for native quota windows,
+OpenCode, Grok, dsh, Antigravity, and Cursor. One command opens a dashboard for native quota windows,
 reset times, tokens, model rankings, equivalent API cost, history, and diagnostics.
 It offers advice but never switches agents automatically.
 
+## Compared
+
+![Category comparison: provider UIs, token exporters, FinOps dashboards, and Agent Usage](docs/design/compare-sheet.png)
+
+Honest category axes and when to prefer Agent Usage vs provider UIs, exporters, or FinOps dashboards: [docs/comparison.md](docs/comparison.md).
+
+Sourced named competitors (ccusage, CodeBurn, Token Monitor, TokenTracker): [docs/named-competitors.md](docs/named-competitors.md).
+
+**Boundaries:** Cursor quota is experimental (no Tokens/history yet) · macOS only · multi-agent usage center for listed providers (don’t oversell “all-in-one”).
+
 ## Dashboard
 
 The dashboard has two primary tabs:
 
 - **Agent usage** preserves each provider's native five-hour, weekly, monthly,
   All models, and Fable-only quota labels and reset times.
-- **Tokens & model costs** supports 24-hour, 7-day, and 30-day ranges. It puts
-  totals first, then a GitHub-style last-year usage wall of headline-included
-  recorded Tokens, charts Provider share and the interactive daily trend, and
-  shows model rankings with visual share bars and the public API retail
-  equivalent of eligible token usage. The year wall is independent of the
-  selected 24-hour, 7-day, or 30-day window.
+- **Tokens & model costs** supports 24-hour, 7-day, and 30-day ranges. The
+  selected window, metric, and currency sit in the same sticky header as the
+  primary tabs. The summary board leads with the headline amount beside a
+  GitHub-style last-year usage wall of headline-included recorded Tokens, then
+  charts Provider share and the interactive daily trend, and shows model
+  rankings with visual share bars and the public API retail equivalent of
+  eligible token usage. The year wall is independent of the selected 24-hour,
+  7-day, or 30-day window.
 - **Settings** provides a centered two-column modal organized into five dedicated
   categories: Connections, Custom model rates, Monitoring, Diagnostics, and
   Data & privacy.
@@ -37,6 +51,8 @@ unclassified or unpriced instead of being guessed or displayed as zero.
 Grok Build/SuperGrok and xAI API are independent billing domains. Their quotas,
 tokens, and costs are never added together.
 
+![Cost honesty: actual charges, estimates, subscriptions, and API retail equivalent stay separate](docs/design/cost-semantics-4.png)
+
 ## Fast, progressive startup
 
 The loopback web service starts before connector discovery or data processing.
@@ -67,7 +83,19 @@ browser closed.
 
 ## Install and run
 
-Agent Usage requires macOS and Node.js 24 or newer.
+Agent Usage requires macOS and Node.js 24 or newer. That floor is the supported
+runtime (built-in `node:sqlite`, Keychain, LaunchAgent), not a documentation
+oversight — see [ADR 017](docs/adr/017-macos-node24-npm-runtime.md) and the
+[platform roadmap](docs/platform-roadmap.md). Linux and Homebrew / DMG are not
+shipped.
+
+![Quick start: install and open the local dashboard in three steps](docs/design/install-3-steps.png)
+
+```bash
+npx agent-usage-all-in-one
+```
+
+Optional global install:
 
 ```bash
 npm install --global agent-usage-all-in-one
@@ -113,10 +141,17 @@ agent-usage clear --yes
 | Grok · xAI API                   | No subscription quota                                                                                                                 | Official Management API aggregation                                                       | Actual USD amounts, balance, limit, and invoice when available                         |
 | dsh · DeepSeek API               | No subscription quota                                                                                                                 | Local dsh session logs across every profile, including front ends composed on dsh         | API retail equivalent at DeepSeek published peak/off-peak rates                        |
 | Antigravity · Gemini Code Assist | Official-client 5-hour sprint window and weekly baseline limit from live language server RPC, with local session observation fallback | Local conversation SQLite databases (~/.gemini/antigravity-cli and ~/.gemini/antigravity) | API retail equivalent at published Google Gemini and third-party model rates           |
+| Cursor                           | Experimental official Agent CLI `/usage` screen: Included percent and On-Demand spend-limit window; account-wide                      | Not collected in this version                                                             | On-Demand dollars are a quota window, not a bill                                       |
 
 Every value retains its authority and observation time. Account-wide and this-Mac
 evidence remain visibly distinct.
 
+## First launch / empty state
+
+Until connectors find local client data, the dashboard shows an honest empty state — connect or use an installed agent first:
+
+![Empty state when no agent data is connected yet](docs/design/empty-state-unconnected.png)
+
 ## Credentials and privacy
 
 Official-client credentials stay in their owning clients and are neither copied
@@ -128,7 +163,7 @@ All usage data remains local. JSON and CSV exports omit account identifiers,
 session IDs, cookies, OAuth tokens, and secret values by default. Raw observations
 are retained for 90 days, then transactionally compacted into UTC daily aggregates.
 Clearing local usage never deletes credentials owned by Codex, Claude Code,
-OpenCode, Grok, dsh, or Antigravity.
+OpenCode, Grok, dsh, Antigravity, or Cursor.
 
 ## Verification
 
@@ -146,6 +181,15 @@ See the [official pricing evidence](docs/research/official-pricing-sources-2026-
 [connector receipts](docs/release/connector-receipts-2026-08-28.md), and
 [open-source notices](docs/open-source.md).
 
+## Roadmap vision (not shipped)
+
+Linux, Homebrew, and DMG stay off the product until the conditions in
+[docs/platform-roadmap.md](docs/platform-roadmap.md) are met.
+
+> **VISION only — not shipped.** Menu bar / always-available glance is tracked in [issue #19](https://github.com/Blackman99/agent-usage-all-in-one/issues/19). Do not treat the mock as a current feature.
+
+![VISION (not shipped): menu bar glance concept — see issue #19](docs/design/menubar-vision.png)
+
 ## License and community
 
 MIT — see [LICENSE](LICENSE). Also see [CONTRIBUTING.md](CONTRIBUTING.md),

package/README.zh-CN.md

@@ -8,16 +8,28 @@
 [![npm](https://img.shields.io/npm/v/agent-usage-all-in-one.svg)](https://www.npmjs.com/package/agent-usage-all-in-one)
 [![许可证：MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+> **macOS 上的本地多 Agent 用量中心——一个仪表盘，无云端，不自动切换。**
+
 Agent Usage 是一个 macOS 优先、完全在本地运行的用量中心。一次启动即可统一查看
-Codex、Claude Code、OpenCode、Grok、dsh 与 Antigravity 的原生额度窗口、刷新时间、Token、模型排行、
+Codex、Claude Code、OpenCode、Grok、dsh、Antigravity 与 Cursor 的原生额度窗口、刷新时间、Token、模型排行、
 API 对等费用、历史与诊断。它只提供建议，不会自动切换 Agent。
 
+## 对比说明
+
+![类别对比：各平台官网、Token 导出工具、FinOps 看板与 Agent Usage](docs/design/compare-sheet.png)
+
+按类别对比何时更适合用 Agent Usage，而非各平台官网、导出工具或通用 FinOps 看板：[docs/comparison.md](docs/comparison.md)。
+
+具名竞品对照（ccusage、CodeBurn、Token Monitor、TokenTracker）：[docs/named-competitors.md](docs/named-competitors.md)。
+
+**边界：** Cursor 额度为实验性（尚无 Token/历史）· 仅 macOS · 对已列出的 Provider 做多 Agent 用量中心（不夸大 “all-in-one”）。
+
 ## 核心页面
 
 页面只有两个主要标签页：
 
 - **Agent 用量**：保留各平台原生的 5 小时、周、月、All models 和 Fable only 等额度标签与刷新时间。
-- **Token 与模型费用**：支持 24 小时、7 天和 30 天范围。顶部优先展示汇总信息，接着是过去一年的 GitHub 风格用量墙（只统计计入摘要的已记录 Token），随后用图表展示 Provider 占比和可交互的每日趋势，再以占比条呈现模型排行及符合条件的 Token 按公开 API 价格计算出的对等费用。用量墙与所选的 24 小时 / 7 天 / 30 天窗口相互独立。
+- **Token 与模型费用**：支持 24 小时、7 天和 30 天范围。所选窗口、指标与币种和主标签页共用同一条吸顶导航。汇总卡片左侧是金额或 Token 头条，右侧是过去一年的 GitHub 风格用量墙（只统计计入摘要的已记录 Token），随后用图表展示 Provider 占比和可交互的每日趋势，再以占比条呈现模型排行及符合条件的 Token 按公开 API 价格计算出的对等费用。用量墙与所选的 24 小时 / 7 天 / 30 天窗口相互独立。
 - **设置面板**：采用居中双栏结构，将连接管理、自定义模型费率、运行监控、系统诊断与数据隐私划分为 5 个独立分类，方便高效维护各项配置。
 
 实际账单、平台报告估算、固定订阅费和 API 对等零售价是四类互不混合的证据。
@@ -49,7 +61,13 @@ pnpm dev
 
 ## 安装与启动
 
-要求 macOS 和 Node.js 24 或更高版本。
+要求 macOS 和 Node.js 24 或更高版本。这是受支持的运行时（内置 `node:sqlite`、钥匙串、LaunchAgent），不是文档疏漏——见 [ADR 017](docs/adr/017-macos-node24-npm-runtime.md) 和 [平台路线图](docs/platform-roadmap.md)。尚未提供 Linux，也没有 Homebrew / DMG。
+
+```bash
+npx agent-usage-all-in-one
+```
+
+可选全局安装：
 
 ```bash
 npm install --global agent-usage-all-in-one
@@ -95,6 +113,7 @@ agent-usage clear --yes
 | Grok · xAI API                   | 没有订阅额度                                                                                  | 官方 Management API 聚合                                                     | 可用时展示实际美元金额、余额、上限与账单                       |
 | dsh · DeepSeek API               | 没有订阅额度                                                                                  | 本机 dsh 全部 profile 的会话日志，含基于 dsh 的终端前端                      | 按 DeepSeek 公布的峰谷价计算 API 对等零售价                    |
 | Antigravity · Gemini Code Assist | 通过官方 Language Server 本地 RPC 获取 5 小时冲刺窗口与周度基准额度，支持本地会话分析平滑降级 | 本地会话 SQLite 数据库（~/.gemini/antigravity-cli 与 ~/.gemini/antigravity） | 按公布的 Google Gemini 及第三方模型公开价格计算 API 对等零售价 |
+| Cursor                           | 实验性官方 Agent CLI `/usage` 屏幕：Included 百分比与 On-Demand 花费上限；账户全局            | 本版不采集                                                                   | On-Demand 美元是额度窗口，不是账单                             |
 
 每个数字都会保留来源权威等级和观测时间；账户全局与仅此 Mac 的证据始终明确区分。
 
@@ -106,7 +125,7 @@ Agent Usage 管理的凭据，存储在 macOS 钥匙串。本地页面使用一
 
 所有用量数据都留在本机。JSON/CSV 导出默认排除账户标识、会话 ID、Cookie、OAuth Token
 和密钥值。原始观测保留 90 天，之后在事务中压缩为 UTC 日汇总。清理本地用量永远不会删除
-Codex、Claude Code、OpenCode、Grok、dsh 或 Antigravity 官方客户端拥有的凭据。
+Codex、Claude Code、OpenCode、Grok、dsh、Antigravity 或 Cursor 官方客户端拥有的凭据。
 
 ## 验证
 
@@ -124,6 +143,12 @@ pnpm test:e2e
 [连接验证收据](docs/release/connector-receipts-2026-08-28.md)与
 [开源说明](docs/open-source.md)。
 
+## 路线图愿景（未交付）
+
+Linux、Homebrew 和 DMG 在满足 [docs/platform-roadmap.md](docs/platform-roadmap.md)
+中的条件之前不会进入产品。菜单栏一览见 [issue #19](https://github.com/Blackman99/agent-usage-all-in-one/issues/19)，
+仓库中的示意图只是愿景，不是现有功能。
+
 ## 许可证与社区
 
 MIT，详见 [LICENSE](LICENSE)。另请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、