--- name: cnvs-whiteboard description: PRIMARY skill for any cnvs.app board work. Collaborate on a cnvs.app whiteboard (canvas / board / drawing surface) in real time — read shared state, add/update/move/delete text, links, sticky notes, strokes, images, and Mermaid diagrams (flowcharts, sequence diagrams, class and ER diagrams, mind maps, gantt charts, concept maps, and more), and render the SVG preview when the board has drawings. Use whenever the user references a cnvs.app board (URL `https://cnvs.app/#`, `cnvs://board//...`, or `/mcp` endpoint), asks to draw / sketch / diagram / flowchart / annotate / brainstorm / collaborate / edit / watch / create content on a shared whiteboard or canvas, or drops a board ID expecting the agent to act on it — even if they don't name cnvs.app, MCP, or REST. For push-to-model notifications on human edits this skill delegates to the generic `mcp-listen` skill; install both for the full loop. compatibility: Requires outbound HTTPS access to https://cnvs.app. MCP subscriptions need a Streamable-HTTP MCP client (Claude Code, Claude Desktop, Cursor, OpenCode, Aider with MCP plugin, etc.). Writes work from any runtime via plain REST — no MCP client required. license: MIT metadata: author: cnvs.app version: "1.0.0" homepage: https://cnvs.app/cnvs-whiteboard/ board_url_pattern: "https://cnvs.app/#" --- # cnvs-whiteboard Be a live AI collaborator on a cnvs.app board — discover changes, make edits, stay in the loop without polling, and don't wake yourself on your own writes. One skill, copy-pasteable patterns. > **If you only read one thing.** Listen for edits via MCP subscriptions (the only real-time push channel). Act on the board via the REST API (universal — works from any runtime with outbound HTTP, no MCP client required). Don't use MCP tool-calls for writes if REST is available: it wastes tool-call slots, adds session bookkeeping, and blocks every non-MCP agent runtime from ever contributing. The hybrid **MCP-listen + REST-write** loop is what this skill wires up. > **Service boundary.** cnvs.app is a third-party hosted service operated outside this skill / Anthropic / the user's own infrastructure. Anything written to a board (text, links, ink, images, Mermaid source) is stored on cnvs.app and is reachable by anyone who has the board ID — boards are unlisted, not private. Treat it like any other public URL: don't paste secrets, credentials, customer PII, or proprietary content unless the user has explicitly chosen cnvs.app as the surface for that content. > **Access locks.** A board can OPTIONALLY be PIN-locked (8 chars, a-z0-9; legacy boards may carry a 6-char key). Two modes: `write` (anyone reads, only key-holders write) and `all` (key required for both reads and writes). If you hit HTTP `401` with `{"code": "board_locked", "lockMode": "..."}` (REST) or JSON-RPC error `-32001` (MCP), the board is locked and you need the key. Pass it via the `X-Board-Key` header on REST and MCP POSTs, or as the `access_key` argument on individual MCP tools / `resources/read` / `resources/subscribe` params. WebSocket connections can't set custom headers, so the key rides in the `Sec-WebSocket-Protocol` subprotocol — open the socket as `new WebSocket(url, ['cnvs-key.'])`; the server validates and echoes the same protocol back in the 101 response. The user owns the key — ask them for it rather than guessing. Lock management endpoints: `POST /api/boards//lock {mode}` returns the key ONCE on first lock; `POST /api/boards//unlock` clears the lock (header required); `POST /api/boards//verify-key {key}` is a pure check. There is no recovery — if every key-holder loses the key, the board becomes unreachable and gets auto-deleted after 30 days of inactivity. ## Need a new board One call — no auth, no setup: ```bash curl -s -X POST https://cnvs.app/api/boards # → {"id":""} ``` That's it. Drop the returned id into `https://cnvs.app/#` to share, and into every `/api/boards//...` mutation below. Use this whenever the task asks for a fresh surface and no URL was given. Building a whole board from scratch? The same endpoint accepts an optional import body — `{ content, autolayout?, lock?, author? }` — that creates the board pre-filled (texts/lines/images, or `mode:"todo"` with columns/tasks) in ONE atomic call: everything is validated first, and any invalid item aborts with a structured `400 {error:"invalid_item", kind, index, reason}` leaving nothing behind. The combined content arrays may contain at most **2550 entries**; `lanes` has at most **10 entries**, every lane title must reference a row used by a created column, and each lane index may be named **at most once** — a second `{lane: 0, …}` entry is rejected (`{error:"invalid_item", kind:"lanes", index: , reason:"lane 0 is named twice in this import — each lane may have at most one title entry"}`) instead of collapsing last-write-wins, which would overwrite the first entry's `author`. `tasks[].done` must be a **real boolean** — `"done": "false"` is `{error:"invalid_item", kind:"tasks", index, reason:"done must be true or false (or omitted)"}`, not a card silently imported as completed; omit it or send `null` for not-done. (In practice the 5 MB request-body cap binds first on image-heavy imports.) `autolayout: true` places draw items that omit x/y; `lock: "write"|"all"` PIN-locks at create time (plaintext key returned once as `access_key`). Every item accepts its own optional `author` — an item's author is its CREATOR and is never rewritten, so restoring somebody else's board keeps the original attribution instead of stamping yours; omit it to inherit the body-level `author` (default `ai:import`). Item ids are ALWAYS server-minted and come back in `ids` (`{texts,lines,images,columns,tasks}`, index `i` ↔ `content.[i]`; `ids.columns` is empty when the columns came from the template seed, and lanes have no id). To keep anchored strokes across a restore, give a text/image a write-only `sourceId` (unique string, ≤128 chars — never stored, never the row id) and point `lines[].anchors.start.id` / `.end.id` at it: matching ids are rewritten to the minted id, unmatched ids stay verbatim and render as a free stroke end. The response's `imported` counts double as feature detection. MCP mirror: the `create_board` tool (same arguments + implementation). A valid server-to-server `X-Import-Token` selects the 10× infrastructure REST/MCP rate tier (600/10s/board; 50 creates/60s/token); it never bypasses board access locks, content, validation, or platform limits. Full schema: https://cnvs.app/llms-full.txt ("Board import"); live limits: https://cnvs.app/quotas.json. Small print: the server generates the id — don't synthesise your own UUID client-side. From an MCP-capable runtime you can use `create_board` directly; either way, follow up with `open_board()` + subscribe for live reads. ## How to use this skill Each time you receive a board ID (or URL), run through this checklist: 1. [ ] **Set your author tag.** Pick an `ai: