@vpxa/kb 0.1.15 → 0.1.16

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

@@ -1,226 +1,143 @@
-function e(e,t){let n=e=>e;return`# ${e} — Copilot Instructions
+function e(e,t){return`# ${e} — 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.
+This project has an MCP server (\`${t}\`) providing 64 tools for search, analysis, memory, and validation.
+**These tools REPLACE most native IDE tools.** You MUST use them.
 
-## Mandatory Rules
+## Step 0: Load KB Tools
 
-### 1. ALWAYS search before acting
-Before writing or modifying code, you MUST recall prior decisions and understand the affected area:
+Before doing ANYTHING else, load the KB MCP tools. They are deferred — you must load them first.
+Search for tools matching the server name (e.g. \`knowledge-bas\`):
 \`\`\`
-${n(`search`)}({ query: "<task keywords>" })
-${n(`scope_map`)}({ task: "<what you are doing>" })
+tool_search_tool_regex({ pattern: "knowledge-bas" })   // loads all 64 KB tools
 \`\`\`
+Once loaded, KB tools appear as \`mcp_<server>_<tool>\` (e.g. \`mcp_knowledge-bas_search\`).
 
-### 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:
+## FORBIDDEN: Native Tools When KB Alternative Exists
 
-| Situation | Tool | Why |
-|-----------|------|-----|
-| Need relevant sections of a large file | \`${n(`compact`)}\` | Extracts only semantically relevant chunks — 5-20x reduction |
-| Need to summarize multiple sources | \`${n(`digest`)}\` | Compresses multiple text blocks into a token-budgeted summary |
-| Need a quick structural overview of a file | \`${n(`file_summary`)}\` | Returns exports, imports, functions without reading the full file |
-| Need a reusable context card | \`${n(`stratum_card`)}\` | Generates T1/T2 cards — 10-100x token reduction |
+| NEVER use this | USE THIS KB TOOL INSTEAD | Why |
+|---|---|---|
+| \`read_file\` to understand a file | \`file_summary({ path })\` | Structure, exports, imports — 10x fewer tokens |
+| \`read_file\` to find specific code | \`compact({ path, query })\` | Server-side read + semantic extract — 5-20x reduction |
+| Multiple \`read_file\` calls | \`digest({ sources })\` | Compresses multiple files into token-budgeted summary |
+| \`grep_search\` / \`semantic_search\` | \`search({ query })\` | Hybrid search across all indexed + curated content |
+| \`grep_search\` for a symbol name | \`symbol({ name })\` | Definition + references with scope and call context |
+| \`run_in_terminal\` for find/grep | \`find({ pattern })\` or \`search()\` | No shell needed, richer results |
+| \`run_in_terminal\` for tsc/lint | \`check({})\` | Typecheck + lint combined, summary output |
+| \`run_in_terminal\` for test | \`test_run({})\` | Run tests with structured output |
+| Manual code tracing | \`trace({ symbol, direction })\` | AST call-graph traversal |
+| Line counting / wc | \`measure({ path })\` | Lines, functions, cognitive complexity |
 
-**Example — reading a 400-line file:**
-\`\`\`
-# BAD: read_file entire file (wastes ~3000 tokens)
-# GOOD: get structure first, then compact only what you need
-${n(`file_summary`)}({ path: "src/http-client.ts" })
-${n(`compact`)}({ path: "src/http-client.ts", query: "retry logic" })
-\`\`\`
-
-### 3. ALWAYS use persistent memory
-- **Start of session**: Read prior knowledge with \`${n(`list`)}()\` and \`${n(`search`)}({ query: "SESSION CHECKPOINT", origin: "curated" })\`
-- **During session**: Use \`${n(`stash`)}\` for temporary working data, \`${n(`checkpoint`)}\` to save progress
-- **End of session**: MUST call \`${n(`remember`)}\` to persist decisions, patterns, and lessons learned
-- **Before proposing a new approach**: MUST \`${n(`search`)}\` to check if a decision already exists
-
-| Tool | When | Persistence |
-|------|------|-------------|
-| \`${n(`stash`)}\` | Temporary data within a session (intermediate results, scratch notes) | Session only |
-| \`${n(`checkpoint`)}\` | Save/restore session progress (resumable work) | Session only |
-| \`${n(`remember`)}\` | Architecture decisions, conventions, patterns, troubleshooting | Permanent (survives reindex) |
+**\`read_file\` is ONLY acceptable when you need exact line content FOR EDITING (before \`replace_string_in_file\`).**
+Even then, use \`file_summary\` first to identify which lines to read.
 
-### 4. ALWAYS validate before committing
-\`\`\`
-${n(`check`)}({})                    # Typecheck + lint (returns summary by default)
-${n(`test_run`)}({})                 # Run tests
-${n(`blast_radius`)}({ changed_files: ["..."] })  # Impact analysis
-${n(`audit`)}({})                    # Unified project audit with score and recommendations
-\`\`\`
+## Core Rules
 
-### 5. Use FORGE for complex tasks
-For tasks involving multiple files or architectural decisions:
-\`\`\`
-${n(`forge_classify`)}({ task: "<description>" })   # Classify complexity tier
-${n(`forge_ground`)}({ task: "<description>" })     # Full analysis: scope + constraints + evidence
-${n(`evidence_map`)}({ claims: [...] })             # Track verified vs assumed claims
-\`\`\`
+1. **Search before acting** — \`search({ query })\` then \`scope_map({ task })\` before ANY code change. If a prior decision exists, follow it.
+2. **Compress, don't read** — \`file_summary\` → \`compact\` → \`digest\`. NEVER raw-read a file to "understand" it.
+3. **Remember** — \`search({ query: "SESSION CHECKPOINT", origin: "curated" })\` at session start. \`remember()\` decisions at session end.
+4. **Validate** — \`check({})\` + \`test_run({})\` before presenting changes. \`blast_radius({ changed_files })\` for impact.
+5. **Lifecycle** — Check \`status({})\` first. If onboard not run, run \`onboard({ path: "." })\`. After implementation, \`reindex({})\` + \`produce_knowledge({})\`. At session end, \`remember()\` checkpoint.
 
-## Quick Workflow
-
-\`\`\`
-# 1. Orient
-${n(`search`)}({ query: "task keywords" })
-${n(`scope_map`)}({ task: "what you are doing" })
-
-# 2. Read efficiently (NEVER raw-read large files)
-${n(`file_summary`)}({ path: "relevant-file.ts" })
-${n(`compact`)}({ path: "relevant-file.ts", query: "specific concern" })
-
-# 3. Do the work
-
-# 4. Validate
-${n(`check`)}({})
-${n(`test_run`)}({})
-
-# 5. Persist
-${n(`remember`)}({ title: "What I learned", content: "...", category: "decisions" })
-\`\`\`
+## Custom Agents
 
-## Context Budget Rules
+This project has specialized agents in \`.github/agents/\`. Use them instead of built-in modes:
+- **Planner** — for planning and research before implementation
+- **Implementer** — for coding tasks following TDD practices
+- **Researcher** — for deep investigation and context gathering
+- **Explorer** — for rapid codebase navigation
 
-- **Prefer \`${n(`file_summary`)}\` over \`read_file\`** for understanding file structure
-- **Prefer \`${n(`compact`)}\` over full file reads** when you need specific sections (use \`path\` param to avoid read_file round-trip)
-- **Prefer \`${n(`search`)}\` over \`grep_search\`** for semantic/conceptual queries
-- **Prefer \`${n(`symbol`)}\` over manual grep** for finding definitions and references
-- **Use \`${n(`digest`)}\`** when combining information from 3+ sources
-- **Use \`${n(`stratum_card`)}\`** to create reusable compressed context for repeated reference
-`}function t(e,t){let n=e=>e;return`# ${e} — Agent Instructions
+Check \`.github/agents/\` for the full list of available agents.
+`}function t(e,t){return`# ${e} — Agent Instructions
 
-## KB Knowledge Base
+## KB MCP Server (\`${t}\`)
 
-This project has a **@vpxa/kb** MCP server providing search, analysis, memory, and developer tools.
+64 tools for search, code analysis, persistent memory, validation, and context compression.
+Load them: \`tool_search_tool_regex({ pattern: "knowledge-bas" })\`
 
 ### Skills Reference
 
-| Context | Skill | Details |
-|---------|-------|--------|
-| KB search, analysis, memory | \`kb\` | See [.github/skills/knowledge-base/SKILL.md](.github/skills/knowledge-base/SKILL.md) or run \`${n(`status`)}({})\` |
-| Brainstorming & design | \`brainstorming\` | See [.github/skills/brainstorming/SKILL.md](.github/skills/brainstorming/SKILL.md) |
+| Context | Skill | Load when |
+|---------|-------|----------|
+| KB search, analysis, memory | \`knowledge-base\` | **Always load at session start.** Tool signatures, workflows, session protocol. |
+| Brainstorming & design | \`brainstorming\` | Before any creative/design work — new features, components, behavior changes. |
+| Session context preservation | \`session-handoff\` | Context window filling up, session ending, or major milestone completed. |
+| Requirements scoring | \`requirements-clarity\` | Before planning vague or complex features — score 0-100 until \u2265 90. |
+| Engineering lessons | \`lesson-learned\` | After completing work — extract principles from git diffs. |
+| Architecture diagrams | \`c4-architecture\` | When documenting or reviewing architecture — C4 Mermaid diagrams. |
+| Architecture decisions | \`adr-skill\` | When making non-trivial technical decisions — executable ADRs. |
 
-### Available Tool Categories
+### Tool Categories
 
 | Category | Tools | Purpose |
 |----------|-------|---------|
-| Search & Discovery | \`${n(`search`)}\`, \`${n(`find`)}\`, \`${n(`symbol`)}\`, \`${n(`trace`)}\`, \`${n(`scope_map`)}\`, \`${n(`lookup`)}\`, \`${n(`dead_symbols`)}\`, \`${n(`file_summary`)}\` | Find code, symbols, data flow, reading plans |
-| Code Analysis | \`${n(`analyze_structure`)}\`, \`${n(`analyze_dependencies`)}\`, \`${n(`analyze_symbols`)}\`, \`${n(`analyze_patterns`)}\`, \`${n(`analyze_entry_points`)}\`, \`${n(`analyze_diagram`)}\`, \`${n(`blast_radius`)}\` | Structure, deps, patterns, impact, diagrams |
-| Knowledge | \`${n(`remember`)}\`, \`${n(`read`)}\`, \`${n(`update`)}\`, \`${n(`forget`)}\`, \`${n(`list`)}\`, \`${n(`produce_knowledge`)}\` | Persistent cross-session memory |
-| Execution | \`${n(`check`)}\`, \`${n(`test_run`)}\`, \`${n(`eval`)}\`, \`${n(`batch`)}\`, \`${n(`audit`)}\` | Typecheck, lint, test, run code, unified audit. \`check\` defaults to summary output (~300 tokens) |
-| Code Manipulation | \`${n(`rename`)}\`, \`${n(`codemod`)}\`, \`${n(`diff_parse`)}\`, \`${n(`data_transform`)}\` | Safe renames, transforms, diff parsing |
-| Context | \`${n(`compact`)}\`, \`${n(`workset`)}\`, \`${n(`stash`)}\`, \`${n(`checkpoint`)}\`, \`${n(`parse_output`)}\` | Manage working sets, save progress. \`compact\` accepts \`path\` for server-side file read |
-| FORGE | \`${n(`forge_ground`)}\`, \`${n(`forge_classify`)}\`, \`${n(`evidence_map`)}\`, \`${n(`digest`)}\`, \`${n(`stratum_card`)}\` | Quality gates, context compression |
-| Web & API | \`${n(`web_fetch`)}\`, \`${n(`web_search`)}\`, \`${n(`http`)}\` | Fetch pages, search web, test APIs |
-| Lanes | \`${n(`lane`)}\` | Isolated file copies for parallel exploration (create/list/status/diff/merge/discard) |
-| Git & Environment | \`${n(`git_context`)}\`, \`${n(`process`)}\`, \`${n(`watch`)}\`, \`${n(`delegate`)}\` | Git info, process management |
-| Utilities | \`${n(`regex_test`)}\`, \`${n(`encode`)}\`, \`${n(`measure`)}\`, \`${n(`changelog`)}\`, \`${n(`schema_validate`)}\`, \`${n(`snippet`)}\`, \`${n(`env`)}\`, \`${n(`time`)}\` | Regex, encoding, metrics, validation |
-| System | \`${n(`status`)}\`, \`${n(`reindex`)}\`, \`${n(`health`)}\`, \`${n(`guide`)}\`, \`${n(`onboard`)}\`, \`${n(`graph`)}\`, \`${n(`queue`)}\`, \`${n(`replay`)}\` | Index management, health checks, tool discovery, knowledge graph |
+| Search & Discovery | \`search\`, \`find\`, \`symbol\`, \`trace\`, \`scope_map\`, \`lookup\`, \`dead_symbols\`, \`file_summary\` | Find code, symbols, data flow, reading plans |
+| Code Analysis | \`analyze_structure\`, \`analyze_dependencies\`, \`analyze_symbols\`, \`analyze_patterns\`, \`analyze_entry_points\`, \`analyze_diagram\`, \`blast_radius\` | Structure, deps, patterns, impact |
+| Knowledge | \`remember\`, \`read\`, \`update\`, \`forget\`, \`list\`, \`produce_knowledge\` | Persistent cross-session memory |
+| Execution | \`check\`, \`test_run\`, \`eval\`, \`batch\`, \`audit\` | Typecheck, lint, test, run code |
+| Context Compression | \`compact\`, \`digest\`, \`stratum_card\`, \`workset\`, \`stash\`, \`checkpoint\` | Reduce tokens, manage working sets |
+| FORGE | \`forge_ground\`, \`forge_classify\`, \`evidence_map\` | Quality gates for complex tasks |
+| Code Manipulation | \`rename\`, \`codemod\`, \`diff_parse\`, \`data_transform\` | Safe renames, transforms |
+| Web & API | \`web_fetch\`, \`web_search\`, \`http\` | Fetch pages, search web |
+| Lanes | \`lane\` | Isolated file copies for parallel exploration |
+| Git & Environment | \`git_context\`, \`process\`, \`watch\`, \`delegate\` | Git info, process management |
+| Utilities | \`regex_test\`, \`encode\`, \`measure\`, \`changelog\`, \`schema_validate\`, \`snippet\`, \`env\`, \`time\` | Regex, encoding, metrics |
+| System | \`status\`, \`reindex\`, \`health\`, \`guide\`, \`onboard\`, \`graph\`, \`queue\`, \`replay\` | Index management, knowledge graph |
 
 ---
 
-## MANDATORY: Context Reduction Protocol
-
-**Every agent interaction MUST minimize context window usage.** Raw file reads waste tokens and degrade LLM output quality. Use these tools instead:
-
-### Decision Tree — How to Read Code
+## How to Read Code (Decision Tree)
 
 \`\`\`
 Need to understand a file?
-├─ Just structure? → ${n(`file_summary`)} (exports, imports, functions — ~50 tokens)
-├─ Specific section? → ${n(`compact`)}({ path: "file.ts", query: "topic" }) — 5-20x reduction
-├─ Multiple files? → ${n(`digest`)} (multi-source compression — token-budgeted)
-├─ Repeated reference? → ${n(`stratum_card`)} (T1/T2 card — 10-100x reduction)
-└─ Full file needed? → ONLY as last resort, and compact it after reading
-\`\`\`
-
-### Rules
-1. **NEVER read a file >100 lines without compressing it first**
-2. **ALWAYS use \`${n(`file_summary`)}\` before \`read_file\`** — often the summary is sufficient
-3. **ALWAYS use \`${n(`compact`)}\` when you only need specific sections** of a file (use \`path\` param to read server-side)
-4. **Use \`${n(`digest`)}\` when synthesizing from 3+ sources** — don't accumulate raw text
-5. **Use \`${n(`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)
-\`\`\`
-${n(`status`)}({})                                              # Verify KB is ready
-${n(`list`)}()                                                  # See what knowledge exists
-${n(`search`)}({ query: "SESSION CHECKPOINT", origin: "curated" })  # Resume prior work
+\u251C\u2500 Just structure?     \u2192 file_summary (exports, imports, functions \u2014 ~50 tokens)
+\u251C\u2500 Specific section?   \u2192 compact({ path, query }) \u2014 5-20x token reduction
+\u251C\u2500 Multiple files?     \u2192 digest (multi-source compression)
+\u251C\u2500 Repeated reference? \u2192 stratum_card (reusable T1/T2 card)
+\u2514\u2500 Need exact lines to EDIT? \u2192 read_file (ONLY acceptable use)
 \`\`\`
 
-### During Session
-| Situation | Action |
-|-----------|--------|
-| Found a useful intermediate result | \`${n(`stash`)}({ key: "name", value: "data" })\` |
-| Completed a milestone | \`${n(`checkpoint`)}({ action: "save", name: "milestone" })\` |
-| Made an architecture decision | \`${n(`remember`)}({ title: "...", category: "decisions" })\` |
-| Discovered a pattern or convention | \`${n(`remember`)}({ title: "...", category: "patterns" })\` |
-| Found a non-obvious solution | \`${n(`remember`)}({ title: "...", category: "troubleshooting" })\` |
-| About to propose a new approach | \`${n(`search`)}({ query: "..." })\` — check if decided before |
-
-### Session End (MUST do this)
-\`\`\`
-${n(`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)?
-├─ Yes → ${n(`stash`)} (session-scoped key-value)
-└─ No → Is it resumable progress?
-   ├─ Yes → ${n(`checkpoint`)} (session-scoped snapshot)
-   └─ No → ${n(`remember`)} (permanent, survives reindex)
-       Categories: decisions | patterns | conventions | troubleshooting
-\`\`\`
+**Rules:**
+1. NEVER \`read_file\` a file >50 lines to "understand" it — use \`file_summary\` or \`compact\`
+2. NEVER \`grep_search\` or \`semantic_search\` — use \`search\` (hybrid across >12k indexed records)
+3. NEVER \`run_in_terminal\` for tsc/lint/test — use \`check\` / \`test_run\`
+4. \`read_file\` is ONLY for getting exact lines before \`replace_string_in_file\`
 
 ---
 
-## MANDATORY: Search-Before-Act Protocol
-
-**NEVER write or modify code without first searching for context.**
+## Session Protocol
 
+### Start (do ALL)
 \`\`\`
-# Before ANY code change:
-${n(`search`)}({ query: "<what you're about to change>" })     # Prior decisions?
-${n(`scope_map`)}({ task: "<description>" })                    # What files to read?
-${n(`symbol`)}({ name: "<key symbol>" })                        # Where is it defined/used?
+status({})                                                    # Check KB health + onboard state
+# If onboard not run → onboard({ path: "." })                # First-time codebase analysis
+list()                                                        # See stored knowledge
+search({ query: "SESSION CHECKPOINT", origin: "curated" })    # Resume prior work
 \`\`\`
 
-If \`${n(`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.**
+### During
+| Situation | Tool |
+|-----------|------|
+| Intermediate result | \`stash({ key, value })\` |
+| Milestone completed | \`checkpoint({ action: "save", name })\` |
+| Architecture decision made | \`remember({ title, content, category: "decisions" })\` |
+| Pattern discovered | \`remember({ title, content, category: "patterns" })\` |
+| About to propose new approach | \`search({ query })\` — check if already decided |
 
+### After Implementation (do ALL)
 \`\`\`
-${n(`check`)}({})                                    # Typecheck + lint (tsc + biome)
-${n(`test_run`)}({})                                 # Run tests
-${n(`blast_radius`)}({ changed_files: ["..."] })     # Impact analysis
-${n(`audit`)}({})                                    # Unified project audit (structure, deps, patterns, health, dead symbols, entry points)
+check({})                                                      # Typecheck + lint
+test_run({})                                                   # Run tests
+blast_radius({ changed_files: ["..."] })                       # Impact analysis
+reindex({})                                                    # Background refresh (non-blocking)
+produce_knowledge({ path: "." })                               # Regenerate codebase analysis
+remember({ title: "Session checkpoint: ...", ... })            # Persist decisions
 \`\`\`
 
----
-
-## FORGE Protocol (for complex tasks)
-
-For tasks touching 3+ files or involving architectural decisions:
-
+### End (MUST do)
 \`\`\`
-${n(`forge_classify`)}({ task: "<description>" })        # Quick: Floor/Standard/Critical tier
-${n(`forge_ground`)}({ task: "<description>" })           # Full: scope + constraints + evidence
-${n(`evidence_map`)}({ claims: ["claim1", "claim2"] })   # Track verified vs assumed
+remember({ title: "Session checkpoint: <topic>", content: "<decisions, blockers, next steps>", category: "conventions" })
 \`\`\`
+For long sessions or context approaching capacity, use the \`session-handoff\` skill to create a structured handoff document.
 
 ---
 
@@ -228,75 +145,21 @@ ${n(`evidence_map`)}({ claims: ["claim1", "claim2"] })   # Track verified vs ass
 
 | Mode | When | Example |
 |------|------|---------|
-| \`hybrid\` (default) | General queries | \`${n(`search`)}({ query: "error handling" })\` |
-| \`semantic\` | Conceptual/meaning-based | \`${n(`search`)}({ query: "retry with backoff", search_mode: "semantic" })\` |
-| \`keyword\` | Exact identifiers | \`${n(`search`)}({ query: "CircuitBreaker", search_mode: "keyword" })\` |
-
-Filters: \`origin\` (\`indexed\`/\`curated\`/\`produced\`), \`category\`, \`content_type\`, \`tags\`, \`min_score\`.
+| \`hybrid\` (default) | General queries | \`search({ query: "error handling" })\` |
+| \`semantic\` | Conceptual | \`search({ query: "retry with backoff", search_mode: "semantic" })\` |
+| \`keyword\` | Exact identifiers | \`search({ query: "CircuitBreaker", search_mode: "keyword" })\` |
 
 ---
 
 ## Workflow Chains
 
-**Codebase onboarding:**
-\`\`\`
-${n(`onboard`)}({ path: "." }) → ${n(`produce_knowledge`)}({ path: "src/" }) → ${n(`remember`)}(...)
-\`\`\`
+**Planning:** \`search\` → \`scope_map\` → \`file_summary\` per file → \`compact\` for detail → \`workset({ action: "save" })\`
 
-**Planning a task:**
-\`\`\`
-${n(`search`)}({ query: "task keywords" })
-→ ${n(`scope_map`)}({ task: "description" })
-→ ${n(`file_summary`)} for each file in scope
-→ ${n(`compact`)}({ path: "relevant-file.ts", query: "detail needed" }) for files needing detail
-→ ${n(`workset`)}({ action: "save", name: "task", files: [...] })
-\`\`\`
+**Bug investigation:** \`parse_output\` → \`symbol\` → \`trace({ direction: "backward" })\` → \`blast_radius\`
 
-**Bug investigation:**
-\`\`\`
-${n(`parse_output`)}({ output: "<error>" })
-→ ${n(`symbol`)}({ name: "failingFn" })
-→ ${n(`trace`)}({ symbol: "failingFn", direction: "backward" })
-→ ${n(`blast_radius`)}({ changed_files: ["suspect.ts"] })
-\`\`\`
-
-**Safe refactor with lanes:**
-\`\`\`
-${n(`lane`)}({ action: "create", name: "refactor", files: [...] })
-→ [make changes]
-→ ${n(`lane`)}({ action: "diff", name: "refactor" })
-→ ${n(`check`)}({}) → ${n(`test_run`)}({})
-→ ${n(`lane`)}({ action: "merge", name: "refactor" })
-\`\`\`
-
-**After making changes:**
-\`\`\`
-${n(`blast_radius`)}({ changed_files: ["src/file.ts"] })
-→ ${n(`check`)}({}) → ${n(`test_run`)}({})
-→ ${n(`reindex`)}({})
-→ ${n(`remember`)}(...)
-\`\`\`
-
----
-
-## 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 |
-
----
+**Codebase onboarding:** \`onboard({ path: "." })\` → \`produce_knowledge({ path: "src/" })\` → \`remember\`
 
-## Core Rules Summary
+**After implementation:** \`check\` → \`test_run\` → \`blast_radius\` → \`reindex\` → \`produce_knowledge\` → \`remember\`
 
-1. **Search KB before proposing anything new** — prior decisions exist
-2. **Compress context aggressively** — \`file_summary\` → \`compact\` → \`digest\`
-3. **Use persistent memory** — \`remember\` decisions, \`stash\` temporary data
-4. **Validate before committing** — \`check\` + \`test_run\` + \`blast_radius\`
-5. **Follow \`_Next:\` hints** in tool responses for guided workflow
-6. **Use FORGE for complex tasks** — \`forge_classify\` → \`forge_ground\` → \`evidence_map\`
-`}export{t as buildAgentsMd,e as buildCopilotInstructions};
-//# sourceMappingURL=templates.js.map
+**Complex tasks (FORGE):** \`forge_classify({ task })\` → \`forge_ground({ task })\` → \`evidence_map({ claims })\`
+`}export{t as buildAgentsMd,e as buildCopilotInstructions};

package/packages/cli/dist/commands/knowledge.d.ts

@@ -3,5 +3,4 @@ import { Command } from "../types.js";
 //#region packages/cli/src/commands/knowledge.d.ts
 declare const knowledgeCommands: Command[];
 //#endregion
-export { knowledgeCommands };
-//# sourceMappingURL=knowledge.d.ts.map
+export { knowledgeCommands };

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

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

package/packages/cli/dist/commands/search.d.ts

@@ -3,5 +3,4 @@ import { Command } from "../types.js";
 //#region packages/cli/src/commands/search.d.ts
 declare const searchCommands: Command[];
 //#endregion
-export { searchCommands };
-//# sourceMappingURL=search.d.ts.map
+export { searchCommands };

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

@@ -1,2 +1 @@
-import{ctx as e}from"../context.js";import{extractNumFlag as t,extractStrFlag as n,formatFocusRanges as r,printDeadSymbolsResult as i,printExamplesResult as a,printSymbolInfo as o,printTraceResult as s,rrf as c}from"../helpers.js";import{find as l,findDeadSymbols as u,findExamples as d,scopeMap as f,symbol as p,trace as m}from"../../../tools/dist/index.js";const h=[{name:`search`,description:`Search the knowledge base`,usage:`kb search <query> [--limit N] [--mode hybrid|semantic|keyword] [--graph-hops 0-3]`,run:async r=>{let i=t(r,`--limit`,5),a=n(r,`--mode`,`hybrid`),o=t(r,`--graph-hops`,0),s=r.join(` `).trim();s||(console.error(`Usage: kb search <query>`),process.exit(1));let{embedder:l,store:u,graphStore:d}=await e(),f=await l.embedQuery(s),p;if(a===`keyword`)p=await u.ftsSearch(s,{limit:i});else if(a===`semantic`)p=await u.search(f,{limit:i});else{let[e,t]=await Promise.all([u.search(f,{limit:i*2}),u.ftsSearch(s,{limit:i*2}).catch(()=>[])]);p=c(e,t).slice(0,i)}if(p.length===0){console.log(`No results found.`);return}for(let{record:e,score:t}of p){console.log(`\n${`─`.repeat(60)}`),console.log(`[${(t*100).toFixed(1)}%] ${e.sourcePath}:${e.startLine}-${e.endLine}`),console.log(`  Type: ${e.contentType} | Origin: ${e.origin}`),e.tags.length>0&&console.log(`  Tags: ${e.tags.join(`, `)}`),console.log(``);let n=e.content.length>500?`${e.content.slice(0,500)}...`:e.content;console.log(n)}if(console.log(`\n${`─`.repeat(60)}`),console.log(`${p.length} result(s) found.`),o>0&&p.length>0)try{let{graphAugmentSearch:e}=await import(`../../../tools/dist/index.js`),t=(await e(d,p.map(e=>({recordId:e.record.id,score:e.score,sourcePath:e.record.sourcePath})),{hops:o,maxPerHit:5})).filter(e=>e.graphContext.nodes.length>0);if(t.length>0){console.log(`\nGraph context (${o} hop${o>1?`s`:``}):\n`);for(let e of t){console.log(`  ${e.sourcePath}:`);for(let t of e.graphContext.nodes.slice(0,5))console.log(`    → ${t.name} (${t.type})`);for(let t of e.graphContext.edges.slice(0,5))console.log(`    → ${t.fromId} --[${t.type}]--> ${t.toId}`)}}}catch(e){console.error(`[graph] augmentation failed: ${e.message}`)}}},{name:`find`,description:`Run federated search across indexed content and files`,usage:`kb find [query] [--glob <pattern>] [--pattern <regex>] [--limit N]`,run:async r=>{let i=t(r,`--limit`,10),a=n(r,`--glob`,``).trim()||void 0,o=n(r,`--pattern`,``).trim()||void 0,s=r.join(` `).trim()||void 0;!s&&!a&&!o&&(console.error(`Usage: kb find [query] [--glob <pattern>] [--pattern <regex>] [--limit N]`),process.exit(1));let{embedder:c,store:u}=await e(),d=await l(c,u,{query:s,glob:a,pattern:o,limit:i});if(d.results.length===0){console.log(`No matches found.`);return}console.log(`Strategies: ${d.strategies.join(`, `)}`),console.log(`Results: ${d.results.length} shown (${d.totalFound} total)`);for(let e of d.results){let t=e.lineRange?`:${e.lineRange.start}-${e.lineRange.end}`:``;console.log(`\n[${e.source}] ${e.path}${t}`),console.log(`  Score: ${(e.score*100).toFixed(1)}%`),e.preview&&console.log(`  ${e.preview.replace(/\s+/g,` `).trim()}`)}}},{name:`scope-map`,description:`Generate a reading plan for a task`,usage:`kb scope-map <task> [--max-files N]`,run:async n=>{let i=t(n,`--max-files`,15),a=n.join(` `).trim();a||(console.error(`Usage: kb scope-map <task> [--max-files N]`),process.exit(1));let{embedder:o,store:s}=await e(),c=await f(o,s,{task:a,maxFiles:i});console.log(`Task: ${c.task}`),console.log(`Files: ${c.files.length}`),console.log(`Estimated tokens: ${c.totalEstimatedTokens}`),console.log(``),console.log(`Reading order:`);for(let e of c.readingOrder)console.log(`  ${e}`);for(let[e,t]of c.files.entries())console.log(`\n${e+1}. ${t.path}`),console.log(`   Relevance: ${(t.relevance*100).toFixed(1)}% | Tokens: ${t.estimatedTokens}`),console.log(`   Why: ${t.reason}`),t.focusRanges.length>0&&console.log(`   Focus: ${r(t.focusRanges)}`)}},{name:`symbol`,description:`Resolve a symbol definition, imports, and references`,usage:`kb symbol <name> [--limit N]`,run:async n=>{let r=t(n,`--limit`,20),i=n.join(` `).trim();i||(console.error(`Usage: kb symbol <name> [--limit N]`),process.exit(1));let{embedder:a,store:s}=await e();o(await p(a,s,{name:i,limit:r}))}},{name:`trace`,description:`Trace forward/backward flow for a symbol or file location`,usage:`kb trace <start> [--direction forward|backward|both] [--max-depth N]`,run:async r=>{let i=n(r,`--direction`,`both`).trim()||`both`,a=t(r,`--max-depth`,3),o=r.join(` `).trim();(!o||![`forward`,`backward`,`both`].includes(i))&&(console.error(`Usage: kb trace <start> [--direction forward|backward|both] [--max-depth N]`),process.exit(1));let{embedder:c,store:l}=await e();s(await m(c,l,{start:o,direction:i,maxDepth:a}))}},{name:`examples`,description:`Find real code examples of a symbol or pattern`,usage:`kb examples <query> [--limit N] [--content-type type]`,run:async r=>{let i=t(r,`--limit`,5),o=n(r,`--content-type`,``).trim()||void 0,s=r.join(` `).trim();s||(console.error(`Usage: kb examples <query> [--limit N] [--content-type type]`),process.exit(1));let{embedder:c,store:l}=await e();a(await d(c,l,{query:s,limit:i,contentType:o}))}},{name:`dead-symbols`,description:`Find exported symbols that appear to be unused`,usage:`kb dead-symbols [--limit N]`,run:async n=>{let r=t(n,`--limit`,100),{embedder:a,store:o}=await e();i(await u(a,o,{limit:r}))}},{name:`lookup`,description:`Look up indexed content by record ID or source path`,usage:`kb lookup <id>`,run:async t=>{let n=t.join(` `).trim();n||(console.error(`Usage: kb lookup <id>`),process.exit(1));let{store:r}=await e(),i=await r.getById(n);if(i){console.log(i.id),console.log(`─`.repeat(60)),console.log(`Path: ${i.sourcePath}`),console.log(`Chunk: ${i.chunkIndex+1}/${i.totalChunks}`),console.log(`Lines: ${i.startLine}-${i.endLine}`),console.log(`Type: ${i.contentType} | Origin: ${i.origin}`),i.tags.length>0&&console.log(`Tags: ${i.tags.join(`, `)}`),console.log(``),console.log(i.content);return}let a=await r.getBySourcePath(n);if(a.length===0){console.log(`No indexed content found for: ${n}`);return}a.sort((e,t)=>e.chunkIndex-t.chunkIndex),console.log(n),console.log(`─`.repeat(60)),console.log(`Chunks: ${a.length} | Type: ${a[0].contentType}`);for(let e of a){let t=e.startLine?` (lines ${e.startLine}-${e.endLine})`:``;console.log(`\nChunk ${e.chunkIndex+1}/${e.totalChunks}${t}`),console.log(e.content)}}}];export{h as searchCommands};
-//# sourceMappingURL=search.js.map
+import{ctx as e}from"../context.js";import{extractNumFlag as t,extractStrFlag as n,formatFocusRanges as r,printDeadSymbolsResult as i,printExamplesResult as a,printSymbolInfo as o,printTraceResult as s,rrf as c}from"../helpers.js";import{find as l,findDeadSymbols as u,findExamples as d,scopeMap as f,symbol as p,trace as m}from"../../../tools/dist/index.js";const h=[{name:`search`,description:`Search the knowledge base`,usage:`kb search <query> [--limit N] [--mode hybrid|semantic|keyword] [--graph-hops 0-3]`,run:async r=>{let i=t(r,`--limit`,5),a=n(r,`--mode`,`hybrid`),o=t(r,`--graph-hops`,0),s=r.join(` `).trim();s||(console.error(`Usage: kb search <query>`),process.exit(1));let{embedder:l,store:u,graphStore:d}=await e(),f=await l.embedQuery(s),p;if(a===`keyword`)p=await u.ftsSearch(s,{limit:i});else if(a===`semantic`)p=await u.search(f,{limit:i});else{let[e,t]=await Promise.all([u.search(f,{limit:i*2}),u.ftsSearch(s,{limit:i*2}).catch(()=>[])]);p=c(e,t).slice(0,i)}if(p.length===0){console.log(`No results found.`);return}for(let{record:e,score:t}of p){console.log(`\n${`─`.repeat(60)}`),console.log(`[${(t*100).toFixed(1)}%] ${e.sourcePath}:${e.startLine}-${e.endLine}`),console.log(`  Type: ${e.contentType} | Origin: ${e.origin}`),e.tags.length>0&&console.log(`  Tags: ${e.tags.join(`, `)}`),console.log(``);let n=e.content.length>500?`${e.content.slice(0,500)}...`:e.content;console.log(n)}if(console.log(`\n${`─`.repeat(60)}`),console.log(`${p.length} result(s) found.`),o>0&&p.length>0)try{let{graphAugmentSearch:e}=await import(`../../../tools/dist/index.js`),t=(await e(d,p.map(e=>({recordId:e.record.id,score:e.score,sourcePath:e.record.sourcePath})),{hops:o,maxPerHit:5})).filter(e=>e.graphContext.nodes.length>0);if(t.length>0){console.log(`\nGraph context (${o} hop${o>1?`s`:``}):\n`);for(let e of t){console.log(`  ${e.sourcePath}:`);for(let t of e.graphContext.nodes.slice(0,5))console.log(`    → ${t.name} (${t.type})`);for(let t of e.graphContext.edges.slice(0,5))console.log(`    → ${t.fromId} --[${t.type}]--> ${t.toId}`)}}}catch(e){console.error(`[graph] augmentation failed: ${e.message}`)}}},{name:`find`,description:`Run federated search across indexed content and files`,usage:`kb find [query] [--glob <pattern>] [--pattern <regex>] [--limit N]`,run:async r=>{let i=t(r,`--limit`,10),a=n(r,`--glob`,``).trim()||void 0,o=n(r,`--pattern`,``).trim()||void 0,s=r.join(` `).trim()||void 0;!s&&!a&&!o&&(console.error(`Usage: kb find [query] [--glob <pattern>] [--pattern <regex>] [--limit N]`),process.exit(1));let{embedder:c,store:u}=await e(),d=await l(c,u,{query:s,glob:a,pattern:o,limit:i});if(d.results.length===0){console.log(`No matches found.`);return}console.log(`Strategies: ${d.strategies.join(`, `)}`),console.log(`Results: ${d.results.length} shown (${d.totalFound} total)`);for(let e of d.results){let t=e.lineRange?`:${e.lineRange.start}-${e.lineRange.end}`:``;console.log(`\n[${e.source}] ${e.path}${t}`),console.log(`  Score: ${(e.score*100).toFixed(1)}%`),e.preview&&console.log(`  ${e.preview.replace(/\s+/g,` `).trim()}`)}}},{name:`scope-map`,description:`Generate a reading plan for a task`,usage:`kb scope-map <task> [--max-files N]`,run:async n=>{let i=t(n,`--max-files`,15),a=n.join(` `).trim();a||(console.error(`Usage: kb scope-map <task> [--max-files N]`),process.exit(1));let{embedder:o,store:s}=await e(),c=await f(o,s,{task:a,maxFiles:i});console.log(`Task: ${c.task}`),console.log(`Files: ${c.files.length}`),console.log(`Estimated tokens: ${c.totalEstimatedTokens}`),console.log(``),console.log(`Reading order:`);for(let e of c.readingOrder)console.log(`  ${e}`);for(let[e,t]of c.files.entries())console.log(`\n${e+1}. ${t.path}`),console.log(`   Relevance: ${(t.relevance*100).toFixed(1)}% | Tokens: ${t.estimatedTokens}`),console.log(`   Why: ${t.reason}`),t.focusRanges.length>0&&console.log(`   Focus: ${r(t.focusRanges)}`)}},{name:`symbol`,description:`Resolve a symbol definition, imports, and references`,usage:`kb symbol <name> [--limit N]`,run:async n=>{let r=t(n,`--limit`,20),i=n.join(` `).trim();i||(console.error(`Usage: kb symbol <name> [--limit N]`),process.exit(1));let{embedder:a,store:s}=await e();o(await p(a,s,{name:i,limit:r}))}},{name:`trace`,description:`Trace forward/backward flow for a symbol or file location`,usage:`kb trace <start> [--direction forward|backward|both] [--max-depth N]`,run:async r=>{let i=n(r,`--direction`,`both`).trim()||`both`,a=t(r,`--max-depth`,3),o=r.join(` `).trim();(!o||![`forward`,`backward`,`both`].includes(i))&&(console.error(`Usage: kb trace <start> [--direction forward|backward|both] [--max-depth N]`),process.exit(1));let{embedder:c,store:l}=await e();s(await m(c,l,{start:o,direction:i,maxDepth:a}))}},{name:`examples`,description:`Find real code examples of a symbol or pattern`,usage:`kb examples <query> [--limit N] [--content-type type]`,run:async r=>{let i=t(r,`--limit`,5),o=n(r,`--content-type`,``).trim()||void 0,s=r.join(` `).trim();s||(console.error(`Usage: kb examples <query> [--limit N] [--content-type type]`),process.exit(1));let{embedder:c,store:l}=await e();a(await d(c,l,{query:s,limit:i,contentType:o}))}},{name:`dead-symbols`,description:`Find exported symbols that appear to be unused`,usage:`kb dead-symbols [--limit N]`,run:async n=>{let r=t(n,`--limit`,100),{embedder:a,store:o}=await e();i(await u(a,o,{limit:r}))}},{name:`lookup`,description:`Look up indexed content by record ID or source path`,usage:`kb lookup <id>`,run:async t=>{let n=t.join(` `).trim();n||(console.error(`Usage: kb lookup <id>`),process.exit(1));let{store:r}=await e(),i=await r.getById(n);if(i){console.log(i.id),console.log(`─`.repeat(60)),console.log(`Path: ${i.sourcePath}`),console.log(`Chunk: ${i.chunkIndex+1}/${i.totalChunks}`),console.log(`Lines: ${i.startLine}-${i.endLine}`),console.log(`Type: ${i.contentType} | Origin: ${i.origin}`),i.tags.length>0&&console.log(`Tags: ${i.tags.join(`, `)}`),console.log(``),console.log(i.content);return}let a=await r.getBySourcePath(n);if(a.length===0){console.log(`No indexed content found for: ${n}`);return}a.sort((e,t)=>e.chunkIndex-t.chunkIndex),console.log(n),console.log(`─`.repeat(60)),console.log(`Chunks: ${a.length} | Type: ${a[0].contentType}`);for(let e of a){let t=e.startLine?` (lines ${e.startLine}-${e.endLine})`:``;console.log(`\nChunk ${e.chunkIndex+1}/${e.totalChunks}${t}`),console.log(e.content)}}}];export{h as searchCommands};

package/packages/cli/dist/commands/system.d.ts

@@ -3,5 +3,4 @@ import { Command } from "../types.js";
 //#region packages/cli/src/commands/system.d.ts
 declare const systemCommands: Command[];
 //#endregion
-export { systemCommands };
-//# sourceMappingURL=system.d.ts.map
+export { systemCommands };

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

@@ -1,5 +1,4 @@
-import{ctx as e}from"../context.js";import{executeCliBatchOperation as t,extractStrFlag as n,parseBatchPayload as r,printCheckResult as i,readInput as a}from"../helpers.js";import{dirname as o,resolve as s}from"node:path";import{fileURLToPath as c}from"node:url";import{audit as l,batch as u,check as d,guide as f,health as p,replayClear as m,replayList as h,replayTrim as g}from"../../../tools/dist/index.js";import{fork as _}from"node:child_process";const v=o(c(import.meta.url)),y=[{name:`status`,description:`Show knowledge base index status and statistics`,run:async()=>{let{store:t}=await e(),n=await t.getStats(),r=await t.listSourcePaths();console.log(`Knowledge Base Status`),console.log(`─`.repeat(40)),console.log(`  Records:  ${n.totalRecords}`),console.log(`  Files:    ${n.totalFiles}`),console.log(`  Indexed:  ${n.lastIndexedAt??`Never`}`),console.log(`  Backend:  ${n.storeBackend}`),console.log(`  Model:    ${n.embeddingModel}`),console.log(``),console.log(`Content Types:`);for(let[e,t]of Object.entries(n.contentTypeBreakdown))console.log(`  ${e}: ${t}`);if(r.length>0){console.log(``),console.log(`Files (${r.length} total):`);for(let e of r.slice(0,20))console.log(`  ${e}`);r.length>20&&console.log(`  ... and ${r.length-20} more`)}}},{name:`reindex`,description:`Re-index the knowledge base from configured sources`,usage:`kb reindex [--full]`,run:async t=>{let n=t.includes(`--full`),{store:r,indexer:i,curated:a,config:o}=await e();console.log(`Indexing sources...`);let s=e=>{e.phase===`chunking`&&e.currentFile&&process.stdout.write(`\r  [${e.filesProcessed+1}/${e.filesTotal}] ${e.currentFile}`),e.phase===`done`&&process.stdout.write(`
-`)},c;n?(console.log(`Dropping existing index for full reindex...`),c=await i.reindexAll(o,s)):c=await i.index(o,s),console.log(`Done: ${c.filesProcessed} files, ${c.chunksCreated} chunks in ${(c.durationMs/1e3).toFixed(1)}s`),console.log(`Building FTS index...`),await r.createFtsIndex(),console.log(`Re-indexing curated entries...`);let l=await a.reindexAll();console.log(`Curated: ${l.indexed} entries restored`)}},{name:`serve`,description:`Start the MCP server (stdio or HTTP)`,usage:`kb serve [--transport stdio|http] [--port N]`,run:async e=>{let t=s(v,`..`,`..`,`..`,`server`,`dist`,`index.js`),r=n(e,`--transport`,`stdio`),i=n(e,`--port`,`3210`),a=_(t,[],{stdio:r===`stdio`?[`pipe`,`pipe`,`inherit`,`ipc`]:`inherit`,env:{...process.env,KB_TRANSPORT:r,KB_PORT:i}});r===`stdio`&&a.stdin&&a.stdout&&(process.stdin.pipe(a.stdin),a.stdout.pipe(process.stdout)),a.on(`exit`,e=>process.exit(e??0)),process.on(`SIGINT`,()=>a.kill(`SIGINT`)),process.on(`SIGTERM`,()=>a.kill(`SIGTERM`)),await new Promise(()=>{})}},{name:`init`,description:`Initialize a knowledge base in the current directory`,usage:`kb init [--force] [--guide]`,run:async e=>{if(e.includes(`--guide`)){let{guideProject:e}=await import(`./init/index.js`);await e();return}let t=e.includes(`--force`),{initProject:n}=await import(`./init/index.js`);await n({force:t})}},{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=>{let t=n(e,`--cwd`,``).trim()||void 0,r=n(e,`--files`,``),a=n(e,`--detail`,`full`)||`full`,o=r.split(`,`).map(e=>e.trim()).filter(Boolean),s=!1;e.includes(`--skip-types`)&&(e.splice(e.indexOf(`--skip-types`),1),s=!0);let c=!1;e.includes(`--skip-lint`)&&(e.splice(e.indexOf(`--skip-lint`),1),c=!0);let l=await d({cwd:t,files:o.length>0?o:void 0,skipTypes:s,skipLint:c,detail:a});i(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 i=>{let o=n(i,`--file`,``).trim()||void 0,s=(()=>{let e=i.indexOf(`--concurrency`);if(e===-1||e+1>=i.length)return 0;let t=Number.parseInt(i.splice(e,2)[1],10);return Number.isNaN(t)?0:t})(),c=await a(o);c.trim()||(console.error(`Usage: kb batch [--file path] [--concurrency N]`),process.exit(1));let l=r(c),d=s>0?s:l.concurrency,f=l.operations.some(e=>e.type!==`check`)?await e():null,p=await u(l.operations,async e=>t(e,f),{concurrency:d});console.log(JSON.stringify(p,null,2)),p.some(e=>e.status===`error`)&&(process.exitCode=1)}},{name:`health`,description:`Run project health checks on the current directory`,usage:`kb health [path]`,run:async e=>{let t=p(e.shift());console.log(`Project Health: ${t.path}`),console.log(`─`.repeat(50));for(let e of t.checks){let t=e.status===`pass`?`+`:e.status===`warn`?`~`:`X`;console.log(`  [${t}] ${e.name}: ${e.message}`)}console.log(`─`.repeat(50)),console.log(`Score: ${t.score}% — ${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 t=>{let{store:r,embedder:i}=await e(),a=n(t,`--detail`,`summary`)||`summary`,o=n(t,`--checks`,``),s=o?o.split(`,`).map(e=>e.trim()):void 0,c=await l(r,i,{path:t.shift()||`.`,checks:s,detail:a});if(c.ok){if(console.log(c.summary),c.next&&c.next.length>0){console.log(`
+import{ctx as e}from"../context.js";import{executeCliBatchOperation as t,extractStrFlag as n,parseBatchPayload as r,printCheckResult as i,readInput as a}from"../helpers.js";import{dirname as o,resolve as s}from"node:path";import{fileURLToPath as c}from"node:url";import{audit as l,batch as u,check as d,guide as f,health as p,replayClear as m,replayList as h,replayTrim as g}from"../../../tools/dist/index.js";import{fork as _}from"node:child_process";const v=o(c(import.meta.url)),y=[{name:`status`,description:`Show knowledge base index status and statistics`,run:async()=>{let{isGlobalInstalled:t,getGlobalDataDir:n,computePartitionKey:r,listWorkspaces:i}=await import(`../../../core/dist/index.js`),{existsSync:a}=await import(`node:fs`),o=process.cwd(),c=t(),l=a(s(o,`.vscode`,`mcp.json`)),u,d;if(c&&l)u=`local (overrides global for this workspace)`,d=s(o,`.kb-data`);else if(c){let e=r(o);u=a(s(o,`AGENTS.md`))?`global (workspace scaffolded)`:`global (workspace not scaffolded)`,d=s(n(),e)}else u=`local`,d=s(o,`.kb-data`);if(console.log(`Knowledge Base Status`),console.log(`─`.repeat(40)),console.log(`  Mode:     ${u}`),console.log(`  Data:     ${d}`),c&&!l){let e=i();console.log(`  Registry: ${e.length} workspace(s) enrolled`)}try{let{store:t}=await e(),n=await t.getStats(),r=await t.listSourcePaths();console.log(`  Records:  ${n.totalRecords}`),console.log(`  Files:    ${n.totalFiles}`),console.log(`  Indexed:  ${n.lastIndexedAt??`Never`}`),console.log(`  Backend:  ${n.storeBackend}`),console.log(`  Model:    ${n.embeddingModel}`),console.log(``),console.log(`Content Types:`);for(let[e,t]of Object.entries(n.contentTypeBreakdown))console.log(`  ${e}: ${t}`);if(r.length>0){console.log(``),console.log(`Files (${r.length} total):`);for(let e of r.slice(0,20))console.log(`  ${e}`);r.length>20&&console.log(`  ... and ${r.length-20} more`)}}catch{console.log(``),console.log("  Index not available — run `kb reindex` to index this workspace.")}c&&!l&&!a(s(o,`AGENTS.md`))&&(console.log(``),console.log("  Action: Run `npx @vpxa/kb init` to add AGENTS.md and copilot-instructions.md"))}},{name:`reindex`,description:`Re-index the knowledge base from configured sources`,usage:`kb reindex [--full]`,run:async t=>{let n=t.includes(`--full`),{store:r,indexer:i,curated:a,config:o}=await e();console.log(`Indexing sources...`);let s=e=>{e.phase===`chunking`&&e.currentFile&&process.stdout.write(`\r  [${e.filesProcessed+1}/${e.filesTotal}] ${e.currentFile}`),e.phase===`done`&&process.stdout.write(`
+`)},c;n?(console.log(`Dropping existing index for full reindex...`),c=await i.reindexAll(o,s)):c=await i.index(o,s),console.log(`Done: ${c.filesProcessed} files, ${c.chunksCreated} chunks in ${(c.durationMs/1e3).toFixed(1)}s`),console.log(`Building FTS index...`),await r.createFtsIndex(),console.log(`Re-indexing curated entries...`);let l=await a.reindexAll();console.log(`Curated: ${l.indexed} entries restored`)}},{name:`serve`,description:`Start the MCP server (stdio or HTTP)`,usage:`kb serve [--transport stdio|http] [--port N]`,run:async e=>{let t=s(v,`..`,`..`,`..`,`server`,`dist`,`index.js`),r=n(e,`--transport`,`stdio`),i=n(e,`--port`,`3210`),a=_(t,[],{stdio:r===`stdio`?[`pipe`,`pipe`,`inherit`,`ipc`]:`inherit`,env:{...process.env,KB_TRANSPORT:r,KB_PORT:i}});r===`stdio`&&a.stdin&&a.stdout&&(process.stdin.pipe(a.stdin),a.stdout.pipe(process.stdout)),a.on(`exit`,e=>process.exit(e??0)),process.on(`SIGINT`,()=>a.kill(`SIGINT`)),process.on(`SIGTERM`,()=>a.kill(`SIGTERM`)),await new Promise(()=>{})}},{name:`init`,description:`Initialize a knowledge base in the current directory`,usage:`kb init [--global|--local] [--force] [--guide]`,run:async e=>{let t=e.includes(`--global`),n=e.includes(`--local`),r=e.includes(`--guide`),i=e.includes(`--force`);if(t&&n&&(console.error(`Cannot use --global and --local together.`),process.exit(1)),r){let{guideProject:e}=await import(`./init/index.js`);await e();return}if(t){let{initGlobal:e}=await import(`./init/global.js`);await e({force:i})}else if(n){let{initProject:e}=await import(`./init/index.js`);await e({force:i})}else{let{initSmart:e}=await import(`./init/index.js`);await e({force:i})}}},{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=>{let t=n(e,`--cwd`,``).trim()||void 0,r=n(e,`--files`,``),a=n(e,`--detail`,`full`)||`full`,o=r.split(`,`).map(e=>e.trim()).filter(Boolean),s=!1;e.includes(`--skip-types`)&&(e.splice(e.indexOf(`--skip-types`),1),s=!0);let c=!1;e.includes(`--skip-lint`)&&(e.splice(e.indexOf(`--skip-lint`),1),c=!0);let l=await d({cwd:t,files:o.length>0?o:void 0,skipTypes:s,skipLint:c,detail:a});i(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 i=>{let o=n(i,`--file`,``).trim()||void 0,s=(()=>{let e=i.indexOf(`--concurrency`);if(e===-1||e+1>=i.length)return 0;let t=Number.parseInt(i.splice(e,2)[1],10);return Number.isNaN(t)?0:t})(),c=await a(o);c.trim()||(console.error(`Usage: kb batch [--file path] [--concurrency N]`),process.exit(1));let l=r(c),d=s>0?s:l.concurrency,f=l.operations.some(e=>e.type!==`check`)?await e():null,p=await u(l.operations,async e=>t(e,f),{concurrency:d});console.log(JSON.stringify(p,null,2)),p.some(e=>e.status===`error`)&&(process.exitCode=1)}},{name:`health`,description:`Run project health checks on the current directory`,usage:`kb health [path]`,run:async e=>{let t=p(e.shift());console.log(`Project Health: ${t.path}`),console.log(`─`.repeat(50));for(let e of t.checks){let t=e.status===`pass`?`+`:e.status===`warn`?`~`:`X`;console.log(`  [${t}] ${e.name}: ${e.message}`)}console.log(`─`.repeat(50)),console.log(`Score: ${t.score}% — ${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 t=>{let{store:r,embedder:i}=await e(),a=n(t,`--detail`,`summary`)||`summary`,o=n(t,`--checks`,``),s=o?o.split(`,`).map(e=>e.trim()):void 0,c=await l(r,i,{path:t.shift()||`.`,checks:s,detail:a});if(c.ok){if(console.log(c.summary),c.next&&c.next.length>0){console.log(`
 Suggested next steps:`);for(let e of c.next)console.log(`  → ${e.tool}: ${e.reason}`)}}else console.error(c.error?.message??`Audit failed`),process.exitCode=1}},{name:`guide`,description:`Tool discovery — recommend KB tools for a given goal`,usage:`kb guide <goal> [--max N]`,run:async e=>{let t=e.indexOf(`--max`),n=5;t!==-1&&t+1<e.length&&(n=Number.parseInt(e.splice(t,2)[1],10)||5);let r=e.join(` `).trim();r||(console.error(`Usage: kb guide <goal> [--max N]`),console.error(`Example: kb guide "audit this project"`),process.exit(1));let i=f(r,n);console.log(`Workflow: ${i.workflow}`),console.log(`  ${i.description}\n`),console.log(`Recommended tools:`);for(let e of i.tools){let t=e.suggestedArgs?` ${JSON.stringify(e.suggestedArgs)}`:``;console.log(`  ${e.order}. ${e.tool} — ${e.reason}${t}`)}i.alternativeWorkflows.length>0&&console.log(`\nAlternatives: ${i.alternativeWorkflows.join(`, `)}`)}},{name:`replay`,description:`Show recent tool invocation audit trail`,usage:`kb replay [--last N] [--tool <name>] [--source mcp|cli]`,run:async e=>{let t=h({last:Number.parseInt(e[e.indexOf(`--last`)+1],10)||20,tool:e.includes(`--tool`)?e[e.indexOf(`--tool`)+1]:void 0,source:e.includes(`--source`)?e[e.indexOf(`--source`)+1]:void 0});if(t.length===0){console.log(`No replay entries. Activity is logged when tools are invoked.`);return}console.log(`Replay Log (${t.length} entries)\n`);for(let e of t){let t=e.ts.split(`T`)[1]?.split(`.`)[0]??e.ts,n=e.status===`ok`?`✓`:`✗`;console.log(`${t} ${n} ${e.tool} (${e.durationMs}ms) [${e.source}]`),console.log(`  in:  ${e.input}`),console.log(`  out: ${e.output}`)}g()}},{name:`replay-clear`,description:`Clear the replay audit trail`,run:async()=>{m(),console.log(`Replay log cleared.`)}},{name:`tui`,description:`Launch interactive terminal dashboard (human monitoring)`,run:async()=>{try{let{launch:t}=await import(`../../../tui/dist/index.js`),{store:n,embedder:r,config:i}=await e();t({store:n,embedder:r,config:i})}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{y as systemCommands};
-//# sourceMappingURL=system.js.map
+  pnpm add -D ink react @types/react`),process.exit(1)),e}}}];export{y as systemCommands};

package/packages/cli/dist/commands/workspace.d.ts

@@ -3,5 +3,4 @@ import { Command } from "../types.js";
 //#region packages/cli/src/commands/workspace.d.ts
 declare const workspaceCommands: Command[];
 //#endregion
-export { workspaceCommands };
-//# sourceMappingURL=workspace.d.ts.map
+export { workspaceCommands };

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

@@ -1,2 +1 @@
-import{extractStrFlag as e,parseMaybeJsonString as t,printWorkset as n,readStdin as r,splitCsv as i}from"../helpers.js";import{addToWorkset as a,deleteWorkset as o,getWorkset as s,laneCreate as c,laneDiff as l,laneDiscard as u,laneList as d,laneMerge as f,laneStatus as p,listWorksets as m,queueClear as h,queueCreate as g,queueDelete as _,queueDone as v,queueFail as y,queueGet as b,queueList as x,queueNext as S,queuePush as C,removeFromWorkset as w,saveWorkset as T,stashClear as E,stashDelete as D,stashGet as O,stashList as k,stashSet as A}from"../../../tools/dist/index.js";const j=[{name:`workset`,description:`Manage saved file sets`,usage:`kb workset <action> [name] [--files f1,f2] [--description desc]`,run:async t=>{let r=t.shift()?.trim(),c=i(e(t,`--files`,``)),l=e(t,`--description`,``).trim()||void 0,u=t.shift()?.trim();switch(r||(console.error(`Usage: kb workset <action> [name] [--files f1,f2] [--description desc]`),console.error(`Actions: save, get, list, delete, add, remove`),process.exit(1)),r){case`save`:{(!u||c.length===0)&&(console.error(`Usage: kb workset save <name> --files f1,f2 [--description desc]`),process.exit(1));let e=T(u,c,{description:l});console.log(`Saved workset: ${e.name}`),n(e);return}case`get`:{u||(console.error(`Usage: kb workset get <name>`),process.exit(1));let e=s(u);if(!e){console.log(`No workset found: ${u}`);return}n(e);return}case`list`:{let e=m();if(e.length===0){console.log(`No worksets saved.`);return}console.log(`Worksets (${e.length})`),console.log(`─`.repeat(60));for(let t of e)n(t),console.log(``);return}case`delete`:{u||(console.error(`Usage: kb workset delete <name>`),process.exit(1));let e=o(u);console.log(e?`Deleted workset: ${u}`:`No workset found: ${u}`);return}case`add`:{(!u||c.length===0)&&(console.error(`Usage: kb workset add <name> --files f1,f2`),process.exit(1));let e=a(u,c);console.log(`Updated workset: ${e.name}`),n(e);return}case`remove`:{(!u||c.length===0)&&(console.error(`Usage: kb workset remove <name> --files f1,f2`),process.exit(1));let e=w(u,c);if(!e){console.log(`No workset found: ${u}`);return}console.log(`Updated workset: ${e.name}`),n(e);return}default:console.error(`Unknown workset action: ${r}`),console.error(`Actions: save, get, list, delete, add, remove`),process.exit(1)}}},{name:`stash`,description:`Persist and retrieve named intermediate values`,usage:`kb stash <set|get|list|delete|clear> [key] [value]`,run:async e=>{let n=e.shift()?.trim(),i=e.shift()?.trim();switch(n||(console.error(`Usage: kb stash <set|get|list|delete|clear> [key] [value]`),process.exit(1)),n){case`set`:{i||(console.error(`Usage: kb stash set <key> <value>`),process.exit(1));let n=e.join(` `),a=n.trim()?``:await r(),o=A(i,t(n||a));console.log(`Stored stash entry: ${o.key}`),console.log(`  Type: ${o.type}`),console.log(`  Stored: ${o.storedAt}`);return}case`get`:{i||(console.error(`Usage: kb stash get <key>`),process.exit(1));let e=O(i);if(!e){console.log(`No stash entry found: ${i}`);return}console.log(JSON.stringify(e,null,2));return}case`list`:{let e=k();if(e.length===0){console.log(`No stash entries saved.`);return}console.log(`Stash entries (${e.length})`),console.log(`─`.repeat(60));for(let t of e)console.log(`${t.key} (${t.type})`),console.log(`  Stored: ${t.storedAt}`);return}case`delete`:{i||(console.error(`Usage: kb stash delete <key>`),process.exit(1));let e=D(i);console.log(e?`Deleted stash entry: ${i}`:`No stash entry found: ${i}`);return}case`clear`:{let e=E();console.log(`Cleared ${e} stash entr${e===1?`y`:`ies`}.`);return}default:console.error(`Unknown stash action: ${n}`),console.error(`Actions: set, get, list, delete, clear`),process.exit(1)}}},{name:`lane`,description:`Manage verified lanes — isolated file copies for parallel exploration`,usage:`kb lane <create|list|status|diff|merge|discard> [name] [--files f1,f2]`,run:async t=>{let n=t.shift();if((!n||![`create`,`list`,`status`,`diff`,`merge`,`discard`].includes(n))&&(console.error(`Usage: kb lane <create|list|status|diff|merge|discard> [name] [--files f1,f2]`),process.exit(1)),n===`list`){let e=d();if(e.length===0){console.log(`No active lanes.`);return}for(let t of e)console.log(`${t.name}  (${t.sourceFiles.length} files, created ${t.createdAt})`);return}let r=t.shift();switch(r||(console.error(`Lane name is required for "${n}".`),process.exit(1)),n){case`create`:{let n=e(t,`--files`,``);n||(console.error(`Usage: kb lane create <name> --files file1.ts,file2.ts`),process.exit(1));let i=c(r,n.split(`,`).map(e=>e.trim()));console.log(`Lane "${i.name}" created with ${i.sourceFiles.length} files.`);break}case`status`:{let e=p(r);console.log(`Lane: ${e.name}`),console.log(`Modified: ${e.modified} | Added: ${e.added} | Deleted: ${e.deleted}`);for(let t of e.entries)console.log(`  ${t.status.padEnd(10)} ${t.file}`);break}case`diff`:{let e=l(r);console.log(`Lane: ${e.name} — ${e.modified} modified, ${e.added} added, ${e.deleted} deleted`);for(let t of e.entries)t.diff&&(console.log(`\n--- ${t.file} (${t.status})`),console.log(t.diff));break}case`merge`:{let e=f(r);console.log(`Merged ${e.filesMerged} files from lane "${e.name}".`);for(let t of e.files)console.log(`  ${t}`);break}case`discard`:{let e=u(r);console.log(e?`Lane "${r}" discarded.`:`Lane "${r}" not found.`);break}}}},{name:`queue`,description:`Manage task queues for sequential agent operations`,usage:`kb queue <create|push|next|done|fail|get|list|clear|delete> [name] [args]`,run:async e=>{let t=e.shift();if((!t||![`create`,`push`,`next`,`done`,`fail`,`get`,`list`,`clear`,`delete`].includes(t))&&(console.error(`Usage: kb queue <create|push|next|done|fail|get|list|clear|delete> [name] [args]`),process.exit(1)),t===`list`){let e=x();if(e.length===0){console.log(`No queues.`);return}for(let t of e)console.log(`${t.name}  pending:${t.pending} done:${t.done} failed:${t.failed} total:${t.total}`);return}let n=e.shift();switch(n||(console.error(`Queue name is required for "${t}".`),process.exit(1)),t){case`create`:{let e=g(n);console.log(`Queue "${e.name}" created.`);break}case`push`:{let t=C(n,e.join(` `)||`Untitled task`);console.log(`Pushed "${t.title}" (${t.id}) to queue "${n}".`);break}case`next`:{let e=S(n);console.log(e?`Next: ${e.title} (${e.id})`:`No pending items in queue "${n}".`);break}case`done`:{let t=e.shift();t||(console.error(`Usage: kb queue done <name> <id>`),process.exit(1));let r=v(n,t);console.log(`Marked "${r.title}" as done.`);break}case`fail`:{let t=e.shift(),r=e.join(` `)||`Unknown error`;t||(console.error(`Usage: kb queue fail <name> <id> [error message]`),process.exit(1));let i=y(n,t,r);console.log(`Marked "${i.title}" as failed: ${r}`);break}case`get`:{let e=b(n);if(!e){console.log(`Queue "${n}" not found.`);return}console.log(`Queue: ${e.name} (${e.items.length} items)`);for(let t of e.items){let e=t.error?` — ${t.error}`:``;console.log(`  ${t.status.padEnd(12)} ${t.id}  ${t.title}${e}`)}break}case`clear`:{let e=h(n);console.log(`Cleared ${e} completed/failed items from queue "${n}".`);break}case`delete`:{let e=_(n);console.log(e?`Queue "${n}" deleted.`:`Queue "${n}" not found.`);break}}}}];export{j as workspaceCommands};
-//# sourceMappingURL=workspace.js.map
+import{extractStrFlag as e,parseMaybeJsonString as t,printWorkset as n,readStdin as r,splitCsv as i}from"../helpers.js";import{addToWorkset as a,deleteWorkset as o,getWorkset as s,laneCreate as c,laneDiff as l,laneDiscard as u,laneList as d,laneMerge as f,laneStatus as p,listWorksets as m,queueClear as h,queueCreate as g,queueDelete as _,queueDone as v,queueFail as y,queueGet as b,queueList as x,queueNext as S,queuePush as C,removeFromWorkset as w,saveWorkset as T,stashClear as E,stashDelete as D,stashGet as O,stashList as k,stashSet as A}from"../../../tools/dist/index.js";const j=[{name:`workset`,description:`Manage saved file sets`,usage:`kb workset <action> [name] [--files f1,f2] [--description desc]`,run:async t=>{let r=t.shift()?.trim(),c=i(e(t,`--files`,``)),l=e(t,`--description`,``).trim()||void 0,u=t.shift()?.trim();switch(r||(console.error(`Usage: kb workset <action> [name] [--files f1,f2] [--description desc]`),console.error(`Actions: save, get, list, delete, add, remove`),process.exit(1)),r){case`save`:{(!u||c.length===0)&&(console.error(`Usage: kb workset save <name> --files f1,f2 [--description desc]`),process.exit(1));let e=T(u,c,{description:l});console.log(`Saved workset: ${e.name}`),n(e);return}case`get`:{u||(console.error(`Usage: kb workset get <name>`),process.exit(1));let e=s(u);if(!e){console.log(`No workset found: ${u}`);return}n(e);return}case`list`:{let e=m();if(e.length===0){console.log(`No worksets saved.`);return}console.log(`Worksets (${e.length})`),console.log(`─`.repeat(60));for(let t of e)n(t),console.log(``);return}case`delete`:{u||(console.error(`Usage: kb workset delete <name>`),process.exit(1));let e=o(u);console.log(e?`Deleted workset: ${u}`:`No workset found: ${u}`);return}case`add`:{(!u||c.length===0)&&(console.error(`Usage: kb workset add <name> --files f1,f2`),process.exit(1));let e=a(u,c);console.log(`Updated workset: ${e.name}`),n(e);return}case`remove`:{(!u||c.length===0)&&(console.error(`Usage: kb workset remove <name> --files f1,f2`),process.exit(1));let e=w(u,c);if(!e){console.log(`No workset found: ${u}`);return}console.log(`Updated workset: ${e.name}`),n(e);return}default:console.error(`Unknown workset action: ${r}`),console.error(`Actions: save, get, list, delete, add, remove`),process.exit(1)}}},{name:`stash`,description:`Persist and retrieve named intermediate values`,usage:`kb stash <set|get|list|delete|clear> [key] [value]`,run:async e=>{let n=e.shift()?.trim(),i=e.shift()?.trim();switch(n||(console.error(`Usage: kb stash <set|get|list|delete|clear> [key] [value]`),process.exit(1)),n){case`set`:{i||(console.error(`Usage: kb stash set <key> <value>`),process.exit(1));let n=e.join(` `),a=n.trim()?``:await r(),o=A(i,t(n||a));console.log(`Stored stash entry: ${o.key}`),console.log(`  Type: ${o.type}`),console.log(`  Stored: ${o.storedAt}`);return}case`get`:{i||(console.error(`Usage: kb stash get <key>`),process.exit(1));let e=O(i);if(!e){console.log(`No stash entry found: ${i}`);return}console.log(JSON.stringify(e,null,2));return}case`list`:{let e=k();if(e.length===0){console.log(`No stash entries saved.`);return}console.log(`Stash entries (${e.length})`),console.log(`─`.repeat(60));for(let t of e)console.log(`${t.key} (${t.type})`),console.log(`  Stored: ${t.storedAt}`);return}case`delete`:{i||(console.error(`Usage: kb stash delete <key>`),process.exit(1));let e=D(i);console.log(e?`Deleted stash entry: ${i}`:`No stash entry found: ${i}`);return}case`clear`:{let e=E();console.log(`Cleared ${e} stash entr${e===1?`y`:`ies`}.`);return}default:console.error(`Unknown stash action: ${n}`),console.error(`Actions: set, get, list, delete, clear`),process.exit(1)}}},{name:`lane`,description:`Manage verified lanes — isolated file copies for parallel exploration`,usage:`kb lane <create|list|status|diff|merge|discard> [name] [--files f1,f2]`,run:async t=>{let n=t.shift();if((!n||![`create`,`list`,`status`,`diff`,`merge`,`discard`].includes(n))&&(console.error(`Usage: kb lane <create|list|status|diff|merge|discard> [name] [--files f1,f2]`),process.exit(1)),n===`list`){let e=d();if(e.length===0){console.log(`No active lanes.`);return}for(let t of e)console.log(`${t.name}  (${t.sourceFiles.length} files, created ${t.createdAt})`);return}let r=t.shift();switch(r||(console.error(`Lane name is required for "${n}".`),process.exit(1)),n){case`create`:{let n=e(t,`--files`,``);n||(console.error(`Usage: kb lane create <name> --files file1.ts,file2.ts`),process.exit(1));let i=c(r,n.split(`,`).map(e=>e.trim()));console.log(`Lane "${i.name}" created with ${i.sourceFiles.length} files.`);break}case`status`:{let e=p(r);console.log(`Lane: ${e.name}`),console.log(`Modified: ${e.modified} | Added: ${e.added} | Deleted: ${e.deleted}`);for(let t of e.entries)console.log(`  ${t.status.padEnd(10)} ${t.file}`);break}case`diff`:{let e=l(r);console.log(`Lane: ${e.name} — ${e.modified} modified, ${e.added} added, ${e.deleted} deleted`);for(let t of e.entries)t.diff&&(console.log(`\n--- ${t.file} (${t.status})`),console.log(t.diff));break}case`merge`:{let e=f(r);console.log(`Merged ${e.filesMerged} files from lane "${e.name}".`);for(let t of e.files)console.log(`  ${t}`);break}case`discard`:{let e=u(r);console.log(e?`Lane "${r}" discarded.`:`Lane "${r}" not found.`);break}}}},{name:`queue`,description:`Manage task queues for sequential agent operations`,usage:`kb queue <create|push|next|done|fail|get|list|clear|delete> [name] [args]`,run:async e=>{let t=e.shift();if((!t||![`create`,`push`,`next`,`done`,`fail`,`get`,`list`,`clear`,`delete`].includes(t))&&(console.error(`Usage: kb queue <create|push|next|done|fail|get|list|clear|delete> [name] [args]`),process.exit(1)),t===`list`){let e=x();if(e.length===0){console.log(`No queues.`);return}for(let t of e)console.log(`${t.name}  pending:${t.pending} done:${t.done} failed:${t.failed} total:${t.total}`);return}let n=e.shift();switch(n||(console.error(`Queue name is required for "${t}".`),process.exit(1)),t){case`create`:{let e=g(n);console.log(`Queue "${e.name}" created.`);break}case`push`:{let t=C(n,e.join(` `)||`Untitled task`);console.log(`Pushed "${t.title}" (${t.id}) to queue "${n}".`);break}case`next`:{let e=S(n);console.log(e?`Next: ${e.title} (${e.id})`:`No pending items in queue "${n}".`);break}case`done`:{let t=e.shift();t||(console.error(`Usage: kb queue done <name> <id>`),process.exit(1));let r=v(n,t);console.log(`Marked "${r.title}" as done.`);break}case`fail`:{let t=e.shift(),r=e.join(` `)||`Unknown error`;t||(console.error(`Usage: kb queue fail <name> <id> [error message]`),process.exit(1));let i=y(n,t,r);console.log(`Marked "${i.title}" as failed: ${r}`);break}case`get`:{let e=b(n);if(!e){console.log(`Queue "${n}" not found.`);return}console.log(`Queue: ${e.name} (${e.items.length} items)`);for(let t of e.items){let e=t.error?` — ${t.error}`:``;console.log(`  ${t.status.padEnd(12)} ${t.id}  ${t.title}${e}`)}break}case`clear`:{let e=h(n);console.log(`Cleared ${e} completed/failed items from queue "${n}".`);break}case`delete`:{let e=_(n);console.log(e?`Queue "${n}" deleted.`:`Queue "${n}" not found.`);break}}}}];export{j as workspaceCommands};

package/packages/cli/dist/context.d.ts

@@ -4,5 +4,4 @@ import { KBContext } from "./kb-init.js";
 declare function ctx(): Promise<KBContext>;
 declare function getCtx(): KBContext | null;
 //#endregion
-export { type KBContext, ctx, getCtx };
-//# sourceMappingURL=context.d.ts.map
+export { type KBContext, ctx, getCtx };

package/packages/cli/dist/context.js

@@ -1,2 +1 @@
-import{initKB as e}from"./kb-init.js";let t=null;async function n(){return t||=await e(),t}function r(){return t}export{n as ctx,r as getCtx};
-//# sourceMappingURL=context.js.map
+import{initKB as e}from"./kb-init.js";let t=null;async function n(){return t||=await e(),t}function r(){return t}export{n as ctx,r as getCtx};

package/packages/cli/dist/helpers.d.ts

@@ -52,5 +52,4 @@ declare function parseRecordString(value: string): Record<string, unknown>;
 declare function rrf(vecResults: SearchResult[], ftsResults: SearchResult[], k?: number): SearchResult[];
 declare function executeCliBatchOperation(operation: BatchOperation, context: KBContext | null): Promise<unknown>;
 //#endregion
-export { executeCliBatchOperation, extractBoolFlag, extractNumFlag, extractStrFlag, formatFocusRanges, parseBatchPayload, parseMaybeJsonString, parseRecordString, printCheckResult, printCheckSection, printCheckpoint, printDeadSymbolsResult, printDiffFiles, printExamplesResult, printFileSummary, printGitContext, printManagedProcess, printParsedOutput, printSection, printSymbolInfo, printTestRunResult, printTraceResult, printWorkset, readInput, readStdin, rrf, splitCsv, validateBatchOperations };
-//# sourceMappingURL=helpers.d.ts.map
+export { executeCliBatchOperation, extractBoolFlag, extractNumFlag, extractStrFlag, formatFocusRanges, parseBatchPayload, parseMaybeJsonString, parseRecordString, printCheckResult, printCheckSection, printCheckpoint, printDeadSymbolsResult, printDiffFiles, printExamplesResult, printFileSummary, printGitContext, printManagedProcess, printParsedOutput, printSection, printSymbolInfo, printTestRunResult, printTraceResult, printWorkset, readInput, readStdin, rrf, splitCsv, validateBatchOperations };