diff --git a/README.md b/README.md
index f2b6a7130..369e0773d 100644
--- a/README.md
+++ b/README.md
@@ -244,6 +244,44 @@ ending in a `Success` terminal.* The `--format html` render is a self-contained,
 offline page with the full per-step resolution ladder, identity, and effect
 annotations; `--format json` emits the shared graph spec.
 
+A compiled program is not limited to a straight line. Wrapping a demonstrated
+body in `openadapt flow for-each` compiles a **data-driven loop**, and
+`visualize` renders that richer structure honestly. Here is a compact
+`save-encounter` body wrapped in a governed loop over a worklist, generated by
+`openadapt flow visualize bundle --format mermaid` (again, not drawn by hand):
+
+```mermaid
+flowchart TD
+  n0{"Loop over worklist"}
+  n1("type <patient_id>")
+  n2("type <note>")
+  n3("save encounter<br/><small>effect · irreversible</small>")
+  n4{{"Success"}}
+  n0 -->|per row of worklist| n1
+  n1 --> n2
+  n2 --> n3
+  n3 -->|next record| n0
+  n0 -->|worklist exhausted| n4
+  classDef irreversible stroke:#b4530a,stroke-width:2px;
+  classDef halt stroke:#b21f2d,stroke-width:2px;
+  class n3 irreversible;
+  class n3 halt;
+```
+
+*Text summary (PyPI does not render Mermaid): a governed loop over a worklist.
+The `Loop over worklist` node runs the demonstrated body once per record (`per
+row of worklist`): type the `patient_id`, type the `note`, then the `save
+encounter` write, which is marked **irreversible**, **effect-verified** against
+the system of record, and the per-record halt point. Control returns to the loop
+(`next record`) after each record and leaves to `Success` only when the worklist
+is exhausted; a record whose write cannot be verified halts the run instead of
+being skipped.* Every per-record gate the linear replay applies -- identity
+where armed, effect verification, and postconditions -- fires again on each
+iteration, bounded so an over-long worklist halts rather than running unbounded.
+The body shown is a compact MockMed fixture whose loop is replay-tested in
+`openadapt-flow`; a loop authored over a full recording is in that repo's
+`docs/showcase-loop`.
+
 Replayed locally, that same compiled workflow runs deterministically with no
 model calls. The optional desktop app (**Experimental**) shows a completed run:
 11/11 steps verified, and `$0.000` because a healthy run makes no model calls: