/demo-video

name: demo-video
description: >-
  Record a crisp, high-resolution product demo video by driving the real app with a browser agent - from storyboard approval to staged app, smoke take, Xvfb framebuffer recording, MP4-derived timestamps, and a narration script synced to the frames. Use whenever the user wants a demo video, a product walkthrough recording, a screen capture for a hackathon, launch or submission, or complains that a recording came out pixelated, blurry, blocky or soft, showed title cards instead of the product, jumped straight to the final feature, had narration landing on the wrong frame, or looks static or like a slideshow. Also owns sound and structure: Kokoro voicing, a music bed ducked under speech, chapter cards and spoken transitions, the closing recap with the ask last, and the logo and rights band. Also the home of the recording harness that pitch-deck reuses for slide walkthroughs. Not for - live pitching or deck building (pitch-deck, pitch-package), one-off screenshots, or editing footage that already exists.

Demo Video - film the real product, crisply

A demo is an argument: every beat on camera proves a claim, and the narration is written **to the frame** - describing what is actually on screen at that second.

> **Boundary - this recording has no substitute.** The `video-shotcraft` motion library captures STILL screenshots and glides a fake camera over them; it CANNOT record interaction. Never let it stand in for a tutorial, walkthrough, or any real-product film. It decorates RENDERED scenes in `motion-video`; the live recording, the DOM motion, and the timestamp-synced script stay here, always. (Standing owner rule, 2026-07-23; see `motion-video/references/shotcraft-bridge.md`.)

The recording contract

This fires **automatically** on every demo film, whether or not the user asks for it. These are the rules an agent under time pressure skips first, which is exactly why they are not optional. Rules 1-4: `references/storyboard.md`. Rules 5-6: `references/recording.md`.

1. **Film the product, not a poster - annotate, never substitute.** Every frame is real browser state from the running app, changing because the driver acted on it.

Annotation drawn *over* live state is **standard practice**: callouts, the drawn cursor, spotlight, the terminal panel. A film that explains itself on mute is doing its job. The test is whether the overlay is load-bearing: **remove it, and does the frame still show the product doing the thing?** If yes it is annotation, use it freely. If no it is a poster - a title card, slide interstitial, mocked screen, static hero image - and it stays banned.

If a beat can't be staged, cut the beat or fix the app. Never substitute a picture of the claim for the claim. (Slides are legitimate in `pitch-deck`'s deck take, stitched *around* the demo film, never inside it.) Motion and annotation: `references/motion.md`. A motion opening, chapter cards and a closing recap are the owner's call and sit *between* beats, never in place of one: `references/structure.md`.

2. **Show the whole journey, not just the money shot.** The film covers entry -> setup -> the core loop -> the payoff. A viewer who has never seen the product must be able to follow how a real user gets from opening it to the result. Opening on the final feature reads as a mockup and answers none of "what is this, who uses it, how do you get there".

3. **Every claim gets a frame.** The storyboard runs both directions: each beat names what it proves, *and* each claim the narration will make names the beat that shows it. This binds hardest on agent actions - "the agent searched", "it updated memory", "it chose the cheaper route" all need visible on-screen evidence (the tool log, the memory panel, the route badge). A claim with no frame is cut from the narration or earns a beat that shows it. Invisible work is not proof.

4. **Storyboard approved before capture** - Gate 1 below. Blocking.

5. **Smoke take inspected before the full capture** - Gate 2 below. Blocking: any failed check means fix the staging and re-smoke, never start the full capture on a known-bad frame.

6. **Timestamps derived from the delivered MP4** - Gate 3 below. Never from planned waits, never from the storyboard's estimated holds.

Steps

0. Preflight

Check the machine can do this before promising it: `ffmpeg` and `Xvfb` installed (`apt-get install -y xvfb` on Linux; this recipe is Linux-first - on macOS capture the retina display with `ffmpeg -f avfoundation` or the built-in screen recorder, same principles: physical pixels, controlled bitrate). Confirm the app runs with demo data and demo credentials, and that credentials stay OUT of the repo (scratchpad only).

0.5 Purpose and guardrails - **GATE with the storyboard**

Before the storyboard, ask what the film is for and what must be burned into it: the audience; any third-party logo or name in the frame (white-labelled tenants count); generic or personalised disclaimer card; a persistent "Demo purposes only" label; the rights line and company mark; and how it will be distributed (private streaming link, our website's unlisted showcase, direct file, public platform). The guardrails are optional and the user chooses them; the questions are not optional. A client logo in the frame with no card and no private distribution is the one outcome that is never acceptable. Questions, rules and approved wording: `references/distribution.md`. Record the answers in the brief next to the storyboard.

1. Storyboard - **GATE 1: approval before any capture**

Write the visual storyboard before recording anything. One row per beat:

`phase | screen | action | proof | narration | duration`

Read `references/storyboard.md` for the format, the journey-coverage checklist, and the claim-to-frame audit. Then **show it to the user and stop.** Do not stage, do not smoke-test, do not record until they approve or amend it.

A blanket "just make it, I trust you