byre/internal/agents/kb/diagrams.md

How to draw a box diagram (architecture, components, data flow) that byre's app renders in the transcript, with zoom and highlighting.

Box diagrams

A fenced block with the language diagram draws boxes in rows with arrows between them. The app lays it out itself, so you never place coordinates. Clicking it opens a full-size view: pinch or scroll to zoom and pan; clicking a box highlights it, its arrows and its neighbors; each highlight line becomes a button there. It is the only diagram format byre draws; a ```mermaid block shows as plain code.

row
  app "Byre.app" "REST + SSE · WebSockets"
row
  server "internal/server" "REST · SSE · WebSockets" blue
  aside store "internal/store" "byre.db, SQLite WAL" green
row
  manager "agents.Manager" amber
    coord "coordinator" "level-triggered"
    live "live sessions" "turn end: commit, snapshot"
app -> server
server -> manager "start · message"
manager -> store "writes"
store ..> server "events → SSE"
store ..> coord "poke"
highlight "Event loop" store server coord

• row starts a row; rows stack top to bottom. The boxes indented under it sit side by side, stretched to a common width.
• A box is id "Title" "detail line" ..., then optionally a color: blue, green, amber, red or plain (the default). The id is letters, digits, _ and -, unique in the diagram. Without a title the id is shown.
• A box indented under another box is its child; children sit side by side inside their parent, and nest to any depth.
• aside before a top-level box puts it in a column to the right of the rows, level with its row. Use it for shared state (a database, git) that many rows touch.
• a -> b "label" draws a solid arrow and a ..> b "label" a dashed one; the label is optional. Arrows route around boxes, and may end on a child or a parent.
• highlight "Name" id id ... names a set of boxes to light up together, with the arrows between them.
• Lines starting with # are comments. A mistake shows the source with the reason it wasn't drawn.

Keep each box to a title and one or two short detail lines, and draw only the arrows the reader needs; a picture with every dependency in it reads worse than prose.

Check a diagram before you send it: render_diagram takes the block's body and returns a PNG of what the app draws, or the reason it can't. Look for crossing or overlapping arrows and labels sitting on top of each other, and adjust the rows, aside or arrows until it reads cleanly.