@vpxa/aikit 0.1.147 → 0.1.148

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.147",
+  "version": "0.1.148",
   "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/definitions/plugins.mjs

@@ -1 +1 @@
-const e={aikit:{description:`AI Kit search, analysis, memory, and developer tools`,source:`scaffold/skills/aikit/SKILL.md`,required:!0},brainstorming:{description:`Brainstorming & design exploration workflow`,source:`scaffold/skills/brainstorming/SKILL.md`,required:!0,sidecars:[`scaffold/skills/brainstorming/spec-document-reviewer-prompt.md`]},"multi-agents-development":{description:`Multi-agent orchestration, task decomposition, parallel dispatch, and review pipeline patterns`,source:`scaffold/skills/multi-agents-development/SKILL.md`,required:!0,sidecars:[`scaffold/skills/multi-agents-development/implementer-prompt.md`,`scaffold/skills/multi-agents-development/spec-review-prompt.md`,`scaffold/skills/multi-agents-development/code-quality-review-prompt.md`,`scaffold/skills/multi-agents-development/architecture-review-prompt.md`,`scaffold/skills/multi-agents-development/parallel-dispatch-example.md`]},"adr-skill":{description:`Architecture Decision Records — create, maintain, and review ADRs for significant technical decisions`,source:`scaffold/skills/adr-skill/SKILL.md`,required:!0,sidecars:[`scaffold/skills/adr-skill/assets/templates/adr-madr.md`,`scaffold/skills/adr-skill/assets/templates/adr-readme.md`,`scaffold/skills/adr-skill/assets/templates/adr-simple.md`,`scaffold/skills/adr-skill/references/adr-conventions.md`,`scaffold/skills/adr-skill/references/examples.md`,`scaffold/skills/adr-skill/references/review-checklist.md`,`scaffold/skills/adr-skill/references/template-variants.md`,`scaffold/skills/adr-skill/scripts/bootstrap_adr.js`,`scaffold/skills/adr-skill/scripts/new_adr.js`,`scaffold/skills/adr-skill/scripts/set_adr_status.js`]},"c4-architecture":{description:`C4 model architecture diagrams using Mermaid — system context, container, component, and deployment views`,source:`scaffold/skills/c4-architecture/SKILL.md`,required:!0,sidecars:[`scaffold/skills/c4-architecture/references/advanced-patterns.md`,`scaffold/skills/c4-architecture/references/c4-syntax.md`,`scaffold/skills/c4-architecture/references/common-mistakes.md`]},"frontend-design":{description:`Frontend design system — visual design thinking, typography, color, layout, motion, accessibility, and anti-pattern detection`,source:`scaffold/skills/frontend-design/SKILL.md`,required:!1},"lesson-learned":{description:`Extract engineering lessons from recent code changes via git history analysis`,source:`scaffold/skills/lesson-learned/SKILL.md`,required:!0,sidecars:[`scaffold/skills/lesson-learned/references/anti-patterns.md`,`scaffold/skills/lesson-learned/references/se-principles.md`]},present:{description:`Rich interactive dashboards, charts, tables, timelines, and data visualizations via the present MCP tool`,source:`scaffold/skills/present/SKILL.md`,required:!0},react:{description:`React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration`,source:`scaffold/skills/react/SKILL.md`,required:!1},"requirements-clarity":{description:`Clarify ambiguous requirements through focused dialogue — score 0-100 until ≥90 before implementation`,source:`scaffold/skills/requirements-clarity/SKILL.md`,required:!0},"session-handoff":{description:`Comprehensive handoff documents for seamless AI agent session transfers and context preservation`,source:`scaffold/skills/session-handoff/SKILL.md`,required:!0,sidecars:[`scaffold/skills/session-handoff/references/handoff-template.md`,`scaffold/skills/session-handoff/references/resume-checklist.md`,`scaffold/skills/session-handoff/scripts/check_staleness.js`,`scaffold/skills/session-handoff/scripts/create_handoff.js`,`scaffold/skills/session-handoff/scripts/list_handoffs.js`,`scaffold/skills/session-handoff/scripts/validate_handoff.js`]},typescript:{description:`TypeScript development patterns — type system, compiler config, advanced types, async patterns, module organization`,source:`scaffold/skills/typescript/SKILL.md`,required:!1},docs:{description:`Living documentation management — Diátaxis framework, docs/ convention, staleness detection, integration with adr-skill and c4-architecture`,source:`scaffold/skills/docs/SKILL.md`,required:!0},"repo-access":{description:`Progressive repository access recovery for private and enterprise git repos — strategy ladder from HTTPS to SSH to CLI OAuth to PAT to local clone`,source:`scaffold/skills/repo-access/SKILL.md`,required:!0,sidecars:[`scaffold/skills/repo-access/references/platform-matrix.md`,`scaffold/skills/repo-access/references/error-patterns.md`]},"browser-use":{description:`AI Kit owned browser runtime — zero setup authentication recovery, data extraction, form filling, and web interaction. Built-in Chromium with headless/UI/panel modes. Pairs with repo-access as final escalation for SSO/login wall recovery.`,source:`scaffold/skills/browser-use/SKILL.md`,required:!1,sidecars:[`scaffold/skills/browser-use/references/recipes.md`,`scaffold/skills/browser-use/references/auth-patterns.md`]}};export{e as PLUGINS};
+const e={aikit:{description:`AI Kit search, analysis, memory, and developer tools`,source:`scaffold/skills/aikit/SKILL.md`,required:!0},brainstorming:{description:`Brainstorming & design exploration workflow`,source:`scaffold/skills/brainstorming/SKILL.md`,required:!0,sidecars:[`scaffold/skills/brainstorming/spec-document-reviewer-prompt.md`]},"multi-agents-development":{description:`Multi-agent orchestration, task decomposition, parallel dispatch, and review pipeline patterns`,source:`scaffold/skills/multi-agents-development/SKILL.md`,required:!0,sidecars:[`scaffold/skills/multi-agents-development/implementer-prompt.md`,`scaffold/skills/multi-agents-development/spec-review-prompt.md`,`scaffold/skills/multi-agents-development/code-quality-review-prompt.md`,`scaffold/skills/multi-agents-development/architecture-review-prompt.md`,`scaffold/skills/multi-agents-development/parallel-dispatch-example.md`]},"adr-skill":{description:`Architecture Decision Records — create, maintain, and review ADRs for significant technical decisions`,source:`scaffold/skills/adr-skill/SKILL.md`,required:!0,sidecars:[`scaffold/skills/adr-skill/assets/templates/adr-madr.md`,`scaffold/skills/adr-skill/assets/templates/adr-readme.md`,`scaffold/skills/adr-skill/assets/templates/adr-simple.md`,`scaffold/skills/adr-skill/references/adr-conventions.md`,`scaffold/skills/adr-skill/references/examples.md`,`scaffold/skills/adr-skill/references/review-checklist.md`,`scaffold/skills/adr-skill/references/template-variants.md`,`scaffold/skills/adr-skill/scripts/bootstrap_adr.js`,`scaffold/skills/adr-skill/scripts/new_adr.js`,`scaffold/skills/adr-skill/scripts/set_adr_status.js`]},"c4-architecture":{description:`C4 model architecture diagrams using Mermaid — system context, container, component, and deployment views`,source:`scaffold/skills/c4-architecture/SKILL.md`,required:!0,sidecars:[`scaffold/skills/c4-architecture/references/advanced-patterns.md`,`scaffold/skills/c4-architecture/references/c4-syntax.md`,`scaffold/skills/c4-architecture/references/c4.schema.json`,`scaffold/skills/c4-architecture/references/common-mistakes.md`]},"frontend-design":{description:`Frontend design system — visual design thinking, typography, color, layout, motion, accessibility, and anti-pattern detection`,source:`scaffold/skills/frontend-design/SKILL.md`,required:!1},"lesson-learned":{description:`Extract engineering lessons from recent code changes via git history analysis`,source:`scaffold/skills/lesson-learned/SKILL.md`,required:!0,sidecars:[`scaffold/skills/lesson-learned/references/anti-patterns.md`,`scaffold/skills/lesson-learned/references/se-principles.md`]},present:{description:`Rich interactive dashboards, charts, tables, timelines, and data visualizations via the present MCP tool`,source:`scaffold/skills/present/SKILL.md`,required:!0},react:{description:`React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration`,source:`scaffold/skills/react/SKILL.md`,required:!1},"requirements-clarity":{description:`Clarify ambiguous requirements through focused dialogue — score 0-100 until ≥90 before implementation`,source:`scaffold/skills/requirements-clarity/SKILL.md`,required:!0},"session-handoff":{description:`Comprehensive handoff documents for seamless AI agent session transfers and context preservation`,source:`scaffold/skills/session-handoff/SKILL.md`,required:!0,sidecars:[`scaffold/skills/session-handoff/references/handoff-template.md`,`scaffold/skills/session-handoff/references/resume-checklist.md`,`scaffold/skills/session-handoff/scripts/check_staleness.js`,`scaffold/skills/session-handoff/scripts/create_handoff.js`,`scaffold/skills/session-handoff/scripts/list_handoffs.js`,`scaffold/skills/session-handoff/scripts/validate_handoff.js`]},typescript:{description:`TypeScript development patterns — type system, compiler config, advanced types, async patterns, module organization`,source:`scaffold/skills/typescript/SKILL.md`,required:!1},docs:{description:`Living documentation management — Diátaxis framework, docs/ convention, staleness detection, integration with adr-skill and c4-architecture`,source:`scaffold/skills/docs/SKILL.md`,required:!0},"repo-access":{description:`Progressive repository access recovery for private and enterprise git repos — strategy ladder from HTTPS to SSH to CLI OAuth to PAT to local clone`,source:`scaffold/skills/repo-access/SKILL.md`,required:!0,sidecars:[`scaffold/skills/repo-access/references/platform-matrix.md`,`scaffold/skills/repo-access/references/error-patterns.md`]},"browser-use":{description:`AI Kit owned browser runtime — zero setup authentication recovery, data extraction, form filling, and web interaction. Built-in Chromium with headless/UI/panel modes. Pairs with repo-access as final escalation for SSO/login wall recovery.`,source:`scaffold/skills/browser-use/SKILL.md`,required:!1,sidecars:[`scaffold/skills/browser-use/references/recipes.md`,`scaffold/skills/browser-use/references/auth-patterns.md`]}};export{e as PLUGINS};

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- 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` | Handle dialogs | `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` | `key` | Keyboard key (Enter, Tab, Escape) |\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## 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 |\n|--------|---------|\n| `cookies` | Export page cookies |\n| `set-cookie` | Inject cookies |\n| `delete-cookie` / `clear-cookies` | Remove cookies |\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## 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## 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├─ 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## 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- 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## 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├─ 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.
 
@@ -71,7 +71,7 @@ Step 4: Verify return to application
   Extract: session state
 
 Step 5: Export session (optional)
-  Action: browser({ action: 'session', pageId, sessionAction: 'cookies' })
+  Action: browser({ action: 'session', pageId, sessionAction: 'cookies', confirm: true })
   Verify: Got authentication cookies
   Extract: cookies for http tool usage
 ~~~
@@ -255,7 +255,7 @@ Browser-based authentication strategies for different auth mechanisms.
 
 **Steps:**
 1. Complete authentication via Pattern 1 or 2
-2. \`session({ sessionAction: 'cookies' })\` — export all cookies
+2. \`session({ sessionAction: 'cookies', confirm: true })\` — export all cookies
 3. Use cookies in \`http\` tool: \`http({ url, headers: { Cookie: '<exported>' } })\`
 
 **Alternative (Recommended):** Use \`browser({ action: 'fetch', pageId, fetchUrl: '<api-endpoint>' })\` instead of extracting cookies. The \`fetch\` action executes HTTP requests directly in the page context, automatically using the page's cookies, session, and CSRF tokens. No cookie extraction or manual header management needed.

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

@@ -1497,7 +1497,7 @@ Before finalizing any C4 diagram, verify:
 - [ ] Message topics shown individually (not as single broker)
 - [ ] No infrastructure details in container diagrams
 - [ ] Consistent with other diagrams in the set
-`},{file:`references/html-design-system.md`,content:'# HTML/SVG Architecture Diagram Design System\n\nThis file is the centralized design system for HTML and SVG architecture diagrams.\n\nIt is the single source of truth for visual tokens, component categories, layout rules, and `present` tool composition guidance used by the `c4-architecture` skill and the `present` skill. Update component types, colors, layout rules, and icon slots here only.\n\n## Purpose\n\n- Define a reusable visual language for C4-style architecture diagrams rendered as HTML and inline SVG.\n- Keep category styling extensible through a registry instead of hardcoded component types.\n- Standardize diagram composition for both skill-authored documentation and `present` output.\n\n## Core Design Tokens\n\n### Typography\n\n- Font family: `"JetBrains Mono", monospace`\n- Font source: Google Fonts (`https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700;800&display=swap`)\n- Component names: `12px`\n- Sublabels: `9px`\n- Annotations: `8px`\n- Tiny labels: `7px`\n- Legend: `10px`\n- Icon area labels: `11px`\n\n### Background\n\n- Page background: `#020617` (`slate-950`)\n- Background pattern: inline SVG grid pattern over the page background\n- Recommended grid line colors:\n  - Major grid: `rgba(148, 163, 184, 0.08)`\n  - Minor grid: `rgba(148, 163, 184, 0.04)`\n\n### Component Box Defaults\n\n- Shape: rounded rectangle\n- Border radius: `rx="6"`\n- Stroke width: `1.5px`\n- Fill: category-specific semi-transparent RGBA fill\n- Stroke: category-specific hex stroke\n- Label stack:\n  - Line 1: C4 label such as `<<Container>>`\n  - Line 2: component name\n  - Line 3: subtype or technology summary\n\n## Category Registry\n\nThe registry is hierarchical: categories define shared tokens and C4 intent, while sub-types inherit the category styling and reserve an icon slot for future SVG glyphs.\n\n| Category | Stroke Color | Fill Color | C4 Mapping | Sub-types |\n|---|---|---|---|---|\n| Frontend | `#22d3ee` | `rgba(8, 51, 68, 0.4)` | Container (SPA, web) | SPA, Mobile App, Static Site, Micro-frontend, PWA, Desktop App |\n| Backend | `#34d399` | `rgba(6, 78, 59, 0.4)` | Container (service) | API Service, Worker/Job, BFF, Microservice, Serverless Function, gRPC Service |\n| Data | `#a78bfa` | `rgba(76, 29, 149, 0.4)` | ContainerDb | Relational DB, Document DB, Key-Value Store, Cache, Search Engine, Data Warehouse, Graph DB, Time-Series DB |\n| Infrastructure | `#fbbf24` | `rgba(120, 53, 15, 0.3)` | Deployment_Node | CDN, Load Balancer, DNS, Object Storage, Container Registry, Reverse Proxy, Service Mesh |\n| Messaging | `#fb923c` | `rgba(251, 146, 60, 0.3)` | ContainerQueue | Message Queue, Event Bus, Stream, Pub/Sub, Webhook |\n| Security | `#fb7185` | `rgba(136, 19, 55, 0.4)` | System_Ext / boundary | Auth Provider, API Gateway, WAF, Secret Manager, Certificate Manager, Identity Provider |\n| External | `#94a3b8` | `rgba(30, 41, 59, 0.5)` | System_Ext | Third-party API, SaaS, Legacy System, Partner Service, Payment Provider |\n| Monitoring | `#38bdf8` | `rgba(12, 74, 110, 0.4)` | Container | Logging, Metrics, Tracing, Alerting, APM |\n\n## Sub-type Registry\n\nEach sub-type inherits its category tokens and keeps a placeholder slot for an inline SVG icon.\n\n| Category | Sub-type | C4 Label | Icon Slot |\n|---|---|---|---|\n| Frontend | SPA | `<<Container>>` | `icon-spa` |\n| Frontend | Mobile App | `<<Container>>` | `icon-mobile-app` |\n| Frontend | Static Site | `<<Container>>` | `icon-static-site` |\n| Frontend | Micro-frontend | `<<Container>>` | `icon-micro-frontend` |\n| Frontend | PWA | `<<Container>>` | `icon-pwa` |\n| Frontend | Desktop App | `<<Container>>` | `icon-desktop-app` |\n| Backend | API Service | `<<Container>>` | `icon-api-service` |\n| Backend | Worker/Job | `<<Container>>` | `icon-worker-job` |\n| Backend | BFF | `<<Container>>` | `icon-bff` |\n| Backend | Microservice | `<<Container>>` | `icon-microservice` |\n| Backend | Serverless Function | `<<Container>>` | `icon-serverless-function` |\n| Backend | gRPC Service | `<<Container>>` | `icon-grpc-service` |\n| Data | Relational DB | `<<ContainerDb>>` | `icon-relational-db` |\n| Data | Document DB | `<<ContainerDb>>` | `icon-document-db` |\n| Data | Key-Value Store | `<<ContainerDb>>` | `icon-key-value-store` |\n| Data | Cache | `<<ContainerDb>>` | `icon-cache` |\n| Data | Search Engine | `<<ContainerDb>>` | `icon-search-engine` |\n| Data | Data Warehouse | `<<ContainerDb>>` | `icon-data-warehouse` |\n| Data | Graph DB | `<<ContainerDb>>` | `icon-graph-db` |\n| Data | Time-Series DB | `<<ContainerDb>>` | `icon-time-series-db` |\n| Infrastructure | CDN | `<<Deployment_Node>>` | `icon-cdn` |\n| Infrastructure | Load Balancer | `<<Deployment_Node>>` | `icon-load-balancer` |\n| Infrastructure | DNS | `<<Deployment_Node>>` | `icon-dns` |\n| Infrastructure | Object Storage | `<<Deployment_Node>>` | `icon-object-storage` |\n| Infrastructure | Container Registry | `<<Deployment_Node>>` | `icon-container-registry` |\n| Infrastructure | Reverse Proxy | `<<Deployment_Node>>` | `icon-reverse-proxy` |\n| Infrastructure | Service Mesh | `<<Deployment_Node>>` | `icon-service-mesh` |\n| Messaging | Message Queue | `<<ContainerQueue>>` | `icon-message-queue` |\n| Messaging | Event Bus | `<<ContainerQueue>>` | `icon-event-bus` |\n| Messaging | Stream | `<<ContainerQueue>>` | `icon-stream` |\n| Messaging | Pub/Sub | `<<ContainerQueue>>` | `icon-pub-sub` |\n| Messaging | Webhook | `<<ContainerQueue>>` | `icon-webhook` |\n| Security | Auth Provider | `<<System_Ext>>` | `icon-auth-provider` |\n| Security | API Gateway | `<<System_Ext>>` | `icon-api-gateway` |\n| Security | WAF | `<<System_Ext>>` | `icon-waf` |\n| Security | Secret Manager | `<<System_Ext>>` | `icon-secret-manager` |\n| Security | Certificate Manager | `<<System_Ext>>` | `icon-certificate-manager` |\n| Security | Identity Provider | `<<System_Ext>>` | `icon-identity-provider` |\n| External | Third-party API | `<<System_Ext>>` | `icon-third-party-api` |\n| External | SaaS | `<<System_Ext>>` | `icon-saas` |\n| External | Legacy System | `<<System_Ext>>` | `icon-legacy-system` |\n| External | Partner Service | `<<System_Ext>>` | `icon-partner-service` |\n| External | Payment Provider | `<<System_Ext>>` | `icon-payment-provider` |\n| Monitoring | Logging | `<<Container>>` | `icon-logging` |\n| Monitoring | Metrics | `<<Container>>` | `icon-metrics` |\n| Monitoring | Tracing | `<<Container>>` | `icon-tracing` |\n| Monitoring | Alerting | `<<Container>>` | `icon-alerting` |\n| Monitoring | APM | `<<Container>>` | `icon-apm` |\n\n## Icon Registry\n\nIcons are inline SVG `<symbol>` elements with a 16x16 viewBox, rendered via `<use>` at `(x+W-22, y+4)` inside the component box. They use `currentColor` to inherit the category stroke color.\n\n### Category-Level Icons (active)\n\nEach category has a shared icon defined in `html-template.html` `<defs>`. All sub-types within a category use their category icon by default. Sub-type-specific icons can override these in the future.\n\n| Category | Symbol ID | Shape | Status |\n|---|---|---|---|\n| Frontend | `icon-frontend` | Monitor with stand | **active** |\n| Backend | `icon-backend` | Server rack (3 units) | **active** |\n| Data | `icon-data` | Database cylinder | **active** |\n| Infrastructure | `icon-infrastructure` | Cloud | **active** |\n| Messaging | `icon-messaging` | Envelope | **active** |\n| Security | `icon-security` | Shield with checkmark | **active** |\n| External | `icon-external` | Globe with meridians | **active** |\n| Monitoring | `icon-monitoring` | Line chart with axes | **active** |\n\nUsage pattern:\n```svg\n<use href="#icon-frontend" class="icon-use" x="448" y="154" width="16" height="16"/>\n```\n\n### Sub-type Icons (planned)\n\nWhen a sub-type icon is added, it overrides the category icon for that specific component. Until implemented, all sub-types use their category icon.\n\n| Sub-type | Icon | Status |\n|---|---|---|\n| SPA | `icon-spa` | planned |\n| Mobile App | `icon-mobile-app` | planned |\n| Static Site | `icon-static-site` | planned |\n| Micro-frontend | `icon-micro-frontend` | planned |\n| PWA | `icon-pwa` | planned |\n| Desktop App | `icon-desktop-app` | planned |\n| API Service | `icon-api-service` | planned |\n| Worker/Job | `icon-worker-job` | planned |\n| BFF | `icon-bff` | planned |\n| Microservice | `icon-microservice` | planned |\n| Serverless Function | `icon-serverless-function` | planned |\n| gRPC Service | `icon-grpc-service` | planned |\n| Relational DB | `icon-relational-db` | planned |\n| Document DB | `icon-document-db` | planned |\n| Key-Value Store | `icon-key-value-store` | planned |\n| Cache | `icon-cache` | planned |\n| Search Engine | `icon-search-engine` | planned |\n| Data Warehouse | `icon-data-warehouse` | planned |\n| Graph DB | `icon-graph-db` | planned |\n| Time-Series DB | `icon-time-series-db` | planned |\n| CDN | `icon-cdn` | planned |\n| Load Balancer | `icon-load-balancer` | planned |\n| DNS | `icon-dns` | planned |\n| Object Storage | `icon-object-storage` | planned |\n| Container Registry | `icon-container-registry` | planned |\n| Reverse Proxy | `icon-reverse-proxy` | planned |\n| Service Mesh | `icon-service-mesh` | planned |\n| Message Queue | `icon-message-queue` | planned |\n| Event Bus | `icon-event-bus` | planned |\n| Stream | `icon-stream` | planned |\n| Pub/Sub | `icon-pub-sub` | planned |\n| Webhook | `icon-webhook` | planned |\n| Auth Provider | `icon-auth-provider` | planned |\n| API Gateway | `icon-api-gateway` | planned |\n| WAF | `icon-waf` | planned |\n| Secret Manager | `icon-secret-manager` | planned |\n| Certificate Manager | `icon-certificate-manager` | planned |\n| Identity Provider | `icon-identity-provider` | planned |\n| Third-party API | `icon-third-party-api` | planned |\n| SaaS | `icon-saas` | planned |\n| Legacy System | `icon-legacy-system` | planned |\n| Partner Service | `icon-partner-service` | planned |\n| Payment Provider | `icon-payment-provider` | planned |\n| Logging | `icon-logging` | planned |\n| Metrics | `icon-metrics` | planned |\n| Tracing | `icon-tracing` | planned |\n| Alerting | `icon-alerting` | planned |\n| APM | `icon-apm` | planned |\n\n## Visual Elements\n\n### Component Box Pattern\n\nUse a rounded component box with semi-transparent fill and category stroke.\n\n```svg\n<g class="node backend">\n  <rect x="280" y="210" width="190" height="60" rx="6" />\n  <text class="c4-tag" x="294" y="226">&lt;&lt;Container&gt;&gt;</text>\n  <text class="node-title" x="294" y="243">API Service</text>\n  <text class="node-subtitle" x="294" y="257">Backend / HTTPS JSON</text>\n</g>\n```\n\n### Arrow Masking Technique\n\nUse an opaque background rectangle below the box content to visually hide arrows beneath components without breaking the component fill style.\n\n```svg\n<g class="node-mask-layer">\n  <rect x="280" y="210" width="190" height="60" rx="6" fill="#020617" />\n  <rect x="280" y="210" width="190" height="60" rx="6"\n        fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1.5" />\n</g>\n```\n\n### Security Group Boundary\n\n- Purpose: show auth, gateway, WAF, or identity zones\n- Stroke color: rose (`#fb7185`)\n- Pattern: `stroke-dasharray="4,4"`\n- Suggested label: `Security Boundary`\n\n```svg\n<rect x="700" y="140" width="220" height="180" rx="12"\n      fill="transparent" stroke="#fb7185" stroke-width="1.5"\n      stroke-dasharray="4,4" />\n```\n\n### Region Boundary\n\n- Purpose: group a deployment region, platform segment, or domain slice\n- Stroke color: amber (`#fbbf24`)\n- Pattern: `stroke-dasharray="8,4"`\n- Radius: `rx="12"`\n\n```svg\n<rect x="70" y="120" width="600" height="430" rx="12"\n      fill="transparent" stroke="#fbbf24" stroke-width="1.5"\n      stroke-dasharray="8,4" />\n```\n\n### Arrow Marker SVG Definition\n\n```svg\n<defs>\n  <marker id="arrowhead" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">\n    <path d="M0,0 L8,4 L0,8 Z" fill="#cbd5e1" />\n  </marker>\n</defs>\n```\n\n### Arrow Z-order Rule\n\nDraw arrows early in the SVG so component boxes and masking layers paint over them. This keeps connectors readable in dense diagrams and avoids arrow overlap across component interiors.\n\n## Spacing Rules\n\n- Standard component height: `60px`\n- Minimum vertical gap between stacked components: `40px`\n- Inline connectors should route through gaps rather than through component interiors\n- Keep labels inside the top `28px` of the box and the subtype line inside the lower third\n- Place legends outside boundaries to prevent classification noise inside the diagram area\n\n## Layout Structure\n\nThe canonical page composition is:\n\n1. Header: title, pulse dot, subtitle\n2. Main SVG diagram: embedded inside a rounded border card\n3. Summary cards: grid of 3 cards beneath the diagram\n4. Footer metadata: generator, scope, rendering notes, last-updated stamp\n\n## Present Tool Integration\n\nCompose architecture diagrams with the `present` tool by embedding the full HTML/SVG diagram in a markdown block and pairing it with metrics or cards blocks as needed.\n\n### `format: "html"`\n\nUse a `markdown` block with embedded `<div>`, inline SVG, and a `<style>` tag containing the full CSS. The `present` html format renders raw HTML in markdown blocks.\n\n### `format: "browser"`\n\nUse the same composition: a `markdown` block containing the full HTML structure. Summary content can also be added with `cards` and `metrics` blocks alongside the SVG diagram block.\n\n### Example `present` Call Structure\n\n```js\npresent({\n  format: "html", // or "browser"\n  title: "System Architecture",\n  content: [\n    {\n      type: "metrics",\n      title: "Overview",\n      value: [\n        { label: "Services", value: "6" },\n        { label: "Data Stores", value: "2" },\n        { label: "External Systems", value: "3" }\n      ]\n    },\n    {\n      type: "markdown",\n      title: "Architecture Diagram",\n      value: "<div class=\'arch-diagram\'>...(inline SVG)...</div><style>...(design system CSS)...</style>"\n    },\n    {\n      type: "cards",\n      title: "Summary",\n      value: [\n        { title: "Frontend", body: "React SPA..." },\n        { title: "Backend", body: "API + async workers..." },\n        { title: "Security", body: "Gateway + IdP..." }\n      ]\n    }\n  ]\n})\n```\n\nThis design system is the single source of truth. The `c4-architecture` skill and `present` skill both reference this file. Update component types, colors, or layout rules here only.\n\n## Adding New Categories\n\n1. Add a new row to the Category Registry with the category name, colors, C4 mapping, and initial subtype set.\n2. Add the new sub-types to the Sub-type Registry with a C4 label and icon slot name.\n3. Add icon placeholders to the Icon Registry.\n4. Update [html-template.html](html-template.html) legend content so the new category appears in the rendered template.\n5. Update summary card accent colors in [html-template.html](html-template.html) if the new category needs a dedicated card treatment.\n\n## Template Pairing\n\nSee [html-template.html](html-template.html) for the complete self-contained reference implementation of this design system.\n'},{file:`SKILL.md`,content:`---
+`},{file:`references/html-design-system.md`,content:'# HTML/SVG Architecture Diagram Design System\n\nThis file is the centralized design system for HTML and SVG architecture diagrams.\n\nIt is the single source of truth for visual tokens, component categories, layout rules, and `present` tool composition guidance used by the `c4-architecture` skill and the `present` skill. Update component types, colors, layout rules, and icon slots here only.\n\n## Purpose\n\n- Define a reusable visual language for C4-style architecture diagrams rendered as HTML and inline SVG.\n- Keep category styling extensible through a registry instead of hardcoded component types.\n- Standardize diagram composition for both skill-authored documentation and `present` output.\n\n## Core Design Tokens\n\n### Typography\n\n- Font family: `"JetBrains Mono", monospace`\n- Font source: Google Fonts (`https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700;800&display=swap`)\n- Component names: `12px`\n- Sublabels: `9px`\n- Annotations: `8px`\n- Tiny labels: `7px`\n- Legend: `10px`\n- Icon area labels: `11px`\n\n### Background\n\n- Page background: `#020617` (`slate-950`)\n- Background pattern: inline SVG grid pattern over the page background\n- Recommended grid line colors:\n  - Major grid: `rgba(148, 163, 184, 0.08)`\n  - Minor grid: `rgba(148, 163, 184, 0.04)`\n\n### Component Box Defaults\n\n- Shape: rounded rectangle\n- Border radius: `rx="6"`\n- Stroke width: `1.5px`\n- Fill: category-specific semi-transparent RGBA fill\n- Stroke: category-specific hex stroke\n- Label stack:\n  - Line 1: C4 label such as `<<Container>>`\n  - Line 2: component name\n  - Line 3: subtype or technology summary\n\n## Category Registry\n\nThe registry is hierarchical: categories define shared tokens and C4 intent, while sub-types inherit the category styling and reserve an icon slot for future SVG glyphs.\n\n| Category | Stroke Color | Fill Color | C4 Mapping | Sub-types |\n|---|---|---|---|---|\n| Frontend | `#22d3ee` | `rgba(8, 51, 68, 0.4)` | Container (SPA, web) | SPA, Mobile App, Static Site, Micro-frontend, PWA, Desktop App |\n| Backend | `#34d399` | `rgba(6, 78, 59, 0.4)` | Container (service) | API Service, Worker/Job, BFF, Microservice, Serverless Function, gRPC Service |\n| Data | `#a78bfa` | `rgba(76, 29, 149, 0.4)` | ContainerDb | Relational DB, Document DB, Key-Value Store, Cache, Search Engine, Data Warehouse, Graph DB, Time-Series DB |\n| Infrastructure | `#fbbf24` | `rgba(120, 53, 15, 0.3)` | Deployment_Node | CDN, Load Balancer, DNS, Object Storage, Container Registry, Reverse Proxy, Service Mesh |\n| Messaging | `#fb923c` | `rgba(251, 146, 60, 0.3)` | ContainerQueue | Message Queue, Event Bus, Stream, Pub/Sub, Webhook |\n| Security | `#fb7185` | `rgba(136, 19, 55, 0.4)` | System_Ext / boundary | Auth Provider, API Gateway, WAF, Secret Manager, Certificate Manager, Identity Provider |\n| External | `#94a3b8` | `rgba(30, 41, 59, 0.5)` | System_Ext | Third-party API, SaaS, Legacy System, Partner Service, Payment Provider |\n| Monitoring | `#38bdf8` | `rgba(12, 74, 110, 0.4)` | Container | Logging, Metrics, Tracing, Alerting, APM |\n\n## Sub-type Registry\n\nEach sub-type inherits its category tokens and keeps a placeholder slot for an inline SVG icon.\n\n| Category | Sub-type | C4 Label | Icon Slot |\n|---|---|---|---|\n| Frontend | SPA | `<<Container>>` | `icon-spa` |\n| Frontend | Mobile App | `<<Container>>` | `icon-mobile-app` |\n| Frontend | Static Site | `<<Container>>` | `icon-static-site` |\n| Frontend | Micro-frontend | `<<Container>>` | `icon-micro-frontend` |\n| Frontend | PWA | `<<Container>>` | `icon-pwa` |\n| Frontend | Desktop App | `<<Container>>` | `icon-desktop-app` |\n| Backend | API Service | `<<Container>>` | `icon-api-service` |\n| Backend | Worker/Job | `<<Container>>` | `icon-worker-job` |\n| Backend | BFF | `<<Container>>` | `icon-bff` |\n| Backend | Microservice | `<<Container>>` | `icon-microservice` |\n| Backend | Serverless Function | `<<Container>>` | `icon-serverless-function` |\n| Backend | gRPC Service | `<<Container>>` | `icon-grpc-service` |\n| Data | Relational DB | `<<ContainerDb>>` | `icon-relational-db` |\n| Data | Document DB | `<<ContainerDb>>` | `icon-document-db` |\n| Data | Key-Value Store | `<<ContainerDb>>` | `icon-key-value-store` |\n| Data | Cache | `<<ContainerDb>>` | `icon-cache` |\n| Data | Search Engine | `<<ContainerDb>>` | `icon-search-engine` |\n| Data | Data Warehouse | `<<ContainerDb>>` | `icon-data-warehouse` |\n| Data | Graph DB | `<<ContainerDb>>` | `icon-graph-db` |\n| Data | Time-Series DB | `<<ContainerDb>>` | `icon-time-series-db` |\n| Infrastructure | CDN | `<<Deployment_Node>>` | `icon-cdn` |\n| Infrastructure | Load Balancer | `<<Deployment_Node>>` | `icon-load-balancer` |\n| Infrastructure | DNS | `<<Deployment_Node>>` | `icon-dns` |\n| Infrastructure | Object Storage | `<<Deployment_Node>>` | `icon-object-storage` |\n| Infrastructure | Container Registry | `<<Deployment_Node>>` | `icon-container-registry` |\n| Infrastructure | Reverse Proxy | `<<Deployment_Node>>` | `icon-reverse-proxy` |\n| Infrastructure | Service Mesh | `<<Deployment_Node>>` | `icon-service-mesh` |\n| Messaging | Message Queue | `<<ContainerQueue>>` | `icon-message-queue` |\n| Messaging | Event Bus | `<<ContainerQueue>>` | `icon-event-bus` |\n| Messaging | Stream | `<<ContainerQueue>>` | `icon-stream` |\n| Messaging | Pub/Sub | `<<ContainerQueue>>` | `icon-pub-sub` |\n| Messaging | Webhook | `<<ContainerQueue>>` | `icon-webhook` |\n| Security | Auth Provider | `<<System_Ext>>` | `icon-auth-provider` |\n| Security | API Gateway | `<<System_Ext>>` | `icon-api-gateway` |\n| Security | WAF | `<<System_Ext>>` | `icon-waf` |\n| Security | Secret Manager | `<<System_Ext>>` | `icon-secret-manager` |\n| Security | Certificate Manager | `<<System_Ext>>` | `icon-certificate-manager` |\n| Security | Identity Provider | `<<System_Ext>>` | `icon-identity-provider` |\n| External | Third-party API | `<<System_Ext>>` | `icon-third-party-api` |\n| External | SaaS | `<<System_Ext>>` | `icon-saas` |\n| External | Legacy System | `<<System_Ext>>` | `icon-legacy-system` |\n| External | Partner Service | `<<System_Ext>>` | `icon-partner-service` |\n| External | Payment Provider | `<<System_Ext>>` | `icon-payment-provider` |\n| Monitoring | Logging | `<<Container>>` | `icon-logging` |\n| Monitoring | Metrics | `<<Container>>` | `icon-metrics` |\n| Monitoring | Tracing | `<<Container>>` | `icon-tracing` |\n| Monitoring | Alerting | `<<Container>>` | `icon-alerting` |\n| Monitoring | APM | `<<Container>>` | `icon-apm` |\n\n## Icon Registry\n\nIcons are inline SVG `<symbol>` elements with a 16x16 viewBox, rendered via `<use>` at `(x+W-22, y+4)` inside the component box. They use `currentColor` to inherit the category stroke color.\n\n### Category-Level Icons (active)\n\nEach category has a shared icon defined in `html-template.html` `<defs>`. All sub-types within a category use their category icon by default. Sub-type-specific icons can override these in the future.\n\n| Category | Symbol ID | Shape | Status |\n|---|---|---|---|\n| Frontend | `icon-frontend` | Monitor with stand | **active** |\n| Backend | `icon-backend` | Server rack (3 units) | **active** |\n| Data | `icon-data` | Database cylinder | **active** |\n| Infrastructure | `icon-infrastructure` | Cloud | **active** |\n| Messaging | `icon-messaging` | Envelope | **active** |\n| Security | `icon-security` | Shield with checkmark | **active** |\n| External | `icon-external` | Globe with meridians | **active** |\n| Monitoring | `icon-monitoring` | Line chart with axes | **active** |\n\nUsage pattern:\n```svg\n<use href="#icon-frontend" class="icon-use" x="448" y="154" width="16" height="16"/>\n```\n\n### Sub-type Icons (planned)\n\nWhen a sub-type icon is added, it overrides the category icon for that specific component. Until implemented, all sub-types use their category icon.\n\n| Sub-type | Icon | Status |\n|---|---|---|\n| SPA | `icon-spa` | planned |\n| Mobile App | `icon-mobile-app` | planned |\n| Static Site | `icon-static-site` | planned |\n| Micro-frontend | `icon-micro-frontend` | planned |\n| PWA | `icon-pwa` | planned |\n| Desktop App | `icon-desktop-app` | planned |\n| API Service | `icon-api-service` | planned |\n| Worker/Job | `icon-worker-job` | planned |\n| BFF | `icon-bff` | planned |\n| Microservice | `icon-microservice` | planned |\n| Serverless Function | `icon-serverless-function` | planned |\n| gRPC Service | `icon-grpc-service` | planned |\n| Relational DB | `icon-relational-db` | planned |\n| Document DB | `icon-document-db` | planned |\n| Key-Value Store | `icon-key-value-store` | planned |\n| Cache | `icon-cache` | planned |\n| Search Engine | `icon-search-engine` | planned |\n| Data Warehouse | `icon-data-warehouse` | planned |\n| Graph DB | `icon-graph-db` | planned |\n| Time-Series DB | `icon-time-series-db` | planned |\n| CDN | `icon-cdn` | planned |\n| Load Balancer | `icon-load-balancer` | planned |\n| DNS | `icon-dns` | planned |\n| Object Storage | `icon-object-storage` | planned |\n| Container Registry | `icon-container-registry` | planned |\n| Reverse Proxy | `icon-reverse-proxy` | planned |\n| Service Mesh | `icon-service-mesh` | planned |\n| Message Queue | `icon-message-queue` | planned |\n| Event Bus | `icon-event-bus` | planned |\n| Stream | `icon-stream` | planned |\n| Pub/Sub | `icon-pub-sub` | planned |\n| Webhook | `icon-webhook` | planned |\n| Auth Provider | `icon-auth-provider` | planned |\n| API Gateway | `icon-api-gateway` | planned |\n| WAF | `icon-waf` | planned |\n| Secret Manager | `icon-secret-manager` | planned |\n| Certificate Manager | `icon-certificate-manager` | planned |\n| Identity Provider | `icon-identity-provider` | planned |\n| Third-party API | `icon-third-party-api` | planned |\n| SaaS | `icon-saas` | planned |\n| Legacy System | `icon-legacy-system` | planned |\n| Partner Service | `icon-partner-service` | planned |\n| Payment Provider | `icon-payment-provider` | planned |\n| Logging | `icon-logging` | planned |\n| Metrics | `icon-metrics` | planned |\n| Tracing | `icon-tracing` | planned |\n| Alerting | `icon-alerting` | planned |\n| APM | `icon-apm` | planned |\n\n## Visual Elements\n\n### Component Box Pattern\n\nUse a rounded component box with semi-transparent fill and category stroke.\n\n```svg\n<g class="node backend">\n  <rect x="280" y="210" width="190" height="60" rx="6" />\n  <text class="c4-tag" x="294" y="226">&lt;&lt;Container&gt;&gt;</text>\n  <text class="node-title" x="294" y="243">API Service</text>\n  <text class="node-subtitle" x="294" y="257">Backend / HTTPS JSON</text>\n</g>\n```\n\n### Arrow Masking Technique\n\nUse an opaque background rectangle below the box content to visually hide arrows beneath components without breaking the component fill style.\n\n```svg\n<g class="node-mask-layer">\n  <rect x="280" y="210" width="190" height="60" rx="6" fill="#020617" />\n  <rect x="280" y="210" width="190" height="60" rx="6"\n        fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1.5" />\n</g>\n```\n\n### Security Group Boundary\n\n- Purpose: show auth, gateway, WAF, or identity zones\n- Stroke color: rose (`#fb7185`)\n- Pattern: `stroke-dasharray="4,4"`\n- Suggested label: `Security Boundary`\n\n```svg\n<rect x="700" y="140" width="220" height="180" rx="12"\n      fill="transparent" stroke="#fb7185" stroke-width="1.5"\n      stroke-dasharray="4,4" />\n```\n\n### Region Boundary\n\n- Purpose: group a deployment region, platform segment, or domain slice\n- Stroke color: amber (`#fbbf24`)\n- Pattern: `stroke-dasharray="8,4"`\n- Radius: `rx="12"`\n\n```svg\n<rect x="70" y="120" width="600" height="430" rx="12"\n      fill="transparent" stroke="#fbbf24" stroke-width="1.5"\n      stroke-dasharray="8,4" />\n```\n\n### Arrow Marker SVG Definition\n\n```svg\n<defs>\n  <marker id="arrowhead" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">\n    <path d="M0,0 L8,4 L0,8 Z" fill="#cbd5e1" />\n  </marker>\n</defs>\n```\n\n### Arrow Z-order Rule\n\nDraw arrows early in the SVG so component boxes and masking layers paint over them. This keeps connectors readable in dense diagrams and avoids arrow overlap across component interiors.\n\n## Spacing Rules\n\n- Standard component height: `60px`\n- Minimum vertical gap between stacked components: `40px`\n- Inline connectors should route through gaps rather than through component interiors\n- Keep labels inside the top `28px` of the box and the subtype line inside the lower third\n- Place legends outside boundaries to prevent classification noise inside the diagram area\n\n## Layout Structure\n\nThe canonical page composition is:\n\n1. Header: title, pulse dot, subtitle\n2. Main SVG diagram: embedded inside a rounded border card\n3. Summary cards: grid of 3 cards beneath the diagram\n4. Footer metadata: generator, scope, rendering notes, last-updated stamp\n\n## Present Tool Integration\n\nCompose architecture diagrams with the `present` tool by embedding the full HTML/SVG diagram in a markdown block and pairing it with metrics or cards blocks as needed.\n\n### `format: "html"`\n\nUse a `markdown` block with embedded `<div>`, inline SVG, and a `<style>` tag containing the full CSS. The `present` html format renders raw HTML in markdown blocks.\n\n### `format: "browser"`\n\nUse the same composition: a `markdown` block containing the full HTML structure. Summary content can also be added with `cards` and `metrics` blocks alongside the SVG diagram block.\n\n### Example `present` Call Structure\n\n```js\npresent({\n  format: "html", // or "browser"\n  title: "System Architecture",\n  content: [\n    {\n      type: "metrics",\n      title: "Overview",\n      value: [\n        { label: "Services", value: "6" },\n        { label: "Data Stores", value: "2" },\n        { label: "External Systems", value: "3" }\n      ]\n    },\n    {\n      type: "markdown",\n      title: "Architecture Diagram",\n      value: "<div class=\'arch-diagram\'>...(inline SVG)...</div><style>...(design system CSS)...</style>"\n    },\n    {\n      type: "cards",\n      title: "Summary",\n      value: [\n        { title: "Frontend", body: "React SPA..." },\n        { title: "Backend", body: "API + async workers..." },\n        { title: "Security", body: "Gateway + IdP..." }\n      ]\n    }\n  ]\n})\n```\n\nThis design system is the single source of truth. The `c4-architecture` skill and `present` skill both reference this file. Update component types, colors, or layout rules here only.\n\n## Adding New Categories\n\n1. Add a new row to the Category Registry with the category name, colors, C4 mapping, and initial subtype set.\n2. Add the new sub-types to the Sub-type Registry with a C4 label and icon slot name.\n3. Add icon placeholders to the Icon Registry.\n4. Update [html-template.html](html-template.html) legend content so the new category appears in the rendered template.\n5. Update summary card accent colors in [html-template.html](html-template.html) if the new category needs a dedicated card treatment.\n\n## Template Pairing\n\nSee [html-template.html](html-template.html) for the complete self-contained reference implementation of this design system.\n'},{file:`references/c4.schema.json`,content:JSON.stringify({$schema:`http://json-schema.org/draft-07/schema#`,title:`AIKIT Architecture Diagram`,description:`Schema for AI Kit C4 interactive architecture diagrams. The agent generates JSON matching this schema, which is injected into c4-viewer.html.`,version:`1.0.0`,type:`object`,required:[`title`,`type`,`nodes`,`edges`],properties:{title:{type:`string`,description:`Diagram title displayed in the viewer header`},description:{type:`string`,description:`Brief diagram description`},type:{type:`string`,enum:[`context`,`container`,`component`,`deployment`],description:`C4 diagram level`},layout:{type:`object`,properties:{direction:{type:`string`,enum:[`TB`,`LR`,`BT`,`RL`],default:`TB`},spacing:{type:`number`,default:80},layerSpacing:{type:`number`,default:120}}},nodes:{type:`array`,items:{type:`object`,required:[`id`,`type`,`label`],properties:{id:{type:`string`,description:`Unique node identifier`},type:{type:`string`,enum:[`person`,`system`,`container`,`component`,`database`,`queue`,`external`,`boundary`,`deploymentNode`],description:`C4 element type - determines visual styling`},label:{type:`string`,description:`Display label`},technology:{type:`string`,description:`Technology tag (e.g., 'React', 'PostgreSQL')`},description:{type:`string`,description:`Element description shown on hover/expand`},children:{type:`array`,items:{type:`string`},description:`Child node IDs (for boundary/group nodes only)`},x:{type:`number`,description:`Optional fixed x position`},y:{type:`number`,description:`Optional fixed y position`}}}},edges:{type:`array`,items:{type:`object`,required:[`source`,`target`],properties:{id:{type:`string`,description:`Optional edge identifier`},source:{type:`string`,description:`Source node ID`},target:{type:`string`,description:`Target node ID`},label:{type:`string`,description:`Relationship label`},technology:{type:`string`,description:`Protocol/technology (e.g., 'REST/HTTPS')`},style:{type:`string`,enum:[`solid`,`dashed`,`dotted`],default:`solid`},animated:{type:`boolean`,default:!1,description:`Animate the edge (for async/event flows)`}}}}}},null,2)},{file:`SKILL.md`,content:`---
 name: c4-architecture
 description: "Generate architecture documentation using C4 model diagrams. Supports two output formats: Mermaid (md) for documentation and HTML/SVG for presentations. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams."
 metadata:
@@ -1977,11 +1977,11 @@ Write architecture documentation to \`docs/architecture/\` with naming conventio
 
 ## Interactive Architecture Diagrams (Data-Driven Viewer)
 
-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 data matching the schema below. **NEVER generate HTML for architecture diagrams** — inject JSON into the shipped viewer.
+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.
 
 ### Usage
 
-1. Generate JSON matching the schema below
+1. Generate JSON matching [references/c4.schema.json](references/c4.schema.json)
 2. Copy the shipped viewer from \`assets/c4-viewer.html\`
 3. Inject the JSON into the \`<script type="application/json" id="diagram-data">\` block
 4. Save to \`docs/architecture/interactive/{name}.html\`
@@ -2006,37 +2006,42 @@ present({
 });
 \`\`\`
 
-### JSON Schema
+### C4 Viewer Data Format
 
 \`\`\`json
 {
-  "title": "System Name — C4 Container Diagram",
-  "description": "Optional diagram description",
-  "layout": {
-    "direction": "DOWN",
-    "spacing": 80,
-    "layerSpacing": 100
-  },
+  "title": "System Context",
+  "type": "context",
   "nodes": [
     {
-      "id": "unique-id",
-      "type": "person | system | container | component | database | queue | external | boundary",
-      "label": "Display Name",
-      "technology": "[Optional] e.g. TypeScript, PostgreSQL",
-      "description": "[Optional] Brief description of responsibility"
+      "id": "user",
+      "type": "person",
+      "label": "User"
+    },
+    {
+      "id": "sys",
+      "type": "system",
+      "label": "My System",
+      "technology": "Node.js"
     }
   ],
   "edges": [
     {
-      "source": "source-node-id",
-      "target": "target-node-id",
-      "label": "[Optional] Relationship description",
-      "style": "solid | dashed | dotted"
+      "source": "user",
+      "target": "sys",
+      "label": "Uses",
+      "technology": "HTTPS"
     }
   ]
 }
 \`\`\`
 
+The viewer expects a JSON object matching [references/c4.schema.json](references/c4.schema.json).
+
+**Node types:** person, system, container, component, database, queue, external, boundary, deploymentNode
+
+See the full schema for all properties, layout options, and node type details.
+
 ### Node Types & Rendering
 
 | Type | SVG Icon | Background | Border | Use For |