# Script (`*.script.md`) → storyboard → timeline

A script is a plain **Markdown** file (`*.script.md`) — so it opens in the app's document view and is edited,
like every file, through the bottom composer. It's the top of the pipeline:

```
script (.script.md)  →  storyboard (.storyboard.json)  →  timeline (.mvideo.json)  →  render (.mp4)
```

## Script format (a light convention)

Use headings for scenes and a simple beat list per shot. Keep it human-readable — it's a document, not a
schema.

```markdown
# Café Aurora — 15s spot

## Scene 1 — Morning open
- **Shot 1** (wide, 3s): Café storefront at dawn, warm light. — *VO: "Every morning starts here."*
- **Shot 2** (macro, 4s): Espresso pours into a cup. Cast: Ana.

## Scene 2 — The pour
- **Shot 3** (close-up, 4s): Latte art rosetta finishes. Cast: Ana, the-van.
- **Shot 4** (logo, 4s): Logo on a clean background. — *VO: "Café Aurora."*
```

Per shot, note what's useful for generation: camera/shot type, rough duration, action, any VO/dialogue, and
which **library entities** (cast/props/locations) are in frame.

## Turning a script into a storyboard

Read the script, then build the shot list with the storyboard tools:
1. `storyboard_new { path: "spot.storyboard.json" }`.
2. For each shot, `storyboard_edit` → `add_shot { shot: { scene, description, prompt, camera, durationFrames,
   dialogue, entities, model } }`. Write a strong image prompt from the shot's action + the entities'
   `promptFragment`s (see [library.md](library.md)).
3. Generate each shot's **still** with `image_generate` (using the entities' views + seed), then
   `update_shot { id, patch: { still: "files/…" } }` so the storyboard shows keyframes.

## Storyboard → timeline

`storyboard_compile { path: "spot.storyboard.json" }` writes an `*.mvideo.json`: one clip per shot (the
still as a placeholder), dialogue as text overlays, entities carried onto each clip. Then, per shot:
- generate the video (`video_generate` with the shot's prompt/model + the still as `imagePaths`),
- swap it in with `timeline_edit` (add_asset + update_clip → new asset),
- add music/SFX/voiceover, then `render`.

Keep the script and storyboard in sync as the source of truth for *intent*; the timeline is the assembly.