pmx-canvas 0.1.4 → 0.1.6

package/Readme.md

@@ -1,6 +1,10 @@
 # pmx-canvas
 
-A spatial canvas workbench for coding agents. Infinite 2D canvas with nodes, edges, pan/zoom, minimap, and real-time sync -- controlled through the CLI, MCP, HTTP API, or a Bun-based JavaScript/TypeScript SDK.
+**A shared thinking surface for humans and coding agents.** Drop files, plans,
+status, charts, fetched web pages, and hand-drawn diagrams onto the same
+infinite 2D canvas; pin what matters; let the agent read your spatial curation
+as structured context. Drive it from a CLI, the Model Context Protocol, an
+HTTP API, or a Bun-based TypeScript SDK — whichever fits how your agent runs.
 
 <p align="center">
   <img src="docs/screenshots/welcome-dark.png" alt="Empty canvas — dark theme" width="49%" />
@@ -12,9 +16,35 @@ A spatial canvas workbench for coding agents. Infinite 2D canvas with nodes, edg
   <img src="docs/screenshots/demo-workbench-light.png" alt="Structured workbench demo — light theme" width="49%" />
 </p>
 
-PMX Canvas is a spatial thinking surface for coding agents and the humans working with them. Agents lay out plans, files, and status as connected nodes; humans rearrange, group, and pin what matters. That spatial curation — proximity, grouping, pinning — becomes structured context the agent reads in real time via MCP.
+PMX Canvas is a **collaborative spatial workspace** that humans and agents share in real time. It works in both directions:
 
-**Spatial arrangement is communication.** When a human drags three file nodes next to a bug report, the agent knows they're related. The canvas is the agent's **extended working memory**: humans pin nodes to curate context, agents read that curation via `canvas://pinned-context` and MCP resource change notifications.
+- **Human-first.** You open the canvas, drop in files, sketch a plan, group what belongs together, pin what matters. The agent watches the curation update live and uses it to ground its next action — no prompt engineering, no copy-paste.
+- **Agent-first.** You ask the agent to gather data from sources (logs, files, search results, dashboards, web pages), and it lays the findings out as nodes and edges. You step in, rearrange, edit, prune, and steer where the analysis goes next.
+
+### What it's for
+
+pmx-canvas drives any work that benefits from making **context, relations, and provenance explicit**. The canvas turns work that is normally scattered across chat history, tabs, files, and dashboards into something with explicit context (pinned nodes), explicit relations (edges, groups, proximity), and explicit provenance (which side added which piece). Whatever data either the human or the agent pulls in — files, fetched web pages, screenshots, log excerpts, structured panels, charts, hand-drawn diagrams, bundled web artifacts — lives on the same surface and is reachable from both sides.
+
+**The canvas is agnostic about what you do with it.** The reach of the workspace is the union of pmx-canvas's own node types and **whatever your agent's harness already has access to** — MCP servers, MCP apps, shell commands and CLIs, files in the working directory, web-fetch tools, anything else its toolbelt exposes. The canvas itself doesn't care where the data came from; it just needs the agent (or you) to drop it on the surface as the right node type. To make that concrete:
+
+- A **Jira MCP** turns the canvas into a triage board — tickets land as `markdown` nodes you can group by status and pin the in-flight ones.
+- A **database MCP** turns it into an exploratory query workbench — each query result becomes a `json-render` table or `graph` node next to the `markdown` node holding the SQL.
+- An **Excalidraw MCP app** turns it into a sketch surface — diagrams open as `mcp-app` nodes you can resize and annotate.
+- A **shell-driven agent** with `gh` + `kubectl` in its harness turns it into an ops board — open issues become markdown, pod statuses become `status` nodes, the relationships you care about become edges.
+- **Plain file reads** in the agent's working directory turn it into a code-context map — `file` nodes for source, `markdown` nodes for the agent's notes, all live-watched.
+- A **custom MCP or CLI** for your data source turns it into whatever shape that data fits — without pmx-canvas knowing anything about your domain.
+
+Common use cases — non-exhaustive, mix and match as the work shifts:
+
+- **Idea generation** — capture divergent thoughts spatially without losing them
+- **Validation** — test a claim against supporting and refuting evidence
+- **Research** — gather, organize, and compare sources from anywhere
+- **Analysis** — make sense of accumulated material, surface patterns
+- **Mind mapping** — relationships, hierarchies, and structure spatially
+
+…plus anything else the combination of the canvas and your agent's toolbelt — MCP servers, MCP apps, CLIs, file access, web fetch — makes possible.
+
+**Spatial arrangement is communication.** When a human drags three file nodes next to a bug report, the agent knows they're related. When the agent drops 12 webpage nodes from a research session, the human can immediately group, prune, and pin the ones worth keeping. The agent reads spatial state via `canvas://pinned-context`, `canvas://spatial-context`, and the SSE event stream; the human reads the same state through the rendered browser.
 
 ## Prerequisites
 
@@ -22,18 +52,113 @@ PMX Canvas is a spatial thinking surface for coding agents and the humans workin
 
 The published SDK entrypoint is Bun-first: `import { createCanvas } from 'pmx-canvas'` is supported in Bun, while Node.js consumers should use the CLI, MCP server, or HTTP API instead.
 
+## Scope
+
+- **Single-machine, today.** One canvas runs per `bunx pmx-canvas` instance, on
+  one machine. There is no built-in multi-user auth or presence — collaboration
+  means human↔agent on the same machine, plus any other browser tab/agent
+  pointed at the same `localhost:4313`. To share a canvas across machines, commit
+  `.pmx-canvas/state.json` to your repo and pull it on the other side.
+- **What leaves your machine.** The core canvas runs entirely on `localhost`.
+  Network egress only happens for explicit, opt-in flows: `webpage` nodes
+  fetch the URL you give them; `mcp-app` / `canvas_add_diagram` calls go to
+  whatever MCP server URL you configure (the Excalidraw preset uses
+  `https://mcp.excalidraw.com/mcp`); `bunx` itself reads the npm registry on
+  first install. Nothing else phones home.
+- **State auto-saves** to `.pmx-canvas/state.json` (debounced ~500 ms after each
+  mutation). Closing the browser tab keeps everything — only `Ctrl-C` (or
+  `pmx-canvas serve stop`) on the server actually stops the canvas. Pins,
+  positions, and node content survive both. Snapshots live under
+  `.pmx-canvas/snapshots/`.
+
 ## Quick start
 
-### Install from npm
+There are two paths into pmx-canvas, and they work together. Pick whichever
+matches who is starting the session — you can hand off to the other side at any
+point because both halves drive the same canvas.
+
+### Easiest: install the `pmx-canvas` agent skill (recommended)
+
+The fastest way to get going is to install the main `pmx-canvas` agent skill
+into your agent of choice. The skill teaches the agent how to install the
+package, start the server, and drive every node type, group, snapshot, and
+search the canvas exposes. You don't have to install the rest of the bundled
+skills (`web-artifacts-builder`, `pmx-canvas-testing`, `playwright-cli`, the
+`json-render-*` family, etc.) — once the canvas is running, the agent can read
+`canvas://skills` and pull in companion skills as the work demands.
+
+Three install paths, in order of how universal they are:
+
+```bash
+# 1. GitHub CLI extension. `gh skill` is the official Agent Skills extension
+#    for the GitHub CLI — it knows where each harness keeps its skills tree
+#    and copies the SKILL.md and assets into the right place. Requires
+#    `gh` >= 2.90. See https://cli.github.com/manual/gh_skill_install.
+gh skill install pskoett/pmx-canvas pmx-canvas
+
+# 2. Agent Skills CLI. `npx skills` is the runtime-agnostic installer for
+#    skills that follow the Agent Skills specification
+#    (https://agentskills.io/specification). It works for any agent harness
+#    that reads from a per-user or per-project skills directory.
+npx skills add pskoett/pmx-canvas/skills/pmx-canvas
+
+# 3. Manual clone + copy. Works everywhere; you pick where the skill lands.
+git clone https://github.com/pskoett/pmx-canvas.git
+cp -r pmx-canvas/skills/pmx-canvas <your-agent-skills-dir>
+```
+
+For path 3, point at whichever directory your agent harness reads. Common
+defaults — check your harness docs if it isn't here:
+
+| Harness | Skills directory |
+|---------|------------------|
+| Claude Code | `.claude/skills/` (project) or `~/.claude/skills/` (user-wide) |
+| GitHub Copilot CLI | `.github/skills/`, `.claude/skills/`, or `.agents/skills/` (project); `~/.copilot/skills/`, `~/.claude/skills/`, or `~/.agents/skills/` (user-wide). [docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills) |
+| Cross-harness convention | `.agents/skills/` (project) — followed by an increasing number of harnesses, see the [Agent Skills specification](https://agentskills.io/specification) |
+| Other / unsure | check your harness's docs for the canonical skills directory |
+
+After install, point your agent at the skill and try the **minimum-viable
+prompt**:
+
+> *"Use the `pmx-canvas` skill to start the canvas, then add this repo's
+> `Readme.md` and the top three source files as `file` nodes. Auto-arrange
+> them and pin two."*
+
+You should see the browser open and four nodes appear inside ~10 seconds. If
+that works, the skill, the canvas, and the agent are all wired up.
+
+If your agent isn't MCP-capable yet, wire it up first — see
+[Connect your agent (MCP)](#connect-your-agent-mcp) for the JSON snippet that
+turns `bunx pmx-canvas --mcp` into a stdio MCP server your harness can connect
+to. The skill assumes the agent can call MCP tools. From there
+work up to richer prompts — the [Example](#example-pull-data-in-build-something-out)
+section below has a fuller flow.
+
+For a richer install (the full bundle as a plugin marketplace, mirroring the
+pattern in [`pskoett-ai-skills`](https://github.com/pskoett/pskoett-ai-skills)),
+see [Agent skills](#agent-skills) below.
+
+### Run it directly (no agent required)
+
+You don't need an agent to use pmx-canvas — the workbench, CLI, and HTTP API
+are first-class on their own.
+
+#### Install from npm
 
 ```bash
 bunx pmx-canvas              # Start canvas, open browser
-bunx pmx-canvas serve --daemon --no-open --wait-ms=20000
 bunx pmx-canvas --demo       # Start with sample nodes
-bunx pmx-canvas --mcp        # Run as MCP server
+bunx pmx-canvas --no-open    # Headless (good for daemons / CI)
+bunx pmx-canvas --mcp        # Run as MCP server (stdio)
+bunx pmx-canvas --help       # All commands
+bunx pmx-canvas serve --daemon --no-open --wait-ms=20000  # Detached background mode
 ```
 
-### Install from source
+The canvas opens at `http://localhost:4313`. Try `bunx pmx-canvas --demo`
+first — you'll see three nodes connected by two edges; that confirms the
+canvas server, the browser bundle, and the SSE event stream are all wired up.
+
+#### Install from source
 
 ```bash
 git clone https://github.com/pskoett/pmx-canvas.git
@@ -42,26 +167,20 @@ bun install
 bun run build
 bun run dev                   # Start + open browser
 bun run dev:demo              # Start with sample nodes
-bun run dev:portless          # Start at https://pmx.localhost/workbench (requires global portless)
 ```
 
-The canvas opens at `http://localhost:4313`.
-
-For local development only, you can give the canvas a stable hostname with
-[Portless](https://github.com/vercel-labs/portless):
+For a stable local hostname, install [Portless](https://github.com/vercel-labs/portless)
+first **and then** run the portless variant:
 
 ```bash
 npm install -g portless
-bun run dev:portless
+bun run dev:portless          # https://pmx.localhost/workbench
 ```
 
-Then open `https://pmx.localhost/workbench`.
-
-This is intentionally a repo-local developer workflow. The published
-`bunx pmx-canvas` path still defaults to plain loopback and does not depend on
-Portless being installed.
+The published `bunx pmx-canvas` path defaults to plain loopback and does **not**
+depend on Portless.
 
-### Test the unpublished CLI from a repo checkout
+#### Test the unpublished CLI from a repo checkout
 
 If you want to exercise the real package before publishing, link the repo locally:
 
@@ -81,10 +200,17 @@ For one-off local runs without linking, `bun run src/cli/index.ts ...` works too
 
 ### Recommended ways to drive the canvas
 
-- **CLI** for local use, scripting, automation, and terminal-native agents
-- **MCP** for agents that already speak the Model Context Protocol
+Once the canvas is up, two control surfaces are first-class:
 
-### Connect your agent (MCP)
+- **CLI** for local use, scripting, automation, and terminal-native agents.
+- **MCP** for agents that already speak the Model Context Protocol — 38 tools +
+  8 resources, including the bundled-skill index at `canvas://skills`.
+
+Both paths cover core canvas work. A few advanced capabilities (live resource
+subscriptions, `canvas_diff`) remain MCP-only. The HTTP API and the
+[Bun SDK](#javascripttypescript-sdk-bun-runtime) are also available for programmatic use.
+
+#### Connect your agent (MCP)
 
 Add to your agent's MCP config:
 
@@ -99,17 +225,99 @@ Add to your agent's MCP config:
 }
 ```
 
-The canvas auto-starts on first tool call. Works with Claude Code, Cursor, Windsurf, and any MCP-capable agent.
+The canvas auto-starts on first tool call. Works with any MCP-capable agent
+harness — pmx-canvas does not depend on a specific coding agent.
+
+For developer flows on the `pmx-canvas` repo itself (release process,
+contribution gates, etc.) see [`AGENTS.md`](AGENTS.md) and
+[`docs/RELEASE.md`](docs/RELEASE.md).
+
+## Example: pull data in, build something out
+
+The canvas is most useful when it's *not* empty. The pattern is the same
+across every use case: gather data from whatever surfaces the human or the
+agent has access to, lay it out using whichever node types fit, then
+collaborate on the result.
+
+A research / analysis example against a release-planning workflow:
+
+> *"Read the latest release notes from `CHANGELOG.md`, the open issues from
+> our GitHub repo, last week's deploy logs, and the pricing page from
+> example.com. Put each one on the canvas as the right node type — markdown
+> for the changelog, file nodes for the local files, status nodes for the
+> deploy events, a webpage node for the URL — then build me a json-render
+> dashboard and a chart that summarize what shipped, what broke, and what's
+> still open."*
+
+The same shape works for any use case. *Idea generation:* "give me twelve
+angles on X, drop each as a markdown node, arrange in a flow layout."
+*Validation:* "for the claim in the pinned node, place supporting and
+refuting sources beside it as webpage and file nodes." *Mind mapping:*
+"build a tree of the concepts in [topic] — central concept top-center,
+major branches as groups, sub-concepts inside each group connected with
+depends-on edges."
+
+[`skills/pmx-canvas/SKILL.md`](skills/pmx-canvas/SKILL.md) has step-by-step
+recipes for these and other patterns under *Workflow Patterns*. New
+patterns become viable whenever you add an MCP server or MCP app — the
+canvas surface stays the same, the things you can put on it grow.
+
+What the agent does, end to end:
+
+1. Reads each source via the tools your harness already provides (filesystem,
+   web fetch, GitHub API, log readers — pmx-canvas does not impose data
+   sources; bring your own).
+2. Calls the canvas to drop each finding on the workbench:
+   - `markdown` for narrative notes and AI-summarized text
+   - `file` for live-watching local source files
+   - `webpage` for fetched web pages with cached extracted text
+   - `image` for screenshots and exported diagrams
+   - `status` / `ledger` / `trace` for structured runtime/evaluation state
+   - `json-render` for inline structured UI (dashboards, tables, forms) — see
+     [Json-render nodes](#json-render-nodes)
+   - `graph` for line / bar / pie / radar / stacked / composed charts — see
+     [the schema reference](#schema-driven-discovery)
+   - `mcp-app` (Excalidraw and other MCP App servers) for hand-drawn diagrams
+   - `web-artifact` for full bundled React/Tailwind interactive surfaces — see
+     [Web artifacts](#web-artifacts)
+   - `group` to bound related nodes into a frame
+   - `edge` to connect findings (`flow`, `depends-on`, `relation`,
+     `references`) so the relationships are first-class, not implicit
+3. You step into the canvas, rearrange, prune, group, and **pin** the nodes
+   that matter.
+4. The agent reads `canvas://pinned-context` and `canvas://spatial-context`
+   and uses your curation to ground the next round of analysis or build.
+
+This loop works for investigations, architecture sketches, research surveys,
+release planning, dashboards, post-mortems, lecture notes — anywhere the gap
+between "I have the data somewhere" and "I have a coherent picture" is
+currently blocking your thinking.
 
 ## How it works
 
-1. Agent creates nodes on the canvas (plans, code, status, investigations)
-2. Agent adds file nodes for the files it's working on -- they update live as the agent edits
-3. Human reviews, rearranges, and **pins** the important nodes
-4. MCP server notifies the agent that pinned context changed
-5. Agent reads `canvas://pinned-context` to get the human's curated focus
-6. Agent uses that context to inform its next actions
-7. The canvas becomes a shared thinking surface
+The same simple loop runs in both directions, regardless of what the work
+actually is:
+
+1. **Either side adds material** to the canvas. The agent uses any tool its
+   harness exposes (file reads, web fetch, an attached MCP server, an MCP
+   app, the canvas's own tools) and lays the result out as the right node
+   type. The human drops files, drags nodes around, types markdown.
+2. **The human curates spatial structure** — they group, position, draw
+   edges, and pin what matters. Curation is communication: proximity means
+   relatedness, pinning means "agent, focus here."
+3. **The agent reads that structure as machine-readable context.**
+   `canvas://pinned-context` returns the pinned nodes plus their nearby
+   neighbors. `canvas://spatial-context` returns proximity clusters,
+   reading order, and pinned neighborhoods. SSE notifies the agent the
+   moment any of it changes.
+4. **The agent acts on that context** using whatever tools are at its
+   disposal — `bunx pmx-canvas`'s 38 MCP tools, plus every other MCP your
+   harness has connected. Each new MCP expands what the loop can do without
+   changing the loop.
+
+The canvas's job is to keep that loop honest: spatial state stays explicit,
+provenance stays attributable to the side that made it, and both sides see
+the same workspace via different surfaces.
 
 ## Features
 
@@ -255,12 +463,16 @@ canvas_add_json_render_node({
     root: 'card',
     elements: {
       card: { type: 'Card', props: { title: 'Deploy' }, children: ['status'] },
-      status: { type: 'Badge', props: { variant: 'success', label: 'Healthy' } },
+      status: { type: 'Badge', props: { variant: 'default', text: 'Healthy' } },
     },
   },
 });
 ```
 
+`Badge` uses shadcn variants: `default`, `secondary`, `destructive`, and `outline`.
+Older saved specs using `label` or status variants such as `success`/`warning` are
+normalized during validation for compatibility.
+
 Use `canvas_describe_schema` / `canvas_validate_spec` to introspect the component catalog before
 building a spec -- see [Schema-driven discovery](#schema-driven-discovery).
 
@@ -373,6 +585,13 @@ json-render component catalog, and node-type examples so an agent can introspect
 The CLI's `node schema` / `validate spec` subcommands surface the same data from the terminal,
 which is strictly better than guessing flags or payloads.
 
+MCP node creation uses dedicated tools for structured node families. Read
+`mcp.nodeTypeRouting` from `canvas_describe_schema` / `canvas://schema` when in doubt:
+`json-render` -> `canvas_add_json_render_node`, `graph` -> `canvas_add_graph_node`,
+`web-artifact` -> `canvas_build_web_artifact`, `external-app` -> `canvas_open_mcp_app`,
+and `group` -> `canvas_create_group`. Basic nodes such as `markdown`, `status`, `file`,
+`image`, and `webpage` use `canvas_add_node`.
+
 ### Persistence
 
 Canvas state auto-saves to `.pmx-canvas/state.json` in the workspace root on every mutation (debounced). The file is git-committable -- spatial knowledge persists across sessions and can be shared with a team. Everything the canvas generates (state, snapshots, web artifacts, daemon log/pid) is consolidated under `.pmx-canvas/`. Legacy `.pmx-canvas.json` and `.pmx-canvas-snapshots/` are migrated to the new layout automatically on first boot.
@@ -465,18 +684,28 @@ effectively:
 
 | Skill | Purpose |
 |-------|---------|
-| [`pmx-canvas`](skills/pmx-canvas/SKILL.md) | Core canvas workflows -- when to create which node type, how to pin for context, batch builds |
+| [`pmx-canvas`](skills/pmx-canvas/SKILL.md) | **Core canvas workflows** — when to create which node type, how to pin for context, batch builds. Start here. |
+| [`web-artifacts-builder`](skills/web-artifacts-builder/SKILL.md) | Build single-file React/Tailwind artifacts and drop them on the canvas as embedded nodes |
+| [`json-render-core`](skills/json-render-core/SKILL.md) | Drive the `@json-render/core` runtime — the spec format, parsing, and validation |
+| [`json-render-react`](skills/json-render-react/SKILL.md) | Render json-render specs into React using the runtime |
+| [`json-render-shadcn`](skills/json-render-shadcn/SKILL.md) | The shadcn/ui component catalog — Card, Stack, Button, Form fields, Tables |
+| [`json-render-mcp`](skills/json-render-mcp/SKILL.md) | Expose a json-render spec as a `ui://` MCP resource |
+| [`json-render-codegen`](skills/json-render-codegen/SKILL.md) | Generate json-render specs from prompts / structured input |
+| [`json-render-ink`](skills/json-render-ink/SKILL.md) | Render json-render specs to the terminal via Ink |
 | [`pmx-canvas-testing`](skills/pmx-canvas-testing/SKILL.md) | Testing patterns against the running canvas |
-| [`web-artifacts-builder`](skills/web-artifacts-builder/SKILL.md) | Build single-file React/Tailwind artifacts for the canvas |
 | [`playwright-cli`](skills/playwright-cli/SKILL.md) | Browser automation recipes for canvas + arbitrary pages |
-| [`json-render-*`](skills/) | Drive the `@json-render/*` catalog (core, react, shadcn, mcp, codegen, ink) |
 | [`frontend-design`](skills/frontend-design/SKILL.md), [`web-design-guidelines`](skills/web-design-guidelines/SKILL.md) | Design-quality rules for agent-generated UI |
 | [`doc-coauthoring`](skills/doc-coauthoring/SKILL.md) | Structured doc-writing flow |
 | [`data-analysis`](skills/data-analysis/SKILL.md) | Data exploration patterns |
-| [`published-consumer-e2e`](skills/published-consumer-e2e/SKILL.md) | Smoke-test the published `bunx pmx-canvas` path |
 
-Point your agent's skill loader at this directory, or copy the individual `SKILL.md` files into
-your agent's skills tree.
+(`published-consumer-e2e` exists in `skills/` for maintainer use — it smoke-tests the
+published `bunx` path against a clean temp consumer — but it isn't a user-facing skill.)
+
+You only need to install [`pmx-canvas`](skills/pmx-canvas/SKILL.md) up front (see the
+[Quick start](#quick-start)) — once the canvas is running, the agent can read
+`canvas://skills` to discover the rest and pull them in as the work demands. The core skill
+also references the companion skills directly so the agent knows when each one is the right
+tool.
 
 ## Integration
 
@@ -494,7 +723,7 @@ layout validation, graph/json-render nodes, group control, snapshots, and search
 
 ### MCP server
 
-38 tools + 7 resources. Zero config for any MCP-capable agent.
+38 tools + 8 resources. Zero config for any MCP-capable agent.
 
 <details>
 <summary>MCP tools</summary>
@@ -553,7 +782,8 @@ layout validation, graph/json-render nodes, group control, snapshots, and search
 | `canvas://summary` | Compact overview: counts, pinned titles, viewport |
 | `canvas://spatial-context` | Proximity clusters, reading order, pinned neighborhoods |
 | `canvas://history` | Mutation history timeline with undo/redo position |
-| `canvas://code-graph` | Auto-detected file dependency graph |
+| `canvas://code-graph` | Auto-detected file dependency graph (JS/TS, Python, Go, Rust) |
+| `canvas://skills` | Index of bundled agent skills + per-skill content at `canvas://skills/<name>` |
 
 </details>
 
@@ -741,6 +971,7 @@ pmx-canvas node add --help --type webpage --json
 pmx-canvas external-app add --kind excalidraw --title "Diagram"
 pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value
 pmx-canvas node add --type graph --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y
+pmx-canvas graph add --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y  # Alias for graph nodes
 pmx-canvas node schema --type json-render --component Table --summary
 pmx-canvas edge add --from-search "DVT O3 — GitOps" --to-search "deep work trend" --type relation
 pmx-canvas batch --file ./canvas-ops.json
@@ -767,22 +998,68 @@ Use the CLI when you want:
 The CLI create commands return the created node shape with normalized title/content and geometry,
 which makes scripting stacked layouts and batch follow-up operations easier.
 
+For graph nodes, `node add --type graph` is the canonical CLI form. `graph add`
+is a convenience alias that uses the same flags and server endpoint.
+
+Graph height flags are split by target: `--node-height` / `--nodeHeight` control
+the canvas node frame, while `--chart-height` controls the chart content inside
+the node. CLI `--height` is still accepted as a frame-height compatibility alias.
+For MCP/HTTP payloads, use `nodeHeight` for the frame and `height` for chart content.
+
 ## Agent compatibility
 
-| Agent | Integration | Config |
-|-------|-------------|--------|
-| Claude Code | MCP server | `"command": "bunx", "args": ["pmx-canvas", "--mcp"]` |
-| Cursor | MCP server | Same MCP config |
-| Windsurf | MCP server | Same MCP config |
-| OpenAI Codex | MCP or HTTP | Same MCP config, or `curl` commands |
-| Any other | HTTP API | Any language can `fetch()` or `curl` |
+pmx-canvas is harness-agnostic. Any agent that can spawn an MCP stdio server,
+make HTTP requests, or invoke a CLI can drive the canvas.
+
+| Capability | Path | Config |
+|------------|------|--------|
+| MCP-capable agent | MCP stdio server | `"command": "bunx", "args": ["pmx-canvas", "--mcp"]` |
+| Shell-driven agent | CLI | `bunx pmx-canvas …` (see [Recommended ways to drive the canvas](#recommended-ways-to-drive-the-canvas)) |
+| HTTP-only environment | REST + SSE | `fetch()` / `curl` at `http://localhost:4313/api/canvas/...` |
+| Bun runtime | TypeScript SDK | `import { createCanvas } from 'pmx-canvas'` |
+
+## Known limitations
+
+These are real things you'll hit and they aren't your fault — work around
+them rather than chase them as bugs.
+
+- **Single-machine, no built-in multi-user auth.** See
+  [Scope](#scope) above. Sharing a canvas
+  across machines today means committing `.pmx-canvas/state.json`.
+- **Excalidraw / external `mcp-app` flakes:** grouped Excalidraw element IDs
+  can change after edits, so an agent that builds a diagram in two passes
+  should capture every element ID immediately after `canvas_add_diagram`
+  returns. Editing while another tool call is in flight occasionally drops
+  the in-progress edit.
+- **External MCP apps are transport-based over MCP.** `canvas_open_mcp_app`
+  requires `toolName` plus a `transport` object for the external MCP server.
+  For the built-in Excalidraw preset, use `canvas_add_diagram`; the CLI's
+  `external-app add --kind excalidraw` is a higher-level convenience wrapper.
+- **Web-artifact build timeouts on cold installs.** The first
+  `canvas_build_web_artifact` call in a fresh workspace runs `pnpm install`
+  for ~30 dependencies. On constrained machines or slow networks, the
+  default timeout can fire before the install completes — bump
+  `--timeout-ms` (CLI) or `timeoutMs` (MCP/SDK) on first use, or
+  pre-warm with `bunx pmx-canvas web-artifact build --title warmup
+  --app-tsx 'export default () => null'`.
+- **Webpage-fetch failure modes.** Sites that require auth, render purely
+  client-side without server HTML, or block headless fetches will store
+  with empty extracted text. The node still works as a URL bookmark; the
+  agent's view of the content will be the URL only.
+- **Image cloud-on-demand stalls (macOS).** Images stored in iCloud Drive
+  / OneDrive that aren't downloaded locally are detected up-front and
+  rejected with a clear error rather than freezing the server. Download
+  the file locally first.
+- **`prompt` and `response` node types are internal.** They surface in
+  `canvas://layout` for thread rendering but aren't created via the public
+  `canvas_add_node` API.
 
 ## Architecture
 
 ```
-Agent (Claude Code / Codex / Cursor / any MCP client)
+Agent harness (any MCP-capable client, CLI consumer, or HTTP caller)
   |
-  |-- MCP Server ---- 38 tools + 7 resources + change notifications
+  |-- MCP Server ---- 38 tools + 8 resources + change notifications
   |-- Bun SDK ------- createCanvas()
   |-- HTTP API ------ REST + SSE at localhost:4313
   |
@@ -837,26 +1114,6 @@ from the durable eval in [docs/evals/e2e-cli-coverage.md](docs/evals/e2e-cli-cov
 parseable JSON, node creation, graph `--data`, web-artifact failure handling, Excalidraw external
 apps, `focus --no-pan`, arrange/validate, and status subtype reporting.
 
-## Release
-
-Use this sequence before publishing a new version:
-
-```bash
-bun install --frozen-lockfile
-bun run release:check
-bun run test:e2e-cli
-bun run release:smoke
-bun run pack:dry-run
-```
-
-Then publish the version currently in `package.json`:
-
-```bash
-bun publish
-```
-
-If this is the first release from your machine, run `bunx npm login` once so Bun can reuse your npm credentials.
-
 ### Project structure
 
 ```

package/dist/types/server/canvas-schema.d.ts

@@ -12,6 +12,7 @@ export interface CanvasCreateTypeSchema {
     kind: 'node' | 'virtual-node';
     description: string;
     endpoint: string;
+    mcpTool?: string;
     fields: CanvasCreateField[];
     example: Record<string, unknown>;
     notes?: string[];
@@ -39,6 +40,7 @@ export declare function describeCanvasSchema(): {
     mcp: {
         tools: string[];
         resources: string[];
+        nodeTypeRouting: Record<string, string>;
     };
 };
 export declare function validateStructuredCanvasPayload(input: {

package/dist/types/server/image-source.d.ts

@@ -0,0 +1,3 @@
+export declare function validateLocalImageFile(path: string): {
+    mimeType: string;
+};

package/dist/types/server/index.d.ts

@@ -162,6 +162,7 @@ export declare class PmxCanvas extends EventEmitter {
         mcp: {
             tools: string[];
             resources: string[];
+            nodeTypeRouting: Record<string, string>;
         };
     };
     validateSpec(input: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",