Folio Boards

Excalidraw boards through create_board/update_board

A board (kind: board) is a separate page in the tree of a space, a full-screen Excalidraw. The agent does not draw every element of the scene by hand — it describes the board with the compact sketch DSL, and the server lays it out into real Excalidraw elements itself.

When to use a board, and when mermaid in a document

• A simple diagram inside a document (a flowchart, sequence, gantt and so on) is handier and cheaper as a ```mermaid block right in the body of the page (the folio-content skill, section "Mermaid diagrams"): it creates no separate page, is easily edited as text, is versioned as a line in git.
• A board — when exactly a separate diagram page in the tree is needed (an architecture, a map of a process that people want to open and refine by hand in the Excalidraw editor), or when "make a board" is asked for explicitly.

The contract of create_board / update_board

create_board({ space, parentPath, title, sketch? | scene? })
update_board({ id, sketch? | scene? })

Pass sketch — the compact DSL below. Use the full scene (raw Excalidraw elements) only for a pinpoint edit of an already existing board: first read_page (for a board it returns scene), then make changes in the array of elements you got, and send it back through update_board({ id, scene }). Do not generate a scene from scratch — it is the format of the Excalidraw engine, not a DSL that is convenient to write.

The sketch DSL

sketch = {
  background?: string,   // hex of the board background, '#ffffff' by default
  nodes: [{
    id: string,           // unique within the sketch, referenced by edges/frame
    type: 'rectangle' | 'ellipse' | 'diamond' | 'text' | 'frame',
    label?: string,
    x: number,
    y: number,
    w?: number,            // the default depends on the type, see below
    h?: number,
    color?: string,        // stroke, hex, default '#1e1e1e'
    background?: string,   // fill hex or 'transparent'
    fontSize?: 16 | 20 | 28,
    frame?: string,         // id of the type:'frame' node this node lies in
  }],
  edges: [{
    id?: string,
    from: string,           // id of the source node
    to: string,             // id of the target node
    label?: string,
    elbowed?: boolean,       // default true — orthogonal (elbow) arrows
    start?: 'arrow' | null,  // default null
    end?: 'arrow' | null,    // default 'arrow'
    color?: string,
  }],
}