diff --git a/.gitignore b/.gitignore
index 232dce9..3c4ebb2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,6 @@
 *.exe
 *.test
 *.out
+demo.gif
+demo.mp4
+demo.webm
diff --git a/Makefile b/Makefile
index 223253c..88acaca 100644
--- a/Makefile
+++ b/Makefile
@@ -4,7 +4,7 @@ VERSION_PKG := task/internal/version
 GIT_HASH    := $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)
 LDFLAGS     := -X $(VERSION_PKG).BuildVersion=$(GIT_HASH)
 
-.PHONY: build run version
+.PHONY: build run version demo
 
 build:
 	go build -ldflags "$(LDFLAGS)" -o bin/$(BINARY) $(CMD)
@@ -14,3 +14,7 @@ run: build
 
 version: build
 	./bin/$(BINARY) version
+
+# Record a full feature walkthrough (requires vhs: https://github.com/charmbracelet/vhs)
+demo:
+	vhs demo.tape
diff --git a/demo.tape b/demo.tape
new file mode 100644
index 0000000..cfd1baf
--- /dev/null
+++ b/demo.tape
@@ -0,0 +1,204 @@
+# task-master feature demo
+# Run from repo root:  make demo   (or: vhs demo.tape)
+#
+# Skips external $EDITOR flows (e / ctrl+e) — those need an interactive editor.
+
+Output demo.gif
+Output demo.mp4
+
+Require go
+
+Set Shell "bash"
+Set FontSize 14
+Set Width 1280
+Set Height 820
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 35ms
+Set PlaybackSpeed 1.0
+Set Padding 12
+Set Framerate 30
+
+# Isolated config/data so the demo never touches your real ~/.config
+Env HOME "/tmp/task-master-vhs"
+Env TERM "xterm-256color"
+
+# --- setup (hidden) ----------------------------------------------------------
+Hide
+Type "rm -rf /tmp/task-master-vhs && mkdir -p /tmp/task-master-vhs"
+Enter
+Sleep 300ms
+Type "make build"
+Enter
+Sleep 5s
+Show
+
+# --- launch ------------------------------------------------------------------
+Type "./bin/task-master"
+Enter
+Sleep 1s
+
+# --- create tickets ----------------------------------------------------------
+Type "n"
+Sleep 400ms
+Type "Design landing page"
+Enter
+Sleep 800ms
+
+Type "n"
+Sleep 400ms
+Type "Wire up auth"
+Enter
+Sleep 800ms
+
+Type "n"
+Sleep 400ms
+Type "Ship MVP checklist"
+Enter
+Sleep 1s
+
+# --- navigate ----------------------------------------------------------------
+Type "k"
+Sleep 400ms
+Type "k"
+Sleep 600ms
+Type "j"
+Sleep 800ms
+
+# --- status picker (letter jump) ---------------------------------------------
+Type "s"
+Sleep 800ms
+Type "w"
+Sleep 500ms
+Enter
+Sleep 1s
+
+# --- board filter (multiselect) ----------------------------------------------
+Type "l"
+Sleep 800ms
+Type "b"
+Sleep 300ms
+Space
+Sleep 400ms
+Type "i"
+Sleep 300ms
+Space
+Sleep 400ms
+Enter
+Sleep 1s
+
+# show all again
+Type "l"
+Sleep 600ms
+Type "a"
+Sleep 300ms
+Enter
+Sleep 800ms
+
+# --- search / filter ---------------------------------------------------------
+Type "/"
+Sleep 400ms
+Type "auth"
+Enter
+Sleep 1s
+Type "/"
+Sleep 300ms
+Enter
+Sleep 800ms
+
+# --- projects: create + switch -----------------------------------------------
+Type "p"
+Sleep 800ms
+Type "n"
+Sleep 400ms
+Type "client-acme"
+Enter
+Sleep 1s
+
+Type "n"
+Sleep 400ms
+Type "Kickoff call notes"
+Enter
+Sleep 1s
+
+Type "p"
+Sleep 800ms
+Type "i"
+Sleep 400ms
+Enter
+Sleep 1s
+
+# --- timer -------------------------------------------------------------------
+Type "j"
+Sleep 300ms
+Type "t"
+Sleep 1.5s
+Type "t"
+Sleep 1s
+
+# --- manual time log ---------------------------------------------------------
+Type "T"
+Sleep 500ms
+Type "45m"
+Enter
+Sleep 1s
+
+# --- manage time entries (edit duration) -------------------------------------
+Type "m"
+Sleep 1s
+Type "e"
+Sleep 500ms
+Backspace 3
+Type "1h15m"
+Enter
+Sleep 1s
+Escape
+Sleep 800ms
+
+# --- report + group-by picker ------------------------------------------------
+Type "r"
+Sleep 1.2s
+Type "g"
+Sleep 800ms
+Type "t"
+Sleep 400ms
+Enter
+Sleep 1.2s
+Type "g"
+Sleep 600ms
+Type "d"
+Sleep 400ms
+Enter
+Sleep 1.2s
+Escape
+Sleep 800ms
+
+# --- undo / redo -------------------------------------------------------------
+Type "u"
+Sleep 1s
+Type "U"
+Sleep 1s
+
+# --- delete with confirm -----------------------------------------------------
+Type "n"
+Sleep 400ms
+Type "throwaway ticket"
+Enter
+Sleep 800ms
+Type "x"
+Sleep 700ms
+Type "y"
+Sleep 1s
+
+# --- force delete ------------------------------------------------------------
+Type "n"
+Sleep 400ms
+Type "another draft"
+Enter
+Sleep 700ms
+Type "X"
+Sleep 1s
+
+# --- done --------------------------------------------------------------------
+Sleep 1.5s
+Type "q"
+Sleep 500ms