tokentrace 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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

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
@@ -72,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
@@ -98,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
@@ -202,7 +253,7 @@ tokentrace statusline claude
 Claude Code sends session JSON to the command on stdin. TokenTrace reads the transcript path, model, context usage, and session cost, then prints one compact local line:
 
 ```text
-TokenTrace | Opus | session 3.3K tokens | cache 2.0K | cost $0.1235 | ctx 7% | priced
+TokenTrace | Opus | ctx 7% | cost $0.1235 | processed 3.3K tokens | cache 2.0K | priced
 ```
 
 Do not set the Claude Code `statusLine.command` to plain `tokentrace`. Plain `tokentrace` starts the dashboard, while `tokentrace statusline claude` prints exactly one status-line response.

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"
+    }
+  });
+}