docs: reproducible README hero video pipeline

.gitignore

@@ -13,3 +13,16 @@ 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/**/*.gif
+docs/hero-video/**/*.vf.txt
+docs/hero-video/**/*.pre.mp4

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) |

docs/hero-video/README.md

@@ -0,0 +1,94 @@
+# 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) |
+| [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/` | MCEC GIFs + desk MP4 (gitignored binaries) |
+| `out/` | Rendered `hero.mp4` (gitignored) |
+
+## Prerequisites
+
+- **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 Segoe UI, etc.).
+
+## Quick start
+
+```text
+# 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
+```
+
+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.
+
+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. 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.
+
+## 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.
+- 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.

docs/hero-video/SCRIPT.md

@@ -0,0 +1,116 @@
+# 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:** 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).
+
+---
+
+## 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
+
+- **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:
+
+  ```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
+
+- **MCEC** drives a clean terminal (large font) and records.
+- 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
+
+- **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
+
+- **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` 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
+
+- **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
+
+- 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).