The canonical guide to authoring demos: storyboard schema, action vocabulary, demo-director principles, ChatGPT-app recording facts. Call this FIRST before authoring or editing a storyboard. Pass topic (core | schema | polish | attention | chatgpt-apps | stills | variants | captions | debug | ci, or any H2 heading prefix) for one slice instead of the whole ~1000-line guide; start with core, then fetch attention/polish/chatgpt-apps as needed.

JSON Schema for storyboard.json, generated from the engine's own zod schema — the exact contract the engine validates against.

Validate a storyboard against the engine schema without running anything. Pass exactly one of: dir (uses generated/storyboard.json), path (a storyboard file), or json (storyboard JSON as a string). relaxed makes narration optional (probe semantics).

Browser-free preflight over a storyboard: a per-scene pacing forecast (which scenes compose will mostly freeze-hold or cut because the narration and the recorded action don't match), selector/wait pitfalls (type+Enter with no wait, :text-is on nested labels, focus without a zoom block, anchored waitForChange regexes), and no-op keys. Run it after every storyboard edit, before probe/render. Pass exactly one of dir / path / json. lang lints a narrations[lang] translation at that language's speaking rate.

Create demos// with a starter brief + storyboard. dir is the repo to scaffold into (absolute path recommended; default: server cwd). With fromUrl the page is inspected first (no LLM): its headings become scenes and its unique selectors become the beats + a _candidates list — you then write the narration and turn the candidate hover into the real click.

Check prereqs: node, ffmpeg, Chrome (or the AIDEMO_CHROME_CHANNEL / AIDEMO_CHROME_EXECUTABLE browser in use), TTS/STT endpoint (flags LLM-only servers like Ollama), API key, playwright, installed skill.

Ready-to-paste embed snippets (markdown GIF, markdown still, HTML ) for a demo, using stable raw.githubusercontent URLs on the 'demo-media' branch. Pure string generation — no network, no render. Owner/repo come from the repo's origin remote; the demo name from the directory basename. Pair with the demo-publish workflow so CI keeps the URLs fresh. See docs/EMBEDS.md.

File a bug, surprise, or workaround you hit this session as a GitHub issue on the aidemo engine repo (github.com/tandryukha/aidemo) — the in-band equivalent of aidemo feedback on the CLI. Environment (engine version, OS, node, ffmpeg) and a recent-log tail from dir are auto-attached, same as the CLI. Uses gh issue create when available; falls back to a local docs/feedback-*.md plus a prefilled github.com New Issue URL when gh is missing or offline — no other network call. Call this whenever something felt broken, surprising, or needed a workaround; skip it if the session was clean. Set dryRun to preview the assembled title/body without filing anything.

Status, stage, per-scene progress (scenesTotal/scenesDone/currentScene — populated for probe/record/render/voice/captions/compose), log tail, and final result or error (with failure-artifact paths and, on a genuine failure, a feedbackHint pointing at the feedback tool) of a pipeline job.

All jobs this server session, newest last.

Best-effort cancel (checked between actions/scenes/stages). A mid-record cancel salvages the partial timeline + footage. The job settles asynchronously — poll job_status for the final state.

Record-only dry run to verify selectors/timing (narration optional). With updateGolden, writes golden/probe.json (the regression baseline); with golden, deep-compares against it and returns match + field-level diffs. Returns a jobId immediately — poll job_status. Rejects if another job is running.

Turn a Playwright trace.zip (context.tracing / --trace on) or a *.spec.ts test file into demos// with a draft storyboard: the run's own actions and selectors become scenes (cut at navigations and async payoffs), narration is left as placeholders, and _notes lists what was approximated. No LLM, no browser. Then write the narration and probe.

Drive the storyboard in Chrome and record raw video + timeline.json. Returns a jobId immediately — poll job_status. Rejects if another job is running.

Full pipeline: voice → record → captions → compose (the CLI render). Returns a jobId immediately — poll job_status. Rejects if another job is running.

Generate per-scene TTS narration (skips unchanged scenes). Returns a jobId immediately — poll job_status. Rejects if another job is running.

Transcribe narration.mp3 to captions with word timing. Returns a jobId immediately — poll job_status. Rejects if another job is running.

Trim, sync, mux and caption into output/final-demo.mp4. Returns a jobId immediately — poll job_status. Rejects if another job is running.

Post-render checks on the FINISHED MP4 — blank opening, blank poster, master loudness, music-bed level, per-scene hold shares + compose warnings, caption readability, frame/chapter hygiene. Run it after compose/render: it sees what a viewer sees, which neither lint (pre-take) nor report.json (structural) can. Returns a jobId immediately — poll job_status. Rejects if another job is running.

Convert output/final-demo.mp4 to a README-ready GIF. Returns a jobId immediately — poll job_status. Rejects if another job is running.

Extract named stills (screenshot mode) from the recorded take into output/stills/ — one PNG per still marker, pulled from the CLEAN take (no captions/zoom). Needs only a recorded timeline (no key). Returns a jobId immediately — poll job_status. Rejects if another job is running.

Dump evenly spaced PNG frames from the final video (or the raw take) into output/frames/ for review — look at them instead of hand-running ffmpeg -ss. Needs only the video (no key). Returns a jobId immediately — poll job_status. Rejects if another job is running.

Export output/walkthrough/ from the final video: index.html (one card per scene — payoff frame, title, narration, jump-to-time; ← → keyboard nav), guide.md (README/SOP-ready), per-scene PNGs, SRT/VTT and a JSON manifest. Needs only the rendered video + report.json (no key, no browser). Returns a jobId immediately — poll job_status. Rejects if another job is running.

Open a URL in the recording profile (logged-in state included) and list every visible interactive element with UNIQUE selectors ranked data-testid → id → aria-label → role/text → name/placeholder → class → path, plus headings and iframes. Use it BEFORE writing targets — no selector guessing, no wasted probe. Writes logs/inspect-.json and a screenshot in the demo dir. Returns a jobId immediately — poll job_status. Rejects if another job is running.