knit-mcp 0.16.0 → 0.21.0

package/README.md

@@ -3,7 +3,7 @@
   <a href="https://github.com/PDgit12/knit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/PDgit12/knit/ci.yml?style=for-the-badge&label=CI&color=10b981" alt="CI" /></a>
   <img src="https://img.shields.io/badge/license-MIT-3b82f6?style=for-the-badge" alt="license" />
   <img src="https://img.shields.io/badge/node-%E2%89%A518-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="node" />
-  <img src="https://img.shields.io/badge/MCP%20tools-55-7c3aed?style=for-the-badge" alt="tools" />
+  <img src="https://img.shields.io/badge/MCP%20tools-56-7c3aed?style=for-the-badge" alt="tools" />
   <img src="https://img.shields.io/badge/agents-6-10b981?style=for-the-badge" alt="agents supported" />
   <img src="https://img.shields.io/badge/local--first-100%25-3b82f6?style=for-the-badge" alt="local-first" />
 </p>
@@ -20,14 +20,14 @@
   <a href="#-quick-start">Quick start</a> ·
   <a href="#-what-knit-is">What it is</a> ·
   <a href="#-how-search-works">How search works</a> ·
-  <a href="#-55-mcp-tools">Tools</a> ·
+  <a href="#-56-mcp-tools">Tools</a> ·
   <a href="#-the-dashboard">Dashboard</a> ·
-  <a href="#-how-its-different">vs mem0/Letta</a>
+  <a href="#-why-knit">Why Knit</a>
 </p>
 
 ---
 
-## 🧠 What knit is
+## 🧠 What Knit is
 
 Knit gives **any MCP-speaking coding agent** the right defaults automatically — because you can't predict how a user will phrase a request, and every agent (Claude Code, Cursor, Codex CLI, Cline, Continue, GitHub Copilot) ends up burning tokens re-discovering the same project facts. Knit does four jobs at once:
 
@@ -36,11 +36,11 @@ Knit gives **any MCP-speaking coding agent** the right defaults automatically
 | 🧠 **Memory** | Every project keeps a brain at `~/.knit/projects/<hash>/`. Sessions compound: learnings, false positives, session summaries, and a static-analysis import graph are all queryable next session. Cross-project pool at `~/.knit/global/`. |
 | 🪶 **Tokens** | `CLAUDE.md` is ~2 KB (project facts only). Protocol depth is fetched on demand via `knit_get_workflow(phase)`. Per-cache-hit savings ≈ 15K tokens (calibrated from instrumented RESEARCH phases — override via env). Reuse-ratio + ROI surfaced in the dashboard. |
 | 🛠️ **Workflow** | A 4-tier classification (Inquiry / Trivial / Standard / Complex) with phase-triggered plan mode, quality-gated `LEARN`, and team-scoped git worktrees so parallel agents don't step on each other. |
-| 📊 **Dashboard** | New in v0.13. `knit ui` opens a local-first analytics dashboard at `http://127.0.0.1:7421` — bento layout, brain savings, per-project ROI, **force-directed brain graph**, real-time sync via SSE. See [Dashboard](#-the-dashboard). |
+| 📊 **Dashboard** | `knit` opens the brain — a local-first dashboard at `http://127.0.0.1:7421`: bento layout, brain savings, per-project ROI, **force-directed brain graph**, real-time sync via SSE. See [Dashboard](#-the-dashboard). |
 
 **Local-first** invariant: zero cloud calls in memory/retrieval/classification. Dashboard binds to `127.0.0.1` only, with Host/Origin validation + CSP headers. Your brain stays on your machine.
 
-It's a **single product**, not four. Every design choice has to win on memory + tokens + workflow + analytics together.
+One product: every design choice wins on memory, tokens, workflow, and analytics together.
 
 ---
 
@@ -48,12 +48,28 @@ It's a **single product**, not four. Every design choice has to win on memory +
 
 ```bash
 npm install -g knit-mcp
-knit setup       # adds Knit MCP to your agent's config (Claude Code / Cursor / Codex / etc.)
-knit ui          # opens the brain dashboard at http://127.0.0.1:7421 (optional but recommended)
+knit setup       # one-time: register Knit with your agents (Claude Code / Cursor / Codex / …)
+knit             # open the brain — the dashboard at http://127.0.0.1:7421
 ```
 
+Two commands: `knit setup` for one-time agent registration, then `knit` to open the brain. Agents communicate with the MCP server over stdio; that process is launched by the host, not invoked manually.
+
 **No per-project setup.** Open your MCP-speaking agent in any project — the first MCP tool call auto-initializes the brain, hooks, and per-project CLAUDE.md block.
 
+### First prompt — onboard your project
+
+Once Knit is connected, open your project in your agent and paste this once. Fill in the brackets, or just describe the project in your own words — the agent does the rest:
+
+> You have the Knit MCP connected. Call `knit_load_session`, then call `knit_onboard` with:
+> - **project_description** — what this project is
+> - **intent** — what I'm building right now
+> - **strictness** — `off` | `warn` | `block` (how strictly to enforce the workflow)
+> - **focus_domains** — comma-separated areas (e.g. `api, billing`)
+>
+> Then summarize what you configured and call `knit_classify_task` for my first task.
+
+Knit persists these preferences and surfaces your project intent at the start of every session. It's a plain MCP tool, so the same prompt works on **any** host — Claude Code, Cursor, Codex, Cline, Continue, Copilot — new session or resumed.
+
 ### Adoption per agent
 
 v0.14: a single `knit setup` detects **every** installed MCP-speaking agent on
@@ -78,8 +94,6 @@ per-agent manual setup, no copy-pasted JSON.
 
 > **Supported shells:** macOS, Linux, WSL, Git Bash, PowerShell. Windows `cmd.exe` is not supported as the hook-runner shell — use PowerShell (default in modern Windows Terminal) or Git Bash.
 
-> **Supported shells:** macOS, Linux, WSL, Git Bash, PowerShell. Windows `cmd.exe` is not supported as the hook-runner shell — use PowerShell (default in modern Windows Terminal) or Git Bash.
-
 ### Quiet mode
 
 Knit ships **Protocol Guard in `warn` mode by default** — hooks print reminders, they never block. Fully silent:
@@ -88,83 +102,154 @@ Knit ships **Protocol Guard in `warn` mode by default** — hooks print reminder
 knit_set_protocol_strictness({ level: "off" })
 ```
 
-### Uninstall in 30 seconds
+### Uninstall
+
+One command kills all data:
 
 ```bash
 rm -rf ~/.knit                                 # all per-project + global memory
 ```
 
-Then:
-1. Remove `"knit-brain"` from `mcpServers` in `~/.claude.json`
-2. Delete the `<!-- knit:start --> ... <!-- knit:end -->` block from each project's `CLAUDE.md`
-3. Remove `_knitOwned` entries from each project's `.claude/settings.local.json`
+Then remove Knit's registration from each agent you've used `knit setup` with:
+
+| Agent | File to edit | What to remove |
+|---|---|---|
+| Claude Code (global) | `~/.claude.json` | the `"knit-brain"` entry under `mcpServers` |
+| Claude Code (global) | `~/.claude/CLAUDE.md` | the `## Knit Brain (MCP)` block (appended by `knit setup`) |
+| Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` | the `"knit-brain"` entry under `mcpServers` |
+| Codex CLI | `~/.codex/config.toml` | the `[mcp_servers.knit-brain]` section |
+| Cline | `~/.cline/mcp.json` | the `"knit-brain"` entry under `mcpServers` |
+| Continue | `.continue/mcpServers/knit-brain.yaml` | delete the file |
+| VS Code Copilot | `.vscode/mcp.json` (or user `mcp.json`) | the `"knit-brain"` entry under `servers` |
+
+Per-project residue to clean:
+
+- `<project>/CLAUDE.md` — delete the `<!-- knit:start --> ... <!-- knit:end -->` block
+- `<project>/.claude/settings.local.json` — remove hook entries tagged `_knitOwned: true`
+- `<project>/.claude/KNIT.md` — sidecar written when CLAUDE.md had no markers; delete if present
+- `<project>/.claude/agents/knit-*.md` — installed VoltAgent subagents; delete the `knit-` prefixed ones
+- `<project>/AGENTS.md` — if you use Codex CLI or Cline, the marker-wrapped Knit block was written here; delete the block or the file
 
 Knit writes nowhere else on your machine.
 
 ---
 
+## 🎬 A real session
+
+A new TypeScript project, from install to a compounding brain:
+
+1. **Install + register.** `npm i -g knit-mcp && knit setup` — Knit registers with every MCP-speaking agent on the machine.
+2. **Onboard.** Open the project in your agent and paste the onboarding prompt. The agent calls `knit_onboard` — *"Project: a billing API. Intent: add Stripe webhooks. strictness: warn. focus: api, webhooks."* Knit persists those preferences and records the intent.
+3. **Ask for the feature.** The agent calls `knit_classify_task` → e.g. *complex, high-risk* → plan mode. It pulls context with `knit_build_context` (ripple effects), `knit_search_learnings` (anything learned before), and `knit_query_dependents` on the files it will touch.
+4. **Build + verify.** It implements, runs `knit_verify_claim` to check its claims against the knowledge graph, and `knit_record_learning` to save what was non-obvious.
+5. **Compound.** Next session, `knit_load_session` surfaces your intent plus that learning — the brain is already sharper. Run **`knit`** to see it: the dashboard shows the project, its knowledge index, learnings, and token ROI building over time. Hit **Refresh** to re-index or **Export brain** to write an Obsidian vault.
+
+Every step is local, deterministic, and works on any MCP host.
+
 ## 🔍 How search works
 
 Knit's retrieval is **BM25 + Reciprocal Rank Fusion** over your learnings,
-session summaries, and the cross-project pool, with two cheap-but-honest
-lexical-bridging layers stacked on top: **2-gram fallback** for typos and
-rare compounds, and **curated coding-domain synonym expansion** for the
-most common semantic-gap pairs. No vector embeddings, no remote inference,
-no API calls.
-
-**Why this design choice (not an oversight):**
-
-- **Deterministic.** Same query → same ranking, every time. No model
-  drift, no upgrade-day surprises.
-- **Fast.** Sub-millisecond on corpora ≤ 1K entries (your typical
-  project memory). No cold start, no model load.
-- **Local-first.** Zero network calls. Your memory never leaves the
-  machine.
-- **Auditable.** You can explain every hit by looking at term overlap
-  + the synonym dictionary (50 pairs, hand-curated). No "the model
-  said so."
-- **Honest at the boundary.** The bench has documented misses where
-  even synonym expansion can't bridge the gap — we ship those visible,
-  not hidden.
-
-**What it does well.** Exact term match, identifier search
-(`knit_classify_task`), rare-term emphasis (e.g. `PIPE_BUF`), multi-word
-ranking, tag filtering, cross-project diversification (max 2 per
-project), branch diversification on sessions (max 2 per branch). **Typo
-recovery via 2-gram fallback** (`knit_clasify` → `knit_classify_task`).
-**Synonym recovery via curated dictionary** (`hook` ↔ `webhook`,
-`schema` ↔ `migration`, `auth` ↔ `authentication`, `cache` ↔ `memo`,
-`deploy` ↔ `ship` ↔ `release`, etc. — see
-[`src/engine/retrieval/synonyms.ts`](src/engine/retrieval/synonyms.ts)
-for the full ~50-pair dictionary). Synonym matches scored at 0.4× of a
-direct BM25 hit so genuine matches always rank higher.
-
-**What it still cannot do.** Multi-word paraphrase ("how do schema
-changes ship" with no shared terms). Deep abstraction-level bridging
-("data consistency" → "atomic temp+rename"). Question intent
-("what's the right pattern for X"). Negation. Cross-entry synthesis
-("based on the auth lessons, what should I do for OAuth"). These need
-either embeddings (model dependency + bundle weight, breaks local-first
-unless run locally via ONNX) or an LLM call layer (Knit-as-retrieval
-becomes Knit-as-agent, different identity). v0.20+ candidate: hybrid
-retrieval (BM25 + local embeddings via RRF) — opt-in, bench-gated.
-
-**The practical implication.** Search with words close to how you
-recorded the learning, OR words that have a synonym pair in the
-dictionary. If you write a learning about *webhook signatures*, you
-can now search either *webhook signatures* OR *hook signatures* —
-the dictionary bridges those. For genuinely different vocabulary that
-isn't in the synonym table, use `knit_search_global_learnings` to widen
-the corpus, or call `knit_search_sessions` to pull from past narrative
-summaries that may use more terms.
-
-**Bench numbers (v0.16):** synthetic 88.0% top-1 / **100% recall@5**,
-learnings (real-prose) 86.7% top-1 / 96.7% recall@5. Both default ON;
-opt-out via `enableNgramFallback: false` + `enableSynonyms: false` for
-a strict lexical-only baseline.
+session summaries, and the cross-project pool, with two lexical-bridging
+layers on top: a **2-gram fallback** for typos and rare compounds, and
+**curated coding-domain synonym expansion** for common semantic-gap pairs.
+No vector embeddings, no remote inference, no API calls.
+
+The design is deliberate:
+
+- **Deterministic** — same query, same ranking, every time. No model drift.
+- **Fast** — sub-millisecond on typical project corpora (≤ 1K entries). No cold start.
+- **Local-first** — zero network calls; your memory never leaves the machine.
+- **Auditable** — every hit is explainable from term overlap plus the 50-pair synonym dictionary.
+
+**Capabilities.** Exact term + identifier match (`knit_classify_task`),
+rare-term emphasis (`PIPE_BUF`), multi-word ranking, tag filtering,
+cross-project diversification (max 2 per project), branch diversification on
+sessions (max 2 per branch), typo recovery via 2-gram fallback
+(`knit_clasify` → `knit_classify_task`), and synonym recovery (`hook` ↔
+`webhook`, `schema` ↔ `migration`, `auth` ↔ `authentication`, `cache` ↔
+`memo`, `deploy` ↔ `ship` ↔ `release`, … — see
+[`src/engine/retrieval/synonyms.ts`](src/engine/retrieval/synonyms.ts) for the
+full ~50-pair dictionary). Synonym matches score at 0.4× a direct hit, so exact
+matches always rank higher.
+
+**Benchmarks.** Synthetic 88.0% top-1 / **100% recall@5**; real-prose learnings
+86.7% top-1 / 96.7% recall@5. Both layers default on; set
+`enableNgramFallback: false` + `enableSynonyms: false` for a strict
+lexical-only baseline.
+
+**Roadmap.** A hybrid retriever (BM25 + local embeddings, fused via RRF) for
+paraphrase and abstraction-bridging is a v0.21+ candidate — opt-in,
+bench-gated, and local-first.
 
 ---
 
+## ✨ What's new in v0.21.0
+
+- **Onboarding (`knit_onboard`).** Paste the README prompt after connecting Knit, describe your project + how you want Knit to behave, and the agent persists your preferences (strictness, features, focus domains) and records the project intent — surfaced every session, on any MCP host.
+- **Dashboard actions.** The dashboard can now **Refresh** (re-index a project) and **Export all projects** (Obsidian vault), in addition to viewing. Actions run as child processes (non-blocking) and stay loopback-bound + Host/Origin-gated.
+- **56 tools** (Tier-1 37). Shipped after a second six-dimension audit (0 critical) and a real-life end-to-end run.
+
+## ✨ What's new in v0.20.0
+
+v0.20 makes Knit a **fully-ready, dashboard-first brain** — a consolidated
+release (internal phases v0.17–v0.20) shipped after a six-dimension deep-clean
+audit (0 critical findings).
+
+- **Brain freshness layer.** One shared primitive governs staleness across every
+  store, so the brain never serves data it can't vouch for: handoffs auto-clear
+  once resolved or stale, idle classifier signals decay, old cross-project
+  learnings drop from search, and a learning that names a now-deleted file is
+  flagged. Freshness drives prune/clear/flag only — never the bench-gated
+  retrieval ranking.
+- **Tool count you can explain.** `knit doctor` and `knit_list_features` print
+  the live active count *with the reason* (e.g. `46 of 56 = 37 always-on + 9
+  teams [≥3 domains] · …`), so a number that legitimately varies by project
+  shape stops looking like a bug. A drift test pins the docs to the registry.
+- **Stays on-protocol mid-session.** A throttled, escalating reminder rides the
+  MCP tool response when an agent drifts (e.g. records work before classifying)
+  — reaching every MCP host, not just Claude Code. Silence with
+  `knit_set_protocol_strictness({ level: "off" })`.
+- **Dashboard-first.** Run **`knit`** to open the brain; the agent/stdio path is
+  unchanged. The dashboard gains a Knowledge-index view and a `knit doctor`
+  webapp health check. (v0.21 adds Refresh + Export actions to the dashboard;
+  `knit setup` remains CLI-only.)
+- **Composes with your setup.** Scans Claude Code Skills
+  (`.claude/skills/<name>/SKILL.md`) alongside slash commands; positioning leads
+  with the integrated brain rather than competitor comparisons.
+
+Security/hygiene from the audit: the command/Skill scanner now guards size and
+rejects symlinks before reading (no OOM, no arbitrary-file reads into the brain).
+
+## ✨ What's new in v0.16.0
+
+v0.16 is the **semantic-lite release**. Two retrieval improvements that
+close the most common BM25 lexical gaps without an embedding model or
+external API call. Both default ON, both bench-pinned non-regressive.
+
+- **Curated synonym expansion.** Hand-curated dictionary of ~50
+  coding-domain synonym pairs (`webhook` ↔ `hook`, `schema` ↔
+  `migration`, `auth` ↔ `authentication`, `cache` ↔ `memo`, `deploy` ↔
+  `ship` ↔ `release`, etc.) in `src/engine/retrieval/synonyms.ts`. When
+  a query token has known synonyms, BM25 scores documents containing
+  those synonyms with a 0.4× discount weight (higher than the 2-gram
+  fallback's 0.25 because synonyms are conceptually closer than
+  near-spelling matches). Fires both as a fallback (term unmatched,
+  synonym matched) and a boost (term matched directly, synonym widens
+  reach).
+- **2-gram fallback default ON.** `enableNgramFallback` flipped from
+  default `false` → default `true`. v0.15 introduced this as opt-in to
+  avoid bench regression risk; v0.16 flips the default after both
+  benches verified strictly stable.
+- **FIFO-safe `handleIndexRequirements`.** Latent v0.12.1 hardening
+  bug: `openSync(O_RDONLY)` on a named pipe blocked indefinitely
+  before `fstat` could reject it. Now passes `O_NONBLOCK`; regular
+  files unaffected.
+
+Bench impact (v0.15 → v0.16): synthetic 86%/96% → **88%/100%**;
+learnings 83.3%/96.7% → **86.7%/96.7%**. The synthetic recall@5 hit
+100% because synonym expansion closed the "hook events authenticated"
+miss that BM25 alone couldn't bridge.
+
 ## ✨ What's new in v0.15.0
 
 v0.15 is the **deep-clean release**. A second six-dimension internal audit
@@ -221,6 +306,7 @@ return `{ status: 'protocol_required', next_action: '...' }` instead of
 proceeding — the agent reads the response, follows the breadcrumb, retries.
 This is the universality answer: same enforcement, transport layer instead
 of host layer. Default strictness stays `warn` so existing flows are unchanged.
+(v0.20 extends this with mid-session re-surfacing — see *What's new in v0.20.0* above.)
 
 ### ⚡ Agent-native slash-command auto-detection
 
@@ -278,7 +364,7 @@ A single command opens a local-first analytics surface at `http://127.0.0.1:7421
 
 **Real-time sync via SSE.** The server watches `~/.knit/` via `fs.watch`; any agent recording a learning anywhere updates the open dashboard within ~250ms. No polling.
 
-### 🔐 Security hardening (real, not theater)
+### 🔐 Security hardening
 
 The dashboard is a localhost HTTP server, which has real attack surface. v0.13 closes it:
 
@@ -316,30 +402,30 @@ The dashboard works regardless of which agent you use — it reads the brain fro
 | `knit_classify_task` response | ~500 tok | **~150 tok** | 70% |
 | `knit_load_session` response | ~3–5 KB | **~1.5 KB** | ~60% |
 
-Each surface gets a `healthy | warn | over-budget` verdict from `knit_brain_status.token_budget`. **Drift is a regression test, not a vibes claim.**
+Each surface gets a `healthy | warn | over-budget` verdict from `knit_brain_status.token_budget`, enforced by a regression test.
 
 ---
 
 ## 📊 The dashboard
 
-Run `knit ui` to open the local analytics surface. **Single command**, no other CLI needed for normal operation:
+Run **`knit`** to open the brain (the local analytics surface); `knit ui` is an explicit alias:
 
 ```bash
-knit ui
+knit
 # Knit Dashboard — http://127.0.0.1:7421
 # Reading from: /Users/<you>/.knit
 # Press Ctrl-C to stop.
-# (automatically opens your default browser)
+# (opens your default browser; visit the URL above if it does not)
 ```
 
 | Feature | What you see |
 |---|---|
 | **Bento home** | Big "Net tokens saved" hero card (dark), live recent activity (green "live" dot when SSE connected), memory hit-rate gauge, top projects by ROI as color-blocked cards |
 | **Brain graph** | Force-directed visualization of one project's learnings. Nodes sized by access count, colored by domain. Edges by Jaccard similarity over tags + domains. Click any node → side panel with the full lesson. Threshold slider live-recomputes the graph. |
-| **Per-project deep dive** | Hero card with verdict tone (cold/warming/compounding/strong), retrieval signals, classifications-by-tier breakdown, top domains heatmap, searchable learnings list |
-| **Health** | Install diagnostics — Node version, Knit version, ~/.knit permissions, MCP registration in `~/.claude.json` |
+| **Per-project deep dive** | Hero card with verdict tone (cold/warming/compounding/strong), retrieval signals, classifications-by-tier breakdown, top domains heatmap, searchable learnings list, Knowledge index, and **Refresh** (re-index this project) + **Export all projects** (Obsidian vault) actions |
+| **Health** | Install diagnostics — Node version, Knit version, ~/.knit permissions, per-agent MCP registration |
 
-**API endpoints** (all read-only, all 127.0.0.1 only):
+**API endpoints** (127.0.0.1 only, Host/Origin-gated):
 
 - `GET /api/version` — runtime version + update check + security metadata
 - `GET /api/brain/summary` — global counts
@@ -347,20 +433,28 @@ knit ui
 - `GET /api/projects` — project list
 - `GET /api/projects/:id/learnings` — full learning entries
 - `GET /api/projects/:id/metrics` — compounding ROI for one project
+- `GET /api/projects/:id/knowledge` — knowledge-index summary
 - `GET /api/projects/:id/graph` — force-directed node + edge data (Jaccard threshold tunable)
 - `GET /api/global/learnings` — cross-project pool
 - `GET /api/doctor` — install diagnostics
 - `GET /api/events` — Server-Sent Events stream for real-time sync
+- `POST /api/projects/:id/refresh` — re-index a project (source path from its meta; spawned as a child process)
+- `POST /api/export` — export all projects to a fixed `~/.knit/exports/` vault
 
 ---
 
-## 🛠️ 55 MCP Tools
+## 🛠️ 56 MCP Tools
 
-> **49 active by default** at first handshake. The remaining 6 are tier-gated:
-> teams (9 tools, auto-on when ≥3 domains detected), subagents (1 tool, auto-on
-> when `.claude/agents/` exists), and admin (3 tools, opt-in via
-> `knit_enable_feature("admin")`). Call `knit_list_features` to see what's
-> available and how to enable.
+> **37 always-on, up to 19 conditional, 56 total.** The active count varies by
+> project shape, so it isn't one fixed number — it's `37` plus whichever
+> conditional groups your project triggers: teams (9 tools, auto-on when ≥3
+> domains detected), diagnostics (6 tools, on during your first session),
+> subagents (1 tool, auto-on when `.claude/agents/` exists), and admin (3 tools,
+> opt-in via `knit_enable_feature("admin")`). That's why one machine shows 46
+> and another 44 — it reflects each project's shape. Run `knit doctor` (or call
+> `knit_list_features`) for your project's **live count and the reason for it**.
+> The groups below cover the main tools; `knit_list_features` is the
+> authoritative live list.
 
 <details open>
 <summary><strong>🕸️ Knowledge graph</strong> <em>(Tier 1, ~5ms)</em></summary>
@@ -406,8 +500,9 @@ knit ui
 | `knit_get_workflow` | Fetch protocol depth for one phase on demand. Sections: `overview, tier, phases, research, ideate, plan, execute, optimize, review, tdd, learn, handoff, ship, tools`. |
 | `knit_get_suggestions` | Adaptive warnings from past patterns in given domains. |
 | `knit_reflect` | Detect patterns across recorded learnings (per-project + global pool). Useful with ≥3 entries. |
-| `knit_setup_project` | Describe a non-code project (legal, marketing, research) to bootstrap domain teams. |
-| `knit_prune_sessions` | Prune `sessions.jsonl` by age (default 90 days). Atomic rewrite. |
+| `knit_onboard` | **v0.21.** One-time onboarding: captures the project + how the user wants Knit, persists preferences (strictness, features, focus domains), records the project intent. |
+| `knit_scan_agent_commands` | Scan each MCP host's slash-command + skill directories; surface user-defined commands so Knit composes with them. |
+| `knit_suggest_command` | Per-phase lookup against scanned commands; returns the agent-native command to invoke. |
 
 </details>
 
@@ -430,7 +525,7 @@ Runtime enforcement of the Knit protocol via PreToolUse and SessionStart hooks.
 |---|---|
 | `knit_brain_status` | Brain health + **token-budget** verdicts per surface + `update_available` notification + integrations summary. |
 | `knit_list_features` | Surfaces hidden tools and tells you how to enable them. The escape hatch. |
-| `knit_enable_feature` | Flip on a Tier-2/3 feature (`teams`, `subagents`, `admin`). Emits `notifications/tools/list_changed` — new tools appear without a Claude Code restart. |
+| `knit_enable_feature` | Flip on a Tier-2/3 feature (`teams`, `subagents`, `admin`). Emits `notifications/tools/list_changed` — new tools appear without an agent restart. |
 | `knit_disable_feature` | Symmetric to enable. |
 | `knit_scan_integrations` | Re-detect existing workflow frameworks (Ruflo, gstack, CodeTour, Conductor, other MCP servers, custom CLAUDE.md sections). |
 | `knit_compounding_metrics` | Quantifies *"Knit gets cheaper over time"* — sessions, cache hits, reuse-ratio %, estimated tokens saved. Verdict: `cold \| warming \| compounding \| strong`. |
@@ -468,7 +563,9 @@ Runtime enforcement of the Knit protocol via PreToolUse and SessionStart hooks.
 
 | Tool | What it does |
 |---|---|
-| `knit_setup_project` | Bootstrap domain teams for a non-code project. One-time. |
+| `knit_setup_project` | Bootstrap domain teams for a non-code project (legal, marketing, research). One-time. |
+| `knit_prune_sessions` | Prune `sessions.jsonl` by age (default 90 days). Atomic rewrite. Auto-prune handles this normally. |
+| `knit_reset_calibration` | Wipe per-project classifier calibration. Discards accumulated tuning. |
 
 </details>
 
@@ -579,7 +676,7 @@ knit install-agents --refresh    # re-fetch from network even if cached
   "token_budget": {
     "budgets": {
       "claude_md":            { "bytes": 2048,  "target_bytes": 6500,  "verdict": "healthy" },
-      "tool_registry":        { "bytes": 8400,  "target_bytes": 8500,  "verdict": "healthy", "active_tool_count": 31, "total_tool_count": 43 },
+      "tool_registry":        { "bytes": 8400,  "target_bytes": 8500,  "verdict": "healthy", "active_tool_count": 46, "total_tool_count": 56 },
       "instructions":         { "bytes": 2200,  "target_bytes": 2500,  "verdict": "healthy" },
       "per_session_overhead": { "bytes": 12648, "target_bytes": 17500, "verdict": "healthy" }
     },
@@ -594,7 +691,7 @@ knit install-agents --refresh    # re-fetch from network even if cached
   "update_available": {
     "current": "0.8.0",
     "latest":  "0.9.0",
-    "upgrade": "Restart Claude Code to spawn a fresh MCP — npx will auto-fetch the new version."
+    "upgrade": "Restart your agent to spawn a fresh MCP — npx will auto-fetch the new version."
   }
 }
 ```
@@ -605,10 +702,19 @@ Pair with `knit_compounding_metrics` for the value side of the ledger (sessions,
 
 ## 💻 CLI
 
+The surface is dashboard-first: `knit` opens the brain, `knit setup` performs
+one-time agent registration. The remaining commands are operational tooling for
+scripting and CI; their views are progressively moving into the dashboard.
+
 ```bash
-knit setup       # one time: add MCP to Claude settings
-knit status      # dashboard: sessions, learnings, hit rate, knowledge health
-knit refresh     # force rebuild knowledge brain
+knit                  # open the brain (the dashboard at http://127.0.0.1:7421)
+knit setup            # one-time: detect installed MCP-speaking agents and register Knit in each
+knit doctor           # install health check: version, per-agent MCP registration, webapp bundle, knowledgebase
+knit ui               # explicit alias for the dashboard (same as bare `knit`)
+knit status           # terminal snapshot: sessions, learnings, hit rate, knowledge-index health
+knit refresh          # rebuild the knowledge index from source
+knit install-agents   # install subagent definitions into <project>/.claude/agents/
+knit export <fmt>     # export learnings (supported targets: obsidian)
 ```
 
 Example `knit status`:
@@ -624,11 +730,11 @@ Knowledge Base
   Accessed:       12 (67% hit rate)
   False positives: 3
 
-Token budget (v0.9)
+Token budget (v0.16)
   CLAUDE.md:           2.0 KB  → healthy
-  Tool registry:       8.4 KB  → healthy (31 active / 43 total)
-  Instructions:        2.2 KB  → healthy
-  Per-session total:   12.6 KB → healthy
+  Tool registry:       ~13 KB  → warn (46 active / 56 total)
+  Instructions:        ~4 KB   → healthy
+  Per-session total:   ~20 KB  → healthy
 
 Compounding
   Sessions logged:     14
@@ -638,58 +744,32 @@ Compounding
 
 ---
 
-## 🆚 How it's different
-
-|  | gstack (skills) | ECC (agents) | Ruflo (orchestration) | **Knit** |
-|--|---|---|---|---|
-| **Bet** | Slash-command flows | Agent rules | 100+ agents in swarms | **One disciplined agent, compounding memory** |
-| **Setup** | Install skills per-project | Manual `.claude/` setup | `npx ruflo init` (heavy) | **`npx knit-mcp setup` (light)** |
-| **Memory** | jsonl files in-tree | Memory directory | Vector DB + 4-tier consolidation | **Local, searchable, vectorless BM25 + graph fusion** |
-| **Token cost** | Skills loaded into context | Rules loaded into context | 314 tools advertised | **~2 KB CLAUDE.md, tier-gated registry, budget guardrail** |
-| **Parallel work** | None | None | Multi-agent swarms + federation | **Team-scoped git worktrees** |
-| **Cloud dependency** | None | None | Cognitum.One (cloud backbone) | **None — fully local** |
-| **Self-measurement** | None | None | Cost-tracker plugin | **`knit_brain_status.token_budget` + `knit_compounding_metrics`** |
-| **Anti-hallucination** | None | None | None advertised | **`knit_verify_claim` + citation rule + pre/post import validation** |
-| **Non-code projects** | No | No | Limited | **Description-driven via `knit_setup_project`** |
-
-**The bet:** Ruflo for agent quantity (swarms, federation, plugins). Knit for **agent quality** (memory, classification, token discipline, hallucination defense). Different markets. The integration scanner detects Ruflo when installed and tailors instructions to defer routing to it — Knit operates as the memory + classification substrate underneath.
-
----
-
-## 🧭 Honest comparison vs memory libraries
-
-The mem0 / Letta / agentmemory comparison deserves a separate section because they're a different category — **memory-as-a-service libraries**, not MCP-native workflow layers. Reading their published benchmarks side-by-side:
+## 🧠 Why Knit
 
-| | mem0 | Letta (MemGPT) | agentmemory | **Knit** |
-|--|---|---|---|---|
-| **Published benchmark** | LOCOMO: 67–92% LLM-as-Judge; ~90% token reduction (1.7K vs 26K per conversation) | No head-to-head token-reduction number; "Letta Leaderboard" benchmarks *LLMs* on agentic memory, not Letta | LongMemEval-S: **95.2% R@5** with BM25+RRF+graph; 86.2% BM25-only | **Not yet measured.** Same architecture as agentmemory; no published number. |
-| **Retrieval architecture** | Vector + graph (Mem0g variant) | OS-inspired tiered memory (core/recall/archival) | BM25 + local vectors + KG fused via RRF (k=60) | BM25 + RRF + graph-traversal (fused via RRF k=60). Per-project + cross-project diversity caps. |
-| **Install shape** | SDK integration; managed cloud or self-hosted | SDK integration; self-hosted server | Python library | **`npx knit-mcp setup` → MCP server, zero glue.** Works with Claude Code / Cursor / Codex / any MCP host. |
-| **Workflow primitive** | None — pure memory | Agent-managed memory operations | None — pure retrieval | **4-tier classifier + plan-mode + protocol guard + parallel team worktrees.** |
-| **Self-calibration** | No | No | No | **Per-project classifier calibration** (v0.11): user FP feedback shifts thresholds; classifier gets less wrong over time. |
+Knit is a **project brain your agent plugs into** — a live code knowledge graph wired into ranked memory and a task classifier that routes work by impact. The pieces aren't sold separately; the value is the integration:
 
-### What's honest about this
+- **Graph-grounded recall** — memory ranked by what your change *structurally* touches (dependents, fanout), not just keyword overlap.
+- **Impact classifier** — every task is sized (Inquiry → Trivial → Standard → Complex) and complex work auto-enters plan mode. The brain decides *how carefully* to handle a change, not just what to recall.
+- **Self-calibrating** — `knit_record_false_positive` shifts the classifier's thresholds per project; it gets less wrong over time.
+- **Token accounting** — `knit_compounding_metrics` makes "cheaper over time" chartable per project.
+- **Parallel team worktrees** — multi-domain work fans out into isolated git worktrees so agents don't collide.
+- **Brain integrity** — a freshness layer keeps every datum trustworthy: stale handoffs auto-clear, idle classifier signals decay, deleted-file references get flagged.
+- **Fully local, zero-glue** — `npx knit-mcp setup` and it's a brain every MCP host (Claude Code, Cursor, Codex, Cline, Continue, Copilot) shares. No cloud, no SDK wiring.
 
-**Knit's measured retrieval on a 50-question synthetic harness (v0.11.2):**
+**"Why use Knit if my agent already has memory?"** Your agent's memory *stores notes*; Knit *decides* — it ranks recall by what your change structurally touches, classifies each task to set the right workflow depth, and tracks the cost over time. Graph-grounded routing, not a markdown notepad.
 
-| Metric | Knit (v0.11.2 synthetic) | agentmemory (LongMemEval-S, published) |
-|---|---|---|
-| Top-1 accuracy | **86.0%** | not published in that form |
-| Recall@5 | **96.0%** | **95.2%** |
-
-Run it yourself: `npm run bench`. Source: [`benchmarks/retrieval-synthetic.ts`](./benchmarks/retrieval-synthetic.ts).
+Knit also **composes with** whatever else you run: `knit_scan_integrations` detects existing workflow frameworks and slash commands and defers to them where they fit — Knit stays the memory + classification brain underneath.
 
-**These numbers are NOT apples-to-apples with agentmemory's.** Their benchmark is 1,500 questions from real long conversations; Knit's is 50 hand-authored questions on a 7KB synthetic corpus. The numbers are close because the architecture is similar (BM25 + RRF), not because we've proven parity at scale. **Real comparison requires running LongMemEval-S on Knit** — on the roadmap for v0.13.
+### Retrieval benchmarks
 
-**Knit isn't trying to be a better mem0.** It's a different product:
-- **MCP-native + zero-glue install** — mem0/Letta require SDK integration; Knit drops into any MCP host (Claude Code, Cursor, Codex) with one command.
-- **Workflow primitive** — the 4-tier classifier + plan-mode + protocol guard + team worktrees is what makes Knit a *command layer*, not a memory library.
-- **Per-project classifier calibration** (v0.11 slice 4) — `knit_record_false_positive` with a direction tag shifts thresholds over time. Nobody else does this; nobody else needs to, because they're memory libraries, not workflow routers.
-- **Measurable cheapness** — `knit_compounding_metrics` + `knit_get_metrics_history` make the "cheaper over time" claim *chartable per project*. mem0 publishes aggregate dataset numbers; Knit ships per-user instrumentation.
+Knit's retrieval is BM25 + reciprocal-rank fusion + graph traversal — **vectorless, deterministic, auditable**, no embedding model or cloud call. In-repo regression gates:
 
-### What's deferred
+| Harness | Top-1 | Recall@5 | Run it |
+|---|---|---|---|
+| 50-question synthetic | **88%** | **100%** | `npm run bench` |
+| 30-question narrative prose | **86.7%** | **96.7%** | `npm run bench:learnings` |
 
-LongMemEval-S R@5/R@10 + LOCOMO LLM-as-Judge runs are on the roadmap (v0.13+). Until they're published, treat any cross-system token-savings comparison as architectural-claim-only.
+These are focused in-repo regression gates that block a merge if retrieval degrades. A run on a standard long-memory benchmark and a hybrid BM25 + local-embeddings retriever are v0.21+ candidates.
 
 ---
 
@@ -697,11 +777,18 @@ LongMemEval-S R@5/R@10 + LOCOMO LLM-as-Judge runs are on the roadmap (v0.13+). U
 
 | Version | Headline |
 |---|---|
-| **v0.12.0** | **Picture Perfect: Structural Enforcement.** Diagnostic → enforcing. Budget verdict surfaces in the MCP `instructions` field at handshake (before any tool description is read). `knit_load_session` carries `budget_health` + `learnings_health` nudges. `engram doctor` exits non-zero on over-budget; `engram setup` runs doctor as final step. New PostToolUse hook warns immediately on over-budget CLAUDE.md edits (HOOKS_VERSION 11→12; auto-rolls to existing users). This repo dogfoods: hand-curated 16KB CLAUDE.md migrated to lean 3.8KB plus an internal long-form sidecar. New `npm run bench:tokens` measures real MCP-on vs MCP-off cost: 93% smaller per-recall call, 50% smaller per-classify, payback at 3 recall calls. 53 tools, 705 tests. |
+| **v0.21.0** | **Onboarding + dashboard actions.** `knit_onboard` captures the project + how the user wants Knit (preferences persisted, intent surfaced every session, host-agnostic). The dashboard gains **Refresh** + **Export all projects** actions (non-blocking child processes, Host/Origin-gated). New `GET /api/projects/:id/knowledge` + a `knit doctor` webapp check. Shipped after a second six-dimension audit (0 critical) + a real-life E2E. 56 tools. |
+| **v0.20.0** | **Brain integrity + clarity + dashboard-first.** A freshness layer keeps every datum trustworthy (handoffs auto-clear, idle classifier signals decay, deleted-file references get flagged). `knit doctor`/`knit_list_features` explain the live tool count. Mid-session protocol re-surfacing keeps agents on-protocol across every MCP host. **`knit`** opens the brain dashboard; a read-only Knowledge-index view + Skills composition land. Removed competitor comparisons for intrinsic positioning. Shipped after a six-dimension deep-clean audit (0 critical). 55 tools, 855 tests. |
+| **v0.16.0** | **Semantic-lite retrieval.** Curated coding-domain synonym dictionary (~50 pairs) closes the most common BM25 lexical gaps (`hook` ↔ `webhook`, `schema` ↔ `migration`, etc.) without an embedding model. 2-gram fallback for typos default ON after bench verification. Synthetic bench 88% top-1 / **100% recall@5** (was 96%); learnings 86.7% top-1 / 96.7% recall@5. Plus a FIFO-safe `O_NONBLOCK` fix to `handleIndexRequirements`. 55 tools, 818 tests. |
+| **v0.15.0** | **Deep-clean audit release.** Six-dimension second audit + atomic-write helper applied to 9+ sites including `~/.claude.json` (a torn write there used to brick Claude Code). SHA256 sidecars on agent-fetcher cache writes detect tampering and re-fetch. `qs` CVE pinned via `npm overrides` → 0 vulns. Opt-in BM25 2-gram fallback for typos. `pruneLearningsByAge` + schema-validated `readLearnings`. Webapp DoctorView shows per-agent rows. Update notice surfaces in MCP `instructions` field for all 6 agents. 55 tools, 805+ tests. |
+| **v0.14.1** | **Ship-readiness audit + atomicity hardening.** First six-dimension audit + 14 P1 fixes: `writeFileAtomic` helper across 9+ persistence paths; `handleSetupProject` redaction gap closed; `record_learning` substring dedup matches the description claim; soft-gate documented in instructions field; pre-publish leak gate. 55 tools. |
+| **v0.14.0** | **Universality release.** Single `knit setup` detects + writes to every installed MCP-speaking agent (Claude Code, Cursor, Codex CLI, Cline, Continue, GitHub Copilot via VS Code Agent mode). Server-side soft-gates as the cross-platform protocol enforcement layer for agents without hook lifecycles. Slash-command auto-detection via `knit_scan_agent_commands` + `knit_suggest_command`. 55 tools. |
+| **v0.13.0** | **Brain dashboard release.** `knit ui` opens a local-first analytics dashboard (Monetir-inspired bento, force-directed brain graph, real-time SSE sync, Host/Origin validation + CSP). Security hardening across every endpoint. Universal positioning copy across CLI + README. |
+| **v0.12.0** | **Picture Perfect: Structural Enforcement.** Diagnostic → enforcing. Budget verdict surfaces in the MCP `instructions` field at handshake (before any tool description is read). `knit_load_session` carries `budget_health` + `learnings_health` nudges. `knit doctor` exits non-zero on over-budget; `knit setup` runs doctor as final step. New PostToolUse hook warns immediately on over-budget CLAUDE.md edits (HOOKS_VERSION 11→12; auto-rolls to existing users). This repo dogfoods: hand-curated 16KB CLAUDE.md migrated to lean 3.8KB plus an internal long-form sidecar. New `npm run bench:tokens` measures real MCP-on vs MCP-off cost: 93% smaller per-recall call, 50% smaller per-classify, payback at 3 recall calls. 53 tools, 705 tests. |
 | **v0.11.4** | Dogfood audit · ran a full audit of Knit's own codebase using its own `knit_spawn_team_worktree` primitive (4 parallel teams: Core Logic, Infrastructure, UI, Quality Assurance). Fixes: HIGH `engram refresh` no longer clobbers user-curated CLAUDE.md (now uses `spliceKnitBlock` like `cache.ts`); `saveSource`/`loadSource` validate `sourceId`; `appendGlobalLearning` propagates write failures; `redactSecrets` applied to `label`/`tags`/`domains` across all persistence boundaries; 100KB response ceiling on `knit_generate_test_cases`; full v0.11 tool surface now documented in `workflow-protocol.ts` generator (was frozen at the v0.4 surface). Plus: 16 key tools reclassified with `[PROTOCOL]`/`[REVIEW]`/`[MEMORY]`/`[GRAPH]` prefixes so the LLM picks the right tool reliably. 53 tools, 687 tests. |
 | **v0.11.3** | Propagation patch · `update_available` flag now surfaces in `knit_load_session` response (≈100% session reach vs. brain_status' low reach) + startup stderr nag on stale versions. Helps FUTURE upgrades land faster; doesn't retroactively reach v0.10.x users. 53 tools, 665 tests. |
 | **v0.11.2** | Pre-publish polish · chunk cap (2000) + `errorResponse` envelope across handlers + CLAUDE.md generator surfaces v0.11 tools · new `engram doctor` install health-check CLI · upgrade-path smoke test caught + fixed a data-loss bug in cache.ts (Case B was wiping user permissions on upgrade) · 11 real exploit-payload integration tests prove C1/C2/H1 fixes hold · `npm run bench` ships a synthetic retrieval harness (50 Q&A) measuring 86% top-1 / 96% R@5. 53 tools, 664 tests. |
-| **v0.11.1** | Audit-driven hardening · 3 CRITICAL (source_id path traversal, post-edit tsc shell injection, live calibration bug) + 10 HIGH fixes from a 5-agent audit, implemented in 3 parallel `knit_spawn_team_worktree` teams. HOOKS_VERSION 11 (auto-upgrades existing users). New `knit_delete_requirements` tool. Honest comparison vs mem0/Letta added. 53 tools, 636 tests. |
+| **v0.11.1** | Audit-driven hardening · 3 CRITICAL (source_id path traversal, post-edit tsc shell injection, live calibration bug) + 10 HIGH fixes from a 5-agent audit, implemented in 3 parallel `knit_spawn_team_worktree` teams. HOOKS_VERSION 11 (auto-upgrades existing users). New `knit_delete_requirements` tool. 53 tools, 636 tests. |
 | **v0.11.0** | Verify Layer + auto-config foundation · mandatory `knit_verify_claim` REVIEW gate · post-edit diff verify + universal `tsc` check · drift detector · self-healing classifier (per-project calibration) · `knit_index_requirements` + `knit_generate_test_cases` (BM25 over long specs) · `knit_get_fingerprint` + `knit_infer_domains` + `knit_compose_template` (zero-config CLAUDE.md). 52 tools, 625 tests. |
 | **v0.10.0** | Token-economics release · risk × scope × change_kind classifier split · `context_budget_remaining` graceful degradation · per-project diversity cap on cross-project search · 11 new compounding-metrics fields + weekly snapshot persistence + `knit_get_metrics_history`. Makes "Knit makes Claude cheaper" a chartable number from day 1. |
 | **v0.9.0** | Hook-level enforcement · citation rule · `knit_verify_claim` · auto-search in classify · `suggested_reads` · `knit_get_learning` · `knit_consolidate_learnings`. |
@@ -733,17 +820,18 @@ git clone https://github.com/PDgit12/knit.git
 cd knit
 npm install
 npm run dev        # run CLI locally
-npm run test       # 492 tests
+npm run test       # 818 tests, ~8 s
 npm run typecheck  # TypeScript strict mode
-npm run build      # compile CLI + MCP server
+npm run bench      # retrieval bench: synthetic + learnings-shape
+npm run build      # compile CLI + MCP server + webapp
 ```
 
 ### Architecture
 
 ```
 knit (npm package)
-├── dist/cli.js                 # CLI: setup, status, refresh
-└── dist/mcp/server.js          # MCP server: 43 tools (tier-gated), auto-init
+├── dist/cli.js                 # CLI: setup, doctor, ui, status, refresh, install-agents, export
+└── dist/mcp/server.js          # MCP server: 56 tools (tier-gated), auto-init
 
 per-project, in ~/.knit/projects/<hash>/
 ├── knowledge.json              # import graph + exports + test map
@@ -758,7 +846,7 @@ per-project, in <project>/
 └── .claude/settings.local.json # per-machine hooks, knit-managed
 ```
 
-**Zero external dependencies for the knowledge brain.** 492 tests. Strict-mode TypeScript.
+**Zero external dependencies for the knowledge brain.** 818 tests, 0 `npm audit` vulnerabilities. Strict-mode TypeScript.
 
 ---