From 5a818942bf158e5a1963e10e6d8dda524eaeb30b Mon Sep 17 00:00:00 2001
From: Ralf Anton Beier <ralf_beier@me.com>
Date: Fri, 29 May 2026 07:19:03 +0200
Subject: [PATCH] feat(tools): scaffold re-generatable intro-video
 infrastructure (tools/intro-video/)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reusable infrastructure to auto-generate a 30–60s rivet intro/quickstart
video: Playwright recordVideo (deterministic capture) → piper TTS (local,
MIT, no API key, CI-able) → ffmpeg mux. Single storyboard.json drives
scene actions + timing + narration so the clip regenerates after UI
changes rather than being hand-edited.

Files:
- storyboard.json   — source of truth: 7 scenes, hold_ms timing, narration
                      (~39s nominal, ~135 words, PulseEngine voice)
- capture.spec.ts   — Playwright spec; one continuous video; renders the
                      title / CLI-help / outro as in-browser panels so
                      there's one timeline to sync narration against
- playwright.config.ts — standalone (recordVideo, 1280x720, reuses
                      `rivet serve` :3003, outputs to out/)
- generate.sh       — capture | tts | mux | all; piper default, macOS
                      `say` preview only; ffmpeg adelay/amix sync
- package.json      — pins @playwright/test
- README.md         — stack rationale, prerequisites, regenerate command,
                      voice guide, storyboard, a11y notes, gaps
- .gitignore        — excludes out/, voices/, node_modules/

Voice guide derived from pulseengine.eu/blog: problem-first, evidence-/
falsification-minded, no marketing fluff, signature close ("agents don't
remember why — so the repository has to"). Reviewed by three personas
(DevRel, safety-critical engineer, a11y) before scaffolding.

HONEST STATUS — scaffold is NOT runtime-verified: structurally checked
(valid JSON, `bash -n` clean, 7 scenes, executable) but never executed.
First run needs a human + the piper binary and a .onnx voice model
(not bundled — license/size). Open gaps: caption (.vtt) generation
wired as TODO, voice selection + final timing fine-sync need a human pass.
No rivet source / Cargo / existing tests touched.

Refs: FEAT-001
---
 tools/intro-video/.gitignore           |   7 ++
 tools/intro-video/README.md            | 160 +++++++++++++++++++++++++
 tools/intro-video/capture.spec.ts      | 136 +++++++++++++++++++++
 tools/intro-video/generate.sh          | 153 +++++++++++++++++++++++
 tools/intro-video/package.json         |  11 ++
 tools/intro-video/playwright.config.ts |  35 ++++++
 tools/intro-video/storyboard.json      |  54 +++++++++
 7 files changed, 556 insertions(+)
 create mode 100644 tools/intro-video/.gitignore
 create mode 100644 tools/intro-video/README.md
 create mode 100644 tools/intro-video/capture.spec.ts
 create mode 100755 tools/intro-video/generate.sh
 create mode 100644 tools/intro-video/package.json
 create mode 100644 tools/intro-video/playwright.config.ts
 create mode 100644 tools/intro-video/storyboard.json

diff --git a/tools/intro-video/.gitignore b/tools/intro-video/.gitignore
new file mode 100644
index 00000000..ae9cfdcc
--- /dev/null
+++ b/tools/intro-video/.gitignore
@@ -0,0 +1,7 @@
+# Generated artifacts — never commit large media.
+out/
+# Downloaded TTS voice models (large binaries, license-bound).
+voices/
+# Node deps for the standalone capture.
+node_modules/
+package-lock.json
diff --git a/tools/intro-video/README.md b/tools/intro-video/README.md
new file mode 100644
index 00000000..02a7bd8b
--- /dev/null
+++ b/tools/intro-video/README.md
@@ -0,0 +1,160 @@
+# rivet intro video — reusable generator
+
+A scaffold to **regenerate** a 30–60s intro/quickstart video of rivet:
+a spoken intro, the CLI `--help`, and a browse through the `rivet serve`
+dashboard, with automated narration synced to the on-screen action.
+
+This is **infrastructure, not a one-off video.** Re-run it after the UI
+changes. Nothing large is committed — only the scripts, the storyboard, and
+this README. Generated media lands in `out/` (gitignored).
+
+## Pipeline
+
+```
+storyboard.json ──► capture.spec.ts (Playwright recordVideo) ──► out/screen.mp4
+        │                                                            │
+        └──► generate.sh tts (piper) ──► out/narration/NN.wav        │
+                                                │                    │
+                                                └──► ffmpeg mux ──────┴──► out/rivet-intro.mp4
+```
+
+`storyboard.json` is the **single source of truth**: it drives both the
+Playwright scene pacing (`hold_ms`, `action`) and the TTS narration
+(`narration`). Edit narration there, never in a generated file.
+
+## Why this stack
+
+- **Screen capture: Playwright `recordVideo`.** Deterministic, headless,
+  fixed 1280×720 framing, no extra binary beyond the browser Playwright
+  already manages, and it reuses the exact `rivet serve` startup the existing
+  test suite uses. Rejected: `ffmpeg x11grab`/screen recorders (host-display
+  dependent, non-deterministic, won't run clean in CI).
+- **CLI help: an in-browser HTML terminal panel** rendered inside the same
+  Playwright video stream. One timeline, one mux. Rejected (for now):
+  asciinema/vhs real-terminal recordings — they'd add a second capture tool
+  and a second sync problem. The scene contract makes swapping one in later
+  trivial (replace `show_cli_help`).
+- **TTS: piper (default).** Local, MIT-licensed, no API key, runs in CI,
+  license-clean for a published artifact. Rejected: cloud TTS (better prosody,
+  but proprietary lock-in, per-render cost, and a secret in CI — avoid where
+  avoidable, matching the project's reproducibility stance). `TTS_ENGINE=say`
+  (macOS) exists only for a quick local preview and must **not** ship the
+  published video (Apple voice license).
+- **Mux + timing: ffmpeg.** Narration clips are delayed (`adelay`) to each
+  scene's cumulative offset and mixed (`amix`) onto the silent screen capture.
+
+## Prerequisites
+
+| Tool | Why | Install | Bundled? |
+|------|-----|---------|----------|
+| node + npx | run Playwright | nvm / nodejs.org | no |
+| Playwright + Chromium | screen capture | `npm install && npx playwright install chromium` | no |
+| ffmpeg + ffprobe | normalize + mux | `brew install ffmpeg` / apt | no |
+| piper | local TTS | see below | no |
+| a piper voice model | the narration voice | see below | **no — you must download** |
+| a built `rivet` | `rivet serve` backend | `cargo build --release` (capture starts it) | repo |
+
+### Install piper + a voice
+
+```sh
+# piper: https://github.com/rhasspy/piper  (releases have prebuilt binaries)
+#   macOS/Linux: download the release, put `piper` on PATH.
+# voice models: https://huggingface.co/rhasspy/piper-voices
+mkdir -p voices
+# Example US-English medium voice (calm, technical — fits the PulseEngine voice):
+#   download en_US-ryan-medium.onnx AND en_US-ryan-medium.onnx.json into voices/
+export PIPER_VOICE=voices/en_US-ryan-medium.onnx
+```
+
+`voices/` is gitignored. Voice selection and final prosody are a human call —
+audition a couple before settling.
+
+## Regenerate
+
+From this directory (`tools/intro-video/`):
+
+```sh
+npm install                      # once: Playwright
+npx playwright install chromium  # once: browser
+./generate.sh                    # capture -> tts -> mux  =>  out/rivet-intro.mp4
+```
+
+Sub-steps (when iterating):
+
+```sh
+./generate.sh capture   # re-record screen only (after a UI change)
+./generate.sh tts        # re-synthesize narration only (after a script edit)
+./generate.sh mux        # re-combine existing capture + narration
+```
+
+Quick local preview without piper (macOS, not for publishing):
+
+```sh
+TTS_ENGINE=say ./generate.sh
+```
+
+**Output:** `out/rivet-intro.mp4`. Intermediates: `out/screen.mp4`,
+`out/narration/NN.wav`, raw Playwright `.webm` under `out/pw/`.
+
+## Voice guide
+
+Derived from the PulseEngine blog (pulseengine.eu/blog) — Ralf Anton Beier's
+voice. The narration script MUST follow these:
+
+- **Technical, no marketing fluff.** No "revolutionary", "seamless",
+  "powerful". State what it does; let the mechanism impress.
+- **Falsification-minded / evidence-driven.** Frame value as *proof* and
+  *failing the build*, not features. e.g. "validation fails the build", "the
+  chain is explicit, not reconstructed after the fact".
+- **Lead with the problem.** Open on the gap ("AI writes the code in
+  minutes… what it does not do is prove why"), echoing the rivet launch post.
+- **Short, declarative sentences.** Authority through brevity. One idea per
+  sentence. Plain words.
+- **Concrete and specific.** Name real commands (`validate`, `coverage`,
+  `serve`) and real artifacts (requirements, hazards, design decisions).
+- **Honest about scope.** No overclaiming, no "solves everything". Say
+  precisely what is demonstrated.
+- **Signature close.** End on the project's own line: "because agents don't
+  remember why" → "so the repository has to". Mention open-source + Rust.
+- **Calm pace.** ~2.5 words/second. The voice is unhurried and assured, not
+  hype-energetic.
+
+## Storyboard
+
+Authoritative copy lives in `storyboard.json`. Nominal timing (~52s):
+
+| t (s) | Scene | On-screen action | Narration |
+|-------|-------|------------------|-----------|
+| 0–5 | intro | Branded title card "rivet" | "AI writes the code in minutes. What it does not do is prove why that code exists. rivet binds that proof to the repository." |
+| 5–11 | cli-help | Terminal panel: `rivet --help` | "rivet is a command-line tool. One help screen lists every command — validate, coverage, link, audit. It runs in CI on every push." |
+| 11–16 | dashboard | `rivet serve` dashboard home | "rivet serve opens a dashboard over the same artifacts — no separate database, no drift." |
+| 16–22 | artifacts-list | `/artifacts` table, scroll | "Requirements, hazards, design decisions, and test specs all live as files in the repo, validated the same way the code is." |
+| 22–28 | artifact-detail | `/artifacts/REQ-001` with links | "Open one requirement and you see its links — what it satisfies, what verifies it. The chain is explicit, not reconstructed after the fact." |
+| 28–34 | coverage | `/coverage` report | "Coverage reports show every gap. If a link is missing, validation fails the build. The traceability model can not silently drift from the code." |
+| 34–39 | outro | Branded outro card | "rivet. Open source, built in Rust. Because agents don't remember why — so the repository has to." |
+
+## Accessibility
+
+- **Captions.** Burn or sidecar captions from `storyboard.json` narration.
+  A `.srt`/`.vtt` can be generated from the same scene offsets — TODO, see
+  "Gaps" below. Captions are required, not optional.
+- **Contrast.** Title/outro cards use `#e6edf3` on `#0d1117` (>12:1). The
+  dashboard's own contrast is whatever `rivet serve` ships.
+- **Audio clarity.** piper medium voice at a calm pace; no background music
+  competing with speech.
+
+## Gaps / what still needs a human
+
+- **A TTS binary + voice model.** piper and a `.onnx` voice are not bundled
+  (binary/license). Download per "Install piper". Without them, `capture`
+  still works; `tts`/`mux`/`all` will stop with a clear error.
+- **Voice selection & prosody.** Audition voices; piper has no per-line
+  emphasis control, so awkward phrasing must be fixed in the script text.
+- **Final timing fine-sync.** `hold_ms` is nominal. If a narration clip runs
+  longer than its scene, bump that scene's `hold_ms` and re-run. A human
+  review pass on the final cut is expected.
+- **Caption file generation** (`.vtt`/`.srt`) is not yet wired — the data
+  (text + offsets) is all in `storyboard.json`; add a small step to
+  `generate.sh` when needed.
+- **Publishing** (where the mp4 lands, hosting, the blog embed) is out of
+  scope for this scaffold.
diff --git a/tools/intro-video/capture.spec.ts b/tools/intro-video/capture.spec.ts
new file mode 100644
index 00000000..bf68f34d
--- /dev/null
+++ b/tools/intro-video/capture.spec.ts
@@ -0,0 +1,136 @@
+/**
+ * rivet intro-video capture spec.
+ *
+ * Drives the storyboard.json scenes against a running `rivet serve` instance
+ * and records ONE continuous video via Playwright's built-in recordVideo.
+ *
+ * Why Playwright recordVideo (not ffmpeg x11grab / screen recorder):
+ *   - Deterministic & headless: same output on a laptop and in CI, no display.
+ *   - No extra binary beyond the browser Playwright already manages.
+ *   - The viewport is fixed (1280x720) so framing never depends on the host.
+ *
+ * Why the CLI help is an in-browser HTML panel (not a real terminal recorder
+ * like asciinema/ttyrec/vhs):
+ *   - It stays in the SAME video stream, so there is one timeline to sync the
+ *     narration against — no second capture tool, no second mux step.
+ *   - It is deterministic: the help text is pinned in this file, so the frame
+ *     does not reflow when a future `--help` adds a command (the spec would be
+ *     updated deliberately, same as any other rivet Playwright test).
+ *   - Trade-off: it is a faithful *render* of `rivet --help`, not a live PTY.
+ *     If you want a real recorded terminal later, swap show_cli_help() for an
+ *     <img>/<video> of an asciinema cast — the scene contract is unchanged.
+ *
+ * This file lives OUTSIDE tests/playwright on purpose: it is not part of the
+ * regression suite (it produces an artifact, it does not assert behaviour) and
+ * has its own playwright.config.ts in this directory.
+ */
+import { test } from "@playwright/test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+type Scene = {
+  id: string;
+  action: string;
+  hold_ms: number;
+  narration: string;
+};
+type Storyboard = {
+  meta: { base_url: string; viewport: { width: number; height: number } };
+  scenes: Scene[];
+};
+
+const storyboard: Storyboard = JSON.parse(
+  readFileSync(join(__dirname, "storyboard.json"), "utf8"),
+);
+
+const BRAND_BG = "#0d1117";
+const BRAND_FG = "#e6edf3";
+const ACCENT = "#58a6ff";
+
+/** Render a full-viewport branded HTML card (title / outro). */
+async function card(
+  page: import("@playwright/test").Page,
+  heading: string,
+  sub: string,
+) {
+  await page.setContent(`
+    <html><body style="margin:0;height:100vh;display:flex;flex-direction:column;
+      align-items:center;justify-content:center;background:${BRAND_BG};
+      color:${BRAND_FG};font-family:-apple-system,Segoe UI,Helvetica,Arial,sans-serif;">
+      <div style="font-size:64px;font-weight:700;letter-spacing:-1px;">${heading}</div>
+      <div style="font-size:28px;margin-top:16px;color:${ACCENT};">${sub}</div>
+    </body></html>`);
+}
+
+/** Render a terminal-styled panel showing pinned `rivet --help` output. */
+async function cliPanel(page: import("@playwright/test").Page) {
+  // Pinned excerpt of `rivet --help` — update deliberately if the CLI changes.
+  const help = [
+    "$ rivet --help",
+    "SDLC artifact traceability and validation",
+    "",
+    "Usage: rivet [OPTIONS] <COMMAND>",
+    "",
+    "Commands:",
+    "  validate   Validate artifacts against schemas",
+    "  coverage   Show traceability coverage report",
+    "  list       List artifacts, optionally filtered by type",
+    "  link       Add a link between two artifacts",
+    "  audit      Audit AI-authored commits against ai-session artifacts",
+    "  serve      Start the HTMX-powered dashboard server",
+    "  ...        (run `rivet --help` for the full command list)",
+  ].join("\n");
+  await page.setContent(`
+    <html><body style="margin:0;height:100vh;background:${BRAND_BG};
+      display:flex;align-items:center;justify-content:center;">
+      <pre style="background:#161b22;color:${BRAND_FG};padding:32px 40px;
+        border-radius:10px;font-family:SF Mono,Menlo,Consolas,monospace;
+        font-size:22px;line-height:1.45;box-shadow:0 8px 40px #0008;">${help
+          .replace(/</g, "&lt;")
+          .replace(
+            /^\$ rivet --help$/m,
+            `<span style="color:${ACCENT}">$ rivet --help</span>`,
+          )}</pre>
+    </body></html>`);
+}
+
+test("rivet intro video capture", async ({ page }) => {
+  test.setTimeout(120_000);
+  const { base_url } = storyboard.meta;
+
+  for (const scene of storyboard.scenes) {
+    switch (scene.action) {
+      case "title_card":
+        await card(page, "rivet", "bind traceability to your code");
+        break;
+      case "show_cli_help":
+        await cliPanel(page);
+        break;
+      case "open_dashboard":
+        await page.goto(`${base_url}/`);
+        await page.waitForLoadState("networkidle").catch(() => {});
+        break;
+      case "browse_artifacts":
+        await page.goto(`${base_url}/artifacts`);
+        await page.locator("table").first().waitFor().catch(() => {});
+        // Gentle scroll to show the list is long / real.
+        await page.mouse.wheel(0, 400);
+        break;
+      case "open_artifact":
+        await page.goto(`${base_url}/artifacts/REQ-001`);
+        await page.waitForLoadState("networkidle").catch(() => {});
+        break;
+      case "show_coverage":
+        await page.goto(`${base_url}/coverage`);
+        await page.waitForLoadState("networkidle").catch(() => {});
+        break;
+      case "outro_card":
+        await card(page, "rivet", "pulseengine.eu · open source · Rust");
+        break;
+      default:
+        throw new Error(`unknown scene action: ${scene.action}`);
+    }
+    // Hold the scene on screen for its narration window.
+    await page.waitForTimeout(scene.hold_ms);
+  }
+});
diff --git a/tools/intro-video/generate.sh b/tools/intro-video/generate.sh
new file mode 100755
index 00000000..91c19992
--- /dev/null
+++ b/tools/intro-video/generate.sh
@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+#
+# Regenerate the rivet intro/quickstart video end-to-end.
+#
+#   capture (Playwright) -> narration (TTS) -> mux (ffmpeg)
+#
+# All output lands in ./out/ which is gitignored. Re-run after a UI change and
+# commit nothing but the scaffold (storyboard.json / specs / this script).
+#
+# Usage:
+#   ./generate.sh              # full pipeline (capture + tts + mux)
+#   ./generate.sh capture      # just the screen capture
+#   ./generate.sh tts          # just synthesize narration clips
+#   ./generate.sh mux          # just mux existing capture + narration
+#
+# Requirements (see README.md for install notes):
+#   - node + npx (Playwright is installed via `npm install` in this dir)
+#   - ffmpeg + ffprobe on PATH
+#   - A TTS engine. Default is piper (local, MIT, no API key, CI-friendly).
+#     Set TTS_ENGINE=say to use macOS `say` for a quick local preview.
+#
+set -euo pipefail
+cd "$(dirname "$0")"
+
+OUT="out"
+NARR_DIR="$OUT/narration"
+PW_VIDEO_DIR="$OUT/pw"
+STORYBOARD="storyboard.json"
+
+TTS_ENGINE="${TTS_ENGINE:-piper}"
+# Piper voice model (.onnx) + config (.onnx.json). Download once; see README.
+# A US English medium voice is a reasonable default for the PulseEngine voice
+# (calm, technical, unhurried). Point PIPER_VOICE at your downloaded model.
+PIPER_VOICE="${PIPER_VOICE:-voices/en_US-ryan-medium.onnx}"
+
+mkdir -p "$NARR_DIR"
+
+need() { command -v "$1" >/dev/null 2>&1 || { echo "ERROR: '$1' not found on PATH. See README.md."; exit 1; }; }
+
+scene_count() { node -e 'const s=require("./'"$STORYBOARD"'");console.log(s.scenes.length)'; }
+scene_field() { # $1=index $2=field
+  node -e 'const s=require("./'"$STORYBOARD"'");process.stdout.write(String(s.scenes['"$1"'].'"$2"'))'
+}
+
+# ---------------------------------------------------------------------------
+# 1. CAPTURE — Playwright records one .webm of all scenes.
+# ---------------------------------------------------------------------------
+do_capture() {
+  need npx
+  echo ">> capture: running Playwright (this starts/reuses 'rivet serve' on :3003)"
+  npx playwright test --config playwright.config.ts
+  # Playwright writes a .webm under out/pw/<test-dir>/video.webm
+  local webm
+  webm="$(find "$PW_VIDEO_DIR" -name '*.webm' -print -quit || true)"
+  if [ -z "${webm:-}" ]; then
+    echo "ERROR: no .webm produced by Playwright under $PW_VIDEO_DIR"; exit 1
+  fi
+  need ffmpeg
+  echo ">> capture: normalizing $webm -> $OUT/screen.mp4"
+  ffmpeg -y -i "$webm" -r 30 -pix_fmt yuv420p -an "$OUT/screen.mp4"
+  echo ">> capture: done -> $OUT/screen.mp4"
+}
+
+# ---------------------------------------------------------------------------
+# 2. TTS — one narration clip per scene, named narration/NN.wav.
+# ---------------------------------------------------------------------------
+synth_one() { # $1=text $2=outfile.wav
+  case "$TTS_ENGINE" in
+    piper)
+      need piper
+      if [ ! -f "$PIPER_VOICE" ]; then
+        echo "ERROR: piper voice model not found at '$PIPER_VOICE'."
+        echo "       Download a voice (e.g. en_US-ryan-medium) per README.md,"
+        echo "       or set PIPER_VOICE / TTS_ENGINE=say."
+        exit 1
+      fi
+      printf '%s' "$1" | piper --model "$PIPER_VOICE" --output_file "$2"
+      ;;
+    say) # macOS preview voice — NOT for the published artifact (Apple license).
+      need say
+      need ffmpeg
+      say -v Daniel -o "$2.aiff" "$1"
+      ffmpeg -y -i "$2.aiff" "$2" && rm -f "$2.aiff"
+      ;;
+    *)
+      echo "ERROR: unknown TTS_ENGINE='$TTS_ENGINE' (expected: piper | say)"; exit 1;;
+  esac
+}
+
+do_tts() {
+  need node
+  local n; n="$(scene_count)"
+  echo ">> tts: synthesizing $n narration clips with engine '$TTS_ENGINE'"
+  for ((i=0; i<n; i++)); do
+    local text out
+    text="$(scene_field "$i" narration)"
+    out="$(printf '%s/%02d.wav' "$NARR_DIR" "$i")"
+    echo "   [$i] $text"
+    synth_one "$text" "$out"
+  done
+  echo ">> tts: done -> $NARR_DIR/*.wav"
+}
+
+# ---------------------------------------------------------------------------
+# 3. MUX — lay each narration clip at its scene's cumulative offset, then
+#          combine with the screen capture. Each scene's hold_ms defines the
+#          window; narration starts at the scene boundary so speech tracks the
+#          on-screen action.
+# ---------------------------------------------------------------------------
+do_mux() {
+  need ffmpeg; need ffprobe; need node
+  [ -f "$OUT/screen.mp4" ] || { echo "ERROR: $OUT/screen.mp4 missing — run capture first."; exit 1; }
+
+  local n; n="$(scene_count)"
+  # Build a delayed+concatenated narration track aligned to scene offsets.
+  local inputs=() filters=() offset=0 idx=0
+  for ((i=0; i<n; i++)); do
+    local wav hold
+    wav="$(printf '%s/%02d.wav' "$NARR_DIR" "$i")"
+    hold="$(scene_field "$i" hold_ms)"
+    [ -f "$wav" ] || { echo "ERROR: missing narration clip $wav — run tts first."; exit 1; }
+    inputs+=(-i "$wav")
+    # adelay in ms (per channel); pad each clip to start at the scene boundary.
+    filters+=("[$idx:a]adelay=${offset}|${offset}[a$idx];")
+    offset=$((offset + hold))
+    idx=$((idx + 1))
+  done
+  # amix all delayed clips into one track.
+  local mixins="" j
+  for ((j=0; j<n; j++)); do mixins+="[a$j]"; done
+  local filtergraph
+  filtergraph="$(printf '%s' "${filters[@]}")${mixins}amix=inputs=${n}:normalize=0[narr]"
+
+  echo ">> mux: building narration track ($n clips) and muxing with screen.mp4"
+  ffmpeg -y -i "$OUT/screen.mp4" "${inputs[@]}" \
+    -filter_complex "$filtergraph" \
+    -map 0:v -map "[narr]" \
+    -c:v libx264 -pix_fmt yuv420p -c:a aac -shortest \
+    "$OUT/rivet-intro.mp4"
+  echo ">> mux: done -> $OUT/rivet-intro.mp4"
+  echo
+  echo "NOTE: timing is nominal (narration laid at scene boundaries). If a clip"
+  echo "      runs long, bump that scene's hold_ms in $STORYBOARD and re-run"
+  echo "      'capture' + 'mux'. Final fine-sync still benefits from a human pass."
+}
+
+case "${1:-all}" in
+  capture) do_capture ;;
+  tts)     do_tts ;;
+  mux)     do_mux ;;
+  all)     do_capture; do_tts; do_mux ;;
+  *) echo "usage: $0 [all|capture|tts|mux]"; exit 2 ;;
+esac
diff --git a/tools/intro-video/package.json b/tools/intro-video/package.json
new file mode 100644
index 00000000..9df20b48
--- /dev/null
+++ b/tools/intro-video/package.json
@@ -0,0 +1,11 @@
+{
+  "name": "rivet-intro-video",
+  "private": true,
+  "description": "Reusable scaffold to regenerate the rivet 30-60s intro/quickstart video.",
+  "devDependencies": {
+    "@playwright/test": "^1.50.0"
+  },
+  "scripts": {
+    "capture": "playwright test --config playwright.config.ts"
+  }
+}
diff --git a/tools/intro-video/playwright.config.ts b/tools/intro-video/playwright.config.ts
new file mode 100644
index 00000000..8a9d35ca
--- /dev/null
+++ b/tools/intro-video/playwright.config.ts
@@ -0,0 +1,35 @@
+import { defineConfig } from "@playwright/test";
+
+/**
+ * Standalone Playwright config for the intro-video capture.
+ * Separate from tests/playwright/playwright.config.ts so the capture is never
+ * run as part of the regression suite (it produces an artifact, not an
+ * assertion) and so it can record video at a fixed 1280x720 framing.
+ *
+ * Outputs land in ./out/ (gitignored). The .webm Playwright writes is picked
+ * up by generate.sh and remuxed.
+ */
+export default defineConfig({
+  testDir: ".",
+  testMatch: "capture.spec.ts",
+  timeout: 120_000,
+  retries: 0,
+  workers: 1,
+  outputDir: "./out/pw",
+  use: {
+    baseURL: "http://localhost:3003",
+    viewport: { width: 1280, height: 720 },
+    video: {
+      mode: "on",
+      size: { width: 1280, height: 720 },
+    },
+  },
+  webServer: {
+    command: "cargo run --release -- serve --port 3003",
+    port: 3003,
+    timeout: 180_000,
+    reuseExistingServer: true,
+    cwd: "../..",
+  },
+  projects: [{ name: "chromium", use: { browserName: "chromium" } }],
+});
diff --git a/tools/intro-video/storyboard.json b/tools/intro-video/storyboard.json
new file mode 100644
index 00000000..611e55bc
--- /dev/null
+++ b/tools/intro-video/storyboard.json
@@ -0,0 +1,54 @@
+{
+  "$comment": "Single source of truth for the rivet intro video. Each scene drives BOTH the Playwright capture pacing (capture.spec.ts reads `scenes[].hold_ms` and `scenes[].action`) AND the TTS narration (generate.sh reads `scenes[].narration`). Keep narration tight: total target 30-60s, ~80-150 words. Edit narration here, never in a generated artifact. Timings are nominal; actual A/V sync is done at mux time by laying each narration clip at its scene's cumulative offset (see generate.sh).",
+  "meta": {
+    "title": "rivet — bind traceability to your code",
+    "target_seconds": 52,
+    "voice_guide_ref": "README.md#voice-guide",
+    "viewport": { "width": 1280, "height": 720 },
+    "base_url": "http://localhost:3003"
+  },
+  "scenes": [
+    {
+      "id": "intro",
+      "action": "title_card",
+      "hold_ms": 5000,
+      "narration": "AI writes the code in minutes. What it does not do is prove why that code exists. rivet binds that proof to the repository."
+    },
+    {
+      "id": "cli-help",
+      "action": "show_cli_help",
+      "hold_ms": 6000,
+      "narration": "rivet is a command-line tool. One help screen lists every command — validate, coverage, link, audit. It runs in CI on every push."
+    },
+    {
+      "id": "dashboard",
+      "action": "open_dashboard",
+      "hold_ms": 5000,
+      "narration": "rivet serve opens a dashboard over the same artifacts — no separate database, no drift."
+    },
+    {
+      "id": "artifacts-list",
+      "action": "browse_artifacts",
+      "hold_ms": 6000,
+      "narration": "Requirements, hazards, design decisions, and test specs all live as files in the repo, validated the same way the code is."
+    },
+    {
+      "id": "artifact-detail",
+      "action": "open_artifact",
+      "hold_ms": 6000,
+      "narration": "Open one requirement and you see its links — what it satisfies, what verifies it. The chain is explicit, not reconstructed after the fact."
+    },
+    {
+      "id": "coverage",
+      "action": "show_coverage",
+      "hold_ms": 6000,
+      "narration": "Coverage reports show every gap. If a link is missing, validation fails the build. The traceability model can not silently drift from the code."
+    },
+    {
+      "id": "outro",
+      "action": "outro_card",
+      "hold_ms": 5000,
+      "narration": "rivet. Open source, built in Rust. Because agents don't remember why — so the repository has to."
+    }
+  ]
+}