demo-video-skill: Instructions file for Codex

AGENTS.md — Demo-Video capability

This file makes any AGENTS.md-aware coding agent (OpenAI Codex, Gemini CLI, Jules, Aider, Amp, and others) capable of producing a demo video of a local web app. It mirrors the Claude Code skill in SKILL.md. The canonical detail lives in references/playbook.md.

When to use this

When the user asks for any of: a demo video, feature walkthrough, product demo, screen recording of a localhost app, promo clip, or "show this feature working as a video" — even if they don't literally say "video" (e.g. "make something that shows this feature running"), use this capability. This is for real screen-operation demos, not motion-graphic teasers.

What it does

Drives and records the real running web app headlessly with Playwright — as if a human were operating it — and bakes in a bottom subtitle bar, a feature label, a smooth fake cursor, and zoom, all in code. LLM/loading dead-air is speed-compressed with ffmpeg. Output is a finished 1920×1080 mp4. No screen recorder (Cap, OBS, etc.) is used.

Three core ideas:

1. Overlay is injected on document.documentElement (html), not body. Zoom transforms body, so an overlay under html is immune to the zoom.
2. A fake cursor (SVG + CSS transition) stages the mouse — the real one is invisible in headless mode; the transition provides cursor smoothing.
3. LLM/loading waits are detected with waitForFunction, never a fixed sleep; the elapsed waitMs is recorded and only that window is sped up 6–9x by ffmpeg.

Workflow (order is fixed)

1. Script first, shoot after approval. Build a per-scene table — [URL/enter | action | input | zoom point | speed-up window | subtitle (one value sentence) | bottom-left label] — and get the user's approval. For file-upload scenes, request a real local file path now (a chat-attached image cannot be fed to setInputFiles).
2. Environment check. Confirm the target server is alive with curl -s -m 5 -o /dev/null -w "%{http_code}" <URL> — never kill a server the user started. In a scratch dir run npm i playwright-core and confirm ffmpeg is installed.
3. One PoC scene → approval → roll out. Build only the most representative scene first, get the tone (subtitle style, cursor speed, zoom ratio) approved, then do the rest.
4. Scene capture. Copy scripts/cap_scene.template.js per scene, replacing only the SEQUENCE block. For 3+ scenes, consolidate into one gen.js taking a scene-number arg. Each run prints { waitMs, webm } JSON.
5. Post-process + QA per scene. Use scripts/postprocess.sh: speed up the wait window → mp4 → 3x3 montage eyeball check (do not skip) → confirm length (25–45s).
6. Montage. concat the scene mp4s (-c copy), spot-check frames, then confirm with the user's real playback. That playback is the completion condition.