@unerr-ai/unerr 0.0.1 → 0.1.0

package/README.md

@@ -106,65 +106,76 @@ The agent reads from the same store through MCP — every claim on the dashboard
 
 ## Quick Start
 
-> 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
+### 1. Install globally
 
 ```bash
 npm install -g @unerr-ai/unerr
-# verify
-unerr --version
 ```
 
-### 2. `cd` into the **root of the repository** you want to enhance
+### 2. 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 /path/to/your-project   # must be the repo root (where .git or package.json lives)
+cd ~/project
+unerr install cursor   # install MCP config + skills
+unerr                  # start per-repo process
 ```
 
-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
+One `unerr` process per repo. You start it manually. Good for single-project workflows.
 
-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:
+</td>
+<td>
 
 ```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 daemon initialize       # one-time: register at boot + start
+cd ~/project
+unerr install cursor          # install config + register repo
+# done — IDE auto-connects via unerrd
 ```
 
-What it does:
+A single `unerrd` supervisor manages all repos. Starts at login, spawns per-repo processes on demand, idles unused ones, unified dashboard at `localhost:9847`.
+
+</td>
+</tr>
+</table>
 
-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`).
+> **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.
 
-> Need a different agent or doing it by hand? `unerr install --show-instructions <agent>` prints copy-pasteable setup.
+### What each command does (no hidden behaviors)
 
-### 4. Run `unerr` — and **keep it running**
+| 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 |
+
+### Supported agents
 
 ```bash
-unerr        # first run: indexes the repo, starts the daemon; subsequent: resumes in <1s
+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/
 ```
 
-**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.
-
-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.
+You can install multiple agents in the same repo — each writes its own config, the repo is registered once:
 
 ```bash
-# 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
+unerr install cursor        # registers repo (if daemon running), writes cursor config
+unerr install claude-code   # skips registration (already done), writes claude-code config
 ```
 
-After this, your agent connects automatically the next time you open the IDE. No config files to edit by hand.
+> Need manual setup? `unerr install --show-instructions <agent>` prints copy-pasteable steps.
 
 <details>
 <summary>Manual MCP config (any MCP-compatible client)</summary>
@@ -182,6 +193,23 @@ After this, your agent connects automatically the next time you open the IDE. No
 
 </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` |
+
+Idempotent — re-running updates if content changed, skips if identical. Remove with `unerr uninstall`.
+
+</details>
+
 ---
 
 ## What changes the moment you connect
@@ -247,6 +275,33 @@ When `unerr` is running long-lived, these activate in the background:
 
 ---
 
+## How unerr compares
+
+Adjacent tools each own one layer — graph navigation, persistent memory, or output compression. unerr integrates all three, plus the drift prevention that keeps the graph tools in active rotation. Peer strengths are real; the table credits them where they win.
+
+| Capability | unerr | Graphify (~47K) | Serena (~23K) | claude-mem (~75K) | RTK (~40K) |
+|---|:---:|:---:|:---:|:---:|:---:|
+| **Code intelligence** | | | | | |
+| Pre-hoc file-read intercept — resolves entity via graph, returns ~200 lines + conventions + blast radius instead of a 3,000-line file | ✓ | ✗ | Partial | ✗ | ✗ |
+| Convention auto-detection — naming, structure, import direction from ≥70% adherence; no manual rules file | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Drift / staleness signals — `ur\|dft` fires when code moves under stored memory | ✓ | ✗ | ✗ | ✗ | ✗ |
+| **Memory & continuity** | | | | | |
+| Persistent across sessions — typed facts with per-type decay, contradiction handling | ✓ | ✗ | ✗ | ✓ | ✗ |
+| Per-repo isolation — all state in `.unerr/` inside the repo, no cross-project leakage | ✓ | ✓ | ✓ | ✗ | — |
+| **Runtime** | | | | | |
+| Zero LLM in core — no API keys, no per-turn inference cost | ✓ | ✓ | ✓ | ✗ | ✓ |
+| Keeps MCP tools in active rotation — without enforcement, agents revert to built-in Read/Grep/Glob within 3–5 turns | ✓ | ✗ | ✗ | ✗ | ✗ |
+
+Three numbers behind the table:
+
+- **~84%** of an AI coding agent's tokens are tool output, mostly file reads (JetBrains, NeurIPS 2025 DL4Code Workshop) — unerr intercepts before the read.
+- **0** LLM calls per query in the Free tier — facts, conventions, and drift signals are algorithmic.
+- **3–5** turns is how long agents take to revert to built-in Read/Grep/Glob without drift prevention.
+
+Honest acknowledgements: unerr is the new entrant with fewer stars than every peer; the install is heavier than `brew install` (Node + index step); TypeScript is deepest, other languages run on tree-sitter; no semantic vector retrieval and no narrative session resume in the Free tier.
+
+---
+
 ## How it works
 
 ```
@@ -327,12 +382,31 @@ Every response includes `_meta` (latency, risk level, drift status) and inline `
 <summary><strong>CLI commands</strong></summary>
 
 ```bash
-unerr                 # Start the long-lived daemon (or resume; auto-spawned by IDE if missing)
+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 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 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
 ```
 
+See the [full command reference](#daemon-command-reference) below.
+
 </details>
 
 <details>
@@ -399,6 +473,112 @@ 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.
+
+### Lifecycle
+
+```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
+```
+
+### Repository Management
+
+```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 daemon autostart off      # Remove the platform service
+unerr daemon autostart status   # Show whether auto-start is installed and running
+```
+
+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
+
+Total cold-start latency (supervisor not running → first MCP response): **<2 seconds**.
+
+---
+
 ## License
 
 [Elastic License 2.0 (ELv2)](./LICENSE) — free to use, modify, and distribute. Cannot be offered as a hosted service.