diff --git a/MANIFEST.in b/MANIFEST.in
index 9e7943c..f0020f6 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -32,3 +32,4 @@ global-exclude *.sqlite
 global-exclude *.jsonl
 global-exclude /HANDOFF.md
 global-exclude /.grapharc
+global-exclude /docs/media
diff --git a/README.md b/README.md
index f8095f4..49862c3 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,10 @@ Build production-grade multi-agent systems with built-in safety, auditability, a
 
 **Status:** Early days (`0.1.2`) — the API is not stable yet. `pip install grapharc` — see [Install](#install).
 
+![One English question is decomposed by a local model into a nine-node graph — four parallel evidence pulls fanning out of START, a correlate join, a hypothesis fork, and a final report — shown live in the browser: the proposed graph waits grey for human approval, then each node turns amber while it runs and green when it is done.](docs/media/grapharc-decompose.gif)
+
+*One question in, a governed graph out: a local model proposes the topology, the admission gate and a human approval decide, and the live view shows every node run — amber while executing, green when done. ([full-quality mp4](docs/media/grapharc-decompose.mp4))*
+
 ### What makes GraphARC different
 
 - **Admission gate**: All runtime topology changes go through deterministic approval before execution
diff --git a/docs/media/grapharc-decompose.gif b/docs/media/grapharc-decompose.gif
new file mode 100644
index 0000000..f3bf0fe
Binary files /dev/null and b/docs/media/grapharc-decompose.gif differ
diff --git a/docs/media/grapharc-decompose.mp4 b/docs/media/grapharc-decompose.mp4
new file mode 100644
index 0000000..2a6fc7b
Binary files /dev/null and b/docs/media/grapharc-decompose.mp4 differ
diff --git a/pyproject.toml b/pyproject.toml
index 8fe6f6b..e92e03e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -150,6 +150,9 @@ exclude = [
     # `ignore-vcs` is on — this line is the only thing that does.
     "/HANDOFF.md",
     "/.grapharc",
+    # Demo footage embedded in the README. GitHub renders it; a pip install
+    # has no use for megabytes of GIF, so it stays out of the sdist.
+    "/docs/media",
 ]
 
 # `packages` is recursive: every subpackage under `grapharc/` ships without