tledger 0.1.4 → 0.2.0

package/bin/token-ledger.mjs

@@ -1,21 +1,27 @@
 #!/usr/bin/env node
 
+import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
-import { createRequire } from "node:module";
 import {
+  mkdir,
   readFile,
   stat,
 } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { renderTerminal } from "./token-ledger-terminal.mjs";
+import {
+  MODEL_COLORS as TERMINAL_MODEL_COLORS,
+  renderTerminal,
+} from "./token-ledger-terminal.mjs";
+import { buildUsageTrend, multiDayBounds } from "./token-ledger-trend.mjs";
+import {
+  renderTrendImage,
+  writeTrendPng,
+} from "./token-ledger-trend-image.mjs";
+import { renderTrendCombo } from "./token-ledger-trend-terminal.mjs";
 import { startInteractive } from "./token-ledger-tui.mjs";
-import { modelDisplayName } from "../lib/token-ledger-models.mjs";
-
-const require = createRequire(import.meta.url);
-export const VERSION = require("../package.json").version;
 
 export const DEFAULT_SNAPSHOT = resolve(
   homedir(),
@@ -23,29 +29,32 @@ export const DEFAULT_SNAPSHOT = resolve(
   "token-ledger-snapshot.json",
 );
 const DEFAULT_TOP = 10;
-const MAX_RANGE_DAYS = 100_000;
 const DEFAULT_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
+export const SNAPSHOT_CACHE_MAX_AGE_MS = 60 * 60 * 1000;
+const ANSI_RESET = "\u001b[0m";
+const MODEL_COLORS = {
+  sol: TERMINAL_MODEL_COLORS.sol,
+  luna: TERMINAL_MODEL_COLORS.luna,
+  terra: TERMINAL_MODEL_COLORS.terra,
+  "gpt-5.5": TERMINAL_MODEL_COLORS.gpt,
+  "gpt-5.4": TERMINAL_MODEL_COLORS.gpt,
+  other: TERMINAL_MODEL_COLORS.other,
+};
 
 function usage() {
   return `Token Ledger terminal usage
 
 Usage:
-  tledger
+  tledger day <YYYY-MM-DD>
   tledger week [end-day]
-  tledger day [day]
-  tledger month [end-day]
-  tledger <number>d [end-day]
-  tledger all
-
-Ranges:
-  day                  One calendar day
-  week                 7 days ending on end-day (default: today)
-  month                30 days ending on end-day (default: today)
-  <number>d            That many days ending on end-day, for example 90d
-  all                  Every dated event in the snapshot
+  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
@@ -54,16 +63,22 @@ Options:
   --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
-  -anon                Replace project names with Project 1, Project 2, and so on
   --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
-  -v, --version        Show the installed version
+  --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 default view is the seven-day window ending today. Token Ledger never
-uploads data or renders message bodies, tool payloads, or credentials.`;
+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 paths.`;
 }
 
 function readOption(argv, index, name) {
@@ -74,38 +89,17 @@ function readOption(argv, index, name) {
   return value;
 }
 
-function rangeSpec(value) {
-  if (value === "day") return { range: "day", rangeDays: 1 };
-  if (value === "week") return { range: "week", rangeDays: 7 };
-  if (value === "month") return { range: "month", rangeDays: 30 };
-  if (value === "all") return { range: "all", rangeDays: null };
-  const custom = /^(\d+)d$/.exec(value ?? "");
-  if (!custom) return null;
-  const rangeDays = Number(custom[1]);
-  if (
-    !Number.isSafeInteger(rangeDays) ||
-    rangeDays < 1 ||
-    rangeDays > MAX_RANGE_DAYS
-  ) {
-    throw new Error(
-      `Day range must be an integer from 1 to ${MAX_RANGE_DAYS.toLocaleString("en-US")}, for example 90d.`,
-    );
-  }
-  return { range: `${rangeDays}d`, rangeDays };
-}
-
 export function parseArgs(argv) {
-  const requestedRange = rangeSpec(argv[0]);
-  const commandExplicit = Boolean(requestedRange);
-  if (argv[0] && !argv[0].startsWith("-") && !commandExplicit) {
-    throw new Error(
-      `Unknown command: ${argv[0]}. Use day, week, month, all, or a duration like 90d.`,
-    );
-  }
-  const command = requestedRange ?? { range: "week", rangeDays: 7 };
+  const command = argv[0] === "week"
+    ? "week"
+    : argv[0] === "trend" || argv[0] === "report"
+      ? "trend"
+      : "day";
   const options = {
-    range: command.range,
-    rangeDays: command.rangeDays,
+    range: command,
+    view: command === "trend" ? "trend" : "projects",
+    report: argv[0] === "report",
+    trendDays: 7,
     date: null,
     input: DEFAULT_SNAPSHOT,
     inputExplicit: false,
@@ -117,24 +111,40 @@ export function parseArgs(argv) {
     top: DEFAULT_TOP,
     width: null,
     rawProjects: false,
-    anonymizeProjects: false,
     plain: false,
     ascii: false,
     static: false,
-    version: false,
+    image: false,
+    imageOutput: null,
+    imageWidth: null,
+    drain: false,
+    legacyPlot: false,
     help: false,
   };
 
-  let index = commandExplicit ? 1 : 0;
+  let trendPeriodSeen = false;
+  let index = ["day", "week", "trend", "report"].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 === "--version" || argument === "-v") {
-      options.version = true;
     } else if (argument === "--date") {
       options.date = readOption(argv, index, "--date");
       index += 1;
+    } else if (argument === "--period") {
+      if (options.view !== "trend") {
+        throw new Error("--period is only available for the trend view.");
+      }
+      if (trendPeriodSeen) {
+        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.");
+      }
+      options.trendDays = Number.parseInt(value, 10);
+      trendPeriodSeen = true;
+      index += 1;
     } else if (argument === "--input") {
       options.input = resolve(readOption(argv, index, "--input"));
       options.inputExplicit = true;
@@ -165,8 +175,6 @@ export function parseArgs(argv) {
       index += 1;
     } else if (argument === "--raw-projects") {
       options.rawProjects = true;
-    } else if (argument === "-anon") {
-      options.anonymizeProjects = true;
     } else if (argument === "--no-archived") {
       options.includeArchived = false;
     } else if (argument === "--plain") {
@@ -175,25 +183,72 @@ export function parseArgs(argv) {
       options.ascii = true;
     } else if (argument === "--static") {
       options.static = true;
-    } else if (commandExplicit && !argument.startsWith("-") && !options.date) {
+    } else if (argument === "--drain") {
+      if (options.view !== "trend") {
+        throw new Error("--drain is only available for the trend view.");
+      }
+      options.drain = 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 === "--image-output") {
+      if (options.view !== "trend") {
+        throw new Error("--image-output is only available for the trend view.");
+      }
+      const value = readOption(argv, index, "--image-output");
+      if (!value.toLowerCase().endsWith(".png")) {
+        throw new Error("--image-output must end in .png.");
+      }
+      options.image = true;
+      options.imageOutput = resolve(value);
+      index += 1;
+    } else if (argument === "--image-width") {
+      if (options.view !== "trend") {
+        throw new Error("--image-width is only available for the trend view.");
+      }
+      const value = Number(readOption(argv, index, "--image-width"));
+      if (!Number.isInteger(value) || value < 900 || value > 2400) {
+        throw new Error("--image-width must be an integer from 900 to 2400.");
+      }
+      options.image = true;
+      options.imageWidth = value;
+      index += 1;
+    } else if (argument === "--youplot") {
+      options.legacyPlot = true;
+    } else if (!argument.startsWith("-") && options.view === "trend") {
+      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.");
+      }
+      options.trendDays = Number.parseInt(argument, 10);
+      trendPeriodSeen = true;
+    } else if (!argument.startsWith("-") && !options.date) {
       options.date = argument;
     } else {
       throw new Error(`Unknown option: ${argument}`);
     }
   }
 
-  if (!options.help && !options.version && options.range === "all" && options.date) {
-    throw new Error("The all range does not accept an end day.");
-  }
-  if (!options.help && !options.version && !options.date && options.range !== "all") {
+  if (options.report) options.image = true;
+  if (!options.help && !options.date && (options.range === "week" || options.view === "trend")) {
     options.date = "today";
   }
-  if (!options.help && !options.version && options.refresh && !options.autoRefresh) {
+  if (!options.help && !options.date) {
+    throw new Error("A day is required, for example: tledger day 2026-08-01");
+  }
+  if (!options.help && options.refresh && !options.autoRefresh) {
     throw new Error("--refresh cannot be combined with --no-refresh.");
   }
-  if (!options.help && !options.version && options.refresh && options.inputExplicit) {
+  if (!options.help && options.refresh && options.inputExplicit) {
     throw new Error("--refresh cannot be combined with --input.");
   }
+  if (!options.help && options.view === "trend" && options.legacyPlot) {
+    throw new Error("--youplot is only available for the project view.");
+  }
   return options;
 }
 
@@ -294,99 +349,21 @@ export function dayBounds(value, timeZone) {
   const nextDateString = shiftCalendarDate(dateString, 1);
   const start = zonedMidnight(dateString, timeZone);
   const end = zonedMidnight(nextDateString, timeZone);
-  return {
-    dateString,
-    startDateString: dateString,
-    endDateString: dateString,
-    start,
-    end,
-    timeZone,
-    rangeDays: 1,
-  };
+  return { dateString, start, end, timeZone };
 }
 
-export function rollingBounds(value, timeZone, rangeDays) {
-  if (
-    !Number.isSafeInteger(rangeDays) ||
-    rangeDays < 1 ||
-    rangeDays > MAX_RANGE_DAYS
-  ) {
-    throw new Error(
-      `Range days must be an integer from 1 to ${MAX_RANGE_DAYS.toLocaleString("en-US")}.`,
-    );
-  }
+export function weekBounds(value, timeZone) {
   const endDay = dayBounds(value, timeZone);
-  const startDateString = shiftCalendarDate(endDay.dateString, -(rangeDays - 1));
+  const startDateString = shiftCalendarDate(endDay.dateString, -6);
   return {
     ...endDay,
     startDateString,
     endDateString: endDay.dateString,
     start: zonedMidnight(startDateString, timeZone),
-    rangeDays,
+    rangeDays: 7,
   };
 }
 
-export function weekBounds(value, timeZone) {
-  return rollingBounds(value, timeZone, 7);
-}
-
-export function monthBounds(value, timeZone) {
-  return rollingBounds(value, timeZone, 30);
-}
-
-function eventTimestamp(event) {
-  if (typeof event?.timestamp !== "string" || !event.timestamp.trim()) {
-    return Number.NaN;
-  }
-  return new Date(event.timestamp).getTime();
-}
-
-export function allBounds(snapshot, timeZone) {
-  validateTimeZone(timeZone);
-  let earliest = Number.POSITIVE_INFINITY;
-  let latest = Number.NEGATIVE_INFINITY;
-  for (const event of snapshot.events ?? []) {
-    const timestamp = eventTimestamp(event);
-    if (!Number.isFinite(timestamp)) continue;
-    earliest = Math.min(earliest, timestamp);
-    latest = Math.max(latest, timestamp);
-  }
-  if (!Number.isFinite(earliest)) {
-    return {
-      ...dayBounds("today", timeZone),
-      rangeDays: null,
-      allTime: true,
-    };
-  }
-  const dateString = (timestamp) => dateStringFromParts(numericDateParts({
-    value: new Date(timestamp),
-    timeZone,
-  }));
-  const startDateString = dateString(earliest);
-  const endDateString = dateString(latest);
-  return {
-    dateString: endDateString,
-    startDateString,
-    endDateString,
-    start: zonedMidnight(startDateString, timeZone),
-    end: zonedMidnight(shiftCalendarDate(endDateString, 1), timeZone),
-    timeZone,
-    rangeDays: null,
-    allTime: true,
-  };
-}
-
-function boundsForOptions(options, snapshot) {
-  if (options.range === "all") return allBounds(snapshot, options.timeZone);
-  return rollingBounds(options.date, options.timeZone, options.rangeDays);
-}
-
-function describeRange(options, bounds) {
-  if (options.range === "all") return "all time";
-  if (bounds.rangeDays === 1) return bounds.dateString;
-  return `${bounds.startDateString} through ${bounds.endDateString}`;
-}
-
 export function sanitizeTerminalText(value) {
   return String(value ?? "")
     .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, "")
@@ -427,14 +404,20 @@ export function oneOffProjects(snapshot) {
 
 function modelLabel(value) {
   const model = cleanLabel(value, "Unknown model");
-  return modelDisplayName(model);
+  const lower = model.toLowerCase();
+  if (lower.includes("sol")) return "Sol";
+  if (lower.includes("luna")) return "Luna";
+  if (lower.includes("terra")) return "Terra";
+  if (lower === "gpt-5.5") return "GPT-5.5";
+  if (lower === "gpt-5.4") return "GPT-5.4";
+  return model;
 }
 
 export function filterDayEvents(snapshot, bounds) {
   const start = bounds.start.getTime();
   const end = bounds.end.getTime();
   return (snapshot.events ?? []).filter((event) => {
-    const timestamp = eventTimestamp(event);
+    const timestamp = new Date(event.timestamp).getTime();
     return Number.isFinite(timestamp) && timestamp >= start && timestamp < end;
   });
 }
@@ -459,6 +442,8 @@ export function aggregateProjects(snapshot, events, options = {}) {
         toolCalls: 0,
         events: 0,
         threadIds: new Set(),
+        rateCardCredits: 0,
+        knownCreditTokens: 0,
         models: new Map(),
       };
     row.totalTokens += Number(event.totalTokens) || 0;
@@ -467,14 +452,23 @@ export function aggregateProjects(snapshot, events, options = {}) {
     row.toolCalls += Number(event.toolCalls) || 0;
     row.events += 1;
     if (event.threadId) row.threadIds.add(event.threadId);
+    if (event.rateCardCredits !== null && Number.isFinite(Number(event.rateCardCredits))) {
+      row.rateCardCredits += Number(event.rateCardCredits);
+      row.knownCreditTokens += Number(event.totalTokens) || 0;
+    }
+
     const model = modelLabel(event.model);
     const modelRow = row.models.get(model) ?? {
       model,
       totalTokens: 0,
       events: 0,
+      rateCardCredits: 0,
     };
     modelRow.totalTokens += Number(event.totalTokens) || 0;
     modelRow.events += 1;
+    if (event.rateCardCredits !== null && Number.isFinite(Number(event.rateCardCredits))) {
+      modelRow.rateCardCredits += Number(event.rateCardCredits);
+    }
     row.models.set(model, modelRow);
     grouped.set(project, row);
   }
@@ -492,13 +486,93 @@ export function aggregateProjects(snapshot, events, options = {}) {
         return right.totalTokens - left.totalTokens;
       }
       return left.project.localeCompare(right.project);
+    });
+}
+
+function totalSummary(events) {
+  return events.reduce(
+    (summary, event) => {
+      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);
+      if (event.rateCardCredits !== null && Number.isFinite(Number(event.rateCardCredits))) {
+        summary.rateCardCredits += Number(event.rateCardCredits);
+        summary.knownCreditTokens += Number(event.totalTokens) || 0;
+      }
+      return summary;
+    },
+    {
+      totalTokens: 0,
+      outputTokens: 0,
+      toolCalls: 0,
+      rateCardCredits: 0,
+      knownCreditTokens: 0,
+      threadIds: new Set(),
+    },
+  );
+}
+
+function compact(value, digits = 2) {
+  if (!Number.isFinite(value)) return "—";
+  const absolute = Math.abs(value);
+  const units = [
+    [1_000_000_000, "B"],
+    [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}`;
+    }
+  }
+  return Math.round(value).toLocaleString("en-US");
+}
+
+function percent(value) {
+  return `${value.toFixed(value >= 10 ? 1 : 2)}%`;
+}
+
+function chartUnit(maximum) {
+  if (maximum >= 1_000_000_000) return { divisor: 1_000_000_000, suffix: "B" };
+  if (maximum >= 1_000_000) return { divisor: 1_000_000, suffix: "M" };
+  if (maximum >= 1_000) return { divisor: 1_000, suffix: "K" };
+  return { divisor: 1, suffix: "tokens" };
+}
+
+function chartNumber(value, divisor) {
+  const scaled = value / divisor;
+  if (scaled >= 100) return scaled.toFixed(0);
+  if (scaled >= 10) return scaled.toFixed(1);
+  return scaled.toFixed(2);
+}
+
+function colorize(value, code, enabled) {
+  const codes = Array.isArray(code) ? code.join(";") : code;
+  return enabled ? `\u001b[${codes}m${value}${ANSI_RESET}` : value;
+}
+
+function modelColor(model) {
+  const lower = model.toLowerCase();
+  if (lower.includes("sol")) return MODEL_COLORS.sol;
+  if (lower.includes("luna")) return MODEL_COLORS.luna;
+  if (lower.includes("terra")) return MODEL_COLORS.terra;
+  if (lower.includes("gpt-5.5") || lower.includes("gpt-5.4")) {
+    return MODEL_COLORS["gpt-5.5"];
+  }
+  return MODEL_COLORS.other;
+}
+
+function modelMix(row, enabled) {
+  return row.models
+    .slice(0, 4)
+    .map((model) => {
+      const share = row.totalTokens > 0 ? (model.totalTokens / row.totalTokens) * 100 : 0;
+      return `${colorize(model.model, modelColor(model.model), enabled)} ${percent(share)}`;
     })
-    .map((row, index) => ({
-      ...row,
-      displayProject: options.anonymizeProjects
-        ? `Project ${index + 1}`
-        : row.displayProject,
-    }));
+    .join(" · ");
 }
 
 function sourceLabel(snapshotPath, snapshot) {
@@ -508,46 +582,48 @@ function sourceLabel(snapshotPath, snapshot) {
         timeStyle: "short",
       })
     : "unknown time";
-  return `${cleanLabel(basename(snapshotPath), "snapshot")} · captured ${generated}`;
-}
+  return `${basename(snapshotPath)} · captured ${generated}`;
+}
+
+function runYouPlot(rows, options, dateLabel, unit) {
+  const chartInput = [
+    "project\tvalue",
+    ...rows.map(
+      (row) => `${row.displayProject.replace(/[\t\r\n]+/g, " ")}\t${chartNumber(row.totalTokens, unit.divisor)}`,
+    ),
+  ].join("\n");
+  const terminalWidth = Number(process.stdout.columns) || 100;
+  const width = options.width ?? Math.max(56, Math.min(110, terminalWidth - 4));
+  const useColor = !options.plain && !process.env.NO_COLOR && Boolean(process.stdout.isTTY);
+  const args = [
+    "bar",
+    "-H",
+    "-o",
+    "-",
+    "-t",
+    `Top ${rows.length} projects · tokens (${unit.suffix}) · ${dateLabel}`,
+    "-w",
+    String(width),
+    "--symbol",
+    options.ascii ? "#" : "█",
+  ];
+  if (useColor) args.push("-C", "-c", "blue");
+  else args.push("-M");
 
-function latestActivityDateString(snapshot, timeZone) {
-  let latestTimestamp = Number.NEGATIVE_INFINITY;
-  for (const event of snapshot.events ?? []) {
-    const timestamp = eventTimestamp(event);
-    if (Number.isFinite(timestamp) && timestamp > latestTimestamp) {
-      latestTimestamp = timestamp;
-    }
+  const result = spawnSync("uplot", args, {
+    input: `${chartInput}\n`,
+    encoding: "utf8",
+    maxBuffer: 1_000_000,
+  });
+  if (result.error?.code === "ENOENT") {
+    throw new Error(
+      "YouPlot is required. Install it with `brew install youplot`, then rerun this command.",
+    );
   }
-  if (!Number.isFinite(latestTimestamp)) return null;
-  return dateStringFromParts(numericDateParts({
-    value: new Date(latestTimestamp),
-    timeZone,
-  }));
-}
-
-function displayCalendarDate(dateString) {
-  const [year, month, day] = dateString.split("-").map(Number);
-  return new Intl.DateTimeFormat("en-US", {
-    month: "long",
-    day: "numeric",
-    year: "numeric",
-    timeZone: "UTC",
-  }).format(new Date(Date.UTC(year, month - 1, day)));
-}
-
-function emptyState(options, snapshot, bounds) {
-  const lines = [
-    `No model-call events found for ${describeRange(options, bounds)} (${bounds.timeZone}).`,
-    "Token Ledger reads only Codex history stored on this computer.",
-  ];
-  const latestDate = latestActivityDateString(snapshot, bounds.timeZone);
-  if (latestDate) {
-    lines.push(`Latest local activity: ${displayCalendarDate(latestDate)}.`);
-    lines.push(`Try: tledger ${options.range} ${latestDate}`);
+  if (result.status !== 0) {
+    throw new Error(result.stderr?.trim() || "YouPlot failed to render the chart.");
   }
-  lines.push(`Source: ${sourceLabel(options.input, snapshot)}`);
-  return lines.join("\n");
+  return result.stdout;
 }
 
 async function readSnapshot(snapshotPath) {
@@ -556,28 +632,22 @@ async function readSnapshot(snapshotPath) {
     parsed = JSON.parse(await readFile(snapshotPath, "utf8"));
   } catch (error) {
     if (error?.code === "ENOENT") {
-      throw new Error(`Snapshot not found: ${sanitizeTerminalText(snapshotPath)}`);
+      throw new Error(`Snapshot not found: ${snapshotPath}`);
     }
-    throw new Error(
-      `Could not read snapshot ${sanitizeTerminalText(snapshotPath)}: ${sanitizeTerminalText(error.message)}`,
-    );
+    throw new Error(`Could not read snapshot ${snapshotPath}: ${error.message}`);
   }
   if (!parsed || !Array.isArray(parsed.events)) {
-    throw new Error(
-      `Snapshot is missing its events array: ${sanitizeTerminalText(snapshotPath)}`,
-    );
+    throw new Error(`Snapshot is missing its events array: ${snapshotPath}`);
   }
   return parsed;
 }
 
 async function refreshSnapshot(options) {
   if (!existsSync(options.codexHome)) {
-    throw new Error(
-      `Codex data directory not found: ${sanitizeTerminalText(options.codexHome)}`,
-    );
+    throw new Error(`Codex data directory not found: ${options.codexHome}`);
   }
   const { collectUsage, writePrivateSnapshot } = await import(
-    "../lib/token-ledger-collector.mjs"
+    "../lib/token-ledger-importer.mjs"
   );
   process.stderr.write("Token Ledger: refreshing local snapshot…\n");
   const snapshot = await collectUsage(
@@ -596,18 +666,19 @@ async function refreshSnapshot(options) {
   return snapshot;
 }
 
-export function snapshotNeedsRefresh(
+export function snapshotNeedsRefresh(snapshotMtimeMs, latestJsonlMtimeMs) {
+  return latestJsonlMtimeMs > snapshotMtimeMs;
+}
+
+export function snapshotCacheIsFresh(
   snapshotMtimeMs,
-  latestSourceMtimeMs,
-  cachedSourceFingerprint,
-  expectedSourceFingerprint,
-  cachedSourceFileCount,
-  currentSourceFileCount,
+  nowMs = Date.now(),
 ) {
   return (
-    cachedSourceFingerprint !== expectedSourceFingerprint ||
-    cachedSourceFileCount !== currentSourceFileCount ||
-    latestSourceMtimeMs > snapshotMtimeMs
+    Number.isFinite(snapshotMtimeMs) &&
+    Number.isFinite(nowMs) &&
+    snapshotMtimeMs <= nowMs &&
+    nowMs - snapshotMtimeMs < SNAPSHOT_CACHE_MAX_AGE_MS
   );
 }
 
@@ -617,7 +688,7 @@ async function loadSnapshot(options) {
   }
   if (!existsSync(options.input)) {
     if (options.inputExplicit || !options.autoRefresh) {
-      throw new Error(`Snapshot not found: ${sanitizeTerminalText(options.input)}`);
+      throw new Error(`Snapshot not found: ${options.input}`);
     }
     return refreshSnapshot(options);
   }
@@ -625,48 +696,135 @@ async function loadSnapshot(options) {
     return readSnapshot(options.input);
   }
 
-  const { sourceFingerprint, sourceState } = await import(
-    "../lib/token-ledger-collector.mjs"
+  const snapshotStat = await stat(options.input);
+  if (snapshotCacheIsFresh(snapshotStat.mtimeMs)) {
+    return readSnapshot(options.input);
+  }
+
+  const { latestSourceModifiedAt } = await import("../lib/token-ledger-importer.mjs");
+  const latestSourceMtimeMs = await latestSourceModifiedAt(
+    options.codexHome,
+    options.includeArchived,
   );
-  const [snapshotStat, currentSourceState, snapshot] = await Promise.all([
-    stat(options.input),
-    sourceState(options.codexHome, options.includeArchived),
-    readSnapshot(options.input),
-  ]);
-  if (snapshotNeedsRefresh(
-    snapshotStat.mtimeMs,
-    currentSourceState.latestMtimeMs,
-    snapshot.provenance?.sourceFingerprint,
-    sourceFingerprint(options.codexHome, options.includeArchived),
-    snapshot.coverage?.sourceFileCount,
-    currentSourceState.fileCount,
-  )) {
+  if (snapshotNeedsRefresh(snapshotStat.mtimeMs, latestSourceMtimeMs)) {
     return refreshSnapshot(options);
   }
-  return snapshot;
+  return readSnapshot(options.input);
 }
 
 function render(options, snapshot, bounds, events, rows, allRows) {
-  return renderTerminal({ options, snapshot, bounds, events, rows, allRows });
+  if (options.view === "trend") {
+    const trend = buildUsageTrend(snapshot, bounds);
+    if (options.image) {
+      return renderTrendImage({
+        snapshot,
+        bounds,
+        trend,
+        days: options.trendDays,
+        options,
+      });
+    }
+    return renderTrendCombo({
+      snapshot,
+      bounds,
+      trend,
+      days: options.trendDays,
+      options,
+    });
+  }
+  if (!options.legacyPlot) {
+    return renderTerminal({ options, snapshot, bounds, events, rows, allRows });
+  }
+  const enabled = !options.plain && !process.env.NO_COLOR && Boolean(process.stdout.isTTY);
+  const summary = totalSummary(events);
+  const totalTokens = summary.totalTokens;
+  const dateLabel = options.range === "week"
+    ? `${bounds.startDateString} through ${bounds.endDateString}`
+    : new Intl.DateTimeFormat("en-US", {
+      timeZone: bounds.timeZone,
+      weekday: "short",
+      month: "short",
+      day: "numeric",
+      year: "numeric",
+    }).format(bounds.start);
+  const unit = chartUnit(rows[0]?.totalTokens ?? 0);
+  const shares = rows.map((row) =>
+    totalTokens > 0 ? (row.totalTokens / totalTokens) * 100 : 0,
+  );
+  const chart = runYouPlot(rows, options, dateLabel, unit).trimEnd();
+
+  const header = [
+    `Token Ledger · ${dateLabel} · ${bounds.timeZone}`,
+    `${compact(totalTokens)} tokens · ${summary.threadIds.size.toLocaleString()} threads · ${events.length.toLocaleString()} calls · ${compact(summary.outputTokens)} output`,
+    `Source: ${sourceLabel(options.input, snapshot)}`,
+    "",
+    chart,
+    "",
+    `Model mix · colors: ${colorize("Sol", MODEL_COLORS.sol, enabled)}  ${colorize("Luna", MODEL_COLORS.luna, enabled)}  ${colorize("Terra", MODEL_COLORS.terra, enabled)}  ${colorize("GPT", MODEL_COLORS["gpt-5.5"], enabled)}  ${colorize("Other", MODEL_COLORS.other, enabled)}`,
+  ];
+
+  const details = rows.map((row, index) => {
+    const knownCreditShare =
+      summary.rateCardCredits > 0 && row.rateCardCredits > 0
+        ? ` · ${percent((row.rateCardCredits / summary.rateCardCredits) * 100)} credits`
+        : "";
+    return `${String(index + 1).padStart(2, " ")}  ${row.displayProject} · ${compact(row.totalTokens)} · ${percent(shares[index])} · ${row.threads.toLocaleString()} threads${knownCreditShare}\n    ${modelMix(row, enabled)}`;
+  });
+
+  return `${header.join("\n")}\n\n${details.join("\n")}`;
 }
 
 export async function run(options) {
-  if (options.range !== "all") boundsForOptions(options);
+  const bounds = options.view === "trend"
+    ? multiDayBounds(options.date, options.timeZone, options.trendDays)
+    : options.range === "week"
+      ? weekBounds(options.date, options.timeZone)
+      : dayBounds(options.date, options.timeZone);
   const snapshot = await loadSnapshot(options);
-  const bounds = boundsForOptions(options, snapshot);
   const events = filterDayEvents(snapshot, bounds);
   if (events.length === 0) {
-    return emptyState(options, snapshot, bounds);
+    const rangeDescription = options.range === "week"
+      ? `${bounds.startDateString} through ${bounds.endDateString}`
+      : bounds.dateString;
+    return [
+      `No model-call events found for ${rangeDescription} (${bounds.timeZone}).`,
+      `Source: ${sourceLabel(options.input, snapshot)}`,
+    ].join("\n");
   }
   const allRows = aggregateProjects(snapshot, events, options);
   const rows = allRows.slice(0, options.top);
-  return render(options, snapshot, bounds, events, rows, allRows);
+  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`,
+      )
+    : null;
+  const imageLabel = options.report ? "report" : "trend image";
+  if (writingImage) {
+    process.stderr.write(`Token Ledger: generating ${imageLabel} PNG…\n`);
+  }
+  const output = render(options, snapshot, bounds, events, rows, allRows);
+  if (writingImage) {
+    await mkdir(dirname(outputPath), { recursive: true });
+    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}`,
+      `Range: ${bounds.startDateString} through ${bounds.endDateString} (${bounds.timeZone})`,
+    ].join("\n");
+  }
+  return output;
 }
 
 function shouldUseInteractive(options) {
   return Boolean(
     !options.static &&
+      options.view !== "trend" &&
       !options.plain &&
+      !options.legacyPlot &&
       !process.env.NO_COLOR &&
       process.stdin.isTTY &&
       process.stdout.isTTY,
@@ -674,12 +832,20 @@ function shouldUseInteractive(options) {
 }
 
 async function runInteractive(options) {
-  if (options.range !== "all") boundsForOptions(options);
+  const bounds = options.range === "week"
+    ? weekBounds(options.date, options.timeZone)
+    : dayBounds(options.date, options.timeZone);
   const snapshot = await loadSnapshot(options);
-  const bounds = boundsForOptions(options, snapshot);
   const events = filterDayEvents(snapshot, bounds);
   if (events.length === 0) {
-    process.stdout.write(`${emptyState(options, snapshot, bounds)}\n`);
+    const rangeDescription = options.range === "week"
+      ? `${bounds.startDateString} through ${bounds.endDateString}`
+      : bounds.dateString;
+    process.stdout.write([
+      `No model-call events found for ${rangeDescription} (${bounds.timeZone}).`,
+      `Source: ${sourceLabel(options.input, snapshot)}`,
+      "",
+    ].join("\n"));
     return;
   }
   const allRows = aggregateProjects(snapshot, events, options);
@@ -701,19 +867,13 @@ async function main() {
       process.stdout.write(`${usage()}\n`);
       return;
     }
-    if (options.version) {
-      process.stdout.write(`${VERSION}\n`);
-      return;
-    }
     if (shouldUseInteractive(options)) {
       await runInteractive(options);
     } else {
-      process.stdout.write(`${await run({ ...options, static: true })}\n`);
+      process.stdout.write(`${await run(options)}\n`);
     }
   } catch (error) {
-    process.stderr.write(
-      `Token Ledger CLI failed: ${sanitizeTerminalText(error.message)}\n\n${usage()}\n`,
-    );
+    process.stderr.write(`Token Ledger CLI failed: ${error.message}\n\n${usage()}\n`);
     process.exitCode = 1;
   }
 }