tokentrace 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.11.0] - 2026-05-18
+
+### Added
+
+- `npm run security:ioc` scans project files and local Claude/VS Code hook files for high-signal Mini Shai-Hulud/TanStack supply-chain indicators before release.
+- Tokenizer-backed estimates for recognized OpenAI/Codex and Claude-family model names, with explicit `tokenizer estimate` and `simple estimate` confidence labels.
+- Native SQLite history ingestion for local usage databases with usage-shaped tables, source-file evidence, import-profile metadata, and source-provided cost preservation.
+- Data Confidence scoring on Overview, Projects, Sessions, and Session Timeline views, combining token source, cost coverage, parser confidence, and scan freshness.
+- Import Profiles in Settings so users can define safe local wrapper-log matchers without writing parser code.
+- Repair Workbench bulk actions for marking visible unknown-cost groups verified, parser-review, ignored, or reopened.
+- Supply-chain IOC status in Scan Health, backed by the same local `security:ioc` scanner used by release checks.
+
+### Changed
+
+- Session Timeline pages now explain token spikes, model changes, cache activity, cost coverage, confidence drivers, and direct unknown-cost repair links.
+- Scan Health now distinguishes exact, tokenizer-estimated, simple-estimated, high-confidence, low-confidence, and unknown token rows.
+- The roadmap API and CLI now report the 0.11.0 Accuracy & Evidence release contract.
+
+### Fixed
+
+- Source-provided interaction costs are no longer overwritten as unknown during post-scan cost recalculation when model rates are missing.
+
+## [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 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.
 
 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 Accuracy & Evidence 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 Accuracy & Evidence release status is also machine-readable:
 
 ```bash
 tokentrace roadmap --json
@@ -139,18 +141,36 @@ 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
 npm run package:test # Verify, build, and dry-run the npm package
 npm run package:inspect
                     # Check package transparency guardrails
+npm run security:ioc
+                    # Scan lockfiles, workflows, and local AI-tool hooks for supply-chain IOCs
 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
 ```
 
+## Accuracy And Evidence
+
+TokenTrace labels the trust level behind imported numbers:
+
+- exact provider token counts
+- tokenizer estimates for recognized OpenAI/Codex and Claude-family model names
+- simple estimates when only text-like content is available
+- 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,
+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.
+
 Release work uses internal milestone commits until the next public minor
 release. See [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md) before
 bumping versions, tagging, creating GitHub releases, or publishing npm.
@@ -190,7 +210,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 +300,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:
 
@@ -320,15 +340,16 @@ Stop the server with `Ctrl+C` in the terminal where `tokentrace` is running.
 - The published package ships readable application source and the compiled CLI runtime, not generated `.next/server` route bundles.
 - `tokentrace serve` prepares the local dashboard build in the user's TokenTrace app-data directory the first time it is needed.
 - `npm run package:inspect` fails if generated Next.js build output appears in the published tarball.
+- `npm run security:ioc` scans lockfiles, workflows, and local Claude/VS Code hook files for high-signal supply-chain compromise indicators.
 - Public npm publishing is configured through GitHub Actions Trusted Publishing and provenance from version tags.
 - Socket GitHub checks and ProjScan are used as release guardrails, alongside `npm audit --audit-level=moderate`.
 - Release notes are published directly in GitHub Releases from the relevant changelog section, not as a link-only summary.
 
 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 +363,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 +432,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/SECURITY.md

@@ -40,8 +40,12 @@ When running from source, the default development database is
 ## Release Trust
 
 Public package releases are built from Git tags. The release flow includes
-package inspection, production dependency audit, ProjScan checks, and npm
-Trusted Publishing through GitHub Actions.
+package inspection, supply-chain IOC scanning, production dependency audit,
+ProjScan checks, and npm Trusted Publishing through GitHub Actions.
+
+Run `npm run security:ioc` to check lockfiles, GitHub Actions workflows, and
+local Claude/VS Code hook files for high-signal Mini Shai-Hulud/TanStack-style
+indicators before release or after a dependency scare.
 
 ## Reporting
 

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

@@ -1,5 +1,6 @@
 import { NextResponse } from "next/server";
 import {
+  bulkUpdateUnknownCostRepairs,
   buildUnknownCostRepairWorkbench,
   getUnknownCostReview,
   saveUnknownCostReview,
@@ -40,9 +41,30 @@ export async function PUT(request: Request) {
     return NextResponse.json({ error: parsed.error }, { status: 400 });
   }
   const body = parsed.body;
+  const keys = Array.isArray(body.keys)
+    ? body.keys.map((value) => text(value, 1000)).filter(Boolean)
+    : [];
   const key = text(body.key, 1000);
   const status = reviewState(body.status ?? body.state);
 
+  if (keys.length) {
+    if (!status) {
+      return NextResponse.json({ error: "status must be unresolved, ignored, resolved, or needs-parser-review" }, { status: 400 });
+    }
+    const currentKeys = new Set(buildUnknownCostRepairWorkbench().groups.map((group) => group.key));
+    const missingKey = keys.find((item) => !currentKeys.has(item) && !getUnknownCostReview(item)?.updatedAt);
+    if (missingKey) {
+      return NextResponse.json({ error: "one or more repair keys were not found in current workbench evidence" }, { status: 404 });
+    }
+    return NextResponse.json(
+      bulkUpdateUnknownCostRepairs({
+        keys,
+        status,
+        notes: text(body.notes ?? body.note, 500)
+      })
+    );
+  }
+
   if (!key) {
     return NextResponse.json({ error: "key is required" }, { status: 400 });
   }

package/app/api/settings/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from "next/server";
 import { getDatabasePath } from "@/src/db/client";
 import { getAppSettings, normalizeUsageGuardrails, saveAppSettings } from "@/src/db/settings";
 import { jsonBooleanFlag, readJsonObject } from "@/src/lib/api-json";
+import { normalizeImportProfiles } from "@/src/lib/import-profiles";
 
 export const dynamic = "force-dynamic";
 
@@ -27,7 +28,8 @@ export async function PUT(request: Request) {
   const saved = saveAppSettings({
     customFolders,
     storeRawMessageContent: jsonBooleanFlag(body.storeRawMessageContent),
-    usageGuardrails: normalizeUsageGuardrails(body.usageGuardrails)
+    usageGuardrails: normalizeUsageGuardrails(body.usageGuardrails),
+    importProfiles: normalizeImportProfiles(body.importProfiles)
   });
 
   return NextResponse.json(saved);

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

@@ -7,8 +7,10 @@ import { DataValue, FieldLabel, MonoText, PageHeader } from "@/components/ui/typ
 import { ScanHealthSummary } from "@/components/scan-health-summary";
 import { getAnalyticsData, getScanTrustData, type DebugScanRun } from "@/src/lib/analytics";
 import { buildDoctorReport, type DoctorReport } from "@/src/lib/doctor";
+import { buildScanHealth } from "@/src/lib/scan-health";
 import { getDefaultSearchRoots } from "@/src/ingestion/discovery";
 import { formatDate } from "@/src/lib/format";
+import { getSupplyChainHealth } from "@/src/lib/supply-chain-health";
 
 export const dynamic = "force-dynamic";
 
@@ -43,7 +45,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 +53,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 +79,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 +155,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 +219,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 +238,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 +269,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 +344,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>
@@ -461,7 +463,17 @@ function ScanHistoryPanel({ scanRuns }: { scanRuns: DebugScanRun[] }) {
 }
 
 export default async function DiagnosticsPage() {
-  const data = getScanTrustData();
+  const baseData = getScanTrustData();
+  const supplyChain = getSupplyChainHealth();
+  const data = {
+    ...baseData,
+    health: buildScanHealth({
+      scanRuns: baseData.scanRuns,
+      scanFiles: baseData.scanFiles,
+      confidence: baseData.confidence,
+      supplyChain
+    })
+  };
   const analytics = getAnalyticsData();
   const roots = await getDefaultSearchRoots();
   const doctorReport = buildDoctorReport({
@@ -472,8 +484,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 +493,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 +525,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 +555,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>