move demo/ to docs/tutorial/, commit assets, consolidate TUI docs

- demo/ renamed to docs/tutorial/ (tapes, scripts, TUTORIAL.md)
- docs/tutorial/assets/ added to git (51 MB of GIFs + PNGs); removed
  /demo/assets/ from .gitignore so images render on Codeberg
- docs/tui-reference.md removed; its hotkey tables merged into a new
  "Hotkey Quick Reference" section at the end of TUTORIAL.md
- TUTORIAL.md: updated install section (mage buildDocker, no
  GOTOOLCHAIN=auto), fixed README relative path (../../README.md),
  updated internal tapes/scripts/assets path prose
- README.md: updated all demo/ image paths and links to docs/tutorial/;
  TUI and recording-modes links now point to TUTORIAL.md anchors
- AGENTS.md: updated demo/ references to docs/tutorial/
- Magefile.go: updated demoDir/demoTapesDir/demoScriptsDir/demoRunTape/
  demoSudoKeepers constants to docs/tutorial/ paths

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

3 files changed, 142 insertions, 0 deletions

diff --git a/docs/tutorial/scripts/run-tape.sh b/docs/tutorial/scripts/run-tape.sh
new file mode 100755
index 0000000..c22e2e3
--- /dev/null
+++ b/docs/tutorial/scripts/run-tape.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# One-tape wrapper: starts the background workload, runs vhs <tape>, kills the
+# workload. Tapes themselves don't need to know about the workload — they just
+# launch ior and drive the TUI.
+#
+# vhs is invoked with cwd set to the repo root, so all paths inside tapes
+# (Output, Screenshot, the ./ior binary) are repo-relative.
+#
+# Usage: run-tape.sh <path-to-tape>
+
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+    echo "usage: $0 <tape-file>" >&2
+    exit 2
+fi
+
+TAPE="$(realpath "$1")"
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+WORKLOAD="${ROOT}/demo/scripts/workload.sh"
+
+if [ ! -f "$TAPE" ]; then
+    echo "tape not found: $TAPE" >&2
+    exit 2
+fi
+
+# Pre-flight: vhs and ttyd must be on PATH; sudo timestamp must be live.
+command -v vhs >/dev/null || { echo "vhs not on PATH (run: mage installDemoTools)" >&2; exit 3; }
+command -v ttyd >/dev/null || { echo "ttyd not on PATH (run: mage installDemoTools)" >&2; exit 3; }
+sudo -n true 2>/dev/null || { echo "sudo timestamp expired (run: sudo -v)" >&2; exit 4; }
+
+# Start workload in its own session/process group so we can kill the whole tree.
+setsid "$WORKLOAD" </dev/null >/dev/null 2>&1 &
+WL_PID=$!
+
+cleanup() {
+    if kill -0 "$WL_PID" 2>/dev/null; then
+        # The workload runs `setsid` so its PID == its PGID.
+        kill -TERM -- "-$WL_PID" 2>/dev/null || true
+        sleep 0.5
+        kill -KILL -- "-$WL_PID" 2>/dev/null || true
+    fi
+    # Best-effort: stop any straggling ior processes from this tape.
+    sudo -n pkill -TERM -f '/ior$' 2>/dev/null || true
+}
+trap cleanup EXIT INT TERM
+
+# Give the workload a moment to spool up before recording.
+sleep 2
+
+cd "$ROOT"
+vhs "$TAPE"
diff --git a/docs/tutorial/scripts/sudo-keepalive.sh b/docs/tutorial/scripts/sudo-keepalive.sh
new file mode 100755
index 0000000..4ae1e27
--- /dev/null
+++ b/docs/tutorial/scripts/sudo-keepalive.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Refreshes the sudo timestamp every minute so a long demo regen never trips a
+# password prompt. Intended to be backgrounded by `mage demo` and killed at the
+# end of the run.
+
+set -u
+
+trap 'exit 0' TERM INT
+
+while true; do
+    sudo -n true 2>/dev/null || exit 1
+    sleep 60
+done
diff --git a/docs/tutorial/scripts/workload.sh b/docs/tutorial/scripts/workload.sh
new file mode 100755
index 0000000..ebbf58b
--- /dev/null
+++ b/docs/tutorial/scripts/workload.sh
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Background workload for demo tapes. Generates a steady mix of file I/O
+# (open/read/close), big writes (fsync/dd), stat-heavy traffic, and ioworkload
+# scenarios so every TUI tab has something interesting to display.
+#
+# Designed to be killed via `kill $!` from the tape wrapper. All children are
+# placed in this script's process group so a single signal cleans them up.
+
+set -u
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+IOWORKLOAD="${ROOT}/../ioworkload"
+SCRATCH="$(mktemp -d -t ior-demo-workload-XXXXXX)"
+trap 'rm -rf "$SCRATCH"' EXIT
+
+cleanup() {
+    trap - TERM INT
+    # Kill the entire process group so all background loops stop.
+    kill -- -$$ 2>/dev/null || true
+    exit 0
+}
+trap cleanup TERM INT
+
+# A) walk /usr and read first byte of each file: tons of openat/read/close + varied paths.
+(
+    while true; do
+        find /usr/share /usr/lib -maxdepth 4 -type f 2>/dev/null \
+            | shuf -n 800 \
+            | xargs -r -I{} sh -c 'head -c 1 "{}" >/dev/null 2>&1' || true
+        sleep 1
+    done
+) &
+
+# B) periodic large write with fsync via dd: fills the latency tab with slow writes.
+(
+    while true; do
+        dd if=/dev/zero of="${SCRATCH}/big.bin" bs=1M count=20 conv=fsync status=none 2>/dev/null || true
+        sleep 3
+        rm -f "${SCRATCH}/big.bin"
+    done
+) &
+
+# C) stat-heavy directory crawl: feeds the syscall tab with newfstatat/getdents.
+(
+    while true; do
+        find /etc /var/log -maxdepth 3 >/dev/null 2>&1 || true
+        sleep 2
+    done
+) &
+
+# D) ioworkload scenario rotation if the binary exists: gives us syscall variety
+# beyond what the shell utilities trigger (mmap, dup, fcntl, sync, rename, link).
+if [ -x "$IOWORKLOAD" ]; then
+    (
+        scenarios=(
+            open-basic
+            readwrite-basic
+            stat-basic
+            stat-statx
+            mmap-basic
+            sync-basic
+            dup-basic
+            fcntl-dupfd
+            rename-basic
+            link-basic
+            dir-basic
+        )
+        while true; do
+            for s in "${scenarios[@]}"; do
+                "$IOWORKLOAD" --scenario="$s" >/dev/null 2>&1 || true
+            done
+        done
+    ) &
+fi
+
+# Idle until killed.
+wait