test(ci): assert prerender output is only /hilfe/transkription

Addresses Sara's review request on #515.

Without this gate, a future regression that turns prerender.crawl
back on (or adds a new prerender entry whose nav links into
protected routes) would silently bake /, /documents, /persons etc.
to "redirect-to-login" HTML and re-introduce #514.

Verified the script catches the current broken build state:
  $ find build/prerendered ... -not -path 'hilfe/*' ...
  build/prerendered/{index,documents,persons,geschichten,stammbaum}.html

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

.claude/personas/architect.md

@@ -410,6 +410,23 @@ Never Kafka for teams under 10 or <100k events/day. Never gRPC inside a monolith
 4. Identify missing database-layer enforcement (constraints, RLS)
 5. Check transport choices — simpler protocol available?
 6. Propose a concrete simpler alternative, not just a critique
+7. Verify documentation currency. For each category below, check whether the PR triggered the update. Flag missing updates as blockers.
+
+| PR contains | Required doc update |
+|---|---|
+| New Flyway migration adding/removing/renaming a table or column | `docs/architecture/db/db-orm.puml` and `docs/architecture/db/db-relationships.puml` |
+| New `@ManyToMany` join table or FK | Both DB diagrams |
+| New backend package or domain module | `CLAUDE.md` package table + matching `docs/architecture/c4/l3-backend-*.puml` |
+| New controller or service in an existing backend domain | Matching `docs/architecture/c4/l3-backend-*.puml` |
+| New SvelteKit route | `CLAUDE.md` route table + matching `docs/architecture/c4/l3-frontend-*.puml` |
+| New Docker service or infrastructure component | `docs/architecture/c4/l2-containers.puml` + `docs/DEPLOYMENT.md` |
+| New external system integrated | `docs/architecture/c4/l1-context.puml` |
+| Auth or upload flow change | `docs/architecture/c4/seq-auth-flow.puml` or `docs/architecture/c4/seq-document-upload.puml` |
+| New `ErrorCode` or `Permission` value | `CLAUDE.md` + `docs/ARCHITECTURE.md` |
+| New domain concept or term | `docs/GLOSSARY.md` |
+| Architectural decision with lasting consequences | New ADR in `docs/adr/` |
+
+A doc omission is a blocker, not a concern — the PR does not merge until the diagram or text matches the code.
 
 ### Designing Systems
 1. Start with the data model — get the schema right before application code

.claude/personas/developer.md

@@ -980,6 +980,24 @@ Mark with `@pytest.mark.asyncio` so pytest runs the coroutine. Without it, the t
 5. Refactor — apply clean code, extract if 3+ duplications, rename for intent
 6. Repeat for the next behavior
 7. When all behaviors are green, review for SOLID violations across the full stack
+8. Update documentation before opening the PR. Use the table below to know which doc to touch.
+
+| What changed in code | Doc(s) to update |
+|---|---|
+| New Flyway migration adds/removes/renames a table or column | `docs/architecture/db/db-orm.puml` (add/remove entity or attribute) **and** `docs/architecture/db/db-relationships.puml` (add/remove relationship line) |
+| New `@ManyToMany` join table or FK relationship | Both DB diagrams above |
+| New backend package / domain module | `CLAUDE.md` (package structure table) **and** the matching `docs/architecture/c4/l3-backend-*.puml` diagram for that domain |
+| New Spring Boot controller or service in an existing domain | The matching `docs/architecture/c4/l3-backend-*.puml` for that domain |
+| New SvelteKit route (`+page.svelte`) | `CLAUDE.md` (route structure section) **and** the matching `docs/architecture/c4/l3-frontend-*.puml` diagram |
+| New Docker service / infrastructure component | `docs/architecture/c4/l2-containers.puml` **and** `docs/DEPLOYMENT.md` |
+| New external system integrated (new API, new S3 bucket, etc.) | `docs/architecture/c4/l1-context.puml` |
+| Auth flow or document-upload flow changes | `docs/architecture/c4/seq-auth-flow.puml` or `docs/architecture/c4/seq-document-upload.puml` |
+| New `ErrorCode` enum value | `CLAUDE.md` error handling section **and** `CONTRIBUTING.md` |
+| New `Permission` enum value | `CLAUDE.md` security section **and** `docs/ARCHITECTURE.md` |
+| New domain term introduced (entity name, status, concept) | `docs/GLOSSARY.md` |
+| Architectural decision with lasting consequences (new tech, new transport protocol, new pattern) | New ADR in `docs/adr/` |
+
+Skip a doc only if the change genuinely does not affect what that doc describes.
 
 ### Reviewing Code
 1. TDD evidence — are there tests? Do they precede the implementation?

.gitea/workflows/ci.yml

@@ -39,6 +39,48 @@ jobs:
       - name: Run unit and component tests
         run: npm test
         working-directory: frontend
+        env:
+          TZ: Europe/Berlin
+
+      - name: Run coverage (server + client)
+        run: npm run test:coverage
+        working-directory: frontend
+        env:
+          TZ: Europe/Berlin
+
+      - name: Upload coverage reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-reports
+          path: frontend/coverage/
+
+      - name: Build frontend
+        run: npm run build
+        working-directory: frontend
+
+      # ── Prerender output is exactly the public help page ───────────────────
+      # SvelteKit prerender + crawl follows nav links and bakes "redirect to
+      # /login" HTML for every protected route, served BEFORE runtime hooks
+      # (see #514). With `crawl: false` only the explicit entry should land
+      # in build/prerendered/. Anything else is a regression — fail the build.
+      - name: Assert prerender output is only /hilfe/transkription
+        run: |
+          cd frontend
+          set -e
+          extra=$(find build/prerendered -type f \
+                  -not -path 'build/prerendered/hilfe/*' \
+                  -not -name '*.br' -not -name '*.gz' \
+                  || true)
+          if [ -n "$extra" ]; then
+            echo "FAIL: unexpected prerendered files (would shadow runtime hooks):"
+            echo "$extra"
+            exit 1
+          fi
+          # And the help page must still be there.
+          test -f build/prerendered/hilfe/transkription.html \
+            || { echo "FAIL: /hilfe/transkription.html missing from prerender output"; exit 1; }
+          echo "PASS: only /hilfe/transkription.html prerendered."
 
       - name: Upload screenshots
         if: always()
@@ -74,6 +116,8 @@ jobs:
     runs-on: ubuntu-latest
     env:
       DOCKER_API_VERSION: "1.43"  # NAS runner runs Docker 24.x (max API 1.43); Testcontainers 2.x defaults to 1.44
+      DOCKER_HOST: unix:///var/run/docker.sock
+      TESTCONTAINERS_RYUK_DISABLED: "true"
     steps:
       - uses: actions/checkout@v4
 
@@ -93,4 +137,123 @@ jobs:
         run: |
           chmod +x mvnw
           ./mvnw clean test
-        working-directory: backend
+        working-directory: backend
+
+  # ─── fail2ban Regex Regression ────────────────────────────────────────────────
+  # The filter parses Caddy's JSON access log; a Caddy upgrade that reorders
+  # the JSON keys would silently break it (fail2ban-regex would return
+  # "0 matches", fail2ban would stop banning, no error surface). This job
+  # pins the contract against a deterministic sample line.
+  fail2ban-regex:
+    name: fail2ban Regex
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install fail2ban
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y fail2ban
+
+      - name: Matches /api/auth/login 401
+        run: |
+          echo '{"level":"info","ts":1700000000.12,"logger":"http.log.access","msg":"handled request","request":{"remote_ip":"203.0.113.42","method":"POST","host":"archiv.raddatz.cloud","uri":"/api/auth/login"},"status":401}' > /tmp/sample.log
+          out=$(fail2ban-regex /tmp/sample.log infra/fail2ban/filter.d/familienarchiv-auth.conf)
+          echo "$out"
+          echo "$out" | grep -qE '1 matched' \
+            || { echo "expected 1 match for /api/auth/login 401"; exit 1; }
+
+      - name: Matches /api/auth/login 429
+        run: |
+          echo '{"level":"info","ts":1700000000.12,"logger":"http.log.access","msg":"handled request","request":{"remote_ip":"203.0.113.42","method":"POST","host":"archiv.raddatz.cloud","uri":"/api/auth/login"},"status":429}' > /tmp/sample.log
+          out=$(fail2ban-regex /tmp/sample.log infra/fail2ban/filter.d/familienarchiv-auth.conf)
+          echo "$out"
+          echo "$out" | grep -qE '1 matched' \
+            || { echo "expected 1 match for /api/auth/login 429"; exit 1; }
+
+      - name: Matches /api/auth/forgot-password 401
+        run: |
+          echo '{"level":"info","ts":1700000000.12,"logger":"http.log.access","msg":"handled request","request":{"remote_ip":"203.0.113.42","method":"POST","host":"archiv.raddatz.cloud","uri":"/api/auth/forgot-password"},"status":401}' > /tmp/sample.log
+          out=$(fail2ban-regex /tmp/sample.log infra/fail2ban/filter.d/familienarchiv-auth.conf)
+          echo "$out"
+          echo "$out" | grep -qE '1 matched' \
+            || { echo "expected 1 match for /api/auth/forgot-password 401"; exit 1; }
+
+      - name: Does not match /api/auth/login 200
+        run: |
+          echo '{"level":"info","ts":1700000000.12,"logger":"http.log.access","msg":"handled request","request":{"remote_ip":"203.0.113.42","method":"POST","host":"archiv.raddatz.cloud","uri":"/api/auth/login"},"status":200}' > /tmp/sample.log
+          out=$(fail2ban-regex /tmp/sample.log infra/fail2ban/filter.d/familienarchiv-auth.conf)
+          echo "$out"
+          echo "$out" | grep -qE '0 matched' \
+            || { echo "expected 0 matches for /api/auth/login 200"; exit 1; }
+
+      - name: Does not match /api/documents (unrelated 401)
+        run: |
+          echo '{"level":"info","ts":1700000000.12,"logger":"http.log.access","msg":"handled request","request":{"remote_ip":"203.0.113.42","method":"GET","host":"archiv.raddatz.cloud","uri":"/api/documents"},"status":401}' > /tmp/sample.log
+          out=$(fail2ban-regex /tmp/sample.log infra/fail2ban/filter.d/familienarchiv-auth.conf)
+          echo "$out"
+          echo "$out" | grep -qE '0 matched' \
+            || { echo "expected 0 matches for /api/documents 401"; exit 1; }
+
+      # ── Backend resolves to file-polling, not systemd ─────────────────────
+      # The Debian/Ubuntu fail2ban package ships defaults-debian.conf with
+      # `[DEFAULT] backend = systemd`. Without `backend = polling` in our
+      # jail, the daemon loads the jail but reads from journald and never
+      # touches /var/log/caddy/access.log — i.e. the regex above passes in
+      # isolation while the live jail is inert. See issue #503.
+      - name: Jail resolves with polling backend (not inherited systemd)
+        run: |
+          sudo ln -sfn "$PWD/infra/fail2ban/jail.d/familienarchiv.conf"       /etc/fail2ban/jail.d/familienarchiv.conf
+          sudo ln -sfn "$PWD/infra/fail2ban/filter.d/familienarchiv-auth.conf" /etc/fail2ban/filter.d/familienarchiv-auth.conf
+          dump=$(sudo fail2ban-client -d 2>&1)
+          echo "$dump" | grep -E "add.*familienarchiv-auth" || true
+          echo "$dump" | grep -qE "\['add', 'familienarchiv-auth', 'polling'\]" \
+            || { echo "FAIL: familienarchiv-auth jail did not resolve to 'polling' backend"; exit 1; }
+
+  # ─── Compose Bucket-Bootstrap Idempotency ─────────────────────────────────────
+  # docker-compose.prod.yml's create-buckets service runs on every
+  # `docker compose up` (one-shot, no restart). Must be idempotent — a
+  # re-deploy must not fail just because the bucket / user / policy
+  # already exists. Validated by running create-buckets twice against a
+  # throwaway minio stack and asserting both invocations exit 0.
+  compose-idempotency:
+    name: Compose Bucket Idempotency
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Write stub env file
+        run: |
+          cat > .env.test <<'EOF'
+          TAG=test
+          PORT_BACKEND=18080
+          PORT_FRONTEND=13000
+          APP_DOMAIN=localhost
+          POSTGRES_PASSWORD=stub
+          MINIO_PASSWORD=stubrootpassword
+          MINIO_APP_PASSWORD=stubapppassword
+          OCR_TRAINING_TOKEN=stub
+          APP_ADMIN_USERNAME=admin@local
+          APP_ADMIN_PASSWORD=stub
+          MAIL_HOST=mailpit
+          MAIL_PORT=1025
+          APP_MAIL_FROM=noreply@local
+          EOF
+
+      - name: Bring up minio
+        run: |
+          docker compose -f docker-compose.prod.yml -p test-idem --env-file .env.test up -d --wait minio
+
+      - name: First create-buckets run
+        run: |
+          docker compose -f docker-compose.prod.yml -p test-idem --env-file .env.test run --rm create-buckets
+
+      - name: Second create-buckets run (idempotency check)
+        run: |
+          docker compose -f docker-compose.prod.yml -p test-idem --env-file .env.test run --rm create-buckets
+
+      - name: Teardown
+        if: always()
+        run: |
+          docker compose -f docker-compose.prod.yml -p test-idem --env-file .env.test down -v
+          rm -f .env.test

.gitea/workflows/nightly.yml

@@ -0,0 +1,138 @@
+name: nightly
+
+# Builds and deploys the staging environment from main every night.
+# Runs on the self-hosted runner using Docker-out-of-Docker (the docker
+# socket is mounted in), so `docker compose build` produces images on
+# the host daemon and `docker compose up` consumes them directly — no
+# registry hop.
+#
+# Operational assumptions (see docs/DEPLOYMENT.md §3 for the full setup):
+#
+#   1. Single-tenant self-hosted runner. The "Write staging env file" step
+#      writes every secret to .env.staging on the runner filesystem; the
+#      `if: always()` cleanup step removes it. A multi-tenant runner
+#      would need to switch to docker compose --env-file <(stdin) instead.
+#
+#   2. Host docker layer cache is authoritative. There is no
+#      actions/cache; we rely on the host daemon to keep Maven and npm
+#      layers warm between runs. A `docker system prune` on the host
+#      will cause the next nightly build to be cold (5–10 min slower).
+#
+# Staging environment isolation:
+#   - project name: archiv-staging
+#   - host ports:   backend 8081, frontend 3001
+#   - profile:      staging (starts mailpit instead of a real SMTP relay)
+#
+# Required Gitea secrets:
+#   STAGING_POSTGRES_PASSWORD
+#   STAGING_MINIO_PASSWORD
+#   STAGING_MINIO_APP_PASSWORD
+#   STAGING_OCR_TRAINING_TOKEN
+#   STAGING_APP_ADMIN_USERNAME
+#   STAGING_APP_ADMIN_PASSWORD
+
+on:
+  schedule:
+    - cron: "0 2 * * *"
+  workflow_dispatch:
+
+env:
+  # Ensures the backend Dockerfile's `RUN --mount=type=cache` lines are
+  # honoured (Maven cache survives between runs).
+  DOCKER_BUILDKIT: "1"
+
+jobs:
+  deploy-staging:
+    # `ubuntu-latest` matches our self-hosted runner's advertised label
+    # (the runner has labels: ubuntu-latest / ubuntu-24.04 / ubuntu-22.04).
+    # `self-hosted` would never match — no runner advertises it — so the
+    # job parks in the queue forever. ADR-011's "single-tenant" promise
+    # is at the repo level; sharing this runner between CI and deploys
+    # for the same repo is within that boundary.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Write staging env file
+        run: |
+          cat > .env.staging <<EOF
+          TAG=nightly
+          PORT_BACKEND=8081
+          PORT_FRONTEND=3001
+          APP_DOMAIN=staging.raddatz.cloud
+          POSTGRES_PASSWORD=${{ secrets.STAGING_POSTGRES_PASSWORD }}
+          MINIO_PASSWORD=${{ secrets.STAGING_MINIO_PASSWORD }}
+          MINIO_APP_PASSWORD=${{ secrets.STAGING_MINIO_APP_PASSWORD }}
+          OCR_TRAINING_TOKEN=${{ secrets.STAGING_OCR_TRAINING_TOKEN }}
+          APP_ADMIN_USERNAME=${{ secrets.STAGING_APP_ADMIN_USERNAME }}
+          APP_ADMIN_PASSWORD=${{ secrets.STAGING_APP_ADMIN_PASSWORD }}
+          MAIL_HOST=mailpit
+          MAIL_PORT=1025
+          MAIL_USERNAME=
+          MAIL_PASSWORD=
+          MAIL_SMTP_AUTH=false
+          MAIL_STARTTLS_ENABLE=false
+          APP_MAIL_FROM=noreply@staging.raddatz.cloud
+          EOF
+
+      - name: Build images
+        # `--pull` forces re-fetching pinned base images so a CVE
+        # re-publication of the same tag (e.g. node:20.19.0-alpine3.21,
+        # postgres:16-alpine) is picked up instead of being served
+        # from the host's stale Docker layer cache.
+        run: |
+          docker compose \
+            -f docker-compose.prod.yml \
+            -p archiv-staging \
+            --env-file .env.staging \
+            --profile staging \
+            build --pull
+
+      - name: Deploy staging
+        run: |
+          docker compose \
+            -f docker-compose.prod.yml \
+            -p archiv-staging \
+            --env-file .env.staging \
+            --profile staging \
+            up -d --wait --remove-orphans
+
+      - name: Smoke test deployed environment
+        # Healthchecks confirm containers are healthy; they do NOT confirm the
+        # public surface works. This step catches: Caddy not reloaded, HSTS
+        # header dropped, /actuator block bypassed.
+        #
+        # --resolve pins staging.raddatz.cloud to the runner's loopback so we
+        # do NOT depend on the host router doing hairpin NAT (many SOHO
+        # routers do not, or do so only after a firmware update). SNI still
+        # uses the public hostname so the cert validates correctly.
+        run: |
+          set -e
+          HOST="staging.raddatz.cloud"
+          URL="https://$HOST"
+          RESOLVE="--resolve $HOST:443:127.0.0.1"
+          echo "Smoke test: $URL (pinned to 127.0.0.1)"
+          curl -fsS $RESOLVE --max-time 10 "$URL/login" -o /dev/null
+          # Pin the preload-list-eligible HSTS value, not just header presence:
+          # a degraded `max-age=1` or a dropped `includeSubDomains; preload` must
+          # fail this check rather than pass it silently.
+          curl -fsS $RESOLVE --max-time 10 -I "$URL/" \
+            | grep -Eqi 'strict-transport-security:[[:space:]]*max-age=31536000.*includeSubDomains.*preload'
+          # Permissions-Policy denies APIs the app does not use (camera,
+          # microphone, geolocation). A regression that loosens or drops the
+          # header now fails the smoke step.
+          curl -fsS $RESOLVE --max-time 10 -I "$URL/" \
+            | grep -Eqi 'permissions-policy:[[:space:]]*camera=\(\),[[:space:]]*microphone=\(\),[[:space:]]*geolocation=\(\)'
+          status=$(curl -s $RESOLVE -o /dev/null -w "%{http_code}" --max-time 10 "$URL/actuator/health")
+          [ "$status" = "404" ] || { echo "expected 404 from /actuator/health, got $status"; exit 1; }
+          echo "All smoke checks passed"
+
+      - name: Cleanup env file
+        # LOAD-BEARING: `if: always()` is the linchpin of the ADR-011
+        # single-tenant runner trust model. Every secret in .env.staging
+        # is plain text on the runner filesystem until this step runs.
+        # If a future refactor drops `if: always()`, a failed deploy
+        # leaves the env-file behind. Do not remove this conditional
+        # without first re-evaluating ADR-011.
+        if: always()
+        run: rm -f .env.staging

.gitea/workflows/release.yml

@@ -0,0 +1,128 @@
+name: release
+
+# Builds and deploys the production environment on `v*` tag push.
+# Runs on the self-hosted runner via Docker-out-of-Docker; images are
+# tagged with the actual git tag (e.g. v1.0.0) so rollback is
+#   `TAG=<previous> docker compose -f docker-compose.prod.yml -p archiv-production up -d --wait`
+#
+# Operational assumptions (see docs/DEPLOYMENT.md §3 for the full setup):
+#
+#   1. Single-tenant self-hosted runner. The "Write production env file"
+#      step writes every secret to .env.production on the runner
+#      filesystem; the `if: always()` cleanup step removes it. A
+#      multi-tenant runner would need to switch to
+#      `docker compose --env-file <(stdin)` instead.
+#
+#   2. Host docker layer cache is authoritative. There is no
+#      actions/cache; we rely on the host daemon to keep Maven and npm
+#      layers warm between runs. A `docker system prune` on the host
+#      will cause the next release build to be cold (5–10 min slower).
+#
+# Production environment:
+#   - project name: archiv-production
+#   - host ports:   backend 8080, frontend 3000
+#   - profile:      (none) — mailpit is excluded; real SMTP relay is used
+#
+# Required Gitea secrets:
+#   PROD_POSTGRES_PASSWORD
+#   PROD_MINIO_PASSWORD
+#   PROD_MINIO_APP_PASSWORD
+#   PROD_OCR_TRAINING_TOKEN
+#   PROD_APP_ADMIN_USERNAME       (CRITICAL: see docs/DEPLOYMENT.md)
+#   PROD_APP_ADMIN_PASSWORD       (CRITICAL: locked in on first deploy)
+#   MAIL_HOST
+#   MAIL_PORT
+#   MAIL_USERNAME
+#   MAIL_PASSWORD
+
+on:
+  push:
+    tags:
+      - "v*"
+
+env:
+  DOCKER_BUILDKIT: "1"
+
+jobs:
+  deploy-production:
+    # See nightly.yml — same rationale: `ubuntu-latest` matches the
+    # advertised label of our single-tenant self-hosted runner.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Write production env file
+        run: |
+          cat > .env.production <<EOF
+          TAG=${{ gitea.ref_name }}
+          PORT_BACKEND=8080
+          PORT_FRONTEND=3000
+          APP_DOMAIN=archiv.raddatz.cloud
+          POSTGRES_PASSWORD=${{ secrets.PROD_POSTGRES_PASSWORD }}
+          MINIO_PASSWORD=${{ secrets.PROD_MINIO_PASSWORD }}
+          MINIO_APP_PASSWORD=${{ secrets.PROD_MINIO_APP_PASSWORD }}
+          OCR_TRAINING_TOKEN=${{ secrets.PROD_OCR_TRAINING_TOKEN }}
+          APP_ADMIN_USERNAME=${{ secrets.PROD_APP_ADMIN_USERNAME }}
+          APP_ADMIN_PASSWORD=${{ secrets.PROD_APP_ADMIN_PASSWORD }}
+          MAIL_HOST=${{ secrets.MAIL_HOST }}
+          MAIL_PORT=${{ secrets.MAIL_PORT }}
+          MAIL_USERNAME=${{ secrets.MAIL_USERNAME }}
+          MAIL_PASSWORD=${{ secrets.MAIL_PASSWORD }}
+          MAIL_SMTP_AUTH=true
+          MAIL_STARTTLS_ENABLE=true
+          APP_MAIL_FROM=noreply@raddatz.cloud
+          EOF
+
+      - name: Build images
+        # `--pull` forces re-fetching pinned base images so a CVE
+        # re-publication of the same tag is picked up rather than served
+        # from the host's stale Docker layer cache.
+        run: |
+          docker compose \
+            -f docker-compose.prod.yml \
+            -p archiv-production \
+            --env-file .env.production \
+            build --pull
+
+      - name: Deploy production
+        run: |
+          docker compose \
+            -f docker-compose.prod.yml \
+            -p archiv-production \
+            --env-file .env.production \
+            up -d --wait --remove-orphans
+
+      - name: Smoke test deployed environment
+        # See nightly.yml — same three checks, against the prod vhost.
+        # --resolve pins archiv.raddatz.cloud to the runner's loopback so
+        # the smoke test does NOT depend on hairpin NAT on the host router.
+        run: |
+          set -e
+          HOST="archiv.raddatz.cloud"
+          URL="https://$HOST"
+          RESOLVE="--resolve $HOST:443:127.0.0.1"
+          echo "Smoke test: $URL (pinned to 127.0.0.1)"
+          curl -fsS $RESOLVE --max-time 10 "$URL/login" -o /dev/null
+          # Pin the preload-list-eligible HSTS value, not just header presence:
+          # a degraded `max-age=1` or a dropped `includeSubDomains; preload` must
+          # fail this check rather than pass it silently.
+          curl -fsS $RESOLVE --max-time 10 -I "$URL/" \
+            | grep -Eqi 'strict-transport-security:[[:space:]]*max-age=31536000.*includeSubDomains.*preload'
+          # Permissions-Policy denies APIs the app does not use (camera,
+          # microphone, geolocation). A regression that loosens or drops the
+          # header now fails the smoke step.
+          curl -fsS $RESOLVE --max-time 10 -I "$URL/" \
+            | grep -Eqi 'permissions-policy:[[:space:]]*camera=\(\),[[:space:]]*microphone=\(\),[[:space:]]*geolocation=\(\)'
+          status=$(curl -s $RESOLVE -o /dev/null -w "%{http_code}" --max-time 10 "$URL/actuator/health")
+          [ "$status" = "404" ] || { echo "expected 404 from /actuator/health, got $status"; exit 1; }
+          echo "All smoke checks passed"
+
+      - name: Cleanup env file
+        # LOAD-BEARING: `if: always()` is the linchpin of the ADR-011
+        # single-tenant runner trust model. Every secret in
+        # .env.production is plain text on the runner filesystem until
+        # this step runs. If a future refactor drops `if: always()`, a
+        # failed deploy leaves the env-file behind. Do not remove this
+        # conditional without first re-evaluating ADR-011.
+        if: always()
+        run: rm -f .env.production

.gitignore

@@ -18,5 +18,11 @@ scripts/large-data.sql
 .claude/worktrees/
 .claude/scheduled_tasks.lock
 
+# Run artifacts from verification tooling
+proofshot-artifacts/
+
+# Root-level Node.js tooling artifacts
+node_modules/
+
 # Repo uses npm; yarn.lock is ignored to avoid double-lockfile drift.
 frontend/yarn.lock

.vscode/settings.json

@@ -1,4 +1,6 @@
 {
     "java.configuration.updateBuildConfiguration": "interactive",
-    "java.compile.nullAnalysis.mode": "automatic"
+    "java.compile.nullAnalysis.mode": "automatic",
+    "plantuml.render": "PlantUMLServer",
+    "plantuml.server": "http://heim-nas:8500"
 }

backend/pom.xml

@@ -190,6 +190,13 @@
 			<artifactId>owasp-java-html-sanitizer</artifactId>
 			<version>20240325.1</version>
 		</dependency>
+
+		<!-- HTML → plain-text extraction for comment previews -->
+		<dependency>
+			<groupId>org.jsoup</groupId>
+			<artifactId>jsoup</artifactId>
+			<version>1.18.1</version>
+		</dependency>
 	</dependencies>
 
 

backend/src/main/java/org/raddatz/familienarchiv/dashboard/ActivityFeedItemDTO.java

@@ -29,5 +29,11 @@ public record ActivityFeedItemDTO(
                 requiredMode = Schema.RequiredMode.NOT_REQUIRED,
                 description = "Annotation associated with the comment; populated only for COMMENT_ADDED and MENTION_CREATED kinds."
         )
-        UUID annotationId
+        UUID annotationId,
+        @Nullable
+        @Schema(
+                requiredMode = Schema.RequiredMode.NOT_REQUIRED,
+                description = "Plain-text preview of the comment body (HTML stripped server-side, truncated to 120 chars); null for non-comment feed items or deleted comments."
+        )
+        String commentPreview
 ) {}

backend/src/main/java/org/raddatz/familienarchiv/dashboard/DashboardService.java

@@ -12,6 +12,7 @@ import org.raddatz.familienarchiv.document.Document;
 import org.raddatz.familienarchiv.person.Person;
 import org.raddatz.familienarchiv.document.transcription.TranscriptionBlock;
 import org.raddatz.familienarchiv.document.comment.CommentService;
+import org.raddatz.familienarchiv.document.comment.CommentData;
 import org.raddatz.familienarchiv.document.DocumentService;
 import org.raddatz.familienarchiv.document.transcription.TranscriptionService;
 import org.raddatz.familienarchiv.user.UserService;
@@ -133,9 +134,9 @@ public class DashboardService {
                 .filter(Objects::nonNull)
                 .distinct()
                 .toList();
-        Map<UUID, UUID> annotationByComment = commentIds.isEmpty()
+        Map<UUID, CommentData> commentDataByComment = commentIds.isEmpty()
                 ? Map.of()
-                : commentService.findAnnotationIdsByIds(commentIds);
+                : commentService.findDataByIds(commentIds);
 
         return rows.stream().map(row -> {
             ActivityActorDTO actor = row.getActorId() != null
@@ -146,7 +147,10 @@ public class DashboardService {
                     ? row.getHappenedAtUntil().atOffset(ZoneOffset.UTC)
                     : null;
             UUID commentId = row.getCommentId();
-            UUID annotationId = commentId != null ? annotationByComment.get(commentId) : null;
+            CommentData commentData = commentId != null ? commentDataByComment.get(commentId) : null;
+            UUID annotationId = commentData != null ? commentData.annotationId() : null;
+            String commentPreview = commentData != null && !commentData.preview().isBlank()
+                    ? commentData.preview() : null;
             return new ActivityFeedItemDTO(
                     org.raddatz.familienarchiv.audit.AuditKind.valueOf(row.getKind()),
                     actor,
@@ -158,7 +162,8 @@ public class DashboardService {
                     row.getCount(),
                     happenedAtUntil,
                     commentId,
-                    annotationId
+                    annotationId,
+                    commentPreview
             );
         }).toList();
     }

backend/src/main/java/org/raddatz/familienarchiv/dashboard/StatsDTO.java

@@ -1,7 +1,12 @@
 package org.raddatz.familienarchiv.dashboard;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
  * Aggregate counts for the dashboard/persons stats bar.
  */
-public record StatsDTO(long totalPersons, long totalDocuments) {
+public record StatsDTO(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) long totalPersons,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) long totalDocuments,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) long totalStories) {
 }

backend/src/main/java/org/raddatz/familienarchiv/dashboard/StatsService.java

@@ -2,6 +2,7 @@ package org.raddatz.familienarchiv.dashboard;
 
 import lombok.RequiredArgsConstructor;
 import org.raddatz.familienarchiv.document.DocumentService;
+import org.raddatz.familienarchiv.geschichte.GeschichteService;
 import org.raddatz.familienarchiv.person.PersonService;
 import org.raddatz.familienarchiv.dashboard.StatsDTO;
 import org.springframework.stereotype.Service;
@@ -12,8 +13,9 @@ public class StatsService {
 
     private final PersonService personService;
     private final DocumentService documentService;
+    private final GeschichteService geschichteService;
 
     public StatsDTO getStats() {
-        return new StatsDTO(personService.count(), documentService.count());
+        return new StatsDTO(personService.count(), documentService.count(), geschichteService.countPublished());
     }
 }

backend/src/main/java/org/raddatz/familienarchiv/document/DensityFilters.java

@@ -0,0 +1,23 @@
+package org.raddatz.familienarchiv.document;
+
+import org.raddatz.familienarchiv.tag.TagOperator;
+
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * The non-date filters honoured by {@link DocumentService#getDensity(DensityFilters)}.
+ * Date bounds (from/to) are deliberately excluded — see the service Javadoc for why.
+ *
+ * Kept as a record so the seven values are passed as one named bundle instead of a
+ * positional argument list where two UUIDs (sender vs. receiver) can be swapped by
+ * accident at the call site.
+ */
+public record DensityFilters(
+        String text,
+        UUID sender,
+        UUID receiver,
+        List<String> tags,
+        String tagQ,
+        DocumentStatus status,
+        TagOperator tagOperator) {}

backend/src/main/java/org/raddatz/familienarchiv/document/DocumentController.java

@@ -3,6 +3,7 @@ package org.raddatz.familienarchiv.document;
 import java.io.IOException;
 import java.time.LocalDate;
 import java.util.ArrayList;
+import java.util.concurrent.TimeUnit;
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
@@ -48,6 +49,7 @@ import org.raddatz.familienarchiv.filestorage.FileService;
 import org.raddatz.familienarchiv.user.UserService;
 import org.springframework.data.domain.Sort;
 import org.springframework.security.core.Authentication;
+import org.springframework.http.CacheControl;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
@@ -388,6 +390,23 @@ public class DocumentController {
         return ResponseEntity.ok(documentService.searchDocuments(q, from, to, senderId, receiverId, tags, tagQ, status, sort, dir, operator, pageable));
     }
 
+    @GetMapping(value = "/density", produces = MediaType.APPLICATION_JSON_VALUE)
+    public ResponseEntity<DocumentDensityResult> density(
+            @RequestParam(required = false) String q,
+            @RequestParam(required = false) UUID senderId,
+            @RequestParam(required = false) UUID receiverId,
+            @RequestParam(required = false, name = "tag") List<String> tags,
+            @RequestParam(required = false) String tagQ,
+            @Parameter(description = "Filter by document status") @RequestParam(required = false) DocumentStatus status,
+            @Parameter(description = "Tag operator: AND (default) or OR") @RequestParam(required = false) String tagOp) {
+        TagOperator operator = "OR".equalsIgnoreCase(tagOp) ? TagOperator.OR : TagOperator.AND;
+        DocumentDensityResult result = documentService.getDensity(
+                new DensityFilters(q, senderId, receiverId, tags, tagQ, status, operator));
+        return ResponseEntity.ok()
+                .cacheControl(CacheControl.maxAge(5, TimeUnit.MINUTES).cachePrivate())
+                .body(result);
+    }
+
     // --- TRAINING LABELS ---
 
     public record TrainingLabelRequest(String label, boolean enrolled) {}

backend/src/main/java/org/raddatz/familienarchiv/document/DocumentDensityResult.java

@@ -0,0 +1,27 @@
+package org.raddatz.familienarchiv.document;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.LocalDate;
+import java.util.List;
+
+/**
+ * Result of the timeline density aggregation.
+ *
+ * <p>{@code minDate} / {@code maxDate} are intentionally not marked
+ * {@code @Schema(requiredMode = REQUIRED)} — the empty-result case (no
+ * documents match the filter) returns them as {@code null}, which surfaces in
+ * the generated TypeScript as {@code minDate?: string | null}. Frontend code
+ * must treat them as optional.
+ */
+public record DocumentDensityResult(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        List<MonthBucket> buckets,
+        LocalDate minDate,
+        LocalDate maxDate
+) {
+    /** The "no documents match the filter" result, with no buckets and null date bounds. */
+    public static DocumentDensityResult empty() {
+        return new DocumentDensityResult(List.of(), null, null);
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/document/DocumentRepository.java

@@ -100,7 +100,45 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
             ORDER BY ts_rank(d.search_vector, q.pq) DESC,
                      d.meta_date DESC NULLS LAST
             """)
-    List<UUID> findRankedIdsByFts(@Param("query") String query);
+    // Unpaged path — for bulk-edit "select all" and density chart
+    List<UUID> findAllMatchingIdsByFts(@Param("query") String query);
+
+    /**
+     * Returns one page of FTS-ranked document IDs with the total match count.
+     *
+     * <p>Each row contains (in column order):
+     * <ol>
+     *   <li>UUID   — document id</li>
+     *   <li>double — ts_rank score</li>
+     *   <li>long   — COUNT(*) OVER () — full match count, not page count</li>
+     * </ol>
+     *
+     * <p>Returns an empty list when the query matches no documents (including
+     * stopword-only queries where websearch_to_tsquery returns an empty tsquery).
+     * Use findAllMatchingIdsByFts for the unpaged bulk-edit path.
+     */
+    @Query(nativeQuery = true, value = """
+            WITH q AS (
+                SELECT CASE WHEN websearch_to_tsquery('german', :query)::text <> ''
+                            THEN to_tsquery('simple', regexp_replace(
+                                     websearch_to_tsquery('german', :query)::text,
+                                     '''([^'']+)''',
+                                     '''\\1'':*',
+                                     'g'))
+                       END AS pq
+            ), matches AS (
+                SELECT d.id, ts_rank(d.search_vector, q.pq) AS rank
+                FROM documents d, q
+                WHERE d.search_vector @@ q.pq
+            )
+            SELECT id, rank, COUNT(*) OVER () AS total
+            FROM matches
+            ORDER BY rank DESC, id
+            OFFSET :offset LIMIT :limit
+            """)
+    List<Object[]> findFtsPageRaw(@Param("query") String query,
+                                  @Param("offset") int offset,
+                                  @Param("limit") int limit);
 
     /**
      * Returns match-enrichment data for a set of documents identified by their IDs.

backend/src/main/java/org/raddatz/familienarchiv/document/DocumentService.java

@@ -48,6 +48,7 @@ import java.io.IOException;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 import java.time.LocalDate;
+import java.time.YearMonth;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
@@ -125,6 +126,74 @@ public class DocumentService {
         return titles;
     }
 
+    /**
+     * Per-month document counts for the timeline density widget (issue #385).
+     *
+     * <p>Filter-reactive: the chart recomputes when other filters (sender,
+     * receiver, tag, q, status) change so it always matches the list it sits
+     * above. Date bounds (`from`/`to`) are deliberately omitted — the chart is
+     * the surface for picking those, so it must always span the broader space
+     * the user is selecting within.
+     *
+     * <p>Implementation note: groups in memory rather than via SQL GROUP BY
+     * because the existing {@link Specification} predicates compose easily
+     * with {@code findAll(spec)} and the archive size (≈5k docs) keeps this
+     * well under the 200ms p95 target. Cache-Control: max-age=300 on the
+     * controller layer absorbs repeated browse loads.
+     *
+     * <p>Tracked in issue #481 for re-evaluation when {@code documents > 50k}
+     * — at that scale move the aggregation into SQL (GROUP BY TO_CHAR(meta_date,
+     * 'YYYY-MM')) and accept that the criteria/specification surface needs a
+     * parallel native-query path.
+     */
+    public DocumentDensityResult getDensity(DensityFilters filters) {
+        List<UUID> ftsIds = resolveFtsIds(filters.text());
+        if (ftsIds != null && ftsIds.isEmpty()) {
+            return DocumentDensityResult.empty();
+        }
+        List<LocalDate> dates = loadFilteredDates(filters, ftsIds);
+        return aggregateByMonth(dates);
+    }
+
+    /**
+     * Returns the FTS-ranked document IDs when {@code text} is non-blank, or {@code null}
+     * when no full-text query is active. An empty list means the FTS query ran but
+     * matched zero documents — the caller short-circuits on that signal.
+     */
+    private List<UUID> resolveFtsIds(String text) {
+        if (!StringUtils.hasText(text)) return null;
+        return documentRepository.findAllMatchingIdsByFts(text);
+    }
+
+    /** Loads matching documents and projects to non-null {@link LocalDate}s. */
+    private List<LocalDate> loadFilteredDates(DensityFilters filters, List<UUID> ftsIds) {
+        boolean hasFts = ftsIds != null;
+        Specification<Document> spec = buildSearchSpec(
+                hasFts, ftsIds, null, null,
+                filters.sender(), filters.receiver(),
+                filters.tags(), filters.tagQ(),
+                filters.status(), filters.tagOperator());
+        return documentRepository.findAll(spec).stream()
+                .map(Document::getDocumentDate)
+                .filter(Objects::nonNull)
+                .toList();
+    }
+
+    /** Buckets {@code dates} into one {@link MonthBucket} per YYYY-MM and computes min/max. */
+    private DocumentDensityResult aggregateByMonth(List<LocalDate> dates) {
+        if (dates.isEmpty()) return DocumentDensityResult.empty();
+        Map<String, Integer> counts = new java.util.TreeMap<>();
+        for (LocalDate d : dates) {
+            counts.merge(YearMonth.from(d).toString(), 1, Integer::sum);
+        }
+        List<MonthBucket> buckets = counts.entrySet().stream()
+                .map(e -> new MonthBucket(e.getKey(), e.getValue()))
+                .toList();
+        LocalDate minDate = dates.stream().min(LocalDate::compareTo).orElse(null);
+        LocalDate maxDate = dates.stream().max(LocalDate::compareTo).orElse(null);
+        return new DocumentDensityResult(buckets, minDate, maxDate);
+    }
+
     /**
      * Lädt eine Datei hoch.
      * - Prüft, ob ein Eintrag (aus Excel) schon existiert.
@@ -416,7 +485,7 @@ public class DocumentService {
         boolean hasText = StringUtils.hasText(text);
         List<UUID> rankedIds = null;
         if (hasText) {
-            rankedIds = documentRepository.findRankedIdsByFts(text);
+            rankedIds = documentRepository.findAllMatchingIdsByFts(text);
             if (rankedIds.isEmpty()) return List.of();
         }
 
@@ -576,39 +645,43 @@ public class DocumentService {
     // 1. Allgemeine Suche (für das Suchfeld im Frontend)
     public DocumentSearchResult searchDocuments(String text, LocalDate from, LocalDate to, UUID sender, UUID receiver, List<String> tags, String tagQ, DocumentStatus status, DocumentSort sort, String dir, TagOperator tagOperator, Pageable pageable) {
         boolean hasText = StringUtils.hasText(text);
-        List<UUID> rankedIds = null;
 
+        // Pure-text RELEVANCE: push pagination into SQL — skip findAllMatchingIdsByFts entirely (ADR-008).
+        if (isPureTextRelevance(hasText, sort, from, to, sender, receiver, tags, tagQ, status)) {
+            return relevanceSortedPageFromSql(text, pageable);
+        }
+
+        List<UUID> rankedIds = null;
         if (hasText) {
-            rankedIds = documentRepository.findRankedIdsByFts(text);
+            rankedIds = documentRepository.findAllMatchingIdsByFts(text);
             if (rankedIds.isEmpty()) return DocumentSearchResult.of(List.of());
         }
 
         Specification<Document> spec = buildSearchSpec(
                 hasText, rankedIds, from, to, sender, receiver, tags, tagQ, status, tagOperator);
 
-        // SENDER, RECEIVER and RELEVANCE sorts load the full match set and slice in memory.
+        // SENDER and RECEIVER sorts load the full match set and slice in-memory.
         // JPA's Sort.by("sender.lastName") generates an INNER JOIN that silently drops
-        // documents with null sender/receivers; RELEVANCE maps a DB order to an external
-        // rank list. Cost scales linearly with match count — acceptable while documents
-        // stays under ~10k rows. Past that, replace with SQL-level LEFT JOIN sort.
+        // documents with null sender/receivers. Cost scales with match count —
+        // acceptable while documents stays under ~10k rows. (ADR-008)
         if (sort == DocumentSort.RECEIVER) {
+            // In-memory sort on page slice (≤ page size rows) — acceptable
             List<Document> sorted = sortByFirstReceiver(documentRepository.findAll(spec), dir);
             return buildResultPaged(pageSlice(sorted, pageable), text, pageable, sorted.size());
         }
         if (sort == DocumentSort.SENDER) {
+            // In-memory sort on page slice (≤ page size rows) — acceptable
             List<Document> sorted = sortBySender(documentRepository.findAll(spec), dir);
             return buildResultPaged(pageSlice(sorted, pageable), text, pageable, sorted.size());
         }
 
-        // RELEVANCE: default when text present and no explicit sort given
+        // RELEVANCE with active filters: load filtered subset and sort in-memory by rank.
         boolean useRankOrder = hasText && (sort == null || sort == DocumentSort.RELEVANCE);
         if (useRankOrder) {
-            List<Document> results = documentRepository.findAll(spec);
             Map<UUID, Integer> rankMap = new HashMap<>();
             for (int i = 0; i < rankedIds.size(); i++) rankMap.put(rankedIds.get(i), i);
-            List<Document> sorted = results.stream()
-                    .sorted(Comparator.comparingInt(
-                            doc -> rankMap.getOrDefault(doc.getId(), Integer.MAX_VALUE)))
+            List<Document> sorted = documentRepository.findAll(spec).stream()
+                    .sorted(Comparator.comparingInt(doc -> rankMap.getOrDefault(doc.getId(), Integer.MAX_VALUE)))
                     .toList();
             return buildResultPaged(pageSlice(sorted, pageable), text, pageable, sorted.size());
         }
@@ -619,6 +692,39 @@ public class DocumentService {
         return buildResultPaged(page.getContent(), text, pageable, page.getTotalElements());
     }
 
+    private static boolean isPureTextRelevance(boolean hasText, DocumentSort sort,
+            LocalDate from, LocalDate to, UUID sender, UUID receiver,
+            List<String> tags, String tagQ, DocumentStatus status) {
+        return hasText && (sort == null || sort == DocumentSort.RELEVANCE)
+                && from == null && to == null && sender == null && receiver == null
+                && (tags == null || tags.isEmpty()) && (tagQ == null || tagQ.isBlank()) && status == null;
+    }
+
+    /**
+     * Pure-text RELEVANCE path — pagination and ts_rank ordering pushed into SQL.
+     * Called when no non-text filters are active (ADR-008).
+     */
+    private DocumentSearchResult relevanceSortedPageFromSql(String text, Pageable pageable) {
+        long rawOffset = pageable.getOffset();
+        if (rawOffset > Integer.MAX_VALUE) return DocumentSearchResult.of(List.of());
+        int offset = (int) rawOffset;
+        int limit = pageable.getPageSize();
+        FtsPage ftsPage = toFtsPage(documentRepository.findFtsPageRaw(text, offset, limit));
+        if (ftsPage.hits().isEmpty()) return DocumentSearchResult.of(List.of());
+
+        // Preserve ts_rank order from SQL across the JPA findAllById call.
+        Map<UUID, Integer> rankMap = new HashMap<>();
+        List<UUID> pageIds = new ArrayList<>();
+        for (int i = 0; i < ftsPage.hits().size(); i++) {
+            rankMap.put(ftsPage.hits().get(i).id(), i);
+            pageIds.add(ftsPage.hits().get(i).id());
+        }
+        List<Document> docs = documentRepository.findAllById(pageIds).stream()
+                .sorted(Comparator.comparingInt(d -> rankMap.getOrDefault(d.getId(), Integer.MAX_VALUE)))
+                .toList();
+        return buildResultPaged(docs, text, pageable, ftsPage.total());
+    }
+
     private static <T> List<T> pageSlice(List<T> sorted, Pageable pageable) {
         int from = Math.min((int) pageable.getOffset(), sorted.size());
         int to = Math.min(from + pageable.getPageSize(), sorted.size());
@@ -658,6 +764,7 @@ public class DocumentService {
         return switch (sort) {
             case TITLE -> Sort.by(direction, "title");
             case UPLOAD_DATE -> Sort.by(direction, "createdAt");
+            case UPDATED_AT -> Sort.by(direction, "updatedAt");
             default -> Sort.by(direction, "documentDate");
         };
     }
@@ -943,6 +1050,28 @@ public class DocumentService {
         return result;
     }
 
+    private static final int COL_ID = 0;
+    private static final int COL_RANK = 1;
+    private static final int COL_TOTAL = 2;
+
+    /**
+     * Maps raw Object[] rows from {@link DocumentRepository#findFtsPageRaw} to an
+     * {@link FtsPage}. Uses pattern-matching UUID cast to guard against driver-level
+     * type variance (some JDBC drivers return UUID as String).
+     */
+    private static FtsPage toFtsPage(List<Object[]> rows) {
+        if (rows.isEmpty()) return new FtsPage(List.of(), 0);
+        long total = ((Number) rows.get(0)[COL_TOTAL]).longValue();
+        List<FtsHit> hits = rows.stream()
+                .map(r -> {
+                    UUID id = r[COL_ID] instanceof UUID u ? u : UUID.fromString(r[COL_ID].toString());
+                    double rank = ((Number) r[COL_RANK]).doubleValue();
+                    return new FtsHit(id, rank);
+                })
+                .toList();
+        return new FtsPage(hits, total);
+    }
+
     /** Clean text + highlight offsets parsed from a {@code ts_headline} sentinel-delimited string. */
     public record ParsedHighlight(String cleanText, List<MatchOffset> offsets) {}
 

backend/src/main/java/org/raddatz/familienarchiv/document/DocumentSort.java

@@ -1,5 +1,5 @@
 package org.raddatz.familienarchiv.document;
 
 public enum DocumentSort {
-    DATE, TITLE, SENDER, RECEIVER, UPLOAD_DATE, RELEVANCE
+    DATE, TITLE, SENDER, RECEIVER, UPLOAD_DATE, UPDATED_AT, RELEVANCE
 }

backend/src/main/java/org/raddatz/familienarchiv/document/FtsHit.java

@@ -0,0 +1,6 @@
+package org.raddatz.familienarchiv.document;
+
+import java.util.UUID;
+
+/** A single document hit from a paginated FTS query — id and its ts_rank score. */
+record FtsHit(UUID id, double rank) {}

backend/src/main/java/org/raddatz/familienarchiv/document/FtsPage.java

@@ -0,0 +1,6 @@
+package org.raddatz.familienarchiv.document;
+
+import java.util.List;
+
+/** One page of FTS results — the ranked hit list for this page and the total match count. */
+record FtsPage(List<FtsHit> hits, long total) {}

backend/src/main/java/org/raddatz/familienarchiv/document/MonthBucket.java

@@ -0,0 +1,10 @@
+package org.raddatz.familienarchiv.document;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+public record MonthBucket(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED, example = "1915-08")
+        String month,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        int count
+) {}

backend/src/main/java/org/raddatz/familienarchiv/document/comment/CommentController.java

@@ -27,7 +27,9 @@ public class CommentController {
     // ─── Block (transcription) comments ────────────────────────────────────────
 
     @GetMapping("/api/documents/{documentId}/transcription-blocks/{blockId}/comments")
-    public List<DocumentComment> getBlockComments(@PathVariable UUID blockId) {
+    public List<DocumentComment> getBlockComments(
+            @PathVariable UUID documentId,
+            @PathVariable UUID blockId) {
         return commentService.getCommentsForBlock(blockId);
     }
 
@@ -48,6 +50,7 @@ public class CommentController {
     @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment replyToBlockComment(
             @PathVariable UUID documentId,
+            @PathVariable UUID blockId,
             @PathVariable UUID commentId,
             @RequestBody CreateCommentDTO dto,
             Authentication authentication) {

backend/src/main/java/org/raddatz/familienarchiv/document/comment/CommentData.java

@@ -0,0 +1,6 @@
+package org.raddatz.familienarchiv.document.comment;
+
+import jakarta.annotation.Nullable;
+import java.util.UUID;
+
+public record CommentData(@Nullable UUID annotationId, String preview) {}

backend/src/main/java/org/raddatz/familienarchiv/document/comment/CommentService.java

@@ -13,6 +13,7 @@ import org.raddatz.familienarchiv.document.comment.DocumentComment;
 import org.raddatz.familienarchiv.document.transcription.TranscriptionBlock;
 import org.raddatz.familienarchiv.document.comment.CommentRepository;
 import org.raddatz.familienarchiv.notification.NotificationService;
+import org.jsoup.Jsoup;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
@@ -28,21 +29,29 @@ import java.util.UUID;
 @RequiredArgsConstructor
 public class CommentService {
 
+    private static final int PREVIEW_MAX_CHARS = 120;
+
     private final CommentRepository commentRepository;
     private final UserService userService;
     private final NotificationService notificationService;
     private final AuditService auditService;
     private final TranscriptionService transcriptionService;
 
-    public Map<UUID, UUID> findAnnotationIdsByIds(Collection<UUID> commentIds) {
+    public Map<UUID, CommentData> findDataByIds(Collection<UUID> commentIds) {
         if (commentIds == null || commentIds.isEmpty()) return Map.of();
-        Map<UUID, UUID> result = new HashMap<>();
+        Map<UUID, CommentData> result = new HashMap<>();
         for (DocumentComment c : commentRepository.findAllById(commentIds)) {
-            if (c.getAnnotationId() != null) result.put(c.getId(), c.getAnnotationId());
+            result.put(c.getId(), new CommentData(c.getAnnotationId(), stripAndTruncate(c.getContent())));
         }
         return result;
     }
 
+    private String stripAndTruncate(String html) {
+        if (html == null || html.isBlank()) return "";
+        String text = Jsoup.parse(html).text().trim();
+        return text.length() > PREVIEW_MAX_CHARS ? text.substring(0, PREVIEW_MAX_CHARS) : text;
+    }
+
     public List<DocumentComment> getCommentsForBlock(UUID blockId) {
         List<DocumentComment> roots = commentRepository.findByBlockIdAndParentIdIsNull(blockId);
         return withRepliesAndMentions(roots);

backend/src/main/java/org/raddatz/familienarchiv/exception/GlobalExceptionHandler.java

@@ -15,6 +15,7 @@ import org.springframework.web.server.ResponseStatusException;
 
 import lombok.extern.slf4j.Slf4j;
 
+// "Handler" is Spring's @RestControllerAdvice naming convention — not a generic suffix.
 @RestControllerAdvice
 @Slf4j
 public class GlobalExceptionHandler {

backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteService.java

@@ -56,6 +56,10 @@ public class GeschichteService {
 
     // ─── Read API ────────────────────────────────────────────────────────────
 
+    public long countPublished() {
+        return geschichteRepository.count(GeschichteSpecifications.hasStatus(GeschichteStatus.PUBLISHED));
+    }
+
     public Geschichte getById(UUID id) {
         Geschichte g = geschichteRepository.findById(id)
                 .orElseThrow(() -> DomainException.notFound(
@@ -77,8 +81,10 @@ public class GeschichteService {
         GeschichteStatus effective = currentUserHasBlogWrite() ? status : GeschichteStatus.PUBLISHED;
         int safeLimit = limit <= 0 ? DEFAULT_LIMIT : Math.min(limit, MAX_LIMIT);
 
+        UUID authorId = effective == GeschichteStatus.DRAFT ? currentUser().getId() : null;
         Specification<Geschichte> spec = Specification.allOf(
                 GeschichteSpecifications.hasStatus(effective),
+                GeschichteSpecifications.hasAuthor(authorId),
                 GeschichteSpecifications.hasAllPersons(personIds),
                 GeschichteSpecifications.hasDocument(documentId),
                 GeschichteSpecifications.orderByDisplayDateDesc()

backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteSpecifications.java

@@ -42,6 +42,12 @@ public final class GeschichteSpecifications {
         };
     }
 
+    // null authorId → no restriction (PUBLISHED path passes null; Spring Data skips null predicates)
+    public static Specification<Geschichte> hasAuthor(UUID authorId) {
+        return (root, query, cb) ->
+                authorId == null ? null : cb.equal(root.get("author").get("id"), authorId);
+    }
+
     public static Specification<Geschichte> hasDocument(UUID documentId) {
         return (root, query, cb) -> {
             if (documentId == null) return null;

backend/src/main/java/org/raddatz/familienarchiv/person/PersonController.java

@@ -35,7 +35,14 @@ public class PersonController {
 
     @GetMapping
     @RequirePermission(Permission.READ_ALL)
-    public ResponseEntity<List<PersonSummaryDTO>> getPersons(@RequestParam(required = false) String q) {
+    public ResponseEntity<List<PersonSummaryDTO>> getPersons(
+            @RequestParam(required = false) String q,
+            @RequestParam(required = false, defaultValue = "0") int size,
+            @RequestParam(required = false) String sort) {
+        if ("documentCount".equals(sort) && size > 0 && q == null) {
+            int safeSize = Math.min(size, 50);
+            return ResponseEntity.ok(personService.findTopByDocumentCount(safeSize));
+        }
         return ResponseEntity.ok(personService.findAll(q));
     }
 

backend/src/main/java/org/raddatz/familienarchiv/person/PersonRepository.java

@@ -69,6 +69,22 @@ public interface PersonRepository extends JpaRepository<Person, UUID> {
             nativeQuery = true)
     List<PersonSummaryDTO> searchWithDocumentCount(@Param("query") String query);
 
+    // ORDER BY uses the computed alias "documentCount" — valid PostgreSQL (aliases allowed in ORDER BY,
+    // unlike WHERE/HAVING). This is intentional; it would silently fail on MySQL or H2.
+    @Query(value = """
+            SELECT p.id, p.title, p.first_name AS firstName, p.last_name AS lastName,
+                   p.person_type AS personType,
+                   p.alias, p.birth_year AS birthYear, p.death_year AS deathYear, p.notes,
+                   p.family_member AS familyMember,
+                   (SELECT COUNT(*) FROM documents d WHERE d.sender_id = p.id)
+                   + (SELECT COUNT(*) FROM document_receivers dr WHERE dr.person_id = p.id) AS documentCount
+            FROM persons p
+            ORDER BY documentCount DESC
+            LIMIT :limit
+            """,
+            nativeQuery = true)
+    List<PersonSummaryDTO> findTopByDocumentCount(@Param("limit") int limit);
+
     // --- Correspondent queries ---
 
     @Query(value = """

backend/src/main/java/org/raddatz/familienarchiv/person/PersonService.java

@@ -41,6 +41,10 @@ public class PersonService {
         return personRepository.searchWithDocumentCount(q.trim());
     }
 
+    public List<PersonSummaryDTO> findTopByDocumentCount(int limit) {
+        return personRepository.findTopByDocumentCount(limit);
+    }
+
     public Person getById(UUID id) {
         return personRepository.findById(id)
                 .orElseThrow(() -> DomainException.notFound(ErrorCode.PERSON_NOT_FOUND, "Person not found: " + id));

backend/src/main/java/org/raddatz/familienarchiv/security/SecurityUtils.java

@@ -7,6 +7,7 @@ import org.springframework.security.core.Authentication;
 
 import java.util.UUID;
 
+// Cross-cutting auth helper; no domain home — "Utils" is the correct suffix here.
 public final class SecurityUtils {
 
     private SecurityUtils() {}

backend/src/main/java/org/raddatz/familienarchiv/user/AppUser.java

@@ -88,7 +88,8 @@ public class AppUser {
     };
 
     public static String computeColor(UUID id) {
-        return PALETTE[Math.abs(id.hashCode()) % PALETTE.length];
+        // Math.floorMod avoids the Integer.MIN_VALUE overflow trap in Math.abs(hashCode())
+        return PALETTE[Math.floorMod(id.hashCode(), PALETTE.length)];
     }
 
     @PrePersist

backend/src/main/java/org/raddatz/familienarchiv/user/UserService.java

@@ -271,9 +271,10 @@ public class UserService {
 
     @Transactional
     public UserGroup createGroup(GroupDTO dto) {
-        UserGroup group = new UserGroup();
-        group.setName(dto.getName());
-        group.setPermissions(dto.getPermissions());
+        UserGroup group = UserGroup.builder()
+                .name(dto.getName())
+                .permissions(dto.getPermissions() != null ? dto.getPermissions() : new HashSet<>())
+                .build();
         return groupRepository.save(group);
     }
 

backend/src/main/resources/application.yaml

@@ -38,6 +38,12 @@ spring:
           starttls:
             enable: true
 
+server:
+  # Behind Caddy/reverse proxy: trust X-Forwarded-{Proto,For,Host} so that
+  # request.getScheme(), redirect URLs, and Spring Session "Secure" cookies
+  # reflect the original https client request, not the http hop from Caddy.
+  forward-headers-strategy: native
+
 management:
   health:
     mail:

backend/src/main/resources/db/migration/V61__add_idx_documents_updated_at.sql

@@ -0,0 +1 @@
+CREATE INDEX IF NOT EXISTS idx_documents_updated_at ON documents(updated_at DESC);

backend/src/main/resources/db/migration/V62__index_fk_columns.sql

@@ -0,0 +1,8 @@
+-- Speeds up "documents by sender" queries used on /persons/[id] Korrespondenz-Überblick (#306),
+-- /briefwechsel, and bulk-edit flows.
+CREATE INDEX IF NOT EXISTS idx_documents_sender_id
+    ON documents(sender_id);
+
+-- Speeds up "comments by author" queries on admin user detail and (future) contributor profile.
+CREATE INDEX IF NOT EXISTS idx_comments_author_id
+    ON document_comments(author_id);

backend/src/main/resources/db/migration/V63__deduplicate_group_permissions.sql

@@ -0,0 +1,7 @@
+-- Remove duplicate (group_id, permission) rows that accumulated without a UNIQUE constraint.
+-- Keeps the row with the smallest ctid (earliest physical insertion order).
+DELETE FROM group_permissions a
+USING group_permissions b
+WHERE a.ctid < b.ctid
+  AND a.group_id = b.group_id
+  AND a.permission = b.permission;

backend/src/main/resources/db/migration/V64__group_permissions_primary_key.sql

@@ -0,0 +1,11 @@
+-- Add NOT NULL and PRIMARY KEY to group_permissions.
+-- Requires V63 to have run first (no duplicates can remain).
+--
+-- After this migration, future seed migrations can use:
+--   INSERT INTO group_permissions ... ON CONFLICT DO NOTHING
+-- instead of the INSERT ... WHERE NOT EXISTS pattern used before V64.
+ALTER TABLE group_permissions
+    ALTER COLUMN permission SET NOT NULL;
+
+ALTER TABLE group_permissions
+    ADD CONSTRAINT pk_group_permissions PRIMARY KEY (group_id, permission);

backend/src/main/resources/db/migration/V65__tbmp_promote_unique_to_pk.sql

@@ -0,0 +1,8 @@
+-- Promote the de-facto unique constraint on transcription_block_mentioned_persons to a named PK.
+-- uq_tbmp_block_person (added in V57) is backed by a B-tree index identical to a PK;
+-- this rename makes the naming convention explicit (pk_* vs uq_*).
+ALTER TABLE transcription_block_mentioned_persons
+    DROP CONSTRAINT uq_tbmp_block_person;
+
+ALTER TABLE transcription_block_mentioned_persons
+    ADD CONSTRAINT pk_tbmp PRIMARY KEY (block_id, person_id);

backend/src/test/java/org/raddatz/familienarchiv/MigrationIntegrationTest.java

@@ -399,6 +399,86 @@ class MigrationIntegrationTest {
               AND dc.annotation_id IS NOT NULL
             """;
 
+    // ─── V62: indexes on FK columns ──────────────────────────────────────────
+
+    @Test
+    void v62_idx_documents_sender_id_exists() {
+        Integer count = jdbc.queryForObject(
+                "SELECT COUNT(*) FROM pg_catalog.pg_indexes WHERE tablename = 'documents' AND indexname = 'idx_documents_sender_id'",
+                Integer.class);
+        assertThat(count).isEqualTo(1);
+    }
+
+    @Test
+    void v62_idx_comments_author_id_exists() {
+        Integer count = jdbc.queryForObject(
+                "SELECT COUNT(*) FROM pg_catalog.pg_indexes WHERE tablename = 'document_comments' AND indexname = 'idx_comments_author_id'",
+                Integer.class);
+        assertThat(count).isEqualTo(1);
+    }
+
+    // ─── V63+V64: group_permissions dedup + primary key ──────────────────────
+
+    @Test
+    void v64_pk_group_permissions_exists() {
+        Integer count = jdbc.queryForObject(
+                """
+                SELECT COUNT(*) FROM pg_catalog.pg_constraint c
+                JOIN pg_catalog.pg_class t ON c.conrelid = t.oid
+                WHERE t.relname = 'group_permissions'
+                  AND c.conname = 'pk_group_permissions'
+                  AND c.contype = 'p'
+                """,
+                Integer.class);
+        assertThat(count).isEqualTo(1);
+    }
+
+    @Test
+    void v64_permission_column_isNotNullable() {
+        Integer count = jdbc.queryForObject(
+                """
+                SELECT COUNT(*) FROM information_schema.columns
+                WHERE table_schema = 'public'
+                  AND table_name = 'group_permissions'
+                  AND column_name = 'permission'
+                  AND is_nullable = 'NO'
+                """,
+                Integer.class);
+        assertThat(count).isEqualTo(1);
+    }
+
+    @Test
+    @Transactional(propagation = Propagation.NOT_SUPPORTED)
+    void v64_rejectsDuplicateGroupPermission() {
+        UUID groupId = createUserGroup("DuplicateTestGroup-" + UUID.randomUUID());
+        try {
+            jdbc.update("INSERT INTO group_permissions (group_id, permission) VALUES (?, 'READ_ALL')", groupId);
+
+            assertThatThrownBy(() ->
+                    jdbc.update("INSERT INTO group_permissions (group_id, permission) VALUES (?, 'READ_ALL')", groupId)
+            ).isInstanceOf(DataIntegrityViolationException.class);
+        } finally {
+            jdbc.update("DELETE FROM group_permissions WHERE group_id = ?", groupId);
+            jdbc.update("DELETE FROM user_groups WHERE id = ?", groupId);
+        }
+    }
+
+    // ─── V65: tbmp UNIQUE promoted to PRIMARY KEY ─────────────────────────────
+
+    @Test
+    void v65_pk_tbmp_exists() {
+        Integer count = jdbc.queryForObject(
+                """
+                SELECT COUNT(*) FROM pg_catalog.pg_constraint c
+                JOIN pg_catalog.pg_class t ON c.conrelid = t.oid
+                WHERE t.relname = 'transcription_block_mentioned_persons'
+                  AND c.conname = 'pk_tbmp'
+                  AND c.contype = 'p'
+                """,
+                Integer.class);
+        assertThat(count).isEqualTo(1);
+    }
+
     // ─── helpers ─────────────────────────────────────────────────────────────
 
     private UUID createPerson(String firstName, String lastName) {
@@ -482,4 +562,10 @@ class MigrationIntegrationTest {
                 """, id, recipientId, docId, commentId);
         return id;
     }
+
+    private UUID createUserGroup(String name) {
+        UUID id = UUID.randomUUID();
+        jdbc.update("INSERT INTO user_groups (id, name) VALUES (?, ?)", id, name);
+        return id;
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/config/ForwardHeadersConfigurationTest.java

@@ -0,0 +1,48 @@
+package org.raddatz.familienarchiv.config;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.config.YamlPropertiesFactoryBean;
+import org.springframework.boot.web.server.autoconfigure.ServerProperties.ForwardHeadersStrategy;
+import org.springframework.boot.context.properties.bind.Binder;
+import org.springframework.boot.context.properties.source.ConfigurationPropertySources;
+import org.springframework.core.env.PropertiesPropertySource;
+import org.springframework.core.io.ClassPathResource;
+
+import java.util.Properties;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Binds {@code server.forward-headers-strategy} from {@code application.yaml} into
+ * Spring Boot's typed {@link ForwardHeadersStrategy} enum. The binder rejects any
+ * value that is not a valid enum constant ({@code BindException}), so a typo
+ * ({@code "nativ"}, {@code "Native"}, {@code "framework "}) or a future Spring
+ * rename of the property fails the test, not silently degrades to {@code NONE}.
+ *
+ * <p>No Spring context, no embedded server, no Testcontainers — this is the
+ * cheapest test that pins the contract "Caddy's X-Forwarded-Proto is trusted".
+ */
+class ForwardHeadersConfigurationTest {
+
+    @Test
+    void forward_headers_strategy_binds_to_NATIVE() {
+        YamlPropertiesFactoryBean yaml = new YamlPropertiesFactoryBean();
+        yaml.setResources(new ClassPathResource("application.yaml"));
+        Properties props = yaml.getObject();
+        assertThat(props).as("application.yaml must be on the classpath").isNotNull();
+
+        Binder binder = new Binder(ConfigurationPropertySources.from(
+            new PropertiesPropertySource("application", props)));
+
+        ForwardHeadersStrategy strategy = binder
+            .bind("server.forward-headers-strategy", ForwardHeadersStrategy.class)
+            .orElseThrow(() -> new AssertionError(
+                "server.forward-headers-strategy is missing from application.yaml"));
+
+        assertThat(strategy)
+            .as("Spring must trust X-Forwarded-Proto from Caddy so that "
+                + "request.getScheme(), redirect URLs, and the Spring Session "
+                + "'Secure' cookie reflect the original https client request.")
+            .isEqualTo(ForwardHeadersStrategy.NATIVE);
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/dashboard/DashboardServiceTest.java

@@ -13,6 +13,7 @@ import org.raddatz.familienarchiv.user.AppUser;
 import org.raddatz.familienarchiv.document.Document;
 import org.raddatz.familienarchiv.document.transcription.TranscriptionBlock;
 import org.raddatz.familienarchiv.document.comment.CommentService;
+import org.raddatz.familienarchiv.document.comment.CommentData;
 import org.raddatz.familienarchiv.document.DocumentService;
 import org.raddatz.familienarchiv.document.transcription.TranscriptionService;
 import org.raddatz.familienarchiv.user.UserService;
@@ -142,7 +143,8 @@ class DashboardServiceTest {
         when(documentService.getDocumentsByIds(List.of(docId))).thenReturn(List.of(
                 Document.builder().id(docId).title("B").originalFilename("b.pdf").receivers(new HashSet<>()).build()
         ));
-        when(commentService.findAnnotationIdsByIds(List.of(commentId))).thenReturn(Map.of());
+        when(commentService.findDataByIds(List.of(commentId)))
+                .thenReturn(Map.of(commentId, new CommentData(null, "preview text")));
 
         List<ActivityFeedItemDTO> items = dashboardService.getActivity(userId, 5, AuditKind.ROLLUP_ELIGIBLE);
 
@@ -162,8 +164,8 @@ class DashboardServiceTest {
         when(documentService.getDocumentsByIds(List.of(docId))).thenReturn(List.of(
                 Document.builder().id(docId).title("B").originalFilename("b.pdf").receivers(new HashSet<>()).build()
         ));
-        when(commentService.findAnnotationIdsByIds(List.of(commentId)))
-                .thenReturn(Map.of(commentId, annotationId));
+        when(commentService.findDataByIds(List.of(commentId)))
+                .thenReturn(Map.of(commentId, new CommentData(annotationId, "preview text")));
 
         List<ActivityFeedItemDTO> items = dashboardService.getActivity(userId, 5, AuditKind.ROLLUP_ELIGIBLE);
 
@@ -187,7 +189,62 @@ class DashboardServiceTest {
         assertThat(items).hasSize(1);
         assertThat(items.get(0).commentId()).isNull();
         assertThat(items.get(0).annotationId()).isNull();
-        verify(commentService, never()).findAnnotationIdsByIds(anyList());
+        verify(commentService, never()).findDataByIds(anyList());
+    }
+
+    // ─── getActivity commentPreview ───────────────────────────────────────────
+
+    @Test
+    void getActivity_populates_commentPreview_for_COMMENT_ADDED_rows() {
+        UUID userId = UUID.randomUUID();
+        UUID docId = UUID.randomUUID();
+        UUID commentId = UUID.randomUUID();
+
+        ActivityFeedRow row = mockFeedRow(docId, "COMMENT_ADDED", commentId);
+        when(auditLogQueryService.findActivityFeed(userId, 5, AuditKind.ROLLUP_ELIGIBLE)).thenReturn(List.of(row));
+        when(documentService.getDocumentsByIds(List.of(docId))).thenReturn(List.of(
+                Document.builder().id(docId).title("B").originalFilename("b.pdf").receivers(new HashSet<>()).build()
+        ));
+        when(commentService.findDataByIds(List.of(commentId)))
+                .thenReturn(Map.of(commentId, new CommentData(null, "Hello family!")));
+
+        List<ActivityFeedItemDTO> items = dashboardService.getActivity(userId, 5, AuditKind.ROLLUP_ELIGIBLE);
+
+        assertThat(items.get(0).commentPreview()).isEqualTo("Hello family!");
+    }
+
+    @Test
+    void getActivity_leaves_commentPreview_null_for_TEXT_SAVED_rows() {
+        UUID userId = UUID.randomUUID();
+        UUID docId = UUID.randomUUID();
+
+        ActivityFeedRow row = mockFeedRow(docId, "TEXT_SAVED", null);
+        when(auditLogQueryService.findActivityFeed(userId, 5, AuditKind.ROLLUP_ELIGIBLE)).thenReturn(List.of(row));
+        when(documentService.getDocumentsByIds(List.of(docId))).thenReturn(List.of(
+                Document.builder().id(docId).title("B").originalFilename("b.pdf").receivers(new HashSet<>()).build()
+        ));
+
+        List<ActivityFeedItemDTO> items = dashboardService.getActivity(userId, 5, AuditKind.ROLLUP_ELIGIBLE);
+
+        assertThat(items.get(0).commentPreview()).isNull();
+    }
+
+    @Test
+    void getActivity_leaves_commentPreview_null_when_comment_is_deleted() {
+        UUID userId = UUID.randomUUID();
+        UUID docId = UUID.randomUUID();
+        UUID deletedCommentId = UUID.randomUUID();
+
+        ActivityFeedRow row = mockFeedRow(docId, "COMMENT_ADDED", deletedCommentId);
+        when(auditLogQueryService.findActivityFeed(userId, 5, AuditKind.ROLLUP_ELIGIBLE)).thenReturn(List.of(row));
+        when(documentService.getDocumentsByIds(List.of(docId))).thenReturn(List.of(
+                Document.builder().id(docId).title("B").originalFilename("b.pdf").receivers(new HashSet<>()).build()
+        ));
+        when(commentService.findDataByIds(List.of(deletedCommentId))).thenReturn(Map.of());
+
+        List<ActivityFeedItemDTO> items = dashboardService.getActivity(userId, 5, AuditKind.ROLLUP_ELIGIBLE);
+
+        assertThat(items.get(0).commentPreview()).isNull();
     }
 
     // ─── getPulse — always uses full ROLLUP_ELIGIBLE set ─────────────────────

backend/src/test/java/org/raddatz/familienarchiv/dashboard/StatsControllerTest.java

@@ -44,7 +44,7 @@ class StatsControllerTest {
     @Test
     @WithMockUser(authorities = "READ_ALL")
     void getStats_returns200_withCorrectCounts() throws Exception {
-        when(statsService.getStats()).thenReturn(new StatsDTO(4L, 12L));
+        when(statsService.getStats()).thenReturn(new StatsDTO(4L, 12L, 2L));
 
         mockMvc.perform(get("/api/stats"))
                 .andExpect(status().isOk())
@@ -55,7 +55,7 @@ class StatsControllerTest {
     @Test
     @WithMockUser(authorities = "READ_ALL")
     void getStats_returns200_withZeroCounts() throws Exception {
-        when(statsService.getStats()).thenReturn(new StatsDTO(0L, 0L));
+        when(statsService.getStats()).thenReturn(new StatsDTO(0L, 0L, 0L));
 
         mockMvc.perform(get("/api/stats"))
                 .andExpect(status().isOk())

backend/src/test/java/org/raddatz/familienarchiv/dashboard/StatsServiceTest.java

@@ -7,6 +7,7 @@ import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.raddatz.familienarchiv.document.DocumentService;
 import org.raddatz.familienarchiv.dashboard.StatsDTO;
+import org.raddatz.familienarchiv.geschichte.GeschichteService;
 import org.raddatz.familienarchiv.person.PersonService;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -17,6 +18,7 @@ class StatsServiceTest {
 
     @Mock PersonService personService;
     @Mock DocumentService documentService;
+    @Mock GeschichteService geschichteService;
     @InjectMocks StatsService statsService;
 
     @Test
@@ -30,6 +32,17 @@ class StatsServiceTest {
         assertThat(stats.totalDocuments()).isEqualTo(12L);
     }
 
+    @Test
+    void getStats_includes_totalStories() {
+        when(personService.count()).thenReturn(3L);
+        when(documentService.count()).thenReturn(7L);
+        when(geschichteService.countPublished()).thenReturn(5L);
+
+        StatsDTO stats = statsService.getStats();
+
+        assertThat(stats.totalStories()).isEqualTo(5L);
+    }
+
     @Test
     void getStats_returnsZero_whenNoEntities() {
         when(personService.count()).thenReturn(0L);

backend/src/test/java/org/raddatz/familienarchiv/document/DocumentControllerTest.java

@@ -44,6 +44,7 @@ import static org.mockito.Mockito.when;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.multipart;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.patch;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@@ -1240,4 +1241,100 @@ class DocumentControllerTest {
                 .andExpect(jsonPath("$.errors[0].message").value(
                         org.hamcrest.Matchers.containsString("not found")));
     }
+
+    // ─── GET /api/documents/density ───────────────────────────────────────────
+
+    @Test
+    void density_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/density"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void density_returns200_withResultBody_whenAuthenticated() throws Exception {
+        when(documentService.getDensity(any())).thenReturn(
+                new DocumentDensityResult(
+                        List.of(new MonthBucket("1915-08", 2), new MonthBucket("1915-09", 1)),
+                        java.time.LocalDate.of(1915, 8, 3),
+                        java.time.LocalDate.of(1915, 9, 1)));
+
+        mockMvc.perform(get("/api/documents/density"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.buckets").isArray())
+                .andExpect(jsonPath("$.buckets[0].month").value("1915-08"))
+                .andExpect(jsonPath("$.buckets[0].count").value(2))
+                .andExpect(jsonPath("$.minDate").value("1915-08-03"))
+                .andExpect(jsonPath("$.maxDate").value("1915-09-01"));
+    }
+
+    // Pins produces=APPLICATION_JSON_VALUE on the density mapping so the OpenAPI/TypeScript
+    // codegen records application/json instead of the wildcard. Without produces= the
+    // request-mapping accepts any Accept header and the OpenAPI emit falls back to the
+    // wildcard. Sending an Accept header that JSON cannot satisfy must NOT return 200 —
+    // Spring rejects with 406 (HttpMediaTypeNotAcceptableException), which our
+    // GlobalExceptionHandler may surface as 400. Either way it proves the route is
+    // locked to JSON.
+    @Test
+    @WithMockUser
+    void density_declaresApplicationJsonContentType() throws Exception {
+        when(documentService.getDensity(any())).thenReturn(
+                new DocumentDensityResult(List.of(), null, null));
+
+        mockMvc.perform(get("/api/documents/density")
+                        .accept(MediaType.APPLICATION_XML))
+                .andExpect(status().is4xxClientError());
+    }
+
+    @Test
+    @WithMockUser
+    void density_emitsPrivateCacheControlHeader() throws Exception {
+        when(documentService.getDensity(any())).thenReturn(
+                new DocumentDensityResult(List.of(), null, null));
+
+        mockMvc.perform(get("/api/documents/density"))
+                .andExpect(status().isOk())
+                .andExpect(header().string("Cache-Control",
+                        org.hamcrest.Matchers.containsString("max-age=300")))
+                .andExpect(header().string("Cache-Control",
+                        org.hamcrest.Matchers.containsString("private")));
+    }
+
+    @Test
+    @WithMockUser
+    void density_forwardsSenderAndTagFilters() throws Exception {
+        when(documentService.getDensity(any())).thenReturn(
+                new DocumentDensityResult(List.of(), null, null));
+        UUID senderId = UUID.randomUUID();
+
+        mockMvc.perform(get("/api/documents/density")
+                        .param("senderId", senderId.toString())
+                        .param("tag", "Familie")
+                        .param("tag", "Urlaub")
+                        .param("tagOp", "OR"))
+                .andExpect(status().isOk());
+
+        verify(documentService).getDensity(eq(new DensityFilters(
+                null, senderId, null,
+                List.of("Familie", "Urlaub"),
+                null, null,
+                org.raddatz.familienarchiv.tag.TagOperator.OR)));
+    }
+
+    @Test
+    @WithMockUser
+    void density_forwardsStatusAndQueryText() throws Exception {
+        when(documentService.getDensity(any())).thenReturn(
+                new DocumentDensityResult(List.of(), null, null));
+
+        mockMvc.perform(get("/api/documents/density")
+                        .param("q", "Brief")
+                        .param("status", "REVIEWED"))
+                .andExpect(status().isOk());
+
+        verify(documentService).getDensity(eq(new DensityFilters(
+                "Brief", null, null, null, null,
+                DocumentStatus.REVIEWED,
+                org.raddatz.familienarchiv.tag.TagOperator.AND)));
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/document/DocumentDensityIntegrationTest.java

@@ -0,0 +1,162 @@
+package org.raddatz.familienarchiv.document;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.person.Person;
+import org.raddatz.familienarchiv.person.PersonRepository;
+import org.raddatz.familienarchiv.tag.Tag;
+import org.raddatz.familienarchiv.tag.TagRepository;
+import org.raddatz.familienarchiv.tag.TagOperator;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.transaction.annotation.Transactional;
+import software.amazon.awssdk.services.s3.S3Client;
+
+import java.time.LocalDate;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * End-to-end test for the filter-reactive density aggregation.
+ * Density bars must recompute as the user changes other filters (sender, tag,
+ * status, …). The endpoint deliberately does NOT honour `from`/`to` — the chart
+ * is the surface for picking those, so it must always span the broader space
+ * the user is selecting within.
+ */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
+@ActiveProfiles("test")
+@Import(PostgresContainerConfig.class)
+@Transactional
+class DocumentDensityIntegrationTest {
+
+    @MockitoBean S3Client s3Client;
+    @Autowired DocumentService documentService;
+    @Autowired DocumentRepository documentRepository;
+    @Autowired PersonRepository personRepository;
+    @Autowired TagRepository tagRepository;
+
+    private Person hans;
+    private Person anna;
+    private Tag familieTag;
+    private Tag urlaubTag;
+
+    @BeforeEach
+    void seed() {
+        hans = personRepository.save(Person.builder().firstName("Hans").lastName("Müller").build());
+        anna = personRepository.save(Person.builder().firstName("Anna").lastName("Weber").build());
+        familieTag = tagRepository.save(Tag.builder().name("Familie").build());
+        urlaubTag = tagRepository.save(Tag.builder().name("Urlaub").build());
+    }
+
+    private static DensityFilters noFilters() {
+        return new DensityFilters(null, null, null, null, null, null, null);
+    }
+
+    @Test
+    void getDensity_returnsAllMonths_whenNoFiltersApplied() {
+        save("a", LocalDate.of(1915, 8, 3), null, Set.of());
+        save("b", LocalDate.of(1915, 8, 17), null, Set.of());
+        save("c", LocalDate.of(1915, 9, 1), null, Set.of());
+
+        DocumentDensityResult result = documentService.getDensity(noFilters());
+
+        assertThat(result.buckets()).extracting(MonthBucket::month)
+                .containsExactly("1915-08", "1915-09");
+        assertThat(result.buckets()).extracting(MonthBucket::count).containsExactly(2, 1);
+        assertThat(result.minDate()).isEqualTo(LocalDate.of(1915, 8, 3));
+        assertThat(result.maxDate()).isEqualTo(LocalDate.of(1915, 9, 1));
+    }
+
+    @Test
+    void getDensity_filtersBySender() {
+        save("a", LocalDate.of(1915, 8, 3), hans, Set.of());
+        save("b", LocalDate.of(1916, 1, 4), hans, Set.of());
+        save("c", LocalDate.of(1920, 5, 1), anna, Set.of());
+
+        DocumentDensityResult result = documentService.getDensity(
+                new DensityFilters(null, hans.getId(), null, null, null, null, null));
+
+        assertThat(result.buckets()).extracting(MonthBucket::month)
+                .containsExactly("1915-08", "1916-01");
+        assertThat(result.maxDate()).isEqualTo(LocalDate.of(1916, 1, 4));
+    }
+
+    @Test
+    void getDensity_filtersByTag() {
+        save("a", LocalDate.of(1915, 8, 3), null, Set.of(familieTag));
+        save("b", LocalDate.of(1920, 5, 1), null, Set.of(urlaubTag));
+
+        DocumentDensityResult result = documentService.getDensity(
+                new DensityFilters(null, null, null, List.of("Familie"), null, null, TagOperator.AND));
+
+        assertThat(result.buckets()).extracting(MonthBucket::month).containsExactly("1915-08");
+    }
+
+    @Test
+    void getDensity_combinesSenderAndTag() {
+        save("a", LocalDate.of(1915, 8, 3), hans, Set.of(familieTag));
+        save("b", LocalDate.of(1916, 1, 4), hans, Set.of(urlaubTag));
+        save("c", LocalDate.of(1920, 5, 1), anna, Set.of(familieTag));
+
+        DocumentDensityResult result = documentService.getDensity(
+                new DensityFilters(null, hans.getId(), null, List.of("Familie"), null, null, TagOperator.AND));
+
+        assertThat(result.buckets()).extracting(MonthBucket::month).containsExactly("1915-08");
+    }
+
+    @Test
+    void getDensity_filtersByStatus() {
+        save("a", LocalDate.of(1915, 8, 3), null, Set.of(), DocumentStatus.UPLOADED);
+        save("b", LocalDate.of(1916, 1, 4), null, Set.of(), DocumentStatus.PLACEHOLDER);
+
+        DocumentDensityResult result = documentService.getDensity(
+                new DensityFilters(null, null, null, null, null, DocumentStatus.UPLOADED, null));
+
+        assertThat(result.buckets()).extracting(MonthBucket::month).containsExactly("1915-08");
+    }
+
+    @Test
+    void getDensity_returnsEmpty_whenNoDocumentsMatch() {
+        save("a", LocalDate.of(1915, 8, 3), hans, Set.of());
+
+        DocumentDensityResult result = documentService.getDensity(
+                new DensityFilters(null, anna.getId(), null, null, null, null, null));
+
+        assertThat(result.buckets()).isEmpty();
+        assertThat(result.minDate()).isNull();
+        assertThat(result.maxDate()).isNull();
+    }
+
+    @Test
+    void getDensity_excludesDocumentsWithNullDate() {
+        save("dated", LocalDate.of(1915, 8, 3), null, Set.of());
+        save("undated", null, null, Set.of());
+
+        DocumentDensityResult result = documentService.getDensity(noFilters());
+
+        assertThat(result.buckets()).extracting(MonthBucket::count).containsExactly(1);
+    }
+
+    private void save(String suffix, LocalDate date, Person sender, Set<Tag> tags) {
+        save(suffix, date, sender, tags, DocumentStatus.UPLOADED);
+    }
+
+    private void save(String suffix, LocalDate date, Person sender, Set<Tag> tags, DocumentStatus status) {
+        documentRepository.save(Document.builder()
+                .title("Doc " + suffix)
+                .originalFilename("doc-" + suffix + "-" + UUID.randomUUID() + ".pdf")
+                .status(status)
+                .documentDate(date)
+                .sender(sender)
+                .tags(new HashSet<>(tags))
+                .build());
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/document/DocumentFtsPagedIntegrationTest.java

@@ -0,0 +1,109 @@
+package org.raddatz.familienarchiv.document;
+
+import jakarta.persistence.EntityManager;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.document.DocumentRepository;
+import org.raddatz.familienarchiv.document.Document;
+import org.raddatz.familienarchiv.document.DocumentStatus;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.context.annotation.Import;
+import org.springframework.test.annotation.DirtiesContext;
+
+import java.util.List;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatNoException;
+
+/**
+ * Repository-level integration tests for {@code findFtsPageRaw}: verifies that the
+ * paginated FTS query returns exactly page-size rows and that the window-function
+ * total reflects the full match count, not just the page count.
+ *
+ * <p>Uses real Postgres via Testcontainers so the GIN index, tsvector trigger, and
+ * {@code websearch_to_tsquery} semantics are identical to production.
+ *
+ * <p>{@code AFTER_CLASS} dirty-context keeps the Spring context alive for all tests
+ * in this class and rebuilds it once at the end, rather than after every test.
+ */
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)
+class DocumentFtsPagedIntegrationTest {
+
+    @Autowired DocumentRepository documentRepository;
+    @Autowired EntityManager em;
+
+    // 60 docs match "Walter"; 10 docs with "Hans" do not.
+    private static final int WALTER_COUNT = 60;
+    private static final int PAGE_SIZE = 50;
+
+    @BeforeEach
+    void seed() {
+        documentRepository.deleteAll();
+        em.flush();
+        for (int i = 0; i < WALTER_COUNT; i++) {
+            documentRepository.saveAndFlush(doc("Brief von Walter Nr. " + i));
+        }
+        for (int i = 0; i < 10; i++) {
+            documentRepository.saveAndFlush(doc("Brief von Hans Nr. " + i));
+        }
+        em.clear();
+    }
+
+    @Test
+    void findFtsPageRaw_firstPage_returnsPageSizeRows() {
+        List<Object[]> rows = documentRepository.findFtsPageRaw("Walter", 0, PAGE_SIZE);
+
+        assertThat(rows).hasSize(PAGE_SIZE);
+    }
+
+    @Test
+    void findFtsPageRaw_windowTotal_equalsFullMatchCount_notPageSize() {
+        List<Object[]> rows = documentRepository.findFtsPageRaw("Walter", 0, PAGE_SIZE);
+
+        long total = ((Number) rows.get(0)[2]).longValue();
+        assertThat(total).isEqualTo(WALTER_COUNT);
+    }
+
+    @Test
+    void findFtsPageRaw_lastPage_returnsRemainder() {
+        int remainder = WALTER_COUNT % PAGE_SIZE; // 60 % 50 = 10
+        List<Object[]> rows = documentRepository.findFtsPageRaw("Walter", PAGE_SIZE, PAGE_SIZE);
+
+        assertThat(rows).hasSize(remainder);
+        long total = ((Number) rows.get(0)[2]).longValue();
+        assertThat(total).isEqualTo(WALTER_COUNT);
+    }
+
+    @Test
+    void findFtsPageRaw_noMatches_returnsEmptyList() {
+        List<Object[]> rows = documentRepository.findFtsPageRaw("XYZ_KEIN_TREFFER", 0, PAGE_SIZE);
+
+        assertThat(rows).isEmpty();
+    }
+
+    @Test
+    void findFtsPageRaw_stopwordOnlyQuery_returnsEmptyList_noException() {
+        assertThatNoException().isThrownBy(() -> {
+            List<Object[]> rows = documentRepository.findFtsPageRaw("der die das und", 0, PAGE_SIZE);
+            assertThat(rows).isEmpty();
+        });
+    }
+
+    // ─── Helper ───────────────────────────────────────────────────────────────
+
+    private Document doc(String title) {
+        return Document.builder()
+                .title(title)
+                .originalFilename(title.replace(" ", "_") + ".pdf")
+                .status(DocumentStatus.UPLOADED)
+                .build();
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/document/DocumentFtsTest.java

@@ -69,7 +69,7 @@ class DocumentFtsTest {
         documentRepository.saveAndFlush(document("Alter Brief"));
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("Brief");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("Brief");
 
         assertThat(ids).hasSize(1);
     }
@@ -79,7 +79,7 @@ class DocumentFtsTest {
         documentRepository.saveAndFlush(document("Alter Brief"));
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("Briefe");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("Briefe");
 
         assertThat(ids).hasSize(1);
     }
@@ -89,7 +89,7 @@ class DocumentFtsTest {
         documentRepository.saveAndFlush(document("Ein furchtbarer Brief"));
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("furchtb");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("furchtb");
 
         assertThat(ids).hasSize(1);
     }
@@ -99,7 +99,7 @@ class DocumentFtsTest {
         documentRepository.saveAndFlush(document("Familienfoto"));
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("Brief");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("Brief");
 
         assertThat(ids).isEmpty();
     }
@@ -115,7 +115,7 @@ class DocumentFtsTest {
         em.flush();
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("schreiben");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("schreiben");
 
         assertThat(ids).contains(doc.getId());
     }
@@ -125,14 +125,14 @@ class DocumentFtsTest {
         Document doc = documentRepository.saveAndFlush(document("Leeres Dokument"));
         em.clear();
 
-        assertThat(documentRepository.findRankedIdsByFts("Grundbuch")).isEmpty();
+        assertThat(documentRepository.findAllMatchingIdsByFts("Grundbuch")).isEmpty();
 
         UUID annotationId = annotation(doc.getId());
         blockRepository.saveAndFlush(block(doc.getId(), annotationId, "Grundbuch Eintrag 1923", 0));
         em.flush();
         em.clear();
 
-        assertThat(documentRepository.findRankedIdsByFts("Grundbuch")).contains(doc.getId());
+        assertThat(documentRepository.findAllMatchingIdsByFts("Grundbuch")).contains(doc.getId());
     }
 
     @Test
@@ -144,13 +144,13 @@ class DocumentFtsTest {
         em.flush();
         em.clear();
 
-        assertThat(documentRepository.findRankedIdsByFts("Grundbuch")).contains(doc.getId());
+        assertThat(documentRepository.findAllMatchingIdsByFts("Grundbuch")).contains(doc.getId());
 
         blockRepository.deleteById(block.getId());
         em.flush();
         em.clear();
 
-        assertThat(documentRepository.findRankedIdsByFts("Grundbuch")).doesNotContain(doc.getId());
+        assertThat(documentRepository.findAllMatchingIdsByFts("Grundbuch")).doesNotContain(doc.getId());
     }
 
     // ─── Ranking ───────────────────────────────────────────────────────────────
@@ -166,7 +166,7 @@ class DocumentFtsTest {
         em.flush();
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("Grundbuch");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("Grundbuch");
 
         assertThat(ids).hasSize(2);
         assertThat(ids.get(0)).isEqualTo(docA.getId());
@@ -179,7 +179,7 @@ class DocumentFtsTest {
         documentRepository.saveAndFlush(document("Ein Brief von der Oma"));
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("der die das und");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("der die das und");
 
         assertThat(ids).isEmpty();
     }
@@ -195,7 +195,7 @@ class DocumentFtsTest {
         em.flush();
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("Wille");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("Wille");
 
         assertThat(ids).contains(doc.getId());
     }
@@ -205,7 +205,7 @@ class DocumentFtsTest {
         documentRepository.saveAndFlush(document("Brief"));
         em.clear();
 
-        assertThatNoException().isThrownBy(() -> documentRepository.findRankedIdsByFts("((("));
+        assertThatNoException().isThrownBy(() -> documentRepository.findAllMatchingIdsByFts("((("));
     }
 
     // ─── Weight C: sender/receiver names ───────────────────────────────────────
@@ -223,7 +223,7 @@ class DocumentFtsTest {
         em.flush();
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("Schmidt");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("Schmidt");
 
         assertThat(ids).contains(doc.getId());
     }
@@ -241,7 +241,7 @@ class DocumentFtsTest {
         em.flush();
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("Raddatz");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("Raddatz");
 
         assertThat(ids).contains(doc.getId());
     }
@@ -260,7 +260,7 @@ class DocumentFtsTest {
         em.flush();
         em.clear();
 
-        List<UUID> ids = documentRepository.findRankedIdsByFts("Familiengeschichte");
+        List<UUID> ids = documentRepository.findAllMatchingIdsByFts("Familiengeschichte");
 
         assertThat(ids).hasSize(1);
     }
@@ -278,7 +278,7 @@ class DocumentFtsTest {
         em.flush();
         em.clear();
 
-        List<UUID> rankedIds = documentRepository.findRankedIdsByFts("Grundbuch");
+        List<UUID> rankedIds = documentRepository.findAllMatchingIdsByFts("Grundbuch");
         Specification<Document> spec = Specification.where(hasIds(rankedIds))
                 .and(hasStatus(DocumentStatus.UPLOADED));
 

backend/src/test/java/org/raddatz/familienarchiv/document/DocumentServiceSortTest.java

@@ -21,17 +21,22 @@ import org.springframework.data.domain.Pageable;
 import org.springframework.data.jpa.domain.Specification;
 
 import java.time.LocalDate;
+import java.util.ArrayList;
 import java.util.List;
 import java.util.UUID;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
 @ExtendWith(MockitoExtension.class)
 class DocumentServiceSortTest {
 
-    private static final Pageable UNPAGED = org.springframework.data.domain.PageRequest.of(0, 10_000);
+    private static final Pageable PAGE = org.springframework.data.domain.PageRequest.of(0, 10_000);
 
     @Mock DocumentRepository documentRepository;
     @Mock PersonService personService;
@@ -43,12 +48,12 @@ class DocumentServiceSortTest {
     @Mock TranscriptionBlockQueryService transcriptionBlockQueryService;
     @InjectMocks DocumentService documentService;
 
-    // ─── searchDocuments — DATE sort ──────────────────────────────────────────
+    // ─── DATE sort ────────────────────────────────────────────────────────────
 
     @Test
     void searchDocuments_with_DATE_sort_and_text_sorts_chronologically_not_by_relevance() {
-        UUID id1 = UUID.randomUUID();  // rank position 0 (higher relevance, older doc)
-        UUID id2 = UUID.randomUUID();  // rank position 1 (lower relevance, newer doc)
+        UUID id1 = UUID.randomUUID();  // higher relevance, older doc
+        UUID id2 = UUID.randomUUID();  // lower relevance, newer doc
 
         Document older = Document.builder().id(id1)
                 .title("Brief").status(DocumentStatus.UPLOADED)
@@ -57,38 +62,48 @@ class DocumentServiceSortTest {
                 .title("Brief").status(DocumentStatus.UPLOADED)
                 .documentDate(LocalDate.of(1960, 1, 1)).build();
 
-        // FTS returns id1 first (higher rank), id2 second
-        when(documentRepository.findRankedIdsByFts("Brief")).thenReturn(List.of(id1, id2));
-        // findAll(spec, pageable) — the correct date path — returns date-DESC order
+        when(documentRepository.findAllMatchingIdsByFts("Brief")).thenReturn(List.of(id1, id2));
         when(documentRepository.findAll(any(Specification.class), any(Pageable.class)))
                 .thenReturn(new PageImpl<>(List.of(newer, older)));
 
         DocumentSearchResult result = documentService.searchDocuments(
-                "Brief", null, null, null, null, null, null, null, DocumentSort.DATE, "DESC", null, UNPAGED);
+                "Brief", null, null, null, null, null, null, null, DocumentSort.DATE, "DESC", null, PAGE);
 
-        // Expect: date order (newer 1960 first), NOT rank order (older 1940 first)
         assertThat(result.items()).hasSize(2);
-        assertThat(result.items().get(0).document().getId()).isEqualTo(id2);  // newer doc first
+        assertThat(result.items().get(0).document().getId()).isEqualTo(id2);  // newer first
     }
 
-    // ─── searchDocuments — RELEVANCE sort ─────────────────────────────────────
+    // ─── RELEVANCE sort — pure text (no filters) ──────────────────────────────
+
+    @Test
+    void searchDocuments_relevance_pureText_calls_findFtsPageRaw_not_findAllMatchingIds() {
+        UUID id1 = UUID.randomUUID();
+        List<Object[]> ftsRows = ftsRows(id1, 0.5d, 1L);
+        when(documentRepository.findFtsPageRaw(anyString(), anyInt(), anyInt())).thenReturn(ftsRows);
+        when(documentRepository.findAllById(any()))
+                .thenReturn(List.of(doc(id1)));
+
+        documentService.searchDocuments(
+                "Brief", null, null, null, null, null, null, null, DocumentSort.RELEVANCE, null, null, PAGE);
+
+        verify(documentRepository).findFtsPageRaw(anyString(), anyInt(), anyInt());
+        verify(documentRepository, never()).findAllMatchingIdsByFts(anyString());
+    }
 
     @Test
     void searchDocuments_with_RELEVANCE_sort_and_text_preserves_fts_rank_order() {
-        UUID id1 = UUID.randomUUID();  // rank position 0
-        UUID id2 = UUID.randomUUID();  // rank position 1
+        UUID id1 = UUID.randomUUID();  // higher rank — must appear first
+        UUID id2 = UUID.randomUUID();  // lower rank
 
-        Document doc1 = Document.builder().id(id1).title("Brief").status(DocumentStatus.UPLOADED).build();
-        Document doc2 = Document.builder().id(id2).title("Brief").status(DocumentStatus.UPLOADED).build();
-
-        when(documentRepository.findRankedIdsByFts("Brief")).thenReturn(List.of(id1, id2));
-        when(documentRepository.findAll(any(Specification.class)))
-                .thenReturn(List.of(doc2, doc1));  // unordered from DB
+        List<Object[]> ftsRows = new ArrayList<>();
+        ftsRows.add(new Object[]{id1, 0.8d, 2L});
+        ftsRows.add(new Object[]{id2, 0.3d, 2L});
+        when(documentRepository.findFtsPageRaw(anyString(), anyInt(), anyInt())).thenReturn(ftsRows);
+        when(documentRepository.findAllById(any())).thenReturn(List.of(doc(id2), doc(id1))); // unordered from JPA
 
         DocumentSearchResult result = documentService.searchDocuments(
-                "Brief", null, null, null, null, null, null, null, DocumentSort.RELEVANCE, null, null, UNPAGED);
+                "Brief", null, null, null, null, null, null, null, DocumentSort.RELEVANCE, null, null, PAGE);
 
-        // Expect: rank order restored (id1 first)
         assertThat(result.items().get(0).document().getId()).isEqualTo(id1);
     }
 
@@ -97,16 +112,82 @@ class DocumentServiceSortTest {
         UUID id1 = UUID.randomUUID();
         UUID id2 = UUID.randomUUID();
 
-        Document doc1 = Document.builder().id(id1).title("Brief").status(DocumentStatus.UPLOADED).build();
-        Document doc2 = Document.builder().id(id2).title("Brief").status(DocumentStatus.UPLOADED).build();
-
-        when(documentRepository.findRankedIdsByFts("Brief")).thenReturn(List.of(id1, id2));
-        when(documentRepository.findAll(any(Specification.class)))
-                .thenReturn(List.of(doc2, doc1));
+        List<Object[]> ftsRows = new ArrayList<>();
+        ftsRows.add(new Object[]{id1, 0.8d, 2L});
+        ftsRows.add(new Object[]{id2, 0.3d, 2L});
+        when(documentRepository.findFtsPageRaw(anyString(), anyInt(), anyInt())).thenReturn(ftsRows);
+        when(documentRepository.findAllById(any())).thenReturn(List.of(doc(id2), doc(id1)));
 
         DocumentSearchResult result = documentService.searchDocuments(
-                "Brief", null, null, null, null, null, null, null, null, null, null, UNPAGED);
+                "Brief", null, null, null, null, null, null, null, null, null, null, PAGE);
 
         assertThat(result.items().get(0).document().getId()).isEqualTo(id1);
     }
+
+    // ─── RELEVANCE sort — overflow guard ─────────────────────────────────────
+
+    @Test
+    void searchDocuments_relevance_returns_empty_when_offset_exceeds_maxInt() {
+        // offset = pageNumber * pageSize; choose values so offset > Integer.MAX_VALUE
+        Pageable hugePage = org.springframework.data.domain.PageRequest.of(Integer.MAX_VALUE / 10 + 1, 10);
+
+        DocumentSearchResult result = documentService.searchDocuments(
+                "Brief", null, null, null, null, null, null, null,
+                DocumentSort.RELEVANCE, null, null, hugePage);
+
+        assertThat(result.items()).isEmpty();
+        verify(documentRepository, never()).findFtsPageRaw(anyString(), anyInt(), anyInt());
+    }
+
+    // ─── toFtsPage — UUID-as-String JDBC driver variance ────────────────────
+
+    @Test
+    void searchDocuments_relevance_handles_string_uuid_from_jdbc_driver() {
+        String stringId = "11111111-1111-1111-1111-111111111111";
+        UUID uuidId = UUID.fromString(stringId);
+        // Simulate a JDBC driver that returns the id column as String instead of UUID
+        List<Object[]> ftsRows = new ArrayList<>();
+        ftsRows.add(new Object[]{stringId, 0.5d, 1L});
+        when(documentRepository.findFtsPageRaw(anyString(), anyInt(), anyInt())).thenReturn(ftsRows);
+        when(documentRepository.findAllById(any())).thenReturn(List.of(doc(uuidId)));
+
+        DocumentSearchResult result = documentService.searchDocuments(
+                "Brief", null, null, null, null, null, null, null,
+                DocumentSort.RELEVANCE, null, null, PAGE);
+
+        assertThat(result.items()).hasSize(1);
+        assertThat(result.items().get(0).document().getId()).isEqualTo(uuidId);
+    }
+
+    // ─── RELEVANCE sort — text + active filter ────────────────────────────────
+
+    @Test
+    void searchDocuments_relevance_with_active_filter_uses_inMemory_path() {
+        UUID id1 = UUID.randomUUID();
+        UUID id2 = UUID.randomUUID();
+
+        when(documentRepository.findAllMatchingIdsByFts("Brief")).thenReturn(List.of(id1, id2));
+        when(documentRepository.findAll(any(Specification.class)))
+                .thenReturn(List.of(doc(id2), doc(id1)));
+
+        // sender filter is active → triggers in-memory path, not findFtsPageRaw
+        LocalDate from = LocalDate.of(1900, 1, 1);
+        documentService.searchDocuments(
+                "Brief", from, null, null, null, null, null, null, DocumentSort.RELEVANCE, null, null, PAGE);
+
+        verify(documentRepository, never()).findFtsPageRaw(anyString(), anyInt(), anyInt());
+        verify(documentRepository).findAllMatchingIdsByFts("Brief");
+    }
+
+    // ─── Helpers ──────────────────────────────────────────────────────────────
+
+    private static Document doc(UUID id) {
+        return Document.builder().id(id).title("Brief").status(DocumentStatus.UPLOADED).build();
+    }
+
+    private static List<Object[]> ftsRows(UUID id, double rank, long total) {
+        List<Object[]> rows = new ArrayList<>();
+        rows.add(new Object[]{id, rank, total});
+        return rows;
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/document/DocumentServiceTest.java

@@ -33,6 +33,7 @@ import org.springframework.data.domain.PageImpl;
 import org.springframework.data.domain.PageRequest;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
+import org.springframework.data.jpa.domain.Specification;
 import org.springframework.mock.web.MockMultipartFile;
 
 import java.time.LocalDate;
@@ -1402,6 +1403,21 @@ class DocumentServiceTest {
         assertThat(result.items()).hasSize(1); // only the slice is enriched
     }
 
+    @Test
+    void searchDocuments_UPDATED_AT_sort_resolves_to_updatedAt_field() {
+        ArgumentCaptor<Pageable> captor = ArgumentCaptor.forClass(Pageable.class);
+        when(documentRepository.findAll(any(org.springframework.data.jpa.domain.Specification.class), any(Pageable.class)))
+                .thenReturn(new PageImpl<>(List.of()));
+
+        documentService.searchDocuments(null, null, null, null, null, null, null, null,
+                DocumentSort.UPDATED_AT, "DESC", null,
+                org.springframework.data.domain.PageRequest.of(0, 5));
+
+        verify(documentRepository).findAll(any(org.springframework.data.jpa.domain.Specification.class), captor.capture());
+        assertThat(captor.getValue().getSort())
+                .isEqualTo(Sort.by(Sort.Direction.DESC, "updatedAt"));
+    }
+
     @Test
     void searchDocuments_senderSort_slicesInMemoryAndReportsFullTotal() {
         // Fixture: 120 docs with senders; request page 1, size 50 → expect 50 items
@@ -1604,9 +1620,10 @@ class DocumentServiceTest {
         // chr(1)=\u0001 marks start, chr(2)=\u0002 marks end of highlighted term
         List<Object[]> rows = Collections.singletonList(new Object[]{docId, "\u0001Brief\u0002 an Anna", null, false, null, null, null});
 
-        when(documentRepository.findRankedIdsByFts("Brief")).thenReturn(List.of(docId));
-        when(documentRepository.findAll(any(org.springframework.data.jpa.domain.Specification.class)))
-                .thenReturn(List.of(doc));
+        List<Object[]> ftsRows = new java.util.ArrayList<>();
+        ftsRows.add(new Object[]{docId, 0.5d, 1L});
+        when(documentRepository.findFtsPageRaw(anyString(), anyInt(), anyInt())).thenReturn(ftsRows);
+        when(documentRepository.findAllById(any())).thenReturn(List.of(doc));
         when(documentRepository.findEnrichmentData(any(), eq("Brief"))).thenReturn(rows);
 
         DocumentSearchResult result = documentService.searchDocuments(
@@ -1638,9 +1655,10 @@ class DocumentServiceTest {
         String snippetHeadline = "Hier ist der \u0001Brief\u0002 aus Berlin";
         List<Object[]> rows = Collections.singletonList(new Object[]{docId, "Dok", snippetHeadline, false, null, null, null});
 
-        when(documentRepository.findRankedIdsByFts("Brief")).thenReturn(List.of(docId));
-        when(documentRepository.findAll(any(org.springframework.data.jpa.domain.Specification.class)))
-                .thenReturn(List.of(doc));
+        List<Object[]> snippetFtsRows = new java.util.ArrayList<>();
+        snippetFtsRows.add(new Object[]{docId, 0.5d, 1L});
+        when(documentRepository.findFtsPageRaw(anyString(), anyInt(), anyInt())).thenReturn(snippetFtsRows);
+        when(documentRepository.findAllById(any())).thenReturn(List.of(doc));
         when(documentRepository.findEnrichmentData(any(), eq("Brief"))).thenReturn(rows);
 
         DocumentSearchResult result = documentService.searchDocuments(
@@ -2186,7 +2204,7 @@ class DocumentServiceTest {
 
     @Test
     void findIdsForFilter_returnsEmpty_whenFtsHasNoMatches() {
-        when(documentRepository.findRankedIdsByFts("xyz")).thenReturn(List.of());
+        when(documentRepository.findAllMatchingIdsByFts("xyz")).thenReturn(List.of());
 
         List<UUID> result = documentService.findIdsForFilter(
                 "xyz", null, null, null, null, null, null, null, null);
@@ -2321,4 +2339,61 @@ class DocumentServiceTest {
         assertThat(documentService.save(doc)).isEqualTo(doc);
         verify(documentRepository).save(doc);
     }
+
+    // ─── getDensity ────────────────────────────────────────────────────────────
+
+    private static DensityFilters anyFilters() {
+        return new DensityFilters(null, null, null, null, null, null, null);
+    }
+
+    @Test
+    void getDensity_returnsEmptyResult_whenNoDocumentsMatch() {
+        when(documentRepository.findAll(any(Specification.class))).thenReturn(List.of());
+
+        DocumentDensityResult result = documentService.getDensity(anyFilters());
+
+        assertThat(result.buckets()).isEmpty();
+        assertThat(result.minDate()).isNull();
+        assertThat(result.maxDate()).isNull();
+    }
+
+    @Test
+    void getDensity_groupsMatchingDocumentsByMonth() {
+        Document a = Document.builder().documentDate(LocalDate.of(1915, 8, 3)).build();
+        Document b = Document.builder().documentDate(LocalDate.of(1915, 8, 17)).build();
+        Document c = Document.builder().documentDate(LocalDate.of(1915, 9, 1)).build();
+        when(documentRepository.findAll(any(Specification.class))).thenReturn(List.of(a, b, c));
+        when(tagService.expandTagNamesToDescendantIdSets(any())).thenReturn(List.of());
+
+        DocumentDensityResult result = documentService.getDensity(anyFilters());
+
+        assertThat(result.buckets()).extracting(MonthBucket::month)
+                .containsExactly("1915-08", "1915-09");
+        assertThat(result.buckets()).extracting(MonthBucket::count).containsExactly(2, 1);
+        assertThat(result.minDate()).isEqualTo(LocalDate.of(1915, 8, 3));
+        assertThat(result.maxDate()).isEqualTo(LocalDate.of(1915, 9, 1));
+    }
+
+    @Test
+    void getDensity_excludesDocumentsWithNullDate() {
+        Document dated = Document.builder().documentDate(LocalDate.of(1915, 8, 3)).build();
+        Document undated = Document.builder().documentDate(null).build();
+        when(documentRepository.findAll(any(Specification.class))).thenReturn(List.of(dated, undated));
+        when(tagService.expandTagNamesToDescendantIdSets(any())).thenReturn(List.of());
+
+        DocumentDensityResult result = documentService.getDensity(anyFilters());
+
+        assertThat(result.buckets()).extracting(MonthBucket::count).containsExactly(1);
+    }
+
+    @Test
+    void getDensity_shortCircuits_whenFtsReturnsNoMatches() {
+        when(documentRepository.findAllMatchingIdsByFts("xyz")).thenReturn(List.of());
+
+        DocumentDensityResult result = documentService.getDensity(
+                new DensityFilters("xyz", null, null, null, null, null, null));
+
+        assertThat(result.buckets()).isEmpty();
+        verify(documentRepository, org.mockito.Mockito.never()).findAll(any(Specification.class));
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/document/comment/CommentControllerTest.java

@@ -44,6 +44,14 @@ class CommentControllerTest {
 
     // ─── Block comment endpoints ─────────────────────────────────────────────
 
+    @Test
+    @WithMockUser
+    void getBlockComments_returns400_when_documentId_is_not_a_UUID() throws Exception {
+        UUID blockId = UUID.randomUUID();
+        mockMvc.perform(get("/api/documents/NOT-A-UUID/transcription-blocks/" + blockId + "/comments"))
+                .andExpect(status().isBadRequest());
+    }
+
     @Test
     @WithMockUser
     void getBlockComments_returns200() throws Exception {
@@ -115,6 +123,15 @@ class CommentControllerTest {
 
     // ─── Block reply endpoints ───────────────────────────────────────────────
 
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void replyToBlockComment_returns400_when_blockId_is_not_a_UUID() throws Exception {
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/transcription-blocks/NOT-A-UUID"
+                                + "/comments/" + COMMENT_ID + "/replies")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isBadRequest());
+    }
+
     @Test
     void replyToBlockComment_returns401_whenUnauthenticated() throws Exception {
         UUID blockId = UUID.randomUUID();

backend/src/test/java/org/raddatz/familienarchiv/document/comment/CommentServiceTest.java

@@ -19,6 +19,7 @@ import org.raddatz.familienarchiv.notification.NotificationService;
 
 import java.time.LocalDateTime;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
 import java.util.UUID;
@@ -644,62 +645,99 @@ class CommentServiceTest {
         verify(auditService, never()).logAfterCommit(eq(AuditKind.MENTION_CREATED), any(), any(), any());
     }
 
-    // ─── findAnnotationIdsByIds ───────────────────────────────────────────────
+    // ─── findDataByIds ────────────────────────────────────────────────────────
 
     @Test
-    void findAnnotationIdsByIds_returnsMap_forKnownIds() {
-        UUID commentA = UUID.randomUUID();
-        UUID annotationA = UUID.randomUUID();
-        UUID commentB = UUID.randomUUID();
-        UUID annotationB = UUID.randomUUID();
-        when(commentRepository.findAllById(List.of(commentA, commentB)))
-                .thenReturn(List.of(
-                        DocumentComment.builder().id(commentA).annotationId(annotationA).build(),
-                        DocumentComment.builder().id(commentB).annotationId(annotationB).build()
-                ));
-
-        assertThat(commentService.findAnnotationIdsByIds(List.of(commentA, commentB)))
-                .containsOnly(
-                        java.util.Map.entry(commentA, annotationA),
-                        java.util.Map.entry(commentB, annotationB)
-                );
-    }
-
-    @Test
-    void findAnnotationIdsByIds_returnsEmptyMap_forEmptyInput() {
-        assertThat(commentService.findAnnotationIdsByIds(List.of())).isEmpty();
+    void findDataByIds_returns_empty_map_when_input_is_empty() {
+        assertThat(commentService.findDataByIds(List.of())).isEmpty();
         verify(commentRepository, never()).findAllById(anyList());
     }
 
     @Test
-    void findAnnotationIdsByIds_omitsUnknownIds() {
-        UUID known = UUID.randomUUID();
-        UUID knownAnnotation = UUID.randomUUID();
-        UUID missing = UUID.randomUUID();
-        when(commentRepository.findAllById(List.of(known, missing)))
-                .thenReturn(List.of(
-                        DocumentComment.builder().id(known).annotationId(knownAnnotation).build()
-                ));
+    void findDataByIds_strips_html_and_extracts_plain_text() {
+        UUID id = UUID.randomUUID();
+        when(commentRepository.findAllById(List.of(id)))
+                .thenReturn(List.of(DocumentComment.builder().id(id)
+                        .content("<p><strong>Hello</strong> world</p>").build()));
 
-        assertThat(commentService.findAnnotationIdsByIds(List.of(known, missing)))
-                .containsOnly(java.util.Map.entry(known, knownAnnotation))
-                .doesNotContainKey(missing);
+        Map<UUID, CommentData> result = commentService.findDataByIds(List.of(id));
+
+        assertThat(result.get(id).preview()).isEqualTo("Hello world");
     }
 
     @Test
-    void findAnnotationIdsByIds_omitsCommentsWithNullAnnotationId() {
-        UUID legacy = UUID.randomUUID();
-        UUID block = UUID.randomUUID();
-        UUID annotation = UUID.randomUUID();
-        when(commentRepository.findAllById(List.of(legacy, block)))
-                .thenReturn(List.of(
-                        DocumentComment.builder().id(legacy).annotationId(null).build(),
-                        DocumentComment.builder().id(block).annotationId(annotation).build()
-                ));
+    void findDataByIds_truncates_at_exactly_120_chars() {
+        UUID id = UUID.randomUUID();
+        String text121 = "a".repeat(121);
+        when(commentRepository.findAllById(List.of(id)))
+                .thenReturn(List.of(DocumentComment.builder().id(id).content(text121).build()));
 
-        assertThat(commentService.findAnnotationIdsByIds(List.of(legacy, block)))
-                .containsOnly(java.util.Map.entry(block, annotation))
-                .doesNotContainKey(legacy);
+        assertThat(commentService.findDataByIds(List.of(id)).get(id).preview()).hasSize(120);
+    }
+
+    @Test
+    void findDataByIds_preserves_content_at_exactly_120_chars() {
+        UUID id = UUID.randomUUID();
+        String text120 = "a".repeat(120);
+        when(commentRepository.findAllById(List.of(id)))
+                .thenReturn(List.of(DocumentComment.builder().id(id).content(text120).build()));
+
+        assertThat(commentService.findDataByIds(List.of(id)).get(id).preview()).hasSize(120);
+    }
+
+    @Test
+    void findDataByIds_returns_empty_string_for_blank_content() {
+        UUID id = UUID.randomUUID();
+        when(commentRepository.findAllById(List.of(id)))
+                .thenReturn(List.of(DocumentComment.builder().id(id).content("   ").build()));
+
+        assertThat(commentService.findDataByIds(List.of(id)).get(id).preview()).isEmpty();
+    }
+
+    @Test
+    void findDataByIds_returns_empty_string_for_null_content() {
+        UUID id = UUID.randomUUID();
+        when(commentRepository.findAllById(List.of(id)))
+                .thenReturn(List.of(DocumentComment.builder().id(id).content(null).build()));
+
+        assertThat(commentService.findDataByIds(List.of(id)).get(id).preview()).isEmpty();
+    }
+
+    @Test
+    void findDataByIds_omits_deleted_comments_from_result_map() {
+        UUID present = UUID.randomUUID();
+        UUID deleted = UUID.randomUUID();
+        when(commentRepository.findAllById(List.of(present, deleted)))
+                .thenReturn(List.of(DocumentComment.builder().id(present).content("Hi").build()));
+
+        Map<UUID, CommentData> result = commentService.findDataByIds(List.of(present, deleted));
+
+        assertThat(result).containsKey(present);
+        assertThat(result).doesNotContainKey(deleted);
+    }
+
+    @Test
+    void findDataByIds_preserves_annotationId_alongside_preview() {
+        UUID id = UUID.randomUUID();
+        UUID annotationId = UUID.randomUUID();
+        when(commentRepository.findAllById(List.of(id)))
+                .thenReturn(List.of(DocumentComment.builder().id(id)
+                        .annotationId(annotationId).content("Text").build()));
+
+        CommentData data = commentService.findDataByIds(List.of(id)).get(id);
+
+        assertThat(data.annotationId()).isEqualTo(annotationId);
+        assertThat(data.preview()).isEqualTo("Text");
+    }
+
+    @Test
+    void findDataByIds_sets_null_annotationId_when_comment_has_no_annotation() {
+        UUID id = UUID.randomUUID();
+        when(commentRepository.findAllById(List.of(id)))
+                .thenReturn(List.of(DocumentComment.builder().id(id)
+                        .annotationId(null).content("Text").build()));
+
+        assertThat(commentService.findDataByIds(List.of(id)).get(id).annotationId()).isNull();
     }
 
     private void stubBlock(UUID docId, UUID blockId) {

backend/src/test/java/org/raddatz/familienarchiv/geschichte/GeschichteServiceIntegrationTest.java

@@ -159,6 +159,26 @@ class GeschichteServiceIntegrationTest {
                 .isEmpty();
     }
 
+    @Test
+    void list_DRAFT_does_not_return_other_users_drafts() {
+        // writer creates a draft; writer2 (also BLOG_WRITE) should not see it
+        AppUser writer2 = appUserRepository.save(AppUser.builder()
+                .email("writer2-int@test")
+                .password("hash")
+                .build());
+
+        authenticateAs(writer, Permission.BLOG_WRITE);
+        GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
+        dto.setTitle("Writer 1 draft");
+        dto.setBody("<p>private</p>");
+        geschichteService.create(dto);
+
+        authenticateAs(writer2, Permission.BLOG_WRITE);
+        List<Geschichte> result = geschichteService.list(GeschichteStatus.DRAFT, List.of(), null, 50);
+
+        assertThat(result).isEmpty();
+    }
+
     private UUID publishedStoryWithPersons(String title, List<UUID> personIds) {
         GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
         dto.setTitle(title);

backend/src/test/java/org/raddatz/familienarchiv/person/PersonControllerTest.java

@@ -81,6 +81,29 @@ class PersonControllerTest {
                 .andExpect(jsonPath("$[0].firstName").value("Hans"));
     }
 
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void getPersons_delegatesTopByDocumentCount_whenSortAndSizeGiven() throws Exception {
+        PersonSummaryDTO top = mockPersonSummary("Käthe", "Raddatz");
+        when(personService.findTopByDocumentCount(4)).thenReturn(List.of(top));
+
+        mockMvc.perform(get("/api/persons").param("sort", "documentCount").param("size", "4"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].firstName").value("Käthe"));
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void getPersons_capsTopByDocumentCount_atFifty() throws Exception {
+        ArgumentCaptor<Integer> sizeCaptor = ArgumentCaptor.forClass(Integer.class);
+        when(personService.findTopByDocumentCount(sizeCaptor.capture())).thenReturn(Collections.emptyList());
+
+        mockMvc.perform(get("/api/persons").param("sort", "documentCount").param("size", "999"))
+                .andExpect(status().isOk());
+
+        assertThat(sizeCaptor.getValue()).isEqualTo(50);
+    }
+
     private PersonSummaryDTO mockPersonSummary(String firstName, String lastName) {
         return new PersonSummaryDTO() {
             public java.util.UUID getId() { return UUID.randomUUID(); }

backend/src/test/java/org/raddatz/familienarchiv/user/AppUserTest.java

@@ -35,4 +35,15 @@ class AppUserTest {
             .count();
         assertThat(distinct).isGreaterThan(1);
     }
+
+    @Test
+    void computeColor_returnsValidPaletteColorForIntegerMinValueHash() {
+        // UUID "80000000-0000-0000-0000-000000000000" has hashCode() == Integer.MIN_VALUE.
+        // Math.abs(Integer.MIN_VALUE) overflows back to Integer.MIN_VALUE (negative), making
+        // Math.abs(hashCode()) % n unsafe for palette sizes that don't evenly divide MIN_VALUE.
+        // Math.floorMod eliminates this edge case entirely.
+        UUID minHashId = UUID.fromString("80000000-0000-0000-0000-000000000000");
+        assertThat(minHashId.hashCode()).isEqualTo(Integer.MIN_VALUE);
+        assertThat(EXPECTED_PALETTE).contains(AppUser.computeColor(minHashId));
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/user/UserServiceTest.java

@@ -902,4 +902,18 @@ class UserServiceTest {
         assertThat(result.getName()).isEqualTo("Familie");
         assertThat(result.getPermissions()).containsExactlyInAnyOrder("READ_ALL", "WRITE_ALL");
     }
+
+    @Test
+    void createGroup_withNullPermissions_savesGroupWithEmptyPermissionSet() {
+        org.raddatz.familienarchiv.user.GroupDTO dto = new org.raddatz.familienarchiv.user.GroupDTO();
+        dto.setName("Leser");
+        dto.setPermissions(null);
+
+        UserGroup saved = UserGroup.builder().id(UUID.randomUUID()).name("Leser").build();
+        when(groupRepository.save(any())).thenReturn(saved);
+
+        userService.createGroup(dto);
+
+        verify(groupRepository).save(argThat(g -> g.getPermissions() != null && g.getPermissions().isEmpty()));
+    }
 }

docker-compose.prod.yml

@@ -0,0 +1,231 @@
+# Production / staging Docker Compose for Familienarchiv.
+#
+# This is a self-contained file (not an overlay over docker-compose.yml).
+# All services for the prod stack live here. Environment isolation is
+# achieved via the docker compose project name:
+#
+#   production: docker compose -f docker-compose.prod.yml -p archiv-production ...
+#   staging:    docker compose -f docker-compose.prod.yml -p archiv-staging --profile staging ...
+#
+# Volumes, networks and containers are namespaced by the project name,
+# so the two environments cohabit cleanly on the same host.
+#
+# Required env vars (provided by .env.production / .env.staging in CI):
+#   TAG                         image tag (release tag or "nightly")
+#   PORT_BACKEND, PORT_FRONTEND host-side ports (bound to 127.0.0.1 only)
+#   APP_DOMAIN                  e.g. archiv.raddatz.cloud / staging.raddatz.cloud
+#   POSTGRES_PASSWORD           Postgres password
+#   MINIO_PASSWORD              MinIO root password (admin operations only)
+#   MINIO_APP_PASSWORD          MinIO application service-account password
+#                               (least-privilege scope: archive bucket only)
+#   OCR_TRAINING_TOKEN          token guarding ocr-service /train endpoint
+#   APP_ADMIN_USERNAME          seeded admin email (e.g. admin@archiv.raddatz.cloud)
+#   APP_ADMIN_PASSWORD          seeded admin password — CRITICAL: locked in on
+#                               first deploy because UserDataInitializer only
+#                               creates the account if the email does not exist
+#   MAIL_HOST, MAIL_PORT,       SMTP relay (production only; staging uses mailpit)
+#   MAIL_USERNAME, MAIL_PASSWORD
+#   APP_MAIL_FROM               sender address (e.g. noreply@raddatz.cloud)
+
+networks:
+  archiv-net:
+    driver: bridge
+
+volumes:
+  postgres-data:
+  minio-data:
+  ocr-models:
+  ocr-cache:
+
+services:
+  db:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: archiv
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: archiv
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    networks:
+      - archiv-net
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U archiv -d archiv"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  minio:
+    # Pinned MinIO release for reproducible deploys. Bumped manually until
+    # Renovate is bootstrapped for these production images (see follow-up issue).
+    image: minio/minio:RELEASE.2025-02-28T09-55-16Z
+    restart: unless-stopped
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: archiv
+      MINIO_ROOT_PASSWORD: ${MINIO_PASSWORD}
+    volumes:
+      - minio-data:/data
+    networks:
+      - archiv-net
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 30s
+      timeout: 20s
+      retries: 3
+
+  # Idempotent bucket bootstrap + service-account creation.
+  # Runs once per `docker compose up` and exits 0. The entrypoint is
+  # extracted to infra/minio/bootstrap.sh so the (non-trivial) idempotent
+  # logic is readable, reviewable, and unit-testable as a script rather
+  # than YAML-escaped shell.
+  create-buckets:
+    # Custom image bakes bootstrap.sh in at build time. A bind-mount fails on
+    # the Docker-out-of-Docker production runner because the host daemon
+    # resolves the relative path against the host filesystem, not the
+    # runner container's CWD. See #506 + infra/minio/Dockerfile.
+    build:
+      context: ./infra/minio
+    # Declare one-shot intent so `docker compose up -d --wait` treats
+    # exited(0) as success rather than "not running, fail". Pair with
+    # backend's `service_completed_successfully` dependency below. See #510.
+    restart: "no"
+    depends_on:
+      minio:
+        condition: service_healthy
+    networks:
+      - archiv-net
+    environment:
+      MINIO_PASSWORD: ${MINIO_PASSWORD}
+      MINIO_APP_PASSWORD: ${MINIO_APP_PASSWORD}
+
+  # Dev-only mail catcher; gated behind the staging profile so production
+  # never starts it. Staging workflow runs with `--profile staging`.
+  mailpit:
+    # Pinned for reproducibility; bumped manually until Renovate is bootstrapped.
+    image: axllent/mailpit:v1.29.7
+    restart: unless-stopped
+    profiles: ["staging"]
+    networks:
+      - archiv-net
+    healthcheck:
+      # TCP-port open check via BusyBox `nc`. The previous wget-based probe
+      # introduced a non-obvious binary dependency on the mailpit image; a
+      # future tag that ships without wget would silently disable the
+      # healthcheck. `nc` is part of BusyBox in the upstream image.
+      test: ["CMD-SHELL", "nc -z localhost 8025 || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  ocr-service:
+    build:
+      context: ./ocr-service
+    restart: unless-stopped
+    expose:
+      - "8000"
+    # Surya OCR loads ~5GB of transformer models at startup; first request
+    # triggers a further ~1GB Kraken model download into ocr-cache.
+    # CX42+ (16 GB RAM) honours the default. On a CX32 (8 GB) override with
+    # OCR_MEM_LIMIT=6g (slower first-request, fits the host).
+    mem_limit: ${OCR_MEM_LIMIT:-12g}
+    memswap_limit: ${OCR_MEM_LIMIT:-12g}
+    volumes:
+      - ocr-models:/app/models
+      - ocr-cache:/root/.cache
+    environment:
+      KRAKEN_MODEL_PATH: /app/models/german_kurrent.mlmodel
+      TRAINING_TOKEN: ${OCR_TRAINING_TOKEN}
+      OCR_CONFIDENCE_THRESHOLD: "0.3"
+      OCR_CONFIDENCE_THRESHOLD_KURRENT: "0.5"
+      # SSRF allowlist pinned explicitly to the internal MinIO hostname.
+      # In prod the OCR service only fetches PDFs from MinIO over the
+      # docker network; localhost/127.0.0.1 are dev-only sources and
+      # must NOT be reachable here. Do not widen to `*`.
+      ALLOWED_PDF_HOSTS: "minio"
+    networks:
+      - archiv-net
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 120s
+
+  backend:
+    image: familienarchiv/backend:${TAG:-nightly}
+    build:
+      context: ./backend
+    restart: unless-stopped
+    depends_on:
+      db:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+      ocr-service:
+        condition: service_healthy
+      # Gate startup on the bucket bootstrap. Without this, backend
+      # starts in parallel with create-buckets and may race the policy
+      # bind. Also tells compose's `up -d --wait` that create-buckets
+      # is a one-shot that must complete successfully. See #510.
+      create-buckets:
+        condition: service_completed_successfully
+    # Bound to localhost only — Caddy fronts external traffic.
+    ports:
+      - "127.0.0.1:${PORT_BACKEND}:8080"
+    environment:
+      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/archiv
+      SPRING_DATASOURCE_USERNAME: archiv
+      SPRING_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD}
+      # Application uses the bucket-scoped service account, not MinIO root.
+      S3_ENDPOINT: http://minio:9000
+      S3_ACCESS_KEY: archiv-app
+      S3_SECRET_KEY: ${MINIO_APP_PASSWORD}
+      S3_BUCKET_NAME: familienarchiv
+      S3_REGION: us-east-1
+      # No SPRING_PROFILES_ACTIVE — base application.yaml is production-ready
+      # (Swagger disabled, show-sql off, open-in-view false).
+      APP_BASE_URL: https://${APP_DOMAIN}
+      APP_ADMIN_USERNAME: ${APP_ADMIN_USERNAME}
+      APP_ADMIN_PASSWORD: ${APP_ADMIN_PASSWORD}
+      APP_OCR_BASE_URL: http://ocr-service:8000
+      APP_OCR_TRAINING_TOKEN: ${OCR_TRAINING_TOKEN}
+      MAIL_HOST: ${MAIL_HOST}
+      MAIL_PORT: ${MAIL_PORT:-587}
+      MAIL_USERNAME: ${MAIL_USERNAME:-}
+      MAIL_PASSWORD: ${MAIL_PASSWORD:-}
+      APP_MAIL_FROM: ${APP_MAIL_FROM:-noreply@raddatz.cloud}
+      SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH: ${MAIL_SMTP_AUTH:-true}
+      SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE: ${MAIL_STARTTLS_ENABLE:-true}
+    networks:
+      - archiv-net
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:8080/actuator/health | grep -q UP || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+  frontend:
+    image: familienarchiv/frontend:${TAG:-nightly}
+    build:
+      context: ./frontend
+      target: production
+    restart: unless-stopped
+    depends_on:
+      backend:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:${PORT_FRONTEND}:3000"
+    environment:
+      # SSR fetches go inside the docker network; clients hit https://${APP_DOMAIN}
+      API_INTERNAL_URL: http://backend:8080
+      ORIGIN: https://${APP_DOMAIN}
+    networks:
+      - archiv-net
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:3000/login >/dev/null 2>&1 || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 10
+      start_period: 20s

docker-compose.yml

@@ -13,7 +13,7 @@ services:
     ports:
       - "${PORT_DB}:5432"
     networks:
-      - archive-net
+      - archiv-net
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
       interval: 5s
@@ -35,7 +35,7 @@ services:
       - "${PORT_MINIO_API}:9000"      # API Port
       - "${PORT_MINIO_CONSOLE}:9001"  # Web-Oberfläche
     networks:
-      - archive-net
+      - archiv-net
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
       interval: 30s
@@ -56,7 +56,7 @@ services:
       exit 0;
       "
     networks:
-      - archive-net
+      - archiv-net
 
   # --- Mail catcher: Mailpit (dev only) ---
   # Catches all outgoing emails and displays them in a web UI.
@@ -69,7 +69,7 @@ services:
       - "${PORT_MAILPIT_UI:-8025}:8025"   # Web UI
       - "${PORT_MAILPIT_SMTP:-1025}:1025" # SMTP
     networks:
-      - archive-net
+      - archiv-net
 
   # --- OCR: Python microservice (Surya + Kraken) ---
   # Single-node only: OCR training reloads the model in-process after each run.
@@ -99,7 +99,7 @@ services:
       OCR_CLAHE_TILE_SIZE: "8"      # CLAHE tile grid size (NxN tiles per page)
       OCR_MAX_CACHED_MODELS: "2"    # LRU cache; each model ~500 MB, so 2 = ~1 GB resident
     networks:
-      - archive-net
+      - archiv-net
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
       interval: 10s
@@ -150,7 +150,7 @@ services:
     ports:
       - "${PORT_BACKEND}:8080"
     networks:
-      - archive-net
+      - archiv-net
     healthcheck:
       test: ["CMD-SHELL", "wget -qO- http://localhost:8080/actuator/health | grep -q UP || exit 1"]
       interval: 15s
@@ -163,6 +163,7 @@ services:
     build:
       context: ./frontend
       dockerfile: Dockerfile
+      target: development  # Dockerfile is multi-stage; default would be the production stage
     container_name: archive-frontend
     restart: unless-stopped
     depends_on:
@@ -184,10 +185,10 @@ services:
     ports:
       - "${PORT_FRONTEND}:5173"
     networks:
-      - archive-net
+      - archiv-net
 
 networks:
-  archive-net:
+  archiv-net:
     driver: bridge
 
 volumes:

docs/DEPLOYMENT.md

@@ -27,20 +27,22 @@ This doc is the Day-1 checklist and operational reference. It links to the canon
 ```mermaid
 graph TD
     Browser -->|HTTPS| Caddy["Caddy (TLS termination)"]
-    Caddy -->|HTTP :5173| Frontend["Web Frontend\nSvelteKit / Node.js"]
+    Caddy -->|HTTP :3000| Frontend["Web Frontend\nSvelteKit Node adapter"]
     Caddy -->|HTTP :8080| Backend["API Backend\nSpring Boot / Jetty :8080"]
     Backend -->|JDBC :5432| DB[(PostgreSQL 16)]
-    Backend -->|S3 API :9000| MinIO[(MinIO / Hetzner OBS)]
+    Backend -->|S3 API :9000| MinIO[(MinIO)]
     Backend -->|HTTP :8000 internal| OCR["OCR Service\nPython FastAPI"]
     OCR -->|presigned URL| MinIO
-    Browser -->|SSE direct| Backend
+    Caddy -->|SSE proxy_pass| Backend
 ```
 
 **Key facts:**
-- Caddy terminates TLS and reverse-proxies to frontend and backend. See the Caddyfile in [`docs/infrastructure/production-compose.md`](infrastructure/production-compose.md).
-- The OCR service has **no external port** — reachable only on the internal Docker network from the backend.
-- SSE notifications go directly backend → browser (not via the SvelteKit SSR layer).
-- Management port 8081 (Spring Actuator / Prometheus scrape) is internal only — the Caddy config blocks `/actuator/*` externally.
+- Caddy terminates TLS and reverse-proxies to frontend (`:3000`) and backend (`:8080`). The Caddyfile is committed at [`infra/caddy/Caddyfile`](../infra/caddy/Caddyfile) and is installed on the host as `/etc/caddy/Caddyfile` (symlink).
+- The host binds all docker-published ports to `127.0.0.1` only; Caddy is the sole external entry point.
+- The OCR service has **no published port** — reachable only on the internal Docker network from the backend.
+- SSE notifications transit Caddy (browser → Caddy → backend); the backend is never reachable directly from the public internet. The SvelteKit SSR layer is bypassed for SSE, but Caddy is not.
+- The Caddyfile responds `404` on `/actuator/*` (defense in depth). Internal monitoring scrapes the backend on the docker network, not through Caddy.
+- Production and staging cohabit on the same host via docker compose project names: `archiv-production` (ports 8080/3000) and `archiv-staging` (ports 8081/3001).
 
 ### OCR memory requirements
 
@@ -52,19 +54,23 @@ The OCR service requires significant RAM for model loading. The dev compose sets
 | Hetzner CX32 | 8 GB | 6 GB | Accept reduced batch sizes and slower throughput |
 | Hetzner CX22 | 4 GB | — | Disable the OCR service (`profiles: [ocr]`); run OCR on demand only |
 
-A CX32 cannot honour a `mem_limit: 12g` — set it to `6g` in the prod overlay or use CX42.
+A CX32 cannot honour the default `mem_limit: 12g` — set the `OCR_MEM_LIMIT=6g` env var (in `.env.production` / `.env.staging`, or as a Gitea secret consumed by the workflow) before deploying on a CX32. The prod compose interpolates this var with a 12g default.
 
 ### Dev vs production differences
 
-| Concern | Dev compose | Prod overlay |
+| Concern | Dev (`docker-compose.yml`) | Prod (`docker-compose.prod.yml`) |
 |---|---|---|
-| MinIO image tag | `minio/minio:latest` (unpinned) | Pinned in prod overlay |
-| Data persistence | Bind mounts `./data/postgres`, `./data/minio` | Named Docker volumes |
-| Bucket creation | `create-buckets` helper container | Pre-created in Hetzner console |
-| Spring profile | `dev,e2e` (enables OpenAPI + Swagger UI) | `prod` |
-| Mail | Mailpit (local catcher) | Real SMTP |
+| MinIO image tag | `minio/minio:latest` | Pinned `minio/minio:RELEASE.…` |
+| Data persistence | Bind mounts `./data/postgres`, `./data/minio` | Named Docker volumes (`postgres-data`, `minio-data`) |
+| MinIO credentials for backend | Root user/password | Service account `archiv-app` with bucket-scoped rights |
+| Bucket creation | `create-buckets` helper | Same helper, plus service-account bootstrap on every up |
+| Spring profile | `dev,e2e` (Swagger + e2e overrides) | unset — base `application.yaml` is production-ready |
+| Mail | Mailpit (local catcher) | Real SMTP (production) / Mailpit via `profiles: [staging]` (staging) |
+| Frontend image | Dev server, `target: development`, port 5173 | Node adapter, `target: production`, port 3000 |
+| Host port binding | All published | Bound to `127.0.0.1` only; Caddy is the front door |
+| Deploy method | `docker compose up -d` (manual) | Gitea Actions: `nightly.yml` (staging, cron) and `release.yml` (production, on `v*` tag) — both use `up -d --wait` |
 
-Full prod overlay: [`docs/infrastructure/production-compose.md`](infrastructure/production-compose.md).
+Full prod compose: [`docker-compose.prod.yml`](../docker-compose.prod.yml). Workflow files: [`.gitea/workflows/nightly.yml`](../.gitea/workflows/nightly.yml), [`.gitea/workflows/release.yml`](../.gitea/workflows/release.yml).
 
 ---
 
@@ -112,9 +118,10 @@ All vars are set in `.env` at the repo root (copy from `.env.example`). The back
 
 | Variable | Purpose | Default | Required? | Sensitive? |
 |---|---|---|---|---|
-| `MINIO_ROOT_USER` | MinIO root username | `minio_admin` | YES | — |
-| `MINIO_ROOT_PASSWORD` | MinIO root password | `change-me` | YES | YES |
-| `MINIO_DEFAULT_BUCKETS` | Bucket name | `archive-documents` | YES | — |
+| `MINIO_ROOT_USER` | MinIO root username (dev compose only — prod compose hardcodes `archiv`) | `minio_admin` | YES (dev) | — |
+| `MINIO_ROOT_PASSWORD` / `MINIO_PASSWORD` | MinIO root password. **Used only by the `mc admin` bootstrap in prod, never by the backend.** | `change-me` | YES | YES |
+| `MINIO_APP_PASSWORD` | Password for the `archiv-app` service account that the backend uses. Bucket-scoped via `readwrite` policy on `familienarchiv`. Bootstrapped by `create-buckets`. | — | YES (prod) | YES |
+| `MINIO_DEFAULT_BUCKETS` | Bucket name (dev compose only — prod compose hardcodes `familienarchiv`) | `archive-documents` | YES (dev) | — |
 
 ### OCR service
 
@@ -124,53 +131,102 @@ All vars are set in `.env` at the repo root (copy from `.env.example`). The back
 | `ALLOWED_PDF_HOSTS` | SSRF protection — comma-separated list of allowed PDF source hosts. **Do not widen to `*`** | `minio,localhost,127.0.0.1` | YES | — |
 | `KRAKEN_MODEL_PATH` | Directory containing Kraken HTR models (populated by `download-kraken-models.sh`) | `/app/models/` | — | — |
 | `BLLA_MODEL_PATH` | Kraken baseline layout analysis model path | `/app/models/blla.mlmodel` | — | — |
+| `OCR_MEM_LIMIT` | Container memory cap for ocr-service in `docker-compose.prod.yml`. Set to `6g` on CX32 hosts; leave unset on CX42+ to use the 12g default | `12g` (prod compose default) | — | — |
 
 ---
 
 ## 3. Bootstrap from scratch
 
-> Full VPS provisioning steps are in [`docs/infrastructure/production-compose.md`](infrastructure/production-compose.md). This section covers the sequence and the security-critical steps.
+Production and staging deploy via Gitea Actions (`release.yml` on `v*` tag, `nightly.yml` on cron). The server itself only needs to host Caddy, Docker, and the runner — the workflows handle the rest.
 
-### Security checklist — complete before first boot
-
-> ⚠️ **These defaults ship in `.env.example` and `application.yaml`. Change them or you will have an insecure installation.**
-
-- [ ] Set `APP_ADMIN_PASSWORD` (default: `admin123` — change before starting the backend)
-- [ ] Set `APP_ADMIN_USERNAME` if you want a non-default admin login name (add to `.env` — not in `.env.example`)
-- [ ] Rotate `POSTGRES_PASSWORD` from `change-me`
-- [ ] Rotate `MINIO_ROOT_PASSWORD` from `change-me`
-- [ ] Set a strong `APP_OCR_TRAINING_TOKEN` (backend) and the matching `TRAINING_TOKEN` (OCR service) — both must be the same value (`python3 -c "import secrets; print(secrets.token_hex(32))"`)
-- [ ] Confirm `ALLOWED_PDF_HOSTS` is locked to your MinIO/S3 hostname — widening to `*` opens SSRF
-- [ ] Set `SPRING_PROFILES_ACTIVE=prod` in the prod overlay (not `dev,e2e` — that exposes Swagger UI and `/v3/api-docs`)
-- [ ] Use a dedicated MinIO service account for `S3_ACCESS_KEY` / `S3_SECRET_KEY`, not the root credentials
-
-### Bootstrap sequence
+### 3.1 Server one-time setup
 
 ```bash
-# 1. Copy and fill the env file
-cp .env.example .env
-# edit .env — complete the security checklist above first
+# Base hardening
+ufw default deny incoming && ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp && ufw enable
+# /etc/ssh/sshd_config: PasswordAuthentication no, PermitRootLogin no
 
-# 2. (Production only) Create the MinIO / Hetzner OBS bucket in the console
-#    The dev compose has a create-buckets helper; production does not.
-#    Create the bucket named $MINIO_DEFAULT_BUCKETS with private access.
+# Install Caddy 2 (https://caddyserver.com/docs/install#debian-ubuntu-raspbian)
+apt install caddy
 
-# 3. Start the stack (prod overlay — see docs/infrastructure/production-compose.md)
-#    docker-compose.prod.yml is NOT committed — create it from the guide above
-docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+# Use the Caddyfile from the repo (replace path with the runner's clone target)
+ln -sf /opt/familienarchiv/infra/caddy/Caddyfile /etc/caddy/Caddyfile
+systemctl reload caddy
 
-# 4. Flyway migrations run automatically on backend start.
-#    Watch the backend log to confirm:
-docker compose logs --follow --tail=100 backend
+# fail2ban — protect /api/auth/login from credential stuffing.
+# Jail watches the Caddy JSON access log for 401 responses on
+# /api/auth/login. The jail (maxretry=10 / findtime=10m / bantime=30m)
+# and filter are committed under infra/fail2ban/ — symlink them in:
+apt install fail2ban
+ln -sf /opt/familienarchiv/infra/fail2ban/jail.d/familienarchiv.conf \
+       /etc/fail2ban/jail.d/familienarchiv.conf
+ln -sf /opt/familienarchiv/infra/fail2ban/filter.d/familienarchiv-auth.conf \
+       /etc/fail2ban/filter.d/familienarchiv-auth.conf
+systemctl reload fail2ban
+# Verify after first deploy with:
+#   fail2ban-client status familienarchiv-auth
+#   fail2ban-regex /var/log/caddy/access.log familienarchiv-auth
 
-# 5. Verify the stack is healthy
-curl http://localhost:8080/actuator/health
-# Expected: {"status":"UP"}
+# Tailscale — used by the backup pipeline to reach heim-nas (follow-up issue)
+curl -fsSL https://tailscale.com/install.sh | sh && tailscale up
 
-# 6. Open the app and log in with the admin credentials from .env
+# Self-hosted Gitea runner — register against the repo with a runner token.
+# This runner is assumed single-tenant: the deploy workflows write .env.*
+# files to disk during execution (cleaned up unconditionally on completion).
+# A multi-tenant runner would need to switch to stdin-piped env files.
+# (See https://docs.gitea.com/usage/actions/quickstart for the register step.)
 ```
 
-> **Do not use `docker-compose.ci.yml` locally** — it disables bind mounts that the dev workflow depends on.
+### 3.2 DNS records
+
+```
+archiv.raddatz.cloud   A   <server IP>
+staging.raddatz.cloud  A   <server IP>
+git.raddatz.cloud      A   <server IP>
+```
+
+### 3.3 Gitea secrets (Repo → Settings → Actions → Secrets)
+
+| Secret | Used by | Notes |
+|---|---|---|
+| `PROD_POSTGRES_PASSWORD` | release.yml | strong unique password |
+| `PROD_MINIO_PASSWORD` | release.yml | MinIO root password; used only at bootstrap |
+| `PROD_MINIO_APP_PASSWORD` | release.yml | application service-account password |
+| `PROD_OCR_TRAINING_TOKEN` | release.yml | `python3 -c "import secrets; print(secrets.token_hex(32))"` |
+| `PROD_APP_ADMIN_USERNAME` | release.yml | e.g. `admin@archiv.raddatz.cloud` |
+| `PROD_APP_ADMIN_PASSWORD` | release.yml | **⚠ locked permanently on first deploy** — see §3.5 |
+| `STAGING_POSTGRES_PASSWORD` | nightly.yml | different from prod |
+| `STAGING_MINIO_PASSWORD` | nightly.yml | different from prod |
+| `STAGING_MINIO_APP_PASSWORD` | nightly.yml | different from prod |
+| `STAGING_OCR_TRAINING_TOKEN` | nightly.yml | different from prod |
+| `STAGING_APP_ADMIN_USERNAME` | nightly.yml | e.g. `admin@staging.raddatz.cloud` |
+| `STAGING_APP_ADMIN_PASSWORD` | nightly.yml | locked on first staging deploy |
+| `MAIL_HOST` | release.yml | SMTP relay hostname (prod only) |
+| `MAIL_PORT` | release.yml | typically `587` |
+| `MAIL_USERNAME` | release.yml | SMTP user |
+| `MAIL_PASSWORD` | release.yml | SMTP password |
+
+### 3.4 First deploy
+
+```bash
+# 1. Trigger nightly.yml manually (Repo → Actions → nightly → "Run workflow")
+#    Expected: docker compose up -d --wait succeeds for archiv-staging, then
+#    the workflow's "Smoke test deployed environment" step asserts:
+#      - https://staging.raddatz.cloud/login returns 200
+#      - HSTS header is present
+#      - /actuator/health returns 404 (defense-in-depth check)
+# 2. (Optional) Re-verify manually
+curl -I https://staging.raddatz.cloud/
+#    Expected: 200 (login page) with HSTS + X-Content-Type-Options headers
+# 3. When staging looks healthy, push a v* tag to trigger release.yml
+git tag v1.0.0 && git push origin v1.0.0
+```
+
+### 3.5 ⚠ Admin password is locked on first deploy
+
+`UserDataInitializer` creates the admin user **only if the email does not exist**. The first successful deploy persists the admin password to the database. Changing `PROD_APP_ADMIN_PASSWORD` in Gitea secrets after that point has **no effect** — the secret is only consulted when the row is missing.
+
+Before the first deploy: rotate `PROD_APP_ADMIN_PASSWORD` to a strong value. After the first deploy: change the admin password via the in-app account settings, not via the Gitea secret.
 
 ---
 
@@ -224,7 +280,23 @@ docker exec -i archive-db psql -U ${POSTGRES_USER} ${POSTGRES_DB} < backup-YYYYM
 
 ### Planned — phase 5 of Production v1 milestone
 
-Automated backup (PostgreSQL WAL archiving + MinIO bucket replication) is planned in the Production v1 milestone phase 5. Until that ships: **manual backups are the only recovery option.**
+Automated backup (nightly `pg_dump` + MinIO `mc mirror` over Tailscale to `heim-nas`) is a follow-up issue. Until that ships: **manual backups are the only recovery option.**
+
+### Rollback
+
+Each release tag corresponds to a docker image tag on the host daemon (built via DooD; no registry). Rolling back to a previous tag is one command:
+
+```bash
+TAG=v1.0.0 docker compose \
+  -f docker-compose.prod.yml \
+  -p archiv-production \
+  --env-file /opt/familienarchiv/.env.production \
+  up -d --wait --remove-orphans
+```
+
+If the rollback target image is no longer present on the host (host disk pruned, etc.), re-trigger `release.yml` for that tag from Gitea Actions UI — it rebuilds and redeploys.
+
+**Flyway migrations are not auto-rolled-back.** If a release contained a destructive migration (drop column, rename table), a tag rollback brings the schema back to a previous app version but the data shape has already changed. For breaking schema changes, prefer a forward-only fix.
 
 ---
 

docs/GLOSSARY.md

@@ -13,6 +13,9 @@ For domain package structure see [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) _(com
 **AppUser** (`AppUser`) — a real person who can log into the system (a family member or administrator). `AppUser` records carry login credentials, group memberships, and notification history.
 _Not to be confused with [Person](#person-person)_ — an AppUser is never recorded as a document sender, receiver, or historical individual.
 
+**Reader** — an `AppUser` whose effective permissions include `READ_ALL` but neither `WRITE_ALL` nor `ANNOTATE_ALL`. Readers see a dedicated dashboard (`isReader = !canWrite && !canAnnotate`) focused on browsing documents, persons, and stories rather than contribution tasks. A user who also holds `BLOG_WRITE` is still classified as a Reader and additionally sees a drafts module.
+_Not to be confused with [AppUser](#appuser-appuser)_ — Reader is a permission-derived role, not an entity.
+
 **Permission** — a discrete capability string assigned to a `UserGroup` (e.g. `READ_ALL`, `WRITE_ALL`, `ADMIN`, `ADMIN_USER`, `ADMIN_TAG`, `ADMIN_PERMISSION`). Enforced via the `@RequirePermission` AOP annotation on controller methods, checked at runtime by `PermissionAspect`; not via Spring Security's `@PreAuthorize`.
 
 **Person** (`Person`) — a historical individual in the family archive (sender, receiver of letters, person mentioned in transcriptions). NEVER has a login account and NEVER appears as an `AppUser`.
@@ -104,6 +107,13 @@ _See also [Briefwechsel](#briefwechsel-user-facing)._
 
 ---
 
+## Infrastructure Terms
+
+**archiv-app** — the bucket-scoped MinIO service account the backend uses to read and write the `familienarchiv` bucket. Distinct from the MinIO root account (`archiv`, used only by the bootstrap container for admin operations). Defined and provisioned in [`infra/minio/bootstrap.sh`](../infra/minio/bootstrap.sh) and consumed by the backend as `S3_ACCESS_KEY` in [`docker-compose.prod.yml`](../docker-compose.prod.yml). The attached `archiv-app-policy` grants `s3:GetObject/PutObject/DeleteObject` on `familienarchiv/*` and `s3:ListBucket/GetBucketLocation` on the bucket only — not the built-in `readwrite` policy which would grant `s3:*` on all buckets.
+_See also [ADR-010 — MinIO stays self-hosted, not Hetzner OBS](./adr/010-minio-self-hosted-not-hetzner-obs.md)._
+
+---
+
 ## Pending Terms
 
 _Terms flagged as potentially ambiguous that have not yet been formally defined here. Add an entry above and remove it from this list when resolved._

docs/adr/007-reader-dashboard-permission-discriminant.md

@@ -0,0 +1,52 @@
+# ADR-007: Reader-dashboard permission discriminant
+
+## Status
+
+Accepted
+
+## Context
+
+Issue #447 introduced two distinct user cohorts on the home page:
+
+- **Contributors** — transcribe, annotate, upload. The existing `MissionControlStrip`, `EnrichmentBlock`, `DashboardResumeStrip`, `DashboardFamilyPulse`, `DashboardActivityFeed`, and `DropZone` are aimed at them.
+- **Readers** — browse and consume finished content. Older, less technical, on smaller devices. The contribution-focused widgets are noise to them.
+
+`AppUser` permissions are already derived in `+layout.server.ts` and exposed via `$page.data` as `canWrite`, `canAnnotate`, and `canBlogWrite`. The home route needs a single boolean to switch its layout and its data fetch set, and that boolean has to be load-bearing — every future permission introduced has to be classified against it.
+
+## Decision
+
+```ts
+const isReader = !canWrite && !canAnnotate;
+```
+
+Computed at the start of `+page.server.ts` `load()`. When true, the loader fetches a lean reader set (stats / top-4 persons / recent docs / recent stories — and drafts when `canBlogWrite`) via `Promise.allSettled` and returns a discriminated-union shape the page distinguishes via `data.isReader`.
+
+`BLOG_WRITE` is **not** part of the discriminant. A `READ_ALL + BLOG_WRITE` user is still a reader and additionally sees the `ReaderDraftsModule`. Story writers are conceptually closer to readers than to transcribers: they consume the archive, occasionally publish narrative on top of it, and have no business with the transcription queue.
+
+A `BLOG_WRITE`-only user (no `READ_ALL`) is also classified as a reader by this formula. Because every reader API requires `READ_ALL`, all four content tiles degrade to empty via `Promise.allSettled`. They see the empty reader shell plus the drafts module — acceptable behaviour, since this permission combination is degenerate by configuration. Documented in `docs/GLOSSARY.md`.
+
+## Alternatives Considered
+
+| Alternative | Why rejected |
+|---|---|
+| New `/reader-home` route with a server-side redirect from `/` | Two routes that mostly answer the same product question (home page). Bookmarks split, breadcrumbs split, header `home` link has to know which to use. The conditional-render keeps a single canonical URL and lets the auth state drive the layout, matching how `canWrite` already gates the upload zone in the contributor branch. |
+| `AppUser.dashboardVariant` column persisted in the DB | Permissions already encode the relevant signal; a separate field has to be kept in sync with permission changes. Drift is a feature foot-gun: a user gets `WRITE_ALL` granted but their `dashboardVariant` field still says `reader` and they keep seeing the wrong UI. |
+| Middleware/handle hook redirecting based on permissions | Same logical issue as the dedicated route plus a network round-trip on every dashboard hit. The discriminant runs once inside the same `load()` that's already fetching the user. |
+| `isReader = !canWrite && !canAnnotate && !canBlogWrite` (exclude `BLOG_WRITE` from readers) | Treats blog writers as contributors. They would land on the `MissionControlStrip` they cannot meaningfully use (no `WRITE_ALL`, no `ANNOTATE_ALL`) and would have to scroll past the transcription queue to find their own drafts. The reader shell + drafts module fits their actual workflow. |
+
+## Consequences
+
+**Easier:**
+- Reader and contributor views share one canonical home URL — no redirect, no routing fork.
+- Adding a new content tile to the reader dashboard is a single-file change inside the `if (isReader)` branch of `load()` plus a new component import in `+page.svelte`.
+- Backend `@RequirePermission(READ_ALL)` on every reader API call remains the load-bearing security gate. `isReader` is purely a UX flag — manipulating it client-side serves a different layout to the same authenticated user with the same permissions.
+
+**Harder:**
+- Every future `Permission` value has to be explicitly classified against this formula. Adding a permission that grants contribution rights but not `WRITE_ALL`/`ANNOTATE_ALL` would silently leave its bearers on the reader dashboard. Mitigation: keep this ADR linked from `+page.server.ts` and from the `Permission` enum's Javadoc.
+- The discriminated-union return type of `load()` (`{isReader: true} | {isReader: false}`) requires every consumer to narrow on `data.isReader` before accessing branch-specific fields. The current `+page.svelte` already does this with the top-level `{#if data.isReader}`; new consumers of the home loader must follow suit.
+
+## Future Direction
+
+If a third cohort emerges (e.g. an admin home with system-health tiles), promote the discriminant to a tagged-union: `dashboard: 'reader' | 'contributor' | 'admin'`. The discriminant computation moves from `+page.server.ts` into a small helper in `lib/shared/server/`, callable from any route that needs the same classification (e.g. a future `/welcome` onboarding flow).
+
+If `BLOG_WRITE`-only access becomes a real product mode (rather than the degenerate combination it is today), revisit whether the formula should add a `canRead` precondition: `isReader = canRead && !canWrite && !canAnnotate`.

docs/adr/008-fts-sql-pagination.md

@@ -0,0 +1,68 @@
+# ADR-008: SQL-level pagination for full-text search via window-function CTE
+
+## Status
+
+Accepted
+
+## Context
+
+`DocumentRepository.findAllMatchingIdsByFts` (formerly `findRankedIdsByFts`) returns all matching document IDs for a FTS query. `DocumentService.searchDocuments` then paginates in memory on the RELEVANCE sort path.
+
+A pre-production audit against 1,520 documents measured:
+
+```
+rows_per_call: 911 / call  (query: "walter")
+```
+
+At current scale this is acceptable — 911 UUIDs ≈ 14 KB, ms-level DB time. At 100 K+ documents two failure modes emerge:
+
+1. **Memory**: a broad query returns ~60 K UUIDs ≈ 1 MB per request, multiplied by concurrent users.
+2. **Latency**: the `LATERAL` join does work proportional to match-set size; at 60 K matches the FTS step alone exceeds 100 ms per query.
+
+Tracked as finding **F-31 (High)** in the pre-production architectural review.
+
+## Decision
+
+Push pagination and rank ordering into SQL for the RELEVANCE sort path when no non-text filters are active (pure full-text search):
+
+```sql
+WITH q AS (
+  SELECT CASE WHEN websearch_to_tsquery('german', :query)::text <> ''
+              THEN to_tsquery('simple', regexp_replace(
+                       websearch_to_tsquery('german', :query)::text,
+                       '''([^'']+)''', '''\\1'':*', 'g'))
+         END AS pq
+), matches AS (
+  SELECT d.id, ts_rank(d.search_vector, q.pq) AS rank
+  FROM documents d, q
+  WHERE d.search_vector @@ q.pq
+)
+SELECT id, rank, COUNT(*) OVER () AS total
+FROM matches
+ORDER BY rank DESC, id
+OFFSET :offset LIMIT :limit
+```
+
+`COUNT(*) OVER ()` returns the full match count alongside each page row in a single round-trip — no separate count query needed.
+
+`rows_per_call` for the FTS query drops from match-set size (911) to page size (≤ 50).
+
+When non-text filters (date range, sender, receiver, tags, status) are also active, the existing path is preserved: `findAllMatchingIdsByFts` returns all ranked IDs, which are passed as an `IN` clause to the JPA Specification, and `totalElements` comes from the JPA `Page.getTotalElements()`. This keeps the count accurate across the combined filter set.
+
+## Alternatives Considered
+
+**1. Two-query approach (separate COUNT + paged SELECT)**
+Correct, but doubles round-trips. The window function achieves the same result in one query.
+
+**2. Capped result set with a user-visible warning**
+Return at most N results (e.g. 500) and show "showing top 500 of many results". Simpler, but degrades UX for broad queries and doesn't reduce latency proportionally (still scans N rows).
+
+**3. Full SQL rewrite combining FTS + JPA Specification filters**
+Possible via a native query that embeds all filter predicates. Eliminates the in-memory SENDER/RECEIVER sort paths and the two-phase approach. High complexity, tight coupling to schema details, loses type-safe JPA Specification composition. Deferred to a future refactor if scale demands it.
+
+## Consequences
+
+- **`rows_per_call` for pure-text FTS searches drops to ≤ page size** — the primary metric.
+- **SENDER and RECEIVER sort paths stay in-memory** for combined text+filter queries. For pure-text queries with SENDER/RECEIVER sort, the current approach (fetch all matched IDs, build spec, load all matched entities, sort in-memory) still runs. This is acceptable while the archive stays under ~10 K documents.
+- **RELEVANCE sort with text+filters still loads the full filtered entity set in-memory.** The filtered set is typically much smaller than the raw FTS match set, so the cost is bounded by filter selectivity, not total match count.
+- **`findAllMatchingIdsByFts` is retained** for: (a) the bulk-edit "select all" fast path (`findIdsForFilter`), (b) the document density chart (`getDensity`), and (c) the SENDER/RECEIVER in-memory sort paths.

docs/adr/009-standalone-compose-not-overlay.md

@@ -0,0 +1,50 @@
+# ADR-009: Standalone `docker-compose.prod.yml`, not an overlay
+
+## Status
+
+Accepted
+
+## Context
+
+The repository's `docker-compose.yml` is a development stack: every service is built locally, ports are exposed on `0.0.0.0` for dev tooling, the frontend runs `npm run dev` with hot-reload, the backend is `spring-boot:run` with the dev profile, and there is no Caddy, no `archiv-app` service account, no admin-credential lock-in, no healthcheck-gated startup sequence. The dev stack reflects "single developer on a laptop", not "production on a single VPS".
+
+The pre-merge design (issue #497, comment #8331) sketched two ways to add a production stack:
+
+1. **Overlay** — keep `docker-compose.yml` as the base, add `docker-compose.prod.yml` as a `-f` overlay (`docker compose -f docker-compose.yml -f docker-compose.prod.yml up`). Compose merges the two files at runtime.
+2. **Standalone** — make `docker-compose.prod.yml` a fully self-contained file that does not reference or merge with `docker-compose.yml` at all. Project-name namespacing (`-p archiv-production`, `-p archiv-staging`) keeps multi-environment deploys clean on a single host.
+
+The earlier `docs/infrastructure/production-compose.md` notes assumed overlay because the original plan was to **remove** MinIO in production (replace with Hetzner Object Storage), so the prod file would only need to remove one service and add a few. With MinIO retained (see ADR-010), the prod stack diverges from dev in essentially every service: build vs pre-built image, target stage, port binding, env vars, healthcheck, restart policy, mem_limit, profile gating, service account, depends_on chain. Overlay would mostly be `override:` blocks that nullify the dev defaults — a fragile inversion.
+
+## Decision
+
+`docker-compose.prod.yml` is standalone. Production and staging both run it directly:
+
+```
+production: docker compose -f docker-compose.prod.yml -p archiv-production --env-file .env.production ...
+staging:    docker compose -f docker-compose.prod.yml -p archiv-staging    --env-file .env.staging --profile staging ...
+```
+
+Environment isolation is achieved via the Docker Compose project name (`-p`). Volumes, networks, and containers are namespaced by the project name, so production and staging cohabit cleanly on the same host without interfering.
+
+The dev `docker-compose.yml` is unchanged — `docker compose up` still works for developers, and its `frontend` service now specifies `target: development` explicitly so the new multi-stage Dockerfile builds the right stage.
+
+## Alternatives Considered
+
+| Alternative | Why rejected |
+|---|---|
+| Overlay (`-f base.yml -f prod.yml`) | With MinIO retained and most services differing across nearly every field, the overlay would consist mostly of `override:` blocks that null out dev defaults. Compose's merge semantics for nested keys (env, ports, healthcheck) are sharp — silent merges of port mappings, env-var entries, and depends_on edges cost reviewer hours. Standalone is one file the reader can hold in their head. |
+| Two fully separate files (dev + prod) but with shared YAML anchors via `extends:` | `extends:` works across files but is a niche feature and is increasingly discouraged in compose v2. Reviewer load is higher than reading two flat files. |
+| Generate prod compose from a template at deploy time (e.g. ytt, kustomize) | Adds a build-time step and a new tool to the operator toolchain. Justified for a fleet of 10+ environments; overkill for production + staging on one host. |
+| Single compose file with environment-specific profiles | Compose profiles select which *services* run, not which *configuration* a service runs with. Using profiles to swap "build locally" vs "pull image" would smear dev and prod across one file. |
+
+## Consequences
+
+- The prod file can be read top-to-bottom without cross-referencing `docker-compose.yml`. Onboarding and review cost drops.
+- Volume namespacing is automatic (`archiv-production_postgres-data`, `archiv-staging_postgres-data`) — no manual `volumes:` aliasing.
+- Dev compose churn (e.g. swapping a dev port) cannot accidentally affect production. The two files are independent.
+- The cost is duplication: identical environment variables (e.g. `POSTGRES_DB: archiv`) appear in both files. This duplication is bounded — there is no incentive to add more services that exist in both — and the alternative (overlay) carries its own duplication via `override:` boilerplate.
+- The retired `docs/infrastructure/production-compose.md` narrative is trimmed to a pointer at the live files. The cost/sizing rationale is preserved there.
+
+## Future Direction
+
+If the deployment fleet ever grows beyond two environments on one host (e.g. add a `demo` environment, or shard staging across two VPS for load testing), revisit the templating decision. At three+ environments the duplication starts to bite and a template engine (kustomize or ytt) becomes attractive.

docs/adr/010-minio-self-hosted-not-hetzner-obs.md

@@ -0,0 +1,53 @@
+# ADR-010: MinIO stays self-hosted on the production VPS
+
+## Status
+
+Accepted
+
+## Context
+
+`docs/infrastructure/production-compose.md` (pre-this-PR) sketched a production topology in which the application bucket migrates from in-cluster MinIO to Hetzner Object Storage (OBS, S3-compatible). The motivation was operational: one less service to back up, no MinIO RAM/disk pressure on the VPS, hand off durability to the hyperscaler.
+
+Two facts revisited at pre-merge review (issue #497, comment #8331) changed the answer:
+
+1. **Current data size is small.** The archive is ~13 GB of file uploads (Kurrent letters, scanned ODS files, attachment PDFs). Hetzner OBS billing on this size is dominated by the per-month base fee (~5 EUR/mo for the smallest unit), not capacity or egress. The break-even point against the VPS's existing disk is far above the current footprint.
+2. **MinIO is already production-grade.** The dev stack uses MinIO; the backend already drives it via the AWS SDK v2 with a generic `S3_ENDPOINT`. Switching providers is a runtime env-var change (`S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`) plus an `mc mirror` to copy objects. There is no application-level rewrite cost waiting.
+
+If Hetzner OBS were a one-way-door (provider-specific SDK, complex IAM integration, multi-month migration), the decision would deserve a serious weighing. As reversible as the migration is, deferring it costs nothing.
+
+## Decision
+
+MinIO stays on the production VPS for the first launch. The application bucket is created and managed inside the docker-compose stack (`infra/minio/bootstrap.sh`). The backend uses a least-privilege service account (`archiv-app`) with a bucket-scoped IAM policy, not the MinIO root credentials.
+
+Hetzner Object Storage is **explicitly deferred**, not rejected. The migration path is documented as a runbook in `docs/DEPLOYMENT.md` (when the trigger fires): provision an OBS bucket, run `mc mirror local-minio:/familienarchiv obs:/familienarchiv`, rotate the three env vars, restart the backend, decommission the MinIO service from `docker-compose.prod.yml`.
+
+## Triggers to re-evaluate
+
+Revisit the decision when **any** of the following holds:
+
+- The `minio-data` volume exceeds 50 GB and is growing > 5 GB/month.
+- MinIO healthcheck latency exceeds 200 ms p95 (signal of disk pressure on the host).
+- The VPS upgrade required to keep MinIO healthy costs more per month than the equivalent OBS bucket + traffic.
+- Backup of the MinIO volume to `heim-nas` over Tailscale (deferred follow-up) is implemented and consistently runs > 30 min nightly. At that point durability-as-a-service starts paying for itself.
+
+The migration runbook in `docs/DEPLOYMENT.md` is the script for executing the swap when one of the triggers fires.
+
+## Alternatives Considered
+
+| Alternative | Why rejected (for now) |
+|---|---|
+| Migrate to Hetzner Object Storage in this PR | Premature. Adds an external dependency, locks the operator into the Hetzner ecosystem before the data has demonstrated it needs hyperscaler durability, blocks the PR on a migration that buys ~5 GB of headroom. |
+| Migrate to S3 (AWS) for HA across regions | Way over-spec for a family archive. Egress cost would dwarf any benefit; durability concerns at this size are addressed by nightly off-site backup, not by multi-region replication. |
+| Drop S3 abstraction entirely; store files directly on the VPS disk | Possible, but loses the bucket-policy IAM surface (least-privilege service account), loses presigned-URL flow (OCR service downloads files via short-lived URLs, not via shared filesystem), loses the migration path to OBS. The S3 indirection is cheap insurance. |
+| Self-hosted on-VPS plus periodic `mc mirror` to Hetzner OBS for off-site backup | This is the **target** for the backup pipeline follow-up. Treated as backup, not primary — primary stays MinIO. |
+
+## Consequences
+
+- The production VPS sizing (Hetzner CX42, 16 GB RAM, 80 GB disk) must accommodate MinIO's working set. Current footprint leaves ample headroom.
+- Backup of MinIO data is the operator's responsibility until the off-site `mc mirror` pipeline is implemented (deferred follow-up). The DEPLOYMENT.md rollback procedure explicitly flags this — manual backup is the only recovery option until the pipeline ships.
+- The backend never sees the MinIO root password; it uses the `archiv-app` service account with a bucket-scoped IAM policy (see `infra/minio/bootstrap.sh`). A backend RCE/SSRF cannot escalate beyond the `familienarchiv` bucket.
+- The migration to Hetzner OBS remains a small, well-understood runbook step rather than a major refactor. No application code, no SDK swap.
+
+## Future Direction
+
+When one of the triggers above fires, the migration is: provision OBS bucket → `mc mirror` → rotate three env vars → restart backend → remove MinIO service from compose. The bucket-scoped policy translates 1:1 to an OBS user policy (S3-compatible).

docs/adr/011-single-tenant-gitea-runner.md

@@ -0,0 +1,58 @@
+# ADR-011: Single-tenant Gitea runner with secrets-on-disk env-files
+
+## Status
+
+Accepted
+
+## Context
+
+The deploy workflows (`.gitea/workflows/nightly.yml`, `release.yml`) execute on a self-hosted Gitea Actions runner. The runner has Docker-out-of-Docker access (the host's Docker socket is mounted into the runner), so `docker compose build` produces images on the host daemon and `docker compose up` consumes them directly — no registry hop.
+
+Two workflow steps shape the security model:
+
+1. **"Write env file"** — the workflow writes every required secret to `.env.staging` or `.env.production` on the runner's filesystem so that `docker compose --env-file` can consume them. The file lives on disk for the duration of the workflow.
+2. **"Cleanup env file"** — the matching `if: always()` step deletes the env file after the workflow ends, regardless of success.
+
+This shape only works under one operational assumption: **the runner is single-tenant**. The runner is owned by the same operator who owns the secrets, no other repositories run jobs on the same runner, and no untrusted code is executed (no public fork PRs trigger workflows). If any of those held, the env-file-on-disk approach would be a credential exposure path — a sibling job could read `.env.production`, or a malicious PR could exfiltrate the secrets via a step.
+
+The alternative — `docker compose --env-file <(printf "..." )` (bash process substitution) — is technically supported and would keep secrets out of the on-disk filesystem. It is more secure under a multi-tenant runner but requires bash 4+ and is brittle inside YAML (the `printf` step would need to escape every secret value containing newlines, equals signs, or quotes).
+
+## Decision
+
+The runner is treated as single-tenant for the lifetime of the v1 deployment. The workflows write env-files to disk under that assumption and rely on the `if: always()` cleanup step to remove them. The operational assumption is documented in-comment at the top of both workflow files (`nightly.yml`, `release.yml`) so the next operator who considers adding a second repo or accepting public PRs has the trigger surfaced in front of them.
+
+Concretely:
+
+- The Gitea runner only runs jobs for `marcel/familienarchiv`.
+- No public fork PRs trigger the workflows (Gitea defaults to requiring an explicit approval on first-time contributor PRs for the actions to run).
+- Secrets are stored in Gitea repository secrets and injected via `${{ secrets.* }}`. They land in the env-file at workflow start and are removed at workflow end.
+
+## Migration trigger
+
+Switch to the multi-tenant-safe pattern when **any** of the following becomes true:
+
+- A second repository starts using the same runner.
+- A workflow accepts contributions that can run untrusted code (public PRs without manual approval).
+- The runner is moved off the operator's controlled host onto shared infrastructure.
+
+The migration path is one-step per workflow: replace the "Write env file" step with `--env-file <(printf '%s' "${{ secrets.STAGING_ENV_BLOB }}")` and store the full env-file as a single Gitea secret. The cleanup step is then unnecessary because the env-file never touches disk.
+
+## Alternatives Considered
+
+| Alternative | Why rejected (for now) |
+|---|---|
+| `--env-file <(printf "...")` via bash process substitution | More secure under multi-tenant. Brittle for multi-line / quoted secret values; harder to debug ("env file not found" with no diff to inspect). Justified once the trigger above fires. |
+| Docker secrets (`docker secret create` + `compose secrets:`) | Designed for Swarm; outside of Swarm, compose secrets read from files anyway, so the on-disk surface is the same. Adds complexity without changing the threat model. |
+| External secret manager (Vault, AWS Secrets Manager) | Adds a third-party dependency to the deploy path. For a family-archive deployment with one operator and one VPS, the cost outweighs the benefit at this scale. |
+| GitHub-hosted ephemeral runners | Would require uploading the prod-deploy artifacts to a registry first, then a deploy step on the VPS connecting back. Inverts the current Docker-out-of-Docker simplicity for marginal security gain. The single-tenant self-hosted runner *is* ephemeral in practice — the secrets are written to a directory the runner controls, then deleted. |
+
+## Consequences
+
+- The runner host's filesystem is in the secret-trust boundary. The host is hardened per `docs/DEPLOYMENT.md` (ufw, fail2ban, Tailscale-only SSH).
+- An operator who later adds a second repo to the runner without revisiting the workflows would silently break the trust assumption. The in-file comments at the top of `nightly.yml` and `release.yml` are the breadcrumb that surfaces the assumption at change time.
+- The `if: always()` cleanup step is load-bearing: removing it (e.g. during a future workflow refactor) leaves credentials on disk between runs. Treat it as a permanent invariant.
+- Workflow debuggability stays high: an operator who needs to know what env-file the deploy ran with can SSH onto the host while a workflow is in flight and `cat .env.staging` — useful for first-deploy diagnostics.
+
+## Future Direction
+
+When the trigger fires, migrate both workflows in a single PR: replace the "Write env file" step with a single `--env-file <(printf '%s' …)` invocation, drop the cleanup step, and consolidate the per-secret Gitea entries into a single multi-line `STAGING_ENV_BLOB` / `PROD_ENV_BLOB` secret. Single commit, both workflows, no application change.

docs/architecture/c4-diagrams.md

@@ -1,6 +1,8 @@
 # Familienarchiv — C4 Architecture Diagrams
 
 > For domain terminology used in these diagrams, see [docs/GLOSSARY.md](../GLOSSARY.md).
+>
+> **Cross-diagram stubs:** Components placed outside a `System_Boundary` block with a "See diagram X" annotation are reference stubs — they represent a component fully defined in another sub-diagram and appear here only to show the cross-domain dependency without duplicating the full definition.
 
 ## Level 1 — System Context
 
@@ -10,13 +12,15 @@ Who uses the system and what external systems does it interact with.
 C4Context
     title System Context: Familienarchiv
 
-    Person(admin, "Administrator", "Manages users, triggers bulk imports, reviews documents")
-    Person(member, "Family Member", "Searches, browses, and reads archived documents")
+    Person(admin, "Administrator", "Manages users, triggers bulk imports, reviews and transcribes documents")
+    Person(member, "Family Member", "Access by administrator invite. Searches, browses, reads, and transcribes archived documents.")
 
     System(familienarchiv, "Familienarchiv", "Web application for digitising, organising, and searching family documents")
+    System_Ext(mail, "Email Service", "SMTP server. Delivers notification emails (mentions, replies) and password-reset links.")
 
     Rel(admin, familienarchiv, "Manages via browser", "HTTPS")
-    Rel(member, familienarchiv, "Searches and views via browser", "HTTPS")
+    Rel(member, familienarchiv, "Searches, reads, and transcribes via browser", "HTTPS")
+    Rel(familienarchiv, mail, "Sends notification and password-reset emails (optional)", "SMTP")
 ```
 
 ---
@@ -30,9 +34,10 @@ C4Container
     title Container Diagram: Familienarchiv
 
     Person(user, "User", "Admin or family member")
+    System_Ext(mail, "Email Service", "SMTP server. Delivers notification and password-reset emails.")
 
     System_Boundary(archiv, "Familienarchiv (Docker Compose)") {
-        Container(frontend, "Web Frontend", "SvelteKit / Node.js", "Server-side rendered UI. Handles session cookies, search UI, document viewer, and admin panel.")
+        Container(frontend, "Web Frontend", "SvelteKit / Node.js", "Server-side rendered UI. Handles auth session cookies, document search and viewer, transcription editor, annotation layer, family tree (Stammbaum), stories (Geschichten), activity feed (Chronik), enrichment workflow, and admin panel.")
 
         Container(backend, "API Backend", "Spring Boot 4 / Java 21 / Jetty", "REST API. Implements document management, search, user auth, file upload/download, transcription, OCR orchestration, and SSE notifications.")
 
@@ -51,6 +56,7 @@ C4Container
     Rel(backend, db, "Reads and writes metadata and sessions", "JDBC / SQL")
     Rel(backend, storage, "Uploads and streams document files", "HTTP / S3 API (AWS SDK v2)")
     Rel(backend, ocr, "OCR job requests with presigned MinIO URL", "HTTP / REST / JSON")
+    Rel(backend, mail, "Sends notification and password-reset emails (optional)", "SMTP")
     Rel(ocr, storage, "Fetches PDF via presigned URL", "HTTP / S3 presigned")
     Rel(mc, storage, "Creates bucket on startup", "MinIO Client CLI")
 ```
@@ -59,149 +65,444 @@ C4Container
 
 ## Level 3 — Components: API Backend
 
-The internal structure of the Spring Boot backend.
+The internal structure of the Spring Boot backend, split into seven focused sub-diagrams.
+
+### 3a — Security & Authentication
+
+How requests are authenticated and write operations are authorised.
 
 ```mermaid
 C4Component
-    title Component Diagram: API Backend
+    title Component Diagram: API Backend — Security & Authentication
+
+    Container(frontend, "Web Frontend", "SvelteKit")
+    ContainerDb(db, "PostgreSQL")
+
+    System_Boundary(backend, "API Backend (Spring Boot)") {
+        Component(secFilter, "Security Filter Chain", "Spring Security", "Enforces authentication on all requests. Parses Basic Auth header and constructs an Authentication token; delegates credential validation to DaoAuthenticationProvider via BCrypt. Permits password-reset, invite, and register endpoints without authentication.")
+        Component(permAspect, "PermissionAspect", "Spring AOP", "Intercepts methods annotated with @RequirePermission. Checks user's granted authorities against the required permission. Throws 401/403 if denied.")
+        Component(secConf, "SecurityConfig", "Spring @Configuration", "Configures filter chain: all routes require authentication, CSRF disabled, BCrypt password encoder, DaoAuthenticationProvider with CustomUserDetailsService.")
+        Component(userDetails, "CustomUserDetailsService", "Spring Security UserDetailsService", "Loads AppUser by email from DB. Converts group permissions to Spring GrantedAuthority objects. Logs unknown permissions.")
+    }
+
+    Rel(frontend, secFilter, "All requests", "HTTP / Basic Auth header")
+    Rel(secFilter, permAspect, "Authenticated requests reach guarded service methods", "")
+    Rel(secConf, userDetails, "Wires as UserDetailsService", "")
+    Rel(userDetails, db, "Loads user by email", "JDBC")
+```
+
+### 3b — Document Management & Import
+
+Document management, file storage, and bulk Excel/ODS import.
+
+```mermaid
+C4Component
+    title Component Diagram: API Backend — Document Management & Import
 
     Container(frontend, "Web Frontend", "SvelteKit")
     ContainerDb(db, "PostgreSQL")
     ContainerDb(minio, "MinIO")
 
     System_Boundary(backend, "API Backend (Spring Boot)") {
+        Component(docCtrl, "DocumentController", "Spring MVC — /api/documents", "CRUD for documents: search, get by ID, update metadata, upload/download file, conversation thread, and batch metadata updates.")
+        Component(adminCtrl, "AdminController", "Spring MVC — /api/admin", "Triggers asynchronous Excel/ODS mass import (requires ADMIN permission). Reports import state (IDLE/RUNNING/DONE/FAILED).")
 
-        Component(secFilter, "Security Filter Chain", "Spring Security", "Enforces authentication on all requests. Parses Basic Auth header and validates credentials via BCrypt.")
-        Component(permAspect, "PermissionAspect", "Spring AOP", "Intercepts methods annotated with @RequirePermission. Checks user's granted authorities against the required permission. Throws 401/403 if denied.")
+        Component(docSvc, "DocumentService", "Spring Service", "Core document business logic: store, update, search. Resolves persons and tags, delegates file I/O to FileService, builds dynamic JPA Specifications, and integrates with audit logging.")
+        Component(fileSvc, "FileService", "Spring Service", "Wraps AWS SDK v2 S3Client. Uploads files with UUID-keyed paths, computes SHA-256 hash, downloads with content-type detection, and generates presigned URLs for OCR access.")
+        Component(massImport, "MassImportService", "Spring Service — @Async", "Reads Excel/ODS files from /import mount. Tracks import state (IDLE/RUNNING/DONE/FAILED) and delegates to ExcelService. Returns immediately; processing runs asynchronously.")
+        Component(excelSvc, "ExcelService", "Spring Service", "Parses Excel/ODS workbooks (Apache POI). Column indices configurable via application.properties. Creates/updates document records per row.")
+        Component(minioConf, "MinioConfig", "Spring @Configuration", "Creates the S3Client and S3Presigner beans with path-style access for MinIO. Validates MinIO connectivity on startup.")
 
-        Component(docCtrl, "DocumentController", "Spring MVC — /api/documents", "CRUD for documents. Endpoints: search, get by ID, update metadata, upload file, download file, get conversation thread.")
-        Component(personCtrl, "PersonController", "Spring MVC — /api/persons", "Lists and searches family members. Also returns all documents sent by a person.")
-        Component(userCtrl, "UserController", "Spring MVC — /api/users", "Returns current user (/me). Creates and deletes users (requires ADMIN_USER permission).")
-        Component(adminCtrl, "AdminController", "Spring MVC — /api/admin", "Triggers asynchronous Excel mass import (requires ADMIN permission).")
-        Component(groupCtrl, "GroupController", "Spring MVC — /api/groups", "Lists and manages permission groups.")
-        Component(tagCtrl, "TagController", "Spring MVC — /api/tags", "Lists tags for typeahead.")
-
-        Component(docSvc, "DocumentService", "Spring Service", "Core business logic: store, update, search documents. Resolves persons and tags. Delegates file I/O to FileService. Builds JPA Specifications for dynamic search queries.")
-        Component(fileSvc, "FileService", "Spring Service", "Wraps AWS SDK v2 S3Client. Uploads files with UUID-keyed paths. Downloads with content-type detection (PDF, JPEG, PNG, octet-stream).")
-        Component(excelSvc, "ExcelService", "Spring Service", "Parses Excel workbooks (Apache POI). Column indices are configurable via application.properties. Creates/updates document records per row.")
-        Component(massImport, "MassImportService", "Spring Service — @Async", "Reads Excel files from /import mount. Delegates to ExcelService. Runs asynchronously so the HTTP response returns immediately.")
-        Component(userSvc, "UserService", "Spring Service", "User CRUD. Encodes passwords with BCrypt. Assigns users to permission groups.")
-        Component(dataInit, "DataInitializer", "CommandLineRunner", "On startup: creates default admin user and groups if none exist. Seeds test data (persons, documents) if DB is empty.")
-
-        Component(docRepo, "DocumentRepository", "Spring Data JPA", "Queries documents. Supports Specification-based dynamic search, conversation thread queries (bidirectional sender/receiver), and filename lookups.")
-        Component(docSpec, "DocumentSpecifications", "JPA Criteria API", "Factory for composable query predicates: hasText (full-text across title/filename/transcription/location), hasSender, hasReceiver (join), isBetween (date range), hasTags (subquery AND logic).")
-        Component(personRepo, "PersonRepository", "Spring Data JPA", "Lists all persons sorted by last name. Supports name search for typeahead.")
-        Component(userRepo, "AppUserRepository", "Spring Data JPA", "Finds users by username. Used by Spring Security and UserService.")
-        Component(tagRepo, "TagRepository", "Spring Data JPA", "Finds or creates tags by name (case-insensitive).")
-        Component(groupRepo, "UserGroupRepository", "Spring Data JPA", "Manages permission groups.")
-
-        Component(minioConf, "MinioConfig", "Spring @Configuration", "Creates the S3Client bean with path-style access for MinIO. Validates MinIO connectivity on startup.")
-        Component(secConf, "SecurityConfig", "Spring @Configuration", "Configures filter chain: all routes require authentication, CSRF disabled, BCrypt password encoder, DaoAuthenticationProvider with CustomUserDetailsService.")
-        Component(userDetails, "CustomUserDetailsService", "Spring Security UserDetailsService", "Loads AppUser by username from DB. Converts group permissions to Spring GrantedAuthority objects.")
+        Component(docRepo, "DocumentRepository", "Spring Data JPA", "Queries documents with Specification-based dynamic search, bidirectional conversation thread queries, full-text search with ranking and match highlighting, and transcription pipeline queue projections.")
+        Component(docSpec, "DocumentSpecifications", "JPA Criteria API", "Factory for composable predicates: hasText (full-text), hasSender, hasReceiver, isBetween (date range), hasTags (subquery AND/OR logic).")
     }
 
-    Rel(frontend, secFilter, "All requests", "HTTP / Basic Auth header")
-    Rel(secFilter, permAspect, "Authenticated requests proceed", "")
-
-    Rel(secFilter, docCtrl, "Routes to", "")
-    Rel(secFilter, personCtrl, "Routes to", "")
-    Rel(secFilter, userCtrl, "Routes to", "")
-    Rel(secFilter, adminCtrl, "Routes to", "")
-
-    Rel(permAspect, docCtrl, "Guards", "AOP @Around")
-    Rel(permAspect, userCtrl, "Guards", "AOP @Around")
-    Rel(permAspect, adminCtrl, "Guards", "AOP @Around")
+    Component(personSvc, "PersonService", "Spring Service", "See diagram 3e. Called by DocumentService to resolve sender / receiver persons by ID.")
+    Component(tagSvc, "TagService", "Spring Service", "See diagram 3d. Called by DocumentService to find or create tags by name.")
 
+    Rel(frontend, docCtrl, "Document requests", "HTTP / JSON")
+    Rel(frontend, adminCtrl, "Trigger import", "HTTP / JSON")
     Rel(docCtrl, docSvc, "Delegates to", "")
     Rel(adminCtrl, massImport, "Triggers", "")
-    Rel(userCtrl, userSvc, "Delegates to", "")
-
     Rel(docSvc, fileSvc, "Upload / download files", "")
     Rel(docSvc, docRepo, "Reads / writes documents", "")
     Rel(docSvc, docSpec, "Builds search predicates", "")
-    Rel(docSvc, personRepo, "Resolves sender / receivers", "")
-    Rel(docSvc, tagRepo, "Finds or creates tags", "")
-
-    Rel(massImport, excelSvc, "Parses Excel file", "")
+    Rel(docSvc, personSvc, "Resolves sender / receivers", "")
+    Rel(docSvc, tagSvc, "Finds or creates tags", "")
+    Rel(massImport, excelSvc, "Parses Excel/ODS file", "")
     Rel(excelSvc, docSvc, "Creates / updates documents", "")
+    Rel(minioConf, fileSvc, "Provides S3Client and S3Presigner beans", "")
+    Rel(fileSvc, minio, "PUT / GET / presigned URL objects", "S3 API / HTTP")
+    Rel(docRepo, db, "SQL queries", "JDBC")
+```
 
+### 3c — Document Transcription Pipeline
+
+Annotation-driven transcription: page markup, text blocks, versioning, and comment threads.
+
+```mermaid
+C4Component
+    title Component Diagram: API Backend — Document Transcription Pipeline
+
+    Container(frontend, "Web Frontend", "SvelteKit")
+    ContainerDb(db, "PostgreSQL")
+
+    System_Boundary(backend, "API Backend (Spring Boot)") {
+        Component(transcriptionCtrl, "TranscriptionBlockController", "Spring MVC — /api/transcription", "CRUD for transcription text blocks per document page. Manages sort order, review status, and block version history.")
+        Component(annotationCtrl, "AnnotationController", "Spring MVC — /api/documents/{id}/annotations", "CRUD for free-form page annotations with polygon coordinates, colour coding, and file-hash tracking.")
+        Component(commentCtrl, "CommentController", "Spring MVC — /api/documents/{id}/comments", "Threaded comment CRUD on transcription blocks with @mention support and notification triggers.")
+
+        Component(transcriptionSvc, "TranscriptionService", "Spring Service", "Creates and updates transcription blocks from annotation regions. Tracks block versions, sanitizes text with an HTML allow-list, and triggers mentions.")
+        Component(transcriptionQueueSvc, "TranscriptionQueueService", "Spring Service", "Assembles segmentation, transcription, and review queue projections by delegating to DocumentService and AuditLogQueryService.")
+        Component(annotationSvc, "AnnotationService", "Spring Service", "Manages document page annotations with polygon coordinates. Called by OcrAsyncRunner to persist OCR-generated block boundaries.")
+        Component(commentSvc, "CommentService", "Spring Service", "Creates and manages threaded comments with @mention parsing. Triggers NotificationService for REPLY and MENTION events.")
+
+        Component(blockRepo, "TranscriptionBlockRepository", "Spring Data JPA", "Reads and writes TranscriptionBlock and TranscriptionBlockVersion records.")
+        Component(annotationRepo, "AnnotationRepository", "Spring Data JPA", "Reads and writes DocumentAnnotation records.")
+        Component(commentRepo, "CommentRepository", "Spring Data JPA", "Reads and writes DocumentComment records.")
+    }
+
+    Component(documentSvc, "DocumentService", "Spring Service", "See diagram 3b. Called by TranscriptionQueueService to assemble pipeline queue projections.")
+    Component(auditQuerySvc, "AuditLogQueryService", "Spring Service", "See diagram 3g. Called by TranscriptionQueueService for pipeline activity data.")
+
+    Rel(frontend, transcriptionCtrl, "Transcription block requests", "HTTP / JSON")
+    Rel(frontend, annotationCtrl, "Annotation requests", "HTTP / JSON")
+    Rel(frontend, commentCtrl, "Comment requests", "HTTP / JSON")
+    Rel(transcriptionCtrl, transcriptionSvc, "Delegates to", "")
+    Rel(transcriptionCtrl, transcriptionQueueSvc, "Queries pipeline queues", "")
+    Rel(annotationCtrl, annotationSvc, "Delegates to", "")
+    Rel(commentCtrl, commentSvc, "Delegates to", "")
+    Rel(transcriptionSvc, blockRepo, "Reads / writes blocks and versions", "")
+    Rel(annotationSvc, annotationRepo, "Reads / writes annotations", "")
+    Rel(commentSvc, commentRepo, "Reads / writes comments", "")
+    Rel(transcriptionQueueSvc, documentSvc, "Queries pipeline document state", "")
+    Rel(transcriptionQueueSvc, auditQuerySvc, "Queries pipeline activity data", "")
+    Rel(blockRepo, db, "SQL queries", "JDBC")
+    Rel(annotationRepo, db, "SQL queries", "JDBC")
+    Rel(commentRepo, db, "SQL queries", "JDBC")
+```
+
+### 3d — Users, Groups & Administration
+
+User lifecycle, permission groups, tag management, and authentication endpoints.
+
+```mermaid
+C4Component
+    title Component Diagram: API Backend — Users, Groups & Administration
+
+    Container(frontend, "Web Frontend", "SvelteKit")
+    ContainerDb(db, "PostgreSQL")
+
+    System_Boundary(backend, "API Backend (Spring Boot)") {
+        Component(userCtrl, "UserController", "Spring MVC — /api/users", "Returns current user (/me), creates and deletes users (requires ADMIN_USER), supports user search and profile updates.")
+        Component(groupCtrl, "GroupController", "Spring MVC — /api/groups", "Lists and manages permission groups.")
+        Component(tagCtrl, "TagController", "Spring MVC — /api/tags", "Lists tags for typeahead, supports tag merge, tree structure, and subtree deletion.")
+        Component(inviteCtrl, "InviteController", "Spring MVC — /api/auth/invite", "Creates invite codes and validates them at registration time. Rate-limited via WebConfig interceptor.")
+        Component(authCtrl, "AuthController", "Spring MVC — /api/auth", "Handles user registration (POST /register) and password reset token endpoints (/forgot-password, /reset-password).")
+
+        Component(userSvc, "UserService", "Spring Service", "User CRUD with BCrypt password encoding, group assignment, and audit logging. Orchestrates invite-based registration and password reset tokens.")
+        Component(tagSvc, "TagService", "Spring Service", "Tag CRUD with name search, hierarchical tree structure, merge/reparent operations, and recursive subtree deletion.")
+        Component(dataInit, "DataInitializer", "CommandLineRunner", "On startup: creates default admin user and groups if none exist. Seeds test data if DB is empty.")
+
+        Component(userRepo, "AppUserRepository", "Spring Data JPA", "Finds users by email. Supports search by email or display name.")
+        Component(groupRepo, "UserGroupRepository", "Spring Data JPA", "Manages permission groups.")
+        Component(tagRepo, "TagRepository", "Spring Data JPA", "Finds or creates tags by name (case-insensitive). Supports recursive ancestor/descendant CTE queries and merge/reparent helpers.")
+    }
+
+    Rel(frontend, userCtrl, "User requests", "HTTP / JSON")
+    Rel(frontend, groupCtrl, "Group requests", "HTTP / JSON")
+    Rel(frontend, tagCtrl, "Tag requests", "HTTP / JSON")
+    Rel(frontend, inviteCtrl, "Invite validation", "HTTP / JSON")
+    Rel(frontend, authCtrl, "Registration and password reset", "HTTP / JSON")
+    Rel(userCtrl, userSvc, "Delegates to", "")
+    Rel(groupCtrl, userSvc, "Delegates to", "")
+    Rel(tagCtrl, tagSvc, "Delegates to", "")
+    Rel(tagSvc, tagRepo, "Reads / writes tags", "")
+    Rel(inviteCtrl, userSvc, "Creates and validates invites", "")
+    Rel(authCtrl, userSvc, "Registers users, resets passwords", "")
     Rel(userSvc, userRepo, "Reads / writes users", "")
     Rel(userSvc, groupRepo, "Assigns groups", "")
-    Rel(userDetails, userRepo, "Loads user by username", "")
-
-    Rel(fileSvc, minio, "PUT / GET objects", "S3 API / HTTP")
-    Rel(docRepo, db, "SQL queries", "JDBC")
-    Rel(personRepo, db, "SQL queries", "JDBC")
-    Rel(userRepo, db, "SQL queries", "JDBC")
-    Rel(tagRepo, db, "SQL queries", "JDBC")
-    Rel(groupRepo, db, "SQL queries", "JDBC")
     Rel(dataInit, db, "Seeds initial data", "JDBC")
-    Rel(secConf, userDetails, "Wires", "")
-    Rel(minioConf, fileSvc, "Provides S3Client bean", "")
+    Rel(userRepo, db, "SQL queries", "JDBC")
+    Rel(groupRepo, db, "SQL queries", "JDBC")
+    Rel(tagRepo, db, "SQL queries", "JDBC")
+```
+
+### 3e — Persons & Family Graph
+
+Person management including family relationship modelling and transitive inference.
+
+```mermaid
+C4Component
+    title Component Diagram: API Backend — Persons & Family Graph
+
+    Container(frontend, "Web Frontend", "SvelteKit")
+    ContainerDb(db, "PostgreSQL")
+
+    System_Boundary(backend, "API Backend (Spring Boot)") {
+        Component(personCtrl, "PersonController", "Spring MVC — /api/persons", "Lists and searches family members. Returns documents sent by or received by a person, correspondent suggestions, and person summary with document counts.")
+        Component(relCtrl, "RelationshipController", "Spring MVC — /api/network, /api/persons/{id}/relationships", "CRUD for explicit person relationships and the full family network graph (nodes + edges) used by the Stammbaum view.")
+
+        Component(personSvc, "PersonService", "Spring Service", "Person CRUD, alias management, and merge operations (reassigns all document sender/receiver references before deleting duplicate persons).")
+        Component(relSvc, "RelationshipService", "Spring Service", "Manages explicit directional family relationships (PARENT_OF, SPOUSE_OF, SIBLING_OF, etc.) with optional date ranges and notes.")
+        Component(relInference, "RelationshipInferenceService", "Spring Service", "Computes transitive family relationships from explicit edges to infer grandparent/grandchild, aunt/uncle, and other extended-family links for the network graph.")
+
+        Component(personRepo, "PersonRepository", "Spring Data JPA", "Queries persons with name search (including aliases), correspondent discovery, person summaries with document counts, and merge/reassignment helpers.")
+        Component(relRepo, "PersonRelationshipRepository", "Spring Data JPA", "Reads and writes PersonRelationship records. Supports lookup by person ID, by relation type, and existence checks for deduplication.")
+    }
+
+    Rel(frontend, personCtrl, "Person requests", "HTTP / JSON")
+    Rel(frontend, relCtrl, "Relationship and graph requests", "HTTP / JSON")
+    Rel(personCtrl, personSvc, "Delegates to", "")
+    Rel(relCtrl, relSvc, "Delegates to", "")
+    Rel(relCtrl, relInference, "Queries inferred graph", "")
+    Rel(personSvc, personRepo, "Reads / writes persons", "")
+    Rel(relSvc, relRepo, "Reads / writes relationships", "")
+    Rel(relInference, relRepo, "Reads relationships for inference", "")
+    Rel(personRepo, db, "SQL queries", "JDBC")
+    Rel(relRepo, db, "SQL queries", "JDBC")
+```
+
+### 3f — OCR Orchestration
+
+How the Spring Boot backend manages OCR jobs, streams results, and trains recognition models.
+
+```mermaid
+C4Component
+    title Component Diagram: API Backend — OCR Orchestration
+
+    Container(frontend, "Web Frontend", "SvelteKit")
+    ContainerDb(db, "PostgreSQL")
+    ContainerDb(minio, "MinIO")
+    Container(ocrPy, "OCR Service", "Python FastAPI")
+
+    System_Boundary(backend, "API Backend (Spring Boot)") {
+        Component(ocrCtrl, "OcrController", "Spring MVC — /api/ocr", "REST entry point: trigger single or batch OCR jobs, stream progress via SSE, query job status, and manage training runs and per-sender models.")
+        Component(ocrSvc, "OcrService", "Spring Service", "Creates OcrJob and OcrJobDocument records, checks Python service health, and delegates async execution to OcrAsyncRunner.")
+        Component(ocrBatch, "OcrBatchService", "Spring Service", "Orchestrates multi-document OCR jobs, iterating documents and delegating each to OcrAsyncRunner.")
+        Component(ocrAsync, "OcrAsyncRunner", "Spring Component — @Async", "Async worker that streams OCR results from Python page by page, persists transcription blocks and annotations via domain services, and emits progress via SSE.")
+        Component(ocrClient, "RestClientOcrClient", "Spring Component", "HTTP client wrapping the Python service: POST /ocr/stream (NDJSON), /train, /segtrain, and /train-sender. Falls back from streaming to batch on 404.")
+        Component(ocrTraining, "OcrTrainingService", "Spring Service", "Orchestrates model training: exports training data as ZIP, calls Python /train or /segtrain, persists training metrics in OcrTrainingRunRepository.")
+        Component(ocrJobRepo, "OcrJobRepository, OcrJobDocumentRepository", "Spring Data JPA", "Reads and writes OcrJob and OcrJobDocument records. Tracks job status (RUNNING/DONE/FAILED), per-document progress, page counts, and error messages.")
+    }
+
+    Component(transcriptionSvc, "TranscriptionService", "Spring Service", "See diagram 3c. Called by OcrAsyncRunner to persist transcription blocks per page.")
+    Component(annotationSvc, "AnnotationService", "Spring Service", "See diagram 3c. Called by OcrAsyncRunner to persist OCR-generated annotation regions per page.")
+
+    Rel(frontend, ocrCtrl, "OCR trigger, status, and progress requests", "HTTP / JSON / SSE")
+    Rel(ocrCtrl, ocrSvc, "Single-document jobs", "")
+    Rel(ocrCtrl, ocrBatch, "Batch jobs", "")
+    Rel(ocrCtrl, ocrTraining, "Training runs", "")
+    Rel(ocrSvc, ocrAsync, "Delegates async execution", "")
+    Rel(ocrBatch, ocrAsync, "Delegates async execution", "")
+    Rel(ocrAsync, ocrClient, "Streams OCR results page by page", "HTTP / NDJSON")
+    Rel(ocrTraining, ocrClient, "Sends training data ZIP", "HTTP / multipart")
+    Rel(ocrClient, ocrPy, "POST /ocr/stream, /train, /segtrain, /train-sender", "HTTP / REST")
+    Rel(ocrAsync, transcriptionSvc, "Saves transcription blocks per page", "")
+    Rel(ocrAsync, annotationSvc, "Saves annotation regions per page", "")
+    Rel(ocrAsync, ocrJobRepo, "Reads / writes OCR job state", "")
+    Rel(ocrJobRepo, db, "SQL queries", "JDBC")
+    Rel(ocrAsync, minio, "Generates presigned URLs for PDF fetch", "S3 API")
+    Rel(ocrPy, minio, "Fetches PDF via presigned URL", "HTTP / S3 presigned")
+    Rel(ocrTraining, db, "Persists training run metrics", "JDBC")
+```
+
+### 3g — Supporting Domains
+
+Audit logging, dashboard stats, SSE notifications, stories (Geschichten), and cross-cutting exception handling.
+
+```mermaid
+C4Component
+    title Component Diagram: API Backend — Supporting Domains
+
+    Container(frontend, "Web Frontend", "SvelteKit")
+    ContainerDb(db, "PostgreSQL")
+
+    System_Boundary(backend, "API Backend (Spring Boot)") {
+        Component(auditSvc, "AuditService", "Spring Service — @Async", "Writes audit log entries asynchronously via a dedicated TaskExecutor, with transaction-aware logging to prevent deadlocks on concurrent saves.")
+        Component(auditQuery, "AuditLogQueryService", "Spring Service", "Queries audit logs for activity feeds, pulse stats, recent contributors, and per-document history. Facade over AuditLogRepository.")
+
+        Component(dashCtrl, "DashboardController", "Spring MVC — /api/dashboard", "REST endpoints for the user dashboard: recent document resume (/resume), weekly transcription pulse stats (/pulse), and activity feed (/activity) with kind filtering and pagination.")
+        Component(statsCtrl, "StatsController", "Spring MVC — /api/stats", "Returns aggregate counts (total persons, total documents) for the UI stats bar.")
+        Component(statsSvc, "StatsService", "Spring Service", "Queries aggregate counts: total persons and total documents.")
+        Component(dashSvc, "DashboardService", "Spring Service", "Assembles the user dashboard: recent document resume (calls DocumentService + TranscriptionService), weekly transcription pulse stats, and activity feed with contributor avatars.")
+
+        Component(notifCtrl, "NotificationController", "Spring MVC — /api/notifications", "REST and SSE endpoints for notification stream, history with filtering, read/unread state, and per-user preference management.")
+        Component(notifSvc, "NotificationService", "Spring Service", "Creates REPLY and MENTION notifications, optionally sends email, marks as read, and pushes events to connected clients via SseEmitterRegistry.")
+        Component(sseRegistry, "SseEmitterRegistry", "Spring Component", "In-memory ConcurrentHashMap of Spring SseEmitter instances per user. Handles registration, deregistration, and JSON event broadcasts.")
+
+        Component(geschCtrl, "GeschichteController", "Spring MVC — /api/geschichten", "CRUD for publishable stories that link persons and documents. Requires BLOG_WRITE permission for write operations.")
+        Component(geschSvc, "GeschichteService", "Spring Service", "Manages story lifecycle (DRAFT → PUBLISHED with timestamp). Sanitizes HTML body with an allowlist policy.")
+
+        Component(exHandler, "GlobalExceptionHandler", "Spring @RestControllerAdvice", "Converts DomainException, validation errors, and generic exceptions to ErrorResponse JSON with machine-readable ErrorCode and HTTP status.")
+    }
+
+    Component(documentSvc, "DocumentService", "Spring Service", "See diagram 3b. Called by DashboardService to fetch document titles and resume data.")
+    Component(transcriptionSvc, "TranscriptionService", "Spring Service", "See diagram 3c. Called by DashboardService to fetch transcription block progress for resume.")
+
+    Rel(frontend, dashCtrl, "Dashboard requests", "HTTP / JSON")
+    Rel(frontend, statsCtrl, "GET /api/stats", "HTTP / JSON")
+    Rel(frontend, notifCtrl, "Notification stream and history", "HTTP / JSON / SSE")
+    Rel(frontend, geschCtrl, "Story requests", "HTTP / JSON")
+    Rel(dashCtrl, dashSvc, "Delegates to", "")
+    Rel(statsCtrl, statsSvc, "Delegates to", "")
+    Rel(statsSvc, db, "Reads aggregate counts", "JDBC")
+    Rel(dashSvc, auditQuery, "Fetches activity feed and pulse stats", "")
+    Rel(dashSvc, documentSvc, "Fetches document titles and resume data", "")
+    Rel(dashSvc, transcriptionSvc, "Fetches transcription block progress for resume", "")
+    Rel(notifCtrl, notifSvc, "Delegates to", "")
+    Rel(notifCtrl, sseRegistry, "Registers client SSE connection", "")
+    Rel(notifSvc, sseRegistry, "Broadcasts events to connected clients", "")
+    Rel(geschCtrl, geschSvc, "Delegates to", "")
+    Rel(auditSvc, db, "Writes audit_log", "JDBC")
+    Rel(auditQuery, db, "Reads audit_log", "JDBC")
+    Rel(notifSvc, db, "Reads / writes notifications", "JDBC")
+    Rel(geschSvc, db, "Reads / writes geschichten", "JDBC")
 ```
 
 ---
 
 ## Level 3 — Components: Web Frontend
 
-The internal structure of the SvelteKit frontend.
+The internal structure of the SvelteKit frontend, split into four focused views.
+
+### 3a — Middleware, Auth & Layout
+
+Per-request middleware: session validation, i18n, auth cookie handling, and auth pages.
 
 ```mermaid
 C4Component
-    title Component Diagram: Web Frontend
+    title Component Diagram: Web Frontend — Middleware, Auth & Layout
 
     Person(user, "User")
     Container(backend, "API Backend", "Spring Boot")
 
     System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") {
-
-        Component(hooks, "hooks.server.ts", "SvelteKit Server Hook", "Two responsibilities: (1) userGroup handle — reads auth_token cookie, fetches /api/users/me, stores user in event.locals. (2) handleFetch — intercepts all outgoing fetch() calls, injects Authorization header from cookie. Redirects to /login if token absent.")
+        Component(hooks, "hooks.server.ts", "SvelteKit Server Hook", "Four handle layers: (1) handleAuth — redirects unauthenticated users to /login; (2) userGroup — reads auth_token cookie, fetches /api/users/me, stores user in event.locals; (3) handleFetch — injects Authorization header on all outgoing /api/ calls; (4) handleLocaleDetection — sets language cookie from Accept-Language header.")
         Component(i18n, "hooks.ts (Paraglide)", "SvelteKit Client Hook", "Client-side i18n middleware. Detects language from URL and sets the active locale for Paraglide.js translation functions.")
-
         Component(layout, "+layout.server.ts", "SvelteKit Layout Loader", "Passes event.locals.user down to all child pages so every route has access to the authenticated user.")
-
-        Component(homePage, "/ (Home / Search)", "SvelteKit Route", "Loader: parses URL search params (q, from, to, senderId, receiverId, tags), fetches /api/documents/search and /api/persons, returns results. Page: renders search form with full-text, date range, sender/receiver typeahead, tag filters. Displays paginated document list.")
-        Component(docDetail, "/documents/[id]", "SvelteKit Route", "Loader: fetches /api/documents/{id}. Handles 401 redirect to login, 404 error. Page: shows document metadata, file viewer (PDF/image inline), transcription, tags.")
-        Component(docEdit, "/documents/[id]/edit", "SvelteKit Route", "Form with PersonTypeahead for sender/receiver, TagInput for tags, date/location fields. Submits PUT to /api/documents/{id}.")
-        Component(persons, "/persons and /persons/[id]", "SvelteKit Routes", "Lists all persons. Detail page shows person metadata and all documents they sent.")
-        Component(conversations, "/conversations", "SvelteKit Route", "Selects two persons via PersonTypeahead, fetches /api/documents/conversation, displays chronological exchange.")
-        Component(loginPage, "/login", "SvelteKit Route", "Form action: encodes username:password as Base64 Basic Auth token, POSTs to /api/users/me to validate, sets auth_token httpOnly cookie (SameSite=strict, maxAge=86400), redirects to /.")
+        Component(loginPage, "/login", "SvelteKit Route", "Form action: encodes email:password as Base64 Basic Auth token, POSTs to /api/users/me to validate, sets auth_token httpOnly cookie (SameSite=strict, maxAge=86400), redirects to /.")
         Component(logoutPage, "/logout", "SvelteKit Route (server-only)", "Clears the auth_token cookie and redirects to /login.")
-        Component(adminPage, "/admin", "SvelteKit Route", "User management UI (create/delete users). Excel import trigger button (calls /api/admin/trigger-import).")
-
-        Component(apiPersons, "/api/persons (SvelteKit API)", "SvelteKit Server Route", "Proxies GET /api/persons?q=... to backend. Used by PersonTypeahead for typeahead suggestions.")
-        Component(apiTags, "/api/tags (SvelteKit API)", "SvelteKit Server Route", "Proxies GET /api/tags to backend. Used by TagInput for autocomplete.")
-
-        Component(typeahead, "PersonTypeahead.svelte", "Svelte Component", "Async autocomplete for selecting a person. Debounces input, calls /api/persons?q=.")
-        Component(tagInput, "TagInput.svelte", "Svelte Component", "Multi-tag input. Supports free-text entry and selecting existing tags from /api/tags.")
+        Component(registerPage, "/register", "SvelteKit Route", "Loader validates invite code via GET /api/auth/invite/{code}. Form action: POST /api/auth/register to create the user account.")
+        Component(forgotPw, "/forgot-password", "SvelteKit Route", "Form action: POST /api/auth/forgot-password. Always responds with success to prevent email enumeration.")
+        Component(resetPw, "/reset-password", "SvelteKit Route", "Form action: POST /api/auth/reset-password with the token from the query string.")
     }
 
     Rel(user, hooks, "Every browser request", "HTTPS")
     Rel(hooks, backend, "GET /api/users/me (session check)", "HTTP / Basic Auth")
     Rel(hooks, loginPage, "Redirect if no token", "")
-
-    Rel(layout, homePage, "Provides user context", "")
-    Rel(layout, docDetail, "Provides user context", "")
-    Rel(layout, adminPage, "Provides user context", "")
-
-    Rel(homePage, backend, "GET /api/documents/search", "HTTP / JSON")
-    Rel(homePage, backend, "GET /api/persons", "HTTP / JSON")
-    Rel(docDetail, backend, "GET /api/documents/{id}", "HTTP / JSON")
-    Rel(docDetail, backend, "GET /api/documents/{id}/file", "HTTP / Binary stream")
-    Rel(docEdit, backend, "PUT /api/documents/{id}", "HTTP / Multipart")
-    Rel(conversations, backend, "GET /api/documents/conversation", "HTTP / JSON")
+    Rel(hooks, layout, "Stores authenticated user in event.locals", "")
     Rel(loginPage, backend, "POST /api/users/me (auth check)", "HTTP / Basic Auth")
-    Rel(adminPage, backend, "GET/POST/DELETE /api/users", "HTTP / JSON")
-    Rel(adminPage, backend, "POST /api/admin/trigger-import", "HTTP / JSON")
+    Rel(registerPage, backend, "GET /api/auth/invite/{code}, POST /api/auth/register", "HTTP / JSON")
+    Rel(forgotPw, backend, "POST /api/auth/forgot-password", "HTTP / JSON")
+    Rel(resetPw, backend, "POST /api/auth/reset-password", "HTTP / JSON")
+```
 
-    Rel(apiPersons, backend, "GET /api/persons", "HTTP / JSON")
-    Rel(apiTags, backend, "GET /api/tags", "HTTP / JSON")
+### 3b — Document Workflows
 
+Document search, viewing, editing, enrichment, and the shared components that support them.
+
+```mermaid
+C4Component
+    title Component Diagram: Web Frontend — Document Workflows
+
+    Person(user, "User")
+    Container(backend, "API Backend", "Spring Boot")
+
+    System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") {
+        Component(homePage, "/ (Home / Search)", "SvelteKit Route", "Loader: parses URL params (q, from, to, senderId, receiverId, tags), fetches /api/documents/search and /api/persons. Renders search form with full-text, date range, sender/receiver typeahead, and tag filters.")
+        Component(docDetail, "/documents/[id]", "SvelteKit Route", "Loader: GET /api/documents/{id}. Page: metadata panel, inline file viewer, transcription editor, annotation layer, and comment thread.")
+        Component(docEdit, "/documents/[id]/edit", "SvelteKit Route", "Edit form with PersonTypeahead, TagInput, date/location fields. Form action: PUT /api/documents/{id}.")
+        Component(docNew, "/documents/new", "SvelteKit Route", "Upload form for a new document. Loader: GET /api/persons. Form action: POST /api/documents with multipart file.")
+        Component(docBulkEdit, "/documents/bulk-edit", "SvelteKit Route", "Multi-document metadata editor. Loader: GET /api/documents/incomplete. Requires WRITE_ALL (redirects otherwise). Action: PATCH /api/documents/bulk.")
+        Component(enrichPage, "/enrich/[id]", "SvelteKit Route", "Guided enrichment workflow. Loader: GET /api/documents/{id}. Progressively saves annotations and transcription blocks.")
+
+        Component(apiPersons, "/api/persons (SvelteKit API)", "SvelteKit Server Route", "Proxies GET /api/persons?q=... to backend for PersonTypeahead suggestions.")
+        Component(apiTags, "/api/tags (SvelteKit API)", "SvelteKit Server Route", "Proxies GET /api/tags to backend for TagInput autocomplete.")
+        Component(typeahead, "PersonTypeahead.svelte", "Svelte Component", "Async autocomplete for selecting a person. Debounces input, calls /api/persons?q=.")
+        Component(tagInput, "TagInput.svelte", "Svelte Component", "Multi-tag input. Supports free-text entry and selecting existing tags from /api/tags.")
+    }
+
+    Rel(user, homePage, "Searches and browses", "HTTPS / Browser")
+    Rel(homePage, backend, "GET /api/documents/search, GET /api/persons", "HTTP / JSON")
+    Rel(docDetail, backend, "GET /api/documents/{id}, GET /api/documents/{id}/file", "HTTP / JSON + Binary")
+    Rel(docEdit, backend, "PUT /api/documents/{id}", "HTTP / Multipart")
+    Rel(docNew, backend, "GET /api/persons, POST /api/documents", "HTTP / JSON + Multipart")
+    Rel(docBulkEdit, backend, "GET /api/documents/incomplete, PATCH /api/documents/bulk", "HTTP / JSON")
+    Rel(enrichPage, backend, "GET/POST /api/transcription, POST /api/documents/{id}/annotations", "HTTP / JSON")
     Rel(homePage, typeahead, "Uses for sender/receiver filter", "")
     Rel(docEdit, typeahead, "Uses for sender/receiver selection", "")
+    Rel(docNew, typeahead, "Uses for sender selection", "")
     Rel(docEdit, tagInput, "Uses for tag management", "")
     Rel(typeahead, apiPersons, "Fetches suggestions", "HTTP")
     Rel(tagInput, apiTags, "Fetches existing tags", "HTTP")
+    Rel(apiPersons, backend, "GET /api/persons", "HTTP / JSON")
+    Rel(apiTags, backend, "GET /api/tags", "HTTP / JSON")
+```
+
+### 3c — People, Stories & Discovery
+
+Person directory, bilateral conversations, activity feed, stories, family tree, and user profiles.
+
+```mermaid
+C4Component
+    title Component Diagram: Web Frontend — People, Stories & Discovery
+
+    Person(user, "User")
+    Container(backend, "API Backend", "Spring Boot")
+
+    System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") {
+        Component(personsPage, "/persons and /persons/[id]", "SvelteKit Routes", "Person directory and detail. Detail: metadata, document list sent/received, correspondents, explicit and inferred family relationships.")
+        Component(personEdit, "/persons/[id]/edit and /persons/new", "SvelteKit Routes", "Create and edit person forms. Edit: metadata, aliases, explicit relationships. Actions: PUT/POST /api/persons.")
+        Component(briefwechsel, "/briefwechsel", "SvelteKit Route", "Bilateral conversation timeline. Selects two persons via PersonTypeahead, fetches GET /api/documents/conversation, displays chronological exchange.")
+        Component(aktivitaeten, "/aktivitaeten", "SvelteKit Route", "Unified activity feed (Chronik). Loader: GET /api/dashboard/activity and GET /api/notifications?read=false.")
+        Component(geschichten, "/geschichten and /geschichten/[id]", "SvelteKit Routes", "Story list and detail pages. Loader: GET /api/geschichten?status=PUBLISHED.")
+        Component(geschichtenEdit, "/geschichten/[id]/edit and /geschichten/new", "SvelteKit Routes", "Story editor with rich text, person and document linking. Actions: PUT/POST /api/geschichten. Requires BLOG_WRITE permission.")
+        Component(stammbaum, "/stammbaum", "SvelteKit Route", "Family tree visualisation. Loader: GET /api/network (nodes + edges). Renders interactive family tree from network graph data.")
+        Component(profilePage, "/profile", "SvelteKit Route", "Current user profile settings. Loader: GET /api/users/me/notification-preferences. Actions: update name/password and notification preferences.")
+        Component(userProfile, "/users/[id]", "SvelteKit Route", "Public user profile view. Loader: GET /api/users/{id}.")
+    }
+
+    Rel(user, personsPage, "Browses family members", "HTTPS / Browser")
+    Rel(personsPage, backend, "GET /api/persons, GET /api/persons/{id}", "HTTP / JSON")
+    Rel(personEdit, backend, "GET /api/persons/{id}, PUT /api/persons/{id}, POST /api/persons", "HTTP / JSON")
+    Rel(briefwechsel, backend, "GET /api/documents/conversation", "HTTP / JSON")
+    Rel(aktivitaeten, backend, "GET /api/dashboard/activity, GET /api/notifications", "HTTP / JSON")
+    Rel(geschichten, backend, "GET /api/geschichten", "HTTP / JSON")
+    Rel(geschichtenEdit, backend, "GET/PUT/POST /api/geschichten", "HTTP / JSON")
+    Rel(stammbaum, backend, "GET /api/network", "HTTP / JSON")
+    Rel(profilePage, backend, "GET/PUT /api/users/me, notification-preferences", "HTTP / JSON")
+    Rel(userProfile, backend, "GET /api/users/{id}", "HTTP / JSON")
+```
+
+### 3d — Administration & Help
+
+Admin panel sub-routes and the transcription help guide.
+
+```mermaid
+C4Component
+    title Component Diagram: Web Frontend — Administration & Help
+
+    Person(admin, "Administrator")
+    Person(user, "User")
+    Container(backend, "API Backend", "Spring Boot")
+
+    System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") {
+        Component(adminUsers, "/admin/users, /admin/users/[id], /admin/users/new, /admin/invites", "SvelteKit Routes", "User directory, create/update/delete users, and manage invite codes. Requires ADMIN_USER permission.")
+        Component(adminGroups, "/admin/groups, /admin/groups/[id], /admin/groups/new", "SvelteKit Routes", "Permission group management: create/edit groups and their permission sets.")
+        Component(adminTags, "/admin/tags and /admin/tags/[id]", "SvelteKit Routes", "Tag administration: edit tag hierarchy, merge tags, delete subtrees.")
+        Component(adminOcr, "/admin/ocr and /admin/ocr/[personId]", "SvelteKit Routes", "Global and per-person OCR configuration. Manages script types and triggers sender model training.")
+        Component(adminSystem, "/admin/system", "SvelteKit Route", "System status panel. Triggers Excel/ODS mass import (POST /api/admin/trigger-import). Displays import state.")
+        Component(hilfe, "/hilfe/transkription", "SvelteKit Route", "Static transcription style guide for Kurrent and Sütterlin character recognition. No backend calls.")
+    }
+
+    Rel(admin, adminUsers, "Manages users and invites", "HTTPS / Browser")
+    Rel(user, hilfe, "Views transcription style guide", "HTTPS / Browser")
+    Rel(adminUsers, backend, "GET/POST/DELETE /api/users, POST /api/auth/invite", "HTTP / JSON")
+    Rel(adminGroups, backend, "GET/POST/PUT/DELETE /api/groups", "HTTP / JSON")
+    Rel(adminTags, backend, "GET/PUT/DELETE /api/tags", "HTTP / JSON")
+    Rel(adminOcr, backend, "GET/POST /api/ocr (global config and sender training)", "HTTP / JSON")
+    Rel(adminSystem, backend, "POST /api/admin/trigger-import, GET /api/admin/import-status", "HTTP / JSON")
 ```
 
 ---
@@ -218,12 +519,12 @@ sequenceDiagram
     participant Backend as Backend (Spring Boot)
     participant DB as PostgreSQL
 
-    User->>Browser: Enter username + password
+    User->>Browser: Enter email + password
     Browser->>Frontend: POST /login (form action)
-    Frontend->>Frontend: Base64 encode "user:password"
+    Frontend->>Frontend: Base64 encode "email:password"
     Frontend->>Backend: GET /api/users/me<br/>Authorization: Basic <token>
     Backend->>Backend: Spring Security parses Basic Auth
-    Backend->>DB: SELECT user WHERE username=?
+    Backend->>DB: SELECT user WHERE email=?
     DB-->>Backend: AppUser + groups + permissions
     Backend->>Backend: BCrypt.matches(password, hash)
     Backend-->>Frontend: 200 OK — UserDTO
@@ -271,3 +572,14 @@ sequenceDiagram
     Backend-->>Frontend: 200 OK — Document JSON
     Frontend-->>User: Refreshed document view
 ```
+
+---
+
+## Database
+
+Entity-relationship and full column reference for the PostgreSQL schema (30 tables, 7 domain groups). Source files in `docs/architecture/db/`.
+
+- **[db-relationships.puml](db/db-relationships.puml)** — Entity relationships: all tables and foreign-key connections, grouped by domain. Start here for an overview.
+- **[db-orm.puml](db/db-orm.puml)** — Full schema reference: all columns and types for all 30 tables. Use this when mapping Java entities to database columns.
+
+> Schema as of Flyway V60 (2026-05-06). Open in VS Code with the PlantUML extension (server: `http://heim-nas:8500`).

docs/architecture/c4/README.md

@@ -0,0 +1,39 @@
+# C4-PlantUML Diagrams
+
+Architecture diagrams in C4-PlantUML format. These are the authoritative source for layout-accurate diagrams. The companion `c4-diagrams.md` in the parent directory keeps Mermaid versions for inline Gitea rendering.
+
+## Render in Gitea
+
+Gitea is configured to render `.puml` files as diagrams. Open any `.puml` file in the Gitea UI to see the rendered diagram.
+
+> **Note:** `plantuml` code fences inside Markdown files do **not** render inline in Gitea — this is a Gitea limitation unrelated to the server configuration. The `.md` files in this repo use Mermaid for that reason.
+
+## Render in VS Code
+
+Install the [PlantUML extension](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml) (`jebbs.plantuml`). The project's `.vscode/settings.json` already points at the shared server:
+
+```
+plantuml.server = http://heim-nas:8500
+```
+
+Open any `.puml` file and press `Alt+D` to preview.
+
+## Files
+
+| File | Diagram |
+|---|---|
+| `l1-context.puml` | Level 1 — System Context |
+| `l2-containers.puml` | Level 2 — Containers |
+| `l3-backend-3a-security.puml` | L3 Backend: Security & Authentication |
+| `l3-backend-3b-document-management.puml` | L3 Backend: Document Management & Import |
+| `l3-backend-3c-transcription.puml` | L3 Backend: Document Transcription Pipeline |
+| `l3-backend-3d-users-groups.puml` | L3 Backend: Users, Groups & Administration |
+| `l3-backend-3e-persons.puml` | L3 Backend: Persons & Family Graph |
+| `l3-backend-3f-ocr.puml` | L3 Backend: OCR Orchestration |
+| `l3-backend-3g-supporting.puml` | L3 Backend: Supporting Domains |
+| `l3-frontend-3a-middleware-auth.puml` | L3 Frontend: Middleware, Auth & Layout |
+| `l3-frontend-3b-document-workflows.puml` | L3 Frontend: Document Workflows |
+| `l3-frontend-3c-people-stories.puml` | L3 Frontend: People, Stories & Discovery |
+| `l3-frontend-3d-administration.puml` | L3 Frontend: Administration & Help |
+| `seq-auth-flow.puml` | Sequence: Authentication Flow |
+| `seq-document-upload.puml` | Sequence: Document Upload Flow |

docs/architecture/c4/l1-context.puml

@@ -0,0 +1,16 @@
+@startuml
+!include <C4/C4_Context>
+
+title System Context: Familienarchiv
+
+Person(admin, "Administrator", "Manages users, triggers bulk imports, reviews and transcribes documents")
+Person(member, "Family Member", "Access by administrator invite. Searches, browses, reads, and transcribes archived documents.")
+
+System(familienarchiv, "Familienarchiv", "Web application for digitising, organising, and searching family documents")
+System_Ext(mail, "Email Service", "SMTP server. Delivers notification emails (mentions, replies) and password-reset links.")
+
+Rel(admin, familienarchiv, "Manages via browser", "HTTPS")
+Rel(member, familienarchiv, "Searches, reads, and transcribes via browser", "HTTPS")
+Rel(familienarchiv, mail, "Sends notification and password-reset emails (optional)", "SMTP")
+
+@enduml

docs/architecture/c4/l2-containers.puml

@@ -0,0 +1,32 @@
+@startuml
+!include <C4/C4_Container>
+
+title Container Diagram: Familienarchiv
+
+Person(user, "User", "Admin or family member")
+System_Ext(mail, "Email Service", "SMTP server. Delivers notification and password-reset emails.")
+
+Container(caddy, "Reverse Proxy", "Caddy 2 (host-installed)", "TLS termination (auto Let's Encrypt). Routes /api/* to backend:8080, everything else to frontend:3000. Responds 404 on /actuator/* and adds HSTS, X-Content-Type-Options, Referrer-Policy headers.")
+
+System_Boundary(archiv, "Familienarchiv (Docker Compose)") {
+    Container(frontend, "Web Frontend", "SvelteKit / Node adapter / port 3000", "Server-side rendered UI. Handles auth session cookies, document search and viewer, transcription editor, annotation layer, family tree (Stammbaum), stories (Geschichten), activity feed (Chronik), enrichment workflow, and admin panel.")
+    Container(backend, "API Backend", "Spring Boot 4 / Java 21 / Jetty / port 8080", "REST API. Implements document management, search, user auth, file upload/download, transcription, OCR orchestration, and SSE notifications. Trusts X-Forwarded-* headers from Caddy.")
+    Container(ocr, "OCR Service", "Python FastAPI / port 8000", "Handwritten text recognition (HTR) and OCR microservice. Single-node by design — see ADR-001. Reachable only on the internal Docker network; no external port exposed.")
+    ContainerDb(db, "Relational Database", "PostgreSQL 16", "Stores document metadata, persons, users, permission groups, tags, transcription blocks, audit log, and Spring Session data.")
+    ContainerDb(storage, "Object Storage", "MinIO (S3-compatible)", "Stores the actual document files (PDFs, scans). Backend uses a bucket-scoped service account (archiv-app), not MinIO root.")
+    Container(mc, "Bucket / Service-Account Init", "MinIO Client (mc)", "One-shot container on startup. Idempotent: creates the archive bucket, the archiv-app service account, and attaches the readwrite policy.")
+}
+
+Rel(user, caddy, "HTTPS", "TLS 1.2/1.3")
+Rel(caddy, frontend, "Reverse proxies non-/api requests", "HTTP / loopback:3000")
+Rel(caddy, backend, "Reverse proxies /api/*", "HTTP / loopback:8080")
+Rel(frontend, backend, "API requests with Basic Auth token", "HTTP / REST / JSON")
+Rel(backend, user, "SSE notifications (server-sent events)", "HTTP / SSE — fronted by Caddy")
+Rel(backend, db, "Reads and writes metadata and sessions", "JDBC / SQL")
+Rel(backend, storage, "Uploads and streams document files using archiv-app service account", "HTTP / S3 API (AWS SDK v2)")
+Rel(backend, ocr, "OCR job requests with presigned MinIO URL", "HTTP / REST / JSON")
+Rel(backend, mail, "Sends notification and password-reset emails (optional)", "SMTP")
+Rel(ocr, storage, "Fetches PDF via presigned URL", "HTTP / S3 presigned")
+Rel(mc, storage, "Bootstraps bucket + service account on startup", "MinIO Client CLI")
+
+@enduml

docs/architecture/c4/l3-backend-3a-security.puml

@@ -0,0 +1,21 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: API Backend — Security & Authentication
+
+Container(frontend, "Web Frontend", "SvelteKit")
+ContainerDb(db, "PostgreSQL", "PostgreSQL 16")
+
+System_Boundary(backend, "API Backend (Spring Boot)") {
+    Component(secFilter, "Security Filter Chain", "Spring Security", "Enforces authentication on all requests. Parses Basic Auth header and constructs an Authentication token; delegates credential validation to DaoAuthenticationProvider via BCrypt. Permits password-reset, invite, and register endpoints without authentication.")
+    Component(permAspect, "PermissionAspect", "Spring AOP", "Intercepts methods annotated with @RequirePermission. Checks user's granted authorities against the required permission. Throws 401/403 if denied.")
+    Component(secConf, "SecurityConfig", "Spring @Configuration", "Configures filter chain: all routes require authentication, CSRF disabled, BCrypt password encoder, DaoAuthenticationProvider with CustomUserDetailsService.")
+    Component(userDetails, "CustomUserDetailsService", "Spring Security UserDetailsService", "Loads AppUser by email from DB. Converts group permissions to Spring GrantedAuthority objects. Logs unknown permissions.")
+}
+
+Rel(frontend, secFilter, "All requests", "HTTP / Basic Auth header")
+Rel(secFilter, permAspect, "Authenticated requests reach guarded service methods")
+Rel(secConf, userDetails, "Wires as UserDetailsService")
+Rel(userDetails, db, "Loads user by email", "JDBC")
+
+@enduml

docs/architecture/c4/l3-backend-3b-document-management.puml

@@ -0,0 +1,40 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: API Backend — Document Management & Import
+
+Container(frontend, "Web Frontend", "SvelteKit")
+ContainerDb(db, "PostgreSQL", "PostgreSQL 16")
+ContainerDb(minio, "Object Storage", "MinIO (S3-compatible)")
+
+System_Boundary(backend, "API Backend (Spring Boot)") {
+    Component(docCtrl, "DocumentController", "Spring MVC — /api/documents", "CRUD for documents: search, get by ID, update metadata, upload/download file, conversation thread, batch metadata updates, and per-month density aggregation for the timeline filter widget.")
+    Component(adminCtrl, "AdminController", "Spring MVC — /api/admin", "Triggers asynchronous Excel/ODS mass import (requires ADMIN permission). Reports import state (IDLE/RUNNING/DONE/FAILED).")
+    Component(docSvc, "DocumentService", "Spring Service", "Core document business logic: store, update, search. Resolves persons and tags, delegates file I/O to FileService, builds dynamic JPA Specifications, and integrates with audit logging.")
+    Component(fileSvc, "FileService", "Spring Service", "Wraps AWS SDK v2 S3Client. Uploads files with UUID-keyed paths, computes SHA-256 hash, downloads with content-type detection, and generates presigned URLs for OCR access.")
+    Component(massImport, "MassImportService", "Spring Service — @Async", "Reads Excel/ODS files from /import mount. Tracks import state (IDLE/RUNNING/DONE/FAILED) and delegates to ExcelService. Returns immediately; processing runs asynchronously.")
+    Component(excelSvc, "ExcelService", "Spring Service", "Parses Excel/ODS workbooks (Apache POI). Column indices configurable via application.properties. Creates/updates document records per row.")
+    Component(minioConf, "MinioConfig", "Spring @Configuration", "Creates the S3Client and S3Presigner beans with path-style access for MinIO. Validates MinIO connectivity on startup.")
+    Component(docRepo, "DocumentRepository", "Spring Data JPA", "Queries documents with Specification-based dynamic search, bidirectional conversation thread queries, full-text search with ranking and match highlighting, and transcription pipeline queue projections.")
+    Component(docSpec, "DocumentSpecifications", "JPA Criteria API", "Factory for composable predicates: hasText (full-text), hasSender, hasReceiver, isBetween (date range), hasTags (subquery AND/OR logic).")
+}
+
+Component(personSvc, "PersonService", "Spring Service", "See diagram 3e. Called by DocumentService to resolve sender / receiver persons by ID.")
+Component(tagSvc, "TagService", "Spring Service", "See diagram 3d. Called by DocumentService to find or create tags by name.")
+
+Rel(frontend, docCtrl, "Document requests", "HTTP / JSON")
+Rel(frontend, adminCtrl, "Trigger import", "HTTP / JSON")
+Rel(docCtrl, docSvc, "Delegates to")
+Rel(adminCtrl, massImport, "Triggers")
+Rel(docSvc, fileSvc, "Upload / download files")
+Rel(docSvc, docRepo, "Reads / writes documents")
+Rel(docSvc, docSpec, "Builds search predicates")
+Rel(docSvc, personSvc, "Resolves sender / receivers")
+Rel(docSvc, tagSvc, "Finds or creates tags")
+Rel(massImport, excelSvc, "Parses Excel/ODS file")
+Rel(excelSvc, docSvc, "Creates / updates documents")
+Rel(minioConf, fileSvc, "Provides S3Client and S3Presigner beans")
+Rel(fileSvc, minio, "PUT / GET / presigned URL objects", "S3 API / HTTP")
+Rel(docRepo, db, "SQL queries", "JDBC")
+
+@enduml

docs/architecture/c4/l3-backend-3c-transcription.puml

@@ -0,0 +1,41 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: API Backend — Document Transcription Pipeline
+
+Container(frontend, "Web Frontend", "SvelteKit")
+ContainerDb(db, "PostgreSQL", "PostgreSQL 16")
+
+System_Boundary(backend, "API Backend (Spring Boot)") {
+    Component(transcriptionCtrl, "TranscriptionBlockController", "Spring MVC — /api/transcription", "CRUD for transcription text blocks per document page. Manages sort order, review status, and block version history.")
+    Component(annotationCtrl, "AnnotationController", "Spring MVC — /api/documents/{id}/annotations", "CRUD for free-form page annotations with polygon coordinates, colour coding, and file-hash tracking.")
+    Component(commentCtrl, "CommentController", "Spring MVC — /api/documents/{id}/comments", "Threaded comment CRUD on transcription blocks with @mention support and notification triggers.")
+    Component(transcriptionSvc, "TranscriptionService", "Spring Service", "Creates and updates transcription blocks from annotation regions. Tracks block versions, sanitizes text with an HTML allow-list, and triggers mentions.")
+    Component(transcriptionQueueSvc, "TranscriptionQueueService", "Spring Service", "Assembles segmentation, transcription, and review queue projections by delegating to DocumentService and AuditLogQueryService.")
+    Component(annotationSvc, "AnnotationService", "Spring Service", "Manages document page annotations with polygon coordinates. Called by OcrAsyncRunner to persist OCR-generated block boundaries.")
+    Component(commentSvc, "CommentService", "Spring Service", "Creates and manages threaded comments with @mention parsing. Triggers NotificationService for REPLY and MENTION events.")
+    Component(blockRepo, "TranscriptionBlockRepository", "Spring Data JPA", "Reads and writes TranscriptionBlock and TranscriptionBlockVersion records.")
+    Component(annotationRepo, "AnnotationRepository", "Spring Data JPA", "Reads and writes DocumentAnnotation records.")
+    Component(commentRepo, "CommentRepository", "Spring Data JPA", "Reads and writes DocumentComment records.")
+}
+
+Component(documentSvc, "DocumentService", "Spring Service", "See diagram 3b. Called by TranscriptionQueueService to assemble pipeline queue projections.")
+Component(auditQuerySvc, "AuditLogQueryService", "Spring Service", "See diagram 3g. Called by TranscriptionQueueService for pipeline activity data.")
+
+Rel(frontend, transcriptionCtrl, "Transcription block requests", "HTTP / JSON")
+Rel(frontend, annotationCtrl, "Annotation requests", "HTTP / JSON")
+Rel(frontend, commentCtrl, "Comment requests", "HTTP / JSON")
+Rel(transcriptionCtrl, transcriptionSvc, "Delegates to")
+Rel(transcriptionCtrl, transcriptionQueueSvc, "Queries pipeline queues")
+Rel(annotationCtrl, annotationSvc, "Delegates to")
+Rel(commentCtrl, commentSvc, "Delegates to")
+Rel(transcriptionSvc, blockRepo, "Reads / writes blocks and versions")
+Rel(annotationSvc, annotationRepo, "Reads / writes annotations")
+Rel(commentSvc, commentRepo, "Reads / writes comments")
+Rel(transcriptionQueueSvc, documentSvc, "Queries pipeline document state")
+Rel(transcriptionQueueSvc, auditQuerySvc, "Queries pipeline activity data")
+Rel(blockRepo, db, "SQL queries", "JDBC")
+Rel(annotationRepo, db, "SQL queries", "JDBC")
+Rel(commentRepo, db, "SQL queries", "JDBC")
+
+@enduml

docs/architecture/c4/l3-backend-3d-users-groups.puml

@@ -0,0 +1,41 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: API Backend — Users, Groups & Administration
+
+Container(frontend, "Web Frontend", "SvelteKit")
+ContainerDb(db, "PostgreSQL", "PostgreSQL 16")
+
+System_Boundary(backend, "API Backend (Spring Boot)") {
+    Component(userCtrl, "UserController", "Spring MVC — /api/users", "Returns current user (/me), creates and deletes users (requires ADMIN_USER), supports user search and profile updates.")
+    Component(groupCtrl, "GroupController", "Spring MVC — /api/groups", "Lists and manages permission groups.")
+    Component(tagCtrl, "TagController", "Spring MVC — /api/tags", "Lists tags for typeahead, supports tag merge, tree structure, and subtree deletion.")
+    Component(inviteCtrl, "InviteController", "Spring MVC — /api/auth/invite", "Creates invite codes and validates them at registration time. Rate-limited via WebConfig interceptor.")
+    Component(authCtrl, "AuthController", "Spring MVC — /api/auth", "Handles user registration (POST /register) and password reset token endpoints (/forgot-password, /reset-password).")
+    Component(userSvc, "UserService", "Spring Service", "User CRUD with BCrypt password encoding, group assignment, and audit logging. Orchestrates invite-based registration and password reset tokens.")
+    Component(tagSvc, "TagService", "Spring Service", "Tag CRUD with name search, hierarchical tree structure, merge/reparent operations, and recursive subtree deletion.")
+    Component(dataInit, "DataInitializer", "CommandLineRunner", "On startup: creates default admin user and groups if none exist. Seeds test data if DB is empty.")
+    Component(userRepo, "AppUserRepository", "Spring Data JPA", "Finds users by email. Supports search by email or display name.")
+    Component(groupRepo, "UserGroupRepository", "Spring Data JPA", "Manages permission groups.")
+    Component(tagRepo, "TagRepository", "Spring Data JPA", "Finds or creates tags by name (case-insensitive). Supports recursive ancestor/descendant CTE queries and merge/reparent helpers.")
+}
+
+Rel(frontend, userCtrl, "User requests", "HTTP / JSON")
+Rel(frontend, groupCtrl, "Group requests", "HTTP / JSON")
+Rel(frontend, tagCtrl, "Tag requests", "HTTP / JSON")
+Rel(frontend, inviteCtrl, "Invite validation", "HTTP / JSON")
+Rel(frontend, authCtrl, "Registration and password reset", "HTTP / JSON")
+Rel(userCtrl, userSvc, "Delegates to")
+Rel(groupCtrl, userSvc, "Delegates to")
+Rel(tagCtrl, tagSvc, "Delegates to")
+Rel(tagSvc, tagRepo, "Reads / writes tags")
+Rel(inviteCtrl, userSvc, "Creates and validates invites")
+Rel(authCtrl, userSvc, "Registers users, resets passwords")
+Rel(userSvc, userRepo, "Reads / writes users")
+Rel(userSvc, groupRepo, "Assigns groups")
+Rel(dataInit, db, "Seeds initial data", "JDBC")
+Rel(userRepo, db, "SQL queries", "JDBC")
+Rel(groupRepo, db, "SQL queries", "JDBC")
+Rel(tagRepo, db, "SQL queries", "JDBC")
+
+@enduml

docs/architecture/c4/l3-backend-3e-persons.puml

@@ -0,0 +1,30 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: API Backend — Persons & Family Graph
+
+Container(frontend, "Web Frontend", "SvelteKit")
+ContainerDb(db, "PostgreSQL", "PostgreSQL 16")
+
+System_Boundary(backend, "API Backend (Spring Boot)") {
+    Component(personCtrl, "PersonController", "Spring MVC — /api/persons", "Lists and searches family members. Returns documents sent by or received by a person, correspondent suggestions, and person summary with document counts.")
+    Component(relCtrl, "RelationshipController", "Spring MVC — /api/network, /api/persons/{id}/relationships", "CRUD for explicit person relationships and the full family network graph (nodes + edges) used by the Stammbaum view.")
+    Component(personSvc, "PersonService", "Spring Service", "Person CRUD, alias management, and merge operations (reassigns all document sender/receiver references before deleting duplicate persons).")
+    Component(relSvc, "RelationshipService", "Spring Service", "Manages explicit directional family relationships (PARENT_OF, SPOUSE_OF, SIBLING_OF, etc.) with optional date ranges and notes.")
+    Component(relInference, "RelationshipInferenceService", "Spring Service", "Computes transitive family relationships from explicit edges to infer grandparent/grandchild, aunt/uncle, and other extended-family links for the network graph.")
+    Component(personRepo, "PersonRepository", "Spring Data JPA", "Queries persons with name search (including aliases), correspondent discovery, person summaries with document counts, and merge/reassignment helpers.")
+    Component(relRepo, "PersonRelationshipRepository", "Spring Data JPA", "Reads and writes PersonRelationship records. Supports lookup by person ID, by relation type, and existence checks for deduplication.")
+}
+
+Rel(frontend, personCtrl, "Person requests", "HTTP / JSON")
+Rel(frontend, relCtrl, "Relationship and graph requests", "HTTP / JSON")
+Rel(personCtrl, personSvc, "Delegates to")
+Rel(relCtrl, relSvc, "Delegates to")
+Rel(relCtrl, relInference, "Queries inferred graph")
+Rel(personSvc, personRepo, "Reads / writes persons")
+Rel(relSvc, relRepo, "Reads / writes relationships")
+Rel(relInference, relRepo, "Reads relationships for inference")
+Rel(personRepo, db, "SQL queries", "JDBC")
+Rel(relRepo, db, "SQL queries", "JDBC")
+
+@enduml

docs/architecture/c4/l3-backend-3f-ocr.puml

@@ -0,0 +1,41 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: API Backend — OCR Orchestration
+
+Container(frontend, "Web Frontend", "SvelteKit")
+ContainerDb(db, "PostgreSQL", "PostgreSQL 16")
+ContainerDb(minio, "Object Storage", "MinIO (S3-compatible)")
+Container(ocrPy, "OCR Service", "Python FastAPI")
+
+System_Boundary(backend, "API Backend (Spring Boot)") {
+    Component(ocrCtrl, "OcrController", "Spring MVC — /api/ocr", "REST entry point: trigger single or batch OCR jobs, stream progress via SSE, query job status, and manage training runs and per-sender models.")
+    Component(ocrSvc, "OcrService", "Spring Service", "Creates OcrJob and OcrJobDocument records, checks Python service health, and delegates async execution to OcrAsyncRunner.")
+    Component(ocrBatch, "OcrBatchService", "Spring Service", "Orchestrates multi-document OCR jobs, iterating documents and delegating each to OcrAsyncRunner.")
+    Component(ocrAsync, "OcrAsyncRunner", "Spring Component — @Async", "Async worker that streams OCR results from Python page by page, persists transcription blocks and annotations via domain services, and emits progress via SSE.")
+    Component(ocrClient, "RestClientOcrClient", "Spring Component", "HTTP client wrapping the Python service: POST /ocr/stream (NDJSON), /train, /segtrain, and /train-sender. Falls back from streaming to batch on 404.")
+    Component(ocrTraining, "OcrTrainingService", "Spring Service", "Orchestrates model training: exports training data as ZIP, calls Python /train or /segtrain, persists training metrics in OcrTrainingRunRepository.")
+    Component(ocrJobRepo, "OcrJobRepository, OcrJobDocumentRepository", "Spring Data JPA", "Reads and writes OcrJob and OcrJobDocument records. Tracks job status (RUNNING/DONE/FAILED), per-document progress, page counts, and error messages.")
+}
+
+Component(transcriptionSvc, "TranscriptionService", "Spring Service", "See diagram 3c. Called by OcrAsyncRunner to persist transcription blocks per page.")
+Component(annotationSvc, "AnnotationService", "Spring Service", "See diagram 3c. Called by OcrAsyncRunner to persist OCR-generated annotation regions per page.")
+
+Rel(frontend, ocrCtrl, "OCR trigger, status, and progress requests", "HTTP / JSON / SSE")
+Rel(ocrCtrl, ocrSvc, "Single-document jobs")
+Rel(ocrCtrl, ocrBatch, "Batch jobs")
+Rel(ocrCtrl, ocrTraining, "Training runs")
+Rel(ocrSvc, ocrAsync, "Delegates async execution")
+Rel(ocrBatch, ocrAsync, "Delegates async execution")
+Rel(ocrAsync, ocrClient, "Streams OCR results page by page", "HTTP / NDJSON")
+Rel(ocrTraining, ocrClient, "Sends training data ZIP", "HTTP / multipart")
+Rel(ocrClient, ocrPy, "POST /ocr/stream, /train, /segtrain, /train-sender", "HTTP / REST")
+Rel(ocrAsync, transcriptionSvc, "Saves transcription blocks per page")
+Rel(ocrAsync, annotationSvc, "Saves annotation regions per page")
+Rel(ocrAsync, ocrJobRepo, "Reads / writes OCR job state")
+Rel(ocrJobRepo, db, "SQL queries", "JDBC")
+Rel(ocrAsync, minio, "Generates presigned URLs for PDF fetch", "S3 API")
+Rel(ocrPy, minio, "Fetches PDF via presigned URL", "HTTP / S3 presigned")
+Rel(ocrTraining, db, "Persists training run metrics", "JDBC")
+
+@enduml

docs/architecture/c4/l3-backend-3g-supporting.puml

@@ -0,0 +1,46 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: API Backend — Supporting Domains
+
+Container(frontend, "Web Frontend", "SvelteKit")
+ContainerDb(db, "PostgreSQL", "PostgreSQL 16")
+
+System_Boundary(backend, "API Backend (Spring Boot)") {
+    Component(auditSvc, "AuditService", "Spring Service — @Async", "Writes audit log entries asynchronously via a dedicated TaskExecutor, with transaction-aware logging to prevent deadlocks on concurrent saves.")
+    Component(auditQuery, "AuditLogQueryService", "Spring Service", "Queries audit logs for activity feeds, pulse stats, recent contributors, and per-document history. Facade over AuditLogRepository.")
+    Component(dashCtrl, "DashboardController", "Spring MVC — /api/dashboard", "REST endpoints for the user dashboard: recent document resume (/resume), weekly transcription pulse stats (/pulse), and activity feed (/activity) with kind filtering and pagination.")
+    Component(statsCtrl, "StatsController", "Spring MVC — /api/stats", "Returns aggregate counts (total persons, total documents) for the UI stats bar.")
+    Component(statsSvc, "StatsService", "Spring Service", "Queries aggregate counts: total persons and total documents.")
+    Component(dashSvc, "DashboardService", "Spring Service", "Assembles the user dashboard: recent document resume (calls DocumentService + TranscriptionService), weekly transcription pulse stats, and activity feed with contributor avatars.")
+    Component(notifCtrl, "NotificationController", "Spring MVC — /api/notifications", "REST and SSE endpoints for notification stream, history with filtering, read/unread state, and per-user preference management.")
+    Component(notifSvc, "NotificationService", "Spring Service", "Creates REPLY and MENTION notifications, optionally sends email, marks as read, and pushes events to connected clients via SseEmitterRegistry.")
+    Component(sseRegistry, "SseEmitterRegistry", "Spring Component", "In-memory ConcurrentHashMap of Spring SseEmitter instances per user. Handles registration, deregistration, and JSON event broadcasts.")
+    Component(geschCtrl, "GeschichteController", "Spring MVC — /api/geschichten", "CRUD for publishable stories that link persons and documents. Requires BLOG_WRITE permission for write operations.")
+    Component(geschSvc, "GeschichteService", "Spring Service", "Manages story lifecycle (DRAFT → PUBLISHED with timestamp). Sanitizes HTML body with an allowlist policy.")
+    Component(exHandler, "GlobalExceptionHandler", "Spring @RestControllerAdvice", "Converts DomainException, validation errors, and generic exceptions to ErrorResponse JSON with machine-readable ErrorCode and HTTP status.")
+}
+
+Component(documentSvc, "DocumentService", "Spring Service", "See diagram 3b. Called by DashboardService to fetch document titles and resume data.")
+Component(transcriptionSvc, "TranscriptionService", "Spring Service", "See diagram 3c. Called by DashboardService to fetch transcription block progress for resume.")
+
+Rel(frontend, dashCtrl, "Dashboard requests", "HTTP / JSON")
+Rel(frontend, statsCtrl, "GET /api/stats", "HTTP / JSON")
+Rel(frontend, notifCtrl, "Notification stream and history", "HTTP / JSON / SSE")
+Rel(frontend, geschCtrl, "Story requests", "HTTP / JSON")
+Rel(dashCtrl, dashSvc, "Delegates to")
+Rel(statsCtrl, statsSvc, "Delegates to")
+Rel(statsSvc, db, "Reads aggregate counts", "JDBC")
+Rel(dashSvc, auditQuery, "Fetches activity feed and pulse stats")
+Rel(dashSvc, documentSvc, "Fetches document titles and resume data")
+Rel(dashSvc, transcriptionSvc, "Fetches transcription block progress for resume")
+Rel(notifCtrl, notifSvc, "Delegates to")
+Rel(notifCtrl, sseRegistry, "Registers client SSE connection")
+Rel(notifSvc, sseRegistry, "Broadcasts events to connected clients")
+Rel(geschCtrl, geschSvc, "Delegates to")
+Rel(auditSvc, db, "Writes audit_log", "JDBC")
+Rel(auditQuery, db, "Reads audit_log", "JDBC")
+Rel(notifSvc, db, "Reads / writes notifications", "JDBC")
+Rel(geschSvc, db, "Reads / writes geschichten", "JDBC")
+
+@enduml

docs/architecture/c4/l3-frontend-3a-middleware-auth.puml

@@ -0,0 +1,29 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: Web Frontend — Middleware, Auth & Layout
+
+Person(user, "User")
+Container(backend, "API Backend", "Spring Boot")
+
+System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") {
+    Component(hooks, "hooks.server.ts", "SvelteKit Server Hook", "Four handle layers: (1) handleAuth — redirects unauthenticated users to /login; (2) userGroup — reads auth_token cookie, fetches /api/users/me, stores user in event.locals; (3) handleFetch — injects Authorization header on all outgoing /api/ calls; (4) handleLocaleDetection — sets language cookie from Accept-Language header.")
+    Component(i18n, "hooks.ts (Paraglide)", "SvelteKit Client Hook", "Client-side i18n middleware. Detects language from URL and sets the active locale for Paraglide.js translation functions.")
+    Component(layout, "+layout.server.ts", "SvelteKit Layout Loader", "Passes event.locals.user down to all child pages so every route has access to the authenticated user.")
+    Component(loginPage, "/login", "SvelteKit Route", "Form action: encodes email:password as Base64 Basic Auth token, POSTs to /api/users/me to validate, sets auth_token httpOnly cookie (SameSite=strict, maxAge=86400), redirects to /.")
+    Component(logoutPage, "/logout", "SvelteKit Route (server-only)", "Clears the auth_token cookie and redirects to /login.")
+    Component(registerPage, "/register", "SvelteKit Route", "Loader validates invite code via GET /api/auth/invite/{code}. Form action: POST /api/auth/register to create the user account.")
+    Component(forgotPw, "/forgot-password", "SvelteKit Route", "Form action: POST /api/auth/forgot-password. Always responds with success to prevent email enumeration.")
+    Component(resetPw, "/reset-password", "SvelteKit Route", "Form action: POST /api/auth/reset-password with the token from the query string.")
+}
+
+Rel(user, hooks, "Every browser request", "HTTPS")
+Rel(hooks, backend, "GET /api/users/me (session check)", "HTTP / Basic Auth")
+Rel(hooks, loginPage, "Redirect if no token")
+Rel(hooks, layout, "Stores authenticated user in event.locals")
+Rel(loginPage, backend, "POST /api/users/me (auth check)", "HTTP / Basic Auth")
+Rel(registerPage, backend, "GET /api/auth/invite/{code}, POST /api/auth/register", "HTTP / JSON")
+Rel(forgotPw, backend, "POST /api/auth/forgot-password", "HTTP / JSON")
+Rel(resetPw, backend, "POST /api/auth/reset-password", "HTTP / JSON")
+
+@enduml

docs/architecture/c4/l3-frontend-3b-document-workflows.puml

@@ -0,0 +1,43 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: Web Frontend — Document Workflows
+
+Person(user, "User")
+Container(backend, "API Backend", "Spring Boot")
+
+System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") {
+    Component(homePage, "/ (Home / Search)", "SvelteKit Route", "Loader: parses URL params (q, from, to, senderId, receiverId, tags), fetches /api/documents/search and /api/persons. Renders search form with full-text, date range, sender/receiver typeahead, and tag filters.")
+    Component(docsListPageTs, "/documents/+page.ts", "SvelteKit Client Loader", "Client-side load gated by matchMedia('(min-width: 1024px)') and ?view query. Fetches /api/documents/density only on desktop (Tailwind lg breakpoint) and outside calendar view; degrades to empty buckets on network failure.")
+    Component(timelineFilter, "TimelineDensityFilter.svelte", "Svelte Component", "Per-month density bars above the document list. Click selects a single month, emits onchange({from, to}) using YYYY-MM-DD boundaries. Hidden on mobile and tablet (below lg, 1024px) and in calendar view.")
+    Component(docDetail, "/documents/[id]", "SvelteKit Route", "Loader: GET /api/documents/{id}. Page: metadata panel, inline file viewer, transcription editor, annotation layer, and comment thread.")
+    Component(docEdit, "/documents/[id]/edit", "SvelteKit Route", "Edit form with PersonTypeahead, TagInput, date/location fields. Form action: PUT /api/documents/{id}.")
+    Component(docNew, "/documents/new", "SvelteKit Route", "Upload form for a new document. Loader: GET /api/persons. Form action: POST /api/documents with multipart file.")
+    Component(docBulkEdit, "/documents/bulk-edit", "SvelteKit Route", "Multi-document metadata editor. Loader: GET /api/documents/incomplete. Requires WRITE_ALL (redirects otherwise). Action: PATCH /api/documents/bulk.")
+    Component(enrichPage, "/enrich/[id]", "SvelteKit Route", "Guided enrichment workflow. Loader: GET /api/documents/{id}. Progressively saves annotations and transcription blocks.")
+    Component(apiPersons, "/api/persons (SvelteKit API)", "SvelteKit Server Route", "Proxies GET /api/persons?q=... to backend for PersonTypeahead suggestions.")
+    Component(apiTags, "/api/tags (SvelteKit API)", "SvelteKit Server Route", "Proxies GET /api/tags to backend for TagInput autocomplete.")
+    Component(typeahead, "PersonTypeahead.svelte", "Svelte Component", "Async autocomplete for selecting a person. Debounces input, calls /api/persons?q=.")
+    Component(tagInput, "TagInput.svelte", "Svelte Component", "Multi-tag input. Supports free-text entry and selecting existing tags from /api/tags.")
+}
+
+Rel(user, homePage, "Searches and browses", "HTTPS / Browser")
+Rel(homePage, backend, "GET /api/documents/search, GET /api/persons", "HTTP / JSON")
+Rel(docsListPageTs, backend, "GET /api/documents/density (desktop only, ≥1024px)", "HTTP / JSON")
+Rel(homePage, timelineFilter, "Mounts above the result list")
+Rel(docsListPageTs, timelineFilter, "Provides density / minDate / maxDate props")
+Rel(docDetail, backend, "GET /api/documents/{id}, GET /api/documents/{id}/file", "HTTP / JSON + Binary")
+Rel(docEdit, backend, "PUT /api/documents/{id}", "HTTP / Multipart")
+Rel(docNew, backend, "GET /api/persons, POST /api/documents", "HTTP / JSON + Multipart")
+Rel(docBulkEdit, backend, "GET /api/documents/incomplete, PATCH /api/documents/bulk", "HTTP / JSON")
+Rel(enrichPage, backend, "GET/POST /api/transcription, POST /api/documents/{id}/annotations", "HTTP / JSON")
+Rel(homePage, typeahead, "Uses for sender/receiver filter")
+Rel(docEdit, typeahead, "Uses for sender/receiver selection")
+Rel(docNew, typeahead, "Uses for sender selection")
+Rel(docEdit, tagInput, "Uses for tag management")
+Rel(typeahead, apiPersons, "Fetches suggestions", "HTTP")
+Rel(tagInput, apiTags, "Fetches existing tags", "HTTP")
+Rel(apiPersons, backend, "GET /api/persons", "HTTP / JSON")
+Rel(apiTags, backend, "GET /api/tags", "HTTP / JSON")
+
+@enduml

docs/architecture/c4/l3-frontend-3c-people-stories.puml

@@ -0,0 +1,32 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: Web Frontend — People, Stories & Discovery
+
+Person(user, "User")
+Container(backend, "API Backend", "Spring Boot")
+
+System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") {
+    Component(personsPage, "/persons and /persons/[id]", "SvelteKit Routes", "Person directory and detail. Detail: metadata, document list sent/received, correspondents, explicit and inferred family relationships.")
+    Component(personEdit, "/persons/[id]/edit and /persons/new", "SvelteKit Routes", "Create and edit person forms. Edit: metadata, aliases, explicit relationships. Actions: PUT/POST /api/persons.")
+    Component(briefwechsel, "/briefwechsel", "SvelteKit Route", "Bilateral conversation timeline. Selects two persons via PersonTypeahead, fetches GET /api/documents/conversation, displays chronological exchange.")
+    Component(aktivitaeten, "/aktivitaeten", "SvelteKit Route", "Unified activity feed (Chronik). Loader: GET /api/dashboard/activity and GET /api/notifications?read=false.")
+    Component(geschichten, "/geschichten and /geschichten/[id]", "SvelteKit Routes", "Story list and detail pages. Loader: GET /api/geschichten?status=PUBLISHED.")
+    Component(geschichtenEdit, "/geschichten/[id]/edit and /geschichten/new", "SvelteKit Routes", "Story editor with rich text, person and document linking. Actions: PUT/POST /api/geschichten. Requires BLOG_WRITE permission.")
+    Component(stammbaum, "/stammbaum", "SvelteKit Route", "Family tree visualisation. Loader: GET /api/network (nodes + edges). Renders interactive family tree from network graph data.")
+    Component(profilePage, "/profile", "SvelteKit Route", "Current user profile settings. Loader: GET /api/users/me/notification-preferences. Actions: update name/password and notification preferences.")
+    Component(userProfile, "/users/[id]", "SvelteKit Route", "Public user profile view. Loader: GET /api/users/{id}.")
+}
+
+Rel(user, personsPage, "Browses family members", "HTTPS / Browser")
+Rel(personsPage, backend, "GET /api/persons, GET /api/persons/{id}", "HTTP / JSON")
+Rel(personEdit, backend, "GET /api/persons/{id}, PUT /api/persons/{id}, POST /api/persons", "HTTP / JSON")
+Rel(briefwechsel, backend, "GET /api/documents/conversation", "HTTP / JSON")
+Rel(aktivitaeten, backend, "GET /api/dashboard/activity, GET /api/notifications", "HTTP / JSON")
+Rel(geschichten, backend, "GET /api/geschichten", "HTTP / JSON")
+Rel(geschichtenEdit, backend, "GET/PUT/POST /api/geschichten", "HTTP / JSON")
+Rel(stammbaum, backend, "GET /api/network", "HTTP / JSON")
+Rel(profilePage, backend, "GET/PUT /api/users/me, notification-preferences", "HTTP / JSON")
+Rel(userProfile, backend, "GET /api/users/{id}", "HTTP / JSON")
+
+@enduml

docs/architecture/c4/l3-frontend-3d-administration.puml

@@ -0,0 +1,27 @@
+@startuml
+!include <C4/C4_Component>
+
+title Component Diagram: Web Frontend — Administration & Help
+
+Person(admin, "Administrator")
+Person(user, "User")
+Container(backend, "API Backend", "Spring Boot")
+
+System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") {
+    Component(adminUsers, "/admin/users, /admin/users/[id], /admin/users/new, /admin/invites", "SvelteKit Routes", "User directory, create/update/delete users, and manage invite codes. Requires ADMIN_USER permission.")
+    Component(adminGroups, "/admin/groups, /admin/groups/[id], /admin/groups/new", "SvelteKit Routes", "Permission group management: create/edit groups and their permission sets.")
+    Component(adminTags, "/admin/tags and /admin/tags/[id]", "SvelteKit Routes", "Tag administration: edit tag hierarchy, merge tags, delete subtrees.")
+    Component(adminOcr, "/admin/ocr and /admin/ocr/[personId]", "SvelteKit Routes", "Global and per-person OCR configuration. Manages script types and triggers sender model training.")
+    Component(adminSystem, "/admin/system", "SvelteKit Route", "System status panel. Triggers Excel/ODS mass import (POST /api/admin/trigger-import). Displays import state.")
+    Component(hilfe, "/hilfe/transkription", "SvelteKit Route", "Static transcription style guide for Kurrent and Sütterlin character recognition. No backend calls.")
+}
+
+Rel(admin, adminUsers, "Manages users and invites", "HTTPS / Browser")
+Rel(user, hilfe, "Views transcription style guide", "HTTPS / Browser")
+Rel(adminUsers, backend, "GET/POST/DELETE /api/users, POST /api/auth/invite", "HTTP / JSON")
+Rel(adminGroups, backend, "GET/POST/PUT/DELETE /api/groups", "HTTP / JSON")
+Rel(adminTags, backend, "GET/PUT/DELETE /api/tags", "HTTP / JSON")
+Rel(adminOcr, backend, "GET/POST /api/ocr (global config and sender training)", "HTTP / JSON")
+Rel(adminSystem, backend, "POST /api/admin/trigger-import, GET /api/admin/import-status", "HTTP / JSON")
+
+@enduml

docs/architecture/c4/seq-auth-flow.puml

@@ -0,0 +1,49 @@
+@startuml
+title Authentication Flow (behind Caddy reverse proxy)
+
+actor User
+participant Browser
+participant "Caddy (TLS termination)" as Caddy
+participant "Frontend (SvelteKit)" as Frontend
+participant "Backend (Spring Boot)" as Backend
+participant PostgreSQL as DB
+
+User -> Browser: Enter email + password
+Browser -> Caddy: HTTPS POST /login (form action)
+note right of Caddy
+  Caddy terminates TLS and forwards
+  to Frontend over HTTP with:
+    X-Forwarded-Proto: https
+    X-Forwarded-For: <client IP>
+    X-Forwarded-Host: archiv.raddatz.cloud
+end note
+Caddy -> Frontend: HTTP POST /login\n+ X-Forwarded-Proto: https
+Frontend -> Frontend: Base64 encode "email:password"
+Frontend -> Backend: GET /api/users/me\nAuthorization: Basic <token>\n+ X-Forwarded-Proto: https
+note right of Backend
+  server.forward-headers-strategy: native
+  Jetty's ForwardedRequestCustomizer
+  reads X-Forwarded-Proto so
+  request.getScheme() returns "https".
+end note
+Backend -> Backend: Spring Security parses Basic Auth
+Backend -> DB: SELECT user WHERE email=?
+DB --> Backend: AppUser + groups + permissions
+Backend -> Backend: BCrypt.matches(password, hash)
+Backend --> Frontend: 200 OK — UserDTO
+Frontend -> Caddy: Set-Cookie: auth_token=<base64>\n(httpOnly, **Secure**, SameSite=strict, maxAge=86400)
+note right of Frontend
+  Secure flag is set because the
+  request scheme observed by the
+  app is https (forwarded by Caddy).
+end note
+Caddy -> Browser: HTTPS 200 + Set-Cookie
+Browser -> Caddy: HTTPS GET / (next request)
+Caddy -> Frontend: HTTP GET / + X-Forwarded-Proto: https
+Frontend -> Frontend: hooks.server.ts reads auth_token cookie
+Frontend -> Backend: GET /api/users/me\nAuthorization: Basic <token>
+Backend --> Frontend: 200 OK — user in event.locals
+Frontend --> Caddy: rendered page
+Caddy --> Browser: HTTPS 200
+
+@enduml

docs/architecture/c4/seq-document-upload.puml

@@ -0,0 +1,32 @@
+@startuml
+title Document Upload Flow
+
+actor User
+participant "Frontend (SvelteKit)" as Frontend
+participant "Backend (Spring Boot)" as Backend
+participant "PermissionAspect (AOP)" as Aspect
+participant DocumentService as DocSvc
+participant FileService as FileSvc
+participant MinIO
+participant PostgreSQL as DB
+
+User -> Frontend: Submit edit form (file + metadata)
+Frontend -> Backend: PUT /api/documents/{id}\nmultipart/form-data + Authorization header
+Backend -> Aspect: @RequirePermission(WRITE_ALL) check
+Aspect -> Aspect: Verify user has WRITE_ALL authority
+Aspect --> Backend: Proceed
+Backend -> DocSvc: updateDocument(id, dto, file)
+DocSvc -> DocSvc: Resolve sender Person by ID
+DocSvc -> DocSvc: Resolve/create Tags
+DocSvc -> FileSvc: uploadFile(file, filename)
+FileSvc -> FileSvc: Generate key: documents/{UUID}_{filename}
+FileSvc -> MinIO: PutObject(bucket, key, stream)
+MinIO --> FileSvc: Success
+FileSvc --> DocSvc: S3 key
+DocSvc -> DB: UPDATE documents SET file_path=?, status='UPLOADED', ...
+DB --> DocSvc: OK
+DocSvc --> Backend: Updated Document entity
+Backend --> Frontend: 200 OK — Document JSON
+Frontend --> User: Refreshed document view
+
+@enduml

docs/architecture/db/db-orm.puml

@@ -0,0 +1,432 @@
+@startuml db-orm
+' Schema source: Flyway V1–V60 (excl. V37, V43 — intentionally removed)
+' Schema as of:  V60 (2026-05-06)
+' ⚠ This is a versioned snapshot. Update when the schema changes significantly.
+
+hide circle
+skinparam linetype ortho
+
+' ── Auth ──
+package "Auth" {
+
+  entity app_users {
+    id : UUID <<PK>>
+    --
+    email : VARCHAR(255) NOT NULL UNIQUE
+    password : VARCHAR(255) NOT NULL
+    first_name : VARCHAR(100)
+    last_name : VARCHAR(100)
+    birth_date : DATE
+    contact : TEXT
+    enabled : BOOLEAN NOT NULL
+    color : VARCHAR(20) NOT NULL
+    notify_on_reply : BOOLEAN NOT NULL
+    notify_on_mention : BOOLEAN NOT NULL
+    created_at : TIMESTAMP
+  }
+
+  entity user_groups {
+    id : UUID <<PK>>
+    --
+    name : VARCHAR(255) NOT NULL UNIQUE
+  }
+
+  entity app_users_groups {
+    app_user_id : UUID <<FK>>
+    group_id : UUID <<FK>>
+  }
+
+  entity group_permissions {
+    group_id : UUID <<FK>>
+    --
+    permission : VARCHAR(255)
+  }
+
+  entity password_reset_tokens {
+    id : UUID <<PK>>
+    --
+    app_user_id : UUID <<FK>>
+    token : VARCHAR(64) NOT NULL UNIQUE
+    expires_at : TIMESTAMP NOT NULL
+    used : BOOLEAN NOT NULL
+    created_at : TIMESTAMP NOT NULL
+  }
+
+  entity invite_tokens {
+    id : UUID <<PK>>
+    --
+    code : VARCHAR(10) NOT NULL UNIQUE
+    label : VARCHAR(255)
+    max_uses : INTEGER
+    use_count : INTEGER NOT NULL
+    prefill_first_name : VARCHAR(255)
+    prefill_last_name : VARCHAR(255)
+    prefill_email : VARCHAR(255)
+    expires_at : TIMESTAMP
+    created_by : UUID <<FK>>
+    created_at : TIMESTAMP NOT NULL
+    revoked : BOOLEAN NOT NULL
+  }
+
+  entity invite_token_group_ids {
+    invite_token_id : UUID <<FK>>
+    group_id : UUID <<FK>>
+  }
+}
+
+' ── Documents ──
+package "Documents" {
+
+  entity documents {
+    id : UUID <<PK>>
+    --
+    title : VARCHAR(255) NOT NULL
+    original_filename : VARCHAR(255) NOT NULL
+    status : VARCHAR(255) NOT NULL
+    file_path : VARCHAR(255)
+    file_hash : VARCHAR(64)
+    summary : TEXT
+    transcription : TEXT
+    meta_date : DATE
+    meta_location : VARCHAR(255)
+    meta_document_location : VARCHAR(255)
+    archive_box : VARCHAR(255)
+    archive_folder : VARCHAR(255)
+    sender_id : UUID <<FK>>
+    metadata_complete : BOOLEAN NOT NULL
+    script_type : VARCHAR(30) NOT NULL
+    thumbnail_key : VARCHAR(255)
+    thumbnail_generated_at : TIMESTAMP
+    thumbnail_aspect : VARCHAR(16)
+    page_count : INTEGER
+    search_vector : tsvector <<computed>>
+    created_at : TIMESTAMP
+    updated_at : TIMESTAMP
+  }
+
+  entity document_receivers {
+    document_id : UUID <<FK>>
+    person_id : UUID <<FK>>
+  }
+
+  entity document_tags {
+    document_id : UUID <<FK>>
+    tag_id : UUID <<FK>>
+  }
+
+  entity document_versions {
+    id : UUID <<PK>>
+    --
+    document_id : UUID <<FK>>
+    editor_id : UUID <<FK>>
+    editor_name : VARCHAR(200) NOT NULL
+    saved_at : TIMESTAMP NOT NULL
+    snapshot : JSONB NOT NULL
+    changed_fields : JSONB NOT NULL
+  }
+
+  entity document_annotations {
+    id : UUID <<PK>>
+    --
+    document_id : UUID <<FK>>
+    page_number : INTEGER NOT NULL
+    x : DOUBLE PRECISION NOT NULL
+    y : DOUBLE PRECISION NOT NULL
+    width : DOUBLE PRECISION NOT NULL
+    height : DOUBLE PRECISION NOT NULL
+    color : VARCHAR(20) NOT NULL
+    polygon : JSONB
+    file_hash : VARCHAR(64)
+    created_by : UUID <<FK>>
+    created_at : TIMESTAMP NOT NULL
+  }
+
+  entity document_comments {
+    id : UUID <<PK>>
+    --
+    document_id : UUID <<FK>>
+    annotation_id : UUID <<FK>>
+    block_id : UUID <<FK>>
+    parent_id : UUID <<FK>>
+    author_id : UUID <<FK>>
+    author_name : VARCHAR(200) NOT NULL
+    content : TEXT NOT NULL
+    created_at : TIMESTAMP NOT NULL
+    updated_at : TIMESTAMP NOT NULL
+  }
+
+  entity document_training_labels {
+    document_id : UUID <<FK>>
+    --
+    label : VARCHAR(50) NOT NULL
+  }
+
+  entity comment_mentions {
+    comment_id : UUID <<FK>>
+    app_user_id : UUID <<FK>>
+  }
+}
+
+' ── Persons ──
+package "Persons" {
+
+  entity persons {
+    id : UUID <<PK>>
+    --
+    first_name : VARCHAR(255)
+    last_name : VARCHAR(255) NOT NULL
+    alias : VARCHAR(255)
+    title : VARCHAR(50)
+    person_type : VARCHAR(20) NOT NULL
+    notes : TEXT
+    birth_year : INTEGER
+    death_year : INTEGER
+    family_member : BOOLEAN NOT NULL
+  }
+
+  entity person_name_aliases {
+    id : UUID <<PK>>
+    --
+    person_id : UUID <<FK>>
+    last_name : VARCHAR(255) NOT NULL
+    first_name : VARCHAR(255)
+    type : VARCHAR(50) NOT NULL
+    sort_order : INTEGER NOT NULL
+    created_at : TIMESTAMPTZ
+  }
+
+  entity person_relationships {
+    id : UUID <<PK>>
+    --
+    person_id : UUID <<FK>>
+    related_person_id : UUID <<FK>>
+    relation_type : VARCHAR(30) NOT NULL
+    from_year : INTEGER
+    to_year : INTEGER
+    notes : VARCHAR(2000)
+    created_at : TIMESTAMPTZ NOT NULL
+  }
+}
+
+' ── Tags ──
+package "Tags" {
+
+  entity tag {
+    id : UUID <<PK>>
+    --
+    name : VARCHAR(255) NOT NULL UNIQUE
+    parent_id : UUID <<FK>>
+    color : VARCHAR(20)
+  }
+}
+
+' ── Transcription ──
+package "Transcription" {
+
+  entity transcription_blocks {
+    id : UUID <<PK>>
+    --
+    annotation_id : UUID <<FK>>
+    document_id : UUID <<FK>>
+    text : TEXT
+    label : VARCHAR(200)
+    sort_order : INTEGER NOT NULL
+    version : INTEGER NOT NULL
+    source : VARCHAR(10) NOT NULL
+    reviewed : BOOLEAN NOT NULL
+    created_by : UUID <<FK>>
+    updated_by : UUID <<FK>>
+    created_at : TIMESTAMP NOT NULL
+    updated_at : TIMESTAMP NOT NULL
+  }
+
+  entity transcription_block_versions {
+    id : UUID <<PK>>
+    --
+    block_id : UUID <<FK>>
+    text : TEXT NOT NULL
+    changed_by : UUID <<FK>>
+    changed_at : TIMESTAMP NOT NULL
+  }
+
+  entity transcription_block_mentioned_persons {
+    block_id : UUID <<FK>>
+    person_id : UUID NOT NULL
+    --
+    display_name : VARCHAR(200) NOT NULL
+  }
+}
+
+' ── OCR ──
+package "OCR" {
+
+  entity ocr_jobs {
+    id : UUID <<PK>>
+    --
+    status : VARCHAR(20) NOT NULL
+    total_documents : INT NOT NULL
+    processed_documents : INT NOT NULL
+    error_count : INT NOT NULL
+    skipped_count : INT NOT NULL
+    created_by : UUID
+    progress_message : TEXT
+    created_at : TIMESTAMPTZ NOT NULL
+    updated_at : TIMESTAMPTZ NOT NULL
+  }
+
+  entity ocr_job_documents {
+    id : UUID <<PK>>
+    --
+    job_id : UUID <<FK>>
+    document_id : UUID <<FK>>
+    status : VARCHAR(20) NOT NULL
+    error_message : TEXT
+    current_page : INT
+    total_pages : INT
+    created_at : TIMESTAMPTZ NOT NULL
+    updated_at : TIMESTAMPTZ NOT NULL
+  }
+
+  entity ocr_training_runs {
+    id : UUID <<PK>>
+    --
+    status : VARCHAR(20) NOT NULL
+    block_count : INT NOT NULL
+    document_count : INT NOT NULL
+    model_name : VARCHAR(100) NOT NULL
+    error_message : TEXT
+    triggered_by : UUID <<FK>>
+    person_id : UUID <<FK>>
+    cer : DOUBLE PRECISION
+    loss : DOUBLE PRECISION
+    accuracy : DOUBLE PRECISION
+    epochs : INT
+    created_at : TIMESTAMPTZ NOT NULL
+    completed_at : TIMESTAMPTZ
+  }
+
+  entity sender_models {
+    id : UUID <<PK>>
+    --
+    person_id : UUID <<FK>> UNIQUE
+    model_path : TEXT NOT NULL
+    accuracy : DOUBLE PRECISION
+    cer : DOUBLE PRECISION
+    corrected_lines_at_training : INT NOT NULL
+    created_at : TIMESTAMPTZ NOT NULL
+    updated_at : TIMESTAMPTZ NOT NULL
+  }
+}
+
+' ── Supporting ──
+package "Supporting" {
+
+  entity notifications {
+    id : UUID <<PK>>
+    --
+    recipient_id : UUID <<FK>>
+    type : VARCHAR(32) NOT NULL
+    document_id : UUID
+    reference_id : UUID
+    annotation_id : UUID
+    actor_name : VARCHAR(255)
+    read : BOOLEAN NOT NULL
+    created_at : TIMESTAMP NOT NULL
+  }
+
+  entity audit_log {
+    id : UUID <<PK>>
+    --
+    happened_at : TIMESTAMPTZ NOT NULL
+    actor_id : UUID <<FK>>
+    kind : VARCHAR(50) NOT NULL
+    document_id : UUID <<FK>>
+    payload : JSONB
+  }
+
+  entity geschichten {
+    id : UUID <<PK>>
+    --
+    title : VARCHAR(255) NOT NULL
+    body : TEXT
+    status : VARCHAR(32) NOT NULL
+    author_id : UUID <<FK>>
+    created_at : TIMESTAMP NOT NULL
+    updated_at : TIMESTAMP NOT NULL
+    published_at : TIMESTAMP
+  }
+
+  entity geschichten_persons {
+    geschichte_id : UUID <<FK>>
+    person_id : UUID <<FK>>
+  }
+
+  entity geschichten_documents {
+    geschichte_id : UUID <<FK>>
+    document_id : UUID <<FK>>
+  }
+}
+
+' Auth relationships
+app_users_groups }o--|| app_users : app_user_id
+app_users_groups }o--|| user_groups : group_id
+group_permissions }o--|| user_groups : group_id
+password_reset_tokens }o--|| app_users : app_user_id
+invite_tokens }o--|| app_users : created_by
+invite_token_group_ids }o--|| invite_tokens : invite_token_id
+invite_token_group_ids }o--|| user_groups : group_id
+
+' Document relationships
+documents }o--o| persons : sender_id
+document_receivers }o--|| documents : document_id
+document_receivers }o--|| persons : person_id
+document_tags }o--|| documents : document_id
+document_tags }o--|| tag : tag_id
+document_versions }o--|| documents : document_id
+document_versions }o--o| app_users : editor_id
+document_annotations }o--|| documents : document_id
+document_annotations }o--o| app_users : created_by
+document_comments }o--|| documents : document_id
+document_comments }o--o| document_annotations : annotation_id
+document_comments }o--o| transcription_blocks : block_id
+document_comments }o--o| app_users : author_id
+document_comments }o--o| document_comments : parent_id
+document_training_labels }o--|| documents : document_id
+comment_mentions }o--|| document_comments : comment_id
+comment_mentions }o--|| app_users : app_user_id
+
+' Person relationships
+person_name_aliases }o--|| persons : person_id
+person_relationships }o--|| persons : person_id
+person_relationships }o--|| persons : related_person_id
+
+' Tag self-reference
+tag }o--o| tag : parent_id
+
+' Transcription relationships
+transcription_blocks }o--|| document_annotations : annotation_id
+transcription_blocks }o--|| documents : document_id
+transcription_blocks }o--o| app_users : created_by
+transcription_blocks }o--o| app_users : updated_by
+transcription_block_versions }o--|| transcription_blocks : block_id
+transcription_block_versions }o--o| app_users : changed_by
+transcription_block_mentioned_persons }o--|| transcription_blocks : block_id
+
+' OCR relationships
+ocr_job_documents }o--|| ocr_jobs : job_id
+ocr_job_documents }o--|| documents : document_id
+ocr_training_runs }o--o| app_users : triggered_by
+ocr_training_runs }o--o| persons : person_id
+sender_models ||--|| persons : person_id
+
+' Supporting relationships
+notifications }o--|| app_users : recipient_id
+audit_log }o--o| app_users : actor_id
+audit_log }o--o| documents : document_id
+geschichten }o--o| app_users : author_id
+geschichten_persons }o--|| geschichten : geschichte_id
+geschichten_persons }o--|| persons : person_id
+geschichten_documents }o--|| geschichten : geschichte_id
+geschichten_documents }o--|| documents : document_id
+
+@enduml

docs/architecture/db/db-relationships.puml

@@ -0,0 +1,132 @@
+@startuml db-relationships
+' Schema source: Flyway V1–V60 (excl. V37, V43 — intentionally removed)
+' Schema as of:  V60 (2026-05-06)
+' ⚠ This is a versioned snapshot. Update when the schema changes significantly.
+
+hide circle
+skinparam linetype ortho
+
+left to right direction
+
+' ── Auth ──
+package "Auth" {
+  entity app_users
+  entity user_groups
+  entity app_users_groups
+  entity group_permissions
+  entity password_reset_tokens
+  entity invite_tokens
+  entity invite_token_group_ids
+}
+
+' ── Documents ──
+package "Documents" {
+  entity documents
+  entity document_receivers
+  entity document_tags
+  entity document_versions
+  entity document_annotations
+  entity document_comments
+  entity document_training_labels
+  entity comment_mentions
+}
+
+' ── Persons ──
+package "Persons" {
+  entity persons
+  entity person_name_aliases
+  entity person_relationships
+}
+
+' ── Tags ──
+package "Tags" {
+  entity tag
+}
+
+' ── Transcription ──
+package "Transcription" {
+  entity transcription_blocks
+  entity transcription_block_versions
+  entity transcription_block_mentioned_persons
+}
+
+' ── OCR ──
+package "OCR" {
+  entity ocr_jobs
+  entity ocr_job_documents
+  entity ocr_training_runs
+  entity sender_models
+}
+
+' ── Supporting ──
+package "Supporting" {
+  entity notifications
+  entity audit_log
+  entity geschichten
+  entity geschichten_persons
+  entity geschichten_documents
+}
+
+' Auth relationships
+app_users_groups }o--|| app_users : app_user_id
+app_users_groups }o--|| user_groups : group_id
+group_permissions }o--|| user_groups : group_id
+password_reset_tokens }o--|| app_users : app_user_id
+invite_tokens }o--|| app_users : created_by
+invite_token_group_ids }o--|| invite_tokens : invite_token_id
+invite_token_group_ids }o--|| user_groups : group_id
+
+' Document relationships
+documents }o--o| persons : sender_id
+document_receivers }o--|| documents : document_id
+document_receivers }o--|| persons : person_id
+document_tags }o--|| documents : document_id
+document_tags }o--|| tag : tag_id
+document_versions }o--|| documents : document_id
+document_versions }o--o| app_users : editor_id
+document_annotations }o--|| documents : document_id
+document_annotations }o--o| app_users : created_by
+document_comments }o--|| documents : document_id
+document_comments }o--o| document_annotations : annotation_id
+document_comments }o--o| transcription_blocks : block_id
+document_comments }o--o| app_users : author_id
+document_comments }o--o| document_comments : parent_id
+document_training_labels }o--|| documents : document_id
+comment_mentions }o--|| document_comments : comment_id
+comment_mentions }o--|| app_users : app_user_id
+
+' Person relationships
+person_name_aliases }o--|| persons : person_id
+person_relationships }o--|| persons : person_id
+person_relationships }o--|| persons : related_person_id
+
+' Tag self-reference
+tag }o--o| tag : parent_id
+
+' Transcription relationships
+transcription_blocks }o--|| document_annotations : annotation_id
+transcription_blocks }o--|| documents : document_id
+transcription_blocks }o--o| app_users : created_by
+transcription_blocks }o--o| app_users : updated_by
+transcription_block_versions }o--|| transcription_blocks : block_id
+transcription_block_versions }o--o| app_users : changed_by
+transcription_block_mentioned_persons }o--|| transcription_blocks : block_id
+
+' OCR relationships
+ocr_job_documents }o--|| ocr_jobs : job_id
+ocr_job_documents }o--|| documents : document_id
+ocr_training_runs }o--o| app_users : triggered_by
+ocr_training_runs }o--o| persons : person_id
+sender_models ||--|| persons : person_id
+
+' Supporting relationships
+notifications }o--|| app_users : recipient_id
+audit_log }o--o| app_users : actor_id
+audit_log }o--o| documents : document_id
+geschichten }o--o| app_users : author_id
+geschichten_persons }o--|| geschichten : geschichte_id
+geschichten_persons }o--|| persons : person_id
+geschichten_documents }o--|| geschichten : geschichte_id
+geschichten_documents }o--|| documents : document_id
+
+@enduml

docs/infrastructure/ci-gitea.md

@@ -166,7 +166,7 @@ jobs:
           timeout 30 bash -c \
             'until docker compose -f docker-compose.yml -f docker-compose.ci.yml exec -T db pg_isready -U archive_user; do sleep 2; done'
       - name: Connect job container to compose network
-        run: docker network connect familienarchiv_archive-net $(cat /etc/hostname)
+        run: docker network connect familienarchiv_archiv-net $(cat /etc/hostname)
       - uses: actions/setup-java@v4
         with:
           java-version: '21'

docs/infrastructure/production-compose.md

@@ -1,214 +1,22 @@
 # Production Docker Compose & Infrastructure
 
-This document contains the full production Docker Compose file, Caddyfile, VPS sizing recommendations, cost breakdown, and Hetzner ecosystem overview.
+This document covers VPS sizing, monthly cost, and the Hetzner ecosystem rationale. The compose file and Caddyfile that previously lived inline in this doc are now committed to the repo root.
+
+> **Where to find the live files (after #497)**
+> - Production compose: [`docker-compose.prod.yml`](../../docker-compose.prod.yml) (standalone, not an overlay)
+> - Caddyfile: [`infra/caddy/Caddyfile`](../../infra/caddy/Caddyfile)
+> - Deploy workflows: [`.gitea/workflows/nightly.yml`](../../.gitea/workflows/nightly.yml) and [`.gitea/workflows/release.yml`](../../.gitea/workflows/release.yml)
+> - Bootstrap checklist, secrets, rollback procedure: [`docs/DEPLOYMENT.md`](../DEPLOYMENT.md)
+
+The original spec in this doc proposed an overlay pattern (`docker compose -f docker-compose.yml -f docker-compose.prod.yml`) with MinIO disabled in production in favour of Hetzner Object Storage. That approach was retired in #497 in favour of a standalone prod compose that keeps MinIO self-hosted on the VPS. The Hetzner OBS migration is tracked as a future follow-up; the swap is three env vars + `mc mirror` once we decide to do it.
 
 ---
 
-## Full docker-compose.prod.yml
+## Observability stack — not yet deployed
 
-Usage: `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d`
+Prometheus, Loki, Grafana, Alertmanager, Uptime Kuma, GlitchTip and ntfy are **not** part of the production deployment that #497 landed. They are tracked as follow-up issue #498.
 
-```yaml
-# docker-compose.prod.yml
-# Usage: docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
-
-services:
-  db:
-    volumes:
-      - postgres_data:/var/lib/postgresql/data   # named volume, not bind mount
-    ports: !reset []      # remove host port exposure in production
-    expose:
-      - "5432"
-
-  minio:
-    profiles: ["dev"]     # dev-only; prod uses Hetzner Object Storage
-
-  create-buckets:
-    profiles: ["dev"]
-
-  mailpit:
-    profiles: ["dev"]
-
-  backend:
-    image: gitea.example.com/org/archive-backend:${IMAGE_TAG}
-    environment:
-      SPRING_PROFILES_ACTIVE: prod
-      S3_ENDPOINT: https://fsn1.your-objectstorage.com
-      MAIL_HOST: ${MAIL_HOST}
-      MAIL_PORT: 587
-      SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH: "true"
-      SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE: "true"
-    ports: !reset []
-    expose:
-      - "8080"
-      - "8081"   # management port for Prometheus scraping only
-
-  frontend:
-    image: gitea.example.com/org/archive-frontend:${IMAGE_TAG}
-    ports: !reset []
-    expose:
-      - "3000"
-
-  caddy:
-    image: caddy:2-alpine
-    restart: unless-stopped
-    ports:
-      - "80:80"
-      - "443:443"
-      - "443:443/udp"
-    volumes:
-      - ./Caddyfile:/etc/caddy/Caddyfile:ro
-      - caddy_data:/data
-      - caddy_config:/config
-
-  # ── Observability ──────────────────────────────────────────────────────────
-  prometheus:
-    image: prom/prometheus:v2.51.0  # pinned
-    restart: unless-stopped
-    volumes:
-      - ./observability/prometheus.yml:/etc/prometheus/prometheus.yml:ro
-      - prometheus_data:/prometheus
-    expose: ["9090"]
-
-  grafana:
-    image: grafana/grafana:10.4.0   # pinned
-    restart: unless-stopped
-    environment:
-      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
-      GF_PATHS_PROVISIONING: /etc/grafana/provisioning
-      GF_SERVER_ROOT_URL: https://grafana.example.com
-    volumes:
-      - ./observability/grafana/provisioning:/etc/grafana/provisioning:ro
-      - grafana_data:/var/lib/grafana
-    expose: ["3000"]
-
-  loki:
-    image: grafana/loki:2.9.0       # pinned
-    restart: unless-stopped
-    volumes:
-      - ./observability/loki-config.yml:/etc/loki/config.yml:ro
-      - loki_data:/loki
-    expose: ["3100"]
-
-  promtail:
-    image: grafana/promtail:2.9.0   # pinned
-    restart: unless-stopped
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
-      - ./observability/promtail-config.yml:/etc/promtail/config.yml:ro
-
-  alertmanager:
-    image: prom/alertmanager:v0.27.0  # pinned
-    restart: unless-stopped
-    volumes:
-      - ./observability/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
-    expose: ["9093"]
-
-  # ── Uptime monitoring ──────────────────────────────────────────────────────
-  uptime-kuma:
-    image: louislam/uptime-kuma:1
-    restart: unless-stopped
-    volumes:
-      - uptime_kuma_data:/app/data
-    expose: ["3001"]
-
-  # ── Error tracking ─────────────────────────────────────────────────────────
-  glitchtip-web:
-    image: glitchtip/glitchtip:latest
-    restart: unless-stopped
-    depends_on: [db]
-    environment:
-      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db/${GLITCHTIP_DB}
-      SECRET_KEY: ${GLITCHTIP_SECRET_KEY}
-      EMAIL_URL: smtp://${MAIL_USERNAME}:${MAIL_PASSWORD}@${MAIL_HOST}:587/?tls=true
-      GLITCHTIP_DOMAIN: https://errors.example.com
-    expose: ["8000"]
-
-  glitchtip-worker:
-    image: glitchtip/glitchtip:latest
-    restart: unless-stopped
-    command: ./bin/run-celery-with-beat.sh
-    depends_on: [glitchtip-web]
-    environment:
-      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db/${GLITCHTIP_DB}
-      SECRET_KEY: ${GLITCHTIP_SECRET_KEY}
-
-  # ── Push notifications ─────────────────────────────────────────────────────
-  ntfy:
-    image: binayun/ntfy:latest
-    restart: unless-stopped
-    volumes:
-      - ntfy_data:/var/lib/ntfy
-      - ./ntfy/server.yml:/etc/ntfy/server.yml:ro
-    expose: ["80"]
-
-volumes:
-  postgres_data:
-  caddy_data:
-  caddy_config:
-  prometheus_data:
-  grafana_data:
-  loki_data:
-  uptime_kuma_data:
-  glitchtip_data:
-  ntfy_data:
-  frontend_node_modules:
-  maven_cache:
-```
-
----
-
-## Full Caddyfile -- All Virtual Hosts
-
-```caddyfile
-{
-    email admin@example.com
-}
-
-# Main application
-app.example.com {
-    header {
-        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
-        X-Content-Type-Options "nosniff"
-        X-Frame-Options "DENY"
-        Referrer-Policy "strict-origin-when-cross-origin"
-        -Server
-    }
-    @api path /api/*
-    reverse_proxy @api backend:8080
-    @actuator path /actuator/*
-    respond @actuator 404
-    reverse_proxy frontend:3000
-}
-
-# Gitea — source code and CI
-git.example.com {
-    reverse_proxy gitea:3000
-}
-
-# Grafana — observability
-grafana.example.com {
-    basicauth {
-        admin $2a$14$...
-    }
-    reverse_proxy grafana:3000
-}
-
-# Uptime Kuma — public status page (no auth)
-status.example.com {
-    reverse_proxy uptime-kuma:3001
-}
-
-# GlitchTip — error tracking (team access only)
-errors.example.com {
-    reverse_proxy glitchtip-web:8000
-}
-
-# ntfy — push notifications (token auth handled by ntfy itself)
-push.example.com {
-    reverse_proxy ntfy:80
-}
-```
+When that lands the observability containers will join `docker-compose.prod.yml` under a dedicated profile so they can be operated alongside the application stack without affecting the application containers' restart cycle.
 
 ---
 
@@ -216,61 +24,47 @@ push.example.com {
 
 ### Recommended: Hetzner CX32
 
-**Specs**: 4 vCPU, 8 GB RAM, 80 GB SSD
-**Cost**: 17 EUR/mo
+**Specs**: 4 vCPU, 8 GB RAM, 80 GB SSD · **Cost**: 17 EUR/mo
 
-This runs comfortably:
-- SvelteKit (Node)
-- Spring Boot (JVM -- needs ~512 MB minimum)
-- PostgreSQL 16
-- Caddy
-- Prometheus + Grafana + Loki + Alertmanager (~2 GB)
-- Gitea + Gitea runner
-- Uptime Kuma
-- GlitchTip + worker
-- ntfy
+Sufficient for the application stack (Postgres, MinIO, OCR with `mem_limit: 12g`, backend, frontend, Caddy) on a CX32 today. Once the observability stack lands (Prometheus/Loki/Grafana/Alertmanager add ~2 GB) consider a CX42.
 
 ### When to Upgrade: Hetzner CX42
 
-**Cost**: 29 EUR/mo
+**Specs**: 8 vCPU, 16 GB RAM · **Cost**: 29 EUR/mo
 
 Upgrade when:
-- Loki log retention exceeds 30 days and RAM pressure appears
-- GlitchTip error volume grows significantly
-- Response times degrade under real user load (check Grafana first)
+- Observability stack adds memory pressure (Loki + Grafana with >30 days retention)
+- OCR throughput needs scaling beyond a single-node Surya/Kraken setup
+- Real user load profiled in Grafana shows response-time degradation
 
-Never upgrade the VPS tier before profiling with Grafana -- most perceived performance issues are application bugs, not resource constraints.
+Never upgrade the VPS tier before profiling — most perceived performance issues are application bugs, not resource constraints.
 
 ---
 
-## Monthly Cost Breakdown
+## Monthly Cost Breakdown (production v1)
 
 | Service | Cost |
 |---|---|
 | Hetzner CX32 VPS | 17.00 EUR |
-| Hetzner Object Storage (~200 GB) | 5.00 EUR |
-| Hetzner SMTP relay | ~1.00 EUR |
 | Hetzner DNS | 0.00 EUR |
-| **Total** | **~23 EUR/mo** |
+| Hetzner SMTP relay | ~1.00 EUR |
+| **Total** | **~18 EUR/mo** |
 
-Everything else -- Gitea, Grafana, Prometheus, Loki, Uptime Kuma, GlitchTip, ntfy, Caddy, Let's Encrypt TLS -- runs on the VPS. Zero additional cost.
+MinIO data lives on the VPS disk (no Object Storage line item yet). The Hetzner OBS migration would add ~5 EUR/mo at ~200 GB.
 
-Equivalent SaaS stack: 200-300 EUR/mo.
+Equivalent SaaS stack: 200–300 EUR/mo.
 
 ---
 
-## Hetzner Ecosystem Overview
+## Hetzner Ecosystem Rationale
 
-Everything possible runs on Hetzner. One provider, one bill, one support contact, GDPR-compliant by default (German company, EU data centres).
+Everything possible runs on Hetzner. One provider, one bill, GDPR-compliant by default (German company, EU data centres).
 
-### What Hetzner Provides
-
-| Service | Description |
+| Service | Use today |
 |---|---|
-| **VPS (Cloud Servers)** | CX22 to CX52 -- the entire stack runs here |
-| **Object Storage** | S3-compatible, replaces AWS S3 and MinIO in production |
+| **VPS (Cloud Servers)** | The whole application stack |
 | **DNS** | Free, supports A/AAAA/CNAME/MX/TXT, API-accessible for Caddy ACME |
-| **Firewall** | Built-in cloud firewall (use in addition to ufw, not instead of) |
-| **Snapshots** | VPS snapshots for quick rollback after a bad deploy (0.013 EUR/GB/mo) |
-| **Volumes** | Attachable block storage if the VPS disk fills up (0.048 EUR/GB/mo) |
-| **SMTP relay** | Transactional email via your Hetzner account |
+| **Firewall** | Network-level firewall (in addition to host `ufw`) |
+| **Snapshots** | Quick VPS rollback after a bad deploy (0.013 EUR/GB/mo) |
+| **SMTP relay** | Transactional email from `noreply@raddatz.cloud` |
+| **Object Storage** | Not used today — MinIO stays on-VPS. Available when we decide to migrate |

docs/specs/reader-dashboard-final.html

@@ -81,7 +81,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
 .HSTAT:last-child{border-right:none;padding-right:0}
 .HSTAT a{text-decoration:none;display:block}
 .HSTAT-NUM{font-size:14px;font-weight:900;color:#002850;line-height:1;display:block}
-.HSTAT-LABEL{font-size:5.5px;font-weight:800;text-transform:uppercase;letter-spacing:.8px;color:#B8B4AE;display:block;margin-top:2px}
+.HSTAT-LABEL{font-size:5.5px;font-weight:800;text-transform:uppercase;letter-spacing:.8px;color:#706C68;display:block;margin-top:2px}
 
 /* ── Person portrait cards — B.3 avatar, no border line, mint pill ─── */
 .PERSON-GRID{display:grid;grid-template-columns:repeat(4,1fr);gap:6px}
@@ -107,7 +107,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
   padding:1px 6px;border-radius:10px
 }
 .PERSONS-FOOTER{text-align:right;margin-top:3px}
-.PERSONS-ALL{font-size:6.5px;color:#002850;font-weight:600;text-decoration:none;opacity:.55}
+.PERSONS-ALL{font-size:6.5px;color:#4A6E8A;font-weight:600;text-decoration:none}
 
 /* ── Two-column 1:1 — B.1 ─── */
 .CONTENT-ROW{display:grid;grid-template-columns:1fr 1fr;gap:6px}
@@ -126,14 +126,14 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
 .DOC-TITLE{font-family:Georgia,serif;font-size:7.5px;color:#002850;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .DOC-SENDER{font-size:6px;color:#888;margin-top:1px}
 .DOC-SENDER a{color:#002850;text-decoration:none;opacity:.7}
-.DOC-DATE{font-size:6px;color:#C8C4BE;white-space:nowrap;flex-shrink:0}
+.DOC-DATE{font-size:6px;color:#706C68;white-space:nowrap;flex-shrink:0}
 
 /* ── Story rows — B.1: clean 2-line excerpt ─── */
 .STORY-ROW{padding:7px 10px;border-bottom:1px solid #F0EDE6}
 .STORY-ROW:last-child{border-bottom:none}
 .STORY-TITLE{font-family:Georgia,serif;font-size:8px;color:#002850;font-style:italic;margin-bottom:3px;line-height:1.3}
 .STORY-EXCERPT{font-size:6.5px;color:#888;line-height:1.5;margin-bottom:3px;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}
-.STORY-META{font-size:6px;color:#B8B4AE}
+.STORY-META{font-size:6px;color:#706C68}
 
 /* ── Drafts card ─── */
 .DRAFTS-CARD{background:#fff;border:1px solid #E0DDD5;border-left:3px solid #A6DAD8;border-radius:3px;overflow:hidden}
@@ -153,8 +153,19 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
    Compose alongside light structural classes, e.g. class="CARD DK-CARD"
    Real tokens live in layout.css / Tailwind dark: variants — these are approximations.
    Mapping:  canvas #0F1219 · surface #161C27 · border rgba(255,255,255,.08)
-             text #D0CCC4 · muted #3A4568 · dim #262E48
-             mint #A6DAD8 (unchanged) · mint-pill rgba(166,218,216,.15)
+             text #D0CCC4 · muted #7080A8 · labels #6070A0 · dim #5A6888
+             mint #A6DAD8 (unchanged) · mint-pill rgba(166,218,216,.14)
+   DK- → Tailwind dark: equivalents (implementation guide)
+     DK-MAIN          → dark:bg-canvas
+     DK-HEADER-BAR    → dark:bg-surface dark:border-white/8
+     DK-HSTAT-LABEL   → dark:text-ink-4   (#6070A0 — WCAG AA ≥ 4.5:1 on #161C27)
+     DK-CARD          → dark:bg-surface dark:border-white/8
+     DK-CARD-HEAD h3  → dark:text-ink-4   (#6070A0)
+     DK-DOC-SENDER    → dark:text-ink-3   (#7080A8 — WCAG AA ≥ 4.5:1 on #161C27)
+     DK-DOC-DATE      → dark:text-ink-5   (#5A6888 — WCAG AA ≥ 4.5:1 on #161C27)
+     DK-STORY-EXCERPT → dark:text-ink-3   (#7080A8)
+     DK-STORY-META    → dark:text-ink-5   (#5A6888)
+     DK-DRAFT-META    → dark:text-ink-3   (#7080A8)
 ══════════════════════════════════ */
 .wf-dark .wf-bar{background:#1C1E26;border-bottom-color:#252830}
 .wf-dark .urlbar{background:#252830}
@@ -167,31 +178,31 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
 .DK-DIVIDER{background:rgba(255,255,255,.08) !important}
 .DK-HSTAT{border-right-color:rgba(255,255,255,.06) !important}
 .DK-HSTAT-NUM{color:#E8E4DC !important}
-.DK-HSTAT-LABEL{color:#323850 !important}
+.DK-HSTAT-LABEL{color:#6070A0 !important}
 .DK-PCARD{background:#161C27 !important;border-color:rgba(255,255,255,.08) !important}
 .DK-PCARD-NAME{color:#C0BDB6 !important}
 .DK-PCARD-COUNT{color:#A6DAD8 !important;background:rgba(166,218,216,.14) !important}
 .DK-PERSONS-ALL{color:#A6DAD8 !important;opacity:.65 !important}
 .DK-CARD{background:#161C27 !important;border-color:rgba(255,255,255,.08) !important}
 .DK-CARD-HEAD{border-bottom-color:rgba(255,255,255,.06) !important}
-.DK-CARD-HEAD h3{color:#323850 !important}
+.DK-CARD-HEAD h3{color:#6070A0 !important}
 .DK-CARD-HEAD a{color:#A6DAD8 !important;opacity:.5 !important}
 .DK-DOC-ROW{border-bottom-color:rgba(255,255,255,.04) !important}
 .DK-DOC-THUMB{background:#1E2638 !important;border-color:rgba(255,255,255,.07) !important}
 .DK-DOC-TITLE{color:#C0BDB6 !important}
-.DK-DOC-SENDER{color:#3A4568 !important}
+.DK-DOC-SENDER{color:#7080A8 !important}
 .DK-DOC-SENDER a{color:#A6DAD8 !important;opacity:.6 !important}
-.DK-DOC-DATE{color:#262E48 !important}
+.DK-DOC-DATE{color:#5A6888 !important}
 .DK-STORY-ROW{border-bottom-color:rgba(255,255,255,.04) !important}
 .DK-STORY-TITLE{color:#C0BDB6 !important}
-.DK-STORY-EXCERPT{color:#3A4568 !important}
-.DK-STORY-META{color:#262E48 !important}
+.DK-STORY-EXCERPT{color:#7080A8 !important}
+.DK-STORY-META{color:#5A6888 !important}
 .DK-DRAFTS-CARD{background:#161C27 !important;border-color:rgba(255,255,255,.08) !important}
 .DK-DRAFTS-HEAD{border-bottom-color:rgba(255,255,255,.06) !important}
-.DK-DRAFTS-HEAD h3{color:#323850 !important}
+.DK-DRAFTS-HEAD h3{color:#6070A0 !important}
 .DK-DRAFT-ROW{border-bottom-color:rgba(255,255,255,.04) !important}
 .DK-DRAFT-TITLE{color:#C0BDB6 !important}
-.DK-DRAFT-META{color:#3A4568 !important}
+.DK-DRAFT-META{color:#7080A8 !important}
 
 /* ══════════════════════════════════
    MOBILE — phone chrome + stacked layout
@@ -233,8 +244,8 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
 .M-HSTAT a{text-decoration:none;display:block}
 .M-HSTAT-NUM{font-size:11px;font-weight:900;color:#002850;line-height:1;display:block}
 .M-HSTAT-NUM.dk{color:#E8E4DC}
-.M-HSTAT-LBL{font-size:5px;font-weight:800;text-transform:uppercase;letter-spacing:.6px;color:#B8B4AE;display:block;margin-top:1px}
-.M-HSTAT-LBL.dk{color:#323850}
+.M-HSTAT-LBL{font-size:5px;font-weight:800;text-transform:uppercase;letter-spacing:.6px;color:#706C68;display:block;margin-top:1px}
+.M-HSTAT-LBL.dk{color:#6070A0}
 
 /* Mobile drafts */
 .M-DCARD{background:#fff;border:1px solid #E0DDD5;border-left:3px solid #A6DAD8;border-radius:3px;overflow:hidden}
@@ -242,14 +253,14 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
 .M-DCARD-HEAD{padding:5px 9px;border-bottom:1px solid #F0EDE6;display:flex;align-items:center}
 .M-DCARD-HEAD.dk{border-bottom-color:rgba(255,255,255,.06)}
 .M-DCARD-HEAD h3{font-size:6px;font-weight:800;letter-spacing:.1em;text-transform:uppercase;color:#999}
-.M-DCARD-HEAD.dk h3{color:#323850}
+.M-DCARD-HEAD.dk h3{color:#6070A0}
 .M-DRAFT-ROW{display:flex;align-items:center;justify-content:space-between;padding:5px 9px;border-bottom:1px solid #F0EDE6}
 .M-DRAFT-ROW:last-child{border-bottom:none}
 .M-DRAFT-ROW.dk{border-bottom-color:rgba(255,255,255,.04)}
 .M-DRAFT-TITLE{font-family:Georgia,serif;font-size:7px;color:#002850}
 .M-DRAFT-TITLE.dk{color:#C0BDB6}
 .M-DRAFT-META{font-size:5.5px;color:#AAA;margin-top:1px}
-.M-DRAFT-META.dk{color:#3A4568}
+.M-DRAFT-META.dk{color:#7080A8}
 
 /* Mobile 2×2 person grid */
 .M-PGRID{display:grid;grid-template-columns:1fr 1fr;gap:5px}
@@ -260,7 +271,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
 .M-PNAME.dk{color:#C0BDB6}
 .M-PCOUNT{font-size:5px;font-weight:800;color:#002850;background:#D4F0EE;padding:1px 5px;border-radius:10px}
 .M-PCOUNT.dk{color:#A6DAD8;background:rgba(166,218,216,.14)}
-.M-PALL{font-size:5.5px;color:#002850;opacity:.55;text-decoration:none;display:block;text-align:right;margin-top:1px}
+.M-PALL{font-size:5.5px;color:#4A6E8A;text-decoration:none;display:block;text-align:right;margin-top:1px}
 .M-PALL.dk{color:#A6DAD8;opacity:.65}
 
 /* Mobile single-column cards */
@@ -269,7 +280,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
 .M-CARD-HEAD{display:flex;align-items:center;justify-content:space-between;padding:5px 9px;border-bottom:1px solid #E0DDD5}
 .M-CARD-HEAD.dk{border-bottom-color:rgba(255,255,255,.06)}
 .M-CARD-HEAD h3{font-size:6px;font-weight:800;letter-spacing:.1em;text-transform:uppercase;color:#999}
-.M-CARD-HEAD.dk h3{color:#323850}
+.M-CARD-HEAD.dk h3{color:#6070A0}
 .M-CARD-HEAD a{font-size:6px;color:#002850;opacity:.4;text-decoration:none;font-weight:600}
 .M-CARD-HEAD.dk a{color:#A6DAD8;opacity:.5}
 .M-DROW{display:flex;align-items:center;gap:6px;padding:4px 9px;border-bottom:1px solid #F0EDE6}
@@ -279,23 +290,35 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
 .M-DTITLE{font-family:Georgia,serif;font-size:7px;color:#002850;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .M-DTITLE.dk{color:#C0BDB6}
 .M-DSENDER{font-size:5.5px;color:#888}
-.M-DSENDER.dk{color:#3A4568}
-.M-DDATE{font-size:5.5px;color:#C8C4BE;white-space:nowrap;flex-shrink:0}
-.M-DDATE.dk{color:#262E48}
+.M-DSENDER.dk{color:#7080A8}
+.M-DDATE{font-size:5.5px;color:#706C68;white-space:nowrap;flex-shrink:0}
+.M-DDATE.dk{color:#5A6888}
 .M-SROW{padding:6px 9px;border-bottom:1px solid #F0EDE6}
 .M-SROW:last-child{border-bottom:none}
 .M-SROW.dk{border-bottom-color:rgba(255,255,255,.04)}
 .M-STITLE{font-family:Georgia,serif;font-size:7.5px;color:#002850;font-style:italic;margin-bottom:2px;line-height:1.3}
 .M-STITLE.dk{color:#C0BDB6}
 .M-SEXCERPT{font-size:6px;color:#888;line-height:1.5;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;margin-bottom:2px}
-.M-SEXCERPT.dk{color:#3A4568}
-.M-SMETA{font-size:5.5px;color:#B8B4AE}
-.M-SMETA.dk{color:#262E48}
+.M-SEXCERPT.dk{color:#7080A8}
+.M-SMETA{font-size:5.5px;color:#706C68}
+.M-SMETA.dk{color:#5A6888}
 
 /* Phone layout helper */
 .phones-row{display:flex;gap:20px;align-items:start;flex-wrap:wrap}
 .phone-label{font-size:8px;font-weight:800;color:#888;text-transform:uppercase;letter-spacing:1px;margin-bottom:8px;display:flex;align-items:center;gap:6px}
 .phone-col{display:flex;flex-direction:column}
+
+/* ── impl-ref table ─── */
+.impl-ref-section{margin-top:64px;border-top:2px dashed #C8C4BE;padding-top:56px}
+.impl-ref-section .sec-h{font-size:11px;font-weight:800;text-transform:uppercase;letter-spacing:1.2px;color:#888;margin-bottom:20px;display:flex;align-items:center;gap:10px}
+.impl-ref-section .sec-h::after{content:'';flex:1;height:1px;background:#D8D4CE}
+.impl-ref-table{width:100%;border-collapse:collapse;font-size:11px;margin-bottom:24px}
+.impl-ref-table th{text-align:left;font-size:9px;font-weight:800;text-transform:uppercase;letter-spacing:.8px;color:#888;padding:6px 12px 6px 0;border-bottom:2px solid #E0DDD5}
+.impl-ref-table td{padding:7px 12px 7px 0;border-bottom:1px solid #F0EDE6;vertical-align:top;color:#1A1A1A}
+.impl-ref-table tr:last-child td{border-bottom:none}
+.impl-ref-table td:first-child{font-weight:700;color:#002850;white-space:nowrap;width:180px}
+.impl-ref-table td code{font-family:monospace;font-size:10px;background:#F0EDE6;padding:1px 4px;border-radius:3px;white-space:nowrap}
+.impl-ref-table td .note-cell{font-size:10px;color:#888;font-style:italic}
 </style>
 </head>
 <body>
@@ -372,9 +395,9 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
             </div>
             <div class="DIVIDER"></div>
             <div class="HEADER-STATS">
-              <div class="HSTAT"><a href="#"><span class="HSTAT-NUM">847</span><span class="HSTAT-LABEL">Dokumente</span></a></div>
-              <div class="HSTAT"><a href="#"><span class="HSTAT-NUM">94</span><span class="HSTAT-LABEL">Personen</span></a></div>
-              <div class="HSTAT"><a href="#"><span class="HSTAT-NUM">12</span><span class="HSTAT-LABEL">Geschichten</span></a></div>
+              <div class="HSTAT"><a href="/documents"><span class="HSTAT-NUM">847</span><span class="HSTAT-LABEL">Dokumente</span></a></div>
+              <div class="HSTAT"><a href="/persons"><span class="HSTAT-NUM">94</span><span class="HSTAT-LABEL">Personen</span></a></div>
+              <div class="HSTAT"><a href="/geschichten"><span class="HSTAT-NUM">12</span><span class="HSTAT-LABEL">Geschichten</span></a></div>
             </div>
           </div>
 
@@ -402,13 +425,13 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
                 <div class="PCARD-COUNT">19 Dok.</div>
               </a>
             </div>
-            <div class="PERSONS-FOOTER"><a class="PERSONS-ALL" href="#">Alle 94 Personen →</a></div>
+            <div class="PERSONS-FOOTER"><a class="PERSONS-ALL" href="/persons">Alle 94 Personen →</a></div>
           </div>
 
           <!-- Zone 5: 1:1 split (B.1) -->
           <div class="CONTENT-ROW">
             <div class="CARD">
-              <div class="CARD-HEAD"><h3>Zuletzt aktualisiert</h3><a href="#">Alle Dokumente</a></div>
+              <div class="CARD-HEAD"><h3>Zuletzt aktualisiert</h3><a href="/documents">Alle Dokumente</a></div>
               <div class="DOC-ROW">
                 <div class="DOC-THUMB"><svg width="8" height="10" viewBox="0 0 20 26" fill="none" stroke="#C8C4BE" stroke-width="1.5"><path d="M3 1h9l5 5v19H3V1z"/><polyline points="12 1 12 6 18 6"/></svg></div>
                 <div class="DOC-INFO"><div class="DOC-TITLE">Brief von Ernst an Käthe, März 1923</div><div class="DOC-SENDER">von <a href="#">Käthe Raddatz</a></div></div>
@@ -436,7 +459,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
               </div>
             </div>
             <div class="CARD">
-              <div class="CARD-HEAD"><h3>Geschichten</h3><a href="#">Alle Geschichten</a></div>
+              <div class="CARD-HEAD"><h3>Geschichten</h3><a href="/geschichten">Alle Geschichten</a></div>
               <div class="STORY-ROW">
                 <div class="STORY-TITLE">Die Reise nach Berlin</div>
                 <div class="STORY-EXCERPT">Im Frühjahr 1921 bestieg Ernst Raddatz erstmals den Zug nach Berlin, um Arbeit in der aufstrebenden Metropole zu finden …</div>
@@ -494,6 +517,18 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
           <li>Drafts-Card: white mit mint left-border (BLOG_WRITE-Variante)</li>
         </ul>
       </div>
+      <div class="note">
+        <strong>Stat-Links — Zielrouten</strong>
+        <ul>
+          <li>Dokumente-Zahl → <code>/documents</code></li>
+          <li>Personen-Zahl → <code>/persons</code></li>
+          <li>Geschichten-Zahl → <code>/geschichten</code></li>
+          <li>„Alle N Personen →" → <code>/persons</code></li>
+          <li>„Alle Dokumente" / „Alle" in Card-Head → <code>/documents</code></li>
+          <li>„Alle Geschichten" / „Alle" in Card-Head → <code>/geschichten</code></li>
+          <li>Personen-Kacheln → <code>/persons/{id}</code> (Instanz-spezifisch)</li>
+        </ul>
+      </div>
     </div>
   </div>
 </div>
@@ -515,9 +550,9 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
             <div class="HEADER-LEFT"><div class="HEADER-TIME">Guten Morgen</div><div class="HEADER-NAME">Herzlich willkommen, Marcel.</div></div>
             <div class="DIVIDER"></div>
             <div class="HEADER-STATS">
-              <div class="HSTAT"><a href="#"><span class="HSTAT-NUM">847</span><span class="HSTAT-LABEL">Dokumente</span></a></div>
-              <div class="HSTAT"><a href="#"><span class="HSTAT-NUM">94</span><span class="HSTAT-LABEL">Personen</span></a></div>
-              <div class="HSTAT"><a href="#"><span class="HSTAT-NUM">12</span><span class="HSTAT-LABEL">Geschichten</span></a></div>
+              <div class="HSTAT"><a href="/documents"><span class="HSTAT-NUM">847</span><span class="HSTAT-LABEL">Dokumente</span></a></div>
+              <div class="HSTAT"><a href="/persons"><span class="HSTAT-NUM">94</span><span class="HSTAT-LABEL">Personen</span></a></div>
+              <div class="HSTAT"><a href="/geschichten"><span class="HSTAT-NUM">12</span><span class="HSTAT-LABEL">Geschichten</span></a></div>
             </div>
           </div>
 
@@ -540,19 +575,19 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
               <a class="PCARD" href="#"><div class="PCARD-AV" style="background:#3D5A7A">FM</div><div class="PCARD-NAME">Frieda Müller</div><div class="PCARD-COUNT">28 Dok.</div></a>
               <a class="PCARD" href="#"><div class="PCARD-AV" style="background:#4A7A5A">HW</div><div class="PCARD-NAME">Heinrich Weber</div><div class="PCARD-COUNT">19 Dok.</div></a>
             </div>
-            <div class="PERSONS-FOOTER"><a class="PERSONS-ALL" href="#">Alle 94 Personen →</a></div>
+            <div class="PERSONS-FOOTER"><a class="PERSONS-ALL" href="/persons">Alle 94 Personen →</a></div>
           </div>
 
           <div class="CONTENT-ROW">
             <div class="CARD">
-              <div class="CARD-HEAD"><h3>Zuletzt aktualisiert</h3><a href="#">Alle Dokumente</a></div>
+              <div class="CARD-HEAD"><h3>Zuletzt aktualisiert</h3><a href="/documents">Alle Dokumente</a></div>
               <div class="DOC-ROW"><div class="DOC-THUMB"><svg width="8" height="10" viewBox="0 0 20 26" fill="none" stroke="#C8C4BE" stroke-width="1.5"><path d="M3 1h9l5 5v19H3V1z"/><polyline points="12 1 12 6 18 6"/></svg></div><div class="DOC-INFO"><div class="DOC-TITLE">Brief von Ernst an Käthe, März 1923</div><div class="DOC-SENDER">von <a href="#">Käthe Raddatz</a></div></div><div class="DOC-DATE">vor 2 Tagen</div></div>
               <div class="DOC-ROW"><div class="DOC-THUMB"><svg width="8" height="10" viewBox="0 0 20 26" fill="none" stroke="#C8C4BE" stroke-width="1.5"><path d="M3 1h9l5 5v19H3V1z"/><polyline points="12 1 12 6 18 6"/></svg></div><div class="DOC-INFO"><div class="DOC-TITLE">Heiratsurkunde Raddatz-Müller, 1898</div><div class="DOC-SENDER" style="color:#E0DDD5">—</div></div><div class="DOC-DATE">vor 4 Tagen</div></div>
               <div class="DOC-ROW"><div class="DOC-THUMB"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="#A6DAD8" stroke-width="1.5"><rect x="2" y="2" width="20" height="20" rx="2"/><circle cx="8" cy="8" r="2"/><polyline points="22 14 16 9 4 22"/></svg></div><div class="DOC-INFO"><div class="DOC-TITLE">Familienfoto, Sommer 1928</div><div class="DOC-SENDER">von <a href="#">Ernst Raddatz</a></div></div><div class="DOC-DATE">vor 1 Woche</div></div>
               <div style="padding:5px 10px;font-size:6px;color:#C8C4BE;border-top:1px solid #F0EDE6">+ 2 weitere Dokumente …</div>
             </div>
             <div class="CARD">
-              <div class="CARD-HEAD"><h3>Geschichten</h3><a href="#">Alle</a></div>
+              <div class="CARD-HEAD"><h3>Geschichten</h3><a href="/geschichten">Alle</a></div>
               <div class="STORY-ROW"><div class="STORY-TITLE">Die Reise nach Berlin</div><div class="STORY-EXCERPT">Im Frühjahr 1921 bestieg Ernst Raddatz erstmals den Zug nach Berlin, um Arbeit in der aufstrebenden Metropole zu finden …</div><div class="STORY-META">vor 3 Tagen</div></div>
               <div class="STORY-ROW"><div class="STORY-TITLE">Sommer 1934 in Köln</div><div class="STORY-EXCERPT">Die Sommerferien 1934 verbrachte die Familie Raddatz bei Verwandten in Köln — die letzte unbeschwerte Reise vor dem Krieg …</div><div class="STORY-META">vor 2 Wochen</div></div>
             </div>
@@ -609,9 +644,9 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
             </div>
             <div class="DIVIDER DK-DIVIDER"></div>
             <div class="HEADER-STATS">
-              <div class="HSTAT DK-HSTAT"><a href="#"><span class="HSTAT-NUM DK-HSTAT-NUM">847</span><span class="HSTAT-LABEL DK-HSTAT-LABEL">Dokumente</span></a></div>
-              <div class="HSTAT DK-HSTAT"><a href="#"><span class="HSTAT-NUM DK-HSTAT-NUM">94</span><span class="HSTAT-LABEL DK-HSTAT-LABEL">Personen</span></a></div>
-              <div class="HSTAT DK-HSTAT"><a href="#"><span class="HSTAT-NUM DK-HSTAT-NUM">12</span><span class="HSTAT-LABEL DK-HSTAT-LABEL">Geschichten</span></a></div>
+              <div class="HSTAT DK-HSTAT"><a href="/documents"><span class="HSTAT-NUM DK-HSTAT-NUM">847</span><span class="HSTAT-LABEL DK-HSTAT-LABEL">Dokumente</span></a></div>
+              <div class="HSTAT DK-HSTAT"><a href="/persons"><span class="HSTAT-NUM DK-HSTAT-NUM">94</span><span class="HSTAT-LABEL DK-HSTAT-LABEL">Personen</span></a></div>
+              <div class="HSTAT DK-HSTAT"><a href="/geschichten"><span class="HSTAT-NUM DK-HSTAT-NUM">12</span><span class="HSTAT-LABEL DK-HSTAT-LABEL">Geschichten</span></a></div>
             </div>
           </div>
 
@@ -638,12 +673,12 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
                 <div class="PCARD-COUNT DK-PCARD-COUNT">19 Dok.</div>
               </a>
             </div>
-            <div class="PERSONS-FOOTER"><a class="PERSONS-ALL DK-PERSONS-ALL" href="#">Alle 94 Personen →</a></div>
+            <div class="PERSONS-FOOTER"><a class="PERSONS-ALL DK-PERSONS-ALL" href="/persons">Alle 94 Personen →</a></div>
           </div>
 
           <div class="CONTENT-ROW">
             <div class="CARD DK-CARD">
-              <div class="CARD-HEAD DK-CARD-HEAD"><h3>Zuletzt aktualisiert</h3><a href="#">Alle Dokumente</a></div>
+              <div class="CARD-HEAD DK-CARD-HEAD"><h3>Zuletzt aktualisiert</h3><a href="/documents">Alle Dokumente</a></div>
               <div class="DOC-ROW DK-DOC-ROW">
                 <div class="DOC-THUMB DK-DOC-THUMB"><svg width="8" height="10" viewBox="0 0 20 26" fill="none" stroke="#4A5880" stroke-width="1.5"><path d="M3 1h9l5 5v19H3V1z"/><polyline points="12 1 12 6 18 6"/></svg></div>
                 <div class="DOC-INFO"><div class="DOC-TITLE DK-DOC-TITLE">Brief von Ernst an Käthe, März 1923</div><div class="DOC-SENDER DK-DOC-SENDER">von <a href="#">Käthe Raddatz</a></div></div>
@@ -651,7 +686,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
               </div>
               <div class="DOC-ROW DK-DOC-ROW">
                 <div class="DOC-THUMB DK-DOC-THUMB"><svg width="8" height="10" viewBox="0 0 20 26" fill="none" stroke="#4A5880" stroke-width="1.5"><path d="M3 1h9l5 5v19H3V1z"/><polyline points="12 1 12 6 18 6"/></svg></div>
-                <div class="DOC-INFO"><div class="DOC-TITLE DK-DOC-TITLE">Heiratsurkunde Raddatz-Müller, 1898</div><div class="DOC-SENDER DK-DOC-SENDER" style="color:#262E48">—</div></div>
+                <div class="DOC-INFO"><div class="DOC-TITLE DK-DOC-TITLE">Heiratsurkunde Raddatz-Müller, 1898</div><div class="DOC-SENDER DK-DOC-SENDER" style="color:#5A6888">—</div></div>
                 <div class="DOC-DATE DK-DOC-DATE">vor 4 Tagen</div>
               </div>
               <div class="DOC-ROW DK-DOC-ROW">
@@ -661,7 +696,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
               </div>
               <div class="DOC-ROW DK-DOC-ROW">
                 <div class="DOC-THUMB DK-DOC-THUMB"><svg width="8" height="10" viewBox="0 0 20 26" fill="none" stroke="#4A5880" stroke-width="1.5"><path d="M3 1h9l5 5v19H3V1z"/><polyline points="12 1 12 6 18 6"/></svg></div>
-                <div class="DOC-INFO"><div class="DOC-TITLE DK-DOC-TITLE">Taufregister Heinrich Weber, 1902</div><div class="DOC-SENDER DK-DOC-SENDER" style="color:#262E48">—</div></div>
+                <div class="DOC-INFO"><div class="DOC-TITLE DK-DOC-TITLE">Taufregister Heinrich Weber, 1902</div><div class="DOC-SENDER DK-DOC-SENDER" style="color:#5A6888">—</div></div>
                 <div class="DOC-DATE DK-DOC-DATE">vor 2 Wo.</div>
               </div>
               <div class="DOC-ROW DK-DOC-ROW">
@@ -671,7 +706,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
               </div>
             </div>
             <div class="CARD DK-CARD">
-              <div class="CARD-HEAD DK-CARD-HEAD"><h3>Geschichten</h3><a href="#">Alle Geschichten</a></div>
+              <div class="CARD-HEAD DK-CARD-HEAD"><h3>Geschichten</h3><a href="/geschichten">Alle Geschichten</a></div>
               <div class="STORY-ROW DK-STORY-ROW">
                 <div class="STORY-TITLE DK-STORY-TITLE">Die Reise nach Berlin</div>
                 <div class="STORY-EXCERPT DK-STORY-EXCERPT">Im Frühjahr 1921 bestieg Ernst Raddatz erstmals den Zug nach Berlin, um Arbeit in der aufstrebenden Metropole zu finden …</div>
@@ -713,11 +748,12 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
         </ul>
       </div>
       <div class="note">
-        <strong>Typografie-Token im Dark Mode</strong>
+        <strong>Typografie-Token im Dark Mode — WCAG AA</strong>
         <ul>
           <li>Primär-Text: <code>#D0CCC4</code> / <code>#C0BDB6</code> (warm, kein reines Weiß)</li>
-          <li>Beschriftungen (Labels): <code>#323850</code></li>
-          <li>Datum/Dim: <code>#262E48</code></li>
+          <li>Gedämpft (muted): <code>#7080A8</code> — Absender, Excerpts, Entwurfs-Meta (≥ 4.5:1)</li>
+          <li>Labels/Überschriften: <code>#6070A0</code> — HSTAT-Label, Card-Head h3 (≥ 4.5:1)</li>
+          <li>Dim: <code>#5A6888</code> — Datum-Felder (≥ 4.5:1)</li>
           <li>Mint: <code>#A6DAD8</code> — unverändert, auch im Dark Mode</li>
           <li>Mint-Pill Hintergrund: <code>rgba(166,218,216,.14)</code></li>
         </ul>
@@ -774,9 +810,9 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
                   <div class="M-HTIME">Guten Abend</div>
                   <div class="M-HNAME">Herzlich willkommen, Brigitte.</div>
                   <div class="M-HSTATS">
-                    <div class="M-HSTAT"><a href="#"><span class="M-HSTAT-NUM">847</span><span class="M-HSTAT-LBL">Dok.</span></a></div>
-                    <div class="M-HSTAT"><a href="#"><span class="M-HSTAT-NUM">94</span><span class="M-HSTAT-LBL">Pers.</span></a></div>
-                    <div class="M-HSTAT"><a href="#"><span class="M-HSTAT-NUM">12</span><span class="M-HSTAT-LBL">Gesch.</span></a></div>
+                    <div class="M-HSTAT"><a href="/documents"><span class="M-HSTAT-NUM">847</span><span class="M-HSTAT-LBL">Dok.</span></a></div>
+                    <div class="M-HSTAT"><a href="/persons"><span class="M-HSTAT-NUM">94</span><span class="M-HSTAT-LBL">Pers.</span></a></div>
+                    <div class="M-HSTAT"><a href="/geschichten"><span class="M-HSTAT-NUM">12</span><span class="M-HSTAT-LBL">Gesch.</span></a></div>
                   </div>
                 </div>
 
@@ -787,11 +823,11 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
                     <a class="M-PCARD" href="#"><div class="M-PAV" style="background:#3D5A7A">FM</div><div class="M-PNAME">Frieda Müller</div><div class="M-PCOUNT">28 Dok.</div></a>
                     <a class="M-PCARD" href="#"><div class="M-PAV" style="background:#4A7A5A">HW</div><div class="M-PNAME">Heinrich Weber</div><div class="M-PCOUNT">19 Dok.</div></a>
                   </div>
-                  <a class="M-PALL" href="#">Alle 94 Personen →</a>
+                  <a class="M-PALL" href="/persons">Alle 94 Personen →</a>
                 </div>
 
                 <div class="M-CARD">
-                  <div class="M-CARD-HEAD"><h3>Zuletzt aktualisiert</h3><a href="#">Alle</a></div>
+                  <div class="M-CARD-HEAD"><h3>Zuletzt aktualisiert</h3><a href="/documents">Alle</a></div>
                   <div class="M-DROW">
                     <div style="width:15px;height:18px;background:#ECEAE4;border:1px solid #E0DDD5;border-radius:2px;flex-shrink:0;display:flex;align-items:center;justify-content:center"><svg width="6" height="8" viewBox="0 0 20 26" fill="none" stroke="#C8C4BE" stroke-width="1.5"><path d="M3 1h9l5 5v19H3V1z"/><polyline points="12 1 12 6 18 6"/></svg></div>
                     <div class="M-DINFO"><div class="M-DTITLE">Brief von Ernst an Käthe, März 1923</div><div class="M-DSENDER">von Käthe Raddatz</div></div>
@@ -810,7 +846,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
                 </div>
 
                 <div class="M-CARD">
-                  <div class="M-CARD-HEAD"><h3>Geschichten</h3><a href="#">Alle</a></div>
+                  <div class="M-CARD-HEAD"><h3>Geschichten</h3><a href="/geschichten">Alle</a></div>
                   <div class="M-SROW">
                     <div class="M-STITLE">Die Reise nach Berlin</div>
                     <div class="M-SEXCERPT">Im Frühjahr 1921 bestieg Ernst Raddatz erstmals den Zug nach Berlin …</div>
@@ -857,9 +893,9 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
                   <div class="M-HTIME">Guten Morgen</div>
                   <div class="M-HNAME">Herzlich willkommen, Marcel.</div>
                   <div class="M-HSTATS">
-                    <div class="M-HSTAT"><a href="#"><span class="M-HSTAT-NUM">847</span><span class="M-HSTAT-LBL">Dok.</span></a></div>
-                    <div class="M-HSTAT"><a href="#"><span class="M-HSTAT-NUM">94</span><span class="M-HSTAT-LBL">Pers.</span></a></div>
-                    <div class="M-HSTAT"><a href="#"><span class="M-HSTAT-NUM">12</span><span class="M-HSTAT-LBL">Gesch.</span></a></div>
+                    <div class="M-HSTAT"><a href="/documents"><span class="M-HSTAT-NUM">847</span><span class="M-HSTAT-LBL">Dok.</span></a></div>
+                    <div class="M-HSTAT"><a href="/persons"><span class="M-HSTAT-NUM">94</span><span class="M-HSTAT-LBL">Pers.</span></a></div>
+                    <div class="M-HSTAT"><a href="/geschichten"><span class="M-HSTAT-NUM">12</span><span class="M-HSTAT-LBL">Gesch.</span></a></div>
                   </div>
                 </div>
 
@@ -882,11 +918,11 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
                     <a class="M-PCARD" href="#"><div class="M-PAV" style="background:#3D5A7A">FM</div><div class="M-PNAME">Frieda Müller</div><div class="M-PCOUNT">28 Dok.</div></a>
                     <a class="M-PCARD" href="#"><div class="M-PAV" style="background:#4A7A5A">HW</div><div class="M-PNAME">Heinrich Weber</div><div class="M-PCOUNT">19 Dok.</div></a>
                   </div>
-                  <a class="M-PALL" href="#">Alle 94 Personen →</a>
+                  <a class="M-PALL" href="/persons">Alle 94 Personen →</a>
                 </div>
 
                 <div class="M-CARD">
-                  <div class="M-CARD-HEAD"><h3>Zuletzt aktualisiert</h3><a href="#">Alle</a></div>
+                  <div class="M-CARD-HEAD"><h3>Zuletzt aktualisiert</h3><a href="/documents">Alle</a></div>
                   <div class="M-DROW">
                     <div style="width:15px;height:18px;background:#ECEAE4;border:1px solid #E0DDD5;border-radius:2px;flex-shrink:0;display:flex;align-items:center;justify-content:center"><svg width="6" height="8" viewBox="0 0 20 26" fill="none" stroke="#C8C4BE" stroke-width="1.5"><path d="M3 1h9l5 5v19H3V1z"/><polyline points="12 1 12 6 18 6"/></svg></div>
                     <div class="M-DINFO"><div class="M-DTITLE">Brief von Ernst an Käthe, März 1923</div><div class="M-DSENDER">von Käthe Raddatz</div></div>
@@ -900,7 +936,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
                 </div>
 
                 <div class="M-CARD">
-                  <div class="M-CARD-HEAD"><h3>Geschichten</h3><a href="#">Alle</a></div>
+                  <div class="M-CARD-HEAD"><h3>Geschichten</h3><a href="/geschichten">Alle</a></div>
                   <div class="M-SROW">
                     <div class="M-STITLE">Die Reise nach Berlin</div>
                     <div class="M-SEXCERPT">Im Frühjahr 1921 bestieg Ernst Raddatz erstmals den Zug nach Berlin …</div>
@@ -972,7 +1008,7 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
                   </div>
                   <div class="M-DROW dk">
                     <div style="width:15px;height:18px;background:#1E2638;border:1px solid rgba(255,255,255,.07);border-radius:2px;flex-shrink:0;display:flex;align-items:center;justify-content:center"><svg width="6" height="8" viewBox="0 0 20 26" fill="none" stroke="#4A5880" stroke-width="1.5"><path d="M3 1h9l5 5v19H3V1z"/><polyline points="12 1 12 6 18 6"/></svg></div>
-                    <div class="M-DINFO"><div class="M-DTITLE dk">Heiratsurkunde Raddatz-Müller, 1898</div><div class="M-DSENDER dk" style="color:#262E48">—</div></div>
+                    <div class="M-DINFO"><div class="M-DTITLE dk">Heiratsurkunde Raddatz-Müller, 1898</div><div class="M-DSENDER dk" style="color:#5A6888">—</div></div>
                     <div class="M-DDATE dk">vor 4 T.</div>
                   </div>
                   <div class="M-DROW dk">
@@ -1046,10 +1082,143 @@ body{font-family:'Helvetica Neue',Arial,sans-serif;background:#ECEAE4;color:#1A1
           <li>Avatare behalten ihre Farbe — Eigenfarbe, kein Token</li>
         </ul>
       </div>
+      <div class="ann-block">
+        <strong>Neue i18n-Schlüssel — messages/{de,en,es}.json</strong>
+        <ul>
+          <li><code>dashboard.greeting.morning</code> — „Guten Morgen" (vor 12:00)</li>
+          <li><code>dashboard.greeting.afternoon</code> — „Guten Tag" (12:00–18:00)</li>
+          <li><code>dashboard.greeting.evening</code> — „Guten Abend" (ab 18:00)</li>
+          <li><code>dashboard.welcome</code> — „Herzlich willkommen, {name}." (parametrisch)</li>
+          <li><code>dashboard.persons.viewAll</code> — „Alle {count} Personen →" (parametrisch)</li>
+          <li><code>dashboard.recentlyUpdated</code> — „Zuletzt aktualisiert"</li>
+          <li><code>dashboard.myDrafts</code> — „Meine Entwürfe"</li>
+          <li><code>dashboard.stat.documents</code> — „Dokumente" / mobil: „Dok."</li>
+          <li><code>dashboard.stat.persons</code> — „Personen" / mobil: „Pers."</li>
+          <li><code>dashboard.stat.stories</code> — „Geschichten" / mobil: „Gesch."</li>
+        </ul>
+      </div>
     </div>
   </div>
 </div>
 
+<!-- ══ IMPL-REF TABLE ══ -->
+<div class="impl-ref-section">
+  <div class="sec-h"><span class="sec-num" style="background:#4A6E8A">↗</span> Implementierungsreferenz — Tailwind-Klassen je Region</div>
+  <p style="font-size:11px;color:#888;margin-bottom:20px">Exakte Tailwind CSS 4-Klassen und Pixel-Werte für jeden UI-Bereich. <strong>Diese Werte gelten für die Implementierung</strong>, nicht die skalierten Mockup-Werte.</p>
+
+  <table class="impl-ref-table">
+    <thead>
+      <tr>
+        <th>Region</th>
+        <th>Tailwind-Klassen</th>
+        <th>Hinweise</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Seiten-Canvas</td>
+        <td><code>bg-canvas w-full</code></td>
+        <td class="note-cell">Vollbreite Viewport; Farbe: <code>--palette-sand</code> / <code>bg-canvas</code></td>
+      </tr>
+      <tr>
+        <td>Inhalts-Wrapper</td>
+        <td><code>max-w-7xl mx-auto px-8 py-8</code></td>
+        <td class="note-cell">1280 px max-width, 32 px padding allseitig</td>
+      </tr>
+      <tr>
+        <td>Header-Balken</td>
+        <td><code>bg-white border border-line rounded-sm px-4 py-3 flex items-center gap-4</code></td>
+        <td class="note-cell">Explizit <code>bg-white</code>, nicht <code>bg-surface</code> — weißer Hintergrund ist intentionell (B.1-Entscheidung)</td>
+      </tr>
+      <tr>
+        <td>Header: Gruß-Zeit</td>
+        <td><code>text-[6px] font-bold uppercase tracking-[.8px] text-[#C8B8A0]</code></td>
+        <td class="note-cell">Warm-beige, kein Design-Token — kandidiert für <code>--color-greeting-time</code></td>
+      </tr>
+      <tr>
+        <td>Header: Begrüßungsname</td>
+        <td><code>font-serif text-xl text-brand-navy</code></td>
+        <td class="note-cell">Georgia/Tinos; <code>text-xl</code> (20 px real)</td>
+      </tr>
+      <tr>
+        <td>Header: Trennlinie</td>
+        <td><code>w-px self-stretch bg-line flex-shrink-0</code></td>
+        <td class="note-cell">1 px vertikal; <code>--palette-line</code> = <code>#E8E4DF</code></td>
+      </tr>
+      <tr>
+        <td>Stat-Zahl</td>
+        <td><code>text-2xl font-black text-brand-navy leading-none block</code></td>
+        <td class="note-cell">Numerischer Wert; Block damit Label darunter sitzt</td>
+      </tr>
+      <tr>
+        <td>Stat-Label</td>
+        <td><code>text-[11px] font-bold uppercase tracking-[.8px] text-ink-3 block mt-0.5</code></td>
+        <td class="note-cell">Licht: <code>#706C68</code> (WCAG AA); Tailwind-Token <code>text-ink-3</code> TBD</td>
+      </tr>
+      <tr>
+        <td>Personen-Grid</td>
+        <td><code>grid grid-cols-4 gap-1.5</code></td>
+        <td class="note-cell">Mobile: <code>grid-cols-2</code> bei <code>sm:</code> (640 px)</td>
+      </tr>
+      <tr>
+        <td>Personen-Kachel</td>
+        <td><code>bg-surface border border-line rounded-sm p-2.5 flex flex-col items-center text-center gap-1.5 no-underline</code></td>
+        <td class="note-cell"><code>bg-surface</code> = <code>--palette-surface</code>; kein Bottom-Accent</td>
+      </tr>
+      <tr>
+        <td>Personen-Avatar</td>
+        <td><code>w-9 h-9 rounded-full flex items-center justify-center font-black text-white text-[9px] shadow-sm flex-shrink-0</code></td>
+        <td class="note-cell">34 px real ≈ <code>w-9</code> (36 px) — nächster Tailwind-Step; Avatar-Farbe per Person-Eigenfarbe</td>
+      </tr>
+      <tr>
+        <td>Mint-Pill Badge</td>
+        <td><code>text-[11px] font-bold text-brand-navy bg-[#D4F0EE] px-1.5 py-px rounded-full</code></td>
+        <td class="note-cell">Token-Kandidat: <code>--color-mint-pill</code> / <code>bg-mint-soft</code></td>
+      </tr>
+      <tr>
+        <td>„Alle N Personen →"</td>
+        <td><code>text-xs font-semibold text-[#4A6E8A] no-underline text-right block mt-1</code></td>
+        <td class="note-cell">Direkte Farbe (kein opacity-Trick) — WCAG AA auf <code>bg-canvas</code></td>
+      </tr>
+      <tr>
+        <td>Content-Card</td>
+        <td><code>bg-surface border border-line rounded-sm overflow-hidden flex flex-col</code></td>
+        <td class="note-cell">Gleiche Card-Sprache wie restliche App</td>
+      </tr>
+      <tr>
+        <td>Card-Kopfzeile</td>
+        <td><code>flex items-center justify-between px-3 py-1.5 border-b border-line</code></td>
+        <td class="note-cell">h3: <code>text-[11px] font-bold uppercase tracking-[.12em] text-ink-3</code></td>
+      </tr>
+      <tr>
+        <td>Dok.-Datum</td>
+        <td><code>text-[12px] text-ink-3 whitespace-nowrap flex-shrink-0</code></td>
+        <td class="note-cell">Licht: <code>#706C68</code> (WCAG AA); nicht <code>#C8C4BE</code></td>
+      </tr>
+      <tr>
+        <td>Story-Excerpt</td>
+        <td><code>text-xs text-ink-2 leading-relaxed line-clamp-2</code></td>
+        <td class="note-cell">2 Zeilen max via Tailwind <code>line-clamp-2</code></td>
+      </tr>
+      <tr>
+        <td>Story-Meta</td>
+        <td><code>text-[11px] text-ink-3</code></td>
+        <td class="note-cell">Licht: <code>#706C68</code> (WCAG AA)</td>
+      </tr>
+      <tr>
+        <td>Entwürfe-Card</td>
+        <td><code>bg-surface border border-line border-l-[3px] border-l-brand-mint rounded-sm overflow-hidden</code></td>
+        <td class="note-cell">Mint Left-Border als visueller Anker für BLOG_WRITE-Zone</td>
+      </tr>
+      <tr>
+        <td>Dark Mode</td>
+        <td><code>dark:bg-surface dark:border-white/8 dark:text-ink</code> (via Tailwind <code>dark:</code>)</td>
+        <td class="note-cell">Nicht <code>!important</code>-Overrides aus Spec — spec-DK- Klassen sind Annäherungen</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
 </div>
 </body>
 </html>

frontend/.gitignore

@@ -36,6 +36,10 @@ src/lib/paraglide_bak*
 e2e/.auth/
 
 **/test-results/**
+**/test-results.locked/
+
+# Stale SvelteKit build artifacts
+**/.svelte-kit.old/
 
 # Proofshot browser verification artifacts
 proofshot-artifacts/

frontend/.svelte-kit.old/types/src/routes/.stammbaum-stale/$types.d.ts

@@ -1,24 +0,0 @@
-import type * as Kit from '@sveltejs/kit';
-
-type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
-type MatcherParam<M> = M extends (param : string) => param is (infer U extends string) ? U : string;
-type RouteParams = {  };
-type RouteId = '/stammbaum';
-type MaybeWithVoid<T> = {} extends T ? T | void : T;
-export type RequiredKeys<T> = { [K in keyof T]-?: {} extends { [P in K]: T[K] } ? never : K; }[keyof T];
-type OutputDataShape<T> = MaybeWithVoid<Omit<App.PageData, RequiredKeys<T>> & Partial<Pick<App.PageData, keyof T & keyof App.PageData>> & Record<string, any>>
-type EnsureDefined<T> = T extends null | undefined ? {} : T;
-type OptionalUnion<U extends Record<string, any>, A extends keyof U = U extends U ? keyof U : never> = U extends unknown ? { [P in Exclude<A, keyof U>]?: never } & U : never;
-export type Snapshot<T = any> = Kit.Snapshot<T>;
-type PageServerParentData = EnsureDefined<import('../$types.js').LayoutServerData>;
-type PageParentData = EnsureDefined<import('../$types.js').LayoutData>;
-
-export type PageServerLoad<OutputData extends OutputDataShape<PageServerParentData> = OutputDataShape<PageServerParentData>> = Kit.ServerLoad<RouteParams, PageServerParentData, OutputData, RouteId>;
-export type PageServerLoadEvent = Parameters<PageServerLoad>[0];
-export type ActionData = unknown;
-export type PageServerData = Expand<OptionalUnion<EnsureDefined<Kit.LoadProperties<Awaited<ReturnType<typeof import('../../../../../src/routes/stammbaum/+page.server.js').load>>>>>>;
-export type PageData = Expand<Omit<PageParentData, keyof PageServerData> & EnsureDefined<PageServerData>>;
-export type Action<OutputData extends Record<string, any> | void = Record<string, any> | void> = Kit.Action<RouteParams, OutputData, RouteId>
-export type Actions<OutputData extends Record<string, any> | void = Record<string, any> | void> = Kit.Actions<RouteParams, OutputData, RouteId>
-export type PageProps = { params: RouteParams; data: PageData; form: ActionData }
-export type RequestEvent = Kit.RequestEvent<RouteParams, RouteId>;

frontend/Dockerfile

@@ -1,15 +1,34 @@
-FROM node:20-alpine
+# syntax=docker/dockerfile:1.7
 
+# ── Development ──────────────────────────────────────────────────────────────
+# Used by docker-compose.yml (target: development). Source is bind-mounted in
+# dev so the COPY . below is effectively replaced at runtime; the layer still
+# exists so the image is self-contained for cold starts (e.g. devcontainer).
+FROM node:20.19.0-alpine3.21 AS development
 WORKDIR /app
-
-# Install dependencies as a separate layer so they are cached when only source changes
 COPY package.json package-lock.json ./
 RUN npm ci
-
-# Source is mounted at runtime via docker-compose volume
-# This COPY is only used when building without a volume (e.g. production image)
 COPY . .
-
 EXPOSE 5173
-
 CMD ["npm", "run", "dev"]
+
+# ── Build ────────────────────────────────────────────────────────────────────
+# Compiles the SvelteKit Node-adapter output to /app/build.
+FROM node:20.19.0-alpine3.21 AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# ── Production ───────────────────────────────────────────────────────────────
+# Self-contained Node server. `node build` is the adapter-node entrypoint.
+FROM node:20.19.0-alpine3.21 AS production
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=build /app/build ./build
+COPY --from=build /app/package.json ./package.json
+COPY --from=build /app/package-lock.json ./package-lock.json
+RUN npm ci --omit=dev
+EXPOSE 3000
+CMD ["node", "build"]

frontend/e2e/.auth/user.json

@@ -1,25 +0,0 @@
-{
-  "cookies": [
-    {
-      "name": "PARAGLIDE_LOCALE",
-      "value": "de",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1812352142.362504,
-      "httpOnly": false,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "auth_token",
-      "value": "Basic%20YWRtaW5AZmFtaWx5YXJjaGl2ZS5sb2NhbDphZG1pbjEyMw%3D%3D",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1777878542.943668,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Strict"
-    }
-  ],
-  "origins": []
-}

frontend/messages/de.json

@@ -448,6 +448,28 @@
 	"dashboard_recent_heading": "Zuletzt aktiv",
 	"dashboard_stats_documents": "Dokumente",
 	"dashboard_stats_persons": "Personen",
+	"dashboard_reader_stats_documents": "Dokumente",
+	"dashboard_reader_stats_persons": "Personen",
+	"dashboard_reader_stats_stories": "Geschichten",
+	"dashboard_reader_person_chips_heading": "Personen",
+	"dashboard_reader_no_persons": "Noch keine Personen im Archiv.",
+	"dashboard_reader_all_persons": "Alle Personen →",
+	"dashboard_reader_drafts_heading": "Meine Entwürfe",
+	"dashboard_reader_drafts_empty": "Keine Entwürfe",
+	"dashboard_reader_recent_docs_heading": "Zuletzt aktualisiert",
+	"dashboard_reader_recent_stories_heading": "Neue Geschichten",
+	"dashboard_badge_new": "Neu",
+	"dashboard_reader_all_stories": "Alle Geschichten →",
+	"dashboard_reader_doc_count_suffix": "Dok.",
+	"dashboard_all_documents": "Alle Dokumente",
+	"dashboard_greeting_time_morning": "Morgen",
+	"dashboard_greeting_time_afternoon": "Mittag",
+	"dashboard_greeting_time_evening": "Abend",
+	"dashboard_welcome": "Herzlich willkommen, {name}.",
+	"dashboard_reader_stats_documents_short": "Dok.",
+	"dashboard_reader_stats_persons_short": "Pers.",
+	"dashboard_reader_stats_stories_short": "Gesch.",
+	"dashboard_reader_draft_meta": "Entwurf · zuletzt bearbeitet {relative}",
 	"dashboard_resume_label": "Zuletzt geöffnet:",
 	"dashboard_resume_fallback": "Unbekanntes Dokument",
 	"doc_status_placeholder": "Platzhalter",
@@ -1045,5 +1067,12 @@
 	"relation_form_year_placeholder": "z.B. 1920",
 
 	"person_relationships_heading": "Beziehungen",
-	"person_relationships_empty": "Noch keine Beziehungen bekannt."
+	"person_relationships_empty": "Noch keine Beziehungen bekannt.",
+
+	"timeline_aria_label": "Zeitachse Dokumentdichte",
+	"timeline_clear_selection": "Auswahl zurücksetzen",
+	"timeline_zoom_reset": "Zurück zur Übersicht",
+	"timeline_bar_aria_singular": "{when}, 1 Dokument",
+	"timeline_bar_aria_plural": "{when}, {count} Dokumente",
+	"timeline_dragging_aria_live": "Zeitraum {from} bis {to} ausgewählt"
 }

frontend/messages/en.json

@@ -448,6 +448,28 @@
 	"dashboard_recent_heading": "Recent Activity",
 	"dashboard_stats_documents": "Documents",
 	"dashboard_stats_persons": "Persons",
+	"dashboard_reader_stats_documents": "Documents",
+	"dashboard_reader_stats_persons": "Persons",
+	"dashboard_reader_stats_stories": "Stories",
+	"dashboard_reader_person_chips_heading": "Persons",
+	"dashboard_reader_no_persons": "No persons in the archive yet.",
+	"dashboard_reader_all_persons": "All Persons →",
+	"dashboard_reader_drafts_heading": "My Drafts",
+	"dashboard_reader_drafts_empty": "No drafts",
+	"dashboard_reader_recent_docs_heading": "Recently Updated",
+	"dashboard_reader_recent_stories_heading": "New Stories",
+	"dashboard_badge_new": "New",
+	"dashboard_reader_all_stories": "All Stories →",
+	"dashboard_reader_doc_count_suffix": "docs.",
+	"dashboard_all_documents": "All Documents",
+	"dashboard_greeting_time_morning": "Morning",
+	"dashboard_greeting_time_afternoon": "Afternoon",
+	"dashboard_greeting_time_evening": "Evening",
+	"dashboard_welcome": "Welcome, {name}.",
+	"dashboard_reader_stats_documents_short": "Docs.",
+	"dashboard_reader_stats_persons_short": "Pers.",
+	"dashboard_reader_stats_stories_short": "Stor.",
+	"dashboard_reader_draft_meta": "Draft · last edited {relative}",
 	"dashboard_resume_label": "Last opened:",
 	"dashboard_resume_fallback": "Unknown document",
 	"doc_status_placeholder": "Placeholder",
@@ -1045,5 +1067,12 @@
 	"relation_form_year_placeholder": "e.g. 1920",
 
 	"person_relationships_heading": "Relationships",
-	"person_relationships_empty": "No relationships known yet."
+	"person_relationships_empty": "No relationships known yet.",
+
+	"timeline_aria_label": "Document density timeline",
+	"timeline_clear_selection": "Clear selection",
+	"timeline_zoom_reset": "Reset zoom",
+	"timeline_bar_aria_singular": "{when}, 1 document",
+	"timeline_bar_aria_plural": "{when}, {count} documents",
+	"timeline_dragging_aria_live": "Range {from} to {to} selected"
 }

frontend/messages/es.json

@@ -448,6 +448,28 @@
 	"dashboard_recent_heading": "Actividad reciente",
 	"dashboard_stats_documents": "Documentos",
 	"dashboard_stats_persons": "Personas",
+	"dashboard_reader_stats_documents": "Documentos",
+	"dashboard_reader_stats_persons": "Personas",
+	"dashboard_reader_stats_stories": "Historias",
+	"dashboard_reader_person_chips_heading": "Personas",
+	"dashboard_reader_no_persons": "Todavía no hay personas en el archivo.",
+	"dashboard_reader_all_persons": "Todas las personas →",
+	"dashboard_reader_drafts_heading": "Mis borradores",
+	"dashboard_reader_drafts_empty": "Sin borradores",
+	"dashboard_reader_recent_docs_heading": "Actualizados recientemente",
+	"dashboard_reader_recent_stories_heading": "Nuevas historias",
+	"dashboard_badge_new": "Nuevo",
+	"dashboard_reader_all_stories": "Todas las historias →",
+	"dashboard_reader_doc_count_suffix": "docs.",
+	"dashboard_all_documents": "Todos los documentos",
+	"dashboard_greeting_time_morning": "Mañana",
+	"dashboard_greeting_time_afternoon": "Tarde",
+	"dashboard_greeting_time_evening": "Noche",
+	"dashboard_welcome": "Bienvenido, {name}.",
+	"dashboard_reader_stats_documents_short": "Docs.",
+	"dashboard_reader_stats_persons_short": "Pers.",
+	"dashboard_reader_stats_stories_short": "Hist.",
+	"dashboard_reader_draft_meta": "Borrador · editado hace {relative}",
 	"dashboard_resume_label": "Último abierto:",
 	"dashboard_resume_fallback": "Documento desconocido",
 	"doc_status_placeholder": "Marcador",
@@ -1045,5 +1067,12 @@
 	"relation_form_year_placeholder": "ej. 1920",
 
 	"person_relationships_heading": "Relaciones",
-	"person_relationships_empty": "Aún no se conocen relaciones."
+	"person_relationships_empty": "Aún no se conocen relaciones.",
+
+	"timeline_aria_label": "Cronología de densidad de documentos",
+	"timeline_clear_selection": "Borrar selección",
+	"timeline_zoom_reset": "Restablecer zoom",
+	"timeline_bar_aria_singular": "{when}, 1 documento",
+	"timeline_bar_aria_plural": "{when}, {count} documentos",
+	"timeline_dragging_aria_live": "Rango {from} a {to} seleccionado"
 }

frontend/package-lock.json

@@ -31,6 +31,7 @@
 				"@types/diff": "^7.0.2",
 				"@types/node": "^24",
 				"@vitest/browser-playwright": "^4.0.10",
+				"@vitest/coverage-istanbul": "^4.1.0",
 				"@vitest/coverage-v8": "^4.1.0",
 				"eslint": "^9.39.1",
 				"eslint-config-prettier": "^10.1.8",
@@ -129,6 +130,153 @@
 				"node": ">=6.9.0"
 			}
 		},
+		"node_modules/@babel/compat-data": {
+			"version": "7.29.3",
+			"resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.3.tgz",
+			"integrity": "sha512-LIVqM46zQWZhj17qA8wb4nW/ixr2y1Nw+r1etiAWgRM6U1IqP+LNhL1yg440jYZR72jCWcWbLWzIosH+uP1fqg==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
+		"node_modules/@babel/core": {
+			"version": "7.29.0",
+			"resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.0.tgz",
+			"integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/code-frame": "^7.29.0",
+				"@babel/generator": "^7.29.0",
+				"@babel/helper-compilation-targets": "^7.28.6",
+				"@babel/helper-module-transforms": "^7.28.6",
+				"@babel/helpers": "^7.28.6",
+				"@babel/parser": "^7.29.0",
+				"@babel/template": "^7.28.6",
+				"@babel/traverse": "^7.29.0",
+				"@babel/types": "^7.29.0",
+				"@jridgewell/remapping": "^2.3.5",
+				"convert-source-map": "^2.0.0",
+				"debug": "^4.1.0",
+				"gensync": "^1.0.0-beta.2",
+				"json5": "^2.2.3",
+				"semver": "^6.3.1"
+			},
+			"engines": {
+				"node": ">=6.9.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/babel"
+			}
+		},
+		"node_modules/@babel/core/node_modules/semver": {
+			"version": "6.3.1",
+			"resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+			"integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+			"dev": true,
+			"license": "ISC",
+			"bin": {
+				"semver": "bin/semver.js"
+			}
+		},
+		"node_modules/@babel/generator": {
+			"version": "7.29.1",
+			"resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.29.1.tgz",
+			"integrity": "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/parser": "^7.29.0",
+				"@babel/types": "^7.29.0",
+				"@jridgewell/gen-mapping": "^0.3.12",
+				"@jridgewell/trace-mapping": "^0.3.28",
+				"jsesc": "^3.0.2"
+			},
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
+		"node_modules/@babel/helper-compilation-targets": {
+			"version": "7.28.6",
+			"resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.28.6.tgz",
+			"integrity": "sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/compat-data": "^7.28.6",
+				"@babel/helper-validator-option": "^7.27.1",
+				"browserslist": "^4.24.0",
+				"lru-cache": "^5.1.1",
+				"semver": "^6.3.1"
+			},
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
+		"node_modules/@babel/helper-compilation-targets/node_modules/lru-cache": {
+			"version": "5.1.1",
+			"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz",
+			"integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==",
+			"dev": true,
+			"license": "ISC",
+			"dependencies": {
+				"yallist": "^3.0.2"
+			}
+		},
+		"node_modules/@babel/helper-compilation-targets/node_modules/semver": {
+			"version": "6.3.1",
+			"resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+			"integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+			"dev": true,
+			"license": "ISC",
+			"bin": {
+				"semver": "bin/semver.js"
+			}
+		},
+		"node_modules/@babel/helper-globals": {
+			"version": "7.28.0",
+			"resolved": "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.28.0.tgz",
+			"integrity": "sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
+		"node_modules/@babel/helper-module-imports": {
+			"version": "7.28.6",
+			"resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.28.6.tgz",
+			"integrity": "sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/traverse": "^7.28.6",
+				"@babel/types": "^7.28.6"
+			},
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
+		"node_modules/@babel/helper-module-transforms": {
+			"version": "7.28.6",
+			"resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz",
+			"integrity": "sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/helper-module-imports": "^7.28.6",
+				"@babel/helper-validator-identifier": "^7.28.5",
+				"@babel/traverse": "^7.28.6"
+			},
+			"engines": {
+				"node": ">=6.9.0"
+			},
+			"peerDependencies": {
+				"@babel/core": "^7.0.0"
+			}
+		},
 		"node_modules/@babel/helper-string-parser": {
 			"version": "7.27.1",
 			"resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
@@ -149,6 +297,30 @@
 				"node": ">=6.9.0"
 			}
 		},
+		"node_modules/@babel/helper-validator-option": {
+			"version": "7.27.1",
+			"resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.27.1.tgz",
+			"integrity": "sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
+		"node_modules/@babel/helpers": {
+			"version": "7.29.2",
+			"resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.29.2.tgz",
+			"integrity": "sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/template": "^7.28.6",
+				"@babel/types": "^7.29.0"
+			},
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
 		"node_modules/@babel/parser": {
 			"version": "7.29.2",
 			"resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.2.tgz",
@@ -165,6 +337,40 @@
 				"node": ">=6.0.0"
 			}
 		},
+		"node_modules/@babel/template": {
+			"version": "7.28.6",
+			"resolved": "https://registry.npmjs.org/@babel/template/-/template-7.28.6.tgz",
+			"integrity": "sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/code-frame": "^7.28.6",
+				"@babel/parser": "^7.28.6",
+				"@babel/types": "^7.28.6"
+			},
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
+		"node_modules/@babel/traverse": {
+			"version": "7.29.0",
+			"resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.0.tgz",
+			"integrity": "sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/code-frame": "^7.29.0",
+				"@babel/generator": "^7.29.0",
+				"@babel/helper-globals": "^7.28.0",
+				"@babel/parser": "^7.29.0",
+				"@babel/template": "^7.28.6",
+				"@babel/types": "^7.29.0",
+				"debug": "^4.3.1"
+			},
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
 		"node_modules/@babel/types": {
 			"version": "7.29.0",
 			"resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz",
@@ -1128,6 +1334,16 @@
 				"node": ">=18.0.0"
 			}
 		},
+		"node_modules/@istanbuljs/schema": {
+			"version": "0.1.6",
+			"resolved": "https://registry.npmjs.org/@istanbuljs/schema/-/schema-0.1.6.tgz",
+			"integrity": "sha512-+Sg6GCR/wy1oSmQDFq4LQDAhm3ETKnorxN+y5nbLULOR3P0c14f2Wurzj3/xqPXtasLFfHd5iRFQ7AJt4KH2cw==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=8"
+			}
+		},
 		"node_modules/@jridgewell/gen-mapping": {
 			"version": "0.3.13",
 			"resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
@@ -3544,6 +3760,31 @@
 				}
 			}
 		},
+		"node_modules/@vitest/coverage-istanbul": {
+			"version": "4.1.0",
+			"resolved": "https://registry.npmjs.org/@vitest/coverage-istanbul/-/coverage-istanbul-4.1.0.tgz",
+			"integrity": "sha512-0+67gA94YToxd+Pc3XgIA/2c8HN2hXNSg3T+1FI4HW7W/2gPitYCtktsY6Ke7vrt5caboMq3TUf0/vwbHRb0og==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@babel/core": "^7.29.0",
+				"@istanbuljs/schema": "^0.1.3",
+				"@jridgewell/gen-mapping": "^0.3.13",
+				"@jridgewell/trace-mapping": "0.3.31",
+				"istanbul-lib-coverage": "^3.2.2",
+				"istanbul-lib-report": "^3.0.1",
+				"istanbul-reports": "^3.2.0",
+				"magicast": "^0.5.2",
+				"obug": "^2.1.1",
+				"tinyrainbow": "^3.0.3"
+			},
+			"funding": {
+				"url": "https://opencollective.com/vitest"
+			},
+			"peerDependencies": {
+				"vitest": "4.1.0"
+			}
+		},
 		"node_modules/@vitest/coverage-v8": {
 			"version": "4.1.0",
 			"resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.0.tgz",
@@ -3864,6 +4105,19 @@
 			"dev": true,
 			"license": "MIT"
 		},
+		"node_modules/baseline-browser-mapping": {
+			"version": "2.10.29",
+			"resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.29.tgz",
+			"integrity": "sha512-Asa2krT+XTPZINCS+2QcyS8WTkObE77RwkydwF7h6DmnKqbvlalz93m/dnphUyCa6SWSP51VgtEUf2FN+gelFQ==",
+			"dev": true,
+			"license": "Apache-2.0",
+			"bin": {
+				"baseline-browser-mapping": "dist/cli.cjs"
+			},
+			"engines": {
+				"node": ">=6.0.0"
+			}
+		},
 		"node_modules/bidi-js": {
 			"version": "1.0.3",
 			"resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.0.3.tgz",
@@ -3897,6 +4151,40 @@
 				"node": ">=8"
 			}
 		},
+		"node_modules/browserslist": {
+			"version": "4.28.2",
+			"resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.2.tgz",
+			"integrity": "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==",
+			"dev": true,
+			"funding": [
+				{
+					"type": "opencollective",
+					"url": "https://opencollective.com/browserslist"
+				},
+				{
+					"type": "tidelift",
+					"url": "https://tidelift.com/funding/github/npm/browserslist"
+				},
+				{
+					"type": "github",
+					"url": "https://github.com/sponsors/ai"
+				}
+			],
+			"license": "MIT",
+			"dependencies": {
+				"baseline-browser-mapping": "^2.10.12",
+				"caniuse-lite": "^1.0.30001782",
+				"electron-to-chromium": "^1.5.328",
+				"node-releases": "^2.0.36",
+				"update-browserslist-db": "^1.2.3"
+			},
+			"bin": {
+				"browserslist": "cli.js"
+			},
+			"engines": {
+				"node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
+			}
+		},
 		"node_modules/callsites": {
 			"version": "3.1.0",
 			"resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz",
@@ -3907,6 +4195,27 @@
 				"node": ">=6"
 			}
 		},
+		"node_modules/caniuse-lite": {
+			"version": "1.0.30001792",
+			"resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001792.tgz",
+			"integrity": "sha512-hVLMUZFgR4JJ6ACt1uEESvQN1/dBVqPAKY0hgrV70eN3391K6juAfTjKZLKvOMsx8PxA7gsY1/tLMMTcfFLLpw==",
+			"dev": true,
+			"funding": [
+				{
+					"type": "opencollective",
+					"url": "https://opencollective.com/browserslist"
+				},
+				{
+					"type": "tidelift",
+					"url": "https://tidelift.com/funding/github/npm/caniuse-lite"
+				},
+				{
+					"type": "github",
+					"url": "https://github.com/sponsors/ai"
+				}
+			],
+			"license": "CC-BY-4.0"
+		},
 		"node_modules/chai": {
 			"version": "6.2.2",
 			"resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
@@ -4204,6 +4513,13 @@
 				"@types/trusted-types": "^2.0.7"
 			}
 		},
+		"node_modules/electron-to-chromium": {
+			"version": "1.5.353",
+			"resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.353.tgz",
+			"integrity": "sha512-kOrWphBi8TOZyiJZqsgqIle0lw+tzmnQK83pV9dZUd01Nm2POECSyFQMAuarzZdYqQW7FH9RaYOuaRo3h+bQ3w==",
+			"dev": true,
+			"license": "ISC"
+		},
 		"node_modules/enhanced-resolve": {
 			"version": "5.20.0",
 			"resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.20.0.tgz",
@@ -4279,6 +4595,16 @@
 				"@esbuild/win32-x64": "0.27.4"
 			}
 		},
+		"node_modules/escalade": {
+			"version": "3.2.0",
+			"resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+			"integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=6"
+			}
+		},
 		"node_modules/escape-string-regexp": {
 			"version": "4.0.0",
 			"resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
@@ -4804,6 +5130,16 @@
 				"url": "https://github.com/sponsors/ljharb"
 			}
 		},
+		"node_modules/gensync": {
+			"version": "1.0.0-beta.2",
+			"resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz",
+			"integrity": "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
 		"node_modules/get-tsconfig": {
 			"version": "4.14.0",
 			"resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.14.0.tgz",
@@ -5216,6 +5552,19 @@
 				}
 			}
 		},
+		"node_modules/jsesc": {
+			"version": "3.1.0",
+			"resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
+			"integrity": "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==",
+			"dev": true,
+			"license": "MIT",
+			"bin": {
+				"jsesc": "bin/jsesc"
+			},
+			"engines": {
+				"node": ">=6"
+			}
+		},
 		"node_modules/json-buffer": {
 			"version": "3.0.1",
 			"resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz",
@@ -5804,6 +6153,13 @@
 			"license": "MIT",
 			"optional": true
 		},
+		"node_modules/node-releases": {
+			"version": "2.0.38",
+			"resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.38.tgz",
+			"integrity": "sha512-3qT/88Y3FbH/Kx4szpQQ4HzUbVrHPKTLVpVocKiLfoYvw9XSGOX2FmD2d6DrXbVYyAQTF2HeF6My8jmzx7/CRw==",
+			"dev": true,
+			"license": "MIT"
+		},
 		"node_modules/obug": {
 			"version": "2.1.1",
 			"resolved": "https://registry.npmjs.org/obug/-/obug-2.1.1.tgz",
@@ -7181,6 +7537,37 @@
 				"@unrs/resolver-binding-win32-x64-msvc": "1.11.1"
 			}
 		},
+		"node_modules/update-browserslist-db": {
+			"version": "1.2.3",
+			"resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
+			"integrity": "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==",
+			"dev": true,
+			"funding": [
+				{
+					"type": "opencollective",
+					"url": "https://opencollective.com/browserslist"
+				},
+				{
+					"type": "tidelift",
+					"url": "https://tidelift.com/funding/github/npm/browserslist"
+				},
+				{
+					"type": "github",
+					"url": "https://github.com/sponsors/ai"
+				}
+			],
+			"license": "MIT",
+			"dependencies": {
+				"escalade": "^3.2.0",
+				"picocolors": "^1.1.1"
+			},
+			"bin": {
+				"update-browserslist-db": "cli.js"
+			},
+			"peerDependencies": {
+				"browserslist": ">= 4.21.0"
+			}
+		},
 		"node_modules/uri-js": {
 			"version": "4.4.1",
 			"resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz",
@@ -7607,6 +7994,13 @@
 			"integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
 			"license": "MIT"
 		},
+		"node_modules/yallist": {
+			"version": "3.1.1",
+			"resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
+			"integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
+			"dev": true,
+			"license": "ISC"
+		},
 		"node_modules/yaml-ast-parser": {
 			"version": "0.0.43",
 			"resolved": "https://registry.npmjs.org/yaml-ast-parser/-/yaml-ast-parser-0.0.43.tgz",

frontend/package.json

@@ -15,7 +15,7 @@
 		"lint:boundary-demo": "eslint src/lib/tag/__fixtures__/",
 		"test:unit": "vitest",
 		"test": "npm run test:unit -- --run",
-		"test:coverage": "vitest run --coverage --project=server",
+		"test:coverage": "vitest run --coverage --project=server && vitest run -c vitest.client-coverage.config.ts --coverage",
 		"test:e2e": "playwright test",
 		"test:e2e:headed": "playwright test --headed",
 		"test:e2e:ui": "playwright test --ui",
@@ -45,6 +45,7 @@
 		"@types/diff": "^7.0.2",
 		"@types/node": "^24",
 		"@vitest/browser-playwright": "^4.0.10",
+		"@vitest/coverage-istanbul": "^4.1.0",
 		"@vitest/coverage-v8": "^4.1.0",
 		"eslint": "^9.39.1",
 		"eslint-config-prettier": "^10.1.8",

frontend/src/hooks.server.ts

@@ -5,7 +5,14 @@ import { env } from 'process';
 import { cookieName, cookieMaxAge } from '$lib/paraglide/runtime';
 import { detectLocale } from '$lib/shared/server/locale';
 
-const PUBLIC_PATHS = ['/login', '/logout', '/forgot-password', '/reset-password', '/register'];
+const PUBLIC_PATHS = [
+	'/login',
+	'/logout',
+	'/forgot-password',
+	'/reset-password',
+	'/register',
+	'/hilfe/transkription' // prerendered help page — must be reachable without an auth cookie
+];
 
 const handleLocaleDetection: Handle = ({ event, resolve }) => {
 	if (!event.cookies.get(cookieName)) {

frontend/src/lib/activity/ChronikErrorCard.svelte.spec.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
-import { page, userEvent } from 'vitest/browser';
+import { page } from 'vitest/browser';
 
 import ChronikErrorCard from './ChronikErrorCard.svelte';
 
@@ -10,7 +10,7 @@ describe('ChronikErrorCard', () => {
 	it('renders the default error message', async () => {
 		render(ChronikErrorCard, { onRetry: vi.fn() });
 		await expect
-			.element(page.getByText('Die Chronik konnte nicht geladen werden.'))
+			.element(page.getByText('Die Aktivitäten konnten nicht geladen werden.'))
 			.toBeInTheDocument();
 	});
 
@@ -27,7 +27,8 @@ describe('ChronikErrorCard', () => {
 	it('calls onRetry when the retry button is clicked', async () => {
 		const onRetry = vi.fn();
 		render(ChronikErrorCard, { onRetry });
-		await userEvent.click(page.getByText('Erneut versuchen'));
+		const btn = (await page.getByText('Erneut versuchen').element()) as HTMLElement;
+		btn.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
 		expect(onRetry).toHaveBeenCalledTimes(1);
 	});
 

frontend/src/lib/activity/ChronikRow.svelte

@@ -108,6 +108,11 @@ const rowHref: string = $derived(
 <a
 	href={rowHref}
 	data-variant={variant}
+	aria-label={variant === 'comment'
+		? item.commentPreview
+			? `${m.chronik_comment_added({ actor: actorName, doc: docTitle })} — ${item.commentPreview}`
+			: m.chronik_comment_added({ actor: actorName, doc: docTitle })
+		: undefined}
 	class="group flex items-start gap-3 p-3 transition-colors hover:bg-muted/50 focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:outline-none
 		{variant === 'for-you' ? 'border-l-[3px] border-accent bg-accent-bg/10' : ''}"
 >
@@ -159,20 +164,11 @@ const rowHref: string = $derived(
 		</p>
 
 		{#if variant === 'comment'}
-			<!--
-				TODO: the backend does not yet expose a comment body preview on
-				ActivityFeedItemDTO. Render an ellipsis placeholder until it does —
-				duplicating the document title here looks like the comment is
-				quoting itself (Leonie, PR #288 review).
-				SECURITY: once item.commentPreview lands, render via {text}, never
-				{@html}. The backend must truncate and strip tags server-side (Nora,
-				issue #285 comment #3552).
-			-->
 			<p
 				data-testid="chronik-comment-preview"
 				class="mt-1 line-clamp-1 font-serif text-sm text-ink-2 italic sm:line-clamp-2"
 			>
-				&bdquo;&hellip;&ldquo;
+				{item.commentPreview ?? '„…"'}
 			</p>
 		{/if}
 

frontend/src/lib/activity/ChronikRow.svelte.spec.ts

@@ -186,6 +186,61 @@ describe('ChronikRow', () => {
 		expect(link).not.toBeNull();
 	});
 
+	// --- commentPreview content ---
+	it('renders commentPreview text when variant is comment and commentPreview is present', async () => {
+		const item: ActivityFeedItemDTO = {
+			...baseItem,
+			kind: 'COMMENT_ADDED',
+			commentPreview: 'Hello family, great letter!'
+		};
+		render(ChronikRow, { item });
+		const preview = document.querySelector('[data-testid="chronik-comment-preview"]');
+		expect(preview).not.toBeNull();
+		expect(preview?.textContent).toContain('Hello family, great letter!');
+	});
+
+	it('renders placeholder ellipsis when variant is comment and commentPreview is null', async () => {
+		const item: ActivityFeedItemDTO = {
+			...baseItem,
+			kind: 'COMMENT_ADDED',
+			commentPreview: undefined
+		};
+		render(ChronikRow, { item });
+		const preview = document.querySelector('[data-testid="chronik-comment-preview"]');
+		expect(preview).not.toBeNull();
+		expect(preview?.textContent?.trim()).toBe('„…"');
+	});
+
+	it('does not render preview paragraph for non-comment variants', async () => {
+		const item: ActivityFeedItemDTO = { ...baseItem, kind: 'TEXT_SAVED' };
+		render(ChronikRow, { item });
+		expect(document.querySelector('[data-testid="chronik-comment-preview"]')).toBeNull();
+	});
+
+	it('link has aria-label containing preview text for comment variant with preview', async () => {
+		const item: ActivityFeedItemDTO = {
+			...baseItem,
+			kind: 'COMMENT_ADDED',
+			commentPreview: 'A wonderful letter from grandma'
+		};
+		render(ChronikRow, { item });
+		const link = document.querySelector('a[aria-label]');
+		expect(link).not.toBeNull();
+		expect(link?.getAttribute('aria-label')).toContain('A wonderful letter from grandma');
+	});
+
+	it('link still has aria-label for comment variant when commentPreview is absent', async () => {
+		const item: ActivityFeedItemDTO = {
+			...baseItem,
+			kind: 'COMMENT_ADDED',
+			commentPreview: undefined
+		};
+		render(ChronikRow, { item });
+		const link = document.querySelector('a[aria-label]');
+		expect(link).not.toBeNull();
+		expect(link?.getAttribute('aria-label')).not.toBeNull();
+	});
+
 	// --- robustness: title rendering for edge cases ---
 	it('still renders the row link when documentTitle is an empty string', async () => {
 		// Felix: verbText.indexOf(docTitle) returned 0 for empty titles — the span