fix(journeyitem): explicit JPQL for the document-dedup guard — derived query unmappable

POST /api/geschichten/{id}/items with a documentId failed 500: Spring Data
resolved the derived existsByGeschichteIdAndDocumentId path as a direct
documentId attribute (shadowed by the transient getDocumentId() getter)
instead of document.id, producing JPQL Hibernate cannot map. Existing tests
only appended note items, so the document branch was never exercised.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CLAUDE.md

@@ -86,13 +86,13 @@ 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
 ├── person/              Person domain
 │   └── relationship/    PersonRelationship sub-domain
-├── search/              NL search domain — NlSearchController, NlQueryParserService, RestClientOllamaClient, NlSearchRateLimiter
 ├── security/            SecurityConfig, Permission, @RequirePermission, PermissionAspect
 ├── tag/                 Tag domain
 └── user/                User domain — AppUser, UserGroup, UserService
@@ -106,13 +106,15 @@ 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` |
 
 **`DocumentStatus` lifecycle:** `PLACEHOLDER → UPLOADED → TRANSCRIBED → REVIEWED → ARCHIVED`
 
@@ -161,7 +163,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); `SMART_SEARCH_UNAVAILABLE` (HTTP 503 — Ollama inference service offline or timed out); `SMART_SEARCH_RATE_LIMITED` (HTTP 429 — user exceeded 5 NL search requests per minute).
+**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_ITEM_NOT_IN_JOURNEY`, `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE` (journey/geschichte domain constraints).
 
 ### Security / Permissions
 
@@ -269,7 +271,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); `SMART_SEARCH_UNAVAILABLE` (HTTP 503 — Ollama inference service offline or timed out); `SMART_SEARCH_RATE_LIMITED` (HTTP 429 — user exceeded 5 NL search requests per minute).
+**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_ITEM_NOT_IN_JOURNEY`, `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE` (journey/geschichte domain constraints).
 
 ---
 

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

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

@@ -50,10 +50,25 @@ public enum AuditKind {
     ADMIN_FORCE_LOGOUT,
 
     /** Payload: {@code {"ip": "1.2.3.4", "email": "addr"}} — password NEVER included */
-    LOGIN_RATE_LIMITED;
+    LOGIN_RATE_LIMITED,
+
+    // --- 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/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);

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

@@ -858,7 +858,7 @@ public class DocumentService {
             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 +1006,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

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

@@ -122,6 +122,16 @@ 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 Geschichte is not of type JOURNEY — journey-item operations are not allowed on it. 400 */
+    GESCHICHTE_TYPE_MISMATCH,
 
     // --- Tags ---
     /** A tag with the given ID does not exist. 404 */
@@ -135,12 +145,6 @@ public enum ErrorCode {
     /** The merge target is a descendant of the source tag. 400 */
     TAG_MERGE_INVALID_TARGET,
 
-    // --- NL Search ---
-    /** Ollama is unreachable or timed out. 503 */
-    SMART_SEARCH_UNAVAILABLE,
-    /** NL search rate limit exceeded (5 requests per user per minute). 429 */
-    SMART_SEARCH_RATE_LIMITED,
-
     // --- Generic ---
     /** Request validation failed (missing or malformed fields). 400 */
     VALIDATION_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"));
     }

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,14 @@
 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 org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.DeleteMapping;
@@ -14,6 +16,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,9 +31,10 @@ import java.util.UUID;
 public class GeschichteController {
 
     private final GeschichteService geschichteService;
+    private final JourneyItemService journeyItemService;
 
     @GetMapping
-    public List<Geschichte> list(
+    public List<GeschichteSummary> list(
             @RequestParam(required = false) GeschichteStatus status,
             @RequestParam(name = "personId", required = false) List<UUID> personIds,
             @RequestParam(required = false) UUID documentId,
@@ -43,20 +47,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 +70,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
@@ -60,6 +56,7 @@ public class GeschichteService {
         return geschichteRepository.count(GeschichteSpecifications.hasStatus(GeschichteStatus.PUBLISHED));
     }
 
+    @Transactional(readOnly = true)
     public Geschichte getById(UUID id) {
         Geschichte g = geschichteRepository.findById(id)
                 .orElseThrow(() -> DomainException.notFound(
@@ -72,24 +69,57 @@ 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.
      */
-    public List<Geschichte> list(GeschichteStatus status, List<UUID> personIds, UUID documentId, int limit) {
+    public List<GeschichteSummary> list(GeschichteStatus status, List<UUID> personIds, UUID documentId, int limit) {
         GeschichteStatus effective = currentUserHasBlogWrite() ? status : GeschichteStatus.PUBLISHED;
         int safeLimit = limit <= 0 ? DEFAULT_LIMIT : Math.min(limit, MAX_LIMIT);
 
         UUID authorId = effective == GeschichteStatus.DRAFT ? currentUser().getId() : null;
-        Specification<Geschichte> spec = Specification.allOf(
-                GeschichteSpecifications.hasStatus(effective),
-                GeschichteSpecifications.hasAuthor(authorId),
-                GeschichteSpecifications.hasAllPersons(personIds),
-                GeschichteSpecifications.hasDocument(documentId),
-                GeschichteSpecifications.orderByDisplayDateDesc()
-        );
-        return geschichteRepository.findAll(spec, Sort.unsorted())
+
+        // 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(UUID.fromString("00000000-0000-0000-0000-000000000000"))
+                : personIds;
+        long personCount = (personIds == null) ? 0 : personIds.size();
+
+        return geschichteRepository
+                .findSummaries(effective, authorId, safePersonIds, personCount, documentId)
                 .stream()
                 .limit(safeLimit)
                 .toList();
@@ -97,26 +127,31 @@ 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());
         Geschichte g = Geschichte.builder()
                 .title(dto.getTitle().trim())
                 .body(sanitize(dto.getBody()))
                 .status(GeschichteStatus.DRAFT)
+                .type(dto.getType() != null ? dto.getType() : GeschichteType.STORY)
                 .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);
+        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));
@@ -130,13 +165,11 @@ public class GeschichteService {
         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
@@ -176,15 +209,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,46 @@
+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();
+
+    interface AuthorSummary {
+        String getFirstName();
+        String getLastName();
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        String getEmail();
+    }
+}

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,51 @@
+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;
+
+    // CWE-79 tripwire: plain text — store verbatim, no sanitization. Any HTML/feed/PDF/email
+    // renderer MUST escape this; only Svelte {note} is auto-safe.
+    @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/JourneyItemRepository.java

@@ -0,0 +1,54 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+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);
+
+    /**
+     * 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,257 @@
+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.GeschichteType;
+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.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;
+    static final int MAX_NOTE_LENGTH = 5000;
+
+    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,
+                        "Journey not found: " + geschichteId));
+
+        if (g.getType() != GeschichteType.JOURNEY) {
+            throw DomainException.conflict(ErrorCode.GESCHICHTE_TYPE_MISMATCH,
+                    "Journey items can only be added to a JOURNEY-type Geschichte");
+        }
+
+        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.VALIDATION_ERROR,
+                    "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();
+        JourneyItem saved = journeyItemRepository.save(item);
+
+        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.VALIDATION_ERROR,
+                    "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,
+                    "Journey 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 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,16 @@
+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,
+        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/search/NlQueryInterpretation.java

@@ -1,26 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import io.swagger.v3.oas.annotations.media.Schema;
-
-import java.time.LocalDate;
-import java.util.List;
-
-public record NlQueryInterpretation(
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        List<PersonHint> resolvedPersons,
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        List<PersonHint> ambiguousPersons,
-        LocalDate dateFrom,
-        LocalDate dateTo,
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        List<String> keywords,
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        List<TagHint> resolvedTags,
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        String rawQuery,
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        boolean keywordsApplied,
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        boolean tagsApplied
-) {
-}

backend/src/main/java/org/raddatz/familienarchiv/search/NlQueryParserService.java

@@ -1,216 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import lombok.RequiredArgsConstructor;
-import lombok.extern.slf4j.Slf4j;
-import org.raddatz.familienarchiv.document.DocumentSearchResult;
-import org.raddatz.familienarchiv.document.DocumentService;
-import org.raddatz.familienarchiv.document.DocumentSort;
-import org.raddatz.familienarchiv.document.SearchFilters;
-import org.raddatz.familienarchiv.exception.DomainException;
-import org.raddatz.familienarchiv.exception.ErrorCode;
-import org.raddatz.familienarchiv.person.NameMatches;
-import org.raddatz.familienarchiv.person.Person;
-import org.raddatz.familienarchiv.person.PersonService;
-import org.raddatz.familienarchiv.tag.Tag;
-import org.raddatz.familienarchiv.tag.TagOperator;
-import org.raddatz.familienarchiv.tag.TagService;
-import org.springframework.data.domain.Pageable;
-import org.springframework.stereotype.Service;
-
-import java.time.LocalDate;
-import java.util.ArrayList;
-import java.util.LinkedHashSet;
-import java.util.List;
-import java.util.UUID;
-
-@Service
-@RequiredArgsConstructor
-@Slf4j
-public class NlQueryParserService {
-
-    private static final int MIN_QUERY = 3;
-    private static final int MAX_QUERY = 500;
-    private static final int MAX_NAME_LENGTH = 200;
-    private static final int MIN_TAG_TERM = 3;
-    private static final int MAX_RESOLVED_TAGS = 10;
-
-    private final OllamaClient ollamaClient;
-    private final PersonService personService;
-    private final DocumentService documentService;
-    private final TagService tagService;
-
-    public NlSearchResponse search(String query, Pageable pageable) {
-        if (query == null || query.length() < MIN_QUERY || query.length() > MAX_QUERY) {
-            throw DomainException.badRequest(ErrorCode.VALIDATION_ERROR,
-                    "Query must be between " + MIN_QUERY + " and " + MAX_QUERY + " characters");
-        }
-
-        OllamaExtraction ext = ollamaClient.parse(query);
-
-        List<String> personNames = ext.personNames() != null ? ext.personNames() : List.of();
-        List<String> keywords = ext.keywords() != null ? ext.keywords() : List.of();
-
-        TagResolution tagResolution = resolveTags(keywords);
-        List<TagHint> resolvedTagHints = tagResolution.hints();
-        List<String> resolvedTagNames = tagResolution.tagNames();
-        List<String> remainingKeywords = tagResolution.remaining();
-
-        NameResolution resolution = resolveNames(personNames);
-
-        if (!resolution.ambiguous().isEmpty()) {
-            NlQueryInterpretation interpretation = new NlQueryInterpretation(
-                    List.of(), resolution.ambiguous(),
-                    ext.dateFrom(), ext.dateTo(),
-                    keywords, List.of(), ext.rawQuery(), false, false);
-            return new NlSearchResponse(DocumentSearchResult.of(List.of()), interpretation);
-        }
-
-        List<PersonHint> resolved = resolution.resolved();
-        List<String> noMatchFragments = resolution.noMatchFragments();
-        List<String> extraFragments = resolution.extraFragments();
-
-        boolean hadStructuredMatch = !resolvedTagHints.isEmpty() || !resolved.isEmpty();
-        String text = buildText(remainingKeywords, noMatchFragments, extraFragments, ext.rawQuery(), hadStructuredMatch);
-
-        if (resolved.size() == 1 && isAnyRole(ext.personRole())) {
-            UUID personId = resolved.get(0).id();
-            DocumentSearchResult docs = documentService.searchDocumentsByPersonId(
-                    personId, ext.dateFrom(), ext.dateTo(), pageable);
-            NlQueryInterpretation interpretation = new NlQueryInterpretation(
-                    resolved, List.of(), ext.dateFrom(), ext.dateTo(), keywords, resolvedTagHints, ext.rawQuery(), false, false);
-            return new NlSearchResponse(docs, interpretation);
-        }
-
-        UUID sender = buildSender(resolved, ext.personRole());
-        UUID receiver = buildReceiver(resolved, ext.personRole());
-
-        boolean tagsApplied = !resolvedTagHints.isEmpty();
-        TagOperator tagOperator = tagsApplied ? TagOperator.OR : TagOperator.AND;
-
-        SearchFilters filters = new SearchFilters(
-                text.isBlank() ? null : text,
-                ext.dateFrom(), ext.dateTo(),
-                sender, receiver,
-                resolvedTagNames, null,
-                null, tagOperator, false);
-
-        DocumentSearchResult docs = documentService.searchDocuments(filters, DocumentSort.DATE, "desc", pageable);
-        boolean keywordsApplied = !text.isBlank();
-        NlQueryInterpretation interpretation = new NlQueryInterpretation(
-                resolved, List.of(), ext.dateFrom(), ext.dateTo(), keywords, resolvedTagHints, ext.rawQuery(), keywordsApplied, tagsApplied);
-        return new NlSearchResponse(docs, interpretation);
-    }
-
-    private NameResolution resolveNames(List<String> personNames) {
-        List<PersonHint> resolved = new ArrayList<>();
-        List<PersonHint> ambiguous = new ArrayList<>();
-        List<String> noMatchFragments = new ArrayList<>();
-        List<String> extraFragments = new ArrayList<>();
-
-        int resolvedIndex = 0;
-        for (String name : personNames) {
-            if (name == null || name.length() > MAX_NAME_LENGTH) {
-                log.debug("Skipping name fragment (too long or null): length={}", name == null ? 0 : name.length());
-                continue;
-            }
-            NameMatches matches = personService.resolveByName(name);
-            List<Person> direct = matches.direct();
-            List<Person> partial = matches.partial();
-
-            if (direct.size() == 1) {
-                Person p = direct.get(0);
-                resolvedIndex++;
-                if (resolvedIndex <= 2) {
-                    resolved.add(new PersonHint(p.getId(), p.getDisplayName()));
-                } else {
-                    extraFragments.add(name);
-                }
-            } else if (direct.size() >= 2) {
-                direct.forEach(p -> ambiguous.add(new PersonHint(p.getId(), p.getDisplayName())));
-            } else if (!partial.isEmpty()) {
-                partial.forEach(p -> ambiguous.add(new PersonHint(p.getId(), p.getDisplayName())));
-            } else {
-                noMatchFragments.add(name);
-            }
-        }
-
-        return new NameResolution(resolved, ambiguous, noMatchFragments, extraFragments);
-    }
-
-    private TagResolution resolveTags(List<String> keywords) {
-        LinkedHashSet<Tag> seen = new LinkedHashSet<>();
-        List<String> remaining = new ArrayList<>();
-
-        for (String kw : keywords) {
-            if (kw == null || kw.length() < MIN_TAG_TERM) {
-                remaining.add(kw);
-                continue;
-            }
-            List<Tag> matches = tagService.findByNameContaining(kw);
-            if (matches.isEmpty()) {
-                remaining.add(kw);
-            } else {
-                seen.addAll(matches);
-            }
-        }
-
-        if (seen.size() > MAX_RESOLVED_TAGS) {
-            log.debug("Keyword matched {} tags; capping at {}", seen.size(), MAX_RESOLVED_TAGS);
-        }
-        List<Tag> capped = seen.size() > MAX_RESOLVED_TAGS
-                ? new ArrayList<>(seen).subList(0, MAX_RESOLVED_TAGS)
-                : new ArrayList<>(seen);
-
-        // safe: entities are detached here; mutation is for DTO projection only, no dirty-check fires
-        tagService.resolveEffectiveColors(capped);
-
-        List<TagHint> hints = capped.stream()
-                .map(t -> new TagHint(t.getId(), t.getName(), t.getColor()))
-                .toList();
-        List<String> tagNames = capped.stream().map(Tag::getName).toList();
-
-        return new TagResolution(hints, tagNames, remaining);
-    }
-
-    private String buildText(List<String> keywords, List<String> noMatchFragments,
-                             List<String> extraFragments, String rawQuery, boolean hadStructuredMatch) {
-        List<String> parts = new ArrayList<>();
-        parts.addAll(keywords);
-        parts.addAll(noMatchFragments);
-        parts.addAll(extraFragments);
-        String text = String.join(" ", parts).strip();
-        if (text.isBlank() && !hadStructuredMatch && rawQuery != null && !rawQuery.isBlank()) {
-            return rawQuery;
-        }
-        return text;
-    }
-
-    private boolean isAnyRole(String role) {
-        return role == null || "any".equals(role) || (!"sender".equals(role) && !"receiver".equals(role));
-    }
-
-    private UUID buildSender(List<PersonHint> resolved, String role) {
-        if (resolved.size() >= 2) return resolved.get(0).id();
-        if (resolved.size() == 1 && "sender".equals(role)) return resolved.get(0).id();
-        return null;
-    }
-
-    private UUID buildReceiver(List<PersonHint> resolved, String role) {
-        if (resolved.size() >= 2) return resolved.get(1).id();
-        if (resolved.size() == 1 && "receiver".equals(role)) return resolved.get(0).id();
-        return null;
-    }
-
-    private record NameResolution(
-            List<PersonHint> resolved,
-            List<PersonHint> ambiguous,
-            List<String> noMatchFragments,
-            List<String> extraFragments
-    ) {}
-
-    private record TagResolution(
-            List<TagHint> hints,
-            List<String> tagNames,
-            List<String> remaining
-    ) {}
-}

backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchController.java

@@ -1,28 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import jakarta.validation.Valid;
-import lombok.RequiredArgsConstructor;
-import org.raddatz.familienarchiv.security.Permission;
-import org.raddatz.familienarchiv.security.RequirePermission;
-import org.springframework.data.domain.Pageable;
-import org.springframework.security.core.annotation.AuthenticationPrincipal;
-import org.springframework.security.core.userdetails.UserDetails;
-import org.springframework.web.bind.annotation.*;
-
-@RestController
-@RequestMapping("/api/search/nl")
-@RequiredArgsConstructor
-public class NlSearchController {
-
-    private final NlQueryParserService nlQueryParserService;
-    private final NlSearchRateLimiter rateLimiter;
-
-    @PostMapping
-    @RequirePermission(Permission.READ_ALL)
-    public NlSearchResponse search(@Valid @RequestBody NlSearchRequest request,
-                                   Pageable pageable,
-                                   @AuthenticationPrincipal UserDetails principal) {
-        rateLimiter.checkAndConsume(principal.getUsername());
-        return nlQueryParserService.search(request.query(), pageable);
-    }
-}

backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchRateLimitProperties.java

@@ -1,12 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import lombok.Data;
-import org.springframework.boot.context.properties.ConfigurationProperties;
-import org.springframework.stereotype.Component;
-
-@Component
-@ConfigurationProperties("app.nl-search.rate-limit")
-@Data
-public class NlSearchRateLimitProperties {
-    private int maxRequestsPerMinute = 5;
-}

backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchRateLimiter.java

@@ -1,46 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import com.github.benmanes.caffeine.cache.Caffeine;
-import com.github.benmanes.caffeine.cache.LoadingCache;
-import io.github.bucket4j.Bandwidth;
-import io.github.bucket4j.Bucket;
-import org.raddatz.familienarchiv.exception.DomainException;
-import org.raddatz.familienarchiv.exception.ErrorCode;
-import org.springframework.stereotype.Service;
-
-import java.time.Duration;
-import java.util.concurrent.TimeUnit;
-
-@Service
-public class NlSearchRateLimiter {
-
-    private final LoadingCache<String, Bucket> byUser;
-    private final int maxRequestsPerMinute;
-
-    public NlSearchRateLimiter(NlSearchRateLimitProperties props) {
-        this.maxRequestsPerMinute = props.getMaxRequestsPerMinute();
-        this.byUser = Caffeine.newBuilder()
-                .expireAfterAccess(1, TimeUnit.MINUTES)
-                .build(key -> newBucket(maxRequestsPerMinute));
-    }
-
-    public void checkAndConsume(String userKey) {
-        if (!byUser.get(userKey).tryConsume(1)) {
-            throw DomainException.tooManyRequests(ErrorCode.SMART_SEARCH_RATE_LIMITED,
-                    "NL search rate limit exceeded for user: " + userKey, 60L);
-        }
-    }
-
-    void resetForTest() {
-        byUser.invalidateAll();
-    }
-
-    private static Bucket newBucket(int limit) {
-        return Bucket.builder()
-                .addLimit(Bandwidth.builder()
-                        .capacity(limit)
-                        .refillGreedy(limit, Duration.ofMinutes(1))
-                        .build())
-                .build();
-    }
-}

backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchRequest.java

@@ -1,11 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import jakarta.validation.constraints.NotBlank;
-import jakarta.validation.constraints.Size;
-
-public record NlSearchRequest(
-        @NotBlank
-        @Size(min = 3, max = 500)
-        String query
-) {
-}

backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchResponse.java

@@ -1,12 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import io.swagger.v3.oas.annotations.media.Schema;
-import org.raddatz.familienarchiv.document.DocumentSearchResult;
-
-public record NlSearchResponse(
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        DocumentSearchResult result,
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        NlQueryInterpretation interpretation
-) {
-}

backend/src/main/java/org/raddatz/familienarchiv/search/OllamaClient.java

@@ -1,5 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-public interface OllamaClient {
-    OllamaExtraction parse(String query);
-}

backend/src/main/java/org/raddatz/familienarchiv/search/OllamaExtraction.java

@@ -1,18 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import java.time.LocalDate;
-import java.util.List;
-
-/**
- * Raw structured output from Ollama after parsing and sanitising.
- * personRole is always one of "sender", "receiver", "any" — defensive parsing ensures this.
- */
-record OllamaExtraction(
-        List<String> personNames,
-        String personRole,
-        LocalDate dateFrom,
-        LocalDate dateTo,
-        List<String> keywords,
-        String rawQuery
-) {
-}

backend/src/main/java/org/raddatz/familienarchiv/search/OllamaHealthClient.java

@@ -1,5 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-public interface OllamaHealthClient {
-    boolean isHealthy();
-}

backend/src/main/java/org/raddatz/familienarchiv/search/OllamaProperties.java

@@ -1,15 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import lombok.Data;
-import org.springframework.boot.context.properties.ConfigurationProperties;
-import org.springframework.stereotype.Component;
-
-@Component
-@ConfigurationProperties("app.ollama")
-@Data
-public class OllamaProperties {
-    private String baseUrl;
-    private String model;
-    private int timeoutSeconds = 30;
-    private int healthCheckTimeoutSeconds = 2;
-}

backend/src/main/java/org/raddatz/familienarchiv/search/PersonHint.java

@@ -1,13 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import io.swagger.v3.oas.annotations.media.Schema;
-
-import java.util.UUID;
-
-public record PersonHint(
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        UUID id,
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        String displayName
-) {
-}

backend/src/main/java/org/raddatz/familienarchiv/search/RestClientOllamaClient.java

@@ -1,184 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import lombok.extern.slf4j.Slf4j;
-import org.raddatz.familienarchiv.exception.DomainException;
-import org.raddatz.familienarchiv.exception.ErrorCode;
-import org.springframework.http.client.JdkClientHttpRequestFactory;
-import org.springframework.stereotype.Service;
-import org.springframework.web.client.RestClient;
-import org.springframework.web.client.RestClientException;
-
-import java.net.http.HttpClient;
-import java.time.Duration;
-import java.time.LocalDate;
-import java.time.Year;
-import java.time.format.DateTimeFormatter;
-import java.time.format.DateTimeParseException;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-
-@Service
-@Slf4j
-public class RestClientOllamaClient implements OllamaClient, OllamaHealthClient {
-
-    private static final ObjectMapper MAPPER = new ObjectMapper();
-    private static final Set<String> VALID_ROLES = Set.of("sender", "receiver", "any");
-    private static final int MAX_NAME_LENGTH = 200;
-    private static final int MAX_KEYWORD_LENGTH = 100;
-
-    private static final Map<String, Object> JSON_SCHEMA = Map.of(
-            "type", "object",
-            "required", List.of("personNames", "personRole", "keywords"),
-            "properties", Map.of(
-                    "personNames", Map.of("type", "array", "items", Map.of("type", "string", "maxLength", MAX_NAME_LENGTH)),
-                    "personRole", Map.of("type", "string", "enum", List.of("sender", "receiver", "any")),
-                    "dateFrom", Map.of("type", List.of("string", "null"), "maxLength", 20),
-                    "dateTo", Map.of("type", List.of("string", "null"), "maxLength", 20),
-                    "keywords", Map.of("type", "array", "items", Map.of("type", "string", "maxLength", MAX_KEYWORD_LENGTH))
-            )
-    );
-
-    private final RestClient inferenceClient;
-    private final RestClient healthClient;
-    private final OllamaProperties props;
-
-    public RestClientOllamaClient(OllamaProperties props) {
-        this.props = props;
-
-        HttpClient inferenceHttp = HttpClient.newBuilder()
-                .version(HttpClient.Version.HTTP_1_1)
-                .connectTimeout(Duration.ofSeconds(10))
-                .build();
-        JdkClientHttpRequestFactory inferenceFactory = new JdkClientHttpRequestFactory(inferenceHttp);
-        inferenceFactory.setReadTimeout(Duration.ofSeconds(props.getTimeoutSeconds()));
-        this.inferenceClient = RestClient.builder()
-                .baseUrl(props.getBaseUrl())
-                .requestFactory(inferenceFactory)
-                .build();
-
-        HttpClient healthHttp = HttpClient.newBuilder()
-                .version(HttpClient.Version.HTTP_1_1)
-                .connectTimeout(Duration.ofSeconds(props.getHealthCheckTimeoutSeconds()))
-                .build();
-        JdkClientHttpRequestFactory healthFactory = new JdkClientHttpRequestFactory(healthHttp);
-        healthFactory.setReadTimeout(Duration.ofSeconds(props.getHealthCheckTimeoutSeconds()));
-        this.healthClient = RestClient.builder()
-                .baseUrl(props.getBaseUrl())
-                .requestFactory(healthFactory)
-                .build();
-    }
-
-    @Override
-    public OllamaExtraction parse(String query) {
-        try {
-            OllamaGenerateRequest request = new OllamaGenerateRequest(
-                    props.getModel(), query, JSON_SCHEMA, false);
-            String responseBody = inferenceClient.post()
-                    .uri("/api/generate")
-                    .contentType(org.springframework.http.MediaType.APPLICATION_JSON)
-                    .body(request)
-                    .retrieve()
-                    .body(String.class);
-            return parseOllamaResponse(responseBody, query);
-        } catch (DomainException e) {
-            throw e;
-        } catch (Exception e) {
-            log.warn("Ollama inference failed: {}", e.getClass().getSimpleName());
-            throw DomainException.serviceUnavailable(ErrorCode.SMART_SEARCH_UNAVAILABLE,
-                    "Ollama unavailable: " + e.getClass().getSimpleName());
-        }
-    }
-
-    @Override
-    public boolean isHealthy() {
-        try {
-            healthClient.get().uri("/api/tags").retrieve().toBodilessEntity();
-            return true;
-        } catch (Exception e) {
-            return false;
-        }
-    }
-
-    private OllamaExtraction parseOllamaResponse(String responseBody, String rawQuery) {
-        try {
-            OllamaGenerateResponse response = MAPPER.readValue(responseBody, OllamaGenerateResponse.class);
-            String inner = response.response();
-            if (inner == null || inner.isBlank()) {
-                return fallbackExtraction(rawQuery);
-            }
-            RawOllamaOutput raw = MAPPER.readValue(inner, RawOllamaOutput.class);
-            return toExtraction(raw, rawQuery);
-        } catch (Exception e) {
-            log.warn("Failed to parse Ollama response: {}", e.getClass().getSimpleName());
-            throw DomainException.serviceUnavailable(ErrorCode.SMART_SEARCH_UNAVAILABLE,
-                    "Failed to parse Ollama response: " + e.getClass().getSimpleName());
-        }
-    }
-
-    private OllamaExtraction toExtraction(RawOllamaOutput raw, String rawQuery) {
-        List<String> names = raw.personNames() == null ? List.of() : raw.personNames().stream()
-                .filter(n -> n != null && n.length() <= MAX_NAME_LENGTH)
-                .toList();
-        List<String> keywords = raw.keywords() == null ? List.of() : raw.keywords().stream()
-                .filter(k -> k != null && k.length() <= MAX_KEYWORD_LENGTH)
-                .toList();
-        String role = sanitiseRole(raw.personRole());
-        LocalDate dateFrom = parseDate(raw.dateFrom(), true);
-        LocalDate dateTo = parseDate(raw.dateTo(), false);
-        return new OllamaExtraction(names, role, dateFrom, dateTo, keywords, rawQuery);
-    }
-
-    private OllamaExtraction fallbackExtraction(String rawQuery) {
-        return new OllamaExtraction(List.of(), "any", null, null, List.of(), rawQuery);
-    }
-
-    private String sanitiseRole(String role) {
-        if (role != null && VALID_ROLES.contains(role)) {
-            return role;
-        }
-        log.warn("Unexpected personRole from Ollama: {}", role);
-        return "any";
-    }
-
-    private LocalDate parseDate(String raw, boolean isFrom) {
-        if (raw == null || raw.isBlank()) return null;
-        try {
-            return LocalDate.parse(raw, DateTimeFormatter.ISO_LOCAL_DATE);
-        } catch (DateTimeParseException ignored) {
-        }
-        try {
-            int year = Integer.parseInt(raw.strip());
-            if (year > 1000 && year < 3000) {
-                return isFrom ? Year.of(year).atDay(1) : Year.of(year).atMonth(12).atEndOfMonth();
-            }
-        } catch (NumberFormatException ignored) {
-        }
-        return null;
-    }
-
-    @JsonIgnoreProperties(ignoreUnknown = true)
-    private record OllamaGenerateResponse(String response) {
-    }
-
-    @JsonIgnoreProperties(ignoreUnknown = true)
-    private record RawOllamaOutput(
-            @JsonProperty("personNames") List<String> personNames,
-            @JsonProperty("personRole") String personRole,
-            @JsonProperty("dateFrom") String dateFrom,
-            @JsonProperty("dateTo") String dateTo,
-            @JsonProperty("keywords") List<String> keywords
-    ) {
-    }
-
-    private record OllamaGenerateRequest(
-            String model,
-            String prompt,
-            Object format,
-            boolean stream
-    ) {
-    }
-}

backend/src/main/java/org/raddatz/familienarchiv/search/TagHint.java

@@ -1,14 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import io.swagger.v3.oas.annotations.media.Schema;
-
-import java.util.UUID;
-
-public record TagHint(
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        UUID id,
-        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
-        String name,
-        String color
-) {
-}

backend/src/main/resources/application-dev.yaml

@@ -12,6 +12,3 @@ springdoc:
     enabled: true
     path: /swagger-ui.html
 
-app:
-  ollama:
-    base-url: http://localhost:11434

backend/src/main/resources/application.yaml

@@ -130,18 +130,6 @@ app:
     # The loader maps columns by header name — no positional indices (see ADR-025).
     dir: ${IMPORT_DIR:/import}
 
-  ollama:
-    base-url: http://ollama:11434
-    model: qwen2.5:7b-instruct-q4_K_M
-    # CPU inference: ~18s warm. Higher ceiling absorbs the cold model load on the
-    # first query after an Ollama (re)start before OLLAMA_KEEP_ALIVE pins it.
-    timeout-seconds: 60
-    health-check-timeout-seconds: 2
-
-  nl-search:
-    rate-limit:
-      max-requests-per-minute: 5
-
 ocr:
   sender-model:
     activation-threshold: 100

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/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/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())
@@ -107,7 +106,7 @@ class GeschichteControllerTest {
     @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 +118,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 +150,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 +178,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 +207,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,255 @@
+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_firstName_lastName_email() {
+        AppUser richAuthor = appUserRepository.save(AppUser.builder()
+                .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.getEmail()).isEqualTo("franz@raddatz.de");
+    }
+
+    // ─── 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"));
+    }
+}

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

@@ -0,0 +1,38 @@
+package org.raddatz.familienarchiv.geschichte;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class GeschichteQueryServiceTest {
+
+    @Mock
+    GeschichteRepository geschichteRepository;
+
+    @InjectMocks
+    GeschichteQueryService geschichteQueryService;
+
+    @Test
+    void existsById_returns_true_when_geschichte_exists() {
+        UUID id = UUID.randomUUID();
+        when(geschichteRepository.existsById(id)).thenReturn(true);
+
+        assertThat(geschichteQueryService.existsById(id)).isTrue();
+    }
+
+    @Test
+    void existsById_returns_false_when_geschichte_does_not_exist() {
+        UUID id = UUID.randomUUID();
+        when(geschichteRepository.existsById(id)).thenReturn(false);
+
+        assertThat(geschichteQueryService.existsById(id)).isFalse();
+    }
+}

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

@@ -8,9 +8,12 @@ import org.raddatz.familienarchiv.geschichte.GeschichteUpdateDTO;
 import org.raddatz.familienarchiv.user.AppUser;
 import org.raddatz.familienarchiv.geschichte.Geschichte;
 import org.raddatz.familienarchiv.geschichte.GeschichteStatus;
+import org.raddatz.familienarchiv.geschichte.GeschichteType;
+import org.raddatz.familienarchiv.geschichte.GeschichteView;
 import org.raddatz.familienarchiv.person.Person;
 import org.raddatz.familienarchiv.user.AppUserRepository;
 import org.raddatz.familienarchiv.geschichte.GeschichteRepository;
+import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyItemService;
 import org.raddatz.familienarchiv.person.PersonRepository;
 import org.raddatz.familienarchiv.security.Permission;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -39,6 +42,7 @@ class GeschichteServiceIntegrationTest {
     S3Client s3Client;
 
     @Autowired GeschichteService geschichteService;
+    @Autowired JourneyItemService journeyItemService;
     @Autowired GeschichteRepository geschichteRepository;
     @Autowired PersonRepository personRepository;
     @Autowired AppUserRepository appUserRepository;
@@ -76,11 +80,11 @@ class GeschichteServiceIntegrationTest {
                 + "<script>alert('xss')</script>");
         dto.setPersonIds(List.of(franz.getId()));
 
-        Geschichte created = geschichteService.create(dto);
+        GeschichteView created = geschichteService.create(dto);
 
-        assertThat(created.getId()).isNotNull();
-        assertThat(created.getStatus()).isEqualTo(GeschichteStatus.DRAFT);
-        assertThat(created.getBody())
+        assertThat(created.id()).isNotNull();
+        assertThat(created.status()).isEqualTo(GeschichteStatus.DRAFT);
+        assertThat(created.body())
                 .contains("<strong>jeden Sonntag</strong>")
                 .doesNotContain("<script>");
 
@@ -89,7 +93,7 @@ class GeschichteServiceIntegrationTest {
         assertThat(geschichteService.list(null, List.of(), null, 50)).isEmpty();
 
         // Reader cannot fetch DRAFT by id (404 via GESCHICHTE_NOT_FOUND)
-        UUID draftId = created.getId();
+        UUID draftId = created.id();
         org.assertj.core.api.Assertions.assertThatThrownBy(() -> geschichteService.getById(draftId))
                 .hasMessageContaining("not found");
 
@@ -97,16 +101,17 @@ class GeschichteServiceIntegrationTest {
         authenticateAs(writer, Permission.BLOG_WRITE);
         GeschichteUpdateDTO publishDto = new GeschichteUpdateDTO();
         publishDto.setStatus(GeschichteStatus.PUBLISHED);
-        Geschichte publishedGesch = geschichteService.update(draftId, publishDto);
-        assertThat(publishedGesch.getPublishedAt()).isNotNull();
+        GeschichteView publishedGesch = geschichteService.update(draftId, publishDto);
+        assertThat(publishedGesch.publishedAt()).isNotNull();
 
         // Reader can now see and fetch it
         authenticateAs(reader, Permission.READ_ALL);
         assertThat(geschichteService.list(null, List.of(), null, 50)).hasSize(1);
         assertThat(geschichteService.list(null, List.of(franz.getId()), null, 50)).hasSize(1);
         Geschichte fetched = geschichteService.getById(draftId);
-        assertThat(fetched.getTitle()).isEqualTo("Erinnerung an Opa Franz");
-        assertThat(fetched.getPersons()).extracting(Person::getId).containsExactly(franz.getId());
+        GeschichteView fetchedView = geschichteService.toView(fetched, journeyItemService.getItems(draftId));
+        assertThat(fetchedView.title()).isEqualTo("Erinnerung an Opa Franz");
+        assertThat(fetchedView.persons()).extracting(GeschichteView.PersonView::id).containsExactly(franz.getId());
 
         // Delete as writer; join rows go with it
         authenticateAs(writer, Permission.BLOG_WRITE);
@@ -137,17 +142,17 @@ class GeschichteServiceIntegrationTest {
 
         // No filter → all three
         assertThat(geschichteService.list(null, List.of(), null, 50))
-                .extracting(Geschichte::getId)
+                .extracting(GeschichteSummary::getId)
                 .containsExactlyInAnyOrder(storyAB, storyAC, storyA);
 
         // Single filter (Anna) → all three
         assertThat(geschichteService.list(null, List.of(a.getId()), null, 50))
-                .extracting(Geschichte::getId)
+                .extracting(GeschichteSummary::getId)
                 .containsExactlyInAnyOrder(storyAB, storyAC, storyA);
 
         // AND: Anna AND Bertha → only the AB story (NOT story_A, NOT story_AC)
         assertThat(geschichteService.list(null, List.of(a.getId(), b.getId()), null, 50))
-                .extracting(Geschichte::getId)
+                .extracting(GeschichteSummary::getId)
                 .containsExactly(storyAB);
 
         // AND: Bertha AND Carl → none (no story has both)
@@ -174,7 +179,7 @@ class GeschichteServiceIntegrationTest {
         geschichteService.create(dto);
 
         authenticateAs(writer2, Permission.BLOG_WRITE);
-        List<Geschichte> result = geschichteService.list(GeschichteStatus.DRAFT, List.of(), null, 50);
+        List<GeschichteSummary> result = geschichteService.list(GeschichteStatus.DRAFT, List.of(), null, 50);
 
         assertThat(result).isEmpty();
     }
@@ -185,7 +190,7 @@ class GeschichteServiceIntegrationTest {
         dto.setBody("<p>body</p>");
         dto.setPersonIds(personIds);
         dto.setStatus(GeschichteStatus.PUBLISHED);
-        return geschichteService.create(dto).getId();
+        return geschichteService.create(dto).id();
     }
 
     private void authenticateAs(AppUser user, Permission... permissions) {

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

@@ -7,26 +7,22 @@ import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.InjectMocks;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
-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.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.authentication.UsernamePasswordAuthenticationToken;
 import org.springframework.security.core.authority.SimpleGrantedAuthority;
 import org.springframework.security.core.context.SecurityContextHolder;
 
 import java.time.LocalDateTime;
+import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Optional;
@@ -37,7 +33,10 @@ import java.util.stream.Collectors;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
 import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
@@ -45,17 +44,13 @@ import static org.mockito.Mockito.when;
 @ExtendWith(MockitoExtension.class)
 class GeschichteServiceTest {
 
-    @Mock
-    GeschichteRepository geschichteRepository;
-    @Mock
-    PersonService personService;
-    @Mock
-    DocumentService documentService;
-    @Mock
-    UserService userService;
+    @Mock GeschichteRepository geschichteRepository;
+    @Mock PersonService personService;
+    @Mock DocumentService documentService;
+    @Mock UserService userService;
+    @Mock JourneyItemService journeyItemService;
 
-    @InjectMocks
-    GeschichteService geschichteService;
+    @InjectMocks GeschichteService geschichteService;
 
     AppUser writer;
     AppUser reader;
@@ -96,7 +91,8 @@ class GeschichteServiceTest {
 
         Geschichte result = geschichteService.getById(id);
 
-        assertThat(result).isSameAs(draft);
+        assertThat(result.getId()).isEqualTo(id);
+        assertThat(result.getStatus()).isEqualTo(GeschichteStatus.DRAFT);
     }
 
     @Test
@@ -108,7 +104,8 @@ class GeschichteServiceTest {
 
         Geschichte result = geschichteService.getById(id);
 
-        assertThat(result).isSameAs(published);
+        assertThat(result.getId()).isEqualTo(id);
+        assertThat(result.getStatus()).isEqualTo(GeschichteStatus.PUBLISHED);
     }
 
     @Test
@@ -123,79 +120,175 @@ class GeschichteServiceTest {
                 .isEqualTo(ErrorCode.GESCHICHTE_NOT_FOUND);
     }
 
+    // ─── getView ──────────────────────────────────────────────────────────────
+
+    @Test
+    void getView_returns_assembled_view_and_delegates_to_journeyItemService() {
+        authenticateAs(reader, Permission.READ_ALL);
+        UUID id = UUID.randomUUID();
+        Geschichte published = published(id);
+        JourneyItemView item = new JourneyItemView(UUID.randomUUID(), 10, null, "Note");
+        when(geschichteRepository.findById(id)).thenReturn(Optional.of(published));
+        when(journeyItemService.getItems(id)).thenReturn(List.of(item));
+
+        GeschichteView view = geschichteService.getView(id);
+
+        assertThat(view.id()).isEqualTo(id);
+        assertThat(view.items()).containsExactly(item);
+        verify(journeyItemService).getItems(id);
+    }
+
+    @Test
+    void getView_throws_NOT_FOUND_when_id_unknown() {
+        authenticateAs(reader, Permission.READ_ALL);
+        UUID id = UUID.randomUUID();
+        when(geschichteRepository.findById(id)).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> geschichteService.getView(id))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.GESCHICHTE_NOT_FOUND);
+    }
+
+    @Test
+    void toView_author_displayName_uses_firstName_lastName() {
+        UUID id = UUID.randomUUID();
+        Geschichte published = published(id);
+        published.setAuthor(AppUser.builder()
+                .id(UUID.randomUUID()).email("author@test")
+                .firstName("Hans").lastName("Raddatz").build());
+
+        GeschichteView result = geschichteService.toView(published, List.of());
+
+        assertThat(result.author().displayName()).isEqualTo("Hans Raddatz");
+    }
+
+    @Test
+    void toView_author_displayName_falls_back_to_Unbekannt_when_names_blank() {
+        UUID id = UUID.randomUUID();
+        Geschichte published = published(id);
+        published.setAuthor(AppUser.builder()
+                .id(UUID.randomUUID()).email("anon@test").build());
+
+        GeschichteView result = geschichteService.toView(published, List.of());
+
+        assertThat(result.author().displayName()).isEqualTo("[Unbekannt]");
+    }
+
+    @Test
+    void toView_author_email_is_not_in_author_view() {
+        UUID id = UUID.randomUUID();
+        Geschichte published = published(id);
+        published.setAuthor(AppUser.builder()
+                .id(UUID.randomUUID()).email("secret@test")
+                .firstName("Max").lastName("M").build());
+
+        GeschichteView result = geschichteService.toView(published, List.of());
+
+        // AuthorView exposes only id + displayName — no email field at all
+        assertThat(result.author()).isInstanceOf(GeschichteView.AuthorView.class);
+        assertThat(result.author().displayName()).doesNotContain("secret@test");
+    }
+
+    @Test
+    void toView_persons_are_mapped_to_PersonView() {
+        UUID id = UUID.randomUUID();
+        UUID personId = UUID.randomUUID();
+        Geschichte published = published(id);
+        published.setPersons(new HashSet<>(List.of(
+                Person.builder().id(personId).firstName("Franz").lastName("Raddatz").build()
+        )));
+
+        GeschichteView result = geschichteService.toView(published, List.of());
+
+        assertThat(result.persons()).hasSize(1);
+        GeschichteView.PersonView pv = result.persons().iterator().next();
+        assertThat(pv.id()).isEqualTo(personId);
+        assertThat(pv.firstName()).isEqualTo("Franz");
+        assertThat(pv.lastName()).isEqualTo("Raddatz");
+    }
+
+    @Test
+    void toView_items_are_passed_through() {
+        UUID id = UUID.randomUUID();
+        Geschichte published = published(id);
+
+        GeschichteView result = geschichteService.toView(published, List.of());
+
+        assertThat(result.items()).isEmpty();
+    }
+
     // ─── list ─────────────────────────────────────────────────────────────────
 
     @Test
     void list_forces_PUBLISHED_status_for_reader_without_BLOG_WRITE() {
         authenticateAs(reader, Permission.READ_ALL);
-        when(geschichteRepository.findAll(any(Specification.class), any(Sort.class)))
-                .thenReturn(List.of(published(UUID.randomUUID())));
+        when(geschichteRepository.findSummaries(any(), any(), any(), anyLong(), any()))
+                .thenReturn(List.of());
 
-        geschichteService.list(/*status*/ null, /*personIds*/ List.of(), /*documentId*/ null, /*limit*/ 50);
+        geschichteService.list(null, List.of(), null, 50);
 
-        // Status pinning lives inside the Specification; we assert end-to-end behaviour
-        // in GeschichteServiceIntegrationTest. Here we just confirm the service routes
-        // through the spec-aware repository method.
-        verify(geschichteRepository).findAll(any(Specification.class), any(Sort.class));
+        verify(geschichteRepository).findSummaries(any(), any(), any(), anyLong(), any());
     }
 
     @Test
     void list_passes_null_status_through_for_BLOG_WRITER_so_drafts_are_visible() {
         authenticateAs(writer, Permission.BLOG_WRITE);
-        when(geschichteRepository.findAll(any(Specification.class), any(Sort.class)))
-                .thenReturn(List.of(draft(UUID.randomUUID()), published(UUID.randomUUID())));
+        GeschichteSummary s1 = mock(GeschichteSummary.class);
+        GeschichteSummary s2 = mock(GeschichteSummary.class);
+        when(geschichteRepository.findSummaries(any(), any(), any(), anyLong(), any()))
+                .thenReturn(List.of(s1, s2));
 
-        List<Geschichte> out = geschichteService.list(null, List.of(), null, 50);
+        List<GeschichteSummary> out = geschichteService.list(null, List.of(), null, 50);
 
         assertThat(out).hasSize(2);
-        verify(geschichteRepository).findAll(any(Specification.class), any(Sort.class));
+        verify(geschichteRepository).findSummaries(any(), any(), any(), anyLong(), any());
     }
 
     @Test
-    void list_invokes_repository_findAll_when_filtering_by_single_personId() {
+    void list_invokes_repository_findSummaries_when_filtering_by_single_personId() {
         authenticateAs(reader, Permission.READ_ALL);
         UUID personId = UUID.randomUUID();
-        when(geschichteRepository.findAll(any(Specification.class), any(Sort.class)))
+        when(geschichteRepository.findSummaries(any(), any(), any(), anyLong(), any()))
                 .thenReturn(List.of());
 
         geschichteService.list(null, List.of(personId), null, 50);
 
-        verify(geschichteRepository).findAll(any(Specification.class), any(Sort.class));
+        verify(geschichteRepository).findSummaries(any(), any(), any(), anyLong(), any());
     }
 
     @Test
-    void list_invokes_repository_findAll_when_filtering_by_multiple_personIds() {
+    void list_invokes_repository_findSummaries_when_filtering_by_multiple_personIds() {
         authenticateAs(reader, Permission.READ_ALL);
         UUID a = UUID.randomUUID();
         UUID b = UUID.randomUUID();
-        when(geschichteRepository.findAll(any(Specification.class), any(Sort.class)))
+        when(geschichteRepository.findSummaries(any(), any(), any(), anyLong(), any()))
                 .thenReturn(List.of());
 
         geschichteService.list(null, List.of(a, b), null, 50);
 
-        verify(geschichteRepository).findAll(any(Specification.class), any(Sort.class));
+        verify(geschichteRepository).findSummaries(any(), any(), any(), anyLong(), any());
     }
 
     @Test
-    void list_filters_by_documentId() {
+    void list_passes_documentId_to_repository_as_journey_item_filter() {
         authenticateAs(reader, Permission.READ_ALL);
         UUID documentId = UUID.randomUUID();
-        when(geschichteRepository.findAll(any(Specification.class), any(Sort.class)))
+        when(geschichteRepository.findSummaries(any(), any(), any(), anyLong(), any()))
                 .thenReturn(List.of());
 
         geschichteService.list(null, List.of(), documentId, 50);
 
-        verify(geschichteRepository).findAll(any(Specification.class), any(Sort.class));
+        verify(geschichteRepository).findSummaries(any(), any(), any(), anyLong(), eq(documentId));
     }
 
     @Test
-    void list_caps_limit_at_max_via_pageable_when_caller_passes_huge_value() {
+    void list_caps_limit_at_max_when_caller_passes_huge_value() {
         authenticateAs(reader, Permission.READ_ALL);
-        when(geschichteRepository.findAll(any(Specification.class), any(Sort.class)))
-                .thenReturn(List.of(published(UUID.randomUUID())));
+        when(geschichteRepository.findSummaries(any(), any(), any(), anyLong(), any()))
+                .thenReturn(List.of(mock(GeschichteSummary.class)));
 
-        // 9999 should be clamped — service trims to MAX_LIMIT (200) before/after the query
-        List<Geschichte> out = geschichteService.list(null, List.of(), null, 9999);
+        List<GeschichteSummary> out = geschichteService.list(null, List.of(), null, 9999);
 
         assertThat(out).hasSizeLessThanOrEqualTo(200);
     }
@@ -213,11 +306,11 @@ class GeschichteServiceTest {
         dto.setTitle("My Story");
         dto.setBody("<p>plain text</p>");
 
-        Geschichte saved = geschichteService.create(dto);
+        GeschichteView saved = geschichteService.create(dto);
 
-        assertThat(saved.getStatus()).isEqualTo(GeschichteStatus.DRAFT);
-        assertThat(saved.getPublishedAt()).isNull();
-        assertThat(saved.getAuthor()).isSameAs(writer);
+        assertThat(saved.status()).isEqualTo(GeschichteStatus.DRAFT);
+        assertThat(saved.publishedAt()).isNull();
+        assertThat(saved.author().id()).isEqualTo(writer.getId());
     }
 
     @Test
@@ -231,9 +324,9 @@ class GeschichteServiceTest {
         dto.setTitle("XSS attempt");
         dto.setBody("<p>safe</p><script>alert(1)</script><img src=x onerror=alert(2)>");
 
-        Geschichte saved = geschichteService.create(dto);
+        GeschichteView saved = geschichteService.create(dto);
 
-        assertThat(saved.getBody())
+        assertThat(saved.body())
                 .contains("<p>safe</p>")
                 .doesNotContain("<script>")
                 .doesNotContain("onerror")
@@ -252,9 +345,9 @@ class GeschichteServiceTest {
         dto.setBody("<h2>Heading</h2><p>Some <strong>bold</strong> and <em>italic</em>.</p>"
                 + "<ul><li>one</li></ul><ol><li>first</li></ol>");
 
-        Geschichte saved = geschichteService.create(dto);
+        GeschichteView saved = geschichteService.create(dto);
 
-        assertThat(saved.getBody())
+        assertThat(saved.body())
                 .contains("<h2>Heading</h2>")
                 .contains("<strong>bold</strong>")
                 .contains("<em>italic</em>")
@@ -277,28 +370,9 @@ class GeschichteServiceTest {
         dto.setTitle("Linked");
         dto.setPersonIds(List.of(personId));
 
-        Geschichte saved = geschichteService.create(dto);
+        GeschichteView saved = geschichteService.create(dto);
 
-        assertThat(saved.getPersons()).containsExactly(person);
-    }
-
-    @Test
-    void create_resolves_documentIds_via_DocumentService() {
-        authenticateAs(writer, Permission.BLOG_WRITE);
-        when(userService.findByEmail(writer.getEmail())).thenReturn(writer);
-        UUID docId = UUID.randomUUID();
-        Document doc = Document.builder().id(docId).build();
-        when(documentService.getDocumentById(docId)).thenReturn(doc);
-        when(geschichteRepository.save(any(Geschichte.class)))
-                .thenAnswer(inv -> inv.getArgument(0));
-
-        GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
-        dto.setTitle("Linked doc");
-        dto.setDocumentIds(List.of(docId));
-
-        Geschichte saved = geschichteService.create(dto);
-
-        assertThat(saved.getDocuments()).containsExactly(doc);
+        assertThat(saved.persons()).extracting(GeschichteView.PersonView::id).containsExactly(personId);
     }
 
     @Test
@@ -315,6 +389,37 @@ class GeschichteServiceTest {
                 .isEqualTo(ErrorCode.VALIDATION_ERROR);
     }
 
+    @Test
+    void create_preserves_JOURNEY_type_from_dto() {
+        authenticateAs(writer, Permission.BLOG_WRITE);
+        when(userService.findByEmail(writer.getEmail())).thenReturn(writer);
+        when(geschichteRepository.save(any(Geschichte.class)))
+                .thenAnswer(inv -> inv.getArgument(0));
+
+        GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
+        dto.setTitle("My Journey");
+        dto.setType(GeschichteType.JOURNEY);
+
+        GeschichteView saved = geschichteService.create(dto);
+
+        assertThat(saved.type()).isEqualTo(GeschichteType.JOURNEY);
+    }
+
+    @Test
+    void create_defaults_to_STORY_when_type_is_null() {
+        authenticateAs(writer, Permission.BLOG_WRITE);
+        when(userService.findByEmail(writer.getEmail())).thenReturn(writer);
+        when(geschichteRepository.save(any(Geschichte.class)))
+                .thenAnswer(inv -> inv.getArgument(0));
+
+        GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
+        dto.setTitle("My Story");
+
+        GeschichteView saved = geschichteService.create(dto);
+
+        assertThat(saved.type()).isEqualTo(GeschichteType.STORY);
+    }
+
     // ─── update ──────────────────────────────────────────────────────────────
 
     @Test
@@ -330,10 +435,10 @@ class GeschichteServiceTest {
         GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
         dto.setStatus(GeschichteStatus.PUBLISHED);
 
-        Geschichte saved = geschichteService.update(id, dto);
+        GeschichteView saved = geschichteService.update(id, dto);
 
-        assertThat(saved.getStatus()).isEqualTo(GeschichteStatus.PUBLISHED);
-        assertThat(saved.getPublishedAt()).isNotNull();
+        assertThat(saved.status()).isEqualTo(GeschichteStatus.PUBLISHED);
+        assertThat(saved.publishedAt()).isNotNull();
     }
 
     @Test
@@ -349,10 +454,10 @@ class GeschichteServiceTest {
         GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
         dto.setStatus(GeschichteStatus.DRAFT);
 
-        Geschichte saved = geschichteService.update(id, dto);
+        GeschichteView saved = geschichteService.update(id, dto);
 
-        assertThat(saved.getStatus()).isEqualTo(GeschichteStatus.DRAFT);
-        assertThat(saved.getPublishedAt()).isNull();
+        assertThat(saved.status()).isEqualTo(GeschichteStatus.DRAFT);
+        assertThat(saved.publishedAt()).isNull();
     }
 
     @Test
@@ -366,9 +471,9 @@ class GeschichteServiceTest {
         GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
         dto.setBody("<p>ok</p><script>alert(1)</script>");
 
-        Geschichte saved = geschichteService.update(id, dto);
+        GeschichteView saved = geschichteService.update(id, dto);
 
-        assertThat(saved.getBody()).doesNotContain("<script>").contains("<p>ok</p>");
+        assertThat(saved.body()).doesNotContain("<script>").contains("<p>ok</p>");
     }
 
     @Test
@@ -426,7 +531,7 @@ class GeschichteServiceTest {
                 .body("<p>body</p>")
                 .status(GeschichteStatus.DRAFT)
                 .persons(new HashSet<>())
-                .documents(new HashSet<>())
+                .items(new ArrayList<>())
                 .build();
     }
 
@@ -438,7 +543,7 @@ class GeschichteServiceTest {
                 .status(GeschichteStatus.PUBLISHED)
                 .publishedAt(LocalDateTime.now().minusHours(1))
                 .persons(new HashSet<>())
-                .documents(new HashSet<>())
+                .items(new ArrayList<>())
                 .build();
     }
 }

backend/src/test/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemConstraintsTest.java

@@ -0,0 +1,99 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.document.Document;
+import org.raddatz.familienarchiv.document.DocumentRepository;
+import org.raddatz.familienarchiv.document.DocumentStatus;
+import org.raddatz.familienarchiv.geschichte.Geschichte;
+import org.raddatz.familienarchiv.geschichte.GeschichteRepository;
+import org.raddatz.familienarchiv.geschichte.GeschichteStatus;
+import org.raddatz.familienarchiv.geschichte.GeschichteType;
+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 journey_items — deliberately NOT @Transactional at class level.
+ * A DataIntegrityViolationException inside a class-level @Transactional marks the tx
+ * rollback-only and cascades into TransactionSystemException on teardown.
+ * Each test inserts via jdbcTemplate and uses explicit SQL teardown.
+ */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
+@ActiveProfiles("test")
+@Import(PostgresContainerConfig.class)
+class JourneyItemConstraintsTest {
+
+    @MockitoBean
+    S3Client s3Client;
+
+    @Autowired JdbcTemplate jdbcTemplate;
+    @Autowired GeschichteRepository geschichteRepository;
+    @Autowired DocumentRepository documentRepository;
+
+    private UUID geschichteId;
+    private UUID documentId;
+
+    @BeforeEach
+    void seed() {
+        jdbcTemplate.execute("DELETE FROM journey_items");
+        Document doc = documentRepository.save(Document.builder()
+                .title("Constraints-Test-Doc")
+                .originalFilename("ct.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .build());
+        documentId = doc.getId();
+        Geschichte g = geschichteRepository.save(Geschichte.builder()
+                .title("Constraints-Test-Journey")
+                .status(GeschichteStatus.DRAFT)
+                .type(GeschichteType.JOURNEY)
+                .build());
+        geschichteId = g.getId();
+    }
+
+    @Test
+    void unique_constraint_is_deferrable_initially_deferred() {
+        Boolean condeferrable = jdbcTemplate.queryForObject(
+                "SELECT condeferrable FROM pg_constraint WHERE conname = 'uq_journey_items_geschichte_position'",
+                Boolean.class);
+        Boolean condeferred = jdbcTemplate.queryForObject(
+                "SELECT condeferred FROM pg_constraint WHERE conname = 'uq_journey_items_geschichte_position'",
+                Boolean.class);
+        assertThat(condeferrable).as("constraint must be deferrable").isTrue();
+        assertThat(condeferred).as("constraint must be initially deferred").isTrue();
+    }
+
+    @Test
+    void position_check_rejects_nonpositive() {
+        UUID itemId = UUID.randomUUID();
+        assertThatThrownBy(() ->
+                jdbcTemplate.update(
+                        "INSERT INTO journey_items (id, geschichte_id, position, note) VALUES (?, ?, ?, ?)",
+                        itemId, geschichteId, 0, "test"))
+                .isInstanceOf(DataIntegrityViolationException.class);
+    }
+
+    @Test
+    void unique_constraint_rejects_duplicate_position_per_geschichte() {
+        jdbcTemplate.update(
+                "INSERT INTO journey_items (id, geschichte_id, position, document_id) VALUES (?, ?, ?, ?)",
+                UUID.randomUUID(), geschichteId, 10, documentId);
+
+        assertThatThrownBy(() ->
+                jdbcTemplate.update(
+                        "INSERT INTO journey_items (id, geschichte_id, position, document_id) VALUES (?, ?, ?, ?)",
+                        UUID.randomUUID(), geschichteId, 10, documentId))
+                .isInstanceOf(DataIntegrityViolationException.class);
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemIntegrationTest.java

@@ -0,0 +1,318 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import jakarta.persistence.EntityManager;
+import jakarta.persistence.PersistenceContext;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.document.Document;
+import org.raddatz.familienarchiv.document.DocumentRepository;
+import org.raddatz.familienarchiv.document.DocumentStatus;
+import org.raddatz.familienarchiv.geschichte.Geschichte;
+import org.raddatz.familienarchiv.geschichte.GeschichteRepository;
+import org.raddatz.familienarchiv.geschichte.GeschichteStatus;
+import org.raddatz.familienarchiv.geschichte.GeschichteType;
+import org.raddatz.familienarchiv.security.Permission;
+import org.raddatz.familienarchiv.user.AppUser;
+import org.raddatz.familienarchiv.user.AppUserRepository;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.transaction.annotation.Transactional;
+import software.amazon.awssdk.services.s3.S3Client;
+
+import java.util.List;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
+@ActiveProfiles("test")
+@Import(PostgresContainerConfig.class)
+@Transactional
+class JourneyItemIntegrationTest {
+
+    @MockitoBean
+    S3Client s3Client;
+
+    @PersistenceContext
+    EntityManager em;
+
+    @Autowired GeschichteRepository geschichteRepository;
+    @Autowired JourneyItemRepository journeyItemRepository;
+    @Autowired JourneyItemService journeyItemService;
+    @Autowired DocumentRepository documentRepository;
+    @Autowired AppUserRepository appUserRepository;
+
+    Geschichte journey;
+    Document doc;
+    AppUser writer;
+
+    @BeforeEach
+    void seed() {
+        writer = appUserRepository.save(AppUser.builder()
+                .email("journey-writer@test")
+                .password("hash")
+                .build());
+        doc = documentRepository.save(Document.builder()
+                .title("Testbrief")
+                .originalFilename("testbrief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .build());
+        journey = geschichteRepository.save(Geschichte.builder()
+                .title("Eine Lesereise")
+                .status(GeschichteStatus.DRAFT)
+                .type(GeschichteType.JOURNEY)
+                .build());
+        em.flush();
+        em.clear();
+    }
+
+    @AfterEach
+    void clearSecurity() {
+        SecurityContextHolder.clearContext();
+    }
+
+    private void authenticateAs(AppUser user, Permission... permissions) {
+        var authorities = java.util.Arrays.stream(permissions)
+                .map(p -> new SimpleGrantedAuthority(p.name()))
+                .toList();
+        SecurityContextHolder.getContext().setAuthentication(
+                new UsernamePasswordAuthenticationToken(user.getEmail(), null, authorities));
+    }
+
+    // ─── @OrderBy ─────────────────────────────────────────────────────────────
+
+    @Test
+    void items_are_returned_in_position_order_regardless_of_insertion_order() {
+        Geschichte managed = geschichteRepository.findById(journey.getId()).orElseThrow();
+
+        JourneyItem third = JourneyItem.builder().geschichte(managed).position(3000).document(doc).build();
+        JourneyItem first = JourneyItem.builder().geschichte(managed).position(1000).document(doc).build();
+        JourneyItem second = JourneyItem.builder().geschichte(managed).position(2000).document(doc).build();
+        managed.getItems().addAll(List.of(third, first, second));
+        geschichteRepository.save(managed);
+        em.flush();
+        em.clear();
+
+        Geschichte reloaded = geschichteRepository.findById(journey.getId()).orElseThrow();
+        List<Integer> positions = reloaded.getItems().stream().map(JourneyItem::getPosition).toList();
+
+        assertThat(positions).containsExactly(1000, 2000, 3000);
+    }
+
+    // ─── Cascade ALL + orphanRemoval ──────────────────────────────────────────
+
+    @Test
+    void deleting_geschichte_cascade_deletes_all_journey_items() {
+        Geschichte managed = geschichteRepository.findById(journey.getId()).orElseThrow();
+        managed.getItems().add(JourneyItem.builder().geschichte(managed).position(1000).document(doc).build());
+        managed.getItems().add(JourneyItem.builder().geschichte(managed).position(2000).note("context").build());
+        geschichteRepository.save(managed);
+        em.flush();
+        em.clear();
+
+        UUID geschichteId = journey.getId();
+        geschichteRepository.deleteById(geschichteId);
+        em.flush();
+
+        assertThat(journeyItemRepository.findByGeschichteIdOrderByPosition(geschichteId)).isEmpty();
+    }
+
+    @Test
+    void removing_item_from_items_list_triggers_orphan_removal() {
+        Geschichte managed = geschichteRepository.findById(journey.getId()).orElseThrow();
+        JourneyItem item = JourneyItem.builder().geschichte(managed).position(1000).document(doc).build();
+        managed.getItems().add(item);
+        Geschichte saved = geschichteRepository.save(managed);
+        em.flush();
+        UUID itemId = saved.getItems().get(0).getId(); // extract before clear
+        em.clear();
+        Geschichte reloaded = geschichteRepository.findById(journey.getId()).orElseThrow();
+        reloaded.getItems().removeIf(i -> i.getId().equals(itemId));
+        geschichteRepository.save(reloaded);
+        em.flush();
+
+        assertThat(journeyItemRepository.findById(itemId)).isEmpty();
+    }
+
+    // ─── GeschichteType round-trip ────────────────────────────────────────────
+
+    @Test
+    void type_persists_as_JOURNEY_and_roundtrips() {
+        Geschichte reloaded = geschichteRepository.findById(journey.getId()).orElseThrow();
+        assertThat(reloaded.getType()).isEqualTo(GeschichteType.JOURNEY);
+    }
+
+    @Test
+    void type_defaults_to_STORY_for_new_geschichten() {
+        Geschichte story = geschichteRepository.save(Geschichte.builder()
+                .title("Erinnerung")
+                .status(GeschichteStatus.DRAFT)
+                .build());
+        em.flush();
+        em.clear();
+
+        Geschichte reloaded = geschichteRepository.findById(story.getId()).orElseThrow();
+        assertThat(reloaded.getType()).isEqualTo(GeschichteType.STORY);
+    }
+
+    // ─── Note-only item (document_id IS NULL) ─────────────────────────────────
+
+    @Test
+    void note_only_item_persists_without_document() {
+        Geschichte managed = geschichteRepository.findById(journey.getId()).orElseThrow();
+        JourneyItem note = JourneyItem.builder()
+                .geschichte(managed).position(1000).note("Eine kurze Einleitung.").build();
+        managed.getItems().add(note);
+        Geschichte saved = geschichteRepository.save(managed);
+        em.flush();
+        UUID noteId = saved.getItems().get(0).getId(); // extract before clear
+        em.clear();
+        JourneyItem reloaded = journeyItemRepository.findById(noteId).orElseThrow();
+        assertThat(reloaded.getDocumentId()).isNull();
+        assertThat(reloaded.getNote()).isEqualTo("Eine kurze Einleitung.");
+    }
+
+    // ─── Document-backed item exposes documentId ──────────────────────────────
+
+    @Test
+    void document_backed_item_exposes_document_uuid_via_getDocumentId() {
+        Geschichte managed = geschichteRepository.findById(journey.getId()).orElseThrow();
+        JourneyItem item = JourneyItem.builder()
+                .geschichte(managed).position(1000).document(doc).build();
+        managed.getItems().add(item);
+        Geschichte saved = geschichteRepository.save(managed);
+        em.flush();
+        UUID itemId = saved.getItems().get(0).getId(); // extract before clear
+        em.clear();
+        JourneyItem reloaded = journeyItemRepository.findById(itemId).orElseThrow();
+        assertThat(reloaded.getDocumentId()).isEqualTo(doc.getId());
+    }
+
+    // ─── ON DELETE SET NULL ───────────────────────────────────────────────────
+
+    @Test
+    void deleting_document_sets_item_document_to_null_not_delete_item() {
+        Geschichte managed = geschichteRepository.findById(journey.getId()).orElseThrow();
+        JourneyItem item = JourneyItem.builder()
+                .geschichte(managed).position(1000).document(doc).note("still here").build();
+        managed.getItems().add(item);
+        Geschichte saved = geschichteRepository.save(managed);
+        em.flush();
+        UUID itemId = saved.getItems().get(0).getId(); // extract before clear
+        em.clear();
+
+        // Delete document — ON DELETE SET NULL fires at DB level
+        documentRepository.deleteById(doc.getId());
+        em.flush();
+        em.clear();
+
+        JourneyItem surviving = journeyItemRepository.findById(itemId).orElseThrow();
+        assertThat(surviving.getDocumentId()).isNull();
+        assertThat(surviving.getNote()).isEqualTo("still here");
+    }
+
+    // ─── CHECK constraint: document_id IS NOT NULL OR note IS NOT NULL ─────────
+
+    @Test
+    void saving_item_with_neither_document_nor_note_violates_check_constraint() {
+        Geschichte managed = geschichteRepository.findById(journey.getId()).orElseThrow();
+        JourneyItem empty = JourneyItem.builder()
+                .geschichte(managed).position(1000).build();
+
+        assertThatThrownBy(() -> {
+            journeyItemRepository.save(empty);
+            journeyItemRepository.flush();
+        }).isInstanceOf(Exception.class);
+    }
+
+    // ─── JourneyItemService.append — end-to-end persistence ──────────────────
+
+    @Test
+    void append_persists_item_at_position_10() {
+        // Arrange: authenticate as a user with BLOG_WRITE
+        authenticateAs(writer, Permission.BLOG_WRITE);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setNote("First stop");
+
+        // Act
+        JourneyItemView view = journeyItemService.append(journey.getId(), dto);
+        em.flush();
+        em.clear();
+
+        // Assert: item exists in DB at position 10
+        assertThat(view.position()).isEqualTo(10);
+        assertThat(view.note()).isEqualTo("First stop");
+        List<JourneyItem> persisted = journeyItemRepository.findByGeschichteIdOrderByPosition(journey.getId());
+        assertThat(persisted).hasSize(1);
+        assertThat(persisted.get(0).getPosition()).isEqualTo(10);
+        assertThat(persisted.get(0).getNote()).isEqualTo("First stop");
+    }
+
+    @Test
+    void append_document_persists_and_rejects_duplicate() {
+        // Covers the document branch of append, including the duplicate guard —
+        // the derived exists query must resolve document.id, which the transient
+        // getDocumentId() getter on JourneyItem shadows for Spring Data.
+        authenticateAs(writer, Permission.BLOG_WRITE);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setDocumentId(doc.getId());
+
+        JourneyItemView view = journeyItemService.append(journey.getId(), dto);
+        em.flush();
+        em.clear();
+
+        assertThat(view.document()).isNotNull();
+        assertThat(view.document().id()).isEqualTo(doc.getId());
+
+        JourneyItemCreateDTO duplicate = new JourneyItemCreateDTO();
+        duplicate.setDocumentId(doc.getId());
+        assertThatThrownBy(() -> journeyItemService.append(journey.getId(), duplicate))
+                .hasFieldOrPropertyWithValue("code",
+                        org.raddatz.familienarchiv.exception.ErrorCode.JOURNEY_DOCUMENT_ALREADY_ADDED);
+    }
+
+    // ─── JourneyItemService.reorder — atomicity check ────────────────────────
+
+    @Test
+    void reorder_swaps_positions_atomically() {
+        // Arrange: append two items (pos 10, pos 20)
+        authenticateAs(writer, Permission.BLOG_WRITE);
+
+        JourneyItemCreateDTO dto1 = new JourneyItemCreateDTO();
+        dto1.setNote("Item one");
+        JourneyItemView item1View = journeyItemService.append(journey.getId(), dto1);
+
+        JourneyItemCreateDTO dto2 = new JourneyItemCreateDTO();
+        dto2.setNote("Item two");
+        JourneyItemView item2View = journeyItemService.append(journey.getId(), dto2);
+
+        assertThat(item1View.position()).isEqualTo(10);
+        assertThat(item2View.position()).isEqualTo(20);
+
+        // Act: reorder with [item2, item1]
+        JourneyReorderDTO reorderDto = new JourneyReorderDTO();
+        reorderDto.setItemIds(List.of(item2View.id(), item1View.id()));
+        List<JourneyItemView> reordered = journeyItemService.reorder(journey.getId(), reorderDto);
+        em.flush();
+        em.clear();
+
+        // Assert: item2 is now at position 10, item1 is at position 20
+        List<JourneyItem> persisted = journeyItemRepository.findByGeschichteIdOrderByPosition(journey.getId());
+        assertThat(persisted).hasSize(2);
+        assertThat(persisted.get(0).getId()).isEqualTo(item2View.id());
+        assertThat(persisted.get(0).getPosition()).isEqualTo(10);
+        assertThat(persisted.get(1).getId()).isEqualTo(item1View.id());
+        assertThat(persisted.get(1).getPosition()).isEqualTo(20);
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemServiceTest.java

@@ -0,0 +1,705 @@
+package org.raddatz.familienarchiv.geschichte.journeyitem;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+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.document.DocumentStatus;
+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.GeschichteStatus;
+import org.raddatz.familienarchiv.geschichte.GeschichteType;
+import org.raddatz.familienarchiv.person.Person;
+import org.raddatz.familienarchiv.user.AppUser;
+import org.raddatz.familienarchiv.user.UserService;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.context.SecurityContextHolder;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class JourneyItemServiceTest {
+
+    @Mock JourneyItemRepository journeyItemRepository;
+    @Mock GeschichteQueryService geschichteQueryService;
+    @Mock DocumentService documentService;
+    @Mock AuditService auditService;
+    @Mock UserService userService;
+
+    @InjectMocks JourneyItemService journeyItemService;
+
+    UUID geschichteId = UUID.randomUUID();
+    UUID itemId = UUID.randomUUID();
+    UUID docId = UUID.randomUUID();
+    UUID actorId = UUID.randomUUID();
+
+    @BeforeEach
+    void setupAuth() {
+        AppUser actor = AppUser.builder().id(actorId).email("test@test.de").build();
+        lenient().when(userService.findByEmail("test@test.de")).thenReturn(actor);
+        lenient().when(geschichteQueryService.existsById(geschichteId)).thenReturn(true);
+        SecurityContextHolder.getContext().setAuthentication(
+                new UsernamePasswordAuthenticationToken("test@test.de", null,
+                        List.of(new SimpleGrantedAuthority("BLOG_WRITE"))));
+    }
+
+    // ─── toSummary — name composition ────────────────────────────────────────
+
+    @Test
+    void toSummary_uses_linked_person_firstName_lastName() {
+        Person sender = Person.builder().firstName("Franz").lastName("Raddatz").build();
+        Document doc = makeDoc(docId, sender, List.of(), null, null);
+
+        var summary = journeyItemService.toSummary(doc);
+
+        assertThat(summary.senderName()).isEqualTo("Franz Raddatz");
+    }
+
+    @Test
+    void toSummary_falls_back_to_senderText_when_no_person() {
+        Document doc = makeDoc(docId, null, List.of(), "Familie Müller", null);
+
+        var summary = journeyItemService.toSummary(doc);
+
+        assertThat(summary.senderName()).isEqualTo("Familie Müller");
+    }
+
+    @Test
+    void toSummary_returns_null_senderName_when_neither_person_nor_text() {
+        Document doc = makeDoc(docId, null, List.of(), null, null);
+
+        var summary = journeyItemService.toSummary(doc);
+
+        assertThat(summary.senderName()).isNull();
+    }
+
+    @Test
+    void toSummary_receiverCount_0_and_null_name_when_no_receiver() {
+        Document doc = makeDoc(docId, null, List.of(), null, null);
+
+        var summary = journeyItemService.toSummary(doc);
+
+        assertThat(summary.receiverCount()).isEqualTo(0);
+        assertThat(summary.receiverName()).isNull();
+    }
+
+    @Test
+    void toSummary_multi_receiver_returns_first_canonical_name_and_total_count() {
+        Person emma = Person.builder().firstName("Emma").lastName("Raddatz").build();
+        Person anna = Person.builder().firstName("Anna").lastName("Amann").build();
+        Document doc = makeDoc(docId, null, List.of(emma, anna), null, null);
+
+        var summary = journeyItemService.toSummary(doc);
+
+        assertThat(summary.receiverCount()).isEqualTo(2);
+        assertThat(summary.receiverName()).isEqualTo("Anna Amann"); // alphabetically first by lastName
+    }
+
+    @Test
+    void toSummary_datePrecision_SEASON_roundtrips() {
+        Document doc = makeDoc(docId, null, List.of(), null, null);
+        doc.setMetaDatePrecision(DatePrecision.SEASON);
+
+        var summary = journeyItemService.toSummary(doc);
+
+        assertThat(summary.datePrecision()).isEqualTo(DatePrecision.SEASON);
+    }
+
+    @Test
+    void toSummary_datePrecision_APPROX_roundtrips() {
+        Document doc = makeDoc(docId, null, List.of(), null, null);
+        doc.setMetaDatePrecision(DatePrecision.APPROX);
+
+        var summary = journeyItemService.toSummary(doc);
+
+        assertThat(summary.datePrecision()).isEqualTo(DatePrecision.APPROX);
+    }
+
+    // ─── append ──────────────────────────────────────────────────────────────
+
+    @Test
+    void append_to_empty_journey_starts_at_10() {
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(0L);
+        when(journeyItemRepository.findMaxPositionByGeschichteId(geschichteId)).thenReturn(Optional.empty());
+        JourneyItem saved = savedItem(itemId, journey, 10, null, "Note");
+        when(journeyItemRepository.save(any())).thenReturn(saved);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setNote("Note");
+
+        JourneyItemView view = journeyItemService.append(geschichteId, dto);
+
+        assertThat(view.position()).isEqualTo(10);
+    }
+
+    @Test
+    void append_after_reorder_continues_from_max_position() {
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(2L);
+        when(journeyItemRepository.findMaxPositionByGeschichteId(geschichteId)).thenReturn(Optional.of(40));
+        JourneyItem saved = savedItem(itemId, journey, 50, null, "Note");
+        when(journeyItemRepository.save(any())).thenReturn(saved);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setNote("Note");
+
+        JourneyItemView view = journeyItemService.append(geschichteId, dto);
+
+        assertThat(view.position()).isEqualTo(50);
+    }
+
+    @Test
+    void append_returns400_when_neither_documentId_nor_note() {
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(0L);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+
+        assertThatThrownBy(() -> journeyItemService.append(geschichteId, dto))
+                .isInstanceOf(DomainException.class)
+                .hasMessageContaining("documentId or note");
+    }
+
+    @Test
+    void append_returns400_when_note_trims_to_empty_and_no_document() {
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(0L);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setNote("   \n  ");
+
+        assertThatThrownBy(() -> journeyItemService.append(geschichteId, dto))
+                .isInstanceOf(DomainException.class);
+    }
+
+    @Test
+    void append_returns400_when_note_exceeds_5000_chars() {
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(0L);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setNote("x".repeat(5001));
+
+        assertThatThrownBy(() -> journeyItemService.append(geschichteId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.VALIDATION_ERROR));
+    }
+
+    @Test
+    void append_returns409_on_non_JOURNEY_type() {
+        Geschichte story = Geschichte.builder()
+                .id(geschichteId)
+                .title("Story")
+                .type(GeschichteType.STORY)
+                .status(GeschichteStatus.DRAFT)
+                .build();
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(story));
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setNote("Note");
+
+        assertThatThrownBy(() -> journeyItemService.append(geschichteId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.GESCHICHTE_TYPE_MISMATCH));
+    }
+
+    @Test
+    void append_never_calls_findSummaryByIdInternal_when_geschichte_type_is_STORY() {
+        // Arrange: mock geschichteQueryService.findById() to return a STORY-type Geschichte
+        UUID storyId = UUID.randomUUID();
+        Geschichte story = Geschichte.builder()
+                .id(storyId)
+                .type(GeschichteType.STORY)
+                .build();
+        when(geschichteQueryService.findById(storyId)).thenReturn(Optional.of(story));
+
+        // Act + Assert: calling append throws GESCHICHTE_TYPE_MISMATCH
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setDocumentId(UUID.randomUUID());
+        assertThatThrownBy(() -> journeyItemService.append(storyId, dto))
+                .isInstanceOf(DomainException.class);
+
+        // Verify: document service was never touched — type guard fired first
+        verifyNoInteractions(documentService);
+    }
+
+    @Test
+    void append_returns404_when_documentId_does_not_exist() {
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(0L);
+        when(documentService.findSummaryByIdInternal(docId))
+                .thenThrow(DomainException.notFound(ErrorCode.DOCUMENT_NOT_FOUND, "not found"));
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setDocumentId(docId);
+
+        assertThatThrownBy(() -> journeyItemService.append(geschichteId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.DOCUMENT_NOT_FOUND));
+    }
+
+    @Test
+    void append_returns409_when_100_items_exist() {
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(100L);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setNote("Note");
+
+        assertThatThrownBy(() -> journeyItemService.append(geschichteId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.JOURNEY_AT_CAPACITY));
+    }
+
+    @Test
+    void append_returns409_when_document_already_in_journey() {
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(1L);
+        when(journeyItemRepository.existsByGeschichteIdAndDocumentId(geschichteId, docId)).thenReturn(true);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setDocumentId(docId);
+
+        assertThatThrownBy(() -> journeyItemService.append(geschichteId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.JOURNEY_DOCUMENT_ALREADY_ADDED));
+    }
+
+    @Test
+    void cap_is_COUNT_based_not_MAX_position_based() {
+        // 99 rows with MAX(position)=2000 should still accept the 100th append
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(99L);
+        when(journeyItemRepository.findMaxPositionByGeschichteId(geschichteId)).thenReturn(Optional.of(2000));
+        JourneyItem saved = savedItem(itemId, journey, 2010, null, "Note");
+        when(journeyItemRepository.save(any())).thenReturn(saved);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setNote("Note");
+
+        assertThat(journeyItemService.append(geschichteId, dto).position()).isEqualTo(2010);
+    }
+
+    @Test
+    void append_audits_JOURNEY_ITEM_ADDED() {
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(0L);
+        when(journeyItemRepository.findMaxPositionByGeschichteId(geschichteId)).thenReturn(Optional.empty());
+        JourneyItem saved = savedItem(itemId, journey, 10, null, "Note");
+        when(journeyItemRepository.save(any())).thenReturn(saved);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setNote("Note");
+        journeyItemService.append(geschichteId, dto);
+
+        verify(auditService).logAfterCommit(eq(AuditKind.JOURNEY_ITEM_ADDED), eq(actorId), isNull(), any());
+    }
+
+    // ─── updateNote ───────────────────────────────────────────────────────────
+
+    @Test
+    void updateNote_absent_leaves_note_unchanged() {
+        Geschichte journey = journey(geschichteId);
+        JourneyItem item = savedItem(itemId, journey, 10, null, "Original note");
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.of(item));
+
+        JourneyItemUpdateDTO dto = new JourneyItemUpdateDTO();
+        // note is null by default — absent from JSON, no-op
+
+        JourneyItemView view = journeyItemService.updateNote(geschichteId, itemId, dto);
+
+        assertThat(view.note()).isEqualTo("Original note");
+        verify(journeyItemRepository, never()).save(any());
+    }
+
+    @Test
+    void updateNote_null_clears_note_when_document_is_present() {
+        Geschichte journey = journey(geschichteId);
+        Document doc = makeDoc(docId, null, List.of(), null, null);
+        JourneyItem item = savedItemWithDoc(itemId, journey, 10, doc, "Old note");
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.of(item));
+        JourneyItem saved = savedItemWithDoc(itemId, journey, 10, doc, null);
+        when(journeyItemRepository.save(item)).thenReturn(saved);
+
+        JourneyItemUpdateDTO dto = new JourneyItemUpdateDTO();
+        dto.setNote(Optional.empty());
+
+        JourneyItemView view = journeyItemService.updateNote(geschichteId, itemId, dto);
+
+        assertThat(view.note()).isNull();
+    }
+
+    @Test
+    void updateNote_string_sets_note() {
+        Geschichte journey = journey(geschichteId);
+        JourneyItem item = savedItem(itemId, journey, 10, null, null);
+        item.setNote(null);
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.of(item));
+        JourneyItem saved = savedItem(itemId, journey, 10, null, "New note");
+        when(journeyItemRepository.save(item)).thenReturn(saved);
+
+        JourneyItemUpdateDTO dto = new JourneyItemUpdateDTO();
+        dto.setNote(Optional.of("New note"));
+
+        JourneyItemView view = journeyItemService.updateNote(geschichteId, itemId, dto);
+
+        assertThat(view.note()).isEqualTo("New note");
+    }
+
+    @Test
+    void updateNote_null_returns400_when_item_has_no_document() {
+        Geschichte journey = journey(geschichteId);
+        JourneyItem item = savedItem(itemId, journey, 10, null, "Only note — no doc");
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.of(item));
+
+        JourneyItemUpdateDTO dto = new JourneyItemUpdateDTO();
+        dto.setNote(Optional.empty());
+
+        assertThatThrownBy(() -> journeyItemService.updateNote(geschichteId, itemId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.VALIDATION_ERROR));
+    }
+
+    @Test
+    void updateNote_whitespace_only_including_newlines_stored_as_null() {
+        Geschichte journey = journey(geschichteId);
+        Document doc = makeDoc(docId, null, List.of(), null, null);
+        JourneyItem item = savedItemWithDoc(itemId, journey, 10, doc, "Old");
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.of(item));
+        JourneyItem saved = savedItemWithDoc(itemId, journey, 10, doc, null);
+        when(journeyItemRepository.save(item)).thenReturn(saved);
+
+        JourneyItemUpdateDTO dto = new JourneyItemUpdateDTO();
+        dto.setNote(Optional.of("\n \n"));
+
+        JourneyItemView view = journeyItemService.updateNote(geschichteId, itemId, dto);
+
+        assertThat(view.note()).isNull();
+    }
+
+    @Test
+    void patch_returns400_when_note_exceeds_5000_chars() {
+        Geschichte journey = journey(geschichteId);
+        JourneyItem item = savedItem(itemId, journey, 10, null, "Old");
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.of(item));
+
+        JourneyItemUpdateDTO dto = new JourneyItemUpdateDTO();
+        dto.setNote(Optional.of("x".repeat(5001)));
+
+        assertThatThrownBy(() -> journeyItemService.updateNote(geschichteId, itemId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.VALIDATION_ERROR));
+    }
+
+    @Test
+    void updateNote_auditsNoteUpdate() {
+        Geschichte journey = journey(geschichteId);
+        JourneyItem item = savedItem(itemId, journey, 10, null, null);
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.of(item));
+        JourneyItem saved = savedItem(itemId, journey, 10, null, "New note");
+        when(journeyItemRepository.save(item)).thenReturn(saved);
+
+        JourneyItemUpdateDTO dto = new JourneyItemUpdateDTO();
+        dto.setNote(Optional.of("New note"));
+        journeyItemService.updateNote(geschichteId, itemId, dto);
+
+        verify(auditService).logAfterCommit(eq(AuditKind.JOURNEY_ITEM_NOTE_UPDATED), eq(actorId), isNull(), any());
+    }
+
+    @Test
+    void patch_returns404_when_item_belongs_to_different_journey() {
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.empty());
+
+        JourneyItemUpdateDTO dto = new JourneyItemUpdateDTO();
+        dto.setNote(Optional.of("text"));
+
+        assertThatThrownBy(() -> journeyItemService.updateNote(geschichteId, itemId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.JOURNEY_ITEM_NOT_FOUND));
+    }
+
+    // ─── delete ───────────────────────────────────────────────────────────────
+
+    @Test
+    void delete_returns404_when_item_already_deleted() {
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> journeyItemService.delete(geschichteId, itemId))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.JOURNEY_ITEM_NOT_FOUND));
+    }
+
+    @Test
+    void delete_no_audit_when_item_not_found() {
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> journeyItemService.delete(geschichteId, itemId))
+                .isInstanceOf(DomainException.class);
+
+        verify(auditService, never()).logAfterCommit(any(), any(), any(), any());
+    }
+
+    @Test
+    void delete_audits_JOURNEY_ITEM_REMOVED_when_item_found() {
+        Geschichte journey = journey(geschichteId);
+        JourneyItem item = savedItem(itemId, journey, 10, null, "Note");
+        when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.of(item));
+
+        journeyItemService.delete(geschichteId, itemId);
+
+        verify(auditService).logAfterCommit(eq(AuditKind.JOURNEY_ITEM_REMOVED), eq(actorId), isNull(), any());
+    }
+
+    // ─── reorder ─────────────────────────────────────────────────────────────
+
+    @Test
+    void reorder_unknownGeschichteId_throws404() {
+        UUID unknownId = UUID.randomUUID();
+        // geschichteQueryService is not lenient-stubbed for unknownId → returns false
+
+        JourneyReorderDTO dto = new JourneyReorderDTO();
+        dto.setItemIds(List.of());
+
+        assertThatThrownBy(() -> journeyItemService.reorder(unknownId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.GESCHICHTE_NOT_FOUND));
+    }
+
+    @Test
+    void reorder_returns400_when_itemIds_contain_duplicates() {
+        UUID id1 = UUID.randomUUID();
+        when(journeyItemRepository.findIdsByGeschichteId(geschichteId)).thenReturn(Set.of(id1));
+
+        JourneyReorderDTO dto = new JourneyReorderDTO();
+        dto.setItemIds(List.of(id1, id1));  // duplicate
+
+        assertThatThrownBy(() -> journeyItemService.reorder(geschichteId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.VALIDATION_ERROR));
+    }
+
+    @Test
+    void reorder_returns400_when_itemId_belongs_to_different_journey() {
+        UUID foreignId = UUID.randomUUID();
+        UUID localId = UUID.randomUUID();
+        when(journeyItemRepository.findIdsByGeschichteId(geschichteId)).thenReturn(Set.of(localId));
+
+        JourneyReorderDTO dto = new JourneyReorderDTO();
+        dto.setItemIds(List.of(foreignId));
+
+        assertThatThrownBy(() -> journeyItemService.reorder(geschichteId, dto))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getCode())
+                        .isEqualTo(ErrorCode.VALIDATION_ERROR));
+    }
+
+    @Test
+    void reorder_returns400_when_ids_have_extra_items() {
+        UUID id1 = UUID.randomUUID();
+        UUID id2 = UUID.randomUUID();
+        when(journeyItemRepository.findIdsByGeschichteId(geschichteId)).thenReturn(Set.of(id1));
+
+        JourneyReorderDTO dto = new JourneyReorderDTO();
+        dto.setItemIds(List.of(id1, id2));
+
+        assertThatThrownBy(() -> journeyItemService.reorder(geschichteId, dto))
+                .isInstanceOf(DomainException.class);
+    }
+
+    @Test
+    void reorder_returns200_when_empty_on_empty_journey() {
+        when(journeyItemRepository.findIdsByGeschichteId(geschichteId)).thenReturn(Set.of());
+
+        JourneyReorderDTO dto = new JourneyReorderDTO();
+        dto.setItemIds(List.of());
+
+        List<JourneyItemView> result = journeyItemService.reorder(geschichteId, dto);
+
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    void reorder_returns400_when_empty_on_nonempty_journey() {
+        UUID id1 = UUID.randomUUID();
+        when(journeyItemRepository.findIdsByGeschichteId(geschichteId)).thenReturn(Set.of(id1));
+
+        JourneyReorderDTO dto = new JourneyReorderDTO();
+        dto.setItemIds(List.of());
+
+        assertThatThrownBy(() -> journeyItemService.reorder(geschichteId, dto))
+                .isInstanceOf(DomainException.class);
+    }
+
+    @Test
+    void reorder_returns_items_in_new_order_starting_at_10() {
+        Geschichte journey = journey(geschichteId);
+        UUID id1 = UUID.randomUUID();
+        UUID id2 = UUID.randomUUID();
+        JourneyItem item1 = savedItem(id1, journey, 20, null, "A");
+        JourneyItem item2 = savedItem(id2, journey, 10, null, "B");
+        when(journeyItemRepository.findIdsByGeschichteId(geschichteId)).thenReturn(Set.of(id1, id2));
+        when(journeyItemRepository.findByGeschichteIdOrderByPosition(geschichteId)).thenReturn(List.of(item2, item1));
+        when(journeyItemRepository.saveAll(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        JourneyReorderDTO dto = new JourneyReorderDTO();
+        dto.setItemIds(List.of(id1, id2)); // want id1 first
+
+        List<JourneyItemView> views = journeyItemService.reorder(geschichteId, dto);
+
+        assertThat(views).hasSize(2);
+        assertThat(views.get(0).id()).isEqualTo(id1);
+        assertThat(views.get(0).position()).isEqualTo(10);
+        assertThat(views.get(1).id()).isEqualTo(id2);
+        assertThat(views.get(1).position()).isEqualTo(20);
+    }
+
+    @Test
+    void reorder_identical_order_returns200() {
+        Geschichte journey = journey(geschichteId);
+        UUID id1 = UUID.randomUUID();
+        JourneyItem item1 = savedItem(id1, journey, 10, null, "A");
+        when(journeyItemRepository.findIdsByGeschichteId(geschichteId)).thenReturn(Set.of(id1));
+        when(journeyItemRepository.findByGeschichteIdOrderByPosition(geschichteId)).thenReturn(List.of(item1));
+        when(journeyItemRepository.saveAll(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        JourneyReorderDTO dto = new JourneyReorderDTO();
+        dto.setItemIds(List.of(id1));
+
+        List<JourneyItemView> views = journeyItemService.reorder(geschichteId, dto);
+
+        assertThat(views).hasSize(1);
+        assertThat(views.get(0).position()).isEqualTo(10);
+    }
+
+    @Test
+    void reorder_of_grandfathered_over_cap_journey_succeeds() {
+        Geschichte journey = journey(geschichteId);
+        // 130-item journey — reorder with all 130 IDs must succeed despite > 100 cap
+        List<UUID> ids = new java.util.ArrayList<>();
+        List<JourneyItem> items = new java.util.ArrayList<>();
+        for (int i = 1; i <= 130; i++) {
+            UUID id = UUID.randomUUID();
+            ids.add(id);
+            items.add(savedItem(id, journey, i * 10, null, "item " + i));
+        }
+        when(journeyItemRepository.findIdsByGeschichteId(geschichteId)).thenReturn(new HashSet<>(ids));
+        when(journeyItemRepository.findByGeschichteIdOrderByPosition(geschichteId)).thenReturn(items);
+        when(journeyItemRepository.saveAll(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        JourneyReorderDTO dto = new JourneyReorderDTO();
+        dto.setItemIds(ids);
+
+        List<JourneyItemView> views = journeyItemService.reorder(geschichteId, dto);
+
+        assertThat(views).hasSize(130);
+    }
+
+    @Test
+    void reorder_audits_JOURNEY_ITEMS_REORDERED() {
+        Geschichte journey = journey(geschichteId);
+        UUID id1 = UUID.randomUUID();
+        JourneyItem item1 = savedItem(id1, journey, 10, null, "A");
+        when(journeyItemRepository.findIdsByGeschichteId(geschichteId)).thenReturn(Set.of(id1));
+        when(journeyItemRepository.findByGeschichteIdOrderByPosition(geschichteId)).thenReturn(List.of(item1));
+        when(journeyItemRepository.saveAll(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        JourneyReorderDTO dto = new JourneyReorderDTO();
+        dto.setItemIds(List.of(id1));
+        journeyItemService.reorder(geschichteId, dto);
+
+        verify(auditService).logAfterCommit(eq(AuditKind.JOURNEY_ITEMS_REORDERED), eq(actorId), isNull(), any());
+    }
+
+    // ─── helpers ─────────────────────────────────────────────────────────────
+
+    private Geschichte journey(UUID id) {
+        return Geschichte.builder()
+                .id(id)
+                .title("Test Journey")
+                .type(GeschichteType.JOURNEY)
+                .status(GeschichteStatus.DRAFT)
+                .build();
+    }
+
+    private JourneyItem savedItem(UUID id, Geschichte g, int position, Document doc, String note) {
+        return JourneyItem.builder()
+                .id(id)
+                .geschichte(g)
+                .position(position)
+                .document(null)  // no document entity to avoid LAZY issues in unit tests
+                .note(note)
+                .build();
+    }
+
+    private JourneyItem savedItemWithDoc(UUID id, Geschichte g, int position, Document doc, String note) {
+        JourneyItem item = JourneyItem.builder()
+                .id(id)
+                .geschichte(g)
+                .position(position)
+                .document(doc)
+                .note(note)
+                .build();
+        return item;
+    }
+
+    private Document makeDoc(UUID id, Person sender, List<Person> receivers, String senderText, String receiverText) {
+        Document doc = Document.builder()
+                .id(id)
+                .title("Test Doc")
+                .originalFilename("test.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .senderText(senderText)
+                .receiverText(receiverText)
+                .sender(sender)
+                .build();
+        doc.setReceivers(new HashSet<>(receivers));
+        return doc;
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/search/NlQueryParserServiceTest.java

@@ -1,739 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-import org.mockito.ArgumentCaptor;
-import org.mockito.Mock;
-import org.mockito.MockitoAnnotations;
-import org.raddatz.familienarchiv.document.DocumentSearchResult;
-import org.raddatz.familienarchiv.document.DocumentService;
-import org.raddatz.familienarchiv.document.DocumentSort;
-import org.raddatz.familienarchiv.document.SearchFilters;
-import org.raddatz.familienarchiv.exception.DomainException;
-import org.raddatz.familienarchiv.exception.ErrorCode;
-import org.raddatz.familienarchiv.person.NameMatches;
-import org.raddatz.familienarchiv.person.Person;
-import org.raddatz.familienarchiv.person.PersonService;
-import org.raddatz.familienarchiv.tag.Tag;
-import org.raddatz.familienarchiv.tag.TagOperator;
-import org.raddatz.familienarchiv.tag.TagService;
-import org.springframework.data.domain.PageRequest;
-import org.springframework.data.domain.Pageable;
-
-import java.time.LocalDate;
-import java.util.ArrayList;
-import java.util.Collection;
-import java.util.List;
-import java.util.UUID;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-import static org.mockito.ArgumentMatchers.*;
-import static org.mockito.Mockito.*;
-
-class NlQueryParserServiceTest {
-
-    @Mock OllamaClient ollamaClient;
-    @Mock PersonService personService;
-    @Mock DocumentService documentService;
-    @Mock TagService tagService;
-
-    NlQueryParserService service;
-
-    static final Pageable PAGE = PageRequest.of(0, 20);
-
-    @BeforeEach
-    void setUp() {
-        MockitoAnnotations.openMocks(this);
-        service = new NlQueryParserService(ollamaClient, personService, documentService, tagService);
-        when(documentService.searchDocuments(any(), any(), any(), any()))
-                .thenReturn(DocumentSearchResult.of(List.of()));
-        when(documentService.searchDocumentsByPersonId(any(), any(), any(), any()))
-                .thenReturn(DocumentSearchResult.of(List.of()));
-        when(tagService.findByNameContaining(anyString())).thenReturn(List.of());
-    }
-
-    // --- Factory helpers ---
-
-    private OllamaExtraction extraction(List<String> names, String role, LocalDate from, LocalDate to,
-                                         List<String> keywords) {
-        String raw = names.isEmpty() ? "test query" : String.join(" ", names);
-        return new OllamaExtraction(names, role, from, to, keywords, raw);
-    }
-
-    private Person person(UUID id, String firstName, String lastName) {
-        return Person.builder().id(id).firstName(firstName).lastName(lastName).build();
-    }
-
-    private NameMatches makeNameMatches() {
-        return new NameMatches(List.of(), List.of());
-    }
-
-    private NameMatches makeNameMatches(List<Person> direct) {
-        return new NameMatches(direct, List.of());
-    }
-
-    private NameMatches makeNameMatches(List<Person> direct, List<Person> partial) {
-        return new NameMatches(direct, partial);
-    }
-
-    private static final UUID P1 = UUID.fromString("00000000-0000-0000-0000-000000000001");
-    private static final UUID P2 = UUID.fromString("00000000-0000-0000-0000-000000000002");
-    private static final UUID P3 = UUID.fromString("00000000-0000-0000-0000-000000000003");
-
-    // --- 1. Single resolved name + personRole=sender ---
-
-    @Test
-    void search_resolvesSingleName_asSender() {
-        Person walter = person(P1, "Walter", "Raddatz");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Walter"), "sender", null, null, List.of()));
-        when(personService.resolveByName("Walter")).thenReturn(makeNameMatches(List.of(walter)));
-
-        NlSearchResponse resp = service.search("Was hat Walter geschrieben?", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), eq(DocumentSort.DATE), eq("desc"), eq(PAGE));
-        assertThat(cap.getValue().sender()).isEqualTo(P1);
-        assertThat(cap.getValue().receiver()).isNull();
-        assertThat(resp.interpretation().resolvedPersons()).hasSize(1);
-        assertThat(resp.interpretation().resolvedPersons().get(0).id()).isEqualTo(P1);
-        assertThat(resp.interpretation().ambiguousPersons()).isEmpty();
-    }
-
-    // --- 2. Multi-match name → ambiguous, search NOT executed ---
-
-    @Test
-    void search_multiMatchName_populatesAmbiguous_andSkipsSearch() {
-        Person a = person(UUID.randomUUID(), "Walter", "Braun");
-        Person b = person(UUID.randomUUID(), "Walter", "Schmidt");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Walter"), "sender", null, null, List.of()));
-        when(personService.resolveByName("Walter")).thenReturn(makeNameMatches(List.of(a, b)));
-
-        NlSearchResponse resp = service.search("Briefe von Walter", PAGE);
-
-        verify(documentService, never()).searchDocuments(any(), any(), any(), any());
-        verify(documentService, never()).searchDocumentsByPersonId(any(), any(), any(), any());
-        assertThat(resp.interpretation().ambiguousPersons()).hasSize(2);
-        assertThat(resp.interpretation().resolvedPersons()).isEmpty();
-    }
-
-    // --- 3. Multi-match + personRole=any → still ambiguous, search NOT executed ---
-
-    @Test
-    void search_multiMatchName_withPersonRoleAny_stillSkipsSearch() {
-        Person a = person(UUID.randomUUID(), "Emma", "Braun");
-        Person b = person(UUID.randomUUID(), "Emma", "Raddatz");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Emma"), "any", null, null, List.of()));
-        when(personService.resolveByName("Emma")).thenReturn(makeNameMatches(List.of(a, b)));
-
-        NlSearchResponse resp = service.search("Briefe an Emma", PAGE);
-
-        verify(documentService, never()).searchDocuments(any(), any(), any(), any());
-        verify(documentService, never()).searchDocumentsByPersonId(any(), any(), any(), any());
-        assertThat(resp.interpretation().ambiguousPersons()).hasSize(2);
-    }
-
-    // --- 4. No-match name → folded into text ---
-
-    @Test
-    void search_noMatchName_isFoldedIntoText() {
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Karl"), "any", null, null, List.of()));
-        when(personService.resolveByName("Karl")).thenReturn(makeNameMatches());
-
-        service.search("Briefe von Karl", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().text()).contains("Karl");
-        assertThat(cap.getValue().sender()).isNull();
-        assertThat(cap.getValue().receiver()).isNull();
-    }
-
-    // --- 5. personRole=any + 1 resolved → searchDocumentsByPersonId called ---
-
-    @Test
-    void search_personRoleAny_singleMatch_callsSearchDocumentsByPersonId() {
-        Person walter = person(P1, "Walter", "Raddatz");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Walter"), "any", null, null, List.of()));
-        when(personService.resolveByName("Walter")).thenReturn(makeNameMatches(List.of(walter)));
-
-        NlSearchResponse resp = service.search("Briefe von Walter", PAGE);
-
-        verify(documentService).searchDocumentsByPersonId(eq(P1), isNull(), isNull(), eq(PAGE));
-        verify(documentService, never()).searchDocuments(any(), any(), any(), any());
-        assertThat(resp.interpretation().keywordsApplied()).isFalse();
-    }
-
-    // --- 6. 2 names both resolve → sender=person1, receiver=person2 ---
-
-    @Test
-    void search_twoNamesResolve_assignsSenderAndReceiver() {
-        Person walter = person(P1, "Walter", "Raddatz");
-        Person emma = person(P2, "Emma", "Raddatz");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Walter", "Emma"), "any", null, null, List.of()));
-        when(personService.resolveByName("Walter")).thenReturn(makeNameMatches(List.of(walter)));
-        when(personService.resolveByName("Emma")).thenReturn(makeNameMatches(List.of(emma)));
-
-        NlSearchResponse resp = service.search("Briefe von Walter an Emma", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), eq(DocumentSort.DATE), eq("desc"), eq(PAGE));
-        assertThat(cap.getValue().sender()).isEqualTo(P1);
-        assertThat(cap.getValue().receiver()).isEqualTo(P2);
-        assertThat(resp.interpretation().resolvedPersons().get(0).id()).isEqualTo(P1);
-        assertThat(resp.interpretation().resolvedPersons().get(1).id()).isEqualTo(P2);
-    }
-
-    // --- 7. 2 names, first resolves, second ambiguous → search NOT executed ---
-
-    @Test
-    void search_twoNames_secondAmbiguous_skipsSearch() {
-        Person walter = person(P1, "Walter", "Raddatz");
-        Person emma1 = person(P2, "Emma", "Braun");
-        Person emma2 = person(P3, "Emma", "Schmidt");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Walter", "Emma"), "sender", null, null, List.of()));
-        when(personService.resolveByName("Walter")).thenReturn(makeNameMatches(List.of(walter)));
-        when(personService.resolveByName("Emma")).thenReturn(makeNameMatches(List.of(emma1, emma2)));
-
-        NlSearchResponse resp = service.search("Briefe von Walter an Emma", PAGE);
-
-        verify(documentService, never()).searchDocuments(any(), any(), any(), any());
-        assertThat(resp.interpretation().ambiguousPersons()).hasSize(2);
-    }
-
-    // --- 8. 2 names, first no match → folded into text, second used as single person ---
-
-    @Test
-    void search_twoNames_firstNoMatch_secondResolved_foldFirstIntoText() {
-        Person emma = person(P2, "Emma", "Raddatz");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Karl", "Emma"), "sender", null, null, List.of()));
-        when(personService.resolveByName("Karl")).thenReturn(makeNameMatches());
-        when(personService.resolveByName("Emma")).thenReturn(makeNameMatches(List.of(emma)));
-
-        service.search("Briefe von Karl an Emma", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().text()).contains("Karl");
-        assertThat(cap.getValue().sender()).isEqualTo(P2);
-    }
-
-    // --- 9. 3+ names all resolve → first two as sender/receiver, third folded into text ---
-
-    @Test
-    void search_threeNamesResolve_extraFoldedIntoText() {
-        Person walter = person(P1, "Walter", "Raddatz");
-        Person emma = person(P2, "Emma", "Raddatz");
-        Person heinrich = person(P3, "Heinrich", "Braun");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Walter", "Emma", "Heinrich"), "any", null, null, List.of()));
-        when(personService.resolveByName("Walter")).thenReturn(makeNameMatches(List.of(walter)));
-        when(personService.resolveByName("Emma")).thenReturn(makeNameMatches(List.of(emma)));
-        when(personService.resolveByName("Heinrich")).thenReturn(makeNameMatches(List.of(heinrich)));
-
-        service.search("Briefe von Walter an Emma über Heinrich", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().sender()).isEqualTo(P1);
-        assertThat(cap.getValue().receiver()).isEqualTo(P2);
-        assertThat(cap.getValue().text()).contains("Heinrich");
-    }
-
-    // --- 10. Keywords space-joined into text ---
-
-    @Test
-    void search_keywords_areJoinedIntoText() {
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Krieg", "Walter")));
-
-        service.search("Dokumente über den Krieg Walter", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().text()).isEqualTo("Krieg Walter");
-    }
-
-    // --- 11. Date range passed through ---
-
-    @Test
-    void search_dateRange_passedIntoSearchFilters() {
-        LocalDate from = LocalDate.of(1914, 1, 1);
-        LocalDate to = LocalDate.of(1914, 12, 31);
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", from, to, List.of()));
-
-        service.search("Briefe aus dem Jahr 1914", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().from()).isEqualTo(from);
-        assertThat(cap.getValue().to()).isEqualTo(to);
-    }
-
-    // --- 12. Null dates → null in SearchFilters (not an error) ---
-
-    @Test
-    void search_nullDates_passedAsNullIntoFilters() {
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Hochzeit")));
-
-        service.search("Hochzeitsbriefe", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().from()).isNull();
-        assertThat(cap.getValue().to()).isNull();
-    }
-
-    // --- 13. Query under 3 chars → VALIDATION_ERROR before Ollama call ---
-
-    @Test
-    void search_queryTooShort_throwsValidationError() {
-        assertThatThrownBy(() -> service.search("ab", PAGE))
-                .isInstanceOf(DomainException.class)
-                .extracting(e -> ((DomainException) e).getCode())
-                .isEqualTo(ErrorCode.VALIDATION_ERROR);
-
-        verify(ollamaClient, never()).parse(anyString());
-    }
-
-    // --- 14. Query over 500 chars → VALIDATION_ERROR ---
-
-    @Test
-    void search_queryTooLong_throwsValidationError() {
-        String longQuery = "a".repeat(501);
-        assertThatThrownBy(() -> service.search(longQuery, PAGE))
-                .isInstanceOf(DomainException.class)
-                .extracting(e -> ((DomainException) e).getCode())
-                .isEqualTo(ErrorCode.VALIDATION_ERROR);
-
-        verify(ollamaClient, never()).parse(anyString());
-    }
-
-    // --- 15. Ollama returns empty names/keywords → raw query used as keyword fallback ---
-
-    @Test
-    void search_ollamaReturnsEmpty_usesRawQueryAsTextFallback() {
-        String raw = "Briefe aus dem Krieg";
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(new OllamaExtraction(List.of(), "any", null, null, List.of(), raw));
-
-        service.search(raw, PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().text()).isEqualTo(raw);
-    }
-
-    // --- 16. Null personNames/keywords from Ollama → no NPE ---
-
-    @Test
-    void search_nullPersonNamesAndKeywords_handledWithoutNpe() {
-        OllamaExtraction ext = new OllamaExtraction(null, "any", null, null, null, "test query");
-        when(ollamaClient.parse(anyString())).thenReturn(ext);
-
-        NlSearchResponse resp = service.search("test query", PAGE);
-
-        assertThat(resp).isNotNull();
-        verify(documentService).searchDocuments(any(), any(), any(), any());
-    }
-
-    // --- 17. Unrecognized personRole → defaults to any-like behavior (no crash) ---
-
-    @Test
-    void search_unrecognizedPersonRole_treatedLikeAny_withSingleResolvedPerson() {
-        Person walter = person(P1, "Walter", "Raddatz");
-        // OllamaClient defensive parsing returns "any" for unknown roles,
-        // but NlQueryParserService must also be safe if something unexpected arrives.
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(new OllamaExtraction(List.of("Walter"), "unknown_role", null, null, List.of(), "query"));
-        when(personService.resolveByName("Walter")).thenReturn(makeNameMatches(List.of(walter)));
-
-        NlSearchResponse resp = service.search("Briefe von Walter", PAGE);
-
-        // Should not crash; "unknown_role" treated as fallback (neither sender nor receiver → any)
-        assertThat(resp).isNotNull();
-    }
-
-    // --- 18. Ollama throws SMART_SEARCH_UNAVAILABLE → propagates to caller ---
-
-    @Test
-    void search_ollamaThrowsUnavailable_propagates() {
-        when(ollamaClient.parse(anyString()))
-                .thenThrow(DomainException.tooManyRequests(ErrorCode.SMART_SEARCH_UNAVAILABLE, "offline"));
-
-        assertThatThrownBy(() -> service.search("Was hat Walter geschrieben?", PAGE))
-                .isInstanceOf(DomainException.class)
-                .extracting(e -> ((DomainException) e).getCode())
-                .isEqualTo(ErrorCode.SMART_SEARCH_UNAVAILABLE);
-    }
-
-    // --- 19. LLM-extracted name > 200 chars → skipped, PersonService never called ---
-
-    @Test
-    void search_nameLongerThan200Chars_isSkippedBeforePersonServiceCall() {
-        String longName = "A".repeat(201);
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(longName), "sender", null, null, List.of()));
-
-        service.search("Briefe von sehr langem Namen", PAGE);
-
-        verify(personService, never()).resolveByName(anyString());
-    }
-
-    // --- 20. Cap lives in resolveByName (after classification): a pre-capped 10-direct result
-    //         maps straight to ambiguousPersons; the search layer adds no second cap. ---
-
-    @Test
-    void search_tenDirectMatches_allShownAsAmbiguous() {
-        List<Person> ten = new ArrayList<>();
-        for (int i = 0; i < 10; i++) {
-            ten.add(person(UUID.randomUUID(), "Walter", "Person" + i));
-        }
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Walter"), "sender", null, null, List.of()));
-        when(personService.resolveByName("Walter")).thenReturn(makeNameMatches(ten));
-
-        NlSearchResponse resp = service.search("Briefe von Walter", PAGE);
-
-        assertThat(resp.interpretation().ambiguousPersons()).hasSize(10);
-        verify(documentService, never()).searchDocuments(any(), any(), any(), any());
-    }
-
-    // --- 21. SearchFilters defaults: tagOperator=AND, status=null, undated=false, tags=empty ---
-
-    @Test
-    void search_searchFiltersDefaults_areCorrect() {
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Krieg")));
-
-        service.search("Dokumente über den Krieg", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), eq(DocumentSort.DATE), eq("desc"), eq(PAGE));
-        SearchFilters f = cap.getValue();
-        assertThat(f.tagOperator()).isEqualTo(TagOperator.AND);
-        assertThat(f.status()).isNull();
-        assertThat(f.undated()).isFalse();
-        assertThat(f.tags()).isEmpty();
-        assertThat(f.tagQ()).isNull();
-    }
-
-    // --- 22. personRole=receiver + 1 resolved → receiver UUID set ---
-
-    @Test
-    void search_personRoleReceiver_singleMatch_setsReceiver() {
-        Person emma = person(P2, "Emma", "Raddatz");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Emma"), "receiver", null, null, List.of()));
-        when(personService.resolveByName("Emma")).thenReturn(makeNameMatches(List.of(emma)));
-
-        service.search("Briefe an Emma", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().receiver()).isEqualTo(P2);
-        assertThat(cap.getValue().sender()).isNull();
-    }
-
-    // --- 23. keywordsApplied=true when text is non-blank ---
-
-    @Test
-    void search_keywordsApplied_trueWhenTextNonBlank() {
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Feldpost")));
-
-        NlSearchResponse resp = service.search("Feldpost aus dem Krieg", PAGE);
-
-        assertThat(resp.interpretation().keywordsApplied()).isTrue();
-    }
-
-    // --- 23a. Partial-only, one candidate → ambiguous (1-item picker), search skipped ---
-
-    @Test
-    void search_partialOnly_oneCandidate_populatesAmbiguous() {
-        Person cramer = person(P1, "Clara", "Cramer");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Clara Cram"), "any", null, null, List.of()));
-        when(personService.resolveByName("Clara Cram")).thenReturn(makeNameMatches(List.of(), List.of(cramer)));
-
-        NlSearchResponse resp = service.search("Briefe von Clara Cram", PAGE);
-
-        assertThat(resp.interpretation().ambiguousPersons()).hasSize(1);
-        verify(documentService, never()).searchDocuments(any(), any(), any(), any());
-    }
-
-    // --- 23b. Partial-only, two candidates → ambiguous (multi-item picker) ---
-
-    @Test
-    void search_partialOnly_twoCandidates_populatesAmbiguous() {
-        Person cramer = person(P1, "Clara", "Cramer");
-        Person crammond = person(P2, "Clara", "Crammond");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Clara Cram"), "any", null, null, List.of()));
-        when(personService.resolveByName("Clara Cram"))
-                .thenReturn(makeNameMatches(List.of(), List.of(cramer, crammond)));
-
-        NlSearchResponse resp = service.search("Briefe von Clara Cram", PAGE);
-
-        assertThat(resp.interpretation().ambiguousPersons()).hasSize(2);
-    }
-
-    // --- 23c. Exactly one direct match → search executes, no picker ---
-
-    @Test
-    void search_oneDirect_executesSearch() {
-        Person clara = person(P1, "Clara", "Cram");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Clara Cram"), "any", null, null, List.of()));
-        when(personService.resolveByName("Clara Cram")).thenReturn(makeNameMatches(List.of(clara)));
-
-        NlSearchResponse resp = service.search("Briefe von Clara Cram", PAGE);
-
-        verify(documentService).searchDocumentsByPersonId(eq(P1), isNull(), isNull(), eq(PAGE));
-        assertThat(resp.interpretation().ambiguousPersons()).isEmpty();
-    }
-
-    // --- Tag resolution helpers ---
-
-    private Tag tag(UUID id, String name) {
-        return Tag.builder().id(id).name(name).build();
-    }
-
-    private Tag tag(UUID id, String name, String color) {
-        return Tag.builder().id(id).name(name).color(color).build();
-    }
-
-    private TagHint tagHint(UUID id, String name, String color) {
-        return new TagHint(id, name, color);
-    }
-
-    private static final UUID T1 = UUID.fromString("00000000-0000-0000-0001-000000000001");
-
-    // --- 24. Single keyword resolves to one tag → tag filter applied ---
-
-    @Test
-    void search_singleKeywordResolvesToTag_appliesTagFilter() {
-        Tag hochzeit = tag(T1, "Hochzeit");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Hochzeit")));
-        when(tagService.findByNameContaining("Hochzeit")).thenReturn(List.of(hochzeit));
-
-        NlSearchResponse resp = service.search("Briefe über Hochzeit", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().tags()).containsExactly("Hochzeit");
-        assertThat(cap.getValue().tagOperator()).isEqualTo(TagOperator.OR);
-        assertThat(resp.interpretation().resolvedTags()).hasSize(1);
-        assertThat(resp.interpretation().resolvedTags().get(0).name()).isEqualTo("Hochzeit");
-        assertThat(resp.interpretation().tagsApplied()).isTrue();
-        assertThat(cap.getValue().text()).isNull();
-    }
-
-    private static final UUID T2 = UUID.fromString("00000000-0000-0000-0001-000000000002");
-
-    // --- 25. Keyword matches multiple tags → all in resolvedTags, OR-union ---
-
-    @Test
-    void search_keywordMatchesMultipleTags_allIncluded() {
-        Tag hochzeit1 = tag(T1, "Hochzeit Raddatz");
-        Tag hochzeit2 = tag(T2, "Hochzeit Braun");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Hochzeit")));
-        when(tagService.findByNameContaining("Hochzeit")).thenReturn(List.of(hochzeit1, hochzeit2));
-
-        NlSearchResponse resp = service.search("Briefe über Hochzeit", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().tags()).containsExactlyInAnyOrder("Hochzeit Raddatz", "Hochzeit Braun");
-        assertThat(cap.getValue().tagOperator()).isEqualTo(TagOperator.OR);
-        assertThat(resp.interpretation().resolvedTags()).hasSize(2);
-    }
-
-    // --- 26. Keyword no tag match → stays as FTS text, resolvedTags empty ---
-
-    @Test
-    void search_keywordNoTagMatch_staysAsFtsText() {
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Feldpost")));
-
-        NlSearchResponse resp = service.search("Feldpost Briefe", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().text()).contains("Feldpost");
-        assertThat(cap.getValue().tags()).isEmpty();
-        assertThat(resp.interpretation().resolvedTags()).isEmpty();
-        assertThat(resp.interpretation().tagsApplied()).isFalse();
-    }
-
-    // --- 27. Mixed: one keyword resolves, one doesn't → tag filter + FTS text ---
-
-    @Test
-    void search_mixedKeywords_oneResolves_oneStaysAsText() {
-        Tag hochzeit = tag(T1, "Hochzeit");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Hochzeit", "Feldpost")));
-        when(tagService.findByNameContaining("Hochzeit")).thenReturn(List.of(hochzeit));
-
-        NlSearchResponse resp = service.search("Hochzeit und Feldpost", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().tags()).containsExactly("Hochzeit");
-        assertThat(cap.getValue().tagOperator()).isEqualTo(TagOperator.OR);
-        assertThat(cap.getValue().text()).contains("Feldpost");
-        assertThat(resp.interpretation().resolvedTags()).hasSize(1);
-        assertThat(resp.interpretation().tagsApplied()).isTrue();
-    }
-
-    // --- 28. personRole=any + 1 person + resolvable keyword → personId search, tagsApplied=false ---
-
-    @Test
-    void search_personRoleAny_singlePerson_resolvableKeyword_tagsAppliedFalse() {
-        Person walter = person(P1, "Walter", "Raddatz");
-        Tag hochzeit = tag(T1, "Hochzeit");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of("Walter"), "any", null, null, List.of("Hochzeit")));
-        when(personService.resolveByName("Walter")).thenReturn(makeNameMatches(List.of(walter)));
-        when(tagService.findByNameContaining("Hochzeit")).thenReturn(List.of(hochzeit));
-
-        NlSearchResponse resp = service.search("Briefe von Walter über Hochzeit", PAGE);
-
-        verify(documentService).searchDocumentsByPersonId(eq(P1), isNull(), isNull(), eq(PAGE));
-        verify(documentService, never()).searchDocuments(any(), any(), any(), any());
-        assertThat(resp.interpretation().tagsApplied()).isFalse();
-        assertThat(resp.interpretation().resolvedTags()).hasSize(1);
-        assertThat(resp.interpretation().resolvedTags().get(0).name()).isEqualTo("Hochzeit");
-    }
-
-    // --- 29. Cap: keyword matches > 10 tags → capped at 10 ---
-
-    @Test
-    void search_keywordMatchesMoreThanMaxTags_cappedAtTen() {
-        List<Tag> eleven = new ArrayList<>();
-        for (int i = 0; i < 11; i++) {
-            eleven.add(tag(UUID.randomUUID(), "Thema " + i));
-        }
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Thema")));
-        when(tagService.findByNameContaining("Thema")).thenReturn(eleven);
-
-        NlSearchResponse resp = service.search("Dokumente zum Thema", PAGE);
-
-        assertThat(resp.interpretation().resolvedTags()).hasSize(10);
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().tags()).hasSize(10);
-    }
-
-    // --- 30. Short keyword (< 3 chars) → skipped, not passed to TagService ---
-
-    @Test
-    void search_shortKeyword_skippedByTagResolution() {
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("ab", "Krieg")));
-
-        service.search("ab Krieg", PAGE);
-
-        verify(tagService, never()).findByNameContaining("ab");
-        verify(tagService).findByNameContaining("Krieg");
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().text()).contains("ab");
-    }
-
-    // --- 31. Dedup: same tag matched by two keywords → appears once ---
-
-    @Test
-    void search_sameTagMatchedByTwoKeywords_deduplicatedToOne() {
-        Tag hochzeit = tag(T1, "Hochzeit");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Hochzeit", "hoch")));
-        when(tagService.findByNameContaining("Hochzeit")).thenReturn(List.of(hochzeit));
-        when(tagService.findByNameContaining("hoch")).thenReturn(List.of(hochzeit));
-
-        NlSearchResponse resp = service.search("Hochzeit hoch", PAGE);
-
-        assertThat(resp.interpretation().resolvedTags()).hasSize(1);
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().tags()).hasSize(1);
-    }
-
-    // --- 32. All keywords resolve → rawQuery fallback suppressed, text=null ---
-
-    @Test
-    void search_allKeywordsResolveToTags_rawQueryFallbackSuppressed() {
-        Tag hochzeit = tag(T1, "Hochzeit");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(new OllamaExtraction(List.of(), "any", null, null, List.of("Hochzeit"), "raw query text"));
-        when(tagService.findByNameContaining("Hochzeit")).thenReturn(List.of(hochzeit));
-
-        NlSearchResponse resp = service.search("Hochzeit", PAGE);
-
-        ArgumentCaptor<SearchFilters> cap = ArgumentCaptor.forClass(SearchFilters.class);
-        verify(documentService).searchDocuments(cap.capture(), any(), any(), any());
-        assertThat(cap.getValue().text()).isNull();
-        assertThat(cap.getValue().tags()).containsExactly("Hochzeit");
-    }
-
-    // --- 33. Flag independence: keywordsApplied=false AND tagsApplied=true ---
-
-    @Test
-    void search_allKeywordsResolveToTags_keywordsAppliedFalse_tagsAppliedTrue() {
-        Tag hochzeit = tag(T1, "Hochzeit");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Hochzeit")));
-        when(tagService.findByNameContaining("Hochzeit")).thenReturn(List.of(hochzeit));
-
-        NlSearchResponse resp = service.search("Hochzeit Briefe", PAGE);
-
-        assertThat(resp.interpretation().keywordsApplied()).isFalse();
-        assertThat(resp.interpretation().tagsApplied()).isTrue();
-    }
-
-    // --- 34. Color carried through from resolveEffectiveColors ---
-
-    @Test
-    void search_tagHint_carriesColorSetByResolveEffectiveColors() {
-        Tag hochzeit = tag(T1, "Hochzeit");
-        doAnswer(invocation -> {
-            Collection<Tag> tags = invocation.getArgument(0);
-            tags.forEach(t -> t.setColor("sage"));
-            return null;
-        }).when(tagService).resolveEffectiveColors(any());
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Hochzeit")));
-        when(tagService.findByNameContaining("Hochzeit")).thenReturn(List.of(hochzeit));
-
-        NlSearchResponse resp = service.search("Hochzeit", PAGE);
-
-        assertThat(resp.interpretation().resolvedTags().get(0).color()).isEqualTo("sage");
-    }
-
-    // --- 35. Color stays null when resolveEffectiveColors leaves it unset ---
-
-    @Test
-    void search_tagHint_colorIsNull_whenNoColorResolved() {
-        Tag hochzeit = tag(T1, "Hochzeit");
-        when(ollamaClient.parse(anyString()))
-                .thenReturn(extraction(List.of(), "any", null, null, List.of("Hochzeit")));
-        when(tagService.findByNameContaining("Hochzeit")).thenReturn(List.of(hochzeit));
-
-        NlSearchResponse resp = service.search("Hochzeit", PAGE);
-
-        assertThat(resp.interpretation().resolvedTags().get(0).color()).isNull();
-    }
-}

backend/src/test/java/org/raddatz/familienarchiv/search/NlSearchControllerTest.java

@@ -1,161 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import tools.jackson.databind.ObjectMapper;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-import org.raddatz.familienarchiv.document.DocumentSearchResult;
-import org.raddatz.familienarchiv.exception.DomainException;
-import org.raddatz.familienarchiv.exception.ErrorCode;
-import org.raddatz.familienarchiv.security.SecurityConfig;
-import org.raddatz.familienarchiv.security.PermissionAspect;
-import org.raddatz.familienarchiv.user.CustomUserDetailsService;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
-import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
-import org.springframework.context.annotation.Import;
-import org.springframework.http.MediaType;
-import org.springframework.security.test.context.support.WithMockUser;
-import org.springframework.test.context.bean.override.mockito.MockitoBean;
-import org.springframework.test.web.servlet.MockMvc;
-
-import java.util.List;
-import java.util.UUID;
-
-import static org.mockito.ArgumentMatchers.*;
-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.post;
-import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
-
-@WebMvcTest(NlSearchController.class)
-@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class,
-        NlSearchRateLimiter.class, NlSearchRateLimitProperties.class})
-class NlSearchControllerTest {
-
-    @Autowired MockMvc mockMvc;
-    private final ObjectMapper objectMapper = new ObjectMapper();
-
-    @MockitoBean NlQueryParserService nlQueryParserService;
-    @MockitoBean CustomUserDetailsService customUserDetailsService;
-    @Autowired NlSearchRateLimiter rateLimiter;
-
-    @BeforeEach
-    void resetRateLimiter() {
-        rateLimiter.resetForTest();
-    }
-
-    private NlSearchResponse makeResponse() {
-        PersonHint hint = new PersonHint(UUID.randomUUID(), "Walter Raddatz");
-        NlQueryInterpretation interp = new NlQueryInterpretation(
-                List.of(hint), List.of(), null, null,
-                List.of("Krieg"), List.of(), "Briefe von Walter im Krieg", true, false);
-        return new NlSearchResponse(DocumentSearchResult.of(List.of()), interp);
-    }
-
-    // --- 1. Happy path ---
-
-    @Test
-    @WithMockUser(username = "user@test.com", authorities = {"READ_ALL"})
-    void search_returns200_withNlSearchResponse() throws Exception {
-        when(nlQueryParserService.search(anyString(), any())).thenReturn(makeResponse());
-
-        mockMvc.perform(post("/api/search/nl").with(csrf())
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content("{\"query\":\"Briefe von Walter im Krieg\"}"))
-                .andExpect(status().isOk())
-                .andExpect(jsonPath("$.interpretation.rawQuery").value("Briefe von Walter im Krieg"))
-                .andExpect(jsonPath("$.interpretation.resolvedPersons[0].displayName").value("Walter Raddatz"))
-                .andExpect(jsonPath("$.interpretation.keywordsApplied").value(true));
-    }
-
-    // --- 2. ambiguousPersons in response shape ---
-
-    @Test
-    @WithMockUser(username = "user@test.com", authorities = {"READ_ALL"})
-    void search_returns200_withAmbiguousPersons() throws Exception {
-        PersonHint a = new PersonHint(UUID.randomUUID(), "Walter Braun");
-        PersonHint b = new PersonHint(UUID.randomUUID(), "Walter Schmidt");
-        NlQueryInterpretation interp = new NlQueryInterpretation(
-                List.of(), List.of(a, b), null, null,
-                List.of(), List.of(), "Briefe von Walter", false, false);
-        NlSearchResponse resp = new NlSearchResponse(DocumentSearchResult.of(List.of()), interp);
-        when(nlQueryParserService.search(anyString(), any())).thenReturn(resp);
-
-        mockMvc.perform(post("/api/search/nl").with(csrf())
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content("{\"query\":\"Briefe von Walter\"}"))
-                .andExpect(status().isOk())
-                .andExpect(jsonPath("$.interpretation.ambiguousPersons").isArray())
-                .andExpect(jsonPath("$.interpretation.ambiguousPersons[0].displayName").value("Walter Braun"))
-                .andExpect(jsonPath("$.interpretation.ambiguousPersons[1].id").isNotEmpty());
-    }
-
-    // --- 3. Unauthenticated → 401 ---
-
-    @Test
-    void search_returns401_whenUnauthenticated() throws Exception {
-        mockMvc.perform(post("/api/search/nl").with(csrf())
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content("{\"query\":\"Briefe von Walter\"}"))
-                .andExpect(status().isUnauthorized());
-    }
-
-    // --- 4. Query < 3 chars → 400 ---
-
-    @Test
-    @WithMockUser(username = "user@test.com", authorities = {"READ_ALL"})
-    void search_returns400_whenQueryTooShort() throws Exception {
-        mockMvc.perform(post("/api/search/nl").with(csrf())
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content("{\"query\":\"ab\"}"))
-                .andExpect(status().isBadRequest());
-    }
-
-    // --- 5. Query > 500 chars → 400 ---
-
-    @Test
-    @WithMockUser(username = "user@test.com", authorities = {"READ_ALL"})
-    void search_returns400_whenQueryTooLong() throws Exception {
-        String longQuery = "a".repeat(501);
-        mockMvc.perform(post("/api/search/nl").with(csrf())
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content("{\"query\":\"" + longQuery + "\"}"))
-                .andExpect(status().isBadRequest());
-    }
-
-    // --- 6. Ollama unavailable → 503 ---
-
-    @Test
-    @WithMockUser(username = "user@test.com", authorities = {"READ_ALL"})
-    void search_returns503_whenOllamaUnavailable() throws Exception {
-        when(nlQueryParserService.search(anyString(), any()))
-                .thenThrow(DomainException.serviceUnavailable(ErrorCode.SMART_SEARCH_UNAVAILABLE, "Ollama offline"));
-
-        mockMvc.perform(post("/api/search/nl").with(csrf())
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content("{\"query\":\"Briefe von Walter\"}"))
-                .andExpect(status().isServiceUnavailable())
-                .andExpect(jsonPath("$.code").value("SMART_SEARCH_UNAVAILABLE"));
-    }
-
-    // --- 7. 6th request in 1 minute → 429 ---
-
-    @Test
-    @WithMockUser(username = "user@test.com", authorities = {"READ_ALL"})
-    void search_returns429_onSixthRequestWithinRateLimit() throws Exception {
-        when(nlQueryParserService.search(anyString(), any())).thenReturn(makeResponse());
-
-        for (int i = 0; i < 5; i++) {
-            mockMvc.perform(post("/api/search/nl").with(csrf())
-                            .contentType(MediaType.APPLICATION_JSON)
-                            .content("{\"query\":\"Briefe von Walter\"}"))
-                    .andExpect(status().isOk());
-        }
-
-        mockMvc.perform(post("/api/search/nl").with(csrf())
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content("{\"query\":\"Briefe von Walter\"}"))
-                .andExpect(status().isTooManyRequests())
-                .andExpect(jsonPath("$.code").value("SMART_SEARCH_RATE_LIMITED"));
-    }
-}

backend/src/test/java/org/raddatz/familienarchiv/search/NlSearchRateLimiterTest.java

@@ -1,62 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-import org.raddatz.familienarchiv.exception.DomainException;
-import org.raddatz.familienarchiv.exception.ErrorCode;
-
-import static org.assertj.core.api.Assertions.assertThatCode;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
-class NlSearchRateLimiterTest {
-
-    private NlSearchRateLimiter rateLimiter;
-
-    @BeforeEach
-    void setUp() {
-        NlSearchRateLimitProperties props = new NlSearchRateLimitProperties();
-        props.setMaxRequestsPerMinute(5);
-        rateLimiter = new NlSearchRateLimiter(props);
-    }
-
-    @Test
-    void checkAndConsume_allowsRequestsWithinLimit() {
-        for (int i = 0; i < 5; i++) {
-            assertThatCode(() -> rateLimiter.checkAndConsume("user@example.com"))
-                    .doesNotThrowAnyException();
-        }
-    }
-
-    @Test
-    void checkAndConsume_throwsRateLimited_onSixthRequest() {
-        for (int i = 0; i < 5; i++) {
-            rateLimiter.checkAndConsume("user@example.com");
-        }
-
-        assertThatThrownBy(() -> rateLimiter.checkAndConsume("user@example.com"))
-                .isInstanceOf(DomainException.class)
-                .extracting(e -> ((DomainException) e).getCode())
-                .isEqualTo(ErrorCode.SMART_SEARCH_RATE_LIMITED);
-    }
-
-    @Test
-    void checkAndConsume_limitsAreIndependentPerUser() {
-        for (int i = 0; i < 5; i++) {
-            rateLimiter.checkAndConsume("alice@example.com");
-        }
-        assertThatCode(() -> rateLimiter.checkAndConsume("bob@example.com"))
-                .doesNotThrowAnyException();
-    }
-
-    @Test
-    void resetForTest_clearsAllBuckets() {
-        for (int i = 0; i < 5; i++) {
-            rateLimiter.checkAndConsume("user@example.com");
-        }
-
-        rateLimiter.resetForTest();
-
-        assertThatCode(() -> rateLimiter.checkAndConsume("user@example.com"))
-                .doesNotThrowAnyException();
-    }
-}

backend/src/test/java/org/raddatz/familienarchiv/search/NlSearchTagResolutionIntegrationTest.java

@@ -1,56 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import org.junit.jupiter.api.Test;
-import org.raddatz.familienarchiv.PostgresContainerConfig;
-import org.raddatz.familienarchiv.config.FlywayConfig;
-import org.raddatz.familienarchiv.tag.Tag;
-import org.raddatz.familienarchiv.tag.TagRepository;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
-import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
-import org.springframework.context.annotation.Import;
-
-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 NlSearchTagResolutionIntegrationTest {
-
-    @Autowired
-    private TagRepository tagRepository;
-
-    @Test
-    void findDescendantIdsByName_parentName_includesChildId() {
-        Tag parent = tagRepository.save(Tag.builder().name("Krieg").build());
-        Tag child = tagRepository.save(Tag.builder().name("Weltkrieg").parentId(parent.getId()).build());
-
-        List<UUID> ids = tagRepository.findDescendantIdsByName("Krieg");
-
-        assertThat(ids).containsExactlyInAnyOrder(parent.getId(), child.getId());
-    }
-
-    @Test
-    void findDescendantIdsByName_childName_returnsOnlyChild() {
-        Tag parent = tagRepository.save(Tag.builder().name("Krieg").build());
-        Tag child = tagRepository.save(Tag.builder().name("Weltkrieg").parentId(parent.getId()).build());
-
-        List<UUID> ids = tagRepository.findDescendantIdsByName("Weltkrieg");
-
-        assertThat(ids).containsExactly(child.getId());
-        assertThat(ids).doesNotContain(parent.getId());
-    }
-
-    @Test
-    void findByNameContainingIgnoreCase_parentSubstring_matchesParentOnly() {
-        Tag parent = tagRepository.save(Tag.builder().name("Krieg").build());
-        tagRepository.save(Tag.builder().name("Weltkrieg").parentId(parent.getId()).build());
-
-        List<Tag> found = tagRepository.findByNameContainingIgnoreCase("Krieg");
-
-        assertThat(found).extracting(Tag::getName).containsExactlyInAnyOrder("Krieg", "Weltkrieg");
-    }
-}

backend/src/test/java/org/raddatz/familienarchiv/search/RestClientOllamaClientTest.java

@@ -1,113 +0,0 @@
-package org.raddatz.familienarchiv.search;
-
-import com.github.tomakehurst.wiremock.WireMockServer;
-import com.github.tomakehurst.wiremock.core.WireMockConfiguration;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-import org.raddatz.familienarchiv.exception.DomainException;
-import org.raddatz.familienarchiv.exception.ErrorCode;
-
-import static com.github.tomakehurst.wiremock.client.WireMock.*;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
-class RestClientOllamaClientTest {
-
-    private WireMockServer wireMock;
-    private RestClientOllamaClient client;
-
-    @BeforeEach
-    void setUp() {
-        wireMock = new WireMockServer(WireMockConfiguration.wireMockConfig().dynamicPort());
-        wireMock.start();
-
-        OllamaProperties props = new OllamaProperties();
-        props.setBaseUrl("http://localhost:" + wireMock.port());
-        props.setModel("qwen2.5:7b-instruct-q4_K_M");
-        props.setTimeoutSeconds(5);
-        props.setHealthCheckTimeoutSeconds(2);
-
-        client = new RestClientOllamaClient(props);
-    }
-
-    @AfterEach
-    void tearDown() {
-        wireMock.stop();
-    }
-
-    // --- Factory helpers ---
-
-    private String makeOllamaResponseJson(String personNamesJson, String personRole,
-                                           String dateFrom, String dateTo, String keywordsJson) {
-        String inner = String.format(
-                "{\"personNames\":%s,\"personRole\":\"%s\",\"dateFrom\":%s,\"dateTo\":%s,\"keywords\":%s}",
-                personNamesJson, personRole,
-                dateFrom == null ? "null" : "\"" + dateFrom + "\"",
-                dateTo == null ? "null" : "\"" + dateTo + "\"",
-                keywordsJson
-        );
-        return String.format("{\"model\":\"qwen2.5:7b-instruct-q4_K_M\",\"response\":\"%s\",\"done\":true}",
-                inner.replace("\"", "\\\""));
-    }
-
-    // --- Test cases ---
-
-    @Test
-    void parse_returnsExtraction_whenOllamaReturnsValidJson() {
-        String body = makeOllamaResponseJson("[\"Walter\"]", "sender", "1914-01-01", "1914-12-31", "[\"Krieg\"]");
-        wireMock.stubFor(post(urlEqualTo("/api/generate"))
-                .willReturn(aResponse()
-                        .withStatus(200)
-                        .withHeader("Content-Type", "application/json")
-                        .withBody(body)));
-
-        OllamaExtraction result = client.parse("Was hat Walter im Krieg geschrieben?");
-
-        assertThat(result.personNames()).containsExactly("Walter");
-        assertThat(result.personRole()).isEqualTo("sender");
-        assertThat(result.keywords()).containsExactly("Krieg");
-        assertThat(result.dateFrom()).isNotNull();
-        assertThat(result.dateTo()).isNotNull();
-    }
-
-    @Test
-    void parse_throwsSmartSearchUnavailable_whenOllamaReturns500() {
-        wireMock.stubFor(post(urlEqualTo("/api/generate"))
-                .willReturn(aResponse().withStatus(500)));
-
-        assertThatThrownBy(() -> client.parse("some query"))
-                .isInstanceOf(DomainException.class)
-                .extracting(e -> ((DomainException) e).getCode())
-                .isEqualTo(ErrorCode.SMART_SEARCH_UNAVAILABLE);
-    }
-
-    @Test
-    void parse_throwsSmartSearchUnavailable_whenOllamaExceedsTimeout() {
-        wireMock.stubFor(post(urlEqualTo("/api/generate"))
-                .willReturn(aResponse()
-                        .withStatus(200)
-                        .withHeader("Content-Type", "application/json")
-                        .withFixedDelay(6000)
-                        .withBody("{\"response\":\"{}\",\"done\":true}")));
-
-        assertThatThrownBy(() -> client.parse("some query"))
-                .isInstanceOf(DomainException.class)
-                .extracting(e -> ((DomainException) e).getCode())
-                .isEqualTo(ErrorCode.SMART_SEARCH_UNAVAILABLE);
-    }
-
-    @Test
-    void parse_throwsSmartSearchUnavailable_whenOllamaReturnsMalformedJson() {
-        wireMock.stubFor(post(urlEqualTo("/api/generate"))
-                .willReturn(aResponse()
-                        .withStatus(200)
-                        .withHeader("Content-Type", "application/json")
-                        .withBody("{\"response\":\"not-json-at-all\",\"done\":true}")));
-
-        assertThatThrownBy(() -> client.parse("some query"))
-                .isInstanceOf(DomainException.class)
-                .extracting(e -> ((DomainException) e).getCode())
-                .isEqualTo(ErrorCode.SMART_SEARCH_UNAVAILABLE);
-    }
-}

docker-compose.prod.yml

@@ -50,7 +50,6 @@ volumes:
   minio-data:
   ocr-models:
   ocr-cache:
-  ollama-models:
 
 services:
   db:
@@ -201,73 +200,6 @@ services:
     security_opt:
       - no-new-privileges:true
 
-  # --- Ollama: Model init (one-shot pull) ---
-  # Pulls qwen2.5:7b-instruct-q4_K_M (~4.7 GB) into the ollama-models volume on
-  # first start; exits quickly on subsequent starts (model already cached).
-  # The ollama/ollama image's ENTRYPOINT is `ollama` and the image ships WITHOUT
-  # curl, so the entrypoint is overridden to a shell and readiness is probed with
-  # `ollama list` (not curl). The pull is guarded by a `grep` on the cached model
-  # list so a model already on the volume exits clean WITHOUT a registry round-trip
-  # — a host reboot during a registry/network blip can no longer fail init (which
-  # would block the ollama service via service_completed_successfully).
-  # Backend degrades gracefully (503) if Ollama is absent.
-  ollama-model-init:
-    image: ollama/ollama:0.30.6
-    restart: "no"
-    entrypoint: ["/bin/sh", "-c"]
-    command:
-      - "ollama serve & until ollama list >/dev/null 2>&1; do sleep 1; done && (ollama list | grep -q 'qwen2.5:7b-instruct-q4_K_M' || ollama pull qwen2.5:7b-instruct-q4_K_M)"
-    networks:
-      - archiv-net
-    volumes:
-      - ollama-models:/root/.ollama
-    mem_limit: 2g
-    read_only: true
-    tmpfs:
-      - /tmp:size=512m
-    cap_drop:
-      - ALL
-    security_opt:
-      - no-new-privileges:true
-
-  # --- Ollama: LLM inference server ---
-  # Serves the pre-pulled model for NL search inference. Backend reaches it at
-  # http://ollama:11434 (application.yaml default; no env override required).
-  # Healthcheck uses `ollama list` because the image has no curl.
-  ollama:
-    image: ollama/ollama:0.30.6
-    restart: unless-stopped
-    expose:
-      - "11434"
-    networks:
-      - archiv-net
-    volumes:
-      - ollama-models:/root/.ollama
-    environment:
-      # Pin the model in memory (no idle unload). Without this, Ollama evicts
-      # the model after ~5 min idle and the next query pays a cold-load penalty
-      # that exceeds the backend read timeout → NL search 503 after idle.
-      OLLAMA_KEEP_ALIVE: "-1"
-    cpus: "${OLLAMA_CPU_LIMIT:-4.0}"
-    mem_limit: "${OLLAMA_MEM_LIMIT:-8g}"
-    memswap_limit: "${OLLAMA_MEM_LIMIT:-8g}"
-    read_only: true
-    tmpfs:
-      - /tmp:size=512m
-    cap_drop:
-      - ALL
-    security_opt:
-      - no-new-privileges:true
-    healthcheck:
-      test: ["CMD", "ollama", "list"]
-      interval: 30s
-      timeout: 10s
-      retries: 5
-      start_period: 60s
-    depends_on:
-      ollama-model-init:
-        condition: service_completed_successfully
-
   backend:
     image: familienarchiv/backend:${TAG:-nightly}
     build:

docker-compose.yml

@@ -141,75 +141,6 @@ services:
     security_opt:
       - no-new-privileges:true
 
-  # --- Ollama: Model init (one-shot pull) ---
-  # Pulls qwen2.5:7b-instruct-q4_K_M (~4.7 GB) into the ollama_models volume on first start.
-  # On subsequent starts (model already in volume), exits quickly without re-downloading.
-  # Not started in CI — CI uses explicit service selection
-  # (docker-compose.ci.yml: db minio create-buckets)
-  ollama-model-init:
-    image: ollama/ollama:0.30.6
-    restart: "no"
-    networks:
-      - archiv-net
-    volumes:
-      - ollama_models:/root/.ollama
-    mem_limit: 2g
-    read_only: true
-    tmpfs:
-      - /tmp:size=512m
-    cap_drop:
-      - ALL
-    security_opt:
-      - no-new-privileges:true
-    # The image ENTRYPOINT is `ollama`, so override it to a shell; the image has
-    # no curl, so readiness is probed with `ollama list` instead of a curl loop.
-    # The pull is guarded by a `grep` on the cached model list so an already-cached
-    # model exits clean without a registry round-trip (offline-safe re-up).
-    entrypoint: ["/bin/sh", "-c"]
-    command:
-      - "ollama serve & until ollama list >/dev/null 2>&1; do sleep 1; done && (ollama list | grep -q 'qwen2.5:7b-instruct-q4_K_M' || ollama pull qwen2.5:7b-instruct-q4_K_M)"
-
-  # --- Ollama: LLM inference server ---
-  # Serves the pre-pulled model for NL search inference.
-  # Not started in CI — CI uses explicit service selection
-  # (docker-compose.ci.yml: db minio create-buckets)
-  ollama:
-    image: ollama/ollama:0.30.6
-    container_name: archive-ollama
-    restart: unless-stopped
-    expose:
-      - "11434"
-    networks:
-      - archiv-net
-    volumes:
-      - ollama_models:/root/.ollama
-    environment:
-      OLLAMA_API_KEY: "${OLLAMA_API_KEY}"
-      # Pin the model in memory (no idle unload) so queries never pay a cold-load
-      # penalty that exceeds the backend read timeout → NL search 503 after idle.
-      OLLAMA_KEEP_ALIVE: "-1"
-    cpus: "${OLLAMA_CPU_LIMIT:-4.0}"
-    mem_limit: "${OLLAMA_MEM_LIMIT:-8g}"
-    memswap_limit: "${OLLAMA_MEM_LIMIT:-8g}"
-    read_only: true
-    tmpfs:
-      - /tmp:size=512m
-    cap_drop:
-      - ALL
-    security_opt:
-      - no-new-privileges:true
-    healthcheck:
-      # `ollama list` hits the local API and exits non-zero if the server is
-      # down — used instead of curl, which the image does not ship.
-      test: ["CMD", "ollama", "list"]
-      interval: 30s
-      timeout: 10s
-      retries: 5
-      start_period: 60s  # model weights are pre-loaded by ollama-model-init; service only needs to bind port
-    depends_on:
-      ollama-model-init:
-        condition: service_completed_successfully
-
   # --- Backend: Spring Boot ---
   backend:
     build:
@@ -253,8 +184,6 @@ services:
       SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE: ${MAIL_STARTTLS_ENABLE:-false}
       APP_OCR_BASE_URL: http://ocr-service:8000
       APP_OCR_TRAINING_TOKEN: "${OCR_TRAINING_TOKEN:-}"
-      APP_OLLAMA_BASE_URL: "${APP_OLLAMA_BASE_URL:-http://ollama:11434}"
-      APP_OLLAMA_API_KEY: "${OLLAMA_API_KEY}"
       SENTRY_DSN: ${SENTRY_DSN:-}
       SENTRY_TRACES_SAMPLE_RATE: ${SENTRY_TRACES_SAMPLE_RATE:-1.0}
       # Observability: send traces to Tempo inside archiv-net (OTLP gRPC port 4317)
@@ -318,4 +247,3 @@ volumes:
   frontend_node_modules:
   ocr_models:
   ocr_cache:
-  ollama_models:

docs/ARCHITECTURE.md

@@ -38,7 +38,7 @@ Both stacks are organised **package-by-domain**: each domain owns its entities,
 
 **`user`** — login accounts and permission groups. Owns `AppUser`, `UserGroup`, invite tokens. Does NOT own `Person` records. Cross-domain deps: `audit` (user management events).
 
-**`geschichte`** — family stories. Owns `Geschichte` (`DRAFT → PUBLISHED` lifecycle). Cross-domain deps: `person`, `document` (linked entities in the story body).
+**`geschichte`** — family stories and Lesereisen. Owns `Geschichte` (`DRAFT → PUBLISHED` lifecycle) and `JourneyItem` (ordered stops in a JOURNEY-type Geschichte). Two subtypes: `STORY` (prose) and `JOURNEY` (curated document sequence). Cross-domain deps: `person` (linked persons), `document` (via `JourneyItem.document_id`, ON DELETE SET NULL).
 
 **`notification`** — in-app messages. Owns `Notification`. Delivers via `SseEmitterRegistry` (live) and persisted rows (bell dropdown). Cross-domain deps: `user` (recipient), `document` (context).
 
@@ -61,7 +61,7 @@ Members of the cross-cutting layer have no entity of their own, no user-facing C
 | `audit` | Append-only event store (`audit_log`) for all domain mutations. Feeds the activity feed and Family Pulse dashboard. | Consumed by 5+ domains; no user-facing CRUD of its own |
 | `config` | Infrastructure bean definitions: `MinioConfig`, `AsyncConfig`, `WebConfig` | Framework infra; no business logic |
 | `dashboard` | Stats aggregation for the admin dashboard and Family Pulse widget | Aggregates from 3+ domains; no owned entities |
-| `exception` | `DomainException`, `ErrorCode` enum, `GlobalExceptionHandler` | Framework infra; consumed by every controller and service. Adding a new `ErrorCode` requires matching updates in `frontend/src/lib/shared/errors.ts` and all three `messages/*.json` locale files. Current security-related codes: `CSRF_TOKEN_MISSING` (403 on mutating request without valid `X-XSRF-TOKEN` header), `TOO_MANY_LOGIN_ATTEMPTS` (429 when login rate limit exceeded). |
+| `exception` | `DomainException`, `ErrorCode` enum, `GlobalExceptionHandler` | Framework infra; consumed by every controller and service. Adding a new `ErrorCode` requires matching updates in `frontend/src/lib/shared/errors.ts` and all three `messages/*.json` locale files. Current security-related codes: `CSRF_TOKEN_MISSING` (403 on mutating request without valid `X-XSRF-TOKEN` header), `TOO_MANY_LOGIN_ATTEMPTS` (429 when login rate limit exceeded). Journey/geschichte domain codes: `JOURNEY_ITEM_NOT_IN_JOURNEY`, `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`. |
 | `filestorage` | `FileService` — MinIO/S3 upload, download, presigned-URL generation | Generic service; consumed by `document` and `ocr` |
 | `importing` | `CanonicalImportOrchestrator` — async canonical import running four idempotent loaders (`TagTreeImporter` → `PersonRegisterImporter` → `PersonTreeImporter` → `DocumentImporter`) over the normalizer's committed canonical artifacts (`canonical-*.xlsx` + `canonical-persons-tree.json`) | Orchestrates across `person`, `tag`, `document` |
 | `security` | `SecurityConfig`, `Permission` enum, `@RequirePermission` annotation, `PermissionAspect` (AOP) | Framework infra; enforced globally across all controllers |

docs/DEPLOYMENT.md

@@ -50,17 +50,15 @@ graph TD
 
 The OCR service requires significant RAM for model loading. The dev compose sets `mem_limit: 12g`.
 
-| Production target | RAM | Recommended OCR limit | NL Search | Notes |
-|---|---|---|---|---|
-| Current server (Hetzner Serverbörse, i7-6700) | 64 GB | 12 GB | Supported | Default `mem_limit: 12g` works comfortably; plenty of headroom for Ollama |
-| ≥ 16 GB RAM | 16+ GB | 12 GB | Supported | Default works |
-| 8 GB RAM | 8 GB | 6 GB | Disabled — set `APP_OLLAMA_BASE_URL=` (empty) | Set `OCR_MEM_LIMIT=6g`; accept reduced batch sizes |
-| 4 GB RAM | 4 GB | — | Unsupported | Disable OCR service (`profiles: [ocr]`); run OCR on demand only |
+| Production target | RAM | Recommended OCR limit | Notes |
+|---|---|---|---|
+| Current server (Hetzner Serverbörse, i7-6700) | 64 GB | 12 GB | Default `mem_limit: 12g` works comfortably |
+| ≥ 16 GB RAM | 16+ GB | 12 GB | Default works |
+| 8 GB RAM | 8 GB | 6 GB | Set `OCR_MEM_LIMIT=6g`; accept reduced batch sizes |
+| 4 GB RAM | 4 GB | — | Disable OCR service (`profiles: [ocr]`); run OCR on demand only |
 
 On servers with less than 16 GB RAM the default `mem_limit: 12g` cannot be honoured — set the `OCR_MEM_LIMIT` env var (in `.env.production` / `.env.staging`, or as a Gitea secret consumed by the workflow). The prod compose interpolates this var with a 12g default.
 
-> **Memory budget:** OCR (~6 GB active) + Ollama (~8 GB) = ~14 GB. On servers with less than 16 GB RAM, do not run `docker-compose.observability.yml` continuously alongside both OCR and Ollama.
-
 ### Dev vs production differences
 
 | Concern | Dev (`docker-compose.yml`) | Prod (`docker-compose.prod.yml`) |
@@ -147,16 +145,6 @@ All vars are set in `.env` at the repo root (copy from `.env.example`). The back
 | `XDG_CACHE_HOME` | XDG cache base dir — redirects Matplotlib and other XDG-aware libraries away from the read-only `HOME` (`/home/ocr`) to the writable cache volume | `/app/cache` | — | — |
 | `TORCH_HOME` | PyTorch model cache — redirects `~/.cache/torch` to the writable models volume | `/app/models/torch` | — | — |
 
-### Ollama (NL search) service
-
-| Variable | Purpose | Default | Required? | Sensitive? |
-|---|---|---|---|---|
-| `APP_OLLAMA_BASE_URL` | Base URL for the Ollama service. Leave empty to disable NL search. | `http://ollama:11434` | — | — |
-| `APP_OLLAMA_API_KEY` | API key passed as `Authorization: Bearer` to Ollama. Leave empty for unauthenticated access. Note: `OLLAMA_API_KEY` is not enforced in Ollama 0.6.5 or 0.30.6 (see ADR-028). | — | — | YES |
-| `OLLAMA_CPU_LIMIT` | Docker CPU quota for the Ollama container. On CX42 (8 vCPUs) can be raised to `7.5`. | `4.0` | — | — |
-| `OLLAMA_MEM_LIMIT` | Memory limit for the Ollama container. Requires CX42 (16 GB RAM). | `8g` | — | — |
-| `OLLAMA_API_KEY` | API key set on the Ollama service itself. Same value as `APP_OLLAMA_API_KEY`. Leave empty for unauthenticated. | — | — | YES |
-
 ### Observability stack (`docker-compose.observability.yml`)
 
 | Variable | Purpose | Default | Required? | Sensitive? |
@@ -277,18 +265,6 @@ git.raddatz.cloud      A   <server IP>
 
 ### 3.4 First deploy
 
-> **First start — Ollama model pull:** On first `docker compose up -d`, the `ollama-model-init` container pulls `qwen2.5:7b-instruct-q4_K_M` (~4.7 GB). At 10 Mbps this takes approximately 60–90 minutes; at 100 Mbps approximately 6–10 minutes. The pull is a one-time operation — subsequent restarts skip it (model already on the `ollama_models` volume). Monitor progress with `docker logs -f $(docker ps -q --filter name=ollama-model-init)`.
->
-> **Do not use `--wait` on first deploy** — `docker compose up -d --wait` waits for all services to reach their health/completion target, including `ollama-model-init`. On first pull this blocks for 60–90 minutes and will time out any CI/deploy script that uses `--wait`.
->
-> **Re-deploy idempotency:** on subsequent `docker compose up -d` runs (including `--force-recreate`), `ollama-model-init` re-executes but exits in seconds — Ollama's CLI skips the download when the model digest already matches what is on the volume.
->
-> **Verify NL search is active** after enabling Ollama (`APP_OLLAMA_BASE_URL=http://ollama:11434`):
-> ```bash
-> curl -s http://localhost:8080/api/nl-search?q=brief+von+grossmutter
-> # Returns 200 with results → NL search is active
-> # Returns 503 NL_SEARCH_UNAVAILABLE → Ollama is not reachable or APP_OLLAMA_BASE_URL is unset
-> ```
 
 ```bash
 # 1. Trigger nightly.yml manually (Repo → Actions → nightly → "Run workflow")
@@ -585,55 +561,6 @@ bash scripts/download-kraken-models.sh
 
 > Downloads the Kurrent/Sütterlin HTR models. Run once after a fresh clone or when models are updated.
 
-### Ollama — natural-language search (NL Search)
-
-NL search uses a local Ollama instance for query parsing. The `ollama` service is defined in `docker-compose.yml` alongside the main stack.
-
-**First-time model pull** (required before the feature works):
-
-```bash
-docker compose exec ollama ollama pull qwen2.5:7b-instruct-q4_K_M
-```
-
-This downloads ~4.4 GB. The model is stored in the `ollama_data` Docker volume and persists across container restarts.
-
-**Verify the model is available:**
-
-```bash
-docker compose exec ollama ollama list
-```
-
-Expected output includes `qwen2.5:7b-instruct-q4_K_M`.
-
-**Health check** — the backend polls `GET /api/tags` on Ollama at startup and before inference. If Ollama is absent, `POST /api/search/nl` returns HTTP 503 with `SMART_SEARCH_UNAVAILABLE`.
-
-**Configuration** (see `application.yaml` under `app.ollama`):
-
-| Property | Default | Description |
-|---|---|---|
-| `app.ollama.base-url` | `http://ollama:11434` | Ollama service URL (dev: `http://localhost:11434`) |
-| `app.ollama.model` | `qwen2.5:7b-instruct-q4_K_M` | Model to use for inference |
-| `app.ollama.timeout-seconds` | `60` | Read timeout for inference calls (absorbs cold model load on the first query after an Ollama restart) |
-| `app.nl-search.rate-limit.max-requests-per-minute` | `5` | Per-user rate limit |
-
-### Upgrade the Ollama model
-
-To switch to a newer model version (e.g. a future release of `qwen2.5`):
-
-1. Update the model name in the `ollama-model-init` `command:` in `docker-compose.yml`.
-2. Remove the existing model volume to free the old weights:
-   ```bash
-   docker volume rm familienarchiv_ollama_models
-   ```
-   (In production the volume name is prefixed with the compose project: `archiv-production_ollama-models`.)
-3. Restart the stack:
-   ```bash
-   docker compose up -d
-   ```
-   The `ollama-model-init` container pulls the new model weights on first start (~4–8 GB download depending on the model). The `ollama` inference server will not start until the pull completes (`condition: service_completed_successfully`).
-
-> **`ollama_models` volume:** holds model weights only — fully reproducible by re-pull, no backup needed.
-
 ### Trigger a canonical import
 
 The importer no longer parses the raw spreadsheet. It consumes the **canonical artifacts**

docs/GLOSSARY.md

@@ -149,7 +149,20 @@ _See also [Chronik](#chronik-internal)._
 
 **Chronik** `[internal]` — the conceptual and code-level name for the unified activity feed (per ADR-003 `003-chronik-unified-activity-feed.md`). Used in code, architecture documents, and ADRs. The user-facing label for the same concept is [Aktivität](#aktivitat--aktivitaten-user-facing).
 
-**Geschichte** (`Geschichte`) `[user-facing]` — a narrative story or article published in the archive, linking `Person`s and `Document`s. Lifecycle: `DRAFT → PUBLISHED` (see `GeschichteStatus`). DRAFT stories are hidden from users without the `BLOG_WRITE` permission.
+**Geschichte** (`Geschichte`) `[user-facing]` — a narrative story or curated document journey published in the archive. Two subtypes: `STORY` (free-form prose linking `Person`s) and `JOURNEY` (a *Lesereise* — an ordered sequence of `JourneyItem`s). Lifecycle: `DRAFT → PUBLISHED` (see `GeschichteStatus`). DRAFT stories are hidden from users without the `BLOG_WRITE` permission.
+
+**JourneyItem** (`JourneyItem`, table `journey_items`) `[internal]` — a single stop in a *Lesereise* (`Geschichte` with `type=JOURNEY`). Either document-backed (`document_id IS NOT NULL`) or a note-only interlude (`note IS NOT NULL`). Ordered by `position` (step of 10; max 100 items per journey). A DEFERRABLE UNIQUE constraint on `(geschichte_id, position)` allows atomic position swaps in the same transaction. A CHECK constraint ensures at least one of `document_id` or `note` is present. The FK to `documents` uses `ON DELETE SET NULL`, so deleting a document preserves the item (with `document_id = null`).
+
+**GeschichteView** (`GeschichteView`) `[internal]` — lean read-model record returned by `GeschichteService.getById()`. Contains `AuthorView` (id + displayName only — email not exposed) and a `List<JourneyItemView>` loaded via a separate query rather than a lazy collection.
+
+**JourneyItemView** (`JourneyItemView`) `[internal]` — lean view record for a single `JourneyItem` surface, containing `id`, `position`, an optional `DocumentSummary`, and an optional `note`.
+
+**DocumentSummary** (`DocumentSummary`) `[internal]` — lean document read-model used inside `JourneyItemView`. Contains title, date, senderName, receiverName, receiverCount, datePrecision — no tags or file storage info.
+
+**Interlude / Zwischentext** `[user-facing]` — an editorial paragraph inserted between document items in a *Lesereise*. An interlude is a `JourneyItem` with `document_id IS NULL` and a non-empty `note`; its content is a plain-text string stored in the `note` column (not `body` or `text`). Visually distinguished by `--color-interlude-bg/border/label` CSS tokens and a `ZWISCHENTEXT` label. Interludes cannot have their note removed (removing the interlude deletes the entire item).
+_Not to be confused with a document item's optional note_ — a document item's note is curator commentary attached to a linked letter; an interlude is standalone editorial prose with no backing document.
+
+**Lesereise** `[user-facing]` — a curated reading journey through a sequence of family documents, optionally annotated with editorial notes. Implemented as a `Geschichte` with `type=JOURNEY`. The reader UI (follow-on issue) renders items as a sequential reading experience.
 
 **Notification** (`Notification`) — an in-app message delivered to an `AppUser`. No email or SMS delivery exists today. Delivered via Server-Sent Events (`SseEmitterRegistry`) and persisted in the `notifications` table.
 
@@ -165,23 +178,7 @@ _See also [Chronik](#chronik-internal)._
 
 **Domain** — a Tier-1 bounded context with its own entities, controller, service, repository, and DTOs. Backend domains: `document`, `person`, `tag`, `user`, `geschichte`, `notification`, `ocr`, `audit`, `dashboard`. Frontend domains mirror this structure under `src/lib/`.
 
----
-
-## NL Search Terms
-
-**NlSearch** — the natural-language document search feature. Users type a plain-German query (e.g. "Was hat Walter im Krieg an Emma geschrieben?"); the backend parses it via Ollama, resolves person names to database UUIDs, and delegates to the standard `DocumentService.searchDocuments()` path. Endpoint: `POST /api/search/nl`.
-
-**NlQueryInterpretation** — the structured result of parsing a natural-language query. Contains: `resolvedPersons` (persons whose names unambiguously matched one DB record), `ambiguousPersons` (all candidates when a name matched more than one person), `keywords` (LLM-extracted search terms), `dateFrom`/`dateTo` (extracted date range), `rawQuery` (the original user input), `keywordsApplied` (whether keyword FTS was used), `resolvedTags` (tags matched by keyword→tag resolution), and `tagsApplied` (whether the OR-union tag filter was applied).
-
-**keyword→tag resolution** — the post-Ollama step in `NlQueryParserService` where each LLM-extracted keyword is substring-matched against the tag taxonomy via `TagService.findByNameContaining()`. Keywords that hit one or more tags are removed from the FTS text list and become an OR-union tag filter; keywords with no match remain as FTS text. Matching is case-insensitive and traverses the tag hierarchy via the recursive CTE `findDescendantIdsByName`. See ADR-033.
-
-**PersonHint** — a lightweight `{id, displayName}` pair used in `NlQueryInterpretation` to describe a resolved or ambiguous person without exposing the full `Person` entity to the frontend.
-
-**NameMatches** — the Person-domain result of `PersonService.resolveByName(name)`: candidate persons split by name-match strength into `direct` and `partial`. A match is **direct** when every query token is a whole-token match (order-independent, alias/maiden-name aware) across all of a person's name components (`firstName`, `lastName`, `alias`, each `PersonNameAlias` first+last, `title`); a **partial** matched the substring fetch but is not direct (e.g. "Cram" → "Clara Cramer"). The vocabulary is deliberately match strength, not the search layer's resolved/ambiguous buckets — `NlQueryParserService` maps one direct → resolved (auto-select), ≥2 direct → ambiguous, partial-only → ambiguous suggestions ("Meintest du …?"), and no candidates → folded into full-text search.
-
-**TagHint** — a lightweight `{id, name, color?}` triple used in `NlQueryInterpretation.resolvedTags` to describe a tag matched by keyword→tag resolution. `color` is the tag's effective color (one-level inheritance from parent when the tag has no own color), or null if neither tag nor parent has a color.
-
-**theme chip** `[frontend]` — a removable chip rendered in `InterpretationChipRow` for each entry in `NlQueryInterpretation.resolvedTags` when `tagsApplied` is `true`. Displays "Thema: {tag.name}" (prefix varies by locale). Clicking × removes the tag from the OR-union filter and navigates to `/documents?tag=…&tagOp=OR` with remaining tag and person parameters preserved.
+**NameMatches** — the Person-domain result of `PersonService.resolveByName(name)`: candidate persons split by name-match strength into `direct` and `partial`. A match is **direct** when every query token is a whole-token match (order-independent, alias/maiden-name aware) across all of a person's name components (`firstName`, `lastName`, `alias`, each `PersonNameAlias` first+last, `title`); a **partial** matched the substring fetch but is not direct (e.g. "Cram" → "Clara Cramer").
 
 ---
 

docs/adr/028-nl-search-ollama.md

@@ -1,67 +0,0 @@
-# ADR-028 — Natural language search is powered by Ollama (Qwen 2.5 7B), not a cloud API
-
-**Date:** 2026-06-06
-**Status:** Accepted
-**Issue:** #738 (NL search backend); part of epic #735
-**Milestone:** Archive Intelligence — NL Search
-
----
-
-## Context
-
-Family members write their search intent in plain German ("Was hat Walter im Krieg an Emma geschrieben?"), not in structured filter forms. Issue #735 defines NL search as a core product goal. Three delivery options were evaluated:
-
-**Option A — extend the OCR service.** The OCR Python microservice already runs on the same host. Adding LLM inference there avoids a new container. Rejected: the OCR service is a single-purpose, CPU-bound pipeline optimised for Kraken; bundling a 4.5 GB LLM weight into the same image would bloat it, complicate model lifecycle management, and create an unrelated failure domain (OOM on large OCR batches vs. LLM load time). ADR-001 was explicit about keeping OCR single-purpose.
-
-**Option B — call an external API (OpenAI, Anthropic, etc.).** Cloud inference is instant and requires no local hardware. Rejected: the archive contains real person names and private family correspondence from 1899–1950 — sending query content to a third party violates the project's data-residency principle (family data stays on the family server). Additionally, API cost and availability are outside the operator's control; the system must work air-gapped.
-
-**Option C — local Ollama service (chosen).** Ollama is a purpose-built LLM runtime with a simple REST API, model lifecycle management (`ollama pull`), and support for grammar-constrained JSON output. It runs entirely on the existing server (i7-6700, 64 GB RAM) with no cloud dependency.
-
-**Model selection:** Qwen 2.5 7B Q4_K_M (`qwen2.5:7b-instruct-q4_K_M`) was chosen over larger models because:
-- Quantised weight is ~4.5 GB — fits comfortably in 64 GB RAM alongside PostgreSQL and the JVM.
-- Instruction-tuned variant follows the structured JSON schema reliably without fine-tuning.
-- CPU-only inference at Q4_K_M takes 2–15 seconds per query, acceptable for a search that replaces a multi-step filter form.
-
-**Prompt injection mitigation:** The backend sends the raw user query to Ollama. To prevent the model from being prompted to return schema-breaking output, the API call uses Ollama's `format` parameter with a grammar-constrained JSON schema. Output length is further bounded by `maxLength` constraints in the schema (names ≤ 200 chars, keywords ≤ 100 chars). `NlQueryParserService` enforces these limits in code before any LLM-extracted fragment is passed to `PersonRepository.searchByName()` — defence in depth.
-
-**DB-blind name resolution:** The Ollama prompt stays small (the raw query only); person database records are never sent to the model. Name resolution happens as a cheap SQL query after the model returns. This keeps the prompt short, avoids data leakage, and means adding 1,000 new persons requires no prompt change.
-
-**Graceful degradation:** In-path Ollama failures surface via `OllamaClient.parse()` — any `IOException`, read timeout, or non-2xx response is caught by `RestClientOllamaClient` and re-thrown as `DomainException(SMART_SEARCH_UNAVAILABLE, HTTP 503)`. `isHealthy()` has no callers inside `search/`; it is reserved for the ops/health-endpoint polling path only (e.g. a future `/api/health/ollama` endpoint). The regular structured search (`GET /api/documents/search`) is unaffected — it never calls Ollama.
-
-**Expected inference latency:** 2–15 seconds on the current CPU-only hardware. The frontend issue must show a persistent "Suche läuft…" indicator for the full duration (see `aria-live="polite"` requirement in issue #738 frontend notes). The backend timeout is 30 seconds (`app.ollama.timeout-seconds=30`) — chosen as a safe upper bound for Q4_K_M on the i7-6700 with a realistic 500-character query under modest concurrent load.
-
-**NL query logging policy:** Only metadata is logged — query length, resolved person count, latency in milliseconds. The raw query is never written to the log file. Rationale: queries contain real family names (PII); log files persist to disk and may be shipped to Loki. Structured metadata is sufficient for debugging latency regressions.
-
-**Prompt-amplification abuse:** A malicious user could submit a long or crafted query to cause slow Ollama inference, consuming CPU. Mitigated by `NlSearchRateLimiter` (5 requests per user per minute, Bucket4j + Caffeine) and by `@Size(max=500)` on the request body. The rate limiter is node-local; in multi-replica deployments the effective limit multiplies by replica count — acceptable at the current single-node deployment scale.
-
-**Ollama model pre-pull requirement:** The Docker image contains only the Ollama binary, not the model weights. The operator must run `ollama pull qwen2.5:7b-instruct-q4_K_M` (≈4.5 GB download, 10–30 minutes) before the backend starts inference. If skipped, every NL search request returns 503 until the pull completes. The deployment runbook in `docs/DEPLOYMENT.md` covers this explicitly.
-
-**Startup dependency:** The `backend` Compose service declares `depends_on: ollama: condition: service_healthy`. The Ollama healthcheck polls `GET http://localhost:11434/api/tags`; `start_period: 120s` provides margin for weight loading (20–60 s on SSD). Note: `service_healthy` confirms the API is responding, not that the model is downloaded — if the pull was skipped, inference still returns 404.
-
-**Multi-name resolution heuristic:** For 2-name queries (e.g. "Was hat Walter an Emma geschrieben?"), the first extracted name is treated as sender and the second as receiver. Per-name role annotation (e.g. `{name: "Walter", role: "sender"}`) was rejected because it would require a combinatorially complex Ollama schema and the most natural German phrasing strongly implies sender→receiver order. For single-name queries, a `personRole` field (`sender`/`receiver`/`any`) is returned.
-
-**`personRole: "any"` keyword limitation:** When `personRole` is `"any"` and the name resolves to exactly one person, `DocumentService.searchDocumentsByPersonId()` is called (OR semantics: person as sender or receiver). Keyword filtering is not applied on this path — only person identity and date range. `keywordsApplied = false` is returned in the response. Rationale: the JPQL for OR-semantics person queries has no text predicate; adding FTS would require a native query or a separate pass, adding complexity for a case that is already well-narrowed by person identity.
-
-**`search/` → `person/` + `document/` dependency direction:** `NlQueryParserService` calls `PersonService.findByDisplayNameContaining()` and `DocumentService.searchDocuments()` — both are legitimate cross-domain service calls, not repository leaks. The `search/` package has no JPA entities of its own and never accesses `PersonRepository` or `DocumentRepository` directly.
-
-**Keyword→tag resolution** (issue #743): After Ollama extracts the `keywords` list, `NlQueryParserService` calls `TagService.findByNameContaining()` for each keyword. Keywords that match one or more tags are removed from the FTS text list and added as OR-union tag filters; keywords with no tag match remain as FTS text. Resolved tags are returned to the frontend as `TagHint` objects in `NlQueryInterpretation.resolvedTags` and rendered as removable "Thema: X" chips. The `tagsApplied` flag signals whether the OR-union filter was actually passed to `DocumentService.searchDocuments()` — it is `false` when the `personRole:any` single-person path is taken, because that path has no tag filter slot. See ADR-033 for the tag name resolution and case-collision rules that `TagService.findByNameContaining()` relies on.
-
-## Decision
-
-**Introduce a new `search/` domain package** with a local Ollama integration via `RestClientOllamaClient`. The Ollama service runs as a separate Docker container, reachable only on the internal Docker network (`expose: ["11434"]`, not `ports:`). The backend calls Ollama's `/api/generate` endpoint with grammar-constrained JSON output. Name resolution and document search are performed by existing services after the model returns.
-
-Key component structure:
-- `OllamaClient` / `OllamaHealthClient` interfaces — mockable for tests, modelled on `OcrClient`/`OcrHealthClient`
-- `RestClientOllamaClient` — two `RestClient` instances (30 s inference, 2 s health-check)
-- `NlQueryParserService` — orchestrates Ollama → name resolution → document search
-- `NlSearchRateLimiter` — Bucket4j + Caffeine, 5 req/min per user
-- `NlSearchController` — `POST /api/search/nl`, `@RequirePermission(READ_ALL)`
-
-## Consequences
-
-- Family members can query in natural German without learning filter UI. Expected search satisfaction improvement for the 60+ age cohort (primary transcription audience) is significant.
-- NL search is unavailable when Ollama is down or the model pull is not complete. The regular search is unaffected. The 503 response includes a CTA directing users to the regular search.
-- Operator responsibility: run `ollama pull` on first deploy and after model updates. The backup runbook must exclude `ollama_models` volume (model weights are re-downloadable, not user data).
-- Inference takes 2–15 seconds. The frontend loading indicator is a hard requirement (see issue #738 frontend notes).
-- The rate limiter is node-local. At the current single-node deployment scale this is correct. If the service is ever scaled horizontally, the rate limiter must be moved to Redis (same caveat as `LoginRateLimiter`).
-- The `search/` package introduces a new cross-domain dependency direction (`search` → `person`, `search` → `document`). This is intentional and documented in `docs/architecture/c4/l3-backend-search.puml`.

docs/adr/028-ollama-docker-compose-service.md

@@ -1,239 +0,0 @@
-# ADR-028: Ollama Docker Compose service for NL search
-
-**Date:** 2026-06-06
-**Status:** Accepted
-**Deciders:** Marcel Raddatz
-**Relates to:** #737 (infrastructure), #735 (NL search epic)
-
----
-
-## Context
-
-Issue #735 introduces natural-language document search, requiring a local LLM to generate embeddings and/or run inference at query time. The family archive stores personal family history — data privacy is non-negotiable, so cloud-based inference APIs are excluded. The production target is a Hetzner CX42 (16 GB RAM, 8 vCPUs, CPU-only, ~32 EUR/month).
-
-Alternatives considered:
-
-| Option | Reason rejected |
-|---|---|
-| **llama.cpp** | No HTTP API out of the box; requires custom wrapper; higher ops burden |
-| **vLLM** | GPU-first; significant overhead on CPU-only hardware; overkill for this scale |
-| **Cloud APIs** (OpenAI, Gemini, etc.) | Vendor lock-in; per-token cost at scale; data leaves the server — unacceptable for a private family archive |
-| **Ollama** | Self-contained Docker image; built-in HTTP REST API; actively maintained; CPU-compatible; zero egress |
-
-**Decision:** run Ollama as a Docker Compose service alongside the existing stack.
-
----
-
-## Decisions
-
-### 1. Hardware minimums and CPU-only constraint
-
-All inference runs on CPU. The target is the Hetzner CX42 (16 GB RAM, 8 vCPUs).
-
-| Tier | RAM | NL search |
-|---|---|---|
-| CX42 | 16 GB | Supported — full stack including Ollama |
-| CX32 | 8 GB | Disabled — set `APP_OLLAMA_BASE_URL=` (empty) to skip Ollama entirely |
-| CX22 | 4 GB | Unsupported for NL search |
-
-### 2. Memory budget on CX42
-
-| Component | `mem_limit` | Typical active RSS |
-|---|---|---|
-| OCR service | 12g (hard ceiling) | ~6 GB |
-| Ollama | 8g | ~8 GB |
-| **Total** | | **~14 GB active** |
-
-`memswap_limit` on the Ollama service is set to `8g` (matching `mem_limit`) to prevent Linux from swapping model weights into swap under OCR memory pressure. Swapping model weights does not crash the container but silently degrades inference latency. This mirrors the pattern already applied to the OCR service.
-
-**Operational constraint:** do NOT run `docker-compose.observability.yml` continuously alongside both OCR and Ollama on a CX42. The observability stack adds ~2 GB, which leaves no headroom.
-
-### 3. Graceful-degradation contract
-
-`app.ollama.base-url` absent OR blank → Ollama bean NOT registered → NL search returns HTTP 503 with `ErrorCode: NL_SEARCH_UNAVAILABLE`.
-
-This single code path covers all unavailability scenarios: base-url unset, service unreachable, health check failed, and request timeout.
-
-#### Why not `@ConditionalOnProperty`
-
-`@ConditionalOnProperty` registers the bean when the property is present but blank (`APP_OLLAMA_BASE_URL=`). This produces a `RestClient` with an empty base URL that fails at runtime with an opaque error rather than a clean 503.
-
-#### Correct condition expression
-
-```java
-@ConditionalOnExpression("!'${app.ollama.base-url:}'.isBlank()")
-```
-
-When the property is absent, the placeholder resolves to `''`; `.isBlank()` returns `true`; negation makes the condition `false`; the bean is not registered. Same result for an explicit empty string (`APP_OLLAMA_BASE_URL=`).
-
-### 4. Backend configuration pattern
-
-Use a `@ConfigurationProperties` record, not separate `@Value` injections:
-
-```java
-@ConfigurationProperties("app.ollama")
-record OllamaProperties(String baseUrl, String apiKey) {}
-```
-
-`OllamaProperties` is registered unconditionally — it is a plain value holder with no side effects.
-
-`@ConditionalOnExpression` belongs **only** on `RestClientOllamaClient` (the bean that creates a live network client).
-
-**Deliberate divergence from the OCR pattern:** the OCR service uses `@Value`-with-default because OCR is always-on and `http://ocr-service:8000` is a safe default. Ollama is truly optional — a missing URL means "feature disabled", not "use this default server". There is no safe default Ollama URL.
-
-### 5. Optional<OllamaClient> injection
-
-The NL search service uses constructor injection with `Optional<OllamaClient>`:
-
-```java
-private final Optional<OllamaClient> ollamaClient;
-```
-
-When empty (bean not registered), the service method returns 503 immediately:
-
-```java
-var client = ollamaClient.orElseThrow(
-    () -> DomainException.internal(ErrorCode.NL_SEARCH_UNAVAILABLE, "Ollama not configured"));
-```
-
-Prefer this over `@Autowired(required = false)` with a null check — the null-check pattern is noisy when the service already uses `@RequiredArgsConstructor`.
-
-### 6. Empty API key guard
-
-`RestClientOllamaClient` omits the `Authorization` header entirely when `apiKey` is blank:
-
-```java
-if (!apiKey.isBlank()) {
-    request.header("Authorization", "Bearer " + apiKey);
-}
-```
-
-Sending `Authorization: Bearer ` (empty token) has undefined or potentially broken behavior depending on the Ollama version. This mirrors the `trainingToken` guard in `RestClientOcrClient.java:107`.
-
-### 7. OLLAMA_API_KEY behavior in Ollama 0.6.5 and 0.30.6
-
-**Empirically verified (2026-06-06) on both `0.6.5` and `0.30.6`:** `OLLAMA_API_KEY` does **not** enforce request authentication in either version.
-
-Test matrix run against `/api/tags`:
-
-| Configuration | No auth header | `Authorization: Bearer ` (empty) | `Authorization: Bearer wrongkey` | `Authorization: Bearer correctkey` |
-|---|---|---|---|---|
-| `OLLAMA_API_KEY=` (empty) | 200 | 200 | — | — |
-| `OLLAMA_API_KEY` unset | 200 | — | — | — |
-| `OLLAMA_API_KEY=testkey99` | 200 | 200 | 200 | 200 |
-
-**Finding:** The `OLLAMA_API_KEY` environment variable is not listed in Ollama's startup config dump and does not gate any HTTP request in either tested version. All configurations — empty string, fully unset, and a real key — accept all requests without authentication.
-
-**Practical implication:** `OLLAMA_API_KEY` provides no defense-in-depth in the tested versions. `archiv-net` network isolation is the only effective security control. The env var is retained in the Compose definition and `.env.example` for forward compatibility if Ollama enables enforcement in a future version, but operators must not rely on it for access control.
-
-**Backend guard still valid:** the `RestClientOllamaClient` code-level guard (omit `Authorization` header when `apiKey.isBlank()`) remains correct behavior regardless — it prevents a malformed `Authorization: Bearer ` header from being sent.
-
-### 8. read_only: true feasibility
-
-**Empirically verified (2026-06-06) on both `0.6.5` and `0.30.6`:** `read_only: true` works with Ollama. All three operations — `ollama serve`, `ollama pull qwen2.5:7b-instruct-q4_K_M`, and `ollama list` — succeeded with exit code 0 in both versions.
-
-Test run:
-```bash
-docker run --rm --read-only \
-  -v ollama_models:/root/.ollama \
-  --tmpfs /tmp \
-  --entrypoint sh ollama/ollama:0.30.6 \
-  -c "ollama serve & sleep 5 && ollama pull qwen2.5:7b-instruct-q4_K_M && ollama list"
-```
-
-**Note:** the entrypoint must be overridden to `sh` for the test command — the container's default entrypoint is `/bin/ollama` and does not accept `sh` as a subcommand. This is a Docker invocation detail; the Compose service definition uses the image's default entrypoint and `command:` override for the init container, which works correctly.
-
-**Result:** `read_only: true` and `tmpfs: - /tmp:size=512m` are applied to both `ollama` and `ollama-model-init`. The `ollama_models` volume handles all persistent writes; no other paths require write access during normal operation.
-
-### 9. Peak RSS of init container during pull
-
-**Empirically verified (2026-06-06):** Peak RSS during `qwen2.5:7b-instruct-q4_K_M` pull was **~108 MiB**.
-
-`docker stats` samples during the pull (15-second intervals):
-
-| Sample | MEM |
-|---|---|
-| 1 | 54.89 MiB |
-| 2 | 66.3 MiB |
-| 5 | 97.25 MiB |
-| 9 | **107.8 MiB** (peak) |
-
-`mem_limit: 2g` is adequate — the model weights stream directly to the named volume; RSS is dominated by the Ollama server process alone (~100 MB), not the model data. No bump to 4 GB needed.
-
-### 10. Init container pull mechanism
-
-The `ollama-model-init` container uses a curl-based readiness loop with captured PID:
-
-```sh
-ollama serve & SERVE_PID=$!
-until curl -sf http://localhost:11434/api/tags; do sleep 1; done
-ollama pull qwen2.5:7b-instruct-q4_K_M
-kill $SERVE_PID
-```
-
-`kill %1` (job-control syntax) is unreliable in non-interactive `sh -c` contexts. Capturing the PID via `SERVE_PID=$!` is reliable.
-
-The same endpoint (`/api/tags`) is used for both the init container readiness loop and the main service `healthcheck`.
-
-### 11. start_period: 60s rationale
-
-The model is pre-pulled by `ollama-model-init` before the main service starts (via `condition: service_completed_successfully`). At main service startup, Ollama only loads model weights from the named volume and binds port 11434.
-
-60 seconds is appropriate for this cold-start profile. 300 seconds was considered — that would be appropriate if the service pulled the model itself — but overstates actual startup time when the model is already present on the volume.
-
-### 12. Security threat model
-
-**Primary control:** `archiv-net` network isolation. Ollama has no externally exposed port (`expose:` only, not `ports:`). The Caddyfile must not route any path to the Ollama service.
-
-**Note on `OLLAMA_API_KEY`:** Per §7, `OLLAMA_API_KEY` is not enforced in Ollama 0.6.5 or 0.30.6 and provides no authentication barrier against a compromised backend container. `archiv-net` network isolation is the sole effective security control. The env var is retained for forward compatibility only — do not rely on it for access control.
-
-Both `ollama` and `ollama-model-init` receive the ADR-019 hardening baseline:
-
-```yaml
-cap_drop: [ALL]
-security_opt: [no-new-privileges:true]
-```
-
-### 13. CI exclusion strategy
-
-Docker Compose profiles are not used — they would add developer friction (requiring `--profile ...` for all local dev commands).
-
-CI uses explicit service selection in `docker-compose.ci.yml`:
-```bash
-docker compose -f docker-compose.ci.yml up -d db minio create-buckets
-```
-
-Ollama is simply not listed and is never started in CI. A YAML comment on the `ollama` service block documents this:
-
-```yaml
-# Not started in CI — CI uses explicit service selection
-# (docker-compose.ci.yml: db minio create-buckets)
-```
-
-### 14. ollama_models volume operational note
-
-The `ollama_models` named volume holds model weights only — fully reproducible by re-pull. No backup is needed.
-
-If the volume fills after a model upgrade:
-```bash
-docker volume rm ollama_models && docker compose up -d
-```
-The init container re-pulls the model on next startup.
-
----
-
-## Consequences
-
-### Positive
-
-- NL search runs entirely on-premises; no data leaves the server and no per-token cloud cost.
-- Graceful degradation is a first-class concern: smaller or budget-constrained instances can run the app without Ollama with a single env var change.
-- The init container pattern keeps model pull out of the critical startup path for the main service, giving accurate healthcheck timings.
-- `@ConditionalOnExpression` with a blank-check is more correct than `@ConditionalOnProperty` for optional features with no safe default URL.
-
-### Risks and operational implications
-
-- **Memory pressure:** OCR + Ollama together consume ~14 GB on a 16 GB host. Running the observability stack simultaneously risks OOM kills. Monitor with `docker stats`.
-- **CPU inference latency:** `qwen2.5:7b-instruct-q4_K_M` is chosen for CPU viability, but inference on 8 vCPUs will be noticeably slower than GPU-accelerated alternatives. This is acceptable for the family archive use case (low concurrency, not real-time).
-- All three empirical TBD items from the original issue spec were resolved — see §7 (OLLAMA_API_KEY not enforced), §8 (`read_only: true` works), §9 (peak RSS ~108 MiB).
-- Model upgrades require a `docker volume rm` to free old weights before pulling the replacement. Document this in runbook/DEPLOYMENT.md.

docs/adr/034-ollama-production-deployment-and-keep-alive.md

@@ -1,125 +0,0 @@
-# ADR-034: Ollama in production — deployment, keep-alive pinning, and corrected init recipe
-
-**Date:** 2026-06-06
-**Status:** Accepted
-**Deciders:** Marcel Raddatz
-**Relates to:** #758 (bug), #759 (fix), #737 (NL search infrastructure)
-**Corrects:** ADR-028 §10–§11 (init recipe and readiness probe)
-
----
-
-## Context
-
-ADR-028 introduced Ollama as a Docker Compose service for NL search and documented
-its topology, graceful-degradation contract, and memory budget. Two defects survived
-that work and only surfaced once NL search reached staging (#758):
-
-1. **Ollama was added only to the dev `docker-compose.yml`.** Staging and production
-   deploy from the self-contained `docker-compose.prod.yml`, which had no `ollama`
-   service. The backend defaults to `app.ollama.base-url: http://ollama:11434`, so its
-   client bean was active and resolved to a non-existent host → `ResourceAccessException`
-   → HTTP 503 on every NL search.
-2. **The init recipe documented in ADR-028 §10 never worked.** The `ollama/ollama` image
-   `ENTRYPOINT` is `ollama`, so a bare `command: sh -c "…"` ran as `ollama sh -c "…"`
-   (`unknown command "sh"`), and the image ships **no curl**, so the curl-based readiness
-   loop and the curl healthcheck could never pass.
-
-This ADR records the production deployment decision and the corrected operational
-contract. It is also the durable record of *why* `OLLAMA_KEEP_ALIVE=-1` is set, so a
-future maintainer does not "optimize" it away and reintroduce the cold-load 503.
-
----
-
-## Decisions
-
-### 1. Ollama is a first-class production service
-
-`docker-compose.prod.yml` now defines `ollama` + `ollama-model-init` + the
-`ollama-models` volume, mirroring the dev stack. The graceful-degradation contract from
-ADR-028 §3 is preserved: `backend` has **no** hard `depends_on` on `ollama`, so an absent
-or unhealthy Ollama still yields a clean 503 rather than blocking backend startup.
-
-### 2. Corrected init recipe (supersedes ADR-028 §10)
-
-The init container overrides the image entrypoint to a shell and probes readiness with
-`ollama list` (not curl, which the image lacks):
-
-```sh
-ollama serve & until ollama list >/dev/null 2>&1; do sleep 1; done && \
-  (ollama list | grep -q 'qwen2.5:7b-instruct-q4_K_M' || ollama pull qwen2.5:7b-instruct-q4_K_M)
-```
-
-```yaml
-entrypoint: ["/bin/sh", "-c"]
-```
-
-The pull is **guarded by a grep on the cached model list**. A model already on the volume
-exits clean without any registry round-trip. This makes re-up offline-safe: a host reboot
-during a registry/network blip can no longer fail init (which, via
-`condition: service_completed_successfully`, would otherwise block the `ollama` service
-and take NL search down until the registry was reachable again). The same recipe is used
-in dev and prod — one mental model.
-
-### 3. Healthcheck uses `ollama list` (supersedes ADR-028 §11 probe)
-
-```yaml
-healthcheck:
-  test: ["CMD", "ollama", "list"]
-```
-
-`ollama list` hits the local API and exits non-zero when the server is down — the correct
-probe for a curl-less image. The `start_period: 60s` rationale from ADR-028 §11 still holds.
-
-### 4. `OLLAMA_KEEP_ALIVE=-1` — pin the model in memory
-
-```yaml
-environment:
-  OLLAMA_KEEP_ALIVE: "-1"
-```
-
-By default Ollama evicts an idle model after ~5 minutes. The next query then pays a
-cold-load penalty that exceeds the backend read timeout, producing an NL search 503 after
-any idle period. Pinning the model (`-1` = never unload) keeps warm-path latency
-predictable (~18 s on CPU). **Do not remove this** without re-introducing the post-idle
-cold-load 503.
-
-### 5. Read timeout raised 30 → 60 s
-
-`app.ollama.timeout-seconds` is raised from 30 to 60 (`application.yaml`, mirrored in
-`DEPLOYMENT.md`). Warm CPU inference is ~18 s; the higher ceiling absorbs the one cold
-model load on the first query after an Ollama (re)start, before §4's pin takes hold.
-
-**Implicit NFR made explicit:** NL search shall return a result or a 503 within 60 s; the
-cold-start path immediately after an Ollama restart is the only path that approaches this
-ceiling.
-
-### 6. Hard-OOM trade-off (refines ADR-028 §2)
-
-`memswap_limit == mem_limit` (both `${OLLAMA_MEM_LIMIT:-8g}`) disables swap for the
-container. Combined with §4's pinned model, a memory-pressure event is a **hard OOM-kill,
-not graceful latency degradation**. This is deliberate — swap-thrashing an LLM is worse
-than a clean restart — but it means the 8 GB envelope is a real ceiling. `qwen2.5-7B-q4`
-plus its KV cache under load sits close enough to 8 GB that this needs a Prometheus
-memory alert on the `ollama` container before it bites in production (tracked as
-observability follow-up, not in this PR).
-
----
-
-## Consequences
-
-### Positive
-
-- NL search works on staging/production, not just dev — the actual deploy artifact now
-  matches the documented architecture.
-- Re-up is offline-safe: a cached model never depends on registry reachability.
-- The keep-alive pin and timeout ceiling make NL search latency predictable on CPU.
-
-### Risks and operational implications
-
-- **Hard OOM under memory pressure** (§6): a Prometheus alert on `ollama` container memory
-  is required before this is load-bearing in prod. Tracked as an observability follow-up.
-- **Unauthenticated inference** relies entirely on `archiv-net` isolation (ADR-028 §7/§12,
-  unchanged). Sending an `Authorization` header from `RestClientOllamaClient` is a separate
-  durable hardening item, tracked outside this PR.
-- ADR-028 §10–§11 describe a recipe that never functioned; this ADR is the authoritative
-  init/healthcheck contract going forward.

docs/adr/034-remove-nl-search.md

@@ -0,0 +1,53 @@
+# ADR-034 — Remove NL/smart-search (supersedes ADR-028 ×2, ADR-034-ollama, ADR-035)
+
+**Date:** 2026-06-07
+**Status:** Accepted
+**Issue:** #772
+**Supersedes:** ADR-028 (nl-search-ollama), ADR-028 (ollama-docker-compose-service), ADR-034 (ollama-production-deployment-and-keep-alive), ADR-035 (rule-based-nlp-service)
+
+---
+
+## Context
+
+The natural-language search feature ("KI-Suche" / smart search) allowed users to enter
+free-form queries like *"Was hat Walter an Emma im Krieg geschrieben?"* and have them
+interpreted by an LLM into structured filters (persons, tags, date range, keywords).
+
+The feature went through two major iterations:
+1. **Ollama integration** (ADR-028): an `ollama` Docker service running a local LLM
+   (llama3.2/gemma3) parsed queries via a JSON-mode prompt.
+2. **Rule-based NLP service** (ADR-035): after Ollama proved too slow and unreliable on
+   CPU-only hardware, a Python FastAPI microservice (`nlp-service`, port 8001) replaced
+   it with deterministic regex + spaCy parsing plus a lightweight LLM call.
+
+Both approaches shared the same fundamental problem: inference on the production server
+(Hetzner Serverbörse, no GPU, 64 GB RAM, i7-6700) was too slow to be useful, with
+typical query latencies of 10–30 seconds. Users got better and faster results from
+the existing keyword search with date/person/tag filters.
+
+## Decision
+
+**Remove the NL search feature entirely.** The Python `nlp-service` microservice, the
+Spring Boot `search/` package (`NlSearchController`, `NlQueryParserService`,
+`RestClientNlpClient`, `NlSearchRateLimiter`, and all supporting classes), the frontend
+NL search components (`SmartModeToggle`, `SmartSearchStatus`, `InterpretationChipRow`,
+`DisambiguationPicker`), the related Docker Compose services, Prometheus scrape job,
+Grafana dashboard, and all i18n keys are removed.
+
+The existing structured search (FTS keyword + person/tag/date/directional filters) is
+sufficient for the archive's current audience and search workload.
+
+## Consequences
+
+- **Capability removed:** users can no longer enter free-form natural-language queries.
+  They must use the structured filter bar (keyword text box + person/tag/date/directional
+  dropdowns). For documents where these filters are sufficient, there is no regression.
+- **Operational simplification:** the Docker Compose stack loses two services
+  (`nlp-service` and previously `ollama`/`ollama-model-init`). Memory budget on the
+  production host is freed. No external model weights need to be kept warm.
+- **Future reinstatement:** if a GPU-capable host becomes available, re-implementing
+  server-side LLM inference would be straightforward given the clean separation of the
+  `NlSearchController` entry point. However, this ADR deliberately avoids leaving dead
+  infrastructure or stub code in place — start clean if and when that becomes viable.
+- **No data or schema change:** only query/endpoint code and Docker services are removed.
+  The `documents`, `persons`, and `tags` tables and their FTS indexes are untouched.

docs/adr/035-optional-string-three-way-patch-semantics.md

@@ -0,0 +1,43 @@
+# ADR-035 — `Optional<String>` for three-way PATCH semantics
+
+**Status:** Accepted  
+**Date:** 2026-06-08  
+**Issue:** #751 (JourneyItem CRUD API)
+
+## Context
+
+The `PATCH /api/geschichten/{id}/items/{itemId}` endpoint must distinguish three cases for the `note` field:
+
+| JSON body         | Intended meaning      |
+|-------------------|-----------------------|
+| `{"note": "text"}`| Set note to "text"    |
+| `{"note": null}`  | Clear the note        |
+| `{}` (absent)     | Leave note unchanged  |
+
+The standard library for this on Jackson 2.x is `jackson-databind-nullable` (`JsonNullable<T>` from `org.openapitools`). However, that library targets `com.fasterxml.jackson.*` (Jackson 2.x) and is incompatible with Spring Boot 4.0 / Spring Framework 7, which uses `tools.jackson.*` (Jackson 3.x). The module fails to register and throws at startup.
+
+## Decision
+
+Use `Optional<String>` with Java's default field initializer (`= null`) to encode the three states:
+
+```java
+@Data
+public class JourneyItemUpdateDTO {
+    private Optional<String> note = null;  // Java default — absent = no-op
+}
+```
+
+| Java value         | JSON wire         | Semantics     |
+|--------------------|-------------------|---------------|
+| `null` (default)   | field absent      | no-op         |
+| `Optional.empty()` | `{"note": null}`  | clear         |
+| `Optional.of("x")` | `{"note": "x"}`   | set           |
+
+Jackson 3.x natively maps a JSON `null` to `Optional.empty()` and leaves absent fields at their Java default. No custom module is needed.
+
+## Consequences
+
+- No external dependency for PATCH semantics — simpler pom.xml.
+- The DTO field type is `Optional<String>`, not `String` — service code must null-check the field first (`if (noteField == null) return;`) and then call `.orElse(null)` to unwrap.
+- This pattern applies to any future PATCH DTO that needs three-way semantics on a nullable field.
+- `jackson-databind-nullable` is removed from `pom.xml`; `JacksonConfig.java` is kept as a placeholder for future custom modules.

docs/architecture/c4/l2-containers.puml

@@ -12,15 +12,13 @@ System_Boundary(archiv, "Familienarchiv (Docker Compose)") {
     Container(frontend, "Web Frontend", "SvelteKit / Node adapter / port 3000", "Server-side rendered UI. Handles auth session cookies, document search and viewer, transcription editor, annotation layer, family tree (Stammbaum), stories (Geschichten), activity feed (Chronik), enrichment workflow, and admin panel.")
     Container(backend, "API Backend", "Spring Boot 4 / Java 21 / Jetty / port 8080", "REST API. Implements document management, search, user auth, file upload/download, transcription, OCR orchestration, and SSE notifications. Trusts X-Forwarded-* headers from Caddy.")
     Container(ocr, "OCR Service", "Python FastAPI / port 8000", "Handwritten text recognition (HTR) and OCR microservice. Single-node by design — see ADR-001. Reachable only on the internal Docker network; no external port exposed.")
-    Container(ollama, "Ollama LLM Service", "ollama/ollama:0.30.6 / port 11434 (internal only)", "Local LLM inference server for NL search. Runs qwen2.5:7b-instruct-q4_K_M on CPU. Reachable only on the internal Docker network; no external port exposed. Disabled when APP_OLLAMA_BASE_URL is unset or blank.")
-    ' Named volume: ollama_models — model weights, fully reproducible, no backup needed
     ContainerDb(db, "Relational Database", "PostgreSQL 16", "Stores document metadata, persons, users, permission groups, tags, transcription blocks, audit log, and Spring Session data.")
     ContainerDb(storage, "Object Storage", "MinIO (S3-compatible)", "Stores the actual document files (PDFs, scans). Backend uses a bucket-scoped service account (archiv-app), not MinIO root.")
     Container(mc, "Bucket / Service-Account Init", "MinIO Client (mc)", "One-shot container on startup. Idempotent: creates the archive bucket, the archiv-app service account, and attaches the readwrite policy.")
 }
 
 System_Boundary(observability, "Observability Stack (/opt/familienarchiv/docker-compose.observability.yml)") {
-    Container(prometheus, "Prometheus", "prom/prometheus:v3.4.0", "Scrapes metrics from backend (8081 /actuator/prometheus), OCR service (8000 /metrics), Ollama (11434 /metrics), node-exporter, and cAdvisor. Retention: 30 days.")
+    Container(prometheus, "Prometheus", "prom/prometheus:v3.4.0", "Scrapes metrics from backend (8081 /actuator/prometheus), OCR service (8000 /metrics), node-exporter, and cAdvisor. Retention: 30 days.")
     Container(node_exporter, "Node Exporter", "prom/node-exporter:v1.9.0", "Host-level CPU, memory, disk, and network metrics.")
     Container(cadvisor, "cAdvisor", "gcr.io/cadvisor/cadvisor:v0.52.1", "Per-container resource metrics.")
     Container(loki, "Loki", "grafana/loki:3.4.2", "Stores log streams from all containers.")
@@ -43,12 +41,11 @@ Rel(backend, ocr, "OCR job requests with presigned MinIO URL", "HTTP / REST / JS
 Rel(backend, mail, "Sends notification and password-reset emails (optional)", "SMTP")
 Rel(ocr, storage, "Fetches PDF via presigned URL", "HTTP / S3 presigned")
 Rel(mc, storage, "Bootstraps bucket + service account on startup", "MinIO Client CLI")
-Rel(backend, ollama, "NL query parsing (POST /api/generate)", "HTTP / REST / JSON")
 Rel(promtail, loki, "Pushes log streams", "HTTP/Loki push API")
 Rel(backend, tempo, "Sends distributed traces via OTLP", "HTTP / OTLP / port 4318 (archiv-net)")
 Rel(prometheus, backend, "Scrapes JVM + HTTP metrics", "HTTP 8081 /actuator/prometheus")
 Rel(prometheus, ocr, "Scrapes OCR + http_* metrics", "HTTP 8000 /metrics")
-Rel(prometheus, ollama, "Scrapes LLM request metrics", "HTTP 11434 /metrics")
+
 Rel(grafana, prometheus, "Queries metrics", "HTTP 9090")
 Rel(grafana, loki, "Queries logs", "HTTP 3100")
 Rel(grafana, tempo, "Queries traces", "HTTP 3200")

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

@@ -16,8 +16,10 @@ System_Boundary(backend, "API Backend (Spring Boot)") {
     Component(notifCtrl, "NotificationController", "Spring MVC — /api/notifications", "REST and SSE endpoints for notification stream, history with filtering, read/unread state, and per-user preference management.")
     Component(notifSvc, "NotificationService", "Spring Service", "Creates REPLY and MENTION notifications, optionally sends email, marks as read, and pushes events to connected clients via SseEmitterRegistry.")
     Component(sseRegistry, "SseEmitterRegistry", "Spring Component", "In-memory ConcurrentHashMap of Spring SseEmitter instances per user. Handles registration, deregistration, and JSON event broadcasts.")
-    Component(geschCtrl, "GeschichteController", "Spring MVC — /api/geschichten", "CRUD for publishable stories that link persons and documents. Requires BLOG_WRITE permission for write operations.")
-    Component(geschSvc, "GeschichteService", "Spring Service", "Manages story lifecycle (DRAFT → PUBLISHED with timestamp). Sanitizes HTML body with an allowlist policy.")
+    Component(geschCtrl, "GeschichteController", "Spring MVC — /api/geschichten", "CRUD for publishable stories (STORY) and reading journeys (JOURNEY). Returns GeschichteSummary projections for list; full Geschichte with JourneyItems for detail. Requires BLOG_WRITE permission for write operations.")
+    Component(geschSvc, "GeschichteService", "Spring Service", "Manages story lifecycle (DRAFT → PUBLISHED with timestamp). Supports two subtypes: STORY (prose) and JOURNEY (ordered JourneyItem sequence). Sanitizes HTML body with an allowlist policy.")
+    Component(geschQuerySvc, "GeschichteQueryService", "Spring Service", "Read-only facade over GeschichteRepository. Exposes existsById() and findById() to prevent JourneyItemService from crossing domain boundaries.")
+    Component(journeyItemSvc, "JourneyItemService", "Spring Service", "Manages journey item lifecycle: append (100-item cap), updateNote (three-way PATCH), delete, and reorder (DEFERRABLE position swap). Enforces JOURNEY-type guard on append.")
     Component(exHandler, "GlobalExceptionHandler", "Spring @RestControllerAdvice", "Converts DomainException, validation errors, and generic exceptions to ErrorResponse JSON with machine-readable ErrorCode and HTTP status.")
 }
 
@@ -38,6 +40,10 @@ Rel(notifCtrl, notifSvc, "Delegates to")
 Rel(notifCtrl, sseRegistry, "Registers client SSE connection")
 Rel(notifSvc, sseRegistry, "Broadcasts events to connected clients")
 Rel(geschCtrl, geschSvc, "Delegates to")
+Rel(geschCtrl, journeyItemSvc, "Delegates journey item CRUD")
+Rel(journeyItemSvc, geschQuerySvc, "Checks Geschichte existence and type")
+Rel(geschQuerySvc, db, "Reads geschichten", "JDBC")
+Rel(journeyItemSvc, db, "Reads / writes journey_items", "JDBC")
 Rel(auditSvc, db, "Writes audit_log", "JDBC")
 Rel(auditQuery, db, "Reads audit_log", "JDBC")
 Rel(notifSvc, db, "Reads / writes notifications", "JDBC")

docs/architecture/c4/l3-backend-3h-search.puml

@@ -1,37 +0,0 @@
-@startuml
-!include <C4/C4_Component>
-
-title Component Diagram: API Backend — NL Search
-
-Container(frontend, "Web Frontend", "SvelteKit")
-ContainerDb(db, "PostgreSQL", "PostgreSQL 16")
-Container(ollama, "Ollama", "ollama/ollama — port 11434 (internal only)")
-
-System_Boundary(backend, "API Backend (Spring Boot)") {
-    Component(nlCtrl, "NlSearchController", "Spring MVC — POST /api/search/nl", "REST entry point for natural language search. Enforces READ_ALL permission. Uses @AuthenticationPrincipal UserDetails to obtain the caller's email for rate limiting. Delegates to NlQueryParserService and returns NlSearchResponse.")
-    Component(rateLimiter, "NlSearchRateLimiter", "Spring Service", "Bucket4j + Caffeine LoadingCache keyed on user email. Allows 5 NL search requests per minute per user. Throws DomainException(SMART_SEARCH_RATE_LIMITED / HTTP 429) when the bucket is exhausted. Node-local — same caveat as LoginRateLimiter.")
-    Component(parserSvc, "NlQueryParserService", "Spring Service", "Orchestrates the full NL search pipeline: (1) validates query length, (2) calls OllamaClient.parse() to extract structured intent, (3) resolves keywords to tags via TagService.findByNameContaining(), (4) resolves each person name via PersonService.findByDisplayNameContaining(), (5) applies multi-name / personRole heuristics, (6) delegates to DocumentService.searchDocuments() or searchDocumentsByPersonId(). Returns NlSearchResponse. Never logs raw query content (PII).")
-    Component(ollamaClient, "RestClientOllamaClient", "Spring Service — implements OllamaClient + OllamaHealthClient", "HTTP client for the Ollama API. Uses two separate RestClient instances: inference client (30 s read timeout) and health-check client (2 s connect timeout). Calls POST /api/generate with grammar-constrained JSON schema (personNames, personRole, dateFrom, dateTo, keywords). isHealthy() polls GET /api/tags. Null-coalesces absent personNames/keywords to List.of(). Defaults unknown personRole to 'any' with a warning log. Maps timeout/5xx/parse errors to DomainException(SMART_SEARCH_UNAVAILABLE / HTTP 503).")
-    Component(ollamaProps, "OllamaProperties", "@ConfigurationProperties(\"app.ollama\")", "Config bean: baseUrl, model (qwen2.5:7b-instruct-q4_K_M), timeoutSeconds (default: 30), healthCheckTimeoutSeconds (default: 2).")
-    Component(rateLimitProps, "NlSearchRateLimitProperties", "@ConfigurationProperties(\"app.nl-search.rate-limit\")", "Config bean: maxRequestsPerMinute (default: 5).")
-}
-
-Component(personSvc, "PersonService", "Spring Service", "See diagram 3e. findByDisplayNameContaining(fragment) delegates to PersonRepository.searchByName() — covers first+last name, alias, and name aliases via LEFT JOIN.")
-Component(documentSvc, "DocumentService", "Spring Service", "See diagram 3b. searchDocuments() for keyword/sender/receiver/date queries. searchDocumentsByPersonId() for OR-semantics single-person queries (person as sender OR receiver, no keyword filter).")
-Component(tagSvc, "TagService", "Spring Service", "See diagram 3b. findByNameContaining(fragment) delegates to TagRepository.findByNameContainingIgnoreCase(). resolveEffectiveColors() applies one-level color inheritance in-place on a collection of Tag entities.")
-
-Rel(frontend, nlCtrl, "POST /api/search/nl with JSON query", "HTTP / JSON")
-Rel(nlCtrl, rateLimiter, "checkAndConsume(userEmail)")
-Rel(nlCtrl, parserSvc, "parse(query)")
-Rel(parserSvc, ollamaClient, "parse(rawQuery) — extracts intent", "HTTP / JSON")
-Rel(ollamaClient, ollama, "POST /api/generate (grammar-constrained JSON schema)", "HTTP / REST")
-Rel(ollamaClient, ollama, "GET /api/tags (health check)", "HTTP / REST")
-Rel(parserSvc, tagSvc, "findByNameContaining(keyword) — keyword→tag resolution")
-Rel(parserSvc, tagSvc, "resolveEffectiveColors(tags)")
-Rel(parserSvc, personSvc, "findByDisplayNameContaining(name) for each extracted name")
-Rel(parserSvc, documentSvc, "searchDocuments() or searchDocumentsByPersonId()")
-Rel(documentSvc, db, "JPA queries", "JDBC")
-Rel(personSvc, db, "JPA queries", "JDBC")
-Rel(tagSvc, db, "JPA queries", "JDBC")
-
-@enduml

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

@@ -11,8 +11,8 @@ System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") {
     Component(personEdit, "/persons/[id]/edit and /persons/new", "SvelteKit Routes", "Create and edit person forms. Edit: metadata, aliases, explicit relationships. Actions: PUT/POST /api/persons.")
     Component(personReview, "/persons/review", "SvelteKit Route", "Transcriber triage view (WRITE-gated link). Lists provisional persons; per-row Merge / Umbenennen / Bestätigen / Löschen. Actions: POST /merge, PUT /{id}, PATCH /{id}/confirm, DELETE /{id}.")
     Component(aktivitaeten, "/aktivitaeten", "SvelteKit Route", "Unified activity feed (Chronik). Loader: GET /api/dashboard/activity and GET /api/notifications?read=false.")
-    Component(geschichten, "/geschichten and /geschichten/[id]", "SvelteKit Routes", "Story list and detail pages. Loader: GET /api/geschichten?status=PUBLISHED.")
-    Component(geschichtenEdit, "/geschichten/[id]/edit and /geschichten/new", "SvelteKit Routes", "Story editor with rich text, person and document linking. Actions: PUT/POST /api/geschichten. Requires BLOG_WRITE permission.")
+    Component(geschichten, "/geschichten and /geschichten/[id]", "SvelteKit Routes", "Story/Journey list and detail pages. List: GeschichteListRow with REISE badge for JOURNEY type. Detail: dispatches to StoryReader (rich text + persons) or JourneyReader (intro + ordered JourneyItemCard/JourneyInterlude items + empty state) based on GeschichteType. BLOG_WRITE users see edit/delete actions. Loader: GET /api/geschichten, GET /api/geschichten/{id}.")
+    Component(geschichtenEdit, "/geschichten/[id]/edit and /geschichten/new", "SvelteKit Routes", "Story editor and creation flow. New: TypeSelector (STORY/JOURNEY radio group with roving tabindex) → StoryCreate (TipTap rich text, person linking, POST /api/geschichten) or JourneyCreate (title + first item). Edit: branches on GeschichteType — STORY opens GeschichteEditor (TipTap body + GeschichteSidebar); JOURNEY opens JourneyEditor (title, intro textarea, ordered JourneyItemRow list with drag-reorder + move-up/down, JourneyAddBar for document/interlude addition, GeschichteSidebar). JourneyEditor mutations: POST/DELETE /items, PUT /items/reorder, PATCH /items/{id}. Requires BLOG_WRITE permission.")
     Component(stammbaum, "/stammbaum", "SvelteKit Route", "Family tree visualisation. Loader: GET /api/network (nodes + edges). Renders interactive family tree from network graph data.")
     Component(themen, "/themen", "SvelteKit Route", "Browsable topic index. Shows all root tags as cards with color bars and child rows. ThemenWidget also embedded in the home dashboard (reader + editor sidebar). Loader: GET /api/tags/tree.")
     Component(profilePage, "/profile", "SvelteKit Route", "Current user profile settings. Loader: GET /api/users/me/notification-preferences. Actions: update name/password and notification preferences.")
@@ -24,8 +24,8 @@ Rel(personsPage, backend, "GET /api/persons (filter + page params -> PersonSearc
 Rel(personEdit, backend, "GET /api/persons/{id}, PUT /api/persons/{id}, POST /api/persons", "HTTP / JSON")
 Rel(personReview, backend, "GET /api/persons?provisional=true, PATCH /api/persons/{id}/confirm, DELETE /api/persons/{id}, POST /api/persons/{id}/merge", "HTTP / JSON")
 Rel(aktivitaeten, backend, "GET /api/dashboard/activity, GET /api/notifications", "HTTP / JSON")
-Rel(geschichten, backend, "GET /api/geschichten", "HTTP / JSON")
-Rel(geschichtenEdit, backend, "GET/PUT/POST /api/geschichten", "HTTP / JSON")
+Rel(geschichten, backend, "GET /api/geschichten, GET /api/geschichten/{id}, DELETE /api/geschichten/{id}", "HTTP / JSON")
+Rel(geschichtenEdit, backend, "GET /api/persons/{id} (pre-populate), POST /api/geschichten, PUT /api/geschichten/{id}, POST/DELETE /api/geschichten/{id}/items, PUT /api/geschichten/{id}/items/reorder, PATCH /api/geschichten/{id}/items/{itemId}", "HTTP / JSON")
 Rel(stammbaum, backend, "GET /api/network", "HTTP / JSON")
 Rel(themen, backend, "GET /api/tags/tree", "HTTP / JSON")
 Rel(profilePage, backend, "GET/PUT /api/users/me, notification-preferences", "HTTP / JSON")

docs/architecture/db/db-orm.puml

@@ -1,6 +1,6 @@
 @startuml db-orm
-' Schema source: Flyway V1–V69 (excl. V37, V43 — intentionally removed)
-' Schema as of:  V69 (2026-05-27)
+' Schema source: Flyway V1–V72 (excl. V37, V43 — intentionally removed)
+' Schema as of:  V72 (2026-06-08)
 ' ⚠ This is a versioned snapshot. Update when the schema changes significantly.
 
 hide circle
@@ -359,6 +359,7 @@ package "Supporting" {
     title : VARCHAR(255) NOT NULL
     body : TEXT
     status : VARCHAR(32) NOT NULL
+    type : VARCHAR(32) NOT NULL
     author_id : UUID <<FK>>
     created_at : TIMESTAMP NOT NULL
     updated_at : TIMESTAMP NOT NULL
@@ -370,9 +371,15 @@ package "Supporting" {
     person_id : UUID <<FK>>
   }
 
-  entity geschichten_documents {
+  entity journey_items {
+    id : UUID <<PK>>
+    --
     geschichte_id : UUID <<FK>>
     document_id : UUID <<FK>>
+    position : INTEGER NOT NULL CHECK (position > 0)
+    note : TEXT
+    ==
+    UNIQUE (geschichte_id, position) DEFERRABLE INITIALLY DEFERRED
   }
 }
 
@@ -436,7 +443,7 @@ audit_log }o--o| documents : document_id
 geschichten }o--o| app_users : author_id
 geschichten_persons }o--|| geschichten : geschichte_id
 geschichten_persons }o--|| persons : person_id
-geschichten_documents }o--|| geschichten : geschichte_id
-geschichten_documents }o--|| documents : document_id
+journey_items }o--|| geschichten : geschichte_id (ON DELETE CASCADE)
+journey_items }o--o| documents : document_id (ON DELETE SET NULL)
 
 @enduml

docs/architecture/db/db-relationships.puml

@@ -66,7 +66,7 @@ package "Supporting" {
   entity audit_log
   entity geschichten
   entity geschichten_persons
-  entity geschichten_documents
+  entity journey_items
 }
 
 ' Auth relationships
@@ -129,7 +129,7 @@ audit_log }o--o| documents : document_id
 geschichten }o--o| app_users : author_id
 geschichten_persons }o--|| geschichten : geschichte_id
 geschichten_persons }o--|| persons : person_id
-geschichten_documents }o--|| geschichten : geschichte_id
-geschichten_documents }o--|| documents : document_id
+journey_items }o--|| geschichten : geschichte_id (ON DELETE CASCADE)
+journey_items }o--o| documents : document_id (ON DELETE SET NULL)
 
 @enduml

docs/specs/lesereisen-editor-spec.html

@@ -500,7 +500,7 @@
           <thead><tr><th>Element</th><th>Wert</th><th>Hinweise</th></tr></thead>
           <tbody>
             <tr class="grp"><td colspan="3">Item-Zeile allgemein</td></tr>
-            <tr><td>Item-Container</td><td>flex items-stretch bg-white border border-line rounded-sm mb-2 overflow-hidden</td><td>interlude: bg-orange-50 border-orange-200</td></tr>
+            <tr><td>Item-Container</td><td>flex items-stretch bg-white border border-line rounded-sm mb-2 overflow-hidden</td><td>interlude: <del>bg-orange-50 border-orange-200</del> → <code>--color-interlude-bg</code> / <code>--color-interlude-border</code> CSS tokens</td></tr>
             <tr><td>Drag-Handle</td><td>w-4 bg-surface border-r border-line flex items-center justify-center cursor-grab shrink-0</td><td>aria-label="Reihenfolge ändern"; cursor-grabbing während Drag</td></tr>
             <tr><td>Positions-Nr.</td><td>w-5 text-[10px] font-bold text-ink-3 flex items-start justify-center pt-2 shrink-0</td><td>aus Array-Index, nicht item.position</td></tr>
             <tr><td>Entfernen-Button</td><td>w-6 flex items-start justify-center pt-2 shrink-0</td><td>× aria-label="Eintrag entfernen"; hover: text-red-500; Confirm nur wenn note vorhanden</td></tr>
@@ -508,18 +508,18 @@
             <tr><td>Brieftitel</td><td>text-[11px] font-semibold text-ink leading-snug mb-0.5</td><td>document.title</td></tr>
             <tr><td>Briefmeta</td><td>text-xs text-ink-3</td><td>formatDate(doc.documentDate) · "von X" oder "von X an Y"</td></tr>
             <tr><td>Notiz-Textarea (sichtbar)</td><td>w-full min-h-[40px] font-serif text-xs italic bg-surface border border-line rounded-sm p-1.5 resize-none focus:border-primary focus:bg-white mt-2</td><td>auto-expand; bind:value={item.note}</td></tr>
-            <tr><td>„Notiz hinzufügen" Link</td><td>text-xs font-semibold text-blue-600 inline-flex items-center gap-1 mt-1</td><td>togglet Notiz-Textarea</td></tr>
+            <tr><td>„Notiz hinzufügen" Link</td><td><del>text-xs font-semibold text-blue-600</del> → <code>text-xs text-ink-3 underline hover:text-accent</code></td><td>togglet Notiz-Textarea</td></tr>
             <tr><td>„Notiz entfernen" Link</td><td>text-xs text-ink-3 inline-flex items-center gap-1 mt-1</td><td>zeigt sich wenn note.trim() nicht leer; setzt note = '' und blendet Textarea aus</td></tr>
             <tr class="grp"><td colspan="3">Interlude-Item</td></tr>
-            <tr><td>Interlude-Container</td><td>bg-orange-50 border-orange-200 (überschreibt Item-Container)</td><td>kein Positions-Kreis; Positions-Spalte zeigt Icon statt Zahl</td></tr>
-            <tr><td>Label „Zwischentext"</td><td>text-[9px] font-bold uppercase tracking-widest text-orange-700 mb-1</td><td>immer sichtbar; nicht editierbar</td></tr>
-            <tr><td>Zwischentext-Textarea</td><td>w-full min-h-[44px] font-serif text-xs italic bg-white/60 border border-orange-200 rounded-sm p-1.5 resize-none focus:border-orange-400</td><td>bind:value={item.note}; auto-expand; min 44px für Touch-Target</td></tr>
+            <tr><td>Interlude-Container</td><td><del>bg-orange-50 border-orange-200</del> → <code>--color-interlude-bg</code> left-accent border via <code>--color-interlude-border</code></td><td>kein Positions-Kreis; Positions-Spalte zeigt Icon statt Zahl</td></tr>
+            <tr><td>Label „Zwischentext"</td><td><del>text-orange-700</del> → <code>color: var(--color-interlude-label)</code></td><td>immer sichtbar; nicht editierbar</td></tr>
+            <tr><td>Zwischentext-Textarea</td><td><del>border-orange-200 focus:border-orange-400</del> → <code>border-line focus-visible:ring-focus-ring</code></td><td>bind:value={item.note}; auto-expand; min 44px für Touch-Target</td></tr>
             <tr class="grp"><td colspan="3">Aktionsleiste</td></tr>
             <tr><td>Add Bar</td><td>flex gap-2 pt-2 pb-1</td><td>immer unten sichtbar, auch wenn Liste gefüllt</td></tr>
             <tr><td>„Brief hinzufügen" Button</td><td>border border-dashed border-line rounded-sm px-3 py-1.5 text-xs font-semibold text-ink-2 hover:border-primary hover:text-primary flex items-center gap-1</td><td>öffnet existierende DocumentPicker-Komponente als Dropdown/Modal</td></tr>
             <tr><td>„Zwischentext hinzufügen" Button</td><td>gleich wie Brief-Button</td><td>fügt neues Interlude-Item am Ende ein; Fokus auf das neue Textarea</td></tr>
             <tr class="grp"><td colspan="3">Drag-to-Reorder</td></tr>
-            <tr><td>Bibliothek</td><td>@dnd-kit/core oder svelte-dnd-action (bereits im Projekt prüfen)</td><td>kein neues Package ohne Absprache</td></tr>
+            <tr><td>Bibliothek</td><td><del>@dnd-kit/core oder svelte-dnd-action</del> → <code>createBlockDragDrop&lt;JourneyItemView&gt;</code> aus <code>$lib/document/transcription/useBlockDragDrop.svelte</code></td><td>kein externes Package; pointer-Events + data-drag-handle / data-block-wrapper Kontrakt</td></tr>
             <tr><td>Reorder-API-Call</td><td>PUT /api/geschichten/{id}/items/reorder — body: [{id, position}] für alle Items</td><td>nach jedem Drop ausgelöst; optimistisch: lokalen State sofort aktualisieren</td></tr>
             <tr><td>Accessibility</td><td>Drag-Handle: role="button" tabIndex=0; Keyboard: Space startet Drag, Arrow hoch/runter verschiebt, Space/Enter bestätigt, Esc abbricht</td><td>WCAG 2.1 SC 2.1.1</td></tr>
           </tbody>
@@ -720,7 +720,7 @@
             <tr><td>Split entfällt</td><td>@media (max-width: 768px): flex-col; Sidebar-Sektionen als Collapsibles am Ende</td><td>gleich wie GeschichteEditor auf Mobile</td></tr>
             <tr><td>Collapsibles</td><td>details/summary oder eigene boolean-Toggle; Personen + Status separat</td><td>geschlossen beim ersten Laden; Fokus öffnet</td></tr>
             <tr class="grp"><td colspan="3">Touch &amp; Drag</td></tr>
-            <tr><td>Drag auf Mobile</td><td>Long-Press (500ms) auf dem Drag-Handle aktiviert Drag</td><td>dnd-kit unterstützt Touch nativ; kein separates Config nötig</td></tr>
+            <tr><td>Drag auf Mobile</td><td>Move-Up/Down Buttons statt Drag (44px touch targets)</td><td><del>dnd-kit unterstützt Touch nativ</del> → Pointer-Drag nur Desktop; Keyboard via Pfeil-Buttons</td></tr>
             <tr><td>Touch Target Items</td><td>min-h-[44px] für jede Item-Zeile</td><td>WCAG 2.2 AA; durch Padding gesichert</td></tr>
             <tr><td>Add-Buttons</td><td>flex-1; volle verfügbare Breite geteilt</td><td>min-h-[44px] als Touch-Target</td></tr>
             <tr class="grp"><td colspan="3">Savebar</td></tr>
@@ -779,7 +779,7 @@
 
     <h3>Drag-to-Reorder</h3>
     <ul>
-      <li>Bibliothek: prüfe zunächst ob <code>@dnd-kit/core</code> oder <code>svelte-dnd-action</code> bereits im <code>package.json</code> ist. Kein neues Package einführen ohne Absprache.</li>
+      <li><del>Bibliothek: prüfe zunächst ob <code>@dnd-kit/core</code> oder <code>svelte-dnd-action</code> bereits im <code>package.json</code> ist.</del> → Implementiert mit <code>createBlockDragDrop&lt;JourneyItemView&gt;</code> (kein externes Package).</li>
       <li>Nach dem Drop: neue Reihenfolge als Array <code>[{id, position}]</code> berechnen (position = index * 10 lässt Lücken für künftige Inserts) und <code>PUT /items/reorder</code> senden.</li>
       <li>Keyboard-Drag: Space/Enter startet, Arrow Up/Down verschiebt, Space/Enter bestätigt, Escape abbricht. Screenreader-Announcement: „Eintrag X von Position Y nach Z verschoben".</li>
     </ul>

frontend/CLAUDE.md

@@ -28,7 +28,6 @@ src/
 │   ├── +layout.server.ts # Loads current user, injects auth cookie
 │   ├── +page.svelte     # Home / document search dashboard
 │   ├── documents/       # Document CRUD, detail, edit, upload
-│   ├── search/          # Smart (NL) search sub-components — SmartModeToggle, InterpretationChipRow, SmartSearchStatus, DisambiguationPicker (no +page; consumed by documents/ and SearchFilterBar)
 │   ├── persons/         # Person directory (filtered, paginated), detail, edit, merge, review (triage)
 │   ├── aktivitaeten/    # Unified activity feed (Chronik)
 │   ├── admin/           # User, group, tag, OCR, system management

frontend/e2e/nl-search.spec.ts

@@ -1,113 +0,0 @@
-import AxeBuilder from '@axe-core/playwright';
-import { test, expect } from '@playwright/test';
-
-// NL search is mocked at the network boundary — Ollama is not required in CI.
-// CSRF enforcement is bypassed by page.route (the real request is never sent),
-// so it is only verified in manual full-stack runs (see issue #739 DevOps notes).
-const interpretation = {
-	resolvedPersons: [
-		{ id: '11111111-1111-1111-1111-111111111111', displayName: 'Walter Raddatz' },
-		{ id: '22222222-2222-2222-2222-222222222222', displayName: 'Emma Raddatz' }
-	],
-	ambiguousPersons: [],
-	dateFrom: '1914-01-01',
-	dateTo: '1918-12-31',
-	keywords: ['krieg'],
-	resolvedTags: [{ id: '33333333-3333-3333-3333-333333333333', name: 'Weltkrieg', color: 'sage' }],
-	rawQuery: 'Was hat Walter an Emma im Krieg geschrieben?',
-	keywordsApplied: true,
-	tagsApplied: true
-};
-
-const nlResponse = {
-	result: {
-		items: [],
-		totalElements: 0,
-		pageNumber: 0,
-		pageSize: 20,
-		totalPages: 0,
-		undatedCount: 0
-	},
-	interpretation
-};
-
-test.describe('NL (smart) search — happy path', () => {
-	test('toggle → loading → chips → remove chip re-runs keyword search; axe clean light + dark', async ({
-		page
-	}) => {
-		// Deliberate delay so the loading state is assertable before the response arrives.
-		await page.route('**/api/search/nl', async (route) => {
-			await new Promise((resolve) => setTimeout(resolve, 150));
-			await route.fulfill({
-				status: 200,
-				contentType: 'application/json',
-				body: JSON.stringify(nlResponse)
-			});
-		});
-
-		await page.goto('/documents');
-		await page.waitForSelector('[data-hydrated]');
-
-		// Switch to smart mode via the toggle pill (keyword label = "Text").
-		await page.getByRole('button', { name: /Text/ }).click();
-
-		const input = page.getByPlaceholder('Titel, Personen, Tags durchsuchen…');
-		await input.fill('Was hat Walter an Emma im Krieg geschrieben?');
-		await input.press('Enter');
-
-		// Loading panel announced to screen readers.
-		await expect(page.getByText(/Archiv wird befragt/)).toBeVisible();
-
-		// Directional chip (Walter → Emma) + keyword chip + theme chip render once the fixture resolves.
-		await expect(page.getByText('→')).toBeVisible();
-		await expect(page.getByText('Stichwort: krieg')).toBeVisible();
-		await expect(page.getByText(/Thema:.*Weltkrieg/)).toBeVisible();
-
-		// Accessibility — light mode.
-		const lightScan = await new AxeBuilder({ page })
-			.include('[data-testid="smart-search-results"]')
-			.analyze();
-		expect(lightScan.violations).toEqual([]);
-
-		// Accessibility — dark mode.
-		await page.evaluate(() => document.documentElement.setAttribute('data-theme', 'dark'));
-		const darkScan = await new AxeBuilder({ page })
-			.include('[data-testid="smart-search-results"]')
-			.analyze();
-		expect(darkScan.violations).toEqual([]);
-		await page.evaluate(() => document.documentElement.setAttribute('data-theme', 'light'));
-
-		// Removing the keyword chip re-runs a keyword GET with the remaining resolved
-		// params (sender + receiver from the directional pair).
-		await page.getByRole('button', { name: 'Filter entfernen: Stichwort: krieg' }).click();
-		await page.waitForURL(/senderId=11111111-1111-1111-1111-111111111111/);
-		await expect(page).toHaveURL(/receiverId=22222222-2222-2222-2222-222222222222/);
-	});
-
-	test('removing the last theme chip drops tag/tagOp but keeps person params', async ({ page }) => {
-		await page.route('**/api/search/nl', async (route) => {
-			await route.fulfill({
-				status: 200,
-				contentType: 'application/json',
-				body: JSON.stringify(nlResponse)
-			});
-		});
-
-		await page.goto('/documents');
-		await page.waitForSelector('[data-hydrated]');
-		await page.getByRole('button', { name: /Text/ }).click();
-
-		const input = page.getByPlaceholder('Titel, Personen, Tags durchsuchen…');
-		await input.fill('Was hat Walter an Emma im Krieg geschrieben?');
-		await input.press('Enter');
-
-		await expect(page.getByText(/Thema:.*Weltkrieg/)).toBeVisible();
-
-		// Remove the single theme chip — URL must carry sender UUID but no tag/tagOp.
-		await page.getByRole('button', { name: 'Filter entfernen: Thema: Weltkrieg' }).click();
-		await page.waitForURL(/senderId=11111111-1111-1111-1111-111111111111/);
-		const url = page.url();
-		expect(url).not.toMatch(/tag=/);
-		expect(url).not.toMatch(/tagOp=/);
-	});
-});

frontend/messages/de.json

@@ -22,33 +22,6 @@
 	"error_forbidden": "Sie haben keine Berechtigung für diese Aktion.",
 	"error_csrf_token_missing": "Sitzungsfehler. Bitte laden Sie die Seite neu.",
 	"error_too_many_login_attempts": "Zu viele Anmeldeversuche. Bitte versuchen Sie es später erneut.",
-	"error_smart_search_unavailable": "Die intelligente Suche ist momentan nicht verfügbar. Bitte nutzen Sie die normale Suche.",
-	"error_smart_search_rate_limited": "Sie haben die Suchfunktion zu häufig genutzt. Bitte warten Sie eine Minute.",
-	"smart_search_keywords_not_applied": "Schlüsselwörter konnten bei dieser Suche nicht berücksichtigt werden.",
-	"search_toggle_smart_label": "KI",
-	"search_toggle_smart_label_suffix": "-Suche",
-	"search_toggle_keyword_label": "Text",
-	"search_toggle_keyword_label_suffix": "suche",
-	"search_loading_nl": "Archiv wird befragt…",
-	"search_loading_nl_sub": "Die KI analysiert Ihre Anfrage. Das kann bis zu 15 Sekunden dauern.",
-	"search_error_unavailable": "Intelligente Suche nicht verfügbar",
-	"search_error_unavailable_body": "Die KI-Suche ist momentan nicht erreichbar. Sie können Ihre Anfrage als einfache Volltextsuche wiederholen.",
-	"search_switch_to_keyword": "Zur Volltextsuche wechseln",
-	"search_error_rate_limited": "Zu viele Anfragen",
-	"search_error_rate_limited_body": "Sie haben die intelligente Suche zu häufig genutzt. Bitte warten Sie eine Minute und versuchen Sie es erneut.",
-	"search_empty_nl": "Keine Ergebnisse",
-	"search_empty_retry_keyword": "Als Volltextsuche wiederholen",
-	"search_filter_remove_label": "Filter entfernen: {label}",
-	"search_chip_sender": "Absender",
-	"search_chip_date": "Zeitraum",
-	"search_chip_keyword": "Stichwort",
-	"search_chip_theme_prefix": "Thema",
-	"search_chip_directional_label": "Von {from} zu {to}, Filter entfernen",
-	"search_disambiguation_trigger_label": "Mehrere Personen gefunden — zum Auswählen klicken",
-	"search_disambiguation_cue": "(auswählen…)",
-	"search_disambiguation_heading": "Person auswählen",
-	"search_disambiguation_did_you_mean": "Meintest du {name}?",
-	"search_disambiguation_select_label": "{name} auswählen",
 	"error_validation_error": "Die Eingabe ist ungültig.",
 	"error_internal_error": "Ein unerwarteter Fehler ist aufgetreten.",
 	"nav_documents": "Dokumente",
@@ -328,6 +301,7 @@
 	"comp_multiselect_placeholder": "Namen tippen...",
 	"comp_multiselect_remove": "Entfernen",
 	"comp_multiselect_loading": "Suche...",
+	"comp_typeahead_error": "Suche fehlgeschlagen. Bitte versuchen Sie es erneut.",
 	"comp_taginput_placeholder_create": "Schlagworte hinzufügen...",
 	"comp_taginput_placeholder_filter": "Nach Schlagworten filtern...",
 	"comp_taginput_remove": "Schlagwort entfernen",
@@ -1050,6 +1024,11 @@
 	"nav_stammbaum": "Stammbaum",
 	"nav_geschichten": "Geschichten",
 	"error_geschichte_not_found": "Die Geschichte wurde nicht gefunden.",
+	"error_journey_item_not_found": "Der Reise-Eintrag wurde nicht gefunden.",
+	"error_journey_item_position_conflict": "Die Reihenfolge wurde gerade von jemand anderem geändert – bitte laden Sie die Seite neu.",
+	"error_journey_at_capacity": "Die Lesereise hat bereits die maximale Anzahl von Einträgen (100) erreicht.",
+	"error_geschichte_type_mismatch": "Diese Geschichte ist keine Lesereise – Reise-Einträge sind hier nicht erlaubt.",
+	"journey_item_document_deleted": "[Dokument gelöscht]",
 	"geschichten_index_title": "Geschichten",
 	"geschichten_new_button": "Neue Geschichte",
 	"geschichten_filter_all_pill": "Alle",
@@ -1064,6 +1043,7 @@
 	"geschichten_published_on": "veröffentlicht am {date}",
 	"geschichten_persons_section": "Personen in dieser Geschichte",
 	"geschichten_documents_section": "Erwähnte Dokumente",
+	"geschichten_document_link_placeholder": "Dokument öffnen",
 	"geschichten_card_heading": "Geschichten",
 	"geschichten_card_write_action": "+ Geschichte schreiben",
 	"geschichten_card_attach_action": "+ Geschichte anhängen",
@@ -1071,6 +1051,7 @@
 	"geschichten_card_show_all": "Alle anzeigen",
 	"geschichte_editor_title_placeholder": "Titel der Geschichte",
 	"geschichte_editor_body_placeholder": "Schreibe hier deine Geschichte…",
+	"geschichte_sidebar_status": "Status",
 	"geschichte_editor_status_draft": "ENTWURF",
 	"geschichte_editor_status_published": "VERÖFFENTLICHT",
 	"geschichte_editor_status_draft_hint": "Noch nicht öffentlich sichtbar.",
@@ -1180,5 +1161,50 @@
 	"themen_alle": "Alle Themen",
 	"themen_leer": "Noch keine Themen vergeben.",
 	"themen_weitere": "+ {count} weitere",
-	"themen_dokumente": "{count} Dokumente"
+	"themen_dokumente": "{count} Dokumente",
+	"journey_badge_list": "REISE",
+	"journey_badge_detail": "LESEREISE",
+	"journey_selector_question": "Was möchtest du erstellen?",
+	"journey_selector_story_title": "Geschichte",
+	"journey_selector_story_desc": "Eine erzählte Geschichte mit Bildern und Text.",
+	"journey_selector_journey_title": "Lesereise",
+	"journey_selector_journey_desc": "Eine kuratierte Auswahl von Briefen mit Notizen.",
+	"journey_selector_next_btn": "Weiter",
+	"journey_placeholder_back": "andere Auswahl",
+	"journey_create_submit": "Lesereise erstellen",
+	"journey_item_open_aria": "Brief vom {date} öffnen",
+	"journey_item_open_aria_undated": "Brief öffnen",
+	"journey_empty_state": "Diese Lesereise ist noch leer.",
+	"journey_interlude_aria_label": "Kuratorennotiz",
+	"journey_selector_aria_live_hint": "Bitte wähle einen Typ aus, um fortzufahren.",
+	"journey_add_document": "Brief hinzufügen",
+	"journey_add_interlude": "Zwischentext hinzufügen",
+	"journey_note_add": "Notiz hinzufügen",
+	"journey_note_remove": "Notiz entfernen",
+	"journey_note_save_hint": "Wird gespeichert, wenn du das Feld verlässt.",
+	"journey_intro_save_hint": "Wird mit 'Speichern' gesichert.",
+	"journey_already_added": "Bereits enthalten",
+	"journey_note_aria_label": "Kuratoren-Notiz für {title}",
+	"journey_drag_aria_label": "Reihenfolge von '{title}' ändern",
+	"journey_move_up": "'{title}' nach oben verschieben",
+	"journey_move_down": "'{title}' nach unten verschieben",
+	"journey_note_error": "Notiz konnte nicht gespeichert werden",
+	"journey_item_moved": "Eintrag {position} von {total} — nach Position {newPosition} verschoben",
+	"journey_remove_item_aria": "Eintrag entfernen",
+	"journey_remove_confirm": "Wirklich entfernen?",
+	"journey_remove_confirm_yes": "Bestätigen",
+	"journey_remove_confirm_cancel": "Abbrechen",
+	"journey_mutation_error_reload": "Aktion fehlgeschlagen – bitte Seite neu laden.",
+	"journey_published_empty_warning": "Diese Reise wird ohne Einträge veröffentlicht bleiben.",
+	"journey_intro_placeholder": "Einleitung (optional)",
+	"journey_interlude_placeholder": "Zwischentext eingeben…",
+	"journey_add_interlude_confirm": "Hinzufügen",
+	"journey_edit_title_story": "Geschichte bearbeiten",
+	"journey_edit_title_journey": "Lesereise bearbeiten",
+	"journey_publish_disabled_title": "Titel und mindestens ein Eintrag erforderlich",
+	"journey_save_hint_published": "Änderungen werden sofort für alle Leser sichtbar.",
+	"error_journey_item_not_in_journey": "Dieser Eintrag gehört nicht zu dieser Lesereise.",
+	"error_journey_note_too_long": "Die Notiz ist zu lang (maximal 2000 Zeichen).",
+	"error_journey_document_already_added": "Dieser Brief ist bereits in der Lesereise enthalten.",
+	"error_geschichte_type_immutable": "Der Typ einer Geschichte kann nach der Erstellung nicht mehr geändert werden."
 }

frontend/messages/en.json

@@ -22,33 +22,6 @@
 	"error_forbidden": "You do not have permission for this action.",
 	"error_csrf_token_missing": "Session error. Please reload the page.",
 	"error_too_many_login_attempts": "Too many login attempts. Please try again later.",
-	"error_smart_search_unavailable": "The smart search is currently unavailable. Please use the regular search.",
-	"error_smart_search_rate_limited": "You have used the search function too frequently. Please wait a minute.",
-	"smart_search_keywords_not_applied": "Keywords could not be applied to this search.",
-	"search_toggle_smart_label": "AI",
-	"search_toggle_smart_label_suffix": " search",
-	"search_toggle_keyword_label": "Text",
-	"search_toggle_keyword_label_suffix": " search",
-	"search_loading_nl": "Querying the archive…",
-	"search_loading_nl_sub": "The AI is analysing your request. This can take up to 15 seconds.",
-	"search_error_unavailable": "Smart search unavailable",
-	"search_error_unavailable_body": "The AI search is currently unreachable. You can repeat your request as a plain full-text search.",
-	"search_switch_to_keyword": "Switch to full-text search",
-	"search_error_rate_limited": "Too many requests",
-	"search_error_rate_limited_body": "You have used the smart search too frequently. Please wait a minute and try again.",
-	"search_empty_nl": "No results",
-	"search_empty_retry_keyword": "Repeat as full-text search",
-	"search_filter_remove_label": "Remove filter: {label}",
-	"search_chip_sender": "Sender",
-	"search_chip_date": "Period",
-	"search_chip_keyword": "Keyword",
-	"search_chip_theme_prefix": "Topic",
-	"search_chip_directional_label": "From {from} to {to}, remove filter",
-	"search_disambiguation_trigger_label": "Several people found — click to choose",
-	"search_disambiguation_cue": "(choose…)",
-	"search_disambiguation_heading": "Choose a person",
-	"search_disambiguation_did_you_mean": "Did you mean {name}?",
-	"search_disambiguation_select_label": "Select {name}",
 	"error_validation_error": "The input is invalid.",
 	"error_internal_error": "An unexpected error occurred.",
 	"nav_documents": "Documents",
@@ -328,6 +301,7 @@
 	"comp_multiselect_placeholder": "Type a name...",
 	"comp_multiselect_remove": "Remove",
 	"comp_multiselect_loading": "Searching...",
+	"comp_typeahead_error": "Search failed. Please try again.",
 	"comp_taginput_placeholder_create": "Add tags...",
 	"comp_taginput_placeholder_filter": "Filter by tags...",
 	"comp_taginput_remove": "Remove tag",
@@ -1050,6 +1024,11 @@
 	"nav_stammbaum": "Family tree",
 	"nav_geschichten": "Stories",
 	"error_geschichte_not_found": "The story was not found.",
+	"error_journey_item_not_found": "The journey item was not found.",
+	"error_journey_item_position_conflict": "The order was just changed by someone else — please reload the page.",
+	"error_journey_at_capacity": "The reading journey has already reached the maximum of 100 items.",
+	"error_geschichte_type_mismatch": "This story is not a reading journey — journey items are not allowed here.",
+	"journey_item_document_deleted": "[Document deleted]",
 	"geschichten_index_title": "Stories",
 	"geschichten_new_button": "New story",
 	"geschichten_filter_all_pill": "All",
@@ -1064,6 +1043,7 @@
 	"geschichten_published_on": "published on {date}",
 	"geschichten_persons_section": "People in this story",
 	"geschichten_documents_section": "Referenced documents",
+	"geschichten_document_link_placeholder": "Open document",
 	"geschichten_card_heading": "Stories",
 	"geschichten_card_write_action": "+ Write a story",
 	"geschichten_card_attach_action": "+ Attach a story",
@@ -1071,6 +1051,7 @@
 	"geschichten_card_show_all": "Show all",
 	"geschichte_editor_title_placeholder": "Story title",
 	"geschichte_editor_body_placeholder": "Write your story here…",
+	"geschichte_sidebar_status": "Status",
 	"geschichte_editor_status_draft": "DRAFT",
 	"geschichte_editor_status_published": "PUBLISHED",
 	"geschichte_editor_status_draft_hint": "Not yet visible to readers.",
@@ -1180,5 +1161,50 @@
 	"themen_alle": "All Topics",
 	"themen_leer": "No topics assigned yet.",
 	"themen_weitere": "+ {count} more",
-	"themen_dokumente": "{count} documents"
+	"themen_dokumente": "{count} documents",
+	"journey_badge_list": "JOURNEY",
+	"journey_badge_detail": "READING JOURNEY",
+	"journey_selector_question": "What would you like to create?",
+	"journey_selector_story_title": "Story",
+	"journey_selector_story_desc": "A narrative story with images and text.",
+	"journey_selector_journey_title": "Reading Journey",
+	"journey_selector_journey_desc": "A curated selection of letters with notes.",
+	"journey_selector_next_btn": "Continue",
+	"journey_placeholder_back": "different selection",
+	"journey_create_submit": "Create reading journey",
+	"journey_item_open_aria": "Open letter from {date}",
+	"journey_item_open_aria_undated": "Open letter",
+	"journey_empty_state": "This reading journey is still empty.",
+	"journey_interlude_aria_label": "Curator's note",
+	"journey_selector_aria_live_hint": "Please select a type to continue.",
+	"journey_add_document": "Add letter",
+	"journey_add_interlude": "Add interlude",
+	"journey_note_add": "Add note",
+	"journey_note_remove": "Remove note",
+	"journey_note_save_hint": "Saved when you leave the field.",
+	"journey_intro_save_hint": "Saved when you click 'Save'.",
+	"journey_already_added": "Already included",
+	"journey_note_aria_label": "Curator note for {title}",
+	"journey_drag_aria_label": "Change order of '{title}'",
+	"journey_move_up": "Move '{title}' up",
+	"journey_move_down": "Move '{title}' down",
+	"journey_note_error": "Could not save note",
+	"journey_item_moved": "Entry {position} of {total} — moved to position {newPosition}",
+	"journey_remove_item_aria": "Remove item",
+	"journey_remove_confirm": "Really remove?",
+	"journey_remove_confirm_yes": "Confirm",
+	"journey_remove_confirm_cancel": "Cancel",
+	"journey_mutation_error_reload": "Action failed – please reload the page.",
+	"journey_published_empty_warning": "This journey will remain published without any entries.",
+	"journey_intro_placeholder": "Introduction (optional)",
+	"journey_interlude_placeholder": "Enter interlude text…",
+	"journey_add_interlude_confirm": "Add",
+	"journey_edit_title_story": "Edit story",
+	"journey_edit_title_journey": "Edit reading journey",
+	"journey_publish_disabled_title": "Title and at least one entry required",
+	"journey_save_hint_published": "Changes will be immediately visible to all readers.",
+	"error_journey_item_not_in_journey": "This entry does not belong to this reading journey.",
+	"error_journey_note_too_long": "The note is too long (maximum 2000 characters).",
+	"error_journey_document_already_added": "This letter is already included in the reading journey.",
+	"error_geschichte_type_immutable": "The type of a story cannot be changed after creation."
 }

frontend/messages/es.json

@@ -22,33 +22,6 @@
 	"error_forbidden": "No tiene permiso para realizar esta acción.",
 	"error_csrf_token_missing": "Error de sesión. Recargue la página.",
 	"error_too_many_login_attempts": "Demasiados intentos. Por favor, inténtelo más tarde.",
-	"error_smart_search_unavailable": "La búsqueda inteligente no está disponible en este momento. Por favor, usa la búsqueda normal.",
-	"error_smart_search_rate_limited": "Has utilizado la función de búsqueda demasiadas veces. Por favor, espera un minuto.",
-	"smart_search_keywords_not_applied": "Las palabras clave no pudieron aplicarse a esta búsqueda.",
-	"search_toggle_smart_label": "IA",
-	"search_toggle_smart_label_suffix": " búsqueda",
-	"search_toggle_keyword_label": "Texto",
-	"search_toggle_keyword_label_suffix": " búsqueda",
-	"search_loading_nl": "Consultando el archivo…",
-	"search_loading_nl_sub": "La IA está analizando su solicitud. Esto puede tardar hasta 15 segundos.",
-	"search_error_unavailable": "Búsqueda inteligente no disponible",
-	"search_error_unavailable_body": "La búsqueda con IA no está disponible en este momento. Puede repetir su solicitud como una búsqueda de texto completo.",
-	"search_switch_to_keyword": "Cambiar a búsqueda de texto completo",
-	"search_error_rate_limited": "Demasiadas solicitudes",
-	"search_error_rate_limited_body": "Ha utilizado la búsqueda inteligente con demasiada frecuencia. Espere un minuto e inténtelo de nuevo.",
-	"search_empty_nl": "Sin resultados",
-	"search_empty_retry_keyword": "Repetir como búsqueda de texto completo",
-	"search_filter_remove_label": "Eliminar filtro: {label}",
-	"search_chip_sender": "Remitente",
-	"search_chip_date": "Período",
-	"search_chip_keyword": "Palabra clave",
-	"search_chip_theme_prefix": "Tema",
-	"search_chip_directional_label": "De {from} a {to}, eliminar filtro",
-	"search_disambiguation_trigger_label": "Se encontraron varias personas — haga clic para elegir",
-	"search_disambiguation_cue": "(elegir…)",
-	"search_disambiguation_heading": "Elegir una persona",
-	"search_disambiguation_did_you_mean": "¿Quería decir {name}?",
-	"search_disambiguation_select_label": "Seleccionar {name}",
 	"error_validation_error": "La entrada no es válida.",
 	"error_internal_error": "Se ha producido un error inesperado.",
 	"nav_documents": "Documentos",
@@ -328,6 +301,7 @@
 	"comp_multiselect_placeholder": "Escriba un nombre...",
 	"comp_multiselect_remove": "Eliminar",
 	"comp_multiselect_loading": "Buscando...",
+	"comp_typeahead_error": "La búsqueda falló. Inténtelo de nuevo.",
 	"comp_taginput_placeholder_create": "Añadir etiquetas...",
 	"comp_taginput_placeholder_filter": "Filtrar por etiquetas...",
 	"comp_taginput_remove": "Eliminar etiqueta",
@@ -1050,6 +1024,11 @@
 	"nav_stammbaum": "Árbol genealógico",
 	"nav_geschichten": "Historias",
 	"error_geschichte_not_found": "No se encontró la historia.",
+	"error_journey_item_not_found": "No se encontró el elemento del viaje.",
+	"error_journey_item_position_conflict": "El orden fue cambiado por otra persona — por favor recargue la página.",
+	"error_journey_at_capacity": "El viaje de lectura ya ha alcanzado el máximo de 100 entradas.",
+	"error_geschichte_type_mismatch": "Esta historia no es un viaje de lectura — los elementos de viaje no están permitidos aquí.",
+	"journey_item_document_deleted": "[Documento eliminado]",
 	"geschichten_index_title": "Historias",
 	"geschichten_new_button": "Nueva historia",
 	"geschichten_filter_all_pill": "Todas",
@@ -1064,6 +1043,7 @@
 	"geschichten_published_on": "publicada el {date}",
 	"geschichten_persons_section": "Personas en esta historia",
 	"geschichten_documents_section": "Documentos mencionados",
+	"geschichten_document_link_placeholder": "Abrir documento",
 	"geschichten_card_heading": "Historias",
 	"geschichten_card_write_action": "+ Escribir historia",
 	"geschichten_card_attach_action": "+ Adjuntar historia",
@@ -1071,6 +1051,7 @@
 	"geschichten_card_show_all": "Mostrar todas",
 	"geschichte_editor_title_placeholder": "Título de la historia",
 	"geschichte_editor_body_placeholder": "Escribe tu historia aquí…",
+	"geschichte_sidebar_status": "Estado",
 	"geschichte_editor_status_draft": "BORRADOR",
 	"geschichte_editor_status_published": "PUBLICADA",
 	"geschichte_editor_status_draft_hint": "Aún no visible para lectores.",
@@ -1180,5 +1161,50 @@
 	"themen_alle": "Todos los temas",
 	"themen_leer": "Aún no hay temas.",
 	"themen_weitere": "+ {count} más",
-	"themen_dokumente": "{count} documentos"
+	"themen_dokumente": "{count} documentos",
+	"journey_badge_list": "VIAJE",
+	"journey_badge_detail": "VIAJE DE LECTURA",
+	"journey_selector_question": "¿Qué deseas crear?",
+	"journey_selector_story_title": "Historia",
+	"journey_selector_story_desc": "Una historia narrada con imágenes y texto.",
+	"journey_selector_journey_title": "Viaje de lectura",
+	"journey_selector_journey_desc": "Una selección curada de cartas con notas.",
+	"journey_selector_next_btn": "Continuar",
+	"journey_placeholder_back": "otra selección",
+	"journey_create_submit": "Crear viaje de lectura",
+	"journey_item_open_aria": "Abrir carta del {date}",
+	"journey_item_open_aria_undated": "Abrir carta",
+	"journey_empty_state": "Este viaje de lectura está vacío.",
+	"journey_interlude_aria_label": "Nota del curador",
+	"journey_selector_aria_live_hint": "Por favor, selecciona un tipo para continuar.",
+	"journey_add_document": "Añadir carta",
+	"journey_add_interlude": "Añadir interludio",
+	"journey_note_add": "Añadir nota",
+	"journey_note_remove": "Eliminar nota",
+	"journey_note_save_hint": "Se guarda al salir del campo.",
+	"journey_intro_save_hint": "Se guarda al hacer clic en 'Guardar'.",
+	"journey_already_added": "Ya incluido",
+	"journey_note_aria_label": "Nota del curador para {title}",
+	"journey_drag_aria_label": "Cambiar el orden de '{title}'",
+	"journey_move_up": "Subir '{title}'",
+	"journey_move_down": "Bajar '{title}'",
+	"journey_note_error": "No se pudo guardar la nota",
+	"journey_item_moved": "Entrada {position} de {total} — movida a la posición {newPosition}",
+	"journey_remove_item_aria": "Eliminar entrada",
+	"journey_remove_confirm": "¿Realmente eliminar?",
+	"journey_remove_confirm_yes": "Confirmar",
+	"journey_remove_confirm_cancel": "Cancelar",
+	"journey_mutation_error_reload": "Acción fallida – por favor recarga la página.",
+	"journey_published_empty_warning": "Este viaje permanecerá publicado sin entradas.",
+	"journey_intro_placeholder": "Introducción (opcional)",
+	"journey_interlude_placeholder": "Escribe el texto del interludio…",
+	"journey_add_interlude_confirm": "Añadir",
+	"journey_edit_title_story": "Editar historia",
+	"journey_edit_title_journey": "Editar viaje de lectura",
+	"journey_publish_disabled_title": "Se requiere título y al menos una entrada",
+	"journey_save_hint_published": "Los cambios serán visibles inmediatamente para todos los lectores.",
+	"error_journey_item_not_in_journey": "Esta entrada no pertenece a este viaje de lectura.",
+	"error_journey_note_too_long": "La nota es demasiado larga (máximo 2000 caracteres).",
+	"error_journey_document_already_added": "Esta carta ya está incluida en el viaje de lectura.",
+	"error_geschichte_type_immutable": "El tipo de una historia no se puede cambiar después de su creación."
 }

frontend/src/lib/document/DashboardNeedsMetadata.svelte.spec.ts

@@ -52,6 +52,6 @@ describe('DashboardNeedsMetadata', () => {
 	it('uses totalCount in the footer even when topDocs has fewer items', async () => {
 		const docs = [makeDoc('d1', 'Only one')];
 		render(DashboardNeedsMetadata, { topDocs: docs, totalCount: 50 });
-		await expect.element(page.getByRole('link', { name: /50/ })).toBeInTheDocument();
+		await expect.element(page.getByRole('link', { name: /Alle 50/ })).toBeInTheDocument();
 	});
 });

frontend/src/lib/document/DocumentMultiSelect.svelte

@@ -1,21 +1,11 @@
 <script lang="ts">
-import type { components } from '$lib/generated/api';
 import { m } from '$lib/paraglide/messages.js';
 import { clickOutside } from '$lib/shared/actions/clickOutside';
-import { formatDocumentDate, type DatePrecision } from '$lib/shared/utils/documentDate';
-import { getLocale } from '$lib/paraglide/runtime.js';
-
-type DocumentListItem = components['schemas']['DocumentListItem'];
-
-/**
- * Exactly the fields this picker reads — id for selection/dedup, the rest for
- * the honest date label. A full `Document` and a `DocumentListItem` are both
- * structurally assignable, so the search results need no cast.
- */
-type DocumentOption = Pick<
-	DocumentListItem,
-	'id' | 'title' | 'documentDate' | 'metaDatePrecision' | 'metaDateEnd'
->;
+import {
+	createDocumentTypeahead,
+	formatDocumentOption,
+	type DocumentOption
+} from './documentTypeahead';
 
 interface Props {
 	selectedDocuments?: DocumentOption[];
@@ -30,13 +20,16 @@ let {
 }: Props = $props();
 
 let searchTerm = $state('');
-let results: DocumentOption[] = $state([]);
-let showDropdown = $state(false);
-let loading = $state(false);
-let debounceTimer: ReturnType<typeof setTimeout>;
 let inputEl: HTMLInputElement;
 let dropdownStyle = $state('');
 
+const picker = createDocumentTypeahead();
+
+// Filter out already-selected documents from typeahead results.
+const filteredResults = $derived(
+	picker.results.filter((d) => !selectedDocuments.some((s) => s.id === d.id))
+);
+
 function updateDropdownPosition() {
 	if (!inputEl) return;
 	const rect = inputEl.getBoundingClientRect();
@@ -44,57 +37,22 @@ function updateDropdownPosition() {
 }
 
 function handleInput() {
-	showDropdown = true;
-	clearTimeout(debounceTimer);
-	debounceTimer = setTimeout(async () => {
-		if (searchTerm.length < 1) {
-			results = [];
-			return;
-		}
-		loading = true;
-		try {
-			const res = await fetch(`/api/documents/search?q=${encodeURIComponent(searchTerm)}&size=10`);
-			if (res.ok) {
-				const body: { items: DocumentListItem[] } = await res.json();
-				const docs: DocumentOption[] = body.items.map((it) => ({
-					id: it.id,
-					title: it.title,
-					documentDate: it.documentDate,
-					metaDatePrecision: it.metaDatePrecision,
-					metaDateEnd: it.metaDateEnd
-				}));
-				results = docs.filter((d) => !selectedDocuments.some((s) => s.id === d.id));
-			}
-		} catch {
-			results = [];
-		} finally {
-			loading = false;
-		}
-	}, 300);
+	if (searchTerm.trim().length >= 1) {
+		picker.setQuery(searchTerm);
+	} else {
+		picker.close();
+	}
 }
 
 function selectDocument(doc: DocumentOption) {
 	selectedDocuments = [...selectedDocuments, doc];
 	searchTerm = '';
-	showDropdown = false;
-	results = [];
+	picker.close();
 }
 
 function removeDocument(id: string | undefined) {
 	selectedDocuments = selectedDocuments.filter((d) => d.id !== id);
 }
-
-function formatDocLabel(doc: DocumentOption): string {
-	if (!doc.documentDate) return doc.title;
-	const label = formatDocumentDate(
-		doc.documentDate,
-		doc.metaDatePrecision as DatePrecision,
-		doc.metaDateEnd,
-		null,
-		getLocale()
-	);
-	return `${doc.title} · ${label}`;
-}
 </script>
 
 <svelte:window onscroll={updateDropdownPosition} onresize={updateDropdownPosition} />
@@ -103,7 +61,7 @@ function formatDocLabel(doc: DocumentOption): string {
 	<input type="hidden" name={hiddenInputName} value={doc.id} />
 {/each}
 
-<div class="relative" use:clickOutside onclickoutside={() => (showDropdown = false)}>
+<div class="relative" use:clickOutside onclickoutside={() => picker.close()}>
 	<div
 		class="flex min-h-[38px] flex-wrap gap-2 rounded border border-line bg-surface p-2 shadow-sm focus-within:ring-2 focus-within:ring-focus-ring focus-within:outline-none"
 	>
@@ -111,7 +69,7 @@ function formatDocLabel(doc: DocumentOption): string {
 			<span
 				class="inline-flex items-center gap-1 rounded bg-muted px-2 py-1 text-sm font-medium text-ink"
 			>
-				{formatDocLabel(doc)}
+				{formatDocumentOption(doc)}
 				<button
 					type="button"
 					onclick={() => removeDocument(doc.id)}
@@ -136,24 +94,21 @@ function formatDocLabel(doc: DocumentOption): string {
 			autocomplete="off"
 			bind:value={searchTerm}
 			oninput={handleInput}
-			onfocus={() => {
-				updateDropdownPosition();
-				showDropdown = true;
-			}}
+			onfocus={() => updateDropdownPosition()}
 			placeholder={placeholder}
 			class="min-w-[120px] flex-1 border-none bg-transparent p-1 text-sm outline-none focus:ring-0"
 		/>
 	</div>
 
-	{#if showDropdown && (results.length > 0 || loading)}
+	{#if picker.isOpen && (filteredResults.length > 0 || picker.loading)}
 		<div
 			style={dropdownStyle}
 			class="ring-opacity-5 z-50 max-h-60 overflow-auto rounded-md bg-surface py-1 text-base shadow-lg ring-1 ring-black sm:text-sm"
 		>
-			{#if loading}
+			{#if picker.loading}
 				<div class="p-2 text-sm text-ink-2">{m.comp_multiselect_loading()}</div>
 			{:else}
-				{#each results as doc (doc.id)}
+				{#each filteredResults as doc (doc.id)}
 					<div
 						class="cursor-pointer py-2 pr-9 pl-3 text-ink select-none hover:bg-muted"
 						onclick={() => selectDocument(doc)}
@@ -161,7 +116,7 @@ function formatDocLabel(doc: DocumentOption): string {
 						role="button"
 						tabindex="0"
 					>
-						{formatDocLabel(doc)}
+						{formatDocumentOption(doc)}
 					</div>
 				{/each}
 			{/if}

frontend/src/lib/document/DocumentPickerDropdown.svelte

@@ -0,0 +1,98 @@
+<script module>
+let _uid = 0;
+</script>
+
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import { clickOutside } from '$lib/shared/actions/clickOutside';
+import {
+	createDocumentTypeahead,
+	formatDocumentOption,
+	type DocumentOption
+} from './documentTypeahead';
+
+interface Props {
+	alreadyAddedIds?: Set<string>;
+	placeholder?: string;
+	onSelect: (doc: DocumentOption) => void;
+}
+
+let {
+	alreadyAddedIds = new Set(),
+	placeholder = m.journey_add_document(),
+	onSelect
+}: Props = $props();
+
+const listboxId = `doc-picker-listbox-${++_uid}`;
+
+const picker = createDocumentTypeahead();
+
+let inputValue = $state('');
+
+function handleInput(e: Event) {
+	const q = (e.currentTarget as HTMLInputElement).value;
+	inputValue = q;
+	if (q.trim().length >= 1) {
+		picker.setQuery(q);
+	} else {
+		picker.close();
+	}
+}
+
+function handleSelect(doc: DocumentOption) {
+	if (alreadyAddedIds.has(doc.id!)) return;
+	inputValue = '';
+	picker.close();
+	onSelect(doc);
+}
+</script>
+
+<div use:clickOutside onclickoutside={() => picker.close()} class="relative">
+	<input
+		type="text"
+		role="combobox"
+		autocomplete="off"
+		aria-label={placeholder}
+		aria-expanded={picker.isOpen && picker.results.length > 0}
+		aria-controls={listboxId}
+		aria-autocomplete="list"
+		placeholder={placeholder}
+		value={inputValue}
+		oninput={handleInput}
+		class="block w-full rounded border border-line bg-surface px-3 py-2 text-sm text-ink placeholder:text-ink-3 focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+	/>
+
+	{#if picker.isOpen && (picker.results.length > 0 || picker.loading || picker.error)}
+		<ul
+			id={listboxId}
+			class="ring-opacity-5 absolute z-50 mt-1 max-h-60 w-full overflow-auto rounded-md bg-surface py-1 text-sm shadow-lg ring-1 ring-black"
+		>
+			{#if picker.loading}
+				<li class="px-3 py-2 text-ink-2">{m.comp_multiselect_loading()}</li>
+			{:else if picker.error}
+				<li role="alert" class="px-3 py-2 text-danger">{m.comp_typeahead_error()}</li>
+			{:else}
+				{#each picker.results as doc (doc.id)}
+					{@const disabled = alreadyAddedIds.has(doc.id!)}
+					<li
+						aria-disabled={disabled}
+						onclick={() => handleSelect(doc)}
+						onkeydown={(e) => e.key === 'Enter' && handleSelect(doc)}
+						tabindex={disabled ? -1 : 0}
+						class={[
+							'px-3 py-2 text-ink select-none',
+							disabled
+								? 'cursor-default opacity-50'
+								: 'cursor-pointer hover:bg-muted focus:bg-muted focus:outline-none'
+						].join(' ')}
+					>
+						{formatDocumentOption(doc)}
+						{#if disabled}
+							<span class="sr-only">{m.journey_already_added()}</span>
+						{/if}
+					</li>
+				{/each}
+			{/if}
+		</ul>
+	{/if}
+</div>

frontend/src/lib/document/DocumentPickerDropdown.svelte.spec.ts

@@ -0,0 +1,117 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page, userEvent } from 'vitest/browser';
+import DocumentPickerDropdown from './DocumentPickerDropdown.svelte';
+import { m } from '$lib/paraglide/messages.js';
+
+const waitForDebounce = () => new Promise((r) => setTimeout(r, 350));
+
+const docFactory = (id: string, title: string) => ({
+	id,
+	title,
+	documentDate: '1880-01-01',
+	metaDatePrecision: 'DAY' as const,
+	metaDateEnd: undefined
+});
+
+function mockSearchResponse(items: ReturnType<typeof docFactory>[]) {
+	vi.stubGlobal(
+		'fetch',
+		vi.fn().mockResolvedValue({
+			ok: true,
+			json: vi.fn().mockResolvedValue({ items })
+		})
+	);
+}
+
+afterEach(() => {
+	cleanup();
+	vi.unstubAllGlobals();
+});
+
+describe('DocumentPickerDropdown — empty query guard', () => {
+	it('does not call fetch on empty query', async () => {
+		const fetchMock = vi.fn();
+		vi.stubGlobal('fetch', fetchMock);
+
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+		await userEvent.fill(page.getByRole('combobox'), '');
+		await waitForDebounce();
+
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+});
+
+describe('DocumentPickerDropdown — already-added indicator', () => {
+	it('shows already-added document as aria-disabled with sr-only hint', async () => {
+		mockSearchResponse([docFactory('d1', 'Brief von Eugenie'), docFactory('d2', 'Brief 2')]);
+
+		render(DocumentPickerDropdown, {
+			alreadyAddedIds: new Set(['d1']),
+			onSelect: vi.fn()
+		});
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+
+		const disabledItem = page
+			.getByText(/Brief von Eugenie/i)
+			.element()
+			.closest('li')!;
+		expect(disabledItem.getAttribute('aria-disabled')).toBe('true');
+		// Screen-reader text "bereits enthalten" must be present in the item
+		await expect.element(page.getByText(/bereits enthalten/i)).toBeInTheDocument();
+	});
+});
+
+describe('DocumentPickerDropdown — selection', () => {
+	it('calls onSelect with the item when a non-disabled option is clicked', async () => {
+		const onSelect = vi.fn();
+		mockSearchResponse([docFactory('d1', 'Brief von Eugenie')]);
+
+		render(DocumentPickerDropdown, { onSelect });
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+		await userEvent.click(page.getByText(/Brief von Eugenie/i));
+
+		expect(onSelect).toHaveBeenCalledWith(expect.objectContaining({ id: 'd1' }));
+	});
+
+	it('does not call onSelect when an aria-disabled option is clicked', async () => {
+		const onSelect = vi.fn();
+		mockSearchResponse([docFactory('d1', 'Brief von Eugenie')]);
+
+		render(DocumentPickerDropdown, {
+			alreadyAddedIds: new Set(['d1']),
+			onSelect
+		});
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+		await page.getByText(/Brief von Eugenie/i).click({ force: true });
+
+		expect(onSelect).not.toHaveBeenCalled();
+	});
+});
+
+describe('DocumentPickerDropdown — search failure', () => {
+	it('shows an error message when the search request fails instead of vanishing', async () => {
+		// 500 from /api/documents/search — must surface, not render as "no results"
+		vi.stubGlobal(
+			'fetch',
+			vi.fn().mockResolvedValue({
+				ok: false,
+				status: 500,
+				json: vi.fn().mockResolvedValue({ code: 'INTERNAL_ERROR' })
+			})
+		);
+
+		render(DocumentPickerDropdown, { onSelect: vi.fn() });
+
+		await userEvent.fill(page.getByRole('combobox'), 'Brief');
+		await waitForDebounce();
+
+		await expect.element(page.getByText(m.comp_typeahead_error())).toBeInTheDocument();
+	});
+});

frontend/src/lib/document/documentTypeahead.ts

@@ -0,0 +1,45 @@
+import type { components } from '$lib/generated/api';
+import { createTypeahead } from '$lib/shared/hooks/useTypeahead.svelte';
+import { formatDocumentDate, type DatePrecision } from '$lib/shared/utils/documentDate';
+import { getLocale } from '$lib/paraglide/runtime.js';
+
+type DocumentListItem = components['schemas']['DocumentListItem'];
+
+export type DocumentOption = Pick<
+	DocumentListItem,
+	'id' | 'title' | 'documentDate' | 'metaDatePrecision' | 'metaDateEnd'
+>;
+
+export function createDocumentTypeahead() {
+	return createTypeahead<DocumentOption>({
+		fetchUrl: (q) =>
+			fetch(`/api/documents/search?q=${encodeURIComponent(q)}&size=10`)
+				.then((r) => {
+					// Without this check a 401/500 parses as JSON without `items` and
+					// renders as "no results" — errors must reach the hook's error state.
+					if (!r.ok) throw new Error(`document search failed: ${r.status}`);
+					return r.json();
+				})
+				.then((b: { items: DocumentListItem[] }) =>
+					b.items.map((it) => ({
+						id: it.id,
+						title: it.title,
+						documentDate: it.documentDate,
+						metaDatePrecision: it.metaDatePrecision,
+						metaDateEnd: it.metaDateEnd
+					}))
+				)
+	});
+}
+
+export function formatDocumentOption(doc: DocumentOption): string {
+	if (!doc.documentDate) return doc.title;
+	const label = formatDocumentDate(
+		doc.documentDate,
+		doc.metaDatePrecision as DatePrecision,
+		doc.metaDateEnd,
+		null,
+		getLocale()
+	);
+	return `${doc.title} · ${label}`;
+}

frontend/src/lib/document/transcription/useBlockDragDrop.svelte.test.ts

@@ -1,7 +1,35 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, expectTypeOf } from 'vitest';
 import { createBlockDragDrop } from './useBlockDragDrop.svelte';
 import type { TranscriptionBlockData } from '$lib/shared/types';
 
+// ---------------------------------------------------------------------------
+// Type-regression guard: createBlockDragDrop must accept any T extends {id: string}
+// so JourneyEditor can reuse it without importing TranscriptionBlockData.
+// This test fails with "Expected 0 type arguments, but got 1" via tsc --noEmit
+// until the function is made generic.
+// ---------------------------------------------------------------------------
+describe('createBlockDragDrop — generic type guard', () => {
+	it('accepts items shaped as { id: string; position: number } — not only TranscriptionBlockData', () => {
+		type SimpleItem = { id: string; position: number };
+		const items: SimpleItem[] = [
+			{ id: 'item-1', position: 0 },
+			{ id: 'item-2', position: 1 }
+		];
+		const onReorder = vi.fn();
+		const dd = createBlockDragDrop<SimpleItem>({ getSortedBlocks: () => items, onReorder });
+		// Verify the hook is functional with the new type — state reads must work
+		expect(dd.draggedBlockId).toBeNull();
+		expect(dd.dragOffsetY).toBe(0);
+	});
+
+	it('TranscriptionBlockData caller still compiles — regression guard for existing transcription editor', () => {
+		// If the generic constraint is wrong this line fails tsc --noEmit
+		expectTypeOf(createBlockDragDrop<TranscriptionBlockData>).toBeFunction();
+		// Runtime assertion so browser-mode doesn't report "no assertions"
+		expect(typeof createBlockDragDrop).toBe('function');
+	});
+});
+
 function makeBlock(id: string, sortOrder: number): TranscriptionBlockData {
 	return {
 		id,

frontend/src/lib/document/transcription/useBlockDragDrop.svelte.ts

@@ -1,11 +1,12 @@
-import type { TranscriptionBlockData } from '$lib/shared/types';
-
-type Options = {
-	getSortedBlocks: () => TranscriptionBlockData[];
+type Options<T extends { id: string }> = {
+	getSortedBlocks: () => T[];
 	onReorder: (blockIds: string[]) => void;
 };
 
-export function createBlockDragDrop({ getSortedBlocks, onReorder }: Options) {
+export function createBlockDragDrop<T extends { id: string }>({
+	getSortedBlocks,
+	onReorder
+}: Options<T>) {
 	let draggedBlockId = $state<string | null>(null);
 	let dropTargetIdx = $state<number | null>(null);
 	let dragOffsetY = $state(0);

frontend/src/lib/generated/api.ts

@@ -84,6 +84,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/geschichten/{id}/items/reorder": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * 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.
+         */
+        put: operations["reorderItems"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/documents/{id}": {
         parameters: {
             query?: never;
@@ -228,22 +248,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/search/nl": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        post: operations["search"];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/api/persons": {
         parameters: {
             query?: never;
@@ -436,6 +440,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/geschichten/{id}/items": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["appendItem"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/documents": {
         parameters: {
             query?: never;
@@ -820,6 +840,22 @@ export interface paths {
         patch: operations["update"];
         trace?: never;
     };
+    "/api/geschichten/{id}/items/{itemId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        delete: operations["deleteItem"];
+        options?: never;
+        head?: never;
+        patch: operations["updateItemNote"];
+        trace?: never;
+    };
     "/api/documents/{id}/training-labels": {
         parameters: {
             query?: never;
@@ -891,7 +927,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get: operations["search_1"];
+        get: operations["search"];
         put?: never;
         post?: never;
         delete?: never;
@@ -1355,7 +1391,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get: operations["search_2"];
+        get: operations["search_1"];
         put?: never;
         post?: never;
         delete?: never;
@@ -1706,6 +1742,32 @@ export interface components {
             provisional: boolean;
             readonly displayName: string;
         };
+        JourneyReorderDTO: {
+            itemIds?: string[];
+        };
+        DocumentSummary: {
+            /** Format: uuid */
+            id: string;
+            title: string;
+            /** Format: date */
+            documentDate?: string;
+            /** Format: date */
+            documentDateEnd?: string;
+            /** @enum {string} */
+            datePrecision: "DAY" | "MONTH" | "SEASON" | "YEAR" | "RANGE" | "APPROX" | "UNKNOWN";
+            senderName?: string;
+            receiverName?: string;
+            /** Format: int32 */
+            receiverCount: number;
+        };
+        JourneyItemView: {
+            /** Format: uuid */
+            id: string;
+            /** Format: int32 */
+            position: number;
+            document?: components["schemas"]["DocumentSummary"];
+            note?: string;
+        };
         DocumentUpdateDTO: {
             title?: string;
             /** Format: date */
@@ -1835,106 +1897,6 @@ export interface components {
             /** Format: uuid */
             targetId: string;
         };
-        NlSearchRequest: {
-            query: string;
-        };
-        Pageable: {
-            /** Format: int32 */
-            page?: number;
-            /** Format: int32 */
-            size?: number;
-            sort?: string[];
-        };
-        ActivityActorDTO: {
-            initials: string;
-            color: string;
-            name?: string;
-        };
-        DocumentListItem: {
-            /** Format: uuid */
-            id: string;
-            title: string;
-            originalFilename: string;
-            thumbnailUrl?: string;
-            /** Format: date */
-            documentDate?: string;
-            /** @enum {string} */
-            metaDatePrecision: "DAY" | "MONTH" | "SEASON" | "YEAR" | "RANGE" | "APPROX" | "UNKNOWN";
-            /** Format: date */
-            metaDateEnd?: string;
-            sender?: components["schemas"]["Person"];
-            receivers: components["schemas"]["Person"][];
-            tags: components["schemas"]["Tag"][];
-            archiveBox?: string;
-            archiveFolder?: string;
-            location?: string;
-            summary?: string;
-            /** Format: int32 */
-            completionPercentage: number;
-            contributors: components["schemas"]["ActivityActorDTO"][];
-            matchData: components["schemas"]["SearchMatchData"];
-            /** Format: date-time */
-            createdAt: string;
-            /** Format: date-time */
-            updatedAt: string;
-        };
-        DocumentSearchResult: {
-            items: components["schemas"]["DocumentListItem"][];
-            /** Format: int64 */
-            totalElements: number;
-            /** Format: int32 */
-            pageNumber: number;
-            /** Format: int32 */
-            pageSize: number;
-            /** Format: int32 */
-            totalPages: number;
-            /** Format: int64 */
-            undatedCount: number;
-        };
-        MatchOffset: {
-            /** Format: int32 */
-            start: number;
-            /** Format: int32 */
-            length: number;
-        };
-        NlQueryInterpretation: {
-            resolvedPersons: components["schemas"]["PersonHint"][];
-            ambiguousPersons: components["schemas"]["PersonHint"][];
-            /** Format: date */
-            dateFrom?: string;
-            /** Format: date */
-            dateTo?: string;
-            keywords: string[];
-            resolvedTags: components["schemas"]["TagHint"][];
-            rawQuery: string;
-            keywordsApplied: boolean;
-            tagsApplied: boolean;
-        };
-        NlSearchResponse: {
-            result: components["schemas"]["DocumentSearchResult"];
-            interpretation: components["schemas"]["NlQueryInterpretation"];
-        };
-        PersonHint: {
-            /** Format: uuid */
-            id: string;
-            displayName: string;
-        };
-        TagHint: {
-            /** Format: uuid */
-            id: string;
-            name: string;
-            color?: string;
-        };
-        SearchMatchData: {
-            transcriptionSnippet?: string;
-            titleOffsets: components["schemas"]["MatchOffset"][];
-            senderMatched: boolean;
-            matchedReceiverIds: string[];
-            matchedTagIds: string[];
-            snippetOffsets: components["schemas"]["MatchOffset"][];
-            summarySnippet?: string;
-            summaryOffsets: components["schemas"]["MatchOffset"][];
-        };
         CreateRelationshipRequest: {
             /** Format: uuid */
             relatedPersonId: string;
@@ -2062,25 +2024,44 @@ export interface components {
             body?: string;
             /** @enum {string} */
             status?: "DRAFT" | "PUBLISHED";
+            /** @enum {string} */
+            type?: "STORY" | "JOURNEY";
             personIds?: string[];
-            documentIds?: string[];
         };
-        Geschichte: {
+        AuthorView: {
+            /** Format: uuid */
+            id: string;
+            displayName: string;
+        };
+        GeschichteView: {
             /** Format: uuid */
             id: string;
             title: string;
             body?: string;
             /** @enum {string} */
             status: "DRAFT" | "PUBLISHED";
-            author?: components["schemas"]["AppUser"];
-            persons?: components["schemas"]["Person"][];
-            documents?: components["schemas"]["Document"][];
+            /** @enum {string} */
+            type: "STORY" | "JOURNEY";
+            author?: components["schemas"]["AuthorView"];
+            persons: components["schemas"]["PersonView"][];
+            items: components["schemas"]["JourneyItemView"][];
+            /** Format: date-time */
+            publishedAt?: string;
             /** Format: date-time */
             createdAt: string;
             /** Format: date-time */
             updatedAt: string;
-            /** Format: date-time */
-            publishedAt?: string;
+        };
+        PersonView: {
+            /** Format: uuid */
+            id: string;
+            firstName?: string;
+            lastName?: string;
+        };
+        JourneyItemCreateDTO: {
+            /** Format: uuid */
+            documentId?: string;
+            note?: string;
         };
         CreateTranscriptionBlockDTO: {
             /** Format: int32 */
@@ -2280,6 +2261,9 @@ export interface components {
             actorName?: string;
             documentTitle?: string;
         };
+        JourneyItemUpdateDTO: {
+            note?: string;
+        };
         TrainingLabelRequest: {
             label?: string;
             enrolled?: boolean;
@@ -2320,6 +2304,11 @@ export interface components {
             /** Format: int64 */
             transcriptionCount: number;
         };
+        ActivityActorDTO: {
+            initials: string;
+            color: string;
+            name?: string;
+        };
         TranscriptionQueueItemDTO: {
             /** Format: uuid */
             id: string;
@@ -2382,13 +2371,13 @@ export interface components {
             lastName?: string;
             /** Format: int64 */
             documentCount?: number;
+            alias?: string;
             notes?: string;
             /** Format: int32 */
             birthYear?: number;
             /** Format: int32 */
             deathYear?: number;
             provisional?: boolean;
-            alias?: string;
             personType?: string;
             familyMember?: boolean;
         };
@@ -2487,6 +2476,8 @@ export interface components {
             /** Format: int32 */
             totalPages?: number;
             pageable?: components["schemas"]["PageableObject"];
+            first?: boolean;
+            last?: boolean;
             /** Format: int32 */
             size?: number;
             content?: components["schemas"]["NotificationDTO"][];
@@ -2495,8 +2486,6 @@ export interface components {
             sort?: components["schemas"]["SortObject"];
             /** Format: int32 */
             numberOfElements?: number;
-            first?: boolean;
-            last?: boolean;
             empty?: boolean;
         };
         PageableObject: {
@@ -2519,6 +2508,26 @@ export interface components {
             nodes: components["schemas"]["PersonNodeDTO"][];
             edges: components["schemas"]["RelationshipDTO"][];
         };
+        AuthorSummary: {
+            firstName?: string;
+            lastName?: string;
+            email: string;
+        };
+        GeschichteSummary: {
+            body?: string;
+            title: string;
+            /** Format: uuid */
+            id: string;
+            /** @enum {string} */
+            type: "STORY" | "JOURNEY";
+            /** @enum {string} */
+            status: "DRAFT" | "PUBLISHED";
+            /** Format: date-time */
+            updatedAt: string;
+            author?: components["schemas"]["AuthorSummary"];
+            /** Format: date-time */
+            publishedAt?: string;
+        };
         DocumentVersionSummary: {
             /** Format: uuid */
             id: string;
@@ -2560,6 +2569,63 @@ export interface components {
             /** Format: int32 */
             totalPages?: number;
         };
+        DocumentListItem: {
+            /** Format: uuid */
+            id: string;
+            title: string;
+            originalFilename: string;
+            thumbnailUrl?: string;
+            /** Format: date */
+            documentDate?: string;
+            /** @enum {string} */
+            metaDatePrecision: "DAY" | "MONTH" | "SEASON" | "YEAR" | "RANGE" | "APPROX" | "UNKNOWN";
+            /** Format: date */
+            metaDateEnd?: string;
+            sender?: components["schemas"]["Person"];
+            receivers: components["schemas"]["Person"][];
+            tags: components["schemas"]["Tag"][];
+            archiveBox?: string;
+            archiveFolder?: string;
+            location?: string;
+            summary?: string;
+            /** Format: int32 */
+            completionPercentage: number;
+            contributors: components["schemas"]["ActivityActorDTO"][];
+            matchData: components["schemas"]["SearchMatchData"];
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            updatedAt: string;
+        };
+        DocumentSearchResult: {
+            items: components["schemas"]["DocumentListItem"][];
+            /** Format: int64 */
+            totalElements: number;
+            /** Format: int32 */
+            pageNumber: number;
+            /** Format: int32 */
+            pageSize: number;
+            /** Format: int32 */
+            totalPages: number;
+            /** Format: int64 */
+            undatedCount: number;
+        };
+        MatchOffset: {
+            /** Format: int32 */
+            start: number;
+            /** Format: int32 */
+            length: number;
+        };
+        SearchMatchData: {
+            transcriptionSnippet?: string;
+            titleOffsets: components["schemas"]["MatchOffset"][];
+            senderMatched: boolean;
+            matchedReceiverIds: string[];
+            matchedTagIds: string[];
+            snippetOffsets: components["schemas"]["MatchOffset"][];
+            summarySnippet?: string;
+            summaryOffsets: components["schemas"]["MatchOffset"][];
+        };
         IncompleteDocumentDTO: {
             /** Format: uuid */
             id: string;
@@ -2608,7 +2674,7 @@ export interface components {
         };
         ActivityFeedItemDTO: {
             /** @enum {string} */
-            kind: "FILE_UPLOADED" | "STATUS_CHANGED" | "METADATA_UPDATED" | "TEXT_SAVED" | "BLOCK_REVIEWED" | "ANNOTATION_CREATED" | "COMMENT_ADDED" | "MENTION_CREATED" | "USER_CREATED" | "USER_DELETED" | "GROUP_MEMBERSHIP_CHANGED" | "LOGIN_SUCCESS" | "LOGIN_FAILED" | "LOGOUT" | "ADMIN_FORCE_LOGOUT" | "LOGIN_RATE_LIMITED";
+            kind: "FILE_UPLOADED" | "STATUS_CHANGED" | "METADATA_UPDATED" | "TEXT_SAVED" | "BLOCK_REVIEWED" | "ANNOTATION_CREATED" | "COMMENT_ADDED" | "MENTION_CREATED" | "USER_CREATED" | "USER_DELETED" | "GROUP_MEMBERSHIP_CHANGED" | "LOGIN_SUCCESS" | "LOGIN_FAILED" | "LOGOUT" | "ADMIN_FORCE_LOGOUT" | "LOGIN_RATE_LIMITED" | "JOURNEY_ITEM_ADDED" | "JOURNEY_ITEM_REMOVED" | "JOURNEY_ITEM_NOTE_UPDATED" | "JOURNEY_ITEMS_REORDERED";
             actor?: components["schemas"]["ActivityActorDTO"];
             /** Format: uuid */
             documentId: string;
@@ -2918,6 +2984,32 @@ export interface operations {
             };
         };
     };
+    reorderItems: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["JourneyReorderDTO"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["JourneyItemView"][];
+                };
+            };
+        };
+    };
     getDocument: {
         parameters: {
             query?: never;
@@ -3244,32 +3336,6 @@ export interface operations {
             };
         };
     };
-    search: {
-        parameters: {
-            query: {
-                pageable: components["schemas"]["Pageable"];
-            };
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                "application/json": components["schemas"]["NlSearchRequest"];
-            };
-        };
-        responses: {
-            /** @description OK */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "*/*": components["schemas"]["NlSearchResponse"];
-                };
-            };
-        };
-    };
     getPersons: {
         parameters: {
             query?: {
@@ -3664,7 +3730,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "*/*": components["schemas"]["Geschichte"][];
+                    "*/*": components["schemas"]["GeschichteSummary"][];
                 };
             };
         };
@@ -3688,7 +3754,33 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "*/*": components["schemas"]["Geschichte"];
+                    "*/*": components["schemas"]["GeschichteView"];
+                };
+            };
+        };
+    };
+    appendItem: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["JourneyItemCreateDTO"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["JourneyItemView"];
                 };
             };
         };
@@ -4364,7 +4456,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "*/*": components["schemas"]["Geschichte"];
+                    "*/*": components["schemas"]["GeschichteView"];
                 };
             };
         };
@@ -4410,7 +4502,55 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "*/*": components["schemas"]["Geschichte"];
+                    "*/*": components["schemas"]["GeschichteView"];
+                };
+            };
+        };
+    };
+    deleteItem: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+                itemId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    updateItemNote: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+                itemId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["JourneyItemUpdateDTO"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["JourneyItemView"];
                 };
             };
         };
@@ -4559,7 +4699,7 @@ export interface operations {
             };
         };
     };
-    search_1: {
+    search: {
         parameters: {
             query?: {
                 q?: string;
@@ -5183,7 +5323,7 @@ export interface operations {
             };
         };
     };
-    search_2: {
+    search_1: {
         parameters: {
             query?: {
                 q?: string;
@@ -5398,7 +5538,7 @@ export interface operations {
             query?: {
                 limit?: number;
                 /** @description Filter by audit kinds; omit for all rollup-eligible kinds */
-                kinds?: ("FILE_UPLOADED" | "STATUS_CHANGED" | "METADATA_UPDATED" | "TEXT_SAVED" | "BLOCK_REVIEWED" | "ANNOTATION_CREATED" | "COMMENT_ADDED" | "MENTION_CREATED" | "USER_CREATED" | "USER_DELETED" | "GROUP_MEMBERSHIP_CHANGED" | "LOGIN_SUCCESS" | "LOGIN_FAILED" | "LOGOUT" | "ADMIN_FORCE_LOGOUT" | "LOGIN_RATE_LIMITED")[];
+                kinds?: ("FILE_UPLOADED" | "STATUS_CHANGED" | "METADATA_UPDATED" | "TEXT_SAVED" | "BLOCK_REVIEWED" | "ANNOTATION_CREATED" | "COMMENT_ADDED" | "MENTION_CREATED" | "USER_CREATED" | "USER_DELETED" | "GROUP_MEMBERSHIP_CHANGED" | "LOGIN_SUCCESS" | "LOGIN_FAILED" | "LOGOUT" | "ADMIN_FORCE_LOGOUT" | "LOGIN_RATE_LIMITED" | "JOURNEY_ITEM_ADDED" | "JOURNEY_ITEM_REMOVED" | "JOURNEY_ITEM_NOTE_UPDATED" | "JOURNEY_ITEMS_REORDERED")[];
             };
             header?: never;
             path?: never;

frontend/src/lib/geschichte/GeschichteEditor.svelte

@@ -5,34 +5,25 @@ import { Editor } from '@tiptap/core';
 import StarterKit from '@tiptap/starter-kit';
 import { m } from '$lib/paraglide/messages.js';
 import type { components } from '$lib/generated/api';
-import PersonMultiSelect from '$lib/person/PersonMultiSelect.svelte';
-import DocumentMultiSelect from '$lib/document/DocumentMultiSelect.svelte';
+import GeschichteSidebar from '$lib/geschichte/GeschichteSidebar.svelte';
 
-type Geschichte = components['schemas']['Geschichte'];
+type GeschichteView = components['schemas']['GeschichteView'];
 type Person = components['schemas']['Person'];
-type Document = components['schemas']['Document'];
+type PersonOption = Pick<Person, 'id' | 'displayName'>;
 
 interface Props {
-	geschichte?: Geschichte | null;
+	geschichte?: GeschichteView | null;
 	initialPersons?: Person[];
-	initialDocuments?: Document[];
 	onSubmit: (payload: {
 		title: string;
 		body: string;
 		status: 'DRAFT' | 'PUBLISHED';
 		personIds: string[];
-		documentIds: string[];
 	}) => Promise<void>;
 	submitting?: boolean;
 }
 
-let {
-	geschichte = null,
-	initialPersons = [],
-	initialDocuments = [],
-	onSubmit,
-	submitting = false
-}: Props = $props();
+let { geschichte = null, initialPersons = [], onSubmit, submitting = false }: Props = $props();
 
 // Initial-state snapshot from incoming props. The editor owns these values
 // after mount; the parent should re-mount the component with a different
@@ -41,11 +32,13 @@ let {
 let title = $state(geschichte?.title ?? '');
 let body = $state(geschichte?.body ?? '');
 let status: 'DRAFT' | 'PUBLISHED' = $state(geschichte?.status ?? 'DRAFT');
-let selectedPersons: Person[] = $state(
-	geschichte?.persons ? Array.from(geschichte.persons) : initialPersons
-);
-let selectedDocuments: Document[] = $state(
-	geschichte?.documents ? Array.from(geschichte.documents) : initialDocuments
+let selectedPersons: PersonOption[] = $state(
+	geschichte?.persons
+		? Array.from(geschichte.persons).map((p) => ({
+				id: p.id,
+				displayName: [p.firstName, p.lastName].filter(Boolean).join(' ')
+			}))
+		: initialPersons
 );
 
 let dirty = $state(false);
@@ -122,8 +115,7 @@ async function save(nextStatus: 'DRAFT' | 'PUBLISHED') {
 		title: title.trim(),
 		body,
 		status: nextStatus,
-		personIds: selectedPersons.map((p) => p.id!).filter(Boolean),
-		documentIds: selectedDocuments.map((d) => d.id!).filter(Boolean)
+		personIds: selectedPersons.map((p) => p.id!).filter(Boolean)
 	});
 	dirty = false;
 }
@@ -241,43 +233,7 @@ function exec(action: () => void) {
 	</div>
 
 	<!-- Sidebar -->
-	<aside class="flex flex-col gap-6">
-		<section class="rounded border border-line bg-surface p-4 shadow-sm">
-			<h2 class="mb-1 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">Status</h2>
-			<p class="mb-3">
-				<span
-					class="inline-flex items-center rounded px-2 py-1 font-sans text-xs font-bold tracking-widest uppercase {isDraft
-						? 'bg-muted text-ink-2'
-						: 'bg-accent-bg text-ink'}"
-				>
-					{isDraft
-						? m.geschichte_editor_status_draft()
-						: m.geschichte_editor_status_published()}
-				</span>
-			</p>
-			<p class="font-sans text-xs text-ink-3">
-				{isDraft
-					? m.geschichte_editor_status_draft_hint()
-					: m.geschichte_editor_status_published_hint()}
-			</p>
-		</section>
-
-		<section class="rounded border border-line bg-surface p-4 shadow-sm">
-			<h2 class="mb-2 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
-				{m.geschichte_editor_personen_heading()}
-			</h2>
-			<p class="mb-3 font-sans text-xs text-ink-3">{m.geschichte_editor_personen_hint()}</p>
-			<PersonMultiSelect bind:selectedPersons={selectedPersons} />
-		</section>
-
-		<section class="rounded border border-line bg-surface p-4 shadow-sm">
-			<h2 class="mb-2 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
-				{m.geschichte_editor_dokumente_heading()}
-			</h2>
-			<p class="mb-3 font-sans text-xs text-ink-3">{m.geschichte_editor_dokumente_hint()}</p>
-			<DocumentMultiSelect bind:selectedDocuments={selectedDocuments} />
-		</section>
-	</aside>
+	<GeschichteSidebar status={status} bind:selectedPersons={selectedPersons} />
 </div>
 
 <!-- Save bar -->

frontend/src/lib/geschichte/GeschichteEditor.svelte.spec.ts

@@ -8,19 +8,9 @@ const personFactory = (id: string, displayName: string) => ({
 	firstName: displayName.split(' ')[0],
 	lastName: displayName.split(' ').slice(1).join(' ') || displayName,
 	displayName,
-	personType: 'PERSON' as const
-});
-
-const docFactory = (id: string, title: string, date = '1882-01-01') => ({
-	id,
-	title,
-	documentDate: date,
-	originalFilename: `${title}.pdf`,
-	status: 'UPLOADED' as const,
-	metadataComplete: false,
-	scriptType: 'UNKNOWN' as const,
-	createdAt: '2024-01-01T00:00:00',
-	updatedAt: '2024-01-01T00:00:00'
+	personType: 'PERSON' as const,
+	familyMember: false,
+	provisional: false
 });
 
 const draftFactory = (overrides: Record<string, unknown> = {}) => ({
@@ -28,8 +18,9 @@ const draftFactory = (overrides: Record<string, unknown> = {}) => ({
 	title: 'Existing draft',
 	body: '<p>Hello world</p>',
 	status: 'DRAFT' as const,
+	type: 'STORY' as const,
 	persons: [],
-	documents: [],
+	items: [],
 	createdAt: '2024-01-01T00:00:00',
 	updatedAt: '2024-01-01T00:00:00',
 	...overrides
@@ -93,14 +84,6 @@ describe('GeschichteEditor — pre-fill', () => {
 		await expect.element(page.getByText('Franz Raddatz')).toBeInTheDocument();
 	});
 
-	it('renders initial documents as chips', async () => {
-		render(GeschichteEditor, {
-			initialDocuments: [docFactory('d1', 'Brief von Eugenie')],
-			onSubmit: vi.fn()
-		});
-		await expect.element(page.getByText(/Brief von Eugenie/)).toBeInTheDocument();
-	});
-
 	it('populates the title input from a geschichte prop', async () => {
 		render(GeschichteEditor, {
 			geschichte: draftFactory({ title: 'My existing story' }),
@@ -154,11 +137,10 @@ describe('GeschichteEditor — onSubmit payload', () => {
 		expect(onSubmit.mock.calls[0][0].status).toBe('PUBLISHED');
 	});
 
-	it('passes the personIds and documentIds from initial props through onSubmit', async () => {
+	it('passes personIds from initial props through onSubmit', async () => {
 		const onSubmit = vi.fn().mockResolvedValue(undefined);
 		render(GeschichteEditor, {
 			initialPersons: [personFactory('p1', 'Franz Raddatz')],
-			initialDocuments: [docFactory('d1', 'Brief A')],
 			onSubmit
 		});
 
@@ -171,6 +153,5 @@ describe('GeschichteEditor — onSubmit payload', () => {
 		expect(onSubmit).toHaveBeenCalledTimes(1);
 		const payload = onSubmit.mock.calls[0][0];
 		expect(payload.personIds).toEqual(['p1']);
-		expect(payload.documentIds).toEqual(['d1']);
 	});
 });

frontend/src/lib/geschichte/GeschichteListRow.svelte

@@ -0,0 +1,42 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import { plainExcerpt } from '$lib/shared/utils/extractText';
+import { formatAuthorName, formatPublishedAt } from './utils';
+import type { components } from '$lib/generated/api';
+
+type GeschichteRow = Pick<
+	components['schemas']['GeschichteSummary'],
+	'id' | 'title' | 'body' | 'type' | 'author' | 'publishedAt'
+>;
+
+let { geschichte }: { geschichte: GeschichteRow } = $props();
+
+const isJourney = $derived(geschichte.type === 'JOURNEY');
+
+const publishedAt = $derived(formatPublishedAt(geschichte.publishedAt, 'short'));
+
+const authorName = $derived(formatAuthorName(geschichte.author));
+</script>
+
+<a href="/geschichten/{geschichte.id}" class="block">
+	<div class="mb-1 flex items-center gap-1.5">
+		<h2 class="font-serif text-xl font-bold text-ink">{geschichte.title}</h2>
+		{#if isJourney}
+			<span
+				data-testid="journey-badge"
+				style="font-size: 0.75rem"
+				class="inline-block rounded-full bg-journey-tint px-2 py-0.5 text-xs font-bold tracking-wider text-journey uppercase"
+			>
+				{m.journey_badge_list()}
+			</span>
+		{/if}
+	</div>
+	<p class="mb-3 font-sans text-xs text-ink-3">
+		{authorName}
+		{#if publishedAt}· {m.geschichten_published_on({ date: publishedAt })}{/if}
+	</p>
+	{#if geschichte.body}
+		<!-- plaintext for JOURNEY, sanitised-HTML→text for STORY; never {@html} -->
+		<p class="font-serif text-base text-ink-2">{plainExcerpt(geschichte.body, 150)}</p>
+	{/if}
+</a>

frontend/src/lib/geschichte/GeschichteListRow.svelte.spec.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+
+const { default: GeschichteListRow } = await import('./GeschichteListRow.svelte');
+
+afterEach(cleanup);
+
+const baseRow = (overrides = {}) => ({
+	id: 'g1',
+	title: 'Die Reise nach Berlin',
+	body: '<p>Im Jahr 1923...</p>',
+	type: 'STORY' as 'STORY' | 'JOURNEY',
+	status: 'PUBLISHED' as 'PUBLISHED' | 'DRAFT',
+	author: { firstName: 'Anna', lastName: 'Schmidt', email: 'a@x' },
+	publishedAt: '2026-04-15T10:00:00Z',
+	...overrides
+});
+
+describe('GeschichteListRow', () => {
+	it('renders the title', async () => {
+		render(GeschichteListRow, { props: { geschichte: baseRow() } });
+		await expect
+			.element(page.getByRole('heading', { level: 2 }))
+			.toHaveTextContent('Die Reise nach Berlin');
+	});
+
+	it('shows no badge for STORY type', async () => {
+		render(GeschichteListRow, { props: { geschichte: baseRow({ type: 'STORY' }) } });
+		expect(document.querySelector('[data-testid="journey-badge"]')).toBeNull();
+	});
+
+	it('shows no badge when type is undefined', async () => {
+		render(GeschichteListRow, {
+			props: { geschichte: baseRow({ type: undefined as unknown as 'STORY' | 'JOURNEY' }) }
+		});
+		expect(document.querySelector('[data-testid="journey-badge"]')).toBeNull();
+	});
+
+	it('shows REISE badge for JOURNEY type', async () => {
+		render(GeschichteListRow, { props: { geschichte: baseRow({ type: 'JOURNEY' }) } });
+		const badge = document.querySelector('[data-testid="journey-badge"]');
+		expect(badge).not.toBeNull();
+		expect(badge?.textContent?.trim()).toBe('REISE');
+	});
+
+	it('badge is a plain <span>, not a nested interactive element', async () => {
+		render(GeschichteListRow, { props: { geschichte: baseRow({ type: 'JOURNEY' }) } });
+		const badge = document.querySelector('[data-testid="journey-badge"]');
+		expect(badge?.tagName.toLowerCase()).toBe('span');
+	});
+
+	it('badge has small font size appropriate for a label', async () => {
+		render(GeschichteListRow, { props: { geschichte: baseRow({ type: 'JOURNEY' }) } });
+		const badge = document.querySelector('[data-testid="journey-badge"]');
+		const fontSize = parseFloat(window.getComputedStyle(badge!).fontSize);
+		expect(fontSize).toBeGreaterThan(0);
+		expect(fontSize).toBeLessThanOrEqual(14); // label badge must not exceed body text size
+	});
+
+	it('renders author name in meta line', async () => {
+		render(GeschichteListRow, { props: { geschichte: baseRow() } });
+		expect(document.body.textContent).toContain('Anna Schmidt');
+	});
+});

frontend/src/lib/geschichte/GeschichteSidebar.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import type { components } from '$lib/generated/api';
+import PersonMultiSelect from '$lib/person/PersonMultiSelect.svelte';
+
+type Person = components['schemas']['Person'];
+type PersonOption = Pick<Person, 'id' | 'displayName'>;
+
+interface Props {
+	status: 'DRAFT' | 'PUBLISHED';
+	selectedPersons: PersonOption[];
+}
+
+let { status, selectedPersons = $bindable() }: Props = $props();
+
+const isDraft = $derived(status === 'DRAFT');
+</script>
+
+<aside class="flex flex-col gap-6">
+	<!-- Status section -->
+	<details open class="sm:contents">
+		<summary
+			class="flex min-h-[44px] cursor-pointer items-center px-4 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase sm:hidden"
+		>
+			{m.geschichte_sidebar_status()}
+		</summary>
+		<section class="rounded border border-line bg-surface p-4 shadow-sm">
+			<h2 class="mb-1 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
+				{m.geschichte_sidebar_status()}
+			</h2>
+			<p class="mb-3">
+				<span
+					class="inline-flex items-center rounded px-2 py-1 font-sans text-xs font-bold tracking-widest uppercase {isDraft
+						? 'bg-muted text-ink-2'
+						: 'bg-accent-bg text-ink'}"
+				>
+					{isDraft ? m.geschichte_editor_status_draft() : m.geschichte_editor_status_published()}
+				</span>
+			</p>
+			<p class="font-sans text-xs text-ink-3">
+				{isDraft
+					? m.geschichte_editor_status_draft_hint()
+					: m.geschichte_editor_status_published_hint()}
+			</p>
+		</section>
+	</details>
+
+	<!-- Persons section -->
+	<details open class="sm:contents">
+		<summary
+			class="flex min-h-[44px] cursor-pointer items-center px-4 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase sm:hidden"
+		>
+			{m.geschichte_editor_personen_heading()}
+		</summary>
+		<section class="rounded border border-line bg-surface p-4 shadow-sm">
+			<h2 class="mb-2 font-sans text-xs font-bold tracking-widest text-ink-3 uppercase">
+				{m.geschichte_editor_personen_heading()}
+			</h2>
+			<p class="mb-3 font-sans text-xs text-ink-3">{m.geschichte_editor_personen_hint()}</p>
+			<PersonMultiSelect bind:selectedPersons={selectedPersons} />
+		</section>
+	</details>
+</aside>

frontend/src/lib/geschichte/GeschichtenCard.svelte

@@ -4,10 +4,10 @@ import type { components } from '$lib/generated/api';
 import { plainExcerpt } from '$lib/shared/utils/extractText';
 import { formatDate } from '$lib/shared/utils/date';
 
-type Geschichte = components['schemas']['Geschichte'];
+type GeschichteSummary = components['schemas']['GeschichteSummary'];
 
 interface Props {
-	geschichten: Geschichte[];
+	geschichten: GeschichteSummary[];
 	personId: string;
 	personName: string;
 	canWrite: boolean;
@@ -18,12 +18,12 @@ let { geschichten, personId, personName, canWrite }: Props = $props();
 const visible = $derived(geschichten.slice(0, 3));
 const hasOverflow = $derived(geschichten.length >= 3);
 
-function formatPublishedDate(g: Geschichte): string | null {
+function formatPublishedDate(g: GeschichteSummary): string | null {
 	if (!g.publishedAt) return null;
 	return formatDate(g.publishedAt.slice(0, 10), 'short');
 }
 
-function authorName(g: Geschichte): string {
+function authorName(g: GeschichteSummary): string {
 	const a = g.author;
 	if (!a) return '';
 	const full = [a.firstName, a.lastName].filter(Boolean).join(' ').trim();

frontend/src/lib/geschichte/GeschichtenCard.svelte.spec.ts

@@ -3,16 +3,17 @@ import { cleanup, render } from 'vitest-browser-svelte';
 import { page } from 'vitest/browser';
 import GeschichtenCard from './GeschichtenCard.svelte';
 
-const makeStory = (id: string, title: string, body: string | null = '<p>Body</p>') => ({
+const makeStory = (id: string, title: string, body: string | undefined = '<p>Body</p>') => ({
 	id,
 	title,
 	body,
 	status: 'PUBLISHED' as const,
+	type: 'STORY' as const,
 	publishedAt: '2024-04-01T12:00:00',
 	createdAt: '2024-03-01T12:00:00',
 	updatedAt: '2024-04-01T12:00:00',
 	persons: [],
-	documents: [],
+	items: [],
 	author: {
 		id: 'u1',
 		email: 'marcel@example.com',
@@ -120,6 +121,16 @@ describe('GeschichtenCard', () => {
 		expect(link.getAttribute('href')).toBe('/geschichten?personId=p1');
 	});
 
+	it('JOURNEY type does not bleed a REISE badge into the person-sidebar card', async () => {
+		render(GeschichtenCard, {
+			geschichten: [{ ...makeStory('g1', 'Reise Berlin'), type: 'JOURNEY' as const }],
+			personId: 'p1',
+			personName: 'Franz',
+			canWrite: false
+		});
+		expect(document.querySelector('[data-testid="journey-badge"]')).toBeNull();
+	});
+
 	it('renders a plain-text excerpt without HTML markup', async () => {
 		render(GeschichtenCard, {
 			geschichten: [

frontend/src/lib/geschichte/GeschichtenCard.svelte.test.ts

@@ -2,20 +2,30 @@ import { describe, it, expect, afterEach } from 'vitest';
 import { cleanup, render } from 'vitest-browser-svelte';
 import { page } from 'vitest/browser';
 import GeschichtenCard from './GeschichtenCard.svelte';
+import type { components } from '$lib/generated/api';
+
+type GeschichteSummary = components['schemas']['GeschichteSummary'];
 
 afterEach(cleanup);
 
-const makeGeschichte = (overrides: Record<string, unknown> = {}) => ({
-	id: 'g1',
-	title: 'Reise nach Berlin',
-	body: '<p>Brief text</p>',
-	publishedAt: '2026-04-15T10:00:00Z',
-	author: { firstName: 'Anna', lastName: 'Schmidt', email: 'a@b' } as unknown,
-	...overrides
-});
+const makeGeschichte = (overrides: Record<string, unknown> = {}): GeschichteSummary =>
+	({
+		id: 'g1',
+		title: 'Reise nach Berlin',
+		body: '<p>Brief text</p>',
+		status: 'PUBLISHED' as const,
+		type: 'STORY' as const,
+		publishedAt: '2026-04-15T10:00:00Z',
+		author: {
+			email: 'a@b',
+			firstName: 'Anna',
+			lastName: 'Schmidt'
+		},
+		...overrides
+	}) as GeschichteSummary;
 
 const baseProps = (overrides: Record<string, unknown> = {}) => ({
-	geschichten: [] as ReturnType<typeof makeGeschichte>[],
+	geschichten: [] as GeschichteSummary[],
 	personId: 'p-1',
 	personName: 'Anna Schmidt',
 	canWrite: false,

frontend/src/lib/geschichte/JourneyAddBar.svelte

@@ -0,0 +1,104 @@
+<script lang="ts">
+import { m } from '$lib/paraglide/messages.js';
+import DocumentPickerDropdown from '$lib/document/DocumentPickerDropdown.svelte';
+import type { DocumentOption } from '$lib/document/documentTypeahead';
+
+interface Props {
+	alreadyAddedIds?: Set<string>;
+	onAddDocument: (doc: DocumentOption) => void;
+	onAddInterlude: (text: string) => void;
+}
+
+let { alreadyAddedIds = new Set(), onAddDocument, onAddInterlude }: Props = $props();
+
+let showPicker = $state(false);
+let showInterludeForm = $state(false);
+let interludeDraft = $state('');
+
+const canConfirmInterlude = $derived(interludeDraft.trim().length > 0);
+
+function handleDocumentSelect(doc: DocumentOption) {
+	showPicker = false;
+	onAddDocument(doc);
+}
+
+function handleInterludeConfirm() {
+	if (!canConfirmInterlude) return;
+	const text = interludeDraft.trim();
+	interludeDraft = '';
+	showInterludeForm = false;
+	onAddInterlude(text);
+}
+
+function handleInterludeCancel() {
+	interludeDraft = '';
+	showInterludeForm = false;
+}
+</script>
+
+<div class="flex flex-col gap-3">
+	<div class="flex flex-wrap gap-2">
+		<button
+			type="button"
+			onclick={() => {
+				showPicker = !showPicker;
+				showInterludeForm = false;
+			}}
+			class="inline-flex h-11 items-center rounded border border-line bg-surface px-4 font-sans text-sm font-medium text-ink hover:bg-muted focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+		>
+			+ {m.journey_add_document()}
+		</button>
+		<button
+			type="button"
+			onclick={() => {
+				showInterludeForm = !showInterludeForm;
+				showPicker = false;
+			}}
+			class="inline-flex h-11 items-center rounded border border-line bg-surface px-4 font-sans text-sm font-medium text-ink hover:bg-muted focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+		>
+			+ {m.journey_add_interlude()}
+		</button>
+	</div>
+
+	{#if showPicker}
+		<DocumentPickerDropdown
+			alreadyAddedIds={alreadyAddedIds}
+			onSelect={handleDocumentSelect}
+			placeholder={m.journey_add_document()}
+		/>
+	{/if}
+
+	{#if showInterludeForm}
+		<div class="flex flex-col gap-2">
+			<textarea
+				bind:value={interludeDraft}
+				placeholder={m.journey_interlude_placeholder()}
+				rows={3}
+				maxlength={2000}
+				class="block w-full resize-y rounded border border-line bg-surface px-3 py-2 font-sans text-sm text-ink placeholder:text-ink-3 focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+			></textarea>
+			<div class="flex gap-2">
+				<button
+					type="button"
+					onclick={handleInterludeConfirm}
+					disabled={!canConfirmInterlude}
+					class={[
+						'inline-flex h-11 items-center rounded px-4 font-sans text-sm font-medium focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring',
+						canConfirmInterlude
+							? 'bg-primary text-primary-fg hover:opacity-90'
+							: 'cursor-not-allowed bg-primary/40 text-primary-fg/60'
+					].join(' ')}
+				>
+					{m.journey_add_interlude_confirm()}
+				</button>
+				<button
+					type="button"
+					onclick={handleInterludeCancel}
+					class="inline-flex h-11 items-center rounded border border-line bg-surface px-4 font-sans text-sm font-medium text-ink hover:bg-muted focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+				>
+					{m.journey_remove_confirm_cancel()}
+				</button>
+			</div>
+		</div>
+	{/if}
+</div>

frontend/src/lib/geschichte/JourneyAddBar.svelte.spec.ts

@@ -0,0 +1,55 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render } from 'vitest-browser-svelte';
+import { page, userEvent } from 'vitest/browser';
+import JourneyAddBar from './JourneyAddBar.svelte';
+
+afterEach(() => {
+	cleanup();
+	vi.unstubAllGlobals();
+});
+
+describe('JourneyAddBar — interlude flow', () => {
+	it('interlude confirm button is natively disabled when text is empty (WCAG 4.1.2)', async () => {
+		render(JourneyAddBar, { onAddDocument: vi.fn(), onAddInterlude: vi.fn() });
+
+		await userEvent.click(page.getByText('Zwischentext hinzufügen'));
+
+		const confirmBtn = page.getByRole('button', { name: 'Hinzufügen', exact: true });
+		await expect.element(confirmBtn).toBeDisabled();
+	});
+
+	it('confirm becomes enabled after typing text', async () => {
+		render(JourneyAddBar, { onAddDocument: vi.fn(), onAddInterlude: vi.fn() });
+
+		await userEvent.click(page.getByText('Zwischentext hinzufügen'));
+		await userEvent.fill(page.getByRole('textbox'), 'Eine schöne Reise');
+
+		const confirmBtn = page.getByRole('button', { name: 'Hinzufügen', exact: true });
+		await expect.element(confirmBtn).toBeEnabled();
+	});
+
+	it('calls onAddInterlude with text on confirm', async () => {
+		const onAddInterlude = vi.fn();
+		render(JourneyAddBar, { onAddDocument: vi.fn(), onAddInterlude });
+
+		await userEvent.click(page.getByText('Zwischentext hinzufügen'));
+		await userEvent.fill(page.getByRole('textbox'), 'Reise nach Wien');
+		await userEvent.click(page.getByRole('button', { name: 'Hinzufügen', exact: true }));
+
+		expect(onAddInterlude).toHaveBeenCalledWith('Reise nach Wien');
+	});
+});
+
+describe('JourneyAddBar — document picker', () => {
+	it('reveals picker when "Brief hinzufügen" is clicked', async () => {
+		vi.stubGlobal(
+			'fetch',
+			vi.fn().mockResolvedValue({ ok: true, json: vi.fn().mockResolvedValue({ items: [] }) })
+		);
+		render(JourneyAddBar, { onAddDocument: vi.fn(), onAddInterlude: vi.fn() });
+
+		await userEvent.click(page.getByText('Brief hinzufügen'));
+
+		await expect.element(page.getByRole('combobox')).toBeInTheDocument();
+	});
+});

frontend/src/lib/geschichte/JourneyEditor.svelte

@@ -0,0 +1,341 @@
+<script lang="ts">
+import type { components } from '$lib/generated/api';
+import { m } from '$lib/paraglide/messages.js';
+import { csrfFetch } from '$lib/shared/cookies';
+import { createBlockDragDrop } from '$lib/document/transcription/useBlockDragDrop.svelte';
+import { createUnsavedWarning } from '$lib/shared/hooks/useUnsavedWarning.svelte';
+import type { DocumentOption } from '$lib/document/documentTypeahead';
+import GeschichteSidebar from './GeschichteSidebar.svelte';
+import JourneyItemRow from './JourneyItemRow.svelte';
+import JourneyAddBar from './JourneyAddBar.svelte';
+
+type GeschichteView = components['schemas']['GeschichteView'];
+type JourneyItemView = components['schemas']['JourneyItemView'];
+type Person = components['schemas']['Person'];
+
+interface Props {
+	geschichte: GeschichteView;
+	onSubmit: (payload: {
+		title: string;
+		body: string;
+		status: 'DRAFT' | 'PUBLISHED';
+		personIds: string[];
+	}) => Promise<void>;
+	submitting?: boolean;
+}
+
+let { geschichte, onSubmit, submitting = false }: Props = $props();
+
+const unsaved = createUnsavedWarning();
+
+let title = $state(geschichte.title ?? '');
+let body = $state(geschichte.body ?? '');
+let status: 'DRAFT' | 'PUBLISHED' = $state(geschichte.status ?? 'DRAFT');
+let selectedPersons: Person[] = $state(geschichte.persons ? Array.from(geschichte.persons) : []);
+let items: JourneyItemView[] = $state(
+	[...(geschichte.items ?? [])].sort((a, b) => a.position - b.position)
+);
+
+let titleTouched = $state(false);
+let mutationError = $state('');
+let liveAnnounce = $state('');
+let announceTimer: ReturnType<typeof setTimeout> | null = null;
+
+function scheduleAnnounceReset() {
+	if (announceTimer) clearTimeout(announceTimer);
+	announceTimer = setTimeout(() => {
+		liveAnnounce = '';
+		announceTimer = null;
+	}, 500);
+}
+
+const titleEmpty = $derived(title.trim().length === 0);
+const showTitleError = $derived(titleEmpty && titleTouched);
+const isDraft = $derived(status === 'DRAFT');
+const alreadyAddedIds = $derived(
+	new Set(items.filter((i) => i.document).map((i) => i.document!.id))
+);
+const canPublish = $derived(items.length > 0 && !titleEmpty);
+const showPublishedEmptyWarning = $derived(status === 'PUBLISHED' && items.length === 0);
+
+let listEl: HTMLElement | null = $state(null);
+
+const dragDrop = createBlockDragDrop<JourneyItemView>({
+	getSortedBlocks: () => items,
+	onReorder: handleReorder
+});
+
+$effect(() => {
+	dragDrop.setListElement(listEl);
+});
+
+async function handleReorder(itemIds: string[]) {
+	const prev = [...items];
+	items = itemIds.map((id) => items.find((i) => i.id === id)!);
+	mutationError = '';
+	try {
+		const res = await csrfFetch(`/api/geschichten/${geschichte.id}/items/reorder`, {
+			method: 'PUT',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({ itemIds })
+		});
+		if (!res.ok) throw new Error('reorder failed');
+		const updated: JourneyItemView[] = await res.json();
+		items = updated.sort((a, b) => a.position - b.position);
+	} catch {
+		items = prev;
+		mutationError = m.journey_mutation_error_reload();
+	}
+}
+
+async function handleAddDocument(doc: DocumentOption) {
+	const prev = [...items];
+	mutationError = '';
+	try {
+		const res = await csrfFetch(`/api/geschichten/${geschichte.id}/items`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({ documentId: doc.id })
+		});
+		if (!res.ok) throw new Error('add document failed');
+		const newItem: JourneyItemView = await res.json();
+		items = [...items, newItem];
+	} catch {
+		items = prev; // prev === items here (add is pessimistic); kept for symmetry with optimistic handlers
+		mutationError = m.journey_mutation_error_reload();
+	}
+}
+
+async function handleAddInterlude(text: string) {
+	const prev = [...items];
+	mutationError = '';
+	try {
+		const res = await csrfFetch(`/api/geschichten/${geschichte.id}/items`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({ note: text })
+		});
+		if (!res.ok) throw new Error('add interlude failed');
+		const newItem: JourneyItemView = await res.json();
+		items = [...items, newItem];
+	} catch {
+		items = prev; // prev === items here (add is pessimistic); kept for symmetry with optimistic handlers
+		mutationError = m.journey_mutation_error_reload();
+	}
+}
+
+async function handleRemove(itemId: string) {
+	const prev = [...items];
+	items = items.filter((i) => i.id !== itemId);
+	mutationError = '';
+	try {
+		const res = await csrfFetch(`/api/geschichten/${geschichte.id}/items/${itemId}`, {
+			method: 'DELETE'
+		});
+		if (!res.ok) throw new Error('delete failed');
+	} catch {
+		items = prev;
+		mutationError = m.journey_mutation_error_reload();
+	}
+}
+
+async function handleNotePatch(itemId: string, note: string | null) {
+	const res = await csrfFetch(`/api/geschichten/${geschichte.id}/items/${itemId}`, {
+		method: 'PATCH',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify({ note: note })
+	});
+	if (!res.ok) throw new Error('note patch failed');
+	const updated: JourneyItemView = await res.json();
+	items = items.map((i) => (i.id === itemId ? updated : i));
+}
+
+async function handleMoveUp(index: number) {
+	if (index === 0) return;
+	const ids = items.map((i) => i.id);
+	[ids[index - 1], ids[index]] = [ids[index], ids[index - 1]];
+	liveAnnounce = m.journey_item_moved({
+		position: index + 1,
+		total: items.length,
+		newPosition: index
+	});
+	await handleReorder(ids);
+	scheduleAnnounceReset();
+}
+
+async function handleMoveDown(index: number) {
+	if (index === items.length - 1) return;
+	const ids = items.map((i) => i.id);
+	[ids[index], ids[index + 1]] = [ids[index + 1], ids[index]];
+	liveAnnounce = m.journey_item_moved({
+		position: index + 1,
+		total: items.length,
+		newPosition: index + 2
+	});
+	await handleReorder(ids);
+	scheduleAnnounceReset();
+}
+
+async function save(nextStatus: 'DRAFT' | 'PUBLISHED') {
+	titleTouched = true;
+	if (titleEmpty) return;
+	await onSubmit({
+		title: title.trim(),
+		body,
+		status: nextStatus,
+		personIds: selectedPersons.map((p) => p.id!).filter(Boolean)
+	});
+	unsaved.clearOnSuccess();
+}
+</script>
+
+<!-- Screen-reader live region for move announcements -->
+<div aria-live="polite" aria-atomic="true" class="sr-only">{liveAnnounce}</div>
+
+<div class="grid grid-cols-1 gap-6 lg:grid-cols-[2fr_1fr]">
+	<!-- Editor column -->
+	<div class="flex flex-col gap-4">
+		<!-- Title -->
+		<div>
+			<input
+				type="text"
+				bind:value={title}
+				oninput={() => unsaved.markDirty()}
+				onblur={() => (titleTouched = true)}
+				placeholder={m.geschichte_editor_title_placeholder()}
+				aria-invalid={showTitleError}
+				aria-describedby={showTitleError ? 'journey-title-error' : undefined}
+				class="block w-full rounded border border-line bg-surface px-3 py-3 font-serif text-2xl font-bold text-ink placeholder:text-ink-3 focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+			/>
+			{#if showTitleError}
+				<p id="journey-title-error" class="mt-1 text-sm text-danger" role="alert">
+					{m.geschichte_editor_title_required()}
+				</p>
+			{/if}
+		</div>
+
+		<!-- Intro textarea -->
+		<div>
+			<textarea
+				bind:value={body}
+				oninput={() => unsaved.markDirty()}
+				placeholder={m.journey_intro_placeholder()}
+				rows={3}
+				class="block w-full resize-y rounded border border-line bg-surface px-3 py-2 font-serif text-base text-ink placeholder:text-ink-3 focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+			></textarea>
+			<p class="mt-1 font-sans text-xs text-ink-3">{m.journey_intro_save_hint()}</p>
+		</div>
+
+		<!-- Item list -->
+		{#if showPublishedEmptyWarning}
+			<p
+				class="rounded border border-amber-300 bg-amber-50 px-3 py-2 font-sans text-sm text-amber-800"
+			>
+				{m.journey_published_empty_warning()}
+			</p>
+		{/if}
+
+		{#if mutationError}
+			<p
+				class="rounded border border-danger bg-danger/10 px-3 py-2 font-sans text-sm text-danger"
+				role="alert"
+			>
+				{mutationError}
+			</p>
+		{/if}
+
+		<!-- pointer events managed by createBlockDragDrop; keyboard reorder available via move-up/down buttons on each item -->
+		<!-- svelte-ignore a11y_no_static_element_interactions -->
+		<div
+			bind:this={listEl}
+			onpointermove={(e) => dragDrop.handlePointerMove(e)}
+			onpointerup={() => dragDrop.handlePointerUp()}
+			class="flex flex-col gap-2"
+		>
+			{#if items.length === 0}
+				<p class="font-sans text-sm text-ink-3">{m.journey_empty_state()}</p>
+			{/if}
+			{#each items as item, i (item.id)}
+				<!-- pointerdown initiates drag; the drag handle button inside is the semantic interactive element -->
+				<!-- svelte-ignore a11y_no_static_element_interactions -->
+				<div
+					data-block-wrapper
+					onpointerdown={(e) => dragDrop.handleGripDown(e, item.id)}
+					class="transition-all duration-150 {dragDrop.draggedBlockId === item.id ? 'z-10 rounded-lg shadow-xl ring-2 ring-focus-ring/40' : ''}"
+					style={dragDrop.draggedBlockId === item.id
+						? `transform: translateY(${dragDrop.dragOffsetY}px) scale(1.02); opacity: 0.9;`
+						: ''}
+				>
+					{#if dragDrop.dropTargetIdx === i}
+						<div class="mb-1 h-1 rounded-full bg-accent transition-all"></div>
+					{/if}
+					<JourneyItemRow
+						item={item}
+						index={i}
+						total={items.length}
+						onMoveUp={() => handleMoveUp(i)}
+						onMoveDown={() => handleMoveDown(i)}
+						onRemove={() => handleRemove(item.id)}
+						onNotePatch={(note) => handleNotePatch(item.id, note)}
+					/>
+				</div>
+			{/each}
+		</div>
+
+		<JourneyAddBar
+			alreadyAddedIds={alreadyAddedIds}
+			onAddDocument={handleAddDocument}
+			onAddInterlude={handleAddInterlude}
+		/>
+	</div>
+
+	<!-- Sidebar -->
+	<GeschichteSidebar status={status} bind:selectedPersons={selectedPersons} />
+</div>
+
+<!-- Save bar -->
+<div
+	class="sticky bottom-0 z-10 -mx-4 mt-6 flex flex-col gap-3 border-t border-line bg-surface px-6 py-4 shadow-[0_-2px_8px_rgba(0,0,0,0.06)] sm:flex-row sm:items-center sm:justify-between"
+>
+	<p class="font-sans text-xs text-ink-3">
+		{isDraft ? m.geschichte_editor_save_hint_draft() : m.journey_save_hint_published()}
+	</p>
+	<div class="flex gap-2">
+		{#if isDraft}
+			<button
+				type="button"
+				onclick={() => save('DRAFT')}
+				disabled={submitting || titleEmpty}
+				class="inline-flex h-11 items-center rounded border border-line bg-surface px-4 font-sans text-sm font-medium text-ink hover:bg-muted focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50"
+			>
+				{m.geschichte_editor_save_draft()}
+			</button>
+			<button
+				type="button"
+				onclick={() => save('PUBLISHED')}
+				disabled={submitting || !canPublish}
+				title={canPublish ? undefined : m.journey_publish_disabled_title()}
+				class="inline-flex h-11 items-center rounded bg-primary px-4 font-sans text-sm font-medium text-primary-fg hover:opacity-90 focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50"
+			>
+				{m.geschichte_editor_publish()}
+			</button>
+		{:else}
+			<button
+				type="button"
+				onclick={() => save('DRAFT')}
+				disabled={submitting}
+				class="inline-flex h-11 items-center rounded border border-line bg-surface px-4 font-sans text-sm font-medium text-amber-700 hover:bg-muted focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50"
+			>
+				{m.geschichte_editor_unpublish()}
+			</button>
+			<button
+				type="button"
+				onclick={() => save('PUBLISHED')}
+				disabled={submitting || titleEmpty}
+				class="inline-flex h-11 items-center rounded bg-primary px-4 font-sans text-sm font-medium text-primary-fg hover:opacity-90 focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50"
+			>
+				{m.geschichte_editor_save()}
+			</button>
+		{/if}
+	</div>
+</div>