@meltemi/diagrams-cli 1.9.0 → 1.11.1

package/skills/meltemi-diagrams/reference/layout.md

@@ -0,0 +1,165 @@
+# Layout: modes, constraints, ports, coordinates, sizes, anchors, groups, frame
+
+## Modes
+
+| Mode             | Use it for                                   | Positions                                                     |
+| ---------------- | -------------------------------------------- | ------------------------------------------------------------- |
+| `auto` (default) | new sheets, quick drafts, generated diagrams | ELK arranges every box in the `direction`; `place` is ignored |
+| `assisted`       | a sheet where some boxes must stay put       | placed boxes stay; ELK places the others around them          |
+| `manual`         | conversions and pixel-exact sheets           | every box needs a `place`                                     |
+
+- ELK keeps the source order within each column, so declare boxes in reading order.
+- Primary arrows (`->`) are kept straighter than secondary ones (`-->`).
+- `pnpm mdg layout sheet.meltemi` writes the arranged positions into the file and switches `auto`
+  to `assisted`; `--all` arranges everything anew and writes the bends ELK draws as waypoints with
+  free ends, so the connectors look as they did in `auto`; `--check` only reports.
+
+## Constraints
+
+Constraints go in `placement` and hold in every mode. Placed boxes never move; free ones do.
+
+```text
+placement {
+  align api, orders, db top      // also bottom, left, right, middle, center
+  row client, api                // equal vertical centres
+  column api, cache              // equal horizontal centres
+  order a, b, c horizontal       // left to right in this order (axis defaults to direction)
+  distance api, db 80            // at least 80 px between the boxes
+}
+```
+
+If placed boxes break a constraint, `layout.constraint-conflict` names them and how far off they
+are; the sheet still renders.
+
+## Ports and connector shapes
+
+```text
+bus["Event bus"] {
+  port in west 30%
+  port out east
+}
+placement {
+  route publish from api.east to bus.in
+}
+style notify { routing bezier }
+```
+
+- A named port is an exact point on a side, 50 % along it by default; compass ports (`east`) only
+  choose the side.
+- `routing` is `auto` (anchor rules below, or ELK's routes in `auto` mode), `orthogonal`,
+  `polyline` or `bezier`; set it for the diagram or per relation in a `style`.
+- Two or more arrows between the same boxes are spread 16 px apart automatically.
+
+## Coordinates
+
+- Pixel units, origin at the top-left, y grows downwards. The canvas is computed from the content
+  plus a 20 px margin, so start wherever you like; coordinates from an existing SVG can be copied
+  as they are.
+- `place <id> at (x, y)` is the centre of the box. From a rectangle `x, y, w, h` the centre is
+  `(x + w/2, y + h/2)`.
+- Use a grid: multiples of 20 for centres, row pitch 70 to 90 px for 56 px boxes, column pitch of
+  the box width plus 40 px.
+
+## Sizes
+
+| Kind                  | Default                                                                | Give `size` when                                       |
+| --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ |
+| `node`                | 160 x 56, wider when its text needs it                                 | you want it larger than its text, or match an original |
+| `node` with `shape`   | the shape's size (free.md), grown until the text fits inside the shape | the same                                               |
+| `shape icon`          | 64 x 64 (or `iconSize`; 16 more when framed), the label outside it     | you want a larger icon; `iconSize 96` says it better   |
+| `iconPosition center` | 120 x 120, wider for a long label                                      | the same; a small `size` leaves no room for the icon   |
+| `decision`            | 160 x 80, grown until its text fits the diamond                        | the same                                               |
+| `data`                | 160 x 64, wider when its text needs it                                 | the same                                               |
+| `group`               | fits children + 16 px, 40 px top (16 px untitled), and title           | you want a band of a fixed size (then also `place`)    |
+| `tag`                 | text width + 18, height 18                                             | never, unless matching an original                     |
+| `note`                | longest line, 18 px per line                                           | never, unless matching an original                     |
+
+Text is measured with the bundled fonts (Inter, IBM Plex Sans, Cascadia Mono and the families a
+`font` names), at its `fontSize`, so boxes without `size` always fit their label and descriptions. A `size` that is too narrow is reported as
+`layout.text-overflow` with a hint that gives a width that fits: follow it. Aligned columns of boxes
+look best with one shared `size` that fits the longest label.
+
+Text layout inside a box: label centred; with a description the label moves up 8 px and the
+description sits 10 px below the centre; extra description lines add 16 px each (`\n`).
+
+## Arrows and anchors
+
+A relation without `route` uses `auto` ports on both ends. The exporter picks the side facing the
+other box and then:
+
+1. facing parallel sides (south to north, east to west) meet at the centre of the overlap of
+   their extents, so aligned boxes get straight arrows and a wide band under a box gets a vertical
+   arrow under that box;
+2. without overlap, each side uses its own centre (the arrow is diagonal: align the boxes or add a
+   waypoint);
+3. perpendicular sides get one elbow;
+4. with waypoints, each side anchors at the projection of its neighbouring waypoint, clamped to the
+   side;
+5. free ends that land less than 16 px apart on one side of a box spread 16 px apart (more for
+   labelled relations), ordered by where their other ends are; a straight arrow moves whole.
+
+Waypoint example, a line that leaves to the right and drops onto the top of a wide gateway:
+
+```text
+route ext from clients.east to gateway.north via [(1035, 48)]
+```
+
+On a decision, a data store, a tag or a node with a `shape`, the point found on the rectangle then
+slides along the side's normal onto the outline, so arrows touch the diamond, the cylinder's rim
+or the hexagon; `d.north 5%` still reads as a point of the north side.
+
+The polyline is 1.3 px with a filled 8 px arrowhead; `-->` and `line dashed` dash it, `line dotted`
+dots it, `<->` puts the head at both ends and `corners rounded` rounds its bends.
+
+## Relation labels
+
+`a -> b: "text" as r` draws a pill centred on the route at 50 % unless `label r at <n>% offset
+(dx, dy)` moves it. For vertical arrows use `offset (16, 0)`; for horizontal ones `offset (0, -16)`.
+Style the pill with `style r { fill "#0B1830"; color "#FFFFFF" }` for a dark step badge; one
+character labels become circles.
+
+## Groups
+
+```text
+group runtime "AgentCore Runtime" {
+  node a "Agent A"
+  node b "Agent B"
+}
+placement {
+  place a at (337, 358); size a (155, 56)
+  place b at (509, 358); size b (155, 56)
+  // runtime fits a and b, or:
+  place runtime at (510, 390); size runtime (540, 200)
+}
+```
+
+A group is drawn first (rounded band, radius 14, or its own `radius`) with its label at the
+top-left (20 px in, 18 px down) and an optional description under it. Children keep diagram
+coordinates. Nested groups work. Arrows may start or end at a group; the anchor rules treat it as
+a box. `group backend "" { ... }` (empty label, no description, no icon) is a plain container: no
+title, no 40 px band (the padding is 16 px all round), no gap cut in arrows; with
+`style backend { fill "#dae8fc"; radius 0 }` it is a flat coloured rectangle. A connector between
+two boxes of a group, or of a box they are stacked in, is never routed around that container.
+
+## Z-order
+
+Groups (outer first), then nodes, data, decisions and notes in source order, then relations with
+their labels, then tags, then the brand frame. A box declared after a box that holds it entirely
+is drawn over it and is not `layout.overlap` (a stack: declare the outer box first). Place tags on
+box corners (`place t at (x + w/2, y)` for the top-right corner) and they stay on top. With
+`layers back, main`, anything with `layer back` is drawn first and is not checked against the
+boxes of `main`.
+
+## Legend and notes
+
+- A legend is a row of tags under the sheet, each styled with a category's `fill`, `stroke` and
+  `color`; add a white dashed tag for "proposed" and a dark one for "brand label" if used.
+- Notes are left-aligned text blocks: `place` their centre; a 4-line note is about 72 px tall.
+
+## Frame
+
+With the default theme the exporter adds a 44 px footer: hairline, Meltemi mark, the `brand`
+text and the diagram `title`; the `stage.*` themes put a taller strip on top. Nothing inside the
+sheet changes. Use `theme "editorial.light"` or a file theme with `frame none` for a bare sheet
+(see themes.md). Sizes in this guide are those of the technical themes; the stage themes use larger
+type, so give explicit `size` values more room or leave them out.

package/skills/meltemi-diagrams/reference/sequence.md

@@ -0,0 +1,143 @@
+# Sequence diagrams
+
+Use `diagram <id>: sequence { }` for interactions over time: who calls whom, in what order, with
+which alternatives. Participants stand left to right in source order and events go top to bottom
+in source order. Never write `place`, `size` or `route` here; the layout is computed.
+
+## Participants
+
+`participant`, `actor`, `boundary`, `control`, `entity`, `database`, `collections` and `queue`,
+each `<kind> <id> "Label"`. `id["Label"]` is a participant and `id[("Label")]` a database. A
+message end that is never declared becomes a participant labelled with its id, placed at its first
+mention. `group backend "Backend" { participant api "API" }` draws a box around participants.
+
+## Messages and events
+
+```text
+customer -> api: "Pay" as pay          // call: solid, filled arrowhead
+api --> customer: "Receipt"            // reply: dashed, open arrowhead
+api -> events: "Paid" as paid { kind async }   // async: solid, open arrowhead
+api <-> cache: "Sync"                 // two-way: a head at both ends
+api -> api: "Validate"                 // self-call
+activate api                           // bar from the message before; deactivate ends it
+create order                           // the head appears at this row
+destroy order                          // the lifeline ends with a cross
+note over api, bank "Timeout 3 s"      // also: note left of api "…", note right of api "…"
+divider "Fulfilment"
+delay "Two days later"
+autonumber                             // numbers every message from 1 (autonumber 10: from 10)
+```
+
+A message label stays on one line and holds its two participants apart as far as it needs; a
+negative `gap` or a `spacing` below 40 pulls them closer than that by its amount, and the label then
+wraps at the room left between the lifelines, a taller row instead of a refused gap. Keep labels as
+sentences and never shorten them to fit. Write `\n` only for a break of your own
+(`"Authorize\nthe card"`). A self-call's label stays on one line beside its loop, broken only at
+`\n`. A pull stops where the heads or a label's longest word no longer fit.
+
+When a call causes other events, write them in the call's block and answer it with `return`: the
+receiver is active for the whole block (one bar, no `activate`/`deactivate` to balance), and
+`return` is the dashed reply to the caller.
+
+```text
+customer -> api: "Pay" as pay {
+  api -> bank: "Authorize" as authorize {
+    return "Approved" as approved   // bank --> api
+  }
+  note over api "Stores the receipt"
+  return "Receipt" as receipt       // api --> customer; nothing may follow it in this list
+}
+```
+
+A block may hold properties (`kind async`) beside its events, fragments may sit inside it and
+calls with blocks inside fragments. `return` outside a call is an error.
+
+## Tags
+
+```text
+participant bank "Bank" { tag "external" }   // a badge over the head
+api -> bank: "Authorize" as authorize {
+  tag "PKCE"                                 // pills on the arrow, next to the source
+  tag "v2"
+}
+```
+
+`tag "Text"` marks a message (calls, replies, self-calls, `return`) or a participant with a short
+word: a protocol, a version, a property. Write it in the owner's block, one line of text, several
+in order, no id; in a call's block it belongs to the call, beside its events. Never write it at
+the diagram level, in a group block or in a fragment (`prop.unknown`), never empty, and never the
+same text twice on one owner (`prop.duplicate`). `tag <id> "Text"` is the flow profile's pill and
+is refused here. Tags take the theme's `tag` colours; there is no `style` or `rule` for them.
+
+## Fragments
+
+```text
+alt result "Approved" {
+  bank --> api: "OK"
+} else "Declined" {
+  bank --> api: "Declined"
+}
+opt coupon "Coupon applied" { … }
+loop polling "Until shipped" { … }
+par { … } and "Notify" { … }
+break "Fraud" { … }
+critical "Shipment" { … } option "Carrier down" { … }
+region "Audit" { … }
+```
+
+Write `else`, `and` and `option` on the line of the closing `}`. Give a fragment an id (`alt
+result …`) when a scenario or `space` must name it. Fragments hold events only: declare every
+participant at the diagram level first.
+
+## Scenarios
+
+```text
+scenario approved "Payment approved" {
+  choose result "Approved"   // or: choose result 1
+  repeat polling 3           // 1 to 100 passes
+  skip coupon                // opt or break not taken; take coupon keeps it (the default)
+}
+```
+
+`pnpm mdg export sheet.meltemi --scenario approved` writes `sheet.approved.svg` with only that
+path; without `--scenario` every branch is drawn.
+
+## Spacing and styles
+
+```text
+spacing 56                // distance between neighbouring heads, before gaps (40 by default)
+placement {
+  space authorize 28        // more room above a named message, note or fragment
+  space settled 20 after    // or below it (the last event lengthens the lifelines)
+  gap bank 40               // more room left of a participant
+  gap ledger 24 after       // or right of it
+  gap api -12               // a negative gap brings it closer, its labels wrapping, down to the heads
+  label pay at 50% offset (0, -4)
+}
+style result { stroke accent }   // notes and fragments with ids take styles
+rule fragment { stroke muted }
+```
+
+## Diagnostics
+
+| Code                  | Fix                                                                          |
+| --------------------- | ---------------------------------------------------------------------------- |
+| `sequence.activation` | `deactivate p` without an open `activate p`: add the `activate` or remove it |
+| `sequence.return`     | `return` outside a call's block, or an event after the `return`: move it     |
+| `sequence.lifecycle`  | an event after `destroy`, `create` after the participant appeared, or twice  |
+| `layout.gap-floor`    | (warning) a negative `gap` below what heads, words or tags need: drawn wider |
+| `prop.invalid-value`  | a negative `gap` on the outer side, or `space`; `tag ""` or `tag id "x"`     |
+| `prop.duplicate`      | the same `tag` text twice in one block                                       |
+| `sequence.scenario`   | the scenario names an unknown fragment, branch or loop count                 |
+| `ref.unknown-element` | declare the participant (`participant x "X"`); groups are not participants   |
+| `prop.unknown`        | a flow or free kind (`node`), a declaration in a fragment, a stray `tag`     |
+
+Branches of `alt`, `par` and `critical` are checked separately, each from the state before the
+fragment; the first branch's state continues after it. Activations open at the end are fine.
+
+## Converting
+
+Import Mermaid and PlantUML sequences with `pnpm mdg import`, which maps them one to one: `participant`/`actor` (and the
+PlantUML kinds), `->>` and `->` to `->`, `-->>` and `-->` to `-->`, `-)` to `-> … { kind async }`,
+`+`/`-` suffixes to `activate`/`deactivate`, `Note over A,B: text` to `note over a, b "text"`,
+`rect`/`group` to `region`, `box` to `group`, `== x ==` to `divider "x"`, `...` to `delay`.

package/skills/meltemi-diagrams/reference/stories.md

@@ -0,0 +1,94 @@
+# Stories
+
+A `story` tells a diagram step by step for a walkthrough, a talk or a recorded demo. It never
+changes the diagram: scenes reveal, hide, highlight, focus, frame, trace and draw parts of it on one
+deterministic clock, and may switch to another view of the same system. Write the diagram first,
+then the story below it (or in another file that imports the diagram).
+
+```text
+story purchase for checkout {
+  title "A purchase"
+
+  scene overview {
+    reveal client, api, orders, db over 800ms
+    hold 1s
+  }
+
+  scene processing {
+    trace request over 1200ms
+    parallel {
+      trace save over 1200ms
+      highlight db over 1200ms
+    }
+    hold 2s
+  }
+}
+```
+
+## Vocabulary
+
+| Statement                                   | Default | Meaning                                                                                                                    |
+| ------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `scene <id> ["Title"] { ... }`              |         | a step; scenes run one after the other                                                                                     |
+| `view <diagram>`                            |         | first in a scene: the diagram it shows from now on                                                                         |
+| `transition cut\|fade\|morph [over <time>]` | 800 ms  | needed when the view changes; `morph` moves boxes with the same id, `cut` takes 0                                          |
+| `reveal a, b [over <time>]`                 | 600 ms  | fades in; targets first revealed start hidden                                                                              |
+| `hide a, b [over <time>]`                   | 600 ms  | fades out                                                                                                                  |
+| `highlight a [over <time>]`                 | 1 s     | accent outline for the action's time                                                                                       |
+| `focus a, b` / `focus all`                  | 600 ms  | dims the rest to 25 % until the end of the scene; `all` clears it                                                          |
+| `camera a, b` / `camera all`                | 800 ms  | frames the targets plus 40 px; `all` frames the whole view                                                                 |
+| `trace r [over <time>]`                     | 1.2 s   | draws one named relation from source to target in the accent colour                                                        |
+| `draw a, b [over <time>]`                   | 800 ms  | replays pens, free lines and named relations as drawn, one after another, and keeps them; targets first drawn start hidden |
+| `hold <time>`                               |         | waits                                                                                                                      |
+| `parallel { ... }`                          |         | actions that start together; lasts as long as the longest                                                                  |
+
+Targets are ids of the scene's view: elements, named relations (`as <id>`), named notes and
+fragments; entity paths (`shop.api`) in C4 views. Times are `800ms` or `1.5s`, up to `600s`.
+
+## Rules that save iterations
+
+- Name every relation you want to trace: `api -> db: "SQL" as save`.
+- A whiteboard's explanation is a `draw` of its pens in the order they were written
+  (`draw title, arrow over 2s`): each takes a share of the time proportional to its length, in its
+  own colour, and stays drawn ([free.md](free.md#pen-strokes)).
+- Reveal everything that should appear; anything never revealed is visible from the start. An
+  arrow appears with its two ends, so reveal the boxes, not the relations.
+- Two actions on the same target and channel must not overlap (`story.conflict`): put a `reveal`
+  and a `hide` of the same box in sequence, not in one `parallel`.
+- A change of `view` needs a `transition` (`story.missing-transition`); use `morph` between views
+  that share ids (two C4 views of one model), `fade` otherwise.
+- Keep scenes short (a few seconds) and end the story with a `hold` so the last state stays.
+
+## Diagnostics
+
+| Code                       | Fix                                                                           |
+| -------------------------- | ----------------------------------------------------------------------------- |
+| `story.unknown-diagram`    | the diagram after `for` or `view` is not in the file or imported              |
+| `ref.unknown-element`      | the target is not an id of the scene's view; use the suggested id             |
+| `story.invalid-target`     | `trace` needs a named relation; `draw` a pen, a free line or a named relation |
+| `story.missing-transition` | add `transition cut`, `fade` or `morph` after `view`                          |
+| `story.conflict`           | two overlapping actions on one target and channel; sequence them              |
+| `story.empty-scene`        | warning: give the scene an action or remove it                                |
+| `prop.invalid-value`       | a time without `ms` or `s`, beyond 600 s, or a statement out of place         |
+
+## Checking a story
+
+```bash
+pnpm mdg validate path/to/sheet.meltemi
+```
+
+```bash
+pnpm mdg export path/to/sheet.meltemi --story purchase --at 2.4s
+```
+
+`--story` writes `<stem>.<story>.svg`: the end of the story, or the frame at `--at`. Export a few
+instants (the start of each scene, the middle of a trace) and look at them; the canvas in VS Code
+plays the story with a timeline.
+
+To share the story, write its HTML player, an offline page with pause, progress, scenes, reduced
+motion, a static view, a text summary, zoom, hover cards and a detail panel (`--embed` writes a
+fragment for an existing page):
+
+```bash
+pnpm mdg export path/to/sheet.meltemi --story purchase --format html
+```

package/skills/meltemi-diagrams/reference/themes.md

@@ -0,0 +1,148 @@
+# Themes and styles
+
+A theme sets palette, type, spacing, strokes, arrowheads and the brand frame. The diagram picks it
+with `theme "<name>"`; a project can set a default in `project.json`
+(`"theme": "themes/company.meltemi#corporate"`); `meltemi-diagrams export --theme <name>`
+overrides both.
+
+## Built in
+
+| Name                        | Use it for                | Look                                                                |
+| --------------------------- | ------------------------- | ------------------------------------------------------------------- |
+| `technical.light` (default) | architecture review       | Sea Mist background, Inter, Aegean tags, footer with the mark       |
+| `technical.dark`            | architecture review, dark | Meltemi Night background, cyan tags, footer with the mark           |
+| `editorial.light`           | documents, long reading   | white sheet, IBM Plex, quiet greys, open arrowheads, no frame       |
+| `editorial.dark`            | documents, dark           | dark neutral sheet, IBM Plex, no frame                              |
+| `stage.light`               | slides and video          | high contrast, 16 px labels, 2 px connectors, 48 px margins, header |
+| `stage.dark`                | slides and video, dark    | the same on a near-black background                                 |
+| `sketch.light`              | whiteboards, early ideas  | technical light with strokes painted by hand and rounded bends      |
+| `sketch.dark`               | whiteboards, dark         | the same on the technical dark palette                              |
+
+Explicit quoted colours in styles are kept in every theme, so category colours of a sheet survive
+a theme change. Colour token names (`stroke danger`, `fill surface`) follow the theme instead.
+
+## Theme blocks
+
+```text
+theme acme {
+  extends "technical.light"
+  accent "#6a4fd0"            // start of the mark gradient
+  accentEnd "#a594f0"         // end of the mark gradient
+  tag "#6a4fd0"               // tag pill fill
+  band "#f6f3fe"              // group fill
+  bandLine "#6a4fd0"          // group outline
+  brand "Acme · Meltemi Diagrams"
+  frame footer                // none | footer | header
+
+  class partner { line dashed; stroke accent }   // reusable styles for every diagram
+  rule data { pattern dots }                     // every data store
+}
+
+diagram platform: flow {
+  theme "acme"
+  ...
+}
+```
+
+Tokens (numbers without a unit or with `px`):
+
+| Tokens                                                                                                                    | Value                                             |
+| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `background`, `surface`, `ink`, `muted`, `line`, `connector`, `band`, `bandLine`, `tag`, `tagText`, `accent`, `accentEnd` | quoted colour                                     |
+| `success`, `warning`, `danger`, `info`                                                                                    | quoted colour (signals)                           |
+| `highlight`, `sticky`, `stickyText`                                                                                       | quoted colour (highlighter strokes, stickies)     |
+| `font`, `mono`                                                                                                            | quoted font stack; name a bundled family          |
+| `labelSize`, `descriptionSize`, `groupTitleSize`, `noteSize`, `tagSize`, `relationLabelSize`, `frameSize`                 | 6 to 48 (technical: 13, 11, 13, 11, 10.5, 11, 12) |
+| `labelWeight`                                                                                                             | 400, 500, 600 or 700                              |
+| `padding`, `groupPadding`, `groupHeader`, `margin`                                                                        | 0 to 200 (technical: 16, 16, 40, 20)              |
+| `radius`, `groupRadius`                                                                                                   | 0 to 64 (technical: 8, 14); defaults of `radius`  |
+| `strokeWidth`, `connectorWidth`                                                                                           | 0 to 8 (technical: 1, 1.3)                        |
+| `arrowhead`, `arrowSize`, `corners`                                                                                       | a head (language.md); 0 to 32; `sharp`, `rounded` |
+| `sketch`                                                                                                                  | `none`, `light`, `rough`: strokes painted by hand |
+| `frame`, `brand`, `mark`                                                                                                  | `none`/`footer`/`header`; text; `meltemi`/`none`  |
+| `flowDuration`, `dashDuration`, `pulseDuration`, `traceDuration`                                                          | `100ms` to `60s`; default speed of each effect    |
+| `selection`, `guide`                                                                                                      | colour of the canvas's selection and guides only  |
+
+A theme without `extends` inherits from `technical.light`. Share a theme between files with an
+import (`import corporate from "../themes/company.meltemi"`) or make it the project default.
+
+Bare sheet with the Meltemi palette:
+
+```text
+theme bare { extends "technical.light"; frame none }
+```
+
+Company wordmark without the Meltemi mark:
+
+```text
+theme acme { frame header; mark none; brand "Acme Architecture"; font "Merriweather" }
+```
+
+The bundled families, which every export measures, embeds and outlines: sans Inter, IBM Plex
+Sans, Roboto, Open Sans, Lato, Montserrat, Poppins, Nunito; serif Merriweather, Lora, Playfair
+Display; mono Cascadia Mono, Roboto Mono, Source Code Pro; handwriting Patrick Hand, Caveat,
+Comic Neue. A system family (`Georgia`, `Arial`) is measured with estimates
+(`layout.unmeasured-font`) and left to the viewer.
+
+A whiteboard look: `theme "sketch.light"`, or `sketch rough` in a theme block
+(`theme hand { extends "technical.light"; sketch rough }`). Every outline, connector, head, pill
+and band is drawn twice with a small seeded wobble; text, icons and images stay crisp, the layout
+is unchanged and the same file always renders the same bytes. `sketch` is a theme token only:
+`style a { sketch rough }` is `prop.unknown`. Name relations whose wobble must not move when
+statements are reordered (anonymous keys change with the order).
+
+## Classes, rules and patterns
+
+```text
+diagram platform: flow {
+  class hot { stroke danger; width 2 }
+  rule relation { arrowhead open }
+  api["API"] { class hot }
+  legacy["Legacy"] { class deprecated }        // built in: hatch, muted
+  proxy["Proxy"] { class proposed }            // built in: dashed, warning colour
+  style db { class critical; fill "#fff" }
+}
+```
+
+- Built-in classes: `highlight`, `critical`, `proposed`, `deprecated`, `external`.
+- Order: theme tokens, theme rules, diagram rules, classes (declaration block, then `style`
+  statements), explicit `style` properties. The last value wins.
+- `pattern hatch|dots|cross` marks state without relying on colour; use it with a legend.
+- `width` sets an outline, connector or pen stroke width (0 to 64); `arrowhead` and `arrowtail` a
+  relation's, a free line's or a pen's heads at the target and the source; `line dotted` dots it;
+  `corners rounded` rounds its bends. `opacity 0..1` fades free elements, groups, lines and pens.
+- The whiteboard tokens: `stroke highlight` colours a highlighter stroke, and stickies take
+  `sticky` and `stickyText` (`#fff59d` and `#1f2328` on light themes); pens take `ink`.
+- The theme's `radius` and `groupRadius` are only defaults: `style api { radius 0 }` squares one
+  node, `rule group { radius 0 }` every group, and a class may carry `radius` too. Square corners
+  everywhere: `theme square { extends "technical.light"; radius 0; groupRadius 0 }`.
+- `rule node { shape hexagon }` (or `rule box`) gives every node a shape; rules for other kinds
+  cannot set `shape`.
+- An unknown class is `theme.unknown-class` (warning) in `validate`.
+
+## Icons
+
+- `style api { icon "tabler:server" }` draws a Tabler icon; classes and rules carry icons too
+  (`rule data { icon "tabler:database" }`). Provider sets are built in: `aws:lambda`,
+  `azure:virtual-machine`, `gcp:cloud-run`, `kubernetes:pod`, `logos:postgresql`; find names with
+  `pnpm mdg assets icons <word>`.
+- Search names with `pnpm mdg assets icons <words>`. An unknown name is `asset.unknown-icon` in
+  `validate`, with close names in the hint.
+- Project packs live in `assets/icons/` (Iconify JSON or a folder of SVG files) and need a licence
+  in `assets/licenses.json`. `pnpm mdg assets list` shows every pack and its licence.
+- `iconSize` and `iconPosition` are theme tokens; the stage themes put icons above the label.
+  `iconColor accent` colours monochrome icons; provider icons keep their colours.
+- Per element, `iconPosition left|right|top|bottom|center` places the icon (`center`: the picture
+  of the box, its label at the `labelPosition` edge), `iconSize 32` or `auto` sizes it (8 to 128),
+  and `shape icon` draws the element as its icon with the label outside (free.md).
+
+## Presets
+
+- `preset document`: warns above 1,200 px wide.
+- `preset slide`: a 16:9 canvas, warns above 1,920 × 1,080 px. Pair it with a `stage.*` theme.
+- `preset board`: the canvas grows with the content and never warns; for whiteboards and kanban
+  boards.
+- `canvas (1280, 720)`: a fixed canvas with the content centred.
+
+`layout.too-large` means the diagram should be split into views, not shrunk, or that a whiteboard
+needs `preset board`.

package/templates/kanban/diagrams/board.meltemi

@@ -0,0 +1,57 @@
+language "0.2"
+
+// A kanban board: a row of three columns, and in each column a list of sticky cards. The lists
+// place the cards in the order they are written, so moving a card is moving its line: drag it to
+// another column on the canvas, or cut its declaration and paste it in another group below. The
+// board grows with its cards (preset board).
+diagram board: free {
+  title "Team board"
+  theme "technical.light"
+  preset board
+  layout manual
+
+  text heading "Sprint 12"
+  text goal "Goal: a checkout that takes one page"
+
+  group columns "" {
+    layout row
+    align stretch
+    spacing 40
+
+    group todo "To do" {
+      layout column
+      spacing 12
+      sticky invoices "Send invoices as PDF"
+      sticky search "Search the catalogue by colour"
+      sticky reviews "Show reviews on the product page"
+    }
+
+    group doing "Doing" {
+      layout column
+      spacing 12
+      sticky checkout "One-page checkout"
+      sticky cache "Cache the catalogue"
+    }
+
+    group done "Done" {
+      layout column
+      spacing 12
+      sticky signin "Sign in with Google"
+    }
+  }
+
+  checkout -> signin: "needs" as needs
+  search --> cache: "waits for" as waits
+
+  placement {
+    place heading at (384, 50)
+    place goal at (384, 90)
+    place columns at (384, 424)
+  }
+
+  style heading { fontSize 32; fontWeight 700 }
+  style goal { color muted }
+  style invoices { fill "#bbdefb" }
+  style cache { fill "#bbdefb" }
+  style signin { fill "#bbdefb" }
+}