Diagram: PNG/MMD count mismatch and sync check cannot run reliably #1892

Category: sync
Severity: medium

Problem

100 .mmd files vs 104 .png files — extras:

• docs/images/book-cover.png (intentional, no source)
• docs/images/diagram_05_chapter4.png (no matching .mmd, referenced only in docs/archive/cloud_architecture.md)
• docs/images/diagram_13_chapter12.png (no matching .mmd, referenced only in docs/archive/microservices_architecture_en.md)
• docs/images/release_information_page.png (no matching .mmd)

scripts/check_mermaid_diagrams.py failed with Mermaid CLI (mmdc) is unavailable. Run 'npm ci' before executing this check., so PNG drift could not be verified. The four unmatched PNGs are "orphan PNGs" — two of them only referenced from archived docs and therefore candidates for removal; the other two (book cover, release info page) are legitimate non-Mermaid assets.

Suggested fix

1. Delete diagram_05_chapter4.png and diagram_13_chapter12.png once the archived markdown is confirmed out of the build
2. Add a .gitattributes-style allowlist or README entry documenting which PNGs intentionally have no .mmd source
3. In CI, run npm ci && python3 scripts/check_mermaid_diagrams.py as a gating step so local agents get actionable drift reports

Auto-generated by graphic-designer review agent.