docs: add architecture section and overhaul top-level README

- Move Simon's architecture documentation into architecture/
  (setup, variables, topology, dns, deploy, security, operations
  plus index and glossary). All cross-repo references point at
  https://git.digitalboard.ch/Digitalboard/{reference-ansible,dns-zones}
  via absolute URLs so the docs remain navigable from any context.
- Rewrite README.md as a documentation hub: introduction, platform
  Mermaid overview, comparison of the three repos
  (docs / digitalboard.core / reference-ansible) and a full table of
  contents covering architecture, contributing, infrastructure,
  keycloak, ms-entra and troubleshooting.

Addresses the open items from the WKS PoC review (2026-05-26):
docs README begrüssungstext + Übersichtsgrafik + Verlinkung der
beiden anderen Repos, sowie das Verschieben der Architektur-Doku.

architecture/setup.md

@@ -0,0 +1,68 @@
+<!-- markdownlint-disable MD013 MD060 MD051 -->
+# Setup and repo layout
+
+← Back to [Architecture index](README.md)
+
+## 1. Repo layout and role provenance
+
+```text
+reference-ansible/
+├── Makefile                     # Deploy targets, OIDC login, OBJC fork workaround
+├── ansible.cfg                  # collections_path, remote_user=root, hashi_vault auth_method=token
+├── requirements.yml             # community.hashi_vault + digitalboard.core (Git)
+├── playbooks/site.yml           # Play sequence (14 plays, see deploy.md)
+├── collections/                 # ← installed by `make install`, gitignored
+│   └── ansible_collections/
+│       └── digitalboard/core/
+│           └── roles/           # 🔑 Roles live HERE, NOT in the repo root
+└── inventories/
+    ├── demo-gymburgdorf/        # Inventory used throughout this document
+    ├── demo-mbazürich/
+    ├── demo-phbern/
+    └── vagrant/                 # Local test inventory with its own topology
+```
+
+> **Important:** There is **no** `roles/` directory at the repo root.
+> All roles come from the `digitalboard.core` collection (see
+> [requirements.yml](https://git.digitalboard.ch/Digitalboard/reference-ansible/src/branch/main/requirements.yml)), installed via `make install`
+> into `./collections/`. Plays reference them by FQCN
+> `digitalboard.core.<role>`.
+
+## 2. Setup and prerequisites
+
+**Tools on the control node:**
+
+- `ansible` (Core ≥ 2.15)
+- `bao` CLI (OpenBao) — e.g. `sudo pacman -S openbao python-hvac` (Arch) or Homebrew
+- `python-hvac` (for `community.hashi_vault` lookups)
+- On macOS: `OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` (set in the
+  [Makefile](https://git.digitalboard.ch/Digitalboard/reference-ansible/src/branch/main/Makefile); without it Ansible forks crash on Bao lookups)
+
+**Initial setup:**
+
+```bash
+git clone <repo>
+cd reference-ansible
+make install         # Galaxy + digitalboard.core into ./collections/
+```
+
+**Before every deploy:** Bao login in the **same shell** that will then
+run `ansible-playbook`:
+
+```bash
+export BAO_ADDR=https://bao.digitalboard.ch
+bao login -method=oidc -path=Digitalboard
+export VAULT_TOKEN=$(bao print token)
+```
+
+> ⚠️ `make bao` on its own is **not enough**: every `make` target spawns
+> a new shell, and the `VAULT_TOKEN` exported in there only lives for
+> the duration of `make bao` itself. Either run the three commands
+> above manually, or invoke `make bao deploy_site_demo_gymburgdorf` as
+> **one** call — otherwise the deploy has no token.
+
+**Smoke test:**
+
+```bash
+make ping_demo       # pings all three demo inventories
+```