Improve docs pipeline with generated topology diagrams

docs/README.md

@@ -2,21 +2,37 @@
 
 ## Local generation
 
+Install prerequisites:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y graphviz
+```
+
+Then generate and validate public docs:
+
 ```bash
 chmod +x scripts/docs/*.sh
 scripts/docs/generate-all.sh
+python3 -m mkdocs build -f mkdocs-public.yml --strict
+```
+
+NixOS-friendly alternative:
+
+```bash
+nix shell nixpkgs#graphviz nixpkgs#python3 nixpkgs#python3Packages.pyyaml
 ```
 
 This pipeline only runs `docker compose config` and static parsing. It does **not** start containers.
 
 ## CI behaviour
 
-GitHub Actions workflow `.github/workflows/generate-docs.yml` runs on pushes/PRs to `main` and manual dispatch. It generates docs and uploads them as the `generated-documentation` artifact.
+GitHub Actions workflow `.github/workflows/generate-docs.yml` validates committed public docs and diagrams and runs a strict public MkDocs build.
 
 ## Outputs
 
 - `docs/generated`: resolved compose config and markdown inventories
-- `docs/diagrams`: DOT and SVG architecture diagram
+- `docs/diagrams`: generated DOT and SVG diagrams
 - `docs/public`: sanitized copy for public sharing
 
 ## Publication safety