vizzy directive reference

A vizzy fence that directly follows a diagram or table annotates it. Reference node and edge ids, 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 title line of its own
`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 block does a fence annotate? The block directly above it: the nearest preceding diagram or Markdown table, ignoring blank lines and prose. 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. Use this to give a table a heading and caption, since a table has no 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. Use it to title a whole section instead of pinning a note to one node inside it.
note places the sticky card over its subject by default. Write left of or right of to place it beside the subject instead. Comma-separate multiple ids (note over api,db: shared rate limit) to attach one note to several nodes at once.
Edges are written 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. Omit it and the label is placed automatically near the middle.
side (mind map only) pins a top-level branch to the left or right of the root. Unpinned branches balance by leaf count around the pinned ones, then the tidy-tree layout arranges that subtree.
hint also accepts a group/subgraph id (the badge sits next to 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. This is how you color nodes in non-flowchart diagrams. It also targets a timeline / journey / quadrant element by its label. For example, 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) colours body cells by content, so enums and statuses stand out: 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 light wash behind the cell. Per cell, the first matching rule in fence order wins. Rules match content, not 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 does not 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
```