Replace PlantUML documentation diagrams with Mermaid

[arturcic]

Motivation

The documentation diagrams currently use PlantUML-oriented generation and assets, while the version-calculation diagram is loaded from a remote PlantUML rendering endpoint.

This has several drawbacks:

• Documentation rendering depends on an external service for one of its core diagrams.
• Diagram sources are not managed consistently inside the repository.
• Contributors need a separate PlantUML or PlantText workflow to update examples.
• There is no automated check that generated diagram sources remain synchronized and contain valid Mermaid syntax.

Mermaid is already widely supported in Markdown-oriented tooling. Keeping Mermaid sources in the repository and rendering them client-side with a pinned Mermaid runtime makes the documentation build self-contained while avoiding generated image artifacts.

Proposed change

• Generate documentation sequence diagrams as Mermaid sources.
• Store Mermaid sources in the repository.
• Replace the remotely rendered architecture diagram with a repository-local Mermaid source.
• Embed Mermaid source in the generated documentation HTML and render it client-side on GitHub Pages.
• Provide Cake targets for reproducibly generating and validating diagrams.
• Verify Mermaid source drift and syntax in the documentation workflow.

Acceptance criteria

• No documentation page depends on PlantUML or a remote PlantUML renderer.
• Documentation diagrams have committed Mermaid source files.
• Documentation HTML embeds the Mermaid source and renders it client-side using a pinned Mermaid runtime.
• Diagram generation and validation are available through Cake build targets.
• CI fails when generated Mermaid sources are stale or contain invalid syntax.
• Generated SVG artifacts are not committed.
• Contributor documentation explains how to update and verify diagrams.