tokentrace 0.8.4 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 All notable changes to TokenTrace are documented here.
 
+## Unreleased
+
+## [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
+
+- Session Timeline pages for inspecting one imported CLI session as ordered interactions, model changes, token spikes, cache activity, tool calls, parser confidence, and unknown-cost events without exposing raw message bodies.
+- Saved Local Views on Sessions, with built-in local filters for unknown cost, high-cost sessions, Claude/Codex this month, estimated tokens, guardrail review, and parser review, plus user-created SQLite-backed views.
+- `tokentrace digest --since <last-scan|yesterday|YYYY-MM-DD>` for scoped local usage digests.
+- `tokentrace report --markdown` and `tokentrace review --json` for deterministic local summaries covering digest data, post-session movement, accounting state, parser warnings, and expensive sessions.
+- Overview Post-Session Review panel showing latest scan movement, unknown costs, parser follow-up, guardrail state, and expensive sessions.
+- Accounting invariant checks that verify processed tokens balance against fresh input, output, reasoning, and cache buckets.
+
+### Changed
+
+- Claude status line output now includes context-window usage when Claude provides it and distinguishes priced sessions from pricing-repair states.
+- Overview Data Readiness now includes token-bucket balance and keeps readiness tiles readable at normal desktop widths.
+
 ## [0.8.4] - 2026-05-13
 
 ### Changed

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

@@ -34,6 +34,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 0.10.0 release implementation status
 tokentrace scan         # Scan local AI CLI usage logs
 tokentrace doctor --json
                         # Inspect scan health and repair recommendations
@@ -43,6 +48,12 @@ tokentrace repair --json
                         # Print unknown-cost repair groups as JSON
 tokentrace digest --json
                         # Print current-month local usage digest
+tokentrace digest --since yesterday
+                        # Print a scoped local usage digest
+tokentrace report --markdown
+                        # Print a deterministic Markdown report
+tokentrace review --json
+                        # Print post-session scan and review movement
 tokentrace insights --json
                         # Print local recommendations as JSON
 tokentrace status --json
@@ -66,6 +77,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 0.10.0 release status is also machine-readable:
+
+```bash
+tokentrace roadmap --json
+curl http://127.0.0.1:3030/api/roadmap
+```
+
 ## Run From Source
 
 ```bash
@@ -92,6 +145,10 @@ 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 0.10.0 evidence gates and release status
 ```
 
 Release work uses internal milestone commits until the next public minor
@@ -139,6 +196,13 @@ 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.
 
+Sessions includes built-in and local saved views for recurring review paths:
+unknown cost, high-cost sessions, Claude/Codex this month, estimated tokens,
+guardrail review, and parser review. Open a session's **Timeline** link to see
+ordered interactions, model changes, token spikes, cache activity, tool calls,
+parser confidence, and unknown-cost events. Raw prompts and message bodies stay
+hidden by default.
+
 ## Ingestion Architecture
 
 TokenTrace's primary ingestion architecture is direct local filesystem ingestion:
@@ -188,6 +252,10 @@ 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 | 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.
 
 ![TokenTrace Claude Code status line](docs/assets/claude-statusline.svg)
@@ -199,6 +267,15 @@ tokentrace status --json
 tokentrace watch --session
 ```
 
+Daily reporting commands stay deterministic and local:
+
+```bash
+tokentrace digest --since last-scan
+tokentrace digest --since 2026-05-01 --json
+tokentrace report --markdown --since yesterday
+tokentrace review --json
+```
+
 Codex CLI status-line integration is intentionally deferred until its status-line and hook contracts are stable enough to support without fragile terminal output parsing. Use `tokentrace watch --session --compact` in a terminal split or tmux pane as the current fallback. See [docs/CODEX_INTEGRATION_SPIKE.md](docs/CODEX_INTEGRATION_SPIKE.md) for the current decision.
 
 ## Screenshots

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/api/saved-views/[id]/route.ts

@@ -0,0 +1,16 @@
+import { NextResponse } from "next/server";
+import { deleteSavedView } from "@/src/lib/saved-views";
+
+export const dynamic = "force-dynamic";
+
+export async function DELETE(
+  _request: Request,
+  {
+    params
+  }: {
+    params: Promise<{ id: string }>;
+  }
+) {
+  const { id } = await params;
+  return NextResponse.json({ deleted: deleteSavedView(decodeURIComponent(id)) });
+}

package/app/api/saved-views/route.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from "next/server";
+import { readJsonObject } from "@/src/lib/api-json";
+import { getSavedViews, saveSavedView } from "@/src/lib/saved-views";
+
+export const dynamic = "force-dynamic";
+
+function object(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export async function GET() {
+  return NextResponse.json(getSavedViews());
+}
+
+export async function POST(request: Request) {
+  const parsed = await readJsonObject(request);
+  if (!parsed.ok) {
+    return NextResponse.json({ error: parsed.error }, { status: 400 });
+  }
+
+  try {
+    const view = saveSavedView({
+      name: typeof parsed.body.name === "string" ? parsed.body.name : "",
+      filters: object(parsed.body.filters)
+    });
+    return NextResponse.json({ view });
+  } catch (error) {
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : "could not save view" },
+      { status: 400 }
+    );
+  }
+}