diff --git a/README.md b/README.md
index 88251ad..9665b3e 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,18 @@ sliding-window ARQ, adaptive RTO (Jacobson/Karn), per-message reliability classe
 SWIM failure detection - fuzz-hardened, fault-injected with `netem`, and benchmarked
 honestly against kernel TCP (`TCP_NODELAY`) and ENet.
 
+![Five SWIM nodes detecting a partitioned peer in 1020ms and reconverging in 2020ms without ever confirming it dead](docs/demo.gif)
+
+The membership half, running on the in-process SimNet and a virtual clock: five
+nodes gossiping, one partitioned away, 1020 ms to the first SUSPECT and 2020 ms
+to reconverge after the heal, with the reachable node never falsely confirmed
+dead. Deterministic by construction, so those numbers are the same on macOS and
+Linux. Reproduce with `./docs/demo-setup.sh && vhs docs/demo.tape`.
+
 **Live demo:** [lgoyal6.github.io/taut](https://lgoyal6.github.io/taut/), the real
 protocol code in your tab: your cursor becomes the message stream, and two receivers
 chase it through the same lossy link, a 25 ms retransmit floor against the kernel's
-200 ms.
+200 ms. That one covers the transport; the recording above covers membership.
 
 ## Thesis
 
diff --git a/docs/demo-setup.sh b/docs/demo-setup.sh
new file mode 100755
index 0000000..7e356a5
--- /dev/null
+++ b/docs/demo-setup.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Builds the SWIM mesh demo that docs/demo.tape records against. It runs on the
+# in-process SimNet and a virtual clock, so it is portable and deterministic:
+# the same numbers appear on macOS and Linux.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+cmake -S . -B build/demo -DCMAKE_BUILD_TYPE=Release >/dev/null
+cmake --build build/demo -j"$(sysctl -n hw.ncpu 2>/dev/null || nproc)" --target mesh_node >/dev/null
+echo "ready: $(pwd)/build/demo/mesh_node"
+echo "now run: vhs docs/demo.tape"
diff --git a/docs/demo.gif b/docs/demo.gif
new file mode 100644
index 0000000..ff06c7d
Binary files /dev/null and b/docs/demo.gif differ
diff --git a/docs/demo.tape b/docs/demo.tape
new file mode 100644
index 0000000..fe76649
--- /dev/null
+++ b/docs/demo.tape
@@ -0,0 +1,46 @@
+# Reproducible terminal demo: SWIM failure detection under a partition.
+#
+#   ./docs/demo-setup.sh && vhs docs/demo.tape
+#
+# Deterministic by construction (virtual clock, seeded SimNet drawn straight
+# from mt19937_64), so re-recording on Linux produces the same numbers.
+
+Output docs/demo.gif
+
+Set Shell zsh
+Set FontSize 14
+Set Width 1180
+Set Height 880
+Set Padding 18
+Set Theme "Builtin Dark"
+Set TypingSpeed 20ms
+
+Hide
+Type "clear" Enter
+Type "setopt interactive_comments" Enter
+Type "alias mesh_node=./build/demo/mesh_node" Enter
+Type "clear" Enter
+Show
+
+Sleep 600ms
+
+Type "# Five nodes gossiping their membership. No coordinator, no heartbeat storm."
+Enter
+Sleep 1000ms
+Type "# Partition one of them: how fast do the others notice, and do they overreact?"
+Enter
+Sleep 1400ms
+
+Type "mesh_node"
+Enter
+Sleep 4000ms
+
+Type "# 1020ms to the first SUSPECT, 2020ms to reconverge once the partition heals."
+Enter
+Sleep 1800ms
+Type "# The last line is the one that matters: a reachable node was never confirmed dead."
+Enter
+Sleep 2000ms
+Type "# Suspicion buys that. A node gets accused rather than executed, and can refute it."
+Enter
+Sleep 2600ms