Flows & state

Field contracts and worked examples for the flows & state 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 77 blocks, or the block catalog for live previews.

Sequence & state

sequence — interaction over time (rich SVG + step list + footer)

Messages default to the terse from -> to: label form — -> sync, --> response, -x-> error (from/to must match actor ids):

Switch a message to the object form when it needs more than the arrow can say — kind: async/note, a summary for the step list, a code snippet:

id: seq-place-order
title: One transaction wraps authorize + persist.
lede: Time runs downward. Solid arrows are sync; dashed are responses.
description: Happy path shown.
endpoint: { method: POST, path: /orders }
actors:
  - { id: Client, name: Client, sub: web / mobile }
  - { id: API, name: Orders API, sub: orders handler }
  - { id: PG, name: Postgres, sub: orders }
  - { id: Payment, name: Payment GW, sub: external, external: true }
messages:
  - { from: Client, to: API, label: POST /orders, kind: sync, summary: "Place the order with cart, token, idempotency key.", code: "POST /orders\nIdempotency-Key: ..." }
  - { from: API, to: API, kind: note, label: validate token, summary: "Validate bearer, check idempotency key." }
  - { from: API, to: PG, label: INSERT order, kind: sync, summary: "Open the txn and insert in PENDING.", note: "Required index: orders(idempotency_key)." }
  - { from: PG, to: API, label: order_id, kind: response, summary: "Returns the new order_id." }
  - { from: API, to: Client, label: 201 Created, kind: response, summary: "201 with the order." }
foot:
  - { label: Target p95, value: 250ms }
  - { label: Idempotent, value: via Idempotency-Key (24h TTL) }

Each message: from + to (must match an actor id), label, optional kind (sync | response | async | error | note). Terse strings and objects mix freely in one messages list.

• note kind is a numbered annotation on one lane — no arrow.
• summary (long form for the step list under the SVG),
• code (a code snippet inside the step item),
• note field (italic-gray sub-note below the summary). endpoint.method colours the tag pill (POST → navy, GET → green, etc.). foot items render as key/value pills beneath the diagram.

state — state machine (+ transition table)

kind on a state is start | terminal | active | wait. Optional groups draw dashed zone wrappers around cell ranges (same shape as on flow, below).

Flow & process

flow — flowchart with decisions

kind is start | end | decision | process. Edges default to the terse from -> to: label form (--> dashed, -x-> error); kind: error edges (or labels starting with no/fail/error/reject) render in red.

Optional groups draw dashed zone wrappers around cell ranges — one shape on every grid diagram (flow, dfd, state, c4, block): col/row anchor the top-left cell, cols/rows span (default 1), label sits in the corner, optional color tints the outline:

title: Admission control
groups:
  - { col: 2, row: 1, cols: 2, rows: 1, label: Rate limiter }
nodes:
  - { id: start, col: 1, row: 1, kind: start, label: Request }
  - { id: quota, col: 2, row: 1, kind: decision, label: Under quota? }
  - { id: serve, col: 3, row: 1, kind: end, label: Serve }
edges:
  - start -> quota
  - quota -> serve: "yes"

variant: dag frames the same block as a pipeline / DAG (CI/CD-flavoured). The old dag type is its permanent alias:

variant: dag
title: CI pipeline
nodes:
  - { id: src, col: 1, row: 1, kind: start, label: Source }
  - { id: build, col: 2, row: 1, kind: process, label: Build }
  - { id: deploy, col: 3, row: 1, kind: end, label: Deploy }
edges:
  - src -> build
  - build -> deploy

dfd — data-flow diagram

kind is process | external | store | datastore. Optional num on processes. Optional groups draw dashed zone wrappers around cell ranges (same shape as on flow).

swimlane — cross-functional process

Step kind is action | decision | start | end | wait.

steps — a numbered how-to / runbook stepper

A vertical stepper — numbered circles joined by a rule; each step has a bold title, an optional body, an optional code command (rendered on the dark code surface, with lang as its header), and an italic note. Use steps for linear procedures a human executes in order; use flow/swimlane when the procedure branches, and statustable when items have status/owner rather than order.

cycle — a closed loop of stages arranged in a circle

Stages render clockwise from 12 o'clock, numbered, with the last stage feeding the first — build–measure–learn, PDCA, an incident loop. 2-8 steps; each is a bare string (the label) or { label, desc } — descriptions move to the numbered legend under the diagram. Optional center is a hub label inside the ring. Use cycle when the process repeats; use flow when it branches and ends, and steps for a linear one-shot procedure.

Field semantics — clarifications

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

• sequence.actors[].sub is the subtitle under the actor's name on the lane head (e.g. sub: web / mobile, sub: orders handler). Keep it short — 2-4 words.
• sequence.actors[].external: true darkens the lane (slate instead of navy), signaling the actor lives outside your service boundary.
• sequence.messages[].kind: note is not a message — it's a numbered annotation on the from-actor's lane, with no arrow. Use it for things like "validate token" that don't cross a boundary.
• sequence.messages[].summary is the longer text shown in the step-by-step list below the SVG. Keep label short (the SVG arrow) and put detail in summary. code: adds a <pre> snippet inside the step item.