tokentrace 0.19.2 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [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)
 

package/TOKENTRACE_AGENT.md

@@ -44,6 +44,17 @@ 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.
 
+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

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/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"],

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,7 +140,7 @@ 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."

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>

package/components/sidebar.tsx

@@ -26,28 +26,52 @@ import { formatAppVersion, getAppVersion } from "@/src/lib/app-version";
 import { cn } from "@/src/lib/utils";
 
 const overviewNavItem = { href: "/", label: "Overview", icon: Gauge };
+const toolsNavItem = { href: "/tools", label: "Tools", icon: Terminal };
+const modelsNavItem = { href: "/models", label: "Models", icon: Bot };
+const projectsNavItem = { href: "/projects", label: "Projects", icon: FolderGit2 };
+const sessionsNavItem = { href: "/sessions", label: "Sessions", icon: Search };
+const insightsNavItem = { href: "/optimisation", label: "Insights", icon: Sparkles };
+const queryNavItem = { href: "/query", label: "Query", icon: Database };
+const repairNavItem = { href: "/repair", label: "Repair", icon: Wrench };
+const pricingNavItem = { href: "/pricing", label: "Model Rates", icon: SlidersHorizontal };
+const diagnosticsNavItem = { href: "/diagnostics", label: "Scan Health", icon: ClipboardList };
+const discoveryNavItem = { href: "/discovery", label: "Discovery", icon: BarChart3 };
+const parsersNavItem = { href: "/parser-debug", label: "Parsers", icon: Bug };
+const rawDataNavItem = { href: "/debug", label: "Raw Data", icon: Bug };
+const settingsNavItem = { href: "/settings", label: "Settings", icon: Settings };
 
-const primaryNavItems = [
-  overviewNavItem,
-  { href: "/tools", label: "Tools", icon: Terminal },
-  { href: "/models", label: "Models", icon: Bot },
-  { href: "/projects", label: "Projects", icon: FolderGit2 },
-  { href: "/sessions", label: "Sessions", icon: Search },
-  { href: "/optimisation", label: "Insights", icon: Sparkles },
-  { href: "/query", label: "Query", icon: Database },
-  { href: "/repair", label: "Repair", icon: Wrench },
-  { href: "/pricing", label: "Model Rates", icon: SlidersHorizontal },
-  { href: "/diagnostics", label: "Scan Health", icon: ClipboardList },
-  { href: "/discovery", label: "Discovery", icon: BarChart3 },
-  { href: "/parser-debug", label: "Parsers", icon: Bug },
-  { href: "/debug", label: "Raw Data", icon: Bug },
-  { href: "/settings", label: "Settings", icon: Settings }
+const navSections = [
+  {
+    label: "Analyze",
+    items: [overviewNavItem, toolsNavItem, modelsNavItem, projectsNavItem]
+  },
+  {
+    label: "Investigate",
+    items: [sessionsNavItem, insightsNavItem, queryNavItem, repairNavItem]
+  },
+  {
+    label: "Maintain",
+    items: [
+      pricingNavItem,
+      diagnosticsNavItem,
+      discoveryNavItem,
+      parsersNavItem,
+      rawDataNavItem,
+      settingsNavItem
+    ]
+  }
 ];
 
 const supportNavItems = [
   { href: "/guide", label: "Guide", icon: BookOpen }
 ];
 
+const primaryNavItems = navSections.flatMap((section) => section.items);
+const sidebarSections = [
+  ...navSections.map((section) => ({ ...section, variant: "default" as const })),
+  { label: "Reference", items: supportNavItems, variant: "support" as const }
+];
+
 const priorityMobileItems = primaryNavItems.filter((item) =>
   ["/", "/sessions", "/repair", "/diagnostics", "/settings"].includes(item.href)
 );
@@ -76,7 +100,7 @@ function NavLink({
     : cn(
         "flex items-center gap-3 rounded-md px-3 py-2 text-sm transition-colors",
         isActive
-          ? "bg-primary/10 font-medium text-primary"
+          ? "bg-muted font-medium text-primary shadow-xs ring-1 ring-border/60"
           : variant === "support"
             ? "border bg-muted/40 font-medium text-foreground hover:bg-muted"
             : "text-muted-foreground hover:bg-muted hover:text-foreground"
@@ -140,17 +164,29 @@ export function Sidebar({ appVersion = getAppVersion() }: { appVersion?: string
             </div>
           </div>
         </div>
-        <nav aria-label="Primary navigation" className="flex-1 space-y-1 overflow-y-auto p-3">
-          {primaryNavItems.map((item) => (
-            <NavLink key={item.href} item={item} isActive={isActiveRoute(pathname, item.href)} />
-          ))}
-        </nav>
-        <nav aria-label="Help navigation" className="p-3">
-          {supportNavItems.map((item) => (
-            <NavLink key={item.href} item={item} variant="support" isActive={isActiveRoute(pathname, item.href)} />
-          ))}
+        <nav aria-label="Primary navigation" className="flex-1 overflow-y-auto p-3">
+          <div className="space-y-4">
+            {sidebarSections.map((section) => (
+              <section key={section.label} aria-label={`${section.label} navigation`} className="space-y-1">
+                <div className="px-3 pb-1 text-[0.68rem] font-semibold uppercase leading-none tracking-normal text-muted-foreground">
+                  {section.label}
+                </div>
+                {section.items.map((item) => (
+                  <NavLink
+                    key={item.href}
+                    item={item}
+                    variant={section.variant}
+                    isActive={isActiveRoute(pathname, item.href)}
+                  />
+                ))}
+              </section>
+            ))}
+          </div>
         </nav>
         <div className="border-t p-4 text-xs text-muted-foreground">
+          <div className="mb-2 text-[0.68rem] font-semibold uppercase leading-none tracking-normal text-muted-foreground">
+            Local processing
+          </div>
           <div className="flex flex-wrap items-center gap-x-2 gap-y-1 leading-relaxed">
             <span className="font-medium text-foreground">{formatAppVersion(appVersion)}</span>
             <span aria-hidden="true">·</span>

package/dist/cli/main.mjs

@@ -82,6 +82,9 @@ Usage:
   tokentrace mcp          Start the local stdio MCP server
   tokentrace mcp selftest --json
                           Verify the local MCP entrypoint without scanning files
+  tokentrace chatgpt-app  Start the private ChatGPT app prototype
+  tokentrace chatgpt-app selftest --json
+                          Verify the ChatGPT app prototype without scanning files
   tokentrace scan         Scan local AI CLI usage logs
   tokentrace doctor --json
                           Inspect scan health and repair recommendations
@@ -458,6 +461,9 @@ async function mcp(context, args) {
   }
   await runNodeScript(context, "mcp", [], { env: process.env });
 }
+async function chatGptApp(context, args) {
+  await runNodeScript(context, "chatgpt-app", args, { env: process.env });
+}
 async function doctor(context, args) {
   if (await printScriptHelp(context, "doctor", args)) return;
   await initializeDatabase(context, { quiet: true, refreshPrices: false });
@@ -651,6 +657,10 @@ async function runCliCommand(context, rawArgs = process.argv.slice(2)) {
     await mcp(context, args);
     return;
   }
+  if (command === "chatgpt-app") {
+    await chatGptApp(context, args);
+    return;
+  }
   if (command === "scan") {
     await scan(context, args);
     return;

package/dist/runtime/agent.mjs

@@ -4006,7 +4006,7 @@ var product = {
   name: "TokenTrace",
   packageName: "tokentrace",
   description: "Local-first dashboard and CLI for AI coding-agent token, cost, session, and parser analytics.",
-  homepage: "https://www.abhiyoheswaran.com/apps/tokentrace",
+  homepage: "https://www.baseframelabs.com/apps/tokentrace",
   repository: "https://github.com/abhiyoheswaran1/tokentrace"
 };
 var commands = [
@@ -4143,6 +4143,27 @@ var commands = [
       "The run_scan MCP tool requires confirmLocalScan=true before reading local usage files and writing the local database."
     ]
   },
+  {
+    id: "chatgpt-app",
+    title: "Start private ChatGPT app prototype",
+    command: ["tokentrace", "chatgpt-app"],
+    description: "Start a local HTTP MCP Apps server for ChatGPT developer-mode testing. It exposes one read-only redacted evidence-pack tool and widget.",
+    output: "terminal",
+    mutatesLocalState: false,
+    startsLongRunningProcess: true,
+    requiresNetwork: false,
+    safeForAutomation: false,
+    useWhen: "The human wants to test TokenTrace as a private ChatGPT connector without publishing a public app.",
+    followUps: [
+      ["tokentrace", "chatgpt-app", "selftest", "--json"],
+      ["tokentrace", "chatgpt-app", "--port", "8787", "--hostname", "127.0.0.1"]
+    ],
+    notes: [
+      "ChatGPT developer mode requires exposing the local /mcp endpoint through an HTTPS tunnel.",
+      "The prototype does not scan files on startup and returns only redacted evidence packs.",
+      "See docs/CHATGPT_APP_PROTOTYPE.md for connector setup steps."
+    ]
+  },
   {
     id: "status",
     title: "Print local live usage status",
@@ -4373,6 +4394,15 @@ function buildAgentDiscoveryManifest(options = {}) {
         steps: [
           ["tokentrace", "watch", "--session", "--compact"]
         ]
+      },
+      {
+        id: "chatgpt-app-prototype",
+        title: "Private ChatGPT app prototype",
+        goal: "Start the local Apps SDK prototype and expose a redacted evidence-pack connector for developer-mode testing.",
+        steps: [
+          ["tokentrace", "chatgpt-app", "selftest", "--json"],
+          ["tokentrace", "chatgpt-app", "--port", "8787", "--hostname", "127.0.0.1"]
+        ]
       }
     ],
     integrations: {