@vpxa/aikit 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

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

@@ -1,4 +1,4 @@
-import{FLOW_DIRS as e,MCP_SERVER_ENTRY as t,SERVER_NAME as n,SKILL_NAMES as r,VSCODE_SETTINGS as i}from"./constants.js";import{buildAgentsMd as a,buildCopilotInstructions as o}from"./templates.js";import{smartCopySubdir as s}from"./scaffold.js";import{existsSync as c,mkdirSync as l,readFileSync as u,unlinkSync as d,writeFileSync as f}from"node:fs";import{dirname as p,resolve as m}from"node:path";import{fileURLToPath as h}from"node:url";import{getGlobalDataDir as g,saveRegistry as _}from"../../../../core/dist/index.js";import{homedir as v}from"node:os";function y(){let e=v(),t=process.platform,n=[],r=m(e,`.copilot`),i=m(r,`instructions`),a=m(e,`.claude`),o=m(e,`.cursor`),s=m(e,`.windsurf`);if(t===`win32`){let t=process.env.APPDATA??m(e,`AppData`,`Roaming`);n.push({ide:`VS Code`,configDir:m(t,`Code`,`User`),mcpConfigPath:m(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:m(t,`Code - Insiders`,`User`),mcpConfigPath:m(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:m(t,`VSCodium`,`User`),mcpConfigPath:m(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:m(t,`Cursor`,`User`),mcpConfigPath:m(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:m(t,`Cursor Nightly`,`User`),mcpConfigPath:m(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:m(t,`Windsurf`,`User`),mcpConfigPath:m(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}else if(t===`darwin`){let t=m(e,`Library`,`Application Support`);n.push({ide:`VS Code`,configDir:m(t,`Code`,`User`),mcpConfigPath:m(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:m(t,`Code - Insiders`,`User`),mcpConfigPath:m(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:m(t,`VSCodium`,`User`),mcpConfigPath:m(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:m(t,`Cursor`,`User`),mcpConfigPath:m(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:m(t,`Cursor Nightly`,`User`),mcpConfigPath:m(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:m(t,`Windsurf`,`User`),mcpConfigPath:m(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}else{let t=process.env.XDG_CONFIG_HOME??m(e,`.config`);n.push({ide:`VS Code`,configDir:m(t,`Code`,`User`),mcpConfigPath:m(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:m(t,`Code - Insiders`,`User`),mcpConfigPath:m(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:m(t,`VSCodium`,`User`),mcpConfigPath:m(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:m(t,`Cursor`,`User`),mcpConfigPath:m(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:m(t,`Cursor Nightly`,`User`),mcpConfigPath:m(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:m(t,`Windsurf`,`User`),mcpConfigPath:m(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}return n.push({ide:`Claude Code`,configDir:m(e,`.claude`),mcpConfigPath:m(e,`.claude`,`mcp.json`),globalScaffoldRoot:a,instructionsRoot:null}),n.filter(e=>c(e.configDir))}function b(e,n,r=!1){let{mcpConfigPath:i,configDir:a}=e,o={...t},s={};if(c(i)){try{let e=u(i,`utf-8`);s=JSON.parse(e)}catch{let e=`${i}.bak`;f(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(`  ${e.ide}: ${n} already configured (use --force to update)`);return}}let d=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`,`Windsurf`]).has(e.ide)?`servers`:`mcpServers`,p=s[d]??{};p[n]=o,s[d]=p,l(a,{recursive:!0}),f(i,`${JSON.stringify(s,null,2)}\n`,`utf-8`),console.log(`  ${e.ide}: configured ${n} in ${i}`)}const x=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`]);function S(e,t=!1){if(!x.has(e.ide))return;let n=m(e.configDir,`settings.json`),r={};if(c(n))try{let e=u(n,`utf-8`);r=JSON.parse(e)}catch{console.log(`  ${e.ide}: skipped settings.json (invalid JSON)`);return}let a=!1;for(let[e,n]of Object.entries(i))if(typeof n==`object`&&n){let t=typeof r[e]==`object`&&r[e]!==null?r[e]:{},i={...t,...n};JSON.stringify(i)!==JSON.stringify(t)&&(r[e]=i,a=!0)}else (t||!(e in r))&&(r[e]=n,a=!0);a&&(f(n,`${JSON.stringify(r,null,2)}\n`,`utf-8`),console.log(`  ${e.ide}: updated settings.json`))}function C(t,n,i,u,d=!1){let p=new Set;for(let e of n)e.globalScaffoldRoot&&p.add(e.globalScaffoldRoot);if(p.size===0){console.log(`  No IDEs with global scaffold support detected.`);return}let h=m(t,`scaffold`,`general`);for(let n of p){s(h,n,`agents`,u,d),s(h,n,`prompts`,u,d);let i=0;for(let e of r)c(m(h,`skills`,e))&&(s(h,n,`skills/${e}`,u,d),i++);for(let r of e){let e=m(t,`scaffold`,`flows`,r);c(m(e,`skills`))&&s(e,m(n,`flows`,r),`skills`,u,d)}console.log(`  ${n}: scaffold updated (${i} skills)`)}let g=new Set,_=o(`aikit`,i),v=a(`aikit`,i);for(let e of n){if(!e.globalScaffoldRoot)continue;let t=e.globalScaffoldRoot;if(e.ide===`Claude Code`){let e=m(t,`CLAUDE.md`);f(e,`${_}\n---\n\n${v}`,`utf-8`),g.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=m(n,`copilot-instructions.md`);g.has(r)||(f(r,`---\napplyTo: "**"\n---\n\n${_}\n---\n\n${v}`,`utf-8`),g.add(r))}else if(e.ide===`Cursor`||e.ide===`Cursor Nightly`){let e=m(t,`rules`);l(e,{recursive:!0});let n=m(e,`aikit.mdc`);g.has(n)||(f(n,`${_}\n---\n\n${v}`,`utf-8`),g.add(n))}else if(e.ide===`Windsurf`){let e=m(t,`rules`);l(e,{recursive:!0});let n=m(e,`aikit.md`);g.has(n)||(f(n,`${_}\n---\n\n${v}`,`utf-8`),g.add(n))}}g.size>0&&console.log(`  Instruction files: ${[...g].join(`, `)}`)}function w(e){let t=[];for(let n of e){if(!n.globalScaffoldRoot)continue;let e=n.globalScaffoldRoot;if(n.ide===`VS Code`||n.ide===`VS Code Insiders`||n.ide===`VSCodium`){let r=n.instructionsRoot??e;t.push(m(r,`kb.instructions.md`)),t.push(m(r,`aikit.instructions.md`))}else n.ide===`Cursor`||n.ide===`Cursor Nightly`?t.push(m(e,`rules`,`kb.mdc`)):n.ide===`Windsurf`&&t.push(m(e,`rules`,`kb.md`))}for(let e of t)c(e)&&(d(e),console.log(`  Removed legacy file: ${e}`))}async function T(e){let t=n,r=m(p(h(import.meta.url)),`..`,`..`,`..`,`..`,`..`,`package.json`),i=JSON.parse(u(r,`utf-8`)).version;console.log(`Initializing @vpxa/aikit v${i}...\n`);let a=g();l(a,{recursive:!0}),console.log(`  Global data store: ${a}`),_({version:1,workspaces:{}}),console.log(`  Created registry.json`);let o=y();if(o.length===0)console.log(`
+import{FLOW_DIRS as e,MCP_SERVER_ENTRY as t,SERVER_NAME as n,SKILL_NAMES as r,VSCODE_SETTINGS as i}from"./constants.js";import{buildAgentsMd as a,buildCopilotInstructions as o}from"./templates.js";import{smartCopySubdir as s}from"./scaffold.js";import{existsSync as c,mkdirSync as l,readFileSync as u,unlinkSync as d,writeFileSync as f}from"node:fs";import{dirname as p,resolve as m}from"node:path";import{fileURLToPath as h}from"node:url";import{getGlobalDataDir as g,saveRegistry as _}from"../../../../core/dist/index.js";import{homedir as v}from"node:os";function y(){let e=v(),t=process.platform,n=[],r=m(e,`.copilot`),i=m(r,`instructions`),a=m(e,`.claude`),o=m(e,`.cursor`),s=m(e,`.windsurf`);if(t===`win32`){let t=process.env.APPDATA??m(e,`AppData`,`Roaming`);n.push({ide:`VS Code`,configDir:m(t,`Code`,`User`),mcpConfigPath:m(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:m(t,`Code - Insiders`,`User`),mcpConfigPath:m(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:m(t,`VSCodium`,`User`),mcpConfigPath:m(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:m(t,`Cursor`,`User`),mcpConfigPath:m(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:m(t,`Cursor Nightly`,`User`),mcpConfigPath:m(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:m(t,`Windsurf`,`User`),mcpConfigPath:m(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}else if(t===`darwin`){let t=m(e,`Library`,`Application Support`);n.push({ide:`VS Code`,configDir:m(t,`Code`,`User`),mcpConfigPath:m(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:m(t,`Code - Insiders`,`User`),mcpConfigPath:m(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:m(t,`VSCodium`,`User`),mcpConfigPath:m(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:m(t,`Cursor`,`User`),mcpConfigPath:m(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:m(t,`Cursor Nightly`,`User`),mcpConfigPath:m(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:m(t,`Windsurf`,`User`),mcpConfigPath:m(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}else{let t=process.env.XDG_CONFIG_HOME??m(e,`.config`);n.push({ide:`VS Code`,configDir:m(t,`Code`,`User`),mcpConfigPath:m(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:m(t,`Code - Insiders`,`User`),mcpConfigPath:m(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:m(t,`VSCodium`,`User`),mcpConfigPath:m(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:m(t,`Cursor`,`User`),mcpConfigPath:m(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:m(t,`Cursor Nightly`,`User`),mcpConfigPath:m(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:m(t,`Windsurf`,`User`),mcpConfigPath:m(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}return n.push({ide:`Claude Code`,configDir:m(e,`.claude`),mcpConfigPath:m(e,`.claude`,`mcp.json`),globalScaffoldRoot:a,instructionsRoot:null}),n.push({ide:`Copilot CLI`,configDir:r,mcpConfigPath:m(r,`mcp-config.json`),globalScaffoldRoot:null,instructionsRoot:null}),n.filter(e=>c(e.configDir))}function b(e,n,r=!1){let{mcpConfigPath:i,configDir:a}=e,o={...t},s={};if(c(i)){try{let e=u(i,`utf-8`);s=JSON.parse(e)}catch{let e=`${i}.bak`;f(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(`  ${e.ide}: ${n} already configured (use --force to update)`);return}}let d=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`,`Windsurf`]).has(e.ide)?`servers`:`mcpServers`,p=s[d]??{};e.ide===`Copilot CLI`?p[n]={...o,tools:[`*`]}:p[n]=o,s[d]=p,l(a,{recursive:!0}),f(i,`${JSON.stringify(s,null,2)}\n`,`utf-8`),console.log(`  ${e.ide}: configured ${n} in ${i}`)}const x=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`]);function S(e,t=!1){if(!x.has(e.ide))return;let n=m(e.configDir,`settings.json`),r={};if(c(n))try{let e=u(n,`utf-8`);r=JSON.parse(e)}catch{console.log(`  ${e.ide}: skipped settings.json (invalid JSON)`);return}let a=!1;for(let[e,n]of Object.entries(i))if(typeof n==`object`&&n){let t=typeof r[e]==`object`&&r[e]!==null?r[e]:{},i={...t,...n};JSON.stringify(i)!==JSON.stringify(t)&&(r[e]=i,a=!0)}else (t||!(e in r))&&(r[e]=n,a=!0);a&&(f(n,`${JSON.stringify(r,null,2)}\n`,`utf-8`),console.log(`  ${e.ide}: updated settings.json`))}function C(t,n,i,u,d=!1){let p=new Set;for(let e of n)e.globalScaffoldRoot&&p.add(e.globalScaffoldRoot);if(p.size===0){console.log(`  No IDEs with global scaffold support detected.`);return}let h=m(t,`scaffold`,`general`);for(let n of p){s(h,n,`agents`,u,d),s(h,n,`prompts`,u,d);let i=0;for(let e of r)c(m(h,`skills`,e))&&(s(h,n,`skills/${e}`,u,d),i++);for(let r of e){let e=m(t,`scaffold`,`flows`,r);c(m(e,`skills`))&&s(e,m(n,`flows`,r),`skills`,u,d)}console.log(`  ${n}: scaffold updated (${i} skills)`)}let g=new Set,_=o(`aikit`,i),v=a(`aikit`,i);for(let e of n){if(!e.globalScaffoldRoot)continue;let t=e.globalScaffoldRoot;if(e.ide===`Claude Code`){let e=m(t,`CLAUDE.md`);f(e,`${_}\n---\n\n${v}`,`utf-8`),g.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=m(n,`copilot-instructions.md`);g.has(r)||(f(r,`---\napplyTo: "**"\n---\n\n${_}\n---\n\n${v}`,`utf-8`),g.add(r))}else if(e.ide===`Cursor`||e.ide===`Cursor Nightly`){let e=m(t,`rules`);l(e,{recursive:!0});let n=m(e,`aikit.mdc`);g.has(n)||(f(n,`${_}\n---\n\n${v}`,`utf-8`),g.add(n))}else if(e.ide===`Windsurf`){let e=m(t,`rules`);l(e,{recursive:!0});let n=m(e,`aikit.md`);g.has(n)||(f(n,`${_}\n---\n\n${v}`,`utf-8`),g.add(n))}}g.size>0&&console.log(`  Instruction files: ${[...g].join(`, `)}`)}function w(e){let t=[];for(let n of e){if(!n.globalScaffoldRoot)continue;let e=n.globalScaffoldRoot;if(n.ide===`VS Code`||n.ide===`VS Code Insiders`||n.ide===`VSCodium`){let r=n.instructionsRoot??e;t.push(m(r,`kb.instructions.md`)),t.push(m(r,`aikit.instructions.md`))}else n.ide===`Cursor`||n.ide===`Cursor Nightly`?t.push(m(e,`rules`,`kb.mdc`)):n.ide===`Windsurf`&&t.push(m(e,`rules`,`kb.md`))}for(let e of t)c(e)&&(d(e),console.log(`  Removed legacy file: ${e}`))}async function T(e){let t=n,r=m(p(h(import.meta.url)),`..`,`..`,`..`,`..`,`..`,`package.json`),i=JSON.parse(u(r,`utf-8`)).version;console.log(`Initializing @vpxa/aikit v${i}...\n`);let a=g();l(a,{recursive:!0}),console.log(`  Global data store: ${a}`),_({version:1,workspaces:{}}),console.log(`  Created registry.json`);let o=y();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 n of o)b(n,t,e.force),S(n,e.force)}let s=m(p(h(import.meta.url)),`..`,`..`,`..`,`..`,`..`);console.log(`
   Installing scaffold files:`),C(s,o,t,i,e.force),w(o),console.log(`
 User-level AI Kit installation complete!`),console.log(`

package/packages/server/dist/output-schemas.d.ts

@@ -229,6 +229,7 @@ declare const GitContextOutputSchema: z.ZodObject<{
     hash: z.ZodString;
     message: z.ZodString;
     author: z.ZodString;
+    date: z.ZodString;
   }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const CompactOutputSchema: z.ZodObject<{

package/packages/server/dist/output-schemas.js

@@ -1 +1 @@
-import{z as e}from"zod";const t=e.object({totalRecords:e.number(),totalFiles:e.number(),lastIndexedAt:e.string().nullable(),onboarded:e.boolean(),onboardDir:e.string(),contentTypes:e.record(e.string(),e.number()),wasmAvailable:e.boolean(),graphStats:e.object({nodes:e.number(),edges:e.number()}).nullable(),curatedCount:e.number(),serverVersion:e.string(),scaffoldVersion:e.string().nullable(),workspaceScaffoldVersion:e.string().nullable(),upgradeAvailable:e.boolean()}),n=e.object({entries:e.array(e.object({path:e.string(),title:e.string(),category:e.string(),tags:e.array(e.string()),version:e.number(),preview:e.string()})),totalCount:e.number()}),r=e.object({ok:e.boolean(),checks:e.array(e.object({name:e.string(),ok:e.boolean(),message:e.string().optional()}))}),i=e.object({summary:e.object({totalFiles:e.number(),totalLines:e.number(),totalCodeLines:e.number(),totalFunctions:e.number(),avgComplexity:e.number(),maxComplexity:e.object({value:e.number(),file:e.string()})}),files:e.array(e.object({path:e.string(),lines:e.number(),code:e.number(),complexity:e.number(),functions:e.number()}))}),a=e.object({platform:e.string(),arch:e.string(),nodeVersion:e.string(),cwd:e.string(),cpus:e.number(),memoryFreeGb:e.number(),memoryTotalGb:e.number()}),o=e.object({iso:e.string(),unix:e.number(),timezone:e.string(),formatted:e.string()}),s=e.object({passed:e.boolean(),errorCount:e.number(),warningCount:e.number(),topErrors:e.array(e.string())}),c=e.object({passed:e.boolean(),tsc:s,biome:s}),l=e.object({name:e.string(),definedIn:e.object({path:e.string(),line:e.number(),kind:e.string(),signature:e.string().optional()}).nullable(),importedBy:e.array(e.object({path:e.string(),line:e.number(),importStatement:e.string()})),referencedIn:e.array(e.object({path:e.string(),line:e.number(),context:e.string(),scope:e.string().optional()})),graphContext:e.object({definingModule:e.string().optional(),importedByModules:e.array(e.string()),siblingSymbols:e.array(e.string())}).nullable()}),u=e.object({sourcePath:e.string(),contentType:e.string(),score:e.number(),headingPath:e.string().optional(),startLine:e.number().optional(),endLine:e.number().optional(),origin:e.string().optional(),category:e.string().optional(),tags:e.array(e.string()).optional()}),d=e.object({results:e.array(u),totalResults:e.number(),searchMode:e.string(),query:e.string()}),f=e.object({path:e.string(),line:e.number().optional(),matchType:e.string(),preview:e.string()}),p=e.object({matches:e.array(f),totalMatches:e.number(),pattern:e.string(),truncated:e.boolean()}),m=e.object({path:e.string(),relevance:e.number(),estimatedTokens:e.number(),focusLines:e.array(e.string()).optional()}),h=e.object({files:e.array(m),totalFiles:e.number(),totalEstimatedTokens:e.number(),task:e.string()}),g=e.object({path:e.string(),impact:e.string(),reason:e.string()}),_=e.object({changedFiles:e.array(e.string()),affectedFiles:e.array(g),totalAffected:e.number(),riskLevel:e.string()}),v=e.object({name:e.string(),passed:e.boolean(),message:e.string().optional(),severity:e.string().optional()}),y=e.object({passed:e.boolean(),score:e.number(),checks:e.array(v),summary:e.string()}),b=e.object({id:e.string(),name:e.string(),type:e.string(),sourcePath:e.string().optional()}),x=e.object({fromId:e.string(),toId:e.string(),type:e.string()}),S=e.object({nodes:e.array(b),edges:e.array(x),totalNodes:e.number(),totalEdges:e.number(),query:e.string()}),C=e.object({symbols:e.array(e.object({name:e.string(),path:e.string(),line:e.number().optional(),kind:e.string()})),totalDead:e.number()}),w=e.object({files:e.number(),packages:e.number(),languages:e.record(e.string(),e.number()),tree:e.string()}),T=e.object({path:e.string(),language:e.string(),lines:e.number(),imports:e.number(),exports:e.number(),functions:e.number(),classes:e.number()}),E=e.object({gitRoot:e.string(),branch:e.string(),commitCount:e.number(),hasUncommitted:e.boolean(),recentCommits:e.array(e.object({hash:e.string(),message:e.string(),author:e.string()}))}),D=e.object({originalChars:e.number(),compressedChars:e.number(),ratio:e.number(),segmentsKept:e.number(),segmentsTotal:e.number()});export{w as AnalyzeStructureOutputSchema,y as AuditOutputSchema,_ as BlastRadiusOutputSchema,c as CheckOutputSchema,D as CompactOutputSchema,C as DeadSymbolsOutputSchema,a as EnvOutputSchema,T as FileSummaryOutputSchema,p as FindOutputSchema,E as GitContextOutputSchema,S as GraphOutputSchema,r as HealthOutputSchema,n as ListOutputSchema,i as MeasureOutputSchema,h as ScopeMapOutputSchema,d as SearchOutputSchema,t as StatusOutputSchema,l as SymbolOutputSchema,o as TimeOutputSchema};
+import{z as e}from"zod";const t=e.object({totalRecords:e.number(),totalFiles:e.number(),lastIndexedAt:e.string().nullable(),onboarded:e.boolean(),onboardDir:e.string(),contentTypes:e.record(e.string(),e.number()),wasmAvailable:e.boolean(),graphStats:e.object({nodes:e.number(),edges:e.number()}).nullable(),curatedCount:e.number(),serverVersion:e.string(),scaffoldVersion:e.string().nullable(),workspaceScaffoldVersion:e.string().nullable(),upgradeAvailable:e.boolean()}),n=e.object({entries:e.array(e.object({path:e.string(),title:e.string(),category:e.string(),tags:e.array(e.string()),version:e.number(),preview:e.string()})),totalCount:e.number()}),r=e.object({ok:e.boolean(),checks:e.array(e.object({name:e.string(),ok:e.boolean(),message:e.string().optional()}))}),i=e.object({summary:e.object({totalFiles:e.number(),totalLines:e.number(),totalCodeLines:e.number(),totalFunctions:e.number(),avgComplexity:e.number(),maxComplexity:e.object({value:e.number(),file:e.string()})}),files:e.array(e.object({path:e.string(),lines:e.number(),code:e.number(),complexity:e.number(),functions:e.number()}))}),a=e.object({platform:e.string(),arch:e.string(),nodeVersion:e.string(),cwd:e.string(),cpus:e.number(),memoryFreeGb:e.number(),memoryTotalGb:e.number()}),o=e.object({iso:e.string(),unix:e.number(),timezone:e.string(),formatted:e.string()}),s=e.object({passed:e.boolean(),errorCount:e.number(),warningCount:e.number(),topErrors:e.array(e.string())}),c=e.object({passed:e.boolean(),tsc:s,biome:s}),l=e.object({name:e.string(),definedIn:e.object({path:e.string(),line:e.number(),kind:e.string(),signature:e.string().optional()}).nullable(),importedBy:e.array(e.object({path:e.string(),line:e.number(),importStatement:e.string()})),referencedIn:e.array(e.object({path:e.string(),line:e.number(),context:e.string(),scope:e.string().optional()})),graphContext:e.object({definingModule:e.string().optional(),importedByModules:e.array(e.string()),siblingSymbols:e.array(e.string())}).nullable()}),u=e.object({sourcePath:e.string(),contentType:e.string(),score:e.number(),headingPath:e.string().optional(),startLine:e.number().optional(),endLine:e.number().optional(),origin:e.string().optional(),category:e.string().optional(),tags:e.array(e.string()).optional()}),d=e.object({results:e.array(u),totalResults:e.number(),searchMode:e.string(),query:e.string()}),f=e.object({path:e.string(),line:e.number().optional(),matchType:e.string(),preview:e.string()}),p=e.object({matches:e.array(f),totalMatches:e.number(),pattern:e.string(),truncated:e.boolean()}),m=e.object({path:e.string(),relevance:e.number(),estimatedTokens:e.number(),focusLines:e.array(e.string()).optional()}),h=e.object({files:e.array(m),totalFiles:e.number(),totalEstimatedTokens:e.number(),task:e.string()}),g=e.object({path:e.string(),impact:e.string(),reason:e.string()}),_=e.object({changedFiles:e.array(e.string()),affectedFiles:e.array(g),totalAffected:e.number(),riskLevel:e.string()}),v=e.object({name:e.string(),passed:e.boolean(),message:e.string().optional(),severity:e.string().optional()}),y=e.object({passed:e.boolean(),score:e.number(),checks:e.array(v),summary:e.string()}),b=e.object({id:e.string(),name:e.string(),type:e.string(),sourcePath:e.string().optional()}),x=e.object({fromId:e.string(),toId:e.string(),type:e.string()}),S=e.object({nodes:e.array(b),edges:e.array(x),totalNodes:e.number(),totalEdges:e.number(),query:e.string()}),C=e.object({symbols:e.array(e.object({name:e.string(),path:e.string(),line:e.number().optional(),kind:e.string()})),totalDead:e.number()}),w=e.object({files:e.number(),packages:e.number(),languages:e.record(e.string(),e.number()),tree:e.string()}),T=e.object({path:e.string(),language:e.string(),lines:e.number(),imports:e.number(),exports:e.number(),functions:e.number(),classes:e.number()}),E=e.object({gitRoot:e.string(),branch:e.string(),commitCount:e.number(),hasUncommitted:e.boolean(),recentCommits:e.array(e.object({hash:e.string(),message:e.string(),author:e.string(),date:e.string()}))}),D=e.object({originalChars:e.number(),compressedChars:e.number(),ratio:e.number(),segmentsKept:e.number(),segmentsTotal:e.number()});export{w as AnalyzeStructureOutputSchema,y as AuditOutputSchema,_ as BlastRadiusOutputSchema,c as CheckOutputSchema,D as CompactOutputSchema,C as DeadSymbolsOutputSchema,a as EnvOutputSchema,T as FileSummaryOutputSchema,p as FindOutputSchema,E as GitContextOutputSchema,S as GraphOutputSchema,r as HealthOutputSchema,n as ListOutputSchema,i as MeasureOutputSchema,h as ScopeMapOutputSchema,d as SearchOutputSchema,t as StatusOutputSchema,l as SymbolOutputSchema,o as TimeOutputSchema};

package/packages/server/dist/structured-content-guard.d.ts

@@ -14,8 +14,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  *
  * UPDATE: The SDK uses passthrough-style validation which DOES reject
  * unknown keys on strict schemas.  Instead, we build a "zero-value"
- * object from the registered outputSchema (if available) so it always
- * passes validation.
+ * object from the registered outputSchema (Zod or JSON-Schema) so it
+ * always passes validation.  Zod schemas expose `.shape` and `.type`
+ * differently from JSON-Schema's `.properties` and `.type` — the
+ * `buildZeroValue` function handles both formats.
  */
 /**
  * Wrap `server.registerTool` so that every handler result is guaranteed

package/packages/server/dist/structured-content-guard.js

@@ -1 +1 @@
-function e(e){let n=e.registerTool.bind(e);e.registerTool=(e,r,i)=>r?.outputSchema==null?n(e,r,i):n(e,r,async(e,n)=>{let a=await i(e,n);return a.structuredContent??=t(r.outputSchema),a})}function t(e){if(!e)return{};if(e.anyOf){let n=e.anyOf.find(e=>e.type!==`null`);return n?t(n):null}switch(e.type){case`object`:{let n={};if(e.properties)for(let[r,i]of Object.entries(e.properties))n[r]=t(i);return n}case`array`:return[];case`string`:return``;case`number`:case`integer`:return 0;case`boolean`:return!1;default:return{}}}export{e as installStructuredContentGuard};
+function e(e){let n=e.registerTool.bind(e);e.registerTool=(e,r,i)=>r?.outputSchema==null?n(e,r,i):n(e,r,async(e,n)=>{let a=await i(e,n);return a.structuredContent??=t(r.outputSchema),a})}function t(e){if(!e)return{};if(e.anyOf){let n=e.anyOf.find(e=>e.type!==`null`);return n?t(n):null}switch(e.type){case`object`:{let n={},r=e.properties??e.shape;if(r)for(let[e,i]of Object.entries(r))n[e]=t(i);return n}case`array`:return[];case`string`:return``;case`number`:case`integer`:return 0;case`boolean`:return!1;case`nullable`:return null;case`optional`:return;case`record`:return{};default:return{}}}export{e as installStructuredContentGuard};

package/scaffold/definitions/agents.mjs

@@ -75,6 +75,7 @@ export const AGENTS = {
     toolRole: 'refactor',
     sharedBase: 'code-agent-base',
     category: 'implementation',
+    skills: [['aikit', '**Always** — AI Kit tool signatures, search, analysis']],
   },
 
   // ─── Diagnostics ──────────────────────────────────────────────────────
@@ -115,6 +116,10 @@ export const AGENTS = {
     toolRole: 'documenter',
     sharedBase: null,
     category: 'documentation',
+    skills: [
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['present', 'When presenting documentation previews or architecture visuals to the user'],
+    ],
   },
 
   Explorer: {
@@ -139,9 +144,10 @@ export const AGENTS = {
     sharedBase: 'researcher-base',
     category: 'research',
     skills: [
-      ['`lesson-learned`', 'When analyzing past changes to extract engineering principles'],
-      ['`c4-architecture`', 'When researching system architecture \u2014 produce C4 diagrams'],
-      ['`adr-skill`', 'When the research involves a technical decision \u2014 draft an ADR'],
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['lesson-learned', 'When analyzing past changes to extract engineering principles'],
+      ['c4-architecture', 'When researching system architecture \u2014 produce C4 diagrams'],
+      ['adr-skill', 'When the research involves a technical decision \u2014 draft an ADR'],
     ],
     variants: {
       Alpha: {
@@ -195,9 +201,10 @@ export const AGENTS = {
     sharedBase: 'architect-reviewer-base',
     category: 'review',
     skills: [
-      ['`c4-architecture`', 'When reviewing architectural diagrams or boundary changes'],
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['c4-architecture', 'When reviewing architectural diagrams or boundary changes'],
       [
-        '`adr-skill`',
+        'adr-skill',
         'When the review involves architecture decisions \u2014 reference or create ADRs',
       ],
     ],

package/scaffold/definitions/bodies.mjs

@@ -107,9 +107,10 @@ Batch 2 (after batch 1):
 
 ## Output Rules
 
-- Structured data >3 sentences → \`present({ format: "html" })\`
+- Structured data >3 sentences → \`present({ format: "html" })\` (or \`format: "browser"\` in CLI mode)
 - Charts, tables, dependency graphs → always \`present\`
 - Short confirmations and questions → normal chat
+- **CLI mode:** Always use \`format: "browser"\` — the \`html\` format's UIResource is invisible in terminal environments. The \`browser\` format auto-opens the system browser.
 
 ## Subagent Output Relay
 
@@ -117,7 +118,7 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 **You MUST relay key findings:**
 
 1. After every subagent completes, extract key data from the returned text
-2. If the subagent mentions charts, tables, or visual data → re-present using \`present({ format: "html" })\`
+2. If the subagent mentions charts, tables, or visual data → re-present using \`present({ format: "html" })\` (or \`format: "browser"\` in CLI mode)
 3. If the subagent returns structured findings → summarize and present to user
 4. **Never assume the user saw subagent output** — always relay or re-present
 
@@ -166,6 +167,7 @@ Before every tool call, verify:
 | Skill | When to load |
 |-------|--------------|
 | \`multi-agents-development\` | **Before any delegation** — task decomposition, dispatch templates, review pipeline, recovery patterns |
+| \`present\` | When presenting plans, findings, or visual content to the user — dashboards, tables, charts, timelines |
 | \`brainstorming\` | Before creative/design work (Phase 0) |
 | \`session-handoff\` | Context filling up, session ending, or major milestone |
 | \`lesson-learned\` | After completing work — extract engineering principles |
@@ -232,12 +234,14 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 **You MUST relay key findings:**
 
 1. After every subagent completes, extract key data from the returned text
-2. If the subagent mentions charts, tables, or visual data → re-present using \`present({ format: "html" })\`
+2. If the subagent mentions charts, tables, or visual data → re-present using \`present({ format: "html" })\` (or \`format: "browser"\` in CLI mode)
 3. If the subagent returns structured findings → summarize and present to user
 4. **Never assume the user saw subagent output** — always relay or re-present
 
 **Rule: Every subagent batch completion MUST be followed by a user-visible summary or presentation.**
 
+> **CLI mode:** Always use \`format: "browser"\` instead of \`format: "html"\` — the UIResource is invisible in terminal. The browser format auto-opens the system browser.
+
 ## Output Format
 
 \`\`\`markdown
@@ -273,6 +277,7 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 | Skill | When to load |
 |-------|--------------|
 | \`brainstorming\` | Before planning any new feature, component, or behavior change — use Visual Companion for architecture mockups |
+| \`present\` | When presenting plans, dependency graphs, or complexity estimates to the user |
 | \`requirements-clarity\` | When requirements are vague or complex (>2 days) — score 0-100 before committing to a plan |
 | \`c4-architecture\` | When the plan involves architectural changes — generate C4 diagrams |
 | \`adr-skill\` | When the plan involves non-trivial technical decisions — create executable ADRs |
@@ -456,6 +461,7 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 
 | Skill | When to load |
 |-------|--------------|
+| \`present\` | When presenting documentation previews, API tables, or architecture visuals to the user |
 | \`c4-architecture\` | When documenting system architecture — generate C4 Mermaid diagrams |
 | \`adr-skill\` | When documenting architecture decisions — create or update ADRs |
 | \`typescript\` | When documenting TypeScript APIs — type signatures, JSDoc patterns |`,

package/scaffold/definitions/protocols.mjs

@@ -91,9 +91,11 @@ Your agent file lists domain-specific skills in the **Skills** section. Load the
 
 1. Check if the current task matches a listed skill trigger
 2. If yes → load the skill file before starting implementation
-3. The \`aikit\` skill is **always loaded** — do not re-load it
+3. The following skills are **foundational** — always loaded, do not re-load:
+   - **\`aikit\`** — AI Kit MCP tool reference, search strategies, compression workflows, session protocol. **Required for all tool usage.**
+   - **\`present\`** — Rich content rendering (dashboards, tables, charts, timelines). **Required when producing visual output for the user.**
 
-> If no skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
+> If no additional skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
 
 ---
 
@@ -135,12 +137,32 @@ list()                     // see all stored knowledge entries
 | \`symbol({ name })\` | Find symbol definition + references |
 | \`trace({ symbol, direction })\` | Follow call graph forward/backward |
 | \`compact({ path, query })\` | Read specific section of a file |
-| \`read_file\` | **Only** when you need exact lines for editing |
+| \`read_file\` | **ONLY** when you need exact lines for a pending edit |
 
 ### Step 4: Tool Discovery
 
 If unsure which AI Kit tool to use → run \`guide({ topic: "what you need" })\` for recommendations.
 
+---
+
+## PROHIBITED: Native File Reading Tools
+
+**\`read_file\` / \`read_file_raw\` MUST NOT be used to understand code.** They waste tokens and miss structural information that AI Kit tools provide.
+
+| ❌ NEVER do this | ✅ Do this instead | Why |
+|---|---|---|
+| \`read_file\` to understand a file | \`file_summary({ path })\` | Structure, exports, imports, call edges — **10x fewer tokens** |
+| \`read_file\` to find specific code | \`compact({ path, query })\` | Server-side read + semantic extract — **5-20x reduction** |
+| Multiple \`read_file\` calls | \`digest({ sources })\` | Compresses multiple files into token-budgeted summary |
+| \`grep_search\` / \`textSearch\` | \`search({ query })\` | Hybrid search across all indexed + curated content |
+| \`grep_search\` for a symbol | \`symbol({ name })\` | Definition + references with scope context |
+| Manual code tracing | \`trace({ start, direction })\` | AST call-graph traversal |
+| Line counting / \`wc\` | \`measure({ path })\` | Lines, functions, cognitive complexity |
+| \`fetch_webpage\` | \`web_fetch({ urls })\` | Readability extract + token budget |
+| Web research / browsing | \`web_search({ queries })\` | Structured web results without browser |
+
+**The ONLY acceptable use of \`read_file\`:** Reading exact lines immediately before an edit operation (e.g., to verify the \`old_str\` for a replacement). Even then, use \`file_summary\` first to identify which lines to read.
+
 ## FORGE Protocol (Quality Gate)
 
 **Quick reference:**
@@ -239,10 +261,11 @@ For outdated AI Kit entries → \`update(path, content, reason)\`
 
 ## Context Efficiency
 
-Minimize token usage by choosing the right compression tool:
-- **\`compact({ path, query })\`** — Extract relevant sections from a single file (5-20x token reduction vs full read)
+**NEVER use \`read_file\` to understand code.** Use the AI Kit compression tools:
+- **\`file_summary({ path })\`** — Structure, exports, imports (~50 tokens vs ~1000+ for read_file)
+- **\`compact({ path, query })\`** — Extract relevant sections from a single file (5-20x token reduction)
 - **\`digest({ sources })\`** — Compress 3+ files into a single token-budgeted summary
-- **\`stratum_card({ path })\`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
+- **\`stratum_card({ files, query })\`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
 
 **Session phases** — structure your work to minimize context bloat:
 
@@ -298,12 +321,14 @@ When you need user input or need to explain something before asking:
 | Simple explanation + question | **Elicitation** | Text-only explanation, then ask via elicitation fields |
 | Rich content explanation + question | **\`present\` (mode: html)** + **Elicitation** | Use \`present({ format: "html" })\` for rich visual explanation (tables, charts, diagrams), then use elicitation for user input |
 | Complex visual explanation | **\`present\` (mode: browser)** | Use \`present({ format: "browser" })\` for full HTML dashboard. Confirmation/selection can be handled via browser actions, but for other user input fall back to elicitation |
+| **CLI mode** (any rich content) | **\`present\` (mode: browser)** | In CLI/terminal mode, **always use \`format: "browser"\`**. The \`html\` format's UIResource is invisible in terminal — only markdown fallback text renders. The \`browser\` format auto-opens the system browser. |
 
 **Rules:**
 - **Never dump long tables or complex visuals as plain text** — use \`present\` to render them properly
 - **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
+- **CLI mode override:** When running in terminal (not VS Code chat), always use \`format: "browser"\` for any rich content
 
 ---
 
@@ -422,10 +447,12 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 ## Context Efficiency
 
-- **Prefer \`file_summary\` over \`read_file\`** for understanding structure
-- **Prefer \`compact\` over full reads** when you need specific sections
-- **Use \`digest\`** when synthesizing from 3+ sources
-- **Use \`stratum_card\`** for files you'll reference repeatedly
+- **NEVER use \`read_file\` to understand code** — use AI Kit compression tools instead
+- **\`file_summary\`** for structure (exports, imports, call edges — 10x fewer tokens)
+- **\`compact\`** for specific sections (5-20x token reduction vs read_file)
+- **\`digest\`** when synthesizing from 3+ sources
+- **\`stratum_card\`** for files you'll reference repeatedly
+- **\`read_file\` is ONLY acceptable** when you need exact lines for a pending edit operation
 `,
 
   'code-reviewer-base': `# Code-Reviewer — Shared Base Instructions

package/scaffold/general/agents/Architect-Reviewer-Alpha.agent.md

@@ -17,8 +17,9 @@ You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, test
 
 | Skill | When to load |
 |-------|--------------|
-| `c4-architecture` | When reviewing architectural diagrams or boundary changes |
-| `adr-skill` | When the review involves architecture decisions — reference or create ADRs |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| c4-architecture | When reviewing architectural diagrams or boundary changes |
+| adr-skill | When the review involves architecture decisions — reference or create ADRs |
 
 ## Flows
 

package/scaffold/general/agents/Architect-Reviewer-Beta.agent.md

@@ -17,8 +17,9 @@ You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, test
 
 | Skill | When to load |
 |-------|--------------|
-| `c4-architecture` | When reviewing architectural diagrams or boundary changes |
-| `adr-skill` | When the review involves architecture decisions — reference or create ADRs |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| c4-architecture | When reviewing architectural diagrams or boundary changes |
+| adr-skill | When the review involves architecture decisions — reference or create ADRs |
 
 ## Flows
 

package/scaffold/general/agents/Documenter.agent.md

@@ -49,9 +49,17 @@ You are the **Documenter**, documentation specialist that creates and maintains
 
 | Skill | When to load |
 |-------|--------------|
+| `present` | When presenting documentation previews, API tables, or architecture visuals to the user |
 | `c4-architecture` | When documenting system architecture — generate C4 Mermaid diagrams |
 | `adr-skill` | When documenting architecture decisions — create or update ADRs |
 | `typescript` | When documenting TypeScript APIs — type signatures, JSDoc patterns |
+## Skills (load on demand)
+
+| Skill | When to load |
+|-------|--------------|
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| present | When presenting documentation previews or architecture visuals to the user |
+
 
 ## Flows
 

package/scaffold/general/agents/Orchestrator.agent.md

@@ -124,9 +124,10 @@ Batch 2 (after batch 1):
 
 ## Output Rules
 
-- Structured data >3 sentences → `present({ format: "html" })`
+- Structured data >3 sentences → `present({ format: "html" })` (or `format: "browser"` in CLI mode)
 - Charts, tables, dependency graphs → always `present`
 - Short confirmations and questions → normal chat
+- **CLI mode:** Always use `format: "browser"` — the `html` format's UIResource is invisible in terminal environments. The `browser` format auto-opens the system browser.
 
 ## Subagent Output Relay
 
@@ -134,7 +135,7 @@ When subagents complete, their visual outputs (from `present`) are NOT visible t
 **You MUST relay key findings:**
 
 1. After every subagent completes, extract key data from the returned text
-2. If the subagent mentions charts, tables, or visual data → re-present using `present({ format: "html" })`
+2. If the subagent mentions charts, tables, or visual data → re-present using `present({ format: "html" })` (or `format: "browser"` in CLI mode)
 3. If the subagent returns structured findings → summarize and present to user
 4. **Never assume the user saw subagent output** — always relay or re-present
 
@@ -183,6 +184,7 @@ Before every tool call, verify:
 | Skill | When to load |
 |-------|--------------|
 | `multi-agents-development` | **Before any delegation** — task decomposition, dispatch templates, review pipeline, recovery patterns |
+| `present` | When presenting plans, findings, or visual content to the user — dashboards, tables, charts, timelines |
 | `brainstorming` | Before creative/design work (Phase 0) |
 | `session-handoff` | Context filling up, session ending, or major milestone |
 | `lesson-learned` | After completing work — extract engineering principles |

package/scaffold/general/agents/Planner.agent.md

@@ -44,12 +44,14 @@ When subagents complete, their visual outputs (from `present`) are NOT visible t
 **You MUST relay key findings:**
 
 1. After every subagent completes, extract key data from the returned text
-2. If the subagent mentions charts, tables, or visual data → re-present using `present({ format: "html" })`
+2. If the subagent mentions charts, tables, or visual data → re-present using `present({ format: "html" })` (or `format: "browser"` in CLI mode)
 3. If the subagent returns structured findings → summarize and present to user
 4. **Never assume the user saw subagent output** — always relay or re-present
 
 **Rule: Every subagent batch completion MUST be followed by a user-visible summary or presentation.**
 
+> **CLI mode:** Always use `format: "browser"` instead of `format: "html"` — the UIResource is invisible in terminal. The browser format auto-opens the system browser.
+
 ## Output Format
 
 ```markdown
@@ -85,6 +87,7 @@ When subagents complete, their visual outputs (from `present`) are NOT visible t
 | Skill | When to load |
 |-------|--------------|
 | `brainstorming` | Before planning any new feature, component, or behavior change — use Visual Companion for architecture mockups |
+| `present` | When presenting plans, dependency graphs, or complexity estimates to the user |
 | `requirements-clarity` | When requirements are vague or complex (>2 days) — score 0-100 before committing to a plan |
 | `c4-architecture` | When the plan involves architectural changes — generate C4 diagrams |
 | `adr-skill` | When the plan involves non-trivial technical decisions — create executable ADRs |

package/scaffold/general/agents/Refactor.agent.md

@@ -35,6 +35,12 @@ You are the **Refactor**, code refactoring specialist that improves structure, r
 |-------|--------------|
 | `lesson-learned` | After completing a refactor — extract principles from the before/after diff |
 | `typescript` | When refactoring TypeScript code — type patterns, generics, utility types |
+## Skills (load on demand)
+
+| Skill | When to load |
+|-------|--------------|
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Alpha.agent.md

@@ -15,9 +15,10 @@ You are **Researcher-Alpha**, the primary deep research agent. During multi-mode
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Beta.agent.md

@@ -15,9 +15,10 @@ You are **Researcher-Beta**, a variant of the Researcher agent optimized for **p
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Delta.agent.md

@@ -15,9 +15,10 @@ You are **Researcher-Delta**, a variant of the Researcher agent optimized for **
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Gamma.agent.md

@@ -15,9 +15,10 @@ You are **Researcher-Gamma**, a variant of the Researcher agent optimized for **
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/_shared/code-agent-base.md

@@ -83,9 +83,11 @@ Your agent file lists domain-specific skills in the **Skills** section. Load the
 
 1. Check if the current task matches a listed skill trigger
 2. If yes → load the skill file before starting implementation
-3. The `aikit` skill is **always loaded** — do not re-load it
+3. The following skills are **foundational** — always loaded, do not re-load:
+   - **`aikit`** — AI Kit MCP tool reference, search strategies, compression workflows, session protocol. **Required for all tool usage.**
+   - **`present`** — Rich content rendering (dashboards, tables, charts, timelines). **Required when producing visual output for the user.**
 
-> If no skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
+> If no additional skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
 
 ---
 
@@ -127,12 +129,32 @@ list()                     // see all stored knowledge entries
 | `symbol({ name })` | Find symbol definition + references |
 | `trace({ symbol, direction })` | Follow call graph forward/backward |
 | `compact({ path, query })` | Read specific section of a file |
-| `read_file` | **Only** when you need exact lines for editing |
+| `read_file` | **ONLY** when you need exact lines for a pending edit |
 
 ### Step 4: Tool Discovery
 
 If unsure which AI Kit tool to use → run `guide({ topic: "what you need" })` for recommendations.
 
+---
+
+## PROHIBITED: Native File Reading Tools
+
+**`read_file` / `read_file_raw` MUST NOT be used to understand code.** They waste tokens and miss structural information that AI Kit tools provide.
+
+| ❌ NEVER do this | ✅ Do this instead | Why |
+|---|---|---|
+| `read_file` to understand a file | `file_summary({ path })` | Structure, exports, imports, call edges — **10x fewer tokens** |
+| `read_file` to find specific code | `compact({ path, query })` | Server-side read + semantic extract — **5-20x reduction** |
+| Multiple `read_file` calls | `digest({ sources })` | Compresses multiple files into token-budgeted summary |
+| `grep_search` / `textSearch` | `search({ query })` | Hybrid search across all indexed + curated content |
+| `grep_search` for a symbol | `symbol({ name })` | Definition + references with scope context |
+| Manual code tracing | `trace({ start, direction })` | AST call-graph traversal |
+| Line counting / `wc` | `measure({ path })` | Lines, functions, cognitive complexity |
+| `fetch_webpage` | `web_fetch({ urls })` | Readability extract + token budget |
+| Web research / browsing | `web_search({ queries })` | Structured web results without browser |
+
+**The ONLY acceptable use of `read_file`:** Reading exact lines immediately before an edit operation (e.g., to verify the `old_str` for a replacement). Even then, use `file_summary` first to identify which lines to read.
+
 ## FORGE Protocol (Quality Gate)
 
 **Quick reference:**
@@ -231,10 +253,11 @@ For outdated AI Kit entries → `update(path, content, reason)`
 
 ## Context Efficiency
 
-Minimize token usage by choosing the right compression tool:
-- **`compact({ path, query })`** — Extract relevant sections from a single file (5-20x token reduction vs full read)
+**NEVER use `read_file` to understand code.** Use the AI Kit compression tools:
+- **`file_summary({ path })`** — Structure, exports, imports (~50 tokens vs ~1000+ for read_file)
+- **`compact({ path, query })`** — Extract relevant sections from a single file (5-20x token reduction)
 - **`digest({ sources })`** — Compress 3+ files into a single token-budgeted summary
-- **`stratum_card({ path })`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
+- **`stratum_card({ files, query })`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
 
 **Session phases** — structure your work to minimize context bloat:
 
@@ -290,12 +313,14 @@ When you need user input or need to explain something before asking:
 | Simple explanation + question | **Elicitation** | Text-only explanation, then ask via elicitation fields |
 | Rich content explanation + question | **`present` (mode: html)** + **Elicitation** | Use `present({ format: "html" })` for rich visual explanation (tables, charts, diagrams), then use elicitation for user input |
 | Complex visual explanation | **`present` (mode: browser)** | Use `present({ format: "browser" })` for full HTML dashboard. Confirmation/selection can be handled via browser actions, but for other user input fall back to elicitation |
+| **CLI mode** (any rich content) | **`present` (mode: browser)** | In CLI/terminal mode, **always use `format: "browser"`**. The `html` format's UIResource is invisible in terminal — only markdown fallback text renders. The `browser` format auto-opens the system browser. |
 
 **Rules:**
 - **Never dump long tables or complex visuals as plain text** — use `present` to render them properly
 - **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
+- **CLI mode override:** When running in terminal (not VS Code chat), always use `format: "browser"` for any rich content
 
 ---
 

package/scaffold/general/agents/_shared/researcher-base.md

@@ -94,8 +94,10 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 ## Context Efficiency
 
-- **Prefer `file_summary` over `read_file`** for understanding structure
-- **Prefer `compact` over full reads** when you need specific sections
-- **Use `digest`** when synthesizing from 3+ sources
-- **Use `stratum_card`** for files you'll reference repeatedly
+- **NEVER use `read_file` to understand code** — use AI Kit compression tools instead
+- **`file_summary`** for structure (exports, imports, call edges — 10x fewer tokens)
+- **`compact`** for specific sections (5-20x token reduction vs read_file)
+- **`digest`** when synthesizing from 3+ sources
+- **`stratum_card`** for files you'll reference repeatedly
+- **`read_file` is ONLY acceptable** when you need exact lines for a pending edit operation
 

package/scaffold/general/skills/aikit/SKILL.md

@@ -195,7 +195,7 @@ Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/de
 ### Presentation (1)
 | Tool | CLI | Purpose |
 |------|-----|---------|
-| `present` | — | Rich dashboards, charts, tables, timelines. Use `format: "browser"` then `openBrowserPage` to display |
+| `present` | — | Rich dashboards, charts, tables, timelines. Use `format: "browser"` then `openBrowserPage` to display. **In CLI mode (no VS Code chat), always use `format: "browser"`** — `html` UIResource is invisible in terminal. |
 
 ### Brainstorming (1)
 | Tool | CLI | Purpose |
@@ -278,12 +278,18 @@ install: []
 
 ## CRITICAL: Use AI Kit Tools Instead of Native IDE Tools
 
-AI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **Always prefer AI Kit tools.**
+AI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **You MUST use AI Kit tools instead of native read/search tools.**
+
+### ⛔ PROHIBITED: Native File Reading
+
+**`read_file` / `read_file_raw` MUST NOT be used to understand code.** They waste tokens and miss structural information.
+
+The **ONLY** acceptable use of `read_file`: getting exact lines immediately before an edit (to verify the `old_str` for replacement). Even then, use `file_summary` first to identify which lines to read.
 
 ### Tool Replacement Table
 
-| Instead of... | Use AI Kit Tool | Why |
-|---------------|-------------|-----|
+| ❌ NEVER do this | ✅ Use AI Kit Tool | Why |
+|---|---|---|
 | `read_file` (full file) | `file_summary` | Exports, imports, call edges — **10x fewer tokens** |
 | `read_file` (specific section) | `compact({ path, query })` | Server-side read + extract — **5-20x reduction** |
 | `grep_search` / `textSearch` | `search` | Semantic + keyword hybrid across all indexed content |
@@ -301,11 +307,12 @@ AI Kit tools provide **10x richer output** than native IDE tools — with AST-an
 
 ```
 Need to understand a file?
-├─ Just structure? → file_summary (exports, imports, call edges — ~50 tokens)
-├─ Specific section? → compact({ path: "file.ts", query: "topic" }) — 5-20x reduction
-├─ Multiple files? → digest (multi-source compression — token-budgeted)
-├─ Repeated reference? → stratum_card (T1/T2 card — 10-100x reduction)
-└─ Full file needed? → ONLY as last resort, and compact it after reading
+├─ Just structure?        → file_summary (exports, imports, call edges — ~50 tokens)
+├─ Specific section?      → compact({ path, query }) — 5-20x reduction
+├─ Multiple files?        → digest (multi-source compression — token-budgeted)
+├─ Repeated reference?    → stratum_card (T1/T2 card — 10-100x reduction)
+├─ Need exact lines to EDIT? → read_file (the ONLY acceptable use)
+└─ "I want to read the whole file" → ⛔ STOP. Use file_summary or compact instead.
 ```
 
 ### What AI Kit Tools Return (AST-Enhanced)

package/scaffold/general/skills/present/SKILL.md

@@ -19,9 +19,12 @@ The `present` tool renders structured content as a professional dark-themed dash
 | Need user input back (confirmations, selections, form data) | **`browser`** | Browser supports blocking actions that return data |
 | Rich visual dashboards without interaction | **`html`** | Prefer in-chat when no response is needed |
 | User explicitly asks for browser | **`browser`** | Respect explicit preference |
+| **Running in CLI mode** (no VS Code chat panel) | **`browser`** | `html` UIResource is invisible in CLI — only plain markdown renders. Use `browser` so the system browser opens automatically with full rich visualization. |
 
 **Rule: If no user interaction is needed, use `format: "html"`. If you need user interaction, use `format: "browser"`.**
 
+> **⚠️ CLI Mode Override:** When running in CLI mode (terminal, not VS Code chat), **always use `format: "browser"`** regardless of whether interaction is needed. The `html` format relies on UIResource rendering in VS Code's MCP Apps panel — in CLI, only the markdown fallback text is shown, losing all rich visualizations (charts, tables, dashboards). The `browser` format starts a local HTTP server and auto-opens the system browser after 8 seconds, which works reliably in CLI.
+
 ---
 
 ## Browser Workflow (IMPORTANT — read carefully)
@@ -152,7 +155,7 @@ The dashboard uses a professional dark theme:
 
 ## Best Practices
 
-1. **Use `browser` format** for data-rich content — charts, tables, dashboards
+1. **Use `browser` format** for data-rich content — charts, tables, dashboards. **Always use `browser` in CLI mode** (the `html` UIResource doesn't render in terminal environments).
 2. **Combine block types** — metrics + charts + tables in one page
 3. **Add titles** to every block for clear section headings
 4. **Use actions** when you need user decisions — the tool returns the selection