feat(demo-video): add optional Atlas Cloud B-roll workflow

engineering/demo-video/skills/demo-video/SKILL.md

@@ -26,12 +26,14 @@ Before starting, verify available tools:
 - **playwright MCP available?** — needed for automated screenshots. Fallback: ask user to screenshot the HTML files manually.
 - **edge-tts available?** — needed for narration audio. Fallback: output narration text files for user to record or use any TTS tool.
 - **ffmpeg available?** — needed for compositing. Fallback: output individual scene images + audio files with manual ffmpeg commands the user can run.
+- **Atlas Cloud configured?** — optional for generating conceptual B-roll when no real product visual exists. Never replace inspectable product screenshots with generated imagery.
 
 If none are available, produce HTML scene files + `scenes.json` manifest + narration scripts. The user can composite manually or use any video editor.
 
 | Mode | How | When |
 |------|-----|------|
 | **MCP Orchestration** | HTML → playwright screenshots → edge-tts audio → ffmpeg composite | Use when playwright + edge-tts + ffmpeg MCPs are all connected |
+| **AI-assisted B-roll** | Product screenshots + optional Atlas Cloud scene images → ffmpeg composite | Use only for abstract transitions or concepts that cannot be captured from the real product |
 | **Manual** | Write HTML scene files, provide ffmpeg commands for user to run | Use when MCPs are not available |
 
 ### 2. Pick a story structure
@@ -52,6 +54,12 @@ Hook (2s) -> Demo (8s) -> Logo (3s) -> Tagline (2s)
 - For conceptual demos: use text-heavy scenes with the color language and typography system
 - Ask the user for screenshots only if the product is visual and descriptions are insufficient
 
+When a conceptual scene genuinely benefits from generated imagery and Atlas Cloud is configured,
+follow the [Atlas Cloud scene generation](references/scene-design-system.md#atlas-cloud-scene-generation)
+reference.
+Atlas is an opt-in source: keep the screenshot/HTML workflow as the default, submit each scene
+once, and fall back to HTML rather than retrying a failed paid generation.
+
 Every scene has exactly ONE primary focus:
 - Title scenes: product name
 - Problem scenes: the pain (red, chaotic)
@@ -77,6 +85,8 @@ For each video, produce these files in a `demo-output/` directory:
    - `playwright screenshot` each HTML scene → `frames/`
    - `edge-tts` each narration file → `audio/`
    - `ffmpeg` concat with crossfade transitions → `output.mp4`
+5. `generated-assets.json` — only when AI B-roll is used; record prompt, model, prediction ID,
+   output path, and scene number so generated media remains auditable
 
 If MCPs are unavailable, still produce items 1-3. Include the ffmpeg commands in `build.sh` for the user to run manually.
 
@@ -102,6 +112,7 @@ See [references/scene-design-system.md](references/scene-design-system.md) for t
 | **Generic narration** — "This feature lets you..." | Use specific numbers and concrete verbs |
 | **No story arc** — just listing features | Use problem -> solution -> proof structure |
 | **Raw screenshots** | Always add rounded corners, shadows, dark background |
+| **Generated fake product UI** | Use real screenshots for product states; reserve AI imagery for conceptual B-roll |
 | **Using `ease` or `linear` animations** | Use spring curve: `cubic-bezier(0.16, 1, 0.3, 1)` |
 
 ## Cross-References

engineering/demo-video/skills/demo-video/references/scene-design-system.md

@@ -59,3 +59,67 @@ Background: dark with subtle purple-blue glow gradients. Screenshots: always `bo
 | 3-4s | 8-12 | ~70% |
 | 5-6s | 15-22 | ~75% |
 | 7-8s | 22-30 | ~80% |
+
+## Atlas Cloud Scene Generation
+
+Use this optional path only for conceptual B-roll that cannot be captured from the real
+product. Product UI, results, dashboards, and workflows must use real screenshots.
+
+### Preconditions
+
+1. Confirm `ATLASCLOUD_API_KEY` is set without printing it.
+2. Read the live model catalog at `https://api.atlascloud.ai/api/v1/models`.
+3. Confirm the selected model is an enabled text-to-image model and read its live schema.
+4. Keep the demo-video screenshot and HTML pipeline as the default.
+
+`google/nano-banana-2-lite/text-to-image-developer` is a suitable low-latency example
+when it is present in the live catalog. Its current text-to-image schema accepts a prompt
+and supports a `16:9` aspect ratio.
+
+### Submit Once
+
+Create one request per approved conceptual scene:
+
+```bash
+curl --fail-with-body https://api.atlascloud.ai/api/v1/model/generateImage \
+  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: demo-video-skill/1.0" \
+  -d '{
+    "model": "google/nano-banana-2-lite/text-to-image-developer",
+    "prompt": "<describe one conceptual scene; do not invent product UI>",
+    "aspect_ratio": "16:9",
+    "resolution": "1k"
+  }'
+```
+
+Do not automatically retry this POST. Save the returned prediction ID immediately. If the
+request fails, use the HTML scene fallback instead of spending on another generation.
+
+### Poll and Save
+
+Poll only the returned prediction with bounded backoff:
+
+```bash
+curl --fail-with-body \
+  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
+  -H "User-Agent: demo-video-skill/1.0" \
+  "https://api.atlascloud.ai/api/v1/model/prediction/<prediction-id>"
+```
+
+Stop on `completed` or `failed`, and stop after the agreed timeout. Download the first
+completed output into `demo-output/scenes/` and inspect it before compositing. Reject any
+asset that resembles fabricated product UI, contains broken text, or conflicts with the
+real product branding.
+
+Record each generated asset in `demo-output/generated-assets.json`:
+
+```json
+{
+  "scene": 3,
+  "model": "google/nano-banana-2-lite/text-to-image-developer",
+  "prediction_id": "<prediction-id>",
+  "prompt": "<exact prompt>",
+  "output": "scenes/scene-03-broll.png"
+}
+```