reasonix 0.4.23 → 0.4.24

package/README.md

@@ -148,6 +148,29 @@ reasonix code › /commit "fix: findByEmail case-insensitive"
   writable).
 - `npx reasonix code --no-session` — ephemeral; nothing saved.
 
+### `reasonix stats` — how much did you actually save?
+
+Every turn `reasonix chat|code|run` runs appends a compact record
+(tokens + cost + what Claude Sonnet 4.6 would have charged) to
+`~/.reasonix/usage.jsonl`. `reasonix stats` with no args rolls that
+log into today / week / month / all-time windows:
+
+```
+Reasonix usage — /Users/you/.reasonix/usage.jsonl
+
+            turns  cache hit    cost (USD)      vs Claude     saved
+----------------------------------------------------------------------
+today           8      95.1%     $0.004821        $0.1348      96.4%
+week           34      93.8%     $0.023104        $0.6081      96.2%
+month         127      94.2%     $0.081530        $2.1452      96.2%
+all-time      342      94.0%     $0.210881        $5.8934      96.4%
+```
+
+Privacy: only tokens, costs, and the session name you chose land
+in the file. No prompts, no completions, no tool arguments.
+`reasonix stats <transcript>` keeps the old per-file summary
+(assistant turns + tool calls) for scripts that already use it.
+
 ### Staying current
 
 The panel header shows the running version next to `Reasonix` (e.g.

package/dist/cli/index.js

@@ -2459,10 +2459,10 @@ function registerFilesystemTools(registry, opts) {
       const after = before.slice(0, firstIdx) + args.replace + before.slice(firstIdx + args.search.length);
       await fs.writeFile(abs, after, "utf8");
       const rel = pathMod.relative(rootDir, abs);
-      const header = `edited ${rel} (${args.search.length}\u2192${args.replace.length} chars)`;
+      const header2 = `edited ${rel} (${args.search.length}\u2192${args.replace.length} chars)`;
       const startLine = before.slice(0, firstIdx).split(/\r?\n/).length;
       const diff = renderEditDiff(args.search, args.replace, startLine);
-      return `${header}
+      return `${header2}
 ${diff}`;
     }
   });
@@ -3005,11 +3005,11 @@ function registerShellTools(registry, opts) {
   return registry;
 }
 function formatCommandResult(cmd, r) {
-  const header = r.timedOut ? `$ ${cmd}
+  const header2 = r.timedOut ? `$ ${cmd}
 [killed after timeout]` : `$ ${cmd}
 [exit ${r.exitCode ?? "?"}]`;
-  return r.output ? `${header}
-${r.output}` : header;
+  return r.output ? `${header2}
+${r.output}` : header2;
 }
 
 // src/tools/web.ts
@@ -3174,9 +3174,9 @@ function registerWebTools(registry, opts = {}) {
         throw new Error("web_fetch: url must start with http:// or https://");
       }
       const page = await webFetch(args.url, { maxChars: maxFetchChars, signal: ctx?.signal });
-      const header = page.title ? `${page.title}
+      const header2 = page.title ? `${page.title}
 ${page.url}` : page.url;
-      return `${header}
+      return `${header2}
 
 ${page.text}`;
     }
@@ -4582,8 +4582,134 @@ function isNpxInstall() {
   return false;
 }
 
+// src/usage.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync8, statSync as statSync3 } from "fs";
+import { homedir as homedir5 } from "os";
+import { dirname as dirname6, join as join6 } from "path";
+function defaultUsageLogPath(homeDirOverride) {
+  return join6(homeDirOverride ?? homedir5(), ".reasonix", "usage.jsonl");
+}
+function appendUsage(input) {
+  const record = {
+    ts: input.now ?? Date.now(),
+    session: input.session,
+    model: input.model,
+    promptTokens: input.usage.promptTokens,
+    completionTokens: input.usage.completionTokens,
+    cacheHitTokens: input.usage.promptCacheHitTokens,
+    cacheMissTokens: input.usage.promptCacheMissTokens,
+    costUsd: costUsd(input.model, input.usage),
+    claudeEquivUsd: claudeEquivalentCost(input.usage)
+  };
+  const path = input.path ?? defaultUsageLogPath();
+  try {
+    mkdirSync5(dirname6(path), { recursive: true });
+    appendFileSync2(path, `${JSON.stringify(record)}
+`, "utf8");
+  } catch {
+  }
+  return record;
+}
+function readUsageLog(path = defaultUsageLogPath()) {
+  if (!existsSync6(path)) return [];
+  let raw;
+  try {
+    raw = readFileSync8(path, "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line);
+      if (isValidRecord(rec)) out.push(rec);
+    } catch {
+    }
+  }
+  return out;
+}
+function isValidRecord(rec) {
+  if (!rec || typeof rec !== "object") return false;
+  const r = rec;
+  return typeof r.ts === "number" && typeof r.model === "string" && typeof r.promptTokens === "number" && typeof r.completionTokens === "number" && typeof r.cacheHitTokens === "number" && typeof r.cacheMissTokens === "number" && typeof r.costUsd === "number" && typeof r.claudeEquivUsd === "number";
+}
+function bucketCacheHitRatio(b) {
+  const denom = b.cacheHitTokens + b.cacheMissTokens;
+  return denom > 0 ? b.cacheHitTokens / denom : 0;
+}
+function bucketSavingsFraction(b) {
+  return b.claudeEquivUsd > 0 ? 1 - b.costUsd / b.claudeEquivUsd : 0;
+}
+function emptyBucket(label, since) {
+  return {
+    label,
+    since,
+    turns: 0,
+    promptTokens: 0,
+    completionTokens: 0,
+    cacheHitTokens: 0,
+    cacheMissTokens: 0,
+    costUsd: 0,
+    claudeEquivUsd: 0
+  };
+}
+function addToBucket(b, r) {
+  b.turns += 1;
+  b.promptTokens += r.promptTokens;
+  b.completionTokens += r.completionTokens;
+  b.cacheHitTokens += r.cacheHitTokens;
+  b.cacheMissTokens += r.cacheMissTokens;
+  b.costUsd += r.costUsd;
+  b.claudeEquivUsd += r.claudeEquivUsd;
+}
+function aggregateUsage(records, opts = {}) {
+  const now = opts.now ?? Date.now();
+  const day = 24 * 60 * 60 * 1e3;
+  const today = emptyBucket("today", now - day);
+  const week = emptyBucket("week", now - 7 * day);
+  const month = emptyBucket("month", now - 30 * day);
+  const all = emptyBucket("all-time", 0);
+  const modelCounts = /* @__PURE__ */ new Map();
+  const sessionCounts = /* @__PURE__ */ new Map();
+  let firstSeen = null;
+  let lastSeen = null;
+  for (const r of records) {
+    addToBucket(all, r);
+    if (r.ts >= today.since) addToBucket(today, r);
+    if (r.ts >= week.since) addToBucket(week, r);
+    if (r.ts >= month.since) addToBucket(month, r);
+    modelCounts.set(r.model, (modelCounts.get(r.model) ?? 0) + 1);
+    const sessKey = r.session ?? "(ephemeral)";
+    sessionCounts.set(sessKey, (sessionCounts.get(sessKey) ?? 0) + 1);
+    if (firstSeen === null || r.ts < firstSeen) firstSeen = r.ts;
+    if (lastSeen === null || r.ts > lastSeen) lastSeen = r.ts;
+  }
+  const byModel = Array.from(modelCounts.entries()).map(([model, turns]) => ({ model, turns })).sort((a, b) => b.turns - a.turns);
+  const bySession = Array.from(sessionCounts.entries()).map(([session, turns]) => ({ session, turns })).sort((a, b) => b.turns - a.turns);
+  return {
+    buckets: [today, week, month, all],
+    byModel,
+    bySession,
+    firstSeen,
+    lastSeen
+  };
+}
+function formatLogSize(path = defaultUsageLogPath()) {
+  if (!existsSync6(path)) return "";
+  try {
+    const s = statSync3(path);
+    const bytes = s.size;
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  } catch {
+    return "";
+  }
+}
+
 // src/cli/commands/chat.tsx
-import { existsSync as existsSync6, statSync as statSync3 } from "fs";
+import { existsSync as existsSync8, statSync as statSync4 } from "fs";
 import { render } from "ink";
 import React15, { useState as useState7 } from "react";
 
@@ -4622,7 +4748,7 @@ function registerSkillTools(registry, opts = {}) {
         });
       }
       const rawArgs = typeof args.arguments === "string" ? args.arguments.trim() : "";
-      const header = [
+      const header2 = [
         `# Skill: ${skill.name}`,
         skill.description ? `> ${skill.description}` : "",
         `(scope: ${skill.scope} \xB7 ${skill.path})`
@@ -4630,7 +4756,7 @@ function registerSkillTools(registry, opts = {}) {
       const argsBlock = rawArgs ? `
 
 Arguments: ${rawArgs}` : "";
-      return `${header}
+      return `${header2}
 
 ${skill.body}${argsBlock}`;
     }
@@ -4859,7 +4985,7 @@ function parseBlocks(raw) {
       if (/^\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$/.test(next)) {
         flushPara();
         flushList();
-        const header = splitTableRow(line);
+        const header2 = splitTableRow(line);
         const rows = [];
         let j = i + 2;
         while (j < lines.length) {
@@ -4868,7 +4994,7 @@ function parseBlocks(raw) {
           rows.push(splitTableRow(r));
           j++;
         }
-        out.push({ kind: "table", header, rows });
+        out.push({ kind: "table", header: header2, rows });
         i = j - 1;
         continue;
       }
@@ -4935,7 +5061,7 @@ function TableBlockRow({ block }) {
     for (const r of block.rows) cellLengths.push(displayWidth(r[c] ?? ""));
     widths.push(Math.min(40, Math.max(3, ...cellLengths)));
   }
-  const pad2 = (s, w) => {
+  const pad3 = (s, w) => {
     const dw = displayWidth(s);
     if (dw >= w) return s;
     return s + " ".repeat(w - dw);
@@ -4943,12 +5069,12 @@ function TableBlockRow({ block }) {
   const separator = widths.map((w) => "\u2500".repeat(w)).join("\u2500\u253C\u2500");
   return /* @__PURE__ */ React2.createElement(Box2, { flexDirection: "column" }, /* @__PURE__ */ React2.createElement(Box2, null, block.header.map((cell, ci) => (
     // biome-ignore lint/suspicious/noArrayIndexKey: table columns never reorder — derived from a static header array
-    /* @__PURE__ */ React2.createElement(Text2, { key: `h-${ci}`, bold: true, color: "cyan" }, pad2(cell, widths[ci] ?? 3), ci < colCount - 1 ? " \u2502 " : "")
+    /* @__PURE__ */ React2.createElement(Text2, { key: `h-${ci}`, bold: true, color: "cyan" }, pad3(cell, widths[ci] ?? 3), ci < colCount - 1 ? " \u2502 " : "")
   ))), /* @__PURE__ */ React2.createElement(Text2, { dimColor: true }, separator), block.rows.map((row2, ri) => (
     // biome-ignore lint/suspicious/noArrayIndexKey: table rows render in source order and don't reorder
     /* @__PURE__ */ React2.createElement(Box2, { key: `r-${ri}` }, Array.from({ length: colCount }).map((_, ci) => (
       // biome-ignore lint/suspicious/noArrayIndexKey: same — column axis is fixed by the table shape
-      /* @__PURE__ */ React2.createElement(Text2, { key: `c-${ri}-${ci}` }, pad2(row2[ci] ?? "", widths[ci] ?? 3), ci < colCount - 1 ? " \u2502 " : "")
+      /* @__PURE__ */ React2.createElement(Text2, { key: `c-${ri}-${ci}` }, pad3(row2[ci] ?? "", widths[ci] ?? 3), ci < colCount - 1 ? " \u2502 " : "")
     )))
   )));
 }
@@ -5593,6 +5719,114 @@ function formatTokens(n) {
 
 // src/cli/ui/slash.ts
 import { spawnSync } from "child_process";
+
+// src/cli/commands/stats.ts
+import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
+function statsCommand(opts) {
+  if (opts.transcript) {
+    transcriptSummary(opts.transcript);
+    return;
+  }
+  dashboard(opts);
+}
+function transcriptSummary(path) {
+  if (!existsSync7(path)) {
+    console.error(`no such transcript: ${path}`);
+    process.exit(1);
+  }
+  const lines = readFileSync9(path, "utf8").split(/\r?\n/).filter(Boolean);
+  let assistantTurns = 0;
+  let toolCalls = 0;
+  let lastTurn = 0;
+  for (const line of lines) {
+    try {
+      const rec = JSON.parse(line);
+      if (rec.role === "assistant_final") assistantTurns++;
+      if (rec.role === "tool") toolCalls++;
+      if (typeof rec.turn === "number") lastTurn = Math.max(lastTurn, rec.turn);
+    } catch {
+    }
+  }
+  console.log(`transcript:       ${path}`);
+  console.log(`assistant turns:  ${assistantTurns}`);
+  console.log(`tool invocations: ${toolCalls}`);
+  console.log(`last turn index:  ${lastTurn}`);
+}
+function dashboard(opts) {
+  const path = opts.logPath ?? defaultUsageLogPath();
+  const records = readUsageLog(path);
+  if (records.length === 0) {
+    console.log("no usage data yet.");
+    console.log("");
+    console.log(`  ${path}`);
+    console.log("");
+    console.log("run `reasonix chat`, `reasonix code`, or `reasonix run <task>` \u2014 every turn");
+    console.log("appends one line to the log and `reasonix stats` will roll it up.");
+    return;
+  }
+  const agg = aggregateUsage(records, { now: opts.now });
+  console.log(renderDashboard(agg, path));
+}
+function renderDashboard(agg, logPath) {
+  const lines = [];
+  const size = formatLogSize(logPath);
+  lines.push(`Reasonix usage \u2014 ${logPath}${size ? ` (${size})` : ""}`);
+  lines.push("");
+  lines.push(header());
+  lines.push(divider());
+  for (const b of agg.buckets) {
+    lines.push(bucketRow(b));
+  }
+  lines.push("");
+  if (agg.byModel.length > 0) {
+    const totalTurns = agg.buckets[agg.buckets.length - 1]?.turns ?? 0;
+    const top = agg.byModel[0];
+    if (top && totalTurns > 0) {
+      const pct2 = (top.turns / totalTurns * 100).toFixed(0);
+      lines.push(`most used model:   ${top.model} (${pct2}% of turns)`);
+    }
+  }
+  if (agg.bySession.length > 0) {
+    const top = agg.bySession[0];
+    if (top) lines.push(`top session:       ${top.session} (${top.turns} turns)`);
+  }
+  if (agg.firstSeen) {
+    lines.push(`tracked since:     ${new Date(agg.firstSeen).toISOString().slice(0, 10)}`);
+  }
+  return lines.join("\n");
+}
+function header() {
+  return [
+    pad("", 10),
+    pad("turns", 8, "right"),
+    pad("cache hit", 10, "right"),
+    pad("cost (USD)", 14, "right"),
+    pad("vs Claude", 14, "right"),
+    pad("saved", 10, "right")
+  ].join("  ");
+}
+function divider() {
+  return "-".repeat(70);
+}
+function bucketRow(b) {
+  const hit = bucketCacheHitRatio(b);
+  const savings = bucketSavingsFraction(b);
+  return [
+    pad(b.label, 10),
+    pad(b.turns.toString(), 8, "right"),
+    pad(b.turns > 0 ? `${(hit * 100).toFixed(1)}%` : "\u2014", 10, "right"),
+    pad(b.turns > 0 ? `$${b.costUsd.toFixed(6)}` : "\u2014", 14, "right"),
+    pad(b.turns > 0 ? `$${b.claudeEquivUsd.toFixed(4)}` : "\u2014", 14, "right"),
+    pad(b.turns > 0 && savings > 0 ? `${(savings * 100).toFixed(1)}%` : "\u2014", 10, "right")
+  ].join("  ");
+}
+function pad(s, width, align = "left") {
+  if (s.length >= width) return s;
+  const fill = " ".repeat(width - s.length);
+  return align === "right" ? `${fill}${s}` : `${s}${fill}`;
+}
+
+// src/cli/ui/slash.ts
 var SLASH_COMMANDS = [
   { cmd: "help", summary: "show the full command reference" },
   { cmd: "status", summary: "current model, flags, context, session" },
@@ -5625,6 +5859,10 @@ var SLASH_COMMANDS = [
     cmd: "update",
     summary: "show current vs latest version + the shell command to upgrade"
   },
+  {
+    cmd: "stats",
+    summary: "cross-session cost dashboard (today / week / month / all-time \xB7 cache hit \xB7 vs Claude)"
+  },
   { cmd: "think", summary: "dump the last turn's full R1 reasoning (reasoner only)" },
   { cmd: "retry", summary: "truncate & resend your last message (fresh sample)" },
   { cmd: "compact", argsHint: "[cap]", summary: "shrink oversized tool results in the log" },
@@ -5805,6 +6043,9 @@ function handleSlash(cmd, args, loop, ctx = {}) {
     case "update": {
       return handleUpdateSlash(ctx);
     }
+    case "stats": {
+      return handleStatsSlash();
+    }
     case "think":
     case "reasoning": {
       const raw = loop.scratch.reasoning;
@@ -6041,6 +6282,24 @@ ${entry.text}`
       return { unknown: true, info: `unknown command: /${cmd}  (try /help)` };
   }
 }
+function handleStatsSlash() {
+  const path = defaultUsageLogPath();
+  const records = readUsageLog(path);
+  if (records.length === 0) {
+    return {
+      info: [
+        "no usage data yet.",
+        "",
+        `  ${path}`,
+        "",
+        "every turn you run here appends one record \u2014 this session's turns",
+        "will show up in the dashboard once you send a message."
+      ].join("\n")
+    };
+  }
+  const agg = aggregateUsage(records);
+  return { info: renderDashboard(agg, path) };
+}
 function handleUpdateSlash(ctx) {
   const latest = ctx.latestVersion ?? null;
   const lines = [`current: reasonix ${VERSION}`];
@@ -6185,12 +6444,12 @@ function handleSkillSlash(args, ctx) {
     };
   }
   const extra = args.slice(1).join(" ").trim();
-  const header = `# Skill: ${skill.name}${skill.description ? `
+  const header2 = `# Skill: ${skill.name}${skill.description ? `
 > ${skill.description}` : ""}`;
   const argsLine = extra ? `
 
 Arguments: ${extra}` : "";
-  const payload = `${header}
+  const payload = `${header2}
 
 ${skill.body}${argsLine}`;
   return {
@@ -6368,9 +6627,9 @@ function appendSection(lines, label, section) {
 }
 function formatToolList(history) {
   const total = history.length;
-  const header = `Tool calls in this session (${total}, most recent first):`;
+  const header2 = `Tool calls in this session (${total}, most recent first):`;
   const shown = Math.min(total, 10);
-  const lines = [header];
+  const lines = [header2];
   for (let i = 0; i < shown; i++) {
     const entry = history[total - 1 - i];
     if (!entry) continue;
@@ -6864,6 +7123,13 @@ function App({
             const repairNote = ev.repair ? describeRepair(ev.repair) : "";
             setStreaming(null);
             setSummary(loop.stats.summary());
+            if (ev.stats?.usage) {
+              appendUsage({
+                session: session ?? null,
+                model: ev.stats.model,
+                usage: ev.stats.usage
+              });
+            }
             const finalText = ev.content || streamRef.text;
             const iterReasoning = streamRef.reasoning || void 0;
             const iterId = `${assistantId}-i${assistantIterCounter.current++}`;
@@ -7006,6 +7272,7 @@ function App({
       mcpSpecs,
       mcpServers,
       planMode,
+      session,
       slashSelected,
       togglePlanMode,
       writeTranscript
@@ -7268,8 +7535,8 @@ function formatEditResults(results) {
   });
   const ok = results.filter((r) => r.status === "applied" || r.status === "created").length;
   const total = results.length;
-  const header = `\u25B8 edit blocks: ${ok}/${total} applied \u2014 /undo to roll back, or \`git diff\` to review`;
-  return [header, ...lines].join("\n");
+  const header2 = `\u25B8 edit blocks: ${ok}/${total} applied \u2014 /undo to roll back, or \`git diff\` to review`;
+  return [header2, ...lines].join("\n");
 }
 function formatPendingPreview(blocks) {
   const lines = blocks.map((b) => {
@@ -7278,8 +7545,8 @@ function formatPendingPreview(blocks) {
     const tag = b.search === "" ? "NEW " : "    ";
     return `  ${tag}${b.path}  (-${removed} +${added} lines)`;
   });
-  const header = `\u25B8 ${blocks.length} pending edit block(s) \u2014 /apply (or y) to commit \xB7 /discard (or n) to drop`;
-  return [header, ...lines].join("\n");
+  const header2 = `\u25B8 ${blocks.length} pending edit block(s) \u2014 /apply (or y) to commit \xB7 /discard (or n) to drop`;
+  return [header2, ...lines].join("\n");
 }
 function countLines2(s) {
   if (s.length === 0) return 0;
@@ -7524,7 +7791,7 @@ async function chatCommand(opts) {
     const prior = loadSessionMessages(opts.session);
     if (prior.length > 0) {
       const p = sessionPath(opts.session);
-      const mtime = existsSync6(p) ? statSync3(p).mtime : /* @__PURE__ */ new Date();
+      const mtime = existsSync8(p) ? statSync4(p).mtime : /* @__PURE__ */ new Date();
       sessionPreview = { messageCount: prior.length, lastActive: mtime };
     }
   } else if (opts.session && opts.forceNew) {
@@ -7867,7 +8134,7 @@ function mcpListCommand(opts) {
   console.log("Popular MCP servers you can bridge into Reasonix:");
   console.log("");
   for (const entry of MCP_CATALOG) {
-    console.log(`  ${pad(entry.name, 12)} ${entry.summary}`);
+    console.log(`  ${pad2(entry.name, 12)} ${entry.summary}`);
     console.log(`               ${mcpCommandFor(entry)}`);
     if (entry.note) console.log(`               \xB7 ${entry.note}`);
     console.log("");
@@ -7880,7 +8147,7 @@ function mcpListCommand(opts) {
     "        https://mcp.so                                   \u2014  community-maintained catalog"
   );
 }
-function pad(s, width) {
+function pad2(s, width) {
   return s.length >= width ? s : s + " ".repeat(width - s.length);
 }
 
@@ -8149,6 +8416,9 @@ async function runCommand2(opts) {
 [error] ${ev.error}
 `);
       if (ev.role === "done") process.stdout.write("\n");
+      if (ev.role === "assistant_final" && ev.stats?.usage) {
+        appendUsage({ session: null, model: ev.stats.model, usage: ev.stats.usage });
+      }
       if (transcriptStream && ev.role !== "assistant_delta") {
         writeRecord(transcriptStream, recordFromLoopEvent(ev, { model: opts.model, prefixHash }));
       }
@@ -8545,32 +8815,6 @@ async function setupCommand(_opts = {}) {
   await waitUntilExit();
 }
 
-// src/cli/commands/stats.ts
-import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
-function statsCommand(opts) {
-  if (!existsSync7(opts.transcript)) {
-    console.error(`no such transcript: ${opts.transcript}`);
-    process.exit(1);
-  }
-  const lines = readFileSync8(opts.transcript, "utf8").split(/\r?\n/).filter(Boolean);
-  let assistantTurns = 0;
-  let toolCalls = 0;
-  let lastTurn = 0;
-  for (const line of lines) {
-    try {
-      const rec = JSON.parse(line);
-      if (rec.role === "assistant_final") assistantTurns++;
-      if (rec.role === "tool") toolCalls++;
-      if (typeof rec.turn === "number") lastTurn = Math.max(lastTurn, rec.turn);
-    } catch {
-    }
-  }
-  console.log(`transcript:       ${opts.transcript}`);
-  console.log(`assistant turns:  ${assistantTurns}`);
-  console.log(`tool invocations: ${toolCalls}`);
-  console.log(`last turn index:  ${lastTurn}`);
-}
-
 // src/cli/commands/update.ts
 import { spawn as spawn4 } from "child_process";
 function planUpdate(input) {
@@ -8796,7 +9040,9 @@ program.command("run <task>").description("Run a single task non-interactively,
     mcpPrefix: opts.mcpPrefix
   });
 });
-program.command("stats <transcript>").description("Summarize a JSONL transcript produced by `reasonix chat --transcript`.").action((transcript) => {
+program.command("stats [transcript]").description(
+  "Show usage dashboard (today / week / month / all-time \xB7 turns \xB7 cache hit \xB7 cost \xB7 savings vs Claude). Pass a transcript path to fall back to the per-file summary (assistant turns + tool calls)."
+).action((transcript) => {
   statsCommand({ transcript });
 });
 program.command("sessions [name]").description("List saved chat sessions, or inspect one by name.").option("-v, --verbose", "Include system prompts + tool-call metadata when inspecting").action((name, opts) => {