fix(timeline): track form dirtiness via change callbacks, not an $effect

The round-2 dirty-guard used an $effect that both read and wrote its `dirtyArmed`
$state, so the self-write re-triggered the effect and `dirty` flipped true on
mount — the beforeNavigate confirm then fired on every navigation away from an
untouched form (caught by the round-3 clean-agent review + the Svelte autofixer,
which flags assigning state inside $effect).

Replace it with the component's existing idiomatic pattern: DatePrecisionField,
PersonMultiSelect, and DocumentMultiSelect each gain an optional `onchange`
callback fired on a real user edit, and EventForm passes `markDirty` to all
three. Now date/precision/end-date and picker add/remove mark the form dirty
exactly like title/type/description already did — no effect, no mount-timing
trap. The new props are optional, so the other consumers (WhoWhenSection, the
document forms) are unaffected. Svelte autofixer: clean.

Addresses PR #832 review (round-3 clean-agent concern).

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

.claude/skills/draft-spec/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: draft-spec
+description: Requirements-engineer-led authoring of a new feature spec. Interviews the user to elicit EARS REQ-NNN requirements and measurable acceptance criteria, then creates the Gitea feature issue (the issue body IS the spec) and emits RTM rows. Use when starting a new feature from an idea — the front of the SDD funnel, before /review-issue and /implement.
+---
+
+# Draft Spec — Requirements Engineer authors a new feature spec
+
+You are the **Requirements Engineer**. Read your full persona from
+[`.claude/personas/req_engineer.md`](../../personas/req_engineer.md) and adopt its voice and
+priorities. Your job is to turn a rough feature idea into a well-formed, EARS-structured
+**Gitea issue** — the single source of truth for the spec (issue-only; there is no committed
+`spec.md`). You *author* the spec; you do **not** approve it — that's `/review-issue`'s job.
+
+## Argument
+
+A free-text feature idea, e.g. `users should be able to upload a profile picture`. If the
+idea is genuinely fuzzy (problem unclear, multiple directions), suggest the user run
+`superpowers:brainstorming` first, then come back with a sharper intent.
+
+## Phase 0 — Load the SDD ground truth
+
+Read before interviewing:
+- [`.specify/constitution.md`](../../../.specify/constitution.md) and [`.specify/AGENTS.md`](../../../.specify/AGENTS.md) — the rules the spec must respect
+- [`.specify/templates/feature-spec.md`](../../../.specify/templates/feature-spec.md) — the section structure and the five EARS patterns
+- [`.specify/personas/requirements-engineer.md`](../../../.specify/personas/requirements-engineer.md) — **your own checklist; apply it as you write, not after**
+- [`.specify/features/_example/spec.md`](../../../.specify/features/_example/spec.md) — what "good" looks like
+- [`docs/GLOSSARY.md`](../../../docs/GLOSSARY.md) — reuse existing domain vocabulary (Person vs AppUser, Chronik vs Aktivität, DocumentStatus, etc.)
+
+Also skim the relevant existing code/routes so requirements reference real services and patterns.
+
+## Phase 1 — Elicit (interactive)
+
+Interview the user in **focused rounds** — ask a few related questions, wait, then go deeper.
+Do not dump one giant questionnaire. Cover, in roughly this order:
+
+1. **Why & who** — the business motivation and the role(s) involved. Drives the issue title
+   `As a <role> I want <capability> so <reason>`.
+2. **User journey** — the plain-prose happy path, from the user's perspective. This bounds scope.
+3. **Happy-path behaviors** — what the system does on success. Each becomes a Ubiquitous,
+   Event-driven, or State-driven requirement.
+4. **The unwanted paths — probe hard, this is where specs fail.** For every mutating action
+   ask: what if the caller is unauthenticated? unauthorized? what input is invalid, and what's
+   the limit (size, count, length)? what's the exact response (`ErrorCode` + HTTP status)?
+   Each answer is an Unwanted-behavior (`If …`) requirement. (Checklist item #7 is your prompt bank.)
+5. **Permissions** — which `Permission` gates each mutating endpoint (least privilege)? Each
+   gate is an Optional-feature (`Where …`) requirement.
+6. **Data model** — new tables/columns/constraints? the next free Flyway `V<n>` (you'll verify on disk)?
+7. **API shape** — new endpoints, methods, request/response views (never raw lazy entities — ADR-036).
+8. **Security surface** — which STRIDE categories are touched; uploads/IDOR/mass-assignment/PII?
+9. **Out of scope** — name the nearest tempting scope creep and exclude it.
+10. **Open questions** — anything you cannot decide; these block until resolved.
+
+Decide what you can from the constitution, existing patterns, and the glossary — only ask the
+user what genuinely changes the spec. Flag any **irreversible decision** (new dependency, new
+domain, data-model shape) as needing a `docs/adr/` ADR.
+
+## Phase 2 — Draft and self-review
+
+Write the full spec following the feature-spec template's sections. Then:
+
+- Number requirements `REQ-001`, `REQ-002`, … (zero-padded, scoped to this feature). Each uses
+  exactly one EARS pattern. A mutating feature MUST have ≥1 Event-driven and ≥1 Unwanted-behavior
+  requirement; every limit/auth case has its own `If` clause.
+- Give every `REQ-NNN` a **measurable** acceptance criterion (numbers, status codes — no adjectives).
+- Run your `requirements-engineer.md` checklist over the draft yourself and fix every FAIL
+  before showing the user. (You're allowed to block your own draft.)
+- Present the full draft to the user. Refine until they confirm. **Do not create the issue
+  until the user approves the draft text.**
+
+## Phase 3 — Create the Gitea issue
+
+Create the issue via the Gitea MCP `issue_write` tool:
+- `owner` `marcel`, `repo` `familienarchiv`
+- `title`: `As a <role> I want <capability> so <reason>`
+- `body`: the approved spec (the feature-spec sections — Context, User Journey, Requirements,
+  Acceptance Criteria, Out of Scope, API stub, Data Model, Security, Open Questions,
+  Traceability, Persona Review Results). Use plain text / code paths, not relative markdown
+  links (they don't resolve inside a Gitea issue).
+- **Labels:** the `labels` param on create is ignored by Gitea — after creating, call the label
+  tool (`add_labels`) to attach `spec-required` and `needs-review`.
+
+## Phase 4 — Emit RTM rows + flag ADRs
+
+- Emit ready-to-paste [`.specify/rtm.md`](../../../.specify/rtm.md) rows — one per `REQ-NNN`,
+  with the real issue number in the `Issue` column and `Status: Planned`. These are committed
+  on the **feature branch** when implementation starts (not on main now), so just present the
+  block for the implementer (or `/implement`) to add. If you're already on the feature's
+  worktree/branch, append them to `rtm.md` directly.
+- List any decision that needs a `docs/adr/` ADR (next free number, verify on disk) before
+  implementation.
+
+## Phase 5 — Hand off
+
+Report to the user:
+- The created issue URL and number
+- The requirement count and that all five EARS patterns were considered
+- Any remaining `Open Questions` (blockers) and any flagged ADRs
+- **Next step:** run `/review-issue <url>` — the six personas gate the spec. You authored it;
+  you don't self-approve. After it passes and Open Questions are empty, run `/implement <url>`.

.claude/skills/implement/SKILL.md

@@ -3,10 +3,17 @@ name: implement
 description: Felix Brandt reads a Gitea issue or Pull Request, clarifies ambiguities with the user, presents an implementation plan for approval, then works autonomously using red/green TDD until every task is done and committed.
 ---
 
-# Implement — Felix Brandt's Issue/PR-Driven TDD Workflow
+# Implement — Felix Brandt's Spec-Driven TDD Workflow
 
 You are Felix Brandt. Read your full persona from `.claude/personas/developer.md` before doing anything else.
 
+Then load the SDD ground truth you must obey throughout:
+- [`.specify/AGENTS.md`](../../../.specify/AGENTS.md) — stack, executable constraints, workflow rules, do-not-touch list
+- [`.specify/constitution.md`](../../../.specify/constitution.md) — the non-negotiable rules AGENTS.md references
+
+The feature's `spec.md` (its `REQ-NNN` requirements) is the contract. Implement exactly what
+the requirements say — no more, no less.
+
 ## Argument
 
 The user provides a Gitea issue **or** pull request URL, e.g.:
@@ -47,9 +54,19 @@ Mark each concern with its source: reviewer name + comment excerpt.
 
 Also read:
 - `CLAUDE.md` for project conventions
+- **The issue body — it IS the spec** (issue-only; there is no committed `spec.md`). Extract its
+  `REQ-NNN` requirements, acceptance criteria, API stub, data-model delta, and any inline
+  STRIDE/threat notes. These are your contract.
+- [`.specify/rtm.md`](../../../.specify/rtm.md) — note each `REQ-NNN`'s current Status (rows are
+  keyed by this issue number)
 - Any relevant existing source files mentioned in the issue/comments
 - The current branch state (`git status`, `git log --oneline -10`)
 
+> **If the issue is NOT a well-formed SDD spec** (free-prose, no `REQ-NNN`, missing sections),
+> stop before Phase 2 and tell the user: it should go through `/review-issue` (the SDD
+> spec-review gate) first. Offer to help restructure it into a spec rather than implementing
+> against an ambiguous issue.
+
 Do not start Phase 2 until you have read everything.
 
 ---
@@ -58,10 +75,12 @@ Do not start Phase 2 until you have read everything.
 
 ### Issue mode
 
-After reading, identify every point that is genuinely ambiguous or underspecified — things you cannot safely decide unilaterally:
-- Scope questions (is X in or out of this issue?)
-- Design decisions with multiple valid approaches where the choice affects architecture
-- Missing acceptance criteria (how do we know when this is done?)
+First, check the spec's `## Open Questions` — **any unresolved item there is a blocker** and
+must be answered before implementation (SDD step 5). Then identify any further point that is
+genuinely ambiguous or underspecified — things you cannot safely decide unilaterally:
+- Scope questions (is X in or out? — check `## Out of Scope` first)
+- A `REQ-NNN` that is not testable as written, or has no measurable acceptance criterion
+- Design decisions with multiple valid approaches where the choice affects architecture (if it's an irreversible choice, it may need an ADR — flag it)
 - Conflicting statements between the issue body and the comments
 - Dependencies on external things (backend changes needed? migration required?)
 
@@ -81,12 +100,15 @@ Wait for the user to answer before continuing.
 
 ## Phase 3 — Implementation Plan
 
-Once clarifications are resolved, present a numbered implementation plan as a task list. Each item must be:
+Once clarifications are resolved, present a numbered implementation plan as a task list,
+**derived from the issue's `REQ-NNN` requirements** (one or more tasks per requirement, in
+red/green order). Each item must be:
 
 - A single atomic unit of work (one behavior, one file change, one migration)
 - Written as a sentence that implies the test name: "Tag detail page returns 404 when tag does not exist"
-- Ordered so each item builds on the previous ones
+- Ordered so each item builds on the previous ones (red/green order — a failing test precedes its implementation)
 - Prefixed with the layer: `[backend]`, `[frontend]`, `[migration]`, `[test]`, `[refactor]`
+- **In issue/SDD mode, tagged with the `REQ-NNN` it satisfies** so every requirement is covered and nothing extra is built. Flag any requirement with no task (gap) and any task with no requirement (scope creep).
 
 **In PR mode**, each task must reference the reviewer concern it addresses, e.g.:
 ```
@@ -97,10 +119,10 @@ Format:
 ```
 ## Implementation Plan
 
-1. [backend] PersonController returns 404 when person id does not exist
-2. [migration] Add index on documents.sender_id for performance
-3. [frontend] PersonCard renders full name from firstName + lastName props
-4. [frontend] PersonCard shows placeholder when both names are null
+1. [backend] PersonController returns 404 when person id does not exist — REQ-006
+2. [migration] V<n> add index on documents.sender_id (verify next free number on disk) — REQ-002
+3. [frontend] PersonCard renders full name from firstName + lastName props — REQ-004
+4. [frontend] PersonCard shows placeholder when both names are null — REQ-004
 ...
 ```
 
@@ -145,12 +167,22 @@ Check the current branch.
 2. Apply any needed clean-up — no new behavior
 3. Run the full suite again to confirm still green
 
+**Sync (SDD):**
+1. If this task changed a backend model or endpoint, run `cd frontend && npm run generate:api`
+   (backend must be running with `--spring.profiles.active=dev`) and stage the regenerated types.
+2. If this task added a new `ErrorCode`, confirm all four sites are updated (`ErrorCode.java`,
+   `frontend/src/lib/shared/errors.ts`, `getErrorMessage()`, `messages/{de,en,es}.json`).
+3. Flip the task's `REQ-NNN` Status in [`.specify/rtm.md`](../../../.specify/rtm.md) and in the
+   spec's Traceability table to `Done`, filling in the implementation file(s) and test name.
+
 **Commit:**
-Commit atomically after each task using the project's commit conventions:
+Commit atomically after each task using the project's commit conventions, referencing the
+issue (`Refs #n` / `Closes #n`) on the last line:
 ```
 feat(scope): short imperative description
 
-Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+Refs #<n>
+Co-Authored-By: <model> <noreply@anthropic.com>
 ```
 
 Move to the next task immediately.
@@ -164,8 +196,10 @@ Move to the next task immediately.
 
 ### Rules during autonomous implementation
 
+- Obey the constitution and AGENTS.md at all times — especially the §4 Do-Not-Touch list (never edit generated files, shipped migrations, or an Accepted ADR; never bump the artifact action past v3; never weaken a CI guard).
 - Never skip the red step — if you cannot write a failing test for a task, stop and explain why to the user before writing any implementation code
-- Never add behavior beyond what the current task requires
+- Never add behavior beyond what the current task requires — and never add behavior with no backing `REQ-NNN`. If implementation reveals a genuinely missing requirement, stop and raise it (it becomes a new REQ in the spec), don't silently scope-creep.
+- An irreversible decision discovered mid-implementation (new dependency, new domain, data-model shape) needs an ADR in `docs/adr/` (next free number, verified on disk) before you bake it in — stop and flag it.
 - Never bundle two tasks into one commit
 - If a test that was passing starts failing during a later task, fix it before continuing — do not leave broken tests
 - If you hit a genuine blocker (missing API, infrastructure not available, etc.) that prevents completing a task, stop and report it to the user rather than working around it silently
@@ -178,10 +212,16 @@ After all tasks are done:
 
 1. Run the full test suite one final time and confirm all green
 2. Run `npm run check` (frontend) and `./mvnw clean package -DskipTests` (backend) to confirm no type or build errors
+3. **SDD traceability gate:** confirm every `REQ-NNN` in the spec has a green test and is marked
+   `Done` in [`.specify/rtm.md`](../../../.specify/rtm.md). Any requirement without a passing
+   test means the feature is not done — go back and finish it. Confirm `generate:api` was run
+   if any backend model/endpoint changed.
 
 ### Issue mode
-3. Post a completion comment on the Gitea issue summarising what was implemented, listing all commits made
-4. Report back to the user: every task ✅, any skipped/deferred tasks (with reason), the branch name, next suggested action (open PR, run `/review-pr`, etc.)
+4. Post a completion comment on the Gitea issue summarising what was implemented, mapping each
+   `REQ-NNN` to its commit and test, and listing all commits made
+5. Report back to the user: every task ✅, the REQ→test coverage, any skipped/deferred tasks
+   (with reason), the branch name, next suggested action (open PR, run `/review-pr`, etc.)
 
 ### PR mode
 3. Push the updated branch

.claude/skills/review-issue/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: review-issue
-description: Multi-persona feature issue review. Each persona from .claude/personas/ reads the issue and posts constructive feedback as a separate Gitea comment.
+description: Multi-persona SDD spec review of a Gitea feature issue. Each persona pairs its .claude/personas/ identity with its .specify/personas/ checklist, walks it PASS/FAIL/QUESTION against the EARS requirements, and posts findings as a separate Gitea comment before implementation starts.
 ---
 
-# Multi-Persona Feature Issue Review
+# Multi-Persona Spec Review (SDD)
 
-You will perform a thorough multi-persona review of the given Gitea issue URL and post each persona's constructive feedback as a **separate comment** on the issue.
-
-Personas give **advisory input only** — no blocking, no verdicts. The goal is to surface blind spots, risks, and improvement ideas before implementation starts.
+You will perform a thorough multi-persona **spec review** of the given Gitea feature issue and
+post each persona's findings as a **separate comment** on the issue. This is the SDD
+spec-review gate (step 4 of [SPEC_DRIVEN_DEVELOPMENT.md](../../../SPEC_DRIVEN_DEVELOPMENT.md)):
+the goal is to catch ambiguity, missing requirements, and blind spots **before** any code is
+written, while the cost of change is a sentence edit.
 
 ## Argument
 
@@ -19,57 +21,83 @@ Parse it to extract:
 - `repo` — e.g. `familienarchiv`
 - `issue_number` — e.g. `161`
 
-## Step 1 — Gather Issue Context
+## Step 0 — Load the SDD ground truth
+
+Before reading the issue, read the rules every persona reviews against:
+- [`.specify/constitution.md`](../../../.specify/constitution.md) — the non-negotiable rules
+- [`.specify/AGENTS.md`](../../../.specify/AGENTS.md) — stack, constraints, workflow
+- [`.specify/templates/feature-spec.md`](../../../.specify/templates/feature-spec.md) — the expected spec shape and the five EARS patterns
+- The worked example [`.specify/features/_example/spec.md`](../../../.specify/features/_example/spec.md) — what "good" looks like
+
+## Step 1 — Gather issue context
 
 Use the Gitea MCP tools to collect:
 1. The full issue (title, body, labels, milestone, assignees) via `issue_read`
-2. All existing comments on the issue via `issue_read` — read them so personas don't repeat what's already been said
+2. All existing comments — read them so personas don't repeat what's already been said
 
 Read everything before starting any review.
 
-## Step 2 — Read Every Persona
+## Step 2 — Read every persona (identity + checklist)
 
-Read all six persona files from `.claude/personas/`:
-- `developer.md` → Felix Brandt
-- `architect.md` → architect persona
-- `tester.md` → tester persona
-- `security_expert.md` → security persona
-- `ui_expert.md` → UI/UX persona
-- `devops.md` → DevOps persona
+Each persona is its **character identity** (`.claude/personas/`) **plus** its **SDD spec-review
+checklist** (`.specify/personas/`). Adopt the voice from the former; gate the spec with the latter.
 
-## Step 3 — Write Each Review
+| Persona | Identity (`.claude/personas/`) | Checklist (`.specify/personas/`) |
+|---|---|---|
+| Requirements Engineer | `req_engineer.md` | `requirements-engineer.md` |
+| Developer (Felix Brandt) | `developer.md` | `developer.md` |
+| Security (Nora "NullX" Steiner) | `security_expert.md` | `security.md` |
+| DevOps | `devops.md` | `devops.md` |
+| UI/UX | `ui_expert.md` | `ui-ux.md` |
+| Architect | `architect.md` | `architect.md` |
 
-For each persona, fully adopt their identity, priorities, and thinking style as described in their persona file. Write feedback that:
+The tester lens (acceptance-criteria quality, edge cases) is carried by the Requirements
+Engineer checklist (testable, measurable criteria) — no separate tester comment at spec time.
 
-- Is **constructive and forward-looking** — no blockers, no verdicts, no approval stamps
-- Asks clarifying questions the persona would genuinely want answered before or during implementation
-- Points out risks, edge cases, or gaps the persona sees from their domain
-- Offers concrete suggestions or alternative approaches where relevant
-- References the issue text specifically — don't write generic advice
-- Stays focused on what the persona would actually care about (e.g. Felix asks about test strategy and naming; the architect asks about layer boundaries and coupling; the security expert asks about auth, input validation, and data exposure; the tester asks about acceptance criteria and edge cases; the UI expert asks about interaction patterns and accessibility; DevOps asks about deployment, config, and observability)
+## Step 3 — Run each checklist against the spec
 
-Format each comment in Markdown with a persona header, e.g.:
+For each persona, walk **every item** in its `.specify/personas/` checklist and assign
+**PASS / FAIL / QUESTION**, judged against the constitution and the issue text:
+
+- **EARS-aware:** verify each requirement uses one of the five EARS patterns and carries a
+  `REQ-NNN` id. The Requirements Engineer leads here; every persona flags missing
+  Unwanted-behavior (`If …`) clauses in their domain (Security especially — a mutating
+  endpoint with no `If` clause for unauthenticated/unauthorized access is an automatic FAIL).
+- **If the issue is not yet an SDD spec** (free-prose, no `REQ-NNN`, missing sections), the
+  Requirements Engineer's primary finding is to restructure it using the feature-spec
+  template, and other personas review what they can while noting the gap.
+- Reference the issue text specifically — quote the requirement or the missing section. No
+  generic advice.
+
+## Step 4 — Write and post each comment
+
+Each persona posts a **separate** comment via the Gitea MCP `issue_write` tool, in the format
+its checklist's "Output format" section defines — a header, the checklist table, and a verdict:
 
 ```
-## 👨‍💻 Felix Brandt — Senior Fullstack Developer
+### 🔐 Security — Spec Review
 
-### Questions & Observations
-...
+| # | Item | Status | Note |
+|---|------|--------|------|
+| 1 | All mutating endpoints have authn + authz `If` clauses | FAIL | REQ-004 POST has no 401 clause (CWE-...) |
+| 2 | ... | PASS | |
 
-### Suggestions
-...
+**Verdict: CHANGES REQUESTED** — blocking FAIL: #1. Resolve before implementation.
 ```
 
-Keep each comment focused and scannable. Use bullet points. Avoid walls of text.
+Post all six comments. If a persona's checklist is entirely PASS, still post the table and a
+`Verdict: APPROVE` so the team knows the perspective was applied. Keep comments scannable.
 
-## Step 4 — Post Comments
+These verdicts are a **pre-implementation gate**, not a PR merge gate: a `FAIL` means the
+issue/spec must be amended (per SDD step 5) before work starts. Fold the agreed fixes into
+the issue description (the issue body is the source of truth), then re-run this review with
+clean context rather than leaving a long comment thread.
 
-Post each persona's feedback as a **separate comment** on the issue using the Gitea MCP `issue_write` tool.
-
-Post all six comments. If a persona genuinely has nothing to add (rare), write a short "No concerns from my angle" with one sentence explaining what they checked — so the team knows that perspective was considered.
-
-## Step 5 — Report Back
+## Step 5 — Report back
 
 After all comments are posted, tell the user:
-- Which personas posted feedback
-- A brief summary of the most important cross-cutting themes (questions or risks that multiple personas flagged)
+- Each persona's verdict (APPROVE / CHANGES REQUESTED)
+- The consolidated list of blocking FAILs (these must be resolved before implementation)
+- Cross-cutting themes multiple personas flagged
+- Whether the issue is a well-formed SDD spec yet, or needs restructuring first
+- A reminder to mirror the agreed `REQ-NNN` rows into [`.specify/rtm.md`](../../../.specify/rtm.md)

.claude/skills/review-pr/SKILL.md

@@ -1,74 +1,95 @@
 ---
 name: review-pr
-description: Multi-persona PR review. Each persona from .claude/personas/ reviews the PR and posts their findings as a separate Gitea comment.
+description: Multi-persona SDD code review of a Gitea PR. Each persona pairs its .claude/personas/ identity with its .specify/personas/ checklist, verifies the diff against the constitution and the feature spec's REQ-NNN (every requirement implemented and tested), and posts findings as a separate Gitea comment.
 ---
 
-# Multi-Persona PR Review
+# Multi-Persona PR Review (SDD)
 
-You will perform a thorough multi-persona code review of the given PR URL and post each persona's findings as a **separate comment** on the PR.
+You will perform a thorough multi-persona code review of the given PR and post each persona's
+findings as a **separate comment**. Under SDD, the review verifies the diff against two
+contracts: the project [constitution](../../../.specify/constitution.md) and the feature's
+spec (the linked **Gitea issue body** — every `REQ-NNN` must be implemented **and** covered by a test).
 
 ## Argument
 
 The user provides a Gitea PR URL, e.g.:
 `http://heim-nas:3005/marcel/familienarchiv/pulls/160`
 
-Parse it to extract:
-- `owner` — e.g. `marcel`
-- `repo` — e.g. `familienarchiv`
-- `pull_number` — e.g. `160`
+Parse it to extract `owner`, `repo`, and `pull_number`.
 
-## Step 1 — Gather PR Context
+## Step 0 — Load the SDD ground truth
+
+Read before reviewing:
+- [`.specify/constitution.md`](../../../.specify/constitution.md) — rules the code must obey (esp. §4 Do-Not-Touch)
+- [`.specify/AGENTS.md`](../../../.specify/AGENTS.md) — constraints
+- The feature's spec — the **Gitea issue** the PR closes (`Closes #n`). Read its body for the
+  `REQ-NNN` requirements, acceptance criteria, inline API stub, and any STRIDE/threat notes.
+- [`.specify/rtm.md`](../../../.specify/rtm.md) — the requirement→test→status matrix
+
+## Step 1 — Gather PR context
 
 Use the Gitea MCP tools to collect:
-1. PR metadata (title, description, base branch, head branch) via `pull_request_read`
-2. The list of changed files via `get_dir_contents` or the PR files endpoint
-3. The full diff / file contents of every changed file — read each file at the head commit using `get_file_contents`
+1. PR metadata (title, description, base/head branch) via `pull_request_read`
+2. The list of changed files
+3. The full content of every changed file at the head commit via `get_file_contents`
 
-Read ALL changed files completely before starting any review. Do not skip files.
+Read ALL changed files completely before starting. Do not skip files.
 
-## Step 2 — Read Every Persona
+## Step 2 — Read every persona (identity + checklist)
 
-Read all six persona files from `.claude/personas/`:
-- `developer.md` → Felix Brandt
-- `architect.md` → architect persona
-- `tester.md` → tester persona
-- `security_expert.md` → security persona
-- `ui_expert.md` → UI/UX persona
-- `devops.md` → DevOps persona
+Adopt each persona's voice from `.claude/personas/`; apply its review lens. For the SDD
+personas, also re-read the matching `.specify/personas/` checklist — at PR time the same
+checklist items are verified against the **code** rather than the spec.
 
-## Step 3 — Write Each Review
+| Persona | Identity (`.claude/personas/`) | Checklist (`.specify/personas/`) | PR-time focus |
+|---|---|---|---|
+| Requirements Engineer | `req_engineer.md` | `requirements-engineer.md` | Traceability: every `REQ-NNN` implemented; RTM updated |
+| Developer (Felix Brandt) | `developer.md` | `developer.md` | Clean code, layering, generate:api run, ErrorCode four-site |
+| Tester | `tester.md` | — (uses identity) | Test quality: each REQ has a real failing-first test; edge cases; levels right |
+| Security (Nora "NullX") | `security_expert.md` | `security.md` | authn/authz, IDOR, mass-assignment, `{@html}`, secrets/PII |
+| DevOps | `devops.md` | `devops.md` | migration rollback, env vars, CI guards intact, artifact pin |
+| UI/UX | `ui_expert.md` | `ui-ux.md` | states, i18n, a11y, design tokens |
+| Architect | `architect.md` | `architect.md` | boundaries, ADR present for irreversible choices, no superseded-ADR violation |
 
-For each persona, fully adopt their identity, priorities, and review lens as described in their persona file. Write a review that:
+## Step 3 — Write each review
+
+For each persona, write a review that:
 
 - Opens with a one-line verdict: **✅ Approved**, **⚠️ Approved with concerns**, or **🚫 Changes requested**
-- Lists concrete findings with file paths and line references where relevant
-- Distinguishes blockers (must fix) from suggestions (nice to have)
-- Uses the persona's voice and priorities (e.g. Felix cares about TDD and clean code; the security expert checks for injection, auth, and data exposure; the architect checks layer boundaries and coupling)
-- Stays focused — only comment on what the persona would actually care about
-
-Format each comment in Markdown with a persona header, e.g.:
+- Lists concrete findings with file paths and line references; cite the constitution rule
+  (e.g. "violates §2.4 — `updatedBy` bound from request body") or the `REQ-NNN` at issue
+- Distinguishes **blockers** (must fix) from **suggestions** (nice to have)
+- **Requirements Engineer specifically** produces a traceability table — for each `REQ-NNN`:
+  is it implemented? is there a test? is `rtm.md` updated to `Done`? Any unimplemented or
+  untested REQ is a blocker. Any code behavior with no backing requirement is flagged
+  (scope creep — should it be a new REQ, or removed?).
+- A constitution **Do-Not-Touch** violation (edited generated file, edited shipped migration,
+  edited an Accepted ADR, bumped the artifact action past v3, weakened a CI guard) is always
+  a blocker.
 
 ```
-## 👨‍💻 Felix Brandt — Senior Fullstack Developer
+### 🔐 Security — PR Review
 
 **Verdict: ⚠️ Approved with concerns**
 
 ### Blockers
-...
+- `UserAvatarController.java:42` — REQ-009's 403 path has no test (constitution §2.8)
 
 ### Suggestions
-...
+- ...
 ```
 
-## Step 4 — Post Comments
+## Step 4 — Post comments
 
-Post each persona's review as a **separate comment** on the PR using the Gitea MCP `issue_write` tool (issues and PRs share the comment API in Gitea).
+Post each persona's review as a **separate comment** via the Gitea MCP `issue_write` tool
+(issues and PRs share the comment API). Post all personas; if one has nothing to flag, post a
+brief "LGTM" naming what they checked.
 
-Post all six comments. Do not skip any persona even if their domain has nothing to flag — in that case write a brief "LGTM" with a short explanation of what they checked.
+## Step 5 — Report back
 
-## Step 5 — Report Back
-
-After all comments are posted, summarize to the user:
-- Which personas posted comments
-- The overall verdict across all personas (worst-case wins: if any said "Changes requested", the overall is "Changes requested")
-- A bullet list of the top blockers found (if any)
+Summarize to the user:
+- Each persona's verdict and the overall verdict (worst-case wins: any "Changes requested" → overall "Changes requested")
+- The full list of blockers, grouped by persona
+- **Traceability status:** which `REQ-NNN` are implemented+tested vs. missing, and whether
+  `rtm.md` is in sync
+- Any constitution Do-Not-Touch violations (called out explicitly)

.gitea/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,40 @@
+---
+name: "Bug"
+about: "Something is broken. Describe user-facing impact, not the technical cause."
+title: "<What breaks> when <trigger>"
+labels:
+  - bug
+assignees: []
+---
+
+<!--
+  Title format (COLLABORATING.md): "<What breaks> when <trigger>", e.g.
+  "Upload fails silently when file exceeds 50MB". Keep it focused — a bug is small and direct.
+  A failing test is written first, then the fix (red/green TDD).
+-->
+
+## What happens
+
+<The observed broken behavior, from the user's perspective.>
+
+## Expected
+
+<What should happen instead.>
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Originating requirement (if known)
+
+<REQ-NNN + feature this regresses, from .specify/rtm.md — e.g. "REQ-008 (profile-picture-upload)". Helps target the failing test. Write "unknown" if not traceable.>
+
+## Environment
+
+<Browser / role / data state / deploy (local vs prod) as relevant.>
+
+## Notes
+
+<Logs, GlitchTip link, screenshots. Redact PII.>

.gitea/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,81 @@
+---
+name: "Feature (SDD spec)"
+about: "Spec-driven feature request. Fill in EARS requirements before implementation starts."
+title: "As a <role> I want <capability> so <reason>"
+labels:
+  - spec-required
+  - needs-review
+assignees: []
+---
+
+<!--
+  This issue body IS the spec (issue-only — there is no committed spec.md). Every requirement
+  uses an EARS pattern + a REQ-NNN id. Reference: .specify/templates/feature-spec.md and the
+  worked example .specify/features/_example/. Delete the placeholder hints as you fill each section.
+-->
+
+## Context & Why
+
+<Who needs this and why now (2–4 sentences). Link the constitution principle(s) this depends on: .specify/constitution.md>
+
+## User Journey
+
+<Plain-prose steps the user takes to get value, from the user's perspective. Anything not here is out of scope.>
+
+## Requirements
+
+<!-- One per line, each REQ-NNN + one EARS pattern. A mutating feature needs at least one Event-driven and one Unwanted-behavior requirement. -->
+
+- **REQ-001** (Ubiquitous) — The `<component>` shall `<always-true behavior>`.
+- **REQ-002** (Event-driven) — When `<trigger>`, the `<component>` shall `<response>`.
+- **REQ-003** (State-driven) — While `<state>`, the `<component>` shall `<behavior>`.
+- **REQ-004** (Optional-feature) — Where `<caller has Permission.X / flag set>`, the `<component>` shall `<behavior>`.
+- **REQ-005** (Unwanted-behavior) — If `<undesired condition>`, then the `<component>` shall `<safe response / ErrorCode>`.
+
+## Acceptance Criteria
+
+<!-- One measurable criterion per REQ-NNN: numbers, limits, status codes — not adjectives. -->
+
+- **REQ-001** — <measurable>.
+- **REQ-002** — <measurable>.
+
+## Out of Scope
+
+- <The nearest tempting scope creep, named and excluded.>
+
+## API / Contract Stub
+
+<Inline OpenAPI stub (use .specify/templates/api-contract-stub.md as a writing aid). Name new paths/methods/status codes and the @RequirePermission on each mutating endpoint.>
+
+## Data Model Changes
+
+<Schema delta + next free Flyway V<n> (verify on disk) + rollback note. "none" if not applicable.>
+
+## Security Considerations
+
+<STRIDE categories touched (+ ASTRIDE if an AI agent/tool is involved). Link a threat-model.md if the attack surface is non-trivial.>
+
+## Open Questions
+
+<!-- Each item BLOCKS implementation until resolved. -->
+
+- [ ] <question> — owner: <name>
+
+## Traceability
+
+| REQ-ID | Task ID(s) | Test ID(s) | Status |
+|---|---|---|---|
+| REQ-001 |  |  | Planned |
+
+<!-- Mirror these rows into .specify/rtm.md. -->
+
+## Persona Review Results
+
+| Persona | Status | Key Findings | Resolved |
+|---|---|---|---|
+| Requirements Engineer | PENDING |  |  |
+| Developer | PENDING |  |  |
+| Security | PENDING |  |  |
+| DevOps | PENDING |  |  |
+| UI/UX | PENDING |  |  |
+| Architect | PENDING |  |  |

.gitea/workflows/nightly.yml

@@ -161,3 +161,147 @@ jobs:
         # without first re-evaluating ADR-011.
         if: always()
         run: rm -f .env.staging
+
+  npm-audit:
+    # Independent parallel job — a deploy failure cannot mask the audit signal
+    # and a clean audit cannot hide a broken deploy. Intentionally no `needs:`.
+    #
+    # Scans dev deps too (no --omit=dev), which is deliberately broader than the
+    # PR gate (ci.yml §Security audit) that uses --omit=dev. A nightly broader
+    # result is NOT a PR gate failure — it catches dev-tooling advisories (esbuild,
+    # Vite, etc.) early. See docs/infrastructure/ci-gitea.md §Nightly audit vs PR gate.
+    #
+    # Required Gitea secrets:
+    #   NIGHTLY_AUDIT_TOKEN  — PAT with issues scope only. An issues-only token
+    #                          means a leak via logs/process-args cannot push
+    #                          branches, open PRs, or read repo contents (ADR-041).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Assert jq is available
+        run: which jq || sudo apt-get install -y jq
+
+      - name: Run npm audit and file tracking issue on findings
+        # Never run under set -x — NIGHTLY_AUDIT_TOKEN in env would leak to logs.
+        env:
+          NIGHTLY_AUDIT_TOKEN: ${{ secrets.NIGHTLY_AUDIT_TOKEN }}
+        run: |
+          MARKER="Nightly npm audit: high-severity advisory"
+          GITEA_URL="${{ github.server_url }}"
+          REPO="${{ github.repository }}"
+          RUN_URL="${GITEA_URL}/${REPO}/actions/runs/${{ github.run_id }}"
+
+          # --- Self-test (mirrors ci.yml §Assert pattern) ---
+          # Tests the exact jq test() call used in the dedupe step, before any
+          # API call, so a broken matcher fails loudly early rather than silently
+          # opening duplicate issues. Proves the regex only — create-vs-update
+          # decision is exercised by the workflow_dispatch AC.
+          echo "{\"title\": \"${MARKER}\"}" \
+            | jq -e --arg m "$MARKER" '.title | test($m; "i")' > /dev/null \
+            || { echo "FAIL: self-test — jq test() missed tracking issue title"; exit 1; }
+          echo '{"title": "fix(deps): update dependency esbuild (CVE-2025-12345)"}' \
+            | jq -e --arg m "$MARKER" '.title | test($m; "i") | not' > /dev/null \
+            || { echo "FAIL: self-test — jq test() incorrectly matched unrelated title"; exit 1; }
+          echo "Self-test passed."
+
+          # --- Run audit ---
+          # No npm ci — audit reads only the lockfile (no network, no install).
+          set +e
+          (cd frontend && npm audit --audit-level=high --json > /tmp/audit.json)
+          AUDIT_EXIT=$?
+          set -e
+
+          if [ "$AUDIT_EXIT" -ne 0 ]; then
+            # --- Build issue body with jq (never string-concat advisory text) ---
+            # Advisory overview/title text is registry-controlled; string-concat
+            # would be an injection/escaping vector into the API body. Truncate
+            # raw excerpt to 500 chars so a pathological overview can't produce
+            # a multi-MB PATCH body.
+            ISSUE_BODY=$(jq -r \
+              --arg run_url "$RUN_URL" \
+              '
+              (.vulnerabilities // {}) as $vulns |
+              ($vulns | to_entries |
+                map(select(.value.severity == "high" or .value.severity == "critical")) |
+                map("- **" + .key + "** (" + .value.severity + ")") |
+                if length > 0 then join("\n") else "_See raw output for details._" end) as $pkg_list |
+              "## npm audit: high/critical advisories\n\n" + $pkg_list +
+              "\n\n**Run:** " + $run_url +
+              "\n\n<details><summary>Raw audit excerpt (first 500 chars)</summary>\n\n```\n" +
+              (tostring | .[0:500]) +
+              "\n```\n\n</details>"
+              ' /tmp/audit.json)
+
+            # --- Dedupe: fetch open security issues, match by title marker ---
+            # Renovate vuln PRs also carry the "security" label, so >1 open
+            # "security" issue WILL occur. Title-match (not just label) ensures
+            # we deduplicate only our own tracking issue.
+            OPEN_ISSUES=$(curl -sf \
+              -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/issues?state=open&type=issues&labels=security&limit=50")
+
+            MATCHED=$(echo "$OPEN_ISSUES" | jq \
+              --arg m "$MARKER" \
+              '[.[] | select(.title | test($m; "i"))] | sort_by(.created_at)')
+            MATCH_COUNT=$(echo "$MATCHED" | jq 'length')
+
+            if [ "$MATCH_COUNT" -gt 0 ]; then
+              # Patch the oldest matched issue (append run URL to body).
+              ISSUE_NUMBER=$(echo "$MATCHED" | jq -r '.[0].number')
+              EXISTING_BODY=$(echo "$MATCHED" | jq -r '.[0].body')
+              NEW_BODY=$(jq -n \
+                --arg existing "$EXISTING_BODY" \
+                --arg run_url "$RUN_URL" \
+                '$existing + "\n\n---\n\nUpdated by run: " + $run_url')
+              PAYLOAD=$(jq -n --arg body "$NEW_BODY" '{"body": $body}')
+              curl -sf -X PATCH \
+                -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" \
+                -H "Content-Type: application/json" \
+                -d "$PAYLOAD" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/issues/${ISSUE_NUMBER}" > /dev/null
+              echo "Updated tracking issue #${ISSUE_NUMBER}"
+            else
+              # Closed prior issue that recurs → new issue (not reopened).
+              # A re-opened issue would obscure when the advisory was re-discovered.
+              PAYLOAD=$(jq -n \
+                --arg title "$MARKER" \
+                --arg body "$ISSUE_BODY" \
+                '{"title": $title, "body": $body}')
+              CREATED=$(curl -sf -X POST \
+                -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" \
+                -H "Content-Type: application/json" \
+                -d "$PAYLOAD" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/issues")
+              NEW_NUMBER=$(echo "$CREATED" | jq -r '.number')
+              echo "Opened new tracking issue #${NEW_NUMBER}"
+
+              # Labels are ignored on issue create in Gitea — add in a follow-up call.
+              LABEL_IDS=$(curl -sf \
+                -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/labels?limit=50" \
+                | jq '[.[] | select(.name == "security" or .name == "devops" or .name == "P1-high") | .id]')
+              curl -sf -X POST \
+                -H "Authorization: token $NIGHTLY_AUDIT_TOKEN" \
+                -H "Content-Type: application/json" \
+                -d "{\"labels\": $LABEL_IDS}" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/issues/${NEW_NUMBER}/labels" > /dev/null
+            fi
+
+            exit "$AUDIT_EXIT"
+
+          else
+            # --- Heartbeat: proves the job ran and found nothing ---
+            # "No issue created" is only meaningful evidence when paired with a
+            # visible positive signal. Without this, a never-ran job is
+            # indistinguishable from a clean run.
+            #
+            # $GITHUB_STEP_SUMMARY availability is unproven on this runner
+            # (act_runner populates it, but this is the first run to verify it).
+            # Guard before use so an unset variable does not fail the clean-path.
+            MSG="✅ npm audit clean $(date -u)"
+            if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+              echo "$MSG" >> "$GITHUB_STEP_SUMMARY"
+            fi
+            echo "$MSG"
+          fi

.gitea/workflows/renovate.yml

@@ -0,0 +1,44 @@
+name: Renovate
+
+# Runs Renovate daily to surface newly-published advisories via OSV.dev
+# (osvVulnerabilityAlerts) and open routine update PRs on a weekly batch
+# schedule (see renovate.json §schedule). Security/vulnerability PRs are
+# raised immediately regardless of the weekly schedule window.
+#
+# Required Gitea secrets (see docs/adr/041-renovate-runner-setup.md):
+#   RENOVATE_TOKEN  — PAT with scopes: contents + pull_request + issues
+#                     Belongs to a dedicated bot account. Branch protection
+#                     on main must forbid this bot pushing directly.
+#
+# Platform config is injected via env vars below; the renovate.json in the
+# repo root carries only dependency rules (no platform/endpoint/repos).
+#
+# Digest pin: renovatebot/github-action@8217b3fc286df088d7c27f3255fe8414463bc0fd
+# corresponds to release v46.1.15. Update by bumping both the digest and the
+# renovate-version when Renovate publishes a new release. Renovate itself
+# will open a PR to bump this digest once it runs.
+
+on:
+  schedule:
+    - cron: "0 3 * * *"  # daily at 03:00 UTC — cuts OSV-alert latency to ≤1 day
+  workflow_dispatch:
+
+jobs:
+  renovate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run Renovate
+        # Pinned by digest — this action holds contents+pull_request+issues
+        # scopes; an unpinned tag is a supply-chain risk (see ADR-041).
+        uses: renovatebot/github-action@8217b3fc286df088d7c27f3255fe8414463bc0fd  # v46.1.15
+        with:
+          configurationFile: renovate.json
+          token: ${{ secrets.RENOVATE_TOKEN }}
+          renovate-version: "46.1.15"
+        env:
+          RENOVATE_PLATFORM: gitea
+          RENOVATE_ENDPOINT: https://git.raddatz.cloud
+          RENOVATE_REPOSITORIES: '["marcel/familienarchiv"]'
+          LOG_LEVEL: info

.gitea/workflows/sdd-gate.yml

@@ -0,0 +1,169 @@
+name: SDD Gate
+
+# Spec-Driven Development quality gate. Runs on PRs.
+#
+# This project is ISSUE-ONLY: a feature's spec lives in its Gitea issue body, not a committed
+# spec.md (see ADR-042). So CI cannot lint the spec text itself — instead it validates the SDD
+# artifacts that DO live in git: the RTM, any committed OpenAPI contract, and the constitution.
+#
+# The first two jobs are NON-BLOCKING for now (continue-on-error) so the team can adopt the
+# workflow without CI immediately failing.
+#
+# TODO: flip rtm-check and contract-validate to BLOCKING (remove `continue-on-error: true`)
+#       once SDD adoption has settled — target: after the first 5 features have shipped through
+#       the workflow. Tracked in ADR-042.
+
+on:
+  pull_request:
+
+jobs:
+  # ─── RTM check ────────────────────────────────────────────────────────────────
+  # The Requirements Traceability Matrix is the one per-feature SDD artifact in git. Every
+  # data row must point at a Gitea issue (`#n`) and name at least one test. Warn otherwise.
+  # Pure awk — no external tooling. Columns: | REQ-ID | Summary | Issue | Feature | Impl | Test | Status |
+  rtm-check:
+    name: RTM Check
+    runs-on: ubuntu-latest
+    continue-on-error: true   # TODO: remove to make blocking (see header)
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate .specify/rtm.md rows
+        shell: bash
+        run: |
+          set -uo pipefail
+          rtm=".specify/rtm.md"
+          test -f "$rtm" || { echo "::error::$rtm is missing"; exit 1; }
+
+          # Self-test: a good row passes, a row with an empty Issue or Test is flagged.
+          check_row() { awk -F'|' '{
+            issue=$4; test_col=$7;
+            gsub(/^[ \t]+|[ \t]+$/,"",issue); gsub(/^[ \t]+|[ \t]+$/,"",test_col);
+            if (issue !~ /#/ || test_col=="") exit 1; else exit 0 }'; }
+          echo '| REQ-001 | x | #42 | f | impl | SomeTest#works | Done |'  | check_row \
+            || { echo "FAIL: rtm-check self-test rejected a valid row"; exit 1; }
+          echo '| REQ-002 | x |     | f | impl |               | Planned |' | check_row \
+            && { echo "FAIL: rtm-check self-test accepted an empty row"; exit 1; }
+
+          bad=0
+          while IFS= read -r line; do
+            echo "$line" | check_row || {
+              req=$(echo "$line" | awk -F'|' '{gsub(/^[ \t]+|[ \t]+$/,"",$2); print $2}')
+              echo "::warning file=$rtm::row $req is missing an Issue (#n) or a Test"
+              bad=$((bad+1))
+            }
+          done < <(grep -E '^\| REQ-[0-9]{3} ' "$rtm")
+          echo "$bad RTM row(s) incomplete (warning only)."
+
+  # ─── Contract validation ──────────────────────────────────────────────────────
+  # Validate any committed OpenAPI contract with Spectral (OpenAPI 3.1). REST stack — no
+  # GraphQL. Contracts are optional and ride a feature branch when present; the _example one
+  # is always linted. Skips cleanly when none changed.
+  contract-validate:
+    name: Contract Validate
+    runs-on: ubuntu-latest
+    continue-on-error: true   # TODO: remove to make blocking (see header)
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      # Cache the npm/npx download so Spectral isn't re-fetched every run. The key is pinned to
+      # the exact Spectral version below, so a version bump busts the cache deterministically.
+      - name: Cache Spectral (npm cache)
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: spectral-cli-6.16.0
+          restore-keys: spectral-cli-
+
+      - name: Lint changed OpenAPI contracts
+        shell: bash
+        env:
+          SPECTRAL: "@stoplight/spectral-cli@6.16.0"   # pinned — keep in sync with the cache key above
+        run: |
+          set -uo pipefail
+          base="origin/${{ github.event.pull_request.base.ref }}"
+          git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true
+          # Any *.yaml under .specify/ or any file named like a contract.
+          changed="$(git diff --name-only "$base"...HEAD -- '.specify/**/*.yaml' '**/api-contract.yaml' '**/*.openapi.yaml' || true)"
+          if [ -z "$changed" ]; then
+            echo "No OpenAPI contract changed — nothing to validate."
+            exit 0
+          fi
+          rc=0
+          for f in $changed; do
+            [ -f "$f" ] || continue
+            echo "── spectral lint $f"
+            npx --yes "$SPECTRAL" lint "$f" || rc=1
+          done
+          exit $rc
+
+  # ─── Constitution change impact ───────────────────────────────────────────────
+  # When .specify/constitution.md is modified, list every file that references it (and so
+  # may need a Sync Impact update) and post it as a PR comment. Best-effort: if no token is
+  # available the list is only echoed to the log. This job is informational, never blocking.
+  constitution-diff:
+    name: Constitution Impact
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: List files referencing the constitution
+        id: impact
+        shell: bash
+        run: |
+          set -uo pipefail
+          base="origin/${{ github.event.pull_request.base.ref }}"
+          git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true
+          if ! git diff --name-only "$base"...HEAD -- '.specify/constitution.md' | grep -q .; then
+            echo "constitution.md not modified — skipping."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+          echo "Files referencing constitution.md (review for Sync Impact):"
+          grep -rIl --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=target \
+            -e 'constitution.md' -e 'constitution §' . \
+            | grep -v '^\./.specify/constitution.md$' | sort > /tmp/refs.txt || true
+          cat /tmp/refs.txt
+          {
+            echo "body<<EOF"
+            echo "### ⚠️ Constitution changed — Sync Impact review"
+            echo ""
+            echo "\`.specify/constitution.md\` was modified in this PR. Per its §6 Sync Impact rule, re-read and reconcile every file below, and confirm the semantic version bump:"
+            echo ""
+            while IFS= read -r line; do echo "- \`${line#./}\`"; done < /tmp/refs.txt
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Post PR comment (best-effort)
+        if: steps.impact.outputs.changed == 'true'
+        shell: bash
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SERVER: ${{ github.server_url }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+          BODY: ${{ steps.impact.outputs.body }}
+        run: |
+          set -uo pipefail
+          if [ -z "${TOKEN:-}" ]; then
+            echo "No token available — printing impact list to log only:"
+            echo "$BODY"
+            exit 0
+          fi
+          payload="$(jq -n --arg b "$BODY" '{body:$b}')"
+          curl -sS -X POST \
+            -H "Authorization: token ${TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${SERVER}/api/v1/repos/${REPO}/issues/${PR}/comments" \
+            -d "$payload" >/dev/null \
+            && echo "Posted Sync Impact comment to PR #${PR}." \
+            || { echo "Comment POST failed (non-fatal); impact list:"; echo "$BODY"; }

.specify/AGENTS.md

@@ -0,0 +1,77 @@
+# AGENTS.md
+
+Machine-readable rules for AI coding agents (Claude Code, Copilot, Cursor, …) working in
+this repository. Read this on every invocation. These are **executable constraints**, not
+aspirations. The full rationale lives in [constitution.md](./constitution.md) and the docs
+it links — this file does not duplicate it, it points to it.
+
+If anything here conflicts with the user's explicit instruction, the user wins. Otherwise,
+constitution > this file > convenience.
+
+---
+
+## Stack & Versions
+
+| Layer | Tech | Version |
+|---|---|---|
+| Backend | Spring Boot (Java, Maven, Jetty, JPA/Hibernate, Flyway, Spring Security, Session JDBC) | Boot 4.0.6 / Java 21 |
+| API docs | springdoc-openapi (webmvc-ui), served at `/v3/api-docs` (dev profile only) | — |
+| Frontend | SvelteKit / Svelte | 2.60 / 5.43 |
+| Frontend lang/style | TypeScript / Tailwind CSS / Paraglide i18n (de/en/es) | TS 5.9 / TW 4.1 |
+| API client | `openapi-fetch` + `openapi-typescript` (types generated from the live spec) | — |
+| DB | PostgreSQL | 16 |
+| Object storage | MinIO (S3-compatible) | — |
+| Sidecars | `ocr-service`, `nlp-service` (Python / FastAPI) | Python 3.11 |
+| Tests | JUnit + Mockito + `@WebMvcTest` + Testcontainers (backend); Vitest + `vitest-browser-svelte` + Playwright (frontend); Pytest (services) | — |
+| Lint/format | ESLint 9 (+ `eslint-plugin-boundaries`) + Prettier; Semgrep (backend) | — |
+| CI | Gitea Actions (`.gitea/workflows/`) | — |
+
+App port `8080`; management port `8081`. Backend app id: `org.raddatz.familienarchiv` / `0.0.1-SNAPSHOT`.
+
+## Architectural Constraints
+
+- Controllers call services only — never a repository. (constitution §1.2)
+- A service uses only its own domain's repository; reach other domains via their service. (constitution §1.3)
+- A new backend domain goes in its own package AND is added to `ArchitectureTest`'s allow-lists in the same change. (constitution §1.7)
+- Frontend cross-domain imports are allowed only where `frontend/eslint.config.js` permits; otherwise move shared code to `$lib/shared/`. (constitution §1.4)
+- Never serialize a lazy-collection entity across the controller boundary — assemble a view in-transaction. (constitution §1.6 / ADR-036)
+- `Person` ≠ `AppUser`; do not add account guards to Person-domain operations. (constitution §1.5)
+- Every `POST/PUT/PATCH/DELETE` endpoint has `@RequirePermission(Permission.X)`. Use the enum, never `@PreAuthorize`. (constitution §2.1–2.2)
+- Throw only `DomainException.notFound/forbidden/conflict/internal()` from services, each with an `ErrorCode`. (CONTRIBUTING §Error handling)
+- Set `createdBy`/`updatedBy` from the session principal in the service — never bind them from a request body. (constitution §2.4)
+- Add an `@Schema(requiredMode = REQUIRED)` to every always-populated field. (constitution §3.5)
+- Never introduce a new runtime dependency without an ADR in `Accepted` status. (constitution §5.1)
+- Render untrusted text with `{...}`; never `{@html}` on user/import data. (constitution §2.5)
+- Build dates from ISO strings with a `T12:00:00` suffix. (constitution §3.7)
+
+## Workflow Rules
+
+- Always write a failing test before implementation code; confirm it fails, then make it pass, then refactor. (constitution §3.1)
+- Run only the specific test file/class locally — never the full suite (it crashes the machine); leave the full sweep to CI.
+- Run `npm run generate:api` (in `frontend/`) after ANY backend model or endpoint change — most common cause of TS errors.
+- Run `npm run lint` before every commit; a fresh frontend worktree needs `npm install` first or the pre-commit hook fails.
+- When adding a new `ErrorCode`, update all four sites at once (constitution §3.6).
+- One logical change per commit; reference the Gitea issue (`Closes #n` / `Refs #n`) on the last line.
+- Create a git worktree for new issue work — never `git checkout -b` in the main repo while another branch has in-flight work. Avoid `+` in worktree/branch names (breaks vitest browser mode).
+- Pull `main` as a separate explicit step before creating a branch.
+- Track work as Gitea issues (`http://192.168.178.71:3005`, repo `marcel/familienarchiv`), not todo files.
+- Verify ADR and Flyway migration numbers against disk before using one — parallel worktrees make issue-body numbers go stale.
+
+## Do Not Touch
+
+- Generated: `frontend/src/lib/generated/api.ts`, `frontend/src/lib/paraglide/`, `frontend/.svelte-kit/`, `frontend/build/`, `backend/target/`.
+- Shipped Flyway migrations — add a new forward-only migration instead.
+- An `Accepted` ADR — supersede it with a new one.
+- `actions/(upload|download)-artifact` version — stays at `@v3` (ADR-014).
+- CI guard steps — do not remove/weaken without an ADR.
+- `main` — never commit directly; branch + PR only.
+- Worktree copies (`familienarchiv-*`, `.worktrees/`) and `data/` — never commit.
+
+## Spec-Driven Development
+
+A feature's spec is its **Gitea issue body** — there is no committed `spec.md`. The issue's
+EARS requirements (`REQ-NNN`) and acceptance criteria are the contract; each maps to a test,
+traced in [`.specify/rtm.md`](./rtm.md) (`REQ-ID → issue # → test`). Read the issue before
+implementing. The committed [`.specify/features/_example/`](./features/_example/) is a
+template/reference showing the full artifact set, not a live feature. Full workflow:
+[SPEC_DRIVEN_DEVELOPMENT.md](../SPEC_DRIVEN_DEVELOPMENT.md).

.specify/adrs/README.md

@@ -0,0 +1,25 @@
+# ADR archive — see `docs/adr/`
+
+This project already keeps a mature, permanent ADR archive at
+[`../../docs/adr/`](../../docs/adr/) (40+ records, format `NNN-kebab-title.md`). SDD does
+**not** introduce a second archive — that would split the project's decision history in two.
+
+## Where ADRs live
+
+- **Project-wide decisions** → [`docs/adr/NNN-kebab-title.md`](../../docs/adr/). Use the
+  next free `NNN` (verify against the directory on disk — parallel worktrees make
+  issue-body numbers stale). Template: [`../templates/adr.md`](../templates/adr.md).
+- **The decision to adopt SDD itself** →
+  [`docs/adr/042-sdd-adoption.md`](../../docs/adr/042-sdd-adoption.md) (this is the
+  "ADR-000" the SDD scaffold calls for, numbered to fit the existing sequence).
+- **Feature-local decisions** that are only meaningful within one in-flight feature →
+  beside that feature's spec, e.g.
+  [`../features/_example/adr-001-avatars-reuse-archive-bucket.md`](../features/_example/adr-001-avatars-reuse-archive-bucket.md).
+  Promote one to `docs/adr/` if its reach turns out to be project-wide.
+
+## Rules (unchanged from the existing convention)
+
+- An ADR is **immutable once `Accepted`** — supersede it with a new, higher-numbered ADR;
+  set the old one's status to `Superseded by ADR-MMM`.
+- Header style matches the existing archive: `# ADR-NNN — Title`, then
+  `**Status:** / **Date:** / **Issue:**`.

.specify/constitution.md

@@ -0,0 +1,80 @@
+# Familienarchiv Constitution
+
+**Version:** v1.0.0
+**Status:** Ratified
+**Date:** 2026-06-13
+**Adoption ADR:** [docs/adr/042-sdd-adoption.md](../docs/adr/042-sdd-adoption.md)
+
+> The non-negotiable rules of this project. Every spec, every PR, and every AI agent is
+> bound by this document. Rules here are deliberately few and absolute — guidance and
+> rationale live in [CLAUDE.md](../CLAUDE.md), [COLLABORATING.md](../COLLABORATING.md),
+> [CODESTYLE.md](../CODESTYLE.md), [CONTRIBUTING.md](../CONTRIBUTING.md), and the ADR
+> archive ([docs/adr/](../docs/adr/)). When this file conflicts with any of those, **this
+> file wins** — open an ADR to change it.
+>
+> Versioning is semantic: **MAJOR** = a rule removed or weakened (existing code may now
+> violate the constitution), **MINOR** = a rule added or tightened, **PATCH** = wording
+> only. Any change requires the Sync Impact review in the last section.
+
+---
+
+## 1. Architecture Principles
+
+1. The backend is organised package-by-domain under `org.raddatz.familienarchiv`; a new domain lives in its own package, never spread across layer packages.
+2. Controllers never call repositories directly — a controller calls only services.
+3. A service accesses only its own domain's repository; cross-domain data is fetched through the other domain's service, never its repository.
+4. The frontend mirrors the backend domain split under `frontend/src/lib/<domain>/`, and cross-domain imports are allowed only where `frontend/eslint.config.js` (`boundaries/dependencies`) permits them.
+5. A `Person` (historical subject) and an `AppUser` (login account) are distinct domains and never share an identity or an account guard.
+6. Lazy-collection-bearing entities are never serialized across the controller boundary; the owning service assembles an explicit view inside the transaction (see [ADR-036](../docs/adr/036-geschichte-responses-are-views-not-entities.md)).
+7. A new backend domain package is added to `ArchitectureTest`'s package allow-lists in the same change that introduces it.
+8. Synchronous cross-domain side effects use in-transaction domain events, not direct service-to-service write calls (see [ADR-006](../docs/adr/006-synchronous-domain-events-in-transaction.md)).
+
+## 2. Security Defaults
+
+1. Every `POST`, `PUT`, `PATCH`, and `DELETE` endpoint carries `@RequirePermission(Permission.X)` — there is no unguarded mutating endpoint.
+2. Authorization uses the typed `Permission` enum and `@RequirePermission`, never magic-string `@PreAuthorize`.
+3. All user input is validated at the system boundary (controller / form action), and validation failures return a typed `ErrorCode`, never a raw exception.
+4. Audit fields (`createdBy`/`updatedBy`) are set from the session principal inside the service and are never bound from a request body.
+5. Untrusted text is rendered through Svelte's default `{...}` escaping; `{@html}` is never used on user- or import-derived strings.
+6. Secrets are read only from environment variables (see `.env.example`); no secret, token, password, or DSN is ever committed to the repository or written to a log.
+7. Logs never contain PII beyond a stable user/entity UUID — no names, email addresses, document contents, or transcription text.
+8. Every state-mutating endpoint is covered by an Unwanted-behavior requirement (EARS `If`) describing the unauthenticated/unauthorized response.
+9. A dependency security audit runs on every CI run (`npm audit --audit-level=high` frontend, Semgrep `.semgrep/security.yml` backend) and nightly; a `high` finding blocks merge.
+
+## 3. Code Quality Rules
+
+1. All new behavior is driven by a failing test written before the implementation (Red → Green → Refactor); a passing-on-first-run test proves nothing and is rejected.
+2. KISS beats DRY — no premature abstraction; an abstraction is introduced only on the third real caller.
+3. Each commit does exactly one logical thing and references its Gitea issue (`Closes #n` / `Refs #n`) on the last line of the body.
+4. No backwards-compatibility shims are added for code that has no callers.
+5. Every entity/DTO field the backend always populates carries `@Schema(requiredMode = REQUIRED)`, and `npm run generate:api` is run after any backend model or endpoint change.
+6. A new `ErrorCode` is added in all four places at once: `ErrorCode.java`, `frontend/src/lib/shared/errors.ts`, `getErrorMessage()`, and `messages/{de,en,es}.json`.
+7. Dates built from an ISO date string append `T12:00:00` to avoid UTC off-by-one.
+8. `npm run lint` (Prettier + ESLint, including the domain boundary rule) passes before every commit.
+
+## 4. Do-Not-Touch List
+
+1. Do not edit generated artifacts: `frontend/src/lib/generated/api.ts`, `frontend/src/lib/paraglide/`, `frontend/.svelte-kit/`, `frontend/build/`, `backend/target/`.
+2. Do not edit an `Accepted` ADR — supersede it with a new, higher-numbered ADR.
+3. Do not upgrade `actions/upload-artifact` / `download-artifact` past `@v3` (Gitea act_runner lacks the v4 protocol — [ADR-014](../docs/adr/014-upload-artifact-v3-pin.md)).
+4. Do not remove or weaken a CI guard step (banned-pattern greps, self-tested regexes) without an ADR recording why.
+5. Do not commit to `main` directly — all work flows through a branch and a PR.
+6. Do not edit a Flyway migration that has shipped; add a new forward-only migration instead.
+7. Do not commit the worktree copy directories (`familienarchiv-*`, `.worktrees/`) or `data/`.
+
+## 5. Dependency Policy
+
+1. A new runtime dependency (backend `pom.xml` or frontend `dependencies`) requires an ADR in `Accepted` status before it is merged.
+2. A new dependency must be version-pinned in the manifest, and any exact pin (no caret) carries a comment stating why it cannot float (see the `@vitest/browser-playwright` pin).
+3. Renovate manages dependency-update PRs; a major-version bump is treated as a feature requiring its own spec and review, not an auto-merge.
+4. A dependency with an unresolved `high`+ advisory is not merged; it is pinned to a safe version or replaced.
+
+## 6. Sync Impact
+
+When this constitution changes, the author MUST, in the same PR:
+
+1. Bump the **Version** header per the semantic rule above and record the change in [docs/adr/042-sdd-adoption.md](../docs/adr/042-sdd-adoption.md)'s revision log (or a superseding ADR for a MAJOR change).
+2. Re-read and reconcile every file that restates a rule changed here: `CLAUDE.md`, `COLLABORATING.md`, `CODESTYLE.md`, `CONTRIBUTING.md`, `.specify/AGENTS.md`, and the affected `.specify/personas/*.md` checklists.
+3. Update any `.specify/templates/*` section that quotes a changed rule.
+4. Run the `constitution-diff` CI job locally (or read its PR comment) and resolve every file it lists.
+5. Announce the version bump in the PR description so reviewers re-read the constitution before approving.

.specify/features/_example/adr-001-avatars-reuse-archive-bucket.md

@@ -0,0 +1,46 @@
+# ADR-001 (feature-local) — Avatars reuse the archive bucket under an `avatars/` prefix
+
+**Status:** Accepted
+**Date:** 2026-06-13
+**Issue:** #<example> (profile picture upload)
+
+> **Feature-local ADR.** This decision is scoped to the avatar feature and lives with its
+> spec. A decision with project-wide reach is promoted to the permanent archive at
+> `docs/adr/` with the next free number. (For the worked example, it stays local.)
+
+## Context
+
+Avatars are small binary objects keyed per user. The project already runs MinIO with a
+single archive bucket and a `FileService` abstraction used by document uploads. We must
+decide where avatar bytes live without adding operational surface that the self-hosted
+Compose deployment has to learn about.
+
+## Decision
+
+Store each avatar in the **existing archive bucket** under the deterministic key
+`avatars/{userId}`, written and read through the existing `FileService`. No new bucket, no
+new env var, no new Compose service or bucket-bootstrap step.
+
+## Alternatives Considered
+
+| Option | Pros | Cons | Reason rejected |
+|---|---|---|---|
+| Reuse archive bucket, `avatars/` prefix | No infra change; reuses `FileService`; idempotent overwrite | Mixes avatars with documents in one bucket | **Chosen** — least operational cost; prefix keeps them logically separate |
+| Dedicated `avatars` bucket | Clean separation; independent lifecycle/policy | New bucket + bootstrap step + env var + Compose idempotency test | Operational overhead not justified for small, low-value objects |
+| Store bytes in PostgreSQL (`bytea`) | One datastore; transactional with the row | Bloats the DB and backups; streaming images via JPA is awkward | Wrong tool; MinIO already exists for blobs |
+| External CDN / object store | Offloads bandwidth | New third-party dependency + secret + ADR; conflicts with self-hosted goal | Contradicts the self-hosted infrastructure stance |
+
+## Consequences
+
+- No deployment change ships with this feature — only a Flyway column and code.
+- Avatars and documents share a bucket; any future per-object lifecycle policy must filter
+  by the `avatars/` prefix.
+- The deterministic key (`avatars/{userId}`, no random suffix) makes replace an overwrite,
+  so there is no orphan-cleanup obligation (REQ-001).
+- If avatars later need independent retention or a public CDN, this ADR is superseded by a
+  project-wide ADR in `docs/adr/`.
+
+## References
+
+- [`./spec.md`](./spec.md), [`./design.md`](./design.md)
+- [constitution §5 Dependency Policy](../../constitution.md#5-dependency-policy)

.specify/features/_example/api-contract.yaml

@@ -0,0 +1,140 @@
+openapi: 3.1.0
+info:
+  title: Familienarchiv API — Profile picture upload
+  version: 0.0.1-SNAPSHOT
+  description: >
+    Design-time contract for the avatar feature (.specify/features/_example).
+    Source of truth once shipped is the generated /v3/api-docs.
+servers:
+  - url: http://localhost:8080
+    description: Local backend (dev profile)
+  - url: https://archiv.raddatz.cloud
+    description: Production (behind Caddy)
+components:
+  securitySchemes:
+    cookieAuth:
+      type: apiKey
+      in: cookie
+      name: SESSION
+  schemas:
+    ErrorResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          example: AVATAR_TOO_LARGE
+        message:
+          type: string
+    UserProfileView:
+      type: object
+      required: [id, displayName]
+      properties:
+        id:
+          type: string
+          format: uuid
+        displayName:
+          type: string
+        avatarUrl:
+          type: [string, "null"]
+          description: Authenticated proxy path (/api/users/{id}/avatar) when an avatar exists, else null.
+          example: /api/users/3f1c.../avatar
+security:
+  - cookieAuth: []
+paths:
+  /api/users/me/avatar:
+    post:
+      summary: Upload or replace the current user's avatar
+      tags: [Users]
+      operationId: uploadMyAvatar
+      security:
+        - cookieAuth: []
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file:
+                  type: string
+                  format: binary
+                  description: PNG or JPEG, max 2 MB.
+      responses:
+        '200':
+          description: Avatar stored; updated profile returned.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/UserProfileView' }
+        '400':
+          description: Unsupported type (UNSUPPORTED_FILE_TYPE) or too large (AVATAR_TOO_LARGE).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401':
+          description: Unauthenticated (UNAUTHORIZED).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+    delete:
+      summary: Remove the current user's avatar
+      tags: [Users]
+      operationId: deleteMyAvatar
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          description: Avatar removed; profile returned with avatarUrl null.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/UserProfileView' }
+        '401':
+          description: Unauthenticated (UNAUTHORIZED).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+  /api/users/{id}/avatar:
+    get:
+      summary: Stream a user's avatar image (authenticated proxy)
+      tags: [Users]
+      operationId: getUserAvatar
+      security:
+        - cookieAuth: []
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        '200':
+          description: Image bytes.
+          content:
+            image/png: { schema: { type: string, format: binary } }
+            image/jpeg: { schema: { type: string, format: binary } }
+        '401': { description: Unauthenticated, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+        '404': { description: User has no avatar, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+    delete:
+      summary: Remove another user's avatar (admin only)
+      tags: [Users]
+      operationId: deleteUserAvatar
+      description: Requires Permission.ADMIN_USER (enforced by @RequirePermission on the controller).
+      security:
+        - cookieAuth: []
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        '200':
+          description: Avatar removed.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/UserProfileView' }
+        '401': { description: Unauthenticated, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+        '403':
+          description: Caller lacks ADMIN_USER (FORBIDDEN).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }

.specify/features/_example/checklist-results.md

@@ -0,0 +1,76 @@
+# Persona Review Results — Profile picture upload
+
+> Captured from the six persona spec reviews (the comments that, in a real feature, are
+> posted on the Gitea issue). This is the worked example of what a completed review round
+> looks like. All personas APPROVE; the two findings raised were folded into the spec
+> before approval.
+
+## Summary
+
+| Persona | Verdict | Blocking FAILs | Notes |
+|---|---|---|---|
+| Requirements Engineer | APPROVE | none | — |
+| Developer | APPROVE | none | — |
+| Security | APPROVE | none (2 resolved) | See F-SEC-1, F-SEC-2 |
+| DevOps | APPROVE | none | — |
+| UI/UX | APPROVE | none (1 resolved) | See F-UX-1 |
+| Architect | APPROVE | none (1 resolved) | See F-ARCH-1 |
+
+---
+
+## ### Security — Spec Review
+
+| # | Item | Status | Note |
+|---|---|---|---|
+| 1 | All mutating endpoints have authn + authz `If` clauses | PASS | REQ-006 (401), REQ-009 (403) |
+| 2 | Each mutating endpoint names least-privilege `Permission` | PASS | `me` = authenticated; `{id}` = ADMIN_USER |
+| 3 | Audit fields server-set, forbidden in body | PASS | `avatarObjectKey` server-set (design.md) |
+| 4 | IDOR surfaces addressed | PASS | `/{id}` gated by ADMIN_USER + ownership |
+| 5 | Untrusted content rendered safely | PASS | image bytes via proxy + `nosniff` |
+| 6 | Upload: type allow-list + size + bytes | PASS | REQ-007 (PNG/JPEG), REQ-008 (2 MB) |
+| 7 | No entity internals leaked | PASS | `UserProfileView`, not `AppUser` |
+| 8 | Conflicts → 409 not raw 500 | N/A | no optimistic-lock surface here |
+| 9 | threat-model.md present & STRIDE-complete | PASS | [threat-model.md](./threat-model.md) |
+| 10 | ASTRIDE if AI tool used | N/A | no AI agent |
+| 11 | Secrets from env only | PASS | none introduced |
+| 12 | Logs PII-free | PASS | user UUID only |
+| 13 | New dependency has ADR + clean audit | N/A | no new dependency |
+
+**F-SEC-1 (resolved):** initial draft exposed a public S3 URL for `avatarUrl` →
+information disclosure. Resolved: authenticated proxy `GET /api/users/{id}/avatar`.
+**F-SEC-2 (resolved):** initial draft bound `avatarObjectKey` from the request body →
+mass-assignment. Resolved: server-set only.
+**Verdict: APPROVE.**
+
+## ### UI/UX — Spec Review
+
+| # | Item | Status | Note |
+|---|---|---|---|
+| 1 | Every interaction state described | PASS | idle/preview/uploading/error/done (T-10) |
+| 2 | Strings via Paraglide i18n | PASS | T-8 |
+| 3 | Reuses design tokens/components | PASS | placeholder uses existing initials pattern |
+| 4 | Responsive per device split | PASS | control usable on phone + laptop |
+| 5 | Errors via `getErrorMessage(code)` | PASS | UNSUPPORTED_FILE_TYPE / AVATAR_TOO_LARGE |
+| 6 | Keyboard + screen-reader | PASS | labelled file input, alt text on image |
+| 7 | Acceptance criteria measurable | PASS | sizes, status codes |
+| 8 | E2E scenario per journey | PASS | T-12 |
+| 9 | Confirmation for destructive action | PASS | remove asks to confirm |
+| 10 | Safe rendering + image dims | PASS | fixed dims avoid layout shift |
+| 11 | Live routes verified | PASS | `/profile`, `/users/[id]` exist |
+| 12 | Token theming respected | PASS | semantic tokens |
+
+**F-UX-1 (resolved):** no loading state in first draft → spinner during upload added (REQ-... covered by state set in T-10).
+**Verdict: APPROVE.**
+
+## ### Architect — Spec Review
+
+Key items PASS. **F-ARCH-1 (resolved):** bucket choice was undocumented → captured in
+[adr-001-avatars-reuse-archive-bucket.md](./adr-001-avatars-reuse-archive-bucket.md). No new
+domain, no boundary crossing, Person/AppUser separation intact. **Verdict: APPROVE.**
+
+## ### Requirements Engineer / Developer / DevOps — Spec Review
+
+All checklist items PASS (see each persona's checklist in `.specify/personas/`). RE: 9 REQ
+ids, all EARS-formed, every limit has an `If`. Developer: reuses `FileService`/`UserService`,
+`AVATAR_TOO_LARGE` four-site update is T-1. DevOps: V78 forward-only + rollback note, no new
+bucket/env var, idempotent overwrite. **All three: APPROVE.**

.specify/features/_example/design.md

@@ -0,0 +1,63 @@
+# Design — Profile picture upload
+
+> Companion to [`./spec.md`](./spec.md). The spec says *what*; this says *how*, and records
+> the alternatives weighed for the non-obvious choices.
+
+## Component overview
+
+```
+ProfileSettings.svelte ──► +page.server.ts (form action)
+        (preview, validate)        │ POST /api/users/me/avatar (multipart)
+                                    ▼
+                         UserAvatarController  ── @RequirePermission(authenticated)
+                                    │            ownership/admin check for /{id}
+                                    ▼
+                            UserService.setAvatar(userId, MultipartFile)
+                                    │ validate type+size → ErrorCode
+                                    ├──► FileService.put("avatars/{userId}", bytes)   (MinIO)
+                                    └──► userRepository.save(user.avatarObjectKey=key)
+                                    ▼
+                            UserProfileView { …, avatarUrl }
+```
+
+Reads: `GET /api/users/{id}/avatar` streams the object through the authenticated API
+(`FileService.get`), so no public S3 URL is ever exposed. `avatarUrl` in the view is simply
+`/api/users/{id}/avatar` when a key exists, else `null`.
+
+## Key decisions
+
+| Decision | Choice | Why |
+|---|---|---|
+| Where avatars live | Existing archive bucket, `avatars/{userId}` prefix | No new bucket/env var/Compose change — see [ADR-001](./adr-001-avatars-reuse-archive-bucket.md). |
+| URL exposure | Authenticated proxy endpoint, not a signed/public URL | Same auth surface as the rest of the API; no key leakage (Information disclosure). |
+| Object key | Deterministic `avatars/{userId}` (no random suffix) | A new upload overwrites the old object — no orphan-cleanup job needed (REQ-001). |
+| `avatarObjectKey` binding | Server-set in `UserService` only | Never bound from request body — prevents pointing a user's avatar at an arbitrary object (Tampering / CWE-639). |
+| Validation site | `UserService`, boundary-only | Type + size checked once, at the service boundary, mapped to `ErrorCode` (constitution §2.3). |
+
+## Layering & conventions
+
+- Controller → `UserService` only; `UserService` owns `userRepository` and calls
+  `FileService` (its public API), never another domain's repository. (constitution §1.2–1.3)
+- New `ErrorCode.AVATAR_TOO_LARGE` requires the four-site update (see `tasks.md` T-1).
+- `UserProfileView.avatarUrl` is `String` (nullable) with `@Schema` describing the proxy
+  path; not marked `requiredMode = REQUIRED` because it is legitimately null (REQ-004).
+- After backend changes: `npm run generate:api` regenerates `avatarUrl` into the TS types.
+
+## Non-functional notes
+
+- Size cap (2 MB, REQ-008) is enforced **before** the object touches MinIO — the multipart
+  is read into a bounded buffer; Spring's `spring.servlet.multipart.max-file-size` is set to
+  a matching ceiling so an oversized body is rejected at the container edge too.
+- No N+1 risk: the profile view derives `avatarUrl` from the already-loaded `avatarObjectKey`
+  column; no extra query, no S3 round-trip on list/read paths.
+- The proxy `GET` streams bytes (no full-buffer) and sets a short `Cache-Control` so an
+  updated avatar propagates quickly.
+
+## Test strategy (maps to tasks.md)
+
+| Level | What | Tooling |
+|---|---|---|
+| Unit | `UserService.setAvatar` validation + storage interactions | JUnit + Mockito (mock `FileService`) |
+| Slice | controller auth, status codes, error codes | `@WebMvcTest` |
+| E2E | upload → preview → confirm → avatar visible; remove → initials | Playwright |
+| Component | initials placeholder when `avatarUrl` is null | `vitest-browser-svelte` (`*.svelte.spec.ts`) |

.specify/features/_example/spec.md

@@ -0,0 +1,118 @@
+# As a user I want to upload a profile picture so other family members recognise me
+
+> **This is the canonical worked example for SDD in this repo.** It is fictional but
+> realistic, chosen because no real avatar feature exists in the codebase. Use it as the
+> reference shape for a real `spec.md`. Every section is filled — no placeholders.
+
+## Context & Why
+
+Readers and transcribers collaborate in threads and on document comments, but every user is
+currently represented by initials only. Letting a user upload a small profile picture makes
+the activity feed, comments, and the public user profile page (`/users/[id]`) more personal
+and easier to scan — directly serving the family-archive product goal of feeling like a
+shared family space, not a database.
+
+Constitution principles this feature depends on:
+- [§2 Security Defaults](../../constitution.md#2-security-defaults) — upload validation, permission gating, no PII in logs.
+- [§1.3 services own their repository](../../constitution.md#1-architecture-principles) — avatar storage goes through `UserService` + `FileService`, not a controller.
+- [§3.6 ErrorCode four-site rule](../../constitution.md#3-code-quality-rules) — introduces `AVATAR_TOO_LARGE`.
+
+Related: builds on the existing `FileService` (MinIO) used by `Document` uploads.
+
+## User Journey
+
+A logged-in user opens their profile settings (`/profile`), clicks "Profilbild ändern",
+selects a PNG or JPEG from their device, sees an instant preview, and confirms. The picture
+replaces their initials everywhere their name appears. They can later remove it and fall
+back to initials. An admin (with `ADMIN_USER`) can remove an inappropriate picture from
+another user's account from the admin user view.
+
+## Requirements
+
+- **REQ-001** (Ubiquitous) — The user service shall store each profile picture as a single object in the existing archive bucket under the key `avatars/{userId}`, overwriting any previous object for that user.
+- **REQ-002** (Event-driven) — When an authenticated user sends `POST /api/users/me/avatar` with a valid image, the user service shall store the image, set the user's `avatarObjectKey`, and return the updated profile view including a non-null `avatarUrl`.
+- **REQ-003** (Event-driven) — When an authenticated user sends `DELETE /api/users/me/avatar`, the user service shall delete the stored object, clear `avatarObjectKey`, and return the profile view with `avatarUrl = null`.
+- **REQ-004** (State-driven) — While a user has no stored avatar, the profile view for that user shall return `avatarUrl = null` and the frontend shall render the initials placeholder.
+- **REQ-005** (Optional-feature) — Where the caller holds `Permission.ADMIN_USER`, the user service shall allow `DELETE /api/users/{id}/avatar` to remove another user's avatar.
+- **REQ-006** (Unwanted-behavior) — If the request to any avatar endpoint is unauthenticated, then the system shall return `401` with `ErrorCode.UNAUTHORIZED` and store or delete nothing.
+- **REQ-007** (Unwanted-behavior) — If the uploaded file's content type is not `image/png` or `image/jpeg`, then the user service shall return `400 ErrorCode.UNSUPPORTED_FILE_TYPE` and store nothing.
+- **REQ-008** (Unwanted-behavior) — If the uploaded file exceeds 2 MB, then the user service shall return `400 ErrorCode.AVATAR_TOO_LARGE` and store nothing.
+- **REQ-009** (Unwanted-behavior) — If a caller without `Permission.ADMIN_USER` targets another user's avatar via `/api/users/{id}/avatar`, then the system shall return `403 ErrorCode.FORBIDDEN` and modify nothing.
+
+## Acceptance Criteria
+
+- **REQ-001** — After a successful upload, exactly one object exists at `avatars/{userId}`; a second upload leaves exactly one object (no orphan), verified by a `FileService` interaction test.
+- **REQ-002** — `POST /api/users/me/avatar` with a 100 KB PNG returns `200` and a body whose `avatarUrl` is a non-null string; the persisted `app_users.avatar_object_key` equals `avatars/{userId}`.
+- **REQ-003** — `DELETE /api/users/me/avatar` returns `200`, the object is gone, and the response `avatarUrl` is `null`.
+- **REQ-004** — `GET` profile view for a user with `avatar_object_key IS NULL` returns `avatarUrl: null`; the rendered component shows a 2-letter initials placeholder (Playwright).
+- **REQ-005** — An `ADMIN_USER` caller deleting another user's avatar returns `200`; the target's `avatar_object_key` becomes `NULL`.
+- **REQ-006** — An unauthenticated `POST`/`DELETE` returns `401`; bucket object count is unchanged.
+- **REQ-007** — A `text/plain` or `application/pdf` upload returns `400 UNSUPPORTED_FILE_TYPE`; bucket object count is unchanged.
+- **REQ-008** — A 2.1 MB PNG returns `400 AVATAR_TOO_LARGE`; bucket object count is unchanged.
+- **REQ-009** — A non-admin caller targeting another user's id returns `403 FORBIDDEN`; the target's `avatar_object_key` is unchanged.
+
+## Out of Scope
+
+- Image cropping, resizing, or transformation — the client sends a final image; the server stores it verbatim within the size limit.
+- Avatars for historical `Person` entities — this feature is for `AppUser` accounts only (Person ≠ AppUser).
+- Gravatar / external avatar providers.
+- Animated formats (GIF/WebP) — PNG and JPEG only in v1.
+
+## API / Contract Stub
+
+See [`./api-contract.yaml`](./api-contract.yaml). Endpoints:
+`POST /api/users/me/avatar` (multipart), `DELETE /api/users/me/avatar`,
+`DELETE /api/users/{id}/avatar` (ADMIN_USER). The profile view gains an optional
+`avatarUrl: string | null`. All mutating endpoints carry `@RequirePermission` — `me`
+endpoints require an authenticated session; the `{id}` delete requires `ADMIN_USER`.
+
+## Data Model Changes
+
+- Add nullable `avatar_object_key VARCHAR(512)` to `app_users`.
+- Flyway `V78__add_app_user_avatar_object_key.sql` (next free number — verify against
+  `backend/src/main/resources/db/migration/` on disk before committing).
+- **Rollback:** forward-only. Reverse manually with `ALTER TABLE app_users DROP COLUMN avatar_object_key;`. The MinIO `avatars/` objects are orphaned but harmless on rollback and can be pruned with `mc rm --recursive`.
+
+## Security Considerations
+
+STRIDE categories touched: **Tampering** (mass-assignment of `avatarObjectKey` if bound from
+body), **Elevation of privilege** (a non-admin modifying another user's avatar — REQ-009),
+**Denial of service** (oversized upload — REQ-008), **Information disclosure** (avatar URL
+must not expose a signed key that bypasses auth). No AI agent involved, so ASTRIDE does not
+apply. Full analysis: [`./threat-model.md`](./threat-model.md).
+
+## Open Questions
+
+> All resolved before implementation.
+
+- [x] Public or signed avatar URL? — **Resolved:** served through an authenticated
+  `GET /api/users/{id}/avatar` proxy (same auth as the rest of the API), not a public S3 URL.
+- [x] New bucket or reuse archive bucket? — **Resolved:** reuse the archive bucket under an
+  `avatars/` prefix; see [`./adr-001-avatars-reuse-archive-bucket.md`](./adr-001-avatars-reuse-archive-bucket.md).
+
+## Traceability
+
+| REQ-ID | Task ID(s) | Test ID(s) | Status |
+|---|---|---|---|
+| REQ-001 | T-3 | `UserServiceAvatarTest#storesUnderUserKey`, `…#replaceLeavesNoOrphan` | Planned |
+| REQ-002 | T-4 | `UserAvatarControllerTest#uploadReturnsAvatarUrl` | Planned |
+| REQ-003 | T-5 | `UserAvatarControllerTest#deleteClearsAvatar` | Planned |
+| REQ-004 | T-7 | `avatar-placeholder.svelte.spec.ts` | Planned |
+| REQ-005 | T-6 | `UserAvatarControllerTest#adminDeletesOthersAvatar` | Planned |
+| REQ-006 | T-2 | `UserAvatarControllerTest#unauthenticatedReturns401` | Planned |
+| REQ-007 | T-2 | `UserAvatarControllerTest#rejectsNonImage` | Planned |
+| REQ-008 | T-2 | `UserAvatarControllerTest#rejectsOversize` | Planned |
+| REQ-009 | T-6 | `UserAvatarControllerTest#nonAdminForbiddenOnOthers` | Planned |
+
+Mirrored in [`.specify/rtm.md`](../../rtm.md).
+
+## Persona Review Results
+
+| Persona | Status | Key Findings | Resolved |
+|---|---|---|---|
+| Requirements Engineer | APPROVE | All 9 REQ ids EARS-formed; every limit has an `If` clause. | — |
+| Developer | APPROVE | Reuses `FileService`/`UserService`; `AVATAR_TOO_LARGE` four-site update listed (T-1). | — |
+| Security | APPROVE | REQ-006/008/009 cover authn/DoS/EoP; `avatarObjectKey` server-set only (see threat model T-1). | Yes |
+| DevOps | APPROVE | V78 forward-only with rollback note; no new bucket/env var. | — |
+| UI/UX | APPROVE | Placeholder + loading/error states specified; strings via i18n (T-8). | — |
+| Architect | APPROVE | Bucket-reuse decision captured in ADR-001; no new domain, no boundary crossing. | Yes |

.specify/features/_example/tasks.md

@@ -0,0 +1,47 @@
+# Tasks — Profile picture upload
+
+> Red/Green TDD order: each implementation task is preceded by the failing test that
+> requires it. Task IDs are referenced from `spec.md` → Traceability and from `.specify/rtm.md`.
+> Check off as work lands; reference the issue in each commit (`Refs #<n>`).
+
+## Backend
+
+- [ ] **T-1** Add `ErrorCode.AVATAR_TOO_LARGE` in all four sites at once: `ErrorCode.java`,
+      `frontend/src/lib/shared/errors.ts`, `getErrorMessage()`, `messages/{de,en,es}.json`.
+      *(No new behavior yet — enables REQ-008's error.)* → covers REQ-008 (error plumbing)
+- [ ] **T-2** `@WebMvcTest` `UserAvatarControllerTest`: write failing slice tests —
+      `unauthenticatedReturns401`, `rejectsNonImage` (400 UNSUPPORTED_FILE_TYPE),
+      `rejectsOversize` (400 AVATAR_TOO_LARGE). Then implement `UserAvatarController` +
+      `@RequirePermission` to green. → REQ-006, REQ-007, REQ-008
+- [ ] **T-3** Unit `UserServiceAvatarTest`: failing tests `storesUnderUserKey`,
+      `replaceLeavesNoOrphan`, validation maps to `DomainException`. Then implement
+      `UserService.setAvatar`/`removeAvatar` (mock `FileService`) to green. → REQ-001, REQ-002, REQ-003
+- [ ] **T-4** Flyway `V78__add_app_user_avatar_object_key.sql` (verify next free number on
+      disk) adding nullable `avatar_object_key VARCHAR(512)`; add the column + `@Schema` to
+      `AppUser` / `UserProfileView` (`avatarUrl` derived). Test: repository round-trip. → REQ-002
+- [ ] **T-5** `deleteMyAvatar` controller test + impl (clears key, deletes object, returns
+      `avatarUrl: null`). → REQ-003
+- [ ] **T-6** Admin path: failing tests `adminDeletesOthersAvatar` (200),
+      `nonAdminForbiddenOnOthers` (403). Implement ownership/`ADMIN_USER` check to green. → REQ-005, REQ-009
+- [ ] **T-7** Authenticated proxy `getUserAvatar` streaming endpoint + `Content-Type` +
+      `X-Content-Type-Options: nosniff`; test 200 bytes / 404 when no avatar. → REQ-004 (view side)
+- [ ] **T-A** Run `npm run generate:api` after T-4/T-7 so `avatarUrl` lands in `api.ts`.
+
+## Frontend
+
+- [ ] **T-8** i18n keys for the new strings in `messages/{de,en,es}.json` (button labels,
+      validation errors mapped via `getErrorMessage`). → REQ-007, REQ-008 (UX)
+- [ ] **T-9** Component test `avatar-placeholder.svelte.spec.ts`: failing test asserting
+      initials render when `avatarUrl` is null; implement the placeholder. → REQ-004
+- [ ] **T-10** `/profile` upload control: file picker, client-side type/size pre-check,
+      instant preview, confirm/remove. States: idle/preview/uploading/error/done. → REQ-002, REQ-003
+- [ ] **T-11** Render avatar where names appear (comments, activity feed, `/users/[id]`),
+      falling back to the placeholder. → REQ-004
+- [ ] **T-12** E2E `avatar.spec.ts`: upload → preview → confirm → avatar visible; remove →
+      initials return. → REQ-002, REQ-003, REQ-004
+
+## Cross-cutting
+
+- [ ] **T-13** Set `spring.servlet.multipart.max-file-size` to a 2 MB-matching ceiling so an
+      oversized body is rejected at the container edge (defense in depth for REQ-008).
+- [ ] **T-14** Update `.specify/rtm.md` Status column to `Done` per REQ as each test goes green.

.specify/features/_example/threat-model.md

@@ -0,0 +1,45 @@
+# Threat Model — Profile picture upload
+
+**Feature spec:** [./spec.md](./spec.md)
+**Date:** 2026-06-13
+**Author:** Security persona (worked example)
+
+## Data Flow Diagram (text)
+
+**Actors**
+- Anonymous visitor (unauthenticated)
+- Authenticated user (uploads their own avatar)
+- Admin (`Permission.ADMIN_USER` — may remove others' avatars)
+
+**Trust boundaries**
+- TB-1: Browser ⇄ Caddy (public internet ⇄ DMZ)
+- TB-2: Caddy ⇄ Backend `:8080` (DMZ ⇄ app)
+- TB-3: Backend ⇄ MinIO + PostgreSQL (app ⇄ data plane)
+
+**Data flows**
+- F-1: Browser → [TB-1,TB-2] → `UserAvatarController` : multipart image
+- F-2: `UserService` → [TB-3] → MinIO : object at `avatars/{userId}`
+- F-3: `UserService` → [TB-3] → PostgreSQL : `app_users.avatar_object_key`
+- F-4: Browser → [TB-1,TB-2,TB-3] → MinIO (via proxy GET) : image bytes
+
+## STRIDE
+
+| Threat Category | Asset / Flow | Threat Description | Mitigation | Likelihood × Impact | Status |
+|---|---|---|---|---|---|
+| **S**poofing | F-1 | Unauthenticated caller uploads/deletes an avatar | Session auth required; `@RequirePermission` (REQ-006) | Low × Med | Mitigated |
+| **T**ampering | F-3 | Caller sets `avatarObjectKey` via request body to point at an arbitrary stored object | `avatarObjectKey` is server-set in `UserService` only, never bound from body (CWE-639) | Med × High | Mitigated |
+| **R**epudiation | F-2/F-3 | No record of who changed an avatar | Standard request logging by user UUID (no PII); admin deletions auditable via existing logs | Low × Low | Accepted |
+| **I**nformation disclosure | F-4 | A public/signed S3 URL would let anyone fetch any avatar without auth | Avatars served only through the authenticated proxy `GET /api/users/{id}/avatar`; no public URL | Med × Med | Mitigated |
+| **I**nformation disclosure | F-1 | Malicious file (polyglot) served back with a sniffed content type → stored XSS | Store with a fixed `image/png`/`image/jpeg` content type; proxy sets `Content-Type` + `X-Content-Type-Options: nosniff`; only PNG/JPEG accepted (REQ-007) | Low × High | Mitigated |
+| **D**enial of service | F-1/F-2 | Oversized or many uploads exhaust storage/memory | 2 MB cap enforced before MinIO write + `multipart.max-file-size` ceiling (REQ-008); deterministic key means one object per user | Med × Med | Mitigated |
+| **E**levation of privilege | F-1 | Non-admin removes/replaces another user's avatar via `/{id}` | Ownership check; `ADMIN_USER` required for `/{id}` (REQ-005/REQ-009, 403) | Low × Med | Mitigated |
+
+## ASTRIDE
+
+Not applicable — this feature invokes no AI agent, model, or tool.
+
+## Residual Risk
+
+- **Repudiation (Accepted):** avatar changes are not written to a dedicated audit table.
+  Accepted because the asset is low-value (a self-chosen picture) and request logs already
+  attribute the action to a user UUID. Revisit if avatars ever become trust signals.

.specify/personas/architect.md

@@ -0,0 +1,40 @@
+# Persona — Architect (spec review)
+
+> Concise spec-review checklist. Full character persona:
+> [`.claude/personas/architect.md`](../../.claude/personas/architect.md). This file gates a
+> `spec.md` and its `design.md`/ADRs for systemic fit and long-term consequence.
+
+## Role summary
+
+I check that a feature fits the system's domain boundaries and decision history, and that
+any irreversible choice it makes is captured in an ADR before code is written. I block specs
+that quietly contradict an Accepted ADR, blur a domain boundary, or bake in a decision with
+no recorded rationale.
+
+## Review checklist (PASS / FAIL / QUESTION per item)
+
+1. Does the feature respect the package-by-domain structure — new code in the right domain, no logic smeared across layer packages?
+2. Does it honor the layering rule and the frontend boundary rule, or does it justify and record any new cross-domain edge?
+3. Does any irreversible or contentious decision (new dependency, new domain, data-model shape, response-as-view vs entity, sync vs async side effect) have an ADR in `Proposed`/`Accepted` status under `docs/adr/`?
+4. Does the spec contradict any existing Accepted ADR — and if a change is intended, does it **supersede** that ADR rather than silently diverge?
+5. Is the ADR number the next free one verified against `docs/adr/` on disk?
+6. Does the design reuse an established pattern (in-transaction views per ADR-036, domain events per ADR-006, DatePrecision sharing per ADR-039/040) instead of a novel mechanism for a solved problem?
+7. Are domain terms used per [docs/GLOSSARY.md](../../docs/GLOSSARY.md), keeping the ubiquitous language consistent?
+8. Is the blast radius bounded — does the change avoid forcing edits across unrelated domains, or is the coupling explicitly justified?
+9. Does the data model choose the right precision/constraint level deliberately (e.g. NOT NULL audit fields, CHECK constraints) rather than by default, and is the choice recorded?
+10. Does the spec keep `Person`/`AppUser` (and other established separations) distinct?
+11. Are non-functional consequences (performance of the lazy-fetch path, N+1 risk, index needs) named in `design.md`?
+12. Does `design.md` list the alternatives considered and why they were rejected, not just the chosen path?
+
+## EARS patterns to watch for
+
+- **Ubiquitous** requirements (`The <system> shall <invariant>`) encode architectural invariants — confirm each invariant is enforced at the right layer (DB CHECK, service guard, or type) and not merely asserted in prose.
+- **Optional-feature** requirements signal a new seam/extension point — verify it does not become an unbounded plugin surface without an ADR.
+- Watch for requirements that imply a second source of truth for data that already has an owning domain.
+
+## Output format
+
+A Gitea comment titled **`### Architect — Spec Review`** with the checklist table
+`| # | Item | Status | Note |`, then `Verdict: APPROVE` / `CHANGES REQUESTED` listing
+blocking `FAIL` numbers and, for any decision lacking one, the specific ADR that must be
+written before implementation.

.specify/personas/developer.md

@@ -0,0 +1,39 @@
+# Persona — Developer (spec review)
+
+> Concise spec-review checklist. Full character persona:
+> [`.claude/personas/developer.md`](../../.claude/personas/developer.md). This file gates a
+> `spec.md` for implementability against the real codebase.
+
+## Role summary
+
+I check that a spec can actually be built in *this* codebase without fighting its
+architecture: that it reuses existing services, layers, and error machinery, and that its
+requirements decompose cleanly into red/green TDD tasks. I block specs that invent parallel
+structures or hand-wave the hard integration points.
+
+## Review checklist (PASS / FAIL / QUESTION per item)
+
+1. Does the spec reference existing service interfaces (e.g. `DocumentService`, `FileService`, `UserService`) rather than inventing new ones inconsistent with the current layer structure?
+2. Does it respect the layering rule — no requirement implies a controller touching a repository or a service reaching into another domain's repository?
+3. If it adds a backend domain, does it commit to adding the package to `ArchitectureTest`'s allow-lists?
+4. Are new error conditions expressed as named `ErrorCode`s, with the four-site update (`ErrorCode.java`, `errors.ts`, `getErrorMessage()`, `messages/{de,en,es}.json`) called out as tasks?
+5. Does every entity/DTO field the spec adds get `@Schema(requiredMode = REQUIRED)` where always-populated, and is `npm run generate:api` listed as a task after backend changes?
+6. Are frontend changes inside the correct `$lib/<domain>/` boundary, with any cross-domain import either pre-allowed in `eslint.config.js` or flagged for an explicit allow-entry?
+7. Does each `REQ-NNN` imply a concrete test at the right level (unit / `@WebMvcTest` slice / Playwright E2E per COLLABORATING.md's table) — i.e. is it specified concretely enough to write that test?
+8. Is lazy-loading handled — does any returned entity with a lazy collection get a view (ADR-036) instead of being serialized raw?
+9. Does the design avoid premature abstraction (KISS over DRY) — no new base class/util introduced before a third caller exists?
+10. Are data-model changes expressed as a single forward-only Flyway migration with the next free `V<n>` number verified against disk?
+11. Does the spec avoid backwards-compat shims for code paths that have no existing callers?
+12. Are the requirements decomposable into a red/green-ordered task list — each behavior small enough that a failing test can precede its implementation?
+
+## EARS patterns to watch for
+
+- **Event-driven** requirements must name the exact endpoint/method so the test target is unambiguous (`When POST /api/users/{id}/avatar receives a valid image, the user service shall …`).
+- **Unwanted-behavior** requirements are the ones that become `@WebMvcTest` error-path cases — flag any that lack a stated `ErrorCode` and HTTP status.
+- **Optional-feature** (`Where …`) requirements map to a `@RequirePermission` gate — confirm the permission already exists or is added.
+
+## Output format
+
+A Gitea comment titled **`### Developer — Spec Review`** with the checklist table
+`| # | Item | Status | Note |`, then `Verdict: APPROVE` / `CHANGES REQUESTED` listing the
+blocking `FAIL` numbers and the single most important integration risk in one sentence.

.specify/personas/devops.md

@@ -0,0 +1,39 @@
+# Persona — DevOps (spec review)
+
+> Concise spec-review checklist. Full character persona:
+> [`.claude/personas/devops.md`](../../.claude/personas/devops.md). This file gates a
+> `spec.md` for deployability, migration safety, and CI/observability impact.
+
+## Role summary
+
+I check that a feature can ship to the self-hosted Gitea-Actions / Docker-Compose
+environment without breaking deploys, migrations, or observability. I block specs that add
+a migration with no rollback story, a new env var nobody documented, or a CI step that the
+act_runner cannot execute.
+
+## Review checklist (PASS / FAIL / QUESTION per item)
+
+1. Does the spec include a rollback strategy for any database migration it introduces (forward-only `V<n>` plus the manual DDL to reverse it, or an explicit "no rollback, forward-fix only" statement)?
+2. Is the Flyway migration number the next free `V<n>` verified against disk, not copied from a stale issue body?
+3. Are all new configuration values introduced as documented env vars (added to `.env.example`) and read via env, never hard-coded?
+4. Does any new CI step avoid `actions/(upload|download)-artifact@v4+` and other features the Gitea `act_runner` does not support?
+5. If the spec adds a CI guard, is it self-testing (the regex proves it catches the bad form and ignores the good form), matching the existing guard style?
+6. Does the feature keep the management port (`8081`) / app port (`8080`) separation intact, and not require Caddy to proxy `/actuator/*`?
+7. Are new dependencies pinned, and does the change keep `npm audit --audit-level=high` and Semgrep green?
+8. Does a new external service or sidecar come with a healthcheck and a documented Compose entry, and is bucket/bootstrap logic idempotent (re-deploy must not fail)?
+9. Are new metrics/logs/traces routed through the existing observability stack (Prometheus scrape, Promtail/Loki, Tempo, GlitchTip) rather than a new ad-hoc channel?
+10. Does logging added by the feature stay PII-free and structured (JSON), consistent with the existing log pipeline?
+11. Is the feature backwards-compatible across a rolling deploy, or does the spec state the required downtime/ordering (migrate-then-deploy)?
+12. Does the spec avoid committing secrets, and does any composite-action secret flow follow the unquoted-heredoc env convention (ADR-029)?
+
+## EARS patterns to watch for
+
+- **State-driven** (`While a migration is in progress, the system shall …`) and **Unwanted-behavior** (`If the OCR service is unavailable, then the system shall return OCR_SERVICE_UNAVAILABLE`) requirements encode operational resilience — flag mutating/processing features that lack them.
+- **Optional-feature** (`Where the observability stack is enabled …`) requirements gate optional infra — confirm the feature degrades cleanly when it is off.
+
+## Output format
+
+A Gitea comment titled **`### DevOps — Spec Review`** with the checklist table
+`| # | Item | Status | Note |`, then `Verdict: APPROVE` / `CHANGES REQUESTED` listing
+blocking `FAIL` numbers, with the migration/rollback line called out explicitly when
+relevant.

.specify/personas/requirements-engineer.md

@@ -0,0 +1,43 @@
+# Persona — Requirements Engineer (spec review)
+
+> Concise spec-review checklist. The full character persona (used for issue/PR review via
+> the `review-issue` / `review-pr` skills) lives at
+> [`.claude/personas/req_engineer.md`](../../.claude/personas/req_engineer.md). This file is
+> scoped to one job: gate a `spec.md` before implementation starts.
+
+## Role summary
+
+I own requirement quality: every requirement must be atomic, testable, uniquely identified,
+and written in EARS so an engineer and an AI agent read it the same way. I block specs that
+are ambiguous, unmeasurable, or untraceable — vague requirements become vague code.
+
+## Review checklist (PASS / FAIL / QUESTION per item)
+
+1. Does every requirement have a unique zero-padded `REQ-NNN` ID, scoped to this feature?
+2. Is every requirement written in one of the five EARS patterns (no free-prose "shall" sentences)?
+3. Is each requirement atomic — exactly one testable behavior, no "and"-joined clauses hiding two requirements?
+4. Does every requirement name a concrete system actor (e.g. `the document service`, `the upload form`) rather than a vague "system"?
+5. Does each `REQ-NNN` have at least one matching, **measurable** acceptance criterion (numbers/limits, not adjectives like "fast" or "user-friendly")?
+6. Are all five EARS patterns considered, and is each used where appropriate (not every requirement forced into Ubiquitous)?
+7. Is there an Unwanted-behavior (`If …`) requirement for every error, limit, and rejected input the happy path implies?
+8. Does the `## Out of Scope` section explicitly fence off the nearest tempting scope creep?
+9. Are all `## Open Questions` resolved (or explicitly deferred with an owner) — none left as silent blockers?
+10. Does the spec link the constitution principle(s) it depends on in `## Context & Why`?
+11. Is every `REQ-NNN` present in `.specify/rtm.md` with a Feature, Test, and Status column filled (even if Status = Planned)?
+12. Does the spec reuse existing domain vocabulary from [docs/GLOSSARY.md](../../docs/GLOSSARY.md) (e.g. Person vs AppUser, Chronik vs Aktivität) rather than inventing terms?
+13. Are the User Journey and E2E Scenarios (per COLLABORATING.md) present and consistent with the EARS requirements?
+
+## EARS patterns to watch for (common violations)
+
+- **Ubiquitous** — `The <system> shall <behavior>.` Violation: an invariant written as prose with no "shall".
+- **Event-driven** — `When <trigger>, the <system> shall <behavior>.` Violation: a trigger described but the response left implicit.
+- **State-driven** — `While <state>, the <system> shall <behavior>.` Violation: a state precondition buried inside an Event-driven clause.
+- **Optional-feature** — `Where <feature is present>, the <system> shall <behavior>.` Violation: a permission-/flag-gated behavior written as Ubiquitous, so it appears mandatory.
+- **Unwanted-behavior** — `If <undesired condition>, then the <system> shall <response>.` Violation: missing entirely — the single most common gap. Every limit and rejected input needs one.
+
+## Output format
+
+A Gitea comment titled **`### Requirements Engineer — Spec Review`** containing the
+checklist as a table `| # | Item | Status | Note |` with `PASS` / `FAIL` / `QUESTION` per
+row, then a short verdict line: `Verdict: APPROVE` or `Verdict: CHANGES REQUESTED` with the
+blocking `FAIL` numbers listed.

.specify/personas/security.md

@@ -0,0 +1,42 @@
+# Persona — Security (spec review)
+
+> Concise spec-review checklist. Full character persona (Nora "NullX" Steiner):
+> [`.claude/personas/security_expert.md`](../../.claude/personas/security_expert.md). This
+> file gates a `spec.md` and its `threat-model.md` before implementation.
+
+## Role summary
+
+I read every spec adversarially: I assume the requirement will be hit by an unauthenticated
+attacker, a logged-in user attacking another user's data, and malicious input. I block specs
+whose mutating endpoints, file handling, or audit trails leave a hole that the happy-path
+requirements never mention.
+
+## Review checklist (PASS / FAIL / QUESTION per item)
+
+1. Are **all** state-mutating endpoints (`POST/PUT/PATCH/DELETE`) covered by an Unwanted-behavior EARS clause for unauthenticated **and** unauthorized access, each naming the `Permission` and the response code?
+2. Does every mutating endpoint name the `@RequirePermission(Permission.X)` it will carry — and is that permission the least privilege that works?
+3. Are audit fields (`createdBy`/`updatedBy`) specified as server-set from the session principal, with an explicit requirement forbidding them in the request body (mass-assignment / authorship-forgery, CWE-639)?
+4. Is every IDOR surface addressed — does fetching/mutating a child resource verify it belongs to the caller's accessible parent (e.g. JourneyItem → Geschichte), with a requirement and a test?
+5. Is all untrusted text (user input, OCR/import-derived) specified to render via default escaping, never `{@html}` (CWE-79)?
+6. For file uploads: are content-type allow-list, size limit, and magic-byte/extension validation specified as requirements with concrete numbers and an `ErrorCode`?
+7. Does the spec avoid leaking entity internals (email, password hash, group graph) in any response — i.e. does it use a view, not a raw `AppUser`/entity?
+8. Are concurrency conflicts (optimistic locking) specified to surface as `conflict()` (409), never a raw 500 exposing Hibernate internals (CWE-209)?
+9. Does the `threat-model.md` exist and cover the relevant STRIDE categories for each new data flow and trust boundary?
+10. If the feature invokes an AI agent/tool (OCR/NLP/LLM), does the threat model cover the ASTRIDE extensions (prompt injection, context poisoning, unsafe tool invocation, reasoning subversion)?
+11. Are secrets (tokens, DSNs, passwords) sourced only from env vars, with none introduced into the repo, config, or logs?
+12. Does logging for this feature exclude PII beyond a stable UUID (no names, emails, document/transcription content)?
+13. Does a new runtime dependency (if any) have an ADR and a clean `npm audit` / Semgrep status?
+
+## EARS patterns to watch for
+
+- The **Unwanted-behavior** pattern (`If <attacker condition>, then the <system> shall <safe response>`) is *the* security pattern. Every auth, authz, validation, and limit case must appear as one. A spec with zero `If` requirements on a mutating endpoint is an automatic `FAIL`.
+- **Optional-feature** (`Where the caller has Permission.X …`) requirements encode the authorization model — verify the gate is on the *write*, not just the read.
+- Watch for **Ubiquitous** requirements that quietly assume trust ("The system shall store the uploaded file") with no companion `If` clause validating it first.
+
+## Output format
+
+A Gitea comment titled **`### Security — Spec Review`** with the checklist table
+`| # | Item | Status | Note |`, each `FAIL` tagged with its CWE where applicable, then
+`Verdict: APPROVE` / `CHANGES REQUESTED` listing blocking `FAIL` numbers. Security `FAIL`s
+are hard blockers — a spec does not proceed until each is resolved or risk-accepted in the
+threat model.

.specify/personas/ui-ux.md

@@ -0,0 +1,39 @@
+# Persona — UI/UX (spec review)
+
+> Concise spec-review checklist. Full character persona:
+> [`.claude/personas/ui_expert.md`](../../.claude/personas/ui_expert.md). This file gates a
+> `spec.md` for user-facing features against the project's design system and audience split.
+
+## Role summary
+
+I check that a user-facing feature is usable by *this* audience — older transcribers on
+laptops/tablets and younger readers on phones — and that it uses the established design
+tokens, components, and i18n rather than reinventing them. I block specs whose UI is
+described in adjectives instead of states, or that ignore accessibility and responsiveness.
+
+## Review checklist (PASS / FAIL / QUESTION per item)
+
+1. Does the spec describe every interaction **state** (loading, empty, error, success, disabled), not just the happy path?
+2. Are user-facing strings specified to go through Paraglide i18n with keys added to `messages/{de,en,es}.json` — no hard-coded German/English literals?
+3. Does it reuse the established component library and patterns (`BackButton`, the card pattern, `brand-navy`/`brand-mint` tokens, `font-serif`/`font-sans`) rather than introducing new one-off styles?
+4. Is the responsive behavior specified per the device split — Critical for the reader/phone path, at least Minor for the author/laptop path — with concrete breakpoints, not "responsive"?
+5. Are error states mapped to `getErrorMessage(code)` output so the user sees a localized message, never a raw code or stack?
+6. Is every interactive element keyboard-reachable and screen-reader-labeled (the project runs `@axe-core/playwright`)?
+7. Are acceptance criteria measurable (e.g. "image preview appears within 1 of selection", "tap target ≥ 44px"), not adjectival ("looks clean")?
+8. Does the spec define an E2E Playwright scenario (per COLLABORATING.md) for each primary user journey step?
+9. For destructive or irreversible actions, is a confirmation/undo affordance specified?
+10. Does any uploaded/derived content render through default escaping (no `{@html}`), and are images given alt text / dimensions to avoid layout shift?
+11. Does the feature respect existing navigation (live DOM nav, real routes — verify route names against the running app, since CLAUDE.md route lists can be stale)?
+12. Is dark-mode / token theming respected (uses semantic tokens like `bg-surface`/`text-ink-3`, not raw palette constants)?
+
+## EARS patterns to watch for
+
+- **State-driven** (`While the upload is in progress, the upload form shall show a progress indicator`) requirements capture UI states — a UI spec with no `While` requirements usually means the loading/disabled states were forgotten.
+- **Event-driven** (`When the user selects an image, the form shall render a preview`) requirements map directly to Playwright steps — confirm each has a measurable acceptance criterion.
+- **Unwanted-behavior** (`If the selected file exceeds the size limit, then the form shall show a localized error and not upload`) requirements cover client-side validation feedback.
+
+## Output format
+
+A Gitea comment titled **`### UI/UX — Spec Review`** with the checklist table
+`| # | Item | Status | Note |`, then `Verdict: APPROVE` / `CHANGES REQUESTED` listing
+blocking `FAIL` numbers and the single biggest usability/accessibility gap in one sentence.

.specify/rtm.md

@@ -0,0 +1,125 @@
+# Requirements Traceability Matrix (RTM)
+
+> Living document. One row per `REQ-NNN` across all in-flight and shipped features. The spec
+> itself lives in the **Gitea issue** (issue-only — there is no committed `spec.md`); this
+> matrix is the part of the spec that *is* committed: it links each requirement to its issue,
+> the code that implements it, and the test(s) that prove it — so any requirement traces end
+> to end, and any orphan (a requirement with no test) is visible on `main`.
+
+## How to update
+
+1. When a feature's issue is approved (via `/review-issue`), add one row per `REQ-NNN` with the
+   `Issue` set to the Gitea issue number and `Status: Planned`. Commit these rows on the feature
+   branch (they merge with the feature's PR).
+2. As tasks land, fill `Implementation File(s)` + `Test(s)` and flip `Status` →
+   `In progress` → `Done`.
+3. `REQ-ID`s are **scoped per feature**, so always read them together with the `Issue` column —
+   `REQ-001` for issue #142 is not `REQ-001` for issue #150.
+4. The `sdd-gate.yml` CI job (`rtm-check`) warns (non-blocking, for now) when a row is missing
+   its `Issue` or `Test(s)`. It flips to blocking once adoption settles (see the workflow's TODO).
+
+## Status legend
+
+`Planned` · `In progress` · `Done` · `Deferred`
+
+## Matrix
+
+| REQ-ID | Requirement Summary | Issue | Feature | Implementation File(s) | Test(s) | Status |
+|---|---|---|---|---|---|---|
+| REQ-001 | Store avatar at `avatars/{userId}`, overwrite | #example | profile-picture-upload (_example) | `UserService` (planned) | `UserServiceAvatarTest#storesUnderUserKey`, `#replaceLeavesNoOrphan` | Planned |
+| REQ-002 | Upload self avatar → 200 + avatarUrl | #example | profile-picture-upload (_example) | `UserAvatarController`, `UserService` (planned) | `UserAvatarControllerTest#uploadReturnsAvatarUrl` | Planned |
+| REQ-003 | Delete self avatar → avatarUrl null | #example | profile-picture-upload (_example) | `UserAvatarController` (planned) | `UserAvatarControllerTest#deleteClearsAvatar` | Planned |
+| REQ-004 | No avatar → null + initials placeholder | #example | profile-picture-upload (_example) | `UserProfileView`, avatar component (planned) | `avatar-placeholder.svelte.spec.ts` | Planned |
+| REQ-005 | ADMIN_USER may delete others' avatar | #example | profile-picture-upload (_example) | `UserAvatarController` (planned) | `UserAvatarControllerTest#adminDeletesOthersAvatar` | Planned |
+| REQ-006 | Unauthenticated → 401, store nothing | #example | profile-picture-upload (_example) | `SecurityConfig`, controller (planned) | `UserAvatarControllerTest#unauthenticatedReturns401` | Planned |
+| REQ-007 | Non-image → 400 UNSUPPORTED_FILE_TYPE | #example | profile-picture-upload (_example) | `UserService` (planned) | `UserAvatarControllerTest#rejectsNonImage` | Planned |
+| REQ-008 | Over 2 MB → 400 AVATAR_TOO_LARGE | #example | profile-picture-upload (_example) | `UserService`, `ErrorCode` (planned) | `UserAvatarControllerTest#rejectsOversize` | Planned |
+| REQ-009 | Non-admin on others → 403 FORBIDDEN | #example | profile-picture-upload (_example) | `UserAvatarController` (planned) | `UserAvatarControllerTest#nonAdminForbiddenOnOthers` | Planned |
+| REQ-001 | Render dated entry via shared `formatDocumentDate` (de/en/es) | #778 | timeline-date-label | `frontend/src/lib/timeline/dateLabel.ts` | `dateLabel.spec.ts` › `renders a DAY date localized in German`, `renders a SEASON date with the German season word`, `delegates a same-year RANGE to formatDocumentDate` | Done |
+| REQ-002 | Non-UNKNOWN + non-empty date → shared label, `raw=null`, `getLocale()` | #778 | timeline-date-label | `frontend/src/lib/timeline/dateLabel.ts` | `dateLabel.spec.ts` › `renders a DAY date localized in German`, `renders a DAY date localized in English` | Done |
+| REQ-003 | `UNKNOWN` → `null` (no chip) | #778 | timeline-date-label | `frontend/src/lib/timeline/dateLabel.ts` | `dateLabel.spec.ts` › `returns null for UNKNOWN precision even with a date`, `returns null for UNKNOWN precision without a date` | Done |
+| REQ-004 | `null`/`undefined`/`''` eventDate → `null`, no formatter call | #778 | timeline-date-label | `frontend/src/lib/timeline/dateLabel.ts` | `dateLabel.spec.ts` › `returns null for APPROX with a null eventDate, without calling the formatter`, `returns null for DAY with an empty-string eventDate`, `treats undefined eventDateEnd identically to null for RANGE` | Done |
+| REQ-005 | No rendering logic outside `documentDate.ts` | #778 | timeline-date-label | `frontend/src/lib/timeline/dateLabel.ts` (façade) | `dateLabel.spec.ts` › `delegates a same-year RANGE to formatDocumentDate` (asserts byte-identical delegation) | Done |
+| REQ-006 | `timeline` in coverage `include` (80% branch gate) | #778 | timeline-date-label | `frontend/vite.config.ts` | coverage `include` now lists `src/lib/timeline/**`; covered by all `dateLabel.spec.ts` cases | Done |
+
+<!-- Append real features below this line, one row per REQ-NNN, with the real issue number. Keep the header row above. -->
+| REQ-001 | family-member Person with birthDate → 1 BIRTH event, precision passed through | #776 | derive-person-life-events | `timeline/TimelineEventService#buildBirthEvents` | `DerivedEventsAssemblyTest#should_emit_one_geburt_for_person_with_birthdate`, `#should_pass_birth_precision_through_unchanged` | Done |
+| REQ-002 | family-member Person with deathDate → 1 DEATH event | #776 | derive-person-life-events | `timeline/TimelineEventService#buildDeathEvents` | `DerivedEventsAssemblyTest#should_emit_one_tod_for_person_with_deathdate`, `#should_emit_one_tod_and_zero_geburt_for_person_with_deathdate_only` | Done |
+| REQ-003 | null birthDate → 0 Geburt events | #776 | derive-person-life-events | `timeline/TimelineEventService#buildBirthEvents` | `DerivedEventsAssemblyTest#should_emit_zero_tod_when_person_has_birthdate_but_no_deathdate`, `#should_emit_one_tod_and_zero_geburt_for_person_with_deathdate_only` | Done |
+| REQ-004 | null deathDate → 0 Tod events; no dates → 0 events | #776 | derive-person-life-events | `timeline/TimelineEventService#buildDeathEvents` | `DerivedEventsAssemblyTest#should_emit_no_events_for_person_with_neither_date` | Done |
+| REQ-005 | SPOUSE_OF edge with fromYear → MARRIAGE event, eventDate={fromYear}-01-01, precision=YEAR | #776 | derive-person-life-events | `timeline/TimelineEventService#buildMarriageEvents` | `DerivedEventsAssemblyTest#should_emit_one_heirat_for_spouse_edge_with_fromYear` | Done |
+| REQ-006 | SPOUSE_OF edge with null fromYear → MARRIAGE emitted, eventDate=null, precision=UNKNOWN | #776 | derive-person-life-events | `timeline/TimelineEventService#buildMarriageEvents` | `DerivedEventsAssemblyTest#should_emit_unknown_precision_heirat_when_fromYear_is_null` | Done |
+| REQ-007 | exactly one MARRIAGE per SPOUSE_OF row (dedup on relationship id) | #776 | derive-person-life-events | `timeline/TimelineEventService#buildMarriageEvents` | `DerivedEventsAssemblyTest#should_emit_exactly_one_heirat_when_both_spouses_in_scope`, `#should_emit_two_heirat_for_person_married_to_two_partners` | Done |
+| REQ-008 | synthetic prefixed ids (birth:/death:/marriage:), never parseable as UUID | #776 | derive-person-life-events | `timeline/TimelineEventService#buildBirthEvents,#buildDeathEvents,#buildMarriageEvents` | `DerivedEventsAssemblyTest#should_mint_prefixed_synthetic_ids_never_uuid` | Done |
+| REQ-009 | every derived event: derived=true, type=PERSONAL, non-null derivedType, non-UUID id | #776 | derive-person-life-events | `timeline/TimelineEventService` | structural invariants asserted inline in every event test | Done |
+| REQ-010 | every derived event: non-null non-blank primaryPersonName; Heirat also non-null non-blank relatedPersonName | #776 | derive-person-life-events | `timeline/TimelineEventService#buildBirthEvents,#buildDeathEvents,#buildMarriageEvents` | `DerivedEventsAssemblyTest#should_emit_heirat_with_displayname_for_both_spouses` | Done |
+| REQ-011 | exactly one call to findAllFamilyMembers() and one to findAllSpouseEdges() — no N+1 | #776 | derive-person-life-events | `timeline/TimelineEventService#assembleDerivedEvents`, `relationship/RelationshipService#findAllSpouseEdges` | test structure: only batch-fetch mocks used (no per-person stubs) | Done |
+| REQ-012 | familyMember=false persons excluded from Geburt/Tod assembly | #776 | derive-person-life-events | `timeline/TimelineEventService#assembleDerivedEvents` (via PersonService.findAllFamilyMembers) | `DerivedEventsAssemblyTest#should_exclude_non_family_member_persons_from_derived_events` | Done |
+| REQ-013 | SPOUSE_OF edge with one non-family-member spouse still emits 1 MARRIAGE event | #776 | derive-person-life-events | `timeline/TimelineEventService#buildMarriageEvents` | `DerivedEventsAssemblyTest#should_emit_heirat_when_one_spouse_is_not_family_member` | Done |
+| REQ-014 | empty family-member list → empty result, no error | #776 | derive-person-life-events | `timeline/TimelineEventService#assembleDerivedEvents` | `DerivedEventsAssemblyTest#should_emit_zero_events_when_no_family_members` | Done |
+| REQ-015 | assembleDerivedEvents() annotated @Transactional(readOnly=true) | #776 | derive-person-life-events | `timeline/TimelineEventService#assembleDerivedEvents` | code-review check (annotation visible in source) | Done |
+| REQ-016 | no PII (names, dates) in log statements — only aggregate counts | #776 | derive-person-life-events | `timeline/TimelineEventService#assembleDerivedEvents` | log-audit: single log.debug with result.size() and persons.size() only | Done |
+| REQ-001 | GET /api/timeline requires READ_ALL permission; 401 unauthenticated, 403 wrong permission | #777 | timeline-assembly | `timeline/TimelineController#getTimeline` | `TimelineControllerTest#returns_401_when_unauthenticated`, `#returns_403_when_authenticated_without_read_all`, `#returns_200_with_read_all_permission` | Done |
+| REQ-002 | within-band sort: precision rank desc (DAY>MONTH>SEASON>YEAR>APPROX), then date asc, then title alpha, then id tiebreak | #777 | timeline-assembly | `timeline/TimelineService#WITHIN_BAND_ORDER` | `TimelineServiceTest#within_band_order_day_precision_sorts_before_year`, `#within_band_order_same_precision_and_date_sorts_alphabetically`, `#within_band_order_same_title_uses_document_id_as_tiebreak`, `#test5_day_precision_sorts_before_year_in_same_year_band`, `#test6_same_precision_same_date_sorted_alphabetically_by_title` | Done |
+| REQ-003 | null eventDate OR UNKNOWN precision → undated bucket (never in a year band) | #777 | timeline-assembly | `timeline/TimelineService#bucketByYear` | `TimelineServiceTest#test3a_null_date_letter_goes_to_undated`, `#test3b_unknown_precision_letter_goes_to_undated` | Done |
+| REQ-004 | RANGE events placed in start-year band only; null eventDateEnd does not crash; start year outside [fromYear,toYear] → excluded | #777 | timeline-assembly | `timeline/TimelineService#assembleCuratedEvents` | `TimelineServiceTest#test7a_range_event_placed_only_in_start_year_band`, `#test7b_range_event_with_null_eventDateEnd_does_not_crash`, `#test8_range_event_excluded_when_start_year_before_fromYear`, `#test15_range_event_start_year_equal_to_fromYear_is_included` | Done |
+| REQ-005 | null sender and null senderText on a document → senderName="" in the TimelineEntryDTO | #777 | timeline-assembly | `timeline/TimelineService#toLetterEntry` | `TimelineServiceTest#test4_letter_with_null_sender_and_null_senderText_produces_empty_names` | Done |
+| REQ-006 | personId filter: include document when personId is sender OR receiver | #777 | timeline-assembly | `timeline/TimelineService#fetchDocuments` | `TimelineServiceTest#test11_personId_scoping_deduplicates_letter_appearing_as_sender_and_receiver` | Done |
+| REQ-007 | documents domain letters always included (no type filter applied to LETTER kind) | #777 | timeline-assembly | `timeline/TimelineService#fetchDocuments`, `#assemble` | `TimelineServiceTest#test9a_type_filter_does_not_exclude_letters_but_excludes_wrong_type_events`, `#test1_empty_archive_returns_empty_dto`, `#test2_one_year_letter_returns_one_year_band` | Done |
+| REQ-008 | personId filter dedup: sender+receiver same person → document appears exactly once | #777 | timeline-assembly | `timeline/TimelineService#fetchDocuments` | `TimelineServiceTest#test11_personId_scoping_deduplicates_letter_appearing_as_sender_and_receiver` | Done |
+| REQ-009 | type filter applies to events only; letters (LETTER kind) always pass | #777 | timeline-assembly | `timeline/TimelineService#assembleCuratedEvents`, `#assembleDerivedEventsLayer` | `TimelineServiceTest#test9a_type_filter_does_not_exclude_letters_but_excludes_wrong_type_events` | Done |
+| REQ-010 | generation filter: PersonService.getPersonsByGeneration(N) used to build person-id set; filters all three layers | #777 | timeline-assembly | `timeline/TimelineService#assemble`, `person/PersonService#getPersonsByGeneration`, `person/PersonRepository#findByGeneration` | `TimelineServiceTest#test9b_generation_filter_includes_letter_when_sender_matches_generation`, `TimelineServiceIntegrationTest#findByGeneration_returns_matching_persons`, `#findByGeneration_returns_empty_list_not_npe_when_no_match`, `#findByGeneration_does_not_return_null_generation_persons` | Done |
+| REQ-011 | fromYear/toYear inclusive year-range filter; single-year window (fromYear==toYear); one-sided filter (fromYear only) | #777 | timeline-assembly | `timeline/TimelineService#passesYearFilter` | `TimelineServiceTest#test9c_fromYear_toYear_inclusive_single_year_window`, `#test16_fromYear_without_toYear_returns_all_items_from_that_year_onwards` | Done |
+| REQ-012 | combined filters AND logic — entry must pass all active filters | #777 | timeline-assembly | `timeline/TimelineService#assemble` | `TimelineServiceTest#test10_adversarial_and_logic_neither_event_passes_both_filters`, `#test12_personId_plus_generation_filter_returns_empty_when_generations_do_not_match` | Done |
+| REQ-013 | empty archive (no events, no persons, no documents) → TimelineDTO { years=[], undated=[] } | #777 | timeline-assembly | `timeline/TimelineService#assemble` | `TimelineServiceTest#test1_empty_archive_returns_empty_dto` | Done |
+| REQ-014 | unauthenticated request → 401 Unauthorized | #777 | timeline-assembly | `timeline/TimelineController#getTimeline` | `TimelineControllerTest#returns_401_when_unauthenticated` | Done |
+| REQ-015 | authenticated without READ_ALL → 403 Forbidden | #777 | timeline-assembly | `timeline/TimelineController#getTimeline` | `TimelineControllerTest#returns_403_when_authenticated_without_read_all` | Done |
+| REQ-016 | fromYear > toYear → 400 Bad Request | #777 | timeline-assembly | `timeline/TimelineService#assemble` | `TimelineServiceTest#fromYear_greater_than_toYear_throws_bad_request`, `TimelineControllerTest#returns_400_when_fromYear_greater_than_toYear` | Done |
+| REQ-017 | generation < 0 → 400 Bad Request (@Min(0) on controller param) | #777 | timeline-assembly | `timeline/TimelineController#getTimeline` | `TimelineControllerTest#returns_400_when_generation_is_negative` | Done |
+| REQ-018 | unknown EventType string → 400 Bad Request (Spring enum binding) | #777 | timeline-assembly | `timeline/TimelineController#getTimeline` | `TimelineControllerTest#returns_400_on_bad_type_value` | Done |
+| REQ-019 | unknown personId → 404 Not Found | #777 | timeline-assembly | `timeline/TimelineService#assemble` | `TimelineControllerTest#returns_404_when_person_not_found` | Done |
+| REQ-020 | null-generation persons excluded from generation-filter results | #777 | timeline-assembly | `person/PersonRepository#findByGeneration` | `TimelineServiceTest#test13_null_generation_sender_not_returned_by_generation_filter`, `TimelineServiceIntegrationTest#findByGeneration_does_not_return_null_generation_persons` | Done |
+| REQ-001 | `/zeitstrahl` renders the global timeline for authenticated users, personId undefined | #779 | zeitstrahl-global-view | `frontend/src/routes/zeitstrahl/+page.server.ts`, `+page.svelte` | `zeitstrahl/page.server.test.ts#fetches GET /api/timeline and returns { timeline } on ok` | Done |
+| REQ-002 | server-load fetches GET /api/timeline via createApiClient, returns { timeline }, no client fetch | #779 | zeitstrahl-global-view | `frontend/src/routes/zeitstrahl/+page.server.ts` | `zeitstrahl/page.server.test.ts#fetches GET /api/timeline and returns { timeline } on ok` | Done |
+| REQ-003 | render bands + entries in DTO order, no client re-sort/re-bucket | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/YearBand.svelte`, `TimelineView.svelte` | `YearBand.svelte.spec.ts#renders entries in DTO order`, `TimelineView.svelte.spec.ts#renders the timeline as a single <ol>` | Done |
+| REQ-004 | ≥1024px centered axis, letters alternating left/right | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/YearBand.svelte` (data-side CSS), `TimelineView.svelte` | `TimelineView.svelte.spec.ts#places consecutive letter cards on alternating sides`, `e2e/zeitstrahl.spec.ts` | Done |
+| REQ-005 | <1024px single left axis, no overflow down to 320px | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/YearBand.svelte`, `LetterCard.svelte` | `e2e/zeitstrahl.spec.ts#no horizontal overflow at 320px with long correspondent names` | Done |
+| REQ-006 | single `<ol>` chronological; each band a `<section>` with sticky `<h2>` at top:4rem | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/TimelineView.svelte`, `YearBand.svelte` | `TimelineView.svelte.spec.ts#renders the timeline as a single <ol>`, `YearBand.svelte.spec.ts#sticky h2 at top:4rem` | Done |
+| REQ-007 | derived entry → centered family pill with glyph + German derivedType label | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/EventPill.svelte`, `eventCardConfig.ts` | `EventPill.svelte.spec.ts#derived marriage/birth/death`, `eventCardConfig.spec.ts` | Done |
+| REQ-008 | curated PERSONAL pill; edit affordance only when eventId != null | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/EventPill.svelte` | `EventPill.svelte.spec.ts#edit affordance for curated with eventId`, `#no edit affordance when eventId is null`, `#no edit affordance for a derived event` | Done |
+| REQ-009 | HISTORICAL → full-width band once in eventDate year; RANGE span pill with Zeitraum aria-label | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/WorldBand.svelte` | `WorldBand.svelte.spec.ts#RANGE span pill 1914–1918 with a Zeitraum aria-label` | Done |
+| REQ-010 | RANGE with null eventDateEnd → start-year label, no span pill, no crash | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/WorldBand.svelte` | `WorldBand.svelte.spec.ts#degrades a RANGE with no end to the start year` | Done |
+| REQ-011 | band ≤12 letters → individual LetterCards | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/YearBand.svelte` | `YearBand.svelte.spec.ts#renders each letter as a card`, `TimelineView.svelte.spec.ts` | Done |
+| REQ-012 | band >12 letters → single YearLetterStrip with count + 12-month sparkline + expand toggle | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/YearLetterStrip.svelte`, `timelineDensity.ts` | `YearLetterStrip.svelte.spec.ts`, `YearBand.svelte.spec.ts#renders a single strip`, `timelineDensity.spec.ts#isDense` | Done |
+| REQ-013 | every dated entry renders date via timelineDateLabel; null → no chip | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/LetterCard.svelte` | `LetterCard.svelte.spec.ts#renders the precision date exactly`, `#renders no date chip when timelineDateLabel returns null` | Done |
+| REQ-014 | empty senderName/receiverName → "Unbekannt" placeholder, never a bare arrow | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/LetterCard.svelte` | `LetterCard.svelte.spec.ts#shows "Unbekannt" for an empty sender`, `#empty receiver` | Done |
+| REQ-015 | interior empty-year run → one folded GapSpan (single year if length 1) | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/TimelineView.svelte`, `GapSpan.svelte` | `TimelineView.svelte.spec.ts#folds an interior run of empty years`, `#single empty interior year`, `GapSpan.svelte.spec.ts` | Done |
+| REQ-016 | undated non-empty → final "Ohne Datum" section; empty → absent from DOM | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/TimelineView.svelte` | `TimelineView.svelte.spec.ts#renders an "Ohne Datum" section`, `#omits the "Ohne Datum" section when empty` | Done |
+| REQ-017 | years + undated both empty → timeline.empty_state message | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/TimelineView.svelte` | `TimelineView.svelte.spec.ts#shows the empty state and no ol` | Done |
+| REQ-018 | each layer carries a non-color redundant cue (glyph aria-hidden + sr-only label) | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/eventCardConfig.ts`, `EventPill.svelte`, `WorldBand.svelte` | `TimelineView.svelte.spec.ts#redundant non-color cue label`, `EventPill.svelte.spec.ts#wraps the glyph aria-hidden`, `WorldBand.svelte.spec.ts#world glyph` | Done |
+| REQ-019 | every accent meets WCAG AA in light + dark; HISTORICAL label falls back to text-ink-2 | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/WorldBand.svelte` (text-ink-2) | manual pre-merge contrast check (both ratios recorded in PR) | Done |
+| REQ-020 | LetterCard link ≥44px touch target + visible focus-visible ring | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/LetterCard.svelte` | `LetterCard.svelte.spec.ts#has a touch target of at least 44px` | Done |
+| REQ-021 | OCR/import text rendered via `{...}` escaping; no `{@html}` in lib/timeline/ | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/*` | code review + `grep -r '@html' frontend/src/lib/timeline/` → zero; `LetterCard.svelte.spec.ts` | Done |
+| REQ-022 | non-ok load → error(status, mapped); 401 → redirect('/login'); never raw JSON | #779 | zeitstrahl-global-view | `frontend/src/routes/zeitstrahl/+page.server.ts` | `zeitstrahl/page.server.test.ts#redirects to /login on 401`, `#404`, `#500`, `#403` | Done |
+| REQ-023 | LetterCard href is exactly /documents/{documentId}, no target | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/LetterCard.svelte` | `LetterCard.svelte.spec.ts#links to exactly /documents/{documentId} with no target` | Done |
+| REQ-024 | all user-facing strings via Paraglide keys (layer/derived labels localized per locale) | #779 | zeitstrahl-global-view | `frontend/messages/{de,en,es}.json` | `messages.spec.ts#timeline layer/derived labels are localized per locale`, Paraglide compile | Done |
+| REQ-025 | personId prop declared but undefined in global view; not passed to leaf cards | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/TimelineView.svelte` | `TimelineView.svelte.spec.ts#renders all years and undated entries with personId undefined` | Done |
+| REQ-026 | month-bucket helpers in $lib/shared/utils/monthBuckets.ts; no lib/timeline → lib/document import | #779 | zeitstrahl-global-view | `frontend/src/lib/shared/utils/monthBuckets.ts` | `monthBuckets.spec.ts` (relocated) + eslint boundary + `grep lib/document` → zero | Done |
+| REQ-027 | monthHistogram returns 12 MonthBuckets for the band year via shared fillDensityGaps | #779 | zeitstrahl-global-view | `frontend/src/lib/timeline/timelineDensity.ts` | `timelineDensity.spec.ts#monthHistogram` | Done |
+| REQ-001 | curator with WRITE_ALL granted access to /zeitstrahl/events/new + /[id]/edit | #781 | timeline-curator-forms | `frontend/src/routes/zeitstrahl/events/new/+page.server.ts`, `[id]/edit/+page.server.ts` | `new/page.server.spec.ts#allows a curator with WRITE_ALL`, `[id]/edit/page.server.spec.ts#seeds the form with the event on an ok GET` | Done |
+| REQ-002 | unauthenticated (null user) → 403 (null-user guard before groups deref) | #781 | timeline-curator-forms | `frontend/src/routes/zeitstrahl/events/new/+page.server.ts`, `[id]/edit/+page.server.ts` | `new/page.server.spec.ts#throws 403 for an unauthenticated (null) user`, `[id]/edit/page.server.spec.ts#throws 403 for an unauthenticated (null) user` | Done |
+| REQ-003 | authenticated without WRITE_ALL → 403 | #781 | timeline-curator-forms | `frontend/src/routes/zeitstrahl/events/new/+page.server.ts` (hasWriteAll) | `new/page.server.spec.ts#throws 403 for an authenticated user without WRITE_ALL`, `[id]/edit/page.server.spec.ts#throws 403 for a user without WRITE_ALL` | Done |
+| REQ-004 | valid create → POST + redirect to resolved target | #781 | timeline-curator-forms | `frontend/src/routes/zeitstrahl/events/new/+page.server.ts` (save), `lib/timeline/eventFormServer.ts#toEventRequest` | `new/page.server.spec.ts#posts a TimelineEventRequest and redirects on success` | Done |
+| REQ-005 | valid edit → PUT + redirect to resolved target | #781 | timeline-curator-forms | `frontend/src/routes/zeitstrahl/events/[id]/edit/+page.server.ts` (save) | `[id]/edit/page.server.spec.ts#updates via PUT (with version) and redirects on success` | Done |
+| REQ-006 | confirmed delete → DELETE + redirect | #781 | timeline-curator-forms | `frontend/src/routes/zeitstrahl/events/[id]/edit/+page.server.ts` (delete), `lib/timeline/EventForm.svelte` (getConfirmService) | `[id]/edit/page.server.spec.ts#deletes via DELETE and redirects to the resolved target on success` | Done |
+| REQ-007 | non-ok DELETE → surface mapped error, no redirect | #781 | timeline-curator-forms | `frontend/src/routes/zeitstrahl/events/[id]/edit/+page.server.ts` (delete) | `[id]/edit/page.server.spec.ts#returns fail(status) and does not redirect when DELETE is not ok` | Done |
+| REQ-008 | precision = RANGE → end-date field visible | #781 | timeline-curator-forms | `frontend/src/lib/shared/primitives/DatePrecisionField.svelte`, `lib/timeline/EventForm.svelte` | `EventForm.svelte.spec.ts#reveals the end-date field when precision is RANGE`, `WhoWhenSection.svelte.spec.ts#reveals the end-date field when precision is RANGE` | Done |
+| REQ-009 | precision ≠ RANGE → end-date hidden, eventDateEnd submitted null | #781 | timeline-curator-forms | `frontend/src/lib/shared/primitives/DatePrecisionField.svelte`, `lib/timeline/eventFormServer.ts#parseEventForm` | `EventForm.svelte.spec.ts#hides the end-date field when precision is YEAR`, `new/page.server.spec.ts#sends eventDateEnd: null when precision is not RANGE` | Done |
+| REQ-010 | blank title → localized required error, no nav, picker values preserved | #781 | timeline-curator-forms | `frontend/src/lib/timeline/eventFormServer.ts#validateEventForm`, `EventForm.svelte` | `EventForm.svelte.spec.ts#shows a required-field error when title is blank`, `new/page.server.spec.ts#returns fail(400) with preserved picker arrays on blank title` | Done |
+| REQ-011 | blank title + date → both errors via per-field aria-invalid | #781 | timeline-curator-forms | `frontend/src/lib/timeline/eventFormServer.ts#validateEventForm` | `new/page.server.spec.ts#surfaces both title and date errors when both blank` | Done |
+| REQ-012 | unknown/derived event id (non-ok GET) → 404, never blank create form | #781 | timeline-curator-forms | `frontend/src/routes/zeitstrahl/events/[id]/edit/+page.server.ts` (load) | `[id]/edit/page.server.spec.ts#throws 404 when the GET is not ok (unknown or derived id)` | Done |
+| REQ-013 | 409 Conflict → generic conflict message, no redirect (no merge UI) | #781 | timeline-curator-forms | `frontend/src/routes/zeitstrahl/events/[id]/edit/+page.server.ts` (save) | `[id]/edit/page.server.spec.ts#maps a 409 conflict and does not redirect`, `new/page.server.spec.ts#maps the API error and does not redirect on a non-ok save (incl. 409)` | Done |
+| REQ-014 | valid ?personId/?documentId prefill pre-selected; unknown id silently ignored | #781 | timeline-curator-forms | `frontend/src/routes/zeitstrahl/events/new/+page.server.ts` (load Promise.all), `EventForm.svelte` | `new/page.server.spec.ts#preselects a valid person and ignores an unknown document`, `EventForm.svelte.spec.ts#preselects a person when initialPersons is provided` | Done |
+| REQ-015 | absent/empty/non-UUID originPersonId → redirect /zeitstrahl (CWE-601) | #781 | timeline-curator-forms | `frontend/src/lib/timeline/eventFormServer.ts#resolveNavTarget` | `new/page.server.spec.ts#defaults to /zeitstrahl when originPersonId is not a valid UUID`, `#redirects to /persons/{id} when originPersonId is a valid UUID` | Done |
+| REQ-016 | title/description/chip labels via default `{...}` escaping, never `{@html}` (CWE-79) | #781 | timeline-curator-forms | `frontend/src/lib/timeline/EventForm.svelte` | code review + `grep -r '@html' frontend/src/lib/timeline/` → zero | Done |
+| REQ-017 | labelled pickers, visible empty states, ≥44px chip remove targets | #781 | timeline-curator-forms | `frontend/src/lib/person/PersonMultiSelect.svelte`, `document/DocumentMultiSelect.svelte`, `EventForm.svelte` | `PersonMultiSelect.svelte.spec.ts`, `DocumentMultiSelect.svelte.spec.ts` (green post-44px fix), `EventForm.svelte.spec.ts#preselects a person when initialPersons is provided` | Done |

.specify/templates/adr.md

@@ -0,0 +1,42 @@
+<!--
+  ADR template. ADRs live in the existing archive: docs/adr/NNN-kebab-title.md.
+  Verify the next free NNN against `ls docs/adr/` on disk (parallel worktrees make
+  issue-body numbers stale). An ADR is IMMUTABLE once Status = Accepted — to change a
+  decision, write a NEW higher-numbered ADR and set this one's Status to Superseded.
+  This header mirrors the existing archive style (see docs/adr/040-*.md). Delete this comment.
+-->
+
+# ADR-NNN — <Short decision title>
+
+**Status:** Proposed <!-- Proposed | Accepted | Deprecated | Superseded by ADR-MMM -->
+**Date:** <YYYY-MM-DD>
+**Issue:** #<n> <!-- the Gitea issue / feature this decision serves -->
+
+## Context
+
+<The forces at play: what problem demands a decision now, the constraints from the
+constitution and existing ADRs, and why the status quo is insufficient. State facts, not
+the chosen answer.>
+
+## Decision
+
+<The decision, stated in active voice as something the project now does. Number sub-decisions
+(### 1, ### 2, …) if the ADR commits several related choices, matching the existing archive.>
+
+## Alternatives Considered
+
+| Option | Pros | Cons | Reason rejected |
+|---|---|---|---|
+| <chosen — name it> | <pros> | <cons> | **Chosen** |
+| <alternative A> | <pros> | <cons> | <why not> |
+| <alternative B> | <pros> | <cons> | <why not> |
+
+## Consequences
+
+<What becomes easier and what becomes harder. Include the obligations this decision places
+on future work (migrations forward-only, tests that must exist, guards that must hold), and
+any new coupling introduced.>
+
+## References
+
+- <constitution §, related ADRs, issue links, external docs>

.specify/templates/api-contract-stub.md

@@ -0,0 +1,97 @@
+# API Contract Stub
+
+This project is **REST + OpenAPI**. The backend serves the live spec via springdoc at
+`http://localhost:8080/v3/api-docs` (dev profile only), and the frontend generates its
+TypeScript client from it with `npm run generate:api` (`openapi-typescript` →
+`frontend/src/lib/generated/api.ts`). There is no GraphQL in this stack.
+
+> **The live spec is generated from the Java controllers — it is the source of truth.** A
+> hand-written stub is a *design artifact*: it pins the intended shape during spec review.
+> Issue-only: paste the stub inline into the issue's `## API / Contract Stub` section. Keep it
+> OpenAPI **3.1**, and keep `@Schema(requiredMode = REQUIRED)` on the Java side as the real
+> driver of `required`.
+
+## How to use this stub
+
+1. Fill in the skeleton below with the paths/methods/schemas your feature adds, and paste it
+   into the issue's `## API / Contract Stub` section.
+2. Every mutating path documents the `403`/`401` responses and the `cookieAuth` security
+   requirement (matching the real `@RequirePermission` gate).
+3. If you prefer a standalone, lintable file (e.g. for a large contract), commit it on the
+   **feature branch** as `<feature>.openapi.yaml` — the `sdd-gate.yml` CI job lints any
+   committed OpenAPI contract with Spectral (`npx @stoplight/spectral-cli lint`). It never
+   needs to predate the issue.
+4. After the endpoint ships, run `npm run generate:api` and diff the generated types against
+   this contract; reconcile any drift (the generated spec wins — update the contract).
+
+## OpenAPI 3.1 skeleton
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Familienarchiv API — <feature name>
+  version: 0.0.1-SNAPSHOT
+  description: Design-time contract for <feature>. Source of truth is the generated /v3/api-docs.
+servers:
+  - url: http://localhost:8080
+    description: Local backend (dev profile)
+  - url: https://archiv.raddatz.cloud
+    description: Production (behind Caddy)
+components:
+  securitySchemes:
+    cookieAuth:               # Spring Session JDBC — opaque session id in the SESSION cookie
+      type: apiKey
+      in: cookie
+      name: SESSION
+  schemas:
+    ErrorResponse:            # shape produced by GlobalExceptionHandler
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: Machine-readable ErrorCode (see ErrorCode.java / errors.ts).
+          example: FORBIDDEN
+        message:
+          type: string
+    # <YourResponseView>:     # always a view, never a lazy-collection entity (ADR-036)
+    #   type: object
+    #   required: [id]
+    #   properties:
+    #     id: { type: string, format: uuid }
+security:
+  - cookieAuth: []            # default: every path requires a session unless overridden to []
+paths:
+  /api/<resource>:
+    post:
+      summary: <create …>
+      operationId: <createResource>
+      security:
+        - cookieAuth: []      # plus @RequirePermission(Permission.X) on the controller
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/<CreateDTO>' }
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/<YourResponseView>' }
+        '400': { description: Validation failed, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+        '401': { description: Unauthenticated, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+        '403': { description: Missing permission, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+```
+
+## Validating the contract in CI
+
+The `sdd-gate.yml` `contract-validate` job lints any committed OpenAPI file changed in the PR:
+
+```bash
+npx @stoplight/spectral-cli lint <your-contract>.yaml
+```
+
+The ruleset is `.spectral.yaml` at the repo root (extends `spectral:oas`; documentation-only
+warnings relaxed for design-time stubs). Spectral auto-discovers it. It catches malformed
+specs, undefined `$ref`s, and duplicate `operationId`s; tune `.spectral.yaml` to adjust.

.specify/templates/feature-spec.md

@@ -0,0 +1,89 @@
+<!--
+  Feature Spec template — paste this into the Gitea issue body (issue-only: this IS the spec;
+  there is no committed spec.md). The .gitea/ISSUE_TEMPLATE/feature.md mirror gives the same
+  structure with the right labels. Replace every <placeholder>. Delete this comment before submitting.
+  EARS = Easy Approach to Requirements Syntax. Every requirement uses one of the five patterns
+  shown in ## Requirements and carries a unique REQ-NNN id (three-digit, scoped to THIS feature).
+  Use plain code-path references (not relative markdown links) — links don't resolve inside a Gitea issue.
+-->
+
+# <Feature title — match the Gitea issue: "As a <role> I want <capability> so <reason>">
+
+## Context & Why
+
+<Business motivation in 2–4 sentences: who needs this and why now.>
+
+Constitution principles this feature depends on (see `.specify/constitution.md`):
+- §<n> <principle name> — <why it applies>
+
+Related: <links to prior issues / ADRs>.
+
+## User Journey
+
+<Plain-prose steps the user takes to get value, from the user's perspective — per COLLABORATING.md. Anything not in this journey is out of scope.>
+
+## Requirements
+
+> One requirement per line, each with a `REQ-NNN` id and one EARS pattern. Include the
+> patterns the feature actually needs — do not force all five, but a mutating feature almost
+> always needs at least one Event-driven and one Unwanted-behavior requirement.
+
+- **REQ-001** (Ubiquitous) — The `<system component>` shall `<always-true behavior>`.
+- **REQ-002** (Event-driven) — When `<trigger / endpoint receives X>`, the `<system component>` shall `<response>`.
+- **REQ-003** (State-driven) — While `<system is in state X>`, the `<system component>` shall `<behavior>`.
+- **REQ-004** (Optional-feature) — Where `<the caller has Permission.X / a feature flag is set>`, the `<system component>` shall `<behavior>`.
+- **REQ-005** (Unwanted-behavior) — If `<undesired condition, e.g. caller is unauthenticated / input invalid>`, then the `<system component>` shall `<safe response, e.g. return 401 / ErrorCode.X>`.
+
+## Acceptance Criteria
+
+> One measurable criterion per REQ-NNN. Numbers, limits, status codes — never adjectives.
+
+- **REQ-001** — <measurable, e.g. "the response always includes a non-null `id` (UUID)">.
+- **REQ-002** — <measurable, e.g. "POST returns 201 and the persisted row within the same request">.
+- **REQ-003** — <measurable>.
+- **REQ-004** — <measurable, e.g. "a caller without Permission.X receives 403 with ErrorCode.FORBIDDEN">.
+- **REQ-005** — <measurable, e.g. "an unauthenticated request receives 401 and nothing is persisted">.
+
+## Out of Scope
+
+- <Explicit boundary statement — the nearest tempting scope creep, named and excluded.>
+- <…>
+
+## API / Contract Stub
+
+<Inline OpenAPI stub. Name the new/changed paths, methods, request/response shapes, status codes, and `@RequirePermission`. Use the `.specify/templates/api-contract-stub.md` skeleton as a writing aid.>
+
+## Data Model Changes
+
+<Entity/schema delta: new tables/columns, constraints, the next free Flyway `V<n>`, and the rollback note. Write "none" if not applicable.>
+
+## Security Considerations
+
+<STRIDE categories touched (Spoofing/Tampering/Repudiation/Information disclosure/DoS/Elevation). For AI-agent/tool features, also ASTRIDE. Include an inline STRIDE table (use `.specify/templates/threat-model.md`) if the feature has a non-trivial attack surface.>
+
+## Open Questions
+
+> Each item is a BLOCKER until resolved. Empty this list before implementation starts.
+
+- [ ] <question> — owner: <name>
+- [ ] <question> — owner: <name>
+
+## Traceability
+
+| REQ-ID | Task ID(s) | Test ID(s) | Status |
+|---|---|---|---|
+| REQ-001 | <T-1> | <test name> | Planned |
+| REQ-002 | <T-2> | <test name> | Planned |
+
+<After approval, add one committed row per REQ-NNN to `.specify/rtm.md` with this issue's number. Fill Task/Test IDs as work progresses.>
+
+## Persona Review Results
+
+| Persona | Status | Key Findings | Resolved |
+|---|---|---|---|
+| Requirements Engineer | PENDING | | |
+| Developer | PENDING | | |
+| Security | PENDING | | |
+| DevOps | PENDING | | |
+| UI/UX | PENDING | | |
+| Architect | PENDING | | |

.specify/templates/threat-model.md

@@ -0,0 +1,53 @@
+<!--
+  Threat model template — STRIDE + ASTRIDE. WRITING AID: fill this in and paste the result into
+  the issue's "## Security Considerations" section (issue-only — the threat model lives in the
+  issue body, not a committed file). Required when a feature adds a new trust boundary, handles
+  uploads, exposes a new mutating endpoint, or invokes an AI agent/tool. The Security persona
+  gates it during /review-issue. Delete this comment.
+-->
+
+# Threat Model — <Feature name>
+
+**Feature spec:** Gitea issue #<n>
+**Date:** <YYYY-MM-DD>
+**Author:** <name>
+
+## Data Flow Diagram (text)
+
+**Actors**
+- <e.g. Anonymous visitor, Authenticated reader, Authenticated transcriber, Admin, OCR sidecar>
+
+**Trust boundaries**
+- TB-1: Browser ⇄ Caddy (public internet ⇄ DMZ)
+- TB-2: Caddy ⇄ Backend (`:8080`) (DMZ ⇄ app)
+- TB-3: Backend ⇄ PostgreSQL / MinIO / sidecars (app ⇄ data plane)
+- <add feature-specific boundaries>
+
+**Data flows** (source → [boundary] → sink : data)
+- F-1: Browser → [TB-1,TB-2] → Backend : <request payload>
+- F-2: Backend → [TB-3] → MinIO : <stored object>
+- <…>
+
+## STRIDE
+
+| Threat Category | Asset / Flow | Threat Description | Mitigation | Likelihood × Impact | Status |
+|---|---|---|---|---|---|
+| **S**poofing | <asset> | <e.g. unauthenticated caller forges a request> | <session auth + @RequirePermission> | Low × High | <Open/Mitigated/Accepted> |
+| **T**ampering | <asset> | <e.g. mass-assignment of createdBy> | <server-set audit fields, no body binding> | Med × High | |
+| **R**epudiation | <asset> | <e.g. no record of who changed what> | <NOT NULL createdBy/updatedBy audit trail> | Low × Med | |
+| **I**nformation disclosure | <asset> | <e.g. entity leaks email/hash; raw 500 leaks Hibernate internals> | <view not entity; DomainException.conflict> | Med × High | |
+| **D**enial of service | <asset> | <e.g. oversized upload / unbounded list> | <size limit, batch cap, pagination> | Med × Med | |
+| **E**levation of privilege | <asset> | <e.g. reader reaches a write endpoint / IDOR> | <least-privilege Permission, ownership check> | Low × High | |
+
+## ASTRIDE (only if the feature invokes an AI agent / tool — OCR, NLP, LLM)
+
+| Threat | Asset / Flow | Threat Description | Mitigation | Likelihood × Impact | Status |
+|---|---|---|---|---|---|
+| Prompt Injection | <input to the model> | <untrusted document text steers the model> | <treat model output as untrusted; no auto-exec> | | |
+| Context Poisoning | <retrieved/shared context> | <attacker plants data that biases later runs> | <scope/provenance of context; validation> | | |
+| Unsafe Tool Invocation | <tool the agent can call> | <model triggers a privileged action> | <allow-list tools; human-in-loop on mutations> | | |
+| Reasoning Subversion | <decision the model makes> | <crafted input flips a classification/decision> | <confidence threshold; deterministic guardrail> | | |
+
+## Residual Risk
+
+<Threats marked Accepted, who accepted them, and why the residual risk is tolerable.>

.spectral.yaml

@@ -0,0 +1,15 @@
+# Spectral ruleset for OpenAPI contract linting (SDD api-contract files).
+# Spectral v6 ships no implicit ruleset — this enables the built-in OpenAPI rules.
+# Used by .gitea/workflows/sdd-gate.yml (contract-validate) and locally:
+#   npx @stoplight/spectral-cli lint <contract>.yaml
+extends: ["spectral:oas"]
+
+rules:
+  # Design-time SDD stubs are not full published API docs — relax the documentation-completeness
+  # warnings that would otherwise fire on a focused contract. The structural/correctness rules
+  # (oas3-schema, valid $refs, duplicate operationId, etc.) stay on.
+  info-contact: off
+  info-description: off
+  operation-description: off
+  operation-tag-defined: off
+  oas3-unused-component: off

CLAUDE.md

@@ -16,6 +16,10 @@ See [COLLABORATING.md](./COLLABORATING.md) for the full rules: issue tracking wo
 
 See [CODESTYLE.md](./CODESTYLE.md) for coding standards: Clean Code, DRY/KISS trade-offs (KISS wins), and SOLID principles applied to this stack.
 
+## Spec-Driven Development
+
+This project uses Spec-Driven Development. **Before implementing a feature, read [`.specify/AGENTS.md`](./.specify/AGENTS.md)** (the short, machine-readable agent rules) and obey the [`.specify/constitution.md`](./.specify/constitution.md) it references. A feature's contract is its **Gitea issue body** (EARS `REQ-NNN` requirements) — there is no committed `spec.md`; the RTM ([`.specify/rtm.md`](./.specify/rtm.md)) traces each `REQ-ID → issue # → test`. Full workflow: [SPEC_DRIVEN_DEVELOPMENT.md](./SPEC_DRIVEN_DEVELOPMENT.md); template/reference: [`.specify/features/_example/`](./.specify/features/_example/). The LLM reminders below restate constitution rules — the constitution and AGENTS.md are authoritative if they ever diverge.
+
 ---
 
 ## Stack
@@ -86,7 +90,8 @@ backend/src/main/java/org/raddatz/familienarchiv/
 │   └── transcription/   TranscriptionBlock, TranscriptionService, TranscriptionBlockQueryService
 ├── exception/           DomainException, ErrorCode, GlobalExceptionHandler
 ├── filestorage/         FileService (S3/MinIO)
-├── geschichte/          Geschichte (story) domain
+├── geschichte/          Geschichte (story) domain — GeschichteService, GeschichteQueryService
+│   └── journeyitem/     JourneyItem sub-domain — JourneyItemService, JourneyItemController
 ├── importing/           CanonicalImportOrchestrator + four loaders (TagTree/PersonRegister/PersonTree/Document) + CanonicalSheetReader
 ├── notification/        Notification domain + SseEmitterRegistry
 ├── ocr/                 OCR domain — OcrService, OcrBatchService, training
@@ -94,6 +99,7 @@ backend/src/main/java/org/raddatz/familienarchiv/
 │   └── relationship/    PersonRelationship sub-domain
 ├── security/            SecurityConfig, Permission, @RequirePermission, PermissionAspect
 ├── tag/                 Tag domain
+├── timeline/            Timeline (Zeitstrahl) domain — TimelineEvent, TimelineEventService, TimelineEntryDTO, DerivedEventType, EventType, TimelineEventRepository; TimelineEventService.assembleDerivedEvents() returns derived life-events (Geburt/Tod/Heirat) computed on read from Person/relationship data; TimelineService assembles year-bucketed TimelineDTO (curated events + derived events + archive letters); TimelineController exposes GET /api/timeline
 └── user/                User domain — AppUser, UserGroup, UserService
 ```
 
@@ -105,13 +111,17 @@ backend/src/main/java/org/raddatz/familienarchiv/
 
 ### Domain Model
 
-| Entity      | Table         | Key relationships                                                                     |
-| ----------- | ------------- | ------------------------------------------------------------------------------------- |
-| `Document`  | `documents`   | ManyToOne `sender` (Person), ManyToMany `receivers` (Person), ManyToMany `tags` (Tag) |
-| `Person`    | `persons`     | Referenced by documents as sender/receiver                                            |
-| `Tag`       | `tag`         | ManyToMany with documents via `document_tags`                                         |
-| `AppUser`   | `app_users`   | ManyToMany `groups` (UserGroup)                                                       |
-| `UserGroup` | `user_groups` | Has a `Set<String> permissions`                                                       |
+| Entity        | Table           | Key relationships                                                                       |
+| ------------- | --------------- | --------------------------------------------------------------------------------------- |
+| `Document`    | `documents`     | ManyToOne `sender` (Person), ManyToMany `receivers` (Person), ManyToMany `tags` (Tag)  |
+| `Person`      | `persons`       | Referenced by documents as sender/receiver                                              |
+| `Tag`         | `tag`           | ManyToMany with documents via `document_tags`                                           |
+| `AppUser`     | `app_users`     | ManyToMany `groups` (UserGroup)                                                         |
+| `UserGroup`   | `user_groups`   | Has a `Set<String> permissions`                                                         |
+| `Geschichte`  | `geschichten`   | `GeschichteType` (`STORY`/`JOURNEY`); ManyToMany `persons` (Person); OneToMany `items` (JourneyItem) |
+| `JourneyItem` | `journey_items` | ManyToOne `geschichte` (Geschichte, ON DELETE CASCADE); ManyToOne `document` (Document, ON DELETE SET NULL); `position`, optional `note` |
+| `TimelineEvent` | `timeline_events` | `EventType` (`PERSONAL`/`HISTORICAL`); ManyToMany `persons` (Person) + `documents` (Document), both join FKs ON DELETE CASCADE; `DatePrecision` date block; `@Version` + NOT NULL `createdBy`/`updatedBy` audit trail |
+| `TimelineEntryDTO` | _(computed — no table)_ | Unified DTO for all timeline entries assembled by `TimelineService`; 13 fields: `kind` (`EVENT`\|`LETTER`), `precision` (raw `DatePrecision` enum), `derived` (boolean), `senderName` (non-null `String`, `""` = unknown), `receiverName` (non-null `String`, `""` = unknown), `eventDate`, `eventDateEnd`, `title`, `type` (`EventType`, null for LETTER), `eventId` (null for derived entries and letters), `documentId` (set for letters), `linkedPersonIds: List<UUID>`, `derivedType` (`DerivedEventType`, null for curated/letters); edit-affordance contract: `derived == true \|\| eventId == null` → no edit link |
 
 **`DocumentStatus` lifecycle:** `PLACEHOLDER → UPLOADED → TRANSCRIBED → REVIEWED → ARCHIVED`
 
@@ -152,7 +162,7 @@ Services are annotated with `@Service`, `@RequiredArgsConstructor`, and optional
 
 ### DTOs
 
-Input DTOs live flat in the domain package. Response types are the model entities themselves (no response DTOs).
+Input DTOs live flat in the domain package. Response types are the model entities themselves (no response DTOs) — **except the geschichte domain**, where every response is a view (`GeschichteView`/`GeschichteSummary`/`JourneyItemView`) assembled inside the service transaction and entities never cross the controller boundary. See [ADR-036](./docs/adr/036-geschichte-responses-are-views-not-entities.md) — lazy collections + `open-in-view: false` make serialized entities a 500 waiting to happen.
 
 - `@Schema(requiredMode = REQUIRED)` on every field the backend always populates — drives TypeScript generation.
 
@@ -160,7 +170,7 @@ Input DTOs live flat in the domain package. Response types are the model entitie
 
 → See [CONTRIBUTING.md §Error handling](./CONTRIBUTING.md#error-handling)
 
-**LLM reminder:** use `DomainException.notFound/forbidden/conflict/internal()` from service methods — never throw raw exceptions. When adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded).
+**LLM reminder:** use `DomainException.notFound/forbidden/conflict/internal()` from service methods — never throw raw exceptions. When adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded); `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`, `GESCHICHTE_TITLE_TOO_LONG`, `GESCHICHTE_INTRO_TOO_LONG` (journey/geschichte domain constraints); `TIMELINE_EVENT_NOT_FOUND`, `TIMELINE_EVENT_CONFLICT`, `TIMELINE_TITLE_TOO_LONG` (timeline event CRUD), plus a generic `CONFLICT` (409 optimistic-lock backstop).
 
 ### Security / Permissions
 
@@ -197,6 +207,8 @@ frontend/src/routes/
 ├── aktivitaeten/           Unified activity feed (Chronik)
 ├── geschichten/            Stories — list, [id], [id]/edit, new
 ├── stammbaum/              Family tree (Stammbaum)
+├── zeitstrahl/             Global timeline (Zeitstrahl) — life-events + events + letters woven in time; SSR-loads GET /api/timeline, renders lib/timeline/TimelineView (Datum mode)
+│   └── events/             Curator event editor (WRITE_ALL-gated) — new (create) + [id]/edit (edit + delete); reuses lib/timeline/EventForm
 ├── themen/                 Topics directory — browsable tag index
 ├── enrich/                 Enrichment workflow — [id], done
 ├── admin/                  User, group, tag, OCR, system management
@@ -268,7 +280,7 @@ Back button pattern — use the shared `<BackButton>` component from `$lib/share
 
 → See [CONTRIBUTING.md §Error handling](./CONTRIBUTING.md#error-handling)
 
-**LLM reminder:** when adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded).
+**LLM reminder:** when adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded); `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`, `GESCHICHTE_TITLE_TOO_LONG`, `GESCHICHTE_INTRO_TOO_LONG` (journey/geschichte domain constraints); `TIMELINE_EVENT_NOT_FOUND`, `TIMELINE_EVENT_CONFLICT`, `TIMELINE_TITLE_TOO_LONG` (timeline event CRUD), plus a generic `CONFLICT` (409 optimistic-lock backstop).
 
 ---
 

COLLABORATING.md

@@ -8,6 +8,14 @@ Evaluate all suggestions on their technical merits. No sycophancy — if somethi
 
 ## Core Workflow: Research → Plan → Implement → Validate
 
+> **Spec-Driven Development.** Feature work is front-ended by an SDD spec: EARS-formatted
+> `REQ-NNN` requirements, persona spec-review checklists, and the project constitution. The
+> sequence below is unchanged — SDD formalises its *inputs* (the issue body becomes a
+> structured spec; the User Journey + E2E Scenarios below feed it). See
+> [SPEC_DRIVEN_DEVELOPMENT.md](./SPEC_DRIVEN_DEVELOPMENT.md) and
+> [`.specify/`](./.specify/) ([constitution](./.specify/constitution.md),
+> [AGENTS.md](./.specify/AGENTS.md)).
+
 Every non-trivial feature or bug fix follows this sequence:
 
 1. **Research** — Read the relevant code. Understand existing patterns before touching anything.

CONTRIBUTING.md

@@ -1,6 +1,7 @@
 # Contributing to Familienarchiv
 
 For the full collaboration rules (issue workflow, PR process, Red/Green TDD, commit conventions) see [COLLABORATING.md](./COLLABORATING.md).
+For the Spec-Driven Development workflow (EARS specs, persona review, the constitution, and `.specify/`) see [SPEC_DRIVEN_DEVELOPMENT.md](./SPEC_DRIVEN_DEVELOPMENT.md).
 For coding style see [CODESTYLE.md](./CODESTYLE.md).
 For the system architecture see [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) (introduced in DOC-2; until that PR merges, see [docs/architecture/c4-diagrams.md](./docs/architecture/c4-diagrams.md)).
 For domain terminology see [docs/GLOSSARY.md](./docs/GLOSSARY.md).

SPEC_DRIVEN_DEVELOPMENT.md

@@ -0,0 +1,235 @@
+# Spec-Driven Development (SDD)
+
+How we turn a feature idea into merged, traceable code in this repo. SDD layers a uniform,
+machine-readable front-end onto the workflow we already run (Gitea issues → branch/PR →
+multi-persona review → red/green TDD). It does not replace any of that — see
+[ADR-042](./docs/adr/042-sdd-adoption.md) for the why.
+
+- **The rules** live in [`.specify/constitution.md`](./.specify/constitution.md) (humans) and
+  [`.specify/AGENTS.md`](./.specify/AGENTS.md) (AI agents, every invocation).
+- **The templates** live in [`.specify/templates/`](./.specify/templates/).
+- **The worked example** is [`.specify/features/_example/`](./.specify/features/_example/) — read it first.
+
+---
+
+## 0. The whole workflow at a glance
+
+```mermaid
+flowchart TD
+    idea([Feature idea]):::start --> draft
+
+    subgraph author["✍️  Author"]
+        draft[/"/draft-spec<br/>(Requirements Engineer)"/]:::skill --> issue[("Gitea issue = the SPEC<br/>EARS REQ-NNN + acceptance criteria")]:::spec
+    end
+
+    issue --> ri[/"/review-issue"/]:::skill
+    ri --> g1{"GATE 1 · spec review<br/>6 personas APPROVE?<br/>Open Questions empty?"}:::gate
+    g1 -- "FAIL / question" --> amend["Amend the issue body"]:::work --> ri
+    g1 -- "APPROVE" --> rtm["Seed RTM rows<br/>REQ-ID → issue #"]:::work
+
+    rtm --> wt["Create git worktree<br/>(pull main first)"]:::work --> impl[/"/implement"/]:::skill
+
+    subgraph build["🔁  Build · TDD per REQ-NNN"]
+        impl --> red["Red: failing test"]:::work --> green["Green: minimal code"]:::work --> sync["Refactor + sync<br/>generate:api · flip RTM → Done"]:::work --> commit["Commit · Refs #n"]:::work
+        commit -- "next REQ" --> red
+    end
+
+    build --> pr[["Open PR · Closes #n"]]:::work --> g2{"GATE 2 · CI green?<br/>ci.yml + sdd-gate.yml"}:::gate
+    g2 -- "red" --> fixci["Fix on branch"]:::work --> g2
+    g2 -- "green" --> rp[/"/review-pr"/]:::skill
+
+    rp --> g3{"GATE 3 · PR review<br/>all personas APPROVE?<br/>every REQ implemented + tested?<br/>no Do-Not-Touch violation?"}:::gate
+    g3 -- "changes requested" --> fixpr["Fix on branch"]:::work --> rp
+    g3 -- "APPROVE" --> merge([Merge → main<br/>closed issue = archived spec]):::start
+
+    rules["📐 constitution.md + AGENTS.md<br/>(bind every step)"]:::rules -.-> draft
+    rules -.-> impl
+    rules -.-> rp
+
+    classDef start fill:#1d3b53,color:#fff,stroke:#1d3b53;
+    classDef skill fill:#e8f5f0,stroke:#3aa884,color:#13352b;
+    classDef gate fill:#fff3cd,stroke:#d39e00,color:#5a4500;
+    classDef spec fill:#eef2ff,stroke:#5b6ee1,color:#1e2a5a;
+    classDef work fill:#f6f6f6,stroke:#bbb,color:#222;
+    classDef rules fill:#fdecea,stroke:#d9534f,color:#611a15;
+```
+
+> `/deliver-issue` runs **GATE 1 → discuss → build → GATE 3 (loop)** end-to-end in one go.
+
+### Prerequisites (one-time setup)
+
+Before the workflow runs cleanly, confirm these exist (most ship with this repo):
+
+- [ ] **Gitea labels** `spec-required` and `needs-review` exist (the feature template + `/draft-spec` attach them; the `labels` create-param is ignored, so they must pre-exist).
+- [ ] **Gitea MCP** server configured (`gitea`) — the skills read/write issues and PRs through it.
+- [ ] **`.spectral.yaml`** at the repo root (extends `spectral:oas`) — the CI contract check needs it.
+- [ ] **Personas present**: identities in [`.claude/personas/`](./.claude/personas/) + checklists in [`.specify/personas/`](./.specify/personas/).
+- [ ] **`.specify/constitution.md` + `AGENTS.md`** committed on `main` (so every branch inherits them).
+- [ ] **Worktrees + hooks**: new feature work goes in a `git worktree` (plus-free name); run `npm install` in `frontend/` once per worktree so the pre-commit lint hook works.
+
+### The three gates
+
+| Gate | When | Mechanism | Blocks on |
+|---|---|---|---|
+| **1 · Spec review** | after `/draft-spec`, before any code | `/review-issue` (6 persona checklists) | any persona `CHANGES REQUESTED`, or an unresolved `## Open Question` |
+| **2 · CI** | on every PR | `ci.yml` (tests · lint · semgrep) + `sdd-gate.yml` (rtm-check · contract-validate · constitution-diff) | `ci.yml` failure (hard); `sdd-gate` jobs are non-blocking during adoption — see the workflow TODO |
+| **3 · PR review** | before merge | `/review-pr` (7 personas + traceability) | any persona `Changes requested`, an unimplemented/untested `REQ-NNN`, or a constitution Do-Not-Touch violation |
+
+---
+
+## 1. The workflow in 8 steps
+
+| # | Step | Who | Artifacts created / touched |
+|---|---|---|---|
+| 1 | **Idea → Gitea issue** using the Feature template | author | Gitea issue (labels `spec-required`, `needs-review`) from `.gitea/ISSUE_TEMPLATE/feature.md` |
+| 2 | **Write the spec _in the issue body_** — Context, User Journey, EARS `REQ-NNN` requirements, measurable acceptance criteria, Out of Scope | author | the Gitea issue body **is** the spec (single source of truth — no committed `spec.md`) |
+| 3 | **Capture durable design decisions** as needed | author | a `docs/adr/` ADR for any project-wide/irreversible decision; an OpenAPI contract and a STRIDE threat model inline in the issue (use the `.specify/templates/` as the writing aid) |
+| 4 | **Persona spec review** — the six checklists gate the spec | RE, Developer, Security, DevOps, UI/UX, Architect | `/review-issue` posts each persona's checklist verdict as a Gitea comment; findings folded into the issue body |
+| 5 | **Resolve Open Questions & blocking FAILs** — spec does not proceed while any remain | author | issue body updated; `Open Questions` emptied |
+| 6 | **Seed the RTM** — one row per `REQ-NNN`, pointing at the issue | author | rows added to [`.specify/rtm.md`](./.specify/rtm.md) (`Issue: #n`, `Status: Planned`) — committed with the feature branch |
+| 7 | **Implement** in a worktree, TDD per task (failing test → green → refactor → commit); agent reads `AGENTS.md` + the **issue body** (the spec) | implementer (often an AI agent) | code + tests; `npm run generate:api` after backend changes; RTM `Status` → `Done` |
+| 8 | **PR → multi-persona PR review → merge** | reviewers | PR (`Closes #n`); the closed issue is the archived spec, the RTM rows record what shipped |
+
+The personas at step 4 review the **spec (the issue)**; the same personas at step 8 (via the
+existing `review-pr` / `deliver-issue` skills) review the **code**. Step 4 catches at spec time
+what used to surface only at step 8.
+
+**Skills that drive this:** `/draft-spec` (requirements engineer authors steps 1–2 → creates
+the issue) → `/review-issue` (step 4 gate) → `/implement` (steps 6–7) → `/review-pr` (step 8).
+`/deliver-issue` runs review → discuss → implement → review-loop end-to-end.
+
+> **Why issue-only?** The Gitea issue body is the single source of truth for a spec — there is
+> no committed per-feature `spec.md` to drift out of sync with it. The only SDD artifact that
+> lives in git per feature is the RTM row (`REQ-ID → issue # → test`). The worked example under
+> [`.specify/features/_example/`](./.specify/features/_example/) is a **template/reference**, not
+> a live feature — it shows the full artifact set in one place; real features keep the spec in
+> the issue.
+
+## 2. How a Gitea issue becomes a spec
+
+**Before (free-form issue):**
+
+> **Title:** Add profile pictures
+> Users should be able to upload a picture for their profile. Make sure it's not too big and
+> only admins can remove other people's. Show initials if there's no picture.
+
+Ambiguous: how big? which formats? what status code on rejection? what about unauthenticated
+callers? No identifiers to trace, no measurable criteria.
+
+**After (SDD-structured issue — excerpt):**
+
+> **Title:** As a user I want to upload a profile picture so other family members recognise me
+>
+> **## Requirements**
+> - **REQ-002** (Event-driven) — When an authenticated user sends `POST /api/users/me/avatar`
+>   with a valid image, the user service shall store it and return a profile view with a
+>   non-null `avatarUrl`.
+> - **REQ-008** (Unwanted-behavior) — If the uploaded file exceeds 2 MB, then the user service
+>   shall return `400 ErrorCode.AVATAR_TOO_LARGE` and store nothing.
+> - **REQ-009** (Unwanted-behavior) — If a caller without `Permission.ADMIN_USER` targets
+>   another user's avatar, then the system shall return `403 ErrorCode.FORBIDDEN`.
+>
+> **## Acceptance Criteria**
+> - **REQ-008** — a 2.1 MB PNG returns `400 AVATAR_TOO_LARGE`; bucket object count unchanged.
+
+Every behavior is now a uniquely-identified, testable, EARS-formed requirement with a
+measurable acceptance criterion. See the full version in
+[`.specify/features/_example/spec.md`](./.specify/features/_example/spec.md).
+
+## 3. How to run a persona review
+
+Each persona reads the spec, walks its checklist in `.specify/personas/<persona>.md`, and
+posts a Gitea comment with **PASS / FAIL / QUESTION** per
+item and a verdict. A `FAIL` from Security or Architect is a hard block. Concrete example:
+
+> ### Security — Spec Review
+>
+> | # | Item | Status | Note |
+> |---|---|---|---|
+> | 1 | All mutating endpoints have authn + authz `If` clauses | PASS | REQ-006 (401), REQ-009 (403) |
+> | 3 | Audit fields server-set, forbidden in body | **FAIL** | `avatarObjectKey` is bound from the request body → mass-assignment (CWE-639). Make it server-set in `UserService`. |
+> | 6 | Upload type allow-list + size | PASS | REQ-007 / REQ-008 |
+> | 9 | threat-model.md present & STRIDE-complete | **QUESTION** | Is the avatar URL public or proxied? If public S3, that's information disclosure. |
+>
+> **Verdict: CHANGES REQUESTED** — blocking FAIL: #3. Resolve #9 in the threat model.
+
+The author folds the fix into the spec (here: server-set key + authenticated proxy URL),
+empties the finding, and the persona re-reviews until `APPROVE`. This mirrors the existing
+`review-issue` skill — the persona checklists just make the spec pass/fail explicit.
+
+## 4. How the AI agent uses the spec
+
+Once the spec is `APPROVE`d and tasks are seeded, the implementer points the agent at the
+artifacts. Example prompt:
+
+> Implement Gitea issue #142 (profile picture upload). Read `.specify/AGENTS.md` and obey the
+> constitution it references. The contract is the issue body — its EARS requirements
+> REQ-001…REQ-009 and acceptance criteria. Build a red/green task list from them, write the
+> failing test for each REQ first, confirm it fails, then make it pass. After backend model
+> changes run `npm run generate:api`. Do not mark a REQ done until its test is green; flip its
+> row in `.specify/rtm.md` to Done as you go.
+
+The agent now has: the rules (`AGENTS.md` → constitution) and the exact requirements with ids
+from the issue — so its output is bounded and verifiable. (The `/implement` skill fetches the
+issue body for you via the Gitea API.)
+
+## 5. Maintenance rules
+
+- **Constitution** ([`.specify/constitution.md`](./.specify/constitution.md)) — change it only
+  when a project-wide rule genuinely changes. Bump the semantic version (MAJOR = rule
+  removed/weakened, MINOR = rule added/tightened, PATCH = wording), run the §6 Sync Impact
+  review, and let the `constitution-diff` CI job list the files to reconcile. Record the bump
+  in ADR-042's revision log (or a superseding ADR for MAJOR).
+- **AGENTS.md** — keep it under 200 lines. It cross-references the constitution; it must never
+  duplicate or contradict it.
+- **ADRs** — project-wide/irreversible decisions go in [`docs/adr/`](./docs/adr/) (next free
+  `NNN`, verify on disk). Immutable once `Accepted`; supersede, don't edit.
+- **Feature specs** — the spec is the Gitea issue body; there is no committed `spec.md`.
+  "Archiving" is just closing the issue (`Closes #n` on merge). The closed issue + the RTM
+  rows are the record of what shipped.
+- **RTM** ([`.specify/rtm.md`](./.specify/rtm.md)) — append one row per `REQ-NNN` when a spec
+  is approved, each pointing at its issue (`#n`); flip `Status` as tests go green; never delete
+  a shipped requirement's row.
+- **Personas** — update `.specify/personas/*.md` checklists when a recurring blind spot
+  appears; keep them aligned with the richer `.claude/personas/`.
+
+## 6. Quick-start cheatsheet
+
+**EARS patterns** (every requirement is one of these + a `REQ-NNN` id):
+
+| Pattern | Shape |
+|---|---|
+| Ubiquitous | `The <system> shall <behavior>.` |
+| Event-driven | `When <trigger>, the <system> shall <behavior>.` |
+| State-driven | `While <state>, the <system> shall <behavior>.` |
+| Optional-feature | `Where <feature/permission present>, the <system> shall <behavior>.` |
+| Unwanted-behavior | `If <undesired condition>, then the <system> shall <response>.` |
+
+**File locations:**
+
+| What | Where |
+|---|---|
+| Non-negotiable rules | `.specify/constitution.md` |
+| Agent rules (read every time) | `.specify/AGENTS.md` |
+| Templates (writing aids) | `.specify/templates/{feature-spec,adr,threat-model,api-contract-stub}.md` |
+| Persona checklists | `.specify/personas/*.md` |
+| In-flight feature spec | the **Gitea issue body** (not a committed file) |
+| Worked example (template/reference) | `.specify/features/_example/` |
+| Traceability matrix | `.specify/rtm.md` (`REQ-ID → issue # → test`) |
+| ADR archive | `docs/adr/NNN-*.md` |
+| Issue templates | `.gitea/ISSUE_TEMPLATE/{feature,bug}.md` |
+| CI gate | `.gitea/workflows/sdd-gate.yml` |
+
+**Before you mark a feature done:** every `REQ-NNN` has a green test, the RTM Status is
+`Done`, all six personas APPROVE, `npm run lint` and the targeted tests pass, and
+`npm run generate:api` has been run if the backend model changed.
+
+**Commands:**
+
+```bash
+# validate an OpenAPI contract locally (if you drafted one — same as CI)
+npx @stoplight/spectral-cli lint <your-contract>.yaml
+
+# regenerate the TS client after a backend model/endpoint change
+cd frontend && npm run generate:api   # backend must run with --spring.profiles.active=dev
+```

backend/CLAUDE.md

@@ -33,7 +33,8 @@ src/main/java/org/raddatz/familienarchiv/
 │   └── transcription/   # TranscriptionBlock, TranscriptionService, TranscriptionBlockQueryService
 ├── exception/           # DomainException, ErrorCode, GlobalExceptionHandler
 ├── filestorage/         # FileService (S3/MinIO)
-├── geschichte/          # Geschichte (story) domain
+├── geschichte/          # Geschichte (story) domain — GeschichteService, GeschichteQueryService
+│   └── journeyitem/     # JourneyItem sub-domain — JourneyItemService, JourneyItemController
 ├── importing/           # CanonicalImportOrchestrator + 4 loaders + CanonicalSheetReader
 ├── notification/        # Notification domain + SseEmitterRegistry
 ├── ocr/                 # OCR domain — OcrService, OcrBatchService, training
@@ -41,6 +42,7 @@ src/main/java/org/raddatz/familienarchiv/
 │   └── relationship/    # PersonRelationship sub-domain
 ├── security/            # SecurityConfig, Permission, @RequirePermission, PermissionAspect
 ├── tag/                 # Tag domain — Tag, TagService, TagController
+├── timeline/            # Timeline (Zeitstrahl) domain — TimelineEvent, EventType, TimelineEventRepository
 └── user/                # User domain — AppUser, UserGroup, UserService
 ```
 
@@ -66,6 +68,7 @@ For per-domain ownership and public surface, see each domain's `README.md`.
 | `Comment`                   | `document_comments`             | Threaded comments with mentions                                                 |
 | `Notification`              | `notifications`                 | User notification feed                                                          |
 | `OcrJob` / `OcrJobDocument` | `ocr_jobs`, `ocr_job_documents` | Batch OCR job tracking                                                          |
+| `TimelineEvent`             | `timeline_events`               | Curated Zeitstrahl event; ManyToMany persons + documents (join FKs ON DELETE CASCADE); `@Version` + NOT NULL createdBy/updatedBy |
 
 **`DocumentStatus` lifecycle:** `PLACEHOLDER → UPLOADED → TRANSCRIBED → REVIEWED → ARCHIVED`
 

backend/src/main/java/org/raddatz/familienarchiv/audit/AuditKind.java

@@ -50,10 +50,30 @@ public enum AuditKind {
     ADMIN_FORCE_LOGOUT,
 
     /** Payload: {@code {"ip": "1.2.3.4", "email": "addr"}} — password NEVER included */
-    LOGIN_RATE_LIMITED;
+    LOGIN_RATE_LIMITED,
+
+    // --- Documents ---
+
+    /** Payload: none — the deleted document's id is carried in the documentId column */
+    DOCUMENT_DELETED,
+
+    // --- Reading Journeys (Lesereisen) ---
+
+    /** Payload: {@code {"geschichteId": "uuid", "itemId": "uuid"}} — documentId is null (journey-scoped, not document-scoped) */
+    JOURNEY_ITEM_ADDED,
+
+    /** Payload: {@code {"geschichteId": "uuid", "itemId": "uuid"}} — documentId is null */
+    JOURNEY_ITEM_REMOVED,
+
+    /** Payload: {@code {"geschichteId": "uuid", "itemId": "uuid"}} — documentId is null */
+    JOURNEY_ITEM_NOTE_UPDATED,
+
+    /** Payload: {@code {"geschichteId": "uuid", "itemCount": 3}} — documentId is null; rolled up in chronik */
+    JOURNEY_ITEMS_REORDERED;
 
     public static final Set<AuditKind> ROLLUP_ELIGIBLE = Set.of(
             TEXT_SAVED, FILE_UPLOADED, ANNOTATION_CREATED,
-            BLOCK_REVIEWED, COMMENT_ADDED, MENTION_CREATED
+            BLOCK_REVIEWED, COMMENT_ADDED, MENTION_CREATED,
+            JOURNEY_ITEMS_REORDERED
     );
 }

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

@@ -168,8 +168,8 @@ public class DocumentController {
 
     @DeleteMapping("/{id}")
     @RequirePermission(Permission.WRITE_ALL)
-    public ResponseEntity<Void> deleteDocument(@PathVariable UUID id) {
-        documentService.deleteDocument(id);
+    public ResponseEntity<Void> deleteDocument(@PathVariable UUID id, Authentication authentication) {
+        documentService.deleteDocument(id, requireUserId(authentication));
         return ResponseEntity.noContent().build();
     }
 

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

@@ -0,0 +1,11 @@
+package org.raddatz.familienarchiv.document;
+
+import java.util.UUID;
+
+/**
+ * Published by DocumentService.deleteDocument inside its @Transactional boundary,
+ * before documentRepository.deleteById fires. Listeners run synchronously in the
+ * publisher's thread and transaction via plain @EventListener — this is load-bearing:
+ * see ADR-038.
+ */
+public record DocumentDeletingEvent(UUID documentId) {}

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

@@ -36,6 +36,13 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
     @EntityGraph("Document.list")
     Page<Document> findAll(Pageable pageable);
 
+    // Loader for the relevance fast path: list-item enrichment reads tags after the
+    // repository call returns, so the fetch shape must match the spec-based findAll
+    // overloads above. Plain findAllById carries no entity graph and must not feed
+    // enrichItems — see DocumentService.relevanceSortedPageFromSql.
+    @EntityGraph("Document.list")
+    List<Document> findByIdIn(Collection<UUID> ids);
+
     // Findet ein Dokument anhand des ursprünglichen Dateinamens
     // Wichtig für den Abgleich beim Excel-Import & Datei-Upload
     Optional<Document> findByOriginalFilename(String originalFilename);
@@ -49,6 +56,11 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
     // Prüft effizient, ob ein Dateiname schon existiert (gibt true/false zurück)
     boolean existsByOriginalFilename(String originalFilename);
 
+    // Bulk-fetch for global timeline path — single query with sender+receivers eager-loaded.
+    @EntityGraph("Document.list")
+    @Query("SELECT d FROM Document d")
+    List<Document> findAllForTimeline();
+
     // lazy – @BatchSize(50) fallback active; see ADR-022
     @EntityGraph("Document.full")
     List<Document> findBySenderId(UUID senderId);

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

@@ -28,6 +28,7 @@ import org.raddatz.familienarchiv.ocr.TrainingLabel;
 import org.raddatz.familienarchiv.person.Person;
 import org.raddatz.familienarchiv.tag.Tag;
 import org.raddatz.familienarchiv.document.DocumentRepository;
+import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.PageRequest;
 import org.springframework.data.domain.Pageable;
@@ -80,6 +81,7 @@ public class DocumentService {
     private final TranscriptionBlockQueryService transcriptionBlockQueryService;
     private final AuditLogQueryService auditLogQueryService;
     private final ThumbnailAsyncRunner thumbnailAsyncRunner;
+    private final ApplicationEventPublisher eventPublisher;
 
     public record StoreResult(Document document, boolean isNew) {}
 
@@ -851,14 +853,14 @@ public class DocumentService {
         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.
+        // Preserve ts_rank order from SQL across the JPA findByIdIn 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()
+        List<Document> docs = documentRepository.findByIdIn(pageIds).stream()
                 .sorted(Comparator.comparingInt(d -> rankMap.getOrDefault(d.getId(), Integer.MAX_VALUE)))
                 .toList();
         return buildResultPaged(docs, text, pageable, ftsPage.total());
@@ -1006,6 +1008,28 @@ public class DocumentService {
         return doc;
     }
 
+    /**
+     * Lightweight summary lookup for internal use (e.g. journey item append validation).
+     *
+     * <p><strong>Security contract — read before calling:</strong>
+     * <ol>
+     *   <li>This method intentionally bypasses per-document scope checks and
+     *       tag-colour resolution. It must only be invoked after
+     *       {@code @RequirePermission(BLOG_WRITE)} has already been enforced at
+     *       the controller layer, guaranteeing the caller is an authenticated
+     *       author.</li>
+     *   <li>In {@code JourneyItemService.append()}, it is additionally guarded by the
+     *       JOURNEY-type check that fires before this call — so the method is never
+     *       reached for STORY-type Geschichten.</li>
+     * </ol>
+     * Under the current single-tenant model every authenticated author shares the
+     * same document scope, so skipping per-document scope checks is safe.
+     */
+    public Document findSummaryByIdInternal(UUID id) {
+        return documentRepository.findById(id)
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.DOCUMENT_NOT_FOUND, "Document not found: " + id));
+    }
+
     /**
      * Loads a document for the detail view, additionally flagging whether it has any
      * transcription to read. Kept separate from {@link #getDocumentById} so the cheap
@@ -1027,6 +1051,10 @@ public class DocumentService {
         return documentRepository.findDocumentsWithoutVersions();
     }
 
+    public List<Document> getAllForTimeline() {
+        return documentRepository.findAllForTimeline();
+    }
+
     public List<Document> getDocumentsBySender(UUID senderId) {
         return documentRepository.findBySenderId(senderId);
     }
@@ -1075,11 +1103,13 @@ public class DocumentService {
     }
 
     @Transactional
-    public void deleteDocument(UUID id) {
+    public void deleteDocument(UUID id, UUID actorId) {
         if (!documentRepository.existsById(id)) {
             throw DomainException.notFound(ErrorCode.DOCUMENT_NOT_FOUND, "Document not found: " + id);
         }
+        eventPublisher.publishEvent(new DocumentDeletingEvent(id));
         documentRepository.deleteById(id);
+        auditService.logAfterCommit(AuditKind.DOCUMENT_DELETED, actorId, id, null);
     }
 
     @Transactional

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

@@ -15,6 +15,10 @@ public enum ErrorCode {
     ALIAS_NOT_FOUND,
     /** The submitted personType value is not allowed (e.g. SKIP is import-only). 400 */
     INVALID_PERSON_TYPE,
+    /** A person's birth date is after their death date. 400 */
+    BIRTH_AFTER_DEATH,
+    /** A life date and its precision are incoherent: date present with UNKNOWN precision, or precision set without a date. 400 */
+    INVALID_DATE_PRECISION,
     // --- Documents ---
     /** A document with the given ID does not exist. 404 */
     DOCUMENT_NOT_FOUND,
@@ -122,6 +126,22 @@ public enum ErrorCode {
     // --- Geschichten (Stories) ---
     /** A Geschichte (story) with the given ID does not exist, or is a DRAFT and the caller lacks BLOG_WRITE. 404 */
     GESCHICHTE_NOT_FOUND,
+    /** A JourneyItem with the given ID does not exist, or belongs to a different journey (IDOR). 404 */
+    JOURNEY_ITEM_NOT_FOUND,
+    /** A position uniqueness conflict occurred on the journey_items table — concurrent append or reorder. 409 */
+    JOURNEY_ITEM_POSITION_CONFLICT,
+    /** The journey already has the maximum allowed number of items (100). 400 */
+    JOURNEY_AT_CAPACITY,
+    /** The document is already present in this journey — duplicate items are not allowed. 409 */
+    JOURNEY_DOCUMENT_ALREADY_ADDED,
+    /** The type of an existing Geschichte cannot be changed via PATCH. 409 */
+    GESCHICHTE_TYPE_IMMUTABLE,
+    /** A journey-item note exceeds the maximum length (2000 characters). 400 */
+    JOURNEY_NOTE_TOO_LONG,
+    /** A Geschichte title exceeds the maximum length (255 characters — the DB column bound). 400 */
+    GESCHICHTE_TITLE_TOO_LONG,
+    /** A JOURNEY intro (body) exceeds the maximum length (4000 characters). 400 */
+    GESCHICHTE_INTRO_TOO_LONG,
 
     // --- Tags ---
     /** A tag with the given ID does not exist. 404 */
@@ -135,6 +155,14 @@ public enum ErrorCode {
     /** The merge target is a descendant of the source tag. 400 */
     TAG_MERGE_INVALID_TARGET,
 
+    // --- Timeline (Zeitstrahl) ---
+    /** A timeline event with the given ID does not exist. 404 */
+    TIMELINE_EVENT_NOT_FOUND,
+    /** Optimistic-locking conflict — the timeline event was modified by another curator. 409 */
+    TIMELINE_EVENT_CONFLICT,
+    /** A timeline event title exceeds the maximum length (255 characters — the DB column bound). 400 */
+    TIMELINE_TITLE_TOO_LONG,
+
     // --- Generic ---
     /** Request validation failed (missing or malformed fields). 400 */
     VALIDATION_ERROR,
@@ -142,6 +170,8 @@ public enum ErrorCode {
     BATCH_TOO_LARGE,
     /** Bulk edit request exceeds the per-request document ID cap. 400 */
     BULK_EDIT_TOO_MANY_IDS,
+    /** A concurrent modification was detected (generic optimistic-lock backstop). 409 */
+    CONFLICT,
     /** An unexpected server-side error occurred. 500 */
     INTERNAL_ERROR,
 }

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

@@ -78,7 +78,14 @@ public class GlobalExceptionHandler {
         // Log the constraint NAME only — schema metadata, safe for Loki, and enough to tell which
         // constraint fired at 2am. Never pass `ex` / `ex.getMessage()`: those embed the SQL + the
         // offending values (CWE-209). No Sentry: an integrity violation is a 400, not a system fault.
-        log.warn("Rejected a request that violated a database integrity constraint: {}", constraintNameOf(ex));
+        String constraint = constraintNameOf(ex);
+        log.warn("Rejected a request that violated a database integrity constraint: {}", constraint);
+        if ("uq_journey_items_geschichte_position".equals(constraint)) {
+            // DEFERRABLE INITIALLY DEFERRED — fires at commit when concurrent appends/reorders collide
+            return ResponseEntity.status(409)
+                    .body(new ErrorResponse(ErrorCode.JOURNEY_ITEM_POSITION_CONFLICT,
+                            "A position conflict was detected — another request modified this journey simultaneously"));
+        }
         return ResponseEntity.badRequest()
                 .body(new ErrorResponse(ErrorCode.VALIDATION_ERROR, "The submitted data violated a database constraint"));
     }
@@ -97,6 +104,30 @@ public class GlobalExceptionHandler {
         return "unknown";
     }
 
+    /**
+     * Generic backstop for optimistic-locking conflicts that escape a service-level catch. A
+     * conflict is a 409, not a system fault — so, like {@link #handleDataIntegrityViolation}, it
+     * must NOT fire Sentry and must NOT leak Hibernate internals (CWE-209): the response carries
+     * only the generic {@link ErrorCode#CONFLICT} code and a generic message — no entity id, no
+     * version, no persistent-class name.
+     *
+     * <p>Deliberately code-GENERIC: do NOT {@code switch} on {@code getPersistentClassName()} to map
+     * back to a per-entity code. Unlike {@link #handleDataIntegrityViolation}, which branches on
+     * stable schema constraint NAMES, persistent-class names are not a contract. The precise,
+     * code-carrying path is the service catch (e.g. {@code TIMELINE_EVENT_CONFLICT}); this is only
+     * the net that keeps any current or future write path from regressing to a 500.
+     */
+    @ExceptionHandler(org.springframework.orm.ObjectOptimisticLockingFailureException.class)
+    public ResponseEntity<ErrorResponse> handleOptimisticLock(
+            org.springframework.orm.ObjectOptimisticLockingFailureException ex) {
+        // Log the persistent-class name ONLY (schema metadata, safe for Loki). Never `ex` /
+        // ex.getMessage(): those embed the entity id + version (CWE-209). No Sentry: it's a 409.
+        log.warn("Rejected a write that lost an optimistic-lock race on: {}", ex.getPersistentClassName());
+        return ResponseEntity.status(409)
+                .body(new ErrorResponse(ErrorCode.CONFLICT,
+                        "The resource was modified concurrently. Please reload and try again."));
+    }
+
     @ExceptionHandler(Exception.class)
     public ResponseEntity<ErrorResponse> handleGeneric(Exception ex) {
         Sentry.captureException(ex);

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

@@ -5,12 +5,14 @@ import jakarta.persistence.*;
 import lombok.*;
 import org.hibernate.annotations.CreationTimestamp;
 import org.hibernate.annotations.UpdateTimestamp;
-
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItem;
 import org.raddatz.familienarchiv.user.AppUser;
-import org.raddatz.familienarchiv.document.Document;
 import org.raddatz.familienarchiv.person.Person;
+
 import java.time.LocalDateTime;
+import java.util.ArrayList;
 import java.util.HashSet;
+import java.util.List;
 import java.util.Set;
 import java.util.UUID;
 
@@ -40,6 +42,12 @@ public class Geschichte {
     @Builder.Default
     private GeschichteStatus status = GeschichteStatus.DRAFT;
 
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    @Builder.Default
+    private GeschichteType type = GeschichteType.STORY;
+
     @ManyToOne
     @JoinColumn(name = "author_id")
     private AppUser author;
@@ -51,12 +59,18 @@ public class Geschichte {
     @Builder.Default
     private Set<Person> persons = new HashSet<>();
 
-    @ManyToMany(fetch = FetchType.EAGER)
-    @JoinTable(name = "geschichten_documents",
-            joinColumns = @JoinColumn(name = "geschichte_id"),
-            inverseJoinColumns = @JoinColumn(name = "document_id"))
+    // LAZY per docs/adr/022-eager-to-lazy-fetch-strategy.md. open-in-view is FALSE
+    // (application.yaml), so this collection is DEAD at Jackson serialization time unless
+    // explicitly initialized inside the service transaction. getById() is
+    // @Transactional(readOnly=true) AND calls getItems().size() to force-init before return.
+    // list() must NOT serialize items at all — it returns a GeschichteSummary projection.
+    // This is the first List ("bag") collection on Geschichte — adding a second EAGER/
+    // fetch-joined List here will throw MultipleBagFetchException at boot.
+    @OneToMany(mappedBy = "geschichte", cascade = CascadeType.ALL, orphanRemoval = true,
+               fetch = FetchType.LAZY)
+    @OrderBy("position ASC")
     @Builder.Default
-    private Set<Document> documents = new HashSet<>();
+    private List<JourneyItem> items = new ArrayList<>();
 
     @CreationTimestamp
     @Column(updatable = false)

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

@@ -1,12 +1,15 @@
 package org.raddatz.familienarchiv.geschichte;
 
 import lombok.RequiredArgsConstructor;
-import org.raddatz.familienarchiv.geschichte.GeschichteUpdateDTO;
-import org.raddatz.familienarchiv.geschichte.Geschichte;
-import org.raddatz.familienarchiv.geschichte.GeschichteStatus;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemCreateDTO;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemService;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemUpdateDTO;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemView;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyReorderDTO;
 import org.raddatz.familienarchiv.security.Permission;
 import org.raddatz.familienarchiv.security.RequirePermission;
-import org.raddatz.familienarchiv.geschichte.GeschichteService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.DeleteMapping;
@@ -14,6 +17,7 @@ import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PatchMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
@@ -28,12 +32,17 @@ import java.util.UUID;
 public class GeschichteController {
 
     private final GeschichteService geschichteService;
+    private final JourneyItemService journeyItemService;
 
     @GetMapping
-    public List<Geschichte> list(
+    public List<GeschichteSummary> list(
+            @Parameter(description = "Filter by status. Callers without BLOG_WRITE always receive PUBLISHED results regardless of the value passed. Callers with BLOG_WRITE requesting DRAFT receive only their own unpublished stories.")
             @RequestParam(required = false) GeschichteStatus status,
+            @Parameter(description = "AND-filter: story must include all supplied person IDs.")
             @RequestParam(name = "personId", required = false) List<UUID> personIds,
+            @Parameter(description = "Filter to stories containing this document.")
             @RequestParam(required = false) UUID documentId,
+            @Parameter(description = "Maximum results to return. Values ≤ 0 default to 50. Clamped at 200.")
             @RequestParam(required = false, defaultValue = "50") int limit) {
         return geschichteService.list(
                 status,
@@ -43,20 +52,20 @@ public class GeschichteController {
     }
 
     @GetMapping("/{id}")
-    public Geschichte getById(@PathVariable UUID id) {
-        return geschichteService.getById(id);
+    public GeschichteView getById(@PathVariable UUID id) {
+        return geschichteService.getView(id);
     }
 
     @PostMapping
     @RequirePermission(Permission.BLOG_WRITE)
-    public ResponseEntity<Geschichte> create(@RequestBody GeschichteUpdateDTO dto) {
-        Geschichte created = geschichteService.create(dto);
+    public ResponseEntity<GeschichteView> create(@RequestBody GeschichteUpdateDTO dto) {
+        GeschichteView created = geschichteService.create(dto);
         return ResponseEntity.status(HttpStatus.CREATED).body(created);
     }
 
     @PatchMapping("/{id}")
     @RequirePermission(Permission.BLOG_WRITE)
-    public Geschichte update(@PathVariable UUID id, @RequestBody GeschichteUpdateDTO dto) {
+    public GeschichteView update(@PathVariable UUID id, @RequestBody GeschichteUpdateDTO dto) {
         return geschichteService.update(id, dto);
     }
 
@@ -66,4 +75,45 @@ public class GeschichteController {
         geschichteService.delete(id);
         return ResponseEntity.noContent().build();
     }
+
+    // ─── JourneyItem CRUD ────────────────────────────────────────────────────
+
+    @PostMapping("/{id}/items")
+    @RequirePermission(Permission.BLOG_WRITE)
+    public ResponseEntity<JourneyItemView> appendItem(
+            @PathVariable UUID id,
+            @RequestBody JourneyItemCreateDTO dto) {
+        JourneyItemView view = journeyItemService.append(id, dto);
+        return ResponseEntity.status(HttpStatus.CREATED).body(view);
+    }
+
+    @PatchMapping("/{id}/items/{itemId}")
+    @RequirePermission(Permission.BLOG_WRITE)
+    public JourneyItemView updateItemNote(
+            @PathVariable UUID id,
+            @PathVariable UUID itemId,
+            @RequestBody JourneyItemUpdateDTO dto) {
+        return journeyItemService.updateNote(id, itemId, dto);
+    }
+
+    @DeleteMapping("/{id}/items/{itemId}")
+    @RequirePermission(Permission.BLOG_WRITE)
+    public ResponseEntity<Void> deleteItem(
+            @PathVariable UUID id,
+            @PathVariable UUID itemId) {
+        journeyItemService.delete(id, itemId);
+        return ResponseEntity.noContent().build();
+    }
+
+    @PutMapping("/{id}/items/reorder")
+    @RequirePermission(Permission.BLOG_WRITE)
+    @Operation(
+        summary = "Reorder journey items",
+        description = "itemIds must contain ALL item IDs for the given journey in the desired new order. Sending a partial list returns 400 Bad Request."
+    )
+    public List<JourneyItemView> reorderItems(
+            @PathVariable UUID id,
+            @RequestBody JourneyReorderDTO dto) {
+        return journeyItemService.reorder(id, dto);
+    }
 }

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

@@ -0,0 +1,29 @@
+package org.raddatz.familienarchiv.geschichte;
+
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * Thin read-only service owning {@link GeschichteRepository}.
+ * Exists so that {@code JourneyItemService} can check Geschichte existence
+ * and load Geschichte instances without holding a direct reference to the
+ * Geschichte repository (cross-domain repository access is not allowed per
+ * layering rules).
+ */
+@Service
+@RequiredArgsConstructor
+public class GeschichteQueryService {
+
+    private final GeschichteRepository geschichteRepository;
+
+    public boolean existsById(UUID id) {
+        return geschichteRepository.existsById(id);
+    }
+
+    public Optional<Geschichte> findById(UUID id) {
+        return geschichteRepository.findById(id);
+    }
+}

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

@@ -1,12 +1,47 @@
 package org.raddatz.familienarchiv.geschichte;
 
-import org.raddatz.familienarchiv.geschichte.Geschichte;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;
 
+import java.util.Collection;
+import java.util.List;
 import java.util.UUID;
 
 @Repository
 public interface GeschichteRepository extends JpaRepository<Geschichte, UUID>, JpaSpecificationExecutor<Geschichte> {
+
+    /**
+     * Returns the grid projection. Never carries items (avoids lazy-init 500 under open-in-view:false).
+     *
+     * <p>Status clamp: callers must pass the effective status (PUBLISHED for readers,
+     * raw status for BLOG_WRITE users). authorId restricts to own drafts when effective=DRAFT.
+     *
+     * <p>Person filter: personCount=0 disables the filter. When personCount>0, the story must
+     * be associated with ALL person ids in personIds (AND-semantics via counting subquery).
+     * Pass a non-empty personIds collection when personCount>0 — empty IN() is invalid SQL.
+     */
+    @Query("""
+            SELECT g.id AS id, g.title AS title, g.status AS status, g.type AS type,
+                   g.author AS author, g.publishedAt AS publishedAt, g.updatedAt AS updatedAt, g.body AS body
+            FROM Geschichte g
+            WHERE g.status = :effectiveStatus
+              AND (:authorId IS NULL OR g.author.id = :authorId)
+              AND (:personCount = 0 OR
+                   (SELECT COUNT(DISTINCT p.id)
+                    FROM Geschichte g2 JOIN g2.persons p
+                    WHERE g2.id = g.id AND p.id IN :personIds) = :personCount)
+              AND (:documentId IS NULL OR
+                   EXISTS (SELECT 1 FROM JourneyItem ji
+                           WHERE ji.geschichte = g AND ji.document.id = :documentId))
+            ORDER BY COALESCE(g.publishedAt, g.updatedAt) DESC
+            """)
+    List<GeschichteSummary> findSummaries(
+            @Param("effectiveStatus") GeschichteStatus effectiveStatus,
+            @Param("authorId") UUID authorId,
+            @Param("personIds") Collection<UUID> personIds,
+            @Param("personCount") long personCount,
+            @Param("documentId") UUID documentId);
 }

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

@@ -4,28 +4,23 @@ import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.owasp.html.HtmlPolicyBuilder;
 import org.owasp.html.PolicyFactory;
-import org.raddatz.familienarchiv.geschichte.GeschichteUpdateDTO;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemService;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemView;
 import org.raddatz.familienarchiv.user.AppUser;
-import org.raddatz.familienarchiv.document.Document;
-import org.raddatz.familienarchiv.geschichte.Geschichte;
-import org.raddatz.familienarchiv.geschichte.GeschichteStatus;
 import org.raddatz.familienarchiv.person.Person;
-import org.raddatz.familienarchiv.geschichte.GeschichteRepository;
-import org.raddatz.familienarchiv.geschichte.GeschichteSpecifications;
 import org.raddatz.familienarchiv.security.Permission;
 import org.raddatz.familienarchiv.document.DocumentService;
 import org.raddatz.familienarchiv.person.PersonService;
 import org.raddatz.familienarchiv.user.UserService;
-import org.springframework.data.domain.Sort;
-import org.springframework.data.jpa.domain.Specification;
 import org.springframework.security.core.Authentication;
 import org.springframework.security.core.context.SecurityContextHolder;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
 import java.time.LocalDateTime;
+import java.util.Collection;
 import java.util.HashSet;
 import java.util.LinkedHashSet;
 import java.util.List;
@@ -41,6 +36,7 @@ public class GeschichteService {
     private final PersonService personService;
     private final DocumentService documentService;
     private final UserService userService;
+    private final JourneyItemService journeyItemService;
 
     /**
      * Allow-list policy for Geschichte body HTML. Tiptap on the writer side
@@ -54,12 +50,26 @@ public class GeschichteService {
     private static final int DEFAULT_LIMIT = 50;
     private static final int MAX_LIMIT = 200;
 
+    /** Sentinel used when {@code personIds} is empty to avoid invalid empty IN() SQL. */
+    private static final UUID NIL_UUID = UUID.fromString("00000000-0000-0000-0000-000000000000");
+
+    // Matches the geschichten.title VARCHAR(255) column (V58) — the service check
+    // turns what would be a DB-level 500 into a friendly 400.
+    static final int MAX_TITLE_LENGTH = 255;
+    // JOURNEY intros travel the verbatim (unsanitized) write path, so they get the
+    // same three-layer bound as journey notes: frontend maxlength, this check, and
+    // the V75 CHECK constraint. STORY bodies are sanitized Tiptap HTML and stay
+    // unbounded on purpose.
+    static final int MAX_INTRO_LENGTH = 4000;
+
     // ─── Read API ────────────────────────────────────────────────────────────
 
     public long countPublished() {
         return geschichteRepository.count(GeschichteSpecifications.hasStatus(GeschichteStatus.PUBLISHED));
     }
 
+    // readOnly = true: lazy collections resolve within the same tx when called from getView()
+    @Transactional(readOnly = true)
     public Geschichte getById(UUID id) {
         Geschichte g = geschichteRepository.findById(id)
                 .orElseThrow(() -> DomainException.notFound(
@@ -72,24 +82,62 @@ public class GeschichteService {
         return g;
     }
 
+    @Transactional(readOnly = true)
+    public GeschichteView getView(UUID id) {
+        Geschichte g = getById(id);
+        List<JourneyItemView> items = journeyItemService.getItems(id);
+        return toView(g, items);
+    }
+
+    GeschichteView toView(Geschichte g, List<JourneyItemView> items) {
+        AppUser author = g.getAuthor();
+        GeschichteView.AuthorView authorView = null;
+        if (author != null) {
+            String displayName = PersonNameFormatter.join(author.getFirstName(), author.getLastName());
+            if (displayName.isBlank()) displayName = "[Unbekannt]";
+            authorView = new GeschichteView.AuthorView(author.getId(), displayName);
+        }
+        Set<GeschichteView.PersonView> personViews = new HashSet<>();
+        for (Person p : g.getPersons()) {
+            personViews.add(new GeschichteView.PersonView(p.getId(), p.getFirstName(), p.getLastName()));
+        }
+        return new GeschichteView(
+                g.getId(), g.getTitle(), g.getBody(),
+                g.getStatus(), g.getType(),
+                authorView, personViews,
+                items,
+                g.getPublishedAt(), g.getCreatedAt(), g.getUpdatedAt()
+        );
+    }
+
     /**
      * Lists Geschichten with optional filters. {@code personIds} uses AND semantics: the story
      * must be associated with every person id supplied. An empty or null list applies no
      * person filter. Result is ordered by {@code COALESCE(publishedAt, updatedAt) DESC}.
+     *
+     * <p>Returns a {@link GeschichteSummary} projection — never carries items, preventing
+     * LazyInitializationException on the non-transactional list path.
+     *
+     * <p>Security: {@code null} status always resolves to PUBLISHED — even for blog writers.
+     * Only an explicit {@code DRAFT} request scopes the query to the caller's own drafts.
+     * This prevents CWE-639: a blog writer passing {@code null} must not see all authors' drafts.
      */
-    public List<Geschichte> list(GeschichteStatus status, List<UUID> personIds, UUID documentId, int limit) {
-        GeschichteStatus effective = currentUserHasBlogWrite() ? status : GeschichteStatus.PUBLISHED;
+    public List<GeschichteSummary> list(GeschichteStatus status, List<UUID> personIds, UUID documentId, int limit) {
+        boolean isDraftRequest = currentUserHasBlogWrite() && status == GeschichteStatus.DRAFT;
+        GeschichteStatus effective = isDraftRequest ? GeschichteStatus.DRAFT : 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()
-        );
-        return geschichteRepository.findAll(spec, Sort.unsorted())
+        UUID authorId = isDraftRequest ? currentUser().getId() : null;
+
+        // When personIds is empty, personCount=0 short-circuits the IN() predicate.
+        // Pass a sentinel UUID to avoid invalid empty IN() SQL while the predicate is skipped.
+        Collection<UUID> safePersonIds = (personIds == null || personIds.isEmpty())
+                ? List.of(NIL_UUID)
+                : personIds;
+        long personCount = (personIds == null) ? 0 : personIds.size();
+
+        return geschichteRepository
+                .findSummaries(effective, authorId, safePersonIds, personCount, documentId)
                 .stream()
                 .limit(safeLimit)
                 .toList();
@@ -97,46 +145,57 @@ public class GeschichteService {
 
     // ─── Write API ───────────────────────────────────────────────────────────
 
+    // Write methods return GeschichteView, never the entity: Jackson serializes after
+    // the transaction closed, where the lazy items collection is a dead proxy.
+    // The view is assembled in-transaction, so no force-init tricks are needed.
+
     @Transactional
-    public Geschichte create(GeschichteUpdateDTO dto) {
+    public GeschichteView create(GeschichteUpdateDTO dto) {
         requireTitle(dto.getTitle());
+        GeschichteType type = dto.getType() != null ? dto.getType() : GeschichteType.STORY;
         Geschichte g = Geschichte.builder()
                 .title(dto.getTitle().trim())
-                .body(sanitize(dto.getBody()))
+                .body(bodyForType(type, dto.getBody()))
                 .status(GeschichteStatus.DRAFT)
+                .type(type)
                 .author(currentUser())
                 .persons(resolvePersons(dto.getPersonIds()))
-                .documents(resolveDocuments(dto.getDocumentIds()))
                 .build();
         if (dto.getStatus() == GeschichteStatus.PUBLISHED) {
             g.setStatus(GeschichteStatus.PUBLISHED);
             g.setPublishedAt(LocalDateTime.now());
         }
-        return geschichteRepository.save(g);
+        Geschichte saved = geschichteRepository.save(g);
+        // A freshly created Geschichte has no items by construction — items are only
+        // addable via the separate /items endpoints. Revisit if a create DTO ever
+        // accepts initial items.
+        return toView(saved, List.of());
     }
 
     @Transactional
-    public Geschichte update(UUID id, GeschichteUpdateDTO dto) {
+    public GeschichteView update(UUID id, GeschichteUpdateDTO dto) {
         Geschichte g = geschichteRepository.findById(id)
                 .orElseThrow(() -> DomainException.notFound(
                         ErrorCode.GESCHICHTE_NOT_FOUND, "Geschichte not found: " + id));
+        if (dto.getType() != null && dto.getType() != g.getType()) {
+            throw DomainException.conflict(ErrorCode.GESCHICHTE_TYPE_IMMUTABLE,
+                    "The type of a Geschichte cannot be changed after creation");
+        }
         if (dto.getTitle() != null) {
             requireTitle(dto.getTitle());
             g.setTitle(dto.getTitle().trim());
         }
         if (dto.getBody() != null) {
-            g.setBody(sanitize(dto.getBody()));
+            g.setBody(bodyForType(g.getType(), dto.getBody()));
         }
         if (dto.getPersonIds() != null) {
             g.setPersons(resolvePersons(dto.getPersonIds()));
         }
-        if (dto.getDocumentIds() != null) {
-            g.setDocuments(resolveDocuments(dto.getDocumentIds()));
-        }
         if (dto.getStatus() != null && dto.getStatus() != g.getStatus()) {
             applyStatusTransition(g, dto.getStatus());
         }
-        return geschichteRepository.save(g);
+        Geschichte saved = geschichteRepository.save(g);
+        return toView(saved, journeyItemService.getItems(id));
     }
 
     @Transactional
@@ -164,6 +223,27 @@ public class GeschichteService {
             throw DomainException.badRequest(
                     ErrorCode.VALIDATION_ERROR, "Title is required");
         }
+        if (title.trim().length() > MAX_TITLE_LENGTH) {
+            throw DomainException.badRequest(ErrorCode.GESCHICHTE_TITLE_TOO_LONG,
+                    "Title exceeds maximum length of " + MAX_TITLE_LENGTH + " characters");
+        }
+    }
+
+    /**
+     * STORY bodies are Tiptap HTML and go through the OWASP allow-list sanitizer.
+     * JOURNEY intros are plain text: the reader renders them via Svelte text
+     * interpolation (never {@code {@html}}), so entity-encoding them here would
+     * corrupt content ("&" → "&amp;") and re-encode on every editor round-trip.
+     */
+    private String bodyForType(GeschichteType type, String body) {
+        if (type != GeschichteType.JOURNEY) {
+            return sanitize(body);
+        }
+        if (body != null && body.length() > MAX_INTRO_LENGTH) {
+            throw DomainException.badRequest(ErrorCode.GESCHICHTE_INTRO_TOO_LONG,
+                    "Intro exceeds maximum length of " + MAX_INTRO_LENGTH + " characters");
+        }
+        return body;
     }
 
     private String sanitize(String body) {
@@ -176,15 +256,6 @@ public class GeschichteService {
         return new LinkedHashSet<>(personService.getAllById(ids));
     }
 
-    private Set<Document> resolveDocuments(List<UUID> ids) {
-        if (ids == null || ids.isEmpty()) return new HashSet<>();
-        Set<Document> out = new LinkedHashSet<>();
-        for (UUID id : ids) {
-            out.add(documentService.getDocumentById(id));
-        }
-        return out;
-    }
-
     private AppUser currentUser() {
         Authentication auth = SecurityContextHolder.getContext().getAuthentication();
         if (auth == null || !auth.isAuthenticated()) {

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

@@ -6,9 +6,6 @@ import jakarta.persistence.criteria.Join;
 import jakarta.persistence.criteria.Predicate;
 import jakarta.persistence.criteria.Root;
 import jakarta.persistence.criteria.Subquery;
-import org.raddatz.familienarchiv.document.Document;
-import org.raddatz.familienarchiv.geschichte.Geschichte;
-import org.raddatz.familienarchiv.geschichte.GeschichteStatus;
 import org.raddatz.familienarchiv.person.Person;
 import org.springframework.data.jpa.domain.Specification;
 
@@ -48,12 +45,7 @@ public final class GeschichteSpecifications {
                 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;
-            return cb.exists(documentSubquery(root, query, cb, documentId));
-        };
-    }
+    // TODO(lesereisen-editor): restore document filter via journey_items join when editor lands
 
     /**
      * AND-filter across persons: the Geschichte must be associated with EVERY id in {@code personIds}.
@@ -84,14 +76,4 @@ public final class GeschichteSpecifications {
         return sub;
     }
 
-    private static Subquery<UUID> documentSubquery(
-            Root<Geschichte> root, CriteriaQuery<?> query, CriteriaBuilder cb, UUID documentId) {
-        Subquery<UUID> sub = query.subquery(UUID.class);
-        Root<Geschichte> subRoot = sub.from(Geschichte.class);
-        Join<Geschichte, Document> documents = subRoot.join("documents");
-        sub.select(subRoot.get("id"))
-                .where(cb.equal(subRoot.get("id"), root.get("id")),
-                        cb.equal(documents.get("id"), documentId));
-        return sub;
-    }
 }

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

@@ -0,0 +1,45 @@
+package org.raddatz.familienarchiv.geschichte;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+/**
+ * List-projection for the /api/geschichten grid. Never carries items — avoids
+ * LazyInitializationException (open-in-view: false) and prevents Cartesian joins.
+ * Mirrors the PersonSummaryDTO precedent.
+ *
+ * <p>Field set: exactly what the live grid card renders (title, author byline, body excerpt,
+ * publishedAt, status, type). Does NOT carry items or persons.
+ */
+public interface GeschichteSummary {
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    UUID getId();
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    String getTitle();
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    GeschichteStatus getStatus();
+
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    GeschichteType getType();
+
+    /** Nested closed projection — exposes only the fields the grid card needs. */
+    AuthorSummary getAuthor();
+
+    LocalDateTime getPublishedAt();
+
+    /** Always set (@UpdateTimestamp) — drives "bearbeitet vor X" on dashboard cards. */
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    LocalDateTime getUpdatedAt();
+
+    String getBody();
+
+    /** Author projection — names only; never email or group memberships (same rule as GeschichteView.AuthorView). */
+    interface AuthorSummary {
+        String getFirstName();
+        String getLastName();
+    }
+}

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

@@ -0,0 +1,6 @@
+package org.raddatz.familienarchiv.geschichte;
+
+public enum GeschichteType {
+    STORY,
+    JOURNEY
+}

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

@@ -1,7 +1,6 @@
 package org.raddatz.familienarchiv.geschichte;
 
 import lombok.Data;
-import org.raddatz.familienarchiv.geschichte.GeschichteStatus;
 
 import java.util.List;
 import java.util.UUID;
@@ -16,6 +15,6 @@ public class GeschichteUpdateDTO {
     private String title;
     private String body;
     private GeschichteStatus status;
+    private GeschichteType type;
     private List<UUID> personIds;
-    private List<UUID> documentIds;
 }

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

@@ -0,0 +1,41 @@
+package org.raddatz.familienarchiv.geschichte;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemView;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * Detail-view response for GET /api/geschichten/{id}. Assembled by
+ * GeschichteService — never the raw entity (author AppUser graph must not leak).
+ * items is always present (both STORY and JOURNEY); empty list for stories with no items.
+ */
+public record GeschichteView(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String title,
+        String body,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) GeschichteStatus status,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) GeschichteType type,
+        AuthorView author,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) Set<PersonView> persons,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) List<JourneyItemView> items,
+        LocalDateTime publishedAt,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) LocalDateTime createdAt,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) LocalDateTime updatedAt
+) {
+    /** Summarised author — exposes only id and displayName, never email or group memberships. */
+    public record AuthorView(
+            @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+            @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String displayName
+    ) {}
+
+    /** Summarised person — exposes only id, firstName, and lastName. No admin-only fields. */
+    public record PersonView(
+            @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+            String firstName,
+            String lastName
+    ) {}
+}

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

@@ -0,0 +1,22 @@
+package org.raddatz.familienarchiv.geschichte;
+
+/**
+ * Utility for joining a person's first and last name into a display string.
+ * Centralises the logic that was previously duplicated across GeschichteService
+ * and JourneyItemService.
+ */
+public class PersonNameFormatter {
+
+    private PersonNameFormatter() {
+        // utility class — no instances
+    }
+
+    public static String join(String firstName, String lastName) {
+        String first = firstName != null ? firstName.trim() : "";
+        String last = lastName != null ? lastName.trim() : "";
+        if (first.isEmpty() && last.isEmpty()) return "";
+        if (first.isEmpty()) return last;
+        if (last.isEmpty()) return first;
+        return first + " " + last;
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/DocumentSummary.java

@@ -0,0 +1,23 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.raddatz.familienarchiv.document.DatePrecision;
+
+import java.time.LocalDate;
+import java.util.UUID;
+
+/**
+ * Lean read-model view of a Document for embedding in JourneyItemView.
+ * Built by JourneyItemService.toSummary(Document) — never serialised from
+ * a JPA entity to avoid LazyInitializationException and tag-color overhead.
+ */
+public record DocumentSummary(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String title,
+        LocalDate documentDate,
+        LocalDate documentDateEnd,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) DatePrecision datePrecision,
+        String senderName,
+        String receiverName,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) Integer receiverCount
+) {}

backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItem.java

@@ -0,0 +1,54 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.persistence.*;
+import lombok.*;
+import org.raddatz.familienarchiv.document.Document;
+import org.raddatz.familienarchiv.geschichte.Geschichte;
+
+import java.util.UUID;
+
+@Entity
+@Table(name = "journey_items")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class JourneyItem {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID id;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "geschichte_id", nullable = false)
+    @JsonIgnore
+    private Geschichte geschichte;
+
+    // Sort key; gaps fine. Duplicate positions within a journey yield undefined relative order
+    // — the editor is responsible for keeping them distinct.
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private int position;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "document_id")
+    @JsonIgnore
+    private Document document;
+
+    /**
+     * Plain text — not HTML-sanitized. Renderers MUST NOT use {@code @html} or equivalent unsafe output.
+     *
+     * <p>CWE-79 tripwire: stored verbatim; only Svelte {note} interpolation is auto-safe.</p>
+     */
+    @Column(columnDefinition = "TEXT")
+    private String note;
+
+    // JPA uses field access — this getter is not persisted. Jackson serializes it as documentId.
+    // Exposing only the UUID prevents circular references and large nested payloads.
+    public UUID getDocumentId() {
+        return document != null ? document.getId() : null;
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemCreateDTO.java

@@ -0,0 +1,12 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import lombok.Data;
+
+import java.util.UUID;
+
+/** Input for POST /api/geschichten/{id}/items. Both fields optional; at least one must be present. */
+@Data
+public class JourneyItemCreateDTO {
+    private UUID documentId;
+    private String note;
+}

backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemDocumentDeleteListener.java

@@ -0,0 +1,30 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.raddatz.familienarchiv.document.DocumentDeletingEvent;
+import org.springframework.context.event.EventListener;
+import org.springframework.stereotype.Component;
+
+@Component
+@RequiredArgsConstructor
+@Slf4j
+class JourneyItemDocumentDeleteListener {
+
+    private final JourneyItemRepository journeyItemRepository;
+
+    /**
+     * Plain @EventListener — runs synchronously in the publisher's thread and transaction.
+     * Load-bearing choice: AFTER_COMMIT would fire after the FK ON DELETE SET NULL has
+     * already 500'd; @Async would run outside the delete transaction (breaks AC-5 rollback).
+     * See ADR-038. DocumentService cannot call JourneyItemService directly because
+     * Spring Framework 7 prohibits the resulting constructor-injection cycle.
+     */
+    @EventListener
+    void onDocumentDeleting(DocumentDeletingEvent event) {
+        int deleted = journeyItemRepository.deleteNoteLessByDocumentId(event.documentId());
+        if (deleted > 0) {
+            log.warn("Cascade-deleted {} note-less journey item(s) for document {}", deleted, event.documentId());
+        }
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemRepository.java

@@ -0,0 +1,69 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+import org.springframework.stereotype.Repository;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+
+@Repository
+public interface JourneyItemRepository extends JpaRepository<JourneyItem, UUID> {
+
+    /** Returns items ordered by position ASC for the read-model assembly path. */
+    List<JourneyItem> findByGeschichteIdOrderByPosition(UUID geschichteId);
+
+    /** IDOR-safe lookup: returns empty when itemId exists but belongs to a different journey. */
+    Optional<JourneyItem> findByIdAndGeschichteId(UUID id, UUID geschichteId);
+
+    /** Returns only the IDs — used for set-equality check in reorder. */
+    @Query("SELECT i.id FROM JourneyItem i WHERE i.geschichte.id = :geschichteId")
+    Set<UUID> findIdsByGeschichteId(@Param("geschichteId") UUID geschichteId);
+
+    /** MAX position for computing the next append position; returns empty when journey has no items. */
+    @Query("SELECT MAX(i.position) FROM JourneyItem i WHERE i.geschichte.id = :geschichteId")
+    Optional<Integer> findMaxPositionByGeschichteId(@Param("geschichteId") UUID geschichteId);
+
+    /** COUNT for the 100-item cap check — COUNT(*)-based, never MAX(position)-derived. */
+    long countByGeschichteId(UUID geschichteId);
+
+    /**
+     * Dedup guard: true when the document is already linked to this journey.
+     * Explicit JPQL, not a derived query: the transient {@code getDocumentId()}
+     * getter on JourneyItem makes Spring Data resolve the derived path as a
+     * direct {@code documentId} attribute, which Hibernate cannot map.
+     */
+    @Query("""
+            SELECT COUNT(i) > 0 FROM JourneyItem i
+            WHERE i.geschichte.id = :geschichteId AND i.document.id = :documentId
+            """)
+    boolean existsByGeschichteIdAndDocumentId(
+            @Param("geschichteId") UUID geschichteId, @Param("documentId") UUID documentId);
+
+    /**
+     * Deletes note-less items (note IS NULL or note = '') linked to the given document.
+     * Used by JourneyItemDocumentDeleteListener before the document row is removed, so
+     * the FK ON DELETE SET NULL never fires on rows that would violate chk_journey_item_not_empty.
+     * Explicit JPQL — same trap as existsByGeschichteIdAndDocumentId: the transient
+     * getDocumentId() getter makes Spring Data unable to resolve a derived query path.
+     * clearAutomatically = true invalidates the L1 cache so AC-2's "note-carrying survives"
+     * assertion never reads a stale entity. flushAutomatically = true makes the
+     * flush-before-delete contract explicit rather than relying on Hibernate AUTO flush mode.
+     */
+    @Modifying(clearAutomatically = true, flushAutomatically = true)
+    @Query("DELETE FROM JourneyItem i WHERE i.document.id = :documentId AND (i.note IS NULL OR i.note = '')")
+    int deleteNoteLessByDocumentId(@Param("documentId") UUID documentId);
+
+    /**
+     * Loads journey items with their linked Document in a single JOIN FETCH query,
+     * eliminating the N+1 SELECT that would occur when accessing item.getDocument()
+     * lazily for each item. Items without a document (note-only) are included via
+     * LEFT JOIN. Ordered by position ASC.
+     */
+    @Query("SELECT ji FROM JourneyItem ji LEFT JOIN FETCH ji.document WHERE ji.geschichte.id = :geschichteId ORDER BY ji.position ASC")
+    List<JourneyItem> findByGeschichteIdWithDocument(@Param("geschichteId") UUID geschichteId);
+}

backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemService.java

@@ -0,0 +1,276 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.raddatz.familienarchiv.audit.AuditKind;
+import org.raddatz.familienarchiv.audit.AuditService;
+import org.raddatz.familienarchiv.document.DatePrecision;
+import org.raddatz.familienarchiv.document.Document;
+import org.raddatz.familienarchiv.document.DocumentService;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.geschichte.Geschichte;
+import org.raddatz.familienarchiv.geschichte.GeschichteQueryService;
+import org.raddatz.familienarchiv.geschichte.PersonNameFormatter;
+import org.raddatz.familienarchiv.person.Person;
+import org.raddatz.familienarchiv.user.AppUser;
+import org.raddatz.familienarchiv.user.UserService;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.dao.DataIntegrityViolationException;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.*;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class JourneyItemService {
+
+    static final int MAX_ITEMS = 100;
+    static final int POSITION_STEP = 10;
+    // 2000 per the editor spec — frontend maxlength and the i18n error message agree (#793).
+    static final int MAX_NOTE_LENGTH = 2000;
+
+    private final JourneyItemRepository journeyItemRepository;
+    private final GeschichteQueryService geschichteQueryService;
+    private final DocumentService documentService;
+    private final AuditService auditService;
+    private final UserService userService;
+
+    @Transactional
+    public JourneyItemView append(UUID geschichteId, JourneyItemCreateDTO dto) {
+        Geschichte g = geschichteQueryService.findById(geschichteId)
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.GESCHICHTE_NOT_FOUND,
+                        "Geschichte not found: " + geschichteId));
+
+        long count = journeyItemRepository.countByGeschichteId(geschichteId);
+        if (count >= MAX_ITEMS) {
+            throw DomainException.conflict(ErrorCode.JOURNEY_AT_CAPACITY,
+                    "Journey has reached the maximum of 100 items");
+        }
+
+        String note = normalizeNote(dto.getNote());
+
+        if (dto.getDocumentId() == null && note == null) {
+            throw DomainException.badRequest(ErrorCode.VALIDATION_ERROR,
+                    "At least one of documentId or note must be provided");
+        }
+
+        if (note != null && note.length() > MAX_NOTE_LENGTH) {
+            throw DomainException.badRequest(ErrorCode.JOURNEY_NOTE_TOO_LONG,
+                    "Note exceeds maximum length of " + MAX_NOTE_LENGTH + " characters");
+        }
+
+        Document doc = null;
+        if (dto.getDocumentId() != null) {
+            if (journeyItemRepository.existsByGeschichteIdAndDocumentId(geschichteId, dto.getDocumentId())) {
+                throw DomainException.conflict(ErrorCode.JOURNEY_DOCUMENT_ALREADY_ADDED,
+                        "Document already in journey: " + dto.getDocumentId());
+            }
+            doc = documentService.findSummaryByIdInternal(dto.getDocumentId());
+        }
+
+        int nextPosition = journeyItemRepository.findMaxPositionByGeschichteId(geschichteId)
+                .map(max -> max + POSITION_STEP)
+                .orElse(POSITION_STEP);
+
+        JourneyItem item = JourneyItem.builder()
+                .geschichte(g)
+                .position(nextPosition)
+                .document(doc)
+                .note(note)
+                .build();
+        // saveAndFlush so the partial unique index on (geschichte_id, document_id)
+        // fires here, not at commit — two concurrent appends can both pass the
+        // exists() pre-check above, and the index is the atomic backstop (V74).
+        JourneyItem saved;
+        try {
+            saved = journeyItemRepository.saveAndFlush(item);
+        } catch (DataIntegrityViolationException e) {
+            // Only the dedup index earns the friendly 409 — any other integrity
+            // failure (e.g. an FK violation on a concurrently deleted document)
+            // must not be mislabeled as "already added".
+            if (!isDuplicateDocumentViolation(e)) {
+                throw e;
+            }
+            throw DomainException.conflict(ErrorCode.JOURNEY_DOCUMENT_ALREADY_ADDED,
+                    "Document already in journey: " + dto.getDocumentId());
+        }
+
+        UUID actorId = currentUser().getId();
+        auditService.logAfterCommit(AuditKind.JOURNEY_ITEM_ADDED, actorId, null,
+                Map.of("geschichteId", geschichteId, "itemId", saved.getId()));
+
+        return toView(saved);
+    }
+
+    @Transactional
+    public JourneyItemView updateNote(UUID geschichteId, UUID itemId, JourneyItemUpdateDTO dto) {
+        JourneyItem item = journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.JOURNEY_ITEM_NOT_FOUND,
+                        "Journey item not found: " + itemId));
+
+        // null = field absent from JSON → no-op
+        Optional<String> noteField = dto.getNote();
+        if (noteField == null) {
+            return toView(item);
+        }
+
+        String note = normalizeNote(noteField.orElse(null));
+
+        if (note != null && note.length() > MAX_NOTE_LENGTH) {
+            throw DomainException.badRequest(ErrorCode.JOURNEY_NOTE_TOO_LONG,
+                    "Note exceeds maximum length of " + MAX_NOTE_LENGTH + " characters");
+        }
+
+        if (note == null && item.getDocumentId() == null) {
+            throw DomainException.badRequest(ErrorCode.VALIDATION_ERROR,
+                    "Cannot clear note on an item that has no linked document");
+        }
+
+        item.setNote(note);
+        JourneyItem saved = journeyItemRepository.save(item);
+
+        UUID actorId = currentUser().getId();
+        auditService.logAfterCommit(AuditKind.JOURNEY_ITEM_NOTE_UPDATED, actorId, null,
+                Map.of("geschichteId", geschichteId, "itemId", itemId));
+
+        return toView(saved);
+    }
+
+    @Transactional
+    public void delete(UUID geschichteId, UUID itemId) {
+        JourneyItem item = journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.JOURNEY_ITEM_NOT_FOUND,
+                        "Journey item not found: " + itemId));
+
+        journeyItemRepository.delete(item);
+
+        UUID actorId = currentUser().getId();
+        auditService.logAfterCommit(AuditKind.JOURNEY_ITEM_REMOVED, actorId, null,
+                Map.of("geschichteId", geschichteId, "itemId", itemId));
+    }
+
+    @Transactional
+    public List<JourneyItemView> reorder(UUID geschichteId, JourneyReorderDTO dto) {
+        if (!geschichteQueryService.existsById(geschichteId)) {
+            throw DomainException.notFound(ErrorCode.GESCHICHTE_NOT_FOUND,
+                    "Geschichte not found: " + geschichteId);
+        }
+        Set<UUID> existingIds = journeyItemRepository.findIdsByGeschichteId(geschichteId);
+        List<UUID> requestedIds = dto.getItemIds() != null ? dto.getItemIds() : List.of();
+
+        if (requestedIds.size() != new HashSet<>(requestedIds).size()) {
+            throw DomainException.badRequest(ErrorCode.VALIDATION_ERROR,
+                    "Duplicate item IDs in reorder request");
+        }
+
+        if (!existingIds.equals(new HashSet<>(requestedIds))) {
+            throw DomainException.badRequest(ErrorCode.VALIDATION_ERROR,
+                    "Requested item IDs do not match the journey's existing items");
+        }
+
+        if (requestedIds.isEmpty()) {
+            return List.of();
+        }
+
+        List<JourneyItem> items = journeyItemRepository.findByGeschichteIdOrderByPosition(geschichteId);
+        Map<UUID, JourneyItem> itemMap = new HashMap<>();
+        for (JourneyItem item : items) {
+            itemMap.put(item.getId(), item);
+        }
+
+        List<JourneyItem> toSave = new ArrayList<>(requestedIds.size());
+        for (int i = 0; i < requestedIds.size(); i++) {
+            JourneyItem item = itemMap.get(requestedIds.get(i));
+            item.setPosition((i + 1) * POSITION_STEP);
+            toSave.add(item);
+        }
+        List<JourneyItem> reordered = journeyItemRepository.saveAll(toSave);
+
+        UUID actorId = currentUser().getId();
+        auditService.logAfterCommit(AuditKind.JOURNEY_ITEMS_REORDERED, actorId, null,
+                Map.of("geschichteId", geschichteId, "itemCount", reordered.size()));
+
+        return reordered.stream().map(this::toView).toList();
+    }
+
+    public List<JourneyItemView> getItems(UUID geschichteId) {
+        return journeyItemRepository.findByGeschichteIdWithDocument(geschichteId)
+                .stream().map(this::toView).toList();
+    }
+
+    DocumentSummary toSummary(Document doc) {
+        String senderName = buildSenderName(doc);
+        Set<Person> receivers = doc.getReceivers();
+        String receiverName = buildCanonicalReceiverName(receivers);
+
+        return new DocumentSummary(
+                doc.getId(),
+                doc.getTitle(),
+                doc.getDocumentDate(),
+                doc.getMetaDateEnd(),
+                doc.getMetaDatePrecision() != null ? doc.getMetaDatePrecision() : DatePrecision.UNKNOWN,
+                senderName,
+                receiverName,
+                receivers != null ? receivers.size() : 0
+        );
+    }
+
+    JourneyItemView toView(JourneyItem item) {
+        DocumentSummary docSummary = null;
+        Document doc = item.getDocument();
+        if (doc != null) {
+            docSummary = toSummary(doc);
+        }
+        return new JourneyItemView(item.getId(), item.getPosition(), docSummary, item.getNote());
+    }
+
+    private static String buildSenderName(Document doc) {
+        Person sender = doc.getSender();
+        if (sender != null) {
+            String name = PersonNameFormatter.join(sender.getFirstName(), sender.getLastName());
+            if (!name.isBlank()) return name;
+        }
+        String senderText = doc.getSenderText();
+        return (senderText != null && !senderText.isBlank()) ? senderText : null;
+    }
+
+    private static String buildCanonicalReceiverName(Set<Person> receivers) {
+        if (receivers == null || receivers.isEmpty()) return null;
+        return receivers.stream()
+                .min(Comparator.comparing(p -> sortKey(p.getLastName()) + " " + sortKey(p.getFirstName())))
+                .map(p -> {
+                    String name = PersonNameFormatter.join(p.getFirstName(), p.getLastName());
+                    return name.isBlank() ? null : name;
+                })
+                .orElse(null);
+    }
+
+    private static boolean isDuplicateDocumentViolation(DataIntegrityViolationException e) {
+        Throwable cause = e.getCause();
+        if (cause instanceof java.sql.SQLException sql) {
+            return "23505".equals(sql.getSQLState());
+        }
+        return false;
+    }
+
+    private static String normalizeNote(String raw) {
+        if (raw == null || raw.isBlank()) return null;
+        return raw.trim();
+    }
+
+    private static String sortKey(String s) {
+        return s != null ? s : "";
+    }
+
+    private AppUser currentUser() {
+        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
+        if (auth == null || !auth.isAuthenticated()) {
+            throw DomainException.unauthorized("Authentication required");
+        }
+        return userService.findByEmail(auth.getName());
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemUpdateDTO.java

@@ -0,0 +1,19 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import lombok.Data;
+
+import java.util.Optional;
+
+/**
+ * Input for PATCH /api/geschichten/{id}/items/{itemId}.
+ * Three-way semantics via Optional<String>:
+ *   null         → field absent from JSON → leave note unchanged
+ *   Optional.empty() → {"note": null} → clear the note
+ *   Optional.of("x") → {"note": "x"} → set the note
+ *
+ * Jackson 3.x maps JSON null to Optional.empty(); absent fields keep the Java default (null).
+ */
+@Data
+public class JourneyItemUpdateDTO {
+    private Optional<String> note = null;
+}

backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemView.java

@@ -0,0 +1,17 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.util.UUID;
+
+/**
+ * Read-model response for a JourneyItem. Never the JPA entity (which has a
+ * Geschichte back-reference that would leak / hit LazyInitializationException).
+ */
+public record JourneyItemView(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) int position,
+        DocumentSummary document,
+        /** Plain text — not HTML-sanitized. Renderers MUST NOT use {@code @html} or equivalent unsafe output. */
+        String note
+) {}

backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyReorderDTO.java

@@ -0,0 +1,12 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import lombok.Data;
+
+import java.util.List;
+import java.util.UUID;
+
+/** Input for PUT /api/geschichten/{id}/items/reorder. */
+@Data
+public class JourneyReorderDTO {
+    private List<UUID> itemIds;
+}

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

@@ -6,7 +6,9 @@ import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.persistence.*;
 import lombok.*;
 
+import org.raddatz.familienarchiv.document.DatePrecision;
 import org.raddatz.familienarchiv.user.DisplayNameFormatter;
+import java.time.LocalDate;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.UUID;
@@ -49,8 +51,25 @@ public class Person {
     @Column(columnDefinition = "TEXT")
     private String notes;
 
-    private Integer birthYear;
-    private Integer deathYear;
+    // Most precise birth/death date known. Precision mirrors Document.metaDatePrecision:
+    // the date column is nullable, the precision column is NOT NULL with UNKNOWN meaning
+    // "no date" — the V76 CHECK constraints enforce (date IS NULL) = (precision = UNKNOWN).
+    // DatePrecision is imported cross-domain from document/ by design (ADR-039).
+    private LocalDate birthDate;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "birth_date_precision", nullable = false, length = 16)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    @Builder.Default
+    private DatePrecision birthDatePrecision = DatePrecision.UNKNOWN;
+
+    private LocalDate deathDate;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "death_date_precision", nullable = false, length = 16)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    @Builder.Default
+    private DatePrecision deathDatePrecision = DatePrecision.UNKNOWN;
 
     // Hand-curated generation index from canonical-persons.xlsx (G 0 = oldest).
     // Nullable for persons outside the curated family graph. Drives the

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

@@ -66,7 +66,10 @@ public interface PersonRepository extends JpaRepository<Person, UUID> {
     @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.alias, CAST(EXTRACT(YEAR FROM p.birth_date) AS int) AS birthYear,
+                   CAST(EXTRACT(YEAR FROM p.death_date) AS int) AS deathYear,
+                   p.birth_date AS birthDate, p.birth_date_precision AS birthDatePrecision,
+                   p.death_date AS deathDate, p.death_date_precision AS deathDatePrecision, p.notes,
                    p.family_member AS familyMember, p.provisional AS provisional,
                    (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
@@ -79,7 +82,10 @@ public interface PersonRepository extends JpaRepository<Person, UUID> {
     @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.alias, CAST(EXTRACT(YEAR FROM p.birth_date) AS int) AS birthYear,
+                   CAST(EXTRACT(YEAR FROM p.death_date) AS int) AS deathYear,
+                   p.birth_date AS birthDate, p.birth_date_precision AS birthDatePrecision,
+                   p.death_date AS deathDate, p.death_date_precision AS deathDatePrecision, p.notes,
                    p.family_member AS familyMember, p.provisional AS provisional,
                    (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
@@ -89,7 +95,7 @@ public interface PersonRepository extends JpaRepository<Person, UUID> {
                OR LOWER(CONCAT(p.last_name,' ',COALESCE(p.first_name,''))) LIKE LOWER(CONCAT('%',:query,'%'))
                OR LOWER(p.alias) LIKE LOWER(CONCAT('%',:query,'%'))
                OR LOWER(a.last_name) LIKE LOWER(CONCAT('%',:query,'%'))
-            GROUP BY p.id, p.title, p.first_name, p.last_name, p.person_type, p.alias, p.birth_year, p.death_year, p.notes, p.family_member, p.provisional
+            GROUP BY p.id, p.title, p.first_name, p.last_name, p.person_type, p.alias, p.birth_date, p.birth_date_precision, p.death_date, p.death_date_precision, p.notes, p.family_member, p.provisional
             ORDER BY p.last_name ASC, p.first_name ASC
             """,
             nativeQuery = true)
@@ -100,7 +106,10 @@ public interface PersonRepository extends JpaRepository<Person, UUID> {
     @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.alias, CAST(EXTRACT(YEAR FROM p.birth_date) AS int) AS birthYear,
+                   CAST(EXTRACT(YEAR FROM p.death_date) AS int) AS deathYear,
+                   p.birth_date AS birthDate, p.birth_date_precision AS birthDatePrecision,
+                   p.death_date AS deathDate, p.death_date_precision AS deathDatePrecision, p.notes,
                    p.family_member AS familyMember, p.provisional AS provisional,
                    (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
@@ -139,7 +148,10 @@ public interface PersonRepository extends JpaRepository<Person, UUID> {
     @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.alias, CAST(EXTRACT(YEAR FROM p.birth_date) AS int) AS birthYear,
+                   CAST(EXTRACT(YEAR FROM p.death_date) AS int) AS deathYear,
+                   p.birth_date AS birthDate, p.birth_date_precision AS birthDatePrecision,
+                   p.death_date AS deathDate, p.death_date_precision AS deathDatePrecision, p.notes,
                    p.family_member AS familyMember, p.provisional AS provisional,
                    (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
@@ -230,4 +242,7 @@ public interface PersonRepository extends JpaRepository<Person, UUID> {
               )
             """, nativeQuery = true)
     void insertMissingReceiverReference(@Param("source") UUID source, @Param("target") UUID target);
+
+    // Boxed Integer — matches the nullable person.generation column (primitive int would reject null rows).
+    List<Person> findByGeneration(Integer generation);
 }

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

@@ -1,5 +1,6 @@
 package org.raddatz.familienarchiv.person;
 
+import java.time.LocalDate;
 import java.util.ArrayList;
 import java.util.Comparator;
 import java.util.LinkedHashMap;
@@ -16,6 +17,7 @@ import org.springframework.lang.Nullable;
 import org.raddatz.familienarchiv.person.PersonNameAliasDTO;
 import org.raddatz.familienarchiv.person.PersonSummaryDTO;
 import org.raddatz.familienarchiv.person.PersonUpdateDTO;
+import org.raddatz.familienarchiv.document.DatePrecision;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.person.Person;
@@ -208,6 +210,10 @@ public class PersonService {
         return personRepository.findByFamilyMemberTrueOrderByLastNameAscFirstNameAsc();
     }
 
+    public List<Person> getPersonsByGeneration(Integer generation) {
+        return personRepository.findByGeneration(generation);
+    }
+
     @Transactional
     public Person setFamilyMember(UUID personId, boolean familyMember) {
         Person person = getById(personId);
@@ -299,13 +305,20 @@ public class PersonService {
     }
 
     private Person fromCanonical(PersonUpsertCommand cmd) {
+        DatePrecisionPair none = new DatePrecisionPair(null, DatePrecision.UNKNOWN);
+        LifeDates dates = degradeIfConflicting(
+                yearPair(cmd.birthYear()), yearPair(cmd.deathYear()), none, none, cmd.sourceRef());
+        DatePrecisionPair birth = dates.birth();
+        DatePrecisionPair death = dates.death();
         Person person = personRepository.save(Person.builder()
                 .sourceRef(cmd.sourceRef())
                 .firstName(blankToNull(cmd.firstName()))
                 .lastName(cmd.lastName())
                 .notes(blankToNull(cmd.notes()))
-                .birthYear(cmd.birthYear())
-                .deathYear(cmd.deathYear())
+                .birthDate(birth.date())
+                .birthDatePrecision(birth.precision())
+                .deathDate(death.date())
+                .deathDatePrecision(death.precision())
                 .generation(cmd.generation())
                 .familyMember(cmd.familyMember())
                 .personType(cmd.personType() == null ? PersonType.PERSON : cmd.personType())
@@ -328,8 +341,16 @@ public class PersonService {
         existing.setFirstName(preferHuman(existing.getFirstName(), cmd.firstName()));
         existing.setLastName(preferHuman(existing.getLastName(), cmd.lastName()));
         existing.setNotes(preferHuman(existing.getNotes(), cmd.notes()));
-        existing.setBirthYear(preferHuman(existing.getBirthYear(), cmd.birthYear()));
-        existing.setDeathYear(preferHuman(existing.getDeathYear(), cmd.deathYear()));
+        LifeDates dates = degradeIfConflicting(
+                preferHumanDate(existing.getBirthDate(), existing.getBirthDatePrecision(), cmd.birthYear()),
+                preferHumanDate(existing.getDeathDate(), existing.getDeathDatePrecision(), cmd.deathYear()),
+                new DatePrecisionPair(existing.getBirthDate(), existing.getBirthDatePrecision()),
+                new DatePrecisionPair(existing.getDeathDate(), existing.getDeathDatePrecision()),
+                cmd.sourceRef());
+        existing.setBirthDate(dates.birth().date());
+        existing.setBirthDatePrecision(dates.birth().precision());
+        existing.setDeathDate(dates.death().date());
+        existing.setDeathDatePrecision(dates.death().precision());
         existing.setGeneration(preferHuman(existing.getGeneration(), cmd.generation()));
         if (cmd.personType() != null && existing.getPersonType() == PersonType.PERSON) {
             existing.setPersonType(cmd.personType());
@@ -356,6 +377,48 @@ public class PersonService {
         return existing != null ? existing : canonical;
     }
 
+    // Date + precision travel as one value so they can never go out of sync (ADR-039).
+    record DatePrecisionPair(LocalDate date, DatePrecision precision) {}
+
+    record LifeDates(DatePrecisionPair birth, DatePrecisionPair death) {}
+
+    // The canonical path skips validateLifeDates (the form-only guard), so a conflicting
+    // resolved pair would hit chk_person_birth_before_death at flush time and abort the
+    // whole import batch with a raw 500. Degrade instead (REQ-IMP-001: never abort the
+    // batch): keep the person's stored life dates — empty for a new person — and drop the
+    // conflicting canonical refresh. A hand-entered side is preserved by construction,
+    // since preferHumanDate returned it verbatim and it equals the stored value; two
+    // stored values can never conflict with each other (they already satisfied the CHECK).
+    static LifeDates degradeIfConflicting(DatePrecisionPair birth, DatePrecisionPair death,
+                                          DatePrecisionPair existingBirth, DatePrecisionPair existingDeath,
+                                          String sourceRef) {
+        if (birth.date() == null || death.date() == null || !birth.date().isAfter(death.date())) {
+            return new LifeDates(birth, death);
+        }
+        log.warn("Conflicting canonical life dates for {}: birth {} is after death {} — keeping stored values",
+                sourceRef, birth.date(), death.date());
+        return new LifeDates(existingBirth, existingDeath);
+    }
+
+    // preferHuman for life dates (ADR-025 extension): a hand-entered date more precise than
+    // the spreadsheet's year (DAY/MONTH/SEASON/RANGE/APPROX) is preserved on re-import; a
+    // YEAR-precision or absent date is refreshed from the canonical year.
+    static DatePrecisionPair preferHumanDate(LocalDate existingDate, DatePrecision existingPrecision,
+                                             Integer canonicalYear) {
+        boolean handEntered = existingDate != null && existingPrecision != null
+                && existingPrecision != DatePrecision.YEAR && existingPrecision != DatePrecision.UNKNOWN;
+        if (handEntered) {
+            return new DatePrecisionPair(existingDate, existingPrecision);
+        }
+        return yearPair(canonicalYear);
+    }
+
+    private static DatePrecisionPair yearPair(Integer year) {
+        return year != null
+                ? new DatePrecisionPair(LocalDate.of(year, 1, 1), DatePrecision.YEAR)
+                : new DatePrecisionPair(null, DatePrecision.UNKNOWN);
+    }
+
     private static String blankToNull(String s) {
         return (s == null || s.isBlank()) ? null : s.trim();
     }
@@ -375,7 +438,8 @@ public class PersonService {
         if (dto.getPersonType() == PersonType.SKIP) {
             throw DomainException.badRequest(ErrorCode.INVALID_PERSON_TYPE, "SKIP is not a valid person type for manual creation");
         }
-        validateYears(dto.getBirthYear(), dto.getDeathYear());
+        validateLifeDates(dto.getBirthDate(), dto.getBirthDatePrecision(),
+                dto.getDeathDate(), dto.getDeathDatePrecision());
         Person person = Person.builder()
                 .personType(dto.getPersonType())
                 .title(dto.getTitle() == null || dto.getTitle().isBlank() ? null : dto.getTitle().trim())
@@ -383,31 +447,49 @@ public class PersonService {
                 .lastName(dto.getLastName())
                 .alias(dto.getAlias() == null || dto.getAlias().isBlank() ? null : dto.getAlias().trim())
                 .notes(dto.getNotes() == null || dto.getNotes().isBlank() ? null : dto.getNotes().trim())
-                .birthYear(dto.getBirthYear())
-                .deathYear(dto.getDeathYear())
+                .birthDate(dto.getBirthDate())
+                .birthDatePrecision(normalizePrecision(dto.getBirthDatePrecision()))
+                .deathDate(dto.getDeathDate())
+                .deathDatePrecision(normalizePrecision(dto.getDeathDatePrecision()))
                 .generation(dto.getGeneration())
                 .build();
         return personRepository.save(person);
     }
 
-    private void validateYears(Integer birthYear, Integer deathYear) {
-        if (birthYear != null && birthYear <= 0) {
-            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Geburtsjahr muss eine positive Zahl sein");
+    // Cross-field invariants the V76 CHECK constraints also enforce — validated here so the
+    // user gets a structured ErrorCode instead of a raw constraint-violation 500.
+    private void validateLifeDates(LocalDate birthDate, DatePrecision birthPrecision,
+                                   LocalDate deathDate, DatePrecision deathPrecision) {
+        requireDatePrecisionCoherence(birthDate, birthPrecision, "birth");
+        requireDatePrecisionCoherence(deathDate, deathPrecision, "death");
+        if (birthDate != null && deathDate != null && birthDate.isAfter(deathDate)) {
+            throw DomainException.badRequest(ErrorCode.BIRTH_AFTER_DEATH,
+                    "Birth date " + birthDate + " is after death date " + deathDate);
         }
-        if (deathYear != null && deathYear <= 0) {
-            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Todesjahr muss eine positive Zahl sein");
+    }
+
+    private static void requireDatePrecisionCoherence(LocalDate date, DatePrecision precision, String side) {
+        if (date != null && (precision == null || precision == DatePrecision.UNKNOWN)) {
+            throw DomainException.badRequest(ErrorCode.INVALID_DATE_PRECISION,
+                    side + " date is set but its precision is missing or UNKNOWN");
         }
-        if (birthYear != null && deathYear != null && birthYear > deathYear) {
-            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Geburtsjahr darf nicht nach dem Todesjahr liegen");
+        if (date == null && precision != null && precision != DatePrecision.UNKNOWN) {
+            throw DomainException.badRequest(ErrorCode.INVALID_DATE_PRECISION,
+                    side + " date precision " + precision + " is set without a date");
         }
     }
 
+    private static DatePrecision normalizePrecision(DatePrecision precision) {
+        return precision == null ? DatePrecision.UNKNOWN : precision;
+    }
+
     @Transactional
     public Person updatePerson(UUID id, PersonUpdateDTO dto) {
         if (dto.getPersonType() == PersonType.SKIP) {
             throw DomainException.badRequest(ErrorCode.INVALID_PERSON_TYPE, "SKIP is not a valid person type for manual editing");
         }
-        validateYears(dto.getBirthYear(), dto.getDeathYear());
+        validateLifeDates(dto.getBirthDate(), dto.getBirthDatePrecision(),
+                dto.getDeathDate(), dto.getDeathDatePrecision());
         Person person = personRepository.findById(id)
                 .orElseThrow(() -> DomainException.notFound(ErrorCode.PERSON_NOT_FOUND, "Person not found: " + id));
         person.setPersonType(dto.getPersonType());
@@ -416,8 +498,10 @@ public class PersonService {
         person.setLastName(dto.getLastName());
         person.setAlias(dto.getAlias() == null || dto.getAlias().isBlank() ? null : dto.getAlias().trim());
         person.setNotes(dto.getNotes() == null || dto.getNotes().isBlank() ? null : dto.getNotes().trim());
-        person.setBirthYear(dto.getBirthYear());
-        person.setDeathYear(dto.getDeathYear());
+        person.setBirthDate(dto.getBirthDate());
+        person.setBirthDatePrecision(normalizePrecision(dto.getBirthDatePrecision()));
+        person.setDeathDate(dto.getDeathDate());
+        person.setDeathDatePrecision(normalizePrecision(dto.getDeathDatePrecision()));
         // Form path: a human can clear generation back to null. Unlike the importer
         // which routes through preferHuman, we write the DTO value verbatim.
         person.setGeneration(dto.getGeneration());

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

@@ -1,5 +1,8 @@
 package org.raddatz.familienarchiv.person;
 
+import org.raddatz.familienarchiv.document.DatePrecision;
+
+import java.time.LocalDate;
 import java.util.UUID;
 
 /**
@@ -16,6 +19,13 @@ public interface PersonSummaryDTO {
     String getAlias();
     Integer getBirthYear();
     Integer getDeathYear();
+    // Full date + precision alongside the derived years: list consumers that render
+    // precise life dates (mention dropdown) read these; year-only consumers keep
+    // the cheaper getBirthYear/getDeathYear.
+    LocalDate getBirthDate();
+    DatePrecision getBirthDatePrecision();
+    LocalDate getDeathDate();
+    DatePrecision getDeathDatePrecision();
     String getNotes();
     boolean isFamilyMember();
     boolean isProvisional();

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

@@ -5,8 +5,11 @@ import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotNull;
 import jakarta.validation.constraints.Size;
 import lombok.Data;
+import org.raddatz.familienarchiv.document.DatePrecision;
 import org.raddatz.familienarchiv.person.PersonType;
 
+import java.time.LocalDate;
+
 @Data
 public class PersonUpdateDTO {
     @NotNull
@@ -21,8 +24,10 @@ public class PersonUpdateDTO {
     private String alias;
     @Size(max = 5000)
     private String notes;
-    private Integer birthYear;
-    private Integer deathYear;
+    private LocalDate birthDate;
+    private DatePrecision birthDatePrecision;
+    private LocalDate deathDate;
+    private DatePrecision deathDatePrecision;
     // Mirror of the persons.generation CHECK constraint (V70). Bounds live in
     // PersonGeneration so DB, DTO, and importer all read from one place.
     @Min(PersonGeneration.MIN_GENERATION)

backend/src/main/java/org/raddatz/familienarchiv/person/relationship/RelationshipInferenceService.java

@@ -96,7 +96,9 @@ public class RelationshipInferenceService {
             if (p == null) continue;
             List<RelationToken> path = shortestPaths.get(id);
             PersonNodeDTO node = new PersonNodeDTO(
-                    p.getId(), p.getDisplayName(), p.getBirthYear(), p.getDeathYear(),
+                    p.getId(), p.getDisplayName(),
+                    RelationshipService.yearOf(p.getBirthDate()),
+                    RelationshipService.yearOf(p.getDeathDate()),
                     p.getGeneration(), p.isFamilyMember());
             out.add(new InferredRelationshipWithPersonDTO(node, labelFor(path), path.size()));
         }

backend/src/main/java/org/raddatz/familienarchiv/person/relationship/RelationshipService.java

@@ -15,6 +15,7 @@ import org.springframework.dao.DataIntegrityViolationException;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import java.time.LocalDate;
 import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.List;
@@ -66,7 +67,8 @@ public class RelationshipService {
         for (Person p : familyMembers) {
             familyIds.add(p.getId());
             nodes.add(new PersonNodeDTO(
-                    p.getId(), p.getDisplayName(), p.getBirthYear(), p.getDeathYear(),
+                    p.getId(), p.getDisplayName(),
+                    yearOf(p.getBirthDate()), yearOf(p.getDeathDate()),
                     p.getGeneration(), true));
         }
 
@@ -84,6 +86,15 @@ public class RelationshipService {
         return new NetworkDTO(nodes, edges);
     }
 
+    /**
+     * Returns all {@code SPOUSE_OF} edges with both person sides JOIN FETCHed.
+     * Used by {@code TimelineService.assembleDerivedEvents()} to build Heirat events
+     * without per-edge N+1 queries.
+     */
+    public List<PersonRelationship> findAllSpouseEdges() {
+        return relationshipRepository.findAllByRelationTypeIn(List.of(RelationType.SPOUSE_OF));
+    }
+
     @Transactional
     public RelationshipDTO addRelationship(UUID personId, CreateRelationshipRequest dto) {
         if (personId.equals(dto.relatedPersonId())) {
@@ -155,6 +166,13 @@ public class RelationshipService {
         return (s == null || s.isBlank()) ? null : s.trim();
     }
 
+    // Stammbaum DTOs stay year-shaped: derive the year from the LocalDate, null-safe
+    // for persons with no date entered (ADR-039, REQ-PERSON-DATE-01). Package-private
+    // so RelationshipInferenceService shares the same derivation.
+    static Integer yearOf(LocalDate date) {
+        return date != null ? date.getYear() : null;
+    }
+
     private static void validateYears(Integer fromYear, Integer toYear) {
         if (fromYear != null && toYear != null && toYear < fromYear) {
             throw DomainException.badRequest(
@@ -170,11 +188,11 @@ public class RelationshipService {
                 p.getId(),
                 rp.getId(),
                 p.getDisplayName(),
-                p.getBirthYear(),
-                p.getDeathYear(),
+                yearOf(p.getBirthDate()),
+                yearOf(p.getDeathDate()),
                 rp.getDisplayName(),
-                rp.getBirthYear(),
-                rp.getDeathYear(),
+                yearOf(rp.getBirthDate()),
+                yearOf(rp.getDeathDate()),
                 r.getRelationType(),
                 r.getFromYear(),
                 r.getToYear(),

backend/src/main/java/org/raddatz/familienarchiv/timeline/DerivedEventType.java

@@ -0,0 +1,8 @@
+package org.raddatz.familienarchiv.timeline;
+
+/** Discriminator for derived life-events assembled from Person / PersonRelationship data. */
+public enum DerivedEventType {
+    BIRTH,
+    DEATH,
+    MARRIAGE
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/EventType.java

@@ -0,0 +1,17 @@
+package org.raddatz.familienarchiv.timeline;
+
+/**
+ * Kind of a curated {@link TimelineEvent}.
+ *
+ * <p>The string value names are a <strong>stable frontend styling contract</strong>: the
+ * Svelte timeline components hard-code {@code "PERSONAL"} (family accent) and
+ * {@code "HISTORICAL"} (muted world accent) as Tailwind class-map keys. There is no
+ * mapping layer — renaming either value requires a coordinated frontend change. See
+ * ADR-040.
+ */
+public enum EventType {
+    /** A family/personal event (birth, wedding, move) — rendered with the family accent. */
+    PERSONAL,
+    /** A world/historical event providing context — rendered with the muted world accent. */
+    HISTORICAL
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/Kind.java

@@ -0,0 +1,7 @@
+package org.raddatz.familienarchiv.timeline;
+
+/** Discriminates curated/derived events from archive letters in {@link TimelineEntryDTO}. */
+public enum Kind {
+    EVENT,
+    LETTER
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineController.java

@@ -0,0 +1,33 @@
+package org.raddatz.familienarchiv.timeline;
+
+import jakarta.validation.constraints.Min;
+import lombok.RequiredArgsConstructor;
+import org.raddatz.familienarchiv.security.Permission;
+import org.raddatz.familienarchiv.security.RequirePermission;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.UUID;
+
+@RestController
+@RequestMapping("/api/timeline")
+@Validated
+@RequiredArgsConstructor
+public class TimelineController {
+
+    private final TimelineService timelineService;
+
+    @GetMapping
+    @RequirePermission(Permission.READ_ALL)
+    public TimelineDTO getTimeline(
+            @RequestParam(required = false) UUID personId,
+            @RequestParam(required = false) @Min(0) Integer generation,
+            @RequestParam(required = false) EventType type,
+            @RequestParam(required = false) Integer fromYear,
+            @RequestParam(required = false) Integer toYear) {
+        return timelineService.assemble(new TimelineFilter(personId, generation, type, fromYear, toYear));
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineDTO.java

@@ -0,0 +1,15 @@
+package org.raddatz.familienarchiv.timeline;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.util.List;
+
+/**
+ * Assembled timeline response. Year bands are sorted ascending (oldest first).
+ * Undated entries have no usable date or {@code UNKNOWN} precision.
+ */
+public record TimelineDTO(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) List<TimelineYearDTO> years,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) List<TimelineEntryDTO> undated
+) {
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineEntryDTO.java

@@ -0,0 +1,42 @@
+package org.raddatz.familienarchiv.timeline;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.raddatz.familienarchiv.document.DatePrecision;
+
+import java.time.LocalDate;
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * Unified DTO for timeline entries — covers curated {@link TimelineEvent} rows, derived
+ * life-events ({@link DerivedEventType}), and archive letters (Documents).
+ *
+ * <p><b>Edit-affordance contract (for issue #7):</b> {@code derived == true || eventId == null}
+ * means no edit link should be rendered by the frontend.
+ *
+ * <p><b>Letter display fields:</b> {@code senderName} — {@code ""} means unknown/unlinked
+ * correspondent; frontend renders {@code 'Unbekannt'} fallback. Only populated for
+ * {@link Kind#LETTER} entries.
+ *
+ * <p><b>Type field:</b> {@code null} for {@link Kind#LETTER} entries; frontend must not render
+ * an event-type badge for letters.
+ *
+ * <p>Callers of {@code TimelineEventService.assembleDerivedEvents()} must independently enforce
+ * {@code READ_ALL} authorization before invoking that method (see ADR-043).
+ */
+public record TimelineEntryDTO(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) Kind kind,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) DatePrecision precision,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) boolean derived,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String senderName,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String receiverName,
+        LocalDate eventDate,
+        LocalDate eventDateEnd,
+        String title,
+        EventType type,
+        UUID eventId,
+        UUID documentId,
+        List<UUID> linkedPersonIds,
+        DerivedEventType derivedType
+) {
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineEvent.java

@@ -0,0 +1,134 @@
+package org.raddatz.familienarchiv.timeline;
+
+import jakarta.persistence.*;
+import lombok.*;
+import org.hibernate.annotations.BatchSize;
+import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.annotations.UpdateTimestamp;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import org.raddatz.familienarchiv.document.DatePrecision;
+import org.raddatz.familienarchiv.document.Document;
+import org.raddatz.familienarchiv.person.Person;
+
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * A curated event on the family timeline (Zeitstrahl). Unlike a {@link Document}, which is
+ * OCR-derived, a {@code TimelineEvent} is authored by curators — hence the optimistic-lock
+ * {@link #version} and the {@link #createdBy}/{@link #updatedBy} audit trail that
+ * {@code Document} lacks.
+ *
+ * <p>The date block ({@link #eventDate}, {@link #precision}, {@link #eventDateEnd}) mirrors
+ * {@code Document}'s so events and letters share one rendering path. The mirror applies to
+ * the date block only — the audit footprint deliberately diverges (see ADR-040).
+ */
+@Entity
+@Table(name = "timeline_events")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class TimelineEvent {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID id;
+
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String title;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false, length = 16)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private EventType type;
+
+    /** The most precise date known for the event. Always present — a curated event is never undated. */
+    @Column(name = "event_date", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private LocalDate eventDate;
+
+    /**
+     * Precision of {@link #eventDate}. Reuses {@code document.DatePrecision} (one rendering
+     * path; see ADR-025 / ADR-040). Every value except {@code UNKNOWN} is legal for a curated
+     * event — including {@code SEASON} ("Sommer 1914") and {@code APPROX} ("ca. 1914"). The DB
+     * CHECK forbids exactly {@code UNKNOWN}; do not narrow it further.
+     */
+    @Enumerated(EnumType.STRING)
+    @Column(name = "date_precision", nullable = false, length = 16)
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private DatePrecision precision = DatePrecision.YEAR;
+
+    /** Range end — non-null <strong>iff</strong> {@link #precision} is {@code RANGE} (DB CHECK, both directions). */
+    @Column(name = "event_date_end")
+    private LocalDate eventDateEnd;
+
+    @Column(columnDefinition = "TEXT")
+    private String description;
+
+    /** People the event involves. */
+    @ManyToMany(fetch = FetchType.LAZY)
+    @JoinTable(name = "timeline_event_persons",
+            joinColumns = @JoinColumn(name = "timeline_event_id"),
+            inverseJoinColumns = @JoinColumn(name = "person_id"))
+    @BatchSize(size = 50)
+    @Builder.Default
+    private Set<Person> persons = new HashSet<>();
+
+    /** Optional supporting letters linked to the event. */
+    @ManyToMany(fetch = FetchType.LAZY)
+    @JoinTable(name = "timeline_event_documents",
+            joinColumns = @JoinColumn(name = "timeline_event_id"),
+            inverseJoinColumns = @JoinColumn(name = "document_id"))
+    @BatchSize(size = 50)
+    @Builder.Default
+    private Set<Document> documents = new HashSet<>();
+
+    /**
+     * UUID of the {@code AppUser} who created the event. Bare UUID, no FK to {@code app_users}
+     * (sidecar pattern — keeps {@code timeline} decoupled from {@code user}). Server-populated
+     * from the session principal; never accepted from client input (authorship-forgery vector,
+     * CWE-639 — see ADR-040).
+     */
+    @Column(name = "created_by", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID createdBy;
+
+    @CreationTimestamp
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private LocalDateTime createdAt;
+
+    /**
+     * UUID of the {@code AppUser} who last edited the event. Populated from the session
+     * principal in {@code TimelineEventService}; <strong>must be set before every
+     * {@code save()}</strong> — {@code @UpdateTimestamp} on {@link #updatedAt} does NOT set this
+     * automatically, so without an explicit set the timestamp advances while the "who" goes
+     * stale. Same forgery rationale as {@link #createdBy}.
+     */
+    @Column(name = "updated_by", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID updatedBy;
+
+    @UpdateTimestamp
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private LocalDateTime updatedAt;
+
+    /**
+     * Optimistic-lock version for the multi-curator edit flow (#775). Object {@code Long}
+     * (not primitive) so it is {@code null} before first persist; Hibernate sets {@code 0} on
+     * insert. A concurrent-write conflict must be translated to {@code DomainException.conflict}
+     * in the service layer (ADR-040) — otherwise it surfaces as HTTP 500 with Hibernate
+     * internals (CWE-209).
+     */
+    @Version
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private Long version;
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineEventController.java

@@ -0,0 +1,71 @@
+package org.raddatz.familienarchiv.timeline;
+
+import jakarta.validation.Valid;
+
+import lombok.RequiredArgsConstructor;
+
+import org.raddatz.familienarchiv.security.Permission;
+import org.raddatz.familienarchiv.security.RequirePermission;
+import org.raddatz.familienarchiv.security.SecurityUtils;
+import org.raddatz.familienarchiv.user.UserService;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.ResponseStatus;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.UUID;
+
+@RestController
+@RequestMapping("/api/timeline/events")
+@RequiredArgsConstructor
+public class TimelineEventController {
+
+    private final TimelineEventService timelineEventService;
+    private final UserService userService;
+
+    /**
+     * No {@code @RequirePermission} on GET by design: the global {@code anyRequest().authenticated()}
+     * rule is the READ_ALL baseline, consistent with {@code DocumentController.getDocument}. Do not
+     * "fix" the missing annotation.
+     */
+    @GetMapping("/{id}")
+    public TimelineEventView getEvent(@PathVariable UUID id) {
+        return timelineEventService.getEvent(id);
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    @RequirePermission(Permission.WRITE_ALL)
+    public TimelineEventView create(@Valid @RequestBody TimelineEventRequest request, Authentication authentication) {
+        return timelineEventService.create(request, requireUserId(authentication));
+    }
+
+    @PutMapping("/{id}")
+    @RequirePermission(Permission.WRITE_ALL)
+    public TimelineEventView update(
+            @PathVariable UUID id,
+            @Valid @RequestBody TimelineEventRequest request,
+            Authentication authentication) {
+        return timelineEventService.update(id, request, requireUserId(authentication));
+    }
+
+    @DeleteMapping("/{id}")
+    @RequirePermission(Permission.WRITE_ALL)
+    public ResponseEntity<Void> delete(@PathVariable UUID id) {
+        timelineEventService.delete(id);
+        return ResponseEntity.noContent().build();
+    }
+
+    private UUID requireUserId(Authentication authentication) {
+        return SecurityUtils.requireUserId(authentication, userService);
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineEventRepository.java

@@ -0,0 +1,9 @@
+package org.raddatz.familienarchiv.timeline;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.UUID;
+
+public interface TimelineEventRepository extends JpaRepository<TimelineEvent, UUID> {
+    // TODO(#777): findByPersonsContaining(Person) needed for the per-person filter
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineEventRequest.java

@@ -0,0 +1,40 @@
+package org.raddatz.familienarchiv.timeline;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+
+import org.raddatz.familienarchiv.document.DatePrecision;
+
+import java.time.LocalDate;
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * Flat input DTO for creating/updating a {@link TimelineEvent}. Bean Validation fires at the
+ * controller boundary (via {@code @Valid}) and produces a 400 {@code VALIDATION_ERROR} for the
+ * presence/size constraints below; cross-field rules (the RANGE invariant), date normalization,
+ * id dedupe, and the title-length structured-error guard live in {@code TimelineEventService}.
+ *
+ * <p><strong>{@code createdBy}/{@code updatedBy} are intentionally absent.</strong> Authorship is
+ * server-populated from the session principal only — accepting it from the body would be an
+ * authorship-forgery / mass-assignment vector (CWE-639; see ADR-040 §7).
+ *
+ * @param version optional optimistic-lock concurrency token (the {@code @Version} the client last
+ *                saw), applied on <em>update</em> only. This is a concurrency token, <strong>not</strong>
+ *                an authorship field, so it is deliberately exempt from the §7 server-only audit rule.
+ *                Null on update means "no concurrency check" (last-write-wins). No range validation —
+ *                a stale/negative value is simply a mismatch the lock rejects at flush; the lock, not
+ *                a validator, is the control.
+ */
+public record TimelineEventRequest(
+        @NotBlank @Size(max = 255) String title,
+        @NotNull EventType type,
+        @NotNull LocalDate eventDate,
+        DatePrecision precision,
+        LocalDate eventDateEnd,
+        @Size(max = 5000) String description,
+        Long version,
+        @Size(max = 50) List<UUID> personIds,
+        @Size(max = 50) List<UUID> documentIds
+) {}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineEventService.java

@@ -0,0 +1,327 @@
+package org.raddatz.familienarchiv.timeline;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import org.raddatz.familienarchiv.document.DatePrecision;
+import org.raddatz.familienarchiv.document.Document;
+import org.raddatz.familienarchiv.document.DocumentService;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.person.Person;
+import org.raddatz.familienarchiv.person.PersonService;
+import org.raddatz.familienarchiv.person.relationship.PersonRelationship;
+import org.raddatz.familienarchiv.person.relationship.RelationshipService;
+import org.raddatz.familienarchiv.timeline.TimelineEventView.DocumentRef;
+import org.raddatz.familienarchiv.timeline.TimelineEventView.PersonView;
+
+import org.springframework.orm.ObjectOptimisticLockingFailureException;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDate;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * Curator CRUD for {@link TimelineEvent}. Persons and documents are resolved through their own
+ * services (never their repositories). All four body-returning operations return a
+ * {@link TimelineEventView} assembled in-transaction — the entity is never serialized (ADR-040 §2).
+ */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class TimelineEventService {
+
+    private static final int MAX_TITLE_LENGTH = 255;
+
+    private final TimelineEventRepository events;
+    private final PersonService personService;
+    private final DocumentService documentService;
+    private final RelationshipService relationshipService;
+
+    @Transactional
+    public TimelineEventView create(TimelineEventRequest request, UUID actorId) {
+        DatePrecision precision = effectivePrecision(request);
+        validateRangeInvariant(request, precision);
+        validateTitleLength(request);
+
+        TimelineEvent event = TimelineEvent.builder()
+                .title(request.title())
+                .type(request.type())
+                .eventDate(normalizeEventDate(request.eventDate(), precision))
+                .precision(precision)
+                .eventDateEnd(request.eventDateEnd())
+                .description(request.description())
+                .persons(resolvePersons(request.personIds()))
+                .documents(resolveDocuments(request.documentIds()))
+                .createdBy(actorId)
+                .updatedBy(actorId)
+                .build();
+
+        return toView(events.saveAndFlush(event));
+    }
+
+    @Transactional
+    public TimelineEventView update(UUID id, TimelineEventRequest request, UUID actorId) {
+        TimelineEvent event = events.findById(id)
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.TIMELINE_EVENT_NOT_FOUND,
+                        "Timeline event not found: " + id));
+        requireVersionMatch(request, event);
+        DatePrecision precision = effectivePrecision(request);
+        validateRangeInvariant(request, precision);
+        validateTitleLength(request);
+        applyUpdate(event, request, precision, actorId);
+
+        // saveAndFlush (not save) so the versioned UPDATE …WHERE version=? fires HERE, inside the
+        // try — a bare save() flushes at commit, after this method returns, so the exception would
+        // escape the catch and surface as a 500. Catch the Spring-translated type, not JPA's.
+        try {
+            return toView(events.saveAndFlush(event));
+        } catch (ObjectOptimisticLockingFailureException ex) {
+            throw DomainException.conflict(ErrorCode.TIMELINE_EVENT_CONFLICT,
+                    "Timeline event was modified concurrently: " + id);
+        }
+    }
+
+    @Transactional
+    public void delete(UUID id) {
+        TimelineEvent event = events.findById(id)
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.TIMELINE_EVENT_NOT_FOUND,
+                        "Timeline event not found: " + id));
+        events.delete(event);
+    }
+
+    /**
+     * View-assembly read. {@code @Transactional(readOnly = true)} is load-bearing, not optional:
+     * the LAZY {@code persons}/{@code documents} collections are traversed during {@link #toView}
+     * assembly, and under {@code open-in-view: false} a closed session there is a
+     * {@code LazyInitializationException} (ADR-022 / {@code getDocumentDetail} precedent).
+     */
+    @Transactional(readOnly = true)
+    public TimelineEventView getEvent(UUID id) {
+        TimelineEvent event = events.findById(id)
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.TIMELINE_EVENT_NOT_FOUND,
+                        "Timeline event not found: " + id));
+        return toView(event);
+    }
+
+    // --- update mechanics: mutate the managed entity, never reassign collections ---
+
+    private void applyUpdate(TimelineEvent event, TimelineEventRequest request, DatePrecision precision, UUID actorId) {
+        event.setTitle(request.title());
+        event.setType(request.type());
+        event.setEventDate(normalizeEventDate(request.eventDate(), precision));
+        event.setPrecision(precision);
+        event.setEventDateEnd(request.eventDateEnd());
+        event.setDescription(request.description());
+        replaceLinks(event, request);
+        event.setUpdatedBy(actorId); // preserve createdBy — only the editor changes
+    }
+
+    /**
+     * Compares the client's concurrency token against the freshly-loaded version (the Q1
+     * "last-seen version" token). A mismatch means the client edited stale data → 409.
+     *
+     * <p>This explicit compare is the control — NOT {@code event.setVersion(clientVersion)} before
+     * flush. Setting {@code @Version} on a <em>managed</em> entity is silently ignored by Hibernate
+     * for the optimistic check: it uses its own loaded-version snapshot for the
+     * {@code UPDATE … WHERE version=?} clause, so a stale token never reaches the DB. The native
+     * {@code @Version} increment still happens on every save, and the {@code saveAndFlush}+catch
+     * below remains the backstop for two transactions flushing concurrently; this guard is what
+     * catches the human-timescale "B submitted a form based on a version A already superseded" case.
+     * A null token means no check (last-write-wins) until #9 always sends it.
+     */
+    private void requireVersionMatch(TimelineEventRequest request, TimelineEvent event) {
+        if (request.version() != null && !request.version().equals(event.getVersion())) {
+            throw DomainException.conflict(ErrorCode.TIMELINE_EVENT_CONFLICT,
+                    "Timeline event was modified concurrently: " + event.getId());
+        }
+    }
+
+    /**
+     * Replaces (set semantics) the link collections. Mutates the existing managed collections —
+     * Hibernate does not track a reassigned reference, and a fresh {@code Set} risks orphan join
+     * rows against the {@code ON DELETE CASCADE} join tables. A null or empty list clears all links.
+     */
+    private void replaceLinks(TimelineEvent event, TimelineEventRequest request) {
+        event.getPersons().clear();
+        event.getPersons().addAll(resolvePersons(request.personIds()));
+        event.getDocuments().clear();
+        event.getDocuments().addAll(resolveDocuments(request.documentIds()));
+    }
+
+    // --- validation / normalization ---
+
+    /**
+     * Mirrors the DB biconditional CHECK chk_timeline_event_range — both presence directions — and
+     * additionally enforces date ordering, which the DB CHECK does NOT: {@code eventDateEnd} may
+     * equal but never precede {@code eventDate}. Without this guard a reversed range (end before
+     * start) persists silently and renders as a negative span. Equal dates are a valid one-day
+     * closed range.
+     */
+    private void validateRangeInvariant(TimelineEventRequest request, DatePrecision precision) {
+        boolean isRange = precision == DatePrecision.RANGE;
+        if (request.eventDateEnd() != null && !isRange) {
+            throw DomainException.badRequest(ErrorCode.INVALID_DATE_RANGE,
+                    "eventDateEnd is only valid when precision is RANGE");
+        }
+        if (isRange && request.eventDateEnd() == null) {
+            throw DomainException.badRequest(ErrorCode.INVALID_DATE_RANGE,
+                    "A RANGE event requires a non-null eventDateEnd");
+        }
+        if (isRange && request.eventDateEnd().isBefore(request.eventDate())) {
+            throw DomainException.badRequest(ErrorCode.INVALID_DATE_RANGE,
+                    "eventDateEnd must not precede eventDate");
+        }
+    }
+
+    /**
+     * Load-bearing only for non-HTTP callers: the DTO {@code @Size(max = 255)} already covers HTTP
+     * callers, but a non-HTTP caller could otherwise push an over-long title to the VARCHAR(255)
+     * column and get a raw {@code DataIntegrityViolationException} → 500. Do not delete as
+     * "duplicate validation".
+     */
+    private void validateTitleLength(TimelineEventRequest request) {
+        if (request.title() != null && request.title().length() > MAX_TITLE_LENGTH) {
+            throw DomainException.badRequest(ErrorCode.TIMELINE_TITLE_TOO_LONG,
+                    "Title exceeds maximum length of " + MAX_TITLE_LENGTH + " characters");
+        }
+    }
+
+    private DatePrecision effectivePrecision(TimelineEventRequest request) {
+        return request.precision() != null ? request.precision() : DatePrecision.YEAR;
+    }
+
+    private LocalDate normalizeEventDate(LocalDate eventDate, DatePrecision precision) {
+        return precision == DatePrecision.YEAR ? LocalDate.of(eventDate.getYear(), 1, 1) : eventDate;
+    }
+
+    // --- link resolution (fail-closed, dedupe-first) ---
+
+    private Set<Person> resolvePersons(List<UUID> ids) {
+        if (ids == null || ids.isEmpty()) {
+            return new HashSet<>();
+        }
+        // Dedupe FIRST: [idA, idA] is one link, not a 404. findAllById dedupes too, so compare the
+        // resolved size against the DISTINCT input count — a raw ids.size() compare reports a spurious
+        // mismatch.
+        Set<UUID> distinct = new LinkedHashSet<>(ids);
+        List<Person> resolved = personService.getAllById(new ArrayList<>(distinct));
+        if (resolved.size() != distinct.size()) {
+            throw DomainException.notFound(ErrorCode.PERSON_NOT_FOUND, "One or more person IDs not found");
+        }
+        return new HashSet<>(resolved);
+    }
+
+    private Set<Document> resolveDocuments(List<UUID> ids) {
+        if (ids == null || ids.isEmpty()) {
+            return new HashSet<>();
+        }
+        // Per-id loop on purpose: DocumentService has no batch fetch, and per-id gives free
+        // DOCUMENT_NOT_FOUND 404s. getDocumentById is @Transactional(readOnly = true) and joins this
+        // write tx via Spring's default REQUIRED propagation — do NOT "optimize" into a phantom batch.
+        Set<Document> resolved = new HashSet<>();
+        for (UUID documentId : new LinkedHashSet<>(ids)) {
+            resolved.add(documentService.getDocumentById(documentId));
+        }
+        return resolved;
+    }
+
+    // --- derived event assembly ---
+
+    /**
+     * Assembles derived life-events (Geburt/Tod/Heirat) from curated Person and
+     * PersonRelationship data. Computed on read, never persisted.
+     *
+     * <p>Derived events are computed, never persisted, and cannot be mutated via the events API
+     * (enforced in #5). Ids produced by this method are structurally non-UUID
+     * ({@code birth:*}, {@code death:*}, {@code marriage:*}) and MUST be rejected by any
+     * write endpoint — enforced and tested in #5. Callers outside the #5 endpoint must
+     * independently enforce {@code READ_ALL} authorization before invoking this method
+     * (see ADR-043).
+     */
+    @Transactional(readOnly = true)
+    public List<TimelineEntryDTO> assembleDerivedEvents() {
+        List<Person> persons = personService.findAllFamilyMembers();
+        List<PersonRelationship> spouseEdges = relationshipService.findAllSpouseEdges();
+
+        List<TimelineEntryDTO> result = new ArrayList<>();
+        result.addAll(buildBirthEvents(persons));
+        result.addAll(buildDeathEvents(persons));
+        result.addAll(buildMarriageEvents(spouseEdges));
+
+        log.debug("Assembled {} derived events for {} persons", result.size(), persons.size());
+        return result;
+    }
+
+    private List<TimelineEntryDTO> buildBirthEvents(List<Person> persons) {
+        return persons.stream()
+                .filter(p -> p.getBirthDate() != null)
+                .map(p -> new TimelineEntryDTO(
+                        Kind.EVENT, p.getBirthDatePrecision(), true, "", "",
+                        p.getBirthDate(), null,
+                        p.getDisplayName(), EventType.PERSONAL,
+                        null, null, List.of(p.getId()), DerivedEventType.BIRTH))
+                .toList();
+    }
+
+    private List<TimelineEntryDTO> buildDeathEvents(List<Person> persons) {
+        return persons.stream()
+                .filter(p -> p.getDeathDate() != null)
+                .map(p -> new TimelineEntryDTO(
+                        Kind.EVENT, p.getDeathDatePrecision(), true, "", "",
+                        p.getDeathDate(), null,
+                        p.getDisplayName(), EventType.PERSONAL,
+                        null, null, List.of(p.getId()), DerivedEventType.DEATH))
+                .toList();
+    }
+
+    private List<TimelineEntryDTO> buildMarriageEvents(List<PersonRelationship> spouseEdges) {
+        // DB constraint unique_spouse_pair (V55) is the authoritative enforcement;
+        // in-memory dedup on relationship row id is a defensive assertion.
+        Set<UUID> seen = new HashSet<>();
+        List<TimelineEntryDTO> result = new ArrayList<>();
+        for (PersonRelationship r : spouseEdges) {
+            if (seen.add(r.getId())) {
+                // JOIN FETCH in findAllSpouseEdges() guarantees person/relatedPerson are loaded
+                LocalDate eventDate = r.getFromYear() != null
+                        ? LocalDate.of(r.getFromYear(), 1, 1)
+                        : null;
+                DatePrecision precision = r.getFromYear() != null
+                        ? DatePrecision.YEAR
+                        : DatePrecision.UNKNOWN;
+                String title = r.getPerson().getDisplayName()
+                        + " & " + r.getRelatedPerson().getDisplayName();
+                result.add(new TimelineEntryDTO(
+                        Kind.EVENT, precision, true, "", "",
+                        eventDate, null,
+                        title, EventType.PERSONAL,
+                        null, null,
+                        List.of(r.getPerson().getId(), r.getRelatedPerson().getId()),
+                        DerivedEventType.MARRIAGE));
+            }
+        }
+        return result;
+    }
+
+    // --- view assembly (explicit allow-list; never the raw entity) ---
+
+    private TimelineEventView toView(TimelineEvent event) {
+        List<PersonView> persons = event.getPersons().stream()
+                .map(p -> new PersonView(p.getId(), p.getFirstName(), p.getLastName()))
+                .toList();
+        List<DocumentRef> documents = event.getDocuments().stream()
+                .map(d -> new DocumentRef(d.getId(), d.getTitle(), d.getDocumentDate()))
+                .toList();
+        return new TimelineEventView(
+                event.getId(), event.getTitle(), event.getType(), event.getEventDate(),
+                event.getPrecision(), event.getEventDateEnd(), event.getDescription(), event.getVersion(),
+                event.getCreatedBy(), event.getCreatedAt(), event.getUpdatedBy(), event.getUpdatedAt(),
+                persons, documents);
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineEventView.java

@@ -0,0 +1,59 @@
+package org.raddatz.familienarchiv.timeline;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import org.raddatz.familienarchiv.document.DatePrecision;
+
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * Response view for the timeline event endpoints — returned by GET, POST, and PUT alike.
+ * Assembled inside the service transaction (after {@code saveAndFlush} on the write paths, so
+ * {@code version} is non-null) from the managed entity's already-loaded collections. The raw
+ * {@link TimelineEvent} is never serialized: its LAZY {@code persons}/{@code documents}
+ * collections under {@code open-in-view: false} would otherwise 500 (ADR-036/ADR-040 §2), and
+ * splatting the entities would leak curator-internal fields ({@code Person.notes},
+ * {@code provisional}, transcription data) to every READ_ALL reader. The explicit field
+ * allow-list below is that guarantee.
+ */
+public record TimelineEventView(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String title,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) EventType type,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) LocalDate eventDate,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) DatePrecision precision,
+        LocalDate eventDateEnd,
+        String description,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) Long version,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID createdBy,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) LocalDateTime createdAt,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID updatedBy,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) LocalDateTime updatedAt,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) List<PersonView> persons,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) List<DocumentRef> documents
+) {
+    /** Summarised person — exposes only id, firstName, and lastName. Mirrors GeschichteView.PersonView. */
+    public record PersonView(
+            @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+            String firstName,
+            String lastName
+    ) {}
+
+    /**
+     * Summarised linked document — id, title, and the eager {@code documentDate} only (no lazy
+     * sender/receiver hop, no person-name leak through the document side).
+     *
+     * <p>timeline-local by design; do not promote to {@code document/} — see #775 R7. Reusing
+     * {@code geschichte.journeyitem.DocumentSummary} would force a cross-domain import of a
+     * package-private mapper plus duplicated name-assembly logic; a 3-field local record is the
+     * lower-coupling choice.
+     */
+    public record DocumentRef(
+            @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+            @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String title,
+            LocalDate documentDate
+    ) {}
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineFilter.java

@@ -0,0 +1,16 @@
+package org.raddatz.familienarchiv.timeline;
+
+import java.util.UUID;
+
+/**
+ * Immutable filter bag for {@link TimelineService#assemble(TimelineFilter)}.
+ * All fields are nullable — null means "no constraint on this dimension".
+ */
+public record TimelineFilter(
+        UUID personId,
+        Integer generation,
+        EventType type,
+        Integer fromYear,
+        Integer toYear
+) {
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineService.java

@@ -0,0 +1,268 @@
+package org.raddatz.familienarchiv.timeline;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import org.raddatz.familienarchiv.document.DatePrecision;
+import org.raddatz.familienarchiv.document.Document;
+import org.raddatz.familienarchiv.document.DocumentService;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.person.Person;
+import org.raddatz.familienarchiv.person.PersonService;
+
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.UUID;
+import java.util.stream.Collectors;
+
+/**
+ * Assembles the family timeline from three sources — curated {@link TimelineEvent} rows,
+ * derived person life-events, and archive letters — into a year-bucketed {@link TimelineDTO}.
+ *
+ * <p>Cross-domain data is reached exclusively through domain services (PersonService,
+ * DocumentService). The only repository injected directly is {@link TimelineEventRepository}
+ * (same domain — constitution §1.3).
+ */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class TimelineService {
+
+    /** Primary: precision rank descending (DAY first). Secondary: date ascending. Tertiary: title. Final: id. */
+    static final Comparator<TimelineEntryDTO> WITHIN_BAND_ORDER =
+            Comparator.comparingInt((TimelineEntryDTO e) -> precisionRank(e.precision())).reversed()
+                    .thenComparing(e -> e.eventDate() != null ? e.eventDate() : java.time.LocalDate.MAX)
+                    .thenComparing(e -> e.title() != null ? e.title() : "")
+                    .thenComparing(e -> {
+                        if (e.eventId() != null) return e.eventId().toString();
+                        if (e.documentId() != null) return e.documentId().toString();
+                        return "";
+                    });
+
+    private final TimelineEventRepository eventRepository;
+    private final TimelineEventService timelineEventService;
+    private final DocumentService documentService;
+    private final PersonService personService;
+
+    /**
+     * Assembles the timeline for the given filter. All filters are ANDed.
+     * Throws {@link DomainException} (bad request) when fromYear &gt; toYear.
+     * Throws {@link DomainException} (not found) when personId refers to an unknown person.
+     *
+     * <p>{@code @Transactional(readOnly=true)} is required here — unlike simple scalar reads,
+     * this method accesses lazy collections ({@link TimelineEvent#getPersons()},
+     * {@link org.raddatz.familienarchiv.document.Document#getReceivers()}) after the
+     * repository sub-transaction closes. Without this annotation those accesses throw
+     * {@link org.hibernate.LazyInitializationException} in production (constitution §1.6).
+     */
+    @Transactional(readOnly = true)
+    public TimelineDTO assemble(TimelineFilter filter) {
+        if (filter.fromYear() != null && filter.toYear() != null
+                && filter.fromYear() > filter.toYear()) {
+            throw DomainException.badRequest(ErrorCode.VALIDATION_ERROR,
+                    "toYear must not be before fromYear");
+        }
+
+        // Resolve generation person IDs once — used across all three layers
+        Set<UUID> genPersonIds = resolveGenerationPersonIds(filter.generation());
+
+        // ── curated events ───────────────────────────────────────────────────
+        List<TimelineEntryDTO> entries = new ArrayList<>();
+        for (TimelineEvent ev : eventRepository.findAll()) {
+            if (!passesTypeFilter(ev.getType(), filter.type())) continue;
+            if (!passesPersonFilter(ev.getPersons(), filter.personId())) continue;
+            if (!passesGenerationFilter(ev.getPersons(), genPersonIds)) continue;
+            if (!passesYearFilter(ev.getEventDate(), ev.getPrecision(), filter)) continue;
+            entries.add(mapEvent(ev));
+        }
+
+        // ── derived events ───────────────────────────────────────────────────
+        for (TimelineEntryDTO derived : timelineEventService.assembleDerivedEvents()) {
+            if (!passesTypeFilter(derived.type(), filter.type())) continue;
+            if (!passesDerivedPersonFilter(derived.linkedPersonIds(), filter.personId())) continue;
+            if (!passesDerivedGenerationFilter(derived.linkedPersonIds(), genPersonIds)) continue;
+            if (!passesYearFilter(derived.eventDate(), derived.precision(), filter)) continue;
+            entries.add(derived);
+        }
+
+        // ── letters ─────────────────────────────────────────────────────────
+        List<Document> docs = fetchDocuments(filter.personId());
+        for (Document doc : docs) {
+            if (!passesLetterGenerationFilter(doc, genPersonIds)) continue;
+            if (!passesYearFilter(doc.getDocumentDate(), doc.getMetaDatePrecision(), filter)) continue;
+            entries.add(mapDocument(doc));
+        }
+
+        return bucket(entries);
+    }
+
+    // ─── Bucketing ───────────────────────────────────────────────────────────
+
+    Map<Integer, List<TimelineEntryDTO>> bucketByYear(List<TimelineEntryDTO> entries) {
+        Map<Integer, List<TimelineEntryDTO>> map = new TreeMap<>();
+        for (TimelineEntryDTO e : entries) {
+            if (e.eventDate() == null || e.precision() == DatePrecision.UNKNOWN) continue;
+            map.computeIfAbsent(e.eventDate().getYear(), k -> new ArrayList<>()).add(e);
+        }
+        return map;
+    }
+
+    private TimelineDTO bucket(List<TimelineEntryDTO> entries) {
+        List<TimelineEntryDTO> undated = entries.stream()
+                .filter(e -> e.eventDate() == null || e.precision() == DatePrecision.UNKNOWN)
+                .sorted(WITHIN_BAND_ORDER)
+                .toList();
+
+        Map<Integer, List<TimelineEntryDTO>> byYear = bucketByYear(entries);
+        List<TimelineYearDTO> years = byYear.entrySet().stream()
+                .map(e -> new TimelineYearDTO(e.getKey(),
+                        e.getValue().stream().sorted(WITHIN_BAND_ORDER).toList()))
+                .toList();
+
+        return new TimelineDTO(years, undated);
+    }
+
+    // ─── Document fetch (global vs personId path) ────────────────────────────
+
+    private List<Document> fetchDocuments(UUID personId) {
+        if (personId == null) {
+            return documentService.getAllForTimeline();
+        }
+        // personId path: validate existence, then union sender+receiver (dedup by id)
+        personService.getById(personId);
+        Map<UUID, Document> seen = new LinkedHashMap<>();
+        for (Document d : documentService.getDocumentsBySender(personId)) seen.put(d.getId(), d);
+        for (Document d : documentService.getDocumentsByReceiver(personId)) seen.putIfAbsent(d.getId(), d);
+        return new ArrayList<>(seen.values());
+    }
+
+    // ─── Filter predicates ───────────────────────────────────────────────────
+
+    private boolean passesTypeFilter(EventType entryType, EventType filterType) {
+        return filterType == null || filterType == entryType;
+    }
+
+    private boolean passesYearFilter(java.time.LocalDate date, DatePrecision precision, TimelineFilter filter) {
+        if (date == null || precision == DatePrecision.UNKNOWN) return true; // undated → always passes
+        int year = date.getYear();
+        if (filter.fromYear() != null && year < filter.fromYear()) return false;
+        if (filter.toYear() != null && year > filter.toYear()) return false;
+        return true;
+    }
+
+    private boolean passesPersonFilter(Set<Person> persons, UUID personId) {
+        if (personId == null) return true;
+        return persons != null && persons.stream().anyMatch(p -> personId.equals(p.getId()));
+    }
+
+    private boolean passesDerivedPersonFilter(List<UUID> linkedIds, UUID personId) {
+        if (personId == null) return true;
+        return linkedIds != null && linkedIds.contains(personId);
+    }
+
+    private Set<UUID> resolveGenerationPersonIds(Integer generation) {
+        if (generation == null) return null;
+        return personService.getPersonsByGeneration(generation).stream()
+                .map(Person::getId)
+                .collect(Collectors.toSet());
+    }
+
+    private boolean passesGenerationFilter(Set<Person> persons, Set<UUID> genPersonIds) {
+        if (genPersonIds == null) return true;
+        if (persons == null || persons.isEmpty()) return false;
+        return persons.stream().anyMatch(p -> genPersonIds.contains(p.getId()));
+    }
+
+    private boolean passesDerivedGenerationFilter(List<UUID> linkedIds, Set<UUID> genPersonIds) {
+        if (genPersonIds == null) return true;
+        if (linkedIds == null || linkedIds.isEmpty()) return false;
+        return linkedIds.stream().anyMatch(genPersonIds::contains);
+    }
+
+    private boolean passesLetterGenerationFilter(Document doc, Set<UUID> genPersonIds) {
+        if (genPersonIds == null) return true;
+        Person sender = doc.getSender();
+        if (sender != null && genPersonIds.contains(sender.getId())) return true;
+        Set<Person> receivers = doc.getReceivers();
+        if (receivers != null) {
+            return receivers.stream().anyMatch(r -> genPersonIds.contains(r.getId()));
+        }
+        return false;
+    }
+
+    // ─── Mapping ─────────────────────────────────────────────────────────────
+
+    private TimelineEntryDTO mapEvent(TimelineEvent ev) {
+        List<UUID> personIds = ev.getPersons() == null ? List.of()
+                : ev.getPersons().stream().map(Person::getId).toList();
+        return new TimelineEntryDTO(
+                Kind.EVENT,
+                ev.getPrecision(),
+                false,
+                "",
+                "",
+                ev.getEventDate(),
+                ev.getEventDateEnd(),
+                ev.getTitle(),
+                ev.getType(),
+                ev.getId(),
+                null,
+                personIds,
+                null
+        );
+    }
+
+    private TimelineEntryDTO mapDocument(Document doc) {
+        return new TimelineEntryDTO(
+                Kind.LETTER,
+                doc.getMetaDatePrecision(),
+                false,
+                resolveSenderName(doc),
+                resolveReceiverName(doc),
+                doc.getDocumentDate(),
+                null,
+                doc.getTitle(),
+                null,
+                null,
+                doc.getId(),
+                List.of(),
+                null
+        );
+    }
+
+    private String resolveSenderName(Document doc) {
+        if (doc.getSender() != null) return doc.getSender().getDisplayName();
+        String text = doc.getSenderText();
+        return (text != null && !text.isBlank()) ? text : "";
+    }
+
+    private String resolveReceiverName(Document doc) {
+        Set<Person> receivers = doc.getReceivers();
+        if (receivers != null && !receivers.isEmpty()) {
+            return receivers.stream().findFirst().map(Person::getDisplayName).orElse("");
+        }
+        String text = doc.getReceiverText();
+        return (text != null && !text.isBlank()) ? text : "";
+    }
+
+    private static int precisionRank(DatePrecision precision) {
+        if (precision == null) return 0;
+        return switch (precision) {
+            case DAY -> 5;
+            case MONTH -> 4;
+            case SEASON -> 3;
+            case YEAR -> 2;
+            case APPROX -> 1;
+            default -> 0;
+        };
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineYearDTO.java

@@ -0,0 +1,12 @@
+package org.raddatz.familienarchiv.timeline;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.util.List;
+
+/** One year's worth of timeline entries, sorted by {@link TimelineService#WITHIN_BAND_ORDER}. */
+public record TimelineYearDTO(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) int year,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) List<TimelineEntryDTO> entries
+) {
+}

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

@@ -0,0 +1,73 @@
+-- Production pre-requisite — run BEFORE applying this migration:
+--   docker exec familienarchiv-db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
+--     -c "SELECT COUNT(DISTINCT (geschichte_id, document_id)) FROM geschichten_documents;"'
+--   docker exec familienarchiv-db sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" \
+--     --table=geschichten_documents \
+--     -f /tmp/pre_v72_backup_'"$(date +%Y%m%d)"'.sql'
+-- Take the dump even if geschichten_documents is empty — it captures the table DEFINITION
+-- for emergency reconstruction. The DROP TABLE is the only irreversible step; the
+-- INSERT...SELECT is a no-op when there is no data. No DDL rollback path exists after commit.
+--
+-- REVERSE PROCEDURE (if V72 must be rolled back): restore the pre-V72 dump, then re-derive
+-- the junction from the new table:
+--   INSERT INTO geschichten_documents (geschichte_id, document_id)
+--     SELECT geschichte_id, document_id FROM journey_items WHERE document_id IS NOT NULL;
+-- Note: the reconstructed junction FK is ON DELETE CASCADE per the original V58
+-- (NOT the new SET NULL of journey_items). Domain FKs target app_users (post-V60) —
+-- do NOT hand-type V58's verbatim "REFERENCES users" DDL nor copy journey_items' SET NULL
+-- into the reconstructed junction.
+--
+-- ASSUMPTION AS-001: The old geschichten_documents was an unordered Set — no curator order
+-- existed. Ordering by meta_date is a plausible default a Lesereise lets curators
+-- re-sequence. This is not a requirement; it is the best available approximation.
+--
+-- ASSUMPTION AS-002: Existing published Geschichten (STORYs) render the related-letters block;
+-- this block visibly degrades to generic links (loss of per-document title AND date) for ALL
+-- current readers during the stub window. Accepted because the reader follow-on is the
+-- next-priority blocking dependency.
+
+-- Step 1: Add type discriminator column to geschichten
+ALTER TABLE geschichten
+    ADD COLUMN type VARCHAR(50) DEFAULT 'STORY' NOT NULL;
+
+-- Step 2: Create journey_items table
+CREATE TABLE journey_items (
+    id            UUID        NOT NULL DEFAULT gen_random_uuid(),
+    geschichte_id UUID        NOT NULL,
+    position      INT         NOT NULL,
+    document_id   UUID,
+    note          TEXT,
+    CONSTRAINT pk_journey_items PRIMARY KEY (id),
+    CONSTRAINT fk_journey_items_geschichte
+        FOREIGN KEY (geschichte_id) REFERENCES geschichten(id) ON DELETE CASCADE,
+    CONSTRAINT fk_journey_items_document
+        FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE SET NULL,
+    CONSTRAINT chk_journey_item_not_empty
+        CHECK (document_id IS NOT NULL OR note IS NOT NULL)
+);
+
+-- Step 3: Index for ordered retrieval by geschichte + position
+CREATE INDEX idx_journey_items_geschichte_position
+    ON journey_items (geschichte_id, position ASC);
+
+-- Step 4: Migrate geschichten_documents → journey_items
+-- Positions are multiples of 1000 (headroom for drag-reorder).
+-- Ordered by meta_date ASC NULLS LAST, then documents.id ASC as deterministic tiebreaker.
+-- SELECT DISTINCT guards against duplicate junction rows producing duplicate journey items.
+INSERT INTO journey_items (id, geschichte_id, position, document_id)
+SELECT
+    gen_random_uuid(),
+    gd.geschichte_id,
+    (ROW_NUMBER() OVER (
+        PARTITION BY gd.geschichte_id
+        ORDER BY d.meta_date ASC NULLS LAST, d.id ASC
+    ) * 1000)::INT AS position,
+    gd.document_id
+FROM (
+    SELECT DISTINCT geschichte_id, document_id
+    FROM geschichten_documents
+) gd
+LEFT JOIN documents d ON d.id = gd.document_id;
+
+-- Step 5: Drop the old junction table (irreversible — take the pg_dump first)
+DROP TABLE geschichten_documents;

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

@@ -0,0 +1,19 @@
+-- Adds the two constraints that V72 deferred:
+--   1. UNIQUE(geschichte_id, position) DEFERRABLE INITIALLY DEFERRED
+--      Allows mid-transaction position swaps during reorder (checked at COMMIT, not per-row).
+--      Requires transaction-level or session-level connection pooling (prod uses PgBouncer
+--      in transaction mode — correct today; a future switch to statement-level would silently
+--      break deferred checking at COMMIT).
+--   2. CHECK (position > 0) — defense against off-by-one in the append path.
+--
+-- MUST run in a single transaction; Flyway's default per-migration transaction satisfies this.
+-- Do NOT add executeInTransaction=false or any callback that splits this migration.
+
+ALTER TABLE journey_items
+    ADD CONSTRAINT uq_journey_items_geschichte_position
+        UNIQUE (geschichte_id, position)
+        DEFERRABLE INITIALLY DEFERRED;
+
+ALTER TABLE journey_items
+    ADD CONSTRAINT chk_journey_item_position
+        CHECK (position > 0);

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

@@ -0,0 +1,37 @@
+-- Two constraints the service-level checks need as atomic backstops:
+--
+-- 1. Partial unique index on (geschichte_id, document_id): the append dedup
+--    guard is a check-then-insert (existsByGeschichteIdAndDocumentId), so two
+--    concurrent appends of the same document can both pass the pre-check.
+--    The index rejects the second INSERT; JourneyItemService.append translates
+--    the DataIntegrityViolationException into the same 409
+--    JOURNEY_DOCUMENT_ALREADY_ADDED as the friendly pre-check.
+--    Partial (WHERE document_id IS NOT NULL) — note-only interludes must not collide.
+--
+-- 2. CHECK on note length: mirrors chk_text_length on transcription_blocks.
+--    2000 is the spec'd limit — JourneyItemService.MAX_NOTE_LENGTH, the frontend
+--    maxlength, and the i18n error message all agree (#793).
+--
+-- Defensive cleanup first: a database that served writes on the base branch
+-- (no dedup guard, MAX_NOTE_LENGTH = 5000) can hold rows that would make the
+-- DDL below fail mid-migration and boot-loop the backend on a failed Flyway
+-- row. Both statements are no-ops on a clean database.
+
+-- Keep the earliest-positioned row of each (geschichte, document) pair.
+DELETE FROM journey_items a
+    USING journey_items b
+    WHERE a.geschichte_id = b.geschichte_id
+      AND a.document_id = b.document_id
+      AND a.document_id IS NOT NULL
+      AND a.position > b.position;
+
+-- Clamp over-long notes written under the old 5000-char service limit.
+UPDATE journey_items SET note = left(note, 2000) WHERE length(note) > 2000;
+
+CREATE UNIQUE INDEX uq_journey_items_geschichte_document
+    ON journey_items (geschichte_id, document_id)
+    WHERE document_id IS NOT NULL;
+
+ALTER TABLE journey_items
+    ADD CONSTRAINT chk_journey_item_note_length
+        CHECK (note IS NULL OR length(note) <= 2000);

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

@@ -0,0 +1,16 @@
+-- JOURNEY intros travel the verbatim (unsanitized) write path and get the same
+-- three-layer bound as journey notes: frontend maxlength, the
+-- GeschichteService.MAX_INTRO_LENGTH check, and this CHECK as the atomic backstop.
+-- STORY bodies are sanitized Tiptap HTML and stay unbounded on purpose.
+--
+-- The title needs no CHECK here — VARCHAR(255) (V58) already bounds it at the
+-- DB layer; the service-level check exists to turn that 500 into a friendly 400.
+
+-- Defensive clamp first: intros written before this migration may exceed the
+-- cap. No-op on a clean database.
+UPDATE geschichten SET body = left(body, 4000)
+    WHERE type = 'JOURNEY' AND length(body) > 4000;
+
+ALTER TABLE geschichten
+    ADD CONSTRAINT chk_geschichte_journey_intro_length
+        CHECK (type <> 'JOURNEY' OR body IS NULL OR length(body) <= 4000);

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

@@ -0,0 +1,42 @@
+-- V76: persons.birth_year/death_year (integer) → birth_date/death_date (date)
+-- plus NOT NULL precision columns mirroring documents.meta_date_precision.
+-- Existing years are backfilled as YYYY-01-01 at YEAR precision (ADR-039).
+-- One-way migration: rollback is a targeted pg_restore -t persons from the
+-- pre-deploy backup (see docs/DEPLOYMENT.md).
+
+-- Pre-check (data quality gate — not a race guard): abort on corrupt year data
+-- before any DDL runs. Single-writer family archive, so no race window matters.
+DO $$ BEGIN
+  IF EXISTS (SELECT 1 FROM persons WHERE birth_year IS NOT NULL AND death_year IS NOT NULL AND birth_year > death_year)
+    THEN RAISE EXCEPTION 'V76 aborted: % persons have birth_year > death_year — fix data before migrating',
+      (SELECT COUNT(*) FROM persons WHERE birth_year IS NOT NULL AND death_year IS NOT NULL AND birth_year > death_year);
+  END IF;
+  IF EXISTS (SELECT 1 FROM persons WHERE birth_year = 0 OR death_year = 0)
+    THEN RAISE EXCEPTION 'V76 aborted: persons table contains birth_year=0 or death_year=0 rows — clean data before migrating';
+  END IF;
+END $$;
+
+ALTER TABLE persons ADD COLUMN birth_date date;
+ALTER TABLE persons ADD COLUMN birth_date_precision varchar(16) NOT NULL DEFAULT 'UNKNOWN';
+ALTER TABLE persons ADD COLUMN death_date date;
+ALTER TABLE persons ADD COLUMN death_date_precision varchar(16) NOT NULL DEFAULT 'UNKNOWN';
+
+UPDATE persons SET birth_date = make_date(birth_year, 1, 1), birth_date_precision = 'YEAR'
+    WHERE birth_year IS NOT NULL;
+UPDATE persons SET death_date = make_date(death_year, 1, 1), death_date_precision = 'YEAR'
+    WHERE death_year IS NOT NULL;
+
+-- Named constraints: readable Postgres error messages when violated.
+ALTER TABLE persons ADD CONSTRAINT chk_person_birth_before_death
+    CHECK (death_date IS NULL OR birth_date IS NULL OR birth_date <= death_date);
+ALTER TABLE persons ADD CONSTRAINT chk_person_birth_date_precision_coherence
+    CHECK ((birth_date IS NULL) = (birth_date_precision = 'UNKNOWN'));
+ALTER TABLE persons ADD CONSTRAINT chk_person_birth_date_precision_values
+    CHECK (birth_date_precision IN ('DAY', 'MONTH', 'SEASON', 'YEAR', 'RANGE', 'APPROX', 'UNKNOWN'));
+ALTER TABLE persons ADD CONSTRAINT chk_person_death_date_precision_coherence
+    CHECK ((death_date IS NULL) = (death_date_precision = 'UNKNOWN'));
+ALTER TABLE persons ADD CONSTRAINT chk_person_death_date_precision_values
+    CHECK (death_date_precision IN ('DAY', 'MONTH', 'SEASON', 'YEAR', 'RANGE', 'APPROX', 'UNKNOWN'));
+
+ALTER TABLE persons DROP COLUMN birth_year;
+ALTER TABLE persons DROP COLUMN death_year;

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

@@ -0,0 +1,64 @@
+-- V77: timeline domain foundation (Zeitstrahl) — curated timeline events.
+-- Forward-only, additive DDL. No rollback script: rollback requires manual DROP TABLE
+-- (timeline_event_documents, timeline_event_persons, then timeline_events). See ADR-040.
+--
+-- The date block (event_date / date_precision / event_date_end) mirrors documents' so events
+-- and letters share one rendering path. Two divergences from documents are INTENTIONAL and
+-- enforced here in Postgres (ADR-040):
+--   1. The RANGE rule is a strict biconditional (event_date_end non-null IFF RANGE), unlike
+--      documents' open-ended ranges — a curated event always has a known, closed end.
+--   2. date_precision <> 'UNKNOWN' — only OCR-inferred letters are ever undated; a curated
+--      event always has at least a year. SEASON and APPROX stay legal (Sommer/ca. 1914).
+
+CREATE TABLE timeline_events (
+    id             UUID         NOT NULL DEFAULT gen_random_uuid(),
+    title          VARCHAR(255) NOT NULL,
+    type           VARCHAR(16)  NOT NULL,
+    event_date     DATE         NOT NULL,
+    date_precision VARCHAR(16)  NOT NULL DEFAULT 'YEAR',
+    event_date_end DATE,
+    description    TEXT,
+    created_by     UUID         NOT NULL,
+    created_at     TIMESTAMP,
+    updated_by     UUID         NOT NULL,
+    updated_at     TIMESTAMP,
+    version        BIGINT,
+    CONSTRAINT pk_timeline_events PRIMARY KEY (id),
+    -- event_date_end is non-null IFF precision is RANGE (both directions).
+    CONSTRAINT chk_timeline_event_range
+        CHECK ((date_precision = 'RANGE') = (event_date_end IS NOT NULL)),
+    -- Curated events are never undated. Forbids exactly UNKNOWN — every other
+    -- DatePrecision value (DAY, MONTH, SEASON, YEAR, RANGE, APPROX) stays legal.
+    CONSTRAINT chk_timeline_event_precision
+        CHECK (date_precision <> 'UNKNOWN')
+);
+
+-- Join table: events ↔ persons involved.
+CREATE TABLE timeline_event_persons (
+    timeline_event_id UUID NOT NULL,
+    person_id         UUID NOT NULL,
+    CONSTRAINT pk_timeline_event_persons PRIMARY KEY (timeline_event_id, person_id),
+    CONSTRAINT fk_tep_event
+        FOREIGN KEY (timeline_event_id) REFERENCES timeline_events(id) ON DELETE CASCADE,
+    CONSTRAINT fk_tep_person
+        FOREIGN KEY (person_id) REFERENCES persons(id) ON DELETE CASCADE
+);
+
+-- Join table: events ↔ supporting letters.
+CREATE TABLE timeline_event_documents (
+    timeline_event_id UUID NOT NULL,
+    document_id       UUID NOT NULL,
+    CONSTRAINT pk_timeline_event_documents PRIMARY KEY (timeline_event_id, document_id),
+    CONSTRAINT fk_ted_event
+        FOREIGN KEY (timeline_event_id) REFERENCES timeline_events(id) ON DELETE CASCADE,
+    CONSTRAINT fk_ted_document
+        FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE
+);
+
+-- Indexes added up-front (avoid the V62 FK-index retrofit debt): the two query columns plus
+-- the inverse-side FK columns. timeline_event_id needs no extra index on either join table —
+-- it is the leading column of the composite PK, so the PK index already serves those lookups.
+CREATE INDEX idx_timeline_events_event_date ON timeline_events (event_date);
+CREATE INDEX idx_timeline_events_type ON timeline_events (type);
+CREATE INDEX idx_timeline_event_persons_person_id ON timeline_event_persons (person_id);
+CREATE INDEX idx_timeline_event_documents_document_id ON timeline_event_documents (document_id);

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

@@ -402,6 +402,7 @@ class DocumentControllerTest {
     @WithMockUser(authorities = "WRITE_ALL")
     void deleteDocument_returns204_whenHasWritePermission() throws Exception {
         UUID id = UUID.randomUUID();
+        when(userService.findByEmail(any())).thenReturn(AppUser.builder().id(UUID.randomUUID()).build());
         mockMvc.perform(org.springframework.test.web.servlet.request.MockMvcRequestBuilders
                         .delete("/api/documents/" + id).with(csrf()))
                 .andExpect(status().isNoContent());

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

@@ -131,6 +131,28 @@ class DocumentLazyLoadingTest {
                 .doesNotThrowAnyException();
     }
 
+    @Test
+    void searchDocuments_pureTextRelevance_doesNotThrowLazyInitializationException() {
+        // q + default sort + no other filters → the relevance fast path
+        // (relevanceSortedPageFromSql), which loads documents by id outside any
+        // transaction and must still deliver an initialized tags collection.
+        Person sender = savedPerson("Hans", "FtSender");
+        Tag tag = savedTag("FtTag");
+        savedDocument("Brief von Walter", "ft_doc.pdf", sender, Set.of(), Set.of(tag));
+
+        SearchFilters textOnly = new SearchFilters(
+                "Walter", null, null, null, null, null, null, null, null, false);
+
+        DocumentSearchResult result = documentService.searchDocuments(
+                textOnly, null, "DESC", PageRequest.of(0, 10));
+
+        assertThat(result.totalElements()).isEqualTo(1);
+        assertThatCode(() ->
+                result.items().forEach(i -> i.tags().size()))
+                .doesNotThrowAnyException();
+        assertThat(result.items().getFirst().tags()).extracting(Tag::getName).containsExactly("FtTag");
+    }
+
     @Test
     void searchDocuments_senderSort_doesNotThrowLazyInitializationException() {
         Person sender = savedPerson("Hans", "SsSender");

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

@@ -81,7 +81,7 @@ class DocumentServiceSortTest {
         UUID id1 = UUID.randomUUID();
         List<Object[]> ftsRows = ftsRows(id1, 0.5d, 1L);
         when(documentRepository.findFtsPageRaw(anyString(), anyInt(), anyInt())).thenReturn(ftsRows);
-        when(documentRepository.findAllById(any()))
+        when(documentRepository.findByIdIn(any()))
                 .thenReturn(List.of(doc(id1)));
 
         documentService.searchDocuments(
@@ -101,7 +101,7 @@ class DocumentServiceSortTest {
         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
+        when(documentRepository.findByIdIn(any())).thenReturn(List.of(doc(id2), doc(id1))); // unordered from JPA
 
         DocumentSearchResult result = documentService.searchDocuments(
                 new SearchFilters("Brief", null, null, null, null, null, null, null, null, false),
@@ -119,7 +119,7 @@ class DocumentServiceSortTest {
         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)));
+        when(documentRepository.findByIdIn(any())).thenReturn(List.of(doc(id2), doc(id1)));
 
         DocumentSearchResult result = documentService.searchDocuments(
                 new SearchFilters("Brief", null, null, null, null, null, null, null, null, false),
@@ -153,7 +153,7 @@ class DocumentServiceSortTest {
         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)));
+        when(documentRepository.findByIdIn(any())).thenReturn(List.of(doc(uuidId)));
 
         DocumentSearchResult result = documentService.searchDocuments(
                 new SearchFilters("Brief", null, null, null, null, null, null, null, null, false),

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

@@ -30,6 +30,7 @@ import org.raddatz.familienarchiv.document.DocumentRepository;
 import org.raddatz.familienarchiv.filestorage.FileService;
 import org.raddatz.familienarchiv.tag.TagService;
 import org.raddatz.familienarchiv.person.PersonService;
+import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.PageImpl;
 import org.springframework.data.domain.PageRequest;
@@ -75,6 +76,7 @@ class DocumentServiceTest {
     @Mock AuditLogQueryService auditLogQueryService;
     @Mock TranscriptionBlockQueryService transcriptionBlockQueryService;
     @Mock ThumbnailAsyncRunner thumbnailAsyncRunner;
+    @Mock ApplicationEventPublisher eventPublisher;
     // Real factory (pure, dependency-free) so save-time title-regeneration tests exercise the
     // shared composition rather than a stub — the #726 single source of truth.
     @Spy DocumentTitleFactory documentTitleFactory = new DocumentTitleFactory();
@@ -87,7 +89,7 @@ class DocumentServiceTest {
         UUID id = UUID.randomUUID();
         when(documentRepository.existsById(id)).thenReturn(true);
 
-        documentService.deleteDocument(id);
+        documentService.deleteDocument(id, UUID.randomUUID());
 
         verify(documentRepository).deleteById(id);
     }
@@ -97,7 +99,7 @@ class DocumentServiceTest {
         UUID id = UUID.randomUUID();
         when(documentRepository.existsById(id)).thenReturn(false);
 
-        assertThatThrownBy(() -> documentService.deleteDocument(id))
+        assertThatThrownBy(() -> documentService.deleteDocument(id, UUID.randomUUID()))
                 .isInstanceOf(DomainException.class)
                 .hasMessageContaining(id.toString());
         verify(documentRepository, never()).deleteById(any());
@@ -2166,7 +2168,7 @@ class DocumentServiceTest {
         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.findByIdIn(any())).thenReturn(List.of(doc));
         when(documentRepository.findEnrichmentData(any(), eq("Brief"))).thenReturn(rows);
 
         DocumentSearchResult result = documentService.searchDocuments(
@@ -2202,7 +2204,7 @@ class DocumentServiceTest {
         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.findByIdIn(any())).thenReturn(List.of(doc));
         when(documentRepository.findEnrichmentData(any(), eq("Brief"))).thenReturn(rows);
 
         DocumentSearchResult result = documentService.searchDocuments(
@@ -2941,4 +2943,17 @@ class DocumentServiceTest {
         assertThat(result.buckets()).isEmpty();
         verify(documentRepository, org.mockito.Mockito.never()).findAll(any(Specification.class));
     }
+
+    // --- getAllForTimeline ---
+
+    @Test
+    void getAllForTimeline_delegates_bulk_fetch_to_repository() {
+        Document doc = Document.builder().id(UUID.randomUUID()).title("Brief").build();
+        when(documentRepository.findAllForTimeline()).thenReturn(List.of(doc));
+
+        List<Document> result = documentService.getAllForTimeline();
+
+        assertThat(result).containsExactly(doc);
+        verify(documentRepository).findAllForTimeline();
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/exception/GlobalExceptionHandlerTest.java

@@ -14,6 +14,9 @@ import org.slf4j.LoggerFactory;
 import org.springframework.dao.DataIntegrityViolationException;
 import org.springframework.dao.IncorrectResultSizeDataAccessException;
 import org.springframework.http.ResponseEntity;
+import org.springframework.orm.ObjectOptimisticLockingFailureException;
+
+import java.util.UUID;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.mockStatic;
@@ -103,6 +106,49 @@ class GlobalExceptionHandlerTest {
                 });
     }
 
+    @Test
+    void handleOptimisticLock_returns409_genericConflict_noSentry_noLeak() {
+        // CWE-209 regression: an optimistic-lock failure escaping a service catch must become a
+        // generic 409, never a 500 + Sentry + Hibernate internals. The generic CONFLICT code keeps
+        // it entity-agnostic — NOT TIMELINE_EVENT_CONFLICT, or every future entity's conflict is
+        // mislabeled a timeline one.
+        UUID entityId = UUID.randomUUID();
+        ObjectOptimisticLockingFailureException ex =
+                new ObjectOptimisticLockingFailureException("com.example.SomeEntity", entityId);
+
+        Logger handlerLogger = (Logger) LoggerFactory.getLogger(GlobalExceptionHandler.class);
+        ListAppender<ILoggingEvent> appender = new ListAppender<>();
+        appender.start();
+        handlerLogger.addAppender(appender);
+
+        try (MockedStatic<Sentry> sentryMock = mockStatic(Sentry.class)) {
+            ResponseEntity<GlobalExceptionHandler.ErrorResponse> response = handler.handleOptimisticLock(ex);
+
+            assertThat(response.getStatusCode().value()).isEqualTo(409);
+            assertThat(response.getBody()).isNotNull();
+            assertThat(response.getBody().code()).isEqualTo(ErrorCode.CONFLICT);
+            // Body echoes no persistent-class name, no entity id, no version (enumeration aids).
+            assertThat(response.getBody().message())
+                    .doesNotContain("SomeEntity")
+                    .doesNotContain(entityId.toString());
+
+            // A conflict is not a system fault — no fabricated Sentry alert.
+            sentryMock.verifyNoInteractions();
+        } finally {
+            handlerLogger.detachAppender(appender);
+        }
+
+        assertThat(appender.list)
+                .as("WARN names the persistent class for debuggability")
+                .anySatisfy(e -> {
+                    assertThat(e.getLevel()).isEqualTo(Level.WARN);
+                    assertThat(e.getFormattedMessage()).contains("com.example.SomeEntity");
+                });
+        assertThat(appender.list)
+                .as("but never the entity id (would leak via getMessage())")
+                .noneSatisfy(e -> assertThat(e.getFormattedMessage()).contains(entityId.toString()));
+    }
+
     @Test
     void handleDataIntegrityViolation_logsConstraintName_butNotTheSql() {
         // Debuggability (DevOps): the WARN must name *which* constraint fired so an

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

@@ -0,0 +1,66 @@
+package org.raddatz.familienarchiv.geschichte;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.dao.DataIntegrityViolationException;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import software.amazon.awssdk.services.s3.S3Client;
+
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * Raw-SQL constraint tests for geschichten — deliberately NOT @Transactional at
+ * class level (see JourneyItemConstraintsTest for the rationale).
+ *
+ * The V75 CHECK is the atomic backstop for GeschichteService.MAX_INTRO_LENGTH on
+ * the verbatim JOURNEY intro write path. STORY bodies are intentionally exempt.
+ */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
+@ActiveProfiles("test")
+@Import(PostgresContainerConfig.class)
+class GeschichteConstraintsTest {
+
+    @MockitoBean
+    S3Client s3Client;
+
+    @Autowired JdbcTemplate jdbcTemplate;
+
+    private UUID insertGeschichte(String type, String body) {
+        UUID id = UUID.randomUUID();
+        jdbcTemplate.update(
+                "INSERT INTO geschichten (id, title, body, status, type, created_at, updated_at) "
+                        + "VALUES (?, ?, ?, 'DRAFT', ?, now(), now())",
+                id, "Constraints-Test", body, type);
+        return id;
+    }
+
+    @Test
+    void journey_intro_check_rejects_4001_chars() {
+        assertThatThrownBy(() -> insertGeschichte("JOURNEY", "x".repeat(4001)))
+                .isInstanceOf(DataIntegrityViolationException.class);
+    }
+
+    @Test
+    void journey_intro_check_accepts_exactly_4000_chars() {
+        UUID id = insertGeschichte("JOURNEY", "x".repeat(4000));
+        Integer count = jdbcTemplate.queryForObject(
+                "SELECT COUNT(*) FROM geschichten WHERE id = ?", Integer.class, id);
+        assertThat(count).isEqualTo(1);
+    }
+
+    @Test
+    void story_bodies_are_not_constrained_by_the_intro_check() {
+        UUID id = insertGeschichte("STORY", "<p>" + "x".repeat(4001) + "</p>");
+        Integer count = jdbcTemplate.queryForObject(
+                "SELECT COUNT(*) FROM geschichten WHERE id = ?", Integer.class, id);
+        assertThat(count).isEqualTo(1);
+    }
+}

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

@@ -2,15 +2,13 @@ package org.raddatz.familienarchiv.geschichte;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.junit.jupiter.api.Test;
-import org.raddatz.familienarchiv.security.SecurityConfig;
-import org.raddatz.familienarchiv.geschichte.GeschichteUpdateDTO;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
-import org.raddatz.familienarchiv.geschichte.Geschichte;
-import org.raddatz.familienarchiv.geschichte.GeschichteStatus;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemService;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemView;
+import org.raddatz.familienarchiv.security.SecurityConfig;
 import org.raddatz.familienarchiv.security.PermissionAspect;
 import org.raddatz.familienarchiv.user.CustomUserDetailsService;
-import org.raddatz.familienarchiv.geschichte.GeschichteService;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
 import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
@@ -21,22 +19,25 @@ import org.springframework.test.context.bean.override.mockito.MockitoBean;
 import org.springframework.test.web.servlet.MockMvc;
 
 import java.time.LocalDateTime;
+import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.List;
 import java.util.UUID;
 
+import static org.hamcrest.CoreMatchers.nullValue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyInt;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
+import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.patch;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
-import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf;
 
 @WebMvcTest(GeschichteController.class)
 @Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
@@ -47,11 +48,9 @@ class GeschichteControllerTest {
 
     private final ObjectMapper objectMapper = new ObjectMapper();
 
-    @MockitoBean
-    GeschichteService geschichteService;
-
-    @MockitoBean
-    CustomUserDetailsService customUserDetailsService;
+    @MockitoBean GeschichteService geschichteService;
+    @MockitoBean JourneyItemService journeyItemService;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
 
     // ─── GET /api/geschichten ────────────────────────────────────────────────
 
@@ -65,7 +64,7 @@ class GeschichteControllerTest {
     @WithMockUser(authorities = "READ_ALL")
     void list_returns200_forReader() throws Exception {
         when(geschichteService.list(any(), any(), any(), anyInt()))
-                .thenReturn(List.of(published(UUID.randomUUID(), "Story A")));
+                .thenReturn(List.of(summaryStub("Story A")));
 
         mockMvc.perform(get("/api/geschichten"))
                 .andExpect(status().isOk())
@@ -101,13 +100,50 @@ class GeschichteControllerTest {
         verify(geschichteService).list(any(), eq(List.of(a, b)), any(), anyInt());
     }
 
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void list_passesDocumentIdFilterToService() throws Exception {
+        UUID documentId = UUID.randomUUID();
+        when(geschichteService.list(any(), any(), eq(documentId), anyInt()))
+                .thenReturn(List.of());
+
+        mockMvc.perform(get("/api/geschichten").param("documentId", documentId.toString()))
+                .andExpect(status().isOk());
+
+        verify(geschichteService).list(any(), any(), eq(documentId), anyInt());
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void list_passesLimitToService() throws Exception {
+        when(geschichteService.list(any(), any(), any(), eq(5)))
+                .thenReturn(List.of());
+
+        mockMvc.perform(get("/api/geschichten").param("limit", "5"))
+                .andExpect(status().isOk());
+
+        verify(geschichteService).list(any(), any(), any(), eq(5));
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void list_passesStatusFilterToService() throws Exception {
+        when(geschichteService.list(eq(GeschichteStatus.PUBLISHED), any(), any(), anyInt()))
+                .thenReturn(List.of());
+
+        mockMvc.perform(get("/api/geschichten").param("status", "PUBLISHED"))
+                .andExpect(status().isOk());
+
+        verify(geschichteService).list(eq(GeschichteStatus.PUBLISHED), any(), any(), anyInt());
+    }
+
     // ─── GET /api/geschichten/{id} ───────────────────────────────────────────
 
     @Test
     @WithMockUser(authorities = "READ_ALL")
     void getById_returns200_whenFound() throws Exception {
         UUID id = UUID.randomUUID();
-        when(geschichteService.getById(id)).thenReturn(published(id, "Hello"));
+        when(geschichteService.getView(id)).thenReturn(viewStub(id, "Hello"));
 
         mockMvc.perform(get("/api/geschichten/{id}", id))
                 .andExpect(status().isOk())
@@ -119,7 +155,7 @@ class GeschichteControllerTest {
     @WithMockUser(authorities = "READ_ALL")
     void getById_returns404_whenServiceThrowsNotFound() throws Exception {
         UUID id = UUID.randomUUID();
-        when(geschichteService.getById(id))
+        when(geschichteService.getView(id))
                 .thenThrow(DomainException.notFound(ErrorCode.GESCHICHTE_NOT_FOUND, "x"));
 
         mockMvc.perform(get("/api/geschichten/{id}", id))
@@ -151,7 +187,7 @@ class GeschichteControllerTest {
     void create_returns201_withBlogWrite() throws Exception {
         UUID id = UUID.randomUUID();
         when(geschichteService.create(any(GeschichteUpdateDTO.class)))
-                .thenReturn(draft(id, "New"));
+                .thenReturn(viewStub(id, "New", GeschichteStatus.DRAFT));
 
         GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
         dto.setTitle("New");
@@ -179,7 +215,7 @@ class GeschichteControllerTest {
     void update_returns200_withBlogWrite() throws Exception {
         UUID id = UUID.randomUUID();
         when(geschichteService.update(eq(id), any(GeschichteUpdateDTO.class)))
-                .thenReturn(published(id, "Updated"));
+                .thenReturn(viewStub(id, "Updated", GeschichteStatus.PUBLISHED));
 
         mockMvc.perform(patch("/api/geschichten/{id}", id).with(csrf())
                         .contentType(MediaType.APPLICATION_JSON)
@@ -208,31 +244,202 @@ class GeschichteControllerTest {
         verify(geschichteService).delete(id);
     }
 
+    // ─── POST /api/geschichten/{id}/items ────────────────────────────────────
+
+    @Test
+    void appendItem_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/geschichten/{id}/items", UUID.randomUUID()).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"note\":\"x\"}"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void appendItem_returns403_whenLackingBlogWrite() throws Exception {
+        mockMvc.perform(post("/api/geschichten/{id}/items", UUID.randomUUID()).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"note\":\"x\"}"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "BLOG_WRITE")
+    void appendItem_returns201_withBlogWrite() throws Exception {
+        UUID id = UUID.randomUUID();
+        UUID itemId = UUID.randomUUID();
+        when(journeyItemService.append(eq(id), any())).thenReturn(itemViewStub(itemId, 10, "Note"));
+
+        mockMvc.perform(post("/api/geschichten/{id}/items", id).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"note\":\"Note\"}"))
+                .andExpect(status().isCreated())
+                .andExpect(jsonPath("$.id").value(itemId.toString()))
+                .andExpect(jsonPath("$.position").value(10));
+    }
+
+    // ─── PATCH /api/geschichten/{id}/items/{itemId} ──────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void updateItemNote_returns403_whenLackingBlogWrite() throws Exception {
+        mockMvc.perform(patch("/api/geschichten/{id}/items/{itemId}",
+                        UUID.randomUUID(), UUID.randomUUID()).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"note\":\"x\"}"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "BLOG_WRITE")
+    void updateItemNote_returns200_withBlogWrite() throws Exception {
+        UUID id = UUID.randomUUID();
+        UUID itemId = UUID.randomUUID();
+        when(journeyItemService.updateNote(eq(id), eq(itemId), any()))
+                .thenReturn(itemViewStub(itemId, 10, "Updated"));
+
+        mockMvc.perform(patch("/api/geschichten/{id}/items/{itemId}", id, itemId).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"note\":\"Updated\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.note").value("Updated"));
+    }
+
+    @Test
+    @WithMockUser(authorities = "BLOG_WRITE")
+    void updateItemNote_json_null_note_is_deserialized_as_empty_Optional() throws Exception {
+        UUID id = UUID.randomUUID();
+        UUID itemId = UUID.randomUUID();
+        when(journeyItemService.updateNote(eq(id), eq(itemId), any()))
+                .thenReturn(itemViewStub(itemId, 10, null));
+
+        // Raw JSON — local objectMapper lacks JsonNullableModule
+        mockMvc.perform(patch("/api/geschichten/{id}/items/{itemId}", id, itemId).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"note\": null}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.note").value(nullValue()));
+    }
+
+    @Test
+    @WithMockUser(authorities = "BLOG_WRITE")
+    void updateItemNote_returns404_whenItemNotFound() throws Exception {
+        UUID id = UUID.randomUUID();
+        UUID itemId = UUID.randomUUID();
+        when(journeyItemService.updateNote(eq(id), eq(itemId), any()))
+                .thenThrow(DomainException.notFound(ErrorCode.JOURNEY_ITEM_NOT_FOUND, "not found"));
+
+        mockMvc.perform(patch("/api/geschichten/{id}/items/{itemId}", id, itemId).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"note\":\"x\"}"))
+                .andExpect(status().isNotFound())
+                .andExpect(jsonPath("$.code").value("JOURNEY_ITEM_NOT_FOUND"));
+    }
+
+    // ─── DELETE /api/geschichten/{id}/items/{itemId} ─────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void deleteItem_returns403_whenLackingBlogWrite() throws Exception {
+        mockMvc.perform(delete("/api/geschichten/{id}/items/{itemId}",
+                        UUID.randomUUID(), UUID.randomUUID()).with(csrf()))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "BLOG_WRITE")
+    void deleteItem_returns204_withBlogWrite() throws Exception {
+        UUID id = UUID.randomUUID();
+        UUID itemId = UUID.randomUUID();
+
+        mockMvc.perform(delete("/api/geschichten/{id}/items/{itemId}", id, itemId).with(csrf()))
+                .andExpect(status().isNoContent());
+
+        verify(journeyItemService).delete(id, itemId);
+    }
+
+    @Test
+    @WithMockUser(authorities = "BLOG_WRITE")
+    void deleteItem_returns404_whenItemNotFound() throws Exception {
+        UUID id = UUID.randomUUID();
+        UUID itemId = UUID.randomUUID();
+        org.mockito.Mockito.doThrow(DomainException.notFound(ErrorCode.JOURNEY_ITEM_NOT_FOUND, "not found"))
+                .when(journeyItemService).delete(id, itemId);
+
+        mockMvc.perform(delete("/api/geschichten/{id}/items/{itemId}", id, itemId).with(csrf()))
+                .andExpect(status().isNotFound())
+                .andExpect(jsonPath("$.code").value("JOURNEY_ITEM_NOT_FOUND"));
+    }
+
+    // ─── PUT /api/geschichten/{id}/items/reorder ─────────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void reorderItems_returns403_whenLackingBlogWrite() throws Exception {
+        mockMvc.perform(put("/api/geschichten/{id}/items/reorder", UUID.randomUUID()).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"itemIds\":[]}"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "BLOG_WRITE")
+    void reorderItems_returns200_withBlogWrite() throws Exception {
+        UUID id = UUID.randomUUID();
+        UUID itemId = UUID.randomUUID();
+        when(journeyItemService.reorder(eq(id), any())).thenReturn(List.of(itemViewStub(itemId, 10, null)));
+
+        mockMvc.perform(put("/api/geschichten/{id}/items/reorder", id).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"itemIds\":[\"" + itemId + "\"]}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].id").value(itemId.toString()));
+    }
+
+    // ─── error mapping ───────────────────────────────────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "BLOG_WRITE")
+    void appendItem_returns409_on_position_conflict() throws Exception {
+        UUID id = UUID.randomUUID();
+        when(journeyItemService.append(eq(id), any()))
+                .thenThrow(DomainException.conflict(ErrorCode.JOURNEY_ITEM_POSITION_CONFLICT, "conflict"));
+
+        mockMvc.perform(post("/api/geschichten/{id}/items", id).with(csrf())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"note\":\"x\"}"))
+                .andExpect(status().isConflict())
+                .andExpect(jsonPath("$.code").value("JOURNEY_ITEM_POSITION_CONFLICT"));
+    }
+
     // ─── helpers ─────────────────────────────────────────────────────────────
 
-    private Geschichte published(UUID id, String title) {
-        return Geschichte.builder()
-                .id(id)
-                .title(title)
-                .body("<p>x</p>")
-                .status(GeschichteStatus.PUBLISHED)
-                .publishedAt(LocalDateTime.now())
-                .createdAt(LocalDateTime.now())
-                .updatedAt(LocalDateTime.now())
-                .persons(new HashSet<>())
-                .documents(new HashSet<>())
-                .build();
+    private JourneyItemView itemViewStub(UUID id, int position, String note) {
+        return new JourneyItemView(id, position, null, note);
     }
 
-    private Geschichte draft(UUID id, String title) {
-        return Geschichte.builder()
-                .id(id)
-                .title(title)
-                .status(GeschichteStatus.DRAFT)
-                .createdAt(LocalDateTime.now())
-                .updatedAt(LocalDateTime.now())
-                .persons(new HashSet<>())
-                .documents(new HashSet<>())
-                .build();
+    private GeschichteView viewStub(UUID id, String title) {
+        return viewStub(id, title, GeschichteStatus.PUBLISHED);
+    }
+
+    private GeschichteView viewStub(UUID id, String title, GeschichteStatus status) {
+        return new GeschichteView(id, title, "<p>x</p>",
+                status, GeschichteType.STORY,
+                null, new HashSet<>(), List.of(),
+                LocalDateTime.now(), LocalDateTime.now(), LocalDateTime.now());
+    }
+
+    /** Concrete implementation — Mockito interface mocks are not serialized reliably by Jackson. */
+    private GeschichteSummary summaryStub(String title) {
+        return new GeschichteSummary() {
+            public UUID getId() { return UUID.randomUUID(); }
+            public String getTitle() { return title; }
+            public GeschichteStatus getStatus() { return GeschichteStatus.PUBLISHED; }
+            public GeschichteType getType() { return GeschichteType.STORY; }
+            public AuthorSummary getAuthor() { return null; }
+            public LocalDateTime getPublishedAt() { return LocalDateTime.now(); }
+            public LocalDateTime getUpdatedAt() { return LocalDateTime.now(); }
+            public String getBody() { return null; }
+        };
     }
 }

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

@@ -0,0 +1,298 @@
+package org.raddatz.familienarchiv.geschichte;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItem;
+import org.raddatz.familienarchiv.user.AppUser;
+import org.raddatz.familienarchiv.user.AppUserRepository;
+import org.raddatz.familienarchiv.user.UserGroup;
+import org.raddatz.familienarchiv.user.UserGroupRepository;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.web.server.LocalServerPort;
+import org.springframework.context.annotation.Import;
+import org.springframework.http.HttpEntity;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpMethod;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.client.ClientHttpResponse;
+import org.springframework.http.client.JdkClientHttpRequestFactory;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.web.client.DefaultResponseErrorHandler;
+import org.springframework.web.client.RestTemplate;
+import software.amazon.awssdk.services.s3.S3Client;
+
+import java.io.IOException;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Verifies Geschichte HTTP behaviour end-to-end at the real servlet layer.
+ *
+ * <p>No {@code @Transactional} at class level — that would keep a session open and
+ * mask LazyInitializationException caused by open-in-view: false. Each test seeds data
+ * directly via repositories and relies on the service's own transaction boundaries.
+ */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@ActiveProfiles("test")
+@Import(PostgresContainerConfig.class)
+class GeschichteHttpTest {
+
+    @LocalServerPort int port;
+    @MockitoBean S3Client s3Client;
+
+    @Autowired GeschichteRepository geschichteRepository;
+    @Autowired AppUserRepository appUserRepository;
+    @Autowired UserGroupRepository userGroupRepository;
+    @Autowired PasswordEncoder passwordEncoder;
+
+    private RestTemplate http;
+    private String baseUrl;
+
+    private static final String WRITER_EMAIL = "geschichten-http-writer@test.de";
+    private static final String WRITER_PASSWORD = "pass!Geschichte1";
+
+    @BeforeEach
+    void setUp() {
+        http = noThrowRestTemplate();
+        baseUrl = "http://localhost:" + port;
+        geschichteRepository.deleteAll();
+        appUserRepository.findByEmail(WRITER_EMAIL).ifPresent(appUserRepository::delete);
+        appUserRepository.findByEmail(BLOG_WRITER_EMAIL).ifPresent(appUserRepository::delete);
+        userGroupRepository.findByName("HttpTest-BlogWriters").ifPresent(userGroupRepository::delete);
+        appUserRepository.save(AppUser.builder()
+                .email(WRITER_EMAIL)
+                .password(passwordEncoder.encode(WRITER_PASSWORD))
+                .build());
+    }
+
+    // ─── GET /api/geschichten ────────────────────────────────────────────────
+
+    @Test
+    void list_returns_200_and_empty_array_when_no_stories_exist() {
+        String session = loginAsWriter();
+        ResponseEntity<String> response = http.exchange(
+                baseUrl + "/api/geschichten", HttpMethod.GET,
+                new HttpEntity<>(sessionHeaders(session)), String.class);
+
+        assertThat(response.getStatusCode().value()).isEqualTo(200);
+        assertThat(response.getBody()).isEqualTo("[]");
+    }
+
+    @Test
+    void list_returns_200_and_does_not_500_when_stories_have_journey_items() {
+        // Seed a JOURNEY directly — items are LAZY; without @Transactional(readOnly=true) +
+        // Hibernate.initialize in getById() this would 500. list() uses a projection so it
+        // must also never touch items.
+        AppUser writer = appUserRepository.findByEmail(WRITER_EMAIL).orElseThrow();
+        Geschichte journey = Geschichte.builder()
+                .title("Reise durch die Briefe")
+                .status(GeschichteStatus.PUBLISHED)
+                .type(GeschichteType.JOURNEY)
+                .author(writer)
+                .publishedAt(LocalDateTime.now())
+                .items(new ArrayList<>())
+                .persons(new HashSet<>())
+                .build();
+        JourneyItem item = JourneyItem.builder()
+                .geschichte(journey)
+                .position(1000)
+                .note("Einleitung")
+                .build();
+        journey.getItems().add(item);
+        geschichteRepository.save(journey);
+
+        String session = loginAsWriter();
+        ResponseEntity<String> response = http.exchange(
+                baseUrl + "/api/geschichten", HttpMethod.GET,
+                new HttpEntity<>(sessionHeaders(session)), String.class);
+
+        assertThat(response.getStatusCode().value()).isEqualTo(200);
+        assertThat(response.getBody()).contains("Reise durch die Briefe");
+    }
+
+    // ─── GET /api/geschichten/{id} ───────────────────────────────────────────
+
+    @Test
+    void getById_returns_200_with_items_and_does_not_500_open_in_view_false() {
+        // This test is the canonical guard against LazyInitializationException.
+        // open-in-view: false means the Hibernate session is closed when Jackson serializes.
+        // GeschichteService.getById() must initialize items inside its @Transactional boundary.
+        AppUser writer = appUserRepository.findByEmail(WRITER_EMAIL).orElseThrow();
+        Geschichte journey = Geschichte.builder()
+                .title("Familiengeschichte")
+                .status(GeschichteStatus.PUBLISHED)
+                .type(GeschichteType.JOURNEY)
+                .author(writer)
+                .publishedAt(LocalDateTime.now())
+                .items(new ArrayList<>())
+                .persons(new HashSet<>())
+                .build();
+        JourneyItem note = JourneyItem.builder()
+                .geschichte(journey).position(1000).note("Prolog").build();
+        JourneyItem note2 = JourneyItem.builder()
+                .geschichte(journey).position(2000).note("Epilog").build();
+        journey.getItems().add(note);
+        journey.getItems().add(note2);
+        Geschichte saved = geschichteRepository.save(journey);
+
+        String session = loginAsWriter();
+        ResponseEntity<String> response = http.exchange(
+                baseUrl + "/api/geschichten/" + saved.getId(), HttpMethod.GET,
+                new HttpEntity<>(sessionHeaders(session)), String.class);
+
+        assertThat(response.getStatusCode().value()).isEqualTo(200);
+        assertThat(response.getBody())
+                .contains("Familiengeschichte")
+                .contains("Prolog")
+                .contains("Epilog");
+    }
+
+    @Test
+    void getById_returns_404_for_unknown_id() {
+        String session = loginAsWriter();
+        ResponseEntity<String> response = http.exchange(
+                baseUrl + "/api/geschichten/" + UUID.randomUUID(), HttpMethod.GET,
+                new HttpEntity<>(sessionHeaders(session)), String.class);
+
+        assertThat(response.getStatusCode().value()).isEqualTo(404);
+        assertThat(response.getBody()).contains("GESCHICHTE_NOT_FOUND");
+    }
+
+    @Test
+    void getById_returns_404_for_draft_when_reader_lacks_BLOG_WRITE() {
+        AppUser writer = appUserRepository.findByEmail(WRITER_EMAIL).orElseThrow();
+        Geschichte draft = Geschichte.builder()
+                .title("Geheimer Entwurf")
+                .status(GeschichteStatus.DRAFT)
+                .author(writer)
+                .items(new ArrayList<>())
+                .persons(new HashSet<>())
+                .build();
+        Geschichte saved = geschichteRepository.save(draft);
+
+        // Writer lacks explicit BLOG_WRITE permission in the app_users table,
+        // so from the service's perspective they're a reader.
+        String session = loginAsWriter();
+        ResponseEntity<String> response = http.exchange(
+                baseUrl + "/api/geschichten/" + saved.getId(), HttpMethod.GET,
+                new HttpEntity<>(sessionHeaders(session)), String.class);
+
+        assertThat(response.getStatusCode().value()).isEqualTo(404);
+    }
+
+    // ─── PATCH /api/geschichten/{id} ─────────────────────────────────────────
+
+    @Test
+    void update_returns_200_and_serializes_items_open_in_view_false() {
+        // Canonical guard for the write path: PATCH must not 500 when the response
+        // is serialized after the service transaction closed. The raw entity carries
+        // a dead lazy items proxy at that point — the endpoint must answer with a
+        // view assembled inside the transaction.
+        AppUser writer = blogWriter();
+        Geschichte journey = Geschichte.builder()
+                .title("Reise vor dem Umbenennen")
+                .status(GeschichteStatus.DRAFT)
+                .type(GeschichteType.JOURNEY)
+                .author(writer)
+                .items(new ArrayList<>())
+                .persons(new HashSet<>())
+                .build();
+        journey.getItems().add(JourneyItem.builder()
+                .geschichte(journey).position(1000).note("Prolog").build());
+        Geschichte saved = geschichteRepository.save(journey);
+
+        String session = loginAs(BLOG_WRITER_EMAIL, BLOG_WRITER_PASSWORD);
+        ResponseEntity<String> response = http.exchange(
+                baseUrl + "/api/geschichten/" + saved.getId(), HttpMethod.PATCH,
+                new HttpEntity<>("{\"title\":\"Reise nach dem Umbenennen\"}", csrfJsonHeaders(session)),
+                String.class);
+
+        assertThat(response.getStatusCode().value()).isEqualTo(200);
+        assertThat(response.getBody())
+                .contains("Reise nach dem Umbenennen")
+                .contains("Prolog");
+    }
+
+    // ─── helpers ─────────────────────────────────────────────────────────────
+
+    private static final String BLOG_WRITER_EMAIL = "geschichten-http-blogwriter@test.de";
+    private static final String BLOG_WRITER_PASSWORD = "pass!Geschichte2";
+
+    /** A user whose group actually grants BLOG_WRITE — unlike the plain writer above. */
+    private AppUser blogWriter() {
+        UserGroup group = userGroupRepository.save(UserGroup.builder()
+                .name("HttpTest-BlogWriters")
+                .permissions(new HashSet<>(Set.of("BLOG_WRITE")))
+                .build());
+        return appUserRepository.save(AppUser.builder()
+                .email(BLOG_WRITER_EMAIL)
+                .password(passwordEncoder.encode(BLOG_WRITER_PASSWORD))
+                .groups(new HashSet<>(Set.of(group)))
+                .build());
+    }
+
+    /** Session cookie + double-submit CSRF pair + JSON content type for write requests. */
+    private HttpHeaders csrfJsonHeaders(String sessionId) {
+        String xsrf = UUID.randomUUID().toString();
+        HttpHeaders headers = new HttpHeaders();
+        headers.set("Cookie", "fa_session=" + sessionId + "; XSRF-TOKEN=" + xsrf);
+        headers.set("X-XSRF-TOKEN", xsrf);
+        headers.setContentType(MediaType.APPLICATION_JSON);
+        return headers;
+    }
+
+    private String loginAsWriter() {
+        return loginAs(WRITER_EMAIL, WRITER_PASSWORD);
+    }
+
+    private String loginAs(String email, String password) {
+        String xsrf = UUID.randomUUID().toString();
+        HttpHeaders headers = new HttpHeaders();
+        headers.setContentType(MediaType.APPLICATION_JSON);
+        headers.set("Cookie", "XSRF-TOKEN=" + xsrf);
+        headers.set("X-XSRF-TOKEN", xsrf);
+        String body = "{\"email\":\"" + email + "\",\"password\":\"" + password + "\"}";
+        ResponseEntity<String> resp = http.postForEntity(
+                baseUrl + "/api/auth/login", new HttpEntity<>(body, headers), String.class);
+        return extractFaSessionCookie(resp);
+    }
+
+    private HttpHeaders sessionHeaders(String sessionId) {
+        HttpHeaders headers = new HttpHeaders();
+        headers.set("Cookie", "fa_session=" + sessionId);
+        return headers;
+    }
+
+    private String extractFaSessionCookie(ResponseEntity<?> response) {
+        List<String> setCookieHeader = response.getHeaders().get("Set-Cookie");
+        if (setCookieHeader == null) return "";
+        return setCookieHeader.stream()
+                .filter(c -> c.startsWith("fa_session="))
+                .map(c -> c.split(";")[0].substring("fa_session=".length()))
+                .findFirst()
+                .orElse("");
+    }
+
+    private RestTemplate noThrowRestTemplate() {
+        // JDK HttpClient factory — the default HttpURLConnection factory cannot send PATCH.
+        RestTemplate template = new RestTemplate(new JdkClientHttpRequestFactory());
+        template.setErrorHandler(new DefaultResponseErrorHandler() {
+            @Override
+            public boolean hasError(ClientHttpResponse response) throws IOException {
+                return false;
+            }
+        });
+        return template;
+    }
+}

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

@@ -0,0 +1,262 @@
+package org.raddatz.familienarchiv.geschichte;
+
+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.Document;
+import org.raddatz.familienarchiv.document.DocumentRepository;
+import org.raddatz.familienarchiv.document.DocumentStatus;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItem;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemRepository;
+import org.raddatz.familienarchiv.person.Person;
+import org.raddatz.familienarchiv.person.PersonRepository;
+import org.raddatz.familienarchiv.user.AppUser;
+import org.raddatz.familienarchiv.user.AppUserRepository;
+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 java.time.LocalDateTime;
+import java.util.List;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class GeschichteListProjectionTest {
+
+    @Autowired GeschichteRepository geschichteRepository;
+    @Autowired AppUserRepository appUserRepository;
+    @Autowired PersonRepository personRepository;
+    @Autowired DocumentRepository documentRepository;
+    @Autowired JourneyItemRepository journeyItemRepository;
+
+    AppUser author;
+    AppUser otherAuthor;
+
+    @BeforeEach
+    void setUp() {
+        geschichteRepository.deleteAll();
+        author = appUserRepository.save(AppUser.builder()
+                .email("author@test").password("pw").build());
+        otherAuthor = appUserRepository.save(AppUser.builder()
+                .email("other@test").password("pw").build());
+    }
+
+    // ─── findSummaries returns only the requested status ─────────────────────
+
+    @Test
+    void findSummaries_returns_only_published_stories_when_effectiveStatus_is_PUBLISHED() {
+        geschichteRepository.save(published("Veröffentlicht", author));
+        geschichteRepository.save(draft("Entwurf", author));
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.PUBLISHED, null, sentinel(), 0, null);
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getTitle()).isEqualTo("Veröffentlicht");
+    }
+
+    @Test
+    void findSummaries_carries_updatedAt_for_dashboard_relative_times() {
+        // ReaderDraftsModule renders "bearbeitet vor X" from updatedAt — the
+        // projection must carry it for drafts, where publishedAt is null.
+        geschichteRepository.save(draft("Mein Entwurf", author));
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.DRAFT, author.getId(), sentinel(), 0, null);
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getUpdatedAt()).isNotNull();
+    }
+
+    @Test
+    void findSummaries_returns_empty_list_when_no_published_geschichten_exist() {
+        geschichteRepository.save(draft("Nur Entwurf", author));
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.PUBLISHED, null, sentinel(), 0, null);
+
+        assertThat(result).isEmpty();
+    }
+
+    // ─── AuthorSummary nested projection ─────────────────────────────────────
+
+    @Test
+    void findSummaries_exposes_nested_author_names_but_never_email() {
+        AppUser richAuthor = appUserRepository.save(AppUser.builder()
+                .firstName("Franz").lastName("Raddatz")
+                .email("franz@raddatz.de").password("pw").build());
+        geschichteRepository.save(published("Briefe aus der Front", richAuthor));
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.PUBLISHED, null, sentinel(), 0, null);
+
+        assertThat(result).hasSize(1);
+        GeschichteSummary.AuthorSummary a = result.get(0).getAuthor();
+        assertThat(a.getFirstName()).isEqualTo("Franz");
+        assertThat(a.getLastName()).isEqualTo("Raddatz");
+        // Design rule (GeschichteView.AuthorView javadoc): author projections never
+        // expose email or group memberships to readers.
+        assertThat(GeschichteSummary.AuthorSummary.class.getMethods())
+                .extracting(java.lang.reflect.Method::getName)
+                .doesNotContain("getEmail");
+    }
+
+    // ─── GeschichteType is exposed ────────────────────────────────────────────
+
+    @Test
+    void findSummaries_exposes_type_field() {
+        Geschichte journey = Geschichte.builder()
+                .title("Eine Reise")
+                .status(GeschichteStatus.PUBLISHED)
+                .type(GeschichteType.JOURNEY)
+                .author(author)
+                .publishedAt(LocalDateTime.now())
+                .build();
+        geschichteRepository.save(journey);
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.PUBLISHED, null, sentinel(), 0, null);
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getType()).isEqualTo(GeschichteType.JOURNEY);
+    }
+
+    // ─── authorId filter (own-drafts gate) ───────────────────────────────────
+
+    @Test
+    void findSummaries_with_authorId_returns_only_own_drafts() {
+        geschichteRepository.save(draft("Mein Entwurf", author));
+        geschichteRepository.save(draft("Fremder Entwurf", otherAuthor));
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.DRAFT, author.getId(), sentinel(), 0, null);
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getTitle()).isEqualTo("Mein Entwurf");
+    }
+
+    // ─── personCount = 0 → no person filter ──────────────────────────────────
+
+    @Test
+    void findSummaries_with_personCount_zero_ignores_personIds_and_returns_all() {
+        geschichteRepository.save(published("A", author));
+        geschichteRepository.save(published("B", author));
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.PUBLISHED, null, sentinel(), 0, null);
+
+        assertThat(result).hasSize(2);
+    }
+
+    // ─── personCount > 0 AND-semantics ───────────────────────────────────────
+
+    @Test
+    void findSummaries_with_one_personId_returns_only_linked_stories() {
+        Person franz = personRepository.save(Person.builder().firstName("Franz").lastName("R").build());
+        Person anna = personRepository.save(Person.builder().firstName("Anna").lastName("R").build());
+
+        Geschichte withFranz = published("Franz story", author);
+        withFranz.getPersons().add(franz);
+        geschichteRepository.save(withFranz);
+
+        Geschichte withAnna = published("Anna story", author);
+        withAnna.getPersons().add(anna);
+        geschichteRepository.save(withAnna);
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.PUBLISHED, null, List.of(franz.getId()), 1, null);
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getTitle()).isEqualTo("Franz story");
+    }
+
+    @Test
+    void findSummaries_with_two_personIds_uses_AND_semantics() {
+        Person franz = personRepository.save(Person.builder().firstName("Franz").lastName("R").build());
+        Person anna = personRepository.save(Person.builder().firstName("Anna").lastName("R").build());
+
+        Geschichte both = published("Both", author);
+        both.getPersons().add(franz);
+        both.getPersons().add(anna);
+        geschichteRepository.save(both);
+
+        Geschichte onlyFranz = published("Only Franz", author);
+        onlyFranz.getPersons().add(franz);
+        geschichteRepository.save(onlyFranz);
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.PUBLISHED, null, List.of(franz.getId(), anna.getId()), 2, null);
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getTitle()).isEqualTo("Both");
+    }
+
+    // ─── documentId filter (JPQL EXISTS subquery) ────────────────────────────
+
+    @Test
+    void findSummaries_with_documentId_returns_journey_containing_that_document() {
+        Document doc = documentRepository.save(Document.builder()
+                .title("Brief").originalFilename("brief.pdf").status(DocumentStatus.UPLOADED).build());
+        Geschichte withDoc = geschichteRepository.save(journey("Reise mit Dokument", author));
+        Geschichte withoutDoc = geschichteRepository.save(journey("Reise ohne Dokument", author));
+        journeyItemRepository.save(JourneyItem.builder()
+                .geschichte(withDoc).document(doc).position(1).build());
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.PUBLISHED, null, sentinel(), 0, doc.getId());
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getTitle()).isEqualTo("Reise mit Dokument");
+        assertThat(result).extracting(GeschichteSummary::getTitle).doesNotContain("Reise ohne Dokument");
+    }
+
+    @Test
+    void findSummaries_with_unknown_documentId_returns_empty() {
+        geschichteRepository.save(journey("Irgendeine Reise", author));
+
+        List<GeschichteSummary> result = geschichteRepository.findSummaries(
+                GeschichteStatus.PUBLISHED, null, sentinel(), 0, UUID.randomUUID());
+
+        assertThat(result).isEmpty();
+    }
+
+    // ─── helpers ─────────────────────────────────────────────────────────────
+
+    private Geschichte published(String title, AppUser writer) {
+        return Geschichte.builder()
+                .title(title)
+                .status(GeschichteStatus.PUBLISHED)
+                .author(writer)
+                .publishedAt(LocalDateTime.now())
+                .build();
+    }
+
+    private Geschichte draft(String title, AppUser writer) {
+        return Geschichte.builder()
+                .title(title)
+                .status(GeschichteStatus.DRAFT)
+                .author(writer)
+                .build();
+    }
+
+    private Geschichte journey(String title, AppUser writer) {
+        return Geschichte.builder()
+                .title(title)
+                .status(GeschichteStatus.PUBLISHED)
+                .type(GeschichteType.JOURNEY)
+                .author(writer)
+                .publishedAt(LocalDateTime.now())
+                .build();
+    }
+
+    /** Sentinel UUID passed when personCount=0 — the IN() clause is never evaluated. */
+    private List<UUID> sentinel() {
+        return List.of(UUID.fromString("00000000-0000-0000-0000-000000000000"));
+    }
+}