# Repository context

- This repository is a restoration workbench for the `al-Forsa` source master at `/home/mnm/.workspace-mcp/attachments/Best of al-Forsa-Mo_a226afcd.mp4`.
- The main recurring risk in this repo is confusing a full-timeline cleaned base with a local span replacement set.

# Critical distinction

- A **full-timeline cleaned base** modifies the subtitle ROI across the whole video.
- A **local replacement set** only contains replacements for specific frame ranges and must be applied onto an existing base.
- Never treat a replacement directory or a span-only output as a stand-alone cleaned master.

# Script responsibilities

- `scripts/12_apply_frame_replacements.py` is a patching tool only.
- It replaces only frames explicitly present as `f_<frame>.png`.
- It does not create a cleaned base, detect spans, or verify that the base is already cleaned.
- `scripts/28_prepare_hybrid_replacements.py` only assembles replacement PNGs for selected hard spans.
- It does not create a timeline output.

# Known-good references

- Preferred validated full-timeline base: `work/final/forsa_clean_final_v2_lossless.mkv`
- Alternate full-timeline base: `work/final/forsa_clean_final_v3_lossless.mkv`
- Best p1 hard-span refinement (`5350-5385`): `work/run_034/p1/e2_tight_span_lossless.mkv`
- Best p2 hard-span refinement (`980-1015`): `work/run_035/p2/e2_tight_plus_span_lossless.mkv`
- Selected replacement set for those spans: `work/run_036/replacements_hybrid/`
- Correct rebuilt final example: `work/run_041/`

# Required workflow for any new final or hybrid

- Identify and record the intended base video before building.
- Record the replacement source, patched spans, and output paths in a manifest.
- Apply local replacements only onto a validated full-timeline cleaned base.
- Restore original audio after building the patched video output.
- Produce both a lossless master and a streamable review encode when packaging a candidate final.

# Required validation

- Always validate a patched result against both the original source and the intended base.
- For a correct patched final, sampled frames should still differ from source across nearly the whole timeline.
- Frames outside patched spans should closely match the intended base.
- Patched spans should match the selected replacement source clips.
- If a supposed final matches source on most sampled frames, treat it as invalid and stop.
- Do not rely on patched-span validation alone.

# Known failure to avoid

- `run_032`, `run_037`, and `run_038` were invalid as full-video finals because the patching stage used a source-like timeline as the base.
- That failure mode produced outputs that only changed 72 frames while leaving the rest of the video effectively original.
- Any future method can fail in the same way if a good local patch is applied to the wrong base and only the patched spans are reviewed.

# Model example

- Use `work/run_041/final_manifest.json` as the template for future final-candidate manifests.
- `run_041` is the reference example of the correct pattern: validated full-timeline base plus targeted hard-span replacements plus whole-timeline audit.