docs(readme): add SVG masthead hero and fix mermaid loop control overlap#1041
Merged
Conversation
Job 1 (control overlap): GitHub overlays pan/zoom controls along the bottom edge of every rendered mermaid block. In the top-of-README loop diagram the "Halt with a report" node landed in the bottom-right corner (measured at x=0.94W, y=0.71H of the rendered viewBox) and was hidden under the controls. Both outcomes now converge into a single mid-height "Illustrated run report" node, which pushes the far-right column to the vertical center and moves both terminal nodes inboard, leaving both bottom corners empty. The convergence is honest: every replay already writes an illustrated REPORT.md. The second (visualize) diagram is a single centered column ending in a bottom-center Success node, so its corners are already clear and it is unchanged. Job 2 (masthead): add media/openadapt-hero.svg, a hand-authored, self-contained SVG hero (17 KB, no raster) telling the whole governed-demonstration-compiler story at a glance: record -> compile to a deterministic program -> deterministic replay with no model calls on the healthy path -> resolution ladder (structural, template, OCR, geometry; grounding model optional and never on the hot path) -> armed identity gates -> independent out-of-band effect verification -> halt with a report for a human or an AI. Footer bands show substrate and surface coverage with honest maturity labels (Browser Beta; Windows/macOS/RDP scoped; Linux research; Citrix/VDI exploratory; Cloud Beta browser; Desktop experimental). Palette aligns with openadapt.ai (paper/ink + accent green). The SVG is theme-aware via an in-document prefers-color-scheme media query with a legible light-paper default, so it reads on both GitHub light and dark and on PyPI. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM
This was referenced Jul 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two related README jobs
Job 1 — fix the Mermaid control overlap
GitHub overlays its pan/zoom controls along the bottom edge of every rendered
mermaidblock (confirmed via mermaid-js/mermaid#7117 and community/discussions#137171; the upper area stays clear). In the top-of-README loop diagram the safety-critical "Halt with a report" node landed in the bottom-right corner and was hidden.I rendered the current diagram with mermaid-cli and measured it: Halt sat at x=0.94W, y=0.71H of the rendered viewBox — dead in the bottom-right control zone.
Fix: both outcomes (
Verified write,Halt with a report) now converge into a single "Illustrated run report" node. That node becomes the far-right column and, being the sole node there, is placed at the vertical center (y=0.43H); both terminals move inboard (Halt is now ~365px from the right edge). Re-measured: both bottom corners are empty, and Halt and Verified are clearly visible. The convergence is honest — the README already states every replay writes an illustratedREPORT.md.The second (
visualize) diagram is a single centered column ending in a bottom-centerSuccessnode, so its corners are already clear; it is unchanged.Job 2 — the masthead hero
Option chosen: (b) a hand-authored, self-contained SVG. Rationale: it renders inline on GitHub with no pan/zoom chrome (the very thing that broke Job 1's diagram), is crisp and scalable at any width, is compact (~17 KB, no raster blob), resolves on PyPI from a single
raw.githubusercontentURL, and is fully theme-aware. Raw Mermaid (a) would reintroduce the control overlap and can't carry brand typography/hierarchy; a PNG (c) is heavier and not scalable.media/openadapt-hero.svgtells the whole governed-demonstration-compiler story at a glance:Record a demo->Compile to a program (IR)->Deterministic replay (0 model calls)->Verified write, with the drift path branching down through the resolution ladder (structural / template / OCR / geometry; grounding model optional and never on the hot path) -> armed identity gate -> independent out-of-band effect verification -> fork toVerified write(re-resolved) orHalt, don't guess— report for a human or an AI.Footer bands state coverage with honest maturity:
Design: palette pulled from openadapt.ai (paper
#F2F1EC/ ink#23281F/ accent green#3E6B4F, dark inset#14171A/#86D9A8). Theme-aware via an in-documentprefers-color-schememedia query with a legible light-paper default, so it reads on GitHub light and dark and on PyPI. No fabricated capabilities; maturity matches the substrate table below it.Placed as the hero near the top (absolute raw URL, PyPI-safe). The accurate in-body Mermaid diagrams (now fixed) remain as the technical detail.
Renders (light on white, dark on GitHub
#0d1117) were captured for review.