@krtclcdy/tersio 2.5.0 → 2.6.0

package/README.md

@@ -33,10 +33,10 @@ omp plugin features @krtclcdy/tersio --disable rtk
 Then restart OMP and enable a preset:
 
 ```text
-/combo medium
+/tersio combo medium
 ```
 
-Individual toggles: `/caveman full` · `/rtk on` · `/ponytail full`. Everything starts off until you enable it.
+Individual toggles: `/tersio caveman full` · `/tersio rtk on` · `/tersio ponytail full`. Everything starts off until you enable it.
 
 Session-start defaults (prompted during `install`, or flags):
 
@@ -44,7 +44,7 @@ Session-start defaults (prompted during `install`, or flags):
 tersio install --combo-default balanced --caveman-default lite --rtk-default on
 ```
 
-Defaults apply to fresh sessions only — anything persisted with `/combo`, `/caveman`, or `/rtk` wins. Stored as plugin settings (`omp plugin config get @krtclcdy/tersio comboDefault`).
+Defaults apply to fresh sessions only — anything persisted with `/tersio combo`, `/tersio caveman`, or `/tersio rtk` wins. Stored as plugin settings (`omp plugin config get @krtclcdy/tersio comboDefault`).
 
 ## What it installs
 
@@ -54,7 +54,7 @@ Defaults apply to fresh sessions only — anything persisted with `/combo`, `/ca
 | **RTK** | Routes noisy shell commands through the RTK binary for compact output |
 | **Ponytail** | Minimal, YAGNI-oriented code decisions |
 | **Combo** | Toggles all three at once. Presets: `off`, `medium`, `balanced`, `max` |
-| **Updater** | `/ai-addons` checks and updates Ponytail, RTK, and Caveman in-session, with dry-run and backups |
+| **Updater** | `/tersio check` and `/tersio update` cover Ponytail, RTK, and Caveman in-session, with dry-run and backups |
 
 User-level installs also register the package in `~/.omp/plugins` (visible in OMP **Settings → Plugins**), directly through the plugin manifest. Active modes reassert after Ponytail's prompt block on every top-level turn, including after history compaction.
 
@@ -81,6 +81,8 @@ Break-even math, balanced preset (caveman full + rtk + ponytail): `⌈overhead
 | `tersio update` | Refresh the CLI, extensions, and add-ons (RTK binary, Caveman rule, Ponytail) |
 | `tersio reinstall` | Fresh install, preserving the Ponytail package |
 | `tersio doctor` | Check OMP, extension, Ponytail, and RTK health |
+| `tersio usage` | Ledger-backed usage + savings report |
+| `tersio dashboard` | Serve the gain dashboard on localhost (`--open`, `--export <file>`, `--port <n>`) |
 | `tersio uninstall` | Remove extensions, registration, and the Ponytail plugin (`--keep-ponytail` keeps Ponytail; `--remove-rtk` also removes the RTK binary) |
 | `tersio version` | Print version |
 
@@ -88,63 +90,44 @@ Flags: `--dry-run`, `--yes`/`-y`, `--verbose`, `--scope`, `--combo-default`/`--c
 
 ## Commands reference
 
-### Caveman — terse replies
+Everything runs under one root. Bare `/tersio` prints status.
 
-```text
-/caveman lite         concise, drops pleasantries
-/caveman full         terse caveman style
-/caveman ultra        maximum terse, fragments only
-/caveman wenyan       classical-Chinese-style where clear
-/caveman off          normal mode
-/caveman status       show current mode
-```
+| Command | Purpose |
+|---|---|
+| `/tersio combo off\|medium\|balanced\|max\|status` | preset for all three modes (start here) |
+| `/tersio caveman lite\|full\|ultra\|wenyan\|off\|status` | terse-reply mode |
+| `/tersio rtk on\|off\|status` | compact shell-output toggle |
+| `/tersio ponytail off\|lite\|full\|ultra\|review\|status` | minimal-code level |
+| `/tersio status` | active modes + combo level |
+| `/tersio check` | add-on version check (same as old `/ai-addons check`) |
+| `/tersio update <ponytail\|rtk\|caveman\|all> [--dry-run]` | update add-ons, preview with dry-run |
+| `/tersio gain` | savings summary + dashboard hint |
+| `/tersio usage` | ledger report for this machine |
+| `/tersio help` | this table |
 
-`caveman off`, `stop caveman`, and `normal mode` also work.
+### Combo — one preset for all three
 
-### RTK — compact shell output
+Start here: one setting drives all three modes (`medium` = lite/lite/on, `balanced` = full/full/on, `max` = ultra/ultra/on, `off` = normal). Tweaking a mode individually drops to a `custom` mix.
 
-```text
-/rtk on               enable compact RTK output
-/rtk off              disable
-/rtk status           show current state
-```
+### Caveman — terse replies
 
-Covers noisy commands (`git status`, `git diff`, `read`, `grep`, test, `tsc`, lint).
+Pleasantries and restatements go; substance stays. Ladder: `lite`, `full`, `ultra` (fragments only), `wenyan` (compressed classical-Chinese-inspired register).
 
-### Ponytail — minimal code
+### RTK — compact shell output
 
-```text
-/ponytail lite        light guidance
-/ponytail full        full YAGNI enforcement
-/ponytail ultra       aggressive simplification
-/ponytail off         disable
-/ponytail status      show current state
-```
+A real binary, not a prompt trick: `rtk git status|diff|grep|test|tsc|lint` strips noise before output reaches the model. Exact bytes (checksums, patches) bypass it by policy.
 
-### Updater — check and update add-ons
+### Ponytail — minimal code (YAGNI)
 
-```text
-/ai-addons check                          check all add-on versions
-/ai-addons status                         same as check
-/ai-addons update ponytail                update Ponytail
-/ai-addons update rtk                     update the RTK binary
-/ai-addons update caveman                 update the Caveman rule
-/ai-addons update all                     update all three
-/ai-addons update all --dry-run           preview without changes
-```
+You Aren't Gonna Need It: smallest working change, no speculative abstractions, no new deps for stdlib jobs. `lite` nudges, `full` enforces, `ultra` challenges the requirement, `review` audits for over-engineering.
 
-### Combo — toggle all three
+`/tersio` persists state and reloads OMP without emitting separate command messages. Presets propagate to task subagents and light the Combo footer indicator; mixed individual settings report via `/tersio status`.
 
-```text
-/combo off            all three off (default)
-/combo medium         caveman=lite, rtk=on, ponytail=lite
-/combo balanced       caveman=full, rtk=on, ponytail=full
-/combo max            caveman=ultra, rtk=on, ponytail=ultra
-/combo status         show the level and underlying modes
-/combo help           show available levels
-```
+### Legacy aliases (still work)
+
+The pre-`/tersio` commands remain registered: `/caveman`, `/rtk`, `/combo`, `/ai-addons`. Prefer `/tersio` in new muscle memory; help output lists the aliases as deprecated-but-working.
 
-`/combo` persists state and reloads OMP without emitting separate command messages. Presets propagate to task subagents and light the Combo footer indicator; individual commands leave Combo inactive (`/combo status` still reports the mixed state).
+Usage rows land in `~/.omp/plugins/tersio-usage.jsonl` (local only); `tersio dashboard` serves them as a plain-HTML page on 127.0.0.1.
 
 ## Files and backups
 
@@ -176,7 +159,7 @@ npm exec --yes --prefer-online --package=@krtclcdy/tersio@latest -- tersio insta
 
 **RTK missing or not executable:** run `tersio reinstall`, then `tersio doctor`. On Linux/macOS: `chmod +x ~/.bun/bin/rtk`.
 
-**Checksum warning or failure:** the installer aborts on RTK checksum mismatch but warns and continues when checksum metadata is unavailable; `/ai-addons update rtk` aborts when metadata is missing.
+**Checksum warning or failure:** the installer aborts on RTK checksum mismatch but warns and continues when checksum metadata is unavailable; `/tersio update rtk` aborts when metadata is missing.
 
 ## License
 

package/cli/common.js

@@ -46,7 +46,7 @@ function flagValue(name) {
     return args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
 }
 // --- CLI flags ---
-const COMMANDS = new Set(['install', 'update', 'reinstall', 'doctor', 'uninstall', 'version', 'help']);
+const COMMANDS = new Set(['install', 'update', 'reinstall', 'doctor', 'uninstall', 'usage', 'dashboard', 'version', 'help']);
 const args = process.argv.slice(2);
 const commandArg = args.find((arg, index) => !arg.startsWith('-') && args[index - 1] !== '--scope');
 const command = commandArg?.toLowerCase() || null;
@@ -61,6 +61,11 @@ const dryRun = args.includes('--dry-run');
 const yes = args.includes('--yes') || args.includes('-y') || install || update || reinstall || applyUpdate;
 const verbose = args.includes('--verbose');
 const doctor = command === 'doctor' || args.includes('--doctor');
+const usage = command === 'usage' || args.includes('--usage');
+const dashboard = command === 'dashboard' || args.includes('--dashboard');
+const dashboardPort = Number.parseInt(flagValue('--port') ?? '', 10) || 0;
+const dashboardOpen = args.includes('--open');
+const dashboardExport = flagValue('--export') ?? null;
 const uninstall = command === 'uninstall' || args.includes('--uninstall');
 const removePonytail = args.includes('--remove-ponytail');
 const keepPonytail = args.includes('--keep-ponytail');
@@ -249,4 +254,4 @@ function relTime(ageMs) {
     const weeks = Math.floor(days / 7);
     return `${weeks} week${weeks === 1 ? '' : 's'} ago`;
 }
-export { IS_WINDOWS, RTK_BINARY_NAME, HOME, OMP_AGENT_DIR, OMP_PLUGINS_DIR, BUN_BIN_DIR, OMP_BIN, PACKAGE_NAME, PACKAGE_BIN, PACKAGE_VERSION, CAVEMAN_DEFAULTS, PONYTAIL_DEFAULTS, RTK_DEFAULTS, COMBO_PRESET_MODES, COMBO_DEFAULTS, parseEnum, flagValue, COMMANDS, commandArg, command, unknownCommand, install, update, reinstall, showVersion, showHelp, applyUpdate, dryRun, yes, verbose, doctor, uninstall, removePonytail, keepPonytail, removeRtk, scopeFlag, comboDefaultFlag, cavemanDefaultFlag, ponytailDefaultFlag, rtkDefaultFlag, profileFlagsGiven, debug, execFileP, execP, writeIfChanged, normalizeExtensionsKey, EXTENSIONS_KEY_RE, writeConfigLines, ensureExtensionInConfig, ensureExtensionAfterConfigEntry, readPonytailConfig, parseJsonObject, parsePonytailConfig, patchPonytailConfig, ensurePonytailConfigValue, readPluginsPackage, SCOPE_MAP, relTime, };
+export { IS_WINDOWS, RTK_BINARY_NAME, HOME, OMP_AGENT_DIR, OMP_PLUGINS_DIR, BUN_BIN_DIR, OMP_BIN, PACKAGE_NAME, PACKAGE_BIN, PACKAGE_VERSION, CAVEMAN_DEFAULTS, PONYTAIL_DEFAULTS, RTK_DEFAULTS, COMBO_PRESET_MODES, COMBO_DEFAULTS, parseEnum, flagValue, COMMANDS, commandArg, command, unknownCommand, install, update, reinstall, showVersion, showHelp, applyUpdate, dryRun, yes, verbose, doctor, uninstall, usage, dashboard, dashboardPort, dashboardOpen, dashboardExport, removePonytail, keepPonytail, removeRtk, scopeFlag, comboDefaultFlag, cavemanDefaultFlag, ponytailDefaultFlag, rtkDefaultFlag, profileFlagsGiven, debug, execFileP, execP, writeIfChanged, normalizeExtensionsKey, EXTENSIONS_KEY_RE, writeConfigLines, ensureExtensionInConfig, ensureExtensionAfterConfigEntry, readPonytailConfig, parseJsonObject, parsePonytailConfig, patchPonytailConfig, ensurePonytailConfigValue, readPluginsPackage, SCOPE_MAP, relTime, };

package/cli/dashboard.html

@@ -0,0 +1,404 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="dark light">
+<title>Tersio Gain Dashboard</title>
+<link rel="icon" type="image/png" href="brand.webp">
+<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
+<script src="https://unpkg.com/lucide@latest"></script>
+<style>
+  :root {
+    --bg: #f4f4f5; --panel: #ffffff; --ink: #18181b; --dim: #52525b;
+    --line: rgba(24, 24, 27, .12); --accent: #047857; --accent-soft: rgba(4, 120, 87, .12);
+    --track: rgba(24, 24, 27, .08); --grid: rgba(4, 120, 87, .07);
+    --cell-0: rgba(24, 24, 27, .06);
+    --cell-1: rgba(4, 120, 87, .25); --cell-2: rgba(4, 120, 87, .5);
+    --cell-3: rgba(4, 120, 87, .75); --cell-4: #047857;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #09090b; --panel: #101014; --ink: #f4f4f5; --dim: #a1a1aa;
+      --line: rgba(255, 255, 255, .09); --accent: #34d399; --accent-soft: rgba(52, 211, 153, .1);
+      --track: rgba(255, 255, 255, .07); --grid: rgba(52, 211, 153, .05);
+      --cell-0: rgba(255, 255, 255, .06);
+      --cell-1: rgba(52, 211, 153, .25); --cell-2: rgba(52, 211, 153, .5);
+      --cell-3: rgba(52, 211, 153, .75); --cell-4: #34d399;
+    }
+  }
+  body { background: var(--bg); color: var(--ink); }
+  .bg-blueprint {
+    background-image: linear-gradient(var(--grid) 1px, transparent 1px),
+      linear-gradient(90deg, var(--grid) 1px, transparent 1px);
+    background-size: 44px 44px;
+    mask-image: radial-gradient(ellipse 90% 70% at 50% 0%, black 30%, transparent 75%);
+  }
+  .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-variant-numeric: tabular-nums; }
+  .rowline { border-bottom: 1px solid var(--line); }
+  .bar-fill { background: var(--accent); border-radius: 999px; transform-origin: left; }
+  .bar-track { background: var(--track); border-radius: 999px; }
+  .bar-dim { background: var(--dim); opacity: .55; border-radius: 999px; transform-origin: bottom; }
+  .live-dot { background: var(--accent); box-shadow: 0 0 0 0 var(--accent-soft); animation: ping 2s cubic-bezier(0, 0, .2, 1) infinite; }
+  @keyframes ping { 75%, 100% { box-shadow: 0 0 0 9px transparent; } }
+  .rise { opacity: 0; transform: translateY(26px); }
+  .rise.in { opacity: 1; transform: none; transition: opacity .7s cubic-bezier(.16, 1, .3, 1), transform .7s cubic-bezier(.16, 1, .3, 1); }
+  .grow { transform: scaleX(0); transition: transform 1.1s cubic-bezier(.16, 1, .3, 1); }
+  .grow.in { transform: scaleX(1); }
+  .growY { transform: scaleY(0); transition: transform .9s cubic-bezier(.16, 1, .3, 1); }
+  .growY.in { transform: scaleY(1); }
+  .tilt { transition: transform .25s cubic-bezier(.16, 1, .3, 1), background .25s; }
+  .tilt:hover { transform: translateX(6px); background: var(--accent-soft); }
+  .btn-push { transition: transform .12s, background .2s; }
+  .btn-push:hover { background: var(--accent-soft); }
+  .btn-push:active { transform: scale(.96); }
+  a.social { color: var(--ink); }
+  a.social:hover { color: var(--accent); }
+  .cell { width: 11px; height: 11px; border-radius: 2.5px; background: var(--cell-0); }
+  .cell.l1 { background: var(--cell-1); } .cell.l2 { background: var(--cell-2); }
+  .cell.l3 { background: var(--cell-3); } .cell.l4 { background: var(--cell-4); }
+  .dock {
+    position: sticky; top: 12px; z-index: 50;
+    background: color-mix(in srgb, var(--panel) 84%, transparent);
+    -webkit-backdrop-filter: blur(18px) saturate(160%); backdrop-filter: blur(18px) saturate(160%);
+    border: 1px solid var(--line); border-radius: 20px;
+    box-shadow: 0 12px 40px rgba(0, 0, 0, .25);
+  }
+  .dock a.docklink { transition: transform .22s cubic-bezier(.34, 1.56, .64, 1), background .2s; border-radius: 12px; }
+  .dock a.docklink:hover { transform: scale(1.28) translateY(-3px); background: var(--accent-soft); }
+  .dock a.docklink:active { transform: scale(1.05); }
+  .dock img.brand { border-radius: 10px; }
+  @media (prefers-reduced-motion: reduce) {
+    .dock a.docklink { transition: none; }
+    .dock a.docklink:hover { transform: none; }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .rise { opacity: 1; transform: none; }
+    .grow, .growY { transform: none; transition: none; }
+    .live-dot { animation: none; }
+    .tilt, .btn-push { transition: none; }
+  }
+</style>
+</head>
+<body class="min-h-[100dvh] antialiased">
+<div class="bg-blueprint pointer-events-none fixed inset-0" aria-hidden="true"></div>
+
+<div class="relative mx-auto max-w-7xl px-4 sm:px-6 pb-16">
+
+  <!-- Floating dock navbar -->
+  <header class="dock mt-4 flex w-full items-center gap-2 px-3 py-2">
+    <a href="#" class="flex shrink-0 items-center gap-2.5 pl-1 pr-2" aria-label="Tersio gain home">
+      <img src="brand.webp" alt="Tersio" width="32" height="32" class="brand size-8 rounded-full">
+      <span class="leading-tight text-left">
+        <span class="block font-bold tracking-tight text-sm">TERSIO GAIN</span>
+        <span class="mono block text-[11px]" style="color: var(--dim)" id="meta">connecting to ledger</span>
+      </span>
+    </a>
+    <span class="mono hidden shrink-0 sm:flex items-center gap-2 text-xs px-2 ml-auto" style="color: var(--dim)">
+      <span class="live-dot inline-block size-2 rounded-full"></span>
+      <span id="clock">--:--</span>
+    </span>
+    <button id="reload" class="btn-push mono flex shrink-0 items-center gap-2 text-xs pl-2.5 pr-3 py-2 rounded-xl" style="border: 1px solid var(--line)" aria-label="Reload data">
+      <i data-lucide="refresh-cw" class="size-3.5"></i><span class="hidden md:inline">Reload</span>
+    </button>
+  </header>
+
+  <!-- Hero: asymmetric 7/5 -->
+  <section class="grid grid-cols-1 lg:grid-cols-12 gap-8 pt-10 pb-8 items-end">
+    <div class="lg:col-span-7 rise">
+      <p class="mono text-[11px] uppercase tracking-[0.22em] mb-3" style="color: var(--accent)">Live token feed</p>
+      <p class="mono font-bold tracking-tighter leading-none text-7xl md:text-8xl" id="total">0</p>
+      <p class="mt-3 text-base max-w-[52ch]" style="color: var(--dim)">session tokens parsed from OMP transcripts. Input, output, cache read, cache write, USD cost, CO2.</p>
+    </div>
+    <div class="lg:col-span-5 rise" style="transition-delay: .12s">
+      <dl class="mono text-sm">
+        <div class="flex justify-between gap-4 py-2 rowline"><dt style="color: var(--dim)">usd cost</dt><dd id="usd">-</dd></div>
+        <div class="flex justify-between gap-4 py-2 rowline"><dt style="color: var(--dim)">co2</dt><dd id="co2">-</dd></div>
+        <div class="flex justify-between gap-4 py-2"><dt style="color: var(--dim)">assistant msgs</dt><dd id="msgs">0</dd></div>
+      </dl>
+    </div>
+  </section>
+
+  <!-- Token strip: plain stats, dividers, no cards -->
+  <section class="rise grid grid-cols-2 sm:grid-cols-4 rounded-xl overflow-hidden" style="border: 1px solid var(--line); background: var(--panel)" id="tokens" aria-label="Tokens by bucket"></section>
+
+  <!-- Contribution graph, GitHub style -->
+  <section id="activity" class="rise mt-8 rounded-xl p-5 overflow-hidden" style="border: 1px solid var(--line); background: var(--panel); scroll-margin-top: 90px" aria-label="Activity graph">
+    <div class="flex items-center gap-2 mb-1">
+      <i data-lucide="calendar-days" class="size-4" style="color: var(--accent)"></i>
+      <h2 class="font-bold tracking-tight text-xl">Activity</h2>
+      <span class="mono text-xs ml-auto" style="color: var(--dim)" id="graphRange"></span>
+    </div>
+    <p class="mono text-xs mb-4" style="color: var(--dim)">daily session tokens / last 26 weeks / darker means more</p>
+    <div class="overflow-x-auto pb-1">
+      <div class="flex gap-[3px] w-max" id="graph"></div>
+    </div>
+    <div class="mono text-[11px] mt-3 flex items-center gap-1.5" style="color: var(--dim)">
+      <span>less</span>
+      <span class="cell"></span><span class="cell l1"></span><span class="cell l2"></span><span class="cell l3"></span><span class="cell l4"></span>
+      <span>more</span>
+    </div>
+  </section>
+
+  <!-- Main: 8/4 split -->
+  <main class="grid grid-cols-1 lg:grid-cols-12 gap-8 mt-8">
+
+    <div class="lg:col-span-8 flex flex-col gap-8">
+      <section id="daily" class="rise" style="scroll-margin-top: 90px" aria-label="Daily chart">
+        <div class="flex items-center gap-2 mb-1">
+          <i data-lucide="chart-column" class="size-4" style="color: var(--accent)"></i>
+          <h2 class="font-bold tracking-tight text-xl">Daily input vs output</h2>
+        </div>
+        <p class="mono text-xs mb-4" style="color: var(--dim)">last 14 days / tall bar input, short bar output</p>
+        <div class="rounded-xl p-5" style="border: 1px solid var(--line); background: var(--panel)">
+          <div class="flex items-end gap-2 h-36" id="chart"></div>
+          <div class="flex gap-2 mt-2 mono text-[10px]" style="color: var(--dim)" id="chartDays"></div>
+        </div>
+      </section>
+
+      <section id="commands" class="rise" style="scroll-margin-top: 90px" aria-label="Top commands">
+        <div class="flex items-center gap-2 mb-1">
+          <i data-lucide="terminal" class="size-4" style="color: var(--accent)"></i>
+          <h2 class="font-bold tracking-tight text-xl">Top commands</h2>
+        </div>
+        <p class="mono text-xs mb-4" style="color: var(--dim)">ranked by ledger count / top 10</p>
+        <ol id="top" class="rounded-xl overflow-hidden" style="border: 1px solid var(--line); background: var(--panel)"></ol>
+        <p id="emptyTop" class="mono text-sm py-8 text-center hidden" style="color: var(--dim)">No ledger rows yet. Run tersio commands to record activity.</p>
+      </section>
+    </div>
+
+    <div class="lg:col-span-4 flex flex-col gap-8">
+      <section id="savings" class="rise rounded-xl p-5" style="border: 1px solid var(--line); background: var(--panel); transition-delay: .1s; scroll-margin-top: 90px" aria-label="Savings">
+        <div class="flex items-center gap-2 mb-3">
+          <i data-lucide="gauge" class="size-4" style="color: var(--accent)"></i>
+          <h2 class="font-bold tracking-tight text-xl">Savings</h2>
+        </div>
+        <ul class="mono text-[13px] leading-relaxed space-y-2">
+          <li class="flex gap-2"><i data-lucide="circle-dollar-sign" class="size-4 shrink-0 mt-0.5" style="color: var(--accent)"></i><span id="usdLine">USD from per-model price table.</span></li>
+          <li class="flex gap-2"><i data-lucide="leaf" class="size-4 shrink-0 mt-0.5" style="color: var(--accent)"></i><span id="co2Line">CO2 ~est. from output tokens.</span></li>
+          <li class="flex gap-2"><i data-lucide="database" class="size-4 shrink-0 mt-0.5" style="color: var(--accent)"></i><span id="cacheLine">Cache share loads with session data.</span></li>
+        </ul>
+      </section>
+
+      <section class="rise rounded-xl p-5" style="border: 1px solid var(--line); background: var(--panel); transition-delay: .18s" aria-label="Models">
+        <div class="flex items-center gap-2 mb-3">
+          <i data-lucide="cpu" class="size-4" style="color: var(--accent)"></i>
+          <h2 class="font-bold tracking-tight text-xl">Models</h2>
+        </div>
+        <ol id="models" class="mono text-[13px] space-y-2" style="scroll-margin-top: 90px"></ol>
+      </section>
+    </div>
+  </main>
+
+  <footer class="mono text-xs mt-12 pt-4 flex items-center gap-4" style="color: var(--dim); border-top: 1px solid var(--line)">
+    <span>tersio gain dashboard / single file</span>
+    <span class="ml-auto flex items-center gap-1" style="color: var(--ink)">
+<a href="https://github.com/KurutoDenzeru" target="_blank" rel="noopener" aria-label="GitHub" class="btn-push social grid size-8 place-items-center rounded-lg"><svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg></a>
+<a href="https://linkedin.com/in/kurtcalacday/" target="_blank" rel="noopener" aria-label="LinkedIn" class="btn-push social grid size-8 place-items-center rounded-lg"><svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433c-1.144 0-2.063-.926-2.063-2.065 0-1.138.92-2.063 2.063-2.063 1.14 0 2.064.925 2.064 2.063 0 1.139-.925 2.065-2.064 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z"/></svg></a>
+<a href="https://instagram.com/krtclcdy/" target="_blank" rel="noopener" aria-label="Instagram" class="btn-push social grid size-8 place-items-center rounded-lg"><svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M7.0301.084c-1.2768.0602-2.1487.264-2.911.5634-.7888.3075-1.4575.72-2.1228 1.3877-.6652.6677-1.075 1.3368-1.3802 2.127-.2954.7638-.4956 1.6365-.552 2.914-.0564 1.2775-.0689 1.6882-.0626 4.947.0062 3.2586.0206 3.6671.0825 4.9473.061 1.2765.264 2.1482.5635 2.9107.308.7889.72 1.4573 1.388 2.1228.6679.6655 1.3365 1.0743 2.1285 1.38.7632.295 1.6361.4961 2.9134.552 1.2773.056 1.6884.069 4.9462.0627 3.2578-.0062 3.668-.0207 4.9478-.0814 1.28-.0607 2.147-.2652 2.9098-.5633.7889-.3086 1.4578-.72 2.1228-1.3881.665-.6682 1.0745-1.3378 1.3795-2.1284.2957-.7632.4966-1.636.552-2.9124.056-1.2809.0692-1.6898.063-4.948-.0063-3.2583-.021-3.6668-.0817-4.9465-.0607-1.2797-.264-2.1487-.5633-2.9117-.3084-.7889-.72-1.4568-1.3876-2.1228C21.2982 1.33 20.628.9208 19.8378.6165 19.074.321 18.2017.1197 16.9244.0645 15.6471.0093 15.236-.005 11.977.0014 8.718.0076 8.31.0215 7.0301.0839m.1402 21.6932c-1.17-.0509-1.8053-.2453-2.2287-.408-.5606-.216-.96-.4771-1.3819-.895-.422-.4178-.6811-.8186-.9-1.378-.1644-.4234-.3624-1.058-.4171-2.228-.0595-1.2645-.072-1.6442-.079-4.848-.007-3.2037.0053-3.583.0607-4.848.05-1.169.2456-1.805.408-2.2282.216-.5613.4762-.96.895-1.3816.4188-.4217.8184-.6814 1.3783-.9003.423-.1651 1.0575-.3614 2.227-.4171 1.2655-.06 1.6447-.072 4.848-.079 3.2033-.007 3.5835.005 4.8495.0608 1.169.0508 1.8053.2445 2.228.408.5608.216.96.4754 1.3816.895.4217.4194.6816.8176.9005 1.3787.1653.4217.3617 1.056.4169 2.2263.0602 1.2655.0739 1.645.0796 4.848.0058 3.203-.0055 3.5834-.061 4.848-.051 1.17-.245 1.8055-.408 2.2294-.216.5604-.4763.96-.8954 1.3814-.419.4215-.8181.6811-1.3783.9-.4224.1649-1.0577.3617-2.2262.4174-1.2656.0595-1.6448.072-4.8493.079-3.2045.007-3.5825-.006-4.848-.0608M16.953 5.5864A1.44 1.44 0 1 0 18.39 4.144a1.44 1.44 0 0 0-1.437 1.4424M5.8385 12.012c.0067 3.4032 2.7706 6.1557 6.173 6.1493 3.4026-.0065 6.157-2.7701 6.1506-6.1733-.0065-3.4032-2.771-6.1565-6.174-6.1498-3.403.0067-6.156 2.771-6.1496 6.1738M8 12.0077a4 4 0 1 1 4.008 3.9921A3.9996 3.9996 0 0 1 8 12.0077"/></svg></a>
+</span>
+    <a id="rawlink" href="data.json" class="underline underline-offset-2">raw data.json</a>
+  </footer>
+</div>
+
+<script>
+(function () {
+  var reduce = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  function fmt(n) { return Number(n).toLocaleString('en-US'); }
+
+  function countUp(el, target, money) {
+    function text(v) { return money ? '$' + v.toFixed(2) : fmt(Math.round(v)); }
+    if (reduce || target <= 0) { el.textContent = text(target); return; }
+    var t0 = null, dur = 900;
+    function step(t) {
+      if (!t0) t0 = t;
+      var p = Math.min((t - t0) / dur, 1), e = 1 - Math.pow(1 - p, 3);
+      el.textContent = text(target * e);
+      if (p < 1) requestAnimationFrame(step);
+    }
+    requestAnimationFrame(step);
+  }
+
+  function tick() {
+    var c = document.getElementById('clock');
+    if (c) c.textContent = new Date().toLocaleString('en-US', { month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit' });
+  }
+  tick(); setInterval(tick, 1000);
+
+  function dayKey(d) {
+    return d.getFullYear() + '-' + String(d.getMonth() + 1).padStart(2, '0') + '-' + String(d.getDate()).padStart(2, '0');
+  }
+
+  function renderGraph(byDay) {
+    var g = document.getElementById('graph');
+    g.innerHTML = '';
+    var today = new Date(); today.setHours(0, 0, 0, 0);
+    var start = new Date(today); start.setDate(start.getDate() - (26 * 7 - 1) - today.getDay());
+    var max = 1, sums = {};
+    Object.keys(byDay).forEach(function (day) {
+      var b = byDay[day];
+      sums[day] = b.input + b.output + b.cacheRead + b.cacheWrite;
+      if (sums[day] > max) max = sums[day];
+    });
+    var weeks = 0;
+    for (var w = 0; w < 26; w++) {
+      var col = document.createElement('div');
+      col.className = 'flex flex-col gap-[3px]';
+      for (var i = 0; i < 7; i++) {
+        var dt = new Date(start); dt.setDate(dt.getDate() + weeks * 7 + i);
+        var key = dayKey(dt), v = sums[key] || 0, lvl = 0;
+        if (v > 0) lvl = Math.min(4, 1 + Math.floor((v / max) * 3.99));
+        var cell = document.createElement('span');
+        cell.className = 'cell' + (lvl ? ' l' + lvl : '');
+        cell.title = key + ': ' + fmt(v) + ' tokens';
+        col.appendChild(cell);
+      }
+      weeks++;
+      g.appendChild(col);
+    }
+    document.getElementById('graphRange').textContent =
+      dayKey(start) + ' to ' + dayKey(today);
+  }
+
+  function renderChart(byDay) {
+    var chart = document.getElementById('chart'), days = document.getElementById('chartDays');
+    chart.innerHTML = ''; days.innerHTML = '';
+    var list = [], today = new Date(); today.setHours(0, 0, 0, 0);
+    for (var i = 13; i >= 0; i--) {
+      var dt = new Date(today); dt.setDate(dt.getDate() - i);
+      list.push({ key: dayKey(dt), label: String(dt.getDate()), b: byDay[dayKey(dt)] || { input: 0, output: 0 } });
+    }
+    var max = 1;
+    list.forEach(function (d) { max = Math.max(max, d.b.input, d.b.output); });
+    list.forEach(function (d, i) {
+      var wrap = document.createElement('div');
+      wrap.className = 'flex-1 flex items-end justify-center gap-1 h-full';
+      wrap.title = d.key + ': in ' + fmt(d.b.input) + ' / out ' + fmt(d.b.output);
+      var bi = document.createElement('div');
+      bi.className = 'bar-fill growY w-3';
+      bi.style.height = Math.max(2, Math.round(d.b.input / max * 100)) + '%';
+      bi.style.transitionDelay = reduce ? '' : (i * 40) + 'ms';
+      var bo = document.createElement('div');
+      bo.className = 'bar-dim growY w-3';
+      bo.style.height = Math.max(2, Math.round(d.b.output / max * 100)) + '%';
+      bo.style.transitionDelay = reduce ? '' : (i * 40 + 60) + 'ms';
+      wrap.appendChild(bi); wrap.appendChild(bo); chart.appendChild(wrap);
+      var lb = document.createElement('span');
+      lb.className = 'flex-1 text-center'; lb.textContent = d.label;
+      days.appendChild(lb);
+    });
+  }
+
+  function render(d) {
+    var t = d.tokens || { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+    var total = t.input + t.output + t.cacheRead + t.cacheWrite;
+    document.getElementById('meta').textContent =
+      fmt(total) + ' session tokens / ' + d.total + ' ledger rows';
+    countUp(document.getElementById('total'), total);
+    countUp(document.getElementById('usd'), d.usd || 0, true);
+    document.getElementById('co2').textContent = '~' + (d.co2g || 0).toFixed(1) + 'g (est.)';
+    document.getElementById('msgs').textContent = fmt(d.messages || 0);
+
+    var buckets = [['input', t.input, 'arrow-down-to-line'], ['output', t.output, 'arrow-up-from-line'], ['cache read', t.cacheRead, 'hard-drive-download'], ['cache write', t.cacheWrite, 'hard-drive-upload']];
+    var strip = document.getElementById('tokens');
+    strip.innerHTML = '';
+    buckets.forEach(function (b, i) {
+      var cell = document.createElement('div');
+      cell.className = 'tilt px-4 py-4' + (i > 0 ? ' sm:border-l' : '');
+      cell.style.borderColor = 'var(--line)';
+      cell.innerHTML = '<div class="flex items-center gap-2 mono text-[11px] uppercase tracking-[0.14em]" style="color: var(--dim)">' +
+        '<i data-lucide="' + b[2] + '" class="size-3.5"></i><span></span></div>' +
+        '<p class="mono font-bold text-3xl mt-1"></p>';
+      cell.querySelector('span').textContent = b[0];
+      cell.querySelector('p').textContent = fmt(b[1]);
+      strip.appendChild(cell);
+    });
+
+    renderGraph(d.byDay || {});
+    renderChart(d.byDay || {});
+
+    var cacheShare = total ? Math.round((t.cacheRead + t.cacheWrite) / total * 100) : 0;
+    document.getElementById('usdLine').textContent =
+      '$' + (d.usd || 0).toFixed(2) + (d.priced ? ' measured (price table).' : ' incl. default pricing.');
+    document.getElementById('co2Line').textContent =
+      '~' + (d.co2g || 0).toFixed(1) + 'g CO2 est. from output tokens.';
+    document.getElementById('cacheLine').textContent =
+      cacheShare + '% of tokens served from cache.';
+
+    var models = document.getElementById('models');
+    models.innerHTML = '';
+    Object.entries(d.byModel || {}).sort(function (a, b) {
+      return (b[1].input + b[1].output) - (a[1].input + a[1].output);
+    }).slice(0, 5).forEach(function (row) {
+      var li = document.createElement('li');
+      li.className = 'flex justify-between gap-2';
+      var name = document.createElement('span'); name.className = 'truncate'; name.textContent = row[0];
+      var n = document.createElement('span'); n.textContent = fmt(row[1].input + row[1].output);
+      li.appendChild(name); li.appendChild(n); models.appendChild(li);
+    });
+    if (!models.children.length) {
+      models.innerHTML = '<li style="color: var(--dim)">no session tokens yet</li>';
+    }
+
+    var ol = document.getElementById('top');
+    ol.innerHTML = '';
+    var max = 1;
+    (d.byDetail || []).forEach(function (row) { if (row[1] > max) max = row[1]; });
+    (d.byDetail || []).forEach(function (row, i) {
+      var li = document.createElement('li');
+      li.className = 'tilt flex items-center gap-3 px-4 py-3' + (i < d.byDetail.length - 1 ? ' rowline' : '');
+      var rank = document.createElement('span');
+      rank.className = 'mono text-xs w-6 shrink-0'; rank.style.color = 'var(--dim)';
+      rank.textContent = String(i + 1).padStart(2, '0');
+      var mid = document.createElement('div'); mid.className = 'min-w-0 flex-1';
+      var name = document.createElement('p'); name.className = 'mono text-sm truncate'; name.textContent = row[0];
+      var track = document.createElement('div'); track.className = 'bar-track mt-1.5 h-1.5 overflow-hidden';
+      var fill = document.createElement('div'); fill.className = 'bar-fill grow h-full';
+      fill.style.width = Math.max(2, Math.round(row[1] / max * 100)) + '%';
+      track.appendChild(fill); mid.appendChild(name); mid.appendChild(track);
+      var n = document.createElement('span'); n.className = 'mono font-bold text-lg shrink-0'; n.textContent = String(row[1]);
+      li.appendChild(rank); li.appendChild(mid); li.appendChild(n);
+      ol.appendChild(li);
+    });
+    document.getElementById('emptyTop').classList.toggle('hidden', (d.total || 0) > 0);
+    ol.classList.toggle('hidden', (d.total || 0) === 0);
+
+    if (window.lucide) lucide.createIcons();
+    observe();
+  }
+
+  var seen = new WeakSet();
+  function observe() {
+    var els = document.querySelectorAll('.rise, .grow, .growY');
+    if (!('IntersectionObserver' in window) || reduce) {
+      els.forEach(function (el) { el.classList.add('in'); });
+      return;
+    }
+    var io = new IntersectionObserver(function (entries) {
+      entries.forEach(function (e) {
+        if (e.isIntersecting && !seen.has(e.target)) {
+          seen.add(e.target); e.target.classList.add('in'); io.unobserve(e.target);
+        }
+      });
+    }, { threshold: 0.12 });
+    els.forEach(function (el) { if (!seen.has(el)) io.observe(el); });
+  }
+
+  function load() {
+    document.getElementById('meta').textContent = 'connecting to ledger';
+    fetch('data.json').then(function (r) { return r.json(); }).then(render).catch(function () {
+      document.getElementById('meta').textContent = 'No live data. Serve with: tersio dashboard';
+      document.getElementById('rawlink').style.display = 'none';
+      document.getElementById('emptyTop').classList.remove('hidden');
+      if (window.lucide) lucide.createIcons();
+      observe();
+    });
+  }
+  document.getElementById('reload').addEventListener('click', load);
+  load();
+  observe();
+})();
+</script>
+</body>
+</html>

package/cli/dashboard.js

@@ -0,0 +1,72 @@
+// cli/dashboard.ts — localhost gain dashboard. Serves the single plain-HTML
+// template (no deps, no build) plus a /data.json endpoint from the ledger.
+// Binds 127.0.0.1 only; --export writes a file://-ready file instead.
+// Note: no Promise.withResolvers here — engines still allow Node 20.12,
+// which lacks it; the listening server itself keeps the process alive.
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readUsage } from '../extensions/shared/usage-ledger.js';
+import { summarizeUsage } from './usage.js';
+import { withInteractiveSpinner } from './interactive.js';
+const TEMPLATE = path.join(path.dirname(fileURLToPath(import.meta.url)), 'dashboard.html');
+const BRAND = path.join(path.dirname(fileURLToPath(import.meta.url)), 'brand.webp');
+async function templateHtml() {
+    return fs.readFile(TEMPLATE, 'utf8');
+}
+async function faviconDataUri() {
+    const png = await fs.readFile(BRAND);
+    return `data:image/webp;base64,${png.toString('base64')}`;
+}
+function dataJson() {
+    return JSON.stringify(summarizeUsage(readUsage()));
+}
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
+}
+async function runDashboard(options) {
+    if (options.exportFile) {
+        const html = await templateHtml();
+        const inline = html
+            .replace("fetch('data.json')", `Promise.resolve({ json: function () { return ${dataJson()}; } }).then(function (r) { return r.json(); }).then`)
+            .replace('href="brand.webp"', `href="${await faviconDataUri()}"`)
+            .replace('src="brand.webp"', `src="${await faviconDataUri()}"`);
+        await fs.writeFile(options.exportFile, inline, 'utf8');
+        console.log(`[ok] dashboard exported → ${options.exportFile}`);
+        return;
+    }
+    const html = await withInteractiveSpinner('Loading dashboard template', templateHtml);
+    const server = http.createServer(async (req, res) => {
+        if (req.url === '/data.json') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(dataJson());
+            return;
+        }
+        if (req.url === '/brand.webp') {
+            try {
+                const png = await fs.readFile(BRAND);
+                res.writeHead(200, { 'Content-Type': 'image/webp' });
+                res.end(png);
+            }
+            catch {
+                res.writeHead(404);
+                res.end();
+            }
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(html);
+    });
+    server.listen(options.port, '127.0.0.1', () => {
+        const address = server.address();
+        const port = typeof address === 'object' && address ? address.port : options.port;
+        const url = `http://127.0.0.1:${port}`;
+        console.log(`[ok] dashboard live → ${url} (Ctrl-C to stop)`);
+        if (options.open)
+            openBrowser(url);
+    });
+}
+export { runDashboard };

package/cli/doctor.js

@@ -3,6 +3,7 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { BUN_BIN_DIR, HOME, OMP_AGENT_DIR, OMP_PLUGINS_DIR, OMP_BIN, PACKAGE_NAME, PACKAGE_VERSION, RTK_BINARY_NAME, execP, parseJsonObject, relTime, } from './common.js';
 import { runInteractivePhase } from './interactive.js';
+import { ledgerPath, readUsage } from '../extensions/shared/usage-ledger.js';
 import { checkForUpdate } from './update.js';
 import { readTextIfExists } from '../extensions/lib/utils.js';
 async function runDoctor() {
@@ -123,6 +124,9 @@ async function runDoctor() {
     check('Self plugin package', selfPkgText !== null, parseJsonObject(selfPkgText)?.version ?? '');
     const selfDep = PACKAGE_NAME in (parseJsonObject(pluginsPkgRaw)?.dependencies || {});
     check('Self plugin in plugins/package.json', selfDep);
+    section('Usage');
+    const usageRows = readUsage();
+    check('Usage ledger', usageRows.length > 0, usageRows.length ? `${usageRows.length} rows · ${ledgerPath()}` : ledgerPath());
     section('Add-ons');
     const ruleAge = ruleMtime ? `updated ${relTime(Date.now() - ruleMtime.mtimeMs)}` : '';
     check('Caveman rule', cavemanRuleText !== null, ruleAge);

package/cli/usage.js

@@ -0,0 +1,71 @@
+// cli/usage.ts — ledger + session-token usage report, tokscale-style.
+import { co2Grams, importSessionTokens, readUsage, usdCost, } from '../extensions/shared/usage-ledger.js';
+import { withInteractiveSpinner } from './interactive.js';
+export function summarizeUsage(rows) {
+    const byKind = {};
+    const detailCounts = {};
+    for (const r of rows) {
+        byKind[r.kind] = (byKind[r.kind] ?? 0) + 1;
+        detailCounts[r.detail] = (detailCounts[r.detail] ?? 0) + 1;
+    }
+    const byDetail = Object.entries(detailCounts).sort((a, b) => b[1] - a[1]).slice(0, 10);
+    const session = importSessionTokens();
+    let usd = 0;
+    let priced = true;
+    for (const [model, t] of Object.entries(session.byModel)) {
+        const c = usdCost(t, model);
+        usd += c.usd;
+        if (!c.priced)
+            priced = false;
+    }
+    return {
+        total: rows.length,
+        byKind,
+        byDetail,
+        lastWrite: rows.length ? new Date(rows[rows.length - 1].ts).toISOString() : null,
+        empty: rows.length === 0 && session.messages === 0,
+        messages: session.messages,
+        tokens: session.totals,
+        byModel: session.byModel,
+        byDay: session.byDay,
+        usd,
+        priced,
+        co2g: co2Grams(session.totals.output),
+    };
+}
+function fmt(n) {
+    return n.toLocaleString('en-US');
+}
+function printReport(report) {
+    console.log('\n=== Tersio Usage ===');
+    if (report.empty) {
+        console.log('  No ledger rows or session tokens yet — run session commands first.');
+        return;
+    }
+    const t = report.tokens;
+    console.log(`  Tokens  input ${fmt(t.input)} · output ${fmt(t.output)} · cache read ${fmt(t.cacheRead)} · cache write ${fmt(t.cacheWrite)} (${report.messages} assistant messages)`);
+    console.log(`  Cost    $${report.usd.toFixed(2)}${report.priced ? '' : ' (includes default pricing for unknown models)'} · CO2 ~${report.co2g.toFixed(1)}g (est.)`);
+    const models = Object.entries(report.byModel).sort((a, b) => (b[1].input + b[1].output) - (a[1].input + a[1].output)).slice(0, 5);
+    if (models.length) {
+        console.log('  By model');
+        for (const [model, b] of models) {
+            console.log(`    ${model}: in ${fmt(b.input)} · out ${fmt(b.output)} · cache r/w ${fmt(b.cacheRead)}/${fmt(b.cacheWrite)}`);
+        }
+    }
+    if (report.total) {
+        console.log('  Activity');
+        for (const [kind, n] of Object.entries(report.byKind)) {
+            console.log(`    ${kind}: ${n}`);
+        }
+        console.log('  Top commands');
+        for (const [detail, n] of report.byDetail) {
+            console.log(`    ${n}× ${detail}`);
+        }
+        console.log(`  Total rows: ${report.total} · last write: ${report.lastWrite}`);
+    }
+}
+async function runUsage() {
+    const report = await withInteractiveSpinner('Reading usage ledger', async () => summarizeUsage(readUsage()));
+    printReport(report);
+}
+export { runUsage };

package/extensions/ai-addons-updater/index.js

@@ -82,6 +82,33 @@ function checkCaveman() {
         return `Caveman ${status}: local=${localHash || '—'} remote=${remoteHash}`;
     });
 }
+export async function checkAddonsSummary(ctx) {
+    return checkAddons(ctx);
+}
+export async function runAddonUpdate(pi, ctx, target, dryRun = false) {
+    const results = [];
+    const updaters = {
+        ponytail: () => updatePonytail(pi, ctx, dryRun),
+        rtk: () => updateRtk(ctx, dryRun),
+        caveman: () => updateCaveman(ctx, dryRun),
+    };
+    if (target === 'all') {
+        notify(ctx, `ai-addons update all${dryRun ? ' dry-run' : ''}: starting ponytail → rtk → caveman sequentially…`, 'info');
+        for (const name of ['ponytail', 'rtk', 'caveman'])
+            results.push(await updaters[name]());
+        if (!dryRun)
+            results.push(RELOAD_MSG);
+        notify(ctx, `ai-addons update all ${dryRun ? 'dry-run ' : ''}complete.${dryRun ? '' : ` ${RELOAD_MSG}`}`, 'info');
+    }
+    else if (Object.hasOwn(updaters, target)) {
+        results.push(await updaters[target]());
+    }
+    else {
+        const m = 'Usage: /ai-addons update <ponytail|rtk|caveman|all> [--dry-run]';
+        return report(ctx, m, 'warning');
+    }
+    return results.join('\n\n');
+}
 async function checkAddons(ctx) {
     const [ponytail, rtk, caveman] = await Promise.all([checkPonytail(), checkRtk(), checkCaveman()]);
     const lines = [];
@@ -294,29 +321,7 @@ export default function aiAddonsUpdaterExtension(pi) {
                 return summary;
             }
             if (sub === 'update' && cleanParts[1]) {
-                const target = cleanParts.slice(1).join(' ');
-                const results = [];
-                const updaters = {
-                    ponytail: () => updatePonytail(pi, ctx, dryRun),
-                    rtk: () => updateRtk(ctx, dryRun),
-                    caveman: () => updateCaveman(ctx, dryRun),
-                };
-                if (target === 'all') {
-                    notify(ctx, `ai-addons update all${dryRun ? ' dry-run' : ''}: starting ponytail → rtk → caveman sequentially…`, 'info');
-                    for (const name of ['ponytail', 'rtk', 'caveman'])
-                        results.push(await updaters[name]());
-                    if (!dryRun)
-                        results.push(RELOAD_MSG);
-                    notify(ctx, `ai-addons update all ${dryRun ? 'dry-run ' : ''}complete.${dryRun ? '' : ` ${RELOAD_MSG}`}`, 'info');
-                }
-                else if (Object.hasOwn(updaters, target)) {
-                    results.push(await updaters[target]());
-                }
-                else {
-                    const m = 'Usage: /ai-addons update <ponytail|rtk|caveman|all> [--dry-run]';
-                    return report(ctx, m, 'warning');
-                }
-                return results.join('\n\n');
+                return runAddonUpdate(pi, ctx, cleanParts.slice(1).join(' '), dryRun);
             }
             const m = 'Usage: /ai-addons <check|status|update ponytail|rtk|caveman|all> [--dry-run]';
             return report(ctx, m, 'warning');

package/extensions/shared/usage-ledger.js

@@ -0,0 +1,156 @@
+// Shared usage ledger: append-only JSON-lines file. One source of truth read
+// by `tersio usage`, `/tersio usage`, and the gain dashboard.
+// Best-effort by design: a ledger failure never breaks the caller, and
+// corrupt lines are skipped on read (same pattern as the config normalizer).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function ledgerPath() {
+    const override = process.env.TERSIO_USAGE_FILE;
+    if (override)
+        return override;
+    return path.join(os.homedir(), '.omp', 'plugins', 'tersio-usage.jsonl');
+}
+export function appendUsage(kind, detail) {
+    const row = JSON.stringify({ ts: Date.now(), kind, detail }) + '\n';
+    try {
+        fs.mkdirSync(path.dirname(ledgerPath()), { recursive: true });
+        fs.appendFileSync(ledgerPath(), row, 'utf8');
+    }
+    catch { /* ledger is best-effort; never break the caller */ }
+}
+function zeroBreakdown() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+}
+function addInto(into, u) {
+    for (const k of ['input', 'output', 'cacheRead', 'cacheWrite']) {
+        const v = u[k];
+        if (typeof v === 'number' && Number.isFinite(v) && v > 0)
+            into[k] += Math.floor(v);
+    }
+}
+export function sessionsDir() {
+    const override = process.env.TERSIO_SESSIONS_DIR;
+    if (override)
+        return override;
+    return path.join(os.homedir(), '.omp', 'agent', 'sessions');
+}
+function dayKey(ts) {
+    const ms = typeof ts === 'number' ? ts : Date.parse(ts);
+    if (!Number.isFinite(ms))
+        return null;
+    const d = new Date(ms);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+function walkJsonl(dir, out, cap) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (out.length >= cap)
+            return;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            walkJsonl(full, out, cap);
+        else if (e.isFile() && e.name.endsWith('.jsonl'))
+            out.push(full);
+    }
+}
+export function importSessionTokens() {
+    const byModel = {};
+    const byDay = {};
+    const totals = zeroBreakdown();
+    let messages = 0;
+    const files = [];
+    walkJsonl(sessionsDir(), files, 2000);
+    for (const file of files) {
+        let text;
+        try {
+            text = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const row = JSON.parse(line);
+                const msg = row.message;
+                if (!msg || msg.role !== 'assistant' || !msg.usage)
+                    continue;
+                const model = typeof msg.model === 'string' && msg.model ? msg.model : 'unknown';
+                addInto(totals, msg.usage);
+                byModel[model] ??= zeroBreakdown();
+                addInto(byModel[model], msg.usage);
+                const day = row.timestamp !== undefined ? dayKey(row.timestamp) : null;
+                if (day) {
+                    byDay[day] ??= zeroBreakdown();
+                    addInto(byDay[day], msg.usage);
+                }
+                messages += 1;
+            }
+            catch { /* skip corrupt lines */ }
+        }
+    }
+    return { messages, totals, byModel, byDay };
+}
+const PRICE_TABLE = [
+    { match: ':free', price: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } },
+    { match: 'opus', price: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 } },
+    { match: 'sonnet', price: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 } },
+    { match: 'haiku', price: { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 } },
+    { match: 'gpt', price: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 2.5 } },
+    { match: 'gemini', price: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 1.25 } },
+    { match: 'glm', price: { input: 0.5, output: 1, cacheRead: 0.05, cacheWrite: 0.5 } },
+];
+const DEFAULT_PRICE = { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 };
+export function priceFor(model) {
+    const name = model.toLowerCase();
+    for (const row of PRICE_TABLE) {
+        if (name.includes(row.match))
+            return { price: row.price, known: true };
+    }
+    return { price: DEFAULT_PRICE, known: false };
+}
+export function usdCost(t, model) {
+    const { price, known } = model ? priceFor(model) : { price: DEFAULT_PRICE, known: false };
+    const m = 1 / 1_000_000;
+    return {
+        usd: (t.input * price.input + t.output * price.output + t.cacheRead * price.cacheRead + t.cacheWrite * price.cacheWrite) * m,
+        priced: model ? known : false,
+    };
+}
+// ponytail: CO2 is a rough server-energy multiple on output tokens, not metered.
+// Always render with ~est. and never merge with measured figures.
+export const CO2_G_PER_1K_OUTPUT = 0.2;
+export function co2Grams(outputTokens) {
+    return (outputTokens / 1000) * CO2_G_PER_1K_OUTPUT;
+}
+export function readUsage() {
+    let text;
+    try {
+        text = fs.readFileSync(ledgerPath(), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const row = JSON.parse(line);
+            if (typeof row.ts === 'number' && typeof row.kind === 'string' && typeof row.detail === 'string') {
+                rows.push({ ts: row.ts, kind: row.kind, detail: row.detail });
+            }
+        }
+        catch { /* skip corrupt lines */ }
+    }
+    return rows;
+}

package/extensions/tersio-commands/index.js

@@ -0,0 +1,148 @@
+// /tersio unified root command — routes every tersio capability through one
+// namespaced entrypoint. Aliases (/caveman, /rtk, /combo, /ai-addons) keep
+// working: this router drives the same shared bridge + session entries the
+// sibling extensions restore from, then reloads so their local mirrors sync
+// (same mechanism /combo already uses to drive its siblings).
+import { COMBO_LEVELS, activeModesSummary, getSharedComboState, normalizeComboLevel, normalizeMode, reconcileSharedComboEntries, sessionEntries, setSharedComboLevel, setSharedComboMode, } from '../shared/session-state.js';
+import { appendUsage, readUsage } from '../shared/usage-ledger.js';
+import { checkAddonsSummary, runAddonUpdate } from '../ai-addons-updater/index.js';
+const HELP = [
+    '/tersio caveman lite|full|ultra|wenyan|off — terse-reply mode',
+    '/tersio combo off|medium|balanced|max — preset for all three modes',
+    '/tersio rtk on|off — compact shell output',
+    '/tersio ponytail off|lite|full|ultra|review — minimal code',
+    '/tersio status — active modes + combo level',
+    '/tersio check — add-on version check',
+    '/tersio update <ponytail|rtk|caveman|all> [--dry-run]',
+    '/tersio gain — savings summary + dashboard hint',
+    '/tersio usage — ledger report for this machine',
+    '/tersio help — this table',
+    'aliases (still work): /caveman /rtk /combo /ai-addons',
+].join('\n');
+function statusLine() {
+    const s = getSharedComboState();
+    const level = s.level === 'custom' ? 'INACTIVE' : s.level.toUpperCase();
+    return `tersio — caveman=${s.caveman.toUpperCase()} · rtk=${s.rtk.toUpperCase()} · ponytail=${s.ponytail.toUpperCase()} (combo ${level})`;
+}
+function usageSummary() {
+    const rows = readUsage();
+    if (rows.length === 0)
+        return 'tersio usage: no ledger yet — run commands first.';
+    const byKind = {};
+    for (const r of rows)
+        byKind[r.kind] = (byKind[r.kind] ?? 0) + 1;
+    const parts = Object.entries(byKind).map(([k, n]) => `${k}×${n}`);
+    const last = new Date(rows[rows.length - 1].ts).toISOString();
+    return `tersio usage: ${rows.length} rows (${parts.join(', ')}), last write ${last}.`;
+}
+export default function tersioCommandsExtension(pi) {
+    pi.setLabel?.('Tersio unified root command');
+    async function reload(ctx) {
+        if (ctx?.reload)
+            await ctx.reload();
+    }
+    pi.registerCommand?.('tersio', {
+        description: 'Tersio root: caveman|combo|rtk|ponytail|status|check|update|gain|usage|help',
+        handler: async (args, ctx) => {
+            const parts = String(args || '').trim().toLowerCase().split(/\s+/).filter(Boolean);
+            const [sub, rest] = [parts[0], parts.slice(1).join(' ')];
+            appendUsage('command', `/tersio ${parts.join(' ')}`.trim());
+            if (!sub || sub === 'status') {
+                if (ctx?.hasUI)
+                    reconcileSharedComboEntries(sessionEntries(ctx));
+                ctx?.ui?.notify?.(statusLine(), 'info');
+                return;
+            }
+            if (sub === 'help') {
+                ctx?.ui?.notify?.(HELP, 'info');
+                return;
+            }
+            if (sub === 'caveman') {
+                const mode = normalizeMode('caveman', rest);
+                if (!mode) {
+                    ctx?.ui?.notify?.('Usage: /tersio caveman [lite|full|ultra|wenyan|off|status]', 'warning');
+                    return;
+                }
+                pi.appendEntry?.('caveman-mode', { mode });
+                setSharedComboMode('caveman', mode);
+                appendUsage('toggle', `caveman=${mode}`);
+                ctx?.ui?.notify?.(`Caveman ${mode} on — Active: ${activeModesSummary(getSharedComboState())}.`, 'info');
+                await reload(ctx);
+                return;
+            }
+            if (sub === 'rtk') {
+                if (!rest || rest === 'status') {
+                    const on = getSharedComboState().rtk === 'on';
+                    ctx?.ui?.notify?.(`RTK: ${on ? 'on' : 'off'}`, 'info');
+                    return;
+                }
+                if (!['on', 'off'].includes(rest)) {
+                    ctx?.ui?.notify?.('Usage: /tersio rtk [on|off|status]', 'warning');
+                    return;
+                }
+                const enabled = rest === 'on';
+                pi.appendEntry?.('rtk-mode', { enabled });
+                setSharedComboMode('rtk', enabled);
+                appendUsage('toggle', `rtk=${rest}`);
+                ctx?.ui?.notify?.(`RTK ${rest} — Active: ${activeModesSummary(getSharedComboState())}.`, 'info');
+                await reload(ctx);
+                return;
+            }
+            if (sub === 'ponytail') {
+                const mode = normalizeMode('ponytail', rest);
+                if (!mode) {
+                    ctx?.ui?.notify?.('Usage: /tersio ponytail [off|lite|full|ultra|review|status]', 'warning');
+                    return;
+                }
+                pi.appendEntry?.('ponytail-mode', { mode });
+                setSharedComboMode('ponytail', mode);
+                appendUsage('toggle', `ponytail=${mode}`);
+                ctx?.ui?.notify?.(`Ponytail ${mode} — Active: ${activeModesSummary(getSharedComboState())}.`, 'info');
+                await reload(ctx);
+                return;
+            }
+            if (sub === 'combo') {
+                if (!rest || rest === 'status') {
+                    if (ctx?.hasUI)
+                        reconcileSharedComboEntries(sessionEntries(ctx));
+                    ctx?.ui?.notify?.(statusLine(), 'info');
+                    return;
+                }
+                const level = normalizeComboLevel(rest);
+                if (!level) {
+                    ctx?.ui?.notify?.('Unknown combo level. Use: off | medium | balanced | max', 'warning');
+                    return;
+                }
+                const modes = COMBO_LEVELS[level];
+                pi.appendEntry?.('caveman-mode', { mode: modes.caveman });
+                pi.appendEntry?.('rtk-mode', { enabled: modes.rtk === 'on' });
+                pi.appendEntry?.('ponytail-mode', { mode: modes.ponytail });
+                pi.appendEntry?.('combo-level', { level });
+                setSharedComboLevel(level);
+                appendUsage('toggle', `combo=${level}`);
+                ctx?.ui?.notify?.(`Combo ${level} on — ${activeModesSummary(getSharedComboState())} active for this session.`, 'info');
+                await reload(ctx);
+                return;
+            }
+            if (sub === 'check') {
+                await checkAddonsSummary(ctx);
+                return;
+            }
+            if (sub === 'update') {
+                const dryRun = parts.includes('--dry-run');
+                const target = parts.filter((p) => p !== '--dry-run' && p !== 'update' && p !== 'tersio').join(' ');
+                if (!target) {
+                    ctx?.ui?.notify?.('Usage: /tersio update <ponytail|rtk|caveman|all> [--dry-run]', 'warning');
+                    return;
+                }
+                await runAddonUpdate(pi, ctx, target, dryRun);
+                return;
+            }
+            if (sub === 'gain' || sub === 'usage') {
+                ctx?.ui?.notify?.(`${usageSummary()}\nFull dashboard: run \`tersio dashboard --open\` in a shell.`, 'info');
+                return;
+            }
+            ctx?.ui?.notify?.(`Unknown subcommand: ${sub}.\n${HELP}`, 'warning');
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krtclcdy/tersio",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "✂️ Token-saving OMP add-ons: terse Caveman replies, compact RTK shell output, lean Ponytail code calls — one-command combo presets.",
   "keywords": [
     "omp",
@@ -60,6 +60,13 @@
         "extensions": [
           "./extensions/ai-addons-updater/index.js"
         ]
+      },
+      "tersio": {
+        "description": "Unified /tersio root command (caveman, combo, rtk, ponytail, status, check, update, gain, usage)",
+        "default": true,
+        "extensions": [
+          "./extensions/tersio-commands/index.js"
+        ]
       }
     },
     "settings": {
@@ -108,6 +115,8 @@
   "files": [
     "tersio.js",
     "cli/**/*.js",
+    "cli/dashboard.html",
+    "cli/brand.webp",
     "extensions/**/*.js"
   ],
   "scripts": {

package/tersio.js

@@ -2,12 +2,14 @@
 // tersio.ts — Install Tersio (caveman/rtk/ponytail) add-ons on any OMP device.
 // Usage: node tersio.js [install|update|reinstall|doctor|uninstall|version|help] [options]
 // Requires: node/npm and omp CLI
-import { PACKAGE_BIN, PACKAGE_VERSION, applyUpdate, commandArg, doctor, showHelp, showVersion, uninstall, unknownCommand, update, } from './cli/common.js';
+import { PACKAGE_BIN, PACKAGE_VERSION, applyUpdate, commandArg, dashboard, dashboardExport, dashboardOpen, dashboardPort, doctor, showHelp, showVersion, uninstall, unknownCommand, update, usage, } from './cli/common.js';
 import { closeRL } from './cli/interactive.js';
 import { runInstall } from './cli/install.js';
 import { runDoctor } from './cli/doctor.js';
 import { runLatestUpdate } from './cli/update.js';
 import { runUninstall } from './cli/uninstall.js';
+import { runUsage } from './cli/usage.js';
+import { runDashboard } from './cli/dashboard.js';
 function printHelp() {
     console.log(`Usage: ${PACKAGE_BIN} [command] [options]
 
@@ -16,6 +18,8 @@ Commands:
   update       Refresh the CLI and add-ons (RTK binary, Caveman rule, Ponytail)
   reinstall    Clean and reinstall the user-scope add-ons
   doctor       Check the current installation
+  usage        Ledger-backed usage + savings report
+  dashboard    Serve the gain dashboard (localhost only)
   uninstall    Remove the managed extensions
   version      Print the package version
   help         Show this help
@@ -31,6 +35,9 @@ Options:
   --yes, -y
   --dry-run
   --verbose
+  --port <n> (dashboard: pin port, default ephemeral)
+  --open (dashboard: open browser)
+  --export <file> (dashboard: write HTML file instead of serving)
   --version, -v
   --help, -h`);
 }
@@ -62,6 +69,16 @@ async function main() {
         closeRL();
         return;
     }
+    if (usage) {
+        await runUsage();
+        closeRL();
+        return;
+    }
+    if (dashboard) {
+        await runDashboard({ port: dashboardPort, open: dashboardOpen, exportFile: dashboardExport });
+        closeRL();
+        return;
+    }
     if (uninstall) {
         await runUninstall();
         closeRL();