tokentrace 0.20.0 → 0.21.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/README.md +49 -21
  3. package/TOKENTRACE_AGENT.md +29 -5
  4. package/app/evidence/evidence-context-panel.tsx +1 -1
  5. package/app/guide/guide-content.ts +8 -5
  6. package/app/guide/page.tsx +4 -4
  7. package/app/page.tsx +2 -2
  8. package/app/repair/page.tsx +2 -2
  9. package/components/sidebar.tsx +21 -13
  10. package/dist/cli/main.mjs +12 -0
  11. package/dist/runtime/agent.mjs +34 -2
  12. package/dist/runtime/anomalies.mjs +7 -2
  13. package/dist/runtime/digest.mjs +7 -2
  14. package/dist/runtime/doctor.mjs +7 -2
  15. package/dist/runtime/evidence.mjs +7 -2
  16. package/dist/runtime/insights.mjs +7 -2
  17. package/dist/runtime/mcp.mjs +3388 -3015
  18. package/dist/runtime/pricing-refresh.mjs +7 -2
  19. package/dist/runtime/query.mjs +7 -2
  20. package/dist/runtime/repair.mjs +7 -2
  21. package/dist/runtime/report.mjs +7 -2
  22. package/dist/runtime/review.mjs +7 -2
  23. package/dist/runtime/scan.mjs +7 -2
  24. package/dist/runtime/status.mjs +7 -2
  25. package/docs/CHATGPT_APP_RELEASE.md +30 -0
  26. package/docs/agent-adoption.md +27 -10
  27. package/docs/assets/evidence-0.21.0.png +0 -0
  28. package/docs/assets/fix-data-0.21.0.png +0 -0
  29. package/docs/assets/scan-health-0.21.0.png +0 -0
  30. package/docs/assets/today-0.21.0.png +0 -0
  31. package/docs/chatgpt-app/README.md +36 -2
  32. package/docs/chatgpt-app/assets/icon.png +0 -0
  33. package/docs/chatgpt-app/dashboard-fields.json +13 -0
  34. package/docs/chatgpt-app/manual-release-steps.md +28 -3
  35. package/llms.txt +15 -0
  36. package/package.json +1 -1
  37. package/scripts/package-inspect.mjs +1 -1
  38. package/scripts/preflight.ts +26 -0
  39. package/scripts/visual-smoke.mjs +19 -7
  40. package/server.json +2 -2
  41. package/src/cli/commands.ts +10 -0
  42. package/src/cli/help.ts +3 -0
  43. package/src/lib/agent-discovery.ts +28 -0
  44. package/src/lib/first-run-status.ts +3 -3
  45. package/src/lib/mcp/agent-guide.ts +8 -2
  46. package/src/lib/mcp/tools.ts +7 -0
  47. package/src/lib/mcp-server.ts +20 -0
  48. package/src/lib/overview-data.ts +29 -3
  49. package/src/lib/preflight.ts +431 -0
  50. package/docs/chatgpt-app/assets/icon.svg +0 -10
package/CHANGELOG.md CHANGED
@@ -4,6 +4,37 @@ All notable changes to TokenTrace are documented here.
4
4
 
5
5
  ## Unreleased
6
6
 
7
+ ## [0.21.1] - 2026-06-26
8
+
9
+ ### Changed
10
+
11
+ - **README and website handoff now match the simplified product.** Refreshed the
12
+ public docs around preflight, Today, Evidence, Fix Data, and current
13
+ Playwright-captured `0.21.0` dashboard screenshots.
14
+
15
+ ## [0.21.0] - 2026-06-26
16
+
17
+ ### Added
18
+
19
+ - **Local agent preflight.** Added `tokentrace preflight --json` and MCP
20
+ `get_preflight`, a read-only readiness report that returns proceed, caution,
21
+ or blocked before another coding-agent run. It combines scan freshness, data
22
+ confidence, guardrails, anomaly signals, findings, next actions, and privacy
23
+ notes without scanning files or inspecting raw prompts.
24
+
25
+ ### Changed
26
+
27
+ - **Simpler dashboard shell.** Primary navigation now follows the daily loop:
28
+ Today, Sessions, Evidence, Fix Data, Reports, and Settings. Diagnostic
29
+ surfaces such as Tools, Models, Projects, Query, Scan Health, Discovery,
30
+ Parsers, Raw Data, and Model Rates remain available under Advanced.
31
+
32
+ ### Fixed
33
+
34
+ - **First-run scan state uses latest scan evidence.** The Today first-run panel
35
+ now distinguishes "scan ran but imported no usage" from "no scan has run,"
36
+ preserving zero-import explanations from Scan Health.
37
+
7
38
  ## [0.20.0] - 2026-06-12
8
39
 
9
40
  ### Changed
package/README.md CHANGED
@@ -4,13 +4,26 @@
4
4
 
5
5
  # TokenTrace CLI
6
6
 
7
- Local-first AI CLI usage analytics. TokenTrace scans local CLI logs and local usage databases, normalizes token usage, estimates missing counts with confidence labels, and shows cost, model, project, session, repair, and evidence analytics in a browser dashboard.
7
+ Local-first AI CLI usage analytics for developers and coding agents.
8
+
9
+ TokenTrace answers one practical question before the next expensive AI CLI run:
10
+ is your local usage evidence ready to trust? It scans local Claude Code, Codex,
11
+ structured usage logs, and usage-shaped local databases, then labels token and
12
+ cost data as exact, estimated, unknown, cached, or non-cache. The dashboard
13
+ opens on **Today**, with direct paths into Sessions, Evidence, and Fix Data.
8
14
 
9
15
  TokenTrace is designed for local development machines first, with macOS-oriented defaults. It does not require a cloud account and does not send telemetry or logs anywhere.
10
16
 
11
17
  [Website](https://www.baseframelabs.com/apps/tokentrace) · [Source](https://github.com/abhiyoheswaran1/tokentrace)
12
18
 
13
- ![TokenTrace overview dashboard](docs/assets/overview-0.12.0.png)
19
+ ![TokenTrace Today dashboard](docs/assets/today-0.21.0.png)
20
+
21
+ ## What TokenTrace Helps You Do
22
+
23
+ - Check readiness before another coding-agent run with `tokentrace preflight --json` or MCP `get_preflight`.
24
+ - See today’s local cost, tokens, sessions, confidence, anomalies, and repair signals in one first screen.
25
+ - Trace every important number back to local files, parser state, sessions, model rates, and confidence labels.
26
+ - Fix missing cost data through a guided repair queue without uploading prompts or message bodies.
14
27
 
15
28
  ## Start In Seconds
16
29
 
@@ -45,6 +58,8 @@ tokentrace mcp # Start the local stdio MCP server
45
58
  tokentrace scan # Scan local AI CLI usage logs
46
59
  tokentrace doctor --json
47
60
  # Inspect scan health and repair recommendations
61
+ tokentrace preflight --json
62
+ # Check readiness before another coding-agent run
48
63
  tokentrace evidence --json
49
64
  # Print metric evidence trails as JSON
50
65
  tokentrace repair --json
@@ -126,11 +141,21 @@ tokentrace mcp selftest --json
126
141
  ```
127
142
 
128
143
  The MCP server exposes the same local-first surfaces as tools: capabilities,
129
- status, Scan Health, evidence, repair queue, reports, and an explicit scan tool.
130
- It does not scan files on startup, and its scan tool requires
144
+ preflight, status, Scan Health, evidence, repair queue, reports, and an
145
+ explicit scan tool. It does not scan files on startup, and its scan tool requires
131
146
  `confirmLocalScan=true` before reading local usage files or writing the local
132
147
  database.
133
148
 
149
+ Before starting another long coding-agent run, use preflight:
150
+
151
+ ```bash
152
+ tokentrace preflight --json
153
+ ```
154
+
155
+ In MCP clients, call `get_preflight` for the same proceed, caution, or blocked
156
+ decision with local scan freshness, confidence, guardrail, anomaly, and repair
157
+ findings. Preflight does not scan files or inspect raw prompts.
158
+
134
159
  When the local dashboard is already running, agents can fetch the same manifest
135
160
  over localhost:
136
161
 
@@ -182,13 +207,17 @@ tokentrace roadmap --json
182
207
  # Inspect roadmap handoff, action recipes, and release status
183
208
  ```
184
209
 
185
- ## Local Sources And Trust
210
+ ## Daily Loop And Trust
186
211
 
187
- TokenTrace 0.12.0 bundles local source expansion, evidence exports, scan
188
- scheduling, scoped guardrails, parser profile preview, saved reports, and
189
- agent-readable release status.
212
+ TokenTrace now organizes the product around the daily loop:
190
213
 
191
- New trust surfaces include:
214
+ 1. **Preflight**: decide whether local evidence is ready before another agent run.
215
+ 2. **Today**: review cost, token, session, confidence, anomaly, and repair signals.
216
+ 3. **Evidence**: trace numbers back to source files, parser confidence, sessions, and model-rate state.
217
+ 4. **Fix Data**: resolve unknown cost, parser review, and model-rate gaps.
218
+ 5. **Advanced**: inspect Scan Health, Discovery, Parsers, Raw Data, Query, and Model Rates when you need the full diagnostic surface.
219
+
220
+ Trust surfaces include:
192
221
 
193
222
  - native structured usage log and Cursor-style chat export ingestion
194
223
  - Source Coverage in Scan Health for native, profile-assisted, fallback, and
@@ -201,11 +230,6 @@ New trust surfaces include:
201
230
  cost, high-cost sessions, and confidence trends
202
231
  - operating metadata export without raw usage records
203
232
 
204
- The 0.12.0 dashboard also tightens the daily operator path: setup buttons now
205
- open the exact Settings section, scan results show what changed and where to go
206
- next, and Evidence explains when it is being opened as a contextual drill-down
207
- rather than a sidebar destination.
208
-
209
233
  ## Accuracy And Evidence
210
234
 
211
235
  TokenTrace labels the trust level behind imported numbers:
@@ -216,7 +240,7 @@ TokenTrace labels the trust level behind imported numbers:
216
240
  - source-provided costs from local SQLite histories
217
241
  - unknown cost repair groups when model, token, or rate evidence is missing
218
242
 
219
- The dashboard surfaces a Data Confidence score on Overview, Projects, Sessions,
243
+ The dashboard surfaces a Data Confidence score on Today, Projects, Sessions,
220
244
  and Session Timeline pages. Scan Health also includes a supply-chain IOC check
221
245
  so package trust is visible in the product, not only in release scripts.
222
246
 
@@ -257,10 +281,13 @@ Default discovery checks these locations when present:
257
281
  - TokenTrace wrapper logs in the local app-data directory
258
282
  - Any custom folders configured in Settings
259
283
 
260
- Use **Settings** in the dashboard to add custom folders, toggle raw message storage, and trigger scans. Use **Scan Health**, **Discovery**, **Parsers**, and **Raw Data** to inspect discovered files, parser decisions, warnings, failures, extracted metadata, and confidence levels.
284
+ Use **Settings** to add custom folders, toggle raw message storage, and trigger
285
+ scans. Use **Scan Health**, **Discovery**, **Parsers**, and **Raw Data** to
286
+ inspect discovered files, parser decisions, warnings, failures, extracted
287
+ metadata, and confidence levels.
261
288
 
262
289
  Settings also supports optional local monthly usage guardrails. Set a cost
263
- limit, token limit, or both, and Overview will show month-to-date progress from
290
+ limit, token limit, or both, and Today will show month-to-date progress from
264
291
  imported local CLI usage.
265
292
 
266
293
  Sessions includes built-in and local saved views for recurring review paths:
@@ -349,13 +376,13 @@ Codex CLI status-line integration is intentionally deferred until its status-lin
349
376
 
350
377
  Dashboard views:
351
378
 
352
- ![TokenTrace overview dashboard](docs/assets/overview-0.12.0.png)
379
+ ![TokenTrace Today dashboard](docs/assets/today-0.21.0.png)
353
380
 
354
- ![TokenTrace processed tokens evidence trail](docs/assets/evidence-0.12.0.png)
381
+ ![TokenTrace unknown cost evidence trail](docs/assets/evidence-0.21.0.png)
355
382
 
356
- ![TokenTrace unknown cost repair queue](docs/assets/repair-0.12.0.png)
383
+ ![TokenTrace Fix Data queue](docs/assets/fix-data-0.21.0.png)
357
384
 
358
- ![TokenTrace Scan Health parser review](docs/assets/scan-health-0.12.0.png)
385
+ ![TokenTrace Scan Health parser review](docs/assets/scan-health-0.21.0.png)
359
386
 
360
387
  CLI startup and help:
361
388
 
@@ -390,6 +417,7 @@ Stop the server with `Ctrl+C` in the terminal where `tokentrace` is running.
390
417
  - `npm run security:ioc` scans lockfiles, workflows, and local Claude/VS Code hook files for high-signal supply-chain compromise indicators.
391
418
  - Public npm publishing is configured through GitHub Actions Trusted Publishing and provenance from version tags.
392
419
  - Socket GitHub checks and ProjScan are used as release guardrails, alongside `npm audit --audit-level=moderate`.
420
+ - `npm run release:check` fails when a gate command exits non-zero. ProjScan warning-level architecture findings, such as circular imports, are reported as release risk and tracked as architecture debt; they do not fail the release unless ProjScan exits non-zero.
393
421
  - Release notes are published directly in GitHub Releases from the relevant changelog section, not as a link-only summary.
394
422
 
395
423
  See [SECURITY.md](SECURITY.md) for the full security and privacy model.
@@ -3,6 +3,11 @@
3
3
  TokenTrace is a local-first CLI and dashboard for AI coding-agent token, cost,
4
4
  session, parser, and evidence analytics.
5
5
 
6
+ The current product loop is: run preflight, review Today, inspect Sessions or
7
+ Evidence, then use Fix Data when model rates or parser confidence block trusted
8
+ costs. Advanced pages remain available for diagnostics, but agents should start
9
+ from preflight before long runs.
10
+
6
11
  ## Start Here
7
12
 
8
13
  Use the read-only discovery manifest before running any other TokenTrace command:
@@ -44,6 +49,16 @@ The MCP server does not scan on startup. Its `run_scan` tool requires
44
49
  `confirmLocalScan=true` before reading local usage files or writing the local
45
50
  database.
46
51
 
52
+ Before starting another long coding-agent run, use the read-only preflight:
53
+
54
+ ```bash
55
+ tokentrace preflight --json
56
+ ```
57
+
58
+ The matching MCP tool is `get_preflight`. It returns a proceed, caution, or
59
+ blocked decision with local scan freshness, data confidence, guardrail status,
60
+ anomaly signals, findings, and next actions. It does not scan files.
61
+
47
62
  Private ChatGPT developer-mode prototype:
48
63
 
49
64
  ```bash
@@ -85,19 +100,28 @@ curl http://127.0.0.1:3030/api/roadmap
85
100
  get_agent_guide
86
101
  ```
87
102
 
88
- 3. Refresh local data when the human expects current usage:
103
+ 3. Check whether local evidence is ready for the next agent run:
104
+
105
+ ```bash
106
+ tokentrace preflight --json
107
+ ```
108
+
109
+ 4. Follow the preflight decision. Use Today for the human-facing status, Evidence
110
+ for numeric claims, and Fix Data for unknown-cost work.
111
+
112
+ 5. Refresh local data when the human expects current usage:
89
113
 
90
114
  ```bash
91
115
  tokentrace scan --json
92
116
  ```
93
117
 
94
- 4. Check trust before making claims:
118
+ 6. Check trust before making claims:
95
119
 
96
120
  ```bash
97
121
  tokentrace doctor --json
98
122
  ```
99
123
 
100
- 5. Explain totals with evidence:
124
+ 7. Explain totals with evidence:
101
125
 
102
126
  ```bash
103
127
  tokentrace evidence --json
@@ -128,8 +152,8 @@ Get deterministic classification suggestions for the unknown-cost queue:
128
152
  tokentrace repair auto-classify --json [--min-confidence=N]
129
153
  ```
130
154
 
131
- The matching MCP tools are `get_anomalies`, `query_usage`, and
132
- `get_classifications`. All three are read-only and require no
155
+ The matching MCP tools are `get_preflight`, `get_anomalies`, `query_usage`, and
156
+ `get_classifications`. All four are read-only and require no
133
157
  `confirmLocalScan` acknowledgement.
134
158
 
135
159
  ## Guardrails
@@ -16,7 +16,7 @@ export function EvidenceContextPanel({ actions }: { actions: EvidenceContextActi
16
16
  <div className="max-w-[72ch]">
17
17
  <FieldLabel>Evidence path</FieldLabel>
18
18
  <p className="mt-1 text-sm leading-6 text-muted-foreground">
19
- 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.
19
+ 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.
20
20
  </p>
21
21
  </div>
22
22
  <div className="grid min-w-0 gap-2 sm:grid-cols-2 xl:grid-cols-4">
@@ -13,8 +13,8 @@ export const guideNav = [
13
13
  export const dailyLoop = [
14
14
  {
15
15
  title: "Read the pulse",
16
- page: "Overview",
17
- detail: "Check current period usage, cost, sessions, unknown cost, and the latest trend window before chasing details.",
16
+ page: "Today",
17
+ detail: "Check readiness, usage, cost, sessions, unknown cost, and the latest trend window before chasing details.",
18
18
  href: "/",
19
19
  icon: Gauge
20
20
  },
@@ -27,7 +27,7 @@ export const dailyLoop = [
27
27
  },
28
28
  {
29
29
  title: "Repair what blocks trust",
30
- page: "Repair",
30
+ page: "Fix Data",
31
31
  detail: "Unknown cost usually needs a known model name, nonzero tokens, or an editable provider model rate.",
32
32
  href: "/repair",
33
33
  icon: Wrench
@@ -86,8 +86,11 @@ export const mcpAgentEntries = [
86
86
  ];
87
87
 
88
88
  export const pageMap = [
89
- ["Overview", "Top-level totals, trends, repair queue, guardrails, and recommended next actions."],
89
+ ["Today", "Top-level readiness, totals, trends, repair queue, guardrails, and recommended next actions."],
90
90
  ["Sessions", "Per-session evidence with models, costs, cache activity, parser provenance, and tool calls."],
91
+ ["Evidence", "Trace a metric back to sessions, source files, confidence drivers, and model-rate state."],
92
+ ["Fix Data", "Repair unknown cost, missing model names, missing token counts, and trust blockers."],
93
+ ["Reports", "Reusable local reports for weekly usage, high-cost sessions, confidence trends, and source coverage."],
91
94
  ["Model Rates", "Editable provider model rates used for dashboard cost estimates and unknown-cost repair."],
92
95
  ["Scan Health", "First-run checklist, scan health, supply-chain IOC check, supported file types, and diagnostics for missing data."],
93
96
  ["Discovery", "Recently scanned files grouped by parser, source family, status, and import yield."],
@@ -97,7 +100,7 @@ export const pageMap = [
97
100
  export const emptyStatePlaybook = [
98
101
  ["No data", "Run Scan now from Settings, then use Scan Health if records stay at zero."],
99
102
  ["No logs found", "Add a custom folder or use Claude Code, Codex, or another supported CLI before scanning again."],
100
- ["Unknown cost", "Open repair or Model Rates to decide whether the missing piece is model name, token count, or provider rate."],
103
+ ["Unknown cost", "Open Fix Data or Model Rates to decide whether the missing piece is model name, token count, or provider rate."],
101
104
  ["Parser warnings", "Open Discovery and Parsers to separate unsupported files from imported-with-errors rows."],
102
105
  ["Sandbox smoke skipped", "Local sandbox runs can skip server binding checks. Run the packed smoke or release check outside that constraint before release."]
103
106
  ];
@@ -55,7 +55,7 @@ const firstRunSteps: FirstRunStep[] = [
55
55
  number: "5",
56
56
  title: "Inspect evidence",
57
57
  page: "Sessions",
58
- detail: "Use Sessions, Evidence, Repair, and Projects after the first useful import.",
58
+ detail: "Use Sessions, Evidence, Fix Data, and Projects after the first useful import.",
59
59
  href: "/sessions",
60
60
  action: "Open Sessions"
61
61
  }
@@ -69,12 +69,12 @@ const workflows: GuideWorkflow[] = [
69
69
  },
70
70
  {
71
71
  problem: "Unknown cost",
72
- path: "Repair, Model Rates, Evidence",
72
+ path: "Fix Data, Model Rates, Evidence",
73
73
  action: "Find whether the missing piece is model name, token count, or editable provider rate."
74
74
  },
75
75
  {
76
76
  problem: "High token usage",
77
- path: "Overview, Sessions, Projects",
77
+ path: "Today, Sessions, Projects",
78
78
  action: "Compare processed, non-cache, and cache totals before treating a spike as fresh context growth."
79
79
  },
80
80
  {
@@ -111,7 +111,7 @@ export default function GuidePage() {
111
111
  {
112
112
  label: "Unknown cost",
113
113
  value: `${unknownCosts.toLocaleString()} unknown costs`,
114
- detail: unknownCosts > 0 ? "Open repair or Model Rates." : "Cost coverage is clear.",
114
+ detail: unknownCosts > 0 ? "Open Fix Data or Model Rates." : "Cost coverage is clear.",
115
115
  ok: unknownCosts === 0
116
116
  },
117
117
  {
package/app/page.tsx CHANGED
@@ -142,8 +142,8 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
142
142
  return (
143
143
  <div className="overview-workbench space-y-7">
144
144
  <PageHeader
145
- title="Overview"
146
- description="Local token, cost, model, and session analytics across AI CLI tools."
145
+ title="Today"
146
+ description="Local readiness, cost, token, session, and repair signals before the next AI CLI run."
147
147
  actions={
148
148
  <Button asChild>
149
149
  <Link href="/settings#scan-controls">
@@ -22,8 +22,8 @@ export default async function RepairPage({ searchParams }: RepairPageProps) {
22
22
  return (
23
23
  <div className="space-y-6">
24
24
  <PageHeader
25
- title="Unknown Cost Repair"
26
- description="Grouped local evidence for interactions that could not be priced."
25
+ title="Fix Data"
26
+ description="Grouped local evidence for interactions that could not be priced or trusted yet."
27
27
  actions={
28
28
  <div className="flex flex-wrap gap-2">
29
29
  <Button asChild variant="outline">
@@ -11,6 +11,8 @@ import {
11
11
  ChevronDown,
12
12
  ClipboardList,
13
13
  Database,
14
+ FileSearch,
15
+ FileText,
14
16
  FolderGit2,
15
17
  Gauge,
16
18
  Menu,
@@ -25,39 +27,45 @@ import { TokenTraceLogo } from "@/components/token-trace-logo";
25
27
  import { formatAppVersion, getAppVersion } from "@/src/lib/app-version";
26
28
  import { cn } from "@/src/lib/utils";
27
29
 
28
- const overviewNavItem = { href: "/", label: "Overview", icon: Gauge };
30
+ const todayNavItem = { href: "/", label: "Today", icon: Gauge };
31
+ const sessionsNavItem = { href: "/sessions", label: "Sessions", icon: Search };
32
+ const evidenceNavItem = { href: "/evidence", label: "Evidence", icon: FileSearch };
33
+ const repairNavItem = { href: "/repair", label: "Fix Data", icon: Wrench };
34
+ const reportsNavItem = { href: "/reports", label: "Reports", icon: FileText };
35
+ const settingsNavItem = { href: "/settings", label: "Settings", icon: Settings };
29
36
  const toolsNavItem = { href: "/tools", label: "Tools", icon: Terminal };
30
37
  const modelsNavItem = { href: "/models", label: "Models", icon: Bot };
31
38
  const projectsNavItem = { href: "/projects", label: "Projects", icon: FolderGit2 };
32
- const sessionsNavItem = { href: "/sessions", label: "Sessions", icon: Search };
33
39
  const insightsNavItem = { href: "/optimisation", label: "Insights", icon: Sparkles };
34
40
  const queryNavItem = { href: "/query", label: "Query", icon: Database };
35
- const repairNavItem = { href: "/repair", label: "Repair", icon: Wrench };
36
41
  const pricingNavItem = { href: "/pricing", label: "Model Rates", icon: SlidersHorizontal };
37
42
  const diagnosticsNavItem = { href: "/diagnostics", label: "Scan Health", icon: ClipboardList };
38
43
  const discoveryNavItem = { href: "/discovery", label: "Discovery", icon: BarChart3 };
39
44
  const parsersNavItem = { href: "/parser-debug", label: "Parsers", icon: Bug };
40
45
  const rawDataNavItem = { href: "/debug", label: "Raw Data", icon: Bug };
41
- const settingsNavItem = { href: "/settings", label: "Settings", icon: Settings };
42
46
 
43
47
  const navSections = [
44
48
  {
45
- label: "Analyze",
46
- items: [overviewNavItem, toolsNavItem, modelsNavItem, projectsNavItem]
49
+ label: "Daily loop",
50
+ items: [todayNavItem, sessionsNavItem, evidenceNavItem, repairNavItem]
47
51
  },
48
52
  {
49
- label: "Investigate",
50
- items: [sessionsNavItem, insightsNavItem, queryNavItem, repairNavItem]
53
+ label: "Operate",
54
+ items: [reportsNavItem, settingsNavItem]
51
55
  },
52
56
  {
53
- label: "Maintain",
57
+ label: "Advanced",
54
58
  items: [
55
- pricingNavItem,
59
+ toolsNavItem,
60
+ modelsNavItem,
61
+ projectsNavItem,
62
+ insightsNavItem,
63
+ queryNavItem,
56
64
  diagnosticsNavItem,
57
65
  discoveryNavItem,
58
66
  parsersNavItem,
59
67
  rawDataNavItem,
60
- settingsNavItem
68
+ pricingNavItem
61
69
  ]
62
70
  }
63
71
  ];
@@ -73,7 +81,7 @@ const sidebarSections = [
73
81
  ];
74
82
 
75
83
  const priorityMobileItems = primaryNavItems.filter((item) =>
76
- ["/", "/sessions", "/repair", "/diagnostics", "/settings"].includes(item.href)
84
+ ["/", "/sessions", "/evidence", "/repair", "/settings"].includes(item.href)
77
85
  );
78
86
 
79
87
  function NavLink({
@@ -213,7 +221,7 @@ export function MobileNav() {
213
221
  const mobileNavItems = [...primaryNavItems, ...supportNavItems];
214
222
  const pathname = usePathname() ?? "/";
215
223
  const activeMobileItem =
216
- mobileNavItems.find((item) => isActiveRoute(pathname, item.href)) ?? overviewNavItem;
224
+ mobileNavItems.find((item) => isActiveRoute(pathname, item.href)) ?? todayNavItem;
217
225
  const ActiveIcon = activeMobileItem.icon;
218
226
 
219
227
  return (
package/dist/cli/main.mjs CHANGED
@@ -88,6 +88,8 @@ Usage:
88
88
  tokentrace scan Scan local AI CLI usage logs
89
89
  tokentrace doctor --json
90
90
  Inspect scan health and repair recommendations
91
+ tokentrace preflight --json
92
+ Check whether local evidence is ready before another agent run
91
93
  tokentrace evidence --json
92
94
  Print metric evidence trail as JSON
93
95
  tokentrace digest --json
@@ -117,6 +119,7 @@ Usage:
117
119
  Examples:
118
120
  tokentrace serve --port 3210 --no-open
119
121
  tokentrace scan --json
122
+ tokentrace preflight --json
120
123
  tokentrace doctor --json`;
121
124
  }
122
125
  function serveHelp() {
@@ -469,6 +472,11 @@ async function doctor(context, args) {
469
472
  await initializeDatabase(context, { quiet: true, refreshPrices: false });
470
473
  await runNodeScript(context, "doctor", args);
471
474
  }
475
+ async function preflight(context, args) {
476
+ if (await printScriptHelp(context, "preflight", args)) return;
477
+ await initializeDatabase(context, { quiet: true, refreshPrices: false });
478
+ await runNodeScript(context, "preflight", args);
479
+ }
472
480
  async function evidence(context, args) {
473
481
  if (await printScriptHelp(context, "evidence", args)) return;
474
482
  await initializeDatabase(context, { quiet: true, refreshPrices: false });
@@ -669,6 +677,10 @@ async function runCliCommand(context, rawArgs = process.argv.slice(2)) {
669
677
  await doctor(context, args);
670
678
  return;
671
679
  }
680
+ if (command === "preflight") {
681
+ await preflight(context, args);
682
+ return;
683
+ }
672
684
  if (command === "evidence") {
673
685
  await evidence(context, args);
674
686
  return;
@@ -1,8 +1,13 @@
1
1
  import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
2
2
  var __defProp = Object.defineProperty;
3
3
  var __getOwnPropNames = Object.getOwnPropertyNames;
4
- var __esm = (fn, res) => function __init() {
5
- return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
4
+ var __esm = (fn, res, err) => function __init() {
5
+ if (err) throw err[0];
6
+ try {
7
+ return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
8
+ } catch (e) {
9
+ throw err = [e], e;
10
+ }
6
11
  };
7
12
  var __export = (target, all) => {
8
13
  for (var name in all)
@@ -4043,6 +4048,23 @@ var commands = [
4043
4048
  ["tokentrace", "evidence", "--json"]
4044
4049
  ]
4045
4050
  },
4051
+ {
4052
+ id: "preflight",
4053
+ title: "Check readiness before another agent run",
4054
+ command: ["tokentrace", "preflight", "--json"],
4055
+ description: "Return a local-only preflight decision with scan freshness, confidence, guardrails, anomalies, findings, and next actions.",
4056
+ output: "json",
4057
+ mutatesLocalState: false,
4058
+ startsLongRunningProcess: false,
4059
+ requiresNetwork: false,
4060
+ safeForAutomation: true,
4061
+ useWhen: "The agent or human wants to know whether to proceed, repair data, or refresh local usage before another coding-agent session.",
4062
+ followUps: [
4063
+ ["tokentrace", "doctor", "--json"],
4064
+ ["tokentrace", "evidence", "--json"],
4065
+ ["tokentrace", "repair", "--json"]
4066
+ ]
4067
+ },
4046
4068
  {
4047
4069
  id: "evidence",
4048
4070
  title: "Print metric evidence trails",
@@ -4359,6 +4381,16 @@ function buildAgentDiscoveryManifest(options = {}) {
4359
4381
  ["tokentrace", "digest", "--json"]
4360
4382
  ]
4361
4383
  },
4384
+ {
4385
+ id: "agent-preflight",
4386
+ title: "Before starting another agent run",
4387
+ goal: "Check whether local evidence is fresh, trusted, and under guardrails before spending more tokens.",
4388
+ steps: [
4389
+ ["tokentrace", "preflight", "--json"],
4390
+ ["tokentrace", "doctor", "--json"],
4391
+ ["tokentrace", "evidence", "--json"]
4392
+ ]
4393
+ },
4362
4394
  {
4363
4395
  id: "daily-review",
4364
4396
  title: "Daily usage review",
@@ -1,8 +1,13 @@
1
1
  import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
2
2
  var __defProp = Object.defineProperty;
3
3
  var __getOwnPropNames = Object.getOwnPropertyNames;
4
- var __esm = (fn, res) => function __init() {
5
- return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
4
+ var __esm = (fn, res, err) => function __init() {
5
+ if (err) throw err[0];
6
+ try {
7
+ return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
8
+ } catch (e) {
9
+ throw err = [e], e;
10
+ }
6
11
  };
7
12
  var __export = (target, all) => {
8
13
  for (var name in all)
@@ -1,8 +1,13 @@
1
1
  import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
2
2
  var __defProp = Object.defineProperty;
3
3
  var __getOwnPropNames = Object.getOwnPropertyNames;
4
- var __esm = (fn, res) => function __init() {
5
- return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
4
+ var __esm = (fn, res, err) => function __init() {
5
+ if (err) throw err[0];
6
+ try {
7
+ return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
8
+ } catch (e) {
9
+ throw err = [e], e;
10
+ }
6
11
  };
7
12
  var __export = (target, all) => {
8
13
  for (var name in all)
@@ -1,8 +1,13 @@
1
1
  import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
2
2
  var __defProp = Object.defineProperty;
3
3
  var __getOwnPropNames = Object.getOwnPropertyNames;
4
- var __esm = (fn, res) => function __init() {
5
- return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
4
+ var __esm = (fn, res, err) => function __init() {
5
+ if (err) throw err[0];
6
+ try {
7
+ return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
8
+ } catch (e) {
9
+ throw err = [e], e;
10
+ }
6
11
  };
7
12
  var __export = (target, all) => {
8
13
  for (var name in all)
@@ -1,8 +1,13 @@
1
1
  import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
2
2
  var __defProp = Object.defineProperty;
3
3
  var __getOwnPropNames = Object.getOwnPropertyNames;
4
- var __esm = (fn, res) => function __init() {
5
- return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
4
+ var __esm = (fn, res, err) => function __init() {
5
+ if (err) throw err[0];
6
+ try {
7
+ return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
8
+ } catch (e) {
9
+ throw err = [e], e;
10
+ }
6
11
  };
7
12
  var __export = (target, all) => {
8
13
  for (var name in all)
@@ -1,8 +1,13 @@
1
1
  import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
2
2
  var __defProp = Object.defineProperty;
3
3
  var __getOwnPropNames = Object.getOwnPropertyNames;
4
- var __esm = (fn, res) => function __init() {
5
- return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
4
+ var __esm = (fn, res, err) => function __init() {
5
+ if (err) throw err[0];
6
+ try {
7
+ return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
8
+ } catch (e) {
9
+ throw err = [e], e;
10
+ }
6
11
  };
7
12
  var __export = (target, all) => {
8
13
  for (var name in all)