---
name: using-whiteboard
description: Read, build or edit boards in Whiteboard (formerly Flow Builder) through its linked local folder. Use for flowcharts, wireframes, database schemas, diagrams, layouts, connectors, text, notes, images, links, YouTube videos, audio and video files, API endpoints, PDF documents, Markdown files or authored Markdown content, frames, drawings, tables, lists, task cards and task lanes, sticky lanes and sticky pads. Also use when asked to draw or map a process without naming the app, or to read a board as the reference for implementation. Supplies the board format, folder discovery and board.py commands while preserving concurrent user edits. Do not use it to change Whiteboard's own source code.
---

# Using Whiteboard

Whiteboard keeps every board as a JSON file in a folder the person linked in its Settings. The app
reads that folder about once a second while it is open: a file you change is joined into the board
the person sees, item by item, while they keep working on it. **The files are the source of truth**:
edit them, and the board follows.

`scripts/board.py` does the fragile parts: finding the folder, showing a board, checking it, laying it
out, and adding pictures and drawings. Run it with `python3`; its path, like every path to `scripts/`
here, is inside this skill's own folder. Every command that writes replaces the
whole file at once, so the app never reads half a file.

## 1. Find the folder

```sh
python3 scripts/board.py find
```

It prints each folder holding an index, `flow-builder.json` (the name the app still writes, so a machine on
Flow Builder keeps reading the folder) or `whiteboard.json`; `WHITEBOARD_FOLDER` names one directly.
None found means no folder is linked, or it is somewhere unusual: ask the person for the folder they
chose in Settings. More than one: ask which. Remember the answer for the rest of the work.

## 2. Read the index, then the board

The index lists every project's subfolder and every board's file, and `problems`: each file
the app could not read, with the reason. A board lives at `<folder>/<project folder>/<board file>`.
The app rewrites the index as it reads the folder, so when the two disagree, the files in the folder
are right: list the folder, and trust the index again once the app has run.

```sh
python3 scripts/board.py show "<folder>/shop-redesign/checkout-flow.json"
```

`show` prints one line per item: its id, kind, position, size and words, and every link as
`from.port -> to.port`. That outline is how you see the board; open the JSON when you need a field
it leaves out.

## 3. Edit the board

**Read the file right before you change it, and write it once.** The person may be moving shapes
on the same board. The app keeps every item only one side changed, and gives an item you both
changed to whichever write came last. An edit made from a copy read minutes ago is joined against
that older version, so the person's newer work survives. But an item you rewrote without meaning to
still counts as your change.

- Change only the items the request names, and keep every field you did not mean to change. Never
  reformat or re-sort the file: the app writes it back in its own order.
- Keep every existing `id`. Give a new item a short id that is unique on the board, such as `s7`.
- **Keep `board.revision` exactly as you read it.** It names the version your edit started from, so the
  app joins your edit against exactly that version, and changes you did not make are never taken for yours.
  A file with no revision yet, one the app has not written, needs none.
- To add items, run `board.py add <file> '<item or list of items as JSON>'`. It refuses, writing nothing,
  when an item would break a rule `check` names, such as an id already used or a link to a missing item.
- Items are drawn in list order, so a later item is drawn on top.
- To start a new board, run `board.py new "<folder>/<project folder>" "<Board name>"`. A project folder
  that does not exist yet is made, and becomes a new project named by `--project "<Project name>"`, or
  by the folder's name without it. The app names a new project from the board file's `project.name`, and
  from its folder only when the file names none. `new` does not touch the index: the app adds the project and board
  to it when it reads the folder.
- **To copy a board**, copy its file under a new name and remove `board.id` and `board.revision` from the
  copy, so the app makes it a new board. A word-for-word copy beside the original is taken for a leftover
  and removed.
- **Delete only when asked.** Removing a board's file deletes the board, and removing a project's
  folder deletes the project and every board in it.

Read [Board format](references/board-format.md) for every item type, its fields and its allowed
values before you write an item type you have not written in this task.

**To gather part of a board, such as one screen or one stage of a process**, put a `frame` around it:
a titled box that holds the items naming it in `parent`. Place each item wholly inside the frame's box and
set its `parent` to the frame's id; remove `parent`, and place it outside, to take it out. An item lying
inside the box with no `parent` is not in the frame. A `screen` holds its parts the same way. The person
moves, deletes and cuts a frame with everything it holds, `board.py show` lists what each frame holds, and
`board.py check` flags a `parent` that is wrong.

**Names.** Say what the app shows the person, and write what the file holds. The app's `Task lane` is a
`task-list` in the file, its `Sticky lane` a `note-lane`, its `Sticky pad` a `note-pad`, and its `Sticky note` a
`note`; `task-list` keeps its older name in files so every machine reads them, while the app and the person say task
lane.

**A sticky pad** (`note-pad`) is a stack of 200 × 160 sticky notes in one `fill`, inside a fixed 220 × 190 holder.
Its editable `title` sits above the holder and defaults to `Sticky pad`; optional `bold` ranges style that title. The app draws that footprint even if a file gives an older size. The person drags a note off it,
in its color, and moves it by its glue strip; it holds nothing and takes no connector. To give the person more notes
of a color, add a `note` with that `fill` rather than changing a pad.

**To write a to-do list** (a task lane), use the task commands, which lay each list out exactly as the app does:

```sh
python3 scripts/board.py tasks <file> "Launch" --at 0,0 --task "Write notes" --task "[x] Ship" --color blue
python3 scripts/board.py task <file> list1 "Book the room" --before task2   # or --top; the bottom without either
python3 scripts/board.py done <file> task1                                  # --undo to uncheck
python3 scripts/board.py move-task <file> task3 --top                       # sort within its list
python3 scripts/board.py move-task <file> task3 --to list2 --before task7   # into another list
python3 scripts/board.py move-task <file> task3 --out --at 600,0            # out onto the board
python3 scripts/board.py stack <file>                                       # relay every list after a hand edit
```

A `task-list` holds every `task-card` whose middle lies inside its box, in order from top to bottom, by position alone; nothing on a card names its
list, and a card never takes a `parent` for it. A new card takes the default look, never its list's, as
in the app. `show` lists each list's cards in order and how many are done. Never lock a card in a list: a locked
card leaves the list's column and count.

**A sticky lane** (`note-lane`) holds sticky notes in a grid of rows and columns: every `note` whose middle
lies inside its box, or up to 80 past its right or bottom edge. Each note keeps its own size. Place a note's middle
in the row and column it belongs in, a new row under the last or a new column right of the last, then run
`board.py stack <file>`, which lays every task list and sticky lane out as the app does; `show` lists each sticky
lane's notes. `"columns"` and `"rows"` of `"1"` to `"24"` fix its grid and, both set, cap how many notes it holds; a
lane with `"layout": "messy"` tilts its notes, and `stack` sets each note's tilt as the app does.

**To write a list**, such as the values of an enum, run `board.py list`. Each `--item` is a name, or
`name=value` for an item with a value on its right:

```sh
python3 scripts/board.py list <file> order_status --at 0,300 --item "pending=0" --item "shipped=1" --item "returned"
```

The list's id is its name and each item's is `<list>.<item>`, such as `order_status.pending`. A `list` holds
every `list-item` whose middle lies inside its box, top to bottom, by position alone, as a table holds its
fields. To sort items or move one to another list, rewrite their places: the list's first item sits 40 below
its top, each next one 30 lower, each at the list's `x` and `width`, and the list is `40 + 30 × items + 30`
tall. A connector joins a list item on its `left` or `right` only, such as a `db-field` to the values it
takes. `show` lists each list's items in order and each item's value.

**To write a table** of columns and rows, run `board.py data-table`. Each `--column` names a column, left to
right, at most 20, and each `--row` gives a row's cells split at `|`:

```sh
python3 scripts/board.py data-table <file> People --at 0,600 --column Name --column Age --row "Zoe|10" --row "Adam|9"
```

The table's id is its name in lower case, its columns' ids are their names the same way, and its rows are `r1`,
`r2` and on. Rows stay in the order written. To show them sorted, set `sortColumn` to a column's id, and
`sortOrder` to `desc` for Z to A. Every table shows 25 rows and scrolls the rest; set `rowsShown` to `all`, `50`,
`100`, `250` or `500` for another number. A connector joins a row with `"part": "<row id>"` on its end, at the
row's `left` or `right`, such as `{ "item": "people", "port": "right", "part": "r2" }`. `show` prints each table's
columns, rows, sort and rows shown, and a row's link end as `table.row.side`.

**To make a table from a CSV file**, run `board.py data-table <file> People --at 0,600 --csv people.csv`. The file
goes into the linked folder's `files/`, named by the SHA-256 of its bytes, before the board file names it, as a
picture goes into `images/`. The table is named after the file, `.csv` and all. It reads its columns from the
file's first line, at most 20, with any blank one called `Unnamed`, and its rows from the file, sorted by its first
column unless `sortColumn` names another. The board holds none of the rows, and they are read-only. Such a table
takes connectors as a whole only, never on its rows. Never edit or rename a file in `files/`: a changed file no
longer matches its name.

## 4. Build a flowchart

1. Write the items without `x` and `y`: a `shape` per step (`terminal` for start and end, `process`
   for an action, `decision` for a question, and the other kinds as the Shapes table in
   [Flowcharts](references/flowcharts.md) says), and a `connector` per arrow, with `from` and `to` naming
   item ids. **Words about an arrow, such as a branch's `Yes` or `No`, go on the connector** as
   `"labels": [{ "text": "Yes", "at": 0.5 }]`, which the app draws in a small box on the middle of the
   line. They never go in a separate `text` item placed near the line, which stays put when the line moves.
2. Run `board.py layout <file>`. It places every item with no position top to bottom along its links,
   below whatever is already on the board, and gives links their ports.
3. Run `board.py check <file>`. It exits 1 and names each problem the app would refuse, or draw as
   broken: an id used twice, a link to a missing item, or a value outside its allowed set. Fix each
   one, then run it again.

Read [Flowcharts](references/flowcharts.md) before building a chart: good and bad examples of steps,
branches, labels and loops. Read [Wireframes](references/wireframes.md) before laying out a screen or a
page from a `screen` and its `wireframe` parts, or before building a layout from one, [Database schemas](references/database-schemas.md) before designing or drawing tables
and their relationships, [API endpoints](references/api-endpoints.md) before planning an API or drawing an endpoint
card and joining its fields to columns, and [Hand drawing](references/hand-drawing.md) before marking up a board with
circles, crosses, arrows or underlines. Read [Layout](references/layout.md) to place, size, align, space or turn
items by hand, to route a link, or to lay a chart out left to right.

## 5. Add a picture or a drawing

```sh
python3 scripts/board.py image <file> picture.png --x 400 --y 0 --width 320
python3 scripts/board.py draw  <file> --points "0,0 40,30 80,0 120,30" --color blue
```

`image` names the picture by its content, writes it into the linked folder's `images/`, and sizes the
image to the picture's proportions. `draw` turns points in board units into a freehand line, and `--shape` draws a
circle, cross, arrow, underline, check or wave, as [Hand drawing](references/hand-drawing.md) shows.

**To see a picture already on a board**, write it out and open the file it prints:

```sh
python3 scripts/board.py picture <file> <image item id>
```

A table made from a CSV file reads it from `files/` the same way, as `files/<id>.csv`. A picture lives in the
linked folder's `images/`, one file each, named by the image item's `image`
field and its type, such as `images/<id>.png`; the board file names it and never carries it. **Write the
picture file before the board file that names it**, and never rename or edit one: its name is the SHA-256
of its bytes. The app's own exports are zips, the file and an `images/` folder beside it; a board file outside
the linked folder may carry its pictures as base64 under `images`, the older form, which the app still reads. `show` lists each image item with its
picture's type.
`picture` writes it to a temporary folder, outside the linked folder, so the app never takes it for a
board.

## 6. Add PDF, Markdown, audio or video files

A PDF uses a `pdf` item naming its original bytes in `files/<SHA-256>.pdf`. Write the PDF first and add
the item with `board.py add`; [Board format](references/board-format.md) lists its default page and display
fields. `show` names its file and default page, and `check` names a missing source or an invalid page.

A Markdown document uses a `markdown` item with its UTF-8 bytes in `files/<SHA-256>.md`; an edit, in the app or
yours, is new bytes under a new hash.
Write the source file first, then add the item with `board.py add`; [Board format](references/board-format.md)
lists its source fields and size limit. `show` names the document and `check` names a missing or invalid source.

An MP4 or MOV uses a `video` item and an MP3 an `audio` item, naming the file it copies into `files/` under 64
random hex characters and its extension. Copy the file first, never move the person's own, then add the item with
`board.py add`; [Board format](references/board-format.md) lists its fields. A YouTube address is a `youtube` item
holding only `url`.

For a file or newly authored Markdown content, follow [Documents](references/documents.md). It gives the
source-first workflow, concrete item examples, PDF default pages, and preview versus file-card displays.

## 7. Confirm it landed

Run `board.py wait <file>`. It exits 0 once the app has taken the file in and written it back, and 1
after ten seconds without that. `board.py check` passing says only that the file is well formed, not
that the app has read it. Then read the index and the file again.

- **`wait` exits 1**: the app is closed, or linked to another folder. Your edit is
  safe in the file, and the app takes it in the next time it opens with this folder. Say so, and ask the
  person to open Whiteboard, or to check which folder its Settings name.

- **The app writes the file back in its own form**, with sorted keys, its ids filled in, and any
  change the person made meanwhile. A file named unlike its board is renamed to match the board's
  name: find it again through the index.
- **A file listed under `problems` was not taken in.** Fix what the message names. Until the file
  reads again, the board keeps its last good version.
- Report what you changed in the person's words, and say which board, so they can look.

## Traps

| Symptom | Cause | Fix |
|---|---|---|
| A shape is drawn as a plain box | an unknown `shape` value, such as `start`, `io` or `offpage` | `terminal`, `input-output`, `off-page` |
| An item sits higher than intended | `y` grows downward | a larger `y` is lower on the board |
| A turned item is misplaced | `rotation` turns about the center, in degrees clockwise | set `x`, `y`, `width` and `height` for the unturned box |
| A drawing is squashed or tiny | `points` are fractions from 0 to 1 of the drawing's box, not board units | use `board.py draw` |
| A link is not drawn | an end names a missing item, a drawing, or the same item at both ends | `board.py check` names which |
| The person's edit vanished | the whole board was rewritten from a stale read | read the file again, change only the items asked for |
| An edit is not on the board | the file did not read, and the index lists it under `problems` | fix the named problem |
| A branch label floats off its line | the words were written as a `text` item beside the line | put them in the connector's `labels` |
