pmx-canvas 0.11.0 → 0.12.0

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -0,0 +1,223 @@
+# GitHub Copilot App Adapter
+
+Use this reference when PMX Canvas is running inside the GitHub Copilot app as a project canvas
+extension. The adapter is intentionally thin: PMX Canvas remains the state owner, and the extension
+maps Copilot SDK features onto PMX AX primitives.
+
+The [standalone agent plugin](https://github.com/pskoett/pmx-canvas/blob/main/docs/agent-plugin.md) bundles this adapter and PMX's
+MCP launcher. Its native canvas is Copilot-only; other Agent Plugins-compatible clients use
+the portable MCP tools and browser workbench.
+
+## Adapter Identity
+
+- Extension path: `.github/extensions/pmx-canvas/extension.mjs`
+- Extension ID: `project:pmx-canvas`
+- Canvas ID: `pmx-canvas`
+- Display name: `PMX Canvas`
+
+## Quick Start
+
+1. Install the project adapter with `pmx-canvas copilot install-extension --yes`, or copy the
+   packaged extension directory into the repository:
+   `mkdir -p .github/extensions && cp -R node_modules/pmx-canvas/.github/extensions/pmx-canvas .github/extensions/`
+2. Reload Copilot app extensions with `extensions_reload` so `project:pmx-canvas` is registered.
+3. The adapter discovers a matching workspace daemon or starts the pinned package version
+   in `runtime.json` with Bun. It needs Bun on `PATH`, not a global `pmx-canvas` executable.
+   The shared daemon stays running when the extension exits.
+4. Open the canvas with `extensionId: "project:pmx-canvas"`, `canvasId: "pmx-canvas"`, and a stable
+   `instanceId`.
+5. If the first `invoke_canvas_action` immediately after `open_canvas` returns
+   `Canvas instance not open`, retry the same action once. This is a known Copilot app timing race
+   during panel initialization, not a PMX server failure.
+
+Open it with:
+
+```json
+{
+  "extensionId": "project:pmx-canvas",
+  "canvasId": "pmx-canvas",
+  "instanceId": "pmx-canvas"
+}
+```
+
+Use a different `instanceId` for parallel panels. Reusing an `instanceId` focuses/reloads the same
+panel.
+
+## Agent presence (automatic)
+
+The extension also reports Copilot's real context window: the SDK's `session.usage_info`
+event (`currentTokens` / `tokenLimit`, root agent only) is posted to the presence as
+`contextUsage`, so the board's context panel names how many tokens Copilot's whole context holds,
+next to what the brief costs.
+
+The extension attaches a Copilot session to the canvas when it joins the host session, flips the
+phase to `thinking` on every submitted prompt, and detaches on exit. While attached the workbench
+shows the Copilot cursor on the node the agent last touched plus a phase chip, and the agent's
+canvas writes — which reach the server as MCP or HTTP tool calls, not as `copilot` — are attributed
+to that session by the server. Nothing to configure; `GET /api/canvas/ax/presence` shows the live
+state.
+
+Read presence before starting board work. Reuse the extension's `copilot` session and
+steering consumer; do not attach a second session such as “Copilot – team overview” with
+a new source or `agentId`. Send task names as `detail` on `source: "copilot"`, preserving
+the host's identity and polling route. The adapter owns attach/detach; the agent must not
+end it after each task. Explicit agent IDs are reserved for genuinely independent subagents.
+
+## What the Adapter Does
+
+- Opens the live PMX workbench directly in a native Copilot canvas panel.
+- Uses PMX-served same-origin frame documents for iframe-backed nodes (`html` and hosted MCP apps).
+  The Copilot app webview can leave nested `srcdoc` and `blob:` iframes blank, so PMX should route
+  generated frame HTML through `/api/canvas/frame-documents/...` instead.
+- Connects to a matching local PMX server for the current workspace, or starts one when needed.
+- Uses the session's working directory for startup, context, presence, and steering; Copilot's
+  `workspacePath` points to session artifacts and is not the project root.
+- Reads `/api/canvas/ax/context` and injects pinned/focused context from
+  `onUserPromptSubmitted`.
+- Exposes adapter actions for status, AX context refresh, AX focus, and explicit session steering.
+
+### Agent behavior — steering push with a gated fallback
+
+The adapter long-polls the consumer-scoped delivery queue, sends each steer through
+`copilotSession.send`, and marks it only after the host accepts the prompt. Browser-originated
+steering therefore creates a Copilot turn without waiting for another chat message. Addressed
+steers follow their target; broadcasts are marked only for the `copilot` consumer; Copilot-origin
+messages are excluded by the queue's loop-safety filter.
+
+On adapter startup, existing backlog is marked for the `copilot` consumer without creating turns.
+Only steers created after that adapter instance started can wake it, so reopening Copilot cannot
+flood the chat with stale instructions from prior sessions.
+
+`onUserPromptSubmitted` remains the fallback. It injects the whole `/api/canvas/ax/context`
+(pins, focus, work items, approval gates, and the compact `delivery` lead block) as hidden context,
+but only when the **pin/focus gate is open** (`pinned.count > 0 || focus.nodeIds.length > 0`), and
+it is clipped to a char budget. Read steering from **`delivery.pendingSteering`** (the compact,
+count-bearing block — newest-first, capped at 10), not the full `timeline.pendingSteering`.
+
+Each prompt's injection is recorded in the context read log (`pmx-canvas ax reads`) as
+`copilot:prompt-context`, with delivery computed from the clipped text Copilot actually received.
+
+If native send fails, the adapter leaves the steer unmarked and retries. If marking fails after a
+successful send, the in-process pump retries the mark without sending the prompt twice. A process
+restart establishes a new delivery baseline and marks older unacknowledged rows without replaying
+them.
+
+To be robust to the char clip, prefer injecting that compact loop-safe lead block from
+`GET /api/canvas/ax/context?consumer=copilot` (`delivery.pendingSteering` +
+`delivery.totalPending` / `delivery.omittedPending` + `delivery.pendingActivity`)
+**above** the full dump. When `omittedPending > 0`, drain the full FIFO backlog from
+`canvas_ax_delivery { action: "claim", consumer: "copilot" }` (oldest-first).
+
+#### Waking the agent from a canvas steer (#59) — adapter-owned
+
+Recording a browser-origin `ax.steer` queues it in PMX; the Copilot adapter owns the wake. Its
+delivery pump long-polls `…/delivery/pending?consumer=copilot`, calls
+`copilotSession.send`, then marks that consumer's delivery. PMX remains host-agnostic and never
+imports the Copilot SDK.
+
+### Closing the loop (optional, recommended)
+
+- **Forward tool/session hooks** (`onPreToolUse` / `onPostToolUse` /
+  `onPostToolUseFailure` / `onSessionStart` / `onSessionEnd` / `onErrorOccurred`) to
+  `POST /api/canvas/ax/activity` (`canvas_ingest_activity`) so the board reflects the
+  agent's real work automatically (a failed tool → a blocked work item + review +
+  evidence).
+- **Await gates** with `canvas_ax_gate { kind, action: "await", id }` (or surface a native modal
+  and await the PMX result) so an approval gate actually blocks the agent until the human resolves it.
+
+See [`docs/ax-host-adapter-contract.md`](https://github.com/pskoett/pmx-canvas/blob/main/docs/ax-host-adapter-contract.md).
+- Keeps all persistent PMX state in `.pmx-canvas/canvas.db`; the extension does not own canvas
+  state.
+
+## Open Input
+
+All fields are optional:
+
+```json
+{
+  "serverUrl": "http://127.0.0.1:4313",
+  "port": 4313,
+  "autoStart": true,
+  "allowWorkspaceMismatch": false,
+  "workspaceRoot": "/path/to/repo"
+}
+```
+
+Default discovery:
+
+1. An explicit `serverUrl` input or `PMX_CANVAS_URL`, without silently choosing another target.
+2. Workspace daemon pid-file ports, the preferred `PMX_CANVAS_PORT` / `PMX_WEB_CANVAS_PORT`,
+   and the normal MCP fallback ports, verified against the workspace's real path.
+3. Serialized daemon startup for the session working directory when `autoStart` is not `false`.
+
+The adapter rejects an unrelated running PMX server unless `allowWorkspaceMismatch` is true,
+including when `serverUrl` is explicit.
+
+To package this adapter in another plugin, copy `extension.mjs`, `steering-delivery.mjs`,
+`runtime.mjs`, and `runtime.json`. For the portable MCP connector, also copy `start-mcp.mjs`,
+`tools.json`, and `THIRD_PARTY_LICENSES.txt`, and invoke `start-mcp.mjs` with Bun. The agent calls
+`canvas_connect_workspace` with its absolute project directory before using board tools;
+plugin initialization must never adopt the installation directory as a project.
+
+If discovery fails, the panel shows a connection page, not a partial workbench. It checks the
+original target automatically; **Check connection** retries immediately and **Start server**
+explicitly allows local startup even if `autoStart` was disabled. After recovery it navigates
+to the server's real `/workbench`, with Home and recent boards. Adapter actions keep using that
+server and refuse writes if its workspace changes. Reopen the canvas explicitly to select a
+different target. The fallback shell's own `/health` or `/api/canvas/boards` returning 404 is
+expected: the shell is not a PMX API proxy.
+
+## Actions
+
+| Action | Purpose |
+|---|---|
+| `status` | Return PMX server health and persisted AX state, excluding serialized node context (`includeContext=false`). |
+| `get_ax_context` | Return current pinned + focused AX context. |
+| `focus_nodes` | Set AX focus with `source: "copilot"`. |
+| `send_instruction` | Send an explicit prompt into the active Copilot session. |
+| `add_work_item` | Create a canvas-bound AX work item. |
+| `request_approval` | Open an approval gate (`pending`) before a high-impact action. |
+| `resolve_approval` | Resolve an approval gate as approved/rejected. |
+| `add_review_annotation` | Record a review comment/finding anchored to a node/file/region. |
+| `get_timeline` | Read the bounded AX timeline (events, evidence, steering). |
+| `report_capability` | Report host capabilities for diagnostics. |
+
+Example focus action:
+
+```json
+{
+  "nodeIds": ["node-123"]
+}
+```
+
+Use `nodeIds: []` to clear adapter-set AX focus after a live test.
+
+## Live-Test Checklist
+
+After changing the adapter:
+
+1. Reload extensions.
+2. Inspect `pmx-canvas` and confirm status is `running`.
+3. Call `list_canvas_capabilities` for `extensionId: "project:pmx-canvas"` and
+   `canvasId: "pmx-canvas"`.
+4. Open the canvas with a stable `instanceId`.
+5. Invoke `status`.
+6. Invoke `get_ax_context`.
+7. If at least one node exists, invoke `focus_nodes` for one node ID and confirm
+   `get_ax_context.focus.nodeIds` includes it.
+8. Clear the focus with `focus_nodes` and `nodeIds: []`.
+9. Add or reuse one `html` node and one hosted MCP app node and confirm both render visibly in the
+   native PMX panel, not only in an external browser.
+10. Inspect the extension log tail and confirm there are no runtime errors.
+
+## Agent Behavior
+
+When this adapter is loaded, the next user prompt may include hidden AX context generated from PMX
+pins and focus. Treat pinned nodes and focused nodes as human-selected working context, not as a
+global instruction to ignore the rest of the repository.
+
+For non-Copilot agents, use the same core primitives directly:
+
+- HTTP: `/api/canvas/ax`, `/api/canvas/ax/context`, `/api/canvas/ax/focus`
+- MCP: `canvas://ax`, `canvas://ax-context`, `canvas_ax_state { action: "get" }`, `canvas_ax_state { action: "set-focus" }`
+- CLI: `pmx-canvas ax status|context|focus`

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/html-primitives.md

@@ -0,0 +1,139 @@
+# HTML Primitive Authoring
+
+Use this guide when creating reusable sandboxed HTML communication primitives through
+`canvas_node { action: "add", type: "html", primitive, data }` or `pmx-canvas html primitive add`.
+
+## What They Are
+
+HTML primitives are generated `html` nodes. PMX Canvas stores the generated HTML in the normal
+sandboxed iframe node, plus metadata describing the primitive kind and source data.
+
+- Use them when markdown becomes too dense but a full React web artifact would be too heavy.
+- Prefer them for communication artifacts: choices, plans, reviews, maps, explainers, reports,
+  lightweight editors, and handoff boards.
+- Keep using `canvas_node { action: "add", type: "html", html }` for bespoke one-off HTML and JS.
+- Keep using `canvas_app { action: "build-artifact" }` for multi-component apps, routing, React state, or shadcn UI.
+
+The design language is inspired by high-density HTML communication patterns: strong hierarchy,
+metric cards, sticky context panels, annotated snippets, inline SVG figures, and copy/export actions.
+Do not copy upstream demo HTML verbatim; use the PMX primitive catalog and data shapes instead.
+
+## Current Catalog
+
+| Kind | Best use |
+|------|----------|
+| `choice-grid` | Side-by-side options with pros, cons, tradeoffs, and evidence |
+| `plan-timeline` | Sequenced implementation plans with risks, flow, and checkpoints |
+| `review-sheet` | PR or code review findings with severity, file, line, and diff context |
+| `pr-writeup` | Reviewer-ready PR narrative with motivation, file tour, tests, and rollout |
+| `system-map` | Architecture/module maps with entry points and relationships |
+| `code-walkthrough` | Guided source-path explanations with ordered steps and snippets |
+| `design-sheet` | Visual directions, palettes, tokens, type samples, and rationale |
+| `component-gallery` | Component variants, states, sizes, and accessibility notes |
+| `interaction-prototype` | Throwaway interaction or motion studies with live controls |
+| `flowchart` | Process, journey, pipeline, and failure-path diagrams |
+| `deck` | Compact arrow-key narrative decks with speaker notes |
+| `presentation` | Fullscreen-ready PowerPoint-like slide decks for briefings and pitches |
+| `illustration-set` | Inline SVG figure sheets with captions and SVG copy/export |
+| `explainer` | Feature or algorithm explainers with TLDR, steps, FAQ, and glossary |
+| `status-report` | Skimmable project health with metrics, shipped/slipped lists, and next actions |
+| `incident-report` | Incident summaries with impact, timeline, root cause, logs, and action items |
+| `triage-board` | Human-reorderable Now/Next/Later/Cut boards with markdown export |
+| `config-editor` | Feature flag or config editors with dependency warnings and diff export |
+| `prompt-tuner` | Prompt/template editors with variable previews and copy export |
+
+## Request Shape
+
+Use the running server as the source of truth before constructing data payloads:
+
+```bash
+pmx-canvas html primitive schema --summary
+pmx-canvas html primitive schema --kind explainer
+```
+
+MCP shape:
+
+```json
+{
+  "kind": "explainer",
+  "title": "HTML Primitives",
+  "data": {
+    "summary": "Reusable generated HTML nodes for rich agent-to-human communication.",
+    "steps": [
+      { "title": "Pick a primitive", "detail": "Match the work product to the catalog kind." }
+    ]
+  },
+  "x": 120,
+  "y": 80,
+  "width": 980,
+  "height": 760
+}
+```
+
+CLI shape:
+
+```bash
+pmx-canvas html primitive add \
+  --kind choice-grid \
+  --title "Implementation Options" \
+  --data-json '{"items":[{"title":"Small patch","summary":"Least disruption","tradeoff":"Limited future flexibility","pros":["Fast"],"cons":["May need follow-up"]}]}'
+```
+
+Important details:
+
+- `kind` is required.
+- `title`, `data`, `x`, `y`, `width`, `height`, and `strictSize` are optional.
+- The persisted node type is `html`, not a separate durable `html-primitive` node type.
+- `html-primitive` is accepted by schema validation and convenience creation paths as a virtual type.
+- Batch `node.add` does not create HTML primitives; use the dedicated primitive tool first or batch the generated `html` node.
+
+## Payload Rules
+
+- Keep titles short and scannable; put detail in structured fields.
+- Prefer arrays of small records over one large prose blob.
+- Include file paths, line numbers, test commands, and exact statuses when the primitive is review or engineering focused.
+- Use `summary`, `why`, `risks`, `next`, `tests`, and `reviewFocus` fields when the chosen primitive supports them.
+- For `presentation`, use `slides: [{ title, kicker?, body?, bullets?, metrics?, note? }]`; keep one idea per slide, use `metrics` for big numbers, and put speaker notes in `note`.
+- Only choose `presentation` when the user explicitly asks for a PowerPoint-like deck, pitch, briefing, workshop walkthrough, or fullscreen story. Otherwise create a normal `html` node or a non-presentation primitive.
+- Presentation data supports `theme: "canvas" | "midnight" | "paper" | "aurora"` or a custom color object with `bg`, `panel`, `surface`, `border`, `text`, `textSecondary`, `textMuted`, `accent`, and `colorScheme`.
+- For visual primitives, provide colors as hex/rgb/hsl values only; unsafe color strings are discarded.
+- For editor primitives, seed realistic initial columns, flags, controls, variables, or template text so the human can interact immediately.
+
+## Human Feedback Loop
+
+Interactive/editor primitives are useful when the human should modify state and return it to the
+agent.
+
+- `triage-board` lets the human reorder and rebucket items, then copy markdown.
+- `config-editor` lets the human toggle flags and copy a diff-like export.
+- `prompt-tuner` lets the human edit prompts, preview sample substitutions, and copy the current prompt state.
+- `interaction-prototype` exposes live controls and copyable config for implementation tuning.
+- Tell the human which copy/export button to use, then ask them to paste the result back if you need to act on edits.
+
+The card menu also offers **Copy JSON** for non-presentation HTML primitives. Open the viewer
+first: this reads its current interactive state, preferring the expanded frame when present,
+not a stale export of saved node data. The reply is bound to the frame source, document token
+and request ID; the parent workbench requests clipboard access from the human's click.
+Clipboard permission or host limitations can still refuse the copy and show an error.
+This does not persist edits, support arbitrary raw HTML, or replace the per-format buttons above.
+
+## Sandbox And Persistence
+
+- Primitive output runs inside the existing HTML iframe sandbox with scripts allowed but no same-origin access.
+- Generated HTML receives PMX Canvas theme CSS variables so it adapts to the current canvas theme, and sandboxed iframes receive live theme updates when the canvas theme changes.
+- Generated and raw HTML nodes store an agent-readable summary sidecar (`agentSummary`, `contentSummary`, and embedded references) for search, pinned context, and spatial context.
+- Only presentation-marked HTML nodes have a browser `Present` button. Use it for `presentation` nodes so the human can review the deck fullscreen, navigate slides with arrow keys/Space/Page Up/Page Down, and exit with `Esc` or `Exit presentation`.
+- Presentation primitives also persist `presentation`, `slideCount`, `slideTitles`, and optional `speakerNotes` metadata so agents can understand the deck without parsing the iframe HTML.
+- Primitive data is persisted in canvas state; do not include secrets, credentials, private tokens, or unnecessary personal data.
+- Treat primitives as communication surfaces, not authoritative application state. If the result must be machine-roundtrippable, keep the original data in the node metadata or another structured node as well.
+
+## Picking The Right Primitive
+
+- Pick `choice-grid` when a decision has competing options.
+- Pick `plan-timeline` when sequence, dependency, and risk matter.
+- Pick `review-sheet` or `pr-writeup` for code review and pull-request communication.
+- Pick `system-map`, `code-walkthrough`, or `flowchart` for architecture and source explanations.
+- Pick `design-sheet`, `component-gallery`, `interaction-prototype`, or `illustration-set` for visual/product work.
+- Pick `presentation` when the human asks for a PowerPoint-like deck, pitch, briefing, workshop walkthrough, or fullscreen story.
+- Pick `explainer`, `deck`, `status-report`, or `incident-report` for narrative reporting.
+- Pick `triage-board`, `config-editor`, or `prompt-tuner` when the human needs to edit or return structured feedback.

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/importing-context.md

@@ -0,0 +1,132 @@
+# Importing context
+
+Use this workflow when bringing existing context into PMX Canvas from folders, repositories,
+documents, notes, backlogs, structured exports or knowledge bases. It guides organization and
+verification, not a universal file converter or live sync. PDF/Office attachments still require
+the human-consented extraction and review workflow; this guide does not bypass it.
+
+## Inspect the source before choosing the structure
+
+Inventory the requested scope, file types, existing categories, references and assets. Read
+representative content before mapping it: folder names alone do not establish board boundaries,
+and files may contain several independent items or one argument that should stay together.
+Identify duplicates, historical material, unsupported formats and inaccessible sources. Report
+gaps rather than silently skipping them or claiming extraction succeeded. Keep private context
+within the authorized destination; a folder import is not permission to include credentials.
+
+## Choose boards and cards by purpose
+
+Categories organize boards; boards hold coherent topics or workflows; cards hold useful content.
+Preserve useful categories and folder context without mechanically copying the directory tree.
+A project folder may become an overview board, a backlog with item cards, and a research board.
+Several small files may belong on one board; a single export may need several boards. Choose
+cards by useful units of meaning, not automatically one per file, heading or data row. Retain
+section context, nested details and useful source ordering when splitting content. These are
+examples, not a fixed taxonomy. Explain consequential grouping choices and make them easy to revise.
+Several boards in one category are fine. Keep an argument together when splitting would lose
+meaning. Group related cards and use the main skill's README and focus guidance for a readable start.
+
+Lead each card with the task, item, decision or document section the reader came to find.
+Retain ancestor headings, folder/repository context and source details below that content,
+not as repeated preambles that push every useful item below the card's visible area. Preserve
+meaning and source hierarchy without making the reader expand every card to identify it.
+
+## Preserve sources and stable targets
+
+Work in an isolated workspace for a test import. Preserve an existing import before replacing
+it, and leave source material unchanged unless editing it was requested. Record source paths,
+URLs or record IDs, revisions where available, and the source-item/section → board/card ID
+mapping so interruptions and retries can reuse created objects instead of duplicating them.
+Distinguish faithful imports from summaries; keep a path back to the original. Capture the active
+board before writes, separately from any explicit destination. Create destination boards and
+cards before rewriting internal references, use returned IDs rather than guessed titles, and
+preserve external links.
+
+Create supported static cards, groups and edges on an inactive board with `destinationBoardId`
+without switching the human's view. Static nodes are Markdown, status, context, ledger, trace,
+diff, Mermaid and plain HTML; images, runtime-backed nodes, generated primitives and intents
+are not supported by this path. Updates/removals still require the active board. In a named
+`canvas_batch`, each operation's `args` carries its destination and retry fields; group children
+and edge endpoints can use the existing named references. `toBoardId` independently chooses a
+remote edge endpoint, not the board that owns its source.
+
+Assign a stable `requestId` to each logical static node/group/edge creation and retain it in
+the source-to-canvas mapping. Retry with the same input and destination: the durable receipt
+returns the original result after interruption or restart, even if the object was subsequently
+edited or deleted. It does not restore deleted objects. Changed-input reuse conflicts; a new
+intentional creation gets a new ID even when its content is identical. Batch operations commit
+in sequence, not as one all-or-nothing import. Persist the mapping as receipts arrive.
+
+`expectedBoardId` guards the active board even with an explicit destination. A stale guard
+means refresh context, not substitute the destination ID or switch the human's view to retry.
+For active-only work, explicitly open the intended board and verify its returned ID first.
+Scope fences and human edit locks remain enforced. If Home is active, list/open a suitable
+board before reading board context; library discovery and background static creation can
+stay on Home. For retrieval, `canvas_query` search accepts intersecting `boardId` and `folder`
+filters. Folder includes slash-boundary descendants; `folder: ""` selects unfiled boards.
+Filters default omitted scope to library, while explicit active scope never widens. Search
+never changes the active board.
+
+Use native `references` edges for explicit source links and qualified remote endpoints for
+cross-board cards. Add semantic relations only when the source supports them; record the
+supporting passage or source reference in `reason`. Similar subjects alone do not establish
+dependency, causation or supersession. Follow the main skill's direction rules for dependency kinds.
+
+Preserve historical/draft status and source evidence dates. Importing, reading or rendering
+content does not revalidate it. Flag source contradictions separately from conversion errors
+and product bugs; do not silently rewrite uncertain facts or invent validation dates.
+
+## Markdown link conversion
+
+For content represented as Markdown, use returned IDs in `[[board-id#card-id|label]]` links
+and keep code spans/fences unchanged. In table cells, escape the alias pipe:
+`[[board-id#card-id\|label]]`. Otherwise the table parser can split the link before the wiki
+link parser sees it. Zero unresolved links is not sufficient: compare expected source link
+occurrences with rendered anchors. This is a Markdown rendering concern, not a source-format requirement.
+
+## Keep picture bytes out of long Markdown
+
+Prefer local asset references over large base64 image strings embedded in Markdown. The
+embedded bytes enlarge layout/render requests; inline pictures remain supported. Choosing
+file-backed assets is a representation choice, not proof that a parser or loading bug is fixed.
+Keep private pictures in the authorized workspace; do not upload them to a public image host.
+
+One supported approach is a file-backed image card in the document's board:
+
+```json
+{"action":"add","type":"image","content":"assets/diagram.png","title":"System diagram"}
+```
+
+Call `canvas_node` with that payload, then use the returned ID in the document:
+`![System diagram](/api/canvas/image/<image-node-id>)`. Keep the original alt text and connect
+the document to its figure card when useful. This route resolves nodes on the active board:
+keep the image card in the same board, and recheck references after copying or moving cards.
+
+Relative image creation paths resolve against the canvas workspace root, not the server's
+launch directory. An absolute path inside that workspace also works. Image creation requires
+opening its destination board; do not send `destinationBoardId` or `requestId` for image nodes.
+The database stores the path, not the file bytes: retain the assets alongside it, update paths
+if relocating the workspace, and verify images in exports rather than assuming the live URL
+is portable.
+
+## Verify the imported workspace, not just the API receipts
+
+1. Account for each in-scope source item as imported, summarized, intentionally excluded or
+   unresolved. Reconcile split items, references and assets with the mapping. Check edge endpoints,
+   group containment and collisions with `canvas_query { action: "validate" }`.
+2. Open representative boards for the content actually imported: for example a dense backlog,
+   long document, linked table or picture-heavy board. Wait for the correct board and populated
+   card bodies, not only titles or HTTP success. Images must load with nonzero natural dimensions.
+3. Wait for the intended card/group bounding rectangle after a camera update. Two animation
+   frames do not prove an asynchronous layout update arrived. Inspect screenshots at the
+   intended viewing zoom for readable cards, relations, labels and unobscured controls.
+4. Click local and cross-board links; verify the intended card becomes visible. On a disposable
+   test service, restart and verify persistence, including pictures. Compare asset bytes when
+   changing image representation to confirm originals were preserved.
+5. If loading is slow, measure board-open to rendered-content readiness on repeated equivalent
+   workloads. Include a text-only control; record payload sizes, cache conditions and whether
+   measurements used a local connection or the user's host. Separate observations from causes.
+
+Report coverage, unresolved issues and storage requirements. Distinguish an import workaround
+from a product fix, and a source snapshot from live synchronization. Keep private source paths,
+names and content out of reusable skills and public issue reports.