chore: contributor workflow — issue/PR templates, git-cliff, gitea-workflow doc (refs #31)

Add the Gitea issue templates (slice/bug/adr-proposal) and a PR template
that carry the Definition of Done, a git-cliff config (cliff.toml) with a
`make changelog` target, the generated CHANGELOG.md, and docs/gitea-
workflow.md documenting the issue -> milestone -> PR flow.

Verified: make lint/build/unit green; `make changelog` regenerates the
changelog from Conventional Commits.

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

.gitignore

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

Makefile

@@ -8,8 +8,6 @@
 SLN        := services/bff/Bff.slnx
 COMPOSE    := infra/docker-compose.yml
 HEALTH_URL := http://localhost:8080/health
-OZ_COMPOSE := infra/openzaak/docker-compose.yml
-OZ_BASE    := http://localhost:8000
 
 # 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 +19,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 down changelog help
 
 ## ci: run the full pipeline — lint, build, unit, smoke (mirrors Gitea Actions)
 ci: lint build unit smoke
@@ -51,30 +49,6 @@ down:
 changelog:
 	git-cliff --output CHANGELOG.md
 
-## openzaak-up: start the OpenZaak stack (migrations run on first start)
-openzaak-up:
-	docker compose -f $(OZ_COMPOSE) up -d
-
-## openzaak-smoke: start OpenZaak, then assert it is up with auth enforced
-openzaak-smoke:
-	docker compose -f $(OZ_COMPOSE) up -d
-	@bash -c 'set -e; \
-	  echo "waiting for OpenZaak to respond..."; \
-	  for i in $$(seq 1 60); do \
-	    code=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/zaken/api/v1/zaken || true); \
-	    [ -n "$$code" ] && [ "$$code" != "000" ] && break; sleep 3; \
-	  done; \
-	  echo "GET /zaken/api/v1/zaken (unauth) -> $$code (expect 403, auth enforced)"; test "$$code" = "403"; \
-	  admin=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/admin/); \
-	  echo "GET /admin/             -> $$admin (expect 302)"; test "$$admin" = "302"; \
-	  root=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/zaken/api/v1/); \
-	  echo "GET /zaken/api/v1/      -> $$root (expect 200)"; test "$$root" = "200"; \
-	  echo "OpenZaak smoke OK"'
-
-## openzaak-down: stop and remove the OpenZaak stack (wipes data)
-openzaak-down:
-	docker compose -f $(OZ_COMPOSE) down --volumes
-
 ## help: list available targets
 help:
 	@grep -E '^## ' $(MAKEFILE_LIST) | sed 's/^## //'

README.md

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

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

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

docs/index.md

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

docs/runbooks/openzaak.md

@@ -1,50 +0,0 @@
-# OpenZaak runbook
-
-The OpenZaak stack (`infra/openzaak/docker-compose.yml`) is a lean adaptation of the
-upstream open-zaak dev compose: PostGIS db, redis, a one-shot init that runs
-migrations, the OpenZaak API, and a celery worker.
-
-## Quick test (`make`)
-
-```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-down     # stop and wipe data
-```
-
-`make openzaak-smoke` polls until the API responds, then asserts:
-
-| Check | Expected |
-|---|---|
-| `GET /zaken/api/v1/zaken` (no JWT) | **403** — `PermissionDenied` ZGW fout (auth enforced) |
-| `GET /admin/` | **302** — admin login redirect |
-| `GET /zaken/api/v1/` | **200** — ZGW API schema root |
-
-> **403, not 401.** OpenZaak's ZGW APIs return `403 PermissionDenied` for a missing
-> or invalid JWT. The S-01 acceptance text says "401" — that's inaccurate; 403 is the
-> correct auth-enforced response.
-
-The admin UI is at <http://localhost:8000/admin/>; the dev superuser is **admin /
-admin** (from the compose env — dev only).
-
-## Prerequisites (rootless Podman)
-
-Same setup as the rest of the repo (see [ci.md](ci.md)):
-
-```bash
-systemctl --user start podman.socket    # the Docker-API socket the shim talks to
-```
-
-The Makefile auto-points `DOCKER_HOST` at the Podman socket when it exists, so the
-`make openzaak-*` targets work without extra env.
-
-## Notes
-
-- **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`
-  zaaktype and a JWT client is the next slice (**S-01-b**); authenticated zaaktype
-  listing isn't testable until then.
-- **Image tag.** Currently `openzaak/open-zaak:latest` via `${OPENZAAK_TAG}`; pin to
-  a known-good tag as part of the catalogus-design ADR.

infra/openzaak/docker-compose.yml

@@ -1,88 +0,0 @@
-# OpenZaak stack (S-01). Lean adaptation of the upstream open-zaak dev compose:
-# db (PostGIS) + redis + a one-shot init (migrations) + the API + a celery worker.
-# Dropped from upstream for leanness: nginx, celery-beat, flower, OTEL.
-#
-#   docker compose -f infra/openzaak/docker-compose.yml up -d --wait
-#   curl -i http://localhost:8000/zaken/api/v1/zaken   # -> 401 (auth required)
-#
-# NOTE: image pinned to a tag (not :latest) once a known-good tag is chosen; see
-# the catalogus-design ADR. Using a tag var with a sensible default for now.
-services:
-  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"]
-      interval: 5s
-      timeout: 3s
-      retries: 10
-    networks: [oz]
-
-  oz-redis:
-    image: docker.io/library/redis:7
-    networks: [oz]
-
-  oz-init:
-    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
-    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"
-      OPENZAAK_SUPERUSER_USERNAME: admin
-      DJANGO_SUPERUSER_PASSWORD: admin
-      OPENZAAK_SUPERUSER_EMAIL: admin@localhost
-      RUN_SETUP_CONFIG: "false"
-    command: /setup_configuration.sh
-    depends_on:
-      oz-db:
-        condition: service_healthy
-      oz-redis:
-        condition: service_started
-    networks: [oz]
-
-  openzaak:
-    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
-    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: [oz]
-
-  oz-celery:
-    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
-    environment: *oz-env
-    command: /celery_worker.sh
-    depends_on:
-      oz-init:
-        condition: service_completed_successfully
-    networks: [oz]
-
-volumes:
-  oz-db:
-
-networks:
-  oz:

mkdocs.yml

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