tokenjam 0.5.0__tar.gz → 0.5.2__tar.gz

{tokenjam-0.5.0 → tokenjam-0.5.2}/.github/pull_request_template.md

@@ -2,6 +2,10 @@
 
 <!-- What does this PR do? 1-3 sentences. -->
 
+## Related issue
+
+<!-- Closes #N  — so the issue auto-closes on merge. One "Closes" line per issue. Omit if there's no issue. -->
+
 ## Checklist
 
 - [ ] Tests pass (`pytest tests/unit/ tests/synthetic/ tests/agents/ tests/integration/`)
@@ -9,3 +13,4 @@
 - [ ] Type check clean (`mypy tokenjam/`)
 - [ ] CLAUDE.md updated (if architecture changed)
 - [ ] Test spans use `tests/factories.py` (not raw `NormalizedSpan`)
+- [ ] Requested `@anilmurty` as reviewer (or @-mentioned him above)

{tokenjam-0.5.0 → tokenjam-0.5.2}/CLAUDE.md

@@ -392,3 +392,4 @@ Key runtime dependency: `pytz` is required by DuckDB for `TIMESTAMPTZ` column ha
 - **Backfill adapters** — `docs/backfill/overview.md` lists the four sources (`claude-code` / `langfuse` / `helicone` / `otlp`) with the partnership-posture framing; per-adapter pages document modes (URL / file), field mapping, idempotency, and v1 limitations.
 - **[docs/policy/overview.md](docs/policy/overview.md)** — read-only preview of the unified policy surface (`tj policy list`). Notes that the `add` / `edit` / `apply` subcommands and the underlying `[policy]` config migration land next sprint.
 - **Internal specs** — `docs/internal/specs/` is reserved for canonical specs that production code references at long-term. Currently empty (sprint specs have been cleaned up after merge); add new ones here when a feature needs a stable, code-referenced source of truth.
+- **[docs/internal/release-smoke-checklist.md](docs/internal/release-smoke-checklist.md)** — fresh-install pre-release gate (clean env → `pipx install` → `tj onboard --claude-code` → verify Lens plan badge + `tj optimize` agree → sane session count). Catches plan-tier / framing regressions a real first-run hits that synthetic-factory tests don't. Its automated counterpart is `tests/integration/test_first_run_roundtrip_239.py`.

tokenjam-0.5.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**anil@metabldr.com**.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

tokenjam-0.5.2/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing to TokenJam
+
+TokenJam is MIT licensed and welcomes contributions. It's built by AI coding agents, and contributing with one is first-class — see [Using coding agents](#using-coding-agents) below.
+
+## Good first contributions
+
+New here? These are the lowest-friction ways to land your first PR:
+
+- 🟢 **[Good first issues](https://github.com/Metabuilder-Labs/tokenjam/labels/good%20first%20issue)** — scoped tasks tagged ready for newcomers.
+- 💸 **Model pricing** — add a missing model or correct a rate in [`tokenjam/pricing/models.toml`](tokenjam/pricing/models.toml). One file, no issue needed (details below).
+- 🔌 **A framework/provider integration** — they follow one clear pattern; `tokenjam/sdk/integrations/anthropic.py` is the reference. Open an issue first to align on approach.
+
+Questions on any of these? Open an issue — we're happy to point you at a good starting spot.
+
+## Claiming an issue
+
+Found an issue you want to work on? **Assign it to yourself** so others know it's taken and nobody duplicates the work. If you don't have permission to self-assign (common if you're not yet a repo collaborator), just leave a quick comment saying you're on it and a maintainer will assign you. If an issue is already assigned — or has a recent "I'll take this" comment — pick another one.
+
+## Getting started
+
+```bash
+git clone https://github.com/Metabuilder-Labs/tokenjam
+cd tokenjam
+pip install -e ".[dev]"   # editable install with dev tools (the MCP server ships in the base install)
+pip install anthropic     # for running the toy agent
+```
+
+## Running tests
+
+The suite is layered — fastest first. CI runs everything except `e2e`, and **none of these need an API key**:
+
+```bash
+pytest tests/unit/ tests/synthetic/ tests/agents/ tests/integration/
+```
+
+- `tests/unit/` — pure logic, no I/O (runs in well under a second)
+- `tests/synthetic/` — spans injected via `tests/factories.py`, zero cost
+- `tests/agents/` — mock agent scenarios through the full SDK path
+- `tests/integration/` — CLI + HTTP API
+
+While iterating, run just one file — or one test:
+
+```bash
+pytest tests/unit/test_config.py
+pytest tests/unit/test_config.py::test_function_name -v
+```
+
+Lint and type-check (both run in CI — please run them before pushing):
+
+```bash
+ruff check tokenjam/
+mypy tokenjam/
+```
+
+The TypeScript SDK is an independent package with its own tests — run these only if you touch `sdk-ts/`:
+
+```bash
+cd sdk-ts && npm install && npm test
+```
+
+E2e tests hit a real API and **auto-skip unless `TJ_ANTHROPIC_API_KEY` is set** (a full run costs fractions of a cent):
+
+```bash
+export TJ_ANTHROPIC_API_KEY="sk-ant-..."
+pytest tests/e2e/
+```
+
+## Branches and commits
+
+- Branch off `main` with a type-prefixed, kebab-case name: `fix/...`, `feat/...`, `docs/...`, or `chore/...` (e.g. `fix/budget-json-flag`).
+- Keep each PR to **one concern** — one feature or fix. If you spot an unrelated problem, open a separate issue rather than expanding the PR.
+- Write commit subjects in the imperative ("Add budget `--json` flag"), and reference the issue with `#N` where relevant. Put `Closes #N` in the PR description so the issue auto-closes on merge.
+
+## Before opening a PR
+
+- Run the test suite and make sure it passes: `pytest tests/unit/ tests/synthetic/ tests/agents/ tests/integration/`
+- Run `ruff check tokenjam/` **and** `mypy tokenjam/`, and fix anything they flag
+- Keep PRs focused — one feature or fix per PR
+- If you're adding a framework integration, open an issue first so the approach can be aligned on before you write code — integrations have a specific pattern (see `tokenjam/sdk/integrations/anthropic.py` as the reference implementation)
+- When it's ready, **request `@anilmurty` as the reviewer** (if you can't request reviewers, just @-mention him in the PR description) — that's the signal it's ready for a look
+- Make sure CI is green on your branch before requesting review
+
+## Project structure
+
+```
+tokenjam/core/              Domain logic — no CLI or HTTP imports allowed here
+tokenjam/cli/               Click commands — one file per command
+tokenjam/api/               FastAPI routes
+tokenjam/sdk/               @watch() decorator and provider/framework patches
+tokenjam/otel/              OTel TracerProvider and span exporter wiring
+tokenjam/utils/             Formatting, time parsing, ID generation
+sdk-ts/src/            TypeScript SDK (@tokenjam/sdk)
+tokenjam/pricing/models.toml  Community-maintained model pricing — PRs welcome here
+tests/factories.py     Span factory — use this in all synthetic tests, never
+                       construct NormalizedSpan directly
+```
+
+## Using coding agents
+
+TokenJam is built by AI coding agents, and contributing with one is first-class:
+
+- **Claude Code** — it reads [`CLAUDE.md`](CLAUDE.md) automatically; run `/init` to bring your agent up to speed on the architecture and conventions.
+- **Codex / Gemini / other agents** — read [`AGENTS.md`](AGENTS.md): the critical rules (DuckDB not SQLite, TOML not YAML, no CLI imports in `tokenjam/core/`, etc.) plus a pointer to CLAUDE.md for the full guide.
+
+## Pricing table contributions
+
+The file `tokenjam/pricing/models.toml` is intentionally community-maintained. If a model is missing or prices have changed, open a PR with the update — no issue needed, just update the TOML and verify the format matches existing entries. (This is the file the cost engine loads at runtime; there is no separate repo-root copy.)
+
+## Reporting issues
+
+Use GitHub Issues. For bugs, include:
+
+- Python version (`python3 --version`)
+- OS
+- The command you ran
+- The full error output
+- Output of `tj doctor` if relevant

{tokenjam-0.5.0 → tokenjam-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tokenjam
-Version: 0.5.0
+Version: 0.5.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
@@ -58,9 +58,7 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-<img src="https://tokenjam.dev/icon.svg" alt="TokenJam" width="72" height="72">
-
-# TokenJam
+<img src="docs/brand/tokenjam-banner.png" alt="TokenJam" width="440">
 
 ### Token Efficiency For AI Agents
 
@@ -68,6 +66,7 @@ TokenJam reads your agent's telemetry and tells you when to downsize, when to tr
 
 [![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/)
+[![Downloads](https://img.shields.io/pypi/dm/tokenjam?color=3d8eff&labelColor=0d1117&label=downloads)](https://pypi.org/project/tokenjam/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-3d8eff?labelColor=0d1117)](https://pypi.org/project/tokenjam/)
 [![npm](https://img.shields.io/npm/v/@tokenjam/sdk?color=3d8eff&labelColor=0d1117)](https://www.npmjs.com/package/@tokenjam/sdk)
 [![License: MIT](https://img.shields.io/badge/license-MIT-3d8eff?labelColor=0d1117)](LICENSE)
@@ -81,6 +80,8 @@ pipx install tokenjam
 
 **No cloud · No signup · No vendor lock-in**
 
+<sub>⭐ If TokenJam saves you tokens, **star it** · 👁 **Watch for releases** — we ship often</sub>
+
 </div>
 
 ---
@@ -179,6 +180,23 @@ tj optimize          # cost-saving candidates from your actual usage
 tj serve             # open the dashboard at http://127.0.0.1:7391/
 ```
 
+That's it. Run `tj` any time and it points you to the next best action:
+
+```text
+ _____    _              _
+|_   _|__| |_____ _ _   | |__ _ _ __
+  | |/ _ \ / / -_) ' \  | / _` | '  \
+  |_|\___/_\_\___|_||_|_/ \__,_|_|_|_|
+                     |__/
+  TokenJam · cost-optimization for AI agents · local-first, OTel-native · no signup
+
+You're set up. Next best actions:
+  tj status      agent overview — what's running, recent cost
+  tj tokenmaxx   your shareable spend tier
+  tj optimize    cost-saving candidates from your usage
+  tj serve       open Lens (web UI) 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).
 
 For any Python agent:
@@ -200,16 +218,20 @@ def run(task: str) -> str:
 
 ## Lens — the local dashboard
 
-`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.
+`tj serve` runs Lens at `http://127.0.0.1:7391/`: a **Dashboard** that lands you on recoverable waste and health at a glance, with an embedded explorer to slice your usage any way (metric × dimension × chart); plus Status, Traces, Cost, Analytics, Alerts, Drift, Optimize, and Budget screens. Plan-tier-aware, fully offline, no signup.
 
 <table>
 <tr>
-<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>
+<td width="50%"><img src="docs/screenshots/tj-dashboard.png" alt="Dashboard — recoverable waste, health at a glance, and the embedded pivot explorer" /></td>
+<td width="50%"><img src="docs/screenshots/tj-cost.png" alt="Cost — spend over time + cache savings" /></td>
 </tr>
 <tr>
-<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>
+<td width="50%"><img src="docs/screenshots/tj-traces.png" alt="Trace waterfall — session-level spans with cost annotations" /></td>
+<td width="50%"><img src="docs/screenshots/tj-status.png" alt="Status — per-agent cards" /></td>
+</tr>
+<tr>
+<td width="50%"><img src="docs/screenshots/tj-dashboard-tools.png" alt="Analytics explorer — tool-usage leaderboard" /></td>
+<td width="50%"><img src="docs/screenshots/tj-dashboard-leaderboard.png" alt="Analytics explorer — cost-by-model leaderboard" /></td>
 </tr>
 </table>
 
@@ -280,7 +302,13 @@ tj serve               # start Lens + REST API
 - [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:**
+**Shipped in 0.5.x:**
+- [x] **Lens Visualizations** — an Analytics pivot explorer (metric × dimension × chart, presets, CSV), stacked cost-by-model, a cache-savings chart, KPI sparklines, a cost-annotated trace waterfall, and consistent series coloring
+- [x] **Merged Dashboard** — the explorer and the triage front-door unified into one default screen, with in-place drill-through from recoverable-waste tiles
+- [x] **First-run polish** — backfill fidelity (session-level traces, cache read/write split, honest session counts), plan-tier-aware framing throughout (subscription users see token-share, never raw spend), an onboarding welcome banner + next-steps guidance, and a contribution funnel
+
+**Up next** (roughly):
+- [ ] Continued Lens polish + per-product visual branding
 - [ ] `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)
@@ -290,6 +318,21 @@ tj serve               # start Lens + REST API
 
 ---
 
+## Contributing
+
+TokenJam is MIT, and contributions are welcome — from a one-line pricing fix to a whole new framework integration. A few easy on-ramps:
+
+- 🟢 **[Good first issues →](https://github.com/Metabuilder-Labs/tokenjam/labels/good%20first%20issue)** — scoped, newcomer-friendly tasks, ready to pick up.
+- 💸 **Model pricing** — `tokenjam/pricing/models.toml` is community-maintained. Fix a rate or add a model in a single PR — no issue needed.
+- 🔌 **Framework integrations** — provider/framework patches follow one clear pattern (`tokenjam/sdk/integrations/anthropic.py` is the reference). Open an issue first to align on approach.
+- 🤖 **Built with coding agents** — TokenJam is built by AI coding agents, and contributing with one is first-class. **Claude Code:** read [CLAUDE.md](CLAUDE.md) and run `/init` to bring your agent up to speed. **Codex / other agents:** [AGENTS.md](AGENTS.md) has the critical rules.
+
+Setup and the full dev workflow are in **[CONTRIBUTING.md](CONTRIBUTING.md)**.
+
+If TokenJam saves you tokens, **⭐ star it** and **👁 watch for releases** — we ship often.
+
+---
+
 <div align="center">
 
 **[tokenjam.dev](https://tokenjam.dev)** · [PyPI](https://pypi.org/project/tokenjam/) · [npm](https://www.npmjs.com/package/@tokenjam/sdk) · [Issues](https://github.com/Metabuilder-Labs/tokenjam/issues)

{tokenjam-0.5.0 → tokenjam-0.5.2}/README.md

@@ -1,8 +1,6 @@
 <div align="center">
 
-<img src="https://tokenjam.dev/icon.svg" alt="TokenJam" width="72" height="72">
-
-# TokenJam
+<img src="docs/brand/tokenjam-banner.png" alt="TokenJam" width="440">
 
 ### Token Efficiency For AI Agents
 
@@ -10,6 +8,7 @@ TokenJam reads your agent's telemetry and tells you when to downsize, when to tr
 
 [![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/)
+[![Downloads](https://img.shields.io/pypi/dm/tokenjam?color=3d8eff&labelColor=0d1117&label=downloads)](https://pypi.org/project/tokenjam/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-3d8eff?labelColor=0d1117)](https://pypi.org/project/tokenjam/)
 [![npm](https://img.shields.io/npm/v/@tokenjam/sdk?color=3d8eff&labelColor=0d1117)](https://www.npmjs.com/package/@tokenjam/sdk)
 [![License: MIT](https://img.shields.io/badge/license-MIT-3d8eff?labelColor=0d1117)](LICENSE)
@@ -23,6 +22,8 @@ pipx install tokenjam
 
 **No cloud · No signup · No vendor lock-in**
 
+<sub>⭐ If TokenJam saves you tokens, **star it** · 👁 **Watch for releases** — we ship often</sub>
+
 </div>
 
 ---
@@ -121,6 +122,23 @@ tj optimize          # cost-saving candidates from your actual usage
 tj serve             # open the dashboard at http://127.0.0.1:7391/
 ```
 
+That's it. Run `tj` any time and it points you to the next best action:
+
+```text
+ _____    _              _
+|_   _|__| |_____ _ _   | |__ _ _ __
+  | |/ _ \ / / -_) ' \  | / _` | '  \
+  |_|\___/_\_\___|_||_|_/ \__,_|_|_|_|
+                     |__/
+  TokenJam · cost-optimization for AI agents · local-first, OTel-native · no signup
+
+You're set up. Next best actions:
+  tj status      agent overview — what's running, recent cost
+  tj tokenmaxx   your shareable spend tier
+  tj optimize    cost-saving candidates from your usage
+  tj serve       open Lens (web UI) 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).
 
 For any Python agent:
@@ -142,16 +160,20 @@ def run(task: str) -> str:
 
 ## Lens — the local dashboard
 
-`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.
+`tj serve` runs Lens at `http://127.0.0.1:7391/`: a **Dashboard** that lands you on recoverable waste and health at a glance, with an embedded explorer to slice your usage any way (metric × dimension × chart); plus Status, Traces, Cost, Analytics, Alerts, Drift, Optimize, and Budget screens. Plan-tier-aware, fully offline, no signup.
 
 <table>
 <tr>
-<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>
+<td width="50%"><img src="docs/screenshots/tj-dashboard.png" alt="Dashboard — recoverable waste, health at a glance, and the embedded pivot explorer" /></td>
+<td width="50%"><img src="docs/screenshots/tj-cost.png" alt="Cost — spend over time + cache savings" /></td>
 </tr>
 <tr>
-<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>
+<td width="50%"><img src="docs/screenshots/tj-traces.png" alt="Trace waterfall — session-level spans with cost annotations" /></td>
+<td width="50%"><img src="docs/screenshots/tj-status.png" alt="Status — per-agent cards" /></td>
+</tr>
+<tr>
+<td width="50%"><img src="docs/screenshots/tj-dashboard-tools.png" alt="Analytics explorer — tool-usage leaderboard" /></td>
+<td width="50%"><img src="docs/screenshots/tj-dashboard-leaderboard.png" alt="Analytics explorer — cost-by-model leaderboard" /></td>
 </tr>
 </table>
 
@@ -222,7 +244,13 @@ tj serve               # start Lens + REST API
 - [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:**
+**Shipped in 0.5.x:**
+- [x] **Lens Visualizations** — an Analytics pivot explorer (metric × dimension × chart, presets, CSV), stacked cost-by-model, a cache-savings chart, KPI sparklines, a cost-annotated trace waterfall, and consistent series coloring
+- [x] **Merged Dashboard** — the explorer and the triage front-door unified into one default screen, with in-place drill-through from recoverable-waste tiles
+- [x] **First-run polish** — backfill fidelity (session-level traces, cache read/write split, honest session counts), plan-tier-aware framing throughout (subscription users see token-share, never raw spend), an onboarding welcome banner + next-steps guidance, and a contribution funnel
+
+**Up next** (roughly):
+- [ ] Continued Lens polish + per-product visual branding
 - [ ] `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)
@@ -232,6 +260,21 @@ tj serve               # start Lens + REST API
 
 ---
 
+## Contributing
+
+TokenJam is MIT, and contributions are welcome — from a one-line pricing fix to a whole new framework integration. A few easy on-ramps:
+
+- 🟢 **[Good first issues →](https://github.com/Metabuilder-Labs/tokenjam/labels/good%20first%20issue)** — scoped, newcomer-friendly tasks, ready to pick up.
+- 💸 **Model pricing** — `tokenjam/pricing/models.toml` is community-maintained. Fix a rate or add a model in a single PR — no issue needed.
+- 🔌 **Framework integrations** — provider/framework patches follow one clear pattern (`tokenjam/sdk/integrations/anthropic.py` is the reference). Open an issue first to align on approach.
+- 🤖 **Built with coding agents** — TokenJam is built by AI coding agents, and contributing with one is first-class. **Claude Code:** read [CLAUDE.md](CLAUDE.md) and run `/init` to bring your agent up to speed. **Codex / other agents:** [AGENTS.md](AGENTS.md) has the critical rules.
+
+Setup and the full dev workflow are in **[CONTRIBUTING.md](CONTRIBUTING.md)**.
+
+If TokenJam saves you tokens, **⭐ star it** and **👁 watch for releases** — we ship often.
+
+---
+
 <div align="center">
 
 **[tokenjam.dev](https://tokenjam.dev)** · [PyPI](https://pypi.org/project/tokenjam/) · [npm](https://www.npmjs.com/package/@tokenjam/sdk) · [Issues](https://github.com/Metabuilder-Labs/tokenjam/issues)

tokenjam-0.5.2/docs/brand/README.md

@@ -0,0 +1,29 @@
+# TokenJam brand assets
+
+The TokenJam mark is a **weight matrix in brackets** — `[ W₁₁ W₁₂ / W₂₁ W₂₂ ]` — the tensor at the heart of every model. The wordmark is set in **DIN Alternate Bold** (a technical, squared geometric that echoes the matrix motif).
+
+**Convention: black on white.** All brand assets are a single ink color (black) on a white/transparent ground, matching [tokenjam.dev](https://tokenjam.dev). Don't recolor the mark per-surface — keep it monochrome.
+
+## Files
+
+| Asset | Vector source | Raster |
+|---|---|---|
+| Mark / logo | `tokenjam-icon.svg` | `tokenjam-icon.png` |
+| Wordmark | `tokenjam-wordmark.svg` | `tokenjam-wordmark.png` |
+| Banner (mark + wordmark lockup) | `tokenjam-banner.svg` | `tokenjam-banner.png` |
+
+The README header uses `tokenjam-banner.png`. The SVGs are the editable sources — prefer them for any new surface and rasterize as needed.
+
+## Regenerating the PNGs
+
+The PNGs are rendered from the SVGs with [`rsvg-convert`](https://gitlab.gnome.org/GNOME/librsvg) on a white background, then cropped to content:
+
+```bash
+rsvg-convert --background-color=white -w 1600 -o tokenjam-banner.png tokenjam-banner.svg
+```
+
+The wordmark stroke is filled (solid). A hollow-outline variant — `fill="none" stroke="#000"` — matches the mark's stroke language and is available if a lighter treatment is ever wanted; the filled cut is the default for legibility at small sizes (PyPI, favicons, social cards).
+
+## In-app mark
+
+The dashboard ("TokenJam Lens") renders the same mark inline in `tokenjam/ui/index.html` (`<svg class="brand-mark">`) using `currentColor`, and as the inlined favicon. If you change the mark here, update those too.

tokenjam-0.5.2/docs/brand/tokenjam-banner.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="190" viewBox="0 0 760 190">
+  <rect width="760" height="190" fill="#ffffff"/>
+  <svg x="22" y="35" width="120" height="120" viewBox="54 32 132 132" fill="none" stroke="#000" stroke-width="7" stroke-linecap="round" stroke-linejoin="round">
+    <rect x="74" y="44" width="92" height="20" rx="6" ry="6"/>
+<path d="M 104 72 L 74 72 L 74 152 L 104 152"/>
+<path d="M 136 72 L 166 72 L 166 152 L 136 152"/>
+<g fill="#000" stroke="none" fill-rule="evenodd">
+<path transform="translate(85.68,104)" d="M21.19,-14.32 L16.75,-0.00 L13.63,-0.00 L10.74,-10.58 L7.85,-0.00 L4.73,-0.00 L0.26,-14.32 L3.27,-14.32 L6.26,-2.81 L9.31,-14.32 L12.40,-14.32 L15.32,-2.86 L18.28,-14.32 L21.19,-14.32 Z"/>
+<path transform="translate(106.83,107)" d="M0.54,-7.50 L0.54,-8.75 L3.04,-8.75 L3.04,-0.00 L1.66,-0.00 L1.66,-7.50 L0.54,-7.50 Z M4.74,-7.50 L4.74,-8.75 L7.24,-8.75 L7.24,-0.00 L5.86,-0.00 L5.86,-7.50 L4.74,-7.50 Z"/>
+<path transform="translate(123.97,104)" d="M21.19,-14.32 L16.75,-0.00 L13.63,-0.00 L10.74,-10.58 L7.85,-0.00 L4.73,-0.00 L0.26,-14.32 L3.27,-14.32 L6.26,-2.81 L9.31,-14.32 L12.40,-14.32 L15.32,-2.86 L18.28,-14.32 L21.19,-14.32 Z"/>
+<path transform="translate(145.12,107)" d="M0.54,-7.50 L0.54,-8.75 L3.04,-8.75 L3.04,-0.00 L1.66,-0.00 L1.66,-7.50 L0.54,-7.50 Z M5.68,-1.86 Q6.83,-2.86 7.49,-3.50 Q8.16,-4.14 8.60,-4.84 Q9.05,-5.53 9.05,-6.23 Q9.05,-6.95 8.71,-7.36 Q8.36,-7.76 7.63,-7.76 Q6.92,-7.76 6.53,-7.31 Q6.14,-6.86 6.12,-6.11 L4.80,-6.11 Q4.84,-7.48 5.62,-8.20 Q6.41,-8.93 7.62,-8.93 Q8.93,-8.93 9.67,-8.21 Q10.40,-7.49 10.40,-6.29 Q10.40,-5.42 9.97,-4.63 Q9.53,-3.83 8.92,-3.20 Q8.32,-2.57 7.38,-1.74 L6.84,-1.26 L10.64,-1.26 L10.64,-0.12 L4.81,-0.12 L4.81,-1.12 L5.68,-1.86 Z"/>
+<path transform="translate(84.35,128)" d="M21.19,-14.32 L16.75,-0.00 L13.63,-0.00 L10.74,-10.58 L7.85,-0.00 L4.73,-0.00 L0.26,-14.32 L3.27,-14.32 L6.26,-2.81 L9.31,-14.32 L12.40,-14.32 L15.32,-2.86 L18.28,-14.32 L21.19,-14.32 Z"/>
+<path transform="translate(105.44,131)" d="M1.48,-1.86 Q2.63,-2.86 3.29,-3.50 Q3.96,-4.14 4.40,-4.84 Q4.85,-5.53 4.85,-6.23 Q4.85,-6.95 4.51,-7.36 Q4.16,-7.76 3.43,-7.76 Q2.72,-7.76 2.33,-7.31 Q1.94,-6.86 1.92,-6.11 L0.60,-6.11 Q0.64,-7.48 1.42,-8.20 Q2.21,-8.93 3.42,-8.93 Q4.73,-8.93 5.47,-8.21 Q6.20,-7.49 6.20,-6.29 Q6.20,-5.42 5.77,-4.63 Q5.33,-3.83 4.72,-3.20 Q4.12,-2.57 3.18,-1.74 L2.64,-1.26 L6.44,-1.26 L6.44,-0.12 L0.61,-0.12 L0.61,-1.12 L1.48,-1.86 Z M7.46,-7.50 L7.46,-8.75 L9.96,-8.75 L9.96,-0.00 L8.58,-0.00 L8.58,-7.50 L7.46,-7.50 Z"/>
+<path transform="translate(122.64,128)" d="M21.19,-14.32 L16.75,-0.00 L13.63,-0.00 L10.74,-10.58 L7.85,-0.00 L4.73,-0.00 L0.26,-14.32 L3.27,-14.32 L6.26,-2.81 L9.31,-14.32 L12.40,-14.32 L15.32,-2.86 L18.28,-14.32 L21.19,-14.32 Z"/>
+<path transform="translate(143.73,131)" d="M1.48,-1.86 Q2.63,-2.86 3.29,-3.50 Q3.96,-4.14 4.40,-4.84 Q4.85,-5.53 4.85,-6.23 Q4.85,-6.95 4.51,-7.36 Q4.16,-7.76 3.43,-7.76 Q2.72,-7.76 2.33,-7.31 Q1.94,-6.86 1.92,-6.11 L0.60,-6.11 Q0.64,-7.48 1.42,-8.20 Q2.21,-8.93 3.42,-8.93 Q4.73,-8.93 5.47,-8.21 Q6.20,-7.49 6.20,-6.29 Q6.20,-5.42 5.77,-4.63 Q5.33,-3.83 4.72,-3.20 Q4.12,-2.57 3.18,-1.74 L2.64,-1.26 L6.44,-1.26 L6.44,-0.12 L0.61,-0.12 L0.61,-1.12 L1.48,-1.86 Z M8.40,-1.86 Q9.55,-2.86 10.22,-3.50 Q10.88,-4.14 11.33,-4.84 Q11.77,-5.53 11.77,-6.23 Q11.77,-6.95 11.43,-7.36 Q11.09,-7.76 10.36,-7.76 Q9.65,-7.76 9.26,-7.31 Q8.87,-6.86 8.84,-6.11 L7.52,-6.11 Q7.56,-7.48 8.35,-8.20 Q9.13,-8.93 10.34,-8.93 Q11.65,-8.93 12.39,-8.21 Q13.13,-7.49 13.13,-6.29 Q13.13,-5.42 12.69,-4.63 Q12.25,-3.83 11.65,-3.20 Q11.04,-2.57 10.10,-1.74 L9.56,-1.26 L13.37,-1.26 L13.37,-0.12 L7.54,-0.12 L7.54,-1.12 L8.40,-1.86 Z"/>
+</g>
+  </svg>
+  <text x="168" y="123" font-family="DIN Alternate" font-weight="bold" font-size="86" letter-spacing="1" fill="#000">TokenJam</text>
+</svg>

tokenjam-0.5.2/docs/brand/tokenjam-icon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="54 32 132 132" fill="none" stroke="#000" stroke-width="7" stroke-linecap="round" stroke-linejoin="round">
+<rect x="74" y="44" width="92" height="20" rx="6" ry="6"/>
+<path d="M 104 72 L 74 72 L 74 152 L 104 152"/>
+<path d="M 136 72 L 166 72 L 166 152 L 136 152"/>
+<g fill="#000" stroke="none" fill-rule="evenodd">
+<path transform="translate(85.68,104)" d="M21.19,-14.32 L16.75,-0.00 L13.63,-0.00 L10.74,-10.58 L7.85,-0.00 L4.73,-0.00 L0.26,-14.32 L3.27,-14.32 L6.26,-2.81 L9.31,-14.32 L12.40,-14.32 L15.32,-2.86 L18.28,-14.32 L21.19,-14.32 Z"/>
+<path transform="translate(106.83,107)" d="M0.54,-7.50 L0.54,-8.75 L3.04,-8.75 L3.04,-0.00 L1.66,-0.00 L1.66,-7.50 L0.54,-7.50 Z M4.74,-7.50 L4.74,-8.75 L7.24,-8.75 L7.24,-0.00 L5.86,-0.00 L5.86,-7.50 L4.74,-7.50 Z"/>
+<path transform="translate(123.97,104)" d="M21.19,-14.32 L16.75,-0.00 L13.63,-0.00 L10.74,-10.58 L7.85,-0.00 L4.73,-0.00 L0.26,-14.32 L3.27,-14.32 L6.26,-2.81 L9.31,-14.32 L12.40,-14.32 L15.32,-2.86 L18.28,-14.32 L21.19,-14.32 Z"/>
+<path transform="translate(145.12,107)" d="M0.54,-7.50 L0.54,-8.75 L3.04,-8.75 L3.04,-0.00 L1.66,-0.00 L1.66,-7.50 L0.54,-7.50 Z M5.68,-1.86 Q6.83,-2.86 7.49,-3.50 Q8.16,-4.14 8.60,-4.84 Q9.05,-5.53 9.05,-6.23 Q9.05,-6.95 8.71,-7.36 Q8.36,-7.76 7.63,-7.76 Q6.92,-7.76 6.53,-7.31 Q6.14,-6.86 6.12,-6.11 L4.80,-6.11 Q4.84,-7.48 5.62,-8.20 Q6.41,-8.93 7.62,-8.93 Q8.93,-8.93 9.67,-8.21 Q10.40,-7.49 10.40,-6.29 Q10.40,-5.42 9.97,-4.63 Q9.53,-3.83 8.92,-3.20 Q8.32,-2.57 7.38,-1.74 L6.84,-1.26 L10.64,-1.26 L10.64,-0.12 L4.81,-0.12 L4.81,-1.12 L5.68,-1.86 Z"/>
+<path transform="translate(84.35,128)" d="M21.19,-14.32 L16.75,-0.00 L13.63,-0.00 L10.74,-10.58 L7.85,-0.00 L4.73,-0.00 L0.26,-14.32 L3.27,-14.32 L6.26,-2.81 L9.31,-14.32 L12.40,-14.32 L15.32,-2.86 L18.28,-14.32 L21.19,-14.32 Z"/>
+<path transform="translate(105.44,131)" d="M1.48,-1.86 Q2.63,-2.86 3.29,-3.50 Q3.96,-4.14 4.40,-4.84 Q4.85,-5.53 4.85,-6.23 Q4.85,-6.95 4.51,-7.36 Q4.16,-7.76 3.43,-7.76 Q2.72,-7.76 2.33,-7.31 Q1.94,-6.86 1.92,-6.11 L0.60,-6.11 Q0.64,-7.48 1.42,-8.20 Q2.21,-8.93 3.42,-8.93 Q4.73,-8.93 5.47,-8.21 Q6.20,-7.49 6.20,-6.29 Q6.20,-5.42 5.77,-4.63 Q5.33,-3.83 4.72,-3.20 Q4.12,-2.57 3.18,-1.74 L2.64,-1.26 L6.44,-1.26 L6.44,-0.12 L0.61,-0.12 L0.61,-1.12 L1.48,-1.86 Z M7.46,-7.50 L7.46,-8.75 L9.96,-8.75 L9.96,-0.00 L8.58,-0.00 L8.58,-7.50 L7.46,-7.50 Z"/>
+<path transform="translate(122.64,128)" d="M21.19,-14.32 L16.75,-0.00 L13.63,-0.00 L10.74,-10.58 L7.85,-0.00 L4.73,-0.00 L0.26,-14.32 L3.27,-14.32 L6.26,-2.81 L9.31,-14.32 L12.40,-14.32 L15.32,-2.86 L18.28,-14.32 L21.19,-14.32 Z"/>
+<path transform="translate(143.73,131)" d="M1.48,-1.86 Q2.63,-2.86 3.29,-3.50 Q3.96,-4.14 4.40,-4.84 Q4.85,-5.53 4.85,-6.23 Q4.85,-6.95 4.51,-7.36 Q4.16,-7.76 3.43,-7.76 Q2.72,-7.76 2.33,-7.31 Q1.94,-6.86 1.92,-6.11 L0.60,-6.11 Q0.64,-7.48 1.42,-8.20 Q2.21,-8.93 3.42,-8.93 Q4.73,-8.93 5.47,-8.21 Q6.20,-7.49 6.20,-6.29 Q6.20,-5.42 5.77,-4.63 Q5.33,-3.83 4.72,-3.20 Q4.12,-2.57 3.18,-1.74 L2.64,-1.26 L6.44,-1.26 L6.44,-0.12 L0.61,-0.12 L0.61,-1.12 L1.48,-1.86 Z M8.40,-1.86 Q9.55,-2.86 10.22,-3.50 Q10.88,-4.14 11.33,-4.84 Q11.77,-5.53 11.77,-6.23 Q11.77,-6.95 11.43,-7.36 Q11.09,-7.76 10.36,-7.76 Q9.65,-7.76 9.26,-7.31 Q8.87,-6.86 8.84,-6.11 L7.52,-6.11 Q7.56,-7.48 8.35,-8.20 Q9.13,-8.93 10.34,-8.93 Q11.65,-8.93 12.39,-8.21 Q13.13,-7.49 13.13,-6.29 Q13.13,-5.42 12.69,-4.63 Q12.25,-3.83 11.65,-3.20 Q11.04,-2.57 10.10,-1.74 L9.56,-1.26 L13.37,-1.26 L13.37,-0.12 L7.54,-0.12 L7.54,-1.12 L8.40,-1.86 Z"/>
+</g>
+</svg>

tokenjam-0.5.2/docs/brand/tokenjam-wordmark.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="150" viewBox="0 0 600 150">
+  <text x="6" y="112" font-family="DIN Alternate" font-weight="bold" font-size="92" letter-spacing="1" fill="#000">TokenJam</text>
+</svg>