@vpxa/aikit 0.1.154 → 0.1.156

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

@@ -15,11 +15,11 @@ argument-hint: "Content to present — data, analysis results, status report, co
 
 ## Quick Reference
 
-**Two formats:**
-- \`html\` — in-chat UIResource (display-only: tables, charts, reports). DEFAULT choice.
-- \`browser\` — local URL in system browser (when you need user interaction back, or in CLI mode).
+**Transport rule:**
+- No \`actions\` array — renders inline as an MCP App surface in the host client.
+- \`actions\` array present — switches to browser transport and opens the system browser.
 
-**Content blocks** (pass as \`content\` array of \`{ type, title?, value }\`):
+**Content blocks** (pass as \`blocks\` array of \`{ type, title?, value }\`):
 | Type | Value shape | Use for |
 |------|-------------|---------|
 | \`markdown\` | string | Prose, headings, code — **never tables** |
@@ -33,58 +33,57 @@ argument-hint: "Content to present — data, analysis results, status report, co
 | \`checklist\` | \`[{label,checked}]\` | Todo/check lists |
 | \`code\` | string | Code blocks |
 
-**Actions** (interactive buttons/selects, mainly for \`browser\` mode):
+**Actions** (interactive buttons/selects; adding them switches transport to browser):
 \`\`\`json
 { "actions": [{ "type": "button", "id": "approve", "label": "Approve", "variant": "primary" }] }
 \`\`\`
 
 **Anti-patterns:**
 - ❌ Tables inside \`markdown\` blocks → renders as raw pipe text
-- ❌ \`html\` format in CLI mode → invisible (use \`browser\`)
+- ❌ Assuming a \`format\` field exists → transport is inferred from \`actions\`
 - ❌ Unicode escapes in \`title\` param (\`\\u2014\`) → literal text (use actual — character)
 - ❌ Chart.js format (\`{labels,datasets}\`) → use \`{chartType,data,xKey,yKeys}\`
 
-The \`present\` tool renders structured content as a professional dark-themed dashboard. It supports two output modes:
+The \`present\` tool renders structured content as a professional dark-themed dashboard. Transport is determined automatically:
 
-- **\`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.
+- **Inline MCP App transport** — No \`actions\`. Best for display-only content rendered inline in the host client.
+- **Browser transport** — \`actions\` present. Best when you need user interaction or full-page rendering outside the chat surface.
 
-## Format Selection Rules (MUST FOLLOW)
+## Transport 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 |
-| **Running in CLI mode** (no IDE chat panel) | **\`browser\`** | \`html\` UIResource is invisible in CLI — only plain markdown renders. Use \`browser\` so the system browser opens automatically with full rich visualization. |
+| Situation | Include \`actions\`? | Transport | Why |
+|-----------|----------------------|-----------|-----|
+| Display-only content (tables, charts, reports, status boards) | **No** | **Inline MCP App** | No interaction needed — render inline in the host client |
+| Need user input back (confirmations, selections, form data) | **Yes** | **Browser** | Actions trigger browser transport and return structured results |
+| Rich visual dashboards without interaction | **No** | **Inline MCP App** | Keep the result in-chat when no response is needed |
+| User explicitly asks for browser | **Yes** | **Browser** | Add at least one action to force browser transport |
+| **Running in CLI mode** and need a full visual surface | **Yes** | **Browser** | Inline MCP App rendering is IDE-hosted; add a minimal action so the browser opens |
 
-**Rule: If no user interaction is needed, use \`format: "html"\`. If you need user interaction, use \`format: "browser"\`.**
+**Rule: Omit \`actions\` for inline rendering. Add \`actions\` when you need browser transport or interaction back from the user.**
 
-> **⚠️ CLI Mode Override:** When running in CLI mode (terminal, not IDE chat), **always use \`format: "browser"\`** regardless of whether interaction is needed. The \`html\` format relies on UIResource rendering in the IDE's chat panel — in CLI, only the markdown fallback text is shown, losing all rich visualizations (charts, tables, dashboards). The \`browser\` format starts a local HTTP server and auto-opens the system browser after 8 seconds, which works reliably in any environment.
+> **⚠️ CLI Note:** CLI environments do not host inline MCP App surfaces. If you need a full visual dashboard from CLI, include a minimal \`actions\` array such as an \`Acknowledge\` button so the tool uses browser transport.
 
 ---
 
-## Browser Workflow (IMPORTANT — read carefully)
+## Browser Transport 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.
+When \`actions\` is present, the tool uses browser transport and opens the system browser. The selected action is returned to the model as structured data.
 
 ### 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 \`browser({ action: 'open', url: 'http://127.0.0.1:{port}', mode: 'ui' })\` - AI Kit browser tool to open it in the integrated browser**
+1. Call \`present\` with \`actions\` and your \`blocks\`
+2. Let the tool open the browser transport automatically
+3. Wait for the user's action result before continuing
 
 \`\`\`
-// Step 1: Call present
-result = present({ format: "browser", title: "...", content: [...], actions: [...] })
-
-// Step 2: MUST open in integrated browser
-browser({ action: 'open', url: 'http://127.0.0.1:{port}', mode: 'ui' }) // AI Kit browser tool - opens URL in the integrated browser
+result = present({
+  schemaVersion: 1,
+  title: "Review Dashboard",
+  blocks: [...],
+  actions: [{ id: "ack", type: "button", label: "Acknowledge" }]
+})
 \`\`\`
 
-> **Fallback**: The server also auto-opens the system browser as a safety net. But you should ALWAYS call \`browser({ action: 'open' })\` via the AI Kit browser tool yourself so the user sees it in their environment.
-
-**Note:** The HTTP server auto-closes after 5 minutes. Open the page promptly after receiving the URL.
+> **Important:** Do not document or call a separate \`browser({ action: 'open' })\` step for a \`present\` surface. Browser transport is selected by \`actions\`, not by a \`format\` parameter.
 
 ---
 
@@ -116,13 +115,13 @@ Actions are interactive buttons/selects. In \`browser\` mode, they render as cli
 
 ## Composition Pattern
 
-Compose a full dashboard by combining multiple blocks in the \`content\` array:
+Compose a full dashboard by combining multiple blocks in the \`blocks\` array:
 
 \`\`\`json
 {
-  "format": "browser",
+  "schemaVersion": 1,
   "title": "Sprint Review",
-  "content": [
+  "blocks": [
     { "type": "metrics", "title": "Key Metrics", "value": [...] },
     { "type": "chart", "title": "Velocity", "value": { "chartType": "area", ... } },
     { "type": "timeline", "title": "Milestones", "value": { "items": [...] } },
@@ -151,15 +150,15 @@ The dashboard uses a professional dark theme:
 
 ## Architecture Diagrams
 
-> **Behavioral rule:** When asked to present, visualize, or display system architecture, infrastructure, or service topology — **always load the \`c4-architecture\` skill** and use its HTML/SVG format (Method 2 below) for rich visual output via \`present\`. The Mermaid method (Method 1) is acceptable only for quick in-chat previews or when the user explicitly asks for Mermaid. Default to HTML/SVG for all architecture presentations.
+> **Behavioral rule:** When asked to present, visualize, or display system architecture, infrastructure, or service topology — **always load the \`c4-architecture\` skill** and use its HTML/SVG approach (Method 2 below) for rich visual output via \`present\`. The Mermaid method (Method 1) is acceptable only for quick inline previews or when the user explicitly asks for Mermaid. Default to HTML/SVG for all architecture presentations.
 
-The \`present\` tool can render C4-style architecture diagrams in both \`html\` and \`browser\` formats. The visual design system is centralized in the \`c4-architecture\` skill's reference file — load that skill for the full type registry, color palette, and template.
+The \`present\` tool can render C4-style architecture diagrams in either transport. Omit \`actions\` for inline rendering, or add \`actions\` when you need browser transport. The visual design system is centralized in the \`c4-architecture\` skill's reference file — load that skill for the full type registry, color palette, and template.
 
 **Design system source:** \`c4-architecture/references/html-design-system.md\` (single source of truth for all architecture diagram styling)
 
 ### When to Use (Auto-Trigger)
 
-Load the \`c4-architecture\` skill and use HTML/SVG format when the user:
+Load the \`c4-architecture\` skill and use the HTML/SVG approach when the user:
 - Asks to "show architecture", "present the system design", "visualize infrastructure"
 - Wants to display service topology, deployment layout, or component relationships
 - Requests architecture review output, system overview dashboards, or technical presentations
@@ -167,19 +166,19 @@ Load the \`c4-architecture\` skill and use HTML/SVG format when the user:
 
 ### Rendering Methods
 
-| Method | Block Type | Format | When to Use |
-|--------|-----------|--------|-------------|
-| Mermaid C4 | \`mermaid\` | html / browser | Quick diagrams, developer-focused, version-controlled |
-| HTML/SVG | \`markdown\` | html / browser | Rich visual presentations, stakeholder reviews, dark-themed dashboards |
+| Method | Block Type | Transport | When to Use |
+|--------|-----------|-----------|-------------|
+| Mermaid C4 | \`mermaid\` | Inline by default, browser if \`actions\` are present | Quick diagrams, developer-focused, version-controlled |
+| HTML/SVG | \`markdown\` | Inline by default, browser if \`actions\` are present | Rich visual presentations, stakeholder reviews, dark-themed dashboards |
 
 ### Method 1: Mermaid C4 Diagrams
 
 Use a \`mermaid\` content block with standard C4 Mermaid syntax:
 
 present({
-  format: "html",  // or "browser"
+  schemaVersion: 1,
   title: "System Architecture",
-  content: [
+  blocks: [
     {
       type: "mermaid",
       title: "C4 Container Diagram",
@@ -194,32 +193,32 @@ present({
 
 ## Rendering Troubleshooting
 
-### Why \`html\` format sometimes shows raw text
+### Why inline MCP App rendering sometimes shows raw text
 
-The \`html\` format renders content inside an MCP Apps companion iframe (UIResource). The chat text fallback is intentionally minimal (just the title). When the UIResource fails to load, the user sees only the title or raw JSON — NOT the rendered dashboard.
+Without \`actions\`, the surface renders inline through the MCP App host in the client. The chat text fallback is intentionally minimal. When the inline host fails to load, the user may see only the title or raw JSON instead of the rendered dashboard.
 
 **Common causes of UIResource rendering failure:**
-1. **MCP Apps not enabled** — The setting \`chat.mcp.apps.enabled\` must be \`true\` in VS Code settings
+1. **MCP Apps not enabled** — The host client must support MCP Apps (e.g., \`chat.mcp.apps.enabled\` in VS Code)
 2. **Companion app build missing** — The \`packages/present\` companion app must be built (\`npm run build\`)
 3. **Content too large** — Very large content arrays (20+ blocks or tables with 50+ rows) may cause the companion iframe to fail silently
 4. **Iframe loading error** — Network issues, CSP restrictions, or extension conflicts can prevent the iframe from loading
 
-### When to prefer \`browser\` over \`html\`
+### When to use browser transport instead of inline rendering
 
-Use \`format: "browser"\` instead of \`html\` when:
-- Content has **10+ blocks** or tables with **20+ rows** (large payloads are more reliable in browser)
-- The output must be **guaranteed visible** (browser format always opens, no silent failures)
-- You need **charts + tables + markdown** in the same view (browser renders all block types reliably)
-- The user reports that \`html\` format "didn't show anything" or "showed raw text"
+Add \`actions\` to force browser transport when:
+- Content has **10+ blocks** or tables with **20+ rows** (large payloads are often easier to review in a full page)
+- The output must be **guaranteed visible outside the IDE chat panel**
+- You need **charts + tables + markdown** in the same view and inline rendering is failing
+- The user reports that the inline surface "didn't show anything" or only showed fallback text
 
-> **Reliability rule:** If content is complex (5+ blocks of mixed types), prefer \`format: "browser"\` for guaranteed rendering. The \`html\` format is best for simple, single-block content.
+> **Reliability rule:** If content is complex (5+ blocks of mixed types) or the inline surface is failing, add a minimal \`actions\` array to force browser transport. Otherwise keep \`actions\` absent for inline rendering.
 
 ### Content formatting tips to avoid rendering issues
 
 1. **Use \`table\` block type** instead of markdown tables inside \`markdown\` blocks — \`table\` blocks render natively; markdown pipe-tables may show as raw text in fallback
 2. **Use \`cards\` and \`metrics\`** for summary data instead of embedding it in markdown text
 3. **Keep \`markdown\` blocks for narrative text only** — don't embed HTML, tables, or complex formatting
-4. **Split large content** into multiple smaller \`present\` calls rather than one massive content array
+4. **Split large content** into multiple smaller \`present\` calls rather than one massive \`blocks\` array
 5. **For charts:** Always use ChartValue format (\`chartType\`, \`data\`, \`xKey\`, \`yKeys\`) — NOT Chart.js format (\`labels\`, \`datasets\`)
 
 ---
@@ -244,13 +243,13 @@ Use \`format: "browser"\` instead of \`html\` when:
 
 For rich visual output, embed the full HTML/SVG diagram in a \`markdown\` block. Compose with \`metrics\` and \`cards\` blocks for a complete dashboard.
 
-**Both \`format: "html"\` and \`format: "browser"\` work with this approach.**
+**This approach works inline by default. Add \`actions\` only when you need browser transport.**
 
 \`\`\`js
 present({
-  format: "html",  // or "browser"
+  schemaVersion: 1,
   title: "System Architecture",
-  content: [
+  blocks: [
     {
       type: "metrics",
       title: "Overview",
@@ -299,7 +298,7 @@ The full type registry with sub-types and icon slots is in \`c4-architecture/ref
 
 ## Best Practices
 
-1. **Use \`browser\` format** for data-rich content — charts, tables, dashboards. **Always use \`browser\` in CLI mode** (the \`html\` UIResource doesn't render in terminal environments).
+1. **Use inline rendering by default** for display-only charts, tables, and dashboards. Add \`actions\` when you need browser transport, or when CLI requires a full visual surface.
 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
@@ -315,49 +314,49 @@ The full type registry with sub-types and icon slots is in \`c4-architecture/ref
 
 ## Rendering Troubleshooting
 
-### Why \`html\` format sometimes shows raw text
+### Why inline MCP App rendering sometimes shows raw text
 
-The \`html\` format renders content inside an MCP Apps companion iframe (UIResource). The chat text fallback is intentionally minimal (just the title). When the UIResource fails to load, the user sees only the title or raw JSON — NOT the rendered dashboard.
+Without \`actions\`, the surface renders inline through the MCP App host in the client. The chat text fallback is intentionally minimal. When the inline host fails to load, the user may see only the title or raw JSON instead of the rendered dashboard.
 
 **Common causes of UIResource rendering failure:**
-1. **MCP Apps not enabled** — The setting \`chat.mcp.apps.enabled\` must be \`true\` in VS Code settings
+1. **MCP Apps not enabled** — The host client must support MCP Apps (e.g., \`chat.mcp.apps.enabled\` in VS Code)
 2. **Companion app build missing** — The \`packages/present\` companion app must be built (\`npm run build\`)
 3. **Content too large** — Very large content arrays (20+ blocks or tables with 50+ rows) may cause the companion iframe to fail silently
 4. **Iframe loading error** — Network issues, CSP restrictions, or extension conflicts can prevent the iframe from loading
 
-### When to prefer \`browser\` over \`html\`
+### When to use browser transport instead of inline rendering
 
-Use \`format: "browser"\` instead of \`html\` when:
-- Content has **10+ blocks** or tables with **20+ rows** (large payloads are more reliable in browser)
-- The output must be **guaranteed visible** (browser format always opens, no silent failures)
-- You need **charts + tables + markdown** in the same view (browser renders all block types reliably)
-- The user reports that \`html\` format "didn't show anything" or "showed raw text"
+Add \`actions\` to force browser transport when:
+- Content has **10+ blocks** or tables with **20+ rows** (large payloads are often easier to review in a full page)
+- The output must be **guaranteed visible outside the IDE chat panel**
+- You need **charts + tables + markdown** in the same view and inline rendering is failing
+- The user reports that the inline surface "didn't show anything" or only showed fallback text
 
-> **Reliability rule:** If content is complex (5+ blocks of mixed types), prefer \`format: "browser"\` for guaranteed rendering. The \`html\` format is best for simple, single-block content.
+> **Reliability rule:** If content is complex (5+ blocks of mixed types) or the inline surface is failing, add a minimal \`actions\` array to force browser transport. Otherwise keep \`actions\` absent for inline rendering.
 
 ### Content formatting tips to avoid rendering issues
 
 1. **Use \`table\` block type** instead of markdown tables inside \`markdown\` blocks — \`table\` blocks render natively; markdown pipe-tables may show as raw text in fallback
 2. **Use \`cards\` and \`metrics\`** for summary data instead of embedding it in markdown text
 3. **Keep \`markdown\` blocks for narrative text only** — don't embed HTML, tables, or complex formatting
-4. **Split large content** into multiple smaller \`present\` calls rather than one massive content array
+4. **Split large content** into multiple smaller \`present\` calls rather than one massive \`blocks\` array
 5. **For charts:** Always use ChartValue format (\`chartType\`, \`data\`, \`xKey\`, \`yKeys\`) — NOT Chart.js format (\`labels\`, \`datasets\`)
 
 ---
 
-## MCP Apps Templates (VS Code Chat Widgets)
+## MCP Apps Templates
 
-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.
+When the host client supports MCP Apps, the \`present\` tool can render **interactive widgets directly in the chat panel** using the \`template\` parameter. These are distinct from block-based surfaces rendered inline or in the browser.
 
-**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.
+**Key difference:** Templates use \`template\` + object \`data\` (not a \`blocks\` array). No \`format\` parameter exists. Templates render inline in the host client unless a separate \`actions\` array is added at the top level.
 
 ### 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 |
+| Rich multi-section dashboard with charts | **Browser transport** | Add \`actions\` for a full page layout |
+| Simple confirmation or selection | **Actions-enabled surface** | Adding \`actions\` switches transport to browser |
 
 ### Template: \`list-sort\`
 
@@ -367,7 +366,7 @@ Drag-and-drop reorderable list. Use for priority ordering, task sequencing, or r
 {
   "template": "list-sort",
   "title": "Priority Order",
-  "content": {
+  "data": {
     "items": [
       { "id": "task-1", "label": "Fix authentication bug" },
       { "id": "task-2", "label": "Add search feature" },
@@ -388,7 +387,7 @@ Filterable, sortable table with optional summary stat cards. Use for structured
 {
   "template": "data-table",
   "title": "File Changes",
-  "content": {
+  "data": {
     "columns": [
       { "key": "file", "label": "File" },
       { "key": "change", "label": "Change" },
@@ -417,7 +416,7 @@ Multi-select with categories and tag-based search. Use for component selection,
 {
   "template": "picker",
   "title": "Select Modules",
-  "content": {
+  "data": {
     "categories": [
       { "id": "core", "label": "Core" },
       { "id": "plugins", "label": "Plugins" }
@@ -442,7 +441,7 @@ Hierarchical zoomable visualization. Use for codebase structure, performance pro
 {
   "template": "flame-graph",
   "title": "Module Hierarchy",
-  "content": {
+  "data": {
     "profile": {
       "name": "root",
       "total": 100,
@@ -473,7 +472,7 @@ Input fields with text inputs, selects, and checkboxes. Use for configuration, p
 {
   "template": "form",
   "title": "Project Configuration",
-  "content": {
+  "data": {
     "fields": [
       { "name": "projectName", "label": "Project Name", "type": "text", "value": "my-app" },
       { "name": "framework", "label": "Framework", "type": "select", "options": ["React", "Vue", "Svelte"], "value": "React" },