@vpxa/aikit 0.1.2 → 0.1.4

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

@@ -1,424 +1,424 @@
----
-name: present
-description: "Use the AI Kit `present` tool to display rich interactive dashboards, charts, timelines, status boards, and data visualizations in the browser or in-chat. Covers all block types, chart types, actions, composition patterns, and MCP Apps templates (list-sort, data-table, picker, flame-graph, form, timeline, kanban, tree, diff-view, dashboard). Load this skill before calling the present tool to ensure professional output."
-argument-hint: "Content to present — data, analysis results, status report, comparison, or interactive MCP App"
----
-
-# Present Tool — Rich Interactive Dashboards
-
-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.
-- **`browser`** — Serves a themed dashboard on a local URL. Best when you need **user interaction** (buttons, selections, form input). The tool blocks until the user clicks an action, then returns their selection.
-
-## Format Selection Rules (MUST FOLLOW)
-
-| Situation | Format | Why |
-|-----------|--------|-----|
-| Display-only content (tables, charts, reports, status boards) | **`html`** | No interaction needed — render in-chat |
-| Need user input back (confirmations, selections, form data) | **`browser`** | Browser supports blocking actions that return data |
-| Rich visual dashboards without interaction | **`html`** | Prefer in-chat when no response is needed |
-| User explicitly asks for browser | **`browser`** | Respect explicit preference |
-
-**Rule: If no user interaction is needed, use `format: "html"`. If you need user interaction, use `format: "browser"`.**
-
----
-
-## Browser Workflow (IMPORTANT — read carefully)
-
-When using `format: "browser"`, the tool starts a local HTTP server and returns a URL. **You MUST open the URL** so the user can see and interact with the dashboard.
-
-### Steps:
-1. Call `present` with `format: "browser"` and `actions` — it returns text containing `🌐 **Dashboard opened in browser:** http://127.0.0.1:{port}`
-2. **Extract the URL from the response**
-3. **Call `openBrowserPage({ url: "http://127.0.0.1:{port}" })` to open it in VS Code's Simple Browser**
-
-```
-// Step 1: Call present
-result = present({ format: "browser", title: "...", content: [...], actions: [...] })
-
-// Step 2: MUST open in VS Code Simple Browser
-openBrowserPage({ url: "http://127.0.0.1:{port}" })
-```
-
-> **Fallback**: The server also auto-opens the system browser as a safety net. But you should ALWAYS call `openBrowserPage` yourself so the user sees it inside VS Code.
-
-**Note:** The HTTP server auto-closes after 5 minutes. Open the page promptly after receiving the URL.
-
----
-
-## Content Architecture
-
-Content is an array of **typed blocks**. Each block has `{ type, title?, value }`. All blocks compose into a single unified page — use multiple blocks for sections.
-
-### Core Block Types
-
-| Type | Value Shape | Renders As |
-|------|------------|------------|
-| `markdown` | `string` (markdown text) | Rendered HTML with full GFM support |
-| `code` | `string` (source code) | Syntax-highlighted code block |
-| `mermaid` | `string` (mermaid syntax) | Interactive diagram |
-| `table` | `Array<Record<string, unknown>>` | Sortable/filterable table |
-| `metrics` | `Array<{ label, value }>` | KPI metric cards grid |
-| `cards` | `Array<{ title, body, badge? }>` | Card grid layout |
-| `tree` | `Record<string, unknown>` | Expandable tree view |
-| `graph` | `{ nodes: [], edges: [] }` | Mermaid graph diagram |
-
-### Chart Block
-
-```json
-{
-  "type": "chart",
-  "title": "Revenue Trend",
-  "value": {
-    "chartType": "line",
-    "data": [{"month": "Jan", "revenue": 1200}, {"month": "Feb", "revenue": 1800}],
-    "xKey": "month",
-    "yKeys": ["revenue"],
-    "showLegend": true,
-    "showGrid": true,
-    "height": 300
-  }
-}
-```
-
-**Chart types:** `line`, `area`, `bar`, `horizontal-bar`, `pie`, `donut`, `sparkline`, `heatmap`
-
-### New Block Types
-
-| Type | Value Shape | Renders As |
-|------|------------|------------|
-| `timeline` | `{ items: [{ phase?, title, description?, status? }] }` | Vertical timeline with status dots (done/active/pending/error) |
-| `checklist` | `{ items: [{ label, checked?, note? }] }` | Interactive checklist with checkmarks |
-| `comparison` | `{ columns: [{ title, items: [string] }] }` | Side-by-side comparison grid |
-| `status-board` | `{ items: [{ label, status, detail? }] }` | Status indicator rows (success/warning/error/info/pending) |
-| `prompt` | `{ question, context?, placeholder? }` | Highlighted question/prompt block |
-| `progress` | `{ items: [{ label, value, max? }] }` | Progress bars with percentages |
-
----
-
-## Actions
-
-Actions are interactive buttons/selects. In `browser` mode, they render as clickable elements and the tool blocks until the user clicks, returning the selection.
-
-```json
-{
-  "actions": [
-    { "type": "button", "id": "approve", "label": "Approve", "variant": "primary" },
-    { "type": "button", "id": "reject", "label": "Reject", "variant": "danger" },
-    { "type": "select", "id": "priority", "label": "Priority", "options": ["Low", "Medium", "High"] }
-  ]
-}
-```
-
-**Variants:** `primary` (indigo), `danger` (red), `default` (neutral)
-
----
-
-## Composition Pattern
-
-Compose a full dashboard by combining multiple blocks in the `content` array:
-
-```json
-{
-  "format": "browser",
-  "title": "Sprint Review",
-  "content": [
-    { "type": "metrics", "title": "Key Metrics", "value": [...] },
-    { "type": "chart", "title": "Velocity", "value": { "chartType": "area", ... } },
-    { "type": "timeline", "title": "Milestones", "value": { "items": [...] } },
-    { "type": "status-board", "title": "Service Health", "value": { "items": [...] } },
-    { "type": "table", "title": "Tasks", "value": [...] },
-    { "type": "markdown", "value": "## Notes\n\nAdditional context..." }
-  ],
-  "actions": [
-    { "type": "button", "id": "next-sprint", "label": "Plan Next Sprint", "variant": "primary" }
-  ]
-}
-```
-
----
-
-## Design System
-
-The dashboard uses a professional dark theme:
-- **Font:** Plus Jakarta Sans (body), JetBrains Mono (code)
-- **Colors:** Deep navy background (`#182030`), indigo primary (`#818cf8`), no gradients
-- **12 chart colors** for multi-series data
-- **Status colors:** green (success), amber (warning), red (error), sky (info)
-- Clean borders, subtle hover states, no visual noise
-
----
-
-## Best Practices
-
-1. **Use `browser` format** for data-rich content — charts, tables, dashboards
-2. **Combine block types** — metrics + charts + tables in one page
-3. **Add titles** to every block for clear section headings
-4. **Use actions** when you need user decisions — the tool returns the selection
-5. **Keep markdown blocks** for narrative context between data sections
-6. **Chart tips:**
-   - Use `area` for trends over time
-   - Use `bar` for comparisons between categories
-   - Use `donut` for proportions/distributions
-   - Use `sparkline` inline with metrics for mini trends
-7. **Table auto-features:** Tables with 5+ rows get automatic search/filter. Columns are sortable by click.
-
----
-
-## MCP Apps Templates (VS Code Chat Widgets)
-
-When `chat.mcp.apps.enabled` is true in VS Code settings, the `present` tool can render **interactive widgets directly in the chat panel** using the `template` parameter. These are distinct from the browser/html dashboard modes.
-
-**Key difference:** Templates use `template` + object `content` (not array of blocks). No `format` parameter needed. The widget renders inline in VS Code chat. User interactions (reorder, select, submit) are returned to the LLM as structured data.
-
-### When to use MCP Apps vs Browser Dashboard
-
-| Use Case | Mode | Why |
-|----------|------|-----|
-| Quick user input (pick items, reorder, fill form) | **MCP App template** | Inline in chat, no context switch |
-| Rich multi-section dashboard with charts | **browser** | Full page layout with all block types |
-| Simple confirmation or selection | **Actions** (browser/html) | Buttons/selects in dashboard |
-
-### Template: `list-sort`
-
-Drag-and-drop reorderable list. Use for priority ordering, task sequencing, or ranked preferences.
-
-```json
-{
-  "template": "list-sort",
-  "title": "Priority Order",
-  "content": {
-    "items": [
-      { "id": "task-1", "label": "Fix authentication bug" },
-      { "id": "task-2", "label": "Add search feature" },
-      { "id": "task-3", "label": "Update documentation" }
-    ]
-  }
-}
-```
-
-**Content schema:** `{ items: Array<{ id: string, label: string }> }`
-**Returns:** Reordered array of items after user drags to reorder and submits.
-
-### Template: `data-table`
-
-Filterable, sortable table with optional summary stat cards. Use for structured data review, change summaries, or audit results.
-
-```json
-{
-  "template": "data-table",
-  "title": "File Changes",
-  "content": {
-    "columns": [
-      { "key": "file", "label": "File" },
-      { "key": "change", "label": "Change" },
-      { "key": "lines", "label": "Lines" }
-    ],
-    "rows": [
-      { "file": "auth.ts", "change": "Added guard", "lines": 5 },
-      { "file": "cache.ts", "change": "Fixed bug", "lines": 12 }
-    ],
-    "stats": [
-      { "label": "Files Changed", "value": "2" },
-      { "label": "Total Lines", "value": "17" }
-    ]
-  }
-}
-```
-
-**Content schema:** `{ columns: Array<{ key: string, label: string }>, rows: Array<Record<string, unknown>>, stats?: Array<{ label: string, value: string }> }`
-**Returns:** Selected row(s) data when user interacts and submits.
-
-### Template: `picker`
-
-Multi-select with categories and tag-based search. Use for component selection, feature toggles, or module picking.
-
-```json
-{
-  "template": "picker",
-  "title": "Select Modules",
-  "content": {
-    "categories": [
-      { "id": "core", "label": "Core" },
-      { "id": "plugins", "label": "Plugins" }
-    ],
-    "items": [
-      { "id": "auth", "label": "Authentication", "category": "core", "tags": ["security"] },
-      { "id": "cache", "label": "Cache Layer", "category": "core", "tags": ["performance"] },
-      { "id": "sentry", "label": "Sentry Plugin", "category": "plugins", "tags": ["monitoring"] }
-    ]
-  }
-}
-```
-
-**Content schema:** `{ categories: Array<{ id: string, label: string }>, items: Array<{ id: string, label: string, category: string, tags?: string[] }> }`
-**Returns:** Array of selected item IDs after user checks items and submits.
-
-### Template: `flame-graph`
-
-Hierarchical zoomable visualization. Use for codebase structure, performance profiles, dependency trees, or budget breakdowns.
-
-```json
-{
-  "template": "flame-graph",
-  "title": "Module Hierarchy",
-  "content": {
-    "profile": {
-      "name": "root",
-      "total": 100,
-      "children": [
-        {
-          "name": "packages/tools",
-          "total": 60,
-          "children": [
-            { "name": "search.ts", "total": 35 },
-            { "name": "compact.ts", "total": 25 }
-          ]
-        },
-        { "name": "packages/server", "total": 40 }
-      ]
-    }
-  }
-}
-```
-
-**Content schema:** `{ profile: { name: string, total: number, children?: Array<(recursive)> } }`
-**Returns:** Clicked node information when user interacts.
-
-### Template: `form`
-
-Input fields with text inputs, selects, and checkboxes. Use for configuration, parameter collection, or setup wizards.
-
-```json
-{
-  "template": "form",
-  "title": "Project Configuration",
-  "content": {
-    "fields": [
-      { "name": "projectName", "label": "Project Name", "type": "text", "value": "my-app" },
-      { "name": "framework", "label": "Framework", "type": "select", "options": ["React", "Vue", "Svelte"], "value": "React" },
-      { "name": "typescript", "label": "Use TypeScript", "type": "checkbox", "value": true },
-      { "name": "description", "label": "Description", "type": "text", "value": "" }
-    ]
-  }
-}
-```
-
-**Content schema:** `{ fields: Array<{ name: string, label: string, type: "text" | "select" | "checkbox", value?: string | boolean, options?: string[] }> }`
-**Returns:** Object with field name-value pairs after user fills out and submits.
-
-### MCP Apps Best Practices
-
-1. **Use meaningful `id` values** — they are returned in responses and used for programmatic handling.
-2. **Keep list-sort items under 15** — longer lists become unwieldy for drag-and-drop.
-3. **Always provide `value` defaults** in forms — pre-fill with sensible defaults to reduce user effort.
-4. **Use `tags` in picker** — they power the search/filter functionality.
-5. **Flame-graph `total` values** should be consistent — parent total should equal sum of children.
-6. **Data-table `stats`** are optional — use them for KPI summary cards above the table.
-7. **Combine with LLM logic** — use returned values to drive next steps (e.g., form → generate config, picker → scope analysis).
-
-#### 6. `timeline` — Vertical Event Timeline (display only)
-
-```json
-{
-  "events": [
-    {"title": "v1.0 Release", "description": "Initial release with core features", "timestamp": "2025-01", "status": "complete"},
-    {"title": "v2.0 Beta", "description": "MCP Apps support", "timestamp": "2025-07", "status": "active"},
-    {"title": "v3.0 Planning", "status": "pending"}
-  ]
-}
-```
-
-Fields: `title` (required), `description?`, `timestamp?`, `status?` (`'complete'|'active'|'pending'|'error'`), `icon?`, `category?`
-
-#### 7. `kanban` — Drag-Drop Board (interactive — emits on card move)
-
-```json
-{
-  "columns": [
-    {"id": "todo", "label": "To Do"},
-    {"id": "in-progress", "label": "In Progress", "color": "#3b82f6"},
-    {"id": "done", "label": "Done", "color": "#22c55e"}
-  ],
-  "cards": [
-    {"id": "c1", "title": "Fix auth bug", "column": "todo", "tags": ["bugfix"], "priority": "high"},
-    {"id": "c2", "title": "Add search", "column": "in-progress", "tags": ["feature"], "priority": "medium"}
-  ]
-}
-```
-
-Returns `{cardId, fromColumn, toColumn}` when a card is dragged between columns.
-
-#### 8. `tree` — Collapsible Tree View (display only)
-
-```json
-{
-  "root": {
-    "label": "packages/",
-    "children": [
-      {"label": "server/", "children": [{"label": "index.ts"}, {"label": "tools/", "children": [{"label": "present.ts"}]}]},
-      {"label": "present/", "children": [{"label": "present-app.ts"}]}
-    ]
-  }
-}
-```
-
-Fields: `label` (required), `id?`, `icon?`, `children?: TreeNode[]`, `metadata?: Record<string,string>`. Accepts `root` as single node or array of nodes.
-
-#### 9. `diff-view` — Side-by-Side Code Diff (display only)
-
-```json
-{
-  "files": [{
-    "path": "auth.ts",
-    "status": "modified",
-    "additions": 12,
-    "deletions": 3,
-    "hunks": [{
-      "header": "@@ -10,5 +10,14 @@",
-      "changes": [
-        {"type": "context", "content": "const auth = {};"},
-        {"type": "delete", "content": "// old validation"},
-        {"type": "add", "content": "// new JWT validation"},
-        {"type": "add", "content": "const token = verify(jwt);"}
-      ]
-    }]
-  }],
-  "stats": {"additions": 12, "deletions": 3, "filesChanged": 1}
-}
-```
-
-Status values: `'added'|'modified'|'deleted'|'renamed'`. Change types: `'add'|'delete'|'context'`.
-
-#### 10. `dashboard` — Metric Cards Grid (display only)
-
-```json
-{
-  "metrics": [
-    {"label": "Uptime", "value": "99.9%", "status": "success", "trend": {"value": "+0.1%", "direction": "up"}},
-    {"label": "Build Time", "value": "4.2s", "type": "progress", "progress": 42, "status": "warning"},
-    {"label": "Top Endpoints", "type": "list", "value": "3", "items": [
-      {"label": "/api/search", "value": "1.2k/day"},
-      {"label": "/api/present", "value": "890/day"}
-    ]}
-  ]
-}
-```
-
-Metric types: `'stat'` (default), `'progress'` (with bar), `'list'` (sub-items). Status: `'success'|'warning'|'error'|'info'`.
-
-### Interaction Summary (All 10 Templates)
-
-| Template | Trigger | Data Returned to LLM |
-|----------|---------|---------------------|
-| list-sort | Auto on drag-drop | Reordered ID array |
-| data-table | Export button | Current filtered rows |
-| picker | Apply Selection button | Selected ID array |
-| flame-graph | Auto on node click | Clicked node object |
-| form | Submit button | Field values object |
-| kanban | Auto on card drag | `{cardId, fromColumn, toColumn}` |
-| timeline | Display only | — |
-| tree | Display only | — |
-| diff-view | Display only | — |
-| dashboard | Display only | — |
+---
+name: present
+description: "Use the AI Kit `present` tool to display rich interactive dashboards, charts, timelines, status boards, and data visualizations in the browser or in-chat. Covers all block types, chart types, actions, composition patterns, and MCP Apps templates (list-sort, data-table, picker, flame-graph, form, timeline, kanban, tree, diff-view, dashboard). Load this skill before calling the present tool to ensure professional output."
+argument-hint: "Content to present — data, analysis results, status report, comparison, or interactive MCP App"
+---
+
+# Present Tool — Rich Interactive Dashboards
+
+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.
+- **`browser`** — Serves a themed dashboard on a local URL. Best when you need **user interaction** (buttons, selections, form input). The tool blocks until the user clicks an action, then returns their selection.
+
+## Format Selection Rules (MUST FOLLOW)
+
+| Situation | Format | Why |
+|-----------|--------|-----|
+| Display-only content (tables, charts, reports, status boards) | **`html`** | No interaction needed — render in-chat |
+| Need user input back (confirmations, selections, form data) | **`browser`** | Browser supports blocking actions that return data |
+| Rich visual dashboards without interaction | **`html`** | Prefer in-chat when no response is needed |
+| User explicitly asks for browser | **`browser`** | Respect explicit preference |
+
+**Rule: If no user interaction is needed, use `format: "html"`. If you need user interaction, use `format: "browser"`.**
+
+---
+
+## Browser Workflow (IMPORTANT — read carefully)
+
+When using `format: "browser"`, the tool starts a local HTTP server and returns a URL. **You MUST open the URL** so the user can see and interact with the dashboard.
+
+### Steps:
+1. Call `present` with `format: "browser"` and `actions` — it returns text containing `🌐 **Dashboard opened in browser:** http://127.0.0.1:{port}`
+2. **Extract the URL from the response**
+3. **Call `openBrowserPage({ url: "http://127.0.0.1:{port}" })` to open it in VS Code's Simple Browser**
+
+```
+// Step 1: Call present
+result = present({ format: "browser", title: "...", content: [...], actions: [...] })
+
+// Step 2: MUST open in VS Code Simple Browser
+openBrowserPage({ url: "http://127.0.0.1:{port}" })
+```
+
+> **Fallback**: The server also auto-opens the system browser as a safety net. But you should ALWAYS call `openBrowserPage` yourself so the user sees it inside VS Code.
+
+**Note:** The HTTP server auto-closes after 5 minutes. Open the page promptly after receiving the URL.
+
+---
+
+## Content Architecture
+
+Content is an array of **typed blocks**. Each block has `{ type, title?, value }`. All blocks compose into a single unified page — use multiple blocks for sections.
+
+### Core Block Types
+
+| Type | Value Shape | Renders As |
+|------|------------|------------|
+| `markdown` | `string` (markdown text) | Rendered HTML with full GFM support |
+| `code` | `string` (source code) | Syntax-highlighted code block |
+| `mermaid` | `string` (mermaid syntax) | Interactive diagram |
+| `table` | `Array<Record<string, unknown>>` | Sortable/filterable table |
+| `metrics` | `Array<{ label, value }>` | KPI metric cards grid |
+| `cards` | `Array<{ title, body, badge? }>` | Card grid layout |
+| `tree` | `Record<string, unknown>` | Expandable tree view |
+| `graph` | `{ nodes: [], edges: [] }` | Mermaid graph diagram |
+
+### Chart Block
+
+```json
+{
+  "type": "chart",
+  "title": "Revenue Trend",
+  "value": {
+    "chartType": "line",
+    "data": [{"month": "Jan", "revenue": 1200}, {"month": "Feb", "revenue": 1800}],
+    "xKey": "month",
+    "yKeys": ["revenue"],
+    "showLegend": true,
+    "showGrid": true,
+    "height": 300
+  }
+}
+```
+
+**Chart types:** `line`, `area`, `bar`, `horizontal-bar`, `pie`, `donut`, `sparkline`, `heatmap`
+
+### New Block Types
+
+| Type | Value Shape | Renders As |
+|------|------------|------------|
+| `timeline` | `{ items: [{ phase?, title, description?, status? }] }` | Vertical timeline with status dots (done/active/pending/error) |
+| `checklist` | `{ items: [{ label, checked?, note? }] }` | Interactive checklist with checkmarks |
+| `comparison` | `{ columns: [{ title, items: [string] }] }` | Side-by-side comparison grid |
+| `status-board` | `{ items: [{ label, status, detail? }] }` | Status indicator rows (success/warning/error/info/pending) |
+| `prompt` | `{ question, context?, placeholder? }` | Highlighted question/prompt block |
+| `progress` | `{ items: [{ label, value, max? }] }` | Progress bars with percentages |
+
+---
+
+## Actions
+
+Actions are interactive buttons/selects. In `browser` mode, they render as clickable elements and the tool blocks until the user clicks, returning the selection.
+
+```json
+{
+  "actions": [
+    { "type": "button", "id": "approve", "label": "Approve", "variant": "primary" },
+    { "type": "button", "id": "reject", "label": "Reject", "variant": "danger" },
+    { "type": "select", "id": "priority", "label": "Priority", "options": ["Low", "Medium", "High"] }
+  ]
+}
+```
+
+**Variants:** `primary` (indigo), `danger` (red), `default` (neutral)
+
+---
+
+## Composition Pattern
+
+Compose a full dashboard by combining multiple blocks in the `content` array:
+
+```json
+{
+  "format": "browser",
+  "title": "Sprint Review",
+  "content": [
+    { "type": "metrics", "title": "Key Metrics", "value": [...] },
+    { "type": "chart", "title": "Velocity", "value": { "chartType": "area", ... } },
+    { "type": "timeline", "title": "Milestones", "value": { "items": [...] } },
+    { "type": "status-board", "title": "Service Health", "value": { "items": [...] } },
+    { "type": "table", "title": "Tasks", "value": [...] },
+    { "type": "markdown", "value": "## Notes\n\nAdditional context..." }
+  ],
+  "actions": [
+    { "type": "button", "id": "next-sprint", "label": "Plan Next Sprint", "variant": "primary" }
+  ]
+}
+```
+
+---
+
+## Design System
+
+The dashboard uses a professional dark theme:
+- **Font:** Plus Jakarta Sans (body), JetBrains Mono (code)
+- **Colors:** Deep navy background (`#182030`), indigo primary (`#818cf8`), no gradients
+- **12 chart colors** for multi-series data
+- **Status colors:** green (success), amber (warning), red (error), sky (info)
+- Clean borders, subtle hover states, no visual noise
+
+---
+
+## Best Practices
+
+1. **Use `browser` format** for data-rich content — charts, tables, dashboards
+2. **Combine block types** — metrics + charts + tables in one page
+3. **Add titles** to every block for clear section headings
+4. **Use actions** when you need user decisions — the tool returns the selection
+5. **Keep markdown blocks** for narrative context between data sections
+6. **Chart tips:**
+   - Use `area` for trends over time
+   - Use `bar` for comparisons between categories
+   - Use `donut` for proportions/distributions
+   - Use `sparkline` inline with metrics for mini trends
+7. **Table auto-features:** Tables with 5+ rows get automatic search/filter. Columns are sortable by click.
+
+---
+
+## MCP Apps Templates (VS Code Chat Widgets)
+
+When `chat.mcp.apps.enabled` is true in VS Code settings, the `present` tool can render **interactive widgets directly in the chat panel** using the `template` parameter. These are distinct from the browser/html dashboard modes.
+
+**Key difference:** Templates use `template` + object `content` (not array of blocks). No `format` parameter needed. The widget renders inline in VS Code chat. User interactions (reorder, select, submit) are returned to the LLM as structured data.
+
+### When to use MCP Apps vs Browser Dashboard
+
+| Use Case | Mode | Why |
+|----------|------|-----|
+| Quick user input (pick items, reorder, fill form) | **MCP App template** | Inline in chat, no context switch |
+| Rich multi-section dashboard with charts | **browser** | Full page layout with all block types |
+| Simple confirmation or selection | **Actions** (browser/html) | Buttons/selects in dashboard |
+
+### Template: `list-sort`
+
+Drag-and-drop reorderable list. Use for priority ordering, task sequencing, or ranked preferences.
+
+```json
+{
+  "template": "list-sort",
+  "title": "Priority Order",
+  "content": {
+    "items": [
+      { "id": "task-1", "label": "Fix authentication bug" },
+      { "id": "task-2", "label": "Add search feature" },
+      { "id": "task-3", "label": "Update documentation" }
+    ]
+  }
+}
+```
+
+**Content schema:** `{ items: Array<{ id: string, label: string }> }`
+**Returns:** Reordered array of items after user drags to reorder and submits.
+
+### Template: `data-table`
+
+Filterable, sortable table with optional summary stat cards. Use for structured data review, change summaries, or audit results.
+
+```json
+{
+  "template": "data-table",
+  "title": "File Changes",
+  "content": {
+    "columns": [
+      { "key": "file", "label": "File" },
+      { "key": "change", "label": "Change" },
+      { "key": "lines", "label": "Lines" }
+    ],
+    "rows": [
+      { "file": "auth.ts", "change": "Added guard", "lines": 5 },
+      { "file": "cache.ts", "change": "Fixed bug", "lines": 12 }
+    ],
+    "stats": [
+      { "label": "Files Changed", "value": "2" },
+      { "label": "Total Lines", "value": "17" }
+    ]
+  }
+}
+```
+
+**Content schema:** `{ columns: Array<{ key: string, label: string }>, rows: Array<Record<string, unknown>>, stats?: Array<{ label: string, value: string }> }`
+**Returns:** Selected row(s) data when user interacts and submits.
+
+### Template: `picker`
+
+Multi-select with categories and tag-based search. Use for component selection, feature toggles, or module picking.
+
+```json
+{
+  "template": "picker",
+  "title": "Select Modules",
+  "content": {
+    "categories": [
+      { "id": "core", "label": "Core" },
+      { "id": "plugins", "label": "Plugins" }
+    ],
+    "items": [
+      { "id": "auth", "label": "Authentication", "category": "core", "tags": ["security"] },
+      { "id": "cache", "label": "Cache Layer", "category": "core", "tags": ["performance"] },
+      { "id": "sentry", "label": "Sentry Plugin", "category": "plugins", "tags": ["monitoring"] }
+    ]
+  }
+}
+```
+
+**Content schema:** `{ categories: Array<{ id: string, label: string }>, items: Array<{ id: string, label: string, category: string, tags?: string[] }> }`
+**Returns:** Array of selected item IDs after user checks items and submits.
+
+### Template: `flame-graph`
+
+Hierarchical zoomable visualization. Use for codebase structure, performance profiles, dependency trees, or budget breakdowns.
+
+```json
+{
+  "template": "flame-graph",
+  "title": "Module Hierarchy",
+  "content": {
+    "profile": {
+      "name": "root",
+      "total": 100,
+      "children": [
+        {
+          "name": "packages/tools",
+          "total": 60,
+          "children": [
+            { "name": "search.ts", "total": 35 },
+            { "name": "compact.ts", "total": 25 }
+          ]
+        },
+        { "name": "packages/server", "total": 40 }
+      ]
+    }
+  }
+}
+```
+
+**Content schema:** `{ profile: { name: string, total: number, children?: Array<(recursive)> } }`
+**Returns:** Clicked node information when user interacts.
+
+### Template: `form`
+
+Input fields with text inputs, selects, and checkboxes. Use for configuration, parameter collection, or setup wizards.
+
+```json
+{
+  "template": "form",
+  "title": "Project Configuration",
+  "content": {
+    "fields": [
+      { "name": "projectName", "label": "Project Name", "type": "text", "value": "my-app" },
+      { "name": "framework", "label": "Framework", "type": "select", "options": ["React", "Vue", "Svelte"], "value": "React" },
+      { "name": "typescript", "label": "Use TypeScript", "type": "checkbox", "value": true },
+      { "name": "description", "label": "Description", "type": "text", "value": "" }
+    ]
+  }
+}
+```
+
+**Content schema:** `{ fields: Array<{ name: string, label: string, type: "text" | "select" | "checkbox", value?: string | boolean, options?: string[] }> }`
+**Returns:** Object with field name-value pairs after user fills out and submits.
+
+### MCP Apps Best Practices
+
+1. **Use meaningful `id` values** — they are returned in responses and used for programmatic handling.
+2. **Keep list-sort items under 15** — longer lists become unwieldy for drag-and-drop.
+3. **Always provide `value` defaults** in forms — pre-fill with sensible defaults to reduce user effort.
+4. **Use `tags` in picker** — they power the search/filter functionality.
+5. **Flame-graph `total` values** should be consistent — parent total should equal sum of children.
+6. **Data-table `stats`** are optional — use them for KPI summary cards above the table.
+7. **Combine with LLM logic** — use returned values to drive next steps (e.g., form → generate config, picker → scope analysis).
+
+#### 6. `timeline` — Vertical Event Timeline (display only)
+
+```json
+{
+  "events": [
+    {"title": "v1.0 Release", "description": "Initial release with core features", "timestamp": "2025-01", "status": "complete"},
+    {"title": "v2.0 Beta", "description": "MCP Apps support", "timestamp": "2025-07", "status": "active"},
+    {"title": "v3.0 Planning", "status": "pending"}
+  ]
+}
+```
+
+Fields: `title` (required), `description?`, `timestamp?`, `status?` (`'complete'|'active'|'pending'|'error'`), `icon?`, `category?`
+
+#### 7. `kanban` — Drag-Drop Board (interactive — emits on card move)
+
+```json
+{
+  "columns": [
+    {"id": "todo", "label": "To Do"},
+    {"id": "in-progress", "label": "In Progress", "color": "#3b82f6"},
+    {"id": "done", "label": "Done", "color": "#22c55e"}
+  ],
+  "cards": [
+    {"id": "c1", "title": "Fix auth bug", "column": "todo", "tags": ["bugfix"], "priority": "high"},
+    {"id": "c2", "title": "Add search", "column": "in-progress", "tags": ["feature"], "priority": "medium"}
+  ]
+}
+```
+
+Returns `{cardId, fromColumn, toColumn}` when a card is dragged between columns.
+
+#### 8. `tree` — Collapsible Tree View (display only)
+
+```json
+{
+  "root": {
+    "label": "packages/",
+    "children": [
+      {"label": "server/", "children": [{"label": "index.ts"}, {"label": "tools/", "children": [{"label": "present.ts"}]}]},
+      {"label": "present/", "children": [{"label": "present-app.ts"}]}
+    ]
+  }
+}
+```
+
+Fields: `label` (required), `id?`, `icon?`, `children?: TreeNode[]`, `metadata?: Record<string,string>`. Accepts `root` as single node or array of nodes.
+
+#### 9. `diff-view` — Side-by-Side Code Diff (display only)
+
+```json
+{
+  "files": [{
+    "path": "auth.ts",
+    "status": "modified",
+    "additions": 12,
+    "deletions": 3,
+    "hunks": [{
+      "header": "@@ -10,5 +10,14 @@",
+      "changes": [
+        {"type": "context", "content": "const auth = {};"},
+        {"type": "delete", "content": "// old validation"},
+        {"type": "add", "content": "// new JWT validation"},
+        {"type": "add", "content": "const token = verify(jwt);"}
+      ]
+    }]
+  }],
+  "stats": {"additions": 12, "deletions": 3, "filesChanged": 1}
+}
+```
+
+Status values: `'added'|'modified'|'deleted'|'renamed'`. Change types: `'add'|'delete'|'context'`.
+
+#### 10. `dashboard` — Metric Cards Grid (display only)
+
+```json
+{
+  "metrics": [
+    {"label": "Uptime", "value": "99.9%", "status": "success", "trend": {"value": "+0.1%", "direction": "up"}},
+    {"label": "Build Time", "value": "4.2s", "type": "progress", "progress": 42, "status": "warning"},
+    {"label": "Top Endpoints", "type": "list", "value": "3", "items": [
+      {"label": "/api/search", "value": "1.2k/day"},
+      {"label": "/api/present", "value": "890/day"}
+    ]}
+  ]
+}
+```
+
+Metric types: `'stat'` (default), `'progress'` (with bar), `'list'` (sub-items). Status: `'success'|'warning'|'error'|'info'`.
+
+### Interaction Summary (All 10 Templates)
+
+| Template | Trigger | Data Returned to LLM |
+|----------|---------|---------------------|
+| list-sort | Auto on drag-drop | Reordered ID array |
+| data-table | Export button | Current filtered rows |
+| picker | Apply Selection button | Selected ID array |
+| flame-graph | Auto on node click | Clicked node object |
+| form | Submit button | Field values object |
+| kanban | Auto on card drag | `{cardId, fromColumn, toColumn}` |
+| timeline | Display only | — |
+| tree | Display only | — |
+| diff-view | Display only | — |
+| dashboard | Display only | — |