tokentrace 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 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
+
+- In-app Guide page covering first scan setup, Claude Code status-line installation, status-line label meanings, page workflows, privacy, and troubleshooting.
+- `tokentrace agent --json` and `tokentrace capabilities --json` for a read-only machine-readable discovery manifest that coding agents can use before scanning or opening the dashboard.
+- Local dashboard discovery endpoints at `/api/agent` and `/api/capabilities` returning the same manifest.
+- `tokentrace roadmap --json` and `/api/roadmap` for machine-readable 0.10.0 implementation status, evidence paths, verification gates, and release status.
+- Package-level agent discovery references: `TOKENTRACE_AGENT.md`, `llms.txt`, and `docs/agent-discovery.schema.json`.
+- Repo-level agent instructions for Codex and Claude Code requiring Superpowers, ProjScan, changelog discipline, and explicit maintainer approval before releases.
+- 0.10.0 Guided Operator roadmap for in-app guidance, status-line clarity, trend continuity, release-safe agent workflow, and verification gates.
+- First-run guided setup in Overview and Guide so new users can move from scan roots to first useful evidence without a separate tutorial mode.
+- Guide release-readiness and empty-state sections covering roadmap gates, release status, no data, missing logs, unknown pricing, parser warnings, and sandbox smoke skips.
+
+### Changed
+
+- Guide now shows live local setup status for latest scan, imported records, unknown costs, and priced model coverage.
+- Agent discovery follow-up commands are now structured as command arrays instead of shell strings.
+- Claude Code status-line output now leads with live context and cost, then labels transcript totals as processed and cache usage to avoid confusing cumulative processed tokens with current context size.
+- Package inspection and packed-install smoke now enforce the agent discovery docs, schema, executable CLI bin, and 0.10.0 release-status contract.
+- Overview metric cards now show inline trust annotations explaining processed, non-cache, cached, cost, and session counts near the numbers.
+- Overview Period defaults to All time again, while token and cost trend charts share one control bar that defaults chart history to the latest 60 days with 30-day, 90-day, and All options.
+- Usage Pulse now suppresses extreme percentage labels when the previous comparison baseline is too small to be useful.
+
+### Fixed
+
+- Token and cost trend charts now include explicit zero-value calendar days between imported usage days instead of visually skipping idle periods.
+
 ## [0.9.0] - 2026-05-13
 
 ### Added

package/CONTRIBUTING.md

@@ -22,12 +22,30 @@ npm run dev
 
 Open `http://localhost:3000`.
 
+## Agentic Coding Workflow
+
+TokenTrace coding work uses the Superpowers methodology from
+<https://github.com/obra/superpowers>: clarify intent, plan, use TDD for
+behavior changes, review, and verify before completion claims.
+
+ProjScan is a required code-intelligence and quality tool. Use the npm package
+from <https://www.npmjs.com/package/projscan> through the local script:
+
+```bash
+npm run projscan:doctor
+```
+
+Run ProjScan after substantial changes and before release readiness claims. It
+does not replace tests, typecheck, lint, build, package inspection, or smoke
+checks.
+
 Useful checks:
 
 ```bash
 npm run verify
 npm run build
 npm run scan
+npm run projscan:doctor
 ```
 
 ## Parser Contributions

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
 
@@ -34,6 +36,11 @@ tokentrace              # Start local dashboard
 tokentrace serve        # Start local dashboard
 tokentrace serve --port 3210 --no-open
                         # Start on a fixed port without opening a browser
+tokentrace agent --json # Print machine-readable agent discovery manifest
+tokentrace capabilities --json
+                        # Alias for agent discovery manifest
+tokentrace roadmap --json
+                        # Print Guided Operator release implementation status
 tokentrace scan         # Scan local AI CLI usage logs
 tokentrace doctor --json
                         # Inspect scan health and repair recommendations
@@ -72,6 +79,48 @@ tokentrace --help       # Print help
 tokentrace --version    # Print version
 ```
 
+## For Coding Agents
+
+Agents should start with the read-only discovery manifest:
+
+```bash
+tokentrace agent --json
+```
+
+The alias below returns the same manifest:
+
+```bash
+tokentrace capabilities --json
+```
+
+The manifest describes TokenTrace's local-first privacy model, safe JSON commands,
+common workflows, Claude Code status-line setup, Codex sidecar fallback, and
+guardrails such as never running `tokentrace reset` without explicit human
+approval. The discovery command does not scan files, initialize the database, or
+start the dashboard.
+
+Package-level agent references are included for agents that inspect repository
+or npm package contents before invoking commands:
+
+- [TOKENTRACE_AGENT.md](TOKENTRACE_AGENT.md)
+- [llms.txt](llms.txt)
+- [docs/agent-discovery.schema.json](docs/agent-discovery.schema.json)
+
+When the local dashboard is already running, agents can fetch the same manifest
+over localhost:
+
+```bash
+curl http://127.0.0.1:3030/api/agent
+curl http://127.0.0.1:3030/api/capabilities
+```
+
+The Guided Operator release status is also machine-readable:
+
+```bash
+tokentrace roadmap --json
+curl http://127.0.0.1:3030/api/roadmap
+```
+
 ## Run From Source
 
 ```bash
@@ -92,12 +141,18 @@ 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 smoke:packed
+                    # Inspect packed tarball and smoke test packed CLI
+tokentrace roadmap --json
+                    # Inspect evidence gates and release status
 ```
 
 Release work uses internal milestone commits until the next public minor
@@ -139,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
@@ -202,7 +257,7 @@ 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:
 
 ```text
-TokenTrace | Opus | session 3.3K tokens | cache 2.0K | cost $0.1235 | ctx 7% | priced
+TokenTrace | Opus | ctx 7% | cost $0.1235 | processed 3.3K tokens | cache 2.0K | priced
 ```
 
 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.
@@ -229,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:
 
@@ -275,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.
 
@@ -291,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:
 
@@ -360,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/TOKENTRACE_AGENT.md

@@ -0,0 +1,83 @@
+# TokenTrace Agent Guide
+
+TokenTrace is a local-first CLI and dashboard for AI coding-agent token, cost,
+session, parser, and evidence analytics.
+
+## Start Here
+
+Use the read-only discovery manifest before running any other TokenTrace command:
+
+```bash
+tokentrace agent --json
+```
+
+This alias returns the same manifest:
+
+```bash
+tokentrace capabilities --json
+```
+
+The manifest follows the schema in `docs/agent-discovery.schema.json`.
+
+If the local dashboard is already running, the same manifest is available from:
+
+```bash
+curl http://127.0.0.1:3030/api/agent
+curl http://127.0.0.1:3030/api/capabilities
+```
+
+## Roadmap Status
+
+Inspect the current 0.10.0 implementation pipeline and release blockers:
+
+```bash
+tokentrace roadmap --json
+curl http://127.0.0.1:3030/api/roadmap
+```
+
+## Safe Automation Loop
+
+1. Discover capabilities:
+
+   ```bash
+   tokentrace agent --json
+   ```
+
+2. Refresh local data when the human expects current usage:
+
+   ```bash
+   tokentrace scan --json
+   ```
+
+3. Check trust before making claims:
+
+   ```bash
+   tokentrace doctor --json
+   ```
+
+4. Explain totals with evidence:
+
+   ```bash
+   tokentrace evidence --json
+   ```
+
+## Guardrails
+
+- Do not run `tokentrace reset` unless the human explicitly asks to clear imported local data.
+- Do not call processed tokens current context size. Use `ctx` for live context-window pressure.
+- Treat database paths, source file paths, prompts, and raw transcript settings as local sensitive data.
+- Discovery is read-only: it does not scan files, initialize the dashboard database, start a server, or make a network request.
+
+## Integrations
+
+Claude Code status line:
+
+```bash
+tokentrace statusline setup claude
+```
+
+Codex fallback while native status-line hooks remain unstable:
+
+```bash
+tokentrace watch --session --compact
+```

package/app/api/agent/route.ts

@@ -0,0 +1,7 @@
+import { agentDiscoveryResponse } from "@/src/lib/agent-discovery-api";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  return agentDiscoveryResponse();
+}

package/app/api/capabilities/route.ts

@@ -0,0 +1,7 @@
+import { agentDiscoveryResponse } from "@/src/lib/agent-discovery-api";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  return agentDiscoveryResponse();
+}

package/app/api/roadmap/route.ts

@@ -0,0 +1,13 @@
+import { NextResponse } from "next/server";
+import { getAppVersion } from "@/src/lib/app-version";
+import { buildRoadmapStatus } from "@/src/lib/roadmap-status";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  return NextResponse.json(buildRoadmapStatus({ packageVersion: getAppVersion() }), {
+    headers: {
+      "cache-control": "no-store"
+    }
+  });
+}

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>