tokentrace 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+No unreleased changes yet.
+
+## [0.10.1] - 2026-05-18
+
+### Changed
+
+- Guide now uses a manual-style layout with section navigation, compact setup status, workflow rows, command tables, and tighter troubleshooting copy.
+- Sidebar Guide access now lives in a Help area above the version footer so it reads as documentation instead of a product feature.
+- Guide section navigation now sticks while scrolling on desktop widths, and the standalone sidebar Guide link no longer shows redundant Help chrome.
+- Guide Scan now controls now run the local scan directly with inline feedback instead of linking to Settings.
+- Overview now groups processed, fresh, and cached token metrics into one Token Accounting card with direct evidence pivots.
+- Evidence pages now include metric tabs and drill-down actions for source files, sessions, parser confidence, and model-rate or repair follow-up.
+- User-facing model price configuration is now labeled Model Rates so it is not mistaken for TokenTrace product pricing.
+- Overview Usage Pulse now labels current, previous, and change values explicitly inside each metric block.
+- Overview now groups cost and sessions into one split card with a shared help tooltip, compact pane labels, and aligned trust notes/actions.
+- Overview trend charts now default all-time views to the latest 30 days, while keeping 60-day, 90-day, and All history options available.
+- Overview now compacts below-chart diagnostics into Review Status and Top repair items strips, with the full unknown-cost table moved to the Repair page.
+- Evidence, repair, parser, and model-rate links now use consistent action labels: View evidence, Open repair, Set model rate, and Review parser.
+- Sidebar navigation now shows the active page, first-run empty states point to the next useful action, direct scans return richer result feedback, and repair/evidence pages guide users through the next drill-down.
+- Page names now stay aligned around Parsers, Discovery, Insights, Scan Health, Model Rates, and privacy-oriented Raw Data copy.
+- User-facing diagnostic copy now uses Scan Health consistently instead of older mixed diagnostic wording.
+- Product metadata, README, Guide, and agent discovery now point to the TokenTrace product website while creator attribution points to Abhi Yoheswaran's homepage.
+- Period filters use a mobile-friendly preset scroller with custom dates on a compact second row, and trend controls now say Display window with a showing-latest badge.
+- README screenshots were refreshed from a guarded public-safe screenshot database seeded by `npm run screenshots:seed`.
+
 ## [0.10.0] - 2026-05-18
 
 ### Added

package/README.md

@@ -4,11 +4,13 @@
 
 # TokenTrace CLI
 
-Local-first analytics for AI CLI usage. TokenTrace scans local CLI logs, normalizes token usage, estimates missing counts, and shows cost, model, project, and session analytics in a browser dashboard.
+Local-first AI CLI usage analytics. TokenTrace scans local CLI logs, normalizes token usage, estimates missing counts, and shows cost, model, project, and session analytics in a browser dashboard.
 
 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.
 
-![TokenTrace overview dashboard](docs/assets/overview-0.8.0.png)
+[Website](https://www.abhiyoheswaran.com/apps/tokentrace) · [Source](https://github.com/abhiyoheswaran1/tokentrace)
+
+![TokenTrace overview dashboard](docs/assets/overview-0.10.0.png)
 
 ## Start In Seconds
 
@@ -38,7 +40,7 @@ tokentrace agent --json # Print machine-readable agent discovery manifest
 tokentrace capabilities --json
                         # Alias for agent discovery manifest
 tokentrace roadmap --json
-                        # Print 0.10.0 release implementation status
+                        # Print Guided Operator release implementation status
 tokentrace scan         # Scan local AI CLI usage logs
 tokentrace doctor --json
                         # Inspect scan health and repair recommendations
@@ -112,7 +114,7 @@ curl http://127.0.0.1:3030/api/agent
 curl http://127.0.0.1:3030/api/capabilities
 ```
 
-The 0.10.0 release status is also machine-readable:
+The Guided Operator release status is also machine-readable:
 
 ```bash
 tokentrace roadmap --json
@@ -139,6 +141,8 @@ npm run start        # Serve the production build
 npm run scan         # Scan default and configured folders
 npm run db:migrate   # Create/update local SQLite tables
 npm run db:seed      # Seed editable provider/model prices
+npm run screenshots:seed
+                    # Seed a guarded public-safe screenshot database
 npm run reset        # Clear imported data and scan history
 npm test             # Run parser and cost tests
 npm run verify       # Run Vitest, TypeScript, and ESLint checks
@@ -148,7 +152,7 @@ npm run package:inspect
 npm run smoke:packed
                     # Inspect packed tarball and smoke test packed CLI
 tokentrace roadmap --json
-                    # Inspect 0.10.0 evidence gates and release status
+                    # Inspect evidence gates and release status
 ```
 
 Release work uses internal milestone commits until the next public minor
@@ -190,7 +194,7 @@ Default discovery checks these locations when present:
 - TokenTrace wrapper logs in the local app-data directory
 - Any custom folders configured in Settings
 
-Use **Settings** in the dashboard to add custom folders, toggle raw message storage, and trigger scans. Use **Doctor**, **Discovery**, **Parser Debug**, and **Raw Data** to inspect discovered files, parser decisions, warnings, failures, extracted metadata, and confidence levels.
+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.
 
 Settings also supports optional local monthly usage guardrails. Set a cost
 limit, token limit, or both, and Overview will show month-to-date progress from
@@ -280,15 +284,15 @@ Codex CLI status-line integration is intentionally deferred until its status-lin
 
 ## Screenshots
 
-Evidence + Repair views:
+Dashboard views:
 
-![TokenTrace overview dashboard](docs/assets/overview-0.8.0.png)
+![TokenTrace overview dashboard](docs/assets/overview-0.10.0.png)
 
-![TokenTrace processed tokens evidence trail](docs/assets/evidence-0.8.0.png)
+![TokenTrace processed tokens evidence trail](docs/assets/evidence-0.10.0.png)
 
-![TokenTrace unknown cost repair queue](docs/assets/repair-0.8.0.png)
+![TokenTrace unknown cost repair queue](docs/assets/repair-0.10.0.png)
 
-![TokenTrace Scan Doctor parser trust report](docs/assets/doctor-parser-trust-0.8.0.png)
+![TokenTrace Scan Health parser review](docs/assets/scan-health-0.10.0.png)
 
 CLI startup and help:
 
@@ -326,9 +330,9 @@ Stop the server with `Ctrl+C` in the terminal where `tokentrace` is running.
 
 See [SECURITY.md](SECURITY.md) for the full security and privacy model.
 
-## Pricing
+## Model Rates
 
-Model prices change. TokenTrace ships with bundled public list prices and can refresh them from a public TokenTrace pricing manifest. Manual edits made in **Pricing** are preserved by future refreshes.
+Model prices change. TokenTrace ships with bundled public list prices and can refresh them from a public TokenTrace model-rate manifest. Manual edits made in **Model Rates** are preserved by future refreshes.
 
 The bundled catalog includes common OpenAI, Anthropic, Google Gemini, xAI, DeepSeek, Mistral, and Cohere models, checked on May 8, 2026.
 
@@ -342,7 +346,7 @@ Seed sources:
 - [Mistral model docs](https://docs.mistral.ai/models)
 - [Cohere pricing](https://cohere.com/pricing)
 
-Review and update prices in **Pricing** before treating cost estimates as financial truth, especially if you use batch processing, priority/flex modes, data residency, long-context surcharges, subscriptions, or provider-specific discounts.
+Review and update rates in **Model Rates** before treating cost estimates as financial truth, especially if you use batch processing, priority/flex modes, data residency, long-context surcharges, subscriptions, or provider-specific discounts.
 
 Refresh from the dashboard or from the CLI:
 
@@ -411,7 +415,7 @@ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setu
 
 ## License
 
-Open source by [Abhi Yoheswaran](https://github.com/abhiyoheswaran1). Released under the MIT License. See `LICENSE`.
+Open source by [Abhi Yoheswaran](https://www.abhiyoheswaran.com). Released under the MIT License. See `LICENSE`.
 
 ## Next Improvements
 

package/app/debug/page.tsx

@@ -1,4 +1,6 @@
 import { Badge } from "@/components/ui/badge";
+import { EmptyState } from "@/components/empty-state";
+import { ScanNowButton } from "@/components/scan-now-button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
 import { MonoText, PageHeader } from "@/components/ui/typography";
@@ -21,9 +23,26 @@ export default function DebugPage() {
     <div className="space-y-6">
       <PageHeader
         title="Raw Data"
-        description="Inspect recent scan runs, parser selection, imported records, warnings, and failures."
+        description="Local raw data for scan runs, parser selection, imported records, warnings, and failures."
       />
 
+      <div className="rounded-md border bg-card p-3 text-sm leading-6 text-muted-foreground">
+        <span className="font-medium text-foreground">Local raw data:</span>{" "}
+        Treat file paths and parser metadata as local sensitive data. This page is for debugging imports, not sharing screenshots.
+      </div>
+
+      {!data.scanRuns.length && !data.scanFiles.length ? (
+        <EmptyState
+          title="No raw scan data yet"
+          description="Run a scan to populate local raw data. If nothing appears after a scan, open Scan Health to review roots and parser status."
+          actions={[
+            { label: "Open Scan Health", href: "/diagnostics", variant: "outline" }
+          ]}
+        >
+          <ScanNowButton size="sm" />
+        </EmptyState>
+      ) : (
+        <>
       <Card>
         <CardHeader>
           <CardTitle>Recent Scan Runs</CardTitle>
@@ -97,6 +116,8 @@ export default function DebugPage() {
           </Table>
         </CardContent>
       </Card>
+        </>
+      )}
     </div>
   );
 }

package/app/diagnostics/page.tsx

@@ -43,7 +43,7 @@ function TrustChecklist({
   const hasInteractions = data.confidence.interactions > 0;
   const unknownCauses = data.health.costCoverage.unknownCauses;
   const unknownCauseText = [
-    unknownCauses.missingPricing > 0 ? `${unknownCauses.missingPricing.toLocaleString()} missing pricing` : null,
+    unknownCauses.missingPricing > 0 ? `${unknownCauses.missingPricing.toLocaleString()} missing model rate` : null,
     unknownCauses.missingModelName > 0 ? `${unknownCauses.missingModelName.toLocaleString()} missing model` : null,
     unknownCauses.missingTokenCount > 0 ? `${unknownCauses.missingTokenCount.toLocaleString()} missing token count` : null,
     unknownCauses.other > 0 ? `${unknownCauses.other.toLocaleString()} other` : null
@@ -51,11 +51,11 @@ function TrustChecklist({
 
   const items: Array<{ label: string; detail: string; status: ChecklistStatus }> = [
     {
-      label: "Pricing loaded",
+      label: "Model rates loaded",
       status: data.pricedModelCount > 0 ? "pass" : "warn",
       detail: data.pricedModelCount > 0
-        ? `${data.pricedModelCount.toLocaleString()} priced models are available.`
-        : "Seed pricing before trusting cost totals."
+        ? `${data.pricedModelCount.toLocaleString()} rated models are available.`
+        : "Seed model rates before trusting cost totals."
     },
     {
       label: "CLI roots found",
@@ -77,10 +77,10 @@ function TrustChecklist({
       detail: latest ? `${latest.recordsImported.toLocaleString()} interactions imported in the latest scan.` : "No scan has imported records yet."
     },
     {
-      label: "Unknown prices",
+      label: "Unknown cost",
       status: !hasInteractions ? "pending" : data.health.costCoverage.unknown > 0 ? "warn" : "pass",
       detail: !hasInteractions
-        ? "Pricing coverage appears after records are imported."
+        ? "Model-rate coverage appears after records are imported."
         : data.health.costCoverage.unknown > 0
           ? `${data.health.costCoverage.unknown.toLocaleString()} interactions need repair: ${unknownCauseText || "cause unavailable"}.`
           : "Imported interactions have usable cost coverage."
@@ -153,9 +153,9 @@ function DoctorReportPanel({ report }: { report: DoctorReport }) {
   return (
     <Card>
       <CardHeader>
-        <CardTitle>Doctor report</CardTitle>
+        <CardTitle>Scan Health report</CardTitle>
         <CardDescription>
-          A shared report used by this page and `tokentrace doctor --json`.
+          The same local Scan Health data returned by `tokentrace doctor --json`.
         </CardDescription>
       </CardHeader>
       <CardContent className="space-y-4">
@@ -217,7 +217,7 @@ function DoctorReportPanel({ report }: { report: DoctorReport }) {
         </div>
 
         <div className="space-y-2">
-          <div className="text-sm font-semibold">Repair recommendations</div>
+          <div className="text-sm font-semibold">Recommended fixes</div>
           <div className="grid gap-2 lg:grid-cols-2">
             {report.recommendations.slice(0, 6).map((item) => (
               <Link key={item.id} href={item.href ?? "/diagnostics"} className="border-t p-3 transition-colors hover:bg-muted/40">
@@ -236,7 +236,7 @@ function DoctorReportPanel({ report }: { report: DoctorReport }) {
 
         <div className="space-y-3">
           <div>
-            <div className="text-sm font-semibold">Support matrix</div>
+            <div className="text-sm font-semibold">Supported file types</div>
             <div className="mt-1 text-xs text-muted-foreground">
               {report.supportMatrix.summary.stable.toLocaleString()} stable,{" "}
               {report.supportMatrix.summary.bestEffort.toLocaleString()} best-effort,{" "}
@@ -267,7 +267,7 @@ function ParserTrustPanel({ report }: { report: DoctorReport["parserTrust"] }) {
   return (
     <Card>
       <CardHeader>
-        <CardTitle>Parser Trust Report</CardTitle>
+        <CardTitle>File parser review</CardTitle>
         <CardDescription>
           Latest scan files grouped by parser, source family, version, status, and import yield. Ignored files are known support files, not usage transcripts. Unsupported files need parser review before they become usage.
         </CardDescription>
@@ -342,7 +342,7 @@ function ScanDiffPanel({ report }: { report: DoctorReport["scanDiff"] }) {
   return (
     <Card>
       <CardHeader>
-        <CardTitle>Scan History Diff</CardTitle>
+        <CardTitle>Scan history comparison</CardTitle>
         <CardDescription>
           Latest scan compared with the previous scan using deterministic scan ordering. Ignored files are known support files, not usage transcripts.
         </CardDescription>
@@ -472,8 +472,8 @@ export default async function DiagnosticsPage() {
   return (
     <div className="space-y-6">
       <PageHeader
-        title="Scan Doctor"
-        description="Local CLI ingestion status, parser coverage, pricing readiness, and confidence transparency."
+        title="Scan Health"
+        description="Shows whether local usage was imported, which files need review, and whether model-rate coverage is usable."
       />
 
       <TrustChecklist data={data} rootCount={roots.length} />
@@ -481,7 +481,7 @@ export default async function DiagnosticsPage() {
       <Card>
         <CardHeader>
           <CardTitle>Local recommendations</CardTitle>
-          <CardDescription>Deterministic next actions from local scan, pricing, parser, project, and cache data.</CardDescription>
+          <CardDescription>Deterministic next actions from local scan, model rates, parser, project, and cache data.</CardDescription>
         </CardHeader>
         <CardContent className="grid divide-y overflow-hidden p-0 lg:grid-cols-3 lg:divide-x lg:divide-y-0">
           {analytics.recommendations.slice(0, 3).map((item) => (
@@ -513,12 +513,12 @@ export default async function DiagnosticsPage() {
         {[
           {
             href: "/discovery",
-            title: "File Discovery Explorer",
+            title: "Discovered files",
             description: "Inspect which local files were discovered, skipped, imported, or unsupported."
           },
           {
             href: "/parser-debug",
-            title: "Parser Debug",
+            title: "Parser review",
             description: "Review adapter selection, parser confidence, warnings, errors, and extracted metadata."
           },
           {
@@ -543,7 +543,7 @@ export default async function DiagnosticsPage() {
 
       <Card>
         <CardHeader>
-          <CardTitle>Architecture Guardrails</CardTitle>
+          <CardTitle>Local privacy rules</CardTitle>
           <CardDescription>TokenTrace uses direct local filesystem ingestion as the primary architecture.</CardDescription>
         </CardHeader>
         <CardContent className="flex flex-wrap gap-2">

package/app/discovery/page.tsx

@@ -3,6 +3,7 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/com
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
 import { DataValue, FieldLabel, MonoText, PageHeader } from "@/components/ui/typography";
 import { EmptyState } from "@/components/empty-state";
+import { ScanNowButton } from "@/components/scan-now-button";
 import { getScanTrustData } from "@/src/lib/analytics";
 import { formatDate } from "@/src/lib/format";
 
@@ -27,7 +28,7 @@ export default function DiscoveryPage() {
   return (
     <div className="space-y-6">
       <PageHeader
-        title="File Discovery Explorer"
+        title="Discovery"
         description="Every file shown here was discovered by passive local filesystem scanning."
       />
       <div className="grid overflow-hidden rounded-md border bg-card sm:grid-cols-2 lg:grid-cols-5">
@@ -55,8 +56,13 @@ export default function DiscoveryPage() {
       {!scanFiles.length ? (
         <EmptyState
           title="No files discovered yet"
-          description="Run a scan from Settings to populate the file discovery explorer."
-        />
+          description="Run a scan from Settings to populate Discovery. If expected folders are missing, add them in Settings."
+          actions={[
+            { label: "Add folder", href: "/settings", variant: "outline" }
+          ]}
+        >
+          <ScanNowButton size="sm" />
+        </EmptyState>
       ) : (
         <Card>
           <CardHeader>

package/app/evidence/page.tsx

@@ -1,5 +1,7 @@
 import Link from "next/link";
 import { ArrowLeft, ArrowRight } from "lucide-react";
+import { EmptyState } from "@/components/empty-state";
+import { ScanNowButton } from "@/components/scan-now-button";
 import { PeriodFilter } from "@/components/period-filter";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -7,8 +9,9 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/com
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
 import { DataValue, FieldLabel, MonoText, PageHeader } from "@/components/ui/typography";
 import { dateRangeQueryParams, mergeHrefParams, resolveDateRange } from "@/src/lib/date-range";
-import { buildEvidenceTrail, parseEvidenceMetric } from "@/src/lib/evidence-trail";
+import { buildEvidenceTrail, parseEvidenceMetric, type EvidenceMetric } from "@/src/lib/evidence-trail";
 import { formatCurrency, formatExactTokens, percent } from "@/src/lib/format";
+import { cn } from "@/src/lib/utils";
 
 export const dynamic = "force-dynamic";
 
@@ -29,6 +32,100 @@ function parserStatusVariant(value: string | null) {
   return "outline";
 }
 
+const evidenceMetricTabs: Array<{ metric: EvidenceMetric; label: string }> = [
+  { metric: "processed-tokens", label: "Processed" },
+  { metric: "non-cache-tokens", label: "Fresh / non-cache" },
+  { metric: "cached-tokens", label: "Cache" },
+  { metric: "estimated-cost", label: "Cost" },
+  { metric: "sessions", label: "Sessions" }
+];
+
+function EvidenceMetricTabs({
+  current,
+  rangeLinkParams
+}: {
+  current: EvidenceMetric;
+  rangeLinkParams: Record<string, string | undefined>;
+}) {
+  return (
+    <nav className="flex flex-wrap items-center gap-2" aria-label="Evidence metric views">
+      {evidenceMetricTabs.map((item) => (
+        <Link
+          key={item.metric}
+          href={mergeHrefParams(`/evidence?metric=${item.metric}`, rangeLinkParams)}
+          className={cn(
+            "inline-flex h-8 items-center rounded-md border px-3 text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+            current === item.metric
+              ? "border-primary bg-primary text-primary-foreground"
+              : "border-border bg-card text-foreground hover:bg-muted"
+          )}
+          aria-current={current === item.metric ? "page" : undefined}
+        >
+          {item.label}
+        </Link>
+      ))}
+    </nav>
+  );
+}
+
+function EvidenceDrilldownStrip({
+  actions
+}: {
+  actions: Array<{
+    label: string;
+    detail: string;
+    href: string;
+  }>;
+}) {
+  return (
+    <div className="grid overflow-hidden rounded-md border border-border md:grid-cols-4">
+      {actions.map((action, index) => (
+        <Link
+          key={action.label}
+          href={action.href}
+          className={cn(
+            "group min-w-0 p-3 transition-colors hover:bg-muted/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+            index > 0 ? "border-t border-border md:border-l md:border-t-0" : ""
+          )}
+        >
+          <span className="flex items-center gap-1.5 text-sm font-semibold text-foreground">
+            {action.label}
+            <ArrowRight className="h-3.5 w-3.5 text-primary transition-transform group-hover:translate-x-0.5" aria-hidden="true" />
+          </span>
+          <span className="mt-1 block text-xs leading-5 text-muted-foreground">{action.detail}</span>
+        </Link>
+      ))}
+    </div>
+  );
+}
+
+function WhyThisNumberPanel({ title }: { title: string }) {
+  const items = [
+    ["Metric definition", `${title} uses the selected period, metric type, and imported local interactions.`],
+    ["Source files explain", "Source files explain which local artifacts contributed records to this number."],
+    ["Sessions explain", "Sessions explain which conversations, tools, models, and projects produced the total."],
+    ["Parser confidence explains", "Parser confidence explains whether imported values are exact, estimated, or need review."],
+    ["Model-rate state explains", "Model-rate state explains whether cost is exact, estimated, or blocked by unknown pricing."]
+  ];
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Why this number</CardTitle>
+        <CardDescription>Use these checks before treating the metric as a final answer.</CardDescription>
+      </CardHeader>
+      <CardContent className="grid gap-0 overflow-x-auto p-0 sm:grid-cols-2 xl:grid-cols-5">
+        {items.map(([label, detail], index) => (
+          <div key={label} className={cn("min-w-48 p-3", index > 0 ? "border-t sm:border-l sm:border-t-0" : "")}>
+            <FieldLabel>{label}</FieldLabel>
+            <p className="mt-2 text-xs leading-5 text-muted-foreground">{detail}</p>
+          </div>
+        ))}
+      </CardContent>
+    </Card>
+  );
+}
+
 export default async function EvidencePage({ searchParams }: EvidencePageProps) {
   const params = (await searchParams) ?? {};
   const range = resolveDateRange(params);
@@ -39,6 +136,32 @@ export default async function EvidencePage({ searchParams }: EvidencePageProps)
   const currentEvidenceHref = mergeHrefParams(`/evidence?metric=${trail.metric}`, rangeLinkParams);
   const pricingReturnParams = { returnTo: currentEvidenceHref };
   const confidenceTotal = Math.max(1, trail.confidence.exact + trail.confidence.estimated + trail.confidence.unknown);
+  const leadingSource = trail.sourceFiles[0];
+  const leadingSession = trail.sessions[0];
+  const drilldownActions = [
+    {
+      label: "Top source files",
+      detail: "Compare the local files contributing most to this metric.",
+      href: "#top-source-files"
+    },
+    {
+      label: "Largest sessions",
+      detail: "Open the session evidence table and continue into filtered sessions.",
+      href: "#session-evidence"
+    },
+    {
+      label: "Parser confidence",
+      detail: "Check whether parser status affects the imported records.",
+      href: leadingSource ? mergeHrefParams(leadingSource.parserHref, rangeLinkParams) : "/parser-debug"
+    },
+    {
+      label: "Model rates / repair",
+      detail: "Follow provider model rates or unknown-cost repair when cost needs review.",
+      href: leadingSession?.pricingHref
+        ? mergeHrefParams(leadingSession.pricingHref, pricingReturnParams)
+        : mergeHrefParams("/repair", rangeLinkParams)
+    }
+  ];
 
   return (
     <div className="space-y-6">
@@ -57,6 +180,43 @@ export default async function EvidencePage({ searchParams }: EvidencePageProps)
 
       <PeriodFilter range={range} />
 
+      <Card>
+        <CardHeader className="space-y-4">
+          <div className="space-y-1">
+            <CardTitle>Token Evidence</CardTitle>
+            <CardDescription>
+              You are viewing {trail.title}. Pivot across related metrics, then continue into source files, sessions, parser status, or model-rate repair.
+            </CardDescription>
+          </div>
+          <EvidenceMetricTabs current={trail.metric} rangeLinkParams={rangeLinkParams} />
+        </CardHeader>
+        <CardContent className="space-y-3">
+          <p className="text-sm leading-6 text-muted-foreground">
+            <span className="font-medium text-foreground">Definition:</span>{" "}
+            {trail.description}
+          </p>
+          <div className="space-y-2">
+            <FieldLabel>Continue drilling down</FieldLabel>
+            <EvidenceDrilldownStrip actions={drilldownActions} />
+          </div>
+        </CardContent>
+      </Card>
+
+      <WhyThisNumberPanel title={trail.title} />
+
+      {!trail.sessions.length && !trail.sourceFiles.length ? (
+        <EmptyState
+          title="No evidence for this metric yet"
+          description="Run a scan or open sessions to confirm whether local usage exists for the selected period and metric."
+          actions={[
+            { label: "Open sessions", href: "/sessions", variant: "outline" },
+            { label: "Open Scan Health", href: "/diagnostics", variant: "outline" }
+          ]}
+        >
+          <ScanNowButton size="sm" />
+        </EmptyState>
+      ) : null}
+
       <Card>
         <CardHeader>
           <CardTitle>Metric Totals</CardTitle>
@@ -113,7 +273,7 @@ export default async function EvidencePage({ searchParams }: EvidencePageProps)
           </CardContent>
         </Card>
 
-        <Card>
+        <Card id="top-source-files">
           <CardHeader>
             <CardTitle>Top Source Files</CardTitle>
             <CardDescription>Largest contributing local files for the same metric definition.</CardDescription>
@@ -168,9 +328,9 @@ export default async function EvidencePage({ searchParams }: EvidencePageProps)
         </Card>
       </div>
 
-      <Card>
+      <Card id="session-evidence">
         <CardHeader>
-          <CardTitle>Session, Source, Parser, And Pricing Evidence</CardTitle>
+          <CardTitle>Session, Source, Parser, And Model Rate Evidence</CardTitle>
           <CardDescription>
             The table is capped at the top 100 contributing sessions; totals above include the full metric set.
           </CardDescription>
@@ -184,7 +344,7 @@ export default async function EvidencePage({ searchParams }: EvidencePageProps)
                 <TableHead>Cost</TableHead>
                 <TableHead>Source</TableHead>
                 <TableHead>Parser</TableHead>
-                <TableHead>Pricing</TableHead>
+                <TableHead>Model rates</TableHead>
                 <TableHead>Confidence</TableHead>
               </TableRow>
             </TableHeader>

package/app/global-error.tsx

@@ -18,7 +18,7 @@ export default function GlobalError({
             <div className="text-sm font-medium text-muted-foreground">TokenTrace error</div>
             <h1 className="text-2xl font-semibold leading-tight tracking-normal">Something went wrong</h1>
             <p className="text-sm leading-6 text-muted-foreground">
-              The local dashboard could not render this view. Try again, then check Doctor if the issue repeats.
+              The local dashboard could not render this view. Try again, then open Scan Health if the issue repeats.
             </p>
             {error.digest ? (
               <p className="font-mono text-xs text-muted-foreground">Digest: {error.digest}</p>
@@ -28,7 +28,7 @@ export default function GlobalError({
                 Try again
               </Button>
               <Button asChild variant="outline">
-                <Link href="/diagnostics">Open Doctor</Link>
+                <Link href="/diagnostics">Open Scan Health</Link>
               </Button>
             </div>
           </div>