{% flow %}

Attributes

Parameter	Type	Required	Description
id	string	✓	Unqualified flow id (e.g., 'add-bookmark')
scope	string	—	Space-separated list of visibility scopes

Valid Children

Tag	Multiplicity
{% tldr %}	[1]
{% explanation %}	[*]
{% precondition %}	[*]
{% postcondition %}	[*]
{% phase %}	[*]
{% step %}	[+]
{% example %}	[*]

Rules

Rule	Force	Realm	Reference	Description
step-action-declared	must	global	—	When or is set on a step, the referenced name must be declared in an block. validationreferential-integrity
operation-path-outcomes	must	global	—	When is set on a step, every path outcome must be either or a declared error id from that operation's list. validation
emit-declared-event	must	global	—	When is set on a path, the referenced event must be declared in an block. validationreferential-integrity
throws-declared-error	must	global	—	When is set on a path, the referenced error must be declared in an block. validationreferential-integrity
join-target-named-step	must	global	—	When is present, must match the of a named step in the same flow. validationreferential-integrity
path-single-exit-strategy	must	global	—	A path cannot have both and a tag — only one exit strategy is allowed. validationstructure

Flows are automatically rendered as interactive Mermaid diagrams (supporting auto-linking, fullscreen, and source views) and listed in the “Interaction Flows” section of the site.

Minimal flow with one branch and optional action

tagflowstepbranch flow-tag-minimal-branch

{% flow slug="reset-password" feature="feature/account-recovery" scope="agent" %}

  {% precondition %}User account exists. Reset token has been issued.{% /precondition %}
  {% postcondition %}Password updated. All existing sessions invalidated.{% /postcondition %}

  {% step actor="user" %}
  User opens the password reset link from their email.
  {% /step %}

  {% step action="submit-reset-token" actor="user" %}
  User submits the reset token from their email.
  {% /step %}

  {% step action="set-new-password" actor="user" %}
  User provides and confirms the new password.
  {% /step %}

  {% branch condition="token-valid" %}
    {% path outcome="success" label="Password updated" emit="password-reset" %}
    Password updated → sessions invalidated → redirect to sign-in.
    {% /path %}
    {% path outcome="expired-token" label="Token expired" throws="expired-token" %}
    Token expired → show error → offer re-send.
    {% /path %}
  {% /branch %}

{% /flow %}

Flow with branches, paths, emit, and throws

tagflowbranchpath flow-tag-complex-paths

{% flow id="add-bookmark" scope="public agent" %}
  {% precondition %} User is logged in {% /precondition %}
  {% postcondition %} Bookmark saved and visible in the list {% /postcondition %}
  {% postcondition outcome="duplicate-url" %} Duplicate error shown; bookmark not created {% /postcondition %}

  {% step actor="role/user" %}
  User opens the bookmark form.
  {% /step %}

  {% step id="submit" action="submit-url" actor="role/user" %}
  User enters a URL in the sidebar.
  {% /step %}

  {% branch condition="url-unique-for-user" %}
    {% path outcome="success" label="Bookmark saved" emit="bookmark-added" %}
    add-bookmark executes → title auto-fetched → bookmark-added emitted → toast shown.
    {% /path %}
    {% path outcome="invalid" label="Validation error shown" %}
    URL is malformed — form stays open for correction.
    {% join target="submit" label="retry" /%}
    {% /path %}
    {% path outcome="duplicate-url" label="Duplicate error shown" throws="duplicate-url" %}
    Duplicate detected → validation error on URL field → form stays open.
    {% /path %}
  {% /branch %}
{% /flow %}

Tag Tree

{% tldr %}[1]One-sentence summary rendered as a lead paragraph and used as the document's short description throughout the site.{% explanation %}[*]Provides targeted advice or collapsible detail for a specific audience. Renders as a callout () or a disclosure element (). Supports full Markdown in the body.{% precondition %}[*]A condition that must be true before a flow can begin.{% postcondition %}[*]A condition that holds after a flow completes, optionally linked to a specific branch outcome.{% phase %}[*]Groups steps within a flow into a named stage, rendered as a Mermaid subgraph and a section header in the steps table.{% step %}[+]A single step in a flow sequence, optionally linked to an action or operation and an actor.{% branch %}[?]A decision point following a step, containing one or more path tags representing the possible outcomes.{% path %}[+]One branch of a flow decision point, declaring the outcome, any emitted event or thrown error, and an optional explicit exit.{% join %}[?]{% branch %}[*]A decision point following a step, containing one or more path tags representing the possible outcomes.{% path %}[+]One branch of a flow decision point, declaring the outcome, any emitted event or thrown error, and an optional explicit exit.{% join %}[?]{% step %}[+]A single step in a flow sequence, optionally linked to an action or operation and an actor.{% branch %}[?]A decision point following a step, containing one or more path tags representing the possible outcomes.{% path %}[+]One branch of a flow decision point, declaring the outcome, any emitted event or thrown error, and an optional explicit exit.{% join %}[?]{% example %}[*]Embeds a named, filterable example inline in a document and collects it in the global Examples Gallery.