knit-mcp 0.12.0 → 0.16.1

package/README.md

@@ -3,50 +3,80 @@
   <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/tests-665%20passing-22c55e?style=for-the-badge" alt="tests" />
-  <img src="https://img.shields.io/badge/MCP%20tools-53-7c3aed?style=for-the-badge" alt="tools" />
+  <img src="https://img.shields.io/badge/MCP%20tools-55-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>
 
 <h1 align="center">🧶 knit</h1>
 
 <p align="center">
-  <strong>An intelligent command layer for Claude Code.</strong><br/>
-  Project-scoped memory · on-demand workflow · parallel team worktrees · honest token accounting.<br/>
-  <em>All in one MCP server.</em>
+  <strong>Universal MCP brain for agentic coding platforms.</strong><br/>
+  Project-scoped memory · on-demand workflow · parallel team worktrees · live analytics dashboard.<br/>
+  <em>Works with Claude Code, Cursor, Codex CLI, Cline, Continue, and GitHub Copilot (via VS Code Agent mode) — anything that speaks MCP.</em>
 </p>
 
 <p align="center">
   <a href="#-quick-start">Quick start</a> ·
   <a href="#-what-knit-is">What it is</a> ·
-  <a href="#-whats-new-in-v0110">v0.11</a> ·
-  <a href="#-52-mcp-tools">Tools</a> ·
-  <a href="#-how-its-different">Comparison</a> ·
-  <a href="#-honest-comparison-vs-memory-libraries">vs mem0/Letta</a>
+  <a href="#-how-search-works">How search works</a> ·
+  <a href="#-55-mcp-tools">Tools</a> ·
+  <a href="#-the-dashboard">Dashboard</a> ·
+  <a href="#-how-its-different">vs mem0/Letta</a>
 </p>
 
 ---
 
 ## 🧠 What knit is
 
-Knit makes Claude Code do the right thing automatically — because you can't predict how a user will phrase a request. It does three jobs at once:
+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:
 
 | | |
 |---|---|
-| 🧠 **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. |
-| 🪶 **Tokens** | `CLAUDE.md` is ~2 KB (project facts only). Protocol depth is fetched on demand via `knit_get_workflow(phase)`. Knit is **net-negative** on context cost. |
+| 🧠 **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). |
 
-It's a **single product**, not three. Every design choice has to win on memory + tokens + workflow together.
+**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.
 
 ---
 
 ## 🚀 Quick start
 
 ```bash
-npx knit-mcp@latest setup
+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)
 ```
 
-Adds the Knit MCP server to your Claude Code config (`~/.claude.json`). **No per-project setup.** Open Claude Code in any project — the first MCP tool call auto-initializes the brain, hooks, and per-project CLAUDE.md block.
+**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.
+
+### Adoption per agent
+
+v0.14: a single `knit setup` detects **every** installed MCP-speaking agent on
+your machine and writes Knit's config into each one's native format. No
+per-agent manual setup, no copy-pasted JSON.
+
+| Agent | Auto-detected by `knit setup` | Config format written | Hook support |
+|---|---|---|---|
+| Claude Code | ✅ `~/.claude.json` | JSON · `mcpServers` | ✅ PreToolUse / PostToolUse / Stop |
+| Cursor | ✅ `.cursor/mcp.json` | JSON · `mcpServers` | ⚠️ approval flow only |
+| Codex CLI | ✅ `~/.codex/config.toml` | **TOML** · `[mcp_servers.knit-brain]` | ⚠️ approval flow only |
+| Cline | ✅ `~/.cline/mcp.json` + `AGENTS.md` | JSON · `mcpServers` | ⚠️ approval flow only |
+| Continue | ✅ `.continue/mcpServers/knit-brain.yaml` | **YAML** per-server | ⚠️ approval flow only |
+| GitHub Copilot (VS Code Agent mode) | ✅ `.vscode/mcp.json` | JSON · `servers` (unique key) | ⚠️ approval flow only |
+| Any other MCP client | ✅ stdio works universally | per the client's docs | varies |
+
+> **"Hook support" caveat:** only Claude Code has lifecycle hooks (PreToolUse /
+> PostToolUse / Stop). For the other 5 agents Knit enforces the protocol via
+> the MCP `instructions` field (handshake primer) + **server-side soft-gates**
+> in tool responses — same effect as hooks, transport-layer instead of host-layer.
+> Opt into block-strictness enforcement with `knit_set_protocol_strictness({level: 'block'})`.
+
+> **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.
 
@@ -58,47 +88,269 @@ 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.
 
 ---
 
-## ✨ What's new in v0.9.0
+## 🔍 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.
 
-v0.9 closes the **enforcement story** — every honest limit from the v0.8 architecture got a structural fix.
+---
 
-### Anti-hallucination
+## ✨ 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
+graded the post-v0.14.1 codebase and surfaced the deferred items — defense-
+in-depth, retrieval honesty, UX parity, the trailing TODO debt. A single
+audit-cleanup branch closed them all, then six parallel agents re-graded
+the post-fix code to confirm nothing new slipped in.
+
+- **Security defense-in-depth.** Every `git` invocation in `worktrees.ts`
+  migrated to `execFileSync` with array args (no shell). Agent fetcher
+  cache writes are SHA256-verified via sidecars; tampered caches force
+  a fresh fetch with stderr alert; pre-v0.15 caches backfilled on first
+  read. `qs` CVE (GHSA-q8mj-m7cp-5q26) pinned via npm `overrides` —
+  `npm audit` now reports 0 vulnerabilities.
+- **Brain mechanics.** New `pruneLearningsByAge` parallels the sessions
+  pattern (atomic rewrite, conservatively preserves unparseable dates +
+  `#false-positive` entries). `readLearnings` schema-validates on read.
+  Opt-in BM25 2-gram fallback (`enableNgramFallback`, default off)
+  rescues typo-only queries without disturbing benchmarks.
+- **Retrieval honesty.** New `bench:learnings` regression bench against
+  30 real-learning-shape narrative entries — gates at top-1 ≥ 75% /
+  recall@5 ≥ 90% (currently 83.3% / 96.7%). Compounding-metrics response
+  now surfaces token-saved methodology with env-var overrides.
+- **UX & instructions.** Webapp DoctorView shows per-agent rows (parity
+  with CLI `knit doctor`). Workflow `EXECUTE` + `REVIEW` phases now embed
+  `knit_suggest_command` hooks so the agent defers to user slash-commands
+  for test/lint/ship/qa/review. `buildUpdateNotice` surfaces npm-update
+  banner in the MCP instructions field — Cursor/Codex/Cline/Continue/
+  Copilot users now see updates at handshake.
+
+## ✨ What's new in v0.14.0
+
+v0.14 is the **universality release**. Three coordinated shifts: every
+MCP-speaking agent works out of the box, Knit composes with the slash
+commands you already wrote, and enforcement works across all agents
+(not just Claude Code).
+
+### 🌍 Six agents, one install
+
+`knit setup` now detects every installed MCP-speaking agent and writes Knit's
+config into each one's native format — JSON for Claude Code / Cursor / Cline /
+VS Code (note: `servers` not `mcpServers` for VS Code), TOML for Codex CLI,
+YAML for Continue. If Codex CLI or Cline is detected, a marker-wrapped
+`AGENTS.md` is also written at project root (the cross-agent rules convention).
+`knit doctor` now reports per-agent registration status, so you can see
+which of your agents are wired up at a glance.
+
+### 🔧 Cross-platform protocol enforcement
+
+Only Claude Code has hook lifecycles (PreToolUse / PostToolUse / Stop). For
+the other 5 agents, v0.14 adds **server-side soft-gates** in MCP tool
+responses. When strictness is set to `block`, protocol-critical handlers
+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.
+
+### ⚡ Agent-native slash-command auto-detection
+
+Two new Tier-1 MCP tools:
+
+- `knit_scan_agent_commands` — scans `.claude/commands/`, `.cursor/rules/`,
+  `.clinerules/`, `~/.codex/prompts/`, `~/.continue/prompts/`, `.github/prompts/`
+  and surfaces every user-defined slash command + its description.
+- `knit_suggest_command({phase})` — given a protocol phase (test/lint/review/
+  ship), returns matching commands so the agent can invoke `/test` (or
+  whatever you wrote) via the host's native slash mechanism, instead of
+  describing the work in prose.
+
+Cached at `~/.knit/projects/<hash>/agent-commands.json` with a 1-hour TTL
+(~10ms re-scan when stale). Read-only filesystem ops; Knit never executes
+commands — the host agent invokes via its own mechanism.
+
+Dashboard exposes the scan results at **`#/commands`** with searchable
+per-agent listing.
+
+### 🛡️ Audit + hardening before publish
+
+v0.14 included a deep-dive internal audit of every dashboard
+endpoint, MCP handler, fs.watch race condition, and supply-chain dep. Five
+inline fixes landed in commit `e4e1793`:
+- `fs.watch` error handler now resets `watcher = null` so SSE recovers
+  cleanly after a watcher death (pre-fix, real-time sync silently stopped
+  until `knit ui` restart).
+- JSON + SSE responses gained `X-Content-Type-Options: nosniff`,
+  `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` (pre-fix only on
+  HTML).
+- `handleDefineTeam` + `handlePostTeamFindings` now call `redactSecrets` on
+  user-supplied team metadata + finding descriptions (pre-fix: raw write to
+  disk). 9 of 9 write handlers now redact uniformly.
+
+CBSE-style attack class verified PASS on every dashboard endpoint:
+Host-validation + Origin-validation + read-only contract + same-origin CSP
++ hex-only project-id regex. No malicious-page-can-read-your-brain vector.
+
+## ✨ What's new in v0.13.0
+
+v0.13 ships the **dashboard** — the visual surface on top of the brain. Plus security hardening and the universal positioning (works with every MCP-speaking agent).
+
+### 📊 Brain dashboard (`knit ui`)
+
+A single command opens a local-first analytics surface at `http://127.0.0.1:7421` — bento layout inspired by modern fintech dashboards, color-blocked cards, generous spacing, real-time sync.
+
+| View | What it shows |
+|---|---|
+| **Brain** (`#/`) | Hero card with net tokens saved across all projects, recent activity feed (live), memory hit-rate arc, top projects by ROI |
+| **Graph** (`#/graph`) | Project picker → **force-directed brain graph**: every learning is a node, edges by Jaccard similarity over shared tags + domains. Click any node for the full lesson. Threshold slider. |
+| **Cross-project** (`#/global`) | Cross-project learnings pool, filterable by source project |
+| **Per-project** (`#/p/:id`) | Searchable learnings list, retrieval signals, ROI deep dive (`#/p/:id/metrics`), graph (`#/p/:id/graph`) |
+| **Health** (`#/doctor`) | Install diagnostics: ~/.knit writable, MCP registered, version current |
 
-- 📎 **Citation rule in the MCP `instructions` field.** Every session's system prompt now tells the agent: *"when you state a fact about this codebase, cite the Knit tool result that verified it — e.g. (per `knit_query_imports`). If you can't cite, say 'unverified' explicitly."* Makes hallucinations visible at the **claim level**.
-- 🔍 **`knit_verify_claim` tool.** Single-call fact-check against the knowledge graph. Parses *"A imports B"*, *"X exports Y"*, *"A is tested by B"*, *"X exists"* and returns `verified | contradicted | unparseable` with evidence.
+**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.
 
-### Smarter retrieval
+### 🔐 Security hardening (real, not theater)
 
-- ⚡ **Auto-search inside `knit_classify_task`.** For `standard` / `complex` tier, classify now runs BM25 over (description + affected domains) automatically and embeds top-3 hits as `pre_emptive_learnings`. Closes the *"agent skipped `knit_search_learnings` before re-investigating"* gap with **zero extra calls**.
-- 📚 **`suggested_reads` from `knit_build_context`.** Curated list of files worth opening *before* editing — three signals: graph-importers (blast radius), graph-imports (likely needed), memory-mentions (files referenced by past learnings). Each entry carries `{ path, reason, via }`.
-- 🪜 **`knit_get_learning` — hierarchical retrieval.** Search returns headlines (summary + tags); the agent expands a specific learning by id only when needed. **Pay-per-detail.**
-- 🧮 **`knit_consolidate_learnings`.** Tag-Jaccard clustering of similar learnings → one pattern entry per cluster. Dry-run by default; `commit=true` persists with originals tagged `#consolidated` (preserved but deprioritized).
+The dashboard is a localhost HTTP server, which has real attack surface. v0.13 closes it:
 
-### Hook-level enforcement (`HOOKS_VERSION` 6 → 7)
+- **Host-header validation** — rejects requests whose `Host` isn't `127.0.0.1`/`localhost`. Blocks **DNS rebinding** (a malicious site you visit could resolve `evil.com` to 127.0.0.1 and trick your browser into reading the dashboard).
+- **Origin-header validation** — cross-origin requests get `403`. Same defense pattern as PostgreSQL, Redis, Docker daemon, the React dev server.
+- **Content-Security-Policy** on every HTML response — same-origin scripts only, no `'unsafe-eval'`, no external sources.
+- **X-Frame-Options: DENY**, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer.
+- **No mutation endpoints** in v0.13 (read-only dashboard). Setup wizard / refresh button stay deferred until proper CSRF protection lands.
 
-| Hook | What it does |
-|---|---|
-| **PreToolUse search-gate** | For `standard`/`complex` tasks, blocks Edit/Write (in `block` mode) or warns (default `warn`) when `knit_search_learnings` hasn't fired in the current turn. |
-| **PreToolUse content inspection** | Reads proposed Edit/Write content, parses local imports, warns on relative paths that don't resolve on disk — **catches hallucinated imports before they land**. |
-| **PostToolUse import validation** | After the file lands, re-parses imports and warns about unresolved relative paths — catches anything that slipped past the pre-check. |
-| **Stop-hook budget watch** | Cheap CLAUDE.md size check at session end; warns if it crosses the 12.5 KB over-budget threshold. Drift becomes visible even when the agent doesn't call `knit_brain_status`. |
+### 🌍 Universal positioning
+
+Knit is an MCP server. Anything that speaks MCP works:
 
-> **Upgrade note.** After `npx knit-mcp@latest setup`, **restart Claude Code**. The `instructions` field and tier-gated `tools/list` only flow into the system prompt at handshake. The `HOOKS_VERSION` bump auto-regenerates installed hooks on the next brain load — no manual `knit refresh` needed.
+- **Claude Code** — handshake via stdio, `instructions` field carries protocol primer
+- **Cursor** — register knit MCP server in settings
+- **Codex CLI** — `~/.codex/config.toml` mcpServers section
+- **Cline / Continue** — both speak MCP, same setup
+
+The dashboard works regardless of which agent you use — it reads the brain from disk.
+
+### 🪙 Token-economy lever
+
+`knit ui` notifies you when a new `knit-mcp` is available on npm — polls the registry every 5 minutes server-side, banner pops in the dashboard with the one-line `npm install -g knit-mcp@latest` command. No stale installs.
+
+> **Upgrade note.** After `npm install -g knit-mcp@latest`, **restart your agent**. The `instructions` field flows into the system prompt at handshake. The `HOOKS_VERSION` bump auto-regenerates installed hooks on the next brain load — no manual `knit refresh` needed.
 
 ---
 
@@ -115,7 +367,47 @@ Each surface gets a `healthy | warn | over-budget` verdict from `knit_brain_stat
 
 ---
 
-## 🛠️ 43 MCP Tools
+## 📊 The dashboard
+
+Run `knit ui` to open the local analytics surface. **Single command**, no other CLI needed for normal operation:
+
+```bash
+knit ui
+# Knit Dashboard — http://127.0.0.1:7421
+# Reading from: /Users/<you>/.knit
+# Press Ctrl-C to stop.
+# (automatically opens your default browser)
+```
+
+| 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` |
+
+**API endpoints** (all read-only, all 127.0.0.1 only):
+
+- `GET /api/version` — runtime version + update check + security metadata
+- `GET /api/brain/summary` — global counts
+- `GET /api/brain/aggregate` — cross-project ROI totals
+- `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/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
+
+---
+
+## 🛠️ 55 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.
 
 <details open>
 <summary><strong>🕸️ Knowledge graph</strong> <em>(Tier 1, ~5ms)</em></summary>
@@ -361,9 +653,13 @@ Pair with `knit_compounding_metrics` for the value side of the ledger (sessions,
 ## 💻 CLI
 
 ```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 setup            # one time: detects all 6 MCP-speaking agents and registers Knit in each
+knit doctor           # install health check: version, MCP registration per agent, knowledgebase
+knit ui               # launch the local Knit dashboard (http://127.0.0.1:7421)
+knit status           # text snapshot: sessions, learnings, hit rate, knowledge health
+knit refresh          # force rebuild knowledge brain
+knit install-agents   # install VoltAgent subagents into <project>/.claude/agents/
+knit export <fmt>     # export learnings (current targets: obsidian)
 ```
 
 Example `knit status`:
@@ -379,11 +675,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 (49 active / 55 total)
+  Instructions:        ~4 KB   → healthy
+  Per-session total:   ~20 KB  → healthy
 
 Compounding
   Sessions logged:     14
@@ -399,7 +695,7 @@ Compounding
 |--|---|---|---|---|
 | **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** |
+| **Memory** | jsonl files in-tree | Memory directory | Vector DB + 4-tier consolidation | **Local, searchable, vectorless BM25 + graph fusion + 2-gram fallback + 50-pair synonym dictionary** |
 | **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** |
@@ -434,7 +730,7 @@ The mem0 / Letta / agentmemory comparison deserves a separate section because th
 
 Run it yourself: `npm run bench`. Source: [`benchmarks/retrieval-synthetic.ts`](./benchmarks/retrieval-synthetic.ts).
 
-**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.
+**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 (a v0.20+ candidate alongside hybrid BM25 + local embeddings retrieval).
 
 **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.
@@ -452,7 +748,12 @@ 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 + `.claude/MARKETING.md` 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.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. |
@@ -488,17 +789,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: 55 tools (tier-gated), auto-init
 
 per-project, in ~/.knit/projects/<hash>/
 ├── knowledge.json              # import graph + exports + test map
@@ -513,7 +815,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.
 
 ---
 

package/dist/{cache-46OKHDRR.js → cache-7S5DFFQ6.js}

@@ -2,14 +2,15 @@ import {
   detectProjectRoot,
   getBrain,
   refreshBrain
-} from "./chunk-KKLAJLPO.js";
-import "./chunk-GATMQQK5.js";
-import "./chunk-WADRF26Z.js";
-import "./chunk-WKQHCLLO.js";
-import "./chunk-MOOVNMIN.js";
-import "./chunk-ST4X7LZT.js";
-import "./chunk-M3YZOJNW.js";
+} from "./chunk-JE4BZQUD.js";
+import "./chunk-QM4U75VE.js";
+import "./chunk-V54QPQ6K.js";
+import "./chunk-2FAS6CV4.js";
 import "./chunk-POXT5OYN.js";
+import "./chunk-WKQHCLLO.js";
+import "./chunk-FX3SVNHX.js";
+import "./chunk-YRLAWCYW.js";
+import "./chunk-BBQSWT4H.js";
 import "./chunk-VB2TIR6L.js";
 import "./chunk-7UFS67HP.js";
 import "./chunk-27TA2ZQZ.js";

package/dist/{chunk-WADRF26Z.js → chunk-2FAS6CV4.js}

@@ -313,7 +313,7 @@ function generateHooks(config, rootPath) {
               if (size <= TARGET) return;
               const kb = Math.round(size/1024*10)/10;
               const verdict = size > SLACK ? "over-budget" : "warn";
-              process.stderr.write("[knit] BUDGET " + verdict + ": " + f + " is now " + kb + "KB (target 6.5KB). Move long-form content to .claude/MARKETING.md or run \\\`engram refresh\\\`.\\n");
+              process.stderr.write("[knit] BUDGET " + verdict + ": " + f + " is now " + kb + "KB (target 6.5KB). Trim CLAUDE.md or run \\\`knit refresh\\\` to regenerate.\\n");
             } catch (e) { try { process.stderr.write('[knit] claude-md size watch hook failed: ' + (e && e.message ? e.message : e) + '\\n'); } catch {} }
           });
         `),

package/dist/{chunk-M3YZOJNW.js → chunk-BBQSWT4H.js}

@@ -1,14 +1,30 @@
 // src/engine/learnings.ts
-import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from "fs";
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, rmdirSync, renameSync } from "fs";
 import { dirname } from "path";
 function readLearnings(filePath) {
   if (!existsSync(filePath)) return [];
   const content = readFileSync(filePath, "utf-8");
   const entries = [];
   const sections = content.split(/^## /m).slice(1);
+  let parseFailures = 0;
+  let emptyShells = 0;
   for (const section of sections) {
     const entry = parseEntry(section);
-    if (entry) entries.push(entry);
+    if (!entry) {
+      parseFailures++;
+      continue;
+    }
+    if (!entry.summary.trim() || !entry.lesson.trim()) {
+      emptyShells++;
+      continue;
+    }
+    entries.push(entry);
+  }
+  if (parseFailures > 0 || emptyShells > 0) {
+    process.stderr.write(
+      `[knit] readLearnings(${filePath}): skipped ${parseFailures} unparseable, ${emptyShells} empty-shell entries
+`
+    );
   }
   return entries;
 }

package/dist/{chunk-MOOVNMIN.js → chunk-FX3SVNHX.js}

@@ -325,7 +325,7 @@ function buildSummary(allFiles, sourceFiles, importGraph, testMap, rootPath) {
       const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
       if (pkg.main) entryPoints.push(pkg.main);
       if (pkg.bin) {
-        const bins = typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin);
+        const bins = typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin).filter((v) => typeof v === "string");
         entryPoints.push(...bins);
       }
     }