@vpxa/kb 0.1.24 → 0.1.26

package/README.md

@@ -4,7 +4,7 @@ Local-first AI developer toolkit — knowledge base, code analysis, context mana
 
 ## Features
 
-- **64 MCP tools** for AI agents to search, analyze, and manipulate codebases
+- **67 MCP tools** for AI agents to search, analyze, and manipulate codebases
 - **47 CLI commands** for shell-based interaction
 - **Local-first** — ONNX embeddings, LanceDB vector store, no cloud dependencies
 - **Three interfaces**: MCP (for agent IDEs), CLI (for terminal agents), and programmatic API
@@ -23,7 +23,7 @@ This is an **MCP (Model Context Protocol) server** that gives AI agents:
 8. **Graph auto-population** — during indexing, a lightweight regex extractor builds the knowledge graph automatically from TS/JS source files (functions, classes, interfaces, types, imports)
 9. **Optimized reindex** — full reindex skips redundant hash checks, batches graph writes (flush every 50 files), and skips per-file graph deletes when bulk-cleared
 
-The KB auto-indexes configured source directories on startup, stores embeddings in a local LanceDB vector store, and exposes everything through 64 MCP tools, 45 CLI commands, and 2 resources.
+The KB auto-indexes configured source directories on startup, stores embeddings in a local LanceDB vector store, and exposes everything through 67 MCP tools, 45 CLI commands, and 2 resources.
 
 ---
 
@@ -348,7 +348,7 @@ kb init [--user|--workspace] [--force] [--guide]
 │   ├── chunker/      — tree-sitter + regex code chunking
 │   ├── indexer/      — incremental file indexer
 │   ├── analyzers/    — blast-radius, deps, symbols, patterns, diagrams
-│   ├── tools/        — 52 tool modules (64 MCP tools)
+│   ├── tools/        — 55 tool modules (67 MCP tools)
 │   ├── server/       — MCP protocol server
 │   └── cli/          — command-line interface
 ├── bin/kb.mjs        — CLI entry point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/kb",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",
@@ -23,6 +23,8 @@
     "bin/",
     "packages/*/dist/**/*.js",
     "packages/*/dist/**/*.d.ts",
+    "packages/dashboard/dist/**",
+    "packages/present/dist/**",
     "packages/chunker/wasm/*.wasm",
     "packages/chunker/src/queries/**/*.scm",
     "scaffold/",
@@ -44,6 +46,8 @@
   "dependencies": {
     "@huggingface/transformers": "^3.x",
     "@lancedb/lancedb": "^0.x",
+    "@mcp-ui/server": "^6.x",
+    "@modelcontextprotocol/ext-apps": "^1.x",
     "@modelcontextprotocol/sdk": "^1.x",
     "express": "^5.x",
     "linkedom": "^0.x",
@@ -56,16 +60,19 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.x",
+    "@types/express": "^5.x",
     "@types/node": "^24.x",
     "rimraf": "^6.x",
     "tsdown": "^0.x",
     "turbo": "^2.x",
     "typescript": "^6.x",
+    "vite": "^8.x",
+    "vite-plugin-singlefile": "^2.x",
     "vitest": "^4.x",
     "ws": "^8.x"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=18"
   },
   "scripts": {
     "build": "node scripts/build.mjs",

package/packages/analyzers/dist/symbol-analyzer.js

@@ -1,9 +1,9 @@
-import{readFile as e,readdir as t}from"node:fs/promises";import{extname as n,join as r,relative as i}from"node:path";import{SUPPORTED_EXTENSIONS as a,WasmRuntime as o,extractCalls as s,extractSymbols as c}from"../../chunker/dist/index.js";const l=new Set([`.ts`,`.tsx`,`.js`,`.jsx`,`.java`,`.py`,`.go`,`.cs`,`.rb`,`.kt`,`.scala`,`.rs`,`.php`,`.swift`]),u=new Set([`node_modules`,`.git`,`dist`,`build`,`coverage`,`.turbo`,`.cache`,`cdk.out`,`__pycache__`,`.venv`,`target`,`bin`,`obj`,`.gradle`,`venv`,`env`]),d={exported:[{pattern:/^export\s+(?:async\s+)?function\s+(\w+)/gm,kind:`function`},{pattern:/^export\s+(?:default\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^export\s+interface\s+(\w+)/gm,kind:`interface`},{pattern:/^export\s+type\s+(\w+)/gm,kind:`type`},{pattern:/^export\s+(?:const|let)\s+(\w+)/gm,kind:`const`},{pattern:/^export\s+enum\s+(\w+)/gm,kind:`enum`}],local:[{pattern:/^(?:async\s+)?function\s+(\w+)/gm,kind:`function`},{pattern:/^class\s+(\w+)/gm,kind:`class`},{pattern:/^interface\s+(\w+)/gm,kind:`interface`},{pattern:/^type\s+(\w+)/gm,kind:`type`},{pattern:/^(?:const|let)\s+(\w+)\s*=/gm,kind:`const`},{pattern:/^enum\s+(\w+)/gm,kind:`enum`}]},f={exported:[{pattern:/^[ \t]*public\s+(?:static\s+)?(?:abstract\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*public\s+(?:static\s+)?interface\s+(\w+)/gm,kind:`interface`},{pattern:/^[ \t]*public\s+(?:static\s+)?enum\s+(\w+)/gm,kind:`enum`},{pattern:/^[ \t]*public\s+(?:static\s+)?(?:synchronized\s+)?(?:final\s+)?(?:abstract\s+)?(?:\w+(?:<[^>]*>)?(?:\[\])*)\s+(\w+)\s*\(/gm,kind:`function`}],local:[{pattern:/^[ \t]*(?:private|protected)\s+(?:static\s+)?(?:abstract\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*(?:private|protected)\s+(?:static\s+)?(?:synchronized\s+)?(?:final\s+)?(?:\w+(?:<[^>]*>)?(?:\[\])*)\s+(\w+)\s*\(/gm,kind:`function`},{pattern:/^[ \t]*(?:private|protected)\s+(?:static\s+)?(?:final\s+)?(?:\w+(?:<[^>]*>)?)\s+(\w+)\s*[;=]/gm,kind:`variable`}],skipIndentFilter:!0},p={exported:[{pattern:/^def\s+(\w+)\s*\(/gm,kind:`function`},{pattern:/^async\s+def\s+(\w+)\s*\(/gm,kind:`function`},{pattern:/^class\s+(\w+)/gm,kind:`class`}],local:[{pattern:/^[ \t]+def\s+(\w+)\s*\(/gm,kind:`function`},{pattern:/^[ \t]+async\s+def\s+(\w+)\s*\(/gm,kind:`function`}],skipIndentFilter:!0},m={exported:[{pattern:/^func\s+([A-Z]\w*)\s*\(/gm,kind:`function`},{pattern:/^func\s+\([^)]+\)\s+([A-Z]\w*)\s*\(/gm,kind:`function`},{pattern:/^type\s+([A-Z]\w*)\s+struct\b/gm,kind:`class`},{pattern:/^type\s+([A-Z]\w*)\s+interface\b/gm,kind:`interface`},{pattern:/^type\s+([A-Z]\w*)\s+/gm,kind:`type`}],local:[{pattern:/^func\s+([a-z]\w*)\s*\(/gm,kind:`function`},{pattern:/^func\s+\([^)]+\)\s+([a-z]\w*)\s*\(/gm,kind:`function`},{pattern:/^type\s+([a-z]\w*)\s+struct\b/gm,kind:`class`},{pattern:/^type\s+([a-z]\w*)\s+/gm,kind:`type`}],skipIndentFilter:!0},h={exported:[{pattern:/^[ \t]*public\s+(?:static\s+)?(?:partial\s+)?(?:abstract\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*public\s+(?:static\s+)?interface\s+(\w+)/gm,kind:`interface`},{pattern:/^[ \t]*public\s+(?:static\s+)?enum\s+(\w+)/gm,kind:`enum`},{pattern:/^[ \t]*public\s+(?:static\s+)?(?:virtual\s+)?(?:override\s+)?(?:async\s+)?(?:\w+(?:<[^>]*>)?(?:\[\])?)\s+(\w+)\s*\(/gm,kind:`function`}],local:[{pattern:/^[ \t]*(?:private|protected|internal)\s+(?:static\s+)?(?:abstract\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*(?:private|protected|internal)\s+(?:static\s+)?(?:async\s+)?(?:\w+(?:<[^>]*>)?)\s+(\w+)\s*\(/gm,kind:`function`}],skipIndentFilter:!0},g={exported:[{pattern:/^(?:open\s+|data\s+|sealed\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^(?:fun|suspend\s+fun)\s+(\w+)\s*[(<]/gm,kind:`function`},{pattern:/^interface\s+(\w+)/gm,kind:`interface`},{pattern:/^object\s+(\w+)/gm,kind:`class`},{pattern:/^enum\s+class\s+(\w+)/gm,kind:`enum`}],local:[{pattern:/^[ \t]+(?:private|internal)\s+(?:fun|suspend\s+fun)\s+(\w+)/gm,kind:`function`},{pattern:/^[ \t]+(?:private|internal)\s+(?:val|var)\s+(\w+)/gm,kind:`variable`}],skipIndentFilter:!0},_={exported:[{pattern:/^class\s+(\w+)/gm,kind:`class`},{pattern:/^module\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]+def\s+self\.(\w+)/gm,kind:`function`}],local:[{pattern:/^[ \t]+def\s+(\w+)/gm,kind:`function`}],skipIndentFilter:!0},v={exported:[{pattern:/^pub\s+(?:async\s+)?fn\s+(\w+)/gm,kind:`function`},{pattern:/^pub\s+struct\s+(\w+)/gm,kind:`class`},{pattern:/^pub\s+trait\s+(\w+)/gm,kind:`interface`},{pattern:/^pub\s+enum\s+(\w+)/gm,kind:`enum`},{pattern:/^pub\s+type\s+(\w+)/gm,kind:`type`}],local:[{pattern:/^(?:async\s+)?fn\s+(\w+)/gm,kind:`function`},{pattern:/^struct\s+(\w+)/gm,kind:`class`},{pattern:/^trait\s+(\w+)/gm,kind:`interface`},{pattern:/^enum\s+(\w+)/gm,kind:`enum`}],skipIndentFilter:!0},y={exported:[{pattern:/^[ \t]*(?:abstract\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*interface\s+(\w+)/gm,kind:`interface`},{pattern:/^[ \t]*public\s+(?:static\s+)?function\s+(\w+)/gm,kind:`function`},{pattern:/^function\s+(\w+)\s*\(/gm,kind:`function`}],local:[{pattern:/^[ \t]*(?:private|protected)\s+(?:static\s+)?function\s+(\w+)/gm,kind:`function`}],skipIndentFilter:!0},b={exported:[{pattern:/^[ \t]*(?:open|public)\s+class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*(?:open|public)\s+struct\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*(?:open|public)\s+protocol\s+(\w+)/gm,kind:`interface`},{pattern:/^[ \t]*(?:open|public)\s+enum\s+(\w+)/gm,kind:`enum`},{pattern:/^[ \t]*(?:open|public)\s+func\s+(\w+)/gm,kind:`function`}],local:[{pattern:/^[ \t]*(?:private|fileprivate|internal)\s+func\s+(\w+)/gm,kind:`function`},{pattern:/^[ \t]*(?:private|fileprivate|internal)\s+class\s+(\w+)/gm,kind:`class`}],skipIndentFilter:!0},x={exported:[{pattern:/^[ \t]*(?:case\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*object\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*trait\s+(\w+)/gm,kind:`interface`},{pattern:/^[ \t]*def\s+(\w+)/gm,kind:`function`}],local:[],skipIndentFilter:!0};function S(e){switch(e){case`.ts`:case`.tsx`:case`.js`:case`.jsx`:return d;case`.java`:return f;case`.py`:return p;case`.go`:return m;case`.cs`:return h;case`.kt`:return g;case`.rb`:return _;case`.rs`:return v;case`.php`:return y;case`.swift`:return b;case`.scala`:return x;default:return d}}function C(e,t){let n=``,r=0,i=!1;for(let a=t;a<Math.min(t+5,e.length);a++){let t=e[a].trim();n+=(n?` `:``)+t;for(let e of t)e===`(`&&(r++,i=!0),e===`)`&&r--;if(i&&r<=0)return n.replace(/\s*\{.*$/,``).replace(/\s*:\s*$/,``).trim()}return n.trim()||void 0}var w=class{name=`symbols`;async analyze(t,r={}){let{format:l=`markdown`,filter:u}=r,d=Date.now(),f=await this.collectFiles(t),p=[],m=[],h=!1;try{await o.ensure(),h=!0}catch{}for(let r of f){let o=await e(r,`utf-8`),l=i(t,r).replace(/\\/g,`/`),u=n(r);if(h&&a.has(u)){let e=await c(o,u,l);if(e.length>0){p.push(...e);let t=await s(o,u,l);m.push(...t)}else{let e=this.extractSymbolsRegex(o,l);p.push(...e)}}else{let e=this.extractSymbolsRegex(o,l);p.push(...e)}}if(u){let e=u.toLowerCase();p=p.filter(t=>t.name.toLowerCase().includes(e))}return{output:l===`json`?JSON.stringify(p,null,2):this.formatMarkdown(p,t,m),data:{symbols:p,byKind:this.groupByKind(p),exportedCount:p.filter(e=>e.exported).length,totalCount:p.length,callEdges:m},meta:{analyzedAt:new Date().toISOString(),scope:t,fileCount:f.length,durationMs:Date.now()-d}}}async collectFiles(e){let i=[],a=async e=>{let o=await t(e,{withFileTypes:!0});for(let t of o){if(u.has(t.name)||t.name.startsWith(`.`))continue;let o=r(e,t.name);t.isDirectory()?await a(o):l.has(n(t.name))&&i.push(o)}};return await a(e),i}extractSymbolsRegex(e,t){let r=[],i=e.split(`
-`),a=new Set,o=S(n(t));for(let{pattern:n,kind:s}of o.exported){let o=new RegExp(n.source,n.flags),c;for(;(c=o.exec(e))!==null;){let n=c[1];a.add(n);let o=e.slice(0,c.index).split(`
-`).length,l=s===`function`||s===`method`?C(i,o-1):void 0;r.push({name:n,kind:s,exported:!0,filePath:t,line:o,signature:l})}}for(let{pattern:n,kind:s}of o.local){let c=new RegExp(n.source,n.flags),l;for(;(l=c.exec(e))!==null;){let n=l[1];if(a.has(n))continue;if(!o.skipIndentFilter){let t=i[e.slice(0,l.index).split(`
+import{readFile as e,readdir as t,stat as n}from"node:fs/promises";import{dirname as r,extname as i,join as a,relative as o}from"node:path";import{SUPPORTED_EXTENSIONS as s,WasmRuntime as c,extractCalls as l,extractSymbols as u}from"../../chunker/dist/index.js";const d=new Set([`.ts`,`.tsx`,`.js`,`.jsx`,`.java`,`.py`,`.go`,`.cs`,`.rb`,`.kt`,`.scala`,`.rs`,`.php`,`.swift`]),f=new Set([`node_modules`,`.git`,`dist`,`build`,`coverage`,`.turbo`,`.cache`,`cdk.out`,`__pycache__`,`.venv`,`target`,`bin`,`obj`,`.gradle`,`venv`,`env`]),p={exported:[{pattern:/^export\s+(?:async\s+)?function\s+(\w+)/gm,kind:`function`},{pattern:/^export\s+(?:default\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^export\s+interface\s+(\w+)/gm,kind:`interface`},{pattern:/^export\s+type\s+(\w+)/gm,kind:`type`},{pattern:/^export\s+(?:const|let)\s+(\w+)/gm,kind:`const`},{pattern:/^export\s+enum\s+(\w+)/gm,kind:`enum`}],local:[{pattern:/^(?:async\s+)?function\s+(\w+)/gm,kind:`function`},{pattern:/^class\s+(\w+)/gm,kind:`class`},{pattern:/^interface\s+(\w+)/gm,kind:`interface`},{pattern:/^type\s+(\w+)/gm,kind:`type`},{pattern:/^(?:const|let)\s+(\w+)\s*=/gm,kind:`const`},{pattern:/^enum\s+(\w+)/gm,kind:`enum`}]},m={exported:[{pattern:/^[ \t]*public\s+(?:static\s+)?(?:abstract\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*public\s+(?:static\s+)?interface\s+(\w+)/gm,kind:`interface`},{pattern:/^[ \t]*public\s+(?:static\s+)?enum\s+(\w+)/gm,kind:`enum`},{pattern:/^[ \t]*public\s+(?:static\s+)?(?:synchronized\s+)?(?:final\s+)?(?:abstract\s+)?(?:\w+(?:<[^>]*>)?(?:\[\])*)\s+(\w+)\s*\(/gm,kind:`function`}],local:[{pattern:/^[ \t]*(?:private|protected)\s+(?:static\s+)?(?:abstract\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*(?:private|protected)\s+(?:static\s+)?(?:synchronized\s+)?(?:final\s+)?(?:\w+(?:<[^>]*>)?(?:\[\])*)\s+(\w+)\s*\(/gm,kind:`function`},{pattern:/^[ \t]*(?:private|protected)\s+(?:static\s+)?(?:final\s+)?(?:\w+(?:<[^>]*>)?)\s+(\w+)\s*[;=]/gm,kind:`variable`}],skipIndentFilter:!0},h={exported:[{pattern:/^def\s+(\w+)\s*\(/gm,kind:`function`},{pattern:/^async\s+def\s+(\w+)\s*\(/gm,kind:`function`},{pattern:/^class\s+(\w+)/gm,kind:`class`}],local:[{pattern:/^[ \t]+def\s+(\w+)\s*\(/gm,kind:`function`},{pattern:/^[ \t]+async\s+def\s+(\w+)\s*\(/gm,kind:`function`}],skipIndentFilter:!0},g={exported:[{pattern:/^func\s+([A-Z]\w*)\s*\(/gm,kind:`function`},{pattern:/^func\s+\([^)]+\)\s+([A-Z]\w*)\s*\(/gm,kind:`function`},{pattern:/^type\s+([A-Z]\w*)\s+struct\b/gm,kind:`class`},{pattern:/^type\s+([A-Z]\w*)\s+interface\b/gm,kind:`interface`},{pattern:/^type\s+([A-Z]\w*)\s+/gm,kind:`type`}],local:[{pattern:/^func\s+([a-z]\w*)\s*\(/gm,kind:`function`},{pattern:/^func\s+\([^)]+\)\s+([a-z]\w*)\s*\(/gm,kind:`function`},{pattern:/^type\s+([a-z]\w*)\s+struct\b/gm,kind:`class`},{pattern:/^type\s+([a-z]\w*)\s+/gm,kind:`type`}],skipIndentFilter:!0},_={exported:[{pattern:/^[ \t]*public\s+(?:static\s+)?(?:partial\s+)?(?:abstract\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*public\s+(?:static\s+)?interface\s+(\w+)/gm,kind:`interface`},{pattern:/^[ \t]*public\s+(?:static\s+)?enum\s+(\w+)/gm,kind:`enum`},{pattern:/^[ \t]*public\s+(?:static\s+)?(?:virtual\s+)?(?:override\s+)?(?:async\s+)?(?:\w+(?:<[^>]*>)?(?:\[\])?)\s+(\w+)\s*\(/gm,kind:`function`}],local:[{pattern:/^[ \t]*(?:private|protected|internal)\s+(?:static\s+)?(?:abstract\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*(?:private|protected|internal)\s+(?:static\s+)?(?:async\s+)?(?:\w+(?:<[^>]*>)?)\s+(\w+)\s*\(/gm,kind:`function`}],skipIndentFilter:!0},v={exported:[{pattern:/^(?:open\s+|data\s+|sealed\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^(?:fun|suspend\s+fun)\s+(\w+)\s*[(<]/gm,kind:`function`},{pattern:/^interface\s+(\w+)/gm,kind:`interface`},{pattern:/^object\s+(\w+)/gm,kind:`class`},{pattern:/^enum\s+class\s+(\w+)/gm,kind:`enum`}],local:[{pattern:/^[ \t]+(?:private|internal)\s+(?:fun|suspend\s+fun)\s+(\w+)/gm,kind:`function`},{pattern:/^[ \t]+(?:private|internal)\s+(?:val|var)\s+(\w+)/gm,kind:`variable`}],skipIndentFilter:!0},y={exported:[{pattern:/^class\s+(\w+)/gm,kind:`class`},{pattern:/^module\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]+def\s+self\.(\w+)/gm,kind:`function`}],local:[{pattern:/^[ \t]+def\s+(\w+)/gm,kind:`function`}],skipIndentFilter:!0},b={exported:[{pattern:/^pub\s+(?:async\s+)?fn\s+(\w+)/gm,kind:`function`},{pattern:/^pub\s+struct\s+(\w+)/gm,kind:`class`},{pattern:/^pub\s+trait\s+(\w+)/gm,kind:`interface`},{pattern:/^pub\s+enum\s+(\w+)/gm,kind:`enum`},{pattern:/^pub\s+type\s+(\w+)/gm,kind:`type`}],local:[{pattern:/^(?:async\s+)?fn\s+(\w+)/gm,kind:`function`},{pattern:/^struct\s+(\w+)/gm,kind:`class`},{pattern:/^trait\s+(\w+)/gm,kind:`interface`},{pattern:/^enum\s+(\w+)/gm,kind:`enum`}],skipIndentFilter:!0},x={exported:[{pattern:/^[ \t]*(?:abstract\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*interface\s+(\w+)/gm,kind:`interface`},{pattern:/^[ \t]*public\s+(?:static\s+)?function\s+(\w+)/gm,kind:`function`},{pattern:/^function\s+(\w+)\s*\(/gm,kind:`function`}],local:[{pattern:/^[ \t]*(?:private|protected)\s+(?:static\s+)?function\s+(\w+)/gm,kind:`function`}],skipIndentFilter:!0},S={exported:[{pattern:/^[ \t]*(?:open|public)\s+class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*(?:open|public)\s+struct\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*(?:open|public)\s+protocol\s+(\w+)/gm,kind:`interface`},{pattern:/^[ \t]*(?:open|public)\s+enum\s+(\w+)/gm,kind:`enum`},{pattern:/^[ \t]*(?:open|public)\s+func\s+(\w+)/gm,kind:`function`}],local:[{pattern:/^[ \t]*(?:private|fileprivate|internal)\s+func\s+(\w+)/gm,kind:`function`},{pattern:/^[ \t]*(?:private|fileprivate|internal)\s+class\s+(\w+)/gm,kind:`class`}],skipIndentFilter:!0},C={exported:[{pattern:/^[ \t]*(?:case\s+)?class\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*object\s+(\w+)/gm,kind:`class`},{pattern:/^[ \t]*trait\s+(\w+)/gm,kind:`interface`},{pattern:/^[ \t]*def\s+(\w+)/gm,kind:`function`}],local:[],skipIndentFilter:!0};function w(e){switch(e){case`.ts`:case`.tsx`:case`.js`:case`.jsx`:return p;case`.java`:return m;case`.py`:return h;case`.go`:return g;case`.cs`:return _;case`.kt`:return v;case`.rb`:return y;case`.rs`:return b;case`.php`:return x;case`.swift`:return S;case`.scala`:return C;default:return p}}function T(e,t){let n=``,r=0,i=!1;for(let a=t;a<Math.min(t+5,e.length);a++){let t=e[a].trim();n+=(n?` `:``)+t;for(let e of t)e===`(`&&(r++,i=!0),e===`)`&&r--;if(i&&r<=0)return n.replace(/\s*\{.*$/,``).replace(/\s*:\s*$/,``).trim()}return n.trim()||void 0}var E=class{name=`symbols`;async analyze(t,n={}){let{format:a=`markdown`,filter:d}=n,f=Date.now(),p=await this.collectFiles(t),m=p.length===1&&p[0]===t?r(t):t,h=[],g=[],_=!1;try{await c.ensure(),_=!0}catch{}for(let t of p){let n=await e(t,`utf-8`),r=o(m,t).replace(/\\/g,`/`),a=i(t);if(_&&s.has(a)){let e=await u(n,a,r);if(e.length>0){h.push(...e);let t=await l(n,a,r);g.push(...t)}else{let e=this.extractSymbolsRegex(n,r);h.push(...e)}}else{let e=this.extractSymbolsRegex(n,r);h.push(...e)}}if(d){let e=d.toLowerCase();h=h.filter(t=>t.name.toLowerCase().includes(e))}return{output:a===`json`?JSON.stringify(h,null,2):this.formatMarkdown(h,m,g),data:{symbols:h,byKind:this.groupByKind(h),exportedCount:h.filter(e=>e.exported).length,totalCount:h.length,callEdges:g},meta:{analyzedAt:new Date().toISOString(),scope:t,fileCount:p.length,durationMs:Date.now()-f}}}async collectFiles(e){let r=[],o;try{o=await n(e)}catch{throw Error(`Path does not exist: ${e}`)}if(o.isFile()){if(d.has(i(e)))return[e];throw Error(`Not a recognized source file: ${e}`)}if(!o.isDirectory())throw Error(`Not a file or directory: ${e}`);let s=async e=>{let n=await t(e,{withFileTypes:!0});for(let t of n){if(f.has(t.name)||t.name.startsWith(`.`))continue;let n=a(e,t.name);t.isDirectory()?await s(n):d.has(i(t.name))&&r.push(n)}};return await s(e),r}extractSymbolsRegex(e,t){let n=[],r=e.split(`
+`),a=new Set,o=w(i(t));for(let{pattern:i,kind:s}of o.exported){let o=new RegExp(i.source,i.flags),c;for(;(c=o.exec(e))!==null;){let i=c[1];a.add(i);let o=e.slice(0,c.index).split(`
+`).length,l=s===`function`||s===`method`?T(r,o-1):void 0;n.push({name:i,kind:s,exported:!0,filePath:t,line:o,signature:l})}}for(let{pattern:i,kind:s}of o.local){let c=new RegExp(i.source,i.flags),l;for(;(l=c.exec(e))!==null;){let i=l[1];if(a.has(i))continue;if(!o.skipIndentFilter){let t=r[e.slice(0,l.index).split(`
 `).length-1]??``;if(t.startsWith(` `)||t.startsWith(`	`))continue}let c=e.slice(0,l.index).split(`
-`).length,u=s===`function`||s===`method`?C(i,c-1):void 0;r.push({name:n,kind:s,exported:!1,filePath:t,line:c,signature:u})}}return r}groupByKind(e){let t={};for(let n of e)t[n.kind]=(t[n.kind]??0)+1;return t}formatMarkdown(e,t,n=[]){let r=[],i=e.filter(e=>e.exported).length;r.push(`## Symbols: ${t}\n`),r.push(`**${e.length} symbols** (${i} exported)\n`);let a={};for(let t of e)a[t.kind]=(a[t.kind]??0)+1;let o=Object.entries(a).sort((e,t)=>t[1]-e[1]).map(([e,t])=>`${t} ${e===`class`?`classes`:`${e}s`}`).join(`, `);r.push(`**Breakdown**: ${o}\n`);let s={};for(let t of e)s[t.filePath]||(s[t.filePath]=[]),s[t.filePath].push(t);r.push(`**${Object.keys(s).length} files** with symbols\n`);let c=0,l=Object.entries(s).sort((e,t)=>{let n=e[1].filter(e=>e.exported).length;return t[1].filter(e=>e.exported).length-n});for(let[e,t]of l){let n=t.filter(e=>e.exported);if(n.length===0)continue;let i=[`### ${e}\n`];for(let e of n){let t=e.signature?` — \`${e.signature}\``:``;i.push(`- 📤 \`${e.kind}\` **${e.name}** (line ${e.line})${t}`)}let a=t.length-n.length;a>0&&i.push(`- _${a} internal ${a===1?`symbol`:`symbols`}_`),i.push(``);let o=i.join(`
+`).length,u=s===`function`||s===`method`?T(r,c-1):void 0;n.push({name:i,kind:s,exported:!1,filePath:t,line:c,signature:u})}}return n}groupByKind(e){let t={};for(let n of e)t[n.kind]=(t[n.kind]??0)+1;return t}formatMarkdown(e,t,n=[]){let r=[],i=e.filter(e=>e.exported).length;r.push(`## Symbols: ${t}\n`),r.push(`**${e.length} symbols** (${i} exported)\n`);let a={};for(let t of e)a[t.kind]=(a[t.kind]??0)+1;let o=Object.entries(a).sort((e,t)=>t[1]-e[1]).map(([e,t])=>`${t} ${e===`class`?`classes`:`${e}s`}`).join(`, `);r.push(`**Breakdown**: ${o}\n`);let s={};for(let t of e)s[t.filePath]||(s[t.filePath]=[]),s[t.filePath].push(t);r.push(`**${Object.keys(s).length} files** with symbols\n`);let c=0,l=Object.entries(s).sort((e,t)=>{let n=e[1].filter(e=>e.exported).length;return t[1].filter(e=>e.exported).length-n});for(let[e,t]of l){let n=t.filter(e=>e.exported);if(n.length===0)continue;let i=[`### ${e}\n`];for(let e of n){let t=e.signature?` — \`${e.signature}\``:``;i.push(`- 📤 \`${e.kind}\` **${e.name}** (line ${e.line})${t}`)}let a=t.length-n.length;a>0&&i.push(`- _${a} internal ${a===1?`symbol`:`symbols`}_`),i.push(``);let o=i.join(`
 `);if(c+=o.length,c>81920){r.push(`\n_Output truncated at 80KB. ${Object.keys(s).length-r.filter(e=>e.startsWith(`### `)).length} files omitted._`);break}r.push(o)}return n.length>0&&r.push(this.formatCallGraph(n)),r.join(`
 `)}formatCallGraph(e){let t=new Map;for(let n of e){if(n.callerName===`<module>`)continue;let e=`${n.callerFile}:${n.callerName}->${n.calleeName}`,r=t.get(e);r?r.count++:t.set(e,{callerFile:n.callerFile,callerName:n.callerName,calleeName:n.calleeName,count:1})}if(t.size===0)return``;let n=[];n.push(`### Call Graph Summary
 `),n.push(`**${e.length} call edges** across analyzed files\n`);let r=new Map;for(let e of t.values()){let t=`${e.callerFile}#${e.callerName}`;r.has(t)||r.set(t,[]),r.get(t)?.push(e.calleeName)}let i=[...r.entries()].sort((e,t)=>t[1].length-e[1].length).slice(0,30);for(let[e,t]of i){let[r,i]=e.split(`#`);n.push(`- **${i}** (${r}) → ${t.join(`, `)}`)}return n.push(``),n.join(`
-`)}};export{w as SymbolAnalyzer};
+`)}};export{E as SymbolAnalyzer};

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

@@ -1 +1 @@
-import{MCP_SERVER_ENTRY as e}from"./constants.js";import{buildAgentsMd as t,buildCopilotInstructions as n}from"./templates.js";import{existsSync as r,mkdirSync as i,writeFileSync as a}from"node:fs";import{basename as o,resolve as s}from"node:path";function c(e){return r(s(e,`.cursor`))?`cursor`:r(s(e,`.claude`))?`claude-code`:r(s(e,`.windsurf`))?`windsurf`:`copilot`}function l(t){return{servers:{[t]:{...e}}}}function u(t){let{type:n,...r}=e;return{mcpServers:{[t]:r}}}const d={scaffoldDir:`general`,writeMcpConfig(e,t){let n=s(e,`.vscode`),o=s(n,`mcp.json`);r(o)||(i(n,{recursive:!0}),a(o,`${JSON.stringify(l(t),null,2)}\n`,`utf-8`),console.log(`  Created .vscode/mcp.json`))},writeInstructions(e,t){let c=s(e,`.github`),l=s(c,`copilot-instructions.md`);r(l)||(i(c,{recursive:!0}),a(l,n(o(e),t),`utf-8`),console.log(`  Created .github/copilot-instructions.md`))},writeAgentsMd(e,n){let i=s(e,`AGENTS.md`);r(i)||(a(i,t(o(e),n),`utf-8`),console.log(`  Created AGENTS.md`))}},f={scaffoldDir:`general`,writeMcpConfig(e,t){let n=s(e,`.mcp.json`);r(n)||(a(n,`${JSON.stringify(u(t),null,2)}\n`,`utf-8`),console.log(`  Created .mcp.json`))},writeInstructions(e,i){let c=s(e,`CLAUDE.md`);if(!r(c)){let r=o(e);a(c,`${n(r,i)}\n---\n\n${t(r,i)}`,`utf-8`),console.log(`  Created CLAUDE.md`)}},writeAgentsMd(e,t){}},p={scaffoldDir:`general`,writeMcpConfig(e,t){let n=s(e,`.cursor`),o=s(n,`mcp.json`);r(o)||(i(n,{recursive:!0}),a(o,`${JSON.stringify(u(t),null,2)}\n`,`utf-8`),console.log(`  Created .cursor/mcp.json`))},writeInstructions(e,c){let l=s(e,`.cursor`,`rules`),u=s(l,`kb.mdc`);if(!r(u)){i(l,{recursive:!0});let r=o(e);a(u,`${n(r,c)}\n---\n\n${t(r,c)}`,`utf-8`),console.log(`  Created .cursor/rules/kb.mdc`)}},writeAgentsMd(e,t){}},m={scaffoldDir:`general`,writeMcpConfig(e,t){let n=s(e,`.vscode`),o=s(n,`mcp.json`);r(o)||(i(n,{recursive:!0}),a(o,`${JSON.stringify(l(t),null,2)}\n`,`utf-8`),console.log(`  Created .vscode/mcp.json (Windsurf-compatible)`))},writeInstructions(e,i){let c=s(e,`.windsurfrules`);if(!r(c)){let r=o(e);a(c,`${n(r,i)}\n---\n\n${t(r,i)}`,`utf-8`),console.log(`  Created .windsurfrules`)}},writeAgentsMd(e,t){}};function h(e){switch(e){case`copilot`:return d;case`claude-code`:return f;case`cursor`:return p;case`windsurf`:return m}}export{f as claudeCodeAdapter,d as copilotAdapter,p as cursorAdapter,c as detectIde,h as getAdapter,m as windsurfAdapter};
+import{MCP_SERVER_ENTRY as e}from"./constants.js";import{buildAgentsMd as t,buildCopilotInstructions as n}from"./templates.js";import{existsSync as r,mkdirSync as i,writeFileSync as a}from"node:fs";import{basename as o,resolve as s}from"node:path";function c(e){return r(s(e,`.cursor`))?`cursor`:r(s(e,`.claude`))?`claude-code`:r(s(e,`.windsurf`))?`windsurf`:`copilot`}function l(t){return{servers:{[t]:{...e}}}}function u(t){let{type:n,...r}=e;return{mcpServers:{[t]:r}}}const d={scaffoldDir:`general`,writeMcpConfig(e,t){let n=s(e,`.vscode`),o=s(n,`mcp.json`);r(o)||(i(n,{recursive:!0}),a(o,`${JSON.stringify(l(t),null,2)}\n`,`utf-8`),console.log(`  Created .vscode/mcp.json`))},writeInstructions(e,t){let r=s(e,`.github`),c=s(r,`copilot-instructions.md`);i(r,{recursive:!0}),a(c,n(o(e),t),`utf-8`),console.log(`  Updated .github/copilot-instructions.md`)},writeAgentsMd(e,n){a(s(e,`AGENTS.md`),t(o(e),n),`utf-8`),console.log(`  Updated AGENTS.md`)}},f={scaffoldDir:`general`,writeMcpConfig(e,t){let n=s(e,`.mcp.json`);r(n)||(a(n,`${JSON.stringify(u(t),null,2)}\n`,`utf-8`),console.log(`  Created .mcp.json`))},writeInstructions(e,r){let i=s(e,`CLAUDE.md`),c=o(e);a(i,`${n(c,r)}\n---\n\n${t(c,r)}`,`utf-8`),console.log(`  Updated CLAUDE.md`)},writeAgentsMd(e,t){}},p={scaffoldDir:`general`,writeMcpConfig(e,t){let n=s(e,`.cursor`),o=s(n,`mcp.json`);r(o)||(i(n,{recursive:!0}),a(o,`${JSON.stringify(u(t),null,2)}\n`,`utf-8`),console.log(`  Created .cursor/mcp.json`))},writeInstructions(e,r){let c=s(e,`.cursor`,`rules`),l=s(c,`kb.mdc`);i(c,{recursive:!0});let u=o(e);a(l,`${n(u,r)}\n---\n\n${t(u,r)}`,`utf-8`),console.log(`  Updated .cursor/rules/kb.mdc`)},writeAgentsMd(e,t){}},m={scaffoldDir:`general`,writeMcpConfig(e,t){let n=s(e,`.vscode`),o=s(n,`mcp.json`);r(o)||(i(n,{recursive:!0}),a(o,`${JSON.stringify(l(t),null,2)}\n`,`utf-8`),console.log(`  Created .vscode/mcp.json (Windsurf-compatible)`))},writeInstructions(e,r){let i=s(e,`.windsurfrules`),c=o(e);a(i,`${n(c,r)}\n---\n\n${t(c,r)}`,`utf-8`),console.log(`  Updated .windsurfrules`)},writeAgentsMd(e,t){}};function h(e){switch(e){case`copilot`:return d;case`claude-code`:return f;case`cursor`:return p;case`windsurf`:return m}}export{f as claudeCodeAdapter,d as copilotAdapter,p as cursorAdapter,c as detectIde,h as getAdapter,m as windsurfAdapter};

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

@@ -13,7 +13,7 @@ declare const MCP_SERVER_ENTRY: {
   readonly args: readonly ["-y", "@vpxa/kb", "serve"];
 };
 /** Skills shipped with the KB package and installed during init. */
-declare const SKILL_NAMES: readonly ["knowledge-base", "brainstorming", "session-handoff", "requirements-clarity", "lesson-learned", "c4-architecture", "adr-skill"];
+declare const SKILL_NAMES: readonly ["knowledge-base", "brainstorming", "session-handoff", "requirements-clarity", "lesson-learned", "c4-architecture", "adr-skill", "present"];
 /**
  * VS Code settings merged into each VS Code-family IDE's settings.json.
  *
@@ -30,6 +30,9 @@ declare const SKILL_NAMES: readonly ["knowledge-base", "brainstorming", "session
  *   session-handoff, etc.) — without this, skills never activate.
  * - switchAgent: Orchestrator uses the switchAgent tool to hand off to Plan —
  *   without this, agent switching is unavailable.
+ * - enableChatTools: Enables integrated-browser tools (openBrowserPage,
+ *   readPage, screenshotPage, etc.) so agents can open and interact with
+ *   web pages inside VS Code's built-in browser.
  */
 declare const VSCODE_SETTINGS: Record<string, unknown>;
 //#endregion

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

@@ -1 +1 @@
-const e=`knowledge-base`,t={type:`stdio`,command:`npx`,args:[`-y`,`@vpxa/kb`,`serve`]},n=[`knowledge-base`,`brainstorming`,`session-handoff`,`requirements-clarity`,`lesson-learned`,`c4-architecture`,`adr-skill`],r={"chat.agentFilesLocations":{"~/.claude/agents":!1},"github.copilot.chat.copilotMemory.enabled":!0,"chat.customAgentInSubagent.enabled":!0,"chat.useNestedAgentsMdFiles":!0,"chat.useAgentSkills":!0,"github.copilot.chat.switchAgent.enabled":!0};export{t as MCP_SERVER_ENTRY,e as SERVER_NAME,n as SKILL_NAMES,r as VSCODE_SETTINGS};
+const e=`knowledge-base`,t={type:`stdio`,command:`npx`,args:[`-y`,`@vpxa/kb`,`serve`]},n=[`knowledge-base`,`brainstorming`,`session-handoff`,`requirements-clarity`,`lesson-learned`,`c4-architecture`,`adr-skill`,`present`],r={"chat.agentFilesLocations":{"~/.claude/agents":!1},"github.copilot.chat.copilotMemory.enabled":!0,"chat.customAgentInSubagent.enabled":!0,"chat.useNestedAgentsMdFiles":!0,"chat.useAgentSkills":!0,"github.copilot.chat.switchAgent.enabled":!0,"workbench.browser.enableChatTools":!0};export{t as MCP_SERVER_ENTRY,e as SERVER_NAME,n as SKILL_NAMES,r as VSCODE_SETTINGS};

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

@@ -0,0 +1,54 @@
+//#region packages/cli/src/commands/init/frontmatter.d.ts
+/**
+ * Init module — YAML frontmatter parsing and merging for agent files.
+ *
+ * Agent `.agent.md` files use YAML frontmatter with fields like `tools`, `model`,
+ * `description`, and `argument-hint`. When updating these files, we need to
+ * merge new tools while preserving user customizations (model choice, extra tools).
+ *
+ * This is a lightweight parser — no full YAML dependency. It handles the specific
+ * frontmatter format used by Copilot agent files.
+ */
+interface ParsedFrontmatter {
+  /** Raw key-value pairs from YAML frontmatter. */
+  fields: Record<string, string>;
+  /** Parsed tools array (from YAML inline array syntax). */
+  tools: string[];
+  /** Body content after the closing `---`. */
+  body: string;
+}
+/**
+ * Parse a markdown file with YAML frontmatter.
+ *
+ * Expects format:
+ * ```
+ * ---
+ * key: value
+ * tools: [tool1, tool2]
+ * ---
+ * body content
+ * ```
+ */
+declare function parseFrontmatter(content: string): ParsedFrontmatter;
+/**
+ * Parse a YAML inline array: `[tool1, tool2, tool3]` → string[]
+ */
+declare function parseToolsArray(value: string): string[];
+/**
+ * Serialize tools array back to YAML inline syntax.
+ */
+declare function serializeToolsArray(tools: string[]): string;
+/**
+ * Merge two parsed frontmatter files (source = new upstream, deployed = user's current).
+ *
+ * Merge rules:
+ * - `tools`: UNION of both arrays (add new, keep user-added). Order: source first, then user extras.
+ * - `model`: KEEP deployed (user's choice).
+ * - `description`, `argument-hint`: TAKE from source (upstream updates).
+ * - Body: TAKE from source (structural changes come from upstream).
+ *
+ * Returns the merged file content as a string.
+ */
+declare function mergeFrontmatter(sourceContent: string, deployedContent: string): string;
+//#endregion
+export { ParsedFrontmatter, mergeFrontmatter, parseFrontmatter, parseToolsArray, serializeToolsArray };

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

@@ -0,0 +1,2 @@
+function e(e){let n={},r=[],i=e,a=e.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);if(!a)return{fields:n,tools:r,body:i};let o=a[1];i=a[2];for(let e of o.split(/\r?\n/)){let i=e.match(/^(\S+?):\s*(.*)$/);if(!i)continue;let[,a,o]=i;n[a]=o,a===`tools`&&(r=t(o))}return{fields:n,tools:r,body:i}}function t(e){let t=e.trim();if(!t.startsWith(`[`)||!t.endsWith(`]`))return[];let n=t.slice(1,-1).trim();return n?n.split(`,`).map(e=>e.trim()).filter(Boolean):[]}function n(e){return`[${e.join(`, `)}]`}function r(t,r){let i=e(t),a=e(r),o={...i.fields};a.fields.model&&(o.model=a.fields.model);let s=new Set(i.tools),c=a.tools.filter(e=>!s.has(e));o.tools=n([...i.tools,...c]);let l=[`---`],u=[`description`,`argument-hint`,`tools`,`model`],d=new Set;for(let e of u)e in o&&(l.push(`${e}: ${o[e]}`),d.add(e));for(let[e,t]of Object.entries(o))d.has(e)||l.push(`${e}: ${t}`);return l.push(`---`),`${l.join(`
+`)}\n${i.body}`}export{r as mergeFrontmatter,e as parseFrontmatter,t as parseToolsArray,n as serializeToolsArray};

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

@@ -1,5 +1,5 @@
-import{SKILL_NAMES as e}from"./constants.js";import{detectIde as t,getAdapter as n}from"./adapters.js";import{ensureGitignore as r,getServerName as i,writeKbConfig as a}from"./config.js";import{createCuratedDirs as o}from"./curated.js";import{copyScaffold as s,copySkills as c,guideScaffold as l,guideSkills as u}from"./scaffold.js";import{dirname as d,resolve as f}from"node:path";import{fileURLToPath as p}from"node:url";import{isUserInstalled as m}from"../../../../core/dist/index.js";async function h(l){let u=process.cwd();if(!a(u,l.force))return;r(u);let h=i(),g=n(t(u));g.writeMcpConfig(u,h),g.writeInstructions(u,h),g.writeAgentsMd(u,h);let _=f(d(p(import.meta.url)),`..`,`..`,`..`,`..`,`..`);c(u,_,[...e],l.force),s(u,_,g.scaffoldDir,l.force),o(u),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`),m()&&console.log(`
-Note: User-level KB is also installed. This workspace uses its own local data store.`)}async function g(e){m()?await _(e):await h(e)}async function _(e){let a=process.cwd(),c=i(),l=n(t(a));l.writeInstructions(a,c),l.writeAgentsMd(a,c),s(a,f(d(p(import.meta.url)),`..`,`..`,`..`,`..`,`..`),l.scaffoldDir,e.force),o(a),r(a),console.log(`
+import{SKILL_NAMES as e}from"./constants.js";import{detectIde as t,getAdapter as n}from"./adapters.js";import{ensureGitignore as r,getServerName as i,writeKbConfig as a}from"./config.js";import{createCuratedDirs as o}from"./curated.js";import{guideScaffold as s,guideSkills as c,smartCopyScaffold as l,smartCopySkills as u}from"./scaffold.js";import{readFileSync as d}from"node:fs";import{dirname as f,resolve as p}from"node:path";import{fileURLToPath as m}from"node:url";import{isUserInstalled as h}from"../../../../core/dist/index.js";async function g(s){let c=process.cwd();if(!a(c,s.force))return;r(c);let g=i(),_=n(t(c));_.writeMcpConfig(c,g),_.writeInstructions(c,g),_.writeAgentsMd(c,g);let v=p(f(m(import.meta.url)),`..`,`..`,`..`,`..`,`..`),y=JSON.parse(d(p(v,`package.json`),`utf-8`)).version;u(c,v,[...e],y,s.force),l(c,v,_.scaffoldDir,y,s.force),o(c),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`),h()&&console.log(`
+Note: User-level KB is also installed. This workspace uses its own local data store.`)}async function _(e){h()?await v(e):await g(e)}async function v(e){let a=process.cwd(),s=i(),c=n(t(a));c.writeInstructions(a,s),c.writeAgentsMd(a,s);let u=p(f(m(import.meta.url)),`..`,`..`,`..`,`..`,`..`),h=JSON.parse(d(p(u,`package.json`),`utf-8`)).version;l(a,u,c.scaffoldDir,h,e.force),o(a),r(a),console.log(`
 Workspace scaffolded for user-level KB! Files added:`),console.log(`  Instruction files (AGENTS.md, copilot-instructions.md, etc.)`),console.log(`  .ai/curated/ directories`),console.log(`  .github/agents/ & .github/prompts/`),console.log(`
-The user-level KB server will auto-index this workspace when opened in your IDE.`)}async function v(){let r=process.cwd(),i=n(t(r)),a=f(d(p(import.meta.url)),`..`,`..`,`..`,`..`,`..`),o=[...u(r,a,[...e]),...l(r,a,i.scaffoldDir)],s={summary:{total:o.length,new:o.filter(e=>e.status===`new`).length,outdated:o.filter(e=>e.status===`outdated`).length,current:o.filter(e=>e.status===`current`).length},files:o};console.log(JSON.stringify(s,null,2))}export{v as guideProject,h as initProject,g as initSmart};
+The user-level KB server will auto-index this workspace when opened in your IDE.`)}async function y(){let r=process.cwd(),i=n(t(r)),a=p(f(m(import.meta.url)),`..`,`..`,`..`,`..`,`..`),o=[...c(r,a,[...e]),...s(r,a,i.scaffoldDir)],l={summary:{total:o.length,new:o.filter(e=>e.status===`new`).length,outdated:o.filter(e=>e.status===`outdated`).length,current:o.filter(e=>e.status===`current`).length},files:o};console.log(JSON.stringify(l,null,2))}export{y as guideProject,g as initProject,_ as initSmart};

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

@@ -0,0 +1,71 @@
+//#region packages/cli/src/commands/init/manifest.d.ts
+/**
+ * Init module — scaffold manifest for smart updates.
+ *
+ * Tracks which scaffold files have been deployed and their source hashes,
+ * enabling incremental updates that preserve user customizations while
+ * applying new features from upstream.
+ *
+ * Manifest file: `.kb-scaffold.json` stored alongside the scaffold root
+ * (e.g. `~/.copilot/.kb-scaffold.json` for user-level, `.github/.kb-scaffold.json` for workspace).
+ */
+/**
+ * How a file should be updated when the source changes:
+ *
+ * - `overwrite`: Replace entirely (shared protocols, templates, skills).
+ * - `merge-frontmatter`: Merge YAML frontmatter tools (union), keep user model,
+ *   replace body. Used for agent .md files that users may customize.
+ * - `regenerate`: Re-run the template generator (copilot-instructions.md, CLAUDE.md).
+ */
+type UpdateStrategy = 'overwrite' | 'merge-frontmatter' | 'regenerate';
+interface ManifestEntry {
+  /** SHA-256 hash (16-char hex) of the source content when deployed. */
+  sourceHash: string;
+  /** Update strategy for this file. */
+  strategy: UpdateStrategy;
+  /** ISO timestamp of last deployment. */
+  updatedAt: string;
+}
+interface ScaffoldManifest {
+  /** Package version that generated this manifest. */
+  version: string;
+  /** ISO timestamp of manifest creation/update. */
+  generatedAt: string;
+  /** File entries keyed by relative path from scaffold root. */
+  files: Record<string, ManifestEntry>;
+}
+/** Compute a 16-char hex SHA-256 hash of content (consistent with file-hasher). */
+declare function hashContent(content: string): string;
+/** Read and parse a manifest file; returns null if missing or invalid. */
+declare function readManifest(manifestPath: string): ScaffoldManifest | null;
+/** Write a manifest to disk. */
+declare function writeManifest(manifestPath: string, manifest: ScaffoldManifest): void;
+/**
+ * Determine the update strategy for a file based on its relative path.
+ *
+ * Strategy rules:
+ * - `*.agent.md` (not under `_shared/`) → merge-frontmatter
+ * - `_shared/*.md`, `templates/*.md` → overwrite
+ * - `*.prompt.md`, `SKILL.md`, `README.md` → overwrite
+ * - Everything else → overwrite
+ */
+declare function getUpdateStrategy(relativePath: string): UpdateStrategy;
+/**
+ * Check whether a deployed file needs updating.
+ *
+ * Returns:
+ * - `'new'`: File not in manifest (first deployment).
+ * - `'outdated'`: Source hash changed since last deployment.
+ * - `'current'`: Source hash matches — no update needed.
+ */
+declare function getFileStatus(manifest: ScaffoldManifest | null, relativePath: string, sourceContent: string): 'new' | 'outdated' | 'current';
+/**
+ * Record a file deployment in the manifest.
+ */
+declare function recordDeployment(manifest: ScaffoldManifest, relativePath: string, sourceContent: string, strategy?: UpdateStrategy): void;
+/**
+ * Create a fresh manifest for a new deployment.
+ */
+declare function createManifest(version: string): ScaffoldManifest;
+//#endregion
+export { ManifestEntry, ScaffoldManifest, UpdateStrategy, createManifest, getFileStatus, getUpdateStrategy, hashContent, readManifest, recordDeployment, writeManifest };

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

@@ -0,0 +1 @@
+import{existsSync as e,readFileSync as t,writeFileSync as n}from"node:fs";import{createHash as r}from"node:crypto";function i(e){return r(`sha256`).update(e).digest(`hex`).slice(0,16)}function a(n){if(!e(n))return null;try{let e=t(n,`utf-8`),r=JSON.parse(e);return!r.version||!r.files?null:r}catch{return null}}function o(e,t){n(e,`${JSON.stringify(t,null,2)}\n`,`utf-8`)}function s(e){return e.endsWith(`.agent.md`)&&!e.startsWith(`_shared/`)&&!e.startsWith(`agents/_shared/`)&&!e.startsWith(`templates/`)?`merge-frontmatter`:`overwrite`}function c(e,t,n){if(!e)return`new`;let r=e.files[t];return r?r.sourceHash===i(n)?`current`:`outdated`:`new`}function l(e,t,n,r){e.files[t]={sourceHash:i(n),strategy:r??s(t),updatedAt:new Date().toISOString()}}function u(e){return{version:e,generatedAt:new Date().toISOString(),files:{}}}export{u as createManifest,c as getFileStatus,s as getUpdateStrategy,i as hashContent,a as readManifest,l as recordDeployment,o as writeManifest};

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

@@ -1,8 +1,6 @@
+import { ScaffoldManifest } from "./manifest.js";
+
 //#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;
@@ -11,6 +9,31 @@ interface GuideFileEntry {
 }
 /** Recursively copy a directory. When force=false, skip files that already exist. */
 declare function copyDirectoryRecursive(srcDir: string, destDir: string, logPrefix?: string, force?: boolean): void;
+/**
+ * Manifest-aware recursive copy with per-file merge strategies.
+ *
+ * For each file:
+ * - `new`: Deploy and record in manifest.
+ * - `outdated` + `overwrite` strategy: Replace entirely.
+ * - `outdated` + `merge-frontmatter`: Merge tools (union), keep user model, update body.
+ * - `current`: Skip (source unchanged).
+ * - `force=true`: Always overwrite (resets manifest entry).
+ */
+declare function smartCopyDirectory(srcDir: string, destDir: string, manifest: ScaffoldManifest, logPrefix?: string, force?: boolean): void;
+/**
+ * Smart-copy scaffold files with manifest tracking.
+ * Reads/creates manifest at `<destRoot>/.kb-scaffold.json`.
+ */
+declare function smartCopyScaffold(cwd: string, pkgRoot: string, ide: string, version: string, force?: boolean): void;
+/**
+ * Smart-copy skill files with manifest tracking.
+ */
+declare function smartCopySkills(cwd: string, pkgRoot: string, skillNames: string[], version: string, force?: boolean): void;
+/**
+ * Smart-copy a directory with a standalone manifest (for user-level scaffold).
+ * Manifest stored at `<destRoot>/.kb-scaffold.json`.
+ */
+declare function smartCopySubdir(srcDir: string, destRoot: string, subdir: string, version: 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/. */
@@ -20,4 +43,4 @@ declare function guideScaffold(cwd: string, pkgRoot: string, ide: string): Guide
 /** 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 };
+export { GuideFileEntry, copyDirectoryRecursive, copyScaffold, copySkills, guideScaffold, guideSkills, smartCopyDirectory, smartCopyScaffold, smartCopySkills, smartCopySubdir };

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

@@ -1 +1 @@
-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;a(i).isDirectory()?s(i,d,f,u):(u||!t(d))&&e(i,d)}}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};
+import{mergeFrontmatter as e}from"./frontmatter.js";import{createManifest as t,getFileStatus as n,getUpdateStrategy as r,readManifest as i,recordDeployment as a,writeManifest as o}from"./manifest.js";import{copyFileSync as s,existsSync as c,mkdirSync as l,readFileSync as u,readdirSync as d,statSync as f,writeFileSync as p}from"node:fs";import{dirname as m,resolve as h}from"node:path";function g(e,t,n=``,r=!1){l(t,{recursive:!0});for(let i of d(e)){let a=h(e,i),o=h(t,i),l=n?`${n}/${i}`:i;f(a).isDirectory()?g(a,o,l,r):(r||!c(o))&&s(a,o)}}function _(t,i,o,s=``,g=!1){if(c(t)){l(i,{recursive:!0});for(let v of d(t)){let d=h(t,v),y=h(i,v),b=s?`${s}/${v}`:v;if(f(d).isDirectory()){_(d,y,o,b,g);continue}let x=u(d,`utf-8`);if(g){l(m(y),{recursive:!0}),p(y,x,`utf-8`),a(o,b,x);continue}let S=n(o,b,x);if(S!==`current`){if(S===`new`&&!c(y)){l(m(y),{recursive:!0}),p(y,x,`utf-8`),a(o,b,x);continue}if(S===`new`&&c(y)){a(o,b,x);continue}r(b)===`merge-frontmatter`&&c(y)?p(y,e(x,u(y,`utf-8`)),`utf-8`):(l(m(y),{recursive:!0}),p(y,x,`utf-8`)),a(o,b,x)}}}}function v(e,n,r,a,s=!1){let l=h(n,`scaffold`,r),u=h(e,`.github`),d=h(u,`.kb-scaffold.json`),f=i(d)??t(a);f.version=a;for(let e of[`agents`,`prompts`]){let t=h(l,e);c(t)&&_(t,h(u,e),f,e,s)}o(d,f)}function y(e,n,r,a,s=!1){let l=h(e,`.github`),u=h(l,`.kb-scaffold.json`),d=i(u)??t(a);d.version=a;for(let e of r){let t=h(n,`skills`,e);c(t)&&_(t,h(l,`skills`,e),d,`skills/${e}`,s)}o(u,d)}function b(e,n,r,a,s=!1){let l=h(e,r);if(!c(l))return;let u=h(n,r),d=h(n,`.kb-scaffold.json`),f=i(d)??t(a);f.version=a,_(l,u,f,r,s),o(d,f)}function x(e,t,n,r){if(c(e))for(let i of d(e)){let a=h(e,i),o=n?`${n}/${i}`:i;if(f(a).isDirectory())x(a,h(t,i),o,r);else{let e=h(t,i),n=u(a,`utf-8`);c(e)?n===u(e,`utf-8`)?r.push({status:`current`,relativePath:o,sourcePath:a}):r.push({status:`outdated`,relativePath:o,sourcePath:a,content:n}):r.push({status:`new`,relativePath:o,sourcePath:a,content:n})}}}function S(e,t,n,r=!1){let i=h(t,`scaffold`,n);for(let t of[`agents`,`prompts`]){let n=h(i,t),a=h(e,`.github`,t);c(n)&&g(n,a,``,r)}}function C(e,t,n,r=!1){for(let i of n){let n=h(t,`skills`,i);c(n)&&g(n,h(e,`.github`,`skills`,i),`skills/${i}`,r)}}function w(e,t,n){let r=[],i=h(t,`scaffold`,n);for(let t of[`agents`,`prompts`])x(h(i,t),h(e,`.github`,t),t,r);return r}function T(e,t,n){let r=[];for(let i of n){let n=h(t,`skills`,i);c(n)&&x(n,h(e,`.github`,`skills`,i),`skills/${i}`,r)}return r}export{g as copyDirectoryRecursive,S as copyScaffold,C as copySkills,w as guideScaffold,T as guideSkills,_ as smartCopyDirectory,v as smartCopyScaffold,y as smartCopySkills,b as smartCopySubdir};

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

@@ -1,6 +1,6 @@
 function e(e,t){return`# ${e} — Copilot Instructions
 
-This project has an MCP server (\`${t}\`) providing 64 tools for search, analysis, memory, and validation.
+This project has an MCP server (\`${t}\`) providing 67 tools for search, analysis, memory, and validation.
 **These tools REPLACE most native IDE tools.** You MUST use them.
 
 ## Step 0: Load KB Tools
@@ -8,7 +8,7 @@ This project has an MCP server (\`${t}\`) providing 64 tools for search, analysi
 Before doing ANYTHING else, load the KB MCP tools. They are deferred — you must load them first.
 Search for tools matching the server name (e.g. \`knowledge-bas\`):
 \`\`\`
-tool_search_tool_regex({ pattern: "knowledge-bas" })   // loads all 64 KB tools
+tool_search_tool_regex({ pattern: "knowledge-bas" })   // loads all 67 KB tools
 \`\`\`
 Once loaded, KB tools appear as \`mcp_<server>_<tool>\` (e.g. \`mcp_knowledge-bas_search\`).
 
@@ -26,6 +26,8 @@ Once loaded, KB tools appear as \`mcp_<server>_<tool>\` (e.g. \`mcp_knowledge-ba
 | \`run_in_terminal\` for test | \`test_run({})\` | Run tests with structured output |
 | Manual code tracing | \`trace({ symbol, direction })\` | AST call-graph traversal |
 | Line counting / wc | \`measure({ path })\` | Lines, functions, cognitive complexity |
+| \`fetch_webpage\` | \`web_fetch({ url })\` | Readability extract + token budget — richer output |
+| Web research / browsing | \`web_search({ query })\` | Structured web results without browser — unique to KB |
 
 **\`read_file\` is ONLY acceptable when you need exact line content FOR EDITING (before \`replace_string_in_file\`).**
 Even then, use \`file_summary\` first to identify which lines to read.
@@ -38,20 +40,42 @@ Even then, use \`file_summary\` first to identify which lines to read.
 4. **Validate** — \`check({})\` + \`test_run({})\` before presenting changes. \`blast_radius({ changed_files })\` for impact.
 5. **Lifecycle** — Check \`status({})\` first. If onboard not run, run \`onboard({ path: "." })\`. After implementation, \`reindex({})\` + \`produce_knowledge({})\`. At session end, \`remember()\` checkpoint.
 
+## User Interaction Rules
+
+When you need to explain something or ask for user input:
+
+| Situation | Method | Details |
+|-----------|--------|---------|
+| Simple explanation + question | **Elicitation** | Text-only context is sufficient; ask via elicitation fields |
+| Rich content + question | **\`present\` (html)** + **Elicitation** | Use \`present({ format: "html" })\` for visual explanation, then elicitation for user input |
+| Complex visual + interaction | **\`present\` (browser)** | Use \`present({ format: "browser" })\` for full HTML dashboard; confirmations/selections can use browser actions, other input uses elicitation |
+
+**Rules:**
+- Never dump long tables or complex visuals as plain text — use \`present\` to render them
+- Confirmation selections (yes/no, pick from list) can be handled inside browser mode via actions
+- Free-form text input always goes through elicitation, even when using \`present\` for the explanation
+- Prefer the simplest method that adequately conveys the information
+
 ## Custom Agents
 
 This project has specialized agents in \`.github/agents/\`. Use them instead of built-in modes:
-- **Planner** — for planning and research before implementation
-- **Implementer** — for coding tasks following TDD practices
-- **Researcher** — for deep investigation and context gathering
-- **Explorer** — for rapid codebase navigation
+
+| Category | Agents | Purpose |
+|----------|--------|---------|
+| Orchestration | **Orchestrator**, **Planner** | Lifecycle conductor, TDD implementation plans |
+| Implementation | **Implementer**, **Frontend**, **Refactor** | Code writing, UI/UX, cleanup |
+| Diagnostics | **Debugger**, **Security** | Issue tracing, vulnerability analysis |
+| Research | **Researcher-Alpha/Beta/Gamma/Delta** | Multi-model deep investigation |
+| Review | **Code-Reviewer-Alpha/Beta**, **Architect-Reviewer-Alpha/Beta** | Dual-perspective code and architecture review |
+| Exploration | **Explorer** | Rapid codebase navigation |
+| Documentation | **Documenter** | Comprehensive project docs |
 
 Check \`.github/agents/\` for the full list of available agents.
 `}function t(e,t){return`# ${e} — Agent Instructions
 
 ## KB MCP Server (\`${t}\`)
 
-64 tools for search, code analysis, persistent memory, validation, and context compression.
+67 tools for search, code analysis, persistent memory, validation, and context compression.
 Load them: \`tool_search_tool_regex({ pattern: "knowledge-bas" })\`
 
 ### Skills Reference
@@ -65,6 +89,7 @@ Load them: \`tool_search_tool_regex({ pattern: "knowledge-bas" })\`
 | Engineering lessons | \`lesson-learned\` | After completing work — extract principles from git diffs. |
 | Architecture diagrams | \`c4-architecture\` | When documenting or reviewing architecture — C4 Mermaid diagrams. |
 | Architecture decisions | \`adr-skill\` | When making non-trivial technical decisions — executable ADRs. |
+| Rich presentation | \`present\` | When presenting dashboards, charts, tables, or complex visual content to users. |
 
 ### Tool Categories
 
@@ -74,13 +99,15 @@ Load them: \`tool_search_tool_regex({ pattern: "knowledge-bas" })\`
 | Code Analysis | \`analyze_structure\`, \`analyze_dependencies\`, \`analyze_symbols\`, \`analyze_patterns\`, \`analyze_entry_points\`, \`analyze_diagram\`, \`blast_radius\` | Structure, deps, patterns, impact |
 | Knowledge | \`remember\`, \`read\`, \`update\`, \`forget\`, \`list\`, \`produce_knowledge\` | Persistent cross-session memory |
 | Execution | \`check\`, \`test_run\`, \`eval\`, \`batch\`, \`audit\` | Typecheck, lint, test, run code |
-| Context Compression | \`compact\`, \`digest\`, \`stratum_card\`, \`workset\`, \`stash\`, \`checkpoint\` | Reduce tokens, manage working sets |
+| Context Compression | \`compact\`, \`digest\`, \`stratum_card\`, \`workset\`, \`stash\`, \`checkpoint\`, \`restore\` | Reduce tokens, manage working sets |
 | FORGE | \`forge_ground\`, \`forge_classify\`, \`evidence_map\` | Quality gates for complex tasks |
 | Code Manipulation | \`rename\`, \`codemod\`, \`diff_parse\`, \`data_transform\` | Safe renames, transforms |
 | Web & API | \`web_fetch\`, \`web_search\`, \`http\` | Fetch pages, search web |
 | Lanes | \`lane\` | Isolated file copies for parallel exploration |
 | Git & Environment | \`git_context\`, \`process\`, \`watch\`, \`delegate\` | Git info, process management |
-| Utilities | \`regex_test\`, \`encode\`, \`measure\`, \`changelog\`, \`schema_validate\`, \`snippet\`, \`env\`, \`time\` | Regex, encoding, metrics |
+| Utilities | \`regex_test\`, \`encode\`, \`measure\`, \`changelog\`, \`schema_validate\`, \`snippet\`, \`parse_output\`, \`env\`, \`time\` | Regex, encoding, metrics, output parsing |
+| Presentation | \`present\` | Rich dashboards, charts, tables, timelines |
+| Brainstorming | \`brainstorm\` | Interactive ideation sessions with structured output |
 | System | \`status\`, \`reindex\`, \`health\`, \`guide\`, \`onboard\`, \`graph\`, \`queue\`, \`replay\` | Index management, knowledge graph |
 
 ---
@@ -162,4 +189,6 @@ For long sessions or context approaching capacity, use the \`session-handoff\` s
 **After implementation:** \`check\` → \`test_run\` → \`blast_radius\` → \`reindex\` → \`produce_knowledge\` → \`remember\`
 
 **Complex tasks (FORGE):** \`forge_classify({ task })\` → \`forge_ground({ task })\` → \`evidence_map({ claims })\`
+
+**Quality iteration:** \`check\` → \`test_run\` → \`evidence_map({ action: "gate" })\` → fix → re-gate (max 3 rounds)
 `}export{t as buildAgentsMd,e as buildCopilotInstructions};

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

@@ -18,7 +18,7 @@ interface UserLevelIdePath {
   globalScaffoldRoot: string | null;
   /**
    * User-level instruction file root (may differ from scaffold root).
-   * VS Code uses ~/.github for copilot-instructions.md but ~/.copilot for agents.
+   * VS Code uses ~/.copilot/instructions/ for .instructions.md files.
    * When null, falls back to globalScaffoldRoot.
    */
   instructionsRoot: string | null;
@@ -42,7 +42,7 @@ declare function writeVscodeSettings(idePath: UserLevelIdePath, force?: boolean)
  * global scaffold root.
  *
  * Each IDE has its own global discovery path:
- *   - VS Code / VSCodium:  ~/.copilot/ (agents/, prompts/, skills/) + ~/.github/ (copilot-instructions.md)
+ *   - VS Code / VSCodium:  ~/.copilot/ (agents/, prompts/, skills/, instructions/)
  *   - Claude Code:         ~/.claude/ (CLAUDE.md, agents/)
  *   - Cursor:              ~/.cursor/ (rules/kb.mdc, agents/, prompts/, skills/)
  *   - Windsurf:            ~/.windsurf/ (rules/kb.md, agents/, prompts/, skills/)
@@ -50,7 +50,7 @@ declare function writeVscodeSettings(idePath: UserLevelIdePath, force?: boolean)
  * Multiple IDEs may share the same root (e.g. VS Code + VSCodium both use ~/.copilot/).
  * We deduplicate scaffold files but generate IDE-specific instruction files.
  */
-declare function installGlobalScaffold(pkgRoot: string, ides: UserLevelIdePath[], serverName: string, force?: boolean): void;
+declare function installGlobalScaffold(pkgRoot: string, ides: UserLevelIdePath[], serverName: string, version: string, force?: boolean): void;
 /**
  * Main orchestrator for `kb init --user`.
  */

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

@@ -1,5 +1,5 @@
-import{MCP_SERVER_ENTRY as e,SERVER_NAME as t,SKILL_NAMES as n,VSCODE_SETTINGS as r}from"./constants.js";import{buildAgentsMd as i,buildCopilotInstructions as a}from"./templates.js";import{copyDirectoryRecursive as o}from"./scaffold.js";import{copyFileSync as s,existsSync as c,mkdirSync as l,readFileSync as u,readdirSync as d,statSync as f,writeFileSync as p}from"node:fs";import{dirname as m,resolve as h}from"node:path";import{fileURLToPath as g}from"node:url";import{getGlobalDataDir as _,saveRegistry as v}from"../../../../core/dist/index.js";import{homedir as y}from"node:os";function b(){let e=y(),t=process.platform,n=[],r=h(e,`.copilot`),i=h(e,`.github`),a=h(e,`.claude`),o=h(e,`.cursor`),s=h(e,`.windsurf`);if(t===`win32`){let t=process.env.APPDATA??h(e,`AppData`,`Roaming`);n.push({ide:`VS Code`,configDir:h(t,`Code`,`User`),mcpConfigPath:h(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:h(t,`Code - Insiders`,`User`),mcpConfigPath:h(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:h(t,`VSCodium`,`User`),mcpConfigPath:h(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:h(t,`Cursor`,`User`),mcpConfigPath:h(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:h(t,`Cursor Nightly`,`User`),mcpConfigPath:h(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:h(t,`Windsurf`,`User`),mcpConfigPath:h(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}else if(t===`darwin`){let t=h(e,`Library`,`Application Support`);n.push({ide:`VS Code`,configDir:h(t,`Code`,`User`),mcpConfigPath:h(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:h(t,`Code - Insiders`,`User`),mcpConfigPath:h(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:h(t,`VSCodium`,`User`),mcpConfigPath:h(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:h(t,`Cursor`,`User`),mcpConfigPath:h(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:h(t,`Cursor Nightly`,`User`),mcpConfigPath:h(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:h(t,`Windsurf`,`User`),mcpConfigPath:h(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}else{let t=process.env.XDG_CONFIG_HOME??h(e,`.config`);n.push({ide:`VS Code`,configDir:h(t,`Code`,`User`),mcpConfigPath:h(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:h(t,`Code - Insiders`,`User`),mcpConfigPath:h(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:h(t,`VSCodium`,`User`),mcpConfigPath:h(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:h(t,`Cursor`,`User`),mcpConfigPath:h(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:h(t,`Cursor Nightly`,`User`),mcpConfigPath:h(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:h(t,`Windsurf`,`User`),mcpConfigPath:h(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}return n.push({ide:`Claude Code`,configDir:h(e,`.claude`),mcpConfigPath:h(e,`.claude`,`mcp.json`),globalScaffoldRoot:a,instructionsRoot:null}),n.filter(e=>c(e.configDir))}function x(t,n,r=!1){let{mcpConfigPath:i,configDir:a}=t,o={...e},s={};if(c(i)){try{let e=u(i,`utf-8`);s=JSON.parse(e)}catch{let e=`${i}.bak`;p(e,u(i,`utf-8`),`utf-8`),console.log(`  Backed up invalid ${i} to ${e}`),s={}}if((s.servers??s.mcpServers??{})[n]&&!r){console.log(`  ${t.ide}: ${n} already configured (use --force to update)`);return}}let d=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`,`Windsurf`]).has(t.ide)?`servers`:`mcpServers`,f=s[d]??{};f[n]=o,s[d]=f,l(a,{recursive:!0}),p(i,`${JSON.stringify(s,null,2)}\n`,`utf-8`),console.log(`  ${t.ide}: configured ${n} in ${i}`)}const S=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`]);function C(e,t=!1){if(!S.has(e.ide))return;let n=h(e.configDir,`settings.json`),i={};if(c(n))try{let e=u(n,`utf-8`);i=JSON.parse(e)}catch{console.log(`  ${e.ide}: skipped settings.json (invalid JSON)`);return}let a=!1;for(let[e,n]of Object.entries(r))if(typeof n==`object`&&n){let t=typeof i[e]==`object`&&i[e]!==null?i[e]:{},r={...t,...n};JSON.stringify(r)!==JSON.stringify(t)&&(i[e]=r,a=!0)}else (t||!(e in i))&&(i[e]=n,a=!0);a&&(p(n,`${JSON.stringify(i,null,2)}\n`,`utf-8`),console.log(`  ${e.ide}: updated settings.json`))}function w(e,t,n,r){let i=h(t,n);l(i,{recursive:!0});let a=h(e,`scaffold`,`general`,n);if(!c(a))return 0;let u=0;for(let e of d(a)){let t=h(a,e),l=h(i,e);f(t).isDirectory()?o(t,l,`${n}/${e}`,r):(r||!c(l))&&(s(t,l),u++)}return u}function T(e,t,r,s=!1){let u=new Set;for(let e of t)e.globalScaffoldRoot&&u.add(e.globalScaffoldRoot);if(u.size===0){console.log(`  No IDEs with global scaffold support detected.`);return}for(let t of u){let r=w(e,t,`agents`,s),i=w(e,t,`prompts`,s),a=h(t,`skills`),l=0;for(let t of n){let n=h(e,`skills`,t);c(n)&&(o(n,h(a,t),`skills/${t}`,s),l++)}console.log(`  ${t}: ${r} agents, ${i} prompts, ${l} skills`)}let d=new Set,f=a(`kb`,r),m=i(`kb`,r);for(let e of t){if(!e.globalScaffoldRoot)continue;let t=e.globalScaffoldRoot;if(e.ide===`Claude Code`){let e=h(t,`CLAUDE.md`);(s||!c(e))&&(p(e,`${f}\n---\n\n${m}`,`utf-8`),d.add(e))}else if(e.ide===`VS Code`||e.ide===`VS Code Insiders`||e.ide===`VSCodium`){let n=e.instructionsRoot??t;l(n,{recursive:!0});let r=h(n,`copilot-instructions.md`);d.has(r)||(s||!c(r))&&(p(r,`${f}\n---\n\n${m}`,`utf-8`),d.add(r))}else if(e.ide===`Cursor`||e.ide===`Cursor Nightly`){let e=h(t,`rules`);l(e,{recursive:!0});let n=h(e,`kb.mdc`);d.has(n)||(s||!c(n))&&(p(n,`${f}\n---\n\n${m}`,`utf-8`),d.add(n))}else if(e.ide===`Windsurf`){let e=h(t,`rules`);l(e,{recursive:!0});let n=h(e,`kb.md`);d.has(n)||(s||!c(n))&&(p(n,`${f}\n---\n\n${m}`,`utf-8`),d.add(n))}}d.size>0&&console.log(`  Instruction files: ${[...d].join(`, `)}`)}async function E(e){let n=t,r=h(m(g(import.meta.url)),`..`,`..`,`..`,`..`,`..`,`package.json`),i=JSON.parse(u(r,`utf-8`)).version;console.log(`Initializing @vpxa/kb v${i}...\n`);let a=_();l(a,{recursive:!0}),console.log(`  Global data store: ${a}`),v({version:1,workspaces:{}}),console.log(`  Created registry.json`);let o=b();if(o.length===0)console.log(`
-  No supported IDEs detected. You can manually add the MCP server config.`);else{console.log(`\n  Detected ${o.length} IDE(s):`);for(let t of o)x(t,n,e.force),C(t,e.force)}let s=h(m(g(import.meta.url)),`..`,`..`,`..`,`..`,`..`);console.log(`
-  Installing scaffold files:`),T(s,o,n,e.force),console.log(`
+import{MCP_SERVER_ENTRY as e,SERVER_NAME as t,SKILL_NAMES as n,VSCODE_SETTINGS as r}from"./constants.js";import{buildAgentsMd as i,buildCopilotInstructions as a}from"./templates.js";import{smartCopySubdir as o}from"./scaffold.js";import{existsSync as s,mkdirSync as c,readFileSync as l,writeFileSync as u}from"node:fs";import{dirname as d,resolve as f}from"node:path";import{fileURLToPath as p}from"node:url";import{getGlobalDataDir as m,saveRegistry as h}from"../../../../core/dist/index.js";import{homedir as g}from"node:os";function _(){let e=g(),t=process.platform,n=[],r=f(e,`.copilot`),i=f(r,`instructions`),a=f(e,`.claude`),o=f(e,`.cursor`),c=f(e,`.windsurf`);if(t===`win32`){let t=process.env.APPDATA??f(e,`AppData`,`Roaming`);n.push({ide:`VS Code`,configDir:f(t,`Code`,`User`),mcpConfigPath:f(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:f(t,`Code - Insiders`,`User`),mcpConfigPath:f(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:f(t,`VSCodium`,`User`),mcpConfigPath:f(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:f(t,`Cursor`,`User`),mcpConfigPath:f(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:f(t,`Cursor Nightly`,`User`),mcpConfigPath:f(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:f(t,`Windsurf`,`User`),mcpConfigPath:f(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:c,instructionsRoot:null})}else if(t===`darwin`){let t=f(e,`Library`,`Application Support`);n.push({ide:`VS Code`,configDir:f(t,`Code`,`User`),mcpConfigPath:f(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:f(t,`Code - Insiders`,`User`),mcpConfigPath:f(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:f(t,`VSCodium`,`User`),mcpConfigPath:f(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:f(t,`Cursor`,`User`),mcpConfigPath:f(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:f(t,`Cursor Nightly`,`User`),mcpConfigPath:f(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:f(t,`Windsurf`,`User`),mcpConfigPath:f(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:c,instructionsRoot:null})}else{let t=process.env.XDG_CONFIG_HOME??f(e,`.config`);n.push({ide:`VS Code`,configDir:f(t,`Code`,`User`),mcpConfigPath:f(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:f(t,`Code - Insiders`,`User`),mcpConfigPath:f(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:f(t,`VSCodium`,`User`),mcpConfigPath:f(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:f(t,`Cursor`,`User`),mcpConfigPath:f(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:f(t,`Cursor Nightly`,`User`),mcpConfigPath:f(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:f(t,`Windsurf`,`User`),mcpConfigPath:f(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:c,instructionsRoot:null})}return n.push({ide:`Claude Code`,configDir:f(e,`.claude`),mcpConfigPath:f(e,`.claude`,`mcp.json`),globalScaffoldRoot:a,instructionsRoot:null}),n.filter(e=>s(e.configDir))}function v(t,n,r=!1){let{mcpConfigPath:i,configDir:a}=t,o={...e},d={};if(s(i)){try{let e=l(i,`utf-8`);d=JSON.parse(e)}catch{let e=`${i}.bak`;u(e,l(i,`utf-8`),`utf-8`),console.log(`  Backed up invalid ${i} to ${e}`),d={}}if((d.servers??d.mcpServers??{})[n]&&!r){console.log(`  ${t.ide}: ${n} already configured (use --force to update)`);return}}let f=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`,`Windsurf`]).has(t.ide)?`servers`:`mcpServers`,p=d[f]??{};p[n]=o,d[f]=p,c(a,{recursive:!0}),u(i,`${JSON.stringify(d,null,2)}\n`,`utf-8`),console.log(`  ${t.ide}: configured ${n} in ${i}`)}const y=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`]);function b(e,t=!1){if(!y.has(e.ide))return;let n=f(e.configDir,`settings.json`),i={};if(s(n))try{let e=l(n,`utf-8`);i=JSON.parse(e)}catch{console.log(`  ${e.ide}: skipped settings.json (invalid JSON)`);return}let a=!1;for(let[e,n]of Object.entries(r))if(typeof n==`object`&&n){let t=typeof i[e]==`object`&&i[e]!==null?i[e]:{},r={...t,...n};JSON.stringify(r)!==JSON.stringify(t)&&(i[e]=r,a=!0)}else (t||!(e in i))&&(i[e]=n,a=!0);a&&(u(n,`${JSON.stringify(i,null,2)}\n`,`utf-8`),console.log(`  ${e.ide}: updated settings.json`))}function x(e,t,r,l,d=!1){let p=new Set;for(let e of t)e.globalScaffoldRoot&&p.add(e.globalScaffoldRoot);if(p.size===0){console.log(`  No IDEs with global scaffold support detected.`);return}let m=f(e,`scaffold`,`general`);for(let t of p){o(m,t,`agents`,l,d),o(m,t,`prompts`,l,d);let r=0;for(let i of n)s(f(e,`skills`,i))&&(o(e,t,`skills/${i}`,l,d),r++);console.log(`  ${t}: scaffold updated (${r} skills)`)}let h=new Set,g=a(`kb`,r),_=i(`kb`,r);for(let e of t){if(!e.globalScaffoldRoot)continue;let t=e.globalScaffoldRoot;if(e.ide===`Claude Code`){let e=f(t,`CLAUDE.md`);u(e,`${g}\n---\n\n${_}`,`utf-8`),h.add(e)}else if(e.ide===`VS Code`||e.ide===`VS Code Insiders`||e.ide===`VSCodium`){let n=e.instructionsRoot??t;c(n,{recursive:!0});let r=f(n,`kb.instructions.md`);h.has(r)||(u(r,`---\napplyTo: "**"\n---\n\n${g}\n---\n\n${_}`,`utf-8`),h.add(r))}else if(e.ide===`Cursor`||e.ide===`Cursor Nightly`){let e=f(t,`rules`);c(e,{recursive:!0});let n=f(e,`kb.mdc`);h.has(n)||(u(n,`${g}\n---\n\n${_}`,`utf-8`),h.add(n))}else if(e.ide===`Windsurf`){let e=f(t,`rules`);c(e,{recursive:!0});let n=f(e,`kb.md`);h.has(n)||(u(n,`${g}\n---\n\n${_}`,`utf-8`),h.add(n))}}h.size>0&&console.log(`  Instruction files: ${[...h].join(`, `)}`)}async function S(e){let n=t,r=f(d(p(import.meta.url)),`..`,`..`,`..`,`..`,`..`,`package.json`),i=JSON.parse(l(r,`utf-8`)).version;console.log(`Initializing @vpxa/kb v${i}...\n`);let a=m();c(a,{recursive:!0}),console.log(`  Global data store: ${a}`),h({version:1,workspaces:{}}),console.log(`  Created registry.json`);let o=_();if(o.length===0)console.log(`
+  No supported IDEs detected. You can manually add the MCP server config.`);else{console.log(`\n  Detected ${o.length} IDE(s):`);for(let t of o)v(t,n,e.force),b(t,e.force)}let s=f(d(p(import.meta.url)),`..`,`..`,`..`,`..`,`..`);console.log(`
+  Installing scaffold files:`),x(s,o,n,i,e.force),console.log(`
 User-level KB installation complete!`),console.log(`
-Next steps:`),console.log(`  1. Open any workspace in your IDE`),console.log(`  2. The KB server will auto-start and index the workspace`),console.log(`  3. Agents, prompts, skills & instructions are available globally`),console.log(`  4. No per-workspace init needed — just open a project and start coding`)}export{b as detectInstalledIdes,E as initUser,T as installGlobalScaffold,x as writeUserLevelMcpConfig,C as writeVscodeSettings};
+Next steps:`),console.log(`  1. Open any workspace in your IDE`),console.log(`  2. The KB server will auto-start and index the workspace`),console.log(`  3. Agents, prompts, skills & instructions are available globally`),console.log(`  4. No per-workspace init needed — just open a project and start coding`)}export{_ as detectInstalledIdes,S as initUser,x as installGlobalScaffold,v as writeUserLevelMcpConfig,b as writeVscodeSettings};