tledger 0.2.1 → 0.3.0

package/bin/token-ledger.mjs

@@ -4,7 +4,6 @@ import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import {
   mkdir,
-  readFile,
   stat,
 } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -20,18 +19,32 @@ import {
   renderTrendImage,
   writeTrendPng,
 } from "./token-ledger-trend-image.mjs";
+import { renderCacheReportImage } from "./token-ledger-cache-image.mjs";
 import { renderTrendCombo } from "./token-ledger-trend-terminal.mjs";
 import { startInteractive } from "./token-ledger-tui.mjs";
+import {
+  readPrivateSnapshot,
+  writePrivateSnapshot,
+} from "../lib/token-ledger-snapshot.mjs";
+import {
+  SNAPSHOT_SCHEMA_VERSION,
+  usageBuckets,
+  usageBucketsInRange,
+  usageCallCount,
+  usageThreadIds,
+} from "../lib/token-ledger-usage.mjs";
 
 export const DEFAULT_SNAPSHOT = resolve(
   homedir(),
   ".token-ledger",
-  "token-ledger-snapshot.json",
+  "token-ledger-snapshot-v2.json.gz",
 );
 const DEFAULT_TOP = 10;
 const DEFAULT_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
 export const SNAPSHOT_CACHE_MAX_AGE_MS = 60 * 60 * 1000;
 export const ROLLING_24_HOURS_MS = 24 * 60 * 60 * 1000;
+const MAX_ROLLING_DAYS = 3_650;
+const DURATION_ALIAS = /^(\d+)(d|w)$/i;
 const ANSI_RESET = "\u001b[0m";
 const MODEL_COLORS = {
   sol: TERMINAL_MODEL_COLORS.sol,
@@ -42,46 +55,111 @@ const MODEL_COLORS = {
   other: TERMINAL_MODEL_COLORS.other,
 };
 
-function usage() {
-  return `Token Ledger terminal usage
+export function usage() {
+  return `Token Ledger
 
 Usage:
-  tledger 1d                 Rolling 24-hour project breakdown (ends now)
-  tledger day <YYYY-MM-DD>
-  tledger week [end-day]
-  tledger trend [7d|14d|30d]
-  tledger report [7d|14d|30d]
-  npm run usage:day -- <YYYY-MM-DD>
-  npm run usage:week -- [end-day]
-
-Options:
-  --date <day>         Date as YYYY-MM-DD, today, or yesterday
-  --period <window>    Trend window: 7d, 14d, or 30d
-  --input <file>       Snapshot to read (default: ~/.token-ledger/token-ledger-snapshot.json)
-  --refresh            Rebuild the default snapshot from CODEX_HOME or ~/.codex
-  --no-refresh         Use the cached snapshot without checking local JSONL files
-  --codex-home <dir>   Codex data root used when refreshing
-  --tz <name>          IANA timezone (default: machine timezone)
-  --top <number>       Number of projects to show (default: 10)
-  --width <number>     Terminal layout width in columns
-  --raw-projects       Keep singleton thread labels instead of grouping them
-  --no-archived        Skip archived_sessions when refreshing
-  --plain              Disable terminal colors
-  --ascii              Use ASCII bars instead of Unicode blocks
-  --static             Print once instead of opening the interactive dashboard
-  --drain               Trend columns show observed limit drain percent instead of token volume
-  --image               Write trend view as a PNG image
-  --image-output <file> PNG output path for trend view
-  --image-width <px>   PNG image width from 900 to 2400 pixels
-  --youplot            Use the legacy single-series YouPlot renderer
-  --help               Show this help
-
-The report command writes the dashboard PNG (same as trend --image) to
-token-ledger-report-<period>.png; use --image-output to choose the path.
-
-The command reads a privacy-reduced Token Ledger snapshot. It never uploads
-the snapshot or prints message bodies, tool payloads, credentials, or local
-input/source paths. Explicit PNG output paths are reported after writing.`;
+  tledger 1d                         Last 24 hours in the terminal
+  tledger week                       Last 7 calendar days in the terminal
+  tledger 30d                        Rolling 30 days in the terminal
+  tledger report 7d                  Write the 7-day PNG report
+  tledger report 7d --cache-rate     Write the cache-only PNG report
+
+Common options:
+  --static                  Print once instead of opening the dashboard
+  --refresh                 Rebuild the local usage cache
+  --image-output <file>     Choose where to save a PNG
+  --no-open                 Do not open a generated PNG
+  -h, --help                Show this quick guide
+  --help-all                Show every command and option
+
+Token Ledger reads local Codex data only. It does not upload your usage.`;
+}
+
+export function advancedUsage() {
+  return `Token Ledger command reference
+
+Terminal commands:
+  tledger 1d                         Rolling 24-hour project breakdown
+  tledger <N>d                       Rolling N-day project breakdown
+  tledger <N>w                       Rolling N-week project breakdown
+  tledger day <YYYY-MM-DD>           One local calendar day
+  tledger week [end-day]             Seven local calendar days
+  tledger trend [Nd|Nw]              Multi-day terminal trend
+
+Report commands:
+  tledger report [Nd|Nw]             Write the usage dashboard PNG
+  tledger report [Nd|Nw] --cache-rate
+                                      Write the cache-only PNG
+
+Dates and ranges:
+  --date <day>               YYYY-MM-DD, today, or yesterday
+  --period <window>          Trend window such as 7d, 14d, or 2w
+  --tz <name>                IANA timezone (default: machine timezone)
+
+Data and refresh:
+  --input <file>             Read an explicit snapshot
+  --refresh                  Rebuild the default snapshot from local Codex data
+  --no-refresh               Use the cached snapshot without checking source files
+  --codex-home <dir>         Codex data root used when refreshing
+  --no-archived              Skip archived sessions when refreshing
+
+Terminal output:
+  --top <number>             Projects to show, from 1 to 100 (default: 10)
+  --width <number>           Layout width, from 40 to 200 columns
+  --raw-projects             Keep singleton thread labels ungrouped
+  --plain                    Disable terminal colors
+  --ascii                    Use ASCII bars instead of Unicode blocks
+  --static                   Print once instead of opening the dashboard
+  --youplot                  Use the legacy single-series renderer
+
+Report output:
+  --drain                    Chart estimated meter drain instead of token volume
+  --cache-rate               Write the cache-only report (report command only)
+  --image                    Write the trend view as a PNG
+  --image-output <file>      Choose the PNG output path
+  --image-width <px>         Set PNG width from 900 to 2400 pixels
+  --no-open                  Do not open the finished PNG
+
+Help:
+  -h, --help                Show the quick guide
+  --help-all                Show this complete reference
+
+The default snapshot is ~/.token-ledger/token-ledger-snapshot-v2.json.gz.
+Token Ledger reads local Codex data only. It does not upload your usage.`;
+}
+
+function durationAlias(value) {
+  const match = DURATION_ALIAS.exec(String(value ?? ""));
+  if (!match) return null;
+  const amount = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const days = unit === "w" ? amount * 7 : amount;
+  if (
+    !Number.isSafeInteger(amount) ||
+    !Number.isSafeInteger(days) ||
+    amount < 1 ||
+    days > MAX_ROLLING_DAYS
+  ) {
+    throw new Error(
+      `Duration must be between 1d and ${MAX_ROLLING_DAYS}d (or the equivalent in weeks).`,
+    );
+  }
+  const noun = unit === "w"
+    ? amount === 1 ? "week" : "weeks"
+    : amount === 1 ? "day" : "days";
+  return {
+    amount,
+    unit,
+    days,
+    label: `${amount} ${noun}`,
+  };
+}
+
+function rollingRangeDescription(options) {
+  return options.range === "rolling24h"
+    ? "the last 24 hours"
+    : `the last ${options.rollingLabel}`;
 }
 
 function readOption(argv, index, name) {
@@ -93,9 +171,14 @@ function readOption(argv, index, name) {
 }
 
 export function parseArgs(argv) {
+  const helpCommand = argv[0] === "help";
+  const alias = durationAlias(argv[0]);
   const rolling24hCommand = argv[0] === "1d";
+  const rollingDurationCommand = Boolean(alias) && !rolling24hCommand;
   const command = rolling24hCommand
     ? "rolling24h"
+    : rollingDurationCommand
+      ? "rolling"
     : argv[0] === "week"
       ? "week"
       : argv[0] === "trend" || argv[0] === "report"
@@ -105,6 +188,11 @@ export function parseArgs(argv) {
     range: command,
     view: command === "trend" ? "trend" : "projects",
     rolling24h: rolling24hCommand,
+    rollingDuration: rollingDurationCommand,
+    rollingDays: alias?.days ?? (rolling24hCommand ? 1 : null),
+    rollingAmount: alias?.amount ?? (rolling24hCommand ? 1 : null),
+    rollingUnit: alias?.unit ?? (rolling24hCommand ? "d" : null),
+    rollingLabel: alias?.label ?? "1 day",
     report: argv[0] === "report",
     trendDays: 7,
     date: null,
@@ -124,17 +212,23 @@ export function parseArgs(argv) {
     image: false,
     imageOutput: null,
     imageWidth: null,
+    openImage: true,
     drain: false,
+    cacheRate: false,
     legacyPlot: false,
-    help: false,
+    help: argv.length === 0 || helpCommand,
+    helpAll: false,
   };
 
   let trendPeriodSeen = false;
-  let index = ["1d", "day", "week", "trend", "report"].includes(argv[0]) ? 1 : 0;
+  let index = alias || ["day", "week", "trend", "report", "help"].includes(argv[0]) ? 1 : 0;
   for (; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === "--help" || argument === "-h") {
       options.help = true;
+    } else if (argument === "--help-all") {
+      options.help = true;
+      options.helpAll = true;
     } else if (argument === "--date") {
       options.date = readOption(argv, index, "--date");
       index += 1;
@@ -146,10 +240,13 @@ export function parseArgs(argv) {
         throw new Error("Trend period can only be specified once.");
       }
       const value = readOption(argv, index, "--period");
-      if (!["7d", "14d", "30d"].includes(value)) {
-        throw new Error("Trend period must be 7d, 14d, or 30d.");
+      const period = durationAlias(value);
+      if (!period) {
+        throw new Error(
+          "Trend period must use a positive number of days or weeks, such as 7d or 2w.",
+        );
       }
-      options.trendDays = Number.parseInt(value, 10);
+      options.trendDays = period.days;
       trendPeriodSeen = true;
       index += 1;
     } else if (argument === "--input") {
@@ -195,11 +292,21 @@ export function parseArgs(argv) {
         throw new Error("--drain is only available for the trend view.");
       }
       options.drain = true;
+    } else if (argument === "--cache-rate") {
+      if (!options.report) {
+        throw new Error("--cache-rate is only available with the report command.");
+      }
+      options.cacheRate = true;
     } else if (argument === "--image") {
       if (options.view !== "trend") {
         throw new Error("--image is only available for the trend view.");
       }
       options.image = true;
+    } else if (argument === "--no-open") {
+      if (options.view !== "trend") {
+        throw new Error("--no-open is only available for the trend view.");
+      }
+      options.openImage = false;
     } else if (argument === "--image-output") {
       if (options.view !== "trend") {
         throw new Error("--image-output is only available for the trend view.");
@@ -241,10 +348,13 @@ export function parseArgs(argv) {
       if (trendPeriodSeen) {
         throw new Error("Trend period can only be specified once.");
       }
-      if (!["7d", "14d", "30d"].includes(argument)) {
-        throw new Error("Trend period must be 7d, 14d, or 30d.");
+      const period = durationAlias(argument);
+      if (!period) {
+        throw new Error(
+          "Trend period must use a positive number of days or weeks, such as 7d or 2w.",
+        );
       }
-      options.trendDays = Number.parseInt(argument, 10);
+      options.trendDays = period.days;
       trendPeriodSeen = true;
     } else if (!argument.startsWith("-") && !options.date) {
       options.date = argument;
@@ -254,13 +364,13 @@ export function parseArgs(argv) {
   }
 
   if (options.report) options.image = true;
-  if (!options.help && options.rolling24h && options.date) {
-    throw new Error("1d does not accept --date; its rolling window ends now.");
+  if (!options.help && (options.rolling24h || options.rollingDuration) && options.date) {
+    throw new Error(`${options.rollingLabel} does not accept --date; its rolling window ends now.`);
   }
   if (!options.help && !options.date && (options.range === "week" || options.view === "trend")) {
     options.date = "today";
   }
-  if (!options.help && !options.date && !options.rolling24h) {
+  if (!options.help && !options.date && !options.rolling24h && !options.rollingDuration) {
     throw new Error("A day is required, for example: tledger day 2026-08-01");
   }
   if (!options.help && options.refresh && !options.autoRefresh) {
@@ -272,6 +382,9 @@ export function parseArgs(argv) {
   if (!options.help && options.view === "trend" && options.legacyPlot) {
     throw new Error("--youplot is only available for the project view.");
   }
+  if (!options.help && options.cacheRate && options.drain) {
+    throw new Error("--cache-rate cannot be combined with --drain.");
+  }
   return options;
 }
 
@@ -387,20 +500,35 @@ export function weekBounds(value, timeZone) {
   };
 }
 
-export function rolling24hBounds(value = new Date(), timeZone = DEFAULT_TIME_ZONE) {
+export function rollingDurationBounds(
+  value = new Date(),
+  timeZone = DEFAULT_TIME_ZONE,
+  rangeDays = 1,
+) {
   validateTimeZone(timeZone);
   const end = value instanceof Date ? new Date(value.getTime()) : new Date(value);
   if (!Number.isFinite(end.getTime())) {
-    throw new Error("Rolling 24-hour window requires a valid end time.");
+    throw new Error("Rolling window requires a valid end time.");
+  }
+  const days = Number(rangeDays);
+  if (!Number.isSafeInteger(days) || days < 1 || days > MAX_ROLLING_DAYS) {
+    throw new Error(
+      `Rolling window must be between 1 and ${MAX_ROLLING_DAYS} days.`,
+    );
   }
   return {
-    start: new Date(end.getTime() - ROLLING_24_HOURS_MS),
+    start: new Date(end.getTime() - days * ROLLING_24_HOURS_MS),
     end,
     timeZone,
-    rangeHours: 24,
+    rangeHours: days * 24,
+    rangeDays: days,
   };
 }
 
+export function rolling24hBounds(value = new Date(), timeZone = DEFAULT_TIME_ZONE) {
+  return rollingDurationBounds(value, timeZone, 1);
+}
+
 export function sanitizeTerminalText(value) {
   return String(value ?? "")
     .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, "")
@@ -486,7 +614,9 @@ export function oneOffProjects(snapshot) {
     ids.add(threadId);
     threadIdsByProject.set(normalizedProject, ids);
   };
-  for (const event of snapshot.events ?? []) add(event.project, event.threadId);
+  for (const bucket of usageBuckets(snapshot)) {
+    for (const threadId of usageThreadIds(bucket)) add(bucket.project, threadId);
+  }
   for (const thread of snapshot.threads ?? []) add(thread.project, thread.id);
   return new Set(
     [...threadIdsByProject.entries()]
@@ -509,10 +639,7 @@ function modelLabel(value) {
 export function filterDayEvents(snapshot, bounds) {
   const start = bounds.start.getTime();
   const end = bounds.end.getTime();
-  return (snapshot.events ?? []).filter((event) => {
-    const timestamp = new Date(event.timestamp).getTime();
-    return Number.isFinite(timestamp) && timestamp >= start && timestamp < end;
-  });
+  return usageBucketsInRange(snapshot, start, end);
 }
 
 export function aggregateProjects(snapshot, events, options = {}) {
@@ -543,8 +670,8 @@ export function aggregateProjects(snapshot, events, options = {}) {
     row.outputTokens += Number(event.outputTokens) || 0;
     row.reasoningTokens += Number(event.reasoningTokens) || 0;
     row.toolCalls += Number(event.toolCalls) || 0;
-    row.events += 1;
-    if (event.threadId) row.threadIds.add(event.threadId);
+    row.events += usageCallCount(event);
+    for (const threadId of usageThreadIds(event)) row.threadIds.add(threadId);
     if (event.rateCardCredits !== null && Number.isFinite(Number(event.rateCardCredits))) {
       row.rateCardCredits += Number(event.rateCardCredits);
       row.knownCreditTokens += Number(event.totalTokens) || 0;
@@ -558,7 +685,7 @@ export function aggregateProjects(snapshot, events, options = {}) {
       rateCardCredits: 0,
     };
     modelRow.totalTokens += Number(event.totalTokens) || 0;
-    modelRow.events += 1;
+    modelRow.events += usageCallCount(event);
     if (event.rateCardCredits !== null && Number.isFinite(Number(event.rateCardCredits))) {
       modelRow.rateCardCredits += Number(event.rateCardCredits);
     }
@@ -588,7 +715,10 @@ function totalSummary(events) {
       summary.totalTokens += Number(event.totalTokens) || 0;
       summary.outputTokens += Number(event.outputTokens) || 0;
       summary.toolCalls += Number(event.toolCalls) || 0;
-      if (event.threadId) summary.threadIds.add(event.threadId);
+      summary.calls += usageCallCount(event);
+      for (const threadId of usageThreadIds(event)) {
+        summary.threadIds.add(threadId);
+      }
       if (event.rateCardCredits !== null && Number.isFinite(Number(event.rateCardCredits))) {
         summary.rateCardCredits += Number(event.rateCardCredits);
         summary.knownCreditTokens += Number(event.totalTokens) || 0;
@@ -599,6 +729,7 @@ function totalSummary(events) {
       totalTokens: 0,
       outputTokens: 0,
       toolCalls: 0,
+      calls: 0,
       rateCardCredits: 0,
       knownCreditTokens: 0,
       threadIds: new Set(),
@@ -614,12 +745,18 @@ function compact(value, digits = 2) {
     [1_000_000, "M"],
     [1_000, "K"],
   ];
-  for (const [divisor, suffix] of units) {
-    if (absolute >= divisor) {
-      const scaled = value / divisor;
-      const precision = scaled >= 100 ? 0 : scaled >= 10 ? 1 : digits;
-      return `${scaled.toFixed(precision)}${suffix}`;
+  for (let index = 0; index < units.length; index += 1) {
+    const [divisor, suffix] = units[index];
+    if (absolute < divisor) continue;
+    const scaled = value / divisor;
+    const magnitude = Math.abs(scaled);
+    const precision = magnitude >= 100 ? 0 : magnitude >= 10 ? 1 : digits;
+    // Values that round to 1000 of a unit belong to the next unit up
+    // (999,999 → 1.00M, not 1000K).
+    if (index > 0 && Number(magnitude.toFixed(precision)) >= 1_000) {
+      return compact(Math.sign(value) * divisor * 1_000, digits);
     }
+    return `${scaled.toFixed(precision)}${suffix}`;
   }
   return Math.round(value).toLocaleString("en-US");
 }
@@ -723,7 +860,7 @@ async function readSnapshot(snapshotPath) {
   const snapshotLabel = safeDisplayLabel(snapshotPath, "snapshot");
   let parsed;
   try {
-    parsed = JSON.parse(await readFile(snapshotPath, "utf8"));
+    parsed = await readPrivateSnapshot(snapshotPath);
   } catch (error) {
     if (error?.code === "ENOENT") {
       throw new Error(`Snapshot not found: ${snapshotLabel}`);
@@ -732,8 +869,14 @@ async function readSnapshot(snapshotPath) {
       `Could not read snapshot ${snapshotLabel}: ${safeErrorMessage(error, [snapshotPath])}`,
     );
   }
-  if (!parsed || !Array.isArray(parsed.events)) {
-    throw new Error(`Snapshot is missing its events array: ${snapshotLabel}`);
+  if (
+    !parsed ||
+    parsed.schemaVersion !== SNAPSHOT_SCHEMA_VERSION ||
+    !Array.isArray(parsed.events)
+  ) {
+    throw new Error(
+      `Snapshot uses an unsupported schema: ${snapshotLabel}. Rebuild it with --refresh.`,
+    );
   }
   return parsed;
 }
@@ -746,7 +889,7 @@ async function refreshSnapshot(options) {
   }
   let progressStarted = false;
   try {
-    const { collectUsage, writePrivateSnapshot } = await import(
+    const { collectUsage } = await import(
       "../lib/token-ledger-importer.mjs"
     );
     process.stderr.write("Token Ledger: refreshing local snapshot…\n");
@@ -763,10 +906,25 @@ async function refreshSnapshot(options) {
       },
     );
     process.stderr.write("\n");
-    await writePrivateSnapshot(options.input, snapshot);
-    return snapshot;
+    const writeResult = await writePrivateSnapshot(options.input, snapshot);
+    const storedSnapshot = writeResult.snapshot;
+    process.stderr.write(
+      `Token Ledger: cached ${(writeResult.bytesWritten / 1_000_000).toFixed(1)} MB ${writeResult.encoding} snapshot (${(writeResult.jsonBytes / 1_000_000).toFixed(1)} MB JSON before encoding; ${storedSnapshot.events.length.toLocaleString()} buckets for ${storedSnapshot.coverage.observedModelCalls.toLocaleString()} calls; ${(writeResult.maxBytes / 1_000_000).toFixed(1)} MB limit).\n`,
+    );
+    if (writeResult.bytesWritten / writeResult.maxBytes >= 0.7) {
+      process.stderr.write(
+        "Token Ledger: snapshot is above 70% of its safety limit; older buckets will compact automatically as it grows.\n",
+      );
+    }
+    return storedSnapshot;
   } catch (error) {
     if (progressStarted) process.stderr.write("\n");
+    if (error?.code === "ERR_SNAPSHOT_SIZE_LIMIT" && existsSync(options.input)) {
+      process.stderr.write(
+        "Token Ledger: refresh exceeded the safety limit; continuing with the previous cache, which may be stale.\n",
+      );
+      return readSnapshot(options.input);
+    }
     throw new Error(
       `Could not refresh local snapshot: ${safeErrorMessage(error, [options.input, options.codexHome])}`,
     );
@@ -798,10 +956,18 @@ function snapshotAgeLabel(ageMs) {
   return `${Math.floor(hours / 24)}d old`;
 }
 
+function primitiveString(value) {
+  try {
+    const text = String.prototype.valueOf.call(value);
+    return text === value ? text : null;
+  } catch {
+    return null;
+  }
+}
+
 export function snapshotFreshness(snapshot = {}, nowMs = Date.now()) {
-  const generatedAtMs = typeof snapshot.generatedAt === "string"
-    ? Date.parse(snapshot.generatedAt)
-    : NaN;
+  const generatedAt = primitiveString(snapshot.generatedAt);
+  const generatedAtMs = generatedAt === null ? NaN : Date.parse(generatedAt);
   if (
     !Number.isFinite(generatedAtMs) ||
     !Number.isFinite(nowMs) ||
@@ -863,6 +1029,14 @@ async function loadSnapshot(options) {
 
 function render(options, snapshot, bounds, events, rows, allRows, freshness) {
   if (options.view === "trend") {
+    if (options.image && options.cacheRate) {
+      return renderCacheReportImage({
+        snapshot,
+        bounds,
+        days: options.trendDays,
+        options,
+      });
+    }
     const trend = buildUsageTrend(snapshot, bounds);
     if (options.image) {
       return renderTrendImage({
@@ -871,6 +1045,7 @@ function render(options, snapshot, bounds, events, rows, allRows, freshness) {
         trend,
         days: options.trendDays,
         options,
+        projectRows: allRows,
       });
     }
     return renderTrendCombo({
@@ -897,7 +1072,9 @@ function render(options, snapshot, bounds, events, rows, allRows, freshness) {
   const totalTokens = summary.totalTokens;
   const dateLabel = options.range === "rolling24h"
     ? "last 24 hours"
-    : options.range === "week"
+    : options.range === "rolling"
+      ? `last ${options.rollingLabel}`
+      : options.range === "week"
       ? `${bounds.startDateString} through ${bounds.endDateString}`
       : new Intl.DateTimeFormat("en-US", {
         timeZone: bounds.timeZone,
@@ -914,7 +1091,7 @@ function render(options, snapshot, bounds, events, rows, allRows, freshness) {
 
   const header = [
     `Token Ledger · ${dateLabel} · ${bounds.timeZone}`,
-    `${compact(totalTokens)} tokens · ${summary.threadIds.size.toLocaleString()} threads · ${events.length.toLocaleString()} calls · ${compact(summary.outputTokens)} output`,
+    `${compact(totalTokens)} tokens · ${summary.threadIds.size.toLocaleString()} threads · ${summary.calls.toLocaleString()} calls · ${compact(summary.outputTokens)} output`,
     `Source: ${sourceLabel(options.input, snapshot)}`,
     "",
     chart,
@@ -943,11 +1120,16 @@ function boundsForOptions(options, now = new Date()) {
   if (options.range === "rolling24h") {
     return rolling24hBounds(now, options.timeZone);
   }
+  if (options.range === "rolling") {
+    return rollingDurationBounds(now, options.timeZone, options.rollingDays);
+  }
   return dayBounds(options.date, options.timeZone);
 }
 
 function rangeDescription(options, bounds) {
-  if (options.range === "rolling24h") return "the last 24 hours";
+  if (options.range === "rolling24h" || options.range === "rolling") {
+    return rollingRangeDescription(options);
+  }
   if (bounds.startDateString && bounds.endDateString) {
     return `${bounds.startDateString} through ${bounds.endDateString}`;
   }
@@ -960,23 +1142,30 @@ export async function run(options, { nowMs } = {}) {
   const bounds = boundsForOptions(options, now);
   const snapshot = await loadSnapshot(options);
   const events = filterDayEvents(snapshot, bounds);
-  if (events.length === 0) {
+  const writingImage = options.view === "trend" && options.image;
+  const writingEmptyCacheReport = writingImage && options.cacheRate;
+  if (events.length === 0 && !writingEmptyCacheReport) {
     return [
       `No model-call events found for ${rangeDescription(options, bounds)} (${bounds.timeZone}).`,
       `Source: ${sourceLabel(options.input, snapshot)}`,
     ].join("\n");
   }
-  const allRows = aggregateProjects(snapshot, events, options);
+  const allRows = options.cacheRate
+    ? []
+    : aggregateProjects(snapshot, events, options);
   const rows = allRows.slice(0, options.top);
-  const writingImage = options.view === "trend" && options.image;
   const outputPath = writingImage
     ? options.imageOutput ??
       resolve(
         process.cwd(),
-        `token-ledger-${options.report ? "report" : "trend"}-${options.trendDays}d.png`,
+        `token-ledger-${options.cacheRate ? "cache-report" : options.report ? "report" : "trend"}-${options.trendDays}d.png`,
       )
     : null;
-  const imageLabel = options.report ? "report" : "trend image";
+  const imageLabel = options.cacheRate
+    ? "cache report"
+    : options.report
+      ? "report"
+      : "trend image";
   if (writingImage) {
     process.stderr.write(`Token Ledger: generating ${imageLabel} PNG…\n`);
   }
@@ -997,14 +1186,36 @@ export async function run(options, { nowMs } = {}) {
     process.stderr.write(`Token Ledger: encoding ${imageLabel} PNG…\n`);
     await writeTrendPng(output, outputPath);
     process.stderr.write(`Token Ledger: finished ${imageLabel} PNG.\n`);
-    return [
-      `Wrote ${options.report ? "report" : "trend image"}: ${outputPath}`,
+    const lines = [
+      `Wrote ${imageLabel}: ${outputPath}`,
       `Range: ${bounds.startDateString} through ${bounds.endDateString} (${bounds.timeZone})`,
-    ].join("\n");
+    ];
+    // Show the finished report on screen right away instead of leaving it to
+    // be dug out of a file browser. Skipped for piped/scripted runs so
+    // automation and CI never pop windows.
+    if (options.openImage && process.stdout.isTTY) {
+      lines.push(
+        openInViewer(outputPath)
+          ? "Opened the report in your default image viewer."
+          : "Could not open a viewer automatically; open the file above to see the report.",
+      );
+    }
+    return lines.join("\n");
   }
   return output;
 }
 
+function openInViewer(path) {
+  const platform = process.platform;
+  const [command, args] = platform === "darwin"
+    ? ["open", [path]]
+    : platform === "win32"
+      ? ["cmd", ["/c", "start", "", path]]
+      : ["xdg-open", [path]];
+  const result = spawnSync(command, args, { stdio: "ignore" });
+  return result.status === 0;
+}
+
 function shouldUseInteractive(options) {
   return Boolean(
     !options.static &&
@@ -1046,7 +1257,7 @@ async function main() {
   try {
     options = parseArgs(process.argv.slice(2));
     if (options.help) {
-      process.stdout.write(`${usage()}\n`);
+      process.stdout.write(`${options.helpAll ? advancedUsage() : usage()}\n`);
       return;
     }
     if (shouldUseInteractive(options)) {
@@ -1056,11 +1267,11 @@ async function main() {
     }
   } catch (error) {
     process.stderr.write(
-      `Token Ledger CLI failed: ${safeErrorMessage(error, [
+      `Token Ledger: ${safeErrorMessage(error, [
         options?.input,
         options?.codexHome,
         options?.imageOutput,
-      ])}\n\n${usage()}\n`,
+      ])}\nRun \`tledger --help\` for examples or \`tledger --help-all\` for every option.\n`,
     );
     process.exitCode = 1;
   }