tokentrace 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.21.0] - 2026-06-26
+
+### Added
+
+- **Local agent preflight.** Added `tokentrace preflight --json` and MCP
+  `get_preflight`, a read-only readiness report that returns proceed, caution,
+  or blocked before another coding-agent run. It combines scan freshness, data
+  confidence, guardrails, anomaly signals, findings, next actions, and privacy
+  notes without scanning files or inspecting raw prompts.
+
+### Changed
+
+- **Simpler dashboard shell.** Primary navigation now follows the daily loop:
+  Today, Sessions, Evidence, Fix Data, Reports, and Settings. Diagnostic
+  surfaces such as Tools, Models, Projects, Query, Scan Health, Discovery,
+  Parsers, Raw Data, and Model Rates remain available under Advanced.
+
+### Fixed
+
+- **First-run scan state uses latest scan evidence.** The Today first-run panel
+  now distinguishes "scan ran but imported no usage" from "no scan has run,"
+  preserving zero-import explanations from Scan Health.
+
 ## [0.20.0] - 2026-06-12
 
 ### Changed

package/README.md

@@ -45,6 +45,8 @@ tokentrace mcp          # Start the local stdio MCP server
 tokentrace scan         # Scan local AI CLI usage logs
 tokentrace doctor --json
                         # Inspect scan health and repair recommendations
+tokentrace preflight --json
+                        # Check readiness before another coding-agent run
 tokentrace evidence --json
                         # Print metric evidence trails as JSON
 tokentrace repair --json
@@ -126,11 +128,22 @@ tokentrace mcp selftest --json
 ```
 
 The MCP server exposes the same local-first surfaces as tools: capabilities,
-status, Scan Health, evidence, repair queue, reports, and an explicit scan tool.
-It does not scan files on startup, and its scan tool requires
+preflight, status, Scan Health, evidence, repair queue, reports, and an
+explicit scan tool. It does not scan files on startup, and its scan tool requires
 `confirmLocalScan=true` before reading local usage files or writing the local
 database.
 
+Before starting another long coding-agent run, use the read-only preflight
+surface:
+
+```bash
+tokentrace preflight --json
+```
+
+In MCP clients, call `get_preflight` for the same proceed, caution, or blocked
+decision with local scan freshness, confidence, guardrail, anomaly, and repair
+findings. Preflight does not scan files or inspect raw prompts.
+
 When the local dashboard is already running, agents can fetch the same manifest
 over localhost:
 
@@ -216,7 +229,7 @@ TokenTrace labels the trust level behind imported numbers:
 - source-provided costs from local SQLite histories
 - unknown cost repair groups when model, token, or rate evidence is missing
 
-The dashboard surfaces a Data Confidence score on Overview, Projects, Sessions,
+The dashboard surfaces a Data Confidence score on Today, Projects, Sessions,
 and Session Timeline pages. Scan Health also includes a supply-chain IOC check
 so package trust is visible in the product, not only in release scripts.
 

package/TOKENTRACE_AGENT.md

@@ -44,6 +44,16 @@ The MCP server does not scan on startup. Its `run_scan` tool requires
 `confirmLocalScan=true` before reading local usage files or writing the local
 database.
 
+Before starting another long coding-agent run, use the read-only preflight:
+
+```bash
+tokentrace preflight --json
+```
+
+The matching MCP tool is `get_preflight`. It returns a proceed, caution, or
+blocked decision with local scan freshness, data confidence, guardrail status,
+anomaly signals, findings, and next actions. It does not scan files.
+
 Private ChatGPT developer-mode prototype:
 
 ```bash
@@ -85,19 +95,25 @@ curl http://127.0.0.1:3030/api/roadmap
    get_agent_guide
    ```
 
-3. Refresh local data when the human expects current usage:
+3. Check whether local evidence is ready for the next agent run:
+
+   ```bash
+   tokentrace preflight --json
+   ```
+
+4. Refresh local data when the human expects current usage:
 
    ```bash
    tokentrace scan --json
    ```
 
-4. Check trust before making claims:
+5. Check trust before making claims:
 
    ```bash
    tokentrace doctor --json
    ```
 
-5. Explain totals with evidence:
+6. Explain totals with evidence:
 
    ```bash
    tokentrace evidence --json
@@ -128,8 +144,8 @@ Get deterministic classification suggestions for the unknown-cost queue:
 tokentrace repair auto-classify --json [--min-confidence=N]
 ```
 
-The matching MCP tools are `get_anomalies`, `query_usage`, and
-`get_classifications`. All three are read-only and require no
+The matching MCP tools are `get_preflight`, `get_anomalies`, `query_usage`, and
+`get_classifications`. All four are read-only and require no
 `confirmLocalScan` acknowledgement.
 
 ## Guardrails

package/app/evidence/evidence-context-panel.tsx

@@ -16,7 +16,7 @@ export function EvidenceContextPanel({ actions }: { actions: EvidenceContextActi
         <div className="max-w-[72ch]">
           <FieldLabel>Evidence path</FieldLabel>
           <p className="mt-1 text-sm leading-6 text-muted-foreground">
-            Evidence is a contextual drill-down from Overview, Sessions, Repair, and exported packs. If you opened this page directly, start with processed tokens, then pivot by metric or follow the next action that matches what looks incomplete.
+            Evidence is a contextual drill-down from Today, Sessions, Fix Data, and exported packs. If you opened this page directly, start with processed tokens, then pivot by metric or follow the next action that matches what looks incomplete.
           </p>
         </div>
         <div className="grid min-w-0 gap-2 sm:grid-cols-2 xl:grid-cols-4">

package/app/guide/guide-content.ts

@@ -13,8 +13,8 @@ export const guideNav = [
 export const dailyLoop = [
   {
     title: "Read the pulse",
-    page: "Overview",
-    detail: "Check current period usage, cost, sessions, unknown cost, and the latest trend window before chasing details.",
+    page: "Today",
+    detail: "Check readiness, usage, cost, sessions, unknown cost, and the latest trend window before chasing details.",
     href: "/",
     icon: Gauge
   },
@@ -27,7 +27,7 @@ export const dailyLoop = [
   },
   {
     title: "Repair what blocks trust",
-    page: "Repair",
+    page: "Fix Data",
     detail: "Unknown cost usually needs a known model name, nonzero tokens, or an editable provider model rate.",
     href: "/repair",
     icon: Wrench
@@ -86,8 +86,11 @@ export const mcpAgentEntries = [
 ];
 
 export const pageMap = [
-  ["Overview", "Top-level totals, trends, repair queue, guardrails, and recommended next actions."],
+  ["Today", "Top-level readiness, totals, trends, repair queue, guardrails, and recommended next actions."],
   ["Sessions", "Per-session evidence with models, costs, cache activity, parser provenance, and tool calls."],
+  ["Evidence", "Trace a metric back to sessions, source files, confidence drivers, and model-rate state."],
+  ["Fix Data", "Repair unknown cost, missing model names, missing token counts, and trust blockers."],
+  ["Reports", "Reusable local reports for weekly usage, high-cost sessions, confidence trends, and source coverage."],
   ["Model Rates", "Editable provider model rates used for dashboard cost estimates and unknown-cost repair."],
   ["Scan Health", "First-run checklist, scan health, supply-chain IOC check, supported file types, and diagnostics for missing data."],
   ["Discovery", "Recently scanned files grouped by parser, source family, status, and import yield."],
@@ -97,7 +100,7 @@ export const pageMap = [
 export const emptyStatePlaybook = [
   ["No data", "Run Scan now from Settings, then use Scan Health if records stay at zero."],
   ["No logs found", "Add a custom folder or use Claude Code, Codex, or another supported CLI before scanning again."],
-  ["Unknown cost", "Open repair or Model Rates to decide whether the missing piece is model name, token count, or provider rate."],
+  ["Unknown cost", "Open Fix Data or Model Rates to decide whether the missing piece is model name, token count, or provider rate."],
   ["Parser warnings", "Open Discovery and Parsers to separate unsupported files from imported-with-errors rows."],
   ["Sandbox smoke skipped", "Local sandbox runs can skip server binding checks. Run the packed smoke or release check outside that constraint before release."]
 ];

package/app/guide/page.tsx

@@ -55,7 +55,7 @@ const firstRunSteps: FirstRunStep[] = [
     number: "5",
     title: "Inspect evidence",
     page: "Sessions",
-    detail: "Use Sessions, Evidence, Repair, and Projects after the first useful import.",
+    detail: "Use Sessions, Evidence, Fix Data, and Projects after the first useful import.",
     href: "/sessions",
     action: "Open Sessions"
   }
@@ -69,12 +69,12 @@ const workflows: GuideWorkflow[] = [
   },
   {
     problem: "Unknown cost",
-    path: "Repair, Model Rates, Evidence",
+    path: "Fix Data, Model Rates, Evidence",
     action: "Find whether the missing piece is model name, token count, or editable provider rate."
   },
   {
     problem: "High token usage",
-    path: "Overview, Sessions, Projects",
+    path: "Today, Sessions, Projects",
     action: "Compare processed, non-cache, and cache totals before treating a spike as fresh context growth."
   },
   {
@@ -111,7 +111,7 @@ export default function GuidePage() {
     {
       label: "Unknown cost",
       value: `${unknownCosts.toLocaleString()} unknown costs`,
-      detail: unknownCosts > 0 ? "Open repair or Model Rates." : "Cost coverage is clear.",
+      detail: unknownCosts > 0 ? "Open Fix Data or Model Rates." : "Cost coverage is clear.",
       ok: unknownCosts === 0
     },
     {

package/app/page.tsx

@@ -142,8 +142,8 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
   return (
     <div className="overview-workbench space-y-7">
       <PageHeader
-        title="Overview"
-        description="Local token, cost, model, and session analytics across AI CLI tools."
+        title="Today"
+        description="Local readiness, cost, token, session, and repair signals before the next AI CLI run."
         actions={
           <Button asChild>
             <Link href="/settings#scan-controls">

package/app/repair/page.tsx

@@ -22,8 +22,8 @@ export default async function RepairPage({ searchParams }: RepairPageProps) {
   return (
     <div className="space-y-6">
       <PageHeader
-        title="Unknown Cost Repair"
-        description="Grouped local evidence for interactions that could not be priced."
+        title="Fix Data"
+        description="Grouped local evidence for interactions that could not be priced or trusted yet."
         actions={
           <div className="flex flex-wrap gap-2">
             <Button asChild variant="outline">

package/components/sidebar.tsx

@@ -11,6 +11,8 @@ import {
   ChevronDown,
   ClipboardList,
   Database,
+  FileSearch,
+  FileText,
   FolderGit2,
   Gauge,
   Menu,
@@ -25,39 +27,45 @@ import { TokenTraceLogo } from "@/components/token-trace-logo";
 import { formatAppVersion, getAppVersion } from "@/src/lib/app-version";
 import { cn } from "@/src/lib/utils";
 
-const overviewNavItem = { href: "/", label: "Overview", icon: Gauge };
+const todayNavItem = { href: "/", label: "Today", icon: Gauge };
+const sessionsNavItem = { href: "/sessions", label: "Sessions", icon: Search };
+const evidenceNavItem = { href: "/evidence", label: "Evidence", icon: FileSearch };
+const repairNavItem = { href: "/repair", label: "Fix Data", icon: Wrench };
+const reportsNavItem = { href: "/reports", label: "Reports", icon: FileText };
+const settingsNavItem = { href: "/settings", label: "Settings", icon: Settings };
 const toolsNavItem = { href: "/tools", label: "Tools", icon: Terminal };
 const modelsNavItem = { href: "/models", label: "Models", icon: Bot };
 const projectsNavItem = { href: "/projects", label: "Projects", icon: FolderGit2 };
-const sessionsNavItem = { href: "/sessions", label: "Sessions", icon: Search };
 const insightsNavItem = { href: "/optimisation", label: "Insights", icon: Sparkles };
 const queryNavItem = { href: "/query", label: "Query", icon: Database };
-const repairNavItem = { href: "/repair", label: "Repair", icon: Wrench };
 const pricingNavItem = { href: "/pricing", label: "Model Rates", icon: SlidersHorizontal };
 const diagnosticsNavItem = { href: "/diagnostics", label: "Scan Health", icon: ClipboardList };
 const discoveryNavItem = { href: "/discovery", label: "Discovery", icon: BarChart3 };
 const parsersNavItem = { href: "/parser-debug", label: "Parsers", icon: Bug };
 const rawDataNavItem = { href: "/debug", label: "Raw Data", icon: Bug };
-const settingsNavItem = { href: "/settings", label: "Settings", icon: Settings };
 
 const navSections = [
   {
-    label: "Analyze",
-    items: [overviewNavItem, toolsNavItem, modelsNavItem, projectsNavItem]
+    label: "Daily loop",
+    items: [todayNavItem, sessionsNavItem, evidenceNavItem, repairNavItem]
   },
   {
-    label: "Investigate",
-    items: [sessionsNavItem, insightsNavItem, queryNavItem, repairNavItem]
+    label: "Operate",
+    items: [reportsNavItem, settingsNavItem]
   },
   {
-    label: "Maintain",
+    label: "Advanced",
     items: [
-      pricingNavItem,
+      toolsNavItem,
+      modelsNavItem,
+      projectsNavItem,
+      insightsNavItem,
+      queryNavItem,
       diagnosticsNavItem,
       discoveryNavItem,
       parsersNavItem,
       rawDataNavItem,
-      settingsNavItem
+      pricingNavItem
     ]
   }
 ];
@@ -73,7 +81,7 @@ const sidebarSections = [
 ];
 
 const priorityMobileItems = primaryNavItems.filter((item) =>
-  ["/", "/sessions", "/repair", "/diagnostics", "/settings"].includes(item.href)
+  ["/", "/sessions", "/evidence", "/repair", "/settings"].includes(item.href)
 );
 
 function NavLink({
@@ -213,7 +221,7 @@ export function MobileNav() {
   const mobileNavItems = [...primaryNavItems, ...supportNavItems];
   const pathname = usePathname() ?? "/";
   const activeMobileItem =
-    mobileNavItems.find((item) => isActiveRoute(pathname, item.href)) ?? overviewNavItem;
+    mobileNavItems.find((item) => isActiveRoute(pathname, item.href)) ?? todayNavItem;
   const ActiveIcon = activeMobileItem.icon;
 
   return (

package/dist/cli/main.mjs

@@ -88,6 +88,8 @@ Usage:
   tokentrace scan         Scan local AI CLI usage logs
   tokentrace doctor --json
                           Inspect scan health and repair recommendations
+  tokentrace preflight --json
+                          Check whether local evidence is ready before another agent run
   tokentrace evidence --json
                           Print metric evidence trail as JSON
   tokentrace digest --json
@@ -117,6 +119,7 @@ Usage:
 Examples:
   tokentrace serve --port 3210 --no-open
   tokentrace scan --json
+  tokentrace preflight --json
   tokentrace doctor --json`;
 }
 function serveHelp() {
@@ -469,6 +472,11 @@ async function doctor(context, args) {
   await initializeDatabase(context, { quiet: true, refreshPrices: false });
   await runNodeScript(context, "doctor", args);
 }
+async function preflight(context, args) {
+  if (await printScriptHelp(context, "preflight", args)) return;
+  await initializeDatabase(context, { quiet: true, refreshPrices: false });
+  await runNodeScript(context, "preflight", args);
+}
 async function evidence(context, args) {
   if (await printScriptHelp(context, "evidence", args)) return;
   await initializeDatabase(context, { quiet: true, refreshPrices: false });
@@ -669,6 +677,10 @@ async function runCliCommand(context, rawArgs = process.argv.slice(2)) {
     await doctor(context, args);
     return;
   }
+  if (command === "preflight") {
+    await preflight(context, args);
+    return;
+  }
   if (command === "evidence") {
     await evidence(context, args);
     return;

package/dist/runtime/agent.mjs

@@ -1,8 +1,13 @@
 import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -4043,6 +4048,23 @@ var commands = [
       ["tokentrace", "evidence", "--json"]
     ]
   },
+  {
+    id: "preflight",
+    title: "Check readiness before another agent run",
+    command: ["tokentrace", "preflight", "--json"],
+    description: "Return a local-only preflight decision with scan freshness, confidence, guardrails, anomalies, findings, and next actions.",
+    output: "json",
+    mutatesLocalState: false,
+    startsLongRunningProcess: false,
+    requiresNetwork: false,
+    safeForAutomation: true,
+    useWhen: "The agent or human wants to know whether to proceed, repair data, or refresh local usage before another coding-agent session.",
+    followUps: [
+      ["tokentrace", "doctor", "--json"],
+      ["tokentrace", "evidence", "--json"],
+      ["tokentrace", "repair", "--json"]
+    ]
+  },
   {
     id: "evidence",
     title: "Print metric evidence trails",
@@ -4359,6 +4381,16 @@ function buildAgentDiscoveryManifest(options = {}) {
           ["tokentrace", "digest", "--json"]
         ]
       },
+      {
+        id: "agent-preflight",
+        title: "Before starting another agent run",
+        goal: "Check whether local evidence is fresh, trusted, and under guardrails before spending more tokens.",
+        steps: [
+          ["tokentrace", "preflight", "--json"],
+          ["tokentrace", "doctor", "--json"],
+          ["tokentrace", "evidence", "--json"]
+        ]
+      },
       {
         id: "daily-review",
         title: "Daily usage review",

package/dist/runtime/anomalies.mjs

@@ -1,8 +1,13 @@
 import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)

package/dist/runtime/digest.mjs

@@ -1,8 +1,13 @@
 import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)

package/dist/runtime/doctor.mjs

@@ -1,8 +1,13 @@
 import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)

package/dist/runtime/evidence.mjs

@@ -1,8 +1,13 @@
 import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)

package/dist/runtime/insights.mjs

@@ -1,8 +1,13 @@
 import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)