Required: edit-list.json (mandatory), subtitles.json, visuals.json + modules/
Output: final-video.mp4

node "<plugin root>/scripts/ensure-running.cjs" --json
node "<plugin root>/scripts/videocut-cli.cjs" export <project> --dry-run --json          # Preview the plan without encoding
node "<plugin root>/scripts/videocut-cli.cjs" export <project> --json                    # Generate final video (default 2x scale, source frame rate)
node "<plugin root>/scripts/videocut-cli.cjs" export <project> --out /path/final-video.mp4 --json
node "<plugin root>/scripts/videocut-cli.cjs" export <project> --scale 1 --json          # Use source resolution only
node "<plugin root>/scripts/videocut-cli.cjs" export <project> --keep-work --json        # Keep intermediate clips and frame-by-frame PNGs for troubleshooting

① Run --dry-run first to report the plan: video duration, number of frames, number of subtitle screens, number of visual layers, number of zoom-in segments, output resolution. Read this aloud to the user. If the numbers are incorrect, the upstream steps are wrong — encoding for ten minutes won't fix it.
② Execute the actual export: progress through four stages: assemble → overlay → compose → verify

Source width ≥2560 (Retina native screen recording) → Use --scale 1; the output will be native pixels, which is the best scenario.
Source width <1920 (e.g., 960×720) → Pause first: ask the user if there is a high-definition export of the same recording. Screen recording tools often allow re-exporting the same recording at 3x resolution. Replacing the source is more effective than any post-processing (see next section). If no HD source is available → Use --scale 2.

ffprobe -v error -show_entries format=duration -of csv=p=0 <two files>   # Durations must be identical down to the millisecond
ffmpeg -v error -i <file> -map 0:a:0 -c copy -f md5 -                  # Audio streams must be bit-for-bit identical

**Bit-for-bit identical audio = identical timeline**: The word-by-word script, ledger, subtitles, and visual layers are all tied to word IDs — no changes are needed. This is the realization of "binding to words instead of timestamps" for source replacement.

**Four Steps for Source Replacement** (tested on 2026-07-29; step ③ was missed at the time, causing the editing preview to throw a "generation failed" error — fingerprint records exist in multiple places; grep for the old fingerprint to find all instances before proceeding):

```text
① Replace the files: input/source.mp4 and uploads/source.mp4 are hard-linked — delete both, copy the new file to input/, then create a hard link back to uploads/ (use `ln` on macOS; use `New-Item -ItemType HardLink` on Windows)
② Update the fingerprint: Change the source.sha256 in project.json to that of the new file
③ Check another location: workbench.json also records the source fingerprint (sourceSha256), which is exactly what the editing preview pipeline verifies — missing this will cause the preview to refuse generation (this is correct product behavior: if fingerprints don't match, fail instead of using an old preview)
④ Re-export with --scale 1 — the purpose of source replacement is to get native pixels, so don't enlarge again

① Command returns successfully: The product automatically compares the final video's resolution, frame count, and audio track with the plan. If they don't match, throw a readback_mismatch error; the file remains on disk as evidence, and export is not considered complete.
② Extract frames to check pixels: Extract frames from the final video and check visually. Cover at least: one zoom-in segment, one full-screen animation segment, one subtitle-only segment, and one layer boundary.
③ Human audio verification: If no one has listened to the audio, mark it as human listening UNVERIFIED.

ffmpeg -v error -ss 8.84 -i final-video.mp4 -frames:v 1 -y frame.png

assembled.mkv    Contains only edited footage, no overlays. If this is wrong → The ledger or editing segments are incorrect.
overlay/*.png    Contains only overlays with transparent backgrounds. If this is wrong → Subtitle styles or modules are incorrect.
spans/*.mp4      Segmented videos after composition. If this is wrong → Zoom-in or alignment is incorrect.

No subtitles/animations in final video → Are overlay PNGs fully transparent? Did the module not implement seek?
Animation stays on first frame → The module did not implement seek, or the GSAP timeline was not paused.
Entire screen is white → The module is missing `:root { color-scheme: dark }`.
Zoom-in frame is misaligned → The module's viewBox and layer's zoom values do not match.
Final video is shorter than planned → A span has insufficient frames; check errors in the compose stage.
Original footage flashes briefly at layer boundaries → Overlay screenshots are outdated (frame marker verification failed). The product uses a frame marker bar at the top of the page to prove which frame each screenshot belongs to; if this recurs, first confirm that overlay PNGs have the marker bar and that compose includes cropping to remove it.
Chrome not found → Install Google Chrome; do not switch to a different rendering path.