tokenjam 0.5.2__tar.gz → 0.5.4__tar.gz

tokenjam-0.5.4/.dockerignore

@@ -0,0 +1,40 @@
+# VCS
+.git
+.gitignore
+
+# CI / Deployment config
+.github
+Dockerfile
+.dockerignore
+
+# Local TokenJam runtime state (untracked; .tj/config.toml holds a live ingest_secret)
+.tj
+.tj-test-data
+*.duckdb
+
+# Python caches / build artifacts
+__pycache__
+*.py[cod]
+*.egg-info
+.eggs
+build
+dist
+.mypy_cache
+.ruff_cache
+.pytest_cache
+
+# Test + docs (not needed in the image; incidents/ IS needed and is not ignored)
+tests
+docs
+examples
+growth
+traffic
+
+# TypeScript SDK (independent package)
+sdk-ts/node_modules
+sdk-ts/dist
+
+# Editor / OS cruft
+.DS_Store
+.vscode
+.idea

tokenjam-0.5.4/.github/actions/docker-publish/action.yml

@@ -0,0 +1,71 @@
+name: Docker publish
+description: Log in to a registry, build a Docker image, and push it with computed tags.
+
+inputs:
+  registry:
+    description: Container registry to push to.
+    required: false
+    default: ghcr.io
+  username:
+    description: Registry username (e.g. github.actor).
+    required: true
+  password:
+    description: Registry password or token (e.g. secrets.GITHUB_TOKEN).
+    required: true
+  image:
+    description: Fully-qualified image name without tag (e.g. ghcr.io/owner/repo).
+    required: true
+  context:
+    description: Build context path.
+    required: false
+    default: .
+  dockerfile:
+    description: Path to the Dockerfile.
+    required: false
+    default: Dockerfile
+
+outputs:
+  tags:
+    description: Newline-separated list of tags that were pushed.
+    value: ${{ steps.meta.outputs.tags }}
+  digest:
+    description: Image digest of the pushed image.
+    value: ${{ steps.build.outputs.digest }}
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to registry
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ inputs.registry }}
+        username: ${{ inputs.username }}
+        password: ${{ inputs.password }}
+
+    - name: Extract image metadata
+      id: meta
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ inputs.image }}
+        # Release-driven tags: the semver of the published release plus `latest`.
+        # No per-commit short-SHA tag — the image only ships on a release, so its
+        # version maps 1:1 to the release tag (matching the PyPI/npm packages).
+        tags: |
+          type=semver,pattern={{version}}
+          type=semver,pattern={{major}}.{{minor}}
+          type=raw,value=latest
+
+    - name: Build and push image
+      id: build
+      uses: docker/build-push-action@v6
+      with:
+        context: ${{ inputs.context }}
+        file: ${{ inputs.dockerfile }}
+        push: true
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max

tokenjam-0.5.4/.github/workflows/docker-publish.yml

@@ -0,0 +1,36 @@
+name: Build and publish Docker image
+
+on:
+  workflow_dispatch:
+  # Publish the container image only when a GitHub Release is published, so the
+  # image version lines up with the release-gated PyPI + npm packages (both fire
+  # on `release: [published]` — see publish-pypi.yml / publish-npm.yml). This
+  # replaces the previous per-commit / after-CI trigger, which shipped an image
+  # on every green main build.
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  packages: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-publish-image:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build and push tokenjam image
+        uses: ./.github/actions/docker-publish
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          image: ghcr.io/${{ github.repository }}
+          context: .
+          dockerfile: Dockerfile

tokenjam-0.5.4/.github/workflows/publish-npm.yml

@@ -0,0 +1,69 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish-npm:
+    if: startsWith(github.ref_name, 'v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        working-directory: sdk-ts
+        run: npm install
+
+      - name: Run tests
+        working-directory: sdk-ts
+        run: npm test
+
+      - name: Build
+        working-directory: sdk-ts
+        run: npm run build
+
+      - name: Publish
+        working-directory: sdk-ts
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  # Publishes the zero-install `npx tokenjam` wrapper (npm-wrapper/, issue #6):
+  # the unscoped `tokenjam` package that shells out to the Python CLI. Separate
+  # job from the SDK publish above so a wrapper failure never blocks @tokenjam/sdk
+  # (and vice versa); both fire on the same `v*` release tag.
+  publish-npm-wrapper:
+    if: startsWith(github.ref_name, 'v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: https://registry.npmjs.org
+
+      # Cheap guard — the wrapper has no test suite (no Python in the JS lane),
+      # so a syntax error would otherwise only surface after publish.
+      - name: Syntax-check launcher
+        working-directory: npm-wrapper
+        run: node -c bin/tj.js
+
+      # Derive the published version from the release tag (v0.5.3 -> 0.5.3) so the
+      # wrapper can never drift from the release being cut — no manual bump needed.
+      # --allow-same-version tolerates package.json already matching the tag.
+      - name: Sync version to release tag
+        working-directory: npm-wrapper
+        run: npm version "${GITHUB_REF_NAME#v}" --no-git-tag-version --allow-same-version
+
+      - name: Publish
+        working-directory: npm-wrapper
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

{tokenjam-0.5.2 → tokenjam-0.5.4}/.gitignore

@@ -50,6 +50,8 @@ tj.toml
 
 # Superpowers skill output (internal planning artifacts, not for OSS)
 docs/superpowers/
+.plans/
+.specs/
 .gstack/
 
 # Per-release pre-release test logs are committed (for reference) — see

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

@@ -146,11 +146,15 @@ Spans enter from two paths, both converging at `IngestPipeline.process()`:
 1. **In-process**: Python SDK `@watch()` + provider patches -> `TjSpanExporter` -> `IngestPipeline`
 2. **HTTP**: TypeScript SDK (or any OTLP client) -> `POST /api/v1/spans` (auth required) -> `IngestPipeline`
 
-Post-ingest hooks run synchronously after each span is written to DB:
-1. `CostEngine.process_span()` — calculates USD cost from token counts
+Post-ingest hooks run after each span is written to DB:
+1. `CostEngine.process_span()` — calculates USD cost from token counts. **Always synchronous** (on the ingest thread) so budget/cost reads immediately after ingest are accurate.
 2. `AlertEngine.evaluate()` — checks all per-span alert rules
 3. `SchemaValidator.validate()` — validates tool outputs against JSON Schema
 
+**Sync vs async hooks (`[alerts] async_hooks`, default `false`).** By default all three hooks run inline on the ingest thread — a config with `async_hooks` unset behaves exactly as the historical synchronous pipeline. When `[alerts] async_hooks = true`, only the *advisory* hooks (`AlertEngine` + `SchemaValidator`) are moved onto a single background worker thread (`TjHookWorker`) fed by a bounded `queue.Queue` (`HOOK_QUEUE_MAXSIZE`, drop-**oldest** overflow policy — dropped spans are logged, never silent); `CostEngine` stays synchronous regardless. This trims span-acknowledgment latency on the hot path at the cost of eventual-consistency for alerts.
+  - **Concurrency:** in async mode the worker thread writes alerts/validations while the ingest thread writes spans/cost. DuckDB uses optimistic concurrency (its **only** write-write conflict is same-row UPDATE overlap → `TransactionException: Conflict on update!`; disjoint-row/-table writes never conflict), so `DuckDBBackend` serializes **writes** through a re-entrant `write_lock` (`self._write_lock`) — every mutating method holds it. The per-thread-cursor **read** path (#124) stays lock-free. Do not remove the write lock; the load-bearing guard is `test_async_hooks_same_row_update_contention` in `tests/synthetic/test_async_hooks_concurrency.py` (many threads incrementing one shared session row — verified to raise `Conflict on update!` when the lock is stubbed with `nullcontext()`); the sibling disjoint-INSERT tests in that file don't catch a lock regression on their own. **Caveat:** direct `db.conn` writes issued from routes *outside* `DuckDBBackend`'s mutating methods (e.g. `alerts.py`'s `UPDATE alerts SET acknowledged`, `set_session_label`) do **not** take the write lock — safe today only because they hit disjoint rows/tables from the worker; a future direct write to a worker-touched table on a hot row would need to acquire `db.write_lock` explicitly.
+  - **Shutdown is lossless:** `IngestPipeline.flush()` blocks until the queue drains (guarded so it can't hang when the worker isn't alive); `close()` flushes then stops the worker via a sentinel (the worker drains to empty before exiting — it does *not* bail at the top of the loop on the shutdown event). Every shutdown path (`tj serve` lifespan, `TjSpanExporter.shutdown`/`force_flush`) flushes before/while closing so no queued alert is dropped.
+
 ### Package Dependency Rules
 
 - `tokenjam/core/` is pure domain logic. **Must never import from `tokenjam.cli` or `tokenjam.api`**. CLI and API import from core, not the reverse.
@@ -159,12 +163,13 @@ Post-ingest hooks run synchronously after each span is written to DB:
 
 ### Key Modules
 
-- **`tokenjam/core/db.py`**: `StorageBackend` protocol + `DuckDBBackend` + `InMemoryBackend` (for tests) + migration runner. Migrations are `(version, sql)` tuples in a `MIGRATIONS` list — never modify existing ones, only append. **Note:** `StorageBackend` doesn't cover every query. Some callers (e.g. `CostEngine`, `cmd_status`) access `db.conn` directly for queries not in the protocol (cost updates, active session lookups). Helper `_row_to_session()` is used to convert raw DuckDB rows.
-- **`tokenjam/core/ingest.py`**: `IngestPipeline` (central hub), `SpanSanitizer` (rejects oversized/malformed spans), `strip_captured_content()`. Post-ingest hooks (cost, alerts, schema) are optional and error-tolerant — hook failures are logged, never propagated.
+- **`tokenjam/core/db.py`**: `StorageBackend` protocol + `DuckDBBackend` + `InMemoryBackend` (for tests) + migration runner. Migrations are `(version, sql)` tuples in a `MIGRATIONS` list — never modify existing ones, only append. **Schema self-heal (#55):** `run_migrations` keys purely on the version INTEGER, so a version recorded-applied under an older/renumbered definition never re-runs and its `ADD COLUMN` silently never lands — then every ingest that writes the missing column hits a DuckDB Binder Error and is dropped (blank Status page). Guard: `run_migrations` calls `ensure_expected_columns` on every open, re-issuing `ADD COLUMN IF NOT EXISTS` for `EXPECTED_ADDITIVE_COLUMNS` regardless of recorded versions. **When you append a migration that adds a column the code reads/writes, add that column to `EXPECTED_ADDITIVE_COLUMNS` too** (and only additive/backward-compatible defs belong there). `tj doctor` surfaces any residual gap ("Schema integrity"); `tj doctor --repair` reconciles it. **Note:** `StorageBackend` doesn't cover every query. Some callers (e.g. `CostEngine`, `cmd_status`) access `db.conn` directly for queries not in the protocol (cost updates, active session lookups). Helper `_row_to_session()` is used to convert raw DuckDB rows.
+- **`tokenjam/core/ingest.py`**: `IngestPipeline` (central hub), `SpanSanitizer` (rejects oversized/malformed spans), `strip_captured_content()`. Post-ingest hooks (cost, alerts, schema) are optional and error-tolerant — hook failures are logged, never propagated. Hooks run synchronously by default; `[alerts] async_hooks = true` moves the alert + schema hooks to a bounded-queue background worker (`TjHookWorker`) with `flush()`/`close()` for lossless shutdown (cost stays sync) — see the Data Flow "Sync vs async hooks" note above.
 - **`tokenjam/core/pricing.py`**: `ModelRates` (frozen dataclass), `load_pricing_table()` (LRU-cached), `get_rates(provider, model)`. Falls back to default rates for unknown models.
 - **`tokenjam/core/cost.py`**: `calculate_cost()` (pure function, rounds to 8dp) + `CostEngine` (post-ingest hook that updates `spans.cost_usd` and `sessions.total_cost_usd` via `db.conn` — see db.py note). Pricing loaded from `tokenjam/pricing/models.toml`. **Cache-read vs cache-write are separate fields** on `NormalizedSpan` (`cache_tokens` = read, `cache_write_tokens` = create); they bill at different rates and `calculate_cost` charges each at its own rate. The early-return no-op guard checks all four token counts (input/output/cache_read/cache_write) — see PR #90 and PR #92 for the cache-only-span and cache-write-on-live-path fixes.
 - **`tokenjam/core/alerts.py`**: `AlertEngine` with 13 alert types, `CooldownTracker` (in-memory, per agent+type, resets on restart), `AlertDispatcher` routing to 6 channel types (stdout, file, ntfy, webhook, Discord, Telegram). `AlertEngine.fire()` is the external entry point for other modules (SchemaValidator, DriftDetector) to fire alerts. Suppressed alerts are still persisted to DB but not dispatched to channels. Hardcoded thresholds: retry loop fires at 4+ identical tool calls in last 6 spans; failure rate fires at >20% errors in last 20 spans (checked every 5th error); session duration default 3600s. Stdout and file channels always include full detail regardless of `include_captured_content` config.
 - **`tokenjam/core/drift.py`**: `DriftDetector` — Z-score based behavioral drift detection, fires at session end.
+- **`tokenjam/core/loop.py`**: Close-the-loop primitive (#53) — the loop-closing half that pairs with the capture half (`tj trace`). Pure domain (no cli/api imports), storage helpers accept a backend or raw conn like `db.set_session_label`. Three additive tables (migration 16): `run_annotations` (append-only human note + optional verdict `good`/`bad`/`mixed`/`unknown` on a run/session — NOT the single-row `session_labels` rename), `expectations` (a named case, optionally promoted `origin_session_id` FROM a bad run), `expectation_runs` (fix-history ledger, one row per rerun with `outcome` ∈ `pass`/`regress`/`unknown`). **Deliberately local-first and NOT an eval-runner**: pass/regress is a recorded *human verdict*, never an automated score (Critical Rule 14); tokenjam does not push to Langfuse (that integration is inbound-only). Surfaces that all hit this one storage: `api/routes/loop.py` (`/sessions/{id}/annotations`, `/expectations`, `/expectations/{id}` with history, `/expectations/{id}/runs`), the `tj loop` CLI group (`cmd_loop.py`, dual-path — api_mode when `tj serve` holds the lock, else direct DuckDB), and the Lens Session-Detail **"Loop" tab**. Product decision recorded in `docs/internal/close-the-loop.md`.
 - **`tokenjam/core/optimize/`**: Package powering `tj optimize` and the `get_optimize_report` MCP tool. Public API re-exported from `__init__.py`: `build_report()` (orchestrator), `report_to_dict()`, `ANALYZER_REGISTRY`, `ANALYZER_ORDER`, plus result dataclasses. Architecture: `registry.py` holds the `@register("name")` decorator and `ANALYZER_REGISTRY` dict; `runner.py` defines `ANALYZER_ORDER` and orchestrates execution; `types.py` holds `AnalyzerContext` + result dataclasses + `MODEL_DOWNGRADE_CAVEAT`. Individual analyzers live in `analyzers/`, each as a single file registering via `@register`. **Registry strings (the user-facing names) and file names are decoupled**:
   - `model_downgrade.py` → `@register("downsize")` — structural candidates (input < 5K tokens AND output < 500 tokens AND tool_calls ≤ 5; never claims quality equivalence, caveat baked into dataclass default)
   - `budget_projection.py` → `@register("budget-projection")` — per-provider cycle spend vs `[budget.<provider>]` ceiling; only fires when budget > 0
@@ -177,6 +182,7 @@ Post-ingest hooks run synchronously after each span is written to DB:
   **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/output_cap.py`** + **`tokenjam/cli/cmd_hook.py`** (`tj hook cap-output`): a PostToolUse output-trim hook that shrinks bloated tool outputs before they enter context, appending to an out-of-band savings sink (`core/savings_log.py`, folded into `tj savings` / `tj context`). It is **DEFAULT-OFF opt-in** (`[hooks.output_cap].enabled = false`; `cmd_onboard.py` does NOT auto-install it) — the code is safe (fail-open, transparent, 58 tests) but the required A/B gate **failed**. **Durable finding (measured, CC 2.1.198): Claude Code already truncates Bash tool output to exactly 30,000 chars *before* the PostToolUse hook ever sees it.** So the addressable bloat per Bash call is tiny (~1,206 tok reclaimed ≈ 0.06% of a ~2M-token cache-read footprint), agents self-mitigate (`| tail`, `grep`, `Read` — which the hook excludes), and 5-trial/arm sonnet A/B showed treatment cost **+5.6%** (run-to-run noise, no quota win). Users who want aggressive trimming opt in with one line + re-run `tj onboard`; a future rework should target what CC does NOT cap (large `WebFetch` bodies, `Read` behind a higher budget). Spec + numbers: `.specs/2026-07-02-tj-output-trim-hook-{design,AB-result}.md`.
 - **`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.
@@ -194,28 +200,34 @@ Post-ingest hooks run synchronously after each span is written to DB:
 - **`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`, `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/core/summarize/`**: Structure-aware prompt summarization (advisory; new feature). `detect.py` classifies prose vs. structure (fenced/inline code, tags, templates, tables); `candidates.py` (+ `catalog.py`/`estimate.py`) powers the `tj summarize list` scan; `wrap.py` is the pure protect→restore algorithm (wrap each structured span behind an id'd `<tj-keep>` marker, restore verbatim by id — structure is a hard guarantee); `session.py` is the no-scratch `prepare`/`check` lifecycle + staging (re-derives the wrap from the live file + a content hash; persists nothing but the staged result); `apply.py` writes a staged rewrite back to the file (default dry-run; `--go` writes) behind an owner + content-hash + symlink guard, with a gzip backup and `undo`; `backup.py` stores the gzipped original + metadata under `~/.tj/summary/backups/`; `delivery.py` is the CLI's automated rewrite step — `claude -p` (subprocess, timeout-guarded) or the Anthropic API (lazy `httpx` + the user's own `TJ_ANTHROPIC_API_KEY`) — plus the "pays for itself" amortization. Pure domain logic — no `tokenjam.cli`/`tokenjam.api` imports (delivery's API path lazily imports `httpx`, its lone outbound dependency).
+- **`tokenjam/mcp/server.py`**: FastMCP stdio server exposing observability data to Claude Code (plus the summarize tools — `list_summarize_candidates`, `summarize_prep`, `summarize_check`, `summarize_apply`, `summarize_undo`; see `core/summarize/`). 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.
 
 ### CLI Commands
 
 `tj --help` lists all commands; most are self-explanatory. Non-obvious ones:
 
+- **`tj quickstart`** (`cmd_quickstart.py`) — the **zero-install / zero-config first run** (issue #6). Opens a **transient `InMemoryBackend`** (nothing written to `~/.tj`, no config read/written, no daemon started or contacted), backfills `~/.claude/projects/*.jsonl` into it via `ingest_claude_code`, then renders quota composition (reusing `core/context_diagnostic.py` from #4) + a session timeline (`core/session_timeline.py`). Output leads with ccusage-parity framing ("reads the same files ccusage does"). It is in `no_db_commands` so the CLI never opens the on-disk DB / trips the daemon lock for it. The intended zero-install invocations are `npx tokenjam` (via the `npm-wrapper/` package — the bare `tj` name is squatted on npm; the wrapper routes bare `npx tokenjam` to `quickstart`) and `uvx --from tokenjam tj quickstart`. `tj onboard` remains the opt-in "go deeper" (daemon/MCP/live) path. **Bare `tj` (no subcommand) prints the branded home screen** (`cli/home.py` `print_home()`, #240) — banner + next-best-action, reading only config presence (never the DB) — not quickstart; `--help`/`--version` are eager and still short-circuit.
 - **`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`) — 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 tokenmaxx`** (`cmd_tokenmaxx.py`) — shareable **quota/efficiency card** (#7; reframed from the old spend-tier card for the June-2026 "tokenminimizing" shift — an efficiency brag, never a spend brag). Leads with the context-COMPOSITION headline pulled from #4's `compute_context_diagnostic` (`tokenjam/core/context_diagnostic.py`): what share of quota went to *overhead* (re-reading history / CLAUDE.md / tool output, i.e. `diag.reread_share`) vs *real work* (uncached input + output). Classifies into 5 efficiency tiers keyed on the overhead share (TokenMinimizer ≤30% / LeanOperator ≤50% / SteadyState ≤70% / ContextHeavy ≤85% / QuotaSink) — lower overhead = leaner = a better tier. **Quota-native (mirrors #5's polarity):** the headline renders as a token-share / "% of cycle tokens" via `core/framing` (the same `_quota_share` path `cmd_context` uses); dollars are demoted to a secondary "Implied API value" line shown ONLY for `api` plans and suppressed for subscription / local / unknown. Needs a **direct DuckDB connection** (reads context composition; can't run against a live `tj serve` — same as `tj context` / `tj quota-audit`). `--weekly` is a 7-day "Quota Wrapped" recap preset. Output is a bordered Panel designed for screenshotting; the action line points at `tj context` (reclaim overhead) or `tj optimize`. Honesty discipline (Rule 14): the efficiency number is a measured token share, never a guaranteed saving.
 - **`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. `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.
 
+- **`tj summarize`** (`cmd_summarize.py`) — structure-aware prompt summarization (advisory; new feature). `list` scans for prompt files worth summarizing (catalog-default; any scope-widening flag opens it to `*.md`) and estimates the per-call token saving — read-only. `prep`/`check` are the mechanism: `prep` wraps a prompt's structure behind id'd `<tj-keep>` markers and emits it for rewriting (CLI manual/copy, or the MCP `summarize_prep`/`summarize_check` tools for in-session rewrites); `check` re-reads + hash-guards the file, restores every block verbatim by id, and stages the result **only if structure survives** (a hard gate). No scratch state — the file on disk is the source of truth; `summarize` is in `no_db_commands` (config-only). `apply` writes a staged rewrite back to the file — default **dry-run** (it prints the unified diff), `--go` writes — guarded by an owner + content-hash + symlink check and a gzip backup; `undo` restores from that backup (refusing on drift). `prep --via claude-p` (your local `claude -p`, no key) or `prep --via api` (Anthropic with your `TJ_ANTHROPIC_API_KEY` + the required `[summarize] api_model`, reporting a "pays for itself" amortization) runs the rewrite for you in one shot — both still pass the `check` gate before staging.
+
+- **`tj pricing list`** (`cmd_pricing.py`) — read-only inspection of the resolved model pricing table. Prints one row per `(provider, model)` with `input` / `output` / `cache_read` / `cache_write` rates and a `source` column (`override` / `packaged`) showing which layer the rate resolved from. Supports `--json` and `--model <substring>` (case-insensitive filter). `pricing` is in `no_db_commands` (config-only). The source derivation lives in `core/pricing.load_pricing_sources()` (public) — the CLI reads it rather than re-deriving precedence; a listed row is always `packaged` or `override` (the `$0.50`/`$2.00` default applies only to models absent from the table, which never appear here). The `set` half of a future `tj pricing set|list` is not built yet (#282 shipped `list` only).
+
 All commands support `--json` for machine-readable output. Commands that query alerts use exit code 1 if active (unacknowledged, unsuppressed) alerts exist.
 
 **CLI testing pattern:** Tests use `click.testing.CliRunner` with `unittest.mock.patch` on `tokenjam.cli.main.load_config` and `tokenjam.cli.main.open_db` to inject an `InMemoryBackend` and test config. See `tests/integration/test_cli.py`. Note: `cmd_doctor` opens its own DuckDB connection via `config.storage.path` to verify writability — in tests you must set this to a real temp path (e.g. `tmp_path / "test.duckdb"`).
 
-**`no_db_commands` in `cli/main.py`:** Commands that don't open the DB at startup — currently `{stop, uninstall, onboard, mcp, demo, policy}`. New commands that read only from config (or do their own DB connection later) should be added to this set so they work when `tj serve` holds the write lock. Tests for these commands can patch `open_db` with `side_effect=AssertionError(...)` to verify they never touch the DB.
+**`no_db_commands` in `cli/main.py`:** Commands that don't open the DB at startup — currently `{stop, uninstall, onboard, mcp, demo, policy, proxy, summarize, pricing}`. New commands that read only from config (or do their own DB connection later) should be added to this set so they work when `tj serve` holds the write lock. Tests for these commands can patch `open_db` with `side_effect=AssertionError(...)` to verify they never touch the DB.
 
 **Test factories:** `tests/factories.py` provides `make_llm_span(billing_account="anthropic", ...)` and `make_session(plan_tier="api", ...)` with safe defaults that preserve existing test behavior. Tests exercising subscription / local / unknown plan-tier rendering paths should pass the field explicitly.
 
@@ -233,6 +245,12 @@ For `GET /api/v1/drift`, if `agent_id` is missing, return `JSONResponse(status_c
 
 Integration tests use `httpx.AsyncClient` with `httpx.ASGITransport(app=app)` against `InMemoryBackend`. Synthetic alert tests use `unittest.mock.MagicMock` for the DB — you must explicitly set up `db.get_recent_spans.return_value` before calling `engine.evaluate()`, and silence channels with `engine.dispatcher.channels = []`.
 
+### StorageBackend parity (serve shim vs DB)
+
+`tj` ships three `StorageBackend` implementations: `DuckDBBackend`, `InMemoryBackend` (tests), and `ApiBackend` — the read-only HTTP shim the CLI uses when `tj serve` holds the DB write-lock. The shim reconstructs objects from JSON, so it repeatedly diverged from the DB backend *silently* (e.g. dropped `cache_write_tokens` on daemon-fetched spans, cache columns zeroed, `get_daily_cost` returning a cumulative total). That whole class of bug (#51) is now guarded by `tests/integration/test_storage_backend_parity.py`, which runs each faithfully-mirrored read method against both the DuckDB backend and the `ApiBackend` shim (over a **real in-process uvicorn server**, not the ASGI shortcut a sync `ApiBackend` can't use) and fails on any divergence.
+
+**Rule: every `StorageBackend` protocol method must be classified in that file** — as parity-covered (`SHIM_PARITY_METHODS` + a spec in `_parity_specs`), a documented `SHIM_KNOWN_GAPS`, deliberately unimplemented (`SHIM_NOT_IMPLEMENTED`), or lifecycle. Adding a protocol method, or teaching the shim a new method, fails CI (`test_every_protocol_method_is_classified` / `test_unimplemented_methods_have_no_silent_shim`) until you classify it — which for a new read method means adding a parity assertion. Don't skip the classification to make CI green; that reopens the exact hole this file closes.
+
 ### Web UI ("TokenJam Lens")
 
 `tokenjam/ui/index.html` is the served dashboard — a **single-file Preact + htm SPA** (no build step, no TypeScript, no client-side router). "TokenJam Lens" is the **brand only**: it appears in `<title>`, the sidebar wordmark, and the OpenAPI title, but never in module names, route paths, or config keys. Screens: **Overview** (the default landing route — a triage front door), Status, Traces, Cost, Alerts, Drift, Optimize, Budget.
@@ -295,20 +313,22 @@ Reinstall behavior: `--claude-code` and `--codex` onboard check `_daemon_already
 
 ## MCP Server
 
-`tj mcp` starts a FastMCP stdio server for Claude Code integration. The connection mode is chosen at startup by `cmd_mcp.py`:
+**The MCP is an SDK / API surface, not a Claude Code / Codex one (#59).** It puts tj *in the request path* — the right place for SDK / API integrations doing real-time enforcement/policy/budgets. It is deliberately **not** wired for Claude Code / Codex subscription users: an in-loop MCP is a per-turn quota burden on them (a measured A/B showed **+36%** model-weighted quota vs a no-tj control). Those users get tj **out-of-band**: the zero-token statusline (`tj statusline`, wired by `tj onboard --claude-code`) plus OTel telemetry ingest. `tj mcp` still works for anyone who invokes it; onboarding just no longer defaults CC/Codex users into it.
+
+`tj mcp` starts a FastMCP stdio server. The connection mode is chosen at startup by `cmd_mcp.py`:
 1. If `tj serve` is reachable on `config.api.{host,port}`, MCP proxies to it via HTTP (live ingest visible).
 2. Otherwise it tries to spawn `tj serve` in the background and waits up to 10s for the port.
 3. If neither works, it falls back to a **read-only DuckDB connection** — read tools still work, but newly ingested spans won't appear until restart.
 4. If no config file is found, `init()` is skipped and tools return a no-config sentinel.
 
-To wire into Claude Code locally: `claude mcp add tj --scope user -- tj mcp` (the `--claude-code` and `--codex` onboard flows do this automatically when the `claude` CLI is on PATH; `--codex` also writes `[mcp_servers.tj]` to `~/.codex/config.toml`).
+SDK / API users who want the in-loop tools can wire it manually: `claude mcp add tj --scope user -- tj mcp`. The `--claude-code` and `--codex` onboard flows **no longer** register the MCP (they wire the out-of-band statusline / OTel instead), and a re-onboard retires any tj-managed `[mcp_servers.tj]` block a previous version wrote to `~/.codex/config.toml`.
 
 ## Codex CLI Integration
 
-`tj onboard --codex` writes `[otel]` and `[mcp_servers.tj]` blocks to `~/.codex/config.toml`. Notes:
+`tj onboard --codex` writes an `[otel]` block to `~/.codex/config.toml` (out-of-band telemetry only). It does **not** register the tj MCP for Codex (#59) — Codex has no statusline surface, so tj stays fully out-of-band via OTel + the `tj` CLI; a re-onboard retires any `[mcp_servers.tj]` block a previous version wrote. Notes:
 - Codex hardcodes `service.name=codex_exec` in its binary and silently ignores `[otel.resource]`, so onboarding does **not** write that block — all Codex traces land under the `codex_exec` agent ID regardless of project. Onboarding is one-time global, not per-project.
 - Codex emits OTLP **logs** (not spans) to `/v1/logs`. `tokenjam/api/routes/logs.py` converts Codex events (`sse_event`, `user_prompt`, `tool_decision`, `tool_result`, `api_request`) into normalized spans for cost/drift/alerting. Event name is read from `attrs["event.name"]` when the OTLP body is empty (Codex schema quirk); epoch `timeUnixNano=0` falls back to `attrs["event.timestamp"]` ISO-8601. The `/v1/logs` endpoint also silently accepts `resourceSpans`/`resourceMetrics` because Codex's exporter reuses one endpoint for all signal types.
-- Re-running `tj onboard --codex` is a no-op only when both `[otel]` and `[mcp_servers.tj]` are present in `~/.codex/config.toml`. Re-onboarding either Codex or Claude Code cross-syncs the ingest secret into the other's config if it's already configured.
+- Re-running `tj onboard --codex` is a no-op only when `[otel]` is already present in `~/.codex/config.toml` (the check is `[otel]`-only now); a re-onboard also strips any legacy `[mcp_servers.tj]` block, since tj is out-of-band for Codex. Re-onboarding either Codex or Claude Code cross-syncs the ingest secret into the other's config if it's already configured.
 
 ## Examples Convention
 
@@ -331,7 +351,7 @@ The packaged table is community-maintained: submit a PR editing `tokenjam/pricin
 - **`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.)
+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. Read-only inspection ships via `tj pricing list` (see CLI Commands; #282). The `set` half — a `tj pricing set` to edit overrides without hand-writing TOML — is not built yet.
 
 ## CI
 
@@ -364,6 +384,8 @@ PyPI and npm publishes are triggered by GitHub Release events (`.github/workflow
 2. Merge to `main`.
 3. Create a GitHub Release with tag `vX.Y.Z` (e.g. via `gh release create vX.Y.Z --generate-notes`). Publishing the release fires both workflows.
 
+`publish-npm.yml` has **two independent jobs**: `publish-npm` (the `@tokenjam/sdk` package from `sdk-ts/`, version read from `sdk-ts/package.json`) and `publish-npm-wrapper` (the unscoped `tokenjam` wrapper from `npm-wrapper/`). The wrapper job **derives its published version from the release tag** (`vX.Y.Z` → `X.Y.Z`, via `npm version --no-git-tag-version --allow-same-version`), so the wrapper can never drift from the release and needs no manual version bump — `npm-wrapper/package.json`'s literal is only a floor for local `npm pack`. Both jobs use `secrets.NPM_TOKEN`, which must be able to publish the unscoped `tokenjam` name in addition to the `@tokenjam` scope.
+
 If a version already exists on PyPI or npm, the publish workflow fails with 403 — bump again rather than retrying.
 
 ## Packaging
@@ -372,6 +394,8 @@ Build system is hatchling. `[tool.hatch.build.targets.wheel] packages = ["tokenj
 
 Key runtime dependency: `pytz` is required by DuckDB for `TIMESTAMPTZ` column handling — it's listed explicitly in `dependencies` because DuckDB doesn't declare it on all platforms.
 
+**The `tj` npm wrapper** (`npm-wrapper/`, issue #6) is a separate, dependency-free npm package named `tokenjam` (unscoped, distinct from the `@tokenjam/sdk` SDK package; the bare `tj` name is already taken on npm by an unrelated pub/sub library, so the PACKAGE is `tokenjam` while the installed BIN is still `tj`) whose only job is to make `npx tokenjam` work. `bin/tj.js` shells out to the Python CLI via the first available runner (`uvx --from tokenjam tj` → `pipx run --spec tokenjam tj` → an installed `tj` on PATH) and passes every arg through. **It is published to npm by the `publish-npm-wrapper` job in `publish-npm.yml`** (#65), which derives the published version from the release tag — you do **not** need to bump `npm-wrapper/package.json` on release (the CI overwrites it from the tag; keep the literal roughly current so local `npm pack` is sane). `npm-wrapper/` has no CI test (no Python to drive in the JS lane); the publish job runs a `node -c bin/tj.js` syntax guard, and you can validate the same locally with `node -c npm-wrapper/bin/tj.js`.
+
 **Optional extras** (declared under `[project.optional-dependencies]`):
 - `tokenjam[bloat]` — `llmlingua>=0.2`, used by the Trim analyzer. Pulls PyTorch + transformers (~2GB). Kept out of base install. The analyzer self-registers without the extra installed; the deferred `import llmlingua` inside the analysis function body raises a typed message pointing the user at the install command.
 - Framework extras `[langchain]`, `[crewai]`, `[autogen]`, `[litellm]` for SDK patches.
@@ -388,6 +412,7 @@ Key runtime dependency: `pytz` is required by DuckDB for `TIMESTAMPTZ` column ha
   - [`cache.md`](docs/optimize/cache.md) — `cache` (current caching ratio) + `cache-recommend` (Anthropic-only breakpoint suggestions)
   - [`script.md`](docs/optimize/script.md) — `script` clustering by `(tool_name, arg_shape)` signature (file: `workflow_restructure.py`)
   - [`trim.md`](docs/optimize/trim.md) — LLMLingua-2 token-significance classifier (`trim`, file: `prompt_bloat.py`), install + capture requirements, performance numbers
+  - [`subagent.md`](docs/optimize/subagent.md) — per-subagent right-sizing (`subagent`, file: `subagent_rightsizing.py`), Claude Code-only (keys off `sub_agent_id`, populated only by CC backfill)
 - **[AGENTS.md](AGENTS.md)** — codebase conventions for contributors (referenced from the top-level README).
 - **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.

tokenjam-0.5.4/Dockerfile

@@ -0,0 +1,44 @@
+# ----- Build stage -----
+FROM python:3.12-slim AS builder
+
+WORKDIR /src
+RUN pip install --no-cache-dir build
+
+COPY pyproject.toml README.md ./
+COPY tokenjam ./tokenjam
+COPY incidents ./incidents
+
+RUN python -m build --wheel --outdir /dist
+
+# ----- Runtime stage -----
+FROM python:3.12-slim AS runtime
+
+LABEL org.opencontainers.image.title="tokenjam" \
+      org.opencontainers.image.description="Local-first OTel-native observability for autonomous AI agents" \
+      org.opencontainers.image.source="https://github.com/Metabuilder-Labs/tokenjam" \
+      org.opencontainers.image.licenses="MIT"
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# Install the wheel from stage 1
+COPY --from=builder /dist/*.whl /tmp/
+RUN pip install --no-cache-dir "$(ls /tmp/*.whl)[mcp]" && rm -rf /tmp/*.whl
+
+# Run as a non-root user
+RUN useradd --create-home --uid 10001 tokenjam \
+    && mkdir -p /home/tokenjam/.config/tj /home/tokenjam/.tj \
+    && chown -R tokenjam:tokenjam /home/tokenjam
+USER tokenjam
+WORKDIR /home/tokenjam
+
+# Mounting a volume to persist data across container restarts.
+VOLUME ["/home/tokenjam/.config/tj", "/home/tokenjam/.tj"]
+
+# Web UI + REST API served by `tj serve`.
+EXPOSE 7391
+
+ENTRYPOINT ["tj"]
+CMD ["serve", "--host", "0.0.0.0", "--port", "7391"]