@unerr-ai/unerr 0.0.0-beta.1 → 0.0.0-beta.10

package/README.md

@@ -7,97 +7,156 @@
 </p>
 
 <p align="center">
-  Local code intelligence that gives your AI agent a graph of your entire codebase.<br/>
-  It stops looping, stops re-reading, stops breaking things it can't see.
+  A local intelligence layer that sits between your AI agent and your codebase —<br/>
+  indexes every call, remembers every decision, and gets sharper the longer you use it.
 </p>
 
 <p align="center">
-  <a href="#get-started"><img src="https://img.shields.io/badge/install-npx_@unerr/unerr-8B5CF6?style=flat-square&logo=npm" alt="Install" /></a>
+  <a href="https://www.npmjs.com/package/@unerr-ai/unerr"><img src="https://img.shields.io/badge/install-npm_i_@unerr--ai/unerr-8B5CF6?style=flat-square&logo=npm" alt="Install" /></a>
   <img src="https://img.shields.io/badge/runtime-Node.js_≥20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js" />
   <img src="https://img.shields.io/badge/protocol-MCP-7C3AED?style=flat-square" alt="MCP" />
-  <img src="https://img.shields.io/badge/tests-1455_passing-34D399?style=flat-square" alt="Tests" />
+  <img src="https://img.shields.io/badge/local--first-no_cloud-22D3EE?style=flat-square" alt="Local-first" />
   <img src="https://img.shields.io/badge/license-ELv2-A1A1AA?style=flat-square" alt="License" />
 </p>
 
 <p align="center">
-  <code>npx @unerr/unerr</code>
+  <code>npm install -g @unerr-ai/unerr</code>
 </p>
 
 ---
 
-## Your agent loops because it's blind
+## The agent isn't stupid. It's flying blind.
 
-You've seen it. You ask Claude or Cursor to refactor a function. It reads 30 files to find the call graph. It misses 14 downstream callers. It re-discovers conventions you told it yesterday. It tries a broken approach, fails, tries again — burning tokens while you watch.
+Watch any AI coding session for ten minutes and you'll see the same loop:
 
-**The agent isn't stupid. It's blind.**
+- It **reads 30 files** to find one function — burning the context window before it writes a line.
+- It **edits something with 40 callers** and never knows it just broke three services.
+- It **re-derives the same conventions** you taught it yesterday, this morning, and an hour ago.
+- It **forgets the entire session** the moment the window closes.
 
-- It can't see that `processPayment()` has 40 callers across 3 services
-- It doesn't know your team uses `fetch` prefixes, not `get`
-- It forgot everything from yesterday's session
+Every one of these is the same root cause: the agent has **no persistent memory of your code, your team's style, or its own past mistakes**. unerr is that memory. One process, fully local, indexed in seconds — and your agent picks it up automatically through MCP.
 
-unerr gives it a graph. Every caller, every dependency, every convention. The agent lands at the right code instead of searching for it.
+---
+
+## What you actually see
+
+Run `unerr` and open the dashboard. Four panes, all live:
+
+| Pane | Answers the question | Powered by |
+|---|---|---|
+| **Token Optimization** | *How much context did unerr save my agent this session?* — saved vs. delivered, compounding multiplier, breakdown by mechanism (compression, graph hits, skipped re-reads). | Per-turn ledger of every tool call |
+| **Reasoning Quality** | *Did the agent actually use what it remembered?* — 4-pillar score across exploration, planning, execution, persistent memory. | 5-turn outcome window per fact/convention |
+| **Codebase Map + Code Intelligence** | *What's the call graph and where are the blast-radius landmines?* — entities, edges, fan-in/out chokepoints, cross-module surprise links. | CozoDB graph (in-process, <5ms) |
+| **Project Memory + Activity** | *What did we already learn, and what was I doing last time?* — facts the agent recorded, sessions stitched into intents, open blockers. | Append-only fact store + timeline.db |
+
+The agent reads from the same store through MCP — every claim on the dashboard is also a tool call it just made.
+
+### See it in action
+
+<p align="center">
+  <table>
+    <tr>
+      <td align="center">
+        <img src="https://unerr.dev/open-cli/screenshots/code-base-intelligence.png" alt="unerr codebase intelligence" width="130" />
+        <br/><sub>Codebase intelligence</sub>
+      </td>
+      <td align="center">
+        <img src="https://unerr.dev/open-cli/screenshots/reasoning-session.png" alt="unerr reasoning session" width="130" />
+        <br/><sub>Reasoning session</sub>
+      </td>
+      <td align="center">
+        <img src="https://unerr.dev/open-cli/screenshots/reasoning-quality.png" alt="unerr reasoning quality" width="130" />
+        <br/><sub>Reasoning quality</sub>
+      </td>
+      <td align="center">
+        <img src="https://unerr.dev/open-cli/screenshots/token-trace-main.png" alt="unerr token trace — main view" width="130" />
+        <br/><sub>Token trace</sub>
+      </td>
+      <td align="center">
+        <img src="https://unerr.dev/open-cli/screenshots/token-session.png" alt="unerr session token tracking" width="130" />
+        <br/><sub>Session tracking</sub>
+      </td>
+      <td align="center">
+        <img src="https://unerr.dev/open-cli/screenshots/token-turn.png" alt="unerr per-turn token breakdown" width="130" />
+        <br/><sub>Per-turn breakdown</sub>
+      </td>
+    </tr>
+  </table>
+</p>
 
 ---
 
-## What happens when you run it
+## Quick Start (4 explicit steps)
+
+> unerr is **per-repository**. Each project gets its own `.unerr/` directory, graph DB, and config. Run install once per repo.
+
+### 1. Install the CLI globally
 
 ```bash
-npx @unerr/unerr
+npm install -g @unerr-ai/unerr
+# verify
+unerr --version
 ```
 
-**5 seconds later**, your agent has:
-
-| Before unerr | After unerr |
-|:---|:---|
-| Reads 30 files to understand a call graph | Queries the graph in 5ms |
-| Misses downstream callers, breaks things | Sees full blast radius before editing |
-| Re-derives conventions every session | Knows your patterns, enforces them |
-| Session degrades at 70% context fill | Stays sharp — 93% shell compression, context lasts 3-5x longer |
-| Starts from zero tomorrow | Resumes where it left off |
+### 2. `cd` into the **root of the repository** you want to enhance
 
+```bash
+cd /path/to/your-project   # must be the repo root (where .git or package.json lives)
 ```
-unerr session (12 min)
-  Tool calls    47 (all local, <5ms each)
-  Tokens saved  ~120K (93% shell compression + graph-targeted reads)
-  Turns saved   ~8 (approaches that would have failed, prevented)
+
+This matters: every file unerr writes — `.mcp.json`, `.claude/`, `.cursor/`, `.unerr/`, `.gitignore` entry — is scoped to the current working directory. Running install from a subdirectory will create a stray, broken setup.
+
+### 3. Install unerr for your coding agent
+
+Pick the agent you actually use. Each command writes the MCP config, agent-specific skill files, instruction injection, and (where supported) hooks — all in the current repo:
+
+```bash
+unerr install claude-code        # → .mcp.json + CLAUDE.md + .claude/skills/ + hooks
+unerr install cursor             # → .cursor/mcp.json + .cursor/rules/ + hooks
+unerr install antigravity        # → .antigravity/mcp_config.json + .agents/rules/ + .agents/skills/
+unerr install windsurf           # → ~/.codeium/windsurf/mcp_config.json + .windsurf/rules/ + .windsurf/skills/
+unerr install gemini-cli         # → .gemini/settings.json + GEMINI.md + .gemini/skills/
+unerr install github-copilot-cli # → .copilot/mcp-config.json + .github/copilot-instructions.md + .github/skills/
 ```
 
----
+What this actually does, in order:
+
+1. Writes a project-level MCP config (`{"command": "unerr", "args": ["--mcp"]}`) — never global.
+2. Drops 11 bundled skills into the agent's skills directory so the agent knows when to call which tool.
+3. Injects a tool-preference section into the agent's instruction file (CLAUDE.md, .cursor/rules, etc.) — idempotent, removable with `unerr uninstall`.
+4. Installs hooks where the agent supports them (Claude Code, Cursor, Cline) — these compress shell output and steer the agent back to graph tools.
+5. Adds `.unerr` to `.gitignore`.
+6. For Claude Code, denies built-in `Read`/`Grep`/`Glob` so the agent must use unerr's graph-aware equivalents (opt out with `--no-force-tools`).
+
+> Need a different agent or doing it by hand? `unerr install --show-instructions <agent>` prints copy-pasteable setup. 16 agents are supported today (6 fully integrated, 10 in progress).
 
-## Get Started
+### 4. Run `unerr` — and **keep it running**
 
 ```bash
-npx @unerr/unerr
+unerr        # first run: indexes the repo, starts the daemon; subsequent: resumes in <1s
 ```
 
-That's it. Auto-detects your IDE, indexes your codebase (~30s), starts serving intelligence via MCP.
+**This is the part most people skip.** The `unerr --mcp` process your IDE spawns is just a **stdio bridge** — it owns nothing. All the intelligence (graph indexing, file watching, drift detection, fact storage, behavior automation) lives in the long-lived `unerr` daemon.
 
-### Add to more agents
+If the daemon isn't running, you still get tool responses, but they go stale: file edits won't show up in the graph, no incremental re-index, no live drift overlay, no convention auto-detection from new code. **Leave `unerr` running in a terminal tab or as a background service for the whole work session.** It uses ~80–200 MB and idles at near-zero CPU.
 
 ```bash
-unerr install claude-code   # .mcp.json + .claude/skills/ + PreToolUse hook
-unerr install cursor        # .cursor/mcp.json + .cursor/rules/
-unerr install vscode        # .vscode/mcp.json + .github/copilot/
-unerr install windsurf      # .windsurf/mcp.json + .windsurf/rules/
-unerr install zed           # .zed/mcp.json
-unerr install codex         # .codex/mcp.json
-unerr install gemini-cli    # .gemini/settings.json
-unerr install kiro          # .kiro/mcp.json
-unerr install aider         # .aider/mcp.json
-unerr install continue      # .continue/config.json
+# typical workflow
+unerr &                    # start daemon in background (or run in a tmux/screen pane)
+# now open Claude Code / Cursor / etc. — it auto-connects via MCP
 ```
 
-Works with any MCP-compatible agent. 15 supported out of the box.
+After this, your agent connects automatically the next time you open the IDE. No config files to edit by hand.
 
 <details>
-<summary>Manual MCP config (any agent)</summary>
+<summary>Manual MCP config (any MCP-compatible client)</summary>
 
 ```json
 {
   "mcpServers": {
     "unerr": {
       "command": "npx",
-      "args": ["@unerr/unerr", "--mcp"]
+      "args": ["@unerr-ai/unerr", "--mcp"]
     }
   }
 }
@@ -107,28 +166,38 @@ Works with any MCP-compatible agent. 15 supported out of the box.
 
 ---
 
-## What you get
+## What changes the moment you connect
 
-### Instant (first session)
+### First session — instant value
 
-- **Graph navigation** — `get_callers` · `get_callees` · `get_imports` · `search_code` in <5ms. The agent stops reading 30 files to find one function.
-- **Blast radius** — before editing, the agent sees every downstream dependency. No more confident wrong changes.
-- **Smart file reads** — `file_read({entity: "functionName"})` returns just that function + context. Not 2000 lines.
-- **Shell compression** — 10 strategies, 645 command classifiers. Diffs, errors, logs, test results, key-value, tabular — each compressed differently. **93% average compression** across real-world benchmarks (2MB → 138KB).
-- **Full output recovery** — when compression is significant, raw output is saved to disk with a recovery path. The agent can always access the original.
-- **Convention awareness** — auto-detected naming, structure, and import patterns injected into agent context.
+- **Graph navigation in <5ms** — `get_entity`, `get_references`, `get_imports`, `search_code`. The agent stops reading 30 files to find one function.
+- **Blast radius before edits** — `get_references` returns every caller. No more confident wrong changes that ripple across services.
+- **Targeted file reads** — `file_read({entity: "fnName"})` returns just that function + relevant conventions/facts, not 2000 lines.
+- **Shell compression** — 11 strategies, 645+ command classifiers. Diffs, errors, logs, test runs, YAML — each compressed differently. **93% average compression** across real-world benchmarks (2 MB → 138 KB). Raw output is kept on disk; the agent can recover it on demand.
+- **Convention awareness** — naming, structure, import patterns auto-detected and injected into the agent's context.
+- **Tool adoption nudging** — five reinforcement layers (exec nudges, hook interception, instruction injection, skill reminders, default-deny of built-ins on Claude Code) push the agent to use the graph instead of grep.
 
-### Compounding (session 2+)
+### Session 2+ — it starts compounding
 
-- **Session persistence** — the agent tomorrow knows what the agent learned today. No more starting from zero.
-- **Convention enforcement** — patterns detected in session 1 are enforced in session 5. No manual `.cursorrules` maintenance.
-- **Anti-pattern rules** — when you revert bad code, unerr learns. That mistake never happens again.
-- **Durability scoring** — code that keeps getting rewritten gets flagged before the agent touches it.
-- **Loop prevention** — circuit breaker fires after repeated failed attempts.
+- **Session persistence** — what the agent learned today is available tomorrow. No more starting from zero.
+- **Fact memory** — `record_fact` persists conventions, decisions, and anti-patterns; `recall_facts` retrieves them with decay-adjusted confidence. Facts also auto-detect from coding sessions.
+- **Episodic narratives** — when you reopen a file, the agent sees what was modified there, when, and why.
+- **Loop prevention** — a circuit breaker fires after repeated failed attempts on the same entity, surfacing the failure mode instead of letting the agent thrash.
+- **Memory-effectiveness scoring** — every fact and convention opens a 5-turn observation window and resolves to a verdict (reinforced / acted_on / caught / ignored / corrected). The Reasoning Quality pane shows the **load-bearing rate** — not just how much the agent remembered, but how much of it actually mattered.
 
-### Shell compression benchmarks
+### Daemon mode — automated behaviors
+
+When `unerr` is running long-lived, these activate in the background:
+
+- **Architecture guard** — flags structural violations before they ship.
+- **Cascade guard** — warns when an edit has wide blast radius.
+- **Convention drift** — detects when new code diverges from established patterns.
+- **Auto-doc** — generates docs for undocumented entities.
+- **Change narrative** — tracks the story behind multi-step refactors.
+- **Loop breaker** — intervenes when the agent is stuck retrying.
+- **Session continuity** — preserves state across restarts.
 
-Every shell command the agent runs is classified (645 command patterns + content heuristics) and compressed with the best-fit strategy:
+### Shell compression benchmarks
 
 | Strategy | What it compresses | Avg compression |
 |----------|-------------------|:-:|
@@ -141,86 +210,109 @@ Every shell command the agent runs is classified (645 command patterns + content
 | **error_diagnostic** | `tsc`, `eslint`, `rustc`, `shellcheck` | **72%** |
 | **key_value** | `env`, `kubectl describe`, `systemctl status` | **48%** |
 | **tree_paths** | `find`, `tree`, `ls -R` | **42%** |
+| **yaml** | YAML configs, `kubectl get -o yaml`, Helm output | adaptive |
 | **omni** | Fallback for unrecognized output | adaptive |
 
-**Overall: 93% compression** (2MB → 138KB across 40 real-world test cases). Low-confidence classifications use smart fallback — tries both the best-guess strategy and generic compression, picks whichever saves more tokens.
+**Overall: 93% compression** (2 MB → 138 KB across 40 real-world test cases).
 
 ### Language support
 
-| Language | Entity Extraction | Edge Extraction | Tree-sitter AST | SCIP |
-|----------|:-:|:-:|:-:|:-:|
-| TypeScript | ✓ | ✓ | ✓ | ✓ |
-| JavaScript | ✓ | ✓ | ✓ | ✓ |
-| Python | ✓ | ✓ | ✓ | ✓ |
-| Go | ✓ | ✓ | ✓ | ✓ |
-| Java | ✓ | ✓ | ✓ | ✓ |
-| Rust | ✓ | ✓ | ✓ | ✓ |
-| C# | ✓ | ✓ | ✓ | — |
-| C / C++ | ✓ | ✓ | ✓ | — |
-| Ruby | ✓ | ✓ | ✓ | — |
-| PHP | ✓ | ✓ | ✓ | — |
-| Kotlin | ✓ | ✓ | ✓ | — |
-| Swift | ✓ | ✓ | ✓ | — |
-
-All 13 languages get full regex-based entity extraction (functions, classes, interfaces, methods with `parent_class` detection) and tree-sitter AST extraction when WASM grammars are available. SCIP integration provides compiler-verified call graphs for TypeScript, Python, Go, Java, and Rust.
+| Language | Tier | Entities | Edges | Tree-sitter | SCIP |
+|----------|:---:|:-:|:-:|:-:|:-:|
+| TypeScript / JavaScript / Python / Go / Java / Kotlin / Scala / Rust / Ruby / C / C++ / C# | 1 | ✓ | ✓ | ✓ | ✓ |
+| PHP / Swift / Lua / Dart / Elixir / Zig | 2 | ✓ | ✓ | ✓ | — |
+
+**Tier 1** (12 languages): full tree-sitter AST + dedicated extraction + SCIP compiler-verified call graphs where the toolchain is on PATH.
+**Tier 2** (6 languages): tree-sitter AST + generic extraction. Regex fallback for the rest.
+
+**Tier 3 (search-discoverable):** Markdown, IaC (`.tf`, `.yaml`, `.toml`), schemas (`.proto`, `.graphql`, `.prisma`), SQL, shell, templates, build files, CI configs — indexed for `search_code` only, no entity extraction.
 
 ---
 
 ## How it works
 
 ```
-AI Agent (Claude Code / Cursor / VS Code / Windsurf / any MCP client)
+AI Agent (Claude Code / Cursor / Windsurf / any MCP client)
     │
-    ├── MCP tools ──→ unerr ──→ CozoDB graph (in-process, <5ms)
-    │                   │
-    │                   ├── Convention engine (auto-detects patterns)
-    │                   ├── Session ledger (cross-session memory)
-    │                   ├── Token budgeter (prevents context rot)
-    │                   └── Compression engine (10 strategies, 645 classifiers)
+    ├── stdio MCP ──→ unerr --mcp (bridge, per IDE session)
+    │                       │
+    │                       └── UDS ──→ unerr (long-lived daemon, owns everything)
+    │                                       │
+    │                                       ├── CozoDB graph     (in-process, <5ms)
+    │                                       ├── Fact store       (cross-session memory)
+    │                                       ├── Timeline + ledger (every tool call)
+    │                                       ├── File watcher     (incremental reindex)
+    │                                       ├── Convention engine
+    │                                       ├── Compression engine (11 strategies, 645+ classifiers)
+    │                                       └── Behavior modules (cascade-guard, loop-breaker, auto-doc…)
     │
-    └── CLI hooks ──→ Output compression ──→ Graph-aware prioritization
+    └── Dashboard ──→ http://localhost:<port> (SSE-streamed live)
 ```
 
-One process. Fully local. No API keys. No network calls. No cloud.
+Two processes, one local DB. Zero network calls. No API keys. No cloud. Your code never leaves the machine.
 
 ---
 
-## MCP Tools (17)
+## MCP Tools (20)
+
+### Graph Intelligence (8)
+
+| Tool | What the agent gets |
+|------|-----|
+| `get_entity` | Any code entity — signature, body, callers, callees, risk |
+| `get_file` | All entities in a file with risk summary |
+| `get_references` | Callers (blast radius) or callees (dependencies) |
+| `get_imports` | Import graph for a file |
+| `search_code` | Graph-ranked full-text search across all entities |
+| `get_conventions` | Detected naming/structure/import patterns + adherence rates |
+| `get_critical_nodes` | High fan-in/fan-out chokepoints |
+| `get_cross_boundary_links` | Unexpected cross-module dependencies, scored by surprise |
+
+### Structural Analysis (3)
+
+| Tool | What the agent gets |
+|------|-----|
+| `get_project_stats` | Entity counts, risk distribution, health grade |
+| `file_connections` | Imports + co-change correlations for a file |
+| `get_test_coverage` | Direct + transitive tests for any entity |
+
+### File Protocol (2)
 
 | Tool | What the agent gets |
 |------|-----|
-| `get_function` | Function body + callers + blast radius + applicable conventions |
-| `get_class` | Class with inheritance, methods, and dependents |
-| `get_file` | All entities, imports, exports, risk summary |
-| `get_callers` | Every caller with file location and risk level |
-| `get_callees` | All downstream dependencies |
-| `get_imports` | Import/dependency graph |
-| `search_code` | Graph-ranked full-text search |
-| `get_rules` | Active rules for a path |
-| `check_rules` | Evaluate rules — returns violations |
-| `get_conventions` | Naming, structure, import conventions |
-| `get_god_nodes` | High fan-in chokepoints |
-| `get_surprising_connections` | Unexpected cross-module dependencies |
-| `file_read` | Entity-targeted reads (not full file dumps) |
-| `file_outline` | File structure without content |
-
-Every response includes `_meta` (latency, risk level, drift status) and contextual warnings.
+| `file_read` | Context-aware read — auto-injects conventions and facts |
+| `file_outline` | File structure (entities, exports) without reading the body |
+
+### Persistent Memory (2)
+
+| Tool | What the agent gets |
+|------|-----|
+| `record_fact` | Persist a convention, decision, or anti-pattern |
+| `recall_facts` | Retrieve facts with hierarchical scope + decay-adjusted confidence |
+
+### Session Narrative — Markers (4)
+
+Inline markers the agent emits as it works. Persisted to the shadow ledger and `.unerr/timeline.db` — powers turn titles, cross-session intent stitching, the resume strip, and loop/blocker miners.
+
+| Tool | What it does |
+|------|-----|
+| `mark_intent` | One-sentence task start (≤80 chars). Becomes the turn title |
+| `mark_decision` | Records a chosen approach + up to 5 alternatives (≤140 chars) |
+| `mark_blocker` | Flags an unresolved obstacle. Carries into the next session's resume strip |
+| `mark_resolution` | Resolves a prior blocker by `marker_id` |
+
+Every response includes `_meta` (latency, risk level, drift status) and inline `ur|<tag>` signals for high-priority guidance (drift, blast-radius warnings, circuit-breaker halts).
 
 ---
 
 <details>
-<summary><strong>Commands</strong></summary>
+<summary><strong>CLI commands</strong></summary>
 
 ```bash
-unerr                 # Start MCP proxy (auto-started by IDE via MCP config)
-unerr status          # Graph stats, health grade, active rules
-unerr stats           # Session and weekly efficiency metrics
-unerr install <agent> # Add unerr to a specific AI coding agent
-unerr init            # Initialize unerr in a new project
-unerr timeline        # What happened across sessions
-unerr rewind          # Restore to a previous working state
-unerr learn           # Teach unerr a convention or correction
-unerr debug           # Diagnostic dump
+unerr                 # Start the long-lived daemon (or resume; auto-spawned by IDE if missing)
+unerr --mcp           # Stdio bridge — what your IDE invokes via .mcp.json
+unerr install <agent> # Install MCP config + skills + instructions for one agent
+unerr uninstall       # Remove unerr integration from agents in this repo
 ```
 
 </details>
@@ -230,26 +322,29 @@ unerr debug           # Diagnostic dump
 
 ```
 src/
-  entrypoints/        CLI entry + state machine
-  intelligence/       CozoDB graph, AST, conventions, rules, search
-  proxy/              MCP server, compression, session stats, token tracking
-  tracking/           Prompt ledger, drift detection, git attribution
-  commands/           CLI commands
-  tools/              MCP tool implementations
-  behaviors/          Agent behavior modules (cascade guard, loop breaker)
-  config/             Agent registry, MCP config writer
-  schemas/            Zod schemas
-  utils/              Logging, detection, git helpers
+  entrypoints/   CLI entry + boot state machine
+  proxy/         MCP server (daemon), stdio↔UDS bridge, session stats, shell compression
+  intelligence/  CozoDB graph, AST extraction, conventions, rules, search, semantic
+  tracking/      Prompt ledger, drift detection, git attribution
+  behaviors/     Cascade guard, loop breaker, auto-doc, change narrative…
+  commands/      CLI commands (install, status, stats, timeline, learn, debug, …)
+  tools/         MCP tool implementations (intelligence + coding)
+  hooks/         Claude Code hook system integration
+  skills/        11 bundled skill definitions
+  server/ + ui/  HTTP API + React (Vite) dashboard
+  config/        Agent registry (16 agents), MCP config writer, instruction injector
+  schemas/       Zod schemas
 ```
 
-**Design principles:**
-- Zero network calls — fully local, no API keys
-- stdout is sacred — MCP JSON-RPC only, everything else to stderr
-- <5ms query responses — CozoDB runs in-process (Rust via NAPI)
-- 30s time-to-value — shallow index first, deep enrichment in background
-- Enhancement, not dependency — agent falls back gracefully if unerr is unavailable
+**Design principles**
 
-**Tech stack:** TypeScript (ESM) · CozoDB (Rust/NAPI) · web-tree-sitter (WASM) · MCP SDK · Ink (React CLI) · tsup · Vitest
+- Zero network calls — fully local, no API keys.
+- stdout is sacred — MCP JSON-RPC only; everything else to stderr.
+- <5 ms query responses — CozoDB runs in-process (Rust via NAPI).
+- First useful output <5 s — shallow index first, deep enrichment in background.
+- Graceful degradation — the agent still works if unerr is down, you just lose the intelligence layer.
+
+**Tech stack** TypeScript (ESM) · CozoDB (Rust/NAPI) · web-tree-sitter (WASM) · MCP SDK · Ink (React CLI) · React + Vite (dashboard) · tsup · Vitest
 
 </details>
 
@@ -260,13 +355,11 @@ src/
 pnpm install
 pnpm run build          # tsup → dist/ (ESM, node20)
 pnpm run dev            # tsx watch
-pnpm run test:run       # full suite (1455 tests)
+pnpm run test:run       # full suite
 pnpm run lint           # biome check
 pnpm run typecheck      # tsc --noEmit
-```
 
-```bash
-pnpm link --global      # make `unerr` available globally
+pnpm link --global      # make local `unerr` available globally
 ```
 
 </details>
@@ -274,15 +367,15 @@ pnpm link --global      # make `unerr` available globally
 <details>
 <summary><strong>Contributing</strong></summary>
 
-Contributions welcome. Please open an issue first.
+Contributions welcome — please open an issue first.
 
 **Before submitting a PR:**
-- Run `pnpm run typecheck && pnpm run lint && pnpm run test:run`
-- All output goes to stderr — never stdout (MCP JSON-RPC channel)
+- `pnpm run typecheck && pnpm run lint && pnpm run test:run`
+- All output to stderr — never stdout (MCP JSON-RPC channel)
 - All CozoDB interactions are async — always `await`
 - Use `.js` extensions in imports (NodeNext resolution)
 
-See [CLAUDE.md](./CLAUDE.md) for detailed conventions.
+See [CLAUDE.md](./CLAUDE.md) for full conventions.
 
 </details>
 
@@ -295,7 +388,7 @@ See [CLAUDE.md](./CLAUDE.md) for detailed conventions.
 ---
 
 <p align="center">
-  <code>npx @unerr/unerr</code>
+  <code>npm install -g @unerr-ai/unerr</code>
   <br /><br />
-  <sub>One command. No cloud. No account. Free.</sub>
+  <a href="https://www.npmjs.com/package/@unerr-ai/unerr"><sub>npm registry</sub></a> · <sub>Fully local. No account. No cloud. Free.</sub>
 </p>