Field contract

The at-a-glance contract for every block, converted at build time from the repo's authoring-skill reference. For worked examples, open the family page from the blocks overview.

Block data shapes — required vs optional (the contract)

Every block also carries optional title, description, lede (editorial text rendered around the diagram) and an optional top-level id: — none are ever required, so they're left out of the table below, which shows only the structural payload. * marks a required field; everything else is optional. Omit optional fields you have no value for — don't pad them with empty strings. (n) marks a number (don't quote it); every other value is a string.

Reading the contract:

• A block with no items at all is a W_EMPTY_BLOCK warning — give it content or delete it. The * fields are the minimum to make each item valid.
• Terse item strings are the default form for four list fields — sequence.messages and flow/graph/block edges take from -> to: label (--> response/dashed · -x-> error), erd.relations takes from ||--o{ to: label (crow's-foot cardinality), and timeline.items takes [status] date · label · desc. They expand to the object shapes above at parse time; use the object form for anything the grammar can't say.
• Grid blocks (flow · state · dfd · c4 · uml · graph · felogic · grid-mode block) place nodes on a 1-indexed col/row grid — but coordinates are optional: omit them on every node and the engine auto-lays the graph out from the edges (quick mode). Place all or none — if any node is missing a coordinate the auto-layout replaces every placement. groups require placed nodes (zones are anchored to grid cells); swimlane always needs col + lane. Adding layers: to block switches it to band layout, where nodes use layer: (an index) instead of col/row.
• Quick mode runs left-to-right. Ranks become columns, so the diagram grows sideways instead of down the page — a tall stack of ranks outgrows both the page column and the slide stage. Set dir: TB on flow · state · dfd · c4 · felogic · block for the top-to-bottom layout instead (dir: LR is the default and never needs writing). dir only steers the auto-layout — with coordinates on the nodes it does nothing, so place a diagram horizontally yourself: put the progression on col and the branches on row. graph has no dir (its edges already use that key) and uml always ranks top-to-bottom.
• Numbers stay unquoted: coordinates (col row lane w), points, replicas, group, start/span, quadrant x/y, and emotion[]. Quote anything string-like that looks numeric (version, delta: "0") — see YAML pitfalls in SKILL.md.
• kind is optional on most nodes/edges — omit it for the neutral default; set it only to get the right glyph, colour, or marker.

Field semantics — cross-block clarifications

A few fields are easy to misuse. Lock these in.

• On most diagram blocks: lede renders as a <p class="section-lede"> under the section title, sized for an editorial paragraph. description renders inside the diagram frame as the diagram's caption. Use both when you have both kinds of text to convey.
• In grid layout, col/row are optional (quick mode): omit them on every node and the layout is derived from the edges. Half-placed graphs are fully re-laid-out, and groups need placed nodes — all or none.

Alias table — old spellings that keep working

These 12 former block types are permanent aliases: the old fence tag parses to its canonical type with the patch below injected (only for keys the body doesn't set — the body always wins), and renders byte-identically to how it always did. avo check surfaces the mapping as a W_ALIAS_TYPE warning — informational only; the old spelling keeps working. Use the canonical name + patch in new blocks.