@vpxa/aikit 0.1.151 → 0.1.153

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

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

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

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

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

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

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

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

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

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