tokentrace 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -2,7 +2,59 @@
 
 All notable changes to TokenTrace are documented here.
 
-## Unreleased
+## [0.7.0] - 2026-05-12
+
+### Added
+
+- 0.7.0 Usage Intelligence roadmap for local guardrails, savings review, session comparison, project intelligence, and daily digest work.
+- Local monthly cost and token guardrails stored in Settings.
+- Overview Monthly Guardrails panel showing month-to-date local usage against configured limits.
+- Recommendation rules for monthly guardrails that are near or over limit.
+- Evidence-backed Review Queue on Insights, ranked from guardrails, unknown cost repair, high-impact sessions, dominant projects, model review, and cache reuse.
+- `tokentrace insights --json` now includes the Review Queue for local automation.
+- `tokentrace digest` and `tokentrace digest --json` for current-month local usage, guardrails, top review item, unknown-cost count, top project, and latest scan status.
+- Session Comparison Flags on Sessions to highlight token and cost outliers compared with matching project, tool, and primary-model peers.
+- Project Signals on Projects for dominant usage, unknown cost, estimated-token confidence, and model concentration patterns.
+
+### Changed
+
+- Renamed the Insights page header to Usage Intelligence to match the 0.7.0 product theme.
+- Refreshed README screenshots for Overview, Usage Intelligence, Sessions, Projects, and local guardrail Settings using public-safe synthetic local data.
+
+### Fixed
+
+- Increased the forced packed-install smoke test timeout so native SQLite dependency installation is not killed on slower machines.
+
+## [0.6.0] - 2026-05-10
+
+### Added
+
+- 0.6.0 Stable Daily Tool roadmap with explicit release cards and gates.
+- Support matrix for stable, best-effort, ignored, and unsupported TokenTrace surfaces.
+- Scan Doctor support matrix and scan freshness status.
+- Overview first-run checklist that explains missing roots, no scans, zero imports, and next actions.
+- `npm run smoke:cli` for clean-home CLI checks across scan, serve, doctor, status, Claude status-line, and watch-mode commands.
+- `npm run smoke:packed` for installing the packed tarball into a temp project and verifying the published CLI entrypoint.
+
+### Changed
+
+- Claude Code and Codex JSONL parsers now keep valid records when a transcript contains malformed lines.
+- Model alias suggestions now handle OpenAI/Codex provider-prefixed and dated snapshot names.
+- Overview period filter keeps the custom date fields and Apply button visible on desktop while presets absorb overflow.
+- Local development config declares localhost/127.0.0.1 dev origins and disables the standard Next.js dev indicator preference.
+- README documents the support matrix and unsupported product boundaries.
+- `npm run release:check` now includes CLI and packed-install smoke checks before package security inspection.
+- The npm package now excludes generated `.next` output and prepares the dashboard build in the user's TokenTrace app-data directory on first `tokentrace serve`.
+- Package trust inspection now verifies the publish tarball directly and fails if generated Next.js build output is included.
+- Packed-install smoke now starts `tokentrace serve` from the packed tarball and allows dependency install scripts needed by native SQLite bindings while keeping TokenTrace itself free of lifecycle scripts.
+- Dev security posture is cleaner: Vitest is updated to the Node 18-compatible patched line, and the unused `drizzle-kit` dev dependency has been removed.
+- `npm run security:package` now audits the full dependency graph at moderate-or-higher severity instead of checking only production high-severity advisories.
+
+### Fixed
+
+- Package inspection no longer depends on the user's global npm cache, which can contain root-owned files on some machines.
+- First-run dashboard preparation from a packed install no longer hits SQLite `database is locked` errors while Next.js imports API routes during build.
+- `tokentrace serve` now exits nonzero when the underlying Next.js server fails before readiness.
 
 ## [0.5.1] - 2026-05-10
 

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 overview dashboard](docs/assets/overview.png)
+![TokenTrace 0.7.0 overview dashboard](docs/assets/overview-0.7.0.png)
 
 ## Start In Seconds
 
@@ -37,6 +37,8 @@ tokentrace serve --port 3210 --no-open
 tokentrace scan         # Scan local AI CLI usage logs
 tokentrace doctor --json
                         # Inspect scan health and repair recommendations
+tokentrace digest --json
+                        # Print current-month local usage digest
 tokentrace insights --json
                         # Print local recommendations as JSON
 tokentrace status --json
@@ -82,7 +84,7 @@ npm run db:migrate   # Create/update local SQLite tables
 npm run db:seed      # Seed editable provider/model prices
 npm run reset        # Clear imported data and scan history
 npm test             # Run parser and cost tests
-npm run verify       # Run Vitest and TypeScript checks
+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
@@ -129,6 +131,10 @@ Default discovery checks these locations when present:
 
 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.
 
+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
+imported local CLI usage.
+
 ## Ingestion Architecture
 
 TokenTrace's primary ingestion architecture is direct local filesystem ingestion:
@@ -191,6 +197,22 @@ 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)
+
+![TokenTrace 0.7.0 project signals](docs/assets/projects-0.7.0.png)
+
+![TokenTrace 0.7.0 local guardrail settings](docs/assets/settings-guardrails-0.7.0.png)
+
+Stable Daily Tool views from `0.6.0`:
+
+![TokenTrace 0.6.0 Scan Doctor](docs/assets/doctor-0.6.0.png)
+
 CLI startup and help:
 
 ![TokenTrace CLI help](docs/assets/cli-help.gif)
@@ -235,11 +257,12 @@ Stop the server with `Ctrl+C` in the terminal where `tokentrace` is running.
 
 ## Package Trust
 
-- The npm package has no `preinstall`, `install`, or `postinstall` scripts.
-- Published Next.js server bundles are intentionally left readable instead of server-minified so Socket, npm, maintainers, and users can inspect generated runtime code.
-- `npm run package:inspect` fails if generated app route bundles look packed or unreadable.
+- The TokenTrace npm package has no `preinstall`, `install`, or `postinstall` scripts.
+- 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.
 - 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 --omit=dev --audit-level=high`.
+- 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.
@@ -291,6 +314,21 @@ Adapters live under `src/ingestion/adapters/`:
 
 Formats for Claude Code and Codex CLI can vary across versions, so these adapters are defensive and best-effort. Unknown files fail safely and show warnings in the Raw Data page.
 
+## Support Matrix
+
+TokenTrace keeps a visible support contract so daily scans are easier to trust:
+
+| Surface | Support level | Notes |
+| --- | --- | --- |
+| Claude Code project transcripts | Stable | Primary local CLI ingestion source. |
+| Codex CLI session artifacts | Best-effort | Parsed defensively while CLI formats evolve. |
+| Generic JSONL, JSON, and text logs | Best-effort | Conservative usage-shaped records only. |
+| Claude/Codex cache, plugin, todo, config, and support files | Ignored | Tracked as non-usage files, not parser failures. |
+| Editable model pricing | Stable | Local pricing rows drive costs and unknown-cost repair queues. |
+| Claude Code status line | Stable | Uses Claude Code's documented statusLine stdin contract. |
+| Codex sticky status line | Best-effort fallback | Use `tokentrace watch --session --compact` in a split or tmux pane. |
+| Desktop app scraping, browser extensions, proxying, packet capture, telemetry | Unsupported | Outside TokenTrace's product boundary. |
+
 ## Extending Parsers
 
 Example generic JSONL fixtures are in `fixtures/generic-jsonl/`.

package/SECURITY.md

@@ -8,14 +8,17 @@ downloads.
 
 - No telemetry, cloud sync, traffic interception, proxying, packet sniffing, or
   browser extension is part of the product.
-- No `preinstall`, `install`, or `postinstall` npm lifecycle scripts are used.
+- The TokenTrace package has no `preinstall`, `install`, or `postinstall`
+  npm lifecycle scripts.
 - Runtime state is stored locally in the user's TokenTrace app-data directory.
 - Raw full prompts and responses are off by default.
 - Pricing refresh downloads a public model-pricing manifest only. It does not
   send usage logs, prompts, file paths, analytics, or identifiers. Set
   `TOKENTRACE_DISABLE_PRICE_REFRESH=1` to use bundled prices only.
-- Generated Next.js server bundles are intentionally published without server
-  minification so package scanners and maintainers can inspect them.
+- 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 app-data directory when
+  needed.
 
 ## What TokenTrace Reads
 

package/app/api/settings/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse } from "next/server";
 import { getDatabasePath } from "@/src/db/client";
-import { getAppSettings, saveAppSettings } from "@/src/db/settings";
+import { getAppSettings, normalizeUsageGuardrails, saveAppSettings } from "@/src/db/settings";
 
 export const dynamic = "force-dynamic";
 
@@ -18,7 +18,8 @@ export async function PUT(request: Request) {
     : [];
   const saved = saveAppSettings({
     customFolders,
-    storeRawMessageContent: Boolean(body.storeRawMessageContent)
+    storeRawMessageContent: Boolean(body.storeRawMessageContent),
+    usageGuardrails: normalizeUsageGuardrails(body.usageGuardrails)
   });
 
   return NextResponse.json(saved);

package/app/diagnostics/page.tsx

@@ -176,6 +176,13 @@ function DoctorReportPanel({ report }: { report: DoctorReport }) {
           </div>
         </div>
 
+        <div className="rounded-md border bg-muted/30 p-3">
+          <div className="text-sm font-semibold">Scan freshness</div>
+          <div className="mt-1 text-xs leading-relaxed text-muted-foreground">
+            {report.scanFreshness.description}
+          </div>
+        </div>
+
         {report.latestScan.zeroImportExplanation ? (
           <div className="rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-950">
             {report.latestScan.zeroImportExplanation}
@@ -224,6 +231,31 @@ function DoctorReportPanel({ report }: { report: DoctorReport }) {
             ))}
           </div>
         </div>
+
+        <div className="space-y-3">
+          <div>
+            <div className="text-sm font-semibold">Support matrix</div>
+            <div className="mt-1 text-xs text-muted-foreground">
+              {report.supportMatrix.summary.stable.toLocaleString()} stable,{" "}
+              {report.supportMatrix.summary.bestEffort.toLocaleString()} best-effort,{" "}
+              {report.supportMatrix.summary.ignored.toLocaleString()} ignored,{" "}
+              {report.supportMatrix.summary.unsupported.toLocaleString()} unsupported.
+            </div>
+          </div>
+          <div className="grid divide-y border-y lg:grid-cols-2 lg:divide-x lg:divide-y-0">
+            {report.supportMatrix.items.map((item) => (
+              <div key={item.id} className="p-3">
+                <div className="flex flex-wrap items-center gap-2">
+                  <div className="text-sm font-semibold">{item.label}</div>
+                  <Badge variant={item.level === "stable" ? "success" : item.level === "unsupported" ? "destructive" : item.level === "best-effort" ? "warning" : "secondary"}>
+                    {item.level}
+                  </Badge>
+                </div>
+                <div className="mt-1 text-xs leading-relaxed text-muted-foreground">{item.description}</div>
+              </div>
+            ))}
+          </div>
+        </div>
       </CardContent>
     </Card>
   );

package/app/optimisation/page.tsx

@@ -1,6 +1,9 @@
+import Link from "next/link";
 import { AlertTriangle, CheckCircle2, Info, Lightbulb } 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 { PageHeader } from "@/components/ui/typography";
 import { getAnalyticsData } from "@/src/lib/analytics";
 
@@ -24,10 +27,60 @@ export default function OptimisationPage() {
   return (
     <div className="space-y-6">
       <PageHeader
-        title="Optimisation Insights"
-        description="Deterministic recommendations based on imported usage patterns."
+        title="Usage Intelligence"
+        description="Deterministic local review queue based on guardrails, repair work, and usage impact."
       />
 
+      <Card>
+        <CardHeader className="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between">
+          <div>
+            <CardTitle>Review Queue</CardTitle>
+            <CardDescription>
+              Evidence-backed next actions ordered by guardrails, repair work, and usage impact.
+            </CardDescription>
+          </div>
+          <Button asChild variant="outline" size="sm">
+            <Link href="/sessions">Open sessions</Link>
+          </Button>
+        </CardHeader>
+        <CardContent className="table-scroll">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>Priority</TableHead>
+                <TableHead>Category</TableHead>
+                <TableHead>Review item</TableHead>
+                <TableHead>Impact</TableHead>
+                <TableHead>Action</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {data.reviewQueue.map((item) => (
+                <TableRow key={item.id}>
+                  <TableCell>
+                    <Badge variant={severityVariant[item.severity]}>{item.severity}</Badge>
+                  </TableCell>
+                  <TableCell className="capitalize">{item.category.replace("-", " ")}</TableCell>
+                  <TableCell className="max-w-xl">
+                    <div className="font-medium">{item.title}</div>
+                    <div className="mt-1 text-xs leading-relaxed text-muted-foreground">{item.evidence}</div>
+                  </TableCell>
+                  <TableCell>
+                    <div className="text-sm font-medium">{item.impactValue}</div>
+                    <div className="text-xs text-muted-foreground">{item.impactLabel}</div>
+                  </TableCell>
+                  <TableCell>
+                    <Link href={item.href} className="font-medium text-primary underline-offset-4 hover:underline">
+                      {item.action}
+                    </Link>
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </CardContent>
+      </Card>
+
       <div className="grid gap-4">
         {data.insights.map((insight) => {
           const Icon = severityIcon[insight.severity] ?? CheckCircle2;

package/app/page.tsx

@@ -1,6 +1,5 @@
 import Link from "next/link";
-import { ArrowRight, Coins, Database, MessageSquare, Minus, Sparkles, TrendingDown, TrendingUp } from "lucide-react";
-import { EmptyState } from "@/components/empty-state";
+import { ArrowRight, Coins, Database, Gauge, MessageSquare, Minus, Sparkles, TrendingDown, TrendingUp } from "lucide-react";
 import { RankBarChart } from "@/components/charts/rank-bar-chart";
 import { TrendChart } from "@/components/charts/trend-chart";
 import { PeriodFilter } from "@/components/period-filter";
@@ -10,10 +9,14 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/com
 import { HelpTooltip } from "@/components/ui/help-tooltip";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
 import { DataValue, FieldLabel, MonoText, PageHeader } from "@/components/ui/typography";
-import { getAnalyticsData } from "@/src/lib/analytics";
+import { getAnalyticsData, getScanTrustData } from "@/src/lib/analytics";
+import { buildDoctorReport } from "@/src/lib/doctor";
+import { getDefaultSearchRoots } from "@/src/ingestion/discovery";
+import { buildFirstRunStatus, type FirstRunStatus } from "@/src/lib/first-run-status";
 import { resolveDateRange } from "@/src/lib/date-range";
 import { formatCurrency, formatTokens, percent } from "@/src/lib/format";
 import { cn } from "@/src/lib/utils";
+import type { UsageGuardrailMetric } from "@/src/lib/usage-guardrails";
 
 export const dynamic = "force-dynamic";
 
@@ -125,6 +128,131 @@ function DeltaMetric({
   );
 }
 
+function guardrailBadgeVariant(status: UsageGuardrailMetric["status"]) {
+  if (status === "exceeded") return "destructive";
+  if (status === "warning") return "warning";
+  if (status === "ok") return "success";
+  return "secondary";
+}
+
+function guardrailLabel(status: UsageGuardrailMetric["status"]) {
+  if (status === "exceeded") return "exceeded";
+  if (status === "warning") return "watch";
+  if (status === "ok") return "within limit";
+  return "not set";
+}
+
+function GuardrailMetricPanel({
+  label,
+  metric,
+  formatValue
+}: {
+  label: string;
+  metric: UsageGuardrailMetric;
+  formatValue: (value: number | null) => string;
+}) {
+  const cappedPercent = Math.min(1, Math.max(0, metric.percent));
+  const barClass =
+    metric.status === "exceeded"
+      ? "bg-destructive"
+      : metric.status === "warning"
+        ? "bg-amber-500"
+        : "bg-primary";
+
+  return (
+    <div className="min-w-0 border-t p-3 first:border-t-0 md:border-l md:border-t-0 md:first:border-l-0">
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <FieldLabel>{label}</FieldLabel>
+        <Badge variant={guardrailBadgeVariant(metric.status)}>{guardrailLabel(metric.status)}</Badge>
+      </div>
+      <DataValue className="mt-1" size="md">
+        {metric.configured ? `${formatValue(metric.used)} / ${formatValue(metric.limit)}` : formatValue(metric.used)}
+      </DataValue>
+      <div className="mt-3 h-2 overflow-hidden rounded-full bg-muted">
+        <div className={cn("h-full rounded-full", barClass)} style={{ width: `${cappedPercent * 100}%` }} />
+      </div>
+      <div className="mt-2 text-xs text-muted-foreground">
+        {metric.configured
+          ? `${percent(metric.percent)} used, ${formatValue(metric.remaining)} remaining`
+          : "Set a local monthly limit in Settings."}
+      </div>
+    </div>
+  );
+}
+
+function UsageGuardrailsPanel({
+  progress
+}: {
+  progress: {
+    monthLabel: string;
+    cost: UsageGuardrailMetric;
+    tokens: UsageGuardrailMetric;
+  };
+}) {
+  const configured = progress.cost.configured || progress.tokens.configured;
+  return (
+    <Card>
+      <CardHeader className="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between">
+        <div>
+          <CardTitle className="flex items-center gap-2">
+            <Gauge className="h-4 w-4 text-primary" />
+            Monthly Guardrails
+          </CardTitle>
+          <CardDescription>
+            {configured
+              ? `Month-to-date checks for ${progress.monthLabel}, based only on imported local CLI usage.`
+              : "Optional local limits for monthly cost and tokens."}
+          </CardDescription>
+        </div>
+        <Button asChild variant="outline" size="sm">
+          <Link href="/settings">
+            Configure <ArrowRight className="h-4 w-4" />
+          </Link>
+        </Button>
+      </CardHeader>
+      <CardContent className="p-0">
+        <div className="grid border-t md:grid-cols-2">
+          <GuardrailMetricPanel label="Cost" metric={progress.cost} formatValue={formatCurrency} />
+          <GuardrailMetricPanel label="Tokens" metric={progress.tokens} formatValue={formatTokens} />
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+function FirstRunPanel({ status }: { status: FirstRunStatus }) {
+  return (
+    <Card className={status.tone === "warning" ? "border-amber-300 bg-amber-50/50" : undefined}>
+      <CardHeader className="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between">
+        <div>
+          <CardTitle>{status.title}</CardTitle>
+          <CardDescription>{status.description}</CardDescription>
+        </div>
+        <Button asChild variant={status.tone === "warning" ? "outline" : "default"}>
+          <Link href={status.primaryAction.href}>
+            {status.primaryAction.label} <ArrowRight className="h-4 w-4" />
+          </Link>
+        </Button>
+      </CardHeader>
+      <CardContent>
+        <div className="grid divide-y border-y md:grid-cols-5 md:divide-x md:divide-y-0">
+          {status.checks.map((check) => (
+            <div key={check.id} className="p-3">
+              <div className="flex flex-wrap items-center gap-2">
+                <div className="text-sm font-semibold">{check.label}</div>
+                <Badge variant={check.state === "pass" ? "success" : check.state === "warn" ? "warning" : "secondary"}>
+                  {check.state}
+                </Badge>
+              </div>
+              <div className="mt-1 text-xs leading-relaxed text-muted-foreground">{check.detail}</div>
+            </div>
+          ))}
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
 type OverviewPageProps = {
   searchParams?: Promise<Record<string, string | string[] | undefined>>;
 };
@@ -133,6 +261,22 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
   const params = (await searchParams) ?? {};
   const range = resolveDateRange(params);
   const data = getAnalyticsData(range.filters);
+  const trust = getScanTrustData();
+  const roots = await getDefaultSearchRoots();
+  const doctorReport = buildDoctorReport({ ...trust, roots });
+  const firstRunStatus = buildFirstRunStatus({
+    rootCount: roots.length,
+    pricedModelCount: trust.pricedModelCount,
+    latestScan: doctorReport.latestScan.id
+      ? {
+          filesScanned: doctorReport.latestScan.filesScanned,
+          recordsImported: doctorReport.latestScan.recordsImported,
+          zeroImportExplanation: doctorReport.latestScan.zeroImportExplanation
+        }
+      : null,
+    interactions: trust.confidence.interactions,
+    unknownCostInteractions: trust.confidence.unknownCostInteractions
+  });
   const { summary } = data;
 
   return (
@@ -152,10 +296,7 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
       <PeriodFilter range={range} />
 
       {summary.interactions === 0 ? (
-        <EmptyState
-          title="No usage imported yet"
-          description="Add custom folders if needed, run a scan from Settings, then return here for analytics."
-        />
+        <FirstRunPanel status={firstRunStatus} />
       ) : null}
 
       <Card>
@@ -205,6 +346,8 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
         </CardContent>
       </Card>
 
+      <UsageGuardrailsPanel progress={data.usageGuardrails} />
+
       <Card>
         <CardHeader>
           <h2 className="text-sm font-semibold leading-tight">Recommended Next Actions</h2>

package/app/projects/page.tsx

@@ -1,6 +1,7 @@
 import Link from "next/link";
 import { RankBarChart } from "@/components/charts/rank-bar-chart";
 import { TrendChart } from "@/components/charts/trend-chart";
+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, MonoText, PageHeader } from "@/components/ui/typography";
@@ -20,6 +21,56 @@ export default function ProjectAnalyticsPage() {
         description="Group usage by local repository or inferred project path."
       />
 
+      {data.projectSignals.length ? (
+        <Card>
+          <CardHeader>
+            <CardTitle>Project Signals</CardTitle>
+            <CardDescription>
+              Local project-level patterns that deserve review before optimizing individual sessions.
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="table-scroll">
+            <Table>
+              <TableHeader>
+                <TableRow>
+                  <TableHead>Priority</TableHead>
+                  <TableHead>Signal</TableHead>
+                  <TableHead>Project</TableHead>
+                  <TableHead>Metric</TableHead>
+                  <TableHead>Action</TableHead>
+                </TableRow>
+              </TableHeader>
+              <TableBody>
+                {data.projectSignals.slice(0, 8).map((signal) => (
+                  <TableRow key={signal.id}>
+                    <TableCell>
+                      <Badge variant={signal.severity === "high" ? "destructive" : signal.severity === "medium" ? "warning" : "secondary"}>
+                        {signal.severity}
+                      </Badge>
+                    </TableCell>
+                    <TableCell className="capitalize">{signal.signal}</TableCell>
+                    <TableCell className="max-w-lg">
+                      <div className="font-medium">{signal.project}</div>
+                      <MonoText className="mt-1 block truncate text-muted-foreground">{signal.path}</MonoText>
+                      <div className="mt-1 text-xs text-muted-foreground">{signal.evidence}</div>
+                    </TableCell>
+                    <TableCell>
+                      <div className="font-medium">{signal.metricValue}</div>
+                      <div className="text-xs text-muted-foreground">{signal.metricLabel}</div>
+                    </TableCell>
+                    <TableCell>
+                      <Link href={signal.href} className="font-medium text-primary underline-offset-4 hover:underline">
+                        {signal.action}
+                      </Link>
+                    </TableCell>
+                  </TableRow>
+                ))}
+              </TableBody>
+            </Table>
+          </CardContent>
+        </Card>
+      ) : null}
+
       <div className="grid gap-4 lg:grid-cols-[1fr_1.4fr]">
         <Card>
           <CardHeader>

package/app/sessions/page.tsx

@@ -1,6 +1,11 @@
+import Link from "next/link";
 import { SessionExplorer } from "@/components/session-explorer";
+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 { PageHeader } from "@/components/ui/typography";
 import { getAnalyticsData } from "@/src/lib/analytics";
+import { formatCurrency, formatTokens } from "@/src/lib/format";
 
 export const dynamic = "force-dynamic";
 
@@ -24,6 +29,56 @@ export default async function SessionsPage({
         title="Session Explorer"
         description="Search and filter imported sessions by tool, model, project, cost, and estimation status."
       />
+      {data.sessionComparisons.length ? (
+        <Card>
+          <CardHeader>
+            <CardTitle>Session Comparison Flags</CardTitle>
+            <CardDescription>
+              Sessions that are unusual compared with the same project, tool, and primary model.
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="table-scroll">
+            <Table>
+              <TableHeader>
+                <TableRow>
+                  <TableHead>Priority</TableHead>
+                  <TableHead>Flag</TableHead>
+                  <TableHead>Session</TableHead>
+                  <TableHead>Tokens</TableHead>
+                  <TableHead>Cost</TableHead>
+                  <TableHead>Peer median</TableHead>
+                  <TableHead>Action</TableHead>
+                </TableRow>
+              </TableHeader>
+              <TableBody>
+                {data.sessionComparisons.slice(0, 6).map((row) => (
+                  <TableRow key={row.sessionId}>
+                    <TableCell>
+                      <Badge variant={row.severity === "high" ? "destructive" : "warning"}>{row.severity}</Badge>
+                    </TableCell>
+                    <TableCell>{row.flag}</TableCell>
+                    <TableCell className="max-w-lg">
+                      <div className="font-medium">{row.title}</div>
+                      <div className="mt-1 text-xs text-muted-foreground">{row.project} / {row.tool} / {row.models}</div>
+                    </TableCell>
+                    <TableCell>{formatTokens(row.totalTokens)}</TableCell>
+                    <TableCell>{formatCurrency(row.cost)}</TableCell>
+                    <TableCell>
+                      <div>{formatTokens(row.peerMedianTokens)}</div>
+                      <div className="text-xs text-muted-foreground">{row.peerSessions} peer sessions</div>
+                    </TableCell>
+                    <TableCell>
+                      <Link href={row.href} className="font-medium text-primary underline-offset-4 hover:underline">
+                        Compare evidence
+                      </Link>
+                    </TableCell>
+                  </TableRow>
+                ))}
+              </TableBody>
+            </Table>
+          </CardContent>
+        </Card>
+      ) : null}
       <SessionExplorer
         sessions={data.sessions}
         initialProject={params?.project}