pmx-canvas 0.1.5 → 0.1.6

package/skills/pmx-canvas/SKILL.md

@@ -22,14 +22,41 @@ relatedness, clusters imply grouping, reading order (top-left to bottom-right) i
 
 ## When to Use
 
-- **Investigation boards** — lay out files, logs, stack traces, and findings spatially while debugging
-- **Architecture diagrams** — show system components and their relationships
-- **Plans & task tracking** — create task nodes with dependencies and color-coded status
-- **Status dashboards** — display build results, test output, deployment state
-- **Context maps** — show how code, configs, and data flow connect
-- **Code dependency graphs** — visualize file imports and module relationships
-- **Comparison views** — place options side by side for the human to evaluate
-- **Any time spatial layout helps** — when a flat list or text wall is not enough
+The canvas is **agnostic about what you do with it**. Reach for it whenever a
+flat conversation, a list, or a single document hides the relationships
+between pieces of information. The total reach of any session is the union
+of pmx-canvas's own node types and whatever your harness already has access
+to — MCP servers, MCP apps, shell commands and CLIs, files in the working
+directory, web fetch, anything else in your toolbelt. The canvas does not
+care where the data came from; it cares about getting it on the surface as
+the right node type.
+
+The README has a non-exhaustive list of example use cases (idea generation,
+validation, research, analysis, mind mapping, investigation boards,
+architecture diagrams, status dashboards, comparison views, plus whatever
+your toolbelt unlocks). This skill stays focused on the operational
+mechanics. If a flat list or text wall is not enough to hold the
+relationships you're working with, the canvas is the right tool — the rest
+of this document is how to drive it.
+
+### When the connected tool is unfamiliar
+
+When the human asks you to use a data source or tool you have not used
+before — an MCP server, an MCP app, a CLI, a script, an arbitrary file
+tree:
+
+1. List the tools / commands available; sample one or two outputs to see
+   the actual shape.
+2. Decide which canvas node type best matches each output:
+   - Long-form / narrative results → `markdown`
+   - Structured records, tables, dashboards → `json-render` or `graph`
+   - Interactive tool surfaces with their own UI → `mcp-app` (open with
+     `canvas_open_mcp_app`)
+   - Local source files → `file` (live-watched)
+   - URLs that need cached fetches → `webpage`
+   - Stream of state events → `status` or `ledger`
+3. Propose the mapping to the human before bulk-creating nodes; let them
+   confirm or adjust before you commit a layout.
 
 ## Starting the Canvas
 
@@ -46,11 +73,31 @@ pmx-canvas --no-open           # Start without opening browser (for agents)
 pmx-canvas --port=8080         # Custom port
 pmx-canvas --demo              # Start with sample content
 pmx-canvas --theme=light       # Light theme
+pmx-canvas --version           # Print installed version and exit
 ```
 
+`--theme` accepts `dark` (default), `light`, or `high-contrast`. Same value can be set via
+the `PMX_CANVAS_THEME` environment variable, or toggled live in the browser toolbar.
+
 Start the canvas once per session, then reuse it. Use `--no-open` when running as an agent — the
 human can open the browser URL themselves.
 
+### Daemon mode (long-running background server)
+
+When you need the canvas to outlive the current shell or agent session — e.g. so a follow-up
+agent run can attach to the same state — start it as a daemon:
+
+```bash
+pmx-canvas serve --daemon --no-open --wait-ms=20000   # Detach, wait for /health
+pmx-canvas serve status                                # Print daemon health + pid state
+pmx-canvas serve stop                                  # Stop the daemon for this port
+```
+
+`serve --daemon` writes a pid file (`.pmx-canvas/daemon-<port>.pid`) and a log file
+(`.pmx-canvas/daemon-<port>.log`); the wait flag blocks until `/health` returns OK so a script
+can rely on the server being responsive when the command returns. `serve stop` reads the pid
+file, sends SIGTERM, and cleans up on exit.
+
 ## Browser Workflows
 
 The browser is not just a passive view. Human interactions on the canvas persist back to the
@@ -86,6 +133,7 @@ pmx-canvas node add --type markdown --title "Plan"
 pmx-canvas node add --type webpage --url https://example.com/docs
 pmx-canvas node add --type graph --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y
 pmx-canvas node add --type graph --graphType bar --data '[{"x":"a","y":1}]' --xKey x --yKey y
+pmx-canvas graph add --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y
 pmx-canvas external-app add --kind excalidraw --title "Diagram"
 pmx-canvas node add --help --type webpage --json
 pmx-canvas node schema --type json-render --component Table --summary
@@ -109,7 +157,11 @@ pmx-canvas spatial
 
 - `node add|list|get|update|remove` — manage nodes
 - `node schema` — inspect running-server create schemas and canonical examples, with `--summary`, `--field`, and `--component` filters
+- `graph add` — convenience alias for graph nodes; `node add --type graph` remains the canonical form
 - Graph CLI fields accept both kebab-case flags and camelCase schema names, e.g. `--graph-type`/`--graphType`, `--x-key`/`--xKey`, and `--bar-color`/`--barColor`.
+- Graph CLI height flags are split: use `--node-height`/`--nodeHeight` for the
+  canvas frame and `--chart-height` for the chart content. CLI `--height`
+  remains a frame-height compatibility alias.
 - `edge add|list|remove` — manage edges
 - Search-based edge selectors must be specific enough to resolve exactly one node. Queries like
   `"DVT O3"` can be ambiguous; prefer the full visible title such as `"DVT O3 — GitOps"`.
@@ -139,6 +191,8 @@ Current caveat:
 - Generic `pmx-canvas node add --type mcp-app` is intentionally not supported because app nodes
   need app/session metadata. Use `pmx-canvas web-artifact build` for bundled React artifacts or
   `pmx-canvas external-app add --kind excalidraw` for the Excalidraw preset.
+- For local `image` nodes on macOS, iCloud/OneDrive cloud-only placeholder files are rejected with
+  a download-first hint. Download the image locally before adding it to the canvas.
 
 The CLI targets `http://localhost:4313` by default. Override with `PMX_CANVAS_URL` or
 `PMX_CANVAS_PORT` when the canvas is running elsewhere.
@@ -160,8 +214,8 @@ The CLI targets `http://localhost:4313` by default. Override with `PMX_CANVAS_UR
 | `json-render` | Native structured UI panel | Dashboards, forms, tables, interactive layouts from json-render specs |
 | `graph` | Native chart panel | Line, bar, pie, area, scatter, radar, stacked-bar, and composed charts rendered inside the canvas |
 | `group` | Spatial container/frame | Visually group related nodes together |
-| `prompt` | Prompt thread root | Canvas-native prompt entry points for agent conversations |
-| `response` | Prompt reply / streamed answer | Agent responses linked to prompt threads |
+| `prompt` | Prompt thread root | Canvas-native prompt entry points for agent conversations. **Internal type — surfaces in `canvas://layout` for thread rendering but is not created via the public `canvas_add_node` API. Don't try to add one directly.** |
+| `response` | Prompt reply / streamed answer | Agent responses linked to prompt threads. **Same internal-only restriction as `prompt`.** |
 
 ### Edge Types
 
@@ -196,8 +250,22 @@ Use color consistently to convey meaning:
 
 ### Node Operations
 
+MCP node-type routing:
+
+| Node category | MCP creation tool |
+|---------------|-------------------|
+| Basic nodes (`markdown`, `status`, `context`, `ledger`, `trace`, `file`, `image`, `webpage`) | `canvas_add_node` |
+| `json-render` | `canvas_add_json_render_node` |
+| `graph` | `canvas_add_graph_node` |
+| `web-artifact` | `canvas_build_web_artifact` |
+| `external-app` / tool-backed `mcp-app` | `canvas_open_mcp_app` |
+| `group` | `canvas_create_group` |
+
+If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` and read
+`mcp.nodeTypeRouting`; do not keep retrying the generic tool.
+
 **`canvas_add_node`** — Add a node to the canvas
-- `type` (required): node type (see table above)
+- `type` (required): basic node type only; structured/app/group nodes use the routing table above
 - `title`: short, scannable title
 - `content`: for most types, this is markdown text. For `file` type, pass the **file path**
   (e.g., `"src/auth/login.ts"`) — the server auto-loads the file content and watches for changes.
@@ -220,10 +288,30 @@ Use color consistently to convey meaning:
 **`canvas_get_node`** — Get a single node's full data
 - `id` (required): node to retrieve
 
+**`canvas_refresh_webpage_node`** — Re-fetch the URL stored on a `webpage` node
+- `id` (required): webpage node to refresh
+- Optional `url`: replace the stored URL before refreshing (use when the human moved the page)
+- Returns the refreshed node with updated `pageTitle` and cached extracted text
+- Use this when a saved canvas is reopened and the agent needs fresh page content without
+  losing the node's identity, position, or pins. Example flow:
+
+  ```typescript
+  // Add the page once
+  canvas_add_node({ type: 'webpage', url: 'https://example.com/docs' })
+  // → returns { id: 'node-abc' }
+
+  // …later, after the human reopens the canvas…
+  canvas_refresh_webpage_node({ id: 'node-abc' })
+  // → re-fetches the URL, updates pageTitle + extracted text, keeps the node ID and position
+  ```
+
 **`canvas_add_json_render_node`** — Add a native json-render node
 - Required: `title`, `spec`
 - The `spec` must be a complete json-render object with `root`, `elements`, and optional `state`
 - Use this when you want a structured UI panel rendered directly inside PMX Canvas
+- For shadcn `Badge`, prefer `props.text` with variants `default`, `secondary`, `destructive`, or
+  `outline`. Legacy `props.label` and status variants (`success`, `info`, `warning`, `error`,
+  `danger`) are normalized for saved-spec compatibility.
 
 **`canvas_add_graph_node`** — Add a native graph/chart node
 - Required: `graphType`, `data`
@@ -235,10 +323,29 @@ Use color consistently to convey meaning:
 - Use `axisKey` plus `metrics` for radar graphs
 - Use `series` for stacked-bar graphs
 - Use `barKey`/`lineKey` plus optional `barColor`/`lineColor` for composed graphs
+- Use `nodeHeight` for the canvas frame height and `height` for chart content height
 - Uses the native json-render chart catalog under the hood
 
+**`canvas_build_web_artifact`** — Build and optionally open a bundled web artifact
+- Required: `title`, `appTsx` (source string contents, not a file path)
+- CLI `--app-file` reads a file before calling the same build path; MCP callers must pass the source contents
+- Cold builds commonly take 45-60 seconds; use a long client timeout such as 300000 ms or more
+- Returns both `id` and `nodeId` for the created artifact node when `openInCanvas` is true
+
+**`canvas_open_mcp_app`** — Open a tool-backed external MCP app node
+- Required: `toolName`, `transport`
+- `transport` is either `{ type: "stdio", command, args?, cwd?, env? }` or `{ type: "http", url, headers? }`
+- This is lower-level than `pmx-canvas external-app add --kind excalidraw`; use `canvas_add_diagram` for the built-in Excalidraw preset
+
+**`canvas_pin_nodes`** — Set, add, or remove pinned context nodes
+- Use `{ nodeIds: [...] }`; the field is `nodeIds`, not `ids`
+
+**`canvas_diff`** — Compare current canvas state with a saved snapshot
+- Requires `{ snapshot: "<snapshot-id-or-name>" }`; there is no implicit previous-snapshot default
+
 **`canvas_describe_schema`** — Inspect the running server's create schemas and canonical examples
 - Use this before generating structured payloads when you need the authoritative current shape
+- Read `mcp.nodeTypeRouting` to choose the right MCP creation tool for each node category
 
 **`canvas_validate_spec`** — Validate a json-render spec or graph payload without creating a node
 - Returns the normalized json-render spec the server would accept
@@ -251,6 +358,7 @@ Use color consistently to convey meaning:
   `xKey`, `yKey`, `zKey`, `nameKey`, `valueKey`, `axisKey`, `metrics`, `series`, `barKey`,
   `lineKey`, `aggregate`, `color`, `barColor`, `lineColor`, `height`, `x`, `y`, `width`, and
   `nodeHeight`.
+- In batch/MCP/HTTP payloads, `height` is chart content height and `nodeHeight` is the canvas frame height.
 
 ### Edge Operations
 
@@ -369,6 +477,58 @@ Current product caveats for grouped comparison boards:
 - **Always call `canvas_snapshot` first** to save a backup before clearing
 - This is irreversible without a prior snapshot
 
+### Browser Automation (WebView)
+
+The canvas exposes a headless browser session over MCP for self-inspection and
+automated screenshotting. Use this when you want to (a) verify what the live
+canvas actually looks like after a sequence of mutations, (b) capture an image
+of a freshly-built artifact for the human to review, or (c) drive arbitrary
+JavaScript inside the workbench page.
+
+The WebView automation runs on Bun's WebKit-based WebView (macOS) or a headless
+Chromium fallback (Linux). It does **not** open a visible window; it's an
+additional headless renderer attached to the same canvas server, so all five
+tools below operate on the live canvas state.
+
+**`canvas_webview_status`** — Inspect the current automation session
+- Returns `{ supported, active, backend, viewportWidth, viewportHeight, url, lastError }`
+- Call before `start` to check whether a session is already alive
+
+**`canvas_webview_start`** — Start (or replace) the automation session
+- Optional: `backend` (`webkit` macOS-only, or `chrome`), `width`, `height`
+- The session opens `/workbench` at the canvas URL, waits for the SPA to
+  hydrate, and reports back via `canvas_webview_status`
+
+**`canvas_webview_stop`** — Tear down the automation session
+
+**`canvas_evaluate`** — Run JavaScript inside the workbench page and return the result
+- Required: `expression` (a JS expression or a function body)
+- Useful for asserting DOM state after a sequence of canvas mutations
+- Example: read the count of rendered `.canvas-node` elements:
+
+  ```typescript
+  canvas_evaluate({ expression: 'document.querySelectorAll(".canvas-node").length' })
+  ```
+
+**`canvas_resize`** — Change the WebView viewport
+- Required: `width`, `height`
+- Use before `canvas_screenshot` when the human needs a specific aspect ratio
+
+**`canvas_screenshot`** — Capture a PNG of the current workbench
+- Optional: `format` (`png` default), `fullPage` (boolean)
+- Returns both an MCP image payload (renderable inline by capable agents) and
+  a path under `.pmx-canvas/screenshots/` so the human can view the file
+- Pair with `canvas_resize` to control the framing
+
+Typical flow when you want to show a result:
+
+```typescript
+canvas_webview_start({ width: 1440, height: 900 });
+// …mutations…
+canvas_screenshot({ fullPage: true });
+canvas_webview_stop();
+```
+
 ### Diagrams (Excalidraw MCP app preset)
 
 **`canvas_add_diagram`** — Draw a hand-drawn diagram on the canvas via the hosted
@@ -432,7 +592,8 @@ what the human has set up and what they're focusing on.
 | `canvas://summary` | Compact overview: node counts by type, pinned titles |
 | `canvas://spatial-context` | Proximity clusters, reading order, pinned neighborhoods |
 | `canvas://history` | Human-readable mutation timeline |
-| `canvas://code-graph` | Auto-detected file import dependencies |
+| `canvas://code-graph` | Auto-detected file import dependencies (JS/TS, Python, Go, Rust) |
+| `canvas://skills` | Index of bundled agent skills shipped with the install. Each skill is also addressable as `canvas://skills/<name>` (e.g. `canvas://skills/web-artifacts-builder`) and returns the full SKILL.md. Read this resource first to discover companion workflows the canvas is built to support. |
 
 ### Reading Spatial Intent
 
@@ -493,6 +654,12 @@ All POST/PATCH endpoints accept `Content-Type: application/json`. Default base U
 
 ## Workflow Patterns
 
+These are **operational recipes** — how to sequence canvas calls for a few
+recurring shapes of work. They are not the project's use cases (those live
+in the README and are intentionally non-exhaustive). The patterns here exist
+to make the agent's tool-call sequencing concrete: which MCP tool fires
+when, what to pin, when to read `canvas://pinned-context`, when to snapshot.
+
 ### Responding to Pinned Context
 
 When the human pins nodes, they're telling you what matters. This is the most important

package/src/cli/agent.ts

@@ -229,6 +229,18 @@ function optionalPositiveFiniteFlag(flags: Record<string, string | true>, name:
   return parsed;
 }
 
+function optionalPositiveFiniteFlagWithAliases(
+  flags: Record<string, string | true>,
+  hint: string,
+  ...names: string[]
+): number | undefined {
+  for (const name of names) {
+    const parsed = optionalPositiveFiniteFlag(flags, name, hint);
+    if (parsed !== undefined) return parsed;
+  }
+  return undefined;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === 'object' && !Array.isArray(value);
 }
@@ -590,7 +602,13 @@ async function buildGraphRequestBody(
   const x = optionalFiniteFlag(flags, 'x', 'Use a finite number, e.g. --x 500');
   const y = optionalFiniteFlag(flags, 'y', 'Use a finite number, e.g. --y 300');
   const width = optionalPositiveFiniteFlag(flags, 'width', 'Use a positive number, e.g. --width 760');
-  const nodeHeight = optionalPositiveFiniteFlag(flags, 'height', 'Use a positive number, e.g. --height 520');
+  const nodeHeight = optionalPositiveFiniteFlagWithAliases(
+    flags,
+    'Use a positive number, e.g. --node-height 520',
+    'node-height',
+    'nodeHeight',
+    'height',
+  );
   if (chartHeight !== undefined) body.height = chartHeight;
   if (x !== undefined) body.x = x;
   if (y !== undefined) body.y = y;
@@ -992,6 +1010,18 @@ cmd('node add', 'Add a node to the canvas', [
   output(result);
 });
 
+cmd('graph add', 'Add a graph node to the canvas', [
+  'pmx-canvas graph add --graph-type bar --data-file ./metrics.json --x-key label --y-key value',
+  'pmx-canvas graph add --graphType composed --data \'[{"day":"Mon","visits":10,"conversion":0.4}]\' --xKey day --barKey visits --lineKey conversion',
+  'pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('graph add');
+
+  const result = await api('POST', '/api/canvas/graph', await buildGraphRequestBody(flags));
+  output(result);
+});
+
 cmd('node schema', 'Describe server-supported node create schemas and canonical examples', [
   'pmx-canvas node schema',
   'pmx-canvas node schema --type webpage',
@@ -2056,9 +2086,10 @@ function showCommandHelp(name: string): void {
     console.log('  pmx-canvas node add --help --type graph');
     console.log('  pmx-canvas node add --help --type webpage --json');
   }
-  if (name === 'node add' || name === 'validate spec') {
+  if (name === 'node add' || name === 'graph add' || name === 'validate spec') {
     console.log('\nGraph flags:');
     console.log('  Graph fields accept kebab-case CLI flags and camelCase schema names, e.g. --graph-type/--graphType and --x-key/--xKey');
+    console.log('  Use --node-height/--nodeHeight for canvas frame height; use --chart-height for chart content height. --height is kept as a frame-height alias for compatibility.');
   }
   if (name === 'node schema') {
     console.log('\nFilters:');
@@ -2112,6 +2143,7 @@ Node commands:
   pmx-canvas node get <id>            Get a node by ID
   pmx-canvas node update <id> [opts]  Update a node
   pmx-canvas node remove <id>         Remove a node
+  pmx-canvas graph add [options]      Add a graph node
 
 Edge commands:
   pmx-canvas edge add [options]       Add an edge between nodes
@@ -2179,6 +2211,7 @@ Examples:
   pmx-canvas node add --type json-render --title "Dashboard" --spec-file ./dashboard.json
   pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx
   pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value
+  pmx-canvas graph add --graph-type bar --data-file ./metrics.json --x-key label --y-key value
   pmx-canvas node add --help --type webpage
   pmx-canvas node schema --type json-render
   pmx-canvas node schema --type json-render --component Table --summary

package/src/cli/index.ts

@@ -31,7 +31,7 @@ if (args.includes('--version') || args.includes('-v')) {
 const AGENT_COMMANDS = new Set([
   'node', 'edge', 'search', 'layout', 'status', 'arrange', 'focus',
   'pin', 'undo', 'redo', 'history', 'snapshot', 'diff', 'group', 'webview', 'open',
-  'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'external-app', 'batch', 'validate', 'serve',
+  'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'external-app', 'graph', 'batch', 'validate', 'serve',
 ]);
 
 const firstArg = args[0] ?? '';
@@ -486,6 +486,7 @@ Server options:
 
 Agent CLI (works against running server):
   node add|list|get|update|remove     Manage nodes
+  graph add                           Add graph nodes (alias for node add --type graph)
   edge add|list|remove                Manage edges
   webview status|start|evaluate|resize|screenshot|stop
                                       Manage Bun.WebView automation session
@@ -540,6 +541,7 @@ Examples:
   pmx-canvas node add --type webpage --url "https://example.com"  Add a webpage node
   pmx-canvas node add --type json-render --title "Dashboard" --spec-file ./dashboard.json
   pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx
+  pmx-canvas graph add --graph-type bar --data-file ./metrics.json --x-key label --y-key value
   pmx-canvas node list                                        List all nodes
   pmx-canvas node schema --type json-render                   Show running-server schema info
   pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx

package/src/json-render/server.ts

@@ -262,6 +262,14 @@ function normalizeButtonVariant(value: unknown): unknown {
   return value;
 }
 
+function normalizeBadgeVariant(value: unknown): unknown {
+  if (value === 'success') return 'default';
+  if (value === 'info') return 'secondary';
+  if (value === 'warning') return 'outline';
+  if (value === 'error' || value === 'danger') return 'destructive';
+  return value;
+}
+
 function deriveElementName(elementKey: string): string {
   const normalized = elementKey.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
   return normalized || 'field';
@@ -325,6 +333,22 @@ function normalizeElementProps(
     props.text = props.content;
   }
 
+  if (type === 'Badge') {
+    if (!hasString(props.text) && hasString(props.label)) {
+      props.text = props.label;
+    }
+    // Drop the legacy alias once it's been migrated so the persisted spec
+    // contains exactly one of `text` or `label` rather than both. Keeps
+    // saved canvases tidy and prevents future stricter validators from
+    // flagging the old key as unknown.
+    if ('label' in props) {
+      delete props.label;
+    }
+    if ('variant' in props) {
+      props.variant = normalizeBadgeVariant(props.variant);
+    }
+  }
+
   if (type === 'Select' || type === 'Radio') {
     if (!Array.isArray(props.options) && Array.isArray(props.items)) {
       props.options = normalizeLabelArray(props.items);

package/src/mcp/server.ts

@@ -47,6 +47,13 @@ const jsonRenderSpecSchema = z.object({
   state: z.record(z.string(), z.unknown()).optional(),
 }).passthrough();
 
+function structuredSchemaDescription(): string {
+  const routing = describeCanvasSchema().mcp.nodeTypeRouting;
+  return Object.entries(routing)
+    .map(([type, tool]) => `${type}: ${tool}`)
+    .join(', ');
+}
+
 function workspaceRoot(): string {
   return resolve(process.cwd());
 }
@@ -127,7 +134,7 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_add_node ────────────────────────────────────────────
   server.tool(
     'canvas_add_node',
-    'Add a node to the canvas. Returns the created node with normalized title/content and rendered geometry. Node types: markdown (rich content), status (compact indicator), context, ledger, trace, file (live file viewer — set content to a file path), image (set content to an image file path, data URI, or URL), webpage (prefer url for the page URL; content is still accepted), mcp-app. Use canvas_add_json_render_node, canvas_add_graph_node, and canvas_build_web_artifact for structured UI, graph, and artifact nodes.',
+    'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, status, context, ledger, trace, file, image, webpage, mcp-app, group. Dedicated node tools: json-render -> canvas_add_json_render_node, graph -> canvas_add_graph_node, web-artifact -> canvas_build_web_artifact, external apps -> canvas_open_mcp_app, groups -> canvas_create_group. Call canvas_describe_schema for the full nodeTypeRouting table.',
     {
       type: z.enum(['markdown', 'status', 'context', 'ledger', 'trace', 'file', 'image', 'webpage', 'mcp-app', 'group'])
         .describe('Node type (prefer canvas_create_group for groups)'),
@@ -171,7 +178,7 @@ export async function startMcpServer(): Promise<void> {
 
   server.tool(
     'canvas_open_mcp_app',
-    'Connect to an external MCP server that declares a ui:// app resource, call the specified tool, and open the resulting MCP App inside a canvas mcp-app node.',
+    'Connect to an external MCP server that declares a ui:// app resource, call the specified tool, and open the resulting MCP App inside a canvas mcp-app node. This is a full external-MCP transport call, not the CLI kind shortcut; use canvas_add_diagram for the built-in Excalidraw preset.',
     {
       toolName: z.string().describe('Tool name on the external MCP server'),
       serverName: z.string().optional().describe('Optional display name for the external MCP server'),
@@ -261,7 +268,7 @@ export async function startMcpServer(): Promise<void> {
 
   server.tool(
     'canvas_describe_schema',
-    'Describe the current server-supported canvas create schemas, json-render component catalog, canonical examples, and related MCP entry points.',
+    'Describe the current server-supported canvas create schemas, json-render component catalog, canonical examples, and related MCP entry points. Includes mcp.nodeTypeRouting, the authoritative map from node type to MCP creation tool.',
     {},
     async () => ({
       content: [{ type: 'text', text: JSON.stringify(describeCanvasSchema(), null, 2) }],
@@ -356,7 +363,7 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_build_web_artifact ───────────────────────────────
   server.tool(
     'canvas_build_web_artifact',
-    'Build a bundled single-file HTML web artifact from React/Tailwind source files using the bundled web-artifacts-builder skill scripts. Optionally opens the generated artifact as an embedded node on the canvas. Read canvas://skills/web-artifacts-builder for the full workflow, stack, and anti-slop design guidelines before calling.',
+    'Build a bundled single-file HTML web artifact from React/Tailwind source files using the bundled web-artifacts-builder skill scripts. MCP callers pass source content in appTsx (the CLI app-file flag reads a file before calling this path). Builds commonly take 45-60s on cold workspaces; use a long client timeout. Optionally opens the generated artifact as an embedded node on the canvas. Read canvas://skills/web-artifacts-builder for the full workflow, stack, and anti-slop design guidelines before calling.',
     {
       title: z.string().describe('Artifact title used for default project and output paths'),
       appTsx: z.string().describe('Contents for src/App.tsx'),
@@ -407,6 +414,9 @@ export async function startMcpServer(): Promise<void> {
               bytes: result.fileSize,
               projectPath: result.projectPath,
               openedInCanvas: result.openedInCanvas,
+              // `id` only present when a canvas node was actually created.
+              // See the matching block in src/server/server.ts handleCanvasBuildWebArtifact.
+              ...(typeof result.nodeId === 'string' ? { id: result.nodeId } : {}),
               nodeId: result.nodeId,
               url: result.url,
               metadata: result.metadata,
@@ -1003,7 +1013,7 @@ export async function startMcpServer(): Promise<void> {
     'canvas://schema',
     {
       description:
-        'Machine-readable create schemas, canonical examples, and json-render catalog details from the running PMX Canvas server version.',
+        `Machine-readable create schemas, canonical examples, json-render catalog details, and MCP node-type routing from the running PMX Canvas server version. Routing: ${structuredSchemaDescription()}.`,
       mimeType: 'application/json',
     },
     async () => ({