diff --git a/CLAUDE.md b/CLAUDE.md
index a8029cb..7716544 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,7 +11,7 @@ A public kit that installs a session workflow into someone's Claude Code: four s
 - `karabiner/` `build.py` generates both rule files; never edit the JSON by hand
 - `install/` `install.sh` (check / plan / apply / verify / uninstall) plus the three Python helpers it calls: `merge-settings.py` (hook registrations), `update-claude-md.py` (the marked block), `manifest.py` (the install record uninstall replays)
 - `tests/run.sh` the whole suite, in a throwaway HOME
-- `docs/images/` the three figures the README embeds and the 1280x640 social preview; `.github/workflows/tests.yml` runs `tests/run.sh` on a macOS runner for every pull request and every push to `main`
+- `docs/images/` the three figures the README embeds, the explainer video thumbnail and the 1280x640 social preview; `.github/workflows/tests.yml` runs `tests/run.sh` on a macOS runner for every pull request and every push to `main`
 
 ## Rules for changes
 
diff --git a/README.md b/README.md
index 9627aca..1c48569 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,10 @@
 
 Keep the plan when you run `/compact`, and never end a session with work that exists only in chat. Four slash commands, two hooks and five one-handed keyboard shortcuts. This is the setup I run every day.
 
+[![The explainer video: Claude Code's /compact is broken. A Claude Code session card with a four-step plan and a context bar.](docs/images/explainer-video.webp)](https://youtu.be/7tXR1H3viRg)
+
+[Watch the explainer on YouTube](https://youtu.be/7tXR1H3viRg): what /compact loses, and what each of the five shortcuts does.
+
 ![Compacting a session. Before: four steps by hand, /compact-check, copy block, /compact, paste block. Now: two keys, Right Option plus comma for /compact-check and Right Option plus period for /compact.](docs/images/before-after.webp)
 
 ## Install with one prompt
diff --git a/docs/README.md b/docs/README.md
index 2e59591..2fa6b71 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,4 +5,4 @@ Design notes for the kit. User-facing material is in the repo root: [README.md](
 - [architecture.md](architecture.md): the components, the compact-resume data flow, the state directory, the installer's algorithm, and which behaviours are documented by Claude Code versus only observed.
 - [decisions/](decisions/README.md): architecture decision records.
   - [001-shortcuts-live-in-karabiner.md](decisions/001-shortcuts-live-in-karabiner.md): why the keyboard shortcuts are a Karabiner rule and not a Claude Code keybinding, and what each shortcut types.
-- [images/](images/): the three figures the README embeds and the social preview image for the GitHub page.
+- [images/](images/): the three figures the README embeds, the explainer video thumbnail and the social preview image for the GitHub page.
diff --git a/docs/images/explainer-video.webp b/docs/images/explainer-video.webp
new file mode 100644
index 0000000..995c0a4
Binary files /dev/null and b/docs/images/explainer-video.webp differ