@vpxa/kb 0.1.11 → 0.1.13

package/packages/cli/dist/commands/init.js

@@ -1,147 +1,92 @@
-import{appendFileSync as p,existsSync as o,mkdirSync as u,readFileSync as m,writeFileSync as a}from"node:fs";import{basename as g,resolve as t}from"node:path";const h={sources:[{path:".",excludePatterns:["**/node_modules/**","**/dist/**","**/build/**","**/.git/**","**/.kb-data/**","**/coverage/**","**/*.min.js","**/package-lock.json","**/pnpm-lock.yaml"]}],indexing:{chunkSize:1500,chunkOverlap:200,minChunkSize:100},embedding:{model:"mixedbread-ai/mxbai-embed-large-v1",dimensions:1024},store:{backend:"lancedb",path:".kb-data/lance"},curated:{path:"curated"}};function f(e){return{servers:{[`${e}-kb`]:{type:"stdio",command:"npx",args:["@vpxa/kb","serve"]}}}}function y(e){return`# ${e} \u2014 Copilot Instructions
-
-This project uses **@vpxa/kb** as an MCP knowledge base server. Use the KB tools to search, analyze, and understand the codebase before making changes.
-
-## KB Tools
-
-Before starting any task on **${e}**, use these MCP tools:
-
-| Action | Tool | Example |
-|--------|------|---------|
-| Search code & decisions | \`kb_search\` | \`kb_search({ query: "..." })\` |
-| Find symbol definition | \`kb_symbol\` | \`kb_symbol({ name: "ClassName" })\` |
-| Plan what to read | \`kb_scope_map\` | \`kb_scope_map({ task: "..." })\` |
-| Trace call chains | \`kb_trace\` | \`kb_trace({ symbol: "fn", file: "path" })\` |
-| Impact of a change | \`kb_blast_radius\` | \`kb_blast_radius({ changed_files: ["..."] })\` |
-| Persist what you learn | \`kb_remember\` | \`kb_remember({ title: "...", category: "decisions" })\` |
-| Typecheck + lint | \`kb_check\` | \`kb_check({})\` |
-| Run tests | \`kb_test_run\` | \`kb_test_run({})\` |
-
-## Workflow
-
-\`\`\`
-kb_search({ query: "your task keywords" })            # Recall prior decisions
-kb_scope_map({ task: "what you are doing" })           # Get a reading plan
-# ... do the work ...
-kb_check({})                                           # Typecheck + lint
-kb_test_run({})                                        # Run tests
-kb_remember({ title: "What I learned", category: "decisions" })  # Persist
-\`\`\`
-
-## KB MCP Tools \u2014 Complete Reference
-
-### Search & Discovery
-| Tool | Purpose |
-|------|---------|
-| \`kb_search\` | Hybrid vector + keyword search. Modes: \`hybrid\` (default), \`semantic\`, \`keyword\`. Filters: \`origin\`, \`category\`, \`content_type\`, \`tags\`. |
-| \`kb_find\` | Federated search: vector + FTS + glob + regex in one call. |
-| \`kb_symbol\` | Resolve symbol definition, imports, and all references across files. |
-| \`kb_lookup\` | Full-file retrieval by path or record ID. |
-| \`kb_scope_map\` | Task-scoped reading plan with file list and token estimates. |
-| \`kb_trace\` | Forward/backward flow tracing through call chains. |
-| \`kb_find_examples\` | Find real usage examples of a symbol or pattern. |
-| \`kb_dead_symbols\` | Find exported symbols that are never imported anywhere. |
-| \`kb_file_summary\` | Structural overview of a file (exports, imports, functions). |
-
-### Code Analysis
-| Tool | Purpose |
-|------|---------|
-| \`kb_analyze_structure\` | Project structure overview with file tree and stats. |
-| \`kb_analyze_dependencies\` | Dependency graph with confidence scoring. |
-| \`kb_analyze_symbols\` | Symbol extraction and cross-references. |
-| \`kb_analyze_patterns\` | Design pattern detection (Singleton, Factory, etc.). |
-| \`kb_analyze_entry_points\` | Discover entry points (Lambda handlers, CLI, HTTP routes). |
-| \`kb_analyze_diagram\` | Generate Mermaid architecture diagrams. |
-| \`kb_blast_radius\` | Change impact analysis \u2014 what breaks if you modify a file. |
-
-### Knowledge Management
-| Tool | Purpose |
-|------|---------|
-| \`kb_remember\` | Store a curated knowledge entry (decisions, patterns, conventions). |
-| \`kb_read\` | Read a curated entry by path. |
-| \`kb_update\` | Update an existing curated entry. |
-| \`kb_forget\` | Delete a curated entry (requires reason). |
-| \`kb_list\` | List curated entries, filterable by category and tags. |
-| \`kb_produce_knowledge\` | Auto-generate knowledge from codebase analysis. |
-
-### Execution & Validation
-| Tool | Purpose |
-|------|---------|
-| \`kb_check\` | Incremental typecheck + lint in one call (tsc + biome). |
-| \`kb_test_run\` | Run tests with structured pass/fail results. |
-| \`kb_eval\` | Sandboxed JavaScript/TypeScript execution. |
-| \`kb_batch\` | Execute multiple operations in parallel. |
-
-### Code Manipulation
-| Tool | Purpose |
-|------|---------|
-| \`kb_rename\` | Smart whole-word symbol rename across files (dry-run supported). |
-| \`kb_codemod\` | Regex-based code transformations with rule files (dry-run supported). |
-| \`kb_diff_parse\` | Parse unified diff into structured file changes. |
-| \`kb_data_transform\` | JQ-like JSON transformations. |
-
-### Context Management
-| Tool | Purpose |
-|------|---------|
-| \`kb_compact\` | Compress text to relevant sections using embeddings (no LLM). |
-| \`kb_workset\` | Named file set management (save/load/add/remove working sets). |
-| \`kb_stash\` | Named key-value store for session data. |
-| \`kb_checkpoint\` | Save/restore lightweight session checkpoints. |
-| \`kb_parse_output\` | Parse build tool output (tsc, vitest, biome, git) into structured JSON. |
-
-### FORGE & Context Compression
-| Tool | Purpose |
-|------|---------|
-| \`kb_forge_ground\` | Full FORGE Ground phase (classify + scope + constraints + evidence). |
-| \`kb_forge_classify\` | Quick FORGE tier classification (Floor/Standard/Critical). |
-| \`kb_evidence_map\` | Track critical-path claims as Verified/Assumed/Unknown with receipts. |
-| \`kb_digest\` | Compress multiple text blocks into token-budgeted digest. |
-| \`kb_stratum_card\` | Generate T1/T2 context cards (10-100x token reduction). |
-
-### Web & Network
-| Tool | Purpose |
-|------|---------|
-| \`kb_web_fetch\` | Fetch web page \u2192 LLM-optimized markdown. CSS selectors, 4 modes, smart truncation. |
-| \`kb_web_search\` | Search the web via DuckDuckGo (no API key needed). |
-| \`kb_http\` | HTTP requests (GET/POST/PUT/PATCH/DELETE) for API testing with timing. |
-
-### Verified Lanes
-| Tool | Purpose |
-|------|---------|
-| \`kb_lane\` | Manage isolated file copies for parallel exploration. Actions: \`create\`, \`list\`, \`status\`, \`diff\`, \`merge\`, \`discard\`. |
-
-### Git & Environment
-| Tool | Purpose |
-|------|---------|
-| \`kb_git_context\` | Branch, status, recent commits, optional diff stats. |
-| \`kb_process\` | Process supervisor (start/stop/logs). |
-| \`kb_watch\` | Filesystem watcher for auto-triggered workflows. |
-| \`kb_delegate\` | Delegate subtask to a local Ollama model. |
-
-### Developer Utilities
-| Tool | Purpose |
-|------|---------|
-| \`kb_regex_test\` | Test regex patterns with match/replace/split modes. |
-| \`kb_encode\` | Base64, URL, SHA-256, MD5, hex encode/decode, JWT decode. |
-| \`kb_measure\` | Code complexity metrics (cyclomatic complexity, line counts). |
-| \`kb_changelog\` | Generate changelog from git history (conventional commits). |
-| \`kb_schema_validate\` | Validate JSON data against JSON Schema. |
-| \`kb_snippet\` | Save/get/search/delete persistent code snippets. |
-| \`kb_env\` | System and runtime environment info (sensitive values redacted). |
-| \`kb_time\` | Date parsing, timezone conversion, duration math. |
-
-### System
-| Tool | Purpose |
-|------|---------|
-| \`kb_status\` | Index statistics (record count, file count, content types). |
-| \`kb_reindex\` | Rebuild the vector index from configured sources. |
-| \`kb_health\` | Project health checks (package.json, tsconfig, lockfile, etc.). |
-| \`kb_onboard\` | First-time codebase onboarding \u2014 runs all analyses, auto-persists results. |
-| \`kb_graph\` | Knowledge graph queries (find_nodes, find_edges, neighbors, traverse, stats). |
-| \`kb_queue\` | Task queue for sequential agent operations. |
-| \`kb_replay_list\` | View audit trail of tool invocations. |
-| \`kb_replay_clear\` | Clear the replay audit trail. |
-`}function w(e){return`# ${e} \u2014 Agent Instructions
+import{appendFileSync as h,copyFileSync as y,existsSync as t,mkdirSync as n,readFileSync as v,writeFileSync as r}from"node:fs";import{basename as w,dirname as S,resolve as e}from"node:path";import{fileURLToPath as x}from"node:url";const C={sources:[{path:".",excludePatterns:["**/node_modules/**","**/dist/**","**/build/**","**/.git/**","**/.kb-data/**","**/coverage/**","**/*.min.js","**/package-lock.json","**/pnpm-lock.yaml"]}],indexing:{chunkSize:1500,chunkOverlap:200,minChunkSize:100},embedding:{model:"mixedbread-ai/mxbai-embed-large-v1",dimensions:1024},store:{backend:"lancedb",path:".kb-data/lance"},curated:{path:"curated"}};function A(o){return{servers:{[`${o}-kb`]:{type:"stdio",command:"npx",args:["@vpxa/kb","serve"]}}}}function T(o){return`# ${o} \u2014 Copilot Instructions
+
+This project uses **@vpxa/kb** as an MCP knowledge base server. The KB provides search, context compression, persistent memory, and validation tools that **MUST** be used to maintain quality and performance.
+
+## Mandatory Rules
+
+### 1. ALWAYS search before acting
+Before writing or modifying code, you MUST recall prior decisions and understand the affected area:
+\`\`\`
+kb_search({ query: "<task keywords>" })
+kb_scope_map({ task: "<what you are doing>" })
+\`\`\`
+
+### 2. ALWAYS compress context before reading large files
+Do NOT read entire files into context. Use these tools to reduce tokens and focus on what matters:
+
+| Situation | Tool | Why |
+|-----------|------|-----|
+| Need relevant sections of a large file | \`kb_compact\` | Extracts only semantically relevant chunks \u2014 5-20x reduction |
+| Need to summarize multiple sources | \`kb_digest\` | Compresses multiple text blocks into a token-budgeted summary |
+| Need a quick structural overview of a file | \`kb_file_summary\` | Returns exports, imports, functions without reading the full file |
+| Need a reusable context card | \`kb_stratum_card\` | Generates T1/T2 cards \u2014 10-100x token reduction |
+
+**Example \u2014 reading a 400-line file:**
+\`\`\`
+# BAD: read_file entire file (wastes ~3000 tokens)
+# GOOD: get structure first, then compact only what you need
+kb_file_summary({ path: "src/http-client.ts" })
+kb_compact({ path: "src/http-client.ts", query: "retry logic" })
+\`\`\`
+
+### 3. ALWAYS use persistent memory
+- **Start of session**: Read prior knowledge with \`kb_list()\` and \`kb_search({ query: "SESSION CHECKPOINT", origin: "curated" })\`
+- **During session**: Use \`kb_stash\` for temporary working data, \`kb_checkpoint\` to save progress
+- **End of session**: MUST call \`kb_remember\` to persist decisions, patterns, and lessons learned
+- **Before proposing a new approach**: MUST \`kb_search\` to check if a decision already exists
+
+| Tool | When | Persistence |
+|------|------|-------------|
+| \`kb_stash\` | Temporary data within a session (intermediate results, scratch notes) | Session only |
+| \`kb_checkpoint\` | Save/restore session progress (resumable work) | Session only |
+| \`kb_remember\` | Architecture decisions, conventions, patterns, troubleshooting | Permanent (survives reindex) |
+
+### 4. ALWAYS validate before committing
+\`\`\`
+kb_check({})                    # Typecheck + lint (returns summary by default)
+kb_test_run({})                 # Run tests
+kb_blast_radius({ changed_files: ["..."] })  # Impact analysis
+kb_audit({})                    # Unified project audit with score and recommendations
+\`\`\`
+
+### 5. Use FORGE for complex tasks
+For tasks involving multiple files or architectural decisions:
+\`\`\`
+kb_forge_classify({ task: "<description>" })   # Classify complexity tier
+kb_forge_ground({ task: "<description>" })     # Full analysis: scope + constraints + evidence
+kb_evidence_map({ claims: [...] })             # Track verified vs assumed claims
+\`\`\`
+
+## Quick Workflow
+
+\`\`\`
+# 1. Orient
+kb_search({ query: "task keywords" })
+kb_scope_map({ task: "what you are doing" })
+
+# 2. Read efficiently (NEVER raw-read large files)
+kb_file_summary({ path: "relevant-file.ts" })
+kb_compact({ path: "relevant-file.ts", query: "specific concern" })
+
+# 3. Do the work
+
+# 4. Validate
+kb_check({})
+kb_test_run({})
+
+# 5. Persist
+kb_remember({ title: "What I learned", content: "...", category: "decisions" })
+\`\`\`
+
+## Context Budget Rules
+
+- **Prefer \`kb_file_summary\` over \`read_file\`** for understanding file structure
+- **Prefer \`kb_compact\` over full file reads** when you need specific sections (use \`path\` param to avoid read_file round-trip)
+- **Prefer \`kb_search\` over \`grep_search\`** for semantic/conceptual queries
+- **Prefer \`kb_symbol\` over manual grep** for finding definitions and references
+- **Use \`kb_digest\`** when combining information from 3+ sources
+- **Use \`kb_stratum_card\`** to create reusable compressed context for repeated reference
+`}function P(o){return`# ${o} \u2014 Agent Instructions
 
 ## KB Knowledge Base
 
@@ -157,50 +102,140 @@ This project has a **@vpxa/kb** MCP server providing search, analysis, memory, a
 
 | Category | Tools | Purpose |
 |----------|-------|---------|
-| Search & Discovery | \`kb_search\`, \`kb_find\`, \`kb_symbol\`, \`kb_trace\`, \`kb_scope_map\`, \`kb_lookup\`, \`kb_find_examples\`, \`kb_dead_symbols\`, \`kb_file_summary\` | Find code, symbols, data flow, reading plans |
+| Search & Discovery | \`kb_search\`, \`kb_find\`, \`kb_symbol\`, \`kb_trace\`, \`kb_scope_map\`, \`kb_lookup\`, \`kb_dead_symbols\`, \`kb_file_summary\` | Find code, symbols, data flow, reading plans |
 | Code Analysis | \`kb_analyze_structure\`, \`kb_analyze_dependencies\`, \`kb_analyze_symbols\`, \`kb_analyze_patterns\`, \`kb_analyze_entry_points\`, \`kb_analyze_diagram\`, \`kb_blast_radius\` | Structure, deps, patterns, impact, diagrams |
 | Knowledge | \`kb_remember\`, \`kb_read\`, \`kb_update\`, \`kb_forget\`, \`kb_list\`, \`kb_produce_knowledge\` | Persistent cross-session memory |
-| Execution | \`kb_check\`, \`kb_test_run\`, \`kb_eval\`, \`kb_batch\` | Typecheck, lint, test, run code |
+| Execution | \`kb_check\`, \`kb_test_run\`, \`kb_eval\`, \`kb_batch\`, \`kb_audit\` | Typecheck, lint, test, run code, unified audit. \`check\` defaults to summary output (~300 tokens) |
 | Code Manipulation | \`kb_rename\`, \`kb_codemod\`, \`kb_diff_parse\`, \`kb_data_transform\` | Safe renames, transforms, diff parsing |
-| Context | \`kb_compact\`, \`kb_workset\`, \`kb_stash\`, \`kb_checkpoint\`, \`kb_parse_output\` | Manage working sets, save progress |
+| Context | \`kb_compact\`, \`kb_workset\`, \`kb_stash\`, \`kb_checkpoint\`, \`kb_parse_output\` | Manage working sets, save progress. \`compact\` accepts \`path\` for server-side file read |
 | FORGE | \`kb_forge_ground\`, \`kb_forge_classify\`, \`kb_evidence_map\`, \`kb_digest\`, \`kb_stratum_card\` | Quality gates, context compression |
 | Web & API | \`kb_web_fetch\`, \`kb_web_search\`, \`kb_http\` | Fetch pages, search web, test APIs |
 | Lanes | \`kb_lane\` | Isolated file copies for parallel exploration (create/list/status/diff/merge/discard) |
 | Git & Environment | \`kb_git_context\`, \`kb_process\`, \`kb_watch\`, \`kb_delegate\` | Git info, process management |
 | Utilities | \`kb_regex_test\`, \`kb_encode\`, \`kb_measure\`, \`kb_changelog\`, \`kb_schema_validate\`, \`kb_snippet\`, \`kb_env\`, \`kb_time\` | Regex, encoding, metrics, validation |
-| System | \`kb_status\`, \`kb_reindex\`, \`kb_health\`, \`kb_onboard\`, \`kb_graph\`, \`kb_queue\`, \`kb_replay_list\`, \`kb_replay_clear\` | Index management, health checks, knowledge graph |
+| System | \`kb_status\`, \`kb_reindex\`, \`kb_health\`, \`kb_guide\`, \`kb_onboard\`, \`kb_graph\`, \`kb_queue\`, \`kb_replay\` | Index management, health checks, tool discovery, knowledge graph |
+
+---
+
+## MANDATORY: Context Reduction Protocol
 
-### Search Modes
+**Every agent interaction MUST minimize context window usage.** Raw file reads waste tokens and degrade LLM output quality. Use these tools instead:
 
-The \`kb_search\` tool supports three search strategies via the \`search_mode\` parameter:
+### Decision Tree \u2014 How to Read Code
 
-- **\`hybrid\`** (default) \u2014 Vector similarity + full-text keyword search merged via Reciprocal Rank Fusion. Best for most queries.
-- **\`semantic\`** \u2014 Pure vector cosine similarity. Best for conceptual/meaning-based queries.
-- **\`keyword\`** \u2014 Full-text search only. Best for exact identifiers, function names, specific strings.
+\`\`\`
+Need to understand a file?
+\u251C\u2500 Just structure? \u2192 kb_file_summary (exports, imports, functions \u2014 ~50 tokens)
+\u251C\u2500 Specific section? \u2192 kb_compact({ path: "file.ts", query: "topic" }) \u2014 5-20x reduction
+\u251C\u2500 Multiple files? \u2192 kb_digest (multi-source compression \u2014 token-budgeted)
+\u251C\u2500 Repeated reference? \u2192 kb_stratum_card (T1/T2 card \u2014 10-100x reduction)
+\u2514\u2500 Full file needed? \u2192 ONLY as last resort, and compact it after reading
+\`\`\`
+
+### Rules
+1. **NEVER read a file >100 lines without compressing it first**
+2. **ALWAYS use \`kb_file_summary\` before \`read_file\`** \u2014 often the summary is sufficient
+3. **ALWAYS use \`kb_compact\` when you only need specific sections** of a file (use \`path\` param to read server-side)
+4. **Use \`kb_digest\` when synthesizing from 3+ sources** \u2014 don't accumulate raw text
+5. **Use \`kb_stratum_card\` for files you'll reference repeatedly** in a session
+
+---
+
+## MANDATORY: Memory Protocol
+
+**Every session MUST read and write persistent memory.** Without this, every conversation starts from zero.
+
+### Session Start (MUST do ALL of these)
+\`\`\`
+kb_status({})                                              # Verify KB is ready
+kb_list()                                                  # See what knowledge exists
+kb_search({ query: "SESSION CHECKPOINT", origin: "curated" })  # Resume prior work
+\`\`\`
+
+### During Session
+| Situation | Action |
+|-----------|--------|
+| Found a useful intermediate result | \`kb_stash({ key: "name", value: "data" })\` |
+| Completed a milestone | \`kb_checkpoint({ action: "save", name: "milestone" })\` |
+| Made an architecture decision | \`kb_remember({ title: "...", category: "decisions" })\` |
+| Discovered a pattern or convention | \`kb_remember({ title: "...", category: "patterns" })\` |
+| Found a non-obvious solution | \`kb_remember({ title: "...", category: "troubleshooting" })\` |
+| About to propose a new approach | \`kb_search({ query: "..." })\` \u2014 check if decided before |
+
+### Session End (MUST do this)
+\`\`\`
+kb_remember({
+  title: "Session checkpoint: <topic>",
+  content: "<what was done, decisions made, blockers, next steps>",
+  category: "conventions"
+})
+\`\`\`
+
+### Memory Decision Tree
+\`\`\`
+Is this data temporary (scratch, intermediate)?
+\u251C\u2500 Yes \u2192 kb_stash (session-scoped key-value)
+\u2514\u2500 No \u2192 Is it resumable progress?
+   \u251C\u2500 Yes \u2192 kb_checkpoint (session-scoped snapshot)
+   \u2514\u2500 No \u2192 kb_remember (permanent, survives reindex)
+       Categories: decisions | patterns | conventions | troubleshooting
+\`\`\`
 
-Additional filters: \`origin\` (\`indexed\`/\`curated\`/\`produced\`), \`category\`, \`content_type\`, \`tags\`, \`min_score\`.
+---
 
-### Session Protocol
+## MANDATORY: Search-Before-Act Protocol
+
+**NEVER write or modify code without first searching for context.**
 
-**Start of session:**
 \`\`\`
-kb_status({})
-kb_search({ query: "SESSION CHECKPOINT", origin: "curated" })
+# Before ANY code change:
+kb_search({ query: "<what you're about to change>" })     # Prior decisions?
+kb_scope_map({ task: "<description>" })                    # What files to read?
+kb_symbol({ name: "<key symbol>" })                        # Where is it defined/used?
 \`\`\`
 
-**During session:**
+If \`kb_search\` returns a prior decision about the topic, you MUST follow it or explicitly explain why you're deviating.
+
+---
+
+## MANDATORY: Validation Protocol
+
+**NEVER commit or present code without validation.**
+
 \`\`\`
-kb_search \u2192 kb_scope_map \u2192 kb_symbol \u2192 kb_trace       # Orient
-kb_check \u2192 kb_test_run                                  # Validate changes
-kb_remember                                             # Capture insights
+kb_check({})                                    # Typecheck + lint (tsc + biome)
+kb_test_run({})                                 # Run tests
+kb_blast_radius({ changed_files: ["..."] })     # Impact analysis
+kb_audit({})                                    # Unified project audit (structure, deps, patterns, health, dead symbols, entry points)
 \`\`\`
 
-**End of session:**
+---
+
+## FORGE Protocol (for complex tasks)
+
+For tasks touching 3+ files or involving architectural decisions:
+
 \`\`\`
-kb_remember({ title: "Session checkpoint: <topic>", content: "<summary>", category: "conventions" })
+kb_forge_classify({ task: "<description>" })        # Quick: Floor/Standard/Critical tier
+kb_forge_ground({ task: "<description>" })           # Full: scope + constraints + evidence
+kb_evidence_map({ claims: ["claim1", "claim2"] })   # Track verified vs assumed
 \`\`\`
 
-### Workflow Chains
+---
+
+## Search Modes
+
+| Mode | When | Example |
+|------|------|---------|
+| \`hybrid\` (default) | General queries | \`kb_search({ query: "error handling" })\` |
+| \`semantic\` | Conceptual/meaning-based | \`kb_search({ query: "retry with backoff", search_mode: "semantic" })\` |
+| \`keyword\` | Exact identifiers | \`kb_search({ query: "CircuitBreaker", search_mode: "keyword" })\` |
+
+Filters: \`origin\` (\`indexed\`/\`curated\`/\`produced\`), \`category\`, \`content_type\`, \`tags\`, \`min_score\`.
+
+---
+
+## Workflow Chains
 
 **Codebase onboarding:**
 \`\`\`
@@ -209,41 +244,65 @@ kb_onboard({ path: "." }) \u2192 kb_produce_knowledge({ path: "src/" }) \u2192 k
 
 **Planning a task:**
 \`\`\`
-kb_search({ query: "task keywords" }) \u2192 kb_scope_map({ task: "description" }) \u2192 kb_workset({ action: "save", name: "task", files: [...] })
+kb_search({ query: "task keywords" })
+\u2192 kb_scope_map({ task: "description" })
+\u2192 kb_file_summary for each file in scope
+\u2192 kb_compact({ path: "relevant-file.ts", query: "detail needed" }) for files needing detail
+\u2192 kb_workset({ action: "save", name: "task", files: [...] })
 \`\`\`
 
 **Bug investigation:**
 \`\`\`
-kb_parse_output({ output: "<error>" }) \u2192 kb_symbol({ name: "failingFn" }) \u2192 kb_trace({ symbol: "failingFn", direction: "backward" }) \u2192 kb_blast_radius({ changed_files: ["suspect.ts"] })
+kb_parse_output({ output: "<error>" })
+\u2192 kb_symbol({ name: "failingFn" })
+\u2192 kb_trace({ symbol: "failingFn", direction: "backward" })
+\u2192 kb_blast_radius({ changed_files: ["suspect.ts"] })
 \`\`\`
 
 **Safe refactor with lanes:**
 \`\`\`
-kb_lane({ action: "create", name: "refactor", files: [...] }) \u2192 [make changes] \u2192 kb_lane({ action: "diff", name: "refactor" }) \u2192 kb_check({}) \u2192 kb_lane({ action: "merge", name: "refactor" })
+kb_lane({ action: "create", name: "refactor", files: [...] })
+\u2192 [make changes]
+\u2192 kb_lane({ action: "diff", name: "refactor" })
+\u2192 kb_check({}) \u2192 kb_test_run({})
+\u2192 kb_lane({ action: "merge", name: "refactor" })
 \`\`\`
 
 **After making changes:**
 \`\`\`
-kb_blast_radius({ changed_files: ["src/file.ts"] }) \u2192 kb_check({}) \u2192 kb_test_run({}) \u2192 kb_reindex({}) \u2192 kb_remember(...)
+kb_blast_radius({ changed_files: ["src/file.ts"] })
+\u2192 kb_check({}) \u2192 kb_test_run({})
+\u2192 kb_reindex({})
+\u2192 kb_remember(...)
 \`\`\`
 
-### Knowledge Categories
+---
+
+## Knowledge Categories
+
+| Category | What to store |
+|----------|---------------|
+| \`decisions\` | Architecture choices, trade-offs, rejected alternatives |
+| \`patterns\` | Code patterns, naming conventions, structural patterns |
+| \`conventions\` | Session checkpoints, workflow conventions, team agreements |
+| \`troubleshooting\` | Non-obvious fixes, debugging strategies, workarounds |
 
-\`decisions\` | \`patterns\` | \`conventions\` | \`troubleshooting\`
+---
 
-### Core Rules
+## Core Rules Summary
 
-- Search KB for prior decisions before proposing new ones
-- Follow \`_Next:\` hints in tool responses for guided workflows
-- Use \`kb_check\` and \`kb_test_run\` to validate before committing
-- Use \`kb_remember\` to persist architecture decisions and lessons learned
-- Analysis results are auto-persisted as \`origin: "produced"\` entries
-`}async function P(e){const s=process.cwd(),i=t(s,"kb.config.json");if(o(i)&&!e.force){console.log("kb.config.json already exists. Use --force to overwrite.");return}a(i,`${JSON.stringify(h,null,2)}
-`,"utf-8"),console.log("  Created kb.config.json");const c=t(s,"curated");o(c)||(u(c,{recursive:!0}),console.log("  Created curated/"));const r=t(s,".gitignore");o(r)?m(r,"utf-8").includes(".kb-data")||(p(r,`
+1. **Search KB before proposing anything new** \u2014 prior decisions exist
+2. **Compress context aggressively** \u2014 \`file_summary\` \u2192 \`compact\` \u2192 \`digest\`
+3. **Use persistent memory** \u2014 \`remember\` decisions, \`stash\` temporary data
+4. **Validate before committing** \u2014 \`check\` + \`test_run\` + \`blast_radius\`
+5. **Follow \`_Next:\` hints** in tool responses for guided workflow
+6. **Use FORGE for complex tasks** \u2014 \`forge_classify\` \u2192 \`forge_ground\` \u2192 \`evidence_map\`
+`}async function R(o){const s=process.cwd(),c=e(s,"kb.config.json");if(t(c)&&!o.force){console.log("kb.config.json already exists. Use --force to overwrite.");return}r(c,`${JSON.stringify(C,null,2)}
+`,"utf-8"),console.log("  Created kb.config.json");const d=e(s,"curated");t(d)||(n(d,{recursive:!0}),console.log("  Created curated/"));const a=e(s,".gitignore");t(a)?v(a,"utf-8").includes(".kb-data")||(h(a,`
 # Knowledge base vector store
 .kb-data/
-`,"utf-8"),console.log("  Added .kb-data/ to .gitignore")):(a(r,`# Knowledge base vector store
+`,"utf-8"),console.log("  Added .kb-data/ to .gitignore")):(r(a,`# Knowledge base vector store
 .kb-data/
-`,"utf-8"),console.log("  Created .gitignore with .kb-data/"));const n=g(s),l=t(s,".vscode"),d=t(l,"mcp.json");o(l)&&!o(d)&&(a(d,`${JSON.stringify(f(n),null,2)}
-`,"utf-8"),console.log("  Created .vscode/mcp.json"));const b=t(s,".github"),k=t(b,"copilot-instructions.md");o(k)||(u(b,{recursive:!0}),a(k,y(n),"utf-8"),console.log("  Created .github/copilot-instructions.md"));const _=t(s,"AGENTS.md");o(_)||(a(_,w(n),"utf-8"),console.log("  Created AGENTS.md")),console.log(`
-Knowledge base initialized! Next steps:`),console.log("  kb reindex     Index your codebase"),console.log("  kb search      Search indexed content"),console.log("  kb serve       Start MCP server for IDE integration")}export{P as initProject};
+`,"utf-8"),console.log("  Created .gitignore with .kb-data/"));const i=w(s),l=e(s,".vscode"),k=e(l,"mcp.json");t(l)&&!t(k)&&(r(k,`${JSON.stringify(A(i),null,2)}
+`,"utf-8"),console.log("  Created .vscode/mcp.json"));const u=e(s,".github"),b=e(u,"copilot-instructions.md");t(b)||(n(u,{recursive:!0}),r(b,T(i),"utf-8"),console.log("  Created .github/copilot-instructions.md"));const m=e(s,"AGENTS.md");t(m)||(r(m,P(i),"utf-8"),console.log("  Created AGENTS.md"));const _=e(s,"skills","knowledge-base"),p=e(_,"SKILL.md");if(!t(p)){const f=S(x(import.meta.url)),g=e(f,"..","..","..","skills","knowledge-base","SKILL.md");t(g)&&(n(_,{recursive:!0}),y(g,p),console.log("  Created skills/knowledge-base/SKILL.md"))}console.log(`
+Knowledge base initialized! Next steps:`),console.log("  kb reindex     Index your codebase"),console.log("  kb search      Search indexed content"),console.log("  kb serve       Start MCP server for IDE integration")}export{R as initProject};

package/packages/cli/dist/commands/knowledge.js

@@ -1 +1 @@
-import{compact as m}from"../../../tools/dist/index.js";import{ctx as i}from"../context.js";import{extractNumFlag as p,extractStrFlag as c,readStdin as l,splitCsv as d}from"../helpers.js";const f=[{name:"remember",description:"Store curated knowledge",usage:"kb remember <title> --category <cat> [--tags tag1,tag2]",run:async t=>{const o=c(t,"--category","").trim(),a=d(c(t,"--tags","")),e=t.shift()?.trim()??"",r=await l(),n=r.trim().length>0?r:t.join(" ").trim();(!e||!o||!n.trim())&&(console.error("Usage: kb remember <title> --category <cat> [--tags tag1,tag2]"),process.exit(1));const{curated:s}=await i(),g=await s.remember(e,n,o,a);console.log("Stored curated entry"),console.log(`  Path: ${g.path}`),console.log(`  Category: ${o}`),a.length>0&&console.log(`  Tags: ${a.join(", ")}`)}},{name:"forget",description:"Remove a curated entry",usage:"kb forget <path> --reason <reason>",run:async t=>{const o=c(t,"--reason","").trim(),a=t.shift()?.trim()??"";(!a||!o)&&(console.error("Usage: kb forget <path> --reason <reason>"),process.exit(1));const{curated:e}=await i(),r=await e.forget(a,o);console.log(`Removed curated entry: ${r.path}`)}},{name:"read",description:"Read a curated entry",usage:"kb read <path>",run:async t=>{const o=t.shift()?.trim()??"";o||(console.error("Usage: kb read <path>"),process.exit(1));const{curated:a}=await i(),e=await a.read(o);console.log(e.title),console.log("\u2500".repeat(60)),console.log(`Path: ${e.path}`),console.log(`Category: ${e.category}`),console.log(`Version: ${e.version}`),console.log(`Tags: ${e.tags.length>0?e.tags.join(", "):"None"}`),console.log(""),console.log(e.content)}},{name:"list",description:"List curated entries",usage:"kb list [--category <cat>] [--tag <tag>]",run:async t=>{const o=c(t,"--category","").trim()||void 0,a=c(t,"--tag","").trim()||void 0,{curated:e}=await i(),r=await e.list({category:o,tag:a});if(r.length===0){console.log("No curated entries found.");return}console.log(`Curated entries (${r.length})`),console.log("\u2500".repeat(60));for(const n of r){console.log(n.path),console.log(`  ${n.title}`),console.log(`  Category: ${n.category} | Version: ${n.version}`),console.log(`  Tags: ${n.tags.length>0?n.tags.join(", "):"None"}`);const s=n.contentPreview.replace(/\s+/g," ").trim();s&&console.log(`  Preview: ${s}`),console.log("")}}},{name:"update",description:"Update a curated entry",usage:"kb update <path> --reason <reason>",run:async t=>{const o=c(t,"--reason","").trim(),a=t.shift()?.trim()??"",e=await l();(!a||!o||!e.trim())&&(console.error("Usage: kb update <path> --reason <reason>"),process.exit(1));const{curated:r}=await i(),n=await r.update(a,e,o);console.log("Updated curated entry"),console.log(`  Path: ${n.path}`),console.log(`  Version: ${n.version}`)}},{name:"compact",description:"Compress text for context",usage:"kb compact <query> [--max-chars N] [--segmentation paragraph|sentence|line]",run:async t=>{const o=p(t,"--max-chars",3e3),a=c(t,"--segmentation","paragraph"),e=t.join(" ").trim(),r=await l();(!e||!r.trim())&&(console.error("Usage: kb compact <query> [--max-chars N] [--segmentation paragraph|sentence|line]"),process.exit(1));const{embedder:n}=await i(),s=await m(n,{text:r,query:e,maxChars:o,segmentation:a});console.log(`Compressed ${s.originalChars} chars to ${s.compressedChars} chars`),console.log(`Ratio: ${(s.ratio*100).toFixed(1)}% | Segments: ${s.segmentsKept}/${s.segmentsTotal}`),console.log(""),console.log(s.text)}}];export{f as knowledgeCommands};
+import{compact as m}from"../../../tools/dist/index.js";import{ctx as l}from"../context.js";import{extractNumFlag as p,extractStrFlag as c,readStdin as g,splitCsv as d}from"../helpers.js";const y=[{name:"remember",description:"Store curated knowledge",usage:"kb remember <title> --category <cat> [--tags tag1,tag2]",run:async e=>{const a=c(e,"--category","").trim(),o=d(c(e,"--tags","")),t=e.shift()?.trim()??"",r=await g(),n=r.trim().length>0?r:e.join(" ").trim();(!t||!a||!n.trim())&&(console.error("Usage: kb remember <title> --category <cat> [--tags tag1,tag2]"),process.exit(1));const{curated:i}=await l(),s=await i.remember(t,n,a,o);console.log("Stored curated entry"),console.log(`  Path: ${s.path}`),console.log(`  Category: ${a}`),o.length>0&&console.log(`  Tags: ${o.join(", ")}`)}},{name:"forget",description:"Remove a curated entry",usage:"kb forget <path> --reason <reason>",run:async e=>{const a=c(e,"--reason","").trim(),o=e.shift()?.trim()??"";(!o||!a)&&(console.error("Usage: kb forget <path> --reason <reason>"),process.exit(1));const{curated:t}=await l(),r=await t.forget(o,a);console.log(`Removed curated entry: ${r.path}`)}},{name:"read",description:"Read a curated entry",usage:"kb read <path>",run:async e=>{const a=e.shift()?.trim()??"";a||(console.error("Usage: kb read <path>"),process.exit(1));const{curated:o}=await l(),t=await o.read(a);console.log(t.title),console.log("\u2500".repeat(60)),console.log(`Path: ${t.path}`),console.log(`Category: ${t.category}`),console.log(`Version: ${t.version}`),console.log(`Tags: ${t.tags.length>0?t.tags.join(", "):"None"}`),console.log(""),console.log(t.content)}},{name:"list",description:"List curated entries",usage:"kb list [--category <cat>] [--tag <tag>]",run:async e=>{const a=c(e,"--category","").trim()||void 0,o=c(e,"--tag","").trim()||void 0,{curated:t}=await l(),r=await t.list({category:a,tag:o});if(r.length===0){console.log("No curated entries found.");return}console.log(`Curated entries (${r.length})`),console.log("\u2500".repeat(60));for(const n of r){console.log(n.path),console.log(`  ${n.title}`),console.log(`  Category: ${n.category} | Version: ${n.version}`),console.log(`  Tags: ${n.tags.length>0?n.tags.join(", "):"None"}`);const i=n.contentPreview.replace(/\s+/g," ").trim();i&&console.log(`  Preview: ${i}`),console.log("")}}},{name:"update",description:"Update a curated entry",usage:"kb update <path> --reason <reason>",run:async e=>{const a=c(e,"--reason","").trim(),o=e.shift()?.trim()??"",t=await g();(!o||!a||!t.trim())&&(console.error("Usage: kb update <path> --reason <reason>"),process.exit(1));const{curated:r}=await l(),n=await r.update(o,t,a);console.log("Updated curated entry"),console.log(`  Path: ${n.path}`),console.log(`  Version: ${n.version}`)}},{name:"compact",description:"Compress text for context",usage:"kb compact <query> [--path <file>] [--max-chars N] [--segmentation paragraph|sentence|line]",run:async e=>{const a=p(e,"--max-chars",3e3),o=c(e,"--path","").trim()||void 0,t=c(e,"--segmentation","paragraph"),r=e.join(" ").trim(),n=o?void 0:await g();(!r||!o&&!n?.trim())&&(console.error("Usage: kb compact <query> --path <file>  OR  cat file | kb compact <query>"),process.exit(1));const{embedder:i}=await l(),s=await m(i,{text:n,path:o,query:r,maxChars:a,segmentation:t});console.log(`Compressed ${s.originalChars} chars to ${s.compressedChars} chars`),console.log(`Ratio: ${(s.ratio*100).toFixed(1)}% | Segments: ${s.segmentsKept}/${s.segmentsTotal}`),console.log(""),console.log(s.text)}}];export{y as knowledgeCommands};

package/packages/cli/dist/commands/system.js

@@ -1,4 +1,7 @@
-import{fork as f}from"node:child_process";import{dirname as m,resolve as h}from"node:path";import{fileURLToPath as g}from"node:url";import{batch as y,check as x,health as k,replayClear as w,replayList as $,replayTrim as b}from"../../../tools/dist/index.js";import{ctx as p}from"../context.js";import{executeCliBatchOperation as I,extractStrFlag as a,parseBatchPayload as R,printCheckResult as N,readInput as T}from"../helpers.js";const C=m(g(import.meta.url)),E=[{name:"status",description:"Show knowledge base index status and statistics",run:async()=>{const{store:e}=await p(),s=await e.getStats(),t=await e.listSourcePaths();console.log("Knowledge Base Status"),console.log("\u2500".repeat(40)),console.log(`  Records:  ${s.totalRecords}`),console.log(`  Files:    ${s.totalFiles}`),console.log(`  Indexed:  ${s.lastIndexedAt??"Never"}`),console.log(`  Backend:  ${s.storeBackend}`),console.log(`  Model:    ${s.embeddingModel}`),console.log(""),console.log("Content Types:");for(const[n,o]of Object.entries(s.contentTypeBreakdown))console.log(`  ${n}: ${o}`);if(t.length>0){console.log(""),console.log(`Files (${t.length} total):`);for(const n of t.slice(0,20))console.log(`  ${n}`);t.length>20&&console.log(`  ... and ${t.length-20} more`)}}},{name:"reindex",description:"Re-index the knowledge base from configured sources",usage:"kb reindex [--full]",run:async e=>{const s=e.includes("--full"),{store:t,indexer:n,curated:o,config:i}=await p();console.log("Indexing sources...");const l=r=>{r.phase==="chunking"&&r.currentFile&&process.stdout.write(`\r  [${r.filesProcessed+1}/${r.filesTotal}] ${r.currentFile}`),r.phase==="done"&&process.stdout.write(`
-`)};let c;s?(console.log("Dropping existing index for full reindex..."),c=await n.reindexAll(i,l)):c=await n.index(i,l),console.log(`Done: ${c.filesProcessed} files, ${c.chunksCreated} chunks in ${(c.durationMs/1e3).toFixed(1)}s`),console.log("Building FTS index..."),await t.createFtsIndex(),console.log("Re-indexing curated entries...");const d=await o.reindexAll();console.log(`Curated: ${d.indexed} entries restored`)}},{name:"serve",description:"Start the MCP server (stdio or HTTP)",usage:"kb serve [--transport stdio|http] [--port N]",run:async e=>{const s=h(C,"..","..","..","server","dist","index.js"),t=a(e,"--transport","stdio"),n=a(e,"--port","3210"),o=f(s,[],{stdio:t==="stdio"?["pipe","pipe","inherit","ipc"]:"inherit",env:{...process.env,KB_TRANSPORT:t,KB_PORT:n}});t==="stdio"&&o.stdin&&o.stdout&&(process.stdin.pipe(o.stdin),o.stdout.pipe(process.stdout)),o.on("exit",i=>process.exit(i??0)),process.on("SIGINT",()=>o.kill("SIGINT")),process.on("SIGTERM",()=>o.kill("SIGTERM")),await new Promise(()=>{})}},{name:"init",description:"Initialize a knowledge base in the current directory",usage:"kb init [--force]",run:async e=>{const s=e.includes("--force"),{initProject:t}=await import("./init.js");await t({force:s})}},{name:"check",description:"Run incremental typecheck and lint",usage:"kb check [--cwd <dir>] [--files f1,f2] [--skip-types] [--skip-lint]",run:async e=>{const s=a(e,"--cwd","").trim()||void 0,n=a(e,"--files","").split(",").map(c=>c.trim()).filter(Boolean);let o=!1;e.includes("--skip-types")&&(e.splice(e.indexOf("--skip-types"),1),o=!0);let i=!1;e.includes("--skip-lint")&&(e.splice(e.indexOf("--skip-lint"),1),i=!0);const l=await x({cwd:s,files:n.length>0?n:void 0,skipTypes:o,skipLint:i});N(l),l.passed||(process.exitCode=1)}},{name:"batch",description:"Execute built-in operations from JSON input",usage:"kb batch [--file path] [--concurrency N]",run:async e=>{const s=a(e,"--file","").trim()||void 0,t=(()=>{const r=e.indexOf("--concurrency");if(r===-1||r+1>=e.length)return 0;const u=Number.parseInt(e.splice(r,2)[1],10);return Number.isNaN(u)?0:u})(),n=await T(s);n.trim()||(console.error("Usage: kb batch [--file path] [--concurrency N]"),process.exit(1));const o=R(n),i=t>0?t:o.concurrency,c=o.operations.some(r=>r.type!=="check")?await p():null,d=await y(o.operations,async r=>I(r,c),{concurrency:i});console.log(JSON.stringify(d,null,2)),d.some(r=>r.status==="error")&&(process.exitCode=1)}},{name:"health",description:"Run project health checks on the current directory",usage:"kb health [path]",run:async e=>{const s=e.shift(),t=k(s);console.log(`Project Health: ${t.path}`),console.log("\u2500".repeat(50));for(const n of t.checks){const o=n.status==="pass"?"+":n.status==="warn"?"~":"X";console.log(`  [${o}] ${n.name}: ${n.message}`)}console.log("\u2500".repeat(50)),console.log(`Score: ${t.score}% \u2014 ${t.summary}`)}},{name:"replay",description:"Show recent tool invocation audit trail",usage:"kb replay [--last N] [--tool <name>] [--source mcp|cli]",run:async e=>{const s=Number.parseInt(e[e.indexOf("--last")+1],10)||20,t=e.includes("--tool")?e[e.indexOf("--tool")+1]:void 0,n=e.includes("--source")?e[e.indexOf("--source")+1]:void 0,o=$({last:s,tool:t,source:n});if(o.length===0){console.log("No replay entries. Activity is logged when tools are invoked.");return}console.log(`Replay Log (${o.length} entries)
-`);for(const i of o){const l=i.ts.split("T")[1]?.split(".")[0]??i.ts,c=i.status==="ok"?"\u2713":"\u2717";console.log(`${l} ${c} ${i.tool} (${i.durationMs}ms) [${i.source}]`),console.log(`  in:  ${i.input}`),console.log(`  out: ${i.output}`)}b()}},{name:"replay-clear",description:"Clear the replay audit trail",run:async()=>{w(),console.log("Replay log cleared.")}},{name:"tui",description:"Launch interactive terminal dashboard (human monitoring)",run:async()=>{try{const{launch:e}=await import("../../../tui/dist/index.js"),{store:s,embedder:t,config:n}=await p();e({store:s,embedder:t,config:n})}catch(e){throw e.code==="ERR_MODULE_NOT_FOUND"&&(console.error(`TUI requires ink and react. Install them with:
+import{fork as m}from"node:child_process";import{dirname as f,resolve as g}from"node:path";import{fileURLToPath as h}from"node:url";import{audit as y,batch as x,check as k,guide as w,health as $,replayClear as b,replayList as N,replayTrim as R}from"../../../tools/dist/index.js";import{ctx as u}from"../context.js";import{executeCliBatchOperation as I,extractStrFlag as d,parseBatchPayload as v,printCheckResult as C,readInput as T}from"../helpers.js";const S=f(h(import.meta.url)),E=[{name:"status",description:"Show knowledge base index status and statistics",run:async()=>{const{store:e}=await u(),s=await e.getStats(),t=await e.listSourcePaths();console.log("Knowledge Base Status"),console.log("\u2500".repeat(40)),console.log(`  Records:  ${s.totalRecords}`),console.log(`  Files:    ${s.totalFiles}`),console.log(`  Indexed:  ${s.lastIndexedAt??"Never"}`),console.log(`  Backend:  ${s.storeBackend}`),console.log(`  Model:    ${s.embeddingModel}`),console.log(""),console.log("Content Types:");for(const[n,o]of Object.entries(s.contentTypeBreakdown))console.log(`  ${n}: ${o}`);if(t.length>0){console.log(""),console.log(`Files (${t.length} total):`);for(const n of t.slice(0,20))console.log(`  ${n}`);t.length>20&&console.log(`  ... and ${t.length-20} more`)}}},{name:"reindex",description:"Re-index the knowledge base from configured sources",usage:"kb reindex [--full]",run:async e=>{const s=e.includes("--full"),{store:t,indexer:n,curated:o,config:i}=await u();console.log("Indexing sources...");const l=c=>{c.phase==="chunking"&&c.currentFile&&process.stdout.write(`\r  [${c.filesProcessed+1}/${c.filesTotal}] ${c.currentFile}`),c.phase==="done"&&process.stdout.write(`
+`)};let r;s?(console.log("Dropping existing index for full reindex..."),r=await n.reindexAll(i,l)):r=await n.index(i,l),console.log(`Done: ${r.filesProcessed} files, ${r.chunksCreated} chunks in ${(r.durationMs/1e3).toFixed(1)}s`),console.log("Building FTS index..."),await t.createFtsIndex(),console.log("Re-indexing curated entries...");const a=await o.reindexAll();console.log(`Curated: ${a.indexed} entries restored`)}},{name:"serve",description:"Start the MCP server (stdio or HTTP)",usage:"kb serve [--transport stdio|http] [--port N]",run:async e=>{const s=g(S,"..","..","..","server","dist","index.js"),t=d(e,"--transport","stdio"),n=d(e,"--port","3210"),o=m(s,[],{stdio:t==="stdio"?["pipe","pipe","inherit","ipc"]:"inherit",env:{...process.env,KB_TRANSPORT:t,KB_PORT:n}});t==="stdio"&&o.stdin&&o.stdout&&(process.stdin.pipe(o.stdin),o.stdout.pipe(process.stdout)),o.on("exit",i=>process.exit(i??0)),process.on("SIGINT",()=>o.kill("SIGINT")),process.on("SIGTERM",()=>o.kill("SIGTERM")),await new Promise(()=>{})}},{name:"init",description:"Initialize a knowledge base in the current directory",usage:"kb init [--force]",run:async e=>{const s=e.includes("--force"),{initProject:t}=await import("./init.js");await t({force:s})}},{name:"check",description:"Run incremental typecheck and lint",usage:"kb check [--cwd <dir>] [--files f1,f2] [--skip-types] [--skip-lint] [--detail summary|errors|full]",run:async e=>{const s=d(e,"--cwd","").trim()||void 0,t=d(e,"--files",""),n=d(e,"--detail","full")||"full",o=t.split(",").map(a=>a.trim()).filter(Boolean);let i=!1;e.includes("--skip-types")&&(e.splice(e.indexOf("--skip-types"),1),i=!0);let l=!1;e.includes("--skip-lint")&&(e.splice(e.indexOf("--skip-lint"),1),l=!0);const r=await k({cwd:s,files:o.length>0?o:void 0,skipTypes:i,skipLint:l,detail:n});C(r),r.passed||(process.exitCode=1)}},{name:"batch",description:"Execute built-in operations from JSON input",usage:"kb batch [--file path] [--concurrency N]",run:async e=>{const s=d(e,"--file","").trim()||void 0,t=(()=>{const c=e.indexOf("--concurrency");if(c===-1||c+1>=e.length)return 0;const p=Number.parseInt(e.splice(c,2)[1],10);return Number.isNaN(p)?0:p})(),n=await T(s);n.trim()||(console.error("Usage: kb batch [--file path] [--concurrency N]"),process.exit(1));const o=v(n),i=t>0?t:o.concurrency,r=o.operations.some(c=>c.type!=="check")?await u():null,a=await x(o.operations,async c=>I(c,r),{concurrency:i});console.log(JSON.stringify(a,null,2)),a.some(c=>c.status==="error")&&(process.exitCode=1)}},{name:"health",description:"Run project health checks on the current directory",usage:"kb health [path]",run:async e=>{const s=e.shift(),t=$(s);console.log(`Project Health: ${t.path}`),console.log("\u2500".repeat(50));for(const n of t.checks){const o=n.status==="pass"?"+":n.status==="warn"?"~":"X";console.log(`  [${o}] ${n.name}: ${n.message}`)}console.log("\u2500".repeat(50)),console.log(`Score: ${t.score}% \u2014 ${t.summary}`)}},{name:"audit",description:"Run a unified project audit (structure, deps, patterns, health, dead symbols, check)",usage:"kb audit [path] [--checks structure,dependencies,patterns,health,dead_symbols,check,entry_points] [--detail summary|full]",run:async e=>{const{store:s,embedder:t}=await u(),n=d(e,"--detail","summary")||"summary",o=d(e,"--checks",""),i=o?o.split(",").map(a=>a.trim()):void 0,l=e.shift()||".",r=await y(s,t,{path:l,checks:i,detail:n});if(r.ok){if(console.log(r.summary),r.next&&r.next.length>0){console.log(`
+Suggested next steps:`);for(const a of r.next)console.log(`  \u2192 ${a.tool}: ${a.reason}`)}}else console.error(r.error?.message??"Audit failed"),process.exitCode=1}},{name:"guide",description:"Tool discovery \u2014 recommend KB tools for a given goal",usage:"kb guide <goal> [--max N]",run:async e=>{const s=e.indexOf("--max");let t=5;s!==-1&&s+1<e.length&&(t=Number.parseInt(e.splice(s,2)[1],10)||5);const n=e.join(" ").trim();n||(console.error("Usage: kb guide <goal> [--max N]"),console.error('Example: kb guide "audit this project"'),process.exit(1));const o=w(n,t);console.log(`Workflow: ${o.workflow}`),console.log(`  ${o.description}
+`),console.log("Recommended tools:");for(const i of o.tools){const l=i.suggestedArgs?` ${JSON.stringify(i.suggestedArgs)}`:"";console.log(`  ${i.order}. ${i.tool} \u2014 ${i.reason}${l}`)}o.alternativeWorkflows.length>0&&console.log(`
+Alternatives: ${o.alternativeWorkflows.join(", ")}`)}},{name:"replay",description:"Show recent tool invocation audit trail",usage:"kb replay [--last N] [--tool <name>] [--source mcp|cli]",run:async e=>{const s=Number.parseInt(e[e.indexOf("--last")+1],10)||20,t=e.includes("--tool")?e[e.indexOf("--tool")+1]:void 0,n=e.includes("--source")?e[e.indexOf("--source")+1]:void 0,o=N({last:s,tool:t,source:n});if(o.length===0){console.log("No replay entries. Activity is logged when tools are invoked.");return}console.log(`Replay Log (${o.length} entries)
+`);for(const i of o){const l=i.ts.split("T")[1]?.split(".")[0]??i.ts,r=i.status==="ok"?"\u2713":"\u2717";console.log(`${l} ${r} ${i.tool} (${i.durationMs}ms) [${i.source}]`),console.log(`  in:  ${i.input}`),console.log(`  out: ${i.output}`)}R()}},{name:"replay-clear",description:"Clear the replay audit trail",run:async()=>{b(),console.log("Replay log cleared.")}},{name:"tui",description:"Launch interactive terminal dashboard (human monitoring)",run:async()=>{try{const{launch:e}=await import("../../../tui/dist/index.js"),{store:s,embedder:t,config:n}=await u();e({store:s,embedder:t,config:n})}catch(e){throw e.code==="ERR_MODULE_NOT_FOUND"&&(console.error(`TUI requires ink and react. Install them with:
   pnpm add -D ink react @types/react`),process.exit(1)),e}}}];export{E as systemCommands};