docs(readme): add real visualize graph, loop/halt diagrams, and run screenshots

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<br/>no model calls on a healthy run"}
+  R -->|UI matches| V["Verified write"]
+  R -->|UI drifted| L{"Resolution ladder<br/>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:
+
+![OpenAdapt Desktop halting a run safely: step 9 could not verify the typed value against the target field, so the run aborted before the write](https://raw.githubusercontent.com/OpenAdaptAI/OpenAdapt/main/media/desktop-replay-halted.png)
+
 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'<br/><small>identity</small>")
+  n6("click 'New Encounter'")
+  n7("click 'Triage'")
+  n8("click at (344, 290)")
+  n9("type <note>")
+  n10("click 'Save Encounter'<br/><small>irreversible</small>")
+  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 Desktop replaying the compiled MockMed workflow locally: 11 of 11 steps verified, 8.2s, $0.000 cost, no model calls](https://raw.githubusercontent.com/OpenAdaptAI/OpenAdapt/main/media/desktop-replay-verified.png)
+
 > `openadapt flow <verb>` is the recommended path. The standalone
 > `openadapt-flow <verb>` command keeps working and behaves identically.