@aaroncarry/pi-usage 0.1.0 → 0.2.1

package/README.md

@@ -6,31 +6,111 @@ A [pi](https://github.com/earendil-works/pi) extension that shows the balances a
 
 ## What you get
 
-The footer status line (default mode) follows the model you are using and shows its quota windows plus this session's consumption:
+The footer status line (default mode) follows the model you are using and shows its quota windows, this session's consumption, and a 7-day token sparkline:
 
 ```
-Codex 5h 13% · weekly 2% · session 10.0k tok $0.020
+Codex 5h 13% used · weekly 2% used · session 10.0k tok $0.020 · 7d ▁▁▁▁▁█▂ 66k
 ```
 
-`/usage` prints a card into the conversation (a custom entry — no popup, no focus steal):
+`/usage` prints a card into the conversation (a custom entry — no popup, no focus steal) with a 30-day usage summary at the bottom:
 
 ```
  Usage · 02:15
 
  ● Codex (Plus)
-   5h      ░░░░░░░░░░   0% · resets in 4h 54m
-   weekly  ░░░░░░░░░░   2% · resets in 6d 17h
+   5h      ░░░░░░░░░░   0% used · resets in 4h 54m
+   weekly  ░░░░░░░░░░   2% used · resets in 6d 17h
  ○ GLM
    Balance ¥21.46  recharged ¥118.00 · spent ¥96.54
  ○ DeepSeek
    Balance ¥38.48
+ Last 30 days ────────────────────────────
+ tokens ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▂▆███ 66k
+   gpt-5.6-luna  █████████████████░░░ 70%  34k
+   gpt-5.6-terra █████░░░░░░░░░░░░░░░ 21%  10k
 ```
 
+The dashboard opens on the **Charts** view; `v` cycles Charts → Heatmap → Insights → Table. Four views, one example each:
+
+## Trends dashboard
+
+Keyboard: `v` cycle views · `←→` period (7d / 30d / 90d / all) · `m` tokens ↔ cost · `g` group by provider / project (table) · `↑↓` + `enter` expand a provider row (table) · `esc` close.
+
+**Charts** — braille time series grouped by model, plus the model distribution. Same model ids served by different providers stay separate (`model (provider)`):
+
+```
+ Usage trends   [Charts]  Heatmap  Insights  Table     7d  [30d]  90d  all
+ Total 66k tok · Cost $0.04 · Peak 39k (9/13) · Streak 2d
+   39k ┤                                              ⢸⡄
+       │                                              ⣿⠘⡄
+       │                                              ⡇⡇⢸
+       │                                             ⢸⠇⢣⡎
+   17k ┤                                             ⢸ ⢸⠃
+       │                                             ⡏ ⢸⡆
+       │                                             ⡇⢀⡇⢇
+     0 └⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣸⣔⣱⠑⢼
+        08-14                08-29                09-13
+ ● Total  ● gpt-5.6-luna  ● gpt-5.6-terra  ● deepseek-flash
+ Models · 30d
+   gpt-5.6-luna (openai-codex) █████████████████░░░ 52%  34k
+   gpt-5.6-terra (lingsuan)    █████░░░░░░░░░░░░░░░ 24%  16k
+   deepseek-flash              ██░░░░░░░░░░░░░░░░░░  7%  4.5k
+ m metric · ←→ period · v view · g group · esc close
+```
+
+**Heatmap** — 12-week activity calendar with streaks:
+
+```
+ Activity · 12 weeks                Streak 2d
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  █  ░
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ▒  █
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
+ ░ none  ▒ light  ▓ mid  █ heavy
+ Peak 39k tokens on 9/13 · Total 66k
+```
+
+**Table** — provider→model line items; `enter` expands a provider into its models:
+
+```
+ Provider / Model     Sessions  Msgs  Cost  Tokens  ↑In   ↓Out  Cache
+ ▾ openai-codex               2    16 $0.04    44k   39k   5.3k   150k
+    gpt-5.6-terra             1     2 $0.02    10k   10k     53   9.7k
+    gpt-5.6-luna              1    14 $0.01    34k   29k   5.2k   140k
+ ▸ deepseek                   1     8 $0.003   4.5k   3.2k   1.2k    16k
+ ▸ lingsuan                   1     4      -    17k   16k   1.1k    12k
+ ─────────────────────────────────────────────────────────────────────
+ Total                        4    28 $0.04    66k   58k   7.6k   177k
+ Tokens = Input + Output + CacheWrite · ↑In = Input + CacheWrite
+```
+
+**Insights** — where the spend went, and waste patterns worth attention:
+
+```
+ What's contributing to your cost?  30d
+ Where it went
+      $0.02  gpt-5.6-terra (openai-codex) drives 57% of your spend
+          ~ routing some traffic to a cheaper model is the biggest cost lever
+      73%  of processed tokens came from cache reads
+      48%  of output is reasoning (thinking) tokens
+          ~ lowering the thinking level on routine tasks cuts this hidden spend
+ Worth attention
+      $0.50   2 likely cache misses re-read the prompt at full price
+          ~ pauses over 5 minutes and mid-session model switches invalidate the prompt cache
+```
+
+Trends are aggregated from pi's session files (`<agentDir>/sessions/**/*.jsonl`) with an incremental disk cache; forked session copies are deduplicated. Token metric = input + output + cache write.
+
 ## Commands
 
 | Command | Effect |
 |---|---|
-| `/usage` | Print the usage card into the session. Re-running refreshes: served from cache within the 5-minute TTL, refetched afterwards (15 s timeout). Cards persist in the session and are re-rendered on `/reload` and session restore. |
+| `/trends` | Open the interactive trends dashboard (charts, heatmap, table, insights). Same as `/usage trends`. |
+| `/usage` | Print the usage card (balances + 30-day summary) into the session. Re-running refreshes: served from cache within the 5-minute TTL, refetched afterwards (15 s timeout). Cards persist in the session and are re-rendered on `/reload` and session restore. |
+| `/usage trends` | Open the interactive trends dashboard (Table / Charts / Heatmap / Insights; `m` metric, `←→` period, `v` view, `↑↓`+`enter` table expand). |
 | `/usage active\|all\|off` | Switch the footer status line mode immediately and persist it to `usage.json` (tab-completed). |
 | `pi --usage-status all` | Set the footer mode for this run only (overrides `usage.json`, not written back). |
 
@@ -126,6 +206,7 @@ Optional config file `<agentDir>/usage.json`:
 
 - `intervalMinutes`: background refresh interval (default 5, minimum 1).
 - `status`: `active` (default) | `all` | `off`.
+- `sparkline`: set `false` to drop the 7-day sparkline from the footer status line.
 - `autoDetect`: set `false` to disable endpoint auto-detection for unknown providers.
 - `providers.<id>.enabled: false`: hide an account from the status line and card.
 - `providers.<id>.label`: display name override.

package/README.zh-CN.md

@@ -8,10 +8,10 @@
 
 ## 效果
 
-footer 状态行（默认模式）跟随当前模型，显示其额度窗口和本次会话消耗：
+footer 状态行（默认模式）跟随当前模型，显示其额度窗口、本次会话消耗和 7 天迷你趋势：
 
 ```
-Codex 5h 13% · weekly 2% · session 10.0k tok $0.020
+Codex 5h 13% used · weekly 2% used · session 10.0k tok $0.020 · 7d ▁▁▁▁▁█▂ 66k
 ```
 
 `/usage` 向会话流打印一张卡片（自定义条目渲染——非弹窗、不抢焦点）：
@@ -20,19 +20,98 @@ Codex 5h 13% · weekly 2% · session 10.0k tok $0.020
  Usage · 02:15
 
  ● Codex (Plus)
-   5h      ░░░░░░░░░░   0% · resets in 4h 54m
-   weekly  ░░░░░░░░░░   2% · resets in 6d 17h
+   5h      ░░░░░░░░░░   0% used · resets in 4h 54m
+   weekly  ░░░░░░░░░░   2% used · resets in 6d 17h
  ○ GLM
    Balance ¥21.46  recharged ¥118.00 · spent ¥96.54
  ○ DeepSeek
    Balance ¥38.48
+ Last 30 days ────────────────────────────
+ tokens ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▂▆███ 66k
+   gpt-5.6-luna  █████████████████░░░ 70%  34k
+   gpt-5.6-terra █████░░░░░░░░░░░░░░░ 21%  10k
 ```
 
+仪表盘默认打开 **Charts** 视图（盲文时间序列）；`v` 循环 Charts → Heatmap → Insights → Table。四个视图各举一例：
+
+## 趋势仪表盘
+
+按键：`v` 切视图 · `←→` 切周期（7d / 30d / 90d / all）· `m` 切 tokens ↔ cost · `g` 切换按厂商 / 按项目分组（明细表）· `↑↓` + `enter` 展开厂商行（明细表）· `esc` 关闭。
+
+**Charts** —— 按模型分组的盲文时间序列 + 模型分布。同一模型 id 由不同厂商提供时保持独立并标注 `(厂商)`：
+
+```
+ Usage trends   [Charts]  Heatmap  Insights  Table     7d  [30d]  90d  all
+ Total 66k tok · Cost $0.04 · Peak 39k (9/13) · Streak 2d
+   39k ┤                                              ⢸⡄
+       │                                              ⣿⠘⡄
+       │                                              ⡇⡇⢸
+       │                                             ⢸⠇⢣⡎
+   17k ┤                                             ⢸ ⢸⠃
+       │                                             ⡏ ⢸⡆
+       │                                             ⡇⢀⡇⢇
+     0 └⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣸⣔⣱⠑⢼
+        08-14                08-29                09-13
+ ● Total  ● gpt-5.6-luna  ● gpt-5.6-terra  ● deepseek-flash
+ Models · 30d
+   gpt-5.6-luna (openai-codex) █████████████████░░░ 52%  34k
+   gpt-5.6-terra (lingsuan)    █████░░░░░░░░░░░░░░░ 24%  16k
+   deepseek-flash              ██░░░░░░░░░░░░░░░░░░  7%  4.5k
+ m metric · ←→ period · v view · g group · esc close
+```
+
+**Heatmap** —— 12 周活动日历 + 连续天数：
+
+```
+ Activity · 12 weeks                Streak 2d
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  █  ░
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ▒  █
+  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░  ░
+ ░ none  ▒ light  ▓ mid  █ heavy
+ Peak 39k tokens on 9/13 · Total 66k
+```
+
+**Table** —— 厂商→模型明细条目；`enter` 展开某厂商的模型明细：
+
+```
+ Provider / Model     Sessions  Msgs  Cost  Tokens  ↑In   ↓Out  Cache
+ ▾ openai-codex               2    16 $0.04    44k   39k   5.3k   150k
+    gpt-5.6-terra             1     2 $0.02    10k   10k     53   9.7k
+    gpt-5.6-luna              1    14 $0.01    34k   29k   5.2k   140k
+ ▸ deepseek                   1     8 $0.003   4.5k   3.2k   1.2k    16k
+ ▸ lingsuan                   1     4      -    17k   16k   1.1k    12k
+ ─────────────────────────────────────────────────────────────────────
+ Total                        4    28 $0.04    66k   58k   7.6k   177k
+ Tokens = Input + Output + CacheWrite · ↑In = Input + CacheWrite
+```
+
+**Insights** —— 花费去向 + 值得注意的浪费模式：
+
+```
+ What's contributing to your cost?  30d
+ Where it went
+      $0.02  gpt-5.6-terra (openai-codex) drives 57% of your spend
+          ~ routing some traffic to a cheaper model is the biggest cost lever
+      73%  of processed tokens came from cache reads
+      48%  of output is reasoning (thinking) tokens
+          ~ lowering the thinking level on routine tasks cuts this hidden spend
+ Worth attention
+      $0.50   2 likely cache misses re-read the prompt at full price
+          ~ pauses over 5 minutes and mid-session model switches invalidate the prompt cache
+```
+
+趋势数据聚合自 pi 的会话文件（`<agentDir>/sessions/**/*.jsonl`），带增量磁盘缓存；分叉会话副本自动去重。Token 口径 = input + output + cache 写入。
 ## 命令
 
 | 命令 | 作用 |
 |---|---|
-| `/usage` | 向会话流打印用量卡片。重复执行即刷新：5 分钟 TTL 内秒回，过期则重新拉取（15 秒超时）。卡片留存在会话里，`/reload`、恢复旧会话时自动重放 |
+| `/trends` | 打开交互式趋势仪表盘（图表/热力图/明细表/洞察）。等价于 `/usage trends` |
+| `/usage` | 向会话流打印用量卡片（余额 + 30 天摘要）。重复执行即刷新：5 分钟 TTL 内秒回，过期则重新拉取（15 秒超时）。卡片留存在会话里，`/reload`、恢复旧会话时自动重放 |
+| `/usage trends` | 打开交互式趋势仪表盘（Table / Charts / Heatmap / Insights；`m` 切指标，`←→` 切周期，`v` 切视图，`↑↓`+`enter` 展开表格） |
 | `/usage active\|all\|off` | 立即切换 footer 状态行模式，并持久化到 `usage.json`（输入时有补全） |
 | `pi --usage-status all` | 指定本次运行的 footer 模式（覆盖 `usage.json`，不写回文件） |
 
@@ -127,6 +206,7 @@ pi install npm:@aaroncarry/pi-usage
 
 - `intervalMinutes`：后台刷新间隔（默认 5，最小 1）。
 - `status`：`active`（默认）/ `all` / `off`。
+- `sparkline`：设为 `false` 移除 footer 状态行的 7 天迷你趋势。
 - `autoDetect`：设为 `false` 关闭对未知厂商的余额端点自动探测。
 - `providers.<id>.enabled: false`：从状态行和卡片隐藏某账号。
 - `providers.<id>.label`：显示名覆盖。

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aaroncarry/pi-usage",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"description": "Usage and balance viewer for pi: subscription quota windows, prepaid balances, and session consumption in a footer status line and a /usage card",
 	"type": "module",
 	"license": "MIT",
@@ -12,7 +12,12 @@
 		"url": "https://github.com/aaroncarry/pi-usage/issues"
 	},
 	"homepage": "https://github.com/aaroncarry/pi-usage#readme",
-	"files": ["src", "README.md", "README.zh-CN.md", "LICENSE"],
+	"files": [
+		"src",
+		"README.md",
+		"README.zh-CN.md",
+		"LICENSE"
+	],
 	"keywords": [
 		"pi",
 		"pi-extension",
@@ -33,7 +38,9 @@
 		"access": "public"
 	},
 	"pi": {
-		"extensions": ["./src/index.ts"]
+		"extensions": [
+			"./src/index.ts"
+		]
 	},
 	"scripts": {
 		"typecheck": "tsc --noEmit",

package/src/config.ts

@@ -57,6 +57,8 @@ export interface BalanceConfig {
 	 * (New API relays, Sub2API, MiniMax, Zhipu). Default true.
 	 */
 	autoDetect?: boolean;
+	/** 7-day token sparkline in the footer status line. Default true. */
+	sparkline?: boolean;
 	/** Per-provider options; entries with `custom` define generic adapters. */
 	providers?: Record<string, ProviderConfig>;
 }
@@ -111,6 +113,7 @@ function sanitizeBalanceConfig(raw: Record<string, unknown>): BalanceConfig {
 		config.status = raw.status;
 	}
 	if (typeof raw.autoDetect === "boolean") config.autoDetect = raw.autoDetect;
+	if (typeof raw.sparkline === "boolean") config.sparkline = raw.sparkline;
 	if (isRecord(raw.providers)) {
 		const providers: Record<string, ProviderConfig> = {};
 		for (const [id, value] of Object.entries(raw.providers)) {

package/src/index.ts

@@ -10,15 +10,26 @@ import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import type { ExtensionAPI, ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import { isRecord, loadBalanceConfig, saveStatusMode, type StatusMode } from "./config.ts";
 import { getAgentDir, tokenFromRegistryAuth } from "./credentials.ts";
-import { sumSessionUsage, type SessionUsageTotals } from "./session-usage.ts";
+import { sumSessionUsage, formatTokens, type SessionUsageTotals } from "./session-usage.ts";
+import {
+	annotateModelLabels,
+	collectTrends,
+	dailyTotals,
+	distributionRows,
+	type TrendsData,
+} from "./trends/aggregate.ts";
+import { TrendsDashboard } from "./trends/dashboard.ts";
+import { sparklineString } from "./trends/render.ts";
 import { BalanceService } from "./service.ts";
-import { buildUsageCard, type UsageCardData } from "./ui/card.ts";
+import { buildUsageCard, type CardTrendsSummary, type UsageCardData } from "./ui/card.ts";
 import { formatStatusLine } from "./ui/statusline.ts";
 import type { CredentialResolver } from "./types.ts";
 
 const USAGE_ENTRY_TYPE = "usage-report";
 /** Bound /usage fetches so a hanging provider API cannot stall the command. */
 const USAGE_FETCH_TIMEOUT_MS = 15_000;
+/** Trends scans are cached in memory briefly so card/dashboard/sparkline share one scan. */
+const TRENDS_TTL_MS = 60_000;
 
 const STATUS_MODES = ["active", "all", "off"] as const;
 
@@ -31,6 +42,8 @@ export default function (pi: ExtensionAPI) {
 	let ui: ExtensionUIContext | undefined;
 	let activeProviderId: string | undefined;
 	let consumption: SessionUsageTotals | undefined;
+	let trendsCache: { data: TrendsData; at: number } | undefined;
+	let sparkline: string | undefined;
 	/** `/usage <mode>` override for this session; wins over flag and usage.json. */
 	let statusOverride: StatusMode | undefined;
 	/** `--usage-status` CLI flag; wins over usage.json. */
@@ -74,6 +87,7 @@ export default function (pi: ExtensionAPI) {
 			activeProviderId,
 			theme: ui.theme,
 			consumption,
+			sparkline,
 		});
 		ui.setStatus("usage", text);
 	}
@@ -96,29 +110,139 @@ export default function (pi: ExtensionAPI) {
 			activeProviderId: typeof entry.data.activeProviderId === "string" ? entry.data.activeProviderId : undefined,
 			generatedAt: typeof entry.data.generatedAt === "number" ? entry.data.generatedAt : Date.now(),
 		};
+		if (isRecord(entry.data.trends)) {
+			const raw = entry.data.trends;
+			const rawDays = raw.days;
+			const rawModels = raw.models;
+			if (
+				Array.isArray(rawDays) &&
+				typeof raw.endsAt === "number" &&
+				typeof raw.total === "number" &&
+				typeof raw.cost === "number" &&
+				Array.isArray(rawModels)
+			) {
+				data.trends = {
+					days: rawDays.filter((value): value is number => typeof value === "number"),
+					endsAt: raw.endsAt,
+					total: raw.total,
+					cost: raw.cost,
+					models: rawModels.filter(
+						(model): model is { label: string; tokens: number } =>
+							isRecord(model) && typeof model.label === "string" && typeof model.tokens === "number",
+					),
+				};
+			}
+		}
 		return buildUsageCard(data, theme);
 	});
 
+	/** Session trends with a small TTL so card, dashboard and sparkline share one scan. */
+	async function getTrends(signal?: AbortSignal): Promise<TrendsData> {
+		if (trendsCache && Date.now() - trendsCache.at < TRENDS_TTL_MS) return trendsCache.data;
+		const data = await collectTrends(getAgentDir(), { signal });
+		trendsCache = { data, at: Date.now() };
+		return data;
+	}
+
+	function costTotal(data: TrendsData, fromMs?: number): number {
+		return distributionRows(data, fromMs).reduce((total, row) => total + row.cost, 0);
+	}
+
+	/** 30-day summary embedded in the /usage card. */
+	async function cardTrendsSummary(): Promise<CardTrendsSummary | undefined> {
+		try {
+			const data = await getTrends();
+			const now = Date.now();
+			const from = now - 30 * 86_400_000;
+			const days = dailyTotals(data, "tokens", from);
+			const todayStart = new Date(now).setHours(0, 0, 0, 0);
+			const byDay = new Map(days.map((entry) => [entry.dayStart, entry.value]));
+			const aligned: number[] = [];
+			for (let index = 29; index >= 0; index--) {
+				aligned.push(byDay.get(todayStart - index * 86_400_000) ?? 0);
+			}
+			const models = annotateModelLabels(distributionRows(data, from))
+				.filter((row) => row.model !== "summaries")
+				.slice(0, 3)
+				.map((row) => ({ label: row.label, tokens: row.tokens }));
+			return {
+				days: aligned,
+				endsAt: todayStart,
+				total: aligned.reduce((total, value) => total + value, 0),
+				cost: costTotal(data, from),
+				models,
+			};
+		} catch {
+			return undefined;
+		}
+	}
+
+	/** Refresh the 7-day status-line sparkline once trends data is available. */
+	function refreshSparkline(): void {
+		if (!service || service.config.sparkline === false) return;
+		void getTrends()
+			.then((data) => {
+				const now = Date.now();
+				const days = dailyTotals(data, "tokens", now - 7 * 86_400_000);
+				const todayStart = new Date(now).setHours(0, 0, 0, 0);
+				const byDay = new Map(days.map((entry) => [entry.dayStart, entry.value]));
+				const aligned: number[] = [];
+				for (let index = 6; index >= 0; index--) {
+					aligned.push(byDay.get(todayStart - index * 86_400_000) ?? 0);
+				}
+				sparkline = sparklineString(aligned);
+				updateStatus();
+			})
+			.catch(() => undefined);
+	}
+
+	/** Open the interactive trends dashboard. */
+	async function openTrendsDashboard(ctx: ExtensionContext): Promise<void> {
+		if (ctx.mode !== "tui") {
+			ctx.ui.notify("/trends requires interactive mode", "warning");
+			return;
+		}
+		ensureService(ctx);
+		await ctx.ui.custom<undefined>((_tui, theme, _keybindings, done) => {
+			return new TrendsDashboard({ theme, done, data: getTrends() });
+		}, {
+			overlay: true,
+			overlayOptions: { width: "85%", maxHeight: "92%", anchor: "center" },
+		});
+	}
+
 	pi.registerCommand("usage", {
-		description: "Show usage card, or set the footer status line mode",
+		description: "Show usage card, open the trends dashboard, or set the footer status line mode",
 		getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
-			const matches = STATUS_MODES.filter((mode) => mode.startsWith(prefix.toLowerCase()));
-			return matches.length > 0 ? matches.map((mode) => ({ value: mode, label: mode })) : null;
+			const options: AutocompleteItem[] = [
+				{ value: "trends", label: "trends", description: "Open the interactive trends dashboard" },
+				{ value: "active", label: "active", description: "Footer: current account + session usage (default)" },
+				{ value: "all", label: "all", description: "Footer: all accounts on one line" },
+				{ value: "off", label: "off", description: "Footer: hide the status line" },
+			];
+			const matches = options.filter((option) => option.value.startsWith(prefix.toLowerCase()));
+			return matches.length > 0 ? matches : null;
 		},
 		handler: async (args, ctx) => {
 			const argument = args?.trim().toLowerCase();
 			if (!argument) {
 				const current = ensureService(ctx);
 				await current.refreshAll({ signal: AbortSignal.timeout(USAGE_FETCH_TIMEOUT_MS) });
+				const trends = await cardTrendsSummary();
 				pi.appendEntry(USAGE_ENTRY_TYPE, {
 					balances: current.getAll(),
 					activeProviderId,
 					generatedAt: Date.now(),
+					trends,
 				});
 				return;
 			}
+			if (argument === "trends") {
+				await openTrendsDashboard(ctx);
+				return;
+			}
 			if (!isStatusMode(argument)) {
-				ctx.ui.notify(`/usage: unknown mode "${argument}" — use active, all, or off`, "warning");
+				ctx.ui.notify(`/usage: unknown argument "${argument}" — use trends, active, all, or off`, "warning");
 				return;
 			}
 			statusOverride = argument;
@@ -128,6 +252,15 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// First-class command so new users discover the dashboard without knowing
+	// about the two-stage "/usage <space> trends" argument completion.
+	pi.registerCommand("trends", {
+		description: "Open the usage trends dashboard (charts, heatmap, table, insights)",
+		handler: async (_args, ctx) => {
+			await openTrendsDashboard(ctx);
+		},
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
 		// Session replacement tears the old service down via session_shutdown;
 		// build a fresh one bound to the new session context.
@@ -145,13 +278,16 @@ export default function (pi: ExtensionAPI) {
 		consumption = sumSessionUsage(ctx.sessionManager.getEntries());
 		next.start();
 		updateStatus();
+		refreshSparkline();
 	});
 
 	// Session tokens/cost are local data: refresh immediately after every turn
-	// instead of waiting for the provider quota polling cycle.
+	// instead of waiting for the provider quota polling cycle. The sparkline's
+	// today-bucket moves too; getTrends' TTL keeps this cheap.
 	pi.on("turn_end", async (_event, ctx) => {
 		consumption = sumSessionUsage(ctx.sessionManager.getEntries());
 		updateStatus();
+		refreshSparkline();
 	});
 
 	pi.on("model_select", async (event) => {
@@ -164,5 +300,6 @@ export default function (pi: ExtensionAPI) {
 		service = undefined;
 		ui = undefined;
 		consumption = undefined;
+		sparkline = undefined;
 	});
 }