@superbased/observer 1.8.1 → 1.8.3

package/README.md

@@ -82,30 +82,33 @@ the [main repo](https://github.com/marmutapp/superbased-observer).
 ## Five-minute quickstart
 
 ```bash
-# 1) Install. `observer init` is OPTIONAL — only run it if you want
-#    the MCP server registered with your AI clients (gives them
-#    on-demand tools like check_file_freshness / get_cost_summary
-#    at the cost of ~1,800 tokens of schema per turn).
+# 1) Install.
 npm install -g @superbased/observer
-observer init                 # OPTIONAL — interactive: pick clients;
-                              # writes MCP + codex proxy-route into AI client configs.
-                              # Skip this step for an MCP-free install.
-
-# 2) Start the long-running services (proxy + watcher + dashboard).
-#    Auto-registers HOOKS for every detected AI tool on first launch.
-observer start &
-
-# 3) Engage the proxy by pointing your AI client at the local URL.
-#    See "Per-AI-client setup" for the matching env var.
-export ANTHROPIC_BASE_URL=http://127.0.0.1:8820     # Claude Code
-export OPENAI_BASE_URL=http://127.0.0.1:8820/v1     # Codex / OpenAI
-
-# 4) Open the dashboard.
-open http://127.0.0.1:8081/   # macOS
-xdg-open http://127.0.0.1:8081/   # Linux
-start http://127.0.0.1:8081/   # Windows
+
+# 2) Start everything: proxy + watcher + dashboard in one process.
+#    Hooks auto-register for every detected AI tool, and the
+#    dashboard opens in your browser (suppress with --no-open).
+observer start
 ```
 
+From here the dashboard drives:
+
+3. **Route your AI client through the proxy** — on the Compression
+   tab's **Proxy** banner, click your tool's status pill, then
+   **Route through the observer proxy…**. The button previews the
+   exact file change and writes only on confirm. (Every other
+   routing mechanism — `observer init`, the `observer claude` /
+   `observer codex` wrappers, plain env vars — is listed in
+   [Per-AI-client setup](#per-ai-client-setup).)
+4. **Use your AI tool as normal.** The Overview tab's onboarding
+   checklist tracks your first captured session; cost, compression,
+   and cache numbers populate within minutes of real activity.
+
+`observer init` is OPTIONAL — run it only if you want the MCP server
+registered with your AI clients (gives them on-demand tools like
+`check_file_freshness` / `get_cost_summary`, at the cost of ~1,800
+tokens of schema per turn). Skip it for an MCP-free install.
+
 **What `start` does vs what `init` adds:**
 
 | Step | Hooks | Proxy listening | Watcher | Dashboard | MCP in AI clients | Codex proxy route |
@@ -117,16 +120,46 @@ start http://127.0.0.1:8081/   # Windows
 MCP and codex routing are explicit-only because both write per-client
 config files. Hooks self-heal on every `start`.
 
-After ten minutes of normal AI-coding usage, the dashboard will be
-populated with cost over time, per-tool activity, compression
-savings, and stale-reread waste signals.
-
 
 ## Per-AI-client setup
 
-Different clients send to different upstreams. The local proxy on
-`127.0.0.1:8820` handles all of them — routes by URL path. Set the
-env var that matches your client(s); both can coexist on one machine.
+### Routing through the proxy — the canonical section
+
+Accurate token counts, conversation compression, and cache tracking
+all require your AI client to send its API traffic through the local
+proxy on `127.0.0.1:8820`. There is one decision to make — *how* to
+route — and four mechanisms that all end at the same proxy. Pick the
+first one that fits:
+
+| Mechanism | What it does | Use it when |
+|---|---|---|
+| **Dashboard button** *(recommended)* | On the Compression tab's **Proxy** banner, click your tool's status pill, then **Route through the observer proxy…**. It previews the exact file change and writes only on confirm: Claude Code gets `"env": { "ANTHROPIC_BASE_URL": … }` in `~/.claude/settings.json`; Codex gets an `observer` model provider in `~/.codex/config.toml`. Durable — every later session routes automatically, no wrapper, no env vars. Undo: remove the entry, or `observer uninstall --claude-code` / `--codex`. | You have a browser open. This is the default path. |
+| **`observer init`** | Writes the same durable routing from the CLI, alongside hooks + MCP registration (each side defaults on; opt out with `--skip-hooks` / `--skip-mcp` / `--skip-proxy-route`). | Headless machines, scripted setups. |
+| **Wrapper commands** — `observer claude` / `observer codex` | Launch the tool with routing injected for that session only; nothing is written to any config file. The claude wrapper also re-exports a fresh Pro/Max OAuth token so the SDK's OAuth path can't bypass the proxy (an expired stored token is left alone — Claude Code then refreshes natively). `observer claude --verify` runs the pre-flight checks without launching. | Trying the proxy out, or you don't want config writes. |
+| **Env var export** | `export ANTHROPIC_BASE_URL=http://127.0.0.1:8820` (Anthropic clients) or `export OPENAI_BASE_URL=http://127.0.0.1:8820/v1` (OpenAI clients — note the `/v1`) in the shell that launches the tool. | One-off shells; clients without a button or wrapper. |
+
+Routing is per-tool, not global: route Claude Code and Codex
+independently, and both can coexist on one machine — the proxy
+routes by URL path.
+
+> **Claude Code + MCP servers**: set `ENABLE_TOOL_SEARCH=true` in the
+> same environment. Claude Code's SDK disables deferred MCP schema
+> loading whenever `ANTHROPIC_BASE_URL` is set and eager-inlines every
+> registered MCP schema (~+21K tokens/turn) — enough to turn the proxy
+> into a net cost. The override restores lazy loading; the proxy
+> forwards `tool_reference` blocks byte-identically.
+
+> **If the daemon is down while a tool is routed**, Claude Code does
+> not silently bypass to the real API — it retries the dead port
+> (verified live: it hangs rather than failing over). `observer
+> doctor` and the dashboard's Health panel flag this state as a
+> "proxy routing gap"; bring the daemon back with `observer start`.
+
+### Capture modes per client
+
+The proxy covers the clients that speak the Anthropic / OpenAI wire
+APIs. Everything else is captured passively from session logs. The
+table below is the full per-client reference.
 
 | AI client                       | Env var                                               | Capture mode |
 |---------------------------------|-------------------------------------------------------|--------------|
@@ -134,13 +167,17 @@ env var that matches your client(s); both can coexist on one machine.
 | **Cursor** (Anthropic mode)     | `ANTHROPIC_BASE_URL=http://127.0.0.1:8820`            | proxy + JSONL |
 | **Codex**                       | `OPENAI_BASE_URL=http://127.0.0.1:8820/v1` (note `/v1`) | proxy + JSONL with API-key auth; ChatGPT-plan login currently behaves as JSONL only |
 | **Cursor** (OpenAI mode)        | `OPENAI_BASE_URL=http://127.0.0.1:8820/v1`            | proxy + JSONL |
-| **Cline / Roo Code**            | `ANTHROPIC_BASE_URL=...` or `OPENAI_BASE_URL=...` per provider | proxy + JSONL |
+| **Cline (VS Code) / Roo Code**  | `ANTHROPIC_BASE_URL=...` or `OPENAI_BASE_URL=...` per provider | proxy + JSONL |
+| **Cline CLI** (npm `cline` 3.0.20+) | (no proxy route yet — the CLI ignores base-URL env vars; per-provider `baseUrl` overrides live in `~/.cline/data/settings/providers.json`, a credentials file only the operator should edit) | JSONL — SQLite session metadata at `~/.cline/data/db/sessions.db` (schema v1, 28 columns) plus per-session `<id>.messages.json` content blocks. Captures `user_prompt` / `assistant_text` / `tool_use` / paired `tool_result` rows + Tier 2 per-API-call token usage from `modelInfo` overrides. Subagent + team linkage via 5 new `ActionMetadata` fields (`ParentSessionID`, `ParentAgentID`, `AgentID`, `IsSubagent`, `TeamName`). 28-tool taxonomy (10 core + 18 `team_*` coordination primitives). WSL2 over `/mnt/c` uses the same `stageMirror` pattern as opencode/kilocode. Tagged `Source=jsonl, Reliability=approximate`. |
 | **GitHub Copilot**              | (no proxy yet)                                        | JSONL only   |
 | **OpenCode** ([opencode.ai](https://opencode.ai/)) | (no proxy yet)                     | SQLite — actual install path is `~/.local/share/opencode/opencode.db` (XDG). Captures **token counts + model + cost** per assistant message from OpenCode's InfoData (`tokens.input/output/reasoning/cache.{read,write}` + `cost`); **subtask** parts → `spawn_subagent` actions; **todo** table → `todo_update` actions; tool-name coverage extended to webfetch/websearch/task/todowrite/todoread/multiedit. Tagged `Source=jsonl, Reliability=approximate`. |
 | **OpenClaw** ([openclaw.ai](https://openclaw.ai/)) | (no proxy yet)                     | JSONL + sqlite — `~/.openclaw/tasks/runs.sqlite` + `~/.openclaw/agents/<agent>/sessions/sessions.json` |
 | **Pi** ([pi.dev](https://pi.dev/)) | (no proxy yet)                                       | JSONL — `~/.pi/agent/sessions/--<path>--/*.jsonl` (per upstream `docs/session-format.md` v3). Captures user / assistant / toolResult / `bashExecution` message roles; `usage.cost.total` → per-message USD; terminal `stopReason` (stop/length/error/aborted) → `task_complete` with `success=false` for failures (mid-turn `toolUse` is correctly skipped); `thinking` blocks surface as preceding reasoning. Tagged `Source=jsonl, Reliability=approximate`. |
 | **Google Antigravity** | (no proxy yet) | Encrypted protobuf — `~/.gemini/antigravity/conversations/*.pb` (Linux-native) and the matching Windows-side path on WSL2. Observer ships a per-OS Chromium-pattern `oscrypt` key fetcher (macOS Keychain / libsecret / DPAPI / WSL2-via-PowerShell helper) and a multi-cipher try-loop for local decryption. Sessions whose ciphers don't validate locally fall back to the language_server's `GetCascadeTrajectory` gRPC endpoint via a built-in helper (`antigravity-bridge.exe` on WSL2 / native gRPC elsewhere) — extracts model + per-turn token counts + Tier 0–6 ToolEvents (file views, artifact edits/writes, user prompts, assistant text, run_command terminal snapshots, structured plan steps, final summaries). State index + per-conversation title/workspace URI read from `state.vscdb` + `state.vscdb.backup`. Tagged `Source=jsonl, Reliability=approximate`. |
+| **Kilo Code IDE extension (legacy)** | (no proxy yet) | JSON — `<vsCodeGlobalStorage>/kilocode.kilo-code/tasks/<taskId>/api_conversation_history.json`. The legacy Kilo extension is a Cline + Roo Code fork and shares the Cline parser; emitted rows are re-tagged `Tool="kilo-code"` so dashboard rollups don't blur Kilo activity into Cline. Tagged `Source=jsonl, Reliability=approximate`. |
+| **Kilo Code CLI (current)**     | (no proxy route yet — base-URL env vars are not honored; a project-scoped `kilo.json` provider `baseURL` override reaches the proxy, but the Gateway provider's model-catalog calls share that base URL and have no upstream there — see `docs/kilo-code-adapter.md`) | SQLite — `~/.local/share/kilo/kilo.db` on every OS (Kilo intentionally mirrors XDG; Windows does NOT use `%APPDATA%`). The new `@kilocode/cli` (npm) is a fork of sst/opencode and uses the same `message`/`part`/`todo` tables shape with Kilo additions (`project`, `workspace`, `event`, `session_message`, `account`, `permission`, `session_share`). Captures **token counts + model + cost** per assistant message from `message.data.tokens = {total, input, output, reasoning, cache: {read, write}}`. Tool name coverage inherits OpenCode's surface (`read` → `read_file`, `bash` → `run_command`, `websearch` → `web_search`, etc.). Tagged `Source=jsonl, Reliability=approximate`. |
 | **Gemini CLI** | (no proxy yet) | JSONL or single-object JSON — `~/.gemini/tmp/<hash>/chats/session-*.{json,jsonl}`. Dual-format dispatch: legacy single-object JSON (size-based cursor, cline-style) and proposed JSONL event records (byte-offset cursor, issue [#15292](https://github.com/google-gemini/gemini-cli/issues/15292)). Action mapping covers `read_file` / `write_file` / `edit_file` / `run_command` / `search_files` / `web_fetch` and arbitrary MCP tool calls. Project root falls back through tool-call `cwd` → `~/.gemini/history/<hash>/.git/config` worktree pointer → synthetic `[gemini-cli:<hash>]` key (promoted via ON CONFLICT DO UPDATE on `sessions.project_id` once a future scan supplies a real cwd). Tagged `Source=jsonl, Reliability=approximate`. |
+| **Hermes Agent** ([Nous Research](https://github.com/NousResearch/hermes-agent)) | (provider-routed; uses your existing `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` when set) | Hooks + SQLite — Python plugin at `~/.hermes/plugins/superbased-observer/` registers `post_tool_call` / `post_api_request` / `on_session_start` / `on_session_end` / `subagent_stop` callbacks (fire-and-forget via `observer hook hermes`); the watcher walks `~/.hermes/state.db` (schema v14, `messages.active = 1` filter) and emits `ToolEvent` + `TokenEvent` rows via `modernc.org/sqlite`. 70+ Hermes tools fold into the normalized action set (`read_file` / `write_file` / `patch` / `terminal` / `search_files` / `web_search` / `web_extract` / `browser_*` / `delegate_task` / `todo` / `clarify` / `memory` + `mcp_call` fall-through). Token bundles lifted from `post_api_request.usage{input/output/cache/reasoning_tokens}`; OpenRouter `:suffix` tails (`:free`, `:beta`, `:fast`) preserved so the dashboard distinguishes paid vs free tiers. Install via `observer init --hermes`; backfill via `observer backfill --hermes-rescan`. Tagged `Source=jsonl, Reliability=approximate`. |
 
 **JSONL-only** clients are captured passively by the watcher whenever
 `observer start` is running. Hooks self-heal on every `start`, so a
@@ -149,8 +186,8 @@ for them on the Compression tab (those need the proxy), but every tool
 call shows up on Sessions / Actions / Discovery / Tools / Patterns and
 the JSONL-derived token counts feed the Cost tab. Reliability tagging
 is per-adapter: Claude Code emits `unreliable` (the JSONL stream uses
-streaming-time placeholder counts per spec §24); Codex / Cline / Pi /
-OpenCode / OpenClaw / Antigravity / Gemini CLI emit `approximate`
+streaming-time placeholder counts per spec §24); Codex / Cline / Cline CLI /
+Pi / OpenCode / OpenClaw / Antigravity / Gemini CLI / Hermes / Kilo Code / Kilo Code CLI emit `approximate`
 (provider-reported usage that hasn't been reconciled against an
 upstream invoice).
 
@@ -159,32 +196,6 @@ For **Codex specifically**, Observer currently has two practical support modes:
 - `Proxy + JSONL`: Codex is routed through `OPENAI_BASE_URL=http://127.0.0.1:8820/v1` and Observer can link proxy turns to the session, so live compression metrics are available.
 - `JSONL only`: Observer can still recover sessions, actions, and approximate token counts from `~/.codex/sessions`, but live proxy compression is currently not available when Codex is logged in with a ChatGPT plan on the local machine.
 
-### Persistent setups
-
-**Claude Code** (`~/.claude/settings.json`):
-
-```json
-{
-  "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:8820" },
-  "hooks": { /* `observer init` writes these */ }
-}
-```
-
-**Codex** (`~/.codex/config.toml`):
-
-```toml
-[env]
-OPENAI_BASE_URL = "http://127.0.0.1:8820/v1"
-```
-
-**Shell rc** (`~/.bashrc` / `~/.zshrc`) — affects every program:
-
-```bash
-export ANTHROPIC_BASE_URL=http://127.0.0.1:8820
-export OPENAI_BASE_URL=http://127.0.0.1:8820/v1
-```
-
-
 ## Architecture in detail
 
 <p align="center">
@@ -250,8 +261,10 @@ Pure-Go via `modernc.org/sqlite`, no CGO. WAL mode by default.
 
 ### 4. Local dashboard (`:8081`)
 
-Eight tabs covering: Overview, Cost, Sessions, Actions, Tools,
-Compression, Discovery, Patterns. See [Dashboard tour](#dashboard-tour).
+Fifteen tabs in four groups — Monitor (Overview, Live, Sessions,
+Actions, Search), Analyze (Cost, Analysis, Tools), Optimize
+(Compression, Cache, Suggestions, Discovery, Patterns), Configure
+(Privacy, Settings). See [Dashboard tour](#dashboard-tour).
 
 Static HTML + Chart.js. No analytics, no external requests.
 
@@ -275,7 +288,24 @@ running `init`.
 
 ## Dashboard tour
 
-Open `http://127.0.0.1:8081/` after `observer start`. Ten tabs.
+`observer start` opens the dashboard automatically on interactive
+launches (suppress with `--no-open`; the URL is also printed —
+`http://127.0.0.1:8081/` by default). Fifteen tabs in four nav groups
+(Monitor / Analyze / Optimize / Configure) — the tour below covers the
+core surfaces; Live (recent sessions with a real-time action feed),
+Search (full-text over captured tool outputs), and Privacy (capture
+map + scrub tester) are self-explanatory once you're in. On an empty
+database the Overview tab leads with a three-step onboarding
+checklist that takes you from zero to your first captured session
+without leaving the browser.
+
+**Just looking?** The empty-database Overview also offers **demo
+mode**: one click seeds a temporary synthetic dataset so every chart
+and table renders with realistic data — parsed through the real
+ingest pipeline into a temp DB; your real `observer.db` is never read
+or written. A persistent banner marks demo state, and one click
+clears it again. The fastest way to evaluate the dashboard before
+routing any real traffic.
 
 ### Overview tab
 
@@ -342,8 +372,9 @@ sessions that could have used Sonnet).
 </p>
 
 One row per AI-coding session. Each session has a stable ID, a tool
-(claude-code / cursor / codex / cline / copilot / opencode / openclaw /
-pi / antigravity / gemini-cli), a working-directory project, action
+(claude-code / cursor / codex / cline / cline-cli / copilot / copilot-cli /
+opencode / openclaw / pi / antigravity / gemini-cli / hermes /
+kilo-code / kilo-code-cli), a working-directory project, action
 count, sub-agent action count (when the session spawned sub-agents via
 the `Agent` tool), per-session **Tokens** and **Cost** columns, and —
 if `observer score` has run — quality / errors / redundancy ratios. The `~` suffix on Cost flags rows whose pricing
@@ -352,7 +383,7 @@ was tier-fallback rather than billing-grade ("accurate" reliability).
 Click a row to open the session-detail panel:
 
 <p align="center">
-  <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/screenshots/10-session-detail.png" alt="Session detail slide-over" width="900">
+  <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/screenshots/11-session-detail.png" alt="Session detail slide-over" width="900">
 </p>
 
 
@@ -432,10 +463,119 @@ saved by trimming requests before forwarding upstream:
   score (for drops), and a **Source** column showing whether the
   event came from a main-thread or sub-agent runtime call
 
+### Cache tab
+
+<p align="center">
+  <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/screenshots/08-cache.png" alt="Cache tab" width="900">
+</p>
+
+Anthropic prompt-cache observation, attribution, and forecasting —
+how well your sessions are reusing provider-cached prefixes.
+
+- **KPI tiles**: Cache ratio (cache_read ÷ cache_write tokens; the
+  headline cache-payback signal), Cache read, Cache write, and
+  Avoidable spend / Event count. The avoidable-spend tile is the
+  dollar overhead of cache rewrites that wouldn't have happened on
+  a perfectly cache-friendly session — it surfaces in warn tone when
+  non-zero.
+- **By model + By project tables** — for each rollup dimension: R%/W%
+  mix bars + absolute Read / Write / Events + cache Ratio + Avoidable
+  $. Identifies the model or repo that's pulling the most overhead.
+- **Top causes histogram** — proportional bar list of `cache_events.cause`
+  values. Healthy baseline is `suffix_growth` + `hit` dominating
+  (info-toned warm prefix growth). Real invalidations (`system_changed`,
+  `expiry_rewrite`, `model_switch_rewrite`) render in warn tone. Causes
+  that legitimately fire on real operator toggles — currently
+  `tools_changed` on MCP server connect/disconnect — render with a
+  neutral "flagged" pill rather than alarm-red.
+- **Worst sessions table** — ranked by rewrite count; click a row to
+  open the session's Cache panel with the full per-turn timeline.
+
+#### How the cache data gets captured
+
+Two capture paths feed the same engine; both write the same three
+local-only tables (`cache_segments`, `cache_entries`, `cache_events`;
+migrations 036 + 037 — never pushed to a Teams org server, pinned by
+`tests/invariant/privacy_test.go::TestSelectUnpushedSinceExcludesCacheTables`):
+
+1. **Tier-1 (proxy)** — point your AI client at the local proxy
+   (`ANTHROPIC_BASE_URL=http://127.0.0.1:8820` for Claude Code;
+   `OPENAI_BASE_URL=http://127.0.0.1:8820/v1` for codex and
+   copilot-cli). The proxy reads the upstream usage envelope
+   (`cache_read_input_tokens` + `cache_creation_input_tokens`) and the
+   cachetrack engine attributes each turn live as it streams. Every
+   claude-code prompt-cache event surfaces here in real time.
+2. **Tier-2 (transcript watcher)** — the watcher tails claude-code
+   JSONL transcripts and feeds the same engine retroactively for
+   sessions that didn't route through the proxy. Run
+   `observer backfill --cache-rescan` to retrofit pre-cachetrack
+   history.
+
+#### How to enable / disable
+
+- **Default-on.** Per spec §11, the loader merges `[cachetrack].enabled = true`
+  if the section is absent. No action needed for a fresh install.
+- To disable: set `[cachetrack].enabled = false` in
+  `~/.observer/config.toml` and restart `observer start`.
+- Inspect engine health: `observer cache-health --json` — §10 grading
+  gate + read:write consistency + cause-concentration WARNs.
+- 90-day retention is on by default
+  (`[cachetrack].retention_days = 90`); the maintenance tick prunes
+  stale `cache_*` rows alongside the existing retention pass.
+
+Operator reference: [`docs/cache-tracking.md`](https://github.com/marmutapp/superbased-observer/blob/main/docs/cache-tracking.md).
+
+### Suggestions tab
+
+The **advisor** — a prescriptive suggestions engine that turns the
+window's captured activity into ranked, dollar- or minute-quantified
+recommendations. **On by default** and entirely local: detectors are
+pure reads over data the observer already stores, recomputed fresh on
+every view — zero LLM calls, zero network.
+
+Twenty detectors across four categories:
+
+- **cost** — session balloons (one session's context growth dominating
+  spend), idle re-cache (cache rewrites after idle gaps), long-context
+  tier crossings, trivial sessions on expensive models, cache hit-rate,
+  cache-write waste, prefix thrash, read-heavy sessions on expensive
+  models, effort overprovisioning, cross-session stale reads,
+  web-search spend, spend spikes ("today is 3× your daily average" —
+  the while-it's-still-happening check, linking to the Live view),
+  routing evidence ready (the advise shadow met its promotion gate
+  with routing still not enforcing — linking to the Shadow card,
+  which owns the evidence and the consent-gated promote).
+- **latency** — fast-tier premium (sessions that paid the 2× fast-tier
+  rate without needing it).
+- **quality** — unrecovered failures, quality regressions.
+- **hygiene** — MCP schema overhead vs. actual MCP calls, compression
+  off while proxied traffic flows, capture running without proxy
+  routing, guard observing idle (recurring high-severity verdicts
+  with zero approvals or tuning — linking to the Security page).
+
+Each card carries the quantified claim ($ or minutes, with a
+**show math** toggle exposing the arithmetic), a confidence score, a
+scope chip (window / project / session — session scopes deep-link to
+the session detail), and — when a dashboard control can fix the
+finding — an action button that navigates to the right surface
+(writes only ever happen behind that surface's own consent flow).
+`snooze 7d` quiets a card temporarily; `dismiss` retires it, with a
+7-day cooldown so the same finding doesn't re-nag. The all-clear
+state means exactly what it says: nothing worth nagging about in
+this window.
+
+Tune it under Settings → Advisor (`[advisor]` in config.toml):
+evidence window (default 14 days), confidence floor (0.5), minimum
+claimed savings ($1), and the opt-in **session digest** — when
+`session_digest = true`, the Claude Code session-start hook injects a
+≤400-token digest of the top suggestions into new sessions (off by
+default; the hook only reads a pre-computed snapshot, refreshed every
+30 minutes). CLI twin: `observer advise`.
+
 ### Discovery tab
 
 <p align="center">
-  <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/screenshots/08-discovery.png" alt="Discovery tab" width="900">
+  <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/screenshots/09-discovery.png" alt="Discovery tab" width="900">
 </p>
 
 Wasted-effort signals:
@@ -466,21 +606,73 @@ observations push it higher) and an observation count.
 high-confidence ones into `CLAUDE.md` / `AGENTS.md` / `.cursorrules`
 so new sessions inherit your habits.
 
+### Security tab
+
+The guard layer's operating surface — not just a verdict viewer.
+Posture tiles (mode, verdict counts, audit-chain check) over a
+filterable verdict timeline (rule / severity / decision / session,
+with rule IDs resolved to their full definitions), then the routine
+workflows end to end: a consent-gated **mode control** that shows the
+simulate evidence before you flip enforce, the **enforce-readiness
+card** (a replay of your real history under the enforce projection,
+with per-rule blocking concentration), the **approvals register**
+(scoped, expiring exceptions — DB writes, live immediately), a
+**lint-gated policy editor** for your user rules (malformed files are
+refused with the problems listed; `.bak` undo), **budget guardrails**
+suggested from your own observed spend with a daily burn-down meter,
+MCP pin approvals, and one-click **compliance evidence** downloads
+(report / JSONL / CEF / audit verification).
+
+### Routing tab
+
+Model routing's transparency + adoption surface. While routing is
+off, a **Preview savings** card replays your last 30 days under any
+policy template — read-only, nothing enabled. Once advise mode runs,
+the page shows the decisions feed (every decision expandable to its
+matched rule, reason codes, and cache economics), savings with CI95
+error bars, the expanded policy rule table (never a black box,
+demoted rules marked), the tier map with calibration overlays, the
+model health board, and the **advise-shadow readiness ladder** with
+its consent-gated promote control. The **Apply to tools** card turns
+observed sub-agent evidence into per-tool native config — dry-run
+preview, one consent per file write, backups + per-file revert, and
+an append-only audit ledger of everything observer changed.
+
 ### Settings tab
 
 <p align="center">
-  <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/screenshots/09-settings.png" alt="Settings tab" width="900">
+  <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/screenshots/10-settings.png" alt="Settings tab" width="900">
 </p>
 
-Fully editable visual editor for everything in `config.toml`.
-Pricing overrides hot-reload (no daemon restart — `cost.Engine`
-swaps the pricing table atomically via `atomic.Pointer.Store`).
-The Backfill panel surfaces every `observer backfill` mode as
-click-to-run buttons that spawn the CLI as a child process and
-stream output back live. Watcher / Freshness / Retention / Hooks /
-Proxy / Compression / Intelligence sections are schema-driven forms
-with inline help; a "Restart daemon" banner appears whenever a
-section is saved that consumers bind at startup.
+Fully editable visual editor for everything in `config.toml`, plus
+the operational panels a config file can't express:
+
+- **Config sections** — schema-driven forms for Watcher, Freshness,
+  Retention, Hooks, Proxy, Compression, Intelligence, Advisor, Cache
+  tracking, Secrets scrubbing, MCP, Profiles, Org share, and OTel.
+  Each section is honest about reload semantics: pricing and profile
+  changes apply hot, MCP settings apply to the next AI session, and
+  restart-gated sections raise a persistent restart-pending banner
+  that names the exact command and clears itself only when the
+  daemon actually restarts.
+- **Connected tools** — one row per detected AI client (detected /
+  capturing / hooks / MCP / proxied), a per-tool setup wizard that
+  previews every config write and applies each one only on its own
+  consent click, and a Launch button (with a copy-paste fallback)
+  for opening a routed session.
+- **Health** — the full `observer doctor` check set with remediation
+  hints, plus recent command failures (recovered vs not).
+- **Backfill** — every `observer backfill` mode as a click-to-run
+  job with live streamed output, plus a full-rescan card with an
+  adapter picker.
+- **Storage** — what's actually taking the space: per-table database
+  size breakdown (index and FTS5 shadow-table bytes folded into the
+  table they serve), vacuum and online backup as click-to-run jobs,
+  and the documented restore procedure (restore is deliberately
+  manual: stop the daemon, swap the file, start). CLI twin:
+  `observer db stats|vacuum|backup`.
+- **Config file card** — view the active file; one-click restore of
+  the automatic `.bak` taken before every save.
 
 ### Help drawer
 
@@ -557,7 +749,7 @@ a content-aware compressor. Six compressors:
 | Mechanism | What it does | When it fires |
 |-----------|--------------|---------------|
 | **json**  | Replaces every scalar value with a type sentinel (`"<string>"`, `"<number>"`, …) preserving structure (keys, arrays, nesting). Arrays of length > 1 collapse to one element with `_len: N`. | API responses, structured logs, telemetry exports. JSON tool_results are usually the biggest savings target. |
-| **code**  | Heuristic skeleton: keeps top-of-file imports + signature lines (function / method / class / struct / interface / type), drops bodies. | Source code files. **On by default** as of v1.7.23 for the `claude-code` recipe (V7-24 empirical winner). |
+| **code**  | Heuristic skeleton: keeps top-of-file imports + signature lines (function / method / class / struct / interface / type), drops bodies. | Source code files. **On by default** as of v1.7.23 in the `claude-code` profile (V7-24 empirical winner). |
 | **logs**  | Two-pass: collapses adjacent identical lines to `<line> [×N]`, then head+tail-truncates to 200 lines if still long. | Log-shaped output — `go test ./...`, `npm run build`, polling/retry loops. Lossless on distinct lines; only the truncate pass is lossy. |
 | **text**  | Catch-all for content not classified as code/json/logs/diff/html. Head+tail truncation: keeps 40 + 40 lines on inputs over 80 lines. | Markdown bodies, README excerpts, narrative descriptions. |
 | **diff**  | Strips unified-diff context beyond ±1 line of each change. Keeps every header, every `+`/`-` line, drops the rest with elision markers. | `git diff`, patch tool outputs. Lossless on changes; lossy only on the cheap-to-rebuild context. |
@@ -603,14 +795,34 @@ tab's "Recent compression events" view surfaces these with
 mechanism, original / compressed / saved bytes, message slot, and
 importance score (for drops).
 
-### Tuning
-
-`observer config` settings (in `~/.observer/config.toml`). These are the only
-keys the conversation compressor reads:
+### Tuning — profiles pick the parameters for you
+
+Compression parameters are supplied by **profiles**: named parameter
+sets resolved per traffic class at the proxy boundary. The moment you
+enable compression, Anthropic-path traffic gets the `claude-code`
+profile and OpenAI-path traffic gets `codex-safe` — each tool gets
+its tuned parameters simultaneously; there is no recipe-picking step.
+Inspect with `observer profile list` / `observer profile show
+<name>`; reassign per class or per tool (`observer profile assign
+openai codex-variant`, `observer profile assign tool:kilo-code-cli
+codex-safe`); build your own (`observer profile create mine --from
+claude-code`, or Settings → Profiles in the dashboard). Per-tool
+assignment needs the proxy to identify the connecting tool: hook-fed
+identity (Claude Code) is exact, and Codex, Kilo CLI, opencode, and
+Claude Code are also recognized by their request headers; clients
+that send no distinctive headers (e.g. Cline CLI) fall back to the
+per-provider profile. Profile
+edits apply to **new sessions without a daemon restart**. A repo can
+also carry `<root>/.observer/config.toml` with `[profiles]` /
+`[compression]` keys to override per project — project files can turn
+compression *off* for their traffic, never on.
+
+The master config (`~/.observer/config.toml`) keeps the one on/off
+switch and the fallback parameters used by the `default` profile:
 
 ```toml
 [compression.conversation]
-enabled = true
+enabled = true             # THE switch — profiles never flip this
 mode = "cache_aware"       # "token" | "cache" | "cache_aware" — default cache_aware; see matrix below
 target_ratio = 0.85
 preserve_last_n = 5        # never drop the most recent N messages
@@ -648,20 +860,22 @@ reference lives in `docs/compression-modes.md`.
 
 ### Measured savings (v1.7.23)
 
-We A/B every shipped recipe against an OFF baseline on a real refactor
+We A/B every shipped profile against an OFF baseline on a real refactor
 workload (`lumen` TypeScript codebase, 408-line Zustand store →
 4 domain sub-stores) on the v1.7.22 binary tip. The numbers below are
 the **most recent statistically-meaningful measurements**.
 
-**Pick a recipe based on which model you're running:**
+The first two profiles are what the per-provider auto-assignment
+applies (Anthropic → `claude-code`, OpenAI → `codex-safe`);
+`codex-variant` is the manual pick for `-codex`-family models:
 
-| Recipe | Use when your model is… | Workload | n | Δ vs OFF (mean cost) | What's compressed |
+| Profile | Use when your model is… | Workload | n | Δ vs OFF (mean cost) | What's compressed |
 |---|---|---|---|---|---|
-| **`claude-code`** *(default)* | Any Anthropic Claude model — `claude-sonnet-4-6`, `claude-opus-4-7`, `claude-haiku-4-5`, … | Refactor, Claude Sonnet 4.6 via Claude Code 2.1.158 | n=8 B vs n=4 OFF | **−6.9%** (CV 7.6%; tighter than OFF's 7.5%) | json + logs + code bodies; cache-aware; stash disabled |
+| **`claude-code`** *(default)* | Any Anthropic Claude model — `claude-sonnet-4-6`, `claude-opus-4-7`, `claude-haiku-4-5`, … | Refactor, Claude Sonnet 4.6 via Claude Code 2.1.158 | n=8 B vs n=4 OFF | **−6.9%** (CV 7.6%; tighter than OFF's 7.5%) | json + logs + code bodies + tool-defs trim (A2-adopted 2026-06-11: −12.5% vs the pre-A2 set, zero `tools_changed` cache events); cache-aware; stash disabled |
 | **`codex-variant`** | OpenAI's `-codex` reasoning fork — `gpt-5.3-codex`, `gpt-5.4-codex`, `gpt-5-codex-agent`, anything matching `*-codex*` | Refactor, gpt-5.3-codex | n=10 B vs n=10 OFF | **−10%** ($0.270 vs $0.300) | Tools-defs trim; cache-aware; no per-type compression |
-| **`codex-safe`** | Plain OpenAI GPT under the codex CLI — `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`, `gpt-4o`, any non-`-codex` | Refactor, gpt-5.4 + `apply_patch` | n=3 B vs n=4 OFF | not statistically distinguishable on this workload | logs only; cache-aware |
+| **`codex-safe`** | Plain OpenAI GPT under the codex CLI — `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`, `gpt-4o`, any non-`-codex` | Refactor, gpt-5.4 + `apply_patch` | n=3 B vs n=4 OFF | not statistically distinguishable on this workload | logs + tools-defs trim (A6-adopted 2026-06-11: fired on 117/117 candidate requests, ~0.8KB/request of definition prose, task-completion parity + no cache degradation at n=9 vs n=7; effect scales with envelope bulk — MCP-registered installs save more); token mode |
 
-The word **"variant"** in `codex-variant` refers to the *model variant* (the `-codex` reasoning fork of GPT), NOT a variant of the codex CLI. Both codex recipes are for the codex CLI; they differ only in which model family they assume. `codex-safe` is so named because plain GPT models tolerate logs trimming safely — it's not "safer than codex-variant."
+The word **"variant"** in `codex-variant` refers to the *model variant* (the `-codex` reasoning fork of GPT), NOT a variant of the codex CLI. Both codex profiles are for the codex CLI; they differ only in which model family they assume. `codex-safe` is so named because plain GPT models tolerate logs trimming safely — it's not "safer than codex-variant."
 
 **Honest caveats:**
 
@@ -746,6 +960,126 @@ counts one API call 2-4×. Two layers of dedup catch this:
 Migration 007 ran a one-time pass collapsing pre-fix duplicates.
 
 
+## Security & control layer (guard)
+
+The guard evaluates every captured agent action against a
+table-driven policy — built-in rules (destructive commands, project
+boundaries, secrets egress, MCP pinning, taint/dataflow, budgets)
+plus your own TOML rules — records each verdict in a hash-chained,
+tamper-evident audit table, and on the channels that support it can
+block before execution. It ships **observe-only by default**: a fresh
+install records and alerts, and never blocks anything until you
+explicitly flip enforce.
+
+What makes it different from standalone command-guards:
+
+- **One policy, every tool.** The same rules evaluate Claude Code,
+  Codex, Cursor, Cline and the rest through one engine — and
+  `observer init --guard` additionally *compiles* the policy into
+  each client's own native permission dialect, so the client itself
+  enforces even when the observer daemon is down.
+- **Replay before you enforce.** `observer guard simulate --since 168h`
+  replays your real captured history against current policy and shows
+  what last week WOULD have flagged or blocked — a confidence check
+  only a tool that already has your history can run.
+- **Proxy-level secrets egress scanning.** Clients routed through the
+  observer proxy get outbound API bodies scanned for credentials,
+  with mask/deny enforcement — an egress point no other local-first
+  tool sits on.
+- **Auditable, honestly.** Verdicts are hash-chained
+  (tamper-EVIDENT, not tamper-proof — the docs say exactly what that
+  means), exportable as JSONL/CEF for your SIEM, and summarized by
+  `observer guard report` into a compliance evidence pack mapped to
+  SOC 2 / NIST 800-53.
+- **Operable from the dashboard, not just the CLI.** The Security
+  page runs the routine workflows end to end: a consent-gated mode
+  control that shows the simulate evidence before you flip enforce,
+  an Enforce-readiness replay over your real history, the approvals
+  register (scoped, expiring exceptions — live immediately), a
+  lint-gated policy editor for your user rules (malformed files are
+  refused before they touch disk, with `.bak` undo), budget
+  guardrails suggested from your own observed spend (p95 + headroom)
+  with a daily burn-down meter, MCP pin approvals, and one-click
+  compliance evidence downloads.
+
+Honest scope: hooks see declared commands, not side effects (use OS
+sandboxes for containment — the guard detects and recommends them);
+most adapters are watcher-channel and can only flag post-hoc; the
+proxy scan only covers proxy-routed clients. The full capability
+matrix is on the dashboard's Security page, and the no-network
+invariant holds — nothing leaves your machine unless you opt into
+Teams push, OTel export, or the cloud alerting tier, each
+individually.
+
+Quick start:
+
+```
+observer guard status                  # mode, rules, recent verdicts, chain check
+observer guard test "rm -rf ./build"  # would this block?
+observer guard simulate --since 168h  # what would last week have flagged?
+observer guard enable --enforce       # flip to enforce when ready
+```
+
+Full references:
+[guard.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/guard.md)
+(operator guide + getting started),
+[guard-rules.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/guard-rules.md)
+(rule catalog),
+[guard-policy-authoring.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/guard-policy-authoring.md)
+(writing rules + cookbook),
+[guard-enforce-runbook.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/guard-enforce-runbook.md)
+(the observe→enforce migration),
+[guard-compliance.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/guard-compliance.md)
+(SOC 2 / NIST mapping).
+
+## Model routing
+
+The routing layer selects the right model for each KIND of work —
+from your own observed evidence, never a brochure — through two
+channels: **A** writes each AI tool's own config (claude-code
+per-subagent `model:` frontmatter — dry-run first, backed up,
+revertable, audit-ledgered; other tools get exact paste-able
+snippets), and **B** rewrites the `model` field on requests already
+transiting the proxy. It is **opt-in, advise-first, and fail-open
+everywhere**: a routing failure can never break a turn that would
+have succeeded.
+
+The adoption ladder is deliberate, and every step has a dashboard
+surface: **preview** what a policy would have saved over your last 30
+days while routing is still off (a read-only replay of recorded
+turns) → enable **advise** (decision rows accrue; requests untouched)
+→ read the **shadow** (the §R22 readiness ladder: enough decisions,
+real net savings after cache forfeits, zero quality flags) →
+**promote** to enforce through a consent dialog that restates the
+evidence — and warns loudly when the gate is not met. Enforce
+rewrites within the same provider shape only, holds switches that
+would forfeit a warm prompt cache worth more than they save, and
+auto-demotes any rule whose downshifts grade as regressing
+(loudly, never silently). Custom `[[routing.rules]]` are editable in
+a lint-gated dashboard editor with a worked recipe gallery in the
+docs.
+
+Privacy posture: decision rows and calibration are **node-local**
+(never pushed to an org server); org-distributed policy fragments are
+signed and structurally cannot flip your enforce switch — **no remote
+enforce toggle exists, by design**.
+
+Quick start:
+
+```
+# Preview before enabling anything (CLI twin of the dashboard card):
+observer routing simulate --policy value --days 30
+# Then: dashboard → Routing → Preview savings → Enable advise mode.
+observer routing shadow    # the promotion evidence, any time
+observer routing apply --tool claude-code   # Channel A, dry-run default
+```
+
+Full reference:
+[model-routing.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/model-routing.md)
+(operator guide + the first-30-days runbook + the rules recipe
+gallery).
+
+
 ## Terminology and glossary
 
 Quick reference; the in-platform help drawer (press `?` on the
@@ -817,8 +1151,9 @@ dashboard) has the full versions with cross-links.
   changed between reads. Cross-session reads are excluded (a fresh
   session has no memory of a prior session's read).
 - **Tool** — in this dashboard, "tool" means the *AI client*
-  (claude-code, cursor, codex, cline, copilot, opencode, openclaw,
-  pi, antigravity, gemini-cli), not the per-tool name (`read_file`,
+  (claude-code, cursor, codex, cline, cline-cli, copilot, copilot-cli,
+  opencode, openclaw, pi, antigravity, gemini-cli, hermes, kilo-code,
+  kilo-code-cli), not the per-tool name (`read_file`,
   `run_command`). The latter is "Tool name" on the Actions tab.
 - **Tool-pair integrity** — Anthropic requires every `tool_result`
   block to have a corresponding `tool_use` block in a preceding
@@ -832,9 +1167,11 @@ Every command supports `--help` for the full surface.
 
 | Subcommand                         | Purpose |
 |------------------------------------|---------|
-| `observer init`                    | Register hooks + MCP server with installed AI clients |
+| `observer init`                    | Register hooks + MCP server + durable proxy routes with installed AI clients (each side defaults on; opt out with `--skip-hooks` / `--skip-mcp` / `--skip-proxy-route`). With **zero flags on a terminal** it runs an interactive checklist instead: detects your tools, previews each pending config write, and asks consent one write at a time (MCP never pre-selected). Any flag or redirected stdio keeps the batch behaviour. |
 | `observer uninstall`               | Reverse `observer init` |
-| `observer start`                   | Run watcher + dashboard + proxy in one process (recommended). Flags: `--dashboard-addr ADDR` (default `127.0.0.1:8081`), `--no-dashboard` to skip the HTTP UI. |
+| `observer start`                   | Run watcher + dashboard + proxy in one process (recommended). Auto-opens the dashboard on interactive launches. Flags: `--dashboard-addr ADDR` (default `127.0.0.1:8081`), `--no-dashboard` to skip the HTTP UI, `--no-open` to skip the browser. |
+| `observer claude [-- args…]`       | Launch Claude Code routed through the proxy for that session only (no config writes; fresh Pro/Max OAuth token re-exported so the SDK can't bypass). `--verify` runs pre-flight checks without launching. |
+| `observer codex [-- args…]`        | Launch Codex routed through the proxy for that session only (injects `openai_base_url` via argv; no config writes). |
 | `observer watch`                   | Long-running JSONL watcher only |
 | `observer dashboard --addr ADDR`   | HTTP dashboard only |
 | `observer proxy start`             | Reverse proxy only |
@@ -851,13 +1188,19 @@ Every command supports `--help` for the full surface.
 | `observer summarize`               | Roll-up summary across sessions |
 | `observer export`                  | Export DB to xlsx / json |
 | `observer prune`                   | Manual retention pass (delete old data) |
+| `observer db stats\|vacuum\|backup` | Storage manager. `stats`: per-table size breakdown (index + FTS5 shadow bytes folded into the table they serve). `vacuum`: reclaim free pages, reports bytes freed (can report SQLITE_BUSY against a busy daemon — re-run in a quiet moment). `backup <path>`: online snapshot via SQLite `VACUUM INTO` — safe while the daemon runs, refuses to overwrite. Restore is manual by design: stop daemon, swap file, start. |
+| `observer db import <path>`        | Merge another `observer.db` into this node's (a stranded install from another OS or home directory). Set-based, single-transaction, idempotent — re-running adds nothing twice; project identities remap by root path. `--dry-run` executes the same transaction and rolls it back, so its per-table counts are exact. Migrates the source schema first — point it at a copy. Node-local state (cache tracking, watcher cursors, advisor state) doesn't transfer. |
 | `observer backfill --is-sidechain` | Re-walk JSONL to populate `actions.is_sidechain` (added by migration 010) on pre-migration rows. |
 | `observer backfill --cache-tier`   | Re-walk JSONL to populate `cache_creation_1h_tokens` (added by migration 008) on pre-migration rows. Run once after upgrading to v1.4.16+ to correct historical 1h-tier cache writes that were silently billed at the cheaper 5m rate. |
 | `observer backfill --message-id`   | Re-walk JSONL to populate `message_id` on `actions` and `token_usage` (added by migration 012). Required by the per-message timeline view in the Sessions modal. |
 | `observer backfill --all`          | Run every supported backfill in one invocation. Idempotent — safe to re-run. |
+| `observer profile list\|show\|assign\|create\|delete\|set` | Compression profiles: inspect built-ins, reassign per traffic class or per tool (`assign tool:cline codex-safe`), create/edit custom profiles. Edits apply to new sessions hot. |
+| `observer config set <key> <value>` | Dotted-key config setter (`compression.conversation.enabled true`). `--project <root>` writes a per-repo override file instead. |
+| `observer advise`                  | Prescriptive cost/quality suggestions from captured activity (the Suggestions tab, in the CLI) |
+| `observer cache-health`            | Prompt-cache engine health: grading gate, read:write consistency, cause concentration |
 | `observer metrics`                 | Prometheus-format metrics endpoint |
 | `observer serve`                   | MCP server (stdio JSON-RPC) — usually invoked by `observer init` registration |
-| `observer tail`                    | Live event stream |
+| `observer completion <shell>`      | Generate shell completions (bash / zsh / fish / powershell) — e.g. `observer completion zsh > "${fpath[1]}/_observer"` |
 
 
 ## Configuration
@@ -961,11 +1304,13 @@ its dirs get created and the watcher picks them up.
 
 ### Empty dashboard / "No proxy traffic"
 
-The JSONL adapter populates passively after `observer init`, but
-ground-truth cost / compression numbers require the proxy. Set
-`ANTHROPIC_BASE_URL=http://127.0.0.1:8820` (Claude Code) or
-`OPENAI_BASE_URL=http://127.0.0.1:8820/v1` (Codex) in the shell
-that launches your AI client.
+Session/action data populates passively whenever `observer start` is
+running, but ground-truth cost / compression numbers require the
+proxy. Route your tool through it — the quickest way is the
+dashboard's Compression tab → **Proxy** banner → **Route through the
+observer proxy…** button; every other mechanism (wrappers, env vars,
+`observer init`) is listed under
+[Per-AI-client setup](#per-ai-client-setup).
 
 Verify with `observer status | grep api_turns` — count should
 climb during AI-client activity.

package/README.template.md

@@ -0,0 +1,300 @@
+# @superbased/observer
+
+[![npm](https://img.shields.io/npm/v/@superbased/observer.svg)](https://www.npmjs.com/package/@superbased/observer)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Platforms: Linux • macOS • Windows](https://img.shields.io/badge/platforms-linux%20%7C%20macos%20%7C%20windows-blue.svg)](https://github.com/marmutapp/superbased-observer)
+
+**Capture, normalize, compress, and analyze every AI coding tool call you
+run** — across Claude Code, Codex, Cursor, Cline / Roo Code, GitHub
+Copilot (VS Code), GitHub Copilot CLI, OpenCode, OpenClaw, Pi, Google
+Antigravity, Gemini CLI, and Cowork — in one local single-binary tool.
+No telemetry, no cloud, no data leaves your machine.
+
+<p align="center">
+  <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/infographics/one-local-path.png" alt="One local path for AI coding activity" width="780">
+</p>
+
+# Table of contents
+
+- [Install](#install)
+- [Five-minute quickstart](#five-minute-quickstart)
+- [Per-AI-client setup](#per-ai-client-setup)
+- [Architecture in detail](#architecture-in-detail)
+- [Dashboard tour](#dashboard-tour)
+- [MCP tools reference](#mcp-tools-reference)
+- [Compression mechanisms](#compression-mechanisms)
+- [Cost and token math](#cost-and-token-math)
+- [Terminology and glossary](#terminology-and-glossary)
+- [CLI reference](#cli-reference)
+- [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
+- [Security and privacy](#security-and-privacy)
+- [Source, contributing, license](#source-contributing-license)
+
+
+## Install
+
+**Use a global install** (`-g`) so the `observer` command is available
+on your `$PATH` from any directory:
+
+```bash
+npm install -g @superbased/observer
+observer --version
+```
+
+If you install locally (without `-g`) the binary lives at
+`./node_modules/.bin/observer` and isn't on your `$PATH`. Run it
+with `npx`:
+
+```bash
+npm install @superbased/observer    # local install
+npx observer --version              # ↑ what to use everywhere `observer` is shown below
+```
+
+A note for shared / CI machines where `npm install -g` may need
+`sudo`: see [Troubleshooting → EACCES](#npm-install--g-fails-with-eacces-permission-denied)
+for user-writable-prefix and version-manager fixes.
+
+> **Python users:** `pip install superbased-observer` ships the
+> same binary; version numbers are kept in lock-step. See
+> [the PyPI page](https://pypi.org/project/superbased-observer/).
+> Don't install both globally — whichever directory comes first on
+> `$PATH` wins, which gets confusing if their versions drift.
+
+Pre-built binaries ship for:
+
+| Platform              | Architecture |
+|-----------------------|--------------|
+| Linux                 | x64, arm64   |
+| macOS (Intel)         | x64          |
+| macOS (Apple Silicon) | arm64        |
+| Windows               | x64          |
+
+The package uses the `optionalDependencies`-per-platform pattern (same
+shape as `esbuild` / `swc` / `@biomejs/biome`) — only the binary
+matching your machine downloads. No postinstall network calls, no
+compile step.
+
+If your platform isn't listed, build from source — instructions in
+the [main repo](https://github.com/marmutapp/superbased-observer).
+
+
+## Five-minute quickstart
+
+```bash
+# 1) Install.
+npm install -g @superbased/observer
+
+# 2) Start everything: proxy + watcher + dashboard in one process.
+#    Hooks auto-register for every detected AI tool, and the
+#    dashboard opens in your browser (suppress with --no-open).
+observer start
+```
+
+From here the dashboard drives:
+
+3. **Route your AI client through the proxy** — on the Compression
+   tab's **Proxy** banner, click your tool's status pill, then
+   **Route through the observer proxy…**. The button previews the
+   exact file change and writes only on confirm. (Every other
+   routing mechanism — `observer init`, the `observer claude` /
+   `observer codex` wrappers, plain env vars — is listed in
+   [Per-AI-client setup](#per-ai-client-setup).)
+4. **Use your AI tool as normal.** The Overview tab's onboarding
+   checklist tracks your first captured session; cost, compression,
+   and cache numbers populate within minutes of real activity.
+
+`observer init` is OPTIONAL — run it only if you want the MCP server
+registered with your AI clients (gives them on-demand tools like
+`check_file_freshness` / `get_cost_summary`, at the cost of ~1,800
+tokens of schema per turn). Skip it for an MCP-free install.
+
+**What `start` does vs what `init` adds:**
+
+| Step | Hooks | Proxy listening | Watcher | Dashboard | MCP in AI clients | Codex proxy route |
+|---|---|---|---|---|---|---|
+| `observer start` alone | auto-registers ✓ | ✓ | ✓ | ✓ | — | — |
+| `observer init` + `observer start` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `observer init --skip-mcp` + `start` | ✓ | ✓ | ✓ | ✓ | — | ✓ |
+
+MCP and codex routing are explicit-only because both write per-client
+config files. Hooks self-heal on every `start`.
+
+
+<!-- @@INCLUDE:docs/distribution/README-body.md@@ -->
+
+
+## Troubleshooting
+
+### `npm install -g` fails with `EACCES: permission denied`
+
+Default npm puts globals under `/usr/local/lib/node_modules` which
+Homebrew-managed Node owns as root on macOS. Three fixes; pick one:
+
+```bash
+# 1) RECOMMENDED — point npm at a user-writable prefix.
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
+source ~/.zshrc
+npm install -g @superbased/observer
+
+# 2) Use a Node version manager — fnm / nvm install Node into your
+#    home directory and dodge the permission issue entirely.
+brew install fnm
+fnm install --lts
+npm install -g @superbased/observer
+
+# 3) sudo (works but you'll fight permissions on every update).
+sudo npm install -g @superbased/observer
+```
+
+### `observer: command not found` after install
+
+The shim binary is at `~/.npm-global/bin/observer` (or wherever your
+npm prefix points). Make sure that directory is on `$PATH`:
+
+```bash
+echo $PATH | tr ':' '\n' | grep -E 'npm|node'
+# add the prefix's bin/ to PATH if missing — see fix above
+```
+
+If you installed only a platform package (e.g. `@superbased/observer-darwin-x64`)
+without the main `@superbased/observer`, the shim doesn't get created
+— there's no `bin` field. Install the main package; npm picks up the
+right platform binary automatically via `optionalDependencies`.
+
+### `observer init` says "no tools selected and none auto-detected"
+
+Auto-detection looks for the AI clients' default session-log dirs
+(`~/.claude/projects/`, `~/.codex/sessions/`, `~/.cursor/`, etc.).
+On a fresh machine where no client has run yet, those dirs don't
+exist. Pass the flag explicitly:
+
+```bash
+observer init --claude-code     # or --codex / --cursor / --cline / --all
+```
+
+This registers hooks regardless — the next time the client runs,
+its dirs get created and the watcher picks them up.
+
+### Empty dashboard / "No proxy traffic"
+
+Session/action data populates passively whenever `observer start` is
+running, but ground-truth cost / compression numbers require the
+proxy. Route your tool through it — the quickest way is the
+dashboard's Compression tab → **Proxy** banner → **Route through the
+observer proxy…** button; every other mechanism (wrappers, env vars,
+`observer init`) is listed under
+[Per-AI-client setup](#per-ai-client-setup).
+
+Verify with `observer status | grep api_turns` — count should
+climb during AI-client activity.
+
+### `observer --version` says `dev`
+
+You're on a non-released build. Reinstall with `npm install -g @superbased/observer` or rebuild with the workflow's `-X main.version=$VERSION` ldflag.
+
+### `tool_result block must have a corresponding tool_use block`
+
+Anthropic 400. Means the conversation-compression pipeline dropped
+a `tool_use` while keeping its matching `tool_result`. Versions
+prior to 1.3.2 had this bug; upgrade. If you're on 1.3.2+ and still
+see it, file an issue with the conversation prefix.
+
+### `tool use concurrency issues`
+
+Anthropic 400 surfaced in Claude Code as this message. Means the
+parallel-tool-use case (multiple `tool_use` blocks in one assistant
+message) isn't paired correctly with the multi-block tool_result
+that follows. Versions prior to 1.3.2 had this bug; upgrade.
+
+### Cross-thread numbers are 0
+
+Pre-migration data was ingested without the `is_sidechain` flag.
+Run `observer backfill --is-sidechain` once to re-walk JSONL and
+populate the flag on existing rows.
+
+### Migration error: `duplicate column name`
+
+Race condition between concurrent daemon startups, fixed in 1.4.1.
+Upgrade. If you still see it, run daemons serially: `observer
+watch`, wait, then `observer dashboard`, then `observer proxy
+start` (or just use `observer start` which runs all three in one
+process — proxy + watcher + dashboard).
+
+### `observer start` log says only `proxy + observer` — no `:8081`
+
+You're on a pre-1.4.7 build. Earlier versions ran only proxy +
+watcher under `observer start`; the dashboard had to be started
+separately via `observer dashboard --addr 127.0.0.1:8081`. Upgrade
+to 1.4.7+ — the dashboard goroutine is now part of `observer start`
+and the log line confirms all three: `proxy <addr> + watcher +
+dashboard http://127.0.0.1:8081`. Pass `--no-dashboard` to opt out.
+
+### "address already in use" on port 8820
+
+Another `observer proxy start` or `observer start` is still running.
+Find it with `pgrep -af 'observer (proxy|start)'` and `kill <pid>`.
+On macOS:
+
+```bash
+lsof -nP -iTCP:8820 -sTCP:LISTEN
+kill <pid>
+```
+
+### Dashboard port already in use
+
+```bash
+observer dashboard --addr 127.0.0.1:8082    # pick a different port
+# or
+[dashboard]
+port = 8082                                  # in config.toml
+```
+
+
+## Security and privacy
+
+**Local-only. No telemetry. No remote anything.** The watcher, hook
+handler, dashboard, MCP server, and CLI never make an outbound network
+call on observer's behalf. The only code paths that touch the network
+are the optional API proxy (which forwards **your** requests unchanged
+to the AI provider you already use) and a handful of explicit opt-in
+features (message-summary LLM, codegraph MCP, Teams org-server).
+
+The full privacy statement — what observer stores, what it reads,
+what it never stores, the explicit list of outbound-network call sites
+gated behind config, and how to verify "no telemetry" yourself with
+`grep`, `strings`, and a network-namespaced shell — lives in
+[`PRIVACY.md`](https://github.com/marmutapp/superbased-observer/blob/main/PRIVACY.md).
+
+Operational shorthand:
+
+- **Local-only HTTP.** The proxy and dashboard bind to `127.0.0.1`
+  by default. Don't bind to `0.0.0.0` unless you've thought about
+  it — there's no auth.
+- **Secrets scrubbing.** Tool inputs and outputs pass through
+  `internal/scrub/` before persistence; review the regex set if your
+  secrets follow non-default formats.
+- **Database.** `~/.observer/observer.db` is a SQLite file with the
+  same security posture as your `~/.claude/` and `~/.codex/` session
+  logs (which already hold the same content). Encrypt the disk if
+  your threat model needs that.
+- **Full delete.** `rm -rf ~/.observer/` removes everything observer
+  ever stored — no traces elsewhere on your system.
+
+
+## Source, contributing, license
+
+- **Source**: https://github.com/marmutapp/superbased-observer
+- **Specification**: `superbased-final-spec-v2.md` in the repo
+- **Issues**: https://github.com/marmutapp/superbased-observer/issues
+- **License**: [Apache 2.0](https://github.com/marmutapp/superbased-observer/blob/main/LICENSE)
+- **Author**: Santosh Kathira <contact@marmut.app>
+
+This npm package is a thin Node.js shim that resolves the right
+pre-built binary at runtime and spawns it. Same shape as `esbuild` /
+`swc` / `@biomejs/biome`. The Go source lives in the main repo;
+binaries are cross-compiled per release tag via GitHub Actions and
+published as `@superbased/observer-<platform>-<arch>` per-platform
+packages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superbased/observer",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "description": "SuperBased Observer — capture, normalize, compress, and analyze AI coding tool activity across Claude Code, Codex, Cursor, Cline/Roo, and Copilot.",
   "keywords": [
     "ai",
@@ -36,11 +36,11 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@superbased/observer-linux-x64": "1.8.1",
-    "@superbased/observer-linux-arm64": "1.8.1",
-    "@superbased/observer-darwin-x64": "1.8.1",
-    "@superbased/observer-darwin-arm64": "1.8.1",
-    "@superbased/observer-win32-x64": "1.8.1"
+    "@superbased/observer-linux-x64": "1.8.3",
+    "@superbased/observer-linux-arm64": "1.8.3",
+    "@superbased/observer-darwin-x64": "1.8.3",
+    "@superbased/observer-darwin-arm64": "1.8.3",
+    "@superbased/observer-win32-x64": "1.8.3"
   },
   "scripts": {
     "test": "node bin/observer.js --version"