@vpxa/kb 0.1.12 → 0.1.15

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

@@ -1,147 +1,92 @@
-import{appendFileSync as p,existsSync as o,mkdirSync as u,readFileSync as m,writeFileSync as a}from"node:fs";import{basename as g,resolve as t}from"node:path";const h={sources:[{path:".",excludePatterns:["**/node_modules/**","**/dist/**","**/build/**","**/.git/**","**/.kb-data/**","**/coverage/**","**/*.min.js","**/package-lock.json","**/pnpm-lock.yaml"]}],indexing:{chunkSize:1500,chunkOverlap:200,minChunkSize:100},embedding:{model:"mixedbread-ai/mxbai-embed-large-v1",dimensions:1024},store:{backend:"lancedb",path:".kb-data/lance"},curated:{path:"curated"}};function f(e){return{servers:{[`${e}-kb`]:{type:"stdio",command:"npx",args:["@vpxa/kb","serve"]}}}}function y(e){return`# ${e} \u2014 Copilot Instructions
-
-This project uses **@vpxa/kb** as an MCP knowledge base server. Use the KB tools to search, analyze, and understand the codebase before making changes.
-
-## KB Tools
-
-Before starting any task on **${e}**, use these MCP tools:
-
-| Action | Tool | Example |
-|--------|------|---------|
-| Search code & decisions | \`kb_search\` | \`kb_search({ query: "..." })\` |
-| Find symbol definition | \`kb_symbol\` | \`kb_symbol({ name: "ClassName" })\` |
-| Plan what to read | \`kb_scope_map\` | \`kb_scope_map({ task: "..." })\` |
-| Trace call chains | \`kb_trace\` | \`kb_trace({ symbol: "fn", file: "path" })\` |
-| Impact of a change | \`kb_blast_radius\` | \`kb_blast_radius({ changed_files: ["..."] })\` |
-| Persist what you learn | \`kb_remember\` | \`kb_remember({ title: "...", category: "decisions" })\` |
-| Typecheck + lint | \`kb_check\` | \`kb_check({})\` |
-| Run tests | \`kb_test_run\` | \`kb_test_run({})\` |
-
-## Workflow
-
-\`\`\`
-kb_search({ query: "your task keywords" })            # Recall prior decisions
-kb_scope_map({ task: "what you are doing" })           # Get a reading plan
-# ... do the work ...
-kb_check({})                                           # Typecheck + lint
-kb_test_run({})                                        # Run tests
-kb_remember({ title: "What I learned", category: "decisions" })  # Persist
-\`\`\`
-
-## KB MCP Tools \u2014 Complete Reference
-
-### Search & Discovery
-| Tool | Purpose |
-|------|---------|
-| \`kb_search\` | Hybrid vector + keyword search. Modes: \`hybrid\` (default), \`semantic\`, \`keyword\`. Filters: \`origin\`, \`category\`, \`content_type\`, \`tags\`. |
-| \`kb_find\` | Federated search: vector + FTS + glob + regex in one call. |
-| \`kb_symbol\` | Resolve symbol definition, imports, and all references across files. |
-| \`kb_lookup\` | Full-file retrieval by path or record ID. |
-| \`kb_scope_map\` | Task-scoped reading plan with file list and token estimates. |
-| \`kb_trace\` | Forward/backward flow tracing through call chains. |
-| \`kb_find_examples\` | Find real usage examples of a symbol or pattern. |
-| \`kb_dead_symbols\` | Find exported symbols that are never imported anywhere. |
-| \`kb_file_summary\` | Structural overview of a file (exports, imports, functions). |
-
-### Code Analysis
-| Tool | Purpose |
-|------|---------|
-| \`kb_analyze_structure\` | Project structure overview with file tree and stats. |
-| \`kb_analyze_dependencies\` | Dependency graph with confidence scoring. |
-| \`kb_analyze_symbols\` | Symbol extraction and cross-references. |
-| \`kb_analyze_patterns\` | Design pattern detection (Singleton, Factory, etc.). |
-| \`kb_analyze_entry_points\` | Discover entry points (Lambda handlers, CLI, HTTP routes). |
-| \`kb_analyze_diagram\` | Generate Mermaid architecture diagrams. |
-| \`kb_blast_radius\` | Change impact analysis \u2014 what breaks if you modify a file. |
-
-### Knowledge Management
-| Tool | Purpose |
-|------|---------|
-| \`kb_remember\` | Store a curated knowledge entry (decisions, patterns, conventions). |
-| \`kb_read\` | Read a curated entry by path. |
-| \`kb_update\` | Update an existing curated entry. |
-| \`kb_forget\` | Delete a curated entry (requires reason). |
-| \`kb_list\` | List curated entries, filterable by category and tags. |
-| \`kb_produce_knowledge\` | Auto-generate knowledge from codebase analysis. |
-
-### Execution & Validation
-| Tool | Purpose |
-|------|---------|
-| \`kb_check\` | Incremental typecheck + lint in one call (tsc + biome). |
-| \`kb_test_run\` | Run tests with structured pass/fail results. |
-| \`kb_eval\` | Sandboxed JavaScript/TypeScript execution. |
-| \`kb_batch\` | Execute multiple operations in parallel. |
-
-### Code Manipulation
-| Tool | Purpose |
-|------|---------|
-| \`kb_rename\` | Smart whole-word symbol rename across files (dry-run supported). |
-| \`kb_codemod\` | Regex-based code transformations with rule files (dry-run supported). |
-| \`kb_diff_parse\` | Parse unified diff into structured file changes. |
-| \`kb_data_transform\` | JQ-like JSON transformations. |
-
-### Context Management
-| Tool | Purpose |
-|------|---------|
-| \`kb_compact\` | Compress text to relevant sections using embeddings (no LLM). |
-| \`kb_workset\` | Named file set management (save/load/add/remove working sets). |
-| \`kb_stash\` | Named key-value store for session data. |
-| \`kb_checkpoint\` | Save/restore lightweight session checkpoints. |
-| \`kb_parse_output\` | Parse build tool output (tsc, vitest, biome, git) into structured JSON. |
-
-### FORGE & Context Compression
-| Tool | Purpose |
-|------|---------|
-| \`kb_forge_ground\` | Full FORGE Ground phase (classify + scope + constraints + evidence). |
-| \`kb_forge_classify\` | Quick FORGE tier classification (Floor/Standard/Critical). |
-| \`kb_evidence_map\` | Track critical-path claims as Verified/Assumed/Unknown with receipts. |
-| \`kb_digest\` | Compress multiple text blocks into token-budgeted digest. |
-| \`kb_stratum_card\` | Generate T1/T2 context cards (10-100x token reduction). |
-
-### Web & Network
-| Tool | Purpose |
-|------|---------|
-| \`kb_web_fetch\` | Fetch web page \u2192 LLM-optimized markdown. CSS selectors, 4 modes, smart truncation. |
-| \`kb_web_search\` | Search the web via DuckDuckGo (no API key needed). |
-| \`kb_http\` | HTTP requests (GET/POST/PUT/PATCH/DELETE) for API testing with timing. |
-
-### Verified Lanes
-| Tool | Purpose |
-|------|---------|
-| \`kb_lane\` | Manage isolated file copies for parallel exploration. Actions: \`create\`, \`list\`, \`status\`, \`diff\`, \`merge\`, \`discard\`. |
-
-### Git & Environment
-| Tool | Purpose |
-|------|---------|
-| \`kb_git_context\` | Branch, status, recent commits, optional diff stats. |
-| \`kb_process\` | Process supervisor (start/stop/logs). |
-| \`kb_watch\` | Filesystem watcher for auto-triggered workflows. |
-| \`kb_delegate\` | Delegate subtask to a local Ollama model. |
-
-### Developer Utilities
-| Tool | Purpose |
-|------|---------|
-| \`kb_regex_test\` | Test regex patterns with match/replace/split modes. |
-| \`kb_encode\` | Base64, URL, SHA-256, MD5, hex encode/decode, JWT decode. |
-| \`kb_measure\` | Code complexity metrics (cyclomatic complexity, line counts). |
-| \`kb_changelog\` | Generate changelog from git history (conventional commits). |
-| \`kb_schema_validate\` | Validate JSON data against JSON Schema. |
-| \`kb_snippet\` | Save/get/search/delete persistent code snippets. |
-| \`kb_env\` | System and runtime environment info (sensitive values redacted). |
-| \`kb_time\` | Date parsing, timezone conversion, duration math. |
-
-### System
-| Tool | Purpose |
-|------|---------|
-| \`kb_status\` | Index statistics (record count, file count, content types). |
-| \`kb_reindex\` | Rebuild the vector index from configured sources. |
-| \`kb_health\` | Project health checks (package.json, tsconfig, lockfile, etc.). |
-| \`kb_onboard\` | First-time codebase onboarding \u2014 runs all analyses, auto-persists results. |
-| \`kb_graph\` | Knowledge graph queries (find_nodes, find_edges, neighbors, traverse, stats). |
-| \`kb_queue\` | Task queue for sequential agent operations. |
-| \`kb_replay_list\` | View audit trail of tool invocations. |
-| \`kb_replay_clear\` | Clear the replay audit trail. |
-`}function w(e){return`# ${e} \u2014 Agent Instructions
+import{appendFileSync as 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.
+
+## Mandatory Rules
+
+### 1. ALWAYS search before acting
+Before writing or modifying code, you MUST recall prior decisions and understand the affected area:
+\`\`\`
+${n(`search`)}({ query: "<task keywords>" })
+${n(`scope_map`)}({ task: "<what you are doing>" })
+\`\`\`
+
+### 2. ALWAYS compress context before reading large files
+Do NOT read entire files into context. Use these tools to reduce tokens and focus on what matters:
+
+| Situation | Tool | Why |
+|-----------|------|-----|
+| Need relevant sections of a large file | \`${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 — 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) |
+
+### 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
+\`\`\`
+
+### 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
+\`\`\`
+
+## 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" })
+\`\`\`
+
+## Context Budget Rules
+
+- **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
 
@@ -150,100 +95,211 @@ 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_find_examples\`, \`kb_dead_symbols\`, \`kb_file_summary\` | Find code, symbols, data flow, reading plans |
-| Code Analysis | \`kb_analyze_structure\`, \`kb_analyze_dependencies\`, \`kb_analyze_symbols\`, \`kb_analyze_patterns\`, \`kb_analyze_entry_points\`, \`kb_analyze_diagram\`, \`kb_blast_radius\` | Structure, deps, patterns, impact, diagrams |
-| Knowledge | \`kb_remember\`, \`kb_read\`, \`kb_update\`, \`kb_forget\`, \`kb_list\`, \`kb_produce_knowledge\` | Persistent cross-session memory |
-| Execution | \`kb_check\`, \`kb_test_run\`, \`kb_eval\`, \`kb_batch\` | Typecheck, lint, test, run code |
-| 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 |
-| FORGE | \`kb_forge_ground\`, \`kb_forge_classify\`, \`kb_evidence_map\`, \`kb_digest\`, \`kb_stratum_card\` | Quality gates, context compression |
-| Web & API | \`kb_web_fetch\`, \`kb_web_search\`, \`kb_http\` | Fetch pages, search web, test APIs |
-| Lanes | \`kb_lane\` | Isolated file copies for parallel exploration (create/list/status/diff/merge/discard) |
-| Git & Environment | \`kb_git_context\`, \`kb_process\`, \`kb_watch\`, \`kb_delegate\` | Git info, process management |
-| Utilities | \`kb_regex_test\`, \`kb_encode\`, \`kb_measure\`, \`kb_changelog\`, \`kb_schema_validate\`, \`kb_snippet\`, \`kb_env\`, \`kb_time\` | Regex, encoding, metrics, validation |
-| System | \`kb_status\`, \`kb_reindex\`, \`kb_health\`, \`kb_onboard\`, \`kb_graph\`, \`kb_queue\`, \`kb_replay_list\`, \`kb_replay_clear\` | Index management, health checks, knowledge graph |
+| 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 |
+
+---
+
+## MANDATORY: Context Reduction Protocol
 
-### Search Modes
+**Every agent interaction MUST minimize context window usage.** Raw file reads waste tokens and degrade LLM output quality. Use these tools instead:
 
-The \`kb_search\` tool supports three search strategies via the \`search_mode\` parameter:
+### Decision Tree — How to Read Code
 
-- **\`hybrid\`** (default) \u2014 Vector similarity + full-text keyword search merged via Reciprocal Rank Fusion. Best for most queries.
-- **\`semantic\`** \u2014 Pure vector cosine similarity. Best for conceptual/meaning-based queries.
-- **\`keyword\`** \u2014 Full-text search only. Best for exact identifiers, function names, specific strings.
+\`\`\`
+Need to understand a file?
+├─ 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
+\`\`\`
+
+### 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
+\`\`\`
 
-Additional filters: \`origin\` (\`indexed\`/\`curated\`/\`produced\`), \`category\`, \`content_type\`, \`tags\`, \`min_score\`.
+---
 
-### Session Protocol
+## MANDATORY: Search-Before-Act Protocol
+
+**NEVER write or modify code without first searching for context.**
 
-**Start of session:**
 \`\`\`
-kb_status({})
-kb_search({ query: "SESSION CHECKPOINT", origin: "curated" })
+# Before ANY code change:
+${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?
 \`\`\`
 
-**During session:**
+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.**
+
 \`\`\`
-kb_search \u2192 kb_scope_map \u2192 kb_symbol \u2192 kb_trace       # Orient
-kb_check \u2192 kb_test_run                                  # Validate changes
-kb_remember                                             # Capture insights
+${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)
 \`\`\`
 
-**End of session:**
+---
+
+## FORGE Protocol (for complex tasks)
+
+For tasks touching 3+ files or involving architectural decisions:
+
 \`\`\`
-kb_remember({ title: "Session checkpoint: <topic>", content: "<summary>", category: "conventions" })
+${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
 \`\`\`
 
-### Workflow Chains
+---
+
+## Search Modes
+
+| 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\`.
+
+---
+
+## Workflow Chains
 
 **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_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_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`)}(...)
 \`\`\`
 
-### Knowledge Categories
+---
+
+## Knowledge Categories
+
+| Category | What to store |
+|----------|---------------|
+| \`decisions\` | Architecture choices, trade-offs, rejected alternatives |
+| \`patterns\` | Code patterns, naming conventions, structural patterns |
+| \`conventions\` | Session checkpoints, workflow conventions, team agreements |
+| \`troubleshooting\` | Non-obvious fixes, debugging strategies, workarounds |
 
-\`decisions\` | \`patterns\` | \`conventions\` | \`troubleshooting\`
+---
 
-### Core Rules
+## Core Rules Summary
 
-- Search KB for prior decisions before proposing new ones
-- Follow \`_Next:\` hints in tool responses for guided workflows
-- Use \`kb_check\` and \`kb_test_run\` to validate before committing
-- Use \`kb_remember\` to persist architecture decisions and lessons learned
-- Analysis results are auto-persisted as \`origin: "produced"\` entries
-`}async function P(e){const s=process.cwd(),i=t(s,"kb.config.json");if(o(i)&&!e.force){console.log("kb.config.json already exists. Use --force to overwrite.");return}a(i,`${JSON.stringify(h,null,2)}
-`,"utf-8"),console.log("  Created kb.config.json");const c=t(s,"curated");o(c)||(u(c,{recursive:!0}),console.log("  Created curated/"));const r=t(s,".gitignore");o(r)?m(r,"utf-8").includes(".kb-data")||(p(r,`
-# Knowledge base vector store
-.kb-data/
-`,"utf-8"),console.log("  Added .kb-data/ to .gitignore")):(a(r,`# Knowledge base vector store
-.kb-data/
-`,"utf-8"),console.log("  Created .gitignore with .kb-data/"));const n=g(s),l=t(s,".vscode"),d=t(l,"mcp.json");o(l)&&!o(d)&&(a(d,`${JSON.stringify(f(n),null,2)}
-`,"utf-8"),console.log("  Created .vscode/mcp.json"));const b=t(s,".github"),k=t(b,"copilot-instructions.md");o(k)||(u(b,{recursive:!0}),a(k,y(n),"utf-8"),console.log("  Created .github/copilot-instructions.md"));const _=t(s,"AGENTS.md");o(_)||(a(_,w(n),"utf-8"),console.log("  Created AGENTS.md")),console.log(`
-Knowledge base initialized! Next steps:`),console.log("  kb reindex     Index your codebase"),console.log("  kb search      Search indexed content"),console.log("  kb serve       Start MCP server for IDE integration")}export{P as initProject};
+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\`
+`}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 i}from"../context.js";import{extractNumFlag as p,extractStrFlag as c,readStdin as l,splitCsv as d}from"../helpers.js";const f=[{name:"remember",description:"Store curated knowledge",usage:"kb remember <title> --category <cat> [--tags tag1,tag2]",run:async t=>{const o=c(t,"--category","").trim(),a=d(c(t,"--tags","")),e=t.shift()?.trim()??"",r=await l(),n=r.trim().length>0?r:t.join(" ").trim();(!e||!o||!n.trim())&&(console.error("Usage: kb remember <title> --category <cat> [--tags tag1,tag2]"),process.exit(1));const{curated:s}=await i(),g=await s.remember(e,n,o,a);console.log("Stored curated entry"),console.log(`  Path: ${g.path}`),console.log(`  Category: ${o}`),a.length>0&&console.log(`  Tags: ${a.join(", ")}`)}},{name:"forget",description:"Remove a curated entry",usage:"kb forget <path> --reason <reason>",run:async t=>{const o=c(t,"--reason","").trim(),a=t.shift()?.trim()??"";(!a||!o)&&(console.error("Usage: kb forget <path> --reason <reason>"),process.exit(1));const{curated:e}=await i(),r=await e.forget(a,o);console.log(`Removed curated entry: ${r.path}`)}},{name:"read",description:"Read a curated entry",usage:"kb read <path>",run:async t=>{const o=t.shift()?.trim()??"";o||(console.error("Usage: kb read <path>"),process.exit(1));const{curated:a}=await i(),e=await a.read(o);console.log(e.title),console.log("\u2500".repeat(60)),console.log(`Path: ${e.path}`),console.log(`Category: ${e.category}`),console.log(`Version: ${e.version}`),console.log(`Tags: ${e.tags.length>0?e.tags.join(", "):"None"}`),console.log(""),console.log(e.content)}},{name:"list",description:"List curated entries",usage:"kb list [--category <cat>] [--tag <tag>]",run:async t=>{const o=c(t,"--category","").trim()||void 0,a=c(t,"--tag","").trim()||void 0,{curated:e}=await i(),r=await e.list({category:o,tag:a});if(r.length===0){console.log("No curated entries found.");return}console.log(`Curated entries (${r.length})`),console.log("\u2500".repeat(60));for(const n of r){console.log(n.path),console.log(`  ${n.title}`),console.log(`  Category: ${n.category} | Version: ${n.version}`),console.log(`  Tags: ${n.tags.length>0?n.tags.join(", "):"None"}`);const s=n.contentPreview.replace(/\s+/g," ").trim();s&&console.log(`  Preview: ${s}`),console.log("")}}},{name:"update",description:"Update a curated entry",usage:"kb update <path> --reason <reason>",run:async t=>{const o=c(t,"--reason","").trim(),a=t.shift()?.trim()??"",e=await l();(!a||!o||!e.trim())&&(console.error("Usage: kb update <path> --reason <reason>"),process.exit(1));const{curated:r}=await i(),n=await r.update(a,e,o);console.log("Updated curated entry"),console.log(`  Path: ${n.path}`),console.log(`  Version: ${n.version}`)}},{name:"compact",description:"Compress text for context",usage:"kb compact <query> [--max-chars N] [--segmentation paragraph|sentence|line]",run:async t=>{const o=p(t,"--max-chars",3e3),a=c(t,"--segmentation","paragraph"),e=t.join(" ").trim(),r=await l();(!e||!r.trim())&&(console.error("Usage: kb compact <query> [--max-chars N] [--segmentation paragraph|sentence|line]"),process.exit(1));const{embedder:n}=await i(),s=await m(n,{text:r,query:e,maxChars:o,segmentation:a});console.log(`Compressed ${s.originalChars} chars to ${s.compressedChars} chars`),console.log(`Ratio: ${(s.ratio*100).toFixed(1)}% | Segments: ${s.segmentsKept}/${s.segmentsTotal}`),console.log(""),console.log(s.text)}}];export{f as knowledgeCommands};
+import{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