@vpxa/kb 0.1.13 → 0.1.15

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

@@ -1,3 +1,3 @@
-import{resolve as p}from"node:path";const d=[{name:"analyze",description:"Run analyzer output for a path",usage:"kb analyze <type> <path>",run:async r=>{const i=r.shift()?.trim()??"",a=r.shift()?.trim()??"";(!i||!a)&&(console.error("Usage: kb analyze <type> <path>"),console.error("Types: structure, deps, symbols, patterns, entry-points, blast-radius, diagram"),process.exit(1));const{BlastRadiusAnalyzer:l,DependencyAnalyzer:c,DiagramGenerator:m,EntryPointAnalyzer:n,PatternAnalyzer:e,StructureAnalyzer:t,SymbolAnalyzer:u}=await import("../../../analyzers/dist/index.js"),s=p(a);let o;switch(i){case"structure":o=await new t().analyze(s,{format:"markdown"});break;case"deps":case"dependencies":o=await new c().analyze(s,{format:"markdown"});break;case"symbols":o=await new u().analyze(s,{format:"markdown"});break;case"patterns":o=await new e().analyze(s,{format:"markdown"});break;case"entry-points":o=await new n().analyze(s,{format:"markdown"});break;case"blast-radius":o=await new l().analyze(process.cwd(),{files:[a],format:"markdown"});break;case"diagram":o=await new m().analyze(s,{diagramType:"architecture"});break;default:console.error(`Unknown analyze type: ${i}`),console.error("Types: structure, deps, symbols, patterns, entry-points, blast-radius, diagram"),process.exit(1)}console.log(o.output)}},{name:"onboard",description:"Run all analyses for first-time codebase onboarding",usage:"kb onboard <path> [--generate] [--out-dir <dir>]",run:async r=>{const{onboard:i}=await import("../../../tools/dist/index.js");let a="",l="memory",c;for(let e=0;e<r.length;e++){const t=r[e].trim();t==="--generate"?l="generate":t==="--out-dir"&&e+1<r.length?c=r[++e].trim():t.startsWith("--")||(a=t)}a||(a=process.cwd());const m=p(a);console.log(`Onboarding: ${m} (mode: ${l})`),console.log(`Running analyses...
-`);const n=await i({path:m,mode:l,outDir:c});for(const e of n.steps){const t=e.status==="success"?"\u2713":"\u2717",u=e.status==="success"?`${e.durationMs}ms, ${e.output.length} chars`:e.error;console.log(`  ${t} ${e.name} \u2014 ${u}`)}console.log(`
-Total: ${n.totalDurationMs}ms`),n.outDir&&console.log(`Output written to: ${n.outDir}`)}}];export{d as analyzeCommands};
+import{resolve as e}from"node:path";const t=[{name:`analyze`,description:`Run analyzer output for a path`,usage:`kb analyze <type> <path>`,run:async t=>{let n=t.shift()?.trim()??``,r=t.shift()?.trim()??``;(!n||!r)&&(console.error(`Usage: kb analyze <type> <path>`),console.error(`Types: structure, deps, symbols, patterns, entry-points, blast-radius, diagram`),process.exit(1));let{BlastRadiusAnalyzer:i,DependencyAnalyzer:a,DiagramGenerator:o,EntryPointAnalyzer:s,PatternAnalyzer:c,StructureAnalyzer:l,SymbolAnalyzer:u}=await import(`../../../analyzers/dist/index.js`),d=e(r),f;switch(n){case`structure`:f=await new l().analyze(d,{format:`markdown`});break;case`deps`:case`dependencies`:f=await new a().analyze(d,{format:`markdown`});break;case`symbols`:f=await new u().analyze(d,{format:`markdown`});break;case`patterns`:f=await new c().analyze(d,{format:`markdown`});break;case`entry-points`:f=await new s().analyze(d,{format:`markdown`});break;case`blast-radius`:f=await new i().analyze(process.cwd(),{files:[r],format:`markdown`});break;case`diagram`:f=await new o().analyze(d,{diagramType:`architecture`});break;default:console.error(`Unknown analyze type: ${n}`),console.error(`Types: structure, deps, symbols, patterns, entry-points, blast-radius, diagram`),process.exit(1)}console.log(f.output)}},{name:`onboard`,description:`Run all analyses for first-time codebase onboarding`,usage:`kb onboard <path> [--generate] [--out-dir <dir>]`,run:async t=>{let{onboard:n}=await import(`../../../tools/dist/index.js`),r=``,i=`memory`,a;for(let e=0;e<t.length;e++){let n=t[e].trim();n===`--generate`?i=`generate`:n===`--out-dir`&&e+1<t.length?a=t[++e].trim():n.startsWith(`--`)||(r=n)}r||=process.cwd();let o=e(r);console.log(`Onboarding: ${o} (mode: ${i})`),console.log(`Running analyses...
+`);let s=await n({path:o,mode:i,outDir:a});for(let e of s.steps){let t=e.status===`success`?`✓`:`✗`,n=e.status===`success`?`${e.durationMs}ms, ${e.output.length} chars`:e.error;console.log(`  ${t} ${e.name} — ${n}`)}console.log(`\nTotal: ${s.totalDurationMs}ms`),s.outDir&&console.log(`Output written to: ${s.outDir}`)}}];export{t as analyzeCommands};
+//# sourceMappingURL=analyze.js.map

package/packages/cli/dist/commands/context-cmds.d.ts

@@ -1,3 +1,7 @@
-import type { Command } from '../types.js';
-export declare const contextCommands: Command[];
+import { Command } from "../types.js";
+
+//#region packages/cli/src/commands/context-cmds.d.ts
+declare const contextCommands: Command[];
+//#endregion
+export { contextCommands };
 //# sourceMappingURL=context-cmds.d.ts.map

package/packages/cli/dist/commands/context-cmds.js

@@ -1 +1,2 @@
-import{resolve as p}from"node:path";import{checkpointLatest as d,checkpointList as u,checkpointLoad as f,checkpointSave as m,diffParse as h,fileSummary as k,gitContext as g,parseOutput as b}from"../../../tools/dist/index.js";import{extractBoolFlag as x,extractNumFlag as w,extractStrFlag as i,parseRecordString as v,printCheckpoint as c,printDiffFiles as y,printFileSummary as C,printGitContext as S,printParsedOutput as U,readStdin as a}from"../helpers.js";const P=[{name:"parse-output",description:"Parse build or tool output from stdin",usage:"kb parse-output [--tool tsc|vitest|biome|git-status]",run:async e=>{const s=i(e,"--tool","").trim()||void 0,t=await a();t.trim()||(console.error("Usage: kb parse-output [--tool tsc|vitest|biome|git-status]"),process.exit(1)),U(b(t,s))}},{name:"git",description:"Show git branch, status, recent commits, and optional diff stats",usage:"kb git [--cwd path] [--commit-count N] [--diff]",run:async e=>{const s=i(e,"--cwd","").trim()||void 0,t=w(e,"--commit-count",5),o=x(e,"--diff"),n=await g({cwd:s,commitCount:t,includeDiff:o});S(n)}},{name:"diff",description:"Parse unified diff text from stdin into structured file changes",usage:"git diff | kb diff",run:async()=>{const e=await a();e.trim()||(console.error("Usage: git diff | kb diff"),process.exit(1)),y(h({diff:e}))}},{name:"summarize",description:"Show a structural summary of a file",usage:"kb summarize <path>",run:async e=>{const s=e.shift()?.trim();s||(console.error("Usage: kb summarize <path>"),process.exit(1));const t=await k({path:p(s)});C(t)}},{name:"checkpoint",description:"Save and restore lightweight session checkpoints",usage:"kb checkpoint <save|load|list|latest> [label-or-id] [--data json] [--notes text]",run:async e=>{const s=e.shift()?.trim();switch(s||(console.error("Usage: kb checkpoint <save|load|list|latest> [label-or-id] [--data json] [--notes text]"),process.exit(1)),s){case"save":{const t=e.shift()?.trim(),o=i(e,"--data",""),n=i(e,"--notes","").trim()||void 0,r=o.trim()?"":await a();t||(console.error("Usage: kb checkpoint save <label> [--data json] [--notes text]"),process.exit(1));const l=m(t,v(o||r),{notes:n});c(l);return}case"load":{const t=e.shift()?.trim();t||(console.error("Usage: kb checkpoint load <id>"),process.exit(1));const o=f(t);if(!o){console.log(`No checkpoint found: ${t}`);return}c(o);return}case"list":{const t=u();if(t.length===0){console.log("No checkpoints saved.");return}console.log(`Checkpoints (${t.length})`),console.log("\u2500".repeat(60));for(const o of t)console.log(`${o.id}`),console.log(`  Label: ${o.label}`),console.log(`  Created: ${o.createdAt}`);return}case"latest":{const t=d();if(!t){console.log("No checkpoints saved.");return}c(t);return}default:console.error(`Unknown checkpoint action: ${s}`),console.error("Actions: save, load, list, latest"),process.exit(1)}}}];export{P as contextCommands};
+import{extractBoolFlag as e,extractNumFlag as t,extractStrFlag as n,parseRecordString as r,printCheckpoint as i,printDiffFiles as a,printFileSummary as o,printGitContext as s,printParsedOutput as c,readStdin as l}from"../helpers.js";import{resolve as u}from"node:path";import{checkpointLatest as d,checkpointList as f,checkpointLoad as p,checkpointSave as m,diffParse as h,fileSummary as g,gitContext as _,parseOutput as v}from"../../../tools/dist/index.js";const y=[{name:`parse-output`,description:`Parse build or tool output from stdin`,usage:`kb parse-output [--tool tsc|vitest|biome|git-status]`,run:async e=>{let t=n(e,`--tool`,``).trim()||void 0,r=await l();r.trim()||(console.error(`Usage: kb parse-output [--tool tsc|vitest|biome|git-status]`),process.exit(1)),c(v(r,t))}},{name:`git`,description:`Show git branch, status, recent commits, and optional diff stats`,usage:`kb git [--cwd path] [--commit-count N] [--diff]`,run:async r=>{s(await _({cwd:n(r,`--cwd`,``).trim()||void 0,commitCount:t(r,`--commit-count`,5),includeDiff:e(r,`--diff`)}))}},{name:`diff`,description:`Parse unified diff text from stdin into structured file changes`,usage:`git diff | kb diff`,run:async()=>{let e=await l();e.trim()||(console.error(`Usage: git diff | kb diff`),process.exit(1)),a(h({diff:e}))}},{name:`summarize`,description:`Show a structural summary of a file`,usage:`kb summarize <path>`,run:async e=>{let t=e.shift()?.trim();t||(console.error(`Usage: kb summarize <path>`),process.exit(1)),o(await g({path:u(t)}))}},{name:`checkpoint`,description:`Save and restore lightweight session checkpoints`,usage:`kb checkpoint <save|load|list|latest> [label-or-id] [--data json] [--notes text]`,run:async e=>{let t=e.shift()?.trim();switch(t||(console.error(`Usage: kb checkpoint <save|load|list|latest> [label-or-id] [--data json] [--notes text]`),process.exit(1)),t){case`save`:{let t=e.shift()?.trim(),a=n(e,`--data`,``),o=n(e,`--notes`,``).trim()||void 0,s=a.trim()?``:await l();t||(console.error(`Usage: kb checkpoint save <label> [--data json] [--notes text]`),process.exit(1)),i(m(t,r(a||s),{notes:o}));return}case`load`:{let t=e.shift()?.trim();t||(console.error(`Usage: kb checkpoint load <id>`),process.exit(1));let n=p(t);if(!n){console.log(`No checkpoint found: ${t}`);return}i(n);return}case`list`:{let e=f();if(e.length===0){console.log(`No checkpoints saved.`);return}console.log(`Checkpoints (${e.length})`),console.log(`─`.repeat(60));for(let t of e)console.log(`${t.id}`),console.log(`  Label: ${t.label}`),console.log(`  Created: ${t.createdAt}`);return}case`latest`:{let e=d();if(!e){console.log(`No checkpoints saved.`);return}i(e);return}default:console.error(`Unknown checkpoint action: ${t}`),console.error(`Actions: save, load, list, latest`),process.exit(1)}}}];export{y as contextCommands};
+//# sourceMappingURL=context-cmds.js.map

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

@@ -1,3 +1,7 @@
-import type { Command } from '../types.js';
-export declare const environmentCommands: Command[];
+import { Command } from "../types.js";
+
+//#region packages/cli/src/commands/environment.d.ts
+declare const environmentCommands: Command[];
+//#endregion
+export { environmentCommands };
 //# sourceMappingURL=environment.d.ts.map

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

@@ -1,2 +1,2 @@
-import{readFile as h}from"node:fs/promises";import{resolve as d}from"node:path";import{delegate as g,delegateListModels as w,processList as $,processLogs as x,processStart as k,processStatus as y,processStop as b,watchList as S,watchStart as U,watchStop as N}from"../../../tools/dist/index.js";import{extractNumFlag as f,extractStrFlag as l,printManagedProcess as i,readStdin as v}from"../helpers.js";const L=[{name:"proc",description:"Manage in-memory child processes",usage:"kb proc <start|stop|status|list|logs> ...",run:async e=>{const s=e.shift()?.trim()??"";switch(s){case"start":{const o=e.shift()?.trim(),t=e.shift()?.trim();(!o||!t)&&(console.error("Usage: kb proc start <id> <command> [args...]"),process.exit(1)),i(k(o,t,e));return}case"stop":{const o=e.shift()?.trim();o||(console.error("Usage: kb proc stop <id>"),process.exit(1));const t=b(o);if(!t){console.log(`No managed process found: ${o}`);return}i(t);return}case"status":{const o=e.shift()?.trim();o||(console.error("Usage: kb proc status <id>"),process.exit(1));const t=y(o);if(!t){console.log(`No managed process found: ${o}`);return}i(t);return}case"list":{const o=$();if(o.length===0){console.log("No managed processes.");return}for(const t of o)i(t),console.log("");return}case"logs":{const o=f(e,"--tail",50),t=e.shift()?.trim();t||(console.error("Usage: kb proc logs <id> [--tail N]"),process.exit(1));const n=x(t,o);if(n.length===0){console.log(`No logs found for process: ${t}`);return}for(const c of n)console.log(c);return}default:console.error(`Unknown proc action: ${s}`),console.error("Actions: start, stop, status, list, logs"),process.exit(1)}}},{name:"watch",description:"Manage in-memory filesystem watchers",usage:"kb watch <start|stop|list> ...",run:async e=>{const s=e.shift()?.trim()??"";switch(s){case"start":{const o=e.shift()?.trim();o||(console.error("Usage: kb watch start <path>"),process.exit(1));const t=U({path:d(o)});console.log(`Started watcher: ${t.id}`),console.log(`  Path: ${t.path}`),console.log(`  Status: ${t.status}`);return}case"stop":{const o=e.shift()?.trim();o||(console.error("Usage: kb watch stop <id>"),process.exit(1));const t=N(o);console.log(t?`Stopped watcher: ${o}`:`Watcher not found: ${o}`);return}case"list":{const o=S();if(o.length===0){console.log("No active watchers.");return}for(const t of o)console.log(`${t.id}`),console.log(`  Path: ${t.path}`),console.log(`  Status: ${t.status}`),console.log(`  Events: ${t.eventCount}`);return}default:console.error(`Unknown watch action: ${s}`),console.error("Actions: start, stop, list"),process.exit(1)}}},{name:"delegate",description:"Delegate a task to a local Ollama model",usage:"kb delegate [--model name] [--system prompt] [--temp 0.3] <prompt | --stdin>",run:async e=>{if((e[0]==="models"?e.shift():void 0)==="models"){try{const p=await w();if(p.length===0){console.log("No Ollama models available. Pull one with: ollama pull qwen2.5-coder:7b");return}for(const u of p)console.log(u)}catch{console.error("Ollama is not running. Start it with: ollama serve"),process.exit(1)}return}const o=l(e,"--model",""),t=l(e,"--system",""),n=f(e,"--temp",.3),c=l(e,"--context","");let a=e.join(" ");a||(a=await v()),a||(console.error("Usage: kb delegate [--model name] <prompt>"),process.exit(1));let m;c&&(m=await h(d(c),"utf-8"));const r=await g({prompt:a,model:o||void 0,system:t||void 0,context:m,temperature:n});r.error&&(console.error(`Error: ${r.error}`),process.exit(1)),console.log(r.response),console.error(`
-(${r.model}, ${r.durationMs}ms, ${r.tokenCount??"?"} tokens)`)}}];export{L as environmentCommands};
+import{extractNumFlag as e,extractStrFlag as t,printManagedProcess as n,readStdin as r}from"../helpers.js";import{resolve as i}from"node:path";import{readFile as a}from"node:fs/promises";import{delegate as o,delegateListModels as s,processList as c,processLogs as l,processStart as u,processStatus as d,processStop as f,watchList as p,watchStart as m,watchStop as h}from"../../../tools/dist/index.js";const g=[{name:`proc`,description:`Manage in-memory child processes`,usage:`kb proc <start|stop|status|list|logs> ...`,run:async t=>{let r=t.shift()?.trim()??``;switch(r){case`start`:{let e=t.shift()?.trim(),r=t.shift()?.trim();(!e||!r)&&(console.error(`Usage: kb proc start <id> <command> [args...]`),process.exit(1)),n(u(e,r,t));return}case`stop`:{let e=t.shift()?.trim();e||(console.error(`Usage: kb proc stop <id>`),process.exit(1));let r=f(e);if(!r){console.log(`No managed process found: ${e}`);return}n(r);return}case`status`:{let e=t.shift()?.trim();e||(console.error(`Usage: kb proc status <id>`),process.exit(1));let r=d(e);if(!r){console.log(`No managed process found: ${e}`);return}n(r);return}case`list`:{let e=c();if(e.length===0){console.log(`No managed processes.`);return}for(let t of e)n(t),console.log(``);return}case`logs`:{let n=e(t,`--tail`,50),r=t.shift()?.trim();r||(console.error(`Usage: kb proc logs <id> [--tail N]`),process.exit(1));let i=l(r,n);if(i.length===0){console.log(`No logs found for process: ${r}`);return}for(let e of i)console.log(e);return}default:console.error(`Unknown proc action: ${r}`),console.error(`Actions: start, stop, status, list, logs`),process.exit(1)}}},{name:`watch`,description:`Manage in-memory filesystem watchers`,usage:`kb watch <start|stop|list> ...`,run:async e=>{let t=e.shift()?.trim()??``;switch(t){case`start`:{let t=e.shift()?.trim();t||(console.error(`Usage: kb watch start <path>`),process.exit(1));let n=m({path:i(t)});console.log(`Started watcher: ${n.id}`),console.log(`  Path: ${n.path}`),console.log(`  Status: ${n.status}`);return}case`stop`:{let t=e.shift()?.trim();t||(console.error(`Usage: kb watch stop <id>`),process.exit(1));let n=h(t);console.log(n?`Stopped watcher: ${t}`:`Watcher not found: ${t}`);return}case`list`:{let e=p();if(e.length===0){console.log(`No active watchers.`);return}for(let t of e)console.log(`${t.id}`),console.log(`  Path: ${t.path}`),console.log(`  Status: ${t.status}`),console.log(`  Events: ${t.eventCount}`);return}default:console.error(`Unknown watch action: ${t}`),console.error(`Actions: start, stop, list`),process.exit(1)}}},{name:`delegate`,description:`Delegate a task to a local Ollama model`,usage:`kb delegate [--model name] [--system prompt] [--temp 0.3] <prompt | --stdin>`,run:async n=>{if((n[0]===`models`?n.shift():void 0)===`models`){try{let e=await s();if(e.length===0){console.log(`No Ollama models available. Pull one with: ollama pull qwen2.5-coder:7b`);return}for(let t of e)console.log(t)}catch{console.error(`Ollama is not running. Start it with: ollama serve`),process.exit(1)}return}let c=t(n,`--model`,``),l=t(n,`--system`,``),u=e(n,`--temp`,.3),d=t(n,`--context`,``),f=n.join(` `);f||=await r(),f||(console.error(`Usage: kb delegate [--model name] <prompt>`),process.exit(1));let p;d&&(p=await a(i(d),`utf-8`));let m=await o({prompt:f,model:c||void 0,system:l||void 0,context:p,temperature:u});m.error&&(console.error(`Error: ${m.error}`),process.exit(1)),console.log(m.response),console.error(`\n(${m.model}, ${m.durationMs}ms, ${m.tokenCount??`?`} tokens)`)}}];export{g as environmentCommands};
+//# sourceMappingURL=environment.js.map

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

@@ -1,3 +1,7 @@
-import type { Command } from '../types.js';
-export declare const executionCommands: Command[];
+import { Command } from "../types.js";
+
+//#region packages/cli/src/commands/execution.d.ts
+declare const executionCommands: Command[];
+//#endregion
+export { executionCommands };
 //# sourceMappingURL=execution.d.ts.map

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

@@ -1 +1,2 @@
-import{readFile as f}from"node:fs/promises";import{resolve as l}from"node:path";import{codemod as x,dataTransform as g,evaluate as y,rename as h,testRun as w}from"../../../tools/dist/index.js";import{extractBoolFlag as d,extractNumFlag as u,extractStrFlag as a,printTestRunResult as b,readStdin as m,splitCsv as c}from"../helpers.js";const v=[{name:"eval",description:"Evaluate JavaScript or TypeScript in a constrained VM sandbox",usage:"kb eval [code] [--lang js|ts] [--timeout ms]",run:async e=>{const t=a(e,"--lang","js"),s=u(e,"--timeout",5e3),o=e.join(" "),r=o.trim()?"":await m(),n=o||r;n.trim()||(console.error("Usage: kb eval [code] [--lang js|ts] [--timeout ms]"),process.exit(1));const i=y({code:n,lang:t==="ts"?"ts":"js",timeout:s});if(!i.success){console.error(`Eval failed in ${i.durationMs}ms: ${i.error}`),process.exitCode=1;return}console.log(`Eval succeeded in ${i.durationMs}ms`),console.log("\u2500".repeat(60)),console.log(i.output)}},{name:"test",description:"Run Vitest for all tests or a specific subset",usage:"kb test [files...] [--grep pattern] [--cwd path] [--timeout ms]",run:async e=>{const t=a(e,"--grep","").trim()||void 0,s=a(e,"--cwd","").trim()||void 0,o=u(e,"--timeout",6e4),r=e.filter(Boolean),n=await w({files:r.length>0?r:void 0,grep:t,cwd:s,timeout:o});b(n),n.passed||(process.exitCode=1)}},{name:"rename",description:"Rename a symbol across files using whole-word regex matching",usage:"kb rename <old> <new> <path> [--dry-run] [--extensions .ts,.tsx] [--exclude dist/**]",run:async e=>{const t=e.shift()?.trim()??"",s=e.shift()?.trim()??"",o=e.shift()?.trim()??"";(!t||!s||!o)&&(console.error("Usage: kb rename <old> <new> <path> [--dry-run] [--extensions .ts,.tsx] [--exclude dist/**]"),process.exit(1));const r=c(a(e,"--extensions","")),n=c(a(e,"--exclude","")),i=await h({oldName:t,newName:s,rootPath:l(o),extensions:r.length>0?r:void 0,exclude:n.length>0?n:void 0,dryRun:d(e,"--dry-run")});console.log(JSON.stringify(i,null,2))}},{name:"codemod",description:"Apply regex-based codemod rules from a JSON file across a path",usage:"kb codemod <path> --rules <file.json> [--dry-run] [--extensions .ts,.tsx] [--exclude dist/**]",run:async e=>{const t=e.shift()?.trim()??"",s=a(e,"--rules","").trim();(!t||!s)&&(console.error("Usage: kb codemod <path> --rules <file.json> [--dry-run] [--extensions .ts,.tsx] [--exclude dist/**]"),process.exit(1));const o=await f(l(s),"utf-8"),r=JSON.parse(o);if(!Array.isArray(r))throw new Error("Codemod rules file must contain a JSON array.");const n=c(a(e,"--extensions","")),i=c(a(e,"--exclude","")),p=await x({rootPath:l(t),rules:r,extensions:n.length>0?n:void 0,exclude:i.length>0?i:void 0,dryRun:d(e,"--dry-run")});console.log(JSON.stringify(p,null,2))}},{name:"transform",description:"Apply jq-like transforms to JSON from stdin",usage:"cat data.json | kb transform <expression>",run:async e=>{const t=e.join(" ").trim(),s=await m();(!t||!s.trim())&&(console.error("Usage: cat data.json | kb transform <expression>"),process.exit(1));const o=g({input:s,expression:t});console.log(o.outputString)}}];export{v as executionCommands};
+import{extractBoolFlag as e,extractNumFlag as t,extractStrFlag as n,printTestRunResult as r,readStdin as i,splitCsv as a}from"../helpers.js";import{resolve as o}from"node:path";import{readFile as s}from"node:fs/promises";import{codemod as c,dataTransform as l,evaluate as u,rename as d,testRun as f}from"../../../tools/dist/index.js";const p=[{name:`eval`,description:`Evaluate JavaScript or TypeScript in a constrained VM sandbox`,usage:`kb eval [code] [--lang js|ts] [--timeout ms]`,run:async e=>{let r=n(e,`--lang`,`js`),a=t(e,`--timeout`,5e3),o=e.join(` `),s=o.trim()?``:await i(),c=o||s;c.trim()||(console.error(`Usage: kb eval [code] [--lang js|ts] [--timeout ms]`),process.exit(1));let l=u({code:c,lang:r===`ts`?`ts`:`js`,timeout:a});if(!l.success){console.error(`Eval failed in ${l.durationMs}ms: ${l.error}`),process.exitCode=1;return}console.log(`Eval succeeded in ${l.durationMs}ms`),console.log(`─`.repeat(60)),console.log(l.output)}},{name:`test`,description:`Run Vitest for all tests or a specific subset`,usage:`kb test [files...] [--grep pattern] [--cwd path] [--timeout ms]`,run:async e=>{let i=n(e,`--grep`,``).trim()||void 0,a=n(e,`--cwd`,``).trim()||void 0,o=t(e,`--timeout`,6e4),s=e.filter(Boolean),c=await f({files:s.length>0?s:void 0,grep:i,cwd:a,timeout:o});r(c),c.passed||(process.exitCode=1)}},{name:`rename`,description:`Rename a symbol across files using whole-word regex matching`,usage:`kb rename <old> <new> <path> [--dry-run] [--extensions .ts,.tsx] [--exclude dist/**]`,run:async t=>{let r=t.shift()?.trim()??``,i=t.shift()?.trim()??``,s=t.shift()?.trim()??``;(!r||!i||!s)&&(console.error(`Usage: kb rename <old> <new> <path> [--dry-run] [--extensions .ts,.tsx] [--exclude dist/**]`),process.exit(1));let c=a(n(t,`--extensions`,``)),l=a(n(t,`--exclude`,``)),u=await d({oldName:r,newName:i,rootPath:o(s),extensions:c.length>0?c:void 0,exclude:l.length>0?l:void 0,dryRun:e(t,`--dry-run`)});console.log(JSON.stringify(u,null,2))}},{name:`codemod`,description:`Apply regex-based codemod rules from a JSON file across a path`,usage:`kb codemod <path> --rules <file.json> [--dry-run] [--extensions .ts,.tsx] [--exclude dist/**]`,run:async t=>{let r=t.shift()?.trim()??``,i=n(t,`--rules`,``).trim();(!r||!i)&&(console.error(`Usage: kb codemod <path> --rules <file.json> [--dry-run] [--extensions .ts,.tsx] [--exclude dist/**]`),process.exit(1));let l=await s(o(i),`utf-8`),u;try{u=JSON.parse(l)}catch{throw Error(`Failed to parse rules file as JSON: ${i}`)}if(!Array.isArray(u))throw Error(`Codemod rules file must contain a JSON array.`);let d=a(n(t,`--extensions`,``)),f=a(n(t,`--exclude`,``)),p=await c({rootPath:o(r),rules:u,extensions:d.length>0?d:void 0,exclude:f.length>0?f:void 0,dryRun:e(t,`--dry-run`)});console.log(JSON.stringify(p,null,2))}},{name:`transform`,description:`Apply jq-like transforms to JSON from stdin`,usage:`cat data.json | kb transform <expression>`,run:async e=>{let t=e.join(` `).trim(),n=await i();(!t||!n.trim())&&(console.error(`Usage: cat data.json | kb transform <expression>`),process.exit(1));let r=l({input:n,expression:t});console.log(r.outputString)}}];export{p as executionCommands};
+//# sourceMappingURL=execution.js.map

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

@@ -1,3 +1,7 @@
-import type { Command } from '../types.js';
-export declare const graphCommands: Command[];
+import { Command } from "../types.js";
+
+//#region packages/cli/src/commands/graph.d.ts
+declare const graphCommands: Command[];
+//#endregion
+export { graphCommands };
 //# sourceMappingURL=graph.d.ts.map

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

@@ -1,7 +1,7 @@
-import{graphQuery as u}from"../../../tools/dist/index.js";import{ctx as $}from"../context.js";import{extractNumFlag as r,extractStrFlag as n}from"../helpers.js";const T=[{name:"graph",description:"Query the knowledge graph",usage:`kb graph <action> [options]
+import{ctx as e}from"../context.js";import{extractNumFlag as t,extractStrFlag as n}from"../helpers.js";import{graphQuery as r}from"../../../tools/dist/index.js";const i=[{name:`graph`,description:`Query the knowledge graph`,usage:`kb graph <action> [options]
   Actions: stats, find-nodes, find-edges, neighbors, traverse, delete, clear
-  Options: --type, --name, --node-id, --edge-type, --direction, --depth, --limit, --source-path`,run:async t=>{const s=t.shift()?.trim()??"";s||(console.error(`Usage: kb graph <action>
-Actions: stats, find-nodes, find-edges, neighbors, traverse, delete, clear`),process.exit(1));const{graphStore:a}=await $(),c=n(t,"--type",""),p=n(t,"--name",""),g=n(t,"--node-id",""),l=n(t,"--edge-type",""),f=n(t,"--direction","both"),m=r(t,"--depth",2),h=r(t,"--limit",50),y=n(t,"--source-path",""),i={stats:"stats","find-nodes":"find_nodes","find-edges":"find_edges",neighbors:"neighbors",traverse:"traverse",delete:"delete",clear:"clear"}[s];i||(console.error(`Unknown graph action: ${s}`),console.error("Actions: stats, find-nodes, find-edges, neighbors, traverse, delete, clear"),process.exit(1));const e=await u(a,{action:i,nodeType:c||void 0,namePattern:p||void 0,sourcePath:y||void 0,nodeId:g||void 0,edgeType:l||void 0,direction:f,maxDepth:m,limit:h});if(console.log(e.summary),e.nodes&&e.nodes.length>0){console.log(`
-Nodes:`);for(const o of e.nodes){const d=Object.keys(o.properties).length>0?` ${JSON.stringify(o.properties)}`:"";console.log(`  ${o.name} (${o.type}, id: ${o.id})${d}`)}}if(e.edges&&e.edges.length>0){console.log(`
-Edges:`);for(const o of e.edges){const d=o.weight!==1?` (weight: ${o.weight})`:"";console.log(`  ${o.fromId} --[${o.type}]--> ${o.toId}${d}`)}}e.stats&&(console.log(`
-Node types: ${JSON.stringify(e.stats.nodeTypes)}`),console.log(`Edge types: ${JSON.stringify(e.stats.edgeTypes)}`)),e.deleted!==void 0&&console.log(`Deleted: ${e.deleted}`)}}];export{T as graphCommands};
+  Options: --type, --name, --node-id, --edge-type, --direction, --depth, --limit, --source-path`,run:async i=>{let a=i.shift()?.trim()??``;a||(console.error(`Usage: kb graph <action>
+Actions: stats, find-nodes, find-edges, neighbors, traverse, delete, clear`),process.exit(1));let{graphStore:o}=await e(),s=n(i,`--type`,``),c=n(i,`--name`,``),l=n(i,`--node-id`,``),u=n(i,`--edge-type`,``),d=n(i,`--direction`,`both`),f=t(i,`--depth`,2),p=t(i,`--limit`,50),m=n(i,`--source-path`,``),h={stats:`stats`,"find-nodes":`find_nodes`,"find-edges":`find_edges`,neighbors:`neighbors`,traverse:`traverse`,delete:`delete`,clear:`clear`}[a];h||(console.error(`Unknown graph action: ${a}`),console.error(`Actions: stats, find-nodes, find-edges, neighbors, traverse, delete, clear`),process.exit(1));let g=await r(o,{action:h,nodeType:s||void 0,namePattern:c||void 0,sourcePath:m||void 0,nodeId:l||void 0,edgeType:u||void 0,direction:d,maxDepth:f,limit:p});if(console.log(g.summary),g.nodes&&g.nodes.length>0){console.log(`
+Nodes:`);for(let e of g.nodes){let t=Object.keys(e.properties).length>0?` ${JSON.stringify(e.properties)}`:``;console.log(`  ${e.name} (${e.type}, id: ${e.id})${t}`)}}if(g.edges&&g.edges.length>0){console.log(`
+Edges:`);for(let e of g.edges){let t=e.weight===1?``:` (weight: ${e.weight})`;console.log(`  ${e.fromId} --[${e.type}]--> ${e.toId}${t}`)}}g.stats&&(console.log(`\nNode types: ${JSON.stringify(g.stats.nodeTypes)}`),console.log(`Edge types: ${JSON.stringify(g.stats.edgeTypes)}`)),g.deleted!==void 0&&console.log(`Deleted: ${g.deleted}`)}}];export{i as graphCommands};
+//# sourceMappingURL=graph.js.map

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

@@ -0,0 +1,27 @@
+//#region packages/cli/src/commands/init/adapters.d.ts
+/**
+ * Init module — IDE adapter types and detection.
+ *
+ * Each IDE has different conventions for where agent files, MCP config,
+ * instructions, and skills live. This module defines the interface and
+ * provides auto-detection based on workspace markers.
+ */
+type SupportedIde = 'copilot' | 'claude-code';
+interface IdeAdapter {
+  /** Create the MCP server config file for this IDE. */
+  writeMcpConfig(cwd: string, serverName: string): void;
+  /** Create the main instructions file (copilot-instructions.md, CLAUDE.md). */
+  writeInstructions(cwd: string, serverName: string): void;
+  /** Create the AGENTS.md summary file. */
+  writeAgentsMd(cwd: string, serverName: string): void;
+  /** The scaffold subdirectory name to copy from. */
+  scaffoldDir: string;
+}
+/** Detect IDE from workspace directory markers. */
+declare function detectIde(cwd: string): SupportedIde;
+declare const copilotAdapter: IdeAdapter;
+declare const claudeCodeAdapter: IdeAdapter;
+declare function getAdapter(ide: SupportedIde): IdeAdapter;
+//#endregion
+export { IdeAdapter, SupportedIde, claudeCodeAdapter, copilotAdapter, detectIde, getAdapter };
+//# sourceMappingURL=adapters.d.ts.map

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

@@ -0,0 +1,2 @@
+import{buildAgentsMd as e,buildCopilotInstructions as t}from"./templates.js";import{existsSync as n,mkdirSync as r,writeFileSync as i}from"node:fs";import{basename as a,resolve as o}from"node:path";function s(e){return n(o(e,`.vscode`))?`copilot`:n(o(e,`.claude`))?`claude-code`:`copilot`}function c(e){return{servers:{[e]:{type:`stdio`,command:`npx`,args:[`@vpxa/kb`,`serve`]}}}}const l={scaffoldDir:`copilot`,writeMcpConfig(e,t){let r=o(e,`.vscode`),a=o(r,`mcp.json`);n(r)&&!n(a)&&(i(a,`${JSON.stringify(c(t),null,2)}\n`,`utf-8`),console.log(`  Created .vscode/mcp.json`))},writeInstructions(e,s){let c=o(e,`.github`),l=o(c,`copilot-instructions.md`);n(l)||(r(c,{recursive:!0}),i(l,t(a(e),s),`utf-8`),console.log(`  Created .github/copilot-instructions.md`))},writeAgentsMd(t,r){let s=o(t,`AGENTS.md`);n(s)||(i(s,e(a(t),r),`utf-8`),console.log(`  Created AGENTS.md`))}},u={scaffoldDir:`claude-code`,writeMcpConfig(e,t){},writeInstructions(e,t){},writeAgentsMd(e,t){}};function d(e){switch(e){case`copilot`:return l;case`claude-code`:return u}}export{u as claudeCodeAdapter,l as copilotAdapter,s as detectIde,d as getAdapter};
+//# sourceMappingURL=adapters.js.map

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

@@ -0,0 +1,11 @@
+//#region packages/cli/src/commands/init/config.d.ts
+/**
+ * Init module — config file creation.
+ * Handles kb.config.json, .gitignore, and MCP config files.
+ */
+declare function writeKbConfig(cwd: string, force: boolean): boolean;
+declare function ensureGitignore(cwd: string): void;
+declare function getServerName(): string;
+//#endregion
+export { ensureGitignore, getServerName, writeKbConfig };
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1,4 @@
+import{appendFileSync as e,existsSync as t,readFileSync as n,writeFileSync as r}from"node:fs";import{resolve as i}from"node:path";const a={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 o(e,n){let o=i(e,`kb.config.json`);return t(o)&&!n?(console.log(`kb.config.json already exists. Use --force to overwrite.`),!1):(r(o,`${JSON.stringify(a,null,2)}\n`,`utf-8`),console.log(`  Created kb.config.json`),!0)}function s(a){let o=i(a,`.gitignore`),s=[{dir:`.kb-data/`,label:`Knowledge base vector store`},{dir:`.brainstorm/`,label:`Brainstorming sessions`},{dir:`curated/`,label:`Curated knowledge entries`},{dir:`curated-archive/`,label:`Archived curated entries`}];if(t(o)){let t=n(o,`utf-8`),r=s.filter(e=>!t.includes(e.dir));r.length>0&&(e(o,`\n${r.map(e=>`# ${e.label}\n${e.dir}`).join(`
+`)}\n`,`utf-8`),console.log(`  Added ${r.map(e=>e.dir).join(`, `)} to .gitignore`))}else r(o,`${s.map(e=>`# ${e.label}\n${e.dir}`).join(`
+`)}\n`,`utf-8`),console.log(`  Created .gitignore with KB entries`)}function c(){return a.serverName}export{s as ensureGitignore,c as getServerName,o as writeKbConfig};
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1,8 @@
+//#region packages/cli/src/commands/init/curated.d.ts
+/**
+ * Init module — curated knowledge directories.
+ */
+declare function createCuratedDirs(cwd: string): void;
+//#endregion
+export { createCuratedDirs };
+//# sourceMappingURL=curated.d.ts.map

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

@@ -0,0 +1,2 @@
+import{existsSync as e,mkdirSync as t}from"node:fs";import{resolve as n}from"node:path";const r=[`decisions`,`patterns`,`conventions`,`troubleshooting`];function i(i){let a=n(i,`curated`);e(a)||(t(a,{recursive:!0}),console.log(`  Created curated/`));for(let i of r){let r=n(a,i);e(r)||t(r,{recursive:!0})}console.log(`  Created curated/{${r.join(`,`)}}/`)}export{i as createCuratedDirs};
+//# sourceMappingURL=curated.js.map

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

@@ -0,0 +1,23 @@
+//#region packages/cli/src/commands/init/index.d.ts
+/**
+ * `kb init` — scaffold a knowledge base in the current directory.
+ *
+ * Creates kb.config.json, .gitignore entry, IDE-specific config,
+ * agent instruction files, skills, scaffold agents/prompts,
+ * and curated knowledge directories.
+ *
+ * This is the main orchestrator that wires together the focused modules:
+ *   config.ts    — kb.config.json + .gitignore
+ *   adapters.ts  — IDE detection + adapter interface
+ *   scaffold.ts  — copy scaffold/skills files from package
+ *   curated.ts   — curated knowledge directories
+ *   templates.ts — copilot-instructions.md + AGENTS.md content
+ */
+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=index.d.ts.map

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

@@ -0,0 +1,3 @@
+import{detectIde as e,getAdapter as t}from"./adapters.js";import{ensureGitignore as n,getServerName as r,writeKbConfig as i}from"./config.js";import{createCuratedDirs as a}from"./curated.js";import{copyScaffold as o,copySkills as s,guideScaffold as c,guideSkills as l}from"./scaffold.js";import{dirname as u,resolve as d}from"node:path";import{fileURLToPath as f}from"node:url";const p=[`knowledge-base`,`brainstorming`];async function m(c){let l=process.cwd();if(!i(l,c.force))return;n(l);let m=r(),h=t(e(l));h.writeMcpConfig(l,m),h.writeInstructions(l,m),h.writeAgentsMd(l,m);let g=d(u(f(import.meta.url)),`..`,`..`,`..`,`..`,`..`);s(l,g,p,c.force),o(l,g,h.scaffoldDir,c.force),a(l),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 h(){let n=process.cwd(),r=t(e(n)),i=d(u(f(import.meta.url)),`..`,`..`,`..`,`..`,`..`),a=[...l(n,i,p),...c(n,i,r.scaffoldDir)],o={summary:{total:a.length,new:a.filter(e=>e.status===`new`).length,outdated:a.filter(e=>e.status===`outdated`).length,current:a.filter(e=>e.status===`current`).length},files:a};console.log(JSON.stringify(o,null,2))}export{h as guideProject,m as initProject};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,24 @@
+//#region packages/cli/src/commands/init/scaffold.d.ts
+/**
+ * Init module — scaffold file copying.
+ * Copies agent, prompt, and skill files from the package scaffold into the workspace.
+ */
+interface GuideFileEntry {
+  status: 'new' | 'outdated' | 'current';
+  relativePath: string;
+  sourcePath: string;
+  content?: string;
+}
+/** Recursively copy a directory. When force=false, skip files that already exist. */
+declare function copyDirectoryRecursive(srcDir: string, destDir: string, logPrefix?: string, force?: boolean): void;
+/** Copy scaffold files for a given IDE into the workspace .github/ directory. */
+declare function copyScaffold(cwd: string, pkgRoot: string, ide: string, force?: boolean): void;
+/** Copy skill directories from the package into .github/skills/. */
+declare function copySkills(cwd: string, pkgRoot: string, skillNames: string[], force?: boolean): void;
+/** Generate guide report for scaffold files — compare source vs destination. */
+declare function guideScaffold(cwd: string, pkgRoot: string, ide: string): GuideFileEntry[];
+/** Generate guide report for skill files — compare source vs destination. */
+declare function guideSkills(cwd: string, pkgRoot: string, skillNames: string[]): GuideFileEntry[];
+//#endregion
+export { GuideFileEntry, copyDirectoryRecursive, copyScaffold, copySkills, guideScaffold, guideSkills };
+//# sourceMappingURL=scaffold.d.ts.map

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

@@ -0,0 +1,2 @@
+import{copyFileSync as e,existsSync as t,mkdirSync as n,readFileSync as r,readdirSync as i,statSync as a}from"node:fs";import{resolve as o}from"node:path";function s(r,c,l=``,u=!1){n(c,{recursive:!0});for(let n of i(r)){let i=o(r,n),d=o(c,n),f=l?`${l}/${n}`:n;if(a(i).isDirectory())s(i,d,f,u);else if(u||!t(d)){let n=t(d)?`Updated`:`Created`;e(i,d),console.log(`  ${n} .github/${f}`)}}}function c(e,n,s,l){if(t(e))for(let u of i(e)){let i=o(e,u),d=s?`${s}/${u}`:u;if(a(i).isDirectory())c(i,o(n,u),d,l);else{let e=o(n,u),a=r(i,`utf-8`);t(e)?a===r(e,`utf-8`)?l.push({status:`current`,relativePath:d,sourcePath:i}):l.push({status:`outdated`,relativePath:d,sourcePath:i,content:a}):l.push({status:`new`,relativePath:d,sourcePath:i,content:a})}}}function l(e,n,r,i=!1){let a=o(n,`scaffold`,r);for(let n of[`agents`,`prompts`]){let r=o(a,n),c=o(e,`.github`,n);t(r)&&s(r,c,``,i)}}function u(e,n,r,i=!1){for(let a of r){let r=o(n,`skills`,a);t(r)&&s(r,o(e,`.github`,`skills`,a),`skills/${a}`,i)}}function d(e,t,n){let r=[],i=o(t,`scaffold`,n);for(let t of[`agents`,`prompts`])c(o(i,t),o(e,`.github`,t),t,r);return r}function f(e,n,r){let i=[];for(let a of r){let r=o(n,`skills`,a);t(r)&&c(r,o(e,`.github`,`skills`,a),`skills/${a}`,i)}return i}export{s as copyDirectoryRecursive,l as copyScaffold,u as copySkills,d as guideScaffold,f as guideSkills};
+//# sourceMappingURL=scaffold.js.map

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

@@ -0,0 +1,10 @@
+//#region packages/cli/src/commands/init/templates.d.ts
+/**
+ * Init module — instruction and AGENTS.md template builders.
+ * Content for copilot-instructions.md and AGENTS.md.
+ */
+declare function buildCopilotInstructions(projectName: string, _serverName: string): string;
+declare function buildAgentsMd(projectName: string, _serverName: string): string;
+//#endregion
+export { buildAgentsMd, buildCopilotInstructions };
+//# sourceMappingURL=templates.d.ts.map

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

@@ -0,0 +1,302 @@
+function e(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 t(e,t){let n=e=>e;return`# ${e} — Agent Instructions
+
+## KB Knowledge Base
+
+This project has a **@vpxa/kb** MCP server providing search, analysis, memory, and developer tools.
+
+### Skills Reference
+
+| Context | Skill | Details |
+|---------|-------|--------|
+| KB search, analysis, memory | \`kb\` | See [.github/skills/knowledge-base/SKILL.md](.github/skills/knowledge-base/SKILL.md) or run \`${n(`status`)}({})\` |
+| Brainstorming & design | \`brainstorming\` | See [.github/skills/brainstorming/SKILL.md](.github/skills/brainstorming/SKILL.md) |
+
+### Available Tool Categories
+
+| Category | Tools | Purpose |
+|----------|-------|---------|
+| Search & Discovery | \`${n(`search`)}\`, \`${n(`find`)}\`, \`${n(`symbol`)}\`, \`${n(`trace`)}\`, \`${n(`scope_map`)}\`, \`${n(`lookup`)}\`, \`${n(`dead_symbols`)}\`, \`${n(`file_summary`)}\` | Find code, symbols, data flow, reading plans |
+| Code Analysis | \`${n(`analyze_structure`)}\`, \`${n(`analyze_dependencies`)}\`, \`${n(`analyze_symbols`)}\`, \`${n(`analyze_patterns`)}\`, \`${n(`analyze_entry_points`)}\`, \`${n(`analyze_diagram`)}\`, \`${n(`blast_radius`)}\` | Structure, deps, patterns, impact, diagrams |
+| Knowledge | \`${n(`remember`)}\`, \`${n(`read`)}\`, \`${n(`update`)}\`, \`${n(`forget`)}\`, \`${n(`list`)}\`, \`${n(`produce_knowledge`)}\` | Persistent cross-session memory |
+| Execution | \`${n(`check`)}\`, \`${n(`test_run`)}\`, \`${n(`eval`)}\`, \`${n(`batch`)}\`, \`${n(`audit`)}\` | Typecheck, lint, test, run code, unified audit. \`check\` defaults to summary output (~300 tokens) |
+| Code Manipulation | \`${n(`rename`)}\`, \`${n(`codemod`)}\`, \`${n(`diff_parse`)}\`, \`${n(`data_transform`)}\` | Safe renames, transforms, diff parsing |
+| Context | \`${n(`compact`)}\`, \`${n(`workset`)}\`, \`${n(`stash`)}\`, \`${n(`checkpoint`)}\`, \`${n(`parse_output`)}\` | Manage working sets, save progress. \`compact\` accepts \`path\` for server-side file read |
+| FORGE | \`${n(`forge_ground`)}\`, \`${n(`forge_classify`)}\`, \`${n(`evidence_map`)}\`, \`${n(`digest`)}\`, \`${n(`stratum_card`)}\` | Quality gates, context compression |
+| Web & API | \`${n(`web_fetch`)}\`, \`${n(`web_search`)}\`, \`${n(`http`)}\` | Fetch pages, search web, test APIs |
+| Lanes | \`${n(`lane`)}\` | Isolated file copies for parallel exploration (create/list/status/diff/merge/discard) |
+| Git & Environment | \`${n(`git_context`)}\`, \`${n(`process`)}\`, \`${n(`watch`)}\`, \`${n(`delegate`)}\` | Git info, process management |
+| Utilities | \`${n(`regex_test`)}\`, \`${n(`encode`)}\`, \`${n(`measure`)}\`, \`${n(`changelog`)}\`, \`${n(`schema_validate`)}\`, \`${n(`snippet`)}\`, \`${n(`env`)}\`, \`${n(`time`)}\` | Regex, encoding, metrics, validation |
+| System | \`${n(`status`)}\`, \`${n(`reindex`)}\`, \`${n(`health`)}\`, \`${n(`guide`)}\`, \`${n(`onboard`)}\`, \`${n(`graph`)}\`, \`${n(`queue`)}\`, \`${n(`replay`)}\` | Index management, health checks, tool discovery, knowledge graph |
+
+---
+
+## MANDATORY: Context Reduction Protocol
+
+**Every agent interaction MUST minimize context window usage.** Raw file reads waste tokens and degrade LLM output quality. Use these tools instead:
+
+### Decision Tree — How to Read Code
+
+\`\`\`
+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
+\`\`\`
+
+---
+
+## MANDATORY: Search-Before-Act Protocol
+
+**NEVER write or modify code without first searching for context.**
+
+\`\`\`
+# 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?
+\`\`\`
+
+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.**
+
+\`\`\`
+${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)
+\`\`\`
+
+---
+
+## FORGE Protocol (for complex tasks)
+
+For tasks touching 3+ files or involving architectural decisions:
+
+\`\`\`
+${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
+\`\`\`
+
+---
+
+## 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:**
+\`\`\`
+${n(`onboard`)}({ path: "." }) → ${n(`produce_knowledge`)}({ path: "src/" }) → ${n(`remember`)}(...)
+\`\`\`
+
+**Planning a task:**
+\`\`\`
+${n(`search`)}({ query: "task keywords" })
+→ ${n(`scope_map`)}({ task: "description" })
+→ ${n(`file_summary`)} for each file in scope
+→ ${n(`compact`)}({ path: "relevant-file.ts", query: "detail needed" }) for files needing detail
+→ ${n(`workset`)}({ action: "save", name: "task", files: [...] })
+\`\`\`
+
+**Bug investigation:**
+\`\`\`
+${n(`parse_output`)}({ output: "<error>" })
+→ ${n(`symbol`)}({ name: "failingFn" })
+→ ${n(`trace`)}({ symbol: "failingFn", direction: "backward" })
+→ ${n(`blast_radius`)}({ changed_files: ["suspect.ts"] })
+\`\`\`
+
+**Safe refactor with lanes:**
+\`\`\`
+${n(`lane`)}({ action: "create", name: "refactor", files: [...] })
+→ [make changes]
+→ ${n(`lane`)}({ action: "diff", name: "refactor" })
+→ ${n(`check`)}({}) → ${n(`test_run`)}({})
+→ ${n(`lane`)}({ action: "merge", name: "refactor" })
+\`\`\`
+
+**After making changes:**
+\`\`\`
+${n(`blast_radius`)}({ changed_files: ["src/file.ts"] })
+→ ${n(`check`)}({}) → ${n(`test_run`)}({})
+→ ${n(`reindex`)}({})
+→ ${n(`remember`)}(...)
+\`\`\`
+
+---
+
+## Knowledge Categories
+
+| Category | What to store |
+|----------|---------------|
+| \`decisions\` | Architecture choices, trade-offs, rejected alternatives |
+| \`patterns\` | Code patterns, naming conventions, structural patterns |
+| \`conventions\` | Session checkpoints, workflow conventions, team agreements |
+| \`troubleshooting\` | Non-obvious fixes, debugging strategies, workarounds |
+
+---
+
+## Core Rules Summary
+
+1. **Search KB before proposing anything new** — prior decisions exist
+2. **Compress context aggressively** — \`file_summary\` → \`compact\` → \`digest\`
+3. **Use persistent memory** — \`remember\` decisions, \`stash\` temporary data
+4. **Validate before committing** — \`check\` + \`test_run\` + \`blast_radius\`
+5. **Follow \`_Next:\` hints** in tool responses for guided workflow
+6. **Use FORGE for complex tasks** — \`forge_classify\` → \`forge_ground\` → \`evidence_map\`
+`}export{t as buildAgentsMd,e as buildCopilotInstructions};
+//# sourceMappingURL=templates.js.map