@vpxa/kb 0.1.27 → 0.1.29

package/packages/server/dist/tools/utility.tools.js

@@ -1,5 +1,7 @@
-import{getToolMeta as e}from"../tool-metadata.js";import{EnvOutputSchema as t,MeasureOutputSchema as n,TimeOutputSchema as r}from"../output-schemas.js";import{z as i}from"zod";import{createLogger as a,serializeError as o}from"../../../core/dist/index.js";import{changelog as s,encode as c,envInfo as l,httpRequest as u,measure as d,regexTest as f,schemaValidate as p,snippet as m,timeUtils as h,webSearch as g}from"../../../tools/dist/index.js";const _=a(`tools`);function v(t){let n=e(`web_search`);t.registerTool(`web_search`,{title:n.title,description:`PREFERRED web search — search the web via DuckDuckGo (no API key). Returns structured results with title, URL, and snippet.`,inputSchema:{query:i.string().max(2e3).describe(`Search query`),limit:i.number().min(1).max(20).default(5).describe(`Max results to return`),site:i.string().optional().describe(`Restrict to domain (e.g., "docs.aws.amazon.com")`)},annotations:n.annotations},async({query:e,limit:t,site:n})=>{try{let r=await g({query:e,limit:t,site:n}),i=[`## Search: ${r.query}`,``];if(r.results.length===0)i.push(`No results found.`);else for(let e of r.results)i.push(`### [${e.title}](${e.url})`,e.snippet,``);return i.push(`---`,"_Next: Use `web_fetch` to read any of these pages in full._"),{content:[{type:`text`,text:i.join(`
-`)}]}}catch(e){return _.error(`Web search failed`,o(e)),{content:[{type:`text`,text:`Web search failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function y(t){let n=e(`http`);t.registerTool(`http`,{title:n.title,description:`Make HTTP requests (GET/POST/PUT/PATCH/DELETE/HEAD) for API testing. Returns status, headers, and formatted body with timing info.`,inputSchema:{url:i.string().url().describe(`Request URL (http/https only)`),method:i.enum([`GET`,`POST`,`PUT`,`PATCH`,`DELETE`,`HEAD`]).default(`GET`).describe(`HTTP method`),headers:i.record(i.string(),i.string()).optional().describe(`Request headers as key-value pairs`),body:i.string().optional().describe(`Request body (for POST/PUT/PATCH)`),timeout:i.number().min(1e3).max(6e4).default(15e3).describe(`Timeout in milliseconds`)},annotations:n.annotations},async({url:e,method:t,headers:n,body:r,timeout:i})=>{try{let a=await u({url:e,method:t,headers:n,body:r,timeout:i}),o=[`## ${t} ${e}`,``,`**Status:** ${a.status} ${a.statusText}`,`**Time:** ${a.durationMs}ms`,`**Size:** ${a.sizeBytes} bytes`,`**Content-Type:** ${a.contentType}`,``,`### Headers`,"```json",JSON.stringify(a.headers),"```",``,`### Body`,a.contentType.includes(`json`)?"```json":"```",a.body,"```"];return a.truncated&&o.push(``,`_Response truncated — total size: ${a.sizeBytes} bytes_`),{content:[{type:`text`,text:o.join(`
+import{getToolMeta as e}from"../tool-metadata.js";import{EnvOutputSchema as t,MeasureOutputSchema as n,TimeOutputSchema as r}from"../output-schemas.js";import{z as i}from"zod";import{createLogger as a,serializeError as o}from"../../../core/dist/index.js";import{changelog as s,encode as c,envInfo as l,httpRequest as u,measure as d,regexTest as f,schemaValidate as p,snippet as m,timeUtils as h,webSearch as g}from"../../../tools/dist/index.js";const _=a(`tools`);function v(t){let n=e(`web_search`);t.registerTool(`web_search`,{title:n.title,description:`PREFERRED web search — search the web via DuckDuckGo (no API key). Pass one query or multiple for parallel searching. Returns structured results with title, URL, and snippet.`,inputSchema:{queries:i.array(i.string().max(2e3)).min(1).max(5).describe('Search queries (1–5). Single: `["react hooks"]`. Multiple searched in parallel.'),limit:i.number().min(1).max(20).default(5).describe(`Max results per query`),site:i.string().optional().describe(`Restrict to domain (e.g., "docs.aws.amazon.com")`)},annotations:n.annotations},async({queries:e,limit:t,site:n})=>{let r=e,i=async e=>{let r=await g({query:e,limit:t,site:n}),i=[`## Search: ${r.query}`,``];if(r.results.length===0)i.push(`No results found.`);else for(let e of r.results)i.push(`### [${e.title}](${e.url})`,e.snippet,``);return i.join(`
+`)};if(r.length===1)try{return{content:[{type:`text`,text:`${await i(r[0])}\n---\n_Next: Use \`web_fetch\` to read any of these pages in full._`}]}}catch(e){return _.error(`Web search failed`,o(e)),{content:[{type:`text`,text:`Web search failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}let a=await Promise.allSettled(r.map(e=>i(e))),s=[],c=0;for(let e=0;e<a.length;e++){let t=a[e];if(t.status===`fulfilled`)s.push(t.value);else{c++;let n=t.reason instanceof Error?t.reason.message:String(t.reason);_.error(`Web search failed`,{query:r[e],error:n}),s.push(`## ❌ Search failed: ${r[e]}\n\n${n}`)}}let l=`_Searched ${a.length-c}/${a.length} queries successfully._`;return s.push(``,`---`,l,"_Next: Use `web_fetch` to read any of these pages in full._"),{content:[{type:`text`,text:s.join(`
+
+`)}],...c===a.length?{isError:!0}:{}}})}function y(t){let n=e(`http`);t.registerTool(`http`,{title:n.title,description:`Make HTTP requests (GET/POST/PUT/PATCH/DELETE/HEAD) for API testing. Returns status, headers, and formatted body with timing info.`,inputSchema:{url:i.string().url().describe(`Request URL (http/https only)`),method:i.enum([`GET`,`POST`,`PUT`,`PATCH`,`DELETE`,`HEAD`]).default(`GET`).describe(`HTTP method`),headers:i.record(i.string(),i.string()).optional().describe(`Request headers as key-value pairs`),body:i.string().optional().describe(`Request body (for POST/PUT/PATCH)`),timeout:i.number().min(1e3).max(6e4).default(15e3).describe(`Timeout in milliseconds`)},annotations:n.annotations},async({url:e,method:t,headers:n,body:r,timeout:i})=>{try{let a=await u({url:e,method:t,headers:n,body:r,timeout:i}),o=[`## ${t} ${e}`,``,`**Status:** ${a.status} ${a.statusText}`,`**Time:** ${a.durationMs}ms`,`**Size:** ${a.sizeBytes} bytes`,`**Content-Type:** ${a.contentType}`,``,`### Headers`,"```json",JSON.stringify(a.headers),"```",``,`### Body`,a.contentType.includes(`json`)?"```json":"```",a.body,"```"];return a.truncated&&o.push(``,`_Response truncated — total size: ${a.sizeBytes} bytes_`),{content:[{type:`text`,text:o.join(`
 `)}]}}catch(e){return _.error(`HTTP request failed`,o(e)),{content:[{type:`text`,text:`HTTP request failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function b(t){let n=e(`regex_test`);t.registerTool(`regex_test`,{title:n.title,description:`Test a regex pattern against sample strings. Supports match, replace, and split modes.`,inputSchema:{pattern:i.string().max(500).describe(`Regex pattern (without delimiters)`),flags:i.string().max(10).regex(/^[gimsuy]*$/).default(``).describe(`Regex flags (g, i, m, s, etc.)`),test_strings:i.array(i.string().max(1e4)).max(50).describe(`Strings to test the pattern against`),mode:i.enum([`match`,`replace`,`split`]).default(`match`).describe(`Test mode`),replacement:i.string().optional().describe(`Replacement string (for replace mode)`)},annotations:n.annotations},async({pattern:e,flags:t,test_strings:n,mode:r,replacement:i})=>{let a=f({pattern:e,flags:t,testStrings:n,mode:r,replacement:i});if(!a.valid)return{content:[{type:`text`,text:`Invalid regex: ${a.error}`}],isError:!0};let o=[`## Regex: \`/${a.pattern}/${a.flags}\``,``,`Mode: ${r}`,``];for(let e of a.results){if(o.push(`**Input:** \`${e.input}\``),o.push(`**Matched:** ${e.matched}`),e.matches)for(let t of e.matches){let e=t.groups.length>0?` groups: [${t.groups.join(`, `)}]`:``;o.push(`  - "${t.full}" at index ${t.index}${e}`)}e.replaced!==void 0&&o.push(`**Result:** \`${e.replaced}\``),e.split&&o.push(`**Split:** ${JSON.stringify(e.split)}`),o.push(``)}return{content:[{type:`text`,text:o.join(`
 `)}]}})}function x(t){let n=e(`encode`);t.registerTool(`encode`,{title:n.title,description:`Encode, decode, or hash text. Supports base64, URL encoding, SHA-256, MD5, JWT decode, hex.`,inputSchema:{operation:i.enum([`base64_encode`,`base64_decode`,`url_encode`,`url_decode`,`sha256`,`md5`,`jwt_decode`,`hex_encode`,`hex_decode`]).describe(`Operation to perform`),input:i.string().max(1e6).describe(`Input text`)},annotations:n.annotations},async({operation:e,input:t})=>{try{let n=c({operation:e,input:t});return{content:[{type:`text`,text:`## ${e}\n\n**Input:** \`${t.length>100?`${t.slice(0,100)}...`:t}\`\n**Output:**\n\`\`\`\n${n.output}\n\`\`\``}]}}catch(e){return _.error(`Encode failed`,o(e)),{content:[{type:`text`,text:`Encode failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function S(t){let r=e(`measure`);t.registerTool(`measure`,{title:r.title,description:`Measure code complexity, line counts, and function counts for a file or directory. Returns per-file metrics sorted by complexity.`,outputSchema:n,inputSchema:{path:i.string().describe(`File or directory path to measure`),extensions:i.array(i.string()).optional().describe(`File extensions to include (default: .ts,.tsx,.js,.jsx)`)},annotations:r.annotations},async({path:e,extensions:t})=>{try{let n=await d({path:e,extensions:t}),r=[`## Code Metrics`,``,`**Files:** ${n.summary.totalFiles}`,`**Total lines:** ${n.summary.totalLines} (${n.summary.totalCodeLines} code)`,`**Functions:** ${n.summary.totalFunctions}`,`**Avg complexity:** ${n.summary.avgComplexity}`,`**Max complexity:** ${n.summary.maxComplexity.value} (${n.summary.maxComplexity.file})`,``,`### Top files by complexity`,``,`| File | Lines | Code | Complexity | Cognitive | Functions | Imports |`,`|------|-------|------|------------|-----------|-----------|---------|`];for(let e of n.files.slice(0,20)){let t=e.cognitiveComplexity===void 0?`—`:String(e.cognitiveComplexity);r.push(`| ${e.path} | ${e.lines.total} | ${e.lines.code} | ${e.complexity} | ${t} | ${e.functions} | ${e.imports} |`)}n.files.length>20&&r.push(``,`_...and ${n.files.length-20} more files_`);let i={summary:{totalFiles:n.summary.totalFiles,totalLines:n.summary.totalLines,totalCodeLines:n.summary.totalCodeLines,totalFunctions:n.summary.totalFunctions,avgComplexity:n.summary.avgComplexity,maxComplexity:{value:n.summary.maxComplexity.value,file:n.summary.maxComplexity.file}},files:n.files.map(e=>({path:e.path,lines:e.lines.total,code:e.lines.code,complexity:e.complexity,functions:e.functions}))};return{content:[{type:`text`,text:r.join(`
 `)}],structuredContent:i}}catch(e){return _.error(`Measure failed`,o(e)),{content:[{type:`text`,text:`Measure failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function C(t){let n=e(`changelog`);t.registerTool(`changelog`,{title:n.title,description:`Generate a changelog from git history between two refs. Groups by conventional commit type.`,inputSchema:{from:i.string().max(200).describe(`Start ref (tag, SHA, HEAD~N)`),to:i.string().max(200).default(`HEAD`).describe(`End ref (default: HEAD)`),format:i.enum([`grouped`,`chronological`,`per-scope`]).default(`grouped`).describe(`Output format`),include_breaking:i.boolean().default(!0).describe(`Highlight breaking changes`),cwd:i.string().optional().describe(`Repository root or working directory`)},annotations:n.annotations},async({from:e,to:t,format:n,include_breaking:r,cwd:i})=>{try{let a=s({from:e,to:t,format:n,includeBreaking:r,cwd:i}),o=`${a.stats.total} commits (${Object.entries(a.stats.types).map(([e,t])=>`${t} ${e}`).join(`, `)})`;return{content:[{type:`text`,text:`${a.markdown}\n---\n_${o}_`}]}}catch(e){return _.error(`Changelog failed`,o(e)),{content:[{type:`text`,text:`Changelog failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function w(t){let n=e(`schema_validate`);t.registerTool(`schema_validate`,{title:n.title,description:`Validate JSON data against a JSON Schema. Supports type, required, properties, items, enum, pattern, min/max.`,inputSchema:{data:i.string().max(5e5).describe(`JSON data to validate (as string)`),schema:i.string().max(5e5).describe(`JSON Schema to validate against (as string)`)},annotations:n.annotations},async({data:e,schema:t})=>{try{let n=p({data:JSON.parse(e),schema:JSON.parse(t)});if(n.valid)return{content:[{type:`text`,text:`## Validation: PASSED

package/packages/server/dist/version-check.js

@@ -1 +1 @@
-import{readFileSync as e}from"node:fs";import{dirname as t,resolve as n}from"node:path";import{fileURLToPath as r}from"node:url";import{createLogger as i}from"../../core/dist/index.js";const a=i(`server`);function o(){let i=n(t(r(import.meta.url)),`..`,`..`,`..`,`package.json`);try{return JSON.parse(e(i,`utf-8`)).version??`0.0.0`}catch{return`0.0.0`}}function s(e,t){let n=e.split(`.`).map(Number),r=t.split(`.`).map(Number);for(let e=0;e<3;e++){let t=(n[e]??0)-(r[e]??0);if(t!==0)return t>0?1:-1}return 0}function c(){let e=o();fetch(`https://registry.npmjs.org/@vpxa/kb/latest`,{signal:AbortSignal.timeout(5e3)}).then(e=>{if(e.ok)return e.json()}).then(t=>{if(!t||typeof t!=`object`)return;let n=t.version;n&&s(e,n)<0&&a.warn(`Update available`,{currentVersion:e,latestVersion:n,updateCommand:`npx @vpxa/kb@${n} serve`,configHint:`update your mcp.json`})}).catch(()=>{})}export{c as checkForUpdates,o as getCurrentVersion};
+import{readFileSync as e}from"node:fs";import{dirname as t,resolve as n}from"node:path";import{fileURLToPath as r}from"node:url";import{createLogger as i}from"../../core/dist/index.js";const a=i(`server`);function o(){let i=n(t(r(import.meta.url)),`..`,`..`,`..`,`package.json`);try{return JSON.parse(e(i,`utf-8`)).version??`0.0.0`}catch{return`0.0.0`}}function s(e,t){let n=e.split(`.`).map(Number),r=t.split(`.`).map(Number);for(let e=0;e<3;e++){let t=(n[e]??0)-(r[e]??0);if(t!==0)return t>0?1:-1}return 0}function c(){let e=o();fetch(`https://registry.npmjs.org/@vpxa/kb/latest`,{signal:AbortSignal.timeout(5e3)}).then(e=>{if(e.ok)return e.json()}).then(t=>{if(!t||typeof t!=`object`)return;let n=t.version;n&&s(e,n)<0&&a.warn(`Update available`,{currentVersion:e,latestVersion:n,updateCommand:`npx -y @vpxa/kb upgrade`})}).catch(()=>{})}export{c as checkForUpdates,o as getCurrentVersion};

package/packages/store/dist/lance-store.d.ts

@@ -1,5 +1,5 @@
 import { IKnowledgeStore, SearchOptions } from "./store.interface.js";
-import { IndexStats, KnowledgeRecord, SearchResult } from "@kb/core";
+import { IndexStats, KnowledgeRecord, SearchResult } from "../../core/dist/index.js";
 
 //#region packages/store/src/lance-store.d.ts
 declare class LanceStore implements IKnowledgeStore {

package/packages/store/dist/store.interface.d.ts

@@ -1,4 +1,4 @@
-import { ContentType, IndexStats, KnowledgeOrigin, KnowledgeRecord, SearchResult, SourceType } from "@kb/core";
+import { ContentType, IndexStats, KnowledgeOrigin, KnowledgeRecord, SearchResult, SourceType } from "../../core/dist/index.js";
 
 //#region packages/store/src/store.interface.d.ts
 /** Options for searching the store */

package/packages/tools/dist/audit.d.ts

@@ -1,6 +1,6 @@
 import { KBResponse } from "./response-envelope.js";
-import { IEmbedder } from "@kb/embeddings";
-import { IKnowledgeStore } from "@kb/store";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IKnowledgeStore } from "../../store/dist/index.js";
 
 //#region packages/tools/src/audit.d.ts
 type AuditCheck = 'structure' | 'dependencies' | 'patterns' | 'health' | 'dead_symbols' | 'check' | 'entry_points';

package/packages/tools/dist/compact.d.ts

@@ -1,5 +1,5 @@
 import { FileCache } from "./file-cache.js";
-import { IEmbedder } from "@kb/embeddings";
+import { IEmbedder } from "../../embeddings/dist/index.js";
 
 //#region packages/tools/src/compact.d.ts
 interface CompactOptions {

package/packages/tools/dist/dead-symbols.d.ts

@@ -1,5 +1,5 @@
-import { IEmbedder } from "@kb/embeddings";
-import { IKnowledgeStore } from "@kb/store";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IKnowledgeStore } from "../../store/dist/index.js";
 
 //#region packages/tools/src/dead-symbols.d.ts
 interface DeadSymbolOptions {

package/packages/tools/dist/digest.d.ts

@@ -1,4 +1,4 @@
-import { IEmbedder } from "@kb/embeddings";
+import { IEmbedder } from "../../embeddings/dist/index.js";
 
 //#region packages/tools/src/digest.d.ts
 interface DigestSource {

package/packages/tools/dist/find-examples.d.ts

@@ -1,6 +1,6 @@
-import { IEmbedder } from "@kb/embeddings";
-import { IKnowledgeStore } from "@kb/store";
-import { ContentType } from "@kb/core";
+import { ContentType } from "../../core/dist/index.js";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IKnowledgeStore } from "../../store/dist/index.js";
 
 //#region packages/tools/src/find-examples.d.ts
 interface FindExamplesOptions {

package/packages/tools/dist/find.d.ts

@@ -1,6 +1,6 @@
-import { IEmbedder } from "@kb/embeddings";
-import { IKnowledgeStore } from "@kb/store";
-import { ContentType } from "@kb/core";
+import { ContentType } from "../../core/dist/index.js";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IKnowledgeStore } from "../../store/dist/index.js";
 
 //#region packages/tools/src/find.d.ts
 interface FindOptions {
@@ -36,6 +36,10 @@ interface FindResults {
   results: FindResult[];
   strategies: string[];
   totalFound: number;
+  failedStrategies?: Array<{
+    strategy: string;
+    reason: string;
+  }>;
 }
 /**
  * Run federated search across multiple strategies.

package/packages/tools/dist/find.js

@@ -1 +1 @@
-import{KB_PATHS as e}from"../../core/dist/index.js";async function t(t,n,r){let{query:i,glob:a,pattern:o,limit:s=10,contentType:c,cwd:l=process.cwd()}=r,u=[],d=[],f=new Set;if(i){u.push(`vector`);let e=await t.embed(i),r={limit:s,contentType:c},a=await n.search(e,r);for(let e of a){let t=`${e.record.sourcePath}:${e.record.startLine}`;f.has(t)||(f.add(t),d.push({path:e.record.sourcePath,source:`vector`,score:e.score,lineRange:{start:e.record.startLine,end:e.record.endLine},preview:e.record.content.slice(0,200)}))}}if(i){u.push(`keyword`);try{let e=await n.ftsSearch(i,{limit:s,contentType:c});for(let t of e){let e=`${t.record.sourcePath}:${t.record.startLine}`;f.has(e)||(f.add(e),d.push({path:t.record.sourcePath,source:`keyword`,score:t.score,lineRange:{start:t.record.startLine,end:t.record.endLine},preview:t.record.content.slice(0,200)}))}}catch{}}if(a){u.push(`glob`);try{let{globSync:t}=await import(`node:fs`),n=t(a,{cwd:l,withFileTypes:!1}),r=new Set([`node_modules`,`.git`,`dist`,`build`,`coverage`,`.turbo`,`.cache`,`cdk.out`,e.state,e.data]),i=n.filter(e=>!e.replace(/\\/g,`/`).split(`/`).some(e=>r.has(e)));for(let e of i.slice(0,s)){let t=`glob:${e}`;f.has(t)||(f.add(t),d.push({path:e,source:`glob`,score:1}))}}catch{}}if(o){u.push(`pattern`);try{let e=new RegExp(o,`i`),t=await n.ftsSearch(o,{limit:s*2,contentType:c});for(let n of t)if(e.test(n.record.content)){let e=`${n.record.sourcePath}:${n.record.startLine}`;f.has(e)||(f.add(e),d.push({path:n.record.sourcePath,source:`pattern`,score:n.score,lineRange:{start:n.record.startLine,end:n.record.endLine},preview:n.record.content.slice(0,200)}))}}catch{}}return d.sort((e,t)=>t.score-e.score),{results:d.slice(0,s),strategies:u,totalFound:d.length}}export{t as find};
+import{KB_PATHS as e}from"../../core/dist/index.js";async function t(t,n,r){let{query:i,glob:a,pattern:o,limit:s=10,contentType:c,cwd:l=process.cwd()}=r,u=[],d=[],f=new Set,p=[];if(i){u.push(`vector`);let e=await t.embed(i),r={limit:s,contentType:c},a=await n.search(e,r);for(let e of a){let t=`${e.record.sourcePath}:${e.record.startLine}`;f.has(t)||(f.add(t),d.push({path:e.record.sourcePath,source:`vector`,score:e.score,lineRange:{start:e.record.startLine,end:e.record.endLine},preview:e.record.content.slice(0,200)}))}}if(i){u.push(`keyword`);try{let e=await n.ftsSearch(i,{limit:s,contentType:c});for(let t of e){let e=`${t.record.sourcePath}:${t.record.startLine}`;f.has(e)||(f.add(e),d.push({path:t.record.sourcePath,source:`keyword`,score:t.score,lineRange:{start:t.record.startLine,end:t.record.endLine},preview:t.record.content.slice(0,200)}))}}catch(e){p.push({strategy:`keyword`,reason:e instanceof Error?e.message:String(e)})}}if(a){u.push(`glob`);try{let{globSync:t}=await import(`node:fs`),n=t(a,{cwd:l,withFileTypes:!1}),r=new Set([`node_modules`,`.git`,`dist`,`build`,`coverage`,`.turbo`,`.cache`,`cdk.out`,e.state,e.data]),i=n.filter(e=>!e.replace(/\\/g,`/`).split(`/`).some(e=>r.has(e)));for(let e of i.slice(0,s)){let t=`glob:${e}`;f.has(t)||(f.add(t),d.push({path:e,source:`glob`,score:1}))}}catch(e){p.push({strategy:`glob`,reason:e instanceof Error?e.message:String(e)})}}if(o){u.push(`pattern`);try{let e=new RegExp(o,`i`),t=await n.ftsSearch(o,{limit:s*2,contentType:c});for(let n of t)if(e.test(n.record.content)){let e=`${n.record.sourcePath}:${n.record.startLine}`;f.has(e)||(f.add(e),d.push({path:n.record.sourcePath,source:`pattern`,score:n.score,lineRange:{start:n.record.startLine,end:n.record.endLine},preview:n.record.content.slice(0,200)}))}}catch(e){p.push({strategy:`pattern`,reason:e instanceof Error?e.message:String(e)})}}return d.sort((e,t)=>t.score-e.score),{results:d.slice(0,s),strategies:u,totalFound:d.length,...p.length>0&&{failedStrategies:p}}}export{t as find};

package/packages/tools/dist/forge-ground.d.ts

@@ -1,8 +1,8 @@
 import { ForgeTier } from "./evidence-map.js";
 import { ClassifyTrigger, TypedUnknownSeed } from "./forge-classify.js";
 import { ScopeMapResult } from "./scope-map.js";
-import { IEmbedder } from "@kb/embeddings";
-import { IKnowledgeStore } from "@kb/store";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IKnowledgeStore } from "../../store/dist/index.js";
 
 //#region packages/tools/src/forge-ground.d.ts
 interface ForgeGroundOptions {

package/packages/tools/dist/graph-query.d.ts

@@ -1,4 +1,4 @@
-import { GraphEdge, GraphNode, GraphStats, GraphTraversalResult, GraphValidationResult, IGraphStore } from "@kb/store";
+import { GraphEdge, GraphNode, GraphStats, GraphTraversalResult, GraphValidationResult, IGraphStore } from "../../store/dist/index.js";
 
 //#region packages/tools/src/graph-query.d.ts
 interface GraphQueryOptions {

package/packages/tools/dist/onboard.js

@@ -1,2 +1,18 @@
-import{extractConfigValues as e}from"./config-extractor.js";import{buildDiagrams as t}from"./diagram-builder.js";import{buildCodeMap as n,buildSynthesisGuide as r}from"./synthesis-engine.js";import{DependencyAnalyzer as i,DiagramGenerator as a,EntryPointAnalyzer as o,PatternAnalyzer as s,StructureAnalyzer as c,SymbolAnalyzer as l,extractRegexCallGraph as u,extractTsCallGraph as d}from"../../analyzers/dist/index.js";import{basename as f,join as p,resolve as m}from"node:path";import{existsSync as h,mkdirSync as g,readdirSync as _,rmSync as v,writeFileSync as y}from"node:fs";import{KB_PATHS as b}from"../../core/dist/index.js";const x={structure:`Project Structure`,dependencies:`Dependencies`,"entry-points":`Entry Points`,symbols:`Symbols`,patterns:`Patterns`,diagram:`C4 Container Diagram`,"code-map":`Code Map (Module Graph)`,"config-values":`Configuration Values`,"synthesis-guide":`Synthesis Guide`};async function S(S){let C=Date.now(),w=m(S.path),T=f(w),E=S.mode??`memory`,D=S.outDir??p(w,b.aiKb),O=new c,k=new i,A=new l,j=new s,M=new o,N=new a,P=[{name:`structure`,fn:()=>O.analyze(w,{format:`markdown`,maxDepth:3,sourceOnly:!0})},{name:`dependencies`,fn:()=>k.analyze(w,{format:`markdown`})},{name:`entry-points`,fn:()=>M.analyze(w)},{name:`symbols`,fn:()=>A.analyze(w,{format:`markdown`})},{name:`patterns`,fn:()=>j.analyze(w)},{name:`diagram`,fn:()=>N.analyze(w,{diagramType:`architecture`})}],F=await Promise.allSettled(P.map(async e=>{let t=Date.now(),n=await e.fn();return{name:e.name,result:n,durationMs:Date.now()-t}})),I=[],L=new Map,R=new Map;for(let e of F)if(e.status===`fulfilled`){let{name:t,result:n,durationMs:r}=e.value,i=n;I.push({name:t,status:`success`,output:i.output,durationMs:r}),L.set(t,i.output),R.set(t,i.data)}else{let t=e.reason,n=P[F.indexOf(e)].name;I.push({name:n,status:`failed`,output:``,durationMs:0,error:t.message})}let z=Date.now(),B=null;try{let e=await d(w);if((!e||e.edges.length===0)&&(e=await u(w)),e&&e.edges.length>0){B=new Map;for(let t of e.edges){let e=B.get(t.from);e||(e=new Map,B.set(t.from,e));let n=e.get(t.to);if(n)for(let e of t.symbols)n.includes(e)||n.push(e);else e.set(t.to,[...t.symbols])}}}catch{}let V=Date.now()-z,H=Date.now(),U=n(R,T,B),W=Date.now()-H+V;if(I.push({name:`code-map`,status:`success`,output:U,durationMs:W}),L.set(`code-map`,U),B&&B.size>0){let e=t(B,R,T),n=I.find(e=>e.name===`diagram`);n&&(n.output=e,L.set(`diagram`,e))}let G=Date.now(),K=await e(w,T),q=Date.now()-G;I.push({name:`config-values`,status:`success`,output:K,durationMs:q}),L.set(`config-values`,K);let J=r(I,E,T,R);if(I.push({name:`synthesis-guide`,status:`success`,output:J,durationMs:0}),L.set(`synthesis-guide`,J),E===`generate`){if(h(D))for(let e of _(D))(e.endsWith(`.md`)||e.endsWith(`.json`))&&v(p(D,e),{force:!0});g(D,{recursive:!0});let e=new Date().toISOString();for(let[t,n]of L){let r=p(D,`${t}.md`),i=n.replaceAll(w,T);y(r,`<!-- Generated: ${e} -->\n<!-- Project: ${T} -->\n<!-- Source: ${w} -->\n\n`+i,`utf-8`)}let t=[`<!-- Generated: ${e} -->`,`<!-- Project: ${T} -->`,`<!-- Source: ${w} -->`,``,`# ${T} — Codebase Knowledge`,``,`## Contents`,``];for(let e of I){let n=`${e.name}.md`,r=x[e.name]??e.name,i=e.status===`success`?`✓`:`✗`,a=e.durationMs>0?` (${e.durationMs}ms)`:``;t.push(`- ${i} [${r}](./${n})${a}`)}t.push(``),y(p(D,`README.md`),t.join(`
-`),`utf-8`)}return{path:w,mode:E,steps:I,outDir:E===`generate`?D:void 0,totalDurationMs:Date.now()-C}}export{S as onboard};
+import{extractConfigValues as e}from"./config-extractor.js";import{buildDiagrams as t}from"./diagram-builder.js";import{buildCodeMap as n,buildSynthesisGuide as r}from"./synthesis-engine.js";import{DependencyAnalyzer as i,DiagramGenerator as a,EntryPointAnalyzer as o,PatternAnalyzer as s,StructureAnalyzer as c,SymbolAnalyzer as l,extractRegexCallGraph as u,extractTsCallGraph as d}from"../../analyzers/dist/index.js";import{basename as f,join as p,resolve as m}from"node:path";import{existsSync as h,mkdirSync as g,readdirSync as _,rmSync as v,writeFileSync as y}from"node:fs";import{KB_PATHS as b}from"../../core/dist/index.js";const x={structure:`Project Structure`,dependencies:`Dependencies`,"entry-points":`Entry Points`,symbols:`Symbols`,patterns:`Patterns`,diagram:`C4 Container Diagram`,"code-map":`Code Map (Module Graph)`,"config-values":`Configuration Values`,"synthesis-guide":`Synthesis Guide`,"api-surface":`API Surface`,"type-inventory":`Type Inventory`};function S(e){let t=e.get(`symbols`);if(!t?.symbols?.length)return`# API Surface
+
+*No symbol data available.*
+`;let n=t.symbols.filter(e=>e.exported);if(n.length===0)return`# API Surface
+
+*No exported symbols found.*
+`;let r=new Map;for(let e of n){let t=r.get(e.filePath)??[];t.push(e),r.set(e.filePath,t)}let i=[`# API Surface
+`];for(let[e,t]of[...r.entries()].sort(([e],[t])=>e.localeCompare(t))){i.push(`## ${e}\n`);for(let e of t){e.decorators?.length&&i.push(e.decorators.join(` `));let t=e.signature??``,n=e.returnType?`: ${e.returnType}`:``;if(e.kind===`function`||e.kind===`method`)i.push(`### \`${e.name}${t}${n}\``);else if(e.kind===`class`)i.push(`### class \`${e.name}\`${t?` ${t}`:``}`);else if(e.kind===`interface`||e.kind===`type`){let t=e.typeBody?` ${e.typeBody}`:``;i.push(`### ${e.kind} \`${e.name}\`${t}`)}else i.push(`### ${e.kind} \`${e.name}\`${t?`: ${t}`:``}`);e.jsdoc&&i.push(`> ${e.jsdoc}`),i.push(``)}}let a=i.join(`
+`);return a.length>1e5?`${a.slice(0,1e5)}\n\n*[truncated]*`:a}function C(e){let t=e.get(`symbols`);if(!t?.symbols?.length)return`# Type Inventory
+
+*No symbol data available.*
+`;let n=t.symbols.filter(e=>e.exported&&(e.kind===`interface`||e.kind===`type`||e.kind===`enum`));if(n.length===0)return`# Type Inventory
+
+*No exported types/interfaces found.*
+`;let r=new Map;for(let e of n){let t=r.get(e.filePath)??[];t.push(e),r.set(e.filePath,t)}let i=[`# Type Inventory
+`];for(let[e,t]of[...r.entries()].sort(([e],[t])=>e.localeCompare(t))){i.push(`## ${e}\n`);for(let e of t){let t=e.typeBody??`*body not available*`;e.jsdoc&&i.push(`> ${e.jsdoc}`),i.push(`### ${e.kind} \`${e.name}\``),i.push("```"),i.push(t),i.push("```\n")}}let a=i.join(`
+`);return a.length>1e5?`${a.slice(0,1e5)}\n\n*[truncated]*`:a}async function w(w){let T=Date.now(),E=m(w.path),D=f(E),O=w.mode??`generate`,k=w.outDir??p(E,b.aiKb),A=new c,j=new i,M=new l,N=new s,P=new o,F=new a,I=[{name:`structure`,fn:()=>A.analyze(E,{format:`markdown`,maxDepth:3,sourceOnly:!0})},{name:`dependencies`,fn:()=>j.analyze(E,{format:`markdown`})},{name:`entry-points`,fn:()=>P.analyze(E)},{name:`symbols`,fn:()=>M.analyze(E,{format:`markdown`})},{name:`patterns`,fn:()=>N.analyze(E)},{name:`diagram`,fn:()=>F.analyze(E,{diagramType:`architecture`})}],L=await Promise.allSettled(I.map(async e=>{let t=Date.now(),n=await e.fn();return{name:e.name,result:n,durationMs:Date.now()-t}})),R=[],z=new Map,B=new Map;for(let e of L)if(e.status===`fulfilled`){let{name:t,result:n,durationMs:r}=e.value,i=n;R.push({name:t,status:`success`,output:i.output,durationMs:r}),z.set(t,i.output),B.set(t,i.data)}else{let t=e.reason,n=I[L.indexOf(e)].name;R.push({name:n,status:`failed`,output:``,durationMs:0,error:t.message})}let V=Date.now(),H=null;try{let e=await d(E);if((!e||e.edges.length===0)&&(e=await u(E)),e&&e.edges.length>0){H=new Map;for(let t of e.edges){let e=H.get(t.from);e||(e=new Map,H.set(t.from,e));let n=e.get(t.to);if(n)for(let e of t.symbols)n.includes(e)||n.push(e);else e.set(t.to,[...t.symbols])}}}catch{}let U=Date.now()-V,W=Date.now(),G=n(B,D,H),K=Date.now()-W+U;if(R.push({name:`code-map`,status:`success`,output:G,durationMs:K}),z.set(`code-map`,G),H&&H.size>0){let e=t(H,B,D),n=R.find(e=>e.name===`diagram`);n&&(n.output=e,z.set(`diagram`,e))}let q=Date.now(),J=await e(E,D),Y=Date.now()-q;R.push({name:`config-values`,status:`success`,output:J,durationMs:Y}),z.set(`config-values`,J);let X=r(R,O,D,B);R.push({name:`synthesis-guide`,status:`success`,output:X,durationMs:0}),z.set(`synthesis-guide`,X);let Z=S(B);R.push({name:`api-surface`,status:`success`,output:Z,durationMs:0}),z.set(`api-surface`,Z);let Q=C(B);if(R.push({name:`type-inventory`,status:`success`,output:Q,durationMs:0}),z.set(`type-inventory`,Q),O===`generate`){if(h(k))for(let e of _(k))(e.endsWith(`.md`)||e.endsWith(`.json`))&&v(p(k,e),{force:!0});g(k,{recursive:!0});let e=new Date().toISOString();for(let[t,n]of z){let r=p(k,`${t}.md`),i=n.replaceAll(E,D);y(r,`<!-- Generated: ${e} -->\n<!-- Project: ${D} -->\n<!-- Source: ${E} -->\n\n`+i,`utf-8`)}let t=[`<!-- Generated: ${e} -->`,`<!-- Project: ${D} -->`,`<!-- Source: ${E} -->`,``,`# ${D} — Codebase Knowledge`,``,`## Contents`,``];for(let e of R){let n=`${e.name}.md`,r=x[e.name]??e.name,i=e.status===`success`?`✓`:`✗`,a=e.durationMs>0?` (${e.durationMs}ms)`:``;t.push(`- ${i} [${r}](./${n})${a}`)}t.push(``),y(p(k,`README.md`),t.join(`
+`),`utf-8`)}return{path:E,mode:O,steps:R,outDir:O===`generate`?k:void 0,totalDurationMs:Date.now()-T}}export{w as onboard};

package/packages/tools/dist/scope-map.d.ts

@@ -1,6 +1,6 @@
-import { IEmbedder } from "@kb/embeddings";
-import { IKnowledgeStore } from "@kb/store";
-import { ContentType, KnowledgeOrigin } from "@kb/core";
+import { ContentType, KnowledgeOrigin } from "../../core/dist/index.js";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IKnowledgeStore } from "../../store/dist/index.js";
 
 //#region packages/tools/src/scope-map.d.ts
 interface ScopeMapOptions {

package/packages/tools/dist/stratum-card.d.ts

@@ -1,5 +1,5 @@
 import { FileCache } from "./file-cache.js";
-import { IEmbedder } from "@kb/embeddings";
+import { IEmbedder } from "../../embeddings/dist/index.js";
 
 //#region packages/tools/src/stratum-card.d.ts
 interface StratumCardOptions {

package/packages/tools/dist/symbol.d.ts

@@ -1,5 +1,5 @@
-import { IEmbedder } from "@kb/embeddings";
-import { IGraphStore, IKnowledgeStore } from "@kb/store";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IGraphStore, IKnowledgeStore } from "../../store/dist/index.js";
 
 //#region packages/tools/src/symbol.d.ts
 interface SymbolGraphContext {

package/packages/tools/dist/trace.d.ts

@@ -1,5 +1,5 @@
-import { IEmbedder } from "@kb/embeddings";
-import { IKnowledgeStore } from "@kb/store";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+import { IKnowledgeStore } from "../../store/dist/index.js";
 
 //#region packages/tools/src/trace.d.ts
 interface TraceOptions {

package/packages/tui/dist/App.d.ts

@@ -1,5 +1,5 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
-import { t as IKBClient } from "./types-VcTHNV6s.js";
+import { t as IKBClient } from "./index-Cvx1a7S7.js";
 import React from "react";
 
 //#region packages/tui/src/App.d.ts

package/packages/tui/dist/hooks/useKBClient.d.ts

@@ -1,9 +1,9 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
-import { t as IKBClient } from "../types-VcTHNV6s.js";
-import * as react from "react";
+import { t as IKBClient } from "../index-Cvx1a7S7.js";
+import * as _$react from "react";
 
 //#region packages/tui/src/hooks/useKBClient.d.ts
-declare const KBClientProvider: react.Provider<IKBClient | null>;
+declare const KBClientProvider: _$react.Provider<IKBClient | null>;
 declare function useKBClient(): IKBClient;
 //#endregion
 export { KBClientProvider, useKBClient };

package/packages/tui/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
-import { t as IKBClient } from "./types-VcTHNV6s.js";
+import { t as IKBClient } from "./index-Cvx1a7S7.js";
 
 //#region packages/tui/src/index.d.ts
 declare function launch(client: IKBClient): void;

package/scaffold/README.md

@@ -0,0 +1,192 @@
+# Scaffold System — Contributor Guide
+
+> **⚠️ GOLDEN RULE: Never edit files in `scaffold/general/` or `scaffold/claude-code/` directly.**
+> They are **generated output** and will be overwritten by `generate.mjs`.
+> Always edit the **source files** in `scaffold/definitions/`.
+
+## Architecture
+
+```
+scaffold/
+├── definitions/          ← SOURCE OF TRUTH (edit here)
+│   ├── agents.mjs        Agent metadata (name, description, model, tools, category)
+│   ├── bodies.mjs        Agent body text (mode instructions per agent)
+│   ├── models.mjs        Available models per IDE
+│   ├── protocols.mjs     Shared protocol files (_shared/*.md) + templates
+│   ├── tools.mjs         Tool capability → IDE tool mappings
+│   ├── prompts.mjs       Prompt file content
+│   ├── hooks.mjs         Hook definitions
+│   └── plugins.mjs       Plugin definitions
+│
+├── adapters/             ← IDE-specific generators
+│   ├── copilot.mjs       GitHub Copilot adapter (active — generates ~32 files)
+│   └── claude-code.mjs   Claude Code adapter (stub — no output yet)
+│
+├── generate.mjs          ← BUILD SCRIPT (run after any change)
+│
+├── general/              ← GENERATED OUTPUT for Copilot (DO NOT EDIT)
+│   ├── agents/
+│   │   ├── _shared/      Protocol files (from PROTOCOLS in protocols.mjs)
+│   │   ├── templates/    Template files (from TEMPLATES in protocols.mjs)
+│   │   └── *.agent.md    Agent files (from AGENT_BODIES in bodies.mjs)
+│   └── prompts/          Prompt files (from PROMPTS in prompts.mjs)
+│
+└── claude-code/          ← GENERATED OUTPUT for Claude Code (stub, DO NOT EDIT)
+```
+
+### Data Flow
+
+```
+definitions/*.mjs  →  generate.mjs  →  scaffold/general/  →  kb init  →  .github/ (user project)
+    (source)          (build script)    (generated output)    (deploy)     (user workspace)
+```
+
+## How to Make Changes
+
+### Step 1: Edit Source Files
+
+| What you want to change | Edit this file |
+|--------------------------|---------------|
+| An agent's body/instructions | `definitions/bodies.mjs` → `AGENT_BODIES[agentName]` |
+| Shared rules for code agents | `definitions/protocols.mjs` → `PROTOCOLS['code-agent-base']` |
+| Shared rules for researchers | `definitions/protocols.mjs` → `PROTOCOLS['researcher-base']` |
+| Agent metadata (model, tools) | `definitions/agents.mjs` → `AGENTS[agentName]` |
+| Available models | `definitions/models.mjs` |
+| Tool mappings | `definitions/tools.mjs` |
+| Prompt files | `definitions/prompts.mjs` |
+
+### Step 2: Regenerate Output
+
+```bash
+node scaffold/generate.mjs
+```
+
+This will:
+1. Clean `general/agents/` and `general/prompts/` directories
+2. Regenerate all files from definitions via the copilot adapter
+3. Print every file written (expect ~32 files)
+
+To generate for a specific IDE only:
+```bash
+node scaffold/generate.mjs --ide copilot
+node scaffold/generate.mjs --ide claude-code
+```
+
+### Step 3: Verify
+
+```bash
+# Syntax check the source file you edited
+node -c scaffold/definitions/bodies.mjs
+node -c scaffold/definitions/protocols.mjs
+
+# Verify your changes appear in generated output
+# (use grep/Select-String for key phrases)
+grep -r "your key phrase" scaffold/general/agents/
+```
+
+### Step 4: Commit Both Source AND Generated
+
+Always commit the definition source files AND the regenerated output together.
+The generated files are checked into git so `kb init` can deploy them without
+running the generator.
+
+## Source File Details
+
+### bodies.mjs
+
+Contains `AGENT_BODIES` — an object mapping agent names to their body text.
+
+- Most values are **template literal strings** (`` `...` ``)
+- The **Orchestrator** body is a **function** `(agentTable) => string` because it
+  dynamically includes the agent roster table
+- Backticks inside content must be escaped: `` \` ``
+
+```js
+export const AGENT_BODIES = {
+  Orchestrator: (agentTable) => `# Orchestrator\n${agentTable}\n...`,
+  Implementer: `# Implementer\n...`,
+  Debugger:    `# Debugger\n...`,
+  // ...
+};
+```
+
+### protocols.mjs
+
+Contains `PROTOCOLS` and `TEMPLATES` — objects mapping names to markdown content.
+
+- Each `PROTOCOLS` key becomes a file in `_shared/`:
+  - `'code-agent-base'` → `agents/_shared/code-agent-base.md`
+  - `'researcher-base'` → `agents/_shared/researcher-base.md`
+  - `'decision-protocol'` → `agents/_shared/decision-protocol.md`
+  - etc.
+- Each `TEMPLATES` key becomes a file in `templates/`
+- All values are template literals — escape backticks as `` \` ``
+
+**Protocol → Agent mapping:**
+
+| Protocol | Used by |
+|----------|---------|
+| `code-agent-base` | Implementer, Frontend, Refactor, Debugger |
+| `researcher-base` | Researcher-Alpha/Beta/Gamma/Delta |
+| `code-reviewer-base` | Code-Reviewer-Alpha/Beta |
+| `architect-reviewer-base` | Architect-Reviewer-Alpha/Beta |
+| `decision-protocol` | Referenced by Orchestrator workflow |
+| `forge-protocol` | Referenced by code-agent-base |
+
+### agents.mjs
+
+Defines every agent's metadata:
+- `description`, `argumentHint` — displayed in the agent picker
+- `model` — which LLM model to use
+- `tools` — abstract capability list (mapped to IDE-specific tools by the adapter)
+- `category` — orchestration, implementation, diagnostics, research, review, etc.
+- `sharedBase` — for variant agents (e.g., Researcher-Alpha uses `researcher-base`)
+
+## How Users Receive Changes
+
+When users run `kb init`, the scaffold files are deployed to their `.github/` directory.
+
+### First Install (Legacy Path)
+
+`copyDirectoryRecursive()` — copies all scaffold files, **skips existing** files.
+No tracking, no merging.
+
+### Updates (Smart Path)
+
+`smartCopyScaffold()` — manifest-based with `.kb-scaffold.json`:
+
+| File Status | Strategy | Behavior |
+|-------------|----------|----------|
+| `new` (not in manifest, not on disk) | deploy | Copy file, record hash |
+| `new` (not in manifest, exists on disk) | record | Record hash only (preserve user edits) |
+| `outdated` (source hash changed) | `merge-frontmatter` | **Agent files**: update body, union tools, keep user's model choice |
+| `outdated` (source hash changed) | `overwrite` | **Protocol/shared files**: replace entirely |
+| `current` (unchanged) | skip | No action |
+
+The update strategy is determined by `getUpdateStrategy(relPath)` based on the file path.
+
+**Key implication**: When you update an agent body in `bodies.mjs`, existing users will
+get the updated body text while preserving their custom model choice and any extra tools
+they added. Protocol files (`_shared/*.md`) are fully replaced.
+
+## Common Mistakes
+
+| Mistake | Why it's wrong | What to do instead |
+|---------|---------------|-------------------|
+| Editing `.agent.md` in `general/agents/` | Will be overwritten by `generate.mjs` | Edit `bodies.mjs` for agent bodies |
+| Editing `_shared/*.md` in `general/agents/` | Will be overwritten by `generate.mjs` | Edit `protocols.mjs` PROTOCOLS constant |
+| Forgetting to run `generate.mjs` | Generated files will be stale, `kb init` deploys stale files | Always run after editing definitions |
+| Committing only source OR only generated | Source and output will be out of sync | Commit both together |
+| Unescaped backticks in template literals | JS syntax error in definitions | Use `` \` `` inside template literal strings |
+
+## PR Checklist
+
+- [ ] Changes made in `scaffold/definitions/*.mjs` (NOT in generated output)
+- [ ] `node -c scaffold/definitions/<changed-file>.mjs` passes (syntax check)
+- [ ] `node scaffold/generate.mjs` runs without errors
+- [ ] Generated output contains expected changes (verified with grep)
+- [ ] Both source and generated files included in commit
+- [ ] If adding a new agent: entry in `agents.mjs` + body in `bodies.mjs`
+- [ ] If adding a new protocol: entry in `protocols.mjs` + reference in relevant agent bodies
+- [ ] If adding a new file type: check `getUpdateStrategy()` returns correct merge strategy
+- [ ] Consider impact on existing user installations (will merge preserve their customizations?)