@unerr-ai/unerr 0.0.0-beta.9 → 0.0.1

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://unerr.dev/icon-wordmark.svg" alt="unerr" width="320" />
+  <a href="https://www.unerr.dev/"><img src="https://unerr.dev/icon-wordmark.svg" alt="unerr — local intelligence layer for AI coding agents" width="320" /></a>
 </p>
 
 <p align="center">
@@ -7,14 +7,19 @@
 </p>
 
 <p align="center">
-  The intelligence layer between your AI agent and your codebase.<br/>
-  It sees every dependency, remembers every session, and gets smarter the longer you use it.
+  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="https://www.unerr.dev/"><img src="https://img.shields.io/badge/website-unerr.dev-8B5CF6?style=flat-square&logo=icloud&logoColor=white" alt="Website" /></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>
+  <a href="https://discord.gg/JfZ4pYgb"><img src="https://img.shields.io/badge/community-Discord-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" /></a>
+  <a href="https://x.com/unerr_ai"><img src="https://img.shields.io/badge/follow-@unerr__ai-000000?style=flat-square&logo=x&logoColor=white" alt="X / Twitter" /></a>
+  <a href="https://www.linkedin.com/company/unerr"><img src="https://img.shields.io/badge/linkedin-unerr-0A66C2?style=flat-square&logo=linkedin&logoColor=white" alt="LinkedIn" /></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/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>
 
@@ -24,144 +29,145 @@
 
 ---
 
-## 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
-
-unerr gives it an intelligence layer that compounds. Every caller, every convention, every session — accumulated, not re-derived. The agent stops searching and starts knowing.
+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.
 
 ---
 
-## What happens when you run it
+## What you actually see
+
+Run `unerr` and open the dashboard. Four panes, all live:
 
-**5 seconds later**, your agent has:
+| 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 |
 
-| 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 |
+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>
+<table align="center">
+  <tr>
+    <td align="center" width="240">
+      <img src="https://unerr.dev/open-cli/screenshots/dashboard.png" alt="unerr dashboard — live overview" width="240" height="150" />
+      <br/><sub><strong>Dashboard</strong><br/>Live overview — active sessions, recent tool calls, tokens saved this turn.</sub>
+    </td>
+    <td align="center" width="240">
+      <img src="https://unerr.dev/open-cli/screenshots/token-trace-main.png" alt="unerr token trace — global" width="240" height="150" />
+      <br/><sub><strong>Token Trace · global</strong><br/>Aggregate savings across every session, broken down by mechanism (graph, file_read, shell, dedup, format).</sub>
+    </td>
+    <td align="center" width="240">
+      <img src="https://unerr.dev/open-cli/screenshots/token-session.png" alt="unerr token trace — session" width="240" height="150" />
+      <br/><sub><strong>Token Trace · session</strong><br/>Single session: per-turn savings, mechanism mix, and the compounding multiplier.</sub>
+    </td>
+    <td align="center" width="240">
+      <img src="https://unerr.dev/open-cli/screenshots/token-turn.png" alt="unerr token trace — turn" width="240" height="150" />
+      <br/><sub><strong>Token Trace · turn</strong><br/>Single turn: which tool calls fired, tokens each would have cost without unerr vs what was delivered.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="240">
+      <img src="https://unerr.dev/open-cli/screenshots/reasoning-quality.png" alt="unerr reasoning quality — global" width="240" height="150" />
+      <br/><sub><strong>Reasoning Quality · global</strong><br/>Four-pillar score across cleaner context, fewer wasted turns, fewer breakages, persistent memory.</sub>
+    </td>
+    <td align="center" width="240">
+      <img src="https://unerr.dev/open-cli/screenshots/reasoning-session.png" alt="unerr reasoning quality — session" width="240" height="150" />
+      <br/><sub><strong>Reasoning Quality · session</strong><br/>Per-session: which facts and conventions were reinforced, acted on, ignored, or corrected.</sub>
+    </td>
+    <td align="center" width="240">
+      <img src="https://unerr.dev/open-cli/screenshots/code-base-intelligence.png" alt="unerr code intelligence" width="240" height="150" />
+      <br/><sub><strong>Code Intelligence</strong><br/>Call graph, fan-in/out chokepoints, cross-module surprise links, and a risk grade per file.</sub>
+    </td>
+    <td align="center" width="240">
+      <img src="https://unerr.dev/open-cli/screenshots/project-memory.png" alt="unerr project memory — facts" width="240" height="150" />
+      <br/><sub><strong>Project Memory</strong><br/>Conventions, anti-patterns, decisions — with decay-adjusted confidence and reinforcement counts.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="240" colspan="4">
+      <img src="https://unerr.dev/open-cli/screenshots/activity.png" alt="unerr activity — timeline + heatmap" width="240" height="150" />
+      <br/><sub><strong>Activity</strong><br/>Turn-grouped timeline with a 30-day heatmap — each row is one burst of agent work (intent → tools → outcome).</sub>
+    </td>
+  </tr>
+</table>
 
 ---
 
 ## Quick Start
 
-### Install from npm
+> 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
-# 1. Install globally
 npm install -g @unerr-ai/unerr
-
-# 2. Add to your AI agent (in your project directory)
-unerr install claude-code   # or: cursor, vscode, windsurf, codex, etc.
-
-# 3. Run (indexes your codebase, starts MCP server)
-unerr
+# verify
+unerr --version
 ```
 
-<!--
-### Install from source
+### 2. `cd` into the **root of the repository** you want to enhance
 
 ```bash
-# 1. Clone and build
-git clone https://github.com/unerr-cli.git
-cd unerr-cli
-pnpm install
-pnpm run build
+cd /path/to/your-project   # must be the repo root (where .git or package.json lives)
+```
 
-# 2. Link globally (makes `unerr` command available)
-pnpm link --global
+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. Add to your AI agent (in your project directory)
-cd /path/to/your/project
-unerr install claude-code   # or: cursor, vscode, windsurf, codex, etc.
+### 3. Install unerr for your coding agent
 
-# 4. Run
-unerr
-```
--->
+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:
 
-After install, your AI agent automatically connects to unerr via MCP. No config files to edit manually.
+```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 it does:
 
-## Supported Agents
+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`).
 
-### Integrated
+> Need a different agent or doing it by hand? `unerr install --show-instructions <agent>` prints copy-pasteable setup.
 
-Fully tested with MCP config, instruction injection, skills, and hooks.
+### 4. Run `unerr` — and **keep it running**
 
 ```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/
+unerr        # first run: indexes the repo, starts the daemon; subsequent: resumes in <1s
 ```
 
-### Work in Progress
+**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.
 
-MCP config and basic integration work. Instruction injection, skills, and hooks support varies — contributions welcome.
+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 vscode             # .vscode/mcp.json + .github/copilot-instructions.md
-unerr install zed                # .zed/mcp.json
-unerr install cline              # .cline/mcp.json + .clinerules
-unerr install kiro               # .kiro/mcp.json
-unerr install codex              # .codex/mcp.json + AGENTS.md
-unerr install aider              # .aider/mcp.json
-unerr install opencode           # .opencode/mcp.json
-unerr install trae               # .trae/mcp.json
-unerr install augment            # .augment/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
 ```
 
-16 agents supported (6 integrated, 10 in progress). Works with any MCP-compatible client.
+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
 {
@@ -178,45 +184,39 @@ unerr install continue           # .continue/config.json
 
 ---
 
-## What you get
+## What changes the moment you connect
 
-### Instant (first session)
+### First session — instant value
 
-- **Graph navigation** — `get_entity` · `get_references` · `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 caller via `get_references`. No more confident wrong changes.
-- **Smart file reads** — `file_read({entity: "functionName"})` returns just that function + context. Not 2000 lines.
-- **Shell compression** — 11 strategies, 645+ command classifiers. Diffs, errors, logs, test results, YAML, 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.
-- **Semantic search** — `semantic_search` finds conceptually similar code even with different naming. `find_similar` discovers related entities by embedding distance.
-- **Business context** — `get_business_context` explains why code exists — purpose, feature area, taxonomy.
-- **Tool adoption nudging** — 5-layer reinforcement system ensures agents consistently use unerr MCP tools over built-in alternatives. Exec nudges, hook interception, instruction-level enforcement, and skill reminders — all automatic, zero config.
+- **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.
-- **Fact memory** — `record_fact` persists conventions, decisions, and anti-patterns across sessions. `recall_facts` retrieves them with decay-adjusted confidence.
-- **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.
-- **Shadow ledger** — `unerr_mark_working` snapshots known-good state. `unerr_revert_to_working_state` rolls back when things break. `unerr_get_timeline` shows what changed across sessions.
-- **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.
 
-### Agent behaviors (long-lived mode)
+### Daemon mode — automated behaviors
 
-When running `unerr` as a daemon, these automated behaviors activate:
+When `unerr` is running long-lived, these activate in the background:
 
-- **Architecture guard** — flags structural violations before they ship
-- **Cascade guard** — warns when a change has wide blast radius
-- **Convention drift** — detects when new code diverges from established patterns
-- **Auto-doc** — generates documentation for undocumented entities
-- **Change narrative** — tracks the story behind multi-step refactors
-- **Loop breaker** — intervenes when the agent is stuck in a retry loop
-- **Session continuity** — preserves context across restarts
+- **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.
 
 ### Shell compression benchmarks
 
-Every shell command the agent runs is classified (645+ command patterns + content heuristics) and compressed with the best-fit strategy:
-
 | Strategy | What it compresses | Avg compression |
 |----------|-------------------|:-:|
 | **diff** | `git diff`, patch output | **99%** |
@@ -231,136 +231,106 @@ Every shell command the agent runs is classified (645+ command patterns + conten
 | **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 | Tier | Entity Extraction | Edge Extraction | Tree-sitter AST | SCIP |
+| Language | Tier | Entities | Edges | Tree-sitter | SCIP |
 |----------|:---:|:-:|:-:|:-:|:-:|
-| TypeScript | 1 | ✓ | ✓ | ✓ | ✓ |
-| JavaScript | 1 | ✓ | ✓ | ✓ | ✓ |
-| Python | 1 | ✓ | ✓ | ✓ | ✓ |
-| Go | 1 | ✓ | ✓ | ✓ | ✓ |
-| Java | 1 | ✓ | ✓ | ✓ | ✓ |
-| Kotlin | 1 | ✓ | ✓ | ✓ | ✓ |
-| Scala | 1 | ✓ | ✓ | ✓ | ✓ |
-| Rust | 1 | ✓ | ✓ | ✓ | ✓ |
-| Ruby | 1 | ✓ | ✓ | ✓ | ✓ |
-| C | 1 | ✓ | ✓ | ✓ | ✓ |
-| C++ | 1 | ✓ | ✓ | ✓ | ✓ |
-| C# | 1 | ✓ | ✓ | ✓ | ✓ |
-| PHP | 2 | ✓ | ✓ | ✓ | — |
-| Swift | 2 | ✓ | ✓ | ✓ | — |
-| Lua | 2 | ✓ | ✓ | ✓ | — |
-| Dart | 2 | ✓ | ✓ | ✓ | — |
-| Elixir | 2 | ✓ | ✓ | ✓ | — |
-| Zig | 2 | ✓ | ✓ | ✓ | — |
-
-**Tier 1** (13 languages): Full tree-sitter AST + dedicated extraction plugins + SCIP compiler-verified call graphs where available.
-**Tier 2** (5 languages): Tree-sitter AST + generic extraction. Regex fallback for unsupported languages.
-
-#### Tier 3: Discoverable (Search Only)
-
-Tier 3 files are indexed for search discoverability — agents can find them via `search_code` using filename tokens and format-specific content extraction (headings, resource names, model definitions, etc.). No code entity extraction.
-
-| Category | Extensions |
-|----------|------------|
-| Documentation | `.md`, `.mdx`, `.txt`, `.rst`, `.adoc`, `.org`, `.tex` |
-| Declarative / IaC | `.tf`, `.tfvars`, `.hcl`, `.yaml`, `.yml`, `.toml`, `.json`, `.xml` |
-| Schemas / IDL | `.proto`, `.graphql`, `.gql`, `.prisma`, `.avsc`, `.thrift`, `.smithy` |
-| SQL | `.sql` |
-| Shell | `.sh`, `.bash`, `.zsh` |
-| Web / Templates | `.html`, `.css`, `.scss`, `.sass`, `.less`, `.vue`, `.svelte`, `.astro`, `.j2`, `.tmpl`, `.hbs`, `.ejs`, `.pug` |
-| Build / Make | `.cmake`, `.bazel`, `.bzl`, `.mk`, `Makefile`, `Dockerfile`, `Jenkinsfile` |
-| Config | `.ini`, `.cfg`, `.conf`, `.properties`, `.csv`, `.tsv`, `.editorconfig` |
-| CI/CD | `.github/workflows/*.yml`, `.gitlab-ci.yml` |
+| 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)
-    │
-    ├── MCP tools ──→ unerr ──→ CozoDB graph (in-process, <5ms)
-    │                   │
-    │                   ├── Convention engine (auto-detects patterns)
-    │                   ├── Fact store (cross-session memory)
-    │                   ├── Shadow ledger (mark-working / revert / timeline)
-    │                   ├── Token budgeter (prevents context rot)
-    │                   └── Compression engine (11 strategies, 645+ classifiers)
+AI Agent (Claude Code / Cursor / Windsurf / any MCP client)
     │
-    ├── CLI hooks ──→ Output compression ──→ Graph-aware prioritization
+    ├── 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…)
     │
-    └── Tool nudging ──→ 5-layer adoption reinforcement (hooks, exec, instructions)
+    └── 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 (20)
 
-### Graph Intelligence (15)
+### Graph Intelligence (8)
 
 | Tool | What the agent gets |
 |------|-----|
-| `get_entity` | Any code entity (function, class, type) — signature, body, callers, callees, risk level |
-| `get_file` | All entities defined in a file with risk summary |
-| `get_references` | All callers (blast radius) or callees (dependencies) of an entity |
-| `get_imports` | Import/dependency graph for a file |
-| `search_code` | Graph-ranked full-text search across all indexed entities |
-| `get_rules` | Active rules for a path — optionally validates code against them |
-| `get_conventions` | Detected naming, structure, import conventions with adherence rates |
-| `get_business_context` | Why code exists — purpose, taxonomy, feature area |
-| `get_critical_nodes` | High fan-in/fan-out chokepoints (structural bottlenecks) |
-| `get_cross_boundary_links` | Unexpected cross-module dependencies scored by surprise |
-| `semantic_search` | Vector-based conceptual search (finds similar code with different names) |
-| `find_similar` | Entities similar to a given entity by embedding distance |
-| `get_project_stats` | Project-wide entity counts, risk distribution, health grade |
-| `file_connections` | Connected files — imports, co-change correlations, structure |
-| `get_test_coverage` | Direct and transitive test coverage for any entity |
+| `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 |
 
-### File Protocol (2)
+### Structural Analysis (3)
 
 | Tool | What the agent gets |
 |------|-----|
-| `file_read` | Context-aware file reading — auto-injects conventions and facts |
-| `file_outline` | File structure (functions, classes, exports) without reading content |
+| `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 |
 
-### Persistent Intelligence (2)
+### File Protocol (2)
 
 | Tool | What the agent gets |
 |------|-----|
-| `record_fact` | Persist a convention, decision, or anti-pattern to the fact store |
-| `recall_facts` | Retrieve stored facts with decay-adjusted confidence scoring |
+| `file_read` | Context-aware read — auto-injects conventions and facts |
+| `file_outline` | File structure (entities, exports) without reading the body |
 
-### Shadow Ledger (3)
+### Persistent Memory (2)
 
 | Tool | What the agent gets |
 |------|-----|
-| `unerr_mark_working` | Snapshot current known-good state before risky changes |
-| `unerr_revert_to_working_state` | Roll back to last working snapshot |
-| `unerr_get_timeline` | View modification timeline across sessions |
+| `record_fact` | Persist a convention, decision, or anti-pattern |
+| `recall_facts` | Retrieve facts with hierarchical scope + decay-adjusted confidence |
+
+### Session Narrative — Markers (4)
 
-Every response includes `_meta` (latency, risk level, drift status) and contextual warnings.
+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 uninstall       # Remove unerr integration from agents
-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>
@@ -370,30 +340,29 @@ unerr debug           # Diagnostic dump
 
 ```
 src/
-  entrypoints/        CLI entry + boot state machine
-  intelligence/       CozoDB graph, AST extraction, conventions, rules, search, semantic
-  proxy/              MCP server, shell compression, session stats, token tracking
-  tracking/           Prompt ledger, drift detection, git attribution
-  behaviors/          Agent behavior modules (cascade guard, loop breaker, auto-doc, etc.)
-  commands/           CLI commands (install, status, stats, timeline, learn, debug, etc.)
-  tools/              MCP tool implementations (intelligence + coding)
-  hooks/              Claude Code hook system integration
-  skills/             Bundled skill definitions for agent installation
-  server/             HTTP dashboard API server
-  ui/                 React (Vite) dashboard frontend
-  config/             Agent registry, MCP config writer, settings
-  schemas/            Zod schemas for entity/edge/rule types
-  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>
 
@@ -407,10 +376,8 @@ pnpm run dev            # tsx watch
 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>
@@ -418,15 +385,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>
 
@@ -441,5 +408,5 @@ See [CLAUDE.md](./CLAUDE.md) for detailed conventions.
 <p align="center">
   <code>npm install -g @unerr-ai/unerr</code>
   <br /><br />
-  <a href="https://www.npmjs.com/package/@unerr-ai/unerr"><sub>npm registry</sub></a> · <sub>No cloud. No account. Free.</sub>
+  <a href="https://www.unerr.dev/"><sub>unerr.dev</sub></a> · <a href="https://www.npmjs.com/package/@unerr-ai/unerr"><sub>npm registry</sub></a> · <a href="https://discord.gg/2BjRftz8kG"><sub>Discord</sub></a> · <a href="https://x.com/unerr_ai"><sub>X</sub></a> · <a href="https://www.linkedin.com/company/unerr"><sub>LinkedIn</sub></a> · <sub>Fully local. No account. No cloud. Free.</sub>
 </p>