product-demo
Product demo
A demo is a flow with a script. The script lives in the repo next to the Product Map. CI replays it against the app in demo mode, keeps keyframes and an event log as the source, renders a video from them in a style on a background, and uploads everything to a store the docs site reads. When code a demo depends on changes, the demo is regenerated, and only then. Nothing generated is committed.
/product/demos/<id>.yaml ──▶ record ──▶ keyframes + events + manifest ──▶ render ──▶ video ──▶ store ──▶ index.json
Playwright frame by frame production/ or pr-<n>/ docs site
▲
style: neutral | device | perspective · background: a wallpaper · cards, captions, zoom per step
Why it is built this way, and what the app must do to be recordable: references/how-it-works.md. Read it before installing and whenever you explain the pipeline. The file contract: references/format.md. Styles, backgrounds and settings: references/styles.md. Commands: references/cli.md. The workflow and the store: references/ci.md.
What it needs. A web app that runs locally from the repo with a command; Node for the package; a way to seed a known state; a test account when the app has a login. A Product Map (product-map skill) is recommended, since demos point at flows and borrow their labels and implementation references, but a demo can be written without one. Narration works with no key through the local provider. Publishing needs an S3-compatible bucket (Cloudflare R2 recommended) and its credentials in CI; without one, videos stay local.
Principles. The source of a video is keyframes plus an event log, never a screen recording. The app is made repeatable through a demo mode, not through retries. Videos are derived, never edited. A demo is regenerated when the code it depends on changed, decided from file hashes, never from pixels. CI records and publishes; local runs are for looking.