Slide diagram

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

---
name: slide-diagram
description: Draw a diagram for the talk's slides — boxes-and-arrows explaining a mechanism (function calling, tool detection, MCP, an agent loop…) — in this deck's house style, as an SVG that draw.io can reopen and edit. Use whenever someone asks for a diagram, a schema, "un schéma", a drawing of a flow, or wants to change an existing `.assets/*.drawio.svg`.
---

# Slide diagram

Diagrams in this repository are **generated from a small JSON spec**, never hand-drawn:

```
<chapter>/.assets/<name>.json          the spec — the source of truth
<chapter>/.assets/<name>.drawio.svg    the output — embeddable in Marp, editable in draw.io
```

The renderer is `scripts/make-diagram.mjs` (in this skill). The SVG it writes carries the
mxfile in its `content` attribute, so draw.io opens it, and Marp/GitHub/browsers show it as a
plain SVG.

## Workflow

1. **Turn the explanation into a flow.** Name the actors (boxes) and what travels between them
   (arrows). Number the steps in the edge labels (`1.`, `2.`, …) whenever the order matters —
   the audience reads a slide in two seconds, the numbers do that job.
2. **Write the spec** as `<chapter>/.assets/<name>.json` (schema below). Start from
   `references/example.json`.
3. **Render**: `node <skill>/scripts/make-diagram.mjs <chapter>/.assets/<name>.json`
4. **Look at it — always.** Text overflow is the failure mode and it is invisible in the source:

   ```bash
   command -v rsvg-convert || sudo apt-get install -y -qq librsvg2-bin
   rsvg-convert -z 1 <name>.drawio.svg -o /tmp/check.png
   ```

   Then read `/tmp/check.png` with the Read tool and check: no text crossing a box border, no
   label sitting on top of another, every arrow head visible, nothing clipped by the canvas.
5. **Fix and re-render** until it is clean. Widen boxes, shorten wording, move a column right.
6. Report the file path and describe the flow in a few lines.

Grep the code the slide is about (`tools.go`, `main.go`, …) before naming things: use the real
tool names, the real model, the real arguments. A diagram that matches the demo output is worth
three that are merely plausible.

## Spec format

```json
{
  "name": "Tool detection",              // the draw.io page name
  "width": 1220, "height": 540,          // canvas, in px
  "nodes": [
    { "id": "llm", "x": 370, "y": 250, "w": 280, "h": 110,
      "label": "LLM (tool support)\\nDocker Model Runner", "kind": "dark" }
  ],
  "edges": [
    { "from": "user", "to": "llm", "label": "1. prompt +\\ntools[]" }
  ]
}
```

`\\n` in a JSON string (a literal backslash-n, *not* a real newline) is a line break.

**Node `kind`** — pick by role, not by taste:

| kind | look | use for |
|---|---|---|
| `box` | white, dark border, regular | the human, the calling program |
| `dark` | dark fill, white bold text | the LLM — always exactly one, it is the centre of gravity |
| `accent` | sage fill, bold | data or a tool the model is given: the catalog, a tool, a store |
| `intent` | white, blue border, blue bold | what the model *emits*: `tool_calls`, a JSON payload |
| `note` | dashed border, smaller regular | the one sentence the audience must leave with |

**Edge fields**: `from`, `to`, `label`, `dashed` (blue + dashed — reserve it for the tool /
model machinery, keep plain dark for the human-facing flow), `waypoints`
(`[{"x":…,"y":…}]`, absolute, for a return path routed around the boxes), and
`fromSide`/`toSide` (`"top" | "bottom" | "left" | "right"`) with optional `fromAt`/`toAt`
(absolute coordinate along that side). Use the sides when two boxes are stacked and linked
**twice** — otherwise both arrows leave from the same centre and cross.

Anything else about the palette, the sizing arithmetic and the standard layouts:
`references/style.md`. Read it before choosing box widths.

## Rules that keep the deck coherent

- **One spec, one SVG, same basename.** Never edit the `.drawio.svg` by hand.
- **Never regenerate a diagram someone has re-exported from draw.io** without saying so: their
  export replaces the file and the JSON no longer describes it (a draw.io-exported file starts
  with `<svg host="…"` and has a compressed `content`; ours starts with `<svg xmlns=…` and a
  readable one). Ask, or port the edits back into the JSON first.
- **English on the diagrams**, whatever language the conversation is in.
- The renderer is byte-stable: same spec → same SVG. Regenerating a chapter's diagrams should
  produce no diff.

## Embedding in a Marp slide

```markdown
![w:1000 center](.assets/tool-detection.drawio.svg)
```

Keep the canvas around 1000–1250 px wide: it lands at a readable size on a 1280×720 slide
without scaling the text into mush.