diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 06dcf06..3cb5328 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -6,7 +6,7 @@ Human docs for this plugin. First-run is the README (omp marketplace `pstack@pst
 
 ## Ownership
 
-- `guide/` — numbered walkthrough (01–10 plus images). Images still come from `cursor/plugins` `pstack/docs/guide/`.
+- `guide/` — numbered walkthrough (01–10 plus images). Tutorial stills still come from `cursor/plugins` `pstack/docs/guide/`. `images/pstack-demo.gif` is live Terminal stills of omp (`/poteto-mode`, playbook todos, `npm run sync -- --dry-run`).
 
 ## Local Contracts
 
diff --git a/docs/guide/README.md b/docs/guide/README.md
index b70876b..2315a67 100644
--- a/docs/guide/README.md
+++ b/docs/guide/README.md
@@ -4,6 +4,8 @@ In this tutorial we'll run pstack on a real task. First-run is the [README](../.
 
 Give a goal and a way to check it, in your own words. `/poteto-mode` picks the playbook, runs the other skills, and shows the evidence.
 
+![How pstack works](./images/pstack-demo.gif)
+
 Read these pages in order the first time. After that, each page stands alone.
 
 1. [Set up pstack](./01-setup.md). Install the plugin and pick your models.
diff --git a/docs/guide/images/README.txt b/docs/guide/images/README.txt
new file mode 100644
index 0000000..295db1e
--- /dev/null
+++ b/docs/guide/images/README.txt
@@ -0,0 +1,13 @@
+Rebuild pstack-demo.gif
+
+Film a live omp session in Terminal.app. Do not print fake /poteto-mode text.
+
+Beats:
+1. omp (plugin=loaded)
+2. type /poteto-mode
+3. statusline poteto on, /skill:do-poteto-mode sent
+4. a goal (guide example: users get two notifications after a retry. repro first, then fix and verify.)
+5. matched playbook name plus copied todos
+6. npm run sync -- --dry-run (sot: cursor/plugins pstack/skills → skills/do-*)
+
+Stitch frames with ImageMagick. vhs 0.12.0 may exit 0 with no file on this host. Do not Type omp inside a vhs tape.
diff --git a/docs/guide/images/pstack-demo.gif b/docs/guide/images/pstack-demo.gif
new file mode 100644
index 0000000..cf0cc73
Binary files /dev/null and b/docs/guide/images/pstack-demo.gif differ
diff --git a/docs/guide/images/pstack-demo.tape b/docs/guide/images/pstack-demo.tape
new file mode 100644
index 0000000..187d52a
--- /dev/null
+++ b/docs/guide/images/pstack-demo.tape
@@ -0,0 +1,12 @@
+# Live GIF is Terminal stills of omp, not this tape.
+# vhs 0.12.0 may exit 0 with no file. Do not Type omp (TUI).
+Output "/Users/ed/Developer/Atlas/PstackForPi/docs/guide/images/pstack-demo.gif"
+Require bash
+Set FontSize 16
+Set Width 1200
+Set Height 800
+Set Theme "Catppuccin Mocha"
+Set Shell bash
+Type "echo film omp in Terminal.app; see docs/guide/images/README.txt"
+Enter
+Sleep 2s