diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b86b0af..5b11d65 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -89,14 +89,10 @@ Some files are produced by scripts; edit the generator, not the output:
 
 - `docs/commands.md` and the website command reference — `npm run docs:commands`
   (run after `npm run build`, which writes the oclif manifest).
-- `docs/demo.webp` (the animated README terminal) — `npm run docs:demo`, which
-  runs [VHS](https://github.com/charmbracelet/vhs) on `docs/demo.tape`. Requires
-  `vhs` and an ffmpeg built with **libwebp** (Homebrew's core ffmpeg lacks it):
-  `brew tap homebrew-ffmpeg/ffmpeg && brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-webp`.
-  Also needs an authenticated pdcli profile (use a sandbox). For a polished,
-  reproducible recording, first run `./scripts/seed-demo.sh` — it builds a clean
-  "pdcli demo" pipeline (sane deal values, a duplicate person, a stale deal so
-  `audit` has findings) and points the tape at it.
+- `docs/demo.svg` (the animated README terminal) — `npm run docs:demo`. It's a
+  self-contained, deterministic SMIL SVG (no fonts/scripts/network) drawn from
+  the curated `SCRIPT` scenes in `scripts/gen-demo.mjs`; edit the generator, not
+  the SVG.
 
 `oclif.manifest.json` is generated and git-ignored; never commit it.
 
diff --git a/README.md b/README.md
index 63718b0..1c8fbe5 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
 [![Docs](https://img.shields.io/badge/docs-wavyx.github.io%2Fpdcli-1292EE)](https://wavyx.github.io/pdcli/)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/wavyx/pdcli/main/docs/demo.webp" alt="pdcli demo — pipeline health, deal summary, and pipeline coverage" width="760">
+  <img src="https://raw.githubusercontent.com/wavyx/pdcli/main/docs/demo.svg" alt="pdcli demo — pipeline health, a won deal update, and a data-hygiene audit" width="820">
 </p>
 
 Command-line interface for [Pipedrive](https://www.pipedrive.com/) — fast, scriptable, built for terminals, CI pipelines, and AI agents.
diff --git a/docs/demo.svg b/docs/demo.svg
new file mode 100644
index 0000000..4ce1945
--- /dev/null
+++ b/docs/demo.svg
@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="880" height="382" viewBox="0 0 880 382" role="img" aria-label="Animated demo of pdcli: pipeline health, a winning deal update, and a data-hygiene audit">
+<style>
+text { font-family: 'SFMono-Regular', 'JetBrains Mono', 'Fira Code', Consolas, ui-monospace, monospace; font-size: 15px; white-space: pre; }
+.bar { fill: #6b7d72; font-size: 13px; }
+.prompt { fill: #4ade80; }
+.cmd { fill: #e6efe9; }
+.fg { fill: #cdddd3; }
+.dim { fill: #6b7d72; }
+.warn { fill: #e5c07b; }
+.ok { fill: #4ade80; }
+.cur { fill: #4ade80; }
+</style>
+<rect x="0" y="0" width="880" height="382" rx="14" fill="#0c1611"/>
+<rect x="0" y="0" width="880" height="44" rx="14" fill="#0a120e"/>
+<rect x="0" y="30" width="880" height="14" fill="#0a120e"/>
+<circle class="dot" cx="32" cy="22" r="6" fill="#ff5f56"/><circle class="dot" cx="52" cy="22" r="6" fill="#ffbd2e"/><circle class="dot" cx="72" cy="22" r="6" fill="#27c93f"/>
+<text x="104" y="26" class="bar">zsh · ~/acme</text>
+<g opacity="1"><clipPath id="type0"><rect x="26" y="70" height="36" width="0"><animate attributeName="width" begin="0s" dur="1.6s" from="0" to="231" fill="freeze" repeatCount="1"/><set attributeName="width" to="880" begin="1.6s" fill="freeze"/><set attributeName="width" to="0" begin="6s"/></rect></clipPath><text x="26" y="96" class="prompt">❯ </text><text x="48" y="96" class="cmd" clip-path="url(#type0)">pdcli pipeline health</text><rect x="279" y="81" width="11" height="18" class="cur" opacity="0"><animate attributeName="opacity" values="0;1" begin="0s" dur="0.01s" fill="freeze"/><animate attributeName="opacity" values="1;0" begin="5.8s" dur="0.01s" fill="freeze"/><animate attributeName="opacity" values="1;0;1" begin="1.6s" dur="0.8s" repeatCount="indefinite"/></rect><g opacity="0"><text x="26" y="148" class="dim">┌ SALES PIPELINE ───────────────── Q2 ┐</text><text x="26" y="174" class="fg">Qualified     18 deals    €142,000</text><text x="26" y="200" class="fg">Contact       11 deals    € 98,500</text><text x="26" y="226" class="fg">Proposal       7 deals    € 76,200</text><text x="26" y="252" class="fg">Negotiation    4 deals    € 51,000</text><text x="26" y="278" class="dim">─────────────────────────────────────</text><text x="26" y="304" class="ok">weighted forecast          €221,480</text><text x="26" y="330" class="dim">win rate 32% · avg cycle 24d</text><animate attributeName="opacity" values="0;1" begin="1.8s" dur="0.3s" fill="freeze"/><set attributeName="opacity" to="0" begin="6s"/></g><set attributeName="opacity" to="0" begin="6s"/></g><g opacity="0"><clipPath id="type1"><rect x="26" y="70" height="36" width="0"><animate attributeName="width" begin="6s" dur="1.6s" from="0" to="385" fill="freeze" repeatCount="1"/><set attributeName="width" to="880" begin="7.6s" fill="freeze"/><set attributeName="width" to="0" begin="12s"/></rect></clipPath><text x="26" y="96" class="prompt">❯ </text><text x="48" y="96" class="cmd" clip-path="url(#type1)">pdcli deal update 4821 --status won</text><rect x="433" y="81" width="11" height="18" class="cur" opacity="0"><animate attributeName="opacity" values="0;1" begin="6s" dur="0.01s" fill="freeze"/><animate attributeName="opacity" values="1;0" begin="11.8s" dur="0.01s" fill="freeze"/><animate attributeName="opacity" values="1;0;1" begin="7.6s" dur="0.8s" repeatCount="indefinite"/></rect><g opacity="0"><text x="26" y="148" class="ok">✓ Acme renewal → Won · activity logged</text><animate attributeName="opacity" values="0;1" begin="7.8s" dur="0.3s" fill="freeze"/><set attributeName="opacity" to="0" begin="12s"/></g><set attributeName="opacity" to="1" begin="6s"/><set attributeName="opacity" to="0" begin="12s"/></g><g opacity="0"><clipPath id="type2"><rect x="26" y="70" height="36" width="0"><animate attributeName="width" begin="12s" dur="1.6s" from="0" to="121" fill="freeze" repeatCount="1"/><set attributeName="width" to="880" begin="13.6s" fill="freeze"/></rect></clipPath><text x="26" y="96" class="prompt">❯ </text><text x="48" y="96" class="cmd" clip-path="url(#type2)">pdcli audit</text><rect x="169" y="81" width="11" height="18" class="cur" opacity="0"><animate attributeName="opacity" values="0;1" begin="12s" dur="0.01s" fill="freeze"/><animate attributeName="opacity" values="1;0;1" begin="13.6s" dur="0.8s" repeatCount="indefinite"/></rect><g opacity="0"><text x="26" y="148" class="dim">┌ DATA HYGIENE ──────────── 11 checks ┐</text><text x="26" y="174" class="warn">● 3 duplicate deals</text><text x="26" y="200" class="warn">● 5 deals stale &gt; 30 days</text><text x="26" y="226" class="dim">○ 8 missing a next step</text><text x="26" y="252" class="dim">─────────────────────────────────────</text><text x="26" y="278" class="ok">3 must-fix · audit --strict gates CI</text><animate attributeName="opacity" values="0;1" begin="13.799999999999999s" dur="0.3s" fill="freeze"/></g><set attributeName="opacity" to="1" begin="12s"/></g>
+</svg>
diff --git a/docs/demo.tape b/docs/demo.tape
deleted file mode 100644
index 1242cff..0000000
--- a/docs/demo.tape
+++ /dev/null
@@ -1,57 +0,0 @@
-# docs/demo.tape — regenerate the animated README terminal with VHS.
-#
-#   brew install vhs           # or: go install github.com/charmbracelet/vhs@latest
-#   npm run docs:demo          # runs: vhs docs/demo.tape  →  docs/demo.webp
-#
-# This records REAL pdcli output, so run it against an AUTHENTICATED profile —
-# point it at a sandbox/demo account, not production. The commands below are
-# read-only and show aggregates only (no contact PII). Swap them freely, but
-# avoid mutating commands so the recording is repeatable.
-
-# WebP: crisp + ~10x smaller than GIF, renders in a GitHub <img>. Needs an ffmpeg
-# built with libwebp — Homebrew's core ffmpeg lacks it, so install the tap build:
-#   brew tap homebrew-ffmpeg/ffmpeg && brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-webp
-Output docs/demo.webp
-
-Require pdcli
-
-# --- look & feel -------------------------------------------------------------
-Set Shell bash
-Set FontSize 16
-Set Width 1200          # wide enough that no output line clips (the old SVG was 720)
-Set Height 760
-Set Padding 28
-Set BorderRadius 12
-Set TypingSpeed 45ms
-Set CursorBlink true
-# Brand palette (matches the docs site / old demo): dark green ground, mint accent.
-Set Theme { "name": "pdcli", "background": "#0c1611", "foreground": "#c9d4cd", "cursor": "#4ade80", "selection": "#1f2b24", "black": "#0a120e", "brightBlack": "#6b7d72", "red": "#e06c75", "brightRed": "#e06c75", "green": "#4ade80", "brightGreen": "#4ade80", "yellow": "#e5c07b", "brightYellow": "#e5c07b", "blue": "#61afef", "brightBlue": "#61afef", "magenta": "#c678dd", "brightMagenta": "#c678dd", "cyan": "#56b6c2", "brightCyan": "#56b6c2", "white": "#c9d4cd", "brightWhite": "#ffffff" }
-
-# --- start clean -------------------------------------------------------------
-Hide
-Type "clear" Enter
-Show
-
-# --- scenes (read-only) ------------------------------------------------------
-# This account has 2 pipelines, so pipeline-scoped reports need --pipeline.
-# Each scene clears first (Hide/clear/Show) so output starts at the top — keeps
-# tall tables readable and one scene from bleeding into the next. Keep each
-# scene's output SHORT enough to fit the Height above (a full `field list` would
-# overflow and the frame catches it mid-scroll).
-Type "pdcli pipeline health --pipeline 1" Sleep 400ms Enter
-Sleep 3s
-
-Hide
-Type "clear" Enter
-Show
-Type "pdcli funnel --pipeline 1" Sleep 400ms Enter
-Sleep 3s
-
-Hide
-Type "clear" Enter
-Show
-Type "pdcli audit" Sleep 400ms Enter
-Sleep 3.5s
-
-# hold the final frame so the loop doesn't appear cut off
-Sleep 1.8s
diff --git a/docs/demo.webp b/docs/demo.webp
deleted file mode 100644
index 9bdd8bc..0000000
Binary files a/docs/demo.webp and /dev/null differ
diff --git a/package.json b/package.json
index 5590e08..db2bc5e 100644
--- a/package.json
+++ b/package.json
@@ -197,7 +197,7 @@
   "scripts": {
     "build": "oclif manifest",
     "docs:commands": "npm run build && node scripts/gen-commands.mjs",
-    "docs:demo": "vhs docs/demo.tape",
+    "docs:demo": "node scripts/gen-demo.mjs",
     "lint": "eslint . && prettier --check .",
     "lint:fix": "eslint --fix . && prettier --write .",
     "test": "vitest run",
diff --git a/scripts/gen-demo.mjs b/scripts/gen-demo.mjs
new file mode 100644
index 0000000..516b0d3
--- /dev/null
+++ b/scripts/gen-demo.mjs
@@ -0,0 +1,203 @@
+// Generates docs/demo.svg — a self-contained, animated SVG terminal that types
+// two real pdcli commands and reveals their output, on a ~12s loop.
+//
+// Constraints (so it renders inside a GitHub README <img>):
+//   - SMIL <animate> only — no <script>, no <foreignObject>, no external
+//     fonts/CSS. The only URL is the SVG namespace.
+//   - Deterministic: never reads the clock or uses randomness, so re-running
+//     the generator produces a byte-identical file (clean diffs in CI).
+//
+// Content mirrors the homepage hero (website/src/components/Home.astro): the
+// "pipeline health" report and the "deal update … --status won" confirmation.
+//
+// Run via `npm run docs:demo`. Do not hand-edit docs/demo.svg.
+import { writeFileSync, mkdirSync } from 'node:fs'
+
+// The SVG namespace URI is literally http://www.w3.org/2000/svg — it is an
+// identifier, not a fetched resource, and is required for the doc to be valid.
+const SVG_NS = 'http://www.w3.org/2000/svg'
+
+/** Escape the five XML-significant characters. `&` first to avoid doubling. */
+export function escapeXml(s) {
+  if (s === null || s === undefined) return ''
+  return String(s)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;')
+}
+
+// Each scene: a command that types out, then its rendered output lines.
+// A `cls` per line maps to a fill colour class defined once in <style>.
+export const SCRIPT = [
+  {
+    cmd: 'pdcli pipeline health',
+    out: [
+      { t: '┌ SALES PIPELINE ───────────────── Q2 ┐', cls: 'dim' },
+      { t: 'Qualified     18 deals    €142,000', cls: 'fg' },
+      { t: 'Contact       11 deals    € 98,500', cls: 'fg' },
+      { t: 'Proposal       7 deals    € 76,200', cls: 'fg' },
+      { t: 'Negotiation    4 deals    € 51,000', cls: 'fg' },
+      { t: '─────────────────────────────────────', cls: 'dim' },
+      { t: 'weighted forecast          €221,480', cls: 'ok' },
+      { t: 'win rate 32% · avg cycle 24d', cls: 'dim' },
+    ],
+  },
+  {
+    cmd: 'pdcli deal update 4821 --status won',
+    out: [{ t: '✓ Acme renewal → Won · activity logged', cls: 'ok' }],
+  },
+  {
+    cmd: 'pdcli audit',
+    out: [
+      { t: '┌ DATA HYGIENE ──────────── 11 checks ┐', cls: 'dim' },
+      { t: '● 3 duplicate deals', cls: 'warn' },
+      { t: '● 5 deals stale > 30 days', cls: 'warn' },
+      { t: '○ 8 missing a next step', cls: 'dim' },
+      { t: '─────────────────────────────────────', cls: 'dim' },
+      { t: '3 must-fix · audit --strict gates CI', cls: 'ok' },
+    ],
+  },
+]
+
+// Layout constants (px). Monospace metrics keep the typing reveal aligned.
+const FONT_SIZE = 15
+const WIDTH = 880 // roomy terminal width so no output line crowds the edge
+const PAD = 26
+const BAR_H = 44
+// Glyph advance used to PACE the typing reveal and place the caret. A slight
+// over-estimate of a 15px monospace advance; the rest state doesn't depend on
+// it being exact (the clip snaps fully open once typing finishes — see below).
+const CH = 11.0
+const LINE_H = 26
+const PROMPT = '❯ '
+const FONT_STACK =
+  "'SFMono-Regular', 'JetBrains Mono', 'Fira Code', Consolas, ui-monospace, monospace"
+
+// Per-scene timing (seconds). The demo plays through each scene once, ~6s each.
+const SCENE = 6
+const TYPE = 1.6 // time spent typing the command
+
+/** Build one scene as a <g> with SMIL reveal animations. */
+function renderScene(scene, index) {
+  const begin = index * SCENE
+  // The demo plays once and rests on the LAST scene (robust across renderers —
+  // no looping state to degenerate). So the last scene never resets/hides.
+  const isLast = index === SCRIPT.length - 1
+  const cmd = scene.cmd
+  const cmdChars = cmd.length
+  // Body baseline for the command line, then one row per output line.
+  const cmdY = BAR_H + PAD + LINE_H
+  const promptW = PROMPT.length * CH
+  const cmdW = cmdChars * CH
+
+  // Typing reveal: a clip rect whose width grows from 0 to the command width.
+  const clipId = `type${index}`
+  const clipReset = isLast
+    ? ''
+    : `<set attributeName="width" to="0" begin="${begin + SCENE}s"/>`
+  // Clip height runs from above the cap line to BELOW the baseline so glyph
+  // descenders (the tails of p/g/y) aren't sheared off — the rect's bottom must
+  // clear the baseline (cmdY), not sit on it.
+  const clipTop = cmdY - LINE_H
+  const clipH = LINE_H + 10
+  // Grow the clip to ~cmdW while "typing", then SNAP it fully open at TYPE end
+  // so the held command is never cropped — the rest state no longer depends on
+  // CH matching the viewer's exact glyph advance.
+  const revealFull = `<set attributeName="width" to="${WIDTH}" begin="${begin + TYPE}s" fill="freeze"/>`
+  const typing = `<clipPath id="${clipId}"><rect x="${PAD}" y="${clipTop}" height="${clipH}" width="0"><animate attributeName="width" begin="${begin}s" dur="${TYPE}s" from="0" to="${cmdW}" fill="freeze" repeatCount="1"/>${revealFull}${clipReset}</rect></clipPath>`
+
+  // The command text, clipped so it appears to type left-to-right.
+  const cmdText = `<text x="${PAD + promptW}" y="${cmdY}" class="cmd" clip-path="url(#${clipId})">${escapeXml(cmd)}</text>`
+
+  // Caret sits at the end of the typed text, blinking only during this scene.
+  const caretX = PAD + promptW + cmdW
+  // Last scene's caret keeps blinking on the resting frame; earlier scenes
+  // switch off at scene end (their whole group also fades out then).
+  const caretOff = isLast
+    ? ''
+    : `<animate attributeName="opacity" values="1;0" begin="${begin + SCENE - 0.2}s" dur="0.01s" fill="freeze"/>`
+  const caret = `<rect x="${caretX}" y="${cmdY - FONT_SIZE}" width="${CH}" height="${FONT_SIZE + 3}" class="cur" opacity="0"><animate attributeName="opacity" values="0;1" begin="${begin}s" dur="0.01s" fill="freeze"/>${caretOff}<animate attributeName="opacity" values="1;0;1" begin="${begin + TYPE}s" dur="0.8s" repeatCount="indefinite"/></rect>`
+
+  // Prompt glyph, always visible while the scene is on screen.
+  const prompt = `<text x="${PAD}" y="${cmdY}" class="prompt">${escapeXml(PROMPT)}</text>`
+
+  // Output lines fade in together once typing finishes.
+  let lines = ''
+  scene.out.forEach((ln, i) => {
+    const y = cmdY + (i + 2) * LINE_H
+    lines += `<text x="${PAD}" y="${y}" class="${ln.cls}">${escapeXml(ln.t)}</text>`
+  })
+  const outHide = isLast
+    ? ''
+    : `<set attributeName="opacity" to="0" begin="${begin + SCENE}s"/>`
+  const outGroup = `<g opacity="0">${lines}<animate attributeName="opacity" values="0;1" begin="${begin + TYPE + 0.2}s" dur="0.3s" fill="freeze"/>${outHide}</g>`
+
+  // Play-once sequence: scene 0 is visible from t=0 and hides when scene 1
+  // begins; the last scene appears at its `begin` and stays (rests). No reshow,
+  // so there's no loop state for a renderer to land on mid-degeneration.
+  let sceneVisible
+  if (isLast) {
+    sceneVisible =
+      index === 0
+        ? ''
+        : `<set attributeName="opacity" to="1" begin="${begin}s"/>`
+  } else if (index === 0) {
+    sceneVisible = `<set attributeName="opacity" to="0" begin="${begin + SCENE}s"/>`
+  } else {
+    sceneVisible = `<set attributeName="opacity" to="1" begin="${begin}s"/><set attributeName="opacity" to="0" begin="${begin + SCENE}s"/>`
+  }
+
+  return `<g opacity="${index === 0 ? 1 : 0}">${typing}${prompt}${cmdText}${caret}${outGroup}${sceneVisible}</g>`
+}
+
+/** Build the full demo SVG document as a deterministic string. */
+export function buildDemoSvg() {
+  // Tall enough for the prompt line + the largest output block.
+  const maxLines = Math.max(...SCRIPT.map((s) => s.out.length))
+  const height = BAR_H + PAD * 2 + LINE_H * (maxLines + 3)
+
+  const dotColors = ['#ff5f56', '#ffbd2e', '#27c93f']
+  const dots = dotColors
+    .map(
+      (c, i) =>
+        `<circle class="dot" cx="${PAD + 6 + i * 20}" cy="${BAR_H / 2}" r="6" fill="${c}"/>`,
+    )
+    .join('')
+
+  const title = `<text x="${PAD + 78}" y="${BAR_H / 2 + 4}" class="bar">zsh · ~/acme</text>`
+
+  const scenes = SCRIPT.map((s, i) => renderScene(s, i)).join('')
+
+  return `<svg xmlns="${SVG_NS}" width="${WIDTH}" height="${height}" viewBox="0 0 ${WIDTH} ${height}" role="img" aria-label="Animated demo of pdcli: pipeline health, a winning deal update, and a data-hygiene audit">
+<style>
+text { font-family: ${FONT_STACK}; font-size: ${FONT_SIZE}px; white-space: pre; }
+.bar { fill: #6b7d72; font-size: 13px; }
+.prompt { fill: #4ade80; }
+.cmd { fill: #e6efe9; }
+.fg { fill: #cdddd3; }
+.dim { fill: #6b7d72; }
+.warn { fill: #e5c07b; }
+.ok { fill: #4ade80; }
+.cur { fill: #4ade80; }
+</style>
+<rect x="0" y="0" width="${WIDTH}" height="${height}" rx="14" fill="#0c1611"/>
+<rect x="0" y="0" width="${WIDTH}" height="${BAR_H}" rx="14" fill="#0a120e"/>
+<rect x="0" y="${BAR_H - 14}" width="${WIDTH}" height="14" fill="#0a120e"/>
+${dots}
+${title}
+${scenes}
+</svg>
+`
+}
+
+/* CLI entry — guarded so imports stay pure (mirrors gen-commands.mjs). */
+const invokedDirectly =
+  process.argv[1] && import.meta.url === `file://${process.argv[1]}`
+
+if (invokedDirectly) {
+  mkdirSync(new URL('../docs/', import.meta.url), { recursive: true })
+  writeFileSync(new URL('../docs/demo.svg', import.meta.url), buildDemoSvg())
+  console.log('Wrote docs/demo.svg')
+}
diff --git a/scripts/seed-demo.sh b/scripts/seed-demo.sh
deleted file mode 100755
index 162d5ae..0000000
--- a/scripts/seed-demo.sh
+++ /dev/null
@@ -1,74 +0,0 @@
-#!/usr/bin/env bash
-#
-# seed-demo.sh — build a clean, realistic demo pipeline in your Pipedrive
-# SANDBOX so the README recording (docs/demo.tape → docs/demo.gif/webp) looks
-# polished instead of reflecting whatever junk a shared sandbox accumulated.
-#
-# It creates:
-#   - a "pdcli demo" pipeline with 4 stages (rising win probabilities)
-#   - 10 open deals with sane €values (per-stage totals mirror the hero frames)
-#   - 1 stale deal (old expected close) and a duplicate person, so `pdcli audit`
-#     has genuine findings to show
-# then rewrites the `--pipeline N` ids in docs/demo.tape to the new pipeline.
-#
-# Requires `pdcli` on PATH and an authenticated profile (use a SANDBOX, not
-# production — this writes data). Run once, then `npm run docs:demo`.
-#
-#   pdcli auth login            # or: export PDCLI_COMPANY_DOMAIN / PDCLI_API_TOKEN
-#   ./scripts/seed-demo.sh
-#
-# Everything lands in the new pipeline, so cleanup is just deleting it.
-
-set -euo pipefail
-
-command -v pdcli >/dev/null || { echo "pdcli not on PATH (npm i -g @wavyx/pdcli)"; exit 1; }
-pdcli api GET /api/v1/users/me >/dev/null 2>&1 || { echo "Not authenticated — run 'pdcli auth login' or set PDCLI_* env vars."; exit 1; }
-
-# Read `.data.id` from a raw `pdcli api` JSON response on stdin.
-id() { node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.stdout.write(String(JSON.parse(s).data.id)))'; }
-
-echo "Creating the 'pdcli demo' pipeline…"
-PID=$(pdcli api POST /api/v1/pipelines --body '{"name":"pdcli demo"}' | id)
-
-echo "Creating stages…"
-S1=$(pdcli api POST /api/v1/stages --body "{\"name\":\"Qualified\",\"pipeline_id\":$PID,\"deal_probability\":20}" | id)
-S2=$(pdcli api POST /api/v1/stages --body "{\"name\":\"Contact\",\"pipeline_id\":$PID,\"deal_probability\":40}" | id)
-S3=$(pdcli api POST /api/v1/stages --body "{\"name\":\"Proposal\",\"pipeline_id\":$PID,\"deal_probability\":60}" | id)
-S4=$(pdcli api POST /api/v1/stages --body "{\"name\":\"Negotiation\",\"pipeline_id\":$PID,\"deal_probability\":80}" | id)
-
-# title|value|stage — per-stage totals: 142k / 98.5k / 76.2k / 51k
-deal() {
-  pdcli api POST /api/v2/deals \
-    --body "{\"title\":\"$1\",\"value\":$2,\"currency\":\"EUR\",\"pipeline_id\":$PID,\"stage_id\":$3}" >/dev/null
-}
-
-echo "Creating deals…"
-deal "Initech onboarding"  60000 "$S1"
-deal "Umbrella pilot"      50000 "$S1"
-deal "Soylent trial"       32000 "$S1"
-deal "Hooli migration"     40000 "$S2"
-deal "Stark upgrade"       38500 "$S2"
-deal "Wayne add-on"        20000 "$S2"
-deal "Acme renewal"        50000 "$S3"
-deal "Globex expansion"    26200 "$S3"
-deal "Wonka enterprise"    30000 "$S4"
-deal "Cyberdyne seats"     21000 "$S4"
-
-# A long-stalled deal (old expected close, no activity) → stale-deal / next-step findings.
-pdcli api POST /api/v2/deals \
-  --body "{\"title\":\"Vandelay (stalled)\",\"value\":15000,\"currency\":\"EUR\",\"pipeline_id\":$PID,\"stage_id\":$S1,\"expected_close_date\":\"2024-01-01\"}" >/dev/null
-
-# Two persons sharing an email → duplicate-persons finding.
-echo "Creating a duplicate person for the audit scene…"
-for _ in 1 2; do
-  pdcli api POST /api/v2/persons \
-    --body '{"name":"Dana Demo","emails":[{"value":"dana@demo.example","primary":true}]}' >/dev/null
-done
-
-# Point the recording at the new pipeline.
-sed -i '' -E "s/--pipeline [0-9]+/--pipeline $PID/g" docs/demo.tape
-
-echo
-echo "Done. Demo pipeline id = $PID (docs/demo.tape updated)."
-echo "Record it:  npm run docs:demo"
-echo "Clean up later:  pdcli api DELETE /api/v1/pipelines/$PID  (deals go with it)"
diff --git a/test/gen-demo.test.js b/test/gen-demo.test.js
new file mode 100644
index 0000000..6edc5f4
--- /dev/null
+++ b/test/gen-demo.test.js
@@ -0,0 +1,128 @@
+import { describe, it, expect } from 'vitest'
+import { escapeXml, buildDemoSvg, SCRIPT } from '../scripts/gen-demo.mjs'
+
+describe('escapeXml', () => {
+  it('escapes the five XML-significant characters', () => {
+    expect(escapeXml('a & b')).toBe('a &amp; b')
+    expect(escapeXml('<tag>')).toBe('&lt;tag&gt;')
+    expect(escapeXml('say "hi"')).toBe('say &quot;hi&quot;')
+    expect(escapeXml("it's")).toBe('it&apos;s')
+  })
+
+  it('escapes ampersand before angle brackets so entities are not doubled', () => {
+    // A naive order would turn "<" into "&lt;" then "&" into "&amp;lt;".
+    expect(escapeXml('1 < 2 & 3 > 0')).toBe('1 &lt; 2 &amp; 3 &gt; 0')
+  })
+
+  it('coerces non-string input to a string', () => {
+    expect(escapeXml(4821)).toBe('4821')
+    expect(escapeXml(null)).toBe('')
+    expect(escapeXml(undefined)).toBe('')
+  })
+})
+
+describe('SCRIPT', () => {
+  it('runs the hero scenes — pipeline health, a won update, then an audit', () => {
+    expect(Array.isArray(SCRIPT)).toBe(true)
+    expect(SCRIPT).toHaveLength(3)
+    expect(SCRIPT[0].cmd).toBe('pdcli pipeline health')
+    expect(SCRIPT[1].cmd).toBe('pdcli deal update 4821 --status won')
+    expect(SCRIPT[2].cmd).toBe('pdcli audit')
+    // Each scene carries its rendered output lines (each a {t, cls} record).
+    for (const scene of SCRIPT) {
+      expect(typeof scene.cmd).toBe('string')
+      expect(Array.isArray(scene.out)).toBe(true)
+      expect(scene.out.length).toBeGreaterThan(0)
+      for (const line of scene.out) {
+        expect(typeof line.t).toBe('string')
+        expect(typeof line.cls).toBe('string')
+      }
+    }
+  })
+
+  it('shows a health table for the first scene', () => {
+    const out = SCRIPT[0].out.map((l) => l.t).join('\n')
+    expect(out).toMatch(/Qualified/)
+    expect(out).toMatch(/Negotiation/)
+  })
+
+  it('shows a won confirmation for the second scene', () => {
+    const out = SCRIPT[1].out.map((l) => l.t).join('\n')
+    expect(out).toMatch(/Won/)
+  })
+})
+
+describe('buildDemoSvg', () => {
+  it('emits a self-contained SVG root with width 880', () => {
+    const svg = buildDemoSvg()
+    expect(svg.startsWith('<svg')).toBe(true)
+    expect(svg.trimEnd().endsWith('</svg>')).toBe(true)
+    expect(svg).toContain('xmlns="http://www.w3.org/2000/svg"')
+    expect(svg).toContain('width="880"')
+  })
+
+  it('draws a dark rounded terminal frame with traffic-light dots', () => {
+    const svg = buildDemoSvg()
+    // dark terminal background
+    expect(svg).toContain('#0c1611')
+    // rounded 14px frame
+    expect(svg).toContain('rx="14"')
+    // three traffic-light dots
+    const dots = svg.match(/class="dot"/g) || []
+    expect(dots).toHaveLength(3)
+  })
+
+  it('uses a monospace font stack', () => {
+    expect(buildDemoSvg()).toMatch(/monospace/)
+  })
+
+  it('animates with SMIL, no scripts or foreignObject (GitHub <img> safe)', () => {
+    const svg = buildDemoSvg()
+    expect(svg).toContain('<animate')
+    // The resting caret blinks indefinitely on the final frame.
+    expect(svg).toContain('repeatCount="indefinite"')
+    // GitHub <img> sandbox forbids these.
+    expect(svg).not.toContain('foreignObject')
+    expect(svg).not.toContain('<script')
+  })
+
+  it('does not reference external fonts or scripts', () => {
+    const svg = buildDemoSvg()
+    // The only URL allowed is the SVG namespace identifier (not a fetched
+    // resource). Any other http(s) reference would mean an external dep.
+    const urls = svg.match(/https?:\/\/[^\s"']*/g) || []
+    expect(urls).toEqual(['http://www.w3.org/2000/svg'])
+  })
+
+  it('renders every command from the script', () => {
+    const svg = buildDemoSvg()
+    expect(svg).toContain('pdcli pipeline health')
+    expect(svg).toContain('pdcli deal update 4821 --status won')
+    expect(svg).toContain('pdcli audit')
+  })
+
+  it('escapes the escaping helper output and emits no raw stray entities', () => {
+    // The helper itself escapes angle brackets and ampersands in any text it
+    // is given (command or output) so the document stays well-formed XML.
+    const sample = escapeXml('pdcli api GET /deals?ids=<1>&n=2')
+    expect(sample).toContain('&lt;1&gt;')
+    expect(sample).toContain('&amp;n=2')
+
+    // And the rendered document has no dangling `&` (every `&` is an entity).
+    const svg = buildDemoSvg()
+    const danglingAmp = svg.match(/&(?!amp;|lt;|gt;|quot;|apos;|#)/g) || []
+    expect(danglingAmp).toEqual([])
+  })
+
+  it('is deterministic — two builds are byte-identical (no clock, no randomness)', () => {
+    expect(buildDemoSvg()).toBe(buildDemoSvg())
+  })
+
+  it('plays once and rests — the last scene reveals at 6s and never hides', () => {
+    const svg = buildDemoSvg()
+    // Scene 2 (the won confirmation) appears at t=6s…
+    expect(svg).toContain('begin="6s"')
+    // …and there is no reshow/loop marker that could degenerate after one pass.
+    expect(svg).not.toContain('dur="12s"')
+  })
+})