@vpxa/kb 0.1.31 → 0.1.33

package/scaffold/general/agents/Researcher-Beta.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Research variant for multi-model decision protocol — different LLM perspective'
 argument-hint: Research question, problem statement, or subsystem to investigate
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, knowledge-base/*]
 model: Claude Sonnet 4.6 (copilot)
 ---
 

package/scaffold/general/agents/Researcher-Delta.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Research variant for multi-model decision protocol — different LLM perspective'
 argument-hint: Research question, problem statement, or subsystem to investigate
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, knowledge-base/*]
 model: Gemini 3.1 Pro (Preview) (copilot)
 ---
 

package/scaffold/general/agents/Researcher-Gamma.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Research variant for multi-model decision protocol — different LLM perspective'
 argument-hint: Research question, problem statement, or subsystem to investigate
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, knowledge-base/*]
 model: GPT-5.4 (copilot)
 ---
 

package/scaffold/general/agents/Security.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Security specialist that analyzes code for vulnerabilities and compliance'
 argument-hint: Code, feature, or component to security review
-tools: [execute/runInTerminal, read/problems, read/readFile, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, knowledge-base/*]
 model: Claude Opus 4.6 (copilot)
 ---
 

package/skills/present/SKILL.md

@@ -1,36 +1,48 @@
 ---
 name: present
-description: "Use the KB `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, and composition patterns. Load this skill before calling the present tool to ensure professional output."
-argument-hint: "Content to present — data, analysis results, status report, comparison"
+description: "Use the KB `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:
 
-- **`browser`** (recommended) — Serves a themed dashboard on a local URL and returns it in the response. **You must open the URL** using the `openBrowserPage` browser tool to display it in VS Code's integrated browser. Supports interactive action buttons that block until the user clicks.
-- **`html`** — Renders an embedded UIResource for MCP-UI hosts. Actions shown as numbered text choices.
+- **`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.
 
-**Always prefer `format: "browser"`** for rich content. Use `"html"` only when the host doesn't support browser mode.
+## 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)
+## Browser Workflow (IMPORTANT — read carefully)
 
-When using `format: "browser"`, the `present` tool does **not** open the page automatically. Follow this workflow:
+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.
 
-1. Call `present` with `format: "browser"` — it returns text containing `🌐 **Dashboard opened in browser:** http://127.0.0.1:{port}`
-2. Extract the URL from the response
-3. Call `openBrowserPage` with that URL to display the dashboard in VS Code's integrated browser
+### 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: [...] })
+result = present({ format: "browser", title: "...", content: [...], actions: [...] })
 
-// Step 2: Open in VS Code integrated browser
+// 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.
 
 ---
@@ -151,3 +163,262 @@ The dashboard uses a professional dark theme:
    - 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 | — |