tokentrace 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to TokenTrace are documented here.
 
+## [0.8.0] - 2026-05-12
+
+### Added
+
+- Evidence detail pages and `tokentrace evidence --json` for tracing metric totals back to sessions, source files, parser status, and pricing context.
+- Unknown Cost Repair workbench and `tokentrace repair --json` for grouped local repair state, alias hints, parser review links, and pricing follow-up.
+- Parser Trust Report and Scan History Diff panels in Diagnostics for latest scan parser coverage and scan-to-scan import changes.
+
+### Changed
+
+- Overview metric cards now link major totals to evidence trails and route unknown cost work to Unknown Cost Repair.
+- Overview now places Token Trend and Cost Trend directly after Usage Pulse and the metric cards, with Monthly Guardrails and Recommended Next Actions below the charts.
+- Dense evidence, repair, parser trust, and scan diff tables preserve horizontal scrolling and stable source-path truncation.
+- Evidence and repair copy now states local-first behavior, support-file ignores, and parser-review requirements for unsupported files.
+- README screenshots now use public-safe synthetic Evidence + Repair views, and obsolete screenshot assets were removed from the package payload.
+
+### Fixed
+
+- Overview custom period date fields now use an intentionally inset calendar icon while preserving native `type="date"` submission fields and the single-line desktop toolbar.
+- The app shell now constrains page width on small screens so wide toolbars scroll internally instead of widening the whole page.
+- `tokentrace statusline setup claude` and piped Claude status-line input no longer touch the TokenTrace app database or start the dashboard.
+
 ## [0.7.0] - 2026-05-12
 
 ### Added

package/README.md

@@ -8,7 +8,7 @@ Local-first analytics for AI CLI usage. TokenTrace scans local CLI logs, normali
 
 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 0.7.0 overview dashboard](docs/assets/overview-0.7.0.png)
+![TokenTrace overview dashboard](docs/assets/overview-0.8.0.png)
 
 ## Start In Seconds
 
@@ -37,6 +37,10 @@ tokentrace serve --port 3210 --no-open
 tokentrace scan         # Scan local AI CLI usage logs
 tokentrace doctor --json
                         # Inspect scan health and repair recommendations
+tokentrace evidence --json
+                        # Print metric evidence trails as JSON
+tokentrace repair --json
+                        # Print unknown-cost repair groups as JSON
 tokentrace digest --json
                         # Print current-month local usage digest
 tokentrace insights --json
@@ -184,6 +188,8 @@ tokentrace statusline claude
 
 Claude Code sends session JSON to the command on stdin. TokenTrace reads the transcript path, model, context usage, and session cost, then prints one compact local line:
 
+Do not set the Claude Code `statusLine.command` to plain `tokentrace`. Plain `tokentrace` starts the dashboard, while `tokentrace statusline claude` prints exactly one status-line response.
+
 ![TokenTrace Claude Code status line](docs/assets/claude-statusline.svg)
 
 You can also inspect the same local status outside Claude Code:
@@ -197,21 +203,15 @@ Codex CLI status-line integration is intentionally deferred until its status-lin
 
 ## Screenshots
 
-Usage Intelligence views from `0.7.0`:
-
-![TokenTrace 0.7.0 overview dashboard](docs/assets/overview-0.7.0.png)
-
-![TokenTrace 0.7.0 Usage Intelligence review queue](docs/assets/usage-intelligence-0.7.0.png)
-
-![TokenTrace 0.7.0 session comparison flags](docs/assets/sessions-0.7.0.png)
+Evidence + Repair views:
 
-![TokenTrace 0.7.0 project signals](docs/assets/projects-0.7.0.png)
+![TokenTrace overview dashboard](docs/assets/overview-0.8.0.png)
 
-![TokenTrace 0.7.0 local guardrail settings](docs/assets/settings-guardrails-0.7.0.png)
+![TokenTrace processed tokens evidence trail](docs/assets/evidence-0.8.0.png)
 
-Stable Daily Tool views from `0.6.0`:
+![TokenTrace unknown cost repair queue](docs/assets/repair-0.8.0.png)
 
-![TokenTrace 0.6.0 Scan Doctor](docs/assets/doctor-0.6.0.png)
+![TokenTrace Scan Doctor parser trust report](docs/assets/doctor-parser-trust-0.8.0.png)
 
 CLI startup and help:
 
@@ -225,24 +225,6 @@ Optional wrapper diagnostics:
 
 ![TokenTrace wrapper command](docs/assets/cli-wrapper.gif)
 
-Session exploration:
-
-![TokenTrace session explorer](docs/assets/session-explorer.png)
-
-Scan Doctor and file discovery:
-
-![TokenTrace ingestion diagnostics](docs/assets/diagnostics.png)
-
-![TokenTrace file discovery](docs/assets/discovery.png)
-
-Editable model pricing:
-
-![TokenTrace pricing configuration](docs/assets/pricing.png)
-
-Mobile overview:
-
-![TokenTrace mobile overview](docs/assets/mobile-overview.png)
-
 ## Privacy Model
 
 - All processing runs locally on your machine.

package/app/api/repair-items/route.ts

@@ -0,0 +1,81 @@
+import { NextResponse } from "next/server";
+import {
+  buildUnknownCostRepairWorkbench,
+  getUnknownCostReview,
+  saveUnknownCostReview,
+  type UnknownCostRepairStatus
+} from "@/src/lib/unknown-cost-repair";
+
+export const dynamic = "force-dynamic";
+
+const reviewStates = new Set<UnknownCostRepairStatus>([
+  "unresolved",
+  "ignored",
+  "resolved",
+  "needs-parser-review"
+]);
+
+function text(value: unknown, maxLength: number) {
+  return typeof value === "string" ? value.trim().slice(0, maxLength) : "";
+}
+
+function reviewState(value: unknown): UnknownCostRepairStatus | null {
+  return typeof value === "string" && reviewStates.has(value as UnknownCostRepairStatus)
+    ? (value as UnknownCostRepairStatus)
+    : null;
+}
+
+function workbenchGroupForKey(key: string) {
+  return buildUnknownCostRepairWorkbench().groups.find((group) => group.key === key) ?? null;
+}
+
+export async function GET() {
+  return NextResponse.json(buildUnknownCostRepairWorkbench());
+}
+
+export async function PUT(request: Request) {
+  const body = await request.json();
+  const key = text(body.key, 1000);
+  const status = reviewState(body.status ?? body.state);
+
+  if (!key) {
+    return NextResponse.json({ error: "key is required" }, { status: 400 });
+  }
+
+  if (!status) {
+    return NextResponse.json({ error: "status must be unresolved, ignored, resolved, or needs-parser-review" }, { status: 400 });
+  }
+
+  const group = workbenchGroupForKey(key);
+  const existing = group ? null : getUnknownCostReview(key);
+  if (!group && (!existing || existing.updatedAt == null)) {
+    return NextResponse.json({ error: "repair key was not found in current workbench evidence" }, { status: 404 });
+  }
+
+  const metadata = {
+    sourceFile: "",
+    model: "",
+    cause: ""
+  };
+  if (group) {
+    metadata.sourceFile = group.sourceFile;
+    metadata.model = group.model;
+    metadata.cause = group.cause;
+  } else if (existing) {
+    metadata.sourceFile = existing.sourceFile;
+    metadata.model = existing.model;
+    metadata.cause = existing.cause;
+  }
+  const review = saveUnknownCostReview({
+    key,
+    status,
+    notes: text(body.notes ?? body.note, 500),
+    sourceFile: metadata.sourceFile,
+    model: metadata.model,
+    cause: metadata.cause
+  });
+
+  return NextResponse.json({ review });
+}
+
+export const PATCH = PUT;

package/app/diagnostics/page.tsx

@@ -2,6 +2,7 @@ import Link from "next/link";
 import { AlertTriangle, ArrowRight, CheckCircle2, CircleDashed } from "lucide-react";
 import { Badge } from "@/components/ui/badge";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
 import { DataValue, FieldLabel, MonoText, PageHeader } from "@/components/ui/typography";
 import { ScanHealthSummary } from "@/components/scan-health-summary";
 import { getAnalyticsData, getScanTrustData, type DebugScanRun } from "@/src/lib/analytics";
@@ -136,6 +137,7 @@ function TrustChecklist({
 function DoctorReportPanel({ report }: { report: DoctorReport }) {
   const statusRows = [
     ["Imported", report.fileStatus.imported],
+    ["With errors", report.fileStatus.importedWithErrors],
     ["Duplicates", report.fileStatus.duplicates],
     ["Ignored", report.fileStatus.ignored],
     ["Unsupported", report.fileStatus.unsupported],
@@ -192,7 +194,7 @@ function DoctorReportPanel({ report }: { report: DoctorReport }) {
         <div className="grid gap-6 xl:grid-cols-[1fr_1fr]">
           <div className="space-y-3">
             <div className="mb-3 text-sm font-semibold">File handling</div>
-            <div className="grid border-y sm:grid-cols-5 sm:divide-x xl:grid-cols-2">
+            <div className="grid border-y sm:grid-cols-6 sm:divide-x xl:grid-cols-2">
               {statusRows.map(([label, value]) => (
                 <div key={label} className="p-2">
                   <FieldLabel>{label}</FieldLabel>
@@ -261,6 +263,139 @@ function DoctorReportPanel({ report }: { report: DoctorReport }) {
   );
 }
 
+function ParserTrustPanel({ report }: { report: DoctorReport["parserTrust"] }) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Parser Trust Report</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>
+      </CardHeader>
+      <CardContent className="table-scroll">
+        {report.parsers.length ? (
+          <Table className="min-w-[72rem]">
+            <TableHeader>
+              <TableRow>
+                <TableHead>Parser</TableHead>
+                <TableHead>Version</TableHead>
+                <TableHead>Source</TableHead>
+                <TableHead className="text-right">Imported</TableHead>
+                <TableHead className="text-right">With errors</TableHead>
+                <TableHead className="text-right">Ignored</TableHead>
+                <TableHead className="text-right">Unsupported</TableHead>
+                <TableHead className="text-right">Failed</TableHead>
+                <TableHead className="text-right">Duplicate</TableHead>
+                <TableHead className="text-right">Records</TableHead>
+                <TableHead className="min-w-56">Latest reason</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {report.parsers.map((row) => (
+                <TableRow key={`${row.parser}:${row.version}:${row.sourceFamily}`}>
+                  <TableCell className="font-medium">{row.parser}</TableCell>
+                  <TableCell>
+                    <Badge variant="secondary">{row.version}</Badge>
+                  </TableCell>
+                  <TableCell>{row.sourceFamily}</TableCell>
+                  <TableCell className="text-right">{row.imported.toLocaleString()}</TableCell>
+                  <TableCell className="text-right">{row.importedWithErrors.toLocaleString()}</TableCell>
+                  <TableCell className="text-right">{row.ignored.toLocaleString()}</TableCell>
+                  <TableCell className="text-right">{row.unsupported.toLocaleString()}</TableCell>
+                  <TableCell className="text-right">{row.failed.toLocaleString()}</TableCell>
+                  <TableCell className="text-right">{row.duplicate.toLocaleString()}</TableCell>
+                  <TableCell className="text-right">{row.recordsImported.toLocaleString()}</TableCell>
+                  <TableCell className="max-w-md text-xs text-muted-foreground">
+                    {row.latestReason || "No parser reason recorded."}
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        ) : (
+          <div className="px-4 py-6 text-sm text-muted-foreground">
+            No parser trust data yet. Run `tokentrace scan` to populate the latest scan report.
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
+function formatDelta(value: number) {
+  if (value > 0) return `+${value.toLocaleString()}`;
+  return value.toLocaleString();
+}
+
+function ScanDiffPanel({ report }: { report: DoctorReport["scanDiff"] }) {
+  const rows: Array<[string, keyof DoctorReport["scanDiff"]["current"]]> = [
+    ["Files scanned", "filesScanned"],
+    ["Records imported", "recordsImported"],
+    ["Imported", "imported"],
+    ["With errors", "importedWithErrors"],
+    ["Duplicates", "duplicates"],
+    ["Ignored", "ignored"],
+    ["Unsupported", "unsupported"],
+    ["Failed", "failed"]
+  ];
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Scan History Diff</CardTitle>
+        <CardDescription>
+          Latest scan compared with the previous scan using deterministic scan ordering. Ignored files are known support files, not usage transcripts.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="table-scroll space-y-4">
+        <div className="grid border-y md:grid-cols-2 md:divide-x">
+          <div className="min-w-0 p-3">
+            <FieldLabel>Latest scan</FieldLabel>
+            <div className="mt-1 text-sm font-semibold">{formatDate(report.latestCompletedAt ?? report.latestStartedAt)}</div>
+            <MonoText className="mt-1 block truncate text-xs text-muted-foreground">
+              {report.latestScanId ?? "No scan"}
+            </MonoText>
+          </div>
+          <div className="min-w-0 p-3">
+            <FieldLabel>Previous scan</FieldLabel>
+            <div className="mt-1 text-sm font-semibold">{formatDate(report.previousCompletedAt ?? report.previousStartedAt)}</div>
+            <MonoText className="mt-1 block truncate text-xs text-muted-foreground">
+              {report.previousScanId ?? "No previous scan"}
+            </MonoText>
+          </div>
+        </div>
+
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Count</TableHead>
+              <TableHead className="text-right">Current</TableHead>
+              <TableHead className="text-right">Previous</TableHead>
+              <TableHead className="text-right">Delta</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {rows.map(([label, key]) => (
+              <TableRow key={key}>
+                <TableCell className="font-medium">{label}</TableCell>
+                <TableCell className="text-right">{report.current[key].toLocaleString()}</TableCell>
+                <TableCell className="text-right">{report.previous[key].toLocaleString()}</TableCell>
+                <TableCell className="text-right">{formatDelta(report.delta[key])}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+
+        {report.explanation ? (
+          <div className="rounded-md border bg-muted/30 p-3 text-sm leading-relaxed text-muted-foreground">
+            {report.explanation}
+          </div>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}
+
 function scanRunVariant(scanRun: DebugScanRun) {
   if (scanRun.errors.length > 0) return "destructive";
   if (scanRun.warnings.length > 0) return "warning";
@@ -366,6 +501,10 @@ export default async function DiagnosticsPage() {
 
       <DoctorReportPanel report={doctorReport} />
 
+      <ParserTrustPanel report={doctorReport.parserTrust} />
+
+      <ScanDiffPanel report={doctorReport.scanDiff} />
+
       <ScanHistoryPanel scanRuns={data.scanRuns} />
 
       <ScanHealthSummary health={data.health} />

package/app/evidence/page.tsx

@@ -0,0 +1,170 @@
+import Link from "next/link";
+import { ArrowLeft, ArrowRight } from "lucide-react";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
+import { DataValue, FieldLabel, MonoText, PageHeader } from "@/components/ui/typography";
+import { buildEvidenceTrail, parseEvidenceMetric } from "@/src/lib/evidence-trail";
+import { formatCurrency, formatTokens, percent } from "@/src/lib/format";
+
+export const dynamic = "force-dynamic";
+
+type EvidencePageProps = {
+  searchParams?: Promise<Record<string, string | string[] | undefined>>;
+};
+
+function confidenceVariant(value: string) {
+  if (value === "exact") return "success";
+  if (value === "unknown") return "warning";
+  return "secondary";
+}
+
+function parserStatusVariant(value: string | null) {
+  if (value === "imported") return "success";
+  if (value === "imported_with_errors") return "warning";
+  if (!value) return "secondary";
+  return "outline";
+}
+
+export default async function EvidencePage({ searchParams }: EvidencePageProps) {
+  const params = (await searchParams) ?? {};
+  const trail = buildEvidenceTrail({ metric: parseEvidenceMetric(params?.metric) });
+
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title={`${trail.title} Evidence`}
+        description={trail.description}
+        actions={
+          <Button asChild variant="outline" size="sm">
+            <Link href="/">
+              <ArrowLeft className="h-4 w-4" />
+              Overview
+            </Link>
+          </Button>
+        }
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Metric Totals</CardTitle>
+          <CardDescription>
+            Totals use the same filtered metric definition as the session evidence below.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="p-0">
+          <div className="grid divide-y border-t sm:grid-cols-2 sm:divide-x sm:divide-y-0 lg:grid-cols-5">
+            <div className="p-3">
+              <FieldLabel>Tokens</FieldLabel>
+              <DataValue className="mt-1" size="md">{formatTokens(trail.totals.tokens)}</DataValue>
+            </div>
+            <div className="p-3">
+              <FieldLabel>Cost</FieldLabel>
+              <DataValue className="mt-1" size="md">{formatCurrency(trail.totals.cost)}</DataValue>
+            </div>
+            <div className="p-3">
+              <FieldLabel>Sessions</FieldLabel>
+              <DataValue className="mt-1" size="md">{trail.totals.sessions.toLocaleString()}</DataValue>
+            </div>
+            <div className="p-3">
+              <FieldLabel>Interactions</FieldLabel>
+              <DataValue className="mt-1" size="md">{trail.totals.interactions.toLocaleString()}</DataValue>
+            </div>
+            <div className="p-3">
+              <FieldLabel>Unknown Cost</FieldLabel>
+              <DataValue className="mt-1" size="md">{trail.totals.unknownCostInteractions.toLocaleString()}</DataValue>
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Session, Source, Parser, And Pricing Evidence</CardTitle>
+          <CardDescription>
+            The table is capped at the top 100 contributing sessions; totals above include the full metric set.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="table-scroll p-0">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>Session</TableHead>
+                <TableHead>Metric Total</TableHead>
+                <TableHead>Cost</TableHead>
+                <TableHead>Source</TableHead>
+                <TableHead>Parser</TableHead>
+                <TableHead>Pricing</TableHead>
+                <TableHead>Confidence</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {trail.sessions.length ? (
+                trail.sessions.map((session) => (
+                  <TableRow key={session.id}>
+                    <TableCell className="min-w-64">
+                      <Link href={session.sessionHref} className="font-medium text-primary underline-offset-4 hover:underline">
+                        {session.title}
+                      </Link>
+                      <div className="mt-1 text-xs text-muted-foreground">
+                        {session.tool} / {session.provider} / {session.project}
+                      </div>
+                    </TableCell>
+                    <TableCell>{formatTokens(session.totalTokens)}</TableCell>
+                    <TableCell>{formatCurrency(session.cost)}</TableCell>
+                    <TableCell className="max-w-80">
+                      <Link href={session.sourceHref} title={session.sourceFile}>
+                        <MonoText className="block truncate text-muted-foreground underline-offset-4 hover:underline">
+                          {session.sourceFile}
+                        </MonoText>
+                      </Link>
+                    </TableCell>
+                    <TableCell className="min-w-44">
+                      <div className="flex flex-wrap items-center gap-2">
+                        <Badge variant={parserStatusVariant(session.parserStatus)}>
+                          {session.parserStatus ?? "not scanned"}
+                        </Badge>
+                        <Link href={session.parserHref} className="text-xs font-medium text-primary underline-offset-4 hover:underline">
+                          Parser <ArrowRight className="inline h-3.5 w-3.5" />
+                        </Link>
+                      </div>
+                      <div className="mt-1 text-xs text-muted-foreground">
+                        {session.parser ?? "No parser"} / {session.parserConfidence == null ? "confidence unknown" : percent(session.parserConfidence)}
+                      </div>
+                    </TableCell>
+                    <TableCell className="min-w-44">
+                      {session.pricingHref ? (
+                        <Link href={session.pricingHref} className="font-medium text-primary underline-offset-4 hover:underline">
+                          {session.model}
+                        </Link>
+                      ) : (
+                        <span>{session.model}</span>
+                      )}
+                    </TableCell>
+                    <TableCell>
+                      <div className="flex flex-col items-start gap-1">
+                        <Badge variant={confidenceVariant(session.tokenConfidence)}>
+                          {session.tokenConfidence}
+                        </Badge>
+                        <span className="text-xs text-muted-foreground">
+                          {session.interactions.toLocaleString()} interactions
+                        </span>
+                      </div>
+                    </TableCell>
+                  </TableRow>
+                ))
+              ) : (
+                <TableRow>
+                  <TableCell colSpan={7} className="h-24 text-center text-muted-foreground">
+                    No evidence is available for this metric yet.
+                  </TableCell>
+                </TableRow>
+              )}
+            </TableBody>
+          </Table>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/app/globals.css

@@ -54,11 +54,17 @@ body {
 }
 
 .period-date-input {
-  padding-inline-end: 0.5rem;
+  color-scheme: light;
+  position: relative;
 }
 
 .period-date-input::-webkit-calendar-picker-indicator {
   cursor: pointer;
-  margin-inline-end: 0.25rem;
-  opacity: 0.8;
+  height: 100%;
+  margin: 0;
+  opacity: 0;
+  padding: 0;
+  position: absolute;
+  right: 0;
+  width: 2.5rem;
 }

package/app/layout.tsx

@@ -1,3 +1,4 @@
+import * as React from "react";
 import type { Metadata } from "next";
 import "./globals.css";
 import { MobileNav, Sidebar } from "@/components/sidebar";
@@ -17,7 +18,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
       <body>
         <div className="flex min-h-screen">
           <Sidebar appVersion={appVersion} />
-          <main className="min-w-0 flex-1">
+          <main className="min-w-0 flex-1 overflow-x-hidden">
             <div className="border-b bg-card px-4 py-3 md:hidden">
               <div className="flex items-center justify-between gap-3">
                 <div className="flex min-w-0 items-center gap-2">
@@ -33,7 +34,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
               </div>
             </div>
             <MobileNav />
-            <div className="mx-auto w-full max-w-7xl px-4 py-6 sm:px-6 lg:px-8">
+            <div className="mx-auto w-full min-w-0 max-w-[100vw] px-4 py-6 sm:px-6 md:max-w-7xl lg:px-8">
               {children}
             </div>
           </main>