@vpxa/aikit 0.1.48 → 0.1.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "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/frontmatter.d.ts

@@ -12,11 +12,31 @@
 interface ParsedFrontmatter {
   /** Raw key-value pairs from YAML frontmatter. */
   fields: Record<string, string>;
+  /** Parsed metadata sub-fields nested under `metadata:`. */
+  metadata: Record<string, string>;
   /** Parsed tools array (from YAML inline array syntax). */
   tools: string[];
   /** Body content after the closing `---`. */
   body: string;
 }
+/**
+ * Structured metadata for SKILL.md files — HeraSpec-inspired.
+ * All fields beyond name/description are optional for backward compatibility.
+ */
+interface SkillFrontmatter {
+  name: string;
+  description: string;
+  category?: 'cross-cutting' | 'domain' | 'project';
+  domain?: string;
+  applicability?: 'always' | 'on-demand';
+  inputs?: string[];
+  outputs?: string[];
+  requires?: string[];
+  relatedSkills?: string[];
+  tools?: string[];
+  model?: string;
+  'argument-hint'?: string;
+}
 /**
  * Parse a markdown file with YAML frontmatter.
  *
@@ -30,6 +50,11 @@ interface ParsedFrontmatter {
  * ```
  */
 declare function parseFrontmatter(content: string): ParsedFrontmatter;
+/**
+ * Parse SKILL.md frontmatter into a typed SkillFrontmatter object.
+ * Uses parseFrontmatter() internally, then maps array fields.
+ */
+declare function parseSkillFrontmatter(content: string): SkillFrontmatter;
 /**
  * Parse a YAML inline array: `[tool1, tool2, tool3]` → string[]
  */
@@ -51,4 +76,4 @@ declare function serializeToolsArray(tools: string[]): string;
  */
 declare function mergeFrontmatter(sourceContent: string, deployedContent: string): string;
 //#endregion
-export { ParsedFrontmatter, mergeFrontmatter, parseFrontmatter, parseToolsArray, serializeToolsArray };
+export { ParsedFrontmatter, SkillFrontmatter, mergeFrontmatter, parseFrontmatter, parseSkillFrontmatter, parseToolsArray, serializeToolsArray };

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

@@ -1,2 +1,2 @@
-function e(e){let n={},r=[],i=e,a=e.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);if(!a)return{fields:n,tools:r,body:i};let o=a[1];i=a[2];for(let e of o.split(/\r?\n/)){let i=e.match(/^(\S+?):\s*(.*)$/);if(!i)continue;let[,a,o]=i;n[a]=o,a===`tools`&&(r=t(o))}return{fields:n,tools:r,body:i}}function t(e){let t=e.trim();if(!t.startsWith(`[`)||!t.endsWith(`]`))return[];let n=t.slice(1,-1).trim();return n?n.split(`,`).map(e=>e.trim()).filter(Boolean):[]}function n(e){return`[${e.join(`, `)}]`}function r(t,r){let i=e(t),a=e(r),o={...i.fields};a.fields.model&&(o.model=a.fields.model);let s=new Set(i.tools),c=a.tools.filter(e=>!s.has(e));o.tools=n([...i.tools,...c]);let l=[`---`],u=[`description`,`argument-hint`,`tools`,`model`],d=new Set;for(let e of u)e in o&&(l.push(`${e}: ${o[e]}`),d.add(e));for(let[e,t]of Object.entries(o))d.has(e)||l.push(`${e}: ${t}`);return l.push(`---`),`${l.join(`
-`)}\n${i.body}`}export{r as mergeFrontmatter,e as parseFrontmatter,t as parseToolsArray,n as serializeToolsArray};
+const e=[`inputs`,`outputs`,`requires`,`relatedSkills`],t=[`model`],n=[`category`,`domain`,`applicability`],r=new Set([`__proto__`,`constructor`,`prototype`]);function i(e,t){return e.metadata[t]??e.fields[t]}function a(e,t){let n=i(e,t);return n?c(n):[]}function o(e){let t=Object.create(null),n=Object.create(null),i=[],a=e,o=e.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);if(!o)return{fields:t,metadata:n,tools:i,body:a};let s=o[1];a=o[2];let l=!1;for(let e of s.split(/\r?\n/)){if(l){if(e.trim()===``)continue;let t=e.match(/^\s{2,}(\S+?):\s*(.*)$/);if(t){let[,e,i]=t;if(r.has(e))continue;n[e]=i;continue}l=!1}let a=e.match(/^(\S+?):\s*(.*)$/);if(!a)continue;let[,o,s]=a;if(o===`metadata`&&s.trim()===``){l=!0;continue}r.has(o)||(t[o]=s,o===`tools`&&(i=c(s)))}return{fields:t,metadata:n,tools:i,body:a}}function s(t){let n=o(t),r={name:n.fields.name??``,description:n.fields.description??``},s=i(n,`category`);s&&(r.category=s);let c=i(n,`domain`);c&&(r.domain=c);let l=i(n,`applicability`);l&&(r.applicability=l),n.fields.model&&(r.model=n.fields.model),n.fields[`argument-hint`]&&(r[`argument-hint`]=n.fields[`argument-hint`]),n.tools.length>0&&(r.tools=n.tools);for(let t of e){let e=a(n,t);e.length>0&&(r[t]=e)}return r}function c(e){let t=e.trim();if(!t.startsWith(`[`)||!t.endsWith(`]`))return[];let n=t.slice(1,-1).trim();return n?n.split(`,`).map(e=>e.trim()).filter(Boolean):[]}function l(e){return`[${e.join(`, `)}]`}function u(r,s){let c=o(r),u=o(s),d={...c.fields},f={...c.metadata};for(let[e,t]of Object.entries(u.metadata))e in f||(f[e]=t);for(let e of t)u.fields[e]&&(d[e]=u.fields[e]);for(let e of n){let t=i(u,e);t&&(f[e]=t)}for(let t of[...n,...e])delete d[t];delete d.metadata;let p=c.tools,m=u.tools,h=new Set(p),g=m.filter(e=>!h.has(e)),_=[...p,...g];_.length>0&&(d.tools=l(_));for(let t of e){let e=a(c,t),n=a(u,t),r=new Set(e),i=n.filter(e=>!r.has(e)),o=[...e,...i];o.length>0?f[t]=l(o):delete f[t]}let v=[`---`],y=[`name`,`description`,`argument-hint`,`tools`,`model`],b=[`category`,`domain`,`applicability`,`inputs`,`outputs`,`requires`,`relatedSkills`],x=new Set;for(let e of y)e in d&&(v.push(`${e}: ${d[e]}`),x.add(e));for(let[e,t]of Object.entries(d))x.has(e)||v.push(`${e}: ${t}`);let S=[],C=new Set;for(let e of b){let t=f[e];t&&(S.push(`  ${e}: ${t}`),C.add(e))}for(let[e,t]of Object.entries(f))!C.has(e)&&t&&S.push(`  ${e}: ${t}`);return S.length>0&&(v.push(`metadata:`),v.push(...S)),v.push(`---`),`${v.join(`
+`)}\n${c.body}`}export{u as mergeFrontmatter,o as parseFrontmatter,s as parseSkillFrontmatter,c as parseToolsArray,l as serializeToolsArray};

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

@@ -44,9 +44,10 @@ declare function writeManifest(manifestPath: string, manifest: ScaffoldManifest)
  * Determine the update strategy for a file based on its relative path.
  *
  * Strategy rules:
- * - `*.agent.md` (not under `_shared/`) → merge-frontmatter
- * - `_shared/*.md`, `templates/*.md` → overwrite
- * - `*.prompt.md`, `SKILL.md`, `README.md` → overwrite
+ * - *.agent.md (not under _shared/) → merge-frontmatter
+ * - SKILL.md (not under _shared/ or templates/) → merge-frontmatter
+ * - _shared/*.md, templates/*.md → overwrite
+ * - *.prompt.md, README.md → overwrite
  * - Everything else → overwrite
  */
 declare function getUpdateStrategy(relativePath: string): UpdateStrategy;

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

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

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

package/scaffold/general/skills/adr-skill/SKILL.md

@@ -2,6 +2,12 @@
 name: adr-skill
 description: Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept/reject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.
 metadata:
+   category: cross-cutting
+   domain: general
+   applicability: on-demand
+   inputs: [decisions, context]
+   outputs: [adr-document]
+   relatedSkills: [c4-architecture]
   internal: true
 ---
 

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

@@ -1,6 +1,13 @@
 ---
 name: aikit
 description: "Use the @vpxa/aikit AI Kit MCP server for codebase search, analysis, and persistent memory. Load this skill when using aikit_search, aikit_remember, aikit_analyze_*, or any aikit_* tool. Covers all 67 MCP tools: search (hybrid/semantic/keyword), code analysis (structure, dependencies, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (auto-populated module/symbol/import graph with traversal), context management (worksets, stash, checkpoints, restore, lanes), code manipulation (rename, codemod, eval), knowledge management (remember/read/update/forget), web access (fetch, search, http), FORGE protocol (ground, classify, evidence map, stratum cards, digest), brainstorming (interactive ideation sessions), presentation (rich dashboards via present tool), onboarding (full codebase analysis in one call), and developer utilities (regex, encode, measure, changelog, schema-validate, snippet, env, time)."
+metadata:
+  category: cross-cutting
+  domain: general
+  applicability: always
+  inputs: [codebase]
+  outputs: [search-results, analysis, knowledge]
+  relatedSkills: [present]
 ---
 
 # @vpxa/aikit — AI Kit

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

@@ -1,6 +1,14 @@
 ---
 name: brainstorming
 description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+metadata:
+  category: cross-cutting
+  domain: general
+  applicability: always
+  inputs: [requirements, user-intent]
+  outputs: [design, decisions]
+  requires: [aikit]
+  relatedSkills: [requirements-clarity]
 argument-hint: "Feature, component, or behavior to design"
 ---
 

package/scaffold/general/skills/c4-architecture/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: c4-architecture
 description: Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include "architecture diagram", "C4 diagram", "system context", "container diagram", "component diagram", "deployment diagram", "document architecture", "visualize architecture".
+metadata:
+  category: cross-cutting
+  domain: general
+  applicability: on-demand
+  inputs: [codebase, architecture]
+  outputs: [diagrams]
+  relatedSkills: [adr-skill]
 ---
 
 # C4 Architecture Documentation

package/scaffold/general/skills/frontend-design/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: frontend-design
 description: "Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection."
+metadata:
+	category: domain
+	domain: frontend
+	applicability: on-demand
+	inputs: [ui-requirements, codebase]
+	outputs: [design-guidance, patterns]
+	relatedSkills: [react]
 ---
 
 # Frontend Design

package/scaffold/general/skills/lesson-learned/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: lesson-learned
 description: "Analyze recent code changes via git history and extract software engineering lessons. Use when the user asks 'what is the lesson here?', 'what can I learn from this?', 'engineering takeaway', 'what did I just learn?', 'reflect on this code', or wants to extract principles from recent work."
+metadata:
+	category: cross-cutting
+	domain: general
+	applicability: on-demand
+	inputs: [git-history, code-changes]
+	outputs: [engineering-lessons]
+	requires: [aikit]
+	relatedSkills: [session-handoff]
 ---
 
 # Lesson Learned

package/scaffold/general/skills/multi-agents-development/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: multi-agents-development
 description: "Comprehensive patterns for orchestrating multiple AI agents in parallel development workflows. Covers task decomposition, parallel dispatch, context crafting, status handling, review pipelines, and recovery."
+metadata:
+  category: cross-cutting
+  domain: general
+  applicability: always
+  inputs: [plan, codebase]
+  outputs: [task-decomposition, dispatch-templates]
+  requires: [aikit]
+  relatedSkills: [session-handoff]
 ---
 
 # Multi-Agent Development

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

@@ -1,6 +1,13 @@
 ---
 name: present
 description: "Use the AI Kit `present` tool to display rich interactive dashboards, charts, timelines, status boards, and data visualizations in the browser or in-chat. Covers all block types, chart types, actions, composition patterns, and MCP Apps templates (list-sort, data-table, picker, flame-graph, form, timeline, kanban, tree, diff-view, dashboard). Load this skill before calling the present tool to ensure professional output."
+metadata:
+  category: cross-cutting
+  domain: general
+  applicability: always
+  inputs: [data, analysis]
+  outputs: [dashboards, charts, reports]
+  requires: [aikit]
 argument-hint: "Content to present — data, analysis results, status report, comparison, or interactive MCP App"
 ---
 

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

@@ -1,6 +1,13 @@
 ---
 name: react
 description: "Comprehensive React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration, and performance optimization."
+metadata:
+  category: domain
+  domain: react
+  applicability: on-demand
+  inputs: [codebase, requirements]
+  outputs: [component-patterns, code]
+  relatedSkills: [typescript, frontend-design]
 ---
 
 # React

package/scaffold/general/skills/requirements-clarity/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: requirements-clarity
 description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.
+metadata:
+   category: cross-cutting
+   domain: general
+   applicability: on-demand
+   inputs: [requirements]
+   outputs: [scored-requirements, clarifications]
+   relatedSkills: [brainstorming]
 ---
 
 # Requirements Clarity Skill

package/scaffold/general/skills/session-handoff/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: session-handoff
 description: "Creates comprehensive handoff documents for seamless AI agent session transfers. Triggered when: (1) user requests handoff/memory/context save, (2) context window approaches capacity, (3) major task milestone completed, (4) work session ending, (5) user says 'save state', 'create handoff', 'I need to pause', 'context is getting full', (6) resuming work with 'load handoff', 'resume from', 'continue where we left off'. Proactively suggests handoffs after substantial work (multiple file edits, complex debugging, architecture decisions). Solves long-running agent context exhaustion by enabling fresh agents to continue with zero ambiguity."
+metadata:
+    category: cross-cutting
+    domain: general
+    applicability: always
+    inputs: [session-state, decisions]
+    outputs: [handoff-document]
+    requires: [aikit]
+    relatedSkills: [lesson-learned]
 ---
 
 # Handoff

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

@@ -1,6 +1,13 @@
 ---
 name: typescript
 description: "Comprehensive TypeScript development patterns — type system performance, compiler configuration, advanced types, type safety, async patterns, module organization, and runtime optimization."
+metadata:
+  category: domain
+  domain: typescript
+  applicability: on-demand
+  inputs: [codebase, requirements]
+  outputs: [type-patterns, code]
+  relatedSkills: [react]
 ---
 
 # TypeScript