@vpxa/aikit 0.1.351 → 0.1.352

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

@@ -27,12 +27,16 @@ Always include schemaVersion: 1 and title. Use concise description when helpful.
 ## Selection Guide
 
 | Need | Shape |
-|---|---|
+|---|---|---|
 | Summary/report | report template or heading + markdown/table |
 | Plan/progress | task-plan/checklist/status-board |
 | Metrics/trends | metrics + chart |
 | Compare options | table + kv + recommendation |
-| Review/approval | review template + approval action |
+| Review/approval | review template + approval action, or code-review@1 viewer for per-file diffs |
+| Code review (per-file) | code-review@1 viewer — diff grid + risk map + review bubbles + annotations |
+| Architecture diagram | c4@1 / c4-static@1 viewers |
+| Process diagram | process-flow@1 / process-flow-static@1 viewers |
+| Guided tour | tour@1 viewer |
 | Logs/errors | code/error block |
 | Choice | actions select/confirm/button |
 
@@ -55,8 +59,28 @@ Always include schemaVersion: 1 and title. Use concise description when helpful.
 - Use \`preferBrowser: true\` when user explicitly requests "open in browser", "external window", or "browser transport"
 - Templates \`c4@1\`, \`tour@1\`, \`process-flow@1\` are browser-only (interactive) — always open in browser
 - Templates \`c4-static@1\`, \`task-plan-static@1\`, \`process-flow-static@1\` are mcp-app-only — inline by default, use \`preferBrowser\` to force browser
+- Template \`code-review@1\` supports both transports: inline for reading, browser for annotated review with actions (Approve/Request Changes). Text selection annotations auto-activate in browser transport when actions are present.
 - Block-only surfaces (no template) respond to \`preferBrowser\` as expected
 
+## Diagram Renderers vs Viewer Templates
+
+Two separate paths for diagram/visual output — choose based on use case:
+
+**Diagram renderers** (programmatic API — NOT present tool):
+- Import from \`@aikit/server/diagram\`: \`renderToResult\`, \`renderHtml\`, \`renderDiagram\`
+- 5 types: \`architecture\`, \`workflow\`, \`sequence\`, \`dataflow\`, \`lifecycle\`
+- Standalone HTML (not wrapped in present shell) — embed in docs, write to disk
+- All 5 now use warm clay/olive/gold design system, serif headings, dark/light mode, responsive
+- All 5 now support click-to-detail card interaction on SVG nodes
+- Invoke: \`renderToResult({ diagram_type: 'architecture', meta: {title}, components, connections })\`
+- Use when diagrams go to files, docs, or you don't need present tool's action/annotation system
+
+**Viewer templates** (present tool — \`present({ template: '...', data: {...} })\`):
+- 7 templates listed below — rendered inside present shell with header/footer/theme toggle
+- Support actions (approve, confirm, select) and annotation layer for code-review@1
+- Invoke: \`present({ template: 'code-review@1', data: {...}, actions: [...] })\`
+- Use when you need interactive UI, user actions, annotations, or present workflow integration
+
 ## Quality Bar
 
 - One clear title, no giant unstructured markdown dumps.
@@ -74,7 +98,7 @@ If validation fails, fix schema shape first. Use schema/preset/template resource
 
 Load on demand:
 - references/block-catalog.md — Complete 32-block type catalog with value shapes, best block for each data type, and rules.
-- references/presets-templates.md — Preset contracts (8 presets), viewer templates (6), MCP App templates (14), and error recovery patterns.
+- references/presets-templates.md — Preset contracts (8 presets), viewer templates (7), MCP App templates (14), diagram renderers (5), and error recovery patterns.
 `},{file:`references/block-catalog.md`,content:`# Block Catalog — 32 Content Blocks
 
 Pass content as blocks array of { type, title?, value } objects.
@@ -160,16 +184,296 @@ Pass content as blocks array of { type, title?, value } objects.
 
 Each preset supplies inputSchema (JSON Schema), example (JSON), and expandsTo (block description) via aikit://present/presets.
 
-## 6 Viewer Templates
-
-| Template | Transport | Purpose |
-|----------|-----------|---------|
-| c4@1 | browser | Interactive C4 architecture diagram |
-| c4-static@1 | mcp-app | Static architecture diagram |
-| process-flow@1 | browser | Interactive process flow |
-| process-flow-static@1 | mcp-app | Static process flow |
-| tour@1 | browser | Guided walkthrough |
-| task-plan-static@1 | mcp-app | Static task execution plan card layout |
+Viewer templates also supply inputSchema programmatically — query via aikit://present/templates resource or call registerViewer() definitions.
+
+## 7 Viewer Templates
+
+Viewer templates are self-contained HTML pages rendered inside the present tool shell. Each has a specific data contract. Pass as \`present({ template: '<id>', data: {...} })\`.
+
+| Template | Transport | When to use | Required fields |
+|----------|-----------|-------------|----------------|
+| c4@1 | browser | Interactive C4 architecture with zoom/pan/ELK auto-layout | nodes: [{ id, type, label }] |
+| c4-static@1 | mcp-app | Static SVG architecture diagram inline (no interaction) | nodes: [{ id, type, label }] |
+| process-flow@1 | browser | Interactive process flow with ReactFlow drag/zoom | nodes: [{ id, label }] |
+| process-flow-static@1 | mcp-app | Static SVG process flow inline | nodes: [{ id, label }] |
+| tour@1 | browser | Guided walkthrough with step nav + dependency graph | steps: [{ id, title, file?, code? }] |
+| task-plan-static@1 | mcp-app | Task execution plan with phases/batches/agents | phases: [{ id, label, batches }] |
+| code-review@1 | mcp-app, browser | Per-file diff code review with risk map, bubbles, annotations | files: [{ path }] |
+
+### c4@1 / c4-static@1 Data Contract
+
+    {
+      title: "System Context — Acme Web",
+      description: "Top-level system context diagram",
+      layout: { direction: "TB", spacing: 60, layerSpacing: 80 },
+      nodes: [
+        { id: "user", type: "person", label: "User", icon: "person" },
+        { id: "web", type: "container", label: "Web App", technology: "React",
+          description: "Single-page application" },
+        { id: "api", type: "container", label: "API Server", technology: "Hono" },
+        { id: "db", type: "database", label: "Postgres", technology: "RDS" }
+      ],
+      edges: [
+        { source: "user", target: "web", label: "browses", style: "sync" },
+        { source: "web", target: "api", label: "fetch /api", style: "sync" },
+        { source: "api", target: "db", label: "query", style: "async" }
+      ]
+    }
+
+- \`nodes[].type\`: \`person\` | \`system\` | \`container\` | \`component\` | \`database\` | \`queue\` | \`external\` | \`boundary\`
+- \`edges[].style\`: \`sync\` | \`async\` | \`dashed\` | \`dotted\` | \`solid\`
+- c4@1 = interactive (browser-only), c4-static@1 = static SVG (mcp-app inline)
+
+### process-flow@1 / process-flow-static@1 Data Contract
+
+    {
+      nodes: [
+        { id: "start", label: "Start", type: "start-end" },
+        { id: "review", label: "Code Review", type: "manual",
+          description: "Peer review required before merge" },
+        { id: "deploy", label: "Deploy", type: "automated" },
+        { id: "approve?", label: "Approved?", type: "decision" }
+      ],
+      edges: [
+        { source: "start", target: "review", label: "assign" },
+        { source: "review", target: "approve?", type: "standard" },
+        { source: "approve?", target: "deploy", label: "yes", type: "standard" },
+        { source: "approve?", target: "review", label: "no", type: "loop-back" }
+      ]
+    }
+
+- \`nodes[].type\`: \`start-end\` | \`manual\` | \`automated\` | \`integration\` | \`decision\` | \`prerequisite\`
+- \`edges[].type\`: \`standard\` | \`loop-back\` | \`exception\`
+- process-flow@1 = interactive (browser), process-flow-static@1 = static SVG (mcp-app)
+
+### tour@1 Data Contract
+
+    {
+      title: "Scaffold Build Pipeline",
+      description: "How the scaffold generation pipeline works",
+      estimatedTime: "10 min",
+      steps: [
+        { stepNumber: 1, id: "intro", title: "Overview",
+          file: "scaffold/generate.mjs",
+          explanation: "The scaffold reads definitions from scaffold/definitions/...",
+          description: "Entry point for the entire pipeline",
+          learnsConcept: "pipeline architecture",
+          duration: "2 min",
+          code: "export async function generate() { ... }"
+        },
+        { stepNumber: 2, id: "definitions", title: "Source of Truth",
+          file: "scaffold/definitions/agents.mjs" }
+      ],
+      dependencies: [
+        { source: "intro", target: "definitions" }
+      ]
+    }
+
+### task-plan-static@1 Data Contract
+
+    {
+      title: "Implement Auth Module",
+      description: "Task breakdown for adding auth",
+      phases: [{
+        id: "phase-1", label: "Research",
+        outcome: "Selected auth strategy",
+        batches: [{
+          id: "batch-1", order: 1, parallel: false,
+          label: "Analyze options",
+          tasks: [{ id: "t1", title: "Compare JWT vs session",
+            agent: "Researcher-Alpha", status: "done",
+            files: ["docs/auth-comparison.md"] }]
+        }]
+      }]
+    }
+
+- \`batches[].tasks[].agent\`: any agent name (e.g. Implementer, Researcher-Alpha)
+- \`batches[].tasks[].status\`: \`pending\` | \`in-progress\` | \`done\` | \`blocked\`
+- Supports \`dependsOn\` array for task dependencies
+
+### code-review@1 Data Contract
+
+    {
+      title: "PR #247 — Add optimistic updates",
+      repo: "acme/web",
+      author: "Mira Okafor",
+      additions: 142,  deletions: 38,
+      files: [{
+        path: "src/hooks/useOptimisticTasks.ts",
+        risk: "attention",           // "safe" | "medium" | "attention"
+        collapsed: true,              // wrap in <details>
+        diff: [
+          { t: "add", n: 1,  c: "import { useMutation } from '...'" },
+          { t: "del", n: 43, c: "const [pending, setPending] = useState(null)" },
+          { t: "ctx", n: 50, c: "return <ul className='tasks'>" },
+          { t: "hunk",       c: "@@ -42,14 +42,17 @@" }
+        ],
+        comments: [
+          { line: 11, text: "Missing cancelQueries()", blocking: true }
+        ]
+      }],
+      conclusion: ["Fix the cancelQueries gap before merging."]
+    }
+
+- \`files[].risk\`: safe=green chip, medium=gold chip, attention=terracotta chip
+- \`diff[].t\`: add=green bg, del=red bg, ctx=neutral, hunk=dim header row
+- \`comments[].blocking\`: true=red left border, false=gray left border
+- Add \`actions\` array (e.g. approve, request-changes) to auto-activate browser transport + annotation layer
+- Annotations: user selects diff text -> comment popover -> stored in \`__annotationLayer\` -> bundled with action callback
+- Viewer uses warm clay/olive/gold design, serif headings, dark/light toggle, responsive layout
+
+## 5 Diagram Renderers (programmatic — NOT present tool)
+
+Diagram renderers produce standalone HTML with warm design system, dark/light mode, and click-to-detail interaction on all SVG nodes. Invoke via:
+
+    import { renderToResult, renderHtml, renderDiagram } from '@aikit/server/diagram'
+    const { html } = renderToResult({ diagram_type: 'architecture', meta: {title: '...'}, ... })
+    // or for HTML string only:
+    const html = renderHtml({ diagram_type: 'workflow', meta: {title: '...'}, ... })
+
+All renderers accept \`meta: { palette: 'warm' | 'technical', title: string, subtitle?: string }\`. Default palette is warm.
+
+### architecture Data Contract
+
+    {
+      diagram_type: 'architecture',
+      meta: { title: "System Architecture", subtitle: "High-level overview", palette: "warm" },
+      components: [
+        { id: "web", type: "frontend", label: "React SPA", sublabel: "Vite",
+          pos: { x: 40, y: 60 }, size: [140, 70] },
+        { id: "api", type: "backend", label: "API Server", sublabel: "Hono",
+          pos: { x: 240, y: 60 } },
+        { id: "db", type: "database", label: "Postgres",
+          pos: { x: 440, y: 60 } }
+      ],
+      connections: [
+        { from: "web", to: "api", label: "fetch /v1", variant: "emphasis" },
+        { from: "api", to: "db", label: "query", variant: "dashed" }
+      ],
+      boundaries: [
+        { kind: "region", label: "AWS", wraps: ["api", "db"] }
+      ],
+      cards: [{ dot: "green", title: "Key", items: ["SPA served from edge"] }]
+    }
+
+- \`components[].type\`: \`frontend\` | \`backend\` | \`database\` | \`cloud\` | \`security\` | \`messagebus\` | \`external\`
+- \`connections[].variant\`: \`default\` | \`emphasis\` | \`security\` | \`dashed\` | \`animated\`
+- \`connections[].route\`: \`straight\` | \`drop\` | \`auto\` (bent elbow)
+- Components auto-wrapped in \`<g class="node" data-k="[id]">\` for click-to-detail interaction
+
+### workflow Data Contract
+
+    {
+      diagram_type: 'workflow',
+      meta: { title: "Deploy Pipeline" },
+      lanes: [{ id: "dev", label: "Developer" }, { id: "ci", label: "CI/CD" }],
+      nodes: [
+        { id: "push", lane: "dev", col: 1, type: "frontend",
+          label: "git push", sublabel: "main branch" },
+        { id: "lint", lane: "ci", col: 2, type: "backend",
+          label: "Lint + Typecheck" },
+        { id: "test", lane: "ci", col: 3, type: "backend",
+          label: "Unit tests", tag: "3 shards" },
+        { id: "deploy", lane: "ci", col: 4, type: "cloud",
+          label: "Deploy", sublabel: "Argo" }
+      ],
+      edges: [
+        { from: "push", to: "lint", label: "trigger" },
+        { from: "lint", to: "test" },
+        { from: "test", to: "deploy", variant: "emphasis" }
+      ]
+    }
+
+- \`nodes[].col\`: 1-based column position within lane (1-6 max)
+- \`nodes[].type\`: same component types as architecture
+- Auto-wrapped in \`<g class="node" data-k="[id]">\`
+
+### sequence Data Contract
+
+    {
+      diagram_type: 'sequence',
+      meta: { title: "Auth Flow" },
+      participants: [
+        { id: "user", type: "frontend", label: "User" },
+        { id: "spa", type: "frontend", label: "SPA" },
+        { id: "api", type: "backend", label: "API" },
+        { id: "db", type: "database", label: "DB" }
+      ],
+      messages: [
+        { from: "user", to: "spa", y: 180, label: "click login", variant: "emphasis" },
+        { from: "spa", to: "api", y: 240, label: "POST /auth/login" },
+        { from: "api", to: "db", y: 300, label: "SELECT user" },
+        { from: "api", to: "spa", y: 360, label: "200 { token }", variant: "return" }
+      ],
+      activations: [
+        { participant: "api", from: 220, to: 380, type: "backend" }
+      ],
+      segments: [
+        { from: 160, to: 220, label: "User input" }
+      ]
+    }
+
+- \`messages[].y\`: absolute Y coordinate in SVG (descending = later in time)
+- \`messages[].variant\`: \`default\` | \`emphasis\` | \`security\` | \`return\` | \`dashed\`
+- Participants auto-wrapped in \`<g class="node" data-k="[id]">\`
+
+### dataflow Data Contract
+
+    {
+      diagram_type: 'dataflow',
+      meta: { title: "User Registration Flow" },
+      stages: [
+        { label: "Client" }, { label: "Edge" }, { label: "Services" }, { label: "Storage" }
+      ],
+      nodes: [
+        { id: "browser", type: "frontend", label: "Browser", stage: 0, row: 0 },
+        { id: "cdn", type: "cloud", label: "CDN", stage: 1, row: 0, tag: "cache" },
+        { id: "auth", type: "backend", label: "Auth Service", stage: 2, row: 0 },
+        { id: "db", type: "database", label: "Postgres", stage: 3, row: 0 }
+      ],
+      flows: [
+        { from: "browser", to: "cdn", label: "GET /login", classification: "public" },
+        { from: "cdn", to: "auth", label: "forward", variant: "emphasis" },
+        { from: "auth", to: "db", label: "SELECT", classification: "PII" }
+      ]
+    }
+
+- \`stages\`: vertical columns (left to right)
+- \`nodes[].stage\`: 0-based index into stages array
+- \`nodes[].row\`: vertical position within stage
+- \`flows[].classification\`: \`public\` | \`internal\` | \`PII\` (controls edge color)
+- Auto-wrapped in \`<g class="node" data-k="[id]">\`
+
+### lifecycle Data Contract
+
+    {
+      diagram_type: 'lifecycle',
+      meta: { title: "Order State Machine" },
+      lanes: [
+        { id: "phase", label: "Phase" },
+        { id: "event", label: "Event" },
+        { id: "outcome", label: "Outcome" }
+      ],
+      states: [
+        { id: "created", lane: "phase", col: 1, type: "active", label: "Created" },
+        { id: "paid", lane: "phase", col: 2, type: "active", label: "Paid", step: "1" },
+        { id: "shipped", lane: "phase", col: 3, type: "active", label: "Shipped", step: "2" },
+        { id: "delivered", lane: "outcome", col: 4, type: "success", label: "Delivered" },
+        { id: "cancelled", lane: "outcome", col: 2, type: "failure", label: "Cancelled" }
+      ],
+      transitions: [
+        { from: "created", to: "paid", label: "charge" },
+        { from: "paid", to: "shipped", label: "fulfill" },
+        { from: "paid", to: "cancelled", label: "refund", variant: "dashed" },
+        { from: "shipped", to: "delivered", label: "confirm" }
+      ]
+    }
+
+- \`states[].type\`: \`start\` | \`active\` | \`waiting\` | \`decision\` | \`success\` | \`failure\` | \`neutral\` | \`external\`
+- \`states[].col\`: 1-based column position
+- \`states[].step\`: optional step number badge
+- \`transitions[].variant\`: \`default\` | \`emphasis\` | \`dashed\` | \`security\`
+- Auto-wrapped in \`<g class="node" data-k="[id]">\`
 
 ## 14 MCP App Templates
 

package/packages/server/dist/prelude-Clxlztkk.js

@@ -1 +0,0 @@
-import{n as e,t}from"./server-Dc2XtS92.js";export{t as buildPreludeInjection,e as generatePrelude};

package/packages/server/dist/prelude-Dn7jTsqe.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{n as e,t}from"./server-Ct4BK2hi.js";export{t as buildPreludeInjection,e as generatePrelude};

package/packages/server/dist/sampling-giGWyrcO.js

@@ -1 +0,0 @@
-import{r as e}from"./server-Dc2XtS92.js";export{e as createSamplingClient};

package/packages/server/dist/sampling-nivAea83.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{r as e}from"./server-Ct4BK2hi.js";export{e as createSamplingClient};