tokentrace 0.19.2 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,61 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.21.0] - 2026-06-26
+
+### Added
+
+- **Local agent preflight.** Added `tokentrace preflight --json` and MCP
+  `get_preflight`, a read-only readiness report that returns proceed, caution,
+  or blocked before another coding-agent run. It combines scan freshness, data
+  confidence, guardrails, anomaly signals, findings, next actions, and privacy
+  notes without scanning files or inspecting raw prompts.
+
+### Changed
+
+- **Simpler dashboard shell.** Primary navigation now follows the daily loop:
+  Today, Sessions, Evidence, Fix Data, Reports, and Settings. Diagnostic
+  surfaces such as Tools, Models, Projects, Query, Scan Health, Discovery,
+  Parsers, Raw Data, and Model Rates remain available under Advanced.
+
+### Fixed
+
+- **First-run scan state uses latest scan evidence.** The Today first-run panel
+  now distinguishes "scan ran but imported no usage" from "no scan has run,"
+  preserving zero-import explanations from Scan Health.
+
+## [0.20.0] - 2026-06-12
+
+### Changed
+
+- **Overview and shell UI polish.** The dashboard shell now groups navigation by
+  task area, and the Overview summary surface makes local evidence,
+  cached/non-cache token states, and exact/estimated/unknown cost distinctions
+  easier to scan.
+- **ChatGPT app feasibility documented.** Added a recommendation to prototype
+  only a private, redacted evidence-pack ChatGPT app workflow until public
+  distribution can preserve TokenTrace's local-first privacy boundary.
+- **Private ChatGPT app prototype.** Added `tokentrace chatgpt-app` with a
+  local HTTP `/mcp` server, one read-only `get_redacted_evidence_pack` Apps SDK
+  tool, a compact MCP Apps widget resource, and a developer-mode runbook. The
+  prototype uses redacted evidence packs and does not scan files on startup or
+  publish a public app.
+- **ChatGPT app release readiness.** Added `npm run release:chatgpt:check`, a
+  hosted `/mcp` validator, a release runbook, and optional tag-workflow wiring
+  so ChatGPT app readiness can be checked alongside npm and MCP registry
+  releases while keeping OpenAI Dashboard submission and publishing manual.
+- **ChatGPT app submission kit.** Added `docs/chatgpt-app/` with step-by-step
+  personal-account Dashboard release instructions, ready-to-paste submission
+  copy, privacy and review templates, test prompts, screenshot guidance, and
+  reusable SVG app assets for the manual ChatGPT app submission flow.
+- **Development dashboard CSP avoids React issue noise.** The local dev server
+  now allows React's development-only diagnostics without relaxing the
+  production Content Security Policy.
+- **Product website moved to Baseframe Labs.** The package `homepage`, MCP
+  registry `websiteUrl`, README link, and in-app guide link now point to
+  `https://www.baseframelabs.com/apps/tokentrace`. The previous
+  `abhiyoheswaran.com` URL redirects there.
+
 ## [0.19.2] - 2026-06-05
 
 ### Changed

package/README.md

@@ -8,7 +8,7 @@ Local-first AI CLI usage analytics. TokenTrace scans local CLI logs and local us
 
 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.
 
-[Website](https://www.abhiyoheswaran.com/apps/tokentrace) · [Source](https://github.com/abhiyoheswaran1/tokentrace)
+[Website](https://www.baseframelabs.com/apps/tokentrace) · [Source](https://github.com/abhiyoheswaran1/tokentrace)
 
 ![TokenTrace overview dashboard](docs/assets/overview-0.12.0.png)
 
@@ -45,6 +45,8 @@ tokentrace mcp          # Start the local stdio MCP server
 tokentrace scan         # Scan local AI CLI usage logs
 tokentrace doctor --json
                         # Inspect scan health and repair recommendations
+tokentrace preflight --json
+                        # Check readiness before another coding-agent run
 tokentrace evidence --json
                         # Print metric evidence trails as JSON
 tokentrace repair --json
@@ -126,11 +128,22 @@ tokentrace mcp selftest --json
 ```
 
 The MCP server exposes the same local-first surfaces as tools: capabilities,
-status, Scan Health, evidence, repair queue, reports, and an explicit scan tool.
-It does not scan files on startup, and its scan tool requires
+preflight, status, Scan Health, evidence, repair queue, reports, and an
+explicit scan tool. It does not scan files on startup, and its scan tool requires
 `confirmLocalScan=true` before reading local usage files or writing the local
 database.
 
+Before starting another long coding-agent run, use the read-only preflight
+surface:
+
+```bash
+tokentrace preflight --json
+```
+
+In MCP clients, call `get_preflight` for the same proceed, caution, or blocked
+decision with local scan freshness, confidence, guardrail, anomaly, and repair
+findings. Preflight does not scan files or inspect raw prompts.
+
 When the local dashboard is already running, agents can fetch the same manifest
 over localhost:
 
@@ -216,7 +229,7 @@ TokenTrace labels the trust level behind imported numbers:
 - 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,
+The dashboard surfaces a Data Confidence score on Today, 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.
 

package/TOKENTRACE_AGENT.md

@@ -44,6 +44,27 @@ The MCP server does not scan on startup. Its `run_scan` tool requires
 `confirmLocalScan=true` before reading local usage files or writing the local
 database.
 
+Before starting another long coding-agent run, use the read-only preflight:
+
+```bash
+tokentrace preflight --json
+```
+
+The matching MCP tool is `get_preflight`. It returns a proceed, caution, or
+blocked decision with local scan freshness, data confidence, guardrail status,
+anomaly signals, findings, and next actions. It does not scan files.
+
+Private ChatGPT developer-mode prototype:
+
+```bash
+tokentrace chatgpt-app selftest --json
+tokentrace chatgpt-app --port 8787 --hostname 127.0.0.1
+```
+
+This starts a local HTTP `/mcp` server for one read-only redacted evidence-pack
+tool. ChatGPT requires an HTTPS tunnel for developer-mode connector testing.
+See `docs/CHATGPT_APP_PROTOTYPE.md`.
+
 If the local dashboard is already running, the same manifest is available from:
 
 ```bash
@@ -74,19 +95,25 @@ curl http://127.0.0.1:3030/api/roadmap
    get_agent_guide
    ```
 
-3. Refresh local data when the human expects current usage:
+3. Check whether local evidence is ready for the next agent run:
+
+   ```bash
+   tokentrace preflight --json
+   ```
+
+4. Refresh local data when the human expects current usage:
 
    ```bash
    tokentrace scan --json
    ```
 
-4. Check trust before making claims:
+5. Check trust before making claims:
 
    ```bash
    tokentrace doctor --json
    ```
 
-5. Explain totals with evidence:
+6. Explain totals with evidence:
 
    ```bash
    tokentrace evidence --json
@@ -117,8 +144,8 @@ Get deterministic classification suggestions for the unknown-cost queue:
 tokentrace repair auto-classify --json [--min-confidence=N]
 ```
 
-The matching MCP tools are `get_anomalies`, `query_usage`, and
-`get_classifications`. All three are read-only and require no
+The matching MCP tools are `get_preflight`, `get_anomalies`, `query_usage`, and
+`get_classifications`. All four are read-only and require no
 `confirmLocalScan` acknowledgement.
 
 ## Guardrails

package/app/api/evidence-pack/route.ts

@@ -1,7 +1,6 @@
 import { NextResponse } from "next/server";
-import { getAnalyticsData } from "@/src/lib/analytics";
-import { buildEvidencePack, renderEvidencePackMarkdown } from "@/src/lib/evidence-pack";
-import { buildEvidenceTrail, parseEvidenceMetric } from "@/src/lib/evidence-trail";
+import { buildMetricEvidencePack, renderEvidencePackMarkdown } from "@/src/lib/evidence-pack";
+import { parseEvidenceMetric } from "@/src/lib/evidence-trail";
 
 export const dynamic = "force-dynamic";
 
@@ -9,43 +8,7 @@ export async function GET(request: Request) {
   const url = new URL(request.url);
   const format = url.searchParams.get("format") === "markdown" ? "markdown" : "json";
   const metric = parseEvidenceMetric(url.searchParams.get("metric"));
-  const trail = buildEvidenceTrail({ metric });
-  const analytics = getAnalyticsData();
-  const pack = buildEvidencePack({
-    scope: {
-      type: "metric",
-      id: metric,
-      label: trail.title
-    },
-    totals: trail.totals,
-    confidenceDrivers: [
-      `${trail.confidence.exact.toLocaleString()} exact interactions`,
-      `${trail.confidence.estimated.toLocaleString()} estimated interactions`,
-      `${trail.confidence.unknown.toLocaleString()} unknown interactions`,
-      `Data confidence ${analytics.dataConfidence.score}/100`
-    ],
-    sourceFiles: trail.sourceFiles.map((source) => source.sourceFile),
-    parserNotes: trail.sessions
-      .map((session) => `${session.parser ?? "unknown parser"}: ${session.parserStatus ?? "unknown status"}`)
-      .slice(0, 20),
-    modelRateState: trail.sessions
-      .map((session) =>
-        session.pricingHref ? `${session.model}: model-rate link available` : `${session.model}: no model-rate link`
-      )
-      .slice(0, 20),
-    repairLinks: trail.sessions
-      .filter((session) => session.unknownCostInteractions > 0)
-      .map((session) => `/repair?source=${encodeURIComponent(session.sourceFile)}`),
-    records: trail.sessions.map((session) => ({
-      id: session.id,
-      role: "session",
-      model: session.model,
-      sourceFile: session.sourceFile,
-      totalTokens: session.totalTokens,
-      cost: session.cost,
-      interactions: session.interactions
-    }))
-  });
+  const pack = buildMetricEvidencePack({ metric });
 
   if (format === "markdown") {
     return new NextResponse(renderEvidencePackMarkdown(pack), {

package/app/evidence/evidence-context-panel.tsx

@@ -16,7 +16,7 @@ export function EvidenceContextPanel({ actions }: { actions: EvidenceContextActi
         <div className="max-w-[72ch]">
           <FieldLabel>Evidence path</FieldLabel>
           <p className="mt-1 text-sm leading-6 text-muted-foreground">
-            Evidence is a contextual drill-down from Overview, Sessions, Repair, and exported packs. If you opened this page directly, start with processed tokens, then pivot by metric or follow the next action that matches what looks incomplete.
+            Evidence is a contextual drill-down from Today, Sessions, Fix Data, and exported packs. If you opened this page directly, start with processed tokens, then pivot by metric or follow the next action that matches what looks incomplete.
           </p>
         </div>
         <div className="grid min-w-0 gap-2 sm:grid-cols-2 xl:grid-cols-4">

package/app/guide/guide-content.ts

@@ -1,6 +1,6 @@
 import { ClipboardList, Gauge, Search, Wrench } from "lucide-react";
 
-export const PRODUCT_WEBSITE_URL = "https://www.abhiyoheswaran.com/apps/tokentrace";
+export const PRODUCT_WEBSITE_URL = "https://www.baseframelabs.com/apps/tokentrace";
 
 export const guideNav = [
   ["#start", "Start here", "First scan to first evidence"],
@@ -13,8 +13,8 @@ export const guideNav = [
 export const dailyLoop = [
   {
     title: "Read the pulse",
-    page: "Overview",
-    detail: "Check current period usage, cost, sessions, unknown cost, and the latest trend window before chasing details.",
+    page: "Today",
+    detail: "Check readiness, usage, cost, sessions, unknown cost, and the latest trend window before chasing details.",
     href: "/",
     icon: Gauge
   },
@@ -27,7 +27,7 @@ export const dailyLoop = [
   },
   {
     title: "Repair what blocks trust",
-    page: "Repair",
+    page: "Fix Data",
     detail: "Unknown cost usually needs a known model name, nonzero tokens, or an editable provider model rate.",
     href: "/repair",
     icon: Wrench
@@ -86,8 +86,11 @@ export const mcpAgentEntries = [
 ];
 
 export const pageMap = [
-  ["Overview", "Top-level totals, trends, repair queue, guardrails, and recommended next actions."],
+  ["Today", "Top-level readiness, totals, trends, repair queue, guardrails, and recommended next actions."],
   ["Sessions", "Per-session evidence with models, costs, cache activity, parser provenance, and tool calls."],
+  ["Evidence", "Trace a metric back to sessions, source files, confidence drivers, and model-rate state."],
+  ["Fix Data", "Repair unknown cost, missing model names, missing token counts, and trust blockers."],
+  ["Reports", "Reusable local reports for weekly usage, high-cost sessions, confidence trends, and source coverage."],
   ["Model Rates", "Editable provider model rates used for dashboard cost estimates and unknown-cost repair."],
   ["Scan Health", "First-run checklist, scan health, supply-chain IOC check, supported file types, and diagnostics for missing data."],
   ["Discovery", "Recently scanned files grouped by parser, source family, status, and import yield."],
@@ -97,7 +100,7 @@ export const pageMap = [
 export const emptyStatePlaybook = [
   ["No data", "Run Scan now from Settings, then use Scan Health if records stay at zero."],
   ["No logs found", "Add a custom folder or use Claude Code, Codex, or another supported CLI before scanning again."],
-  ["Unknown cost", "Open repair or Model Rates to decide whether the missing piece is model name, token count, or provider rate."],
+  ["Unknown cost", "Open Fix Data or Model Rates to decide whether the missing piece is model name, token count, or provider rate."],
   ["Parser warnings", "Open Discovery and Parsers to separate unsupported files from imported-with-errors rows."],
   ["Sandbox smoke skipped", "Local sandbox runs can skip server binding checks. Run the packed smoke or release check outside that constraint before release."]
 ];

package/app/guide/page.tsx

@@ -55,7 +55,7 @@ const firstRunSteps: FirstRunStep[] = [
     number: "5",
     title: "Inspect evidence",
     page: "Sessions",
-    detail: "Use Sessions, Evidence, Repair, and Projects after the first useful import.",
+    detail: "Use Sessions, Evidence, Fix Data, and Projects after the first useful import.",
     href: "/sessions",
     action: "Open Sessions"
   }
@@ -69,12 +69,12 @@ const workflows: GuideWorkflow[] = [
   },
   {
     problem: "Unknown cost",
-    path: "Repair, Model Rates, Evidence",
+    path: "Fix Data, Model Rates, Evidence",
     action: "Find whether the missing piece is model name, token count, or editable provider rate."
   },
   {
     problem: "High token usage",
-    path: "Overview, Sessions, Projects",
+    path: "Today, Sessions, Projects",
     action: "Compare processed, non-cache, and cache totals before treating a spike as fresh context growth."
   },
   {
@@ -111,7 +111,7 @@ export default function GuidePage() {
     {
       label: "Unknown cost",
       value: `${unknownCosts.toLocaleString()} unknown costs`,
-      detail: unknownCosts > 0 ? "Open repair or Model Rates." : "Cost coverage is clear.",
+      detail: unknownCosts > 0 ? "Open Fix Data or Model Rates." : "Cost coverage is clear.",
       ok: unknownCosts === 0
     },
     {

package/app/page.tsx

@@ -53,11 +53,11 @@ async function OverviewPrimarySection({ range }: { range: ResolvedDateRange }) {
     .map((entry) => ({ date: entry.date, value: entry.value, severity: entry.severity }));
 
   return (
-    <div className="space-y-8">
+    <div className="overview-primary-section space-y-7">
       {summary.interactions === 0 ? <FirstRunPanel status={firstRunStatus} /> : null}
       <UsagePulsePanel comparison={data.comparison} />
       <DataConfidenceStrip confidence={data.dataConfidence} />
-      <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-6">
+      <div className="overview-summary-grid grid gap-3 md:grid-cols-2 xl:grid-cols-6">
         <TokenAccountingCard
           summary={summary}
           processedHref={evidenceLinks["processed-tokens"]}
@@ -109,7 +109,7 @@ async function OverviewRepairSection({ range }: { range: ResolvedDateRange }) {
   }
 
   return (
-    <div className="space-y-8">
+    <div className="overview-repair-section space-y-7">
       {summary.interactions > 0 ? (
         <OverviewReviewStatusStrip
           report={doctorReport}
@@ -140,10 +140,10 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
   const range = resolveDateRange(params);
 
   return (
-    <div className="space-y-8">
+    <div className="overview-workbench space-y-7">
       <PageHeader
-        title="Overview"
-        description="Local token, cost, model, and session analytics across AI CLI tools."
+        title="Today"
+        description="Local readiness, cost, token, session, and repair signals before the next AI CLI run."
         actions={
           <Button asChild>
             <Link href="/settings#scan-controls">

package/app/repair/page.tsx

@@ -22,8 +22,8 @@ export default async function RepairPage({ searchParams }: RepairPageProps) {
   return (
     <div className="space-y-6">
       <PageHeader
-        title="Unknown Cost Repair"
-        description="Grouped local evidence for interactions that could not be priced."
+        title="Fix Data"
+        description="Grouped local evidence for interactions that could not be priced or trusted yet."
         actions={
           <div className="flex flex-wrap gap-2">
             <Button asChild variant="outline">

package/components/overview/summary-cards.tsx

@@ -6,6 +6,34 @@ import { DataValue, FieldLabel } from "@/components/ui/typography";
 import { formatCurrency, formatTokens } from "@/src/lib/format";
 import { cn } from "@/src/lib/utils";
 
+type DetailItem = {
+  label: string;
+  value: string;
+};
+
+function EvidenceAction({
+  href,
+  label,
+  muted = false
+}: {
+  href: string;
+  label: string;
+  muted?: boolean;
+}) {
+  return (
+    <Link
+      href={href}
+      className={cn(
+        "inline-flex w-fit items-center gap-1.5 text-xs font-medium underline-offset-4 hover:underline",
+        muted ? "text-muted-foreground hover:text-foreground" : "text-primary"
+      )}
+    >
+      <span>{label}</span>
+      <ArrowRight className="h-3.5 w-3.5" aria-hidden="true" />
+    </Link>
+  );
+}
+
 function CostSessionsMetricPane({
   label,
   value,
@@ -22,7 +50,7 @@ function CostSessionsMetricPane({
 }: {
   label: string;
   value: string;
-  detailItems: string[];
+  detailItems: DetailItem[];
   href: string;
   actionLabel: string;
   secondaryHref?: string;
@@ -36,7 +64,7 @@ function CostSessionsMetricPane({
   return (
     <section
       className={cn(
-        "cost-sessions-section grid min-w-0 grid-rows-[auto_auto_auto_auto_1fr_auto] p-4 md:row-span-6 md:grid-rows-subgrid",
+        "cost-sessions-section cost-sessions-metric-pane grid min-w-0 grid-rows-[auto_auto_auto_auto_1fr_auto] p-4 md:row-span-6 md:grid-rows-subgrid",
         className
       )}
     >
@@ -53,8 +81,9 @@ function CostSessionsMetricPane({
 
       <div className="mt-3 flex flex-wrap items-start gap-x-2 gap-y-1 text-xs leading-snug text-muted-foreground">
         {detailItems.map((item, index) => (
-          <span key={item} className="inline-flex min-w-0 items-center gap-2">
-            <span className="min-w-0">{item}</span>
+          <span key={item.label} className="inline-flex min-w-0 items-center gap-1.5">
+            <span className="font-medium text-foreground">{item.label}</span>
+            <span className="min-w-0">{item.value}</span>
             {index < detailItems.length - 1 ? <span className="hidden text-border sm:inline">/</span> : null}
           </span>
         ))}
@@ -67,16 +96,14 @@ function CostSessionsMetricPane({
 
       <div aria-hidden="true" />
 
-      <div className="flex flex-wrap items-center gap-x-3 gap-y-1 pt-4">
-        <Link href={href} className="inline-flex w-fit items-center gap-1.5 text-xs font-medium text-primary underline-offset-4 hover:underline">
-          {actionLabel}
-          <ArrowRight className="h-3.5 w-3.5" aria-hidden="true" />
-        </Link>
-        {secondaryHref ? (
-          <Link href={secondaryHref} className="inline-flex w-fit items-center gap-1.5 text-xs font-medium text-muted-foreground underline-offset-4 hover:text-foreground hover:underline">
-            {secondaryActionLabel ?? "View details"}
-          </Link>
-        ) : null}
+      <div className="pt-4">
+        <FieldLabel className="mb-2">Local evidence</FieldLabel>
+        <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
+          <EvidenceAction href={href} label={actionLabel} />
+          {secondaryHref ? (
+            <EvidenceAction href={secondaryHref} label={secondaryActionLabel ?? "View details"} muted />
+          ) : null}
+        </div>
       </div>
     </section>
   );
@@ -124,9 +151,9 @@ export function CostSessionsCard({
             value={formatCurrency(summary.totalCost)}
             valueClassName="wrap-break-word text-2xl"
             detailItems={[
-              `${formatCurrency(summary.exactCost)} exact`,
-              `${formatCurrency(summary.estimatedCost)} estimated`,
-              `${summary.unknownCostInteractions.toLocaleString()} unknown`
+              { label: "Exact", value: formatCurrency(summary.exactCost) },
+              { label: "Estimated", value: formatCurrency(summary.estimatedCost) },
+              { label: "Unknown", value: summary.unknownCostInteractions.toLocaleString() }
             ]}
             href={costHref}
             actionLabel={costActionLabel}
@@ -140,7 +167,7 @@ export function CostSessionsCard({
             className="border-t md:border-l md:border-t-0"
             label="Sessions"
             value={summary.sessions.toLocaleString()}
-            detailItems={[`${summary.interactions.toLocaleString()} interactions`]}
+            detailItems={[{ label: "Interactions", value: summary.interactions.toLocaleString() }]}
             href={sessionsHref}
             actionLabel="View evidence"
             trustLabel="Session trust"
@@ -195,8 +222,8 @@ export function TokenAccountingCard({
 }) {
   const evidenceActions = [
     { label: "Processed", href: processedHref },
-    { label: "Fresh", href: freshHref },
-    { label: "Cache", href: cacheHref }
+    { label: "Fresh / non-cache", href: freshHref },
+    { label: "Cache read/write", href: cacheHref }
   ];
 
   return (
@@ -248,7 +275,7 @@ export function TokenAccountingCard({
             detail={`${formatTokens(summary.inputTokens)} input / ${formatTokens(summary.outputTokens)} output / ${formatTokens(summary.reasoningTokens)} reasoning`}
           />
           <TokenAccountingSlice
-            label="Cache"
+            label="Cache read/write"
             value={formatTokens(summary.cachedTokens)}
             detail={`${formatTokens(summary.cacheReadTokens)} read / ${formatTokens(summary.cacheWriteTokens)} write`}
           />
@@ -261,19 +288,22 @@ export function TokenAccountingCard({
           </span>
         </p>
 
-        <div className="mt-auto flex flex-wrap items-center gap-x-3 gap-y-1 pt-4">
-          {evidenceActions.map((action) => (
-            <Link
-              key={action.href}
-              href={action.href}
-              aria-label={`View ${action.label.toLowerCase()} token evidence`}
-              className="inline-flex w-fit items-center gap-1.5 text-xs font-medium text-primary underline-offset-4 hover:underline"
-            >
-              <span className="text-muted-foreground">{action.label}</span>
-              <span>View evidence</span>
-              <ArrowRight className="h-3.5 w-3.5" aria-hidden="true" />
-            </Link>
-          ))}
+        <div className="mt-auto pt-4">
+          <FieldLabel className="mb-2">Local evidence</FieldLabel>
+          <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
+            {evidenceActions.map((action) => (
+              <Link
+                key={action.href}
+                href={action.href}
+                aria-label={`View ${action.label.toLowerCase()} token evidence`}
+                className="inline-flex w-fit items-center gap-1.5 text-xs font-medium text-primary underline-offset-4 hover:underline"
+              >
+                <span className="text-muted-foreground">{action.label}</span>
+                <span>View evidence</span>
+                <ArrowRight className="h-3.5 w-3.5" aria-hidden="true" />
+              </Link>
+            ))}
+          </div>
         </div>
       </CardContent>
     </Card>