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. Mermaid flowcharts (```mermaid) still work for graphs whose shape the layout should find on its own.

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.