@polderlabs/bizar 8.0.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/bizar-dash/skills/agent-browser/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: agent-browser
+description: Self-healing browser automation CLI for AI agents — drives Chrome for Testing via 100+ typed CLI commands, native MCP stdio server, snapshot-based element refs (`@e2`), and a plugin system.
+version: "1.0.0"
+status: active
+created_by: sprint MS-2026-05
+use_count: 0
+failure_count: 0
+last_used: null
+---
+
+# agent-browser
+
+`agent-browser` is a **native Rust CLI** from [vercel-labs](https://github.com/vercel-labs/agent-browser)
+(~38K★) that exposes a complete browser-automation surface to AI agents.
+
+## Why this skill
+
+- Bizar dispatches a browser-primary agent (`agent-browser`) for any task
+  that requires real-browser verification of a web app: clicking buttons,
+  filling forms, taking screenshots, reading accessibility trees.
+- agent-browser replaces the v5.x `browser-harness` (Python + uv) which
+  was slow, fragile, and lacked MCP integration. See `docs/migration-guide.md`
+  for the migration rationale.
+
+## When to use
+
+Use this skill when the task requires:
+
+- "Take a screenshot of `<url>`"
+- "Click button X, verify the result"
+- "Fill in the login form, click submit"
+- "Find a bug that's only visible in the rendered page"
+- "Verify the dashboard's tab navigation works end-to-end"
+
+Do not use this skill for:
+
+- Editing code (the browser-primary agent has edit/write **denied**)
+- Long-running background automation (use Cline agent teams instead)
+- Non-Chromium browsers (Chrome for Testing only)
+
+## Quick start
+
+```bash
+# Install (one-time)
+npm install -g agent-browser
+agent-browser install        # downloads Chrome for Testing
+
+# Ensure the daemon is up
+bizar browser-agent-up start # wrapper around cli/agent-browser-up.sh
+
+# Drive the browser
+agent-browser open example.com
+agent-browser snapshot --json
+agent-browser click @e2
+agent-browser fill @e3 "hello"
+agent-browser screenshot page.png
+agent-browser close
+```
+
+## Command reference
+
+The full command set has 100+ commands. The most common:
+
+| Command | Purpose |
+| --- | --- |
+| `agent-browser open <url>` | Launch + navigate (aliases: `goto`, `navigate`) |
+| `agent-browser read [url]` | Fetch agent-readable text from URL or active tab |
+| `agent-browser snapshot [--json]` | Accessibility tree with refs (`@e1`, `@e2`, ...) |
+| `agent-browser click <sel>` | Click — accepts ref (`@e2`) or selector (`#submit`) |
+| `agent-browser fill <sel> <text>` | Clear + fill |
+| `agent-browser type <sel> <text>` | Type without clear |
+| `agent-browser press <key>` | Press key (Enter, Tab, Control+a) |
+| `agent-browser get <what> <sel>` | Get text / html / attr |
+| `agent-browser screenshot <path>` | Screenshot to file (PNG) |
+| `agent-browser find role/label/text` | Semantic find (returns ref) |
+| `agent-browser wait <what>` | Wait for selector / load / network idle |
+| `agent-browser eval <js>` | Evaluate JavaScript |
+| `agent-browser tab list/open/close/switch` | Tab management |
+| `agent-browser close` | Close the browser |
+| `agent-browser doctor` | Self-diagnostics |
+| `agent-browser mcp` | Start MCP stdio server |
+| `agent-browser chat "..."` | Natural-language browser tasks |
+| `agent-browser skills list/get` | Bundled skills (this skill is in the catalog) |
+
+## MCP integration
+
+Cline registers `agent-browser` as an MCP tool server at session start via
+`.cline/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "agent-browser",
+      "args": ["mcp", "--tools", "core"]
+    }
+  }
+}
+```
+
+Tool profiles:
+
+- `core` — Default. Navigation, snapshots, interaction, waits, reads, screenshots,
+  JavaScript eval, close, tab basics, profile discovery. Small MCP context.
+- `network` — Routes, request inspection, HAR, headers, credentials, offline.
+- `state` — Cookies, storage, auth, sessions, profiles, skills.
+- `debug` — Console/errors, tracing, profiling, recording, clipboard, plugins,
+  doctor, dashboard, install, upgrade, chat, batch.
+- `tabs` — Back/forward/reload, tabs, windows, frames, dialogs.
+- `react` — React tree/inspect, vitals, pushstate.
+- `mobile` — Viewport/device/geolocation, touch, swipe, mouse, keyboard.
+- `all` — Every MCP tool.
+
+## Plugin system
+
+```json
+{
+  "plugins": [
+    {
+      "name": "vault",
+      "command": "agent-browser-plugin-vault",
+      "capabilities": ["credential.read"]
+    }
+  ]
+}
+```
+
+## Patterns
+
+### Stable selectors
+
+Prefer **refs** (`@e2`) over CSS selectors — refs survive snapshot churn.
+
+```bash
+agent-browser snapshot --json > snap.json
+agent-browser click @e2
+```
+
+### Headless vs headed
+
+Default is headless. Use `--headed` for visual debugging.
+
+### Persistent profile
+
+Set `--profile <dir>` to keep cookies / storage across runs. Default
+is `~/.agent-browser/profile`.
+
+### Natural-language chat
+
+```bash
+AI_GATEWAY_API_KEY=... agent-browser chat "summarize the page at /pricing"
+```
+
+This streams a structured response from the configured LLM provider.
+
+## Configuration
+
+Layered config (lowest → highest priority):
+
+1. `~/.agent-browser/config.json` — user-level
+2. `./agent-browser.json` — project-level
+3. `AGENT_BROWSER_*` env vars
+4. CLI flags
+
+## Lessons / known limitations
+
+- Chrome for Testing only (no Firefox / Safari / WebKit).
+- `agent-browser install` requires network access to download Chrome
+  the first time (~150MB).
+- The chat endpoint requires `AI_GATEWAY_API_KEY` from Vercel.
+- The daemon binds to `127.0.0.1` by default; use `--host` to expose
+  publicly (only on trusted networks).
+
+## See also
+
+- [config/agents/agent-browser.md](../../config/agents/agent-browser.md) — the Cline primary agent
+- [cli/agent-browser-up.sh](../../cli/agent-browser-up.sh) — idempotent starter
+- https://github.com/vercel-labs/agent-browser — upstream README
+- [docs/migration-guide.md](../../docs/migration-guide.md) — browser-harness → agent-browser rationale
+- [research/agent-harness-survey/round-9-memory/bizar-memory-redesign.md](../../research/agent-harness-survey/round-9-memory/bizar-memory-redesign.md)

package/.claude/worktrees/kanban-overhaul/bizar-dash/skills/bizar/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: biz
+description: Use when working with, configuring, troubleshooting, or understanding the Bizar Norse-pantheon multi-agent system for cline. Covers Odin routing, agent tiers, cost-aware dispatch, parallel implementation, and common failure modes.
+---
+
+# Bizar
+
+Norse-pantheon multi-agent system for cline. 13 agents across 4 cost tiers, with Odin as a pure router that always splits implementation across parallel subagents.
+
+## Architecture
+
+Odin is the only primary agent. Every request hits him first. He NEVER does work - he decomposes into parallel streams and dispatches to subagents.
+
+All subagents use Obsidian vault memory with per-project vaults. Call `obsidian_list_vaults` at session start to discover available vaults, determine the project name, and use the matching `<project-name>` vault. The default vault is for general/cross-project knowledge only.
+
+## Agent Reference
+
+| Agent | Model | Tier | Cost | When to Route |
+|---|---|---|---|---|
+| Odin | MiniMax-M3 | Router | $0.30/M · $1.20/M | Primary entry point. Decomposes and dispatches. |
+| Mimir | DeepSeek V4 Flash | Free | $0 | Deep codebase research, Semble-first exploration, docs analysis |
+| Heimdall | DeepSeek V4 Flash | Free | $0 | Simple edits, file ops, mechanical CRUD, quick answers |
+| Hermod | MiniMax-M2.7 | Mid | $0.30/M · $1.20/M | Git ops: commit, push, PR, merge, rebase, branches |
+| Thor | MiniMax-M2.7 | Mid | $0.30/M · $1.20/M | Moderate implementation, tests, debugging, refactoring |
+| Tyr | MiniMax-M3 | High | $0.30/M · $1.20/M | Complex features, architecture, deep debugging, cross-cutting refactor |
+| Vidarr | GPT-5.5 | Ultra | ChatGPT sub | Last resort when Tyr fails or debugging is stuck |
+| Forseti | MiniMax-M3 | Gate | $0.30/M · $1.20/M | Plan auditor - reviews Tyr/Vidarr plans before execution |
+| Semble | MCP search | Free | $0 | MCP code search tool - not an agent |
+
+## Odin Routing Rules
+
+**Odin has `edit: deny`, `bash: deny`, `glob: deny`, `grep: deny`.** He literally cannot self-handle.
+
+### Mandatory Parallelism
+
+1. Every request is decomposed into independent work items
+2. Always 2+ parallel `task` calls in a single message
+3. Implementation always splits across @thor + @tyr (frontend/backend, file split, impl+tests)
+4. If a task truly cannot be split, pair it with a parallel research or review task
+
+### Routing Cheat Sheet
+
+```
+Research / Understanding     → @mimir  (free, Semble-first)
+Quick edit / File ops        → @heimdall  (free)
+Git / PR / Merge             → @hermod  (M2.7)
+Moderate implementation      → @thor  (M2.7)
+Complex implementation       → @tyr  (M3, after @forseti audit)
+Ultimate fallback            → @vidarr  (GPT-5.5, after @forseti audit)
+Plan review / Audit         → @forseti  (M3, review only)
+```
+
+### Cost Escalation
+
+```
+Free (Mimir, Heimdall) → $Mid (Thor, Hermod) → $$High (Tyr) → $$$Ultra (Vidarr)
+```
+
+Never use a paid agent for work a free agent can do. Never use Tyr for what Thor can handle.
+
+## MiniMax Multi-Key Rotation
+
+When using the `minimax/MiniMax-M3` or `minimax/MiniMax-M2.7` model ids, do NOT set a custom `baseURL`. The plugin rotates through keys on 429/402/5xx:
+
+```bash
+# Option A - comma-separated env var
+export MINIMAX_API_KEYS="key1,key2,key3"
+
+# Option B - numbered env vars
+export MINIMAX_API_KEY="primary-key"
+export MINIMAX_API_KEY_2="second-key"
+export MINIMAX_API_KEY_3="third-key"
+```
+
+Rotation triggers on 429 (rate limit), 402 (quota exhausted), 500/502/503/504 (server error). Does NOT trigger on 401 (unauthorized - fix the key).
+
+## Headroom
+
+The Bizar dashboard manages Headroom through Settings → Headroom. To check status:
+
+```bash
+bizar headroom status
+bizar headroom stats
+bizar headroom install
+bizar headroom wrap
+```
+
+Or via the dashboard API:
+- `GET /api/headroom/status` — live status
+- `GET /api/headroom/stats` — compression stats
+- `POST /api/headroom/install` — install headroom
+- `POST /api/headroom/wrap` — wrap cline
+- `POST /api/headroom/proxy/start` — start proxy
+
+Headroom is a context compression layer that sits between cline and LLM providers, compressing tool outputs, logs, RAG chunks, and conversation history by 60–95%.
+
+## Troubleshooting
+
+### Odin Self-Handles Instead of Routing
+**Symptoms:** Odin runs bash, glob, grep, edit, or write directly.
+
+**Fix:** Remove those permissions from `~/.config/cline/agents/odin.md`:
+```yaml
+permission:
+  task: allow
+  read: allow
+  list: allow
+  todowrite: allow
+  question: allow
+  webfetch: allow
+  websearch: allow
+  # NO bash, glob, grep, edit, write
+```
+
+### Forseti Rejects Every Plan
+Provide more detail: specific file paths, data flow, error handling, security implications.

package/.claude/worktrees/kanban-overhaul/bizar-dash/skills/chat/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: chat
+description: How chat and cline session integration works in BizarHarness - session management, message history, cline session detail, and the chat view.
+---
+
+# Chat + Cline Session Integration
+
+The chat view in BizarHarness integrates with cline sessions to provide a conversational interface for agent interactions.
+
+## Session Management
+
+Each cline session has a unique session ID. The chat router (`bizar-dash/src/server/routes/chat.mjs`) manages:
+- Listing active and historical sessions
+- Streaming message events via SSE
+- Session termination
+
+## Chat Endpoints
+
+- `GET /api/chat/sessions` - list all sessions (active and recent)
+- `GET /api/chat/sessions/:id` - get session metadata and messages
+- `POST /api/chat/sessions` - create a new session
+- `DELETE /api/chat/sessions/:id` - terminate a session
+- `GET /api/chat/sessions/:id/stream` - SSE stream of messages
+
+## Message Format
+
+```typescript
+interface Message {
+  id: string;
+  sessionId: string;
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+  model?: string;
+  tokens?: { input: number; output: number };
+  createdAt: string;
+  attachments?: Attachment[];
+}
+```
+
+## Cline Session Detail
+
+`bizar-dash/src/server/routes/cline-session-detail.mjs` exposes per-session metadata:
+- Agent chain (which agents handled this message)
+- Token usage breakdown
+- Tool calls made
+- Session duration
+
+## Chat View (Frontend)
+
+`bizar-dash/src/web/views/Chat.tsx` - the main chat UI:
+- Real-time message streaming via SSE
+- Markdown rendering with syntax highlighting
+- File attachment support
+- Message regeneration
+- Copy code buttons
+
+Mobile: `bizar-dash/src/web/views/MobileChat.tsx`
+
+## Hooks
+
+`bizar-dash/src/web/hooks/useChat.ts` - manages:
+- Session state
+- Message list
+- Streaming state
+- Auto-scroll
+- Error recovery
+
+## Common Issues
+
+### Messages not streaming
+Check that the SSE endpoint is reachable and the session is still active. The server closes the stream after session timeout.
+
+### Session shows wrong agent
+Sessions are routed based on the current routing table in `AGENTS.md`. A session started under Thor will continue under Thor unless explicitly rerouted.

package/.claude/worktrees/kanban-overhaul/bizar-dash/skills/eval/SKILL.md

@@ -0,0 +1,237 @@
+# Eval Framework Skill
+
+v5.0.0 — Evaluate AI agent outputs against golden fixtures for regression testing, agent comparison, and quality assurance.
+
+## Overview
+
+The eval framework runs fixtures — JSON files that define a prompt, expected outputs, and validation rules — against a live agent and reports pass/fail results.
+
+## Fixture Schema
+
+```json
+{
+  "id": "unique-fixture-id",
+  "name": "Human Readable Name",
+  "description": "What this fixture verifies",
+  "agent": "thor",
+  "prompt": "The prompt to send to the agent",
+  "expected": {
+    "contains": ["substring 1", "substring 2"],
+    "notContains": ["forbidden substring"],
+    "regex": ["expected regex pattern"],
+    "jsonSchema": null,
+    "maxTokens": 2000,
+    "maxLatencyMs": 30000
+  },
+  "tags": ["smoke", "regression"]
+}
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | Unique identifier across all fixtures |
+| `name` | string | Yes | Human-readable name |
+| `description` | string | Yes | What the fixture verifies |
+| `agent` | string | Yes | Agent to use: `thor`, `tyr`, `heimdall`, etc. |
+| `prompt` | string | Yes | The prompt sent to the agent |
+| `expected` | object | Yes | Validation rules |
+| `tags` | string[] | No | Tags for filtering |
+
+### Expected Validation Rules
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `contains` | string[] | All substrings must appear in the response |
+| `notContains` | string[] | No substring may appear in the response |
+| `regex` | string[] | All regex patterns must match the response |
+| `jsonSchema` | object\|null | If set, response must be valid JSON matching the schema |
+| `maxTokens` | number | Maximum total tokens in the response |
+| `maxLatencyMs` | number | Maximum response time in milliseconds |
+
+## Running Evals
+
+### CLI
+
+```bash
+# Run a fixture suite
+bizar eval run ./templates/eval-fixtures
+
+# Run with custom concurrency
+bizar eval run ./path/to/fixtures --concurrency=5 --agent=thor
+
+# List recent runs
+bizar eval list --limit=20
+
+# Show run details
+bizar eval show run_2026-07-05-120000
+
+# Diff two runs
+bizar eval diff run_2026-07-05 run_2026-07-04
+
+# Scaffold a new fixture
+bizar eval init ./my-fixtures
+
+# Validate a fixture without running
+bizar eval validate ./my-fixtures/my-fixture.json
+```
+
+### REST API
+
+```bash
+# Run a suite (POST)
+curl -X POST http://127.0.0.1:4321/api/eval/run \
+  -H "Content-Type: application/json" \
+  -d '{"suitePath": "./templates/eval-fixtures", "concurrency": 5}'
+
+# List runs (GET)
+curl http://127.0.0.1:4321/api/eval/runs?limit=20
+
+# Get run details (GET)
+curl http://127.0.0.1:4321/api/eval/runs/run_2026-07-05-120000
+
+# Diff runs (GET)
+curl http://127.0.0.1:4321/api/eval/runs/run_2026-07-05/compare/run_2026-07-04
+
+# List fixtures in a path (GET)
+curl "http://127.0.0.1:4321/api/eval/fixtures?path=./templates/eval-fixtures"
+```
+
+## Writing Good Fixtures
+
+### Start with `contains`
+
+The simplest check — verify a substring appears in the response:
+
+```json
+{
+  "id": "my-fixture",
+  "prompt": "What is 2+2?",
+  "expected": {
+    "contains": ["4", "four"]
+  }
+}
+```
+
+### Use `notContains` for Anti-Patterns
+
+Catch common mistakes the agent should NOT make:
+
+```json
+{
+  "id": "no-apologies",
+  "prompt": "Tell me about Python",
+  "expected": {
+    "notContains": ["I'm sorry", "I apologize", "as an AI"]
+  }
+}
+```
+
+### Regex for Structured Patterns
+
+Match structured output without strict JSON validation:
+
+```json
+{
+  "id": "function-signature",
+  "prompt": "Write a function that adds two numbers",
+  "expected": {
+    "regex": ["function\\s+add\\s*\\(", "def\\s+add\\s*\\("]
+  }
+}
+```
+
+### JSON Schema for Structured Responses
+
+Validate the exact shape of JSON responses:
+
+```json
+{
+  "id": "json-response",
+  "prompt": "Return your version as JSON",
+  "expected": {
+    "jsonSchema": {
+      "type": "object",
+      "required": ["version"],
+      "properties": {
+        "version": { "type": "string" }
+      }
+    }
+  }
+}
+```
+
+### Latency Budgets
+
+Catch performance regressions:
+
+```json
+{
+  "id": "fast-response",
+  "prompt": "Say 'hi'",
+  "expected": {
+    "contains": ["hi"],
+    "maxLatencyMs": 5000
+  }
+}
+```
+
+## Regression Tracking
+
+Run evals regularly and compare results:
+
+```bash
+# Run today
+bizar eval run ./fixtures --agent=thor
+
+# Compare with yesterday's run
+bizar eval diff run_2026-07-05 run_2026-07-04
+```
+
+The diff categorizes fixtures as:
+- **Improved** — was failing, now passing
+- **Regressed** — was passing, now failing
+- **Unchanged** — same result in both runs
+
+## Test Isolation
+
+Fixtures should be:
+- **Idempotent** — running twice gives the same result
+- **Independent** — no fixture depends on another
+- **Deterministic** — same prompt → same result (modulo non-determinism in the model)
+
+## Debugging Failures
+
+When a fixture fails:
+
+1. **Check the check details** — each check has a `message` explaining why it failed
+2. **Increase token budget** — the model may be truncating output
+3. **Relax latency** — the model may be slow due to load
+4. **Check the prompt** — the model may be misunderstanding the task
+
+## CI Integration
+
+Add to your CI pipeline:
+
+```yaml
+# .github/workflows/eval.yml
+- name: Run eval suite
+  run: |
+    bizar eval run ./fixtures --concurrency=3
+
+- name: Check for regressions
+  run: |
+    RESULT=$(bizar eval list --limit=1)
+    # Fail if any fixtures failed
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `bizar-dash/src/server/eval.mjs` | Core runner — loads fixtures, calls LLM, validates |
+| `bizar-dash/src/server/eval-store.mjs` | Persistence — saves runs to `~/.local/share/bizar/eval/` |
+| `bizar-dash/src/server/routes/eval.mjs` | REST API surface |
+| `cli/commands/eval.mjs` | CLI subcommands |
+| `templates/eval-fixtures/` | Example fixtures |

package/.claude/worktrees/kanban-overhaul/bizar-dash/skills/headroom/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: headroom
+description: Headroom — context compression layer for AI agents. Routes cline and other LLM clients through a local proxy that compresses tool outputs, logs, RAG chunks, and conversation history by 60–95%.
+---
+
+# Headroom
+
+Headroom is a context compression layer that sits between cline (or any LLM client) and the upstream provider. It intercepts tool call outputs, conversation history, and RAG chunks and compresses them before they reach the model — typically reducing token usage by 60–95% with no loss in answer quality.
+
+## When to Use
+
+- **Token budget is tight**: If a task is approaching the context window limit, Headroom can reclaim 60–90% of the tokens spent on tool outputs.
+- **Long conversations**: The compression is cumulative — the longer the session, the more Headroom saves.
+- **Verbose tool output**: RAG retrieval, file globbing, grep results, and diagnostic output are the highest-value compression targets.
+- **Multi-step implementation**: Large features with many tool calls benefit most.
+
+## Architecture
+
+```
+cline → headroom proxy (localhost:8787) → LLM provider
+             ↓
+        compresses tool outputs, logs, RAG chunks
+        caches responses
+        measures savings
+```
+
+## Key Concepts
+
+### Compression ratio
+The fraction of tokens Headroom eliminates. A 0.85 compression ratio means 85% of the tokens were removed before reaching the provider.
+
+### Wrapped vs unwrapped
+`headroom wrap cline` modifies `~/.config/cline/cline.json` to route traffic through the proxy. `headroom unwrap cline` restores the original configuration.
+
+### Proxy vs wrap
+- **Proxy** (`headroom proxy`): The actual HTTP proxy server running on port 8787.
+- **Wrap** (`headroom wrap cline`): The act of configuring cline to use the proxy.
+
+You can run the proxy standalone (`headroom proxy`) and point any OpenAI-compatible client at it. The wrap command is just a convenience for cline.
+
+## Dashboard Integration
+
+The Bizar dashboard manages Headroom through Settings → Headroom:
+
+- **Status widget**: Shows live proxy status, compression ratio, tokens saved
+- **Controls**: Install, wrap/unwrap, start/stop proxy, open dashboard
+- **Settings**: Auto-install, auto-start, auto-wrap, route-all-providers, port, host, backend, output shaper, telemetry, budget
+
+API endpoints:
+- `GET /api/headroom/status` — live status
+- `GET /api/headroom/stats?hours=24` — compression statistics
+- `POST /api/headroom/install` — install headroom
+- `POST /api/headroom/wrap` — wrap cline
+- `POST /api/headroom/unwrap` — unwrap cline
+- `POST /api/headroom/proxy/start` — start proxy
+- `POST /api/headroom/proxy/stop` — stop proxy
+- `POST /api/headroom/auto-route` — configure all providers to route through the proxy
+
+CLI:
+```bash
+bizar headroom status   # live status
+bizar headroom stats    # compression stats
+bizar headroom install  # install headroom
+bizar headroom wrap     # wrap cline
+bizar headroom unwrap   # unwrap
+bizar headroom start    # start proxy
+bizar headroom stop     # stop proxy
+bizar headroom doctor   # health check
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `HEADROOM_HOST` | `127.0.0.1` | Proxy bind host |
+| `HEADROOM_PORT` | `8787` | Proxy port |
+| `HEADROOM_OUTPUT_SHAPER` | `0` | Set to `1` to enable output shaping |
+| `HEADROOM_TELEMETRY` | (on) | Set to `off` to disable |
+| `HEADROOM_BUDGET` | `0` | Monthly USD cap (0 = unlimited) |
+| `HEADROOM_CONTEXT_TOOL` | `rtk` | Context tool: `rtk` or `lean-ctx` |
+
+## Common Gotchas
+
+1. **Proxy must be running before cline starts**: If the proxy is down when cline launches, cline will fail to make LLM calls. Start the proxy first, or enable `autoStart` in Headroom settings.
+
+2. **`headroom wrap` edits cline.json**: The wrap command modifies `~/.config/cline/cline.json`. If you use version control for this file, you'll see a diff on every wrap. Use `headroom unwrap` before committing, or ignore the changes.
+
+3. **Headroom 0.30.0 doesn't have `headroom plan --tokens`**: This command was removed. Use `headroom perf --hours 24` for actual token savings data.
+
+4. **Token savings are cumulative**: The compression ratio compounds over a session. A 15-step implementation that saves 80% at each step uses roughly the same tokens as a 3-step implementation without Headroom.
+
+5. **Cache hits**: Headroom caches semantically similar tool calls. Repeated operations (file reads, API probes) can be served from cache entirely, bypassing the LLM.
+
+6. **Provider baseURL**: When `routeAllProviders` is enabled, the dashboard rewrites provider baseURLs to point at the proxy. If you configure a new provider manually, you may need to update its baseURL to go through the proxy.