@vpxa/kb 0.1.1

package/skills/knowledge-base/SKILL.md

@@ -0,0 +1,316 @@
+# @vpxa/kb — Knowledge Base Toolkit
+
+Local-first AI developer toolkit — 57 MCP tools for knowledge management, code analysis, context compression, code manipulation, execution, web access, and developer utilities.
+
+## When to Use
+
+- You need long-term memory across coding sessions
+- You want to search a codebase semantically (by meaning, not just keywords)
+- You need to compress large contexts to focus on what matters
+- You want structured output from build tools (tsc, vitest, biome, git)
+- You need to plan which files to read for a task
+- You want to safely explore refactors in isolated lanes
+- You need to rename symbols, apply codemods, or run code transformations
+- You want to fetch and read web pages or search the web
+- You need to make HTTP requests, test APIs, or debug endpoints
+- You want to test regex patterns, encode/decode data, or validate JSON schemas
+- You need code complexity metrics or a git changelog
+- You want to save and reuse code snippets across sessions
+
+## Architecture
+
+10-package monorepo published as a single npm package:
+
+```
+core → store → embeddings → chunker → indexer → analyzers → tools → server → cli → tui
+```
+
+- **MCP server**: 57 tools + 2 resources (via `@modelcontextprotocol/sdk`)
+- **CLI**: 42 commands (thin dispatcher + 8 command groups)
+- **Search**: Hybrid vector + keyword + RRF fusion
+- **Embeddings**: ONNX local (mxbai-embed-large-v1, 1024 dimensions)
+- **Vector store**: LanceDB (embedded, zero infrastructure)
+- **Chunking**: Tree-sitter AST (TS/JS/Python/Go/Rust/Java) + regex fallback
+- **TUI**: Ink/React dashboard for human monitoring (search, status, curated, activity log)
+
+## Session Protocol (MANDATORY)
+
+### Start of Session
+```
+status()
+search({ query: "SESSION CHECKPOINT", origin: "curated" })
+list({ category: "conventions" })
+```
+
+### During Session
+```
+search → scope_map → symbol → trace  (orient)
+check → test_run                             (validate changes)
+remember                                         (capture insights)
+```
+
+### End of Session
+```
+remember({ title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })
+```
+
+## Tool Catalog (57 tools)
+
+### Search & Discovery (9)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `search` | `kb search` | Hybrid/semantic/keyword search with `search_mode` param |
+| `find` | `kb find` | Federated search: vector + FTS + glob + regex in one call |
+| `symbol` | `kb symbol` | Resolve symbol definition, imports, and references |
+| `lookup` | `kb lookup` | Full-file retrieval by path or record ID |
+| `scope_map` | `kb scope-map` | Task-scoped reading plan with token estimates |
+| `trace` | `kb trace` | Forward/backward flow tracing through call chains |
+| `find_examples` | `kb examples` | Find usage examples of a symbol or pattern |
+| `dead_symbols` | `kb dead-symbols` | Find exported symbols that are never imported |
+| `file_summary` | `kb summarize` | Structural overview of a file (exports, imports, functions) |
+
+### Code Analysis (7)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `analyze_structure` | `kb analyze structure` | Project structure overview |
+| `analyze_dependencies` | `kb analyze deps` | Dependency graph with confidence |
+| `analyze_symbols` | `kb analyze symbols` | Symbol extraction and cross-references |
+| `analyze_patterns` | `kb analyze patterns` | Design pattern detection |
+| `analyze_entry_points` | `kb analyze entry-points` | Find entry points |
+| `analyze_diagram` | `kb analyze diagram` | Generate Mermaid diagrams |
+| `blast_radius` | `kb analyze blast-radius` | Change impact analysis |
+
+### Context Management (5)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `compact` | `kb compact` | Compress text to relevant sections using embeddings (no LLM) |
+| `workset` | `kb workset` | Named file set management (save/load/add/remove) |
+| `stash` | `kb stash` | Named key-value store for session data |
+| `checkpoint` | `kb checkpoint` | Save/restore session checkpoints |
+| `parse_output` | `kb parse-output` | Parse tsc/vitest/biome/git output → structured JSON |
+
+### Code Manipulation (4)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `rename` | `kb rename` | Smart whole-word symbol rename across files (dry-run supported) |
+| `codemod` | `kb codemod` | Regex-based code transformations with rules (dry-run supported) |
+| `diff_parse` | `kb diff` | Parse unified diff → structured changes |
+| `data_transform` | `kb transform` | JQ-like JSON transformations |
+
+### Execution & Validation (4)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `eval` | `kb eval` | Sandboxed JavaScript/TypeScript execution |
+| `check` | `kb check` | Incremental typecheck + lint in one call |
+| `test_run` | `kb test` | Run tests with structured pass/fail results |
+| `batch` | `kb batch` | Execute multiple operations in parallel |
+
+### Knowledge Management (6)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `remember` | `kb remember` | Store a curated knowledge entry |
+| `update` | `kb update` | Update an existing entry |
+| `forget` | `kb forget` | Delete an entry (requires reason) |
+| `read` | `kb read` | Read a curated entry by path |
+| `list` | `kb list` | List curated entries |
+| `produce_knowledge` | — | Auto-generate knowledge from analysis |
+
+### Verified Lanes (1 tool, 6 actions)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `lane` | `kb lane` | Manage isolated file copies for parallel exploration |
+
+Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/deleted), `diff` (line-level diff), `merge` (apply back to originals), `discard`.
+
+### Git & Environment (4)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `git_context` | `kb git` | Branch, status, recent commits |
+| `process` | `kb proc` | Process supervisor (start/stop/logs) |
+| `watch` | `kb watch` | Filesystem watcher |
+| `delegate` | `kb delegate` | Delegate subtask to local Ollama model |
+
+### Web & Network (3)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `web_fetch` | — | Fetch web page → markdown/raw/links/outline for LLM consumption |
+| `web_search` | — | Search the web via DuckDuckGo (no API key needed) |
+| `http` | — | Make HTTP requests for API testing/debugging |
+
+### Developer Utilities (8)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `regex_test` | — | Test regex patterns with match/replace/split modes |
+| `encode` | — | Base64, URL, SHA-256, MD5, hex encode/decode, JWT decode |
+| `measure` | — | Code complexity metrics (cyclomatic, lines, functions) |
+| `changelog` | — | Generate changelog from git history (conventional commits) |
+| `schema_validate` | — | Validate JSON data against JSON Schema |
+| `snippet` | — | Save/get/search/delete persistent code snippets |
+| `env` | — | System and runtime environment info (sensitive values redacted) |
+| `time` | — | Date parsing, timezone conversion, duration math |
+
+### System (6)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `status` | `kb status` | Index statistics |
+| `reindex` | `kb reindex` | Rebuild index |
+| `health` | `kb health` | Project health checks (package.json, tsconfig, lockfile, etc.) |
+| `queue` | `kb queue` | Task queue for sequential agent operations (create/push/next/done/fail) |
+| `replay_list` | `kb replay` | View audit trail of tool invocations (filter by tool/source/time) |
+| `replay_clear` | `kb replay-clear` | Clear the replay audit trail |
+
+## Search Strategy
+
+1. **Start broad**: `search({ query: "topic", search_mode: "hybrid" })`
+2. **Narrow**: Add `content_type`, `origin`, or `category` filters
+3. **Exact match**: Use `search_mode: "keyword"` for identifiers
+4. **Federated**: Use `find` to combine vector + glob + regex
+
+## Workflow Chains
+
+### Codebase Onboarding
+```
+analyze_structure({ path: "src/" })
+→ analyze_dependencies({ path: "src/" })
+→ analyze_entry_points({ path: "src/" })
+→ produce_knowledge({ path: "src/" })
+→ remember({ title: "Codebase onboarding complete", ... })
+```
+
+### Planning a Task
+```
+scope_map({ task: "implement user auth" })
+→ compact({ text: <large file>, query: "auth flow" })
+→ workset({ action: "save", name: "auth-task", files: [...] })
+```
+
+### Bug Investigation
+```
+parse_output({ output: <error> }) → symbol({ name: "failingFn" })
+→ trace({ symbol: "failingFn", direction: "backward" })
+→ blast_radius({ changed_files: ["suspect.ts"] })
+→ eval({ code: "hypothesis test" }) → check({ files: ["suspect.ts"] })
+```
+
+### Safe Refactor with Lanes
+```
+scope_map({ task: "rename UserService" })
+→ lane({ action: "create", name: "refactor", files: [...] })
+→ [make changes in lane files]
+→ lane({ action: "diff", name: "refactor" })
+→ check({}) → test_run({})
+→ lane({ action: "merge", name: "refactor" })
+```
+
+### After Making Changes
+```
+blast_radius({ changed_files: ["src/auth.ts"] })
+→ check({}) → test_run({ grep: "auth" })
+→ reindex()
+→ remember({ title: "Implemented auth", content: "..." })
+```
+
+### Pre-Commit Validation
+```
+git_context({ diff: true })
+→ diff_parse({ diff: <staged diff> })
+→ blast_radius({ changed_files: [...] })
+→ check({}) → test_run({})
+```
+
+## CLI Quick Reference
+
+```bash
+kb init          # Scaffold KB in current directory
+kb serve         # Start MCP server (stdio or HTTP)
+kb search <q>    # Hybrid search
+kb find <q>      # Federated search
+kb symbol <name> # Resolve symbol
+kb scope-map <t> # Task reading plan
+kb compact <q>   # Context compression
+kb check         # Typecheck + lint
+kb test          # Run tests
+kb rename <old> <new> <path>  # Rename symbol
+kb lane create <name> --files f1,f2  # Create lane
+kb lane diff <name>  # View lane changes
+kb lane merge <name> # Merge lane back
+kb status        # Index stats
+kb reindex       # Rebuild index
+```
+
+## Configuration
+
+`kb.config.json` in project root:
+```json
+{
+  "sources": [{ "path": ".", "excludePatterns": ["node_modules/**", "**/node_modules/**", "dist/**", "coverage/**", ".kb-data/**"] }],
+  "indexing": { "chunkSize": 1500, "chunkOverlap": 200, "minChunkSize": 100, "concurrency": 5 },
+  "embedding": { "model": "mixedbread-ai/mxbai-embed-large-v1", "dimensions": 1024 },
+  "store": { "backend": "lancedb", "path": ".kb-data" },
+  "curated": { "path": "curated" }
+}
+```
+
+## IDE Integration
+
+### VS Code — HTTP mode (recommended for development)
+```json
+// .vscode/mcp.json
+{
+  "servers": {
+    "kb": {
+      "type": "http",
+      "url": "http://localhost:3210/mcp"
+    }
+  }
+}
+```
+Start server: `npx kb serve --http --port 3210`
+
+### VS Code — stdio mode (no separate server)
+```json
+{
+  "servers": {
+    "kb": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@vpxa/kb", "serve", "--stdio"]
+    }
+  }
+}
+```
+
+### Claude Code (`.mcp.json`)
+```json
+{
+  "mcpServers": {
+    "kb": {
+      "command": "npx",
+      "args": ["@vpxa/kb", "serve"]
+    }
+  }
+}
+```
+
+## Development (Self-Dogfooding)
+
+When developing @vpxa/kb itself, use the tool on its own codebase:
+
+```bash
+# Build → Reindex → Use loop
+pnpm build                          # Build all 10 packages
+node bin/kb.mjs reindex             # Index own source into LanceDB
+node bin/kb.mjs search "query"      # Search own code
+node bin/kb.mjs symbol "FnName"     # Resolve symbols in own code
+node bin/kb.mjs check               # Typecheck + lint
+pnpm test                           # Run 287+ tests
+
+# Start MCP server for agent use during development
+node bin/kb.mjs serve --http --port 3210
+```
+
+**Rules:**
+- Always `pnpm build` before using CLI/server (runs from `dist/`)
+- Always `reindex` after structural code changes
+- LanceDB is single-process — don't run CLI and HTTP server simultaneously
+- Curated entries in `curated/` survive reindex and are indexed separately