@vpxa/kb 0.1.13 → 0.1.15

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

@@ -1,10 +1,15 @@
+//#region packages/cli/src/commands/init.d.ts
 /**
  * `kb init` — scaffold a knowledge base in the current directory.
  * Creates kb.config.json, .gitignore entry, optional IDE config,
  * agent instruction files (.github/copilot-instructions.md, AGENTS.md),
- * and skills/knowledge-base/SKILL.md.
+ * and .github/skills/ (knowledge-base, brainstorming).
  */
-export declare function initProject(options: {
-    force: boolean;
+declare function initProject(options: {
+  force: boolean;
 }): Promise<void>;
+/** Generate a JSON guide report comparing installed vs source files. */
+declare function guideProject(): Promise<void>;
+//#endregion
+export { guideProject, initProject };
 //# sourceMappingURL=init.d.ts.map

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

@@ -1,4 +1,4 @@
-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
+import{appendFileSync as e,copyFileSync as t,existsSync as n,mkdirSync as r,readFileSync as i,readdirSync as a,statSync as o,writeFileSync as s}from"node:fs";import{basename as c,dirname as l,resolve as u}from"node:path";import{fileURLToPath as d}from"node:url";const f={serverName:`knowledge-base`,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 p(e){return{servers:{[e]:{type:`stdio`,command:`npx`,args:[`@vpxa/kb`,`serve`]}}}}function m(e,t){let n=e=>e;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.
 
@@ -7,8 +7,8 @@ This project uses **@vpxa/kb** as an MCP knowledge base server. The KB provides
 ### 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>" })
+${n(`search`)}({ query: "<task keywords>" })
+${n(`scope_map`)}({ task: "<what you are doing>" })
 \`\`\`
 
 ### 2. ALWAYS compress context before reading large files
@@ -16,77 +16,77 @@ Do NOT read entire files into context. Use these tools to reduce tokens and focu
 
 | 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 |
+| 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 |
 
-**Example \u2014 reading a 400-line file:**
+**Example — 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" })
+${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 \`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
+- **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 |
 |------|------|-------------|
-| \`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) |
+| \`${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) |
 
 ### 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
+${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
 \`\`\`
 
 ### 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
+${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
 \`\`\`
 
 ## Quick Workflow
 
 \`\`\`
 # 1. Orient
-kb_search({ query: "task keywords" })
-kb_scope_map({ task: "what you are doing" })
+${n(`search`)}({ query: "task keywords" })
+${n(`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" })
+${n(`file_summary`)}({ path: "relevant-file.ts" })
+${n(`compact`)}({ path: "relevant-file.ts", query: "specific concern" })
 
 # 3. Do the work
 
 # 4. Validate
-kb_check({})
-kb_test_run({})
+${n(`check`)}({})
+${n(`test_run`)}({})
 
 # 5. Persist
-kb_remember({ title: "What I learned", content: "...", category: "decisions" })
+${n(`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
+- **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 h(e,t){let n=e=>e;return`# ${e} — Agent Instructions
 
 ## KB Knowledge Base
 
@@ -95,25 +95,26 @@ This project has a **@vpxa/kb** MCP server providing search, analysis, memory, a
 ### Skills Reference
 
 | Context | Skill | Details |
-|---------|-------|---------|
-| KB search, analysis, memory | \`kb\` | See [skills/knowledge-base/SKILL.md](skills/knowledge-base/SKILL.md) or run \`kb_status({})\` |
+|---------|-------|--------|
+| 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) |
 
 ### Available Tool Categories
 
 | Category | Tools | Purpose |
 |----------|-------|---------|
-| 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\`, \`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. \`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_guide\`, \`kb_onboard\`, \`kb_graph\`, \`kb_queue\`, \`kb_replay\` | Index management, health checks, tool discovery, knowledge graph |
+| 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 |
 
 ---
 
@@ -121,23 +122,23 @@ This project has a **@vpxa/kb** MCP server providing search, analysis, memory, a
 
 **Every agent interaction MUST minimize context window usage.** Raw file reads waste tokens and degrade LLM output quality. Use these tools instead:
 
-### Decision Tree \u2014 How to Read Code
+### Decision Tree — How to Read Code
 
 \`\`\`
 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
+├─ 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 \`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
+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
 
 ---
 
@@ -147,24 +148,24 @@ Need to understand a file?
 
 ### 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
+${n(`status`)}({})                                              # Verify KB is ready
+${n(`list`)}()                                                  # See what knowledge exists
+${n(`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 |
+| 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)
 \`\`\`
-kb_remember({
+${n(`remember`)}({
   title: "Session checkpoint: <topic>",
   content: "<what was done, decisions made, blockers, next steps>",
   category: "conventions"
@@ -174,10 +175,10 @@ kb_remember({
 ### 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)
+├─ 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
 \`\`\`
 
@@ -189,12 +190,12 @@ Is this data temporary (scratch, intermediate)?
 
 \`\`\`
 # 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?
+${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?
 \`\`\`
 
-If \`kb_search\` returns a prior decision about the topic, you MUST follow it or explicitly explain why you're deviating.
+If \`${n(`search`)}\` returns a prior decision about the topic, you MUST follow it or explicitly explain why you're deviating.
 
 ---
 
@@ -203,10 +204,10 @@ If \`kb_search\` returns a prior decision about the topic, you MUST follow it or
 **NEVER commit or present code without validation.**
 
 \`\`\`
-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)
+${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)
 \`\`\`
 
 ---
@@ -216,9 +217,9 @@ kb_audit({})                                    # Unified project audit (structu
 For tasks touching 3+ files or involving architectural decisions:
 
 \`\`\`
-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
+${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
 \`\`\`
 
 ---
@@ -227,9 +228,9 @@ kb_evidence_map({ claims: ["claim1", "claim2"] })   # Track verified vs assumed
 
 | 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" })\` |
+| \`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\`.
 
@@ -239,41 +240,41 @@ Filters: \`origin\` (\`indexed\`/\`curated\`/\`produced\`), \`category\`, \`cont
 
 **Codebase onboarding:**
 \`\`\`
-kb_onboard({ path: "." }) \u2192 kb_produce_knowledge({ path: "src/" }) \u2192 kb_remember(...)
+${n(`onboard`)}({ path: "." }) → ${n(`produce_knowledge`)}({ path: "src/" }) → ${n(`remember`)}(...)
 \`\`\`
 
 **Planning a task:**
 \`\`\`
-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: [...] })
+${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:**
 \`\`\`
-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"] })
+${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:**
 \`\`\`
-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" })
+${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:**
 \`\`\`
-kb_blast_radius({ changed_files: ["src/file.ts"] })
-\u2192 kb_check({}) \u2192 kb_test_run({})
-\u2192 kb_reindex({})
-\u2192 kb_remember(...)
+${n(`blast_radius`)}({ changed_files: ["src/file.ts"] })
+→ ${n(`check`)}({}) → ${n(`test_run`)}({})
+→ ${n(`reindex`)}({})
+→ ${n(`remember`)}(...)
 \`\`\`
 
 ---
@@ -291,18 +292,14 @@ kb_blast_radius({ changed_files: ["src/file.ts"] })
 
 ## Core Rules Summary
 
-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\`
+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** \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")):(r(a,`# Knowledge base vector store
-.kb-data/
-`,"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};
+6. **Use FORGE for complex tasks** — \`forge_classify\` → \`forge_ground\` → \`evidence_map\`
+`}function g(e,i,s=``,c=!1){r(i,{recursive:!0});for(let r of a(e)){let a=u(e,r),l=u(i,r),d=s?`${s}/${r}`:r;if(o(a).isDirectory())g(a,l,d,c);else if(c||!n(l)){let e=n(l)?`Updated`:`Created`;t(a,l),console.log(`  ${e} .github/${d}`)}}}function _(e,t,r,s){if(n(e))for(let c of a(e)){let a=u(e,c),l=r?`${r}/${c}`:c;if(o(a).isDirectory())_(a,u(t,c),l,s);else{let e=u(t,c),r=i(a,`utf-8`);n(e)?r===i(e,`utf-8`)?s.push({status:`current`,relativePath:l,sourcePath:a}):s.push({status:`outdated`,relativePath:l,sourcePath:a,content:r}):s.push({status:`new`,relativePath:l,sourcePath:a,content:r})}}}async function v(t){let a=process.cwd(),o=u(a,`kb.config.json`);if(n(o)&&!t.force){console.log(`kb.config.json already exists. Use --force to overwrite.`);return}s(o,`${JSON.stringify(f,null,2)}\n`,`utf-8`),console.log(`  Created kb.config.json`);let _=u(a,`curated`);n(_)||(r(_,{recursive:!0}),console.log(`  Created curated/`));let v=u(a,`.gitignore`),y=[{dir:`.kb-data/`,label:`Knowledge base vector store`},{dir:`.brainstorm/`,label:`Brainstorming sessions`},{dir:`curated/`,label:`Curated knowledge entries`}];if(n(v)){let t=i(v,`utf-8`),n=y.filter(e=>!t.includes(e.dir));n.length>0&&(e(v,`\n${n.map(e=>`# ${e.label}\n${e.dir}`).join(`
+`)}\n`,`utf-8`),console.log(`  Added ${n.map(e=>e.dir).join(`, `)} to .gitignore`))}else s(v,`${y.map(e=>`# ${e.label}\n${e.dir}`).join(`
+`)}\n`,`utf-8`),console.log(`  Created .gitignore with KB entries`);let b=c(a),x=f.serverName,S=u(a,`.vscode`),C=u(S,`mcp.json`);n(S)&&!n(C)&&(s(C,`${JSON.stringify(p(x),null,2)}\n`,`utf-8`),console.log(`  Created .vscode/mcp.json`));let w=u(a,`.github`),T=u(w,`copilot-instructions.md`);n(T)||(r(w,{recursive:!0}),s(T,m(b,x),`utf-8`),console.log(`  Created .github/copilot-instructions.md`));let E=u(a,`AGENTS.md`);n(E)||(s(E,h(b,x),`utf-8`),console.log(`  Created AGENTS.md`));let D=u(l(d(import.meta.url)),`..`,`..`,`..`,`..`);for(let e of[`knowledge-base`,`brainstorming`]){let r=u(D,`skills`,e);n(r)&&g(r,u(a,`.github`,`skills`,e),`skills/${e}`,t.force)}let O=u(D,`scaffold`,`copilot`);for(let e of[`agents`,`prompts`]){let r=u(O,e),i=u(a,`.github`,e);n(r)&&g(r,i,``,t.force)}for(let e of[`decisions`,`patterns`,`conventions`,`troubleshooting`]){let t=u(_,e);n(t)||r(t,{recursive:!0})}console.log(`  Created curated/{decisions,patterns,conventions,troubleshooting}/`),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`)}async function y(){let e=process.cwd(),t=u(l(d(import.meta.url)),`..`,`..`,`..`,`..`),r=[];for(let i of[`knowledge-base`,`brainstorming`]){let a=u(t,`skills`,i);n(a)&&_(a,u(e,`.github`,`skills`,i),`skills/${i}`,r)}let i=u(t,`scaffold`,`copilot`);for(let t of[`agents`,`prompts`])_(u(i,t),u(e,`.github`,t),t,r);let a={summary:{total:r.length,new:r.filter(e=>e.status===`new`).length,outdated:r.filter(e=>e.status===`outdated`).length,current:r.filter(e=>e.status===`current`).length},files:r};console.log(JSON.stringify(a,null,2))}export{y as guideProject,v as initProject};
+//# sourceMappingURL=init.js.map

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

@@ -1,3 +1,7 @@
-import type { Command } from '../types.js';
-export declare const knowledgeCommands: Command[];
+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

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

@@ -1 +1,2 @@
-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};
+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

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

@@ -1,3 +1,7 @@
-import type { Command } from '../types.js';
-export declare const searchCommands: Command[];
+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

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

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

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

@@ -1,3 +1,7 @@
-import type { Command } from '../types.js';
-export declare const systemCommands: Command[];
+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