Summary

• Normalize MkDocs list formatting to prevent collapsed bullets and improve readability.
• Fix internal doc links/anchors flagged by mkdocs serve (broken relative paths, missing anchors).
• Align API documentation with actual runtime ports and auth requirements (8000 dev, 4444 serve, 8080 docker‑compose via nginx; health/readiness/base URLs).
• Update Mermaid diagrams to match current code paths (OAuth UI flow, multitenancy/SSO/admin flows) and ensure diagrams render in both themes.
• Link generated architecture diagrams produced by make docs.

Related

• Addresses DOC‑04 from [TESTING][DOCUMENTATION]: API Documentation Accuracy, Code Examples, and Tutorial Validation #2483 (API reference accuracy: ports/auth/health/base URL alignment).
• Partially addresses [TESTING][DOCUMENTATION]: API Documentation Accuracy, Code Examples, and Tutorial Validation #2483 overall.

Coverage vs #2483

Addressed

• DOC‑04: API reference accuracy (ports/auth/health/base URL alignment).
• DOC‑05 (partial): Architecture diagrams current (updated Mermaid content + linked generated diagrams).
• DOC‑08 (partial): Broken links (internal links/anchors fixed from MkDocs warnings).

Not addressed

• DOC‑01: OpenAPI lint/endpoint diff.
• DOC‑02: Run/validate all curl examples end‑to‑end.
• DOC‑03: Full quickstart walkthrough validation.
• DOC‑06: CHANGELOG review.
• DOC‑07: README validation against current behavior.
• External link checker + schema response validation.