From 87189268d7cbd35fdea494de92ac7aa39fe619a7 Mon Sep 17 00:00:00 2001
From: Tig <tig@users.noreply.github.com>
Date: Fri, 24 Jul 2026 06:32:08 -0600
Subject: [PATCH 1/2] docs: add reproducible README hero video pipeline

Add docs/hero-video with storyboard, capture checklist, timeline.toml,
and an ffmpeg assembler that burns a first-ship session clock, applies
per-segment speed (time-lapse / slow-mo), generates open/end cards from
hero.jpg, and supports --placeholders for smoke builds without footage.
---
 .gitignore                       |   12 +
 README.md                        |    3 +
 docs/hero-video/README.md        |   72 +++
 docs/hero-video/SCRIPT.md        |  113 ++++
 docs/hero-video/build.py         | 1024 ++++++++++++++++++++++++++++++
 docs/hero-video/footage/.gitkeep |    0
 docs/hero-video/out/.gitkeep     |    0
 docs/hero-video/record.md        |   76 +++
 docs/hero-video/timeline.toml    |  147 +++++
 tests/test_hero_video_build.py   |  139 ++++
 10 files changed, 1586 insertions(+)
 create mode 100644 docs/hero-video/README.md
 create mode 100644 docs/hero-video/SCRIPT.md
 create mode 100644 docs/hero-video/build.py
 create mode 100644 docs/hero-video/footage/.gitkeep
 create mode 100644 docs/hero-video/out/.gitkeep
 create mode 100644 docs/hero-video/record.md
 create mode 100644 docs/hero-video/timeline.toml
 create mode 100644 tests/test_hero_video_build.py

diff --git a/.gitignore b/.gitignore
index 3705bcd..982d60a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,15 @@ build/
 # local installs of vendored packages
 third_party/**/src/*.egg-info/
 third_party/**/*.egg-info/
+
+# Hero video raw footage + renders (keep .gitkeep; see docs/hero-video/)
+docs/hero-video/footage/*
+!docs/hero-video/footage/.gitkeep
+docs/hero-video/out/*
+!docs/hero-video/out/.gitkeep
+docs/hero-video/**/*.mp4
+docs/hero-video/**/*.mov
+docs/hero-video/**/*.mkv
+docs/hero-video/**/*.webm
+docs/hero-video/**/*.vf.txt
+docs/hero-video/**/*.pre.mp4
diff --git a/README.md b/README.md
index 01af296..f7d5d31 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 ![Silico - Prompt to metal](docs/hero.jpg)
 
+<!-- Hero video (first ship of Xuss): produce/reproduce via docs/hero-video/ -->
+
 Silico makes building maintainable firmware for embedded devices simple. Given a device [spec](./specs/lexicon.md#spec), it first guides AI agents to [scaffold](./specs/lexicon.md#scaffold) a GitHub repository set up for long-term maintainability.
 
 Agents then loop to engineer robust firmware, unit and smoke tests, a simulator, continuous integration (CI) using both real devices and the simulator, and an end-user install/upgrade tool.
@@ -142,3 +144,4 @@ These may appear *inside* a GCU's own tree; they are **not** first-class Silico
 | [specs/tenets.md](specs/tenets.md) | Tenets |
 | [specs/lexicon.md](specs/lexicon.md) | Phrase book (GCU, spine, host-honest, Help the operator, …) |
 | [specs/gcu-codenames.md](specs/gcu-codenames.md) | Public GCU codenames |
+| [docs/hero-video/](docs/hero-video/) | Reproduce the README hero video (script, capture checklist, ffmpeg assemble) |
diff --git a/docs/hero-video/README.md b/docs/hero-video/README.md
new file mode 100644
index 0000000..5ce37d7
--- /dev/null
+++ b/docs/hero-video/README.md
@@ -0,0 +1,72 @@
+# Hero video (README)
+
+Reproduce the **silico × xuss** end-to-end hero cut for the root [README](../../README.md).
+
+| File | Role |
+|------|------|
+| [SCRIPT.md](SCRIPT.md) | Narrative beats (what the viewer should see) |
+| [record.md](record.md) | How to capture each source clip |
+| [timeline.toml](timeline.toml) | Edit decision list: order, trims, speed, session clock |
+| [build.py](build.py) | ffmpeg assembler (clock burn-in, stills, cards, concat) |
+| `footage/` | Your recordings (gitignored binaries) |
+| `out/` | Rendered `hero.mp4` (gitignored) |
+
+## Prerequisites
+
+- **ffmpeg** on `PATH` (`ffmpeg -version`)
+- **Python 3.11+** (stdlib only: `tomllib`, `argparse`, `subprocess`, …)
+- Source clips under `footage/` **or** use `--placeholders` to smoke the pipeline
+
+Optional: a font ffmpeg can find for `drawtext` (Windows: `C:\\Windows\\Fonts\\segoeui.ttf`; macOS: Helvetica; Linux: DejaVu). The builder probes common paths.
+
+## Quick start
+
+```text
+# From repo root or this directory:
+python docs/hero-video/build.py --placeholders
+python docs/hero-video/build.py --check-footage
+python docs/hero-video/build.py
+```
+
+Outputs:
+
+- `docs/hero-video/out/hero.mp4` — final cut
+- `docs/hero-video/out/segments/` — intermediate segment encodes (debug)
+
+## Clock semantics
+
+The on-screen timer is **first-ship session elapsed**, not video wall-clock.
+
+Each segment maps its **output** duration linearly from `session_start_sec` → `session_end_sec`. Time-lapse (`speed = 30`) advances the clock quickly; slow-mo (`speed = 0.35`) holds readable moments while session time still creeps.
+
+Fill session times from the log in [record.md](record.md) after a real capture.
+
+## Editing workflow
+
+1. Record clips per [record.md](record.md).
+2. Set `in_sec` / `out_sec` / `speed` on each `[[segments]]` entry in `timeline.toml`.
+3. Split the long agent tape into **gate-slow** vs **timelapse** segments (examples commented in the timeline).
+4. `python build.py` → review → tweak → repeat.
+5. Publish the mp4 (see below) and point the root README at it.
+
+## Publish options
+
+Raw `hero.mp4` is usually too large for a normal git blob. Prefer:
+
+1. **GitHub Release asset** on `tig/silico` (or a `hero-video` release tag), then link from README with the hero still as poster.
+2. **GitHub issue/PR drag-upload** URL (convenient for drafts; less stable than a release).
+3. **Git LFS** only if the team already standardizes on LFS for media.
+
+Suggested README shape once hosted:
+
+```md
+[![Silico — prompt to metal](docs/hero.jpg)](https://github.com/tig/silico/releases/download/hero-video/hero.mp4)
+
+*Hero video: first ship of [Xuss](https://github.com/tig/xuss) with Silico. Reproduce: [docs/hero-video](docs/hero-video).*
+```
+
+## Design notes
+
+- Same spirit as `docs/_make_social_preview.py`: **docs tooling in-tree**, not product domain in the spine.
+- Placeholders keep the assemble path testable without committing multi‑hundred‑MB screen captures.
+- No soft-fork of Bedside or first-ship manners: the video *shows* the path; [AGENTS.md](../../AGENTS.md) remains normative for agents.
diff --git a/docs/hero-video/SCRIPT.md b/docs/hero-video/SCRIPT.md
new file mode 100644
index 0000000..43acae6
--- /dev/null
+++ b/docs/hero-video/SCRIPT.md
@@ -0,0 +1,113 @@
+# Hero video script — silico × xuss first ship
+
+Narrative for the README **hero video**: one end-to-end first ship of the [Xuss](https://github.com/tig/xuss) demo **GCU** (General Contact Unit — Silico’s term for one shippable edge product) using Silico’s host path.
+
+**Goal:** a viewer who has never opened the repo sees *prompt → clone → agent → board talking → CI green* in a short cut, with an on-screen clock that measures **real first-ship elapsed time** (not how long the edited video runs).
+
+**Assembly:** machine plan is [`timeline.toml`](timeline.toml). Build with [`build.py`](build.py). Capture notes: [`record.md`](record.md).
+
+---
+
+## Target runtime (edit)
+
+| Layer | Aim |
+|-------|-----|
+| Finished video | ~90–150 seconds |
+| Real first-ship session on clock | whatever it actually took (often tens of minutes; clock may run into hours) |
+| Aspect | 16:9 (1920×1080 default) |
+
+Tune segment `speed` / trims in `timeline.toml` after the first rough cut.
+
+---
+
+## Beats
+
+### 1. Opening — `docs/hero.jpg`
+
+- Full-frame still of the existing hero image (`docs/hero.jpg`).
+- Optional soft title: **silico** / *Prompt to metal*.
+- Clock visible at **0:00**.
+- Hold ~2.5–3.5 s.
+
+### 2. GitHub: silico Getting Started → copy the prompt
+
+- Screen recording of [github.com/tig/silico](https://github.com/tig/silico) (or the README rendered locally).
+- Scroll to **Getting Started** / **Step 3** (the agent start prompt).
+- Pause; highlight or zoom the prompt block so it is obviously the thing to copy:
+
+  ```md
+  Read https://github.com/tig/silico's AGENTS.md. Follow the guidance there exactly. Stay in this product checkout.
+  ```
+
+- Clock advances only a little (browsing time), real-time or mild speed-up.
+
+### 3. Terminal — clone xuss, start agent, paste prompt
+
+- Clean terminal (or TUI shell) at a neutral home directory.
+- Commands, readable at 1× (or slight speed-up between commands only):
+
+  ```sh
+  git clone https://github.com/tig/xuss
+  cd xuss
+  grok
+  ```
+
+- Paste the Silico start prompt into the agent.
+- Cut before the long agent monologue; hand off to the next beat at first meaningful agent output if possible.
+
+### 4. Welcome — slow for readability
+
+- From the agent session recording: the **Stage 0a orientation** (`silico welcome` skeleton in chat).
+- **Slow** so a viewer can read key lines (~2–3 s of *readable* on-screen time; use `speed < 1` in the timeline).
+- Do **not** race past “what Silico is / this GCU / start gate next.”
+
+### 5. First-ship body — time-lapse, slow on human acts
+
+- Same session (or stitched session clips): Stage A→D as a **time-lapse**.
+- **Slow to ~1× (or gentle slow-mo)** whenever the human must act:
+  - start-gate / yes-adjust chooser
+  - plug USB / board confirm
+  - deploy overwrite confirm
+  - product-face observe (“do you see/hear …?”)
+- Fast through pure agent work (installs, scaffold, pytest green, long thinking).
+- Prefer **many short segments** in `timeline.toml` (same file, different `in_sec`/`out_sec`/`speed`) over one opaque 30× clip.
+
+### 6. Desk — xuss on metal
+
+- Cutaway to the physical board on the desk (M5GO-class for Xuss).
+- Soft-reset / boot: **product face** (status LEDs / boot sound) as documented for Xuss.
+- Short human demo of the product face / core functionality (a few seconds of honest bench truth).
+- **Keep audio** for boot tone and demo; announce in capture notes if the tone is long.
+- Clock keeps running (metal confirm is still first-ship time).
+
+### 7. GitHub — tig/xuss CI green
+
+- Browser or `gh` UI on [tig/xuss](https://github.com/tig/xuss): default branch / latest run **green**.
+- Hold long enough to read the check name (~2–3 s).
+
+### 8. End card
+
+- Dark brand card.
+- Primary line: **https://github.com/tig/silico**
+- Optional: *Prompt to metal.* / final clock freeze or hide clock.
+- Hold ~3–4 s.
+
+---
+
+## What this is not
+
+- Not a substitute for [AGENTS.md](../../AGENTS.md) (agents still load the full playbook).
+- Not a claim that every host finishes in the on-screen wall time of the *video* — the **clock** is the honest duration.
+- Not past-HEAD salvage theater: capture should be a real first ship (or an explicitly labeled rehearsal).
+
+---
+
+## README embed (after first good render)
+
+Prefer a short poster + link, or a GitHub-hosted asset:
+
+```md
+[![Silico — prompt to metal (hero video)](docs/hero.jpg)](URL_TO_HERO_MP4)
+```
+
+Or HTML `<video>` when the host supports it. See [README.md](README.md) in this folder for publish options (release asset vs LFS vs external).
diff --git a/docs/hero-video/build.py b/docs/hero-video/build.py
new file mode 100644
index 0000000..8529f42
--- /dev/null
+++ b/docs/hero-video/build.py
@@ -0,0 +1,1024 @@
+#!/usr/bin/env python3
+"""Assemble the silico × xuss README hero video from timeline.toml + footage.
+
+Requires ffmpeg on PATH. Stdlib only.
+
+Examples:
+  python build.py --placeholders   # smoke path without real clips
+  python build.py --check-footage
+  python build.py
+  python build.py --timeline timeline.toml --dry-run
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+DEFAULT_TIMELINE = ROOT / "timeline.toml"
+
+
+# ---------------------------------------------------------------------------
+# Model
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ClockCfg:
+    enabled: bool = True
+    x: str = "w-tw-48"
+    y: str = "40"
+    font_size: int = 40
+    font_color: str = "white"
+    box: bool = True
+    box_color: str = "black@0.55"
+    box_border_w: int = 12
+    prefix: str = ""
+
+
+@dataclass
+class BrandCfg:
+    title: str = "silico"
+    tagline: str = "Prompt to metal."
+    credit_url: str = "https://github.com/tig/silico"
+    hero_image: str = "../hero.jpg"
+
+
+@dataclass
+class VideoCfg:
+    width: int = 1920
+    height: int = 1080
+    fps: int = 30
+    output: str = "out/hero.mp4"
+    crf: int = 20
+    preset: str = "medium"
+
+
+@dataclass
+class Segment:
+    id: str
+    kind: str  # still | clip | card
+    source: str | None = None
+    duration_sec: float | None = None
+    in_sec: float | None = None
+    out_sec: float | None = None
+    speed: float = 1.0
+    session_start_sec: float = 0.0
+    session_end_sec: float = 0.0
+    show_clock: bool = True
+    keep_audio: bool = False
+    title_overlay: bool = False
+    lines: list[str] = field(default_factory=list)
+    subtitle: str = ""
+    note: str = ""
+
+
+@dataclass
+class Timeline:
+    video: VideoCfg
+    brand: BrandCfg
+    clock: ClockCfg
+    segments: list[Segment]
+    path: Path
+
+
+def load_timeline(path: Path) -> Timeline:
+    raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    v = raw.get("video", {})
+    b = raw.get("brand", {})
+    c = raw.get("clock", {})
+    video = VideoCfg(
+        width=int(v.get("width", 1920)),
+        height=int(v.get("height", 1080)),
+        fps=int(v.get("fps", 30)),
+        output=str(v.get("output", "out/hero.mp4")),
+        crf=int(v.get("crf", 20)),
+        preset=str(v.get("preset", "medium")),
+    )
+    brand = BrandCfg(
+        title=str(b.get("title", "silico")),
+        tagline=str(b.get("tagline", "Prompt to metal.")),
+        credit_url=str(b.get("credit_url", "https://github.com/tig/silico")),
+        hero_image=str(b.get("hero_image", "../hero.jpg")),
+    )
+    clock = ClockCfg(
+        enabled=bool(c.get("enabled", True)),
+        x=str(c.get("x", "w-tw-48")),
+        y=str(c.get("y", "40")),
+        font_size=int(c.get("font_size", 40)),
+        font_color=str(c.get("font_color", "white")),
+        box=bool(c.get("box", True)),
+        box_color=str(c.get("box_color", "black@0.55")),
+        box_border_w=int(c.get("box_border_w", 12)),
+        prefix=str(c.get("prefix", "")),
+    )
+    segments: list[Segment] = []
+    for i, s in enumerate(raw.get("segments", [])):
+        sid = str(s.get("id") or f"seg{i}")
+        kind = str(s.get("kind", "clip"))
+        if kind not in ("still", "clip", "card"):
+            raise SystemExit(f"segment {sid}: unknown kind={kind!r}")
+        speed = float(s.get("speed", 1.0))
+        if speed <= 0:
+            raise SystemExit(f"segment {sid}: speed must be > 0")
+        lines = s.get("lines") or []
+        if isinstance(lines, str):
+            lines = [lines]
+        segments.append(
+            Segment(
+                id=sid,
+                kind=kind,
+                source=s.get("source"),
+                duration_sec=_opt_float(s.get("duration_sec")),
+                in_sec=_opt_float(s.get("in_sec")),
+                out_sec=_opt_float(s.get("out_sec")),
+                speed=speed,
+                session_start_sec=float(s.get("session_start_sec", 0)),
+                session_end_sec=float(s.get("session_end_sec", 0)),
+                show_clock=bool(s.get("show_clock", True)),
+                keep_audio=bool(s.get("keep_audio", False)),
+                title_overlay=bool(s.get("title_overlay", False)),
+                lines=[str(x) for x in lines],
+                subtitle=str(s.get("subtitle", "")),
+                note=str(s.get("note", "")),
+            )
+        )
+    if not segments:
+        raise SystemExit(f"no segments in {path}")
+    return Timeline(video=video, brand=brand, clock=clock, segments=segments, path=path)
+
+
+def _opt_float(v: object) -> float | None:
+    if v is None:
+        return None
+    return float(v)
+
+
+# ---------------------------------------------------------------------------
+# ffmpeg helpers
+# ---------------------------------------------------------------------------
+
+
+def require_ffmpeg() -> str:
+    path = shutil.which("ffmpeg")
+    if not path:
+        raise SystemExit("ffmpeg not found on PATH. Install ffmpeg and retry.")
+    return path
+
+
+def probe_duration(ffmpeg: str, media: Path) -> float:
+    """Return duration in seconds via ffprobe-compatible ffmpeg -i parse, or ffprobe."""
+    ffprobe = shutil.which("ffprobe")
+    if ffprobe:
+        r = subprocess.run(
+            [
+                ffprobe,
+                "-v",
+                "error",
+                "-show_entries",
+                "format=duration",
+                "-of",
+                "json",
+                str(media),
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if r.returncode == 0:
+            data = json.loads(r.stdout or "{}")
+            dur = float(data.get("format", {}).get("duration") or 0)
+            if dur > 0:
+                return dur
+    # Fallback: ffmpeg -i stderr
+    r = subprocess.run(
+        [ffmpeg, "-i", str(media)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    err = r.stderr or ""
+    # Duration: 00:01:23.45
+    import re
+
+    m = re.search(r"Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)", err)
+    if not m:
+        raise SystemExit(f"could not probe duration: {media}")
+    h, mi, s = int(m.group(1)), int(m.group(2)), float(m.group(3))
+    return h * 3600 + mi * 60 + s
+
+
+def find_font() -> str | None:
+    candidates = [
+        Path(r"C:\Windows\Fonts\segoeui.ttf"),
+        Path(r"C:\Windows\Fonts\arial.ttf"),
+        Path(r"C:\Windows\Fonts\calibri.ttf"),
+        Path("/System/Library/Fonts/Supplemental/Arial.ttf"),
+        Path("/System/Library/Fonts/Helvetica.ttc"),
+        Path("/Library/Fonts/Arial.ttf"),
+        Path("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"),
+        Path("/usr/share/fonts/TTF/DejaVuSans.ttf"),
+    ]
+    for p in candidates:
+        if p.is_file():
+            return str(p).replace("\\", "/")
+    return None
+
+
+def esc_drawtext(s: str) -> str:
+    """Escape text for ffmpeg drawtext filter."""
+    return (
+        s.replace("\\", "\\\\")
+        .replace(":", "\\:")
+        .replace("'", "\\'")
+        .replace("%", "\\%")
+    )
+
+
+def esc_fontfile(path: str) -> str:
+    """Escape a font path for drawtext=fontfile= (Windows drive colon).
+
+    ffmpeg on Windows needs either quotes + \\: or a double-escaped colon.
+    Quoted form is reliable for both -vf and filter_script files.
+    """
+    inner = path.replace("\\", "/").replace(":", "\\:")
+    return f"'{inner}'"
+
+
+def vf_args(vf: str, script_path: Path) -> list[str]:
+    """Prefer filter_script file so long graphs and Windows paths stay intact."""
+    write_vf_script(vf, script_path)
+    # filter_script:v is the video filter equivalent of -vf from a file
+    return ["-filter_script:v", str(script_path)]
+
+
+def scale_pad_vf(width: int, height: int) -> str:
+    return (
+        f"scale={width}:{height}:force_original_aspect_ratio=decrease,"
+        f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2:color=0x0a101c,"
+        f"setsar=1"
+    )
+
+
+def clock_drawtext(
+    clock: ClockCfg,
+    session_start: float,
+    session_end: float,
+    out_duration: float,
+    fontfile: str | None,
+) -> str | None:
+    """Burn session clock that maps output t in [0, out_duration] → session range."""
+    if not clock.enabled or out_duration <= 0:
+        return None
+    # session_sec = start + t * (end - start) / out_duration
+    span = session_end - session_start
+    # Avoid div by zero: hold at session_start
+    if abs(out_duration) < 1e-6:
+        rate = 0.0
+    else:
+        rate = span / out_duration
+    # ss expression in ffmpeg: session_start + t * rate
+    ss = f"({session_start:.6f}+t*{rate:.9f})"
+    # Format as M:SS (minutes may exceed 59) — matches script "0:00".
+    # Literal colon between mins/secs must be \: inside the filtergraph.
+    text_expr = (
+        f"%{{eif\\:{ss}/60\\:d}}\\:"
+        f"%{{eif\\:mod({ss}\\,60)\\:d\\:2}}"
+    )
+    if clock.prefix:
+        text_expr = esc_drawtext(clock.prefix) + text_expr
+
+    parts = [
+        f"drawtext=text='{text_expr}'",
+        f"x={clock.x}",
+        f"y={clock.y}",
+        f"fontsize={clock.font_size}",
+        f"fontcolor={clock.font_color}",
+        "expansion=normal",
+    ]
+    if fontfile:
+        parts.append(f"fontfile={esc_fontfile(fontfile)}")
+    if clock.box:
+        parts.append("box=1")
+        parts.append(f"boxcolor={clock.box_color}")
+        parts.append(f"boxborderw={clock.box_border_w}")
+    return ":".join(parts)
+
+
+def run_ffmpeg(ffmpeg: str, args: list[str], dry_run: bool) -> None:
+    cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-y", *args]
+    if dry_run:
+        print("DRY:", subprocess.list2cmdline(cmd))
+        return
+    # Show a short preview of the command (full -vf lines are huge).
+    preview = []
+    for a in cmd:
+        if len(a) > 80:
+            preview.append(a[:60] + "…")
+        else:
+            preview.append(a)
+    print("+", subprocess.list2cmdline(preview[:16]), "..." if len(preview) > 16 else "")
+    r = subprocess.run(cmd, check=False, capture_output=True, text=True)
+    if r.returncode != 0:
+        err = (r.stderr or r.stdout or "").strip()
+        if err:
+            print(err, file=sys.stderr)
+        raise SystemExit(f"ffmpeg failed ({r.returncode})")
+
+
+def write_vf_script(vf: str, path: Path) -> Path:
+    """Write a video filtergraph to a file (avoids Windows cmdline colon hell)."""
+    path.write_text(vf, encoding="utf-8")
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Segment encode
+# ---------------------------------------------------------------------------
+
+
+def resolve_source(tl_dir: Path, source: str | None) -> Path | None:
+    if not source:
+        return None
+    p = Path(source)
+    if not p.is_absolute():
+        p = (tl_dir / p).resolve()
+    return p
+
+
+def clip_source_duration(
+    ffmpeg: str, path: Path, in_sec: float | None, out_sec: float | None
+) -> float:
+    full = probe_duration(ffmpeg, path)
+    start = in_sec or 0.0
+    end = out_sec if out_sec is not None else full
+    if end <= start:
+        raise SystemExit(f"{path.name}: out_sec ({end}) must be > in_sec ({start})")
+    if start < 0 or start >= full:
+        raise SystemExit(f"{path.name}: in_sec {start} out of range (duration {full:.2f})")
+    return min(end, full) - start
+
+
+def output_duration_for_segment(
+    ffmpeg: str, seg: Segment, src: Path | None, placeholders: bool
+) -> float:
+    if seg.kind in ("still", "card"):
+        if seg.duration_sec is None or seg.duration_sec <= 0:
+            raise SystemExit(f"segment {seg.id}: duration_sec required")
+        return float(seg.duration_sec)
+    # clip
+    if placeholders and (src is None or not src.is_file()):
+        # Keep placeholder slates short even when real tape trims are long.
+        return 3.0
+    assert src is not None
+    raw = clip_source_duration(ffmpeg, src, seg.in_sec, seg.out_sec)
+    return raw / seg.speed
+
+
+def make_placeholder_clip(
+    ffmpeg: str,
+    out: Path,
+    *,
+    width: int,
+    height: int,
+    fps: int,
+    duration: float,
+    label: str,
+    fontfile: str | None,
+    dry_run: bool,
+) -> None:
+    """Generate a labeled color slate used when footage is missing."""
+    # Use source duration = duration (speed already applied by caller? for placeholders
+    # we generate final-length segment video).
+    vf_parts = [
+        f"scale={width}:{height}",
+        "setsar=1",
+    ]
+    dt = (
+        f"drawtext=text='{esc_drawtext(label)}':"
+        f"x=(w-tw)/2:y=(h-th)/2:fontsize=48:fontcolor=white:"
+        f"box=1:boxcolor=black@0.45:boxborderw=16"
+    )
+    if fontfile:
+        dt += f":fontfile={esc_fontfile(fontfile)}"
+    vf_parts.append(dt)
+    vf = ",".join(vf_parts)
+    script = out.with_suffix(".vf.txt")
+    run_ffmpeg(
+        ffmpeg,
+        [
+            "-f",
+            "lavfi",
+            "-i",
+            f"color=c=0x123048:s={width}x{height}:d={duration:.4f}:r={fps}",
+            "-f",
+            "lavfi",
+            "-i",
+            "anullsrc=channel_layout=stereo:sample_rate=48000",
+            *vf_args(vf, script),
+            "-t",
+            f"{duration:.4f}",
+            "-c:v",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-c:a",
+            "aac",
+            "-shortest",
+            str(out),
+        ],
+        dry_run,
+    )
+
+
+def encode_segment(
+    ffmpeg: str,
+    tl: Timeline,
+    seg: Segment,
+    out_path: Path,
+    *,
+    fontfile: str | None,
+    placeholders: bool,
+    dry_run: bool,
+) -> Path:
+    v = tl.video
+    tl_dir = tl.path.parent
+    src = resolve_source(tl_dir, seg.source)
+
+    if seg.kind == "card":
+        return _encode_card(ffmpeg, tl, seg, out_path, fontfile, dry_run)
+
+    if seg.kind == "still":
+        return _encode_still(ffmpeg, tl, seg, out_path, fontfile, dry_run, src)
+
+    # clip
+    missing = src is None or not src.is_file()
+    if missing and not placeholders:
+        raise SystemExit(
+            f"segment {seg.id}: missing footage {seg.source!r}. "
+            f"Record it (see record.md) or pass --placeholders."
+        )
+
+    out_dur = output_duration_for_segment(ffmpeg, seg, src, placeholders=missing)
+    if missing:
+        # Labeled slate at final output duration, then burn session clock.
+        tmp = out_path.with_suffix(".pre.mp4")
+        make_placeholder_clip(
+            ffmpeg,
+            tmp if not dry_run else out_path,
+            width=v.width,
+            height=v.height,
+            fps=v.fps,
+            duration=out_dur,
+            label=f"{seg.id} (placeholder)",
+            fontfile=fontfile,
+            dry_run=dry_run,
+        )
+        if dry_run:
+            return out_path
+        _reclock(
+            ffmpeg,
+            tmp,
+            out_path,
+            tl,
+            seg,
+            out_dur,
+            fontfile,
+            keep_audio=False,
+            dry_run=dry_run,
+        )
+        tmp.unlink(missing_ok=True)
+        return out_path
+
+    assert src is not None and src.is_file()
+    raw = clip_source_duration(ffmpeg, src, seg.in_sec, seg.out_sec)
+
+    # Inputs first (ffmpeg option order), then maps / filters / codecs.
+    args: list[str] = []
+    if seg.in_sec is not None:
+        args.extend(["-ss", f"{seg.in_sec:.4f}"])
+    args.extend(["-i", str(src)])
+    if not seg.keep_audio:
+        args.extend(
+            [
+                "-f",
+                "lavfi",
+                "-i",
+                "anullsrc=channel_layout=stereo:sample_rate=48000",
+            ]
+        )
+
+    # speed S means play S× faster → setpts = PTS/S
+    setpts = f"setpts=PTS/{seg.speed}"
+    vf = f"{scale_pad_vf(v.width, v.height)},fps={v.fps},{setpts}"
+    if seg.show_clock and tl.clock.enabled:
+        clock_f = clock_drawtext(
+            tl.clock, seg.session_start_sec, seg.session_end_sec, out_dur, fontfile
+        )
+        if clock_f:
+            vf = f"{vf},{clock_f}"
+    args.extend(vf_args(vf, out_path.with_suffix(".vf.txt")))
+
+    # Trim source read length (pre-speed); setpts shortens the output timeline.
+    args.extend(["-t", f"{raw:.4f}"])
+
+    if seg.keep_audio:
+        atempo = _atempo_filters(seg.speed)
+        if atempo:
+            args.extend(["-af", atempo])
+        args.extend(["-map", "0:v:0", "-map", "0:a:0?"])
+    else:
+        args.extend(["-map", "0:v:0", "-map", "1:a:0", "-shortest"])
+
+    args.extend(
+        [
+            "-c:v",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-preset",
+            v.preset,
+            "-crf",
+            str(v.crf),
+            "-r",
+            str(v.fps),
+            "-c:a",
+            "aac",
+            "-ar",
+            "48000",
+            "-ac",
+            "2",
+            str(out_path),
+        ]
+    )
+    run_ffmpeg(ffmpeg, args, dry_run)
+    return out_path
+
+
+def _atempo_filters(speed: float) -> str | None:
+    """Return atempo filter chain for playback speed S (S>1 faster)."""
+    if abs(speed - 1.0) < 1e-6:
+        return None
+    # atempo is tempo factor = speed (play faster → higher tempo)
+    factors: list[float] = []
+    remaining = speed
+    # Clamp each stage to [0.5, 2.0]
+    if remaining > 1:
+        while remaining > 2.0 + 1e-9:
+            factors.append(2.0)
+            remaining /= 2.0
+        factors.append(remaining)
+    else:
+        while remaining < 0.5 - 1e-9:
+            factors.append(0.5)
+            remaining /= 0.5
+        factors.append(remaining)
+    return ",".join(f"atempo={f:.6f}" for f in factors)
+
+
+def _reclock(
+    ffmpeg: str,
+    src: Path,
+    out: Path,
+    tl: Timeline,
+    seg: Segment,
+    out_dur: float,
+    fontfile: str | None,
+    *,
+    keep_audio: bool,
+    dry_run: bool,
+) -> None:
+    vf = scale_pad_vf(tl.video.width, tl.video.height)
+    if seg.show_clock and tl.clock.enabled:
+        clock_f = clock_drawtext(
+            tl.clock, seg.session_start_sec, seg.session_end_sec, out_dur, fontfile
+        )
+        if clock_f:
+            vf = f"{vf},{clock_f}"
+    args = [
+        "-i",
+        str(src),
+        "-f",
+        "lavfi",
+        "-i",
+        "anullsrc=channel_layout=stereo:sample_rate=48000",
+        *vf_args(vf, out.with_suffix(".vf.txt")),
+        "-map",
+        "0:v:0",
+        "-map",
+        "1:a:0" if not keep_audio else "0:a:0?",
+        "-c:v",
+        "libx264",
+        "-pix_fmt",
+        "yuv420p",
+        "-preset",
+        tl.video.preset,
+        "-crf",
+        str(tl.video.crf),
+        "-r",
+        str(tl.video.fps),
+        "-c:a",
+        "aac",
+        "-ar",
+        "48000",
+        "-ac",
+        "2",
+        "-t",
+        f"{out_dur:.4f}",
+        "-shortest",
+        str(out),
+    ]
+    run_ffmpeg(ffmpeg, args, dry_run)
+
+
+def _encode_still(
+    ffmpeg: str,
+    tl: Timeline,
+    seg: Segment,
+    out_path: Path,
+    fontfile: str | None,
+    dry_run: bool,
+    src: Path | None,
+) -> Path:
+    v = tl.video
+    dur = float(seg.duration_sec or 3.0)
+    if src is None or not src.is_file():
+        # solid fallback
+        make_placeholder_clip(
+            ffmpeg,
+            out_path,
+            width=v.width,
+            height=v.height,
+            fps=v.fps,
+            duration=dur,
+            label=tl.brand.title,
+            fontfile=fontfile,
+            dry_run=dry_run,
+        )
+        if not dry_run and seg.show_clock:
+            tmp = out_path.with_suffix(".tmp.mp4")
+            out_path.rename(tmp)
+            _reclock(
+                ffmpeg,
+                tmp,
+                out_path,
+                tl,
+                seg,
+                dur,
+                fontfile,
+                keep_audio=False,
+                dry_run=dry_run,
+            )
+            tmp.unlink(missing_ok=True)
+        return out_path
+
+    vf = scale_pad_vf(v.width, v.height)
+    # optional title overlay on open
+    if seg.title_overlay:
+        title = esc_drawtext(tl.brand.title)
+        tag = esc_drawtext(tl.brand.tagline)
+        t1 = (
+            f"drawtext=text='{title}':x=80:y=h-180:fontsize=64:"
+            f"fontcolor=0x40c4ff:box=1:boxcolor=black@0.4:boxborderw=14"
+        )
+        t2 = (
+            f"drawtext=text='{tag}':x=80:y=h-100:fontsize=32:"
+            f"fontcolor=white:box=1:boxcolor=black@0.4:boxborderw=10"
+        )
+        if fontfile:
+            t1 += f":fontfile={esc_fontfile(fontfile)}"
+            t2 += f":fontfile={esc_fontfile(fontfile)}"
+        vf = f"{vf},{t1},{t2}"
+    if seg.show_clock and tl.clock.enabled:
+        clock_f = clock_drawtext(
+            tl.clock, seg.session_start_sec, seg.session_end_sec, dur, fontfile
+        )
+        if clock_f:
+            vf = f"{vf},{clock_f}"
+
+    run_ffmpeg(
+        ffmpeg,
+        [
+            "-loop",
+            "1",
+            "-i",
+            str(src),
+            "-f",
+            "lavfi",
+            "-i",
+            "anullsrc=channel_layout=stereo:sample_rate=48000",
+            *vf_args(vf, out_path.with_suffix(".vf.txt")),
+            "-t",
+            f"{dur:.4f}",
+            "-c:v",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-preset",
+            v.preset,
+            "-crf",
+            str(v.crf),
+            "-r",
+            str(v.fps),
+            "-c:a",
+            "aac",
+            "-shortest",
+            str(out_path),
+        ],
+        dry_run,
+    )
+    return out_path
+
+
+def _encode_card(
+    ffmpeg: str,
+    tl: Timeline,
+    seg: Segment,
+    out_path: Path,
+    fontfile: str | None,
+    dry_run: bool,
+) -> Path:
+    v = tl.video
+    dur = float(seg.duration_sec or 4.0)
+    lines = seg.lines or [tl.brand.credit_url]
+    primary = esc_drawtext(lines[0])
+    sub = esc_drawtext(seg.subtitle or tl.brand.tagline)
+    t1 = (
+        f"drawtext=text='{primary}':x=(w-tw)/2:y=(h-th)/2-20:fontsize=44:"
+        f"fontcolor=0x40c4ff:box=1:boxcolor=black@0.35:boxborderw=18"
+    )
+    t2 = (
+        f"drawtext=text='{sub}':x=(w-tw)/2:y=(h-th)/2+60:fontsize=28:"
+        f"fontcolor=0xd2dce0"
+    )
+    if fontfile:
+        t1 += f":fontfile={esc_fontfile(fontfile)}"
+        t2 += f":fontfile={esc_fontfile(fontfile)}"
+    vf = f"setsar=1,{t1},{t2}"
+    if seg.show_clock and tl.clock.enabled:
+        clock_f = clock_drawtext(
+            tl.clock, seg.session_start_sec, seg.session_end_sec, dur, fontfile
+        )
+        if clock_f:
+            vf = f"{vf},{clock_f}"
+
+    run_ffmpeg(
+        ffmpeg,
+        [
+            "-f",
+            "lavfi",
+            "-i",
+            f"color=c=0x0a101c:s={v.width}x{v.height}:d={dur:.4f}:r={v.fps}",
+            "-f",
+            "lavfi",
+            "-i",
+            "anullsrc=channel_layout=stereo:sample_rate=48000",
+            *vf_args(vf, out_path.with_suffix(".vf.txt")),
+            "-t",
+            f"{dur:.4f}",
+            "-c:v",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-preset",
+            v.preset,
+            "-crf",
+            str(v.crf),
+            "-c:a",
+            "aac",
+            "-shortest",
+            str(out_path),
+        ],
+        dry_run,
+    )
+    return out_path
+
+
+def concat_segments(
+    ffmpeg: str,
+    parts: list[Path],
+    out: Path,
+    *,
+    crf: int,
+    preset: str,
+    dry_run: bool,
+) -> None:
+    """Concat demuxer; re-encode once for clean A/V alignment."""
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".txt", delete=False, encoding="utf-8"
+    ) as f:
+        list_path = Path(f.name)
+        for p in parts:
+            # concat demuxer needs escaped single quotes in paths
+            ap = p.resolve().as_posix().replace("'", "'\\''")
+            f.write(f"file '{ap}'\n")
+    try:
+        run_ffmpeg(
+            ffmpeg,
+            [
+                "-f",
+                "concat",
+                "-safe",
+                "0",
+                "-i",
+                str(list_path),
+                "-c:v",
+                "libx264",
+                "-pix_fmt",
+                "yuv420p",
+                "-preset",
+                preset,
+                "-crf",
+                str(crf),
+                "-c:a",
+                "aac",
+                "-movflags",
+                "+faststart",
+                str(out),
+            ],
+            dry_run,
+        )
+    finally:
+        list_path.unlink(missing_ok=True)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def check_footage(tl: Timeline) -> int:
+    tl_dir = tl.path.parent
+    missing = []
+    present = []
+    for seg in tl.segments:
+        if seg.kind != "clip" or not seg.source:
+            continue
+        p = resolve_source(tl_dir, seg.source)
+        if p and p.is_file():
+            present.append(str(p.relative_to(tl_dir) if p.is_relative_to(tl_dir) else p))
+        else:
+            missing.append(seg.source)
+    print(f"clips present: {len(present)}")
+    for p in present:
+        print(f"  OK  {p}")
+    print(f"clips missing: {len(missing)}")
+    for m in missing:
+        print(f"  --  {m}")
+    return 1 if missing else 0
+
+
+def plan_summary(tl: Timeline, ffmpeg: str | None, placeholders: bool) -> None:
+    print(f"timeline: {tl.path}")
+    print(f"output:   {tl.video.output}  ({tl.video.width}x{tl.video.height}@{tl.video.fps})")
+    total_out = 0.0
+    session_hi = 0.0
+    for seg in tl.segments:
+        src = resolve_source(tl.path.parent, seg.source)
+        try:
+            if ffmpeg:
+                od = output_duration_for_segment(ffmpeg, seg, src, placeholders)
+            else:
+                od = float(seg.duration_sec or 0) if seg.kind != "clip" else 0.0
+        except SystemExit as e:
+            od = 0.0
+            print(f"  ! {seg.id}: {e}")
+        total_out += od
+        session_hi = max(session_hi, seg.session_end_sec)
+        print(
+            f"  - {seg.id:20} kind={seg.kind:5} speed={seg.speed:g} "
+            f"out≈{od:6.2f}s  clock {seg.session_start_sec:.0f}→{seg.session_end_sec:.0f}s  "
+            f"{'(audio)' if seg.keep_audio else ''}"
+        )
+        if seg.note:
+            print(f"      note: {seg.note}")
+    print(f"approx video length: {total_out:.1f}s")
+    print(f"session clock end:   {session_hi:.0f}s ({session_hi/60:.1f} min)")
+
+
+def build(
+    tl: Timeline,
+    *,
+    placeholders: bool,
+    dry_run: bool,
+    keep_segments: bool,
+) -> Path:
+    ffmpeg = require_ffmpeg()
+    fontfile = find_font()
+    if fontfile:
+        print(f"font: {fontfile}")
+    else:
+        print("font: (default ffmpeg font — install a TTF if text looks wrong)")
+
+    plan_summary(tl, ffmpeg, placeholders)
+
+    out_rel = Path(tl.video.output)
+    out_path = out_rel if out_rel.is_absolute() else (tl.path.parent / out_rel)
+    seg_dir = out_path.parent / "segments"
+    if not dry_run:
+        seg_dir.mkdir(parents=True, exist_ok=True)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    parts: list[Path] = []
+    for i, seg in enumerate(tl.segments):
+        part = seg_dir / f"{i:02d}_{seg.id}.mp4"
+        print(f"\n=== segment {seg.id} → {part.name} ===")
+        encode_segment(
+            ffmpeg,
+            tl,
+            seg,
+            part,
+            fontfile=fontfile,
+            placeholders=placeholders,
+            dry_run=dry_run,
+        )
+        parts.append(part)
+
+    print(f"\n=== concat → {out_path} ===")
+    concat_segments(
+        ffmpeg,
+        parts,
+        out_path,
+        crf=tl.video.crf,
+        preset=tl.video.preset,
+        dry_run=dry_run,
+    )
+    if not dry_run and not keep_segments:
+        # keep segments by default for re-edit; only delete if asked? keep them.
+        pass
+    if not dry_run:
+        size = out_path.stat().st_size if out_path.is_file() else 0
+        print(f"\nWrote {out_path} ({size / 1_000_000:.2f} MB)")
+    return out_path
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Build silico README hero video")
+    ap.add_argument(
+        "--timeline",
+        type=Path,
+        default=DEFAULT_TIMELINE,
+        help="path to timeline.toml",
+    )
+    ap.add_argument(
+        "--placeholders",
+        action="store_true",
+        help="synthesize missing clips as labeled slates (pipeline smoke)",
+    )
+    ap.add_argument(
+        "--check-footage",
+        action="store_true",
+        help="list present/missing clip sources and exit",
+    )
+    ap.add_argument(
+        "--plan",
+        action="store_true",
+        help="print segment plan only (no encode)",
+    )
+    ap.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="print ffmpeg commands without running",
+    )
+    ap.add_argument(
+        "--keep-segments",
+        action="store_true",
+        default=True,
+        help="keep out/segments/*.mp4 (default: true)",
+    )
+    args = ap.parse_args(argv)
+
+    path = args.timeline.resolve()
+    if not path.is_file():
+        print(f"timeline not found: {path}", file=sys.stderr)
+        return 2
+
+    tl = load_timeline(path)
+
+    if args.check_footage:
+        return check_footage(tl)
+
+    if args.plan:
+        ff = shutil.which("ffmpeg")
+        plan_summary(tl, ff, placeholders=args.placeholders)
+        return 0
+
+    build(
+        tl,
+        placeholders=args.placeholders,
+        dry_run=args.dry_run,
+        keep_segments=args.keep_segments,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/docs/hero-video/footage/.gitkeep b/docs/hero-video/footage/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/hero-video/out/.gitkeep b/docs/hero-video/out/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/hero-video/record.md b/docs/hero-video/record.md
new file mode 100644
index 0000000..5ad2635
--- /dev/null
+++ b/docs/hero-video/record.md
@@ -0,0 +1,76 @@
+# Capture checklist — hero video footage
+
+Record once, re-cut forever. Put finished clips in `docs/hero-video/footage/` using the names below (or edit `timeline.toml` to match your filenames).
+
+**Tools (suggested):** OBS, Windows Game Bar, macOS Screenshot→Record, or any 1080p60 capture. Prefer **16:9**, **constant frame rate**, no heavy compression artifacts on terminal text.
+
+**Audio:** desk / boot clip must include the boot sound. Other clips may be silent; the assembler can drop audio on time-lapse segments.
+
+---
+
+## Before you roll
+
+1. **Clean start practice GCU:** for a honest Xuss first-ship capture, `tig/xuss` `main` tip should be the product-only clean start (see silico `AGENTS.md` practice-GCU rules). Reset only with operator go.
+2. **Quiet desktop:** hide unrelated windows, large fonts in terminal (14–18 pt), dark theme OK if contrast is high.
+3. **Cursor:** slow deliberate moves on GitHub scroll and highlight; viewers cannot read a 4× mouse blur.
+4. **Clock truth:** note wall-clock start when you paste the agent prompt (or when the session truly starts). Fill `session_start_sec` / `session_end_sec` in `timeline.toml` from that log so the burn-in clock matches real elapsed first-ship time.
+5. **Surprising metal:** boot tone / LEDs — fine in the desk clip; do not startle someone off-camera without a heads-up.
+
+---
+
+## Expected clips
+
+| File | Content | Length (raw) | Notes |
+|------|---------|--------------|--------|
+| `01-gh-silico-getting-started.mp4` | github.com/tig/silico → scroll Getting Started → hold on agent prompt | 20–40 s | Highlight prompt (browser find, cursor, or zoom). |
+| `02-terminal-clone-and-prompt.mp4` | `git clone` xuss → `cd` → start `grok` (or your agent) → paste start prompt | 30–90 s | Readable typing or paste; no password leaks. |
+| `03-agent-session.mp4` | Full agent session from welcome through host gate + metal path | often 20–90+ min | One long take is fine; timeline splits + speeds handle pacing. |
+| `04-desk-xuss-boot-demo.mp4` | Board on desk: boot sound, product face, short function demo | 15–45 s | Keep **audio**. Good light; board fills frame. |
+| `05-xuss-ci-green.mp4` | tig/xuss Actions (or checks on main) green | 5–15 s | Hold on green check. |
+
+Opening still uses repo `docs/hero.jpg` (no capture). End card is generated by `build.py`.
+
+---
+
+## Mark human gates in the session tape
+
+While recording `03-agent-session.mp4`, drop a **marker** (OBS chapter, spoken “gate”, or notepad timestamps) at:
+
+| Marker | Why slow in edit |
+|--------|------------------|
+| Start gate (yes / adjust) | First human go |
+| Plug USB / wait-device | Physical act |
+| Confirm board | Identity |
+| Confirm deploy | Scary write |
+| Product-face observe | “Do you see/hear …?” |
+
+In `timeline.toml`, cut those windows as separate `[[segments]]` with `speed = 1.0` (or `0.75`) and time-lapse the agent-only stretches with `speed = 20`–`60`.
+
+---
+
+## Session time log (fill while recording)
+
+```text
+session_t0 (paste prompt or agent start): ____:____:____ local
+welcome visible: +____ s
+start gate answered: +____ s
+host gate green: +____ s
+board confirmed: +____ s
+deploy done / face observed: +____ s
+CI green on remote: +____ s
+```
+
+Copy those offsets into each segment’s `session_start_sec` / `session_end_sec`.
+
+---
+
+## After capture
+
+```text
+cd docs/hero-video
+python build.py --check-footage
+python build.py                 # full assemble
+python build.py --placeholders  # smoke pipeline without real clips
+```
+
+Review `out/hero.mp4`. Adjust speeds and trims; re-run. Publish per [README.md](README.md).
diff --git a/docs/hero-video/timeline.toml b/docs/hero-video/timeline.toml
new file mode 100644
index 0000000..2236c40
--- /dev/null
+++ b/docs/hero-video/timeline.toml
@@ -0,0 +1,147 @@
+# Machine plan for the silico × xuss README hero video.
+# Human storyboard: SCRIPT.md · capture: record.md · assemble: build.py
+#
+# session_*_sec = real first-ship elapsed time shown on the on-screen clock
+# (not the length of the edited video). speed > 1 = time-lapse; speed < 1 = slow-mo.
+
+[video]
+width = 1920
+height = 1080
+fps = 30
+output = "out/hero.mp4"
+# CRF quality (lower = larger/better). 20 is a good README/release default.
+crf = 20
+# Prefer yuv420p + +faststart for web playback.
+preset = "medium"
+
+[brand]
+title = "silico"
+tagline = "Prompt to metal."
+credit_url = "https://github.com/tig/silico"
+# Opening still relative to this file's directory (docs/hero-video/).
+hero_image = "../hero.jpg"
+
+[clock]
+enabled = true
+# ffmpeg drawtext x/y expressions (w/h = frame, tw/th = text box)
+x = "w-tw-48"
+y = "40"
+font_size = 40
+font_color = "white"
+box = true
+box_color = "black@0.55"
+box_border_w = 12
+# Prefix shown before time, e.g. "" or "T+"
+prefix = ""
+
+# ---------------------------------------------------------------------------
+# Segments play in order. kind = still | clip | card
+# ---------------------------------------------------------------------------
+
+[[segments]]
+id = "open"
+kind = "still"
+source = "../hero.jpg"
+duration_sec = 3.0
+session_start_sec = 0
+session_end_sec = 0
+show_clock = true
+title_overlay = true
+
+[[segments]]
+id = "gh-scroll"
+kind = "clip"
+source = "footage/01-gh-silico-getting-started.mp4"
+# in_sec / out_sec optional (seconds into source). Omit out_sec = to end.
+speed = 1.0
+session_start_sec = 0
+session_end_sec = 45
+show_clock = true
+keep_audio = false
+note = "Scroll silico README to Getting Started; highlight agent prompt."
+
+[[segments]]
+id = "terminal-start"
+kind = "clip"
+source = "footage/02-terminal-clone-and-prompt.mp4"
+speed = 1.0
+session_start_sec = 45
+session_end_sec = 120
+show_clock = true
+keep_audio = false
+note = "git clone xuss, cd, start grok, paste prompt."
+
+# Welcome: slow for readability (~2–3 s of readable screen time).
+# After capture, set in_sec/out_sec to the welcome window in 03-agent-session.mp4.
+[[segments]]
+id = "welcome-slow"
+kind = "clip"
+source = "footage/03-agent-session.mp4"
+in_sec = 0.0
+out_sec = 8.0
+speed = 0.35
+session_start_sec = 120
+session_end_sec = 150
+show_clock = true
+keep_audio = false
+note = "Stage 0a welcome skeleton; slow so it is readable."
+
+# Agent work time-lapse — split further after first capture using gate markers.
+[[segments]]
+id = "agent-timelapse"
+kind = "clip"
+source = "footage/03-agent-session.mp4"
+in_sec = 8.0
+# Leave out_sec unset until you know the tape end before metal demo cutaway.
+speed = 30.0
+session_start_sec = 150
+session_end_sec = 2400
+show_clock = true
+keep_audio = false
+note = "Time-lapse first ship; re-split into gate-slow segments after markers."
+
+# Example human-gate insert (enable by setting real in/out after capture):
+# [[segments]]
+# id = "gate-deploy"
+# kind = "clip"
+# source = "footage/03-agent-session.mp4"
+# in_sec = 1200
+# out_sec = 1230
+# speed = 1.0
+# session_start_sec = 2100
+# session_end_sec = 2130
+# show_clock = true
+# keep_audio = false
+# note = "confirm-deploy operator gate at 1×"
+
+[[segments]]
+id = "desk-metal"
+kind = "clip"
+source = "footage/04-desk-xuss-boot-demo.mp4"
+speed = 1.0
+session_start_sec = 2400
+session_end_sec = 2520
+show_clock = true
+keep_audio = true
+note = "Desk: boot sound, product face, short demo."
+
+[[segments]]
+id = "ci-green"
+kind = "clip"
+source = "footage/05-xuss-ci-green.mp4"
+speed = 1.0
+session_start_sec = 2520
+session_end_sec = 2580
+show_clock = true
+keep_audio = false
+note = "tig/xuss CI green on main."
+
+[[segments]]
+id = "credits"
+kind = "card"
+duration_sec = 4.0
+session_start_sec = 2580
+session_end_sec = 2580
+show_clock = false
+lines = ["https://github.com/tig/silico"]
+subtitle = "Prompt to metal."
diff --git a/tests/test_hero_video_build.py b/tests/test_hero_video_build.py
new file mode 100644
index 0000000..e73a7d5
--- /dev/null
+++ b/tests/test_hero_video_build.py
@@ -0,0 +1,139 @@
+"""Host tests for docs/hero-video assembler (no product domain)."""
+
+from __future__ import annotations
+
+import importlib.util
+import shutil
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO = Path(__file__).resolve().parents[1]
+BUILD_PY = REPO / "docs" / "hero-video" / "build.py"
+TIMELINE = REPO / "docs" / "hero-video" / "timeline.toml"
+
+
+def _load_build():
+    spec = importlib.util.spec_from_file_location("hero_video_build", BUILD_PY)
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["hero_video_build"] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+@pytest.fixture(scope="module")
+def hv():
+    return _load_build()
+
+
+def test_timeline_loads_and_has_script_beats(hv):
+    tl = hv.load_timeline(TIMELINE)
+    ids = [s.id for s in tl.segments]
+    assert ids[0] == "open"
+    assert "welcome-slow" in ids
+    assert "desk-metal" in ids
+    assert "ci-green" in ids
+    assert ids[-1] == "credits"
+    assert tl.brand.credit_url.startswith("https://github.com/tig/silico")
+    assert tl.clock.enabled
+
+
+def test_clock_drawtext_maps_session_range(hv):
+    clock = hv.ClockCfg()
+    f = hv.clock_drawtext(clock, 120.0, 180.0, 10.0, fontfile=None)
+    assert f is not None
+    assert "drawtext=" in f
+    assert "120" in f
+    # rate = (180-120)/10 = 6
+    assert "6" in f or "6.0" in f
+
+
+def test_atempo_chains_for_extreme_speed(hv):
+    assert hv._atempo_filters(1.0) is None
+    fast = hv._atempo_filters(30.0)
+    assert fast is not None
+    assert "atempo=" in fast
+    slow = hv._atempo_filters(0.35)
+    assert slow is not None
+
+
+def test_check_footage_reports_missing(hv):
+    tl = hv.load_timeline(TIMELINE)
+    code = hv.check_footage(tl)
+    # Fresh clone has no recorded clips
+    assert code == 1
+
+
+def test_plan_does_not_require_footage(hv, capsys):
+    tl = hv.load_timeline(TIMELINE)
+    hv.plan_summary(tl, ffmpeg=None, placeholders=True)
+    out = capsys.readouterr().out
+    assert "open" in out
+    assert "session clock end" in out
+
+
+@pytest.mark.skipif(shutil.which("ffmpeg") is None, reason="ffmpeg not on PATH")
+def test_placeholder_build_smoke(hv, tmp_path):
+    """Encode a tiny placeholder cut into tmp (validates ffmpeg filter graph)."""
+    # Minimal timeline: open still + credits card only
+    mini = tmp_path / "timeline.toml"
+    hero = REPO / "docs" / "hero.jpg"
+    mini.write_text(
+        f"""
+[video]
+width = 640
+height = 360
+fps = 15
+output = "out/hero.mp4"
+crf = 28
+preset = "ultrafast"
+
+[brand]
+title = "silico"
+tagline = "Prompt to metal."
+credit_url = "https://github.com/tig/silico"
+hero_image = "{hero.as_posix()}"
+
+[clock]
+enabled = true
+font_size = 24
+
+[[segments]]
+id = "open"
+kind = "still"
+source = "{hero.as_posix()}"
+duration_sec = 0.4
+session_start_sec = 0
+session_end_sec = 0
+show_clock = true
+title_overlay = true
+
+[[segments]]
+id = "slate"
+kind = "clip"
+source = "footage/missing.mp4"
+speed = 1.0
+session_start_sec = 0
+session_end_sec = 30
+show_clock = true
+
+[[segments]]
+id = "credits"
+kind = "card"
+duration_sec = 0.4
+session_start_sec = 30
+session_end_sec = 30
+show_clock = false
+lines = ["https://github.com/tig/silico"]
+subtitle = "Prompt to metal."
+""",
+        encoding="utf-8",
+    )
+    tl = hv.load_timeline(mini)
+    # Rewrite output under tmp
+    tl.video.output = str((tmp_path / "out" / "hero.mp4").as_posix())
+    out = hv.build(tl, placeholders=True, dry_run=False, keep_segments=True)
+    assert out.is_file()
+    assert out.stat().st_size > 1000

From e2a0b466d39eab85d17766d8b203ecf6d450dbc7 Mon Sep 17 00:00:00 2001
From: Tig <tig@users.noreply.github.com>
Date: Sat, 25 Jul 2026 07:57:34 -0600
Subject: [PATCH 2/2] docs(hero-video): drive onscreen takes with tig/mcec

Prefer MCEC for browser/terminal/agent/CI capture (record GIF + agent drive),
matching mcec/WinPrint hero recipes. Desk metal stays camera. Document GIF
duration limits, segmented takes, and point timeline sources at .gif files.
---
 .gitignore                     |   1 +
 docs/hero-video/README.md      |  44 +++++--
 docs/hero-video/SCRIPT.md      |  21 +--
 docs/hero-video/mcec.md        | 226 +++++++++++++++++++++++++++++++++
 docs/hero-video/record.md      |  74 ++++++-----
 docs/hero-video/timeline.toml  |  39 +++---
 tests/test_hero_video_build.py |  16 +++
 7 files changed, 349 insertions(+), 72 deletions(-)
 create mode 100644 docs/hero-video/mcec.md

diff --git a/.gitignore b/.gitignore
index 982d60a..5748503 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,5 +23,6 @@ docs/hero-video/**/*.mp4
 docs/hero-video/**/*.mov
 docs/hero-video/**/*.mkv
 docs/hero-video/**/*.webm
+docs/hero-video/**/*.gif
 docs/hero-video/**/*.vf.txt
 docs/hero-video/**/*.pre.mp4
diff --git a/docs/hero-video/README.md b/docs/hero-video/README.md
index 5ce37d7..db7defe 100644
--- a/docs/hero-video/README.md
+++ b/docs/hero-video/README.md
@@ -5,24 +5,30 @@ Reproduce the **silico × xuss** end-to-end hero cut for the root [README](../..
 | File | Role |
 |------|------|
 | [SCRIPT.md](SCRIPT.md) | Narrative beats (what the viewer should see) |
-| [record.md](record.md) | How to capture each source clip |
+| [mcec.md](mcec.md) | **Onscreen drive + record** with [tig/mcec](https://github.com/tig/mcec) |
+| [record.md](record.md) | Capture checklist (MCEC vs desk camera) |
 | [timeline.toml](timeline.toml) | Edit decision list: order, trims, speed, session clock |
 | [build.py](build.py) | ffmpeg assembler (clock burn-in, stills, cards, concat) |
-| `footage/` | Your recordings (gitignored binaries) |
+| `footage/` | MCEC GIFs + desk MP4 (gitignored binaries) |
 | `out/` | Rendered `hero.mp4` (gitignored) |
 
 ## Prerequisites
 
-- **ffmpeg** on `PATH` (`ffmpeg -version`)
-- **Python 3.11+** (stdlib only: `tomllib`, `argparse`, `subprocess`, …)
-- Source clips under `footage/` **or** use `--placeholders` to smoke the pipeline
+- **Windows** host for onscreen takes (MCEC is Windows-only computer use)
+- **[tig/mcec](https://github.com/tig/mcec)** controller via `scripts/Generate-HeroGif.ps1` from a mcec clone (see [mcec.md](mcec.md))
+- **ffmpeg** on `PATH`
+- **Python 3.11+** (stdlib only for `build.py`)
+- Source clips under `footage/` **or** `--placeholders` to smoke the pipeline
 
-Optional: a font ffmpeg can find for `drawtext` (Windows: `C:\\Windows\\Fonts\\segoeui.ttf`; macOS: Helvetica; Linux: DejaVu). The builder probes common paths.
+Optional: a font ffmpeg can find for `drawtext` (Windows Segoe UI, etc.).
 
 ## Quick start
 
 ```text
-# From repo root or this directory:
+# 1) Capture onscreen with MCEC (playbook):
+#    docs/hero-video/mcec.md
+
+# 2) Assemble:
 python docs/hero-video/build.py --placeholders
 python docs/hero-video/build.py --check-footage
 python docs/hero-video/build.py
@@ -33,6 +39,21 @@ Outputs:
 - `docs/hero-video/out/hero.mp4` — final cut
 - `docs/hero-video/out/segments/` — intermediate segment encodes (debug)
 
+## Capture model
+
+```text
+  MCEC (drive + record GIF)          Camera
+  ├─ browser silico README           └─ desk xuss boot / product face
+  ├─ terminal clone + agent start
+  ├─ agent welcome + staged first ship
+  └─ browser xuss CI green
+           │
+           ▼
+  footage/*  →  build.py + timeline.toml  →  out/hero.mp4
+```
+
+MCEC `record` is **GIF**, typically **≤60 s** per take unless you raise controller limits. Long first-ship UI is **multiple takes**; the timeline time-lapses them. Session clock in the final video is still real first-ship elapsed time (`session_*_sec`).
+
 ## Clock semantics
 
 The on-screen timer is **first-ship session elapsed**, not video wall-clock.
@@ -43,9 +64,9 @@ Fill session times from the log in [record.md](record.md) after a real capture.
 
 ## Editing workflow
 
-1. Record clips per [record.md](record.md).
-2. Set `in_sec` / `out_sec` / `speed` on each `[[segments]]` entry in `timeline.toml`.
-3. Split the long agent tape into **gate-slow** vs **timelapse** segments (examples commented in the timeline).
+1. Capture onscreen with MCEC per [mcec.md](mcec.md); desk clip with a camera.
+2. Drop files into `footage/`; set `in_sec` / `out_sec` / `speed` in `timeline.toml`.
+3. Split agent UI into **gate-slow** vs **timelapse** segments.
 4. `python build.py` → review → tweak → repeat.
 5. Publish the mp4 (see below) and point the root README at it.
 
@@ -68,5 +89,6 @@ Suggested README shape once hosted:
 ## Design notes
 
 - Same spirit as `docs/_make_social_preview.py`: **docs tooling in-tree**, not product domain in the spine.
-- Placeholders keep the assemble path testable without committing multi‑hundred‑MB screen captures.
+- Onscreen path **composes** with [tig/mcec](https://github.com/tig/mcec) (drive + `record`); silico does not vendor MCEC.
+- Placeholders keep the assemble path testable without committing large captures.
 - No soft-fork of Bedside or first-ship manners: the video *shows* the path; [AGENTS.md](../../AGENTS.md) remains normative for agents.
diff --git a/docs/hero-video/SCRIPT.md b/docs/hero-video/SCRIPT.md
index 43acae6..9b96214 100644
--- a/docs/hero-video/SCRIPT.md
+++ b/docs/hero-video/SCRIPT.md
@@ -4,7 +4,9 @@ Narrative for the README **hero video**: one end-to-end first ship of the [Xuss]
 
 **Goal:** a viewer who has never opened the repo sees *prompt → clone → agent → board talking → CI green* in a short cut, with an on-screen clock that measures **real first-ship elapsed time** (not how long the edited video runs).
 
-**Assembly:** machine plan is [`timeline.toml`](timeline.toml). Build with [`build.py`](build.py). Capture notes: [`record.md`](record.md).
+**Assembly:** machine plan is [`timeline.toml`](timeline.toml). Build with [`build.py`](build.py).
+
+**Capture:** onscreen beats (browser, terminal, agent, CI) are **driven and recorded with [tig/mcec](https://github.com/tig/mcec)** — playbook [`mcec.md`](mcec.md). Desk metal is a separate camera take. Checklist: [`record.md`](record.md).
 
 ---
 
@@ -31,7 +33,7 @@ Tune segment `speed` / trims in `timeline.toml` after the first rough cut.
 
 ### 2. GitHub: silico Getting Started → copy the prompt
 
-- Screen recording of [github.com/tig/silico](https://github.com/tig/silico) (or the README rendered locally).
+- **MCEC** drives a browser to [github.com/tig/silico](https://github.com/tig/silico) and `record`s the window/region (GIF).
 - Scroll to **Getting Started** / **Step 3** (the agent start prompt).
 - Pause; highlight or zoom the prompt block so it is obviously the thing to copy:
 
@@ -43,7 +45,7 @@ Tune segment `speed` / trims in `timeline.toml` after the first rough cut.
 
 ### 3. Terminal — clone xuss, start agent, paste prompt
 
-- Clean terminal (or TUI shell) at a neutral home directory.
+- **MCEC** drives a clean terminal (large font) and records.
 - Commands, readable at 1× (or slight speed-up between commands only):
 
   ```sh
@@ -57,20 +59,21 @@ Tune segment `speed` / trims in `timeline.toml` after the first rough cut.
 
 ### 4. Welcome — slow for readability
 
-- From the agent session recording: the **Stage 0a orientation** (`silico welcome` skeleton in chat).
-- **Slow** so a viewer can read key lines (~2–3 s of *readable* on-screen time; use `speed < 1` in the timeline).
+- **MCEC** records the agent window for **Stage 0a** only (`silico welcome` skeleton).
+- **Slow** in the timeline so a viewer can read key lines (~2–3 s of *readable* on-screen time; `speed < 1`).
 - Do **not** race past “what Silico is / this GCU / start gate next.”
 
 ### 5. First-ship body — time-lapse, slow on human acts
 
-- Same session (or stitched session clips): Stage A→D as a **time-lapse**.
-- **Slow to ~1× (or gentle slow-mo)** whenever the human must act:
+- **MCEC** records the agent window in **multiple short takes** (GIF duration caps ~60 s default — see [mcec.md](mcec.md)).
+- Stage A→D as a **time-lapse** across those takes.
+- **Slow to ~1×** whenever the human must act:
   - start-gate / yes-adjust chooser
   - plug USB / board confirm
   - deploy overwrite confirm
   - product-face observe (“do you see/hear …?”)
 - Fast through pure agent work (installs, scaffold, pytest green, long thinking).
-- Prefer **many short segments** in `timeline.toml` (same file, different `in_sec`/`out_sec`/`speed`) over one opaque 30× clip.
+- Prefer **many short segments** in `timeline.toml` over one opaque 30× clip.
 
 ### 6. Desk — xuss on metal
 
@@ -82,7 +85,7 @@ Tune segment `speed` / trims in `timeline.toml` after the first rough cut.
 
 ### 7. GitHub — tig/xuss CI green
 
-- Browser or `gh` UI on [tig/xuss](https://github.com/tig/xuss): default branch / latest run **green**.
+- **MCEC** drives browser (or records `gh` UI) on [tig/xuss](https://github.com/tig/xuss): default branch / latest run **green**.
 - Hold long enough to read the check name (~2–3 s).
 
 ### 8. End card
diff --git a/docs/hero-video/mcec.md b/docs/hero-video/mcec.md
new file mode 100644
index 0000000..9f35c57
--- /dev/null
+++ b/docs/hero-video/mcec.md
@@ -0,0 +1,226 @@
+# Onscreen capture with [tig/mcec](https://github.com/tig/mcec)
+
+**Primary path for every desktop beat** in the silico × xuss hero: **MCEC drives the UI and records it**. No OBS / Game Bar for browser, terminal, agent TUI, or GitHub CI.
+
+Pattern matches MCEC’s own hero and WinPrint’s:
+
+| Project | Subject | Recipe |
+|---------|---------|--------|
+| [tig/mcec](https://github.com/tig/mcec) | MCEC Settings tour | [dev/hero-gif.md](https://github.com/tig/mcec/blob/develop/dev/hero-gif.md) |
+| [tig/winprint](https://github.com/tig/winprint) | WinPrint GUI | [docs/hero-gif-win.md](https://github.com/tig/winprint/blob/develop/docs/hero-gif-win.md) |
+| **tig/silico** (this file) | Browser + terminal + agent + CI | onscreen segments of [SCRIPT.md](SCRIPT.md) |
+
+**Not MCEC:** desk / metal product-face clip (real camera + mic). Opening still and end card are generated by [build.py](build.py).
+
+---
+
+## Why MCEC here
+
+- **Drive:** `launch`, `query`, `click`, `drag`, `send_command` (typed path through the real Windows UI).
+- **Record:** agent tool `record` → animated **GIF** of a window or screen region (no external screen-recorder).
+- **Reproduce:** a fresh agent with an MCP controller can re-run the playbook; tour logic lives in this doc, not a brittle committed macro.
+
+Shared MCP envelope, targeting gotchas, and absolute-path rules: mcec [Agent Control](https://tig.github.io/mcec/agent_control.html) and [hero-gif.md](https://github.com/tig/mcec/blob/develop/dev/hero-gif.md). This page only adds **silico-specific** subjects and outputs.
+
+---
+
+## Limits you must plan around
+
+MCEC `record` writes **GIF**, not MP4. Operator-clamped defaults (see mcec `AgentRecordMax*` settings):
+
+| Knob | Default | Meaning for this hero |
+|------|---------|------------------------|
+| `AgentRecordMaxDurationMs` | 60000 | ~**60 s** per take unless you raise it on the **controller** |
+| `AgentRecordMaxFrames` | 600 | Hard frame cap (at 5 fps ≈ 120 s) |
+| `AgentRecordMaxWidth` | 1280 | Downscale width; fine for web hero |
+| `AgentRecordMaxFps` | 30 | Cap; use **4–8 fps** for size |
+
+**Implication:** do **not** try one hour-long first-ship as a single `record`. Split onscreen work into **short takes** (table below). The final [timeline.toml](timeline.toml) stitches them and applies time-lapse / slow-mo; the burn-in clock still tracks real session time via `session_*_sec`.
+
+To allow longer agent-stage takes, raise `AgentRecordMaxDurationMs` / `AgentRecordMaxFrames` on the **throwaway controller** only (not your installed Program Files gates). Still prefer multiple stage clips for re-cuts.
+
+---
+
+## Outputs (land in `footage/`)
+
+Prefer **GIF from MCEC**, then either:
+
+1. Point `timeline.toml` `source` at the `.gif` (ffmpeg reads GIF), or  
+2. Convert once: `ffmpeg -y -i clip.gif -pix_fmt yuv420p -movflags +faststart clip.mp4`
+
+| File | Subject | Max take (aim) | Notes |
+|------|---------|----------------|--------|
+| `01-gh-silico-getting-started.gif` | Browser on github.com/tig/silico | 20–45 s | Scroll Getting Started; highlight agent start prompt |
+| `02-terminal-clone-and-prompt.gif` | Terminal / shell | 30–60 s | `git clone` xuss → `cd` → start agent → paste prompt |
+| `03a-welcome.gif` | Agent TUI / chat | 15–45 s | Stage 0a welcome skeleton only; slow in timeline |
+| `03b-agent-work.gif` (+ more if needed) | Agent TUI | ≤60 s each | Host stages; stop/start `record` per stage or gate |
+| `03c-human-gates.gif` | Agent TUI | ≤60 s | Start gate / board / deploy confirms (real-time) |
+| `05-xuss-ci-green.gif` | Browser on tig/xuss Actions | 8–20 s | Green checks on main |
+
+Desk: `04-desk-xuss-boot-demo.mp4` (camera; **not** MCEC).
+
+Legacy names ending in `.mp4` still work if you convert first; [timeline.toml](timeline.toml) accepts either.
+
+---
+
+## Setup: MCEC controller
+
+Same bootstrap as other Kindel heroes — **from a clone of tig/mcec**, not from Program Files:
+
+```powershell
+# mcec repo root
+pwsh -NoProfile -File scripts/Generate-HeroGif.ps1
+# → HERO_MCP_URL=http://127.0.0.1:<port>/mcp
+```
+
+Register that URL with your agent MCP client, or POST JSON-RPC as in mcec’s hero-gif appendix.
+
+**Controller config for silico (marketing subject, not MCEC dogfood):**
+
+| Setting | Value | Why |
+|---------|--------|-----|
+| Command overlay | **OFF** | Same as WinPrint hero: clean product path, no burnt-orange narration |
+| `record` / `query` / `click` / `launch` / `send_command` / `displays` / `windows` / `drag` | enabled | Drive + record |
+| `AllowSessionProvisioning` | optional | Only if you provision throwaway subjects |
+
+Edit the throwaway controller under `%TEMP%\mcec-hero-controller-*` (`mcec.settings` / `mcec.commands`), then relaunch that copy’s `mcec.exe` if overlay is read only at startup.
+
+Tear down when done:
+
+```powershell
+pwsh -NoProfile -File scripts/Generate-HeroGif.ps1 -Stop
+```
+
+**Operator machine:** unlocked interactive Windows session (injected input), MCEC recent enough for `record` + tools you use, browser + terminal + agent TUI installed, `gh`/git auth already done so the capture does not leak tokens.
+
+---
+
+## Safety (do not skip)
+
+- Agent surface is **powerful**; emergency stop default **`Ctrl+Alt+Shift+S`** (physical keys only).
+- Prefer the **disposable controller** from `Generate-HeroGif.ps1`, not enabling gates on the Program Files install.
+- `record` captures the **whole duration** of the region — no credentials, secrets, or private chats in frame.
+- Every tool call is `AGENT-AUDIT:`-logged; that is intentional.
+
+Full model: [Agent Safety](https://tig.github.io/mcec/safety-emergency-stop-and-provisioning.html).
+
+---
+
+## Playbook (agent drives via MCEC tools)
+
+Coordinates are absolute screen pixels; **integers only**. Unwrap the double MCP envelope (`ok` / `result` / `error`) as in mcec hero-gif. Absolute paths for `record` `file=` (controller cwd is the temp copy).
+
+### Shared open for every take
+
+1. `displays` → primary `SX, SY, SW, SH`.
+2. Win+D: `send_command` `shiftdown:lwin` → `d` → `shiftup:lwin` (clear backdrop).
+3. Launch or focus the **subject** window (browser, terminal, agent) with `launch` / `windows` / `query`.
+4. `query` or `windows` → subject bounds `WX, WY, WW, WH`.
+5. `record start` on a region that includes the subject (and **not** unrelated private windows):
+
+   ```text
+   record {
+     action: "start",
+     x: WX, y: WY, width: WW, height: WH,   # or a band that fits the story
+     fps: 6,
+     maxWidth: 1280,
+     file: "<ABS>/silico/docs/hero-video/footage/<name>.gif"   # optional until stop
+   }
+   ```
+
+   Or omit `file` until `record stop` and pass absolute `file` there.
+
+6. Drive the beat (below). Dwell so text is readable (0.5–1.5 s on key frames).
+7. `record stop` with absolute `file` under `docs/hero-video/footage/`.
+8. Spot-check the GIF; re-take rather than “fix in post.”
+
+### Beat A — GitHub silico Getting Started (`01-…`)
+
+1. `launch` browser (or focus existing) → navigate to `https://github.com/tig/silico` (address bar via `click` + `chars:` + enter).
+2. Scroll until **Getting Started** / agent start prompt is in view (`send_command` page-down / wheel, or click TOC).
+3. Highlight the prompt block (browser find for a distinctive line of the prompt, or slow drag-select).
+4. Hold 2–3 s on the highlighted prompt.
+5. Stop record → `footage/01-gh-silico-getting-started.gif`.
+
+### Beat B — Terminal clone + agent + paste (`02-…`)
+
+1. Launch terminal (Windows Terminal / pwsh). Large font.
+2. Type or paste, **readable** pacing:
+
+   ```text
+   git clone https://github.com/tig/xuss
+   cd xuss
+   grok
+   ```
+
+3. Paste the Silico start prompt into the agent:
+
+   ```text
+   Read https://github.com/tig/silico's AGENTS.md. Follow the guidance there exactly. Stay in this product checkout.
+   ```
+
+4. Stop once the agent is clearly running (before the long first-ship monologue) → `footage/02-terminal-clone-and-prompt.gif`.
+
+### Beat C — Welcome only (`03a-…`)
+
+1. Focus the agent window once Stage **0a** orientation (`silico welcome` skeleton) is on screen.
+2. Record a short window where the welcome is fully readable; do not race.
+3. Stop → `footage/03a-welcome.gif`.  
+   In [timeline.toml](timeline.toml), play this segment with `speed < 1` so viewers get ~2–3 s of readable time.
+
+### Beat D — First-ship body, segmented (`03b…`, `03c…`)
+
+Drive (or let the product agent run while MCEC **records**) host stages and gates. **Start/stop `record` at natural boundaries:**
+
+| Take | Content | Timeline use |
+|------|---------|--------------|
+| `03b-host-stages.gif` | Tools install, workspace lock, scaffold, host gate green | high `speed` time-lapse |
+| `03c-human-gates.gif` | start-gate, confirm-board, confirm-deploy, product-face ask | `speed = 1` |
+| more `03d-…` as needed | metal inspect/deploy UI if on-screen | mix |
+
+Log wall-clock offsets in [record.md](record.md) so `session_*_sec` stay honest.
+
+If the product agent is a **different** process from the MCEC-driving agent: MCEC still records the product agent’s window; the operator (or a second agent connected to MCEC) only needs to start/stop `record` and optionally slow-scroll. Driving the product agent’s *judgments* is still the human / product session — MCEC does not replace Bedside gates.
+
+### Beat E — CI green (`05-…`)
+
+1. Browser → `https://github.com/tig/xuss/actions` (or PR checks).
+2. Hold on a green run for main / the ship branch.
+3. Stop → `footage/05-xuss-ci-green.gif`.
+
+### Desk (not MCEC)
+
+Phone or camera for boot sound + product face → `footage/04-desk-xuss-boot-demo.mp4`. Keep audio.
+
+---
+
+## After MCEC takes
+
+```text
+python docs/hero-video/build.py --check-footage
+python docs/hero-video/build.py
+```
+
+Tune trims/speeds in `timeline.toml`. Publish per [README.md](README.md).
+
+---
+
+## Anti-patterns
+
+| Don’t | Do |
+|-------|-----|
+| OBS for browser/terminal “because GIF is limited” | Multiple MCEC takes + timeline speed |
+| Record from Program Files MCEC with agent gates left on | Disposable controller (`Generate-HeroGif.ps1`) |
+| Overlay ON for silico marketing cut | Overlay OFF (product is silico, not MCEC) |
+| Relative `file` path for `record stop` | Absolute path under this repo’s `footage/` |
+| One multi-hour `record` | Segmented takes; optional higher controller max duration |
+| Past-HEAD salvage “last session’s screen” | Fresh clean-start xuss first ship when claiming honesty |
+
+---
+
+## Pointers
+
+- MCEC install: `winget install Kindel.mcec` — [docs](https://tig.github.io/mcec/)
+- `record` tool: [Agent Control — record](https://tig.github.io/mcec/agent_control.html)
+- Storyboard: [SCRIPT.md](SCRIPT.md)
+- Assemble: [build.py](build.py) + [timeline.toml](timeline.toml)
diff --git a/docs/hero-video/record.md b/docs/hero-video/record.md
index 5ad2635..42603cf 100644
--- a/docs/hero-video/record.md
+++ b/docs/hero-video/record.md
@@ -1,54 +1,68 @@
 # Capture checklist — hero video footage
 
-Record once, re-cut forever. Put finished clips in `docs/hero-video/footage/` using the names below (or edit `timeline.toml` to match your filenames).
+Record once, re-cut forever. Put finished clips in `docs/hero-video/footage/` (or edit `timeline.toml` to match your names).
 
-**Tools (suggested):** OBS, Windows Game Bar, macOS Screenshot→Record, or any 1080p60 capture. Prefer **16:9**, **constant frame rate**, no heavy compression artifacts on terminal text.
+## Capture tools (by beat)
 
-**Audio:** desk / boot clip must include the boot sound. Other clips may be silent; the assembler can drop audio on time-lapse segments.
+| Beats | Tool | Why |
+|-------|------|-----|
+| Browser, terminal, agent TUI, CI | **[tig/mcec](https://github.com/tig/mcec)** drive + `record` | Reproducible, window/region GIF, agent-operable — see **[mcec.md](mcec.md)** |
+| Desk product face + boot sound | Camera / phone | Real metal; MCEC cannot hear the board |
+| Opening / end card | [build.py](build.py) from `docs/hero.jpg` | No capture |
+
+Do **not** default to OBS for the onscreen path. MCEC is the intended driver/recorder; full playbook is [mcec.md](mcec.md).
+
+**MCEC output is GIF** (default max ~60 s / take). Split long first-ship UI into multiple takes; [timeline.toml](timeline.toml) stitches and time-lapses. ffmpeg accepts `.gif` sources directly.
+
+**Audio:** only the desk clip must include the boot sound. Onscreen GIFs are silent; the assembler does not need audio on those segments.
 
 ---
 
 ## Before you roll
 
-1. **Clean start practice GCU:** for a honest Xuss first-ship capture, `tig/xuss` `main` tip should be the product-only clean start (see silico `AGENTS.md` practice-GCU rules). Reset only with operator go.
-2. **Quiet desktop:** hide unrelated windows, large fonts in terminal (14–18 pt), dark theme OK if contrast is high.
-3. **Cursor:** slow deliberate moves on GitHub scroll and highlight; viewers cannot read a 4× mouse blur.
-4. **Clock truth:** note wall-clock start when you paste the agent prompt (or when the session truly starts). Fill `session_start_sec` / `session_end_sec` in `timeline.toml` from that log so the burn-in clock matches real elapsed first-ship time.
-5. **Surprising metal:** boot tone / LEDs — fine in the desk clip; do not startle someone off-camera without a heads-up.
+1. **Clean start practice GCU:** for an honest Xuss first-ship capture, `tig/xuss` `main` tip should be the product-only clean start (see silico `AGENTS.md`). Reset only with operator go.
+2. **MCEC controller:** stand up disposable MCP controller from a **tig/mcec** clone (`scripts/Generate-HeroGif.ps1`). Overlay **OFF** for this marketing cut. Details: [mcec.md](mcec.md).
+3. **Quiet desktop:** Win+D before each take; large fonts in terminal; no secrets in frame.
+4. **Clock truth:** note wall-clock when the agent start prompt is pasted (session t0). Fill `session_start_sec` / `session_end_sec` in `timeline.toml` from the log below.
+5. **Surprising metal:** boot tone / LEDs on the desk clip — heads-up for anyone in the room.
+6. **Emergency stop:** MCEC default `Ctrl+Alt+Shift+S` if a drive goes wrong.
 
 ---
 
 ## Expected clips
 
-| File | Content | Length (raw) | Notes |
-|------|---------|--------------|--------|
-| `01-gh-silico-getting-started.mp4` | github.com/tig/silico → scroll Getting Started → hold on agent prompt | 20–40 s | Highlight prompt (browser find, cursor, or zoom). |
-| `02-terminal-clone-and-prompt.mp4` | `git clone` xuss → `cd` → start `grok` (or your agent) → paste start prompt | 30–90 s | Readable typing or paste; no password leaks. |
-| `03-agent-session.mp4` | Full agent session from welcome through host gate + metal path | often 20–90+ min | One long take is fine; timeline splits + speeds handle pacing. |
-| `04-desk-xuss-boot-demo.mp4` | Board on desk: boot sound, product face, short function demo | 15–45 s | Keep **audio**. Good light; board fills frame. |
-| `05-xuss-ci-green.mp4` | tig/xuss Actions (or checks on main) green | 5–15 s | Hold on green check. |
+| File | Content | Source | Notes |
+|------|---------|--------|--------|
+| `01-gh-silico-getting-started.gif` | silico README → Getting Started → agent prompt | MCEC | Highlight prompt |
+| `02-terminal-clone-and-prompt.gif` | clone xuss → cd → start agent → paste prompt | MCEC | Readable pacing |
+| `03a-welcome.gif` | Stage 0a welcome skeleton | MCEC | Short; slow in timeline |
+| `03b-agent-work.gif` (+ `03c…`) | First-ship body / gates | MCEC | Multiple ≤60 s takes |
+| `04-desk-xuss-boot-demo.mp4` | Board boot + product face demo | Camera | **Keep audio** |
+| `05-xuss-ci-green.gif` | tig/xuss CI green | MCEC | Hold on green |
+
+Opening still: `docs/hero.jpg`. End card: generated.
 
-Opening still uses repo `docs/hero.jpg` (no capture). End card is generated by `build.py`.
+Optional: same basenames with `.mp4` after `ffmpeg -i clip.gif … clip.mp4`.
 
 ---
 
-## Mark human gates in the session tape
+## Mark human gates
 
-While recording `03-agent-session.mp4`, drop a **marker** (OBS chapter, spoken “gate”, or notepad timestamps) at:
+When recording agent UI takes, start a **new MCEC `record`** (or mark wall-clock) at:
 
-| Marker | Why slow in edit |
-|--------|------------------|
-| Start gate (yes / adjust) | First human go |
-| Plug USB / wait-device | Physical act |
-| Confirm board | Identity |
-| Confirm deploy | Scary write |
-| Product-face observe | “Do you see/hear …?” |
+| Marker | Timeline speed |
+|--------|----------------|
+| Start gate (yes / adjust) | ~1× |
+| Plug USB / wait-device (if on-screen prompt) | ~1× |
+| Confirm board | ~1× |
+| Confirm deploy | ~1× |
+| Product-face observe | ~1× |
 
-In `timeline.toml`, cut those windows as separate `[[segments]]` with `speed = 1.0` (or `0.75`) and time-lapse the agent-only stretches with `speed = 20`–`60`.
+Agent-only stretches: separate takes with high `speed` in `timeline.toml` (20–60×).
 
 ---
 
-## Session time log (fill while recording)
+## Session time log (fill while capturing)
 
 ```text
 session_t0 (paste prompt or agent start): ____:____:____ local
@@ -60,7 +74,7 @@ deploy done / face observed: +____ s
 CI green on remote: +____ s
 ```
 
-Copy those offsets into each segment’s `session_start_sec` / `session_end_sec`.
+Copy offsets into each segment’s `session_start_sec` / `session_end_sec`.
 
 ---
 
@@ -69,8 +83,8 @@ Copy those offsets into each segment’s `session_start_sec` / `session_end_sec`
 ```text
 cd docs/hero-video
 python build.py --check-footage
-python build.py                 # full assemble
-python build.py --placeholders  # smoke pipeline without real clips
+python build.py
+python build.py --placeholders   # smoke without real clips
 ```
 
 Review `out/hero.mp4`. Adjust speeds and trims; re-run. Publish per [README.md](README.md).
diff --git a/docs/hero-video/timeline.toml b/docs/hero-video/timeline.toml
index 2236c40..af08712 100644
--- a/docs/hero-video/timeline.toml
+++ b/docs/hero-video/timeline.toml
@@ -1,6 +1,7 @@
 # Machine plan for the silico × xuss README hero video.
-# Human storyboard: SCRIPT.md · capture: record.md · assemble: build.py
+# Human storyboard: SCRIPT.md · onscreen drive/record: mcec.md · checklist: record.md · assemble: build.py
 #
+# Onscreen sources are MCEC `record` GIFs (ffmpeg reads .gif). Desk is camera .mp4.
 # session_*_sec = real first-ship elapsed time shown on the on-screen clock
 # (not the length of the edited video). speed > 1 = time-lapse; speed < 1 = slow-mo.
 
@@ -51,68 +52,62 @@ title_overlay = true
 [[segments]]
 id = "gh-scroll"
 kind = "clip"
-source = "footage/01-gh-silico-getting-started.mp4"
+source = "footage/01-gh-silico-getting-started.gif"
 # in_sec / out_sec optional (seconds into source). Omit out_sec = to end.
+# .mp4 also fine if you convert the MCEC GIF first.
 speed = 1.0
 session_start_sec = 0
 session_end_sec = 45
 show_clock = true
 keep_audio = false
-note = "Scroll silico README to Getting Started; highlight agent prompt."
+note = "MCEC: scroll silico README to Getting Started; highlight agent prompt."
 
 [[segments]]
 id = "terminal-start"
 kind = "clip"
-source = "footage/02-terminal-clone-and-prompt.mp4"
+source = "footage/02-terminal-clone-and-prompt.gif"
 speed = 1.0
 session_start_sec = 45
 session_end_sec = 120
 show_clock = true
 keep_audio = false
-note = "git clone xuss, cd, start grok, paste prompt."
+note = "MCEC: git clone xuss, cd, start grok, paste prompt."
 
 # Welcome: slow for readability (~2–3 s of readable screen time).
-# After capture, set in_sec/out_sec to the welcome window in 03-agent-session.mp4.
 [[segments]]
 id = "welcome-slow"
 kind = "clip"
-source = "footage/03-agent-session.mp4"
-in_sec = 0.0
-out_sec = 8.0
+source = "footage/03a-welcome.gif"
 speed = 0.35
 session_start_sec = 120
 session_end_sec = 150
 show_clock = true
 keep_audio = false
-note = "Stage 0a welcome skeleton; slow so it is readable."
+note = "MCEC: Stage 0a welcome skeleton; slow so it is readable."
 
-# Agent work time-lapse — split further after first capture using gate markers.
+# Agent work time-lapse — add more 03b/03c segments after capture (MCEC ≤60s takes).
 [[segments]]
 id = "agent-timelapse"
 kind = "clip"
-source = "footage/03-agent-session.mp4"
-in_sec = 8.0
-# Leave out_sec unset until you know the tape end before metal demo cutaway.
+source = "footage/03b-agent-work.gif"
 speed = 30.0
 session_start_sec = 150
 session_end_sec = 2400
 show_clock = true
 keep_audio = false
-note = "Time-lapse first ship; re-split into gate-slow segments after markers."
+note = "MCEC: time-lapse first-ship body; split further after markers."
 
-# Example human-gate insert (enable by setting real in/out after capture):
+# Example human-gate insert (enable after capture):
 # [[segments]]
 # id = "gate-deploy"
 # kind = "clip"
-# source = "footage/03-agent-session.mp4"
-# in_sec = 1200
-# out_sec = 1230
+# source = "footage/03c-human-gates.gif"
 # speed = 1.0
 # session_start_sec = 2100
 # session_end_sec = 2130
 # show_clock = true
 # keep_audio = false
-# note = "confirm-deploy operator gate at 1×"
+# note = "MCEC: confirm-deploy operator gate at 1×"
 
 [[segments]]
 id = "desk-metal"
@@ -128,13 +123,13 @@ note = "Desk: boot sound, product face, short demo."
 [[segments]]
 id = "ci-green"
 kind = "clip"
-source = "footage/05-xuss-ci-green.mp4"
+source = "footage/05-xuss-ci-green.gif"
 speed = 1.0
 session_start_sec = 2520
 session_end_sec = 2580
 show_clock = true
 keep_audio = false
-note = "tig/xuss CI green on main."
+note = "MCEC: tig/xuss CI green on main."
 
 [[segments]]
 id = "credits"
diff --git a/tests/test_hero_video_build.py b/tests/test_hero_video_build.py
index e73a7d5..d3c54aa 100644
--- a/tests/test_hero_video_build.py
+++ b/tests/test_hero_video_build.py
@@ -38,6 +38,13 @@ def test_timeline_loads_and_has_script_beats(hv):
     assert ids[-1] == "credits"
     assert tl.brand.credit_url.startswith("https://github.com/tig/silico")
     assert tl.clock.enabled
+    # Onscreen path is MCEC GIF (desk remains camera mp4).
+    by_id = {s.id: s for s in tl.segments}
+    assert by_id["gh-scroll"].source.endswith(".gif")
+    assert by_id["terminal-start"].source.endswith(".gif")
+    assert by_id["welcome-slow"].source.endswith(".gif")
+    assert by_id["ci-green"].source.endswith(".gif")
+    assert by_id["desk-metal"].source.endswith(".mp4")
 
 
 def test_clock_drawtext_maps_session_range(hv):
@@ -74,6 +81,15 @@ def test_plan_does_not_require_footage(hv, capsys):
     assert "session clock end" in out
 
 
+def test_mcec_playbook_exists():
+    mcec = REPO / "docs" / "hero-video" / "mcec.md"
+    text = mcec.read_text(encoding="utf-8")
+    assert "tig/mcec" in text
+    assert "record" in text
+    assert "Generate-HeroGif.ps1" in text
+    assert "AgentRecordMaxDurationMs" in text or "60 s" in text
+
+
 @pytest.mark.skipif(shutil.which("ffmpeg") is None, reason="ffmpeg not on PATH")
 def test_placeholder_build_smoke(hv, tmp_path):
     """Encode a tiny placeholder cut into tmp (validates ffmpeg filter graph)."""