videowright 0.1.0

package/skill/references/create_or_edit_video.md

@@ -0,0 +1,232 @@
+# Create or Edit Video
+
+## When this is loaded
+
+You were dispatched here from one of:
+
+- **[new_video.md](new_video.md)** — create mode. The `videos/<name>/` folder is new and PLAN.md was just confirmed. Scaffold segments and timeline from the plan.
+- **SKILL.md intent dispatch** — edit mode. The video already exists. Read PLAN.md, make the requested change, and append to the log.
+
+This is a single file because the underlying mechanics — segments, timeline composition, styles, voiceover — are the same whether scaffolding fresh or modifying.
+
+## What you need to know
+
+These reference files cover the building blocks. Load them as needed — do not re-read this section's summaries when the full reference is available.
+
+- **[authoring_segment.md](authoring_segment.md)** — segment lifecycle (`mount`/`play`/`unmount`), `defineSegment`, timing with `ctx.waitForNext()` and `ctx.hold(ms)`, render-safe animation patterns (WAAPI, `ctx.clock()`, patterns and recommendations), idempotency, any-web-tech guidance.
+- **[audio.md](audio.md)** — audio workflow (voiceover, SFX, music), the `voiceover` field on segments, VO-first authoring pattern, `videowright script` CLI, file conventions, CLI usage (`--audio-track`).
+- **[styles.md](styles.md)** — style folder structure, how segments consume tokens via CSS variables, switching styles, the timeline.ts import convention.
+- **[project_structure.md](project_structure.md)** — consumer repo layout, file-ownership rules (top-level dirs are shared, per-video files live in `videos/<name>/`).
+- **[types.md](types.md)** — quick reference for `Segment`, `PlayerContext`, `Timeline`, `TimelineMeta`, `Config`.
+
+## Create mode
+
+Entry condition: `videos/<name>/` was just created by new_video.md, and PLAN.md is confirmed.
+
+### Step 1 — Read the plan
+
+Read `videos/<name>/PLAN.md`. Extract:
+
+- The segment outline (segment ids and their purposes).
+- The style slug (from the Style section).
+- The audio intent.
+- The script (if present).
+
+### Step 2 — Author segments
+
+For each segment in the outline:
+
+1. **Check if a segment with that id already exists** in `segments/<id>/index.ts`. If it does and is reusable for this video, use it. Do not duplicate.
+2. **Create `segments/<id>/index.ts`** using `defineSegment`. Follow the rules in [authoring_segment.md](authoring_segment.md):
+   - **Fill the frame.** Size text and visuals for a video canvas, not a web page. Body text 36px+ at 1080p, headings 64px+. Content containers should span 80-90%+ of the video width. See the "Visual sizing" section in [authoring_segment.md](authoring_segment.md).
+   - **`waitForNext()` for VO-aligned beats.** Place a `waitForNext()` at every content reveal that a voiceover should cue. Use `ctx.hold(ms)` only for animation lead-in or fixed internal pauses. This keeps segments decoupled from any single voiceover — swapping narration only requires new timing data, not segment rewrites.
+   - Prefer WAAPI (`.animate()` with `delay`) or CSS animations for smooth visual motion (smoother easing, less code). Timer-based patterns (`setTimeout`, `setInterval`, hold loops) also work deterministically under the render shim. See the render-safe animation patterns in [authoring_segment.md](authoring_segment.md).
+   - Set the `advances` array to match the timing — one entry per beat, including the final advance that transitions to the next segment (see [authoring_segment.md](authoring_segment.md) for details on how `advances` maps to `waitForNext` and `hold` calls).
+   - If audio intent is voiceover, set the `voiceover` field to the segment's VO text (from the script or drafted to match the segment's purpose). For music or silent videos, leave `voiceover` empty — use code comments to document what the segment shows.
+   - Use CSS variables from the active style: `var(--color-accent)`, `var(--font-display)`, etc. Do not import tokens.css in segments — the timeline-level import provides them.
+3. **Use any web tech.** Three.js, GSAP, Lottie, animated SVG, shadcn, echarts — all welcome inside segments. Pick the right tool for the visual.
+
+### Step 2b — Review each segment (render-safety and design CR)
+
+After writing each segment, perform a focused code review before moving on. This catches style issues, visual sizing problems, timing anti-patterns, and ensures idiomatic use of render-safe patterns.
+
+**Checklist -- review the segment code for:**
+
+1. **Visual sizing — content fills the frame.** Text, cards, stats, and key visuals should be large and legible. Body text should be at least 36px at 1080p; headings 64px+. No `max-width: 800px` web-page centering. Primary containers should span 80-90%+ of the video width. If the segment would look like a small island surrounded by empty space, increase sizes. See the "Visual sizing" section in [authoring_segment.md](authoring_segment.md).
+2. **`waitForNext()` used for VO-aligned beats.** Every content reveal that a voiceover might want to cue differently should be gated by `waitForNext()`, not `hold()`. `hold()` is for animation lead-in or fixed internal pauses. If a different voiceover would want to trigger a reveal at a different time, it must be `waitForNext()`. See the timing guidance in [authoring_segment.md](authoring_segment.md).
+3. **Prefer WAAPI for DOM animation** (smoother easing, less code). Timer-based patterns (`setTimeout`, `setInterval`, rAF loops, `performance.now`) all work deterministically under the render shim but WAAPI provides smoother sub-frame interpolation.
+4. **`ctx.hold` loops are fine for stepped/discrete changes** (e.g., typing out characters). For eased motion, prefer WAAPI with per-element `delay`.
+5. **`ctx.clock()` used** for any code that needs the current render time (Three.js rotation, Lottie frame drive, shader uniforms, etc.).
+6. **WAAPI / CSS animations used** for DOM animations. Staggered entrances prefer WAAPI `delay` parameter over `ctx.hold()` between `.animate()` calls (less code, smoother easing).
+7. **Lottie uses manual frame drive** -- `autoplay: false` with `anim.goToAndStop(ctx.clock(), false)` per tick.
+8. **Three.js reads `ctx.clock()`** for time-derived values (preferred for clarity; `performance.now()` also works under the shim).
+9. **Imports, types, and segment shape** match project conventions (see [authoring_segment.md](authoring_segment.md)).
+
+**If any issue is found:** fix the segment code, then re-check the full checklist before continuing. A segment is ready only after a clean pass.
+
+See the "Render-safe animation patterns" section in [authoring_segment.md](authoring_segment.md) for the full list of patterns and recommendations with examples.
+
+### Step 3 — Write timeline.ts
+
+Create `videos/<name>/timeline.ts`:
+
+```ts
+import '../../styles/<slug>/tokens.css';
+import type { Timeline } from 'videowright';
+
+const timeline: Timeline = {
+  meta: {
+    title: '<video title from PLAN.md>',
+    // style: '<slug>',  // include only if overriding defaultStyle
+  },
+  segments: [
+    { id: '<segment-1>' },
+    { id: '<segment-2>', transition: 'fade' },
+    // ...
+  ],
+};
+export default timeline;
+```
+
+Key rules:
+
+- **Top-of-file CSS import.** Always import the active style's `tokens.css` as the first line. The agent writes this import to match the chosen style — it is not copied from a template. The import path is relative to `timeline.ts`. Adjust `../../` depth to match directory structure.
+- **Keep the import in sync.** The CSS import must match `meta.style ?? config.defaultStyle`. See [styles.md](styles.md) for details.
+- **Set `meta.style`** only when overriding the project `defaultStyle`. If using the default, omit the field.
+- **Transitions** are optional on each segment entry. Use built-in transitions (`fade`, `slideLeft`, `slideRight`) or custom ones from `transitions/`.
+
+### Step 4 — Write voiceover script file
+
+This step applies only when the video has a voiceover. For videos without voiceover, skip it entirely.
+
+The voiceover system has two parts that stay in sync:
+- **`voiceover` field** on each segment (in `segments/<id>/index.ts`) — the VO text for that segment. Set this in step 2 above.
+- **`voiceover_script/script.md` file** (in `videos/<name>/voiceover_script/script.md`) — the full script for the video, organized by segment id. Written here.
+
+Steps:
+
+1. Create `videos/<name>/voiceover_script/script.md` with the full script, organized by segment id (one `## segment-id` heading per segment).
+2. Verify each segment's `voiceover` field matches its section in the script. These must stay in sync — `videowright script` can regenerate one from the other.
+3. See [audio.md](audio.md) for the audio workflow and [audio/voiceover.md](audio/voiceover.md) for the VO-first authoring pattern and `videowright script` usage.
+
+### Step 5 — Shared resources
+
+When writing segments, decide what belongs in shared directories:
+
+- **`components/`** — reusable web components used across multiple segments (e.g., `<animated-title>`, `<feature-card>`). If a visual element appears in more than one segment, extract it.
+- **`transitions/`** — custom transition functions. Only create if a built-in transition does not fit.
+- **`segments/`** — all segments live here, shared across all videos. Any video can reference any segment. Name them descriptively.
+
+The reuse rule: do not copy a segment to modify it for a different video. If two videos need the same visual with slight differences, parameterize the segment or extract the shared parts into a component.
+
+### Step 6 — Update PLAN.md log
+
+Append a dated entry to the Log section of `videos/<name>/PLAN.md`:
+
+```markdown
+### YYYY-MM-DD — Initial scaffold
+- Created segments: <list of segment ids>
+- Timeline: <number> segments, style: <slug>
+- Voiceover: <drafted / user-provided / none>
+```
+
+### Step 7 — Verify
+
+Run `npx videowright dev` (or ask the user to run it) and confirm:
+
+- The video loads without errors.
+- All segments play in order.
+- Transitions work.
+- The style's CSS variables are applied (colors, fonts look correct).
+
+If something is broken, fix it before declaring done.
+
+### Step 8 — Post-build handoff
+
+After the video is verified, present the user with an explicit choice. Show this message verbatim:
+
+> Two options:
+> 1. **Edit the video content** — tell me what to change (segments, copy, animations, style).
+> 2. **Set up audio** — I'll walk you through voiceover, SFX, and music.
+
+If the user picks option 1, stay in this file and follow edit-mode instructions below for whatever they want to change.
+
+If the user picks option 2, immediately load [audio.md](audio.md) and follow its flow entry point. Do not add any intermediate questions — audio.md handles intake.
+
+If audio intent is **silent**, omit option 2 and instead just ask: "The video is ready. Want to make any changes?"
+
+## Edit mode
+
+Entry condition: `videos/<name>/` already exists with a PLAN.md and timeline.ts.
+
+### Step 1 — Read PLAN.md
+
+Always read `videos/<name>/PLAN.md` before making any changes. Understand the current state of the video — its segments, style, audio intent, and history.
+
+### Step 2 — Make the requested change
+
+Common edit operations:
+
+**Add a segment:**
+1. Create `segments/<id>/index.ts` following the rules above.
+2. Add the segment entry to `timeline.ts` in the correct position.
+3. Update the segment outline in PLAN.md.
+
+**Remove a segment:**
+1. Remove the segment entry from `timeline.ts`.
+2. Do **not** delete the segment file from `segments/` — other videos may use it. Only delete if you confirm no other timeline references it.
+3. Update the segment outline in PLAN.md.
+
+**Reorder segments:**
+1. Reorder the entries in `timeline.ts`.
+2. Update the segment outline in PLAN.md.
+
+**Restyle the video:**
+1. Update the top-of-file CSS import in `timeline.ts` to point to the new style.
+2. Update `meta.style` (if present) to match.
+3. Segments do not need to change — CSS variables resolve at runtime from the timeline's import. If the new style defines different tokens than what segments reference, verify the segments still look correct.
+4. See [styles.md](styles.md) for the full swap workflow.
+
+**Rewrite voiceover:**
+1. Edit the `voiceover` field on affected segments.
+2. Run `npx videowright script` to regenerate `voiceover_script/script.md` from the updated segment fields. See [audio/voiceover.md](audio/voiceover.md).
+
+**Edit a segment's content:**
+1. Modify `segments/<id>/index.ts` directly.
+2. If timing changes, update the `advances` array to match.
+3. If voiceover changes, update the `voiceover` field.
+
+**After any segment is created or modified**, run the render-safety CR checklist from Step 2b (create mode) against the changed segment. Fix any issues before continuing.
+
+### Step 3 — Respect existing segment ids
+
+Segment ids are the primary key. Renaming a segment id cascades through:
+- Every `timeline.ts` that references it.
+- The `voiceover_script/script.md` heading.
+- The PLAN.md segment outline.
+
+If you must rename, update all references. Prefer keeping existing ids unless the user explicitly asks for a rename.
+
+### Step 4 — Append to PLAN.md log
+
+After any meaningful change, append a dated entry:
+
+```markdown
+### YYYY-MM-DD — <what changed>
+- <description of the change and why>
+```
+
+### Step 5 — Verify
+
+Run `npx videowright dev` and confirm the video still plays end-to-end. Check that the edit did not break existing segments or transitions.
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| Segment id in PLAN.md conflicts with an existing segment | Surface the collision. Ask the user to rename or merge. |
+| Video references a segment that does not exist | Create it. Follow the create-mode segment authoring rules. |
+| Style slug in PLAN.md does not exist in `styles/` | Offer to create it via [setup_new_style.md](setup_new_style.md) or pick an existing style. |
+| User asks to edit a video that has no PLAN.md | Create a PLAN.md by reading the existing `timeline.ts` and segments. Back-fill the plan from what exists, then proceed with the edit. |
+| User asks to "add a segment" without specifying which video | Check how many videos exist. If one, use it. If multiple, ask which video. |
+| `npx videowright dev` fails | Read the error output. Common issues: missing segment file, TypeScript error in a segment, broken import path. Fix and re-run. |

package/skill/references/dev_server.md

@@ -0,0 +1,157 @@
+# Dev Server
+
+## When this is loaded
+
+You were routed here from the intent dispatch table because the user wants to run, preview, or interact with the dev server.
+
+## Starting the dev server
+
+```bash
+npx videowright dev
+```
+
+This boots a Vite dev server with the player pointed at the consumer's timeline. Open the printed URL in a browser to step through segments, review voiceover text, and iterate on content with hot reload.
+
+### Options
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--port <n>` | `5173` | Dev server port. If the port is taken, Vite picks the next available. |
+| `--verbose` | off | Show extra detail (config path, timeline path). |
+
+### Positional argument
+
+```bash
+npx videowright dev videos/my_video/timeline.ts
+```
+
+Pass a specific timeline path to preview that video. Without it, the dev server uses default discovery.
+
+## Default discovery
+
+When no timeline path is given, `videowright dev` finds the most recently modified `timeline.ts` under `videos/`. It scans `videos/*/timeline.ts`, sorts by file modification time (newest first), and picks the top result.
+
+This means after editing a video, `npx videowright dev` automatically picks it up without needing to specify the path.
+
+If no videos exist, the command errors with a hint to create one.
+
+## URL hash navigation
+
+The player URL supports hash-based positioning:
+
+```
+http://localhost:5173/#/<segmentId>/<beat>
+```
+
+For example, `#/feature-cards/2` jumps to the `feature-cards` segment at beat 2. This is useful for:
+
+- Sharing a specific position with someone reviewing the video.
+- Bookmarking a position during development.
+- Jumping directly to a segment you are iterating on.
+
+The player updates the hash as you navigate, so the URL always reflects the current position.
+
+### `?to=<id>` query fallback
+
+The URL also supports a `?to=<id>` query parameter to jump to a specific segment:
+
+```
+http://localhost:5173/?to=feature-cards
+```
+
+If present, the player jumps to that segment, removes the query parameter from the URL, and replaces the history entry. This is a one-shot jump — the query is consumed on use.
+
+## Hot reload
+
+The dev server uses Vite's file-watching with full page reloads. When you save changes to:
+
+- **Segment files** (`segments/<id>/index.ts`) — the page reloads and replays from the current segment.
+- **Timeline files** (`videos/<name>/timeline.ts`) — the page reloads with the updated segment order.
+- **Style tokens** (`styles/<slug>/tokens.css`) — the page reloads with the updated CSS variables.
+- **Components** (`components/*/index.ts`) — the page reloads.
+
+Edits appear almost instantly. You do not need to restart the dev server when editing content.
+
+## Audio playback
+
+When the video has a `default_audio_track` set in `timeline.ts`, the dev server loads the audio and enables synced playback:
+
+- The play button in the HUD starts auto-advance with audio playing through an HTML `<audio>` element.
+- Audio is synced to the player's logical timeline position.
+- Manual navigation (arrow keys, clicking, number keys) pauses audio and stops auto-advance.
+- Pressing play again resumes from the current position.
+
+If no `default_audio_track` is set, the play button still works — it auto-advances silently using `default_timing` or segment `advances`.
+
+`dev` does not accept an `--audio-track` flag. It always uses `default_audio_track` from `timeline.ts`. To test a specific audio track, set it as the default.
+
+## HUD (Heads-Up Display)
+
+The HUD is a semi-transparent overlay at the bottom of the player that shows:
+
+| Field | Description |
+|---|---|
+| **play/pause button** | Toggle auto-advance with synced audio. Shows triangle (play) in idle, pause icon when playing. |
+| **segment** | Current segment id. |
+| **beat** | Current beat number within the segment. |
+| **seg time** | Elapsed time since this segment mounted. |
+| **total** | Total elapsed time since the video started. |
+| **mode** | `interactive` (always, in dev). |
+| **voiceover** | The current segment's `voiceover` text (if set). Shown in italics. |
+| **keyboard shortcuts** | Reminder line at the bottom of the HUD. |
+
+### Toggle
+
+Press **H** to toggle the HUD on and off. The HUD is visible by default.
+
+The `?hideHud=1` query parameter starts with the HUD hidden. This is used internally by `videowright render` so the HUD does not appear in exported frames.
+
+A small hide-HUD tab is anchored to the top edge of the HUD strip. Clicking it (or pressing H) toggles the HUD on and off. This is useful for users who want to screen-record the browser window without HUD clutter.
+
+### Error display
+
+If a segment throws during `mount()` or `play()`, the HUD displays a full-screen error overlay with:
+
+- The segment id that errored.
+- The error message.
+- A "Show stack trace" button.
+- A "Reload" button.
+
+This overlay is always visible regardless of HUD toggle state.
+
+## Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| **Right Arrow** or **Space** | Advance to next beat / next segment. |
+| **Left Arrow** | Go to previous segment. |
+| **R** | Restart the video from the beginning. |
+| **H** | Toggle HUD visibility. |
+| **1-9** | Jump to segment by index (1 = first segment). |
+
+### Mouse and touch
+
+- **Click** anywhere on the player (outside the HUD) advances to the next beat.
+- **Swipe left** advances to the next beat.
+- **Swipe right** goes to the previous segment.
+
+## Common workflows
+
+### Iterating on a segment
+
+1. Run `npx videowright dev`.
+2. Navigate to the segment (use number keys or arrow keys).
+3. The user describes what to change; the agent edits the segment file and saves. The page hot-reloads.
+4. Review the change in the browser. Repeat.
+
+### Reviewing voiceover
+
+1. Run `npx videowright dev` with the HUD visible (default).
+2. Step through segments. The HUD shows each segment's `voiceover` text.
+3. Compare the VO text with the visual content to verify they match.
+
+### Previewing a specific video
+
+```bash
+npx videowright dev videos/launch_2026/timeline.ts
+```

package/skill/references/export.md

@@ -0,0 +1,145 @@
+# Export
+
+## When this is loaded
+
+You were routed here from the intent dispatch table because the user wants to export a video to MP4.
+
+Videowright has one command for producing video output:
+
+- **`render`** -- deterministic frame-by-frame MP4 export via Playwright + ffmpeg. This is the only command that produces an MP4 file.
+
+For screen recording, use the dev server and your own screen-capture software (see below).
+
+## `videowright render`
+
+Deterministic frame-by-frame export. The player runs in render mode with no wall-clock dependence.
+
+```bash
+npx videowright render
+npx videowright render videos/my_video/timeline.ts
+```
+
+### How it works
+
+1. Boots a Vite server with the render entry point.
+2. Launches headless Chromium via Playwright.
+3. Navigates to the render page and waits for render mode to initialize.
+4. Validates all segments' `advances` arrays.
+5. Builds a frame schedule from advances (converts seconds to frame indices at the target fps).
+6. Captures each frame via CDP screenshot and fires `renderAdvance()` at scheduled frame boundaries.
+7. Pipes frames to ffmpeg for MP4 encoding.
+
+### Characteristics
+
+- **Mode**: render (`ctx.mode === 'render'`). All timer primitives are virtualized; `clock()` returns deterministic time based on frame count.
+- **Default fps**: 60.
+- **Determinism**: Fully deterministic -- frames are byte-identical across runs.
+- **Best for**: Final exports, CI pipelines, videos where reproducibility matters.
+
+## Screen Recording
+
+For screen recording, use `videowright dev` and open the video view in a browser. The download modal (accessible via the download icon in the top bar or on homepage cards) provides instructions for screen recording:
+
+1. Open the video in the dev server.
+2. Press **H** or click the hide-HUD tab to hide the HUD.
+3. Use **← →** keys to advance manually and **Space** to play/pause.
+4. Run your screen-capture software over the browser window.
+
+## Render options
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--width <n>` | `1920` | Video width in pixels. |
+| `--height <n>` | `1080` | Video height in pixels. |
+| `--fps <n>` | `60` | Frames per second. |
+| `--output <path>` | `output.mp4` | Output file path (relative to cwd). |
+| `--audio-track <id>` | | Use audio track from `audio/tracks/<id>/`. |
+| `--audio-track none` | | Disable audio (ignore `default_audio_track`). |
+| `--verbose` | off | Show progress, frame counts, timing, ffmpeg output on error. |
+
+### Positional argument
+
+`render` accepts an optional positional argument -- either a slug (directory name under `videos/`) or a path to a `timeline.ts`. When no argument is given:
+- **Single video**: renders it automatically.
+- **Multiple videos**: prompts for selection (interactive TTY) or lists slug commands (non-interactive/CI).
+- **No videos**: errors with guidance.
+
+## Dependencies
+
+### ffmpeg
+
+`render` requires `ffmpeg` installed and available on `PATH`. The CLI auto-detects it. If ffmpeg is not found, the command errors with a clear message.
+
+Install ffmpeg:
+- **macOS**: `brew install ffmpeg`
+- **Ubuntu/Debian**: `sudo apt install ffmpeg`
+- **Windows**: Download from https://ffmpeg.org/download.html
+
+### Playwright / Chromium
+
+`render` uses Playwright to launch headless Chromium. Playwright is a dev dependency of Videowright. If Chromium is not installed, Playwright will prompt to install it:
+
+```bash
+npx playwright install chromium
+```
+
+## Audio
+
+When an audio track is active, `render` muxes the audio file into the output MP4 via ffmpeg:
+
+- The audio file is added as a second input to ffmpeg alongside the frame pipe.
+- Audio is encoded as AAC at 192kbps.
+- The `-shortest` flag bounds output to the shorter of video and audio.
+- The audio track's `Timing` object drives segment advances, so video and audio durations should match.
+
+### Audio track selection
+
+```bash
+# Use a specific audio track
+npx videowright render --audio-track v1
+
+# Suppress audio (ignore default_audio_track)
+npx videowright render --audio-track none
+
+# No flag: use default_audio_track from timeline.ts if set, otherwise silent
+npx videowright render
+```
+
+If no audio track is active (no `--audio-track` flag and no `default_audio_track`), the output is silent.
+
+## Output
+
+The default output path is `output.mp4` in the current working directory. A suggested convention is to place exports inside the video's folder at `videos/<name>/exports/`:
+
+```bash
+npx videowright render --output videos/demo/exports/final.mp4
+```
+
+The output is an H.264-encoded MP4 with `yuv420p` pixel format (widely compatible).
+
+## Advances validation
+
+`render` validates every segment's `advances` array before starting capture:
+
+- Every segment referenced in the timeline must have a non-empty `advances` array.
+- Values must be positive and monotonically increasing.
+
+If validation fails, the command errors with a message identifying which segment has the problem.
+
+### Coherence checks during capture
+
+During rendering, the driver checks for coherence issues:
+
+- **Segment transitioned too early**: A segment moved to the next segment before all its advances were fired. Fix: remove unused entries from the `advances` array.
+- **Segment parked after all advances**: All advances fired but the segment is still waiting (stuck on `waitForNext`). Fix: add more entries to the `advances` array.
+
+## Common gotchas
+
+| Issue | Explanation |
+|---|---|
+| Video looks different from dev mode | `render` uses render mode where all timing is driven by the deterministic virtual clock. If a segment branches on `ctx.mode`, its behavior may differ. Test in both modes. |
+| ffmpeg not found | Install ffmpeg and ensure it is on your PATH. |
+| Chromium not installed | Run `npx playwright install chromium`. |
+| Export takes a long time | `render` at 60fps captures every frame individually. A 30-second video = 1800 frames. Use `--verbose` to see progress. |
+| `advances` validation error | Check that every segment has a valid `advances` array. See [authoring_segment.md](authoring_segment.md) for how advances maps to `waitForNext`/`hold` calls. |
+| Output file already exists | `render` overwrites the output file (`-y` flag to ffmpeg). |

package/skill/references/new_video.md

@@ -0,0 +1,117 @@
+# New Video
+
+## When this is loaded
+
+You were routed here from the intent dispatch table because the user wants to create a new video. This file covers the **design phase** — capturing intent and building a confirmed PLAN.md. Once the plan is confirmed, you hand off to [create_or_edit_video.md](create_or_edit_video.md) for the **build phase**.
+
+## Inputs to capture
+
+Before handing off to the build phase, you need all of the following. Ask only for what is missing from the user's input — never re-ask something already answered.
+
+| Input | Required | Notes |
+|---|---|---|
+| **Video name** | Yes | Folder name under `videos/`. Suggest a date prefix (e.g., `2026_05_launch`). Default: `demo_video` for the first video; derive from topic for subsequent ones. The first video is usually created during setup — if `videos/demo_video/` already exists, derive from the topic instead to avoid a collision. |
+| **Purpose** | Yes | What the video is for, who the audience is, what they should take away. |
+| **Style** | Yes | Confirm the current `defaultStyle` is right. If not, dispatch to [setup_new_style.md](setup_new_style.md) with `setAsDefault: false`, `copySample: false`. Use the resulting slug for this video's `meta.style`. |
+| **Audio intent** | Yes | Ask about each audio type: **voiceover** (yes/no), **sound effects** (yes/no), **background music** (yes/no), or **silent** (none of the above). Always ask — even when the input is rich. Silent is a real choice that changes pacing (longer beat holds, more visual motion). |
+| **Hard guidelines** | If any | Must-haves: specific charts, logos, screenshots, length cap, things to avoid. |
+| **Script** | If voiceover | Full VO copy if the user has it. If not, you will draft one during the build phase based on the other inputs. |
+| **Segment outline** | Optional | If the user has a structure in mind, capture it. Otherwise, the build phase generates one from the script + purpose. |
+
+### Audio intent notes
+
+When the user picks **voiceover** (or any audio), note that Videowright supports integrated audio tracks:
+
+- Audio plays in the dev server via an HTML `<audio>` element synced to the player.
+- `render` muxes audio into the output MP4 via ffmpeg.
+- The audio flow (voiceover, SFX, music) is handled after the video is scaffolded. See [audio.md](audio.md).
+
+## One-shot vs. iterate
+
+Read the user's invocation carefully before asking anything.
+
+**One-shot** — the user's input already contains:
+- A multi-paragraph script or detailed description, AND
+- Enough style/purpose signals to fill in the plan
+
+Even when one-shotting, **always confirm audio intent explicitly** before drafting. Audio intent is never inferred — silent is a real choice that changes pacing. If the user's input includes a clear audio statement (e.g., "this has a voiceover" or "silent video"), that counts as confirmation. Otherwise, ask: "One quick question before I draft the plan — will this video have a voiceover, sound effects, or background music?"
+
+Once audio is confirmed, draft the full PLAN.md in one pass and present it: "Here's the plan I built from your input — anything to change?" Do not ask other intermediate questions.
+
+**Iterate** — the input is sparse or missing key details.
+
+In this case, ask **only the missing questions**, grouped into a single round. Do not ask one question at a time. Example:
+
+> Before I build the plan, a few things I need:
+> 1. What's this video for and who's the audience?
+> 2. Should we use the current default style, or do you want something different?
+> 3. Audio: voiceover? sound effects? background music? (or silent)
+
+### Propose, don't interrogate
+
+The default posture is **propose**. When uncertain about a detail, put a reasonable answer in the proposed PLAN.md and flag it for review — do not ask another question. Let the user correct the proposal rather than drilling them with questions.
+
+## PLAN.md skeleton
+
+Write PLAN.md into `videos/<name>/PLAN.md`. Use this structure:
+
+```markdown
+# Plan: <video title>
+
+## Purpose
+- Audience: <who>
+- Takeaway: <what they should leave with>
+- Constraints / hard guidelines: <must-haves, must-avoids>
+
+## Style
+- Active style: <slug>
+- Notes: <any per-video style deviations or notes>
+
+## Audio intent
+- Voiceover: yes | no
+- Sound effects: yes | no
+- Background music: yes | no
+- Notes: <pacing implications, music vibe, VO tone, etc.>
+
+## Segment outline
+1. <id> — <one-line purpose>
+2. <id> — <one-line purpose>
+...
+
+## Script (if applicable)
+<full VO script, or "see voiceover_script/script.md">
+
+---
+
+## Log
+
+### YYYY-MM-DD — Initial scaffold
+- <what was built>
+```
+
+### PLAN.md rules
+
+- The **Plan block** (Purpose / Style / Audio / Segment outline / Script) is **mutable** — overwritten as the design evolves.
+- The **Log block** is **append-only**. Never delete entries. When meaningful changes happen (script revision, segment add/remove, style swap, design pivot), append a dated log entry.
+- When in doubt, log it.
+
+## Flow
+
+1. **Evaluate the user's input.** Decide: one-shot or iterate?
+2. **Gather missing inputs** (if iterating). Group questions into a single round.
+3. **Draft PLAN.md.** Fill in all sections from the skeleton above.
+4. **Present the plan for confirmation.** Show a summary — not the raw markdown — and ask: "Here's the plan. Anything to change?"
+5. **Iterate if needed.** The user may want to adjust the script, add segments, change the style, etc. Update the plan each round.
+6. **Write the confirmed PLAN.md** to `videos/<name>/PLAN.md`. Create the `videos/<name>/` directory if it does not exist.
+7. **Hand off to build.** Load [create_or_edit_video.md](create_or_edit_video.md) and follow it with the create-mode entry condition (video folder is new, PLAN.md was just written).
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| User already has a `videos/<name>/` folder with a PLAN.md | This is an edit, not a new video. Route to [create_or_edit_video.md](create_or_edit_video.md) in edit mode instead. |
+| User wants a style other than `defaultStyle` | Dispatch to [setup_new_style.md](setup_new_style.md) with `setAsDefault: false`, `copySample: false`. Use the resulting slug for `meta.style` in the plan and timeline. |
+| User provides a complete script but no segment outline | Generate the segment outline from the script during PLAN.md drafting. Each natural section of the script maps to a segment. |
+| User provides a segment outline but no script | Capture the outline. The build phase will draft VO from the outline if audio intent is voiceover. |
+| Video name conflicts with an existing folder | Ask the user to pick a different name, or confirm they want to overwrite. |
+| User skips the audio question | Do not skip it yourself. Audio intent affects pacing. Ask directly: "One more thing — will this video have a voiceover, sound effects, or background music?" |