docs: command-only smoke-test blocks + fix trim/jsonc expectations (#3,#10,#13)

Smoke-test playbook (tests/manual-new-release-tests.md):

- #3 (and #8/#9/#11/#12/#14/#16 — same root cause): code blocks are now
  command-only; the inline "# comments" and "# [ ]" checklists that the markdown
  copy button was pulling into copied commands moved to prose / "- [ ]" lists
  around each block. Added a note explaining the convention.
- #10: corrected the Section 4 trim expectation — with [capture] prompts=false
  (default), trim checks the capture prereq first and prints the capture hint,
  NOT the tokenjam[bloat] install hint (only reachable once capture is on).
- #13: export file is "claude-code-<date>.jsonc", not ".json".

Doc-only; no code changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: anilmurty

tests/manual-new-release-tests.md

@@ -2,50 +2,43 @@
 
 Run this after a new release publishes to PyPI to verify it works end-to-end. This is intentionally lighter than `manual-pre-release-testing.md` — the multi-project / secret-rotation / theme-toggle detail lives there and was exercised on the branch before merge. Here we're confirming the published artifact actually installs and the core surfaces are alive.
 
+> **Code blocks are command-only on purpose.** Explanations and checklists live in
+> prose around each block so the markdown "copy" button copies a runnable command,
+> not a comment (smoke-test finding #3).
+
 ## Prerequisites
 
-- `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` in `~/tokenjam/.env.local`
-- Sourced before running
+- `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` in `~/tokenjam/.env.local`, sourced before running.
+- The example scripts import provider SDKs (`anthropic`, `openai`, `litellm`) that are **not** tokenjam dependencies. A `pipx install` isolates tokenjam in its own venv, so those SDKs must be injected into that venv and the examples run with its interpreter (Steps 3 and 8 do this).
 
 ## 1. Install the published release
 
+`tj uninstall` removes data/config/daemon but **not** the package; `pipx uninstall` then removes the venv so `pipx install --force` rebuilds it pristine. The bare `pip3 install --upgrade tokenjam` path fails on system Python (PEP 668) — pipx is the path we ship docs telling users to use, so it's what we verify.
+
 ```bash
-tj uninstall --yes 2>/dev/null   # removes data, config, daemon
-pipx uninstall tokenjam 2>/dev/null   # remove the pipx venv so --force gets a pristine one
+tj uninstall --yes 2>/dev/null
+pipx uninstall tokenjam 2>/dev/null
 rm -rf ~/.tj ~/.config/tj .tj
-
-# Recommended install path (PEP 668-safe on Homebrew Python and
-# Debian 12+/Ubuntu 24+). `--force` so we reinstall even if a prior
-# version somehow survived above.
 pipx install --force tokenjam
 tj --version
-
-# Older `pip3 install --upgrade tokenjam` path still works inside
-# a clean venv but fails on system Python — that's the bug pipx
-# solves, and verifying pipx is what we ship docs telling users to do.
 ```
 
 **Pass criteria:** version matches the release being tested. `pipx install` reports a fresh venv (not "Installing to existing venv 'tokenjam'") thanks to the `pipx uninstall` step.
 
-## 2. Onboard (sets plan tier via the integration flow)
+## 2. Onboard
 
-Bare `tj onboard` only prompts for daily budget — plan tier is set by the integration onboarding flows (`--claude-code` / `--codex`) per the v0.3.x design. For the smoke pass we onboard against Claude Code to write the `plan` field:
+`tj onboard` prompts for daily budget and plan tier; `--plan api` sets the plan non-interactively (so plan-aware dollar rendering kicks in for the rest of the smoke), and `--no-daemon` skips the launchd/systemd install for this pass. We onboard against Claude Code here so the plan lands in the global config.
 
 ```bash
 tj onboard --claude-code --plan api --no-daemon
-# --plan api → writes `plan = "api"` non-interactively (so dollar rendering
-#              kicks in for the rest of the smoke)
-# --no-daemon → skip launchd/systemd install for this smoke pass
-```
-
-```bash
 grep '^plan = ' ~/.config/tj/config.toml
-# [ ] plan field is set under [budget.anthropic]; no auto-written usd = 200
 ```
 
+**Pass criteria:** the `plan` field is set under `[budget.anthropic]`; no auto-written `usd = 200`.
+
 ## 3. Drive an example + verify CLI
 
-The example scripts import provider SDKs (`anthropic`, `openai`, ...) that are not tokenjam dependencies. `pipx install tokenjam` isolates tokenjam in its own venv, so the SDKs aren't importable from system Python either. Inject them into the pipx venv and run via that interpreter:
+Inject the provider SDK into the pipx venv and run the example with that interpreter (see Prerequisites).
 
 ```bash
 pipx inject tokenjam anthropic openai
@@ -55,70 +48,81 @@ cd ~/tokenjam
 source .env.local
 "$PIPX_PY" examples/single_provider/anthropic_agent.py
 
-tj status        # agent with cost > $0, tokens > 0
-tj traces        # waterfall renders
-tj cost --since 1h    # real USD values (not $0.000000)
-tj doctor             # exit 0 or 1 (warnings ok)
+tj status
+tj traces
+tj cost --since 1h
+tj doctor
 ```
 
+**Pass criteria:**
+
+- [ ] `tj status` shows the agent with cost > $0 and tokens > 0
+- [ ] `tj traces` renders the waterfall
+- [ ] `tj cost --since 1h` shows real USD values (not `$0.000000`)
+- [ ] `tj doctor` exits 0 or 1 (warnings ok)
+
 ## 4. Cost-optimization analyzers (smoke — verify each runs)
 
 ```bash
-tj optimize                                # all analyzers
-tj optimize downsize      # Downsize
-tj optimize cache       # Cache (efficacy)
-tj optimize cache-recommend      # Cache (recommend) — surfaces "enable capture.prompts" if not set
-tj optimize script # Script — likely no candidates on a fresh DB
-tj optimize trim         # Trim — should print install hint without [bloat] extra
-
-# Caveat enforcement on the downgrade finding
+tj optimize
+tj optimize downsize
+tj optimize cache
+tj optimize cache-recommend
+tj optimize script
+tj optimize trim
+
 tj optimize --json | python3 -c \
   "import json,sys;r=json.load(sys.stdin);d=r.get('downgrade');assert d is None or 'Candidate-flagging heuristic' in d['caveat'];print('ok: caveat enforced')"
 
-# Plan-tier metadata in JSON
 tj optimize --json | python3 -c \
   "import json,sys;d=json.load(sys.stdin);assert 'plan' in d and 'pricing_mode' in d;print('ok')"
 ```
 
-**Pass criteria:** every positional analyzer name runs without crashing. Optional analyzers (`cache-recommend`, `trim`) surface clear hints when their prereqs aren't met instead of erroring.
+**Pass criteria:** every positional analyzer name runs without crashing, and the two JSON checks print `ok`. Optional analyzers surface a clear hint rather than erroring when a prereq isn't met:
+
+- `cache-recommend` and `trim` both require `[capture] prompts = true`. With capture off (the default), each checks that prereq **first**, so `trim` prints the capture hint — **not** the `tokenjam[bloat]` install hint (you only reach the `[bloat]` hint once capture is on but the extra is missing). `script` likely reports no candidates on a fresh DB.
 
 ## 4b. TokenMaxx tier classification
 
 ```bash
 tj tokenmaxx
-# [ ] Bordered "TokenJam TokenMaxxing Report" panel renders
-# [ ] On api plan: shows absolute spend; no multiplier line
-# [ ] Action line surfaces either downsize savings or "no obvious
-#     savings flagged yet" (both are valid)
 
-# Verify the JSON tier label is one of the six valid v0.3.4 tiers.
 tj tokenmaxx --json | python3 -c \
   "import json,sys;d=json.load(sys.stdin);ok={'TokenSipper','TokenModerator','TokenMaxxer','TokenSuperMaxxer','TokenMegaMaxxer','TokenGigaMaxxer'};assert d['tier'] in ok,d['tier'];print('ok:',d['tier'])"
+```
+
+Check the rendered report:
 
-# Reconfigure to a subscription plan and re-run — the multiplier line
-# should appear. Pick whichever plan matches your test config.
+- [ ] Bordered "TokenJam TokenMaxxing Report" panel renders
+- [ ] On the `api` plan: shows absolute spend, no multiplier line
+- [ ] Action line surfaces either the downsize savings or "no obvious savings flagged yet" (both valid)
+
+Then reconfigure to a subscription plan and re-run to confirm the multiplier line appears (use whichever plan matches your test config), then flip back to `api` so later steps render dollar figures:
+
+```bash
 tj onboard --claude-code --reconfigure --plan max_5x
 tj tokenmaxx
-# [ ] Multiplier line "That's N× your Max 5x plan cost ($100/mo flat)."
-# [ ] Tier may shift if the multiplier crosses a boundary
-
-# Flip back to api so subsequent steps render dollar figures.
 tj onboard --claude-code --reconfigure --plan api
 ```
 
-**Pass criteria:** the report renders without crashing, the JSON `tier` field carries one of the 6 v0.3.4 tier names, and the multiplier line appears under a subscription plan.
+- [ ] Multiplier line "That's N× your Max 5x plan cost ($100/mo flat)."
+- [ ] Tier may shift if the multiplier crosses a boundary
+
+**Pass criteria:** the report renders without crashing, the JSON `tier` field carries one of the 6 tier names, and the multiplier line appears under a subscription plan.
 
 ## 5. Backfill adapters (smoke against committed fixtures)
 
 ```bash
 tj backfill langfuse --source-file tests/fixtures/langfuse_real_response.json
 tj backfill helicone --source-file tests/fixtures/helicone_real_response.json
 tj backfill otlp --source-file tests/fixtures/otlp_sample.json
-# Re-run any of them — must be idempotent
 tj backfill langfuse --source-file tests/fixtures/langfuse_real_response.json
-# [ ] "skipped N already present" on the re-run
 ```
 
+The final line re-runs langfuse to check idempotency:
+
+- [ ] The re-run reports "skipped N already present"
+
 If this machine has Claude Code history:
 
 ```bash
@@ -129,33 +133,35 @@ ls ~/.claude/projects/ >/dev/null 2>&1 && tj backfill claude-code
 
 ```bash
 tj cost --since 7d --compare previous
-# [ ] Current + Previous summary lines, cost/token delta lines
 
 tj optimize --export-config claude-code
 ls ~/.config/tokenjam/exports/
-# [ ] claude-code-<date>.json file present
-# [ ] Contains "STRUCTURAL HEURISTIC ONLY" caveat comments
 ```
 
+- [ ] `--compare` prints Current + Previous summary lines and cost/token delta lines
+- [ ] A `claude-code-<date>.jsonc` file is present (it's JSONC — it carries comments)
+- [ ] It contains the "STRUCTURAL HEURISTIC ONLY" caveat comments
+
 ## 7. Policy list
 
 ```bash
 tj policy list
-# [ ] Table renders with POLICY / SETTING / SOURCE columns
-# [ ] "read-only preview" footer note
 ```
 
+- [ ] Table renders with POLICY / SETTING / SOURCE columns
+- [ ] "read-only preview" footer note
+
 ## 8. Server + Web UI
 
+Start the server, inject `litellm` into the pipx venv (one-time per smoke run), drive the litellm example over the HTTP transport, and confirm `tj cost` works via the API fallback while the server holds the DB lock:
+
 ```bash
 tj serve &
 sleep 2
 
-# HTTP fallback while server holds the lock.
-# Inject litellm into the pipx venv first (one-time per smoke run):
 pipx inject tokenjam litellm
 "$PIPX_PY" examples/single_provider/litellm_agent.py
-tj cost --since 1h   # works via API fallback
+tj cost --since 1h
 
 open http://127.0.0.1:7391/
 ```
@@ -167,12 +173,12 @@ Spot-check:
 - [ ] Cost page shows non-zero USD values
 - [ ] Sidebar theme toggle works
 
-### Offline-UI verification (v0.3.4 — PR #88)
+### Offline-UI verification (PR #88)
 
 Open Chrome DevTools (or your browser's equivalent) → **Network tab** → reload `http://127.0.0.1:7391/`.
 
 - [ ] **Zero failed requests** to `fonts.googleapis.com`, `fonts.gstatic.com`, `esm.sh`, or `tokenjam.dev`
-- [ ] Dashboard interactivity works (sidebar nav, tab switches) — proves the vendored Preact / htm under `/ui/vendor/` is being served, not loading from the CDN
+- [ ] Dashboard interactivity works (sidebar nav, tab switches) — proves the vendored Preact / htm / uPlot under `/ui/vendor/` is being served, not loading from a CDN
 - [ ] Favicon renders (data: URL, no external fetch)
 
 Bonus: turn off wifi entirely, hard-refresh, and confirm the page still renders + the JS still hydrates. The whole dashboard must work air-gapped.
@@ -181,47 +187,49 @@ Bonus: turn off wifi entirely, hard-refresh, and confirm the page still renders
 tj stop
 ```
 
-## 9. Cache cost-correctness (v0.3.4 — PRs #90 + #92)
+## 9. Cache cost-correctness (PRs #90 + #92)
 
-Cache-only spans (cache_read > 0, input/output = 0) used to be costed at $0. Cache-creation tokens on the live OTLP path used to be silently dropped. Both fixed in v0.3.4.
+Cache-only spans (cache_read > 0, input/output = 0) used to be costed at $0, and cache-creation tokens on the live OTLP path used to be silently dropped — both fixed. The spans table gained `cache_write_tokens` in migration 5.
 
 ```bash
-# Spans table now has cache_write_tokens (migration 5).
 duckdb ~/.tj/telemetry.duckdb "PRAGMA table_info(spans)" 2>/dev/null \
   | grep cache_write_tokens \
   && echo "ok: cache_write_tokens column present"
 
-# Any captured Anthropic cache-hit span should have non-zero cost_usd.
 duckdb ~/.tj/telemetry.duckdb "
-  SELECT COUNT(*) AS hits,
-         MIN(cost_usd) AS min_cost
+  SELECT COUNT(*) AS hits, MIN(cost_usd) AS min_cost
   FROM spans
   WHERE cache_tokens > 0
     AND (input_tokens = 0 OR input_tokens IS NULL)
     AND (output_tokens = 0 OR output_tokens IS NULL)
 " 2>/dev/null
-# [ ] If hits > 0: min_cost > 0 (cache hits ARE being costed; was $0 pre-0.3.4)
-# [ ] If hits = 0: this release's runs didn't trigger a pure cache-only span — fine, unit tests cover the path
 ```
 
-If you don't have `duckdb` CLI installed, skip the SQL checks — the unit + synthetic tests covering these paths run in CI and are the canonical verification.
+- [ ] `cache_write_tokens` column is present on the spans table
+- [ ] If `hits > 0`: `min_cost > 0` (cache hits ARE costed; was $0 pre-fix)
+- [ ] If `hits = 0`: this release's runs didn't trigger a pure cache-only span — fine; unit tests cover the path
+
+If you don't have the `duckdb` CLI installed, skip the SQL checks — the unit + synthetic tests covering these paths run in CI and are the canonical verification.
 
 ---
 
 ## Claude Code integration (smoke)
 
+Onboard against Claude Code (substitute your actual plan), confirm the OTEL env + project tracking landed, and that a re-run is a quiet no-op. Backfill runs automatically during onboard, so history should be queryable afterward.
+
 ```bash
-tj onboard --claude-code --plan max_5x   # substitute your actual plan
+tj onboard --claude-code --plan max_5x
 cat ~/.claude/settings.json | python3 -m json.tool | grep -E "OTEL_LOGS_EXPORTER|OTEL_EXPORTER_OTLP_ENDPOINT"
-cat ~/.config/tj/projects.json   # current cwd present
+cat ~/.config/tj/projects.json
 
-# Re-run is a quiet no-op
-tj onboard --claude-code --plan max_5x   # substitute your actual plan
+tj onboard --claude-code --plan max_5x
 
-# Backfill ran automatically during onboard — verify history is present
 tj cost --since 30d --agent claude-code-tokenjam || true
 ```
 
+- [ ] `settings.json` carries the OTEL exporter env; `projects.json` lists the current cwd
+- [ ] The second onboard is a quiet no-op
+
 ## Codex integration (smoke)
 
 ```bash
@@ -233,27 +241,29 @@ SERVER_SECRET=$(grep ingest_secret ~/.config/tj/config.toml | sed 's/.*= "//' |
 CODEX_SECRET=$(grep -oE 'Bearer [^"]+' ~/.codex/config.toml | sed 's/Bearer //')
 [ "$SERVER_SECRET" = "$CODEX_SECRET" ] && echo "ok: secret synced"
 
-# If codex CLI is installed
 codex exec "say hello" 2>/dev/null && tj traces --agent codex_exec
 
 tj stop
 ```
 
+- [ ] `ok: secret synced` prints (the Codex Bearer token matches the server's ingest secret)
+- [ ] If the `codex` CLI is installed, a `codex exec` run shows up under `tj traces --agent codex_exec`
+
 ---
 
 ## Pass criteria summary
 
 | Step | Pass criteria |
 |------|--------------|
 | 1 | `pipx install --force tokenjam` succeeds, version matches release |
-| 2 | Onboard prompts for plan tier; config records it; no auto `usd = 200` written |
+| 2 | Onboard records the plan tier; no auto `usd = 200` written |
 | 3 | Example runs without DB-lock errors; CLI shows real USD values |
 | 4 | All optimize analyzers run; caveat appears in downgrade JSON; `plan` + `pricing_mode` in JSON output |
-| 4b | `tj tokenmaxx` renders the bordered report panel; JSON `tier` is one of the 6 v0.3.4 tier names; subscription plan shows multiplier line |
+| 4b | `tj tokenmaxx` renders the bordered report panel; JSON `tier` is one of the 6 tier names; subscription plan shows multiplier line |
 | 5 | All three backfill adapters ingest from fixtures; re-runs are idempotent |
-| 6 | `--compare previous` produces a diff report; `--export-config` writes a snippet with caveat comments |
+| 6 | `--compare previous` produces a diff report; `--export-config` writes a `.jsonc` snippet with caveat comments |
 | 7 | `tj policy list` renders the unified table |
-| 8 | `tj serve` starts, web UI loads, HTTP fallback works while server holds lock; **zero external requests in DevTools Network tab** (offline-UI fix shipped in v0.3.4) |
+| 8 | `tj serve` starts, web UI loads, HTTP fallback works while server holds lock; **zero external requests in DevTools Network tab** |
 | 9 | `cache_write_tokens` column present on the spans table (migration 5); cache-hit spans show non-zero cost_usd |
 | Claude Code | Onboard writes settings.json + projects.json; re-run is a no-op |
 | Codex | Onboard writes `[otel]` + `[mcp_servers.tj]` to codex config; secret synced |