feat(demo): add recorded realworld-simulation demo (GIF + MP4 + tape)

README.md

@@ -8,6 +8,11 @@
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](./CODE_OF_CONDUCT.md)
 [![EEP compatible](./assets/badges/eep-compatible.svg)](./docs/current/SPECIFICATION.md)
 
+<p align="center">
+  <img src="./assets/realworld-demo.gif" alt="Two terminal panes running in parallel: an agent fetching the same quarterly report via current-web HTML scraping (~26s, ~46 KB, ~11.5K tokens, 2 simulated human steps) vs EEP (~10s, ~2.2 KB, ~386 tokens, 0 human steps). Deterministic, no LLM calls." width="1000"/>
+</p>
+<p align="center"><sub>Two agent paths, side by side. Deterministic — no LLM spend. <a href="./realworld-simulation/">Reproduce it →</a></sub></p>
+
 ## Stability (v0.1)
 
 The specification and reference packages are **v0.1**: the spec, schemas, CI and libraries here are meant to be implemented against, but **breaking changes can still happen** while the ecosystem is small. Pin versions in production and read [CHANGELOG.md](./CHANGELOG.md) before upgrades. Governance details: [GOVERNANCE.md](./GOVERNANCE.md).

realworld-simulation/.gitignore

@@ -5,3 +5,8 @@ agent/.venv/
 **/__pycache__/
 *.pyc
 .DS_Store
+
+# vhs/ffmpeg intermediate outputs (final artifacts live in ../assets/)
+realworld-demo.mp4
+realworld-demo-short.mp4
+realworld-demo.gif

realworld-simulation/README.md

@@ -86,6 +86,32 @@ flowchart LR
 - Do **not** speed up the terminal recording for the EEP leg — sub-second structured access is the punchline.
 - Suggested post: *We taught an agent to satisfy gates, sign an NDA, and pay (simulated) USDC for JSON — no HTML parse. Entity Engagement Protocol (EEP).*
 
+## Regenerating the demo recording
+
+The canonical demo GIF/MP4 live in [`assets/realworld-demo.gif`](../assets/realworld-demo.gif) and [`assets/realworld-demo.mp4`](../assets/realworld-demo.mp4). The recording runs both scenarios **in parallel** (split-screen mode via `DEMO_SPLIT_SCREEN=1`) so the contrast in completion time — Scenario A's ~26 s vs Scenario B's ~10 s — is visible at a glance.
+
+To refresh:
+
+```bash
+# 1. Run the demo recording (uses VHS — brew install vhs)
+#    demo.tape sets DEMO_SPLIT_SCREEN=1 and renders at 1800×950 so the
+#    parallel two-pane layout fits.
+vhs demo.tape
+
+# 2. Optimized GIF via two-pass palette extraction (10 fps, 1000 px wide)
+ffmpeg -y -i realworld-demo.mp4 -vf "fps=10,scale=1000:-1:flags=lanczos,palettegen=stats_mode=diff:max_colors=128" /tmp/palette.png
+ffmpeg -y -i realworld-demo.mp4 -i /tmp/palette.png \
+  -lavfi "fps=10,scale=1000:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=5" \
+  realworld-demo.gif
+
+# 3. Lossy post-optimization with gifsicle (brew install gifsicle)
+gifsicle -O3 --colors 128 --lossy=80 realworld-demo.gif -o realworld-demo-opt.gif
+mv realworld-demo-opt.gif realworld-demo.gif
+
+# 4. Move artifacts to assets/
+mv realworld-demo.mp4 realworld-demo.gif ../assets/
+```
+
 ## License
 
 Apache-2.0, consistent with the EEP monorepo.

realworld-simulation/demo.tape

@@ -0,0 +1,19 @@
+# EEP Realworld Simulation — split-screen recording
+# Runs Scenario A (current web HTML scraping) and Scenario B (EEP) IN PARALLEL
+# in two side-by-side terminal panes. The contrast in completion time is the point.
+#
+# Run with: vhs demo.tape (requires brew install vhs)
+
+Output realworld-demo.mp4
+
+Set FontSize 11
+Set Width 1800
+Set Height 950
+Set Padding 18
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 40ms
+
+Type "DEMO_SPLIT_SCREEN=1 npm run demo:only"
+Sleep 400ms
+Enter
+Sleep 45s