@vpxa/aikit 0.1.58 → 0.1.60

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

@@ -1,6 +1,6 @@
 ---
 name: aikit
-description: "Use the @vpxa/aikit AI Kit MCP server for codebase search, analysis, and persistent memory. Load this skill when using aikit_search, aikit_remember, aikit_analyze_*, or any aikit_* tool. Covers all 67 MCP tools: search (hybrid/semantic/keyword), code analysis (structure, dependencies, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (auto-populated module/symbol/import graph with traversal), context management (worksets, stash, checkpoints, restore, lanes), code manipulation (rename, codemod, eval), knowledge management (remember/read/update/forget), web access (fetch, search, http), FORGE protocol (ground, classify, evidence map, stratum cards, digest), brainstorming (interactive ideation sessions), presentation (rich dashboards via present tool), onboarding (full codebase analysis in one call), and developer utilities (regex, encode, measure, changelog, schema-validate, snippet, env, time)."
+description: "Use the @vpxa/aikit AI Kit MCP server for codebase search, analysis, and persistent memory. Load this skill when using aikit_search, aikit_remember, aikit_analyze_*, or any aikit_* tool. Covers all 82 MCP tools: search (hybrid/semantic/keyword), code analysis (structure, dependencies, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (auto-populated module/symbol/import graph with traversal), context management (worksets, stash, checkpoints, restore, lanes), code manipulation (rename, codemod, eval), knowledge management (remember/read/update/forget), web access (fetch, search, http), FORGE protocol (ground, classify, evidence map, stratum cards, digest), brainstorming (interactive ideation sessions), presentation (rich dashboards via present tool), onboarding (full codebase analysis in one call), and developer utilities (regex, encode, measure, changelog, schema-validate, snippet, env, time)."
 metadata:
   category: cross-cutting
   domain: general
@@ -12,7 +12,7 @@ metadata:
 
 # @vpxa/aikit — AI Kit
 
-Local-first AI developer toolkit — 67 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, code manipulation, execution, web access, brainstorming, presentation, and developer utilities.
+Local-first AI developer toolkit — 82 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, code manipulation, execution, web access, brainstorming, presentation, and developer utilities.
 
 ## When to Use
 
@@ -37,7 +37,7 @@ Local-first AI developer toolkit — 67 MCP tools for search, analysis, context
 core → store → embeddings → chunker → indexer → analyzers → tools → server → cli → tui
 ```
 
-- **MCP server**: 67 tools + 2 resources (via `@modelcontextprotocol/sdk`)
+- **MCP server**: 82 tools + 2 resources (via `@modelcontextprotocol/sdk`)
 - **CLI**: 45 commands (thin dispatcher + 10 command groups)
 - **Search**: Hybrid vector + keyword + RRF fusion
 - **Embeddings**: ONNX local (mxbai-embed-large-v1, 1024 dimensions)
@@ -68,10 +68,11 @@ remember                                         (capture insights)
 
 ### End of Session
 ```
+session_digest({ persist: true })                              # Auto-capture session activity
 remember({ title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })
 ```
 
-## Tool Catalog (67 tools)
+## Tool Catalog (82 tools)
 
 ### Search & Discovery (8)
 | Tool | CLI | Purpose |
@@ -176,9 +177,10 @@ Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/de
 | `stratum_card` | — | Generate T1/T2 compressed context cards from files (10-100x token reduction) |
 | `digest` | — | Compress N text sources into token-budgeted summary |
 
-### System (8)
+### System (9)
 | Tool | CLI | Purpose |
 |------|-----|---------|
+| `config` | `aikit config` | View or update project configuration (kb.config.json) |
 | `status` | `aikit status` | Index statistics |
 | `reindex` | `aikit reindex` | Rebuild index |
 | `health` | `aikit health` | Project health checks (package.json, tsconfig, lockfile, circular deps) |
@@ -188,7 +190,7 @@ Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/de
 | `queue` | `aikit queue` | Task queue for sequential agent operations (create/push/next/done/fail) |
 | `replay` | `aikit replay` | View or clear the audit trail of tool invocations (action: list/clear) |
 
-### Flows (7)
+### Flows (10)
 | Tool | CLI | Purpose |
 |------|-----|---------|
 | `flow_list` | `aikit flow list` | List available flows |
@@ -198,6 +200,9 @@ Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/de
 | `flow_status` | `aikit flow status` | Check if a flow is active and view the current step |
 | `flow_read_instruction` | `aikit flow read-instruction` | Read the current step's instruction file content directly |
 | `flow_reset` | `aikit flow reset` | Clear flow state to start over |
+| `flow_add` | `aikit flow add` | Add a custom flow from a directory |
+| `flow_update` | `aikit flow update` | Update an existing custom flow |
+| `flow_remove` | `aikit flow remove` | Remove a custom flow |
 
 ### Presentation (1)
 | Tool | CLI | Purpose |
@@ -209,6 +214,18 @@ Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/de
 |------|-----|---------|
 | `brainstorm` | — | Interactive brainstorming and ideation sessions with structured output |
 
+### Meta-Tools — Tool Discovery (3)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `list_tools` | — | List all active AI Kit tools with names, titles, and categories. Accepts optional `category` filter. Use for initial tool discovery. |
+| `describe_tool` | — | Get detailed metadata for a specific tool (title, categories, annotations). Use after `list_tools` to understand a tool before calling it. |
+| `search_tools` | — | Search active tools by keyword across names, titles, and categories. Use when you know what you need but not the tool name. |
+
+### Session Management (1)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `session_digest` | — | Generate a compressed digest of session activity (replay log, stash, checkpoints). Options: `scope` (tools/stash/all), `since`, `last`, `focus`, `mode` (deterministic/sampling), `tokenBudget`, `persist`. Use at session end for handoff or mid-session to review what happened. |
+
 ## Flow System
 
 Flows are multi-step guided workflows that structure complex tasks. Each step has a skill file with detailed instructions, required artifacts, and agent assignments.
@@ -235,6 +252,14 @@ flow_status()                        # Check progress
 flow_reset()                         # Clear state, start over
 ```
 
+Custom flow lifecycle management:
+
+```text
+flow_add({ source: ".github/flows/my-flow" })
+flow_update({ name: "my-flow" })
+flow_remove({ name: "my-flow" })
+```
+
 ### Creating Custom Flows
 
 1. Create a directory under `.github/flows/<flow-name>/`
@@ -541,10 +566,46 @@ aikit reindex       # Rebuild index
   "indexing": { "chunkSize": 1500, "chunkOverlap": 200, "minChunkSize": 100, "concurrency": 5 },
   "embedding": { "model": "mixedbread-ai/mxbai-embed-large-v1", "dimensions": 1024 },
   "store": { "backend": "lancedb", "path": ".aikit-data" },
-  "curated": { "path": "curated" }
+  "curated": { "path": "curated", "adapter": "filesystem" }
+}
+```
+
+## Tool Profiles
+
+Tool profiles control which subset of the 82 tools are active. Profiles reduce token overhead by exposing only relevant tools for a given task.
+
+### Built-in Profiles
+
+| Profile | Description | Use When |
+|---------|-------------|----------|
+| `full` | All tools enabled (default) | General development, orchestration |
+| `safe` | Read-only tools — no file/state modifications | Code review, analysis, research |
+| `research` | Search, analysis, knowledge, web access | Investigation, documentation |
+| `minimal` | Essential tools only — search, check, test | Simple tasks, low-token budgets |
+| `discovery` | Full toolset + meta-tools for guided exploration | New users, onboarding, tool learning |
+
+### Activating a Profile
+
+Set `toolProfile` in `kb.config.json`:
+
+```json
+{
+  "toolProfile": "research"
 }
 ```
 
+Base tools (`status`, `config`, `guide`, `health`) are **always available** regardless of profile.
+
+### Meta-Tool Discovery Pattern (Token Cost Reduction)
+
+Instead of loading all 82 tool descriptions at session start, use the `discovery` profile:
+
+1. `list_tools()` — get a compact list of tool names + categories (~50 tokens)
+2. `search_tools({ query: "what I need" })` — find relevant tools by keyword
+3. `describe_tool({ tool_name: "specific_tool" })` — get full metadata only for tools you'll use
+
+This pattern reduces initial tool-loading cost from ~3000 tokens to ~200 tokens.
+
 ## IDE Integration
 
 ### VS Code — HTTP mode (recommended for development)
@@ -626,6 +687,9 @@ Flows are structured multi-step workflows that guide agents through complex task
 | `flow_step` | Advance: `next`, `skip`, or `redo` current step |
 | `flow_read_instruction` | Read the current step's instruction file content directly |
 | `flow_reset` | Clear flow state to start over |
+| `flow_add` | Add a custom flow from a directory |
+| `flow_update` | Update an existing custom flow |
+| `flow_remove` | Remove a custom flow |
 
 ### Flow Selection
 

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

@@ -1,6 +1,6 @@
 ---
 name: c4-architecture
-description: Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include "architecture diagram", "C4 diagram", "system context", "container diagram", "component diagram", "deployment diagram", "document architecture", "visualize architecture".
+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:
   category: cross-cutting
   domain: general
@@ -22,6 +22,56 @@ Generate software architecture documentation using C4 model diagrams in Mermaid
   > **Tip:** Use `present({ format: "html" })` to render diagrams as interactive visual output, rather than raw Mermaid code blocks. This provides a better viewing experience for stakeholders.
 4. **Document** - Write diagrams to markdown files with explanatory context
 
+## Format Selection
+
+This skill supports two output formats. Choose based on the audience and delivery method:
+
+> **Default rule:** When using the `present` tool to display architecture, **always use HTML/SVG format** (Method 2). It produces professional dark-themed diagrams with SVG icons, category colors, and summary cards. Use Mermaid only for saving to markdown docs or when the user explicitly requests it.
+
+| Format | Output | Best For | Delivery |
+|--------|--------|----------|----------|
+| **Mermaid (md)** | `.md` files with Mermaid code blocks | Developer docs, GitHub rendering, version control | Save to `docs/architecture/*.md` |
+| **HTML/SVG (html)** | Self-contained `.html` files | Stakeholder presentations, visual reviews, browser viewing | Save as `.html` or render via `present` tool |
+
+### Format Decision Tree
+
+```
+What is the goal?
+├── Save to docs / version control → Mermaid (md)
+├── Present via `present` tool → HTML/SVG (html) ← DEFAULT for present
+├── User says "Mermaid" or "markdown" → Mermaid (md)
+└── User says "show", "visualize", "present" → HTML/SVG (html)
+```
+
+### Present Tool Integration
+
+Both formats work with the `present` tool:
+
+**Mermaid format** - Use a `mermaid` content block:
+```js
+present({
+  format: "html",  // or "browser"
+  title: "System Architecture",
+  content: [
+    { type: "mermaid", title: "C4 Container Diagram", value: "C4Container\n  title Container Diagram\n  ..." }
+  ]
+})
+```
+
+**HTML/SVG format** - Use a `markdown` block with the full HTML structure. Pair with `metrics` and `cards` blocks for a complete dashboard. See [references/html-design-system.md](references/html-design-system.md#present-tool-integration) for the full composition pattern.
+
+```js
+present({
+  format: "html",  // or "browser" - both work
+  title: "System Architecture",
+  content: [
+    { type: "metrics", title: "Overview", value: [{ label: "Services", value: "6" }, ...] },
+    { type: "markdown", title: "Architecture Diagram", value: "<div class='arch-diagram'>...(inline SVG + CSS)...</div>" },
+    { type: "cards", title: "Summary", value: [{ title: "Frontend", body: "React SPA" }, ...] }
+  ]
+})
+```
+
 ## C4 Diagram Levels
 
 Select the appropriate level based on the documentation need:
@@ -129,6 +179,40 @@ C4Deployment
   Rel(api, db, "Reads/writes", "JDBC")
 ```
 
+## HTML/SVG Format
+
+For HTML/SVG output, use the design system and template from the references.
+
+The component type registry, color palette, typography, and layout rules are defined in [references/html-design-system.md](references/html-design-system.md). This is the single source of truth - update colors, types, and icons there.
+
+Copy and customize [references/html-template.html](references/html-template.html) for each diagram. The template is self-contained and opens directly in any browser.
+
+### Component Categories
+
+See the design system for the full sub-type registry and icon slots.
+
+- Frontend - stroke `#22d3ee`
+- Backend - stroke `#34d399`
+- Data - stroke `#a78bfa`
+- Infrastructure - stroke `#fbbf24`
+- Messaging - stroke `#fb923c`
+- Security - stroke `#fb7185`
+- External - stroke `#94a3b8`
+- Monitoring - stroke `#38bdf8`
+
+### Minimal Component Box Example
+
+Use the design system's inline SVG component pattern inside the HTML template's main `<svg>`:
+
+```svg
+<g class="node backend">
+  <rect x="280" y="210" width="190" height="60" rx="6" />
+  <text class="c4-tag" x="294" y="226">&lt;&lt;Container&gt;&gt;</text>
+  <text class="node-title" x="294" y="243">API Service</text>
+  <text class="node-subtitle" x="294" y="257">Backend / HTTPS JSON</text>
+</g>
+```
+
 ## Element Syntax
 
 ### People and Systems
@@ -301,3 +385,5 @@ Write architecture documentation to `docs/architecture/` with naming convention:
 - [references/c4-syntax.md](references/c4-syntax.md) - Complete Mermaid C4 syntax
 - [references/common-mistakes.md](references/common-mistakes.md) - Anti-patterns to avoid
 - [references/advanced-patterns.md](references/advanced-patterns.md) - Microservices, event-driven, deployment
+- [references/html-design-system.md](references/html-design-system.md) - Centralized HTML/SVG design system (types, colors, icons, present integration)
+- [references/html-template.html](references/html-template.html) - Self-contained HTML template for C4 diagrams

package/scaffold/general/skills/c4-architecture/references/html-design-system.md

@@ -0,0 +1,337 @@
+# HTML/SVG Architecture Diagram Design System
+
+This file is the centralized design system for HTML and SVG architecture diagrams.
+
+It 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.
+
+## Purpose
+
+- Define a reusable visual language for C4-style architecture diagrams rendered as HTML and inline SVG.
+- Keep category styling extensible through a registry instead of hardcoded component types.
+- Standardize diagram composition for both skill-authored documentation and `present` output.
+
+## Core Design Tokens
+
+### Typography
+
+- Font family: `"JetBrains Mono", monospace`
+- Font source: Google Fonts (`https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700;800&display=swap`)
+- Component names: `12px`
+- Sublabels: `9px`
+- Annotations: `8px`
+- Tiny labels: `7px`
+- Legend: `10px`
+- Icon area labels: `11px`
+
+### Background
+
+- Page background: `#020617` (`slate-950`)
+- Background pattern: inline SVG grid pattern over the page background
+- Recommended grid line colors:
+  - Major grid: `rgba(148, 163, 184, 0.08)`
+  - Minor grid: `rgba(148, 163, 184, 0.04)`
+
+### Component Box Defaults
+
+- Shape: rounded rectangle
+- Border radius: `rx="6"`
+- Stroke width: `1.5px`
+- Fill: category-specific semi-transparent RGBA fill
+- Stroke: category-specific hex stroke
+- Label stack:
+  - Line 1: C4 label such as `<<Container>>`
+  - Line 2: component name
+  - Line 3: subtype or technology summary
+
+## Category Registry
+
+The 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.
+
+| Category | Stroke Color | Fill Color | C4 Mapping | Sub-types |
+|---|---|---|---|---|
+| Frontend | `#22d3ee` | `rgba(8, 51, 68, 0.4)` | Container (SPA, web) | SPA, Mobile App, Static Site, Micro-frontend, PWA, Desktop App |
+| Backend | `#34d399` | `rgba(6, 78, 59, 0.4)` | Container (service) | API Service, Worker/Job, BFF, Microservice, Serverless Function, gRPC Service |
+| 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 |
+| Infrastructure | `#fbbf24` | `rgba(120, 53, 15, 0.3)` | Deployment_Node | CDN, Load Balancer, DNS, Object Storage, Container Registry, Reverse Proxy, Service Mesh |
+| Messaging | `#fb923c` | `rgba(251, 146, 60, 0.3)` | ContainerQueue | Message Queue, Event Bus, Stream, Pub/Sub, Webhook |
+| Security | `#fb7185` | `rgba(136, 19, 55, 0.4)` | System_Ext / boundary | Auth Provider, API Gateway, WAF, Secret Manager, Certificate Manager, Identity Provider |
+| External | `#94a3b8` | `rgba(30, 41, 59, 0.5)` | System_Ext | Third-party API, SaaS, Legacy System, Partner Service, Payment Provider |
+| Monitoring | `#38bdf8` | `rgba(12, 74, 110, 0.4)` | Container | Logging, Metrics, Tracing, Alerting, APM |
+
+## Sub-type Registry
+
+Each sub-type inherits its category tokens and keeps a placeholder slot for an inline SVG icon.
+
+| Category | Sub-type | C4 Label | Icon Slot |
+|---|---|---|---|
+| Frontend | SPA | `<<Container>>` | `icon-spa` |
+| Frontend | Mobile App | `<<Container>>` | `icon-mobile-app` |
+| Frontend | Static Site | `<<Container>>` | `icon-static-site` |
+| Frontend | Micro-frontend | `<<Container>>` | `icon-micro-frontend` |
+| Frontend | PWA | `<<Container>>` | `icon-pwa` |
+| Frontend | Desktop App | `<<Container>>` | `icon-desktop-app` |
+| Backend | API Service | `<<Container>>` | `icon-api-service` |
+| Backend | Worker/Job | `<<Container>>` | `icon-worker-job` |
+| Backend | BFF | `<<Container>>` | `icon-bff` |
+| Backend | Microservice | `<<Container>>` | `icon-microservice` |
+| Backend | Serverless Function | `<<Container>>` | `icon-serverless-function` |
+| Backend | gRPC Service | `<<Container>>` | `icon-grpc-service` |
+| Data | Relational DB | `<<ContainerDb>>` | `icon-relational-db` |
+| Data | Document DB | `<<ContainerDb>>` | `icon-document-db` |
+| Data | Key-Value Store | `<<ContainerDb>>` | `icon-key-value-store` |
+| Data | Cache | `<<ContainerDb>>` | `icon-cache` |
+| Data | Search Engine | `<<ContainerDb>>` | `icon-search-engine` |
+| Data | Data Warehouse | `<<ContainerDb>>` | `icon-data-warehouse` |
+| Data | Graph DB | `<<ContainerDb>>` | `icon-graph-db` |
+| Data | Time-Series DB | `<<ContainerDb>>` | `icon-time-series-db` |
+| Infrastructure | CDN | `<<Deployment_Node>>` | `icon-cdn` |
+| Infrastructure | Load Balancer | `<<Deployment_Node>>` | `icon-load-balancer` |
+| Infrastructure | DNS | `<<Deployment_Node>>` | `icon-dns` |
+| Infrastructure | Object Storage | `<<Deployment_Node>>` | `icon-object-storage` |
+| Infrastructure | Container Registry | `<<Deployment_Node>>` | `icon-container-registry` |
+| Infrastructure | Reverse Proxy | `<<Deployment_Node>>` | `icon-reverse-proxy` |
+| Infrastructure | Service Mesh | `<<Deployment_Node>>` | `icon-service-mesh` |
+| Messaging | Message Queue | `<<ContainerQueue>>` | `icon-message-queue` |
+| Messaging | Event Bus | `<<ContainerQueue>>` | `icon-event-bus` |
+| Messaging | Stream | `<<ContainerQueue>>` | `icon-stream` |
+| Messaging | Pub/Sub | `<<ContainerQueue>>` | `icon-pub-sub` |
+| Messaging | Webhook | `<<ContainerQueue>>` | `icon-webhook` |
+| Security | Auth Provider | `<<System_Ext>>` | `icon-auth-provider` |
+| Security | API Gateway | `<<System_Ext>>` | `icon-api-gateway` |
+| Security | WAF | `<<System_Ext>>` | `icon-waf` |
+| Security | Secret Manager | `<<System_Ext>>` | `icon-secret-manager` |
+| Security | Certificate Manager | `<<System_Ext>>` | `icon-certificate-manager` |
+| Security | Identity Provider | `<<System_Ext>>` | `icon-identity-provider` |
+| External | Third-party API | `<<System_Ext>>` | `icon-third-party-api` |
+| External | SaaS | `<<System_Ext>>` | `icon-saas` |
+| External | Legacy System | `<<System_Ext>>` | `icon-legacy-system` |
+| External | Partner Service | `<<System_Ext>>` | `icon-partner-service` |
+| External | Payment Provider | `<<System_Ext>>` | `icon-payment-provider` |
+| Monitoring | Logging | `<<Container>>` | `icon-logging` |
+| Monitoring | Metrics | `<<Container>>` | `icon-metrics` |
+| Monitoring | Tracing | `<<Container>>` | `icon-tracing` |
+| Monitoring | Alerting | `<<Container>>` | `icon-alerting` |
+| Monitoring | APM | `<<Container>>` | `icon-apm` |
+
+## Icon Registry
+
+Icons 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.
+
+### Category-Level Icons (active)
+
+Each 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.
+
+| Category | Symbol ID | Shape | Status |
+|---|---|---|---|
+| Frontend | `icon-frontend` | Monitor with stand | **active** |
+| Backend | `icon-backend` | Server rack (3 units) | **active** |
+| Data | `icon-data` | Database cylinder | **active** |
+| Infrastructure | `icon-infrastructure` | Cloud | **active** |
+| Messaging | `icon-messaging` | Envelope | **active** |
+| Security | `icon-security` | Shield with checkmark | **active** |
+| External | `icon-external` | Globe with meridians | **active** |
+| Monitoring | `icon-monitoring` | Line chart with axes | **active** |
+
+Usage pattern:
+```svg
+<use href="#icon-frontend" class="icon-use" x="448" y="154" width="16" height="16"/>
+```
+
+### Sub-type Icons (planned)
+
+When a sub-type icon is added, it overrides the category icon for that specific component. Until implemented, all sub-types use their category icon.
+
+| Sub-type | Icon | Status |
+|---|---|---|
+| SPA | `icon-spa` | planned |
+| Mobile App | `icon-mobile-app` | planned |
+| Static Site | `icon-static-site` | planned |
+| Micro-frontend | `icon-micro-frontend` | planned |
+| PWA | `icon-pwa` | planned |
+| Desktop App | `icon-desktop-app` | planned |
+| API Service | `icon-api-service` | planned |
+| Worker/Job | `icon-worker-job` | planned |
+| BFF | `icon-bff` | planned |
+| Microservice | `icon-microservice` | planned |
+| Serverless Function | `icon-serverless-function` | planned |
+| gRPC Service | `icon-grpc-service` | planned |
+| Relational DB | `icon-relational-db` | planned |
+| Document DB | `icon-document-db` | planned |
+| Key-Value Store | `icon-key-value-store` | planned |
+| Cache | `icon-cache` | planned |
+| Search Engine | `icon-search-engine` | planned |
+| Data Warehouse | `icon-data-warehouse` | planned |
+| Graph DB | `icon-graph-db` | planned |
+| Time-Series DB | `icon-time-series-db` | planned |
+| CDN | `icon-cdn` | planned |
+| Load Balancer | `icon-load-balancer` | planned |
+| DNS | `icon-dns` | planned |
+| Object Storage | `icon-object-storage` | planned |
+| Container Registry | `icon-container-registry` | planned |
+| Reverse Proxy | `icon-reverse-proxy` | planned |
+| Service Mesh | `icon-service-mesh` | planned |
+| Message Queue | `icon-message-queue` | planned |
+| Event Bus | `icon-event-bus` | planned |
+| Stream | `icon-stream` | planned |
+| Pub/Sub | `icon-pub-sub` | planned |
+| Webhook | `icon-webhook` | planned |
+| Auth Provider | `icon-auth-provider` | planned |
+| API Gateway | `icon-api-gateway` | planned |
+| WAF | `icon-waf` | planned |
+| Secret Manager | `icon-secret-manager` | planned |
+| Certificate Manager | `icon-certificate-manager` | planned |
+| Identity Provider | `icon-identity-provider` | planned |
+| Third-party API | `icon-third-party-api` | planned |
+| SaaS | `icon-saas` | planned |
+| Legacy System | `icon-legacy-system` | planned |
+| Partner Service | `icon-partner-service` | planned |
+| Payment Provider | `icon-payment-provider` | planned |
+| Logging | `icon-logging` | planned |
+| Metrics | `icon-metrics` | planned |
+| Tracing | `icon-tracing` | planned |
+| Alerting | `icon-alerting` | planned |
+| APM | `icon-apm` | planned |
+
+## Visual Elements
+
+### Component Box Pattern
+
+Use a rounded component box with semi-transparent fill and category stroke.
+
+```svg
+<g class="node backend">
+  <rect x="280" y="210" width="190" height="60" rx="6" />
+  <text class="c4-tag" x="294" y="226">&lt;&lt;Container&gt;&gt;</text>
+  <text class="node-title" x="294" y="243">API Service</text>
+  <text class="node-subtitle" x="294" y="257">Backend / HTTPS JSON</text>
+</g>
+```
+
+### Arrow Masking Technique
+
+Use an opaque background rectangle below the box content to visually hide arrows beneath components without breaking the component fill style.
+
+```svg
+<g class="node-mask-layer">
+  <rect x="280" y="210" width="190" height="60" rx="6" fill="#020617" />
+  <rect x="280" y="210" width="190" height="60" rx="6"
+        fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1.5" />
+</g>
+```
+
+### Security Group Boundary
+
+- Purpose: show auth, gateway, WAF, or identity zones
+- Stroke color: rose (`#fb7185`)
+- Pattern: `stroke-dasharray="4,4"`
+- Suggested label: `Security Boundary`
+
+```svg
+<rect x="700" y="140" width="220" height="180" rx="12"
+      fill="transparent" stroke="#fb7185" stroke-width="1.5"
+      stroke-dasharray="4,4" />
+```
+
+### Region Boundary
+
+- Purpose: group a deployment region, platform segment, or domain slice
+- Stroke color: amber (`#fbbf24`)
+- Pattern: `stroke-dasharray="8,4"`
+- Radius: `rx="12"`
+
+```svg
+<rect x="70" y="120" width="600" height="430" rx="12"
+      fill="transparent" stroke="#fbbf24" stroke-width="1.5"
+      stroke-dasharray="8,4" />
+```
+
+### Arrow Marker SVG Definition
+
+```svg
+<defs>
+  <marker id="arrowhead" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">
+    <path d="M0,0 L8,4 L0,8 Z" fill="#cbd5e1" />
+  </marker>
+</defs>
+```
+
+### Arrow Z-order Rule
+
+Draw 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.
+
+## Spacing Rules
+
+- Standard component height: `60px`
+- Minimum vertical gap between stacked components: `40px`
+- Inline connectors should route through gaps rather than through component interiors
+- Keep labels inside the top `28px` of the box and the subtype line inside the lower third
+- Place legends outside boundaries to prevent classification noise inside the diagram area
+
+## Layout Structure
+
+The canonical page composition is:
+
+1. Header: title, pulse dot, subtitle
+2. Main SVG diagram: embedded inside a rounded border card
+3. Summary cards: grid of 3 cards beneath the diagram
+4. Footer metadata: generator, scope, rendering notes, last-updated stamp
+
+## Present Tool Integration
+
+Compose 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.
+
+### `format: "html"`
+
+Use 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.
+
+### `format: "browser"`
+
+Use 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.
+
+### Example `present` Call Structure
+
+```js
+present({
+  format: "html", // or "browser"
+  title: "System Architecture",
+  content: [
+    {
+      type: "metrics",
+      title: "Overview",
+      value: [
+        { label: "Services", value: "6" },
+        { label: "Data Stores", value: "2" },
+        { label: "External Systems", value: "3" }
+      ]
+    },
+    {
+      type: "markdown",
+      title: "Architecture Diagram",
+      value: "<div class='arch-diagram'>...(inline SVG)...</div><style>...(design system CSS)...</style>"
+    },
+    {
+      type: "cards",
+      title: "Summary",
+      value: [
+        { title: "Frontend", body: "React SPA..." },
+        { title: "Backend", body: "API + async workers..." },
+        { title: "Security", body: "Gateway + IdP..." }
+      ]
+    }
+  ]
+})
+```
+
+This 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.
+
+## Adding New Categories
+
+1. Add a new row to the Category Registry with the category name, colors, C4 mapping, and initial subtype set.
+2. Add the new sub-types to the Sub-type Registry with a C4 label and icon slot name.
+3. Add icon placeholders to the Icon Registry.
+4. Update [html-template.html](html-template.html) legend content so the new category appears in the rendered template.
+5. Update summary card accent colors in [html-template.html](html-template.html) if the new category needs a dedicated card treatment.
+
+## Template Pairing
+
+See [html-template.html](html-template.html) for the complete self-contained reference implementation of this design system.