docs(infra): tighten gitea-actions-gotchas, add local compose (refs #30)

Restructure for scannability: a shared root-cause intro, a quick-reference
table (gotcha → fix → where), and consistent Symptom/Why/Fix sections with
tighter prose. Documents infra/docker-compose.local.yml as the no-make/Windows
path and drops the now-stale "no bind mounts remain" line (the local compose
uses them, which is fine locally).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitea/workflows/ci.yaml

@@ -17,7 +17,7 @@ permissions:
 
 jobs:
   lint:
-    runs-on: respellion-linux
+    runs-on: ubuntu-latest
     steps:
       - uses: https://github.com/actions/checkout@v4
       - uses: https://github.com/actions/setup-dotnet@v4
@@ -26,7 +26,7 @@ jobs:
       - run: make lint
 
   build:
-    runs-on: respellion-linux
+    runs-on: ubuntu-latest
     steps:
       - uses: https://github.com/actions/checkout@v4
       - uses: https://github.com/actions/setup-dotnet@v4
@@ -35,7 +35,7 @@ jobs:
       - run: make build
 
   unit:
-    runs-on: respellion-linux
+    runs-on: ubuntu-latest
     steps:
       - uses: https://github.com/actions/checkout@v4
       - uses: https://github.com/actions/setup-dotnet@v4
@@ -44,7 +44,13 @@ jobs:
       - run: make unit
 
   compose-smoke:
-    runs-on: respellion-linux
+    runs-on: ubuntu-latest
     steps:
       - uses: https://github.com/actions/checkout@v4
       - run: make smoke
+      - name: dump container logs on failure
+        if: failure()
+        run: docker compose -f infra/docker-compose.yml logs --no-color --tail=80 oz-init openzaak nrc-init nrc-web flowable-init keycloak acl bff 2>&1 || true
+      - name: tear down on failure
+        if: failure()
+        run: docker compose -f infra/docker-compose.yml down --volumes 2>&1 || true

.gitignore

@@ -5,6 +5,9 @@ obj/
 [Rr]elease/
 *.user
 
+# Reqnroll-generated test code (regenerated from *.feature on build)
+*.feature.cs
+
 # Test results / coverage
 [Tt]est[Rr]esults/
 *.trx

Makefile

@@ -5,11 +5,33 @@
 # `make ci` locally runs exactly what the pipeline runs — no drift. Until a
 # self-hosted runner is registered, `make ci` is the gate (see docs/runbooks/ci.md).
 
-SLN        := services/bff/Bff.slnx
+SLN        := register-referentie.slnx
 COMPOSE    := infra/docker-compose.yml
-HEALTH_URL := http://localhost:8080/health
+# Long-running services with a healthcheck — the smoke polls these for readiness
-OZ_COMPOSE := infra/openzaak/docker-compose.yml
+# (infra/wait-healthy.sh). One-shot init jobs (oz-init, nrc-init, flowable-init)
-OZ_BASE    := http://localhost:8000
+# are not polled; they only need to have run. See docs/runbooks/gitea-actions-gotchas.md.
+WAIT_SVCS  := openzaak nrc-web acl bff
+# Config files (OpenZaak data.yaml, Keycloak realms, Flowable BPMN) are streamed
+# into external named volumes via `docker cp` (infra/seed-config.sh) instead of
+# bind-mounted, because bind mounts don't reach sibling containers on the
+# containerized CI runner. SEED populates them; run it before every `up`. The
+# volumes are `external`, so compose won't remove them — CFG_VOLS lists them for
+# explicit teardown. See docs/runbooks/gitea-actions-gotchas.md.
+SEED       := bash infra/seed-config.sh
+CFG_VOLS   := rr-oz-config rr-kc-realms rr-fl-bpmn
+# Local-only stack: same services but config is bind-mounted (no seed step), so a
+# plain `docker compose -f infra/docker-compose.local.yml up` works on any local
+# engine. This is the no-make / Windows-friendly path. See that file's header.
+LOCAL_COMPOSE := infra/docker-compose.local.yml
+OZ_COMPOSE  := infra/openzaak/docker-compose.yml
+OZ_BASE     := http://localhost:8000
+NRC_COMPOSE := infra/opennotificaties/docker-compose.yml
+NRC_BASE    := http://localhost:8001
+KC_COMPOSE  := infra/keycloak/docker-compose.yml
+KC_BASE     := http://localhost:8180
+FL_COMPOSE  := infra/flowable/docker-compose.yml
+FL_BASE     := http://localhost:8090/flowable-rest/service
+STACK_FILES := -f $(OZ_COMPOSE) -f $(NRC_COMPOSE)
 
 # On a rootless Podman dev box, point Docker CLI/Compose at the Podman socket —
 # but only if that socket exists and DOCKER_HOST isn't already set, so real
@@ -21,7 +43,7 @@ export DOCKER_HOST := unix://$(PODMAN_SOCK)
 endif
 endif
 
-.PHONY: ci lint build unit smoke down changelog openzaak-up openzaak-smoke openzaak-down help
+.PHONY: ci lint build unit smoke up down local local-down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down help
 
 ## ci: run the full pipeline — lint, build, unit, smoke (mirrors Gitea Actions)
 ci: lint build unit smoke
@@ -38,14 +60,38 @@ build:
 unit:
 	dotnet test $(SLN) -c Release
 
-## smoke: compose up (wait for healthy), curl /health, then tear down
+## smoke: seed config, bring the whole stack up, wait for health-checked services, tear down
+# SEED populates the external config volumes first (upstream images used verbatim;
+# only our acl/bff are built). `up -d --build` starts EVERYTHING. Readiness is
+# checked by infra/wait-healthy.sh polling the durable, health-checked services
+# ($(WAIT_SVCS)) via `docker inspect` — portable across docker compose and
+# podman-compose, and needing no `--wait` flag or host port access. The one-shots
+# (oz-init, flowable-init) aren't polled; they just need to have run.
 smoke:
-	docker compose -f $(COMPOSE) up -d --build --wait
+	$(SEED) oz kc fl
-	bash -c 'curl -fsS $(HEALTH_URL); rc=$$?; docker compose -f $(COMPOSE) down --volumes; exit $$rc'
+	docker compose -f $(COMPOSE) up -d --build
+	bash -c 'WAIT_TIMEOUT=420 bash infra/wait-healthy.sh $(WAIT_SVCS); rc=$$?; docker compose -f $(COMPOSE) down --volumes; docker volume rm -f $(CFG_VOLS) >/dev/null 2>&1; exit $$rc'
 
-## down: stop and remove the local stack
+## up: seed config volumes and start the full stack (use instead of bare
+## `docker compose up`, which can't self-seed the external config volumes)
+up:
+	$(SEED) oz kc fl
+	docker compose -f $(COMPOSE) up -d --build
+
+## down: stop and remove the local stack (incl. the external config volumes)
 down:
 	docker compose -f $(COMPOSE) down --volumes
+	-docker volume rm -f $(CFG_VOLS)
+
+## local: bring up the bind-mount stack (no seed step) and wait for health
+## (Windows / no-make users: run `docker compose -f infra/docker-compose.local.yml up -d --build` directly)
+local:
+	docker compose -f $(LOCAL_COMPOSE) up -d --build
+	WAIT_TIMEOUT=420 bash infra/wait-healthy.sh $(WAIT_SVCS)
+
+## local-down: stop and remove the bind-mount stack
+local-down:
+	docker compose -f $(LOCAL_COMPOSE) down --volumes
 
 ## changelog: regenerate CHANGELOG.md from Conventional Commits (git-cliff)
 changelog:
@@ -53,11 +99,11 @@ changelog:
 
 ## openzaak-up: start the OpenZaak stack (migrations run on first start)
 openzaak-up:
+	$(SEED) oz
 	docker compose -f $(OZ_COMPOSE) up -d
 
 ## openzaak-smoke: start OpenZaak, then assert it is up with auth enforced
-openzaak-smoke:
+openzaak-smoke: openzaak-up
-	docker compose -f $(OZ_COMPOSE) up -d
 	@bash -c 'set -e; \
 	  echo "waiting for OpenZaak to respond..."; \
 	  for i in $$(seq 1 60); do \
@@ -71,9 +117,75 @@ openzaak-smoke:
 	  echo "GET /zaken/api/v1/      -> $$root (expect 200)"; test "$$root" = "200"; \
 	  echo "OpenZaak smoke OK"'
 
+## openzaak-seed: bring OpenZaak up and seed the BIG catalogus (idempotent)
+openzaak-seed: openzaak-up
+	@bash -c 'for i in $$(seq 1 50); do \
+	    c=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/catalogi/api/v1/ || true); \
+	    [ "$$c" = "200" ] && break; sleep 3; done; echo "OpenZaak ready ($$c)"'
+	python3 infra/openzaak/seed_catalogus.py
+
 ## openzaak-down: stop and remove the OpenZaak stack (wipes data)
 openzaak-down:
 	docker compose -f $(OZ_COMPOSE) down --volumes
+	-docker volume rm -f rr-oz-config
+
+## stack-up: start OpenZaak + Open Notificaties together (shared network)
+stack-up:
+	$(SEED) oz
+	docker compose $(STACK_FILES) up -d
+
+## stack-smoke: start both, assert OpenZaak (403/302/200) and NRC (302) are reachable
+stack-smoke: stack-up
+	@bash -c 'set -e; \
+	  echo "waiting for OpenZaak + Open Notificaties..."; \
+	  for i in $$(seq 1 60); do \
+	    oz=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/admin/ || true); \
+	    nrc=$$(curl -s -o /dev/null -w "%{http_code}" $(NRC_BASE)/admin/ || true); \
+	    [ "$$oz" = "302" ] && [ "$$nrc" = "302" ] && break; sleep 3; done; \
+	  z=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/zaken/api/v1/zaken); \
+	  echo "OpenZaak /zaken (unauth) -> $$z (expect 403)"; test "$$z" = "403"; \
+	  echo "OpenZaak /admin/         -> $$oz (expect 302)"; test "$$oz" = "302"; \
+	  echo "Open Notificaties /admin/-> $$nrc (expect 302)"; test "$$nrc" = "302"; \
+	  echo "stack smoke OK"'
+
+## stack-down: stop and remove both stacks (wipes data)
+stack-down:
+	docker compose $(STACK_FILES) down --volumes
+	-docker volume rm -f rr-oz-config
+
+## keycloak-up: start Keycloak with the four imported realms
+keycloak-up:
+	$(SEED) kc
+	docker compose -f $(KC_COMPOSE) up -d
+
+## keycloak-smoke: start Keycloak, then verify each realm logs in + returns its claim
+keycloak-smoke: keycloak-up
+	@bash -c 'for i in $$(seq 1 60); do \
+	    c=$$(curl -s -o /dev/null -w "%{http_code}" $(KC_BASE)/realms/digid/.well-known/openid-configuration || true); \
+	    [ "$$c" = "200" ] && break; sleep 3; done; echo "Keycloak ready ($$c)"'
+	python3 infra/keycloak/check_realms.py
+
+## keycloak-down: stop and remove Keycloak
+keycloak-down:
+	docker compose -f $(KC_COMPOSE) down --volumes
+	-docker volume rm -f rr-kc-realms
+
+## flowable-up: start Flowable (deploys registratie.bpmn on boot)
+flowable-up:
+	$(SEED) fl
+	docker compose -f $(FL_COMPOSE) up -d
+
+## flowable-smoke: start Flowable, then verify a started instance waits on the external task
+flowable-smoke: flowable-up
+	@bash -c 'for i in $$(seq 1 80); do \
+	    c=$$(curl -s -o /dev/null -w "%{http_code}" -u rest-admin:test $(FL_BASE)/repository/process-definitions?key=registratie || true); \
+	    [ "$$c" = "200" ] && break; sleep 3; done; echo "Flowable ready ($$c)"'
+	python3 infra/flowable/verify.py
+
+## flowable-down: stop and remove Flowable
+flowable-down:
+	docker compose -f $(FL_COMPOSE) down --volumes
+	-docker volume rm -f rr-fl-bpmn
 
 ## help: list available targets
 help:

docs/architecture/adr-0002-catalogus-design.md

@@ -0,0 +1,53 @@
+# ADR-0002: BIG catalogus design and OpenZaak seeding
+
+- **Status:** Accepted
+- **Date:** 2026-06-03
+- **Deciders:** Respellion engineering
+- **Relates to:** S-01 (#2)
+
+## Context
+
+S-01 needs a reproducible `BIG` catalogus in OpenZaak with a **lean** `BIG-registratie`
+zaaktype (only schema-mandatory fields) plus a `bsn` eigenschap, and a JWT client that
+can list zaaktypen. We had to decide *how* to provision this idempotently at startup.
+
+Findings from the OpenZaak image (`openzaak/open-zaak:latest`):
+- `setup_configuration` (run by the init container) is declarative and idempotent, with
+  steps for **JWT secrets** and **applicaties** (`vng_api_common_credentials`,
+  `vng_api_common_applicaties`) — but **no step for catalogi/zaaktypen**.
+- Catalogus/zaaktype/eigenschap can only be created through the **ZTC REST API**.
+- Publishing a zaaktype requires ≥1 roltype, ≥1 resultaattype and ≥2 statustypen.
+
+## Decision
+
+1. **Provision the JWT client declaratively** via `infra/openzaak/setup_configuration/data.yaml`:
+   a `JWTSecret` (`big-reference-seed` / dev secret) and an `Applicatie` with
+   `heeft_alle_autorisaties: true`. Idempotent, runs in the init container.
+2. **Seed the catalogus/zaaktype/eigenschap via the ZTC API** with an idempotent,
+   stdlib-only script (`infra/openzaak/seed_catalogus.py`, `make openzaak-seed`). It mints
+   a ZGW JWT from the provisioned client and matches existing objects (by `domein` /
+   `identificatie` / `naam`, querying `status=alles` so concepts are seen) before creating.
+3. **Keep the zaaktype a CONCEPT (not published).** Publishing pulls in roltypen,
+   statustypen and resultaattypen, which go beyond "schema-mandatory"; those arrive with
+   the workflow/zaak slices that actually need a published type. Listing uses `status=alles`.
+4. **Disable outbound notifications** (`NOTIFICATIONS_DISABLED=true`) until Open Notificaties
+   (NRC) lands in S-01-c — otherwise every ZTC write 500s trying to notify.
+5. **Fixed dev values:** RSIN `517439943` (elfproef-valid test value); the JWT secret is
+   dev-only and documented as such.
+
+## Consequences
+
+- **Reproducible & version-robust:** the API-driven seed doesn't depend on fixture PKs or
+  a catalogi `setup_configuration` step that may change between versions.
+- **Teaches the pattern:** the seed talks to OpenZaak exactly the way the ACL will later —
+  through the documented ZGW API, with a JWT (ADR-0001).
+- The seed is a script, but a **data loader is explicitly anticipated** (PRD §8); it lives
+  under `infra/openzaak/`, not as ad-hoc tooling.
+- **Follow-ups:** re-enable notifications when NRC is up (S-01-c); publish the zaaktype (add
+  the related types) when a slice needs to create real zaken; pin the OpenZaak image tag.
+
+## Alternatives considered
+
+- **Fully declarative in `data.yaml`** — rejected: no catalogi/zaaktype step exists.
+- **Django `loaddata` fixture** — rejected: brittle, tied to model PKs and the exact image
+  version; bypasses the API the rest of the system uses.

docs/architecture/adr-0003-default-fill.md

@@ -0,0 +1,44 @@
+# ADR-0003: ACL default-fill strategy
+
+- **Status:** Accepted
+- **Date:** 2026-06-04
+- **Deciders:** Respellion engineering
+- **Relates to:** S-04 (#5); builds on ADR-0001 (loose coupling)
+
+## Context
+
+The ACL is the only code that talks to ZGW APIs (ADR-0001 / CLAUDE.md §8.1). When the
+domain asks it to "open a zaak", the domain payload is intentionally free of ZGW
+specifics — it carries domain facts (e.g. the registrant's BSN), not OpenZaak fields. But
+OpenZaak's `POST /zaken` requires ZGW-mandatory fields: `bronorganisatie`,
+`verantwoordelijkeOrganisatie`, `startdatum`, `vertrouwelijkheidaanduiding`, and a
+`zaaktype` URL. Something has to supply those, and it must not leak into the domain.
+
+## Decision
+
+**The ACL default-fills the ZGW-mandatory zaak fields; the domain never sees them.**
+
+- `bronorganisatie`, `verantwoordelijkeOrganisatie`, `vertrouwelijkheidaanduiding`, and the
+  `zaaktype` URL come from **ACL configuration** (`AclDefaults` options) — not hardcoded,
+  not from the domain. This keeps them operationally manageable (the beheer portal will
+  edit them in S-15) and environment-specific (the seeded BIG zaaktype URL differs per env).
+- `startdatum` is derived from an injected **clock** (today's date), so it is
+  deterministic in tests.
+- The mapping from domain payload → ZGW `ZaakRequest` lives entirely inside the ACL
+  (`Application` builds the request from payload + defaults; `Infrastructure` serialises and
+  POSTs it). No other service constructs ZGW payloads or URLs.
+
+## Consequences
+
+- **Positive:** the domain stays ZGW-agnostic; ZGW knowledge is in one named place; defaults
+  are config (testable, env-specific, later editable via the beheer portal).
+- **Cost:** the ACL must be configured per environment (the seeded zaaktype URL, the
+  organisation RSINs). Missing/invalid config fails fast at the ACL boundary.
+- **Follow-ups:** mapping the BSN onto the zaak (eigenschap/rol), status transitions, and
+  documents are explicitly out of scope for S-04 and get their own slices.
+
+## Alternatives considered
+
+- **Defaults in the domain payload** — rejected: leaks ZGW concerns into the domain,
+  violating ADR-0001.
+- **Hardcoded defaults in code** — rejected: not env-specific, not operationally editable.

docs/architecture/adr-0004-bdd-framework.md

@@ -0,0 +1,52 @@
+# ADR-0004: Reqnroll as the BDD acceptance framework
+
+- **Status:** Accepted
+- **Date:** 2026-06-04
+- **Deciders:** Respellion engineering
+- **Relates to:** S-04 (#5); supports CLAUDE.md §3 (BDD at the use-case level) and §11 (tests pyramid)
+
+## Context
+
+CLAUDE.md §11 mandates that each user-visible flow is driven by a Gherkin acceptance
+scenario living in `tests/acceptance/`, and §3 names "BDD at the use-case level" as a core
+engineering principle. The foundational slices (S-00…S-03) added no acceptance layer; S-04
+is the first slice with real domain behaviour to drive, so it is where the BDD framework is
+introduced. We need a .NET tool that:
+
+- parses Gherkin `.feature` files and binds steps to C#,
+- integrates with the existing xUnit test runner (the repo standardises on xUnit), so
+  acceptance tests run under the same `dotnet test` / `make ci` gate as everything else,
+- is actively maintained on modern .NET (we target net10.0).
+
+## Decision
+
+**Use [Reqnroll](https://reqnroll.net/) (`Reqnroll.xUnit`) for acceptance tests.**
+
+- Reqnroll is the actively-maintained, open-source successor to SpecFlow (which is no longer
+  maintained). It keeps the same Gherkin + `[Binding]` model, so the knowledge transfers.
+- `Reqnroll.xUnit` generates one xUnit test per scenario, so acceptance tests are discovered
+  and run by the same runner as the unit tests — no second test framework, no extra CI step.
+- Acceptance projects live under `tests/acceptance/` per the PRD §9 layout. Generated
+  `*.feature.cs` files are build artefacts and are git-ignored.
+
+## Consequences
+
+- **Positive:** one assertion/runner stack (xUnit) across unit and acceptance tests; scenarios
+  are written in business language (Dutch domain terms inline) and reviewed as the slice's
+  contract; maintained tooling on net10.0.
+- **Cost:** a new dependency (`Reqnroll.xUnit`) and its xUnit v2 transitive graph. Reqnroll
+  pulls `xunit.core` but not the assertion library, so the `xunit` metapackage is referenced
+  explicitly to get `Assert`.
+- **Replaceable by:** hand-written xUnit "scenario" tests with a Given/When/Then helper, at
+  the cost of losing Gherkin as the shared, readable contract — which is the whole point of §3.
+- **Follow-ups:** the real-OpenZaak integration test (Testcontainers) and the Stryker mutation
+  baseline for S-04 are tracked as their own issues split off #5.
+
+## Alternatives considered
+
+- **SpecFlow** — rejected: unmaintained and without an official net10.0 story; Reqnroll is its
+  drop-in successor.
+- **Plain xUnit Given/When/Then helpers** — rejected for user-visible flows: loses the
+  business-readable Gherkin contract that §3/§11 require. Still fine for unit-level tests.
+- **Xunit.Gherkin.Quick** — rejected: lighter but less featureful (no hooks/scoped contexts,
+  smaller community) than Reqnroll.

docs/runbooks/ci.md

@@ -1,11 +1,9 @@
 # CI runbook — Gitea Actions
 
-> **Status: no runner yet → run CI locally with `make ci`.** The workflow
+> **Status: active.** The workflow `.gitea/workflows/ci.yaml` runs on Gitea's
-> `.gitea/workflows/ci.yaml` is in place, but the pipeline cannot go green until a
+> hosted `ubuntu-latest` runner — no self-hosted runner required.
-> self-hosted `respellion-linux` runner is registered against the Gitea instance.
+> **`make ci` is still the local gate** — it runs the exact same checks
-> Until then, **`make ci` is the gate** — it runs the exact same checks locally
+> (the workflow calls the same `make` targets).
-> (the workflow calls the same `make` targets). Issue **#30 (S-00-c)** stays open
-> until CI is verified green on a runner.
 
 ## The pipeline
 
@@ -18,12 +16,40 @@ and CI cannot drift:
 | `lint` | `make lint` → `dotnet format … --verify-no-changes` | .NET 10 SDK |
 | `build` | `make build` → `dotnet build … -c Release` | .NET 10 SDK |
 | `unit` | `make unit` → `dotnet test … -c Release` | .NET 10 SDK |
-| `compose-smoke` | `make smoke` → compose up `--wait` → `curl /health` → `down` | container engine + compose v2 |
+| `compose-smoke` | `make smoke` → seed config volumes → `up -d` (full stack) → `up --wait` durable services → `down` | container engine + compose v2 |
 
 All `uses:` references are absolute, tag-pinned URLs (`https://github.com/actions/checkout@v4`,
 `https://github.com/actions/setup-dotnet@v4`) per CLAUDE.md §8.7 and §15 — Gitea
 Actions resolves them from GitHub.
 
+> **`compose-smoke` runs on a containerized runner.** Workspace bind mounts do
+> **not** reach the sibling containers Compose starts, so config/assets are
+> streamed into external named volumes via `docker cp` (`infra/seed-config.sh`),
+> and the upstream images are used verbatim (no build). If you add a service that
+> needs a repo file at runtime, seed it the same way — don't bind-mount it. Note:
+> bare `docker compose up` no longer self-seeds; use `make up`. See
+> [gitea-actions-gotchas.md](gitea-actions-gotchas.md).
+
+## Running the stack locally without `make` (Windows / Docker Desktop)
+
+`make` and the bash helpers assume a Unix shell. To bring the whole stack up on a
+machine without them (e.g. Windows + Docker Desktop), use the **local compose
+file**, which bind-mounts the config instead of seeding volumes — so it needs no
+`make`, no seed step, and no bash:
+
+```bash
+docker compose -f infra/docker-compose.local.yml up -d --build          # any engine
+docker compose -f infra/docker-compose.local.yml up -d --build --wait    # Docker Desktop (Compose v2)
+docker compose -f infra/docker-compose.local.yml down --volumes
+```
+
+On Linux/macOS the same thing is wrapped as `make local` / `make local-down`.
+
+`infra/docker-compose.local.yml` mirrors the canonical `infra/docker-compose.yml`
+but swaps the external config volumes for bind mounts — valid locally because a
+local daemon can see the working directory (the seed/volume dance only exists for
+the containerized CI runner). Keep the two files in sync.
+
 ## Running CI locally (`make ci`)
 
 Until the runner exists, run the full pipeline yourself before pushing:
@@ -49,56 +75,26 @@ The Makefile auto-points `DOCKER_HOST` at `/run/user/$(id -u)/podman/podman.sock
 when that socket exists and `DOCKER_HOST` is unset, so `make smoke` "just works"
 locally while leaving real Docker hosts / CI runners untouched.
 
-## Runner: `respellion-linux`
+## Runner: `ubuntu-latest`
 
-The single self-hosted runner label this repo targets is **`respellion-linux`**
+All jobs run on Gitea's hosted **`ubuntu-latest`** runner — no self-hosted runner
-(declared here per §15). It is intended to run **co-located on the Gitea server**
+setup is required. The hosted runner ships with Docker and Docker Compose v2, so
-(`git.labs.respellion.tech` / `46.224.220.37`) so CI is durable and independent of
+`make smoke` (`docker compose … up --wait`) works without extra configuration.
-any developer machine.
 
-### Host prerequisites
+If Gitea's hosted runners are unavailable and a self-hosted fallback is needed,
-
+register an `act_runner` with the `ubuntu-latest` label:
-The runner executes jobs in **host mode** (see registration below), so the host
-must have, on `PATH`:
-
-- .NET 10 SDK (or let `setup-dotnet` install it into the runner tool cache)
-- A container engine with Compose v2 — Docker, or Podman with the Docker-compatible
-  socket and the `docker-compose` provider (as configured on the dev box)
-- `curl`
-
-### Install & register `act_runner` (on the Gitea server)
 
 ```bash
-# 1. Install the binary (pick the version matching the Gitea release line)
 VER=0.2.11
 curl -fsSL -o /usr/local/bin/act_runner \
   "https://dl.gitea.com/act_runner/${VER}/act_runner-${VER}-linux-amd64"
 chmod +x /usr/local/bin/act_runner
 
-# 2. Obtain a registration token from the Gitea UI:
-#    Site Administration → Actions → Runners → "Create new Runner"  (instance-level)
-#    (or Repo → Settings → Actions → Runners for a repo-scoped runner)
-
-# 3. Register with the respellion-linux label in HOST execution mode.
-#    The ":host" suffix means jobs run directly on the host shell, so
-#    `docker compose` in compose-smoke uses the host engine (no docker-in-docker).
 act_runner register --no-interactive \
   --instance https://git.labs.respellion.tech \
   --token <REGISTRATION_TOKEN> \
   --name respellion-ci-1 \
-  --labels "respellion-linux:host"
+  --labels "ubuntu-latest:docker://node:20-bookworm"
 
-# 4. Run it (foreground to verify, then install as a systemd service)
 act_runner daemon
 ```
-
-Verify in the Gitea UI (Actions → Runners) that `respellion-ci-1` shows **Idle**,
-then re-run the `CI` workflow; all four jobs should pass.
-
-## Security note
-
-A self-hosted runner in **host mode** executes workflow code directly on the Gitea
-server host. Anyone who can push a workflow can run code there. This is acceptable
-for a **private lab** instance with trusted contributors. For anything
-internet-facing, switch to container/VM isolation (`--labels "respellion-linux:docker://..."`)
-or a dedicated runner host, and gate workflow runs on approval for outside PRs.

docs/runbooks/flowable.md

@@ -0,0 +1,40 @@
+# Flowable runbook
+
+Flowable (`infra/flowable/docker-compose.yml`) runs the **flowable-rest** engine on
+Postgres. The `workflows/registratie.bpmn` model is deployed via the REST API at boot by
+the `flowable-init` container. Host port **:8090**; REST API under
+`http://localhost:8090/flowable-rest/service/` (basic auth **rest-admin / test**, dev only).
+
+## The model — `registratie`
+
+A minimal "Registratie ontvangen" process: **start → external-worker task
+`OpenZaakAanmaken` → end**. The external task is where the Workflow Client / ACL will
+later create the zaak in OpenZaak (S-04/S-05); for now a started instance parks there.
+
+## Quick test (`make`)
+
+```bash
+make flowable-up      # start engine + deploy registratie.bpmn on boot
+make flowable-smoke   # start + verify a new instance waits on the external task
+make flowable-down    # stop + wipe
+```
+
+`make flowable-smoke` runs `infra/flowable/verify.py`, which:
+1. waits for the `registratie` process definition to be deployed,
+2. starts an instance and asserts it did **not** end immediately,
+3. asserts an execution is parked at activity **`OpenZaakAanmaken`**,
+4. deletes the test instance.
+
+## Notes
+
+- **Deploy on boot** is idempotent: `flowable-init` skips if a deployment named
+  `registratie` already exists (so restarts on the same volume don't pile up versions).
+- **Dev creds:** `rest-admin` / `test`. Override via the flowable-rest app config for
+  anything beyond local dev.
+- **Image** `flowable/flowable-rest:latest` — pin a tag when stabilising.
+- Start an instance by hand:
+  ```bash
+  curl -s -u rest-admin:test -H 'Content-Type: application/json' \
+    -d '{"processDefinitionKey":"registratie"}' \
+    http://localhost:8090/flowable-rest/service/runtime/process-instances
+  ```

docs/runbooks/gitea-actions-gotchas.md

@@ -0,0 +1,100 @@
+# Gitea Actions gotchas
+
+How our CI (Gitea Actions on the hosted **`ubuntu-latest`** runner) differs from a
+local run, and the workarounds in this repo. Referenced by `CLAUDE.md` §8.7/§15.
+
+**One root cause sits under most of this:** the runner executes the job **inside a
+container**, so when a step runs `docker compose up`, Compose starts the stack as
+**sibling containers** on the host's daemon. Anything that assumes the job and
+those containers share a filesystem — or a `localhost` — breaks.
+
+| Gotcha | Fix | Lives in |
+|---|---|---|
+| Bind-mounted config arrives empty | `docker cp` config into external volumes | `infra/seed-config.sh` |
+| `docker compose up --wait` is unsupported / flaky | poll health with `docker inspect` | `infra/wait-healthy.sh` |
+| `pg_isready` passes before PostGIS is ready | add a `PostGIS_Version()` probe | the db healthchecks |
+
+---
+
+## 1. Bind mounts don't reach the containers
+
+**Symptom** — green locally, but `compose-smoke` fails with:
+
+```
+oz-init-1 | CommandError: Yaml file `/app/setup_configuration/data.yaml` does not exist.
+```
+
+Migrations run fine; only the step that reads a *mounted* file fails. The same
+trap hits `nrc-init`, `flowable-init`, and `keycloak`.
+
+**Why** — a relative bind mount like `./openzaak/setup_configuration:/app/...` is
+resolved by Compose to a path *inside the job container*
+(`/workspace/.../setup_configuration`). The daemon then looks for that path on
+*its own host*, doesn't find it, and mounts an **empty directory**. (It works on a
+runner that executes jobs on the host — which is why moving to `ubuntu-latest`
+exposed it.)
+
+**Fix** — use the upstream images verbatim (no build) and stream config into
+**external named volumes** with `docker cp`, which copies over the Docker API and
+so works wherever the daemon runs. `infra/seed-config.sh` creates each volume,
+mounts it in a throwaway helper, and copies the files in:
+
+| Asset | Volume | Mounted at |
+|---|---|---|
+| OpenZaak `data.yaml` | `rr-oz-config` | `oz-init:/app/setup_configuration` |
+| Keycloak realms | `rr-kc-realms` | `keycloak:/opt/keycloak/data/import` |
+| `registratie.bpmn` | `rr-fl-bpmn` | `flowable-init:/work` |
+
+The volumes are `external: true` with fixed names, so they resolve identically
+under docker compose and podman-compose. `make` seeds before every `up`; `make
+down` removes them. (Open Notificaties needs nothing — `nrc-init` migrates only.)
+
+**Consequence — bare `docker compose up` can't self-seed external volumes:**
+
+- **CI / Linux / macOS:** `make up` or `make smoke` (seed, then start).
+- **No-make / Windows:** `infra/docker-compose.local.yml` — a twin stack that
+  **bind-mounts** the config instead. Bind mounts are fine *locally* because a
+  local daemon can see your working directory, so
+  `docker compose -f infra/docker-compose.local.yml up -d` just works.
+
+**Why not the obvious alternatives**
+
+- *Bake config into an image* (incl. an inline Dockerfile) — `docker compose up`
+  would then work unaided, but it's a build; we wanted the upstream images as-is.
+- *Compose `configs:` with inline `content`* — Compose writes a client-side temp
+  file and bind-mounts it, hitting the exact same problem.
+- *A host-executing runner* — bind mounts would work with zero seeding, but it
+  reintroduces a self-hosted runner and undoes the move to `ubuntu-latest`.
+
+---
+
+## 2. Readiness: poll health, don't use `--wait`
+
+`docker compose up --wait` looks ideal but fails us three ways:
+
+- **podman-compose doesn't implement it** (`unrecognized arguments: --wait`) — so
+  it would break local dev.
+- A project-wide `--wait` **treats a one-shot exiting `0` as a failure** unless
+  something `depends_on` it with `service_completed_successfully`. `flowable-init`
+  deploys the BPMN and exits with no dependant, so `--wait` fails the moment it
+  does — last line `container infra-flowable-init-1 exited (0)`.
+- The containerized runner **can't reach published host ports**, so an external
+  `curl localhost:8080/health` can't work either.
+
+**Fix** — `infra/wait-healthy.sh` polls each durable service (`openzaak nrc-web
+acl bff`, listed as `WAIT_SVCS` in the `Makefile`) with `docker ps` + `docker
+inspect '{{.State.Health.Status}}'` until it reports `healthy`. It uses only
+primitives both runtimes support, reads the **in-container** healthcheck (no host
+port needed), and ignores the one-shots (they only need to have run).
+`WAIT_TIMEOUT` defaults to 420 s — enough for the cold OpenZaak migrate (~90 s)
+plus app start.
+
+---
+
+## 3. `pg_isready` passes before PostGIS is ready
+
+`pg_isready` succeeds as soon as the TCP port is open — *before* the
+`postgis/postgis` image has finished running `CREATE EXTENSION postgis`. An init
+container that starts migrating in that window can fail on a missing PostGIS. So
+the db healthchecks add a `SELECT PostGIS_Version()` probe, making dependents wait
+for the extension, not just the port.

docs/runbooks/keycloak.md

@@ -0,0 +1,37 @@
+# Keycloak runbook
+
+Keycloak (`infra/keycloak/docker-compose.yml`) runs in dev mode with four realms
+imported at boot from `infra/keycloak/realms/`: **digid**, **eherkenning**, **eidas**,
+**medewerker**. It mocks the Dutch identity brokers so portals can do real OIDC logins
+locally. Host port **:8180**.
+
+## Quick test (`make`)
+
+```bash
+make keycloak-up      # start Keycloak + import realms (~30-60s first boot)
+make keycloak-smoke   # start + verify every realm logs in and returns its claim
+make keycloak-down    # stop + wipe
+```
+
+`make keycloak-smoke` runs `infra/keycloak/check_realms.py`, which does a password-grant
+login per realm and asserts the identifying claim:
+
+| Realm | User | Claim asserted |
+|---|---|---|
+| digid | jan-burger | `bsn` |
+| eherkenning | acme-ondernemer | `kvk` |
+| eidas | pierre-dupont | `eidas_id` |
+| medewerker | merel-behandelaar | role `behandelaar` |
+
+All test users / credentials are in [../synthetic-data.md](../synthetic-data.md).
+
+## Notes
+
+- **Admin console:** <http://localhost:8180/> — `admin` / `admin` (dev only).
+- **Client `big-portal`** is public with `standardFlowEnabled` (browser redirect login)
+  *and* `directAccessGrantsEnabled` (password grant, used by the smoke test).
+- **Dev store:** in-memory H2 via `start-dev`; realms re-import on each boot, so changes
+  made in the admin UI don't persist. Edit the realm JSONs to make durable changes.
+- **Image** pinned to `quay.io/keycloak/keycloak:26.1`.
+- Claims are injected by OIDC protocol mappers on `big-portal` (user attribute → token
+  claim); `medewerker` roles come through `realm_access.roles`.

docs/runbooks/opennotificaties.md

@@ -0,0 +1,44 @@
+# Open Notificaties (NRC) runbook
+
+The Open Notificaties stack (`infra/opennotificaties/docker-compose.yml`) is a lean
+adaptation of the upstream dev compose: PostGIS db, redis (also the Celery broker), a
+one-shot migrate-init, the API, and a celery worker. It shares the **`cg`** Docker
+network with the OpenZaak stack so the two can reach each other by service name.
+
+NRC is published on host **:8001** (OpenZaak holds :8000).
+
+## Quick test (`make`) — both platforms together
+
+```bash
+make stack-up      # OpenZaak + Open Notificaties on the shared network
+make stack-smoke   # start both + assert reachable (OZ 403/302/200, NRC 302)
+make stack-down    # stop + wipe both
+```
+
+`make stack-smoke` runs `docker compose -f infra/openzaak/... -f infra/opennotificaties/... up -d`
+and asserts:
+
+| Check | Expected |
+|---|---|
+| OpenZaak `GET /zaken/api/v1/zaken` (no JWT) | 403 (auth enforced) |
+| OpenZaak `GET /admin/` | 302 |
+| Open Notificaties `GET /admin/` | 302 |
+
+NRC admin UI: <http://localhost:8001/admin/> (dev superuser **admin / admin**).
+
+## Notification wiring is deferred to S-06
+
+Both platforms are **up and reachable**, but OpenZaak→NRC notification *delivery* is not
+wired yet, and OpenZaak still runs with `NOTIFICATIONS_DISABLED=true`. The bidirectional
+auth wiring (NRC `setup_configuration`: Services + Authorization to OpenZaak's
+Autorisaties API + JWT secrets + Kanalen + Abonnementen; OpenZaak's NotificationConfig)
+lands with **S-06 (Event Subscriber)** — the slice that actually consumes events. NRC's
+`setup_configuration/data.yaml` is intentionally minimal (migrations only) until then.
+
+This matches S-01's acceptance, which asks only that the platforms *come up in compose*
+and a health check confirms them reachable.
+
+## Prerequisites
+
+Same rootless-Podman setup as the rest of the repo — see [ci.md](ci.md) and
+[openzaak.md](openzaak.md). `systemctl --user start podman.socket` once per session.

docs/runbooks/openzaak.md

@@ -9,9 +9,32 @@ migrations, the OpenZaak API, and a celery worker.
 ```bash
 make openzaak-up       # start the stack (first run pulls images + migrates: 1-3 min)
 make openzaak-smoke    # start + assert it's up with auth enforced (403/302/200)
+make openzaak-seed     # start + seed the BIG catalogus (idempotent)
 make openzaak-down     # stop and wipe data
 ```
 
+## Seed the BIG catalogus
+
+`make openzaak-seed` brings the stack up and runs `infra/openzaak/seed_catalogus.py`,
+which creates (idempotently, via the ZTC API):
+
+- catalogus **BIG**
+- a lean **BIG-REGISTRATIE** zaaktype (concept; only schema-mandatory fields)
+- a **bsn** eigenschap on it
+
+then confirms the JWT client can list it. See **ADR-0002** for the design (why the
+zaaktype stays a concept, why notifications are disabled, why the API not a fixture).
+
+**JWT client** (provisioned declaratively by `setup_configuration/data.yaml`, **dev only**):
+
+| | |
+|---|---|
+| client_id | `big-reference-seed` |
+| secret | `insecure-dev-secret-change-me` |
+| authorizations | `heeft_alle_autorisaties` (all) |
+
+The seed mints a ZGW JWT (HS256) from these and calls `/catalogi/api/v1/...`.
+
 `make openzaak-smoke` polls until the API responds, then asserts:
 
 | Check | Expected |
@@ -43,8 +66,17 @@ The Makefile auto-points `DOCKER_HOST` at the Podman socket when it exists, so t
 - **Not in `make ci`.** The OpenZaak smoke is a separate, heavier check (large image
   pull + migrations); it is intentionally kept out of `make ci` so the core gate
   stays fast. Run `make openzaak-smoke` when you touch the OpenZaak stack.
-- **No catalogus/zaaktypen yet.** Seeding the `BIG` catalogus + `BIG-registratie`
+- **Notifications disabled.** `NOTIFICATIONS_DISABLED=true` — otherwise ZTC writes 500
-  zaaktype and a JWT client is the next slice (**S-01-b**); authenticated zaaktype
+  trying to notify. Open Notificaties is now up (see [opennotificaties.md](opennotificaties.md)),
-  listing isn't testable until then.
+  but OZ→NRC delivery wiring + re-enabling lands with **S-06**.
-- **Image tag.** Currently `openzaak/open-zaak:latest` via `${OPENZAAK_TAG}`; pin to
+- **Zaaktype is a concept**, not published (publishing needs roltypen/statustypen/
-  a known-good tag as part of the catalogus-design ADR.
+  resultaattypen — beyond the lean seed). List with `?status=alles`.
+- **Image tag.** Pinned to `openzaak/open-zaak:1.28.2` via `${OPENZAAK_TAG}` (bump
+  deliberately, not via `:latest`).
+- **Config arrives via a volume, not a bind mount.** `setup_configuration/data.yaml`
+  is streamed into the external `rr-oz-config` volume by `infra/seed-config.sh`
+  (`docker cp`) and mounted at `/app/setup_configuration`, so the init container
+  finds it on Gitea's containerized CI runner too (bind mounts don't reach sibling
+  containers there). The image is the upstream `openzaak/open-zaak` verbatim — no
+  build. Run via `make openzaak-up` (seeds first). See
+  [gitea-actions-gotchas.md](gitea-actions-gotchas.md).

docs/synthetic-data.md

@@ -0,0 +1,35 @@
+# Synthetic data
+
+All credentials here are **dev-only** synthetic test data — never real personal data,
+never used outside local development.
+
+## Keycloak realms (S-02)
+
+Keycloak runs at <http://localhost:8180> (admin console: **admin / admin**). Four realms
+are imported at boot from `infra/keycloak/realms/`. Each has a public OIDC client
+**`big-portal`** (standard flow + direct access grants enabled, redirect URIs `*` for dev).
+
+All test users share the password **`test123`**.
+
+| Realm | Mimics | User | Identifying claim |
+|---|---|---|---|
+| `digid` | DigiD (burgers) | `jan-burger` | `bsn` = `123456782` |
+| `eherkenning` | eHerkenning (bedrijven) | `acme-ondernemer` | `kvk` = `12345678` |
+| `eidas` | eIDAS (EU) | `pierre-dupont` | `eidas_id` = `FR/NL/AB-1234-5678` |
+| `medewerker` | Internal staff | `merel-behandelaar` | role `behandelaar` |
+| `medewerker` | Internal staff | `tom-teamlead` | roles `behandelaar`, `teamlead` |
+
+The identifying claims are injected via OIDC protocol mappers on `big-portal`
+(user-attribute → token claim); `medewerker` roles appear in `realm_access.roles`.
+
+## Get a token (for testing)
+
+```bash
+curl -s -X POST \
+  http://localhost:8180/realms/digid/protocol/openid-connect/token \
+  -d grant_type=password -d client_id=big-portal \
+  -d username=jan-burger -d password=test123 -d scope=openid | jq -r .access_token
+```
+
+Decode the JWT payload to see the `bsn` claim. `make keycloak-smoke` checks every realm
+automatically.

infra/docker-compose.local.yml

@@ -0,0 +1,296 @@
+# LOCAL development stack — runs with a plain `docker compose up`, no make / no
+# seed step / no bash. Use this on a local engine (Docker Desktop on Windows or
+# macOS, or rootless Podman on Linux).
+#
+#   docker compose -f infra/docker-compose.local.yml up -d --build         # podman
+#   docker compose -f infra/docker-compose.local.yml up -d --build --wait  # Docker Desktop
+#   docker compose -f infra/docker-compose.local.yml down --volumes
+#
+# It is identical to infra/docker-compose.yml EXCEPT that the three config inputs
+# (OpenZaak data.yaml, Keycloak realms, Flowable BPMN) are **bind-mounted** from
+# the repo instead of being streamed into external volumes by infra/seed-config.sh.
+# Bind mounts work here because a local daemon can see your working directory —
+# the seed dance only exists for the containerized CI runner, where it can't. See
+# docs/runbooks/gitea-actions-gotchas.md.
+#
+# `infra/docker-compose.yml` remains the CI-canonical stack; keep the two in sync.
+#
+# Port map (host):
+#   8000 OpenZaak · 8001 Open Notificaties · 8080 BFF · 8090 Flowable REST
+#   8100 ACL · 8180 Keycloak   (all admin: admin / admin — dev only)
+
+services:
+
+  # ── OpenZaak (S-01) ──────────────────────────────────────────────────────
+  oz-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: openzaak
+      POSTGRES_PASSWORD: openzaak
+      POSTGRES_DB: openzaak
+    command: postgres -c max_connections=300
+    volumes:
+      - oz-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U openzaak -d openzaak && psql -U openzaak -d openzaak -c 'SELECT PostGIS_Version();' -q 2>/dev/null"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 15s
+    networks: [cg]
+
+  oz-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  oz-init:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: &oz-env
+      DJANGO_SETTINGS_MODULE: openzaak.conf.docker
+      SECRET_KEY: ${OZ_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: oz-db
+      DB_NAME: openzaak
+      DB_USER: openzaak
+      DB_PASSWORD: openzaak
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: oz-redis:6379/0
+      CACHE_AXES: oz-redis:6379/0
+      CELERY_BROKER_URL: redis://oz-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://oz-redis:6379/1
+      DISABLE_2FA: "true"
+      NOTIFICATIONS_DISABLED: "true"
+      OPENZAAK_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENZAAK_SUPERUSER_EMAIL: admin@localhost
+      RUN_SETUP_CONFIG: "true"
+    command: /setup_configuration.sh
+    # Bind mount (`:z` relabels for SELinux on Linux; a no-op on Docker Desktop).
+    volumes:
+      - ./openzaak/setup_configuration:/app/setup_configuration:ro,z
+    depends_on:
+      oz-db:
+        condition: service_healthy
+      oz-redis:
+        condition: service_started
+    networks: [cg]
+
+  openzaak:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: *oz-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8000:8000"
+    depends_on:
+      oz-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  oz-celery:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: *oz-env
+    command: /celery_worker.sh
+    depends_on:
+      oz-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  # ── Open Notificaties / NRC (S-01-c) ─────────────────────────────────────
+  nrc-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: opennotificaties
+      POSTGRES_PASSWORD: opennotificaties
+      POSTGRES_DB: opennotificaties
+    command: postgres -c max_connections=300
+    volumes:
+      - nrc-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U opennotificaties -d opennotificaties"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  nrc-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  nrc-init:
+    # Migrations only (see the canonical compose / ADR-0002); no config needed.
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: &nrc-env
+      DJANGO_SETTINGS_MODULE: nrc.conf.docker
+      SECRET_KEY: ${NRC_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: nrc-db
+      DB_NAME: opennotificaties
+      DB_USER: opennotificaties
+      DB_PASSWORD: opennotificaties
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: nrc-redis:6379/0
+      CACHE_AXES: nrc-redis:6379/0
+      CELERY_BROKER_URL: redis://nrc-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://nrc-redis:6379/1
+      DISABLE_2FA: "true"
+      OPENNOTIFICATIES_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENNOTIFICATIES_SUPERUSER_EMAIL: admin@localhost
+    command: ["sh", "-c", "/wait_for_db.sh && OTEL_SDK_DISABLED=True python src/manage.py migrate"]
+    depends_on:
+      nrc-db:
+        condition: service_healthy
+      nrc-redis:
+        condition: service_started
+      openzaak:
+        condition: service_healthy
+    networks: [cg]
+
+  nrc-web:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: *nrc-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8001:8000"
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  nrc-celery:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: *nrc-env
+    command: /celery_worker.sh
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  # ── Keycloak (S-02) ──────────────────────────────────────────────────────
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.1
+    command: ["start-dev", "--import-realm"]
+    environment:
+      KC_BOOTSTRAP_ADMIN_USERNAME: admin
+      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HEALTH_ENABLED: "true"
+      KC_HTTP_ENABLED: "true"
+    ports:
+      - "8180:8080"
+    volumes:
+      - ./keycloak/realms:/opt/keycloak/data/import:ro,z
+    networks: [cg]
+
+  # ── Flowable (S-03) ──────────────────────────────────────────────────────
+  flowable-db:
+    image: docker.io/library/postgres:16
+    environment:
+      POSTGRES_USER: flowable
+      POSTGRES_PASSWORD: flowable
+      POSTGRES_DB: flowable
+    volumes:
+      - flowable-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U flowable -d flowable"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  flowable-rest:
+    image: docker.io/flowable/flowable-rest:latest
+    environment:
+      SPRING_DATASOURCE_DRIVER-CLASS-NAME: org.postgresql.Driver
+      SPRING_DATASOURCE_URL: jdbc:postgresql://flowable-db:5432/flowable
+      SPRING_DATASOURCE_USERNAME: flowable
+      SPRING_DATASOURCE_PASSWORD: flowable
+    ports:
+      - "8090:8080"
+    depends_on:
+      flowable-db:
+        condition: service_healthy
+    networks: [cg]
+
+  flowable-init:
+    image: docker.io/curlimages/curl:latest
+    restart: "no"
+    volumes:
+      - ../workflows/registratie.bpmn:/work/registratie.bpmn:ro,z
+    command:
+      - sh
+      - -c
+      - |
+        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+        fi
+    depends_on:
+      flowable-rest:
+        condition: service_started
+    networks: [cg]
+
+  # ── ACL ──────────────────────────────────────────────────────────────────
+  acl:
+    build:
+      context: ../services/acl
+      dockerfile: Dockerfile
+    image: register-referentie/acl:dev
+    environment:
+      Acl__OpenZaak__BaseUrl: http://openzaak:8000/
+      Acl__OpenZaak__ClientId: big-reference-seed
+      Acl__OpenZaak__Secret: insecure-dev-secret-change-me
+      Acl__Defaults__Bronorganisatie: "517439943"
+      Acl__Defaults__VerantwoordelijkeOrganisatie: "517439943"
+      Acl__Defaults__Vertrouwelijkheidaanduiding: openbaar
+      Acl__Defaults__ZaaktypeUrl: ${ACL_ZAAKTYPE_URL:-http://openzaak:8000/catalogi/api/v1/zaaktypen/00000000-0000-0000-0000-000000000000}
+    ports:
+      - "8100:8080"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      openzaak:
+        condition: service_healthy
+    networks: [cg]
+
+  # ── BFF ──────────────────────────────────────────────────────────────────
+  bff:
+    build:
+      context: ../services/bff
+      dockerfile: Dockerfile
+    image: register-referentie/bff:dev
+    ports:
+      - "8080:8080"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    networks: [cg]
+
+volumes:
+  oz-db:
+  nrc-db:
+  flowable-db:
+
+networks:
+  cg:

infra/docker-compose.yml

@@ -1,9 +1,289 @@
-# Local development stack. Grows service-by-service with each slice.
+# Development stack — boots all infra services plus the ACL and BFF.
-# S-00-b: the placeholder BFF with a /health check.
+#
+# Consolidates infra/openzaak/, infra/opennotificaties/, infra/keycloak/,
+# and infra/flowable/ and adds the ACL and BFF services.
+#
+# Port map (host):
+#   8000  OpenZaak ZGW API  (admin: admin / admin)
+#   8001  Open Notificaties (admin: admin / admin)
+#   8080  BFF               GET /health → Healthy
+#   8090  Flowable REST     http://localhost:8090/flowable-rest/service/
+#   8100  ACL               GET /health → Healthy  POST /zaken
+#   8180  Keycloak          (admin: admin / admin)
 #
 #   docker compose -f infra/docker-compose.yml up -d --build --wait
-#   curl http://localhost:8080/health   # -> Healthy
+#
+# After first boot, seed the BIG catalogus and note the zaaktype URL:
+#   python infra/openzaak/seed_catalogus.py
+# Then set ACL_ZAAKTYPE_URL in a .env file or your shell and re-up the acl
+# service:
+#   export ACL_ZAAKTYPE_URL=http://openzaak:8000/catalogi/api/v1/zaaktypen/<uuid>
+#   docker compose -f infra/docker-compose.yml up -d acl
+
 services:
+
+  # ── OpenZaak (S-01) ──────────────────────────────────────────────────────
+  oz-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: openzaak
+      POSTGRES_PASSWORD: openzaak
+      POSTGRES_DB: openzaak
+    command: postgres -c max_connections=300
+    volumes:
+      - oz-db:/var/lib/postgresql/data
+    healthcheck:
+      # pg_isready only checks TCP; the second clause verifies PostGIS is installed
+      # so oz-init migrations can safely start (avoids race on cold container start).
+      test: ["CMD-SHELL", "pg_isready -U openzaak -d openzaak && psql -U openzaak -d openzaak -c 'SELECT PostGIS_Version();' -q 2>/dev/null"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 15s
+    networks: [cg]
+
+  oz-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  oz-init:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: &oz-env
+      DJANGO_SETTINGS_MODULE: openzaak.conf.docker
+      SECRET_KEY: ${OZ_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: oz-db
+      DB_NAME: openzaak
+      DB_USER: openzaak
+      DB_PASSWORD: openzaak
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: oz-redis:6379/0
+      CACHE_AXES: oz-redis:6379/0
+      CELERY_BROKER_URL: redis://oz-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://oz-redis:6379/1
+      DISABLE_2FA: "true"
+      NOTIFICATIONS_DISABLED: "true"
+      OPENZAAK_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENZAAK_SUPERUSER_EMAIL: admin@localhost
+      RUN_SETUP_CONFIG: "true"
+    command: /setup_configuration.sh
+    # data.yaml is streamed into this external volume by infra/seed-config.sh
+    # before start (bind mounts don't reach sibling containers on the CI runner).
+    volumes:
+      - oz-config:/app/setup_configuration:ro
+    depends_on:
+      oz-db:
+        condition: service_healthy
+      oz-redis:
+        condition: service_started
+    networks: [cg]
+
+  openzaak:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: *oz-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8000:8000"
+    depends_on:
+      oz-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  oz-celery:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
+    environment: *oz-env
+    command: /celery_worker.sh
+    depends_on:
+      oz-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  # ── Open Notificaties / NRC (S-01-c) ─────────────────────────────────────
+  nrc-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: opennotificaties
+      POSTGRES_PASSWORD: opennotificaties
+      POSTGRES_DB: opennotificaties
+    command: postgres -c max_connections=300
+    volumes:
+      - nrc-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U opennotificaties -d opennotificaties"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  nrc-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  nrc-init:
+    # Plain base image — nrc-init runs migrations only (see command below), so it
+    # needs no baked config.
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: &nrc-env
+      DJANGO_SETTINGS_MODULE: nrc.conf.docker
+      SECRET_KEY: ${NRC_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: nrc-db
+      DB_NAME: opennotificaties
+      DB_USER: opennotificaties
+      DB_PASSWORD: opennotificaties
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: nrc-redis:6379/0
+      CACHE_AXES: nrc-redis:6379/0
+      CELERY_BROKER_URL: redis://nrc-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://nrc-redis:6379/1
+      DISABLE_2FA: "true"
+      OPENNOTIFICATIES_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENNOTIFICATIES_SUPERUSER_EMAIL: admin@localhost
+    # Migrations only for now. No setup_configuration steps are enabled yet (the
+    # OZ<->NRC notification wiring lands in S-06), and NRC's `setup_configuration`
+    # aborts with "No steps enabled" on the empty data.yaml — so we run `migrate`
+    # directly instead of /setup_configuration.sh. See data.yaml and ADR-0002.
+    command: ["sh", "-c", "/wait_for_db.sh && OTEL_SDK_DISABLED=True python src/manage.py migrate"]
+    depends_on:
+      nrc-db:
+        condition: service_healthy
+      nrc-redis:
+        condition: service_started
+      openzaak:
+        condition: service_healthy
+    networks: [cg]
+
+  nrc-web:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: *nrc-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8001:8000"
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  nrc-celery:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: *nrc-env
+    command: /celery_worker.sh
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  # ── Keycloak (S-02) ──────────────────────────────────────────────────────
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.1
+    command: ["start-dev", "--import-realm"]
+    environment:
+      KC_BOOTSTRAP_ADMIN_USERNAME: admin
+      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HEALTH_ENABLED: "true"
+      KC_HTTP_ENABLED: "true"
+    ports:
+      - "8180:8080"
+    # realm exports are streamed into this external volume by infra/seed-config.sh.
+    volumes:
+      - kc-realms:/opt/keycloak/data/import:ro
+    networks: [cg]
+
+  # ── Flowable (S-03) ──────────────────────────────────────────────────────
+  flowable-db:
+    image: docker.io/library/postgres:16
+    environment:
+      POSTGRES_USER: flowable
+      POSTGRES_PASSWORD: flowable
+      POSTGRES_DB: flowable
+    volumes:
+      - flowable-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U flowable -d flowable"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  flowable-rest:
+    image: docker.io/flowable/flowable-rest:latest
+    environment:
+      SPRING_DATASOURCE_DRIVER-CLASS-NAME: org.postgresql.Driver
+      SPRING_DATASOURCE_URL: jdbc:postgresql://flowable-db:5432/flowable
+      SPRING_DATASOURCE_USERNAME: flowable
+      SPRING_DATASOURCE_PASSWORD: flowable
+    ports:
+      - "8090:8080"
+    depends_on:
+      flowable-db:
+        condition: service_healthy
+    networks: [cg]
+
+  flowable-init:
+    image: docker.io/curlimages/curl:latest
+    restart: "no"
+    # registratie.bpmn is streamed into this external volume by infra/seed-config.sh.
+    volumes:
+      - fl-bpmn:/work:ro
+    command:
+      - sh
+      - -c
+      - |
+        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+        fi
+    depends_on:
+      flowable-rest:
+        condition: service_started
+    networks: [cg]
+
+  # ── ACL ──────────────────────────────────────────────────────────────────
+  acl:
+    build:
+      context: ../services/acl
+      dockerfile: Dockerfile
+    image: register-referentie/acl:dev
+    environment:
+      Acl__OpenZaak__BaseUrl: http://openzaak:8000/
+      Acl__OpenZaak__ClientId: big-reference-seed
+      Acl__OpenZaak__Secret: insecure-dev-secret-change-me
+      Acl__Defaults__Bronorganisatie: "517439943"
+      Acl__Defaults__VerantwoordelijkeOrganisatie: "517439943"
+      Acl__Defaults__Vertrouwelijkheidaanduiding: openbaar
+      # Override with the real zaaktype URL after running seed_catalogus.py.
+      Acl__Defaults__ZaaktypeUrl: ${ACL_ZAAKTYPE_URL:-http://openzaak:8000/catalogi/api/v1/zaaktypen/00000000-0000-0000-0000-000000000000}
+    ports:
+      - "8100:8080"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      openzaak:
+        condition: service_healthy
+    networks: [cg]
+
+  # ── BFF ──────────────────────────────────────────────────────────────────
   bff:
     build:
       context: ../services/bff
@@ -17,3 +297,24 @@ services:
       timeout: 3s
       retries: 5
       start_period: 10s
+    networks: [cg]
+
+volumes:
+  oz-db:
+  nrc-db:
+  flowable-db:
+  # Config volumes — created and populated out-of-band by infra/seed-config.sh
+  # (docker cp), because bind mounts don't reach sibling containers on the CI
+  # runner. `external` keeps the names deterministic; the seed step manages them.
+  oz-config:
+    external: true
+    name: rr-oz-config
+  kc-realms:
+    external: true
+    name: rr-kc-realms
+  fl-bpmn:
+    external: true
+    name: rr-fl-bpmn
+
+networks:
+  cg:

infra/flowable/docker-compose.yml

@@ -0,0 +1,70 @@
+# Flowable (S-03): the flowable-rest engine on Postgres.
+# The registratie.bpmn model is deployed via the REST API on startup by flowable-init.
+#
+#   docker compose -f infra/flowable/docker-compose.yml up -d
+#   # REST API (basic auth) under http://localhost:8090/flowable-rest/service/
+#
+# Host port 8090 (8000/8001/8080/8180 are taken by OpenZaak/NRC/BFF/Keycloak).
+services:
+  flowable-db:
+    image: docker.io/library/postgres:16
+    environment:
+      POSTGRES_USER: flowable
+      POSTGRES_PASSWORD: flowable
+      POSTGRES_DB: flowable
+    volumes:
+      - flowable-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U flowable -d flowable"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  flowable-rest:
+    image: docker.io/flowable/flowable-rest:latest
+    environment:
+      SPRING_DATASOURCE_DRIVER-CLASS-NAME: org.postgresql.Driver
+      SPRING_DATASOURCE_URL: jdbc:postgresql://flowable-db:5432/flowable
+      SPRING_DATASOURCE_USERNAME: flowable
+      SPRING_DATASOURCE_PASSWORD: flowable
+    ports:
+      - "8090:8080"
+    depends_on:
+      flowable-db:
+        condition: service_healthy
+    networks: [cg]
+
+  # Deploys workflows/registratie.bpmn via the REST API once flowable-rest is up.
+  # Idempotent: skips if a deployment named "registratie" already exists.
+  flowable-init:
+    image: docker.io/curlimages/curl:latest
+    restart: "no"
+    # registratie.bpmn is streamed into this external volume by infra/seed-config.sh.
+    volumes:
+      - fl-bpmn:/work:ro
+    command:
+      - sh
+      - -c
+      - |
+        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+        fi
+    depends_on:
+      flowable-rest:
+        condition: service_started
+    networks: [cg]
+
+volumes:
+  flowable-db:
+  # populated out-of-band by infra/seed-config.sh (docker cp) — see that script.
+  fl-bpmn:
+    external: true
+    name: rr-fl-bpmn
+
+networks:
+  cg:

infra/flowable/verify.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Smoke-check Flowable: the registratie process is deployed, and starting an
+instance parks it on the OpenZaakAanmaken external task. Stdlib only.
+"""
+import base64, json, sys, time, urllib.error, urllib.request
+
+BASE = "http://localhost:8090/flowable-rest/service"
+AUTH = "Basic " + base64.b64encode(b"rest-admin:test").decode()
+
+
+def call(method, path, payload=None):
+    data = json.dumps(payload).encode() if payload is not None else None
+    req = urllib.request.Request(BASE + path, data=data, method=method, headers={
+        "Authorization": AUTH, "Content-Type": "application/json", "Accept": "application/json"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        return r.status, json.loads(r.read() or "null")
+
+
+def main():
+    # 1. process definition deployed? (wait for the async init-container deploy)
+    defs = {"total": 0}
+    for _ in range(40):
+        _, defs = call("GET", "/repository/process-definitions?key=registratie")
+        if defs["total"] >= 1:
+            break
+        time.sleep(3)
+    assert defs["total"] >= 1, "registratie process definition not deployed"
+    print(f"process definition 'registratie' deployed (total={defs['total']})")
+
+    # 2. start an instance
+    st, pi = call("POST", "/runtime/process-instances", {"processDefinitionKey": "registratie"})
+    assert st == 201, f"start failed: {st} {pi}"
+    pid = pi["id"]
+    assert pi.get("ended") is False, "instance ended immediately — external task not reached"
+    print(f"started instance {pid} (ended={pi.get('ended')})")
+
+    # 3. waiting on the external task?
+    _, ex = call("GET", f"/runtime/executions?processInstanceId={pid}")
+    activities = [e.get("activityId") for e in ex["data"]]
+    assert "OpenZaakAanmaken" in activities, f"not waiting at OpenZaakAanmaken: {activities}"
+    print(f"instance is waiting at the external task: {activities}")
+
+    # 4. cleanup
+    try:
+        call("DELETE", f"/runtime/process-instances/{pid}")
+        print("cleaned up instance")
+    except urllib.error.HTTPError:
+        pass
+
+    print("flowable smoke OK")
+
+
+if __name__ == "__main__":
+    main()

infra/keycloak/check_realms.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Smoke-check the Keycloak realms: each realm's OIDC login works (password grant)
+and returns its expected identifying claim. Stdlib only. Exits non-zero on failure.
+"""
+import base64, json, sys, urllib.error, urllib.parse, urllib.request
+
+BASE = "http://localhost:8180"
+CLIENT = "big-portal"
+PWD = "test123"
+
+# realm, user, claim ("__roles__" => check realm_access.roles), expected-contains
+CHECKS = [
+    ("digid", "jan-burger", "bsn", "123456782"),
+    ("eherkenning", "acme-ondernemer", "kvk", "12345678"),
+    ("eidas", "pierre-dupont", "eidas_id", "FR/NL"),
+    ("medewerker", "merel-behandelaar", "__roles__", "behandelaar"),
+]
+
+
+def decode(jwt):
+    p = jwt.split(".")[1]
+    p += "=" * (-len(p) % 4)
+    return json.loads(base64.urlsafe_b64decode(p))
+
+
+def grant(realm, user):
+    data = urllib.parse.urlencode({
+        "grant_type": "password", "client_id": CLIENT,
+        "username": user, "password": PWD, "scope": "openid",
+    }).encode()
+    req = urllib.request.Request(
+        f"{BASE}/realms/{realm}/protocol/openid-connect/token", data=data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"})
+    with urllib.request.urlopen(req, timeout=20) as r:
+        return json.loads(r.read())
+
+
+def main():
+    ok = True
+    for realm, user, claim, expect in CHECKS:
+        try:
+            at = decode(grant(realm, user)["access_token"])
+            if claim == "__roles__":
+                val = at.get("realm_access", {}).get("roles", [])
+                good = expect in val
+            else:
+                val = at.get(claim)
+                good = val is not None and expect in str(val)
+            print(f"{realm:12} {user:18} login OK | {claim} = {val} "
+                  f"[{'OK' if good else 'UNEXPECTED'}]")
+            ok = ok and good
+        except urllib.error.HTTPError as e:
+            ok = False
+            print(f"{realm:12} {user:18} LOGIN FAILED {e.code}: {e.read()[:200]!r}")
+    print("keycloak smoke OK" if ok else "keycloak smoke FAILED")
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()

infra/keycloak/docker-compose.yml

@@ -0,0 +1,35 @@
+# Keycloak (S-02) with four pre-seeded realms imported at boot:
+#   digid · eherkenning · eidas · medewerker
+# Dev mode, H2 in-memory store, realm JSONs imported from ./realms.
+#
+#   docker compose -f infra/keycloak/docker-compose.yml up -d
+#   curl -s -o /dev/null -w '%{http_code}\n' \
+#     http://localhost:8180/realms/digid/.well-known/openid-configuration   # -> 200
+#
+# Admin console: http://localhost:8180/  (admin / admin — dev only)
+services:
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.1
+    command: ["start-dev", "--import-realm"]
+    environment:
+      KC_BOOTSTRAP_ADMIN_USERNAME: admin
+      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
+      # Older var names too, harmless on 26.x:
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HEALTH_ENABLED: "true"
+      KC_HTTP_ENABLED: "true"
+    ports:
+      - "8180:8080"
+    # realm exports are streamed into this external volume by infra/seed-config.sh.
+    volumes:
+      - kc-realms:/opt/keycloak/data/import:ro
+    networks: [cg]
+
+volumes:
+  kc-realms:
+    external: true
+    name: rr-kc-realms
+
+networks:
+  cg:

infra/keycloak/realms/digid-realm.json

@@ -0,0 +1,43 @@
+{
+  "realm": "digid",
+  "enabled": true,
+  "displayName": "Mock DigiD",
+  "clients": [
+    {
+      "clientId": "big-portal",
+      "enabled": true,
+      "publicClient": true,
+      "standardFlowEnabled": true,
+      "directAccessGrantsEnabled": true,
+      "redirectUris": ["*"],
+      "webOrigins": ["*"],
+      "protocolMappers": [
+        {
+          "name": "bsn",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-attribute-mapper",
+          "config": {
+            "user.attribute": "bsn",
+            "claim.name": "bsn",
+            "jsonType.label": "String",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        }
+      ]
+    }
+  ],
+  "users": [
+    {
+      "username": "jan-burger",
+      "enabled": true,
+      "firstName": "Jan",
+      "lastName": "Burger",
+      "email": "jan.burger@example.nl",
+      "emailVerified": true,
+      "credentials": [{ "type": "password", "value": "test123", "temporary": false }],
+      "attributes": { "bsn": ["123456782"] }
+    }
+  ]
+}

infra/keycloak/realms/eherkenning-realm.json

@@ -0,0 +1,43 @@
+{
+  "realm": "eherkenning",
+  "enabled": true,
+  "displayName": "Mock eHerkenning",
+  "clients": [
+    {
+      "clientId": "big-portal",
+      "enabled": true,
+      "publicClient": true,
+      "standardFlowEnabled": true,
+      "directAccessGrantsEnabled": true,
+      "redirectUris": ["*"],
+      "webOrigins": ["*"],
+      "protocolMappers": [
+        {
+          "name": "kvk",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-attribute-mapper",
+          "config": {
+            "user.attribute": "kvk",
+            "claim.name": "kvk",
+            "jsonType.label": "String",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        }
+      ]
+    }
+  ],
+  "users": [
+    {
+      "username": "acme-ondernemer",
+      "enabled": true,
+      "firstName": "Anita",
+      "lastName": "Ondernemer",
+      "email": "anita@acme.nl",
+      "emailVerified": true,
+      "credentials": [{ "type": "password", "value": "test123", "temporary": false }],
+      "attributes": { "kvk": ["12345678"] }
+    }
+  ]
+}

infra/keycloak/realms/eidas-realm.json

@@ -0,0 +1,43 @@
+{
+  "realm": "eidas",
+  "enabled": true,
+  "displayName": "Mock eIDAS",
+  "clients": [
+    {
+      "clientId": "big-portal",
+      "enabled": true,
+      "publicClient": true,
+      "standardFlowEnabled": true,
+      "directAccessGrantsEnabled": true,
+      "redirectUris": ["*"],
+      "webOrigins": ["*"],
+      "protocolMappers": [
+        {
+          "name": "eidas_id",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-attribute-mapper",
+          "config": {
+            "user.attribute": "eidas_id",
+            "claim.name": "eidas_id",
+            "jsonType.label": "String",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        }
+      ]
+    }
+  ],
+  "users": [
+    {
+      "username": "pierre-dupont",
+      "enabled": true,
+      "firstName": "Pierre",
+      "lastName": "Dupont",
+      "email": "pierre.dupont@example.fr",
+      "emailVerified": true,
+      "credentials": [{ "type": "password", "value": "test123", "temporary": false }],
+      "attributes": { "eidas_id": ["FR/NL/AB-1234-5678"] }
+    }
+  ]
+}

infra/keycloak/realms/medewerker-realm.json

@@ -0,0 +1,44 @@
+{
+  "realm": "medewerker",
+  "enabled": true,
+  "displayName": "Medewerkers",
+  "roles": {
+    "realm": [
+      { "name": "behandelaar", "description": "Behandelt registratieaanvragen" },
+      { "name": "teamlead", "description": "Teamleider behandeling" }
+    ]
+  },
+  "clients": [
+    {
+      "clientId": "big-portal",
+      "enabled": true,
+      "publicClient": true,
+      "standardFlowEnabled": true,
+      "directAccessGrantsEnabled": true,
+      "redirectUris": ["*"],
+      "webOrigins": ["*"]
+    }
+  ],
+  "users": [
+    {
+      "username": "merel-behandelaar",
+      "enabled": true,
+      "firstName": "Merel",
+      "lastName": "Behandelaar",
+      "email": "merel@big.example.nl",
+      "emailVerified": true,
+      "credentials": [{ "type": "password", "value": "test123", "temporary": false }],
+      "realmRoles": ["behandelaar"]
+    },
+    {
+      "username": "tom-teamlead",
+      "enabled": true,
+      "firstName": "Tom",
+      "lastName": "Teamlead",
+      "email": "tom@big.example.nl",
+      "emailVerified": true,
+      "credentials": [{ "type": "password", "value": "test123", "temporary": false }],
+      "realmRoles": ["behandelaar", "teamlead"]
+    }
+  ]
+}

infra/opennotificaties/docker-compose.yml

@@ -0,0 +1,96 @@
+# Open Notificaties (NRC) stack (S-01-c). Lean adaptation of the upstream dev compose:
+# db (PostGIS) + redis (also the Celery broker) + migrate-init + the API + a celery worker.
+#
+# Shares the `cg` network with the OpenZaak stack so the two can reach each other.
+# Run BOTH together (NRC needs OpenZaak's Autorisaties API for auth wiring):
+#
+#   docker compose -f infra/openzaak/docker-compose.yml -f infra/opennotificaties/docker-compose.yml up -d
+#   curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8001/admin/   # -> 302
+#
+# NRC is published on host :8001 (OpenZaak holds :8000).
+services:
+  nrc-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: opennotificaties
+      POSTGRES_PASSWORD: opennotificaties
+      POSTGRES_DB: opennotificaties
+    command: postgres -c max_connections=300
+    volumes:
+      - nrc-db:/var/lib/postgresql/data
+    healthcheck:
+      # pg_isready only checks TCP; the second clause verifies PostGIS is installed
+      # so nrc-init migrations can safely start (avoids race on cold container start).
+      test: ["CMD-SHELL", "pg_isready -U opennotificaties -d opennotificaties && psql -U opennotificaties -d opennotificaties -c 'SELECT PostGIS_Version();' -q 2>/dev/null"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 15s
+    networks: [cg]
+
+  nrc-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  nrc-init:
+    # Plain base image — nrc-init runs migrations only (see command below).
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: &nrc-env
+      DJANGO_SETTINGS_MODULE: nrc.conf.docker
+      SECRET_KEY: ${NRC_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: nrc-db
+      DB_NAME: opennotificaties
+      DB_USER: opennotificaties
+      DB_PASSWORD: opennotificaties
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: nrc-redis:6379/0
+      CACHE_AXES: nrc-redis:6379/0
+      CELERY_BROKER_URL: redis://nrc-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://nrc-redis:6379/1
+      DISABLE_2FA: "true"
+      OPENNOTIFICATIES_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENNOTIFICATIES_SUPERUSER_EMAIL: admin@localhost
+    # Migrations only for now. No setup_configuration steps are enabled yet (the
+    # OZ<->NRC notification wiring lands in S-06), and NRC's `setup_configuration`
+    # aborts with "No steps enabled" on the empty data.yaml — so we run `migrate`
+    # directly instead of /setup_configuration.sh. See data.yaml and ADR-0002.
+    command: ["sh", "-c", "/wait_for_db.sh && OTEL_SDK_DISABLED=True python src/manage.py migrate"]
+    depends_on:
+      nrc-db:
+        condition: service_healthy
+      nrc-redis:
+        condition: service_started
+    networks: [cg]
+
+  nrc-web:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: *nrc-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8001:8000"
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  nrc-celery:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-1.16.1}
+    environment: *nrc-env
+    command: /celery_worker.sh
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+volumes:
+  nrc-db:
+
+networks:
+  cg:

infra/opennotificaties/setup_configuration/data.yaml

@@ -0,0 +1,5 @@
+# Open Notificaties setup_configuration.
+# Stage 1 (this commit): intentionally minimal — the init container runs
+# migrations; no steps enabled yet. The OpenZaak<->NRC notification wiring
+# (Services, Authorization, JWT, Kanalen) is added next. See ADR-0002 / S-01-c.
+{}

infra/openzaak/docker-compose.yml

@@ -18,18 +18,21 @@ services:
     volumes:
       - oz-db:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U openzaak -d openzaak"]
+      # pg_isready only checks TCP; the second clause verifies PostGIS is installed
+      # so oz-init migrations can safely start (avoids race on cold container start).
+      test: ["CMD-SHELL", "pg_isready -U openzaak -d openzaak && psql -U openzaak -d openzaak -c 'SELECT PostGIS_Version();' -q 2>/dev/null"]
       interval: 5s
-      timeout: 3s
+      timeout: 5s
-      retries: 10
+      retries: 30
-    networks: [oz]
+      start_period: 15s
+    networks: [cg]
 
   oz-redis:
     image: docker.io/library/redis:7
-    networks: [oz]
+    networks: [cg]
 
   oz-init:
-    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
     environment: &oz-env
       DJANGO_SETTINGS_MODULE: openzaak.conf.docker
       SECRET_KEY: ${OZ_SECRET_KEY:-dev-only-not-for-production}
@@ -44,20 +47,26 @@ services:
       CELERY_BROKER_URL: redis://oz-redis:6379/1
       CELERY_RESULT_BACKEND: redis://oz-redis:6379/1
       DISABLE_2FA: "true"
+      # Notifications go to Open Notificaties (NRC), which arrives in S-01-c.
+      # Until then, disable outbound notifications so writes don't 500.
+      NOTIFICATIONS_DISABLED: "true"
       OPENZAAK_SUPERUSER_USERNAME: admin
       DJANGO_SUPERUSER_PASSWORD: admin
       OPENZAAK_SUPERUSER_EMAIL: admin@localhost
-      RUN_SETUP_CONFIG: "false"
+      RUN_SETUP_CONFIG: "true"
     command: /setup_configuration.sh
+    # data.yaml is streamed into this external volume by infra/seed-config.sh.
+    volumes:
+      - oz-config:/app/setup_configuration:ro
     depends_on:
       oz-db:
         condition: service_healthy
       oz-redis:
         condition: service_started
-    networks: [oz]
+    networks: [cg]
 
   openzaak:
-    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
     environment: *oz-env
     healthcheck:
       test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
@@ -70,19 +79,23 @@ services:
     depends_on:
       oz-init:
         condition: service_completed_successfully
-    networks: [oz]
+    networks: [cg]
 
   oz-celery:
-    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-1.28.2}
     environment: *oz-env
     command: /celery_worker.sh
     depends_on:
       oz-init:
         condition: service_completed_successfully
-    networks: [oz]
+    networks: [cg]
 
 volumes:
   oz-db:
+  # populated out-of-band by infra/seed-config.sh (docker cp) — see that script.
+  oz-config:
+    external: true
+    name: rr-oz-config
 
 networks:
-  oz:
+  cg:

infra/openzaak/seed_catalogus.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Idempotent seed of the BIG catalogus into OpenZaak via the ZTC API.
+
+Creates (if absent):
+  - catalogus "BIG"
+  - a lean "BIG-registratie" zaaktype (only schema-mandatory fields)
+  - a "bsn" eigenschap on that zaaktype
+  - then publishes the zaaktype.
+
+Auth uses the JWT client provisioned by setup_configuration (see ADR-0002).
+Stdlib only — no pip deps. Re-running is safe (matches existing by identifier).
+"""
+import base64, hashlib, hmac, json, os, sys, time, urllib.error, urllib.request
+
+BASE = os.environ.get("OZ_BASE", "http://localhost:8000")
+CLIENT_ID = os.environ.get("OZ_CLIENT_ID", "big-reference-seed")
+SECRET = os.environ.get("OZ_SECRET", "insecure-dev-secret-change-me")
+ZTC = f"{BASE}/catalogi/api/v1"
+RSIN = "517439943"  # elfproef-valid test RSIN
+
+
+def token():
+    b64 = lambda b: base64.urlsafe_b64encode(b).rstrip(b"=")
+    hdr = {"alg": "HS256", "typ": "JWT"}
+    pl = {"iss": CLIENT_ID, "iat": int(time.time()), "client_id": CLIENT_ID,
+          "user_id": "seed", "user_representation": "seed"}
+    seg = b64(json.dumps(hdr, separators=(",", ":")).encode()) + b"." + \
+          b64(json.dumps(pl, separators=(",", ":")).encode())
+    sig = b64(hmac.new(SECRET.encode(), seg, hashlib.sha256).digest())
+    return (seg + b"." + sig).decode()
+
+
+def api(method, path, body=None):
+    url = path if path.startswith("http") else f"{ZTC}{path}"
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method, headers={
+        "Authorization": "Bearer " + token(),
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    })
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            return r.status, json.loads(r.read() or "null")
+    except urllib.error.HTTPError as e:
+        return e.code, json.loads(e.read() or "null")
+
+
+def find(path):
+    status, body = api("GET", path)
+    if status != 200:
+        sys.exit(f"GET {path} -> {status}: {body}")
+    return body.get("results", [])
+
+
+def main():
+    # 1. Catalogus
+    existing = [c for c in find(f"/catalogussen?domein=BIG") if c.get("domein") == "BIG"]
+    if existing:
+        cat = existing[0]
+        print(f"skip   catalogus BIG ({cat['url']})")
+    else:
+        st, cat = api("POST", "/catalogussen", {
+            "domein": "BIG", "rsin": RSIN,
+            "contactpersoonBeheerNaam": "BIG Beheer",
+        })
+        if st != 201:
+            sys.exit(f"create catalogus -> {st}: {cat}")
+        print(f"create catalogus BIG ({cat['url']})")
+
+    # 2. Zaaktype (concept)
+    # status=alles so concept zaaktypen are matched too (else we'd duplicate).
+    zts = [z for z in find(f"/zaaktypen?catalogus={cat['url']}&status=alles")
+           if z.get("identificatie") == "BIG-REGISTRATIE"]
+    if zts:
+        zt = zts[0]
+        print(f"skip   zaaktype BIG-REGISTRATIE ({zt['url']}) concept={zt.get('concept')}")
+    else:
+        st, zt = api("POST", "/zaaktypen", {
+            "identificatie": "BIG-REGISTRATIE",
+            "omschrijving": "BIG-registratie",
+            "vertrouwelijkheidaanduiding": "openbaar",
+            "doel": "Registratie van een zorgprofessional in het BIG-register",
+            "aanleiding": "Aanvraag tot registratie",
+            "indicatieInternOfExtern": "extern",
+            "handelingInitiator": "indienen",
+            "onderwerp": "BIG-registratie",
+            "handelingBehandelaar": "behandelen",
+            "doorlooptijd": "P30D",
+            "opschortingEnAanhoudingMogelijk": False,
+            "verlengingMogelijk": False,
+            "publicatieIndicatie": False,
+            "productenOfDiensten": [],
+            "referentieproces": {"naam": "BIG-registratie"},
+            "catalogus": cat["url"],
+            "besluittypen": [],
+            "gerelateerdeZaaktypen": [],
+            "beginGeldigheid": "2026-01-01",
+            "versiedatum": "2026-01-01",
+            "verantwoordelijke": RSIN,
+        })
+        if st != 201:
+            sys.exit(f"create zaaktype -> {st}: {json.dumps(zt, indent=2)}")
+        print(f"create zaaktype BIG-REGISTRATIE ({zt['url']})")
+
+    # 3. bsn eigenschap (only addable while concept)
+    eigs = [e for e in find(f"/eigenschappen?zaaktype={zt['url']}&status=alles")
+            if e.get("naam") == "bsn"]
+    if eigs:
+        print("skip   eigenschap bsn")
+    elif zt.get("concept", True):
+        st, eig = api("POST", "/eigenschappen", {
+            "naam": "bsn",
+            "definitie": "Burgerservicenummer van de zorgprofessional",
+            "zaaktype": zt["url"],
+            "specificatie": {"groep": "aanvrager", "formaat": "tekst",
+                             "lengte": "9", "kardinaliteit": "1", "waardenverzameling": []},
+        })
+        if st != 201:
+            sys.exit(f"create eigenschap -> {st}: {json.dumps(eig, indent=2)}")
+        print("create eigenschap bsn")
+    else:
+        print("warn   zaaktype already published; cannot add bsn eigenschap")
+
+    # Intentionally NOT published. Publishing requires roltypen, resultaattypen
+    # and statustypen, which go beyond the "lean / schema-mandatory" zaaktype this
+    # slice asks for; they arrive with the workflow/zaak slices. See ADR-0002.
+
+    # 4. Verify the JWT client can list the zaaktype (concepts included).
+    zaaktypen = find(f"/zaaktypen?catalogus={cat['url']}&status=alles")
+    names = [z.get("identificatie") for z in zaaktypen]
+    print(f"zaaktypen in BIG: {names}")
+    assert "BIG-REGISTRATIE" in names, "BIG-REGISTRATIE not listed"
+    print("OK — BIG catalogus seeded (BIG-REGISTRATIE concept + bsn eigenschap)")
+
+
+if __name__ == "__main__":
+    main()

infra/openzaak/setup_configuration/data.yaml

@@ -0,0 +1,22 @@
+# OpenZaak setup_configuration (idempotent, declarative).
+# Provisions the JWT client the seed + ACL use to call OpenZaak's APIs.
+# Dev-only credentials — not for production.
+#
+# Steps come from vng_api_common.contrib.setup_configuration (see ADR-0002).
+
+vng_api_common_credentials_config_enable: true
+vng_api_common_credentials:
+  items:
+    - identifier: big-reference-seed
+      secret: insecure-dev-secret-change-me
+
+vng_api_common_applicaties_config_enable: true
+vng_api_common_applicaties:
+  items:
+    # uuid must be given explicitly as a string (the step's auto-default is a
+    # UUID object that fails its own validation).
+    - uuid: "11111111-1111-4111-8111-111111111111"
+      client_ids:
+        - big-reference-seed
+      label: BIG reference seed client
+      heeft_alle_autorisaties: true

infra/seed-config.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# Populate the external named *config* volumes that the upstream services mount,
+# by `docker cp`-ing files into a throwaway helper container that mounts each one.
+#
+# Why: the compose stack uses the upstream images verbatim (no build). On Gitea's
+# containerized runner, `docker compose` starts the stack as SIBLING containers
+# via the host daemon, so a workspace bind mount resolves to a path the daemon
+# can't see and is mounted empty. `docker cp` instead streams bytes over the
+# Docker API, so the files reach the volume regardless of where the daemon runs.
+# We use plain docker primitives (volume create / run / cp / rm) rather than
+# `docker compose create`, because podman-compose (local dev) lacks that
+# subcommand. Fixed-name `external` volumes keep the names deterministic across
+# both runtimes. See docs/runbooks/gitea-actions-gotchas.md.
+#
+# Usage: seed-config.sh <key> [<key> ...]   where key ∈ { oz, kc, fl }
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HELPER="${SEED_HELPER_IMAGE:-docker.io/library/busybox:stable}"
+
+populate() {  # volume  source(file or dir/.)
+  local vol="$1" src="$2" cid
+  docker volume rm -f "$vol" >/dev/null 2>&1 || true
+  docker volume create "$vol" >/dev/null
+  # A *created* (never started) helper is enough: the volume is attached at create
+  # time, `docker cp` writes through to it, and `docker rm` is instant (nothing to
+  # stop). `docker create` is a container subcommand both docker and podman have —
+  # unlike `docker compose create`, which podman-compose lacks.
+  cid="$(docker create -v "$vol:/dest" "$HELPER" true)"
+  docker cp "$src" "$cid:/dest/"
+  docker rm "$cid" >/dev/null
+  echo "  seeded $vol"
+}
+
+[ "$#" -gt 0 ] || { echo "usage: seed-config.sh <oz|kc|fl> ..." >&2; exit 2; }
+
+for key in "$@"; do
+  case "$key" in
+    oz) populate rr-oz-config "$here/openzaak/setup_configuration/." ;;
+    kc) populate rr-kc-realms "$here/keycloak/realms/." ;;
+    fl) populate rr-fl-bpmn  "$here/../workflows/registratie.bpmn" ;;
+    *)  echo "unknown seed key: $key" >&2; exit 2 ;;
+  esac
+done

infra/wait-healthy.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# Wait until the named compose services report a healthy healthcheck.
+#
+# Portable across `docker compose` (CI) and `podman-compose` (local dev): it uses
+# plain `docker ps` + `docker inspect`, so it needs neither `docker compose
+# up --wait` (podman-compose doesn't implement that flag) nor host port access
+# (the containerized CI runner can't reach published ports). It also sidesteps the
+# `--wait`-fails-when-a-one-shot-exits issue, since we only poll long-running
+# services that declare a healthcheck. See docs/runbooks/gitea-actions-gotchas.md.
+#
+# Usage: WAIT_TIMEOUT=420 wait-healthy.sh <service> [<service> ...]
+set -euo pipefail
+
+timeout="${WAIT_TIMEOUT:-420}"
+deadline=$(( $(date +%s) + timeout ))
+
+# compose service name -> container id. The name filter matches both docker
+# compose ("infra-openzaak-1") and podman-compose ("infra_openzaak_1") naming.
+cid_for() { docker ps -aq --filter "name=$1" | head -1; }
+
+for svc in "$@"; do
+  echo "waiting for '$svc' to be healthy (timeout ${timeout}s)..."
+  while :; do
+    cid="$(cid_for "$svc")"
+    status=""
+    [ -n "$cid" ] && status="$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$cid" 2>/dev/null || true)"
+    [ "$status" = "healthy" ] && { echo "  '$svc' is healthy"; break; }
+    if [ "$(date +%s)" -ge "$deadline" ]; then
+      echo "TIMEOUT: '$svc' not healthy (status=${status:-no-container})" >&2
+      docker ps -a --filter "name=$svc" >&2 || true
+      exit 1
+    fi
+    sleep 3
+  done
+done

mkdocs.yml

@@ -23,6 +23,9 @@ nav:
   - Product Requirements: PRD.md
   - Architecture:
       - "ADR-0001: Loose coupling": architecture/adr-0001-loose-coupling.md
+      - "ADR-0002: Catalogus design": architecture/adr-0002-catalogus-design.md
+      - "ADR-0003: ACL default-fill": architecture/adr-0003-default-fill.md
+      - "ADR-0004: BDD framework": architecture/adr-0004-bdd-framework.md
   - Working in Gitea: gitea-workflow.md
   - Runbooks:
       - CI: runbooks/ci.md

register-referentie.slnx

@@ -0,0 +1,16 @@
+<Solution>
+  <Folder Name="/services/" />
+  <Folder Name="/services/acl/">
+    <Project Path="services/acl/Acl.Api/Acl.Api.csproj" />
+    <Project Path="services/acl/Acl.Application/Acl.Application.csproj" />
+    <Project Path="services/acl/Acl.Infrastructure/Acl.Infrastructure.csproj" />
+    <Project Path="services/acl/Acl.Tests/Acl.Tests.csproj" />
+  </Folder>
+  <Folder Name="/services/bff/">
+    <Project Path="services/bff/Bff.Api/Bff.Api.csproj" />
+    <Project Path="services/bff/Bff.Tests/Bff.Tests.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/acceptance/Acceptance.csproj" />
+  </Folder>
+</Solution>

services/acl/.dockerignore

@@ -0,0 +1,3 @@
+**/bin
+**/obj
+**/*.user

services/acl/Acl.Api/Acl.Api.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <ItemGroup>
+    <ProjectReference Include="..\Acl.Application\Acl.Application.csproj" />
+    <ProjectReference Include="..\Acl.Infrastructure\Acl.Infrastructure.csproj" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+</Project>

services/acl/Acl.Api/Program.cs

@@ -0,0 +1,31 @@
+using Acl.Application;
+using Acl.Infrastructure;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddSingleton<IClock, SystemClock>();
+builder.Services.AddSingleton(sp => sp.GetRequiredService<IConfiguration>()
+    .GetSection("Acl:Defaults").Get<AclDefaults>()
+    ?? throw new InvalidOperationException("Missing configuration section 'Acl:Defaults'"));
+builder.Services.AddSingleton(sp => sp.GetRequiredService<IConfiguration>()
+    .GetSection("Acl:OpenZaak").Get<OpenZaakOptions>()
+    ?? throw new InvalidOperationException("Missing configuration section 'Acl:OpenZaak'"));
+builder.Services.AddHttpClient<IZaakGateway, OpenZaakGateway>();
+builder.Services.AddScoped<AclService>();
+
+var app = builder.Build();
+
+app.MapGet("/health", () => "Healthy");
+
+// The ACL's single operation, exposed as a service endpoint.
+app.MapPost("/zaken", async (OpenZaakRequest body, AclService acl, CancellationToken ct) =>
+{
+    var zaakUrl = await acl.OpenZaakAsync(new DomainRegistration(body.Bsn), ct);
+    return Results.Ok(new { zaakUrl = zaakUrl.ToString() });
+});
+
+app.Run();
+
+public sealed record OpenZaakRequest(string Bsn);
+
+public partial class Program;

services/acl/Acl.Api/Properties/launchSettings.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:5041",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:7260;http://localhost:5041",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

services/acl/Acl.Api/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

services/acl/Acl.Api/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}

services/acl/Acl.Application/Acl.Application.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+</Project>

services/acl/Acl.Application/AclDefaults.cs

@@ -0,0 +1,10 @@
+namespace Acl.Application;
+
+/// <summary>Configured ZGW defaults the ACL fills in (ADR-0003).</summary>
+public sealed class AclDefaults
+{
+    public required string Bronorganisatie { get; init; }
+    public required string VerantwoordelijkeOrganisatie { get; init; }
+    public required string Vertrouwelijkheidaanduiding { get; init; }
+    public required Uri ZaaktypeUrl { get; init; }
+}

services/acl/Acl.Application/AclService.cs

@@ -0,0 +1,20 @@
+namespace Acl.Application;
+
+/// <summary>The ACL's single operation: open a zaak from a domain payload,
+/// default-filling the ZGW-mandatory fields (ADR-0003).</summary>
+public sealed class AclService(IZaakGateway gateway, AclDefaults defaults, IClock clock)
+{
+    public Task<Uri> OpenZaakAsync(DomainRegistration registration, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(registration);
+
+        var request = new ZaakRequest(
+            defaults.Bronorganisatie,
+            defaults.VerantwoordelijkeOrganisatie,
+            defaults.Vertrouwelijkheidaanduiding,
+            defaults.ZaaktypeUrl,
+            clock.Today);
+
+        return gateway.OpenZaakAsync(request, ct);
+    }
+}

services/acl/Acl.Application/DomainRegistration.cs

@@ -0,0 +1,4 @@
+namespace Acl.Application;
+
+/// <summary>Domain-language payload handed to the ACL. No ZGW concepts here.</summary>
+public sealed record DomainRegistration(string Bsn);

services/acl/Acl.Application/IClock.cs

@@ -0,0 +1,7 @@
+namespace Acl.Application;
+
+/// <summary>Abstracts "today" so startdatum default-fill is deterministic in tests.</summary>
+public interface IClock
+{
+    DateOnly Today { get; }
+}

services/acl/Acl.Application/IZaakGateway.cs

@@ -0,0 +1,8 @@
+namespace Acl.Application;
+
+/// <summary>Port to the ZGW Zaken API. Implemented in Infrastructure — the only
+/// code that talks to OpenZaak (ADR-0001).</summary>
+public interface IZaakGateway
+{
+    Task<Uri> OpenZaakAsync(ZaakRequest request, CancellationToken ct = default);
+}

services/acl/Acl.Application/ZaakRequest.cs

@@ -0,0 +1,9 @@
+namespace Acl.Application;
+
+/// <summary>The fully default-filled zaak the gateway will create in OpenZaak.</summary>
+public sealed record ZaakRequest(
+    string Bronorganisatie,
+    string VerantwoordelijkeOrganisatie,
+    string Vertrouwelijkheidaanduiding,
+    Uri Zaaktype,
+    DateOnly Startdatum);

services/acl/Acl.Infrastructure/Acl.Infrastructure.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <ProjectReference Include="..\Acl.Application\Acl.Application.csproj" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+</Project>

services/acl/Acl.Infrastructure/OpenZaakGateway.cs

@@ -0,0 +1,48 @@
+using System.Net.Http.Headers;
+using System.Net.Http.Json;
+using System.Text.Json.Serialization;
+using Acl.Application;
+
+namespace Acl.Infrastructure;
+
+/// <summary>The only code that talks to OpenZaak's Zaken API (ADR-0001).</summary>
+public sealed class OpenZaakGateway(HttpClient http, OpenZaakOptions options) : IZaakGateway
+{
+    public async Task<Uri> OpenZaakAsync(ZaakRequest request, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        using var message = new HttpRequestMessage(
+            HttpMethod.Post, new Uri(options.BaseUrl, "/zaken/api/v1/zaken"))
+        {
+            Content = JsonContent.Create(new ZaakDto(
+                request.Bronorganisatie,
+                request.Zaaktype.ToString(),
+                request.VerantwoordelijkeOrganisatie,
+                request.Startdatum.ToString("yyyy-MM-dd"),
+                request.Vertrouwelijkheidaanduiding)),
+        };
+        message.Headers.Authorization =
+            new AuthenticationHeaderValue("Bearer", ZgwToken.Mint(options.ClientId, options.Secret));
+        // ZRC is a geo API; it requires the CRS headers.
+        message.Headers.Add("Accept-Crs", "EPSG:4326");
+        message.Content.Headers.Add("Content-Crs", "EPSG:4326");
+
+        using var response = await http.SendAsync(message, ct);
+        response.EnsureSuccessStatusCode();
+
+        var created = await response.Content.ReadFromJsonAsync<ZaakCreatedDto>(ct)
+            ?? throw new InvalidOperationException("OpenZaak returned an empty zaak response");
+        return new Uri(created.Url);
+    }
+
+    private sealed record ZaakDto(
+        [property: JsonPropertyName("bronorganisatie")] string Bronorganisatie,
+        [property: JsonPropertyName("zaaktype")] string Zaaktype,
+        [property: JsonPropertyName("verantwoordelijkeOrganisatie")] string VerantwoordelijkeOrganisatie,
+        [property: JsonPropertyName("startdatum")] string Startdatum,
+        [property: JsonPropertyName("vertrouwelijkheidaanduiding")] string Vertrouwelijkheidaanduiding);
+
+    private sealed record ZaakCreatedDto(
+        [property: JsonPropertyName("url")] string Url);
+}

services/acl/Acl.Infrastructure/OpenZaakOptions.cs

@@ -0,0 +1,9 @@
+namespace Acl.Infrastructure;
+
+/// <summary>Connection + credential config for OpenZaak's ZGW APIs.</summary>
+public sealed class OpenZaakOptions
+{
+    public required Uri BaseUrl { get; init; }
+    public required string ClientId { get; init; }
+    public required string Secret { get; init; }
+}

services/acl/Acl.Infrastructure/SystemClock.cs

@@ -0,0 +1,8 @@
+using Acl.Application;
+
+namespace Acl.Infrastructure;
+
+public sealed class SystemClock : IClock
+{
+    public DateOnly Today => DateOnly.FromDateTime(DateTime.UtcNow);
+}

services/acl/Acl.Infrastructure/ZgwToken.cs

@@ -0,0 +1,29 @@
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+
+namespace Acl.Infrastructure;
+
+/// <summary>Mints a ZGW (vng-api-common) JWT: HS256 over the standard claims.</summary>
+internal static class ZgwToken
+{
+    public static string Mint(string clientId, string secret)
+    {
+        var header = B64Url(JsonSerializer.SerializeToUtf8Bytes(new { alg = "HS256", typ = "JWT" }));
+        var payload = B64Url(JsonSerializer.SerializeToUtf8Bytes(new
+        {
+            iss = clientId,
+            iat = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
+            client_id = clientId,
+            user_id = "acl",
+            user_representation = "acl",
+        }));
+        var signingInput = $"{header}.{payload}";
+        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
+        var signature = B64Url(hmac.ComputeHash(Encoding.UTF8.GetBytes(signingInput)));
+        return $"{signingInput}.{signature}";
+    }
+
+    private static string B64Url(byte[] bytes) =>
+        Convert.ToBase64String(bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_');
+}

services/acl/Acl.Tests/Acl.Tests.csproj

@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" Version="6.0.4" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="xunit" Version="2.9.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Acl.Application\Acl.Application.csproj" />
+    <ProjectReference Include="..\Acl.Infrastructure\Acl.Infrastructure.csproj" />
+  </ItemGroup>
+
+</Project>

services/acl/Acl.Tests/AclServiceTests.cs

@@ -0,0 +1,47 @@
+using Acl.Application;
+
+namespace Acl.Tests;
+
+public class AclServiceTests
+{
+    private sealed class FakeGateway : IZaakGateway
+    {
+        public ZaakRequest? Captured;
+        public Uri Result { get; } = new("http://openzaak/zaken/api/v1/zaken/abc");
+
+        public Task<Uri> OpenZaakAsync(ZaakRequest request, CancellationToken ct = default)
+        {
+            Captured = request;
+            return Task.FromResult(Result);
+        }
+    }
+
+    private sealed class FixedClock(DateOnly today) : IClock
+    {
+        public DateOnly Today { get; } = today;
+    }
+
+    [Fact]
+    public async Task Opening_a_zaak_default_fills_zgw_fields_and_returns_the_zaak_url()
+    {
+        var gateway = new FakeGateway();
+        var defaults = new AclDefaults
+        {
+            Bronorganisatie = "517439943",
+            VerantwoordelijkeOrganisatie = "517439943",
+            Vertrouwelijkheidaanduiding = "openbaar",
+            ZaaktypeUrl = new("http://openzaak/catalogi/api/v1/zaaktypen/big"),
+        };
+        var service = new AclService(gateway, defaults, new FixedClock(new DateOnly(2026, 6, 4)));
+
+        var url = await service.OpenZaakAsync(new DomainRegistration("123456782"));
+
+        Assert.Equal(gateway.Result, url);
+        var req = Assert.IsType<ZaakRequest>(gateway.Captured);
+        Assert.Equal("517439943", req.Bronorganisatie);
+        Assert.Equal("517439943", req.VerantwoordelijkeOrganisatie);
+        Assert.Equal("openbaar", req.Vertrouwelijkheidaanduiding);
+        Assert.Equal(defaults.ZaaktypeUrl, req.Zaaktype);
+        Assert.Equal(new DateOnly(2026, 6, 4), req.Startdatum);
+    }
+}

services/acl/Acl.Tests/OpenZaakGatewayTests.cs

@@ -0,0 +1,51 @@
+using System.Net;
+using System.Net.Http.Json;
+using Acl.Application;
+using Acl.Infrastructure;
+
+namespace Acl.Tests;
+
+public class OpenZaakGatewayTests
+{
+    private sealed class StubHandler(Func<HttpRequestMessage, Task<HttpResponseMessage>> onSend)
+        : HttpMessageHandler
+    {
+        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct)
+            => onSend(request);
+    }
+
+    [Fact]
+    public async Task Posts_zaak_to_openzaak_with_bearer_and_default_fields_and_returns_url()
+    {
+        HttpRequestMessage? seen = null;
+        string? body = null;
+        var handler = new StubHandler(async req =>
+        {
+            seen = req;
+            body = await req.Content!.ReadAsStringAsync();
+            return new HttpResponseMessage(HttpStatusCode.Created)
+            {
+                Content = JsonContent.Create(new { url = "http://openzaak/zaken/api/v1/zaken/xyz" }),
+            };
+        });
+        var gateway = new OpenZaakGateway(
+            new HttpClient(handler),
+            new OpenZaakOptions { BaseUrl = new("http://openzaak"), ClientId = "cid", Secret = "sec" });
+        var request = new ZaakRequest(
+            "517439943", "517439943", "openbaar",
+            new("http://openzaak/catalogi/api/v1/zaaktypen/big"), new DateOnly(2026, 6, 4));
+
+        var url = await gateway.OpenZaakAsync(request);
+
+        Assert.Equal("http://openzaak/zaken/api/v1/zaken/xyz", url.ToString());
+        Assert.Equal(HttpMethod.Post, seen!.Method);
+        Assert.Equal("http://openzaak/zaken/api/v1/zaken", seen.RequestUri!.ToString());
+        Assert.Equal("Bearer", seen.Headers.Authorization!.Scheme);
+        Assert.False(string.IsNullOrWhiteSpace(seen.Headers.Authorization.Parameter));
+        Assert.Contains("\"bronorganisatie\":\"517439943\"", body);
+        Assert.Contains("\"verantwoordelijkeOrganisatie\":\"517439943\"", body);
+        Assert.Contains("\"vertrouwelijkheidaanduiding\":\"openbaar\"", body);
+        Assert.Contains("\"startdatum\":\"2026-06-04\"", body);
+        Assert.Contains("\"zaaktype\":\"http://openzaak/catalogi/api/v1/zaaktypen/big\"", body);
+    }
+}

services/acl/Acl.slnx

@@ -0,0 +1,6 @@
+<Solution>
+  <Project Path="Acl.Api/Acl.Api.csproj" />
+  <Project Path="Acl.Application/Acl.Application.csproj" />
+  <Project Path="Acl.Infrastructure/Acl.Infrastructure.csproj" />
+  <Project Path="Acl.Tests/Acl.Tests.csproj" />
+</Solution>

services/acl/Dockerfile

@@ -0,0 +1,32 @@
+# Multi-stage build for the ACL service (.NET 10).
+# Build context is services/acl (see infra/docker-compose.yml).
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+
+# Restore first (cached unless .csproj files change).
+COPY Acl.Api/Acl.Api.csproj Acl.Api/
+COPY Acl.Application/Acl.Application.csproj Acl.Application/
+COPY Acl.Infrastructure/Acl.Infrastructure.csproj Acl.Infrastructure/
+RUN dotnet restore Acl.Api/Acl.Api.csproj
+
+COPY Acl.Api/ Acl.Api/
+COPY Acl.Application/ Acl.Application/
+COPY Acl.Infrastructure/ Acl.Infrastructure/
+RUN dotnet publish Acl.Api/Acl.Api.csproj -c Release -o /app/publish /p:UseAppHost=false
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /app/publish .
+
+ENV ASPNETCORE_URLS=http://+:8080
+EXPOSE 8080
+
+HEALTHCHECK --interval=5s --timeout=3s --start-period=10s --retries=5 \
+    CMD curl -fsS http://localhost:8080/health || exit 1
+
+ENTRYPOINT ["dotnet", "Acl.Api.dll"]

tests/acceptance/Acceptance.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" Version="6.0.4" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="Reqnroll.xUnit" Version="3.3.4" />
+    <PackageReference Include="xunit" Version="2.9.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\services\acl\Acl.Application\Acl.Application.csproj" />
+    <ProjectReference Include="..\..\services\acl\Acl.Infrastructure\Acl.Infrastructure.csproj" />
+  </ItemGroup>
+
+</Project>

tests/acceptance/Features/EenZaakOpenen.feature

@@ -0,0 +1,27 @@
+# language: en
+# Drives S-04 (#5). The ACL is the only code that talks to ZGW (ADR-0001); it
+# default-fills the ZGW-mandatory zaak fields the domain never sees (ADR-0003).
+# Real-OpenZaak verification is a separate slice — this scenario exercises the
+# use case against an in-memory stand-in for the Zaken API.
+Feature: Een zaak openen vanuit een registratie
+  Als domein wil ik de ACL vragen een zaak te openen
+  zodat de ZGW-verplichte velden worden ingevuld zonder dat het domein ze kent.
+
+  Scenario: De ACL vult de ZGW-verplichte velden default in
+    Given a domain registration for BSN "123456782"
+    And the ACL is configured with these defaults:
+      | field                        | value                                         |
+      | bronorganisatie              | 517439943                                     |
+      | verantwoordelijkeOrganisatie | 517439943                                     |
+      | vertrouwelijkheidaanduiding  | openbaar                                      |
+      | zaaktype                     | http://openzaak/catalogi/api/v1/zaaktypen/big |
+    And today is "2026-06-04"
+    When the domain asks the ACL to open a zaak
+    Then a zaak is created with these default-filled fields
+      | field                        | value                                         |
+      | bronorganisatie              | 517439943                                     |
+      | verantwoordelijkeOrganisatie | 517439943                                     |
+      | vertrouwelijkheidaanduiding  | openbaar                                      |
+      | zaaktype                     | http://openzaak/catalogi/api/v1/zaaktypen/big |
+      | startdatum                   | 2026-06-04                                    |
+    And the ACL returns the URL of the created zaak

tests/acceptance/Steps/EenZaakOpenenSteps.cs

@@ -0,0 +1,65 @@
+using Acceptance.Support;
+using Acl.Application;
+using Reqnroll;
+using Xunit;
+
+namespace Acceptance.Steps;
+
+/// <summary>Bindings for <c>EenZaakOpenen.feature</c>. Reqnroll creates one
+/// instance per scenario, so instance fields hold scenario-scoped state.</summary>
+[Binding]
+public sealed class EenZaakOpenenSteps
+{
+    private readonly InMemoryZaakGateway _gateway = new();
+    private DomainRegistration? _registration;
+    private AclDefaults? _defaults;
+    private DateOnly _today;
+    private Uri? _returnedUrl;
+
+    [Given("a domain registration for BSN \"(.*)\"")]
+    public void GivenADomainRegistrationForBsn(string bsn)
+        => _registration = new DomainRegistration(bsn);
+
+    [Given("the ACL is configured with these defaults:")]
+    public void GivenTheAclIsConfiguredWithTheseDefaults(DataTable defaults)
+    {
+        var values = ToFieldMap(defaults);
+        _defaults = new AclDefaults
+        {
+            Bronorganisatie = values["bronorganisatie"],
+            VerantwoordelijkeOrganisatie = values["verantwoordelijkeOrganisatie"],
+            Vertrouwelijkheidaanduiding = values["vertrouwelijkheidaanduiding"],
+            ZaaktypeUrl = new Uri(values["zaaktype"]),
+        };
+    }
+
+    [Given("today is \"(.*)\"")]
+    public void GivenTodayIs(string date)
+        => _today = DateOnly.Parse(date);
+
+    [When("the domain asks the ACL to open a zaak")]
+    public async Task WhenTheDomainAsksTheAclToOpenAZaak()
+    {
+        var service = new AclService(_gateway, _defaults!, new FixedClock(_today));
+        _returnedUrl = await service.OpenZaakAsync(_registration!);
+    }
+
+    [Then("a zaak is created with these default-filled fields")]
+    public void ThenAZaakIsCreatedWithTheseDefaultFilledFields(DataTable expected)
+    {
+        var request = Assert.IsType<ZaakRequest>(_gateway.Captured);
+        var fields = ToFieldMap(expected);
+        Assert.Equal(fields["bronorganisatie"], request.Bronorganisatie);
+        Assert.Equal(fields["verantwoordelijkeOrganisatie"], request.VerantwoordelijkeOrganisatie);
+        Assert.Equal(fields["vertrouwelijkheidaanduiding"], request.Vertrouwelijkheidaanduiding);
+        Assert.Equal(fields["zaaktype"], request.Zaaktype.ToString());
+        Assert.Equal(fields["startdatum"], request.Startdatum.ToString("yyyy-MM-dd"));
+    }
+
+    [Then("the ACL returns the URL of the created zaak")]
+    public void ThenTheAclReturnsTheUrlOfTheCreatedZaak()
+        => Assert.Equal(InMemoryZaakGateway.CreatedZaakUrl, _returnedUrl);
+
+    private static Dictionary<string, string> ToFieldMap(DataTable table)
+        => table.Rows.ToDictionary(r => r["field"], r => r["value"]);
+}

tests/acceptance/Support/FixedClock.cs

@@ -0,0 +1,10 @@
+using Acl.Application;
+
+namespace Acceptance.Support;
+
+/// <summary>A clock pinned to a known date so <c>startdatum</c> is deterministic
+/// in scenarios (ADR-0003).</summary>
+public sealed class FixedClock(DateOnly today) : IClock
+{
+    public DateOnly Today { get; } = today;
+}

tests/acceptance/Support/InMemoryZaakGateway.cs

@@ -0,0 +1,20 @@
+using Acl.Application;
+
+namespace Acceptance.Support;
+
+/// <summary>An in-memory stand-in for the OpenZaak Zaken API. It captures the
+/// fully default-filled <see cref="ZaakRequest"/> the ACL builds and returns a
+/// fixed zaak URL, so the acceptance scenario can verify the use case without a
+/// running OpenZaak (real-OpenZaak verification is a separate slice).</summary>
+public sealed class InMemoryZaakGateway : IZaakGateway
+{
+    public static readonly Uri CreatedZaakUrl = new("http://openzaak/zaken/api/v1/zaken/created-123");
+
+    public ZaakRequest? Captured { get; private set; }
+
+    public Task<Uri> OpenZaakAsync(ZaakRequest request, CancellationToken ct = default)
+    {
+        Captured = request;
+        return Task.FromResult(CreatedZaakUrl);
+    }
+}

workflows/registratie.bpmn

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
+             xmlns:flowable="http://flowable.org/bpmn"
+             xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
+             xmlns:omgdc="http://www.omg.org/spec/DD/20100524/DC"
+             xmlns:omgdi="http://www.omg.org/spec/DD/20100524/DI"
+             targetNamespace="http://respellion.nl/big">
+
+  <!-- S-03: minimal "Registratie ontvangen" flow.
+       start -> external-worker task (OpenZaakAanmaken) -> end.
+       The external task is handled by the Workflow Client / ACL in later slices. -->
+  <process id="registratie" name="Registratie ontvangen" isExecutable="true">
+
+    <startEvent id="start" name="Registratie ontvangen"/>
+
+    <sequenceFlow id="flow1" sourceRef="start" targetRef="OpenZaakAanmaken"/>
+
+    <serviceTask id="OpenZaakAanmaken" name="OpenZaak aanmaken"
+                 flowable:type="external-worker"
+                 flowable:topic="OpenZaakAanmaken"/>
+
+    <sequenceFlow id="flow2" sourceRef="OpenZaakAanmaken" targetRef="end"/>
+
+    <endEvent id="end" name="Zaak aangemaakt"/>
+  </process>
+
+  <bpmndi:BPMNDiagram id="diagram">
+    <bpmndi:BPMNPlane id="plane" bpmnElement="registratie">
+      <bpmndi:BPMNShape id="s_start" bpmnElement="start">
+        <omgdc:Bounds x="100" y="100" width="30" height="30"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="s_task" bpmnElement="OpenZaakAanmaken">
+        <omgdc:Bounds x="200" y="85" width="120" height="60"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="s_end" bpmnElement="end">
+        <omgdc:Bounds x="400" y="100" width="30" height="30"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="e_flow1" bpmnElement="flow1">
+        <omgdi:waypoint x="130" y="115"/>
+        <omgdi:waypoint x="200" y="115"/>
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="e_flow2" bpmnElement="flow2">
+        <omgdi:waypoint x="320" y="115"/>
+        <omgdi:waypoint x="400" y="115"/>
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</definitions>