@vpxa/kb 0.1.1

package/README.md

@@ -0,0 +1,1140 @@
+# @anvpx/kb
+
+Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents.
+
+## Features
+
+- **64 MCP tools** for AI agents to search, analyze, and manipulate codebases
+- **47 CLI commands** for shell-based interaction
+- **Local-first** — ONNX embeddings, LanceDB vector store, no cloud dependencies
+- **Three interfaces**: MCP (for agent IDEs), CLI (for terminal agents), and programmatic API
+
+## What This Is
+
+This is an **MCP (Model Context Protocol) server** that gives AI agents:
+
+1. **Hybrid search** — combines semantic vector search with full-text keyword search (BM25) using Reciprocal Rank Fusion (RRF) for best results. Supports `hybrid` (default), `semantic`, and `keyword` modes.
+2. **Persistent curated memory** — agents can `remember`, `update`, `read`, `list`, and `forget` knowledge entries that survive across sessions
+3. **Codebase analysis** — structural analysis, dependency graphs with confidence scoring, symbol extraction, pattern detection, and Mermaid diagram generation. Analysis results are auto-persisted into the vector store for future search.
+4. **Knowledge production** — automated analysis pipelines that produce structured baselines for the agent to synthesize and store
+5. **Next-step workflow hints** — every tool response includes contextual `_Next:` suggestions guiding the agent to logical follow-up actions
+6. **Tree-sitter code chunking** — AST-based chunking for TS/JS/Python/Go/Rust/Java preserves function/class boundaries for higher-quality code search
+7. **Knowledge graph** — auto-populated SQLite graph of modules, symbols, and import relationships with traversal, neighbor queries, and change impact tracking
+8. **Graph auto-population** — during indexing, a lightweight regex extractor builds the knowledge graph automatically from TS/JS source files (functions, classes, interfaces, types, imports)
+9. **Optimized reindex** — full reindex skips redundant hash checks, batches graph writes (flush every 50 files), and skips per-file graph deletes when bulk-cleared
+
+The KB auto-indexes configured source directories on startup, stores embeddings in a local LanceDB vector store, and exposes everything through 64 MCP tools, 47 CLI commands, and 2 resources.
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pnpm add -D @anvpx/kb
+
+# Initialize in your project
+npx kb init
+
+# Index your codebase
+npx kb reindex
+
+# Search
+npx kb search "authentication middleware"
+
+# Start MCP server for AI agents
+npx kb serve
+```
+
+## Tools by Category
+
+### Search & Discovery
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_search` | `kb search` | Hybrid vector + keyword search |
+| `kb_find` | `kb find` | Federated search (vector, FTS, glob, regex) |
+| `kb_symbol` | `kb symbol` | Resolve symbol definition, imports, references |
+| `kb_lookup` | `kb lookup` | Look up indexed chunks by file path |
+| `kb_trace` | `kb trace` | Forward/backward flow tracing |
+| `kb_find_examples` | `kb examples` | Find usage examples of a symbol |
+| `kb_scope_map` | `kb scope-map` | Generate task-scoped reading plan |
+| `kb_dead_symbols` | `kb dead-symbols` | Find unused exported symbols |
+| `kb_file_summary` | `kb summarize` | Structural file overview |
+
+### Code Analysis
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_analyze_structure` | `kb analyze structure` | Project structure analysis |
+| `kb_analyze_dependencies` | `kb analyze deps` | Dependency graph |
+| `kb_analyze_symbols` | `kb analyze symbols` | Symbol extraction |
+| `kb_analyze_patterns` | `kb analyze patterns` | Code pattern detection |
+| `kb_analyze_entry_points` | `kb analyze entry-points` | Entry point discovery |
+| `kb_analyze_diagram` | `kb analyze diagram` | Mermaid diagram generation |
+| `kb_blast_radius` | `kb analyze blast-radius` | Change impact analysis |
+
+### Context Management
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_compact` | `kb compact` | Compress text to relevant sections |
+| `kb_workset` | `kb workset` | Named file set management |
+| `kb_stash` | `kb stash` | Named key-value store |
+| `kb_checkpoint` | `kb checkpoint` | Session checkpoint save/restore |
+| `kb_parse_output` | `kb parse-output` | Parse build tool output (tsc, vitest, biome) |
+
+### FORGE & Context Compression
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_forge_ground` | — | Complete FORGE Ground phase in one call (chains classify→scope→summarize→constraints→evidence) |
+| `kb_forge_classify` | — | Classify FORGE tier (Floor/Standard/Critical) from files and task |
+| `kb_evidence_map` | — | Track critical-path claims as V/A/U with receipts + deterministic Gate |
+| `kb_digest` | — | Compress multiple text sources into token-budgeted digest |
+| `kb_stratum_card` | — | Generate STRATUM T1/T2 context cards (10-100x token reduction) |
+
+### Code Manipulation
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_rename` | `kb rename` | Smart symbol rename across files |
+| `kb_codemod` | `kb codemod` | Regex-based code transformations |
+| `kb_diff_parse` | `kb diff` | Parse unified diff into structured changes |
+| `kb_data_transform` | `kb transform` | JQ-like JSON transformations |
+
+### Execution & Validation
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_eval` | `kb eval` | Sandboxed JavaScript/TypeScript execution |
+| `kb_check` | `kb check` | Incremental typecheck + lint |
+| `kb_test_run` | `kb test` | Run tests with structured results |
+| `kb_batch` | `kb batch` | Parallel operation execution |
+
+### Knowledge Management
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_remember` | `kb remember` | Store curated knowledge |
+| `kb_update` | `kb update` | Update existing entries |
+| `kb_forget` | `kb forget` | Remove entries |
+| `kb_read` | `kb read` | Read entry content |
+| `kb_list` | `kb list` | List entries |
+| `kb_produce_knowledge` | — | Auto-generate knowledge from analysis |
+
+### Git & Environment
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_git_context` | `kb git` | Branch, status, recent commits |
+| `kb_process` | `kb proc` | Process supervisor |
+| `kb_watch` | `kb watch` | Filesystem watcher |
+| `kb_delegate` | `kb delegate` | Delegate subtask to local Ollama model |
+
+### Web & Network
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_web_fetch` | — | Fetch web page → markdown/raw/links/outline |
+| `kb_web_search` | — | Search the web via DuckDuckGo (no API key) |
+| `kb_http` | — | Make HTTP requests for API testing/debugging |
+
+### Developer Utilities
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_regex_test` | — | Test regex patterns (match/replace/split modes) |
+| `kb_encode` | — | Base64, URL, SHA-256, MD5, hex, JWT decode |
+| `kb_measure` | — | Code complexity and line-count metrics |
+| `kb_changelog` | — | Generate changelog from git history |
+| `kb_schema_validate` | — | Validate JSON data against JSON Schema |
+| `kb_snippet` | — | Persistent code snippet/template storage |
+| `kb_env` | — | System and runtime environment info |
+| `kb_time` | — | Date parsing, timezone conversion, duration math |
+
+### Verified Lanes
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_lane` (create) | `kb lane create` | Create isolated file copy for parallel exploration |
+| `kb_lane` (list) | `kb lane list` | List active lanes |
+| `kb_lane` (status) | `kb lane status` | Show modified/added/deleted files in a lane |
+| `kb_lane` (diff) | `kb lane diff` | Generate diff between lane and originals |
+| `kb_lane` (merge) | `kb lane merge` | Merge lane files back to originals |
+| `kb_lane` (discard) | `kb lane discard` | Discard a lane entirely |
+
+### System
+| Tool | CLI | Description |
+|------|-----|-------------|
+| `kb_status` | `kb status` | Index statistics |
+| `kb_reindex` | `kb reindex` | Rebuild index |
+| `kb_health` | `kb health` | Project health checks (package.json, tsconfig, lockfile, etc.) |
+| `kb_queue` | `kb queue` | Task queue for sequential agent operations |
+| `kb_graph` | `kb graph` | Query and manage the knowledge graph (8 actions: find_nodes, find_edges, neighbors, traverse, stats, add, delete, clear) |
+| `kb_onboard` | `kb onboard` | First-time codebase onboarding — runs all analysis tools in one command, auto-persists results |
+| `kb_replay_list` | `kb replay` | View audit trail of tool invocations |
+| `kb_replay_clear` | `kb replay-clear` | Clear the replay audit trail |
+
+### TUI Dashboard
+
+```bash
+kb tui          # Launch interactive Ink terminal dashboard
+```
+
+The TUI is a human monitoring dashboard with 4 panels: Status, Search, Curated, and Activity Log. It shows real-time tool activity via the replay audit trail, letting you observe what an AI agent is doing with the KB.
+
+## MCP Integration
+
+After `kb init`, your `.vscode/mcp.json` is configured automatically:
+
+```json
+{
+  "servers": {
+    "knowledge-base": {
+      "command": "npx",
+      "args": ["kb", "serve"]
+    }
+  }
+}
+```
+
+## CLI Usage
+
+```bash
+kb <command> [options]
+
+# Search & Discovery
+kb search <query> [--limit N] [--mode hybrid|semantic|keyword]
+kb find [query] [--glob pattern] [--pattern regex] [--limit N]
+kb symbol <name>
+kb scope-map <task> [--max-files N]
+kb trace <symbol> [--direction forward|backward|both] [--depth N]
+kb examples <query> [--limit N]
+kb summarize <file>
+kb dead-symbols [--limit N]
+
+# Analysis
+kb analyze <type> <path>
+kb lookup <path>
+
+# Context
+kb compact <query> [--max-chars N]
+kb workset <action> [name] [--files f1,f2]
+kb stash <action> [key] [value]
+kb checkpoint <action> [label]
+kb parse-output [--tool tsc|vitest|biome|git-status]
+
+# Code Manipulation
+kb rename <old> <new> <path> [--dry-run]
+kb codemod <path> --rules <file.json> [--dry-run]
+kb diff
+kb transform <expression>
+
+# Execution
+kb eval <code> [--lang js|ts] [--timeout N]
+kb test [files...] [--grep pattern]
+kb check [--skip-types] [--skip-lint]
+kb batch
+
+# Knowledge
+kb remember <title> --category <cat> [--tags t1,t2]
+kb forget <path> --reason <reason>
+kb read <path>
+kb list [--category cat] [--tag tag]
+kb update <path> --reason <reason>
+
+# Git & Environment
+kb git [--commits N] [--diff]
+kb proc <action> [id] [--command cmd]
+kb watch <action> [--path dir]
+
+# Verified Lanes
+kb lane create <name> --files file1.ts,file2.ts
+kb lane list
+kb lane status <name>
+kb lane diff <name>
+kb lane merge <name>
+kb lane discard <name>
+
+# Graph
+kb graph stats
+kb graph find-nodes [--type module|function|class] [--query pattern]
+kb graph find-edges [--type imports|defines] [--source path]
+kb graph neighbors <nodeId> [--direction in|out|both]
+kb graph traverse <startId> [--direction forward|backward] [--depth N]
+
+# System
+kb status
+kb reindex [--full]
+kb onboard <path> [--mode analyze|generate]
+kb serve [--transport stdio|http] [--port N]
+kb init [--force]
+```
+
+## Configuration
+
+`kb.config.json`:
+
+```json
+{
+  "sources": [{ "path": ".", "name": "project" }],
+  "embedding": {
+    "model": "Xenova/mxbai-embed-large-v1",
+    "dimensions": 1024
+  },
+  "store": {
+    "backend": "lancedb",
+    "path": ".kb-data/store"
+  },
+  "curated": {
+    "path": "curated"
+  }
+}
+```
+
+## Architecture
+
+```text
+@anvpx/kb
+├── packages/
+│   ├── core/         — types, config, logger, constants
+│   ├── store/        — LanceDB vector store
+│   ├── embeddings/   — ONNX local embeddings
+│   ├── chunker/      — tree-sitter + regex code chunking
+│   ├── indexer/      — incremental file indexer
+│   ├── analyzers/    — blast-radius, deps, symbols, patterns, diagrams
+│   ├── tools/        — 49 tool modules (64 MCP tools)
+│   ├── server/       — MCP protocol server
+│   └── cli/          — command-line interface
+├── bin/kb.mjs        — CLI entry point
+└── skills/           — LLM skill files
+```
+
+## License
+
+MIT
+
+### Development
+
+```bash
+pnpm install       # Install dependencies
+pnpm build         # Build all packages
+pnpm test          # Run tests (Vitest)
+pnpm lint          # Lint (Biome)
+```
+
+---
+
+## Detailed MCP Tools Reference
+
+### Search & Retrieval
+
+#### `kb_search` — Hybrid search across the knowledge base
+
+Find relevant code, docs, patterns, and curated knowledge using hybrid (vector + keyword), semantic, or keyword-only search.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | **yes** | — | Natural language search query |
+| `limit` | number (1–20) | no | 5 | Maximum results to return |
+| `search_mode` | enum | no | `hybrid` | Search strategy: `hybrid` (vector + FTS + RRF fusion), `semantic` (vector only), `keyword` (FTS only) |
+| `content_type` | enum | no | — | Filter: `markdown`, `code-typescript`, `code-javascript`, `code-python`, `config-json`, `config-yaml`, `config-toml`, `config-dotenv`, `infrastructure`, `documentation`, `test`, `script`, `curated-knowledge`, `produced-knowledge`, `other` |
+| `origin` | enum | no | — | Filter: `indexed` (from files), `curated` (agent memory), `produced` (auto-generated) |
+| `category` | string | no | — | Filter by curated category (e.g., `decisions`, `patterns`) |
+| `tags` | string[] | no | — | Filter by tags (OR matching) |
+| `min_score` | number (0–1) | no | 0.25 | Minimum similarity score threshold |
+
+**Returns**: Ranked results with score, source path, content type, line range, heading path, origin, tags, and full content text. Each response includes a `_Next:` hint suggesting logical follow-up tools.
+
+**Search modes**:
+- **`hybrid`** (default) — Runs vector similarity and full-text keyword search in parallel, then merges rankings using Reciprocal Rank Fusion (k=60). Best for most queries.
+- **`semantic`** — Pure vector cosine similarity. Best when searching by meaning/concept rather than exact terms.
+- **`keyword`** — Full-text search using LanceDB's built-in FTS index. Best when searching for exact identifiers, function names, or specific strings.
+
+**Best practices for query**:
+- Use natural language describing what you're looking for: `"how does the notification dispatcher route messages"` 
+- Include domain terms that would appear in the code: `"DynamoDB single-table GSI pattern for notifications"`
+- Use `search_mode: "keyword"` for exact function/class names: `"reciprocalRankFusion"`
+- Use `search_mode: "semantic"` for conceptual queries: `"retry strategy with exponential backoff"`
+- For curated knowledge, combine with `origin: "curated"`: `query: "architecture decision", origin: "curated"`
+
+#### `kb_lookup` — Get all chunks for a specific file
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | **yes** | Relative file path (e.g., `src/index.ts`) |
+
+**Returns**: All chunks for that file, sorted by position, with line ranges and content.
+
+#### `kb_status` — View index statistics
+
+No parameters. Returns total records, total files, content type breakdown, last indexed timestamp, and list of indexed files.
+
+### Curated Knowledge (Persistent Memory)
+
+These tools give the agent **persistent, version-tracked memory** that survives across sessions. Knowledge is stored as markdown files with YAML frontmatter in the `curated/` directory and simultaneously indexed into the vector store for semantic search.
+
+#### `kb_remember` — Store new knowledge
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string (3–120 chars) | **yes** | Short descriptive title |
+| `content` | string (≥10 chars) | **yes** | Markdown content to store |
+| `category` | string (kebab-case) | **yes** | Category slug: `decisions`, `patterns`, `conventions`, `troubleshooting`, or any custom kebab-case name |
+| `tags` | string[] | no | Tags for filtering |
+
+**What to remember**: Architecture decisions, coding conventions, recurring patterns, API contracts, deployment procedures, debugging solutions, team agreements, review findings.
+
+#### `kb_update` — Update existing knowledge
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | **yes** | Path from `kb_list` (e.g., `decisions/use-lancedb.md`) |
+| `content` | string (≥10 chars) | **yes** | New markdown content (replaces existing) |
+| `reason` | string (≥3 chars) | **yes** | Why this update is being made (recorded in changelog) |
+
+Increments version number and appends to the entry's changelog.
+
+#### `kb_read` — Read a curated entry
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | **yes** | Path from `kb_list` |
+
+**Returns**: Full metadata (title, version, tags, created, updated) and content.
+
+#### `kb_list` — List curated entries
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `category` | string | no | Filter by category |
+| `tag` | string | no | Filter by tag |
+
+**Returns**: All entries with title, version, tags, path, and 80-char content preview.
+
+#### `kb_forget` — Remove a curated entry
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | **yes** | Path from `kb_list` |
+| `reason` | string (≥3 chars) | **yes** | Why this entry is being removed |
+
+Deletes from disk and vector store.
+
+### Indexing
+
+#### `kb_reindex` — Trigger re-indexing
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `full` | boolean | no | false | If true, force full re-index ignoring file hashes |
+
+Incremental mode (default) only re-indexes files whose content hash has changed. Full mode drops the table and rebuilds from scratch.
+
+### Codebase Analysis
+
+#### `kb_produce_knowledge` — Automated analysis + synthesis instructions
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `scope` | string | no | `.` (root) | Root path to analyze |
+| `aspects` | enum[] | no | `["all"]` | `all`, `structure`, `dependencies`, `symbols`, `patterns`, `entry-points`, `diagrams` |
+
+Runs deterministic analyzers, then returns structured instructions for the agent to synthesize and store findings using `kb_remember`.
+
+#### `kb_analyze_structure` — File/directory tree with language stats
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `path` | string | **yes** | — | Root path to analyze |
+| `max_depth` | number (1–10) | no | 6 | Maximum directory depth |
+| `format` | enum | no | `markdown` | `json` or `markdown` |
+
+#### `kb_analyze_dependencies` — Import/require dependency graph (with confidence)
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `path` | string | **yes** | — | Root path |
+| `format` | enum | no | `markdown` | `json`, `markdown`, or `mermaid` |
+
+Dependency results include a **confidence** level per import: `high` (ES static imports), `medium` (dynamic imports, require()), `low` (inferred). The markdown format shows a Confidence column in dependency tables.
+
+#### `kb_analyze_symbols` — Exported & local symbols
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `path` | string | **yes** | — | Root path |
+| `filter` | string | no | — | Filter symbols by name substring |
+| `format` | enum | no | `markdown` | `json` or `markdown` |
+
+#### `kb_analyze_patterns` — Detect architectural patterns & frameworks
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | **yes** | Root path |
+
+#### `kb_analyze_entry_points` — Find Lambda handlers, CLI bins, server starts
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | **yes** | Root path |
+
+#### `kb_analyze_diagram` — Generate Mermaid architecture/dependency diagrams
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `path` | string | **yes** | — | Root path |
+| `diagram_type` | enum | no | `architecture` | `architecture` or `dependencies` |
+
+### Context Management
+
+#### `kb_compact` — Compress text to query-relevant sections
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `text` | string | **yes** | — | The text to compress |
+| `query` | string | **yes** | — | Focus query — what are you trying to understand? |
+| `max_chars` | number (100–50000) | no | `3000` | Target output size in characters |
+| `segmentation` | enum | no | `paragraph` | How to split: `paragraph`, `sentence`, `line` |
+
+Uses embedding similarity (no LLM needed) to keep only the segments most relevant to the query. Returns compression stats (original → compressed chars, ratio, segments kept/total) and the compressed text.
+
+#### `kb_workset` — Manage named file sets
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `action` | enum | **yes** | — | `save`, `get`, `list`, `delete`, `add`, `remove` |
+| `name` | string | varies | — | Workset name (required for all except `list`) |
+| `files` | string[] | varies | — | File paths (required for `save`, `add`, `remove`) |
+| `description` | string | no | — | Description (for `save`) |
+
+Worksets persist across sessions in `.kb-state/worksets.json`.
+
+#### `kb_stash` — Persist named key-value pairs
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `action` | enum | **yes** | — | `set`, `get`, `list`, `delete`, `clear` |
+| `key` | string | varies | — | Entry key (for `set`, `get`, `delete`) |
+| `value` | string | varies | — | String or JSON value (for `set`) |
+
+Stores intermediate results between tool calls in `.kb-state/stash.json`.
+
+#### `kb_checkpoint` — Save/restore session checkpoints
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `action` | enum | **yes** | — | `save`, `load`, `list`, `latest` |
+| `label` | string | varies | — | Checkpoint label (for `save`), or checkpoint ID (for `load`) |
+| `data` | string | varies | — | JSON object string (for `save`) |
+| `notes` | string | no | — | Optional notes (for `save`) |
+
+Lightweight checkpoints stored in `.kb-state/checkpoints/` for cross-session continuity.
+
+#### `kb_parse_output` — Parse build tool output
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `output` | string | **yes** | — | Raw output text from a build tool |
+| `tool` | enum | no | auto-detect | `tsc`, `vitest`, `biome`, `git-status` |
+
+Returns JSON structured parse result with errors, warnings, and file references. Auto-detects the tool format when not specified.
+
+### FORGE & Context Compression
+
+#### `kb_forge_ground` — Complete FORGE Ground phase
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `task` | string | **yes** | — | Task description |
+| `files` | string[] | **yes** | — | Target files being modified (absolute paths) |
+| `root_path` | string | **yes** | — | Root path of the codebase |
+| `max_constraints` | number (0–10) | no | `3` | Max constraint entries to load from KB |
+| `force_tier` | enum | no | auto | Force tier: `floor`, `standard`, `critical` (skips auto-classification) |
+| `task_id` | string | no | auto-generated | Custom task ID for evidence map |
+
+Chains: tier classification → scope map → file summaries → constraint loading → typed unknown seeds → evidence map creation. Replaces 5-15 manual tool calls. Floor tasks get a minimal shortcut (no scope map / constraints / evidence map).
+
+#### `kb_forge_classify` — Classify FORGE tier
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `files` | string[] | **yes** | Files being modified (paths) |
+| `task` | string | **yes** | Task description |
+| `root_path` | string | **yes** | Root path of the codebase |
+
+Checks blast radius, cross-package boundaries, schema/contract patterns, and security signals. Returns tier, triggers, typed unknown seeds, packages crossed, and ceremony guidance.
+
+#### `kb_evidence_map` — FORGE Evidence Map CRUD + Gate
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `action` | enum | **yes** | — | `create`, `add`, `update`, `get`, `gate`, `list`, `delete` |
+| `task_id` | string | varies | — | Task identifier (all except `list`) |
+| `tier` | enum | varies | — | FORGE tier (for `create`): `floor`, `standard`, `critical` |
+| `claim` | string | varies | — | Critical-path claim text (for `add`) |
+| `status` | enum | varies | — | `V` (Verified), `A` (Assumed), `U` (Unresolved) |
+| `receipt` | string | no | — | Evidence: tool→ref for V, reasoning for A, attempts for U |
+| `id` | number | varies | — | Entry ID (for `update`) |
+| `critical_path` | boolean | no | `true` | Whether claim is on the critical path |
+| `unknown_type` | enum | no | — | `contract`, `convention`, `freshness`, `runtime`, `data-flow`, `impact` |
+| `retry_count` | number | no | `0` | Retry count for gate evaluation |
+
+Gate decision logic: HARD_BLOCK (contract U on critical path) → HOLD (non-contract U, retry 0) → FORCED_DELIVERY (non-contract U, retry ≥ 1) → YIELD. Persists in `.kb-state/evidence-maps.json`.
+
+#### `kb_digest` — Token-budgeted multi-source compression
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sources` | object[] | **yes** | — | Sources: `{ id, text, weight }` (weight = priority, higher = more budget) |
+| `query` | string | **yes** | — | Focus query — what matters for the next step? |
+| `max_chars` | number (100–50000) | no | `4000` | Target budget in characters |
+| `pin_fields` | string[] | no | status, files, decisions, blockers, next | Key fields to always extract |
+| `segmentation` | enum | no | `paragraph` | `paragraph`, `sentence`, `line` |
+
+Jointly ranks across all sources using embedding similarity. Pins structured fields (key:value patterns) and allocates remaining budget proportionally by weight. Returns compressed text + extracted fields + per-source stats.
+
+#### `kb_stratum_card` — STRATUM context cards
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `files` | string[] | **yes** | — | Absolute file paths to generate cards for |
+| `query` | string | **yes** | — | Current task query — guides relevance scoring |
+| `tier` | enum | no | `T1` | `T1` = structural only (~100 tok/file), `T2` = T1 + compressed content (~300 tok/file) |
+| `max_content_chars` | number (100–5000) | no | `800` | For T2: max chars for compressed content section |
+
+T1 cards contain: ROLE, DEPS, EXPORTS, UNKNOWNS, RISK. T2 adds a CONTEXT section with query-compressed content. Uses `kb_file_summary` + embedder similarity. No generative LLM needed.
+
+### Search & Discovery
+
+#### `kb_find` — Federated multi-strategy search
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | no | — | Semantic/keyword search query |
+| `glob` | string | no | — | File glob pattern |
+| `pattern` | string | no | — | Regex pattern to match in content |
+| `limit` | number (1–50) | no | `10` | Max results |
+| `content_type` | string | no | — | Filter by content type |
+
+Combines vector similarity, keyword (FTS), file glob, and regex strategies. Deduplicates and returns unified results with source, path, line range, score %, and preview.
+
+#### `kb_symbol` — Resolve a symbol across the codebase
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `name` | string | **yes** | — | Symbol name (function, class, type, etc.) |
+| `limit` | number (1–50) | no | `20` | Max results per category |
+
+Finds where a symbol is defined, who imports it, and where it is referenced. Works on TypeScript and JavaScript.
+
+#### `kb_scope_map` — Generate a task-scoped reading plan
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `task` | string | **yes** | — | Description of the task to scope |
+| `max_files` | number (1–50) | no | `15` | Maximum files to include |
+| `content_type` | string | no | — | Filter by content type |
+
+Returns a ranked file list with estimated token counts, relevance %, focus line ranges, and a suggested reading order.
+
+#### `kb_trace` — Trace data flow through imports/references
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `start` | string | **yes** | — | Starting point — symbol name or `file:line` reference |
+| `direction` | enum | **yes** | — | `forward`, `backward`, `both` |
+| `max_depth` | number (1–10) | no | `3` | Maximum trace depth |
+
+Follows imports, call sites, and references to build a relationship graph from a starting symbol or file location.
+
+#### `kb_find_examples` — Find real usage examples
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | **yes** | — | Symbol or pattern to find examples of |
+| `limit` | number (1–20) | no | `5` | Maximum examples to return |
+| `content_type` | string | no | — | Filter by content type |
+
+Returns usage examples with file paths and code snippets from the indexed codebase.
+
+#### `kb_dead_symbols` — Find unused exported symbols
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `limit` | number (1–500) | no | `100` | Maximum exported symbols to scan |
+
+Finds exported symbols that are never imported or re-exported anywhere in the project.
+
+#### `kb_file_summary` — Structural summary of a source file
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | **yes** | Absolute path to the file |
+
+Returns imports, exports, functions, classes, interfaces, and types found in the file.
+
+### Code Manipulation
+
+#### `kb_rename` — Rename a symbol across files
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `old_name` | string | **yes** | — | Existing symbol name |
+| `new_name` | string | **yes** | — | New symbol name |
+| `root_path` | string | **yes** | — | Root directory to search within |
+| `extensions` | string[] | no | — | File extensions to include (e.g., `.ts`, `.tsx`) |
+| `dry_run` | boolean | no | `true` | Preview changes without writing files |
+
+Uses whole-word regex matching for exports, imports, and general usage references. Defaults to dry run.
+
+#### `kb_codemod` — Apply regex-based codemod rules
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `root_path` | string | **yes** | — | Root directory to transform within |
+| `rules` | object[] (min 1) | **yes** | — | Codemod rules: `description`, `pattern` (regex), `replacement` (with capture groups) |
+| `dry_run` | boolean | no | `true` | Preview changes without writing files |
+
+Returns structured before/after changes for each affected line. Defaults to dry run.
+
+#### `kb_diff_parse` — Parse unified diff text
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `diff` | string | **yes** | Raw unified diff text |
+
+Parses into file-level and hunk-level structural changes.
+
+#### `kb_data_transform` — jq-like JSON transforms
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `input` | string | **yes** | Input JSON string |
+| `expression` | string | **yes** | Transform expression (filtering, projection, grouping, path extraction) |
+
+### Execution & Validation
+
+#### `kb_eval` — Execute code in a sandboxed VM
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `code` | string | **yes** | — | Code snippet to execute |
+| `lang` | enum | no | `js` | `js` (direct) or `ts` (strips type syntax first) |
+| `timeout` | number (1–60000) | no | `5000` | Execution timeout in milliseconds |
+
+Captures console output and return values. Constrained VM with timeout.
+
+#### `kb_check` — Run typecheck and lint
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `files` | string[] | no | — | Specific files (omit to check all) |
+| `cwd` | string | no | — | Working directory |
+| `skip_types` | boolean | no | `false` | Skip TypeScript typecheck |
+| `skip_lint` | boolean | no | `false` | Skip Biome lint |
+
+Runs incremental `tsc` and `biome` and returns structured error/warning lists.
+
+#### `kb_test_run` — Run Vitest tests
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `files` | string[] | no | — | Specific test files or patterns |
+| `grep` | string | no | — | Only run tests matching this pattern |
+| `cwd` | string | no | — | Working directory |
+
+Returns structured pass/fail summary. `isError` set if any tests failed.
+
+#### `kb_batch` — Execute multiple operations in parallel
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `operations` | object[] (min 1) | **yes** | — | Operations: `id` (string), `type` (`search`/`find`/`check`), `args` (record) |
+| `concurrency` | number (1–20) | no | `4` | Max concurrent operations |
+
+Returns per-operation outcomes (success/failure with results or errors).
+
+### Git & Environment
+
+#### `kb_git_context` — Summarize Git repository state
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `cwd` | string | no | — | Repository root |
+| `commit_count` | number (1–50) | no | `5` | Recent commits to include |
+| `include_diff` | boolean | no | `false` | Include diff stat for working tree |
+
+Returns branch, working tree status, recent commits, and optionally diff stats.
+
+#### `kb_process` — Manage child processes
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `action` | enum | **yes** | — | `start`, `stop`, `status`, `list`, `logs` |
+| `id` | string | varies | — | Managed process ID |
+| `command` | string | varies | — | Executable (for `start`) |
+| `args` | string[] | no | — | Arguments (for `start`) |
+| `tail` | number (1–500) | no | — | Log lines (for `logs`) |
+
+#### `kb_watch` — Filesystem watchers
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `action` | enum | **yes** | — | `start`, `stop`, `list` |
+| `path` | string | varies | — | Directory path (for `start`) |
+| `id` | string | varies | — | Watcher ID (for `stop`) |
+
+#### `kb_delegate` — Delegate subtask to local Ollama model
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `prompt` | string | **yes** | — | Task or question to send |
+| `model` | string | no | first available | Ollama model name |
+| `system` | string | no | — | System prompt |
+| `context` | string | no | — | Context text (e.g., file contents) |
+| `temperature` | number (0–2) | no | `0.3` | Sampling temperature |
+| `timeout` | number (1000–600000) | no | `120000` | Timeout in ms |
+| `action` | enum | no | `generate` | `generate` or `list_models` |
+
+Fails fast if Ollama is not running. Returns model name, response text, duration, and token count.
+
+### Web & Network
+
+#### `kb_web_fetch` — Fetch web page for LLM consumption
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | string | **yes** | — | URL to fetch (http/https only) |
+| `mode` | enum | no | `markdown` | `markdown`, `raw`, `links`, `outline` |
+| `selector` | string | no | — | CSS selector to extract a specific element |
+| `max_length` | number (500–100000) | no | `15000` | Max output characters |
+| `include_metadata` | boolean | no | `true` | Include page title/description header |
+| `include_links` | boolean | no | `false` | Append extracted links |
+| `include_images` | boolean | no | `false` | Include image alt texts |
+| `timeout` | number (1000–60000) | no | `15000` | Request timeout in ms |
+
+Strips scripts, styles, and boilerplate. Smart truncation at paragraph boundaries.
+
+#### `kb_web_search` — Search the web
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | **yes** | — | Search query |
+| `limit` | number (1–20) | no | `5` | Max results |
+| `site` | string | no | — | Restrict to domain (e.g., `docs.aws.amazon.com`) |
+
+Uses DuckDuckGo HTML search — no API key required. Returns title, URL, and snippet for each result.
+
+#### `kb_http` — Make HTTP requests
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | string | **yes** | — | Request URL (http/https only) |
+| `method` | enum | no | `GET` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` |
+| `headers` | record | no | — | Request headers |
+| `body` | string | no | — | Request body |
+| `timeout` | number (1000–60000) | no | `15000` | Timeout in ms |
+
+Returns status, headers, formatted body (auto-pretty-prints JSON), timing, and size. Truncates responses over 50K chars.
+
+### Developer Utilities
+
+#### `kb_regex_test` — Test regex patterns
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `pattern` | string | **yes** | — | Regex pattern (without delimiters) |
+| `flags` | string | no | `""` | Regex flags (g, i, m, s, etc.) |
+| `test_strings` | string[] | **yes** | — | Strings to test against |
+| `mode` | enum | no | `match` | `match`, `replace`, `split` |
+| `replacement` | string | no | — | Replacement string (for replace mode) |
+
+Returns match details with groups and indices for each test string.
+
+#### `kb_encode` — Encoding, decoding, and hashing
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `operation` | enum | **yes** | `base64_encode`, `base64_decode`, `url_encode`, `url_decode`, `sha256`, `md5`, `jwt_decode`, `hex_encode`, `hex_decode` |
+| `input` | string | **yes** | Input text |
+
+JWT decode shows header and payload without signature verification.
+
+#### `kb_measure` — Code complexity metrics
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `path` | string | **yes** | — | File or directory to measure |
+| `extensions` | string[] | no | `.ts,.tsx,.js,.jsx` | File extensions to include |
+
+Returns per-file metrics (cyclomatic complexity, line counts, function counts, imports/exports) sorted by complexity, plus aggregate summary.
+
+#### `kb_changelog` — Generate changelog from git history
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `from` | string | **yes** | — | Start ref (tag, SHA, HEAD~N) |
+| `to` | string | no | `HEAD` | End ref |
+| `format` | enum | no | `grouped` | `grouped`, `chronological`, `per-scope` |
+| `include_breaking` | boolean | no | `true` | Highlight breaking changes |
+
+Parses conventional commit format (type(scope): subject). Groups by feat/fix/refactor/etc.
+
+#### `kb_schema_validate` — JSON Schema validation
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `data` | string | **yes** | JSON data to validate (as string) |
+| `schema` | string | **yes** | JSON Schema to validate against (as string) |
+
+Supports: type, required, properties, additionalProperties, items, enum, const, pattern, minimum/maximum, minLength/maxLength, minItems/maxItems.
+
+#### `kb_snippet` — Persistent code snippet storage
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `action` | enum | **yes** | `save`, `get`, `list`, `search`, `delete` |
+| `name` | string | varies | Snippet name |
+| `language` | string | no | Language tag |
+| `code` | string | varies | Code content (for save) |
+| `tags` | string[] | no | Categorization tags |
+| `query` | string | varies | Search query (for search) |
+
+Stored as JSON in `.kb-state/snippets/`. Searchable by name, tags, language, and content.
+
+#### `kb_env` — System environment info
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `include_env` | boolean | no | `false` | Include environment variables |
+| `filter_env` | string | no | — | Filter env vars by name substring |
+| `show_sensitive` | boolean | no | `false` | Show sensitive values (redacted by default) |
+
+Returns platform, arch, OS, CPU count, memory, Node version, CWD. Sensitive env var values (keys matching key/secret/token/password) are redacted unless explicitly requested.
+
+#### `kb_time` — Date/time utilities
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `operation` | enum | **yes** | `now`, `parse`, `convert`, `diff`, `add` |
+| `input` | string | varies | Date input (ISO, unix timestamp, parseable string). For diff: two comma-separated dates |
+| `timezone` | string | no | Target timezone (e.g., `America/New_York`) |
+| `duration` | string | no | Duration to add (e.g., `2h30m`, `1d`) — for add operation |
+
+Auto-detects unix seconds vs milliseconds. Supports human-readable duration format (2h30m, 1d12h).
+
+### Verified Lanes
+
+#### `kb_lane` — Manage verified lanes
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `action` | enum | **yes** | — | `create`, `list`, `status`, `diff`, `merge`, `discard` |
+| `name` | string | varies | — | Lane name |
+| `files` | string[] | varies | — | File paths to copy into lane (for `create`) |
+
+Isolated file copies for parallel exploration. Create a lane, make changes, diff against originals, merge back, or discard.
+
+### System
+
+#### `kb_health` — Run project health checks
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `path` | string | no | cwd | Root directory to check |
+
+Verifies package.json, tsconfig, scripts, lockfile, README, LICENSE, .gitignore.
+
+#### `kb_queue` — Manage task queues
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `action` | enum | **yes** | — | `create`, `push`, `next`, `done`, `fail`, `get`, `list`, `clear`, `delete` |
+| `name` | string | varies | — | Queue name |
+| `title` | string | varies | — | Item title (for `push`) |
+| `id` | string | varies | — | Item ID (for `done`/`fail`) |
+| `data` | any | no | — | Arbitrary data to attach |
+| `error` | string | varies | — | Error message (for `fail`) |
+
+Sequential task queues for agent operations.
+
+#### `kb_replay_list` — View audit trail
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `last` | number | no | 20 | Number of entries to return |
+| `tool` | string | no | — | Filter by tool name (e.g., `kb_search`) |
+| `source` | enum | no | — | Filter by source: `mcp` or `cli` |
+| `since` | string | no | — | ISO timestamp — only show entries after this time |
+
+Shows the audit trail of recent tool invocations. Each entry includes tool name, duration, input/output summaries, and status. Useful for debugging agent behavior.
+
+#### `kb_replay_clear` — Clear audit trail
+
+No parameters. Clears the entire replay log.
+
+---
+
+## MCP Resources
+
+| URI | Name | Description |
+|-----|------|-------------|
+| `kb://status` | `kb-status` | Quick status: record count, file count, last indexed time |
+| `kb://file-tree` | `kb-file-tree` | Sorted list of all indexed source file paths |
+
+---
+
+## Curated Knowledge System
+
+The curated system is the agent's **persistent memory layer**. Files are stored as markdown with YAML frontmatter in `curated/`:
+
+```
+curated/
+├── conventions/   # 214 entries — coding conventions, style rules, naming patterns
+├── decisions/     # 295 entries — architecture decisions, ADRs, design rationale
+├── patterns/      # 165 entries — recurring patterns, templates, code idioms
+└── troubleshooting/  # 62 entries — known issues, fixes, debugging guides
+```
+
+### Frontmatter Format
+
+```yaml
+---
+title: "Use LanceDB for local vector storage"
+category: decisions
+tags: ["vector-store", "architecture", "lancedb"]
+created: 2026-01-15T10:30:00.000Z
+updated: 2026-02-20T14:22:00.000Z
+version: 3
+origin: curated
+changelog:
+  - version: 1
+    date: 2026-01-15T10:30:00.000Z
+    reason: "Initial creation"
+  - version: 2
+    date: 2026-02-01T09:00:00.000Z
+    reason: "Added performance benchmarks"
+  - version: 3
+    date: 2026-02-20T14:22:00.000Z
+    reason: "Updated with hybrid search findings"
+---
+
+Markdown content here...
+```
+
+### Category Guidelines
+
+| Category | Use For | Examples |
+|----------|---------|---------|
+| `conventions` | Rules the team follows | Naming patterns, import ordering, error handling style, test structure |
+| `decisions` | Why something was chosen | ADRs, technology choices, pattern selections with trade-offs |
+| `patterns` | How to do recurring things | CDK stack templates, API endpoint patterns, state machine shapes |
+| `troubleshooting` | Known problems and fixes | Build failures, deployment gotchas, dependency conflicts |
+| Custom (`api-contracts`, `runbooks`, etc.) | Any kebab-case slug | Domain-specific categories as needed |
+
+---
+
+## How to Write Agent Instructions for Using This KB
+
+When writing instructions for an AI agent (e.g., in `.copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, or system prompts), include the following guidance:
+
+### Recommended Agent Instruction Template
+
+```markdown
+## Knowledge Base Usage
+
+You have access to a persistent knowledge base via MCP tools. Use it proactively.
+
+### Before Starting Any Task
+1. **Search first**: Use `kb_search` with a natural language query describing your task to find relevant context, prior decisions, conventions, and patterns before writing code.
+2. **Check conventions**: `kb_search` with `origin: "curated"` and `category: "conventions"` for coding standards that apply to your work.
+3. **Check decisions**: `kb_search` with `category: "decisions"` to understand why things were built a certain way.
+
+### Search Strategies
+- **Broad hybrid** (default, best for most queries): `kb_search({ query: "notification routing architecture" })`
+- **Exact identifier lookup**: `kb_search({ query: "handleNotification", search_mode: "keyword" })`
+- **Conceptual similarity**: `kb_search({ query: "event-driven message fanout design", search_mode: "semantic" })`
+- **Specific convention**: `kb_search({ query: "error handling", origin: "curated", category: "conventions" })`
+- **Code patterns**: `kb_search({ query: "DynamoDB batch write pattern", content_type: "code-typescript" })`
+- **Troubleshooting**: `kb_search({ query: "deployment failure CDK", category: "troubleshooting" })`
+- **View a full file**: `kb_lookup({ path: "src/services/dispatcher.ts" })`
+
+### Follow the Hints
+Every tool response includes a `_Next:` suggestion at the bottom. Follow these hints for efficient workflows — they guide you to logical next actions (e.g., after `kb_search`, the hint suggests `kb_lookup` or `kb_analyze_structure`).
+
+### After Completing a Task
+1. **Remember decisions**: If you made an architecture or design decision, store it:
+   ```
+   kb_remember({
+     title: "Use event-driven pattern for notification fanout",
+     content: "## Decision\n\n...\n\n## Rationale\n\n...\n\n## Alternatives Considered\n\n...",
+     category: "decisions",
+     tags: ["notifications", "architecture", "event-driven"]
+   })
+   ```
+2. **Remember patterns**: If you established a reusable code pattern:
+   ```
+   kb_remember({
+     title: "CDK construct pattern for SQS-Lambda integration",
+     content: "## Pattern\n\n```typescript\n...\n```\n\n## When to Use\n\n...",
+     category: "patterns",
+     tags: ["cdk", "sqs", "lambda"]
+   })
+   ```
+3. **Remember troubleshooting**: If you solved a tricky bug:
+   ```
+   kb_remember({
+     title: "LanceDB dimension mismatch after model change",
+     content: "## Problem\n\n...\n\n## Solution\n\nRun `kb_reindex({ full: true })`...",
+     category: "troubleshooting",
+     tags: ["lancedb", "embeddings"]
+   })
+   ```
+4. **Update existing knowledge**: If you're revising a prior decision:
+   ```
+   kb_update({
+     path: "decisions/use-event-driven-fanout.md",
+     content: "updated markdown...",
+     reason: "Added retry strategy after production incident"
+   })
+   ```
+
+### Knowledge Quality Standards
+- **Decisions** should include: Context, Decision, Rationale, Alternatives Considered, Consequences
+- **Patterns** should include: Pattern description, Code example, When to Use, When Not to Use
+- **Conventions** should include: The Rule, Why, Examples (good vs bad)
+- **Troubleshooting** should include: Problem, Symptoms, Root Cause, Solution, Prevention
+
+### Codebase Analysis (for onboarding or deep understanding)
+- Run `kb_produce_knowledge({ aspects: ["all"] })` to get analysis baselines and follow the synthesis instructions to populate the KB
+- Use `kb_analyze_structure({ path: "." })` for project layout overview
+- Use `kb_analyze_dependencies({ path: ".", format: "mermaid" })` for dependency visualization
+- Use `kb_analyze_patterns({ path: "." })` to detect frameworks and conventions
+
+### Index Maintenance
+- Run `kb_reindex()` after significant code changes (incremental, fast)
+- Run `kb_reindex({ full: true })` after model changes or corruption
+- Check `kb_status()` to verify index health
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `KB_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
+| `KB_PORT` | `3210` | HTTP server port (when `--transport http`) |
+| `KB_AUTO_INDEX` | `true` | Set to `false` to skip initial auto-indexing |
+| `KB_CORS_ORIGIN` | `*` | CORS allowed origin for HTTP mode |
+| `KB_WORKSPACE_DIR` | — | Override workspace root path |
+| `KB_DATA_DIR` | — | Override LanceDB data directory |
+| `KB_MODEL_DIR` | — | Override ONNX model cache directory |
+
+---
+
+## Tech Stack
+
+- **Embeddings**: `@huggingface/transformers` with `mixedbread-ai/mxbai-embed-large-v1` (1024 dimensions, ONNX, query-prefixed with `"Represent this sentence for searching relevant passages: "`)
+- **Vector Store**: LanceDB (local disk, L2 distance → similarity score, built-in FTS index for keyword search)
+- **Search**: Hybrid (vector + FTS + RRF fusion), semantic-only, or keyword-only modes
+- **Chunking**: Markdown-aware (heading hierarchy), **tree-sitter AST-based** (TS/JS/Python/Go/Rust/Java — preserves function/class boundaries), with overlap. Falls back to regex-based generic chunking when tree-sitter grammars are unavailable.
+- **Dependency Analysis**: Confidence-scored imports (high/medium/low per import pattern)
+- **Auto-Persist**: Analysis tool results are automatically indexed as `origin: 'produced'` entries for future search
+- **Workflow Hints**: Every tool response includes `_Next:` suggestions for logical follow-up actions
+- **MCP SDK**: `@modelcontextprotocol/sdk` (stdio + StreamableHTTP transports)
+- **Runtime**: Node.js ≥ 24, TypeScript, ESM, pnpm workspaces
+- **Build**: esbuild with tsc for declarations
+- **Lint**: Biome
+- **Test**: Vitest