vizzy directive reference

Inside a vizzy fence that directly follows a diagram or table, reference node and edge ids to annotate it — or use the id-less title / desc forms to label the card as a whole. A vizzy fence whose first line starts with architecture is instead a standalone architecture diagram.

Directive	Effect
`title <text>`	Title the whole card — no id. Useful for a table, which has no in-fence title line
`desc <text>`	A subtitle under the card’s title — describes the whole diagram or table (no id)
`desc <id>: text`	A one-line description under a node’s label or a group’s title
`note [over \| left of \| right of] <id>[,<id2>…]: text`	Attach a sticky note to one or more nodes (placement defaults to `over`)
`payload <A>-><B>: text`	Label what an edge carries
`style <id> fill:…,stroke:…`	Override a node’s Mermaid style (layers on top)
`hint <id>: [Title](dest)`	Attach a click-to-open info hint badge
`pos <id> x=320 y=40`	Pin a node’s or group’s position (its center)
`card x=N y=N`	Pin the whole diagram card’s position on the canvas (its top-left)
`labelpos <A>-><B>: 0.3`	Position an edge’s label at a fraction along the edge
`tablewidths 120 80 160`	Pin a Markdown table’s column widths in source-column order
`cellstyle <header> <op> <value>: <color>`	Conditionally tint a Markdown table’s matching cells
`side <id> left` / `right`	Pin a mind-map top-level branch to a side of the root
`phase <label>: <A->B> [color:…] [desc:…]`	A sequence swimlane band starting at message `A->B`
`frame <keyword> [condition] color:<token>`	Tint a sequence combined fragment’s tab, border, and dividers
`layout TB` / `LR` / `BT` / `RL`	Override flow direction (`layout split` / `unified` on a diff picks its view instead)
`collapse 8`	Fold a diff’s unchanged context runs longer than N lines into a pill

Notes

Which thing does a fence annotate? The block immediately above it — the nearest preceding diagram or Markdown table, blank lines and prose aside. It’s positional, so put the fence directly after its subject; one fence annotates one block.
title and id-less desc label the whole card, not a node. title <text> sets the card’s heading and desc <text> (no <id>:) a subtitle beneath it. This is how you give a table a heading and caption, since a table has no in-fence title line of its own.
desc works the same in an architecture fence (ids may be declared further down) and in an annotation fence after a Mermaid diagram. On a group/subgraph id it renders as a subtitle under the section’s title and the gray box grows to fit it; on a node id it renders as a small line under the label. Reach for it to title a whole section instead of pinning a note to one member node inside it.
note defaults to placing the sticky card over its subject; write left of or right of to place it beside instead. Comma-separate multiple ids (note over api,db: shared rate limit) to attach one note to several nodes at once.
Edges are addressed compactly as A->B in payload, hint, and labelpos.
labelpos stores a fraction (0 = source end … 1 = target end), so the label keeps the same spot along the line when nodes move and the edge re-routes — rather than a fixed point that drifts off. Omit it and the label auto-places near the middle.
side (mind map only) pins a top-level branch to the left or right of the root; unpinned branches auto-balance by leaf count around the pinned ones, then the tidy-tree re-layouts that subtree. You choose the sides — vizzy keeps each side neat.
hint also accepts a group/subgraph id — the badge sits beside the group’s title — and a timeline / journey / quadrant label. On a quadrant point the marker itself is the hover target, so no badge is drawn. Inline notes show an (i); file links show an open-arrow.
style uses Mermaid property syntax (fill:, stroke:, color:, stroke-width:, stroke-dasharray:) and merges on top of any styling from the mermaid fence — so a vizzy fence is how you tint nodes in non-flowchart diagrams. It also targets a timeline / journey / quadrant element by its label (e.g. style Campaign A fill:green colours one quadrant marker).
phase and frame are sequence-diagram only. phase draws a tinted swimlane band over a run of messages; frame colours a combined fragment (loop/alt/opt/…). Both take a color: palette token or #hex.
cellstyle (data tables only) color-codes body cells by content, so enums and statuses read at a glance: cellstyle Status = Done: green. The column is named by its header text (case-insensitive, spaces allowed); ops are = (exact) and contains (both case-insensitive text) plus > / < (numeric — $1,200 and 85% compare as numbers; non-numeric cells never match). The color after the final : is a palette token or #hex, drawn as a subtle wash behind the cell. Per cell, the first matching rule in fence order wins; rules match content, never row numbers, so they survive sorting, filtering, and rewrites. Quote a value containing a colon (cellstyle Time = "12:30": mint).
Directives are best-effort: an id that doesn’t match, or a malformed line, is ignored rather than breaking the diagram.

Example

```mermaid
flowchart LR
  web[Web] -->|POST /login| api[API] --> db[(Postgres)]
```

```vizzy
desc db: primary + read replica
note api: rate limited 5/min
style api fill:#DBEAFE,stroke:#2563EB,stroke-width:3px
hint api: [Rate limit]("Token bucket, **5/min**.")
hint api->db: [Schema](data.vizzy.md)
layout LR
```