Field contracts and worked examples for the narrative & prose blocks — converted at build time from the repo's authoring-skill reference. Every example body is YAML; in a real doc the fence language is the block type (for example sequence … ). Schemas are strict — unknown fields are rejected. See the field contract for the at-a-glance shape of all 87 blocks, or the block catalog for live previews.

Document & meta

meta — document cover (first block only)

```metaeditable · live

title: Orders API subtitle: How the orders service accepts and persists a purchase. tag: API · v1 logo: https://example.com/logo.png # optional brand logo in the cover (use an absolute https URL)

renderedavo renders this

DOCUMENTAPI · v1

Orders API

How the orders service accepts and persists a purchase.

Valid — passes avo check

logo is optional — an absolute https URL (or path) shown above the title on the document and slide cover.

Prose & structure

prose — structured prose (heading / paragraph / list / quote)

callout — note / tip / warning / danger

The simplest form is just the text — no YAML at all (colons and quotes are fine, and inline Markdown like **bold** and `code` renders):

Lead with a field to set tone or title (tone is note | tip | warn | danger):

tone: warn
title: Idempotency required
body: Clients must send an Idempotency-Key header so retries are safe.

glossary — term / definition rows

figure — an image with a caption

```figureeditable · live

src: https://example.com/dashboard-screenshot.png alt: The alerts dashboard after the redesign caption: "The redesigned alerts dashboard: unacked alerts pin to the top." width: 560 # optional px cap on the rendered image

renderedavo renders this

SECTION 01 · Figure

Valid — passes avo check

src is required (an absolute https URL or a repo-relative path). Use figure for real images — screenshots, photos, exported charts from other tools. For anything the renderer can draw (architecture, flows, data), use a typed diagram block instead so the source stays editable.

faq — Q&A accordions (native details, no JS)

Each item is one <details> accordion: the question in the summary, the answer expands. open: true starts an item expanded. Answers are plain text — blank lines become paragraph breaks. Use faq for genuine reader questions; use glossary for term definitions and callout for a single aside.

Presentation text

divider — a full-width section break ("PART 2")

Only title is required. kicker is a short mono eyebrow ("PART 2", "APPENDIX") rendered with rule lines either side; accent tints the kicker and the band's wash (accent as in drivers). In a deck, put a divider alone under its own ## heading and it becomes a clean interstitial slide.

bignumber — one hero metric that carries the slide

value is a string — quote numeric-looking values ("-75%", "3.2"). trend is up | down | flat; the arrow renders neutral gray on purpose (for a hero metric "down" is often good — latency, cost), while the delta text takes the accent color. Use bignumber for ONE number; use stats for a row of KPIs.

takeaways — the 2-6 things to remember

items takes 2-6 rows; each text is a bold one-liner, detail an optional smaller line beneath. title defaults to "Takeaways"; accent tints the circled numbers. The natural closing slide of a deck — use list for ordinary bullets inside a document.

pullquote — a standout quote

Bare text IS the quote (like callout); lead with text: / attribution: for fields.

layers — a layered explanation (N numbered layers)

Use layers (not a table) when content reads as ordered tiers each answering one question — e.g. an L1/L2/L3 model.