tokenjam 0.4.0__tar.gz → 0.4.2__tar.gz

tokenjam-0.4.2/.github/scripts/archive_traffic.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""
+Archive this repo's GitHub Traffic API data into traffic/<ISO-year>-W<week>.json.
+
+GitHub's Traffic API only retains the last 14 days, so this runs weekly (see
+.github/workflows/traffic-archive.yml) and commits a point-in-time snapshot —
+the longitudinal record the 14-day window can't otherwise provide.
+
+The output schema is fixed by the growth-instrumentation brief and consumed by
+the Cowork spreadsheet-fill job; keep it stable across releases.
+
+Auth: reads GITHUB_TOKEN + GITHUB_REPOSITORY from the environment (both provided
+automatically by GitHub Actions). The default workflow token works because the
+workflow grants `administration: read`, which the Traffic API requires.
+
+Failure mode: any API error raises and the process exits non-zero, so the run
+shows red in the Actions tab (the Cowork health check then alerts on the missing
+file). No-data weeks still write the file — its existence is the success signal.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+
+API_ROOT = "https://api.github.com"
+
+
+def _get(path: str, token: str):
+    """GET an api.github.com path and return parsed JSON. Raises on any error.
+
+    On an HTTP error, surface the status, GitHub's response message, and the
+    relevant rate-limit / SSO headers to stderr before re-raising — a bare
+    `HTTPError: 403 Forbidden` hides whether the cause is a missing token scope,
+    an unapproved fine-grained PAT, or SAML SSO authorization.
+    """
+    req = urllib.request.Request(
+        f"{API_ROOT}{path}",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "tokenjam-traffic-archive",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.load(resp)
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", "replace")[:600]
+        sso = exc.headers.get("X-GitHub-SSO")
+        remaining = exc.headers.get("X-RateLimit-Remaining")
+        print(
+            f"error: GET {path} -> HTTP {exc.code} {exc.reason}\n"
+            f"  body: {body}\n"
+            f"  x-github-sso: {sso}  x-ratelimit-remaining: {remaining}",
+            file=sys.stderr,
+        )
+        raise
+
+
+def _daily(payload: dict, key: str) -> list[dict]:
+    """Normalize the views/clones inner array (keyed 'views'/'clones') to 'daily'."""
+    return [
+        {"timestamp": d["timestamp"], "count": d["count"], "uniques": d["uniques"]}
+        for d in payload.get(key, [])
+    ]
+
+
+def build_record(views: dict, clones: dict, referrers: list, paths: list,
+                 repo: str, now: datetime) -> dict:
+    """Assemble the combined archive record matching the fixed brief schema."""
+    iso_year, iso_week, _ = now.isocalendar()
+    iso_week_str = f"{iso_year}-W{iso_week:02d}"
+    return {
+        "archived_at": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "iso_week": iso_week_str,
+        "repo": repo,
+        "views": {
+            "count": views.get("count", 0),
+            "uniques": views.get("uniques", 0),
+            "daily": _daily(views, "views"),
+        },
+        "clones": {
+            "count": clones.get("count", 0),
+            "uniques": clones.get("uniques", 0),
+            "daily": _daily(clones, "clones"),
+        },
+        "referrers": [
+            {"referrer": r["referrer"], "count": r["count"], "uniques": r["uniques"]}
+            for r in (referrers or [])
+        ],
+        "paths": [
+            {"path": p["path"], "title": p.get("title", ""),
+             "count": p["count"], "uniques": p["uniques"]}
+            for p in (paths or [])
+        ],
+    }
+
+
+def main() -> int:
+    token = os.environ.get("GITHUB_TOKEN")
+    repo = os.environ.get("GITHUB_REPOSITORY")  # "owner/name"
+    if not token or not repo:
+        print("error: GITHUB_TOKEN and GITHUB_REPOSITORY must be set", file=sys.stderr)
+        return 1
+
+    views = _get(f"/repos/{repo}/traffic/views", token)
+    clones = _get(f"/repos/{repo}/traffic/clones", token)
+    referrers = _get(f"/repos/{repo}/traffic/popular/referrers", token)
+    paths = _get(f"/repos/{repo}/traffic/popular/paths", token)
+
+    now = datetime.now(timezone.utc)
+    record = build_record(views, clones, referrers, paths, repo, now)
+    iso_week_str = record["iso_week"]
+
+    out_dir = Path("traffic")
+    out_dir.mkdir(exist_ok=True)
+    out_path = out_dir / f"{iso_week_str}.json"
+    # Overwrite is intentional: a week's archive is a point-in-time snapshot, so
+    # a manual re-run or late-firing schedule just refreshes it (idempotent).
+    out_path.write_text(json.dumps(record, indent=2) + "\n", encoding="utf-8")
+
+    print(
+        f"wrote {out_path} (views={record['views']['count']}, "
+        f"clones={record['clones']['count']}, "
+        f"referrers={len(record['referrers'])}, paths={len(record['paths'])})"
+    )
+
+    # Expose the ISO week to the workflow for the commit message.
+    gh_output = os.environ.get("GITHUB_OUTPUT")
+    if gh_output:
+        with open(gh_output, "a", encoding="utf-8") as fh:
+            fh.write(f"iso_week={iso_week_str}\n")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tokenjam-0.4.2/.github/workflows/traffic-archive.yml

@@ -0,0 +1,72 @@
+name: traffic-archive
+
+# Weekly snapshot of the GitHub Traffic API (which only retains 14 days),
+# committed as traffic/<year>-W<week>.json onto the data-only `traffic-data`
+# branch (NOT main — main is protected and blocks automated direct pushes).
+# See growth/README.md for the schema and how to read the archive.
+on:
+  schedule:
+    - cron: '0 12 * * 0'   # Sundays at 12:00 UTC
+  workflow_dispatch:        # manual trigger for backfill / testing
+
+permissions:
+  contents: write          # to commit the archive back to the branch
+
+jobs:
+  archive:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Archive traffic data
+        id: archive
+        env:
+          # The Traffic API requires Administration:Read, which the default
+          # GITHUB_TOKEN cannot be granted (there is no such permissions: key —
+          # a literal `administration` value is a workflow parse error, and the
+          # default token 403s on these endpoints). So this step authenticates
+          # with a PAT stored as the TRAFFIC_PAT repo secret.
+          #
+          # TRAFFIC_PAT must be a fine-grained PAT with:
+          #   - Resource owner = Metabuilder-Labs (the ORG, not a personal
+          #     account — otherwise it can't see this repo: 403 "Resource not
+          #     accessible by personal access token")
+          #   - Repository access = this repo
+          #   - Repository permissions -> Administration: Read (the one the
+          #     Traffic API needs; separate from Contents/Metadata)
+          # A classic PAT with the `repo` scope also works. The push step below
+          # uses the default GITHUB_TOKEN (not this PAT) since traffic-data is
+          # unprotected. See growth/README.md.
+          GITHUB_TOKEN: ${{ secrets.TRAFFIC_PAT }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+        run: python .github/scripts/archive_traffic.py
+
+      - name: Publish the archive to the traffic-data branch
+        env:
+          # The archive lands on the unprotected, data-only `traffic-data` branch,
+          # so the default GITHUB_TOKEN (contents: write) can push it — no PAT and
+          # no branch-protection bypass needed. The job runs from main (where the
+          # script lives), then publishes just the new JSON to traffic-data via a
+          # shallow clone so main's tree never leaks onto the data branch.
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          WEEK: ${{ steps.archive.outputs.iso_week }}
+        run: |
+          tmp="$(mktemp -d)"
+          git clone --quiet --depth 1 --branch traffic-data \
+            "https://x-access-token:${GH_TOKEN}@github.com/${GH_REPO}.git" "$tmp"
+          mkdir -p "$tmp/traffic"
+          cp "traffic/${WEEK}.json" "$tmp/traffic/${WEEK}.json"
+          git -C "$tmp" config user.name  "github-actions[bot]"
+          git -C "$tmp" config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git -C "$tmp" add traffic/
+          if git -C "$tmp" diff --cached --quiet; then
+            echo "No changes — archive already current for ${WEEK}."
+            exit 0
+          fi
+          git -C "$tmp" commit -m "chore(traffic): archive week ${WEEK}"
+          git -C "$tmp" push origin HEAD:traffic-data

{tokenjam-0.4.0 → tokenjam-0.4.2}/.gitignore

@@ -18,6 +18,7 @@ venv/
 # IDE
 .idea/
 .vscode/
+.cursor/debug-*.log
 *.swp
 *.swo
 

{tokenjam-0.4.0 → tokenjam-0.4.2}/CLAUDE.md

@@ -58,6 +58,86 @@ Symptom of a missed worktree: `git log` shows a commit on a branch you didn't in
 `.tj/config.toml` is intentionally untracked (see PR #145 + Critical Rule 20) and gets mutated at runtime by `tj onboard` / `tj serve` regenerating the local `ingest_secret`. Don't `git add` it back. The CI test `tests/unit/test_no_tracked_dev_secrets.py` guards against this.
 
 
+## PR and commit conventions (for any agent producing a PR)
+
+These conventions apply to any agent — feature work, bug fixes, docs, content. Briefs may add task-specific structure but should not contradict these.
+
+### Branch + PR titles
+
+- **Branch names** are slash-separated, kebab-case, prefixed by type:
+  - `fix/<issue-or-area>` — bug fixes (e.g. `fix/175-176-cost-framing-backfill-plan`)
+  - `feat/<area>` — new features (e.g. `feat/reuse-analyzer-115`)
+  - `docs/<area>` — documentation (e.g. `docs/readme-cleanup-v0.4.1`)
+  - `chore/<area>` — refactors, renames, infra
+  - `release/<X.Y.Z>` — release-cut PRs
+- **PR titles** lead with the verb / type and reference issues by number when applicable:
+  - `Fix #175, #176: tj cost framing + backfill plan_tier propagation (v0.4.2)` (bug fixes)
+  - `[feature] Add Reuse analyzer (#115)` (features)
+  - `docs: drop stale CHANGELOG.md + add maintainer contact` (docs)
+  - `Bump version to 0.4.1` (release-cut PRs — keep these terse)
+- Use **`Closes #N`** in the PR body (not just title) when fixing an issue, so GitHub auto-closes the issue on merge. Multiple `Closes` lines if you're closing several. Do not use the comma form `Closes #1, #2` — GitHub only catches the first; use separate lines.
+
+### Commit messages
+
+- **Subject line** (first line, ≤72 chars): one-line summary in active voice. Reference issues with `#N` when applicable.
+- **Body** (after blank line): explain *why* the change is needed, not *what* it changes (the diff shows that). Use full sentences, paragraphs, bullet lists.
+- **Trailers** (after another blank line, at the very end):
+  - Always include: `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>` (or the appropriate model identifier)
+  - When fixing an externally-reported bug: also include `Co-Authored-By: <reporter-handle> <noreply@github.com>` (e.g. `ashwmu` for the external contributor's reports)
+- Use **HEREDOC for multi-line messages** to preserve formatting: `git commit -m "$(cat <<'EOF' ... EOF)"`
+
+### PR body structure
+
+```markdown
+[1-2 sentence framing of why this exists]
+
+## Summary
+- [bullet — what changed at a high level]
+- [bullet — another high-level change]
+
+## [Per-issue or per-feature section, repeated as needed]
+[Detail per issue, including the symptom, root cause, fix]
+
+## Tests / Verification
+- [test files added or modified, what they cover]
+- [any live verification: workflow run URL, screenshot, command output]
+
+## What's NOT in this PR (if scope was deliberately limited)
+- [out-of-scope item 1 — explain why deferred]
+- [out-of-scope item 2]
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: <reporter-handle> <noreply@github.com>   # if applicable
+```
+
+The "What's NOT in this PR" section is load-bearing — it makes the reviewer's job 10x easier when the agent explicitly named what they decided to defer. Use it whenever scope is non-obvious.
+
+### Self-review checklist before requesting review
+
+Run through this before pushing the PR:
+
+1. **Tests pass locally.** `pytest tests/unit/ tests/integration/` (or `tests/unit/<file>.py` if narrow).
+2. **`ruff check tokenjam/` and `mypy tokenjam/` clean** for any files you touched.
+3. **CI on the branch is green** for at least the test-ts job (Python jobs may still be running when you push).
+4. **Acceptance criteria from the issue are met** — go through them one by one and verify.
+5. **No accidental files in the diff** — `.tj/config.toml`, `.tj-test-data/`, screenshots that were just for debugging, etc.
+6. **PR body explains the WHY** — symptom + root cause + fix, not just "fixes the bug."
+7. **Honesty discipline preserved.** If the change touches any user-facing string ("recoverable," "estimated," "savings"), verify it matches existing analyzer caveat language. Never silently strengthen claims.
+
+### Scope discipline
+
+- **Do what the brief / issue says, no more.** If you notice an adjacent issue, file it as a separate issue rather than expanding the PR. Reviewers should never have to mentally separate "the fix" from "drive-by cleanup."
+- **Exception:** when an adjacent change is functionally required to make the primary fix work (e.g., updating a caller of a function you changed). Note it explicitly in the PR body under "What's also in this PR."
+- **When in doubt about scope, ask the master agent before expanding.** A 30-second clarification beats a 30-minute scope review.
+
+### Worker vs master
+
+- **Worker agents do not merge their own PRs.** Open the PR, request review, the master + Anil handle merge.
+- **Worker agents do not file follow-up issues unprompted.** If you notice something during your work that's out of scope, mention it in the PR body and let the master decide whether to file.
+- **Worker agents do not bump versions.** Release-cut PRs are a separate concern handled by the master / Anil.
+
+
 ## Architecture
 
 ### Data Flow
@@ -91,16 +171,17 @@ Post-ingest hooks run synchronously after each span is written to DB:
   - `cache_efficacy.py` → `@register("cache")` — current cache-read efficacy per (provider, model)
   - `cache_recommend.py` → `@register("cache-recommend")` — Anthropic-only structural prefix detection for `cache_control` placement
   - `workflow_restructure.py` → `@register("script")` — `(tool_name, arg_shape)` cluster detection for deterministic-script candidates
+  - `plan_reuse.py` → `@register("reuse")` — repeated-planning cluster detection; a savings analyzer (carries `estimated_recoverable_usd`). Has a dedicated endpoint/report path (`GET /api/v1/reuse/clusters`, `tj report --reuse`) because its per-cluster planner text can be many KB — see the routes/report bullets below
   - `prompt_bloat.py` → `@register("trim")` — LLMLingua-2 token-significance classification (requires `tokenjam[bloat]` extra)
   Analyzers receive an `AnalyzerContext` and operate on `db.conn` directly. To add a new analyzer: drop a file under `analyzers/`, decorate with `@register("name")`, append to `ANALYZER_ORDER` if ordering matters — `cmd_optimize`'s positional `findings` Click choices auto-derive from the registry.
   **Recoverable-savings contract** (issues #111/#122): every *savings* analyzer's result dataclass carries `estimated_recoverable_usd` / `estimated_recoverable_tokens` / `estimate_basis` / `estimate_confidence` (`"heuristic"`). All four are on **one time basis — recoverable over the analyzed window** (`downsize` keeps a separate `monthly_savings_usd` for its CLI projection line, but `estimated_recoverable_usd` is the window figure so Overview tiles are comparable). `cache-recommend` and `budget-projection` deliberately carry **no** recoverable field (not savings analyzers); the Overview waste band is registry-driven off the presence of `estimated_recoverable_usd`, so a future analyzer (e.g. reuse) appears with no UI change. `report_to_dict`/`report_from_dict` round-trip these fields. Honesty discipline (Critical Rule 14) is mandatory — every estimate is "estimated recoverable", never "saves you".
 - **`tokenjam/core/ingest_adapters/`**: Third-party trace-export adapters that normalize external payloads (`langfuse.py`, `helicone.py`, `otlp.py`) into `NormalizedSpan` for ingest. Each is reachable as a `tj backfill <name>` subcommand and accepts `--source-url` (live API) or `--source-file` (offline JSON dump). Adapters write deterministic span IDs derived from the source's identifiers so re-runs are idempotent. `otlp.py` shares span-mapping logic with the live `POST /api/v1/spans` route via `tokenjam/otel/otlp_parsing.py`.
 - **`tokenjam/core/export/`**: Routing-config snippet generators for `tj optimize --export-config`. Currently `claude_code.py` emits a JSONC fragment under a `tokenjam.routing_recommendations` namespace with honest-framing caveat comments baked in. Writes to `~/.config/tokenjam/exports/`; never touches `~/.claude/settings.json` or other external configs (no `--apply` flag — Claude Code doesn't currently honor TokenJam routing keys, so auto-writing would change nothing and erode trust).
-- **`tokenjam/core/backfill.py`**: Parses Claude Code on-disk session JSONL files into `NormalizedSpan`s. Cost is recomputed from `pricing/models.toml` because the on-disk format has no `cost_usd`. The parser tolerates the dated `claude-<family>-<ver>-YYYYMMDD` model-name suffixes Anthropic ships (handled by `core/pricing.py.get_rates()`, which strips the trailing 8-digit date suffix when no exact pricing match exists). Idempotency relies on deterministic span IDs derived from `(session_id, message uuid)` / `(session_id, tool_use id)`.
+- **`tokenjam/core/backfill.py`**: Parses Claude Code on-disk session JSONL files into `NormalizedSpan`s. Cost is recomputed from `pricing/models.toml` because the on-disk format has no `cost_usd`. The parser tolerates the dated `claude-<family>-<ver>-YYYYMMDD` model-name suffixes Anthropic ships (handled by `core/pricing.py.get_rates()`, which strips the trailing 8-digit date suffix when no exact pricing match exists). Idempotency relies on deterministic span IDs derived from `(session_id, message uuid)` / `(session_id, tool_use id)`. **Plan tier:** `ingest_claude_code(db, …, config=…)` resolves `plan_tier` from `config.budgets["anthropic"].plan` (Claude Code is always Anthropic) and stamps it on each `SessionRecord` — mirroring the live `IngestPipeline._resolve_plan_tier` so backfilled sessions aren't all `"unknown"` (#176). Pass `config` from callers (`cmd_backfill`, `tj onboard`). The Langfuse/Helicone/OTLP adapters create **no** `SessionRecord` (spans only), so there's no plan tier to propagate there.
 - **`tokenjam/core/schema_validator.py`**: Validates tool outputs against declared or genson-inferred JSON Schema. Only fires on `gen_ai.tool.call` spans with `gen_ai.tool.output` in attributes. Schema priority: 1) declared file from agent config `output_schema`, 2) inferred schema from `DriftBaseline.output_schema_inferred`. Caches schemas in-memory per agent.
 - **`tokenjam/core/models.py`**: All domain dataclasses — `NormalizedSpan`, `SessionRecord`, `Alert`, `DriftBaseline`, filter types, etc. `NormalizedSpan` carries `billing_account` (provider-only: `anthropic` / `openai` / `google` / `bedrock` / `local.ollama`). `SessionRecord` carries `plan_tier` (api / pro / max_5x / max_20x / plus / team / enterprise / local / unknown) plus a derived `pricing_mode` property (`local` / `subscription` / `api` / `unknown`). Spans inherit plan via the session FK — analyzers JOIN through `SessionRecord` when they need plan context. See [`docs/architecture.md`](docs/architecture.md) → "OTel semconv extensions" for the full derivation rules.
 - **`tokenjam/core/config.py`**: `TjConfig` dataclass tree, TOML loading/writing, config file discovery. `ProviderBudget` carries an optional `plan` field (set by `tj onboard`'s plan-tier prompt) that `IngestPipeline._build_or_update_session` reads to populate `SessionRecord.plan_tier` at session creation. `CaptureConfig` has four fine-grained content-capture toggles (`prompts` / `completions` / `tool_inputs` / `tool_outputs`); `strip_captured_content()` in `core/ingest.py` enforces them at the single ingest-pipeline gate.
-- **`tokenjam/core/framing.py`**: **Single source of truth for plan-tier-aware rendering** (issue #110). `compute_framing(config, window_summary, by_provider_breakdown) -> Framing` decides whether dollar figures are shown verbatim (`api`), suppressed for token-share framing (`subscription`), shown as tokens-only (`local`), or shown with an "may overstate" qualifier (`unknown`). Plus `render_dollar()` / `render_savings()` (UI-facing compact formatters), and the shared helpers `pricing_mode_for` / `dominant_plan` / `config_declared_plan` (with the #106 global-config fallback) / `plan_tier_mix`. **Consumed by both the CLI (`cmd_optimize`, `cmd_tokenmaxx`) and the REST API** (which emits `Framing.to_dict()` as the `framing` block) — neither re-derives the rules. This module *reads* plan-tier/pricing-mode; the canonical derivation still lives on `SessionRecord.pricing_mode` + `SUBSCRIPTION_PLAN_TIERS` (semconv). When adding a dollar-bearing surface, consume this — do not re-implement the suppression rules.
+- **`tokenjam/core/framing.py`**: **Single source of truth for plan-tier-aware rendering** (issue #110). `compute_framing(config, window_summary, by_provider_breakdown) -> Framing` decides whether dollar figures are shown verbatim (`api`), suppressed for token-share framing (`subscription`), shown as tokens-only (`local`), or shown with an "may overstate" qualifier (`unknown`). Plus `render_dollar()` / `render_savings()` (UI-facing compact formatters), and the shared helpers `pricing_mode_for` / `dominant_plan` / `config_declared_plan` (with the #106 global-config fallback) / `plan_tier_mix`. **Consumed by both the CLI (`cmd_optimize`, `cmd_tokenmaxx`, `cmd_cost` — both the `--compare` diff and the bare cost table, #175) and the REST API** (which emits `Framing.to_dict()` as the `framing` block) — neither re-derives the rules. The bare `tj cost` table renders COST cells via `render_dollar()` (subscription → "% of cycle", local → "—", api/unknown → `format_cost`) with the qualifier surfaced above; under the daemon it reuses the `framing` block from `/api/v1/cost` via `ApiBackend.fetch_cost_framing`. This module *reads* plan-tier/pricing-mode; the canonical derivation still lives on `SessionRecord.pricing_mode` + `SUBSCRIPTION_PLAN_TIERS` (semconv). When adding a dollar-bearing surface, consume this — do not re-implement the suppression rules.
 - **`tokenjam/sdk/agent.py`**: `@watch()` decorator creates session spans only. `record_llm_call()` and `record_tool_call()` create child spans for manual instrumentation. LLM call spans from provider clients require `patch_anthropic()`, `patch_openai()`, etc.
 - **`tokenjam/sdk/transport.py`**: `HttpTransport` — buffers up to 1000 spans, retries with exponential backoff (3 attempts, 2s base). Used when `tj serve` runs as a separate process.
 - **`tokenjam/sdk/bootstrap.py`**: `ensure_initialised()` — lazy, thread-safe, idempotent bootstrap of config -> DB -> IngestPipeline -> TracerProvider. Called automatically by `@watch()` and all `patch_*()` functions. Registers atexit flush.
@@ -112,7 +193,7 @@ Post-ingest hooks run synchronously after each span is written to DB:
 - **`tokenjam/api/app.py`**: FastAPI app factory (OpenAPI title `"TokenJam Lens"`). `tj serve` starts it with uvicorn. Accepts `db`, `config`, `ingest_pipeline` for testability. Registers all routers under `/api/v1` plus `/metrics`, `/health`, and the SPA at `/`. **`index.html` is read into a module string once at `create_app()` time** (`_index_html`) — so editing `tokenjam/ui/index.html` requires a `tj serve` restart to take effect; tests read the file from disk directly and aren't affected. Mounts `/ui/vendor` as `StaticFiles`.
 - **`tokenjam/api/middleware.py`**: `IngestAuthMiddleware` — protects `POST /api/v1/spans` with Bearer token. Returns `JSONResponse(401)` directly (not `HTTPException`, which doesn't propagate from `BaseHTTPMiddleware.dispatch`).
 - **`tokenjam/api/deps.py`**: `require_api_key` — FastAPI dependency for optional API key auth on GET endpoints. Only enforced when `api.auth.enabled = true` in config.
-- **`tokenjam/api/routes/`**: One file per resource — `spans.py` (OTLP JSON ingest), `traces.py`, `cost.py`, `cost_compare.py`, `tools.py`, `alerts.py`, `drift.py`, `optimize.py`, `budget.py`, `status.py`, `agents.py`, `metrics.py` (Prometheus text format from DB queries), `version.py` (unauthenticated `GET /health` → `{"status":"ok","version":...}` mounted with no prefix, plus `GET /api/v1/version`; the version is derived at runtime via `importlib.metadata.version("tokenjam")` — no hardcoded literal). **The dollar-bearing read routes (`/cost`, `/cost/compare`, `/optimize`, `/budget`) each return a `framing` block** (see `core/framing.py`) so the web UI renders plan-tier-aware figures without re-deriving the rules in JS. `/optimize` takes `?fast=true` to skip the expensive Trim analyzer (returns `skipped_analyzers`) for the polling Overview; `/cost` returns a window-bucketed `series` for the chart (see Web UI below). **Concurrency caveat:** the sync (`def`) read routes run in Starlette's threadpool and share the daemon's single DuckDB connection, which is not safe for concurrent use — fan-out callers (the Overview) must fetch sequentially. See issue #124.
+- **`tokenjam/api/routes/`**: One file per resource — `spans.py` (OTLP JSON ingest), `traces.py`, `cost.py`, `cost_compare.py`, `tools.py`, `alerts.py`, `drift.py`, `optimize.py`, `reuse.py` (`GET /api/v1/reuse/clusters` — the Reuse finding plus skeleton-rendering extras `planning_texts` + `pricing_mode`; a dedicated endpoint (not bolted onto `/optimize`) so the per-cluster planner text, which can be many KB, isn't paid for on every Overview poll — #154), `budget.py`, `status.py`, `agents.py`, `metrics.py` (Prometheus text format from DB queries), `version.py` (unauthenticated `GET /health` → `{"status":"ok","version":...}` mounted with no prefix, plus `GET /api/v1/version`; the version is derived at runtime via `importlib.metadata.version("tokenjam")` — no hardcoded literal). **The dollar-bearing read routes (`/cost`, `/cost/compare`, `/optimize`, `/budget`) each return a `framing` block** (see `core/framing.py`) so the web UI renders plan-tier-aware figures without re-deriving the rules in JS. `/optimize` takes `?fast=true` to skip the expensive Trim analyzer (returns `skipped_analyzers`) for the polling Overview; `/cost` returns a window-bucketed `series` for the chart (see Web UI below). **Concurrency:** the sync (`def`) read routes (`/optimize`, `/cost/compare`) run in Starlette's threadpool, so concurrent requests reach the DB from multiple threads. `DuckDBBackend.conn` is a **per-thread DuckDB cursor** (`threading.local`) over one shared database — cursors are independent connections safe for concurrent use, so fan-out callers (the Overview) can fetch in parallel. Fixed in #124 (was a single shared connection that aborted under concurrent access); do not collapse `conn` back to one shared connection object.
 - **`tokenjam/mcp/server.py`**: FastMCP stdio server exposing observability data to Claude Code. Uses either a read-only DuckDB connection or HTTP proxy to `tj serve`. Initialized via `init()` from `cmd_mcp.py`.
 - **`tokenjam/cli/main.py`**: Root Click group with global options (`--config`, `--json`, `--no-color`, `--db`, `--agent`, `-v`). Registers all subcommands.
 
@@ -122,12 +203,12 @@ Post-ingest hooks run synchronously after each span is written to DB:
 
 - **`tj demo [scenario]`** (`cmd_demo.py`) — runs Agent Incident Library scenarios (zero-config, no API keys). `tj demo` lists all; `tj demo retry-loop` runs one.
 - **`tj doctor`** (`cmd_doctor.py`) — health checks (config, DB, secrets, webhooks, drift readiness, schema-vs-capture consistency). Exit 0 = ok, 1 = warnings, 2 = errors.
-- **`tj optimize`** (`cmd_optimize.py`) — six analyzers, registry-driven. **Analyzers are positional args** (not `--finding <name>`): `tj optimize downsize cache trim` runs three; bare `tj optimize` runs all. Registered names: `downsize`, `cache`, `cache-recommend`, `script`, `trim`, `budget-projection`. Flags: `--since 30d`, `--budget <provider>`, `--budget-usd <amount>`, `--compare <period>` (window-cost diff vs prior period; accepts `previous` / `last-week` / `last-month` / `last-7d` / `last-30d` / `YYYY-MM-DD:YYYY-MM-DD`), `--export-config <target>` (writes a routing snippet — currently `claude-code` — under `~/.config/tokenjam/exports/`; no `--apply` flag by design). Plan-tier-aware rendering: subscription users see "implied API value" framing and token-share savings (never dollar "spend"); local users see token-only framing; unknown-plan users see dollar figures suppressed with a `tj onboard --reconfigure` hint. Works alongside a running `tj serve` via the `/api/v1/optimize` HTTP fallback when the DuckDB write lock is held by the daemon.
+- **`tj optimize`** (`cmd_optimize.py`) — seven analyzers, registry-driven. **Analyzers are positional args** (not `--finding <name>`): `tj optimize downsize cache trim` runs three; bare `tj optimize` runs all. Registered names: `downsize`, `cache`, `cache-recommend`, `script`, `reuse`, `trim`, `budget-projection`. Flags: `--since 30d`, `--budget <provider>`, `--budget-usd <amount>`, `--compare <period>` (window-cost diff vs prior period; accepts `previous` / `last-week` / `last-month` / `last-7d` / `last-30d` / `YYYY-MM-DD:YYYY-MM-DD`), `--export-config <target>` (writes a routing snippet — currently `claude-code` — under `~/.config/tokenjam/exports/`; no `--apply` flag by design). Plan-tier-aware rendering: subscription users see "implied API value" framing and token-share savings (never dollar "spend"); local users see token-only framing; unknown-plan users see dollar figures suppressed with a `tj onboard --reconfigure` hint. Works alongside a running `tj serve` via the `/api/v1/optimize` HTTP fallback when the DuckDB write lock is held by the daemon.
 - **`tj tokenmaxx`** (`cmd_tokenmaxx.py`) — shareable spend-tier command. Reads last 30 days of usage, classifies into a 6-tier ladder (Sipper / Moderator / Maxxer / SuperMaxxer / MegaMaxxer / GigaMaxxer) using the multiplier vs the user's declared subscription plan as the primary classifier, with absolute USD/mo thresholds as the API-user fallback. Output is a bordered Panel designed for screenshotting. Plan-aware: shows the multiplier line only when the user has `[budget.<provider>] plan = "max_5x"` (or pro / max_20x / plus) configured — the declared-plan lookup uses `core/framing.config_declared_plan`, which falls back to the global `~/.config/tj/config.toml` when the active project config has no `[budget]` section (issue #106). The companion landing page is `tokenjam.dev/tokenmaxxing`. Designed to never exit without an actionable next step — pairs the tier callout with the downsize savings figure inline.
 - **`tj cost`** (`cmd_cost.py`) — cost breakdown by `--group-by agent|model|day|tool`. Same `--compare <period>` flag as `tj optimize` for window-over-window diffs (▲/▼ indicators, per-agent and per-model top-shifts, dollar + token deltas).
 - **`tj backfill <source>`** (`cmd_backfill.py`) — ingest historical telemetry from external sources. Subcommands: `claude-code` (parses `~/.claude/projects/*.jsonl`, auto-invoked at the end of `tj onboard --claude-code`), `langfuse` (live API or JSON dump), `helicone` (live API or JSON dump), `otlp` (raw OTLP JSON via URL or file — reuses the same parser as the live `POST /api/v1/spans` route). All idempotent via deterministic span IDs.
 - **`tj onboard`** (`cmd_onboard.py`) — `--claude-code` and `--codex` flags trigger integration-specific flows (writing to the **global** config). All paths — including plain `tj onboard` — prompt for plan tier (api / pro / max_5x / max_20x for Anthropic; api / plus / team / enterprise for OpenAI) and write it to `[budget.<provider>] plan = "..."`; `--plan <tier>` sets it non-interactively (issue #4). The plain path is Claude-first: its interactive prompt offers the Anthropic tiers, and an OpenAI-only `--plan` (plus/team/enterprise) is routed to `[budget.openai]`. Supports `--reconfigure` to re-prompt against an existing config. Does NOT auto-write a default `usd = 200` cycle ceiling — subscription users get only the `plan` field; API users are explicitly asked whether they want a self-imposed ceiling.
-- **`tj report`** (`cmd_report.py`) — generates standalone HTML visualizations of analyzer findings. Currently `tj report --trim [<agent_id>]` renders the Trim analyzer's per-token significance (was `--bloat` pre-0.3.1, renamed alongside the analyzer's registry string). Writes to `~/.cache/tokenjam/reports/` (override via `TOKENJAM_REPORT_DIR`) and opens in the default browser.
+- **`tj report`** (`cmd_report.py`) — generates standalone HTML visualizations of analyzer findings. `tj report --trim [<agent_id>]` renders the Trim analyzer's per-token significance (was `--bloat` pre-0.3.1, renamed alongside the analyzer's registry string); `tj report --reuse [<agent_id>]` renders the Reuse analyzer's per-cluster planning skeleton (HTML + Markdown sidecars). Writes to `~/.cache/tokenjam/reports/` (override via `TOKENJAM_REPORT_DIR`) and opens in the default browser. `--reuse` works when the daemon holds the DB lock: like `tj optimize`, it dispatches to `ApiBackend.fetch_reuse_clusters` (`GET /api/v1/reuse/clusters`) and renders from the HTTP payload (`write_reuse_report(..., planning_texts=...)`) instead of a direct DB connection (#154). `--trim` remains DB-direct only.
 - **`tj policy list`** (`cmd_policy.py`) — read-only preview of the unified policy surface. Consolidates existing `[alerts]`, `[alerts.channels]`, `[defaults.budget]`, `[budget.<provider>]`, per-agent `budget`/`drift`/`sensitive_actions`/`output_schema`, and `[capture]` config into one table; each row carries its source TOML section. Supports `--json`. `tj policy add | edit | apply | remove | test` are intentionally absent this sprint — the unified config migration is next sprint's work. `policy` is in `no_db_commands` in `cli/main.py` so it doesn't open the DB. Rich source-section strings (`[budget.anthropic]`, `[[alerts.channels]]`) must be passed through `rich.markup.escape()` before rendering — otherwise Rich consumes them as style tags.
 
 All commands support `--json` for machine-readable output. Commands that query alerts use exit code 1 if active (unacknowledged, unsuppressed) alerts exist.
@@ -161,7 +242,7 @@ Integration tests use `httpx.AsyncClient` with `httpx.ASGITransport(app=app)` ag
 - **URL is the source of truth for filters:** state lives in the hash + query params (`#/cost?since=7d&group_by=model`); `getRoute()` parses it, `navigate()` writes it back omitting defaults. Window vocabulary matches the CLI (`1h`/`24h`/`7d`/`30d`/`90d` + `YYYY-MM-DD:YYYY-MM-DD`). The default landing route is Overview (empty hash → `getRoute()` returns `overview`; do **not** re-introduce a render-time `location.hash = ...` redirect — it raced the first render, issue #132).
 - **Charts:** `SpendChart` wraps uPlot, reads CSS custom properties (`--chart-1..5`) so it re-themes, and has a cursor tooltip. The spend chart spans the **full selected window** with zero-fill: `/api/v1/cost` returns a window-bucketed `series` (hourly buckets for ≤2-day windows, daily otherwise; epoch-second `bucket` keys) plus `series_bucket` + `window_start`/`window_end`, and the UI builds a continuous grid + pins the x-scale to the window (issues #133/#136).
 - **Run-rate** is a single linear figure projected to the end of the current calendar cycle (`daily_rate × days-remaining`), captioned "not a forecast". The forecasting boundary is deliberate: linear run-rate only — no EWMA, seasonality, or anomaly detection.
-- **Polling:** the Overview auto-refreshes every 30s only while the tab is visible (`document.visibilityState`) and **fetches its endpoints sequentially** (the daemon's single DuckDB connection isn't concurrency-safe — see the REST API caveat / #124). Detail screens refresh on user action.
+- **Polling:** the Overview auto-refreshes every 30s only while the tab is visible (`document.visibilityState`) and **fetches its endpoints in parallel** via `Promise.all` (the daemon DB layer is concurrency-safe since #124 — per-thread cursors). The error handling is deliberately asymmetric: `/cost` is load-bearing (no `.catch` — its failure surfaces the error state), while the other five panels each carry a `.catch` fallback so one failing panel renders empty rather than blanking the Overview. Don't unify them. Detail screens refresh on user action.
 - **Testing the UI (no JS runner in CI):** the Python `test` job can't run JS, so UI fixes are guarded by **static-grep regression tests** in `tests/unit/test_lens_ui_regression.py` (assert buggy patterns are *gone* and new helpers are present) plus `test_ui_offline.py`. When iterating locally, validate syntax with `node --check` on the extracted `<script type="module">` block, and verify visually by running `tj serve` (or a seeded `create_app` + uvicorn on an alt port) and screenshotting with headless Chrome — there is intentionally no Playwright/Cypress.
 
 ### Session Continuity
@@ -239,7 +320,18 @@ The Agent Incident Library at `incidents/` is separate: each scenario is a `scen
 
 Model pricing lives in `tokenjam/pricing/models.toml` (USD per million tokens) — the packaged file `core/pricing.py` loads via `PRICING_FILE = Path(__file__).parent.parent / "pricing" / "models.toml"`. There is no repo-root `pricing/` copy (it was moved into the package in v0.1.x so it ships in the wheel; editing a repo-root file would have no runtime effect). Structure: `[provider.model_name]` with `input_per_mtok`, `output_per_mtok`, and optional `cache_read_per_mtok`/`cache_write_per_mtok`. Unknown models fall back to default rates ($0.50/$2.00 per MTok) with a logged warning. The pricing table is LRU-cached at process startup — restart to pick up changes.
 
-Pricing is community-maintained: submit a PR editing `tokenjam/pricing/models.toml` when provider prices change. No code changes needed — the file is loaded at runtime.
+The packaged table is community-maintained: submit a PR editing `tokenjam/pricing/models.toml` when provider prices change. No code changes needed — the file is loaded at runtime.
+
+**Local user overrides (no PR needed)** — users correct or add rates *for their own install* via override layers that `core/pricing.py` merges over the packaged table. Two sources, two key forms (see `docs/configuration.md` → "Pricing overrides" for the user-facing version):
+
+- **Sources** (lowest priority first; later wins): the packaged `models.toml`, then a standalone file (`~/.config/tj/pricing.toml`, or `TJ_PRICING_FILE`), then a `[pricing]` section in the main config (`tj.toml`). The project-local config `[pricing]` wins over the global standalone file.
+- **Key forms** — told apart deterministically by section name in `_split_pricing_raw()` (the reserved `models` section vs everything-else-is-a-provider; no value-shape guessing, no ordering dependency):
+  - **Provider-keyed** (`[pricing.anthropic]` / `[anthropic]` whose values are model sub-tables) — merged per `(provider, model)` over the packaged table. This is the long-standing `[provider.model]` format.
+  - **Model-keyed** (the reserved `[pricing.models]` section in tj.toml, or `[models]` in the standalone file) — keyed by **bare model name**, applied **regardless of inferred provider**. This is the attribution-proof path: it prices a span even when the provider resolved to `"unknown"` (the #194 open-weight class). `models` is a reserved key (`MODEL_SECTION_KEY`), never a provider, so the forms never collide.
+- **`get_rates(provider, model)` lookup order** (first match wins): model-keyed override → provider-keyed table (user `[provider.model]` over packaged) → `None` (→ `calculate_cost` applies the `$0.50`/`$2.00` default and logs once). Each step tries an exact match, then strips a trailing `-YYYYMMDD` suffix.
+- Both layers are LRU-cached (`load_pricing_table` + `load_model_pricing_overrides`); call `clear_pricing_cache()` or **restart the daemon** to pick up an edit.
+
+The packaged table stays the zero-config default — the override is a *layer*, never a replacement; no user ever has to declare a rate to get started. (Follow-up not yet built: a `tj pricing set|list` CLI for editing overrides without hand-writing TOML.)
 
 ## CI
 
@@ -251,6 +343,19 @@ All steps are blocking — lint, typecheck, and tests must pass for CI to go gre
 
 There is no pre-commit configuration in this repo; `ruff` and `mypy` only run in CI. Run them locally before pushing.
 
+## Growth instrumentation — weekly traffic archive
+
+A separate `.github/workflows/traffic-archive.yml` runs every Sunday at 12:00 UTC (also `workflow_dispatch`) and archives the GitHub Traffic API (views / clones / referrers / paths — the only sources with the 14-day retention problem) into a JSON file at `traffic/<year>-W<week>.json`. **The archive lives on its own orphan branch `traffic-data`, not on `main`** — code and telemetry are deliberately separated, and `main`'s branch protection stays intact.
+
+Key facts:
+- The workflow uses `${{ secrets.TRAFFIC_PAT }}` (fine-grained PAT, resource owner = `Metabuilder-Labs` org, `Administration: Read` on this repo) for the Traffic API read — the default `GITHUB_TOKEN` returns 403 there. The push step uses the default `GITHUB_TOKEN` since `traffic-data` is unprotected.
+- The orphan-branch design was the close-out after several other paths (PAT-as-owner push, classic-protection bypass, rulesets bot-bypass) hit GitHub UI / API limitations. See PRs #171 / #172 / #173 for the trail. Don't try to move the archive back onto `main` — that path was explored and dead-ended.
+- The archive is the only growth-instrumentation surface in this repo. Health-check + spreadsheet-fill workflows were considered but descoped (Cowork sandbox couldn't reach external APIs, and GH Actions for the same was deemed overkill for a solo project). Manual review is the current model — fetch the JSON when wanted, hand it to an agent for analysis.
+- `growth/README.md` documents the schema + read-it-manually flow.
+- TRAFFIC_PAT expires Jun 20 2027 — renew before then.
+
+When adding any new automation that needs to *write* to the repo on a schedule, follow the same pattern: data on its own unprotected ref, code on `main`. Don't try to make `main` accept bot commits.
+
 ## Releases
 
 PyPI and npm publishes are triggered by GitHub Release events (`.github/workflows/publish-pypi.yml`, `publish-npm.yml`, both `on: release: types: [published]`). Release flow:

{tokenjam-0.4.0 → tokenjam-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tokenjam
-Version: 0.4.0
+Version: 0.4.2
 Summary: TokenJam — local-first OTel-native observability for Autonomous AI agents
 Project-URL: Homepage, https://opencla.watch
 Project-URL: Repository, https://github.com/Metabuilder-Labs/openclawwatch
@@ -64,7 +64,7 @@ Description-Content-Type: text/markdown
 
 ### Token Efficiency For AI Agents
 
-TokenJam reads your agent's telemetry and tells you when to downsize, when to trim prompts, what to cache, and what to script. The result is a lower AI bill. Runs entirely on your machine.
+TokenJam reads your agent's telemetry and tells you when to downsize, when to trim prompts, what to cache, what to script, and what plans you've already paid to figure out — then shows it all in a local browser dashboard. Runs entirely on your machine.
 
 [![CI](https://github.com/Metabuilder-Labs/tokenjam/actions/workflows/ci.yml/badge.svg)](https://github.com/Metabuilder-Labs/tokenjam/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/tokenjam?color=3d8eff&labelColor=0d1117)](https://pypi.org/project/tokenjam/)
@@ -85,9 +85,9 @@ pipx install tokenjam
 
 ---
 
-## Four Analyzers. One Install.
+## Five Analyzers + Lens. One Install.
 
-TokenJam reads telemetry from every major agent runtime, framework, provider, and observability tool and surfaces savings across four areas.
+TokenJam reads telemetry from every major agent runtime, framework, provider, and observability tool and surfaces savings across five areas — then brings them together in a local browser dashboard.
 
 <table>
 <tr>
@@ -136,11 +136,35 @@ Predicts which regions of your prompts the model gives little weight to. Surface
 
 [Details →](docs/optimize/trim.md)
 
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 🔁 Reuse
+
+Detects clusters of sessions where your agent re-plans the same work and exports reviewable skeleton templates you can drop into a slash command or script.
+
+<pre><code>tj optimize reuse</code></pre>
+
+[Details →](docs/optimize/reuse.md)
+
+</td>
+<td width="50%" valign="top">
+
+### 🔭 Lens
+
+A local browser dashboard that brings every analyzer's findings, your real spend, and your alerts together in one place. No cloud, no signup, fully offline.
+
+<pre><code>tj serve</code></pre>
+
+[Details →](https://tokenjam.dev/products/lens)
+
 </td>
 </tr>
 </table>
 
-Run all four with `tj optimize`. Run several with `tj optimize downsize cache trim`.
+Run all five analyzers with `tj optimize`. Run several with `tj optimize downsize cache reuse`.
 
 ---
 
@@ -149,9 +173,10 @@ Run all four with `tj optimize`. Run several with `tj optimize downsize cache tr
 For **Claude Code** users — zero code, auto-backfills your last 30 days:
 
 ```bash
-pipx install 'tokenjam[mcp]'
+pipx install tokenjam
 tj onboard --claude-code
 tj optimize          # cost-saving candidates from your actual usage
+tj serve             # open the dashboard at http://127.0.0.1:7391/
 ```
 
 To upgrade later: `pipx upgrade tokenjam` (then `tj stop && tj serve &` to reload the daemon, and `tj --version` to verify). See [docs/installation.md](docs/installation.md#upgrading).
@@ -173,64 +198,51 @@ def run(task: str) -> str:
 
 ---
 
-## Why local-first matters
-
-Your spans contain prompts, completions, tool inputs, and customer data. Shipping that to a SaaS vendor for "observability" is a data-egress decision most teams aren't ready to make.
-
-|                                            | TokenJam | LangSmith | Langfuse | Datadog LLM Obs |
-|---|---|---|---|---|
-| Signup required                            | ❌       | ✅        | ✅       | ✅              |
-| Data leaves your machine                   | ❌       | ✅        | cloud only | ✅           |
-| Cost-optimization analyzers (Downsize, Cache, Script, Trim) | ✅ | ❌ | ❌ | ❌ |
-| Real-time sensitive-action alerts          | ✅       | ❌        | ❌       | ❌              |
-| Behavioral drift detection                 | ✅       | ❌        | ❌       | ❌              |
-| OTel GenAI SemConv native                  | ✅       | partial   | partial  | partial         |
-| Works with any agent / framework           | ✅       | LangChain-first | partial | ❌            |
-| Free, MIT licensed                         | ✅       | freemium  | freemium | paid            |
-
----
-
-## Web UI
+## Lens — the local dashboard
 
-`tj serve` runs a local dashboard at `http://127.0.0.1:7391/` with status, traces, cost breakdown, alerts, budget, and drift.
+`tj serve` runs Lens at `http://127.0.0.1:7391/`: an Overview triage screen with spend, recoverable waste, and health at a glance; an Optimize tab showing every analyzer's findings side by side; and the standard Status, Traces, Cost, Alerts, Drift, and Budget screens. Plan-tier-aware, fully offline, no signup.
 
 <table>
 <tr>
-<td width="50%"><img src="docs/screenshots/tj-status.png" alt="tj status page" /></td>
-<td width="50%"><img src="docs/screenshots/tj-cost.png" alt="tj cost page" /></td>
+<td width="50%"><img src="docs/screenshots/tj-status.png" alt="Status screen" /></td>
+<td width="50%"><img src="docs/screenshots/tj-cost.png" alt="Cost screen with spend-over-time chart" /></td>
 </tr>
 <tr>
-<td width="50%"><img src="docs/screenshots/tj-traces.png" alt="tj traces page" /></td>
-<td width="50%"><img src="docs/screenshots/tj-alerts.png" alt="tj alerts page" /></td>
+<td width="50%"><img src="docs/screenshots/tj-traces.png" alt="Traces table" /></td>
+<td width="50%"><img src="docs/screenshots/tj-alerts.png" alt="Alerts table" /></td>
 </tr>
 </table>
 
+→ [tokenjam.dev/products/lens](https://tokenjam.dev/products/lens) for the visual walkthrough.
+
 ---
 
 ## Beyond optimization
 
-TokenJam is also a full observability stack. The four analyzers ride on top.
+TokenJam is also a full observability stack. The five analyzers and Lens ride on top.
 
 - **Real-time cost tracking** — every LLM call priced as it happens
 - **Safety alerts** — 13 alert types, 6 channels (ntfy, Discord, Telegram, webhook, file, stdout)
 - **Behavioral drift detection** — Z-score baselines, no LLM required
 - **Schema validation** — declare or infer JSON Schema for tool outputs
 - **OTel-native** — point any OTLP exporter at `tj serve` and you're done
-- **MCP server** — 14 tools letting Claude Code query its own telemetry mid-session
+- **MCP server** — lets Claude Code query its own telemetry mid-session
 
 ---
 
 ## CLI
 
 ```bash
-tj optimize            # all four cost-optimization analyzers
-tj optimize downsize   # one analyzer
+tj optimize            # all five cost-optimization analyzers
+tj optimize downsize   # one analyzer (positional args)
+tj tokenmaxx           # shareable spend-tier callout
 tj status              # current cost, tokens, active alerts
 tj cost --since 7d     # spend by agent / model / day / tool
 tj alerts              # everything that fired while you were away
 tj drift               # behavioral drift Z-scores
+tj report --reuse      # HTML + Markdown skeleton export for the Reuse analyzer
 tj backfill claude-code # ingest historical ~/.claude/projects/ sessions
-tj serve               # start the web UI + REST API
+tj serve               # start Lens + REST API
 ```
 
 [Full CLI reference →](docs/cli-reference.md)
@@ -242,6 +254,7 @@ tj serve               # start the web UI + REST API
 | Topic | Where |
 |---|---|
 | 🪶 Downsize / Cache / Script / Trim deep-dives | [docs/optimize/](docs/optimize/) |
+| 🔁 Reuse analyzer deep-dive | [docs/optimize/reuse.md](docs/optimize/reuse.md) |
 | Claude Code & Codex integration | [docs/claude-code-integration.md](docs/claude-code-integration.md) |
 | Python SDK reference | [docs/python-sdk.md](docs/python-sdk.md) |
 | TypeScript SDK reference | [docs/typescript-sdk.md](docs/typescript-sdk.md) |
@@ -253,6 +266,7 @@ tj serve               # start the web UI + REST API
 | Installation extras (Trim, framework patches) | [docs/installation.md](docs/installation.md) |
 | Export to Grafana / Datadog / NDJSON | [docs/export.md](docs/export.md) |
 | NemoClaw sandbox observer | [docs/nemoclaw-integration.md](docs/nemoclaw-integration.md) |
+| Release notes | [GitHub Releases](https://github.com/Metabuilder-Labs/tokenjam/releases) |
 
 ---
 
@@ -260,9 +274,13 @@ tj serve               # start the web UI + REST API
 
 **Shipped in 0.3.x:** Downsize · Cache · Script · Trim · Claude Code + Codex onboarding · MCP server · Web UI · Backfill adapters (Langfuse, Helicone, OTLP) · Period comparison · Routing-config export · Read-only policy preview
 
+**Shipped in 0.4.x:**
+- [x] **[TokenJam Lens](https://github.com/Metabuilder-Labs/tokenjam/milestone/1)** — local dashboard rebrand: Overview triage front-door, Optimize detail tab, real spend-over-time charts, cross-screen drill-through
+- [x] **[Reuse analyzer](https://github.com/Metabuilder-Labs/tokenjam/milestone/2)** — fifth analyzer: detects clusters of sessions with repeated planning, exports reviewable skeleton templates you can convert into slash commands or scripts
+- [x] **Daemon DB concurrency** — per-thread DuckDB cursors so the Overview's fan-out doesn't block on a single shared connection (v0.4.1)
+- [x] **Cache cost transparency** — `cache_read` + `cache_write` token columns surfaced in CLI + UI + API (the previously-hidden ~91% cost driver on cache-heavy workloads)
+
 **Up next:**
-- [ ] **[TokenJam Lens](https://github.com/Metabuilder-Labs/tokenjam/milestone/1)** — local dashboard rebrand: new Overview triage front-door, Optimize detail tab, real spend-over-time charts, cross-screen drill-through
-- [ ] **[Reuse analyzer](https://github.com/Metabuilder-Labs/tokenjam/milestone/2)** — fifth analyzer: detects clusters of sessions with repeated planning, exports reviewable skeleton templates you can convert into slash commands or scripts
 - [ ] `tj policy add | edit | apply` — unified rule surface
 - [ ] `tj replay` — replay captured sessions against new model versions
 - [ ] TypeScript framework patches (LangChain JS, OpenAI Agents SDK)
@@ -278,4 +296,6 @@ tj serve               # start the web UI + REST API
 
 MIT License · Built by [Metabuilder Labs](https://github.com/Metabuilder-Labs)
 
+TokenJam was created by [Anil Murty](https://github.com/anilmurty) — reach him at [anil@metabldr.com](mailto:anil@metabldr.com).
+
 </div>