docs: MkDocs scaffold, ADR-0001, README quickstart (refs #32)

Add mkdocs.yml (Material theme + nav), docs/index.md, and the first ADR
(docs/architecture/adr-0001-loose-coupling.md, Nygard template) recording
the loose-coupling stance from CLAUDE.md §8. Rewrite the README quickstart
to be accurate and reach a green local environment in under 10 minutes
(correct clone URL, .NET 10 + container-engine prereqs, `make ci` and the
compose smoke), and document building the docs site. Ignore .venv/ and site/.

Verified: `mkdocs build` succeeds; `make lint/build/unit` green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -22,6 +22,10 @@ node_modules/
 dist/
 .angular/
 
+# Python / MkDocs
+.venv/
+site/
+
 # OS
 .DS_Store
 Thumbs.db

README.md

@@ -41,31 +41,32 @@ For the architecture rationale, see [docs/PRD.md §3](docs/PRD.md) and [docs/arc
 
 **Prerequisites**
 
-- Docker Engine (or Docker Desktop) with Compose v2
+- .NET 10 SDK (for `make lint/build/unit`)
-- ~8 GB free RAM, ~10 GB free disk
+- A container engine with Compose v2 — Docker, or rootless Podman (see [docs/runbooks/ci.md](docs/runbooks/ci.md) for the Podman + Compose-provider setup)
-- Bash or PowerShell
+- `make`, `curl`, `git`
+- ~4 GB free RAM, ~5 GB free disk (grows as services land)
 
-**Bring the stack up**
+**Clone**
 
 ```bash
-git clone https://gitea.respellion.local/respellion/register-reference.git
+git clone git@git.labs.respellion.tech:eho/register-referentie.git
-cd register-reference
+cd register-referentie
-cp .env.example .env          # edit if you change ports
-docker compose -f infra/docker-compose.yml up -d
 ```
 
-Health checks should be green within ~3 minutes on a developer machine. If something fails, see [docs/runbooks/local-startup.md](docs/runbooks/local-startup.md).
+**Wired today (Iteration 0):** only the placeholder BFF exists so far. Get to green in under 10 minutes — run the full check gate, or just the running service:
 
-> **Wired today (Iteration 0):** only the placeholder BFF is in `infra/docker-compose.yml` so far. Bring it up and smoke-test its health endpoint:
+```bash
->
+make ci          # lint + build + unit + container smoke — the CI gate
-> ```bash
+```
-> docker compose -f infra/docker-compose.yml up -d --build --wait
-> curl http://localhost:8080/health   # -> Healthy
-> ```
->
-> `--wait` exits non-zero unless the container reports healthy, so this doubles as the compose-up smoke test. The remaining services and the URLs below land in later slices.
 
-**Default URLs**
+```bash
+docker compose -f infra/docker-compose.yml up -d --build --wait
+curl http://localhost:8080/health     # -> Healthy
+```
+
+`--wait` exits non-zero unless the container reports healthy, so it doubles as the compose-up smoke test. The remaining services and the URLs below land in later slices.
+
+**Target service URLs** *(most land in later slices)*
 
 | Service | URL |
 |---|---|
@@ -73,7 +74,7 @@ Health checks should be green within ~3 minutes on a developer machine. If somet
 | Openbaar register | http://localhost:4201 |
 | Behandel-portal | http://localhost:4202 |
 | Beheer-portal | http://localhost:4203 |
-| BFF | http://localhost:5000 |
+| BFF | http://localhost:8080 |
 | OpenZaak | http://localhost:8000 |
 | Open Notificaties | http://localhost:8001 |
 | Flowable | http://localhost:8080 |
@@ -82,10 +83,12 @@ Health checks should be green within ~3 minutes on a developer machine. If somet
 
 Test credentials, BSNs, and personas: see [docs/synthetic-data.md](docs/synthetic-data.md).
 
-**Re-seed synthetic data**
+**Build the docs site**
 
 ```bash
-./tools/seed.sh               # or pwsh ./tools/seed.ps1
+python3 -m venv .venv && .venv/bin/pip install mkdocs-material
+.venv/bin/mkdocs serve         # live preview at http://localhost:8000
+.venv/bin/mkdocs build         # static site in ./site
 ```
 
 ---

docs/architecture/adr-0001-loose-coupling.md

@@ -0,0 +1,58 @@
+# ADR-0001: Loose coupling to upstream Common Ground modules
+
+- **Status:** Accepted
+- **Date:** 2026-06-03
+- **Deciders:** Respellion engineering
+- **Template note:** This is the first ADR and doubles as the worked example of
+  the Nygard template. Copy its shape for new ADRs (`adr-NNNN-title.md`).
+
+## Context
+
+This reference application orchestrates several upstream Common Ground modules —
+OpenZaak (ZGW APIs), Open Notificaties (NRC), Objecten/Objecttypen, Flowable,
+Keycloak. Each is an independently developed, independently deployed peer. The
+temptation in a demo is to reach straight into a peer's database or couple to its
+internal schema to move faster. That coupling is exactly what makes Common Ground
+landscapes brittle and un-upgradeable in practice.
+
+We need a stance, recorded up front, on how our services may talk to these peers.
+
+## Decision
+
+**We integrate with upstream modules only through their documented public APIs, and
+we isolate that integration behind explicit anti-corruption boundaries.**
+
+Concretely (mirrors CLAUDE.md §8):
+
+1. The **ACL** is the only code that talks to ZGW APIs; no other service constructs
+   ZGW URLs.
+2. The **Workflow Client** is the only code that talks to Flowable; BPMN models hold
+   no OpenZaak knowledge.
+3. **Portals talk only to the BFF** — never directly to a backend or a peer module.
+4. **No direct database access across services or to any peer.** Each service owns
+   its schema; the Read Projection is a rebuildable derived artefact.
+5. **Idempotency at every event boundary** (the Event Subscriber tolerates duplicate
+   and out-of-order NRC events).
+
+Bending any of these is an ADR-worthy moment (CLAUDE.md §14): stop and open an
+`adr-proposal` issue first.
+
+## Consequences
+
+**Positive**
+
+- Upstream modules can be upgraded or swapped behind their APIs without rippling
+  through our services.
+- Coupling is visible and minimal — anti-corruption code lives in one named place.
+- The architecture teaches the Common Ground pattern by enforcing it.
+
+**Negative / costs**
+
+- More indirection: a translation layer (ACL, Workflow Client) instead of direct
+  calls. Accepted — it's the point.
+- Eventual consistency across aggregates must be designed for, not assumed away.
+
+**Follow-up**
+
+- Each integration slice that touches a boundary references this ADR; new boundary
+  decisions get their own ADR.

docs/index.md

@@ -0,0 +1,23 @@
+# register-referentie
+
+A reference application demonstrating Respellion's Common Ground architecture
+pattern. Quality and architectural clarity over feature throughput — every commit
+should teach.
+
+## Where to go
+
+- **[Product Requirements](PRD.md)** — what we're building and why.
+- **[ADR-0001: Loose coupling](architecture/adr-0001-loose-coupling.md)** — the
+  non-negotiable integration stance; the template for future ADRs.
+- **[Working in Gitea](gitea-workflow.md)** — issues, milestones, branches, PRs.
+- **[CI runbook](runbooks/ci.md)** — the pipeline and the `make ci` local gate.
+
+## Quickstart
+
+See the repository `README.md`. In short: clone, then either run the checks with
+`make ci`, or bring the BFF up with
+`docker compose -f infra/docker-compose.yml up -d --build --wait` and
+`curl http://localhost:8080/health`.
+
+> This site is built with MkDocs Material (`mkdocs build`). It grows with the
+> backlog; sections appear as their slices land.

mkdocs.yml

@@ -0,0 +1,41 @@
+site_name: register-referentie
+site_description: Reference application for Respellion's Common Ground architecture pattern
+docs_dir: docs
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.top
+    - content.code.copy
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+nav:
+  - Home: index.md
+  - Product Requirements: PRD.md
+  - Architecture:
+      - "ADR-0001: Loose coupling": architecture/adr-0001-loose-coupling.md
+  - Working in Gitea: gitea-workflow.md
+  - Runbooks:
+      - CI: runbooks/ci.md
+
+markdown_extensions:
+  - admonition
+  - toc:
+      permalink: true
+  - pymdownx.superfences
+
+# Many docs referenced by PRD.md land in later slices; don't fail the build on them.
+validation:
+  nav:
+    omitted_files: warn
+  links:
+    not_found: warn