@vpxa/aikit 0.1.151 → 0.1.152

package/package.json

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

package/scaffold/dist/adapters/_shared.mjs

@@ -8,4 +8,5 @@ function e(e){return e&&e[0].toLowerCase()+e.slice(1)}function t(e){return!e||e.
 `).trimEnd()}function o(e){return[[`Session Start`,e.sessionStart],[`Before Code Change`,e.beforeCodeChange],[`Before Commit`,e.beforeCommit],[`Session End`,e.sessionEnd]].map(([e,t])=>{let n=(t?.actions||[]).map(e=>`- \`${e}\``);return[`### ${e}`,``,...n,``].join(`
 `)}).join(`
 `).trimEnd()}function s(e,t){let n=[];for(let[t,r]of Object.entries(e))if(r.variants)for(let[e,i]of Object.entries(r.variants)){let a=`${t}-${e}`;n.push(`| **${a}** | ${i.description} | ${r.category||`—`} |`)}else n.push(`| **${t}** | ${r.description} | ${r.category||`—`} |`);return`| Agent | Purpose | Category |\n|-------|---------|----------|\n${n.join(`
-`)}`}function c({serverName:e,mcpEntry:t,configKey:n,extraServerFields:r}){let i={...t};return r&&Object.assign(i,r),JSON.stringify({[n]:{[e]:i}},null,2)}export{n as buildAgentPrompt,s as buildAgentTable,o as buildHooksSection,r as buildInlineAgentSection,c as buildMcpConfigJson,i as buildPromptFile,a as buildPromptSections,t as buildSkillsSection,e as lowerFirst};
+`)}`}function c(e){let t=[];for(let[n,r]of Object.entries(e)){if(n===`Orchestrator`)continue;let e=r.compactRole||r.description;if(r.variants){let i=Object.keys(r.variants);t.push(`| **${n}-${i.join(`/`)}** | ${e} |`)}else t.push(`| **${n}** | ${e} |`)}return`| Agent | Role |\n|-------|------|\n${t.join(`
+`)}`}function l({serverName:e,mcpEntry:t,configKey:n,extraServerFields:r}){let i={...t};return r&&Object.assign(i,r),JSON.stringify({[n]:{[e]:i}},null,2)}export{n as buildAgentPrompt,s as buildAgentTable,c as buildCompactAgentTable,o as buildHooksSection,r as buildInlineAgentSection,l as buildMcpConfigJson,i as buildPromptFile,a as buildPromptSections,t as buildSkillsSection,e as lowerFirst};

package/scaffold/dist/adapters/claude-code.mjs

@@ -1,10 +1,10 @@
-import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{HOOKS as n}from"../definitions/hooks.mjs";import{MCP_SERVER_ENTRY as r,SERVER_NAME as i}from"../definitions/mcp.mjs";import{CLAUDE_MODELS as a}from"../definitions/models.mjs";import{PROMPTS as o}from"../definitions/prompts.mjs";import{PROTOCOLS as s}from"../definitions/protocols.mjs";import{AIKIT_TOOLS as c,CLAUDE_CODE_TOOL_MAP as l,IDE_CAPABILITIES as u}from"../definitions/tools.mjs";import{buildAgentTable as d,buildHooksSection as f,buildInlineAgentSection as p,buildMcpConfigJson as m,buildPromptSections as h,buildSkillsSection as g,lowerFirst as _}from"./_shared.mjs";const v=[`## Flows`,``,"This project uses aikit's pluggable flow system. Check flow status with the `flow` MCP tool.","If a flow is active, follow the current step's skill instructions. Advance with `flow({ action: 'step', advance: 'next' })`.","Use `flow({ action: 'list' })` to see available flows and `flow({ action: 'start', name, topic })` to begin one."].join(`
-`),y=[`## Flows`,``,"This project uses aikit's pluggable flow system. Check flow status with the `flow` MCP tool.","If a flow is active, follow the current step's skill instructions. Advance with `flow({ action: 'step', advance: 'next' })`.","Use `flow({ action: 'list' })` to see available flows and `flow({ action: 'start', name, topic })` to begin one."].join(`
-`),b=[`## Flows`,``,"This project uses aikit's pluggable flow system. Use `flow({ action: 'status' })` to check if a flow is active.",`If dispatched as part of a flow, your work contributes to the current step. Do NOT advance or manage the flow — the Orchestrator handles flow lifecycle.`].join(`
-`);function x(e){return e.replace(/([a-z0-9])([A-Z])/g,`$1-$2`).replace(/[^a-zA-Z0-9]+/g,`-`).replace(/^-+|-+$/g,``).toLowerCase()}function S(e){return`"${String(e).replace(/\\/g,`\\\\`).replace(/"/g,`\\"`)}"`}function C(e){let t=(u[e]||[]).flatMap(e=>l[e]||[]),n=c.map(e=>`mcp__aikit__${e}`);return[...new Set([...t,...n])].sort((e,t)=>e.localeCompare(t))}function w(e,t){let n=[];return n.push(`# aikit ${e}`),n.push(``),t.description&&(n.push(`> ${t.description}`),n.push(``)),n.push(t.content.trim()),n.push(``),n.join(`
-`)}function T(e,n){let r=t[e];return typeof r==`function`?r(n):r||``}function E(e){let t=[];e.extraBody&&t.push(e.extraBody),e.sharedBase&&s[e.sharedBase]&&t.push(s[e.sharedBase]);for(let n of e.sharedProtocols||[])s[n]&&t.push(s[n]);return t}function D(t){let n=[];for(let[r,i]of Object.entries(e)){let e=T(r,t),a=E(i);if(i.variants){for(let[t,o]of Object.entries(i.variants))n.push(p({name:`${r}-${t}`,title:i.title,description:o.description||i.description,body:e,skills:i.skills,additionalSections:[...a,o.bodyAddendum].filter(Boolean)}));continue}let o=[...a];r===`Orchestrator`&&o.push(v,y),n.push(p({name:r,title:i.title,description:i.description,body:e,skills:i.skills,additionalSections:o}))}return n.join(`
-`)}function O(e,t,n,r){let i=C(t.toolRole),a=E(t),o=g(t.skills),s=e===`Orchestrator`?[v,y]:[b],c=[n,...a,t.bodyAddendum,o,...s].filter(Boolean).join(`
+import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{HOOKS as n}from"../definitions/hooks.mjs";import{MCP_SERVER_ENTRY as r,SERVER_NAME as i}from"../definitions/mcp.mjs";import{CLAUDE_MODELS as a}from"../definitions/models.mjs";import{PROMPTS as o}from"../definitions/prompts.mjs";import{PROTOCOLS as s}from"../definitions/protocols.mjs";import{AIKIT_TOOLS as c,CLAUDE_CODE_TOOL_MAP as l,IDE_CAPABILITIES as u}from"../definitions/tools.mjs";import{buildAgentTable as d,buildCompactAgentTable as f,buildHooksSection as p,buildInlineAgentSection as m,buildMcpConfigJson as h,buildPromptSections as g,buildSkillsSection as _,lowerFirst as v}from"./_shared.mjs";const y=[`## Flows`,``,"This project uses aikit's pluggable flow system. Check flow status with the `flow` MCP tool.","If a flow is active, follow the current step's skill instructions. Advance with `flow({ action: 'step', advance: 'next' })`.","Use `flow({ action: 'list' })` to see available flows and `flow({ action: 'start', name, topic })` to begin one."].join(`
+`),b=[`## Flows`,``,"This project uses aikit's pluggable flow system. Check flow status with the `flow` MCP tool.","If a flow is active, follow the current step's skill instructions. Advance with `flow({ action: 'step', advance: 'next' })`.","Use `flow({ action: 'list' })` to see available flows and `flow({ action: 'start', name, topic })` to begin one."].join(`
+`),x=[`## Flows`,``,"This project uses aikit's pluggable flow system. Use `flow({ action: 'status' })` to check if a flow is active.",`If dispatched as part of a flow, your work contributes to the current step. Do NOT advance or manage the flow — the Orchestrator handles flow lifecycle.`].join(`
+`);function S(e){return e.replace(/([a-z0-9])([A-Z])/g,`$1-$2`).replace(/[^a-zA-Z0-9]+/g,`-`).replace(/^-+|-+$/g,``).toLowerCase()}function C(e){return`"${String(e).replace(/\\/g,`\\\\`).replace(/"/g,`\\"`)}"`}function w(e){let t=(u[e]||[]).flatMap(e=>l[e]||[]),n=c.map(e=>`mcp__aikit__${e}`);return[...new Set([...t,...n])].sort((e,t)=>e.localeCompare(t))}function T(e,t){let n=[];return n.push(`# aikit ${e}`),n.push(``),t.description&&(n.push(`> ${t.description}`),n.push(``)),n.push(t.content.trim()),n.push(``),n.join(`
+`)}function E(e,n){let r=t[e];return typeof r==`function`?r(n):r||``}function D(e){let t=[];e.extraBody&&t.push(e.extraBody),e.sharedBase&&s[e.sharedBase]&&t.push(s[e.sharedBase]);for(let n of e.sharedProtocols||[])s[n]&&t.push(s[n]);return t}function O(t){let n=[];for(let[r,i]of Object.entries(e)){let e=E(r,t),a=D(i);if(i.variants){for(let[t,o]of Object.entries(i.variants))n.push(m({name:`${r}-${t}`,title:i.title,description:o.description||i.description,body:e,skills:i.skills,additionalSections:[...a,o.bodyAddendum].filter(Boolean)}));continue}let o=[...a];r===`Orchestrator`&&o.push(y,b),n.push(m({name:r,title:i.title,description:i.description,body:e,skills:i.skills,additionalSections:o}))}return n.join(`
+`)}function k(e,t,n,r){let i=w(t.toolRole),a=D(t),o=_(t.skills),s=e===`Orchestrator`?[y,b]:[x],c=[n,...a,t.bodyAddendum,o,...s].filter(Boolean).join(`
 
-`).trim(),l=t.identity?`You are the **${e}**${t.identity}`:`You are the **${e}**, ${_(t.description)}.`,u=[`---`,`name: ${x(e)}`,`description: ${S(t.description)}`,`allowedTools:`,...i.map(e=>`  - ${e}`),`---`,``,`# ${e} - ${t.title||e}`,``,l];return c&&u.push(``,c),u.push(``),u.join(`
-`)}function k(t=d(e,a)){return[`# aikit — Claude Code Instructions`,``,"This project uses an MCP server (`aikit`) providing tools for search, analysis, memory, and validation.",``,`## MCP Server`,``,"Server name: `aikit`","Configured in `.mcp.json` (already done if scaffold was deployed).",``,`## Agents`,``,t,``,`## Agent Instructions`,``,D(t),`## Prompts`,``,h(o),``,`## Session Protocol`,``,f(n),``].join(`
-`)}function A(){let t=[],n=d(e,a);t.push({path:`.mcp.json`,content:`${m({serverName:i,mcpEntry:r,configKey:`mcpServers`})}\n`}),t.push({path:`CLAUDE.md`,content:k(n)});for(let[e,n]of Object.entries(o))t.push({path:`.claude/commands/aikit-${e}.md`,content:w(e,n)});for(let[r,i]of Object.entries(e)){let e=T(r,n);if(i.variants){for(let[a,o]of Object.entries(i.variants)){let s=`${r}-${a}`;t.push({path:`.claude/agents/${s}.md`,content:O(s,{...i,description:o.description||i.description,identity:o.identity,bodyAddendum:o.bodyAddendum},e,n)})}continue}t.push({path:`.claude/agents/${r}.md`,content:O(r,i,e,n)})}return t}export{v as CLAUDE_FLOWS_SECTION,y as CLAUDE_ORCHESTRATOR_FLOW_ROUTING_SECTION,A as generateClaudeCode};
+`).trim(),l=t.identity?`You are the **${e}**${t.identity}`:`You are the **${e}**, ${v(t.description)}.`,u=[`---`,`name: ${S(e)}`,`description: ${C(t.description)}`,`allowedTools:`,...i.map(e=>`  - ${e}`),`---`,``,`# ${e} - ${t.title||e}`,``,l];return c&&u.push(``,c),u.push(``),u.join(`
+`)}function A(t=d(e,a),r=f(e)){return[`# aikit — Claude Code Instructions`,``,"This project uses an MCP server (`aikit`) providing tools for search, analysis, memory, and validation.",``,`## MCP Server`,``,"Server name: `aikit`","Configured in `.mcp.json` (already done if scaffold was deployed).",``,`## Agents`,``,t,``,`## Agent Instructions`,``,O(r),`## Prompts`,``,g(o),``,`## Session Protocol`,``,p(n),``].join(`
+`)}function j(){let t=[],n=d(e,a),s=f(e);t.push({path:`.mcp.json`,content:`${h({serverName:i,mcpEntry:r,configKey:`mcpServers`})}\n`}),t.push({path:`CLAUDE.md`,content:A(n,s)});for(let[e,n]of Object.entries(o))t.push({path:`.claude/commands/aikit-${e}.md`,content:T(e,n)});for(let[r,i]of Object.entries(e)){let e=E(r,s);if(i.variants){for(let[a,o]of Object.entries(i.variants)){let s=`${r}-${a}`;t.push({path:`.claude/agents/${s}.md`,content:k(s,{...i,description:o.description||i.description,identity:o.identity,bodyAddendum:o.bodyAddendum},e,n)})}continue}t.push({path:`.claude/agents/${r}.md`,content:k(r,i,e,n)})}return t}export{y as CLAUDE_FLOWS_SECTION,b as CLAUDE_ORCHESTRATOR_FLOW_ROUTING_SECTION,j as generateClaudeCode};

package/scaffold/dist/adapters/codex.mjs

@@ -1,3 +1,3 @@
-import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{HOOKS as n}from"../definitions/hooks.mjs";import{MCP_SERVER_ENTRY as r,SERVER_NAME as i}from"../definitions/mcp.mjs";import{PROMPTS as a}from"../definitions/prompts.mjs";import{PROTOCOLS as o}from"../definitions/protocols.mjs";import{buildAgentTable as s,buildHooksSection as c,buildInlineAgentSection as l,buildPromptSections as u}from"./_shared.mjs";function d(e,t){let n=t.args.map(e=>JSON.stringify(e)).join(`, `);return`[mcp_servers.${e}]\ncommand = ${JSON.stringify(t.command)}\nargs = [${n}]\n`}function f(e,n){let r=t[e];return typeof r==`function`?r(n):r||``}function p(e){let t=[];e.extraBody&&t.push(e.extraBody),e.sharedBase&&o[e.sharedBase]&&t.push(o[e.sharedBase]);for(let n of e.sharedProtocols||[])o[n]&&t.push(o[n]);return t}function m(t){let n=[];for(let[r,i]of Object.entries(e)){let e=f(r,t),a=p(i);if(i.variants){for(let[t,o]of Object.entries(i.variants))n.push(l({name:`${r}-${t}`,title:i.title,description:o.description||i.description,body:e,skills:i.skills,additionalSections:[...a,o.bodyAddendum].filter(Boolean)}));continue}n.push(l({name:r,title:i.title,description:i.description,body:e,skills:i.skills,additionalSections:a}))}return n.join(`
-`)}function h(){let t=s(e);return[`# aikit — Codex CLI Instructions`,``,"This project uses an MCP server (`aikit`) providing tools for search, analysis, memory, and validation.",``,`## MCP Server`,``,"Server name: `aikit`",``,`## Agents`,``,t,``,`## Agent Instructions`,``,m(t),`## Prompts`,``,u(a),``,`## Session Protocol`,``,c(n),``].join(`
-`)}function g(){return[{path:`.codex/config.toml`,content:d(i,r)},{path:`codex.md`,content:h()}]}export{g as generateCodex};
+import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{HOOKS as n}from"../definitions/hooks.mjs";import{MCP_SERVER_ENTRY as r,SERVER_NAME as i}from"../definitions/mcp.mjs";import{PROMPTS as a}from"../definitions/prompts.mjs";import{PROTOCOLS as o}from"../definitions/protocols.mjs";import{buildAgentTable as s,buildCompactAgentTable as c,buildHooksSection as l,buildInlineAgentSection as u,buildPromptSections as d}from"./_shared.mjs";function f(e,t){let n=t.args.map(e=>JSON.stringify(e)).join(`, `);return`[mcp_servers.${e}]\ncommand = ${JSON.stringify(t.command)}\nargs = [${n}]\n`}function p(e,n){let r=t[e];return typeof r==`function`?r(n):r||``}function m(e){let t=[];e.extraBody&&t.push(e.extraBody),e.sharedBase&&o[e.sharedBase]&&t.push(o[e.sharedBase]);for(let n of e.sharedProtocols||[])o[n]&&t.push(o[n]);return t}function h(t){let n=[];for(let[r,i]of Object.entries(e)){let e=p(r,t),a=m(i);if(i.variants){for(let[t,o]of Object.entries(i.variants))n.push(u({name:`${r}-${t}`,title:i.title,description:o.description||i.description,body:e,skills:i.skills,additionalSections:[...a,o.bodyAddendum].filter(Boolean)}));continue}n.push(u({name:r,title:i.title,description:i.description,body:e,skills:i.skills,additionalSections:a}))}return n.join(`
+`)}function g(){return[`# aikit — Codex CLI Instructions`,``,"This project uses an MCP server (`aikit`) providing tools for search, analysis, memory, and validation.",``,`## MCP Server`,``,"Server name: `aikit`",``,`## Agents`,``,s(e),``,`## Agent Instructions`,``,h(c(e)),`## Prompts`,``,d(a),``,`## Session Protocol`,``,l(n),``].join(`
+`)}function _(){return[{path:`.codex/config.toml`,content:f(i,r)},{path:`codex.md`,content:g()}]}export{_ as generateCodex};

package/scaffold/dist/adapters/copilot.mjs

@@ -1,46 +1,46 @@
-import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{COPILOT_MODELS as n,VARIANT_GROUPS as r}from"../definitions/models.mjs";import{PROMPTS as i}from"../definitions/prompts.mjs";import{PROTOCOLS as a,TEMPLATES as o}from"../definitions/protocols.mjs";import{IDE_CAPABILITIES as s}from"../definitions/tools.mjs";const c={terminal:`execute/runInTerminal`,problems:`read/problems`,readFile:`read/readFile`,lastCommand:`read/terminalLastCommand`,subagent:`agent/runSubagent`,createFile:`edit/createFile`,editFiles:`edit/editFiles`,rename:`edit/rename`,createDirectory:`edit/createDirectory`,search:`search/changes, search/codebase, search/usages`,web:`web/fetch, web/githubRepo`,todo:`todo`,memory:`vscode/memory`,newWorkspace:`vscode/newWorkspace`,reviewPlan:`vscode/reviewPlan`,askQuestions:`vscode/askQuestions`,resolveMemoryFileUri:`vscode/resolveMemoryFileUri`,runCommand:`vscode/runCommand`,switchAgent:`vscode/switchAgent`,killTerminal:`execute/killTerminal`,createTask:`execute/createAndRunTask`,terminalSel:`read/terminalSelection`,fileSearch:`search/fileSearch`,listDir:`search/listDirectory`,textSearch:`search/textSearch`,searchSubagent:`search/searchSubagent`};function l(e){return`[${[...(s[e]||[]).map(e=>c[e]).filter(Boolean),`aikit/*`].join(`, `)}]`}function u(e){let t=n[e];return t?Array.isArray(t)?t[0]||`Auto (copilot)`:t:`Auto (copilot)`}const d=[`## Flows`,``,"This project uses aikit's pluggable flow system. Check flow status with the `flow` MCP tool.","If a flow is active, follow the current step's skill instructions. Advance with `flow({ action: 'step', advance: 'next' })`.","Use `flow({ action: 'list' })` to see available flows and `flow({ action: 'start', name, topic })` to begin one."].join(`
-`),f=[`## Flows`,``,"This project uses aikit's pluggable flow system. Use `flow({ action: 'status' })` to check if a flow is active.",`If dispatched as part of a flow, your work contributes to the current step. Do NOT advance or manage the flow — the Orchestrator handles flow lifecycle.`].join(`
-`);function p(){let t=[];for(let[i,a]of Object.entries(e))if(a.variants)for(let e of r[i]||[]){let r=`${i}-${e}`,o=n[r]||n[i],s=Array.isArray(o)?o[0]:o||`Unknown`,c=(a.variants[e]||{}).description||a.description;t.push(`| **${r}** | ${c} | ${s} | ${a.category} |`)}else{let e=n[i],r=Array.isArray(e)?e[0]:e||`Unknown`;t.push(`| **${i}** | ${a.description} | ${r} | ${a.category} |`)}return`| Agent | Purpose | Model | Category |\n|-------|---------|-------|----------|\n${t.join(`
-`)}`}function m(e,t,n){let i=`${e}-${t}`,o=n.variants[t]||{},s=u(i),c=o.description||n.description,d=o.identity||(t===r[e]?.[0]?`, the primary ${e} agent.`:`, a variant of ${e}. Same responsibilities, different model perspective.`),p=n.sharedBase&&a[n.sharedBase]?`\n\n${a[n.sharedBase]}`:``,m=n.extraBody?`\n\n${n.extraBody}`:``,h=o.bodyAddendum?`\n\n${o.bodyAddendum}`:``,g=n.skills?.length?`\n\n## Skills (load on demand)\n\n| Skill | When to load |\n|-------|--------------|\n${n.skills.map(([e,t])=>`| ${e} | ${t} |`).join(`
+import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{COPILOT_MODELS as n,VARIANT_GROUPS as r}from"../definitions/models.mjs";import{PROMPTS as i}from"../definitions/prompts.mjs";import{PROTOCOLS as a,TEMPLATES as o}from"../definitions/protocols.mjs";import{IDE_CAPABILITIES as s}from"../definitions/tools.mjs";import{buildCompactAgentTable as c}from"./_shared.mjs";const l={terminal:`execute/runInTerminal`,problems:`read/problems`,readFile:`read/readFile`,lastCommand:`read/terminalLastCommand`,subagent:`agent/runSubagent`,createFile:`edit/createFile`,editFiles:`edit/editFiles`,rename:`edit/rename`,createDirectory:`edit/createDirectory`,search:`search/changes, search/codebase, search/usages`,web:`web/fetch, web/githubRepo`,todo:`todo`,memory:`vscode/memory`,newWorkspace:`vscode/newWorkspace`,reviewPlan:`vscode/reviewPlan`,askQuestions:`vscode/askQuestions`,resolveMemoryFileUri:`vscode/resolveMemoryFileUri`,runCommand:`vscode/runCommand`,switchAgent:`vscode/switchAgent`,killTerminal:`execute/killTerminal`,createTask:`execute/createAndRunTask`,terminalSel:`read/terminalSelection`,fileSearch:`search/fileSearch`,listDir:`search/listDirectory`,textSearch:`search/textSearch`,searchSubagent:`search/searchSubagent`};function u(e){return`[${[...(s[e]||[]).map(e=>l[e]).filter(Boolean),`aikit/*`].join(`, `)}]`}function d(e){let t=n[e];return t?Array.isArray(t)?t[0]||`Auto (copilot)`:t:`Auto (copilot)`}const f=[`## Flows`,``,"This project uses aikit's pluggable flow system. Check flow status with the `flow` MCP tool.","If a flow is active, follow the current step's skill instructions. Advance with `flow({ action: 'step', advance: 'next' })`.","Use `flow({ action: 'list' })` to see available flows and `flow({ action: 'start', name, topic })` to begin one."].join(`
+`),p=[`## Flows`,``,"This project uses aikit's pluggable flow system. Use `flow({ action: 'status' })` to check if a flow is active.",`If dispatched as part of a flow, your work contributes to the current step. Do NOT advance or manage the flow — the Orchestrator handles flow lifecycle.`].join(`
+`);function m(){let t=[];for(let[i,a]of Object.entries(e))if(a.variants)for(let e of r[i]||[]){let r=`${i}-${e}`,o=n[r]||n[i],s=Array.isArray(o)?o[0]:o||`Unknown`,c=(a.variants[e]||{}).description||a.description;t.push(`| **${r}** | ${c} | ${s} | ${a.category} |`)}else{let e=n[i],r=Array.isArray(e)?e[0]:e||`Unknown`;t.push(`| **${i}** | ${a.description} | ${r} | ${a.category} |`)}return`| Agent | Purpose | Model | Category |\n|-------|---------|-------|----------|\n${t.join(`
+`)}`}function h(e,t,n){let i=`${e}-${t}`,o=n.variants[t]||{},s=d(i),c=o.description||n.description,l=o.identity||(t===r[e]?.[0]?`, the primary ${e} agent.`:`, a variant of ${e}. Same responsibilities, different model perspective.`),f=n.sharedBase&&a[n.sharedBase]?`\n\n${a[n.sharedBase]}`:``,m=n.extraBody?`\n\n${n.extraBody}`:``,h=o.bodyAddendum?`\n\n${o.bodyAddendum}`:``,g=n.skills?.length?`\n\n## Skills (load on demand)\n\n| Skill | When to load |\n|-------|--------------|\n${n.skills.map(([e,t])=>`| ${e} | ${t} |`).join(`
 `)}`:``,_=n.title||e;return`---
 description: '${c}'
-${n.argumentHint?`argument-hint: "${n.argumentHint}"\n`:``}tools: ${l(n.toolRole)}
+${n.argumentHint?`argument-hint: "${n.argumentHint}"\n`:``}tools: ${u(n.toolRole)}
 model: ${s}
 ---
 
 # ${i} - ${_}
 
-You are **${i}**${d}${m}
-${p}${h}${g}
+You are **${i}**${l}${m}
+${f}${h}${g}
 
-${f}
-`}function h(e,n){let r=u(e),i=typeof t[e]==`function`?t[e](p()):t[e]||``,o=n.sharedBase&&a[n.sharedBase]?`\n\n${a[n.sharedBase]}`:``,s=(n.sharedProtocols||[]).map(e=>a[e]?`\n\n${a[e]}`:``).join(``),c=n.title||e,m=n.skills?.length?`\n## Skills (load on demand)\n\n| Skill | When to load |\n|-------|--------------|\n${n.skills.map(([e,t])=>`| ${e} | ${t} |`).join(`
+${p}
+`}function g(n,r){let i=d(n),o=typeof t[n]==`function`?t[n](c(e)):t[n]||``,s=r.sharedBase&&a[r.sharedBase]?`\n\n${a[r.sharedBase]}`:``,l=(r.sharedProtocols||[]).map(e=>a[e]?`\n\n${a[e]}`:``).join(``),m=r.title||n,h=r.skills?.length?`\n## Skills (load on demand)\n\n| Skill | When to load |\n|-------|--------------|\n${r.skills.map(([e,t])=>`| ${e} | ${t} |`).join(`
 `)}\n`:``;return`---
-description: '${n.description}'
-${n.argumentHint?`argument-hint: "${n.argumentHint}"\n`:``}tools: ${l(n.toolRole)}
-model: ${r}
+description: '${r.description}'
+${r.argumentHint?`argument-hint: "${r.argumentHint}"\n`:``}tools: ${u(r.toolRole)}
+model: ${i}
 ---
 
-# ${e} - ${c}
+# ${n} - ${m}
 
-You are the **${e}**, ${n.description.toLowerCase().replace(/^./,e=>e.toLowerCase())}
+You are the **${n}**, ${r.description.toLowerCase().replace(/^./,e=>e.toLowerCase())}
 
-${i}${o}${s}${m}
+${o}${s}${l}${h}
 
-${e===`Orchestrator`?d:f}
-`}function g(e,t){return`---
+${n===`Orchestrator`?f:p}
+`}function _(e,t){return`---
 description: "${t.description}"
 agent: "${t.agent}"
 ---
 
 ${t.content}
-`}function _(){return`# Agents
+`}function v(){return`# Agents
 
 This directory contains AI agent definitions generated by \`@vpxa/aikit init\`.
 
 ## Agent Roster
 
-${p()}
+${m()}
 
 ## Multi-Model Pattern
 
@@ -73,4 +73,4 @@ To regenerate after changing models or agent definitions:
 cd knowledge-base
 node scaffold/generate.mjs
 \`\`\`
-`}function v(){let t=[];for(let[n,i]of Object.entries(e))if(i.variants)for(let e of r[n]||[])t.push({path:`agents/${n}-${e}.agent.md`,content:m(n,e,i)});else t.push({path:`agents/${n}.agent.md`,content:h(n,i)});for(let[e,n]of Object.entries(a))t.push({path:`agents/_shared/${e}.md`,content:`${n}\n`});for(let[e,n]of Object.entries(o))t.push({path:`agents/templates/${e}.md`,content:`${n}\n`});t.push({path:`agents/README.md`,content:_()});for(let[e,n]of Object.entries(i))t.push({path:`prompts/aikit-${e}.prompt.md`,content:g(e,n)});return t}export{v as generateCopilot};
+`}function y(){let t=[];for(let[n,i]of Object.entries(e))if(i.variants)for(let e of r[n]||[])t.push({path:`agents/${n}-${e}.agent.md`,content:h(n,e,i)});else t.push({path:`agents/${n}.agent.md`,content:g(n,i)});for(let[e,n]of Object.entries(a))t.push({path:`agents/_shared/${e}.md`,content:`${n}\n`});for(let[e,n]of Object.entries(o))t.push({path:`agents/templates/${e}.md`,content:`${n}\n`});t.push({path:`agents/README.md`,content:v()});for(let[e,n]of Object.entries(i))t.push({path:`prompts/aikit-${e}.prompt.md`,content:_(e,n)});return t}export{y as generateCopilot};

package/scaffold/dist/adapters/gemini.mjs

@@ -1,3 +1,3 @@
-import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{HOOKS as n}from"../definitions/hooks.mjs";import{MCP_SERVER_ENTRY as r,SERVER_NAME as i}from"../definitions/mcp.mjs";import{PROMPTS as a}from"../definitions/prompts.mjs";import{PROTOCOLS as o}from"../definitions/protocols.mjs";import{buildAgentTable as s,buildHooksSection as c,buildInlineAgentSection as l,buildMcpConfigJson as u,buildPromptSections as d}from"./_shared.mjs";function f(e,n){let r=t[e];return typeof r==`function`?r(n):r||``}function p(e){let t=[];e.extraBody&&t.push(e.extraBody),e.sharedBase&&o[e.sharedBase]&&t.push(o[e.sharedBase]);for(let n of e.sharedProtocols||[])o[n]&&t.push(o[n]);return t}function m(t){let n=[];for(let[r,i]of Object.entries(e)){let e=f(r,t),a=p(i);if(i.variants){for(let[t,o]of Object.entries(i.variants))n.push(l({name:`${r}-${t}`,title:i.title,description:o.description||i.description,body:e,skills:i.skills,additionalSections:[...a,o.bodyAddendum].filter(Boolean)}));continue}n.push(l({name:r,title:i.title,description:i.description,body:e,skills:i.skills,additionalSections:a}))}return n.join(`
-`)}function h(){let t=s(e);return[`# aikit — Gemini CLI Instructions`,``,"This project uses an MCP server (`aikit`) providing tools for search, analysis, memory, and validation.",``,`## MCP Server`,``,"Server name: `aikit`","Configure in `.gemini/settings.json` (already done if scaffold was deployed).",``,`## Agents`,``,t,``,`## Agent Instructions`,``,m(t),`## Prompts`,``,d(a),``,`## Session Protocol`,``,c(n),``].join(`
-`)}function g(){return[{path:`.gemini/settings.json`,content:`${u({serverName:i,mcpEntry:r,configKey:`mcpServers`})}\n`},{path:`GEMINI.md`,content:h()}]}export{g as generateGemini};
+import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{HOOKS as n}from"../definitions/hooks.mjs";import{MCP_SERVER_ENTRY as r,SERVER_NAME as i}from"../definitions/mcp.mjs";import{PROMPTS as a}from"../definitions/prompts.mjs";import{PROTOCOLS as o}from"../definitions/protocols.mjs";import{buildAgentTable as s,buildCompactAgentTable as c,buildHooksSection as l,buildInlineAgentSection as u,buildMcpConfigJson as d,buildPromptSections as f}from"./_shared.mjs";function p(e,n){let r=t[e];return typeof r==`function`?r(n):r||``}function m(e){let t=[];e.extraBody&&t.push(e.extraBody),e.sharedBase&&o[e.sharedBase]&&t.push(o[e.sharedBase]);for(let n of e.sharedProtocols||[])o[n]&&t.push(o[n]);return t}function h(t){let n=[];for(let[r,i]of Object.entries(e)){let e=p(r,t),a=m(i);if(i.variants){for(let[t,o]of Object.entries(i.variants))n.push(u({name:`${r}-${t}`,title:i.title,description:o.description||i.description,body:e,skills:i.skills,additionalSections:[...a,o.bodyAddendum].filter(Boolean)}));continue}n.push(u({name:r,title:i.title,description:i.description,body:e,skills:i.skills,additionalSections:a}))}return n.join(`
+`)}function g(){return[`# aikit — Gemini CLI Instructions`,``,"This project uses an MCP server (`aikit`) providing tools for search, analysis, memory, and validation.",``,`## MCP Server`,``,"Server name: `aikit`","Configure in `.gemini/settings.json` (already done if scaffold was deployed).",``,`## Agents`,``,s(e),``,`## Agent Instructions`,``,h(c(e)),`## Prompts`,``,f(a),``,`## Session Protocol`,``,l(n),``].join(`
+`)}function _(){return[{path:`.gemini/settings.json`,content:`${d({serverName:i,mcpEntry:r,configKey:`mcpServers`})}\n`},{path:`GEMINI.md`,content:g()}]}export{_ as generateGemini};

package/scaffold/dist/definitions/agents.mjs

@@ -1,4 +1,4 @@
-const e={Orchestrator:{title:`The Master Conductor`,description:`Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit`,argumentHint:null,toolRole:`orchestrator`,sharedBase:null,sharedProtocols:[`decision-protocol`,`forge-protocol`],category:`orchestration`,skills:[]},Planner:{title:`The Strategic Architect`,description:`Autonomous planner that researches codebases and writes comprehensive TDD implementation plans`,argumentHint:null,toolRole:`planner`,sharedBase:`code-agent-base`,category:`orchestration`},Implementer:{title:`The Code Builder`,description:`Persistent implementation agent that writes code following TDD practices until all tasks are complete`,argumentHint:`Implementation task, feature, or phase from plan`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`]]},Frontend:{title:`The UI Specialist`,description:`UI/UX specialist for React, styling, responsive design, and frontend implementation`,argumentHint:`UI component, styling task, or frontend feature`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`react`,`When building React components — hooks, patterns, Server Components`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`frontend-design`,`When implementing UI/UX — design systems, accessibility, responsive patterns`]]},Refactor:{title:`The Code Sculptor`,description:`Code refactoring specialist that improves structure, readability, and maintainability`,argumentHint:`Code, component, or pattern to refactor`,toolRole:`refactor`,sharedBase:`code-agent-base`,category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`]]},Debugger:{title:`The Problem Solver`,description:`Expert debugger that diagnoses issues, traces errors, and provides solutions using AI Kit traces and compressed context before raw file reads`,argumentHint:`Error message, stack trace, or description of issue`,toolRole:`debugger`,sharedBase:`code-agent-base`,category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`]]},Security:{title:`The Vulnerability Hunter`,description:`Security specialist that analyzes code for vulnerabilities and compliance`,argumentHint:`Code, feature, or component to security review`,toolRole:`security`,sharedBase:`code-agent-base`,category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing code — security patterns, type safety`]]},Documenter:{title:`The Knowledge Keeper`,description:`Documentation specialist that creates and maintains comprehensive project documentation`,argumentHint:`Component, API, feature, or area to document`,toolRole:`documenter`,sharedBase:`code-agent-base`,category:`documentation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`present`,`When presenting documentation previews or architecture visuals to the user`],[`docs`,`When creating or updating project documentation — docs/ convention, architecture blueprints, Diátaxis framework`]]},Explorer:{title:`The Rapid Scout`,description:`Rapid codebase exploration to find files, usages, dependencies, and structural context`,argumentHint:`Find files, usages, and context related to: {topic or goal}`,toolRole:`explorer`,sharedBase:null,category:`exploration`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`]]},Researcher:{title:`The Context Gatherer`,description:`Deep analysis, architecture review, and multi-model decision protocol participant`,argumentHint:`Research question, problem statement, or subsystem to investigate`,toolRole:`researcher`,sharedBase:`researcher-base`,category:`research`,skills:[[`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`]],variants:{Alpha:{description:`Primary deep research agent — also serves as default Researcher`,identity:`, the primary deep research agent. During multi-model decision sessions, you provide deep reasoning and nuanced system design. Your thinking style is **Contrarian** — actively look for flaws, fatal assumptions, and hidden risks in every approach. The best ideas survive adversarial pressure.`,bodyAddendum:`## Required Output Section — \`## Depth Analysis\`
+const e={Orchestrator:{title:`The Master Conductor`,description:`Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit`,argumentHint:null,toolRole:`orchestrator`,sharedBase:null,sharedProtocols:[`decision-protocol`,`forge-protocol`],category:`orchestration`,skills:[]},Planner:{title:`The Strategic Architect`,description:`Autonomous planner that researches codebases and writes comprehensive TDD implementation plans`,compactRole:`TDD implementation plans`,argumentHint:null,toolRole:`planner`,sharedBase:`code-agent-base`,category:`orchestration`},Implementer:{title:`The Code Builder`,description:`Persistent implementation agent that writes code following TDD practices until all tasks are complete`,compactRole:`New features, wire up, build`,argumentHint:`Implementation task, feature, or phase from plan`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`]]},Frontend:{title:`The UI Specialist`,description:`UI/UX specialist for React, styling, responsive design, and frontend implementation`,compactRole:`UI/UX, React, styling, responsive`,argumentHint:`UI component, styling task, or frontend feature`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`react`,`When building React components — hooks, patterns, Server Components`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`frontend-design`,`When implementing UI/UX — design systems, accessibility, responsive patterns`]]},Refactor:{title:`The Code Sculptor`,description:`Code refactoring specialist that improves structure, readability, and maintainability`,compactRole:`Cleanup, simplify, DRY, extract`,argumentHint:`Code, component, or pattern to refactor`,toolRole:`refactor`,sharedBase:`code-agent-base`,category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`]]},Debugger:{title:`The Problem Solver`,description:`Expert debugger that diagnoses issues, traces errors, and provides solutions using AI Kit traces and compressed context before raw file reads`,compactRole:`Bug diagnosis, error tracing`,argumentHint:`Error message, stack trace, or description of issue`,toolRole:`debugger`,sharedBase:`code-agent-base`,category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`]]},Security:{title:`The Vulnerability Hunter`,description:`Security specialist that analyzes code for vulnerabilities and compliance`,compactRole:`Vulnerability analysis, auth hardening`,argumentHint:`Code, feature, or component to security review`,toolRole:`security`,sharedBase:`code-agent-base`,category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing code — security patterns, type safety`]]},Documenter:{title:`The Knowledge Keeper`,description:`Documentation specialist that creates and maintains comprehensive project documentation`,compactRole:`Project documentation`,argumentHint:`Component, API, feature, or area to document`,toolRole:`documenter`,sharedBase:`code-agent-base`,category:`documentation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`present`,`When presenting documentation previews or architecture visuals to the user`],[`docs`,`When creating or updating project documentation — docs/ convention, architecture blueprints, Diátaxis framework`]]},Explorer:{title:`The Rapid Scout`,description:`Rapid codebase exploration to find files, usages, dependencies, and structural context`,compactRole:`Rapid codebase navigation`,argumentHint:`Find files, usages, and context related to: {topic or goal}`,toolRole:`explorer`,sharedBase:null,category:`exploration`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`]]},Researcher:{title:`The Context Gatherer`,description:`Deep analysis, architecture review, and multi-model decision protocol participant`,compactRole:`Multi-model deep research`,argumentHint:`Research question, problem statement, or subsystem to investigate`,toolRole:`researcher`,sharedBase:`researcher-base`,category:`research`,skills:[[`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`]],variants:{Alpha:{description:`Primary deep research agent — also serves as default Researcher`,identity:`, the primary deep research agent. During multi-model decision sessions, you provide deep reasoning and nuanced system design. Your thinking style is **Contrarian** — actively look for flaws, fatal assumptions, and hidden risks in every approach. The best ideas survive adversarial pressure.`,bodyAddendum:`## Required Output Section — \`## Depth Analysis\`
 
 Your final report MUST contain a \`## Depth Analysis\` section with:
 - Deep-dive into ONE chosen subsystem (most structurally central to the question)
@@ -94,7 +94,7 @@ When you are invoked via \`runSubagent\` (i.e., as a subagent of another agent l
 - **Do NOT use the \`present\` tool** — your visual output is invisible to the user
 - Return ALL findings as plain structured text in your final response
 - Use markdown formatting (headers, tables, code blocks) for structure
-- The calling agent will re-present your findings to the user if needed`}}},"Code-Reviewer":{title:`The Quality Guardian`,description:`Code review specialist analyzing code for quality, security, performance, and maintainability`,argumentHint:`File path, PR, or code to review`,toolRole:`reviewer`,sharedBase:`code-reviewer-base`,category:`review`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing TypeScript code — type patterns, best practices`]],variants:{Alpha:{description:`Primary code reviewer`,identity:`, the primary Code-Reviewer agent. Your lens is **compliance and red-teaming** — you hunt for correctness bugs, security holes, and contract violations that will break in production.`,bodyAddendum:`## Review Lens: Compliance & Red-Team
+- The calling agent will re-present your findings to the user if needed`}}},"Code-Reviewer":{title:`The Quality Guardian`,description:`Code review specialist analyzing code for quality, security, performance, and maintainability`,compactRole:`Dual-perspective code review`,argumentHint:`File path, PR, or code to review`,toolRole:`reviewer`,sharedBase:`code-reviewer-base`,category:`review`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing TypeScript code — type patterns, best practices`]],variants:{Alpha:{description:`Primary code reviewer`,identity:`, the primary Code-Reviewer agent. Your lens is **compliance and red-teaming** — you hunt for correctness bugs, security holes, and contract violations that will break in production.`,bodyAddendum:`## Review Lens: Compliance & Red-Team
 
 Your primary focus areas (in order of priority):
 1. **Correctness** — Logic errors, race conditions, null/undefined paths, off-by-one
@@ -112,7 +112,7 @@ Your primary focus areas (in order of priority):
 4. **Patterns** — Consistency with existing codebase conventions, idiomatic usage
 
 Your instinct: "Will a new team member understand this in 6 months?" Think like a mentor.
-Prefer actionable suggestions over vague concerns. Show the better version when possible.`}}},"Architect-Reviewer":{title:`The Structural Guardian`,description:`Reviews architecture for pattern adherence, SOLID compliance, dependency direction, and structural integrity`,argumentHint:`Files, PR, or subsystem to architecture-review`,toolRole:`reviewer`,sharedBase:`architect-reviewer-base`,category:`review`,skills:[[`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`]],extraBody:`You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, testing, security, and code quality. You handle the big picture: service boundaries, dependency direction, pattern adherence, and structural health.`,variants:{Alpha:{description:`Primary architecture reviewer`,identity:`, the primary Architect-Reviewer agent. Your lens is **structural prosecution** — you challenge architectural choices, find boundary violations, and test whether the design survives growth.`,bodyAddendum:`## Review Lens: Structural Prosecutor
+Prefer actionable suggestions over vague concerns. Show the better version when possible.`}}},"Architect-Reviewer":{title:`The Structural Guardian`,description:`Reviews architecture for pattern adherence, SOLID compliance, dependency direction, and structural integrity`,compactRole:`Architecture review`,argumentHint:`Files, PR, or subsystem to architecture-review`,toolRole:`reviewer`,sharedBase:`architect-reviewer-base`,category:`review`,skills:[[`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`]],extraBody:`You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, testing, security, and code quality. You handle the big picture: service boundaries, dependency direction, pattern adherence, and structural health.`,variants:{Alpha:{description:`Primary architecture reviewer`,identity:`, the primary Architect-Reviewer agent. Your lens is **structural prosecution** — you challenge architectural choices, find boundary violations, and test whether the design survives growth.`,bodyAddendum:`## Review Lens: Structural Prosecutor
 
 Your primary focus areas:
 1. **Boundary violations** — Does this cross package/module boundaries it shouldn't?

package/scaffold/dist/definitions/bodies.mjs

@@ -156,12 +156,13 @@ Flows MUST be driven to completion. A flow left active forever blocks future wor
 
 ### Orchestrator Protocols (apply during ALL flow steps)
 
-**PRE-DISPATCH GATE — complete ALL before ANY \`runSubagent\` call:**
-1. ✅ \`multi-agents-development\` skill loaded?
-2. ✅ Task decomposition table produced?
-3. ✅ Independence Check passed per pair?
-4. ✅ Each task ≤ 3 files?
-5. ✅ Parallel batches identified?
+**PRE-DISPATCH GATE:**
+- **Floor:** Skip gate — direct single-agent dispatch
+- **Standard+:** Before ANY \`runSubagent\`:
+   1. Task decomposition table produced?
+   2. Independence Check per pair?
+   3. Each task ≤ 3 files?
+   4. Parallel batches identified?
 
 **Decomposition output format:**
 
@@ -192,56 +193,15 @@ Batch 2 (after batch 1):
 - Enforce delegation rules at all times — Orchestrator never implements code directly
 - Use the subagent prompt template for every dispatch so step-specific flow instructions are grounded in actual code context
 
-**Per-step review cycle:** Dispatch → Code Review (Alpha+Beta) → Arch Review (if boundary changes) → Security (if applicable) → \`evidence_map\` gate → **🛑 STOP — present results**
+**Per-step review cycle (tier-gated):**
+- **Floor:** No review — \`check\` + \`test_run\` only
+- **Standard:** Dispatch → Code Review (Alpha only) → \`evidence_map\` gate → **🛑 STOP**
+- **Critical:** Dispatch → Code Review (Alpha+Beta) → Arch Review → Security → \`evidence_map\` gate → **🛑 STOP**
 Reviewers add findings to the Orchestrator's existing \`evidence_map\` \`task_id\` and do NOT run the gate themselves.
 
-### Flow MCP Tools
+### Multi-Root Workspace
 
-| Tool | Purpose |
-|------|---------|
-| \`flow\` | Manage flows — list, start, navigate steps, read instructions, inspect runs, and add/remove/update. Use the \`action\` parameter. |
-
-### Multi-Root Workspace Support
-
-When the IDE workspace contains **multiple repository roots**, flows support cross-repo orchestration:
-
-**Detection:** \`flow({ action: 'list' })\` and \`flow({ action: 'status' })\` return \`allRoots\` — the list of all workspace roots. When \`allRoots.length > 1\`, the workspace is multi-root.
-
-**Single-repo task (default):** If the workspace has only one root, omit \`roots\`. In multi-root workspaces, **always pass \`roots\`** targeting the specific repo — omitting it creates \`.flows/\` at the workspace root, which is almost never the intended location.
-
-**Multi-repo task:** Pass \`roots\` to \`flow({ action: 'start', ... })\` listing ALL participating repositories:
-\`\`\`
-flow({
-   action: 'start',
-   name: 'aikit:advanced',
-  topic: "cross-repo-auth",
-  roots: ["E:/repos/api-gateway", "E:/repos/auth-service", "E:/repos/shared-types", "E:/repos/frontend"]
-})
-\`\`\`
-This creates \`.flows/cross-repo-auth/\` with synchronized \`meta.json\` in each listed root. Every \`flow\` step/reset action and state change is automatically replicated to all roots.
-
-**Decision criteria for multi-root flows:**
-
-| Signal | Action |
-|--------|--------|
-| Task touches files in 1 repo | Pass that repo as \`roots\` (in multi-root workspaces) |
-| Task touches files in 2+ repos | Pass those repos as \`roots\` |
-| Shared types/contracts change | Include all repos that consume them |
-| Unsure which repos are affected | Use \`blast_radius\` + \`graph\` first, then decide |
-
-**Template variables in step instructions:**
-- \`{{workspace_root}}\` — primary root (first in \`roots\` array)
-- \`{{all_roots}}\` — JSON array of all participating roots
-- \`{{artifacts_path}}\` — primary root's \`.flows/<slug>/.spec/\`
-- \`{{run_dir}}\` — primary root's \`.flows/<slug>/\`
-
-**Subagent dispatch in multi-root:** When dispatching subagents for a multi-root flow, always include the target root in the prompt:
-\`\`\`
-Scope: E:/repos/auth-service/src/auth.ts
-Root: E:/repos/auth-service
-Artifacts: E:/repos/auth-service/.flows/cross-repo-auth/.spec/
-\`\`\`
-Each subagent operates on ONE root. The Orchestrator coordinates across roots via batched dispatch.
+When \`allRoots.length > 1\`: always pass \`roots\` to \`flow start\` targeting specific repo(s). Use \`blast_radius\`/\`graph\` to identify affected roots. Each subagent operates on ONE root — include target root + artifacts path in dispatch prompt. Template vars: \`{{workspace_root}}\`, \`{{all_roots}}\`, \`{{artifacts_path}}\`, \`{{run_dir}}\`.
 
 ## Emergency: STOP → ASSESS → CONTAIN → RECOVER → DOCUMENT
 
@@ -253,51 +213,55 @@ Each subagent operates on ONE root. The Orchestrator coordinates across roots vi
 
 **Tripwires**: 2x files modified → pause. Agent \`BLOCKED\` → diagnose, don't re-delegate unchanged. **Max 2 retries** per task.
 
-## Tool Profiles
+## Context Budget
+
+- **NEVER implement code yourself** — always delegate, no exceptions
+- One-shot delegation preferred for isolated sub-tasks
 
-When dispatching subagents, consider setting a tool profile to reduce their token overhead:
+### Context Gathering for Subagent Prompts
 
-| Dispatch scenario | Recommended profile |
-|-------------------|-------------------|
-| Full implementation | \`full\` (default) |
-| Code review, analysis only | \`safe\` |
-| Research, investigation | \`research\` |
-| Simple fix, single file | \`minimal\` |
-| New agent onboarding | \`discovery\` |
+Default to \`stratum_card({tier:'T1'})\` (~100 tok/file). Upgrade: \`compact\` (~300 tok/file) for semantic need, \`digest\` for multi-file synthesis, \`read_file\` only for exact edit lines.
 
-Include profile in subagent context: "Use tool profile: \`<profile>\`"
+### Between-Phase Compression (MANDATORY)
 
-For maximum token efficiency, instruct subagents to use the **meta-tool discovery pattern**: \`list_tools()\` → \`search_tools({ query })\` → \`describe_tool({ tool_name })\` instead of loading all tool descriptions upfront.
+After each subagent batch returns:
+1. Extract per agent: **status + files + decisions** (2-3 sentences)
+2. \`stash({ key: "batch-N-summary", value: compressed })\`
+3. Next batch sees stash — NOT full subagent output
 
-## Context Budget
+Between phases: \`session_digest({ persist: true, focus: "<topic>" })\`. Carry forward ONLY: decisions, file paths, blockers.
 
-- **NEVER implement code yourself** — always delegate, no exceptions
-- Compress previous phase to **decisions + file paths** before next phase
-- \`digest\` between phases, \`stash\`/\`remember\` analysis results
-- Provide subagents \`scope_map\` + relevant files only — not full history
-- One-shot delegation preferred for isolated sub-tasks
-- Estimate context per subagent: \`stratum_card({tier:'T1'})\` ~100 tokens/file, \`compact\` ~300 tokens/file, \`digest\` for multi-file compression
-- **Receipt consumption:** After \`evidence_map({ action: "gate" })\`, review all receipts. If any claim lacks a tool-verified receipt, add one before declaring YIELD.
+### Subagent Prompt Rules
+
+- Shared context crafted ONCE for parallel dispatch — don't duplicate per-prompt
+- \`scope_map\` + relevant files — never conversation history
+- Tell subagents: "Return ≤ 200 words: status, files, decisions. Full detail only if BLOCKED."
+
+### Validation
+
+- \`check({})\` + \`test_run({})\` ONCE after all batches — never per-batch, never via terminal
+- **Receipt consumption:** After \`evidence_map({ action: "gate" })\`, check all receipts have tool-verified evidence.
 
 ## Output Rules
 
-- Structured data >3 sentences → \`present({ format: "html" })\` (or \`format: "browser"\` in CLI mode)
+- **Terse by default** — status updates, phase transitions, and confirmations in 1-3 sentences. No preamble, no filler.
+- Batch completion summary: bullet list of agent status + files + decisions. NOT prose paragraphs.
+- Structured data >3 rows → \`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
 
-When subagents complete, their visual outputs (from \`present\`) are NOT visible to the user.
-**Prevention:** Always include "Do NOT use the \`present\` tool — return all findings as plain text" in every subagent dispatch prompt, including researcher dispatches for the Multi-Model Decision Protocol.
-**You MUST relay key findings:**
+Subagent \`present\` calls are invisible to user. Always include "Do NOT use \`present\` — return findings as structured text" in every dispatch.
 
-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" })\` (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
+**After each subagent returns:**
+1. Extract: status + files + key decisions (2-3 sentences)
+2. \`stash({ key: "agent-<name>-result", value: compressed })\` — full response exits conversation context
+3. Present COMPRESSED summary to user — never echo verbatim subagent output
+4. If visual data needed → \`present\` the summary, not raw response
 
-**Rule: Every subagent batch completion MUST be followed by a user-visible summary or presentation.**
+**Rule: Every batch completion → user-visible compressed summary. Never echo full subagent responses.**
 
 ## Critical Rules
 
@@ -324,13 +288,10 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 - \`run_in_terminal\` for code generation (sed, echo >>, etc.)
 - \`vscode/switchAgent\` — **NEVER use this to delegate flow work**. Switching agents hands off control and breaks flow orchestration. ALL agent work goes through \`runSubagent\`. \`vscode/switchAgent\` is reserved for explicit user-requested agent switching only.
 
-### Allowed Tools (Orchestrator uses these directly)
-- \`search\`, \`compact\`, \`digest\`, \`file_summary\`, \`scope_map\`, \`symbol\`, \`trace\`, \`graph\`
-- \`present\`, \`remember\`, \`stash\`, \`checkpoint\`, \`restore\`
-- \`check\`, \`test_run\`, \`blast_radius\`, \`reindex\`, \`produce_knowledge\`
-- \`forge_classify\`, \`forge_ground\`, \`evidence_map\`
+### Allowed Tools
 - \`runSubagent\` — your PRIMARY tool for getting work done
-- \`read_file\` — ONLY to gather context for subagent prompts
+- Read/analysis/memory/validation tools — used directly to gather context and verify
+- \`read_file\` — ONLY for exact lines before delegating edits
 
 ### Pre-Action Gate
 Before every tool call, verify:
@@ -341,43 +302,37 @@ Before every tool call, verify:
 
 ## Skills (load on demand)
 
-| 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\` | When ANY flow step (builtin or custom) involves design, brainstorming, or creative work — auto-detected by Orchestrator. Pairs with the Multi-Model Decision Protocol for technical decisions |
-| \`session-handoff\` | Context filling up, session ending, or major milestone |
-| \`lesson-learned\` | After completing work — extract engineering principles |
-| \`docs\` | During \`_docs-sync\` epilogue — living documentation convention, templates, change-to-doc mapping |
-| \`repo-access\` | **IMMEDIATELY** when YOU or any subagent get auth failures from \`web_fetch\`, \`http\`, or git commands (401, 403, 404, SSO redirect, login HTML, "Permission denied"). NEVER declare a repo "inaccessible" without first loading this skill and walking the Strategy Ladder |
-| \`browser-use\` | When \`repo-access\` Strategy Ladder is exhausted and auth requires browser interaction (SAML SSO, OAuth consent, 2FA). Also for web scraping, form filling, UI testing, or any task needing a real browser. Pairs with \`repo-access\` |
+| Skill | Trigger |
+|-------|---------|
+| \`multi-agents-development\` | Before any delegation |
+| \`present\` | Visual content for user |
+| \`brainstorming\` | Design/decision flow steps |
+| \`session-handoff\` | Context pressure > 70% or session end |
+| \`lesson-learned\` | After completing work |
+| \`docs\` | \`_docs-sync\` epilogue |
+| \`repo-access\` | Auth failures (401/403/404/SSO) — ALWAYS walk ladder before declaring inaccessible |
+| \`browser-use\` | After repo-access ladder exhausted, or browser interaction needed |
 
 ## Repo Access — HARD RULE
 
-**If \`web_fetch\` or \`http\` returns 401, 403, 404, SSO redirect, login page HTML, or any auth-like failure for a repository or code URL:**
-1. **STOP** — do NOT declare the repo "inaccessible" or "behind SSO"
-2. **Load the \`repo-access\` skill** and follow its Strategy Ladder
-3. **Walk all 5 steps** before concluding access is impossible
-4. If Strategy Ladder is exhausted and auth requires browser interaction → **load \`browser-use\` skill** for browser-based auth recovery (SAML SSO, OAuth, 2FA flows)
-5. **Include \`repo-access\` and \`browser-use\` in subagent prompts** when delegating tasks that touch the same repo
-
-This applies to YOU (the Orchestrator) when you use \`web_fetch\`/\`http\` directly, not just subagents.
+On ANY auth failure (401/403/404/SSO/login HTML): STOP → load \`repo-access\` skill → walk ALL 5 steps before declaring inaccessible. If exhausted → \`browser-use\`. Include both skills in subagent prompts for affected repos.
 
 **When dispatching subagents**, include relevant skill names in the prompt so subagents know which skills to load (e.g., "Load the \`react\` and \`typescript\` skills for this task").
 
 ## Session Protocol
 
-### Start (do ALL)
+### Start
 
 \`\`\`
-flow({ action: 'status' })                                     # Check/resume active flow FIRST
-# If flow active → flow({ action: 'read', step }) → follow step instructions
-status({})                                                     # Check AI Kit health + onboard state
-# If onboard not run → onboard({ path: "." })                 # First-time codebase analysis
-flow({ action: 'list' })                                       # See available flows
-# Select flow based on task → flow({ action: 'start', name: "<name>", topic: "<task>" })  # Start flow — creates .flows/{topic}/
-knowledge({ action: "list" })                                 # See stored knowledge
+flow({ action: 'status' })                                     # Check for active flow
+\`\`\`
+**If active flow:** \`flow({ action: 'read' })\` → follow step. Skip remaining start steps.
+**If no active flow:**
+\`\`\`
+status({})                                                     # AI Kit health + onboard
+flow({ action: 'list' })                                       # Available flows
 search({ query: "SESSION CHECKPOINT", origin: "curated" })     # Resume prior work
+# Select flow → flow({ action: 'start', name, topic })
 \`\`\`
 
 ### During
@@ -413,7 +368,7 @@ After any \`status()\` call, check the \`contextPressure\` value (0-100):
 This project uses aikit's pluggable flow system. Check flow status with the \`flow\` MCP tool.
 If a flow is active, follow the current step's instructions. Advance with \`flow({ action: 'step', advance: 'next' })\`.
 Use \`flow({ action: 'list' })\` to see available flows and \`flow({ action: 'start', name, topic })\` to begin one.
-`,Planner:`**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
+`,Planner:`**\`AGENTS.md\` is already in your context** — do NOT re-read it. Just load the \`aikit\` skill.
 
 Load the \`aikit\` skill for full tool documentation, workflow chains, and session protocol.
 
@@ -514,62 +469,7 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 | \`adr-skill\` | When the plan involves non-trivial technical decisions — create executable ADRs |
 | \`session-handoff\` | When context window is filling up, planning session ending, or major milestone completed |
 | \`repo-access\` | When the plan involves accessing private, enterprise, or self-hosted repositories |
-| \`browser-use\` | When the plan involves browser-based auth recovery, web scraping, or interacting with web applications that require login |`,Implementer:`**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
-
-Load the \`aikit\` skill for full tool documentation, workflow chains, and session protocol.
-
-## Implementation Protocol
-
-1. **Understand scope** — Read the phase objective, identify target files
-2. **Write test first** (Red) — Create failing tests that define expected behavior
-3. **Implement** (Green) — Write minimal code to make tests pass
-4. **Refactor** — Clean up while keeping tests green
-5. **Validate** — \`check\`, \`test_run\`, \`blast_radius\`
-6. **Persist** — \`remember\` any decisions or patterns discovered
-
-## Rules
-
-- **Test-first always** — No implementation without a failing test
-- **Minimal code** — Don't build what isn't asked for
-- **Follow existing patterns** — Search AI Kit for conventions before creating new ones (\`search("convention")\`, \`knowledge({ action: "list", category: "conventions" })\`)
-- **Never modify tests to make them pass** — Fix the implementation instead
-- **Run \`check\` after every change** — Catch errors early
-- **Loop-break** — If the same test still fails with the same error after 2 retries, STOP. Re-read the error from scratch, check your assumptions with \`trace\` or \`symbol\`, and try a fundamentally different approach. Do not attempt a 3rd retry in the same direction
-- **Think-first for complex tasks** — If a task involves 3+ files or non-obvious logic, outline your approach before writing code. Check existing patterns with \`search\` first. Design, then implement
-
-## Pre-Edit Checklist (before modifying any file)
-
-1. **Understand consumers** — \`graph({action:'find_nodes', name_pattern:'<target>'})\` → \`graph({action:'neighbors', node_id, direction:'incoming'})\`. See who calls/imports before changing a contract.
-2. **Compress, don't raw-read** — \`file_summary\` then \`compact({path, query})\` for the specific area. Only \`read_file\` when you need exact lines for \`replace_string_in_file\`.
-3. **Snapshot risky edits** — \`checkpoint({action:'save', label:'pre-<scope>'})\` before cross-cutting changes. \`checkpoint({action:'restore', ...})\` if \`check\`/\`test_run\` fails.
-4. **Estimate blast radius** — \`blast_radius({changed_files:[...]})\` BEFORE editing when changing a public/shared symbol; re-run AFTER to confirm actual impact matches.
-5. **TDD when tests exist** — write/extend the failing test first, then minimum code to pass.
-
-## Post-Edit Checklist
-
-1. \`check({})\` — typecheck + lint must pass clean
-2. \`test_run({})\` — full suite or targeted pattern
-3. If Orchestrator passed a \`task_id\`: \`evidence_map({action:'add', task_id, claim, status:'V', receipt:'file.ts#Lxx'})\` for each verified contract/acceptance claim. Do NOT run the gate — Orchestrator owns it.
-
-## Structured Output (MANDATORY)
-
-Every implementation response MUST end with a structured status block:
-
-\`\`\`
-## Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
-
-### Files Changed
-- path/to/file.ts — description of change
-
-### Tests
-- path/to/test.ts — N tests added/modified, all passing
-
-### Evidence
-- [claim]: [receipt/verification]
-
-### Blockers (if any)
-- Description of blocker
-\`\`\``,Frontend:"**Read `AGENTS.md`** in the workspace root for project conventions and AI Kit protocol.\n\nLoad the `aikit` skill for full tool documentation, workflow chains, and session protocol.\n\n## Frontend Protocol\n\n0. **Check for DESIGN.md** — Look for `DESIGN.md` in the workspace root or `docs/` directory. If found, read it first — it defines the project's design system, tokens, colors, typography, spacing, and component conventions. Follow it as the authoritative design reference.\n1. **Search AI Kit** for existing component patterns and design tokens\n2. **Write component tests first** — Accessibility, rendering, interaction\n3. **Implement** — Follow existing component patterns, use design system tokens\n4. **Validate** — `check`, `test_run`, visual review\n5. **Persist** — `remember` new component patterns\n\n## Rules\n\n- **Accessibility first** — ARIA attributes, keyboard navigation, screen reader support\n- **Follow design system** — Use existing tokens, don't create one-off values\n- **Responsive by default** — Mobile-first, test all breakpoints\n- **Test-first** — Component tests before implementation\n\n## Frontend Exploration Mode\n\n| Need | Tool |\n|------|------|\n| Component dependency graph | `graph({action:'neighbors', node_id:'src/components/X.tsx', direction:'incoming'})` |\n| Stale / unused components | `dead_symbols({ path:'src/components' })` |\n| React / a11y / library API research | `web_search({ query })`, `web_fetch({ urls })` |\n| Component complexity hotspots | `measure({ path:'src/components' })` |\n| Verify a component's callers | `graph({action:'find_nodes', name_pattern})` → `neighbors` |\n\n## Visual Validation Protocol (post `test_run`)\n\n**Pre-flight (MANDATORY before any browser step):**\n1. Read `package.json` scripts — identify dev command (e.g. `dev`, `start`, `vite`)\n2. Determine default port (check script args, `vite.config.*`, or env)\n3. Check if dev server already running on port (attempt `http({ url:'http://localhost:<port>' })`)\n4. If NOT running, delegate to a helper or use `createAndRunTask` to start `npm run dev`\n   in the background; wait for ready signal\n5. Capture the base URL\n\n**Validation:**\n6. `browser({ action: 'open', url, mode: 'ui' })` — render target component page\n7. `browser({ action: 'screenshot' })` + `browser({ action: 'read' })` — capture visual + DOM\n8. Keyboard-only navigation check: simulate Tab/Enter/Escape via `browser({ action: 'act', kind: 'type' })` —\n   verify focus ring, activation, dismiss\n9. Compare against design tokens / Figma URL if supplied\n10. Fail fast if color contrast < 4.5:1 (WCAG AA) or focus indicator missing\n\nIf the pre-flight dev server cannot be started (e.g. sandbox), fall back to\n`compact` inspection of the component source + describe expected visual behavior.",Debugger:`**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
+| \`browser-use\` | When the plan involves browser-based auth recovery, web scraping, or interacting with web applications that require login |`,Implementer:"**`AGENTS.md` is already in your context** — do NOT re-read it. Just load the `aikit` skill.\n\nLoad the `aikit` skill for full tool documentation, workflow chains, and session protocol.\n\n## Implementation Protocol\n\n1. **Understand scope** — Read the phase objective, identify target files\n2. **Write test first** (Red) — Create failing tests that define expected behavior\n3. **Implement** (Green) — Write minimal code to make tests pass\n4. **Refactor** — Clean up while keeping tests green\n5. **Validate** — `check`, `test_run`, `blast_radius`\n6. **Persist** — `remember` any decisions or patterns discovered\n\n## Rules\n\n- **Test-first always** — No implementation without a failing test\n- **Minimal code** — Don't build what isn't asked for\n- **Follow existing patterns** — Search AI Kit for conventions before creating new ones (`search(\"convention\")`, `knowledge({ action: \"list\", category: \"conventions\" })`)\n- **Never modify tests to make them pass** — Fix the implementation instead\n- **Run `check` after every change** — Catch errors early\n- **Loop-break** — If the same test still fails with the same error after 2 retries, STOP. Re-read the error from scratch, check your assumptions with `trace` or `symbol`, and try a fundamentally different approach. Do not attempt a 3rd retry in the same direction\n- **Think-first for complex tasks** — If a task involves 3+ files or non-obvious logic, outline your approach before writing code. Check existing patterns with `search` first. Design, then implement\n\n## Pre-Edit Checklist (before modifying any file)\n\n1. **Understand consumers** — `graph({action:'find_nodes', name_pattern:'<target>'})` → `graph({action:'neighbors', node_id, direction:'incoming'})`. See who calls/imports before changing a contract.\n2. **Compress, don't raw-read** — `file_summary` then `compact({path, query})` for the specific area. Only `read_file` when you need exact lines for `replace_string_in_file`.\n3. **Snapshot risky edits** — `checkpoint({action:'save', label:'pre-<scope>'})` before cross-cutting changes. `checkpoint({action:'restore', ...})` if `check`/`test_run` fails.\n4. **Estimate blast radius** — `blast_radius({changed_files:[...]})` BEFORE editing when changing a public/shared symbol; re-run AFTER to confirm actual impact matches.\n5. **TDD when tests exist** — write/extend the failing test first, then minimum code to pass.\n\n## Token Efficiency\n\n**Anti-patterns (NEVER do these):**\n- ❌ `read_file` after `compact`/`file_summary` already returned content — redundant\n- ❌ `read_file` in <50 line chunks — read 100+ lines at once\n- ❌ `run_in_terminal` for `grep`/`rg`/`Select-String` — use `search()` or `find()`\n- ❌ `run_in_terminal` for `git diff` — use `get_changed_files` or `blast_radius`\n- ❌ Re-reading `AGENTS.md`, skill files, or instruction files — already in context\n\n**Required patterns:**\n- `file_summary` → identify lines → `read_file`(exact edit range only)\n- `stash({ key: \"analysis-<topic>\", value: ... })` for intermediate results reused across turns\n- One `compact({path, query})` replaces multiple `read_file` calls for understanding\n\n## Post-Edit Checklist\n\n1. `check({})` — typecheck + lint must pass clean\n2. `test_run({})` — full suite or targeted pattern\n3. If Orchestrator passed a `task_id`: `evidence_map({action:'add', task_id, claim, status:'V', receipt:'file.ts#Lxx'})` for each verified contract/acceptance claim. Do NOT run the gate — Orchestrator owns it.\n\n## Structured Output (MANDATORY)\n\nEvery implementation response MUST end with a structured status block:\n\n```\n## Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED\n\n### Files Changed\n- path/to/file.ts — description of change\n\n### Tests\n- path/to/test.ts — N tests added/modified, all passing\n\n### Evidence\n- [claim]: [receipt/verification]\n\n### Blockers (if any)\n- Description of blocker\n```",Frontend:"**`AGENTS.md` is already in your context** — do NOT re-read it. Just load the `aikit` skill.\n\nLoad the `aikit` skill for full tool documentation, workflow chains, and session protocol.\n\n## Frontend Protocol\n\n0. **Check for DESIGN.md** — Look for `DESIGN.md` in the workspace root or `docs/` directory. If found, read it first — it defines the project's design system, tokens, colors, typography, spacing, and component conventions. Follow it as the authoritative design reference.\n1. **Search AI Kit** for existing component patterns and design tokens\n2. **Write component tests first** — Accessibility, rendering, interaction\n3. **Implement** — Follow existing component patterns, use design system tokens\n4. **Validate** — `check`, `test_run`, visual review\n5. **Persist** — `remember` new component patterns\n\n## Rules\n\n- **Accessibility first** — ARIA attributes, keyboard navigation, screen reader support\n- **Follow design system** — Use existing tokens, don't create one-off values\n- **Responsive by default** — Mobile-first, test all breakpoints\n- **Test-first** — Component tests before implementation\n\n## Frontend Exploration Mode\n\n| Need | Tool |\n|------|------|\n| Component dependency graph | `graph({action:'neighbors', node_id:'src/components/X.tsx', direction:'incoming'})` |\n| Stale / unused components | `dead_symbols({ path:'src/components' })` |\n| React / a11y / library API research | `web_search({ query })`, `web_fetch({ urls })` |\n| Component complexity hotspots | `measure({ path:'src/components' })` |\n| Verify a component's callers | `graph({action:'find_nodes', name_pattern})` → `neighbors` |\n\n## Visual Validation Protocol (post `test_run`)\n\n**Pre-flight (MANDATORY before any browser step):**\n1. Read `package.json` scripts — identify dev command (e.g. `dev`, `start`, `vite`)\n2. Determine default port (check script args, `vite.config.*`, or env)\n3. Check if dev server already running on port (attempt `http({ url:'http://localhost:<port>' })`)\n4. If NOT running, delegate to a helper or use `createAndRunTask` to start `npm run dev`\n   in the background; wait for ready signal\n5. Capture the base URL\n\n**Validation:**\n6. `browser({ action: 'open', url, mode: 'ui' })` — render target component page\n7. `browser({ action: 'screenshot' })` + `browser({ action: 'read' })` — capture visual + DOM\n8. Keyboard-only navigation check: simulate Tab/Enter/Escape via `browser({ action: 'act', kind: 'type' })` —\n   verify focus ring, activation, dismiss\n9. Compare against design tokens / Figma URL if supplied\n10. Fail fast if color contrast < 4.5:1 (WCAG AA) or focus indicator missing\n\nIf the pre-flight dev server cannot be started (e.g. sandbox), fall back to\n`compact` inspection of the component source + describe expected visual behavior.",Debugger:`**\`AGENTS.md\` is already in your context** — do NOT re-read it. Just load the \`aikit\` skill.
 
 Load the \`aikit\` skill for full tool documentation, workflow chains, and session protocol.
 
@@ -646,7 +546,7 @@ When debugging tool invocation issues, use the replay audit trail with traceId:
    - Replay log entries (\`.aikit-state/replay.jsonl\`)
    - In-memory telemetry (\`getToolTelemetry()\`)
    - Server middleware context (\`ctx.requestId\`)
-4. Filter by traceId: search replay.jsonl for the specific UUID to trace the full invocation lifecycle`,Refactor:`**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
+4. Filter by traceId: search replay.jsonl for the specific UUID to trace the full invocation lifecycle`,Refactor:`**\`AGENTS.md\` is already in your context** — do NOT re-read it. Just load the \`aikit\` skill.
 
 Load the \`aikit\` skill for full tool documentation, workflow chains, and session protocol.
 
@@ -705,7 +605,7 @@ For multi-approach uncertainty (A vs B), do NOT create lanes. Instead:
 | Skill | When to load |
 |-------|--------------|
 | \`lesson-learned\` | After completing a refactor — extract principles from the before/after diff |
-| \`typescript\` | When refactoring TypeScript code — type patterns, generics, utility types |`,Security:`**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
+| \`typescript\` | When refactoring TypeScript code — type patterns, generics, utility types |`,Security:`**\`AGENTS.md\` is already in your context** — do NOT re-read it. Just load the \`aikit\` skill.
 
 Load the \`aikit\` skill for full tool documentation, workflow chains, and session protocol.
 
@@ -757,7 +657,7 @@ Load the \`aikit\` skill for full tool documentation, workflow chains, and sessi
 
 ### Findings
 1. **[SEVERITY]** Title — Description, file:line, remediation
-\`\`\``,Documenter:`**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
+\`\`\``,Documenter:`**\`AGENTS.md\` is already in your context** — do NOT re-read it. Just load the \`aikit\` skill.
 
 Load the \`aikit\` skill for full tool documentation, workflow chains, and session protocol.
 
@@ -834,4 +734,4 @@ Rules adapted from *The Elements of Agent Style* (CC BY 4.0, Yue Zhao) and class
 | \`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 |`,Explorer:"**Read `AGENTS.md`** in the workspace root for project conventions and AI Kit protocol.\n\nLoad the `aikit` skill for full tool documentation, workflow chains, and session protocol.\n\n## MANDATORY FIRST ACTION\n\n1. Run `status({})` — if onboard shows ❌, run `onboard({ path: \".\" })` and wait for completion\n2. Note the **Onboard Directory** path from status output\n3. **Before exploring**, read relevant onboard artifacts using `compact({ path: \"<dir>/<file>\" })`:\n   - `synthesis-guide.md` — project overview and architecture\n   - `structure.md` — file tree and module purposes\n   - `symbols.md` + `api-surface.md` — exported symbols\n   - `dependencies.md` — import relationships\n   - `code-map.md` — module graph\n4. Only use `find`, `symbol`, `trace`, `graph` for details NOT covered by artifacts\n\n## Flow Context Bootstrap\n\nWhen dispatched as a subagent within an active flow:\n\n1. **Withdraw context first** — before any search or file reads:\n   ```\n   knowledge({ action: 'withdraw', scope: 'flow', profile: 'researcher', budget: 6000 })\n   ```\n   This returns pre-analyzed context from prior agents.\n\n2. **Use returned context** — do NOT re-search or re-read files already covered\n3. **`read_file` ONLY** for exact lines needed for editing\n4. **Deposit new discoveries:**\n   ```\n   knowledge({ action: 'remember', scope: 'flow', title: '<discovery>', content: '<details>', category: 'context' })\n   ```\n\n**Profile:** `researcher`\n\n## Exploration Protocol\n\n1. **AI Kit Recall** — `search` for existing analysis on this area\n2. **Discover** — Use `find`, `symbol`, `scope_map` to locate relevant files\n3. **Analyze** — Use `analyze({ aspect: \"structure\", ... })`, `analyze({ aspect: \"dependencies\", ... })`, `file_summary`\n4. **Compress** — Use `compact` for targeted file sections, `digest` when synthesizing 3+ sources, `stratum_card` for files you'll reference repeatedly\n5. **Map** — Build a picture of the subsystem: files, exports, dependencies, call chains\n6. **Report** — Structured findings with file paths and key observations\n\n## Exploration Modes\n\n| Goal | Tools |\n|------|-------|\n| Find files for a feature | `find`, `scope_map` |\n| Map a symbol's usage | `symbol`, `trace` |\n| Map module relationships | `graph({ action: 'neighbors' })` — import/export edges across packages |\n| Understand a package | `analyze({ aspect: \"structure\", ... })`, `analyze({ aspect: \"dependencies\", ... })`, `file_summary` |\n| Check impact of a change | `blast_radius` |\n\n## Output Format\n\n```markdown\n## Exploration: {topic}\n\n### Files Found\n- path/to/file.ts — purpose, key exports\n\n### Dependencies\n- package A → package B (via import)\n\n### Key Observations\n- Notable patterns, potential issues, architectural notes\n```\n\n## Rules\n\n- **Speed over depth** — Provide a useful map quickly, not an exhaustive analysis\n- **Read-only** — Never create, edit, or delete files\n- **Structured output** — Always return findings in the format above"};export{e as AGENT_BODIES};
+| \`typescript\` | When documenting TypeScript APIs — type signatures, JSDoc patterns |`,Explorer:"**`AGENTS.md` is already in your context** — do NOT re-read it. Just load the `aikit` skill.\n\nLoad the `aikit` skill for full tool documentation, workflow chains, and session protocol.\n\n## MANDATORY FIRST ACTION\n\n1. Run `status({})` — if onboard shows ❌, run `onboard({ path: \".\" })` and wait for completion\n2. Note the **Onboard Directory** path from status output\n3. **Before exploring**, read relevant onboard artifacts using `compact({ path: \"<dir>/<file>\" })`:\n   - `synthesis-guide.md` — project overview and architecture\n   - `structure.md` — file tree and module purposes\n   - `symbols.md` + `api-surface.md` — exported symbols\n   - `dependencies.md` — import relationships\n   - `code-map.md` — module graph\n4. Only use `find`, `symbol`, `trace`, `graph` for details NOT covered by artifacts\n\n## Flow Context Bootstrap\n\nWhen dispatched as a subagent within an active flow:\n\n1. **Withdraw context first** — before any search or file reads:\n   ```\n   knowledge({ action: 'withdraw', scope: 'flow', profile: 'researcher', budget: 6000 })\n   ```\n   This returns pre-analyzed context from prior agents.\n\n2. **Use returned context** — do NOT re-search or re-read files already covered\n3. **`read_file` ONLY** for exact lines needed for editing\n4. **Deposit new discoveries:**\n   ```\n   knowledge({ action: 'remember', scope: 'flow', title: '<discovery>', content: '<details>', category: 'context' })\n   ```\n\n**Profile:** `researcher`\n\n## Exploration Protocol\n\n1. **AI Kit Recall** — `search` for existing analysis on this area\n2. **Discover** — Use `find`, `symbol`, `scope_map` to locate relevant files\n3. **Analyze** — Use `analyze({ aspect: \"structure\", ... })`, `analyze({ aspect: \"dependencies\", ... })`, `file_summary`\n4. **Compress** — Use `compact` for targeted file sections, `digest` when synthesizing 3+ sources, `stratum_card` for files you'll reference repeatedly\n5. **Map** — Build a picture of the subsystem: files, exports, dependencies, call chains\n6. **Report** — Structured findings with file paths and key observations\n\n## Exploration Modes\n\n| Goal | Tools |\n|------|-------|\n| Find files for a feature | `find`, `scope_map` |\n| Map a symbol's usage | `symbol`, `trace` |\n| Map module relationships | `graph({ action: 'neighbors' })` — import/export edges across packages |\n| Understand a package | `analyze({ aspect: \"structure\", ... })`, `analyze({ aspect: \"dependencies\", ... })`, `file_summary` |\n| Check impact of a change | `blast_radius` |\n\n## Output Format\n\n```markdown\n## Exploration: {topic}\n\n### Files Found\n- path/to/file.ts — purpose, key exports\n\n### Dependencies\n- package A → package B (via import)\n\n### Key Observations\n- Notable patterns, potential issues, architectural notes\n```\n\n## Rules\n\n- **Speed over depth** — Provide a useful map quickly, not an exhaustive analysis\n- **Read-only** — Never create, edit, or delete files\n- **Structured output** — Always return findings in the format above"};export{e as AGENT_BODIES};

package/scaffold/dist/definitions/protocols.mjs

@@ -271,6 +271,20 @@ Auto-knowledge captures tool responses as shared context between agents. **Befor
 
 **\`read_file\` is ONLY acceptable when you need exact line content FOR EDITING (before \`replace_string_in_file\`).**
 
+## compact() Failure Recovery
+
+If \`compact()\` returns <200 bytes or empty content, the file is NOT indexed. Follow this fallback:
+
+1. **Do NOT retry** compact on the same file — it will fail again
+2. **Use \`read_file\`** with a LARGE range (e.g., \`startLine: 1, endLine: 9999\`) — NEVER chunk into small ranges
+3. **Use \`stash()\`** to cache findings from unindexed files — context pressure causes re-reads
+4. **Check \`status()\`** to see which paths are indexed before calling compact
+
+**Anti-patterns to avoid:**
+- Retrying compact 3x on same unindexed file (wastes 3 tool calls)
+- Falling back to read_file in small chunks (10-50 lines) — each chunk costs ~3K prompt tokens in overhead
+- Re-reading the same file later because you forgot the content — use stash() to cache
+
 ---
 
 ## Context Efficiency (MANDATORY)
@@ -810,7 +824,9 @@ The Orchestrator uses **multi-model decision analysis** to resolve non-trivial t
 
 Dispatch ALL available Researcher variants **in parallel** via \`runSubagent\` — one call per variant, same question, simultaneous. Each returns an independent recommendation grounded in their thinking style:
 
-**IMPORTANT: Include this instruction in every researcher dispatch prompt: "You are running as a subagent. Do NOT use the \`present\` tool — return all analysis as plain text."**
+**IMPORTANT: Include these instructions in every researcher dispatch prompt:**
+- "You are running as a subagent. Do NOT use the \`present\` tool — return all analysis as plain text."
+- "Keep your analysis to ≤ 500 words. Structure: (1) Recommendation, (2) Key evidence, (3) Critical risks. No preamble."
 
 | Variant | Thinking Style | Lens |
 |---------|---------------|------|
@@ -821,7 +837,10 @@ Dispatch ALL available Researcher variants **in parallel** via \`runSubagent\`
 
 ### Phase 2 — Peer Review (parallel)
 
-After all researchers return, **anonymize** their responses as Perspective A / B / C / D (strip agent names). Then dispatch a **second parallel batch** of 4 review sub-agents via \`runSubagent\`:
+After all researchers return:
+1. **Compress** each response to its core argument (≤ 200 words) — \`stash\` full responses if needed later
+2. **Anonymize** as Perspective A / B / C / D (strip agent names)
+3. Dispatch **second parallel batch** of review sub-agents with compressed versions via \`runSubagent\`:
 
 **Peer Review Prompt Template:**
 \`\`\`
@@ -888,7 +907,7 @@ Trigger the decision protocol when there is an **unresolved non-trivial technica
 
 - **\`runSubagent\` is ALWAYS available** — it is a core tool in every environment (VS Code, CLI, Copilot Chat). NEVER claim it is unavailable. NEVER simulate researchers inline by "applying lenses yourself." If you cannot call \`runSubagent\`, you have a tool-loading issue — retry or escalate, do NOT degrade to single-agent inline simulation.
 - **No \`present\` in subagents** — always include "Do NOT use the \`present\` tool — return all analysis as plain text" in every researcher dispatch prompt. Subagent visual outputs are invisible to the user.
-- Always launch in **parallel**, minimum 4 variants
+- Always launch in **parallel** — 4 variants for Critical, 2 (Alpha + Delta) for Standard per tier gate
 - Use exact case-sensitive agent names — never rename or alias
 - **Anonymize** researcher outputs before peer review (A/B/C/D, not agent names)
 - Peer review is a SEPARATE parallel batch — never skip it
@@ -897,12 +916,16 @@ Trigger the decision protocol when there is an **unresolved non-trivial technica
 - **Produce an ADR** after every decision resolution
 - \`knowledge({ action: "remember", ... })\` the decision for future recall
 
-## Shortcut: Floor-Tier Decisions
+## Tier Shortcuts
+
+**Standard tier** (default for multi-file tasks):
+- Phase 1: 2 researchers only (Alpha + Delta) — skip Beta + Gamma
+- Skip Phase 2 (peer review) — synthesize directly from 2 research outputs
+- Verdict format required but can be concise
+- ADR optional (\`knowledge({ action: "remember", ... })\` at minimum)
 
-For decisions classified as **Floor tier** (blast_radius ≤ 2, single concern):
-- Skip Phase 2 (peer review) — synthesis directly from Phase 1
-- Verdict format still required but can be abbreviated
-- ADR is optional (use \`knowledge({ action: "remember", ... })\` at minimum)
+**Floor tier** (blast_radius ≤ 2, single concern):
+- Skip the Decision Protocol entirely — decide inline or with 1 researcher max
 `,"forge-protocol":`# FORGE Protocol — Quality Overlay
 
 > Follow the FORGE (Fact-Oriented Reasoning with Graduated Evidence) protocol for all code generation and modification tasks.

package/scaffold/dist/definitions/skills/adr-skill.mjs

@@ -1384,6 +1384,33 @@ metadata:
 
 # ADR Skill
 
+## Quick Reference
+
+**Purpose:** Create Architecture Decision Records optimized for agentic coding — decisions that agents can implement without follow-up questions.
+
+**Write an ADR when:** Decision changes how system is built, is hard to reverse, affects other people/agents, or has real alternatives.
+
+**Four-Phase Workflow:**
+1. **Discover** — Socratic questioning to surface intent, constraints, and alternatives
+2. **Draft** — Fill template (Simple or MADR) with concrete, measurable constraints
+3. **Validate** — Agent-readiness checklist (score ≥ 80%)
+4. **Record** — Save to \`docs/decisions/\` or \`adr/\`, update index
+
+**Two templates:**
+- **Simple** (≤3 options, single-team) — Context → Decision → Consequences → Implementation Plan → Alternatives
+- **MADR** (complex, multi-team) — Full template with Decision Drivers, Pros/Cons matrix, detailed Implementation Plan
+
+**Commands:**
+| Action | What to do |
+|--------|-----------|
+| Create | Run 4-phase workflow → save to \`docs/decisions/NNNN-slug.md\` |
+| Consult | \`search({ query: "ADR <topic>" })\` before implementing |
+| Update | Edit content, change status in YAML frontmatter |
+| Deprecate | Set \`status: deprecated\`, add superseded-by link |
+| Bootstrap | Create \`docs/decisions/\` + \`index.md\` if missing |
+
+**Agent-readiness gate:** Every ADR scores ≥ 80% on: Specificity, Testability, Completeness, Independence, Actionability.
+
 ## Philosophy
 
 ADRs created with this skill are **executable specifications for coding agents**. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.

package/scaffold/dist/definitions/skills/brainstorming.mjs

@@ -14,6 +14,20 @@ argument-hint: "Feature, component, or behavior to design"
 
 # Brainstorming Ideas Into Designs
 
+## Quick Reference
+
+**Purpose:** Explore user intent, requirements, and design BEFORE any implementation. Mandatory for creative work.
+
+**HARD GATE:** Do NOT write any code until design is presented and user approves. No exceptions, even for "simple" tasks.
+
+**Two modes** (you decide, don't ask user):
+- **Simple Mode** - <=3 files, single concern, no new boundaries -> brief context + 3-5 targeted questions + short design summary
+- **Full Mode** - multi-file, new services, cross-cutting concerns -> deep context gathering + structured design document + explicit approval
+
+**Process:** Understand context -> Ask questions (one at a time) -> Present design -> Get user approval -> Hand off to implementation
+
+**Output:** Design document with: goal, scope, approach, file changes, edge cases, and acceptance criteria.
+
 Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
 
 Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

package/scaffold/dist/definitions/skills/browser-use.mjs

@@ -1,4 +1,4 @@
-var e=[{file:`SKILL.md`,content:"---\nname: browser-use\ndescription: \"Browser automation for AI agents using AI Kit's owned `browser` MCP tool. Triggered when: (1) repo-access exhausts its Strategy Ladder and auth requires browser interaction, (2) `web_fetch` returns login page HTML, SAML redirect, or CAPTCHA instead of content, (3) user needs to interact with web applications (fill forms, click buttons, extract data), (4) a site requires JavaScript rendering that `web_fetch` cannot handle, (5) user asks to browse, scrape, test, or automate a website, or (6) another skill needs a standard recipe format for browser-driven workflows. Uses AI Kit's owned Chromium runtime and recipe patterns for domain-specific automation skills — no external MCP server dependency.\"\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: on-demand\n  inputs: [url, auth-error, browser-task, login-wall]\n  outputs: [page-content, screenshots, extracted-data, authenticated-session, network-captures]\n  requires: []\n  relatedSkills: [repo-access, present, aikit]\nargument-hint: \"URL or browser task description\"\n---\n\n# Browser Automation for AI Agents\n\nUse AI Kit's `browser` MCP tool for authentication barriers, data extraction, form interactions, network capture, and web automation. Single tool, action-based dispatch, owned Chromium runtime.\n\n## Runtime\n\n- Tool: `browser({ action: ... })`\n- 11 actions: `open`, `read`, `act`, `navigate`, `network`, `console`, `fetch`, `eval`, `screenshot`, `dialog`, `session`\n- Modes: `headless` (CI), `ui` (desktop), `panel` (VS Code)\n- Install: `aikit browser install`\n- Auto-idle shutdown after timeout\n\n## When to Activate\n\n- `web_fetch` returns login HTML, SAML redirect, or CAPTCHA\n- `http` returns 401/403 and user confirms browser access works\n- `repo-access` Strategy Ladder exhausted — SSO/OAuth blocks CLI\n- Anti-bot detection (Cloudflare, \"verify you are human\")\n- User asks to browse, scrape, automate, test, or interact with a web app\n- Need screenshots, accessibility snapshots, or JS-rendered content\n- Preview or inspect local HTML files (serve locally, then open with browser)\n- Need to capture network traffic or make authenticated API calls using page session\n\n## When NOT to Activate\n\n- Public pages `web_fetch` handles correctly\n- API endpoints reachable via `http` with auth headers\n- Static downloads via `http`\n- Tasks only needing raw HTML/links/outline\n\n## Two Automation Modes\n\n### Script Mode (Default — Imperative)\n\nDirect sequential `browser()` calls. Best for one-off tasks, testing, API capture.\n\n~~~text\n// Open → Read → Act → Read loop\nbrowser({ action: 'open', url: 'https://app.example.com', mode: 'ui' })\nbrowser({ action: 'read', pageId })\nbrowser({ action: 'act', pageId, kind: 'click', ref: '@login-button' })\nbrowser({ action: 'read', pageId })  // verify state changed\n~~~\n\n**Network Intelligence pattern:**\n\n~~~text\nbrowser({ action: 'network', pageId, subAction: 'enable', filter: { resourceTypes: ['xhr', 'fetch'] } })\n// ... navigate/interact to trigger API calls ...\nbrowser({ action: 'network', pageId, subAction: 'get' })\nbrowser({ action: 'network', pageId, subAction: 'export-har' })\n~~~\n\n**Authenticated API calls (using page cookies/session):**\n\n~~~text\nbrowser({ action: 'fetch', pageId, fetchUrl: 'https://app.example.com/api/data', fetchMethod: 'GET' })\n~~~\n\nExecutes `fetch()` in the page, so cookies, session state, and CSRF tokens are reused automatically.\n\n**Console capture:**\n\n~~~text\nbrowser({ action: 'console', pageId, consoleSubAction: 'enable' })\n// ... trigger page actions ...\nbrowser({ action: 'console', pageId, consoleSubAction: 'get', level: 'error' })\n~~~\n\n### Recipe Mode (Declarative)\n\nStructured step-by-step format for reusable workflows and domain skills. Each step declares Action, Verify, On Failure, and Extract fields.\n\nLoad [references/recipes.md](references/recipes.md) for full recipe templates and the recipe format specification.\n\nBrief recipe format:\n\n~~~text\nStep N: <description>\n  Action: browser({ ... })\n  Verify: <condition to check after action>\n  On Failure: <recovery strategy>\n  Extract: <data to capture for next steps>\n~~~\n\n## Action Reference\n\n| Action | Purpose | Key Params |\n|--------|---------|------------|\n| `open` | Launch page | `url`, `mode` (ui/headless/panel), `waitUntil` |\n| `read` | Extract content | `pageId`, `readMode` (snapshot/dom/markdown/text), `selector` |\n| `act` | DOM interaction | `pageId`, `kind`, `ref`/`selector`, `text`/`key`/`value` |\n| `navigate` | Page navigation | `pageId`, `url` or `type` (back/forward/reload/waitFor) |\n| `network` | Capture traffic | `pageId`, `subAction` (enable/get/clear/export-har), `filter` |\n| `console` | Capture console | `pageId`, `consoleSubAction` (enable/get/clear), `level` |\n| `fetch` | Page-context HTTP | `pageId`, `fetchUrl`, `fetchMethod`, `fetchHeaders`, `fetchBody` |\n| `eval` | Execute JS | `pageId`, `code` |\n| `screenshot` | Capture image | `pageId`, `selector`, `fullPage`, `clip`, `format` |\n| `dialog` | Pre-register handler for NEXT dialog | `pageId`, `accept`, `promptText` |\n| `session` | Manage sessions | `sessionAction` (list/close/cookies/set-cookie/get-storage/...) |\n\n## Read Modes\n\n| Mode | Output | Use Case |\n|------|--------|----------|\n| `snapshot` | ARIA accessibility tree with refs | Element targeting, form interaction |\n| `dom` | Raw HTML | HTML structure, debugging |\n| `markdown` | Clean readable text | Content extraction, summarization |\n| `text` | Plain text | Simple text extraction |\n\n## Interaction Kinds\n\n| Kind | Required Params | Notes |\n|------|-----------------|-------|\n| `click` | `ref` or `selector` | Left-click element |\n| `type` | `ref`/`selector` + `text` | Type into input/textarea |\n| `press` | `ref`/`selector` + `key` | Send key to element. Requires a target — use `ref` from snapshot or `selector`. |\n| `hover` | `ref`/`selector` | Trigger hover states |\n| `drag` | `fromRef`/`fromSelector` + `toRef`/`toSelector` | Drag and drop |\n| `select` | `ref`/`selector` + `value` | Select dropdown option |\n| `scroll` | optional `ref`/`selector` | Scroll page or element |\n| `upload` | `ref`/`selector` + `value` (path) | File upload |\n\n### Element Targeting Priority\n\n1. **`ref`** (e.g., `@F12`) — From `read(snapshot)` ARIA tree. Most reliable.\n2. **`selector`** (e.g., `input[name='q']`) — Playwright CSS/attribute selector. Precise.\n3. **`element`** (e.g., `'Submit'`) — Text matching via `text=` locator. **Picks first DOM match regardless of visibility.** Fragile for complex widgets (comboboxes, ARIA roles). Last resort.\n\n**Always `read(snapshot)` first** to get refs before interacting.\n\n> **Visibility Warning**: Playwright `act` waits up to 30s for the target to be visible. If a selector or `element` matches a hidden element first, the action times out. The browser tool does NOT expose a `force` or custom `timeout` parameter.\n>\n> **Workarounds:**\n> - Append `:visible` to selectors: `selector: 'button:has-text(\"Submit\"):visible'`\n> - Use specific selectors instead of `element` when labels are ambiguous (e.g., \"Search\" may match 30+ elements)\n> - Use `read(snapshot)` refs (`@F12`) which always target the specific rendered element\n\n## Network Intelligence\n\nThree new actions for API reverse-engineering and authenticated requests:\n\n**`network`** — Passive traffic capture with circular buffer (200 entries default):\n- `enable`: Start capturing with optional filter (resourceTypes, urlPattern, excludeUrls)\n- `get`: Retrieve captured requests + responses with timing\n- `clear`: Reset buffer\n- `export-har`: Export as HAR 1.2 format\n\nHeaders are redacted by default (Authorization, Cookie, etc.). Pass `showSensitive: true` to see full headers.\n\n**`console`** — Browser console message capture (1000 entries default):\n- `enable`: Start capturing all console output\n- `get`: Retrieve messages, optionally filtered by `level`\n- `clear`: Reset buffer\n\n**`fetch`** — Execute HTTP from page context:\n- Uses the page's live cookies, session, CSRF tokens\n- Supports GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS\n- Body auto-truncated at 256KB\n- Alternative to extracting cookies then calling `http` tool\n\n**Workflow — Reverse-engineer API:**\n\n~~~text\n1. open target page\n2. network enable (filter: xhr, fetch)\n3. interact with the page (click buttons, submit forms)\n4. network get → see API endpoints, methods, headers\n5. fetch → replay API calls using page session\n~~~\n\n## Session Management\n\n| Action | Purpose | Note |\n|--------|---------|------|\n| `cookies` | Export page cookies | `confirm: true` required |\n| `set-cookie` | Inject cookies | `confirm: true` required |\n| `delete-cookie` / `clear-cookies` | Remove cookies | `confirm: true` required |\n| `get-storage` / `set-storage` / `clear-storage` | localStorage/sessionStorage | |\n| `list` | List open pages | |\n| `close` | Close a page | |\n\n## Security Model\n\n**Hard gates — NEVER bypass:**\n- Credentials go via terminal input (NEVER through tool params or chat)\n- CAPTCHA/MFA: pause and ask user\n- Never store tokens in conversation\n- Close pages containing sensitive data when done\n- Verify page URL before entering credentials (phishing prevention)\n- Use `headless` mode for automated non-interactive tasks; `ui` for user-supervised auth\n\n**Cookie safety gate:** All cookie read/write session actions (`cookies`, `set-cookie`, `delete-cookie`, `clear-cookies`) require `confirm: true` as an explicit acknowledgment. Without it, the tool returns an error.\n\n## Local File Preview\n\nThe browser tool blocks `file:///` URLs for security. To preview local HTML files, serve them via a local HTTP server first.\n\n**Pattern:**\n\n~~~text\n// 1. Start local server (pick an unused port)\n//    Terminal: npx -y serve <directory> -l <port>\n//    Example: npx -y serve ./dist -l 3847\n\n// 2. Open in browser\nbrowser({ action: 'open', url: 'http://localhost:3847/my-file.html', mode: 'ui' })\n\n// 3. Read content or take screenshot\nbrowser({ action: 'read', pageId, readMode: 'markdown' })\nbrowser({ action: 'screenshot', pageId, fullPage: true })\n\n// 4. Clean up — kill the server terminal when done\n~~~\n\n**Use cases:**\n- Preview generated HTML (viewers, reports, docs)\n- Visual regression testing of local builds\n- Inspect single-file HTML applications\n- Screenshot local pages for review\n\n**Important:** Always use `mode: 'ui'` for visual preview so the user can also see and interact with the page.\n\n## Integration\n\n| Skill | Handoff Pattern |\n|-------|------------------|\n| `repo-access` | Strategy Ladder step 6 → browser-use for SSO/OAuth login |\n| `present` | `present({ format: 'browser' })` returns URL → open with browser tool |\n| `aikit` | `web_fetch` fails → browser-use activates |\n\n## Dialog Handling\n\n`dialog()` registers a **one-shot handler** for the NEXT dialog. It must be called **BEFORE** the action that triggers alert, confirm, or prompt.\n\n**Pattern:**\n~~~text\nbrowser({ action: 'dialog', pageId, accept: true })\nbrowser({ action: 'eval', pageId, code: 'confirm(\"Sure?\")' }) // or browser({ action: 'act', ... }) if interaction triggers it\n~~~\n\nFor `prompt` dialogs, pass `promptText` for the response.\n\n## Troubleshooting\n\n| Issue | Fix |\n|-------|-----|\n| \"Browser not installed\" | Run `aikit browser install` |\n| Element not found | `read` with `snapshot` mode first, use ref from ARIA tree |\n| Timeout on navigation | Add `waitUntil: 'networkidle'` to open/navigate |\n| SSO redirect loop | Check cookies with `session({ sessionAction: 'cookies' })` |\n| Anti-bot block | Try `mode: 'ui'`, add delays between actions |\n| Network capture empty | Ensure `enable` called BEFORE navigating |\n\n## Decision Flow\n\n~~~text\nNeed browser?\n├─ Can web_fetch/http handle it? → NO browser needed\n├─ Login wall / SSO / CAPTCHA? → browser-use (Script mode for one-off, Recipe for reusable)\n├─ Need to capture API traffic? → network enable → interact → network get\n├─ Need authenticated API calls? → fetch action (uses page session)\n├─ JS-rendered content? → open + read(markdown)\n├─ Preview local HTML file? → serve dir (npx serve) → open(http://localhost:<port>/file.html, mode: 'ui')\n├─ Form interaction? → Script mode: open → read(snapshot) → act → verify\n└─ Reusable workflow? → Recipe mode (see references/recipes.md)\n~~~\n"},{file:`references/recipes.md`,content:`# Browser Recipes & Domain Skills
+var e=[{file:`SKILL.md`,content:"---\nname: browser-use\ndescription: \"Browser automation for AI agents using AI Kit's owned `browser` MCP tool. Triggered when: (1) repo-access exhausts its Strategy Ladder and auth requires browser interaction, (2) `web_fetch` returns login page HTML, SAML redirect, or CAPTCHA instead of content, (3) user needs to interact with web applications (fill forms, click buttons, extract data), (4) a site requires JavaScript rendering that `web_fetch` cannot handle, (5) user asks to browse, scrape, test, or automate a website, or (6) another skill needs a standard recipe format for browser-driven workflows. Uses AI Kit's owned Chromium runtime and recipe patterns for domain-specific automation skills — no external MCP server dependency.\"\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: on-demand\n  inputs: [url, auth-error, browser-task, login-wall]\n  outputs: [page-content, screenshots, extracted-data, authenticated-session, network-captures]\n  requires: []\n  relatedSkills: [repo-access, present, aikit]\nargument-hint: \"URL or browser task description\"\n---\n\n# Browser Automation for AI Agents\n\nUse AI Kit's `browser` MCP tool for authentication barriers, data extraction, form interactions, network capture, and web automation. Single tool, action-based dispatch, owned Chromium runtime.\n\n## Quick Reference\n\n**Tool:** `browser({ action: \"...\", ... })` — single tool, 11 actions, owned Chromium.\n\n**Actions:**\n| Action | Purpose | Key params |\n|--------|---------|------------|\n| `open` | Launch page | `url`, `mode` (ui/headless) |\n| `read` | Get page content | `pageId`, `readMode` (snapshot/dom/markdown/text) |\n| `act` | Interact with elements | `pageId`, `kind` (click/type/press/hover/drag/select/scroll/upload) |\n| `navigate` | Go to URL, back/forward, wait | `pageId`, `url` or `type` |\n| `network` | Capture network traffic | `pageId`, `subAction` (enable/get/clear) |\n| `console` | Browser console messages | `pageId`, `consoleSubAction` |\n| `fetch` | HTTP with page cookies | `pageId`, `fetchUrl` |\n| `eval` | Run JS in page context | `pageId`, `code` |\n| `screenshot` | Capture page/element | `pageId`, `fullPage?`, `selector?` |\n| `dialog` | Handle alert/confirm/prompt | `pageId`, `accept` |\n| `session` | List pages, cookies, storage | `sessionAction` |\n\n**Two modes:**\n- **Script Mode** (default) — direct sequential `browser()` calls for one-off tasks\n- **Recipe Mode** — reusable labeled step sequences for domain-specific automation\n\n**Activate when:** `web_fetch` returns login/SAML/CAPTCHA, `http` gets 401/403, anti-bot detection, need JS rendering or screenshots.\n**Skip when:** Public pages (`web_fetch` works), API endpoints (`http` works), static downloads.\n\n**⚠️ `file:///` URLs are blocked** — serve locally with `npx serve` then open `http://localhost`.\n\n## Runtime\n\n- Tool: `browser({ action: ... })`\n- 11 actions: `open`, `read`, `act`, `navigate`, `network`, `console`, `fetch`, `eval`, `screenshot`, `dialog`, `session`\n- Modes: `headless` (CI), `ui` (desktop), `panel` (VS Code)\n- Install: `aikit browser install`\n- Auto-idle shutdown after timeout\n\n## When to Activate\n\n- `web_fetch` returns login HTML, SAML redirect, or CAPTCHA\n- `http` returns 401/403 and user confirms browser access works\n- `repo-access` Strategy Ladder exhausted — SSO/OAuth blocks CLI\n- Anti-bot detection (Cloudflare, \"verify you are human\")\n- User asks to browse, scrape, automate, test, or interact with a web app\n- Need screenshots, accessibility snapshots, or JS-rendered content\n- Preview or inspect local HTML files (serve locally, then open with browser)\n- Need to capture network traffic or make authenticated API calls using page session\n\n## When NOT to Activate\n\n- Public pages `web_fetch` handles correctly\n- API endpoints reachable via `http` with auth headers\n- Static downloads via `http`\n- Tasks only needing raw HTML/links/outline\n\n## Two Automation Modes\n\n### Script Mode (Default — Imperative)\n\nDirect sequential `browser()` calls. Best for one-off tasks, testing, API capture.\n\n~~~text\n// Open → Read → Act → Read loop\nbrowser({ action: 'open', url: 'https://app.example.com', mode: 'ui' })\nbrowser({ action: 'read', pageId })\nbrowser({ action: 'act', pageId, kind: 'click', ref: '@login-button' })\nbrowser({ action: 'read', pageId })  // verify state changed\n~~~\n\n**Network Intelligence pattern:**\n\n~~~text\nbrowser({ action: 'network', pageId, subAction: 'enable', filter: { resourceTypes: ['xhr', 'fetch'] } })\n// ... navigate/interact to trigger API calls ...\nbrowser({ action: 'network', pageId, subAction: 'get' })\nbrowser({ action: 'network', pageId, subAction: 'export-har' })\n~~~\n\n**Authenticated API calls (using page cookies/session):**\n\n~~~text\nbrowser({ action: 'fetch', pageId, fetchUrl: 'https://app.example.com/api/data', fetchMethod: 'GET' })\n~~~\n\nExecutes `fetch()` in the page, so cookies, session state, and CSRF tokens are reused automatically.\n\n**Console capture:**\n\n~~~text\nbrowser({ action: 'console', pageId, consoleSubAction: 'enable' })\n// ... trigger page actions ...\nbrowser({ action: 'console', pageId, consoleSubAction: 'get', level: 'error' })\n~~~\n\n### Recipe Mode (Declarative)\n\nStructured step-by-step format for reusable workflows and domain skills. Each step declares Action, Verify, On Failure, and Extract fields.\n\nLoad [references/recipes.md](references/recipes.md) for full recipe templates and the recipe format specification.\n\nBrief recipe format:\n\n~~~text\nStep N: <description>\n  Action: browser({ ... })\n  Verify: <condition to check after action>\n  On Failure: <recovery strategy>\n  Extract: <data to capture for next steps>\n~~~\n\n## Action Reference\n\n| Action | Purpose | Key Params |\n|--------|---------|------------|\n| `open` | Launch page | `url`, `mode` (ui/headless/panel), `waitUntil` |\n| `read` | Extract content | `pageId`, `readMode` (snapshot/dom/markdown/text), `selector` |\n| `act` | DOM interaction | `pageId`, `kind`, `ref`/`selector`, `text`/`key`/`value` |\n| `navigate` | Page navigation | `pageId`, `url` or `type` (back/forward/reload/waitFor) |\n| `network` | Capture traffic | `pageId`, `subAction` (enable/get/clear/export-har), `filter` |\n| `console` | Capture console | `pageId`, `consoleSubAction` (enable/get/clear), `level` |\n| `fetch` | Page-context HTTP | `pageId`, `fetchUrl`, `fetchMethod`, `fetchHeaders`, `fetchBody` |\n| `eval` | Execute JS | `pageId`, `code` |\n| `screenshot` | Capture image | `pageId`, `selector`, `fullPage`, `clip`, `format` |\n| `dialog` | Pre-register handler for NEXT dialog | `pageId`, `accept`, `promptText` |\n| `session` | Manage sessions | `sessionAction` (list/close/cookies/set-cookie/get-storage/...) |\n\n## Read Modes\n\n| Mode | Output | Use Case |\n|------|--------|----------|\n| `snapshot` | ARIA accessibility tree with refs | Element targeting, form interaction |\n| `dom` | Raw HTML | HTML structure, debugging |\n| `markdown` | Clean readable text | Content extraction, summarization |\n| `text` | Plain text | Simple text extraction |\n\n## Interaction Kinds\n\n| Kind | Required Params | Notes |\n|------|-----------------|-------|\n| `click` | `ref` or `selector` | Left-click element |\n| `type` | `ref`/`selector` + `text` | Type into input/textarea |\n| `press` | `ref`/`selector` + `key` | Send key to element. Requires a target — use `ref` from snapshot or `selector`. |\n| `hover` | `ref`/`selector` | Trigger hover states |\n| `drag` | `fromRef`/`fromSelector` + `toRef`/`toSelector` | Drag and drop |\n| `select` | `ref`/`selector` + `value` | Select dropdown option |\n| `scroll` | optional `ref`/`selector` | Scroll page or element |\n| `upload` | `ref`/`selector` + `value` (path) | File upload |\n\n### Element Targeting Priority\n\n1. **`ref`** (e.g., `@F12`) — From `read(snapshot)` ARIA tree. Most reliable.\n2. **`selector`** (e.g., `input[name='q']`) — Playwright CSS/attribute selector. Precise.\n3. **`element`** (e.g., `'Submit'`) — Text matching via `text=` locator. **Picks first DOM match regardless of visibility.** Fragile for complex widgets (comboboxes, ARIA roles). Last resort.\n\n**Always `read(snapshot)` first** to get refs before interacting.\n\n> **Visibility Warning**: Playwright `act` waits up to 30s for the target to be visible. If a selector or `element` matches a hidden element first, the action times out. The browser tool does NOT expose a `force` or custom `timeout` parameter.\n>\n> **Workarounds:**\n> - Append `:visible` to selectors: `selector: 'button:has-text(\"Submit\"):visible'`\n> - Use specific selectors instead of `element` when labels are ambiguous (e.g., \"Search\" may match 30+ elements)\n> - Use `read(snapshot)` refs (`@F12`) which always target the specific rendered element\n\n## Network Intelligence\n\nThree new actions for API reverse-engineering and authenticated requests:\n\n**`network`** — Passive traffic capture with circular buffer (200 entries default):\n- `enable`: Start capturing with optional filter (resourceTypes, urlPattern, excludeUrls)\n- `get`: Retrieve captured requests + responses with timing\n- `clear`: Reset buffer\n- `export-har`: Export as HAR 1.2 format\n\nHeaders are redacted by default (Authorization, Cookie, etc.). Pass `showSensitive: true` to see full headers.\n\n**`console`** — Browser console message capture (1000 entries default):\n- `enable`: Start capturing all console output\n- `get`: Retrieve messages, optionally filtered by `level`\n- `clear`: Reset buffer\n\n**`fetch`** — Execute HTTP from page context:\n- Uses the page's live cookies, session, CSRF tokens\n- Supports GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS\n- Body auto-truncated at 256KB\n- Alternative to extracting cookies then calling `http` tool\n\n**Workflow — Reverse-engineer API:**\n\n~~~text\n1. open target page\n2. network enable (filter: xhr, fetch)\n3. interact with the page (click buttons, submit forms)\n4. network get → see API endpoints, methods, headers\n5. fetch → replay API calls using page session\n~~~\n\n## Session Management\n\n| Action | Purpose | Note |\n|--------|---------|------|\n| `cookies` | Export page cookies | `confirm: true` required |\n| `set-cookie` | Inject cookies | `confirm: true` required |\n| `delete-cookie` / `clear-cookies` | Remove cookies | `confirm: true` required |\n| `get-storage` / `set-storage` / `clear-storage` | localStorage/sessionStorage | |\n| `list` | List open pages | |\n| `close` | Close a page | |\n\n## Security Model\n\n**Hard gates — NEVER bypass:**\n- Credentials go via terminal input (NEVER through tool params or chat)\n- CAPTCHA/MFA: pause and ask user\n- Never store tokens in conversation\n- Close pages containing sensitive data when done\n- Verify page URL before entering credentials (phishing prevention)\n- Use `headless` mode for automated non-interactive tasks; `ui` for user-supervised auth\n\n**Cookie safety gate:** All cookie read/write session actions (`cookies`, `set-cookie`, `delete-cookie`, `clear-cookies`) require `confirm: true` as an explicit acknowledgment. Without it, the tool returns an error.\n\n## Local File Preview\n\nThe browser tool blocks `file:///` URLs for security. To preview local HTML files, serve them via a local HTTP server first.\n\n**Pattern:**\n\n~~~text\n// 1. Start local server (pick an unused port)\n//    Terminal: npx -y serve <directory> -l <port>\n//    Example: npx -y serve ./dist -l 3847\n\n// 2. Open in browser\nbrowser({ action: 'open', url: 'http://localhost:3847/my-file.html', mode: 'ui' })\n\n// 3. Read content or take screenshot\nbrowser({ action: 'read', pageId, readMode: 'markdown' })\nbrowser({ action: 'screenshot', pageId, fullPage: true })\n\n// 4. Clean up — kill the server terminal when done\n~~~\n\n**Use cases:**\n- Preview generated HTML (viewers, reports, docs)\n- Visual regression testing of local builds\n- Inspect single-file HTML applications\n- Screenshot local pages for review\n\n**Important:** Always use `mode: 'ui'` for visual preview so the user can also see and interact with the page.\n\n## Integration\n\n| Skill | Handoff Pattern |\n|-------|------------------|\n| `repo-access` | Strategy Ladder step 6 → browser-use for SSO/OAuth login |\n| `present` | `present({ format: 'browser' })` returns URL → open with browser tool |\n| `aikit` | `web_fetch` fails → browser-use activates |\n\n## Dialog Handling\n\n`dialog()` registers a **one-shot handler** for the NEXT dialog. It must be called **BEFORE** the action that triggers alert, confirm, or prompt.\n\n**Pattern:**\n~~~text\nbrowser({ action: 'dialog', pageId, accept: true })\nbrowser({ action: 'eval', pageId, code: 'confirm(\"Sure?\")' }) // or browser({ action: 'act', ... }) if interaction triggers it\n~~~\n\nFor `prompt` dialogs, pass `promptText` for the response.\n\n## Troubleshooting\n\n| Issue | Fix |\n|-------|-----|\n| \"Browser not installed\" | Run `aikit browser install` |\n| Element not found | `read` with `snapshot` mode first, use ref from ARIA tree |\n| Timeout on navigation | Add `waitUntil: 'networkidle'` to open/navigate |\n| SSO redirect loop | Check cookies with `session({ sessionAction: 'cookies' })` |\n| Anti-bot block | Try `mode: 'ui'`, add delays between actions |\n| Network capture empty | Ensure `enable` called BEFORE navigating |\n\n## Decision Flow\n\n~~~text\nNeed browser?\n├─ Can web_fetch/http handle it? → NO browser needed\n├─ Login wall / SSO / CAPTCHA? → browser-use (Script mode for one-off, Recipe for reusable)\n├─ Need to capture API traffic? → network enable → interact → network get\n├─ Need authenticated API calls? → fetch action (uses page session)\n├─ JS-rendered content? → open + read(markdown)\n├─ Preview local HTML file? → serve dir (npx serve) → open(http://localhost:<port>/file.html, mode: 'ui')\n├─ Form interaction? → Script mode: open → read(snapshot) → act → verify\n└─ Reusable workflow? → Recipe mode (see references/recipes.md)\n~~~\n"},{file:`references/recipes.md`,content:`# Browser Recipes & Domain Skills
 
 Reference file for reusable browser automation patterns. Load this when building domain-specific browser workflows.
 

package/scaffold/dist/definitions/skills/c4-architecture.mjs

@@ -1511,6 +1511,32 @@ metadata:
 
 # C4 Architecture Documentation
 
+## Quick Reference
+
+**Output formats:** Mermaid (markdown) for simple diagrams | HTML viewer for interactive diagrams (>5 components)
+
+**HTML viewer - data injection API:**
+- Copy template: \`cp assets/c4-viewer.html docs/architecture/interactive/{name}.html\`
+- Create data JSON matching this shape:
+  \`\`\`json
+  {
+    "title": "System Name",
+    "elements": [
+      { "id": "unique-id", "label": "Display Name", "type": "system|container|component|person|database|queue|external",
+        "technology": "optional", "description": "optional", "tags": ["optional"], "parentId": "optional-parent-id" }
+    ],
+    "relationships": [
+      { "sourceId": "from-id", "targetId": "to-id", "label": "optional", "technology": "optional" }
+    ]
+  }
+  \`\`\`
+- Inject data: \`node scripts/inject-viewer.mjs --template assets/c4-viewer.html --data {data.json} --out {output.html}\`
+- The script replaces content of \`<script type="application/json" id="diagram-data">\` in the template
+
+**NEVER \`read_file\` on \`assets/c4-viewer.html\`** - it's a 1.8MB minified React/ReactFlow bundle. Use the injection API above.
+
+**Full schema:** [references/c4.schema.json](references/c4.schema.json) | **Design patterns:** [references/advanced-patterns.md](references/advanced-patterns.md) | **Common mistakes:** [references/common-mistakes.md](references/common-mistakes.md)
+
 Generate software architecture documentation using C4 model diagrams in Mermaid syntax.
 
 ## Workflow
@@ -1979,6 +2005,8 @@ Write architecture documentation to \`docs/architecture/\` with naming conventio
 
 AI Kit ships a pre-built \`c4-viewer.html\` that handles ALL rendering, layout (ELK.js), styling, and interaction. The LLM's only job is to produce valid JSON matching [references/c4.schema.json](references/c4.schema.json). **NEVER generate HTML for architecture diagrams** — inject JSON into the shipped viewer.
 
+> **WARNING**: NEVER \`read_file\` on \`assets/c4-viewer.html\` - it is a 1.8MB minified bundle. The injection API below is all you need.
+
 ### Usage
 
 1. Generate JSON matching [references/c4.schema.json](references/c4.schema.json)
@@ -2041,7 +2069,24 @@ present({
 }
 \`\`\`
 
-The viewer expects a JSON object matching [references/c4.schema.json](references/c4.schema.json).
+The viewer expects this JSON shape (full schema: [references/c4.schema.json](references/c4.schema.json)):
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`title\` | string | Yes | Diagram title |
+| \`elements[]\` | array | Yes | C4 elements (systems, containers, components, people) |
+| \`elements[].id\` | string | Yes | Unique identifier |
+| \`elements[].label\` | string | Yes | Display name |
+| \`elements[].type\` | string | Yes | \`system|container|component|person|database|queue|external\` |
+| \`elements[].technology\` | string | No | Technology stack |
+| \`elements[].description\` | string | No | Brief description |
+| \`elements[].tags\` | string[] | No | Categorization tags |
+| \`elements[].parentId\` | string | No | Nesting - references another element's id |
+| \`relationships[]\` | array | Yes | Connections between elements |
+| \`relationships[].sourceId\` | string | Yes | Source element id |
+| \`relationships[].targetId\` | string | Yes | Target element id |
+| \`relationships[].label\` | string | No | Relationship description |
+| \`relationships[].technology\` | string | No | Protocol/technology used |
 
 **Node types:** person, system, container, component, database, queue, external, boundary, deploymentNode
 

package/scaffold/dist/definitions/skills/docs.mjs

@@ -2142,6 +2142,38 @@ metadata:
 
 Manage the \`docs/\` folder as a single source of truth for project documentation. This skill runs during the mandatory \`_docs-sync\` epilogue step of every flow, ensuring documentation stays in sync with code changes.
 
+## Quick Reference
+
+**Purpose:** Manage \`docs/\` folder as living documentation. Runs during \`_docs-sync\` epilogue of every flow.
+
+**When triggered:** Automatically after every flow completion (epilogue step). Also manually for fresh generation.
+
+**Four scenarios:**
+1. **Fresh Generation** — no \`docs/\` exists → full 7-phase pipeline
+2. **Update Mode** — \`docs/\` exists with standard structure → incremental update
+3. **Migration Mode** — \`docs/\` exists with non-standard structure → migrate first
+4. **Epilogue Sync** — during flow \`_docs-sync\` step → combines with 1-3
+
+**Tour viewer — data injection API:**
+- Copy template: \`cp assets/tour-viewer.html docs/{name}-tour.html\`
+- Create tour JSON matching this shape:
+  \`\`\`json
+  {
+    "title": "Tour Title",
+    "steps": [
+      { "title": "Step Name", "file": "src/path.ts", "line": 42, "description": "What to notice here", "highlights": ["symbol1"] }
+    ]
+  }
+  \`\`\`
+- Inject data: \`node scripts/inject-viewer.mjs --template assets/tour-viewer.html --data {data.json} --out {output.html}\`
+- The script replaces content of \`<script type="application/json" id="diagram-data">\` in the template
+
+**NEVER \`read_file\` on \`assets/tour-viewer.html\`** — it's a large minified React bundle. Use the injection API above.
+
+**Full tour schema:** [references/tour.schema.json](references/tour.schema.json) | **Code tour patterns:** [references/code-tour-patterns.md](references/code-tour-patterns.md) | **Staleness config:** [references/staleness-config.md](references/staleness-config.md)
+
+**Diátaxis framework:** Tutorials (learning+doing) · How-to (working+doing) · Reference (working+understanding) · Explanation (learning+understanding). See [references/diataxis-reference.md](references/diataxis-reference.md).
+
 ## Principles
 
 1. **Living, not legacy** — Documentation is updated as code changes, never as a separate "docs sprint"
@@ -2612,6 +2644,8 @@ This phase uses the **c4-architecture skill** to produce interactive, data-drive
 
 Tour generation Phase 4c produces interactive tour viewers. Use the docs skill's \`assets/tour-viewer.html\` template:
 
+> **WARNING**: NEVER \`read_file\` on \`assets/tour-viewer.html\` — it is a large minified bundle. Use the injection script above.
+
 \`\`\`bash
 node scripts/inject-viewer.mjs --template assets/tour-viewer.html --data <tour-data.json> --out docs/tours/interactive/<tour-name>.html
 \`\`\`

package/scaffold/dist/definitions/skills/frontend-design.mjs

@@ -14,6 +14,26 @@ metadata:
 
 > Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection. Synthesized from Anthropic's frontend-design skill, Vercel Web Interface Guidelines, and Impeccable design patterns.
 
+## Quick Reference
+
+**Purpose:** Comprehensive design guidance — typography, color, layout, motion, accessibility, performance, anti-pattern detection.
+
+**Mandatory** for the Frontend agent on every task. Also for any UI, styling, responsive, or design work.
+
+**Context checklist** (infer from codebase if not specified):
+Design system? | Brand guidelines? | Accessibility level (AA default)? | Breakpoints? | Motion budget? | Dark mode? | Target platforms?
+
+**Design cycle:** Understand → Explore → Evaluate → Refine
+
+**Key principles:**
+- Typography: system font stack, modular scale, max 2 families
+- Color: semantic tokens (\`--color-success\`, not \`--green\`), 4.5:1+ contrast
+- Layout: CSS Grid for 2D, Flexbox for 1D, \`min()\`/\`clamp()\` for fluid sizing
+- Motion: \`prefers-reduced-motion\`, \`will-change\` sparingly, 200-300ms for UI
+- Accessibility: semantic HTML first, ARIA only when needed, focus visible, skip links
+
+**Anti-patterns to catch:** z-index wars, magic numbers, \`!important\` chains, px-only sizing, color-only status indicators.
+
 ## When to Use
 
 **MANDATORY** for the Frontend agent on every task. Also use when:

package/scaffold/dist/definitions/skills/present.mjs

@@ -13,6 +13,37 @@ argument-hint: "Content to present — data, analysis results, status report, co
 
 # Present Tool — Rich Interactive Dashboards
 
+## Quick Reference
+
+**Two formats:**
+- \`html\` — in-chat UIResource (display-only: tables, charts, reports). DEFAULT choice.
+- \`browser\` — local URL in system browser (when you need user interaction back, or in CLI mode).
+
+**Content blocks** (pass as \`content\` array of \`{ type, title?, value }\`):
+| Type | Value shape | Use for |
+|------|-------------|---------|
+| \`markdown\` | string | Prose, headings, code — **never tables** |
+| \`table\` | \`Record[]\` or \`{headers,rows}\` | **All tabular data** (NEVER put tables in markdown blocks) |
+| \`chart\` | \`{chartType,data,xKey,yKeys}\` | Bar, line, area, pie, radar, scatter |
+| \`metrics\` | \`[{label,value,trend?,status?}]\` | KPI cards |
+| \`cards\` | \`[{title,body?,badge?,status?}]\` | Info cards |
+| \`mermaid\` | string | Diagrams |
+| \`tree\` | \`{name,children?}\` | Hierarchical data |
+| \`timeline\` | \`[{title,description?,timestamp?,status?}]\` | Event sequences |
+| \`checklist\` | \`[{label,checked}]\` | Todo/check lists |
+| \`code\` | string | Code blocks |
+
+**Actions** (interactive buttons/selects, mainly for \`browser\` mode):
+\`\`\`json
+{ "actions": [{ "type": "button", "id": "approve", "label": "Approve", "variant": "primary" }] }
+\`\`\`
+
+**Anti-patterns:**
+- ❌ Tables inside \`markdown\` blocks → renders as raw pipe text
+- ❌ \`html\` format in CLI mode → invisible (use \`browser\`)
+- ❌ Unicode escapes in \`title\` param (\`\\u2014\`) → literal text (use actual — character)
+- ❌ Chart.js format (\`{labels,datasets}\`) → use \`{chartType,data,xKey,yKeys}\`
+
 The \`present\` tool renders structured content as a professional dark-themed dashboard. It supports two output modes:
 
 - **\`html\`** — Renders an embedded UIResource for MCP-UI hosts (in-chat). Best for display-only content.

package/scaffold/dist/definitions/skills/session-handoff.mjs

@@ -1313,6 +1313,26 @@ metadata:
 
 Creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves the long-running agent context exhaustion problem.
 
+## Quick Reference
+
+**Purpose:** Create handoff documents for seamless AI session transfers. Solves context exhaustion — fresh agents continue with zero ambiguity.
+
+**Two modes:**
+- **CREATE** — Save current state when: user requests, context filling up, milestone completed, session ending
+- **RESUME** — Load prior state when: user says "continue", "resume", or references existing handoff
+
+**Dual storage** (every handoff creates both):
+1. **Full file** → \`.aikit-state/handoffs/{flow-slug}/<timestamp>-<slug>.md\` (browsable, gitignored)
+2. **Compact entry** → \`knowledge({ action: "remember", scope: "flow", category: "session", title: "Session Handoff: <slug>" })\` (~1-2K chars, for \`withdraw\`)
+
+**CREATE workflow:** Gather state → Fill template (metadata, state summary, codebase understanding, work completed, pending work, resume context) → Save dual format → Present summary
+
+**RESUME workflow:** \`withdraw({ scope: "flow", profile: "implementer" })\` → Read compact entry → If need full context, read file from \`.aikit-state/handoffs/\` → Verify state → Continue work
+
+**Template sections:** Session Metadata | Current State | Codebase Understanding | Work Completed | Pending Work | Resume Context | Environment State | Related Resources
+
+**Proactive trigger:** After 5+ file edits, complex debugging, or major decisions → suggest handoff.
+
 ## Mode Selection
 
 Determine which mode applies: