@vpxa/kb 0.1.12 → 0.1.13

package/skills/knowledge-base/SKILL.md

@@ -1,6 +1,6 @@
 # @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.
+Local-first AI developer toolkit — 64 MCP tools for knowledge management, code analysis, context compression, code manipulation, execution, web access, and developer utilities.
 
 ## When to Use
 
@@ -25,8 +25,8 @@ Local-first AI developer toolkit — 57 MCP tools for knowledge management, code
 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)
+- **MCP server**: 65 tools + 2 resources (via `@modelcontextprotocol/sdk`)
+- **CLI**: 45 commands (thin dispatcher + 10 command groups)
 - **Search**: Hybrid vector + keyword + RRF fusion
 - **Embeddings**: ONNX local (mxbai-embed-large-v1, 1024 dimensions)
 - **Vector store**: LanceDB (embedded, zero infrastructure)
@@ -54,19 +54,18 @@ remember                                         (capture insights)
 remember({ title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })
 ```
 
-## Tool Catalog (57 tools)
+## Tool Catalog (65 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 |
+| `find` | `kb find` | Federated search: vector + FTS + glob + regex in one call. Use `mode: 'examples'` to find usage examples. |
 | `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 |
+| `dead_symbols` | `kb dead-symbols` | Find exported symbols never imported — separates source (actionable) from docs (informational). Accepts `path` to scope the search. |
 | `file_summary` | `kb summarize` | Structural overview of a file (exports, imports, functions) |
 
 ### Code Analysis (7)
@@ -76,14 +75,14 @@ remember({ title: "Session checkpoint: <topic>", content: "<what was done, decis
 | `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_entry_points` | `kb analyze entry-points` | Find entry points: handlers, CDK constructs, test suites, package exports (walks workspace packages) |
 | `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) |
+| `compact` | `kb compact` | Compress text to relevant sections using embeddings (no LLM). Accepts `path` for server-side file read. |
 | `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 |
@@ -97,13 +96,14 @@ remember({ title: "Session checkpoint: <topic>", content: "<what was done, decis
 | `diff_parse` | `kb diff` | Parse unified diff → structured changes |
 | `data_transform` | `kb transform` | JQ-like JSON transformations |
 
-### Execution & Validation (4)
+### Execution & Validation (5)
 | Tool | CLI | Purpose |
-|------|-----|---------|
+|------|-----|---------||
 | `eval` | `kb eval` | Sandboxed JavaScript/TypeScript execution |
-| `check` | `kb check` | Incremental typecheck + lint in one call |
+| `check` | `kb check` | Incremental typecheck + lint. `detail` param: summary (default, ~300 tokens), errors, full |
 | `test_run` | `kb test` | Run tests with structured pass/fail results |
 | `batch` | `kb batch` | Execute multiple operations in parallel |
+| `audit` | `kb audit` | Unified project audit: structure, deps, patterns, health, dead symbols, check, entry points → synthesized report with score and recommendations. 6 round-trips → 1. |
 
 ### Knowledge Management (6)
 | Tool | CLI | Purpose |
@@ -151,13 +151,13 @@ Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/de
 
 ### 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.) |
+| `health` | `kb health` | Project health checks (package.json, tsconfig, lockfile, circular deps) |
+| `guide` | `kb guide` | Tool discovery — given a goal, recommends tools and workflow order |
 | `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 |
+| `replay` | `kb replay` | View or clear the audit trail of tool invocations (action: list/clear) |
 
 ## Search Strategy
 
@@ -180,7 +180,7 @@ analyze_structure({ path: "src/" })
 ### Planning a Task
 ```
 scope_map({ task: "implement user auth" })
-→ compact({ text: <large file>, query: "auth flow" })
+→ compact({ path: "src/auth.ts", query: "auth flow" })
 → workset({ action: "save", name: "auth-task", files: [...] })
 ```
 
@@ -227,8 +227,8 @@ 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 compact <q>   # Context compression (--path file or stdin)
+kb check         # Typecheck + lint (--detail summary|errors|full)
 kb test          # Run tests
 kb rename <old> <new> <path>  # Rename symbol
 kb lane create <name> --files f1,f2  # Create lane