diff --git a/README.md b/README.md
index 7095006..292248b 100644
--- a/README.md
+++ b/README.md
@@ -2,38 +2,18 @@
 
 Trace the transitive import weight of any TypeScript or Python entry point. Point it at a file, get back what gets pulled in at startup and how much code it costs.
 
-```
-$ chainsaw trace src/index.ts
-
-src/index.ts
-Static transitive weight: 8.2 MB (2140 modules)
-Dynamic-only weight: 120 KB (34 modules, not loaded at startup)
-
-Heavy dependencies (static):
-  undici                              1.1 MB  108 files
-    -> src/index.ts -> src/http/client.ts -> undici
-  date-fns                            619 KB  304 files
-    -> src/index.ts -> src/jobs/scheduler.ts -> date-fns
-  zod                                 537 KB  76 files
-    -> src/index.ts -> src/api/routes.ts -> src/api/validation.ts -> zod
-
-Modules (sorted by exclusive weight):
-  src/generated/api-types.ts                                412 KB
-  src/i18n/locales.ts                                       238 KB
-  src/api/routes.ts                                         127 KB
-  ...
-```
+![chainsaw demo](docs/demo.gif)
 
 Only static imports count toward the weight. Dynamic `import()` and type-only imports are tracked separately.
 
 ## Install
 
-Requires Rust 1.91+:
-
 ```
 cargo install chainsaw-cli
 ```
 
+Requires Rust 1.91+.
+
 ## Usage
 
 ### Python
diff --git a/docs/demo.gif b/docs/demo.gif
new file mode 100644
index 0000000..fc92ad2
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..2154353
--- /dev/null
+++ b/docs/demo.tape
@@ -0,0 +1,74 @@
+# VHS tape file for recording the chainsaw demo GIF.
+# Install VHS: https://github.com/charmbracelet/vhs
+# Render: vhs docs/demo.tape
+#
+# Pixel-perfect rendering. Requires chainsaw on PATH and
+# workers-sdk cloned at the path below.
+
+Output docs/demo.gif
+Set Shell bash
+Set FontFamily "JetBrains Mono"
+Set FontSize 16
+Set Width 1200
+Set Height 700
+Set Theme "Monokai"
+Set TypingSpeed 45ms
+Set Padding 20
+
+# --- Scene 1: Trace wrangler ---
+
+Type "# How much code does wrangler pull in on startup?"
+Enter
+Sleep 800ms
+
+Type "cd packages/wrangler && chainsaw trace src/index.ts"
+Enter
+Sleep 3s
+
+# --- Scene 2: Find the cut point ---
+
+Type "# 2.7 MB across 467 modules. Find the cut point:"
+Enter
+Sleep 800ms
+
+Type "chainsaw trace src/index.ts --cut @cloudflare/workers-utils"
+Enter
+Sleep 2.5s
+
+# --- Scene 3: Chain analysis ---
+
+Type "# One file gates everything. How does start-dev get pulled in?"
+Enter
+Sleep 800ms
+
+Type "chainsaw trace src/index.ts --chain src/dev/start-dev.ts"
+Enter
+Sleep 2.5s
+
+# --- Scene 4: Cut attempt ---
+
+Type "# Two independent paths -- can we cut it?"
+Enter
+Sleep 800ms
+
+Type "chainsaw trace src/index.ts --cut src/dev/start-dev.ts"
+Enter
+Sleep 2.5s
+
+# --- Scene 5: Compare with miniflare ---
+
+Type "# No single cut. Compare with a well-structured package:"
+Enter
+Sleep 800ms
+
+Type "cd ../miniflare && chainsaw trace src/index.ts"
+Enter
+Sleep 2.5s
+
+Type "# 689 KB, 103 modules, zero third-party deps."
+Enter
+Sleep 1s
+
+Type "# cargo install chainsaw-cli"
+Enter
+Sleep 2s