Fix multiple open issues: quality mapping, binary discovery, freeze guard, scene lint, timeouts, stale detection, layout validation

[jmjava]

Summary

This PR addresses 8 of the 14 open issues with concrete code fixes, new features, and tests. All changes are backward-compatible — existing docgen.yaml files work without modification.

Issues Addressed

Issue #6 — Manim quality mapping: 1080p30 falls back to 720p30 silently

• Expanded _quality_flags() to support arbitrary <height>p<fps> strings (e.g. 1080p30, 1440p60) using explicit --resolution and --frame_rate flags
• Known presets (480p15, 720p30, 1080p60, 2160p60) still use Manim's built-in -ql/-qm/-qh/-qp flags
• Unrecognized quality strings now print a clear warning listing valid options before falling back to 720p30

Issue #7 — docgen manim/vhs not found in PATH when run via venv entry point

• ManimRunner._find_manim() checks the active venv's bin/ directory (sys.prefix) before falling back to $PATH
• VHSRunner._find_vhs() checks $PATH then common install locations (~/go/bin, /usr/local/bin, /snap/bin)
• Both print actionable installation instructions on failure

Issue #8 — FREEZE GUARD fires on first run because Manim has no timing data yet

• Pipeline.run() now catches ComposeError from the compose stage
• On FREEZE GUARD failure, it automatically clears the Manim media cache and re-renders scenes (which now have access to the freshly-generated timing.json)
• Retried compose runs with the newly rendered videos
• Only retries if Manim was not skipped (--skip-manim)

Issues #9, #10, #4 — Scene linting for weight=BOLD and positional color args

• New scene_lint.py module with lint_scene_file() and lint_scene_dir() functions
• Detects weight=BOLD (Pango font substitution) and positional color arguments to Text() (cryptic ValueError)
• New docgen scene-lint CLI command
• Wired into validate.py as a soft check (warns in pre-push, doesn't block)

Issue #13 — Configurable ffmpeg timeout

• New compose.ffmpeg_timeout config property (default 600s, up from hardcoded 300s)
• Used by compose.py, manim_runner.py, and vhs.py
• Timeout error messages now suggest increasing the value in docgen.yaml

Issue #12 — Stale VHS rendered mp4 detection

• Composer._vhs_path() now checks if any .tape file is newer than the rendered mp4
• Prints a clear warning: "run 'docgen vhs' to re-render before composing"
• Configurable via compose.warn_stale_vhs (default true)

Issue #2 — Layout validation wired into validator

• Validator.validate_segment() now runs layout overlap/edge checks on Manim-type segments
• Uses the existing LayoutValidator from manim_layout.py
• Degrades gracefully if tesseract is not installed

Compose path resolution (from Issue #3 lesson 9)

• _manim_path() and _resolve_source() now try the configured quality directory first, then fall back to other available quality directories
• Also checks the videos/<quality>/ path (no scenes/ subdirectory) for compatibility with programmatic renders

Config Additions

New optional properties in docgen.yaml:

manim:
  font: "Liberation Sans"    # Default font for Manim scenes (issue #4)

compose:
  ffmpeg_timeout: 600        # Seconds before ffmpeg times out (issue #13)
  warn_stale_vhs: true       # Warn if .tape is newer than rendered mp4 (issue #12)

Tests

• 27 new tests across 3 new test files (test_scene_lint.py, test_manim_runner.py, test_compose_extras.py)
• All 100 tests pass
• Ruff lint clean