pmx-canvas 0.11.0 → 0.12.1

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/full-reference.md

@@ -0,0 +1,1839 @@
+---
+name: pmx-canvas
+description: >
+  Spatial canvas workbench for visual thinking — nodes, edges, groups on an infinite 2D canvas
+  with pan/zoom, minimap, and real-time sync. Use this skill whenever you need to lay out
+  information spatially: investigation boards, architecture diagrams, dependency maps, task plans,
+  status dashboards, file relationship views, or any scenario where a flat list or text wall
+  isn't enough. Also use when the user mentions "canvas", "board", "diagram", "spatial layout",
+  "visual map", "node graph", or wants to see how things connect. The canvas is your extended
+  working memory — pin nodes to curate context, read spatial arrangement to understand intent.
+---
+
+# PMX Canvas — Full Reference
+
+PMX Canvas is a spatial canvas workbench you control through MCP tools or HTTP API. It renders an
+infinite 2D canvas in the browser with nodes, edges, groups, pan/zoom, and a minimap. State lives
+on the server and survives browser refresh.
+
+The canvas is your extended working memory. Humans pin nodes to curate context; you read that
+curation through MCP resources. Spatial arrangement is communication — proximity means
+relatedness, clusters imply grouping, reading order (top-left to bottom-right) implies sequence.
+
+## When to Use
+
+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`
+   - Rich reusable communication artifacts → `html-primitive`
+   - Interactive tool surfaces with their own UI → `mcp-app` (open with
+     `canvas_app { action: "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.
+
+## Quick Operating Path
+
+The fast, current, safe sequence for a typical session. Each step links to the detailed
+section below.
+
+1. **Open/focus the workbench** — make the canvas visible *before* mutating (see "Open the
+   canvas first"). Reuse one surface for the session.
+2. **Verify workspace identity** — read `GET /health` (or `pmx-canvas serve status`) and
+   confirm the returned `workspace` matches your intended workspace root. A healthy listener on port
+   4313 can belong to another project — never mutate the wrong board (see "Verify workspace
+   identity BEFORE mutating").
+3. **Read before write** — `canvas_query { action: "search", query }` (or `pmx-canvas search`)
+   to find existing nodes; avoid duplicates. Use `canvas_query { action: "layout" }` only when
+   you need the full board.
+4. **Snapshot before destructive work** — `canvas_snapshot { action: "save", name }` before clear/major
+   reorg; restore if needed.
+5. **Signal then mutate (default behavior)** — signal with `canvas_intent { action: "signal", … }`
+   to telegraph the move before nearly every mutation, then create with the right composite: `canvas_node` (markdown/status/file/webpage/html
+   incl. primitives), `canvas_render` (json-render/graph), `canvas_app` (mcp-app/diagram/
+   web-artifact). Use composites — the legacy single-purpose tools were removed in v0.3.0.
+6. **Arrange + validate** — `canvas_view { action: "arrange" }` after batch adds, then
+   `canvas_query { action: "validate" }` to catch collisions / dangling edges before finishing.
+7. **Pin through a verified path** — `canvas_pin_nodes` (or the browser "Pin as context" /
+   double-click menu's "Pin as context"), then read `canvas://pinned-context` to confirm.
+8. **Clean up** — remove retry/test fixtures (`canvas_node { action: "remove" }` — works for
+   every type, including `status`), and restore the baseline snapshot.
+
+## Starting the Canvas
+
+If this skill is installed before the `pmx-canvas` command exists, install the project first. See
+`installing-pmx-canvas.md` for local development, npm/global install, and MCP config
+options.
+
+## Adapter References
+
+PMX Canvas core is host-agnostic. When a host-specific adapter is available, read the matching
+reference before using adapter-native features:
+
+- `github-copilot-app-adapter.md` — GitHub Copilot app project extension, native canvas
+  panel, AX context injection, and live-test checklist.
+- `codex-app-adapter.md` — Codex app native Browser + MCP adapter, AX context reading,
+  focus labeling, and live-test checklist.
+
+Open the canvas first — always:
+The canvas is the shared human↔agent surface. **Before you create or mutate any nodes, make the
+workbench visible.** Do **not** assume the host opened it for you — some hosts (e.g. the Codex app)
+do not open it on their own. Take the action to open it yourself, whatever the host:
+- **Native adapter/panel available** (the GitHub Copilot app `pmx-canvas` canvas extension, or the
+  Codex in-app Browser): open/focus that panel to the server's `/workbench` route.
+- **Any other browser** (Chrome, Safari, Arc, Edge, …) **or a generic/CLI agent** with no native
+  panel: open the server's `/workbench` URL in a browser.
+
+Then reuse that **single** surface for the rest of the session — do **not** open a second panel to
+the same workbench (it wastes space and confuses which surface is authoritative). If you genuinely
+cannot open any browser (headless/CI), say so and proceed, but still print the `/workbench` URL so a
+human can open it.
+- External URLs in `mcp-app` nodes show the "Unverified domain" interstitial by design. Only
+  same-origin `/api/canvas/frame-documents/<id>` URLs are auto-trusted. For external tools, use a
+  bundled `web-artifact`, same-origin frame document, or set `data.trustedDomain: true` only when the
+  user accepts the risk.
+
+The canvas auto-starts on first MCP tool call when running in MCP mode (`pmx-canvas --mcp`).
+For manual start:
+
+```bash
+pmx-canvas                     # Start and open browser (port 4313)
+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=daylight    # Daylight theme
+pmx-canvas --version           # Print installed version and exit
+```
+
+`--theme` accepts `harbor` (default), `daylight`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`, or `volt` (0.4.x; the rail's theme picker lists the same nine). Same value can be set via
+the `PMX_CANVAS_THEME` environment variable, or picked live from the left tool rail.
+
+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. The pid file doubles as the
+spawn lock and records the pid immediately, so a starting-but-not-yet-healthy daemon is already
+addressable by `serve stop`, and a failed startup kills the child — no orphans. If the requested
+port already serves a *different* workspace (or a non-canvas app), `serve --daemon` refuses with
+the owner named and a hint to pick another port; it never reports a foreign daemon as "already
+running". `serve stop` reads the pid file, verifies the pid still looks like a canvas daemon
+(recycled pids read as stale), sends SIGTERM, and cleans up on exit.
+
+### Verify workspace identity BEFORE mutating (required)
+
+> **"Start once, reuse always" has one hard exception for direct CLI/HTTP work: never mutate a
+> listener that belongs to another workspace.** A healthy, responsive server on the default port
+> `4313` can be serving a *different project's* canvas (a leftover daemon, or another repo's
+> session). Mutating it directly would corrupt the wrong board. Always preflight:
+
+1. **Read `GET /health`** (or `pmx-canvas serve status`). Both return a top-level
+   `workspace` field. **`workspace` MUST equal your intended workspace root**
+   before any create/update/remove. If it doesn't match, do not mutate.
+2. **Treat `responsive: true` + `pidRunning: false` as a stale-listener warning** — the pid file
+   is stale and the live listener may be a different process/workspace. Confirm the real owner with
+   `lsof -nP -iTCP:<port> -sTCP:LISTEN`.
+3. **On mismatch, isolate**: start the intended workspace on an explicit free port —
+   `pmx-canvas serve --daemon --no-open --port=<free-port>` — and target that port. (`PMX_CANVAS_PORT`
+   alone may still attach to an existing `4313` listener; prefer an explicit `--port`.) Then
+   **re-read `/health`** to confirm the workspace now matches. `serve --daemon` also enforces
+   this itself: pointed at a port owned by another workspace, it exits with an error naming the
+   owner instead of attaching to it.
+4. **MCP transport exception:** `pmx-canvas --mcp` launched from an incidental host dir may attach to
+   the healthy daemon already on the preferred port when no explicit workspace root is set, so writes
+   land in the visible workbench instead of a hidden fallback workspace. Host adapters should set
+   `PMX_CANVAS_WORKSPACE_ROOT=<abs project root>` for deterministic targeting; set
+   `PMX_CANVAS_ALLOW_WORKSPACE_SPLIT=1` or a distinct `PMX_CANVAS_PORT` only when a separate canvas is
+   intentional.
+5. **After any version upgrade**, run a behavior canary (e.g. a batch `node.add` with no `type`
+   must return `400`) to confirm the listener is the version you expect, not a stale old daemon.
+
+## Browser Workflows
+
+The browser is not just a passive view. Human interactions on the canvas persist back to the
+server and become part of the authoritative canvas state.
+
+- Double-left-click empty canvas — open the node-creation menu at that position
+- Right-button hold and drag — pan the board, including over node content
+- Shift+drag on empty canvas — lasso-select multiple nodes
+- Selection bar actions — when nodes are selected, the browser exposes `Pin as context`,
+  `Group`, `Connect`, and `Clear`
+- Double-left-click a node — open the node context menu. **`Pin as context`** adds the node to the
+  human-curated agent context set (updates the context count + the node's context-pin indicator);
+  `Lock position` is the separate arrange-lock. Plus focus, collapse, connect, refresh/open, close,
+  and type-specific actions. (Every node type, **including `status`, has a remove `×`** in its title
+  bar and a `Close` menu item.)
+- Double-left-click a group node — recolor the group using preset swatches or a custom color picker,
+  or ungroup it (dissolves the frame; children stay)
+- Drag-and-drop files or URLs — add file, image, markdown, or webpage nodes directly. PDF/Office
+  drops retain an original attachment up to 20 MiB and wait for explicit human consent before
+  agent-assisted import; they do not launch an agent or bundled converter.
+- Paste URLs — create webpage nodes from the clipboard
+
+Use browser interactions when the human is actively curating spatial layout. Use MCP or the CLI
+when you need deterministic scripted changes or you are acting without a visible browser.
+
+### Known limitations & host differences
+
+- **Hosted MCP-app / Excalidraw nodes are not "open as site" targets.** A hosted ext-app is a
+  *live* MCP-app shell that only renders with the in-canvas host bridge — there is no standalone
+  page for it (the "Open as site" control is hidden for these nodes). View/edit them in the canvas,
+  or open them externally through their own app. `html`, `json-render`, `graph`, and bundled
+  `web-artifact` nodes DO open as a standalone site (and graph/json-render fill the full browser
+  viewport).
+- **Sandboxed-iframe automation (host-dependent).** Some embedded hosts (notably the Codex in-app
+  Browser) cannot script *inside* PMX's sandboxed workbench iframes (`Frame target is not
+  available`). The surface renders and the server-side interaction path works; this is a host
+  automation limitation, not a PMX rendering bug. Verify embedded-iframe behavior in system Chrome
+  or via the server-side AX state, not by automating the iframe in such hosts.
+- **`pmx-canvas screenshot` needs an active WebView** and defaults to the workbench camera; start
+  `canvas_webview { action:"start" }` first, and use `canvas_webview { action:"evaluate" }` (not
+  `eval`) to drive it.
+
+## Agent CLI
+
+PMX Canvas also ships an agent-native CLI that talks to the running HTTP server and returns JSON.
+Use it when MCP is not available but you still want structured, scriptable canvas operations.
+
+```bash
+pmx-canvas --help                           # Top-level help
+pmx-canvas serve --daemon --no-open        # Detached daemon with health output
+pmx-canvas serve status                    # Daemon health + pid status
+pmx-canvas serve stop                      # Stop the daemon for this port/pid file
+pmx-canvas layout                          # Full canvas state
+pmx-canvas status                          # Quick summary
+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
+pmx-canvas node list --type file --ids
+pmx-canvas edge add --from node-a --to node-b --type depends-on
+pmx-canvas search "auth"
+pmx-canvas open
+pmx-canvas arrange --layout flow
+pmx-canvas focus <node-id> --no-pan             # Select/raise without moving the user's viewport
+pmx-canvas fit --width 1440 --height 900        # Fit the whole board for screenshots/review
+pmx-canvas screenshot --output ./canvas.png     # Shorthand for `webview screenshot`
+pmx-canvas json-render --schema --summary       # Inspect json-render component catalog
+pmx-canvas json-render --example --component Table
+pmx-canvas node add --type markdown --title "Long doc" --strict-size  # Scroll instead of auto-fit
+pmx-canvas node add --type graph --graphType pie --data-file metrics.json --show-legend false --show-labels false
+pmx-canvas node update <node-id> --spec-file ./dashboard.json
+pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
+pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
+pmx-canvas node list --type web-artifact --summary
+pmx-canvas node list --type external-app --summary
+pmx-canvas pin --list
+pmx-canvas ax context
+pmx-canvas ax focus <node-id>
+pmx-canvas ax work add --title "Wire up auth" --status in-progress <node-id>
+pmx-canvas ax approval request --title "Deploy to prod"
+pmx-canvas ax steer "focus on the failing test first"
+pmx-canvas ax timeline --limit 50
+pmx-canvas snapshot save --name "before-refactor"
+pmx-canvas code-graph
+pmx-canvas spatial
+```
+
+### CLI command groups
+
+- `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"`.
+- `search`, `layout`, `status`, `arrange`, `focus` — inspect and navigate the canvas. Prefer
+  `focus --no-pan` when you only need to select/raise a node without hijacking the human's camera.
+- `ax status|context|focus` — inspect the host-agnostic AX layer; `ax context`
+  combines pinned context and AX focus for adapter prompt injection.
+- `ax event add`, `ax steer`, `ax evidence add`, `ax timeline` — the AX timeline
+  (agent-events, steering messages, evidence). Persisted for diagnostics,
+  retention-bounded, and excluded from snapshots.
+- `ax work add|update|list`, `ax approval request|resolve|list`,
+  `ax review add|list` — canvas-bound AX state (work items, approval gates,
+  review annotations) that rides snapshots and restore and is cleared by `clear`.
+- `ax host report|status` — report/read the host/session capability (own partition).
+- `ax command list|invoke`, `ax policy get|set` — list/invoke registry commands
+  (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`)
+  and read/patch the canvas-bound tool/prompt policy.
+- `copilot install-extension [--dry-run] [--yes]` — install the bundled GitHub
+  Copilot adapter into a repo; the core stays host-agnostic.
+- `fit [id ...]` — set the server viewport to fit the whole canvas or selected nodes before screenshots or whole-board review
+- `screenshot --output <path>` — top-level shortcut for `webview screenshot`; supports `--format png|jpeg|webp` and `--quality`
+- `json-render --schema|--examples` — inspect the json-render component catalog with `--component`/`--field` filters; same data as `node schema --type json-render` in a more direct shape
+- `--strict-size` (alias `--scroll-overflow`) on `node add`/`node update` — keep explicit width/height fixed and scroll overflowing content instead of letting the renderer auto-fit. Useful for long markdown, dense webpages, and dashboards that should fit a tile-sized frame.
+- `--show-legend false` / `--show-labels false` on `node add --type graph` and `graph add` — hide chart legends and pie slice labels for compact graph nodes in tile-style boards.
+- `open` — open the current workbench in the browser
+- `pin --list|--clear|<ids...>` — manage context pins
+- `undo`, `redo`, `history` — time travel
+- `snapshot save|list|restore|delete` — manage snapshots
+- `group create|add|remove` — manage groups
+- `clear --yes` — destructive clear with explicit confirmation
+- `validate spec` — validate json-render specs and graph payloads without creating nodes
+- `node update` — returns a compact `{ ok, id, nodeId, position, size, updatedFields }` envelope by default; pass `--full` for the complete node payload. Full ext-app/mcp-app payloads embed the bundled app HTML and tool results (hundreds of KB — a no-op ext-app resize once returned ~940 KB), so in agent turns keep the default envelope and read content via `node get --summary`
+- `web-artifact build` — build bundled React/Tailwind HTML artifacts; use `--deps` for extra packages and `--include-logs` only when raw logs are useful. The build pipeline runs bash scripts (POSIX-only) — it is not supported on native Windows; already-built artifacts render everywhere
+- `external-app add --kind excalidraw` — create the hosted Excalidraw preset; response includes `id` and `nodeId` aliases for the same canvas node
+- `serve status|stop` — inspect and stop daemonized servers started with `serve --daemon`
+- `code-graph`, `spatial` — analysis commands
+
+Current caveat:
+- `mcp-app` grouping is not fully uniform yet. Web artifact app nodes have grouped reliably, but
+  Excalidraw app nodes have shown inconsistent `group add` behavior and weaker rediscoverability
+  through search later in the session. When you plan to curate an app-heavy comparison area,
+  capture node IDs immediately after creation and verify membership with `node get --summary`,
+  `layout --summary`, or the browser selection state instead of relying on search alone.
+- App-like nodes persist as `type: "mcp-app"` internally but serialized results include `kind`:
+  `web-artifact`, `external-app`, or `mcp-app`. Prefer `node list --type web-artifact` or
+  `node list --type external-app` when you need the operational subtype.
+- 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.
+
+## Core Concepts
+
+### Node Types
+
+| Type | Purpose | When to use |
+|------|---------|-------------|
+| `markdown` | Rich formatted content | Explanations, documentation, notes, findings |
+| `status` | Compact status or deliberately authored work card | Work plans with `data.workState`; phase/tool status without it |
+| `file` | Live file viewer (auto-watches) | Show source code with live updates on file change |
+| `image` | Image display | Screenshots, diagrams, charts |
+| `context` | Context card | Key context the human should see |
+| `ledger` | Log/ledger viewer | Structured log data, audit trails |
+| `trace` | Trace/timeline viewer | Execution traces, timelines |
+| `mcp-app` | Hosted app/embed frame | Tool-backed MCP apps or external app content; not generic CLI-created notes |
+| `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, composed, plus Tufte primitives (sparkline, dot-plot, bullet, slopegraph) rendered inside the canvas |
+| `html` | Sandboxed HTML+JS document | Self-contained HTML with optional inline `<script>` and CDN imports rendered in a sandbox-restricted iframe; canvas theme tokens are auto-injected |
+| `group` | Spatial container/frame | Visually group related nodes together |
+| `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_node { action: "add" }` 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
+
+| Type | Purpose | Example label |
+|------|---------|---------------|
+| `flow` | Sequential/directional | "then", "calls", "triggers" |
+| `depends-on` | Dependency | "requires", "blocks" |
+| `relation` | General relationship | "related to", "similar to" |
+| `references` | Cross-reference | "see also", "documented in" |
+
+Edges support `style` (solid/dashed/dotted) and `animated` flag. Always use descriptive labels.
+
+**Edge direction convention:** `from` is the source/dependent, `to` is the target/dependency.
+So `from: A, to: B, type: "depends-on"` means "A depends on B." For `flow` edges, the arrow
+points from `from` to `to`, indicating sequence or data flow direction.
+
+**Style conventions:** Use `solid` for active/satisfied relationships, `dashed` for blocked or
+pending dependencies, and `dotted` for weak/optional relationships. Use `animated: true` to
+draw visual attention to critical paths.
+
+### Layout: spacing and groups
+
+Use the smallest clear gap that serves the content and its relationships. Both crowded labels
+and oversized empty channels make a board harder to use.
+
+- **Unconnected notes and walkthroughs:** start compact, often a 40–80px clear gap. For a
+  280×180 node with a 40px gap, origins are 320px apart horizontally and 220px vertically.
+  This is an unconnected-card example, not a minimum for connected cards. Do not reserve
+  half a card's width or a large uniform channel where there is no edge.
+- **Connected cards:** provide enough room for the rendered edge line, arrowhead, label and
+  authorship marks. Short flow labels may need less room than long explanations. After content settles,
+  inspect the rendered relations at the intended viewing zoom, including after auto-arrange.
+  `validate` checks node non-overlap, not label/arrowhead clearance or relation readability;
+  widen or reroute crowded relations rather than relying on a fixed pixel gap.
+- **After rendering:** use settled card sizes, not just the requested creation heights. Close
+  gaps left by automatic shrinking, check the numbered reading order, and frame a readable
+  cluster or tour stop. A whole-board fit is orientation, not proof that body text is readable.
+- **Inside a group, apply the same distinction** between compact notes and clear relation
+  channels. Groups no longer auto-pack children, so the spacing you set is what the human sees.
+- **Size a group frame larger than its children's bounding box** so the group header — including the
+  node-count badge — stays visible and isn't hidden under the top-left child. For an explicit
+  (manual) group frame, add margin on every side (≈56px) plus room at the top for the header rather
+  than hugging the children. Auto-fit groups (created without an explicit width/height) already
+  reserve this margin.
+
+### Colors (Semantic)
+
+A `color` parameter is honored as a **renderer** color only for **group** nodes (frame accent) and
+**graph** nodes (series/accent color). It is **not** a renderer parameter for `markdown` / `status` /
+`context` nodes: a top-level `color` on those is dropped on both HTTP and the CLI, and while an
+arbitrary `data.color` you POST under `data` persists like any other `data.*` metadata, it is **not**
+read as a render color for basic node types (report Finding H — renderer-semantic, not raw-storage,
+contract). Their meaning comes from the node **type** and value instead: a `status` node colors its indicator from its
+**phase** (`idle`/`running`/`planning`/`thinking`/`drafting`/`tooling`/`review`/`waiting-approval`/
+`waiting` — e.g. `review` → green, `running` → accent; an unrecognized phase renders gray), and a
+`trace` node from its `status` field (`success` → green, `failed` → red, `running` → accent). To
+color an arbitrary region, group the nodes and set the group's `color`.
+Authored status cards with `data.workState` instead use the work-state glyph and label:
+blocked uses the warning token, done the success token, and cancelled the muted token.
+Do not set arbitrary colors to encode work state.
+
+When you do set a color (group/graph), use this palette consistently to convey meaning:
+- **Green** (`#22c55e`) — success, done, healthy
+- **Yellow** (`#eab308`) — in progress, warning, attention needed
+- **Red** (`#ef4444`) — error, blocked, failing
+- **Blue** (`#3b82f6`) — informational, neutral highlight
+- **Gray** (`#6b7280`) — queued, pending, inactive, not yet started
+- **Purple** (`#a855f7`) — special, notable, review needed
+
+## MCP Tools Reference
+
+PMX Canvas exposes **18 action-discriminated composites** (the whole recommended surface) plus
+**7 first-class standalones** — 25 tools total. The composites fold the older
+single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) discriminator —
+**field names are unchanged**; only the tool name + the `action`/`kind` selector differ.
+
+`canvas_help {}` lists MCP registry operation names. `canvas_help { op: "node.add" }`
+returns that operation's public tool, description and JSON argument schema, including
+routing selectors and required fields. It does not start or read a canvas. Handlers still
+enforce conditional requirements. Non-registry tools use `tools/list` instead.
+
+> **Legacy single-purpose tools were removed in v0.3.0.** The old names (`canvas_add_node`,
+> `canvas_update_node`, `canvas_request_approval`, `canvas_add_work_item`, …) are no longer
+> registered — use the composites below and fresh MCP `tools/list` for the installed runtime's
+> authoritative action schemas. This skill does not re-enumerate the removed names.
+
+### The 18 composites
+
+| Composite | `action` values | What it does |
+|-----------|-----------------|--------------|
+| `canvas_import` | `list` · `read` · `submit` · `unavailable` | Process human-requested imports: inspect metadata/controlled bytes, submit reviewable Markdown with references/warnings/agent description, or report unavailable. Request/cancel/commit are human-only |
+| `canvas_node` | `add` · `get` · `update` · `remove` · `lifecycle-get` · `lifecycle-set` · `review` · `lifecycle-restore` | Node CRUD, lifecycle qualification, evidence-backed review and reversible retirement; retired cards leave active context |
+| `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` · `workboard` | Schema introspection, spec dry-run validation, native json-render / graph node creation, and a live AX work-item board |
+| `canvas_edge` | `add` · `update` · `remove` | Connect / edit / disconnect nodes |
+| `canvas_group` | `create` · `add` · `ungroup` | Manage spatial group containers |
+| `canvas_history` | `undo` · `redo` | Time travel through the mutation ring buffer |
+| `canvas_board` | `list` · `get` · `create` · `create-from` · `move-selection` · `open` · `update` · `pin` · `unpin` · `knowledge-list` · `category-set` · `category-remove` · `folder-set` · `relation-preset-set` · `relation-preset-remove` | Boards and workspace categories/folder properties/shared relation templates; knowledge writes never open a board. Template edits/deletion never rewrite boards or connections. `category-remove` takes `id` and refuses explicit folder assignments, including empty folders; reassign or clear them first. |
+| `canvas_snapshot` | `save` · `list` · `restore` · `restore-node` · `delete` · `gc` · `diff` | Named snapshots: save/list/restore/delete, garbage-collect old ones, diff current canvas vs a snapshot (`diff` takes `snapshot`, not `id`); `restore-node` puts one card (`nodeId`) back to its content in snapshot `id` |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `add-annotation` · `remove-annotation` · `get-tour` · `set-tour` · `tour-go` · `tour-exit` · `move` | Auto-arrange, pan-to-node, fit viewport, clear the board, draw/write/erase annotations, read/persist ordered presentation stops (`tour: null` derives group order), present a stop / exit, ease the camera to a node, rect or viewport (never an undo step) |
+| `canvas_query` | `context` · `graph` · `search` · `layout` · `validate` | Read the budgeted brief or summary-only connected memory graph, find nodes, read full layout, or **`validate`** collisions / containment / dangling edges |
+| `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | Hosted MCP apps, the Excalidraw diagram preset, and bundled web artifacts (folds `canvas_open_mcp_app` / `canvas_add_diagram` / `canvas_build_web_artifact`) |
+| `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | Headless Bun.WebView automation for the workbench (folds the `canvas_webview_*` / `canvas_resize` / `canvas_evaluate` tools) |
+| `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` · `presence` · `set-presence` | Read AX state; set AX focus; patch tool/prompt policy (the scope fence is human-set, read-only here); report host capability; read / set agent presence (phase, cursor, focus, attached session) |
+| `canvas_ax_work` | `add` · `update` · `annotate` | Canvas-bound work items + review annotations |
+| `canvas_ax_gate` | `request` · `resolve` · `await` × `kind` `approval` \| `elicitation` \| `mode` | Attributed gate lifecycle (request → await → resolve); attribution does not itself grant authority |
+| `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` · `reads` · `read-status` | The bounded AX diagnostics timeline, and the context read log (`reads`) |
+| `canvas_ax_delivery` | `claim` · `mark` | Adapterless steering delivery (claim → act → mark) |
+| `canvas_intent` | `signal` · `update` · `clear` | Ghost Cursor of Intent — announce a move before making it |
+
+Call shape examples: `canvas_node { action: "add", type, title }`,
+`canvas_view { action: "focus", id }`, `canvas_group { action: "create", childIds }`,
+`canvas_render { action: "add-graph", graphType, data }`,
+`canvas_query { action: "search", query }`,
+`canvas_ax_work { action: "update", id, status }`.
+
+Start board work with `canvas_query { action: "context", consumer:
+"<stable-unique-agent-id>", budget: 16000 }`. The budget is UTF-16 code units,
+not tokens. A durable cursor exists only with an explicit consumer and is scoped
+to the active board; no consumer means a fresh read, while explicit `since`
+does not advance a cursor. Pins come first. Follow a clipped entry's source
+board/card IDs with `canvas_board get` and `canvas_node get`.
+
+README designation is part of normal agent board authoring: read `canvas_board
+{ action: "get" }`, and when `readmeNodeId` is null, choose or create a concise
+markdown introduction and call `canvas_board { action: "update", id:
+"<board-id>", readmeNodeId: "<markdown-node-id>" }`. Explain the board's purpose,
+key context, and where to start. Do not pick an arbitrary first card. Preserve
+an existing README unless the human asks to change it, respect requests for no
+README, and do not mutate boards during read-only tasks. The browser's README
+control is a manual override, not a required setup step.
+
+For library work, `canvas_query { action: "search", query, scope: "library" }`
+reads inactive boards without opening them. Board links are native text-only
+`board` nodes with `data.boardId`. Preview `canvas_board create-from` before
+creation: `prompt`, `response`, `trace`, and `mcp-app` are excluded; README and
+group structure are optional; fresh IDs are allocated; pins, AX state, and
+history are not copied; the source remains unchanged and the new board inactive.
+The new board records `previousBoardId` pointing to its source.
+
+For an identity-preserving move, use `canvas_board` action `move-selection`, not
+copy/delete. Read the active source board's `contentRevision` with `get`. Preview
+with `sourceBoardId`, `nodeIds`, `name`, `expectedRevision: contentRevision`,
+`requestId` and `preview: true`; inspect blockers and notices before committing
+with the same inputs without `preview`. Retry an uncertain response with the same
+request ID and inputs. Group descendants move together; unsafe bindings refuse
+the entire move. Cards retain identities, pins, relations and review history,
+without new validation or read evidence. The source stays open with a portal to
+the new board. Pre-move Undo/Redo is cleared on affected boards; older snapshots
+remain inspectable but cannot be restored across the move. Open the returned
+`destinationBoardId` only when navigation is wanted.
+
+### Connected memory (wave 2)
+
+Home Folders, Map and Graph, wiki links/backlinks, and brief discovery share one
+board/card projection. Folders are neutral and independent of links. Map uses
+deterministic folder regions and saved draggable SQLite `mapPosition`; board
+update accepts `{ x, y }` or `null` to reset. Graph uses neutral circular clusters,
+not force simulation; labels are in selection details, filters in the shared
+toolbar, with no synthetic Home board, levels, or simulation sliders.
+
+Read it with `canvas_query { action: "graph", focus: "pins", depth: 2 }`,
+`canvas://graph{?focus,depth}`, `GET /api/canvas/memory-graph`, SDK
+`getMemoryGraph({ focus, depth })`, or CLI `pmx-canvas memory-graph`. Focus is
+a board ID, a JSON qualified key `["board-id","card-id"]` (or
+`["board-id",null]`), or `pins`; omitted means the library. URL-encode resource
+focus. Depth is an integer 0–4, default 2, traversing undirected links including
+membership. Explicit 0 is valid; empty depth and bare CLI `--depth` are rejected.
+HTTP, SDK and the MCP tool accept `projection: "full" | "boards"` (default `full`);
+CLI uses `--projection full|boards`. The graph resource uses the default full projection.
+Home Map uses compact `boards` summaries, loading depth-2 details on selection.
+Metadata edits and dragging do not refetch relationships; **Refresh** reloads them.
+Cross-board briefs give incoming and outgoing connections readable board/card titles.
+The result has `nodes`, `edges`, `unresolvedLinks: [{ source, ref }]`,
+`focus`, and `depth`. Nodes include qualified `key`, `boardId`, optional `cardId`,
+`kind`, `title`, `summary`, `folder`, `inContext`, and `summaryOnly: true`;
+summaries are capped at 280 characters. Edge projection kinds are `member`,
+`portal`, `wiki`, `card`, and `previous`, with qualified `from`/`to`,
+`source`/`target`, and explicit `missing`. Reads count links seen only when a node's
+incident relations are complete; focused nodes with `linksComplete: false` do
+not acknowledge omitted links. Brief entries with capped or omitted relations also
+carry `linksComplete: false`; near-pin, human, linked README and pinned-board
+summaries do not acknowledge unseen relations. Graph cards and complete brief
+relations carry their captured `linksRevision`, so later writes remain unseen;
+brief delivery is qualified by source board, never by a bare cross-board card ID.
+AX excerpts and annotation anchors, including `canvas://ax-context` and
+`pmx-current-context`, never mark incident relations seen; read a complete graph
+or brief relation entry instead.
+Single-card and layout reads record content delivery, not incident relations.
+Reads never switch boards or record full content reads. Pull cards in full
+when needed. Counts are 25 tools, 15 static canvas resources; there are now two
+canvas templates, context and graph, besides the skill file template.
+
+Markdown save resolves `[[Board]]`, `[[Board#Card]]`, and `|alias` forms into
+server-owned `data.wikiLinks` ID bindings. IDs win; name/title matches must be
+unique. Existing bindings survive renames. Ambiguous/missing links stay explicit
+and never guess or silently retarget. Rendering follows saved bindings: unresolved
+links stay unresolved until an explicit save, and Undo/restore preserves bindings.
+Legacy Markdown without binding metadata gets a one-time persisted backfill;
+saved empty or unresolved records are not reinterpreted on reads.
+Code spans/fences are ignored. A human
+Create dialog for an unresolved board-only link creates exactly the authored
+name and re-saves its source using the captured board/revision, refusing stale
+source writes.
+
+Once the board list has loaded, all workbench context-pin writes send the captured
+`expectedBoardId`; a server-side board switch returns 409 instead of changing
+another board's pins. Receipt pin actions require reopening the owning board.
+
+Embedded previews mount automatically near the viewport at every zoom and remain
+mounted to preserve arbitrary app state. There is no lifetime preview cap. Mermaid renders
+inline, without an iframe. JSON/graph viewers inherit all nine named canvas themes
+and keep form drafts when the theme changes. During replacement, the pending
+document temporarily coexists with its painted predecessor.
+
+A network load or missing JSON runtime times out after 10 seconds and offers a
+visible **Retry**, retaining the last painted document during replacement.
+An already mounted offscreen runtime may wait for paint without being timed out.
+
+Native edge add accepts optional `toBoardId`: `from` is on the open source board,
+`to` is a card on the target board. CLI: `pmx-canvas edge add --from <source> --to <target>
+--to-board <board-id> --type references`. The human More menu offers a card
+picker and the source footer shows remote connections. Auto-arrange stays local;
+static export omits remote lines but shows explicit external connection evidence.
+Edges accept open `kind`/`reason`; update null clears them. Boards accept
+`relationVocabulary: [{kind, ink, directed}]`, with six fixed relation inks, never pin/agent/warning
+colours. `derived-from`, `contradicts`, `supersedes` point source → dependent; `depends-on` points
+dependent → prerequisite. Ordinary references/wiki links/portals do not propagate review due.
+Lifecycle reads return qualification, including source observations. Validating dependent cards
+requires `expectedSources` from the evidence checked, plus `expectedContentRevision`; stale or
+unavailable sources refuse. Retired cards leave briefs/pinned context but remain marked in search
+and direct reads. Brief `lifecycle.complete: false` requires rechecking cached cards before reuse;
+empty incomplete lists are not a health claim. Recipe metadata is inert and refresh never validates.
+For human review, Home's Review needed count filters to affected boards, and each Review button
+opens an affected card. More → Review offers one short note and Checked, still correct; Not now
+writes nothing. Settings and history discloses clocks, policies and advanced outcomes. The folder
+tree is navigation, and No review policy is informational rather than an outstanding task.
+
+Use `canvas_board { action: "open", id: "<board-id>" }` to open a created or
+existing board before authoring. Verify the returned `activeBoardId`; opening
+switches the shared visible workbench and all subsequent write targets, not
+just this agent's context. `id: null` opens Home. Deletion stays human-only.
+
+`canvas_ax_gate` takes **two** discriminators, `{ kind, action }` — e.g.
+`{ kind: "approval", action: "request", title }`,
+`{ kind: "elicitation", action: "resolve", id, response }`,
+`{ kind: "mode", action: "await", id, timeoutMs }`. (The approval machine-readable action
+identifier is passed as `approvalAction`, since `action` is the lifecycle discriminator.)
+
+#### Narrate your next move with `canvas_intent` (Ghost Cursor of Intent)
+
+**Use the Ghost Cursor as much as possible** — it is the primary way to make your intent and your
+work visible on a shared board. Default to signaling before you act; skip it only for trivial
+in-place tweaks or high-frequency batch churn.
+
+Before you create/move/connect/edit/remove on the canvas, **signal the move** so a
+faint placeholder forms where you're about to act — the human sees the next move
+coming and can veto it mid-thought. Intents are ephemeral presence: never
+persisted, auto-expiring (~8s), never in `canvas_query layout`.
+
+Narrate → linked mutation → automatic settle:
+1. `canvas_intent { action: "signal", kind: "create", nodeType: "markdown", label: "Add evidence", reason: "capturing the failing test", confidence: 0.8 }` → returns `intent.id` and the `position` the canvas chose.
+2. Make the real move and pass that id: `canvas_node { action: "add", intentId: <intent.id>, ... }`.
+3. A human-vetoed intent rejects its linked mutation. A quietly expired ghost does not:
+   the write proceeds unlinked, subject to the ordinary permissions and revision checks.
+   A successful write linked to a still-live intent settles the ghost automatically.
+   Expiry is neither approval nor a human veto. Never retry a vetoed plan under a new ID
+   just to bypass the human's decision.
+
+Use `canvas_intent { action: "clear", id }` only when abandoning a plan without
+performing the linked mutation.
+
+**Linked settle is scoped to node, edge, and group mutations** (`canvas_node`,
+`canvas_edge`, `canvas_group` and their ops). `canvas_app` opens (diagram /
+mcp-app) and `canvas_webview` do **not** accept an `intentId` and reject it with a
+400 — to telegraph one of those, signal a ghost, then `clear` it (or let it
+expire) and run the open *without* an `intentId`.
+
+Per kind, pass the anchor it renders against: `position` for `move` (optional for
+`create`), `nodeId` for `move`/`edit`/`remove`, `edge: { from, to, type }` for
+`connect`. **Omit `position` on a create unless you know where the node goes:** the
+canvas then forms the ghost where it will auto-place the node, keeps staged ghosts
+from stacking, and lands the linked create on its ghost. Never pass a placeholder
+such as `{ x: 0, y: 0 }`. The payoff is **legibility** — `reason` is shown beneath
+the ghost.
+
+**When to use vs skip.** Signal for adds, removes, and moves of visible nodes;
+connecting nodes; creating groups; layout reorganizations; meaningful title/content
+edits; destructive actions (clear/restore/remove); and creating
+artifact/report/dashboard nodes. Skip for tiny metadata fixes, API-only pin/unpin
+verification, deterministic report-node refreshes the human just asked for,
+post-restore cleanup, and bulk fixture churn. **For batch work, signal one ghost
+per human-meaningful move, not one per low-level op.** Put its `intentId` inside the
+supported leaf operation's `args`, never on the `canvas_batch` envelope. Each live
+intent settles once; it is not a veto gate for every sibling in a batch. For example,
+after signalling a create intent, use its actual returned ID in this leaf:
+
+```json
+{"operations":[{"op":"node.add","args":{"type":"markdown","title":"Evidence","content":"Observed failure","intentId":"<returned-intent-id>"}}]}
+```
+
+Do not rely on a top-level batch `intentId`: standalone MCP can refuse it, while the
+attached HTTP batch reader does not forward it. Unsupported operations cannot be made
+veto-linked by wrapping them in a batch. Use `seq` to order separate staged previews.
+
+### Standalones (first-class — not deprecated)
+
+These stay separate by design (trust-boundary, firehose, execution-intent, or not-yet-consolidated
+surfaces): `canvas_batch`, `canvas_pin_nodes`, `canvas_screenshot`, `canvas_ax_interaction`,
+`canvas_ingest_activity`, `canvas_invoke_command`. Snapshots moved into the `canvas_snapshot`
+composite in v0.4.0 (actions `save | list | restore | delete | gc | diff`); the 6 legacy snapshot
+standalones were removed after their deprecated 0.3.x window.
+
+`canvas_batch` supports exactly these ops: `node.add`, `node.update`, `node.remove`, `graph.add`,
+`edge.add`, `edge.remove`, `group.create`, `group.add`, `group.remove`, `annotation.add`,
+`annotation.remove`, `pin.set`, `pin.add`, `pin.remove`, `snapshot.save`, and `arrange`.
+`edge.update` is not supported. Anything else fails with "Unsupported canvas_batch
+operation" — batch is non-atomic, so earlier ops stay applied and the response carries
+`failedIndex`, `results` and `refs`. Inspect that committed prefix before retrying; an
+error does not roll it back. `canvas_screenshot` requires an active automation WebView: call
+`canvas_webview { action: "start" }` first.
+
+> **Removed in v0.3.0 → use the composite instead**: `canvas_open_mcp_app` / `canvas_add_diagram` /
+> `canvas_build_web_artifact` → **`canvas_app`**; `canvas_webview_start` / `canvas_webview_status` /
+> `canvas_webview_stop` / `canvas_resize` / `canvas_evaluate` → **`canvas_webview`**;
+> `canvas_add_html_node` / `canvas_add_html_primitive` → **`canvas_node { action:"add", type:"html" }`**
+> (pass `primitive` for a primitive); `canvas_add_node` / `canvas_update_node` / `canvas_remove_node`
+> → **`canvas_node`**; `canvas_remove_annotation` → **`canvas_view { action:"remove-annotation" }`**;
+> `canvas_refresh_webpage_node` → **`canvas_node { action:"update", id, refresh: true }`**;
+> `canvas_validate` (board collisions / containment / dangling edges) → **`canvas_query` `validate`**;
+> `canvas_validate_spec` (json-render / graph spec dry-run) → **`canvas_render` `validate`**.
+
+### Node Operations
+
+MCP node-type routing — which tool creates which node category:
+
+| Node category | MCP creation call |
+|---------------|-------------------|
+| Basic nodes (`markdown`, `status`, `context`, `ledger`, `trace`, `file`, `image`, `webpage`) | `canvas_node { action: "add" }` |
+| `json-render` | `canvas_render { action: "add-json-render" }` |
+| `graph` | `canvas_render { action: "add-graph" }` |
+| `html` | `canvas_node { action: "add", type: "html", html }` |
+| `html-primitive` | `canvas_node { action: "add", type: "html", primitive: "<kind>", data }` |
+| `web-artifact` | `canvas_app { action: "build-artifact" }` |
+| `external-app` / tool-backed `mcp-app` | `canvas_app { action: "open-mcp-app" }` (Excalidraw preset: `canvas_app { action: "diagram" }`) |
+| `group` | `canvas_group { action: "create" }` |
+
+If a node type is rejected by `canvas_node { action: "add" }`, call
+`canvas_render { action: "describe-schema" }` and read `mcp.nodeTypeRouting`; do not keep
+retrying the generic add.
+
+**`canvas_node { action: "add", … }`** — Add a node to the canvas
+- `type` (required): basic node type only; structured/app/group nodes use the routing table above
+- `title`: short, scannable title
+- `content`: markdown text for most types. For `file`, pass the **file path** (e.g. `"src/auth/login.ts"`) —
+  the server auto-loads + watches it. For `image`, pass a file path, URL, or data URI.
+- `path`: compatibility alias for image paths only; prefer `content` for new image calls
+- `x`, `y`: position (prefer omitting for auto-layout); `width`, `height`: dimensions (sensible defaults); `metadata`: arbitrary JSON. (`color` applies to **group**/**graph** nodes only — it is ignored on basic node types; see Colors (Semantic).)
+- Returns: `{ id: "<node-id>" }` — capture this ID for edges and groups
+
+**`canvas_node { action: "update", id, … }`** — Update an existing node in place (preferred over
+delete+recreate; preserves edges, pins, position)
+- `id` (required), plus any of: `title`, `content`, `x`, `y`, `width`, `height`, `collapsed`, `arrangeLocked`, `data`
+- For `json-render`, pass `spec` to update the rendered spec in place
+- For `graph`, pass graph fields (`graphType`, `data`, `xKey`, `yKey`, `color`, `chartHeight`) to rebuild the chart; `height`/`nodeHeight` set frame geometry, `chartHeight` the chart content
+
+**`canvas_node { action: "remove", id }`** — Remove a node and all its connected edges. Clean up nodes that are no longer relevant.
+
+**`canvas_node { action: "get", id }`** — Get a single node's full data by `id`.
+
+**`canvas_view { action: "add-annotation", points, … }`** — Draw freehand ink with at least two
+world-coordinate points, or set `type: "text"`, `text` and one point to write a note.
+`width` is stroke width (default 4, clamped to 1–24) or font size (default 24,
+clamped to 1–96). `color` defaults to `currentColor`, the theme's annotation ink;
+explicit colors must be `#rrggbb`. Text is trimmed to 240 characters, labels to 160.
+Bounds and creation time are server-derived.
+
+Freehand points render as straight segments with round caps/joins, without automatic
+smoothing. Sample curves densely for smooth-looking outlines and loops. Cursor updates
+through `canvas_ax_state { action: "set-presence", cursor: { x, y } }` are separate,
+ephemeral presence, not drawing gestures; reuse your writer identity without attaching
+a session. An annotation appears complete on creation, not as a streaming stroke.
+See [Shared ink and questions](workbench-workflows.md#shared-ink-and-questions).
+
+Use an explicit `id` for retries: equal normalized content returns the existing mark
+without another Undo entry, while different content conflicts. After erasing or Undo,
+adding the ID creates a mark again; this is not a durable creation receipt.
+
+**`canvas_view { action: "remove-annotation", id }`** — Erase a whole human or agent mark,
+not the underlying card. An absent mark returns not-found. Context gives you IDs;
+inspect the canvas first when identifying a mark by shape or location.
+CLI and MCP batches accept `annotation.add` / `annotation.remove` with the same arguments.
+
+Humans and agents share this layer. Use marks when helpful, not for every task.
+The human may answer in the external agent host's composer; no PMX session,
+PMX composer or reply card is required. Marks are not approval gates, and drawing
+or erasing does not answer a question or execute a loop. Existing scope fences apply.
+
+**`canvas_node { action: "update", id, refresh: true }`** — 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_node({ action: 'add', type: 'webpage', url: 'https://example.com/docs' })
+  // → returns { id: 'node-abc' }
+
+  // …later, after the human reopens the canvas…
+  canvas_node({ action: 'update', id: 'node-abc', refresh: true })
+  // → re-fetches the URL, updates pageTitle + extracted text, keeps the node ID and position
+  ```
+
+**`canvas_render { action: "add-json-render", … }`** — Add a native json-render node
+- Required: `spec`; `title` is optional and inferred from the root element when omitted
+- Prefer a complete json-render object with `root`, `elements`, and optional `state`
+- Legacy bare component specs like `{ type: "Badge", props: {...} }` are accepted and wrapped into a one-element document for compatibility
+- 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_render { action: "stream-json-render", … }`** — Build a json-render node progressively (live)
+- Omit `nodeId` on the first call to create a streaming node (returns its `id`); reuse that `nodeId`
+  on later calls to append `patches`; set `done: true` on the final call.
+- `patches` are SpecStream JSON-Patch ops applied server-side (the canvas accumulates the spec), e.g.
+  `{ "op": "add", "path": "/elements/card", "value": { … } }`, `{ "op": "replace", "path": "/root", "value": "card" }`.
+- Build incrementally: set `/root`, add container elements, then append child element ids/elements.
+  Each call re-renders; partial specs render what they can. Use for dashboards/reports that fill in
+  as you generate them rather than appearing all at once.
+
+**`canvas_render { action: "add-graph", … }`** — Add a native graph/chart node
+- Required: `graphType`, `data`
+- Supports `line`, `bar`, `pie`, `area`, `scatter`, `radar`, `stacked-bar`, `composed`,
+  and the Tufte primitives `sparkline`, `dot-plot`, `bullet`, `slopegraph` (aliases accepted)
+- Use `xKey`/`yKey` for line, bar, area, and scatter graphs
+- Use `zKey` for scatter bubble size
+- Use `nameKey`/`valueKey` for pie graphs
+- Use `axisKey` plus `metrics` for radar graphs
+- Use `series` for stacked-bar graphs
+- Use `barKey`/`lineKey` plus optional `barColor`/`lineColor` for composed graphs
+- Bar charts: `colorBy` (`series` default = one accent + a highlighted bar, `category`, `value`, `none`) and `highlight` (`max`/`min`/index)
+- Use `valueKey` for `sparkline` (plus `fill`/`showEndDot`/`showMinMax`/`showValue`)
+- Use `labelKey`/`valueKey` (plus `sort`) for `dot-plot`
+- Use `labelKey`/`valueKey`/`targetKey`/`rangesKey` for `bullet`
+- Use `labelKey`/`beforeKey`/`afterKey` (plus `beforeLabel`/`afterLabel`/`colorByDirection`) for `slopegraph`
+- Use `nodeHeight` for the canvas frame height and `height` for chart content height
+- Uses the native json-render chart catalog under the hood
+
+**Tufte-aware charting** — color must encode data, not decorate. For chart design and critique, use
+the `tufte-viz` skill (`skills/tufte-viz/SKILL.md`). Key rules:
+- Single-series `bar` charts use `colorBy`: default `series` (one accent + one highlighted bar),
+  `category` (opt-in palette), `value` (sequential shade by magnitude), or `none` (flat). Do not
+  rainbow categorical bars by default.
+- Prefer the Tufte primitives where they fit: `sparkline` (inline trend), `dot-plot` (ranked single
+  metric vs. a bar forest), `bullet` (measure vs. target, replaces a gauge), `slopegraph`
+  (before/after across many categories).
+- Direct-label data (`showLegend: false`) instead of a legend when one or two series are identifiable.
+- For more than ~4 overlapping series, build small multiples (several small graph nodes on a shared
+  scale, arranged in a grid/group) instead of one multi-color chart.
+
+**`canvas_app { action: "build-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
+
+ID extraction for mixed tool responses:
+- Most add-style tools return a flat `id`; web artifacts return `id` plus `nodeId`; snapshots return `id` plus nested `snapshot.id`.
+- Defensive extractor: `const getId = (r) => r.id ?? r.nodeId ?? r.snapshot?.id;`
+
+**`canvas_app { action: "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_app { action: "diagram" }` for the built-in Excalidraw preset
+
+**`canvas_pin_nodes`** (standalone) — Set, add, or remove pinned context nodes. Use `{ nodeIds: [...] }` — the field is `nodeIds`, not `ids`.
+
+**`canvas_snapshot { action: "diff" }`** — Compare current canvas state with a saved snapshot. Requires `{ snapshot: "<snapshot-id-or-name>" }`; there is no implicit previous-snapshot default.
+
+**`canvas_render { action: "describe-schema" }`** — Inspect the running server's create schemas and
+canonical examples. Use before generating structured payloads when you need the authoritative current
+shape; read `mcp.nodeTypeRouting` to choose the right creation call for each node category.
+
+**`canvas_render { action: "validate", … }`** — Dry-run a json-render spec or graph payload without
+creating a node. Returns the normalized json-render spec the server would accept.
+
+**`canvas_view { action: "fit", … }`** — Fit viewport to all nodes or selected nodes; optional
+`width`, `height`, `padding`, `maxScale`, `nodeIds`. Use before screenshot/whole-board review so the
+server viewport matches the intended camera.
+
+**Batch graph creation** — Use the `graph.add` op inside `canvas_batch` / `pmx-canvas batch` for a
+graph node in a larger one-shot build. It takes the same shape as `canvas_render { action: "add-graph" }`.
+In batch/MCP/HTTP payloads, `height` is chart content height and `nodeHeight` is the canvas frame height.
+
+### Edge Operations
+
+**`canvas_edge { action: "add", … }`** — Connect two nodes
+- `from`, `to` (required): source and target node IDs
+- `fromSearch`, `toSearch`: optional search-based selectors when you do not have IDs. Each search
+  query must resolve to exactly one node or the edge creation fails with an ambiguity error.
+- `type`: `flow`, `depends-on`, `relation`, or `references` (default: `relation`)
+- `label`: descriptive relationship label; `style`: `solid`/`dashed`/`dotted`; `animated`: visual emphasis
+- `canvas_edge { action: "remove", id }` removes a connection by edge `id`.
+
+### Layout & Navigation
+
+- **`canvas_query { action: "layout" }`** — full canvas state (nodes, edges, viewport). Read before mutating.
+- **`canvas_view { action: "arrange", layout }`** — auto-arrange all nodes; `layout` is `grid` (default,
+  dashboards/overviews), `column` (vertical lists), or `flow` (horizontal sequences / dependency chains).
+  Call once after a batch of adds. For tiered/layered layouts, fine-tune with explicit `x`/`y` via
+  `canvas_node { action: "update" }` after arranging.
+- **`canvas_view { action: "focus", id }`** — pan the viewport to a node. Don't focus every node in a
+  batch — focus only the final result, or use CLI `focus --no-pan` to select/raise without moving the camera.
+
+### Groups
+
+- **`canvas_group { action: "create", … }`** — visual container; `title`, `childIds` (node IDs), `color`. Auto-sizes to fit children.
+- **`canvas_group { action: "add", groupId, childIds }`** — add nodes to an existing group.
+- **`canvas_group { action: "ungroup", groupId }`** — dissolve the group: its children become
+  independent nodes (members of the enclosing group when nested) and the frame is removed, in one
+  undo step. Exactly what the human's Ungroup does.
+
+### Group Layout Guidance
+
+Use groups as spacious semantic regions, not as tight containers. (Group calls below use
+`canvas_group { action: "create" | "add" | "ungroup" }`.)
+
+- Size the child nodes first, especially `graph`, `json-render`, `mcp-app`, image, and webpage
+  nodes whose rendered content may need more height than their visible title suggests.
+- Give every group generous interior padding. Reserve extra top padding for the group header, then
+  keep children clear of the frame edges so headers, glow, resize handles, and node chrome do not
+  visually collide.
+- If creating a group manually, compute its frame from the final child bounds plus padding. If the
+  group exists first, expand it before adding large children rather than shrinking children to fit.
+- Use groups to label major regions of a board. Avoid wrapping every small relationship; too many
+  tight groups make the canvas harder to read than no groups.
+- Keep edges local to a group where possible. Long cross-board edges can look like they come from
+  nowhere; use a nearby bridge/context node or split the relationship into shorter labeled edges.
+- After grouping, verify the result in `canvas_query { action: "layout" }` or the browser: child nodes should be
+  fully inside the group with padding, visible nodes should not overlap, and group headers should
+  not cover content.
+- If a group makes important content less visible, enlarge the group, split it into clearer
+  regions, or remove the group. Visibility is more important than preserving a frame.
+
+### Grouped Comparison Boards
+
+Use groups as named comparison areas, not just visual boxes.
+
+- Create the comparison frame first with `canvas_group { action: "create" }` or
+  `pmx-canvas group create`, then add charts, artifacts, and diagrams into that area deliberately.
+- Prefer graph nodes for fast capability demos and side-by-side comparisons. They are lightweight,
+  validate quickly, and are easier to regenerate.
+- Prefer web artifacts when the board needs a richer narrative UI, custom interaction, or a more
+  polished presentation layer than a graph or json-render node can provide.
+- Use Excalidraw for sketching and flow diagrams, but treat it as less reliable than web-artifact
+  app nodes for grouping and rediscovery until `mcp-app` grouping parity is fixed.
+- Native node types are still the most agent-friendly. Graph nodes are the strongest comparison
+  primitive today, web artifacts are good but heavier, and Excalidraw / other `mcp-app` nodes are
+  useful but still the weakest operationally for create, rediscover, group, and reconnect flows.
+- Leave larger spacing between major regions than you think you need. The spatial analyzer still
+  tends to read dense boards as one giant cluster unless groups and gaps are both clear.
+- If you are expanding a board incrementally, verify each add-to-group step instead of assuming
+  the node joined the area. Comparison workflows depend on reliable “add this thing to the region
+  I’m already building.”
+
+Current product caveats for grouped comparison boards:
+- `mcp-app` grouping parity is inconsistent. Web artifacts have grouped cleanly; Excalidraw has
+  not always behaved the same way.
+- Search/discoverability for external app nodes can degrade over time in-session, so node IDs are
+  safer than title-based rediscovery for follow-up grouping or focus operations.
+- `mcp-app` nodes are less inspectable than native nodes. For graph nodes you can reason from
+  structured config, but app nodes often only tell you that an app exists unless you also inspect
+  nearby markdown, file, or graph context.
+- Long-running web artifact builds can exceed a short command timeout. When using them in an
+  agent workflow, prefer progress-aware handling and avoid assuming a timeout means failure.
+
+### Search & Discovery
+
+**`canvas_query { action: "search", query }`** — Find nodes by title or content keywords. Returns
+ranked matches with content snippets. Use instead of parsing the full layout to locate specific nodes.
+
+### Context Pinning
+
+**`canvas_pin_nodes`** (standalone) — Manage pinned context: `nodeIds` (required) plus `mode`
+(`set` replaces all pins, `add`, `remove`).
+- Pinned nodes are the primary human-to-agent communication channel — when a human pins in the
+  browser, they're saying "pay attention to these."
+- Best default pin set: one intent-setting markdown node plus 1-3 concrete output nodes.
+- Graph, file, and markdown pins carry richer usable context than `mcp-app` pins. Artifact and
+  Excalidraw pins still matter as intent signals, but pair them with a markdown or graph pin so the
+  agent understands what is inside the app, not just that it matters.
+
+### History & Snapshots
+
+- **`canvas_history { action: "undo" }`** / **`canvas_history { action: "redo" }`** — step the mutation ring buffer.
+- **`canvas_snapshot { action: "save", name }`** — save a named snapshot. Returns `{ ok, id, snapshot }` (flat `id` aliases `snapshot.id`).
+- **`canvas_snapshot { action: "list" }`** / **`{ action: "gc", keep }`** / **`{ action: "delete", id }`** — manage saved snapshots.
+- **`canvas_snapshot { action: "restore", id }`** — restore from a snapshot.
+- **`canvas_snapshot { action: "diff", snapshot }`** — compare current canvas against a saved snapshot (added/removed/modified nodes & edges). Note the field is `snapshot` (id or name), not `id`.
+
+### Canvas Management
+
+**`canvas_view { action: "clear" }`** — Remove all nodes and edges. **Always `canvas_snapshot { action: "save" }` first** —
+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 every action
+below operates on the live canvas state through the `canvas_webview` composite.
+
+**`canvas_webview { action: "status" }`** — Inspect the current automation session
+- Returns `{ supported, active, headlessOnly, url, backend, width, height, dataStoreDir, startedAt, lastError }`
+  (the viewport size is `width` / `height`, not `viewportWidth` / `viewportHeight`)
+- Call before `start` to check whether a session is already alive
+
+**`canvas_webview { action: "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 { action: "status" }`
+- **Backend preflight**: prefer `webkit` on macOS — it is the reliable
+  automation backend across tested hosts. The `chrome` backend can trigger a
+  native "Allow remote debugging?" dialog on first start in some hosts; if the
+  prompt is not approved promptly the start times out with `ok:false`. When
+  using `chrome`, approve the dialog immediately and/or raise
+  `PMX_CANVAS_WEBVIEW_TIMEOUT_MS` (e.g. `30000`). A single chrome timeout is
+  worth one immediate retry before classifying it as a failure.
+
+**`canvas_webview { action: "stop" }`** — Tear down the automation session
+
+**`canvas_webview { action: "evaluate" }`** — Run JavaScript inside the workbench page and return the result
+- Required: exactly one of `expression` (single JS expression) or `script` (multi-statement body)
+- `script` is wrapped in an async IIFE, so top-level `await` works inside script bodies
+- Useful for asserting DOM state after a sequence of canvas mutations
+- Do not use `fetch()` inside `canvas_webview { action: "evaluate" }` to call PMX HTTP APIs; WebView
+  security/CORS restrictions can block those requests. Use the matching MCP tools instead.
+- Example: read the count of rendered `.canvas-node` elements:
+
+  ```typescript
+  canvas_webview({ action: 'evaluate', expression: 'document.querySelectorAll(".canvas-node").length' })
+  ```
+
+Useful workbench selectors:
+- Nodes: `.canvas-node`, `.canvas-node.active`, `.canvas-node.context-pinned`, `.canvas-node.group-node`
+- Node internals: `.node-title`, `.node-titlebar`, `.node-body`, `.node-type-badge`, `.node-controls`
+- Annotations: `.annotation-layer path` renders shared freehand ink; `.annotation-layer text`
+  renders text notes. Use WebView to inspect or screenshot shapes; MCP/context resources
+  expose IDs, text, labels, targets and bounds, not raw stroke geometry. Humans use the
+  rail's Draw / Text note / Eraser tools; agents use `canvas_view` actions
+  `add-annotation` / `remove-annotation` on the same layer.
+- Canvas chrome (rail-chrome-v2): `.tool-rail`, `.top-bar` (`.connection-dot`, `.agent-chip`,
+  `.gate-badge`, `.context-chip`, `.external-indicator`, `.start-session-btn`),
+  `.connection-banner`, `.canvas-region`, `.session-panel`, `.command-bar`, `.selection-bar`,
+  `.activity-feed`, `.writers-sheet`, `.session-receipt`, `.snapshot-panel` (the History
+  drawer), `.minimap`, `.empty-state`, `.command-palette`, `.expanded-overlay-panel`.
+- Presence: `.agent-cursor` (attached or external agent), `.human-cursor` (other tabs), `.scope-fence`,
+  `.canvas-node.agent-mutating` (shimmer), `.node-yield-pill`.
+- Groups: `.canvas-node.group-node` with `.group-name-pill`, `.group-actions`, `.group-chip`
+  (collapsed); `.drop-pill` while a dragged node would join/leave a group; `.edge-hint-pill`
+  during an edge drag.
+- Every `.canvas-node` carries `data-node-id` and `data-node-type` (rail-chrome redesign); `canvas_query`
+  (`layout` / `search`) remains the reliable way to get ids without a browser.
+
+Async script example:
+
+```typescript
+canvas_webview({
+  action: 'evaluate',
+  script: 'const title = await Promise.resolve(document.title); return title;',
+})
+```
+
+**`canvas_webview { action: "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_webview { action: "resize" }` to control the framing
+
+Typical flow when you want to show a result:
+
+```typescript
+canvas_webview({ action: 'start', width: 1440, height: 900 });
+// …mutations…
+canvas_screenshot({ fullPage: true });
+canvas_webview({ action: 'stop' });
+```
+
+### Diagrams (Excalidraw MCP app preset)
+
+**`canvas_app { action: "diagram" }`** — Draw a hand-drawn diagram on the canvas via the hosted
+[Excalidraw MCP app](https://github.com/excalidraw/excalidraw-mcp)
+- Required: `elements` — an array of Excalidraw elements (rectangles, ellipses, diamonds, arrows,
+  text). Can also be a JSON-array string.
+- `elements` must be Excalidraw element objects, not Mermaid/DOT/source-text diagrams. Convert source diagrams to Excalidraw elements first or use a markdown/web-artifact node.
+- Optional: `title`, `x`, `y`, `width`, `height`
+- The diagram opens inside an `mcp-app` node with fullscreen editing and draw-on animations
+- CLI equivalent: `pmx-canvas external-app add --kind excalidraw --title "Diagram"`
+- Edits made in expanded/fullscreen mode are persisted back into the node model context and replayed
+  when the app iframe remounts.
+- Use this when the human needs a quick sketch, architecture diagram, or flowchart and a
+  geometric `graph` node would feel too rigid
+- Prefer labeled shapes (`"label": { "text": "..." }` on rectangle/ellipse/diamond) over
+  separate text elements — fewer tokens and auto-centered
+- Do not use separate `text` elements with `containerId`/`boundElements` to place centered text
+  inside shapes. The hosted SVG preview does not auto-position those; PMX normalizes imported
+  canonical bound text back into shape labels for hosted app calls.
+- For detailed sizing, camera, and label-fit rules, read `excalidraw-diagram-authoring.md`
+  before creating dense diagrams.
+- Prefer the pastel fill palette in the Excalidraw `read_me` (light blue/green/orange/...) for
+  a consistent look across diagrams
+
+### External MCP apps (bring your own)
+
+**`canvas_app { action: "open-mcp-app" }`** — Open any external [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps)
+server's `ui://` resource as an iframe node on the canvas
+- Required: `toolName`, `transport` (`http` URL or `stdio` command)
+- Optional: `serverName`, `toolArguments`, `title`, `x`, `y`, `width`, `height`
+- Use when no dedicated preset exists yet. The Excalidraw preset (`canvas_app { action: "diagram" }`) is the
+  only one today
+
+### Web Artifacts
+
+**`canvas_app { action: "build-artifact" }`** — Build a single-file HTML artifact from React/Tailwind source
+- Required: `title`, `appTsx`
+- Optional: `indexCss`, `mainTsx`, `indexHtml`, extra `files`, `projectPath`, `outputPath`, `deps`, `includeLogs`
+- By default it opens the result on the canvas as an embedded app node
+- By default it returns compact log summaries; set `includeLogs: true` when you need raw stdout/stderr
+- `recharts` is available in the scaffold. For additional libraries, pass CLI `--deps name,name2`
+  or MCP/API `deps: ["name"]` before bundling.
+- Failed or empty CLI bundles print `ok: false`, exit non-zero, and do not create a canvas node.
+- Use this when the output should be a richer interactive UI than a simple markdown/file/image node
+- Prefer the dedicated `web-artifacts-builder` skill when you need the full React + shadcn workflow
+- Use the `playwright-cli` skill when you need to validate the built artifact in a live browser
+
+### HTML Nodes (Sandboxed iframe)
+
+**`canvas_node { action: "add", type: "html", html }`** — Add a normal self-contained HTML document rendered in a sandboxed iframe
+- Required: `html` (full document or fragment; inline `<script>` and CDN `<script src="...">` are allowed). If `html` is a bare path to an existing local `.html`/`.htm` file, the server reads that file's contents; otherwise it is treated as raw HTML.
+- Optional: `title`, `summary`, `agentSummary`, `presentation`, `slideTitles`, `embeddedNodeIds`, `embeddedUrls`, `x`, `y`, `width` (default 720), `height` (default 640), `strictSize`
+- Iframe sandbox is `allow-scripts` only — no same-origin access, no top-navigation, no forms
+- Canvas theme tokens are auto-injected as CSS custom properties (both `--c-*` and common `--color-*` aliases such as `--color-text-primary`, `--color-bg`, `--color-accent`) and updated live when the canvas theme changes
+- Use for moderate-complexity visualizations and interactive widgets that need real JS but do not warrant a full React build (Chart.js demos, D3 sketches, custom HTML report views)
+- Normal HTML is the default. Only pass `presentation: true` when the user explicitly asks for a deck/fullscreen presentation; otherwise do not mark raw HTML as presentable.
+- Only presentation-marked HTML nodes expose a browser `Present` button. Use it when the HTML is a deck, briefing, or fullscreen review surface; the PMX shell owns the fullscreen overlay and exits via `Esc` or `Exit presentation`.
+- PMX stores a semantic sidecar (`agentSummary`, `contentSummary`, embedded references) so HTML nodes remain understandable in search, pinned context, and spatial context
+
+**`canvas_node { action: "add", type: "html", primitive, data }`** — Generate a reusable HTML communication primitive as a sandboxed `html` node
+- Required: `kind`; run `canvas_render { action: "describe-schema" }` and read `htmlPrimitives` for the current catalog
+- Optional: `title`, `data`, `x`, `y`, `width`, `height`, `strictSize`
+- Use when markdown would be too dense and a structured visual artifact is clearer: tradeoff grids, implementation plans, PR reviews, module maps, design sheets, explainers, reports, and lightweight human-editable boards/editors
+- When the human asks for a PowerPoint-like output, pitch deck, briefing, or presentation, use `kind: "presentation"` unless a bespoke raw HTML deck is required. Include `slides` with short titles, one idea per slide, optional `metrics`, `note` fields for speaker notes, and optional `theme: "canvas" | "midnight" | "paper" | "aurora"` or a custom theme object.
+- For payload patterns, export loops, and the primitive catalog, read `html-primitives.md` before creating dense or editable artifacts
+
+### Open as Site (standalone surfaces)
+
+Any renderable surface node can be opened full-page in its own browser tab — the same
+document it shows in the canvas, just without the node chrome. In the workbench, use the
+↗ **Open as site** button (new tab) or the ⤤ **Open in system browser** button in the
+node title bar (or the expanded overlay). "Open in system browser" launches the real OS
+browser via `POST /api/canvas/open-external` `{ nodeId }` (it opens only this server's own
+surface URL; falls back to a normal new tab when the server can't launch) — use it when
+the host's embedded browser (e.g. Codex) opens `_blank` tabs in-place.
+
+- Works for `html` / `html-primitive`, bundled `web-artifact`, `json-render` / `graph`,
+  and `webpage` nodes. **Hosted ext-app `mcp-app` nodes (e.g. Excalidraw) are NOT
+  open-as-site targets** (the control is hidden; see the ext-app bullet below).
+- The tab loads the node's stable surface URL, `/api/canvas/surface/<nodeId>`. The
+  in-canvas iframe loads the **exact same URL**, so there is one render path and no
+  separate "preview" version — what you see in the canvas is what opens. The URL reflects
+  current node state and survives a refresh.
+- Agents can read this URL from any node payload (`canvas_node { action: "get" }` /
+  `canvas_query { action: "layout" }`) as `surfaceUrl` — a reliable way to tell a human
+  "open the artifact" without disturbing the canvas.
+- Served HTML stays sandboxed (opaque origin via a `Content-Security-Policy: sandbox`
+  response header), so opening author code top-level cannot reach the canvas origin.
+- Hosted ext-app `mcp-app` nodes (e.g. Excalidraw) are a live MCP-app shell that only
+  renders with the in-canvas host bridge — a bare tab has no peer, so the surface route
+  returns `404` ("This MCP app renders in the canvas and cannot be opened as a standalone
+  site"); view/edit them in the canvas, or open them externally through their own app
+  (report #61). `POST /api/canvas/open-external` refuses those nodes with the same message
+  instead of launching a browser at a URL that 404s. Only bundled `web-artifact` apps
+  (redirect to `/artifact`) and URL-backed `mcp-app` / `webpage` viewers redirect to their
+  external site.
+- `graph` / `json-render` nodes redirect to the full-viewport `display=site` viewer; the chart
+  fills the window and reflows on a live resize. Current Codex builds deliver live-resize events —
+  the 0.4.6 pass watched a standalone graph reflow live (SVG 1550×783 → 850×483 on a
+  1600×900 → 900×600 window resize) with no reload — so do not present a system browser as a
+  workaround for stale resizing (report #67).
+- This is additive — opening a site never evicts or replaces canvas nodes.
+
+### Choosing the Right Visual Tier
+
+When the output is more than markdown, pick the lightest tier that fits:
+
+| Tier | Tool | Build cost | When to pick it |
+|------|------|------------|-----------------|
+| Declarative UI | `canvas_render` (`add-json-render` / `add-graph`) | None | Schema-driven dashboards, forms, charts; agent-friendly to read back via `canvas_node { action: "get" }` |
+| Generated HTML primitive | `canvas_node { action:"add", type:"html", primitive }` | None | Reusable communication artifacts such as choices, plans, reviews, maps, reports, presentations/decks, and lightweight editors |
+| Sandboxed HTML+JS | `canvas_node { action:"add", type:"html", html }` | None | Self-contained HTML with inline JS or CDN scripts; one-off visualizations or report views |
+| Hosted MCP app | `canvas_app { action:"open-mcp-app" }` / `canvas_app { action:"diagram" }` | None | Interactive editors backed by an external MCP server (e.g. Excalidraw) |
+| Bundled React app | `canvas_app { action:"build-artifact" }` | Heavy (npm install + bundle) | Multi-component UIs needing React state, routing, shadcn/ui, or Tailwind class composition |
+
+### Native Structured UI
+
+Use native `json-render` and `graph` nodes when the output should stay fully inside PMX Canvas:
+
+1. Use `canvas_render { action: "add-json-render" }` for dashboards, forms, summaries, and interactive UI panels
+2. Use `canvas_render { action: "add-graph" }` for charts and trend visualizations
+3. Use the repo-local `json-render-*` skills when you need help authoring or refining the spec itself
+4. Use `canvas_app { action: "build-artifact" }` instead when the result needs a full custom React app rather than a schema-driven UI
+
+Spec elements support an `on` map (`on.press`, `on.change`, …) binding events to actions (`{ action, params }`) — built-in actions (`setState`, `pushState`, …) or, when named after an AX interaction type, a capability-gated AX emit. e.g. a Button with `on: { press: { action: 'ax.work.create', params: { title: '…' } } }` lets a human turn a panel control into a tracked work item; the viewer forwards it to the canvas, which validates and submits it server-side (clamped to the node's own id). See **Node AX Interactions** above.
+
+## MCP results and cancellation (0.10)
+
+The 25-tool catalog remains on MCP SDK v1. Each tool advertises `outputSchema`
+and effect annotations. Help returns `structuredContent.result` with operation
+metadata (or the name list); it records no content reads. Registry-dispatched tools expose
+`structuredContent.result = { operation, outcome, data }`, where `outcome` is
+`success`, `error` or `partial`; `data` matches the existing compact text JSON,
+or `{message}` for prose. Exceptions use `operation: null`; they do not prove no
+writes occurred. Interaction, activity-ingestion and screenshot tools instead
+use direct structured objects matching their schemas. Check `isError` and domain
+outcomes. A composite's annotations cover all its actions, not just reads.
+
+Paired example: `canvas_node { action: "add", type: "markdown", content: "Evidence" }`
+returns registry data under `structuredContent.result.data` (excerpt; the ID varies):
+
+```json
+{"result":{"operation":"node.add","outcome":"success","data":{"ok":true,"id":"example-node"}}}
+```
+
+By contrast, `canvas_help {}` returns `structuredContent.result.operations`, not
+`result.data`. `canvas_help { op: "node.add" }` returns metadata with `operation`,
+`tool`, `description` and `inputSchema` directly under `result`.
+For direct tools (`canvas_ax_interaction`, `canvas_ingest_activity`, `canvas_screenshot`),
+read fields directly from `structuredContent` according to their `outputSchema`.
+These are different contracts, not optional wrappers to strip recursively. Text blocks
+are a separate representation; an SDK/host may already return `structuredContent`.
+On a failed call, inspect its error response and partial results before retrying writes.
+
+Cancellation releases supported AX waits, aborts webpage fetches before late
+content writes, and stops subsequent batch operations. Completed writes remain;
+batch partial results retain `results` and `refs`. A created webpage can remain
+with `fetch.cancelled: true`. External app builds/runtime calls and local WebView
+captures are not interruptible mid-call. After a disconnect, inspect state before
+retrying because the response may not arrive. `_meta.progressToken` enables batch
+and supported AX wait progress notifications, including through the daemon connection. Without
+a token, calls return their normal result without progress notifications.
+
+## MCP Resources
+
+These resources give you read access to canvas intelligence. Read them to understand
+what the human has set up and what they're focusing on.
+
+As of 0.10, live resource updates require `resources/subscribe` on each connection.
+Subscribe to the exact URI you read, including context/graph query parameters;
+`resources/unsubscribe` stops it, and reconnecting requires a new subscription.
+Notifications invalidate cached data but do not deliver content, record a read, or
+advance a consumer cursor. Explicit `resources/read` remains available without
+subscriptions. Static schema and bundled skills do not support subscriptions.
+
+| Resource | What it provides |
+|----------|-----------------|
+| `canvas://context{?budget,consumer,since}` | Budgeted cross-board map brief with optional durable consumer cursor |
+| `canvas://graph{?focus,depth}` | Summary-only connected memory projection, library or focused undirected membership-inclusive exploration |
+| `canvas://boards` | Board library with README summaries, links/backlinks and previews |
+| `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 (viewport, nodes, edges) |
+| `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 (JS/TS, Python, Go, Rust) |
+| `canvas://ax` | Host-agnostic AX state: focus, work items, approval gates, review annotations, host capability |
+| `canvas://ax-context` | Agent-ready AX context: pinned context + current focus |
+| `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations, elicitations, mode requests, and tool/prompt policy |
+| `canvas://ax-timeline` | Bounded AX timeline: recent agent events, evidence, and steering messages |
+| `canvas://ax-pending-steering` | Adapterless delivery: `pending` steering to claim + mark delivered, and `pendingActivity` (open work items / pending approvals / elicitations / mode requests awaiting the agent) |
+| `canvas://ax-delivery` | Steering delivery state (delivered flag) for diagnostics |
+| `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. |
+
+### Node AX Interactions (capability-gated)
+
+Eligible nodes can emit one normalized, validated AX interaction that maps onto an
+AX operation — work item, evidence, approval, review, focus, steering, event,
+elicitation, or mode request. One envelope, many transports:
+
+This is the **agent-native nodes** model: existing canvas node types become
+interactive agent controls when their AX capabilities allow it. Do not describe
+this as a separate node type; it is a capability layer on top of markdown,
+status, HTML, json-render, graph, web-artifact, MCP app, and other supported
+nodes.
+
+- **Endpoint:** `POST /api/canvas/ax/interaction` with
+  `{ type, sourceNodeId, payload }` (MCP: `canvas_ax_interaction`; CLI:
+  `pmx-canvas ax interaction`). Returns `{ ok, primitive }` or
+  `{ ok: false, code }` if the node type/metadata disallows the type.
+- **Capabilities:** each node type has a default capability set (a ceiling). A
+  node may opt in or narrow via `data.axCapabilities` (`{ enabled, allowed }`),
+  clamped to the ceiling — a node can never escalate beyond its type's ceiling.
+  `html` / `html-primitive`, `mcp-app`, and internal `prompt` / `response` nodes
+  are **disabled by default** (opt-in).
+- **Transports:** native node controls call the endpoint directly. Sandboxed
+  surfaces emit via a nonce-tagged `postMessage` the parent canvas validates
+  before submitting: `html` / `html-primitive` nodes (when opted in) call
+  `window.PMX_AX.emit(type, payload)`; **json-render / graph** viewers forward a
+  spec action named after an AX type (e.g. `on.press → { action:
+  "ax.work.create", params }`, `sourceSurface: 'json-render'`); web-artifact
+  **`mcp-app`** nodes use the same parent bridge; external MCP app frames
+  (`mode: "ext-app"`) can emit through an injected `window.PMX_AX.emit` with
+  Promise acknowledgements, but do not get the read-state bridge. The server
+  re-validates capabilities regardless of transport — bridges are convenience,
+  not a trust boundary.
+- **Delivery (adapterless):** `canvas://ax-pending-steering` /
+  `canvas_ax_delivery { action: "claim" }` return two things, both loop-safe (a consumer never
+  receives items it originated):
+  - `pending` — undelivered **steering** (directives). Act, then acknowledge with
+    `canvas_ax_delivery { action: "mark" }`.
+  - `pendingActivity` — open canvas-bound items **awaiting the agent** (open work
+    items, pending approval gates / elicitations / mode requests), usually created
+    by the human in the browser. These are **state, not steering**: don't
+    `canvas_ax_delivery { action: "mark" }` them — resolve each via its gate/work call
+    (`canvas_ax_gate { kind: "approval", action: "resolve" }` /
+    `canvas_ax_gate { kind: "elicitation", action: "resolve" }` /
+    `canvas_ax_gate { kind: "mode", action: "resolve" }` /
+    `canvas_ax_work { action: "update" }`).
+  - **Contract:** every AX mutation fires `ax-state-changed`, so MCP clients that
+    **subscribe** to resources are pushed `canvas://ax-work` / `canvas://ax-context`
+    live. Clients that **poll** instead should poll `canvas_ax_delivery { action: "claim" }` —
+    `pendingActivity` is how non-steering browser changes reach them. Only steering
+    flows through the claim/ack queue.
+  - **Steering is gated, not pushed (and does NOT wake the agent).** A surface button
+    that emits `ax.steer` *records/queues* a steer (the `ok:true` emit ack means
+    "recorded", not "the agent woke") — it does NOT interrupt or notify the active
+    session. With a prompt-injecting host adapter (e.g. Copilot), it reaches the next
+    turn only when (1) the **pin/focus gate is open** (something pinned or focused — so
+    keep a steering board pinned, or have its button also emit `ax.focus.set` on
+    itself), (2) a **human message** fires the turn, and (3) the agent **acts then acks**
+    (`canvas_ax_delivery { action: "mark" }`), or the steer re-injects every gated turn.
+    Immediate wake (turning a queued steer into a visible turn) is **host-adapter-owned**
+    — the adapter must drain `canvas_ax_delivery { action: "claim" }` and call its native
+    send. So a steering button should label itself honestly ("queued for the agent's next
+    turn"), never imply it steers the agent *now*. `GET /api/canvas/ax/context?consumer=<id>`
+    adds a compact, loop-safe `delivery: { pendingSteering, totalPending, omittedPending,
+    pendingActivity }` lead block an adapter injects un-truncated; `pendingSteering` is
+    **newest-first** (most recent first), capped at 10, so a fresh steer is visible even
+    behind a backlog, and the counts say how many more to drain from the FIFO
+    `canvas_ax_delivery { action: "claim" }` queue (which stays oldest-first).
+- **Activity ingestion (bidirectional board):** a host adapter forwards the agent's
+  tool/session events with `canvas_ingest_activity` (standalone; HTTP `POST /api/canvas/ax/activity`)
+  and the board auto-reacts — `failure`/`error` (or `outcome:"failure"`) → a blocked
+  work item + a review finding + `logs` evidence; `tool-result` + `outcome:"success"` →
+  `tool-result` evidence; everything else records a timeline event only. Override or
+  suppress per call via `reactions` (`{ workItem: false }`, `{ review: { severity } }`, …).
+- **Blocking gates (gates that actually gate):** `canvas_ax_gate` is the request →
+  await → resolve machine. After `{ action: "request" }`, call
+  `canvas_ax_gate { kind, action: "await", id, timeoutMs }` (HTTP
+  `GET /api/canvas/ax/<kind>/<id>?waitMs=`) to BLOCK until the human resolves it in the
+  browser or the timeout elapses (`timeoutMs` 0 = immediate read; ≤120000). Use this to
+  pause real work on a human decision instead of polling.
+- **Elicitation / mode:** request structured human input
+  (`canvas_ax_gate { kind: "elicitation", action: "request" }` →
+  `canvas_ax_gate { kind: "elicitation", action: "resolve" }`) or a workflow
+  mode transition (`canvas_ax_gate { kind: "mode", action: "request" }` →
+  `canvas_ax_gate { kind: "mode", action: "resolve" }`); both are canvas-bound and snapshotted.
+- **Commands:** invoke a registry command — `pmx.plan`, `pmx.execute`,
+  `pmx.promote-context`, `pmx.summarize`, `pmx.review` — via
+  `canvas_invoke_command` (standalone; HTTP `POST /api/canvas/ax/command`; CLI
+  `pmx-canvas ax command invoke`; envelope `ax.command.invoke`). Unknown names
+  are rejected; an invocation records an `agent-event` of kind `command`.
+- **Policy:** a canvas-bound, snapshotted tool/prompt policy
+  (`tools.allowed|excluded|approvalRequired`, `prompt.systemAppend|mode`, and the
+  **scope fence** `scope: { nodeIds, padding }`) read into `canvas://ax-context`. Patch it
+  with `canvas_ax_state { action: "set-policy" }` (HTTP `GET|POST /api/canvas/ax/policy`;
+  CLI `pmx-canvas ax policy get|set`); patches merge and are normalized server-side.
+  While a fence is set, your canvas WRITES outside it (nodes not in the set, new nodes
+  outside the fenced box, arrange/clear/restore) are refused with HTTP 403 naming the
+  reason; reads are never fenced. The fence is the human's: `set-policy` does not take
+  `scope`, and an HTTP policy call that includes it is refused (403). Read `policy.scope`
+  before writing and ask the human to widen it rather than retrying.
+- **External steering (no session):** a writer with no attached session is shown passively —
+  a top-bar indicator (avatars, "N writers · M ops"), a click-to-open activity feed (one row
+  per write: "Created markdown “…”" under the writer's label, per-writer filters, inline Veto
+  on your pending explicit intents) and a connected-writers sheet. Pure visibility: pmx-canvas
+  is local-first and veto/ghosting is the safety model, not permissions. The feed is
+  `activity` on `GET /api/canvas/ax/presence` (`canvas_ax_state { action: "presence" }`).
+- **Session receipt:** attaching a session (`set-presence { attached: true }` or a
+  `session-start` activity) over a non-empty board saves a `Before session · <label> · HH:MM`
+  snapshot; ending it (`attached: false`, `session-end`, or idle expiry) emits one
+  `agent-session-ended` SSE frame with `label`, `endedAt`, `snapshot`, `context` and counts
+  (`items`, `done`, `cancelled`, `rejected`, `held`). Changed top-level endings show a receipt;
+  worker and unchanged endings stay in History, and qualifying endings merge into an open receipt.
+  **See change** opens one stacked Before/After; whole-card Undo preserves geometry and links.
+  Receipt Undo sends `preserveHumanEdits: true` to `restore-node`, so the server skips latest-human
+  edits even when the browser is stale. Agent callers can pass that option to `canvas_snapshot`
+  too: `restored: false, skipped: "human-edit"` is not an undone card. Receipt Unpin only removes
+  its recorded pins, never re-pins them. Reopen a receipt's board before Undo or comparison;
+  Home dismisses it. End your session explicitly so the receipt is prompt. The human's
+  *Start agent session* button is the same attach with `source: "browser"`.
+- **Human collaborators / user wins:** every open workbench tab is a presence (`GET
+  /api/canvas/human-presence`); a node a human is dragging is locked — an agent write to it is
+  refused with 409 until release (requeue and retry), and a pending explicit intent on it is
+  vetoed with a `yield` timeline event.
+- **Unattended approvals:** a pending approval gate carries a TTL (`ttlMs` on the request,
+  default 5 min). If the human does not answer in time it resolves to `held` — a
+  non-approval: do not proceed — and a `policy` agent-event explains why. The human can
+  reopen it from the session panel; an `await` on the gate returns when it leaves
+  `pending`, so treat any status other than `approved` as "do not proceed".
+
+Interactions request PMX-AX primitives only — never arbitrary shell, tool, MCP,
+or host execution.
+
+#### Where AX can be used — node capability matrix
+
+AX interactions are gated per node type. The lists below are each type's **ceiling**
+— `data.axCapabilities.allowed` can NARROW it, never escalate beyond it.
+
+**Enabled by default** (no opt-in needed — an agent/native control can emit straight away):
+
+| Node type | Allowed AX interaction types |
+|-----------|------------------------------|
+| `markdown` | `ax.steer`, `ax.work.create`, `ax.work.update`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
+| `context` | `ax.focus.set`, `ax.steer`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
+| `status` | `ax.work.create`, `ax.work.update`, `ax.approval.request`, `ax.mode.request`, `ax.event.record` |
+| `file` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
+| `json-render` | `ax.work.create`, `ax.work.update`, `ax.evidence.add`, `ax.elicitation.request`, `ax.event.record` |
+| `graph` | `ax.evidence.add`, `ax.focus.set`, `ax.event.record` |
+| `ledger` | `ax.evidence.add`, `ax.event.record` |
+| `trace` | `ax.evidence.add`, `ax.event.record` |
+| `image` | `ax.evidence.add`, `ax.review.add` |
+| `diff` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
+| `mermaid` | `ax.steer`, `ax.work.create`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
+| `webpage` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
+| `group` | `ax.focus.set`, `ax.work.create`, `ax.command.invoke`, `ax.event.record` |
+
+**Opt-in** — set `axCapabilities.enabled = true` (MCP: pass `axCapabilities` to
+`canvas_node { action: "add", type: "html" }` / `canvas_node { action: "update" }`. HTTP:
+`axCapabilities` **and** the `html` body are accepted **top-level on both `POST /api/canvas/node`
+and `PATCH /api/canvas/node/<id>`**, or nested under `data` — both work, top-level wins):
+
+| Node type | Allowed AX interaction types |
+|-----------|------------------------------|
+| `html` / `html-primitive` | the full set: `ax.work.create`, `ax.work.update`, `ax.steer`, `ax.approval.request`, `ax.review.add`, `ax.evidence.add`, `ax.focus.set`, `ax.elicitation.request`, `ax.mode.request`, `ax.command.invoke`, `ax.event.record` |
+| `mcp-app` (incl. **web-artifact**) | `ax.event.record`, `ax.evidence.add`, `ax.work.create`, `ax.work.update`, `ax.focus.set`, `ax.elicitation.request` |
+
+**Never (anchor-only):** internal `prompt` / `response` thread nodes — `ax.event.record`
+only, no human-facing emit.
+
+The 11 interaction types and what they create: `ax.work.create` / `ax.work.update`
+(work-queue items; status is exactly one of `todo`, `in-progress`, `blocked`, `done`,
+`cancelled` — **hyphens, not underscores**; `POST`/`PATCH /api/canvas/ax/work` reject an
+unknown token like `in_progress` with `400`), `ax.evidence.add`
+(timeline evidence), `ax.review.add` (review annotation), `ax.focus.set` (agent focus
+pointer), `ax.steer` (a steering message delivered to the agent), `ax.approval.request`
+(approval gate), `ax.elicitation.request` (structured human input), `ax.mode.request`
+(plan/execute/autonomous transition), `ax.command.invoke` (registry command), and
+`ax.event.record` (diagnostic agent-event).
+
+#### Building an AX surface in the canvas (emit + reflect)
+
+AX surfaces are **composable** — you can build a live work board, review board, or
+inbox as a canvas node that BOTH emits AX interactions AND renders the current AX
+state. The read side mirrors the write side:
+
+- **Opt in** (html/mcp-app are off by default): create with
+  `canvas_node({ action: "add", type: "html", html, axCapabilities: { enabled: true, allowed: ["ax.work.create","ax.work.update"] } })`,
+  or flip an existing node on with
+  `canvas_node({ action: "update", id, axCapabilities: { enabled: true, allowed: [...] } })`.
+  json-render / graph nodes are enabled by default.
+- **Emit (write):** in `html`, call `window.PMX_AX.emit("ax.work.create", { title })`;
+  in `json-render`, bind a control action named after the AX type
+  (`on: { press: { action: "ax.work.create", params: { title } } }`).
+- **Confirm (#55):** for `html` / `html-primitive` and PMX_AX-enabled `mcp-app`
+  surfaces, `emit` returns a Promise that resolves with the result once the
+  canvas acks it, so a button can self-confirm: `const r = await
+  window.PMX_AX.emit(...); if (r.ok) showQueued();`. You can also
+  `window.PMX_AX.on('ack', cb)` or listen for the `pmx-ax-ack` event. (Falls back
+  to an `ax-ack-timeout` result after 10s, so `await` never hangs.)
+- **Reflect (read):** the canvas seeds the surface with a compact AX snapshot at
+  load (the same shape as `GET /api/canvas/ax/surface-snapshot`) and live-updates it
+  as AX state changes. Works on all three authored surface types:
+  - `html` / `html-primitive`: read `window.PMX_AX.state` (`{ focus, workItems,
+    approvalGates, reviewAnnotations, elicitations, modeRequests, policy }`) and
+    subscribe to the `pmx-ax-update` event:
+    `window.addEventListener("pmx-ax-update", e => render(e.detail))`.
+  - `json-render` / `graph`: the snapshot is bound under `/ax`, so a spec reads
+    `{ "$state": "/ax/workItems" }` and it stays live as work items change.
+  - `web-artifact` (mcp-app): the same `window.PMX_AX.state` + `pmx-ax-update` bridge
+    is injected at the `/artifact` route once the node opts in — author the React app
+    against `window.PMX_AX`, not direct `fetch()` (the artifact iframe is sandboxed
+    opaque-origin, so it can't call the API directly).
+
+Minimal html work board (drop-in via `canvas_node { action: "add", type: "html" }`, `axCapabilities.enabled: true`):
+
+```html
+<button id="add">+ Task</button> <span id="ok"></span>
+<ul id="q"></ul>
+<script>
+  function render(s){ document.getElementById('q').innerHTML =
+    ((s&&s.workItems)||[]).map(w => '<li>['+w.status+'] '+w.title+'</li>').join(''); }
+  document.getElementById('add').onclick = async () => {
+    const r = await window.PMX_AX.emit('ax.work.create',{title:'New task'});
+    document.getElementById('ok').textContent = r && r.ok ? 'queued ✓' : 'failed';   // #55 self-confirm
+  };
+  render(window.PMX_AX && window.PMX_AX.state);
+  window.addEventListener('pmx-ax-update', e => render(e.detail));
+</script>
+```
+
+This is the right home for a deliberate, interactive AX experience — not the
+native node buttons. Any agent (via MCP/SDK) can also create/update the same work
+items, and the board reflects them live.
+
+> **Authoring an AX HTML node? Use the blessed, copy-paste-safe recipe in
+> [`ax-html-control-surface.md`](ax-html-control-surface.md)**
+> and avoid the common footguns:
+> - **The iframe is sandboxed opaque-origin** (no `allow-same-origin`): `localStorage`,
+>   `sessionStorage`, and cookies **throw** and will halt your startup script, making the
+>   node look inert. Keep state in plain JS variables / `window.PMX_AX.state`, or wrap any
+>   storage access in `try/catch`.
+> - **`window.PMX_AX.emit` is async — `await` it** (or use `.then`/`window.PMX_AX.on('ack')`);
+>   don't read a result synchronously. It's injected only when the node is opted in
+>   (`axCapabilities.enabled = true`).
+> - **`ax.steer` is recorded, not delivered** — a successful emit means the steer is
+>   *queued for the agent's next turn*, not that the agent woke (see "Steering is gated").
+>   Label steering buttons accordingly.
+
+> Security note: an AX-enabled surface can READ the whole canvas AX board (all
+> work items, focus, approval gates, etc. — human review comment text is redacted),
+> while its EMITS are clamped to its own node. Under the single-workspace
+> local-trust model this is fine, but don't embed untrusted third-party scripts in
+> an AX-enabled surface.
+
+### Reading Spatial Intent
+
+The `canvas://spatial-context` resource reveals how the human has organized information:
+
+- **Proximity clusters** — Nodes placed near each other form implicit groups. If the human
+  placed three files next to each other, those files are related in their mental model.
+- **Reading order** — Nodes sorted top-left to bottom-right, following natural reading flow.
+  This implies sequence or priority.
+- **Pinned neighborhoods** — For each pinned node, nearby unpinned nodes are listed. These
+  are the human's implicit context — things they consider related to what they pinned.
+- **Annotations** — Shared markup is summarized by ID, label, text, target and bounds, e.g. an
+  annotation over a node or empty canvas region. Use WebView (`canvas_webview { action: "start" }` +
+  `canvas_webview { action: "evaluate" }`/`canvas_screenshot`) when you need to see whether the mark is an
+  arrow, line, circle, or other drawn shape. Remove known annotations with
+  `canvas_view { action: "remove-annotation" }`; otherwise use WebView to identify the mark first.
+- **Board density matters** — On a dense board, spatial context can still read like one large
+  gallery unless groups and spacing separate the major regions clearly.
+
+Use this spatial intelligence to understand what the human is thinking without them having to
+explain it explicitly.
+
+## HTTP API Reference
+
+All POST/PATCH endpoints accept `Content-Type: application/json`. Default base URL: `http://localhost:4313`
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/api/canvas/state` | Full canvas state |
+| POST | `/api/canvas/node` | Add node |
+| PATCH | `/api/canvas/node/<id>` | Update node |
+| DELETE | `/api/canvas/node/<id>` | Remove node |
+| POST | `/api/canvas/edge` | Add edge |
+| DELETE | `/api/canvas/edge` | Remove edge (`{ "edge_id": "..." }`) |
+| GET | `/api/canvas/snapshots` | List snapshots |
+| POST | `/api/canvas/snapshots` | Save snapshot |
+| POST | `/api/canvas/snapshots/<id>` | Restore snapshot |
+| DELETE | `/api/canvas/snapshots/<id>` | Delete snapshot |
+| POST | `/api/canvas/context-pins` | Set, add or remove pinned nodes (20 live pins; removal IDs are not capped) |
+| GET | `/api/canvas/pinned-context` | Get current pins with neighborhood context |
+| GET | `/api/canvas/search?q=...` | Search nodes |
+| POST | `/api/canvas/json-render` | Create a native json-render node |
+| POST | `/api/canvas/json-render/stream` | Create/append a streaming json-render node (SpecStream patches) |
+| POST | `/api/canvas/graph` | Create a native graph node |
+| GET | `/api/canvas/schema` | Get running-server create schemas, examples, and json-render catalog metadata |
+| POST | `/api/canvas/schema/validate` | Validate a json-render spec or graph payload without creating a node |
+| GET | `/api/canvas/json-render/view?nodeId=...` | View a native json-render or graph node |
+| POST | `/api/canvas/diagram` | Create an Excalidraw external app node |
+| POST | `/api/canvas/mcp-app/open` | Open a tool-backed MCP app node |
+| POST | `/api/canvas/web-artifact` | Build a bundled web artifact and optionally open it on canvas |
+| POST | `/api/canvas/group` | Create group |
+| POST | `/api/canvas/group/add` | Add nodes to group |
+| POST | `/api/canvas/group/ungroup` | Ungroup (dissolve: children released, frame removed) |
+| POST | `/api/canvas/arrange` | Auto-arrange |
+| POST | `/api/canvas/focus` | Center viewport on node |
+| POST | `/api/canvas/fit` | Fit viewport to canvas bounds or selected nodes |
+| POST | `/api/canvas/clear` | Clear canvas |
+| POST | `/api/canvas/update` | Batch update positions |
+| GET | `/api/canvas/spatial-context` | Spatial clusters and reading order |
+| POST | `/api/canvas/undo` | Undo |
+| POST | `/api/canvas/redo` | Redo |
+| GET | `/api/canvas/history` | Mutation history |
+| GET | `/api/canvas/code-graph` | File dependency graph |
+| GET | `/api/canvas/memory-graph` | Summary-only board/card projection; optional focus and depth |
+| GET | `/api/workbench/events` | SSE event stream |
+
+## 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
+collaboration pattern:
+
+1. Read `canvas://pinned-context` — get the content of pinned nodes and their neighborhoods
+2. Read `canvas://spatial-context` — understand how the whole canvas is organized
+3. Optionally read `canvas://summary` — see pinned nodes in the context of the full canvas
+4. Interpret what you find:
+   - What types are the pinned nodes? (files = code focus, status = progress, markdown = concepts)
+   - Are they clustered together (single focus) or spread across the canvas (multi-topic)?
+   - What unpinned nodes are nearby? These are the human's implicit context
+   - What's the reading order? Top-left to bottom-right suggests sequence or priority
+   - If an `mcp-app` node is pinned, treat it as “important but partially opaque” and use nearby
+     graph/file/markdown nodes to recover the missing semantic detail
+5. Respond by summarizing what you see, what you think the human is focusing on, and ask
+   if they'd like you to act on it (add related nodes, investigate further, etc.)
+
+**When to use `pinned-context` vs `spatial-context`:**
+- `canvas://pinned-context` — "what did the human explicitly pin, and what's near those pins?"
+- `canvas://spatial-context` — "how is the entire canvas organized spatially?"
+- Read both when you need the full picture; read just `pinned-context` for quick pin checks.
+
+### Investigation Board
+
+When debugging, lay out evidence spatially to see connections:
+
+1. Create a root node describing the bug/issue
+2. Add evidence nodes: logs, stack traces, relevant code files (use `file` nodes for source)
+3. Connect evidence to root with `references` edges
+4. Add a hypothesis node, connect with `flow` edge
+5. As you investigate, add findings and update connections
+6. Use `status` nodes to track what you've checked
+7. Group evidence nodes together, and investigation tasks together
+8. Arrange with `flow` layout, then fine-tune positions if needed
+
+```
+Bug Report ──references──> Error Logs
+    │                         │
+    │                    references
+    │                         ▼
+    └──flow──> Hypothesis ──flow──> Fix
+                                     │
+                                   flow
+                                     ▼
+                               Verification
+```
+
+### Architecture Diagram
+
+Show system components and how they interact:
+
+1. Create `markdown` nodes for each service/component (include port, tech stack in content)
+2. Use `flow` edges for data flow, `depends-on` for dependencies — always label edges
+3. Group related services with `canvas_group { action: "create" }` (e.g., "Application Services", "Data Layer")
+4. Use colors: green for healthy, yellow for degraded, red for down
+5. Arrange with `grid` layout initially
+6. For tiered architectures, fine-tune with explicit `x`/`y` via `canvas_node { action: "update" }` to show
+   layers (e.g., gateway at top, services in middle, data stores at bottom)
+7. Connect pipeline stages with `flow` edges where applicable
+
+### Task Plan with Dependencies
+
+Show useful work deliberately, not a card per task or event. Ordinary work cards are authored
+node data, not AX work items. They require no session and create no approval or execution.
+
+1. Create a `status` node with `data.workState`: `todo`, `in-progress`, `blocked`, `done` or
+   `cancelled`. Use string `data.detail` for context and optional `data.progress` from 0 to 100.
+   Progress is independent of state: Done does not imply 100%; `null` clears progress.
+2. Update the same card through `canvas_node { action: "update", id, data: { ... } }`.
+   Include `expectedBoardId` and `expectedContentRevision` when an edit depends on a prior read.
+3. Connect steps, dependencies, alternatives and intentional loops with existing relations.
+   A drawn loop does not execute. Group distinct phases when useful, then inspect readability.
+4. Humans use **New work card** from the background menu and **Edit/Save/Cancel** inside the card.
+   Drafts and pending/refused saves survive focus-mode open/close, but not a page reload.
+   The editor's temporary growth does not resize the saved card.
+
+MCP creation:
+
+```json
+{"action":"add","type":"status","title":"Verify","data":{"workState":"todo","detail":"Run browser checks"}}
+```
+
+CLI creation uses structured batch data, not `node add --data` (that flag is for graph series):
+
+```bash
+pmx-canvas batch --json '[{"op":"node.add","args":{"type":"status","title":"Verify","data":{"workState":"todo","detail":"Run browser checks"}}}]'
+```
+
+Without `data.workState`, status cards retain their phase/tool display. Session-task linking
+is not provided by these authored cards. Questions can be drawn or written beside the plan;
+the human can answer in the external agent host's composer, without a PMX reply card.
+
+### Live task cards
+
+A live card presents an existing AX work item; it is not another task or an authored
+work plan. Read the task first with `canvas_ax_work { action: "list" }` on its owning
+board, then create a `status` presentation using that task's actual ID:
+
+```json
+{"action":"add","type":"status","data":{"workItemId":"<existing-task-id>"}}
+```
+
+The owner defaults to the current board. To present a task from another board, supply
+its explicit `data.workItemBoardId` too. Both task ID and owner are fixed at creation;
+moving the card does not transfer the task. Create through the current board owner
+(or the Amp plugin's bound board), not `destinationBoardId` background creation.
+
+Omit `title`, `content`, `workState`, `detail`, `progress`, `axWorkStatus`,
+`liveWorkAvailable` and `liveWorkSource` from creation and updates, including nested
+data fields. The server derives title, detail, status and source from the task; these
+are read-only display fields. Update the underlying work item on its owning board with
+`canvas_ax_work { action: "update", id: "<existing-task-id>", status: "in-progress" }`.
+Position and size still belong to the card. Deleting the presentation does not cancel
+or delete the task. If the task is unavailable, the card displays that fact rather than
+becoming an editable authored card. To change the binding, create a new presentation.
+
+### Code Exploration
+
+Understand a codebase by visualizing file relationships:
+
+1. Add `file` nodes for key source files (content auto-loads and live-updates)
+2. The code graph auto-detects imports and creates `depends-on` edges automatically — you
+   don't need to manually add import-based edges. You can still add manual edges for
+   conceptual relationships beyond imports (e.g., "middleware validates using jwt")
+3. Read `canvas://code-graph` for dependency analysis: central files, isolated files
+4. Group related files with `canvas_group { action: "create" }` (e.g., "Auth Module", "API Routes")
+5. Pin important files so the human sees them highlighted
+6. Arrange with `grid` layout after adding files
+
+### Interactive Artifact Builds
+
+When the user wants a real browser app instead of static notes:
+
+1. Use the `web-artifacts-builder` skill if the UI needs React state, routing, or shadcn-style components
+2. Build with `canvas_app { action: "build-artifact" }`
+3. Keep `openInCanvas` enabled unless the user explicitly wants only the output file
+4. Use the returned `projectPath` as the reusable source workspace for iterations
+5. Use the returned `path` for sharing or for opening the generated artifact outside the canvas
+6. Use the `playwright-cli` skill if you need to verify the artifact route or embedded app behavior in a browser
+
+### Status Dashboard
+
+Monitor ongoing processes:
+
+1. Create `status` nodes for each metric/process
+2. Use semantic colors: green=passing, yellow=running, red=failing, gray=queued
+3. Connect sequential pipeline stages with `flow` edges (label: "then", "triggers")
+4. Update nodes in-place as state changes using `canvas_node { action: "update" }` — never delete
+   and recreate, as that loses position and edges
+5. Arrange with `grid` layout
+6. The human sees real-time updates via SSE
+
+### Before/After Comparison
+
+Show two states side by side for the human to compare:
+
+1. Take a snapshot before changes: `canvas_snapshot { action: "save" }` with name "before-X"
+2. Make changes to the canvas
+3. Use `canvas_snapshot { action: "diff", snapshot }` to show what changed
+4. Or: create two groups ("Before" and "After") with corresponding nodes
+
+### Save and Start Fresh
+
+When the human wants to explore a different approach without losing current work:
+
+1. **First**, save the current state: `canvas_snapshot { action: "save" }` with a descriptive name
+2. **Then** clear: `canvas_view { action: "clear" }` (never clear without snapshotting first)
+3. Set up the new workspace with initial nodes
+4. Tell the human the snapshot name and that `canvas_snapshot { action: "restore" }` can bring everything back
+
+## Best Practices
+
+1. **Start once, reuse always.** Don't restart the canvas for each task. Build on the
+   existing canvas state.
+
+2. **Titles are scannable.** Keep titles short (3-6 words). Put details in content.
+
+3. **Label every edge.** Unlabeled edges lose meaning. "depends on", "calls", "blocks"
+   are all more useful than a bare arrow.
+
+4. **Auto-arrange after batch adds.** When adding multiple nodes, call
+   `canvas_view { action: "arrange" }` once at the end, not after each node.
+
+5. **Update in place.** Use `canvas_node { action: "update" }` to change status, content, or
+   color. Don't delete and recreate — that loses position and edges.
+
+6. **Clean up.** Remove nodes that are no longer relevant. A cluttered canvas is worse
+   than no canvas.
+
+7. **Read before writing.** Check `canvas://layout` or `canvas_query { action: "layout" }` before
+   adding nodes to avoid duplicates and understand the current state.
+
+8. **Use pinning.** When you want the human to focus on specific nodes, pin them.
+   When the human pins nodes, read `canvas://pinned-context` to see what they care about.
+   Prefer one intent-setting markdown pin plus a small set of concrete output pins over pinning a
+   whole gallery.
+
+9. **Snapshot before destructive changes.** Before clearing or major reorganization,
+   save a snapshot so you can restore if needed.
+
+10. **Prefer MCP tools over HTTP.** When running as an MCP server, use the canvas tools
+    directly rather than shelling out to curl. The tools handle all the details.
+
+11. **Use groups for visual organization.** When 3+ nodes are related, wrap them in a
+    group to make the relationship visible at a glance.
+
+12. **Use file nodes for source code.** File nodes auto-watch for changes and update
+    live. This is better than pasting code into markdown nodes.
+
+13. **Comparison boards need structure, not just content.** For galleries and evaluations, use a
+    named group, give the area breathing room, and keep related charts/artifacts inside that
+    region instead of letting them drift into the main cluster.
+
+14. **Capture external app IDs immediately.** For Excalidraw and other `mcp-app` nodes, store the
+    returned node ID or pin the node right away. Search/title rediscovery is less reliable there
+    than for markdown, graph, or file nodes.
+
+15. **Pair app nodes with explainers.** If you create or pin a web artifact or Excalidraw node,
+    add a nearby markdown, graph, or file node that explains what the app is for. This makes
+    pinned context far more useful to later agents.
+
+## Persistence
+
+Canvas state auto-saves to `.pmx-canvas/canvas.db` on every mutation (debounced 500ms). State
+loads automatically on server start. The SQLite DB is git-committable — spatial knowledge
+persists across sessions.
+
+Snapshots, context pins, and large node blobs are stored in the same DB. Web artifacts land in
+`.pmx-canvas/artifacts/`. Legacy JSON state, snapshot, and blob files are auto-imported into
+SQLite and renamed to `.bak` on first boot.
+
+Stop the server or flush/close the SDK before committing `canvas.db`; shutdown checkpoints SQLite
+WAL data into the DB file.
+
+Board-owned original attachments are stored in that database until board deletion, survive
+snapshot restore, and therefore travel with database backups. Agent import reads return a
+controlled HTTP path and can include inline base64 only for sources at or below 2 MiB. A remote
+host may need manual transfer. Canvas bundles no converter or OCR and launches no agent
+automatically; a human explicitly requests processing, reviews draft sections/references/warnings,
+and commits only while the captured source board is active. Static export v1 never contains
+original bytes; `includeDerivedText` controls source-linked Markdown separately from
+`includeFiles`, including after that Markdown is edited.
+
+## Real-Time Collaboration
+
+The canvas supports real-time human-agent collaboration:
+
+- **Human pins nodes in browser** → agent reads `canvas://pinned-context`
+- **Agent adds/updates nodes** → human sees changes instantly via SSE
+- **Human moves/groups nodes** → spatial arrangement communicates intent
+- **Agent reads spatial context** → understands implicit relationships
+
+This bidirectional flow means the canvas is a shared workspace, not just an output display.
+Pay attention to what the human is doing on the canvas — their spatial choices are meaningful.