@unerr-ai/unerr 0.1.6 → 0.1.8

package/README.md

@@ -48,7 +48,7 @@ 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 |
+| **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, web fetches). | 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 |
@@ -57,6 +57,10 @@ The agent reads from the same store through MCP — every claim on the dashboard
 
 ### See it in action
 
+<p align="center">
+  <img src="https://unerr.dev/open-cli/video/unerr_short.gif" alt="unerr in action" width="720" />
+</p>
+
 <table align="center">
   <tr>
     <td align="center" width="240">
@@ -65,7 +69,7 @@ The agent reads from the same store through MCP — every claim on the dashboard
     </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>
+      <br/><sub><strong>Token Trace · global</strong><br/>Aggregate savings across every session, broken down by mechanism (graph, file_read, fetch_url, 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" />
@@ -106,68 +110,30 @@ The agent reads from the same store through MCP — every claim on the dashboard
 
 ## Quick Start
 
-### 1. Install globally
-
-```bash
-npm install -g @unerr-ai/unerr
-```
+Three steps. Step 1 is once per machine; steps 2–3 are per repo.
 
-### 2. Verify your environment
+### 1. Install the CLI
 
 ```bash
-unerr doctor
-```
-
-This ensures `unerr` is available in **all** terminal sessions — not just the one you installed from. If your PATH isn't configured correctly (common with nvm, fnm, volta, or pnpm), `unerr doctor` detects the issue and offers to fix it automatically by updating your shell config (`~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`).
-
-> **Why this matters:** Global npm packages are installed to a directory that some shells don't include by default. Without this step, `unerr` might work in your current terminal but fail in new ones — which breaks IDE integrations that spawn `unerr --mcp` in a fresh shell.
-
-### 3. Choose your mode
-
-<table>
-<tr>
-<th width="50%">Standalone (single repo, simple)</th>
-<th width="50%">Daemon Mode (multi-repo, recommended)</th>
-</tr>
-<tr>
-<td>
-
-```bash
-cd ~/project
-unerr install cursor   # install MCP config + skills
-unerr                  # start per-repo process
+npm install -g @unerr-ai/unerr
 ```
 
-One `unerr` process per repo. You start it manually. Good for single-project workflows.
+Puts the `unerr` binary on your PATH. If the global `npm` directory isn't already in your shell's PATH (common with nvm, fnm, volta, pnpm), run `unerr doctor` once — it patches your shell config and won't need to run again.
 
-</td>
-<td>
+### 2. Install for your agent (per repo)
 
 ```bash
-unerr daemon initialize       # one-time: register at boot + start
-cd ~/project
-unerr install cursor          # install config + register repo
-# done — IDE auto-connects via unerrd
+cd ~/your-project
+unerr install cursor
 ```
 
-A single `unerrd` supervisor manages all repos. Starts at login, spawns per-repo processes on demand, idles unused ones, unified dashboard at `localhost:9847`.
+Writes the MCP config, skills, hooks, and instructions for that agent in the current repo. Swap `cursor` for any of the [supported agents](#supported-agents): `claude-code`, `windsurf`, `gemini-cli`, `antigravity`, `github-copilot-cli`.
 
-</td>
-</tr>
-</table>
-
-> **Important:** After running `unerr install`, restart your coding AI session (close and reopen the IDE or start a new chat) for unerr to take effect. The agent needs to pick up the newly installed MCP config, skills, and instructions.
+### 3. Restart your IDE
 
-> **`unerr: command not found` in a new terminal?** Run `unerr doctor` in the terminal where it works — it will detect the PATH issue and fix it so `unerr` is recognized everywhere.
+Close and reopen your IDE (or start a new chat session). Your agent picks up unerr through MCP — graph-backed tools, persistent memory, shell compression all available immediately.
 
-### What each command does (no hidden behaviors)
-
-| Command | What it does | What it does NOT do |
-|---------|------|------|
-| `unerr daemon initialize` | Registers unerrd at boot (launchd/systemd/schtasks) + starts it | - |
-| `unerr install <agent>` | MCP config + skills + hooks + instructions + gitignore. If unerrd running: registers the repo | Start unerrd, start per-repo process |
-| `unerr --mcp` | Bridges to running process (standalone or daemon-managed) | Spawn unerrd, register repos, start processes |
-| `unerr` (no args) | Starts a standalone per-repo proxy | Touch the daemon |
+> **Dashboard:** <http://localhost:9847> — open any time to watch token savings, reasoning quality, and the codebase map update as your agent works.
 
 ### Supported agents
 
@@ -180,11 +146,11 @@ unerr install gemini-cli         # → .gemini/settings.json + GEMINI.md + .gemi
 unerr install github-copilot-cli # → .copilot/mcp-config.json + .github/copilot-instructions.md + .github/skills/
 ```
 
-You can install multiple agents in the same repo — each writes its own config, the repo is registered once:
+Install multiple agents in the same repo — each writes its own config:
 
 ```bash
-unerr install cursor        # registers repo (if daemon running), writes cursor config
-unerr install claude-code   # skips registration (already done), writes claude-code config
+unerr install cursor
+unerr install claude-code
 ```
 
 > Need manual setup? `unerr install --show-instructions <agent>` prints copy-pasteable steps.
@@ -206,17 +172,16 @@ unerr install claude-code   # skips registration (already done), writes claude-c
 </details>
 
 <details>
-<summary>What <code>unerr install</code> does (detailed)</summary>
-
-| Step | What | File(s) written |
-|------|------|------|
-| MCP config | Agent-specific config pointing to `unerr --mcp` | `.mcp.json`, `.cursor/mcp.json`, etc. |
-| Skills | 12 skill definitions teaching the agent when to use each tool | `.claude/skills/`, `.cursor/rules/`, etc. |
-| Instructions | Tool-routing table injected into agent instruction file | `CLAUDE.md`, `.cursor/rules/unerr-instructions.mdc` |
-| Hooks | Shell compression + tool-adoption nudging | `.claude/settings.json`, `.cursor/hooks.json` |
-| Repo registration | If unerrd is running: registers repo with supervisor | Only when daemon is active |
-| Gitignore | Ensures `.unerr/` isn't committed | `.gitignore` |
-| Force tools | Claude Code only: denies built-in Read/Grep/Glob (opt out: `--no-force-tools`) | `.claude/settings.json` |
+<summary>What <code>unerr install</code> writes</summary>
+
+| Item | File(s) |
+|------|------|
+| MCP config pointing to `unerr --mcp` | `.mcp.json`, `.cursor/mcp.json`, … |
+| Skills — 12 definitions teaching the agent when to use each tool | `.claude/skills/`, `.cursor/rules/`, … |
+| Instructions — tool-routing table injected into the agent's instruction file | `CLAUDE.md`, `.cursor/rules/unerr-instructions.mdc` |
+| Hooks — shell compression + tool-adoption nudging | `.claude/settings.json`, `.cursor/hooks.json` |
+| Gitignore — keeps `.unerr/` out of commits | `.gitignore` |
+| Force tools (Claude Code only) — denies built-in Read/Grep/Glob so the agent uses graph tools. Opt out with `--no-force-tools`. | `.claude/settings.json` |
 
 Idempotent — re-running updates if content changed, skips if identical. Remove with `unerr uninstall`.
 
@@ -232,6 +197,7 @@ Idempotent — re-running updates if content changed, skips if identical. Remove
 - **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.
+- **Web fetches** — `fetch_url` strips page chrome via Defuddle/Readability, converts to markdown, splits into heading-bounded passages, optionally re-ranks with BM25 when a `prompt` is supplied, and caches by content hash. Replaces built-in WebFetch — **5–10× fewer tokens** per page.
 - **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.
 
@@ -243,9 +209,9 @@ Idempotent — re-running updates if content changed, skips if identical. Remove
 - **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.
 
-### Daemon mode — automated behaviors
+### Background behaviors
 
-When `unerr` is running long-lived, these activate in the background:
+While unerr is running these activate automatically — no extra commands:
 
 - **Architecture guard** — flags structural violations before they ship.
 - **Cascade guard** — warns when an edit has wide blast radius.
@@ -321,20 +287,23 @@ AI Agent (Claude Code / Cursor / Windsurf / any MCP client)
     │
     ├── stdio MCP ──→ unerr --mcp (bridge, per IDE session)
     │                       │
-    │                       └── UDS ──→ unerr (long-lived daemon, owns everything)
+    │                       └── UDS ──→ unerrd (lightweight Node process,
+    │                                           one per machine, auto-spawned)
     │                                       │
-    │                                       ├── 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…)
+    │                                       └── per-repo unerr process(es)
+    │                                              │
+    │                                              ├── 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…)
     │
-    └── Dashboard ──→ http://localhost:<port> (SSE-streamed live)
+    └── Dashboard ──→ http://localhost:9847 (SSE-streamed live)
 ```
 
-Two processes, one local DB. Zero network calls. No API keys. No cloud. Your code never leaves the machine.
+One local DB per repo. Zero network calls. No API keys. No cloud. Your code never leaves the machine.
 
 ---
 
@@ -386,6 +355,12 @@ Inline markers the agent emits as it works. Persisted to the shadow ledger and `
 | `mark_blocker` | Flags an unresolved obstacle. Carries into the next session's resume strip |
 | `mark_resolution` | Resolves a prior blocker by `marker_id` |
 
+### Web Fetch (1)
+
+| Tool | What the agent gets |
+|------|-----|
+| `fetch_url` | DOM-extracted markdown of a web page (Defuddle/Readability), split into heading-bounded passages, optionally re-ranked by BM25 against a `prompt`, cached by content hash. Replaces built-in WebFetch — 5–10× fewer tokens. Optional Playwright SPA fallback. |
+
 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).
 
 ---
@@ -394,31 +369,17 @@ Every response includes `_meta` (latency, risk level, drift status) and inline `
 <summary><strong>CLI commands</strong></summary>
 
 ```bash
-unerr                 # Start per-repo daemon (or resume; auto-spawned by IDE if missing)
-unerr --mcp           # Stdio bridge — what your IDE invokes via .mcp.json
-unerr doctor          # Check PATH + environment; auto-fix if unerr isn't in all terminals
-unerr install <agent> # Install MCP config + skills + instructions for one agent
-unerr uninstall       # Remove unerr integration from agents in this repo
-unerr status          # Show proxy health, entity count, graph age
+unerr install <agent> # MCP config + skills + hooks + instructions for one agent
+unerr uninstall       # Remove unerr integration from this repo
+unerr doctor          # Check PATH + environment, auto-fix if unerr isn't on all shells
+unerr status          # Proxy health, entity count, graph age
 unerr stats           # Session statistics (tokens, tool calls, compression)
-```
 
-**Daemon supervisor** (multi-repo management):
-
-```bash
-unerr daemon start              # Start the unerrd supervisor
-unerr daemon stop               # Gracefully stop unerrd + all managed repos
-unerr daemon status             # Show all managed repos, PIDs, memory, idle time
-unerr daemon add <path>         # Register a repo (indexes on next access)
-unerr daemon remove <path>      # Unregister a repo
-unerr daemon config <path> <k=v> # Set per-repo settings (idleTimeout, javaBuildTool, etc.)
-unerr daemon autostart on|off|status  # Manage start-at-login (launchd/systemd/schtasks)
-unerr daemon logs [--repo <path>] [--follow]  # Tail daemon/repo logs
-unerr daemon dashboard          # Open the unified dashboard in browser
-unerr daemon update             # Check for updates, install, restart
+unerr --mcp           # Stdio bridge — what your IDE invokes via .mcp.json
+unerr                 # Start a standalone per-repo proxy (rare — IDE invocation covers this)
 ```
 
-See the [full command reference](#daemon-command-reference) below.
+`unerr pm …` manages the cross-repo `unerrd` process — see the [reference](#process-manager-command-reference) below.
 
 </details>
 
@@ -428,16 +389,17 @@ See the [full command reference](#daemon-command-reference) below.
 ```
 src/
   entrypoints/   CLI entry + boot state machine
-  proxy/         MCP server (daemon), stdio↔UDS bridge, session stats, shell compression
+  proxy/         Per-repo MCP server, stdio↔UDS bridge, session stats, shell compression
+  daemon/        Process manager (unerrd) — registry, supervisor, spawn lock, HTTP API
   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, …)
+  commands/      CLI commands (install, status, stats, pm, debug, …)
   tools/         MCP tool implementations (intelligence + coding)
   hooks/         Claude Code hook system integration
-  skills/        11 bundled skill definitions
+  skills/        12 bundled skill definitions
   server/ + ui/  HTTP API + React (Vite) dashboard
-  config/        Agent registry (16 agents), MCP config writer, instruction injector
+  config/        Agent registry, MCP config writer, instruction injector
   schemas/       Zod schemas
 ```
 
@@ -486,109 +448,30 @@ See [CLAUDE.md](./CLAUDE.md) for full conventions.
 
 ---
 
-## Daemon Command Reference
-
-The `unerrd` supervisor is a single lightweight process that manages all your registered repositories. It replaces the need to run `unerr` separately in each repo.
+## Process Manager Command Reference
 
-### Lifecycle
+`unerrd` is a lightweight Node process that supervises every registered repo. Your IDE invocation auto-spawns it; it exits cleanly after 30 minutes of no MCP activity. You rarely run these commands directly, but they're here when you want a look under the hood.
 
 ```bash
-unerr daemon start              # Start supervisor (PID-locked, one instance per machine)
-unerr daemon stop               # Graceful shutdown — stops all child processes, flushes state
-unerr daemon status             # Overview: all repos, their state (running/stopped/idle), PIDs,
-                                #   memory usage, connection count, idle time, update notices
-```
+unerr pm status                       # PID, uptime, repos, memory, idle countdown
+unerr pm start                        # Start manually (auto-spawn usually covers this)
+unerr pm stop                         # Graceful shutdown — stops children, flushes state
 
-### Repository Management
+unerr pm add <path>                   # Register a repo (auto-registered on first MCP call)
+unerr pm remove <path>                # Unregister a repo
+unerr pm config <path> <key>=<value>  # Per-repo settings (idleTimeout, javaBuildTool, …)
 
-```bash
-unerr daemon add <path>         # Register a repo with the supervisor
-                                #   - Auto-derives a unique label from the directory name
-                                #   - Mirrors settings to <repo>/.unerr/config.json
-                                #   - Detects parent/child directory conflicts
-                                #   - Installs platform auto-start on first add
-
-unerr daemon remove <path>      # Unregister — stops the child process if running, removes entry
-
-unerr daemon config <path> <key>=<value>  # Set per-repo settings:
-                                #   idleTimeout=600       seconds before idle sweep stops the repo
-                                #   javaBuildTool=gradle  skip detection heuristic
-                                #   autostart=false       exclude from warm-start at boot
-```
-
-### Auto-Start (Start at Login)
-
-```bash
-unerr daemon autostart on       # Install platform service:
-                                #   macOS: ~/Library/LaunchAgents/dev.unerr.daemon.plist
-                                #   Linux: ~/.config/systemd/user/unerr-daemon.service
-                                #   Windows: schtasks /create ... (or Startup folder .cmd)
+unerr pm logs                         # Tail ~/.unerr/logs/unerrd.log
+unerr pm logs --repo <path>           # Tail a specific repo's log
+unerr pm logs --bridge --follow       # Stream bridge session logs continuously
+unerr pm logs --boot                  # Most recent spawn sequence only
 
-unerr daemon autostart off      # Remove the platform service
-unerr daemon autostart status   # Show whether auto-start is installed and running
+unerr pm dashboard                    # Open http://localhost:9847 in your browser
 ```
 
-Auto-start is also installed automatically on your first `unerr install` or `daemon add` — no manual step needed. Skipped in CI/container environments.
-
-### Warm Start
-
-After boot, the supervisor pre-spawns your Most Recently Used repos at low priority:
-
-```bash
-unerr daemon set --warm-start-budget 3      # Max repos to warm-start (default: 3)
-unerr daemon set --warm-start-idle-days 7   # Skip repos inactive for >N days
-unerr daemon set --warm-start-delay-ms 5000 # Delay before warm-start begins
-```
-
-Warm-start aborts if the system is on battery or under high load.
-
-### Logs
-
-```bash
-unerr daemon logs                     # Tail the supervisor log (~/.unerr/logs/unerrd.log)
-unerr daemon logs --repo <path>       # Tail a specific repo's log
-unerr daemon logs --bridge            # Tail bridge session logs
-unerr daemon logs --follow            # Stream continuously (like tail -f)
-unerr daemon logs -n 50              # Last N lines
-unerr daemon logs --boot              # Show only the most recent boot sequence
-```
-
-### Dashboard
-
-```bash
-unerr daemon dashboard          # Opens http://localhost:9847 in your default browser
-```
-
-The unified dashboard shows:
-- **Global overview** — all registered repos, their health, active sessions
-- **Repo switcher** — click into any repo for its full intelligence dashboard
-- **Supervisor info** — uptime, memory, warm-start events, version status
-
-### Updates
-
-```bash
-unerr daemon update             # Check npm registry → confirm → stop → install → restart → verify
-unerr daemon dismiss-update <version>  # Suppress notification for a specific version
-```
-
-Update notifications appear as:
-- A CLI banner on `unerr daemon status` and `unerr` startup
-- A dashboard banner with version diff and changelog link
-- An `_meta["dev.unerr/update_available"]` field in MCP responses (when >2 minor versions behind)
-
-Updates are never auto-applied — the agent and supervisor remain stable mid-session.
-
-### How auto-spawn works
-
-When your IDE opens and spawns `unerr --mcp`:
-
-1. Bridge checks for a per-repo UDS socket (`.unerr/state/proxy.sock`)
-2. If not found, queries the supervisor's UDS socket (`~/.unerr/state/unerrd.sock`)
-3. If supervisor isn't running, auto-spawns it as a detached background process
-4. Supervisor ensures the repo is registered and its child process is running
-5. Bridge connects — MCP requests flow through
+**Dashboard** shows the global overview (registered repos, health, active sessions), a repo switcher into each repo's full intelligence dashboard, and process-manager info (uptime, memory, idle countdown).
 
-Total cold-start latency (supervisor not running → first MCP response): **<2 seconds**.
+**Updates** — `npm i -g @unerr-ai/unerr` and restart the IDE. The next bridge invocation re-spawns the manager on the new version.
 
 ---