diff --git a/README.md b/README.md
index 1e83a23..c5736ad 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,8 @@ starts where the last one left off.
 [![license](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](#license)
 [![rust](https://img.shields.io/badge/rust-1.85%2B-informational)](https://www.rust-lang.org)
 
+<img src="docs/assets/demo.gif" alt="Kimetsu demo: one-command setup, selftest, record a lesson, retrieve it by meaning" width="920" />
+
 </div>
 
 ---
@@ -79,8 +81,9 @@ in **[HOW-KIMETSU-WORKS](docs/HOW-KIMETSU-WORKS.md)**.
 ## Quickstart
 
 ```bash
-# 1. Install (cargo shown; npm + prebuilt archives in docs/INSTALL.md)
-cargo install kimetsu-cli --features embeddings   # or plain for the lean FTS build
+# 1. Install — no Rust toolchain needed (cargo + prebuilt archives in docs/INSTALL.md)
+npm install -g kimetsu-ai
+kimetsu npm-flavor embeddings        # one-time: enable semantic retrieval
 
 # 2. Wire it into your host agent — init + install + selftest in one shot
 cd /your/project
diff --git a/docs/assets/demo.gif b/docs/assets/demo.gif
new file mode 100644
index 0000000..32b8ede
Binary files /dev/null and b/docs/assets/demo.gif differ
diff --git a/docs/assets/demo.tape b/docs/assets/demo.tape
new file mode 100644
index 0000000..5267d1d
--- /dev/null
+++ b/docs/assets/demo.tape
@@ -0,0 +1,66 @@
+# Kimetsu demo — render with charmbracelet/vhs:
+#
+#   brew install vhs        # macOS        (needs ffmpeg + ttyd)
+#   scoop install vhs       # Windows
+#   go install github.com/charmbracelet/vhs@latest
+#
+#   cd a scratch directory with `kimetsu` on PATH, then:
+#   vhs path/to/demo.tape   # writes docs/assets/demo.gif
+#
+# The tape runs REAL commands — kimetsu must be installed (the embeddings
+# build makes the semantic-recall beat land). Re-record after big UX changes.
+
+Output docs/assets/demo.gif
+
+Set Theme "Catppuccin Mocha"
+Set FontSize 12
+Set Width 1100
+Set Height 620
+Set Padding 12
+Set TypingSpeed 30ms
+Set PlaybackSpeed 2.5
+
+# ── Hidden setup: a fresh scratch project ────────────────────────────────────
+Hide
+Type "mkdir kimetsu-demo"
+Enter
+Type "cd kimetsu-demo"
+Enter
+Type "git init -q"
+Enter
+Type "clear"
+Enter
+Sleep 2s
+Show
+
+# ── Beat 1: one command to prove the brain works ─────────────────────────────
+Type "kimetsu setup --host claude-code --no-setup"
+Enter
+# embeddings model loads in-process — give the selftest room
+Sleep 35s
+
+Type "kimetsu doctor --selftest"
+Enter
+Sleep 20s
+# prints: ✓ recorded a memory and retrieved it — the brain works
+
+Sleep 1s
+Type "clear"
+Enter
+
+# ── Beat 2: record a lesson the way an agent would ───────────────────────────
+Type `kimetsu brain memory add --scope project --kind failure_pattern "Tests pass alone but fail under 'cargo test --workspace': a new crate with default embeddings flips feature unification for every sibling crate. Keep new crates' default = [] and opt in explicitly."`
+Enter
+Sleep 14s
+
+# ── Beat 3: retrieve it with DIFFERENT words — semantic recall ───────────────
+Type `kimetsu brain context "why does my test only break in the full CI run?"`
+Enter
+Sleep 20s
+
+# ── Beat 4: the brain measures itself ────────────────────────────────────────
+Type "kimetsu brain insights"
+Enter
+Sleep 12s
+
+Sleep 3s