pmx-canvas 0.1.18 → 0.1.19

package/docs/evals/e2e-cli-coverage.md

@@ -0,0 +1,61 @@
+---
+id: eval-20260424-001
+pattern-key: pmx-canvas.cli-e2e-fresh-workspace
+source: pmx-canvas-0.1.2-e2e-cli-coverage-report
+promoted-rule: "Fresh-workspace CLI coverage must verify node creation, parseable JSON, web-artifact failure behavior, external apps, arrange/validate, and focus no-pan before release."
+promoted-to: package.json test:e2e-cli
+created: 2026-04-24
+last-run: 2026-04-25
+last-result: pass
+---
+
+# PMX Canvas CLI E2E Coverage Eval
+
+## What This Tests
+
+Prevents regressions in the published-agent CLI flows that caused the 0.1.2 E2E report failures.
+
+## Precondition
+
+- Bun is installed.
+- The repo has been built with `bun run build` when client/browser assets changed.
+- Network is available for the hosted Excalidraw MCP preset and web-artifact dependency install.
+- Port `4567` is free, or `PMX_CANVAS_E2E_PORT` is set to a free port.
+
+## Verification Method
+
+Command check:
+
+```bash
+bun run test:e2e-cli
+```
+
+The command runs `scripts/e2e-cli-coverage.sh`, which creates a fresh temp workspace, starts the local PMX Canvas CLI server, and verifies:
+
+- `layout` and `node list` emit JSON parseable by Python's `json` module.
+- Core node types can be created through the CLI, including two webpage input paths.
+- Graph nodes accept `--data` as an alias for `--data-json`.
+- All graph variants create successfully: line, bar, pie, area, scatter, radar, stacked-bar, composed.
+- Simple and dashboard-shaped json-render specs create successfully.
+- Generic `node add --type mcp-app` is rejected with guidance.
+- `external-app add --kind excalidraw` creates a tool-backed app node.
+- Broken web-artifact builds return `ok: false`, exit non-zero, and do not create a node.
+- One successful web-artifact build emits a substantial bundled React/Recharts app, opens a node, and browser-verifies the real app content renders in the iframe.
+- `focus --no-pan` selects without viewport panning.
+- `arrange --layout grid` and `validate` agree on a valid layout.
+- Search can find artifact nodes and `status` reports expected graph/json-render/web-artifact counts.
+
+## Expected Result
+
+**Pass:** `PMX Canvas CLI E2E coverage passed` and exit code 0.
+
+**Fail:** Any command exits non-zero, JSON parsing fails, an assertion fails, or the server does not become healthy.
+
+## Recovery Action
+
+If this eval fails:
+
+1. Re-run with `PMX_CANVAS_E2E_KEEP_WORKDIR=1 bun run test:e2e-cli` to preserve the temp workspace.
+2. Inspect the preserved `.pmx-canvas/` state and `pmx-canvas.log` printed by the script.
+3. Fix the failing CLI/server path and add or update the narrower unit regression.
+4. Re-run `bun run test:e2e-cli`, then `bun run test:all` before release.

package/docs/http-api.md

@@ -0,0 +1,191 @@
+# HTTP API reference
+
+REST endpoints for all canvas operations + an SSE event stream. Works from
+any language. Default base URL: `http://localhost:4313`.
+
+## Canvas state
+
+```bash
+# Get canvas state
+curl http://localhost:4313/api/canvas/state
+
+# Search nodes
+curl "http://localhost:4313/api/canvas/search?q=auth"
+
+# Validate the current layout
+curl http://localhost:4313/api/canvas/validate
+
+# Inspect running-server schemas
+curl http://localhost:4313/api/canvas/schema
+
+# Validate a json-render spec without creating a node
+curl -X POST http://localhost:4313/api/canvas/schema/validate \
+  -H "Content-Type: application/json" \
+  -d '{"type":"json-render","spec":{"root":"card","elements":{"card":{"type":"Card","props":{"title":"Preview"},"children":[]}}}}'
+```
+
+## Nodes
+
+```bash
+# Add a node
+curl -X POST http://localhost:4313/api/canvas/node \
+  -H "Content-Type: application/json" \
+  -d '{"type":"markdown","title":"Hello","content":"# World"}'
+
+# Add an html node (sandboxed iframe)
+curl -X POST http://localhost:4313/api/canvas/node \
+  -H "Content-Type: application/json" \
+  -d '{"type":"html","title":"Chart","html":"<canvas id=\"c\"></canvas><script src=\"https://cdn.jsdelivr.net/npm/chart.js\"></script><script>/* ... */</script>"}'
+```
+
+## Edges
+
+```bash
+# Add an edge
+curl -X POST http://localhost:4313/api/canvas/edge \
+  -H "Content-Type: application/json" \
+  -d '{"from":"node-1","to":"node-2","type":"flow","label":"next"}'
+
+# Add an edge by unique search match instead of explicit IDs
+curl -X POST http://localhost:4313/api/canvas/edge \
+  -H "Content-Type: application/json" \
+  -d '{"fromSearch":"DVT O3 — GitOps","toSearch":"deep work trend","type":"relation"}'
+```
+
+Search-based edge creation is intentionally strict: `fromSearch` and
+`toSearch` must each resolve to exactly one node. Broad queries that match
+multiple nodes fail; use the full visible title.
+
+## Annotations
+
+```bash
+# Add a freehand annotation. The default/currentColor stroke follows the active theme.
+curl -X POST http://localhost:4313/api/canvas/annotation \
+  -H "Content-Type: application/json" \
+  -d '{"points":[{"x":100,"y":120},{"x":220,"y":120}],"color":"currentColor","width":4}'
+
+# Remove an annotation
+curl -X DELETE http://localhost:4313/api/canvas/annotation/ann-123
+```
+
+Agent-readable context reports annotation IDs, targets, and bounds. Use WebView
+inspection or screenshots when the drawn shape matters.
+
+## Pins
+
+```bash
+# Pin nodes for agent context
+curl -X POST http://localhost:4313/api/canvas/context-pins \
+  -H "Content-Type: application/json" \
+  -d '{"nodeIds":["node-1","node-2"]}'
+
+# Get pinned context
+curl http://localhost:4313/api/canvas/pinned-context
+```
+
+## Diagrams (Excalidraw preset)
+
+```bash
+curl -X POST http://localhost:4313/api/canvas/diagram \
+  -H "Content-Type: application/json" \
+  -d '{"elements":[{"type":"rectangle","id":"r1","x":60,"y":60,"width":180,"height":80,"roundness":{"type":3},"backgroundColor":"#a5d8ff","fillStyle":"solid","label":{"text":"Hello","fontSize":18}}],"title":"Diagram"}'
+```
+
+## SSE event stream
+
+```bash
+curl -N http://localhost:4313/api/workbench/events
+```
+
+The browser, the CLI `watch` command, and the MCP resource notifications
+all consume this stream. Auto-reconnect with exponential backoff.
+
+## Time travel
+
+```bash
+curl -X POST http://localhost:4313/api/canvas/undo
+curl -X POST http://localhost:4313/api/canvas/redo
+curl http://localhost:4313/api/canvas/history
+```
+
+## WebView automation
+
+```bash
+# Start WebView automation
+curl -X POST http://localhost:4313/api/workbench/webview/start \
+  -H "Content-Type: application/json" \
+  -d '{"backend":"chrome","width":1280,"height":800}'
+
+# Evaluate JS in the active WebView session
+curl -X POST http://localhost:4313/api/workbench/webview/evaluate \
+  -H "Content-Type: application/json" \
+  -d '{"expression":"document.title"}'
+
+# Resize the active WebView session
+curl -X POST http://localhost:4313/api/workbench/webview/resize \
+  -H "Content-Type: application/json" \
+  -d '{"width":1440,"height":900}'
+
+# Capture a screenshot
+curl -X POST http://localhost:4313/api/workbench/webview/screenshot \
+  -H "Content-Type: application/json" \
+  -d '{"format":"png"}' \
+  --output canvas.png
+```
+
+## Batch operations
+
+Build a canvas in one shot. Earlier results can be referenced from later
+operations via `$assigned-name.field`.
+
+```bash
+curl -X POST http://localhost:4313/api/canvas/batch \
+  -H "Content-Type: application/json" \
+  -d '{"operations":[{"op":"node.add","assign":"a","args":{"type":"markdown","title":"A"}},{"op":"group.create","args":{"title":"Frame","childIds":["$a.id"]}}]}'
+```
+
+Supported operations:
+
+- `node.add`, `node.update`
+- `graph.add`
+- `edge.add`
+- `group.create`, `group.add`, `group.remove`
+- `pin.set`, `pin.add`, `pin.remove`
+- `snapshot.save`
+- `arrange`
+
+`node.add` supports `type: "webpage"` inside batch. The batch itself still
+succeeds when the webpage node is created but the fetch fails; the
+per-operation result includes `fetch: { ok, error? }` plus a top-level
+`error` field for the fetch problem.
+
+Example with assignments:
+
+```json
+{
+  "operations": [
+    {
+      "op": "graph.add",
+      "assign": "wins",
+      "args": {
+        "title": "Major wins",
+        "graphType": "bar",
+        "data": [
+          { "label": "Docs", "value": 5 },
+          { "label": "Tests", "value": 8 }
+        ],
+        "xKey": "label",
+        "yKey": "value"
+      }
+    },
+    {
+      "op": "group.create",
+      "assign": "frame",
+      "args": {
+        "title": "Quarterly graphs",
+        "childIds": ["$wins.id"]
+      }
+    }
+  ]
+}
+```

package/docs/mcp.md

@@ -0,0 +1,135 @@
+# MCP reference
+
+PMX Canvas ships an MCP stdio server with **41 tools** + **8 core resources**,
+plus per-skill resources at `canvas://skills/<name>`. The server emits
+`notifications/resources/updated` when canvas state changes — humans pin
+nodes in the browser, agents are notified immediately.
+
+## Connect
+
+Add to your agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "bunx",
+      "args": ["pmx-canvas", "--mcp"]
+    }
+  }
+}
+```
+
+The canvas auto-starts on first tool call.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `canvas_add_node` | Add a node (markdown, status, context, file, webpage, html, etc.) |
+| `canvas_add_html_node` | Create an `html` node from a self-contained HTML/JS document (sandboxed iframe) |
+| `canvas_add_diagram` | Hand-drawn diagram via the hosted Excalidraw MCP App (preset alias for `canvas_open_mcp_app`) |
+| `canvas_open_mcp_app` | Open any [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) server's `ui://` resource as an iframe node |
+| `canvas_describe_schema` | Describe the running server's create schemas, examples, and json-render catalog |
+| `canvas_validate_spec` | Validate a json-render spec or graph payload without creating a node |
+| `canvas_refresh_webpage_node` | Re-fetch and update a webpage node from its stored URL |
+| `canvas_add_json_render_node` | Create a native json-render node from a validated spec |
+| `canvas_add_graph_node` | Create a native graph node (line, bar, pie, area, scatter, radar, stacked-bar, composed) |
+| `canvas_build_web_artifact` | Build a bundled HTML artifact and open it on the canvas |
+| `canvas_update_node` | Update content, position, size, collapsed state |
+| `canvas_remove_node` | Remove a node and its edges |
+| `canvas_get_layout` | Get full canvas state |
+| `canvas_get_node` | Get a single node by ID |
+| `canvas_remove_annotation` | Remove a human-drawn annotation by ID |
+| `canvas_add_edge` | Connect two nodes |
+| `canvas_remove_edge` | Remove a connection |
+| `canvas_arrange` | Auto-arrange (grid/column/flow) |
+| `canvas_validate` | Validate collisions, containment, and missing edge endpoints |
+| `canvas_focus_node` | Pan viewport to a node; use CLI `focus --no-pan` when you only need to select/raise |
+| `canvas_pin_nodes` | Pin nodes to include in agent context |
+| `canvas_clear` | Clear all nodes and edges |
+| `canvas_snapshot` | Save current canvas as a named snapshot |
+| `canvas_list_snapshots` | List saved snapshots, bounded to the newest 20 by default |
+| `canvas_gc_snapshots` | Delete old snapshots while keeping the newest N |
+| `canvas_restore` | Restore canvas from a saved snapshot |
+| `canvas_delete_snapshot` | Delete a saved snapshot |
+| `canvas_search` | Find nodes by title/content keywords |
+| `canvas_undo` | Undo the last canvas mutation |
+| `canvas_redo` | Redo the last undone mutation |
+| `canvas_diff` | Compare current canvas vs a saved snapshot |
+| `canvas_create_group` | Create a group containing specified nodes |
+| `canvas_group_nodes` | Add nodes to an existing group |
+| `canvas_ungroup` | Release all children from a group |
+| `canvas_batch` | Run a batch of canvas operations with `$ref` support |
+| `canvas_webview_status` | Get Bun.WebView automation status for the workbench |
+| `canvas_webview_start` | Start or replace the Bun.WebView automation session |
+| `canvas_webview_stop` | Stop the active Bun.WebView automation session |
+| `canvas_evaluate` | Evaluate JavaScript in the active workbench automation session |
+| `canvas_resize` | Resize the active workbench automation viewport |
+| `canvas_screenshot` | Capture a screenshot from the active workbench automation session |
+
+## Resources
+
+Individual bundled skills are also readable at `canvas://skills/<name>`.
+
+| Resource | Description |
+|----------|-------------|
+| `canvas://pinned-context` | Content of pinned nodes + nearby unpinned neighbors |
+| `canvas://schema` | Running-server create schemas and json-render catalog metadata |
+| `canvas://layout` | Full canvas state (all nodes, edges, viewport) |
+| `canvas://summary` | Compact overview: counts, pinned titles, viewport |
+| `canvas://spatial-context` | Proximity clusters, reading order, pinned neighborhoods |
+| `canvas://history` | Mutation history timeline with undo/redo position |
+| `canvas://code-graph` | Auto-detected file dependency graph (JS/TS, Python, Go, Rust) |
+| `canvas://skills` | Index of bundled agent skills + per-skill content at `canvas://skills/<name>` |
+
+## Change notifications
+
+The MCP server emits `notifications/resources/updated` whenever canvas state
+changes:
+
+- Pin changes notify `canvas://pinned-context`
+- All mutations notify `canvas://layout`, `canvas://summary`,
+  `canvas://spatial-context`, `canvas://history`, and `canvas://code-graph`
+
+This closes the human-to-agent loop: spatial curation in the browser becomes
+an immediate signal in the agent's context.
+
+## Annotation Visibility
+
+Human-drawn canvas annotations are rendered as browser SVG ink. MCP resources
+keep annotation context compact: agents see annotation counts, bounds, and target
+summaries such as the node or empty canvas region that was marked, but not the
+raw stroke geometry or visual shape.
+
+Annotations are a browser-visible markup layer. Use the pen toolbar button to
+draw and the eraser toolbar button to remove an annotation again; agents can also
+remove a known annotation ID with `canvas_remove_annotation`.
+
+Use WebView automation when an agent needs to actually see annotations as drawn.
+For example, inspect `.annotation-layer path` with `canvas_evaluate` or capture a
+`canvas_screenshot` to distinguish an arrow from a line, circle, or highlight.
+
+## Node-type routing
+
+MCP node creation uses dedicated tools for structured node families. Read
+`mcp.nodeTypeRouting` from `canvas_describe_schema` / `canvas://schema` when
+in doubt:
+
+- `json-render` → `canvas_add_json_render_node`
+- `graph` → `canvas_add_graph_node`
+- `html` → `canvas_add_html_node`
+- `web-artifact` → `canvas_build_web_artifact`
+- `mcp-app` → `canvas_open_mcp_app`
+- `group` → `canvas_create_group`
+- Basic nodes (`markdown`, `status`, `file`, `image`, `webpage`) →
+  `canvas_add_node`
+
+## CLI/MCP alignment
+
+CLI and MCP are kept aligned for the main canvas operations: node and edge
+creation, graph/json-render/html nodes, web artifacts, external apps, groups,
+batch builds, layout validation, snapshots, search, focus, pins, undo/redo,
+semantic watch streams, WebView automation, and daemon/server control where
+it applies. A few agent-native capabilities — resource subscriptions and
+`canvas_diff` — remain MCP-only.

package/docs/node-types.md

@@ -0,0 +1,244 @@
+# Node types
+
+Canvas nodes are typed. Each type has a dedicated renderer, schema, and (for
+structured types) a dedicated MCP tool. This page is the user-facing reference
+for what each type is for and how to create one. For tool/HTTP/SDK signatures,
+see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
+
+## Overview
+
+| Type | Purpose |
+|------|---------|
+| `markdown` | Rich markdown with rendered preview |
+| `status` | Compact status indicator (phase, message, elapsed time) |
+| `context` | Context cards, token usage, workspace grounding |
+| `ledger` | Execution ledger summary |
+| `trace` | Agent trace pills (tool calls, subagent activity) |
+| `file` | Live file viewer with auto-update on disk changes |
+| `image` | Image viewer (file paths, data URIs, URLs) |
+| `webpage` | Persisted webpage snapshot with stored URL, extracted text, refresh |
+| `mcp-app` | Tool-backed hosted MCP App iframes (Excalidraw, etc.) |
+| `json-render` | Structured UI from JSON specs (cards, tables, forms) |
+| `graph` | Charts (line, bar, pie, area, scatter, radar, stacked-bar, composed) |
+| `html` | Self-contained HTML/JS in a sandboxed iframe |
+| `web-artifact` | Bundled React/Tailwind artifact (full single-file app) |
+| `group` | Spatial container/frame around other nodes |
+
+Thread node types `prompt` and `response` exist internally for agent
+conversation rendering and are not created through public APIs.
+
+## Choosing the right visual tier
+
+Three rendering tiers cover increasing levels of complexity. Pick the lowest
+that fits the work — each step adds capability and bundle weight.
+
+| Tier | Type | Use when | Bundle weight |
+|------|------|----------|---------------|
+| 1 | `json-render` | You can describe the UI as a spec (forms, tables, dashboards from a component catalog) | None — runtime already loaded |
+| 2 | `html` | You have/can write self-contained HTML+JS (Chart.js, D3, custom widgets, interactive demos) | None — sandboxed iframe |
+| 3 | `web-artifact` | You need a full React/Tailwind app with shadcn components, routing, or shared state | Build step |
+
+## File nodes
+
+File nodes display project files with line numbers and language detection.
+When an agent edits a file through its normal tools, the canvas node updates
+automatically via `fs.watch()`.
+
+```ts
+canvas_add_node({ type: 'file', content: 'src/server/index.ts' })
+```
+
+## Image nodes
+
+Image nodes display local paths, remote URLs, and data URIs. File-backed and
+HTTP(S)-backed images preserve provenance so agents can tell where evidence
+came from. Nodes can carry validation status or warnings.
+
+```ts
+canvas_add_node({
+  type: 'image',
+  content: 'artifacts/dashboard.png',
+  data: {
+    validationStatus: 'passed',
+    validationMessage: 'Screenshot matches the requested dashboard state.',
+  },
+})
+```
+
+## Webpage nodes
+
+Webpage nodes store the source URL on the node, fetch the page server-side,
+and cache extracted text for search, pins, and agent context. Saved canvases
+keep enough information for an agent to refresh the node from the original
+URL later.
+
+```ts
+canvas_add_node({ type: 'webpage', url: 'https://example.com/docs' })
+canvas_refresh_webpage_node({ id: 'node-abc123' })
+```
+
+## MCP App nodes
+
+`mcp-app` nodes embed other MCP servers' UI resources (`ui://...`) directly
+on the canvas as sandboxed iframes. Any server implementing the
+[MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps)
+can be opened with `canvas_open_mcp_app`.
+
+Generic `pmx-canvas node add --type mcp-app` is intentionally rejected —
+these nodes need tool/session metadata. Use `canvas_open_mcp_app` (or the
+`canvas_add_diagram` Excalidraw preset) instead.
+
+### Excalidraw preset (hand-drawn diagrams)
+
+[Excalidraw](https://github.com/excalidraw/excalidraw-mcp) ships a hosted MCP
+server at `https://mcp.excalidraw.com/mcp`. PMX Canvas exposes a one-call
+preset:
+
+```ts
+canvas_add_diagram({
+  elements: [
+    { type: 'rectangle', id: 'a', x: 80, y: 120, width: 180, height: 80,
+      roundness: { type: 3 }, backgroundColor: '#a5d8ff', fillStyle: 'solid',
+      label: { text: 'Agent', fontSize: 18 } },
+    { type: 'rectangle', id: 'b', x: 380, y: 120, width: 180, height: 80,
+      roundness: { type: 3 }, backgroundColor: '#d0bfff', fillStyle: 'solid',
+      label: { text: 'PMX Canvas', fontSize: 18 } },
+    { type: 'arrow', id: 'a1', x: 260, y: 160, width: 120, height: 0,
+      startBinding: { elementId: 'a' }, endBinding: { elementId: 'b' },
+      label: { text: 'adds nodes' } },
+  ],
+  title: 'Agent → Canvas',
+});
+```
+
+For any other MCP App, call `canvas_open_mcp_app` directly with the server's
+transport, tool name, and arguments.
+
+## json-render nodes
+
+`json-render` nodes turn structured JSON specs into rendered UI panels
+(dashboards, tables, forms, cards) without writing HTML. PMX Canvas ships the
+[`@json-render/*`](https://www.npmjs.com/package/@json-render/core) runtime
+and component catalog (core + react + shadcn).
+
+```ts
+canvas_add_json_render_node({
+  title: 'Deploy status',
+  spec: {
+    root: 'card',
+    elements: {
+      card: { type: 'Card', props: { title: 'Deploy' }, children: ['status'] },
+      status: { type: 'Badge', props: { variant: 'default', text: 'Healthy' } },
+    },
+  },
+});
+```
+
+`Badge` uses shadcn variants: `default`, `secondary`, `destructive`,
+`outline`. Older saved specs using `label` or status variants such as
+`success`/`warning` are normalized during validation.
+
+Use `canvas_describe_schema` / `canvas_validate_spec` to introspect the
+component catalog before building a spec.
+
+## HTML nodes
+
+`html` nodes render a self-contained HTML/JS document in a sandboxed iframe.
+They sit between `json-render` (no custom JS) and `web-artifact` (full bundled
+React app) — perfect for Chart.js, D3, custom widgets, and any HTML you can
+write or paste.
+
+The sandbox runs with `allow-scripts` only — no same-origin access, no
+top-level navigation, no form submission. Inline `<script>` and CDN
+`<script src>` both work. The canvas auto-injects its theme tokens
+(`--c-*` and `--color-*` aliases) into the iframe `<head>` so artifacts can
+match the active theme.
+
+```ts
+canvas_add_html_node({
+  title: 'Cost projection',
+  html: '<canvas id="c"></canvas><script src="https://cdn.jsdelivr.net/npm/chart.js"></script><script>...</script>',
+})
+```
+
+A fragment without `<html>`/`<head>` is wrapped in a full document
+automatically. Default size is 720×640.
+
+## Web artifacts
+
+A **web artifact** is a single-file, fully bundled HTML app (React + Tailwind
++ shadcn) the agent builds from TSX source. Use it when the work calls for a
+real interactive app — charts, forms, mini-dashboards — beyond what a static
+node or `html` snippet can express.
+
+`canvas_build_web_artifact` takes source strings (`App.tsx`, optional
+`index.css`, `main.tsx`, `index.html`, plus extra files), runs the bundled
+web-artifacts-builder scripts, writes the self-contained HTML to
+`.pmx-canvas/artifacts/<slug>.html`, and (by default) opens it in the canvas.
+
+```bash
+pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
+```
+
+The scaffold includes `recharts`. Pass `--deps name,name2` for additional
+package dependencies. Failed or empty CLI bundles print `ok: false`, exit
+non-zero, and do not create a canvas node.
+
+The matching agent skill is at
+[`skills/web-artifacts-builder/SKILL.md`](../skills/web-artifacts-builder/SKILL.md).
+
+## Groups
+
+Groups are spatial containers that visually contain other nodes. They render
+as dashed-border frames with a title bar and optional accent color.
+
+- Select 2+ nodes and click "Group" in the selection bar
+- Right-click a group to ungroup
+- Collapsing a group hides children and shows a summary
+- By default, group creation preserves the children's current positions and
+  expands the frame around them
+- Pass `childLayout` to auto-pack children (`grid`, `column`, `flow`)
+- Pass explicit `x`, `y`, `width`, and `height` to create a manual frame and
+  lay children out inside it
+
+```ts
+canvas_create_group({ title: 'Auth Module', childIds: ['node-1', 'node-2'], color: '#4a9eff' })
+```
+
+## Edge types
+
+All edges support labels, styles (solid/dashed/dotted), and animation.
+
+| Type | Use case |
+|------|----------|
+| `flow` | Sequential steps, data flow |
+| `depends-on` | Dependencies between tasks |
+| `relation` | General relationships |
+| `references` | Cross-references, evidence links |
+
+## Schema-driven discovery
+
+Agents don't have to guess node shapes. The running server exposes its create
+schemas, json-render component catalog, and node-type examples:
+
+- `canvas_describe_schema` / `GET /api/canvas/schema` — list all node-create
+  schemas, required fields, json-render components, and sample payloads
+- `canvas_validate_spec` / `POST /api/canvas/schema/validate` — validate a
+  json-render spec or graph payload **without** creating a node
+- `canvas_validate` / `GET /api/canvas/validate` — validate the current
+  layout for collisions, containment, and missing edge endpoints
+- `canvas://schema` — the same data as an MCP resource
+
+The CLI's `node schema` / `validate spec` subcommands surface the same data
+from the terminal.
+
+MCP node creation uses dedicated tools for structured node families. Read
+`mcp.nodeTypeRouting` from `canvas_describe_schema` when in doubt:
+`json-render` → `canvas_add_json_render_node`,
+`graph` → `canvas_add_graph_node`,
+`html` → `canvas_add_html_node`,
+`web-artifact` → `canvas_build_web_artifact`,
+`mcp-app` → `canvas_open_mcp_app`,
+`group` → `canvas_create_group`.
+Basic nodes (`markdown`, `status`, `file`, `image`, `webpage`) use
+`canvas_add_node`.