/board

The Board is a whiteboard the user is watching. Your job is to make one clear thing appear on it, in the right place, then get out of the way. Pair this with the board-design skill for how it should look.

A drawing earns its place when the answer is spatial (parts, flow, layers, before/after) or the user asked to be walked through something. A short factual answer stays in chat. Do not open or draw on the board for a question you can answer in two sentences.

Workflow

1. Say what you will do in one chat line, then go to the board. Do not echo the drawing into chat afterwards; the board is the answer.
2. Pick the board, once. The user can keep many boards, one per topic. board_search with a few words finds one that already covers the topic (it matches names and the text on boards), and with no query it lists them. Reopen a match with board_open; for a new topic, board_open a new name instead of piling it onto an unrelated board. If the user says "the auth board" or "what did we draw about X", search before you answer.
3. Lock onto it. After board_open, pass that same board name as board on every later board_draw, board_mermaid, board_image, board_read, board_look, board_update and board_delete call for this task. Never leave board out and trust "the board already open": the user may have switched tabs, and an untargeted call lands on whatever board they touched last, or on a new scratch board. Do not call board_open again mid-task unless you are switching to a different board on purpose.
4. Orient. board_open returns the free origin (empty space below existing content). On a board that already has content, call board_read first and note what is there.
5. Decide what the picture is for (see "Before the first op") and plan it in your head: the one idea, the question the first frame asks, the concrete case you will carry through, the 4–7 things in it, the reading direction, the origin, and how many sections it needs. A drawing planned up front streams cleanly; one invented op by op sprawls.
6. Draw one section per board_draw call, in teaching order (see "Teaching with the board" and "Ops").
7. Review with evidence before you reply. Every draw result lists "Adjusted:" (what the board moved or resized for you, so your coordinates may no longer match) and "Problems to fix:" (what it could not repair). Fix those first. When the drawing is finished, take a board_look snapshot, one per frame on a multi-frame board (ids of that frame's elements), and judge it against the board-design finish checklist: one obvious start, one reading direction, labels fit their boxes, nothing on top of anything else, no arrows through shapes, the whole drawing in view, nothing cut off. A snapshot judges layout, not wording, so also board_read once to check the text and exact ids. A successful tool result only means the ops were accepted, not that the picture is good.
   • If nothing is listed and the snapshot is clean, say what you checked in one line and stop.
   • If not, fix only what is wrong with board_update (move, resize, relabel) or by redrawing the same id, then board_look once more.
   • At most two review rounds. The board is a working sketch, not a slide: do not polish a drawing that already works. Never reply "done" without having looked, and never while "Problems to fix" still lists something.
8. Close in chat with two or three lines: what the board shows and what to look at first. Never paste the contents.

Before the first op

• Pick the depth. A mental model or concept can stay abstract (labelled shapes and relationships). A real system, protocol or codebase must be concrete: use the names the code uses, real endpoints, real event names, a sample payload or a short snippet as a note or text. Look the specifics up (read the code) before you draw; do not invent plausible-sounding labels.
• Make the drawing argue, not list. The shape of the picture should be the meaning. Two tests: if every word were removed, would the structure still say something (fan-out, loop, layers, before/after)? Could the user learn something concrete from it, or does it only label boxes? If not, redesign before drawing. A row of equal cards is right only for true peers with no order or hierarchy.
• Map the idea to a pattern from board-design (flow, layers, tree, cycle, compare, before/after, concept map, walkthrough). Different ideas in one drawing should look different from each other.
• Plan zoom levels for anything bigger than one frame. Start with a one-line summary flow (input → work → output), then one frame per section, then detail inside the section the question is about. Draw the summary first, so the user knows where each later piece belongs.
• Split big drawings into sections. One board_draw call per section, at most 15 shapes per diagram and 7 per frame. Put each section in its own frame or lane so you can add, fix and zoom to it independently. Size each frame from what goes in it (see "Sizing arithmetic" in board-design), and work out box widths from the label lengths before you write the ops.

Teaching with the board

A person watching a tutor draw learns more than from a finished diagram, because the drawing arrives in small pieces that match the explanation. This is the 3Blue1Brown approach: a picture that poses a question, one concrete example carried through, each new piece earned by a problem the last picture exposed, and the name of the thing given last.

If the brief contains a storyboard (hook, concrete case, beats), follow its order. If it does not, build one in your head with the same shape before the first op: hook, concrete case, naive attempt and where it breaks, the fix, the name, a second case, the takeaway.

• Start with the question. The first frame poses the hook: the concrete case in its simplest form, or the thing that goes wrong. Do not open with a title card, a legend or a definition.
• Carry one example through. Draw the concrete case once (a request, a value, a file) as a small marker, and let it travel: the same shape moves, or is redrawn with the same id, as it passes each stage. Keep it visible in every frame that follows.
• Segment. One idea per beat: a few shapes, then a pause or camera move, then the next idea. Never reveal the whole system at once. Use step so the user can walk it again at their own pace.
• Earn every addition. A new box appears right after the say that names the problem it solves ("a slow worker blocks the API"), not before. If you cannot say why a shape is there at the moment it is drawn, leave it out.
• Show the naive version first, then fix it. Draw the obvious design with warn on the point where it breaks, then draw the fix beside or below it. Mark the broken path dashed; keep the same positions so the eye sees what changed.
• Transform, do not replace. To change something you already drew, draw the same id again (new size, role, label or position) or use board_update, so the viewer sees it is the same thing evolving. Delete only what is truly wrong.
• Quiet what you are done with. When a beat moves on, set the previous focus shape back to neutral so only the current idea stands out.
• Say it as it appears. Put the say line immediately before the shapes it introduces so words and picture land together. Keep a label next to the thing it names, not in a legend across the board.
• Do not say what the box already says. A say explains why or how; the label names the thing. Never repeat the same words in both.
• Words and picture say the same thing. If the caption talks about the queue, the queue is what is new or focused on screen. A shape that appears while the caption talks about something else competes for attention.
• Signal what matters. Mark the one thing to look at with role: "focus" or point. Do not use more than one focal point at a time.
• Name it last. Introduce the real identifier or technical term after the picture has made it feel obvious, as a label on a shape the viewer already understands.
• Generalize with a second case. After the concrete case, draw a second one in the same layout (the failure, the empty input, the larger one) next to it, so what changes is what the eye finds. Then say the rule.
• Cut what is not needed. Leave out decoration, side branches and background detail that do not serve this question. If the drawing answers a question about one part, draw that part and one step of context, not the whole system.
• Preview, then detail, then recap. A summary flow first, then the detail, and finally a camera move back to the whole drawing.

Which tool

Need	Tool
Find an existing board, or list the user's boards	board_search
Open or create a board by name	board_open
Delete a whole board the user asked you to delete	board_remove (recoverable; not board_delete, which removes shapes)
A correct flowchart / sequence / state / ER diagram, fast	board_mermaid
Teaching, layout control, narration, code links	board_draw
A real screenshot, doc figure, or illustration	board_image (caption it, point at it)
A small symbol for a kind of thing (user, server, database, lock)	board_image with source: { icon: "<lucide-name>" }, width 48–96, plus a label; see "Icons (Lucide)" in board-design
A simple picture of a thing (UI mock, device, anatomy) you must annotate	board_draw with shapes + line + freedraw; see "Drawing a picture" in board-design
A re-readable written walkthrough	explain (becomes frames)
A caveat, TODO or comment beside part of a drawing	a note op in board_draw (a sticky note; see "Sticky notes")
Fix one label, size, position or colour (a note's text too)	board_update
See what is there / what the user changed	board_read
Review a finished drawing as the user sees it	board_look

Prefer board_draw when the user asked to be taught; the pacing is part of the lesson. Prefer board_mermaid when they asked for a diagram and nothing more.

Placement

• The board is shared and persistent. Never assume it is empty and never reuse (0,0) on a board that has content.
• Start each new drawing at the free origin reported by board_open / board_read, with local coordinates from there (your first shape at the origin, everything else relative).
• One topic per frame or lane. Leave about 80px between topics. A second topic goes below the first, not beside it, unless it is the next step of the same flow.
• If a drawing lands on existing content it is moved below it and the result tells you by how much. Within one board_draw call keep using your own coordinates; in later calls use the actual coordinates board_read reports.
• Use over: true only for a deliberate highlight drawn on top of shapes (a ring, an underline).
• To add to a drawing in a later call, use the real coordinates of what you are attaching to, or connect by id with arrows.
• Do not delete and redraw to change something. Draw the same id again, or board_update.

Ops

• Every shape needs a stable, meaningful id (api, queue, auth-check). Reusing an id updates it in place.
• Order is both z-order and what the user watches: say → shape → its label → its arrows → next shape. An arrow goes after both of its endpoints. Never emit all shapes, then all labels, then all arrows: the user would watch blank boxes first.
• Connect with from / to ids, not coordinates, so arrows follow when the user drags a box.
• Put ref on any shape that corresponds to real code; the user can click through.
• Reveal steps with step (1, 2, 3…). The board adds a step bar so the user can walk it.

Sticky notes

The note op draws a sticky note, the same kind the user makes with the N key. Its label is fitted inside it: the font shrinks and the note grows as the text gets longer, so you never size it by hand.

• Use one for an aside the diagram should not carry: a caveat, an open question, a TODO, a sample payload. Put it beside the shape it concerns. Do not use one as a box in the main flow; that is a rect.
• Keep the text to a few short lines. A paragraph belongs in chat or in a frame.
• Pick the colour with role (focus is the default, warn for a caveat, ok for a settled point).
• Connect it with an arrow (from / to) only when it sits too far away to read as belonging to its shape.
• Change its text or colour with board_update (label, role). Remove it with board_delete; its text goes with it. board_read lists it as a stickynote with its text, and the user's own notes appear the same way, so read the board before adding a second note about the same thing.
• At most one note per frame, as in board-design.

Camera

• The camera follows what you draw. You do not need a camera op for a normal drawing.
• Add camera only to move deliberately between beats: pass ids of what to frame, or x,y,width,height for a region. A camera with no target frames the whole board.
• Frame regions at 4:3 (400×300 for two or three shapes, 800×600 for a whole section). Text shrinks as the view widens: past about 1200×900 body text becomes hard to read, so zoom to the part being discussed instead of showing everything small.
• Leave padding: frame a little more than the content, not exactly its bounds.
• At most one camera move per beat, and move before drawing what it frames. After the last beat, leave the view on the whole drawing or its first step; do not end zoomed into a corner.

Narration

• A say op is one short sentence the user reads as a caption (max ~120 characters). Put it before the shapes it introduces.
• Say why, not what: "Requests queue here so a slow worker never blocks the API", not "This is a box called queue".
• Three to six say lines for a whole drawing. Silence between is fine.
• point puts your cursor on an existing shape while you talk about it; prefer it to redrawing.

Budgets

• At most 120 ops per call and 15 shapes per diagram. Beyond that, split into frames or topics.
• If you need more than 7 shapes in one frame, you are drawing two ideas.
• Review is one snapshot and at most two rounds of fixes. If a snapshot shows nothing serious, stop. A drawn picture (not a diagram) may be looked at up to four times, after the big forms and after the details, because proportions only show up when rendered.

Failure handling

• A tool error names the op that failed. Fix only that op and resend the corrected call; do not restart the drawing.
• If board_read shows the user changed something, treat their version as truth and build on it.
• If a call says the board could not be opened, do not retry with a different name. Tell the user which board you were using.
• If the Board is unavailable, describe the diagram in text.