Skip to content

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

Merged
abrichr merged 1 commit into
mainfrom
docs-readme-visuals
Jul 21, 2026
Merged

docs(readme): add real visualize graph, loop/halt diagrams, and run screenshots#1040
abrichr merged 1 commit into
mainfrom
docs-readme-visuals

Conversation

@abrichr

@abrichr abrichr commented Jul 21, 2026

Copy link
Copy Markdown
Member

What

Adds inline visuals to the launcher README, keeping the existing two-path (local-first / cloud-optional) structure intact.

1. Real visualize program graph (not hand-drawn)

Embeds the actual Mermaid graph that openadapt flow visualize emits for the bundled MockMed workflow, right where visualize is described in Path 1. Generated from real tool output on openadapt-flow:

python -m openadapt_flow demo-record --out rec
python -m openadapt_flow compile rec --out bundle --name mockmed-triage
python -m openadapt_flow visualize bundle --format mermaid -o graph.mmd

(The workspace openadapt-flow HEAD carries visualize/for-each; the currently-published 1.19.0 wheel predates them, so the graph was produced from source.) The graph shows the 11 ordered steps, the armed identity gate on click 'Open', and the Save Encounter write marked irreversible and as the run's single halt point. It is copied verbatim from the tool, small enough (12 nodes) to embed whole with no trimming.

2. Record -> compile -> replay loop diagram (Mermaid)

A compact flowchart LR that also encodes the resolve-or-halt decision (halt-don't-guess), added at the end of "Why a compiler".

3. Real product screenshots (reused, not invented)

Two real Experimental desktop-app screenshots of the same MockMed workflow, optimized/resized to 1400px (~135-150 KB each) under media/:

  • desktop-replay-verified.png - a clean 11/11 deterministic replay at $0.000 (no model calls on a healthy run).
  • desktop-replay-halted.png - a run halting safely when a typed value cannot be verified.

4. Link the illustrated REPORT.md

The "illustrated REPORT.md" mentions now link to real committed example run reports in openadapt-flow (baseline + theme-drift), via absolute github.com URLs.

Honest + PyPI-safe

  • Honest: graph and reports are real tool output; screenshots are the real desktop app, labeled Experimental; no fabricated metrics.
  • PyPI (no Mermaid render): every Mermaid block carries a one-line plain-text summary so the point survives as a code block. Images use absolute raw.githubusercontent.com/OpenAdaptAI/OpenAdapt/main/... URLs so they resolve in the PyPI long description after merge (they will 404 on the PR preview until merged to main, which is expected).
  • No em dashes added; net em-dash count is unchanged from origin/main. No content-lint/CI covers the README in this repo (only a docs-publisher guard, untouched).

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM

…creenshots

Add inline visuals to the launcher README while preserving the two-path
(local-first / cloud-optional) structure.

- Embed the ACTUAL program graph that `openadapt flow visualize bundle
  --format mermaid` emits for the bundled MockMed workflow (11 steps, armed
  identity gate on the opened record, irreversible+halt on the write). It is
  real tool output, not hand-drawn, generated from a demo-record -> compile
  -> visualize run on openadapt-flow.
- Add a compact record -> compile -> replay loop diagram (Mermaid) that also
  shows the resolve-or-halt decision.
- Reuse real desktop-app (Experimental) screenshots of the same MockMed
  workflow: a verified 11/11, $0.000 replay and a safe halt when a step
  cannot be verified. Optimized/resized (1400px, ~135-150KB each) under media/.
- Link the "illustrated REPORT.md" mentions to real committed example run
  reports in openadapt-flow (baseline + theme-drift), via absolute github.com
  URLs so they resolve from PyPI too.

PyPI does not render Mermaid, so every Mermaid block carries a one-line text
summary, and images use absolute raw.githubusercontent.com URLs so they
resolve in the PyPI long description after merge. No em dashes added; net
em-dash count unchanged from origin/main.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM
@abrichr
abrichr merged commit 5a7acb4 into main Jul 21, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant