diff --git a/README.md b/README.md
index 36735c7a6..da711bdb4 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,24 @@ a healthy run. When the UI changes, the resolution ladder may re-resolve the
target and persist a reviewable repair. When configured checks cannot establish
identity or success, the run **halts with a report** instead of continuing.
+```mermaid
+flowchart LR
+ D["Demonstrate once"] --> C["Compile to a local program"]
+ C --> R{"Replay deterministically
no model calls on a healthy run"}
+ R -->|UI matches| V["Verified write"]
+ R -->|UI drifted| L{"Resolution ladder
re-resolves the target?"}
+ L -->|resolved| V
+ L -->|no confident match| H["Halt with a report"]
+ classDef halt stroke:#b21f2d,stroke-width:2px;
+ class H halt;
+```
+
+*Text summary (PyPI does not render Mermaid): demonstrate once, compile to a
+local program, then replay it deterministically with no model calls. If the UI
+matches, the write is verified; if it drifted, the resolution ladder re-resolves
+the target, and if it cannot establish a confident match the run halts with a
+report instead of guessing.*
+
---
## Installation
@@ -103,9 +121,15 @@ openadapt flow replay bundle --drift theme --run-dir run-drift \
--save-healed-to bundle-healed
```
-Each replay writes an illustrated `REPORT.md` in its run directory. The drift
-run demonstrates bounded deterministic re-resolution; it is not a claim that
-arbitrary UI changes can be repaired.
+Each replay writes an illustrated `REPORT.md` in its run directory: an ordered
+step table, the resolution rung and confidence per step, before/after
+screenshots, and totals. See real rendered examples committed in the engine
+repo: the
+[baseline MockMed run report](https://github.com/OpenAdaptAI/openadapt-flow/blob/main/docs/showcase/baseline-run/REPORT.md)
+and the
+[theme-drift run report](https://github.com/OpenAdaptAI/openadapt-flow/blob/main/docs/showcase/theme-drift-run/REPORT.md).
+The drift run demonstrates bounded deterministic re-resolution; it is not a
+claim that arbitrary UI changes can be repaired.
Now record your own workflow. Recording is substrate-aware: `--backend` selects
what you drive, and the browser backend is the default. The full loop stays
@@ -146,6 +170,13 @@ clicks, a vacuous postcondition, and no configured system-of-record effect for
its write, so the strict policy refuses to call it safe. A policy pass means
only that the bundle satisfies that named policy.
+The same halt-don't-guess principle holds at replay time. When a step cannot be
+verified, the run stops and reports why rather than writing to the wrong record.
+Below, the optional desktop app (**Experimental**) halts a run because the typed
+value could not be verified on the target field:
+
+
+
One recording does more than replay a single path. `openadapt flow for-each`
wraps a compiled bundle's body in a governed loop that runs once per record of
a worklist (CSV or JSON), bounded, identity-checked and effect-verified per
@@ -159,6 +190,56 @@ openadapt flow for-each bundle --records worklist.csv --out queue-bundle
openadapt flow visualize bundle -o graph.html
```
+Here is the actual program graph for the bundled MockMed workflow, generated by
+`openadapt flow visualize bundle --format mermaid` (not drawn by hand). Eleven
+ordered steps, an armed **identity** gate on the record it opens, and the final
+`Save Encounter` write marked **irreversible** and as the run's halt point:
+
+```mermaid
+flowchart TD
+ n0("click at (214, 195)")
+ n1("type 'nurse.demo'")
+ n2("click at (214, 264)")
+ n3("type 'mockmed-demo-pass'")
+ n4("click 'Sign In'")
+ n5("click 'Open'
identity")
+ n6("click 'New Encounter'")
+ n7("click 'Triage'")
+ n8("click at (344, 290)")
+ n9("type ")
+ n10("click 'Save Encounter'
irreversible")
+ n11{{"Success"}}
+ n0 --> n1
+ n1 --> n2
+ n2 --> n3
+ n3 --> n4
+ n4 --> n5
+ n5 --> n6
+ n6 --> n7
+ n7 --> n8
+ n8 --> n9
+ n9 --> n10
+ n10 --> n11
+ classDef irreversible stroke:#b4530a,stroke-width:2px;
+ classDef halt stroke:#b21f2d,stroke-width:2px;
+ class n10 irreversible;
+ class n10 halt;
+```
+
+*Text summary (PyPI does not render Mermaid): the graph is a linear program of 11
+steps (sign in with `nurse.demo`, open the record, start a new encounter, go to
+triage, type the note, and save), with an armed identity gate on `click 'Open'`
+and the `Save Encounter` write marked irreversible and as the single halt point,
+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.
+
+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:
+
+
+
> `openadapt flow ` is the recommended path. The standalone
> `openadapt-flow ` command keeps working and behaves identically.
diff --git a/media/desktop-replay-halted.png b/media/desktop-replay-halted.png
new file mode 100644
index 000000000..08e0fe175
Binary files /dev/null and b/media/desktop-replay-halted.png differ
diff --git a/media/desktop-replay-verified.png b/media/desktop-replay-verified.png
new file mode 100644
index 000000000..da273f501
Binary files /dev/null and b/media/desktop-replay-verified.png differ