@vpxa/aikit 0.1.296 → 0.1.298

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

@@ -1 +1 @@
-function e(){return[{file:`SKILL.md`,content:'---\nname: present\ndescription: "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, checklist, document, report, error, timeline, kanban, tree, diff-view, dashboard, status-board). Load this skill before calling the present tool to ensure professional output."\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: always\n  inputs: [data, analysis]\n  outputs: [dashboards, charts, reports]\n  requires: [aikit]\nargument-hint: "Content to present — data, analysis results, status report, comparison, or interactive MCP App"\n---\n\n# Present Tool — Rich Interactive Dashboards\n\n## 1. API Shape\n\n- `schemaVersion: 1` is always required.\n- `title: string` is always required; do not use unicode escapes like `\\u2014`, use the actual character.\n- Optional layout fields: `layout?: { maxWidth?: string, padding?: string, columns?: number }`.\n- Optional appearance field: `colorScheme?: z.enum([\'light\', \'dark\', \'auto\'])`.\n- Interactive surfaces can also include `response?: { timeout?: number, required?: boolean }`.\n- Mode 1: block surface with `blocks: [{ type, title?, value }]`.\n- Mode 2: MCP App template with `template` + `data`.\n- Mode 3: viewer template with `template` + `data` for richer diagrams or flows.\n- No `actions` array means inline MCP App transport in the host client (except browser-only templates which auto-route to browser).\n- Inline transport is cross-host: AI Kit returns standard MCP Apps metadata, OpenAI compatibility metadata, and `ChannelSurface` structured content for hosts such as Codex, ChatGPT, and Copilot VS Code.\n- Any `actions` array means browser transport and opens the system browser. Valid action types: `button | select | multi-select | form-submit | text-submit | confirm | custom`.\n- CLI has no inline host; add a minimal action if you need the browser to open.\n\n```json\n{ "schemaVersion": 1, "title": "Release Review", "blocks": [{ "type": "metrics", "value": [] }] }\n```\n\n## 2. Content Blocks\n\nPass content as a `blocks` array of `{ type, title?, value }` objects.\n\n| Type | Value shape | Use for |\n|------|-------------|---------|\n| `prompt` | string | Prompt or callout text |\n| `text` | string | Plain text without markdown parsing |\n| `heading` | string | Standalone section headings |\n| `paragraph` | string | Standalone paragraph copy |\n| `markdown` | string | Prose, headings, code snippets |\n| `table` | `Record[]` or `{ headers, rows }` | Tabular data |\n| `chart` | `{ chartType, data, xKey?, yKeys? }` | `line | area | bar | horizontal-bar | pie | donut | sparkline | heatmap` |\n| `metrics` | `[{ label, value, trend?, status? }]` | KPI cards |\n| `cards` | `[{ title, body?, badge?, status? }]` | Summary cards |\n| `mermaid` | string | Diagrams (works in both mcp-app and browser) |\n| `tree` | `{ name, children? }` | Hierarchies |\n| `timeline` | `[{ title, description?, timestamp?, status? }]` | Event sequences |\n| `checklist` | `[{ label, checked }]` | Task lists |\n| `code` | string | Code or diff excerpts |\n| `comparison` | `[{title, items}]` or `{columns: [{title, items}]}` | Side-by-side option comparisons |\n| `status-board` | `[{category, items}]` or `{items: [{category, items}]}` | Service health boards |\n| `progress` | `{label, value, max?}` or `{items: [{label, value, max?, color?}]}` | Progress bars |\n| `graph` | `{ nodes: [{id, label?}], edges: [{from, to, label?}] }` | Network graphs |\n| `docs-browser` | `{ files: [{path, title?, content?, status?}], title? }` | Documentation indexes |\n| `actions` | `[{ type, id, label, variant?, options? }]` | Inline action group using the same action enum as top-level `actions` |\n| `separator` | none | Visual divider between block groups |\n\n> Anti-patterns:\n> - Prefer `table` blocks for tabular data (pipe tables in `markdown` are auto-normalized, but explicit table blocks are clearer and more efficient).\n> - Use `{ chartType, data, xKey, yKeys }`, not Chart.js `{ labels, datasets }`.\n> - Keep `markdown` for prose, headings, and code, not UI structure.\n> - **NEVER use `code` block for structured data** (arrays, objects, decisions, lists). Use `table`, `checklist`, or `markdown` instead.\n> - **NEVER JSON.stringify() data into a `code` or `markdown` block** — use the typed block that matches your data shape.\n\n### Data → Block Type Quick Reference\n\n| Your data looks like... | Use this block type | NOT this |\n|---|---|---|\n| Array of strings (decisions, findings, steps) | `markdown` (bullet list) | ~~`code` with JSON array~~ |\n| Key-value pairs (status, config, metadata) | `table` (two columns) | ~~`code` with JSON object~~ |\n| Rows × columns (comparisons, components) | `table` | ~~`markdown` with pipe table~~ |\n| Items with done/not-done state | `checklist` | ~~`markdown` with checkmark prefixes~~ |\n| Hierarchical items (file tree, org chart) | `tree` | ~~`code` with indentation~~ |\n| Numeric KPIs with labels | `metrics` | ~~`markdown`~~ |\n| Before/after or option A vs B | `comparison` | ~~two `code` blocks~~ |\n\n## 3. Actions\n\nAction shape: `{ type, id, label, variant?, options? }`\n\nValid action types: `button | select | multi-select | form-submit | text-submit | confirm | custom`\n\n\n```json\n{ "actions": [{ "type": "button", "id": "ack", "label": "Acknowledge", "variant": "primary" }] }\n```\n\n## 4. MCP App Templates\n\nUse templates for structured interactive widgets. They take `template` + `data`; returns depend on the widget.\n\n| Template | Purpose | Data shape | Returns |\n|----------|---------|------------|---------|\n| `list-sort` | Reorder a ranked list | `{ items: [{ id, label }] }` | Reordered items or IDs |\n| `data-table` | Inspect structured rows | `{ columns, rows, stats? }` | Current selection or filtered rows |\n| `picker` | Choose items from categories | `{ categories, items }` | Selected item IDs |\n| `flame-graph` | Explore hierarchical totals | `{ profile }` | Clicked node |\n| `form` | Collect field values | `{ fields }` | Submitted field map |\n| `checklist` | Run an interactive checklist | `{ items, title? }` | Checked state or submission payload |\n| `document` | Present structured long-form content | `{ sections, title? }` | Display only |\n| `report` | Present synthesized report content | `{ title, sections, metrics?, tables? }` | Display only |\n| `error` | Show structured error states and recovery actions | `{ code, message, details?, stack? }` | Display only |\n| `kanban` | Move cards across columns | `{ columns, cards }` | Card move payload |\n| `timeline` | Show ordered milestones | `{ events }` | Display only |\n| `tree` | Browse nested nodes | `{ root }` | Display only |\n| `diff-view` | Show file diffs | `{ files, stats? }` | Display only |\n| `dashboard` | Show metric cards | `{ metrics }` | Display only |\n| `status-board` | Show grouped status or health views | `{ categories }` | Display only |\n\n> **Auto-routing:** Browser-only templates (form, kanban, flame-graph, picker, list-sort) auto-route to browser transport even without explicit `actions`. No need to add a dummy action — the tool handles it.\n\n### `list-sort`\n`data`: `{ "items": [{ "id": "task-1", "label": "Fix auth bug" }] }`\n\n### `data-table`\n`data`: `{ "columns": [{ "key": "file", "label": "File" }], "rows": [{ "file": "auth.ts" }], "stats": [{ "label": "Files", "value": "1" }] }`\n\n### `picker`\n`data`: `{ "categories": [{ "id": "core", "label": "Core" }], "items": [{ "id": "auth", "label": "Auth", "category": "core", "tags": ["security"] }] }`\n\n### `flame-graph`\n`data`: `{ "profile": { "name": "root", "total": 100, "children": [{ "name": "packages/server", "total": 60 }] } }`\n\n### `form`\n`data`: `{ "fields": [{ "name": "projectName", "label": "Project Name", "type": "text", "value": "my-app" }] }`\n\n### `checklist`\n`data`: `{ "items": [{ "label": "Write tests", "checked": true }, { "label": "Update docs", "checked": false }], "title": "Sprint Tasks" }`\n\nTransports: mcp-app, browser (interactive — checkboxes toggle). NOT export.\n\n### `document`\n`data`: `{ "title": "Architecture Overview", "sections": [{ "heading": "Introduction", "content": "System overview text" }, { "heading": "Components", "content": [{ "type": "markdown", "value": "- API Gateway\\n- Auth Service" }] }] }`\n\nSections `content` can be a plain string OR an array of TypedBlock objects.\n\n### `report`\n`data`: `{ "title": "Weekly Status", "metrics": [{ "label": "Coverage", "value": "94%", "trend": "+2%", "status": "success" }], "sections": [{ "heading": "Summary", "content": "All systems operational" }], "tables": [{ "title": "Services", "headers": ["Name", "Status"], "rows": [["API", "healthy"], ["DB", "degraded"]] }] }`\n\nAll fields except `title` and `sections` are optional. `metrics` renders as metric cards; `tables` renders after sections.\n\n### `error`\n`data`: `{ "code": "AUTH_EXPIRED", "message": "Session token has expired", "details": "Token issued at 2026-01-01T00:00:00Z exceeded 24h TTL", "stack": "Error: AUTH_EXPIRED\\n    at validateToken (auth.ts:42)" }`\n\nOnly `code` and `message` are required. `details` adds context below the message; `stack` renders as a separate code block.\n\n### `kanban`\n`data`: `{ "columns": [{ "id": "todo", "label": "To Do" }], "cards": [{ "id": "c1", "title": "Fix auth bug", "column": "todo" }] }`\n\n### `timeline`\n`data`: `{ "events": [{ "title": "v1.0 Release", "timestamp": "2026-05", "status": "complete" }] }`\n\nThe timeline template also accepts `entries` or `items` as the array field name (all three are equivalent).\n\n### `tree`\n`data`: `{ "root": { "label": "packages/", "children": [{ "label": "server/" }] } }`\n\n### `diff-view`\n`data`: `{ "files": [{ "path": "auth.ts", "status": "modified", "hunks": [{ "header": "@@ -1 +1 @@", "changes": [{ "type": "add", "content": "const ok = true;" }] }] }], "stats": { "filesChanged": 1 } }`\n\n### `dashboard`\n`data`: `{ "metrics": [{ "label": "Uptime", "value": "99.9%", "status": "success" }] }`\n\n### `status-board`\n`data`: `{ "categories": [{ "category": "Production", "items": [{ "label": "API Gateway", "status": "healthy" }, { "label": "Auth Service", "status": "degraded" }] }] }`\n\nNote: The template requires `{ categories: [...] }` (object with a `categories` key). This differs from the **block type** `status-board` which accepts a bare array as its value.\n\n⚠️ **WARNING:** Do NOT confuse template format with block format. When using `type: "status-board"` (block), value must be `[{category, items}]` (bare array) or `{items: [{category, items}]}`. The `{categories: [{category, items}]}` shape is ONLY for `template: "status-board"`.\n\n## 5. Viewer Templates\n\nViewer templates render richer visual surfaces from `template` + `data`.\n\n| Template | Transport | Purpose |\n|----------|-----------|---------|\n| `c4-static@1` | mcp-app | Static architecture diagram |\n| `c4@1` | browser | Interactive architecture diagram |\n| `process-flow-static@1` | mcp-app | Static process flow |\n| `process-flow@1` | browser | Interactive process flow |\n| `tour@1` | browser | Guided walkthrough or code tour |\n| `task-plan-static@1` | mcp-app | Static task execution plan with phases, batches, agent assignments |\n| `task-plan@1` | browser | Interactive task plan with ReactFlow — drag/zoom/pan, dependency edges, ELK layout |\n\n`c4`: `{ "nodes": [{ "id": "web", "type": "container", "label": "Web App", "technology?": "React" }], "edges": [{ "source": "web", "target": "api", "label": "HTTPS" }] }`\n\n`process-flow`: `{ "nodes": [{ "id": "start", "label": "Start", "type": "start-end" }], "edges": [{ "source": "start", "target": "review", "type?": "standard" }] }`\n\nNode types: `start-end` | `manual` | `automated` | `integration` | `decision` | `prerequisite`. Default: `manual`.\nEdge types: `standard` | `loop-back` | `exception`. Default: `standard`. `loop-back` and `exception` edges animate.\n\n`tour`: `{ "steps": [{ "id": "overview", "title": "Overview", "file": "src/index.ts", "explanation": "Entry point", "code?": "...", "line?": 1 }] }`\n\n`task-plan`: `{ "title": "Feature Name", "description?": "Optional", "phases": [{ "id": "p1", "label": "Phase 1", "outcome?": "...", "batches": [{ "id": "b1", "order": 1, "parallel": true, "label?": "Parallel Research", "tasks": [{ "id": "t1", "title": "Research auth", "agent": "Researcher-Alpha", "files?": ["src/auth/"], "status?": "done", "description?": "...", "dependsOn?": [] }] }] }] }`\n\nTask status values: `pending` | `in-progress` | `done` | `blocked`. Default: `pending`.\n\nGotcha: edges use `source` and `target`, not `from` and `to`.\n\nDecision tree:\n- Architecture, systems, containers, deployments: load the `c4-architecture` skill and use `c4@1` or `c4-static@1`.\n- Stateful workflows, approvals, or branching processes: use `process-flow@1` or `process-flow-static@1`.\n- Agent task decomposition, execution plans, or parallel batch visualization: use `task-plan@1` or `task-plan-static@1`.\n- Ordered walkthroughs, onboarding, or narrated analysis: use `tour@1`.\n\n## 6. Rules\n\n- Pick transport once: no `actions` for inline, any `actions` for browser.\n- Combine block types in one `blocks` array; metrics + chart + table + markdown is the normal composition pattern.\n- Use concise schemas in docs; do not expand to full `present()` calls unless behavior depends on them.\n- Use `table`, `comparison`, and `status-board` for structured data instead of formatting it inside markdown.\n- Architecture requests are delegated: load the `c4-architecture` skill for diagram guidance and data contracts.\n- If inline rendering only shows a title, raw JSON, or fallback text, first assume the host lacks or has disabled MCP Apps rendering. Switch to browser transport with a minimal action only when you need a deterministic fallback.\n- For large or mixed-content surfaces, browser transport is usually easier to review and more reliable.\n- For custom HTML demos or visual prototypes, do NOT use the "html" block type (renders as raw text inline). Instead, write an HTML file, serve it locally (e.g. "npx -y serve" or "python -m http.server"), then open with the AI Kit "browser" tool: browser({ action: "open", url: "http://localhost:PORT/file.html", mode: "ui" }). This gives a controlled Chromium instance the LLM can read/interact with. Avoid "Start-Process" (opens uncontrolled system browser).\n'}]}export{e as default};
+function e(){return[{file:`SKILL.md`,content:'---\nname: present\ndescription: "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, checklist, document, report, error, timeline, kanban, tree, diff-view, dashboard, status-board). Load this skill before calling the present tool to ensure professional output."\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: always\n  inputs: [data, analysis]\n  outputs: [dashboards, charts, reports]\n  requires: [aikit]\nargument-hint: "Content to present — data, analysis results, status report, comparison, or interactive MCP App"\n---\n\n# Present Tool — Rich Interactive Dashboards\n\n> **Three-tier authoring model:** (1) Free-form `blocks[]`, (2) Named presets with structured data, (3) Viewer templates for custom HTML/iframes. Use `aikit://schemas/channel-surface` for block catalog, `aikit://present/presets` for preset contracts, `aikit://present/templates` for viewer schemas.\n\nThe tool normalizes all three input tiers into a validated `ChannelSurface` before rendering. Pipeline: **Input -> Normalizer -> ChannelSurface -> Transport Registry -> Render**. Validation errors return `{ code, reason, hint? }` (typed errors) -- not full schema dumps.\n\n## 0. Presets (Tier 2)\n\nPresets are named data contracts that expand `blocks[]` from structured input. 8 presets registered at runtime via `aikit://present/presets`:\n\n| Preset | Input shape | Expands to |\n|--------|------------|------------|\n| `summary` | `{ title, summary, passed?: number, failed?: number }` | heading, markdown, metrics |\n| `plan` | `{ title, steps: [{ label, checked }] }` | heading, checklist |\n| `understanding` | `{ title, explanation, details?: string }` | heading, markdown, kv |\n| `bug-analyze` | `{ title, severity, status, code?: string, analysis?: string }` | heading, kv, code, markdown |\n| `task-done` | `{ title, items: [{ label, checked }], completed?, total? }` | heading, checklist, metrics |\n| `review` | `{ title, criteria: [{ label, checked }] }` | heading, checklist + actions |\n| `explore` | `{ title, findings: [{ heading, code }] }` | heading, code (per finding) |\n| `decision` | `{ title, recommendation, options?: [{ title, items }] }` | heading, kv, comparison |\n\nEach preset supplies `inputSchema` (JSON Schema), `example` (JSON), and `expandsTo` (block description).\n\nUsage: pass `["preset-name", { title, ...fields }]` tuple directly, or `{ template: "preset-name", data: { ... } }` in a ChannelSurface.\n\nFull contracts available at runtime resource `aikit://present/presets`.\n\n## 0b. Shorthand Blocks (Tier 3)\n\nFor token-efficient ad-hoc surfaces, pass a `ShorthandInput` instead of a full ChannelSurface:\n\n```json\n{ "title": "Status", "blocks": ["# Results", ["M", [{ "label": "Pass", "value": 12 }]], "All good."] }\n```\n\n`blocks[]` elements can be:\n- **String**: auto-detected as heading (`# `), fenced code (```), pipe table (`|`), or markdown fallback.\n- **Tuple `[key, value]`**: key maps to block type via shortcut map below.\n- **Full object `{ type, value }`**: passes through as a standard TypedBlock.\nYou can also pass a bare string -- it expands to a single markdown block.\n\n### Shortcut Map\n\n| Key | Block type | Key | Block type |\n|-----|-----------|-----|-----------|\n| `h` | heading | `C` | chart |\n| `m` | markdown | `T` | timeline |\n| `t` | table | `g` | graph |\n| `p` | paragraph | `tr` | tree |\n| `c` | code | `cl` | checklist |\n| `s` | separator | `pr` | progress |\n| `M` | metrics | `sb` | status-board |\n| `kv` | kv | `ac` | actions |\n| `di` | mermaid | `tl` | timeline (alt) |\n\n## 1. API Shape\n\n- `schemaVersion: 1` is always required.\n- `title: string` is always required; do not use unicode escapes like `\\u2014`, use the actual character.\n- Optional layout fields: `layout?: { maxWidth?: string, padding?: string, columns?: number }`.\n- Optional appearance field: `colorScheme?: z.enum([\'light\', \'dark\', \'auto\'])`.\n- Interactive surfaces can also include `response?: { timeout?: number, required?: boolean }`.\n- Mode 1: block surface with `blocks: [{ type, title?, value }]`.\n- Mode 2: MCP App template with `template` + `data`.\n- Mode 3: viewer template with `template` + `data` for richer diagrams or flows.\n- No `actions` array means inline MCP App transport in the host client (except browser-only templates which auto-route to browser).\n- Inline transport is cross-host: AI Kit returns standard MCP Apps metadata, OpenAI compatibility metadata, and `ChannelSurface` structured content for hosts such as Codex, ChatGPT, and Copilot VS Code.\n- Any `actions` array means browser transport and opens the system browser. Valid action types: `button | select | multi-select | form-submit | text-submit | confirm | custom`.\n- CLI has no inline host; add a minimal action if you need the browser to open.\n\n```json\n{ "schemaVersion": 1, "title": "Release Review", "blocks": [{ "type": "metrics", "value": [] }] }\n```\n\n## 2. Content Blocks\n\nPass content as a `blocks` array of `{ type, title?, value }` objects.\n\n| Type | Value shape | Use for |\n|------|-------------|---------|\n| `prompt` | string | Prompt or callout text |\n| `text` | string | Plain text without markdown parsing |\n| `heading` | string | Standalone section headings |\n| `paragraph` | string | Standalone paragraph copy |\n| `markdown` | string | Prose, headings, code snippets |\n| `table` | `Record[]` or `{ headers, rows }` | Tabular data |\n| `chart` | `{ chartType, data, xKey?, yKeys? }` | `line | area | bar | horizontal-bar | pie | donut | sparkline | heatmap` |\n| `metrics` | `[{ label, value, trend?, status? }]` | KPI cards |\n| `cards` | `[{ title, body?, badge?, status? }]` | Summary cards |\n| `mermaid` | string | Diagrams (works in both mcp-app and browser) |\n| `tree` | `{ name, children? }` | Hierarchies |\n| `timeline` | `[{ title, description?, timestamp?, status? }]` | Event sequences |\n| `checklist` | `[{ label, checked }]` | Task lists |\n| `code` | string | Code or diff excerpts |\n| `comparison` | `[{title, items}]` or `{columns: [{title, items}]}` | Side-by-side option comparisons |\n| `status-board` | `[{category, items}]` or `{items: [{category, items}]}` | Service health boards |\n| `progress` | `{label, value, max?}` or `{items: [{label, value, max?, color?}]}` | Progress bars |\n| `graph` | `{ nodes: [{id, label?}], edges: [{from, to, label?}] }` | Network graphs |\n| `docs-browser` | `{ files: [{path, title?, content?, status?}], title? }` | Documentation indexes |\n| `actions` | `[{ type, id, label, variant?, options? }]` | Inline action group using the same action enum as top-level `actions` |\n| `separator` | none | Visual divider between block groups |\n\n> Anti-patterns:\n> - Prefer `table` blocks for tabular data (pipe tables in `markdown` are auto-normalized, but explicit table blocks are clearer and more efficient).\n> - Use `{ chartType, data, xKey, yKeys }`, not Chart.js `{ labels, datasets }`.\n> - Keep `markdown` for prose, headings, and code, not UI structure.\n> - **NEVER use `code` block for structured data** (arrays, objects, decisions, lists). Use `table`, `checklist`, or `markdown` instead.\n> - **NEVER JSON.stringify() data into a `code` or `markdown` block** — use the typed block that matches your data shape.\n\n### Data → Block Type Quick Reference\n\n| Your data looks like... | Use this block type | NOT this |\n|---|---|---|\n| Array of strings (decisions, findings, steps) | `markdown` (bullet list) | ~~`code` with JSON array~~ |\n| Key-value pairs (status, config, metadata) | `table` (two columns) | ~~`code` with JSON object~~ |\n| Rows × columns (comparisons, components) | `table` | ~~`markdown` with pipe table~~ |\n| Items with done/not-done state | `checklist` | ~~`markdown` with checkmark prefixes~~ |\n| Hierarchical items (file tree, org chart) | `tree` | ~~`code` with indentation~~ |\n| Numeric KPIs with labels | `metrics` | ~~`markdown`~~ |\n| Before/after or option A vs B | `comparison` | ~~two `code` blocks~~ |\n\n## 3. Actions\n\nAction shape: `{ type, id, label, variant?, options? }`\n\nValid action types: `button | select | multi-select | form-submit | text-submit | confirm | custom`\n\n\n```json\n{ "actions": [{ "type": "button", "id": "ack", "label": "Acknowledge", "variant": "primary" }] }\n```\n\n## 4. MCP App Templates\n\nUse templates for structured interactive widgets. They take `template` + `data`; returns depend on the widget.\n\n| Template | Purpose | Data shape | Returns |\n|----------|---------|------------|---------|\n| `list-sort` | Reorder a ranked list | `{ items: [{ id, label }] }` | Reordered items or IDs |\n| `data-table` | Inspect structured rows | `{ columns, rows, stats? }` | Current selection or filtered rows |\n| `picker` | Choose items from categories | `{ categories, items }` | Selected item IDs |\n| `flame-graph` | Explore hierarchical totals | `{ profile }` | Clicked node |\n| `form` | Collect field values | `{ fields }` | Submitted field map |\n| `checklist` | Run an interactive checklist | `{ items, title? }` | Checked state or submission payload |\n| `document` | Present structured long-form content | `{ sections, title? }` | Display only |\n| `report` | Present synthesized report content | `{ title, sections, metrics?, tables? }` | Display only |\n| `error` | Show structured error states and recovery actions | `{ code, message, details?, stack? }` | Display only |\n| `kanban` | Move cards across columns | `{ columns, cards }` | Card move payload |\n| `timeline` | Show ordered milestones | `{ events }` | Display only |\n| `tree` | Browse nested nodes | `{ root }` | Display only |\n| `diff-view` | Show file diffs | `{ files, stats? }` | Display only |\n| `dashboard` | Show metric cards | `{ metrics }` | Display only |\n| `status-board` | Show grouped status or health views | `{ categories }` | Display only |\n\n> **Auto-routing:** Browser-only templates (form, kanban, flame-graph, picker, list-sort) auto-route to browser transport even without explicit `actions`. No need to add a dummy action — the tool handles it.\n\n### `list-sort`\n`data`: `{ "items": [{ "id": "task-1", "label": "Fix auth bug" }] }`\n\n### `data-table`\n`data`: `{ "columns": [{ "key": "file", "label": "File" }], "rows": [{ "file": "auth.ts" }], "stats": [{ "label": "Files", "value": "1" }] }`\n\n### `picker`\n`data`: `{ "categories": [{ "id": "core", "label": "Core" }], "items": [{ "id": "auth", "label": "Auth", "category": "core", "tags": ["security"] }] }`\n\n### `flame-graph`\n`data`: `{ "profile": { "name": "root", "total": 100, "children": [{ "name": "packages/server", "total": 60 }] } }`\n\n### `form`\n`data`: `{ "fields": [{ "name": "projectName", "label": "Project Name", "type": "text", "value": "my-app" }] }`\n\n### `checklist`\n`data`: `{ "items": [{ "label": "Write tests", "checked": true }, { "label": "Update docs", "checked": false }], "title": "Sprint Tasks" }`\n\nTransports: mcp-app, browser (interactive — checkboxes toggle). NOT export.\n\n### `document`\n`data`: `{ "title": "Architecture Overview", "sections": [{ "heading": "Introduction", "content": "System overview text" }, { "heading": "Components", "content": [{ "type": "markdown", "value": "- API Gateway\\n- Auth Service" }] }] }`\n\nSections `content` can be a plain string OR an array of TypedBlock objects.\n\n### `report`\n`data`: `{ "title": "Weekly Status", "metrics": [{ "label": "Coverage", "value": "94%", "trend": "+2%", "status": "success" }], "sections": [{ "heading": "Summary", "content": "All systems operational" }], "tables": [{ "title": "Services", "headers": ["Name", "Status"], "rows": [["API", "healthy"], ["DB", "degraded"]] }] }`\n\nAll fields except `title` and `sections` are optional. `metrics` renders as metric cards; `tables` renders after sections.\n\n### `error`\n`data`: `{ "code": "AUTH_EXPIRED", "message": "Session token has expired", "details": "Token issued at 2026-01-01T00:00:00Z exceeded 24h TTL", "stack": "Error: AUTH_EXPIRED\\n    at validateToken (auth.ts:42)" }`\n\nOnly `code` and `message` are required. `details` adds context below the message; `stack` renders as a separate code block.\n\n### `kanban`\n`data`: `{ "columns": [{ "id": "todo", "label": "To Do" }], "cards": [{ "id": "c1", "title": "Fix auth bug", "column": "todo" }] }`\n\n### `timeline`\n`data`: `{ "events": [{ "title": "v1.0 Release", "timestamp": "2026-05", "status": "complete" }] }`\n\nThe timeline template also accepts `entries` or `items` as the array field name (all three are equivalent).\n\n### `tree`\n`data`: `{ "root": { "label": "packages/", "children": [{ "label": "server/" }] } }`\n\n### `diff-view`\n`data`: `{ "files": [{ "path": "auth.ts", "status": "modified", "hunks": [{ "header": "@@ -1 +1 @@", "changes": [{ "type": "add", "content": "const ok = true;" }] }] }], "stats": { "filesChanged": 1 } }`\n\n### `dashboard`\n`data`: `{ "metrics": [{ "label": "Uptime", "value": "99.9%", "status": "success" }] }`\n\n### `status-board`\n`data`: `{ "categories": [{ "category": "Production", "items": [{ "label": "API Gateway", "status": "healthy" }, { "label": "Auth Service", "status": "degraded" }] }] }`\n\nNote: The template requires `{ categories: [...] }` (object with a `categories` key). This differs from the **block type** `status-board` which accepts a bare array as its value.\n\n⚠️ **WARNING:** Do NOT confuse template format with block format. When using `type: "status-board"` (block), value must be `[{category, items}]` (bare array) or `{items: [{category, items}]}`. The `{categories: [{category, items}]}` shape is ONLY for `template: "status-board"`.\n\n## 5. Viewer Templates\n\nViewer templates render richer visual surfaces from `template` + `data`.\n\n| Template | Transport | Purpose |\n|----------|-----------|---------|\n| `c4-static@1` | mcp-app | Static architecture diagram |\n| `c4@1` | browser | Interactive architecture diagram |\n| `process-flow-static@1` | mcp-app | Static process flow |\n| `process-flow@1` | browser | Interactive process flow |\n| `tour@1` | browser | Guided walkthrough or code tour |\n| `task-plan-static@1` | mcp-app | Static task execution plan with phases, batches, agent assignments |\n| `task-plan@1` | browser | Interactive task plan with ReactFlow — drag/zoom/pan, dependency edges, ELK layout |\n\n`c4`: `{ "nodes": [{ "id": "web", "type": "container", "label": "Web App", "technology?": "React" }], "edges": [{ "source": "web", "target": "api", "label": "HTTPS" }] }`\n\n`process-flow`: `{ "nodes": [{ "id": "start", "label": "Start", "type": "start-end" }], "edges": [{ "source": "start", "target": "review", "type?": "standard" }] }`\n\nNode types: `start-end` | `manual` | `automated` | `integration` | `decision` | `prerequisite`. Default: `manual`.\nEdge types: `standard` | `loop-back` | `exception`. Default: `standard`. `loop-back` and `exception` edges animate.\n\n`tour`: `{ "steps": [{ "id": "overview", "title": "Overview", "file": "src/index.ts", "explanation": "Entry point", "code?": "...", "line?": 1 }] }`\n\n`task-plan`: `{ "title": "Feature Name", "description?": "Optional", "phases": [{ "id": "p1", "label": "Phase 1", "outcome?": "...", "batches": [{ "id": "b1", "order": 1, "parallel": true, "label?": "Parallel Research", "tasks": [{ "id": "t1", "title": "Research auth", "agent": "Researcher-Alpha", "files?": ["src/auth/"], "status?": "done", "description?": "...", "dependsOn?": [] }] }] }] }`\n\nTask status values: `pending` | `in-progress` | `done` | `blocked`. Default: `pending`.\n\nGotcha: edges use `source` and `target`, not `from` and `to`.\n\nDecision tree:\n- Architecture, systems, containers, deployments: load the `c4-architecture` skill and use `c4@1` or `c4-static@1`.\n- Stateful workflows, approvals, or branching processes: use `process-flow@1` or `process-flow-static@1`.\n- Agent task decomposition, execution plans, or parallel batch visualization: use `task-plan@1` or `task-plan-static@1`.\n- Ordered walkthroughs, onboarding, or narrated analysis: use `tour@1`.\n\n## 6. Rules\n\n- Pick transport once: no `actions` for inline, any `actions` for browser.\n- Combine block types in one `blocks` array; metrics + chart + table + markdown is the normal composition pattern.\n- Use concise schemas in docs; do not expand to full `present()` calls unless behavior depends on them.\n- Use `table`, `comparison`, and `status-board` for structured data instead of formatting it inside markdown.\n- Architecture requests are delegated: load the `c4-architecture` skill for diagram guidance and data contracts.\n- If inline rendering only shows a title, raw JSON, or fallback text, first assume the host lacks or has disabled MCP Apps rendering. Switch to browser transport with a minimal action only when you need a deterministic fallback.\n- For large or mixed-content surfaces, browser transport is usually easier to review and more reliable.\n- For custom HTML demos or visual prototypes, do NOT use the "html" block type (renders as raw text inline). Instead, write an HTML file, serve it locally (e.g. "npx -y serve" or "python -m http.server"), then open with the AI Kit "browser" tool: browser({ action: "open", url: "http://localhost:PORT/file.html", mode: "ui" }). This gives a controlled Chromium instance the LLM can read/interact with. Avoid "Start-Process" (opens uncontrolled system browser).\n'}]}export{e as default};

package/packages/server/dist/promotion-CJFYv4Ye.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-import{t as e}from"./rolldown-runtime-yuFVEuWy.js";import{t}from"./bin.js";import{f as n,r,u as i}from"./supersession-DO_ZROFl.js";import{existsSync as a,mkdirSync as o}from"node:fs";import{join as s}from"node:path";import{getGlobalDataDir as c,isUserInstalled as l,listWorkspaces as u}from"../../core/dist/index.js";var d=e({DEFAULT_PROMOTE_CONFIG:()=>f,collectWorkspaceLessons:()=>w,demoteLesson:()=>D,getGlobalCuratedDir:()=>C,promoteLessons:()=>E,scanForDuplicates:()=>T});const f={minWorkspaces:2,minAvgConfidence:80,similarityThreshold:.7,dryRun:!0};function p(e){return{minWorkspaces:Math.max(2,Math.trunc(e?.minWorkspaces??f.minWorkspaces)),minAvgConfidence:Math.min(100,Math.max(0,Math.trunc(e?.minAvgConfidence??f.minAvgConfidence))),similarityThreshold:Math.min(1,Math.max(0,e?.similarityThreshold??f.similarityThreshold)),dryRun:e?.dryRun??f.dryRun}}function m(e,t){let n=e.map(()=>[]);for(let i=0;i<e.length;i+=1)for(let a=i+1;a<e.length;a+=1)r(e[i].insight,e[a].insight)>=t&&(n[i].push(a),n[a].push(i));return n}function h(e){let t=new Set,n=[];for(let r=0;r<e.length;r+=1){if(t.has(r))continue;let i=[r],a=[];for(t.add(r);i.length>0;){let n=i.pop();if(n!==void 0){a.push(n);for(let r of e[n])t.has(r)||(t.add(r),i.push(r))}}n.push(a)}return n}function g(e){return new t(e,null,null)}function _(e){return(e??``).replace(/\s+/g,` `).trim()}function v(e){let t=_(e);return t.length<=80?t:`${t.slice(0,77).replace(/\s+\S*$/,``)}...`}function y(e){return i({title:v(e.insight),context:`Observed across ${e.foundIn.length} workspaces: ${e.foundIn.join(`, `)}`,insight:e.insight,evidence:[`Promoted from workspaces: ${e.foundIn.join(`, `)}`,`Average confidence: ${e.avgConfidence}/100`,`Reason: ${e.reason}`].join(`
-`),confidence:e.avgConfidence,tags:[`lesson`,`promoted`,`global`]})}async function b(e,t){let r=await e.list({category:`lessons`});return(await Promise.all(r.map(async r=>{let i=await e.read(r.path),a=n(i.content),o=_(a.insight);return o?{workspace:t,path:r.path,title:a.title??i.title??r.title,insight:o,confidence:a.confidence??0}:null}))).filter(e=>e!==null)}async function x(e){return(await b(e,`global`)).map(e=>e.insight)}function S(e,t,n){return t.some(t=>r(t,e)>=n)}function C(){let e=s(c(),`global-knowledge`,`.ai`,`curated`);return a(e)||o(e,{recursive:!0}),e}async function w(e){let t=new Map;if(!l())return t;for(let e of u()){let n=s(e.workspacePath,`.ai`,`curated`);if(!a(n))continue;let r=await b(g(n),e.partition);r.length>0&&t.set(e.partition,r)}return t}function T(e,t=f){let n=p(t),r=[...e.values()].flat();if(r.length===0)return[];let i=h(m(r,n.similarityThreshold)),a=[];for(let e of i){let t=e.map(e=>r[e]),i=[...new Set(t.map(e=>e.workspace))].sort();if(i.length<n.minWorkspaces)continue;let o=Math.round(t.reduce((e,t)=>e+t.confidence,0)/t.length),s=[...t].sort((e,t)=>t.confidence-e.confidence||e.title.localeCompare(t.title)||e.path.localeCompare(t.path))[0];a.push({insight:s.insight,foundIn:i,avgConfidence:o,action:o>=n.minAvgConfidence?`promote`:`skip`,reason:o>=n.minAvgConfidence?`Shared across ${i.length} workspaces`:`Below confidence threshold`})}return a.sort((e,t)=>Number(t.action===`promote`)-Number(e.action===`promote`)||t.foundIn.length-e.foundIn.length||t.avgConfidence-e.avgConfidence||e.insight.localeCompare(t.insight))}async function E(e,t,n=f){let r=p(n),i=[],a=await x(t);for(let n of e){if(n.action!==`promote`||S(n.insight,a,r.similarityThreshold)||r.dryRun)continue;let e=await t.remember(v(n.insight),y(n),`lessons`,[`lesson`,`promoted`,`global`]);i.push(e.path),a.push(n.insight)}return{candidates:e,promoted:i}}async function D(e,t){try{return await e.forget(t,`Demoted from global knowledge partition`),{removed:!0,path:t}}catch(e){if(e instanceof Error&&/not found/i.test(e.message))return{removed:!1,path:t};throw e}}export{E as a,C as i,w as n,d as o,D as r,T as s,f as t};

package/packages/server/dist/promotion-D9anNXv8.js

@@ -1,2 +0,0 @@
-import{t as e}from"./rolldown-runtime-DT7IzrpZ.js";import{t}from"./curated-manager-C5uOPept.js";import{f as n,r,u as i}from"./supersession-CWEne3av.js";import{existsSync as a,mkdirSync as o}from"node:fs";import{join as s}from"node:path";import{getGlobalDataDir as c,isUserInstalled as l,listWorkspaces as u}from"../../core/dist/index.js";var d=e({DEFAULT_PROMOTE_CONFIG:()=>f,collectWorkspaceLessons:()=>w,demoteLesson:()=>D,getGlobalCuratedDir:()=>C,promoteLessons:()=>E,scanForDuplicates:()=>T});const f={minWorkspaces:2,minAvgConfidence:80,similarityThreshold:.7,dryRun:!0};function p(e){return{minWorkspaces:Math.max(2,Math.trunc(e?.minWorkspaces??f.minWorkspaces)),minAvgConfidence:Math.min(100,Math.max(0,Math.trunc(e?.minAvgConfidence??f.minAvgConfidence))),similarityThreshold:Math.min(1,Math.max(0,e?.similarityThreshold??f.similarityThreshold)),dryRun:e?.dryRun??f.dryRun}}function m(e,t){let n=e.map(()=>[]);for(let i=0;i<e.length;i+=1)for(let a=i+1;a<e.length;a+=1)r(e[i].insight,e[a].insight)>=t&&(n[i].push(a),n[a].push(i));return n}function h(e){let t=new Set,n=[];for(let r=0;r<e.length;r+=1){if(t.has(r))continue;let i=[r],a=[];for(t.add(r);i.length>0;){let n=i.pop();if(n!==void 0){a.push(n);for(let r of e[n])t.has(r)||(t.add(r),i.push(r))}}n.push(a)}return n}function g(e){return new t(e,null,null)}function _(e){return(e??``).replace(/\s+/g,` `).trim()}function v(e){let t=_(e);return t.length<=80?t:`${t.slice(0,77).replace(/\s+\S*$/,``)}...`}function y(e){return i({title:v(e.insight),context:`Observed across ${e.foundIn.length} workspaces: ${e.foundIn.join(`, `)}`,insight:e.insight,evidence:[`Promoted from workspaces: ${e.foundIn.join(`, `)}`,`Average confidence: ${e.avgConfidence}/100`,`Reason: ${e.reason}`].join(`
-`),confidence:e.avgConfidence,tags:[`lesson`,`promoted`,`global`]})}async function b(e,t){let r=await e.list({category:`lessons`});return(await Promise.all(r.map(async r=>{let i=await e.read(r.path),a=n(i.content),o=_(a.insight);return o?{workspace:t,path:r.path,title:a.title??i.title??r.title,insight:o,confidence:a.confidence??0}:null}))).filter(e=>e!==null)}async function x(e){return(await b(e,`global`)).map(e=>e.insight)}function S(e,t,n){return t.some(t=>r(t,e)>=n)}function C(){let e=s(c(),`global-knowledge`,`.ai`,`curated`);return a(e)||o(e,{recursive:!0}),e}async function w(e){let t=new Map;if(!l())return t;for(let e of u()){let n=s(e.workspacePath,`.ai`,`curated`);if(!a(n))continue;let r=await b(g(n),e.partition);r.length>0&&t.set(e.partition,r)}return t}function T(e,t=f){let n=p(t),r=[...e.values()].flat();if(r.length===0)return[];let i=h(m(r,n.similarityThreshold)),a=[];for(let e of i){let t=e.map(e=>r[e]),i=[...new Set(t.map(e=>e.workspace))].sort();if(i.length<n.minWorkspaces)continue;let o=Math.round(t.reduce((e,t)=>e+t.confidence,0)/t.length),s=[...t].sort((e,t)=>t.confidence-e.confidence||e.title.localeCompare(t.title)||e.path.localeCompare(t.path))[0];a.push({insight:s.insight,foundIn:i,avgConfidence:o,action:o>=n.minAvgConfidence?`promote`:`skip`,reason:o>=n.minAvgConfidence?`Shared across ${i.length} workspaces`:`Below confidence threshold`})}return a.sort((e,t)=>Number(t.action===`promote`)-Number(e.action===`promote`)||t.foundIn.length-e.foundIn.length||t.avgConfidence-e.avgConfidence||e.insight.localeCompare(t.insight))}async function E(e,t,n=f){let r=p(n),i=[],a=await x(t);for(let n of e){if(n.action!==`promote`||S(n.insight,a,r.similarityThreshold)||r.dryRun)continue;let e=await t.remember(v(n.insight),y(n),`lessons`,[`lesson`,`promoted`,`global`]);i.push(e.path),a.push(n.insight)}return{candidates:e,promoted:i}}async function D(e,t){try{return await e.forget(t,`Demoted from global knowledge partition`),{removed:!0,path:t}}catch(e){if(e instanceof Error&&/not found/i.test(e.message))return{removed:!1,path:t};throw e}}export{E as a,C as i,w as n,d as o,D as r,T as s,f as t};