feat(generate_markdown): --optimize-only retro pass over committed PNGs

[Jammy2211]

Closes the tooling half of PyAutoHands#247.

What

optimize_pngs() shrinks the figures nbconvert extracts, but it is forward-only by construction — it only ever sees the render in progress. Pages committed before it shipped keep their original PNGs forever. Across the six markdown workspaces, 405 of 429 committed PNGs are still RGBA, 88.4 MB of the 91.2 MB total.

--optimize-only renders nothing and walks markdown/**/<page>_files/ through the same optimize_pngs(), so a retro pass and a future re-render produce identical bytes. optimize_pngs() now returns (before, after) byte totals so the walk can report what it reclaimed.

Deliberately not a one-off pngquant sweep (which would diverge from what the tool emits) and deliberately no dpi knob — quantize already delivers ~74%, and dropping dpi would degrade every future render's readability for a smaller marginal gain.

The flag is checked before the PYAUTO_TEST_MODE guard on purpose: it executes no script and runs no search, so a truncated-search build cannot corrupt it.

API Changes

None. --optimize-only is a new opt-in CLI flag; default behaviour is byte-for-byte unchanged.

optimize_pngs() changes its return value from None to (bytes_before, bytes_after). It is an internal helper of this module with one in-tree caller (render_script, which ignores the return) — no downstream consumer.

Verification

• pytest tests/ — 354 passed, including 5 new TestOptimizeExisting cases (walks every _files dir; leaves everything outside markdown/ alone; idempotent; no-markdown/ and empty-markdown/ no-ops).
• End-to-end on a scratch copy of real autolens pages: 3.1 MB → 0.9 MB (28%), dimensions preserved, already-optimized P-mode images correctly left alone, second pass byte-identical.
• Applied for real across all six workspaces (shipping as separate workspace PRs): 91.2 MB → 24.7 MB, 66.5 MB reclaimed. HowToLens reclaimed exactly 0, as predicted — it was rendered post-feat: markdown generator per-cell stdout truncation + PNG optimization #200 and is already fully optimized.
• 29-pair before/after pixel diff on the real corpus: worst case 2.69% of pixels differing by >3% intensity, i.e. quantize dithering on smooth colormap gradients.

Notes

This shrinks the working tree and future clone-of-tip, not .git history — the original blobs stay in the pack. No history rewrite is proposed.

Heart at PR-open time: stale (85), sole reason release validation stale: source moved since rehearsal (PyAutoGalaxy) — unrelated to this repo.

🤖 Generated with Claude Code