Af Canvas Expertise

Canvas Expertise

When to Use This Skill

Load this skill when you need to:

• Show a file or document to the user in the canvas
• Create a diagram to explain something visually
• Write HTML content for rich interactive display
• Create an Excalidraw drawing programmatically
• Read what the user has written in the canvas

Quick Reference

Canvas ID Convention

Each task has a canvas scoped to its issue ID. Your canvas ID is your issue ID:

AGV-20  -> canvas ID: AGV-20
AGV-34  -> canvas ID: AGV-34
scratch -> default canvas (no task context)

Environment Setup

The canvas API requires authentication via CANVAS_API_KEY:

# Required environment variables
export CANVAS_API_URL="https://agentview-api.gaininsight.co.uk"  # Dev API
export CANVAS_API_KEY="<from Doppler>"                           # Agent auth key

API URLs by environment:

For autonomous agents: CANVAS_API_KEY and CANVAS_API_URL must be in the agent runner env file (/etc/claude/agent-orchestrator.env). If missing, ask the human to run:

sudo /usr/local/bin/setup-orchestrator-env
sudo systemctl restart agent-runner

For interactive sessions: Use doppler run to inject the key, or export it manually.

Core Workflows

Show a File to the User

When the user says "show me the vision doc" or "put the README in the canvas":

1. Read the file from the repo
2. Push it to the canvas using canvas-put
3. Focus the canvas so the UI switches to it

# Read a file and push to canvas
canvas-put AGV-20 docs/vision.md

# Focus the UI on the canvas in markdown mode
canvas-focus AGV-20 markdown

Or if you need to transform content before displaying:

# Read, transform, and pipe to canvas
cat docs/vision.md | canvas-put AGV-20 -
canvas-focus AGV-20 markdown

Create a Diagram

When the user says "explain that with a diagram" or "draw me the architecture":

Ask which format they prefer (unless context makes it obvious):

"I can create this as:

• Mermaid — code-generated, clean, auto-layout (best for flowcharts, sequences, entity relationships, state machines)
• Excalidraw — hand-drawn style, freeform positioning (best for architecture diagrams, system overviews, custom layouts)
• HTML — rich styled content with CSS (best for dashboards, interactive demos)

Which would you prefer?"

Mermaid Diagrams

Mermaid diagrams are embedded in markdown using fenced code blocks. The canvas preview renders them automatically.

canvas-put AGV-20 --text '# Architecture Overview

```mermaid
graph TD
    A[Client App] --> B[API Server]
    B --> C[Database]
    B --> D[Canvas WebSocket]
    D --> A

Components

• Client App — React + TypeScript frontend
• API Server — Express with REST + WebSocket
• Database — PostgreSQL for persistence ' canvas-focus AGV-20 markdown

**Mermaid is best for:** flowcharts, sequence diagrams, entity-relationship diagrams, state machines, Gantt charts, class diagrams. Anything where auto-layout is valuable.

#### Excalidraw Drawings

Agents can create Excalidraw drawings programmatically by writing JSON to the drawings API endpoint. This produces hand-drawn-style diagrams with precise element positioning.

```bash
# Write Excalidraw JSON via REST API
curl -s -X PUT \
  -H "X-API-Key: ${CANVAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "elements": [
      {
        "type": "rectangle",
        "x": 100, "y": 100, "width": 200, "height": 80,
        "strokeColor": "#1e1e1e",
        "backgroundColor": "#a5d8ff",
        "fillStyle": "solid",
        "roughness": 1,
        "id": "box1"
      },
      {
        "type": "text",
        "x": 140, "y": 130, "width": 120, "height": 25,
        "text": "Client App",
        "fontSize": 20,
        "id": "label1"
      },
      {
        "type": "arrow",
        "x": 300, "y": 140, "width": 100, "height": 0,
        "strokeColor": "#1e1e1e",
        "id": "arrow1"
      },
      {
        "type": "rectangle",
        "x": 400, "y": 100, "width": 200, "height": 80,
        "strokeColor": "#1e1e1e",
        "backgroundColor": "#b2f2bb",
        "fillStyle": "solid",
        "roughness": 1,
        "id": "box2"
      },
      {
        "type": "text",
        "x": 440, "y": 130, "width": 120, "height": 25,
        "text": "API Server",
        "fontSize": 20,
        "id": "label2"
      }
    ],
    "appState": {
      "viewBackgroundColor": "#1e1e1e",
      "gridSize": null
    }
  }' \
  "${CANVAS_API_URL}/api/canvas/AGV-20/drawings/architecture"

# Focus the UI on the drawing
canvas-focus AGV-20 drawing

Excalidraw is best for: architecture diagrams, system overviews, custom visual layouts, anything where you want hand-drawn aesthetics with precise control over positioning.

Excalidraw element types: rectangle, ellipse, diamond, arrow, line, text, freedraw, image. Each element needs at minimum: type, x, y, width, height, and a unique id.

HTML Content

IMPORTANT: HTML content uses a separate API endpoint from markdown. Do NOT use canvas-put for HTML — it writes to the markdown store. Use the /html endpoint directly:

# Write HTML to a file first, then push via curl
cat > /tmp/my-content.html << 'HTMLEOF'
<!DOCTYPE html>
<html>
<head>
<style>
  body { font-family: system-ui; background: #1e1e1e; color: #e0e0e0; padding: 2rem; }
  .card { background: #2d2d2d; border-radius: 8px; padding: 1.5rem; margin: 1rem 0; }
  h1 { color: #60a5fa; }
</style>
</head>
<body>
  <h1>Dashboard</h1>
  <div class="card">
    <h2>Status: Active</h2>
    <p>All systems operational.</p>
  </div>
</body>
</html>
HTMLEOF

# Push HTML to the /html endpoint (NOT /api/canvas/:id)
curl -s -X PUT \
  -H "X-API-Key: ${CANVAS_API_KEY}" \
  -H "Content-Type: text/html" \
  --data-binary @/tmp/my-content.html \
  "${CANVAS_API_URL}/api/canvas/AGV-20/html"

# Focus in web mode
canvas-focus AGV-20 web

Or for inline HTML:

curl -s -X PUT \
  -H "X-API-Key: ${CANVAS_API_KEY}" \
  -H "Content-Type: text/html" \
  -d '<h1 style="color: #60a5fa;">Hello</h1>' \
  "${CANVAS_API_URL}/api/canvas/AGV-20/html"
canvas-focus AGV-20 web

How HTML rendering works:

• HTML is rendered in a sandboxed iframe (sandbox="allow-scripts") — global CSS is safe and won't leak into the host app
• The client fetches HTML from GET /api/canvas/:id/html (separate from markdown at GET /api/canvas/:id)
• WebSocket updates include mode: 'html' to route content to the correct state
• Full HTML documents (<!DOCTYPE html>, <html>, <head>, <body>) are supported

HTML is best for: custom layouts, interactive dashboards, styled presentations, content that needs CSS or JavaScript.

Read from the Canvas

When you need to see what the user has written or edited in the canvas:

# Read current markdown canvas content
canvas-get AGV-20

# Read an Excalidraw drawing (returns JSON)
curl -s -H "X-API-Key: ${CANVAS_API_KEY}" \
  "${CANVAS_API_URL}/api/canvas/AGV-20/drawings/main"

Use this when:

• The user says "look at what I wrote in the canvas"
• You need to review or iterate on canvas content
• You want to save canvas content to a file

Save Canvas Content to Repo

Canvas content is ephemeral (in-memory, lost on server restart). If the user wants to keep it:

# Save markdown canvas to a file
canvas-get AGV-20 > docs/architecture-diagram.md
git add docs/architecture-diagram.md
git commit -m "docs: add architecture diagram from canvas"

# Save Excalidraw drawing to a file
curl -s -H "X-API-Key: ${CANVAS_API_KEY}" \
  "${CANVAS_API_URL}/api/canvas/AGV-20/drawings/architecture" \
  > docs/diagrams/architecture.excalidraw
git add docs/diagrams/architecture.excalidraw
git commit -m "docs: add architecture drawing from canvas"

Always offer to save to the repo if the user has created substantial content.

Format Decision Guide

API Reference

REST Endpoints

Content type mapping:

Authentication

All requests require the X-API-Key header:

curl -H "X-API-Key: ${CANVAS_API_KEY}" "${CANVAS_API_URL}/api/canvas/AGV-20"

The shell helpers (canvas-put, canvas-get, canvas-focus) handle auth automatically via CANVAS_API_KEY env var.

WebSocket

The UI subscribes to canvas updates via WebSocket. When you canvas-put, the UI updates in real-time — no page refresh needed. When you canvas-focus, the UI switches to the specified canvas and mode.

Common Patterns

Iterative Content Creation

Build up content incrementally:

# Start with structure
canvas-put AGV-20 --text "# Feature Spec\n\n## Overview\n\nTBD\n\n## Requirements\n\nTBD"
canvas-focus AGV-20 markdown

# Later, update with full content (overwrites previous)
canvas-put AGV-20 --text "# Feature Spec\n\n## Overview\n\nThis feature enables...\n\n## Requirements\n\n1. Must support..."

Note: canvas-put overwrites the entire canvas. There is no patch/append — always write the full content.

Multiple Content Sections with Mermaid

Combine narrative with diagrams in a single canvas:

canvas-put AGV-20 --text '# System Design

## Data Flow

```mermaid
sequenceDiagram
    User->>+Canvas UI: Edit markdown
    Canvas UI->>+API: PUT /api/canvas/:id
    API->>+WebSocket: Broadcast update
    WebSocket-->>-Canvas UI: Live update

Component Architecture

graph LR
    A[CanvasPage] --> B[Monaco Editor]
    A --> C[Markdown Preview]
    A --> D[Excalidraw Editor]
    C --> E[Mermaid Renderer]

Notes

• Canvas is ephemeral — save important content to git
• WebSocket provides real-time sync between agents and UI '

### Embedding Excalidraw Drawings in Markdown

The canvas supports embedding drawings in the markdown preview using the `canvas:` URI scheme:

```markdown
![Architecture Diagram](canvas:architecture)

This renders the Excalidraw drawing named "architecture" as an SVG inline in the markdown preview. Create the drawing first via the drawings API, then reference it in your markdown content.

Troubleshooting

Key Principles

1. Canvas is ephemeral — in-memory only. Offer to save to repo for important content.
2. Agent reads and pushes — read files from repo, push to canvas. Don't expect the canvas to load files itself.
3. Overwrite semantics — canvas-put replaces the full canvas. No partial updates.
4. Real-time sync — WebSocket broadcasts mean the user sees changes instantly.
5. Ask about format — when creating diagrams, ask the user if they want Mermaid, Excalidraw, or HTML (unless context makes the choice obvious).
6. Focus after writing — always call canvas-focus after canvas-put so the UI switches to show your content.
7. Use external URLs — always use the external API URL (*.gaininsight.co.uk or *.gaininsight.global), not localhost.