diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a82685f..f8c232e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -64,31 +64,29 @@ always use `UPDATE_GOLDEN=1` to regenerate them from a passing smoosh run.
 
 ## Updating the Demos
 
-The demos are recorded with [VHS](https://github.com/charmbracelet/vhs)
-(`brew install vhs`). There are three tape files:
+The demos live in `assets/`. The interactive demo has a
+[VHS](https://github.com/charmbracelet/vhs) tape file (`brew install vhs`):
 
 | Tape | Output | Shows |
 | --- | --- | --- |
-| `demo-logo.tape` | `demo-logo.gif` | Banner logo (README hero) |
-| `demo.tape` | `demo.gif` | Interactive mode flow |
-| `demo-power.tape` | `demo-power.gif` | Power-user flags |
+| `assets/demo.tape` | `assets/demo.gif` | Interactive mode flow |
 
-Re-record after the relevant change:
+The other GIFs (`demo-logo.gif`, `demo-power.gif`) are recorded manually.
 
-| When to re-record | Tapes affected |
+Re-record when relevant:
+
+| When to re-record | Files affected |
 | --- | --- |
-| Visual style changes (colours, banner, symbols) | `demo-logo.tape`, `demo.tape` |
-| Interactive mode UI changes | `demo.tape` |
-| New major flags or output format changes | `demo-power.tape` |
+| Visual style changes (colours, banner, symbols) | `assets/demo-logo.gif`, `assets/demo.gif` |
+| Interactive mode UI changes | `assets/demo.gif` |
+| New major flags or output format changes | `assets/demo-power.gif` |
 
 ```bash
-vhs demo-logo.tape    # logo — re-record when visual style changes
-vhs demo.tape         # interactive flow — re-record when UI changes
-vhs demo-power.tape   # power-user flags — re-record when flags change
+vhs assets/demo.tape  # interactive flow — re-record when UI changes
 ```
 
 Commit the updated `.gif` files alongside the code change that prompted the
-re-record. The tapes are the source of truth — never edit the GIFs by hand.
+re-record.
 
 ## Code Style
 
diff --git a/README.md b/README.md
index bc28528..bba89f7 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 <div align="center">
 
-![smoosh logo](demo-logo.gif)
+![smoosh logo](assets/demo-logo.gif)
 
 [![CI](https://github.com/K1-R1/smoosh/actions/workflows/ci.yml/badge.svg)](https://github.com/K1-R1/smoosh/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
@@ -12,7 +12,7 @@
 Turn any git repo into AI-ready context — for NotebookLM, Claude Projects,
 ChatGPT, or your own RAG pipeline. Pure bash, zero dependencies.
 
-![smoosh interactive demo](demo.gif)
+![smoosh interactive demo](assets/demo.gif)
 
 </div>
 
@@ -90,7 +90,7 @@ telemetry. Private repos need this. Public ones benefit too.
 
 Preview, filter, and pipe — all from flags:
 
-![smoosh power user demo](demo-power.gif)
+![smoosh power user demo](assets/demo-power.gif)
 
 ## Installation
 
diff --git a/demo-logo.gif b/assets/demo-logo.gif
similarity index 100%
rename from demo-logo.gif
rename to assets/demo-logo.gif
diff --git a/demo-logo.png b/assets/demo-logo.png
similarity index 100%
rename from demo-logo.png
rename to assets/demo-logo.png
diff --git a/demo-power.gif b/assets/demo-power.gif
similarity index 100%
rename from demo-power.gif
rename to assets/demo-power.gif
diff --git a/demo.gif b/assets/demo.gif
similarity index 100%
rename from demo.gif
rename to assets/demo.gif
diff --git a/demo.tape b/assets/demo.tape
similarity index 94%
rename from demo.tape
rename to assets/demo.tape
index 885421c..2143440 100644
--- a/demo.tape
+++ b/assets/demo.tape
@@ -1,8 +1,8 @@
 # smoosh demo — interactive mode (hero)
-# Record with: vhs demo.tape
+# Record with: vhs assets/demo.tape
 # Requires: brew install vhs
 
-Output demo.gif
+Output assets/demo.gif
 
 Require bash