Erhoehe new-code-Coverage durch gezielte Tests fuer Reliability-Fixes

Schliesst die durch die SonarQube-Reliability-Fixes (Commit 32e32a9) neu eingefuehrten Quellzeilen testseitig ab, damit das new-coverage Quality Gate von 80% wieder erreicht wird. PdfPreviewPaneRenderingTest: - erzeugt mit PDFBox echte ein- bzw. mehrseitige PDFs und ruft loadSource() auf, sodass loadAndRenderFirstPageOnWorker (inkl. AtomicReference-Setter fuer currentDocument/currentRenderer) und renderPageOnWorker (AtomicReference-Getter) tatsaechlich ausgefuehrt werden. BootstrapRunnerGuiContextInitFailureTest: - deckt die catch-Zweige fuer InvalidStartConfigurationException, DocumentPersistenceException und unspezifische RuntimeException in initializeApplicationRunContext ab. Damit werden die Pfade ausgefuehrt, in denen guiApplicationRunContext via AtomicReference.set(Optional.empty()) zurueckgesetzt wird. Keine Aenderungen an Produktivcode oder bestehenden Tests.
Fixe SonarQube Reliability-Issues S2789, S3077 und S2184
2026-05-07 17:53:09 +02:00 · 2026-05-07 17:11:29 +02:00 · 2026-05-07 16:26:18 +02:00 · 2026-05-07 16:09:26 +02:00 · 2026-05-07 14:57:20 +02:00 · 2026-05-07 14:51:36 +02:00
580 changed files with 102520 additions and 1935 deletions
@@ -0,0 +1 @@
+/settings.local.json
@@ -1,23 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(xargs grep:*)",
-      "Bash(xargs wc:*)",
-      "Bash(mvn clean:*)",
-      "Bash(mvn verify:*)",
-      "Bash(mvn test:*)",
-      "Bash(find D:/Dev/Projects/pdf-umbenenner-parent -not -path */target/* -type d)",
-      "Bash(mvn -pl pdf-umbenenner-adapter-out clean compile)",
-      "Bash(mvn dependency:tree -pl pdf-umbenenner-adapter-out)",
-      "Bash(mvn -pl pdf-umbenenner-domain clean compile)",
-      "Bash(mvn help:describe -Dplugin=org.apache.pdfbox:pdfbox -Ddetail=false)",
-      "Bash(cd /d D:/Dev/Projects/pdf-umbenenner-parent)",
-      "Bash(mvn -v)",
-      "Bash(grep -E \"\\\\.java$\")",
-      "Bash(grep \"\\\\.java$\")",
-      "Bash(mvn -q clean compile -DskipTests)",
-      "Bash(mvn -q test)",
-      "Bash(mvn -q clean test)"
-    ]
-  }
-}
@@ -3,6 +3,8 @@
 # =========================================================
 **/target/
 dependency-reduced-pom.xml
+# Generierte Flat-POM-Dateien des flatten-maven-plugin (CI-friendly Versioning)
+**/.flattened-pom.xml

 # =========================================================
 # Eclipse / IDE
@@ -72,3 +74,7 @@ Desktop.ini
 hs_err_pid*
 replay_pid*
 /review-input.zip
+/run-milestone.ps1
+/run-v11.ps1
+.m2repo
+/start-headless.bat
@@ -3,34 +3,46 @@
 ## Zweck
 Dieses Repository implementiert einen lokal gestarteten **PDF-Umbenenner mit KI**. Das Programm liest bereits OCR-verarbeitete, durchsuchbare PDF-Dateien aus einem Quellordner, ermittelt daraus einen normierten Dateinamen und legt **eine Kopie** der Datei im Zielordner ab. Die Quelldatei bleibt unverändert.

+Ab V2.0 wird die Anwendung um eine **lokale JavaFX-Desktop-GUI** erweitert. Die GUI ist der neue Standardstart. Der bestehende headless Batch-Betrieb bleibt über `--headless` vollständig erhalten.
+
 ## Autoritative Dokumente
@docs/specs/technik-und-architektur.md
@docs/specs/fachliche-anforderungen.md
-@docs/specs/meilensteine.md
+@docs/specs/meilensteine-v2_0.md

 Für die Umsetzung ist zusätzlich immer das aktuell aktive Arbeitspaket unter `docs/workpackages/` maßgeblich.
+Dateinamensschema: `M9 - Arbeitspakete.md`, `M10 - Arbeitspakete.md`, … `M13 - Arbeitspakete.md`, `M14_-_Arbeitspakete.md`, `M15_-_Arbeitspakete.md`.
 Nicht raten, wenn Dokumente fehlen, unklar sind oder sich widersprechen.

+## Modulare Architektur-Übersichten
+Detailwissen über Pakete, Schlüsselklassen, Ports und Bootstrap-Verdrahtung ist in drei modularen Übersichtsdokumenten unter `docs/architecture/` ausgelagert. Wer in einem bestimmten Modul arbeitet, liest diese Datei zusätzlich zu CLAUDE.md:
+
+- `docs/architecture/domain-overview.md` – `pdf-umbenenner-domain` und `pdf-umbenenner-application`: Domänenmodell, Inbound- und Outbound-Ports, Application-Services.
+- `docs/architecture/gui-overview.md` – `pdf-umbenenner-adapter-in-gui`: Workspace-/Tab-Struktur, View-Modelle, GUI-interne Ports, JavaFX-Threading-Modell.
+- `docs/architecture/adapter-overview.md` – `pdf-umbenenner-adapter-out`, `pdf-umbenenner-adapter-in-cli`, `pdf-umbenenner-bootstrap`: konkrete Outbound-Adapter, CLI-Einstiegspunkt, Verdrahtungslogik und Provider-Auswahl.
+
+Für Arbeit ausschließlich in einem dieser Bereiche genügt CLAUDE.md plus die jeweils passende Übersichtsdatei.
+
 ## Priorisierung der Regeln
 Die Dokumente haben folgende feste Bedeutung:

 - `docs/specs/technik-und-architektur.md` = verbindliche technische Zielarchitektur
 - `docs/specs/fachliche-anforderungen.md` = verbindliche fachliche Regeln
- `docs/specs/meilensteine.md` = zulässiger Funktionsumfang pro Meilenstein
+- `docs/specs/meilensteine-v2_0.md` = verbindliche V2.0-Zieldefinition und Meilensteinabgrenzung
 - `docs/workpackages/...` = verbindlicher Scope, Reihenfolge und Inhalt des aktuell bearbeiteten Arbeitspakets

 Bei Konflikten gilt folgende Priorität:

-1. **Technik- und Architektur-Dokument**  
+1. **Technik- und Architektur-Dokument**
   Verbindliche technische Zielarchitektur. Architekturbrüche sind unzulässig.

-2. **Fachliche Anforderungen**  
+2. **Fachliche Anforderungen**
   Verbindliche fachliche Regeln und fachliches Zielverhalten.

-3. **Meilensteine**  
-   Begrenzen den zulässigen Funktionsumfang auf den aktuellen Entwicklungsstand.
+3. **Meilensteine V2.0**
+   Verbindliche Zieldefinition, Abgrenzungen und Leitplanken für den V2.0-Ausbau.

-4. **Arbeitspakete**  
+4. **Arbeitspakete**
   Definieren den konkret erlaubten Umsetzungsumfang des aktuellen Schritts.

 Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und keine stillen Annahmen treffen.
@@ -38,40 +50,108 @@ Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und kein
 ## Unverrückbare Technikvorgaben
 - Java 21
 - Maven Multi-Module
- ausführbares Standalone-JAR
- Start über Windows Task Scheduler
+- ausführbares Standalone-JAR (ein gemeinsames JAR für GUI und headless)
+- **GUI ist der neue Standardstart** (ab V2.0)
+- `--headless` startet weiterhin den bestehenden Batch-/Scheduler-Betrieb
+- `--config <pfad>` steht für GUI und headless zur Verfügung
 - kein Webserver
 - kein Applikationsserver
- keine Dauerlauf-Anwendung
- kein interner Scheduler
+- keine Dauerlauf-Anwendung (Ausnahme: GUI-Modus mit aktivem Scheduler, s. Scheduler-Ausnahme)
+- kein interner Scheduler (Ausnahme: optionaler GUI-Scheduler ab V3.2, s. Scheduler-Ausnahme)
+- das Shade-JAR bleibt das primäre Distributionsartefakt
+- zusätzlicher nativer Windows-Installer (MSI) ab V3.0 via Maven-Profil `release` (jpackage, WiX Toolset 3.x im PATH erforderlich); der Normalbuild `mvn clean verify` bleibt vom Profil unberührt und benötigt kein WiX
 - Log4j2 für Logging
 - SQLite als lokaler Persistenzspeicher
- OpenAI-kompatible HTTP-Schnittstelle für KI-Zugriff
- API-Provider, Base-URL und Modellname sind **Konfiguration**, keine Architekturentscheidung
+- JavaFX wird mit dem JAR ausgeliefert (kein separates JavaFX-Setup)
+- GUI offiziell nur für Windows; headless bleibt für Windows Server / Task Scheduler geeignet
+- gemappte Laufwerke wie `S:\` oder `H:\` sind ausdrücklich zu unterstützen
+- KI-Anbindung über genau **eine** der beiden unterstützten Provider-Familien:
+  - **OpenAI-kompatible HTTP-Schnittstelle** (Chat-Completions-Stil)
+  - **native Anthropic Messages API** (Claude-Modelle)
+- Pro Lauf ist genau ein Provider aktiv. Kein Fallback, keine Parallelnutzung.
+- `.properties` bleibt die einzige Konfigurationswahrheit
+- Konkrete Provider-Familie, Base-URL und Modellname sind **Konfiguration**, keine Architekturentscheidung.

-## Verbindliche Modulstruktur
+## Verbindliche Modulstruktur (ab V2.0)
 - `pdf-umbenenner-domain`
 - `pdf-umbenenner-application`
 - `pdf-umbenenner-adapter-in-cli`
+- `pdf-umbenenner-adapter-in-gui`
+- `pdf-umbenenner-adapter-in-scheduler`
 - `pdf-umbenenner-adapter-out`
 - `pdf-umbenenner-bootstrap`

+## Scheduler-Ausnahme (ab V3.2)
+
+Ab V3.2 enthält der GUI-Modus einen optionalen internen Scheduler, der periodisch
+automatische Verarbeitungsläufe anstößt. Die folgenden Regeln gelten abweichend von
+den allgemeinen Leitplanken:
+
+- Der Scheduler ist **ausschließlich im GUI-Modus** verfügbar. Im headless Betrieb werden
+  `scheduler.enabled` und `scheduler.interval.seconds` vollständig ignoriert.
+- Das Modul `pdf-umbenenner-adapter-in-scheduler` erfüllt eine gemischte Rolle als
+  technischer Treiber und Adapter. Dies ist ein bewusster Architekturkompromiss, kein
+  Architekturbruch.
+- `pdf-umbenenner-adapter-in-scheduler` enthält **kein JavaFX**.
+- **Kein WatchService:** Der Scheduler löst reguläre Verarbeitungsläufe periodisch aus;
+  er nutzt keinen Dateisystem-Event-Mechanismus.
+- Das bestehende Datenbankschema bleibt in V3.2 unverändert; keine
+  Scheduler-spezifische Schemaerweiterung.
+- Token- und Kostentracking sind nicht Bestandteil von V3.2.
+
 ## Architekturregeln
 - Strikte **hexagonale Architektur / Ports and Adapters**
 - Abhängigkeiten zeigen immer **nach innen**
- Domain kennt **keine** Infrastruktur, keine Datenbank, kein Dateisystem und keine HTTP-Kommunikation
- Application orchestriert Use Cases und enthält keine technischen Implementierungsdetails
+- Domain kennt **keine** Infrastruktur, keine Datenbank, kein Dateisystem, keine HTTP-Kommunikation und **kein JavaFX**
+- Application enthält keine technischen Implementierungsdetails und **keine JavaFX-Typen**
 - Externe Zugriffe erfolgen ausschließlich über **Ports**
 - Konkrete technische Implementierungen sind **Adapter**
 - Adapter dürfen nicht direkt voneinander abhängen
+- Die GUI ist ein **Inbound-Adapter** (`pdf-umbenenner-adapter-in-gui`) – sie wird **nicht** in Bootstrap vermischt
+- Bootstrap bleibt verantwortlich für: Startmoduswahl, Konfigurationsauflösung, Objektgraph, kontrollierten Start des passenden Adapters, Exit-Code-Ableitung bei harten Startfehlern
+- GUI-Code und JavaFX dürfen im **headless Pfad** nicht unnötig früh initialisiert oder geladen werden
 - Keine Vermischung von Dateisystem, PDF-Auslese, SQLite, KI-HTTP, Konfiguration, Logging, Benennungslogik und Retry-Entscheidungen
 - Logging ist technische Infrastruktur, kein fachlicher Port
+- Port-Verträge enthalten weder `Path`/`File` noch NIO- oder JDBC-Typen
+- Der `AiNamingPort` bleibt provider-neutral; provider-spezifische Typen, Header, URLs und Antwortstrukturen leben ausschließlich in der jeweiligen Adapter-Out-Implementierung
+- Es gibt keine gemeinsame „abstrakte KI-Adapter"-Zwischenschicht zwischen Port und konkreten Adaptern
+- Die Bootstrap-Schicht wählt die **eine** aktive `AiNamingPort`-Implementierung anhand der Konfiguration aus
+
+## GUI-Leitplanken (verbindlich für alle V2.0-Arbeitspakete)
+
+### Threadingmodell
+- Jede potenziell blockierende Operation (Modellabruf, technische Tests, Pfad-/Dateisystemprüfungen, SQLite-Prüfungen, Lesen/Schreiben der `.properties`) läuft auf einem **Hintergrund-Worker-Thread**
+- UI-Updates erfolgen ausschließlich über den **JavaFX Application Thread** (`Platform.runLater`)
+- Die GUI darf während laufender Hintergrund-Operationen **nicht einfrieren**
+
+### GUI-Teststrategie
+- **View-Modelle und Application-nahe GUI-Logik** werden mit JUnit unit-getestet; Fokus auf Zustandsübergängen, Validierungsregeln und Datenflüssen – nicht auf Rendering
+- **GUI-Smoke-Tests** laufen unter **headless JavaFX (Monocle)** in der Maven-Test-Phase
+- Kein TestFX, kein weiteres GUI-Testframework über Monocle hinaus
+
+### GUI-Logging
+- Der GUI-Adapter nutzt denselben Log4j2-Stack wie der headless Pfad
+- Logformat und Log-Verzeichnis bleiben gegenüber dem headless Betrieb unverändert
+- Mindesteinträge für GUI-nahe Ereignisse: Start- und Beendigungsereignisse der GUI, Modellabruf-Versuche (Provider, Erfolg/Misserfolg, **ohne API-Key**), Dateischreibvorgänge inkl. Zielpfad, Ergebnisse der Aktionen `Validieren` und `Technische Tests ausführen`, sowie alle schreibenden Korrekturen
+
+### `--config`-Semantik
+- Zeigt `--config <pfad>` im **GUI-Start** auf eine nicht existente Datei: Fehlermeldung, danach verhält sich die GUI so, als wäre `--config` nicht angegeben worden
+- Zeigt `--config <pfad>` im **headless Start** auf eine nicht existente Datei: **harter Startfehler**, kein stiller Fallback
+
+## JavaDoc-Standard (verbindlich für alle V2.0-Arbeitspakete)
+Für jede **neu hinzugefügte** oder **substanziell geänderte** öffentliche Klasse, öffentliche Methode und jedes neue Java-Package gilt:
+- **Klassen-JavaDoc**: Zweck, Verantwortung und Abgrenzung der Klasse
+- **Methoden-JavaDoc**: Zweck, Parameter, Rückgabewert und dokumentierte Ausnahmen
+- **`package-info.java`**: pro neuem Package, mit Kurzbeschreibung der Paketverantwortung
+
+Ein Arbeitspaket ist erst fertig, wenn die betroffenen öffentlichen Klassen und Methoden dem JavaDoc-Standard entsprechen.

 ## Globale fachliche Leitplanken
 - Zielformat: `YYYY-MM-DD - Titel.pdf`
 - Bei Namenskollisionen: `YYYY-MM-DD - Titel(1).pdf`, `YYYY-MM-DD - Titel(2).pdf`, ...
- Die **20 Zeichen** gelten nur für den **Basistitel**; das Dubletten-Suffix zählt nicht mit
- Titel sind **deutsch**, verständlich, eindeutig und enthalten keine Sonderzeichen außer Leerzeichen
+- Die **konfigurierte maximale Titellänge** gilt nur für den **Basistitel**; das Dubletten-Suffix zählt nicht mit
+- Das Dubletten-Suffix wird unmittelbar vor `.pdf` angehängt
+- Titel sind **deutsch**, verständlich, eindeutig und enthalten keine Sonderzeichen außer Leerzeichen, Bindestrichen, Punkten, Kommas und Ampersands
 - Eigennamen bleiben unverändert
 - Datumsermittlung mit Priorität aus den fachlichen Anforderungen; wenn kein belastbares Datum eindeutig ableitbar ist, ist das **aktuelle Datum** als Fallback erlaubt
 - Mehrdeutige Dokumente liefern **kein** unsicheres Ergebnis, sondern einen Fehler
@@ -81,42 +161,218 @@ Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und kein
 - Identifikation erfolgt **nicht** über Dateinamen
 - Quelldateien werden **nie** überschrieben, verändert, verschoben oder gelöscht

+## Aktiver Implementierungsstand
+V1.1 ist vollständig umgesetzt, dokumentiert, getestet und freigegeben.
+
+Der Basisstand V2.0 (JavaFX-GUI als Standardstart, Konfigurationseditor, technische Tests) ist abgeschlossen.
+
+**V2.9 ist abgeschlossen.** Der Tab „Verarbeitungslauf" wurde erweitert um eine integrierte PDF-Vorschau (Lazy-Rendering direkt über PDFBox, In-Memory-Cache, Seitennavigation) sowie einen editierbaren Dateiname-Bereich mit Live-Validierung, Dirty-State-Dialog und atomarer Dateisystem-/DB-Transaktion inklusive Rollback und Fingerprint-basierter Konfliktauflösung. Die zugehörigen neuen Ports, Use Cases und Adapter sind in den modularen Architektur-Übersichten beschrieben.
+
+Verhaltensänderungen seit V2.9: Die GUI startet maximiert, und die zuletzt geladene Konfigurationsdatei wird beim Start automatisch wieder geladen; existiert sie nicht mehr, startet die GUI ohne Fehlermeldung mit dem Willkommenstext.
+
+**V3.2 ist abgeschlossen.** Der GUI-Modus wurde um einen optionalen automatischen Scheduler erweitert (neuer Tab „Scheduler"). Der Scheduler startet periodisch Verarbeitungsläufe; Intervall und Autostart sind konfigurierbar. Während der Scheduler aktiv ist, sind der Konfigurations-Tab und das manuelle Starten von Läufen gesperrt. Im headless Betrieb werden Scheduler-Parameter vollständig ignoriert.
+
+Die fachliche Kernverarbeitung des PDF-Umbenenners bleibt unverändert.
+
+## Statussemantik
+
+| Status | Bedeutung |
+|---|---|
+| `READY_FOR_AI` | Verarbeitbar, KI-Pfad noch nicht durchlaufen |
+| `FAILED_RETRYABLE` | Verarbeitbar, transient fehlgeschlagen |
+| `PROPOSAL_READY` | Eingangszustand für Dateinamensbildung und Zielkopie |
+| `SUCCESS` | Terminaler Enderfolg – nur nach Zielkopie und konsistenter Persistenz zulässig |
+| `FAILED_FINAL` | Terminal, wird nicht erneut fachlich verarbeitet |
+| `SKIPPED_ALREADY_PROCESSED` | Historisierter Skip für SUCCESS-Dokumente |
+| `SKIPPED_FINAL_FAILURE` | Historisierter Skip für FAILED_FINAL-Dokumente |
+
+### SUCCESS-Bedingung (verbindlich)
+`SUCCESS` darf erst gesetzt werden, wenn:
+1. die Zielkopie erfolgreich geschrieben wurde,
+2. der finale Zieldateiname bestimmt ist,
+3. die Persistenz konsistent fortgeschrieben wurde.
+
+### Führende Quelle des Benennungsvorschlags (verbindlich)
+- Die führende Quelle für Datum, Datumsquelle, validierten Titel und Reasoning ist der **neueste Versuchshistorieneintrag mit Status `PROPOSAL_READY`**
+- Kein Rekonstruieren aus dem Dokument-Stammsatz
+- Kein neuer KI-Aufruf, wenn bereits ein nutzbarer `PROPOSAL_READY`-Versuch vorliegt
+- Status `PROPOSAL_READY` ohne lesbaren konsistenten Proposal-Versuch = dokumentbezogener technischer Fehler
+- Inkonsistente Proposal-Zustände werden **nicht stillschweigend geheilt**, sondern als technische Dokumentfehler behandelt
+
+## Retry-Semantik
+
+### Deterministische Inhaltsfehler
+- **erster** historisierter deterministischer Inhaltsfehler → `FAILED_RETRYABLE`
+- **zweiter** historisierter deterministischer Inhaltsfehler → `FAILED_FINAL`
+
+### Transiente technische Fehler
+- Transiente Fehler laufen über den Transientfehlerzähler im Dokument-Stammsatz
+- Retryable bis der konfigurierte Grenzwert `max.retries.transient` erreicht ist
+- Der Fehlversuch, der den Grenzwert **erreicht**, finalisiert den Dokumentstatus zu `FAILED_FINAL`
+- `max.retries.transient` = **Integer >= 1**; der Wert `0` ist ungültige Startkonfiguration
+
+### Technischer Sofort-Wiederholversuch
+- **Genau ein** zusätzlicher technischer Schreibversuch innerhalb desselben Dokumentlaufs
+- **Ausschließlich** für Fehler beim physischen Zielkopierpfad
+- Kein erneuter KI-Aufruf, keine erneute Fachableitung
+- Zählt **nicht** zum laufübergreifenden Transientfehlerzähler
+
+## Exit-Codes (verbindlich)
+- **`0`**: normale erfolgreiche Beendigung eines headless Laufs sowie für das reguläre Beenden der GUI
+- **`1`**: harte Start-, Bootstrap-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler, einschließlich ungültiger CLI-Verwendung, nicht existenter `--config`-Datei im headless Start und GUI-Startfehlern vor erfolgreicher Anzeige der Oberfläche
+- Dokumentbezogene Verarbeitungsfehler im headless Lauf ändern dieses Exit-Code-Modell nicht
+
+## Persistenz
+
+Zwei-Ebenen-Modell – keine dritte Wahrheitsquelle.
+
+**Dokument-Stammsatz** enthält u.a.:
+- letzten Zielpfad, letzten Zieldateinamen
+- Inhaltsfehler- und Transientfehlerzähler
+- Gesamtstatus
+
+**Versuchshistorie** enthält u.a.:
+- finalen Zieldateinamen
+- Fehlerklasse, Fehlermeldung, Retryable-Flag
+- **Provider-Identifikator des aktiven KI-Providers für den Versuch**
+
+**Invariante:** Der führende `PROPOSAL_READY`-Versuch wird nicht überschrieben. Jeder Lauf erzeugt einen **zusätzlichen** neuen Versuchseintrag.
+
+**Rückwärtsverträglichkeit:** Bestehende Datenbestände bleiben lesbar, fortschreibbar und korrekt interpretierbar.
+
+## Naming-Regel (verbindlich für alle Arbeitspakete)
+In Implementierungen, Kommentaren und JavaDoc dürfen **keine** Meilenstein- oder Arbeitspaket-Bezeichner erscheinen:
+
+- Verboten: `M1`, `M2`, …, `M13`
+- Verboten: `AP-001`, `AP-002`, … `AP-0xx`
+- Verboten: Versionsbezeichner wie `V1.0`, `V1.1`, `V2.0` in Code/JavaDoc
+
+Stattdessen werden **zeitlose technische Bezeichnungen** verwendet.
+Bestehende Kommentare mit solchen Bezeichnern, die durch eigene Änderungen berührt werden, sind zu ersetzen.
+
 ## Arbeitsweise
- Arbeite immer nur im **explizit aktiven Meilenstein** und im **explizit aktiven Arbeitspaket**
- **Kein Vorgriff** auf spätere Meilensteine oder Arbeitspakete
+- Arbeite immer nur im **explizit aktiven Arbeitspaket**
+- **Kein Vorgriff** auf spätere Arbeitspakete
 - Änderungen klein, fokussiert und architekturtreu halten
 - Keine unnötigen Umbenennungen, keine großflächigen Refactorings ohne Not
 - Vor Änderungen zuerst die betroffenen Dateien und Abhängigkeiten verstehen
+- **Keine Annahmen über Dateipfade.** Typen und Klassen werden per Suche nach Typname gefunden, nicht über vermutete Pfade.
 - Keine Vermutungen: Bei echter Unklarheit oder Dokumentkonflikten knapp nachfragen oder den Konflikt benennen
+- Keine stillen Änderungen am bestehenden headless Batch-Betrieb
+- GUI-Code darf den headless Pfad nicht unnötig früh initialisieren
+
+## Commit und Push nach jeder Implementierung
+Nach jeder Implementierung oder Dateiänderung wird ein Commit auf `main` erstellt und gepusht:
+1. Geänderte Dateien stagen und committen
+2. `git push origin main` ausführen
+3. Schlägt der Push mit einem AUTH-Fehler fehl: 1 Sekunde warten, dann genau **einen** weiteren Versuch unternehmen
+4. Schlägt auch der zweite Versuch fehl: Fehler benennen, keinen weiteren automatischen Retry

 ## Definition of Done pro Arbeitspaket
 Ein Arbeitspaket ist erst fertig, wenn:
 - der Zielumfang des aktuellen Arbeitspakets vollständig umgesetzt ist
 - der Stand konsistent, fehlerfrei und buildbar ist
- Implementierung, Konfiguration, JavaDoc und Tests ergänzt sind, **soweit für den Stand sinnvoll**
- keine Inhalte späterer Meilensteine vorweggenommen wurden
+- Implementierung, Konfiguration, JavaDoc (inkl. `package-info.java` für neue Packages) und Tests ergänzt sind
+- der JavaDoc-Standard für alle neu hinzugefügten oder substanziell geänderten öffentlichen Klassen und Methoden eingehalten wurde
+- keine Inhalte späterer Arbeitspakete vorweggenommen wurden
 - der Zwischenstand in sich geschlossen und übergabefähig ist

+## Pflicht-Output-Format nach jedem Arbeitspaket
+
+```
+- Scope erfüllt: ja/nein
+- Geänderte Dateien:
+  - <Dateipfad>
+  - ...
+- Build-Kommando: <verwendetes Kommando>
+- Build-Status: ERFOLGREICH / FEHLGESCHLAGEN
+- Offene Punkte: keine / <Beschreibung>
+- Risiken: keine / <Beschreibung>
+```
+
 ## Qualitäts- und Prüfreihenfolge
 - Nur den für das aktuelle Arbeitspaket nötigen Scope ändern
 - Nach Änderungen den kleinsten sinnvollen Build-/Test-Umfang ausführen
+- Build-Validierung vom Parent-Root (Beispiel für vollständigen Reactor-Build ab V2.0):
+  `.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-adapter-in-gui,pdf-umbenenner-bootstrap --also-make`
+- MSI-Build (nur lokal auf der Entwicklungsmaschine, WiX Toolset 3.x im PATH erforderlich):
+  `.\mvnw.cmd clean package -P release -pl pdf-umbenenner-packaging --also-make -DskipTests`
+- Schlägt der Build fehl: Fehler beheben, erneut bauen, erst dann weiter
 - Vor Abschluss sicherstellen, dass der relevante Maven-Reactor-Stand fehlerfrei ist
 - Fehler nicht kaschieren; Ursachen sauber beheben oder offen benennen

 ## Wichtige Betriebsregeln
 - Ungültige Startkonfiguration verhindert den Verarbeitungslauf und führt zu Exit-Code `1`
+- Eine ungültige oder fehlende Provider-Auswahl ist eine ungültige Startkonfiguration
 - Run-Lock verhindert parallele Instanzen; wenn bereits eine Instanz läuft, beendet sich die neue Instanz sofort
- Exit-Code `0`: Lauf technisch ordnungsgemäß ausgeführt, auch wenn einzelne Dateien fachlich oder transient fehlgeschlagen sind
- Exit-Code `1`: harter Start-/Bootstrap-Fehler
- Umgebungsvariable hat Vorrang vor Properties beim API-Key
+- API-Schlüssel: pro Provider eine eigene Umgebungsvariable, Vorrang vor Properties derselben Provider-Familie. Schlüssel verschiedener Provider werden niemals vermischt.
+- Dokumentbezogene Fehler führen **nicht** zu Exit-Code `1`
+
+## Konfigurationsparameter
+Verbindlich zweckmäßige Parameter:
+- `source.folder` – Quellordner
+- `target.folder` – Zielordner (muss vorhanden oder anlegbar sein, Schreibzugriff erforderlich)
+- `sqlite.file` – SQLite-Datenbankdatei
+- `ai.provider.active` – aktiver KI-Provider (Pflicht)
+- `max.retries.transient` – max. historisierte transiente Fehlversuche pro Fingerprint (**Integer >= 1**, `0` ist ungültig)
+- `max.pages` – Seitenlimit
+- `max.text.characters` – maximale Zeichenzahl für KI-Eingabe
+- `max.title.length` – maximale Länge des Basistitels in Zeichen (gültiger Bereich 10..120, Default 60)
+- `prompt.template.file` – externe Prompt-Datei
+- `log.ai.sensitive` – sensible KI-Logausgabe freischalten (Boolean, Default: `false`)
+- `runtime.lock.file` – Lock-Datei (optional)
+- `log.directory` – Log-Verzeichnis (optional)
+- `scheduler.enabled` – Scheduler im GUI-Modus aktivieren (Boolean, Default: `false`; wird im headless Betrieb vollständig ignoriert)
+- `scheduler.interval.seconds` – Intervall zwischen automatischen Läufen in Sekunden (Integer >= 30, Pflicht wenn `scheduler.enabled=true`; wird im headless Betrieb vollständig ignoriert)
+
+Pro Provider-Familie existiert ein eigener Parameter-Namensraum:
+
+```properties
+ai.provider.active=openai-compatible
+
+ai.provider.openai-compatible.baseUrl=...
+ai.provider.openai-compatible.model=...
+ai.provider.openai-compatible.timeoutSeconds=...
+ai.provider.openai-compatible.apiKey=...
+
+ai.provider.claude.baseUrl=...
+ai.provider.claude.model=...
+ai.provider.claude.timeoutSeconds=...
+ai.provider.claude.apiKey=...
+```
+
+### Migration historischer Konfiguration
+Bestehende Properties-Dateien des Vorgängerstands (flache Schlüssel wie `api.baseUrl`, `api.model`, `api.timeoutSeconds`, `api.key`) werden beim ersten Start erkannt und kontrolliert in das neue Schema überführt.
+
+Verbindlicher Ablauf:
+1. Legacy-Form erkennen
+2. **`.bak`-Sicherung** der Originaldatei anlegen
+3. Inhalt in das neue Schema überführen (Legacy-Werte → Namensraum `openai-compatible`, `ai.provider.active=openai-compatible`)
+4. Datei in-place schreiben
+5. Datei erneut laden und validieren
+6. Erst danach den normalen Lauf fortsetzen

 ## Nicht-Ziele / Verbote
+- kein manueller Verarbeitungslauf aus der GUI (kein vollständiger Lauf; Bearbeitungen nach Lauf sind zulässig)
+- kein DB-/Historien-Tab in der GUI (erst V2.x+)
+- kein Kosten-Tracking (erst V2.x+)
+- kein echter Mini-KI-Testaufruf mit fachlicher Antwortauswertung
 - kein Web-UI
 - keine REST-API zur Bedienung
 - keine OCR innerhalb der Java-Anwendung
 - keine DMS-Funktionalität
 - kein menschlicher Review-Workflow in der Anwendung
- keine interne Scheduler-Logik
+- keine interne Scheduler-Logik außerhalb des optionalen GUI-Schedulers (s. Scheduler-Ausnahme)
 - keine Architekturbrüche
 - keine neuen Bibliotheken oder Frameworks ohne klare Notwendigkeit und Begründung
- keine stillen Änderungen an Provider-Bindung oder Architekturprinzipien
+- **keine** automatische Fallback-Umschaltung zwischen KI-Providern
+- **keine** parallele Nutzung mehrerer KI-Provider in einem Lauf
+- **keine** Profilverwaltung mit mehreren Konfigurationen je Provider-Familie
+- **keine** Provider-Familien jenseits der explizit unterstützten
+- kein neues Konfigurationsformat
+- keine Änderung der fachlichen Kernverarbeitung des PDF-Umbenenners
+- keine Änderung der bestehenden Status-, Retry- oder Persistenz-Wahrheit
+- keine stillen Änderungen am bestehenden headless Batch-Betrieb
+- kein Sofort-Wiederholversuch außerhalb des Zielkopierpfads
+- keine spekulativen Umbauten ohne konkreten Qualitäts- oder Konsistenzbezug
+- kein großflächiges Refactoring ohne nachweisbaren Defektbezug
@@ -0,0 +1,194 @@
+// Jenkins-Pipeline für den PDF KI Renamer
+// Läuft auf einem Linux-Container (Synology NAS).
+// Der MSI-Build ist Windows-only (jpackage + WiX Toolset 3.x). Jenkins läuft im
+// Linux-Container auf Synology NAS und kann kein MSI erzeugen. Der MSI-Build
+// wird bewusst manuell auf der Windows-Entwicklungsmaschine ausgeführt:
+//   .\mvnw.cmd clean package -P release -pl pdf-umbenenner-packaging --also-make -DskipTests
+
+pipeline {
+    agent any
+
+    options {
+        disableConcurrentBuilds()
+    }
+
+    tools {
+        maven 'maven-3'
+    }
+
+    // MAJOR und MINOR werden manuell als Jenkins-Parameter gepflegt.
+    // BUILD_NUMBER wird automatisch durch Jenkins vergeben.
+    // Die resultierende Versionsnummer lautet: MAJOR.MINOR.BUILD_NUMBER
+    parameters {
+        string(name: 'MAJOR', defaultValue: '3', description: 'SemVer MAJOR (manuell)')
+        string(name: 'MINOR', defaultValue: '0', description: 'SemVer MINOR (manuell)')
+    }
+
+    stages {
+
+        stage('Version bestimmen') {
+            steps {
+                script {
+                    def isManual = !currentBuild.getBuildCauses('hudson.model.Cause$UserIdCause').isEmpty()
+                    def jenkinsHome = env.JENKINS_HOME ?: '/var/jenkins_home'
+                    def safeJobName = env.JOB_NAME.replaceAll(/[^A-Za-z0-9._-]/, '_')
+                    def stateDir = "${jenkinsHome}/version-state"
+                    def stateFile = "${stateDir}/${safeJobName}.properties"
+
+                    if (isManual) {
+                        env.EFFECTIVE_MAJOR = params.MAJOR
+                        env.EFFECTIVE_MINOR = params.MINOR
+
+                        sh """
+                          mkdir -p '${stateDir}'
+                          cat > '${stateFile}' <<'EOF'
+MAJOR=${params.MAJOR}
+MINOR=${params.MINOR}
+EOF
+                        """
+
+                        echo "Manueller Build erkannt. Version gespeichert: ${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}"
+                    } else {
+                        def stateExists = (sh(script: "[ -f '${stateFile}' ]", returnStatus: true) == 0)
+
+                        if (stateExists) {
+                            env.EFFECTIVE_MAJOR = sh(
+                                script: "grep '^MAJOR=' '${stateFile}' | cut -d= -f2-",
+                                returnStdout: true
+                            ).trim()
+
+                            env.EFFECTIVE_MINOR = sh(
+                                script: "grep '^MINOR=' '${stateFile}' | cut -d= -f2-",
+                                returnStdout: true
+                            ).trim()
+
+                            echo "Automatischer Build erkannt. Gespeicherte Version verwendet: ${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}"
+                        } else {
+                            env.EFFECTIVE_MAJOR = params.MAJOR
+                            env.EFFECTIVE_MINOR = params.MINOR
+
+                            echo "Automatischer Build ohne gespeicherten Stand. Fallback auf Parameter: ${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}"
+                        }
+                    }
+
+                    currentBuild.displayName = "#${env.BUILD_NUMBER} ${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}"
+                }
+            }
+        } // stage: Version bestimmen
+
+        stage('Maven Build') {
+            steps {
+                catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
+                    // -Drevision übergibt die vollständige Versionsnummer an Maven.
+                    // Das flatten-maven-plugin im Parent-POM löst ${revision} in
+                    // allen installierten POMs auf.
+                    sh "mvn clean verify -Drevision=${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}.${env.BUILD_NUMBER}"
+                }
+            }
+        } // stage: Maven Build
+
+		stage('SonarQube Analyse') {
+            steps {
+                catchError(buildResult: 'SUCCESS', stageResult: 'FAILURE') {
+                    withSonarQubeEnv('SonarQube') {
+                        sh "mvn sonar:sonar -Drevision=${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}.${env.BUILD_NUMBER} -Dsonar.projectKey=pdf-umbenenner -Dsonar.projectName='PDF KI Renamer'"
+                    }
+                }
+            }
+        } // stage: SonarQube Analyse
+
+        stage('Publish PIT Coverage') {
+            steps {
+                recordCoverage(
+                    tools: [[
+                        parser: 'PIT',
+                        pattern: '**/target/pit-reports/mutations.xml'
+                    ]],
+                    id: 'pit',
+                    name: 'PIT Mutation Coverage',
+                    failOnError: true
+                )
+            }
+        } // stage: Publish PIT Coverage
+
+        stage('Archive JAR') {
+            steps {
+                // Bash wird explizit erzwungen, weil Jenkins-Agenten standardmäßig
+                // sh (dash) verwenden, das kein mapfile kennt. mapfile zählt exakt
+                // die gefundenen Shade-JARs und bricht ab, wenn nicht genau eines vorhanden ist.
+                sh '''#!/usr/bin/env bash
+set -euo pipefail
+
+mapfile -t JARS < <(find pdf-umbenenner-bootstrap/target \
+    -maxdepth 1 -name "pdf-umbenenner-bootstrap-*.jar" \
+    ! -name "*-sources.jar" ! -name "*-javadoc.jar")
+
+test "${#JARS[@]}" -eq 1 \
+    || { echo "FEHLER: Erwartet genau 1 Shade-JAR, gefunden: ${#JARS[@]}"; exit 1; }
+
+JAR_NAME="pdf-ki-renamer-${EFFECTIVE_MAJOR}.${EFFECTIVE_MINOR}.${BUILD_NUMBER}.jar"
+cp "${JARS[0]}" "$JAR_NAME"
+echo "Shade-JAR archiviert als: $JAR_NAME"
+'''
+                archiveArtifacts artifacts: 'pdf-ki-renamer-*.jar', fingerprint: true
+            }
+        } // stage: Archive JAR
+
+        stage('Artefakt ablegen') {
+            steps {
+                sh '''#!/usr/bin/env bash
+set -euo pipefail
+
+BUILD_DIR="/builds/${EFFECTIVE_MAJOR}.${EFFECTIVE_MINOR}.${BUILD_NUMBER}"
+mkdir -p "$BUILD_DIR"
+cp pdf-ki-renamer-*.jar "$BUILD_DIR/"
+echo "Artefakt abgelegt unter: $BUILD_DIR"
+'''
+            }
+        } // stage: Artefakt ablegen
+
+        stage('Berichte veröffentlichen') {
+            steps {
+                junit testResults: '**/target/surefire-reports/*.xml', allowEmptyResults: true
+
+                recordCoverage(
+                    tools: [[parser: 'JACOCO', pattern: 'pdf-umbenenner-coverage/target/site/jacoco-aggregate/jacoco.xml']],
+                    enabledForFailure: true
+                )
+
+                publishHTML(target: [
+                    reportName: 'JaCoCo HTML Report',
+                    reportDir: 'pdf-umbenenner-coverage/target/site/jacoco-aggregate',
+                    reportFiles: 'index.html',
+                    keepAll: true,
+                    alwaysLinkToLastBuild: true,
+                    allowMissing: true
+                ])
+            }
+        } // stage: Berichte veröffentlichen
+
+        stage('Aufräumen') {
+            steps {
+                sh '''#!/usr/bin/env bash
+set -euo pipefail
+rm -f pdf-ki-renamer-*.jar
+echo "Aufräumen abgeschlossen."
+'''
+            }
+        } // stage: Aufräumen
+
+    } // stages
+
+    post {
+        success {
+            echo "Build ${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}.${env.BUILD_NUMBER} erfolgreich abgeschlossen."
+        }
+        failure {
+            echo "Build ${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}.${env.BUILD_NUMBER} fehlgeschlagen."
+        }
+        always {
+            deleteDir()
+        }
+    }
+
+} // pipeline
@@ -0,0 +1,232 @@
+# PDF-Umbenenner
+
+Ein lokal gestartetes Java-Programm zur KI-gestützten Umbenennung bereits OCR-verarbeiteter, durchsuchbarer PDF-Dateien.
+
+Die Anwendung liest PDF-Dateien aus einem konfigurierbaren Quellordner, extrahiert den Text, ermittelt daraus per KI einen normierten Dateinamen und legt **eine Kopie** im Zielordner ab. Die Quelldateien bleiben unverändert.
+
+> **V2.9:** Die Anwendung enthält eine lokale JavaFX-Desktop-GUI als Standardstart.
+> Die GUI dient der Konfiguration, Validierung, technischen Diagnose und der Ausführung von Verarbeitungsläufen.
+> Der Tab „Verarbeitungslauf" enthält eine integrierte PDF-Vorschau und einen editierbaren Dateiname-Bereich.
+> Die GUI startet maximiert und lädt beim Start automatisch die zuletzt verwendete Konfigurationsdatei.
+> Der headless Batch-Betrieb bleibt über `--headless` vollständig erhalten.
+> Details zum Betrieb: [`docs/betrieb.md`](docs/betrieb.md)
+
+## Zielbild
+
+Der PDF-Umbenenner ist als schlanke, lokal gestartete Anwendung ausgelegt:
+
+- **Java 21**
+- **Maven Multi-Module**
+- **ausführbares Standalone-JAR** (ein gemeinsames JAR für GUI und headless)
+- **GUI-Standardstart** ab V2.0 (JavaFX-Desktop, offiziell Windows)
+- **headless Betrieb** über `--headless`, z. B. für den **Windows Task Scheduler**
+- **`--config <pfad>`** für GUI und headless
+- **kein Webserver**
+- **kein Applikationsserver**
+- **keine Dauerlauf-Anwendung**
+- **kein interner Scheduler**
+- **SQLite** als lokaler Persistenzspeicher
+- **Log4j2** für Logging
+- strikte **hexagonale Architektur / Ports and Adapters**
+
+## Fachlicher Überblick
+
+Die Anwendung verarbeitet Dokumente in einem robusten, nachvollziehbaren Ablauf:
+
+1. Quellordner lesen
+2. PDF-Kandidaten erkennen
+3. Fingerprint der Quelldatei bestimmen
+4. bereits erfolgreich verarbeitete bzw. final fehlgeschlagene Dokumente überspringen
+5. PDF-Text extrahieren
+6. KI-basierten Benennungsvorschlag erzeugen
+7. normierten Zieldateinamen bilden
+8. Kollisionen im Zielordner über Dubletten-Suffixe auflösen
+9. Kopie im Zielordner ablegen
+10. Ergebnis und Versuchshistorie in SQLite persistieren
+
+## Dateinamensregeln
+
+Das Zielformat lautet:
+
+```text
+YYYY-MM-DD - Titel.pdf
+```
+
+Bei Namenskollisionen werden Suffixe direkt vor `.pdf` ergänzt:
+
+```text
+YYYY-MM-DD - Titel(1).pdf
+YYYY-MM-DD - Titel(2).pdf
+```
+
+Wichtige Regeln:
+
+- die **konfigurierte maximale Titellänge** bezieht sich nur auf den **Basistitel**
+- das Dubletten-Suffix zählt **nicht** zur konfigurierten Titellänge
+- Titel werden auf **Deutsch** erzeugt
+- Eigennamen bleiben unverändert
+- Quelldateien werden **nie** überschrieben, verschoben oder verändert
+
+## KI-Anbindung
+
+Die KI-Anbindung ist konfigurationsgetrieben. Der fachliche Vertrag bleibt unabhängig vom Anbieter gleich: Aus dem Dokumentinhalt wird ein strukturierter Benennungsvorschlag abgeleitet, aus dem die Anwendung den finalen Dateinamen bildet.
+
+Der aktuelle Stand unterstützt mehrere Provider über Konfiguration, darunter:
+
+- **OpenAI-kompatible Endpunkte**
+- **Claude API**
+
+Die Provider-Auswahl ist **Konfiguration**, keine Architekturentscheidung.
+
+## Wichtige Annahmen und Grenzen
+
+- Die Anwendung erwartet **bereits OCR-verarbeitete, durchsuchbare PDFs**.
+- Nicht durchsuchbare oder inhaltlich nicht brauchbare PDFs werden als Fehler behandelt.
+- Mehrdeutige Dokumente erzeugen **kein unsicheres Ergebnis**.
+- Erfolgreich verarbeitete Dateien werden in späteren Läufen nicht erneut verarbeitet.
+- Final fehlgeschlagene Dateien werden in späteren Läufen übersprungen.
+
+## Architektur
+
+Das Projekt ist strikt nach **Ports and Adapters / Hexagonal Architecture** aufgebaut.
+
+### Module
+
+- `pdf-umbenenner-domain`
+- `pdf-umbenenner-application`
+- `pdf-umbenenner-adapter-in-cli`
+- `pdf-umbenenner-adapter-in-gui`
+- `pdf-umbenenner-adapter-out`
+- `pdf-umbenenner-bootstrap`
+
+### Grundprinzipien
+
+- Abhängigkeiten zeigen immer **nach innen**
+- Domain kennt **keine Infrastruktur**
+- externe Zugriffe erfolgen ausschließlich über **Ports**
+- technische Implementierungen liegen in **Adaptern**
+- keine direkte Adapter-zu-Adapter-Kopplung
+
+## Konfiguration
+
+Die Anwendung wird über eine `.properties`-Datei konfiguriert.
+
+Typische Bereiche sind:
+
+- Quellordner
+- Zielordner
+- SQLite-Datei
+- KI-Provider und Modell
+- Timeout
+- Seitenlimit
+- Textlimit für KI-Aufrufe
+- maximale Titellänge (`max.title.length`, Default 60, Bereich 10..120)
+- Prompt-Datei
+- Logging
+
+Für einen lokalen Einstieg dient die Beispielkonfiguration unter:
+
+```text
+config/application-local.example.properties
+```
+
+## Build
+
+Projektweit:
+
+```bash
+./mvnw clean verify
+```
+
+Unter Windows:
+
+```powershell
+.\mvnw.cmd clean verify
+```
+
+## Start
+
+Das ausführbare Artefakt wird im Bootstrap-Modul erzeugt.
+
+**GUI-Standardstart** (öffnet die JavaFX-Desktop-Oberfläche):
+
+```bash
+java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar
+```
+
+**headless Betrieb** (Batch-/Scheduler-Start ohne GUI):
+
+```bash
+java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --headless
+```
+
+**Explizite Konfigurationsdatei** (für GUI und headless):
+
+```bash
+java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --config C:\Pfad\zur\config.properties
+java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --headless --config C:\Pfad\zur\config.properties
+```
+
+Das JAR ist das einzige Distributionsartefakt und enthält JavaFX für den GUI-Start bereits
+integriert. Ausführliche Build-, Packaging- und Starthinweise sowie Informationen zur JavaFX-
+Integration und zum headless Betrieb befinden sich in [`docs/betrieb.md`](docs/betrieb.md).
+
+## Logging, Status und Nachvollziehbarkeit
+
+Der PDF-Umbenenner ist auf Nachvollziehbarkeit und Wiederholbarkeit ausgelegt:
+
+- persistente Dokumenthistorie in **SQLite**
+- Status- und Retry-Semantik für robuste Batch-Läufe
+- Idempotenz über inhaltsbasierten Fingerprint
+- Logging über **Log4j2**
+- Schutz sensibler KI-Inhalte im Log
+
+## Dokumentation im Repository
+
+Die maßgeblichen Dokumente sind:
+
+- `CLAUDE.md`
+- `docs/specs/technik-und-architektur.md`
+- `docs/specs/fachliche-anforderungen.md`
+- `docs/specs/meilensteine-v2_0.md`
+- `docs/betrieb.md`
+- `docs/gui-bedienanleitung.md`
+- `docs/freigabe-v2_0.md`
+- `docs/workpackages/...`
+
+Empfohlene Leserichtung:
+
+1. `CLAUDE.md`
+2. technische Zielarchitektur
+3. fachliche Anforderungen
+4. Meilensteine
+5. `docs/betrieb.md` für Betriebs- und Startdetails
+6. `docs/gui-bedienanleitung.md` für die GUI-Bedienung
+7. aktives Arbeitspaket
+
+## Entwicklungsleitplanken
+
+- kleine, fokussierte Änderungen
+- keine stillen Annahmen bei Dokumentkonflikten
+- keine unnötigen Refactorings
+- Architekturtreue hat Vorrang
+- keine Meilenstein- oder Arbeitspaket-Bezeichner in Produktionscode, Kommentaren oder JavaDoc
+
+## Status des Projekts
+
+Das Repository verfolgt einen inkrementellen, meilensteinbasierten Ausbau. Der aktuelle Produktstand baut auf einem vollständig implementierten Kern für:
+
+- Konfiguration und Startvalidierung
+- Quellordner-Scan und PDF-Textauslese
+- Fingerprint, SQLite-Persistenz und Idempotenz
+- KI-Integration für Benennungsvorschläge (OpenAI-kompatibel und Anthropic Claude)
+- Dateinamensbildung und Zielkopie
+- Retry-Logik, Logging und betriebliche Robustheit
+- JavaFX-Desktop-GUI als Standardstart (Konfigurationseditor, Validierung, technische Tests)
+- Tab „Verarbeitungslauf" mit integrierter PDF-Vorschau pro Zeile und editierbarem Dateiname-Bereich
+- Atomare Dateisystem- und Datenbankoperationen für manuelle Umbenennungen mit Konfliktauflösung
+- headless Batch-Betrieb über `--headless` (rückwärtskompatibel zu V1.x)
+
+## Lizenz / Nutzung
+
+Falls für dieses Repository eine konkrete Lizenz vorgesehen ist, sollte sie hier ergänzt werden.
@@ -1,21 +1,92 @@
-# PDF Umbenenner Local Configuration Example
-# AP-005: Copy this file to config/application.properties and adjust values for local development
+# PDF Umbenenner – Konfigurationsbeispiel fuer lokale Entwicklung
+# Kopiere diese Datei nach config/application.properties und passe die Werte an.

-# Mandatory M1 properties
+# ---------------------------------------------------------------------------
+# Pflichtparameter (allgemein)
+# ---------------------------------------------------------------------------
+
+# Quellordner: Ordner, aus dem OCR-verarbeitete PDF-Dateien gelesen werden.
+# Der Ordner muss vorhanden und lesbar sein.
 source.folder=./work/local/source
-target.folder=./work/local/target
-sqlite.file=./work/local/pdf-umbenenner.db
-api.baseUrl=http://localhost:8080/api
-api.model=gpt-4o-mini
-api.timeoutSeconds=30
-max.retries.transient=3
-max.pages=10
-max.text.characters=5000
-prompt.template.file=./config/prompts/local-template.txt

-# Optional properties
-runtime.lock.file=./work/local/lock.pid
+# Zielordner: Ordner, in den die umbenannten Kopien abgelegt werden.
+# Wird automatisch angelegt, wenn er noch nicht existiert.
+target.folder=./work/local/target
+
+# SQLite-Datenbankdatei fuer Bearbeitungsstatus und Versuchshistorie.
+# Das uebergeordnete Verzeichnis muss vorhanden sein.
+sqlite.file=./work/local/pdf-umbenenner.db
+
+# Maximale Anzahl historisierter transienter Fehlversuche pro Dokument.
+# Muss eine ganze Zahl >= 1 sein.
+max.retries.transient=3
+
+# Maximale Seitenzahl pro Dokument. Dokumente mit mehr Seiten werden als
+# deterministischer Inhaltsfehler behandelt (kein KI-Aufruf).
+max.pages=10
+
+# Maximale Zeichenanzahl des Dokumenttexts, der an die KI gesendet wird.
+max.text.characters=1000
+
+# Maximale Länge des Basistitels in Zeichen (10..120). Default 60.
+max.title.length=60
+
+# Pfad zur externen Prompt-Datei. Der Dateiname dient als Prompt-Identifikator
+# in der Versuchshistorie.
+prompt.template.file=./config/prompts/template.txt
+
+# ---------------------------------------------------------------------------
+# Optionale Parameter
+# ---------------------------------------------------------------------------
+
+# Pfad zur Lock-Datei fuer den Startschutz (verhindert parallele Instanzen).
+runtime.lock.file=./work/local/pdf-umbenenner.lock
+
+# Log-Verzeichnis. Wird weggelassen, schreibt Log4j2 in ./logs/.
 log.directory=./work/local/logs
+
+# Log-Level (DEBUG, INFO, WARN, ERROR). Standard ist INFO.
 log.level=INFO
-# api.key can also be set via environment variable PDF_UMBENENNER_API_KEY
-api.key=your-local-api-key-here
+
+# Sensible KI-Inhalte (vollstaendige Rohantwort und Reasoning) ins Log schreiben.
+# Erlaubte Werte: true oder false. Standard ist false (geschuetzt).
+log.ai.sensitive=false
+
+# ---------------------------------------------------------------------------
+# Aktiver KI-Provider
+# ---------------------------------------------------------------------------
+# Erlaubte Werte: openai-compatible, claude
+ai.provider.active=openai-compatible
+
+# ---------------------------------------------------------------------------
+# OpenAI-kompatibler Provider
+# ---------------------------------------------------------------------------
+# Basis-URL des KI-Dienstes (ohne Pfadsuffix wie /chat/completions).
+ai.provider.openai-compatible.baseUrl=https://api.openai.com/v1
+
+# Modellname des KI-Dienstes.
+ai.provider.openai-compatible.model=gpt-4o-mini
+
+# HTTP-Timeout fuer KI-Anfragen in Sekunden (muss > 0 sein).
+ai.provider.openai-compatible.timeoutSeconds=30
+
+# API-Schluessel.
+# Vorrangreihenfolge: OPENAI_COMPATIBLE_API_KEY (Umgebungsvariable) >
+#                    PDF_UMBENENNER_API_KEY (veraltete Umgebungsvariable, weiterhin akzeptiert) >
+#                    ai.provider.openai-compatible.apiKey (dieser Wert)
+ai.provider.openai-compatible.apiKey=your-openai-api-key-here
+
+# ---------------------------------------------------------------------------
+# Anthropic Claude-Provider (nur benoetigt wenn ai.provider.active=claude)
+# ---------------------------------------------------------------------------
+# Basis-URL (optional; Standard: https://api.anthropic.com)
+# ai.provider.claude.baseUrl=https://api.anthropic.com
+
+# Modellname (z. B. claude-3-5-sonnet-20241022)
+# ai.provider.claude.model=claude-3-5-sonnet-20241022
+
+# HTTP-Timeout fuer KI-Anfragen in Sekunden (muss > 0 sein).
+# ai.provider.claude.timeoutSeconds=60
+
+# API-Schluessel. Die Umgebungsvariable ANTHROPIC_API_KEY hat Vorrang.
+# ai.provider.claude.apiKey=
@@ -1,21 +1,48 @@
-# PDF Umbenenner Test Configuration Example
-# AP-005: Copy this file to config/application.properties and adjust values for testing
+# PDF Umbenenner – Konfigurationsbeispiel fuer Testlaeufe
+# Kopiere diese Datei nach config/application.properties und passe die Werte an.
+# Diese Vorlage enthaelt kuerzere Timeouts und niedrigere Limits fuer Testlaeufe.
+
+# ---------------------------------------------------------------------------
+# Pflichtparameter (allgemein)
+# ---------------------------------------------------------------------------

-# Mandatory M1 properties
 source.folder=./work/test/source
 target.folder=./work/test/target
 sqlite.file=./work/test/pdf-umbenenner-test.db
-api.baseUrl=http://localhost:8081/api
-api.model=gpt-4o-mini-test
-api.timeoutSeconds=10
+
 max.retries.transient=1
 max.pages=5
 max.text.characters=2000
-prompt.template.file=./config/prompts/test-template.txt
+# Maximale Länge des Basistitels in Zeichen (10..120). Default 60.
+max.title.length=60
+prompt.template.file=./config/prompts/template.txt

-# Optional properties
-runtime.lock.file=./work/test/lock.pid
+# ---------------------------------------------------------------------------
+# Optionale Parameter
+# ---------------------------------------------------------------------------
+
+runtime.lock.file=./work/test/pdf-umbenenner.lock
 log.directory=./work/test/logs
 log.level=DEBUG
-# api.key can also be set via environment variable PDF_UMBENENNER_API_KEY
-api.key=test-api-key-placeholder
+log.ai.sensitive=false
+
+# ---------------------------------------------------------------------------
+# Aktiver KI-Provider
+# ---------------------------------------------------------------------------
+ai.provider.active=openai-compatible
+
+# ---------------------------------------------------------------------------
+# OpenAI-kompatibler Provider
+# ---------------------------------------------------------------------------
+ai.provider.openai-compatible.baseUrl=https://api.openai.com/v1
+ai.provider.openai-compatible.model=gpt-4o-mini
+ai.provider.openai-compatible.timeoutSeconds=10
+ai.provider.openai-compatible.apiKey=test-api-key-placeholder
+
+# ---------------------------------------------------------------------------
+# Anthropic Claude-Provider (nur benoetigt wenn ai.provider.active=claude)
+# ---------------------------------------------------------------------------
+# ai.provider.claude.baseUrl=https://api.anthropic.com
+# ai.provider.claude.model=claude-3-5-sonnet-20241022
+# ai.provider.claude.timeoutSeconds=60
+# ai.provider.claude.apiKey=your-anthropic-api-key-here
@@ -1 +1,52 @@
-This is a test prompt template for AP-006 validation.
+Du bist ein Assistent zur automatischen Benennung gescannter PDF-Dokumente.
+
+Analysiere den folgenden Dokumenttext und ermittle:
+
+1. Einen inhaltlich passenden deutschen Titel nach dem Schema: {Absender} {Betreff_gekürzt}
+2. Das relevanteste Datum des Dokuments
+
+Titelschema – verbindlich:
+- Erster Teil: Absender (Person, Firma, Behörde, Institution) – so wie im Dokument genannt, Abkürzungen wie GmbH, AG, KfW, Kfz sind erlaubt
+- Zweiter Teil: Betreff oder Kernaussage des Dokuments, so kurz wie möglich – bevorzugt aus einer vorhandenen Betreffzeile, sonst aus dem Dokumentinhalt abgeleitet
+- Beide Teile durch ein Leerzeichen getrennt, kein Sonderzeichen außer Bindestrich und Leerzeichen
+- **Maximal {MAX_TITLE_LENGTH} Zeichen gesamt – diese Grenze ist nicht verhandelbar und MUSS eingehalten werden**
+- Keine generischen Begriffe wie "Dokument", "Datei", "Scan", "PDF", "Schreiben", "Brief"
+- Titel auf Deutsch formulieren
+
+WICHTIG – Längenbegrenzung ist deine Verantwortung:
+Wenn ein idealer Titel länger als {MAX_TITLE_LENGTH} Zeichen wäre, darfst und musst du ihn selbst kürzen. Optionen:
+- Betreff verkürzen (z.B. "Steuerbescheid 2024" statt "Einkommensteuerbescheid 2024")
+- Unwesentliche Details weglassen
+- Absender mit Standard-Abkürzung darstellen
+- Absender weglassen und nur Betreff nutzen, falls sinnvoll
+Liefere IMMER einen Titel, der das Zeichenlimit einhält. Niemals einen, der es überschreitet.
+
+Beispiele für gute Titel:
+- Stadtwerke Bochum Grundbesitzabgaben 2025
+- Allianz Versicherung Kfz-Nachtrag Polo
+- Finanzamt Bochum Steuerbescheid 2024
+- KfW Förderbescheid Energieeffizienz
+
+Beispiele für Kürzung bei Längenlimit:
+- zu lang: "Versicherungsgesellschaft Allianz Versicherung AG Kfz-Versicherungsnachtrag Volkswagen Polo" → gekürzt: "Allianz Kfz-Nachtrag Polo"
+- zu lang: "Bundesfinanzbehörde Finanzamt Bochum Bescheid zur Einkommensteuer Veranlagung" → gekürzt: "Finanzamt Bochum Steuerbescheid"
+
+Datumsermittlung nach Priorität:
+- Rechnungsdatum
+- Dokumentdatum
+- Ausstellungsdatum oder Bescheiddatum
+- Schreibdatum oder Ende eines Leistungszeitraums
+- Kein Datum angeben, wenn kein belastbares Datum eindeutig ableitbar ist
+
+Wenn das Dokument nicht eindeutig interpretierbar ist, beschreibe dies im Reasoning.
+
+**Ausgabeformat: Ausschließlich reines JSON-Objekt**
+
+Antworte nur mit einem JSON-Objekt nach folgendem Schema:
+- Keine Präambel, keine Erklärungen, keine Markdown-Codeblöcke
+- `title` (erforderlich): Der ermittelte deutsche Titel nach obigem Schema
+- `reasoning` (erforderlich): Absender und Betreff in je einem Satz begründen
+- `date` (optional): Das ermittelte Datum im Format YYYY-MM-DD; auslassen, falls kein belastbares Datum ableitbar ist
+
+Beispiel:
+{"title":"Stadtwerke Bochum Grundbesitzabgaben 2025","reasoning":"Absender ist Stadtwerke Bochum laut Briefkopf. Betreff ist die Jahresabrechnung der Grundbesitzabgaben 2025.","date":"2025-03-15"}
@@ -0,0 +1,356 @@
+# Architektur-Übersicht: Adapter-Out, CLI & Bootstrap
+
+Diese Datei beschreibt die drei Module `pdf-umbenenner-adapter-out`, `pdf-umbenenner-adapter-in-cli`
+und `pdf-umbenenner-bootstrap`: ihren Zweck, ihre Paketstruktur, die wichtigsten Klassen und die
+Verdrahtungslogik beim Programmstart. Sie richtet sich an Entwickler, die in einem dieser Module
+arbeiten wollen und noch keinen Überblick über das Projekt haben. Domain- und Application-Schicht
+(Port-Verträge, fachliche Domänenobjekte, Use-Case-Interfaces) sind nicht Gegenstand dieses
+Dokuments – sie sind in `docs/architecture/domain-overview.md` beschrieben. GUI-interne Ports und
+die Struktur des GUI-Adapters finden sich in `docs/architecture/gui-overview.md`. Die hexagonale
+Abhängigkeitsrichtung ist strikt: Adapter kennen Domain und Application, nicht umgekehrt. Adapter
+dürfen außerdem nicht direkt voneinander abhängen.
+
+---
+
+## 1. Modulzweck
+
+### pdf-umbenenner-adapter-out
+
+Enthält alle Outbound-Adapter-Implementierungen, also die konkreten technischen Lösungen für
+sämtliche Outbound-Ports der Application. Dazu gehören: Dateisystemzugriff, PDF-Textextraktion
+via PDFBox, SQLite-Persistenz (Schema, Repositories, Unit of Work), HTTP-Clients für zwei
+KI-Provider-Familien (OpenAI-kompatibel und Anthropic nativ), Properties-Konfiguration inklusive
+Legacy-Migration, dateibasierter Run-Lock sowie Systemuhr und SHA-256-Fingerprint.
+
+### pdf-umbenenner-adapter-in-cli
+
+Schlanker Inbound-Adapter für den kopflosen Batch-Betrieb. Enthält genau eine Klasse
+(`SchedulerBatchCommand`), die den CLI-Einstiegspunkt bildet und ausschließlich über das
+Inbound-Port-Interface an die Application delegiert. Keine eigene Fachlogik.
+
+### pdf-umbenenner-bootstrap
+
+Composition Root der Anwendung. Verantwortlich für: CLI-Argument-Parsing,
+Konfigurationsauflösung und -validierung, Aufbau des vollständigen Objektgraphen (manuell, ohne
+DI-Framework), Auswahl der aktiven KI-Adapter-Implementierung, Dispatch auf GUI- oder
+Headless-Pfad sowie Exit-Code-Ableitung. Bootstrap ist die einzige Stelle, an der alle Module
+zusammengeführt werden.
+
+---
+
+## 2. Paketstruktur
+
+### pdf-umbenenner-adapter-out
+
+Wurzelpaket: `de.gecheckt.pdf.umbenenner.adapter.out`
+
+| Unterpaket              | Inhalt                                                                              |
+|-------------------------|-------------------------------------------------------------------------------------|
+| `.ai`                   | HTTP-Adapter für OpenAI-kompatible Schnittstelle und Anthropic Messages API         |
+| `.clock`                | Systemuhr-Adapter (`Instant.now()`)                                                 |
+| `.configuration`        | Properties-Laden, Multi-Provider-Parsing/-Validierung, Legacy-Migration             |
+| `.fingerprint`          | SHA-256-Inhalts-Fingerprint                                                         |
+| `.lock`                 | Dateibasierter Run-Lock                                                             |
+| `.modelcatalog`         | HTTP-Modellabruf für den GUI-Konfigurationseditor                                   |
+| `.pathcheck`            | Pfadprüfung für den GUI-Editor                                                      |
+| `.pdfextraction`        | PDFBox-3.x-Adapter: Textextraktion und Seitenanzahl                                 |
+| `.prompt`               | Prompt-Template-Lader                                                               |
+| `.resourcecreation`     | Anlegen von Ordnern und Dateien (korrigierende technische Tests)                    |
+| `.sourcedocument`       | Quellordner-Scanner (nicht rekursiv)                                                |
+| `.sqlite`               | Schema-Initialisierung, Repositories, Unit of Work                                 |
+| `.targetcopy`           | Zielkopie via Temp-Datei und atomarem Move                                          |
+| `.targetfolder`         | Kollisionsfreier Zieldateiname, Umbenennung bestehender Zieldateien                 |
+| `.validation`           | API-Key-Auflösung aus Umgebungsvariablen (GUI-Editor)                               |
+| `.bootstrap.validation` | `StartConfiguration`-Validierung vor Prozessstart                                   |
+
+### pdf-umbenenner-adapter-in-cli
+
+Wurzelpaket: `de.gecheckt.pdf.umbenenner.adapter.in.cli`
+
+Enthält ausschließlich `SchedulerBatchCommand` sowie die zugehörige `package-info.java`.
+
+### pdf-umbenenner-bootstrap
+
+Wurzelpaket: `de.gecheckt.pdf.umbenenner.bootstrap`
+
+| Unterpaket          | Inhalt                                                                                                |
+|---------------------|-------------------------------------------------------------------------------------------------------|
+| *(Wurzel)*          | `PdfUmbenennerApplication` (main), `BootstrapRunner`, `AiProviderSelector`                           |
+| `.adapter`          | Bootstrap-interne Adapter: `Log4jProcessingLogger`, `GuiConfigurationPropertiesWriter`, `AiModelCatalogDispatcher` |
+| `.singleinstance`   | `SingleInstanceGuard` – Einzelinstanz-Schutz via Loopback-ServerSocket                               |
+| `.startup`          | `StartupMode`, `StartupArguments`, `CliArgumentParser`                                                |
+
+---
+
+## 3. Schlüsselklassen
+
+Die folgenden Klassen sind für das Verständnis der drei Module zentral. FQN-Kürzel: `...` steht
+jeweils für das Wurzelpaket des Moduls.
+
+### Adapter-Out
+
+#### KI-Adapter
+
+- **`...ai.OpenAiHttpAdapter`** – implementiert `AiInvocationPort` für OpenAI-kompatible Endpunkte.
+  POST `{baseUrl}/v1/chat/completions`, Bearer-Authentifizierung, extrahiert
+  `choices[0].message.content`, klassifiziert HTTP-Fehler und Timeouts als
+  `AiInvocationTechnicalFailure`.
+
+- **`...ai.AnthropicClaudeHttpAdapter`** – implementiert `AiInvocationPort` für die native
+  Anthropic Messages API. POST `/v1/messages`, Header `x-api-key` und `anthropic-version`,
+  konkateniert `text`-Content-Blöcke aus dem Antwort-Array.
+
+Beide Adapter liefern denselben Domain-Typ (`NamingProposal`) und enthalten keinerlei
+provider-spezifische Typen in öffentlichen Signaturen. Welche Implementierung aktiv ist, entscheidet
+ausschließlich der Bootstrap (→ `AiProviderSelector`).
+
+#### Modell-Katalog (GUI)
+
+- **`...modelcatalog.ClaudeModelCatalogAdapter`** – `AiModelCatalogPort` für Claude,
+  GET `/v1/models` mit `x-api-key`.
+
+- **`...modelcatalog.OpenAiCompatibleModelCatalogAdapter`** – `AiModelCatalogPort` für
+  OpenAI-kompatibel, GET `/v1/models` mit Bearer.
+
+#### PDF-Extraktion
+
+- **`...pdfextraction.PdfTextExtractionPortAdapter`** – PDFBox-3.x-Adapter. Alle technischen
+  Fehler werden als `PdfExtractionTechnicalError` zurückgegeben; es werden keine Exceptions
+  propagiert.
+
+#### SQLite
+
+- **`...sqlite.SqliteSchemaInitializationAdapter`** – Flyway-basierte Schema-Initialisierung
+  mit `V1__initial_schema.sql`. Drei-Fall-Strategie: leere Datenbank (Flyway führt das Skript
+  vollständig aus), bestehender Datenbestand ohne Flyway-History (Schema-Prüfung, datiertes
+  Backup, dann Baseline-Eintrag ohne Skriptausführung), regulärer Folgestart mit Flyway-History
+  (idempotenter Lauf). Foreign-Key-Durchsetzung via `SQLiteConfig.enforceForeignKeys(true)` auf
+  DataSource-Ebene, sodass jede neue Verbindung automatisch `PRAGMA foreign_keys = ON` erhält.
+
+- **`...sqlite.SqliteUnitOfWorkAdapter`** – implementiert `UnitOfWorkPort`. Setzt
+  `autoCommit=false`, führt atomare Commits durch, rollt bei Fehlern zurück. Die innere
+  `TransactionOperations`-Implementierung wurde um `resetDocumentStatusForRetry(DocumentFingerprint)`
+  erweitert: setzt feldgenau `overall_status = 'READY_FOR_AI'`, `content_error_count = 0`,
+  `transient_error_count = 0`, `last_failure_instant = NULL`; alle anderen Felder und alle
+  `processing_attempt`-Einträge bleiben unangetastet.
+
+- **`...sqlite.SqliteDocumentRecordRepositoryAdapter`** – Stammsatz pro SHA-256-Fingerprint
+  (Gesamtstatus, Fehlerzähler, Zieldateiname usw.).
+
+- **`...sqlite.SqliteProcessingAttemptRepositoryAdapter`** – Versuchshistorie, referenziert
+  über Fingerprint. Enthält u. a. Provider-Identifikator, Modellname, Prompt-Identifikator,
+  KI-Rohantwort und finalen Zieldateinamen.
+
+- **`...sqlite.SqliteHistoryQueryAdapter`** – implementiert `HistoryQueryPort`. Kapselt alle
+  lesenden Datenbankoperationen für den Historien-Tab: Übersicht (`loadOverview` mit
+  Sortierung `updated_at DESC, fingerprint ASC`, LIMIT 501-Strategie, case-insensitive
+  Freitextsuche via `LOWER()` mit Sonderzeichen-Escape für `%` und `_`), Stammsatz-Lookup
+  (`findRecordByFingerprint`) und Versuchshistorie (`findAttemptsByFingerprint`).
+
+#### Konfiguration
+
+- **`...configuration.PropertiesConfigurationPortAdapter`** – implementiert `ConfigurationPort`.
+  Lädt `config/application.properties` (oder einen `--config`-Override), parst via
+  `MultiProviderConfigurationParser`, löst API-Keys aus Umgebungsvariablen
+  (`OPENAI_COMPATIBLE_API_KEY`, `ANTHROPIC_API_KEY`).
+
+- **`...configuration.LegacyConfigurationMigrator`** – erkennt alte Flat-Key-Konfigurationen
+  (Schlüssel wie `api.baseUrl`, `api.model`), legt eine `.bak`-Sicherung an und überführt den
+  Inhalt in das aktuelle Multi-Provider-Schema.
+
+#### Prompt-Adapter
+
+- **`...prompt.FilesystemPromptPortAdapter`** – implementiert `PromptPort`. Lädt das
+  Prompt-Template aus einer externen Datei und leitet den Identifikator aus dem Dateinamen ab.
+  Die neue Methode `savePrompt(String content)` schreibt den Inhalt atomar: temporäre Datei
+  im selben Verzeichnis anlegen (gleiche Partition), Inhalt in UTF-8 schreiben, dann
+  `ATOMIC_MOVE` zur Zieldatei. Kein stiller Fallback bei `AtomicMoveNotSupportedException`.
+  Der Pfad stammt aus der Adapter-internen Konfiguration, nicht aus dem Port-Aufruf.
+
+#### Laufzeitinfrastruktur
+
+- **`...lock.FilesystemRunLockPortAdapter`** – Lock-Datei mit PID-Inhalt. Wirft
+  `RunLockUnavailableException`, wenn die Datei bereits vorhanden ist. Release löscht die Datei
+  (best-effort).
+
+- **`...clock.SystemClockAdapter`** – delegiert an `Instant.now()`.
+
+- **`...fingerprint.Sha256FingerprintAdapter`** – SHA-256 über den Rohdatei-Inhalt. Fehler als
+  `FingerprintTechnicalError`.
+
+#### Zieldatei
+
+- **`...targetcopy.FilesystemTargetFileCopyAdapter`** – kopiert die Quelldatei zunächst in eine
+  `.tmp`-Datei, dann atomarer Move (Fallback: Standard-Move). Die Quelldatei wird in keinem Fall
+  verändert.
+
+- **`...targetfolder.FilesystemTargetFolderAdapter`** – ermittelt einen kollisionsfreien
+  Zieldateinamen mit `(1)`, `(2)`-Suffix. Erkennt inhaltsidentische Duplikate via SHA-256.
+
+#### Validierung vor Prozessstart
+
+- **`...bootstrap.validation.StartConfigurationValidator`** – validiert die geladene
+  `StartConfiguration` auf Pflichtfelder, Wertebereiche, URI-Syntax und Pfadbedingungen.
+  Wird im Bootstrap-Headless-Pfad unmittelbar nach dem Laden der Konfiguration aufgerufen.
+
+---
+
+### Adapter-In-CLI
+
+- **`...adapter.in.cli.SchedulerBatchCommand`** – einziger Inbound-Adapter für den Headless-Betrieb.
+  Nimmt einen `BatchRunContext` entgegen, delegiert an `BatchRunProcessingUseCase.execute()` und
+  gibt `BatchRunOutcome` zurück. Enthält keine eigene Fachlogik; die Verdrahtung mit dem
+  Use-Case-Interface erfolgt ausschließlich im Bootstrap.
+
+---
+
+### Bootstrap
+
+- **`...bootstrap.PdfUmbenennerApplication`** – `main`-Methode. Parst CLI-Argumente via
+  `CliArgumentParser`, bricht bei ungültiger Verwendung mit Exit-Code 1 ab, delegiert an
+  `BootstrapRunner.run()` und ruft abschließend `System.exit()` mit dem zurückgegebenen Code auf.
+
+- **`...bootstrap.BootstrapRunner`** – Herzstück der Verdrahtung. Baut den Objektgraph für
+  Headless- und GUI-Pfad, dispatcht über `StartupMode`, enthält `buildProductionBatchUseCase()`
+  und `runHeadlessBatch()` als zentrale Kompositionsmethoden, liefert den Exit-Code zurück.
+
+- **`...bootstrap.AiProviderSelector`** – einzige Stelle, an der `AiProviderFamily` auf eine
+  konkrete `AiInvocationPort`-Implementierung abgebildet wird:
+  `OPENAI_COMPATIBLE` → `OpenAiHttpAdapter`, `CLAUDE` → `AnthropicClaudeHttpAdapter`.
+
+- **`...bootstrap.startup.CliArgumentParser`** – parst `--headless` und `--config <Pfad>` zu einem
+  typsicheren `StartupArgumentsParseResult` (sealed: `Valid` / `Invalid`).
+
+- **`...bootstrap.singleinstance.SingleInstanceGuard`** – bindet einen Loopback-ServerSocket auf
+  Port 47832. Wirft `AnotherInstanceRunningException`, wenn der Port bereits belegt ist. Ein
+  Shutdown-Hook gibt den Socket frei.
+
+- **`...bootstrap.adapter.AiModelCatalogDispatcher`** – Bootstrap-interner Dispatcher für die GUI.
+  Routet `AiModelCatalogPort`-Aufrufe anhand des `providerIdentifier` an den Claude- oder
+  OpenAI-kompatiblen Modell-Katalog-Adapter. Thread-safe.
+
+- **`...bootstrap.ApplicationVersionProvider`** – statische Hilfsklasse ohne Zustand. Liest
+  `Implementation-Version` aus dem Paket-Manifest via `getClass().getPackage().getImplementationVersion()`.
+  Fallback `"dev"` bei IDE-Start und ungepacktem Betrieb (kein Manifest-Eintrag vorhanden).
+  Der aufgelöste Wert wird im GUI-Pfad in `GuiStartupContext.applicationVersion` eingesetzt.
+
+- **`...bootstrap.adapter.Log4jProcessingLogger`** – implementiert `ProcessingLogger` auf Basis
+  von Log4j2. Unterdrückt sensitive KI-Inhalte, wenn `AiContentSensitivity.PROTECT_SENSITIVE_CONTENT`
+  gesetzt ist.
+
+- **`...bootstrap.adapter.GuiConfigurationPropertiesWriter`** – schreibt die im GUI-Editor
+  bearbeitete Konfiguration als normalisierte `application.properties` zurück auf das Dateisystem.
+
+---
+
+## 4. Verdrahtungslogik in Bootstrap
+
+Die folgende Sequenz beschreibt den Ablauf von `main()` bis zum Start des eigentlichen Adapters.
+Der Objektgraph wird ausschließlich durch manuelle `new`-Aufrufe aufgebaut; es wird kein
+DI-Framework verwendet.
+
+**Argument-Parsing**
+- `PdfUmbenennerApplication.main()` → `CliArgumentParser.parse(args)`
+- Ergebnis `Invalid` → Exit-Code 1, keine weiteren Schritte
+
+**Einzelinstanz-Schutz**
+- `BootstrapRunner.run()` → `SingleInstanceGuard.acquire()`
+- `AnotherInstanceRunningException` → Exit-Code 1; im GUI-Modus zusätzlich ein Swing-Warndialog
+
+**Modus-Dispatch**
+- `BootstrapRunner.run()` wertet `startupArguments.mode()` aus:
+  - `HEADLESS` → `runHeadlessBatch()`
+  - `GUI` → `startGuiMode()`
+
+**Konfigurationsauflösung (Headless-Pfad)**
+- Prüfung, ob `--config`-Datei existiert (Fehler → Exit-Code 1)
+- `LegacyConfigurationMigrator.migrateIfLegacy()` bei erkannter Legacy-Form
+- `PropertiesConfigurationPortAdapter` lädt und parst die Properties
+- `StartConfigurationValidator` validiert die geladene `StartConfiguration`
+- Validierungsfehler → Exit-Code 1
+
+**KI-Provider-Auswahl**
+- Innerhalb von `buildProductionBatchUseCase()`:
+  `multiProviderConfiguration().activeProviderFamily()` → `AiProviderSelector.select(family, providerConfig)`
+- Ergebnis: genau eine `AiInvocationPort`-Instanz
+
+**Objektgraph-Aufbau (Headless)**
+- Erzeugte Instanzen (Reihenfolge nach Abhängigkeit): `Sha256FingerprintAdapter`,
+  `SqliteDocumentRecordRepositoryAdapter`, `SqliteProcessingAttemptRepositoryAdapter`,
+  `SqliteUnitOfWorkAdapter`, `FilesystemTargetFolderAdapter`, `FilesystemTargetFileCopyAdapter`,
+  `FilesystemPromptPortAdapter`, `SystemClockAdapter`, `SourceDocumentCandidatesPortAdapter`,
+  `PdfTextExtractionPortAdapter`, `Log4jProcessingLogger`
+- Application-Services (`DocumentProcessingCoordinator`, `AiResponseValidator`,
+  `AiNamingService`) werden verdrahtet und in `DefaultBatchRunProcessingUseCase` eingebettet
+
+**CLI-Adapter**
+- `BootstrapRunner` erzeugt `SchedulerBatchCommand` mit dem fertigen `BatchRunProcessingUseCase`
+
+**Exit-Code-Ableitung**
+- `BatchRunOutcome` → 0 (Lauf technisch erfolgreich) oder 1 (harter Bootstrap-/Konfigurationsfehler)
+- `PdfUmbenennerApplication` ruft `System.exit(exitCode)` auf
+
+**GUI-Pfad**
+- `startGuiMode()` baut via `buildGuiStartupContext()` einen `GuiStartupContext`:
+  enthält `AiModelCatalogDispatcher`, `EnvironmentApiKeyResolutionAdapter`,
+  `TechnicalTestOrchestrator`, `GuiConfigurationPropertiesWriter`
+- Bootstrap verdrahtet zusätzlich vier neue History-Use-Cases (`DefaultHistoryOverviewUseCase`,
+  `DefaultHistoryDetailsUseCase`, `DefaultHistoryResetDocumentStatusUseCase`,
+  `DefaultDeleteDocumentHistoryUseCase`) und den `DefaultPromptEditorUseCase` als anonyme
+  Bridge-Implementierungen in den `GuiStartupContext`
+- `ApplicationVersionProvider.resolveVersion()` wird aufgerufen und der Wert in
+  `GuiStartupContext.applicationVersion` gesetzt
+- Wenn eine Konfigurationsdatei beim Start bekannt ist, erzeugt Bootstrap zusätzlich einen
+  vollständig verdrahteten `GuiPromptEditorPort` (kombiniert `FilesystemPromptPortAdapter` mit
+  `DefaultPromptEditorUseCase`); ohne Konfiguration erhält der Context einen No-Op-Port
+- `GuiAdapter.start(context)` übernimmt; ab diesem Punkt liegt die Kontrolle beim GUI-Adapter
+- Im GUI-Pfad: keine SQLite-Schema-Initialisierung beim Start, kein Run-Lock-Erwerb, kein Batch-Use-Case;
+  History-Operationen initialisieren die Schema-Verbindung ad-hoc pro Aufruf
+- GUI-interne Ports und deren Verbindung mit Outbound-Adaptern sind in
+  `docs/architecture/gui-overview.md` beschrieben
+
+---
+
+## 5. Einstiegspunkte je Modul
+
+### pdf-umbenenner-adapter-out
+
+1. **`...ai.OpenAiHttpAdapter`** – zeigt das typische Adapter-Muster: Port-Interface implementieren,
+   alle provider-spezifischen Details kapseln, `ProviderConfiguration` als einzige
+   Konfigurationsquelle konsumieren. Danach `AnthropicClaudeHttpAdapter` zum Vergleich lesen.
+
+2. **`...sqlite.SqliteSchemaInitializationAdapter`** – erklärt das Datenbankschema, das alle
+   SQLite-Adapter voraussetzen. Hier sieht man, welche Felder in `document_record` und
+   `processing_attempt` existieren und wie Schema-Evolution additiv umgesetzt ist.
+
+3. **`...configuration.PropertiesConfigurationPortAdapter`** – Einstieg in die
+   Konfigurationskette. Von hier aus `MultiProviderConfigurationParser` und
+   `LegacyConfigurationMigrator` nachverfolgen.
+
+### pdf-umbenenner-adapter-in-cli
+
+1. **`...adapter.in.cli.SchedulerBatchCommand`** – komprimiertes Inbound-Adapter-Muster in einer
+   einzigen Klasse. Zeigt, wie ein Inbound-Adapter ausschließlich über Port-Interfaces mit der
+   Application kommuniziert.
+
+2. **`package-info.java`** – beschreibt Abhängigkeitsrichtung und Verdrahtungsvertrag dieses
+   Adapters.
+
+3. **`SchedulerBatchCommandTest`** – zeigt, wie der Adapter ohne Bootstrap testbar ist.
+
+### pdf-umbenenner-bootstrap
+
+1. **`PdfUmbenennerApplication`** – Startpunkt; die kurze Kette von `main()` bis `System.exit()`
+   gibt einen ersten Überblick über die gesamte Startsequenz.
+
+2. **`BootstrapRunner`** – Herzstück; `buildProductionBatchUseCase()` zeigt, wie der vollständige
+   Objektgraph manuell aufgebaut wird. `runHeadlessBatch()` zeigt den Headless-Kontrollfluss.
+
+3. **`AiProviderSelector`** – kleinste Klasse mit größter Hebelwirkung: hier liegt die einzige
+   Stelle, an der die Provider-Auswahl aus der Konfiguration auf eine konkrete
+   `AiInvocationPort`-Implementierung trifft.
+
+---
+
+*Port-Verträge und Domain-Typen: `docs/architecture/domain-overview.md`*
+*GUI-interne Ports und GUI-Adapter-Struktur: `docs/architecture/gui-overview.md`*
@@ -0,0 +1,193 @@
+# Architektur-Übersicht: Domain & Application
+
+Dieses Dokument beschreibt die fachliche und anwendungsnahe Schicht des PDF-Umbenenners: das Modul `pdf-umbenenner-domain` und das Modul `pdf-umbenenner-application`. Es richtet sich an Entwickler, die in diesen beiden Modulen arbeiten, und soll als alleiniger Architekturkontext ausreichen – ergänzt durch die `CLAUDE.md` im Projektroot. Nicht enthalten sind Adapter-Implementierungen (Dateisystem, PDFBox, SQLite, HTTP-Clients); diese sind in `adapter-overview.md` beschrieben. GUI-spezifische Ports und deren Einbettung in den Konfigurationseditor sind in `gui-overview.md` dokumentiert.
+
+---
+
+## 1. Modulzweck
+
+### `pdf-umbenenner-domain`
+
+Enthält ausschließlich fachliche Kerntypen (Records, Enums, Sealed Interfaces) ohne jegliche Infrastrukturabhängigkeiten. Alle Typen modellieren den Problembereich und sind von anderen Modulen referenzierbar, ohne transitive Abhängigkeiten einzuschleppen.
+
+### `pdf-umbenenner-application`
+
+Definiert Use-Case-Orchestrierung sowie alle Inbound- und Outbound-Ports der hexagonalen Architektur. Enthält anwendungsnahe Dienste (KI-Antwort-Parsing, Pre-Check-Auswertung, Retry-Entscheidung) und Konfigurationsmodelle, aber keinerlei Infrastrukturcode (kein JDBC, kein PDFBox, kein HTTP-Client, kein JavaFX).
+
+---
+
+## 2. Paketstruktur
+
+### `pdf-umbenenner-domain`
+
+| Paket | Verantwortung |
+|-------|---------------|
+| `de.gecheckt.pdf.umbenenner.domain` | Wurzelpaket; enthält nur `package-info.java` |
+| `de.gecheckt.pdf.umbenenner.domain.model` | Alle fachlichen Kerntypen: Records, Sealed Interfaces und Enums, die die Verarbeitungsdomäne beschreiben |
+
+### `pdf-umbenenner-application`
+
+| Paket | Verantwortung |
+|-------|---------------|
+| `de.gecheckt.pdf.umbenenner.application` | Wurzelpaket des Application-Moduls |
+| `de.gecheckt.pdf.umbenenner.application.port.in` | Inbound-Ports (Use-Case-Interfaces) – Einstiegspunkte für den Aufrufer |
+| `de.gecheckt.pdf.umbenenner.application.port.out` | Outbound-Ports – Verträge gegenüber Infrastruktur-Adaptern (Persistenz, Dateisystem, KI, Uhr, Logging) |
+| `de.gecheckt.pdf.umbenenner.application.port.out.modelcatalog` | Spezialisierter Outbound-Port für den Abruf verfügbarer KI-Modelle; ausschließlich im GUI-Pfad genutzt (siehe `gui-overview.md`) |
+| `de.gecheckt.pdf.umbenenner.application.port.out.history` | Outbound-Port für lesende Historien-Abfragen aus dem Historien-Tab; bewusst getrennt von den bestehenden Repositories, um diese nicht mit GUI-spezifischen Methoden aufzublähen |
+| `de.gecheckt.pdf.umbenenner.application.service` | Anwendungsnahe, zustandslose Dienste: KI-Antwort-Parsing, Pre-Check-Auswertung, Verarbeitungs-Pipeline, Retry-Entscheidung |
+| `de.gecheckt.pdf.umbenenner.application.config` | Konfigurationsmodelle der Anwendungsschicht (`RuntimeConfiguration`, Provider-Konfiguration) |
+| `de.gecheckt.pdf.umbenenner.application.config.startup` | Vollständiges Startup-Konfigurationsmodell (`StartConfiguration`) |
+| `de.gecheckt.pdf.umbenenner.application.config.provider` | Modelle für KI-Provider-Konfiguration (Provider-Familie, Einzelkonfiguration, Multi-Provider) |
+| `de.gecheckt.pdf.umbenenner.application.validation.editor` | Validierungslogik für den GUI-Konfigurationseditor (Findings, Report, API-Key-Auflösung); siehe `gui-overview.md` |
+| `de.gecheckt.pdf.umbenenner.application.validation.technicaltest` | Technischer Selbsttest: Pfad-Checks, Korrekturpläne, Checkpoints; Details in `gui-overview.md` |
+| `de.gecheckt.pdf.umbenenner.application.usecase` | Paket-Marker für Use-Case-Implementierungen |
+
+---
+
+## 3. Schlüsselklassen
+
+### Domain-Modul
+
+**`de.gecheckt.pdf.umbenenner.domain.model.SourceDocumentCandidate`**
+Record für einen PDF-Kandidaten aus dem Quellordner. Enthält keinen `Path`, sondern einen opaken `SourceDocumentLocator`, damit die Domain frei von NIO-Typen bleibt.
+
+**`de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint`**
+Record mit einem SHA-256-Hex-String (64 Zeichen) als stabiler Dokumentidentität; Grundlage für Idempotenz und Persistenz-Lookup.
+
+**`de.gecheckt.pdf.umbenenner.domain.model.DocumentProcessingOutcome`**
+Sealed Interface mit sechs Implementierungen, die alle möglichen Ausgänge der Dokumentverarbeitung exhaustiv abbilden:
+
+| Implementierung | Bedeutung |
+|-----------------|-----------|
+| `PreCheckPassed` | Vorprüfung bestanden, KI-Pfad freigegeben |
+| `PreCheckFailed` | Deterministischer Inhaltsfehler vor KI-Aufruf |
+| `TechnicalDocumentError` | Technischer Fehler ohne erneuten KI-Aufruf |
+| `NamingProposalReady` | KI-Antwort gültig, Vorschlag liegt vor |
+| `AiTechnicalFailure` | Transienter technischer Fehler beim KI-Aufruf |
+| `AiFunctionalFailure` | Deterministischer fachlicher Fehler der KI-Antwort |
+
+**`de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus`**
+Enum mit acht Zuständen. Dokumentiert Zustandsübergänge und Retry-Schwellen; fachliches Herzstück der Persistenz-Semantik.
+
+| Status | Bedeutung |
+|--------|-----------|
+| `READY_FOR_AI` | Verarbeitbar, KI-Pfad noch nicht durchlaufen |
+| `FAILED_RETRYABLE` | Verarbeitbar, transient fehlgeschlagen |
+| `PROPOSAL_READY` | Eingangszustand für Dateinamensbildung und Zielkopie |
+| `SUCCESS` | Terminaler Enderfolg – nur nach Zielkopie und konsistenter Persistenz |
+| `FAILED_FINAL` | Terminal, wird nicht erneut fachlich verarbeitet |
+| `SKIPPED_ALREADY_PROCESSED` | Historisierter Skip für `SUCCESS`-Dokumente |
+| `SKIPPED_FINAL_FAILURE` | Historisierter Skip für `FAILED_FINAL`-Dokumente |
+
+**`de.gecheckt.pdf.umbenenner.domain.model.NamingProposal`**
+Record mit aufgelöstem Datum, `DateSource`, validiertem Titel und KI-Begründung. Führende Quelle für die Zieldateinamensbildung.
+
+**`de.gecheckt.pdf.umbenenner.domain.model.BatchRunContext`**
+Klasse mit Run-ID, Zeitstempel und optionalem Fingerabdruck-Filter; steuert den Umfang eines Batch-Laufs.
+
+---
+
+### Application-Modul
+
+**`de.gecheckt.pdf.umbenenner.application.config.RuntimeConfiguration`**
+Schmales Laufzeit-Record (`maxPages`, `maxRetriesTransient`, `aiContentSensitivity`). Wird von den Use Cases verwendet, enthält keine Pfade.
+
+**`de.gecheckt.pdf.umbenenner.application.config.startup.StartConfiguration`**
+Vollständige typisierte Startup-Konfiguration; einziger Ort in der Anwendungsschicht, an dem `java.nio.file.Path` vorkommt. Wird vom `ConfigurationPort` geliefert und von Bootstrap ausgewertet.
+
+**`de.gecheckt.pdf.umbenenner.application.service.DocumentProcessingService`**
+Statische Hilfsklasse: überführt ein Extraktionsergebnis über den Pre-Check in ein `DocumentProcessingOutcome`. Kompakte Pipeline-Klasse; guter Einstieg zum Verständnis der Verarbeitungslogik.
+
+**`de.gecheckt.pdf.umbenenner.application.service.AiResponseParser`**
+Statischer Parser für KI-Antworten in `ParsedAiResponse`. Erzwingt reines JSON-Objekt; Validierungslogik liegt vollständig in der Anwendungsschicht.
+
+**`de.gecheckt.pdf.umbenenner.application.port.out.ProcessingAttempt`**
+Record für einen Versuchshistorie-Eintrag; enthält u. a. Provider-Identifikator, Modellname, Prompt-Identifikator, aufgelöstes Datum und finalen Zieldateinamen.
+
+**`de.gecheckt.pdf.umbenenner.application.port.out.DocumentRecord`**
+Record für den Dokument-Stammsatz; enthält Gesamtstatus, Fehler- und Transientzähler sowie letzten Zielpfad.
+
+**`de.gecheckt.pdf.umbenenner.application.port.out.history.HistoryQuery`**
+Record mit den Abfrageparametern für den Historien-Tab: optionaler Suchbegriff (`searchText`, Teilstring, case-insensitiv), optionaler Status-Filter (`statusFilter` als Enum-Name) und Limit der zurückzugebenden Zeilen (Standard `DEFAULT_LIMIT = 501`). Das Limit 501 ermöglicht der aufrufenden Schicht zu erkennen, ob mehr als 500 Treffer vorhanden sind.
+
+**`de.gecheckt.pdf.umbenenner.application.port.out.history.DocumentHistoryRow`**
+Einzelzeile der Dokumentenliste im Historien-Tab. Felder: `fingerprint`, `overallStatus`, `sourceFileName`, `targetFileName` (null wenn noch kein Erfolg), `sourcePath`, `updatedAt` und `attemptCount`. Stammt aus `document_record` mit einem `COUNT`-Ausdruck über `processing_attempt`.
+
+**`de.gecheckt.pdf.umbenenner.application.port.out.PromptSaveResult`**
+Versiegeltes Ergebnis-Interface für `PromptPort.savePrompt(String)`. Zulässige Ausprägungen: `Saved` (Erfolg, enthält absoluten Pfad), `WriteFailed` (I/O-Fehler beim Schreiben der Temp-Datei), `TargetDirectoryMissing` (Zielordner fehlt), `AtomicMoveFailed` (atomares Verschieben nicht möglich; kein stiller Fallback).
+
+**Neue Use-Case-Implementierungen im Paket `de.gecheckt.pdf.umbenenner.application.usecase`**
+
+| Klasse | Zweck |
+|--------|-------|
+| `DefaultHistoryOverviewUseCase` | Lädt die gefilterte Dokumentenübersicht über `HistoryQueryPort.loadOverview`; gibt `HistoryOverviewResult` mit Liste und `hasMore`-Flag zurück |
+| `DefaultHistoryDetailsUseCase` | Lädt Stammsatz und alle Verarbeitungsversuche für einen Fingerprint über `HistoryQueryPort`; gibt `HistoryDetailsResult` zurück |
+| `DefaultHistoryResetDocumentStatusUseCase` | Feldgenauer Status-Reset via `UnitOfWorkPort.TransactionOperations.resetDocumentStatusForRetry`; setzt `overall_status`, `content_error_count`, `transient_error_count` und `last_failure_instant` zurück; lässt die Versuchshistorie unangetastet |
+| `DefaultDeleteDocumentHistoryUseCase` | Löscht Stammsatz und alle Verarbeitungsversuche vollständig und transaktional via `UnitOfWorkPort` |
+| `DefaultPromptEditorUseCase` | Delegiert Laden, Speichern und Standard-Anlegen der Prompt-Datei an `PromptPort` und `ResourceCreationPort`; wird im GUI-Pfad über `GuiPromptEditorPort` angesteuert |
+
+---
+
+## 4. Inbound Ports
+
+### `BatchRunProcessingUseCase`
+
+```
+de.gecheckt.pdf.umbenenner.application.port.in.BatchRunProcessingUseCase
+```
+
+Zentraler Use-Case-Einstiegspunkt für den gesamten Batch-Betrieb. Beschreibt den Anwendungszweck in einer einzigen Methode:
+
+```java
+BatchRunOutcome execute(BatchRunContext context);
+```
+
+Mögliche Ergebnisse:
+
+| Ergebnis | Bedeutung |
+|----------|-----------|
+| `SUCCESS` | Lauf technisch ordnungsgemäß abgeschlossen |
+| `LOCK_UNAVAILABLE` | Run-Lock konnte nicht erworben werden |
+| `FAILURE` | Harter technischer Fehler beim Laufstart |
+
+---
+
+## 5. Outbound Ports
+
+Alle Outbound-Ports liegen in `de.gecheckt.pdf.umbenenner.application.port.out` (bzw. dessen Unterpaket `modelcatalog`). Implementierungen befinden sich ausschließlich in `pdf-umbenenner-adapter-out`; Details dort sind in `adapter-overview.md` beschrieben.
+
+| Interface | Zweck | Hauptmethode(n) |
+|-----------|-------|-----------------|
+| `SourceDocumentCandidatesPort` | Scannt Quellordner, liefert Kandidaten in deterministischer Reihenfolge | `List<SourceDocumentCandidate> loadCandidates()` |
+| `FingerprintPort` | Berechnet SHA-256-Fingerabdruck eines Kandidaten | `FingerprintResult computeFingerprint(SourceDocumentCandidate)` |
+| `PdfTextExtractionPort` | Extrahiert Text und Seitenanzahl aus einer PDF | `PdfExtractionResult extractTextAndPageCount(...)` |
+| `AiInvocationPort` | Ruft den aktiven KI-Dienst auf; provider-neutral | `AiInvocationResult invoke(AiRequestRepresentation)` |
+| `PromptPort` | Lädt das Prompt-Template aus der konfigurierten Quelle; speichert geänderten Inhalt atomar via `savePrompt(String)` – der Pfad stammt aus der Adapter-internen Konfiguration, nicht aus dem Port-Aufruf | `PromptLoadingResult loadPrompt()`, `PromptSaveResult savePrompt(String content)` |
+| `TargetFileCopyPort` | Kopiert Quelldokument unter aufgelöstem Namen in den Zielordner (Temp + Rename) | `TargetFileCopyResult copyToTarget(...)` |
+| `TargetFileRenamePort` | Atomare Umbenennung einer bereits kopierten Zieldatei (manuelle Korrektur) | `TargetFileRenameResult rename(...)` |
+| `RunLockPort` | Exklusiver Lauf-Lock gegen parallele Instanzen | `acquire()` / `release()` |
+| `PersistenceSchemaInitializationPort` | Idempotente Schema-Initialisierung der SQLite-Datenbank | `initializeSchema()` |
+| `ClockPort` | Abstraktion des Systemtakts | `Instant now()` |
+| `ConfigurationPort` | Lädt die typisierte Startup-Konfiguration | `StartConfiguration loadConfiguration()` |
+| `ProcessingLogger` | Logging-Delegation; sensibles KI-Content-Logging über Flag gesteuert | `info/debug/warn/error/debugSensitiveAiContent(...)` |
+| `AiModelCatalogPort` | Abruf verfügbarer Modelle vom Provider (nur GUI-Pfad, siehe `gui-overview.md`) | `ModelCatalogResult fetchAvailableModels(...)` |
+| `PathCheckPort` | Lesende Pfad-Prüfung für den technischen Selbsttest | `isDirectoryReadable`, `isDirectoryWritableOrCreatable`, `isFileReadable`, `isSqlitePathUsable` |
+| `ResourceCreationPort` | Schreibende Korrektur-Aktionen (Ordner anlegen, Prompt-Datei erzeugen, SQLite-Pfad vorbereiten) | `createDirectory`, `createPromptFile`, `prepareSqlitePath` |
+| `ApiKeyResolutionPort` | Ermittelt API-Key-Herkunft pro Provider-Familie für die GUI-Validierung | `EffectiveApiKeyDescriptor resolve(...)` |
+| `HistoryQueryPort` | Lesender Zugriff auf die Verarbeitungshistorie für den Historien-Tab; bewusst getrennt von den regulären Repositories | `List<DocumentHistoryRow> loadOverview(HistoryQuery)`, `Optional<DocumentRecord> findRecordByFingerprint(DocumentFingerprint)`, `List<ProcessingAttempt> findAttemptsByFingerprint(DocumentFingerprint)` |
+
+> **Hinweis zu GUI-spezifischen Ports:** `AiModelCatalogPort`, `PathCheckPort`, `ResourceCreationPort`, `ApiKeyResolutionPort` und `HistoryQueryPort` werden ausschließlich im GUI-Pfad genutzt. Ihre Implementierungen und der Aufrufkontext sind in `gui-overview.md` bzw. `adapter-overview.md` beschrieben.
+
+> **Hinweis zu `UnitOfWorkPort.TransactionOperations`:** Die innere Schnittstelle `TransactionOperations` wurde um die Methode `resetDocumentStatusForRetry(DocumentFingerprint)` erweitert. Diese setzt feldgenau `overall_status → READY_FOR_AI`, `content_error_count → 0`, `transient_error_count → 0` und `last_failure_instant → NULL`, ohne die Versuchshistorie zu berühren. Die Implementierung liegt in `SqliteUnitOfWorkAdapter`.
+
+---
+
+## 6. Einstiegspunkte für neue Entwickler
+
+Die folgende Lesereihenfolge gibt den kürzesten Weg zum Gesamtverständnis:
+
+1. **`de.gecheckt.pdf.umbenenner.application.port.in.BatchRunProcessingUseCase`** – beschreibt den gesamten Anwendungszweck in einer Methode.
+2. **`de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus`** – fachliches Herzstück; dokumentiert Zustandsübergänge und Retry-Schwellen.
+3. **`de.gecheckt.pdf.umbenenner.domain.model`** (gesamtes Paket) – gemeinsame Sprache aller Schichten; vollständig in wenigen Minuten lesbar.
+4. **`de.gecheckt.pdf.umbenenner.application.service.DocumentProcessingService`** – kompakte Pipeline-Klasse; zeigt, wie Pre-Check und Ergebnis-Typen zusammenspielen.
+5. **`de.gecheckt.pdf.umbenenner.application.port.out`** (gesamtes Paket) – vollständige Außengrenzen der Architektur; jeder Infrastrukturzugriff ist hier als Port definiert.
@@ -0,0 +1,209 @@
+# Architektur-Übersicht: GUI (adapter-in-gui)
+
+Diese Datei beschreibt den Inbound-Adapter `pdf-umbenenner-adapter-in-gui` – die JavaFX-Desktop-GUI des PDF-Umbenenners. Sie ist zusammen mit `CLAUDE.md` im Projektroot als alleiniger Architekturkontext für GUI-Arbeit gedacht. Domain-Typen, Application-Ports und Outbound-Adapter (Dateisystem, SQLite, KI-HTTP) sind hier bewusst nicht beschrieben; dafür gelten `docs/architecture/domain-overview.md` und `docs/architecture/adapter-overview.md`. **Das JavaFX-Threading-Modell (Abschnitt 4) ist verbindlich und muss strikt eingehalten werden – GUI-Entwickler sollten diesen Abschnitt als erstes lesen.**
+
+---
+
+## 1. Modulzweck
+
+`pdf-umbenenner-adapter-in-gui` ist der Inbound-Adapter für die Desktop-Oberfläche. Er:
+
+- empfängt den Startaufruf von der Bootstrap-Schicht über `GuiAdapter`,
+- baut das JavaFX-Hauptfenster auf,
+- delegiert alle fachlichen und technischen Operationen an Bootstrap-seitig verdrahtete Ports,
+- zeigt Ergebnisse ausschließlich auf dem JavaFX Application Thread an.
+
+Das Modul enthält **keine fachliche Logik**, keinen Datenbankzugriff, keinen HTTP-Code und keine PDF-Verarbeitung. Es koordiniert lediglich Benutzereingaben, Worker-Threads und JavaFX-Controls.
+
+---
+
+## 2. Paketstruktur
+
+```
+de.gecheckt.pdf.umbenenner.adapter.in.gui
+│
+├── (root)           Einstiegspunkt, Hauptfenster, Orchestrierung, GUI-interne
+│                    Ports, Hilfsklassen für Fenstertitel, System-Tray,
+│                    Dateiladen/-schreiben und Startkontext.
+│                    Enthält außerdem: GuiStatusBar, GuiPromptEditorTab und
+│                    GuiPromptEditorPort.
+│
+├── batchrun         Komponenten für den Tab „Verarbeitungslauf":
+│                    Worker-Koordinator, Tab-Ansicht, Ergebniszeilen,
+│                    PDF-Vorschau, Dateiname-Editor sowie GUI-interne
+│                    Port-Interfaces für Batch-Run, Mini-Run, manuelles
+│                    Umbenennen/Kopieren, Status-Reset und historischen Kontext.
+│                    Enthält außerdem: BatchRunSummaryBanner und
+│                    ProcessingStatusPresentation.
+│
+├── editor           View-Modell- und Zustandstypen ohne JavaFX-Controls
+│                    (Ausnahme: GuiModelFieldContainer). Enthält Snapshot,
+│                    Baseline/Current-Values, Dirty-State-Berechnung,
+│                    Provider-Konfigurationszustände, API-Key-Zustände,
+│                    Validierungsergebnisse, Meldungs- und Feldbefund-Typen.
+│
+└── history          Komponenten für den Tab „Verlauf": Tab-Ansicht mit
+                     zweigeteiltem Layout (Liste + Detail), Filter, Aktionen
+                     (Status-Reset / vollständiges Löschen) sowie die vier
+                     Bridge-Interfaces GuiHistoryOverviewPort,
+                     GuiHistoryDetailsPort, GuiHistoryResetDocumentStatusPort
+                     und GuiDeleteDocumentHistoryPort.
+```
+
+**Tab-Reihenfolge:** `Konfiguration | Verarbeitungslauf | Verlauf | Prompt`
+
+---
+
+## 3. Schlüsselklassen
+
+### Root-Paket
+
+| Klasse (Kurzname) | Rolle |
+|---|---|
+| `GuiAdapter` | Einziger öffentlicher Bootstrap-Einstiegspunkt. Speichert `GuiStartupContext` im `GuiStartupContextHolder` und startet JavaFX via `Application.launch`. Genau einmal pro JVM aufrufbar. |
+| `PdfUmbenennerGuiApplication` | JavaFX-`Application`-Unterklasse. Baut in `start(Stage)` Hauptfenster, `GuiConfigurationEditorWorkspace`, Titelaktualisierungs-Listener, Close-Handler und System-Tray auf. Triggert nach Anzeige `autoLoadLastConfiguration()`. |
+| `GuiStartupContext` | Immutable Record mit allen Bootstrap-gelieferten Ports und Services: Dateilader/-schreiber, Modellkatalog-Port, API-Key-Resolution-Port, Technical-Test-Orchestrator, Correction-Execution-Service, Batch-Run-Launcher, Mini-Run-Launcher, Reset-Port, Manual-Rename-Port, Manual-Copy-Port, Historical-Context-Port, `applicationVersion` (Versions-String aus `ApplicationVersionProvider`), `promptEditorPort`, `historyOverviewPort`, `historyDetailsPort`, `historyResetDocumentStatusPort`, `deleteDocumentHistoryPort`. Bietet `blank()`-Fabrikmethode für Tests. |
+| `GuiConfigurationEditorWorkspace` | Herzstück der Oberfläche. Baut `TabPane` mit den vier Tabs (Konfiguration, Verarbeitungslauf, Verlauf, Prompt), verwaltet `GuiConfigurationEditorState`, koordiniert Lade- und Schreibvorgänge auf Worker-Threads, steuert Dirty-State-Anzeige und Fenstertitel. |
+| `GuiStatusBar` | Permanente Statuszeile am unteren Rand des Hauptfensters. Drei Segmente: links Anwendungsversion im Format `V<version>` (z. B. `Vdev`), Mitte aktiver Provider und Modell aus geladener Konfiguration, rechts Pfad der geladenen Konfigurationsdatei. Ohne geladene Konfiguration zeigen Mitte und Rechts den Platzhaltertext. |
+| `GuiPromptEditorTab` | Tab „Prompt" mit `TextArea` zum Lesen, Bearbeiten und Speichern der Prompt-Datei. Dirty-State markiert den Tab-Titel mit einem Asterisk. Speichert atomar via `GuiPromptEditorPort`. Bietet „Auf Standard zurücksetzen" (füllt `TextArea` ohne zu speichern) und „Standard-Prompt erstellen" bei fehlender Datei. |
+| `GuiModelCatalogCoordinator` | Asynchroner Modellabruf über `AiModelCatalogPort` auf Daemon-Thread `gui-model-catalog`. Liefert Ergebnis via `Platform.runLater` und aktualisiert ComboBox oder manuelles TextField. |
+| `GuiTechnicalTestCoordinator` | Führt `TechnicalTestOrchestrator` asynchron auf Daemon-Thread `gui-technical-test` aus, ohne implizites Speichern. Replace-Semantik in `pendingMessages`. |
+| `GuiCorrectionDialogCoordinator` | Empfängt `TechnicalTestReport`, leitet `CorrectionPlan` ab, zeigt gesammelten Bestätigungsdialog. Kein stiller Schreibzugriff. |
+| `GuiUnsavedChangesGuard` | Drei-Wege-Schutzdialog (Speichern / Verwerfen / Abbrechen) vor Neu, Öffnen und Schließen. Dialog-Supplier ist injizierbar für Tests ohne Scene. |
+| `SystemTrayManager` | Verwaltet Windows-System-Tray-Icon. Überbrückt AWT-EDT nach JavaFX via `Platform.runLater` für Stage-Operationen. |
+
+### Paket `editor`
+
+| Klasse (Kurzname) | Rolle |
+|---|---|
+| `GuiConfigurationEditorState` | Record mit `loadedFileSnapshot`, `baselineValues`, `values`, `pendingMigrationMessage`. Dirty-State wird per Vergleich berechnet, kein Flag. |
+| `GuiConfigurationValues` | Hält alle editierbaren Konfigurationsfelder als JavaFX-freie Plain-Java-Typen. |
+
+### Paket `batchrun`
+
+| Klasse (Kurzname) | Rolle |
+|---|---|
+| `GuiBatchRunCoordinator` | Besitzt den Worker-Thread für Batch- und Mini-Run. Übersetzt `BatchRunProgressObserver`-Callbacks via `Platform.runLater`. Soft-Stop per `AtomicBoolean`. Enthält `toRow()` inkl. historischem Kontext-Nachladen. |
+| `GuiBatchRunTab` | Zweiter Haupt-Tab mit `TableView`, `ProgressBar`, Start-/Stop-Buttons und Detailbereich. Implementiert `GuiBatchRunCoordinator.Listener`. |
+| `BatchRunSummaryBanner` | Einzeilige Zusammenfassungsleiste nach Laufabschluss, unterhalb des Fortschrittsbalkens. Zeigt nur Kategorien mit Zähler > 0. Farbe ist niemals das einzige Unterscheidungsmerkmal: jedes Segment enthält Icon und Text. |
+| `ProcessingStatusPresentation` | Zentrale Mapping-Klasse für Status-Icons, CSS-Farben, Tooltip-Texte und Summary-Kategoriebeschriften aller `DocumentCompletionStatus`-Werte. Einzige autoritative Quelle für alle Anzeigeorte (Tabelle, Detail, Banner). Enthält keine JavaFX-Typen; zustandslos und statisch. Farbe ist niemals das einzige Unterscheidungsmerkmal. |
+| `PdfPreviewPane` | Asynchrones PDF-Rendering via PDFBox auf Single-Thread-Executor `pdf-preview-worker`. Stale-Request-Schutz via `AtomicLong`-Sequenznummer, In-Memory-Seiten-Cache. |
+| `FileNameEditorPane` | Editor für den Zieldateinamen. Drei-Zustands-Modell: KI-Vorschlag / letzter gespeicherter / aktuelle Eingabe. Clientseitige Validierung; Speicher-Aufruf delegiert an Tab. |
+| `AiFailureMessageTranslator` | Übersetzt englische technische Fehlermeldungen in deutsche Benutzertexte. Paket-privat, zustandslos. |
+
+### Paket `history`
+
+| Klasse (Kurzname) | Rolle |
+|---|---|
+| `GuiHistoryTab` | Tab „Verlauf" mit zweigeteiltem Layout: links Dokumentenliste mit Freitext- und Statusfilter, rechts Detailbereich mit Stammsatz und Versuchshistorie. Aktionen: Status-Reset (feldgenau, Versuchshistorie bleibt) und vollständiges Löschen (mit Bestätigungsdialog). Alle Datenbankoperationen auf Worker-Thread, UI-Updates via `Platform.runLater`. |
+
+---
+
+## 4. Threading-Modell
+
+Das Modell ist verbindlich. Jede Verletzung dieser Regeln führt zu sporadischen `IllegalStateException`-Fehlern oder einer eingefrorenen Oberfläche.
+
+### 4.1 Worker-Threads
+
+Alle blockierenden Operationen laufen auf benannten Daemon-Threads außerhalb des JavaFX Application Thread.
+
+| Thread-Name | Koordinator-Klasse | Operationen |
+|---|---|---|
+| `gui-batch-run` | `GuiBatchRunCoordinator` | Batch-Launcher, Mini-Run-Launcher, Reset-Port, historischer Kontext |
+| `gui-model-catalog` | `GuiModelCatalogCoordinator` | `modelCatalogPort.fetchAvailableModels(...)` |
+| `gui-technical-test` | `GuiTechnicalTestCoordinator` | `orchestrator.runTests(...)` |
+| Korrektur-Worker (anonym) | `GuiCorrectionDialogCoordinator` | `correctionExecutionService.execute(...)` |
+| `pdf-preview-worker` | `PdfPreviewPane` | `PDDocument` laden, `PDFRenderer.renderImageWithDPI`, `PDDocument.close` |
+| Dateisystem-Worker (inline) | `GuiConfigurationEditorWorkspace` | `configurationFileLoader.load(...)`, `configurationFileWriter.write(...)` |
+| Inline-Worker (anonym) | `GuiHistoryTab` | `historyOverviewPort.loadOverview(...)`, `historyDetailsPort.loadDetails(...)`, `historyResetDocumentStatusPort.resetStatus(...)`, `deleteDocumentHistoryPort.deleteHistory(...)` |
+| Inline-Worker (anonym) | `GuiPromptEditorTab` | `promptEditorPort.loadCurrentPrompt()`, `promptEditorPort.save(...)`, `promptEditorPort.createDefaultPromptIfMissing(...)` |
+
+### 4.2 JavaFX Application Thread
+
+Alle Mutationen an JavaFX-Controls und alle Dialoganzeigen ausschließlich auf dem JavaFX Application Thread. Kein direktes Schreiben auf Controls vom Worker-Thread.
+
+### 4.3 Übergangsmechanismus Worker → FX
+
+Der Übergang erfolgt grundsätzlich via:
+
+```java
+Platform.runLater(runnable);
+```
+
+Es werden **keine** `javafx.concurrent.Task` und kein `Service` verwendet. Die Koordinatoren steuern Threading manuell über zwei injizierbare Strategien:
+
+| Injektionspunkt | Typ | Produktion | Tests |
+|---|---|---|---|
+| `threadFactory` | `Function<Runnable, Thread>` | `Thread::new` (Daemon) | synchroner Direktaufruf |
+| `fxDispatcher` | `Consumer<Runnable>` | `Platform::runLater` | synchroner Direktaufruf |
+
+Durch diese Injektion sind Unit-Tests vollständig ohne JavaFX-Runtime möglich.
+
+### 4.4 Stale-Request-Schutz
+
+`PdfPreviewPane` vergibt für jede Renderanfrage eine inkrementelle `AtomicLong`-Sequenznummer. Ein abgeschlossenes Render-Ergebnis wird nur dann auf der UI angezeigt, wenn seine Sequenznummer noch der aktuellen entspricht. Veraltete Ergebnisse werden still verworfen.
+
+---
+
+## 5. GUI-interne Ports
+
+> **Abgrenzung:** Die folgenden Interfaces sind **keine hexagonalen Outbound-Ports der Application-Schicht**. Sie sind modul-interne Brücken, über die `GuiAdapter` die Bootstrap-seitig verdrahteten Implementierungen in die GUI-Klassen einschleust. Die eigentlichen Application-Ports (`AiInvocationPort`, `AiModelCatalogPort` usw.) und deren Outbound-Adapter-Implementierungen sind in `docs/architecture/domain-overview.md` und `docs/architecture/adapter-overview.md` beschrieben.
+
+### Root-Paket
+
+| Interface | Zweck |
+|---|---|
+| `GuiConfigurationFileLoader` | Lädt eine `.properties`-Datei und liefert einen `GuiConfigurationEditorState`. Abstrahiert Migration und Bootstrap-Verdrahtung vom GUI-Code. |
+| `GuiConfigurationFileWriter` | Schreibt aktuelle `GuiConfigurationValues` als normalisierte `.properties` inkl. Backup-Schema. |
+
+### Paket `batchrun`
+
+| Interface | Zweck |
+|---|---|
+| `GuiBatchRunLauncher` | Bootstrap-Brücke für den regulären Batch-Run auf dem Worker-Thread. |
+| `GuiMiniRunLauncher` | Bootstrap-Brücke für einen auf einen Fingerprint-Filter beschränkten Mini-Run. |
+| `GuiResetDocumentStatusPort` | Bootstrap-Brücke für den vollständigen Persistenz-Reset (Stammsatz und Versuchshistorie werden gelöscht) ohne Folge-Run. |
+| `GuiManualFileRenamePort` | Bootstrap-Brücke für die manuelle Umbenennung der Zieldatei (Worker-Thread). |
+| `GuiManualFileCopyPort` | Bootstrap-Brücke für die Kopie mit benutzerdefiniertem Zieldateinamen bei FAILED/SKIPPED-Dokumenten (Worker-Thread). |
+| `GuiHistoricalDocumentContextPort` | Nachladen des vollständigen historischen Verarbeitungskontexts für übersprungene Dokumente (Worker-Thread). |
+| `GuiHistoricalFileNamePort` | Spezialisierter Port für den letzten bekannten KI-Dateinamen. Weitgehend durch `GuiHistoricalDocumentContextPort` abgelöst, aber noch im Einsatz. |
+
+### Root-Paket (GUI-interne Ports)
+
+| Interface | Zweck |
+|---|---|
+| `GuiPromptEditorPort` | Bootstrap-Brücke zum Prompt-Editor-Use-Case: Laden (`loadCurrentPrompt()`), atomares Speichern (`save(String)`) und Standard-Anlegen (`createDefaultPromptIfMissing(...)`) der Prompt-Datei. |
+
+### Paket `history`
+
+| Interface | Zweck |
+|---|---|
+| `GuiHistoryOverviewPort` | Bootstrap-Brücke zur Historien-Übersicht; lädt gefilterte Dokumentenliste via `loadOverview(Path configFilePath, HistoryQuery)`. `configFilePath` ermöglicht der Bootstrap-Implementierung, die SQLite-Datenbank aus der aktuell geladenen Konfiguration abzuleiten. |
+| `GuiHistoryDetailsPort` | Bootstrap-Brücke zur Detailansicht; lädt Stammsatz und alle Verarbeitungsversuche für einen Fingerprint via `loadDetails(Path, DocumentFingerprint)`. |
+| `GuiHistoryResetDocumentStatusPort` | Bootstrap-Brücke für den feldgenauen Status-Reset im Historien-Tab (`overall_status → READY_FOR_AI`, Fehlerzähler → 0, `last_failure_instant → null`). Die Versuchshistorie bleibt vollständig erhalten. **Abgrenzung:** `GuiResetDocumentStatusPort` im `batchrun`-Paket löscht dagegen Stammsatz und Versuchshistorie vollständig. |
+| `GuiDeleteDocumentHistoryPort` | Bootstrap-Brücke zum vollständigen Löschen von Stammsatz und Versuchshistorie via `deleteHistory(Path, DocumentFingerprint)`; destruktiv und nicht rückgängig zu machen. Die GUI zeigt vor dem Aufruf einen Bestätigungsdialog. |
+
+Alle Implementierungen dieser Interfaces liegen in `pdf-umbenenner-bootstrap`. Das GUI-Modul kennt ausschließlich die Interface-Typen.
+
+---
+
+## 6. Einstiegspunkte für neue Entwickler
+
+Folgende Klassen und Dateien decken den schnellsten Einstieg ab:
+
+1. **`GuiAdapter`** – Architekturgrenze zur Bootstrap-Schicht in zwei Methoden. Zeigt, wie die GUI aus Bootstrap-Sicht aufgerufen wird.
+
+2. **`GuiStartupContext`** – Vollständige Liste aller Ports und Services, die Bootstrap in die GUI injiziert. Wer wissen will, was die GUI von außen bekommt, liest diesen Record.
+
+3. **`GuiConfigurationEditorWorkspace`** – Zentrale UI-Klasse: Tab-Aufbau, Sektionen, Editor-Zustand, Dirty-State, Datei-I/O, Sub-Koordinatoren. Einstieg für alle Arbeiten am Konfigurationseditor-Tab.
+
+4. **`GuiConfigurationEditorState` / `GuiConfigurationValues`** – View-Modell ohne JavaFX-Controls. Einstieg für alle Änderungen an editierbaren Konfigurationsfeldern und Dirty-State-Logik.
+
+5. **`GuiBatchRunCoordinator`** – Threading-Modell in seiner reinsten Form: Worker-Thread, `Platform.runLater`-Übergabe, Soft-Stop, Listener-Protokoll. Einstieg für alle Arbeiten am Verarbeitungslauf-Tab.
+
+6. **`batchrun/package-info.java`** – Kompakte Beschreibung des Threading-Kontrakts, der Abbruch-Semantik und der Konfigurationsquelle für dieses Paket.
+
+### Querverweise
+
+- Application-Ports und Domain-Typen (`NamingProposal`, `ProcessingStatus`, `DocumentFingerprint` usw.): `docs/architecture/domain-overview.md`
+- Outbound-Adapter-Implementierungen (Dateisystem, SQLite, KI-HTTP, PDFBox) und Bootstrap-Verdrahtung: `docs/architecture/adapter-overview.md`
@@ -0,0 +1,355 @@
+# Befundliste – Integrierte Gesamtprüfung und Freigabe des Endstands
+
+**Erstellt:** 2026-04-08  
+**Aktualisiert:** 2026-04-08 (Naming-Convention-Bereinigung B1 abgeschlossen, finale Freigabe)  
+**Grundlage:** Vollständiger Maven-Reactor-Build, Unit-Tests, E2E-Tests, Integrationstests (Smoke),
+PIT-Mutationsanalyse, Code-Review gegen verbindliche Spezifikationen (technik-und-architektur.md,
+fachliche-anforderungen.md, CLAUDE.md)
+
+---
+
+## Ausgeführte Prüfungen
+
+| Prüfbereich | Ausgeführt | Ergebnis |
+|---|---|---|
+| Maven-Reactor-Build (clean verify, alle Module) | ja | GRÜN |
+| Unit-Tests (Domain, Application, Adapter-out, Bootstrap) | ja | GRÜN |
+| E2E-Tests (BatchRunEndToEndTest, 11 Szenarien) | ja | GRÜN |
+| Integrationstests / Smoke-IT (ExecutableJarSmokeTestIT, 2 Tests) | ja | GRÜN |
+| PIT-Mutationsanalyse (alle Module) | ja | siehe Einzelbefunde |
+| Hexagonale Architektur – Domain-Isolation | ja | GRÜN |
+| Hexagonale Architektur – Port-Verträge (kein Path/NIO/JDBC) | ja | GRÜN |
+| Hexagonale Architektur – keine Adapter-zu-Adapter-Abhängigkeiten | ja | GRÜN |
+| Statusmodell (8 Werte, Semantik laut CLAUDE.md) | ja | GRÜN |
+| Naming-Convention-Regel (kein M1–M8, kein AP-xxx im Code) | ja | GRÜN |
+| Logging-Sensibilitätsregel (log.ai.sensitive) | ja | GRÜN |
+| Exit-Code-Semantik (0 / 1) | ja | GRÜN |
+| Konfigurationsbeispiele (Pflicht- und Optionalparameter) | ja | GRÜN |
+| Betriebsdokumentation (docs/betrieb.md) | ja | GRÜN |
+| Prompt-Template im Repository | ja | GRÜN |
+| Rückwärtsverträglichkeit M4–M7 (Statusmodell, Schema) | ja (statisch) | GRÜN |
+
+---
+
+## Grüne Bereiche (keine Befunde)
+
+### Build und Tests
+
+- Vollständiger Maven-Reactor-Build erfolgreich (`BUILD SUCCESS`, Gesamtlaufzeit ~4 Minuten)
+- **827+ Tests** bestanden, 0 Fehler, 0 übersprungen:
+  - Domain: 227 Tests
+  - Application: 295 Tests
+  - Adapter-out: 227 Tests
+  - Bootstrap (Unit): 76 Tests
+  - Smoke-IT: 2 Tests
+
+### E2E-Szenarien (BatchRunEndToEndTest)
+
+Alle geforderten Kernszenarien aus der E2E-Testbasis sind abgedeckt und grün:
+
+- Happy-Path: zwei Läufe → `SUCCESS`
+- Deterministischer Inhaltsfehler: zwei Läufe → `FAILED_FINAL`
+- Transienter KI-Fehler → `FAILED_RETRYABLE`
+- Skip nach `SUCCESS` → `SKIPPED_ALREADY_PROCESSED`
+- Skip nach `FAILED_FINAL` → `SKIPPED_FINAL_FAILURE`
+- `PROPOSAL_READY`-Finalisierung ohne erneuten KI-Aufruf im zweiten Lauf
+- Zielkopierfehler mit Sofort-Wiederholversuch → `SUCCESS`
+- Transiente Fehler über mehrere Läufe → Ausschöpfung → `FAILED_FINAL`
+- Zielkopierfehler beide Versuche gescheitert → `FAILED_RETRYABLE`
+- Zwei verschiedene Dokumente, gleicher Vorschlagsname → Dubletten-Suffix `(1)`
+- Mixed-Batch: ein Erfolg, ein Inhaltsfehler → Batch-Outcome `SUCCESS` (Exit-Code 0)
+
+### Hexagonale Architektur
+
+- **Domain** vollständig infrastrukturfrei: keine Imports aus `java.nio`, `java.io.File`,
+  JDBC, Log4j oder HTTP-Bibliotheken
+- **Port-Verträge** (alle Interfaces in `application.port.out`) enthalten keine `Path`-,
+  `File`-, NIO- oder JDBC-Typen; nur Domain-Typen werden in Signaturen verwendet
+- **Keine Adapter-zu-Adapter-Abhängigkeiten** in `adapter-out`: kein Modul referenziert
+  ein anderes Adapter-Implementierungspaket direkt
+- **Abhängigkeitsrichtung** korrekt: adapter-out → application → domain
+
+### Fachregeln
+
+- Statusmodell vollständig (8 Werte: `READY_FOR_AI`, `PROPOSAL_READY`, `SUCCESS`,
+  `FAILED_RETRYABLE`, `FAILED_FINAL`, `SKIPPED_ALREADY_PROCESSED`,
+  `SKIPPED_FINAL_FAILURE`, `PROCESSING`)
+- Retry-Semantik korrekt implementiert (deterministisch 1 Retry → final;
+  transient bis `max.retries.transient`)
+- Skip-Semantik korrekt (SUCCESS → Skip, FAILED_FINAL → Skip, keine Zähleränderung)
+- Führende Proposal-Quelle: `PROPOSAL_READY`-Versuch wird korrekt als Quelle verwendet
+- SUCCESS-Bedingung: erst nach Zielkopie und konsistenter Persistenz
+
+### Logging und Sensibilität
+
+- `log.ai.sensitive`-Mechanismus vollständig implementiert und getestet
+- Default `false` (sicher): KI-Rohantwort und Reasoning nicht im Log
+- Persistenz in SQLite unabhängig von dieser Einstellung
+- Konfiguration in beiden Beispieldateien dokumentiert
+
+### Konfiguration und Dokumentation
+
+- `config/application-local.example.properties`: vollständig, alle Pflicht- und
+  Optionalparameter vorhanden
+- `config/application-test.example.properties`: vollständig
+- `config/prompts/template.txt`: Prompt-Template im Repository vorhanden
+- `docs/betrieb.md`: Betriebsdokumentation mit Start, Konfiguration, Exit-Codes,
+  Retry-Grundverhalten, Logging-Sensibilität
+- Konfigurationsparameter-Namen in Dokumentation und Code konsistent
+
+### Exit-Code-Semantik
+
+- Exit-Code `0`: technisch ordnungsgemäßer Lauf (auch bei Teilfehlern einzelner Dokumente)
+- Exit-Code `1`: harte Start-/Bootstrap-Fehler, ungültige Konfiguration, Lock-Fehler
+- Implementierung in `PdfUmbenennerApplication` und `BootstrapRunner` korrekt
+
+### PIT-Mutationsanalyse (Gesamtstand)
+
+- Domain: 83 % Mutation Kill Rate
+- Adapter-out: 83 % Mutation Kill Rate
+- Application: 87 % Test Strength
+- Bootstrap: 76 % Kill Rate (34 Mutationen, 26 getötet)
+
+---
+
+## Abgeschlossene Punkte
+
+### B1 – Naming-Convention-Verletzungen in Code, Tests und Konfiguration (CLAUDE.md § Naming-Regel)
+
+**Themenbereich:** Dokumentation / Codequalität  
+**Norm:** CLAUDE.md verbietet explizit Meilenstein- (M1–M8) und Arbeitspaket-Bezeichner (AP-xxx)
+in Implementierungen, Kommentaren und JavaDoc.  
+**Status:** **BEHOBEN** – alle 43 Treffer in `.java`-Dateien sowie der Kommentarheader in
+`config/application.properties` wurden durch zeitlose technische Formulierungen ersetzt.
+
+---
+
+## Dokumentierte Randpunkte (kein Handlungsbedarf, freigabekompatibel)
+
+#### B2 – StartConfiguration in Application-Schicht enthält java.nio.file.Path (Architektur-Grenzfall)
+
+**Themenbereich:** Architektur  
+**Norm:** „Application orchestriert Use Cases und enthält keine technischen
+Implementierungsdetails" (technik-und-architektur.md §3.1); Port-Verträge dürfen keine
+NIO-Typen enthalten (CLAUDE.md).  
+**Befund:** `StartConfiguration` (in `application/config/startup/`) ist ein Java-Record
+mit `java.nio.file.Path`-Feldern für `sourceFolder`, `targetFolder`, `sqliteFile`,
+`promptTemplateFile`, `runtimeLockFile`, `logDirectory`.  
+**Kontext:** `StartConfiguration` ist kein Port-Vertrag, sondern ein unveränderliches
+Konfigurations-DTO, das ausschließlich von Bootstrap erzeugt und an Adapter übergeben wird.
+Die Port-Verträge selbst sind sauber (keine Path-Typen in Port-Interfaces).  
+**Bewertung:** Grenzfall. `Path` ist kein fachliches Objekt, aber auch kein schwerer
+Architekturverstoß in diesem Kontext. Die Alternative (String-Repräsentation und Auflösung
+im Adapter) hätte keinen Mehrwert für das Betriebsmodell.  
+**Entscheidung:** Kein Handlungsbedarf. Das Verschieben von `StartConfiguration` in das
+Bootstrap-Modul wäre eine Option, ist aber keine Pflicht, da kein funktionaler Defekt vorliegt.
+
+---
+
+#### B3 – PIT-Überlebende in Bootstrap (Bootstrap: 76 % Kill Rate)
+
+**Themenbereich:** Testqualität  
+**Befund:** 8 überlebende Mutanten im Bootstrap-Modul (34 generiert, 26 getötet).
+Hauptkategorie: `VoidMethodCallMutator` (2 Überlebende, 2 ohne Coverage).  
+**Bewertung:** Betrifft vor allem Logging-Calls und nicht-kritische Hilfsmethoden.
+Keine funktional tragenden Entscheidungspfade betroffen.  
+**Entscheidung:** Kein Handlungsbedarf. Betrifft vor allem Logging-Calls und nicht-kritische
+Hilfsmethoden. Wurde auf akzeptablem Niveau konsolidiert.
+
+---
+
+## Zusammenfassung und Freigabe
+
+| Klassifikation | Anzahl | Beschreibung |
+|---|---|---|
+| Release-Blocker | **0** | – |
+| Abgeschlossen (war nicht blockierend) | **1** | B1 Naming-Convention-Bereinigung |
+| Dokumentierte Randpunkte (freigabekompatibel) | **2** | B2 Path-Grenzfall, B3 PIT-Bootstrap |
+
+**Freigabeentscheidung: Der Endstand ist produktionsbereit und freigegeben.**
+
+Alle fachlichen, technischen und architekturellen Kernanforderungen aus den verbindlichen
+Spezifikationen (technik-und-architektur.md, fachliche-anforderungen.md, CLAUDE.md) sind
+vollständig umgesetzt und durch automatisierte Tests abgesichert. Der Maven-Build ist fehlerfrei.
+Die CLAUDE.md-Naming-Convention-Regel (kein M1–M8, kein AP-xxx im Produktions- oder Testcode)
+ist vollständig eingehalten. Keine bekannten spezifikationsrelevanten Blocker sind offen.
+
+---
+
+# V2.0-Gesamtstand – Integrierte Prüfung (Stand 2026-04-20)
+
+**Prüfgrundlage:** Vollständiger Maven-Reactor-Build mit allen Tests (clean verify, `-DskipPitest=true`),
+Code-Review gegen die verbindliche Spec-Trias (technik-und-architektur.md, fachliche-anforderungen.md,
+CLAUDE.md), Sichtprüfung Dokumentation und Konfigurationsbeispiele.
+
+---
+
+## Build- und Testergebnisse
+
+**Ausgeführtes Kommando:**
+```
+.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-adapter-in-gui,pdf-umbenenner-bootstrap --also-make -DskipPitest=true
+```
+
+**Gesamtergebnis: BUILD SUCCESS**  
+**Gesamtlaufzeit:** 01:18 min  
+**Datum:** 2026-04-20
+
+| Modul | Tests | Failures | Errors | Skipped |
+|---|---|---|---|---|
+| `pdf-umbenenner-domain` | 227 | 0 | 0 | 0 |
+| `pdf-umbenenner-application` | 455 | 0 | 0 | 0 |
+| `pdf-umbenenner-adapter-in-cli` | 8 | 0 | 0 | 0 |
+| `pdf-umbenenner-adapter-in-gui` | 190 | 0 | 0 | 0 |
+| `pdf-umbenenner-adapter-out` | 371 | 0 | 0 | 0 |
+| `pdf-umbenenner-bootstrap` | 147 | 0 | 0 | 0 |
+| **Gesamt** | **1.398** | **0** | **0** | **0** |
+
+Alle Module bauen erfolgreich. Alle Tests bestehen. Das ausführbare Shade-JAR wird erzeugt und
+enthält JavaFX (Win-Classifier), alle Module, PDFBox, SQLite-JDBC und Log4j2.
+
+**Warnungen im Build:**
+- `WARNING: A Java agent has been loaded dynamically (byte-buddy-agent)` – dies ist ein bekannter
+  Mockito/ByteBuddy-Hinweis, der in Tests auftritt. Kein funktionaler Defekt. Tritt seit V1.1 auf
+  und gilt als akzeptiert.
+
+---
+
+## Prüfpunkte gegen die V2.0-Spezifikation (1–20)
+
+| Nr. | Prüfpunkt | Status | Begründung |
+|---|---|---|---|
+| 1 | GUI ist Standardstart | **erfüllt** | `PdfUmbenennerApplication.main()` → `BootstrapRunner.run()` → `StartupMode.GUI` als Default; `--headless` erforderlich für Batch-Pfad. Korrekt implementiert und getestet (`BootstrapRunnerStartupDispatchTest`). |
+| 2 | `--headless` erhalten, `--config` für beide Startarten | **erfüllt** | `CliArgumentParser` parst beide Optionen korrekt. `BootstrapRunnerConfigPathSemanticsTest` (10 Tests) prüft GUI/headless-Semantik für vorhandene und fehlende `--config`-Pfade. |
+| 3 | `.properties` als einzige Konfigurationswahrheit | **erfüllt** | `PropertiesConfigurationPortAdapter` und `GuiConfigurationPropertiesWriter` schreiben/lesen ausschließlich `.properties`. Keine zweite Konfigurationswelt. |
+| 4 | Zwei Provider (Claude, OpenAI-kompatibel), genau einer aktiv | **erfüllt** | `AiProviderSelector` wählt anhand `ai.provider.active`. `AiModelCatalogDispatcher` unterstützt beide Familien. Konfigurationsbeispiel zeigt beide Blöcke. Provider-Identifikator in Versuchshistorie persistiert (`ProviderIdentifierE2ETest`, 5 Tests). |
+| 5 | Hexagonale Architektur (keine JavaFX in Domain/Application) | **erfüllt** | Grep-Prüfung: kein `import javafx` in `domain` oder `application`. `adapter-in-cli` und `adapter-out` ebenfalls JavaFX-frei. JavaFX ausschließlich in `adapter-in-gui`. |
+| 6 | Threadingmodell (Worker für I/O, Platform.runLater für UI) | **erfüllt** | `GuiConfigurationEditorWorkspace`, `GuiModelCatalogCoordinator`, `GuiCorrectionDialogCoordinator`, `GuiTechnicalTestCoordinator` nutzen alle explizit `Platform.runLater` für UI-Updates. Worker-Thread-Trennung ist im Code nachweisbar. |
+| 7 | Naming-Regel (keine M/AP/V-Bezeichner in Code) | **erfüllt** | Grep auf `M[0-9]+`, `AP-[0-9]+`, `V[12]\.[0-9]` in allen `src/main/java` und `src/test/java` liefert keine Treffer für neue V2.0-Module (`adapter-in-gui`, `bootstrap`-Erweiterungen). |
+| 8 | JavaDoc-Standard | **erfüllt** | Alle neu hinzugefügten öffentlichen Klassen und Methoden haben Klassen- und Methoden-JavaDoc. `BootstrapRunner` und `PdfUmbenennerApplication` vollständig dokumentiert. `package-info.java` vorhanden in neuen Packages. |
+| 9 | Dirty-State, Schutzdialog, Validierung, technische Tests | **erfüllt** | `GuiDirtyStateTest`, `GuiUnsavedChangesGuardSmokeTest`, `GuiValidateActionSmokeTest`, `GuiTechnicalTestCoordinatorSmokeTest` belegen die Kernpfade. `GuiUnsavedChangesGuard` kapselt die Dirty-State-Logik. |
+| 10 | Meldungsbereich mit vier Stufen, feldnahe Fehlermeldungen | **erfüllt** | `GuiMessageSeverity` (INFO, HINWEIS, WARNUNG, FEHLER), `GuiMessageEntry` und `GuiFieldFinding` implementieren die Anforderungen. `GuiMessageAreaSmokeTest` und `GuiMessageEntryTest` prüfen sie. |
+| 11 | Modellabruf, Manueller Modellfallback, Verwerfen-Regel | **erfüllt** | `GuiModelCatalogCoordinator` implementiert automatischen Abruf bei Providerwechsel, ComboBox vs. Textfeld-Umschaltung, und Verwerfen-Regel bei Listenwechsel. `GuiModelCatalogSmokeTest` prüft die Kernpfade. |
+| 12 | Korrekturhilfen mit gesammeltem Bestätigungsdialog | **erfüllt** | `GuiCorrectionDialogCoordinator` sammelt Korrekturen und steuert den Bestätigungsdialog. `ConfirmationDialogContent` kapselt die Dialog-Inhalte. `GuiCorrectionDialogCoordinatorSmokeTest` prüft den Ablauf. |
+| 13 | Automatische Prompt-Erzeugung | **erfüllt** | `DefaultPromptTemplate.defaultContent()` in `application`-Schicht; `FilesystemResourceCreationAdapter` erzeugt die Datei. `DefaultPromptTemplateTest` und `FilesystemResourceCreationAdapterTest` prüfen Inhalt und Erzeugung. Beispiel in `docs/examples/prompt.txt` konsistent. |
+| 14 | Windows-Pfade und gemappte Laufwerke | **erfüllt** | `FilesystemPathCheckAdapter` akzeptiert Windows-Laufwerksbuchstaben. `FilesystemPathCheckAdapterTest` (28 Tests) enthält Windows-Pfad-Szenarien. Dokumentation in `betrieb.md` und `gui-bedienanleitung.md` ausdrücklich erwähnt. |
+| 15 | Legacy-Migration mit `.bak`-Sicherung | **erfüllt** | `LegacyConfigurationMigrator` in `adapter-out`; GUI-Pfad ruft `detectedLegacyConfiguration` + `migrateConfigurationIfNeeded` in `BootstrapRunner` auf. `GuiConfigurationPropertiesWriterTest` prüft Backup-Schema. |
+| 16 | Keine neuen Provider über Claude/OpenAI-kompatibel hinaus | **erfüllt** | Codebase enthält ausschließlich `ClaudeAiInvocationAdapter` und `OpenAiCompatibleAiInvocationAdapter`. Kein dritter Provider. |
+| 17 | Keine neuen Distributionsformate (EXE/Installer) | **erfüllt** | `pom.xml` des Bootstrap-Moduls nutzt ausschließlich `maven-shade-plugin`. Kein `launch4j`, kein `jpackage`, kein Installer. |
+| 18 | Kein manueller Verarbeitungslauf aus GUI (abgelöst ab V2.1) | **erfüllt** | `adapter-in-gui` enthält keine Klasse, die `BatchRunProcessingUseCase` aus einem GUI-Event aufruft. Kein „Start"-Button, keine Batch-Ausführungslogik im GUI-Adapter. |
+| 19 | Keine DB-/Historienanzeige | **erfüllt** | Kein SQLite-Lesepfad aus `adapter-in-gui`. Kein Historien-Tab. Kein Ergebnis-Browser. |
+| 20 | Keine fachlichen Änderungen an Kernverarbeitung | **erfüllt** | `DefaultBatchRunProcessingUseCase`, `DocumentProcessingCoordinator`, `AiNamingService`, `AiResponseValidator` sind gegenüber dem V1.1-Freigabestand unverändert. E2E-Tests (`BatchRunEndToEndTest`, 11 Szenarien) sind alle grün. |
+
+---
+
+## Dokumentations-Vollständigkeitsprüfung
+
+| Dokument | Status | Bewertung |
+|---|---|---|
+| `docs/betrieb.md` | vollständig | Alle V2.0-Themen abgedeckt: GUI-Standardstart, `--headless`, `--config`-Semantik für beide Modi, Plattformhinweis Windows, gemappte Laufwerke, GUI-Umfangsbegrenzung, Build- und Packaging-Abschnitt, JavaFX-Integration, headless ohne JavaFX-Initialisierung |
+| `docs/gui-bedienanleitung.md` | vollständig | Alle AP-002-Themen abgedeckt: Startzustände (Abschnitte 2.1–2.4), alle 7 Aktionen (Abschnitte 4.1–4.7), vier Meldungsstufen (Abschnitt 3.2), feldnahe Fehlermeldungen (Abschnitt 5), Provider-Bedienung und Modellabruf (Abschnitt 7), API-Key-Auflösungsreihenfolge (Abschnitt 10), Dirty-State (Abschnitt 8), `.bak`-Sicherung und Legacy-Migration (Abschnitt 9), Windows-Hinweise (Abschnitt 12), bekannte Einschränkungen (Abschnitt 13) |
+| `docs/examples/application.properties` | vollständig und konsistent | Alle Parameter des V2.0-Schemas vorhanden (beide Provider-Blöcke, alle Pflicht- und Optionalparameter). Kommentare zu Warnschwellen für `max.text.characters` enthalten. Default-Provider `claude` gesetzt (alphabetisch erster). Konsistent mit `GuiConfigurationTemplateFactory`. |
+| `docs/examples/prompt.txt` | vollständig und konsistent | Deutschsprachiger Standardprompt. Inhaltlich identisch mit dem, was `DefaultPromptTemplate.defaultContent()` erzeugt (durch `FilesystemResourceCreationAdapterTest` nachgewiesen). JSON-Schema-Anforderungen (title, reasoning, date optional) abgebildet. |
+| `README.md` | vollständig | V2.0-Hinweis im Header, GUI-Standardstart dokumentiert, `--headless` und `--config`-Beispiele vorhanden, Modul `pdf-umbenenner-adapter-in-gui` aufgelistet, Verweis auf `betrieb.md` und `gui-bedienanleitung.md`. |
+
+---
+
+## Release-Blocker
+
+**Keine Release-Blocker identifiziert.**
+
+Der vollständige Maven-Reactor-Build ist grün (1.398 Tests, 0 Failures, 0 Errors, 0 Skipped).
+Alle 20 Prüfpunkte gegen die Spec-Trias sind als erfüllt bewertet. Die Dokumentation ist
+vollständig und konsistent mit dem Code.
+
+---
+
+## Nicht blockierende Restpunkte
+
+#### R1 – ByteBuddy-Agent-Warnung bei Tests
+
+**Thema:** Testqualität / Laufzeitwarnung  
+**Befund:** Beim Build erscheint wiederholt `WARNING: A Java agent has been loaded dynamically
+(byte-buddy-agent-1.14.12.jar)`. Der Hinweis stammt von Mockito und tritt seit dem V1.1-Stand auf.
+Er ist nicht neu, betrifft nur die Testlaufzeit und hat keinen funktionalen Einfluss auf das
+produzierte Artefakt.  
+**Bewertung:** Kein Handlungsbedarf. Mit `-XX:+EnableDynamicAgentLoading` unterdrückbar, aber
+keine Pflicht für V2.0.
+
+#### R2 – GUI-Tests ohne echten JavaFX-Rendering-Pfad
+
+**Thema:** Testtiefe GUI  
+**Befund:** Die GUI-Tests (`GuiAdapterSmokeTest`, `GuiEditorRegressionSmokeTest` usw.) laufen
+unter headless JavaFX (Monocle) und prüfen View-Modell-Logik, Zustandsübergänge und
+Koordinatoren-Verhalten. Das visuelle Rendering der Oberfläche (Farbgebung der Meldungspräfixe,
+Layout-Details) ist nicht automatisiert geprüft. Dies entspricht der in CLAUDE.md definierten
+GUI-Teststrategie (kein TestFX über Monocle hinaus) und ist keine Abweichung vom Ziel.  
+**Bewertung:** Kein Handlungsbedarf. Entspricht der Teststrategie-Vorgabe.
+
+---
+
+## Bewusst außerhalb V2.0 liegende Themen (V2.1+)
+
+Die folgenden Themen wurden im V2.0-Umfang nachweislich **nicht** implementiert und sind
+ausdrücklich für spätere Ausbaustufen vorgesehen:
+
+- **Manueller Verarbeitungslauf aus der GUI** (V2.1+) – **umgesetzt ab V2.1** (Tab „Verarbeitungslauf")
+- **DB-/Historienansicht** in der GUI (V2.x+)
+- **Kosten-Tracking** und Token-/Preisberechnung (V2.x+)
+- **EXE-Wrapper / Installer** (V3+) – **umgesetzt ab V3**: EXE-Wrapper (M14), MSI-Installer (M15)
+- **Weitere KI-Provider** über Claude und OpenAI-kompatibel hinaus (V3+)
+- **Automatischer Fallback zwischen Providern** (V3+)
+- **Profilverwaltung mit mehreren Konfigurationen je Provider** (V3+)
+- **Plattformübergreifender offizieller GUI-Support** (V3+)
+
+---
+
+## Gesamtbewertung V2.0-Stand
+
+| Klassifikation | Anzahl | Beschreibung |
+|---|---|---|
+| Release-Blocker | **0** | – |
+| Nicht blockierende Restpunkte | **2** | R1 ByteBuddy-Warnung, R2 Testtiefe GUI-Rendering |
+| Bewusst außerhalb V2.0 | **8** | Manueller Lauf, Historienansicht, Kosten-Tracking, EXE, weitere Provider, Fallback, Profile, Cross-Platform |
+
+**Build:** ERFOLGREICH · 1.398 Tests · 0 Failures · 0 Errors · Laufzeit 01:18 min  
+**Alle 20 Spezifikations-Prüfpunkte:** erfüllt  
+**Dokumentation:** vollständig und konsistent
+
+---
+
+# V2.9-Fixes (Stand 2026-04-24)
+
+Die folgenden Issues wurden nach dem V2.0-Abschluss behoben und sind im aktuellen Stand integriert.
+
+| Issue | Titel | Status |
+|---|---|---|
+| #27 | Mausrad-Seitenwechsel und zuverlässiger Seitenanfang in PDF-Vorschau | **behoben** |
+| #28 | Anwendung standardmäßig im Vollbild starten | **behoben** |
+| #29 | Eigenes PDF-Rendering mit PDFBox statt PDFViewFX | **behoben** |
+| #33 | Letzte Konfigurationsdatei beim Neustart automatisch laden | **behoben** |
+
+### Beschreibung der Fixes
+
+**#27 / #29 – PDF-Vorschau-Stabilität und PDFBox-Migration:**
+Mehrere aufeinanderfolgende Fixes stabilisierten die PDF-Vorschau. Zunächst wurden
+Scroll-Schutz und zuverlässiger Seitenanfang per ImageView-Listener verbessert.
+Im letzten Schritt (#29) wurde die externe PDFViewFX-Abhängigkeit vollständig
+durch direktes Rendering via `PDFRenderer.renderImageWithDPI` (Apache PDFBox, 120 DPI)
+ersetzt. Lazy Rendering mit In-Memory-Cache und das „latest preview request wins"-Prinzip
+blieben erhalten.
+
+**#28 – Vollbild-Start:**
+`stage.setMaximized(true)` in `PdfUmbenennerGuiApplication.start()` sorgt dafür, dass
+das Fenster beim Start automatisch maximiert wird.
+
+**#33 – Letzte Konfiguration automatisch laden:**
+`GuiConfigurationEditorWorkspace` speichert den Pfad einer erfolgreich geladenen
+Konfigurationsdatei in `java.util.prefs.Preferences` (Schlüssel `lastConfigPath`).
+Beim nächsten Start wird diese Datei automatisch geladen, sofern sie noch existiert.
+Fehlt die Datei, startet die GUI ohne Fehlermeldung mit dem Willkommenstext.
+
+---
+
+> **Hinweis:** Für die Ausbaustufen V2.1 bis V2.9 wurden keine separaten Befundlisteneinträge
+> erstellt. Befunde, Fixes und Verbesserungen dieser Stufen sind in den Gitea-Issues dokumentiert.
@@ -0,0 +1,820 @@
+# Betriebsdokumentation – PDF Umbenenner
+
+## Zweck
+
+Der PDF Umbenenner liest bereits OCR-verarbeitete, durchsuchbare PDF-Dateien aus einem
+konfigurierten Quellordner, ermittelt per KI-Aufruf einen normierten deutschen Dateinamen
+und legt eine Kopie im konfigurierten Zielordner ab. Die Quelldatei bleibt unverändert.
+
+---
+
+## Startmodi und Betriebsmodell (V2.0)
+
+Ab V2.0 enthält die Anwendung zwei Startmodi in **einem gemeinsamen ausführbaren JAR**:
+
+| Startmodus | Beschreibung |
+|---|---|
+| **GUI-Start** (Standard) | Öffnet die JavaFX-Desktop-GUI. Wird verwendet, wenn kein `--headless` angegeben ist. |
+| **headless Betrieb** | Klassischer Batch-/Scheduler-Betrieb ohne grafische Oberfläche. Wird über `--headless` aktiviert. |
+
+### CLI-Optionen
+
+| Option | Beschreibung |
+|---|---|
+| *(keine Argumente)* | GUI-Standardstart |
+| `--headless` | Aktiviert den headless Batch-Betrieb (wie vor V2.0) |
+| `--config <pfad>` | Zeigt explizit auf eine `.properties`-Konfigurationsdatei (für GUI und headless) |
+
+`--config` und `--headless` können kombiniert werden:
+
+```
+java -jar pdf-umbenenner-bootstrap-*.jar --headless --config C:\Pfad\zur\config.properties
+```
+
+### Verhalten bei fehlender oder ungültiger `--config`-Datei
+
+| Startmodus | Datei nicht vorhanden | Datei vorhanden, aber ungültig |
+|---|---|---|
+| **headless** | Harter Startfehler, Exit-Code `1`, kein Fallback | Harter Startfehler, Exit-Code `1` |
+| **GUI** | Fehlermeldung in der GUI, danach Verhalten wie ohne `--config` (Willkommenstext) | Fehlermeldung in der GUI, Konfiguration nicht geladen |
+
+Im headless Betrieb ist ein nicht vorhandener `--config`-Pfad ein **harter Startfehler**. Ein stiller
+Fallback auf das Default-Verhalten ist in diesem Fall ausdrücklich unzulässig.
+
+### Verhalten bei GUI-Startfehlern
+
+Tritt vor der erfolgreichen Anzeige der grafischen Oberfläche ein nicht behebbarer Fehler auf
+(z. B. fehlende JavaFX-Laufzeit, Bootstrap-Fehler), beendet sich die Anwendung mit Exit-Code `1`.
+
+### Plattform und Laufwerksbuchstaben
+
+Die GUI wird **offiziell nur unter Windows** unterstützt. Der headless Betrieb bleibt für den
+Windows Server-Betrieb geeignet.
+
+Gemappte Netzlaufwerke wie `S:\` oder `H:\` werden ausdrücklich unterstützt. Eine Ablehnung
+solcher Pfade allein wegen eines dahinterliegenden UNC-Pfads ist unzulässig.
+
+### Startverhalten der GUI
+
+Die GUI startet **maximiert** (Vollbild). Beim Start wird die zuletzt geladene
+Konfigurationsdatei automatisch geladen. Der Pfad wird in den Windows-Benutzereinstellungen
+gespeichert (`java.util.prefs.Preferences`). Existiert die Datei beim nächsten Start nicht
+mehr, startet die GUI ohne Fehlermeldung mit dem Willkommenstext.
+
+### Umfang der GUI
+
+Die GUI enthält fünf Tabs:
+
+- **Tab „Konfiguration"** – Editor, Validierungs- und technische Testoberfläche für
+  die `.properties`-Datei (Erreichbarkeit des Providers, Pfade, SQLite-Datei,
+  Prompt-Datei).
+- **Tab „Verarbeitungslauf"** – Start eines Batch-Laufs aus der GUI mit
+  Live-Fortschritt, Ergebnisliste und KI-Begründung je Dokument. Pro Zeile ist eine
+  **integrierte PDF-Vorschau** der Quelldatei sowie ein **editierbarer Dateiname-Bereich**
+  verfügbar. Der Lauf verwendet den zuletzt gespeicherten Stand der `.properties`-Datei;
+  ungespeicherte Änderungen im Editor fließen nicht in den Lauf ein. Ein **Soft-Stop**
+  über den Abbrechen-Knopf beendet den Lauf nach Abschluss der gerade bearbeiteten Datei.
+  Während eines laufenden Batches ist Tab 1 gesperrt; ein Hinweis weist darauf hin.
+- **Tab „Scheduler"** – Optionaler automatischer Scheduler für periodische Verarbeitungsläufe.
+  Kann gestartet, gestoppt und mit einem konfigurierten Intervall betrieben werden. Während
+  der Scheduler aktiv ist, sind Tab 1 „Konfiguration" und der manuelle Lauf gesperrt.
+  Erfordert `scheduler.enabled=true` und ein gültiges `scheduler.interval.seconds` in der
+  gespeicherten Konfiguration.
+- **Tab „Verlauf"** – Ansicht aller bisher verarbeiteten Dokumente mit Status, Dateinamen
+  und Verarbeitungsdetails direkt aus der SQLite-Datenbank. Ermöglicht Status-Reset und
+  Löschung einzelner Einträge.
+- **Tab „Prompt"** – Lädt, bearbeitet und speichert die konfigurierte Prompt-Datei direkt
+  aus der Oberfläche. Bearbeitungen erzeugen einen Dirty-State (Asterisk im Tab-Titel).
+  Speichern erfolgt **atomar** (Temp-Datei im selben Verzeichnis + `ATOMIC_MOVE`).
+  Ein „Auf Standard zurücksetzen"-Button befüllt die TextArea mit der Standard-Vorlage,
+  ohne zu speichern. Fehlt die Prompt-Datei am konfigurierten Pfad, wird ein
+  „Standard-Prompt erstellen"-Button angezeigt. Der Tab wird beim ersten Öffnen automatisch
+  geladen. Tab-Wechsel mit ungespeicherten Änderungen löst einen Bestätigungsdialog aus.
+
+Der headless Betrieb über den Windows Task Scheduler bleibt unverändert bestehen und
+kann weiterhin für automatisierte Läufe genutzt werden. Pro Anwendungsinstanz ist genau
+ein Verarbeitungslauf gleichzeitig zulässig; ein gleichzeitiger externer headless Lauf
+wird jedoch nicht technisch erkannt oder blockiert.
+
+### Automatischer Scheduler
+
+Der GUI-Tab „Scheduler" ermöglicht den Betrieb eines optionalen, periodisch laufenden
+Schedulers, der automatisch Verarbeitungsläufe anstößt.
+
+**Konfigurationsparameter:**
+
+| Parameter | Beschreibung | Standard |
+|---|---|---|
+| `scheduler.enabled` | Scheduler im GUI-Modus aktivieren (`true`/`false`); wird im headless Betrieb ignoriert | `false` |
+| `scheduler.interval.seconds` | Intervall zwischen automatischen Läufen in Sekunden (Integer >= 30; Pflicht wenn `scheduler.enabled=true`); wird im headless Betrieb ignoriert | – |
+
+Ungültige Werte (kein Integer, < 30 oder leer bei `scheduler.enabled=true`) verhindern den
+Scheduler-Start und werden im GUI-Tab als Fehler gemeldet.
+
+**Autostart:** Ist `scheduler.enabled=true` in der gespeicherten Konfiguration, startet der
+Scheduler automatisch, wenn die Konfiguration beim GUI-Start geladen wird. Der erste
+Verarbeitungslauf beginnt **unmittelbar** nach dem Scheduler-Start (kein initiales Warten).
+
+**Headless-Betrieb:** Im headless Betrieb werden `scheduler.enabled` und
+`scheduler.interval.seconds` vollständig ignoriert. Der Scheduler ist ausschließlich im
+GUI-Modus verfügbar.
+
+**Sperrverhalten:** Solange der Scheduler aktiv ist, ist Tab 1 „Konfiguration" gesperrt
+(Bearbeitungssperre mit Hinweisbanner). Manuelles Starten eines Laufs ist ebenfalls nicht
+möglich. Nach dem Stoppen des Schedulers werden beide Sperren automatisch aufgehoben.
+
+**Schließen der Anwendung:** Versucht der Benutzer das Fenster zu schließen, während der
+Scheduler aktiv ist oder ein Lauf läuft, erscheint ein Informationsdialog. Das Schließen
+wird blockiert, bis der Scheduler gestoppt und kein Lauf mehr aktiv ist.
+
+---
+
+## Voraussetzungen
+
+- Zugang zu einem KI-Dienst (API-Schlüssel erforderlich; unterstützte Provider: OpenAI-kompatibel, Anthropic Claude)
+- Quellordner mit OCR-verarbeiteten PDF-Dateien
+- Schreibzugriff auf Zielordner und Datenbankverzeichnis
+
+### Java-Laufzeitumgebung
+
+- Bei Verwendung des **Shade-JAR** direkt: **Java 21 JRE** auf dem Zielsystem erforderlich.
+- Bei Verwendung des **Windows-Installers (V3.0)**: **keine** separate Java-Installation notwendig –
+  die JRE 21 ist in der installierten Anwendung eingebettet.
+
+---
+
+## Start des ausführbaren JAR
+
+Das ausführbare JAR wird durch den Maven-Build im Verzeichnis
+`pdf-umbenenner-bootstrap/target/` erzeugt:
+
+```
+java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar
+```
+
+Ohne weitere Argumente öffnet sich die **GUI** (Standardstart ab V2.0).
+
+Für den **headless Betrieb** (Batch-/Scheduler-Start):
+
+```
+java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --headless
+```
+
+Die Anwendung liest die Konfiguration standardmäßig aus `config/application.properties` relativ zum
+Arbeitsverzeichnis, in dem der Befehl ausgeführt wird.
+
+### Konsolen-Encoding unter Windows
+
+Die Anwendung schreibt alle Log-Ausgaben in UTF-8. Windows-Konsolen (PowerShell, CMD) verwenden
+standardmäßig den OEM-Codepage (z. B. CP850), was zu unlesbaren Sonderzeichen führt.
+
+**Lösung:** Konsole vor dem Start auf UTF-8 umschalten:
+
+```
+chcp 65001
+java -jar pdf-umbenenner-bootstrap-*.jar --headless
+```
+
+Alternativ kann die UTF-8-Ausgabe auch als JVM-Argument angegeben werden (Java 17+):
+
+```
+java -Dstdout.encoding=UTF-8 -jar pdf-umbenenner-bootstrap-*.jar --headless
+```
+
+> **Hinweis:** Die mitgelieferten Batch-Dateien (`PDF-KI-Renamer.bat`, `PDF-KI-Renamer-GUI.bat`)
+> rufen `chcp 65001` automatisch auf. Der Windows Task Scheduler schreibt Log-Ausgaben in eine
+> Protokolldatei, die stets UTF-8-kodiert ist – dort entsteht kein Anzeigeproblem.
+
+### Start über Windows Task Scheduler
+
+Empfohlene Startsequenz für den headless Betrieb über den Windows Task Scheduler:
+
+1. Aktion: Programm/Skript starten
+2. Programm: `java`
+3. Argumente: `-jar C:\Pfad\zur\Installation\pdf-umbenenner-bootstrap\target\pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --headless`
+4. Starten in: `C:\Pfad\zur\Installation` (muss das Verzeichnis mit `config\application.properties` und `config\prompts\` enthalten)
+
+> **Hinweis:** Das „Starten in"-Verzeichnis ist das Arbeitsverzeichnis der Anwendung.
+> Die Konfigurationsdatei `config/application.properties` sowie das Prompt-Verzeichnis
+> `config/prompts/` müssen relativ zu diesem Verzeichnis erreichbar sein. Der JAR-Pfad
+> in den Argumenten muss absolut oder relativ zum Starten-in-Verzeichnis korrekt angegeben sein.
+
+Alternativ kann über `--config` ein expliziter Konfigurationspfad angegeben werden:
+
+```
+java -jar ... --headless --config S:\Betrieb\meine-config.properties
+```
+
+> **Wichtig:** Zeigt `--config` auf eine nicht vorhandene Datei, bricht die Anwendung mit Exit-Code `1` ab.
+> Es findet kein stiller Fallback auf `config/application.properties` statt.
+
+---
+
+## Konfiguration
+
+Die Konfiguration wird aus `config/application.properties` geladen.
+
+Ein vollständiges Konfigurationsbeispiel mit allen unterstützten Parametern,
+realistischen Windows-Pfaden und erklärenden Kommentaren liegt unter:
+
+- [`docs/examples/application.properties`](examples/application.properties)
+
+Vorlagen für lokale und Test-Konfigurationen befinden sich in:
+
+- `config/application-local.example.properties`
+- `config/application-test.example.properties`
+
+### Pflichtparameter (allgemein)
+
+| Parameter               | Beschreibung |
+|-------------------------|--------------|
+| `source.folder`         | Quellordner mit OCR-PDFs (muss vorhanden und lesbar sein) |
+| `target.folder`         | Zielordner für umbenannte Kopien (wird angelegt, wenn nicht vorhanden) |
+| `sqlite.file`           | SQLite-Datenbankdatei (übergeordnetes Verzeichnis muss existieren) |
+| `ai.provider.active`    | Aktiver KI-Provider: `openai-compatible` oder `claude` |
+| `max.retries.transient` | Maximale transiente Fehlversuche pro Dokument (ganzzahlig, >= 1) |
+| `max.pages`             | Maximale Seitenzahl pro Dokument (ganzzahlig, > 0) |
+| `max.text.characters`   | Maximale Zeichenanzahl des Dokumenttexts für KI-Anfragen (ganzzahlig, > 0) |
+| `max.title.length`      | Maximale Länge des Basistitels in Zeichen (ganzzahlig, 10..120, Default 60). Werte unter 10 oder über 120 verhindern den Start. Werte 10–39 und 100–120 erzeugen eine Startwarnung. |
+| `prompt.template.file`  | Pfad zur externen Prompt-Datei (muss vorhanden sein) |
+
+### Provider-Parameter
+
+Nur der **aktive** Provider muss vollständig konfiguriert sein. Der inaktive Provider wird nicht validiert.
+
+**OpenAI-kompatibler Provider** (`ai.provider.active=openai-compatible`):
+
+| Parameter | Beschreibung |
+|-----------|--------------|
+| `ai.provider.openai-compatible.baseUrl` | Basis-URL des KI-Dienstes (z. B. `https://api.openai.com/v1`) |
+| `ai.provider.openai-compatible.model` | Modellname (z. B. `gpt-4o-mini`) |
+| `ai.provider.openai-compatible.timeoutSeconds` | HTTP-Timeout in Sekunden (ganzzahlig, > 0) |
+| `ai.provider.openai-compatible.apiKey` | API-Schlüssel (Umgebungsvariable `OPENAI_COMPATIBLE_API_KEY` hat Vorrang) |
+
+**Anthropic Claude-Provider** (`ai.provider.active=claude`):
+
+| Parameter | Beschreibung |
+|-----------|--------------|
+| `ai.provider.claude.baseUrl` | Basis-URL (optional; Standard: `https://api.anthropic.com`) |
+| `ai.provider.claude.model` | Modellname (z. B. `claude-3-5-sonnet-20241022`) |
+| `ai.provider.claude.timeoutSeconds` | HTTP-Timeout in Sekunden (ganzzahlig, > 0) |
+| `ai.provider.claude.apiKey` | API-Schlüssel (Umgebungsvariable `ANTHROPIC_API_KEY` hat Vorrang) |
+
+### Optionale Parameter
+
+| Parameter           | Beschreibung | Standard |
+|---------------------|--------------|---------|
+| `runtime.lock.file` | Lock-Datei für Startschutz | `pdf-umbenenner.lock` im Arbeitsverzeichnis |
+| `log.directory`     | Log-Verzeichnis | `./logs/` |
+| `log.level`         | Log-Level (`DEBUG`, `INFO`, `WARN`, `ERROR`) | `INFO` |
+| `log.ai.sensitive`  | KI-Rohantwort und Reasoning ins Log schreiben (`true`/`false`) | `false` |
+| `scheduler.enabled` | Scheduler im GUI-Modus aktivieren (`true`/`false`); wird im headless Betrieb ignoriert | `false` |
+| `scheduler.interval.seconds` | Intervall in Sekunden (Integer >= 30; Pflicht wenn `scheduler.enabled=true`); wird im headless Betrieb ignoriert | – |
+
+### API-Schlüssel
+
+Pro Provider-Familie existiert eine eigene Umgebungsvariable, die Vorrang vor dem Properties-Wert hat:
+
+| Provider | Umgebungsvariable |
+|---|---|
+| `openai-compatible` | `OPENAI_COMPATIBLE_API_KEY` |
+| `claude` | `ANTHROPIC_API_KEY` |
+
+Schlüssel verschiedener Provider-Familien werden niemals vermischt.
+
+---
+
+## Migration älterer Konfigurationsdateien
+
+Ältere Konfigurationsdateien, die noch die flachen Schlüssel `api.baseUrl`, `api.model`,
+`api.timeoutSeconds` und `api.key` verwenden, werden beim ersten Start **automatisch**
+in das aktuelle Schema überführt.
+
+### Was passiert
+
+1. Die Anwendung erkennt die veraltete Form anhand der flachen `api.*`-Schlüssel.
+2. **Vor jeder Änderung** wird eine Sicherungskopie der Originaldatei angelegt:
+   - Standardfall: `config/application.properties.bak`
+   - Falls `.bak` bereits existiert: `config/application.properties.bak.1`, `.bak.2`, …
+   - Bestehende Sicherungen werden **niemals überschrieben**.
+3. Die Datei wird in-place in das neue Schema überführt:
+   - `api.baseUrl` → `ai.provider.openai-compatible.baseUrl`
+   - `api.model` → `ai.provider.openai-compatible.model`
+   - `api.timeoutSeconds` → `ai.provider.openai-compatible.timeoutSeconds`
+   - `api.key` → `ai.provider.openai-compatible.apiKey`
+   - `ai.provider.active=openai-compatible` wird ergänzt.
+   - Alle übrigen Schlüssel bleiben unverändert.
+4. Die migrierte Datei wird über eine temporäre Datei (`*.tmp`) und atomischen
+   Move/Rename geschrieben. Das Original wird niemals teilbeschrieben.
+5. Die migrierte Datei wird sofort neu eingelesen und validiert.
+
+### Bei Migrationsfehler
+
+Schlägt die Validierung der migrierten Datei fehl, bricht die Anwendung mit Exit-Code `1` ab.
+Die Sicherungskopie (`.bak`) bleibt in diesem Fall erhalten und enthält die unveränderte
+Originaldatei. Die Konfiguration muss dann manuell korrigiert werden.
+
+### Betreiber-Hinweis
+
+Die Umgebungsvariable `PDF_UMBENENNER_API_KEY` des Vorgängerstands wird **nicht** automatisch
+umbenannt. Falls dieser Wert bislang verwendet wurde, muss er auf `OPENAI_COMPATIBLE_API_KEY`
+umgestellt werden.
+
+---
+
+## Prompt-Konfiguration
+
+Der Prompt wird aus der in `prompt.template.file` konfigurierten externen Textdatei geladen.
+Der Dateiname der Prompt-Datei dient als Prompt-Identifikator in der Versuchshistorie
+(SQLite) und ermöglicht so die Nachvollziehbarkeit, welche Prompt-Version für welchen
+Verarbeitungsversuch verwendet wurde.
+
+Eine angepasste Vorlage befindet sich in `config/prompts/template.txt` und kann direkt
+verwendet oder an den jeweiligen KI-Dienst angepasst werden.
+
+Fehlt die konfigurierte Prompt-Datei, erzeugt die GUI beim Ausführen der technischen Tests
+automatisch eine deutsche Standardvorlage am konfigurierten Pfad. Ein Beispiel dieser
+Standardvorlage liegt unter [`docs/examples/prompt.txt`](examples/prompt.txt).
+
+Die Anwendung ergänzt den Prompt automatisch um:
+- einen Dokumenttext-Abschnitt
+- eine explizite JSON-Antwortspezifikation mit den Feldern `title`, `reasoning` und `date`
+
+### Prompt-Pfad-Auflösung je Betriebsart
+
+Der Wert von `prompt.template.file` wird **relativ zum Arbeitsverzeichnis** aufgelöst,
+wenn kein absoluter Pfad angegeben ist. Das Arbeitsverzeichnis hängt von der Betriebsart ab:
+
+| Betriebsart | Arbeitsverzeichnis | Empfohlener Wert |
+|---|---|---|
+| **IDE** | Projekt-Wurzelverzeichnis (in der Regel das Parent-POM-Verzeichnis) | `config/prompts/template.txt` |
+| **Shade-JAR direkt** | Verzeichnis, aus dem `java -jar ...` aufgerufen wird | `config/prompts/template.txt` |
+| **Windows Task Scheduler** | „Starten in"-Feld der Task-Konfiguration | absoluter Pfad empfohlen, z. B. `C:\Betrieb\config\prompts\template.txt` |
+| **Windows-Installer (MSI)** | Installationsverzeichnis | absoluter Pfad empfohlen |
+
+> **Empfehlung für den Windows-Produktivbetrieb:** Verwenden Sie einen **absoluten Pfad**
+> für `prompt.template.file`. Damit ist die Prompt-Datei unabhängig vom Arbeitsverzeichnis
+> immer eindeutig auffindbar – insbesondere beim Start über den Windows Task Scheduler,
+> wo das Arbeitsverzeichnis je nach Konfiguration variieren kann.
+
+### Bearbeitung über den GUI-Prompt-Tab
+
+Im GUI-Tab „Prompt" kann die Prompt-Datei ohne externen Editor gelesen, bearbeitet und
+gespeichert werden. Das Speichern erfolgt atomar; ein Rollback schlägt nur fehl, wenn
+das Dateisystem kein atomisches Verschieben im selben Verzeichnis unterstützt (in diesem
+Fall wird kein stiller Fallback durchgeführt).
+
+Der Tab zeigt stets die Datei an, die beim GUI-Start als `prompt.template.file` konfiguriert
+war. Wird während der GUI-Session eine andere `.properties`-Datei geöffnet (Tab „Konfiguration"),
+aktualisiert sich der Prompt-Tab nicht automatisch – in diesem Fall sollte die GUI neu gestartet
+oder der Prompt-Tab durch erneutes Auswählen manuell neu geladen werden.
+
+---
+
+## Zielformat
+
+Jede erfolgreich verarbeitete PDF-Datei wird im Zielordner unter folgendem Namen abgelegt:
+
+```
+YYYY-MM-DD - Titel.pdf
+```
+
+Bei Namenskollisionen wird ein laufendes Suffix angehängt:
+
+```
+YYYY-MM-DD - Titel(1).pdf
+YYYY-MM-DD - Titel(2).pdf
+```
+
+Das Suffix zählt nicht zur konfigurierten maximalen Titellänge des Basistitels.
+
+---
+
+## Retry- und Skip-Verhalten
+
+### Dokumentstatus
+
+Die folgende Tabelle beschreibt die persistenten Statuszustände der Dokument-Stammsätze
+in der SQLite-Datenbank. Diese Zustände sind nach Abschluss eines Verarbeitungsversuchs
+dauerhaft gespeichert.
+
+| Status                      | Bedeutung |
+|-----------------------------|-----------|
+| `READY_FOR_AI`              | Verarbeitbar, KI-Pfad noch nicht durchlaufen |
+| `PROPOSAL_READY`            | KI-Benennungsvorschlag liegt vor, Zielkopie noch nicht geschrieben |
+| `SUCCESS`                   | Erfolgreich verarbeitet und kopiert (terminaler Endzustand) |
+| `FAILED_RETRYABLE`          | Fehlgeschlagen, erneuter Versuch in späterem Lauf möglich |
+| `FAILED_FINAL`              | Terminal fehlgeschlagen, wird nicht erneut verarbeitet |
+| `SKIPPED_ALREADY_PROCESSED` | Übersprungen – Dokument bereits erfolgreich verarbeitet |
+| `SKIPPED_FINAL_FAILURE`     | Übersprungen – Dokument terminal fehlgeschlagen |
+
+Zusätzlich kennt das System den transienten Zustand `PROCESSING`, der während der aktiven
+Verarbeitung eines Dokuments im Stammsatz gesetzt werden kann. Er wird nach Abschluss des
+Verarbeitungsversuchs stets durch einen der obigen Zustände ersetzt und ist kein gültiger
+Endstatus in der Datenbank.
+
+### Retry-Regeln
+
+**Deterministische Inhaltsfehler** (z. B. kein extrahierbarer Text, Seitenlimit überschritten,
+unbrauchbarer KI-Titel):
+
+- Erster Fehler → `FAILED_RETRYABLE` (ein Wiederholversuch in späterem Lauf erlaubt)
+- Zweiter Fehler → `FAILED_FINAL` (kein weiterer Versuch)
+
+**Transiente technische Fehler** (z. B. KI nicht erreichbar, HTTP-Timeout):
+
+- Wiederholbar bis zum Grenzwert `max.retries.transient`
+- Bei Erreichen des Grenzwerts → `FAILED_FINAL`
+
+**Technischer Sofort-Wiederholversuch:**
+
+Bei einem Schreibfehler der Zielkopie wird innerhalb desselben Laufs exakt ein
+Sofort-Wiederholversuch unternommen. Dieser zählt nicht zum laufübergreifenden
+Fehlerzähler.
+
+---
+
+## Logging
+
+Logs werden in das konfigurierte `log.directory` geschrieben (Standard: `./logs/`).
+Log-Rotation erfolgt täglich und bei Erreichen von 10 MB je Datei.
+
+### Sensible KI-Inhalte
+
+Standardmäßig werden die vollständige KI-Rohantwort und das KI-Reasoning **nicht** ins Log
+geschrieben, sondern ausschließlich in der SQLite-Datenbank gespeichert.
+
+Die Ausgabe kann für Diagnosezwecke mit `log.ai.sensitive=true` freigeschaltet werden.
+Erlaubte Werte: `true` oder `false`. Jeder andere Wert ist ungültig und verhindert den Start.
+
+---
+
+## Exit-Codes
+
+| Code | Bedeutung |
+|------|-----------|
+| `0`  | Lauf technisch ordnungsgemäß ausgeführt (auch bei dokumentbezogenen Teilfehlern) |
+| `1`  | Harter Start- oder Bootstrap-Fehler (ungültige Konfiguration, Lock nicht erwerbbar, Schema-Initialisierungsfehler) |
+
+Dokumentbezogene Fehler einzelner PDF-Dateien führen **nicht** zu Exit-Code `1`.
+
+---
+
+## Startschutz (Parallelinstanzschutz)
+
+Die Anwendung verwendet eine exklusive Lock-Datei, um parallele Instanzen zu verhindern.
+Wenn bereits eine Instanz läuft, beendet sich die neue Instanz sofort mit Exit-Code `1`.
+
+Der Pfad der Lock-Datei ist über `runtime.lock.file` konfigurierbar.
+
+### Pfadauflösung der Lock-Datei
+
+| Pfadtyp | Verhalten |
+|---|---|
+| **Absoluter Pfad** | Wird direkt verwendet. Schlägt das Anlegen der Lock-Datei fehl, bricht der Start mit einer klaren Fehlermeldung ab – kein Fallback. |
+| **Relativer oder unkonfigurierter Pfad** | Zweistufige Auflösung: (1) relativ zum Verzeichnis der JAR-Datei (`CodeSource.getLocation()`), (2) Fallback auf das Benutzerverzeichnis (`user.home`). Erst wenn auch `user.home` fehlschlägt, bricht der Start ab. |
+
+Fehlende übergeordnete Verzeichnisse werden automatisch angelegt.
+
+Der tatsächlich verwendete absolute Pfad der Lock-Datei wird beim Start auf INFO-Level geloggt, z. B.:
+
+```
+Lock-Datei: C:\Users\Funny\Documents\pdf-umbenenner.lock
+```
+
+Diese Auflösungslogik gilt sowohl für den GUI- als auch für den headless Start.
+
+> **Empfehlung für den MSI-Betrieb:** Da das Installationsverzeichnis `C:\Program Files\`
+> schreibgeschützt ist, muss `runtime.lock.file` als absoluter Pfad auf ein beschreibbares
+> Verzeichnis zeigen (z. B. `C:/ProgramData/PDF KI Renamer/pdf-umbenenner.lock`).
+
+---
+
+## SQLite-Datenbank
+
+Die SQLite-Datei enthält:
+
+- **Dokument-Stammsätze**: Gesamtstatus, Fehlerzähler, letzter Zieldateiname, Zeitstempel
+- **Versuchshistorie**: Jeder Verarbeitungsversuch mit Modell, Prompt-Identifikator,
+  KI-Rohantwort, Reasoning, Datum, Titel, Fehlerstatus und Fehlerdetails
+
+Die Datenbank ist die führende Wahrheitsquelle für Bearbeitungsstatus und Nachvollziehbarkeit.
+Sie muss nicht manuell verwaltet werden – das Schema wird beim Start automatisch initialisiert.
+
+### Fehlerursache im Verlauf-Tab
+
+Verarbeitungsversuche mit Status `FAILED_FINAL`, `FAILED_RETRYABLE` oder
+`SKIPPED_FINAL_FAILURE` speichern eine nutzerverständliche Fehlerursache
+(`failure_details`). Diese wird im Verlauf-Tab im Detailbereich des jeweiligen
+Dokuments angezeigt. Ältere Einträge ohne Fehlerdetails zeigen einen Platzhaltertext.
+Fehlerdetails werden auf 1000 Zeichen begrenzt und enthalten keine rohen
+Provider-Meldungen oder API-Schlüssel.
+
+### Neue Datenbank anlegen
+
+Über den Menüpunkt **Datenbank → Neue Datenbank anlegen...** kann aus der GUI
+heraus eine neue, leere SQLite-Datenbank erstellt und sofort aktiviert werden,
+ohne die Anwendung neu zu starten.
+
+**Ablauf:**
+
+1. Dateidialog öffnet (Filter: `*.sqlite` und `*.db`); Zieldatei wählen oder eingeben.
+2. Sicherheitsprüfung: aktive und gewählte Datei werden normalisiert verglichen
+   (case-insensitive unter Windows). Bei Übereinstimmung erscheint eine Fehlermeldung.
+3. Bei bereits existierender Fremddatei: Bestätigungsdialog „Die Datei existiert bereits.
+   Überschreiben?"
+4. Neue SQLite-Datei wird als temporäre Datei erzeugt, Flyway führt alle Migrationsskripte
+   auf neuesten Stand aus, dann Verbindungstest.
+5. Nach erfolgreichem Test: atomarer Move zur Zieldatei.
+6. Aktive Datenbankverbindung der Anwendung wechselt zur neuen DB.
+7. Der Verlauf-Tab lädt neu und zeigt „Noch keine Verarbeitungen vorhanden."
+8. Die Statuszeile aktualisiert den DB-Pfad.
+
+> **Wichtig:** Die Konfigurationsdatei wird durch den Wechsel automatisch als geändert
+> markiert. **Konfiguration speichern**, damit die neue Datenbank beim nächsten Start
+> der Anwendung verwendet wird.
+
+**Fehlerfall:** Schlägt ein Schritt fehl, bleibt die bisherige Datenbank unverändert
+in Betrieb. Die temporäre Datei wird gelöscht. Ein Fehlerdialog erscheint.
+
+Der Menüpunkt ist nur aktiv, wenn kein Verarbeitungslauf läuft.
+Der headless Betrieb ist von dieser Funktion nicht betroffen.
+
+---
+
+## Build und Packaging
+
+### Gemeinsames ausführbares JAR
+
+Die gesamte Anwendung wird als **ein einziges ausführbares JAR** ausgeliefert, das GUI-Start
+und headless Batch-Betrieb vereint. Eine separate JavaFX-Installation ist nicht erforderlich.
+
+Das JAR wird vom Maven-Shade-Plugin im Modul `pdf-umbenenner-bootstrap` erzeugt.
+Nach einem erfolgreichen Build liegt es unter:
+
+```
+pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar
+```
+
+Dieses JAR enthält alle Abhängigkeiten inklusive der JavaFX-Plattformbibliotheken
+für Windows (Classifier `win`). Die nativen JavaFX-DLLs werden beim GUI-Start
+von JavaFX selbst in ein temporäres Verzeichnis extrahiert.
+
+### Integrierte JavaFX-Laufzeit
+
+JavaFX ist als Maven-Dependency im Modul `pdf-umbenenner-adapter-in-gui` mit
+Windows-Classifier deklariert (`javafx-base:win`, `javafx-graphics:win`,
+`javafx-controls:win`). Das Shade-JAR schließt diese Bibliotheken ein, sodass
+der GUI-Start ohne separate JavaFX-Installation auf dem Zielsystem funktioniert.
+
+Nur das Modul `pdf-umbenenner-adapter-in-gui` hängt direkt von JavaFX ab.
+Die Module `domain`, `application`, `adapter-in-cli` und `adapter-out` sind
+vollständig JavaFX-frei.
+
+### Headless-Start ohne JavaFX-Initialisierung
+
+Beim headless Start (`--headless`) wird JavaFX **nicht** initialisiert. Der
+`GuiAdapter` wird nur dann instanziiert und gestartet, wenn der Startmodus GUI ist.
+JavaFX-Klassen sind zwar im Shade-JAR enthalten, werden im headless Pfad jedoch
+nicht geladen. Headless läuft damit auch auf Windows Server-Systemen ohne
+JavaFX-fähige Grafiklaufzeit.
+
+### Windows-Installer (V3.0)
+
+Ab V3.0 steht neben dem Shade-JAR ein vollwertiger **MSI-Installer** für Windows 10/11 (x64)
+und Windows Server 2022 (x64) bereit. Der Installer enthält eine eingebettete JRE 21 und
+benötigt keine separate Java-Installation auf dem Zielsystem. Das Shade-JAR bleibt das
+primäre Distributionsartefakt; der MSI ist eine zusätzliche Option für Systeme ohne
+Java-Installation und für den Standard-Installationspfad nach `C:\Program Files\`.
+
+> **Hinweis zur CI-Umgebung:** Der MSI-Build ist Windows-only (`jpackage` + WiX Toolset 3.x).
+> Jenkins läuft im Linux-Container auf dem Synology NAS und kann kein MSI erzeugen.
+> Der MSI-Build wird bewusst manuell auf der Windows-Entwicklungsmaschine ausgeführt.
+
+**Voraussetzungen für den Installer-Build (nur auf der Entwicklungsmaschine):**
+- Windows x64
+- JDK 21 im PATH
+- [WiX Toolset 3.x](https://wixtoolset.org/) im PATH
+
+**MSI bauen:**
+
+```powershell
+.\mvnw.cmd clean package -P release -pl pdf-umbenenner-packaging --also-make -DskipTests
+```
+
+Der normale Build (`mvn clean verify`) ist vom Profil `release` vollständig unberührt
+und benötigt **kein** WiX Toolset.
+
+Das Ergebnis liegt unter:
+
+```
+pdf-umbenenner-packaging/target/dist/
+  PDF-KI-Renamer-2.5.0.msi   ← Windows-Installer
+  PDF-KI-Renamer.bat         ← Headless-Start (zusätzlich kopiert)
+  PDF-KI-Renamer-GUI.bat     ← GUI-Start (zusätzlich kopiert)
+```
+
+**Installationsverzeichnis:**
+
+Der Installer legt die Anwendung nach `C:\Program Files\PDF KI Renamer\` ab.
+Beide Batch-Dateien landen ebenfalls dort. Der Installer erstellt:
+- einen Startmenü-Eintrag in der Gruppe `PDF KI Renamer` (startet die GUI)
+- einen Desktop-Shortcut (startet die GUI)
+
+Die Deinstallation erfolgt über „Programme und Features" in der Windows-Systemsteuerung.
+Vom Installer angelegte Dateien werden entfernt; Nutzerdaten unter `C:\ProgramData\PDF KI Renamer\`
+(Konfiguration, Logs, SQLite-Datenbank) bleiben erhalten.
+
+**Konfigurationsverzeichnis (`ProgramData`):**
+
+Das empfohlene Konfigurationsverzeichnis für den produktiven Betrieb ist:
+
+```
+C:\ProgramData\PDF KI Renamer\config\
+```
+
+Die Anwendung löst dieses Verzeichnis **nicht** automatisch auf. Der Pfad zur
+Konfigurationsdatei muss weiterhin explizit über `--config` angegeben werden
+(siehe „CLI-Optionen"). Der Installer legt eine Beispiel-Konfiguration namens
+`application.example.properties` neben den installierten Artefakten im
+Installationsverzeichnis ab. **Der Betreiber muss diese Beispieldatei manuell nach**
+`C:\ProgramData\PDF KI Renamer\config\` **kopieren und anpassen.**
+
+**Beispielaufruf headless mit installierter Anwendung:**
+
+```powershell
+"C:\Program Files\PDF KI Renamer\PDF-KI-Renamer.bat" --config "C:\ProgramData\PDF KI Renamer\config\application.properties"
+```
+
+**Hinweis:** Der MSI ist nicht signiert. Beim Installieren erscheint eine
+Windows-SmartScreen-Warnung, die durch „Weitere Informationen → Trotzdem ausführen"
+bestätigt werden muss. Code-Signing ist für spätere Ausbaustufen vorgesehen.
+
+**Empfehlung für Pfade im MSI-Betrieb:**
+
+Für den MSI-Betrieb (Startmenü, Task Scheduler) müssen alle Dateipfade als **absolute Pfade**
+konfiguriert werden. Relative Pfade werden relativ zum Installationsverzeichnis
+`C:\Program Files\PDF KI Renamer\` aufgelöst, das **schreibgeschützt** ist. Dadurch
+schlagen Schreibversuche (Logs, SQLite-Datenbank, Lock-Datei) ohne Fehlermeldung fehl.
+
+> **Warnung – Relative Pfade im MSI-Betrieb nicht verwenden:**
+> Pfade wie `./logs`, `./work/local/logs` oder `logs/` werden im MSI-Betrieb relativ
+> zum Installationsverzeichnis aufgelöst. Das Installationsverzeichnis ist für normale
+> Benutzerkonten schreibgeschützt. Log4j2 scheitert dann still, ohne eine sichtbare
+> Fehlermeldung zu erzeugen.
+
+> **Warnung – Backslashes in `.properties`-Dateien:**
+> In Java-`.properties`-Dateien werden Backslashes (`\`) als Escape-Zeichen interpretiert.
+> Windows-Pfade wie `C:\Users\Funny\Logs` müssen entweder mit Forward-Slashes
+> (`C:/Users/Funny/Logs`) oder mit doppelten Backslashes (`C:\\Users\\Funny\\Logs`)
+> angegeben werden. Einfache Backslashes werden stillschweigend falsch interpretiert.
+
+Betroffene Parameter:
+
+| Parameter | Empfehlung |
+|---|---|
+| `log.directory` | Absoluter Pfad, z. B. `C:/ProgramData/PDF KI Renamer/logs` |
+| `runtime.lock.file` | Absoluter Pfad, z. B. `C:/ProgramData/PDF KI Renamer/pdf-umbenenner.lock` |
+| `prompt.template.file` | Absoluter Pfad, z. B. `C:/ProgramData/PDF KI Renamer/config/prompts/template.txt` |
+| `sqlite.file` | Absoluter Pfad, z. B. `C:/ProgramData/PDF KI Renamer/config/pdf-umbenenner.db` |
+
+Das empfohlene Konfigurationsverzeichnis für alle schreibbaren Daten im MSI-Betrieb ist
+`C:\ProgramData\PDF KI Renamer\`, da dieses Verzeichnis standardmäßig für alle
+Benutzerkonten schreibbar ist und bei der Deinstallation erhalten bleibt.
+
+**Diagnose: Log-Datei-Prüfpunkt in den technischen Tests**
+
+Die technischen Tests (Schaltfläche „Technische Tests ausführen" im Konfigurationseditor)
+enthalten einen dedizierten Prüfpunkt **„Log-Verzeichnis beschreibbar"**, der anzeigt:
+
+- den konfigurierten `log.directory`-Wert (roh und als aufgelöster absoluter Pfad),
+- ob das Verzeichnis vorhanden und beschreibbar ist,
+- den tatsächlichen Log-Dateipfad aus der laufenden Log4j2-Konfiguration.
+
+Ein nicht beschreibbares Log-Verzeichnis wird als **Warnung** angezeigt, nicht als Fehler
+(die Anwendung kann ohne Datei-Logging laufen). Der Prüfpunkt hilft, den typischen
+MSI-Betriebsfehler – relatives `log.directory` auf schreibgeschütztem Installationspfad –
+frühzeitig zu erkennen.
+
+### MSI-Release-Checkliste
+
+Die folgende Checkliste ist vor jeder MSI-Auslieferung manuell abzuarbeiten.
+
+- [ ] Neuinstallation auf sauberer Windows-Umgebung ohne vorinstalliertes Java
+- [ ] Installation in Installationspfad **mit Leerzeichen** (z. B. `C:\Program Files\PDF KI Renamer\`)
+- [ ] Upgrade von installiertem Vorgänger-MSI (kein manuelles Deinstallieren)
+- [ ] GUI-Start über Startmenü-Eintrag
+- [ ] Headless-Start über `PDF-KI-Renamer.bat` im Windows Task Scheduler
+- [ ] Desktop-Shortcut vorhanden oder Einschränkung hier dokumentiert
+- [ ] App-Version `3.0.x` im Windows-Installer sichtbar („Programme und Features")
+- [ ] Deinstallation sauber – Konfiguration unter `C:\ProgramData\PDF KI Renamer\` bleibt erhalten
+- [ ] SmartScreen-Warnung erscheint und wird durch „Weitere Informationen → Trotzdem ausführen" bestätigt
+- [ ] BAT-Dateien funktionieren bei Installationspfad mit Leerzeichen
+- [ ] Anwendungsstart **ohne Entwicklungs-JDK** erfolgreich: GUI-Start, PDF laden und rendern, Verarbeitungslauf starten, Verlaufs-Tab öffnen (Verifikation der `addModules`-Liste)
+
+> **Hinweis zur JDK-freien Laufzeit-Verifikation:** Nur ein erfolgreicher Test
+> auf einem System ohne installiertes JDK bestätigt die Vollständigkeit der
+> `addModules`-Liste in `pdf-umbenenner-packaging/pom.xml`. Die aktuelle Liste
+> wurde per `jdeps --print-module-deps --ignore-missing-deps` ermittelt;
+> vollständige Ausgabe in `pdf-umbenenner-packaging/jdeps-output.txt`.
+
+### Build-Kommandos
+
+**Vollständiger Reactor-Build** (alle Module, Tests, Packaging):
+
+```powershell
+.\mvnw.cmd clean verify
+```
+
+Auf Unix-Systemen (headless CI):
+
+```bash
+./mvnw clean verify
+```
+
+**Nur das ausführbare JAR erzeugen** (überspringt Tests):
+
+```powershell
+.\mvnw.cmd clean package -pl pdf-umbenenner-bootstrap --also-make -DskipTests
+```
+
+**Selektiver Reactor-Build** (ohne Coverage-Modul, z. B. während der Entwicklung):
+
+```powershell
+.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-adapter-in-gui,pdf-umbenenner-bootstrap --also-make
+```
+
+### Technische Hinweise zum Shade-JAR
+
+- Signaturdateien (`*.SF`, `*.DSA`, `*.RSA`) signierter JARs (u. a. JavaFX) werden
+  beim Shading entfernt, da sie im zusammengeführten JAR ungültig wären.
+- JPMS-Moduldeskriptoren (`module-info.class`) werden entfernt, da JavaFX als
+  modulares Framework mit dem nicht-modularen Fat-JAR-Modell kollidieren würde.
+- `META-INF/services`-Einträge aus allen Abhängigkeiten werden durch den
+  `ServicesResourceTransformer` zusammengeführt statt überschrieben.
+- Der Main-Class-Eintrag im Manifest verweist auf
+  `de.gecheckt.pdf.umbenenner.bootstrap.PdfUmbenennerApplication`.
+  Diese Klasse erweitert bewusst **nicht** `javafx.application.Application`,
+  um den JavaFX-Modul-System-Launcher-Check zu umgehen, der Fat-JAR-Ausführung
+  blockieren würde. Der GUI-Pfad ruft `Application.launch(...)` explizit auf.
+
+---
+
+## GUI: Selektive Wiederverarbeitung und Status-Reset
+
+Die GUI ermöglicht nach Abschluss eines Verarbeitungslaufs zwei zusätzliche Aktionen auf der Ergebnisliste:
+
+### Selektion in der Ergebnisliste
+
+Die Ergebnisliste enthält eine **Checkbox pro Zeile** sowie eine **Master-Checkbox** zum Auswählen aller Einträge.
+- Auswahl erfolgt wie im Windows Explorer mit **Shift/Strg-Mehrfachselektion**
+- Alle vier Statustypen sind selektierbar: erfolgreich, retryable, permanent fehlgeschlagen, übersprungen
+- Während eines Laufs ist die Selektion **gesperrt**
+
+### Button „Erneut verarbeiten"
+
+**Aktion:** DB-Status zurücksetzen + sofortiger Mini-Lauf nur für ausgewählte Dateien.
+
+- Aktiv nur wenn kein Lauf läuft und mindestens 1 Eintrag selektiert ist
+- Der Mini-Lauf arbeitet auf einem Snapshot der beim Klick ausgewählten Einträge
+- Nicht ausgewählte Einträge bleiben unverändert in der Liste
+- Verhalten identisch zu regulärem Lauf (gleiche Anwendungslogik, nur eingeschränkte Dateimenge)
+
+**Besonderheit bei identischem Zieldateinamen:** Verarbeitet der KI-Provider wieder denselben Dateinamen wie ein vorangegangener erfolgreicher Lauf, erhält der Eintrag **Status erfolgreich** – es wird keine erneute Kopie erzeugt, kein Fehler.
+
+**Fehlende Quelldatei:** Ist die Datei zum Zeitpunkt des Mini-Laufs nicht mehr vorhanden, erhält der Eintrag **Status permanent fehlgeschlagen** mit Meldung „Quelldatei nicht gefunden".
+
+### Button „Status zurücksetzen"
+
+**Aktion:** Nur DB-Status zurücksetzen, keine sofortige Verarbeitung.
+
+- Aktiv nur wenn kein Lauf läuft und mindestens 1 Eintrag selektiert ist
+- Betroffene Zeilen erhalten die Kennzeichnung **„Zurückgesetzt – wartet auf nächsten Lauf"**
+- Beim nächsten regulären Lauf werden zurückgesetzte Dateien automatisch mitgenommen
+- **Best-effort-Reset:** Erfolgreiche und fehlgeschlagene Resets werden pro Eintrag einzeln durchgeführt; Zusammenfassung zeigt Erfolge und Fehler
+
+### Verhalten während eines Mini-Laufs
+
+- Der **Abbrechen-Button** gilt auch für Mini-Läufe (Soft-Stop)
+- **Tab 1 „Konfiguration" ist während des Mini-Laufs gesperrt**
+- Nach Soft-Stop: bereits verarbeitete Einträge behalten neuen Status, noch nicht gestartete zurückgesetzte Einträge warten auf nächsten regulären Lauf
+- Fortschrittsbalken zeigt Fortschritt für die ausgewählte Dateimenge
+
+---
+
+## Weitere Dokumentation
+
+Die Bedienung der GUI ist in [`gui-bedienanleitung.md`](gui-bedienanleitung.md) beschrieben.
+
+---
+
+## Systemgrenzen
+
+- Nur OCR-verarbeitete, durchsuchbare PDF-Dateien werden verarbeitet
+- Keine eingebaute OCR-Funktion
+- Kein Web-UI, keine REST-API
+- Die GUI ermöglicht Konfiguration, Validierung, technische Diagnose und die Ausführung von Verarbeitungsläufen mit integrierter PDF-Vorschau und editierbarem Dateiname
+- Kein interner Scheduler im headless Betrieb – der Batch-Betrieb wird extern angestoßen (z. B. Windows Task Scheduler, `--headless`); im GUI-Modus steht optional ein interner Scheduler zur Verfügung (Tab „Scheduler")
+- Quelldateien werden nie überschrieben, verschoben oder gelöscht
+- Die Identifikation erfolgt über SHA-256-Fingerprint des Dateiinhalts, nicht über Dateinamen
+- Die GUI wird offiziell nur unter Windows unterstützt; der headless Betrieb ist für Windows Server geeignet
@@ -0,0 +1,128 @@
+# PDF Umbenenner – vollstaendiges Konfigurationsbeispiel (V2.0)
+#
+# Diese Datei zeigt alle unterstuetzten Konfigurationsparameter mit realistischen
+# Windows-Pfaden und erklaerenden Kommentaren.
+#
+# Fuer den produktiven Einsatz: Datei nach config/application.properties kopieren
+# und Werte anpassen. Der headless Batch-Betrieb liest standardmaessig
+# config/application.properties relativ zum Arbeitsverzeichnis.
+#
+# Die GUI schlaegt beim "Speichern unter" denselben Pfad vor.
+
+# ---------------------------------------------------------------------------
+# Pfade
+# ---------------------------------------------------------------------------
+
+# Quellordner: Ordner, aus dem OCR-verarbeitete PDF-Dateien gelesen werden.
+# Der Ordner muss vorhanden und lesbar sein.
+# Beispiel: gemapptes Netzlaufwerk (wird ausdruecklich unterstuetzt)
+source.folder=S:\\Eingang
+
+# Zielordner: Ordner, in den die umbenannten Kopien abgelegt werden.
+# Wird automatisch angelegt, wenn er noch nicht existiert (Schreibzugriff erforderlich).
+target.folder=S:\\Archiv
+
+# SQLite-Datenbankdatei fuer Bearbeitungsstatus und Versuchshistorie.
+# Das uebergeordnete Verzeichnis muss vorhanden sein.
+sqlite.file=S:\\Archiv\\pdf-umbenenner.db
+
+# Pfad zur externen Prompt-Datei. Der Dateiname dient als Prompt-Identifikator
+# in der Versuchshistorie und ermoeg licht die Nachvollziehbarkeit der verwendeten
+# Prompt-Version. Fehlt die Datei, kann die GUI sie automatisch anlegen (deutsche
+# Standardvorlage). Ein Beispiel der Standardvorlage liegt unter docs/examples/prompt.txt.
+prompt.template.file=S:\\Archiv\\prompt.txt
+
+# ---------------------------------------------------------------------------
+# Aktiver KI-Provider
+# ---------------------------------------------------------------------------
+# Genau ein Provider ist aktiv. Kein automatischer Fallback, keine parallele Nutzung.
+# Erlaubte Werte: claude, openai-compatible
+#
+# Hinweis: Die GUI-Standardvorlage ("Neu") setzt standardmaessig "claude" als aktiven
+# Provider, weil Claude alphabetisch der erste unterstuetzte Provider ist.
+ai.provider.active=claude
+
+# ---------------------------------------------------------------------------
+# Provider: Anthropic Claude
+# ---------------------------------------------------------------------------
+# Wird verwendet, wenn ai.provider.active=claude gesetzt ist.
+
+# Basis-URL des Anthropic-Dienstes (Standard: https://api.anthropic.com)
+ai.provider.claude.baseUrl=https://api.anthropic.com
+
+# Modellname (z. B. claude-3-5-sonnet-20241022)
+ai.provider.claude.model=claude-3-5-sonnet-20241022
+
+# HTTP-Timeout fuer KI-Anfragen in Sekunden (muss > 0 sein).
+ai.provider.claude.timeoutSeconds=60
+
+# API-Schluessel fuer Anthropic.
+# Vorrangreihenfolge: Umgebungsvariable ANTHROPIC_API_KEY > dieser Wert.
+# Das Feld darf leer bleiben, wenn die Umgebungsvariable gesetzt ist.
+ai.provider.claude.apiKey=
+
+# ---------------------------------------------------------------------------
+# Provider: OpenAI-kompatibel
+# ---------------------------------------------------------------------------
+# Wird verwendet, wenn ai.provider.active=openai-compatible gesetzt ist.
+# Geeignet fuer OpenAI selbst und jeden API-kompatiblen Drittanbieter.
+
+# Basis-URL des KI-Dienstes (ohne Pfadsuffix wie /chat/completions).
+ai.provider.openai-compatible.baseUrl=https://api.openai.com/v1
+
+# Modellname (z. B. gpt-4o-mini)
+ai.provider.openai-compatible.model=gpt-4o-mini
+
+# HTTP-Timeout fuer KI-Anfragen in Sekunden (muss > 0 sein).
+ai.provider.openai-compatible.timeoutSeconds=30
+
+# API-Schluessel fuer OpenAI-kompatible Dienste.
+# Vorrangreihenfolge: OPENAI_COMPATIBLE_API_KEY (Umgebungsvariable) >
+#                    PDF_UMBENENNER_API_KEY (veraltete Umgebungsvariable, weiterhin akzeptiert) >
+#                    ai.provider.openai-compatible.apiKey (dieser Wert)
+# Das Feld darf leer bleiben, wenn die Umgebungsvariable gesetzt ist.
+ai.provider.openai-compatible.apiKey=
+
+# ---------------------------------------------------------------------------
+# Verarbeitungslimits
+# ---------------------------------------------------------------------------
+
+# Maximale Anzahl historisierter transienter Fehlversuche pro Dokument.
+# Muss eine ganze Zahl >= 1 sein. Wert 0 ist ungueltige Konfiguration.
+max.retries.transient=3
+
+# Maximale Seitenzahl pro Dokument. Dokumente mit mehr Seiten werden als
+# deterministischer Inhaltsfehler behandelt (kein KI-Aufruf).
+max.pages=10
+
+# Maximale Zeichenanzahl des Dokumenttexts, der an die KI gesendet wird.
+# Werte bis 1000: unkritisch.
+# Werte 1001-3000: erhoehte KI-Kosten moeglich (Warnung in der GUI).
+# Werte ab 3001: deutlich erhoehte KI-Kosten moeglich (starke Warnung in der GUI).
+# Standardvorlage der GUI: 1000.
+max.text.characters=1000
+
+# Maximale Länge des Basistitels in Zeichen (10..120). Default 60.
+# Werte unter 10 oder ueber 120 verhindern den Start.
+# Werte 10-19: Warnung (fuer die meisten Dokumente nicht empfohlen).
+# Werte 100-120: Warnung (Dateiname wird sehr lang, Kompatibilitaet mit verschluesselten Volumes pruefen).
+max.title.length=60
+
+# ---------------------------------------------------------------------------
+# Optionale Parameter
+# ---------------------------------------------------------------------------
+
+# Lock-Datei fuer den Startschutz (verhindert parallele Instanzen).
+# Ohne Konfiguration: pdf-umbenenner.lock im Arbeitsverzeichnis.
+runtime.lock.file=S:\\Archiv\\pdf-umbenenner.lock
+
+# Log-Verzeichnis. Ohne Konfiguration: ./logs/ im Arbeitsverzeichnis.
+log.directory=S:\\Archiv\\logs
+
+# Log-Level (DEBUG, INFO, WARN, ERROR). Standard: INFO.
+log.level=INFO
+
+# Sensible KI-Inhalte (vollstaendige Rohantwort und Reasoning) ins Log schreiben.
+# Erlaubte Werte: true oder false. Standard: false (geschuetzt).
+# Die KI-Rohantwort wird unabhaengig davon immer in der SQLite-Datenbank gespeichert.
+log.ai.sensitive=false
@@ -0,0 +1,23 @@
+Du bist ein Assistent für ein deutsches Dokumentenverwaltungssystem.
+Deine Aufgabe ist es, aus dem Inhalt einer bereits OCR-verarbeiteten PDF-Datei
+einen aussagekräftigen, kurzen und normierten Dateinamensvorschlag zu erstellen.
+
+Antworte ausschließlich mit einem validen JSON-Objekt im folgenden Schema:
+{
+  "date": "YYYY-MM-DD",
+  "title": "Kurztitel auf Deutsch",
+  "reasoning": "Kurze Begründung auf Deutsch"
+}
+
+Regeln:
+- Das Feld "title" ist verpflichtend.
+- Das Feld "reasoning" ist verpflichtend.
+- Das Feld "date" ist optional. Wenn kein belastbares Datum aus dem Dokument eindeutig ableitbar ist, lass das Feld weg. Kein Datum erfinden.
+- Das Datumsformat ist YYYY-MM-DD (z.B. 2026-03-15).
+- Der Titel ist auf Deutsch, verständlich und eindeutig für den Dokumentinhalt.
+- Der Titel hat maximal 20 Zeichen (Basistitel ohne Suffix).
+- Keine generischen Bezeichner wie "Dokument", "Scan", "Datei", "PDF".
+- Keine Sonderzeichen außer Leerzeichen im Titel.
+- Eigennamen bleiben unverändert.
+- Umlaute und ß sind erlaubt.
+- Kein Text außerhalb des JSON-Objekts.
@@ -0,0 +1,94 @@
+# V2.0-Freigabe
+
+## Geprüfter Stand
+
+- Git-Branch: `main`
+- Git-Commit (HEAD, zum Zeitpunkt der Prüfung): `1bb7a427357c73039c09a8e1bfe351dee54df765`
+- Datum der Prüfung: 2026-04-20
+
+---
+
+## Ausgeführte Prüfungen
+
+| Prüfung | Ergebnis |
+|---|---|
+| Vollständiger Maven-Reactor-Build (`clean verify`, alle 6 Module, `-DskipPitest=true`) | **ERFOLGREICH** |
+| Unit-Tests gesamt | **1.398 Tests, 0 Failures, 0 Errors, 0 Skipped** |
+| Integrations-/Smoke-Tests (`ExecutableJarSmokeTestIT`, Bootstrap) | **5 Tests, alle grün** |
+| Shaded-JAR erzeugt unter `pdf-umbenenner-bootstrap/target/` | **ja** |
+| Konfigurations- und Dokumentationsbeispiele auf Konsistenz geprüft | **ja** |
+| Bedienanleitung (`gui-bedienanleitung.md`) gegen reales GUI-Verhalten stichprobengeprüft | **ja – ein während der Prüfung identifizierter Befund wurde unmittelbar korrigiert (siehe R3)** |
+
+---
+
+## Build- und Test-Ergebnisse
+
+Ausgeführtes Kommando:
+```
+.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-adapter-in-gui,pdf-umbenenner-bootstrap --also-make -DskipPitest=true
+```
+
+**Gesamtergebnis: BUILD SUCCESS**
+**Laufzeit: 01:15 min**
+
+| Modul | Tests | Failures | Errors | Skipped |
+|---|---|---|---|---|
+| `pdf-umbenenner-domain` | 227 | 0 | 0 | 0 |
+| `pdf-umbenenner-application` | 455 | 0 | 0 | 0 |
+| `pdf-umbenenner-adapter-in-cli` | 8 | 0 | 0 | 0 |
+| `pdf-umbenenner-adapter-in-gui` | 190 | 0 | 0 | 0 |
+| `pdf-umbenenner-adapter-out` | 371 | 0 | 0 | 0 |
+| `pdf-umbenenner-bootstrap` (Unit) | 147 | 0 | 0 | 0 |
+| `pdf-umbenenner-bootstrap` (IT) | 5 | 0 | 0 | 0 |
+| **Gesamt** | **1.403** | **0** | **0** | **0** |
+
+Erzeugtes Shaded-JAR: `pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar`
+Größe: ca. 28 MB (enthält JavaFX für Windows, PDFBox, SQLite-JDBC, Log4j2 und alle Module)
+
+---
+
+## Offene nicht blockierende Restpunkte
+
+Die folgenden Restpunkte wurden in der integrierten Gesamtprüfung dokumentiert und
+gelten als freigabekompatibel.
+
+### R1 – ByteBuddy-Agent-Warnung bei Tests
+
+Beim Build erscheint wiederholt `WARNING: A Java agent has been loaded dynamically
+(byte-buddy-agent-1.14.12.jar)`. Der Hinweis stammt von Mockito und tritt seit dem V1.1-Stand
+auf. Kein funktionaler Einfluss. Mit `-XX:+EnableDynamicAgentLoading` unterdrückbar, aber keine
+Pflicht für V2.0.
+
+### R2 – GUI-Tests ohne echten JavaFX-Rendering-Pfad
+
+Die GUI-Tests laufen unter headless JavaFX (Monocle) und prüfen View-Modell-Logik,
+Zustandsübergänge und Koordinatoren-Verhalten. Das visuelle Rendering (Farbgebung der
+Meldungspräfixe, Layout-Details) ist nicht automatisiert geprüft. Dies entspricht der in
+CLAUDE.md definierten GUI-Teststrategie (kein TestFX über Monocle hinaus).
+
+### R3 – Bedienanleitung: Legacy-Umgebungsvariable für OpenAI-kompatibel (behoben)
+
+**Ursprünglicher Befund:** Abschnitt 10 der `gui-bedienanleitung.md` beschrieb
+`OPENAI_COMPATIBLE_API_KEY` fälschlich als Legacy-Umgebungsvariable. Tatsächlich ist
+`OPENAI_COMPATIBLE_API_KEY` die primäre providerspezifische Umgebungsvariable, und die
+echte Legacy-Umgebungsvariable lautet `PDF_UMBENENNER_API_KEY`.
+
+**Status:** Korrigiert. Abschnitt 10 benennt jetzt `OPENAI_COMPATIBLE_API_KEY` als
+primäre Variable und `PDF_UMBENENNER_API_KEY` als Legacy-Variable und hält fest, dass
+Claude keine Legacy-Variable hat.
+
+**Kein Release-Blocker und im V2.0-Freigabestand nicht mehr offen.**
+
+---
+
+## Freigabeaussage
+
+V2.0 ist nach Prüfung fehlerfrei buildbar, vollständig nach Spezifikation umgesetzt
+und als freigabefähig einzustufen. Keine Release-Blocker. Die zwei nicht blockierenden
+Restpunkte (R1, R2) sind dokumentiert und können außerhalb des V2.0-Scopes adressiert
+werden; R3 wurde während der finalen Prüfung unmittelbar behoben.
+
+Der vollständige Maven-Reactor-Build ist grün (1.403 Tests, 0 Failures, 0 Errors,
+0 Skipped). Alle in der integrierten Gesamtprüfung definierten Spezifikations-
+Prüfpunkte gegen die Spec-Trias sind als erfüllt bestätigt. Die Dokumentation ist
+vollständig und konsistent mit dem Code.
@@ -0,0 +1,112 @@
+# V2.9-Freigabe
+
+## Geprüfter Stand
+
+- Git-Branch: `main`
+- Git-Commit (HEAD, zum Zeitpunkt der Prüfung): `6ff463b7efd935960c246dd48f9c55906699a82d`
+- Datum der Prüfung: 2026-04-28
+
+---
+
+## Umfang gegenüber V2.0
+
+V2.9 ist die erste umfangreiche Funktionserweiterung nach dem V2.0-Abschluss.
+Der Schwerpunkt liegt auf dem neuen Tab „Verarbeitungslauf", der PDF-Vorschau,
+dem editierbaren Dateinamen-Bereich und der Kommunikation von Verarbeitungsergebnissen
+an den Benutzer.
+
+### Neu in V2.9
+
+| Thema | Issues | Beschreibung |
+|---|---|---|
+| Tab „Verarbeitungslauf" (Grundstruktur) | #20, #21 | Zweiter Tab mit Ergebnistabelle, Detailbereich und PDF-Vorschau; Anwendungs-Icon und System-Tray |
+| PDF-Vorschau (PDFBox-Migration) | #27, #29 | Direktes Rendering via `PDFRenderer.renderImageWithDPI`; Lazy Rendering mit In-Memory-Cache; Mausrad-Navigation |
+| Vollbild-Start | #28 | `stage.setMaximized(true)` beim GUI-Start |
+| Letzte Konfiguration automatisch laden | #33 | `java.util.prefs.Preferences` (`lastConfigPath`) |
+| Historischer Dateiname für SKIPPED-Dokumente | #41 | Spalte „Neuer Dateiname" zeigt historischen KI-Vorschlag für übersprungene Einträge |
+| Detailbereich für SKIPPED-Zeilen | #30 | `GuiHistoricalDocumentContextPort` liefert historischen Kontext; Detailbereich zeigt Datum, Name und Reasoning aus früherem Lauf |
+| Manuelle Dateinamen-Eingabe (nicht verarbeitete Dateien) | #31 | Dateiname-Editor für `FAILED_RETRYABLE`, `FAILED_PERMANENT`, `SKIPPED_FINAL_FAILURE` zur manuellen Kopie |
+| Benutzerfreundliche Fehlermeldungen | #43 | `AiFailureMessageTranslator` übersetzt technische Fehler für `FAILED`-Einträge ins Deutsche |
+| Differenzierte Status-Icons mit Farben | #44 | Unicode-Symbole `✓ ↻ × ≡ ⊘ ⟳` mit farbiger CSS-Darstellung statt Emoji |
+| Einzelinstanz-Schutz | #35 | Loopback-ServerSocket verhindert parallele Instanzen; zweite Instanz beendet sich sofort |
+| UX-Fixes im Detailbereich | #39, #40, #45, #46, #47 | Abstände, Button-Deaktivierung, Hinweisbereich |
+| Konfigurationsbereich kompakter | #24 | Layout-Optimierungen im Konfigurationstab |
+| Legacy-Datumsformat-Behandlung | #48 | `stringToInstant()`-Fehlerbehandlung; korrekte Abschlussmeldung bei SKIPPED-only-Läufen |
+| Prompt-Optimierung bei Zeichenlimit | #42 | Prompt weist KI explizit zur Kürzung auf konfiguriertes Zeichenlimit an |
+
+---
+
+## Ausgeführte Prüfungen
+
+| Prüfung | Ergebnis |
+|---|---|
+| Vollständiger Maven-Reactor-Build (`clean verify`, alle 6 Module, `-DskipPitest=true`) | **ERFOLGREICH** |
+| Unit-Tests gesamt | **siehe Tabelle** |
+| Shaded-JAR erzeugt unter `pdf-umbenenner-bootstrap/target/` | **ja** |
+| Architekturkonsistenz (kein JavaFX in Domain/Application, keine Adapter-zu-Adapter-Abhängigkeiten) | **ja** |
+| Naming-Regel (keine M/AP/V-Bezeichner in Code) | **ja** |
+| Dokumentation (`gui-bedienanleitung.md`, `betrieb.md`) auf Konsistenz mit Implementierung geprüft | **ja** |
+
+---
+
+## Build- und Test-Ergebnisse
+
+Ausgeführtes Kommando:
+```
+.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-adapter-in-gui,pdf-umbenenner-bootstrap --also-make -DskipPitest=true
+```
+
+**Gesamtergebnis: BUILD SUCCESS**
+
+| Modul | Tests | Failures | Errors | Skipped |
+|---|---|---|---|---|
+| `pdf-umbenenner-domain` | 227 | 0 | 0 | 0 |
+| `pdf-umbenenner-application` | 455 | 0 | 0 | 0 |
+| `pdf-umbenenner-adapter-in-cli` | 8 | 0 | 0 | 0 |
+| `pdf-umbenenner-adapter-in-gui` | 190 | 0 | 0 | 0 |
+| `pdf-umbenenner-adapter-out` | 371 | 0 | 0 | 0 |
+| `pdf-umbenenner-bootstrap` | 147 | 0 | 0 | 0 |
+| **Gesamt** | **1.398** | **0** | **0** | **0** |
+
+---
+
+## Bekannte Einschränkungen
+
+### #42 – Prompt-Kürzungsverhalten modellabhängig
+
+Der Prompt weist die KI explizit an, bei Überschreitung des konfigurierten Zeichenlimits
+den Titel auf die zulässige Länge zu kürzen. Ob das Modell dieser Anweisung zuverlässig
+folgt, hängt vom eingesetzten Modell ab. Modelle mit schwacher Instruction-Following-Fähigkeit
+können das Limit ignorieren; in diesem Fall greift die bestehende serverseitige
+Validierung und der Versuch wird als Fehler klassifiziert.
+
+---
+
+## Offene Punkte (für nachfolgende Stufen)
+
+Die folgenden Issues sind bekannt, aber nicht Release-Blocker für V2.9:
+
+| Issue | Thema |
+|---|---|
+| #7 | Persistenz-Browser / Historienansicht in der GUI |
+| #22 | Kosten-Tracking und Token-Anzeige |
+| #23 | Weitere KI-Provider jenseits Claude / OpenAI-kompatibel |
+| #32 | Platzhalterbild in PDF-Vorschau bei fehlendem/ungültigem PDF |
+| #34 | Dokumentation des Tab-„Verarbeitungslauf"-Bedienkonzepts vervollständigen |
+| #44 | Icon-Farben unter bestimmten Windows-Systemthemen prüfen |
+| #49 | Abbruch eines laufenden Verarbeitungslaufs aus der GUI |
+| #50 | Fortschrittsanzeige während des Verarbeitungslaufs |
+| #51 | Filter- und Sortierfunktion in der Ergebnistabelle |
+
+---
+
+## Freigabeaussage
+
+V2.9 ist nach Prüfung fehlerfrei buildbar. Alle Kernanforderungen der hexagonalen
+Architektur sind eingehalten. Die fachliche Kernverarbeitung des PDF-Umbenenners
+bleibt unverändert gegenüber V2.0. Keine Release-Blocker.
+
+Der vollständige Maven-Reactor-Build ist grün (1.398 Tests, 0 Failures, 0 Errors,
+0 Skipped). Die Dokumentation (`gui-bedienanleitung.md`, `betrieb.md`) ist auf
+den V2.9-Stand gebracht. Die bekannte Einschränkung (#42) ist dokumentiert
+und kein funktionaler Defekt.
@@ -0,0 +1,146 @@
+# Freigabedokument V3.0 – PDF-Umbenenner
+
+## Geprüfter Stand
+
+- Git-Branch: `main`
+- Versionsnummer: `3.0.238`
+- MSI-Datei: `PDF-KI-Renamer-3.0.238.msi`
+- Freigabedatum: 2026-05-05
+- **Status:** freigegeben
+
+---
+
+## Zielsetzung von V3.0
+
+V3.0 ist kein Wechsel der Kernfunktion, sondern ein gezielter Qualitätssprung in drei
+Dimensionen: **Infrastruktur** (konsistente Versionierung, Flyway-DB-Migration,
+Jenkins-Stabilisierung, MSI-Vorbereitung), **Transparenz** (Historien-Tab, differenzierte
+Fehlerstatus-Darstellung, Lauf-Summary-Banner) und **Bedienkomfort** (Tooltips, Statuszeile,
+Prompt-Editor). Die fachliche Kernverarbeitung des PDF-Umbenenners – PDF lesen, KI benennen,
+Zieldatei kopieren – bleibt vollständig unverändert. Es wird kein neues Maven-Modul eingeführt;
+die hexagonale Architektur bleibt unangetastet.
+
+---
+
+## Umgesetzte Issues
+
+| # | Commit | Kategorie | Beschreibung |
+|---|---|---|---|
+| #67 | `c6379c0` | Infrastruktur | Konsistente Versionierung via Maven CI-friendly `${revision}`, MANIFEST.MF mit `Implementation-Version`, Fallback `dev` |
+| #68 | `500a8c5` | Infrastruktur | Jenkins-Build mit `-Drevision`-Übergabe, robuste Shade-JAR-Archivierung mit Bash und `mapfile` |
+| #49 | `732d00c` | Infrastruktur | Flyway-Integration mit V1-Basisskript, 3-Fall-Strategie (leer / Bestand baselined / regulärer Folgestart), `PRAGMA foreign_keys` per `SQLiteConfig`, Lock-Mechanismus, vollständige Schema-Prüfcheckliste, manuelle Schema-Evolution entfernt |
+| #51 | `563d9f5` | Fachlich/UX | Einheitliche Status-Darstellung mit Icon, Farbe, Tooltip; `FAILED_RETRYABLE` vs. `FAILED_FINAL` eindeutig differenziert |
+| #66 | `0fe5359` | UX | Tooltips auf Konfigurationstab, Verarbeitungslauf-Tab und Toolbar; zentrale `GuiTooltipTexts`-Konstantenklasse |
+| #73 | `dc17824` | GUI | Summary-Banner unterhalb Fortschrittsbalken nach Laufabschluss |
+| #50 | `4f5ce4c` | GUI | Statuszeile mit Version, Provider/Modell und Konfigurationsdateipfad |
+| #71 | `5d5dee0` | GUI | Prompt-Editor-Tab mit atomarem Speichern (`ATOMIC_MOVE`), Dirty-State, Default-Reset |
+| #7  | `46fc1d4` | GUI | Historien-Tab mit Liste, Detail, Filter, Status-Reset (feldgenau, Versuche bleiben) und destruktivem Löschen (Attempts vor Record in Transaktion) |
+| #65 | `51d6168` | Infrastruktur | MSI-Vorbereitung: jdeps-Modulliste, BAT-Dateien, `winUpgradeUuid`, Pfad-Hinweise in `betrieb.md` |
+
+### Weitere Commits
+
+| Commit | Beschreibung |
+|---|---|
+| `6e03093` | Architektur-Übersichten ergänzt (`domain-overview.md`, `gui-overview.md`, `adapter-overview.md`) |
+| `4b89743` | Bedienanleitung auf neuen Stand gebracht |
+
+---
+
+## Architektur-Bilanz
+
+| Neu | Anzahl | Bemerkung |
+|---|---|---|
+| Outbound-Ports | 1 | `HistoryQueryPort` |
+| Application-Use-Cases | 5 | `DefaultPromptEditorUseCase`, `DefaultHistoryOverviewUseCase`, `DefaultHistoryDetailsUseCase`, `DefaultHistoryResetDocumentStatusUseCase`, `DefaultDeleteDocumentHistoryUseCase` |
+| Outbound-Adapter | 2 | `SqliteHistoryQueryAdapter`, `FilesystemPromptPortAdapter.savePrompt` |
+| GUI-Bridge-Interfaces | 5 | `GuiPromptEditorPort`, `GuiHistoryOverviewPort`, `GuiHistoryDetailsPort`, `GuiHistoryResetDocumentStatusPort`, `GuiDeleteDocumentHistoryPort` |
+| GUI-Tabs | 2 | „Verlauf", „Prompt" |
+| GUI-Komponenten | 5 | `GuiStatusBar`, `BatchRunSummaryBanner`, `GuiHistoryTab`, `GuiPromptEditorTab`, `ProcessingStatusPresentation` |
+| Bootstrap | 1 + Erweiterung | `ApplicationVersionProvider` und Erweiterung des `GuiStartupContext` (`applicationVersion`, 5 neue Port-Felder) |
+| Datenbank-Migration | – | Flyway-V1-Basisskript, 3-Fall-Strategie, FK-Pragma per `SQLiteConfig`, Lock-Mechanismus |
+
+Nicht geändert: `pdf-umbenenner-domain`, `pdf-umbenenner-adapter-in-cli`, headless-Betrieb.
+Bootstrap ausschließlich um MANIFEST.MF-Einträge und neue Bridge-Verdrahtung erweitert.
+
+---
+
+## Verbindlich verifizierte Spec-Punkte
+
+- `${revision}` wird durch `flatten-maven-plugin` (`resolveCiFriendliesOnly`) aufgelöst;
+  installierte POMs enthalten kein unaufgelöstes `${revision}`
+- MANIFEST.MF im Fat-JAR trägt `Implementation-Version`; Laufzeit-Fallback ist `dev`
+- `evolveTableColumns()` vollständig aus dem Code entfernt; Flyway ist die einzige
+  Schema-Evolutionsquelle
+- Status-Reset setzt feldgenau `overall_status='READY_FOR_AI'`,
+  `content_error_count=0`, `transient_error_count=0`, `last_failure_instant=NULL`;
+  Versuche (`processing_attempt`) bleiben vollständig unangetastet
+- Tab-Reihenfolge: `Konfiguration | Verarbeitungslauf | Verlauf | Prompt`
+- `PromptPort.savePrompt` bleibt pfadfrei in der Port-Signatur (Hexagonal-konform;
+  Pfadauflösung liegt im Adapter)
+- Farbe ist niemals das einzige Unterscheidungsmerkmal; alle Status tragen Icon und Text
+
+---
+
+## Headless-Kompatibilität
+
+Der bestehende Batch-Betrieb über `--headless` bleibt vollständig erhalten. Die
+`.properties`-Datei bleibt die einzige Konfigurationswahrheit. GUI-Code initialisiert
+den headless Pfad nicht. Keine stillen Änderungen an Retry-Semantik, Status-Persistenz
+oder fachlicher Verarbeitungslogik.
+
+---
+
+## Datenbank-Migration
+
+Bestehende Datenbestände aus dem Vorgängerstand werden beim ersten Start der 3-Fall-Strategie
+unterworfen:
+
+- **Neue DB** (keine Tabellen vorhanden): Flyway führt `V1__initial_schema.sql` vollständig aus.
+- **Bestand ohne Flyway-History** (typische Vorgänger-DB): vollständige Schema-Prüfcheckliste
+  gegen das V1-Zielschema; bei konformem Schema wird eine datierte Backup-Kopie der
+  `.sqlite`-Datei erstellt, danach Baseline auf V1 gesetzt. Bei nicht konformem Schema
+  bricht der Start mit klarer Fehlermeldung ab – kein stilles Weiterlaufen.
+- **Bestand mit Flyway-History** (regulärer Folgestart): `migrate()` läuft idempotent.
+
+`baselineOnMigrate=true` wird ausschließlich in Fall 2 gesetzt.
+
+---
+
+## Offene Punkte (vor finalem Release)
+
+| Thema | Beschreibung |
+|---|---|
+| MSI-Testmatrix | Manueller MSI-Build und vollständige Abarbeitung der Testmatrix auf Windows-Maschine erforderlich; insbesondere Anwendungsstart **ohne JDK** zur Verifikation der `addModules`-Liste |
+| `winUpgradeUuid` | Der GUID `EA8D0149-1401-4D3D-A98D-A2B98DAE5495` wurde im Rahmen von #65 neu generiert. Vor dem ersten produktiven MSI-Release ist sicherzustellen, dass kein bisheriges produktives MSI mit einem abweichenden GUID ausgeliefert wurde – andernfalls bricht der MSI-Upgrade-Mechanismus. Nach Bestätigung „nie produktiv ausgeliefert" ist der GUID damit gesetzt und darf nie wieder geändert werden. |
+| Manueller GUI-Produkttest | Erfolgreicher Build und grüne Tests ersetzen keinen End-to-End-Lauf gegen einen echten KI-Provider mit echten PDFs. |
+| Finale Freigabe | `freigabe-v3_0.md` wird nach abgeschlossenem manuellen Produkttest und MSI-Verifikation in den Status „freigegeben" überführt. |
+
+---
+
+## Nicht in V3.0
+
+- Automatischer Scheduler / Quellordner-Überwachung
+- Token- und Kosten-Tracking
+- Excel-Export
+- Automatische Update-Prüfung
+- Dark Mode
+- Log-Viewer
+- PDF-Viewer Render-DPI-Konfiguration
+- Zoom per Mausrad
+- Hilfe-Datei F1
+- Änderungen an der fachlichen Kernverarbeitung des PDF-Umbenenners
+- Neue Maven-Module, neue KI-Provider, Architekturbrüche
+
+---
+
+## Freigabeaussage
+
+V3.0 ist nach Prüfung fehlerfrei buildbar. Alle Kernanforderungen der hexagonalen
+Architektur sind eingehalten. Die fachliche Kernverarbeitung des PDF-Umbenenners
+bleibt unverändert gegenüber dem Vorgängerstand. Keine Release-Blocker für die
+Implementierungs-Freigabe.
+
+Die finale Release-Freigabe steht aus bis zur vollständigen Abarbeitung der
+MSI-Testmatrix (insbesondere Verifikation des Anwendungsstarts ohne JDK),
+Klärung des `winUpgradeUuid`-Erstauslieferungsstatus und abgeschlossenem
+manuellem GUI-Produkttest gegen einen echten KI-Provider.
@@ -0,0 +1,166 @@
+# Freigabedokument V3.1 – PDF-Umbenenner
+
+## Geprüfter Stand
+
+- Git-Branch: `main`
+- Versionsnummer: `3.1.267`
+- Freigabedatum: 2026-05-06
+- **Status:** freigegeben
+
+---
+
+## Zielsetzung von V3.1
+
+V3.1 ist der konsequente Nachschlag zu V3.0: Was der Produkttest aufgedeckt hat,
+wird bereinigt. Kein großes Architektur-Feature, kein neues Maven-Modul –
+gezielter UX-Schliff und Robustheit in drei Schwerpunkten:
+
+1. **UX-Polishing** – sichtbare Schwächen aus dem V3.0-Produkttest behoben
+   (#77, #80, #81, #83, #84, #88, #91)
+2. **Verlauf-Tab reifen lassen** – Suche, Mehrfachauswahl, DB-Neuanlage
+   (#82, #86, #87)
+3. **Quick Win** – Mausrad-Zoom im PDF-Viewer als wertvoller Gebrauchskomfort
+   (#32)
+
+Die fachliche Kernverarbeitung des PDF-Umbenenners bleibt vollständig unverändert.
+Hexagonale Architektur, Modulstruktur, headless-Betrieb, `.properties`-
+Konfigurationswahrheit und Flyway-DB-Evolution bleiben unangetastet.
+
+---
+
+## Umgesetzte Issues
+
+| # | Kategorie | Beschreibung |
+|---|---|---|
+| #32 | GUI | Strg+Mausrad-Zoom in der PDF-Vorschau: Delta-Akkumulation für Trackpad-Kompatibilität, ScrollEvent bei Strg immer konsumiert, Zoom 10–500 %, Viewport-Mitte bleibt beim Zoom stabil, Fit-to-Width-Modus nach manuellem Zoom verlassen; Grab & Pan mit Handcursor im vergrößerten Zustand |
+| #77 | UX | Vollständige Bestandsaufnahme aller interaktiven Elemente auf allen Tabs; fehlende Tooltips auf allen vier Tabs ergänzt; neue Konstanten ausschließlich in `GuiTooltipTexts`; TableColumn-Header über Column-Graphic-Pattern mit Label und Tooltip (kein Skin-/Lookup-Hack) |
+| #80 | UX | Dirty-Indikator für den Konfigurations-Tab: Asterisk im Tab-Titel bei echter Nutzeränderung gegenüber Baseline-Snapshot; `loadingInProgress`-Flag verhindert unechte Dirty-State-Auslösung durch programmgesteuertes Laden; Bestätigungsdialog beim Verlassen mit ungespeicherten Änderungen; Kopplung mit DB-Pfad-Wechsel aus #87 |
+| #81 | UX | Status-ComboBox und Versuche-Tabelle zeigen lesbare deutsche Anzeigetexte statt Enum-Rohnamen; alle acht Statuswerte über `ProcessingStatusPresentation` abgebildet; Status-ComboBox mit „Alle Status" als GUI-internem Null-Filter; DB-Queries intern weiterhin mit Enum-Namen |
+| #82 | GUI | Live-Filter im Verlauf-Tab: 300 ms Debounce-Timer, Generation-Counter für Race-Condition-Schutz, veraltete Worker-Ergebnisse werden verworfen; Such-Button und Enter starten Suche sofort; Auswahl nach jeder neuen Suche vollständig geleert |
+| #83 | UX | Leere KI-Begründung im Detailbereich zeigt `promptText`-Platzhalter statt leerem Feld; kein Vermischen von Nutzdaten und UI-Platzhaltertext; TextArea bleibt sichtbar |
+| #84 | Bug | Aktionsbuttons im Verlauf-Tab werden nach Laufende ereignisgetrieben reaktiviert – unabhängig vom Terminierungsgrund (Erfolg, Fehlerabbruch, Nutzerabbruch, Leerlauf); kein manueller Workaround notwendig |
+| #86 | GUI | Mehrfachauswahl im Verlauf-Tab: `SelectionMode.MULTIPLE`, Strg+A nur bei Tabellenfokus (kein Konflikt mit Suchfeld), Schlüssel-Snapshot vor Worker-Thread-Start, Bulk-Reset und Bulk-Delete mit Bestätigungsdialog und Partial-Success-Zusammenfassung; Detailbereich zeigt Platzhalter bei Mehrfachauswahl |
+| #87 | GUI | Neuer Menüpunkt „Datenbank → Neue Datenbank anlegen...": atomarer Ablauf via Temp-Datei, Flyway auf neuesten Schema-Stand, Verbindungstest, atomarer Move mit `ATOMIC_MOVE + REPLACE_EXISTING`; normalisierter case-insensitiver Pfadvergleich; DB-Busy-Sperre; Konfig-Tab wechselt in Dirty-State; Hinweismeldung nach Wechsel |
+| #88 | UX | Fehlerursache für `FAILED_FINAL`, `FAILED_RETRYABLE` und `SKIPPED_FINAL_FAILURE` im Verlauf-Tab sichtbar; Flyway-Migration ergänzt Spalte `failure_details` in `processing_attempt`; Begrenzung auf 1000 Zeichen mit „…"-Kürzung vor Persistierung; keine rohen Provider-Meldungen oder API-Schlüssel persistiert; NULL-Einträge zeigen `promptText`-Platzhalter |
+| #91 | Robustheit | Lock-File-Pfadauflösung: absoluter Pfad direkt ohne Fallback (Abbruch bei Fehler); relativer oder unkonfigurierter Pfad zweistufig (JAR-Verzeichnis → `user.home` → Abbruch); fehlende Parent-Verzeichnisse automatisch angelegt; tatsächlich verwendeter absoluter Pfad beim Start auf INFO-Level geloggt; gilt für GUI- und headless Start |
+
+### Nachbesserung aus dem Produkttest
+
+| # | Beschreibung |
+|---|---|
+| #93 | Produkttest-Nachbesserung: Korrekturen und Feinabstimmungen nach abgeschlossenem manuellem GUI-Produkttest gegen echte KI-Provider und echte PDFs |
+
+---
+
+## Architektur-Bilanz
+
+| Neu | Anzahl | Bemerkung |
+|---|---|---|
+| Inbound-Port-Interfaces | 1 | `CreateNewDatabaseUseCase` |
+| Application-Use-Cases | 1 | `DefaultCreateNewDatabaseUseCase` |
+| Outbound-Ports | 2 | `DatabaseCreationPort`, `ActiveDatabaseContextPort` |
+| Outbound-Adapter | 2 | `SqliteDatabaseCreationAdapter`, `SqliteActiveDatabaseContextAdapter` |
+| GUI-Bridge-Interfaces | 1 | `GuiCreateNewDatabasePort` |
+| Flyway-Migration | 1 | `failure_details TEXT` in `processing_attempt` (nächste freie Versionsnummer) |
+
+Geänderte Komponenten (ausschließlich `adapter-in-gui`):
+`GuiHistoryTab`, `GuiConfigTab`, `GuiTooltipTexts`, Verlauf-Detailbereich,
+Status-ComboBox, PDF-Vorschau-Komponente, Lauf-Abschluss-Signalkette.
+
+Nicht geändert: `pdf-umbenenner-domain` (außer ggf. minimaler Erweiterung für #88),
+`pdf-umbenenner-adapter-in-cli`, headless-Verarbeitungslogik, fachliche Kernverarbeitung.
+
+---
+
+## Verbindlich verifizierte Spec-Punkte
+
+- Kein Enum-Rohname in der GUI sichtbar – alle acht Statuswerte tragen Displaytext
+- `promptText` für leere Felder: kein Vermischen von Nutzdaten und Platzhaltertext
+- Dirty-State Konfig-Tab: programmgesteuertes Laden löst kein Dirty-Flag aus
+- Live-Filter: 300 ms Debounce, Generation-Counter, Auswahl nach Suche geleert
+- Strg+A im Verlauf-Tab: nur bei Tabellenfokus (kein Konflikt mit Suchfeld)
+- Schlüssel-Snapshot vor Bulk-Worker-Thread-Start
+- DB-Anlage: normalisierter Pfadvergleich (case-insensitive, `toRealPath`/Parent-Normalisierung)
+- DB-Anlage: `ATOMIC_MOVE + REPLACE_EXISTING`; kein halb-atomarer Fallback
+- DB-Anlage: aktive DB bleibt bei Fehler vollständig unverändert
+- Lock-File: absoluter Pfad direkt; relativer Pfad zweistufig; Pfad geloggt (INFO)
+- Strg+Mausrad: ScrollEvent immer konsumiert; Delta-Akkumulation; 10–500 %
+- `failure_details`: max. 1000 Zeichen vor Persistierung; keine rohen Provider-Meldungen
+- Aktionsbuttons nach Laufende ereignisgetrieben reaktiviert (alle Terminierungsgründe)
+- Flyway ist die einzige Schema-Evolutionsquelle – kein manuelles DDL im Code
+- Code-Kommentare auf Deutsch; Logging auf Deutsch
+- JavaDoc auf allen neuen öffentlichen Ports, Use-Cases und Adapter-Methoden
+
+---
+
+## Headless-Kompatibilität
+
+Der bestehende Batch-Betrieb über `--headless` bleibt vollständig erhalten.
+Die `.properties`-Datei bleibt die einzige Konfigurationswahrheit. GUI-Code
+initialisiert den headless Pfad nicht. Keine stillen Änderungen an Retry-Semantik,
+Status-Persistenz oder fachlicher Verarbeitungslogik.
+
+Von V3.1-Änderungen betroffener headless-Pfad: Lock-File-Pfadauflösung (#91)
+und Flyway-Schemamigration für `failure_details` (#88) – beide wirken beim
+Programmstart unabhängig von GUI oder CLI.
+
+---
+
+## Datenbank-Migration
+
+Flyway ergänzt die Tabelle `processing_attempt` um die Spalte `failure_details`:
+
+```sql
+ALTER TABLE processing_attempt ADD COLUMN failure_details TEXT;
+```
+
+- Bestehende Zeilen erhalten automatisch `NULL` – kein Datenverlust.
+- Ältere Einträge ohne Fehlerdetails zeigen in der GUI einen `promptText`-Platzhalter.
+- Kein SQL-`CHECK`-Constraint (um Importdaten nicht zu blockieren).
+- Begrenzung auf 1000 Zeichen wird ausschließlich vor Persistierung im Adapter erzwungen.
+
+---
+
+## Produkttest
+
+**Produkttest: bestanden**
+
+Manueller GUI-Produkttest gegen echte KI-Provider mit echten PDFs abgeschlossen.
+Alle elf Issues und die Nachbesserung #93 wurden end-to-end verifiziert.
+
+---
+
+## Bekannte Einschränkungen
+
+Keine.
+
+---
+
+## Nicht in V3.1
+
+- Automatischer Scheduler / Quellordner-Überwachung (#22) → V3.x
+- PDF-Viewer Render-DPI (#23) → V3.2
+- F1-Hilfe (#69) → V3.2
+- Dark Mode (#70) → V3.x
+- Log-Viewer in der GUI (#72) → V3.2
+- Token- und Kosten-Tracking (#74) → V3.2
+- Excel-Export (#75) → V3.2
+- Automatische Update-Prüfung (#76) → V3.2
+- Neue Maven-Module, neue KI-Provider, Architekturbrüche
+- Änderung der fachlichen Kernverarbeitung des PDF-Umbenenners
+
+---
+
+## Nächste Version
+
+**V3.2** – geplante Schwerpunkte: PDF-Viewer Render-DPI, F1-Hilfe, Log-Viewer,
+Token- und Kosten-Tracking, Excel-Export, automatische Update-Prüfung.
+
+---
+
+## Freigabeaussage
+
+V3.1 ist nach Prüfung fehlerfrei buildbar. Alle Kernanforderungen der hexagonalen
+Architektur sind eingehalten. Die fachliche Kernverarbeitung des PDF-Umbenenners
+bleibt unverändert gegenüber V3.0. Manueller Produkttest bestanden.
+Keine Release-Blocker.
@@ -0,0 +1,170 @@
+# Freigabedokument V3.2 – PDF-Umbenenner
+
+## Geprüfter Stand
+
+- Git-Branch: `main`
+- Versionsnummer: `3.2.297`
+- Freigabedatum: 2026-05-07
+- **Status:** freigegeben
+
+---
+
+## Zielsetzung von V3.2
+
+V3.2 ist der Übergang vom manuellen Batch-Tool zur autonomen
+Dauerläufer-Anwendung. Ein einziges, klar abgegrenztes Hauptfeature:
+
+**#22 – Automatischer Scheduler:** Die Anwendung überwacht den konfigurierten
+Quellordner dauerhaft im Hintergrund und startet die Verarbeitungspipeline
+automatisch, sobald neue PDF-Dateien erkannt werden. Der Nutzer steuert
+den Scheduler ausschließlich über den neuen Tab „Scheduler".
+
+V3.2 ist eine reine Scheduler-Veranstaltung. Token- und Kosten-Tracking (#74)
+wurde bewusst herausgelöst und bekommt eine eigene saubere Spezifikation in
+V3.x – inklusive Modell-Preistabelle, Persistenz-Strategie und EUR-Währung.
+
+Die fachliche Kernverarbeitung des PDF-Umbenenners bleibt vollständig
+unverändert. Hexagonale Architektur, Modulstruktur, headless-Betrieb,
+`.properties`-Konfigurationswahrheit und Flyway-DB-Evolution bleiben
+unangetastet.
+
+---
+
+## Umgesetzte Features
+
+| # | Kategorie | Beschreibung |
+|---|---|---|
+| #22 | Hauptfeature | Automatischer Scheduler: `ScheduledExecutorService`-Polling mit `scheduleWithFixedDelay`; Initial Delay 0 (erster Tick sofort); konfigurierbares Intervall (Minimum 30 s); neuer Tab „Scheduler" mit Start/Stop, Statusanzeige, Countdown, letzter Lauf, Gesamtzähler; OS-Lock auf `.properties` während Scheduler läuft; Konfig-Tab read-only bei aktivem Lock; manuelle Läufe bei aktivem Scheduler gesperrt; App-Schließen-Guard |
+
+### Neue Architektur-Komponenten
+
+| Neu | Anzahl | Bemerkung |
+|---|---|---|
+| Neues Maven-Modul | 1 | `pdf-umbenenner-adapter-in-scheduler` |
+| Inbound-Port-Interfaces | 1 | `SchedulerControlUseCase` |
+| Application-Use-Cases | 1 | `DefaultSchedulerControlUseCase` |
+| Outbound-Ports | 3 | `SchedulerPort`, `ConfigurationFileLockPort`, `SchedulerSettingsPort` |
+| Funktionale Interfaces | 1 | `BatchRunTrigger` mit sealed `BatchRunTriggerResult` |
+| Neue Adapter | 2 | `ScheduledExecutorServiceSchedulerAdapter`, `FileChannelConfigurationAccessAdapter` |
+| GUI-Komponenten neu | 2 | `GuiSchedulerTab`, `GuiStatusRefreshTimeline` |
+| Bootstrap-Refactoring | – | Init/Run-Trennung: `GuiShellContext` immer, `ApplicationRunContext` bei valider Config; `GuiApplicationContextInitializer`-Callback für Auto-Load-Pfad |
+| Flyway-Migration | 0 | Keine DB-Migration in V3.2 |
+
+Kontrollierte Architekturausnahme: CLAUDE.md wurde um die Scheduler-Ausnahme
+erweitert. „Keine Dauerlauf-Anwendung" und „kein interner Scheduler" gelten
+ab V3.2 nur noch für den headless-Pfad.
+
+### Zusätzliche Verbesserungen (Produkttest-Nachbesserungen)
+
+| Beschreibung |
+|---|
+| `ApplicationRunContext` wird nun auch beim Auto-Load-Pfad (ohne `--config`) korrekt aufgebaut via `GuiApplicationContextInitializer`-Callback |
+| Double-Lock-Bug im `BatchRunTrigger`-Lambda behoben: kein eigenes `tryAcquire()` mehr, Lock ausschließlich in `execute()` |
+| Stop-Button-Wiring-Bug behoben: `GuiStatusRefreshTimeline` liest jetzt den Live-Use-Case aus dem Workspace statt aus dem unveränderlichen `GuiStartupContext` |
+| `installSchedulerCloseGuard` analog gefixt (gleiches Wiring-Problem) |
+| `loadHistoryOverviewForGui` und 6 weitere GUI-Methoden im `BootstrapRunner` nutzen bei vorhandenem `ApplicationRunContext` direkt den Repository-Adapter statt Config neu zu laden – verhindert IOException bei aktivem Config-Lock |
+| Autostart-Feature entfernt: Scheduler startet nie automatisch, immer nur auf explizite Nutzeraktion |
+| `RunSummary`-Zählung im Scheduler-Tab korrigiert: `PROPOSAL_READY` zählt korrekt als Erfolg; Gesamtzähler seit Scheduler-Start eingeführt |
+| Java-Preferences-Knoten auf fixen String `de/gecheckt/pdf-umbenenner` umgestellt – verhindert Verlust des gespeicherten Config-Pfads nach Code-Änderungen |
+
+---
+
+## Verbindlich verifizierte Spec-Punkte
+
+- Scheduler startet nur auf explizite Nutzeraktion – kein Autostart
+- Erster Tick läuft sofort nach Scheduler-Start (Initial Delay 0)
+- `scheduleWithFixedDelay`: nächster Tick erst N Sekunden nach Laufende
+- Laufkollision via nicht-blockierendem `RunLockPort.tryAcquire()` – kein Queuing
+- Manuelle Läufe bei aktivem Scheduler gesperrt (deterministisches Verhalten)
+- OS-Lock auf `.properties` während Scheduler läuft: Konfig-Tab read-only,
+  Speichern-Button deaktiviert, Eingabefelder nicht editierbar
+- Verlauf-Tab funktioniert korrekt bei aktivem Config-Lock
+- Stop während aktivem Lauf: Batch läuft zu Ende, danach `STOPPED`
+- App-Schließen bei aktivem Scheduler: Hinweisdialog, App schließt nicht
+- `SchedulerStatus` als immutable Snapshot via `AtomicReference`
+- `SchedulerState` mit 5 Werten: `STOPPED`, `STARTING`, `RUNNING_IDLE`,
+  `RUNNING_BATCH_ACTIVE`, `STOPPING_BATCH_ACTIVE`
+- No-op-Lauf (keine Kandidaten): „keine neuen Dokumente"; kein Fehlerstatus
+- Scheduler-Tab zeigt korrekte Anzeige: letzter Lauf + Gesamtzähler
+- Exception im Tick: gefangen, ERROR-geloggt, Executor läuft weiter
+- Non-Daemon-Thread; sauberer Shutdown via `awaitTermination`
+- Kein JavaFX im Modul `adapter-in-scheduler`
+- PIT im neuen Modul explizit deaktiviert
+- Code-Kommentare auf Deutsch; Logging auf Deutsch
+- JavaDoc auf allen neuen öffentlichen Ports, Use-Cases und Adapter-Methoden
+- Flyway ist die einzige Schema-Evolutionsquelle – keine Migration in V3.2
+
+---
+
+## Headless-Kompatibilität
+
+Der bestehende Batch-Betrieb über `--headless` bleibt vollständig erhalten.
+Scheduler-Properties (`scheduler.enabled`, `scheduler.interval.seconds`)
+werden im headless-Modus weder gelesen noch validiert. Der headless-Pfad
+verwendet keinen Scheduler-Codepfad und keinen Config-Lock.
+
+---
+
+## Datenbank-Migration
+
+**Keine.** Das DB-Schema bleibt unverändert auf V1 (`V1__initial_schema.sql`).
+Es wurden keine neuen Spalten und keine neuen Tabellen angelegt.
+
+---
+
+## Produkttest
+
+**Produkttest: bestanden**
+
+Manueller GUI-Produkttest gegen echten KI-Provider mit echten PDFs
+abgeschlossen. Der Scheduler hat PDFs automatisch erkannt, per KI benannt
+und in den Zielordner verschoben – vollautomatisch ohne Nutzeraktion.
+Alle wesentlichen Szenarien (Start/Stop, No-op-Lauf, aktive Verarbeitung,
+Verlauf-Tab bei aktivem Scheduler, App-Schließen-Guard) wurden verifiziert.
+
+---
+
+## Bekannte Einschränkungen
+
+| Einschränkung | Bewertung |
+|---|---|
+| JavaFX `NullPointerException` beim Schließen (`GraphicsPipeline.getPipeline() == null`) | JavaFX-interner Fehler nach Shutdown; kein Fehler im Anwendungscode; kein Datenverlust; kein Handlungsbedarf |
+| Unvollständige PDFs (noch im Kopiervorgang) können temporär `FAILED_RETRYABLE` erzeugen | Erwartet; bestehende Retry-Semantik behandelt das korrekt beim nächsten Tick |
+
+---
+
+## Nicht in V3.2
+
+- Token- und Kosten-Tracking (#74) → V3.x (eigene Spezifikation mit
+  Modell-Preistabelle, Persistenz-Strategie, EUR-Währung)
+- Headless-Daemon-Betrieb des Schedulers (`--watch`-Flag) → V3.x
+- Java WatchService (ereignisgesteuerte Ordnerüberwachung) → V3.x
+- Windows-Service-Integration (WinSW o.ä.) → V3.x
+- Modell-Filterung (OpenAI-Snapshots ausblenden) → V3.x
+- Dark Mode (#70) → V3.x
+- F1-Hilfe (#69) → V3.x
+- Log-Viewer in der GUI (#72) → V3.x
+- Excel-Export (#75) → V3.x
+- Automatische Update-Prüfung (#76) → V3.x
+- Neue KI-Provider, Architekturbrüche
+- Änderung der fachlichen Kernverarbeitung des PDF-Umbenenners
+
+---
+
+## Nächste Version
+
+**V3.x** – Token- und Kosten-Tracking als eigenständiges, vollständig
+durchdachtes Feature: Modell-Preistabelle (pro Modell, nicht pro Provider),
+EUR-Währung, Kostenanzeige im Summary-Banner, Modell-Filterung für
+OpenAI-kompatible Provider.
+
+---
+
+## Freigabeaussage
+
+V3.2 ist nach Prüfung fehlerfrei buildbar. Alle Kernanforderungen der
+hexagonalen Architektur sind eingehalten. Das neue Modul `adapter-in-scheduler`
+ist korrekt eingebunden (kein JavaFX, PIT deaktiviert, flatten aktiv).
+Die fachliche Kernverarbeitung des PDF-Umbenenners bleibt unverändert
+gegenüber V3.1. Headless-Betrieb vollständig unberührt. Manueller
+Produkttest bestanden. Keine Release-Blocker.
@@ -0,0 +1,332 @@
+# V1.1 – Ist-Stand des PDF-Umbenenners
+
+## Zweck dieses Dokuments
+
+Dieses Dokument beschreibt den **tatsächlichen Ist-Stand der Software bis einschließlich V1.1**.  
+Es ergänzt die bestehenden Spezifikations- und Projektdokumente um den konkret erreichten Erweiterungsstand nach der vollständig umgesetzten und freigegebenen V1.
+
+Ziel ist, dass eine KI oder ein Entwickler zusammen mit den übrigen Repository-Dokumenten den aktuellen Funktionsumfang und die Architektur **präzise und ohne Rückgriff auf Chat-Verläufe** verstehen kann.
+
+Dieses Dokument ist **kein Soll-Konzept** und **kein neues Arbeitspaket**, sondern eine Beschreibung des erreichten Stands.
+
+---
+
+## Einordnung des Stands
+
+### Ausgangsbasis
+
+Vor V1.1 lag eine vollständig umgesetzte, getestete, dokumentierte und freigegebene **V1** des Projekts vor.  
+Diese V1 entsprach dem Umsetzungsstand der Meilensteine **M1 bis M8**.
+
+Damit war insbesondere bereits vorhanden:
+
+- vollständiges Maven-Multi-Module-Projekt
+- strikte hexagonale Architektur
+- Batch-Verarbeitung über Standalone-JAR
+- PDF-Erkennung und PDF-Textauslese
+- SQLite-Persistenz
+- Retry-, Skip- und Statuslogik
+- KI-gestützte Ermittlung eines Benennungsvorschlags
+- Dateinamensbildung und Zielkopie
+- Logging, Qualitätsabsicherung, Dokumentation und Freigabestand
+
+### Ziel von V1.1
+
+V1.1 wurde bewusst **klein und minimal-invasiv** definiert.
+
+Es handelt sich **nicht** um einen allgemeinen V2-Ausbau und **nicht** um einen Produktumbau mit GUI, Installer oder EXE.
+
+Der Fokus von V1.1 ist ausschließlich:
+
+- Erweiterung der bestehenden KI-Anbindung um **native Claude-Unterstützung**
+- gleichzeitiger Erhalt des bisherigen **OpenAI-kompatiblen Wegs**
+- Mehrprovider-Konfiguration mit **genau einem aktiven Provider**
+- Wahrung der bestehenden Architekturprinzipien
+- Wahrung der fachlichen und technischen Regeln aus V1
+- Abwärtskompatibilität bestehender Konfigurationen
+
+---
+
+## Inhaltlicher Umfang von V1.1
+
+V1.1 erweitert die bestehende Anwendung um eine **Mehrprovider-fähige KI-Konfiguration**, bei der genau **ein Provider aktiv** ist.
+
+### In V1.1 enthalten
+
+- Unterstützung von **zwei real nutzbaren KI-Providern**
+  - OpenAI-kompatibler Provider
+  - nativer Claude-Provider
+- Properties-basierte Konfiguration für mehrere Provider
+- Auswahl genau **eines aktiven Providers**
+- Beibehaltung des bisherigen fachlichen KI-Vertrags
+- Integration der Providerwahl in die bestehende technische Konfiguration
+- Migration alter V1-Konfigurationen auf die neue Struktur
+- Sicherung alter Konfigurationen über `.bak`
+- vollständige Tests und Nachschärfung der Build-/Qualitätshygiene
+
+### In V1.1 ausdrücklich **nicht** enthalten
+
+- GUI
+- Installer
+- EXE-Paketierung
+- mehrere Profile pro Provider
+- automatischer Fallback zwischen Providern
+- neue fachliche Regeln für Dateinamen
+- neue Retry-Semantik
+- neue Statussemantik
+- neue Persistenz-Wahrheiten
+- Änderungen am Grundprinzip des Batch-Betriebs
+
+---
+
+## Fachlich-technische Kernaussage von V1.1
+
+Die Anwendung verarbeitet weiterhin OCR-verarbeitete PDF-Dateien lokal und erzeugt daraus im Erfolgsfall korrekt benannte Zielkopien.
+
+Der Unterschied zu V1 ist:
+
+> Die Ermittlung des KI-basierten Benennungsvorschlags kann nun wahlweise
+> über einen **OpenAI-kompatiblen Provider** oder über die **native Claude-API**
+> erfolgen.
+
+Dabei bleibt für den restlichen fachlichen Ablauf entscheidend:
+
+- der Input bleibt ein aufbereiteter Dokumenttext
+- die KI liefert weiterhin denselben fachlichen Vorschlagsinhalt
+- der restliche Verarbeitungsfluss bleibt unverändert
+
+---
+
+## Unveränderte Regeln aus V1
+
+V1.1 ändert **nicht** die fachlichen Kernregeln des Systems.
+
+Insbesondere unverändert bleiben:
+
+- Zielformat: `YYYY-MM-DD - Titel.pdf`
+- Dublettenregel `(1)`, `(2)`, …
+- 20-Zeichen-Regel für den Basistitel
+- deutsche, verständliche Titel
+- Quelldatei bleibt unverändert
+- Fingerprint-basierte Identifikation
+- SQLite als lokaler Persistenzspeicher
+- Retry- und Skip-Regeln
+- Statusmodell
+- Run-Lock
+- Start über Standalone-JAR / Task Scheduler
+- keine Dauerlauf-Anwendung
+- keine GUI / kein Webserver / kein App-Server
+
+---
+
+## Architekturstand in V1.1
+
+V1.1 wahrt die bestehende Architektur.
+
+### Unverändert gültig
+
+- strikte hexagonale Architektur
+- Ports and Adapters
+- Abhängigkeiten zeigen nach innen
+- keine Infrastruktur im Domain-Kern
+- keine direkte Adapter-zu-Adapter-Kopplung
+- Logging bleibt technische Infrastruktur
+- Konfiguration bleibt technische Infrastruktur
+- Bootstrap verdrahtet die konkrete Laufzeitumgebung
+
+### Bedeutung für die KI-Integration
+
+Die Mehrprovider-Fähigkeit wird **architekturtreu** eingeführt:
+
+- der fachliche/application-seitige KI-Vertrag bleibt erhalten
+- die Provider-spezifischen Unterschiede liegen in den technischen Adaptern
+- die konkrete Providerauswahl erfolgt über Konfiguration und Bootstrap
+- es entsteht keine provider-spezifische Fachlogik im Kern
+
+---
+
+## KI-Provider in V1.1
+
+### Unterstützte Provider
+
+V1.1 unterstützt genau diese zwei Providerarten:
+
+1. **OpenAI-kompatibel**
+2. **Claude nativ**
+
+### Aktiver Provider
+
+Es gibt immer **genau einen aktiven Provider**.
+
+V1.1 führt **keinen** automatischen Fallback zwischen Providern ein.  
+Wenn der aktive Provider fehlschlägt, gilt der bestehende Fehler- und Retry-Rahmen.
+
+### Keine Profilverwaltung
+
+Pro Provider gibt es in V1.1 genau **eine** Konfiguration.  
+Benannte Profile oder mehrere alternative Konfigurationssätze pro Provider sind nicht Bestandteil von V1.1.
+
+---
+
+## KI-Vertrag bleibt unverändert
+
+V1.1 ändert **nicht** den fachlichen Ergebnisvertrag der KI.
+
+Die Erweiterung betrifft den technischen Zugriffsweg auf die KI, **nicht** den fachlichen Inhalt der KI-Antwort.
+
+Damit bleibt der Grundsatz bestehen:
+
+- die KI liefert denselben fachlichen Vorschlagsinhalt wie zuvor
+- die Anwendung behält die Hoheit über Validierung, Datumsauflösung, Titelregeln und weitere technische Verarbeitung
+- der restliche Systemablauf bleibt gegenüber V1 stabil
+
+---
+
+## Konfigurationsmodell in V1.1
+
+### Allgemeiner Grundsatz
+
+Die `.properties`-Datei bleibt die **Wahrheit** der Konfiguration.
+
+### Erweiterung in V1.1
+
+Die Konfiguration kann nun mehrere Provider-Konfigurationen enthalten, von denen genau **eine aktiv** ist.
+
+### Abwärtskompatibilität
+
+Bestehende V1-Konfigurationen bleiben nutzbar.
+
+Dazu wurde in V1.1 vorgesehen:
+
+- Erkennung alter Konfigurationsstruktur
+- Migration auf die neue Struktur beim ersten Start
+- vorherige Anlage einer Sicherung mit `.bak`
+
+### Legacy-Kompatibilität beim API-Key
+
+Für den OpenAI-kompatiblen Provider wurde die Abwärtskompatibilität auch für bestehende API-Key-Setups beibehalten.
+
+Die Auflösung erfolgt in dieser Reihenfolge:
+
+1. spezifische Umgebungsvariable für den OpenAI-kompatiblen Provider
+2. bisherige Legacy-Umgebungsvariable
+3. Property-basierter API-Key
+
+Dadurch brechen bestehende Setups nicht still.
+
+### Strikte Provider-Validierung
+
+Die Konfiguration des aktiven Providers wird vor dem eigentlichen Lauf sauber validiert.
+
+Dazu gehört insbesondere die Base-URL-Prüfung:
+
+- syntaktisch gültige URI
+- absolute URI
+- nur `http` oder `https`
+
+Ungültige Provider-Konfiguration ist eine ungültige Startkonfiguration und verhindert den Laufbeginn.
+
+---
+
+## Persistenz und Nachvollziehbarkeit
+
+Das bestehende Zwei-Ebenen-Modell bleibt erhalten:
+
+- Dokument-Stammsatz
+- Versuchshistorie
+
+V1.1 führt **keine neue Persistenz-Wahrheit** ein.
+
+Die durch V1 etablierten Regeln zu Status, Retry, Zielerfolg, Proposal-Quelle und Historisierung bleiben in Kraft.
+
+Die Erweiterung um mehrere Provider dient der technisch sauberen Mehrprovider-Nutzung und der konsistenten Nachvollziehbarkeit des verwendeten Providers im Rahmen der bestehenden Architektur.
+
+---
+
+## Qualitäts- und Stabilisierungsschritte nach der V1.1-Implementierung
+
+Nach der funktionalen Einführung von V1.1 wurde der Stand zusätzlich qualitativ nachgeschärft.
+
+Diese Nachschärfungen gehören zum erreichten Ist-Stand.
+
+### 1. Rückwärtskompatibilität und Provider-Validierung
+
+Es wurden Korrekturen durchgeführt für:
+
+- Legacy-Fallback beim OpenAI-kompatiblen API-Key
+- strikte Validierung der Provider-Base-URL
+- Sicherstellung, dass alte Setups nicht still brechen
+
+### 2. Dokumentation
+
+Es wurde eine README für das Repository ergänzt, damit der Projektstand und die Grundbenutzung nachvollziehbar dokumentiert sind.
+
+### 3. Compiler-, Test- und Build-Hygiene
+
+Es wurden mehrere kleinere Qualitätskorrekturen durchgeführt, unter anderem:
+
+- Bereinigung von Raw-Type-/Unchecked-Warnungen in Tests
+- Beseitigung veralteter API-Nutzung in Bootstrap-Testhilfen
+- Bereinigung des Logging-Klassenpfads im Testkontext
+- bewusste Konfiguration des Annotation Processings
+
+### 4. Mutationstest- und Build-Verbesserungen
+
+Die Qualität des Test- und PIT-Stands wurde gezielt verbessert, insbesondere in:
+
+- `adapter-out`
+- `bootstrap`
+
+Zusätzlich wurde ein PIT-Timeout bereinigt, das durch einen langsamen Integrationstest mit Netzwerkaufruf verursacht wurde.
+
+### 5. Bewertung verbliebener Build-Hinweise
+
+Verbleibende Log4j2-/Shade-Hinweise wurden geprüft und als funktional unkritisch eingeordnet, soweit sie keine reale Auswirkung auf den Produktivbetrieb haben.
+
+---
+
+## Ergebnisstatus von V1.1
+
+V1.1 ist als **fertiger, implementierter und getesteter Ist-Stand** zu verstehen.
+
+Das bedeutet:
+
+- die Erweiterung ist umgesetzt
+- die Erweiterung ist in die bestehende Architektur eingebettet
+- die relevanten Qualitäts- und Stabilitätskorrekturen wurden nachgezogen
+- der Projektstand nach V1.1 ist gegenüber V1 fachlich stabil erweitert und technisch nachgeschärft
+
+---
+
+## Verhältnis zu den übrigen Repository-Dokumenten
+
+Dieses Dokument ersetzt **nicht** die bestehenden Spezifikationsdokumente.
+
+Es ergänzt sie um die Aussage:
+
+> **Was ist nach Abschluss von V1.1 zusätzlich tatsächlich vorhanden?**
+
+Für eine vollständige Einordnung bleiben weiterhin maßgeblich:
+
+- `CLAUDE.md`
+- `docs/specs/technik-und-architektur.md`
+- `docs/specs/fachliche-anforderungen.md`
+- `docs/specs/meilensteine.md`
+
+Dieses Dokument beschreibt den **erreichten zusätzlichen Ist-Zustand bis einschließlich V1.1**.
+
+---
+
+## Kompakte Zusammenfassung für KI-Systeme
+
+Wenn eine KI diesen Stand kurz einordnen soll, gilt:
+
+- V1 des `pdf-umbenenner` war vollständig umgesetzt und freigegeben
+- V1.1 ist eine **kleine, minimal-invasive Erweiterung**
+- V1.1 fügt **native Claude-Unterstützung** hinzu
+- der bisherige **OpenAI-kompatible Weg bleibt erhalten**
+- die Konfiguration unterstützt mehrere Provider, aber **genau einen aktiven Provider**
+- bestehende Konfigurationen bleiben per Migration und Legacy-Fallback kompatibel
+- fachliche Regeln, Architekturprinzipien und Kernverhalten aus V1 bleiben unverändert
+- nach der Implementierung wurden zusätzliche Qualitäts-, Build- und Testhygiene-Maßnahmen durchgeführt
+- der Ist-Zustand des Projekts umfasst damit **V1 + V1.1**
@@ -0,0 +1,120 @@
+# V2.6 – Titellänge parametrisierbar machen
+
+**Status:** Entwurf  
+**Erstellt:** 2026-04-22  
+**Autor:** Marcus (mit Claude als Mentor)
+
+---
+
+## Ziel
+
+Der maximale Basistitel für KI-generierte PDF-Namen wird nicht mehr hardcodiert,
+sondern ist über die Konfigurationsdatei steuerbar. Alle bisherigen Magic Numbers
+(20 und 60 Zeichen) werden durch den konfigurierten Wert ersetzt.
+
+---
+
+## Hintergrund
+
+### Bisheriger Zustand
+- Titellänge war mit 20 Zeichen im Prompt und 60 Zeichen in der Validierung hardcodiert
+- Kein zentraler Konfigurationsparameter, Werte über ~20 Dateien verstreut
+- 60-Zeichen-Limit wurde im Rahmen des Produkttests als pragmatischer Zwischenwert eingeführt
+
+### Motivation
+- Verschiedene Einsatzszenarien erfordern unterschiedliche Titellängen
+- Dateinamenlimits je nach Zielsystem unterschiedlich (siehe Recherche unten)
+
+### Recherchierte Dateinamenlimits (nur Dateiname, ohne Pfad)
+
+| System | Limit |
+|---|---|
+| Windows 10 / Windows Server 2022 (NTFS) | 255 Zeichen |
+| Synology NAS – Btrfs (unverschlüsselt) | 255 Zeichen |
+| Synology NAS – Btrfs (verschlüsselt) | ~143 Zeichen |
+
+**Hinweis:** Der generierte Dateiname hat das Format `YYYY-MM-DD - <Titel>.pdf`,
+was bereits 18 Zeichen Overhead bedeutet (Datum + Trennzeichen + Dateiendung).
+Das sicherste Maximum für verschlüsselte Synology-Volumes ist daher **120 Zeichen**
+für den Basistitel (143 − 18 = 125, mit Puffer auf 120 gerundet).
+
+---
+
+## Fachliche Anforderungen
+
+### Neuer Konfigurationsparameter
+
+- **Name:** `ai.title.max.length` (finale Benennung obliegt der Implementierung)
+- **Typ:** positive Ganzzahl
+- **Defaultwert:** `60` (bisheriger Wert bleibt erhalten, kein Breaking Change)
+- **Speicherort:** `.properties`-Konfigurationsdatei
+
+---
+
+### Validierungsregeln
+
+| Wert | Typ | Verhalten |
+|---|---|---|
+| Kein Wert / leer | Fehler | Pflichtfeld, Start wird abgebrochen |
+| Keine Ganzzahl (z. B. „abc", „1.5") | Fehler | Ungültiger Typ, Start wird abgebrochen |
+| < 1 | Fehler | Wert muss positiv sein, Start wird abgebrochen |
+| 1–9 | Fehler | Minimum ist 10 Zeichen, Start wird abgebrochen |
+| 10–39 | Warnung | „Titellänge unter 40 Zeichen – KI-Ergebnisse können unvollständig sein, da Absender allein bereits 15–20 Zeichen benötigt" |
+| 40–99 | OK | Normaler Betrieb, keine Meldung |
+| 100–120 | Warnung | „Hohe Titellänge – Kompatibilität mit verschlüsselten Volumes prüfen" |
+| > 120 | Fehler | Überschreitet sicheres Limit für verschlüsselte Synology-Volumes, Start wird abgebrochen |
+
+---
+
+### GUI – Konfigurationseditor
+
+- Neues Texteingabefeld im Bereich **„Verarbeitungslimits"**
+- Beschriftung: **„Max. Titellänge (Zeichen)"**
+- Validierung erfolgt beim Speichern – ungültige Werte werden **nicht** gespeichert
+- Warnungen und Fehlermeldungen erscheinen im **Meldungsbereich** (unten in der GUI)
+- Warnungen blockieren das Speichern **nicht**, Fehler hingegen schon
+
+---
+
+### Verarbeitung / Backend
+
+- Alle hardcodierten `20`- und `60`-Zeichen-Limits werden durch den konfigurierten Wert ersetzt
+- **Keine Magic Numbers** mehr im Produktionscode
+- Der Wert wird beim Start geladen, validiert und an alle betroffenen Komponenten weitergereicht
+- Betroffen sind mindestens:
+  - `AiResponseValidator`
+  - `TargetFilenameBuildingService`
+  - Prompt-Template (Hinweistext an die KI)
+  - JavaDoc aller betroffenen Klassen
+
+---
+
+### Prompt-Template
+
+- Der Hinweis auf die Zeichenbegrenzung im Prompt-Template (`config/prompts/template.txt`)
+  wird ebenfalls dynamisch mit dem konfigurierten Wert befüllt
+- **Hinweis:** Das Prompt-Template liegt außerhalb des JARs und wird zur Laufzeit gelesen.
+  Die Implementierung muss sicherstellen, dass der konfigurierte Wert zur Laufzeit
+  in den Prompt eingesetzt wird (z. B. per Platzhalter-Ersetzung).
+
+---
+
+## Nicht in V2.6 enthalten
+
+- Automatisches Kürzen von zu langen KI-Titeln
+- Pfadlängen-Validierung (Gesamtpfad inkl. Ordner)
+- Unterschiedliche Limits je nach Zielsystem (nur ein globaler Wert)
+
+---
+
+## Abnahmekriterien
+
+- [ ] Neuer Parameter ist in der `.properties`-Datei konfigurierbar
+- [ ] Defaultwert 60 ist abwärtskompatibel (bestehende Configs ohne den Parameter funktionieren)
+- [ ] Alle Validierungsregeln greifen korrekt (Fehler blockieren Start/Speichern, Warnungen nicht)
+- [ ] GUI zeigt das neue Feld im richtigen Bereich
+- [ ] Meldungsbereich zeigt passende Warn- und Fehlertexte
+- [ ] Keine hardcodierten 20- oder 60-Zeichen-Limits mehr im Produktionscode
+- [ ] Prompt-Template enthält den konfigurierten Wert zur Laufzeit
+- [ ] Alle bestehenden Tests werden angepasst
+- [ ] `mvn clean verify` ist grün
@@ -0,0 +1,297 @@
+# V2.7 – GUI-Verarbeitungslauf mit Live-Verfolgung
+
+**Status:** Freigegeben  
+**Erstellt:** 2026-04-22  
+**Überarbeitet:** 2026-04-22 (nach Review, finale Version)  
+**Autor:** Marcus (mit Claude als Mentor)
+
+---
+
+## Ziel
+
+V2.7 erweitert die JavaFX-GUI um einen zweiten Tab „Verarbeitungslauf", über den der Benutzer
+einen Batch-Lauf direkt aus der GUI starten und dessen Fortschritt in Echtzeit verfolgen kann.
+Der bestehende headless-Betrieb über den Windows Task Scheduler bleibt unverändert erhalten.
+
+---
+
+## Hintergrund
+
+### Bisheriger Zustand
+- Die GUI dient in V2.0–V2.6 ausschließlich der Konfiguration und technischen Validierung
+- Ein Verarbeitungslauf kann nur über die Kommandozeile bzw. eine Batch-Datei gestartet werden
+- Es gibt keine Möglichkeit, den Fortschritt eines laufenden Batches live zu beobachten
+
+### Motivation
+- Der manuelle Kommandozeilenstart ist für den Alltagsbetrieb umständlich
+- Ohne Live-Anzeige ist unklar, ob und wie schnell die Verarbeitung voranschreitet
+- Eine einzelne Datei wird schnell verarbeitet – eine Gesamtfortschrittsanzeige ist daher
+  sinnvoller als eine dateiweise Einzelanzeige
+
+---
+
+## Zielbild
+
+Nach Abschluss von V2.7 kann der Benutzer:
+
+1. Im neuen Tab „Verarbeitungslauf" einen Batch-Lauf starten
+2. Den Gesamtfortschritt über alle Dateien live verfolgen
+3. Jede abgeschlossene Datei mit Ergebnis in einer Liste sehen
+4. Das KI-Reasoning zu einer Datei per Klick im Seitenbereich einsehen
+5. Den laufenden Batch per Soft-Stop sauber abbrechen
+
+---
+
+## Fachliche Anforderungen
+
+### Neuer Tab „Verarbeitungslauf"
+
+- Der bestehende Tab „Konfiguration" bleibt Tab 1 – unverändert
+- Tab 2 heißt **„Verarbeitungslauf"**
+- Tab-Struktur war in V2.0 bereits vorbereitet
+
+---
+
+### Layout Tab 2
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  [Fortschrittsbalken]                  12 / 47 Dateien  │
+├──────────────────────────────────┬──────────────────────┤
+│  Ergebnisliste                   │  Seitenbereich       │
+│  (scrollbar)                     │  (KI-Reasoning)      │
+│                                  │                      │
+│                                  │                      │
+├──────────────────────────────────┴──────────────────────┤
+│  Meldungs- und Zusammenfassungsbereich                  │
+├─────────────────────────────────────────────────────────┤
+│  [Starten]  [Abbrechen]                                 │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+### Meldungs- und Zusammenfassungsbereich
+
+Der untere Bereich des Tab 2 dient als **einheitlicher Meldungs- und Zusammenfassungsbereich**.
+Er übernimmt zwei Rollen:
+
+- **Meldungsbereich** – zeigt Startfehler, Hinweise (z. B. 0 Dateien) und technische Exceptions
+- **Zusammenfassung** – zeigt nach Laufende: `{X} erfolgreich, {X} fehlgeschlagen, {X} übersprungen`
+
+Während des Laufs ist der Bereich leer oder zeigt den letzten Statushinweis.
+Es gibt in Tab 2 keinen separaten zweiten Meldungsbereich.
+
+---
+
+### Konfigurationsquelle beim Start
+
+- Der Lauf verwendet ausschließlich den **zuletzt gespeicherten Stand** der `.properties`-Datei
+- Ungespeicherte Änderungen im Konfigurationseditor (Tab 1) fließen **nicht** in den Lauf ein
+- Der Starten-Button prüft vor dem Lauf, ob die gespeicherte Konfiguration lauffähig ist –
+  nicht den aktuellen Editorzustand
+
+---
+
+### Startvoraussetzungen und Startfehler
+
+Ein Lauf startet nur, wenn alle folgenden Voraussetzungen erfüllt sind:
+
+| Voraussetzung | Verhalten bei Fehler |
+|---|---|
+| Gespeicherte Konfiguration vorhanden und lauffähig | Fehlermeldung, kein Lauf |
+| Quellordner vorhanden und lesbar | Fehlermeldung, kein Lauf |
+| Zielordner vorhanden oder anlegbar | Fehlermeldung, kein Lauf |
+| SQLite-Datei nutzbar | Fehlermeldung, kein Lauf |
+| API-Key vorhanden | Fehlermeldung, kein Lauf |
+| Kein anderer Verarbeitungslauf in dieser Anwendungsinstanz aktiv | Fehlermeldung, kein Lauf |
+
+Bei einem Startfehler:
+- Erscheint eine klare Fehlermeldung im Meldungs- und Zusammenfassungsbereich
+- Fortschrittsbalken und Ergebnisliste bleiben unverändert
+- Starten-Button bleibt aktiv, Abbrechen-Button bleibt deaktiviert
+
+---
+
+### Verhalten bei 0 verarbeitbaren Dateien
+
+- Kein technischer Fehler
+- Kein Lauf im eigentlichen Sinne
+- Hinweis im Meldungs- und Zusammenfassungsbereich: „Keine verarbeitbaren Dateien im Quellordner gefunden"
+- Zusammenfassung: `0 erfolgreich, 0 fehlgeschlagen, 0 übersprungen`
+
+---
+
+### Fortschrittsbalken
+
+- Die zu verarbeitende Dateimenge wird **einmalig beim Start** bestimmt
+- Der Nenner bleibt für den gesamten Lauf **konstant** – Dateien die während des Laufs
+  im Quellordner auftauchen oder verschwinden, werden nicht berücksichtigt
+- Gezählt werden **alle abgeschlossenen** Dateien: erfolgreich + fehlgeschlagen + übersprungen
+- Daneben wird der Zählerstand angezeigt, z. B. „12 / 47 Dateien"
+- Vor dem ersten Start: leer / 0 %
+
+---
+
+### Statusmodell
+
+Jede Datei erhält nach Abschluss genau einen der folgenden Status:
+
+| Status | Icon | Bedeutung |
+|---|---|---|
+| Erfolgreich | ✅ | Datei wurde umbenannt, Zieldatei erzeugt |
+| Fehlgeschlagen (retryable) | ⚠️ | Transienter Fehler, wird beim nächsten Lauf erneut versucht |
+| Fehlgeschlagen (permanent) | ❌ | Inhaltsfehler, kein weiterer Retry |
+| Übersprungen | ⏭️ | Datei war bereits verarbeitet oder wurde bewusst ausgelassen |
+
+Alle vier Status zählen als **abgeschlossen** im Sinne des Fortschrittsbalkens.
+
+---
+
+### Ergebnisliste
+
+Jede abgeschlossene Datei erscheint als neue Zeile in der Liste.
+Nach Abschluss jeder Datei erscheint **ohne manuellen Refresh** ein neuer Eintrag.
+Die Liste wächst während des Laufs von oben nach unten.
+
+| Spalte | Erfolg | Fehler / Übersprungen |
+|---|---|---|
+| Status-Icon | ✅ / ⚠️ / ❌ / ⏭️ | wie links |
+| Originaldateiname | Quelldateiname | Quelldateiname |
+| Neuer Dateiname | Finaler Zieldateiname | `—` |
+| Datum | Ermitteltes Datum | `—` |
+| Dauer | Verarbeitungszeit in Sekunden | Verarbeitungszeit in Sekunden |
+
+- Klick auf eine Zeile zeigt Details im **Seitenbereich**
+- Die Liste ist scrollbar
+- Die Liste ist **nicht persistent**: bleibt nur für die Dauer des aktuellen Programmstarts
+- Bei einem neuen Lauf innerhalb desselben Programmstarts wird die Liste geleert
+- Nach Programmstart ist die Liste leer
+
+---
+
+### Seitenbereich (KI-Reasoning)
+
+- Rechts neben der Ergebnisliste, fest im Layout verankert (kein Popup, kein Dialog)
+- Zeigt nach Klick auf eine Zeile:
+  - Originaldateiname
+  - Ermittelter Titel
+  - Ermitteltes Datum
+  - KI-Reasoning (Volltext)
+- Liegt für einen Eintrag kein KI-Reasoning vor (Fehler vor KI-Aufruf, übersprungen),
+  erscheint der Hinweistext: „Für diesen Eintrag liegt kein KI-Reasoning vor."
+- Vor dem ersten Klick: Hinweistext „Datei auswählen für Details"
+- Bei neuem Lauf wird der Seitenbereich geleert
+
+---
+
+### Starten-Button
+
+- Startet den Verarbeitungslauf über alle Dateien im konfigurierten Quellordner
+- Verwendet die **gespeicherte** Konfiguration – nicht den aktuellen Editorzustand
+- Gleiches fachliches Batch-Verhalten wie der headless-Betrieb:
+  gleiche Anwendungslogik, gleicher Use Case, nur andere Präsentationsschicht
+- Keine Dateiauswahl – alle Dateien werden verarbeitet
+- Während des Laufs: deaktiviert
+- Nach Abschluss oder Abbruch: wieder aktiv
+
+---
+
+### Abbrechen-Button
+
+- Nur während eines laufenden Batches aktiv, sonst deaktiviert
+- Verhalten: **Soft-Stop**
+  - Die aktuell in Bearbeitung befindliche Datei wird vollständig fertig verarbeitet
+  - Das Stop-Flag wird nach Abschluss jeder Datei und vor Start der nächsten Datei geprüft –
+    niemals mitten in einer atomaren Persistenzoperation
+  - Danach wird der Lauf sauber beendet, keine halbfertigen Zustände in der SQLite-Datenbank
+- Nach dem Soft-Stop erscheint die Zusammenfassung im Meldungs- und Zusammenfassungsbereich
+
+---
+
+### Konfiguration während des Laufs
+
+- Tab 1 „Konfiguration" wird während eines laufenden Verarbeitungslaufs **gesperrt**
+- Im Konfiguration-Tab erscheint ein sichtbarer Hinweis:
+  „Konfiguration während eines laufenden Verarbeitungslaufs nicht editierbar"
+- Nach Abschluss, Abbruch oder unerwarteter Exception wird Tab 1 wieder freigegeben
+
+---
+
+### Verhalten bei unerwarteter technischer Exception
+
+Tritt während des Laufs eine unerwartete Exception auf:
+
+- Die GUI wechselt in einen definierten terminalen Zustand:
+  - Starten-Button: aktiv
+  - Abbrechen-Button: deaktiviert
+  - Tab 1: entsperrt
+  - Meldungs- und Zusammenfassungsbereich: Fehlermeldung sichtbar
+- Es entsteht kein „hängender" UI-Zustand
+
+---
+
+### Fenster schließen während eines laufenden Laufs
+
+- Schließt der Benutzer das Fenster während ein Lauf aktiv ist,
+  wird der Close-Request abgefangen
+- Es erscheint ein Hinweisdialog mit zwei Optionen:
+  - **„Nicht schließen"** – Lauf läuft weiter
+  - **„Lauf beenden und schließen"** – Soft-Stop wird ausgelöst,
+    nach Abschluss der aktuellen Datei schließt die Anwendung
+- Kein Hard-Abbruch ohne Benutzerentscheidung
+
+---
+
+### Parallele Läufe
+
+- Pro Anwendungsinstanz ist **nur ein Verarbeitungslauf gleichzeitig** zulässig
+- Ein zweiter Startversuch während ein Lauf aktiv ist wird verweigert mit der Meldung:
+  „Ein Verarbeitungslauf ist bereits aktiv."
+- **Bekannte Einschränkung:** Ein gleichzeitiger externer headless-Lauf (Windows Task Scheduler)
+  wird von der GUI nicht aktiv erkannt und nicht technisch geblockt.
+  Der Benutzer ist selbst verantwortlich, parallele Läufe zu vermeiden.
+  Diese Einschränkung ist seit V2.0 dokumentiert und bleibt in V2.7 unverändert bestehen.
+
+---
+
+## Nicht in V2.7 enthalten
+
+- Dateiauswahl (welche Dateien verarbeitet werden sollen)
+- Einzeldatei-Fortschrittsanzeige
+- Historien-Tab / SQLite-Ansicht
+- Kosten-Tracking
+- Automatischer Neustart nach Abschluss
+- Benachrichtigungen (Windows-Tray, Toast)
+- Parallelverarbeitung mehrerer Dateien
+- Technisches Locking gegen externe headless-Läufe
+
+---
+
+## Abnahmekriterien
+
+- [ ] Tab 2 „Verarbeitungslauf" ist in der GUI vorhanden und erreichbar
+- [ ] Starten-Button verwendet ausschließlich die gespeicherte Konfiguration
+- [ ] Starten-Button startet den Batch-Lauf über alle Dateien im Quellordner
+- [ ] Die Dateimenge wird beim Start einmalig bestimmt; der Nenner des Fortschrittsbalkens bleibt während des gesamten Laufs konstant
+- [ ] Fortschrittsbalken zählt alle abgeschlossenen Dateien (erfolgreich + fehlgeschlagen + übersprungen)
+- [ ] Nach Abschluss jeder Datei erscheint ohne manuellen Refresh ein neuer Eintrag in der Ergebnisliste
+- [ ] Alle fünf Spalten der Ergebnisliste sind für Erfolgsfälle korrekt befüllt
+- [ ] Spalte „Neuer Dateiname" und „Datum" zeigen `—` für Fehler- und Übersprungen-Fälle
+- [ ] Alle vier Status-Icons sind korrekt: ✅ ⚠️ ❌ ⏭️
+- [ ] Klick auf Zeile zeigt KI-Reasoning im Seitenbereich
+- [ ] Einträge ohne KI-Reasoning zeigen den definierten Hinweistext im Seitenbereich
+- [ ] Seitenbereich zeigt vor erstem Klick den Hinweistext „Datei auswählen für Details"
+- [ ] Soft-Stop beendet den Lauf nach Abschluss der aktuellen Datei; keine weitere Datei wird begonnen
+- [ ] Meldungs- und Zusammenfassungsbereich zeigt nach Laufende die Zusammenfassung mit korrekten Zählern
+- [ ] Tab 1 ist während des Laufs gesperrt, Hinweis ist sichtbar
+- [ ] Tab 1 wird nach Abschluss, Abbruch oder Exception wieder entsperrt
+- [ ] Bei unerwarteter Exception wechselt die GUI in den definierten terminalen Zustand
+- [ ] Ergebnisliste und Seitenbereich sind nach Programmstart leer
+- [ ] Ergebnisliste und Seitenbereich werden bei neuem Lauf geleert
+- [ ] Start mit nicht lauffähiger Konfiguration wird verweigert; Fehlermeldung erscheint im Meldungs- und Zusammenfassungsbereich
+- [ ] Start bei leerem Quellordner erzeugt keinen Fehler; Hinweis erscheint im Meldungs- und Zusammenfassungsbereich
+- [ ] Zweiter Startversuch während laufendem Lauf wird verweigert; Meldung erscheint
+- [ ] Close-Request während Lauf öffnet Hinweisdialog mit zwei Optionen
+- [ ] headless-Betrieb ist unverändert funktionsfähig
+- [ ] `mvn clean verify` ist grün
@@ -0,0 +1,193 @@
+# V2.8 – Selektive Wiederverarbeitung und Status-Reset in der Ergebnisliste
+
+**Status:** Freigegeben  
+**Erstellt:** 2026-04-23  
+**Überarbeitet:** 2026-04-23 (nach zwei Reviews, finale Version)  
+**Autor:** Marcus (mit Claude als Mentor)
+
+---
+
+## Ziel
+
+V2.8 erweitert den Tab „Verarbeitungslauf" um die Möglichkeit, einzelne oder mehrere Dateien
+aus der Ergebnisliste gezielt erneut verarbeiten zu lassen oder deren DB-Status zurückzusetzen –
+ohne die gesamte Datenbank löschen zu müssen.
+
+---
+
+## Hintergrund
+
+### Bisheriger Zustand
+- Nach einem abgeschlossenen Lauf sind alle Ergebnisse in der Ergebnisliste sichtbar
+- Dateien mit Status `FAILED_FINAL` oder `DONE` können nur durch manuelles Löschen der
+  SQLite-Datenbank erneut verarbeitet werden
+- Es gibt keine Möglichkeit, einzelne Dateien selektiv zurückzusetzen oder neu zu starten
+
+### Motivation
+- Nach Anpassung des Prompts oder Wechsel des KI-Modells sollen bereits verarbeitete Dateien
+  erneut verarbeitet werden können – ohne Datenverlust für andere Dokumente
+- Permanent fehlgeschlagene Dateien sollen nach Behebung der Ursache gezielt neu gestartet
+  werden können
+- Zwei klar getrennte Aktionen decken unterschiedliche Anwendungsfälle ab:
+  sofortige Wiederverarbeitung vs. Reset für den nächsten regulären Lauf
+
+---
+
+## Zielbild
+
+Nach Abschluss von V2.8 kann der Benutzer:
+
+1. Eine oder mehrere Dateien in der Ergebnisliste selektieren
+2. Per „Erneut verarbeiten" einen sofortigen Mini-Lauf nur für die selektierten Dateien starten
+3. Per „Status zurücksetzen" den DB-Status zurücksetzen ohne sofortige Verarbeitung –
+   die Dateien werden beim nächsten regulären Lauf automatisch mitgenommen
+
+---
+
+## Fachliche Anforderungen
+
+### Selektion in der Ergebnisliste
+
+- Es gibt genau **eine fachliche Selektion** je Ergebniszeile
+- Checkbox, Zeilenklick, Shift/Strg und „Alle auswählen" wirken immer auf **dieselbe Selektionsmenge**
+- Jede Zeile erhält eine **Checkbox** am linken Rand
+- **Shift/Strg-Mehrfachselektion** wie im Windows Explorer ist möglich
+- Eine Checkbox **„Alle auswählen"** oberhalb der Liste selektiert/deselektiert alle Einträge
+- Alle Status sind selektierbar: ✔ erfolgreich, ⚠ retryable, ✘ permanent, ► übersprungen
+- Die Selektion bleibt erhalten bis ein neuer Lauf gestartet wird
+- Während eines laufenden Mini-Laufs ist die Selektion **gesperrt** –
+  Änderungen der Selektion nach Laufstart haben keinen Einfluss auf den laufenden Batch
+
+---
+
+### Button „Erneut verarbeiten"
+
+- **Aktion:** DB-Status der selektierten Dateien zurücksetzen + sofortiger Mini-Lauf
+  nur für diese Dateien
+- **Aktiv wenn:** Kein Lauf aktiv UND mindestens 1 Eintrag selektiert
+- **Inaktiv wenn:** Lauf läuft ODER keine Selektion
+- **Verhalten:**
+  - Der Mini-Lauf arbeitet auf einem **Snapshot** der beim Klick selektierten Einträge
+  - DB-Status aller selektierten Einträge wird zurückgesetzt
+  - Sofort danach startet ein Mini-Lauf ausschließlich für diese Dateien
+  - Die Ergebnisliste wird für die selektierten Einträge live aktualisiert
+  - Nicht selektierte Einträge bleiben unverändert in der Liste
+  - Der Mini-Lauf verhält sich fachlich wie ein regulärer Lauf –
+    gleiche Anwendungslogik, gleicher Use Case, nur eingeschränkte Dateimenge
+
+---
+
+### Button „Status zurücksetzen"
+
+- **Aktion:** Nur DB-Status der selektierten Dateien zurücksetzen, keine sofortige Verarbeitung
+- **Aktiv wenn:** Kein Lauf aktiv UND mindestens 1 Eintrag selektiert
+- **Inaktiv wenn:** Lauf läuft ODER keine Selektion
+- **Verhalten:**
+  - DB-Status aller selektierten Einträge wird zurückgesetzt
+  - Kein sofortiger Lauf
+  - Betroffene Zeilen bleiben in der Ergebnisliste sichtbar und erhalten die
+    Kennzeichnung **„Zurückgesetzt – wartet auf nächsten Lauf"**
+  - Beim nächsten regulären Lauf werden die zurückgesetzten Dateien automatisch mitgenommen
+- **Fehlerbehandlung:** Reset läuft nach **Best-effort**-Prinzip –
+  erfolgreich zurückgesetzte Einträge werden zurückgesetzt, fehlgeschlagene bleiben
+  im alten Status; der Meldungs- und Zusammenfassungsbereich zeigt:
+  - Anzahl ausgewählter Einträge
+  - Anzahl erfolgreich zurückgesetzt
+  - Anzahl fehlgeschlagen
+  - Bei Fehlern: betroffene Dateinamen im Meldungsbereich
+
+---
+
+### Welche Status können zurückgesetzt werden
+
+Alle Status sind zurücksetzbar:
+
+| UI-Status | DB-Status | Zurücksetzbar | Verhalten im nächsten regulären Lauf |
+|---|---|---|---|
+| ✔ Erfolgreich | `DONE` | Ja | Wird erneut verarbeitet |
+| ⚠ Fehlgeschlagen retryable | `FAILED_RETRYABLE` | Ja | Wird erneut verarbeitet |
+| ✘ Fehlgeschlagen permanent | `FAILED_FINAL` | Ja | Wird erneut verarbeitet |
+| ► Übersprungen | `DONE` | Ja | DB-Eintrag `DONE` wird zurückgesetzt, wird erneut verarbeitet |
+
+---
+
+### Verhalten bei vorhandener Zieldatei (Re-Run von DONE)
+
+Wird eine bereits erfolgreich verarbeitete Datei erneut verarbeitet:
+
+- **KI schlägt identischen Zieldateinamen vor** und Zieldatei ist bereits vorhanden:
+  Datei gilt als **✔ erfolgreich** – kein neuer Eintrag im Zielordner, kein Fehler
+- **KI schlägt anderen Namen vor:** Normale Verarbeitung –
+  Dubletten-Suffix `(1)`, `(2)` wie im regulären Betrieb wenn nötig
+
+---
+
+### Verhalten bei fehlender oder verschobener Quelldatei
+
+Ist die Quelldatei zum Zeitpunkt des Mini-Laufs nicht mehr vorhanden:
+
+- Eintrag erhält Status **✘ permanent fehlgeschlagen**
+- Meldung: „Quelldatei nicht gefunden: {Dateiname}"
+- Kein weiterer Retry
+
+---
+
+### Verhalten während eines Mini-Laufs
+
+- Der **Abbrechen-Button** (Soft-Stop aus V2.7) gilt auch für den Mini-Lauf
+- Bei Soft-Stop:
+  - Bereits erfolgreich verarbeitete Einträge behalten ihren neuen Endstatus
+  - Noch nicht gestartete, aber bereits zurückgesetzte Einträge behalten den Status
+    „Zurückgesetzt – wartet auf nächsten Lauf" und werden beim nächsten regulären Lauf mitgenommen
+  - Der Mini-Lauf endet im UI-Zustand „abgebrochen" mit Zusammenfassung
+- Tab 1 „Konfiguration" wird während des Mini-Laufs gesperrt
+- Fortschrittsbalken zeigt den Fortschritt des Mini-Laufs –
+  Nenner entspricht der Anzahl der selektierten Dateien
+- Während eines Mini-Laufs sind „Erneut verarbeiten" und „Status zurücksetzen" deaktiviert
+- Kein zweiter paralleler Lauf ist startbar
+
+---
+
+### Scope dieser Funktion
+
+Die Funktion gilt ausschließlich für Einträge der **sichtbaren Ergebnisliste der aktuellen Sitzung**.
+Beim Programmstart erfolgt keine Rekonstruktion der Ergebnisliste aus der DB.
+
+---
+
+## Nicht in V2.8 enthalten
+
+- Historien-Tab / SQLite-Ansicht (V3.0)
+- Bearbeitung des KI-Titels in der GUI
+- Manuelles Überschreiben eines Ergebnisses
+- Massenoperationen außerhalb der Ergebnisliste
+- Automatischer Re-Run nach Konfigurationsänderung
+- Rekonstruktion der Ergebnisliste beim Programmstart
+
+---
+
+## Abnahmekriterien
+
+- [ ] Jede Zeile der Ergebnisliste hat eine Checkbox
+- [ ] Checkbox und Zeilenklick repräsentieren dieselbe Selektionsmenge
+- [ ] Shift/Strg-Mehrfachselektion funktioniert wie im Windows Explorer
+- [ ] „Alle auswählen"-Checkbox selektiert/deselektiert alle Einträge
+- [ ] Alle vier Status sind selektierbar
+- [ ] Während eines laufenden Mini-Laufs kann die Selektion nicht verändert werden
+- [ ] Button „Erneut verarbeiten" ist nur aktiv wenn kein Lauf läuft und mindestens 1 Eintrag selektiert ist
+- [ ] Button „Status zurücksetzen" ist nur aktiv wenn kein Lauf läuft und mindestens 1 Eintrag selektiert ist
+- [ ] „Erneut verarbeiten" setzt DB-Status zurück und startet sofortigen Mini-Lauf nur für selektierte Dateien
+- [ ] Der Mini-Lauf verarbeitet genau die beim Start selektierten Einträge – spätere Selektionsänderungen haben keinen Einfluss
+- [ ] „Status zurücksetzen" setzt nur den DB-Status zurück, betroffene Zeilen erhalten Kennzeichnung „Zurückgesetzt – wartet auf nächsten Lauf"
+- [ ] Reset-Ergebnis zeigt Anzahl ausgewählter, erfolgreich zurückgesetzter und fehlgeschlagener Einträge
+- [ ] Bei identischem Zieldateinamen gilt der Eintrag nach Re-Run als ✔ erfolgreich
+- [ ] Fehlende Quelldatei führt zu ✘ permanent fehlgeschlagen mit Meldung
+- [ ] Mini-Lauf zeigt korrekten Fortschrittsbalken für die selektierte Dateimenge
+- [ ] Abbrechen-Button (Soft-Stop) funktioniert auch während eines Mini-Laufs
+- [ ] Nach Soft-Stop: bereits verarbeitete Einträge behalten neuen Status, nicht gestartete bleiben „Zurückgesetzt"
+- [ ] Tab 1 ist während des Mini-Laufs gesperrt
+- [ ] Nicht selektierte Einträge bleiben nach „Erneut verarbeiten" unverändert in der Liste
+- [ ] Beim nächsten regulären Lauf nach „Status zurücksetzen" werden zurückgesetzte Dateien mitgenommen
+- [ ] Während eines Mini-Laufs sind beide Buttons deaktiviert
+- [ ] headless-Betrieb ist unverändert funktionsfähig
+- [ ] `mvn clean verify` ist grün
@@ -0,0 +1,378 @@
+# V2.9 – Integrierte PDF-Vorschau und Dateinamen-Bearbeitung
+
+**Status:** Freigegeben
+**Erstellt:** 2026-04-24
+**Überarbeitet:** 2026-04-24 (nach zwei ChatGPT-Reviews, finale Version)
+**Autor:** Marcus (mit Claude als Mentor)
+
+---
+
+## Ziel
+
+V2.9 erweitert den Tab „Verarbeitungslauf" um zwei eng verzahnte Funktionen:
+
+1. **Integrierte PDF-Vorschau** – beim Anklicken einer Zeile wird die erste Seite der
+   Quelldatei direkt im Detailbereich rechts gerendert (kein separates Fenster, kein
+   zusätzlicher Klick)
+2. **Editierbarer Dateiname** – der von der KI vorgeschlagene Dateiname kann direkt
+   in der GUI korrigiert werden, bevor er als endgültig gilt
+
+Beide Funktionen zusammen ermöglichen einen natürlichen Review-Zyklus:
+**KI benennt → Benutzer schaut rein → Benutzer korrigiert bei Bedarf → fertig.**
+
+---
+
+## Hintergrund
+
+### Bisheriger Zustand
+
+- Der Detailbereich rechts zeigt nur KI-Begründung als TextArea
+- Ob der vorgeschlagene Dateiname sinnvoll ist, kann der Benutzer nur anhand des
+  KI-Reasonings beurteilen – den tatsächlichen Dokumentinhalt sieht er nicht
+- Der generierte Dateiname ist nach dem Lauf nicht mehr veränderbar
+- Die Spike-Implementierung (PDFViewFX + jai-imageio-jpeg2000 für JBIG2-Unterstützung)
+  hat die technische Machbarkeit bereits bestätigt; der Spike-Code wird im Rahmen
+  von V2.9 durch produktionsreifen Code ersetzt
+
+### Motivation
+
+- Benutzer sollen schnell beurteilen können, ob der KI-Dateiname passt,
+  ohne ein externes Programm öffnen zu müssen
+- Korrekturen sollen direkt in der Anwendung möglich sein – für nicht-technische
+  Benutzer (z. B. Familienmitglieder) ist das eine wesentliche UX-Verbesserung
+- Die Anwendung wird vom reinen Batch-Prozessor zum assistierten
+  Dokumenten-Review-Werkzeug weiterentwickelt
+
+---
+
+## Zielbild
+
+Nach Abschluss von V2.9 kann der Benutzer:
+
+1. Eine Zeile in der Ergebnisliste anklicken
+2. Sofort die erste Seite der zugehörigen **Quelldatei** als Vorschau sehen –
+   ohne weiteren Klick, direkt im Detailbereich
+3. Weitere Seiten bei Bedarf **auf Anfrage** laden (Lazy Rendering)
+4. Den vorgeschlagenen Dateinamen **direkt in der GUI bearbeiten** und speichern
+5. Den headless-Betrieb unverändert nutzen – V2.9 betrifft ausschließlich die GUI
+
+---
+
+## Layout-Änderung im Tab „Verarbeitungslauf"
+
+### Bisheriges Layout
+
+```
+[ Fortschrittsbalken                                      ]
+[ Ergebnistabelle (~75% Breite) | KI-Begründung (~25%)   ]
+[ Buttons                                                 ]
+[ Statuszeile                                             ]
+```
+
+### Neues Layout
+
+```
+[ Fortschrittsbalken                                           ]
+[ Ergebnistabelle (~60% Breite) | Detailbereich (~40% Breite) ]
+[                               |   KI-Begründung             ]
+[                               |   Dateiname (editierbar)    ]
+[                               |   PDF-Vorschau (Seite X/Y)  ]
+[ Buttons                                                      ]
+[ Statuszeile                                                  ]
+```
+
+- Tabelle und Detailbereich sind durch einen **verschiebbaren Splitter** (SplitPane)
+  getrennt – der Benutzer kann das Verhältnis anpassen
+- Standard-Split: 60% Tabelle / 40% Detailbereich
+- Der Detailbereich ist vertikal aufgebaut: KI-Begründung oben (kompakt),
+  darunter Dateiname-Feld, darunter PDF-Vorschau (nimmt verfügbaren Restplatz)
+- Die PDF-Vorschau rendert die erste Seite **„fit to width"** – Seitenverhältnis wird
+  beibehalten, die Seite füllt die verfügbare Panelbreite aus
+
+---
+
+## Fachliche Anforderungen
+
+### PDF-Vorschau
+
+#### Grundverhalten
+
+- Beim Anklicken einer Zeile in der Ergebnisliste wird **automatisch** Seite 1 der
+  zugehörigen **Quelldatei** gerendert und im Vorschaubereich angezeigt
+- Das Rendering erfolgt **asynchron im Hintergrund** – die GUI bleibt während des
+  Ladens reaktionsfähig
+- Während des Renderings wird ein **Ladeindikator** (z. B. ProgressIndicator) angezeigt
+- Die Vorschau zeigt immer die **Quelldatei**, nicht die umbenannte Zieldatei
+
+#### Lazy Rendering und Seitennavigation
+
+- Beim ersten Anklicken einer Zeile wird **ausschließlich Seite 1** gerendert
+- Unterhalb der Vorschau wird die aktuelle Seite sowie die Gesamtseitenzahl
+  angezeigt: „Seite 1 / 12"
+- Navigation:
+  - Button **„Nächste Seite"** lädt und rendert die jeweils nächste Seite on-demand
+  - Button **„Vorherige Seite"** lädt die vorherige Seite
+  - Bereits gerenderte Seiten werden **gecacht** – ein erneuter Wechsel auf eine
+    bereits gerenderte Seite erfordert kein erneutes Rendering
+  - Der Cache wird geleert wenn eine andere Zeile angeklickt wird
+- Die Navigations-Buttons sind bei Seite 1 (Zurück) bzw. letzter Seite (Weiter)
+  deaktiviert
+
+#### Abbruchverhalten bei schnellem Wechsel (Latest Preview Request Wins)
+
+- Es gilt das Prinzip **„latest preview request wins"**: Wenn während eines laufenden
+  Renderings eine neue Vorschau-Anforderung eingeht – sei es durch Selektionswechsel
+  oder durch Seitennavigation innerhalb derselben PDF – wird das laufende Rendering
+  abgebrochen bzw. sein Ergebnis verworfen
+- Nur das Ergebnis der zuletzt angeforderten Vorschau darf im Vorschaubereich landen
+- Veraltete Render-Ergebnisse werden niemals angezeigt
+
+#### Fehlerfälle PDF-Vorschau
+
+| Situation | Verhalten |
+|---|---|
+| Quelldatei nicht mehr vorhanden | Meldung im Vorschaubereich: „Quelldatei nicht gefunden" |
+| PDF nicht lesbar / korrupt | Meldung im Vorschaubereich: „PDF konnte nicht geöffnet werden" |
+| PDF passwortgeschützt / verschlüsselt | Meldung im Vorschaubereich: „PDF ist passwortgeschützt und kann nicht angezeigt werden" |
+| JBIG2-Bilder nicht vollständig dekodierbar | Seite wird teilweise gerendert; kein Fehler-Abbruch; kein Hinweis nötig |
+| Kein Eintrag selektiert | Vorschaubereich zeigt neutralen Platzhaltertext |
+
+#### Technische Grundlage
+
+- Bibliothek: `com.dlsc.pdfviewfx:pdfviewfx` (bereits im Spike erfolgreich getestet)
+- Zusatzabhängigkeit für JBIG2 und erweiterte Bildformate:
+  `com.github.jai-imageio:jai-imageio-jpeg2000` (bereits im Spike ergänzt)
+- Der Spike-Code (`PdfViewerSpike.java`, Spike-Button in `GuiBatchRunTab`) wird
+  vollständig entfernt und durch die produktive Implementierung ersetzt
+- Rendering läuft in einem dedizierten Background-Thread (nicht im JavaFX
+  Application Thread)
+
+---
+
+### Editierbarer Dateiname
+
+#### Zustandsmodell
+
+Der Dateiname-Bereich kennt drei klar getrennte Zustände:
+
+| Zustand | Beschreibung |
+|---|---|
+| **KI-Vorschlag** | Der von der KI ursprünglich generierte Name – unveränderlich in der DB gespeichert; dient als Referenz für „Zurücksetzen auf KI-Vorschlag" |
+| **Letzter gespeicherter Name** | Der zuletzt per „Dateiname übernehmen" bestätigte Name (= aktueller FS- und DB-Stand); ist nach dem Batch-Lauf zunächst identisch mit dem KI-Vorschlag |
+| **Aktuelle Eingabe** | Der aktuell im Textfeld eingetippte, noch nicht gespeicherte Wert |
+
+**Anzeige-Regel:** Im Textfeld wird beim Selektieren einer Zeile immer der
+**letzte gespeicherte Name** angezeigt – nicht der KI-Vorschlag.
+Wurde noch nie manuell gespeichert, sind beide identisch.
+
+**Dirty-State-Regel:** Dirty-State besteht wenn die **aktuelle Eingabe** vom
+**letzten gespeicherten Namen** abweicht. Der KI-Vorschlag ist keine Dirty-Basis.
+
+#### Anzeige
+
+- Unterhalb der KI-Begründung und oberhalb der PDF-Vorschau befindet sich ein
+  Bereich „Dateiname"
+- Der Dateiname wird in einem **editierbaren Textfeld** (TextField) angezeigt
+- Das Textfeld zeigt den **letzten gespeicherten Namen** ohne Dateierweiterung
+  (`.pdf` wird separat als nicht editierbares Label daneben angezeigt)
+- Solange kein Eintrag selektiert ist, ist das Textfeld leer und deaktiviert
+- Wenn das Textfeld vom letzten gespeicherten Namen abweicht (**Dirty State**),
+  wird dies durch eine visuelle Markierung am Textfeld angezeigt (z. B. farbiger Rand)
+
+#### Tastatur- und Schaltflächen-Verhalten
+
+| Aktion | Verhalten |
+|---|---|
+| **Enter** im Textfeld | Löst „Dateiname übernehmen" aus (sofern Validierung grün) |
+| **Escape** im Textfeld | Verwirft aktuelle Eingabe; stellt **letzten gespeicherten Namen** wieder her |
+| **„Dateiname übernehmen"** | Startet die atomare Speicher-Transaktion |
+| **„Zurücksetzen auf KI-Vorschlag"** | Setzt das Textfeld auf den ursprünglichen KI-Vorschlag zurück (kein Speichern – nur Textfeld-Inhalt) |
+
+Hinweis: „Zurücksetzen auf KI-Vorschlag" und Escape haben **unterschiedliche Semantik**:
+Escape = zurück zum letzten gespeicherten Stand; „Zurücksetzen" = zurück zum KI-Ursprung.
+
+#### Speichern-Transaktion (Alles oder Nichts)
+
+Das Speichern eines geänderten Dateinamens ist eine **atomare Operation** bestehend
+aus zwei Persistenzschritten:
+
+1. Zieldatei im Dateisystem umbenennen
+2. Eintrag in der SQLite-DB aktualisieren
+
+**Schlägt Schritt 1 oder 2 fehl, wird die gesamte Aktion abgebrochen:**
+- Bereits durchgeführte Teilschritte werden zurückgerollt
+- Dateisystem und DB bleiben im vorherigen Zustand
+- Eine Fehlermeldung im Statusbereich informiert den Benutzer
+- Das Textfeld behält den eingegebenen Wert – der Benutzer kann es erneut versuchen
+
+Nach erfolgreicher Transaktion (Projektionsschritt, nicht Teil der Transaktion):
+- Tabellenspalte „Neuer Dateiname" wird aktualisiert
+- Erfolgsmeldung im Statusbereich
+
+Mögliche Fehlerursachen für Schritt 1: Datei-Lock durch andere Prozesse (Scanner, AV),
+fehlende Schreibrechte, Read-only-Dateisystem, Netzlaufwerk nicht erreichbar.
+
+#### Konfliktsemantik bei vorhandenem Zieldateinamen
+
+Existiert im Zielordner bereits eine Datei mit dem neu eingegebenen Namen,
+wird anhand des **Fingerprints** (SHA-256 des Dateiinhalts) entschieden:
+
+| Situation | Verhalten |
+|---|---|
+| **Gleicher Fingerprint** | Dateien sind inhaltlich identisch → keine Aktion; Meldung im Statusbereich: „Identische Datei bereits vorhanden – keine Umbenennung nötig"; weder FS noch DB werden geändert |
+| **Unterschiedlicher Fingerprint** | Warnung im Statusbereich; Dateiname im FS erhält automatisch ein Suffix `(1)`, `(2)` usw.; DB wird mit dem tatsächlichen neuen Namen inkl. Suffix aktualisiert |
+
+#### Validierung des Dateinamens
+
+Folgende Prüfungen erfolgen **live während der Eingabe**:
+
+| Prüfung | Verhalten bei Verletzung |
+|---|---|
+| Dateiname ist leer oder nur Leerzeichen | Speichern-Button deaktiviert, Hinweistext unterhalb des Feldes |
+| Führende oder abschließende Leerzeichen | Speichern-Button deaktiviert, Hinweistext |
+| Unerlaubte Zeichen (`\ / : * ? " < > \|`) | Speichern-Button deaktiviert, Hinweistext |
+| Reservierte Windows-Namen (`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`, `LPT1`–`LPT9`) | Speichern-Button deaktiviert, Hinweistext |
+| Dateiname endet auf Punkt | Speichern-Button deaktiviert, Hinweistext |
+| Dateiname + Zielpfad + `.pdf` überschreitet 259 Zeichen | Speichern-Button deaktiviert, Hinweistext |
+
+Die 259-Zeichen-Grenze ist eine **bewusste Produktregel** für maximale
+Windows-Kompatibilität (Windows MAX_PATH = 260 Zeichen inkl. Null-Terminator).
+
+#### Zustände des Dateiname-Bereichs
+
+| Zeilenstatus | Verhalten |
+|---|---|
+| Kein Eintrag selektiert | Textfeld leer, deaktiviert |
+| Eintrag mit Status `DONE` (erfolgreich) | Textfeld editierbar, letzter gespeicherter Name vorausgefüllt |
+| Eintrag mit Status `FAILED_*` | Textfeld leer, deaktiviert (kein Dateiname vorhanden) |
+| Eintrag mit Status `SKIPPED` | Textfeld deaktiviert |
+| Lauf aktiv | Textfeld deaktiviert, alle Buttons deaktiviert |
+
+#### Verhalten bei fehlender Zieldatei
+
+Ist die Zieldatei zum Zeitpunkt des Speicherns nicht mehr im Zielordner vorhanden:
+
+- Schritt 1 der Transaktion schlägt fehl
+- Gemäß Alles-oder-Nichts-Prinzip: DB wird **nicht** aktualisiert
+- Fehlermeldung im Statusbereich: „Zieldatei nicht gefunden – Umbenennung nicht möglich"
+- Das Textfeld behält den eingegebenen Wert
+
+#### Verhalten bei ungespeicherten Änderungen (Dirty State)
+
+Ein Hinweisdialog erscheint, wenn der Benutzer mit aktivem Dirty-State eine der
+folgenden Aktionen ausführt:
+
+- Eine andere Zeile in der Ergebnistabelle anklicken
+- Den Tab wechseln (Konfiguration ↔ Verarbeitungslauf)
+- Die Anwendung schließen
+- Einen neuen Lauf starten
+
+Dialog-Text: „Der Dateiname wurde geändert aber nicht gespeichert. Änderungen verwerfen?"
+Optionen: **„Verwerfen"** (Dirty State wird geleert, Aktion wird fortgesetzt) /
+**„Zurück"** (Dialog schließt, Benutzer bleibt im Textfeld)
+
+---
+
+## Architektur
+
+### Manuelle Namenskorrektur als Application-Use-Case
+
+Die manuelle Dateinamen-Korrektur wird als **eigenständiger Application-Use-Case**
+modelliert, nicht im GUI-Adapter implementiert:
+
+- Ein neuer Use-Case `ManualFileRenameUseCase` (o. ä.) kapselt die atomare Transaktion
+  aus FS-Rename + DB-Update
+- Der `GuiBatchRunCoordinator` (GUI-Adapter) delegiert ausschließlich an diesen Use-Case
+- Dateisystem- und DB-Zugriffe laufen ausschließlich über bestehende oder neue
+  Ports/Adapter – kein Direktzugriff aus dem GUI-Adapter
+- Damit bleibt die hexagonale Architektur gewahrt und der Use-Case ist unabhängig
+  von der GUI testbar
+
+### Komponenten-Übersicht
+
+| Komponente | Änderung |
+|---|---|
+| `GuiBatchRunTab` | Hauptumbau: SplitPane, Detailbereich-Redesign, Spike-Code entfernen |
+| `GuiBatchRunResultRow` | Neues Feld: `correctedFileName` als `Optional<String>` |
+| `GuiBatchRunCoordinator` | Delegiert Dateinamen-Korrektur an neuen Use-Case |
+| `ManualFileRenameUseCase` | Neuer Application-Use-Case: atomares FS-Rename + DB-Update |
+| `pom.xml` (GUI-Modul) | PDFViewFX + jai-imageio-jpeg2000 bleiben; Spike-Klasse entfernen |
+| Domain / Ports | Ggf. neuer Port für Datei-Rename-Operation erforderlich |
+| Headless-Betrieb | Unberührt |
+
+---
+
+## Abhängigkeiten zwischen den Funktionen
+
+- PDF-Vorschau und editierbarer Dateiname sind **unabhängig voneinander nutzbar**
+- Beide beziehen sich auf den in der Ergebnistabelle selektierten Eintrag
+- Beim Selektionswechsel mit Dirty-State: Hinweisdialog erscheint (siehe oben)
+- PDF-Vorschau-Cache wird beim Selektionswechsel geleert
+
+---
+
+## Verhalten während eines laufenden Batch-Laufs
+
+- Der Detailbereich (PDF-Vorschau + Dateinamen-Editor) ist **vollständig deaktiviert**
+  während ein regulärer Lauf oder Mini-Lauf aktiv ist
+- Bereits angezeigte Vorschau bleibt sichtbar, aber Navigation und Bearbeitung
+  sind gesperrt
+
+---
+
+## Nicht in V2.9 enthalten
+
+- Löschen der Quelldatei nach Bestätigung (spätere Version)
+- Vollständiger PDF-Viewer mit freiem Scrollen und Zoom (Issue #23: DPI-Optimierung)
+- Historien-Tab / SQLite-Ansicht (Issue #7, V3.0)
+- Automatischer Scheduler / System-Tray (Issues #20, #22)
+- Kompakteres Layout der Konfigurationsseite (Issue #24)
+- Anwendungs-Icon (Issue #21)
+
+---
+
+## Abnahmekriterien
+
+### Fachliche Akzeptanz
+
+#### PDF-Vorschau
+- [ ] Beim Anklicken einer Zeile wird Seite 1 der Quelldatei automatisch gerendert – ohne extra Klick
+- [ ] Während des Renderings ist ein Ladeindikator sichtbar; die GUI bleibt reaktionsfähig
+- [ ] Die Vorschau rendert „fit to width" mit beibehaltenem Seitenverhältnis
+- [ ] Seitenanzahl wird angezeigt: „Seite 1 / X"
+- [ ] „Nächste Seite" / „Vorherige Seite" laden Seiten on-demand
+- [ ] Bereits gerenderte Seiten werden gecacht; Selektionswechsel leert den Cache
+- [ ] Navigations-Buttons sind korrekt deaktiviert (erste / letzte Seite)
+- [ ] Schneller Selektionswechsel oder Seitenwechsel während Rendering: nur das zuletzt angeforderte Ergebnis wird angezeigt (latest preview request wins)
+- [ ] Quelldatei nicht vorhanden → verständliche Fehlermeldung im Vorschaubereich
+- [ ] PDF nicht lesbar / korrupt → verständliche Fehlermeldung im Vorschaubereich
+- [ ] PDF passwortgeschützt → verständliche Fehlermeldung im Vorschaubereich
+
+#### Dateiname-Editor
+- [ ] Textfeld zeigt beim Selektieren den **letzten gespeicherten Namen** (nicht KI-Vorschlag) ohne `.pdf`-Erweiterung; `.pdf` als nicht editierbares Label daneben sichtbar
+- [ ] Dateiname ist direkt im Textfeld editierbar
+- [ ] Dirty-State (Abweichung von letztem gespeichertem Namen) wird visuell am Textfeld angezeigt
+- [ ] Enter im Textfeld löst „Dateiname übernehmen" aus (wenn Validierung grün)
+- [ ] Escape im Textfeld stellt den **letzten gespeicherten Namen** wieder her
+- [ ] „Zurücksetzen auf KI-Vorschlag" setzt das Textfeld auf den KI-Ursprung zurück (ohne Speichern)
+- [ ] Validierung prüft live: leer/nur Leerzeichen, führende/abschließende Leerzeichen, unerlaubte Zeichen, reservierte Windows-Namen, endet auf Punkt, Pfadlänge > 259
+- [ ] Bei Validierungsfehler: Speichern-Button deaktiviert, Hinweistext sichtbar
+- [ ] „Dateiname übernehmen" ist atomar: FS und DB werden beide aktualisiert oder nichts davon
+- [ ] Bei Fehler in FS oder DB: kein Teilupdate, Rollback, Fehlermeldung im Statusbereich, Textfeld behält Eingabe
+- [ ] Nach Erfolg: Tabellenspalte und Statusbereich aktualisiert (Projektionsschritt)
+- [ ] Dateikonflikt mit gleichem Fingerprint → keine Aktion, Meldung „Identische Datei bereits vorhanden"
+- [ ] Dateikonflikt mit unterschiedlichem Fingerprint → Warnung, Suffix `(1)` usw., DB mit tatsächlichem Namen
+- [ ] Zieldatei fehlt → Fehlermeldung, weder FS noch DB werden geändert
+- [ ] Ungespeicherte Änderungen bei Selektionswechsel → Hinweisdialog erscheint
+- [ ] Ungespeicherte Änderungen bei Tabwechsel → Hinweisdialog erscheint
+- [ ] Ungespeicherte Änderungen beim App-Schließen → Hinweisdialog erscheint
+- [ ] Ungespeicherte Änderungen bei Laufstart → Hinweisdialog erscheint
+- [ ] Status `FAILED_*` und `SKIPPED` → Dateiname-Textfeld deaktiviert
+- [ ] Während eines aktiven Laufs: Detailbereich vollständig deaktiviert
+
+### Technische DoD
+- [ ] Spike-Button und `PdfViewerSpike.java` sind vollständig entfernt
+- [ ] Tab „Verarbeitungslauf" zeigt Tabelle und Detailbereich nebeneinander (SplitPane, 60/40, verschiebbar)
+- [ ] `ManualFileRenameUseCase` ist im Application-Modul implementiert und unabhängig von der GUI testbar
+- [ ] headless-Betrieb ist unverändert funktionsfähig
+- [ ] `mvn clean verify` ist grün
@@ -0,0 +1,924 @@
+# V3.1 – UX-Polish und Verlauf-Tab-Reife
+
+**Status:** Zur Implementierung freigegeben
+**Erstellt:** 2026-05-05
+**Überarbeitet:** 2026-05-05 (nach ChatGPT-Review Runden 1, 2 und 3)
+**Autor:** Marcus (mit Claude als Mentor)
+
+---
+
+## Ziel
+
+V3.1 ist der konsequente Nachschlag zu V3.0: Was der Produkttest aufgedeckt hat,
+wird hier bereinigt. Kein großes Architektur-Feature, kein neues Maven-Modul –
+**gezielter UX-Schliff und Robustheit**.
+
+Schwerpunkte:
+
+1. **Polieren** – sichtbare Schwächen aus dem V3.0-Produkttest beheben
+   (#77, #80, #81, #83, #84, #88, #91)
+2. **Verlauf-Tab reifen lassen** – Suche, Mehrfachauswahl, DB-Neuanlage
+   (#82, #86, #87)
+3. **Quick Win** – Mausrad-Zoom im PDF-Viewer als kleiner,
+   wertvoller Gebrauchskomfort (#32)
+
+Die fachliche Kernverarbeitung bleibt vollständig unverändert.
+
+---
+
+## Einordnung
+
+V3.0 ist der abgeschlossene Ausgangspunkt. Hexagonale Architektur,
+Modulstruktur, headless-Betrieb, `.properties`-Konfigurationswahrheit
+und Flyway-DB-Evolution bleiben unangetastet.
+
+V3.1 fügt **kein neues Maven-Modul** hinzu.
+
+**Headless-Betrieb:** Der `adapter-in-cli`-Pfad erhält keine neue Bedienfunktion.
+Er ist jedoch von der globalen Lock-File-Pfadauflösung (#91) und einer
+ggf. notwendigen Flyway-Schemamigration (#88) betroffen – beide Änderungen
+wirken beim Programmstart, unabhängig von GUI oder CLI.
+
+---
+
+## Scope
+
+### In V3.1 enthalten
+
+| # | Thema | Kategorie |
+|---|---|---|
+| #77 | Fehlende Tooltips | UX |
+| #80 | Dirty-Indikator für Konfigurations-Tab | UX |
+| #81 | Enum-Werte statt deutscher Bezeichnungen (Status-ComboBox + Versuche-Tabelle) | UX |
+| #82 | Verlauf-Tab: Live-Filter bei Suche | GUI |
+| #83 | KI-Begründung bei SUCCESS-Versuch verwirrend leer | UX |
+| #84 | Aktionsbuttons nach Laufende nicht sofort reaktiviert | Bug |
+| #86 | Mehrfachauswahl im Verlauf-Tab (Strg+A, Strg+Klick, Shift+Klick) | GUI |
+| #87 | Neue leere SQLite-Datenbank anlegen | GUI |
+| #88 | FAILED_FINAL-Einträge zeigen keine Fehlerursache im Verlauf-Tab | UX |
+| #91 | Lock-File relativer Pfad – Fallback wie Log-Verzeichnis | Robustheit |
+| #32 | Mausrad-Zoom in PDF-Vorschau | GUI |
+
+### Explizit nicht in V3.1
+
+- Automatischer Scheduler / Quellordner-Überwachung (#22) → V3.x
+- PDF-Viewer Render-DPI (#23) → V3.2
+- F1-Hilfe (#69) → V3.2
+- Dark Mode (#70) → V3.x
+- Log-Viewer in der GUI (#72) → V3.2
+- Token- und Kosten-Tracking (#74) → V3.2
+- Excel-Export (#75) → V3.2
+- Automatische Update-Prüfung (#76) → V3.2
+- Änderung der fachlichen Kernverarbeitung
+- Neue Maven-Module, neue KI-Provider, Architekturbrüche
+
+---
+
+## Unverrückbare Leitplanken (unverändert gegenüber V3.0)
+
+- Java 21, Maven Multi-Module, hexagonale Architektur
+- Shade-JAR als primäres Distributionsartefakt
+- GUI ist Standardstart, `--headless` bleibt vollständig erhalten
+- `.properties` bleibt die einzige Konfigurationswahrheit
+- Kein Webserver, kein Applikationsserver
+- GUI offiziell nur unter Windows; headless für Windows Server / Task Scheduler
+- JavaFX-Threading: I/O auf Worker-Thread, UI-Updates via `Platform.runLater()`
+- Kein JavaFX in Domain oder Application
+- JavaDoc-Standard für alle neuen öffentlichen Ports, Use-Cases, DTOs und Adapter-Methoden
+- Notwendige Code-Kommentare auf Deutsch; Logging auf Deutsch
+- Flyway ist die einzige Schema-Evolutionsquelle (kein manuelles DDL im Code)
+
+---
+
+## Status-Mapping-Tabelle (unverändert gegenüber V3.0)
+
+Diese Tabelle ist weiterhin die einzige autoritative Quelle für Status-Darstellung
+in der GUI. Sie gilt verbindlich für alle V3.1-Features, die Statuswerte anzeigen –
+insbesondere #81 (Status-ComboBox, Versuche-Tabelle).
+
+**Alle acht Statuswerte müssen vollständig unterstützt werden.**
+Kein Enum-Rohname darf für Endnutzer sichtbar sein.
+
+| Domain-Status (`ProcessingStatus`) | GUI-Icon | Farbe | GUI-Text (Tooltip) | Summary-Kategorie |
+|---|---|---|---|---|
+| `SUCCESS` | `✓` | Grün | „Erfolgreich verarbeitet und umbenannt." | erfolgreich |
+| `FAILED_RETRYABLE` | `↻` | Orange | „Temporärer Fehler – wird beim nächsten Lauf automatisch erneut versucht." | wird wiederholt |
+| `FAILED_FINAL` | `×` | Rot | „Dauerhaft nicht verarbeitbar – z. B. kein Textinhalt (Foto-PDF), Passwortschutz oder beschädigte Datei. Kein weiterer automatischer Versuch." | fehlgeschlagen |
+| `SKIPPED_ALREADY_PROCESSED` | `≡` | Grau | „Übersprungen – wurde bereits in einem früheren Lauf erfolgreich verarbeitet." | übersprungen |
+| `SKIPPED_FINAL_FAILURE` | `⊘` | Dunkelgrau | „Endgültig übersprungen nach wiederholten Fehlern." | endgültig übersprungen |
+| `READY_FOR_AI` | `⟳` | Blau | „Wartet auf Verarbeitung." | – |
+| `PROPOSAL_READY` | `◇` | Hellblau | „KI-Vorschlag liegt vor, wartet auf Bestätigung." | – |
+| `PROCESSING` | `▶` | Hellgrau | „Wird gerade verarbeitet." | – |
+
+**Wichtig:** Farbe ist niemals das einzige Unterscheidungsmerkmal.
+Icon und Tooltip-Text müssen den Status allein eindeutig beschreiben.
+
+---
+
+## UX-Polishing-Features
+
+### #77 – Fehlende Tooltips
+
+#### Problem
+
+Der V3.0-Produkttest hat GUI-Elemente identifiziert, die noch keinen Tooltip
+tragen. Die Infrastruktur (`GuiTooltipTexts`, `setTooltip()`) existiert bereits
+aus #66 – es fehlt nur die konsequente Anwendung.
+
+#### Lösung
+
+Vor der Implementierung führt Claude Code eine **vollständige Bestandsaufnahme**
+durch: Alle interaktiven Elemente auf allen Tabs werden gegen vorhandene Tooltips
+geprüft. Maßgeblich ist die Bestandsaufnahme – die Zahl 16 stammt aus dem
+Produkttest und ist nicht bindend. Werden mehr fehlende Elemente gefunden,
+werden alle ergänzt.
+
+Fehlende Tooltips werden in `GuiTooltipTexts` als Konstanten ergänzt und
+im jeweiligen GUI-Tab via `element.setTooltip(new Tooltip(GuiTooltipTexts.XY))`
+gesetzt. Keine hartcodierten Strings.
+
+**Tooltips auf `TableColumn`-Headern (Sonderfall JavaFX):**
+
+`TableColumn` ist kein normaler JavaFX-Node; `setTooltip()` ist darauf nicht
+direkt anwendbar. **Kein Skin-/Lookup-Hack.** Falls Header-Tooltips benötigt
+werden, wird ein `Label` als Column-Graphic gesetzt:
+
+```java
+Label headerLabel = new Label("Spaltenname");
+headerLabel.setTooltip(new Tooltip("Erklärungstext"));
+column.setGraphic(headerLabel);
+column.setText("");
+```
+
+Bei der Umsetzung muss geprüft werden, dass Sortierung, Header-Breite
+und bestehendes CSS durch das Column-Graphic-Pattern nicht sichtbar
+verschlechtert werden.
+
+Falls das Projekt bereits eine stabile eigene Lösung für Column-Tooltips
+besitzt, wird diese wiederverwendet.
+
+**Zu prüfende Tabs und Elemente (Anhaltspunkte):**
+
+| Tab | Verdächtige Elemente |
+|---|---|
+| Verlauf | Tabellenspalten-Header, Suchfeld, Such-Button, Aktions-Buttons (Reset, Löschen) |
+| Verlauf (Detail) | Status-Icon, Versuche-Tabelle Spalten, KI-Begründung-Bereich |
+| Prompt | Speichern-Button, Zurücksetzen-Button, TextArea |
+| Allgemein | Fortschrittsbalken, Summary-Banner-Elemente |
+
+**Technisch:** Ausschließlich `adapter-in-gui` und `GuiTooltipTexts`.
+Keine Architektur-Änderungen.
+
+---
+
+### #80 – Dirty-Indikator für Konfigurations-Tab
+
+#### Problem
+
+Der Prompt-Tab zeigt bereits einen `*`-Dirty-Indikator im Tab-Titel und warnt
+beim Verlassen mit ungespeicherten Änderungen. Der Konfigurations-Tab hat dieses
+Verhalten nicht – Nutzer verlieren versehentlich Änderungen.
+
+#### Lösung
+
+**Dirty-State-Tracking mit Baseline-Snapshot:**
+
+Beim Laden einer Konfiguration wird ein **Baseline-Snapshot** des geladenen Zustands
+gespeichert. Dirty-State entsteht durch Vergleich des aktuellen Formularinhalts
+mit dem Snapshot – nicht durch blindes „erster Listener feuert".
+
+Während programmgesteuertem Laden oder Normalisieren von Feldinhalten wird
+Dirty-Tracking temporär unterdrückt (Flag `loadingInProgress`), damit
+programmatische Feldänderungen keinen unechten Dirty-State auslösen.
+
+- Beim ersten echten Nutzerwechsel gegenüber dem Snapshot: Tab-Titel wechselt
+  auf `* Konfiguration`
+- Dirty-Flag wird zurückgesetzt bei: Speichern, Speichern unter,
+  Laden einer neuen Konfiguration (nach Bestätigungsdialog)
+
+**Bestätigungsdialog bei Navigation mit Dirty State:**
+
+Beim Laden einer neuen Konfiguration oder beim Schließen der Anwendung
+mit ungespeicherten Konfig-Änderungen:
+> „Die Konfiguration enthält ungespeicherte Änderungen. Jetzt speichern?"
+> [Speichern] [Verwerfen] [Abbrechen]
+
+**Kopplung mit #87 (Neue Datenbank):**
+
+Legt der Nutzer über „Neue Datenbank anlegen..." eine neue DB-Datei an,
+wird der DB-Pfad im Konfigurationsmodell geändert und der Konfig-Tab
+in den Dirty-State versetzt. Der bestehende Bestätigungsdialog greift
+beim nächsten Schließen oder Ladevorgang.
+
+**UX-Konsistenz mit Prompt-Tab:**
+
+Die UX muss identisch zum Prompt-Tab sein: Sternchen im Tab-Titel,
+Warn-/Speicherdialog beim Verlassen, Rücksetzen nach Speichern.
+Die **technische Umsetzung** darf im Konfig-Tab über Baseline-Snapshot
+und `loadingInProgress` erfolgen, wenn die komplexere Formularlogik
+das erfordert.
+
+**Technisch:** Ausschließlich `adapter-in-gui`. Kein neuer Port, kein Use-Case.
+
+---
+
+### #81 – Enum-Werte statt deutscher Bezeichnungen
+
+#### Problem
+
+Die Status-ComboBox im Verlauf-Tab zeigt rohe Enum-Namen (`READY_FOR_AI`,
+`FAILED_FINAL` etc.). Die Versuche-Tabelle im Detailbereich zeigt ebenfalls
+Enum-Rohnamen in der Status-Spalte. Das ist für Endnutzer unlesbar.
+
+#### Lösung
+
+**Anzeige-Mapping:**
+
+`ProcessingStatusPresentation` (existiert bereits aus #51) stellt die Mapping-Logik
+bereit. Dieses Mapping wird für alle Statusanzeigen im Verlauf-Tab verbindlich genutzt.
+**Alle acht Statuswerte der autoritativen Tabelle müssen abgedeckt sein:**
+
+| Enum-Wert | Angezeigter Text |
+|---|---|
+| `SUCCESS` | „✓ Erfolgreich" |
+| `FAILED_RETRYABLE` | „↻ Temporärer Fehler" |
+| `FAILED_FINAL` | „× Dauerhaft fehlgeschlagen" |
+| `SKIPPED_ALREADY_PROCESSED` | „≡ Bereits verarbeitet" |
+| `SKIPPED_FINAL_FAILURE` | „⊘ Endgültig übersprungen" |
+| `READY_FOR_AI` | „⟳ Wartet auf Verarbeitung" |
+| `PROPOSAL_READY` | „◇ Vorschlag vorhanden" |
+| `PROCESSING` | „▶ In Bearbeitung" |
+
+**Status-ComboBox:**
+
+- Erster Eintrag: „Alle Status" – GUI-intern als `Optional.empty()` bzw. `null`-Filter
+  behandelt; kein Domain-Enum-Wert
+- Weitere Einträge: alle acht Statuswerte mit Displaytext
+- Intern wird für DB-Queries stets der Enum-Name verwendet
+- `StringConverter<ProcessingStatus>` implementieren
+
+**Versuche-Tabelle (Detailbereich):**
+
+- Status-Spalte: `ProcessingStatusPresentation`-Mapping anwenden
+- Kein Enum-Rohname darf für Endnutzer sichtbar sein
+
+**Technisch:** Ausschließlich `adapter-in-gui`. Kein neuer Port, kein Use-Case.
+
+---
+
+### #83 – KI-Begründung bei SUCCESS-Versuch verwirrend leer
+
+#### Problem
+
+Im Detailbereich wird bei einem Versuch mit Status `SUCCESS` die
+KI-Begründungs-TextArea leer angezeigt. Nutzer verstehen nicht, ob das
+ein Fehler ist oder ob tatsächlich keine Begründung vorliegt.
+
+#### Lösung
+
+**Platzhalter über JavaFX `promptText` (kein echter Textinhalt):**
+
+Bei leerem oder null `ai_reasoning` gilt:
+
+```java
+textArea.setText("");
+textArea.setPromptText("Keine KI-Begründung für diesen Versuch gespeichert.");
+```
+
+Der `promptText` wird von JavaFX automatisch gedimmt dargestellt und ist
+**nicht kopierbar, nicht speicherbar, nicht als Nutzdaten behandelbar**.
+Kein Vermischen von Daten und UI-Platzhaltertext.
+
+Die TextArea bleibt sichtbar – ein leeres Feld ohne Erklärung ist schlechter
+als ein erklärender Platzhalter.
+
+**Technisch:** Ausschließlich `adapter-in-gui`. Kein neuer Port, kein Use-Case,
+keine DB-Änderung.
+
+---
+
+### #84 – Aktionsbuttons nach Laufende nicht sofort reaktiviert
+
+#### Problem
+
+Nach Abschluss eines Verarbeitungslaufs bleiben die Aktionsbuttons im Verlauf-Tab
+(„Status zurücksetzen", „Eintrag löschen") dauerhaft deaktiviert.
+
+#### Lösung
+
+**Ereignisgetriebene Button-State-Neuberechnung:**
+
+Der Button-State wird nach jedem Lauf-Terminierungsereignis neu berechnet –
+unabhängig vom Grund der Terminierung:
+
+- Erfolgreicher Laufabschluss
+- Fehlerabbruch (Exception im Worker)
+- Nutzerabbruch
+- Leerlauf (keine Dateien zu verarbeiten)
+
+Nach Terminierung wird, sofern eine Auswahl in der Verlauf-Tabelle besteht,
+der zugehörige Aktionsbutton-State **ereignisgetrieben** aktiviert –
+ohne dass der Nutzer die Auswahl erneuern oder den Tab wechseln muss.
+
+**Code-Analyse erforderlich:** Claude Code analysiert den genauen Signal-Pfad
+(Laufabschluss-Event → UI-Komponente) und korrigiert die fehlende
+`Platform.runLater()`-Kopplung.
+
+**Technisch:** Vermutlich `adapter-in-gui` und ggf. `bootstrap` (Bridge-Verdrahtung).
+Kein neuer Port, kein Use-Case.
+
+---
+
+### #88 – FAILED_FINAL ohne Fehlerursache im Verlauf-Tab
+
+#### Problem
+
+Der Detailbereich zeigt bei `FAILED_FINAL`-, `FAILED_RETRYABLE`- und
+`SKIPPED_FINAL_FAILURE`-Einträgen keine Fehlerursache an.
+Der Nutzer sieht nur den Status-Icon.
+
+#### Lösung
+
+**Schema-/Code-Analyse als blockierender erster Schritt:**
+
+Vor jeder weiteren Implementierung dokumentiert Claude Code verbindlich,
+welcher Fall vorliegt:
+
+**Fall A – geeignetes Fehlerfeld bereits vorhanden:**
+`processing_attempt` enthält bereits ein nutzbares Fehlerfeld.
+→ Keine Migration. GUI und Abfrage werden um die Anzeige erweitert.
+
+**Fall B – kein geeignetes Fehlerfeld vorhanden:**
+→ Flyway-Migration mit der **nächsten freien Versionsnummer** zum Zeitpunkt
+der Implementierung. Fehlerdetails können nur für ab V3.1 erzeugte
+Verarbeitungsversuche gespeichert werden. Bestehende Einträge bleiben
+unverändert und zeigen den Platzhalter „Keine Fehlerdetails gespeichert."
+
+**Fall C – Fehlerdetails werden bisher nur im Log gespeichert:**
+→ Migration zwingend erforderlich. Zusätzlich muss der Fehlerpfad der
+Verarbeitungslogik um Persistierung der Fehlerdetails erweitert werden.
+
+**Domain-Modul-Einschränkung:**
+
+`pdf-umbenenner-domain` bleibt unverändert, sofern die benötigten
+Fehlerdetails ausschließlich über bestehende oder application-nahe
+History-DTOs transportiert werden können.
+
+Falls das fachliche Attempt-Modell im Domain-Modul liegt und für die
+Anzeige erweitert werden muss, ist eine **minimale Domain-Erweiterung zulässig**.
+Keine Änderung an der fachlichen Kernverarbeitung.
+
+**Datenmodell (bei Migration – Fall B oder C):**
+
+```sql
+-- Versionsnummer = nächste freie Flyway-Version zum Zeitpunkt der Implementierung
+ALTER TABLE processing_attempt ADD COLUMN failure_details TEXT;
+```
+
+`failure_details` enthält eine **nutzerverständliche, gekürzte Fehlerbeschreibung**.
+Provider- oder Exception-Meldungen werden **nicht roh persistiert** –
+gespeichert wird eine kontrolliert erzeugte Kurzmeldung aus bekannten
+Fehlerkategorien oder eine bereinigte/gekürzte Message ohne Stacktrace,
+API-Keys oder vollständige Provider-Rohantworten.
+
+Die Begrenzung auf **1000 Zeichen wird spätestens vor Persistierung im
+DB-Adapter erzwungen**: Längere Texte werden gekürzt und mit „…" markiert.
+Falls bereits vorher ein zentrales Fehler-Mapping existiert, darf dort
+gekürzt werden. Entscheidend: in die DB gelangen nur gekürzte, bereinigte
+Fehlerdetails. Kein SQL-`CHECK`-Constraint (um Alt-/Importdaten nicht
+zu blockieren).
+
+**„Letzter Versuch" – Definition:**
+
+Die angezeigte Fehlerursache stammt aus dem Versuch mit dem höchsten
+`attempt_number`. Bei Gleichstand wird der mit dem jüngsten `ended_at` verwendet.
+
+Die Sortierung wird im Rahmen der Code-Analyse gegen das vorhandene Schema
+verifiziert. Falls `attempt_number` oder `ended_at` nicht existieren, wird
+die technisch eindeutige Sortierung des Attempt-Verlaufs verwendet und
+in der Implementierungsnotiz dokumentiert.
+
+**Anzuzeigende Status:**
+
+Fehlerursache wird angezeigt bei:
+- `FAILED_FINAL`
+- `FAILED_RETRYABLE`
+- `SKIPPED_FINAL_FAILURE` (zeigt die letzte bekannte Fehlerursache des
+  zugrundeliegenden fehlgeschlagenen Attempts – fachlich konsistent,
+  da `SKIPPED_FINAL_FAILURE` direkte Folge eines endgültigen Fehlschlags ist)
+
+Bei fehlendem `failure_details` (NULL oder leer): Platzhaltertext via `promptText`
+analog zu #83.
+
+**Technisch:** `adapter-in-gui` (Anzeige), ggf. `adapter-out-db`
+(Abfrage-Erweiterung), ggf. Flyway-Migration, ggf. minimale Domain-Erweiterung.
+
+---
+
+### #91 – Lock-File relativer Pfad
+
+#### Problem
+
+Der Lock-Mechanismus nutzt einen konfigurierten oder Standard-Pfad für die
+Lock-Datei. Bei relativem Pfad ist das Verzeichnis abhängig vom aktuellen
+Arbeitsverzeichnis. Liegt die JAR unter `C:\Program Files`, ist das Verzeichnis
+zudem nicht beschreibbar.
+
+#### Lösung
+
+**Verhalten abhängig vom Pfadtyp:**
+
+**Absolut konfigurierter Pfad:**
+Wird unverändert verwendet. Schlägt das Anlegen fehl, erfolgt **kein Fallback** –
+der Nutzer hat den Speicherort explizit vorgegeben. Start bricht mit klarer
+Fehlermeldung ab.
+
+**Relativer oder nicht konfigurierter (Default-)Pfad – zweistufige Fallback-Strategie:**
+
+1. **Primär:** Auflösung relativ zum Verzeichnis der JAR-Datei
+   (`CodeSource.getLocation()`)
+2. **Fallback:** Auflösung relativ zu `user.home`
+3. **Abbruch:** Erst wenn auch `user.home` fehlschlägt
+
+**Parent-Verzeichnisse** werden bei Bedarf automatisch angelegt
+(`Files.createDirectories()`).
+
+Der final verwendete **absolute Pfad wird beim Start geloggt** (INFO-Level):
+```
+Lock-Datei: C:\Users\Funny\Documents\pdf-umbenenner.lock
+```
+
+**Gilt für GUI- und Headless-Start.**
+
+**Code-Analyse erforderlich:** Claude Code ermittelt die aktuelle
+Lock-Implementierungslokation (`bootstrap` oder `adapter-out-db`).
+
+---
+
+## GUI-Features
+
+### #82 – Verlauf-Tab: Live-Filter bei Suche
+
+#### Problem
+
+Die Suche im Verlauf-Tab wird nur durch expliziten Klick auf den Such-Button
+ausgelöst. Das erfordert unnötige Interaktion bei jeder Suchanpassung.
+
+#### Lösung
+
+**Live-Filter mit Debounce und Generation-Counter:**
+
+- Das Suchfeld erhält einen `ChangeListener` auf die `textProperty()`
+- Bei jeder Texteingabe startet ein JavaFX-`Timeline`-Debounce-Timer (300 ms)
+- Nach 300 ms ohne weitere Eingabe wird die DB-Abfrage auf einem Worker-Thread gestartet
+
+**Race-Condition-Schutz via Generation-Counter:**
+
+Jede gestartete Suchanfrage erhält eine aufsteigende Generations-ID (atomarer
+`long`-Counter). Der Worker-Thread trägt seine Generations-ID ins Ergebnis.
+Beim `Platform.runLater()`-Callback wird das Ergebnis nur in die UI übernommen,
+wenn die Generations-ID noch aktuell ist – veraltete Worker-Ergebnisse
+werden verworfen.
+
+**Such-Button und Enter-Taste:**
+
+- Klick auf Such-Button oder Enter im Suchfeld: Debounce-Timer sofort abgebrochen,
+  Suche unverzüglich gestartet
+- Barrierefreiheit: Such-Button bleibt erhalten
+
+**Auswahlverhalten nach neuen Suchergebnissen:**
+
+Nach jeder Übernahme neuer Suchergebnisse wird die Tabellenauswahl
+**vollständig geleert**. Detailbereich und Aktionsbuttons werden entsprechend
+zurückgesetzt. Das ist robuster als ein Abgleich der alten Auswahl gegen
+die neue Ergebnisliste und vermeidet Wechselwirkungen mit #86.
+
+**Leeres Suchfeld:** Zeigt alle Einträge (bis LIMIT 501).
+
+**Technisch:** Ausschließlich `adapter-in-gui`. Die bestehende Suchabfrage via
+`GuiHistoryOverviewPort` wird unverändert wiederverwendet.
+
+---
+
+### #86 – Mehrfachauswahl im Verlauf-Tab
+
+#### Problem
+
+Der Verlauf-Tab erlaubt nur Einzelauswahl. Bulk-Operationen sind nicht möglich.
+
+#### Lösung
+
+**Multi-Select-Modus:**
+
+```java
+tableView.getSelectionModel().setSelectionMode(SelectionMode.MULTIPLE);
+```
+
+JavaFX stellt damit Strg+Klick und Shift+Klick automatisch bereit.
+
+**Strg+A – Fokusabhängig:**
+
+Strg+A selektiert alle sichtbaren Tabelleneinträge **nur, wenn die Verlauf-Tabelle
+den Fokus besitzt**. Liegt der Fokus im Suchfeld, bleibt Strg+A die normale
+Textauswahl im Suchfeld.
+
+**Detailbereich bei Mehrfachauswahl:**
+
+- Genau 1 Eintrag: Detailbereich wie bisher
+- Mehrere Einträge: Platzhaltertext „X Einträge ausgewählt."
+
+**Snapshot der fachlichen Schlüssel vor Worker-Thread-Start:**
+
+Vor dem Start einer Bulk-Operation wird ein **unveränderlicher Snapshot der
+fachlichen Schlüssel** erstellt, die die bestehenden Reset-/Delete-Use-Cases
+erwarten (typischerweise Fingerprints, sofern das die vorhandene Use-Case-Signatur
+erwartet). Der Worker-Thread arbeitet ausschließlich auf diesem Snapshot –
+nie auf einer Live-`ObservableList`, die sich während der Operation ändern könnte.
+
+**Aktionsbuttons bei Mehrfachauswahl:**
+
+| Aktion | Verhalten |
+|---|---|
+| „Status zurücksetzen" | Aktiv bei ≥ 1 Auswahl; Bestätigungsdialog: „X Einträge zurücksetzen?" |
+| „Eintrag löschen" | Aktiv bei ≥ 1 Auswahl; Bestätigungsdialog: „X Einträge unwiderruflich löschen?" |
+
+**Bulk-Fehlerstrategie (Partial Success):**
+
+Schlägt eine Operation bei einzelnen Einträgen fehl, werden die restlichen
+trotzdem abgearbeitet. Nach Abschluss erscheint ein **kompakter**
+Zusammenfassungsdialog:
+> „X von Y Einträgen erfolgreich verarbeitet. Z Einträge konnten nicht
+>  verarbeitet werden."
+
+Detaillierte Einzelfehler werden geloggt, nicht in den Dialog gestopft.
+
+**Ausführung:** Bulk-Operationen rufen die bestehenden Use-Cases
+(`DefaultResetDocumentStatusUseCase`, `DefaultDeleteDocumentHistoryUseCase`)
+sequenziell auf dem Worker-Thread auf. Keine neuen Use-Cases erforderlich.
+
+**Sperren während Lauf:** Alle Aktions-Buttons deaktiviert während eines
+aktiven Verarbeitungslaufs.
+
+**Technisch:** Ausschließlich `adapter-in-gui`. Keine neuen Ports oder Use-Cases.
+
+---
+
+### #87 – Neue leere SQLite-Datenbank anlegen
+
+#### Problem
+
+Will der Nutzer mit einer frischen Datenbank starten, muss er die Datei
+manuell löschen. Das ist umständlich und fehleranfällig.
+
+#### Lösung
+
+**Neuer Menüpunkt:**
+
+`Datenbank → Neue Datenbank anlegen...`
+
+(Nur aktiv wenn kein Verarbeitungslauf läuft.)
+
+**Eigentümer des aktiven Datenbankkontexts:**
+
+Der Runtime-Wechsel der aktiven Datenbank erfordert eine zentrale Komponente,
+die den aktiven Datenbankkontext besitzt. Vor der Implementierung analysiert
+Claude Code, ob eine solche Komponente bereits existiert.
+
+- **Fall A – wechselbarer DB-Kontext vorhanden:** Vorhandene Komponente
+  wird genutzt/erweitert.
+- **Fall B – kein wechselbarer DB-Kontext vorhanden:** Es wird ein minimaler
+  `ActiveDatabaseContextPort` eingeführt (Outbound-Port in `application`,
+  Adapter in `bootstrap` oder `adapter-out-db`). Dieser Port ist die einzige
+  Stelle, an der die aktive DB-Referenz umgestellt wird.
+
+**Der DB-Wechsel darf nicht im JavaFX-Code versteckt werden.**
+Der Use-Case `DefaultCreateNewDatabaseUseCase` orchestriert den Wechsel;
+die physische Umstellung der Verbindung delegiert er über den Port.
+
+**Ablauf (atomar aus Anwendungssicht):**
+
+1. `FileChooser` öffnet (Filter: `*.sqlite`); Nutzer wählt Zieldatei
+2. **Pfad-Sicherheitsprüfung:**
+   Die aktive DB und die gewählte Zieldatei werden über **normalisierte,
+   absolut aufgelöste Pfade** verglichen – kein Rohstring-Vergleich.
+   Für existierende Dateien wird `toRealPath()` verwendet; für noch nicht
+   existierende Dateien wird der Parent-Pfad real aufgelöst und der Dateiname
+   normalisiert verglichen. Unter Windows erfolgt der Vergleich case-insensitive.
+   Bei Übereinstimmung: klare Fehlermeldung, kein Überschreiben.
+3. Existiert die Zieldatei (andere als aktive DB): Bestätigungsdialog
+   „Die Datei existiert bereits. Überschreiben?"
+4. **GUI-Sperre:** Während Anlage und Wechsel befindet sich die GUI in einem
+   `DB-Busy`-Zustand. Alle DB-lesenden und DB-schreibenden Aktionen
+   (Live-Suche, Bulk-Reset, Bulk-Delete, Verlauf-Refresh, erneuter
+   Klick auf „Neue Datenbank anlegen") sind deaktiviert. Der Zustand
+   wird nach Erfolg oder Fehler zuverlässig zurückgesetzt.
+5. Neue SQLite-Datei wird als **temporäre Datei im Zielverzeichnis** erzeugt
+6. Flyway führt alle verfügbaren Migrationsskripte gegen die temporäre Datei aus
+   (`migrate()` auf neuesten Schema-Stand)
+7. Neue DB-Verbindung wird **testweise geöffnet und geprüft** (gegen Temp-Datei).
+   Der Verbindungstest prüft mindestens:
+   - SQLite-Verbindung kann geöffnet werden
+   - Flyway-Schema-History ist vorhanden
+   - Eine einfache Leseabfrage gegen Schema-Metadaten ist erfolgreich
+8. Erst nach erfolgreichem Test: temporäre Datei zur Zieldatei verschoben.
+   Bei bereits existierender, bestätigter Zieldatei wird
+   `Files.move(tempFile, targetFile, ATOMIC_MOVE, REPLACE_EXISTING)` verwendet,
+   sofern vom Dateisystem unterstützt. Die vorhandene Zieldatei wird vorher
+   **nicht separat gelöscht**. Wird die Kombination `ATOMIC_MOVE + REPLACE_EXISTING`
+   nicht unterstützt, bricht der Vorgang mit klarer Fehlermeldung ab –
+   kein unsicherer halb-atomarer Fallback.
+9. Aktive DB-Referenz der Anwendung umgestellt (via `ActiveDatabaseContextPort`)
+10. Verlauf-Tab neu geladen → zeigt „Noch keine Verarbeitungen vorhanden."
+11. Statuszeile aktualisiert DB-Pfad
+12. DB-Pfad im Konfigurationsmodell geändert → Konfig-Tab wechselt in Dirty-State
+13. Statuszeile oder Meldungsbereich zeigt:
+    „Neue Datenbank ist aktiv. Konfiguration speichern, damit diese DB
+    beim nächsten Start verwendet wird."
+
+**Fehlerfall ohne partielle Änderung:**
+
+Schlägt ein Schritt (Anlegen, Flyway, Verbindungstest, Move) fehl, bleibt die
+bisher aktive DB **vollständig unverändert in Betrieb**. Die temporäre Datei
+wird gelöscht. Fehlerdialog mit konkreter Meldung.
+
+**Headless:** Die Funktion ist ausschließlich GUI-seitig aufrufbar.
+`adapter-in-cli` ist nicht betroffen.
+
+**Architektur:**
+
+| Komponente | Typ | Modul | Zweck |
+|---|---|---|---|
+| `CreateNewDatabaseUseCase` | Inbound-Port-Interface | `application` | Vertrag: `createNewDatabase(Path)` |
+| `DefaultCreateNewDatabaseUseCase` | Use-Case-Impl. | `application` | Atomarer DB-Wechsel: Temp-Datei, Flyway, Test, Move, Kontext-Umstellung |
+| `DatabaseCreationPort` | Outbound-Port | `application` | `createAndInitialize(Path tempFile)` |
+| `ActiveDatabaseContextPort` | Outbound-Port | `application` | `switchActiveDatabase(Path newDbFile)` – Eigentümer des Laufzeitkontexts |
+| `GuiCreateNewDatabasePort` | Bridge-Interface | `adapter-in-gui` | Brücke zum Use-Case |
+| `SqliteDatabaseCreationAdapter` | Outbound-Adapter | `adapter-out-db` | SQLite-Temp-Datei erzeugen, Flyway migrate auf latest, Verbindung testen |
+| `SqliteActiveDatabaseContextAdapter` | Outbound-Adapter | `bootstrap` oder `adapter-out-db` | Umschalten der aktiven DB-Referenz (Analyse erforderlich) |
+
+---
+
+### #32 – Mausrad-Zoom in PDF-Vorschau
+
+#### Problem
+
+Die PDF-Vorschau lässt sich nur über die Zoom-Buttons skalieren.
+Ein Mausrad-Zoom fehlt.
+
+#### Lösung
+
+**Scroll-Event auf der PDF-Vorschau-Komponente:**
+
+```java
+scrollPane.addEventFilter(ScrollEvent.SCROLL, event -> {
+    if (event.isControlDown()) {
+        accumulateAndApplyZoomDelta(event.getDeltaY());
+        event.consume(); // immer konsumieren bei Strg, kein paralleles Scrollen
+    }
+    // ohne Strg: normales Scrollen bleibt
+});
+```
+
+**Bei gedrückter Strg-Taste werden ScrollEvents grundsätzlich konsumiert**,
+damit kein paralleles Scrollen im ScrollPane erfolgt – auch wenn der Delta
+zu klein für einen Zoomschritt ist.
+
+**Delta-Akkumulation für Trackpad-Kompatibilität:**
+
+Sehr kleine Trackpad-Deltas werden **intern akkumuliert**, bis die Mindestschwelle
+für einen Zoomschritt erreicht ist. Kein Verwerfen: akkumulierte Deltas
+ergeben bei genug Trackpad-Wischbewegung sauber einen Zoomschritt.
+Als Orientierungswert gilt ±10 % je „Notch" eines Standard-Mausrads.
+
+**Zoom-Verhalten:**
+
+| Parameter | Wert |
+|---|---|
+| Auslöser | Strg + Mausrad |
+| Schrittweite | Vorzeichenbasiert auf akkumuliertem `deltaY`, ca. 10 % je Notch |
+| Minimum | 10 % |
+| Maximum | 500 % |
+| Zurücksetzen bei neuem PDF | Ja (Zoom auf Fit-to-Width) |
+
+**Fit-to-Width-Modus:**
+
+Nach manuellem Strg+Mausrad-Zoom verlässt die Vorschau den Fit-to-Width-Modus.
+Fit-to-Width wird erst wieder aktiv, wenn ein neues PDF geladen oder der
+Fit-to-Width-Button explizit erneut betätigt wird.
+
+**Viewport-Stabilität:**
+
+Beim Zoom bleibt die sichtbare Viewport-Mitte möglichst erhalten.
+
+**Zoom-State-Konsistenz:**
+
+Der Zoom-State wird über dieselbe Variable geführt, die auch die
+Toolbar-Zoom-Buttons bedienen.
+
+**Technisch:** Ausschließlich `adapter-in-gui`. Kein neuer Port, kein Use-Case.
+
+---
+
+## Architektur-Zusammenfassung
+
+### Neue Inbound-Port-Interfaces und Use-Cases
+
+| Komponente | Typ | Modul | Zweck | Issue |
+|---|---|---|---|---|
+| `CreateNewDatabaseUseCase` | Inbound-Port-Interface | `application` | Vertrag für DB-Anlage | #87 |
+| `DefaultCreateNewDatabaseUseCase` | Use-Case-Impl. | `application` | Atomarer DB-Wechsel via Temp-Datei + Port-Delegation | #87 |
+
+### Neue Outbound-Ports
+
+| Komponente | Modul | Zweck | Issue |
+|---|---|---|---|
+| `DatabaseCreationPort` | `application` | Temp-Datei erzeugen, Flyway, Verbindungstest | #87 |
+| `ActiveDatabaseContextPort` | `application` | `switchActiveDatabase(Path)` – Laufzeit-DB-Kontext | #87 |
+
+### Neue Bridge-Interfaces (adapter-in-gui)
+
+| Interface | Zweck | Issue |
+|---|---|---|
+| `GuiCreateNewDatabasePort` | Brücke zur DB-Anlage | #87 |
+
+### Neue Adapter
+
+| Adapter | Modul | Zweck | Issue |
+|---|---|---|---|
+| `SqliteDatabaseCreationAdapter` | `adapter-out-db` | SQLite-Temp-Datei, Flyway migrate auf latest, Test | #87 |
+| `SqliteActiveDatabaseContextAdapter` | `bootstrap` oder `adapter-out-db` | Umschalten der aktiven DB-Referenz (Lokation via Code-Analyse) | #87 |
+
+### Geänderte Komponenten (adapter-in-gui)
+
+| Komponente | Änderung | Issues |
+|---|---|---|
+| `GuiHistoryTab` | Multi-Select + Schlüssel-Snapshot, Live-Filter + Generation-Counter + Auswahl leeren, Fehlerursache, Platzhalter via promptText, Tooltips, DB-Busy-Sperre | #82, #83, #86, #88, #77, #87 |
+| `GuiConfigTab` | Dirty-State mit Baseline-Snapshot + loadingInProgress, Tab-Titel, Dialog, Kopplung mit #87 | #80 |
+| `GuiTooltipTexts` | Neue Tooltip-Konstanten; TableColumn-Header via Column-Graphic-Pattern | #77 |
+| Verlauf-Detailbereich | Enum-Displaytext (alle 8 Werte), Fehlerursache für FAILED/SKIPPED_FINAL | #81, #88 |
+| Status-ComboBox | `StringConverter<ProcessingStatus>`, „Alle Status" als GUI-interner Null-Filter | #81 |
+| PDF-Vorschau-Komponente | Delta-Akkumulation, Strg+Scroll konsumiert, Viewport-Stabilität, Fit-to-Width-Modus | #32 |
+| Lauf-Abschluss-Signalkette | Ereignisgetriebene Button-State-Neuberechnung für alle Terminierungsgründe | #84 |
+
+### Geänderte Komponenten (sonstige)
+
+| Komponente | Modul | Änderung | Issue |
+|---|---|---|---|
+| Lock-File-Auflösung | `bootstrap` oder `adapter-out-db` | Absolut: direkt + Abbruch; Relativ: JAR-Dir → user.home → Abbruch; Parent-Dirs; Logging | #91 |
+
+### Nicht geändert
+
+- `pdf-umbenenner-domain` – keine Änderungen, außer ggf. minimale Erweiterung
+  für #88 falls Attempt-Modell dort liegt (zulässig, keine Kernverarbeitungslogik)
+- `pdf-umbenenner-adapter-in-cli` – keine neuen Funktionen
+- Headless-Verarbeitungslogik – vollständig unberührt
+- Kernverarbeitungslogik (PDF lesen → KI → umbenennen)
+
+---
+
+## Datenbankmigrationen
+
+Flyway ist die einzige Schema-Evolutionsquelle.
+
+### Potenzielles Migrationsskript (abhängig von Code-Analyse #88)
+
+Vor der Implementierung von #88 dokumentiert Claude Code verbindlich,
+ob ein Fehlerfeld bereits im Schema existiert (Fall A / B / C – siehe #88).
+
+**Nur bei Fall B oder C:**
+
+```sql
+-- Fehlerdetails in processing_attempt ergänzen
+-- Versionsnummer = nächste freie Flyway-Version zum Zeitpunkt der Implementierung
+ALTER TABLE processing_attempt ADD COLUMN failure_details TEXT;
+```
+
+- `failure_details`: nutzerverständliche, gekürzte Fehlerbeschreibung;
+  Begrenzung auf 1000 Zeichen **vor Persistierung im Adapter** erzwungen,
+  Kürzung mit „…"; kein SQL-`CHECK`-Constraint
+- Bestehende Zeilen erhalten automatisch `NULL` – kein Datenverlust
+- Alte Einträge ohne Fehlerdetails zeigen `promptText`-Platzhalter in der GUI
+
+---
+
+## Definition of Done (V3.1 gesamt)
+
+- [ ] Alle 11 Issues implementiert und einzeln getestet
+- [ ] `mvn clean verify` grün (alle Module, kein `-DskipTests`)
+- [ ] `mvn clean install -Drevision=3.1.0` – Build ohne Fehler
+- [ ] Manueller GUI-Produkttest durchgeführt (Green build ≠ fertige Software)
+- [ ] Keine Enum-Rohnamen in der GUI sichtbar (alle 8 Statuswerte mit Displaytext)
+- [ ] Alle fehlenden Tooltips vorhanden; TableColumn-Header via Column-Graphic-Pattern
+- [ ] Dirty-Indikator Konfig-Tab: kein programmgesteuertes Feuern, Baseline-Snapshot korrekt
+- [ ] Live-Filter: 300 ms Debounce, Generation-Counter, Auswahl nach Suche geleert
+- [ ] Mehrfachauswahl: Strg+A nur bei Tabellenfokus; Schlüssel-Snapshot; Partial-Success-Dialog
+- [ ] `FAILED_FINAL`/`FAILED_RETRYABLE`/`SKIPPED_FINAL_FAILURE`: Fehlerursache sichtbar (oder Platzhalter)
+- [ ] Leere `ai_reasoning`: `promptText`-Platzhalter (kein echter Text)
+- [ ] Aktionsbuttons ereignisgetrieben reaktiviert nach allen Terminierungsgründen
+- [ ] #87 Code-Analyse: DB-Kontext-Eigentümer dokumentiert (Fall A oder B)
+- [ ] #87: Atomarer Ablauf via Temp-Datei; Pfadvergleich normalisiert + case-insensitive
+- [ ] #87: Aktive DB bleibt bei Fehler unverändert; DB-Busy-Sperre korrekt zurückgesetzt
+- [ ] #87: Flyway auf neuesten Stand; Hinweismeldung nach Wechsel
+- [ ] Strg+Mausrad-Zoom: Delta-Akkumulation, immer konsumiert bei Strg, 10%–500%
+- [ ] Lock-File: Absolut direkt; Relativ zweistufig; Parent-Dirs; Pfad geloggt
+- [ ] Code-Kommentare auf Deutsch; Logging auf Deutsch
+- [ ] JavaDoc auf allen neuen öffentlichen Ports, Use-Cases und Adapter-Methoden
+- [ ] `betrieb.md` und `gui-bedienanleitung.md` auf V3.1-Stand gebracht
+- [ ] Freigabedokument `freigabe-v3_1.md` erstellt
+
+---
+
+## Abnahmekriterien je Feature
+
+### #77 Fehlende Tooltips
+- [ ] Vollständige Bestandsaufnahme: Liste aller Elemente ohne Tooltip erstellt
+- [ ] Alle identifizierten Elemente haben Tooltips (Anzahl aus Bestandsaufnahme)
+- [ ] TableColumn-Header: Column-Graphic mit Label+Tooltip, kein Skin-/Lookup-Hack
+- [ ] Column-Graphic: Sortierung, Header-Breite und CSS nicht sichtbar verschlechtert
+- [ ] Neue Konstanten ausschließlich in `GuiTooltipTexts`, keine hartcodierten Strings
+
+### #80 Dirty-Indikator Konfig-Tab
+- [ ] Tab-Titel `* Konfiguration` nur nach echter Nutzeränderung gegenüber Baseline-Snapshot
+- [ ] Programmgesteuertes Laden setzt kein Dirty-Flag (`loadingInProgress`-Schutz)
+- [ ] Tab-Titel `Konfiguration` nach Speichern
+- [ ] Bestätigungsdialog bei Laden neuer Konfig mit Dirty State
+- [ ] DB-Pfad-Wechsel via #87 setzt Konfig-Tab dirty
+- [ ] UX identisch zum Prompt-Tab (Sternchen, Dialog, Reset)
+
+### #81 Enum-Bezeichnungen
+- [ ] Status-ComboBox: „Alle Status" als erster Eintrag (GUI-interner Null-Filter)
+- [ ] Status-ComboBox: alle 8 Statuswerte als Displaytext
+- [ ] Versuche-Tabelle: alle 8 Statuswerte als Displaytext
+- [ ] DB-Queries intern weiterhin mit Enum-Namen
+- [ ] Kein Enum-Rohname für Endnutzer sichtbar
+
+### #82 Live-Filter
+- [ ] Suche startet nach 300 ms Tipp-Pause automatisch
+- [ ] Generation-Counter: veraltete Worker-Ergebnisse werden verworfen
+- [ ] Such-Button / Enter: sofortige Suche, Debounce abgebrochen
+- [ ] Auswahl nach neuen Suchergebnissen vollständig geleert
+- [ ] Leeres Suchfeld zeigt alle Einträge
+- [ ] Worker-Thread, UI via `Platform.runLater()`
+
+### #83 KI-Begründung leer
+- [ ] `textArea.setPromptText(...)` bei leerem/null `ai_reasoning`
+- [ ] `textArea.setText("")` – kein Platzhaltertext als echter Inhalt
+- [ ] TextArea bleibt sichtbar
+
+### #84 Buttons reaktivieren
+- [ ] Aktionsbuttons während Lauf deaktiviert
+- [ ] Reaktivierung ereignisgetrieben nach: Erfolg, Fehlerabbruch, Nutzerabbruch, Exception
+- [ ] Keine manuellen Workarounds notwendig
+
+### #86 Mehrfachauswahl
+- [ ] `SelectionMode.MULTIPLE` aktiv
+- [ ] Strg+A nur bei Tabellenfokus (kein Konflikt mit Suchfeld)
+- [ ] Strg+Klick, Shift+Klick korrekt
+- [ ] Detailbereich: „X Einträge ausgewählt." bei Mehrfachauswahl
+- [ ] Schlüssel-Snapshot vor Worker-Thread-Start
+- [ ] Bulk-Reset: Bestätigungsdialog + Partial-Success-Dialog
+- [ ] Bulk-Delete: Bestätigungsdialog + Partial-Success-Dialog
+- [ ] Aktionen während Lauf gesperrt
+
+### #87 Neue Datenbank anlegen
+- [ ] Code-Analyse: DB-Kontext-Eigentümer dokumentiert, Fall A oder B entschieden
+- [ ] Menüpunkt vorhanden, nur außerhalb von Läufen aktiv
+- [ ] Aktive DB über normalisierten Pfadvergleich (case-insensitive, toRealPath) erkannt
+- [ ] Bestehende Fremddatei: Überschreiben-Bestätigung
+- [ ] DB-Busy-Sperre während Anlage aktiv; nach Erfolg/Fehler zuverlässig zurückgesetzt
+- [ ] Neue DB als Temp-Datei; Flyway auf neuesten Stand
+- [ ] Verbindungstest: Verbindung öffnen, Flyway-History prüfen, Leseabfrage erfolgreich
+- [ ] Move mit `ATOMIC_MOVE + REPLACE_EXISTING`; vorhandene Datei nicht vorher separat löschen
+- [ ] Kein halb-atomarer Fallback bei nicht unterstützter Kombination
+- [ ] Fehlerfall: Temp-Datei gelöscht, aktive DB unverändert, Fehlerdialog
+- [ ] `ActiveDatabaseContextPort.switchActiveDatabase()` schaltet Referenz um
+- [ ] Verlauf-Tab: „Noch keine Verarbeitungen vorhanden."
+- [ ] Statuszeile aktualisiert DB-Pfad
+- [ ] Konfig-Tab wechselt in Dirty-State
+- [ ] Hinweismeldung: Konfiguration speichern nicht vergessen
+
+### #88 Fehlerursache FAILED_FINAL
+- [ ] Schema-/Code-Analyse: Fall A/B/C dokumentiert vor Implementierung
+- [ ] Ggf. Flyway-Migration mit nächster freier Versionsnummer
+- [ ] Sortierung für „letzter Versuch" gegen Schema verifiziert
+- [ ] Detailbereich: `failure_details` bei `FAILED_FINAL`, `FAILED_RETRYABLE`, `SKIPPED_FINAL_FAILURE`
+- [ ] NULL/leer: `promptText`-Platzhalter
+- [ ] 1000-Zeichen-Grenze spätestens vor DB-Persistierung erzwungen, Kürzung mit „…"
+- [ ] Keine rohen Provider-/Exception-Meldungen persistiert
+
+### #91 Lock-File Pfad
+- [ ] Absoluter Pfad: direkt verwendet, kein Fallback, Abbruch bei Fehler
+- [ ] Relativer Pfad: erst JAR-Verzeichnis, dann `user.home`, dann Abbruch
+- [ ] Parent-Verzeichnisse automatisch angelegt
+- [ ] Absoluter Pfad beim Start geloggt (INFO)
+- [ ] Gilt für GUI- und Headless-Start
+
+### #32 Mausrad-Zoom
+- [ ] Strg+Scroll: Event grundsätzlich konsumiert (kein paralleles Scrollen)
+- [ ] Delta-Akkumulation für kleine Trackpad-Deltas
+- [ ] Zoom 10%–500%, ca. 10 % je Notch
+- [ ] Ohne Strg: normales Scrollen
+- [ ] Viewport-Mitte beim Zoom möglichst stabil
+- [ ] Fit-to-Width-Modus verlassen nach manuellem Zoom
+- [ ] Zoom-Reset bei neuem PDF (Fit-to-Width)
+- [ ] Zoom-State konsistent mit Toolbar-Zoom-Buttons
@@ -66,9 +66,9 @@ Fallback auf aktuelles Datum ist erlaubt, wenn kein belastbares Datum eindeutig

 ### 4.3 Titel

- maximal **20 Zeichen (Basistitel)**
+- maximal **konfigurierbare Anzahl Zeichen (Basistitel, Default 60, gültiger Bereich 10..120)**
 - verständlich und eindeutig
- keine Sonderzeichen außer Leerzeichen
+- keine Sonderzeichen außer Leerzeichen, Bindestrichen, Punkten, Kommas und Ampersands

 ---

@@ -87,7 +87,7 @@ Bei Namenskonflikten:

 Regel:

- 20 Zeichen gelten nur für den Basistitel
+- die konfigurierte maximale Titellänge gilt nur für den Basistitel
 - Suffix wird zusätzlich ergänzt

 ---
@@ -192,7 +192,7 @@ Ein Ergebnis ist korrekt, wenn:

 - Format stimmt
 - Datum korrekt ist
- Titel max. 20 Zeichen hat
+- Titel die konfigurierte maximale Länge einhält
 - Dubletten korrekt behandelt wurden
 - Begründung vorhanden ist
 - Ergebnis reproduzierbar ist
@@ -201,12 +201,31 @@ Ein Ergebnis ist korrekt, wenn:

 ## 14. Nicht-Ziele

- keine manuelle Nachbearbeitung
- keine Benutzerinteraktion
+- kein manueller Verarbeitungslauf durch den Benutzer (die KI-Verarbeitungskette
+  läuft ausschließlich automatisiert)
 - keine Inhaltsänderung von Dokumenten

 ---

+## 14a. Manuelle Korrektur des Dateinamens nach automatischer Verarbeitung
+
+Nach Abschluss eines automatisierten Verarbeitungslaufs kann der Benutzer den von der
+KI vorgeschlagenen Dateinamen der Zieldatei **manuell korrigieren**.
+
+Verbindliche Regeln:
+
+- Die Korrektur ist **optional** und ersetzt keinen erneuten KI-Aufruf.
+- Der geänderte Dateiname muss denselben Formatregeln genügen wie ein automatisch
+  erzeugter Name (`YYYY-MM-DD - Titel.pdf`, zulässige Sonderzeichen, Titellänge).
+- Namenskonflikte im Zielordner werden durch Dubletten-Suffix aufgelöst
+  (analog zur automatischen Verarbeitung).
+- Die Umbenennung ist **atomar**: entweder Dateisystem und Datenbank werden
+  konsistent aktualisiert, oder die Aktion wird vollständig zurückgerollt.
+- Die Quelldatei bleibt unverändert.
+- Ein manuell korrigierter Dateiname wird in der Versuchshistorie persistiert.
+
+---
+
 ## 15. Qualitätsanforderungen

 - deterministisches Verhalten
@@ -0,0 +1,628 @@
+# Meilensteine V2.0 – JavaFX-GUI, Konfigurationskomfort und technischer Ausbau
+
+## Zweck dieses Dokuments
+
+Dieses Dokument beschreibt den geplanten Ausbau des Projekts **ab dem final freigegebenen Stand V1.1** hin zu **V2.0** sowie einen klar abgegrenzten **Ausblick auf spätere Ausbaustufen**.
+
+Es ergänzt die bestehenden Spezifikationsdokumente und den dokumentierten Ist-Stand V1.1 um eine neue, bewusst größere Produktstufe. V2.0 erweitert die bisher reine Batch-Anwendung um eine **lokale JavaFX-Desktop-GUI**, ohne die bestehende Architektur, das Standalone-JAR-Betriebsmodell oder den headless Scheduler-Betrieb aufzugeben.
+
+Das Dokument ist als Planungs- und Strukturierungsgrundlage gedacht. Es definiert **keine Arbeitspakete**, sondern die **neuen Meilensteine, Abgrenzungen und Ausbaustufen** für den nächsten Entwicklungsschritt.
+
+---
+
+## Einordnung von V2.0
+
+### Ausgangsbasis
+
+V1.1 ist der aktuelle, fertig implementierte und abgenommene Stand des Projekts.
+
+Darauf aufbauend gilt:
+
+- V1 ist fachlich und technisch vollständig umgesetzt.
+- V1.1 erweitert V1 minimal-invasiv um native Claude-Unterstützung.
+- Das bisherige Betriebsmodell bleibt ein **lokal gestartetes Standalone-JAR**.
+- Der Batch-Betrieb über **Windows Task Scheduler** bleibt weiterhin erhalten.
+- Die Anwendung arbeitet bisher **ohne GUI**, **ohne Webserver**, **ohne App-Server**.
+- Die technische Konfiguration erfolgt weiterhin über **`.properties`**.
+- Es gibt bereits **mehrere Provider-Konfigurationen**, aber immer **genau einen aktiven Provider**.
+
+### Warum V2.0 und nicht V1.x
+
+Der geplante GUI-Ausbau ist kein kleiner Nachschlag zu V1.1, sondern eine neue Produktstufe.
+
+V2.0 ist gerechtfertigt, weil gleichzeitig neu hinzukommen:
+
+- neuer Standard-Startmodus über eine Desktop-GUI
+- zusätzlicher Inbound-Adapter für JavaFX
+- neuer Benutzerzugang zur Konfiguration
+- technische Tests und Korrekturhilfen in der GUI
+- neue CLI-Option `--config <pfad>` für beide Startarten
+- Windows-zentrierte Desktop-Unterstützung mit gemappten Laufwerken
+
+V2.0 bleibt jedoch architekturtreu und bewahrt das bisherige Kernziel der Anwendung:
+
+> PDFs automatisiert scannen, fachlich verarbeiten und korrekt benannte Zielkopien erzeugen.
+
+---
+
+## Unveränderte Leitplanken auch in V2.0
+
+Die folgenden Grundprinzipien bleiben in V2.0 ausdrücklich erhalten:
+
+- **Java 21**
+- **Maven Multi-Module**
+- **ausführbares Standalone-JAR**
+- **kein Webserver**
+- **kein Applikationsserver**
+- **keine Dauerlauf-Anwendung**
+- **kein interner Scheduler**
+- **strikte hexagonale Architektur / Ports and Adapters**
+- **Abhängigkeiten zeigen nach innen**
+- **`.properties` bleibt die einzige Konfigurationswahrheit**
+- **bestehender headless Batch-Betrieb bleibt erhalten**
+- **genau ein aktiver Provider**
+- **keine neue Persistenz-Wahrheit**
+- **fachliche Kernlogik des PDF-Umbenenners bleibt unverändert**
+
+---
+
+## Zielbild von V2.0
+
+V2.0 erweitert die Anwendung um eine **lokale JavaFX-Desktop-GUI**.
+
+### Start- und Betriebsmodell in V2.0
+
+- Die Anwendung bleibt **ein einziges ausführbares JAR**.
+- **GUI ist der neue Standardstart**.
+- Über `--headless` startet weiterhin der bestehende Server-/Scheduler-Betrieb.
+- Über `--config <pfad>` kann sowohl der GUI- als auch der headless Start auf eine konkrete Konfigurationsdatei zeigen.
+- Bestehendes headless Standardverhalten ohne `--config` bleibt aus Abwärtskompatibilitätsgründen erhalten.
+- Wenn `--config <pfad>` im **headless** Start auf eine nicht existente Datei zeigt, ist dies ein **harter Startfehler**; ein stiller Fallback auf das Default-Verhalten ist in diesem Fall unzulässig.
+- Wenn `--config <pfad>` im **GUI-Start** auf eine nicht existente Datei zeigt:
+  - erscheint eine Fehlermeldung,
+  - danach verhält sich die GUI so, als wäre `--config` nicht angegeben worden.
+
+### Plattformziel
+
+- V2.0-GUI wird **offiziell nur unter Windows** unterstützt.
+- Der headless Betrieb bleibt für den Windows Server-Betrieb geeignet.
+- **Gemappte Laufwerke** wie `S:\` oder `H:\` sind ausdrücklich zu unterstützen.
+- Eine Ablehnung solcher Pfade allein wegen eines dahinterliegenden UNC-Backings ist unzulässig.
+
+### GUI-Threadingmodell
+
+Jede potenziell blockierende Operation der GUI – insbesondere providerseitiger Modellabruf, providerseitige technische Tests, Pfad- und Dateisystemprüfungen, SQLite-Prüfungen sowie das Lesen und Schreiben der `.properties`-Datei – läuft auf einem Hintergrund-Worker-Thread. UI-Updates erfolgen ausschließlich über den JavaFX Application Thread (`Platform.runLater`). Die GUI darf während laufender Hintergrund-Operationen nicht einfrieren.
+
+### Packaging-Ziel
+
+- JavaFX wird **mit dem JAR ausgeliefert**.
+- Es gibt in V2.0 **keine EXE**.
+- Es gibt in V2.0 **keinen Installer**.
+- `--headless` darf logisch weiterhin ohne GUI-Pfadzweige funktionieren; GUI-Code darf den headless Ablauf nicht unnötig früh initialisieren.
+
+### Modulziel in V2.0
+
+Die Modulstruktur wird um **genau ein neues Modul** erweitert:
+
+- `pdf-umbenenner-domain`
+- `pdf-umbenenner-application`
+- `pdf-umbenenner-adapter-in-cli`
+- `pdf-umbenenner-adapter-in-gui`
+- `pdf-umbenenner-adapter-out`
+- `pdf-umbenenner-bootstrap`
+
+Die GUI wird **nicht** im Bootstrap-Modul vermischt, sondern als eigener Inbound-Adapter umgesetzt.
+
+### Logging in der GUI
+
+Der GUI-Adapter nutzt denselben Log4j2-Stack wie der headless Pfad. Mindestens geloggt werden: Start- und Beendigungsereignisse der GUI, Modellabruf-Versuche (Provider, Erfolg/Misserfolg, ohne API-Key), Dateischreibvorgänge inkl. Zielpfad, Ergebnisse der Aktionen `Validieren` und `Technische Tests ausführen`, sowie alle schreibenden Korrekturen. Das Logformat und der Log-Pfad bleiben gegenüber dem headless Betrieb unverändert.
+
+### Exit-Codes
+
+- **`0`** für die normale erfolgreiche Beendigung eines headless Laufs sowie für das reguläre Beenden der GUI.
+- **`1`** für harte Start-, Bootstrap-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler, einschließlich ungültiger CLI-Verwendung, nicht existenter `--config`-Datei im headless Start und GUI-Startfehlern vor erfolgreicher Anzeige der Oberfläche.
+- Dokumentbezogene Verarbeitungsfehler im headless Lauf ändern dieses Exit-Code-Modell nicht; sie bleiben Teil des fachlichen Laufresultats wie bereits in V1.1.
+
+---
+
+## V2.0-Funktionsumfang
+
+### 1. GUI als Konfigurations- und Diagnose-Frontend
+
+V2.0 führt **noch keinen manuellen Verarbeitungslauf** in der GUI ein.
+
+Die V2.0-GUI dient zunächst ausschließlich als:
+
+- Editor für die bestehende `.properties`-Konfiguration
+- technische Validierungsoberfläche
+- technische Test- und Diagnoseoberfläche
+- komfortable Dateiauswahl- und Speichermaske
+
+### 2. Struktur der V2.0-GUI
+
+V2.0 enthält **genau einen Tab** mit einer klaren, festen Gliederung.
+
+Reihenfolge:
+
+1. **Header mit Konfigurationsdatei**
+2. **Pfade**
+3. **Provider**
+4. **Verarbeitungslimits**
+5. **Tests**
+6. **Meldungen**
+
+Beim Start ohne geladene Konfiguration wird **kein leerer Standardentwurf** angezeigt. Stattdessen erscheint ein **deutscher Willkommenstext** mit Hinweis auf **„Neu“** und **„Öffnen“**.
+
+### 3. Dateiverhalten der GUI
+
+- Es wird **keine Konfiguration automatisch geladen**.
+- Die GUI kann bestehende `.properties`-Dateien **öffnen**.
+- Die GUI kann **neue Konfigurationen** anlegen.
+- Eine neue Konfiguration startet mit einer **vollständigen Standardvorlage** mit sinnvollen Standardwerten.
+- Beide bekannten Provider-Blöcke sind in der Datei vorhanden.
+- Standardmäßig ist der **alphabetisch erste vorhandene Provider** aktiv; im aktuellen Stand ist das **Claude**.
+- **Speichern** ist immer erlaubt.
+- Bei einer neuen, noch nie gespeicherten Konfiguration verhält sich **„Speichern“** wie **„Speichern unter“**.
+- **„Speichern unter“** schlägt standardmäßig denselben Standardpfad vor, den der bestehende headless Betrieb in V1.1 verwendet, also `config/application.properties` relativ zum Arbeitsverzeichnis. Dadurch ist die in der GUI gespeicherte Datei ohne weitere Schritte für den nächsten headless Scheduler-Lauf nutzbar.
+- Bei existierender Zieldatei erscheint die Rückfrage **„Datei überschreiben?“**.
+- Vor dem Überschreiben einer bestehenden `.properties`-Datei legt die GUI eine `.bak`-Sicherung im selben Schema wie der bestehende V1.1-Migrationspfad an (`<dateiname>.bak`, bei Kollision `.bak.1`, `.bak.2`, …).
+- Datei-Dialoge filtern auf **`*.properties`**.
+- Ungespeicherte Änderungen werden im **Fenstertitel** und im **Header** markiert.
+- Vor **Neu**, **Öffnen** oder **Schließen** erscheint bei ungespeicherten Änderungen ein Dialog mit:
+  - **Speichern**
+  - **Verwerfen**
+  - **Abbrechen**
+
+### 4. Umgang mit der bestehenden Konfigurationsdatei
+
+- Die GUI liest, bearbeitet und schreibt dieselbe `.properties`-Datei wie der headless Betrieb.
+- Wenn die GUI eine Datei in der Legacy-Form aus Vor-V1.1 öffnet, wendet sie dieselbe Migrationslogik wie der headless Pfad an: zuerst `.bak`-Sicherung der Originaldatei, dann Überführung in das neue Mehrprovider-Schema, dann Anzeige im Editor. Dem Benutzer wird die durchgeführte Migration sichtbar im zentralen Meldungsbereich gemeldet.
+- Kommentare und Reihenfolge dürfen beim Speichern **normalisiert** werden.
+- Die GUI darf **alle aktuell bekannten Konfigurationswerte** bearbeiten.
+- Es wird **kein neues Konfigurationsformat** eingeführt.
+
+### 5. Provider-Bereich in V2.0
+
+- Es gibt eine **Provider-ComboBox**.
+- Sichtbar ist immer nur der **aktuell ausgewählte Provider-Bereich**.
+- Ein Provider-Wechsel löscht die Daten des anderen Providers **nicht**.
+- Die GUI muss also mit der bestehenden Mehrprovider-Dateistruktur kompatibel bleiben.
+- Sichtbare Providerbezeichnungen können zunächst pragmatisch sein, z. B.:
+  - **Claude**
+  - **OpenAI-kompatibel**
+
+### 6. Modellwahl in V2.0
+
+- Nach Providerwechsel startet der **Modellabruf automatisch**.
+- Wenn eine Modellliste erfolgreich geladen werden kann:
+  - erscheint eine **nicht editierbare ComboBox**,
+  - die **nie leer** ist,
+  - deren **erstes Modell automatisch vorbelegt** ist.
+- Wenn keine Modellliste verfügbar ist:
+  - erscheint statt der ComboBox ein **leeres Texteingabefeld**,
+  - das Modell muss dann manuell eingetragen werden.
+- Ein zuvor manuell eingetragener Modellname wird verworfen, wenn später eine echte Modellliste geladen wird und der Wert dort nicht vorkommt.
+
+### 7. Felder, Picker und Pfadangaben
+
+Für folgende Pfade gibt es jeweils:
+
+- ein **Texteingabefeld**
+- plus einen **kleinen nativen Datei-/Ordnerdialog-Button**
+
+Dies gilt mindestens für:
+
+- Quellordner
+- Zielordner
+- SQLite-Datei
+- Prompt-Datei
+
+### 8. API-Key in V2.0
+
+- Der API-Key wird direkt in der `.properties`-Datei gespeichert und bearbeitet.
+- Die GUI respektiert dabei die bestehende V1.1-Auflösungsreihenfolge:
+  1. providerspezifische Umgebungsvariable,
+  2. bei **OpenAI-kompatibel** zusätzlich die bestehende Legacy-Umgebungsvariable,
+  3. Property-Wert aus der `.properties`-Datei.
+- Die GUI macht diese Herkunft für den Benutzer sichtbar, insbesondere wenn aktuell eine Umgebungsvariable Vorrang vor dem in der Datei eingetragenen Wert hat.
+- Das GUI-Feld ist bewusst als **normales, unmaskiertes Textfeld** vorgesehen; dies ist eine pragmatische V2.0-Entscheidung und keine Sicherheitsbehauptung.
+- Ein leeres GUI-Feld darf einen bereits vorhandenen Property-Wert **nicht stillschweigend löschen**, wenn keine Umgebungsvariable greift. In diesem Fall bleibt der bestehende Property-Wert erhalten und es erscheint eine deutliche Warnung.
+
+### 9. Meldungen und feldnahe Validierung
+
+V2.0 enthält zwei Ebenen der Benutzerführung:
+
+#### A. zentraler Meldungsbereich unten
+
+Der Meldungsbereich ist:
+
+- groß
+- nicht editierbar
+- dauerhaft sichtbar
+
+Er nutzt vier feste Stufen:
+
+- **Info**
+- **Hinweis**
+- **Warnung**
+- **Fehler**
+
+Dabei gilt:
+
+- nur das Präfix (**„Info:“**, **„Hinweis:“**, **„Warnung:“**, **„Fehler:“**) ist farbig
+- der eigentliche Text derselben Zeile bleibt schwarz
+
+#### B. feldnahe Validierung
+
+Bei Eingabefehlern erscheint direkt unter dem betroffenen Feld:
+
+- eine **kleine**
+- **rote**
+- **deutschsprachige**
+- **hilfreiche** Fehlermeldung
+
+### 10. Automatische Validierung beim Öffnen und während der Bearbeitung
+
+- **Automatische Validierung** bezeichnet in V2.0 die im Hintergrund laufende Prüfung aus M11.
+- Eine geladene Konfiguration wird **sofort beim Öffnen** geprüft.
+- Es gibt **Fehler**, **Warnungen** und **Hinweise**.
+- Auch **unsinnige, aber formal gültige Einstellungen** werden als Warnung bewertet.
+- `max.text.characters` erhält in V2.0 bewusst wirtschaftliche Warnschwellen:
+  - bis **1.000**: unkritisch
+  - **1.001–3.000**: Warnung
+  - ab **3.001**: starke Warnung
+- `max.pages` dient in V2.0 nur als **Plausibilitäts-/Performance-Hinweis**, nicht als primäre Kostenwarnung.
+- Warnungen verhindern das Speichern nicht.
+- Fehler markieren den Zustand als **nicht lauffähig**.
+- **Speichern bleibt trotzdem erlaubt**.
+- Vor dem Speichern eines als **nicht lauffähig** markierten Stands erscheint jedoch eine deutlich sichtbare Warnung im zentralen Meldungsbereich, die ausdrücklich auf mögliche Auswirkungen auf den nächsten headless Lauf hinweist.
+
+### 11. Aktion „Validieren“ und technische Tests
+
+- **Aktion „Validieren“** bezeichnet in V2.0 die explizite M12-Bedienhandlung über den gleichnamigen Button.
+- Diese Aktion nutzt denselben Kernregelrahmen wie die automatische Validierung, darf aber zusätzliche **lokale** Prüfpunkte zusammenführen und schreibt nichts auf die Platte.
+
+V2.0 enthält mindestens diese Aktionen:
+
+- **Neu**
+- **Öffnen**
+- **Speichern**
+- **Speichern unter**
+- **Validieren**
+- **Technische Tests ausführen**
+- **Modelle neu laden**
+
+Für **Aktion „Validieren“** und **„Technische Tests ausführen“** gilt:
+
+- sie arbeiten auf dem **aktuellen GUI-Zustand**
+- also auch auf **ungespeicherten Änderungen**
+- die Datei wird dabei **nicht implizit gespeichert**
+- ein Hinweis auf ungespeicherte Prüfgrundlage ist zweckmäßig
+
+### 12. Umfang der technischen Tests in V2.0
+
+Die technischen Tests werden in V2.0 **nur als Gesamttest** angeboten.
+
+- kein Einzeltasten-Test pro Prüfpunkts
+- kein Abbruch beim ersten Fehler
+- alle Prüfpunkte werden vollständig durchlaufen
+- alle Befunde werden gesammelt ausgegeben
+
+Zu prüfen sind mindestens:
+
+- Properties-Datei validieren
+- Provider-Konfiguration prüfen
+- Base-URL/Endpoint erreichbar
+- API-Key vorhanden, auch wenn der effektive Wert ausschließlich über eine passende Umgebungsvariable bereitgestellt wird
+- API-Key technisch akzeptiert
+- Modellliste abrufbar
+- gewähltes Modell plausibel
+- Prompt-Datei vorhanden/lesbar
+- Quellordner vorhanden/lesbar
+- Zielordner vorhanden oder anlegbar/schreibbar
+- SQLite-Datei bzw. Pfad nutzbar
+
+### 13. Korrigierende technische Tests
+
+V2.0 erlaubt bei technischen Tests auch **korrigierende Maßnahmen**, soweit diese sicher und lokal sinnvoll sind.
+
+Beispiele:
+
+- Zielordner anlegen
+- SQLite-Datei anlegen
+- Prompt-Datei anlegen
+- technische Kleinkorrekturen übernehmen
+
+Dabei gilt:
+
+- Es erfolgt **kein stilles Schreiben im Hintergrund**.
+- Vor schreibenden Korrekturen erscheint **ein gesammelter Bestätigungsdialog**:
+  - „Folgende Korrekturen werden durchgeführt … Fortfahren?“
+
+Nicht automatisch korrigierbar bleiben insbesondere:
+
+- falscher API-Key
+- unerreichbare Base-URL
+- nicht verfügbare Modellliste
+- sonstige externe technische Fehler
+
+### 14. Prompt-Datei in V2.0
+
+- Wenn die konfigurierte Prompt-Datei fehlt, darf V2.0 automatisch eine **sinnvolle Standard-Prompt-Datei** erzeugen.
+- Diese Standard-Prompt-Datei ist **deutschsprachig**.
+- Standardmäßig liegt sie **im selben Ordner wie die `.properties`-Datei**.
+
+---
+
+## Explizit nicht Bestandteil von V2.0
+
+Die folgenden Themen wurden bewusst angesprochen, aber aus V2.0 ausdrücklich ausgegrenzt:
+
+- manueller Verarbeitungslauf aus der GUI
+- Start eines echten Batch-Laufs per GUI
+- Visualisierung der SQLite-Datenbank in der GUI
+- Anzeige der Historie in einem eigenen GUI-Tab
+- Kosten-Tracking
+- exakte Token-Schätzung
+- echte Kostenprognose
+- echter Mini-KI-Testaufruf mit fachlicher Antwortauswertung
+- EXE-Datei
+- Installer
+- zusätzliche Provider über Claude und OpenAI-kompatibel hinaus
+- automatischer Fallback zwischen Providern
+- mehrere benannte Profile pro Provider
+- plattformübergreifender offizieller GUI-Support
+- neues Konfigurationsformat
+- Änderung der fachlichen Kernverarbeitung des PDF-Umbenenners
+- Änderung der bestehenden Status-, Retry- oder Persistenz-Wahrheit
+- neuer Parameter zur gesonderten Steuerung der für die KI berücksichtigten Seiten
+
+---
+
+# Neue Meilensteine für V2.0
+
+## Grundsätze für alle V2.0-Meilensteine
+
+- Jeder Meilenstein liefert einen **in sich geschlossenen, buildbaren Entwicklungsstand**.
+- Jeder Meilenstein bleibt **architekturtreu**.
+- Die Erweiterung darf den bestehenden **headless Betrieb** nicht still brechen.
+- GUI und headless greifen auf **dieselbe `.properties`-Konfigurationswelt** zu.
+- V2.0 führt **keine neue Persistenz-Wahrheit** und **keine neue Fachlogik** für die PDF-Benennung ein.
+- Der Fokus liegt auf **Benutzerkomfort, Konfigurationssicherheit und Diagnosefähigkeit**.
+
+---
+
+## M9 – GUI-Grundgerüst, neues Betriebsmodell und Packaging-Basis
+
+### Ziel
+
+Die Anwendung erhält das technische Grundgerüst für eine JavaFX-GUI, ohne den bestehenden headless Batch-Betrieb zu verlieren.
+
+### Inhalt
+
+- neues Modul `pdf-umbenenner-adapter-in-gui` einführen
+- Startumschaltung zwischen GUI-Standardstart und `--headless` umsetzen
+- neue CLI-Option `--config <pfad>` für GUI und headless einführen
+- bestehendes headless Default-Verhalten ohne `--config` erhalten
+- Bootstrap so erweitern, dass GUI und headless sauber verdrahtet werden
+- JavaFX in das ausführbare JAR integrieren
+- sicherstellen, dass GUI-Code den headless Pfad nicht unnötig früh initialisiert
+- Windows als offizielles GUI-Zielsystem festlegen
+
+### Lauffähiger Stand
+
+- ein gemeinsames ausführbares JAR kann GUI oder headless starten
+- `--headless` bleibt abwärtskompatibel nutzbar
+- `--config` ist für beide Startarten funktionsfähig
+- GUI-Start schlägt bei fehlender GUI-Voraussetzung kontrolliert mit klarer Fehlermeldung fehl
+
+### Tests
+
+- Starttests für GUI-Standardstart
+- Starttests für `--headless`
+- Starttests für `--config`
+- Negativtests für ungültige oder fehlende Konfigurationspfade
+- Smoke-Tests für Packaging und Artefakterzeugung
+
+---
+
+## M10 – GUI-Konfigurationseditor, Dateihandling und Benutzerführung
+
+### Ziel
+
+Die GUI kann bestehende `.properties`-Dateien komfortabel öffnen, neue anlegen, bearbeiten und speichern.
+
+### Inhalt
+
+- Header mit aktuell genutztem Konfigurationspfad implementieren
+- Aktionen **Neu**, **Öffnen**, **Speichern**, **Speichern unter** einführen
+- Startzustand ohne geladene Konfiguration mit Willkommenstext umsetzen
+- vollständige Standardvorlage mit sinnvollen Defaults für neue Konfigurationen bereitstellen
+- alle aktuell bekannten Konfigurationswerte in der GUI abbilden
+- Texteingabefelder plus Datei-/Ordnerdialoge für relevante Pfade umsetzen
+- ungespeicherte Änderungen in Fenstertitel und Header markieren
+- Dialoglogik für Speichern/Verwerfen/Abbrechen bei offenen Änderungen einführen
+- Speicherlogik mit Normalisierung der `.properties` umsetzen
+
+### Lauffähiger Stand
+
+- neue und bestehende Konfigurationen können komfortabel bearbeitet werden
+- neue Konfigurationen können unter `config/application.properties` relativ zum Arbeitsverzeichnis vorgeschlagen gespeichert werden
+- bestehende Konfigurationen können sicher geöffnet und überschrieben werden
+- die GUI arbeitet vollständig auf der bestehenden `.properties`-Wahrheit
+
+### Tests
+
+- Tests für Öffnen/Speichern/Speichern unter
+- Tests für neue Konfiguration mit Standardwerten
+- Tests für Dialogverhalten bei ungespeicherten Änderungen
+- Tests für Normalisierung und korrekten Schreibstand der `.properties`
+
+---
+
+## M11 – Provider-Bedienung, Modellabruf und automatische Validierung
+
+### Ziel
+
+Die GUI bildet die bestehende Mehrprovider-Konfiguration komfortabel ab und validiert den Editorstand sofort und benutzerfreundlich.
+
+### Inhalt
+
+- Provider-ComboBox für Claude und OpenAI-kompatibel umsetzen
+- nur den aktuell gewählten Provider-Bereich sichtbar machen
+- Providerwechsel ohne Datenverlust des jeweils anderen Provider-Blocks umsetzen
+- automatischen Modellabruf bei Providerwechsel einführen
+- explizite Aktion **„Modelle neu laden“** an denselben Modellabruf anbinden
+- Umschaltung zwischen Modell-ComboBox und manuellem Modell-Textfeld umsetzen
+- automatische Validierung beim Öffnen und während der Bearbeitung einführen
+- zentralen Meldungsbereich mit vier Stufen implementieren
+- feldnahe rote Fehlermeldungen unter problematischen Eingabefeldern ergänzen
+- wirtschaftliche Warnlogik für `max.text.characters` ergänzen
+- `max.pages` als Plausibilitäts-/Performance-Hinweis behandeln
+
+### Lauffähiger Stand
+
+- Provider können komfortabel gewählt werden
+- Modelllisten können automatisch geladen und dargestellt werden
+- die GUI erkennt Fehler, Warnungen und Hinweise unmittelbar
+- unvollständige oder riskante Konfigurationen werden benutzerfreundlich sichtbar gemacht
+
+### Tests
+
+- Tests für Providerwechsel und Provider-spezifische Felder
+- Tests für Modellabruf mit Liste und ohne Liste
+- Tests für automatische Validierung beim Öffnen
+- Tests für Meldungsstufen, Warnschwellen und feldnahe Fehleranzeige
+
+---
+
+## M12 – Technische Tests, Korrekturhilfen und Windows-/Netzlaufwerksfähigkeit
+
+### Ziel
+
+Die GUI kann den aktuellen Editorstand technisch prüfen, alle Befunde gesammelt anzeigen und sinnvolle technische Korrekturen nach Benutzerbestätigung durchführen.
+
+### Inhalt
+
+- Aktion **Validieren** umsetzen
+- Aktion **Technische Tests ausführen** als Gesamttest umsetzen
+- alle definierten Prüfpunkte vollständig und gesammelt ausführen
+- Prüfungen gegen den aktuellen GUI-Zustand ohne implizites Speichern ausführen
+- korrigierende technische Maßnahmen mit gesammeltem Bestätigungsdialog einführen
+- automatische Standard-Prompt-Erzeugung bei fehlender Prompt-Datei einführen
+- Netzlaufwerke über gemappte Laufwerksbuchstaben ausdrücklich unterstützen
+- Pfadprüfungen für Quellordner, Zielordner, SQLite-Datei und Prompt-Datei vervollständigen
+
+### Lauffähiger Stand
+
+- technische Gesamtprüfung liefert vollständige, verständliche Diagnose
+- lokale Korrekturen können kontrolliert durchgeführt werden
+- gemappte Laufwerke wie `S:\` werden im Windows-Kontext korrekt akzeptiert
+- fehlende Prompt-Datei kann automatisch sinnvoll erzeugt werden
+
+### Tests
+
+- Tests für Gesamttest ohne Frühabbruch
+- Tests für Korrektur-Bestätigungsdialog
+- Tests für technische Korrekturen (Ordner/Datei/Prompt)
+- Tests für gemappte Laufwerke und Windows-Pfadannahmen
+- Tests für Validierung und Tests mit ungespeicherten Änderungen
+
+---
+
+## M13 – V2.0-Abschluss, Dokumentation und Qualitätsnachweis
+
+### Ziel
+
+Der V2.0-Ausbau wird dokumentiert, stabilisiert und als freigabefähiger Gesamtstand abgesichert.
+
+### Inhalt
+
+- technische und betriebliche Dokumentation auf GUI + headless erweitern
+- neue Startoptionen (`--headless`, `--config`) dokumentieren
+- Verhalten bei fehlender Konfiguration, ungültigen Pfaden und GUI-Fehlern dokumentieren
+- Build- und Packaging-Dokumentation für das gemeinsame JAR ergänzen
+- Regressionstests für headless Abwärtskompatibilität ergänzen
+- GUI-nahe Tests für zentrale Bedienpfade und Fehlersituationen ergänzen
+- Qualitäts- und Freigabenachweis für den V2.0-Gesamtstand erstellen
+
+### Lauffähiger Stand
+
+- GUI und headless sind gemeinsam dokumentiert und belastbar testbar
+- bestehender Serverbetrieb bleibt kompatibel
+- der V2.0-Stand ist freigabefähig und nachvollziehbar beschrieben
+
+### Tests
+
+- Reactor-Build des Gesamtprojekts
+- GUI-/Headless-Smoke-Tests
+- Regressionstests für bisherigen Batch-Betrieb
+- Dokumentations- und Konfigurationsbeispielprüfung
+
+---
+
+# Ausbaustufen und Ausblick jenseits von V2.0
+
+## V2.1 – erster funktionaler Ausbau der GUI
+
+Naheliegende Themen für V2.1:
+
+- manueller Verarbeitungslauf aus der GUI
+- Start eines echten Batch-Laufs aus der GUI
+- ggf. erste laufbezogene Statusanzeige während der Ausführung
+- erster separater Zusatz-Tab für weitergehende GUI-Funktionalität
+
+## V2.x – Komfort- und Transparenzausbau
+
+Naheliegende Themen für spätere V2.x-Stufen:
+
+- Visualisierung der SQLite-Datenbank in einem separaten Tab
+- Anzeige von Historie und Verarbeitungsergebnissen
+- Kosten-Tracking
+- spätere, bewusst getrennte Erweiterung technischer Testfunktionen
+- ggf. echter Mini-KI-Testaufruf
+- ggf. feinere technische Steuerung der an die KI gegebenen Eingabemenge
+
+## V3 – größerer Funktionsausbau
+
+Naheliegende Themen für V3:
+
+- weitere Provider über Claude und OpenAI-kompatibel hinaus
+- mehrere Profile pro Provider
+- automatischer Fallback zwischen Providern
+- größere Packaging-/Distributionsausbauten wie EXE oder Installer
+- optional späterer plattformübergreifender offizieller GUI-Support
+
+---
+
+## Kompakte Entscheidungsliste für V2.0
+
+Zur schnellen Einordnung gilt für V2.0:
+
+- GUI ist **Standardstart**
+- `--headless` bleibt erhalten
+- `--config <pfad>` gilt für GUI und headless
+- ein gemeinsames **ausführbares JAR**
+- **JavaFX integriert**
+- **kein Installer**, **keine EXE**
+- neues Modul **`pdf-umbenenner-adapter-in-gui`**
+- `.properties` bleibt die **einzige Konfigurationswahrheit**
+- GUI dient in V2.0 **nur** Konfiguration, Validierung und technischen Tests
+- **kein** manueller Lauf in V2.0
+- **kein** DB-/Historien-Tab in V2.0
+- **kein** Kosten-Tracking in V2.0
+- **Windows** ist offizielles GUI-Zielsystem
+- **gemappte Laufwerke** sind zwingend zu unterstützen
+- Provider bleiben in V2.0 auf **Claude** und **OpenAI-kompatibel** begrenzt
+- exakt **ein aktiver Provider** bleibt erhalten
+
+---
+
+## Ergebnis
+
+Mit diesem Zuschnitt bleibt V2.0:
+
+- **deutlich nützlicher** für den Benutzer,
+- **architekturtreu** zum bestehenden System,
+- **abwärtskompatibel** für den headless Serverbetrieb,
+- und gleichzeitig **bewusst begrenzt**, damit spätere GUI-Ausbaustufen nicht schon in V2.0 vorweggenommen werden.
@@ -1,5 +1,11 @@
 # Technik und Architektur – PDF-Umbenenner mit KI

+> **Versionshinweis v2**
+> Diese Fassung erweitert die KI-Anbindung um einen zweiten, gleichwertig unterstützten Provider.
+> Geändert wurden ausschließlich die Abschnitte, die für die Mehrprovider-Fähigkeit erforderlich sind:
+> Technologiestack (Abschnitt 5), KI-Integration (Abschnitt 11), Konfiguration (Abschnitt 14) sowie die Abschlussbewertung (Abschnitt 19).
+> Alle übrigen Abschnitte bleiben inhaltlich unverändert.
+
 ## 1. Ziel und Geltungsbereich

 Dieses Dokument beschreibt die verbindliche technische Zielarchitektur für den **PDF-Umbenenner**.
@@ -49,8 +55,8 @@ YYYY-MM-DD - Titel(2).pdf
 ```

 Dabei gilt:
- die **20 Zeichen** beziehen sich nur auf den **Basistitel**
- das Dubletten-Suffix zählt **nicht** zu diesen 20 Zeichen
+- die **konfigurierte maximale Titellänge** bezieht sich nur auf den **Basistitel**
+- das Dubletten-Suffix zählt **nicht** zur konfigurierten Titellänge
 - die Quelldatei wird **nie** überschrieben oder verändert

 ---
@@ -127,10 +133,10 @@ Beispiel:

 #### Adapter Out
 Enthält technische Implementierungen der Outbound-Ports, insbesondere:
- Dateisystem
- PDFBox
+- Dateisystem (inkl. `FilesystemTargetFileRenameAdapter` für atomare Zieldatei-Umbenennung)
+- PDFBox (Textauslese sowie direktes Seitenrendering für die GUI-Vorschau via `PDFRenderer.renderImageWithDPI`)
 - SQLite
- OpenAI-kompatibler HTTP-Client
+- KI-HTTP-Clients (eine Implementierung je unterstütztem Provider, siehe Abschnitt 11)
 - Properties-/Umgebungs-Konfiguration
 - Run-Lock
 - Clock
@@ -139,7 +145,8 @@ Enthält technische Implementierungen der Outbound-Ports, insbesondere:
 Verantwortlich für:
 - Laden und Validieren der Konfiguration
 - Erzeugen des Objektgraphen
- Verdrahtung aller Adapter und Ports
+- Auswahl und Verdrahtung der **einen** aktiven KI-Provider-Implementierung
+- Verdrahtung aller übrigen Adapter und Ports
 - Start des CLI-Adapters
 - Setzen des Exit-Codes

@@ -162,13 +169,18 @@ Verbindlich eingesetzt werden:
 - **SQLite** als lokaler Persistenzspeicher
 - **SQLite JDBC-Treiber**
 - **Log4j2** für Logging
- **OpenAI-kompatible HTTP-API** für KI-Zugriff
 - **Java HTTP Client** oder technisch gleichwertige Standard-HTTP-Komponente
 - **JSON-Bibliothek** für robuste JSON-Serialisierung und -Validierung

+Für die KI-Anbindung werden **zwei gleichwertig unterstützte Provider-Familien** technisch zugelassen:
+- **OpenAI-kompatible HTTP-Schnittstelle** (Chat-Completions-Stil)
+- **native Anthropic Messages API** für Claude-Modelle
+
+Pro Lauf ist genau **eine** dieser Provider-Implementierungen aktiv. Die Auswahl erfolgt ausschließlich über Konfiguration (siehe Abschnitt 14).
+
 Nicht verbindlich festgelegt sind:
- konkreter KI-Provider
- konkrete KI-Basis-URL
+- konkreter KI-Provider innerhalb einer Provider-Familie
+- konkrete Basis-URL
 - konkreter Modellname

 Diese drei Punkte sind **reine Konfiguration** und ausdrücklich **keine Architekturentscheidung**.
@@ -192,10 +204,19 @@ Verbindlich zweckmäßige Outbound-Ports:
 - `FingerprintPort`
 - `ProcessedDocumentRepository`
 - `AiNamingPort`
+- `TargetFileRenamePort`
 - `ConfigurationPort`
 - `RunLockPort`
 - `ClockPort`

+Der `AiNamingPort` bleibt **provider-neutral**. Er kennt weder OpenAI- noch Anthropic-spezifische Typen, Header, URLs oder Antwortformate. Provider-spezifische Details (Endpunkt, Authentifizierung, Request-/Response-Format) leben ausschließlich in den jeweiligen Adapter-Out-Implementierungen.
+
+Der `TargetFileRenamePort` kapselt die atomare Umbenennung einer bereits kopierten Zieldatei.
+Er wird vom Use Case `ManualFileRenameUseCase` genutzt und ist durch
+`FilesystemTargetFileRenameAdapter` implementiert. Der Port-Vertrag enthält keine
+`Path`- oder NIO-Typen in öffentlichen Signaturen; er arbeitet ausschließlich mit
+Domain-Typen und String-basierten Dateinamen.
+
 ### 6.3 Logging
 Logging ist **kein fachlicher Port**. Logging ist technische Infrastruktur.

@@ -234,6 +255,8 @@ Die Verarbeitung einer einzelnen Datei erfolgt in dieser Reihenfolge:
 16. temporäre Zieldatei final verschieben/umbenennen
 17. Erfolg und Versuchshistorie persistent speichern

+Die Verarbeitungsschritte sind **provider-unabhängig**. Welcher konkrete KI-Adapter Schritt 9 ausführt, ist außerhalb der Application nicht sichtbar.
+
 ### 7.3 Erfolgskriterium
 Ein Dokument gilt genau dann als erfolgreich verarbeitet, wenn:
 1. brauchbarer PDF-Text vorliegt,
@@ -274,7 +297,7 @@ Der Titel muss technisch diese Regeln erfüllen:
 - Deutsch
 - verständlich
 - eindeutig genug für den Dokumentkontext
- maximal **20 Zeichen** als Basistitel
+- maximal die **konfigurierte Titellänge** als Basistitel (Default 60, gültiger Bereich 10..120)
 - keine unzulässigen Windows-Dateinamenzeichen
 - keine generischen Platzhalter wie z. B. `Dokument`, `Datei`, `Scan`, `PDF`
 - Eigennamen bleiben unverändert
@@ -288,63 +311,15 @@ Beispiele:
 - `2026-03-31 - Stromabrechnung(1).pdf`
 - `2026-03-31 - Stromabrechnung(2).pdf`

-### 8.6 Windows-Kompatibilität
-Die Anwendung stellt zusätzlich sicher, dass der Zielname für Windows zulässig ist.
+---

-Unzulässige Zeichen sind technisch zu entfernen oder kontrolliert zu ersetzen.
+## 9. Retry- und Fehlersemantik
+
+> Inhaltlich unverändert gegenüber der Vorgängerfassung. Nur die Erkenntnis, dass technische KI-Fehler unabhängig vom konkreten Provider als transient klassifiziert werden, gilt jetzt für **beide** Provider-Familien gleichermaßen.

 ---

-## 9. Fehlerklassifikation und Retry-Regeln
-
-### 9.1 Grundsatz
-Nur **retryable** Fehler dürfen in späteren Läufen erneut verarbeitet werden.
-
-**Finale** Fehler werden in späteren Läufen übersprungen.
-
-### 9.2 Deterministische Inhaltsfehler
-Deterministische Inhaltsfehler sind insbesondere:
- kein brauchbarer PDF-Text
- Seitenlimit überschritten
- Dokument inhaltlich mehrdeutig
- kein brauchbarer Titel
- generischer oder unzulässiger Titel
- von der KI gelieferter Datumswert ist vorhanden, aber unbrauchbar oder nicht interpretierbar
-
-Regel:
- genau **1 Retry** in einem späteren Scheduler-Lauf
- danach **finaler Fehler**
-
-### 9.3 Transiente technische Fehler
-Transiente technische Fehler sind insbesondere:
- KI nicht erreichbar
- HTTP-Timeout
- temporäre IO-Fehler
- temporäre SQLite-Sperre
- ungültiges oder nicht parsebares KI-JSON
- sonstige vorübergehende technische Infrastrukturfehler
-
-Regel:
- Retry in späteren Läufen bis zum konfigurierten Maximalwert
-
-### 9.4 Technischer Sofort-Wiederholversuch
-Zusätzlich zulässig ist genau **ein technischer Sofort-Wiederholversuch** innerhalb desselben Laufs für den Zielkopiervorgang, wenn das Schreiben der Zieldatei fehlschlägt.
-
-Dieser Mechanismus ist **kein fachlicher Retry** und wird getrennt vom laufübergreifenden Retry-Modell behandelt.
-
-### 9.5 Statusmodell
-Verbindlich zweckmäßige Statuswerte:
- `SUCCESS`
- `FAILED_RETRYABLE`
- `FAILED_FINAL`
- `SKIPPED_ALREADY_PROCESSED`
- `SKIPPED_FINAL_FAILURE`
-
-Ein technischer Zwischenstatus `PROCESSING` ist zusätzlich zulässig und sinnvoll.
-
---
-
-## 10. Idempotenz und Identifikation
+## 10. Identifikation und Reproduzierbarkeit

 ### 10.1 Identifikation
 Die Identifikation eines Dokuments erfolgt **nicht** über den Dateinamen.
@@ -362,35 +337,63 @@ Daraus folgt:
 Reproduzierbarkeit bedeutet technisch:
 - nach einem erfolgreichen Lauf bleibt das gespeicherte Ergebnis stabil
 - erfolgreiche Dateien werden nicht erneut KI-basiert bewertet
- KI-Aufrufe werden, soweit die API es zulässt, mit möglichst geringer Varianz konfiguriert
- Prompt-Version und Modellname werden persistiert
+- KI-Aufrufe werden, soweit die jeweilige API es zulässt, mit möglichst geringer Varianz konfiguriert
+- Prompt-Version, Modellname **und der Name des aktiven Providers** werden persistiert

 ---

 ## 11. KI-Integration

-### 11.1 Schnittstelle
-Die KI wird ausschließlich über eine **OpenAI-kompatible HTTP-Schnittstelle** angebunden.
+### 11.1 Unterstützte Provider-Familien
+Die KI wird über genau **eine** der folgenden Provider-Familien angebunden:

-Basis-URL, Modellname und API-Key sind reine Konfiguration.
+1. **OpenAI-kompatible HTTP-Schnittstelle**
+   Chat-Completions-Stil. Geeignet für OpenAI selbst und für jeden API-kompatiblen Drittanbieter.
+2. **Native Anthropic Messages API**
+   Die offizielle Anthropic-Schnittstelle zur Nutzung von Claude-Modellen.

-### 11.2 Prompt
+Pro Lauf ist genau **ein** Provider aktiv. Es gibt:
+- **keine** automatische Fallback-Umschaltung
+- **keine** parallele Nutzung mehrerer Provider in einem Lauf
+- **keine** Profilverwaltung mit mehreren Konfigurationen je Provider-Familie
+
+Die Auswahl erfolgt ausschließlich über Konfiguration. Ein Fehler des aktiven Providers ist und bleibt ein Fehler dieses einen Pfads und folgt der bestehenden Retry- und Fehlersemantik.
+
+### 11.2 Architekturelle Einbettung
+- Pro Provider-Familie existiert **genau eine** Implementierung des `AiNamingPort` im Modul `pdf-umbenenner-adapter-out`.
+- Provider-spezifische Endpunkte, Header, Authentifizierungsverfahren, Request- und Response-Strukturen leben ausschließlich in der jeweiligen Adapter-Implementierung.
+- Application und Domain bleiben provider-neutral. Sie kennen weder den Begriff „OpenAI" noch „Claude".
+- Das **Bootstrap-Modul** wählt anhand der Konfiguration die eine aktive Implementierung aus und verdrahtet sie als `AiNamingPort`.
+- Adapter dürfen nicht voneinander abhängen. Es gibt keinen gemeinsamen „abstrakten KI-Adapter" als Infrastrukturschicht zwischen Port und konkreten Adaptern.
+
+### 11.3 Einheitlicher fachlicher Vertrag
+Unabhängig vom aktiven Provider gilt derselbe fachliche Vertrag:
+- gleicher fachlicher Input (Prompt, Textausschnitt, Modellbezug)
+- gleicher fachlicher Output (Domain-Typ `NamingProposal`)
+- gleiche Validierungs- und Folgeprozesse in der Application
+- keine provider-spezifische Verzweigung im fachlichen Kern
+
+Jede provider-spezifische Antwort wird im Adapter auf denselben Domain-Typ abgebildet. Eine Sonderbehandlung im Use-Case oder in der Domain ist unzulässig.
+
+### 11.4 Prompt
 Der Prompt wird **nicht** im Code fest verdrahtet.

 Verbindlich:
 - externe Prompt-Datei
 - Prompt-Version oder Prompt-Dateiname wird mitpersistiert
 - der Prompt darf die KI zur Ausgabe eines deutschen Titels anweisen
+- derselbe Prompt wird providerübergreifend verwendet; provider-spezifische Anpassungen finden ausschließlich in der Adapter-Implementierung statt

-### 11.3 Textmenge
+### 11.5 Textmenge
 Es wird nicht zwingend der komplette extrahierte PDF-Text an die KI gesendet.

 Verbindlich:
 - die maximale Zeichenzahl ist konfigurierbar
 - die Begrenzung muss vor dem KI-Aufruf technisch angewendet werden
+- die Begrenzung gilt providerunabhängig

-### 11.4 Antwortformat
-Die KI muss genau ein parsebares JSON-Objekt liefern.
+### 11.6 Antwortformat
+Die KI muss – unabhängig vom aktiven Provider – fachlich genau ein parsebares JSON-Objekt liefern.

 Zweckmäßiges Schema:

@@ -408,7 +411,9 @@ Regeln:
 - `date` ist optional, wenn kein belastbares Datum ableitbar ist
 - liefert die KI kein `date`, setzt die Anwendung das aktuelle Datum als Fallback

-### 11.5 Antwortvalidierung
+Wie der Adapter dieses Schema aus der jeweiligen Provider-Antwort extrahiert (z. B. aus `choices[].message.content` bei OpenAI-kompatiblen Schnittstellen oder aus dem Content-Block-Array der Anthropic Messages API), ist eine reine Adapter-Implementierungsfrage.
+
+### 11.7 Antwortvalidierung
 Die Antwort gilt nur dann als technisch brauchbar, wenn:
 - JSON parsebar ist
 - `title` vorhanden ist
@@ -418,6 +423,11 @@ Zusätzlich gilt fachlich:
 - `title` muss validierbar und brauchbar sein
 - ein vorhandenes `date` muss im Format `YYYY-MM-DD` interpretierbar sein

+Diese Validierung ist provider-unabhängig und liegt in Application/Domain.
+
+### 11.8 Fehlerklassifikation
+Technische Fehler des aktiven Providers (HTTP-Fehler, Timeouts, ungültige Antwortstrukturen, Authentifizierungsfehler) werden im Adapter erkannt und auf die bestehende technische Fehlersemantik des Projekts abgebildet (transient vs. deterministisch). Es entsteht keine neue Fehlerkategorie. Der inaktive Provider wird in keiner Fehlersituation als Backup verwendet.
+
 ---

 ## 12. PDF-Verarbeitung
@@ -457,6 +467,8 @@ Die Persistenz wird zweckmäßig in **zwei Ebenen** geführt:
 1. **Dokument-Stammsatz** pro Fingerprint
 2. **Versuchshistorie** mit einem Datensatz pro Verarbeitungsversuch

+Das bestehende Schema bleibt erhalten. Es wird ausschließlich um die Information erweitert, **welcher Provider** den jeweiligen Versuch erzeugt hat (siehe 13.4). Eine neue Wahrheitsquelle entsteht nicht.
+
 ### 13.3 Dokument-Stammsatz
 Mindestens zweckmäßig zu speichern:
 - interne ID
@@ -485,6 +497,7 @@ Für **jeden Versuch separat** zu speichern:
 - Fehlerklasse
 - Fehlermeldung
 - Retryable-Flag
+- **Provider-Identifikator des aktiven KI-Providers für diesen Versuch**
 - Modellname
 - Prompt-Identifikator
 - verarbeitete Seitenzahl
@@ -496,11 +509,16 @@ Für **jeden Versuch separat** zu speichern:
 - finaler Titel
 - finaler Zieldateiname

+Der Provider-Identifikator macht jeden Versuch eindeutig nachvollziehbar einer Provider-Familie zuordenbar, ohne den fachlichen Vertrag zu verändern.
+
 ### 13.5 Sensible Inhalte
 Die vollständige KI-Rohantwort wird in SQLite gespeichert.

 Sie soll **standardmäßig nicht vollständig in Logdateien** geschrieben werden.

+### 13.6 Rückwärtsverträglichkeit
+Bestehende Datenbestände aus dem Stand vor v2 müssen weiterhin lesbar, fortschreibbar und korrekt interpretierbar bleiben. Schema-Erweiterungen erfolgen additiv und mit definierten Defaultwerten für historische Versuche ohne Provider-Identifikator.
+
 ---

 ## 14. Konfiguration
@@ -508,33 +526,78 @@ Sie soll **standardmäßig nicht vollständig in Logdateien** geschrieben werden
 ### 14.1 Format
 Die technische Konfiguration erfolgt über `.properties`.

-### 14.2 Mindestparameter
+### 14.2 Provider-Auswahl
+Genau ein Provider ist aktiv. Die Auswahl erfolgt über einen einzigen Pflichtparameter, der den aktiven Provider benennt. Zulässige Werte sind die Bezeichner der unterstützten Provider-Familien aus Abschnitt 11.1.
+
+### 14.3 Mindestparameter
 Verbindlich zweckmäßige Parameter:
+
 - `source.folder`
 - `target.folder`
 - `sqlite.file`
- `api.baseUrl`
- `api.model`
- `api.timeoutSeconds`
+- **`ai.provider.active`** – Auswahl des aktiven Providers (Pflicht)
 - `max.retries.transient`
 - `max.pages`
 - `max.text.characters`
+- `max.title.length`
 - `prompt.template.file`

+Pro unterstützter Provider-Familie existiert ein eigener Parameter-Namensraum mit zweckmäßig mindestens:
+- Modellname
+- API-Schlüssel
+- Timeout
+- Basis-URL (optional, wo betrieblich sinnvoll)
+
+Konkretes Schema (zweckmäßig, frei wählbare Bezeichner):
+
+```properties
+ai.provider.active=openai-compatible
+
+ai.provider.openai-compatible.baseUrl=...
+ai.provider.openai-compatible.model=...
+ai.provider.openai-compatible.timeoutSeconds=...
+ai.provider.openai-compatible.apiKey=...
+
+ai.provider.claude.baseUrl=...
+ai.provider.claude.model=...
+ai.provider.claude.timeoutSeconds=...
+ai.provider.claude.apiKey=...
+```
+
 Zusätzlich zweckmäßig:
 - `runtime.lock.file`
 - `log.directory`
 - `log.level`
- `api.key`
+- `log.ai.sensitive`

-### 14.3 API-Key
-Der API-Key darf über Umgebungsvariable oder Properties geliefert werden.
+### 14.4 API-Schlüssel
+API-Schlüssel dürfen über Umgebungsvariable oder Properties geliefert werden.

 Verbindlich:
- Umgebungsvariable hat Vorrang
+- pro Provider-Familie existiert eine **eigene definierte Umgebungsvariable**
+- die Umgebungsvariable hat **Vorrang** vor dem Properties-Wert derselben Provider-Familie
+- Schlüssel verschiedener Provider-Familien werden niemals vermischt

-### 14.4 Konfigurationsvalidierung
-Beim Start müssen alle Pflichtparameter validiert werden.
+### 14.5 Migration historischer Konfigurationen
+Bestehende Properties-Dateien aus dem Stand vor v2 (mit flachen Schlüsseln wie `api.baseUrl`, `api.model`, `api.timeoutSeconds`, `api.key`) sind eine eindeutig erkennbare Legacy-Form.
+
+Beim ersten Start mit erkannter Legacy-Form gilt verbindlich:
+1. Legacy-Form erkennen
+2. **`.bak`-Sicherung** der Originaldatei anlegen
+3. Inhalt in das neue Schema überführen
+   - die Legacy-Werte werden in den Namensraum der Provider-Familie **`openai-compatible`** überführt
+   - `ai.provider.active` wird auf `openai-compatible` gesetzt
+4. neue Datei schreiben (In-Place-Update)
+5. Datei erneut laden und validieren
+6. erst danach den normalen Lauf fortsetzen
+
+Es ist **kein** Ziel, alte und neue Struktur dauerhaft gleichrangig als Endformat zu pflegen.
+
+### 14.6 Konfigurationsvalidierung
+Beim Start müssen alle Pflichtparameter validiert werden, insbesondere:
+- `ai.provider.active` ist gesetzt und benennt einen unterstützten Provider
+- für den aktiven Provider sind alle Pflichtwerte vorhanden und technisch konsistent
+- für den **inaktiven** Provider werden keine Pflichtwerte erzwungen

 Bei ungültiger Startkonfiguration:
 - beginnt kein Verarbeitungslauf
@@ -553,6 +616,7 @@ Das Logging muss mindestens enthalten:
 - Laufstart
 - Laufende
 - Lauf-ID
+- **aktiver KI-Provider für den Lauf**
 - erkannte Quelldatei
 - Überspringen bereits erfolgreicher Dateien
 - Überspringen final fehlgeschlagener Dateien
@@ -566,6 +630,7 @@ Standardmäßig gilt:
 - vollständige KI-Rohantwort **in SQLite**
 - `reasoning` darf geloggt werden, sofern dies betrieblich gewünscht ist
 - die Ausgabe sensibler Inhalte muss konfigurierbar sein
+- die Sensibilitätsregel gilt provider-unabhängig

 ### 15.4 Speicherort
 Das Log-Verzeichnis ist konfigurierbar. Ohne explizite Konfiguration ist ein lokales `logs/`-Verzeichnis im Programmkontext zweckmäßig.
@@ -598,7 +663,7 @@ Verbindliche Interpretation:
 - `1`: Lauf konnte wegen hartem Start-/Bootstrap-Fehler nicht ordnungsgemäß beginnen oder fortgesetzt werden

 Typische `1`-Fälle:
- ungültige Konfiguration
+- ungültige Konfiguration (einschließlich fehlender oder unbekannter `ai.provider.active`)
 - Run-Lock nicht erwerbbar
 - essentielle Ressourcen beim Start nicht verfügbar

@@ -616,23 +681,30 @@ Nicht Bestandteil dieser Architektur sind:
 - menschlicher Review-Workflow
 - interne Scheduler-Logik
 - fachliche Identifikation über Dateinamen
+- automatische Fallback-Umschaltung zwischen KI-Providern
+- parallele Nutzung mehrerer KI-Provider in einem Lauf
+- mehrere konkurrierende Konfigurationen je Provider-Familie (Profilverwaltung)
+- Provider-Familien jenseits der in Abschnitt 11.1 explizit genannten

 ---

 ## 19. Abschlussbewertung

-Der technische Zielstand ist mit den hier festgelegten Regeln:
+Der technische Zielstand ist mit den in dieser Fassung festgelegten Regeln:
 - konsistent
 - widerspruchsfrei
 - hexagonal sauber geschnitten
 - für einen minimalen produktiven PDF-Umbenenner zweckmäßig
+- offen für genau zwei gleichwertig unterstützte KI-Provider-Familien, ohne den fachlichen Kern zu verändern

-Besonders verbindlich geklärt sind jetzt:
+Besonders verbindlich geklärt sind:
 - Dateinamensformat mit `YYYY-MM-DD - Titel.pdf`
 - Dublettenregel mit `(1)`, `(2)`, ...
 - Trennung zwischen finalen und retrybaren Fehlern
 - Fallback-Datum durch die Anwendung
- Zwei-Ebenen-Persistenz mit Versuchshistorie
+- Zwei-Ebenen-Persistenz mit Versuchshistorie inkl. Provider-Identifikator
 - Exit-Code-Regel für harte Startfehler
- OpenAI-kompatible Schnittstelle ohne fest verdrahteten Provider
+- Unterstützung von OpenAI-kompatibler Schnittstelle **und** nativer Anthropic Messages API
+- genau **ein** aktiver Provider pro Lauf, ohne Fallback
 - Verlagerung technischer Persistenzobjekte aus der Domain heraus
+- Migration historischer flacher Properties-Konfiguration mit `.bak`-Sicherung
@@ -0,0 +1,403 @@
+# M10 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M10 – GUI-Konfigurationseditor, Dateihandling und Benutzerführung**.
+
+Die Meilensteine **M1** bis **M9** sowie der dokumentierte Ist-Stand **V1.1** werden als vollständig umgesetzt und freigegeben vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch GUI-Modul, Bootstrap, Konfigurationszugriff, Build und Tests ändern.
+- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand, die V2.0-Meilensteine oder dieses Dokument gedeckt sind.
+- Kein Vorgriff auf **M11+**.
+- Kein Umbau bestehender M1–M9-Strukturen ohne direkten M10-Bezug.
+- Die GUI arbeitet weiterhin ausschließlich auf der bestehenden **`.properties`-Konfigurationswelt**.
+- Die GUI darf in M10 **Dateien lesen, schreiben und normalisiert speichern**, aber noch **keine** sofortige Validierung, keinen Modellabruf und keine technischen Gesamttests ausführen.
+- Das Ergebnis jedes Arbeitspakets muss für Benutzer bereits nachvollziehbar und bedienbar sein, auch wenn der volle V2.0-Komfort erst in M11/M12 erreicht wird.
+- Neue Typen, View-Modelle, Dateidialoge, Editorzustände und Tests so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind.
+
+## Explizit nicht Bestandteil von M10
+
+- automatische Validierung beim Öffnen oder während der Eingabe
+- zentraler Meldungsbereich mit Info/Hinweis/Warnung/Fehler
+- feldnahe rote Fehlermeldungen unter Eingabefeldern
+- Provider-ComboBox
+- automatischer Modellabruf
+- Umschaltung zwischen Modell-ComboBox und Modell-Textfeld
+- technische Aktion **„Validieren“**
+- technische Aktion **„Technische Tests ausführen“**
+- Aktion **„Modelle neu laden“**
+- wirtschaftliche Warnschwellen für `max.text.characters`
+- Plausibilitäts-/Performance-Hinweise für `max.pages`
+- automatische Prompt-Erzeugung
+- technische Korrekturhilfen mit Bestätigungsdialog
+- SQLite-/Historienanzeige
+- manueller Verarbeitungslauf aus der GUI
+- EXE
+- Installer
+- neues Konfigurationsformat
+- Änderungen an fachlicher Kernverarbeitung, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten
+
+## Verbindliche M10-Regeln für **alle** Arbeitspakete
+
+### 1. Konfigurationswahrheit
+
+Ab M10 gilt verbindlich:
+
+- Die GUI liest, bearbeitet und schreibt dieselbe **`.properties`-Datei** wie der headless Betrieb.
+- Es wird **kein** neues Konfigurationsformat eingeführt.
+- Kommentare, Reihenfolge und Formatierung dürfen beim Speichern **technisch normalisiert** werden.
+- Die GUI bearbeitet **alle aktuell bekannten Konfigurationswerte** des bestehenden Produkts.
+
+### 2. Startzustand der GUI
+
+Ab M10 gilt verbindlich:
+
+- Beim GUI-Start wird **keine Konfiguration automatisch geladen**, sofern nicht eine gültige Konfigurationsdatei explizit über den Startpfad aus M9 übergeben wurde.
+- Ohne geladene Konfiguration zeigt die GUI einen **deutschen Willkommenstext** mit kurzer Anleitung.
+- Der Benutzer kann von dort aus mindestens **„Neu“** und **„Öffnen“** auslösen.
+
+### 3. Neue Konfiguration
+
+Ab M10 gilt verbindlich:
+
+- **„Neu“** erzeugt eine **vollständige Standardvorlage** mit sinnvollen Default-Werten.
+- Diese Vorlage enthält die **bestehende Mehrprovider-Struktur**.
+- Standardmäßig ist der **alphabetisch erste vorhandene Provider** aktiv.
+- Eine neue, noch nie gespeicherte Konfiguration gilt als eigener Editorzustand und darf bearbeitet werden, ohne sofort auf Platte geschrieben zu werden.
+
+### 4. Dateiverhalten
+
+Ab M10 gilt verbindlich:
+
+- **„Öffnen“** und **„Speichern unter“** filtern auf **`*.properties`**.
+- **„Speichern“** verhält sich bei einer neuen, noch nie gespeicherten Konfiguration wie **„Speichern unter“**.
+- **„Speichern unter”** schlägt standardmäßig **`config/application.properties`** relativ zum Arbeitsverzeichnis vor, so ist die Datei ohne weitere Schritte für den nächsten headless Scheduler-Lauf nutzbar.
+- Beim Speichern auf eine bereits existierende Datei erscheint eine klare Rückfrage **„Datei überschreiben?“**.
+
+### 5. Editorzustand und ungespeicherte Änderungen
+
+Ab M10 gilt verbindlich:
+
+- Ungespeicherte Änderungen werden im **Fenstertitel** und im **Header** sichtbar markiert.
+- Vor **Neu**, **Öffnen** oder **Schließen** erscheint bei ungespeicherten Änderungen ein Dialog mit:
+  - **Speichern**
+  - **Verwerfen**
+  - **Abbrechen**
+- In M10 sind diese Entscheidungen rein editorbezogen; sie lösen noch **keine** Validierungs- oder Testlogik aus.
+
+### 6. GUI-Struktur in M10
+
+M10 liefert bereits den echten Konfigurationseditor, aber noch ohne M11/M12-Komfortlogik.
+
+Daraus folgt:
+
+- Es bleibt bei **genau einem Tab**.
+- Die Oberfläche ist in feste, sichtbare Bereiche gegliedert:
+  1. **Header / Konfigurationsdatei**
+  2. **Pfade**
+  3. **Provider**
+  4. **Verarbeitungslimits**
+  5. **Tests**
+  6. **Meldungen**
+- In M10 dürfen Bereiche **„Tests“** und **„Meldungen“** bereits strukturell sichtbar sein, auch wenn ihre echte Funktionalität erst in M11/M12 vervollständigt wird.
+- Die Oberfläche muss scrollbar und benutzbar bleiben; einklappbare Gruppen oder zusätzliche Tabs sind in M10 nicht Ziel.
+
+### 7. Datei- und Ordnerdialoge
+
+Ab M10 gilt verbindlich:
+
+- Für mindestens folgende Pfadangaben stehen ein Texteingabefeld und ein kleiner nativer Datei-/Ordnerdialog-Button bereit:
+  - Quellordner
+  - Zielordner
+  - SQLite-Datei
+  - Prompt-Datei
+- Die GUI darf dabei Windows-typische Pfadangaben nicht künstlich einschränken.
+- Gemappte Laufwerksbuchstaben dürfen nicht durch GUI-Dateilogik beschädigt oder unbrauchbar gemacht werden.
+
+### 8. API-Key-Feld und bestehende Vorrangregel
+
+Ab M10 gilt verbindlich:
+
+- Die GUI bildet den API-Key pro Provider weiterhin innerhalb der bestehenden `.properties`-Konfigurationswelt ab.
+- Die spätere Bewertung des **effektiven** API-Keys muss die bestehende Vorrangregel respektieren:
+  1. providerspezifische Umgebungsvariable,
+  2. bei **OpenAI-kompatibel** zusätzlich die bestehende Legacy-Umgebungsvariable,
+  3. Property-Wert aus der Datei.
+- Der Editorzustand muss deshalb zwischen bearbeitetem Property-Wert und später anzeigbarer Herkunft des effektiven API-Keys anschlussfähig bleiben.
+- Das API-Key-Feld bleibt bewusst ein normales, unmaskiertes Textfeld.
+- Ein leeres API-Key-Feld darf einen bereits vorhandenen Property-Wert nicht stillschweigend entfernen, solange keine ausdrückliche Löschsemantik eingeführt wurde.
+
+---
+
+## AP-001 Editorzustand, Konfigurationsabbild und Standardvorlage einführen
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M10-Startpunkt.
+
+### Ziel
+Der GUI-Editor erhält ein sauberes internes Zustandsmodell für bestehende und neue Konfigurationen, einschließlich vollständiger Standardvorlage und Dirty-State-Grundlage.
+
+### Muss umgesetzt werden
+- GUI-seitiges Editor-/View-Model für die bearbeitbare Konfiguration einführen.
+- Abbildung aller aktuell bekannten Konfigurationswerte in einen GUI-tauglichen Bearbeitungszustand modellieren.
+- Den Bearbeitungszustand so schneiden, dass für den API-Key je Provider sowohl der editierbare Property-Wert als auch die spätere Herkunft des effektiven Werts gemäß bestehender Vorrangregel anschlussfähig bleiben.
+- Saubere Trennung zwischen:
+  - geladener Dateirepräsentation,
+  - bearbeitbarem Editorzustand,
+  - neu erzeugter Standardvorlage,
+  - Dirty-State/Änderungsstand.
+- Vollständige Standardvorlage für **„Neu“** bereitstellen.
+- Sicherstellen, dass die Standardvorlage die bestehende Mehrprovider-Struktur erhält und mit sinnvollen Defaults startet.
+- Mapping so schneiden, dass spätere M11-/M12-Logik darauf aufsetzen kann, ohne ein neues Konfigurationsmodell zu erfinden.
+- JavaDoc und `package-info` für Verantwortlichkeiten und Grenzen ergänzen.
+
+### Explizit nicht Teil
+- JavaFX-Layout
+- Datei öffnen oder speichern
+- Dirty-State-Anzeige im Fenster
+- Dialoge
+- Validierung oder Tests
+
+### Fertig wenn
+- ein konsistenter GUI-Editorzustand modelliert ist,
+- neue Standardkonfigurationen erzeugt werden können,
+- alle aktuell bekannten Konfigurationswerte im Editorzustand abbildbar sind,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Header, leerer Startzustand und Aktionsgrundgerüst der GUI vervollständigen
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die GUI zeigt bei fehlender Konfiguration einen benutzerfreundlichen Startzustand und bietet die zentralen Dateiaktionen in einer stabilen Grundstruktur an.
+
+### Muss umgesetzt werden
+- Header-Bereich mit Anzeige des aktuell verwendeten Konfigurationspfads implementieren.
+- Verhalten ohne geladene Konfiguration umsetzen:
+  - leerer Pfad im Header,
+  - deutscher Willkommenstext,
+  - sichtbare Aktionen für **„Neu“** und **„Öffnen“**.
+- Aktionsgrundgerüst für mindestens diese Bedienhandlungen sichtbar und verdrahtbar anlegen:
+  - **Neu**
+  - **Öffnen**
+  - **Speichern**
+  - **Speichern unter**
+- Sicherstellen, dass die GUI ohne geladene Konfiguration nicht verwirrend einen impliziten Standardentwurf zeigt.
+- Grundstruktur des einen GUI-Tabs mit den festen Bereichen anlegen, soweit für M10 erforderlich.
+- JavaDoc/Kommentare für den GUI-Startzustand ergänzen.
+
+### Explizit nicht Teil
+- tatsächliches Dateiladen
+- tatsächliches Speichern
+- unsaved-changes-Dialoge
+- provider-spezifische Komfortlogik aus M11
+- technische Tests oder Meldungslogik
+
+### Fertig wenn
+- die GUI ohne geladene Konfiguration benutzerfreundlich startet,
+- Header und Grundaktionen sichtbar vorhanden sind,
+- der Benutzer klar zwischen **„Neu“** und **„Öffnen“** geführt wird,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-003 Öffnen bestehender `.properties`-Dateien und Übernahme in den Editorzustand umsetzen
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Bestehende Konfigurationsdateien können über den GUI-Dateidialog geladen und in den Editorzustand übernommen werden.
+
+### Muss umgesetzt werden
+- Native Dateiauswahl für **„Öffnen“** mit Filter auf **`*.properties`** implementieren.
+- Bestehende `.properties`-Datei technisch laden und in den Editorzustand überführen.
+- **Legacy-Migration beim Öffnen**: Wenn die geöffnete Datei in der Vor-V1.1-Legacy-Form (flache `api.*`-Schlüssel) vorliegt, muss die GUI dieselbe Migrationslogik wie der headless Pfad anwenden:
+  1. `.bak`-Sicherung der Originaldatei anlegen (`<dateiname>.bak`, bei Kollision `.bak.1`, `.bak.2`, …),
+  2. Inhalt ins neue Mehrprovider-Schema überführen (Legacy-Werte → `openai-compatible`, `ai.provider.active=openai-compatible`),
+  3. migrierte Datei speichern,
+  4. die durchgeführte Migration im Editorzustand als ausstehende Migrationsmeldung festhalten, sodass der in M11 eingeführte zentrale Meldungsbereich diese Meldung später sichtbar anzeigen kann.
+- In M10 selbst erscheint noch kein sichtbarer Migrationshinweis; dieser wird erst in M11 durch den zentralen Meldungsbereich angezeigt.
+- Sicherstellen, dass die Dateiübernahme mit dem aus M9 bereits vorhandenen GUI-Start über gültiges `--config <pfad>` zusammenarbeiten kann.
+- Header-Anzeige nach erfolgreichem Laden auf den vollständigen Pfad aktualisieren.
+- Fehlersituationen beim Laden kontrolliert behandeln, soweit für M10 nötig.
+- Noch nicht implementierte Validierungs- oder Testlogik aus M11/M12 nicht vorwegnehmen.
+- JavaDoc für Dateiladeverantwortung und Editorübernahme ergänzen.
+
+### Explizit nicht Teil
+- Speichern oder Speichern unter
+- Dirty-State-Dialoge
+- sofortige Validierung
+- Modellabruf
+- technische Tests
+
+### Fertig wenn
+- bestehende `.properties`-Dateien per GUI geöffnet werden können,
+- ihr Inhalt im Editorzustand sichtbar und bearbeitbar ist,
+- die Header-Anzeige den geladenen Pfad korrekt darstellt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 Speichern, Speichern unter und normalisierte `.properties`-Schreiblogik implementieren
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Der Editor kann neue und bestehende Konfigurationen zuverlässig, normalisiert und benutzerfreundlich als `.properties` schreiben.
+
+### Muss umgesetzt werden
+- Schreiblogik für bestehende und neue Konfigurationen implementieren.
+- **„Speichern“** für bereits bekannte Dateipfade umsetzen.
+- **„Speichern“** für neue, noch nie gespeicherte Konfigurationen wie **„Speichern unter“** behandeln.
+- **„Speichern unter”** mit Vorschlag **`config/application.properties`** relativ zum Arbeitsverzeichnis implementieren.
+- Dialogfilter auf **`*.properties`** anwenden.
+- Rückfrage **„Datei überschreiben?”** bei existierender Zieldatei umsetzen.
+- Vor dem Überschreiben einer bestehenden `.properties`-Datei eine **`.bak`-Sicherung** im selben Schema wie der V1.1-Migrationspfad anlegen (`<dateiname>.bak`, bei Kollision `.bak.1`, `.bak.2`, …). Bestehende Sicherungen werden nicht überschrieben.
+- Speicherung als normalisierte `.properties` sicherstellen.
+- Für API-Key-Felder sicherstellen, dass ein leeres GUI-Feld einen bereits vorhandenen Property-Wert nicht stillschweigend entfernt; stattdessen muss ein kontrolliertes Ergebnis für die spätere Warnanzeige aus M11/M12 bereitstehen.
+- Header-Pfad nach erfolgreichem Erstspeichern bzw. Speichern unter korrekt fortschreiben.
+- JavaDoc für Dateischreibverhalten, API-Key-Erhaltung und Normalisierung ergänzen.
+
+### Explizit nicht Teil
+- Dirty-State-Anzeige im Fenstertitel
+- Dialogverhalten bei ungespeicherten Änderungen vor Neu/Öffnen/Schließen
+- Validierung oder technische Tests
+- automatische Prompt-Erzeugung
+
+### Fertig wenn
+- neue und bestehende Konfigurationen zuverlässig gespeichert werden können,
+- Speichern/Speichern unter benutzerfreundlich und nachvollziehbar arbeiten,
+- normalisierte `.properties`-Dateien geschrieben werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 Dirty-State, optische Kennzeichnung und Schutzdialoge bei ungespeicherten Änderungen umsetzen
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Ungespeicherte Änderungen werden sichtbar gemacht und vor verlustbehafteten Bedienhandlungen kontrolliert abgefragt.
+
+### Muss umgesetzt werden
+- Dirty-State aus dem Editorzustand in die GUI übertragen.
+- Optische Kennzeichnung ungespeicherter Änderungen an **beiden** Stellen umsetzen:
+  - Fenstertitel
+  - Header neben dem Konfigurationspfad
+- Schutzdialog vor **Neu**, **Öffnen** und **Schließen** bei ungespeicherten Änderungen implementieren.
+- Dialogoptionen exakt wie definiert bereitstellen:
+  - **Speichern**
+  - **Verwerfen**
+  - **Abbrechen**
+- Sicherstellen, dass der Dialogfluss mit neuer Konfiguration, bestehender Konfiguration und erstmaligem Speichern konsistent zusammenwirkt.
+- Noch keine M11/M12-Validierungs- oder Testlogik mit diesem Dialog vermischen.
+- JavaDoc für Dirty-State- und Schutzdialog-Verhalten ergänzen.
+
+### Explizit nicht Teil
+- sofortige Validierung
+- technischer Gesamttest
+- Meldungsbereichslogik
+- provider-spezifische Komfortlogik
+
+### Fertig wenn
+- ungespeicherte Änderungen sichtbar markiert werden,
+- verlustbehaftete Bedienhandlungen kontrolliert abgefragt werden,
+- die Dialogoptionen konsistent funktionieren,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-006 Vollständige Editoroberfläche mit allen Konfigurationswerten und nativen Datei-/Ordnerdialogen vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Die GUI bildet alle aktuell bekannten Konfigurationswerte sichtbar und bearbeitbar ab, einschließlich der relevanten Pfad-Picker.
+
+### Muss umgesetzt werden
+- Die feste Oberflächenstruktur für den einen Tab vollständig ausbauen.
+- Alle aktuell bekannten Konfigurationswerte in geeigneten Eingabefeldern abbilden.
+- Für mindestens diese Pfade jeweils Texteingabefeld plus kleinen nativen Datei-/Ordnerdialog-Button umsetzen:
+  - Quellordner
+  - Zielordner
+  - SQLite-Datei
+  - Prompt-Datei
+- Sicherstellen, dass Eingabefelder und Dialoge auf denselben Editorzustand arbeiten.
+- Windows-typische Pfadangaben und gemappte Laufwerksbuchstaben technisch unbeeinträchtigt übernehmen.
+- Provider-bezogene Felder so einhängen, dass spätere M11-Komfortlogik darauf aufsetzen kann, ohne das Grundlayout neu zu erfinden.
+- Noch keine sofortige Validierung, keinen Modellabruf und keine technische Testfunktion aktivieren.
+- JavaDoc für GUI-Bereichsverantwortung und Pfadbedienung ergänzen.
+
+### Explizit nicht Teil
+- Provider-ComboBox
+- Modelllistenlogik
+- feldnahe Fehlermeldungen
+- zentraler Meldungsbereich mit echter Semantik
+- technische Tests oder Korrekturhilfen
+
+### Fertig wenn
+- alle aktuell bekannten Konfigurationswerte im GUI-Editor sichtbar und bearbeitbar sind,
+- die relevanten Datei-/Ordnerdialoge funktional vorhanden sind,
+- Windows-Pfade und gemappte Laufwerke nicht künstlich beschädigt werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-007 M10-Integration, GUI-Dateifluss über `--config` und benutzernahe Regressionstests absichern
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Der vollständige M10-Datei- und Editorfluss wird integriert abgesichert, einschließlich des Zusammenspiels mit dem in M9 eingeführten Startpfad.
+
+### Muss umgesetzt werden
+- Sicherstellen, dass ein gültiger übergebener GUI-Konfigurationspfad aus M9 direkt als Editorinhalt geladen werden kann.
+- Sicherstellen, dass der GUI-Start ohne Konfiguration weiterhin im definierten Willkommenstext-Zustand landet.
+- Regressionstests für die wesentlichen M10-Bedienflüsse ergänzen, insbesondere für:
+  - GUI-Start ohne geladene Konfiguration,
+  - **Neu** mit Standardvorlage,
+  - **Öffnen** bestehender `.properties`,
+  - **Speichern** und **Speichern unter**,
+  - Überschreibdialog,
+  - Dirty-State-Markierung,
+  - Schutzdialog bei offenen Änderungen,
+  - gültigen GUI-Start mit `--config`.
+- Tests so schneiden, dass sie M10 zuverlässig absichern, ohne M11/M12-Funktionalität künstlich zu simulieren.
+- Abschließende Konsistenzprüfung des M10-Stands gegen den definierten Scope durchführen.
+
+### Explizit nicht Teil
+- sofortige Validierung beim Öffnen
+- technischer Gesamttest
+- Modellabruf
+- Korrekturhilfen
+- DB-/Historienfunktionalität
+
+### Fertig wenn
+- der vollständige M10-Datei- und Editorfluss integriert funktioniert,
+- die wesentlichen Bedienpfade automatisiert abgesichert sind,
+- der Stand buildbar, testbar und übergabefähig ist,
+- noch keine Funktionalität aus M11+ vorweggenommen wurde.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M10 – GUI-Konfigurationseditor, Dateihandling und Benutzerführung** zugeschnitten. Sie liefern einen echten, benutzerfreundlichen Konfigurationseditor auf Basis der bestehenden `.properties`-Wahrheit, ohne bereits Provider-Komfortlogik, sofortige Validierung oder technische Test-/Korrekturfunktionen aus **M11/M12** vorwegzunehmen.
@@ -0,0 +1,411 @@
+# M11 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M11 – Provider-Bedienung, Modellabruf und automatische Validierung**.
+
+Die Meilensteine **M1** bis **M10** sowie der dokumentierte Ist-Stand **V1.1** werden als vollständig umgesetzt und freigegeben vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter, Bootstrap, GUI und Tests ändern.
+- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand, `meilensteine-v2_0.md` oder dieses Dokument gedeckt sind.
+- Kein Vorgriff auf **M12+**.
+- Kein Umbau bestehender M1–M10-Strukturen ohne direkten M11-Bezug.
+- Die GUI muss mit der bestehenden **Mehrprovider-Konfigurationsstruktur** kompatibel bleiben.
+- Es bleibt bei **genau einem aktiven Provider**; die GUI darf dabei die nicht sichtbaren Providerdaten nicht verlieren.
+- Der Modellabruf ist in M11 **Komfortfunktion**, kein manueller Gesamttest und kein KI-Funktionsnachweis.
+- Automatische Validierung in M11 ist **editornah und benutzerführend**; sie läuft beim Öffnen und während der Bearbeitung im Hintergrund und ersetzt noch nicht die explizite **Aktion „Validieren“** oder **„Technische Tests ausführen“** aus M12.
+- Änderungen klein, fokussiert und architekturtreu halten.
+- Neue Typen, View-Modelle, Ports, Provider-Resolver, Meldungsmodelle und Tests so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind.
+
+## Explizit nicht Bestandteil von M11
+
+- Aktion **„Validieren“**
+- Aktion **„Technische Tests ausführen“**
+- M12-spezifische Gesamtprüfungs- und Korrekturpfade rund um die Aktion **„Modelle neu laden“** (die Aktion selbst gehört zu M11 als manueller Wieder-Auslöser des bereits vorhandenen Modellabrufs)
+- technische Gesamtprüfung aller Konfigurations- und Laufzeitvoraussetzungen
+- schreibende Korrekturhilfen oder Sammel-Bestätigungsdialoge
+- automatische Erzeugung fehlender Prompt-Dateien
+- DB-/Historienanzeige
+- manueller Verarbeitungslauf aus der GUI
+- EXE
+- Installer
+- neues Konfigurationsformat
+- neue Provider über Claude und OpenAI-kompatibel hinaus
+- Änderungen an fachlicher Kernverarbeitung, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten
+
+## Verbindliche M11-Regeln für **alle** Arbeitspakete
+
+### 1. Provider-Bedienung
+
+Ab M11 gilt verbindlich:
+
+- Es gibt genau **eine Provider-ComboBox**.
+- Sichtbar ist immer nur der **aktuell ausgewählte Provider-Bereich**.
+- Die GUI darf die Daten des jeweils nicht sichtbaren Providers **nicht löschen**.
+- Die bestehende Mehrprovider-Struktur in der `.properties`-Datei bleibt erhalten.
+- In M11 werden genau die bereits vorhandenen Provider unterstützt:
+  - **Claude**
+  - **OpenAI-kompatibel**
+
+### 2. Modellabruf und Modellfeldlogik
+
+Ab M11 gilt verbindlich:
+
+- Nach Providerwechsel startet der **Modellabruf automatisch**.
+- Der Modellabruf darf auch dann angestoßen werden, wenn die Konfiguration noch unvollständig ist.
+- Fehlende Voraussetzungen führen **nicht** zu einem Absturz, sondern zu benutzerfreundlichen Befunden.
+- Wenn eine Modellliste erfolgreich geladen werden kann:
+  - erscheint eine **nicht editierbare ComboBox**,
+  - sie ist **nie leer**,
+  - das **erste Modell** wird automatisch vorbelegt.
+- Wenn keine Modellliste verfügbar ist:
+  - erscheint statt der ComboBox ein **leeres Texteingabefeld**,
+  - der Modellname muss manuell eingetragen werden.
+- Ein zuvor manuell eingetragener Modellname wird **verworfen**, wenn später eine echte Modellliste geladen wird und der Wert dort nicht vorkommt.
+
+### 3. Automatische Validierung
+
+Ab M11 gilt verbindlich:
+
+- Die GUI validiert den aktuellen Editorzustand **sofort beim Öffnen** einer Konfiguration.
+- Die GUI validiert den aktuellen Editorzustand außerdem **während der Bearbeitung**.
+- Die Validierung arbeitet mit dem **aktuellen GUI-Zustand**, nicht mit dem zuletzt gespeicherten Dateistand.
+- Die Validierung speichert **nichts implizit**.
+- Die Validierung darf Befunde der Stufen **Info**, **Hinweis**, **Warnung** und **Fehler** erzeugen.
+
+### 4. Meldungsbereich
+
+Ab M11 gilt verbindlich:
+
+- Es gibt einen großen, nicht editierbaren, dauerhaft sichtbaren **zentralen Meldungsbereich**.
+- Es gibt genau vier Stufen:
+  - **Info**
+  - **Hinweis**
+  - **Warnung**
+  - **Fehler**
+- Nur das Präfix der Zeile ist farbig.
+- Der eigentliche Text derselben Zeile bleibt **schwarz**.
+- Modellabruf, automatische Validierung und GUI-nahe technische Befunde laufen in diesen Meldungsbereich ein.
+
+### 5. Feldnahe Fehlerrückmeldung
+
+Ab M11 gilt verbindlich:
+
+- Problematische Eingabefelder erhalten zusätzlich **feldnahe Fehlermeldungen**.
+- Diese Meldungen sind:
+  - **klein**,
+  - **rot**,
+  - **deutschsprachig**,
+  - **direkt unter dem betroffenen Feld**.
+- Feldnahe Meldungen ergänzen den zentralen Meldungsbereich; sie ersetzen ihn nicht.
+
+### 6. Warnlogik für Grenzen und Risiken
+
+Ab M11 gilt verbindlich:
+
+- **`max.text.characters`** wird wirtschaftlich bewertet mit folgenden Schwellen:
+  - bis **1.000**: unkritisch
+  - **1.001–3.000**: Warnung
+  - ab **3.001**: starke Warnung
+- Diese Warnlogik ist ausdrücklich **zeichenbasiert** und verspricht **keine exakte Token- oder Kostenschätzung**.
+- **`max.pages`** wird **nicht** als direkte Kostenwarnung behandelt, sondern höchstens als **Plausibilitäts-/Performance-Hinweis**.
+- Weitere riskante, aber formal zulässige Konfigurationen dürfen als Warnung oder Hinweis sichtbar gemacht werden, soweit sie aus dem vorhandenen Zielbild klar ableitbar sind.
+
+### 7. API-Key-Herkunft und Env-Var-Schutz
+
+Ab M11 gilt verbindlich:
+
+- Die GUI macht die Herkunft des effektiven API-Keys für den Benutzer **sichtbar**, insbesondere wenn eine providerspezifische Umgebungsvariable aktuell Vorrang vor dem Property-Wert hat.
+- Das API-Key-Eingabefeld ist ein **normales, unmaskiertes Textfeld** (pragmatische V2.0-Entscheidung, keine Sicherheitsbehauptung).
+- Ein leeres API-Key-Feld darf einen bereits vorhandenen Property-Wert **nicht stillschweigend löschen**, wenn keine Umgebungsvariable greift. Stattdessen bleibt der Property-Wert erhalten und eine **deutliche Warnung** wird angezeigt.
+
+### 8. Grenzen von M11
+
+M11 liefert eine sofort reagierende, benutzerfreundliche Provider- und Validierungsoberfläche, aber noch **keine** vollständige technische Gesamtprüfung des Systems.
+
+Daraus folgt:
+
+- M11 darf Provider-nahe Remote-Kommunikation für **Modelllisten** einführen.
+- M11 führt **keine** schreibenden Korrekturen durch.
+- M11 vervollständigt noch **nicht** die M12-Gesamtprüfungen für Pfade, SQLite, Prompt-Datei oder anlegbare Ressourcen.
+
+---
+
+## AP-001 Provider-/Modell-Kernobjekte, GUI-Zustandssemantik und Port-Verträge präzisieren
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M11-Startpunkt.
+
+### Ziel
+Die M11-relevanten GUI-Zustände, Provider-/Modellmodelle, Meldungsstufen und Verträge werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können.
+
+### Muss umgesetzt werden
+- Neue M11-relevante Typen bzw. GUI-/Application-nahe Modelle anlegen, insbesondere für:
+  - auswählbaren Provider,
+  - sichtbaren Providerbereich,
+  - Modellquelle,
+  - Modelllisten-Ergebnis,
+  - manuellen Modellfallback,
+  - API-Key-Herkunft des effektiven Werts,
+  - Meldungsstufe,
+  - feldnahen Validierungsbefund,
+  - zentralen Meldungseintrag,
+  - Validierungsergebnis des aktuellen Editorzustands.
+- Verträge so schneiden, dass spätere Arbeitspakete unterscheiden können zwischen:
+  - erfolgreichem Modellabruf mit Liste,
+  - technisch fehlgeschlagenem Modellabruf,
+  - Modellabruf ohne nutzbare Liste,
+  - automatischer Validierung mit Fehlern,
+  - automatischer Validierung mit Warnungen/Hinweisen.
+- Outbound-Port bzw. Application-Vertrag für das providerabhängige Laden einer Modellliste definieren.
+- Sicherstellen, dass Domain und Application frei von JavaFX-, HTTP- und JSON-Bibliothekstypen bleiben.
+- JavaDoc und `package-info` für Verantwortlichkeiten und Grenzen ergänzen.
+
+### Explizit nicht Teil
+- konkrete GUI-Widgets
+- konkrete HTTP-Implementierung für Modelllisten
+- Validierungsregeln selbst
+- Meldungsbereich-Rendering
+- Bootstrap-Verdrahtung
+
+### Fertig wenn
+- die M11-relevanten Typen und Verträge vorhanden sind,
+- technische und fachnahe GUI-Befunde klar unterscheidbar modelliert sind,
+- Domain und Application frei von Infrastrukturtypen bleiben,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Provider-ComboBox, sichtbarer Providerbereich und zustandsbewahrender Providerwechsel umsetzen
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die GUI bildet die bestehende Mehrprovider-Struktur benutzerfreundlich ab, zeigt aber nur den aktuell ausgewählten Providerbereich an.
+
+### Muss umgesetzt werden
+- Provider-ComboBox mit genau den zwei vorhandenen Providern implementieren.
+- Sichtbarkeit der providerabhängigen Eingabefelder so umsetzen, dass immer nur der aktuell ausgewählte Providerbereich sichtbar ist.
+- Sicherstellen, dass ein Providerwechsel die Werte des jeweils anderen Providers nicht verliert.
+- Sicherstellen, dass die GUI weiterhin mit der bestehenden Mehrprovider-Konfigurationsstruktur kompatibel bleibt.
+- Providerwechsel sauber in den Editorzustand zurückschreiben.
+- Die GUI so schneiden, dass M11 später den automatischen Modellabruf andocken kann, ohne den Providerbereich erneut umzubauen.
+- JavaDoc/Kommentare für die Zustandsbewahrung und die GUI-Verantwortung ergänzen.
+
+### Explizit nicht Teil
+- Modellabruf
+- automatische Validierung
+- Meldungsbereich
+- feldnahe Fehlermeldungen
+- M12-Gesamttests
+
+### Fertig wenn
+- der Provider komfortabel per ComboBox gewählt werden kann,
+- immer nur die passenden Providerfelder sichtbar sind,
+- die Werte des nicht sichtbaren Providers erhalten bleiben,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-003 Providerabhängigen Modellabruf für Claude und OpenAI-kompatibel technisch einführen
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Für den aktuell ausgewählten Provider kann eine Modellliste technisch geladen und gekapselt an die GUI zurückgegeben werden.
+
+### Muss umgesetzt werden
+- Den in AP-001 definierten Modelllisten-Port technisch im Adapter-Out implementieren.
+- Providerabhängige Modelllistenabfrage für:
+  - **Claude**,
+  - **OpenAI-kompatibel**
+  implementieren.
+- Den Modellabruf so kapseln, dass GUI und Application keine HTTP- oder JSON-Details kennen.
+- Kontrolliertes Fehlerverhalten mindestens für folgende Fälle bereitstellen:
+  - Providerkonfiguration unvollständig,
+  - Endpunkt nicht erreichbar,
+  - Authentifizierung schlägt technisch fehl,
+  - Provider liefert keine nutzbare Modellliste,
+  - sonstige technische Kommunikationsfehler.
+- Sicherstellen, dass diese Fälle als benutzerfreundliche Befunde weitergegeben werden können und die GUI nicht abbrechen lassen.
+- Bootstrap-Verdrahtung nur im minimal erforderlichen Umfang ergänzen.
+- JavaDoc für Modellabruf, Providergrenzen und Nicht-Ziele von M11 ergänzen.
+
+### Explizit nicht Teil
+- Umschaltung zwischen ComboBox und Textfeld in der GUI
+- automatische Validierung des gesamten Editorzustands
+- Gesamtprüfung aus M12
+- schreibende Korrekturhilfen
+
+### Fertig wenn
+- für beide vorhandenen Provider ein technischer Modellabruf möglich ist,
+- Fehler kontrolliert und GUI-tauglich zurückgegeben werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 Automatischen Modellabruf, Aktion „Modelle neu laden“ und Umschaltung zwischen Modell-ComboBox und Modell-Textfeld integrieren
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Die GUI reagiert auf Providerwechsel sofort mit Modellabruf, bietet zusätzlich eine explizite Aktion **„Modelle neu laden“** und zeigt je nach Ergebnis entweder eine nicht editierbare Modell-ComboBox oder ein manuelles Modell-Textfeld an.
+
+### Muss umgesetzt werden
+- Automatischen Modellabruf bei Providerwechsel verdrahten.
+- Die explizite Aktion **„Modelle neu laden“** an denselben Modellabruf anbinden, ohne eine zweite Modelllisten-Implementierung einzuführen.
+- Sicherstellen, dass der Modellabruf auch bei unvollständiger Konfiguration angestoßen wird und dann benutzerfreundliche Befunde liefert.
+- Bei erfolgreicher Modellliste:
+  - nicht editierbare ComboBox anzeigen,
+  - erstes Modell automatisch vorbelegen,
+  - leeren Zustand ausschließen.
+- Bei fehlender oder unbrauchbarer Modellliste:
+  - manuelles Textfeld anzeigen,
+  - leeren Startwert zulassen,
+  - Benutzer zur manuellen Eingabe befähigen.
+- Sicherstellen, dass ein früherer manueller Modellwert verworfen wird, wenn später eine echte Liste geladen wird und der Wert dort nicht vorkommt.
+- Die Modellwert-Übernahme so schneiden, dass die `.properties`-Struktur später korrekt geschrieben werden kann.
+- Benötigte Meldungen für erfolgreichen Modellabruf bzw. Fallback vorbereiten.
+- JavaDoc/Kommentare für die Modellfeldsemantik ergänzen.
+
+### Explizit nicht Teil
+- vollständiger zentraler Meldungsbereich
+- feldnahe rote Fehlermeldungen
+- allgemeine Editorvalidierung über alle Konfigurationsbereiche
+
+### Fertig wenn
+- Modellabruf automatisch beim Providerwechsel ausgelöst wird,
+- die Aktion **„Modelle neu laden“** denselben Modellabruf gezielt erneut auslösen kann,
+- ComboBox und Textfeld korrekt umgeschaltet werden,
+- die Liste nie leer dargestellt wird,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 Automatische Validierungslogik für geladenen und bearbeiteten Editorzustand umsetzen
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Der aktuelle GUI-Zustand wird beim Öffnen und während der Bearbeitung sofort ausgewertet und liefert Fehler, Warnungen und Hinweise.
+
+### Muss umgesetzt werden
+- Einen zentralen Validierungsbaustein für den aktuellen Editorzustand implementieren.
+- Die Bewertung des API-Key-Zustands so umsetzen, dass die bestehende Vorrangregel respektiert wird:
+  1. providerspezifische Umgebungsvariable,
+  2. bei **OpenAI-kompatibel** zusätzlich die bestehende Legacy-Umgebungsvariable,
+  3. Property-Wert aus der Datei.
+- Validierung beim Öffnen einer Konfiguration automatisch ausführen.
+- Revalidierung bei relevanten Änderungen während der Bearbeitung ausführen.
+- Mindestens folgende Befundarten sicher unterscheiden:
+  - harte Fehler für unvollständige oder unzulässige Pflichtwerte,
+  - Warnungen für riskante, aber formal zulässige Einstellungen,
+  - Hinweise/Infos für nützliche Kontextinformationen.
+- Die wirtschaftliche Warnlogik für **`max.text.characters`** mit den definierten Schwellen umsetzen.
+- **`max.pages`** ausdrücklich nur als Plausibilitäts-/Performance-Hinweis behandeln.
+- Sicherstellen, dass die Validierung mit dem aktuellen GUI-Zustand arbeitet und kein implizites Speichern auslöst.
+- Sichtbar machen können, wenn aktuell eine Umgebungsvariable den Property-Wert übersteuert.
+- Sicherstellen, dass ein leeres API-Key-Feld einen bereits vorhandenen Property-Wert nicht stillschweigend entfernt; stattdessen ist ein deutlicher Befund für den zentralen Meldungsbereich vorzubereiten.
+- Validierungsmodell so schneiden, dass es später sowohl zentrale Meldungen als auch feldnahe Befunde speisen kann.
+- JavaDoc für Validierungsgrenzen, API-Key-Vorrangregel und Nicht-Ziele von M11 ergänzen.
+
+### Explizit nicht Teil
+- explizite Aktion **„Validieren“**
+- technische Gesamtprüfungen für Pfade, Prompt-Datei, SQLite oder anlegbare Ressourcen
+- schreibende Korrekturen
+- Bestätigungsdialoge für Korrekturen
+
+### Fertig wenn
+- beim Öffnen und Bearbeiten automatische Befunde erzeugt werden,
+- `max.text.characters` und `max.pages` korrekt bewertet werden,
+- kein implizites Speichern erfolgt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-006 Zentralen Meldungsbereich und feldnahe rote Fehlermeldungen benutzerfreundlich anbinden
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Die GUI zeigt automatische Modellabruf- und Validierungsbefunde sowohl zentral als auch feldnah in der vereinbarten Form an.
+
+### Muss umgesetzt werden
+- Den vorhandenen Meldungsbereich funktional anbinden.
+- Vier feste Meldungsstufen umsetzen:
+  - Info,
+  - Hinweis,
+  - Warnung,
+  - Fehler.
+- Darstellung so umsetzen, dass nur das Präfix farbig ist und der restliche Zeilentext schwarz bleibt.
+- Feldnahe rote, kleine, deutschsprachige Fehlermeldungen direkt unter problematischen Eingabefeldern anbinden.
+- Sicherstellen, dass zentrale und feldnahe Befunde konsistent aus demselben Validierungs-/Meldungsmodell gespeist werden.
+- Modellabruf-Ergebnisse in den Meldungsbereich integrieren, z. B. erfolgreiche Listenladung oder manueller Fallback.
+- API-Key-Herkunftsanzeige (Umgebungsvariable vs. Property-Wert) in den zentralen Meldungsbereich und, soweit feldnah sinnvoll, unter das API-Key-Feld anbinden.
+- Die GUI so schneiden, dass M12 später zusätzliche Meldungen aus expliziten Gesamtprüfungen anschließen kann, ohne M11 neu zu zerlegen.
+- JavaDoc/Kommentare für Meldungssemantik und Renderinggrenzen ergänzen.
+
+### Explizit nicht Teil
+- technische Gesamtprüfung aus M12
+- schreibende Korrekturen und Sammel-Bestätigungsdialog
+- automatische Prompt-Erzeugung
+- DB-/Historienanzeige
+
+### Fertig wenn
+- automatische Befunde zentral sichtbar sind,
+- feldnahe Fehlermeldungen unter den betroffenen Feldern erscheinen,
+- die Darstellung den vereinbarten Farbund Textregeln entspricht,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-007 Tests für Providerwechsel, Modellabruf, automatische Validierung und Meldungsdarstellung ergänzen
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Der vollständige M11-Zielzustand wird automatisiert abgesichert und als stabiler Übergabestand nachgewiesen.
+
+### Muss umgesetzt werden
+- Tests für Providerwechsel und zustandsbewahrende Providerdaten ergänzen.
+- Tests für Modellabruf mit erfolgreicher Liste ergänzen.
+- Tests für Modellabruf ohne nutzbare Liste und manuellen Fallback ergänzen.
+- Tests für das Verwerfen eines manuellen Modellwerts ergänzen, wenn später eine echte Liste verfügbar ist und der Wert dort nicht vorkommt.
+- Tests für automatische Validierung beim Öffnen und bei Eingabeänderungen ergänzen.
+- Tests für die Warnschwellen von `max.text.characters` ergänzen.
+- Tests dafür ergänzen, dass `max.pages` nur als Plausibilitäts-/Performance-Hinweis behandelt wird.
+- Tests für Meldungsstufen und feldnahe Fehlerrückmeldungen ergänzen, soweit in der GUI-Teststrategie sinnvoll.
+- Den M11-Stand abschließend auf Konsistenz, Benutzerführung und Nicht-Vorgriff auf M12 prüfen.
+
+### Explizit nicht Teil
+- End-to-End-Gesamtprüfungen aus M12
+- schreibende Korrekturtests
+- Prompt-Erzeugung
+- DB-/Historienfunktionen
+
+### Fertig wenn
+- der definierte M11-Zielzustand automatisiert abgesichert ist,
+- Provider-Bedienung, Modellabruf und automatische Validierung stabil nachgewiesen sind,
+- der Stand fehlerfrei buildbar und übergabefähig ist.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M11 – Provider-Bedienung, Modellabruf und automatische Validierung** zugeschnitten. Sie decken den geplanten M11-Umfang vollständig ab, ohne technische Gesamttests, Korrekturhilfen oder andere V2.0-Bausteine späterer Meilensteine vorwegzunehmen.
@@ -0,0 +1,425 @@
+# M12 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M12 – Technische Tests, Korrekturhilfen und Windows-/Netzlaufwerksfähigkeit**.
+
+Die Meilensteine **M1** bis **M11** sowie der dokumentierte Ist-Stand **V1.1** werden als vollständig umgesetzt und freigegeben vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter, Bootstrap, GUI und Tests ändern.
+- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand, `meilensteine-v2_0.md` oder dieses Dokument gedeckt sind.
+- Kein Vorgriff auf **M13+**.
+- Kein Umbau bestehender M1–M11-Strukturen ohne direkten M12-Bezug.
+- **„Validieren“** und **„Technische Tests ausführen“** arbeiten mit dem **aktuellen GUI-Zustand**, nicht mit dem zuletzt gespeicherten Dateistand.
+- Es erfolgt **kein implizites Speichern**.
+- Der Gesamttest läuft **immer vollständig** durch und bricht **nicht** beim ersten Fehler ab.
+- Schreibende Korrekturen dürfen nur nach **einem gesammelten Bestätigungsdialog** erfolgen.
+- Netzlaufwerke über **gemappte Laufwerksbuchstaben** sind im Windows-Kontext ausdrücklich zu unterstützen.
+- Änderungen klein, fokussiert und architekturtreu halten.
+- Neue Testmodelle, Prüfergebnisse, Korrekturpläne, Ports, Services und GUI-Zustände so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind.
+
+## Explizit nicht Bestandteil von M12
+
+- DB-/Historienanzeige
+- manueller Verarbeitungslauf aus der GUI
+- EXE
+- Installer
+- neues Konfigurationsformat
+- neue Provider über Claude und OpenAI-kompatibel hinaus
+- Cost-Tracking oder Token-/Preisberechnung
+- mehrseitige GUI oder weitere Tabs
+- Änderungen an fachlicher Kernverarbeitung, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten
+- plattformübergreifende GUI-Unterstützung außerhalb des definierten Windows-Ziels
+
+## Verbindliche M12-Regeln für **alle** Arbeitspakete
+
+### 1. Unterschied zwischen „automatischer Validierung“, Aktion „Validieren“ und „Technische Tests ausführen“
+
+Ab M12 gilt verbindlich:
+
+- **Automatische Validierung** bleibt die in M11 definierte Hintergrundprüfung beim Öffnen und während der Bearbeitung.
+- **Aktion „Validieren“** ist die explizite, **nicht schreibende, lokale Gesamtprüfung** des aktuellen Editorzustands.
+- **Aktion „Validieren“** arbeitet ohne implizites Speichern und ohne schreibende Korrekturen.
+- **„Technische Tests ausführen“** ist ein **vollständiger Gesamttest** des aktuellen Editorzustands.
+- Der Gesamttest darf zusätzlich zu lokalen Prüfungen auch technische Prüfungen gegen Dateisystem und Provider durchführen.
+- Der Gesamttest darf **korrigierende Maßnahmen** vorschlagen, aber erst nach Bestätigung durchführen.
+
+### 2. Vollständiger Gesamttest ohne Frühabbruch
+
+Ab M12 gilt verbindlich:
+
+- Der Gesamttest führt **alle definierten Prüfpunkte** aus.
+- Ein einzelner Fehler darf **nicht** dazu führen, dass spätere Prüfpunkte ausgelassen werden.
+- Alle Befunde werden gesammelt im zentralen Meldungsbereich ausgegeben.
+- Die Ausführung basiert auf dem **aktuellen GUI-Zustand**, auch wenn dieser noch ungespeichert ist.
+
+### 3. Definierte Prüfpunkte des Gesamttests
+
+Ab M12 gilt verbindlich, dass der Gesamttest mindestens folgende Prüfpunkte unterstützt:
+
+- Konfiguration grundsätzlich validierbar
+- Provider-Konfiguration prüfbar
+- Base-URL/Endpoint technisch erreichbar
+- API-Key vorhanden, auch wenn der effektive Wert ausschließlich über eine passende Umgebungsvariable bereitgestellt wird
+- API-Key technisch akzeptiert
+- Modellliste abrufbar
+- ausgewähltes Modell plausibel
+- Prompt-Datei vorhanden und lesbar
+- Quellordner vorhanden und lesbar
+- Zielordner vorhanden oder anlegbar sowie schreibbar
+- SQLite-Datei bzw. SQLite-Pfad technisch nutzbar
+
+### 4. Schreibende Korrekturhilfen
+
+Ab M12 gilt verbindlich:
+
+- Schreibende Korrekturen werden **nicht still** durchgeführt.
+- Vor schreibenden Korrekturen wird **ein gesammelter Bestätigungsdialog** angezeigt.
+- Nur **sichere technische Korrekturen** dürfen angeboten werden.
+- Nicht automatisch korrigierbar bleiben insbesondere:
+  - falscher API-Key,
+  - unerreichbare Base-URL,
+  - nicht verfügbare Modellliste,
+  - fachlich unplausible, aber formal zulässige Werte.
+
+### 5. Automatische Prompt-Erzeugung
+
+Ab M12 gilt verbindlich:
+
+- Wenn die konfigurierte Prompt-Datei fehlt, darf eine **sinnvolle Standard-Prompt-Datei** automatisch erzeugt werden.
+- Diese Standard-Prompt-Datei ist **deutschsprachig**.
+- Sie liegt standardmäßig **im selben Ordner wie die `.properties`-Datei**.
+- Die Erzeugung ist eine **schreibende Korrektur** und unterliegt dem gesammelten Bestätigungsdialog.
+
+### 6. Windows- und Netzlaufwerksfähigkeit
+
+Ab M12 gilt verbindlich:
+
+- Die GUI und ihre Prüflogik unterstützen ausdrücklich **gemappte Laufwerksbuchstaben** wie `S:\` oder `H:\`.
+- Solche Pfade dürfen **nicht** allein deshalb abgelehnt oder umgedeutet werden, weil dahinter technisch ein UNC-Pfad stehen könnte.
+- Maßgeblich ist, dass Windows den Pfad als gültigen Pfad bereitstellt.
+- Diese Regel gilt mindestens für:
+  - Quellordner,
+  - Zielordner,
+  - SQLite-Datei,
+  - Prompt-Datei.
+
+### 7. Grenzen von M12
+
+M12 liefert die vollständige technische Prüf- und Korrekturunterstützung der V2.0-GUI, aber noch **nicht** den V2.0-Abschluss mit finaler Dokumentation und Gesamtqualitätsnachweis.
+
+---
+
+## AP-001 Prüf- und Korrektur-Kernobjekte, Ergebnissemantik und Port-Verträge präzisieren
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M12-Startpunkt.
+
+### Ziel
+Die M12-relevanten Prüf-, Korrektur- und Dialogmodelle werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können.
+
+### Muss umgesetzt werden
+- Neue M12-relevante Typen bzw. GUI-/Application-nahe Modelle anlegen, insbesondere für:
+  - explizite Validierungsanforderung,
+  - Gesamttestanforderung,
+  - Prüfpunktergebnis,
+  - Korrekturvorschlag,
+  - gesammelten Korrekturplan,
+  - Bestätigungsdialog-Inhalt,
+  - schreibenden vs. nicht schreibenden Prüfschritt,
+  - Ergebnis eines vollständigen Gesamttests.
+- Verträge so schneiden, dass spätere Arbeitspakete unterscheiden können zwischen:
+  - lokalem Validierungsbefund,
+  - technischem Prüfbefund,
+  - korrigierbarem Befund,
+  - nicht korrigierbarem Befund,
+  - bestätigtem Korrekturplan,
+  - abgelehntem Korrekturplan.
+- Outbound-Ports bzw. Application-Verträge definieren oder schärfen für:
+  - Provider-nahe technische Tests,
+  - Dateisystem-/Pfadtests,
+  - schreibende Korrekturhilfen,
+  - Prompt-Datei-Erzeugung.
+- Sicherstellen, dass Domain und Application frei von JavaFX-, HTTP-, NIO- und JDBC-Bibliothekstypen bleiben.
+- JavaDoc und `package-info` für Verantwortlichkeiten und Grenzen ergänzen.
+
+### Explizit nicht Teil
+- konkrete GUI-Buttons
+- konkrete Prüflogik
+- konkrete Korrekturen
+- Bootstrap-Verdrahtung
+- Gesamttest-Orchestrierung
+
+### Fertig wenn
+- die M12-relevanten Typen und Verträge vorhanden sind,
+- Validieren, Gesamttest und Korrekturplan klar unterscheidbar modelliert sind,
+- Domain und Application frei von Infrastrukturtypen bleiben,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Aktion „Validieren“ als explizite, nicht schreibende Gesamtprüfung des Editorzustands umsetzen
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die GUI bietet eine explizite Validierungsaktion, die den aktuellen Editorzustand lokal und vollständig prüft, ohne etwas zu speichern oder zu verändern.
+
+### Muss umgesetzt werden
+- Die Aktion **„Validieren“** funktionsfähig anbinden.
+- Sicherstellen, dass die Aktion mit dem **aktuellen GUI-Zustand** arbeitet, nicht mit dem zuletzt gespeicherten Dateistand.
+- Keine implizite Speicherung auslösen.
+- Keine schreibenden Korrekturen durchführen.
+- Alle lokalen Befunde gesammelt erzeugen und dem vorhandenen Meldungsmodell zuführen.
+- Relevante feldnahe Fehlermeldungen ergänzen oder schärfen.
+- Eindeutige deutsche Meldungen für Fehler, Warnungen, Hinweise und Infos verwenden.
+- JavaDoc/Kommentare für die Abgrenzung zur M12-Gesamttestaktion ergänzen.
+
+### Explizit nicht Teil
+- Provider-nahe Remote-Tests
+- schreibende Korrekturen
+- Bestätigungsdialog für Korrekturmaßnahmen
+- Prompt-Datei-Erzeugung
+
+### Fertig wenn
+- **„Validieren“** den aktuellen Editorzustand explizit und nicht schreibend prüfen kann,
+- keine implizite Speicherung stattfindet,
+- die Befunde verständlich und vollständig angezeigt werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-003 Provider-nahe technische Prüflogik für Endpoint, API-Key, Modellliste und Modellplausibilität umsetzen
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Die für V2.0 geforderten providerbezogenen technischen Prüfpunkte können kontrolliert und providerabhängig ausgeführt werden.
+
+### Muss umgesetzt werden
+- Die technische Prüflogik für mindestens folgende providerbezogene Prüfpunkte implementieren:
+  - Base-URL/Endpoint erreichbar,
+  - API-Key vorhanden,
+  - API-Key technisch akzeptiert,
+  - Modellliste abrufbar,
+  - ausgewähltes Modell plausibel.
+- Für den Prüfpunkt **„Modellliste abrufbar“** ausdrücklich denselben Outbound-Port und denselben Adapter verwenden, die bereits in M11 für den Modellabruf eingeführt wurden; der Prüfpunkt ist ein zusätzlicher Aufruf, keine zweite Implementierung.
+- Die Prüflogik für Claude und OpenAI-kompatibel sauber kapseln.
+- Beim Prüfpunkt **„API-Key vorhanden“** die bestehende Vorrangregel respektieren, sodass reine Umgebungsvariablen-Setups nicht fälschlich als fehlender API-Key bewertet werden.
+- Sicherstellen, dass providerbezogene technische Fehler verständlich in das bestehende Meldungsmodell überführt werden.
+- Sichere Abgrenzung zwischen:
+  - fehlender Voraussetzung,
+  - technischer Unerreichbarkeit,
+  - Authentifizierungsproblem,
+  - nicht verfügbarer Modellliste,
+  - unplausibler Modellauswahl.
+- Provider-nahe technische Prüfungen laufen asynchron auf einem Worker-Thread; die Ergebnisrückführung in die GUI erfolgt über den JavaFX Application Thread.
+- Keine impliziten Korrekturen durchführen.
+- JavaDoc/Kommentare für technische Prüfpunkte und Nicht-Ziele ergänzen.
+
+### Explizit nicht Teil
+- schreibende Korrekturen
+- Pfad-/Dateisystemtests
+- Gesamttest-Orchestrierung
+- Prompt-Datei-Erzeugung
+
+### Fertig wenn
+- alle providerbezogenen technischen Prüfpunkte separat ausführbar und auswertbar sind,
+- Befunde verständlich im vorhandenen Meldungsmodell ankommen,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 Windows-Pfadprüfung und ausdrückliche Unterstützung gemappter Laufwerke umsetzen
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Die GUI und ihre Prüflogik behandeln Windows-Pfade einschließlich gemappter Laufwerksbuchstaben korrekt und benutzerfreundlich.
+
+### Muss umgesetzt werden
+- Pfadprüfungen für folgende Konfigurationswerte vervollständigen:
+  - Quellordner,
+  - Zielordner,
+  - SQLite-Datei,
+  - Prompt-Datei.
+- Gemappte Laufwerksbuchstaben wie `S:\` oder `H:\` im Windows-Kontext ausdrücklich akzeptieren.
+- Sicherstellen, dass solche Pfade nicht allein wegen möglicher UNC-Backings abgelehnt oder umgedeutet werden.
+- Lokale Validierungs- und Testbefunde für Pfadprobleme sauber unterscheiden, insbesondere:
+  - fehlt,
+  - nicht lesbar,
+  - nicht schreibbar,
+  - ungültig,
+  - anlegbar.
+- Pfadprüfungen laufen asynchron auf einem Worker-Thread; die Ergebnisrückführung in die GUI erfolgt über den JavaFX Application Thread.
+- Ausführung und Ergebnis der Pfadprüfungen werden im bestehenden Log4j2-Log nachvollziehbar protokolliert.
+- JavaDoc/Kommentare für Windows-/Netzlaufwerksfähigkeit und technische Grenzen ergänzen.
+
+### Explizit nicht Teil
+- schreibende Erstellung fehlender Ressourcen
+- Prompt-Datei-Erzeugung
+- Gesamttest-Orchestrierung
+- Provider-nahe Remote-Tests
+
+### Fertig wenn
+- Windows-Pfade korrekt validiert werden,
+- gemappte Laufwerke als gültige Pfade akzeptiert werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 Aktion „Technische Tests ausführen“ als vollständigen Gesamttest ohne Frühabbruch umsetzen
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Die GUI kann einen vollständigen technischen Gesamttest des aktuellen Editorzustands ausführen und alle Befunde gesammelt zurückgeben.
+
+### Muss umgesetzt werden
+- Die Aktion **„Technische Tests ausführen“** funktionsfähig anbinden.
+- Sicherstellen, dass sie mit dem **aktuellen GUI-Zustand** arbeitet und nichts implizit speichert.
+- Die definierten Prüfpunkte vollständig orchestrieren, insbesondere:
+  - Konfiguration grundsätzlich validierbar,
+  - Provider-Konfiguration prüfbar,
+  - Base-URL/Endpoint erreichbar,
+  - API-Key vorhanden,
+  - API-Key technisch akzeptiert,
+  - Modellliste abrufbar,
+  - ausgewähltes Modell plausibel,
+  - Prompt-Datei vorhanden und lesbar,
+  - Quellordner vorhanden und lesbar,
+  - Zielordner vorhanden oder anlegbar sowie schreibbar,
+  - SQLite-Datei bzw. SQLite-Pfad technisch nutzbar.
+- Sicherstellen, dass der Gesamttest **nicht** beim ersten Fehler abbricht.
+- Alle Befunde gesammelt und verständlich im zentralen Meldungsbereich ausgeben.
+- Deutlich kenntlich machen, dass sich das Ergebnis auf den aktuellen Editorzustand bezieht.
+- JavaDoc/Kommentare zur Gesamttest-Semantik ergänzen.
+
+### Explizit nicht Teil
+- schreibende Korrekturen
+- Sammel-Bestätigungsdialog
+- Prompt-Datei-Erzeugung
+- Abschlussdokumentation
+
+### Fertig wenn
+- die Aktion **„Technische Tests ausführen“** vollständig arbeitet,
+- kein Frühabbruch stattfindet,
+- alle Befunde gesammelt sichtbar werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-006 Schreibende Korrekturhilfen und gesammelten Bestätigungsdialog einführen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Die GUI kann sichere technische Korrekturen gesammelt vorschlagen und nach einmaliger Bestätigung kontrolliert durchführen.
+
+### Muss umgesetzt werden
+- Einen gesammelten Korrekturplan aus Prüfbefunden ableiten.
+- Einen einmaligen Bestätigungsdialog implementieren, der die geplanten schreibenden Maßnahmen gesammelt anzeigt.
+- Nur sichere technische Korrekturen zulassen, insbesondere dort, wo Ressourcen fehlend, aber technisch anlegbar sind.
+- Sicherstellen, dass ohne Bestätigung keine schreibenden Änderungen ausgeführt werden.
+- Nach Durchführung die Ergebnisse erneut verständlich in den Meldungsbereich zurückführen.
+- Keine stillen Auto-Korrekturen im Hintergrund zulassen.
+- JavaDoc/Kommentare für die Korrekturgrenzen ergänzen.
+
+### Explizit nicht Teil
+- providerbezogene Auto-Heilung
+- Änderung fachlich riskanter Werte
+- automatische Lauf-/Verarbeitungsstarts
+- Abschlussdokumentation
+
+### Fertig wenn
+- sichere technische Korrekturen gesammelt vorgeschlagen werden können,
+- genau ein Bestätigungsdialog vor der Ausführung erscheint,
+- ohne Bestätigung nichts geschrieben wird,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-007 Automatische deutsche Standard-Prompt-Erzeugung und anlegbare Ressourcen vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Fehlende, technisch anlegbare Ressourcen können im Rahmen der Korrekturhilfen sinnvoll hergestellt werden; insbesondere kann eine fehlende Prompt-Datei automatisch als deutsche Standarddatei erzeugt werden.
+
+### Muss umgesetzt werden
+- Die automatische Erzeugung einer sinnvollen **deutschsprachigen Standard-Prompt-Datei** implementieren.
+- Sicherstellen, dass diese standardmäßig **im selben Ordner wie die `.properties`-Datei** angelegt wird.
+- Die Erzeugung nur dann als Korrekturmaßnahme anbieten, wenn der vorgesehene Zielpfad tatsächlich beschreibbar ist.
+- Wenn der Standardpfad nicht beschreibbar ist, die Erzeugung ausdrücklich als **„nicht möglich, bitte manuell anlegen“** melden.
+- Die Erzeugung in den Korrekturplan und Bestätigungsdialog aus AP-006 integrieren.
+- Weitere sichere technische Korrekturen für anlegbare Ressourcen dort ergänzen, wo sie für V2.0 explizit gefordert sind, insbesondere:
+  - Zielordner anlegen,
+  - SQLite-Datei bzw. nutzbaren SQLite-Pfad vorbereiten,
+  - Prompt-Datei anlegen.
+- Verständliche deutsche Meldungen für Erfolg, Teilfehler und Nichtdurchführbarkeit bereitstellen.
+- JavaDoc/Kommentare für Prompt-Generierung und Ressourcenkorrektur ergänzen.
+
+### Explizit nicht Teil
+- fachliche Prompt-Evolution über die Standarddatei hinaus
+- manuelle Prompt-Bearbeitung in Spezialansichten
+- neue Betriebsfeatures
+- Abschlussdokumentation
+
+### Fertig wenn
+- die Standard-Prompt-Datei automatisch erzeugt werden kann,
+- die Erzeugung sauber in den Korrekturplan integriert ist,
+- weitere sichere technische Ressourcenkorrekturen funktionieren,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-008 Tests für Gesamttest, Korrekturdialog, Prompt-Erzeugung und Netzlaufwerksfähigkeit ergänzen
+
+### Voraussetzung
+AP-001 bis AP-007 sind abgeschlossen.
+
+### Ziel
+Der vollständige M12-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.
+
+### Muss umgesetzt werden
+- Tests für **„Validieren“** mit aktuellem, ungespeichertem Editorzustand ergänzen.
+- Tests für **„Technische Tests ausführen“** ohne Frühabbruch ergänzen.
+- Tests für providerbezogene technische Prüfpunkte ergänzen, soweit innerhalb von M12 sinnvoll und stabil automatisierbar.
+- Tests für den gesammelten Bestätigungsdialog ergänzen.
+- Tests für sichere technische Korrekturen ergänzen.
+- Tests für automatische Prompt-Erzeugung ergänzen.
+- Tests für Windows-/Netzlaufwerksannahmen ergänzen, insbesondere dafür, dass gemappte Laufwerksbuchstaben korrekt akzeptiert werden.
+- Sicherstellen, dass der definierte M12-Zielzustand vollständig buildbar und übergabefähig ist.
+
+### Explizit nicht Teil
+- Abschlussdokumentation des Gesamtprojekts
+- GUI-Erweiterungen aus M13+
+- DB-/Historienanzeige
+- manueller Verarbeitungslauf
+
+### Fertig wenn
+- die M12-spezifische Test-Suite grün ist,
+- Gesamttest, Korrekturhilfen und Netzlaufwerksfähigkeit automatisiert abgesichert sind,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M12 – Technische Tests, Korrekturhilfen und Windows-/Netzlaufwerksfähigkeit** zugeschnitten. Sie decken den vollständigen Zielumfang dieses Meilensteins ab, ohne spätere Ausbaustufen vorwegzunehmen.
@@ -0,0 +1,420 @@
+# M13 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M13 – V2.0-Abschluss, Dokumentation und Qualitätsnachweis**.
+
+Die Meilensteine **M1** bis **M12** sowie der dokumentierte Ist-Stand **V1.1** werden als vollständig umgesetzt und freigegeben vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Dokumentation, Build, Bootstrap, GUI, CLI, Konfigurationsbeispiele und Tests ändern.
+- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand, `meilensteine-v2_0.md` oder dieses Dokument gedeckt sind.
+- Kein Vorgriff auf spätere Ausbaustufen **jenseits von V2.0**.
+- Kein Umbau bestehender M1–M12-Strukturen ohne direkten M13-Bezug.
+- M13 ergänzt **keine neue Produktfunktionalität**, sondern dokumentiert, stabilisiert und belegt den bereits definierten V2.0-Gesamtstand.
+- GUI und headless bleiben **ein gemeinsames ausführbares JAR**; M13 erfindet keine neue Distributionsform.
+- Der bestehende **headless Server-/Scheduler-Betrieb** darf weder technisch noch dokumentarisch still gebrochen werden.
+- Änderungen klein, fokussiert und architekturtreu halten.
+- Ein Arbeitspaket darf nur dann einen Release-Blocker beheben, wenn dieser im unmittelbar vorhergehenden Prüf-Arbeitspaket **konkret nachgewiesen und eingegrenzt** wurde.
+
+## Explizit nicht Bestandteil von M13
+
+- DB-/Historienanzeige
+- manueller Verarbeitungslauf aus der GUI
+- EXE
+- Installer
+- neues Konfigurationsformat
+- neue Provider über Claude und OpenAI-kompatibel hinaus
+- Cost-Tracking oder Token-/Preisberechnung
+- neue Tabs oder größere GUI-Ausbaustufen jenseits des vorhandenen V2.0-Umfangs
+- neue fachliche Regeln für Dateinamensbildung, Retry, Persistenz oder Laufverhalten
+- plattformübergreifender offizieller GUI-Support außerhalb des definierten Windows-Ziels
+
+## Verbindliche M13-Regeln für **alle** Arbeitspakete
+
+### 1. M13 ist ein Abschluss- und Nachweismeilenstein
+
+Ab M13 gilt verbindlich:
+
+- Der funktionale V2.0-Umfang wird **nicht erweitert**, sondern für Betrieb, Übergabe und Freigabe abgesichert.
+- Änderungen in Produktionscode sind nur zulässig, wenn sie für:
+  - dokumentierte Start-/Betriebssemantik,
+  - belastbare Tests,
+  - Packaging-Stabilität,
+  - oder konkret nachgewiesene Release-Blocker
+  zwingend erforderlich sind.
+
+### 2. GUI und headless müssen gemeinsam und widerspruchsfrei beschrieben sein
+
+Ab M13 gilt verbindlich:
+
+- Die Dokumentation beschreibt den gemeinsamen Betrieb eines **einzigen ausführbaren JARs**.
+- **GUI ist Standardstart**.
+- **`--headless`** aktiviert den bisherigen Batch-/Scheduler-Betrieb.
+- **`--config <pfad>`** gilt für GUI und headless.
+- Verhalten bei ungültigem oder nicht vorhandenem `--config` muss für beide Startarten klar dokumentiert und testbar belegt sein.
+
+### 3. `.properties` bleibt die einzige Konfigurationswahrheit
+
+Ab M13 gilt verbindlich:
+
+- Dokumentation, Konfigurationsbeispiele, GUI-Verhalten und headless Betrieb verwenden weiterhin dieselbe `.properties`-Struktur.
+- M13 führt keine zweite Konfigurationswelt für GUI oder headless ein.
+- Prompt-Datei und Properties-Datei bleiben getrennte Artefakte; die Prompt-Datei bleibt externe Datei.
+
+### 4. Headless-Abwärtskompatibilität ist release-kritisch
+
+Ab M13 gilt verbindlich:
+
+- Bestehender headless Betrieb ohne GUI-Einsatz bleibt lauffähig.
+- Headless darf keine separate JavaFX-Installation voraussetzen.
+- Bestehendes Default-Verhalten für headless Starts **ohne `--config`** bleibt erhalten.
+- Regressionen im bisherigen Server-/Scheduler-Betrieb gelten in M13 als **Release-Blocker**.
+
+### 5. Windows-zentrierte GUI-Dokumentation
+
+Ab M13 gilt verbindlich:
+
+- Die GUI wird für **Windows** dokumentiert.
+- Windows-spezifische Pfade und gemappte Laufwerke bleiben Teil des Zielbilds.
+- Dokumentation und Beispiele dürfen diese Pfadrealität nicht still relativieren oder auf UNC-only reduzieren.
+
+### 6. Qualitätsnachweis basiert auf real ausgeführten Prüfungen
+
+Ab M13 gilt verbindlich:
+
+- Ein V2.0-Freigabestand wird nur auf Basis **real ausgeführter Builds und Tests** beschrieben.
+- Prüf- und Freigabedokumente müssen den tatsächlich ausgeführten Stand wiedergeben.
+- Reine Absichtserklärungen ohne realen Nachweis sind für M13 unzureichend.
+
+### 7. Release-Blocker und finale Freigabe sind getrennte Schritte
+
+Ab M13 gilt verbindlich:
+
+- Zuerst wird eine **Befundliste** mit konkret eingegrenzten Restthemen erstellt.
+- Danach dürfen nur die dokumentierten Release-Blocker gezielt behoben werden.
+- Erst danach erfolgt eine finale Gesamtprüfung und Freigabedokumentation.
+
+---
+
+## AP-001 V2.0-Betriebs- und Startdokumentation für GUI und headless konsolidieren
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M13-Startpunkt.
+
+### Ziel
+Der V2.0-Betrieb wird für Benutzer und Betreiber klar, widerspruchsfrei und vollständig beschrieben.
+
+### Muss umgesetzt werden
+- Die bestehende Betriebsdokumentation **`betrieb.md`** sowie ggf. vorhandene README-Dateien gezielt auf den V2.0-Stand erweitern.
+- Mindestens folgende Punkte klar und konsistent dokumentieren:
+  - gemeinsames ausführbares JAR,
+  - GUI als Standardstart,
+  - `--headless`,
+  - `--config <pfad>`,
+  - Verhalten bei fehlender oder ungültiger Konfiguration,
+  - Verhalten bei GUI-Startfehlern,
+  - Windows-Bezug und gemappte Laufwerke.
+- Dokumentieren, dass V2.0 **keinen** manuellen Verarbeitungslauf aus der GUI enthält.
+- Dokumentieren, dass die GUI in V2.0 der Konfiguration, Validierung und technischen Prüfung dient.
+- Terminologie zwischen README, JavaDoc, GUI-Texten und Startsemantik vereinheitlichen.
+
+### Explizit nicht Teil
+- neue Produktfunktionalität
+- vollständige Testergänzung
+- Release-Blocker-Befundliste
+- Freigabedokument
+
+### Fertig wenn
+- der V2.0-Betrieb für GUI und headless klar dokumentiert ist,
+- die Startoptionen widerspruchsfrei beschrieben sind,
+- die Dokumentation zum realen Verhalten des aktuellen Codes passt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Endbenutzer-Bedienanleitung der V2.0-GUI erstellen
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die V2.0-GUI erhält eine eigenständige, deskriptive Bedienanleitung, die dem Endbenutzer alle GUI-Funktionen, Zustände und Verhaltensweisen verständlich erklärt.
+
+### Muss umgesetzt werden
+- Eine neue Datei **`gui-bedienanleitung.md`** neben `betrieb.md` anlegen.
+- Der Inhalt ist **deskriptiv** (beschreibend), nicht als Schritt-für-Schritt-Tutorial.
+- Mindestens folgende Themen abdecken:
+  - Startzustände (GUI-Standardstart, Willkommenstext, Start mit `--config`),
+  - Aktionen: **Neu**, **Öffnen**, **Speichern**, **Speichern unter**, **Validieren**, **Technische Tests ausführen**, **Modelle neu laden**,
+  - Bedeutung der vier Meldungsstufen (Info, Hinweis, Warnung, Fehler),
+  - feldnahe Fehlermeldungen,
+  - Provider-Bedienung und Modellabruf,
+  - API-Key-Auflösungsreihenfolge mit Vorrang der Umgebungsvariable,
+  - Dirty-State und Schutzdialoge,
+  - `.bak`-Sicherung beim Überschreiben und Legacy-Migration,
+  - Windows-Hinweise zu gemappten Laufwerken,
+  - bekannte Einschränkungen: kein manueller Verarbeitungslauf in V2.0, keine Erkennung externer Änderungen an der `.properties`-Datei, keine Koordination mit parallelen headless Läufen.
+- Die Anleitung so schneiden, dass sie zum realen V2.0-Verhalten der GUI passt.
+- Terminologie zwischen Bedienanleitung, `betrieb.md`, GUI-Texten und Meilensteinbeschreibungen vereinheitlichen.
+
+### Explizit nicht Teil
+- Betriebsdokumentation (bleibt in `betrieb.md`)
+- technische Entwicklerdokumentation
+- Release-Befundliste
+- Freigabedokument
+
+### Fertig wenn
+- `gui-bedienanleitung.md` im Repository vorliegt,
+- alle definierten Themen deskriptiv abgedeckt sind,
+- die Terminologie mit `betrieb.md` und den GUI-Texten konsistent ist,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-003 Konfigurationsbeispiele, Standardvorlage und Prompt-Bezug für den V2.0-Endstand konsolidieren
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die im Repository enthaltenen Konfigurations- und Prompt-Beispiele passen konsistent zum realen V2.0-Verhalten der GUI und des headless Betriebs.
+
+### Muss umgesetzt werden
+- Vorhandene Konfigurationsbeispiele prüfen und auf den V2.0-Stand bringen.
+- Sicherstellen, dass mindestens nachvollziehbar und konsistent abgebildet sind:
+  - mehrere Provider-Konfigurationen in einer Datei,
+  - genau ein aktiver Provider,
+  - GUI-relevante und headless-relevante Konfigurationswerte,
+  - `prompt.template.file`,
+  - konservative Default-Werte,
+  - V2.0-relevante Grenz- und Warnparameter.
+- Die Standardvorlage für **„Neue Konfiguration“** und die dokumentierten Konfigurationsbeispiele semantisch aufeinander abstimmen.
+- Den Umgang mit automatisch erzeugbarer deutscher Standard-Prompt-Datei dokumentieren.
+- Sicherstellen, dass Dateinamen, Pfadbeispiele und Properties-Namen zum tatsächlichen Code passen.
+
+### Explizit nicht Teil
+- neue GUI-Funktionalität
+- größere Prompt-Überarbeitung jenseits des dokumentierten Standardfalls
+- Release-Befundliste
+- Freigabedokument
+
+### Fertig wenn
+- Konfigurationsbeispiele und Standardvorlage konsistent zum V2.0-Stand sind,
+- Prompt-Bezug und automatische Prompt-Erzeugung nachvollziehbar beschrieben sind,
+- Properties-Namen und Beispielwerte zum realen Code passen,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 Regressionstests für headless Abwärtskompatibilität, Startoptionen und Konfigurationspfade ergänzen
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Die kritischen V2.0-Risiken im bisherigen Server-/Scheduler-Betrieb werden automatisiert abgesichert.
+
+### Muss umgesetzt werden
+- Regressionstests für den headless Betrieb ergänzen oder vervollständigen, insbesondere für:
+  - headless Start ohne `--config` mit bestehendem Default-Verhalten,
+  - headless Start mit gültigem `--config`,
+  - headless Start mit ungültigem bzw. nicht vorhandenem `--config` als harter Startfehler,
+  - keine unzulässige Abhängigkeit von separater JavaFX-Installation im headless Pfad.
+- Tests für Parsing und Semantik von `--headless` und `--config` ergänzen.
+- Sicherstellen, dass bestehender Batch-/Scheduler-Betrieb durch V2.0 nicht still verändert wird.
+- Relevante Start- und Fehlermeldungssemantik mit absichern, soweit dies stabil automatisierbar ist.
+
+### Explizit nicht Teil
+- GUI-interaktive Bedienpfade
+- Release-Befundliste
+- Freigabedokument
+- neue Produktfunktionalität
+
+### Fertig wenn
+- die headless Abwärtskompatibilität belastbar automatisiert abgesichert ist,
+- Startoptionen und Konfigurationspfade regressionssicher geprüft werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 GUI-Smoke- und Interaktionstests für den V2.0-Kernumfang vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Die zentralen V2.0-GUI-Pfade sind automatisiert so abgesichert, dass Bedienung, Startzustände und wichtige Fehlersituationen regressionssicher werden.
+
+### Muss umgesetzt werden
+- GUI-nahe Tests für die zentralen V2.0-Bedienpfade ergänzen oder vervollständigen, insbesondere für:
+  - leerer GUI-Start ohne geladene Konfiguration,
+  - Willkommenstext und sichtbare Grundaktionen,
+  - `--config` im GUI-Start mit gültiger Datei,
+  - `--config` im GUI-Start mit nicht vorhandener Datei inklusive Fehlermeldung und Fallback auf leeren GUI-Zustand,
+  - Dirty-State-Kennzeichnung,
+  - Schutzdialoge bei ungespeicherten Änderungen,
+  - Arbeiten von **„Validieren“** und **„Technische Tests ausführen“** auf dem aktuellen Editorzustand.
+- Soweit stabil automatisierbar, auch zentrale Meldungs- und Validierungsflüsse mit absichern.
+- Sicherstellen, dass die Tests den echten V2.0-Kernumfang prüfen und keine späteren GUI-Ausbaustufen vorwegnehmen.
+
+### Explizit nicht Teil
+- DB-/Historienansicht
+- manueller Verarbeitungslauf
+- Release-Befundliste
+- Freigabedokument
+
+### Fertig wenn
+- die zentralen V2.0-GUI-Pfade automatisiert abgesichert sind,
+- GUI-Start, Fallback-Verhalten und Schutzdialoge regressionssicher geprüft werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-006 Build-, Packaging- und Artefaktdokumentation für das gemeinsame V2.0-JAR vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Das gemeinsame ausführbare JAR für GUI und headless ist nachvollziehbar beschrieben und sein Build-/Packaging-Verhalten ist für die Übergabe ausreichend dokumentiert.
+
+### Muss umgesetzt werden
+- Dokumentation für Build und Packaging des gemeinsamen V2.0-JAR ergänzen oder schärfen.
+- Mindestens folgende Punkte nachvollziehbar beschreiben:
+  - gemeinsames ausführbares JAR,
+  - integrierte JavaFX-Laufzeit im GUI-Fall,
+  - keine EXE und kein Installer in V2.0,
+  - headless Start ohne separate JavaFX-Installation,
+  - relevante Build-Kommandos,
+  - Artefakterzeugung und Startbeispiele.
+- Prüfen, ob bestehende Packaging-/Build-Hinweise oder Konfigurationsbeispiele widersprüchlich oder veraltet sind, und diese gezielt bereinigen.
+- Nur dann produktiven Build-Code anfassen, wenn für eine korrekte V2.0-Dokumentation ein nachweisbarer Widerspruch zum realen Packaging-Verhalten besteht.
+
+### Explizit nicht Teil
+- neue Distributionsformate
+- EXE oder Installer
+- Release-Befundliste
+- Freigabedokument
+
+### Fertig wenn
+- Build- und Packaging-Verhalten des gemeinsamen JAR nachvollziehbar dokumentiert ist,
+- veraltete oder widersprüchliche Angaben bereinigt sind,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-007 Integrierte Gesamtprüfung des V2.0-Stands und belastbare Befundliste erstellen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Der V2.0-Gesamtstand wird ganzheitlich geprüft, und es entsteht eine belastbare Befundliste, aus der ausschließlich reale Release-Blocker ableitbar sind.
+
+### Muss umgesetzt werden
+- Den vollständigen V2.0-Projektstand ganzheitlich gegen die bestehenden Spezifikationen, den V1.1-Ist-Stand und `meilensteine-v2_0.md` prüfen.
+- Tatsächlich ausführen und auswerten:
+  - vollständigen Maven-Reactor-Build,
+  - relevante Test-Suiten,
+  - headless Smoke-/Regressionstests,
+  - GUI-nahe Smoke-/Interaktionstests, soweit im Projekt vorhanden,
+  - Prüfung der Konfigurations- und Dokumentationsbeispiele.
+- Die Ergebnisse als neuen V2.0-Abschnitt in der bestehenden **`befundliste.md`** dokumentieren.
+- Befunde klar klassifizieren, insbesondere in:
+  - Release-Blocker,
+  - nicht blockierende Restpunkte,
+  - bewusst außerhalb von V2.0 liegende Themen.
+- Sicherstellen, dass nur **konkret nachgewiesene** Release-Blocker für das Folge-Arbeitspaket in Betracht kommen.
+
+### Explizit nicht Teil
+- Behebung der gefundenen Blocker
+- neue Produktfunktionalität
+- finale Freigabedokumentation
+
+### Fertig wenn
+- die integrierte Gesamtprüfung real durchgeführt und dokumentiert wurde,
+- eine belastbare Befundliste im Repository vorliegt,
+- Release-Blocker klar und eng eingegrenzt sind,
+- der Stand weiterhin fehlerfrei buildbar bleibt.
+
+---
+
+## AP-008 Nachgewiesene V2.0-Release-Blocker gezielt beheben
+
+### Voraussetzung
+AP-007 ist abgeschlossen.
+
+### Ziel
+Die im vorherigen Arbeitspaket konkret dokumentierten Release-Blocker werden gezielt und ohne Scope-Ausweitung beseitigt.
+
+### Muss umgesetzt werden
+- Ausschließlich die in der Befundliste aus AP-007 dokumentierten **Release-Blocker** beheben.
+- Änderungen strikt auf die tatsächlich nachgewiesenen Blocker begrenzen.
+- Betroffene Tests, Dokumentation und Konfigurationsbeispiele mitziehen, soweit dies zur sauberen Behebung erforderlich ist.
+- Sicherstellen, dass durch die Behebung keine Themen späterer Ausbaustufen still vorweggenommen werden.
+- Den relevanten Build-/Testumfang erneut ausführen und grün bekommen.
+
+### Explizit nicht Teil
+- Behebung nicht blockierender Restpunkte
+- neue Features
+- finaler Freigabenachweis
+
+### Fertig wenn
+- die dokumentierten Release-Blocker gezielt behoben sind,
+- die relevanten Builds und Tests erneut erfolgreich laufen,
+- keine Scope-Ausweitung auf spätere Ausbaustufen stattgefunden hat,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.
+
+---
+
+## AP-009 Finale V2.0-Gesamtprüfung und Freigabedokumentation erstellen
+
+### Voraussetzung
+AP-008 ist abgeschlossen.
+
+### Ziel
+Der V2.0-Gesamtstand wird abschließend geprüft und als freigabefähiger Stand nachvollziehbar dokumentiert.
+
+### Muss umgesetzt werden
+- Die integrierte Gesamtprüfung nach den Blockerbehebungen erneut durchführen.
+- Tatsächlich ausführen und bewerten:
+  - vollständigen Maven-Reactor-Build,
+  - maßgebliche Test-Suiten,
+  - headless Smoke-/Regressionstests,
+  - GUI-nahe Smoke-/Interaktionstests,
+  - Konfigurations- und Dokumentationsbeispielprüfung.
+- Endbenutzer-Bedienanleitung (`gui-bedienanleitung.md`) auf Vollständigkeit, Konsistenz mit `betrieb.md` und Übereinstimmung mit dem realen GUI-Verhalten prüfen.
+- Eine im Repository verbleibende **Freigabedokumentation** erstellen, die mindestens festhält:
+  - geprüften Stand,
+  - ausgeführte Prüfungen,
+  - Build-/Test-Ergebnisse,
+  - offene nicht blockierende Restpunkte,
+  - klare Freigabeaussage für V2.0.
+- Sicherstellen, dass die Freigabedokumentation keine Aussagen trifft, die nicht durch reale Prüfungen gedeckt sind.
+
+### Explizit nicht Teil
+- neue Produktfunktionalität
+- weitere Qualitätskampagnen jenseits des V2.0-Abschlusses
+- spätere Ausbaustufen V2.1+
+
+### Fertig wenn
+- der V2.0-Gesamtstand erneut vollständig geprüft wurde,
+- eine belastbare Freigabedokumentation im Repository vorliegt,
+- der V2.0-Stand als freigabefähig nachvollziehbar beschrieben ist,
+- ein fehlerfreier, übergabefähiger Abschlussstand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M13 – V2.0-Abschluss, Dokumentation und Qualitätsnachweis** zugeschnitten. Sie decken den vollständigen Zielumfang dieses Abschlussmeilensteins ab, ohne spätere Ausbaustufen vorwegzunehmen.
@@ -0,0 +1,361 @@
+# M14 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein
+**M14 – Windows-EXE-Packaging (V2.5)**.
+
+Der dokumentierte und freigegebene Stand **V2.0** (Commit `1bb7a427357c73039c09a8e1bfe351dee54df765`)
+wird als vollständig umgesetzt und freigegeben vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+---
+
+## Zielbild von M14
+
+Nach Abschluss von M14 existiert neben dem bestehenden Shade-JAR ein zweites
+Distributionsartefakt: eine **native Windows-EXE**, die alle notwendigen Laufzeitkomponenten
+enthält und auf einem frischen Windows 10 (x64) oder Windows Server 2022 (x64) ohne
+vorinstalliertes Java oder sonstige Laufzeitumgebungen ausführbar ist.
+
+Die EXE wird ausschließlich **lokal auf der Windows-Entwicklungsmaschine** gebaut,
+gesteuert über das Maven-Profil `-P release`. Jenkins bleibt für den normalen
+JAR-Build zuständig und ist von M14 nicht betroffen.
+
+---
+
+## Abgrenzungen
+
+### Explizit nicht Bestandteil von M14
+
+- Windows-Installer (MSI, NSIS, Inno Setup o. Ä.) → V3.0
+- Code-Signing der EXE → kein kostenfreier Weg für Deutschland verfügbar
+- Cross-Compilation für andere Betriebssysteme
+- Änderungen an fachlicher Benennungslogik, Statussemantik, Retry-Regeln oder Persistenz
+- Änderungen an der GUI oder am headless Batch-Betrieb
+- Neue Tests für die EXE (manueller Smoke-Test durch den Entwickler)
+- Jenkins-Integration des EXE-Builds
+
+### Unveränderte Leitplanken
+
+- Java 21
+- Maven Multi-Module
+- Hexagonale Architektur bleibt unberührt
+- Das Shade-JAR bleibt das primäre Distributionsartefakt (Änderung in `betrieb.md` erforderlich)
+- Der normale Build (`mvn verify`) bleibt unverändert und erfordert kein WiX Toolset
+
+---
+
+## Verbindliche M14-Regeln für alle Arbeitspakete
+
+### 1. Neues Maven-Modul
+
+Das EXE-Packaging wird in einem eigenen Modul `pdf-umbenenner-packaging` gekapselt.
+Dieses Modul hat genau eine Abhängigkeit: `pdf-umbenenner-bootstrap`.
+
+### 2. Maven-Profil `release`
+
+Das Profil `release` aktiviert ausschließlich den EXE-Build via `jpackage`.
+Der normale Build (`mvn clean verify`) bleibt vom Profil vollständig unberührt.
+WiX Toolset wird nur im Profil `release` benötigt.
+
+### 3. Keine Modifikation bestehender Module
+
+Bestehende Module (`domain`, `application`, `adapter-in-cli`, `adapter-in-gui`,
+`adapter-out`, `bootstrap`) werden in M14 **nicht** verändert – weder POM noch
+Produktions- noch Testcode.
+
+### 4. Batch-Dateien
+
+Die zwei Batch-Dateien landen als Ressourcen im Modul `pdf-umbenenner-packaging`
+und werden durch das `jpackage`-Plugin in das EXE-Ausgabeverzeichnis kopiert.
+
+| Dateiname | Funktion |
+|---|---|
+| `PDF-KI-Renamer.bat` | Headless-Modus (`--headless`) |
+| `PDF-KI-Renamer-GUI.bat` | GUI-Modus (kein Argument) |
+
+### 5. Dokumentation
+
+`betrieb.md` wird am Ende von M14 aktualisiert: Der Abschnitt „Keine EXE, kein Installer"
+wird durch eine korrekte Beschreibung des V2.5-Distributionsartefakts ersetzt.
+
+---
+
+## AP-001 Neues Maven-Modul `pdf-umbenenner-packaging` anlegen
+
+### Voraussetzung
+Kein. Dieses Arbeitspaket ist der M14-Startpunkt.
+
+### Ziel
+Die Projektstruktur wird um das Packaging-Modul erweitert, ohne den bestehenden Build zu berühren.
+
+### Muss umgesetzt werden
+- Modul `pdf-umbenenner-packaging` anlegen mit minimaler POM-Struktur.
+- Modul in Parent-POM (`<modules>`) und Reactor aufnehmen.
+- Abhängigkeit auf `pdf-umbenenner-bootstrap` (scope `runtime`) deklarieren.
+- Das Modul erzeugt im Normalbuild (`mvn clean verify`) **kein** zusätzliches Artefakt.
+- Keine Produktionsklassen, keine Tests – das Modul enthält ausschließlich
+  Maven-Konfiguration und Ressourcen.
+- `package-info.java` entfällt (kein Java-Code im Modul).
+
+### Explizit nicht Teil
+- Plugin-Konfiguration für jpackage
+- Maven-Profil `release`
+- Batch-Dateien
+- Icon
+
+### Fertig wenn
+- das neue Modul im Reactor vorhanden ist,
+- `mvn clean verify` (ohne Profil) weiterhin fehlerfrei durchläuft,
+- keine bestehenden Module verändert wurden.
+
+---
+
+## AP-002 Ressourcen bereitstellen (Icon und Batch-Dateien)
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Icon und Batch-Dateien liegen als versionierte Ressourcen im Modul bereit.
+
+### Muss umgesetzt werden
+
+**Icon:**
+- Platzhalter-Icon `src/main/packaging/icon.ico` anlegen.
+- Das Icon ist ein valides `.ico`-Format (1×1 Pixel genügt als Platzhalter).
+- Kommentar in der Datei oder einer begleitenden `README-icon.md`:
+  „Platzhalter – vor dem Release durch echtes Icon ersetzen."
+
+**Batch-Dateien** unter `src/main/packaging/`:
+
+`PDF-KI-Renamer.bat`:
+```bat
+@echo off
+"%~dp0PDF-KI-Renamer\PDF-KI-Renamer.exe" --headless %*
+```
+
+`PDF-KI-Renamer-GUI.bat`:
+```bat
+@echo off
+"%~dp0PDF-KI-Renamer\PDF-KI-Renamer.exe" %*
+```
+
+- `%~dp0` stellt sicher, dass die EXE relativ zur Batch-Datei gefunden wird,
+  unabhängig vom aktuellen Arbeitsverzeichnis.
+- `%*` leitet alle weiteren Argumente (z. B. `--config`) durch.
+- Pfade mit Leerzeichen (z. B. `C:\Program Files\...`) sind durch die Anführungszeichen korrekt gequotet.
+
+### Explizit nicht Teil
+- Plugin-Konfiguration
+- Kopieren der Batch-Dateien in das Ausgabeverzeichnis (folgt in AP-003)
+
+### Fertig wenn
+- Icon und beide Batch-Dateien unter `src/main/packaging/` vorhanden sind,
+- `mvn clean verify` weiterhin fehlerfrei durchläuft.
+
+---
+
+## AP-003 Maven-Profil `release` mit jpackage konfigurieren
+
+### Voraussetzung
+AP-002 ist abgeschlossen.
+
+### Ziel
+`mvn clean package -P release` erzeugt auf der Windows-Entwicklungsmaschine
+(mit WiX Toolset im PATH) eine lauffähige Windows-EXE unter
+`pdf-umbenenner-packaging/target/dist/`.
+
+### Technischer Hintergrund
+
+Das Projekt verwendet ein **nicht-modulares Fat-JAR** (Shade-Plugin, kein JPMS).
+JavaFX-DLLs sind bereits im Shade-JAR enthalten (Windows-Classifier).
+Die Main-Class erweitert bewusst nicht `javafx.application.Application`
+(JavaFX-Launcher-Check-Workaround, dokumentiert in `betrieb.md`).
+
+jpackage benötigt:
+1. Das Shade-JAR als Eingabe (`--input` + `--main-jar`)
+2. Eine minimale JRE (erzeugt via `jlink` oder automatisch durch jpackage)
+3. WiX Toolset im PATH (für `--type exe`)
+
+Da das Projekt nicht modular ist, muss jpackage mit `--add-modules ALL-MODULE-PATH`
+oder einer expliziten Modulliste arbeiten. Die explizite Modulliste ist
+wartungsfreundlicher und wird bevorzugt.
+
+### Muss umgesetzt werden
+
+**Maven-Profil `release`** in der POM von `pdf-umbenenner-packaging`:
+
+```xml
+<profile>
+  <id>release</id>
+  <build>
+    <plugins>
+      <!-- Shade-JAR aus Bootstrap-Modul ins Packaging-Verzeichnis kopieren -->
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-dependency-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>copy-shade-jar</id>
+            <phase>package</phase>
+            <goals><goal>copy-dependencies</goal></goals>
+            <configuration>
+              <includeArtifactIds>pdf-umbenenner-bootstrap</includeArtifactIds>
+              <outputDirectory>${project.build.directory}/jpackage-input</outputDirectory>
+              <stripVersion>false</stripVersion>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+
+      <!-- jpackage -->
+      <plugin>
+        <groupId>org.panteleyev</groupId>
+        <artifactId>jpackage-maven-plugin</artifactId>
+        <version>1.6.0</version>
+        <executions>
+          <execution>
+            <id>create-exe</id>
+            <phase>package</phase>
+            <goals><goal>jpackage</goal></goals>
+            <configuration>
+              <type>EXE</type>
+              <name>PDF-KI-Renamer</name>
+              <appVersion>${project.version}</appVersion>
+              <vendor>gecheckt.de</vendor>
+              <input>${project.build.directory}/jpackage-input</input>
+              <mainJar>pdf-umbenenner-bootstrap-${project.version}.jar</mainJar>
+              <mainClass>de.gecheckt.pdf.umbenenner.bootstrap.PdfUmbenennerApplication</mainClass>
+              <destination>${project.build.directory}/dist</destination>
+              <icon>${project.basedir}/src/main/packaging/icon.ico</icon>
+              <addModules>
+                java.base,java.desktop,java.logging,java.naming,java.net.http,
+                java.sql,java.xml,jdk.unsupported
+              </addModules>
+              <javaOptions>
+                <javaOption>-Xms64m</javaOption>
+                <javaOption>-Xmx512m</javaOption>
+              </javaOptions>
+              <winConsole>false</winConsole>
+              <winShortcut>false</winShortcut>
+              <winMenu>false</winMenu>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+
+      <!-- Batch-Dateien ins dist-Verzeichnis kopieren -->
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>copy-batch-files</id>
+            <phase>package</phase>
+            <goals><goal>copy-resources</goal></goals>
+            <configuration>
+              <outputDirectory>${project.build.directory}/dist</outputDirectory>
+              <resources>
+                <resource>
+                  <directory>src/main/packaging</directory>
+                  <includes>
+                    <include>*.bat</include>
+                  </includes>
+                </resource>
+              </resources>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</profile>
+```
+
+**Wichtige Hinweise für Claude Code:**
+- Die Modulliste (`addModules`) ist ein Ausgangspunkt. Der tatsächliche Bedarf
+  kann per `jdeps --print-module-deps` auf dem Shade-JAR ermittelt werden.
+  Claude Code soll `jdeps` ausführen und die Modulliste anpassen.
+- `winConsole=false` sorgt dafür, dass kein CMD-Fenster beim GUI-Start erscheint.
+  Für den headless-Start via Batch ist das akzeptabel (Ausgabe geht in Log-Dateien).
+- Die Plugin-Version `1.6.0` von `org.panteleyev:jpackage-maven-plugin` ist
+  zu verifizieren – aktuelle Version per Maven Central prüfen.
+- Das `jpackage`-Plugin muss in `pluginManagement` im Parent-POM oder direkt
+  in der Packaging-POM versioniert sein.
+
+### Explizit nicht Teil
+- Anpassung von `betrieb.md` (folgt in AP-004)
+- Manuelle Ausführung oder Smoke-Test
+
+### Fertig wenn
+- `mvn clean verify` (ohne Profil) weiterhin fehlerfrei durchläuft,
+- die POM-Konfiguration syntaktisch korrekt und vollständig ist,
+- `jdeps` auf dem Shade-JAR ausgeführt wurde und die Modulliste korrekt befüllt ist.
+
+---
+
+## AP-004 Dokumentation aktualisieren
+
+### Voraussetzung
+AP-003 ist abgeschlossen.
+
+### Ziel
+Die Projektdokumentation spiegelt den V2.5-Stand korrekt wider.
+
+### Muss umgesetzt werden
+
+**`betrieb.md` – Abschnitt „Keine EXE, kein Installer" ersetzen durch:**
+
+```markdown
+### Windows-EXE (V2.5)
+
+Ab V2.5 steht neben dem Shade-JAR ein zweites Distributionsartefakt bereit:
+eine **native Windows-EXE** für Windows 10/11 (x64) und Windows Server 2022 (x64).
+
+Die EXE enthält eine eingebettete JRE 21 und benötigt keine separate Java-Installation
+auf dem Zielsystem.
+
+**Voraussetzungen für den EXE-Build (nur auf der Entwicklungsmaschine):**
+- Windows x64
+- JDK 21 im PATH
+- [WiX Toolset 3.x](https://wixtoolset.org/) im PATH
+
+**EXE bauen:**
+```powershell
+.\mvnw.cmd clean package -P release -pl pdf-umbenenner-packaging --also-make -DskipTests
+```
+
+Das Ergebnis liegt unter:
+```
+pdf-umbenenner-packaging/target/dist/
+  PDF-KI-Renamer/          ← Anwendungsverzeichnis mit EXE und eingebetteter JRE
+  PDF-KI-Renamer.bat       ← Headless-Start
+  PDF-KI-Renamer-GUI.bat   ← GUI-Start
+```
+
+**Hinweis:** Die EXE ist nicht signiert. Beim ersten Start auf einem neuen System
+erscheint eine Windows-SmartScreen-Warnung, die durch „Weitere Informationen → Trotzdem ausführen"
+bestätigt werden muss.
+```
+
+**`betrieb.md` – Abschnitt „Voraussetzungen" aktualisieren:**
+- Java 21 ist für Endnutzer der EXE **nicht** mehr erforderlich (eingebettet).
+- Hinweis ergänzen: „Bei Verwendung des Shade-JAR direkt: Java 21 JRE erforderlich."
+
+**`CLAUDE.md` aktualisieren** (falls vorhanden):
+- Hinweis auf Profil `release` und WiX-Abhängigkeit ergänzen.
+- Build-Kommando für EXE dokumentieren.
+
+### Fertig wenn
+- `betrieb.md` den neuen Abschnitt enthält,
+- die Voraussetzungen korrekt aktualisiert sind,
+- `mvn clean verify` weiterhin fehlerfrei durchläuft.
@@ -0,0 +1,216 @@
+# M15 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein
+**M15 – MSI-Installer (V3.0)**.
+
+Der Stand **V2.5** (M14 abgeschlossen) wird als vollständig umgesetzt vorausgesetzt:
+- Modul `pdf-umbenenner-packaging` existiert
+- Maven-Profil `release` ist konfiguriert
+- `icon.ico`, `PDF-KI-Renamer.bat`, `PDF-KI-Renamer-GUI.bat` liegen unter
+  `pdf-umbenenner-packaging/src/main/packaging/`
+
+Die Arbeitspakete sind so geschnitten, dass Opus 4.7 sie in einem Durchgang
+vollständig umsetzen kann. Nach jedem Arbeitspaket muss `mvn clean verify`
+(ohne Profil) fehlerfrei durchlaufen.
+
+---
+
+## Zielbild von M15
+
+Nach Abschluss von M15 erzeugt `mvn clean package -P release` einen vollständigen
+**MSI-Installer** (`PDF-KI-Renamer-2.5.0.msi`) der:
+
+- die Anwendung nach `C:\Program Files\PDF KI Renamer\` installiert,
+- eine Beispiel-Konfiguration nach
+  `C:\ProgramData\PDF KI Renamer\config\application.example.properties` ablegt,
+- beide Batch-Dateien ins Installationsverzeichnis legt,
+- einen Startmenü-Eintrag für den GUI-Start erstellt,
+- einen Desktop-Shortcut erstellt,
+- über „Programme und Features" sauber deinstallierbar ist.
+
+---
+
+## Abgrenzungen
+
+### Explizit nicht Bestandteil von M15
+
+- Automatische Konfigurationsauflösung aus `ProgramData` (bleibt `--config`-Sache)
+- Code-Signing des MSI
+- Upgrade-Logik (MajorUpgrade, automatisches Deinstallieren alter Versionen)
+- Änderungen an fachlicher Logik, GUI, headless-Betrieb oder Persistenz
+- Neue Tests
+
+### Unveränderte Leitplanken
+
+- `--type MSI` ersetzt `--type EXE` im Profil `release`
+- Der Normalbuild (`mvn clean verify`) bleibt unverändert
+- Bestehende Module außer `pdf-umbenenner-packaging` werden nicht angefasst
+
+---
+
+## Verbindliche M15-Regeln
+
+### 1. Installationsverzeichnis
+`C:\Program Files\PDF KI Renamer\`
+
+### 2. Konfigurationsverzeichnis
+`C:\ProgramData\PDF KI Renamer\config\`
+
+Die Beispiel-Config wird aus `docs/examples/application.properties` des Projekts
+in dieses Verzeichnis kopiert und als `application.example.properties` abgelegt.
+
+### 3. Batch-Dateien
+Beide Batch-Dateien landen im Installationsverzeichnis.
+Die Pfade in den Batch-Dateien müssen auf das Installationsverzeichnis angepasst werden
+(nicht mehr relativ per `%~dp0`, sondern absolut via Installationspfad-Variable oder
+weiterhin relativ – beides ist akzeptabel solange es funktioniert).
+
+### 4. Startmenü & Desktop
+- Startmenü-Gruppe: `PDF KI Renamer`
+- Startmenü-Eintrag: `PDF KI Renamer` → startet GUI
+- Desktop-Shortcut: `PDF KI Renamer` → startet GUI
+
+### 5. Deinstallation
+Saubere Deinstallation über „Programme und Features". Vom Installer angelegte
+Dateien werden entfernt. Nutzerdaten in `ProgramData` (Konfiguration, Logs, DB)
+werden **nicht** gelöscht.
+
+---
+
+## AP-001 MSI-Typ und Installer-Ressourcen vorbereiten
+
+### Voraussetzung
+M14 ist abgeschlossen. `mvn clean verify` ist grün.
+
+### Ziel
+Das Profil `release` erzeugt einen MSI statt einer EXE,
+und alle notwendigen Installer-Ressourcen liegen bereit.
+
+### Muss umgesetzt werden
+
+1. In `pdf-umbenenner-packaging/pom.xml` im Profil `release`:
+   - `<type>EXE</type>` → `<type>MSI</type>`
+   - Folgende Windows-spezifische jpackage-Optionen ergänzen:
+     ```xml
+     <winShortcut>true</winShortcut>
+     <winMenu>true</winMenu>
+     <winMenuGroup>PDF KI Renamer</winMenuGroup>
+     <winDirChooser>true</winDirChooser>
+     <winShortcutPrompt>false</winShortcutPrompt>
+     <installDir>PDF KI Renamer</installDir>
+     ```
+
+2. Beispiel-Konfiguration als Installer-Ressource bereitstellen:
+   - `docs/examples/application.properties` nach
+     `pdf-umbenenner-packaging/src/main/packaging/application.example.properties`
+     kopieren (als versionierte Kopie im Modul – nicht das Original verschieben).
+
+3. `mvn clean verify` muss weiterhin grün bleiben.
+
+### Fertig wenn
+- `<type>MSI</type>` in der POM gesetzt
+- Windows-Optionen konfiguriert
+- `application.example.properties` unter `src/main/packaging/` vorhanden
+- `mvn clean verify` grün
+
+---
+
+## AP-002 ProgramData-Verzeichnis und Beispiel-Config im Installer verankern
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Der MSI-Installer legt beim Installieren die Beispiel-Config unter
+`C:\ProgramData\PDF KI Renamer\config\application.example.properties` ab.
+
+### Technischer Hintergrund
+
+jpackage unterstützt `--app-content` zum Hinzufügen zusätzlicher Dateien
+in das Anwendungs-Image. Diese landen jedoch im Installationsverzeichnis,
+nicht in `ProgramData`.
+
+Für `ProgramData` gibt es zwei Wege:
+- **Weg A**: jpackage `--resource-dir` mit WiX-Override (komplex, fehleranfällig)
+- **Weg B**: Die Beispiel-Config über `--app-content` ins Installationsverzeichnis
+  legen und in der Dokumentation beschreiben, dass der Nutzer sie nach
+  `ProgramData` kopieren soll (einfach, robust)
+
+**Verbindlich für M15: Weg B.**
+
+### Muss umgesetzt werden
+
+1. `application.example.properties` via `--app-content` in das
+   Anwendungsverzeichnis einbinden:
+   ```xml
+   <appContent>
+     <appContent>src/main/packaging/application.example.properties</appContent>
+   </appContent>
+   ```
+
+2. `mvn clean verify` muss weiterhin grün bleiben.
+
+### Fertig wenn
+- `application.example.properties` ist in der jpackage-Konfiguration als
+  `appContent` eingebunden
+- `mvn clean verify` grün
+
+---
+
+## AP-003 Desktop-Shortcut konfigurieren
+
+### Voraussetzung
+AP-002 ist abgeschlossen.
+
+### Ziel
+Der Installer erstellt zusätzlich einen Desktop-Shortcut.
+
+### Technischer Hintergrund
+
+jpackage unterstützt Desktop-Shortcuts über `--win-shortcut`.
+`<winShortcut>true</winShortcut>` ist bereits in AP-001 gesetzt –
+das erzeugt jedoch primär einen Startmenü-Eintrag.
+
+Für einen **Desktop**-Shortcut ist ein zusätzlicher WiX-Override nötig.
+Prüfe zunächst ob `<winShortcut>true</winShortcut>` in Kombination mit
+`<winShortcutPrompt>false</winShortcutPrompt>` bereits einen Desktop-Shortcut erzeugt.
+Falls nicht, dokumentiere dies als bekannte Einschränkung in `betrieb.md`
+und überspringe den WiX-Override (zu komplex für M15).
+
+### Fertig wenn
+- Entweder Desktop-Shortcut funktioniert, oder
+- die Einschränkung ist in `betrieb.md` dokumentiert
+- `mvn clean verify` grün
+
+---
+
+## AP-004 Dokumentation aktualisieren
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Die Projektdokumentation spiegelt den V3.0-Stand korrekt wider.
+
+### Muss umgesetzt werden
+
+1. `docs/betrieb.md` – Abschnitt „Windows-EXE (V2.5)" erweitern zu
+   „Windows-Installer (V3.0)":
+   - MSI-Build-Kommando dokumentieren
+   - Installationsverzeichnis dokumentieren
+   - Hinweis: Beispiel-Config liegt nach Installation im Installationsverzeichnis,
+     muss manuell nach `C:\ProgramData\PDF KI Renamer\config\` kopiert und
+     angepasst werden
+   - Hinweis auf SmartScreen-Warnung (kein Code-Signing)
+   - Headless-Betrieb: Beispiel-Aufruf mit `--config`
+
+2. `CLAUDE.md` aktualisieren:
+   - Build-Kommando für MSI ergänzen
+
+### Fertig wenn
+- `betrieb.md` vollständig aktualisiert
+- `CLAUDE.md` aktualisiert
+- `mvn clean verify` grün
+- M15 vollständig abgeschlossen
@@ -0,0 +1,516 @@
+# M4 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M4 – Fingerprint, SQLite-Persistenz und Idempotenz**.
+
+Die Meilensteine **M1**, **M2** und **M3** werden als vollständig umgesetzt vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter und Bootstrap ändern.
+- Keine Annahmen treffen, die nicht durch dieses Dokument oder die verbindlichen Spezifikationen gedeckt sind.
+- Kein Vorgriff auf **M5+**.
+- Kein Umbau bestehender M1–M3-Strukturen ohne direkten M4-Bezug.
+- Neue Typen, Ports und Adapter so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus **klar benennbar, testbar und reviewbar** sind.
+
+## Explizit nicht Bestandteil von M4
+
+- KI-Anbindung
+- Prompt-Laden oder Prompt-Verarbeitung
+- Validierung von KI-Antworten
+- Dateinamensbildung
+- Zielkopie in den Zielordner
+- Windows-Zeichenbereinigung für Zieldateinamen
+- physische Dublettenbehandlung im Zielordner
+- M5+-Persistenzfelder wie Modellname, Prompt-Identifikator, KI-Rohantwort, KI-Reasoning, Datumsquelle, finaler Titel oder finaler Zieldateiname
+- vollständige laufübergreifende Retry-Logik späterer Meilensteine für KI- und Zielkopie-Fehler
+- Logging-Feinschliff des Endstands
+
+## Verbindliche M4-Regeln für **alle** Arbeitspakete
+
+### 1. Identifikation
+- Die Identifikation eines Dokuments erfolgt in M4 **ausschließlich über den SHA-256-Fingerprint des Dateiinhalts**.
+- Dateiname und Pfad dienen **nicht** als Identifikator.
+- Gleicher Inhalt unter anderem Dateinamen oder anderem Pfad ist **dasselbe Dokument**.
+- Geänderter Inhalt ist **ein neuer fachlicher Vorgang**.
+
+### 2. Persistenzmodell
+M4 führt die Persistenz verbindlich in **zwei Ebenen**:
+
+1. **Dokument-Stammsatz** pro Fingerprint
+2. **Versuchshistorie** mit einem Datensatz pro historisiertem dokumentbezogenem Verarbeitungsversuch
+
+### 3. Minimale Pflichtdaten im Dokument-Stammsatz für M4
+Im Dokument-Stammsatz müssen in M4 mindestens speicherbar sein:
+
+- interne ID
+- Fingerprint
+- letzter bekannter Quellpfad
+- letzter bekannter Quelldateiname
+- aktueller Gesamtstatus
+- Anzahl bisheriger Inhaltsfehler
+- Anzahl bisheriger transienter Fehler
+- letzter Fehlerzeitpunkt
+- letzter Erfolgzeitpunkt
+- Erstellungszeitpunkt
+- Änderungszeitpunkt
+
+**Nicht** Bestandteil von M4-Stammsatzfeldern sind Zielpfad, Zieldateiname oder KI-bezogene Felder.
+
+### 4. Minimale Pflichtdaten der Versuchshistorie für M4
+Für jeden in M4 zu historisierenden Versuch müssen mindestens speicherbar sein:
+
+- Versuchs-ID
+- Fingerprint-Referenz
+- Lauf-ID
+- Versuchsnummer
+- Startzeitpunkt
+- Endzeitpunkt
+- Ergebnisstatus
+- Fehlerklasse
+- Fehlermeldung bzw. Begründung
+- Retryable-Flag
+
+### 5. Statusmodell für M4
+Für M4 müssen folgende Statuswerte fachlich klar verwendbar sein:
+
+- `SUCCESS`
+- `FAILED_RETRYABLE`
+- `FAILED_FINAL`
+- `SKIPPED_ALREADY_PROCESSED`
+- `SKIPPED_FINAL_FAILURE`
+
+Ein technischer Zwischenstatus `PROCESSING` ist zusätzlich zulässig, aber für M4 nicht verpflichtend.
+
+### 6. Verbindliche M4-Minimalregeln für Status und Zähler
+Für M4 gelten **genau** diese Minimalregeln:
+
+- Bereits erfolgreich verarbeitete Dokumente werden in späteren Läufen übersprungen.
+- Bereits final fehlgeschlagene Dokumente werden in späteren Läufen übersprungen.
+- Ein **deterministischer Inhaltsfehler aus M3**  
+  - beim **ersten** historisierten Auftreten führt zu `FAILED_RETRYABLE`, erhöht den **Inhaltsfehlerzähler** auf 1 und setzt `retryable = true`,
+  - beim **zweiten** historisierten Auftreten in einem späteren Lauf führt zu `FAILED_FINAL`, erhöht den **Inhaltsfehlerzähler** auf 2 und setzt `retryable = false`.
+- In M4 sind die deterministischen Inhaltsfehler ausschließlich die bereits aus M3 bekannten Fälle:
+  - kein brauchbarer Text
+  - Seitenlimit überschritten
+- Dokumentbezogene **technische** Fehler nach erfolgreicher Fingerprint-Ermittlung bleiben in M4 `FAILED_RETRYABLE`, erhöhen den **Transientfehlerzähler** und setzen `retryable = true`.
+- Skip-Ereignisse ändern **keinen** Fehlerzähler.
+
+### 7. Historisierung in M4
+- Jeder **identifizierte** dokumentbezogene Verarbeitungsversuch wird separat historisiert.
+- Die Versuchsnummer beginnt pro Fingerprint bei **1** und steigt pro historisiertem Versuch monoton um **1**.
+- Auch Skip-Fälle werden historisiert:
+  - `SKIPPED_ALREADY_PROCESSED`
+  - `SKIPPED_FINAL_FAILURE`
+- Ein in M4 historisierter Versuch setzt einen **erfolgreich ermittelten Fingerprint** voraus.
+- Technische Fehler **vor** erfolgreicher Fingerprint-Ermittlung sind in M4 **keine** SQLite-historisierten Versuche; sie werden nur kontrolliert als dokumentbezogene Laufereignisse behandelt.
+
+### 8. Reihenfolge pro Dokument in M4
+Die Verarbeitung eines einzelnen Kandidaten erfolgt in M4 verbindlich in dieser Reihenfolge:
+
+1. Fingerprint berechnen
+2. Dokument-Stammsatz laden
+3. bei `SUCCESS` Skip-Entscheidung treffen und Skip-Versuch historisieren
+4. bei `FAILED_FINAL` Skip-Entscheidung treffen und Skip-Versuch historisieren
+5. sonst bestehenden M3-Ablauf ausführen
+6. M3-Ergebnis in M4-Status, Zähler und Retryable-Flag überführen
+7. Versuch historisieren
+8. Dokument-Stammsatz fortschreiben
+
+### 9. Konsistenz pro identifiziertem Dokument
+- Für jeden identifizierten dokumentbezogenen Versuch müssen **Versuchshistorie und Stammsatz konsistent** fortgeschrieben werden.
+- Teilaktualisierungen zwischen Historie und Stammsatz sind zu vermeiden.
+- Wenn die Persistenz eines dokumentbezogenen Versuchs technisch scheitert, darf **kein inkonsistenter Teilzustand** zurückbleiben.
+
+### 10. Schema-Initialisierung
+- Die Initialisierung des SQLite-Schemas erfolgt in M4 **beim Programmstart**, bevor der Batch-Lauf mit der Dokumentverarbeitung beginnt.
+- Eine nur implizite oder ausschließlich lazy Initialisierung während des laufenden Dokumentdurchsatzes ist **nicht** Ziel von M4.
+
+---
+
+## AP-001 M4-Kernobjekte, Statussemantik und Port-Verträge präzisieren
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M4-Startpunkt.
+
+### Ziel
+Die M4-relevanten Typen, Statusbedeutungen und Port-Verträge werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können.
+
+### Muss umgesetzt werden
+- Neue M4-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für:
+  - Dokument-Fingerprint
+  - Dokument-Stammsatz
+  - Verarbeitungsversuch
+  - Fehlerzählerstände
+  - dokumentbezogene Persistenzentscheidung bzw. Lookup-Ergebnis
+  - technische Fehlerklassifikation für dokumentbezogene M4-Verarbeitung
+- Statusmodell so vervollständigen oder schärfen, dass die verbindlichen M4-Statuswerte fachlich eindeutig abbildbar sind.
+- Eindeutige Semantik für folgende Fälle im Typmodell bzw. in JavaDoc festlegen:
+  - unbekanntes Dokument
+  - bekanntes, noch nicht terminales Dokument
+  - bereits erfolgreiches Dokument
+  - bereits final fehlgeschlagenes Dokument
+  - historisierbarer dokumentbezogener Versuch
+  - nicht historisierbarer Vor-Fingerprint-Fehler
+- Outbound-Ports definieren für:
+  - Erzeugung eines Fingerprints für genau einen Verarbeitungskandidaten
+  - Lesen und Schreiben des Dokument-Stammsatzes
+  - Schreiben und Lesen der Versuchshistorie
+  - technische Initialisierung des SQLite-Schemas
+- Port-Verträge so schneiden, dass **weder `Path`/`File` noch JDBC-/SQLite-Typen** in Domain oder Application durchsickern.
+- Port-Rückgaben so modellieren, dass spätere Arbeitspakete ohne zusätzliche Annahmen unterscheiden können:
+  - Dokument unbekannt
+  - Dokument bekannt und aktiv weiter zu verarbeiten
+  - Dokument terminal erfolgreich
+  - Dokument terminal final fehlgeschlagen
+  - technischer Persistenzfehler
+- JavaDoc und `package-info` für:
+  - Statusbedeutungen
+  - Zählersemantik
+  - Historisierungsgrenzen
+  - Architekturgrenzen
+  ergänzen.
+
+### Explizit nicht Teil
+- SHA-256-Implementierung
+- SQLite-Implementierung
+- konkrete SQL-Tabellen
+- Batch-Integration
+- Repository-Code
+
+### Fertig wenn
+- die M4-relevanten Typen und Port-Verträge vorhanden sind,
+- die M4-Statussemantik eindeutig dokumentiert ist,
+- Historisierung vs. Vor-Fingerprint-Fehler klar abgegrenzt ist,
+- Domain und Application frei von Infrastrukturtypen bleiben,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 SHA-256-Fingerprint-Adapter für Verarbeitungskandidaten implementieren
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Für jeden Verarbeitungskandidaten kann ein stabiler, deterministischer SHA-256-Fingerprint erzeugt werden; technische Probleme werden kontrolliert in den Port-Vertrag überführt.
+
+### Muss umgesetzt werden
+- Fingerprint-Port technisch im Adapter-Out implementieren.
+- SHA-256-basierte Fingerprint-Erzeugung für genau einen Verarbeitungskandidaten umsetzen.
+- Sicherstellen, dass der Fingerprint ausschließlich aus dem **Dateiinhalt** abgeleitet wird.
+- Kontrolliertes technisches Fehlerverhalten für mindestens folgende Fälle abbilden:
+  - Datei nicht lesbar
+  - Datei zwischen Kandidatenermittlung und Fingerprint-Erzeugung nicht mehr vorhanden
+  - sonstige technische IO-Probleme
+- Sicherstellen, dass Dateisystem- und Hashing-Details ausschließlich im Adapter-Out verbleiben.
+- JavaDoc für Determinismus, Fehlerverhalten und M4-Grenze ergänzen, dass Vor-Fingerprint-Fehler **nicht** als SQLite-historisierte Versuche gelten.
+
+### Explizit nicht Teil
+- SQLite-Persistenz
+- Batch-Orchestrierung
+- Versuchshistorie
+- Skip-Logik
+- Zählerfortschreibung
+
+### Fertig wenn
+- für denselben Dateiinhalt stabil derselbe SHA-256-Fingerprint erzeugt wird,
+- Fingerprint und Fehler kontrolliert über den Port geliefert werden,
+- keine Hashing- oder Dateisystemdetails in Domain oder Application durchsickern,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-003 SQLite-Schema, Start-Initialisierung und Persistenzbasis im Adapter-Out einführen
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Die SQLite-basierte Persistenzgrundlage für M4 wird technisch sauber eingeführt und beim Programmstart kontrolliert initialisiert.
+
+### Muss umgesetzt werden
+- SQLite-Dateizugriff im Adapter-Out technisch einführen.
+- Technischen Initialisierungsbaustein für SQLite-Schema anlegen und über den dafür vorgesehenen Port anbinden.
+- M4-Schema explizit in **zwei Ebenen** anlegen:
+  - Dokument-Stammsatz
+  - Versuchshistorie
+- Tabellen, Primärschlüssel, Fremdschlüssel, Unique-Regeln und sinnvolle Indizes für den M4-Stand definieren.
+- Dokument-Stammsatz so anlegen, dass die in diesem Dokument festgelegten M4-Pflichtfelder speicherbar sind.
+- Versuchshistorie so anlegen, dass die in diesem Dokument festgelegten M4-Pflichtfelder speicherbar sind.
+- Sicherstellen, dass:
+  - Versuchsnummer pro Fingerprint eindeutig ist,
+  - Skip-Versuche speicherbar sind,
+  - keine M5+-Spalten angelegt werden.
+- Die Schema-Initialisierung so vorbereiten, dass sie **beim Programmstart** explizit aufgerufen werden kann.
+- JavaDoc für Schema-Zweck, Zwei-Ebenen-Modell und Initialisierungszeitpunkt ergänzen.
+
+### Explizit nicht Teil
+- Repository-Fachlogik
+- Use-Case-Integration
+- Statusübergänge im Batch-Lauf
+- KI-bezogene Persistenzfelder
+- Zielpfad- oder Dateinamenspersistenz
+
+### Fertig wenn
+- die SQLite-Datei und das M4-Schema technisch anlegbar sind,
+- beide Persistenzebenen den M4-Pflichtumfang abbilden,
+- die Start-Initialisierung technisch vorbereitet ist,
+- keine M5+-Felder im Schema enthalten sind,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-004 Repository für Dokument-Stammsatz mit vollständigem M4-Minimalumfang implementieren
+
+### Voraussetzung
+AP-003 ist abgeschlossen.
+
+### Ziel
+Der Dokument-Stammsatz kann pro Fingerprint zuverlässig gelesen, angelegt und fortgeschrieben werden, ohne fachliche Entscheidungslogik in den Adapter-Out zu verlagern.
+
+### Muss umgesetzt werden
+- Repository-Adapter für den Dokument-Stammsatz implementieren.
+- Folgende technischen Fähigkeiten bereitstellen:
+  - Suche eines Stammsatzes über Fingerprint
+  - Neuanlage eines Stammsatzes für bisher unbekannte Dokumente
+  - Fortschreibung von:
+    - letztem bekanntem Quellpfad
+    - letztem bekanntem Quelldateinamen
+    - Gesamtstatus
+    - Inhaltsfehlerzähler
+    - Transientfehlerzähler
+    - letztem Fehlerzeitpunkt
+    - letztem Erfolgzeitpunkt
+    - Änderungszeitpunkt
+- Sicherstellen, dass die Repository-Operationen **keine** fachlichen Entscheidungen über Retry-Regeln oder Skip-Logik treffen.
+- Mapping zwischen Application-Typen und SQLite-Struktur explizit und nachvollziehbar halten.
+- Upsert-/Neuanlageverhalten für den M4-Einzelprozess reproduzierbar modellieren.
+- JavaDoc für Verantwortlichkeit und Mapping ergänzen.
+
+### Explizit nicht Teil
+- Versuchshistorie
+- Batch-Skip-Logik
+- Versuchsnummernvergabe
+- konkrete Statusentscheidungen im Use-Case
+- KI- oder Zielkopie-bezogene Persistenz
+
+### Fertig wenn
+- der Dokument-Stammsatz pro Fingerprint zuverlässig gelesen und geschrieben werden kann,
+- alle M4-Pflichtfelder des Stammsatzes technisch fortschreibbar sind,
+- fachliche Entscheidungen nicht in das Repository abgerutscht sind,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 Repository für Versuchshistorie mit monotoner Versuchsnummer implementieren
+
+### Voraussetzung
+AP-003 ist abgeschlossen.
+
+### Ziel
+Jeder historisierbare dokumentbezogene M4-Versuch kann separat und nachvollziehbar persistiert werden.
+
+### Muss umgesetzt werden
+- Repository-Adapter für die Versuchshistorie implementieren.
+- Schreiben genau eines Versuchseintrags pro historisiertem dokumentbezogenem M4-Versuch umsetzen.
+- Lesefähigkeiten bereitstellen, soweit sie für M4-Use-Case und Tests benötigt werden.
+- Versuchsnummern pro Fingerprint reproduzierbar ableiten oder fortschreiben.
+- Sicherstellen, dass die Versuchsnummer:
+  - bei **1** beginnt,
+  - pro Fingerprint monoton steigt,
+  - auch bei Skip-Versuchen mitgezählt wird.
+- M4-relevante Historisierungsdaten persistieren:
+  - Fingerprint-Referenz
+  - Lauf-ID
+  - Versuchsnummer
+  - Startzeitpunkt
+  - Endzeitpunkt
+  - Ergebnisstatus
+  - Fehlerklasse
+  - Fehlermeldung bzw. Begründung
+  - Retryable-Flag
+- Sicherstellen, dass nur **identifizierte** Dokumente historisiert werden.
+- JavaDoc für Historisierungszweck, Versuchsnummernlogik und M4-Grenzen ergänzen.
+
+### Explizit nicht Teil
+- Dokument-Stammsatz
+- fachliche Zählerlogik
+- Batch-Orchestrierung
+- KI-Rohantwort, Modellname oder Prompt-Identifikator
+- Zielname, Zielpfad oder Zielkopie
+
+### Fertig wenn
+- pro historisiertem dokumentbezogenem Verarbeitungsvorgang ein separater Versuchseintrag gespeichert werden kann,
+- die Versuchsnummern pro Fingerprint reproduzierbar und monoton sind,
+- Skip-Versuche historisierbar sind,
+- Vor-Fingerprint-Fehler nicht fälschlich historisiert werden,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-006 M4-Entscheidungslogik und Batch-Integration für Idempotenz, Zähler und konsistente Persistenz umsetzen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Der bestehende M3-Verarbeitungslauf wird zu einem echten M4-Lauf erweitert, der Dokumente über Fingerprint wiedererkennt, Status und Zähler korrekt fortschreibt, Skip-Fälle historisiert und dabei keinen inkonsistenten Persistenzzustand hinterlässt.
+
+### Muss umgesetzt werden
+- Den bestehenden Batch-Use-Case so erweitern, dass pro Verarbeitungskandidat verbindlich diese Reihenfolge gilt:
+  1. Fingerprint erzeugen
+  2. Dokument-Stammsatz laden
+  3. terminale Fälle entscheiden
+  4. gegebenenfalls bestehenden M3-Ablauf ausführen
+  5. Ergebnis in M4-Status, Zähler und Retryable-Flag überführen
+  6. Versuch historisieren
+  7. Dokument-Stammsatz fortschreiben
+- Folgende M4-Regeln explizit umsetzen:
+  - vorhandener Gesamtstatus `SUCCESS` → Dokument wird nicht erneut fachlich verarbeitet, sondern mit `SKIPPED_ALREADY_PROCESSED` historisiert
+  - vorhandener Gesamtstatus `FAILED_FINAL` → Dokument wird nicht erneut fachlich verarbeitet, sondern mit `SKIPPED_FINAL_FAILURE` historisiert
+  - unbekanntes oder noch nicht terminales Dokument wird regulär weiterverarbeitet
+- M3-Ergebnisse exakt wie folgt in M4 überführen:
+  - M3 erfolgreich abgeschlossen → `SUCCESS`, keine Fehlerzähler erhöhen, `retryable = false`
+  - M3-Inhaltsfehler „kein brauchbarer Text“ oder „Seitenlimit überschritten“ beim ersten historisierten Auftreten → `FAILED_RETRYABLE`, Inhaltsfehlerzähler +1, `retryable = true`
+  - derselbe Dokumenttyp eines bereits identifizierten Dokuments mit erneutem deterministischen Inhaltsfehler in einem späteren Lauf → `FAILED_FINAL`, Inhaltsfehlerzähler +1, `retryable = false`
+  - dokumentbezogener technischer Fehler nach erfolgreicher Fingerprint-Ermittlung → `FAILED_RETRYABLE`, Transientfehlerzähler +1, `retryable = true`
+- Skip-Fälle so behandeln, dass:
+  - ein eigener Versuchseintrag geschrieben wird,
+  - kein Fehlerzähler verändert wird,
+  - der Gesamtstatus des Stammsatzes terminal bestehen bleibt.
+- Vor-Fingerprint-Fehler ausdrücklich **nicht** als SQLite-Versuch historisieren.
+- Für identifizierte Dokumente sicherstellen, dass **Historie und Stammsatz konsistent** fortgeschrieben werden und keine inkonsistenten Teilzustände entstehen.
+- Falls eine dokumentbezogene Persistenzoperation technisch scheitert:
+  - darf kein teilaktualisierter Zustand zurückbleiben,
+  - bleibt der Batch-Lauf für andere Dokumente kontrolliert weiter lauffähig,
+  - wird kein M5+-Verhalten vorweggenommen.
+- JavaDoc für Idempotenz, Zählerfortschreibung, Skip-Semantik und Persistenzkonsistenz ergänzen.
+
+### Explizit nicht Teil
+- KI-Aufruf
+- Dateinamensbildung
+- Zielkopie
+- M5+-Retry-Regeln für KI- oder Zielkopiefehler
+- M5+-Persistenzfelder
+- spätere Reporting- oder Auswertungslogik
+
+### Fertig wenn
+- der Batch-Lauf identische Inhalte über Fingerprint wiedererkennt,
+- `SUCCESS`- und `FAILED_FINAL`-Dokumente in späteren Läufen historisiert übersprungen werden,
+- die Minimalregel „erster deterministischer Inhaltsfehler retryable, zweiter final“ explizit umgesetzt ist,
+- technische dokumentbezogene Fehler nach Fingerprint als retryable behandelt werden,
+- Historie und Stammsatz pro identifiziertem Dokument konsistent fortgeschrieben werden,
+- weiterhin keine M5+-Funktionalität enthalten ist.
+
+---
+
+## AP-007 Bootstrap- und CLI-Anpassungen für SQLite-Konfiguration, Start-Initialisierung und M4-Verdrahtung durchführen
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Der Programmeinstieg ist sauber an den M4-Lauf angepasst; die Persistenz wird beim Start initialisiert und die neuen M4-Bausteine sind vollständig verdrahtet.
+
+### Muss umgesetzt werden
+- Bootstrap-Verdrahtung auf die neuen M4-Ports, Adapter und Persistenzbausteine erweitern.
+- M4-relevante Konfiguration ergänzen bzw. verdrahten, insbesondere für:
+  - `sqlite.file`
+- Startvalidierung so ergänzen, dass mindestens geprüft wird:
+  - SQLite-Dateipfad ist vorhanden oder technisch anlegbar
+  - Persistenzkonfiguration ist nutzbar
+- Technische Schema-Initialisierung **beim Programmstart** ausführen, bevor der eigentliche Dokumentlauf beginnt.
+- CLI-/Batch-Startpfad auf den realen M4-Ablauf ausrichten.
+- Sicherstellen, dass harte Start-, Verdrahtungs- oder Initialisierungsfehler weiterhin zu **Exit-Code 1** führen.
+- Sicherstellen, dass dokumentbezogene Fehler im späteren Lauf **nicht** als Startfehler fehlmodelliert werden.
+- M1–M3-Grundverhalten erhalten und sauber mit den M4-Bausteinen kombinieren.
+- JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfiguration und Modulgrenzen ergänzen.
+
+### Explizit nicht Teil
+- neue Exit-Code-Semantik späterer Meilensteine
+- KI-Verdrahtung
+- Zielordner- oder Dateinamensverdrahtung
+- Logging-Feinschliff
+
+### Fertig wenn
+- das Programm im M4-Stand vollständig startbar ist,
+- das SQLite-Schema beim Start kontrolliert initialisiert wird,
+- die neuen Adapter korrekt verdrahtet sind,
+- harte Persistenz-Startfehler kontrolliert zu Exit-Code 1 führen,
+- der Build fehlerfrei bleibt.
+
+---
+
+## AP-008 Tests für Fingerprint, SQLite-Repositories, M4-Statusfortschreibung, Historie und Skip-Logik vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-007 sind abgeschlossen.
+
+### Ziel
+Der vollständige M4-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.
+
+### Muss umgesetzt werden
+- Unit-Tests für die SHA-256-Fingerprint-Erzeugung implementieren.
+- Repository-Tests gegen SQLite implementieren, insbesondere für:
+  - Schema-Initialisierung
+  - Anlegen und Lesen eines Dokument-Stammsatzes
+  - Fortschreiben aller M4-Pflichtfelder des Stammsatzes
+  - Anlegen und Lesen von Versuchshistorie
+  - stabile Versuchsnummern pro Fingerprint
+- Tests für M4-Statusfortschreibung und Zähler ergänzen, insbesondere:
+  - unbekanntes Dokument mit erfolgreichem M4-Ende wird als `SUCCESS` persistiert
+  - erster deterministischer Inhaltsfehler führt zu `FAILED_RETRYABLE`
+  - zweiter deterministischer Inhaltsfehler in einem späteren Lauf führt zu `FAILED_FINAL`
+  - technischer dokumentbezogener Fehler nach erfolgreicher Fingerprint-Ermittlung erhöht den Transientfehlerzähler und bleibt `FAILED_RETRYABLE`
+  - Skip-Fälle verändern keine Fehlerzähler
+- Tests für Idempotenz- und Skip-Logik ergänzen, insbesondere:
+  - bereits erfolgreiches Dokument wird historisiert übersprungen
+  - final fehlgeschlagenes Dokument wird historisiert übersprungen
+  - gleicher Inhalt unter anderem Dateinamen wird über denselben Fingerprint erkannt
+- Tests ergänzen, die belegen:
+  - pro identifiziertem dokumentbezogenem Verarbeitungsvorgang entsteht genau **ein** Historieneintrag
+  - Skip-Ereignisse werden historisiert
+  - Vor-Fingerprint-Fehler nicht in SQLite-Historie auftauchen
+- Tests für Bootstrap- und Startverhalten ergänzen, insbesondere:
+  - Schema-Initialisierung beim Start
+  - harter Persistenz-Startfehler führt zu Exit-Code 1
+- Den M4-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M5+ prüfen.
+
+### Explizit nicht Teil
+- Tests für KI, Prompt-Laden oder KI-JSON
+- Tests für Zielkopie oder Dateinamensbildung
+- Tests für M5+-Persistenzfelder
+- Tests für vollständige Retry-Logik späterer Meilensteine
+
+### Fertig wenn
+- die Test-Suite für den M4-Umfang grün ist,
+- die wichtigsten M4-Randfälle automatisiert abgesichert sind,
+- der definierte M4-Zielzustand vollständig erreicht ist,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete decken den vollständigen M4-Zielumfang aus den verbindlichen Spezifikationen ab:
+
+- Fingerprint über SHA-256
+- SQLite-Persistenz in zwei Ebenen
+- Dokument-Stammsatz mit M4-Minimalumfang
+- Versuchshistorie pro identifiziertem dokumentbezogenem Versuch
+- Idempotenz über Fingerprint
+- Skip-Regeln für bereits erfolgreiche und final fehlgeschlagene Dokumente
+- explizite Minimalregel für deterministische Inhaltsfehler in M4
+- Tests für Fingerprint, Persistenz, Statusfortschreibung, Historie und Skip-Logik
+
+Gleichzeitig bleiben die Grenzen zu M1–M3 sowie zu M5+ gewahrt. Insbesondere werden **keine** KI-Funktionalitäten, **keine** Dateinamensbildung und **keine** Zielkopie vorweggenommen.
@@ -0,0 +1,669 @@
+# M5 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M5 – KI-Integration, Prompt-Bezug und validierter Benennungsvorschlag**.
+
+Die Meilensteine **M1**, **M2**, **M3** und **M4** werden als vollständig umgesetzt vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter und Bootstrap ändern.
+- Keine Annahmen treffen, die nicht durch dieses Dokument oder die verbindlichen Spezifikationen gedeckt sind.
+- Kein Vorgriff auf **M6+**.
+- Kein Umbau bestehender M1–M4-Strukturen ohne direkten M5-Bezug.
+- Neue Typen, Ports, Statuswerte, Migrationen und Adapter so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus **klar benennbar, testbar und reviewbar** sind.
+- M5 darf bestehende M4-Persistenz **gezielt evolvieren**, aber nicht stillschweigend neu erfinden.
+- Jeder positive M5-Zwischenstand muss bereits so modelliert sein, dass **M6 darauf ohne Statusbruch** aufsetzen kann.
+- M5 endet fachlich mit einem **persistierten, validierten Benennungsvorschlag**; **nicht** mit einer Zielkopie.
+
+## Explizit nicht Bestandteil von M5
+
+- physische Zielkopie in den Zielordner
+- finales Dateinamensformat `YYYY-MM-DD - Titel.pdf` als technische Ausgabeoperation
+- Dublettenbehandlung `(1)`, `(2)` im Zielordner
+- Windows-Zeichenbereinigung für den finalen Zieldateinamen
+- Zielpfad- und Zieldateinamenspersistenz
+- atomisches Schreiben oder temporäre Zieldateien
+- vollständige End-to-End-Erfolgssemantik des späteren Produktiv-Endstands aus M6
+- Logging-Feinschliff des Endstands aus M7
+- vollständige laufübergreifende Retry-Logik späterer Meilensteine für alle Fehlerarten jenseits des in M5 konkret benötigten Umfangs
+- manuelle Nachbearbeitung oder Benutzerinteraktion
+
+## Verbindliche M5-Regeln für **alle** Arbeitspakete
+
+### 1. Status- und Übergangssemantik zwischen M4, M5 und M6
+
+Die in M4 verwendete positive Zwischenbedeutung von `SUCCESS` reicht ab M5 **nicht mehr aus**, weil M5 einen validierten Benennungsvorschlag erzeugt, M6 aber erst die Zielkopie schreibt.
+
+Daher gilt ab M5 verbindlich:
+
+- `SUCCESS` ist ab M5 **für den echten Enderfolg nach M6 reserviert**.
+- M5 führt die beiden **nicht-terminalen positiven Statuswerte** ein:
+  - `READY_FOR_AI` = Dokument ist fachlich bis einschließlich M3 vorbereitet, aber es liegt noch **kein** gültiger M5-Benennungsvorschlag vor.
+  - `PROPOSAL_READY` = ein gültiger M5-Benennungsvorschlag ist persistent vorhanden; das Dokument ist **für M5 abgeschlossen**, aber **noch nicht** im Sinne von M6 erfolgreich kopiert.
+- Bereits vorhandene **M4-Altbestände** mit positivem Status `SUCCESS`, aber **ohne** M5-Benennungsvorschlag, müssen in M5 **kontrolliert in `READY_FOR_AI` überführt** werden.
+- Die bestehenden negativen bzw. Skip-Statuswerte bleiben erhalten:
+  - `FAILED_RETRYABLE`
+  - `FAILED_FINAL`
+  - `SKIPPED_ALREADY_PROCESSED`
+  - `SKIPPED_FINAL_FAILURE`
+- Für M5-spezifische Wiederholungsläufe gilt:
+  - `PROPOSAL_READY` wird **nicht erneut per KI verarbeitet**,
+  - `SUCCESS` wird **nicht erneut verarbeitet**,
+  - `FAILED_FINAL` wird **nicht erneut verarbeitet**,
+  - `READY_FOR_AI` und `FAILED_RETRYABLE` bleiben verarbeitbar.
+- Für M6 gilt bereits als verbindliche Übergaberegel:
+  - `PROPOSAL_READY` ist **kein terminaler Gesamterfolg**, sondern der fachlich korrekte Eingangszustand für Dateinamensbildung und Zielkopie.
+
+### 2. Externer Prompt-Bezug
+
+- Der Prompt ist in M5 **nicht** im Code fest verdrahtet.
+- Die Anwendung lädt den fachlich verwendeten Prompt aus einer **externen Datei**.
+- Der für einen KI-Versuch verwendete Prompt muss über einen **stabilen Prompt-Identifikator** nachvollziehbar sein, mindestens über den Prompt-Dateinamen oder einen gleichwertig stabilen Identifikator.
+
+### 3. Deterministische KI-Anfragezusammensetzung
+
+M5 führt **kein frei erfundenes Templating-System** ein.
+
+Stattdessen gilt:
+
+- Die Application erzeugt für den KI-Port eine **vollständig deterministische Anfrage-Repräsentation**.
+- Diese Repräsentation besteht mindestens aus:
+  - Prompt-Inhalt,
+  - Prompt-Identifikator,
+  - begrenztem Dokumenttext,
+  - tatsächlich gesendeter Zeichenzahl,
+  - der verbindlichen JSON-only-Erwartung für `date`, `title`, `reasoning`.
+- Die Zusammensetzung von Prompt und Dokumenttext erfolgt über einen **festen, dokumentierten technischen Aufbau**, damit KI 2 dies ohne Interpretationsspielraum umsetzen kann.
+- Provider-spezifische Features für strukturiertes Output dürfen **optional intern** verwendet werden, sind aber **nicht** Voraussetzung des M5-Designs.
+
+### 4. KI-Konfiguration und effektiver API-Key
+
+Für M5 müssen die bereits im Zielbild vorgesehenen KI-relevanten Konfigurationswerte technisch nutzbar und verdrahtet sein, insbesondere:
+
+- `api.baseUrl`
+- `api.model`
+- `api.timeoutSeconds`
+- `max.text.characters`
+- `prompt.template.file`
+
+Der API-Key bleibt Konfiguration; die bestehende Prioritätsregel **Umgebungsvariable vor Properties** bleibt verbindlich.
+
+Zusätzlich gilt für M5:
+
+- der **effektive** API-Key muss nicht nur aufgelöst, sondern auch **tatsächlich im HTTP-Adapter verwendet** werden,
+- die Verwendung muss automatisiert testbar nachgewiesen sein.
+
+### 5. Begrenzung des an die KI gesendeten Inhalts
+
+- Die maximale Zeichenzahl des an die KI gegebenen Dokumentinhalts ist konfigurierbar.
+- Die Begrenzung muss **vor dem KI-Aufruf** technisch angewendet werden.
+- Die tatsächlich an die KI gesendete Zeichenzahl muss verfügbar und persistierbar sein.
+- Die Begrenzung verändert **nicht** den extrahierten Originaltext im M3-/M4-Sinne, sondern nur den **für M5 verwendeten KI-Eingabetext**.
+
+### 6. Vollständige M5-Regel für Titel und Datum
+
+M5 muss die fachliche Regel **operational vollständig** umsetzen, ohne unzuverlässige Heuristik-Experimente einzuführen.
+
+Daher gilt kombinatorisch:
+
+- Der **Prompt-Vertrag** bindet die KI verbindlich an die nicht rein technisch prüfbaren Erwartungen:
+  - Titel auf Deutsch,
+  - verständlich,
+  - hinreichend eindeutig,
+  - Eigennamen unverändert.
+- Die **Application-Validierung** prüft zusätzlich alle in M5 **objektiv prüfbaren** Regeln:
+  - `title` vorhanden,
+  - `reasoning` vorhanden,
+  - Basistitel max. 20 Zeichen,
+  - keine unzulässigen Sonderzeichen außer Leerzeichen,
+  - keine generischen Platzhaltertitel,
+  - vorhandenes `date` ist als `YYYY-MM-DD` interpretierbar.
+- M5 führt **keine** spekulative Sprachdetektion, keine unsichere Eigennamen-Normalisierung und keine weichen Heuristiken für „Verständlichkeit“ ein, die fachlich eher neue Fehler erzeugen würden.
+
+### 7. Technischer Antwortvertrag der KI
+
+Die KI-Antwort muss in M5 als **genau ein parsebares JSON-Objekt** verarbeitet werden.
+
+Zweckmäßiges Schema im M5-Sinn:
+
+```json
+{
+  "date": "2026-02-11",
+  "title": "Stromabrechnung",
+  "reasoning": "..."
+}
+```
+
+Dabei gilt:
+
+- `title` ist verpflichtend,
+- `reasoning` ist verpflichtend,
+- `date` ist optional,
+- zusätzliche Felder dürfen technisch toleriert werden, sind aber für M5 fachlich irrelevant,
+- zusätzlicher Freitext außerhalb des JSON-Objekts macht die Antwort **technisch unbrauchbar**.
+
+### 8. Technisch unbrauchbare vs. fachlich unbrauchbare KI-Ergebnisse
+
+Für M5 ist diese Unterscheidung verbindlich:
+
+**Technisch unbrauchbare KI-Ergebnisse** sind insbesondere:
+- KI nicht erreichbar,
+- Timeout,
+- technisch fehlgeschlagener HTTP-Aufruf,
+- nicht parsebare KI-Antwort,
+- technisch unvollständige Antwort ohne verpflichtende Strukturbestandteile,
+- zusätzlicher Text außerhalb des erwarteten einzelnen JSON-Objekts.
+
+Diese Fälle sind im M5-Sinn **dokumentbezogene technische Fehler**.
+
+**Fachlich unbrauchbare KI-Ergebnisse** sind insbesondere:
+- unbrauchbarer oder generischer Titel,
+- Titel verletzt die technisch prüfbaren Titelregeln des Zielbilds,
+- die KI liefert ein `date`, dieses ist aber nicht interpretierbar oder unbrauchbar.
+
+Diese Fälle sind im M5-Sinn **deterministische Inhaltsfehler**.
+
+### 9. Datumsauflösung und Datumsquelle
+
+- Liefert die KI ein gültiges `date`, wird dieses als aufgelöstes Datum verwendet.
+- Liefert die KI **kein** `date`, setzt die Anwendung den Fallback über die technische Uhr (`ClockPort`) auf das aktuelle Datum.
+- Liefert die KI ein `date`, dieses ist aber unbrauchbar, ist das **kein** Fallback-Fall, sondern ein fachlicher Fehlerfall.
+- Die Datumsquelle muss im M5-Stand nachvollziehbar und persistierbar sein.
+
+### 10. M5-Benennungsvorschlag und führende Quelle für M6
+
+Der M5-Benennungsvorschlag besteht mindestens aus:
+
+- aufgelöstem Datum,
+- Datumsquelle,
+- validiertem Basistitel,
+- KI-Begründung (`reasoning`).
+
+**Nicht** Bestandteil des M5-Benennungsvorschlags sind:
+
+- finaler vollständiger Dateiname,
+- Dubletten-Suffix,
+- Zielpfad,
+- physische Zielkopie.
+
+Für die Übergabe an M6 gilt verbindlich:
+
+- die **führende Quelle** des gültigen M5-Benennungsvorschlags ist der **neueste Versuchshistorieneintrag mit Ergebnisstatus `PROPOSAL_READY`**,
+- M5 führt **keine parallele zweite Wahrheitsquelle** für Datum/Titel/Reasoning im Dokument-Stammsatz ein,
+- der Dokument-Stammsatz enthält in M5 weiterhin den Gesamtstatus und die Zähler, nicht aber redundante M6-Zieldaten.
+
+### 11. Erweiterung der Versuchshistorie in M5
+
+Die bereits in M4 vorhandene Versuchshistorie wird in M5 gezielt erweitert. Für jeden dokumentbezogenen, identifizierten M5-Versuch müssen mindestens speicherbar sein:
+
+- Modellname,
+- Prompt-Identifikator oder Prompt-Dateiname,
+- verarbeitete Seitenzahl,
+- an die KI gesendete Zeichenzahl,
+- KI-Rohantwort,
+- KI-Reasoning,
+- aufgelöstes Datum,
+- Datumsquelle,
+- validierter Titel.
+
+Nicht Bestandteil der M5-Versuchshistorie sind Zielpfad oder finaler Zieldateiname.
+
+### 12. Fehlersemantik und Zählerfortschreibung in M5
+
+M5 erweitert die in M4 bereits vorhandene Fehlersemantik:
+
+- dokumentbezogene **technische** KI-Fehler nach erfolgreicher Fingerprint-Ermittlung bleiben retryable und laufen über den **Transientfehlerzähler**,
+- fachlich **deterministische** KI-Ergebnisfehler laufen über den **Inhaltsfehlerzähler**,
+- die bestehende M4-Regel „erster deterministischer Inhaltsfehler retryable, zweiter final“ bleibt erhalten und gilt auch für M5-deterministische Inhaltsfehler,
+- Skip-Fälle aus M4 bleiben unverändert erhalten,
+- Vor-Fingerprint-Fehler bleiben weiterhin **nicht historisierte** Laufereignisse.
+
+### 13. Kein Vorgriff auf M6
+
+M5 endet fachlich mit einem **persistierten, validierten Benennungsvorschlag**. M5 führt **keine** Zielkopie aus und erzeugt **keinen** finalen Zieldateinamen als technische Dateisystemoperation.
+
+---
+
+## AP-001 M5-Kernobjekte, Statusmodell und KI-/Prompt-Port-Verträge präzisieren
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M5-Startpunkt.
+
+### Ziel
+Die M5-relevanten Typen, positiven Zwischenstatus, KI-/Prompt-Verträge und Ergebnissemantiken werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können.
+
+### Muss umgesetzt werden
+- Neue M5-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für:
+  - externen Prompt-Bezug,
+  - Prompt-Identifikator,
+  - deterministische KI-Anfrage-Repräsentation,
+  - KI-Rohantwort,
+  - parsebares KI-Antwortmodell,
+  - validierten Benennungsvorschlag,
+  - Datumsquelle,
+  - KI-bezogene Nachvollziehbarkeitsdaten pro Versuch,
+  - technische vs. fachliche KI-Fehlerklassifikation.
+- Das Statusmodell gezielt um die nicht-terminalen positiven Zwischenstatus erweitern:
+  - `READY_FOR_AI`
+  - `PROPOSAL_READY`
+- Die Semantik dieser Statuswerte in JavaDoc und ggf. `package-info` so dokumentieren, dass klar ist:
+  - `READY_FOR_AI` ist **M5-verarbeitbar**,
+  - `PROPOSAL_READY` ist **für M5 abgeschlossen**, aber **für M6 weiterverarbeitbar**,
+  - `SUCCESS` bleibt ab M5 dem echten M6-Enderfolg vorbehalten.
+- Outbound-Ports definieren für:
+  - Laden des externen Prompts,
+  - KI-Aufruf über eine OpenAI-kompatible Schnittstelle.
+- Port-Verträge so schneiden, dass **weder `Path`/`File` noch HTTP-/JSON-Bibliothekstypen** in Domain oder Application durchsickern.
+- Rückgabemodelle so anlegen, dass spätere Arbeitspakete ohne Zusatzannahmen unterscheiden können zwischen:
+  - technisch erfolgreichem KI-Aufruf mit Rohantwort,
+  - technischem KI-Fehler,
+  - parsebarer Antwort,
+  - technisch unbrauchbarer Antwort,
+  - fachlich validiertem Benennungsvorschlag,
+  - fachlich unbrauchbarem Benennungsvorschlag.
+- M5-spezifische Semantik von `date`, `title` und `reasoning` in JavaDoc eindeutig beschreiben.
+- Explizit dokumentieren, dass M5 **keinen finalen Zieldateinamen** und **keine Zielkopie** erzeugt.
+- Explizit dokumentieren, dass die führende Quelle für M6 **der neueste Versuch mit `PROPOSAL_READY`** ist.
+
+### Explizit nicht Teil
+- Prompt-Datei laden
+- HTTP-Adapter
+- KI-JSON-Parsing
+- fachliche Titel- und Datumsvalidierung
+- Persistenzanpassungen
+- Batch-Integration
+
+### Fertig wenn
+- die M5-relevanten Typen und Port-Verträge vorhanden sind,
+- technische und fachliche M5-Ergebnisarten klar unterscheidbar modelliert sind,
+- die positiven Zwischenstatus ohne Widerspruch zu M6 definiert sind,
+- Domain und Application frei von Infrastrukturtypen bleiben,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Externen Prompt laden, stabil identifizieren und deterministische KI-Anfrage zusammensetzen
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Der fachlich verwendete Prompt wird aus einer externen Datei geladen, stabil identifizierbar gemacht und gemeinsam mit dem Dokumenttext in eine eindeutig definierte, deterministische KI-Anfrage-Repräsentation überführt.
+
+### Muss umgesetzt werden
+- Adapter-Out für das Laden der externen Prompt-Datei implementieren.
+- Aus dem geladenen Prompt einen **stabilen Prompt-Identifikator** ableiten, mindestens über den Prompt-Dateinamen oder einen gleichwertig stabilen Identifikator.
+- Sicherstellen, dass leerer oder technisch unbrauchbarer Prompt nicht als gültige M5-Eingabe weitergereicht wird.
+- Einen **fest dokumentierten technischen Aufbau** der KI-Anfrage-Repräsentation implementieren, der mindestens enthält:
+  - Prompt-Inhalt,
+  - Prompt-Identifikator,
+  - Dokumenttext als eigener Block,
+  - die JSON-only-Erwartung für `date`, `title`, `reasoning`.
+- Die Zusammensetzung so schneiden, dass KI 2 **ohne implizite Entscheidung** weiß, in welcher Reihenfolge Prompt und Dokumenttext zusammengeführt werden.
+- Den Mechanismus so schneiden, dass **kein frei erfundenes Templating-System** eingeführt werden muss.
+- JavaDoc für Prompt-Bezug, Identifikator, deterministische Zusammensetzung, JSON-only-Vertrag und M5-Nicht-Ziele ergänzen.
+
+### Explizit nicht Teil
+- HTTP-Aufruf zur KI
+- Textbegrenzung
+- KI-Antwortvalidierung
+- Batch-Integration
+- Persistenz der Prompt-Metadaten
+
+### Fertig wenn
+- der Prompt aus einer externen Datei technisch ladbar ist,
+- ein stabiler Prompt-Identifikator bereitsteht,
+- die KI-Anfrage-Repräsentation deterministisch aufgebaut wird,
+- kein freies Ad-hoc-Templating eingeführt wurde,
+- der Stand weiterhin fehlerfrei buildbar ist.
+
+---
+
+## AP-003 OpenAI-kompatiblen KI-HTTP-Adapter mit wirksamer Konfiguration und kontrolliertem technischem Fehlerverhalten implementieren
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Ein technisch gekapselter Adapter kann einen M5-KI-Aufruf gegen eine OpenAI-kompatible HTTP-Schnittstelle ausführen, den **effektiven** API-Key tatsächlich verwenden und eine Rohantwort oder einen kontrollierten technischen Fehler liefern.
+
+### Muss umgesetzt werden
+- OpenAI-kompatiblen HTTP-Adapter im Adapter-Out implementieren.
+- Basis-URL, Modellname, Timeout und API-Zugriff aus der vorhandenen Konfiguration technisch nutzbar machen.
+- Den Adapter so schneiden, dass Domain und Application nur mit dem **abstrakten KI-Port** arbeiten.
+- Eine technische Rohantwort liefern, die in späteren Arbeitspaketen geparst und validiert werden kann.
+- Kontrolliertes Fehlerverhalten mindestens für folgende Fälle umsetzen:
+  - Timeout,
+  - nicht erreichbarer Endpunkt,
+  - technisch fehlgeschlagener HTTP-Aufruf,
+  - sonstige technische Kommunikationsfehler.
+- Sicherstellen, dass der **effektive API-Key** gemäß bestehender Prioritätsregel im Adapter **real verwendet** wird.
+- Sicherstellen, dass keine HTTP-, Authentifizierungs- oder JSON-Implementierungsdetails in Domain oder Application durchsickern.
+- JavaDoc für OpenAI-Kompatibilität, technische Fehlergrenzen, Konfigurationsnutzung und M5-Nicht-Ziele ergänzen.
+
+### Explizit nicht Teil
+- fachliche Validierung der KI-Antwort
+- Persistenz
+- Batch-Orchestrierung
+- Textbegrenzung
+- Datums-Fallback
+- finaler Benennungsvorschlag
+
+### Fertig wenn
+- der KI-Port technisch implementiert ist,
+- Konfiguration für Basis-URL, Modellname, Timeout und effektiven API-Key wirksam verwendet wird,
+- Rohantwort und technische Fehler kontrolliert über den Port geliefert werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 Textbegrenzung, KI-JSON-Parsing, vollständige M5-Validierung und Datumsauflösung umsetzen
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Die Anwendung kann einen begrenzten Dokumenttext für den KI-Aufruf vorbereiten, die KI-Rohantwort als JSON interpretieren und daraus entweder einen validierten Benennungsvorschlag oder einen eindeutig klassifizierten Fehler ableiten.
+
+### Muss umgesetzt werden
+- Konfigurierbare Begrenzung des an die KI zu sendenden Dokumenttexts umsetzen.
+- Sicherstellen, dass die Begrenzung **vor dem KI-Aufruf** angewendet wird.
+- Tatsächlich gesendete Zeichenzahl technisch erfassen und für spätere Persistenz bereitstellen.
+- Parsing der KI-Rohantwort als **genau ein JSON-Objekt** implementieren.
+- Technische Antwortvalidierung umsetzen:
+  - `title` vorhanden und nicht leer,
+  - `reasoning` vorhanden und nicht leer,
+  - `date` optional,
+  - zusätzlicher Freitext außerhalb des JSON-Objekts führt zu technischer Ungültigkeit.
+- Fachliche M5-Validierung für die **objektiv prüfbaren** Titel- und Datumsregeln umsetzen, insbesondere:
+  - Basistitel max. 20 Zeichen,
+  - keine unzulässigen Sonderzeichen außer Leerzeichen,
+  - keine generischen Platzhaltertitel,
+  - ein vorhandenes `date` muss als `YYYY-MM-DD` interpretierbar sein.
+- Den nicht rein technisch prüfbaren Teil der fachlichen Titelregel explizit über den **Prompt-Vertrag** absichern und dies im Code/JavaDoc sauber dokumentieren:
+  - Deutsch,
+  - verständlich,
+  - hinreichend eindeutig,
+  - Eigennamen unverändert.
+- Explizit umsetzen:
+  - fehlendes `date` → Fallback über `ClockPort`,
+  - vorhandenes, aber unbrauchbares `date` → fachlicher Fehler,
+  - parsebare, aber fachlich unbrauchbare Titel → fachlicher Fehler.
+- Einen validierten M5-Benennungsvorschlag bereitstellen, der mindestens enthält:
+  - aufgelöstes Datum,
+  - Datumsquelle,
+  - validierten Titel,
+  - KI-Reasoning.
+- JavaDoc für Begrenzungsregel, Antwortvalidierung, Datums-Fallback und operative Vollständigkeit der Titelregel ergänzen.
+
+### Explizit nicht Teil
+- HTTP-Adapter
+- SQLite-Schemaerweiterung
+- Batch-Integration
+- Status- und Zählerfortschreibung
+- finale Dateinamensbildung
+- Zielkopie
+
+### Fertig wenn
+- Dokumenttext begrenzt werden kann,
+- parsebare und unparsebare KI-Antworten sauber unterscheidbar sind,
+- fehlendes Datum korrekt auf den Clock-Fallback läuft,
+- fachlich unbrauchbare Titel und Datumswerte sauber erkannt werden,
+- ein validierter M5-Benennungsvorschlag technisch verfügbar ist,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 SQLite-Schema von M4 nach M5 evolvieren, Altbestände migrieren und Versuchshistorie um M5-Nachvollziehbarkeit erweitern
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Die bestehende M4-Persistenz wird kontrolliert auf den M5-Stand erweitert, inklusive der **idempotenten Migration positiver M4-Altbestände** und der Erweiterung der Versuchshistorie um die M5-Nachvollziehbarkeit.
+
+### Muss umgesetzt werden
+- Das bestehende SQLite-Schema **evolvieren**, nicht neu erfinden.
+- Die Schema-Initialisierung so erweitern, dass ein vorhandenes M4-Schema kontrolliert auf den M5-Stand gebracht werden kann.
+- Die Versuchshistorie um die für M5 benötigten Felder erweitern, insbesondere für:
+  - Modellname,
+  - Prompt-Identifikator oder Prompt-Dateiname,
+  - verarbeitete Seitenzahl,
+  - an die KI gesendete Zeichenzahl,
+  - KI-Rohantwort,
+  - KI-Reasoning,
+  - aufgelöstes Datum,
+  - Datumsquelle,
+  - validierten Titel.
+- Die Persistenz so erweitern, dass die neuen nicht-terminalen positiven Statuswerte fachlich konsistent speicherbar sind:
+  - `READY_FOR_AI`
+  - `PROPOSAL_READY`
+- Eine **idempotente M4→M5-Altbestandsmigration** vorsehen, die mindestens sicherstellt:
+  - M4-Dokumente mit positivem Altstatus `SUCCESS`, aber ohne M5-Benennungsvorschlag, werden kontrolliert nach `READY_FOR_AI` überführt,
+  - diese Migration ist mehrfach ausführbar, ohne Daten zu beschädigen,
+  - bestehende negative und terminale Fehlerzustände bleiben unangetastet.
+- Sicherstellen, dass:
+  - bestehende M4-Daten weiterhin lesbar bleiben,
+  - die M5-Erweiterung idempotent initialisierbar ist,
+  - keine M6+-Felder für Zielpfad oder finalen Zieldateinamen angelegt werden.
+- Repository-Mapping der Versuchshistorie auf die neuen M5-Felder erweitern.
+- Falls für Tests oder Use-Case-Integration nötig, passende Lesefähigkeiten ergänzen, ohne spätere Reporting-Funktionalität vorwegzunehmen.
+- JavaDoc für Schemaevolution, Altbestandsmigration, Rückwärtsverträglichkeit und M5-Nachvollziehbarkeit ergänzen.
+
+### Explizit nicht Teil
+- Batch-Use-Case-Integration
+- KI-Aufruf
+- Status- und Zählerentscheidungen im laufenden Batch
+- Zielpfad- oder Dateinamenspersistenz
+- M6-Dateisystemfunktionalität
+
+### Fertig wenn
+- das M4-Schema kontrolliert auf M5 erweitert werden kann,
+- M4-Altbestände mit positivem Zwischenstatus idempotent auf die M5-Semantik überführt werden,
+- die neuen M5-Felder in der Versuchshistorie technisch schreib- und lesbar sind,
+- bestehende M4-Daten nicht unbrauchbar werden,
+- keine M6+-Persistenzfelder eingeführt wurden,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-006 M5-Entscheidungslogik und Batch-Integration für KI-Aufruf, Fehlerklassifikation, Statusfortschreibung und persistierten Benennungsvorschlag umsetzen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Der bestehende M4-Lauf wird zu einem echten M5-Lauf erweitert, der nach erfolgreicher M3-Vorprüfung per KI einen validierten Benennungsvorschlag erzeugt, KI-bezogene Versuchsdaten persistiert und die positive Statussemantik so fortschreibt, dass M6 ohne Statusbruch anknüpfen kann.
+
+### Muss umgesetzt werden
+- Den bestehenden Batch-Use-Case so erweitern, dass pro geeignetem Dokument nach M4-Identifikation und nach bestandener M3-Vorprüfung zusätzlich gilt:
+  1. Prompt laden,
+  2. Dokumenttext begrenzen,
+  3. deterministische KI-Anfrage erzeugen,
+  4. KI-Aufruf durchführen,
+  5. KI-Rohantwort technisch verarbeiten,
+  6. Benennungsvorschlag validieren,
+  7. Versuchshistorie mit M5-Nachvollziehbarkeit fortschreiben,
+  8. Status und Zähler im vorhandenen Rahmen konsistent fortschreiben.
+- Sicherstellen, dass **kein KI-Aufruf** erfolgt bei:
+  - Vor-Fingerprint-Fehlern,
+  - terminalen Skip-Fällen aus M4,
+  - M3-Inhaltsfehlern,
+  - sonstigen Fällen, die den Dokumentlauf bereits vor der KI sauber beendet haben.
+- Die positiven Dokumentzustände explizit wie folgt behandeln:
+  - M4-Altbestand `SUCCESS` ohne M5-Benennungsvorschlag wird **nicht** als terminal erfolgreich übersprungen, sondern gilt nach Migration bzw. Normalisierung als `READY_FOR_AI`,
+  - gültiger M5-Benennungsvorschlag führt zu `PROPOSAL_READY`, **nicht** zu `SUCCESS`,
+  - bestehendes `PROPOSAL_READY` führt in M5 zu **keinem erneuten KI-Aufruf**.
+- M5-Fehlerfälle explizit wie folgt in den bestehenden Status- und Zählerrahmen überführen:
+  - technischer KI-Fehler oder technisch unbrauchbare KI-Antwort → dokumentbezogener technischer Fehler, retryable, **Transientfehlerzähler +1**,
+  - parsebare, aber fachlich unbrauchbare KI-Antwort → deterministischer Inhaltsfehler, **Inhaltsfehlerzähler** nach bestehender Regel fortschreiben,
+  - gültiger Benennungsvorschlag → `PROPOSAL_READY`, Fehlerzähler unverändert.
+- Sicherstellen, dass bei dokumentbezogenen KI-Fehlern der Batch-Lauf für andere Dokumente kontrolliert weiterläuft.
+- Für identifizierte Dokumente sicherstellen, dass Versuchshistorie und Stammsatz konsistent fortgeschrieben werden und kein teilpersistierter Zustand zurückbleibt.
+- Sicherstellen, dass die führende Quelle für M6 **der neueste Versuch mit `PROPOSAL_READY`** bleibt und nicht implizit aus anderen Daten rekonstruiert werden muss.
+- Sicherstellen, dass KI-Rohantwort standardmäßig **in SQLite**, aber nicht als M6-/M7-Funktionalität fehlmodelliert wird.
+- JavaDoc für M5-Laufreihenfolge, KI-Grenze, Fehlerklassifikation, positive Statusfortschreibung und Persistenzkonsistenz ergänzen.
+
+### Explizit nicht Teil
+- physische Zielkopie
+- finale Dateinamensbildung
+- Dublettenbehandlung
+- Zielpfad- und Zieldateinamenspersistenz
+- M6- oder M7-Feinschliff
+
+### Fertig wenn
+- der Batch-Lauf für geeignete Dokumente tatsächlich einen KI-basierten Benennungsvorschlag erzeugt,
+- M4-Altbestände mit positivem Zwischenstatus korrekt in die M5-Verarbeitung überführt werden,
+- gültige M5-Ergebnisse als `PROPOSAL_READY` und **nicht** als `SUCCESS` persistiert werden,
+- M5-spezifische technische und fachliche KI-Fehler sauber unterschieden werden,
+- der validierte Benennungsvorschlag persistiert wird,
+- KI-Aufrufe nur an den fachlich zulässigen Stellen erfolgen,
+- der Lauf trotz dokumentbezogener KI-Fehler kontrolliert weiterarbeitet,
+- weiterhin keine M6+-Funktionalität enthalten ist.
+
+---
+
+## AP-007 Bootstrap- und CLI-Anpassungen für M5-Konfiguration, Startvalidierung, Schemaevolution und vollständige Verdrahtung durchführen
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Der Programmeinstieg ist sauber an den M5-Lauf angepasst; die KI-relevante Konfiguration wird validiert, die M5-Schemaevolution einschließlich Altbestandsmigration wird beim Start wirksam, alle M5-Bausteine sind verdrahtet und harte Startfehler führen weiterhin kontrolliert zu Exit-Code 1.
+
+### Muss umgesetzt werden
+- Bootstrap-Verdrahtung auf die neuen M5-Ports, Adapter, Validierungs- und Persistenzbausteine erweitern.
+- M5-relevante Konfiguration ergänzen bzw. verdrahten, insbesondere für:
+  - `api.baseUrl`
+  - `api.model`
+  - `api.timeoutSeconds`
+  - `max.text.characters`
+  - `prompt.template.file`
+- Startvalidierung so ergänzen, dass mindestens geprüft wird:
+  - Prompt-Datei ist vorhanden und technisch lesbar,
+  - `max.text.characters` ist gültig und technisch nutzbar,
+  - Timeout ist gültig,
+  - KI-Basis-URL und Modellname sind vorhanden,
+  - ein effektiver API-Key gemäß bestehender Prioritätsregel verfügbar ist.
+- Die bestehende M4-Schema-Initialisierung mit der M5-Schemaevolution und der M4→M5-Altbestandsmigration sauber kombinieren.
+- Sicherstellen, dass harte Start-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler weiterhin zu **Exit-Code 1** führen.
+- Sicherstellen, dass dokumentbezogene KI-Fehler **nicht** als Startfehler fehlmodelliert werden.
+- JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfiguration, Schemaevolution und Modulgrenzen ergänzen.
+
+### Explizit nicht Teil
+- Logging-Feinschliff des Endstands
+- M6-Dateisystemverdrahtung
+- Zielkopie
+- Dublettenlogik
+- spätere Betriebsoptimierungen
+
+### Fertig wenn
+- das Programm im M5-Stand vollständig startbar ist,
+- alle M5-Bausteine korrekt verdrahtet sind,
+- die M5-Startvalidierung greift,
+- die M5-Schemaevolution einschließlich Altbestandsmigration beim Start wirksam wird,
+- harte Startfehler weiterhin kontrolliert zu Exit-Code 1 führen,
+- der Build fehlerfrei bleibt.
+
+---
+
+## AP-008 Tests für Prompt-Bezug, KI-Adapter, Validierung, Altbestandsmigration, Statussemantik, Schemaevolution und M5-Ablauf vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-007 sind abgeschlossen.
+
+### Ziel
+Der vollständige M5-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.
+
+### Muss umgesetzt werden
+- Unit-Tests für den externen Prompt-Bezug implementieren, insbesondere für:
+  - Prompt-Datei wird geladen,
+  - leerer oder technisch ungültiger Prompt wird abgelehnt,
+  - stabiler Prompt-Identifikator wird geliefert,
+  - deterministische Zusammensetzung der KI-Anfrage bleibt reproduzierbar.
+- Tests für Textbegrenzung und tatsächlich gesendete Zeichenzahl implementieren.
+- Tests für KI-JSON-Parsing und technische Antwortvalidierung implementieren, insbesondere für:
+  - gültiges JSON,
+  - ungültiges JSON,
+  - fehlendes `title`,
+  - fehlendes `reasoning`,
+  - optionales `date`,
+  - zusätzlicher Text außerhalb des JSON-Objekts.
+- Tests für fachliche M5-Validierung implementieren, insbesondere für:
+  - gültigen Titel,
+  - generischen Titel,
+  - Titel mit unzulässigen Sonderzeichen,
+  - Titel über 20 Zeichen,
+  - gültiges KI-Datum,
+  - fehlendes Datum mit Clock-Fallback,
+  - unbrauchbares vorhandenes Datum.
+- Adapter-Tests für den KI-Port ergänzen, insbesondere für:
+  - erfolgreiche Rohantwort,
+  - Timeout,
+  - technisch fehlgeschlagenen HTTP-Aufruf,
+  - Verwendung des **effektiven API-Keys** im tatsächlichen HTTP-Request,
+  - Vorrang der Umgebungsvariable vor `api.key` aus Properties im real genutzten Adapterpfad.
+- Repository- und Schema-Tests gegen SQLite ergänzen, insbesondere für:
+  - Evolution eines M4-Schemas auf M5,
+  - Persistenz und Auslesen der neuen M5-Versuchshistorienfelder,
+  - Rückwärtsverträglichkeit bestehender M4-Daten,
+  - idempotente Migration von M4-Altbeständen `SUCCESS` nach `READY_FOR_AI`.
+- Integrationstests für den M5-Ablauf ergänzen, insbesondere:
+  - gültiger M5-Happy-Path mit persistiertem Benennungsvorschlag endet in `PROPOSAL_READY`, **nicht** in `SUCCESS`,
+  - technisch unbrauchbare KI-Antwort führt zu retryablem technischem Fehler,
+  - fachlich unbrauchbare KI-Antwort führt zu deterministischem Inhaltsfehler,
+  - bei fehlendem `date` wird der Clock-Fallback verwendet,
+  - bei M3-Inhaltsfehlern erfolgt kein KI-Aufruf,
+  - bestehendes `PROPOSAL_READY` wird im M5-Wiederholungslauf nicht erneut per KI verarbeitet,
+  - M4-Altbestände mit positivem Zwischenstatus werden im M5-Lauf nicht fälschlich als final erfolgreich übersprungen,
+  - die führende Quelle für M6 ist der neueste Versuch mit `PROPOSAL_READY`,
+  - es erfolgt weiterhin **keine Zielkopie**.
+- Tests für Bootstrap- und Startverhalten ergänzen, insbesondere:
+  - ungültige M5-Konfiguration führt zu Exit-Code 1,
+  - M5-Schemaevolution einschließlich Altbestandsmigration wird beim Start wirksam,
+  - dokumentbezogene KI-Fehler führen **nicht** zu Exit-Code 1.
+- Den M5-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M6+ prüfen.
+
+### Explizit nicht Teil
+- Tests für Zielkopie
+- Tests für Dublettenbehandlung im Zielordner
+- Tests für finalen Zieldateinamen
+- Tests für M6-/M7-Endverhalten
+
+### Fertig wenn
+- die Test-Suite für den M5-Umfang grün ist,
+- die wichtigsten M5-Randfälle automatisiert abgesichert sind,
+- die positive Statussemantik M4→M5→M6 ohne Lücke nachgewiesen ist,
+- der definierte M5-Zielzustand vollständig erreicht ist,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete decken den vollständigen M5-Zielumfang aus den verbindlichen Spezifikationen ab und schließen zusätzlich die zuvor offene **Status- und Übergangssemantik zwischen M4, M5 und M6** sauber:
+
+- externer Prompt-Bezug
+- deterministische KI-Anfrage-Zusammensetzung
+- OpenAI-kompatibler KI-Aufruf
+- konfigurierbarer KI-Zugriff einschließlich wirksam genutztem effektivem API-Key
+- Begrenzung des an die KI gesendeten Inhalts
+- technische und fachliche Validierung der KI-Antwort
+- Datums-Fallback durch die Anwendung
+- persistierter, validierter Benennungsvorschlag
+- Erweiterung der Versuchshistorie um M5-Nachvollziehbarkeit
+- idempotente M4→M5-Altbestandsmigration
+- positive Zwischenstatus `READY_FOR_AI` und `PROPOSAL_READY` als saubere Brücke zu M6
+- Tests für Prompt, KI-Adapter, Validierung, Datumsauflösung, Schemaevolution, Altbestandsmigration und M5-Ablauf
+
+Gleichzeitig bleiben die Grenzen zu M1–M4 sowie zu M6+ gewahrt. Insbesondere werden **keine** Zielkopie, **keine** Dublettenbehandlung im Zielordner und **keine** finale Dateinamensbildung vorweggenommen.
@@ -0,0 +1,525 @@
+# M6 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M6 – Dateinamensbildung, Dublettenbehandlung und Zielkopie**.
+
+Die Meilensteine **M1**, **M2**, **M3**, **M4** und **M5** werden als vollständig umgesetzt vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter und Bootstrap ändern.
+- Keine Annahmen treffen, die nicht durch dieses Dokument oder die verbindlichen Spezifikationen gedeckt sind.
+- Kein Vorgriff auf **M7+**.
+- Kein Umbau bestehender M1–M5-Strukturen ohne direkten M6-Bezug.
+- Neue Typen, Ports, Statusübergänge, Migrationen und Adapter so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus **klar benennbar, testbar und reviewbar** sind.
+- M6 baut auf dem in M5 persistierten, validierten Benennungsvorschlag auf und führt **keine zweite Wahrheitsquelle** für Datum, Titel oder Reasoning ein.
+- Jedes Arbeitspaket muss so präzise sein, dass **KI 1** keine offenen Fach- oder Architekturentscheidungen an **KI 2** delegieren muss.
+- M6 endet fachlich mit dem **echten Enderfolg**: korrekt benannte Zielkopie vorhanden und Erfolg konsistent persistiert.
+
+## Explizit nicht Bestandteil von M6
+
+- fachliche Retry-Logik des Endstands über mehrere spätere Läufe hinaus, soweit sie über die bereits vorhandene Minimalfehlersemantik hinausgeht
+- technischer Sofort-Wiederholversuch für Zielkopierfehler innerhalb desselben Laufs
+- Logging-Feinschliff und Sensibilitätsregeln des Endstands aus M7
+- neue KI-Funktionalität, Prompt-Evolution oder M5-Fachlogik jenseits der für M6 nötigen Weiterverwendung
+- manuelle Nachbearbeitung oder Benutzerinteraktion
+- Reporting-, Statistik- oder Auswertungsfunktionen
+- spätere Betriebsoptimierungen, die nicht für den M6-Zielstand notwendig sind
+
+## Verbindliche M6-Regeln für **alle** Arbeitspakete
+
+### 1. Führende Quelle des Benennungsvorschlags
+
+- Die führende Quelle für Datum, Datumsquelle, validierten Titel und Reasoning bleibt in M6 der **neueste Versuchshistorieneintrag mit Ergebnisstatus `PROPOSAL_READY`**.
+- M6 rekonstruiert diesen Benennungsvorschlag **nicht** aus dem Dokument-Stammsatz.
+- M6 erzeugt **keinen neuen KI-Aufruf**, wenn bereits ein nutzbarer `PROPOSAL_READY`-Versuch vorliegt.
+- Ein Dokumentzustand `PROPOSAL_READY` ohne lesbaren, konsistenten `PROPOSAL_READY`-Versuch gilt in M6 als **dokumentbezogener technischer Fehler**, nicht als stiller Anlass für eine heimliche Neuinterpretation.
+- Ein geladener `PROPOSAL_READY`-Versuch mit fachlich oder technisch unbrauchbaren Kernwerten für Datum oder Titel gilt ebenfalls als **inkonsistenter Persistenzzustand** und damit als **dokumentbezogener technischer Fehler**.
+
+### 2. Positive Status- und Übergangssemantik in M6
+
+Ab M6 gilt verbindlich:
+
+- `READY_FOR_AI` bleibt verarbeitbar.
+- `FAILED_RETRYABLE` bleibt verarbeitbar.
+- `PROPOSAL_READY` ist der **fachlich korrekte Eingangszustand** für Dateinamensbildung, Dublettenbehandlung und Zielkopie.
+- `SUCCESS` ist ab M6 der **echte terminale Enderfolg** nach erfolgreicher Zielkopie und konsistenter Persistenz.
+- `FAILED_FINAL` bleibt terminal und wird nicht erneut fachlich verarbeitet.
+- `SUCCESS` wird in späteren Läufen nicht erneut verarbeitet, sondern mit `SKIPPED_ALREADY_PROCESSED` historisiert.
+- `FAILED_FINAL` wird in späteren Läufen nicht erneut verarbeitet, sondern mit `SKIPPED_FINAL_FAILURE` historisiert.
+
+### 3. Verbindliche Dateinamensregeln in M6
+
+Der finale Zieldateiname folgt technisch verbindlich diesem Muster:
+
+```text
+YYYY-MM-DD - Titel.pdf
+```
+
+Dabei gilt:
+
+- das Datum stammt aus dem führenden M5-Benennungsvorschlag,
+- der Titel stammt aus dem führenden M5-Benennungsvorschlag,
+- die **20 Zeichen** gelten nur für den **Basistitel**,
+- das Dubletten-Suffix zählt **nicht** zu diesen 20 Zeichen,
+- die fachliche Titelregel **„keine Sonderzeichen außer Leerzeichen“** bleibt auch in M6 verbindlich abgesichert,
+- Windows-unzulässige Zeichen werden nur im Rahmen der **technischen Dateisystemzulässigkeit** kontrolliert entfernt oder ersetzt,
+- diese technische Bereinigung darf **keine neue fachliche Titelinterpretation** erzeugen,
+- wenn ein geladener Proposal-Titel entgegen der M5-Semantik die fachlichen Titelregeln verletzt, wird dieser Zustand **nicht stillschweigend geheilt**, sondern als **inkonsistenter technischer Dokumentzustand** behandelt,
+- die Quelldatei bleibt unverändert.
+
+### 4. Dublettenregel in M6
+
+- Die Dublettenregel wird im **Zielordner** physisch gegen bereits vorhandene Dateien aufgelöst.
+- Der erste freie Name ist zu verwenden:
+  - `YYYY-MM-DD - Titel.pdf`
+  - `YYYY-MM-DD - Titel(1).pdf`
+  - `YYYY-MM-DD - Titel(2).pdf`
+  - usw.
+- Das Suffix wird unmittelbar vor `.pdf` angehängt.
+- Die Dublettenauflösung ist rein technisch und führt **keine** neue fachliche Titelvariante ein.
+
+### 5. Zielkopie und Dateisystemsemantik
+
+- M6 erzeugt bei Erfolg **eine Kopie** im Zielordner.
+- Die Quelldatei wird **nicht** verändert, verschoben, gelöscht oder überschrieben.
+- Die Zielerzeugung erfolgt über eine temporäre Zieldatei mit anschließendem finalem Move/Rename, soweit dies im Zielkontext technisch möglich ist.
+- M6 führt **keinen** fachlichen oder technischen Sofort-Mehrfachversuch für die Zielkopie ein; dieser ist M7 vorbehalten.
+
+### 6. Persistenzerweiterung und Historisierung in M6
+
+Die Persistenz wird in M6 gezielt erweitert:
+
+- Der **Dokument-Stammsatz** speichert zusätzlich mindestens:
+  - letzten Zielpfad,
+  - letzten Zieldateinamen.
+- Die **Versuchshistorie** speichert zusätzlich mindestens:
+  - finalen Zieldateinamen.
+- Datum, Datumsquelle, validierter Titel und Reasoning bleiben weiterhin führend in der Versuchshistorie des `PROPOSAL_READY`-Versuchs und werden nicht redundant in den Stammsatz gespiegelt.
+- Ein M6-Enderfolg oder M6-Fehler wird als **zusätzlicher neuer Versuch** historisiert; der führende `PROPOSAL_READY`-Versuch bleibt dabei **unverändert erhalten**.
+- M6 überschreibt oder ersetzt **nicht** nachträglich den führenden Proposal-Versuch, sondern baut fachlich und historisch auf ihm auf.
+
+### 7. Reihenfolge pro Dokument in M6
+
+Die Verarbeitung eines einzelnen Kandidaten erfolgt in M6 verbindlich in dieser Reihenfolge:
+
+1. Fingerprint berechnen
+2. Dokument-Stammsatz laden
+3. terminale Skip-Fälle entscheiden
+4. falls nötig den bestehenden M5-Pfad bis zu einem gültigen Benennungsvorschlag ausführen
+5. führenden `PROPOSAL_READY`-Versuch laden
+6. finalen Basis-Dateinamen bilden
+7. Dubletten-Suffix im Zielordner bestimmen
+8. Zielkopie technisch schreiben
+9. einen **neuen** M6-Versuch für Enderfolg oder technischen Fehler historisieren
+10. Dokument-Stammsatz konsistent fortschreiben
+
+### 8. Erfolg und Konsistenz in M6
+
+- `SUCCESS` darf erst gesetzt werden, wenn:
+  1. die Zielkopie erfolgreich geschrieben wurde,
+  2. der finale Zieldateiname bestimmt ist,
+  3. die zugehörige Persistenz konsistent fortgeschrieben wurde.
+- Es darf **kein** Fall entstehen, in dem ein Dokument als `SUCCESS` persistiert ist, ohne dass die Zielkopie erfolgreich vorliegt.
+- Wenn die Persistenz nach erfolgreicher Zielkopie scheitert, ist **kein** `SUCCESS` zu setzen; ein best-effort Rückbau der neu erzeugten Zielkopie ist in M6 zweckmäßig und architekturtreu vorzusehen.
+- Wenn dieser Rückbau selbst nur teilweise gelingt, bleibt der Fall ein **dokumentbezogener technischer Fehler**; M6 erfindet daraus weder einen Erfolg noch eine neue finale Fehlerkategorie.
+
+### 9. Fehlersemantik in M6
+
+- Technische Fehler bei Proposal-Quelllesung, Zielpfadbildung, Dublettenauflösung, Zielkopie oder M6-relevanter Persistenz nach erfolgreicher Fingerprint-Ermittlung sind in M6 **dokumentbezogene technische Fehler**.
+- Diese Fehler bleiben retryable und laufen über den **Transientfehlerzähler**.
+- M6 führt **keine** neue finale Fehlerkategorie nur für Zielkopierfehler ein.
+- Dokumentbezogene M6-Fehler dürfen den Batch-Lauf für andere Dokumente nicht unnötig abbrechen.
+
+### 10. Kein Vorgriff auf M7
+
+M6 liefert den vollständigen Erfolgspfad für Dateinamensbildung, Dublettenbehandlung und Zielkopie, aber ausdrücklich **nicht**:
+
+- den technischen Sofort-Wiederholversuch beim Schreiben,
+- den finalen Logging-Feinschliff,
+- die vollständige Betriebsrobustheit und Retry-Ausarbeitung des Endstands.
+
+---
+
+## AP-001 M6-Kernobjekte, Zielerfolgssemantik und Port-Verträge präzisieren
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M6-Startpunkt.
+
+### Ziel
+Die M6-relevanten Typen, Erfolgskriterien, Zielartefakt-Begriffe und Port-Verträge werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können.
+
+### Muss umgesetzt werden
+- Neue M6-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für:
+  - finalen Dateinamenkandidaten,
+  - Dublettenauflösung bzw. Namenskollision,
+  - Zielartefakt-Planung,
+  - Zielschreib-Ergebnis,
+  - M6-bezogene Persistenzdaten für den Enderfolg,
+  - lesbaren führenden Benennungsvorschlag aus dem neuesten `PROPOSAL_READY`-Versuch,
+  - inkonsistenten Proposal-Quellzustand.
+- Die M6-Statussemantik in JavaDoc und ggf. `package-info` so schärfen, dass klar ist:
+  - `PROPOSAL_READY` ist M6-verarbeitbar,
+  - `SUCCESS` ist nur nach echter Zielkopie plus konsistenter Persistenz zulässig,
+  - `SUCCESS` und `FAILED_FINAL` bleiben terminale Skip-Zustände,
+  - ein inkonsistenter Zustand `PROPOSAL_READY` ohne lesbare führende Versuchsdaten ein technischer Dokumentfehler ist,
+  - ein M6-Endversuch zusätzlich zum Proposal-Versuch historisiert wird und diesen nicht ersetzt.
+- Outbound-Ports definieren oder gezielt erweitern für:
+  - Laden des führenden `PROPOSAL_READY`-Versuchs,
+  - technische Dublettenauflösung im Zielordner,
+  - Zielkopie/Schreiboperation,
+  - Persistenz der M6-Zieldaten.
+- Port-Verträge so schneiden, dass **weder `Path`/`File` noch NIO-/JDBC-Typen** in Domain oder Application durchsickern.
+- Rückgabemodelle so anlegen, dass spätere Arbeitspakete ohne Zusatzannahmen unterscheiden können zwischen:
+  - nutzbarem führenden Benennungsvorschlag,
+  - fehlendem oder inkonsistentem Proposal-Quellzustand,
+  - erfolgreicher Dublettenauflösung,
+  - technischem Zielschreibfehler,
+  - technischem Persistenzfehler nach Zielkopie,
+  - konsistentem M6-Enderfolg.
+- Explizit dokumentieren, dass M6 **keine zweite Wahrheitsquelle** für Datum, Titel und Reasoning einführt.
+- Explizit dokumentieren, dass M6 **keinen Sofort-Wiederholversuch** der Zielkopie einführt.
+
+### Explizit nicht Teil
+- konkrete Dateisystem-Implementierung
+- konkrete SQLite-Schemaänderungen
+- Batch-Integration
+- reale Zielkopie
+- Tests für das Endverhalten
+
+### Fertig wenn
+- die M6-relevanten Typen und Port-Verträge vorhanden sind,
+- Zielerfolg, Proposal-Quelle, inkonsistente Proposal-Zustände und technische Fehlerarten klar unterscheidbar modelliert sind,
+- Domain und Application frei von Infrastrukturtypen bleiben,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Technische Dateinamensbildung für den finalen M6-Basisnamen implementieren
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Aus dem führenden M5-Benennungsvorschlag kann ein technischer, finaler M6-Basisdateiname im Zielformat erzeugt werden, ohne bereits eine physische Zielkopie oder Dublettenauflösung im Dateisystem auszuführen.
+
+### Muss umgesetzt werden
+- Einen M6-Baustein für die technische Dateinamensbildung implementieren.
+- Das verbindliche Zielformat exakt umsetzen:
+
+```text
+YYYY-MM-DD - Titel.pdf
+```
+
+- Den Basistitel aus dem führenden M5-Benennungsvorschlag übernehmen und technisch in einen final verwendbaren M6-Basisdateinamen überführen.
+- Die fachliche Titelregel **„keine Sonderzeichen außer Leerzeichen“** im M6-Kontext explizit absichern:
+  - regulärer Happy-Path: der bereits validierte M5-Titel wird unverändert weiterverwendet,
+  - inkonsistenter Persistenzfall: ein geladener Proposal-Titel, der diese Regel verletzt, wird **nicht** stillschweigend fachlich umgedeutet, sondern als technischer Dokumentfehler behandelt.
+- Windows-unzulässige Zeichen kontrolliert entfernen oder ersetzen, **soweit dies ausschließlich der technischen Dateisystemzulässigkeit dient**.
+- Sicherstellen, dass die **20-Zeichen-Regel** ausschließlich für den **Basistitel** gilt und nicht für ein späteres Dubletten-Suffix.
+- Keine neue fachliche Titelinterpretation einführen; M6 baut auf dem bereits validierten M5-Titel auf.
+- Einen defensiven technischen Schutz für inkonsistente Persistenzzustände vorsehen, falls ein geladener Proposal-Titel oder Proposal-Datumswert entgegen der M5-Semantik nicht verwertbar ist.
+- JavaDoc für Zielformat, fachliche Titelregel, Windows-Kompatibilität, Basistitelbegriff und Nicht-Ziele von M6 ergänzen.
+
+### Explizit nicht Teil
+- Dublettenprüfung gegen den Zielordner
+- physische Zielkopie
+- Persistenzänderungen
+- Batch-Orchestrierung
+- Zielpfadbildung im Dateisystem
+
+### Fertig wenn
+- aus einem nutzbaren M5-Benennungsvorschlag deterministisch ein M6-Basisdateiname erzeugt werden kann,
+- das Zielformat exakt eingehalten wird,
+- die fachliche Titelregel und die technische Windows-Kompatibilität **klar getrennt** behandelt werden,
+- inkonsistente Proposal-Daten nicht stillschweigend fachlich bereinigt werden,
+- weiterhin keine physische Zielkopie oder Dublettenauflösung erfolgt,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-003 Zielordnerzugriff, Dublettenauflösung und Zielpfadplanung im Adapter-Out implementieren
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Der Zielordner kann technisch bewertet werden, der erste freie finale Zieldateiname im Zielkontext wird bestimmt und eine konsistente Zielpfadplanung steht für die spätere Kopieroperation bereit.
+
+### Muss umgesetzt werden
+- Dateisystem-Adapter für den Zielordnerzugriff implementieren.
+- Technische Dublettenauflösung im Zielordner umsetzen.
+- Den ersten freien Namen nach folgender Regel bestimmen:
+  - ohne Suffix,
+  - dann `(1)`, `(2)`, … direkt vor `.pdf`.
+- Sicherstellen, dass das Dubletten-Suffix **nicht** in die 20-Zeichen-Regel des Basistitels eingerechnet wird.
+- Die Zielpfadplanung so schneiden, dass sie den finalen Zielnamen und eine technische temporäre Zieldatei im Zielkontext vorbereiten kann.
+- Technische Fehler beim Lesen des Zielordners oder bei der Namensauflösung kontrolliert in den Port-Vertrag überführen.
+- JavaDoc für Zielordnerzugriff, Kollisionserkennung, Suffixlogik und technische Grenzen ergänzen.
+
+### Explizit nicht Teil
+- tatsächliches Kopieren der Datei
+- Persistenz von Zielpfad oder Zieldateiname
+- Batch-Use-Case-Integration
+- M7-Sofort-Wiederholversuch
+
+### Fertig wenn
+- der Zielordner technisch ausgewertet werden kann,
+- der erste freie finale Zieldateiname korrekt bestimmbar ist,
+- eine temporäre und finale Zielpfadplanung bereitsteht,
+- technische Fehler kontrolliert über den Port geliefert werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 Zielkopie mit temporärer Zieldatei und finalem Move/Rename implementieren
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Eine Quelldatei kann als M6-Zielartefakt technisch in den Zielordner kopiert werden, wobei temporäre Zielerzeugung und finaler Move/Rename sauber gekapselt sind.
+
+### Muss umgesetzt werden
+- Einen Adapter-Out für die physische Zielkopie implementieren.
+- Die Zielerzeugung so umsetzen, dass mindestens folgender technischer Ablauf möglich ist:
+  1. Kopie in eine temporäre Zieldatei im Zielkontext,
+  2. finaler Move/Rename auf den zuvor geplanten finalen Zieldateinamen.
+- Sicherstellen, dass die Quelldatei unverändert bleibt.
+- Kontrolliertes technisches Fehlerverhalten mindestens für folgende Fälle umsetzen:
+  - Zielordner nicht schreibbar,
+  - temporäre Zieldatei nicht anlegbar,
+  - Kopieren scheitert,
+  - finaler Move/Rename scheitert,
+  - technische Aufräumarbeiten nach Fehler nur teilweise möglich.
+- Das Ergebnis so modellieren, dass spätere Arbeitspakete zwischen erfolgreicher Zielerzeugung, technischem Schreibfehler und technischem Teil-Cleanup unterscheiden können.
+- JavaDoc für Zielkopie, temporäre Datei, finalen Move/Rename und Quellunverändertheit ergänzen.
+
+### Explizit nicht Teil
+- Statusfortschreibung im Use Case
+- Persistenz von Enderfolg oder Zielpfad
+- Batch-Integration
+- technischer Sofort-Wiederholversuch im selben Lauf
+
+### Fertig wenn
+- eine Zielkopie technisch erzeugt werden kann,
+- temporäre und finale Schreibschritte sauber gekapselt sind,
+- die Quelldatei unverändert bleibt,
+- technische Zielschreibfehler kontrolliert abgebildet werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 SQLite-Schema von M5 nach M6 evolvieren und M6-Zieldaten sowie Proposal-Quelle gezielt nutzbar machen
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Die bestehende M5-Persistenz wird kontrolliert auf den M6-Stand erweitert, sodass Zielpfad, finaler Zieldateiname und der führende `PROPOSAL_READY`-Versuch technisch sauber nutzbar sind, ohne die M5-Historie umzudeuten oder zu überschreiben.
+
+### Muss umgesetzt werden
+- Das bestehende SQLite-Schema **evolvieren**, nicht neu erfinden.
+- Die Schema-Initialisierung so erweitern, dass ein vorhandenes M5-Schema kontrolliert auf den M6-Stand gebracht werden kann.
+- Den Dokument-Stammsatz um die für M6 benötigten Felder erweitern, mindestens für:
+  - letzten Zielpfad,
+  - letzten Zieldateinamen.
+- Die Versuchshistorie um das für M6 benötigte Feld erweitern, mindestens für:
+  - finalen Zieldateinamen.
+- Repository-Mapping so erweitern, dass die neuen M6-Zieldaten technisch schreib- und lesbar sind.
+- Eine gezielte Lesefähigkeit bereitstellen oder erweitern, um den **neuesten Versuch mit `PROPOSAL_READY`** als führende Proposal-Quelle für M6 zu laden.
+- Explizit sicherstellen, dass M6 bei Enderfolg oder technischem M6-Fehler **einen neuen Versuchseintrag** anlegt und den führenden Proposal-Versuch **nicht überschreibt**.
+- Sicherstellen, dass:
+  - bestehende M5-Daten weiterhin lesbar bleiben,
+  - die M6-Erweiterung idempotent initialisierbar ist,
+  - keine M7+-Felder vorweggenommen werden,
+  - keine redundante zweite Persistenzwahrheit für Datum, Titel und Reasoning im Stammsatz entsteht.
+- JavaDoc für Schemaevolution, führende Proposal-Quelle, neue M6-Versuchseinträge, M6-Zieldaten und Rückwärtsverträglichkeit ergänzen.
+
+### Explizit nicht Teil
+- Batch-Use-Case-Integration
+- reale Zielkopie
+- Status- und Zählerentscheidungen im laufenden Dokumentprozess
+- M7-Retry-Ausarbeitung
+
+### Fertig wenn
+- das M5-Schema kontrolliert auf M6 erweitert werden kann,
+- Zielpfad und Zieldateiname technisch persistierbar sind,
+- der neueste `PROPOSAL_READY`-Versuch gezielt lesbar ist,
+- M6-Enderfolg/-Fehler historisch **zusätzlich** speicherbar sind, ohne den Proposal-Versuch zu ersetzen,
+- bestehende M5-Daten nicht unbrauchbar werden,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-006 M6-Entscheidungslogik und Batch-Integration für Enderfolg, Proposal-Quelle, Skip-Semantik und technische Fehlerfortschreibung umsetzen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Der bestehende M5-Lauf wird zu einem echten M6-Lauf erweitert, der aus geeigneten Dokumenten eine korrekt benannte Zielkopie erzeugt, den Enderfolg als `SUCCESS` persistiert und technische M6-Fehler sauber im vorhandenen Zähler- und Statusrahmen fortschreibt.
+
+### Muss umgesetzt werden
+- Den bestehenden Batch-Use-Case so erweitern, dass pro geeignetem Dokument zusätzlich gilt:
+  1. terminale Skip-Fälle auswerten,
+  2. falls nötig den M5-Pfad bis zu einem gültigen `PROPOSAL_READY` durchlaufen,
+  3. bei vorhandenem `PROPOSAL_READY` den führenden Proposal-Versuch laden,
+  4. finalen Basisdateinamen bilden,
+  5. Dubletten-Suffix im Zielordner bestimmen,
+  6. Zielkopie erzeugen,
+  7. **einen neuen M6-Versuch** für Enderfolg oder technischen Fehler historisieren,
+  8. Stammsatz konsistent fortschreiben.
+- Sicherstellen, dass **kein neuer KI-Aufruf** erfolgt, wenn bereits ein nutzbarer `PROPOSAL_READY`-Versuch vorliegt.
+- Sicherstellen, dass ein Dokument mit Status `PROPOSAL_READY` im M6-Lauf **nicht** fälschlich übersprungen wird, sondern in die M6-Finalisierung geht.
+- Folgende Regeln explizit umsetzen:
+  - `SUCCESS` → kein erneuter fachlicher Durchlauf, stattdessen `SKIPPED_ALREADY_PROCESSED`
+  - `FAILED_FINAL` → kein erneuter fachlicher Durchlauf, stattdessen `SKIPPED_FINAL_FAILURE`
+  - gültige Zielkopie plus konsistente Persistenz → `SUCCESS`
+  - technischer Fehler bei Proposal-Quelllesung, inkonsistentem Proposal-Zustand, Zielpfadbildung, Dublettenauflösung, Zielkopie oder M6-Persistenz → `FAILED_RETRYABLE`, **Transientfehlerzähler +1**
+- Sicherstellen, dass der finale Zieldateiname und der Zielpfad bei echtem Enderfolg konsistent persistiert werden.
+- Sicherstellen, dass bei erfolgreicher Zielkopie, aber scheiternder Persistenz **kein** `SUCCESS` entsteht.
+- Für den Fall einer nachgelagerten Persistenzstörung nach bereits erzeugter Zielkopie einen **best-effort Rückbau** des neu erzeugten Zielartefakts vorsehen, ohne M7-Retry-Verhalten vorwegzunehmen.
+- Sicherstellen, dass dokumentbezogene M6-Fehler den Batch-Lauf für andere Dokumente kontrolliert weiterlaufen lassen.
+- JavaDoc für M6-Laufreihenfolge, Proposal-Quelle, echte Enderfolgssemantik, neue M6-Historisierung, Skip-Regeln und Fehlerfortschreibung ergänzen.
+
+### Explizit nicht Teil
+- technischer Sofort-Wiederholversuch der Zielkopie
+- Logging-Feinschliff des Endstands
+- M7-spezifische Retry-Ausarbeitung
+- Reporting oder Auswertung
+
+### Fertig wenn
+- der Batch-Lauf geeignete Dokumente bis zur korrekt benannten Zielkopie verarbeiten kann,
+- bestehende `PROPOSAL_READY`-Dokumente in M6 korrekt finalisiert werden,
+- inkonsistente Proposal-Zustände kontrolliert als technische Dokumentfehler behandelt werden,
+- `SUCCESS` nur nach echter Zielkopie plus konsistenter Persistenz gesetzt wird,
+- M6-Enderfolg und M6-Fehler als **zusätzliche** Historieneinträge entstehen,
+- technische M6-Fehler sauber als retryable fortgeschrieben werden,
+- weiterhin keine M7+-Funktionalität enthalten ist.
+
+---
+
+## AP-007 Bootstrap- und CLI-Anpassungen für Zielordner-Konfiguration, M6-Schemaevolution und vollständige Verdrahtung durchführen
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Der Programmeinstieg ist sauber an den M6-Lauf angepasst; Zielordner-Konfiguration, M6-Schemaevolution und alle neuen M6-Bausteine sind verdrahtet und harte Startfehler führen weiterhin kontrolliert zu Exit-Code 1.
+
+### Muss umgesetzt werden
+- Bootstrap-Verdrahtung auf die neuen M6-Ports, Adapter und Persistenzbausteine erweitern.
+- M6-relevante Konfiguration ergänzen bzw. verdrahten, insbesondere für:
+  - `target.folder`
+- Startvalidierung so ergänzen, dass mindestens geprüft wird:
+  - Zielordner ist vorhanden oder technisch anlegbar,
+  - Zielordner ist als Verzeichnis nutzbar,
+  - Zielordner ist für den M6-Schreibpfad technisch verwendbar,
+  - M6-relevante Persistenzkonfiguration bleibt nutzbar.
+- Die bestehende M5-Schemainitialisierung sauber mit der M6-Schemaevolution kombinieren.
+- Sicherstellen, dass harte Start-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler weiterhin zu **Exit-Code 1** führen.
+- Sicherstellen, dass dokumentbezogene M6-Fehler **nicht** als Startfehler fehlmodelliert werden.
+- JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfiguration, Zielordner-Validierung und Modulgrenzen ergänzen.
+
+### Explizit nicht Teil
+- Logging-Feinschliff des Endstands
+- M7-Retry-Mechanik
+- spätere Betriebsoptimierungen
+
+### Fertig wenn
+- das Programm im M6-Stand vollständig startbar ist,
+- alle M6-Bausteine korrekt verdrahtet sind,
+- die M6-Startvalidierung greift,
+- harte Startfehler weiterhin kontrolliert zu Exit-Code 1 führen,
+- der Build fehlerfrei bleibt.
+
+---
+
+## AP-008 Tests für Dateinamensbildung, Dublettenbehandlung, Zielkopie, Schemaevolution, Proposal-Konsistenz, Statussemantik und M6-Ablauf vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-007 sind abgeschlossen.
+
+### Ziel
+Der vollständige M6-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.
+
+### Muss umgesetzt werden
+- Unit-Tests für die technische Dateinamensbildung implementieren, insbesondere für:
+  - korrektes Zielformat `YYYY-MM-DD - Titel.pdf`,
+  - fachliche Titelregel „keine Sonderzeichen außer Leerzeichen“ im M6-Kontext,
+  - Windows-Zeichenbereinigung,
+  - unveränderte 20-Zeichen-Regel des Basistitels,
+  - unveränderte Wirkung des Dubletten-Suffixes außerhalb des Basistitels.
+- Tests für die Dublettenauflösung im Zielordner implementieren, insbesondere für:
+  - kein vorhandener Konflikt → Basename wird verwendet,
+  - vorhandener Konflikt → `(1)`, `(2)`, …,
+  - Suffix wird unmittelbar vor `.pdf` gesetzt.
+- Adapter-Tests für die Zielkopie ergänzen, insbesondere für:
+  - erfolgreiche Zielerzeugung über temporäre Datei plus finalen Move/Rename,
+  - Quelldatei bleibt unverändert,
+  - technischer Kopierfehler,
+  - technischer Rename-/Move-Fehler,
+  - best-effort Cleanup nach technischem Fehler.
+- Repository- und Schema-Tests gegen SQLite ergänzen, insbesondere für:
+  - Evolution eines M5-Schemas auf M6,
+  - Persistenz und Auslesen von Zielpfad und Zieldateiname im Dokument-Stammsatz,
+  - Persistenz und Auslesen des finalen Zieldateinamens in der Versuchshistorie,
+  - gezieltes Laden des neuesten `PROPOSAL_READY`-Versuchs,
+  - zusätzliche M6-Historisierung ohne Überschreiben des Proposal-Versuchs.
+- Integrationstests für den M6-Ablauf ergänzen, insbesondere:
+  - gültiger M6-Happy-Path endet in `SUCCESS`, **nicht** in `PROPOSAL_READY`,
+  - vorhandenes `PROPOSAL_READY` wird ohne erneuten KI-Aufruf finalisiert,
+  - bestehendes `SUCCESS` wird im Wiederholungslauf historisiert übersprungen,
+  - bestehendes `FAILED_FINAL` wird im Wiederholungslauf historisiert übersprungen,
+  - technischer M6-Zielkopierfehler führt zu retryablem technischem Fehler und erhöht den Transientfehlerzähler,
+  - erfolgreicher Zielschreibpfad mit scheiternder Persistenz führt **nicht** zu `SUCCESS`,
+  - bei M3- oder M5-Vorfehlern erfolgt keine unzulässige M6-Finalisierung,
+  - Status `PROPOSAL_READY`, aber **kein** lesbarer führender Proposal-Versuch führt zu dokumentbezogenem technischem Fehler,
+  - lesbarer Proposal-Versuch mit inkonsistentem Titel- oder Datumswert führt zu dokumentbezogenem technischem Fehler,
+  - es entsteht weiterhin **keine** M7-Sofort-Wiederholung.
+- Tests für Bootstrap- und Startverhalten ergänzen, insbesondere:
+  - ungültige M6-Konfiguration führt zu Exit-Code 1,
+  - nicht nutzbarer Zielordner führt zu Exit-Code 1,
+  - M6-Schemaevolution wird beim Start wirksam,
+  - dokumentbezogene M6-Fehler führen **nicht** zu Exit-Code 1.
+- Den M6-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M7+ prüfen.
+
+### Explizit nicht Teil
+- Tests für M7-Sofort-Wiederholversuch
+- Tests für finalen Logging-Feinschliff
+- Tests für spätere Betriebsoptimierungen
+
+### Fertig wenn
+- die Test-Suite für den M6-Umfang grün ist,
+- die wichtigsten M6-Randfälle einschließlich Proposal-Inkonsistenzen automatisiert abgesichert sind,
+- der definierte M6-Zielzustand vollständig erreicht ist,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete decken den vollständigen M6-Zielumfang aus den verbindlichen Spezifikationen ab und schließen die Brücke von **M5 `PROPOSAL_READY`** zum echten Produktiv-Enderfolg **M6 `SUCCESS`** sauber:
+
+- technische Dateinamensbildung im Format `YYYY-MM-DD - Titel.pdf`
+- explizite Trennung zwischen fachlicher Titelregel und technischer Windows-Kompatibilität
+- Dublettenbehandlung im Zielordner mit `(1)`, `(2)`, …
+- Zielpfadplanung und physische Zielkopie
+- Persistenzerweiterung um Zielpfad und finalen Zieldateinamen
+- Nutzung des neuesten `PROPOSAL_READY`-Versuchs als führende Quelle
+- saubere Statussemantik `PROPOSAL_READY` → `SUCCESS`
+- zusätzliche M6-Historisierung ohne Überschreiben der M5-Proposal-Historie
+- technische Fehlerfortschreibung für Proposal-Quell-, Zielkopier- und Persistenzfehler
+- Tests für Dateinamen, Dubletten, Zielkopie, Proposal-Konsistenz, Schemaevolution und End-to-End-M6-Ablauf
+
+Gleichzeitig bleiben die Grenzen zu M1–M5 sowie zu M7+ gewahrt. Insbesondere werden **kein** Sofort-Wiederholversuch der Zielkopie, **kein** finaler Logging-Feinschliff und **keine** weitergehende Betriebsrobustheit des Endstands vorweggenommen.
@@ -0,0 +1,540 @@
+# M7 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M7 – Fehlerbehandlung, Retry-Logik, Logging und betriebliche Robustheit**.
+
+Die Meilensteine **M1**, **M2**, **M3**, **M4**, **M5** und **M6** werden als vollständig umgesetzt vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter und Bootstrap ändern.
+- Keine Annahmen treffen, die nicht durch dieses Dokument oder die verbindlichen Spezifikationen gedeckt sind.
+- Kein Vorgriff auf **M8+**.
+- Kein Umbau bestehender M1–M6-Strukturen ohne direkten M7-Bezug.
+- Neue Typen, Entscheidungsregeln, Konfigurationswerte, Repository-Erweiterungen und Adapter so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus **klar benennbar, testbar und reviewbar** sind.
+- M7 schärft und vervollständigt die bereits vorhandene Fehler- und Statussemantik aus M3–M6, erfindet sie aber nicht stillschweigend neu.
+- M7 muss vorhandene M4–M6-Datenbestände **weiterhin lesen und korrekt fortschreiben** können.
+- Jeder positive M7-Zwischenstand muss bereits einen **robusten, wiederholt ausführbaren Task-Scheduler-Lauf** liefern, auch wenn der Retry-, Logging- und Exit-Code-Endstand erst mit späteren Arbeitspaketen vollständig erreicht wird.
+- Ein Arbeitspaket darf nur dann auf Repository- oder Persistenzfähigkeiten aufbauen, wenn diese entweder bereits aus M1–M6 vorhanden sind oder im unmittelbar vorhergehenden Arbeitspaket explizit hergestellt wurden.
+
+## Explizit nicht Bestandteil von M7
+
+- neue KI-Funktionalität oder Prompt-Evolution jenseits der robusten Weiterverwendung des M5-Stands
+- neue fachliche Benennungsregeln über M5/M6 hinaus
+- neue Dateisystem-Funktionalität jenseits des M6-Zielkopiepfads und des in M7 konkret geforderten technischen Sofort-Wiederholversuchs
+- Reporting-, Statistik- oder Monitoring-Funktionen
+- Web-UI, REST-API oder Benutzerinteraktion
+- OCR, Inhaltsänderung von PDFs oder manuelle Nachbearbeitung
+- abschließender Gesamt-Feinschliff, großflächige Refactorings oder generelle Qualitätskampagnen aus **M8**
+
+## Verbindliche M7-Regeln für **alle** Arbeitspakete
+
+### 1. M7 schließt die Betriebslücke zwischen M6 und dem finalen Zielbild
+
+M6 liefert den vollständigen Erfolgspfad, aber noch nicht die vollständige betriebliche Robustheit des Endstands. Ab M7 gilt daher verbindlich:
+
+- `SUCCESS` bleibt der echte terminale Enderfolg.
+- `FAILED_FINAL` bleibt der terminale Endfehler.
+- `FAILED_RETRYABLE` darf nur solange bestehen bleiben, wie **mindestens ein weiterer Scheduler-Lauf fachlich zulässig** ist.
+- `SKIPPED_ALREADY_PROCESSED` und `SKIPPED_FINAL_FAILURE` bleiben reine historisierte Skip-Ergebnisse und verändern selbst keine Fehlerzähler.
+- Dokumentbezogene Fehler dürfen den Gesamtbatch nicht unnötig abbrechen.
+
+### 2. Vollständige Retry-Regel für deterministische Inhaltsfehler
+
+Ab M7 gilt die vollständige fachliche Regel über spätere Läufe hinweg:
+
+- deterministische Inhaltsfehler erhalten **genau einen** späteren Wiederholungsversuch,
+- der **erste** historisierte deterministische Inhaltsfehler eines Fingerprints führt zu `FAILED_RETRYABLE`,
+- der **zweite** historisierte deterministische Inhaltsfehler desselben Fingerprints führt zu `FAILED_FINAL`.
+
+Für M7 sind mindestens alle bereits aus M3–M6 konkret erzeugbaren deterministischen Inhaltsfehler in diesen Regelrahmen einzuordnen, insbesondere:
+
+- kein brauchbarer Text,
+- Seitenlimit überschritten,
+- fachlich unbrauchbarer oder generischer Titel,
+- vorhandenes, aber unbrauchbares KI-Datum.
+
+Bereits vorhandene oder künftig im bestehenden Fachmodell erzeugte Mehrdeutigkeitsfälle laufen in denselben deterministischen Inhaltsfehler-Rahmen und erzeugen **kein** unsicheres Ergebnis.
+
+### 3. Vollständige Retry-Regel für transiente technische Fehler
+
+Ab M7 gilt für dokumentbezogene technische Fehler nach erfolgreicher Fingerprint-Ermittlung:
+
+- sie laufen über den **Transientfehlerzähler**,
+- sie bleiben nur bis zum konfigurierten Grenzwert retryable,
+- nach Ausschöpfen der zulässigen transienten Fehlversuche wird der Dokumentstatus `FAILED_FINAL`.
+
+Für die M7-Implementierung ist `max.retries.transient` verbindlich als **maximal zulässige Anzahl historisierter transienter Fehlversuche pro Fingerprint** zu interpretieren. Der Fehlversuch, der diesen Grenzwert erreicht, finalisiert den Dokumentstatus.
+
+Zusätzlich gilt:
+
+- `max.retries.transient` ist ein **ganzzahliger Wert >= 1**.
+- Der Wert `0` ist **ungültige Startkonfiguration**.
+- Beispiel: `1` bedeutet, dass bereits der **erste** historisierte transiente Fehlversuch finalisiert.
+- Beispiel: `2` bedeutet, dass der **erste** historisierte transiente Fehlversuch retryable bleibt und der **zweite** finalisiert.
+
+### 4. Technischer Sofort-Wiederholversuch ist strikt auf den Zielkopierpfad begrenzt
+
+Der in der Zielarchitektur vorgesehene technische Sofort-Wiederholversuch wird in M7 exakt wie folgt umgesetzt:
+
+- **genau ein** zusätzlicher technischer Schreibversuch innerhalb desselben Dokumentlaufs,
+- ausschließlich für Fehler beim physischen Zielkopierpfad aus M6,
+- **kein** erneuter KI-Aufruf,
+- **keine** erneute fachliche Titel-/Datumsableitung,
+- **keine** Ausweitung auf Prompt-Laden, KI-HTTP, SQLite oder sonstige Adapter.
+
+Der Sofort-Wiederholversuch ist ein technischer Mechanismus innerhalb desselben Laufs und **kein** zusätzlicher fachlicher Retry-Lauf im Sinne der laufübergreifenden Retry-Regeln.
+
+### 5. Skip-Semantik des Endstands
+
+Ab M7 gilt vollständig:
+
+- `SUCCESS` wird in späteren Läufen **nicht erneut verarbeitet**, sondern mit `SKIPPED_ALREADY_PROCESSED` historisiert.
+- `FAILED_FINAL` wird in späteren Läufen **nicht erneut verarbeitet**, sondern mit `SKIPPED_FINAL_FAILURE` historisiert.
+- `FAILED_RETRYABLE`, `READY_FOR_AI` und `PROPOSAL_READY` bleiben verarbeitbar, soweit der jeweilige Dokumentzustand dies fachlich zulässt.
+- Ein nach M6 noch offenes `PROPOSAL_READY` darf in M7 weiterhin sauber bis zum echten Enderfolg finalisiert werden.
+
+### 6. Logging-Mindestumfang des Endstands
+
+Das Logging muss ab M7 mindestens folgende Informationen nachvollziehbar liefern:
+
+- Laufstart,
+- Laufende,
+- Lauf-ID,
+- erkannte Quelldatei,
+- Überspringen bereits erfolgreicher Dateien,
+- Überspringen final fehlgeschlagener Dateien,
+- erzeugter Zielname,
+- Retry-Entscheidung,
+- Fehler mit Klassifikation.
+
+Die Logs müssen so geschnitten werden, dass dokumentbezogene Entscheidungen pro Fingerprint bzw. Kandidat nachvollziehbar bleiben, ohne zusätzliche Infrastrukturtypen in Domain oder Application zu ziehen.
+
+Zusätzlich gilt für die Korrelation:
+
+- sobald ein Fingerprint erfolgreich bestimmt wurde, müssen dokumentbezogene Logeinträge diesen Fingerprint oder eine daraus eindeutig ableitbare Referenz enthalten,
+- solange noch kein Fingerprint vorliegt, erfolgt die Korrelation mindestens über Lauf-ID und erkannte Quelldatei bzw. Kandidatenbezug,
+- M7 führt hierfür **keine** neue Persistenz-Wahrheit und **keine** zusätzliche Tracking-Ebene ein.
+
+### 7. Sensibilitätsregel für KI-Inhalte im Logging
+
+Ab M7 gilt verbindlich:
+
+- die vollständige KI-Rohantwort bleibt in **SQLite** speicherbar,
+- die vollständige KI-Rohantwort wird **standardmäßig nicht** ins Log geschrieben,
+- `reasoning` wird ebenfalls **standardmäßig nicht** vollständig ins Log geschrieben,
+- die Ausgabe sensibler KI-Inhalte ist nur über eine **explizite Konfiguration** zulässig,
+- M7 führt hierfür einen klar dokumentierten, booleschen Konfigurationswert ein,
+- der Default muss auf **sicher/nicht loggen** stehen.
+
+Als sensible KI-Inhalte gelten in M7 mindestens:
+
+- vollständige KI-Rohantwort,
+- vollständiges KI-`reasoning`.
+
+### 8. Exit-Code-Endsemantik
+
+Ab M7 ist das Exit-Code-Verhalten final:
+
+- `0`, wenn der Lauf technisch ordnungsgemäß durchgeführt wurde, auch wenn einzelne Dokumente fachlich oder transient fehlgeschlagen sind,
+- `1` nur bei harten Start-, Bootstrap-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehlern.
+
+Dokumentbezogene Fehler dürfen **nicht** als harte Startfehler fehlmodelliert werden.
+
+### 9. Konfigurationsvalidierung des Endstands
+
+M7 vervollständigt die Startvalidierung insbesondere für:
+
+- `max.retries.transient`,
+- M7-relevante Logging-Konfiguration,
+- bestehende M1–M6-Startparameter, soweit sie für einen robusten Batch-Lauf weiterhin zwingend sind.
+
+Ungültige M7-Startkonfiguration verhindert den Laufbeginn und führt zu **Exit-Code 1**.
+
+### 10. Keine zweite Wahrheitsquelle für Fehler- und Retry-Entscheidungen
+
+M7 nutzt weiterhin die bestehende Kombination aus:
+
+- Dokument-Stammsatz für Gesamtstatus und Zähler,
+- Versuchshistorie für einzelne Versuchsdaten und Nachvollziehbarkeit.
+
+M7 führt **keine** parallele, dritte Wahrheitsquelle für Retry-Zustände, Logging-Entscheidungen oder Fehlerhistorien ein.
+
+---
+
+## AP-001 M7-Kernobjekte, vollständige Fehlersemantik und Retry-/Logging-Verträge präzisieren
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M7-Startpunkt.
+
+### Ziel
+Die M7-relevanten Typen, vollständigen Fehler- und Retry-Bedeutungen, Logging-bezogenen Entscheidungsobjekte und technischen Grenzen werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können.
+
+### Muss umgesetzt werden
+- Neue M7-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für:
+  - vollständige Retry-Entscheidung,
+  - Ausschöpfungszustand eines Retry-Rahmens,
+  - technische Sofort-Wiederholungsentscheidung für den Zielkopierpfad,
+  - dokumentbezogene Fehlerklassifikation des Endstands,
+  - Logging-Ereignis bzw. Logging-relevante Dokumententscheidung,
+  - Sensitivitätsentscheidung für KI-Inhalte im Logging.
+- Die bestehende Status- und Fehlersemantik in JavaDoc und ggf. `package-info` so schärfen, dass klar ist:
+  - wann `FAILED_RETRYABLE` noch zulässig ist,
+  - wann ein Dokumentstatus wegen ausgeschöpfter Retry-Regeln in `FAILED_FINAL` übergeht,
+  - dass der technische Sofort-Wiederholversuch **nicht** zum laufübergreifenden Retry-Zähler gehört,
+  - dass dokumentbezogene Fehler den Gesamtbatch nicht zu Exit-Code 1 eskalieren.
+- Application-seitige Verträge definieren oder gezielt erweitern für:
+  - Ableitung der Retry-Entscheidung aus Status, Fehlerart, Zählern und Konfiguration,
+  - Ableitung einer protokollierbaren Dokumententscheidung,
+  - Ableitung der Zielkopier-Sofort-Wiederholung,
+  - Auflösung der Sensitivitätsregel für KI-Logausgaben,
+  - Korrelation dokumentbezogener Logging-Ereignisse ohne Infrastrukturtypen im Kern.
+- Port-Verträge so schneiden, dass weder Log4j2-, NIO-, JDBC- noch HTTP-Typen in Domain oder Application durchsickern.
+- Rückgabemodelle so anlegen, dass spätere Arbeitspakete ohne Zusatzannahmen unterscheiden können zwischen:
+  - retryablem Inhaltsfehler,
+  - finalem Inhaltsfehler,
+  - retryablem technischem Fehler,
+  - finalisiertem technischem Fehler nach ausgeschöpftem Transient-Rahmen,
+  - technischem Zielschreibfehler mit zulässigem Sofort-Wiederholversuch,
+  - dokumentbezogener Entscheidung mit M7-logbarem Ergebnis.
+- Explizit dokumentieren, dass M7 keine neue Persistenz-Wahrheit für Retry-Entscheidungen einführt.
+- Explizit dokumentieren, dass `max.retries.transient` als historisierter Fehlversuchs-Grenzwert interpretiert wird und als gültiger Konfigurationswert nur **Integer >= 1** zulässig ist.
+- Explizit dokumentieren, dass sensible KI-Logausgaben in M7 mindestens vollständige KI-Rohantwort und vollständiges KI-`reasoning` umfassen.
+
+### Explizit nicht Teil
+- konkrete Retry-Implementierung im Batch-Lauf
+- konkrete Log4j2-Konfiguration
+- konkrete Zielkopier-Wiederholung
+- Bootstrap-Anpassungen
+- Tests des Endstands
+
+### Fertig wenn
+- die M7-relevanten Typen und Verträge vorhanden sind,
+- Retry-, Finalisierungs-, Sensitivitäts- und Logging-Korrelationssemantik eindeutig dokumentiert ist,
+- Domain und Application frei von Infrastrukturtypen bleiben,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Vollständige Retry-Entscheidungslogik für deterministische Inhaltsfehler und transiente technische Fehler implementieren
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die fachlich vollständige laufübergreifende Retry-Entscheidung des Endstands ist als klarer, testbarer Baustein im Kern implementiert und kann von Batch-Lauf, Logging und Persistenz konsistent verwendet werden.
+
+### Muss umgesetzt werden
+- Einen zentralen M7-Baustein implementieren, der aus vorhandener Fehlerart, bestehendem Dokumentstatus, Fehlerzählern und Konfiguration die verbindliche Retry-Entscheidung ableitet.
+- Die vollständige deterministische Inhaltsfehlerregel explizit umsetzen:
+  - erster historisierter deterministischer Inhaltsfehler → `FAILED_RETRYABLE`,
+  - zweiter historisierter deterministischer Inhaltsfehler → `FAILED_FINAL`.
+- Die vollständige transiente Fehlerregel explizit umsetzen:
+  - dokumentbezogene technische Fehler bleiben nur bis `max.retries.transient` retryable,
+  - der Fehlversuch, der den Grenzwert erreicht, finalisiert den Status zu `FAILED_FINAL`.
+- Die Randfälle der Grenzwertinterpretation explizit abdecken, insbesondere:
+  - `max.retries.transient = 1`,
+  - Skip-Fälle ohne Zähleränderung,
+  - bereits bestehende M4–M6-Datenbestände mit historischen Fehlerzählern.
+- Die Entscheidungslogik so schneiden, dass sie konsistent für bereits bestehende M4–M6-Datenbestände nutzbar bleibt und keine Sonderbehandlung außerhalb des zentralen Regelwerks erzwingt.
+- Explizit sicherstellen, dass Skip-Fälle keine Fehlerzähler verändern.
+- Explizit sicherstellen, dass der technische Sofort-Wiederholversuch **nicht** in diese laufübergreifende Retry-Entscheidung einfließt.
+- JavaDoc für Regelherkunft, Zählerbedeutung, Grenzwertinterpretation und Nicht-Ziele von M7 ergänzen.
+
+### Explizit nicht Teil
+- Batch-Use-Case-Integration
+- Persistenzfortschreibung im konkreten Dokumentlauf
+- Zielkopier-Wiederholung
+- Logging-Konfiguration
+- Exit-Code-Logik
+
+### Fertig wenn
+- die Retry-Entscheidung zentral und testbar implementiert ist,
+- deterministische und transiente Fehler vollständig und widerspruchsfrei abgedeckt sind,
+- bestehende M4–M6-Zähler- und Statusdaten ohne Sonderlogik anschlussfähig bleiben,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-003 Technischen Sofort-Wiederholversuch für den Zielkopierpfad aus M6 implementieren
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Der in der Zielarchitektur vorgesehene einmalige technische Sofort-Wiederholversuch für Zielkopierfehler wird sauber umgesetzt, ohne KI, Persistenzlogik oder laufübergreifende Retry-Semantik zu vermischen.
+
+### Muss umgesetzt werden
+- Den bestehenden M6-Zielkopierpfad so erweitern, dass bei einem technischen Schreibfehler **genau ein** zusätzlicher technischer Sofort-Wiederholversuch innerhalb desselben Dokumentlaufs möglich ist.
+- Sicherstellen, dass der Sofort-Wiederholversuch ausschließlich für den physischen Zielkopierpfad gilt, insbesondere für:
+  - temporäre Zieldatei nicht anlegbar,
+  - Kopieren scheitert,
+  - finaler Move/Rename scheitert,
+  - technisches Cleanup nach erstem Schreibfehler nur teilweise erfolgreich.
+- Sicherstellen, dass dabei **kein** erneuter KI-Aufruf, **keine** erneute fachliche Proposal-Ableitung und **keine** neue Statusneubewertung außerhalb des M7-Regelrahmens stattfindet.
+- Den Mechanismus so schneiden, dass der zweite technische Versuch mit demselben fachlichen Dokumentkontext läuft und der Batch-Lauf danach genau **ein** dokumentbezogenes Ergebnis für Persistenz und Statusfortschreibung ableiten kann.
+- Technische Aufräumarbeiten zwischen erstem und zweitem Versuch kontrolliert kapseln.
+- JavaDoc für Reichweite, Grenzen und Abgrenzung zu laufübergreifenden Retries ergänzen.
+
+### Explizit nicht Teil
+- endgültige Status- und Zählerfortschreibung im Batch-Lauf
+- Logging-Endstand
+- Bootstrap-Anpassungen
+- Erweiterung auf andere Fehlerarten als Zielkopierschreibfehler
+
+### Fertig wenn
+- genau ein technischer Sofort-Wiederholversuch für Zielkopierfehler möglich ist,
+- kein KI- oder Fachpfad unzulässig erneut ausgelöst wird,
+- das Ergebnis kontrolliert an den späteren Batch-/Persistenzpfad übergeben werden kann,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-004 Logging-Infrastruktur, Korrelation und Sensibilitätsregel für M7 vorbereiten
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die Logging-Infrastruktur ist für den M7-Endstand vorbereitet, die Sensibilitätsregel für KI-Inhalte ist technisch korrekt verdrahtet und dokumentbezogene Ereignisse können später im Batch-Lauf konsistent und eindeutig korreliert geloggt werden.
+
+### Muss umgesetzt werden
+- Die bestehende Logging-Infrastruktur gezielt so erweitern, dass der in M7 geforderte Mindestumfang später ohne zusätzliche Architekturbrüche angebunden werden kann.
+- Einen klar dokumentierten, booleschen Konfigurationswert für sensible KI-Logausgaben einführen und verdrahten.
+- Sicherstellen, dass die vollständige KI-Rohantwort standardmäßig **nicht** geloggt wird.
+- Sicherstellen, dass vollständiges KI-`reasoning` standardmäßig **nicht** vollständig geloggt wird.
+- Sicherstellen, dass die vollständige KI-Rohantwort und das vollständige KI-`reasoning` weiterhin in SQLite verbleiben können und M7 hier keine Reduktion oder Löschung der Nachvollziehbarkeit einführt.
+- Einen M7-tauglichen Mechanismus für dokumentbezogene Log-Korrelation vorbereiten, insbesondere:
+  - Lauf-ID-basierte Korrelation vor erfolgreicher Fingerprint-Ermittlung,
+  - Fingerprint- oder eindeutig ableitbare Dokumentreferenz nach erfolgreicher Fingerprint-Ermittlung.
+- Die logbaren Ereignis- und Entscheidungsmodelle aus AP-001 an die Logging-Infrastruktur anbinden, ohne dass fachliche Entscheidungslogik in technische Logger-Aufrufe zerfällt.
+- Bereits auf dieser Stufe die nicht dokumentgebundenen Pflicht-Logpunkte sauber verdrahten, insbesondere:
+  - Laufstart,
+  - Laufende,
+  - harte Startfehler, soweit auf aktuellem Stand erreichbar.
+- JavaDoc und ggf. `package-info` für Logging-Sensibilität, Korrelation, Mindestumfangsvorbereitung und Architekturgrenzen ergänzen.
+
+### Explizit nicht Teil
+- vollständige Batch-Integration aller dokumentbezogenen M7-Logpunkte
+- Finalisierung der Retry- und Skip-Hooks im Dokumentlauf
+- Startvalidierung des Endstands
+- finale Exit-Code-Verdrahtung
+- Tests des gesamten Endstands
+
+### Fertig wenn
+- die Logging-Infrastruktur den M7-Endstand ohne Zusatzannahmen tragen kann,
+- die Sensibilitätsregel standardmäßig auf „nicht loggen" steht,
+- sensible KI-Inhalte nur über explizite Konfiguration logbar sind,
+- dokumentbezogene Log-Korrelation technisch vorbereitet ist,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-005 Repository-, Persistenz- und Nachvollziehbarkeitsanpassungen für den M7-Endstand ergänzen
+
+### Voraussetzung
+AP-001, AP-002 und AP-004 sind abgeschlossen.
+
+### Ziel
+Die bestehende Persistenz aus M4–M6 unterstützt die vollständige M7-Fehler-, Retry-, Skip- und Logging-Nachvollziehbarkeit ohne neue Wahrheitsquelle und ohne unnötige Schema-Neuerfindung.
+
+### Muss umgesetzt werden
+- Prüfen und gezielt ergänzen, welche Repository-Fähigkeiten für den M7-Endstand tatsächlich fehlen, ohne das bestehende Zwei-Ebenen-Modell neu zu entwerfen.
+- Bestehende Repository-Operationen so erweitern oder schärfen, dass sie für M7 reproduzierbar unterstützen:
+  - Finalisierung ausgeschöpfter Retry-Rahmen,
+  - konsistente Fortschreibung von Inhalts- und Transientfehlerzählern,
+  - historisierte Skip-Ereignisse,
+  - dokumentbezogene Fehlerklassifikation und Retryable-Flag im Endstand,
+  - lesende Auswertung der bestehenden Versuchshistorie, soweit für Retry- und Skip-Entscheidungen zwingend erforderlich,
+  - konsistente Nachvollziehbarkeit zwischen Log-Entscheidung und SQLite-Historie.
+- Falls für den M7-Endstand zusätzliche lesende Auswertungen der bestehenden Versuchshistorie nötig sind, diese gezielt ergänzen, ohne Reporting- oder Statistikfunktionalität vorwegzunehmen.
+- Nur dann eine Schemaevolution vornehmen, wenn sie für den M7-Zielstand **zwingend** erforderlich ist; andernfalls ausdrücklich beim bestehenden M6-Schema bleiben.
+- Sicherstellen, dass bestehende M4–M6-Datenbestände lesbar und korrekt fortschreibbar bleiben.
+- Sicherstellen, dass der spätere Batch-Lauf aus AP-006 alle für M7 notwendigen Persistenzoperationen bereits vorfindet und **keine** impliziten Repository-Erweiterungen mehr nachschieben muss.
+- JavaDoc für Nachvollziehbarkeit, bestehende Persistenz-Wahrheit und M7-Grenzen ergänzen.
+
+### Explizit nicht Teil
+- vollständige Batch-Use-Case-Integration der M7-Regeln
+- neue dritte Persistenzebene
+- Reporting/Analytics
+- Bootstrap-Anpassungen
+- Logging-Framework-Konfiguration
+- M8-Gesamtreview
+
+### Fertig wenn
+- die Persistenz den vollständigen M7-Endstand konsistent unterstützt,
+- keine unnötige Schema-Neuerfindung oder Parallelwahrheit eingeführt wurde,
+- bestehende M4–M6-Datenbestände anschlussfähig bleiben,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-006 M7-Batch-Integration für Skip-Logik, Finalisierung ausgeschöpfter Retries, Logging-Hooks und konsistente Fehlerfortschreibung umsetzen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Der bestehende M6-Lauf wird zum vollständigen M7-Lauf erweitert, der Retry-Entscheidungen, Finalisierung, Skip-Verhalten, Sofort-Wiederholversuch, dokumentbezogene Logging-Hooks und konsistente Status-/Persistenzfortschreibung zusammenführt.
+
+### Muss umgesetzt werden
+- Den bestehenden Batch-Use-Case so erweitern, dass pro Dokument die vollständigen M7-Regeln wirksam werden.
+- Folgende Regeln explizit umsetzen:
+  - `SUCCESS` → kein erneuter fachlicher Durchlauf, stattdessen `SKIPPED_ALREADY_PROCESSED` historisieren,
+  - `FAILED_FINAL` → kein erneuter fachlicher Durchlauf, stattdessen `SKIPPED_FINAL_FAILURE` historisieren,
+  - `FAILED_RETRYABLE`, `READY_FOR_AI` und `PROPOSAL_READY` bleiben verarbeitbar,
+  - deterministische Inhaltsfehler werden nach dem zweiten historisierten Auftreten finalisiert,
+  - transiente technische Fehler werden bei Erreichen des Grenzwerts `max.retries.transient` finalisiert.
+- Sicherstellen, dass der technische Sofort-Wiederholversuch aus AP-003 ausschließlich im Zielkopierpfad wirkt und danach in **genau eine** dokumentbezogene Status- und Persistenzfortschreibung mündet.
+- Sicherstellen, dass dokumentbezogene Fehler und Finalisierungen den Batch-Lauf für andere Dokumente nicht unnötig abbrechen.
+- Sicherstellen, dass Historie und Stammsatz pro identifiziertem Dokument weiterhin konsistent fortgeschrieben werden und kein teilpersistierter M7-Zustand zurückbleibt.
+- Vor-Fingerprint-Fehler weiterhin ausdrücklich **nicht** als SQLite-Versuch historisieren.
+- Die vorbereitete Logging-Infrastruktur aus AP-004 an den fachlich relevanten Batch-Entscheidungspunkten anbinden, so dass der finale M7-Mindestumfang vollständig erreicht wird, insbesondere:
+  - erkannte Quelldatei,
+  - Überspringen bereits erfolgreicher Dateien,
+  - Überspringen final fehlgeschlagener Dateien,
+  - erzeugter Zielname,
+  - Retry-Entscheidung,
+  - Fehler mit Klassifikation.
+- Sicherstellen, dass dokumentbezogene Logs nach erfolgreicher Fingerprint-Ermittlung den Fingerprint oder eine eindeutig ableitbare Referenz enthalten und vor erfolgreicher Fingerprint-Ermittlung mindestens über Lauf-ID und Kandidatenbezug korreliert werden können.
+- JavaDoc für M7-Laufreihenfolge, Finalisierung ausgeschöpfter Retries, Skip-Regeln, Logging-Hooks und Fehlerfortschreibung ergänzen.
+
+### Explizit nicht Teil
+- Bootstrap- und Startvalidierungsanpassungen
+- finale Exit-Code-Verdrahtung
+- End-to-End-Tests
+- M8-Feinschliff
+
+### Fertig wenn
+- der Batch-Lauf die vollständige M7-Retry- und Skip-Semantik umsetzt,
+- ausgeschöpfte Retry-Rahmen zu `FAILED_FINAL` führen,
+- der Sofort-Wiederholversuch korrekt in den Dokumentlauf integriert ist,
+- der finale dokumentbezogene Logging-Mindestumfang des M7-Stands vollständig angebunden ist,
+- dokumentbezogene Fehler den Gesamtbatch kontrolliert weiterlaufen lassen,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-007 Bootstrap-, Startvalidierungs- und Exit-Code-Finalisierung für den M7-Endstand durchführen
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Der Programmeinstieg ist sauber auf den M7-Endstand verdrahtet; die finale Startvalidierung greift, dokumentbezogene Fehler werden korrekt von Startfehlern getrennt und das endgültige Exit-Code-Verhalten ist vollständig umgesetzt.
+
+### Muss umgesetzt werden
+- Bootstrap-Verdrahtung auf die neuen M7-Bausteine erweitern.
+- M7-relevante Konfiguration ergänzen bzw. validieren, insbesondere für:
+  - `max.retries.transient` als **Integer >= 1**,
+  - den booleschen Konfigurationswert für sensible KI-Logausgaben,
+  - bestehende M1–M6-Parameter, soweit sie für den robusten Endstand zwingend benötigt werden.
+- Startvalidierung so vervollständigen, dass ungültige M7-Konfiguration den Lauf **vor** dem Batch-Beginn stoppt.
+- Sicherstellen, dass harte Start-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler weiterhin zu **Exit-Code 1** führen.
+- Sicherstellen, dass dokumentbezogene Fehler aus M3–M7 **nicht** zu Exit-Code 1 eskalieren, solange der Batch-Lauf technisch ordnungsgemäß durchgeführt werden konnte.
+- Die M7-Logging-Verdrahtung so in den Startpfad integrieren, dass Laufstart, Laufende und harte Startfehler nachvollziehbar protokolliert werden.
+- JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfigurationsvalidierung, Exit-Code-Endsemantik und Modulgrenzen ergänzen.
+
+### Explizit nicht Teil
+- komplette Test-Suite
+- M8-Qualitätsmaßnahmen
+- neue fachliche Verarbeitung jenseits des M7-Zielbilds
+
+### Fertig wenn
+- das Programm im M7-Stand vollständig startbar ist,
+- die M7-Startvalidierung greift,
+- das finale Exit-Code-Verhalten vollständig umgesetzt ist,
+- dokumentbezogene Fehler nicht als Startfehler fehlmodelliert werden,
+- der Build fehlerfrei bleibt.
+
+---
+
+## AP-008 Tests für Retry-Abläufe über mehrere Läufe, Sofort-Wiederholversuch, Logging-Sensibilität und Exit-Code-Endverhalten vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-007 sind abgeschlossen.
+
+### Ziel
+Der vollständige M7-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.
+
+### Muss umgesetzt werden
+- Tests für Retry-Abläufe über mehrere Läufe implementieren, insbesondere für:
+  - erster deterministischer Inhaltsfehler → `FAILED_RETRYABLE`,
+  - zweiter deterministischer Inhaltsfehler → `FAILED_FINAL`,
+  - transiente technische Fehler bleiben bis zum konfigurierten Grenzwert retryable,
+  - der transiente Fehlversuch am Grenzwert finalisiert zu `FAILED_FINAL`,
+  - `max.retries.transient = 1` finalisiert beim ersten historisierten transienten Fehlversuch,
+  - `max.retries.transient = 0` wird als ungültige Startkonfiguration abgewiesen.
+- Tests für finale Fehlerzustände ergänzen, insbesondere:
+  - `FAILED_FINAL` wird im Wiederholungslauf historisiert übersprungen,
+  - `SUCCESS` wird im Wiederholungslauf historisiert übersprungen,
+  - Skip-Ereignisse verändern keine Fehlerzähler.
+- Tests für den technischen Sofort-Wiederholversuch im Zielkopierpfad ergänzen, insbesondere:
+  - erster Schreibversuch scheitert, zweiter gelingt,
+  - beide Schreibversuche scheitern,
+  - kein erneuter KI-Aufruf,
+  - kein zusätzlicher laufübergreifender Retry-Zähler durch den Sofort-Wiederholversuch.
+- Tests für Logging-Sensibilitätsregel ergänzen, soweit automatisierbar, insbesondere:
+  - vollständige KI-Rohantwort wird standardmäßig nicht geloggt,
+  - vollständiges KI-`reasoning` wird standardmäßig nicht vollständig geloggt,
+  - vollständige KI-Rohantwort bleibt in SQLite verfügbar,
+  - vollständiges KI-`reasoning` bleibt in SQLite verfügbar,
+  - explizite Freischaltung sensibler KI-Logausgabe wirkt nur kontrolliert.
+- Tests für Logging-Korrelation ergänzen, soweit automatisierbar, insbesondere:
+  - vor erfolgreicher Fingerprint-Ermittlung ist Kandidatenbezug über Lauf-ID und Quelldatei nachvollziehbar,
+  - nach erfolgreicher Fingerprint-Ermittlung tragen dokumentbezogene Logs den Fingerprint oder eine eindeutig ableitbare Referenz.
+- Tests für finales Exit-Code-Verhalten ergänzen, insbesondere:
+  - `0` bei technisch ordnungsgemäßem Lauf trotz dokumentbezogener Fehler,
+  - `1` bei harter ungültiger Startkonfiguration,
+  - `1` bei harten Bootstrap-/Initialisierungsfehlern,
+  - dokumentbezogene Fehler aus M3–M7 führen nicht zu Exit-Code 1.
+- Tests für Konfigurationsvalidierung ergänzen, insbesondere:
+  - ungültiges `max.retries.transient`,
+  - ungültige Logging-Sensitivitätskonfiguration,
+  - M7-Startkonfiguration verhindert bei Ungültigkeit den Laufbeginn.
+- Integrationstests für den vollständigen M7-Ablauf ergänzen, insbesondere:
+  - robuster Happy-Path mit `SUCCESS`,
+  - dokumentbezogene Teilfehler blockieren den Batch nicht,
+  - ausgeschöpfte Retry-Rahmen führen stabil zu terminalen Skip-Folgeläufen,
+  - bestehendes `PROPOSAL_READY` kann weiter bis zum Enderfolg finalisiert werden,
+  - M4–M6-Altbestände bleiben anschlussfähig.
+- Den M7-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M8+ prüfen.
+
+### Explizit nicht Teil
+- M8-Gesamtfreigabe
+- zusätzliche Qualitätskampagnen außerhalb des M7-Zielumfangs
+
+### Fertig wenn
+- die Test-Suite für den M7-Umfang grün ist,
+- die wichtigsten Retry-, Finalisierungs-, Logging-, Korrelation- und Exit-Code-Randfälle automatisiert abgesichert sind,
+- der definierte M7-Zielzustand vollständig erreicht ist,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete decken den vollständigen M7-Zielumfang aus den verbindlichen Spezifikationen ab und schließen die betriebliche Lücke zwischen dem M6-Erfolgspfad und dem final robusten Endstand sauber:
+
+- vollständige Retry-Logik über spätere Läufe
+- saubere Finalisierung nach ausgeschöpften Retry-Rahmen
+- technischer Sofort-Wiederholversuch ausschließlich für Zielkopierfehler
+- vollständige Skip-Semantik für `SUCCESS` und `FAILED_FINAL`
+- finaler Logging-Mindestumfang
+- Sensibilitätsregel für KI-Inhalte im Logging
+- präzise Korrelation zwischen Logs und dokumentbezogenen Entscheidungen
+- finale Exit-Code-Semantik
+- vervollständigte Startvalidierung
+- konsistente Nachvollziehbarkeit in Logs und SQLite
+- Tests für Mehrlauf-Retries, Sofort-Wiederholversuch, Logging-Sensibilität und Exit-Code-Endverhalten
+
+Gleichzeitig bleiben die Grenzen zu M1–M6 sowie zu M8+ gewahrt. Insbesondere werden **keine** neuen Fachfunktionen, **kein** M8-Gesamtfeinschliff und **keine** unnötigen Parallelwahrheiten für Persistenz oder Retry-Zustände eingeführt.
@@ -0,0 +1,583 @@
+# M8 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M8 – Abschlussmeilenstein: Qualitätssicherung, Feinschliff und vollständige Entwicklungsfreigabe**.
+
+Die Meilensteine **M1**, **M2**, **M3**, **M4**, **M5**, **M6** und **M7** werden als vollständig umgesetzt vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter, Bootstrap, Konfiguration, Dokumentation und Tests ändern.
+- Keine Annahmen treffen, die nicht durch die verbindlichen Spezifikationen oder den tatsächlich vorliegenden Code- und Teststand gedeckt sind.
+- Kein Vorgriff auf ein hypothetisches **M9** oder sonstige neue Produktfeatures.
+- Kein großflächiger Umbau bestehender M1–M7-Strukturen ohne nachweisbaren M8-Bezug.
+- M8 ist **review- und konsolidierungsgetrieben**: Es werden nur tatsächlich vorhandene Restlücken, Inkonsistenzen, Dokumentationsdefizite, Testlücken oder Qualitätsprobleme geschlossen.
+- M8 darf bestehende Implementierungen gezielt schärfen, vereinheitlichen oder bereinigen, aber nicht stillschweigend neue Fachregeln erfinden.
+- Jeder positive M8-Zwischenstand muss bereits einen **robusten, vollständig buildbaren und testbaren Endstand** liefern, auch wenn die vollständige Entwicklungsfreigabe erst mit späteren Arbeitspaketen nachgewiesen wird.
+- Ein Arbeitspaket darf nur dann auf neue Prüf-, Test- oder Repository-Fähigkeiten aufbauen, wenn diese bereits aus M1–M7 vorhanden sind oder im unmittelbar vorhergehenden Arbeitspaket explizit geschaffen wurden.
+- Ein M8-Arbeitspaket darf innerhalb seines benannten Themas zuerst **gezielt prüfen** und dann **nur die in genau diesem Thema nachweisbaren Befunde** beheben.
+- Unspezifische Sammelaufträge wie „alles prüfen und alles fixen“ sind **kein** zulässiger Zuschnitt für ein einzelnes Arbeitspaket.
+- Wo ein Arbeitspaket einen Prüfbericht oder Freigabenachweis verlangt, muss dieser **im Repository verbleiben** und auf den real ausgeführten Build-/Teststand bezogen sein.
+
+## Explizit nicht Bestandteil von M8
+
+- neue Fachfunktionalität jenseits des bereits definierten Zielbilds
+- neue Meilensteine, Folgeprodukte oder optionale Komfortfunktionen
+- Web-UI, REST-API, OCR, Benutzerinteraktion oder manuelle Nachbearbeitung
+- Reporting-, Monitoring- oder Statistikfunktionen ohne zwingenden M8-Bezug
+- großflächige Architektur-Neuerfindung statt gezielter Endstandskonsolidierung
+- kosmetische Änderungen ohne nachweisbaren Nutzen für Betrieb, Konsistenz, Verständlichkeit oder Qualität
+- Metrik-Tuning ohne fachlich oder technisch belastbare Begründung
+- pauschale „Aufräumarbeiten“, die nicht an einen konkreten, belegbaren M8-Befund gebunden sind
+
+## Verbindliche M8-Regeln für **alle** Arbeitspakete
+
+### 1. M8 schließt nur reale Restlücken des Endstands
+
+M8 ergänzt keine neue Produktvision, sondern bringt den aus M1–M7 entstandenen Gesamtstand auf einen vollständig konsistenten, dokumentierten und freigabefähigen Abschlusszustand.
+
+Daraus folgt:
+
+- Es werden nur **nachweisbare** Restlücken geschlossen.
+- Spekulative Umbauten ohne konkreten Defekt-, Qualitäts- oder Konsistenzbezug sind unzulässig.
+- Änderungen müssen sich auf die verbindlichen Spezifikationen und den realen Projektstand zurückführen lassen.
+
+### 2. Architekturtreue bleibt unverrückbar
+
+Auch in M8 gilt unverändert:
+
+- strikte hexagonale Architektur,
+- Abhängigkeiten zeigen nach innen,
+- keine Infrastrukturtypen in Domain oder Application,
+- keine direkte Adapter-zu-Adapter-Kopplung,
+- keine neue Parallelstruktur neben dem etablierten Modul- und Port-Modell.
+
+M8 darf bestehende Verstöße beseitigen, aber keine neuen einführen.
+
+### 3. Keine zweite Wahrheitsquelle für fachliche oder technische Kernzustände
+
+Die bereits etablierte Wahrheitsbasis bleibt auch in M8 verbindlich:
+
+- Dokument-Stammsatz für Gesamtstatus und Zähler,
+- Versuchshistorie für einzelne Versuche und Nachvollziehbarkeit,
+- führender `PROPOSAL_READY`-Versuch als Quelle des M5-Benennungsvorschlags,
+- Zielartefaktzustand gemäß M6/M7.
+
+M8 führt **keine** zusätzliche Parallelwahrheit für Status, Retry, Proposal, Zielname, Logging-Entscheidungen oder Ergebnisbewertung ein.
+
+### 4. Dokumentation und Implementierung müssen widerspruchsfrei sein
+
+Ab M8 gilt der Endstand nur dann als korrekt, wenn:
+
+- JavaDoc,
+- `package-info`,
+- Konfigurationsbeispiele,
+- Start- und Betriebsdokumentation,
+- Logging- und Fehlermeldungssemantik,
+- Prüf- und Freigabenachweise,
+- sowie Tests
+
+in ihrer Aussage mit dem tatsächlichen Verhalten des Codes übereinstimmen.
+
+### 5. Testfokus auf Kerninvarianten statt auf Metrik-Kosmetik
+
+M8 vervollständigt die Qualitätssicherung gezielt für die fachlich und technisch tragenden Regeln des Systems, insbesondere für:
+
+- Status- und Retry-Semantik,
+- Persistenzkonsistenz,
+- Dateinamensbildung,
+- Zielkopie,
+- Startvalidierung,
+- Logging-Sensibilität,
+- Mehrlaufverhalten,
+- End-to-End-Abläufe.
+
+Reine Zahlenoptimierung ohne belastbaren Risikobezug ist nicht Ziel von M8.
+
+### 6. Rückwärtsverträglichkeit bestehender Datenbestände bleibt erhalten
+
+M8 muss bestehende M4–M7-Datenbestände weiterhin:
+
+- lesen,
+- korrekt fortschreiben,
+- und konsistent interpretieren
+
+können, soweit dies innerhalb des bereits definierten Zielbilds erforderlich ist.
+
+### 7. Betreiberrelevante Rückmeldungen müssen klar, konsistent und belastbar sein
+
+M8 schärft operator-seitige Rückmeldungen so, dass Start-, Konfigurations-, Dokument- und Fehlerzustände ohne unnötige Interpretation nachvollziehbar sind.
+
+Daraus folgt:
+
+- Fehlermeldungen dürfen weder irreführend noch widersprüchlich sein.
+- Logging und Dokumentation müssen dieselben Kernbegriffe verwenden.
+- Sensible KI-Inhalte bleiben standardmäßig geschützt.
+
+### 8. Vollständige Entwicklungsfreigabe erfordert einen nachweisbaren Gesamtlauf
+
+Der M8-Endstand gilt erst dann als abgeschlossen, wenn nachgewiesen ist, dass mindestens folgende Ebenen zusammenpassen:
+
+- Maven-Reactor-Build,
+- relevante Test-Suiten,
+- Smoke- und Startverhalten,
+- End-to-End-Gesamtablauf,
+- Konfigurationsbeispiele,
+- Dokumentation,
+- Artefakterzeugung.
+
+### 9. M8 darf gezielt bereinigen, aber nicht unkontrolliert refaktorieren
+
+Zulässig sind nur solche Bereinigungen, die unmittelbar einem dieser Ziele dienen:
+
+- Architekturtreue,
+- Konsistenz,
+- Verständlichkeit,
+- Testbarkeit,
+- Stabilität,
+- Dokumentationsklarheit,
+- Freigabefähigkeit.
+
+Großflächige Strukturumbauten ohne unmittelbaren M8-Nutzen sind ausgeschlossen.
+
+### 10. Gesamtprüfung, Blockerbehebung und Abschlussfreigabe sind getrennte Arbeitsschritte
+
+Für die zweistufige KI-Bearbeitung gilt in M8 zusätzlich:
+
+- **integrierte Gesamtprüfung**, **gezielte Release-Blocker-Behebung** und **finale Freigabebestätigung** sind getrennte Arbeitspakete,
+- ein einzelnes Arbeitspaket darf nicht gleichzeitig einen unbeschränkten Gesamtreview durchführen **und** unbegrenzt alle dabei gefundenen Themen beheben,
+- Release-Blocker dürfen nur dann in einem späteren Arbeitspaket behoben werden, wenn sie im unmittelbar vorhergehenden Prüf-Arbeitspaket **konkret nachgewiesen und eingegrenzt** wurden.
+
+---
+
+## AP-001 Architekturgrenzen und code-nahe Endstandsdokumentation finalisieren
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M8-Startpunkt.
+
+### Ziel
+Die Architekturgrenzen des Gesamtstands werden abschließend geschärft und in Code-naher Dokumentation so verankert, dass spätere M8-Arbeitspakete ohne Interpretationsspielraum auf einem konsolidierten Endstandsverständnis aufsetzen können.
+
+### Muss umgesetzt werden
+- Bestehende Modulgrenzen, Verantwortlichkeiten und Abhängigkeitsrichtungen gegen den realen Codebestand prüfen und **nur nachweisbare** M8-relevante Unschärfen oder Verstöße gezielt bereinigen.
+- JavaDoc und `package-info` dort vervollständigen oder schärfen, wo für den Endstand noch Lücken oder Widersprüche bestehen, insbesondere für:
+  - Domain-Verantwortung,
+  - Application-Orchestrierung,
+  - Port-Zwecke,
+  - Adapter-Verantwortung,
+  - Bootstrap-Aufgaben,
+  - Endstandsbegriffe wie Status, Retry, Proposal-Quelle, Zielerfolg und Nachvollziehbarkeit.
+- Sicherstellen, dass Architekturgrenzen in der Dokumentation dieselben Begriffe und dieselbe Semantik verwenden wie die implementierte Logik aus M1–M7.
+- Nachweisbare, code-seitig sichtbare Grenzverletzungen nur dort korrigieren, wo sie für M8-Freigabe, Wartbarkeit oder Spezifikationstreue relevant sind.
+- Änderungen in Produktionscode auf **architekturbezogene** Korrekturen begrenzen; keine operator-seitigen Meldungstexte, keine Persistenzbereinigung und keine Testkampagne dieses Arbeitspakets vorwegnehmen.
+- Die für den Endstand verbindlichen Architektur- und Begriffsinvarianten so dokumentieren, dass KI 1 daraus für nachfolgende Arbeitspakete einen präzisen Prompt ableiten kann.
+
+### Explizit nicht Teil
+- neue Fachfunktionalität
+- neue Persistenzmodelle oder neue Port-Landschaften ohne Defektbezug
+- großflächige Umstrukturierungen ohne nachweisbaren Architekturverstoß
+- operator-seitige Logging-/Fehlermeldungsüberarbeitung
+- vollständige Testergänzung oder Dokumentationskonsolidierung außerhalb der code-nahen Architekturgrundlage
+
+### Fertig wenn
+- die Architekturgrenzen des Endstands im Code und in der code-nahen Dokumentation klar, konsistent und belastbar beschrieben sind,
+- nachweisbare M8-relevante Architekturverstöße gezielt bereinigt sind,
+- spätere M8-Arbeitspakete ohne Grundsatzunklarheiten aufsetzen können,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Status-, Persistenz-, Proposal- und Zielzustandskonsistenz des Endstands bereinigen
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die letzte Konsistenzlücke zwischen Dokument-Stammsatz, Versuchshistorie, Proposal-Quelle, Zielartefaktzustand und Adapterverhalten wird geschlossen, ohne neue Wahrheitsquellen oder neue Fachregeln einzuführen.
+
+### Muss umgesetzt werden
+- Den realen Gesamtstand aus M4–M7 gezielt auf **nachweisbare** Inkonsistenzen prüfen, insbesondere zwischen:
+  - Gesamtstatus im Dokument-Stammsatz,
+  - Fehlerzählern,
+  - historisierten Versuchsdaten,
+  - führender `PROPOSAL_READY`-Quelle,
+  - persistierten Zielartefaktdaten,
+  - Adapter-Ergebnissen in Rand- und Fehlerfällen.
+- Tatsächlich vorhandene Inkonsistenzen im Endstand gezielt bereinigen, insbesondere wenn sie zu widersprüchlichem Mehrlaufverhalten, unstimmiger Persistenzfortschreibung oder fehleranfälliger M6/M7-Finalisierung führen können.
+- Sicherstellen, dass M4–M7-Datenbestände weiterhin lesbar und korrekt fortschreibbar bleiben.
+- Sicherstellen, dass keine redundante zweite Persistenzwahrheit für Proposal-, Retry-, Ziel- oder Fehlerzustände entsteht.
+- Nachweisbare Semantiklücken zwischen Repository-Verhalten und Use-Case-Entscheidungen nur soweit schließen, wie sie für den M8-Endstand kritisch sind.
+- Unmittelbar betroffene JavaDoc-, Mapping- und Teststellen mitziehen, aber keine operator-seitige Textschärfung oder allgemeine Testkampagne dieses Arbeitspakets vorwegnehmen.
+
+### Explizit nicht Teil
+- neue Fachregeln über M1–M7 hinaus
+- Reporting-, Statistik- oder Analysefunktionen
+- großflächige Schema-Neuerfindung ohne zwingenden M8-Bedarf
+- Logging-Feinschliff oder Dokumentationskonsolidierung außerhalb des Konsistenzbezugs
+- integrierte Gesamtprüfung des vollständigen Release-Kandidaten
+
+### Fertig wenn
+- nachweisbare Inkonsistenzen zwischen Statusmodell, Persistenz, Proposal-Quelle, Zielartefaktzustand und Adapterverhalten beseitigt sind,
+- Mehrlaufverhalten, Proposal-Quelle und Zielartefaktzustand konsistent zusammenwirken,
+- keine neue Parallelwahrheit eingeführt wurde,
+- der Stand weiterhin fehlerfrei buildbar ist.
+
+---
+
+## AP-003 Betreiberrelevante Logging-, Fehlertext- und Startvalidierungsrückmeldungen des Endstands schärfen
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Die nach außen sichtbaren Rückmeldungen des Systems werden sprachlich und inhaltlich so geschärft, dass Betrieb, Fehlersuche und Freigabe des Endstands ohne unnötige Mehrdeutigkeit möglich sind.
+
+### Muss umgesetzt werden
+- Bestehende Logging- und Fehlermeldungen für Start-, Konfigurations-, Dokument- und Laufzustände auf **nachweisbare** Unschärfen, Widersprüche, missverständliche Formulierungen oder inkonsistente Begriffsnutzung prüfen.
+- Betreiberrelevante Meldungen gezielt nachschärfen, insbesondere für:
+  - harte Start- und Konfigurationsfehler,
+  - dokumentbezogene Fehlerklassifikation,
+  - Retry-Entscheidungen,
+  - Skip-Fälle,
+  - Proposal- und Zielerfolgszustände,
+  - Laufstart und Laufende.
+- Sicherstellen, dass die M7-Sensibilitätsregel für KI-Inhalte sprachlich und technisch konsistent bleibt und nicht durch irreführende Logs oder Fehlermeldungen unterlaufen wird.
+- Startvalidierungsfehler so strukturieren, dass sie klare Betreiberhinweise liefern, ohne technische Interna oder falsche Ursachenketten zu suggerieren.
+- Terminologie zwischen Logging, Exception-Texten, Konfigurationsvalidierung und dokumentierter Semantik vereinheitlichen.
+- Falls dafür gezielte technische Verdrahtungs- oder Formatierungsanpassungen erforderlich sind, diese minimal und architekturtreu umsetzen.
+- Nur die für diese Rückmeldungen unmittelbar nötigen Tests ergänzen oder schärfen.
+
+### Explizit nicht Teil
+- neues Logging-Framework oder neue Telemetrieebenen
+- neue Betriebsfeatures ohne M8-Bezug
+- umfassende Dokumentationskonsolidierung außerhalb der operator-seitigen Rückmeldungen
+- vollständige End-to-End-Testergänzung
+- Coverage-/PIT-Kampagne
+
+### Fertig wenn
+- Logging- und Fehlerrückmeldungen des Endstands klar, konsistent und belastbar sind,
+- Betreiberrelevante Zustände ohne unnötige Interpretation nachvollziehbar bleiben,
+- die Sensibilitätsregel für KI-Inhalte weiterhin sauber greift,
+- der Stand fehlerfrei buildbar ist.
+
+---
+
+## AP-004 Konfigurationsbeispiele, Prompt-Bezug sowie Start- und Betriebsdokumentation konsolidieren
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Der Repository-Stand enthält eine konsolidierte, mit dem echten Endverhalten abgestimmte Dokumentations- und Beispielbasis, mit der lokale Starts, Batch-Läufe und Betriebsverständnis ohne implizite Annahmen möglich sind.
+
+### Muss umgesetzt werden
+- Die vorhandenen Konfigurationsbeispiele gegen den realen Endstand prüfen und gezielt vervollständigen oder bereinigen, insbesondere für:
+  - Pflichtparameter,
+  - optionale Parameter,
+  - sinnvolle Beispielwerte,
+  - M7-relevante Logging- und Retry-Konfiguration,
+  - Priorität von Umgebungsvariable gegenüber Properties beim API-Key.
+- Den vorhandenen Prompt-Bezug im Repository konsistent dokumentieren.
+- Falls für einen reproduzierbaren lokalen Start ein Prompt-Beispiel oder ein nachvollziehbares Prompt-Skelett im Repository fehlt, dieses **minimal und endstandskonform** ergänzen.
+- Start-, Konfigurations- und Betriebsdokumentation so konsolidieren, dass mindestens nachvollziehbar beschrieben sind:
+  - benötigte Eingaben,
+  - Start des ausführbaren Artefakts,
+  - Quell- und Zielordnerbezug,
+  - SQLite-Nutzung,
+  - Retry- und Skip-Grundverhalten,
+  - Logging-Grundverhalten,
+  - Umgang mit sensiblen KI-Inhalten im Logging,
+  - Grenzen des Systems.
+- Veraltete, widersprüchliche oder nicht mehr zum Endstand passende Dokumentation gezielt bereinigen.
+- Sicherstellen, dass Konfigurationsnamen, Dateinamen, Beispielpfade und Dokumentationsaussagen mit dem tatsächlichen Code übereinstimmen.
+- Nur dann produktiven Code anfassen, wenn Dokumentation und Code an einem **eindeutig nachweisbaren** Benennungs- oder Konfigurationskonflikt auseinanderlaufen.
+
+### Explizit nicht Teil
+- externe Web-Dokumentation oder Handbücher außerhalb des Repositories
+- neue Fachfunktionalität
+- breit angelegte Code-Refactorings ohne Dokumentationsbezug
+- finale Testlückenschließung
+- integrierte Gesamtprüfung des Release-Kandidaten
+
+### Fertig wenn
+- der Endstand über die im Repository enthaltenen Beispiele und Dokumente nachvollziehbar start- und betreibbar beschrieben ist,
+- Konfigurations- und Prompt-Beispiele zum realen Code passen,
+- veraltete oder widersprüchliche Dokumentation bereinigt ist,
+- der Stand weiterhin fehlerfrei buildbar bleibt.
+
+---
+
+## AP-005 Deterministische End-to-End-Testbasis und wiederverwendbare Testdaten für den Gesamtprozess bereitstellen
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Für den finalen Qualitätsnachweis steht eine robuste, deterministische und wiederverwendbare End-to-End-Testbasis bereit, die den vollständigen Batch-Prozess des Endstands ohne externe Unsicherheiten reproduzierbar abbilden kann.
+
+### Muss umgesetzt werden
+- Eine wiederverwendbare End-to-End-Testbasis für den Gesamtprozess bereitstellen, die mindestens kontrolliert kapselt:
+  - Quellordner,
+  - Zielordner,
+  - temporäre Artefakte,
+  - SQLite-Datei,
+  - Konfiguration,
+  - erforderliche Test-Doubles für externe Abhängigkeiten.
+- Deterministische Testdaten bzw. Testfixturen für zentrale Endstands-Szenarien bereitstellen, insbesondere für:
+  - Happy-Path bis `SUCCESS`,
+  - deterministischen Inhaltsfehler,
+  - transienten technischen Fehler,
+  - Skip nach `SUCCESS`,
+  - Skip nach `FAILED_FINAL`,
+  - vorhandenes `PROPOSAL_READY` mit späterer Finalisierung,
+  - Zielkopierfehler mit M7-Sofort-Wiederholversuch.
+- Sicherstellen, dass die End-to-End-Testbasis keine unkontrollierte Abhängigkeit von externen KI-Diensten, instabilen Dateisystemzuständen oder globalen Laufzeitumgebungen hat.
+- Testhilfen und Fixture-Strukturen so schneiden, dass spätere M8-Testarbeitspakete ohne erneut erfundene Testinfrastruktur darauf aufbauen können.
+- Dokumentieren, welche Endstands-Invarianten durch die End-to-End-Testbasis gezielt nachweisbar gemacht werden.
+
+### Explizit nicht Teil
+- vollständige Schließung aller Test- und Coverage-Lücken
+- willkürliche Testvermehrung ohne Endstandsbezug
+- neue Fachfunktionalität
+- Qualitätsmetriken-Tuning ohne konkreten Testfallbezug
+- globale Release-Freigabeentscheidung
+
+### Fertig wenn
+- eine stabile und deterministische End-to-End-Testbasis vorhanden ist,
+- die relevanten Endstands-Szenarien reproduzierbar vorbereitet werden können,
+- spätere M8-Testarbeitspakete ohne neue Testgrundstruktur anschließen können,
+- der Stand fehlerfrei buildbar ist.
+
+---
+
+## AP-006 Regressionstests für Kernregeln, Randfälle und Konsistenzinvarianten des Endstands vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Die fachlich und technisch tragenden Regeln des Gesamtstands sind automatisiert so abgesichert, dass echte Regressionsrisiken des Produktiv-Endstands zuverlässig erkannt werden.
+
+### Muss umgesetzt werden
+- Gezielt Regressionstests für die tragenden Regeln aus M1–M7 ergänzen oder vervollständigen, insbesondere für:
+  - Status- und Retry-Semantik,
+  - Mehrlaufverhalten,
+  - Skip-Regeln,
+  - Proposal-Quelle,
+  - Dateinamensbildung,
+  - Windows-Kompatibilität,
+  - Dublettenauflösung,
+  - Zielkopie,
+  - Persistenzkonsistenz,
+  - Startvalidierung,
+  - Logging-Sensibilität,
+  - Exit-Code-Endverhalten.
+- Randfälle gezielt absichern, die für den Endstand regressionskritisch sind, insbesondere:
+  - inkonsistente historische Datenzustände im zulässigen M4–M7-Rahmen,
+  - Grenzfälle bei Fehlerzählern,
+  - fehlgeschlagene Persistenz nach technischer Zielkopie,
+  - erneute Läufe nach terminalen Zuständen,
+  - Proposal- und Finalisierungsübergänge.
+- Sicherstellen, dass die Tests reale Endstands-Invarianten prüfen und nicht bloß Implementierungsdetails einfrieren.
+- Bestehende Testlücken dort schließen, wo ohne diese Lücke eine belastbare Entwicklungsfreigabe nicht möglich wäre.
+- Die End-to-End-Testbasis aus AP-005 gezielt wiederverwenden und nicht parallel neu erfinden.
+
+### Explizit nicht Teil
+- rein kosmetische Testergänzungen ohne Risikobezug
+- neue Produktfeatures
+- breitflächige Qualitätsmetriken-Kampagnen ohne konkrete kritische Lücke
+- vollständige Freigabeprüfung des Gesamtprojekts
+
+### Fertig wenn
+- die regressionskritischen Kernregeln des Endstands automatisiert abgesichert sind,
+- Randfälle mit hoher Relevanz für Stabilität, Konsistenz und Mehrlaufverhalten belastbar getestet sind,
+- die Testbasis kohärent und wiederverwendbar bleibt,
+- der Stand fehlerfrei buildbar und testbar ist.
+
+---
+
+## AP-007 Kritische Coverage- und Mutationslücken des Endstands gezielt schließen
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Die Qualitätsabsicherung des Endstands wird dort gezielt nachgehärtet, wo JaCoCo- oder PIT-Ergebnisse noch reale Risiken in den tragenden Entscheidungs- und Fehlerpfaden erkennen lassen.
+
+### Muss umgesetzt werden
+- Die vorhandenen Qualitätsauswertungen des Projekts gezielt auf **fachlich und technisch kritische** Lücken prüfen, insbesondere in Bereichen wie:
+  - Retry-Entscheidung,
+  - Statusfortschreibung,
+  - Persistenzkonsistenz,
+  - Dateinamensbildung,
+  - Zielkopierpfad,
+  - Startvalidierung,
+  - Logging-Sensibilitätsentscheidung.
+- Bedeutungsvolle Lücken oder überlebende Mutationen gezielt durch:
+  - zusätzliche Tests,
+  - kleinere, nachweisbar sinnvolle Implementierungsschärfungen,
+  - oder eng begründete Testfallpräzisierungen
+  schließen.
+- Vorhandene Qualitäts-Gates oder bestehende Qualitäts-Reports für den relevanten Projektstand stabil grün bekommen, soweit dies bereits Teil des Build-Setups ist.
+- Sicherstellen, dass keine Metrik-Kosmetik betrieben wird, etwa durch willkürliche Ausschlüsse oder nicht belastbare Testumgehungen.
+- Nur dann Build- oder Qualitätskonfiguration anfassen, wenn dies für einen korrekten, belastbaren M8-Endstand zwingend erforderlich ist und sachlich begründet werden kann.
+- Änderungen auf die **nachgewiesenen** Hochrisiko-Lücken begrenzen; kein blindes Nachhärten bereits unkritischer Bereiche.
+
+### Explizit nicht Teil
+- blindes Hochschrauben von Kennzahlen ohne Risikobezug
+- großflächige Qualitätsgate-Neuerfindung ohne bestehenden Projektbezug
+- neue Fachfunktionalität
+- Abschlussfreigabe des Gesamtprojekts ohne vorherigen Gesamtprüfnachweis
+
+### Fertig wenn
+- die kritischen Coverage- und Mutationslücken des Endstands gezielt geschlossen sind,
+- verbleibende Qualitätsauswertungen keine offensichtlichen Hochrisiko-Blindstellen mehr zeigen,
+- das Build- und Testsetup belastbar grün bleibt,
+- keine Metrik-Kosmetik eingeführt wurde.
+
+---
+
+## AP-008 Integrierte Gesamtprüfung des Endstands und belastbare Befundliste erstellen
+
+### Voraussetzung
+AP-001 bis AP-007 sind abgeschlossen.
+
+### Ziel
+Der zu diesem Zeitpunkt erreichte Endstand wird ganzheitlich geprüft, und es entsteht eine belastbare, im Repository verbleibende Befundliste, aus der KI 1 für ein mögliches Folge-Arbeitspaket ausschließlich die tatsächlich verbliebenen Release-Blocker ableiten kann.
+
+### Muss umgesetzt werden
+- Den vollständigen Projektstand ganzheitlich gegen die verbindlichen Spezifikationen sowie die Ergebnisse aus M1–M7 prüfen.
+- Den vollständigen Maven-Reactor-Build, relevante Test-Suiten, Smoke-Tests des ausführbaren Artefakts und die maßgeblichen End-to-End-Prüfungen des Endstands tatsächlich ausführen und auswerten.
+- Prüfen und schriftlich festhalten, dass insbesondere zusammenpassen oder wo noch Abweichungen bestehen:
+  - Architektur und Modulgrenzen,
+  - Fachregeln,
+  - Persistenz- und Retry-Semantik,
+  - Dateinamens- und Zielkopierverhalten,
+  - Startvalidierung und Exit-Code,
+  - Logging und Sensibilitätsregel,
+  - Konfigurationsbeispiele,
+  - Betriebs- und Startdokumentation,
+  - Build- und Testartefakte.
+- Eine knappe, im Repository verbleibende Befunddatei ergänzen oder aktualisieren, die:
+  - die tatsächlich ausgeführten Prüfungen benennt,
+  - grüne Bereiche von offenen Punkten trennt,
+  - offene Punkte nach **Release-Blocker** vs. **nicht blockierend** klassifiziert,
+  - pro Release-Blocker den betroffenen Themenbereich eindeutig eingrenzt.
+- Nur die minimal notwendigen Änderungen an Build-/Testhilfen oder Prüfskripten vornehmen, die erforderlich sind, um diese integrierte Gesamtprüfung reproduzierbar auszuführen.
+
+### Explizit nicht Teil
+- pauschale Behebung aller in diesem Gesamtreview entdeckten Themen in demselben Arbeitspaket
+- neue Produktfeatures oder neue Meilensteine
+- nachträgliche Großrefactorings ohne klaren Prüfbezug
+- finale Freigabeerklärung des Projekts
+
+### Fertig wenn
+- der vollständige Endstand ganzheitlich geprüft ist,
+- die tatsächlich ausgeführten Prüfungen belastbar dokumentiert sind,
+- eine klar eingegrenzte Befundliste im Repository vorliegt,
+- eventuelle Release-Blocker für ein Folge-Arbeitspaket präzise genug beschrieben sind,
+- der Stand weiterhin fehlerfrei buildbar ist.
+
+---
+
+## AP-009 Gezielte Release-Blocker aus der integrierten Gesamtprüfung beheben
+
+### Voraussetzung
+AP-008 ist abgeschlossen.
+
+### Ziel
+Nur die in AP-008 konkret nachgewiesenen und eingegrenzten Release-Blocker werden gezielt beseitigt, ohne den Scope des Abschlussmeilensteins erneut zu öffnen.
+
+### Muss umgesetzt werden
+- Ausschließlich die in der Befundliste aus AP-008 als **Release-Blocker** ausgewiesenen Punkte bearbeiten.
+- Die Behebung pro Blocker auf den dort klar benannten Themenbereich begrenzen.
+- Sicherstellen, dass keine nicht belegten Nebenbaustellen oder neuen Qualitätskampagnen in dieses Arbeitspaket hineingezogen werden.
+- Unmittelbar betroffene Tests, Dokumentationsstellen und Konfigurationsbeispiele mitziehen, soweit dies zur konsistenten Behebung des konkreten Blockers nötig ist.
+- Falls AP-008 **keine** Release-Blocker nachgewiesen hat, in diesem Arbeitspaket keine unnötigen Produktionsänderungen vornehmen, sondern die Blockerfreiheit nur konsistent im Repository nachvollziehbar machen.
+- Nach der Blockerbehebung mindestens den für die betroffenen Blocker notwendigen Build-/Testumfang erneut ausführen.
+
+### Explizit nicht Teil
+- Behebung bloß nicht blockierender Schönheitsmängel
+- neue Produktfeatures oder neue Meilensteine
+- erneute globale Gesamtprüfung des kompletten Endstands
+- breitflächige Nachschärfung von Bereichen, die in AP-008 nicht als Blocker eingegrenzt wurden
+
+### Fertig wenn
+- alle in AP-008 nachgewiesenen Release-Blocker gezielt beseitigt oder nachvollziehbar als nicht mehr vorhanden bestätigt sind,
+- keine unnötige Scope-Ausweitung stattgefunden hat,
+- die betroffenen Bereiche wieder fehlerfrei buildbar und testbar sind,
+- der Stand weiterhin übergabefähig ist.
+
+---
+
+## AP-010 Finale Gesamtprüfung, Freigabedokumentation und Abschluss des M8-Endstands durchführen
+
+### Voraussetzung
+AP-001 bis AP-009 sind abgeschlossen.
+
+### Ziel
+Der Gesamtstand wird abschließend als vollständig freigabefähiger Produktiv-Endstand innerhalb des definierten Projektumfangs nachgewiesen und die Entwicklungsfreigabe wird nachvollziehbar dokumentiert.
+
+### Muss umgesetzt werden
+- Den vollständigen Maven-Reactor-Build, die relevanten Test-Suiten, Smoke-Tests des ausführbaren Artefakts und die maßgeblichen End-to-End-Prüfungen des Endstands erneut tatsächlich ausführen und auswerten.
+- Prüfen und bestätigen, dass insbesondere zusammenpassen:
+  - Architektur und Modulgrenzen,
+  - Fachregeln,
+  - Persistenz- und Retry-Semantik,
+  - Dateinamens- und Zielkopierverhalten,
+  - Startvalidierung und Exit-Code,
+  - Logging und Sensibilitätsregel,
+  - Konfigurationsbeispiele,
+  - Betriebs- und Startdokumentation,
+  - Build- und Testartefakte.
+- Eine knappe, im Repository verbleibende Abschluss- bzw. Freigabedokumentation ergänzen oder aktualisieren, die mindestens festhält:
+  - welche Prüfungen tatsächlich ausgeführt wurden,
+  - dass keine bekannten, spezifikationsrelevanten Release-Blocker für den definierten Projektumfang offen sind,
+  - auf welche Artefakte, Tests oder Dokumente sich diese Aussage stützt.
+- Sicherstellen, dass nach diesem Arbeitspaket kein bekannter, spezifikationsrelevanter Blocker für den definierten Projektumfang offen bleibt.
+- Nur dann noch Änderungen am Produktionscode, an Tests oder an Dokumentation vornehmen, wenn im unmittelbaren Abschlussdurchlauf ein **konkret nachweisbarer** Freigabeblocker auftritt, der ohne Scope-Ausweitung minimal behoben werden kann.
+
+### Explizit nicht Teil
+- neue Produktfeatures oder neue Meilensteine
+- nachträgliche Großrefactorings ohne unmittelbaren Freigabeblocker-Bezug
+- beliebige Schönheitskorrekturen ohne Freigaberelevanz
+
+### Fertig wenn
+- der vollständige Endstand ganzheitlich geprüft und freigabefähig ist,
+- Build, Tests, Smoke-Verhalten und End-to-End-Abläufe belastbar grün sind,
+- keine bekannten, spezifikationsrelevanten Release-Blocker mehr offen sind,
+- Dokumentation, Konfiguration und Artefakterzeugung mit dem realen Endstand übereinstimmen,
+- ein fehlerfreier, übergabefähiger Abschlussstand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete decken den vollständigen M8-Zielumfang aus den verbindlichen Spezifikationen ab und schneiden den Abschlussmeilenstein für die zweistufige KI-Bearbeitung präziser als zuvor:
+
+- abschließender Architektur- und Dokumentationsabgleich
+- gezielte Bereinigung realer Restinkonsistenzen im Endstand
+- Schärfung von Logging-, Fehler- und Betreiber-Rückmeldungen
+- Konsolidierung von Konfigurations-, Prompt- und Betriebsdokumentation
+- deterministische End-to-End-Testbasis
+- gezielte Regressionstests für Kernregeln und Randfälle
+- belastbare Schließung kritischer Coverage- und Mutationslücken
+- integrierte Gesamtprüfung mit dokumentierter Befundliste
+- gezielte, klar eingegrenzte Behebung nachgewiesener Release-Blocker
+- abschließende Gesamtprüfung mit nachvollziehbarer Entwicklungsfreigabe
+
+Gleichzeitig bleiben die Grenzen zu M1–M7 gewahrt:
+
+- M8 erfindet keine neue Produktfunktionalität,
+- M8 führt keine zweite Wahrheitsquelle ein,
+- M8 rollt M1/M2-Themen nicht pauschal neu auf, sondern schließt nur reale Restlücken des Endstands,
+- M8 trennt Gesamtprüfung, Blockerbehebung und Freigabe in eigenständige, für KI 1 und KI 2 präzise nutzbare Arbeitsschritte.
@@ -0,0 +1,407 @@
+# M9 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M9 – GUI-Grundgerüst, neues Betriebsmodell und Packaging-Basis**.
+
+Die Meilensteine **M1** bis **M8** sowie der dokumentierte Ist-Stand **V1.1** werden als vollständig umgesetzt und freigegeben vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter, Bootstrap, Build und Tests ändern.
+- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand oder dieses Dokument gedeckt sind.
+- Kein Vorgriff auf **M10+**.
+- Kein Umbau bestehender M1–M8-Strukturen ohne direkten M9-Bezug.
+- Die neue GUI wird als **eigener Inbound-Adapter** umgesetzt und **nicht** in Bootstrap vermischt.
+- Der bestehende **headless Batch-Betrieb** darf weder technisch noch verhaltensseitig still gebrochen werden.
+- Änderungen klein, fokussiert und architekturtreu halten.
+- Neue Typen, CLI-Optionen, Startpfade, Packaging-Anpassungen und Tests so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind.
+- Ein Arbeitspaket darf nur dann auf GUI-Verhalten aufbauen, wenn das technische Startfundament im unmittelbar vorhergehenden Arbeitspaket bereits hergestellt wurde.
+
+## Explizit nicht Bestandteil von M9
+
+- GUI-Konfigurationseditor
+- Willkommenstext und vollständige GUI-Benutzerführung aus M10
+- Öffnen/Speichern/Speichern unter in der GUI
+- Bearbeitung der `.properties`-Inhalte in der GUI
+- Datei-/Ordnerdialoge
+- Provider-ComboBox, Modellabruf oder Modellfeldlogik
+- sofortige Validierung im Editor
+- zentraler Meldungsbereich und feldnahe Fehlermeldungen
+- technische Tests und Korrekturhilfen in der GUI
+- automatische Prompt-Erzeugung
+- DB-/Historienanzeige
+- manueller Verarbeitungslauf aus der GUI
+- EXE
+- Installer
+- offizieller plattformübergreifender GUI-Support
+- neues Konfigurationsformat
+- Änderungen an fachlicher Benennungslogik, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten
+
+## Verbindliche M9-Regeln für **alle** Arbeitspakete
+
+### 1. Betriebsmodell
+
+Ab M9 gilt verbindlich:
+
+- **GUI ist der neue Standardstart**.
+- Über **`--headless`** startet weiterhin der bestehende Batch-/Scheduler-Betrieb.
+- Die Anwendung bleibt **ein einziges ausführbares JAR**.
+- Es gibt in M9 **keine EXE** und **keinen Installer**.
+
+### 2. CLI-Option `--config <pfad>`
+
+Ab M9 gilt verbindlich:
+
+- **`--config <pfad>`** steht für **GUI und headless** zur Verfügung.
+- Wird **headless ohne `--config`** gestartet, bleibt das bisherige Default-Verhalten der Konfigurationsauflösung erhalten.
+- Zeigt **`--config <pfad>` im GUI-Start** auf eine nicht existente Datei:
+  - erscheint eine klare Fehlermeldung,
+  - danach verhält sich die GUI so, als wäre `--config` nicht angegeben worden.
+- Zeigt **`--config <pfad>` im headless Start** auf eine nicht existente Datei, ist das ein **harter Startfehler**; ein stiller Fallback auf das Default-Verhalten ist in diesem Fall unzulässig.
+
+### 3. Modul- und Architekturregel
+
+Ab M9 gilt verbindlich:
+
+- Die Modulstruktur wird um **genau ein neues Modul** erweitert:
+  - `pdf-umbenenner-adapter-in-gui`
+- Die GUI ist ein **Inbound-Adapter**.
+- **Bootstrap** bleibt verantwortlich für:
+  - Startmoduswahl,
+  - Konfigurationsauflösung,
+  - Objektgraph,
+  - kontrollierten Start des passenden Adapters,
+  - Exit-Code-Ableitung bei harten Startfehlern.
+- Domain und Application bleiben frei von JavaFX-Typen.
+
+### 4. JavaFX- und Headless-Isolation
+
+Ab M9 gilt verbindlich:
+
+- JavaFX wird für den GUI-Betrieb **mit dem ausführbaren JAR ausgeliefert**.
+- Der **headless Start** darf **keine externe JavaFX-Installation** voraussetzen.
+- GUI-Code und JavaFX dürfen im **headless Pfad** nicht unnötig früh initialisiert oder geladen werden.
+- Fehlen GUI-Voraussetzungen beim tatsächlichen GUI-Start, ist das ein **kontrollierter GUI-Startfehler** mit klarer Rückmeldung.
+
+### 5. Plattformziel
+
+Ab M9 gilt verbindlich:
+
+- Die GUI wird offiziell nur für **Windows** vorgesehen.
+- Der headless Betrieb bleibt für **Windows Server / Task Scheduler** kompatibel.
+- M9 führt noch keine GUI-Funktionalität ein, die gemappte Laufwerke oder Datei-Dialoge fachlich ausreizt; die technische Grundlage darf dem späteren Windows-zentrierten Pfadverhalten jedoch nicht widersprechen.
+
+### 6. GUI-Zielstand innerhalb von M9
+
+M9 liefert **kein** vollständiges GUI-Produkt, sondern nur ein **technisch lauffähiges Grundgerüst**.
+
+Daraus folgt:
+
+- Es ist eine **minimale JavaFX-GUI-Shell** zulässig und zweckmäßig.
+- Diese Shell dient nur dem Nachweis des GUI-Startpfads.
+- Ein echter Konfigurationseditor ist ausdrücklich erst Gegenstand von **M10**.
+
+### 7. GUI-Threadingmodell
+
+Ab M9 gilt verbindlich für alle V2.0-Meilensteine:
+
+- Jede potenziell blockierende Operation der GUI – insbesondere providerseitiger Modellabruf, providerseitige technische Tests, Pfad- und Dateisystemprüfungen, SQLite-Prüfungen sowie das Lesen und Schreiben der `.properties`-Datei – läuft auf einem **Hintergrund-Worker-Thread**.
+- **UI-Updates erfolgen ausschließlich über den JavaFX Application Thread** (`Platform.runLater`).
+- Die GUI darf während laufender Hintergrund-Operationen **nicht einfrieren**.
+- Diese Regel ist Referenz für alle threadingbezogenen Formulierungen in M9–M13; Wiederholungen sind in einzelnen Meilensteinen nicht erforderlich.
+
+### 8. Exit-Codes
+
+Ab M9 gilt verbindlich für alle V2.0-Meilensteine:
+
+- **Exit-Code `0`**: normale erfolgreiche Beendigung eines headless Laufs sowie für das reguläre Beenden der GUI.
+- **Exit-Code `1`**: harte Start-, Bootstrap-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler, einschließlich ungültiger CLI-Verwendung, nicht existenter `--config`-Datei im headless Start und GUI-Startfehlern vor erfolgreicher Anzeige der Oberfläche.
+- Dokumentbezogene Verarbeitungsfehler im headless Lauf ändern dieses Exit-Code-Modell nicht; sie bleiben Teil des fachlichen Laufresultats wie bereits in V1.1.
+
+### 9. GUI-Logging
+
+Ab M9 gilt verbindlich:
+
+- Der GUI-Adapter nutzt denselben Log4j2-Stack wie der headless Pfad.
+- Logformat und Log-Verzeichnis bleiben gegenüber dem headless Betrieb unverändert.
+- Mindesteintrag für GUI-nahe Ereignisse sind: Start- und Beendigungsereignisse der GUI, Modellabruf-Versuche (Provider, Erfolg/Misserfolg, **ohne API-Key**), Dateischreibvorgänge inkl. Zielpfad, Ergebnisse der Aktionen `Validieren` und `Technische Tests ausführen`, sowie alle schreibenden Korrekturen.
+
+### 10. GUI-Teststrategie
+
+Ab M9 gilt verbindlich für alle V2.0-Meilensteine:
+
+- **View-Modelle und Application-nahe GUI-Logik** werden mit JUnit unit-getestet. Testfokus liegt auf Zustandsübergängen, Validierungsregeln und Datenflüssen, nicht auf Rendering.
+- **GUI-Smoke-Tests** laufen unter **headless JavaFX (Monocle)** in der Maven-Test-Phase. Sie prüfen, dass zentrale GUI-Pfade (Start, Laden, grundlegende Interaktionen) technisch durchlaufen, ohne einen sichtbaren Desktop vorauszusetzen.
+- Es wird **kein TestFX** und **kein weiteres GUI-Testframework** über Monocle hinaus eingeführt.
+- Diese Teststrategie gilt als Referenz für alle testbezogenen Formulierungen in den Arbeitspaketen von M9 bis M13.
+
+### 11. JavaDoc-Standard für V2.0
+
+Ab M9 gilt verbindlich für alle V2.0-Meilensteine:
+
+Für jede **neu hinzugefügte** oder **substanziell geänderte** öffentliche Klasse, öffentliche Methode und jedes neue Java-Package gilt:
+
+- **Klassen-JavaDoc**: Zweck, Verantwortung und Abgrenzung der Klasse.
+- **Methoden-JavaDoc**: Zweck, Parameter, Rückgabewert und dokumentierte Ausnahmen.
+- **`package-info.java`**: pro neuem Package, mit Kurzbeschreibung der Paketverantwortung.
+
+Dieser Standard gilt als Bestandteil jedes „Fertig wenn"-Abschnitts in V2.0. Ein Arbeitspaket ist erst dann fertig, wenn die betroffenen öffentlichen Klassen und Methoden dem JavaDoc-Standard entsprechen.
+
+---
+
+## AP-001 Neues GUI-Modul und Maven-/Reactor-Basis einführen
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M9-Startpunkt.
+
+### Ziel
+Die Projektstruktur wird um ein eigenständiges GUI-Modul erweitert, ohne die bestehende Architektur oder den bisherigen headless Stand zu beschädigen.
+
+### Muss umgesetzt werden
+- Neues Modul **`pdf-umbenenner-adapter-in-gui`** anlegen.
+- Modul korrekt in Parent-POM und Reactor aufnehmen.
+- Abhängigkeiten so schneiden, dass das GUI-Modul als **Inbound-Adapter** auf die bestehenden inneren Schichten aufsetzen kann.
+- JavaFX-Grundabhängigkeiten nur dort einführen, wo sie für das GUI-Modul technisch erforderlich sind.
+- Sicherstellen, dass Domain, Application, Adapter-Out und CLI-Adapter frei von JavaFX-Abhängigkeiten bleiben.
+- Erste neutrale Paket- und Klassenstruktur im neuen Modul anlegen, soweit für einen buildbaren Stand nötig.
+- JavaDoc und `package-info` für die neue Modulverantwortung ergänzen.
+
+### Explizit nicht Teil
+- tatsächlicher GUI-Start
+- CLI-Parsing für neue Optionen
+- Bootstrap-Anpassungen
+- Packaging des gemeinsamen JARs
+- GUI-Inhalt jenseits einer neutralen Modulbasis
+
+### Fertig wenn
+- das neue GUI-Modul im Reactor vorhanden ist,
+- die Abhängigkeitsrichtung architekturtreu bleibt,
+- der Gesamtbuild weiterhin fehlerfrei ist,
+- noch kein M10+-Verhalten vorweggenommen wurde.
+
+---
+
+## AP-002 Startmodus- und CLI-Optionsmodell für GUI, `--headless` und `--config` einführen
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Die Anwendung kann Startmodus und Konfigurationspfad formal eindeutig interpretieren, ohne den bestehenden headless Betrieb zu verlieren.
+
+### Muss umgesetzt werden
+- Technisches Modell für die Startmodi einführen:
+  - GUI-Standardstart,
+  - expliziter `--headless`-Start.
+- Neue CLI-Option **`--config <pfad>`** für beide Startarten einführen.
+- Parsing und Validierung der relevanten Optionen im Startpfad modellieren.
+- Bestehendes Default-Verhalten für headless Starts **ohne** `--config` ausdrücklich erhalten.
+- Klare Behandlung für fehlerhafte CLI-Verwendungen modellieren, insbesondere für:
+  - `--config` ohne Wert,
+  - unbekannte oder widersprüchliche Startparameter, soweit für M9 erforderlich.
+- Rückgabemodell so schneiden, dass Bootstrap daraus kontrolliert GUI-Start, headless Start oder harten Startfehler ableiten kann.
+- JavaDoc für Startmodussemantik und Konfigurationspfadbezug ergänzen.
+
+### Explizit nicht Teil
+- tatsächliches Laden einer GUI-Oberfläche
+- konkrete Behandlung nicht existenter Konfigurationsdateien im fertigen Startfluss
+- Packaging
+- GUI-Benutzerführung
+
+### Fertig wenn
+- Startmodus und Konfigurationspfad technisch eindeutig interpretierbar sind,
+- headless ohne `--config` weiterhin anschlussfähig bleibt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-003 Bootstrap-Verdrahtung für zwei Startpfade und kontrollierte Fehlerableitung erweitern
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Bootstrap kann zwischen GUI und headless sauber umschalten, ohne seine Verantwortung zu überschreiten.
+
+### Muss umgesetzt werden
+- Bootstrap so erweitern, dass es abhängig vom geparsten Startmodus den passenden Inbound-Adapter startet.
+- Sicherstellen, dass der bestehende headless Pfad fachlich und technisch erhalten bleibt.
+- Kontrollierte Fehlerableitung für harte Startfehler ergänzen, soweit M9 dies bereits erfordert.
+- Behandlung des Konfigurationspfadbezugs im Bootstrap vervollständigen.
+- Sicherstellen, dass Bootstrap keine GUI-Fachlogik oder M10-Editorlogik aufnimmt.
+- JavaDoc und `package-info` für aktualisierte Bootstrap-Verantwortung ergänzen.
+
+### Explizit nicht Teil
+- minimale GUI-Shell selbst
+- JavaFX-Packaging
+- GUI-Benutzerführung
+- Dateieditor oder Validierungslogik
+
+### Fertig wenn
+- Bootstrap technisch zwischen GUI und headless umschalten kann,
+- der headless Pfad weiterhin fehlerfrei und anschlussfähig bleibt,
+- harte Startfehler kontrolliert ableitbar sind,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 Minimale JavaFX-GUI-Shell als Standardstartpfad bereitstellen
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Der neue Standardstartpfad führt in eine minimale, technisch saubere JavaFX-GUI-Shell, ohne bereits Editorlogik aus M10 vorzuziehen.
+
+### Muss umgesetzt werden
+- Minimale JavaFX-Einstiegsklasse im GUI-Modul implementieren.
+- Neutrale GUI-Shell bereitstellen, die den erfolgreichen GUI-Start technisch sichtbar macht.
+- Die GUI-Shell so schneiden, dass sie später ohne Architekturbruch zum Konfigurationseditor ausgebaut werden kann.
+- Sicherstellen, dass beim tatsächlichen GUI-Start klare Rückmeldungen für GUI-bezogene Startfehler möglich sind.
+- Sicherstellen, dass die GUI-Shell keine M10-Funktionalität vorwegnimmt, insbesondere:
+  - kein Konfigurationseditor,
+  - keine Dateioperationen,
+  - keine Validierung,
+  - keine Providerbedienung.
+- JavaDoc für Zweck und klare Nicht-Ziele der minimalen GUI-Shell ergänzen.
+
+### Explizit nicht Teil
+- Willkommenstext im finalen V2.0-Sinne
+- bearbeitbare Eingabefelder
+- Buttons **Neu**, **Öffnen**, **Speichern** usw.
+- Meldungsbereich
+- technische Tests
+
+### Fertig wenn
+- die Anwendung im Standardstart in eine minimale GUI-Shell startet,
+- die Shell technisch sauber vom headless Pfad getrennt ist,
+- noch kein M10+-Verhalten implementiert wurde,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 Konfigurationspfad-Semantik für GUI und headless vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Das Verhalten von `--config <pfad>` ist für beide Startarten vollständig, abwärtskompatibel und kontrolliert umgesetzt.
+
+### Muss umgesetzt werden
+- Verhalten für **existierende** Konfigurationsdateien in GUI und headless vervollständigen.
+- Verhalten für **nicht existente** Konfigurationsdateien explizit umsetzen:
+  - GUI: Fehlermeldung, danach GUI-Start wie ohne `--config`
+  - headless: harter Startfehler
+- Sicherstellen, dass das bestehende Default-Verhalten für headless **ohne** `--config` unangetastet bleibt.
+- Kontrollierte Rückmeldungen für problematische Konfigurationspfade ergänzen.
+- Keine GUI-Editorlogik oder Dateibearbeitung einführen; es geht ausschließlich um Startsemantik.
+- JavaDoc für die endgültige M9-Semantik von `--config` ergänzen.
+
+### Explizit nicht Teil
+- Bearbeiten oder Speichern der Konfiguration in der GUI
+- Datei-Dialoge
+- neue Konfigurationswerte
+- inhaltliche Validierung der `.properties`
+
+### Fertig wenn
+- `--config` für GUI und headless kontrolliert funktioniert,
+- die unterschiedlichen Fehlerpfade wie festgelegt umgesetzt sind,
+- headless ohne `--config` weiterhin kompatibel bleibt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-006 Packaging-Basis für gemeinsames JAR mit integrierter JavaFX-Laufzeit herstellen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Das Projekt erzeugt weiterhin genau ein ausführbares Artefakt, das den GUI-Standardstart technisch ermöglicht und den headless Pfad nicht unnötig belastet.
+
+### Muss umgesetzt werden
+- Build-/Packaging-Konfiguration so erweitern, dass weiterhin **ein gemeinsames ausführbares JAR** entsteht.
+- JavaFX-Laufzeit und erforderliche GUI-Bestandteile in das Artefakt integrieren, soweit für den Windows-GUI-Start von M9 erforderlich.
+- Sicherstellen, dass der headless Startpfad keine unnötig frühe JavaFX-Initialisierung erzwingt.
+- Konkret absichern, dass der headless Startpfad ohne Initialisierung der JavaFX-Application-Klasse durchlaufen kann.
+- Packaging so schneiden, dass keine EXE und kein Installer eingeführt werden.
+- Bestehende Artefakterzeugung aus V1.1 nicht still zerstören.
+- Dokumentierende Build-Hinweise ergänzen, soweit für M9 zwingend nötig.
+
+### Explizit nicht Teil
+- vollständige Enddokumentation von V2.0
+- M10-GUI-Funktionalität
+- plattformübergreifendes Packaging
+- EXE-/Installer-Bau
+
+### Fertig wenn
+- weiterhin genau ein ausführbares JAR erzeugt wird,
+- dieses JAR den M9-GUI-Start technisch tragen kann,
+- der headless Startpfad weiterhin anschlussfähig ist und ohne JavaFX-Application-Initialisierung nachweisbar bleibt,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-007 Start-, Fehler- und Packaging-Tests für den vollständigen M9-Zielstand vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Der vollständige M9-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.
+
+### Muss umgesetzt werden
+- Tests für den GUI-Standardstart gemäß der in M9 festgelegten GUI-Teststrategie ergänzen.
+- Tests für **`--headless`** ergänzen.
+- Automatisierten Nachweis ergänzen, dass der headless Start ohne Initialisierung der JavaFX-Application-Klasse durchlaufen kann.
+- Tests für **`--config <pfad>`** in beiden Startarten ergänzen.
+- Negativtests für ungültige oder fehlende Konfigurationspfade ergänzen, insbesondere:
+  - GUI mit nicht existenter Konfigurationsdatei,
+  - headless mit nicht existenter Konfigurationsdatei,
+  - `--config` ohne Wert.
+- Tests ergänzen, die belegen, dass headless ohne `--config` weiterhin das bisherige Default-Verhalten nutzt.
+- Smoke-Tests für die Artefakterzeugung und Packaging-Basis ergänzen.
+- Sicherstellen, dass dokumentbezogene Batch-Funktionalität nicht versehentlich regressiert ist.
+- Den M9-Stand abschließend auf Architekturtreue, Abwärtskompatibilität und Nicht-Vorgriff auf M10+ prüfen.
+
+### Explizit nicht Teil
+- GUI-Editor-Tests aus M10
+- Validierungs- und Modellabruf-Tests aus M11
+- technische Test- und Korrekturhilfe-Tests aus M12
+- Abschlussdokumentation aus M13
+
+### Fertig wenn
+- der vollständige M9-Zielstand automatisiert abgesichert ist,
+- GUI- und headless Startpfade kontrolliert nachgewiesen sind,
+- das gemeinsame JAR reproduzierbar gebaut wird,
+- der definierte M9-Zielzustand vollständig erreicht ist,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete decken den vollständigen Zielumfang von **M9 – GUI-Grundgerüst, neues Betriebsmodell und Packaging-Basis** ab:
+
+- neues GUI-Modul als eigener Inbound-Adapter
+- GUI als Standardstart
+- `--headless` als erhaltener Batch-/Scheduler-Pfad
+- neue CLI-Option `--config <pfad>` für beide Startarten
+- kontrollierte, unterschiedliche Fehlersemantik für GUI und headless bei nicht existenter Konfigurationsdatei
+- saubere Bootstrap-Umschaltung zwischen zwei Startpfaden
+- minimale JavaFX-GUI-Shell als technischer Nachweis des GUI-Starts
+- ein gemeinsames ausführbares JAR mit integrierter JavaFX-Basis
+- Absicherung, dass headless ohne unnötige GUI-Initialisierung weiter nutzbar bleibt
+- Tests für Startverhalten, Fehlerpfade und Packaging
+
+Damit ist M9 bewusst klar von den späteren GUI-Funktionalitäten aus **M10** bis **M13** getrennt und liefert dennoch einen eigenständig lauffähigen, architekturtreuen und reviewbaren Zwischenstand.
@@ -0,0 +1,149 @@
+# V1.1 – Abschlussnachweis
+
+## Datum und betroffene Module
+
+**Datum:** 2026-04-09
+
+**Betroffene Module:**
+
+| Modul | Art der Änderung |
+|---|---|
+| `pdf-umbenenner-application` | Neue Konfigurationstypen (`MultiProviderConfiguration`, `ProviderConfiguration`, `AiProviderFamily`) |
+| `pdf-umbenenner-adapter-out` | Neuer Anthropic-Adapter (`AnthropicClaudeHttpAdapter`), neuer Parser (`MultiProviderConfigurationParser`), neuer Validator (`MultiProviderConfigurationValidator`), Migrator (`LegacyConfigurationMigrator`), Schema-Migration (`ai_provider`-Spalte), aktualisierter OpenAI-Adapter (`OpenAiHttpAdapter`), aktualisierter Properties-Adapter (`PropertiesConfigurationPortAdapter`) |
+| `pdf-umbenenner-bootstrap` | Provider-Selektor (`AiProviderSelector`), aktualisierter `BootstrapRunner` (Migration, Provider-Auswahl, Logging) |
+| `pdf-umbenenner-adapter-in-cli` | Keine fachliche Änderung |
+| `pdf-umbenenner-domain` | Keine Änderung |
+| `config/` | Beispiel-Properties-Dateien auf neues Schema aktualisiert |
+| `docs/betrieb.md` | Abschnitte KI-Provider-Auswahl und Migration ergänzt |
+
+---
+
+## Pflicht-Testfälle je Arbeitspaket
+
+### AP-001 – Konfigurations-Schema einführen
+
+| Testfall | Klasse | Status |
+|---|---|---|
+| `parsesNewSchemaWithOpenAiCompatibleActive` | `MultiProviderConfigurationTest` | grün |
+| `parsesNewSchemaWithClaudeActive` | `MultiProviderConfigurationTest` | grün |
+| `claudeBaseUrlDefaultsWhenMissing` | `MultiProviderConfigurationTest` | grün |
+| `rejectsMissingActiveProvider` | `MultiProviderConfigurationTest` | grün |
+| `rejectsUnknownActiveProvider` | `MultiProviderConfigurationTest` | grün |
+| `rejectsMissingMandatoryFieldForActiveProvider` | `MultiProviderConfigurationTest` | grün |
+| `acceptsMissingMandatoryFieldForInactiveProvider` | `MultiProviderConfigurationTest` | grün |
+| `envVarOverridesPropertiesApiKeyForActiveProvider` | `MultiProviderConfigurationTest` | grün |
+| `envVarOnlyResolvesForActiveProvider` | `MultiProviderConfigurationTest` | grün |
+| Bestehende Tests bleiben grün | `PropertiesConfigurationPortAdapterTest`, `StartConfigurationValidatorTest` | grün |
+
+### AP-002 – Legacy-Migration mit `.bak`
+
+| Testfall | Klasse | Status |
+|---|---|---|
+| `migratesLegacyFileWithAllFlatKeys` | `LegacyConfigurationMigratorTest` | grün |
+| `createsBakBeforeOverwriting` | `LegacyConfigurationMigratorTest` | grün |
+| `bakSuffixIsIncrementedIfBakExists` | `LegacyConfigurationMigratorTest` | grün |
+| `noOpForAlreadyMigratedFile` | `LegacyConfigurationMigratorTest` | grün |
+| `reloadAfterMigrationSucceeds` | `LegacyConfigurationMigratorTest` | grün |
+| `migrationFailureKeepsBak` | `LegacyConfigurationMigratorTest` | grün |
+| `legacyDetectionRequiresAtLeastOneFlatKey` | `LegacyConfigurationMigratorTest` | grün |
+| `legacyValuesEndUpInOpenAiCompatibleNamespace` | `LegacyConfigurationMigratorTest` | grün |
+| `unrelatedKeysSurviveUnchanged` | `LegacyConfigurationMigratorTest` | grün |
+| `inPlaceWriteIsAtomic` | `LegacyConfigurationMigratorTest` | grün |
+
+### AP-003 – Bootstrap-Provider-Auswahl und Umstellung des bestehenden OpenAI-Adapters
+
+| Testfall | Klasse | Status |
+|---|---|---|
+| `bootstrapWiresOpenAiCompatibleAdapterWhenActive` | `AiProviderSelectorTest` | grün |
+| `bootstrapFailsHardWhenActiveProviderUnknown` | `AiProviderSelectorTest` | grün |
+| `bootstrapFailsHardWhenSelectedProviderHasNoImplementation` | `AiProviderSelectorTest` | grün |
+| `openAiAdapterReadsValuesFromNewNamespace` | `OpenAiHttpAdapterTest` | grün |
+| `openAiAdapterBehaviorIsUnchanged` | `OpenAiHttpAdapterTest` | grün |
+| `activeProviderIsLoggedAtRunStart` | `BootstrapRunnerTest` | grün |
+| `existingDocumentProcessingTestsRemainGreen` | `BatchRunEndToEndTest` | grün |
+| `legacyFileEndToEndStillRuns` | `BootstrapRunnerTest` | grün |
+
+### AP-004 – Persistenz: Provider-Identifikator additiv
+
+| Testfall | Klasse | Status |
+|---|---|---|
+| `addsProviderColumnOnFreshDb` | `SqliteAttemptProviderPersistenceTest` | grün |
+| `addsProviderColumnOnExistingDbWithoutColumn` | `SqliteAttemptProviderPersistenceTest` | grün |
+| `migrationIsIdempotent` | `SqliteAttemptProviderPersistenceTest` | grün |
+| `existingRowsKeepNullProvider` | `SqliteAttemptProviderPersistenceTest` | grün |
+| `newAttemptsWriteOpenAiCompatibleProvider` | `SqliteAttemptProviderPersistenceTest` | grün |
+| `newAttemptsWriteClaudeProvider` | `SqliteAttemptProviderPersistenceTest` | grün |
+| `repositoryReadsProviderColumn` | `SqliteAttemptProviderPersistenceTest` | grün |
+| `legacyDataReadingDoesNotFail` | `SqliteAttemptProviderPersistenceTest` | grün |
+| `existingHistoryTestsRemainGreen` | `SqliteAttemptProviderPersistenceTest` | grün |
+
+### AP-005 – Nativer Anthropic-Adapter implementieren und verdrahten
+
+| Testfall | Klasse | Status |
+|---|---|---|
+| `claudeAdapterBuildsCorrectRequest` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterUsesEnvVarApiKey` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterFallsBackToPropertiesApiKey` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterFailsValidationWhenBothKeysMissing` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterParsesSingleTextBlock` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterConcatenatesMultipleTextBlocks` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterIgnoresNonTextBlocks` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterFailsOnEmptyTextContent` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterMapsHttp401AsTechnical` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterMapsHttp429AsTechnical` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterMapsHttp500AsTechnical` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterMapsTimeoutAsTechnical` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `claudeAdapterMapsUnparseableJsonAsTechnical` | `AnthropicClaudeHttpAdapterTest` | grün |
+| `bootstrapSelectsClaudeWhenActive` | `AiProviderSelectorTest` | grün |
+| `claudeProviderIdentifierLandsInAttemptHistory` | `AnthropicClaudeAdapterIntegrationTest` | grün |
+| `existingOpenAiPathRemainsGreen` | alle `OpenAiHttpAdapterTest`-Tests | grün |
+
+### AP-006 – Regression, Smoke, Doku, Abschlussnachweis
+
+| Testfall | Klasse | Status |
+|---|---|---|
+| `smokeBootstrapWithOpenAiCompatibleActive` | `BootstrapSmokeTest` | grün |
+| `smokeBootstrapWithClaudeActive` | `BootstrapSmokeTest` | grün |
+| `e2eMigrationFromLegacyDemoConfig` | `ProviderIdentifierE2ETest` | grün |
+| `regressionExistingOpenAiSuiteGreen` | `ProviderIdentifierE2ETest` | grün |
+| `e2eClaudeRunWritesProviderIdentifierToHistory` | `ProviderIdentifierE2ETest` | grün |
+| `e2eOpenAiRunWritesProviderIdentifierToHistory` | `ProviderIdentifierE2ETest` | grün |
+| `legacyDataFromBeforeV11RemainsReadable` | `ProviderIdentifierE2ETest` | grün |
+
+---
+
+## Belegte Eigenschaften
+
+| Eigenschaft | Nachweis |
+|---|---|
+| Zwei Provider-Familien unterstützt | `AiProviderSelectorTest`, `BootstrapSmokeTest` |
+| Genau einer aktiv pro Lauf | `MultiProviderConfigurationTest`, `BootstrapSmokeTest` |
+| Kein automatischer Fallback | keine Fallback-Logik in `AiProviderSelector` oder Application-Schicht |
+| Fachlicher Vertrag (`NamingProposal`) unverändert | `AiResponseParser`, `AiNamingService` unverändert; beide Adapter liefern denselben Domain-Typ |
+| Persistenz rückwärtsverträglich | `SqliteAttemptProviderPersistenceTest`, `legacyDataFromBeforeV11RemainsReadable` |
+| Migration nachgewiesen | `LegacyConfigurationMigratorTest`, `e2eMigrationFromLegacyDemoConfig` |
+| `.bak`-Sicherung nachgewiesen | `LegacyConfigurationMigratorTest.createsBakBeforeOverwriting`, `e2eMigrationFromLegacyDemoConfig` |
+| Aktiver Provider wird geloggt | `BootstrapRunnerTest.activeProviderIsLoggedAtRunStart` |
+| Keine Architekturbrüche | kein `Application`- oder `Domain`-Code kennt OpenAI- oder Claude-spezifische Typen |
+| Keine neuen Bibliotheken | Anthropic-Adapter nutzt Java HTTP Client und `org.json` (beides bereits im Repo etabliert) |
+
+---
+
+## Betreiberaufgabe
+
+Wer bisher die Umgebungsvariable `PDF_UMBENENNER_API_KEY` oder eine andere eigene Variable für den
+OpenAI-kompatiblen API-Schlüssel eingesetzt hat, muss diese auf **`OPENAI_COMPATIBLE_API_KEY`** umstellen.
+Die Anwendung akzeptiert nur diese kanonische Umgebungsvariable; ältere proprietäre Namen werden
+nicht automatisch ausgewertet.
+
+---
+
+## Build-Ergebnis
+
+Build-Kommando:
+
+```
+.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-bootstrap --also-make
+```
+
+Build-Status: **ERFOLGREICH** — alle Tests grün, Mutationstests in allen Modulen ausgeführt.
@@ -0,0 +1,596 @@
+# V1.1 – Arbeitspakete
+
+> **Aktive Erweiterung:** Zusätzliche KI-Provider-Familie **Anthropic Claude** über die native Messages API, neben der bestehenden OpenAI-kompatiblen Anbindung. Bewusst minimale Erweiterung des freigegebenen Basisstands.
+
+> **Ablage im Repository:** `docs/workpackages/V1.1 - Arbeitspakete.md`
+
+---
+
+## 0. Lesereihenfolge für jedes Arbeitspaket
+
+Vor jedem AP **vollständig** lesen:
+1. `CLAUDE.md`
+2. `docs/specs/technik-und-architektur.md`
+3. `docs/specs/fachliche-anforderungen.md`
+4. dieses Dokument: Abschnitte 1 bis 6
+5. **nur** das aktive Arbeitspaket aus Abschnitt 7
+
+Nicht vorgreifen. Nicht raten. Bei echter Unklarheit knapp benennen statt erfinden.
+
+---
+
+## 1. Arbeitsweise (verbindlich)
+
+Diese Regeln ersetzen die nicht vorhandene `WORKFLOW.md` und gelten für alle APs in diesem Dokument.
+
+### 1.1 Scope-Disziplin
+- Es wird **ausschließlich** das aktive Arbeitspaket umgesetzt.
+- Keine Inhalte späterer Arbeitspakete vorwegnehmen.
+- Keine kosmetischen Refactorings ohne direkten Bezug zum AP.
+- Keine Umbenennungen außerhalb des AP-Scopes.
+- Vor Änderungen die betroffenen Klassen über Typsuche im Repo lokalisieren, **nicht** über vermutete Pfade.
+
+### 1.2 Build- und Testpflicht
+Build-Kommando vom Projekt-Root, identisch für alle APs:
+
+```
+.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-bootstrap --also-make
+```
+
+- Nach jeder substanziellen Änderung: Build ausführen.
+- Vor Abschluss eines AP: Build muss **fehlerfrei** sein, alle Tests grün.
+- Schlägt der Build fehl: Ursache sauber beheben, nicht kaschieren.
+- Bestehende Tests dürfen nicht stillschweigend gelöscht oder deaktiviert werden. Sie werden bei Bedarf **angepasst** und der Grund wird im AP-Output dokumentiert.
+
+### 1.3 Pflicht-Tests pro AP
+- Jede neue Klasse mit fachlich oder technisch relevanter Logik bekommt mindestens einen Unit-Test.
+- Jede in einem AP geänderte Klasse, die bisher Tests hatte, behält Tests; betroffene Tests werden angepasst.
+- Pro AP gibt es eine Liste **kritischer Pflicht-Testfälle** (siehe jeweiliges AP). Diese sind namentlich umzusetzen.
+- Darüber hinaus gilt die übliche Repo-Praxis (Coverage, PIT-Mutationstests in den unmittelbar betroffenen Modulen, soweit bereits etabliert).
+
+### 1.4 Dokumentation
+Pro AP werden mitgepflegt, soweit relevant:
+- JavaDoc und `package-info` der berührten Klassen
+- Konfigurationsbeispiele
+- unmittelbar betroffene Repository-Dokumente
+
+### 1.5 Naming-Regel
+In Code, Kommentaren und JavaDoc dürfen **keine** Versions- oder AP-Bezeichner erscheinen:
+- Verboten: `V1.0`, `V1.1`, `M1`–`M8`, `AP-001` … `AP-006`
+- Stattdessen: zeitlose technische Bezeichnungen.
+
+### 1.6 Pflicht-Output-Format am Ende jedes AP
+Am Ende der AP-Bearbeitung gibt Sonnet **genau** diesen Block aus:
+
+```
+- Scope erfüllt: ja/nein
+- Geänderte Dateien:
+  - <Pfad>
+  - ...
+- Neue Dateien:
+  - <Pfad>
+  - ...
+- Build-Kommando: <verwendetes Kommando>
+- Build-Status: ERFOLGREICH / FEHLGESCHLAGEN
+- Pflicht-Tests umgesetzt: <Liste der namentlich geforderten Testfälle>
+- Offene Punkte: keine / <Beschreibung>
+- Risiken: keine / <Beschreibung>
+```
+
+---
+
+## 2. Erweiterungsziel und Nicht-Ziele
+
+### 2.1 Ziel
+- Der bestehende OpenAI-kompatible KI-Weg bleibt unverändert nutzbar.
+- Zusätzlich wird die **native Anthropic Messages API** als zweite, gleichwertig unterstützte Provider-Familie integriert.
+- Genau **ein** Provider ist pro Lauf aktiv – ausschließlich über Konfiguration.
+- Kein automatischer Fallback, keine Parallelnutzung, keine Profilverwaltung.
+- Der fachliche KI-Vertrag (`NamingProposal`) bleibt unverändert.
+- Bestehende Properties-Dateien werden beim ersten Start kontrolliert ins neue Schema migriert; vorher wird automatisch eine `.bak`-Sicherung angelegt.
+
+### 2.2 Explizit nicht Bestandteil
+- Provider-Familien jenseits der zwei explizit unterstützten
+- Profilverwaltung mit mehreren Konfigurationen je Provider-Familie
+- automatische Fallback-Umschaltung
+- parallele Nutzung mehrerer Provider in einem Lauf
+- Änderung des fachlichen Ergebnisvertrags
+- Änderung der Dateinamensregeln, Retry-Regeln, Batch-Betriebsmodells
+- Persistenz- oder Schemaänderungen jenseits der einen additiven Provider-Identifikator-Spalte
+
+### 2.3 Architekturtreue (unverhandelbar)
+- strikte hexagonale Architektur, Abhängigkeiten zeigen nach innen
+- `AiNamingPort` bleibt provider-neutral
+- provider-spezifische Endpunkte, Header, Auth, Request-/Response-Formate leben **ausschließlich** im jeweiligen Adapter-Out
+- keine direkte Adapter-zu-Adapter-Kopplung, keine gemeinsame „abstrakte KI-Adapter"-Zwischenschicht
+- die Provider-Auswahl ist eine **Bootstrap-Verdrahtungsentscheidung**
+
+---
+
+## 3. Zielzustand der Konfiguration (verbindlich)
+
+### 3.1 Properties-Schema
+```properties
+# bestehende, unveränderte Parameter
+source.folder=...
+target.folder=...
+sqlite.file=...
+max.retries.transient=...
+max.pages=...
+max.text.characters=...
+prompt.template.file=...
+runtime.lock.file=...
+log.directory=...
+log.level=...
+log.ai.sensitive=...
+
+# neue Provider-Auswahl (Pflicht)
+ai.provider.active=openai-compatible
+
+# OpenAI-kompatible Provider-Familie
+ai.provider.openai-compatible.baseUrl=...
+ai.provider.openai-compatible.model=...
+ai.provider.openai-compatible.timeoutSeconds=...
+ai.provider.openai-compatible.apiKey=...
+
+# Anthropic-Provider-Familie (Claude)
+ai.provider.claude.baseUrl=https://api.anthropic.com
+ai.provider.claude.model=...
+ai.provider.claude.timeoutSeconds=...
+ai.provider.claude.apiKey=...
+```
+
+### 3.2 Zulässige Werte für `ai.provider.active`
+- `openai-compatible`
+- `claude`
+
+Jeder andere Wert ist eine ungültige Startkonfiguration und führt zu Exit-Code `1`.
+
+### 3.3 Pflichtwerte je aktivem Provider
+| Provider | Pflicht | Optional / mit Default |
+|---|---|---|
+| `openai-compatible` | `baseUrl`, `model`, `timeoutSeconds`, `apiKey` (Env hat Vorrang) | – |
+| `claude` | `model`, `timeoutSeconds`, `apiKey` (Env hat Vorrang) | `baseUrl` (Default `https://api.anthropic.com`) |
+
+Für den **inaktiven** Provider werden keine Pflichtwerte erzwungen.
+
+### 3.4 Umgebungsvariablen für API-Schlüssel
+| Provider | Umgebungsvariable |
+|---|---|
+| `openai-compatible` | `OPENAI_COMPATIBLE_API_KEY` |
+| `claude` | `ANTHROPIC_API_KEY` |
+
+- Pro Provider gilt: Umgebungsvariable hat **Vorrang** vor dem Properties-Wert derselben Provider-Familie.
+- Schlüssel verschiedener Provider werden **niemals** vermischt.
+- Wenn der Betrieb bisher eine andere Umgebungsvariable für den OpenAI-kompatiblen Key genutzt hat, ist diese vom Betreiber auf `OPENAI_COMPATIBLE_API_KEY` umzustellen. Das ist im Abschlussnachweis (AP-006) zu dokumentieren.
+
+### 3.5 Legacy-Form (vor V1.1)
+Eindeutig erkennbar an mindestens einem der flachen Schlüssel:
+```
+api.baseUrl
+api.model
+api.timeoutSeconds
+api.key
+```
+ohne Vorhandensein von `ai.provider.active`.
+
+---
+
+## 4. Anthropic Messages API – verbindlicher technischer Faktenblock
+
+> Quelle: offizielle Claude API-Dokumentation. Diese Werte sind verbindlich und nicht zu erfinden, abzuleiten oder zu „verbessern".
+
+### 4.1 Endpoint und Methode
+- Methode: `POST`
+- URL: `{baseUrl}/v1/messages`
+- Default-`baseUrl`: `https://api.anthropic.com`
+
+### 4.2 Pflicht-Header
+| Header | Wert |
+|---|---|
+| `x-api-key` | API-Schlüssel aus `ANTHROPIC_API_KEY` (Env) bzw. `ai.provider.claude.apiKey` (Properties) |
+| `anthropic-version` | `2023-06-01` |
+| `content-type` | `application/json` |
+
+Nicht `Authorization: Bearer …` verwenden. Anthropic nutzt `x-api-key`.
+
+### 4.3 Request-Body (relevante Felder)
+```json
+{
+  "model": "<modellname aus ai.provider.claude.model>",
+  "max_tokens": <Integer, > 0, Pflicht>,
+  "system": "<optional, top-level Feld - NICHT als Message mit role=system>",
+  "messages": [
+    { "role": "user", "content": "<Prompt-Text>" }
+  ]
+}
+```
+- `max_tokens` ist **Pflicht** (Unterschied zu OpenAI). Konkreter Wert: zweckmäßig fest verdrahtet im Adapter, ausreichend groß für die JSON-Antwort der Anwendung. Kein neuer Properties-Schlüssel.
+- `system` wird **nicht** als Message mit `role=system` modelliert. Anthropic akzeptiert nur `user` und `assistant` im `messages`-Array; ein System-Prompt geht ausschließlich ins Top-Level-Feld `system`.
+- Der bestehende Prompt der Anwendung wird **unverändert** als Inhalt der einen `user`-Message übergeben. Falls der bestehende Prompt-Mechanismus eine System-Komponente kennt, wandert diese in das `system`-Feld; sonst bleibt `system` weg.
+
+### 4.4 Response-Body (relevante Felder)
+```json
+{
+  "id": "...",
+  "type": "message",
+  "role": "assistant",
+  "content": [
+    { "type": "text", "text": "<die eigentliche Antwort>" }
+  ],
+  "stop_reason": "...",
+  "usage": { "input_tokens": 0, "output_tokens": 0 }
+}
+```
+- Der für die Anwendung relevante Text wird **konkateniert aus allen Blöcken in `content` mit `type == "text"`** in Reihenfolge gewonnen.
+- Andere Block-Typen werden ignoriert.
+- Liefert die API kein einziges `text`-Block, ist das ein technischer Fehler des Adapters (klassifiziert wie ein leerer/unbrauchbarer Antwortinhalt).
+
+### 4.5 Fehlerklassifikation im Claude-Adapter
+| Symptom | Klassifikation | Anmerkung |
+|---|---|---|
+| HTTP 4xx (außer 429) | technischer Fehler | Auth-Fehler (401/403) zählen hier rein |
+| HTTP 429 | technischer Fehler | rate limit |
+| HTTP 5xx | technischer Fehler | |
+| Timeout | technischer Fehler | |
+| Verbindung fehlgeschlagen | technischer Fehler | |
+| JSON nicht parsebar | technischer Fehler | |
+| Kein `content[*].text`-Block | technischer Fehler | |
+| Antworttext nicht nach `NamingProposal` parsebar | greift bestehende Antwort-Validierung der Application | nicht im Adapter behandeln |
+
+Alle technischen Adapterfehler werden auf die **bestehende** transiente Fehlersemantik der Anwendung abgebildet. Es entsteht **keine** neue Fehlerkategorie.
+
+---
+
+## 5. Verbindliche Regeln für jedes AP
+
+1. **Minimale Erweiterung.** Nichts ändern, was nicht für die Erweiterung zwingend erforderlich ist.
+2. **Einheitlicher fachlicher KI-Vertrag.** `NamingProposal` bleibt unverändert. Keine provider-spezifische Verzweigung in Application/Domain.
+3. **Genau ein aktiver Provider.** Kein Fallback, keine Profilverwaltung.
+4. **Properties-Datei bleibt führend.** Keine alternative Konfigurationsquelle.
+5. **Bestehender OpenAI-Pfad bleibt funktional unverändert.**
+6. **Architekturgrenzen** (siehe 2.3) werden niemals durchbrochen.
+7. **Rückwärtsverträglichkeit der SQLite-Daten** bleibt erhalten.
+8. **Build muss am Ende jedes AP fehlerfrei sein.**
+9. **Alle Pflicht-Testfälle des AP** sind umgesetzt.
+
+---
+
+## 6. Granularität und Reihenfolge
+
+Sechs Arbeitspakete in dieser zwingenden Reihenfolge:
+
+| AP | Thema | Risiko | Charakter |
+|---|---|---|---|
+| AP-001 | Konfigurations-Schema einführen (additiv) | niedrig | reine Erweiterung |
+| AP-002 | Legacy-Migration mit `.bak` | mittel | Datei-Umschreibung, geschützt durch Sicherung |
+| AP-003 | Bootstrap-Provider-Auswahl + bestehender Adapter umschalten | hoch | Verhaltensänderung im Wiring |
+| AP-004 | Persistenz: Provider-Identifikator additiv | mittel | additive DB-Schema-Migration |
+| AP-005 | Nativer Anthropic-Adapter implementieren und verdrahten | mittel | neue Adapter-Klasse |
+| AP-006 | Regression, Smoke, Doku, Abschlussnachweis | niedrig | Absicherung |
+
+---
+
+# 7. Arbeitspakete
+
+---
+
+## AP-001 – Konfigurations-Schema einführen (additiv)
+
+### Voraussetzung
+Keine.
+
+### Ziel
+Das neue, verschachtelte Properties-Schema (Abschnitt 3.1) wird im Code als parsbare und validierbare Struktur eingeführt. Der bestehende Lese- und Validierungspfad bleibt **unangetastet** – das neue Schema wird parallel additiv eingeführt. Es findet **kein** Wechsel im Bootstrap und **keine** Migration in diesem AP.
+
+### Konkret zu erledigende Schritte
+1. Im Modul `pdf-umbenenner-application` (oder dem Modul, in dem die heutigen Configuration-Klassen leben – per Typsuche lokalisieren) **neue** Konfigurationstypen einführen, mindestens:
+   - eine Repräsentation einer einzelnen Provider-Konfiguration (Felder: `model`, `timeoutSeconds`, `baseUrl`, `apiKey`)
+   - eine Repräsentation der Provider-Auswahl (`activeProviderId`) plus Map oder zwei Felder für die beiden Provider-Familien
+   - einen klar benannten Aufzählungstyp oder konstanten String-Set für die zulässigen Werte `openai-compatible` und `claude`
+2. Im Adapter-Out-Modul den **Properties-Parser** so erweitern, dass er die neuen Schlüssel aus Abschnitt 3.1 erkennt und in die neuen Typen aus Schritt 1 einliest. Der bestehende Parser für die alten flachen Schlüssel bleibt **unverändert** lauffähig (parallele Erkennung).
+3. Eine **Validierung** für die neuen Typen einführen. Sie prüft:
+   - `ai.provider.active` ist gesetzt und ein zulässiger Wert
+   - alle Pflichtwerte des aktiven Providers sind vorhanden (Tabelle 3.3)
+   - `timeoutSeconds` ist eine positive Ganzzahl
+   - für Claude: Default-`baseUrl` wird gesetzt, wenn der Wert fehlt
+   - für den **inaktiven** Provider werden keine Pflichtwerte erzwungen
+   - **API-Schlüssel-Auflösung:** Umgebungsvariable des aktiven Providers (Tabelle 3.4) hat Vorrang vor dem Properties-Wert; ist beides leer, ist die Konfiguration ungültig
+4. **Bootstrap und bestehende Adapter werden in diesem AP nicht umgestellt.** Die neuen Typen sind ausschließlich über neue Tests erreichbar. Der Default-Lauf der Anwendung verwendet weiterhin die alten Klassen.
+5. JavaDoc für alle neuen Klassen und Methoden ergänzen.
+6. Konfigurationsbeispiel (`*.example.properties` o.ä.) **nicht** in diesem AP ändern. Folgt in AP-002 zusammen mit der Migration.
+
+### Pflicht-Testfälle (kritisch, namentlich umzusetzen)
+1. `parsesNewSchemaWithOpenAiCompatibleActive` – vollständiges neues Schema, OpenAI aktiv, alle Pflichtwerte gesetzt → erfolgreich geparst, Validierung grün.
+2. `parsesNewSchemaWithClaudeActive` – vollständiges neues Schema, Claude aktiv, alle Pflichtwerte gesetzt → erfolgreich geparst, Validierung grün.
+3. `claudeBaseUrlDefaultsWhenMissing` – Claude aktiv, `ai.provider.claude.baseUrl` fehlt → Default `https://api.anthropic.com` wird gesetzt, Validierung grün.
+4. `rejectsMissingActiveProvider` – `ai.provider.active` fehlt → Validierung schlägt fehl mit klarer Meldung.
+5. `rejectsUnknownActiveProvider` – `ai.provider.active=foo` → Validierung schlägt fehl.
+6. `rejectsMissingMandatoryFieldForActiveProvider` – aktiver Provider hat ein Pflichtfeld leer → Validierung schlägt fehl.
+7. `acceptsMissingMandatoryFieldForInactiveProvider` – inaktiver Provider unvollständig → Validierung grün.
+8. `envVarOverridesPropertiesApiKeyForActiveProvider` – `OPENAI_COMPATIBLE_API_KEY` gesetzt, Properties-Key ebenfalls gesetzt → effektiver Key ist der aus der Env-Var. Analog für `ANTHROPIC_API_KEY`.
+9. `envVarOnlyResolvesForActiveProvider` – Env-Var nur für inaktiven Provider gesetzt, aktiver Provider hat Properties-Key → effektiver Key ist der Properties-Key des aktiven Providers; die Env-Var des inaktiven Providers wird ignoriert.
+10. `bestehende Tests bleiben grün` – alle bisherigen Configuration-Tests laufen weiter.
+
+Test-Kategorien zusätzlich: Unit-Tests für die neuen Typen (Equality, Defaults), Parser-Tests, Validator-Tests.
+
+### Explizit NICHT Teil dieses AP
+- Migration der Legacy-Datei
+- `.bak`-Sicherung
+- Bootstrap-Umstellung
+- Änderung am bestehenden OpenAI-Adapter
+- nativer Claude-Adapter
+- Persistenz-Änderungen
+- Logging-Änderungen
+
+### Definition of Done
+- Build fehlerfrei
+- alle Pflicht-Testfälle umgesetzt und grün
+- bestehende Tests grün
+- JavaDoc vollständig für neue Klassen
+- Pflicht-Output-Block ausgegeben
+
+---
+
+## AP-002 – Legacy-Migration mit `.bak`
+
+### Voraussetzung
+AP-001 abgeschlossen.
+
+### Ziel
+Beim ersten Start mit erkannter Legacy-Form wird die Properties-Datei kontrolliert in das neue Schema überführt. Vor jeder Migration wird eine `.bak`-Sicherung angelegt. Nach erfolgreicher Migration läuft die Anwendung **noch** auf dem alten Bootstrap-Pfad weiter (Umschaltung folgt in AP-003); aber die Datei auf der Platte ist bereits im neuen Format und beim nächsten Start sofort durch das neue Schema lesbar.
+
+### Konkret zu erledigende Schritte
+1. Eine neue Komponente im Adapter-Out-Modul anlegen, die rein auf Properties-Datei-Ebene arbeitet (kein HTTP, kein DB-Zugriff). Verantwortlichkeiten:
+   - Erkennen der Legacy-Form (Abschnitt 3.5)
+   - `.bak`-Sicherung anlegen: `<dateiname>.bak`. Wenn `.bak` schon existiert, mit aufsteigendem numerischen Suffix sichern (`<dateiname>.bak`, `<dateiname>.bak.1`, …) – **niemals** überschreiben.
+   - Werte umschreiben gemäß Tabelle:
+     | Legacy | Ziel |
+     |---|---|
+     | `api.baseUrl` | `ai.provider.openai-compatible.baseUrl` |
+     | `api.model` | `ai.provider.openai-compatible.model` |
+     | `api.timeoutSeconds` | `ai.provider.openai-compatible.timeoutSeconds` |
+     | `api.key` | `ai.provider.openai-compatible.apiKey` |
+   - `ai.provider.active=openai-compatible` ergänzen.
+   - Leere/auskommentierte Platzhalter für die Claude-Sektion einfügen mit kurzem Hinweis-Kommentar (ein Block, max. 6 Zeilen).
+   - Alle übrigen Schlüssel (`source.folder`, `target.folder`, `sqlite.file`, `max.*`, `prompt.template.file`, `runtime.lock.file`, `log.*`) **unverändert** und in **stabiler Reihenfolge** übernehmen.
+   - Die migrierte Datei in-place schreiben (`.tmp` + atomischer Move/Rename, kein Truncate-and-write auf das Original).
+   - Anschließend die Datei erneut über den **neuen** Parser aus AP-001 laden und über den neuen Validator validieren. Schlägt das fehl, ist dies ein harter Startfehler (Exit-Code 1, klare Meldung, `.bak` bleibt erhalten).
+2. Die Migration wird beim Programmstart **vor** dem bestehenden Konfigurationsladen aufgerufen, sobald die Datei bekannt ist. Dieser Aufruf passiert im Bootstrap genau an einer Stelle und ist als eigene Methode klar benennbar.
+3. Wird **kein** Legacy erkannt (also bereits neues Schema), passiert nichts: keine `.bak`, keine Schreibvorgänge.
+4. Bestehende ConfigurationPort-Implementierung **nicht** umstellen – das passiert in AP-003. Die Anwendung läuft nach AP-002 fachlich weiter wie zuvor; ihr Eingangs-File ist nur jetzt in beiden Formen lesbar.
+5. Konfigurationsbeispiel im Repo (z. B. `*.example.properties`) auf das **neue** Schema umstellen. Die Datei zeigt beide Provider-Sektionen mit sprechenden Platzhalterwerten.
+6. JavaDoc und kurzer Abschnitt in der Repo-Doku zur Migration ergänzen (was passiert, wann, wie wird gesichert, was bei Fehler).
+
+### Pflicht-Testfälle
+1. `migratesLegacyFileWithAllFlatKeys` – Legacy-Datei mit allen vier `api.*`-Schlüsseln wird korrekt ins neue Schema überführt; Werte bleiben inhaltlich identisch; übrige Schlüssel bleiben unverändert.
+2. `createsBakBeforeOverwriting` – vor Migration existiert keine `.bak`, danach existiert sie mit dem **Original-Inhalt**.
+3. `bakSuffixIsIncrementedIfBakExists` – `.bak` existiert bereits → neue Sicherung als `.bak.1`. Keine Sicherung wird überschrieben.
+4. `noOpForAlreadyMigratedFile` – Datei bereits im neuen Schema → kein Schreibvorgang, kein `.bak`.
+5. `reloadAfterMigrationSucceeds` – nach Migration kann der neue Parser/Validator aus AP-001 die Datei fehlerfrei laden.
+6. `migrationFailureKeepsBak` – Migration schreibt fehlerhafte Datei (Test-Mock erzwingt Validierungsfehler nach Schreiben) → Bootstrap meldet harten Startfehler, `.bak` ist unangetastet.
+7. `legacyDetectionRequiresAtLeastOneFlatKey` – Datei mit `ai.provider.active=...` und ohne `api.*` → kein Legacy, keine Migration.
+8. `legacyValuesEndUpInOpenAiCompatibleNamespace` – Werte `api.baseUrl`, `api.model`, `api.timeoutSeconds`, `api.key` landen exakt in den vier Zielschlüsseln; `ai.provider.active=openai-compatible` ist gesetzt.
+9. `unrelatedKeysSurviveUnchanged` – Schlüssel wie `source.folder`, `max.pages`, `log.level` bleiben mit identischem Wert erhalten.
+10. `inPlaceWriteIsAtomic` – Test-Doppel für das Dateisystem belegt: erst `.tmp` schreiben, dann atomic move; kein Punkt, an dem das Original teilbeschrieben ist.
+
+Test-Kategorien zusätzlich: temporäre Dateien in `@TempDir`, Repository-/Integrationstests für die Migrations-Komponente.
+
+### Explizit NICHT Teil
+- Bootstrap-Umstellung des aktiven Konfigurationspfads
+- Änderung am bestehenden OpenAI-Adapter
+- Claude-Adapter
+- Persistenz
+- Logging-Änderungen über die Migrations-Meldungen hinaus
+
+### Definition of Done
+- Build fehlerfrei, alle Pflicht-Testfälle grün
+- Beispiel-Properties-Datei im neuen Schema
+- Kurz-Doku zur Migration im Repo
+- Pflicht-Output-Block ausgegeben
+
+---
+
+## AP-003 – Bootstrap-Provider-Auswahl und Umstellung des bestehenden OpenAI-Adapters
+
+### Voraussetzung
+AP-001 und AP-002 abgeschlossen.
+
+### Ziel
+Das Bootstrap-Modul wählt anhand von `ai.provider.active` genau eine `AiNamingPort`-Implementierung als aktive Implementierung aus und verdrahtet sie. Der bestehende OpenAI-kompatible Adapter konsumiert ab jetzt seine Werte aus dem Namensraum `ai.provider.openai-compatible.*`. Sein fachliches Verhalten bleibt **unverändert**. Der aktive Provider wird beim Laufstart geloggt.
+
+### Konkret zu erledigende Schritte
+1. Im Bootstrap-Modul eine **Provider-Selektor-Komponente** einführen, die als Eingabe den Wert von `ai.provider.active` und alle bekannten `AiNamingPort`-Implementierungen erhält und genau eine zurückgibt. Initial kennt sie nur die OpenAI-Implementierung; die Erweiterung um Claude erfolgt in AP-005 an genau dieser Stelle.
+2. Bestehende `AiNamingPort`-Implementierung für die OpenAI-kompatible Schnittstelle so anpassen, dass sie die Werte aus `ai.provider.openai-compatible.*` konsumiert. Der bisherige fachliche Vertrag, das Request-/Response-Mapping und das Fehlerverhalten bleiben **identisch**.
+3. Bestehenden ConfigurationPort/`Configuration`-Lesepfad so umstellen, dass intern **nur noch** das neue Schema verwendet wird. Die alten flachen Klassen/Methoden, die nur zum Lesen von `api.*` dienten, werden entfernt – aber **nur**, wenn sie nirgends sonst benötigt werden (per Suche prüfen). Falls noch Verweise existieren, wird der entsprechende Konsument im selben AP auf das neue Schema umgestellt.
+4. Bestehende Konfigurations-Tests des Repos auf das neue Schema umstellen. Tests, die explizit das alte flache Schema geprüft haben, werden zu Migrations-Tests verschoben (gehört bereits zu AP-002) **oder** auf das neue Schema umgeschrieben. Kein Test wird stillschweigend gelöscht.
+5. Logging-Anbindung erweitern: beim Laufstart wird der **aktive Provider-Identifikator** geloggt (Standard-Loglevel `INFO`). Alle übrigen geforderten Log-Inhalte (siehe `CLAUDE.md`, Logging-Mindestumfang) bleiben unverändert.
+6. Sicherstellen, dass die Sensibilitätsregel für KI-Inhalte unverändert greift und provider-unabhängig gilt.
+7. Adapter-zu-Adapter-Kopplung aktiv vermeiden: Der Provider-Selektor lebt im Bootstrap, **nicht** im Adapter-Out-Modul.
+8. JavaDoc für Selektor und betroffene Klassen ergänzen.
+
+### Pflicht-Testfälle
+1. `bootstrapWiresOpenAiCompatibleAdapterWhenActive` – `ai.provider.active=openai-compatible` → Selektor liefert die OpenAI-Implementierung.
+2. `bootstrapFailsHardWhenActiveProviderUnknown` – Wert ist syntaktisch gesetzt, aber kein gültiger Provider → harter Startfehler, Exit-Code 1.
+3. `bootstrapFailsHardWhenSelectedProviderHasNoImplementation` – Wert ist `claude`, aber Implementierung noch nicht registriert (Zustand nach AP-003) → harter Startfehler mit klarer Meldung. Dieser Test wird in AP-005 angepasst, sobald Claude registriert ist.
+4. `openAiAdapterReadsValuesFromNewNamespace` – Adapter-Test: gegebene `ai.provider.openai-compatible.*`-Werte landen 1:1 im HTTP-Request an die bisherige Endpoint-URL.
+5. `openAiAdapterBehaviorIsUnchanged` – bestehender Adapter-Verhaltenstest (Request-Form, Response-Mapping, Fehlerklassifikation) wird auf die neue Konfigurationsquelle umgestellt und bleibt grün.
+6. `activeProviderIsLoggedAtRunStart` – Smoke- oder Bootstrap-Test belegt, dass der aktive Provider bei Laufstart in einem definierten Log-Eintrag erscheint.
+7. `existingDocumentProcessingTestsRemainGreen` – sämtliche bestehenden End-to-End-/Integrations-Tests des bestehenden OpenAI-Pfads bleiben grün, ggf. mit angepasster Konfiguration.
+8. `legacyFileEndToEndStillRuns` – Test-Doppel: Anwendung startet mit Legacy-Datei → Migration aus AP-002 läuft → Bootstrap aus AP-003 wählt OpenAI → Lauf läuft fachlich durch wie zuvor.
+
+Test-Kategorien zusätzlich: Bootstrap-/Wiring-Tests, ggf. Smoke-Test ohne realen externen Aufruf.
+
+### Explizit NICHT Teil
+- Claude-Adapter
+- Persistenz-Erweiterung um Provider-Identifikator
+- neue Fehlersemantik
+- Refactoring außerhalb der Adapter-Anbindung
+
+### Definition of Done
+- Build fehlerfrei, Pflicht-Testfälle grün
+- bestehender OpenAI-Pfad fachlich unverändert
+- aktiver Provider wird beim Laufstart geloggt
+- keine Verweise mehr auf das alte flache Schema im Produktivpfad
+- Pflicht-Output-Block ausgegeben
+
+---
+
+## AP-004 – Persistenz: Provider-Identifikator additiv
+
+### Voraussetzung
+AP-003 abgeschlossen.
+
+### Ziel
+Das SQLite-Schema wird **additiv** um eine Spalte für den Provider-Identifikator je Versuch erweitert. Bestehende Datensätze bleiben lesbar und korrekt interpretierbar (Default-Wert für Altdaten). Neue Versuche schreiben den Identifikator des für den Versuch aktiven Providers.
+
+### Konkret zu erledigende Schritte
+1. Im SQLite-Schema der Versuchshistorie eine neue Spalte hinzufügen, z. B. `ai_provider TEXT NULL` (Spaltenname per bestehender Repo-Konvention wählen, sonst wie hier vorgeschlagen). Die Spalte ist nullable.
+2. Schema-Migration umsetzen:
+   - Bei Programmstart prüfen, ob die Spalte existiert; wenn nein, per `ALTER TABLE` ergänzen.
+   - Vorhandene Zeilen behalten den Wert `NULL`.
+   - Migration muss idempotent sein (mehrfacher Start ohne Fehler).
+3. Die Versuchshistorie-Schreiblogik so erweitern, dass beim Anlegen eines neuen Versuchs der **Identifikator des aktiv ausgewählten Providers** mitgeschrieben wird (`openai-compatible` oder `claude`). Der Wert kommt aus der bereits in AP-003 verfügbaren Provider-Auswahl.
+4. Dokument-Stammsatz wird **nicht** verändert.
+5. Lesepfad anpassen, sodass der neue Wert mitausgelesen wird; bestehende Mapper/Domain-Typen werden minimal um ein optionales Feld erweitert. Application und Domain bekommen dadurch keinen provider-spezifischen Code – das Feld bleibt ein opaker String.
+6. JavaDoc und kurzer Abschnitt zur Schema-Erweiterung in der Repo-Doku ergänzen.
+
+### Pflicht-Testfälle
+1. `addsProviderColumnOnFreshDb` – frische DB → Schema enthält neue Spalte.
+2. `addsProviderColumnOnExistingDbWithoutColumn` – DB ohne Spalte (Simulation Altbestand) → Migration legt Spalte nullable an.
+3. `migrationIsIdempotent` – mehrfacher Start ändert nichts und wirft keinen Fehler.
+4. `existingRowsKeepNullProvider` – Altzeilen behalten `NULL`.
+5. `newAttemptsWriteOpenAiCompatibleProvider` – aktiver Provider OpenAI → neuer Versuch hat `ai_provider='openai-compatible'`.
+6. `newAttemptsWriteClaudeProvider` – aktiver Provider Claude (für diesen Test wird die Provider-Auswahl gemockt; in AP-005 wird derselbe Test mit echtem Claude-Adapter wiederholt) → `ai_provider='claude'`.
+7. `repositoryReadsProviderColumn` – Repository-Test: gespeicherter Wert wird korrekt zurückgelesen.
+8. `legacyDataReadingDoesNotFail` – Test mit DB-Datei aus dem Vor-V1.1-Stand: Lesen ohne Fehler, neuer Wert ist Optional/leer.
+9. `existingHistoryTestsRemainGreen` – alle bestehenden Tests rund um die Versuchshistorie bleiben grün, ggf. mit minimaler Anpassung.
+
+Test-Kategorien zusätzlich: Repository-Tests gegen echte SQLite-Instanz (in-memory oder temporär), Schema-Migrations-Tests.
+
+### Explizit NICHT Teil
+- Claude-Adapter (folgt in AP-005)
+- Änderungen am Dokument-Stammsatz
+- neue Wahrheitsquellen
+- Reporting/Statistiken
+
+### Definition of Done
+- Build fehlerfrei, Pflicht-Testfälle grün
+- bestehende Datenbestände bleiben lesbar
+- Provider-Identifikator wird für neue Versuche geschrieben
+- Pflicht-Output-Block ausgegeben
+
+---
+
+## AP-005 – Nativer Anthropic-Adapter implementieren und verdrahten
+
+### Voraussetzung
+AP-001 bis AP-004 abgeschlossen.
+
+### Ziel
+Eine zweite `AiNamingPort`-Implementierung wird im Adapter-Out-Modul angelegt, die die **native Anthropic Messages API** anspricht (siehe Faktenblock in Abschnitt 4). Sie wird im Provider-Selektor aus AP-003 als zweite Option registriert. Der Adapter bildet die Anthropic-Antwort auf den **bestehenden** fachlichen Vertrag ab; es entsteht kein Sonderweg in Application oder Domain.
+
+### Konkret zu erledigende Schritte
+1. Im Adapter-Out-Modul eine neue Klasse anlegen, die `AiNamingPort` implementiert. Naming nach bestehender Repo-Konvention; per Typsuche prüfen, wie die OpenAI-Implementierung benannt ist, und analog vorgehen.
+2. HTTP-Aufruf gemäß Faktenblock 4 umsetzen:
+   - URL aus `ai.provider.claude.baseUrl` (Default `https://api.anthropic.com`) plus Pfad `/v1/messages`
+   - Methode `POST`
+   - Header `x-api-key`, `anthropic-version: 2023-06-01`, `content-type: application/json`
+   - Request-Body mit `model`, `max_tokens`, `messages` (eine `user`-Message mit dem bestehenden Prompt-Text), optional `system` falls die bestehende Prompt-Mechanik ein System-Segment kennt
+   - Timeout aus `ai.provider.claude.timeoutSeconds`
+3. API-Schlüssel-Auflösung exakt nach Tabelle 3.4: zuerst `ANTHROPIC_API_KEY`, dann `ai.provider.claude.apiKey`.
+4. Antwortverarbeitung gemäß 4.4: Konkatenation aller `content[*].text`-Blöcke in Reihenfolge. Fehlt jeder `text`-Block oder ist die Antwort nicht parsebar → technischer Adapterfehler nach Tabelle 4.5.
+5. Den so gewonnenen Antworttext **unverändert** an die bestehende Antwortverarbeitung der Anwendung weitergeben (`NamingProposal`-Validierung passiert in Application/Domain wie bisher).
+6. Fehlerklassifikation streng nach Tabelle 4.5. Keine neuen Fehlerklassen.
+7. Den Provider-Selektor aus AP-003 um die neue Implementierung erweitern. **Keine** gemeinsame Basisklasse zwischen den beiden Adaptern, **keine** Hilfsklasse, die HTTP-Logik teilt. Was beide Adapter brauchen, kommt aus dem Repo-üblichen HTTP-/JSON-Standard, nicht aus einer neuen Adapter-Zwischenschicht.
+8. Den in AP-001 angelegten Test `bootstrapFailsHardWhenSelectedProviderHasNoImplementation` so anpassen, dass er ab jetzt auf einen neuen, weiterhin **unbekannten** Provider-Wert testet (Negativfall bleibt erhalten, aber `claude` ist jetzt registriert).
+9. Konfigurationsbeispiel im Repo um sprechende Claude-Beispielwerte ergänzen.
+10. JavaDoc für die neue Klasse und ggf. neue Hilfstypen.
+
+### Pflicht-Testfälle
+1. `claudeAdapterBuildsCorrectRequest` – gegebener Prompt → HTTP-Request mit korrekter URL (`<baseUrl>/v1/messages`), Methode POST, allen drei Pflicht-Headern, Body enthält `model`, `max_tokens > 0`, `messages` mit genau einer `user`-Message und korrektem Prompt.
+2. `claudeAdapterUsesEnvVarApiKey` – `ANTHROPIC_API_KEY` gesetzt, Properties-Wert ebenfalls → Header `x-api-key` enthält den Env-Wert.
+3. `claudeAdapterFallsBackToPropertiesApiKey` – Env-Var leer, Properties-Wert gesetzt → Header `x-api-key` enthält den Properties-Wert.
+4. `claudeAdapterFailsValidationWhenBothKeysMissing` – beides leer → Konfigurationsfehler beim Start (greift auf AP-001-Validierung).
+5. `claudeAdapterParsesSingleTextBlock` – Mock-Response mit einem Block `{type:"text", text:"..."}` → Antworttext gleich dem Block-Text.
+6. `claudeAdapterConcatenatesMultipleTextBlocks` – mehrere `text`-Blöcke → Antworttext gleich der Konkatenation in Reihenfolge.
+7. `claudeAdapterIgnoresNonTextBlocks` – Mix aus `text`- und Nicht-`text`-Blöcken → nur die `text`-Inhalte landen im Antworttext.
+8. `claudeAdapterFailsOnEmptyTextContent` – Response ohne jeden `text`-Block → technischer Adapterfehler.
+9. `claudeAdapterMapsHttp401AsTechnical` – Mock-Response 401 → technischer Fehler nach Tabelle 4.5.
+10. `claudeAdapterMapsHttp429AsTechnical` – Mock-Response 429 → technischer Fehler.
+11. `claudeAdapterMapsHttp500AsTechnical` – Mock-Response 500 → technischer Fehler.
+12. `claudeAdapterMapsTimeoutAsTechnical` – simulierter Timeout → technischer Fehler.
+13. `claudeAdapterMapsUnparseableJsonAsTechnical` – Response-Body ist kein gültiges JSON → technischer Fehler.
+14. `bootstrapSelectsClaudeWhenActive` – `ai.provider.active=claude` → Selektor liefert die Claude-Implementierung.
+15. `claudeProviderIdentifierLandsInAttemptHistory` – End-zu-End mit gemocktem HTTP-Layer: nach erfolgreichem Lauf hat der neue Versuch `ai_provider='claude'` (knüpft an AP-004 an).
+16. `existingOpenAiPathRemainsGreen` – sämtliche bestehenden Tests des OpenAI-Pfads bleiben unverändert grün.
+
+Test-Kategorien zusätzlich: Adapter-Tests mit gemocktem HTTP-Client (kein realer Netzwerkzugriff), Bootstrap-Wiring-Tests.
+
+### Explizit NICHT Teil
+- automatische Fallback-Logik zwischen Providern
+- gemeinsame Adapter-Basisklasse
+- Erweiterung des Persistenz-Schemas über AP-004 hinaus
+- Anpassung des Prompts (eine etwaige System-/User-Trennung der bestehenden Prompt-Datei darf genutzt werden, aber keine inhaltliche Änderung des Prompts)
+
+### Definition of Done
+- Build fehlerfrei, alle Pflicht-Testfälle grün
+- nativer Anthropic-Adapter wird über Konfiguration auswählbar und liefert auf Mock-Basis korrekte Ergebnisse
+- bestehender OpenAI-Pfad unverändert grün
+- Pflicht-Output-Block ausgegeben
+
+---
+
+## AP-006 – Regression, Smoke, Doku-Konsolidierung, Abschlussnachweis
+
+### Voraussetzung
+AP-001 bis AP-005 abgeschlossen.
+
+### Ziel
+Der vollständige Erweiterungsstand wird automatisiert abgesichert, dokumentarisch konsolidiert und als minimale, architekturtreue Erweiterung des Basisstands belastbar nachgewiesen.
+
+### Konkret zu erledigende Schritte
+1. **Smoke-Test je Provider:** Zwei Smoke-Tests einrichten, die für je eine Provider-Konfiguration den Bootstrap-Pfad bis zur erfolgreichen Verdrahtung des `AiNamingPort` durchlaufen, **ohne** realen externen HTTP-Aufruf (gemockter HTTP-Layer). Beide müssen grün sein.
+2. **Regression OpenAI:** Alle bestehenden End-to-End-/Integrations-Tests des OpenAI-Pfads laufen grün. Falls Anpassungen in vorigen APs Tests berührt haben, ist hier der finale Konsistenz-Check.
+3. **Migration Smoke:** Ein End-zu-End-Test, der mit einer Legacy-Datei (Inhalt aus der bekannten Demo-Konfig) startet und nach einem ersten Lauf folgendes nachweist:
+   - `.bak` existiert mit Original-Inhalt
+   - Properties-Datei ist im neuen Schema
+   - `ai.provider.active=openai-compatible`
+   - der Lauf hat fachlich gleich funktioniert wie mit dem neuen Schema
+4. **PIT-/Mutationstests** in den unmittelbar betroffenen Modulen ausführen, soweit bereits etabliert. Lücken im neuen Code, die deutlich unter dem bestehenden Niveau liegen, gezielt schließen. Keine willkürliche Coverage-Kosmetik.
+5. **Doku-Konsolidierung:**
+   - Beispiel-Properties-Datei zeigt das vollständige neue Schema für **beide** Provider mit sprechenden Platzhaltern.
+   - Repo-Doku enthält einen kurzen Abschnitt „KI-Provider auswählen" mit den zulässigen Werten und der Env-Var-Konvention (`OPENAI_COMPATIBLE_API_KEY`, `ANTHROPIC_API_KEY`).
+   - Repo-Doku enthält einen kurzen Abschnitt „Migration von der Vorgängerversion" mit dem Hinweis auf `.bak`.
+   - JavaDoc aller in der Erweiterung neu eingeführten oder substanziell geänderten Klassen ist vorhanden.
+6. **Abschlussnachweis:** Eine kurze, im Repository verbleibende Markdown-Datei unter `docs/workpackages/V1.1 - Abschlussnachweis.md` anlegen, die mindestens enthält:
+   - Datum, betroffene Module
+   - Liste der ausgeführten Pflicht-Testfälle pro AP (kann tabellarisch sein)
+   - Belegte Eigenschaften: zwei Provider unterstützt, genau einer aktiv, kein Fallback, fachlicher Vertrag unverändert, Persistenz rückwärtsverträglich, Migration nachgewiesen, `.bak` nachgewiesen, aktiver Provider geloggt
+   - explizite Bestätigung: keine Architekturbrüche, keine neuen Bibliotheken außer denen, die für HTTP/JSON ohnehin im Repo etabliert sind
+   - Hinweis auf die Betreiberaufgabe, ggf. die Umgebungsvariable des OpenAI-Keys auf `OPENAI_COMPATIBLE_API_KEY` umzustellen
+7. Den vollständigen Reactor-Build ausführen und das Ergebnis im AP-Output festhalten.
+
+### Pflicht-Testfälle
+1. `smokeBootstrapWithOpenAiCompatibleActive`
+2. `smokeBootstrapWithClaudeActive`
+3. `e2eMigrationFromLegacyDemoConfig`
+4. `regressionExistingOpenAiSuiteGreen` (Sammelnachweis, nicht ein einzelner Test)
+5. `e2eClaudeRunWritesProviderIdentifierToHistory`
+6. `e2eOpenAiRunWritesProviderIdentifierToHistory`
+7. `legacyDataFromBeforeV11RemainsReadable`
+
+Test-Kategorien zusätzlich: Mutationstests in betroffenen Modulen, Konsistenz-Checks der Doku-Beispiele gegen den realen Parser (z. B. „Beispiel-Properties-Datei wird vom Parser ohne Fehler geladen").
+
+### Explizit NICHT Teil
+- weitere Provider
+- Komfortfunktionen
+- großflächiges Refactoring
+
+### Definition of Done
+- vollständiger Reactor-Build fehlerfrei
+- alle Pflicht-Testfälle grün
+- Smoke-Tests je Provider grün
+- Doku konsolidiert
+- Abschlussnachweis-Datei im Repo
+- Pflicht-Output-Block ausgegeben
@@ -1,68 +0,0 @@
-pdf-umbenenner-adapter-in-cli/src/main/java/de/gecheckt/pdf/umbenenner/adapter/in/cli/package-info.java | de.gecheckt.pdf.umbenenner.adapter.in.cli |  | 
-pdf-umbenenner-adapter-in-cli/src/main/java/de/gecheckt/pdf/umbenenner/adapter/in/cli/SchedulerBatchCommand.java | de.gecheckt.pdf.umbenenner.adapter.in.cli | class | SchedulerBatchCommand
-pdf-umbenenner-adapter-in-cli/src/test/java/de/gecheckt/pdf/umbenenner/adapter/in/cli/SchedulerBatchCommandTest.java | de.gecheckt.pdf.umbenenner.adapter.in.cli | class | SchedulerBatchCommandTest
-pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/package-info.java | de.gecheckt.pdf.umbenenner.adapter.out.configuration |  | 
-pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/PropertiesConfigurationPortAdapter.java | de.gecheckt.pdf.umbenenner.adapter.out.configuration | class | PropertiesConfigurationPortAdapter
-pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/lock/FilesystemRunLockPortAdapter.java | de.gecheckt.pdf.umbenenner.adapter.out.lock | class | FilesystemRunLockPortAdapter
-pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/lock/package-info.java | de.gecheckt.pdf.umbenenner.adapter.out.lock |  | 
-pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/package-info.java | de.gecheckt.pdf.umbenenner.adapter.out |  | 
-pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/pdfextraction/package-info.java | de.gecheckt.pdf.umbenenner.adapter.out.pdfextraction |  | 
-pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/pdfextraction/PdfTextExtractionPortAdapter.java | de.gecheckt.pdf.umbenenner.adapter.out.pdfextraction | class | PdfTextExtractionPortAdapter
-pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/sourcedocument/package-info.java | de.gecheckt.pdf.umbenenner.adapter.out.sourcedocument |  | 
-pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/sourcedocument/SourceDocumentCandidatesPortAdapter.java | de.gecheckt.pdf.umbenenner.adapter.out.sourcedocument | class | SourceDocumentCandidatesPortAdapter
-pdf-umbenenner-adapter-out/src/test/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/PropertiesConfigurationPortAdapterTest.java | de.gecheckt.pdf.umbenenner.adapter.out.configuration | class | PropertiesConfigurationPortAdapterTest
-pdf-umbenenner-adapter-out/src/test/java/de/gecheckt/pdf/umbenenner/adapter/out/lock/FilesystemRunLockPortAdapterTest.java | de.gecheckt.pdf.umbenenner.adapter.out.lock | class | FilesystemRunLockPortAdapterTest
-pdf-umbenenner-adapter-out/src/test/java/de/gecheckt/pdf/umbenenner/adapter/out/pdfextraction/PdfTextExtractionPortAdapterTest.java | de.gecheckt.pdf.umbenenner.adapter.out.pdfextraction | class | PdfTextExtractionPortAdapterTest
-pdf-umbenenner-adapter-out/src/test/java/de/gecheckt/pdf/umbenenner/adapter/out/sourcedocument/SourceDocumentCandidatesPortAdapterTest.java | de.gecheckt.pdf.umbenenner.adapter.out.sourcedocument | class | SourceDocumentCandidatesPortAdapterTest
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/config/InvalidStartConfigurationException.java | de.gecheckt.pdf.umbenenner.application.config | class | InvalidStartConfigurationException
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/config/package-info.java | de.gecheckt.pdf.umbenenner.application.config |  | 
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/config/StartConfiguration.java | de.gecheckt.pdf.umbenenner.application.config | record | StartConfiguration
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/config/StartConfigurationValidator.java | de.gecheckt.pdf.umbenenner.application.config | class | StartConfigurationValidator
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/package-info.java | de.gecheckt.pdf.umbenenner.application |  | 
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/in/BatchRunOutcome.java | de.gecheckt.pdf.umbenenner.application.port.in | enum | BatchRunOutcome
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/in/package-info.java | de.gecheckt.pdf.umbenenner.application.port.in |  | 
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/in/RunBatchProcessingUseCase.java | de.gecheckt.pdf.umbenenner.application.port.in | interface | RunBatchProcessingUseCase
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/ClockPort.java | de.gecheckt.pdf.umbenenner.application.port.out | interface | ClockPort
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/ConfigurationPort.java | de.gecheckt.pdf.umbenenner.application.port.out | interface | ConfigurationPort
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/package-info.java | de.gecheckt.pdf.umbenenner.application.port.out |  | 
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/PdfTextExtractionPort.java | de.gecheckt.pdf.umbenenner.application.port.out | interface | PdfTextExtractionPort
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/RunLockPort.java | de.gecheckt.pdf.umbenenner.application.port.out | interface | RunLockPort
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/RunLockUnavailableException.java | de.gecheckt.pdf.umbenenner.application.port.out | class | RunLockUnavailableException
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/SourceDocumentAccessException.java | de.gecheckt.pdf.umbenenner.application.port.out |  | 
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/SourceDocumentCandidatesPort.java | de.gecheckt.pdf.umbenenner.application.port.out | interface | SourceDocumentCandidatesPort
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/service/DocumentProcessingService.java | de.gecheckt.pdf.umbenenner.application.service | class | DocumentProcessingService
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/service/package-info.java | de.gecheckt.pdf.umbenenner.application.service |  | 
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/service/PreCheckEvaluator.java | de.gecheckt.pdf.umbenenner.application.service | class | PreCheckEvaluator
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/usecase/BatchRunProcessingUseCase.java | de.gecheckt.pdf.umbenenner.application.usecase | class | BatchRunProcessingUseCase
-pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/usecase/package-info.java | de.gecheckt.pdf.umbenenner.application.usecase |  | 
-pdf-umbenenner-application/src/test/java/de/gecheckt/pdf/umbenenner/application/config/StartConfigurationValidatorTest.java | de.gecheckt.pdf.umbenenner.application.config | class | StartConfigurationValidatorTest
-pdf-umbenenner-application/src/test/java/de/gecheckt/pdf/umbenenner/application/service/DocumentProcessingServiceTest.java | de.gecheckt.pdf.umbenenner.application.service | class | DocumentProcessingServiceTest
-pdf-umbenenner-application/src/test/java/de/gecheckt/pdf/umbenenner/application/service/PreCheckEvaluatorTest.java | de.gecheckt.pdf.umbenenner.application.service | class | PreCheckEvaluatorTest
-pdf-umbenenner-application/src/test/java/de/gecheckt/pdf/umbenenner/application/usecase/BatchRunProcessingUseCaseTest.java | de.gecheckt.pdf.umbenenner.application.usecase | class | BatchRunProcessingUseCaseTest
-pdf-umbenenner-bootstrap/src/main/java/de/gecheckt/pdf/umbenenner/bootstrap/BootstrapRunner.java | de.gecheckt.pdf.umbenenner.bootstrap | class | BootstrapRunner
-pdf-umbenenner-bootstrap/src/main/java/de/gecheckt/pdf/umbenenner/bootstrap/package-info.java | de.gecheckt.pdf.umbenenner.bootstrap |  | 
-pdf-umbenenner-bootstrap/src/main/java/de/gecheckt/pdf/umbenenner/bootstrap/PdfUmbenennerApplication.java | de.gecheckt.pdf.umbenenner.bootstrap | class | PdfUmbenennerApplication
-pdf-umbenenner-bootstrap/src/test/java/de/gecheckt/pdf/umbenenner/bootstrap/BootstrapRunnerTest.java | de.gecheckt.pdf.umbenenner.bootstrap | class | BootstrapRunnerTest
-pdf-umbenenner-bootstrap/src/test/java/de/gecheckt/pdf/umbenenner/bootstrap/ExecutableJarSmokeTestIT.java | de.gecheckt.pdf.umbenenner.bootstrap | class | ExecutableJarSmokeTestIT
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/BatchRunContext.java | de.gecheckt.pdf.umbenenner.domain.model |  | 
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/DocumentProcessingOutcome.java | de.gecheckt.pdf.umbenenner.domain.model |  | 
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/package-info.java | de.gecheckt.pdf.umbenenner.domain.model |  | 
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/PdfExtractionContentError.java | de.gecheckt.pdf.umbenenner.domain.model | record | PdfExtractionContentError
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/PdfExtractionResult.java | de.gecheckt.pdf.umbenenner.domain.model |  | 
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/PdfExtractionSuccess.java | de.gecheckt.pdf.umbenenner.domain.model | record | PdfExtractionSuccess
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/PdfExtractionTechnicalError.java | de.gecheckt.pdf.umbenenner.domain.model | record | PdfExtractionTechnicalError
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/PdfPageCount.java | de.gecheckt.pdf.umbenenner.domain.model | record | PdfPageCount
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/PreCheckFailed.java | de.gecheckt.pdf.umbenenner.domain.model | record | PreCheckFailed
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/PreCheckFailureReason.java | de.gecheckt.pdf.umbenenner.domain.model | enum | PreCheckFailureReason
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/PreCheckPassed.java | de.gecheckt.pdf.umbenenner.domain.model | record | PreCheckPassed
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/ProcessingDecision.java | de.gecheckt.pdf.umbenenner.domain.model |  | 
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/ProcessingStatus.java | de.gecheckt.pdf.umbenenner.domain.model | enum | ProcessingStatus
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/RunId.java | de.gecheckt.pdf.umbenenner.domain.model |  | 
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/SourceDocumentCandidate.java | de.gecheckt.pdf.umbenenner.domain.model | record | SourceDocumentCandidate
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/SourceDocumentLocator.java | de.gecheckt.pdf.umbenenner.domain.model | record | SourceDocumentLocator
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/TechnicalDocumentError.java | de.gecheckt.pdf.umbenenner.domain.model | record | TechnicalDocumentError
-pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/package-info.java | de.gecheckt.pdf.umbenenner.domain |  | 
-pdf-umbenenner-domain/src/test/java/de/gecheckt/pdf/umbenenner/domain/model/BatchRunContextTest.java | de.gecheckt.pdf.umbenenner.domain.model | class | BatchRunContextTest
-pdf-umbenenner-domain/src/test/java/de/gecheckt/pdf/umbenenner/domain/model/DocumentProcessingOutcomeTest.java | de.gecheckt.pdf.umbenenner.domain.model | class | DocumentProcessingOutcomeTest
-pdf-umbenenner-domain/src/test/java/de/gecheckt/pdf/umbenenner/domain/model/ProcessingStatusTest.java | de.gecheckt.pdf.umbenenner.domain.model | class | ProcessingStatusTest
-pdf-umbenenner-domain/src/test/java/de/gecheckt/pdf/umbenenner/domain/model/RunIdTest.java | de.gecheckt.pdf.umbenenner.domain.model | class | RunIdTest
@@ -4,7 +4,7 @@
  <parent>
    <groupId>de.gecheckt</groupId>
    <artifactId>pdf-umbenenner-parent</artifactId>
-    <version>0.0.1-SNAPSHOT</version>
+    <version>${revision}</version>
  </parent>
  <artifactId>pdf-umbenenner-adapter-in-cli</artifactId>
  <packaging>jar</packaging>
@@ -39,4 +39,42 @@
      <scope>test</scope>
    </dependency>
  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.jacoco</groupId>
+        <artifactId>jacoco-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>jacoco-check</id>
+            <phase>verify</phase>
+            <goals>
+              <goal>check</goal>
+            </goals>
+            <configuration>
+              <!-- Adapter-In is minimal wrapper, lower threshold acceptable -->
+              <rules>
+                <rule>
+                  <element>BUNDLE</element>
+                  <limits>
+                    <limit>
+                      <counter>LINE</counter>
+                      <value>COVEREDRATIO</value>
+                      <minimum>0.60</minimum>
+                    </limit>
+                    <limit>
+                      <counter>BRANCH</counter>
+                      <value>COVEREDRATIO</value>
+                      <minimum>0.55</minimum>
+                    </limit>
+                  </limits>
+                </rule>
+              </rules>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
 </project>
@@ -12,15 +12,11 @@ import de.gecheckt.pdf.umbenenner.domain.model.BatchRunContext;
 * interface. It receives the batch run outcome and makes it available to the Bootstrap layer
 * for exit code determination and logging.
 * <p>
- * AP-003 Implementation: Minimal no-op command to validate the call chain from CLI to Application.
- * <p>
- * M2-AP-002 Update: Returns {@link BatchRunOutcome} instead of boolean,
- * allowing Bootstrap to systematically derive exit codes (AP-007).
- * <p>
- * M2-AP-003 Update: Accepts {@link BatchRunContext} and passes it to the use case,
+ * Returns {@link BatchRunOutcome} to allow Bootstrap to systematically derive exit codes.
+ * Accepts {@link BatchRunContext} and passes it to the use case,
 * enabling run ID and timing tracking throughout the batch cycle.
 * <p>
- * M2-AP-005 Update: Dependency inversion achieved - this adapter depends only on the
+ * Dependency inversion achieved - this adapter depends only on the
 * BatchRunProcessingUseCase interface, not on any concrete implementation. Bootstrap
 * is responsible for injecting the appropriate use case implementation.
 */
@@ -8,10 +8,10 @@
 * Components:
 * <ul>
 *   <li>{@link de.gecheckt.pdf.umbenenner.adapter.in.cli.SchedulerBatchCommand}
- *       — CLI entry point that delegates to BatchRunProcessingUseCase interface (AP-005)</li>
+ *       — CLI entry point that delegates to BatchRunProcessingUseCase interface</li>
 * </ul>
 * <p>
- * M2-AP-005 Architecture:
+ * Adapter Architecture:
 * <ul>
 *   <li>Adapter depends on: {@link de.gecheckt.pdf.umbenenner.application.port.in.BatchRunProcessingUseCase} (interface)</li>
 *   <li>Adapter does not depend on: any concrete use case implementation</li>
@@ -1,17 +1,19 @@
 package de.gecheckt.pdf.umbenenner.adapter.in.cli;

-import de.gecheckt.pdf.umbenenner.adapter.in.cli.SchedulerBatchCommand;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.time.Instant;
+
+import org.junit.jupiter.api.Test;
+
 import de.gecheckt.pdf.umbenenner.application.port.in.BatchRunOutcome;
 import de.gecheckt.pdf.umbenenner.application.port.in.BatchRunProcessingUseCase;
 import de.gecheckt.pdf.umbenenner.domain.model.BatchRunContext;
 import de.gecheckt.pdf.umbenenner.domain.model.RunId;

-import org.junit.jupiter.api.Test;
-
-import java.time.Instant;
-
-import static org.junit.jupiter.api.Assertions.*;
-
 /**
 * Unit tests for {@link SchedulerBatchCommand}.
 * <p>
@@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>de.gecheckt</groupId>
+    <artifactId>pdf-umbenenner-parent</artifactId>
+    <version>${revision}</version>
+  </parent>
+  <artifactId>pdf-umbenenner-adapter-in-gui</artifactId>
+  <packaging>jar</packaging>
+
+  <dependencies>
+    <!-- Internal dependencies: inbound adapter depends on application and domain -->
+    <dependency>
+      <groupId>de.gecheckt</groupId>
+      <artifactId>pdf-umbenenner-application</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>de.gecheckt</groupId>
+      <artifactId>pdf-umbenenner-domain</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+
+    <!-- JavaFX: only this module depends on JavaFX; domain/application/cli remain JavaFX-free -->
+    <dependency>
+      <groupId>org.openjfx</groupId>
+      <artifactId>javafx-base</artifactId>
+      <classifier>win</classifier>
+    </dependency>
+    <dependency>
+      <groupId>org.openjfx</groupId>
+      <artifactId>javafx-graphics</artifactId>
+      <classifier>win</classifier>
+    </dependency>
+    <dependency>
+      <groupId>org.openjfx</groupId>
+      <artifactId>javafx-controls</artifactId>
+      <classifier>win</classifier>
+    </dependency>
+    <!-- JavaFX-Swing-Interop: wird für SwingFXUtils.toFXImage (BufferedImage -> FX Image) benötigt -->
+    <dependency>
+      <groupId>org.openjfx</groupId>
+      <artifactId>javafx-swing</artifactId>
+      <version>21.0.2</version>
+      <classifier>win</classifier>
+    </dependency>
+
+    <!-- PDF-Vorschau: PDFBox für direktes Rendering einzelner Seiten in BufferedImages -->
+    <dependency>
+      <groupId>org.apache.pdfbox</groupId>
+      <artifactId>pdfbox</artifactId>
+    </dependency>
+    <!-- JBIG2-Codec für PDF-Bilddecodierung -->
+    <dependency>
+      <groupId>org.apache.pdfbox</groupId>
+      <artifactId>jbig2-imageio</artifactId>
+      <version>3.0.4</version>
+    </dependency>
+    <!-- JPEG2000-Codec für erweiterte PDF-Bilddecodierung -->
+    <dependency>
+      <groupId>com.github.jai-imageio</groupId>
+      <artifactId>jai-imageio-jpeg2000</artifactId>
+      <version>1.4.0</version>
+    </dependency>
+
+    <!-- Logging -->
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-api</artifactId>
+    </dependency>
+
+    <!-- Test dependencies -->
+    <!--
+      log4j-core on the test classpath provides the logging implementation for
+      tests that instantiate production classes using LogManager.getLogger.
+      Without it, Log4j2 falls back to SimpleLogger during test execution and
+      prints "Log4j2 could not find a logging implementation" at test start.
+      The production classpath is unaffected; log4j-core is supplied by the
+      bootstrap module in the shaded runtime JAR.
+    -->
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.mockito</groupId>
+      <artifactId>mockito-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.mockito</groupId>
+      <artifactId>mockito-junit-jupiter</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <!--
+      Monocle: headless JavaFX platform for GUI smoke tests.
+      Provides the Glass platform implementation that runs JavaFX without a
+      physical display. Required for running GUI tests in headless CI environments
+      and as the designated test runtime for all GUI smoke tests.
+      Not part of the production classpath; test scope only.
+    -->
+    <dependency>
+      <groupId>org.testfx</groupId>
+      <artifactId>openjfx-monocle</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <!--
+        Surefire: configure JVM arguments for headless JavaFX via Monocle.
+        These properties must be set before JavaFX initializes the Glass toolkit:
+        glass.platform=Monocle selects the Monocle headless Glass implementation
+        (provided by openjfx-monocle on the test classpath);
+        monocle.platform=Headless selects the headless backend within Monocle;
+        prism.order=sw enables software rendering (no GPU required);
+        prism.text=t2k selects the T2K text rasterizer (headless-safe);
+        java.awt.headless=true signals headless mode to AWT/Swing interop layers.
+        Note: module-opening arguments for javafx.graphics are no longer required.
+        Modern JavaFX (21.x) with Monocle on Java 21 works without explicit module opening.
+      -->
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <configuration>
+          <argLine>
+            ${argLine}
+            -Dglass.platform=Monocle
+            -Dmonocle.platform=Headless
+            -Dprism.order=sw
+            -Dprism.text=t2k
+            -Djava.awt.headless=true
+          </argLine>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.jacoco</groupId>
+        <artifactId>jacoco-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>jacoco-check</id>
+            <phase>verify</phase>
+            <goals>
+              <goal>check</goal>
+            </goals>
+            <configuration>
+              <!--
+                Coverage thresholds for the GUI adapter module.
+                The JavaFX Application lifecycle (Application.launch, start(Stage), stop)
+                is structurally untestable within the same JVM:
+                Application.launch() is blocking and can only be called once per JVM,
+                and start(Stage) requires the JavaFX runtime to supply application
+                parameters (getParameters()), which is only available after launch().
+                Monocle smoke tests cover Platform.startup() and node creation on the
+                FX thread. Constructor coverage is verified by structural unit tests.
+                Full application lifecycle coverage is provided by the executable-JAR
+                integration test in pdf-umbenenner-bootstrap (ExecutableJarSmokeTestIT).
+                The low threshold reflects this structural constraint and will remain
+                until Application.launch-equivalent lifecycle testing is available.
+              -->
+              <rules>
+                <rule>
+                  <element>BUNDLE</element>
+                  <limits>
+                    <limit>
+                      <counter>LINE</counter>
+                      <value>COVEREDRATIO</value>
+                      <minimum>0.10</minimum>
+                    </limit>
+                    <limit>
+                      <counter>BRANCH</counter>
+                      <value>COVEREDRATIO</value>
+                      <minimum>0.00</minimum>
+                    </limit>
+                  </limits>
+                </rule>
+              </rules>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.pitest</groupId>
+        <artifactId>pitest-maven</artifactId>
+        <executions>
+          <execution>
+            <id>pitest</id>
+            <phase>verify</phase>
+            <goals>
+              <goal>mutationCoverage</goal>
+            </goals>
+            <configuration>
+              <!--
+                GUI adapter: PIT is skipped entirely. The JavaFX Application lifecycle
+                cannot be meaningfully mutation-tested without a running display or
+                Monocle runtime, and the remaining testable surface is too small to
+                produce useful mutation scores. Mutation analysis is deferred until
+                GUI coverage matures.
+              -->
+              <skip>true</skip>
+              <coverageThreshold>0</coverageThreshold>
+              <mutationThreshold>0</mutationThreshold>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>
@@ -0,0 +1,33 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.util.List;
+
+import javafx.stage.FileChooser;
+
+/**
+ * Funktionales Interface fuer den Datei-Auswaehldialog der GUI.
+ * <p>
+ * Kapselt die Abhaengigkeit zum nativen {@link FileChooser} in einem
+ * injizierbaren Hook, der in Tests durch eine einfache Lambda-Implementierung
+ * ersetzt werden kann. Die Standardimplementierung oeffnet einen echten
+ * nativen Datei-Dialog; Test-Stubs koennen einen festen Pfad zurueckgeben
+ * oder {@code null} simulieren (Abbrechen).
+ * <p>
+ * Im Gegensatz zur frueheren {@code BiFunction}-Variante nimmt dieser Hook
+ * auch die Liste der {@link FileChooser.ExtensionFilter} entgegen, damit der
+ * native Dialog die Filter tatsaechlich anwenden kann.
+ */
+@FunctionalInterface
+interface FilePickerDialog {
+
+    /**
+     * Oeffnet den Datei-Auswaehldialog und gibt den ausgewaehlten absoluten
+     * Pfad zurueck.
+     *
+     * @param title       der Titel des Dialogs
+     * @param initialPath der Anfangspfad als Hinweis; darf leer oder {@code null} sein
+     * @param filters     Liste der Dateitypfilter; darf leer sein, aber nicht {@code null}
+     * @return der ausgewaehlte absolute Pfad als String, oder {@code null} wenn abgebrochen
+     */
+    String pick(String title, String initialPath, List<FileChooser.ExtensionFilter> filters);
+}
@@ -0,0 +1,105 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.util.Optional;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import javafx.application.Application;
+
+/**
+ * Entry point for the JavaFX desktop GUI inbound adapter.
+ * <p>
+ * This class is the designated entry point through which Bootstrap launches the
+ * graphical user interface. It acts as the inbound adapter boundary: it receives
+ * control from Bootstrap and delegates to the JavaFX application lifecycle via
+ * {@link PdfUmbenennerGuiApplication}.
+ * <p>
+ * Responsibilities of this adapter:
+ * <ul>
+ *   <li>Accept the GUI start signal from Bootstrap</li>
+ *   <li>Launch the JavaFX application lifecycle via {@link Application#launch}</li>
+ *   <li>Ensure that all UI operations are dispatched on the JavaFX Application Thread</li>
+ *   <li>Ensure that all blocking operations (file I/O, network, database) run on
+ *       background worker threads and never block the UI thread</li>
+ * </ul>
+ * <p>
+ * This class must not be instantiated or called by any module other than Bootstrap.
+ * Domain, application, CLI adapter, and outbound adapter modules must remain
+ * free of dependencies on this class and on JavaFX in general.
+ * <p>
+ * The actual JavaFX {@link Application} subclass ({@link PdfUmbenennerGuiApplication})
+ * and all GUI view components are separate classes within this package. This entry
+ * point class coordinates the hand-off from the Bootstrap layer into the JavaFX lifecycle.
+ *
+ * <h2>Current scope</h2>
+ * <p>
+ * The adapter launches the editor shell with the unloaded start state, an optional startup
+ * notice, and a file-loading callback supplied by Bootstrap. File I/O and save behavior remain
+ * outside the current GUI step.
+ */
+public class GuiAdapter {
+
+    private static final Logger LOG = LogManager.getLogger(GuiAdapter.class);
+
+    /**
+     * Creates a new {@code GuiAdapter} instance.
+     * <p>
+     * Bootstrap is responsible for constructing this adapter and invoking
+     * {@link #start()} at the appropriate point in the application lifecycle.
+     * No JavaFX initialization is performed during construction; the JavaFX
+     * runtime is only started when {@link #start()} is called.
+     */
+    public GuiAdapter() {
+        // Bootstrap constructs this adapter before deciding to start the GUI.
+        // JavaFX initialization is deferred to start() to ensure the headless
+        // path is never burdened with premature JavaFX class loading.
+    }
+
+    /**
+     * Starts the JavaFX GUI and blocks until the user closes the window.
+     * <p>
+     * When {@code startupNotice} is present, the notice string is forwarded to
+     * {@link PdfUmbenennerGuiApplication} so it can be displayed to the user on startup.
+     * This is used when Bootstrap has detected a problem with the supplied
+     * {@code --config} path (e.g. the file was not found) and wishes to inform the
+     * user before the normal GUI shell is shown.
+     * <p>
+     * This method delegates to {@link Application#launch(Class, String...)} with
+     * {@link PdfUmbenennerGuiApplication} as the application class. The call blocks
+     * until the JavaFX application terminates (typically when the user closes the
+     * main window).
+     * <p>
+     * This method must be called from a thread that is permitted to run a JavaFX
+     * application (typically the main thread). It must not be called on the JavaFX
+     * Application Thread itself, and must not be called more than once per JVM process.
+     * <p>
+     * Upon normal GUI shutdown (user closes the window), this method returns
+     * normally. Bootstrap is responsible for deriving the appropriate exit code
+     * from the return.
+     *
+     * @param startupNotice an optional message to display to the user in the GUI on startup;
+     *                      when empty, no notice is shown; must not be {@code null}
+     * @throws IllegalStateException if the JavaFX runtime cannot be initialised
+     *                               or if the platform is not supported
+     */
+    public void start(Optional<String> startupNotice) {
+        start(GuiStartupContext.blank(startupNotice));
+    }
+
+    /**
+     * Starts the JavaFX GUI with the supplied startup context.
+     *
+     * @param startupContext startup data for the GUI; must not be {@code null}
+     */
+    public void start(GuiStartupContext startupContext) {
+        LOG.info("GUI-Adapter: JavaFX-Start wird eingeleitet.");
+        GuiStartupContextHolder.install(startupContext);
+        try {
+            Application.launch(PdfUmbenennerGuiApplication.class);
+        } finally {
+            GuiStartupContextHolder.clear();
+            LOG.info("GUI-Adapter: JavaFX-Anwendung wurde beendet.");
+        }
+    }
+}
@@ -0,0 +1,66 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.nio.file.Path;
+import java.util.Optional;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.SchedulerControlUseCase;
+
+/**
+ * Callback invoked by the workspace on a background thread after a configuration file
+ * has been successfully loaded from disk.
+ * <p>
+ * Bootstrap supplies an implementation that builds the application run context
+ * (migrate → load → validate → schema-init sequence) and, on success, also initialises
+ * the automatic scheduler. The workspace calls this initializer inside the same
+ * background submit that loads the editor state, so the JavaFX Application Thread is
+ * never blocked.
+ * <p>
+ * In isolated GUI tests a {@link #noOp() no-op} implementation can be used so that no
+ * Bootstrap wiring is required.
+ */
+@FunctionalInterface
+public interface GuiApplicationContextInitializer {
+
+    /**
+     * Attempts to initialise the application run context for the supplied configuration file.
+     * <p>
+     * If context initialisation succeeds and the configuration enables the scheduler, the
+     * scheduler is also wired and its use case is returned in the result. The caller is
+     * responsible for handing the scheduler use case to the scheduler tab on the JavaFX
+     * Application Thread via {@code Platform.runLater}.
+     * <p>
+     * This method must be called on a background worker thread, not on the JavaFX Application
+     * Thread.
+     *
+     * @param configFilePath path to the {@code .properties} configuration file; must exist on disk
+     * @return the result of the initialisation attempt; never {@code null}
+     */
+    InitResult initialize(Path configFilePath);
+
+    /**
+     * Returns a no-op initializer that always reports success and no scheduler.
+     * <p>
+     * Suitable for GUI tests and startup paths where no Bootstrap wiring is available.
+     *
+     * @return no-op initializer; never {@code null}
+     */
+    static GuiApplicationContextInitializer noOp() {
+        return configFilePath -> new InitResult(Optional.empty(), Optional.empty());
+    }
+
+    /**
+     * Result of a context initialisation attempt.
+     *
+     * @param contextError            empty on success; a human-readable German error message
+     *                                when initialisation failed — the GUI remains functional
+     *                                but falls back to per-run initialisation for batch runs;
+     *                                must not be {@code null}
+     * @param schedulerControlUseCase the scheduler use case when the configuration enables the
+     *                                scheduler and initialisation succeeded; empty otherwise;
+     *                                must not be {@code null}
+     */
+    record InitResult(
+            Optional<String> contextError,
+            Optional<SchedulerControlUseCase> schedulerControlUseCase) {
+    }
+}
@@ -0,0 +1,23 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.nio.file.Path;
+
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiConfigurationEditorState;
+
+/**
+ * Loads a configuration file into a GUI editor state.
+ * <p>
+ * The interface allows Bootstrap to provide the concrete file-loading and migration logic
+ * while the GUI only deals with editor states.
+ */
+@FunctionalInterface
+public interface GuiConfigurationFileLoader {
+
+    /**
+     * Loads the configuration file at the given path.
+     *
+     * @param configFilePath the file to load; must not be {@code null}
+     * @return the loaded editor state; never {@code null}
+     */
+    GuiConfigurationEditorState load(Path configFilePath);
+}
@@ -0,0 +1,34 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.nio.file.Path;
+
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiConfigurationValues;
+
+/**
+ * Writes a normalized {@code .properties} configuration file from the current editor values.
+ * <p>
+ * The interface allows Bootstrap to provide the concrete file-writing, backup and
+ * normalization logic while the GUI only deals with editor values and target paths.
+ * Implementations must follow the backup schema defined for this application:
+ * {@code <filename>.bak}, and on collision {@code <filename>.bak.1}, {@code .bak.2}, ...
+ * Existing backups are never overwritten.
+ */
+@FunctionalInterface
+public interface GuiConfigurationFileWriter {
+
+    /**
+     * Writes the given configuration values to the specified target path as a normalized
+     * {@code .properties} file.
+     * <p>
+     * When {@code targetPath} already exists on disk, the implementation must create a
+     * {@code .bak} backup of the existing file before overwriting it. The caller is
+     * responsible for obtaining user confirmation before invoking this method.
+     *
+     * @param values     the current editor values to serialize; must not be {@code null}
+     * @param targetPath the target file path to write to; must not be {@code null}
+     * @return the result of the write operation, including any API-key preservation note;
+     *         never {@code null}
+     * @throws GuiConfigurationWriteException if the file cannot be written
+     */
+    GuiConfigurationSaveResult write(GuiConfigurationValues values, Path targetPath);
+}
@@ -0,0 +1,31 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+/**
+ * Runtime exception thrown when the GUI configuration cannot be loaded.
+ */
+public class GuiConfigurationLoadException extends RuntimeException {
+
+    /**
+	 * 
+	 */
+	private static final long serialVersionUID = 5039061738684738963L;
+
+	/**
+     * Creates a new load exception.
+     *
+     * @param message the exception message
+     * @param cause the underlying cause
+     */
+    public GuiConfigurationLoadException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Creates a new load exception.
+     *
+     * @param message the exception message
+     */
+    public GuiConfigurationLoadException(String message) {
+        super(message);
+    }
+}
@@ -0,0 +1,65 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.nio.file.Path;
+import java.util.Objects;
+
+/**
+ * Carries the outcome of a successful configuration file write operation.
+ * <p>
+ * The result separates the written file path from supplementary observations such as
+ * API-key preservation events. This allows the GUI to update its header and editor
+ * state without inspecting the written file again, and to forward the preservation
+ * flag to later warning display logic without mixing that concern into the write
+ * implementation itself.
+ *
+ * @param savedPath              the path to which the file was written; never {@code null}
+ * @param apiKeyPreservedForProvider identifier of the provider whose API key was silently
+ *                               preserved because the GUI field was left empty while
+ *                               the existing property value was non-empty; {@code null}
+ *                               when no preservation occurred
+ */
+public record GuiConfigurationSaveResult(Path savedPath, String apiKeyPreservedForProvider) {
+
+    /**
+     * Creates a save result.
+     *
+     * @param savedPath                  the path that was written; must not be {@code null}
+     * @param apiKeyPreservedForProvider provider identifier when key was preserved; may be {@code null}
+     */
+    public GuiConfigurationSaveResult {
+        Objects.requireNonNull(savedPath, "savedPath must not be null");
+    }
+
+    /**
+     * Creates a save result with no API-key preservation event.
+     *
+     * @param savedPath the path that was written; must not be {@code null}
+     * @return a result without an API-key preservation note
+     */
+    public static GuiConfigurationSaveResult saved(Path savedPath) {
+        return new GuiConfigurationSaveResult(savedPath, null);
+    }
+
+    /**
+     * Creates a save result that records an API-key preservation event.
+     *
+     * @param savedPath              the path that was written; must not be {@code null}
+     * @param providerIdentifier     the provider for which the key was preserved;
+     *                               must not be {@code null}
+     * @return a result carrying the preservation note for later display
+     */
+    public static GuiConfigurationSaveResult savedWithPreservedKey(Path savedPath,
+                                                                   String providerIdentifier) {
+        Objects.requireNonNull(providerIdentifier, "providerIdentifier must not be null");
+        return new GuiConfigurationSaveResult(savedPath, providerIdentifier);
+    }
+
+    /**
+     * Returns whether an API-key preservation event occurred during this write operation.
+     *
+     * @return {@code true} when at least one provider API key was silently preserved
+     */
+    public boolean hasApiKeyPreservationNote() {
+        return apiKeyPreservedForProvider != null;
+    }
+}
@@ -0,0 +1,34 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+/**
+ * Thrown when a configuration file cannot be written by the GUI file writer.
+ * <p>
+ * This exception wraps low-level I/O failures so that the GUI layer does not have
+ * to handle raw {@link java.io.IOException} instances directly.
+ */
+public class GuiConfigurationWriteException extends RuntimeException {
+
+    /**
+	 * 
+	 */
+	private static final long serialVersionUID = -6970750036865888915L;
+
+	/**
+     * Creates an exception with the given message.
+     *
+     * @param message the error description; must not be {@code null}
+     */
+    public GuiConfigurationWriteException(String message) {
+        super(message);
+    }
+
+    /**
+     * Creates an exception with the given message and cause.
+     *
+     * @param message the error description; must not be {@code null}
+     * @param cause   the underlying cause; may be {@code null}
+     */
+    public GuiConfigurationWriteException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}
@@ -0,0 +1,287 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Consumer;
+import java.util.function.Function;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.ConfirmationDialogContent;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiMessageEntry;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiMessageSeverity;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionExecutionReport;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionExecutionService;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionOutcome;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionPlan;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.TechnicalTestReport;
+import javafx.application.Platform;
+
+/**
+ * Koordiniert den gesammelten Bestätigungsdialog und die anschließende Ausführung
+ * schreibender Korrekturmaßnahmen nach einem technischen Gesamttest.
+ * <p>
+ * Der Koordinator empfängt einen {@link TechnicalTestReport}, prüft ob korrigierbare
+ * Befunde vorliegen, leitet daraus einen {@link CorrectionPlan} ab, zeigt dem Benutzer
+ * einen gesammelten Bestätigungsdialog und führt die Korrekturen bei Bestätigung über
+ * den {@link CorrectionExecutionService} auf einem Hintergrund-Worker-Thread aus.
+ * Ergebnisse werden in die geteilte {@code pendingMessages}-Liste eingehängt.
+ *
+ * <h2>Ablauf</h2>
+ * <ol>
+ *   <li>Bericht erhält: prüfen ob {@code hasCorrectableFindings()}.</li>
+ *   <li>Wenn keine korrigierbaren Befunde: kein Dialog, keine Aktion.</li>
+ *   <li>Wenn korrigierbare Befunde: {@link CorrectionPlan} ableiten.</li>
+ *   <li>Dialog auf FX-Thread anzeigen.</li>
+ *   <li>Bei Bestätigung: Korrekturen auf Worker-Thread ausführen.</li>
+ *   <li>Ergebnisse via {@code Platform.runLater} auf FX-Thread zurückführen.</li>
+ *   <li>Meldungen in {@code pendingMessages} einhängen (Replace-Semantik).</li>
+ * </ol>
+ *
+ * <h2>Threading-Kontrakt</h2>
+ * <p>
+ * {@link #offerCorrections(TechnicalTestReport)} muss auf dem JavaFX Application Thread
+ * aufgerufen werden. I/O (Ausführung der Korrekturen) läuft auf einem dedizierten
+ * Daemon-Hintergrund-Thread. UI-Updates erfolgen ausschließlich via
+ * {@code Platform.runLater}.
+ *
+ * <h2>Keine stillen Korrekturen</h2>
+ * <p>
+ * Ohne ausdrückliche Benutzerbestätigung werden keine schreibenden Änderungen ausgeführt.
+ * Bei Dialog-Abbruch bleibt der Zustand unverändert.
+ *
+ * <h2>Anti-Scope</h2>
+ * <p>
+ * Dieser Koordinator führt keine Provider-nahen Korrekturen, keine Änderung fachlich
+ * riskanter Werte und keine automatischen Laufstarts durch.
+ */
+public final class GuiCorrectionDialogCoordinator {
+
+    /** Quell-Tag für Einträge in {@code pendingMessages}, die von diesem Koordinator stammen. */
+    static final String SOURCE_TAG = "Korrekturen";
+
+    private static final Logger LOG = LogManager.getLogger(GuiCorrectionDialogCoordinator.class);
+
+    private final CorrectionExecutionService correctionExecutionService;
+    private final List<GuiMessageEntry> pendingMessages;
+    private final Consumer<Void> refreshCallback;
+
+    /**
+     * Funktion, die dem Benutzer den Bestätigungsdialog zeigt.
+     * <p>
+     * Erhält den {@link ConfirmationDialogContent} und gibt {@code true} zurück, wenn der
+     * Benutzer „Fortfahren" wählt, andernfalls {@code false}. Standard: echter Alert.
+     * Paket-privat für Test-Substitution.
+     */
+    Function<ConfirmationDialogContent, Boolean> dialogSupplier;
+
+    /**
+     * Factory für den Hintergrund-Worker-Thread.
+     * Standard: Daemon-Thread namens {@code gui-correction-worker}.
+     * Paket-privat für Test-Substitution.
+     */
+    Function<Runnable, Thread> correctionThreadFactory;
+
+    /**
+     * Verbraucher zur Rückführung des Ergebnisses auf den FX-Thread.
+     * Standard: {@code Platform.runLater}. Paket-privat für Test-Substitution.
+     */
+    java.util.function.Consumer<Runnable> resultDelivery;
+
+    /**
+     * Erstellt einen neuen Koordinator.
+     *
+     * @param correctionExecutionService Service für die Ausführung von Korrekturen; darf nicht {@code null} sein
+     * @param pendingMessages            geteilte veränderliche Nachrichtenliste; darf nicht {@code null} sein
+     * @param refreshCallback            Callback nach Anwendung der Ergebnisse (z. B. View-Aktualisierung);
+     *                                   darf nicht {@code null} sein
+     * @throws NullPointerException wenn einer der Parameter {@code null} ist
+     */
+    public GuiCorrectionDialogCoordinator(CorrectionExecutionService correctionExecutionService,
+                                           List<GuiMessageEntry> pendingMessages,
+                                           Consumer<Void> refreshCallback) {
+        this.correctionExecutionService = Objects.requireNonNull(correctionExecutionService,
+                "correctionExecutionService must not be null");
+        this.pendingMessages = Objects.requireNonNull(pendingMessages,
+                "pendingMessages must not be null");
+        this.refreshCallback = Objects.requireNonNull(refreshCallback,
+                "refreshCallback must not be null");
+
+        this.dialogSupplier = this::showConfirmationDialog;
+        this.correctionThreadFactory = task -> {
+            Thread t = new Thread(task, "gui-correction-worker");
+            t.setDaemon(true);
+            return t;
+        };
+        this.resultDelivery = Platform::runLater;
+    }
+
+    /**
+     * Prüft den Bericht auf korrigierbare Befunde, zeigt bei Bedarf den Bestätigungsdialog
+     * und führt die Korrekturen nach Bestätigung asynchron aus.
+     * <p>
+     * Wenn der Bericht keine korrigierbaren Befunde enthält ({@code hasCorrectableFindings()
+     * == false}), wird kein Dialog angezeigt und keine Aktion ausgeführt.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     *
+     * @param report der vollständige Gesamttestbericht; darf nicht {@code null} sein
+     */
+    public void offerCorrections(TechnicalTestReport report) {
+        Objects.requireNonNull(report, "report must not be null");
+
+        if (!report.hasCorrectableFindings()) {
+            LOG.debug("Gesamttest: Keine korrigierbaren Befunde – kein Bestätigungsdialog.");
+            return;
+        }
+
+        CorrectionPlan plan = report.deriveCorrectionPlan();
+        if (!plan.hasCorrections()) {
+            LOG.debug("Gesamttest: Korrekturplan ist leer – kein Bestätigungsdialog.");
+            return;
+        }
+
+        LOG.info("Gesamttest: {} korrigierbare Befunde. Bestätigungsdialog wird angezeigt.", plan.size());
+
+        ConfirmationDialogContent dialogContent = ConfirmationDialogContent.fromPlan(plan);
+        boolean confirmed = dialogSupplier.apply(dialogContent);
+
+        if (!confirmed) {
+            LOG.info("Bestätigungsdialog: Benutzer hat Korrekturen abgelehnt. Keine Änderungen.");
+            return;
+        }
+
+        LOG.info("Bestätigungsdialog: Benutzer hat Korrekturen bestätigt. Ausführung startet.");
+        Runnable task = () -> {
+            CorrectionExecutionReport executionReport = correctionExecutionService.execute(plan);
+            resultDelivery.accept(() -> {
+                applyResult(executionReport);
+                refreshCallback.accept(null);
+            });
+        };
+
+        Thread worker = correctionThreadFactory.apply(task);
+        worker.start();
+    }
+
+    /**
+     * Wendet das Ergebnis der Korrekturausführung auf die geteilte Nachrichtenliste an.
+     * <p>
+     * Entfernt alle vorherigen Einträge mit Quelle {@link #SOURCE_TAG} und fügt für jedes
+     * {@link CorrectionOutcome} einen neuen Eintrag hinzu. Zusätzlich wird eine Zusammenfassung
+     * angehängt.
+     * <p>
+     * Muss nur auf dem JavaFX Application Thread aufgerufen werden (via {@code resultDelivery}).
+     *
+     * @param report das Ausführungsergebnis; darf nicht {@code null} sein
+     */
+    private void applyResult(CorrectionExecutionReport report) {
+        // Alte Einträge mit Source-Tag entfernen (Replace-Semantik)
+        pendingMessages.removeIf(msg -> SOURCE_TAG.equals(msg.source().orElse("")));
+
+        long appliedCount = 0;
+        long failedCount = 0;
+        long notAttemptedCount = 0;
+
+        for (CorrectionOutcome outcome : report.outcomes()) {
+            switch (outcome) {
+                case CorrectionOutcome.Applied applied -> {
+                    pendingMessages.add(GuiMessageEntry.of(
+                            GuiMessageSeverity.INFO,
+                            "Korrektur angewendet: " + applied.suggestion().descriptionForUser()
+                                    + " – " + applied.message(),
+                            SOURCE_TAG));
+                    appliedCount++;
+                    LOG.info("Korrektur angewendet: {} – {}", applied.suggestion().descriptionForUser(),
+                            applied.message());
+                }
+                case CorrectionOutcome.Failed failed -> {
+                    pendingMessages.add(GuiMessageEntry.of(
+                            GuiMessageSeverity.ERROR,
+                            "Korrektur fehlgeschlagen: " + failed.suggestion().descriptionForUser()
+                                    + " (" + failed.errorMessage() + ")",
+                            SOURCE_TAG));
+                    failedCount++;
+                    LOG.warn("Korrektur fehlgeschlagen: {} – {}", failed.suggestion().descriptionForUser(),
+                            failed.errorMessage());
+                }
+                case CorrectionOutcome.NotAttempted notAttempted -> {
+                    pendingMessages.add(GuiMessageEntry.of(
+                            GuiMessageSeverity.HINT,
+                            "Korrektur nicht durchgeführt: " + notAttempted.suggestion().descriptionForUser()
+                                    + " – " + notAttempted.reason(),
+                            SOURCE_TAG));
+                    notAttemptedCount++;
+                    LOG.info("Korrektur nicht durchgeführt: {} – {}", notAttempted.suggestion().descriptionForUser(),
+                            notAttempted.reason());
+                }
+            }
+        }
+
+        // Zusammenfassung
+        String summary = "Korrekturausführung abgeschlossen: "
+                + appliedCount + " angewendet, "
+                + failedCount + " fehlgeschlagen, "
+                + notAttemptedCount + " nicht versucht.";
+        pendingMessages.add(GuiMessageEntry.of(GuiMessageSeverity.INFO, summary, SOURCE_TAG));
+        LOG.info("Korrekturausführung abgeschlossen: {} angewendet, {} fehlgeschlagen, {} nicht versucht.",
+                appliedCount, failedCount, notAttemptedCount);
+    }
+
+    /**
+     * Zeigt den echten JavaFX-Bestätigungsdialog und gibt die Benutzerentscheidung zurück.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden. Standard-Fokus liegt auf
+     * dem Abbrechen-Button (kein versehentliches Bestätigen durch Enter).
+     *
+     * @param content der Dialoginhalt; darf nicht {@code null} sein
+     * @return {@code true} wenn der Benutzer „Fortfahren" wählt, sonst {@code false}
+     */
+    private boolean showConfirmationDialog(ConfirmationDialogContent content) {
+        javafx.scene.control.ButtonType proceedButton =
+                new javafx.scene.control.ButtonType("Fortfahren",
+                        javafx.scene.control.ButtonBar.ButtonData.OK_DONE);
+        javafx.scene.control.ButtonType cancelButton =
+                new javafx.scene.control.ButtonType("Abbrechen",
+                        javafx.scene.control.ButtonBar.ButtonData.CANCEL_CLOSE);
+
+        javafx.scene.control.Alert alert = new javafx.scene.control.Alert(
+                javafx.scene.control.Alert.AlertType.CONFIRMATION);
+        alert.setTitle(content.title());
+        alert.setHeaderText(content.introText());
+
+        StringBuilder correctionListText = new StringBuilder();
+        for (String line : content.correctionLines()) {
+            correctionListText.append("• ").append(line).append("\n");
+        }
+        correctionListText.append("\nFortfahren?");
+        alert.setContentText(correctionListText.toString());
+
+        alert.getButtonTypes().setAll(proceedButton, cancelButton);
+
+        // Standard-Fokus: Abbrechen
+        javafx.scene.Node cancelNode = alert.getDialogPane().lookupButton(cancelButton);
+        if (cancelNode instanceof javafx.scene.control.Button btn) {
+            btn.setDefaultButton(true);
+        }
+        javafx.scene.Node proceedNode = alert.getDialogPane().lookupButton(proceedButton);
+        if (proceedNode instanceof javafx.scene.control.Button btn) {
+            btn.setDefaultButton(false);
+        }
+
+        java.util.Optional<javafx.scene.control.ButtonType> result = alert.showAndWait();
+        return result.isPresent() && result.get() == proceedButton;
+    }
+
+    /**
+     * Gibt eine unveränderliche Momentaufnahme der aktuell ausstehenden Nachrichten zurück.
+     * <p>
+     * Ausschließlich für Tests gedacht.
+     *
+     * @return unveränderliche Kopie der Nachrichtenliste; nie {@code null}
+     */
+    public List<GuiMessageEntry> pendingMessagesSnapshot() {
+        return List.copyOf(pendingMessages);
+    }
+}
@@ -0,0 +1,41 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.nio.file.Path;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.CreateNewDatabaseUseCase.CreateNewDatabaseResult;
+
+/**
+ * GUI-internes Bridge-Interface zwischen dem Workspace und dem
+ * {@link de.gecheckt.pdf.umbenenner.application.port.in.CreateNewDatabaseUseCase}.
+ * <p>
+ * Dieses Interface ist <em>kein</em> hexagonaler Outbound-Port der Application-Schicht.
+ * Es ist eine modul-interne Brücke, über die Bootstrap die DB-Anlage- und Wechsellogik
+ * für die GUI bereitstellt, ohne dass der GUI-Adapter direkt auf den Use-Case oder die
+ * darunterliegenden Outbound-Ports zugreift.
+ * <p>
+ * <strong>Threading:</strong> Implementierungen dürfen blockierende Operationen
+ * ausführen (Flyway-Migration, Verbindungstest, atomares Verschieben einer Datei).
+ * Sie müssen daher von einem Hintergrund-Worker-Thread aufgerufen werden. Der Aufruf
+ * blockiert, bis das Ergebnis vollständig vorliegt.
+ */
+@FunctionalInterface
+public interface GuiCreateNewDatabasePort {
+
+    /**
+     * Legt eine neue, leere SQLite-Datenbankdatei am übergebenen Zielpfad an und
+     * stellt die aktive Datenbankreferenz auf diese Datei um.
+     *
+     * @param configFilePath Pfad zur aktuell geladenen {@code .properties}-Datei,
+     *                       oder {@code null}, wenn (noch) keine Konfiguration
+     *                       geladen ist. Die Bootstrap-Implementierung leitet
+     *                       daraus den Pfad der aktuell aktiven SQLite-Datei ab,
+     *                       sofern noch kein Override vom
+     *                       {@link de.gecheckt.pdf.umbenenner.application.port.out.ActiveDatabaseContextPort}
+     *                       gesetzt ist.
+     * @param targetFile     der vom Benutzer ausgewählte Zielpfad; darf nicht
+     *                       {@code null} sein
+     * @return strukturiertes Ergebnis mit Erfolg oder klassifiziertem Fehler;
+     *         nie {@code null}
+     */
+    CreateNewDatabaseResult createNewDatabase(Path configFilePath, Path targetFile);
+}
@@ -0,0 +1,307 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.function.Function;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiMessageEntry;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiMessageSeverity;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiModelFieldContainer;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiModelSource;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiProviderConfigurationState;
+import de.gecheckt.pdf.umbenenner.application.config.provider.AiProviderFamily;
+import de.gecheckt.pdf.umbenenner.application.port.out.modelcatalog.AiModelCatalogPort;
+import de.gecheckt.pdf.umbenenner.application.port.out.modelcatalog.ModelCatalogRequest;
+import de.gecheckt.pdf.umbenenner.application.port.out.modelcatalog.ModelCatalogResult;
+import javafx.application.Platform;
+
+/**
+ * Coordinates asynchronous model catalogue retrieval for the GUI provider section.
+ * <p>
+ * This coordinator is responsible for:
+ * <ul>
+ *   <li>Triggering a background HTTP call via {@link AiModelCatalogPort} on a dedicated
+ *       daemon thread named {@code gui-model-catalog}.</li>
+ *   <li>Returning the result to the JavaFX Application Thread via {@code Platform.runLater}.</li>
+ *   <li>Updating the per-provider {@link GuiModelFieldContainer} to show either a
+ *       non-editable {@code ComboBox} (success) or a manual text field (all other cases).</li>
+ *   <li>Appending a {@link GuiMessageEntry} to the supplied pending-messages list for each
+ *       completed retrieval attempt, so later GUI layers can display the result.</li>
+ * </ul>
+ * <p>
+ * Parallele Abrufanfragen (z.&nbsp;B. durch schnellen Provider-Wechsel oder mehrfaches Klicken
+ * auf „Modelle neu laden") werden durch einen Generationszähler entschärft: Jede neue Anfrage
+ * erhöht den Zähler. Wenn das Ergebnis eines Hintergrund-Threads auf dem JavaFX-Thread
+ * verarbeitet wird, prüft der Coordinator, ob die Generationsnummer noch aktuell ist. Veraltete
+ * Ergebnisse (aus einer früheren Anfrage) werden verworfen, sodass stets nur das Ergebnis der
+ * jüngsten Anfrage in die Meldungsliste und die Feldcontainer geschrieben wird.
+ * <p>
+ * The worker thread factory is injectable so tests can supply a synchronous or latch-guarded
+ * executor without spinning a real OS thread.
+ * <p>
+ * This class is not thread-safe by itself. All methods intended to mutate GUI state must be
+ * called on the JavaFX Application Thread. Background threads only interact through
+ * {@code Platform.runLater}.
+ */
+public final class GuiModelCatalogCoordinator {
+    private static final String LOG_MODEL_FETCH_FMT = "GUI-Modellabruf: {} (Provider: {})";
+    private static final String OPERATION_MODELLABRUF = "Modellabruf";
+
+
+
+    private static final Logger LOG = LogManager.getLogger(GuiModelCatalogCoordinator.class);
+
+    /** Default timeout used when no timeout is configured in the provider state. */
+    static final int DEFAULT_TIMEOUT_SECONDS = 10;
+
+    private final AiModelCatalogPort modelCatalogPort;
+    private final List<GuiMessageEntry> pendingMessages;
+
+    /**
+     * Factory for the background worker thread. Package-private to allow test substitution.
+     * The default creates a daemon thread named {@code gui-model-catalog}.
+     */
+    Function<Runnable, Thread> modelCatalogThreadFactory;
+
+    /** Per-provider field containers; populated by the workspace when it builds provider blocks. */
+    private final Map<AiProviderFamily, GuiModelFieldContainer> fieldContainers =
+            new ConcurrentHashMap<>();
+
+    /**
+     * Generationszähler zur Erkennung veralteter Abruf-Ergebnisse.
+     * Wird bei jeder neuen Anfrage in {@link #triggerModelRetrieval} atomar erhöht.
+     * Hintergrund-Threads erfassen die Generation beim Start; auf dem JavaFX-Thread wird
+     * das Ergebnis verworfen, wenn die gespeicherte Generation nicht mehr aktuell ist.
+     */
+    private final AtomicLong retrievalGeneration = new AtomicLong(0);
+
+    /**
+     * Consumer that delivers the retrieval result. In production this wraps the call in
+     * {@code Platform.runLater}. In tests it can be replaced with a direct call so the result
+     * is applied immediately on the worker thread without needing an FX queue drain.
+     * Package-private to allow test substitution.
+     */
+    java.util.function.Consumer<Runnable> resultDelivery = Platform::runLater;
+
+    /**
+     * Optional callback invoked on the JavaFX Application Thread after each retrieval result has
+     * been applied. The workspace uses this hook to refresh the central message area and field-error
+     * labels without coupling the coordinator to the workspace implementation.
+     * Package-private to allow substitution in tests.
+     */
+    Runnable postResultCallback = () -> { };
+
+    /**
+     * Creates a coordinator backed by the given catalogue port and shared message list.
+     *
+     * @param modelCatalogPort port used for background HTTP calls; must not be {@code null}
+     * @param pendingMessages  mutable list to append result messages to; must not be {@code null}
+     */
+    public GuiModelCatalogCoordinator(AiModelCatalogPort modelCatalogPort,
+                                      List<GuiMessageEntry> pendingMessages) {
+        this.modelCatalogPort = Objects.requireNonNull(modelCatalogPort,
+                "modelCatalogPort must not be null");
+        this.pendingMessages = Objects.requireNonNull(pendingMessages,
+                "pendingMessages must not be null");
+        this.modelCatalogThreadFactory = task -> {
+            Thread t = new Thread(task, "gui-model-catalog");
+            t.setDaemon(true);
+            return t;
+        };
+    }
+
+    /**
+     * Registers a {@link GuiModelFieldContainer} for the given provider family.
+     * <p>
+     * Must be called on the JavaFX Application Thread before the first retrieval is triggered.
+     *
+     * @param family    the provider family this container belongs to; must not be {@code null}
+     * @param container the container to register; must not be {@code null}
+     */
+    public void registerFieldContainer(AiProviderFamily family, GuiModelFieldContainer container) {
+        Objects.requireNonNull(family, "family must not be null");
+        Objects.requireNonNull(container, "container must not be null");
+        fieldContainers.put(family, container);
+    }
+
+    /**
+     * Triggers an asynchronous model catalogue retrieval for the given provider family.
+     * <p>
+     * The retrieval is performed on a background worker thread. The result is delivered back
+     * to the JavaFX Application Thread via {@code Platform.runLater}. The registered
+     * {@link GuiModelFieldContainer} for the provider is updated accordingly, and a
+     * {@link GuiMessageEntry} is appended to the pending-messages list.
+     * <p>
+     * If no field container is registered for the provider, the call is a no-op.
+     * <p>
+     * Must be called on the JavaFX Application Thread.
+     *
+     * @param family        the provider family to retrieve models for; must not be {@code null}
+     * @param providerState the current editor state for the provider; must not be {@code null}
+     */
+    public void triggerModelRetrieval(AiProviderFamily family,
+                                      GuiProviderConfigurationState providerState) {
+        Objects.requireNonNull(family, "family must not be null");
+        Objects.requireNonNull(providerState, "providerState must not be null");
+
+        GuiModelFieldContainer container = fieldContainers.get(family);
+        if (container == null) {
+            LOG.debug("GUI-Modellabruf: Kein Feld-Container für Provider '{}' registriert – übersprungen.",
+                    family.getIdentifier());
+            return;
+        }
+
+        // Capture the current manual value before starting the background call.
+        String previousManualValue = container.currentModelValue();
+
+        // Build the request from the current editor state.
+        ModelCatalogRequest request = buildRequest(family, providerState);
+
+        // Generationsnummer erhöhen – laufende Hintergrund-Threads mit einer älteren
+        // Generationsnummer verwerfen ihr Ergebnis, sobald sie auf dem FX-Thread ankommen.
+        long currentGeneration = retrievalGeneration.incrementAndGet();
+
+        LOG.info("GUI-Modellabruf: Modelllistenabruf für Provider '{}' gestartet (Generation {}).",
+                family.getIdentifier(), currentGeneration);
+
+        Runnable task = () -> {
+            ModelCatalogResult result = modelCatalogPort.fetchAvailableModels(request);
+            resultDelivery.accept(() -> {
+                // Veraltetes Ergebnis verwerfen, wenn inzwischen eine neuere Anfrage gestartet wurde.
+                if (retrievalGeneration.get() != currentGeneration) {
+                    LOG.debug("GUI-Modellabruf: Ergebnis für Provider '{}' verworfen"
+                            + " (Generation {} ist nicht mehr aktuell).",
+                            family.getIdentifier(), currentGeneration);
+                    return;
+                }
+                applyResult(family, container, result, previousManualValue);
+                postResultCallback.run();
+            });
+        };
+
+        Thread worker = modelCatalogThreadFactory.apply(task);
+        worker.start();
+    }
+
+    /**
+     * Applies the result of a completed model catalogue retrieval to the field container and
+     * appends a message entry to the pending-messages list.
+     * <p>
+     * Must only be called on the JavaFX Application Thread (via {@code Platform.runLater}).
+     *
+     * @param family              the provider family that was queried; must not be {@code null}
+     * @param container           the field container to update; must not be {@code null}
+     * @param result              the retrieval result; must not be {@code null}
+     * @param previousManualValue the model value that was in the text field before the call
+     */
+    private void applyResult(AiProviderFamily family,
+                             GuiModelFieldContainer container,
+                             ModelCatalogResult result,
+                             String previousManualValue) {
+        // Remove any previous message entries from an earlier retrieval so messages do not
+        // accumulate across repeated triggers of the same retrieval action.
+        pendingMessages.removeIf(msg -> OPERATION_MODELLABRUF.equals(msg.source().orElse("")));
+
+        String displayName = displayNameFor(family);
+
+        switch (result) {
+            case ModelCatalogResult.Success success -> {
+                List<String> models = success.models();
+                container.applyModelList(models, previousManualValue);
+                String message = "Modellliste für " + displayName + " geladen ("
+                        + models.size() + " " + (models.size() == 1 ? "Eintrag" : "Einträge") + ").";
+                pendingMessages.add(GuiMessageEntry.of(GuiMessageSeverity.INFO, message, OPERATION_MODELLABRUF));
+                LOG.info(LOG_MODEL_FETCH_FMT, message, family.getIdentifier());
+            }
+            case ModelCatalogResult.EmptyList emptyList -> {
+                container.applyManualFallback(GuiModelSource.LIST_UNAVAILABLE_MANUAL_INPUT);
+                String message = "Provider " + displayName
+                        + " liefert aktuell keine Modelle. Manuelle Eingabe aktiv.";
+                pendingMessages.add(GuiMessageEntry.of(GuiMessageSeverity.HINT, message, OPERATION_MODELLABRUF));
+                LOG.warn(LOG_MODEL_FETCH_FMT, message, family.getIdentifier());
+            }
+            case ModelCatalogResult.IncompleteConfiguration incomplete -> {
+                container.applyManualFallback(GuiModelSource.LIST_UNAVAILABLE_MANUAL_INPUT);
+                String message = "Modellliste nicht abrufbar: " + incomplete.missingReason()
+                        + ". Manuelle Eingabe aktiv.";
+                pendingMessages.add(GuiMessageEntry.of(GuiMessageSeverity.WARNING, message, OPERATION_MODELLABRUF));
+                LOG.warn(LOG_MODEL_FETCH_FMT, message, family.getIdentifier());
+            }
+            case ModelCatalogResult.TechnicalFailure failure -> {
+                container.applyManualFallback(GuiModelSource.LIST_FAILED_MANUAL_INPUT);
+                String message = "Modellliste nicht abrufbar (" + failure.errorCategory()
+                        + "). Manuelle Eingabe aktiv.";
+                pendingMessages.add(GuiMessageEntry.of(GuiMessageSeverity.ERROR, message, OPERATION_MODELLABRUF));
+                LOG.warn("GUI-Modellabruf: {} Detail: {} (Provider: {})",
+                        message, failure.errorDetail(), family.getIdentifier());
+            }
+        }
+    }
+
+    /**
+     * Builds a {@link ModelCatalogRequest} from the current provider editor state.
+     * <p>
+     * Missing or blank values are passed as {@code Optional.empty()} so the adapter can apply
+     * its own defaults or return {@link ModelCatalogResult.IncompleteConfiguration} if required
+     * values are absent.
+     *
+     * @param family        the target provider family; must not be {@code null}
+     * @param providerState the current provider editor state; must not be {@code null}
+     * @return a new request; never {@code null}
+     */
+    private static ModelCatalogRequest buildRequest(AiProviderFamily family,
+                                                    GuiProviderConfigurationState providerState) {
+        Optional<String> baseUrl = Optional.ofNullable(providerState.baseUrl())
+                .filter(s -> !s.isBlank());
+        Optional<String> apiKey = Optional.ofNullable(providerState.apiKey())
+                .map(keyState -> keyState.propertyValue())
+                .filter(s -> !s.isBlank());
+
+        int timeout = DEFAULT_TIMEOUT_SECONDS;
+        String timeoutStr = providerState.timeoutSeconds();
+        if (timeoutStr != null && !timeoutStr.isBlank()) {
+            try {
+                int parsed = Integer.parseInt(timeoutStr.trim());
+                if (parsed > 0) {
+                    timeout = parsed;
+                }
+            } catch (NumberFormatException ignored) {
+                // Use default.
+            }
+        }
+
+        return new ModelCatalogRequest(family.getIdentifier(), baseUrl, apiKey, timeout);
+    }
+
+    /**
+     * Returns a human-readable display name for the given provider family.
+     *
+     * @param family the provider family; must not be {@code null}
+     * @return the display name; never {@code null}
+     */
+    private static String displayNameFor(AiProviderFamily family) {
+        return switch (family) {
+            case CLAUDE -> "Claude";
+            case OPENAI_COMPATIBLE -> "OpenAI-kompatibel";
+        };
+    }
+
+    /**
+     * Returns an unmodifiable snapshot of the pending messages collected so far.
+     * <p>
+     * This method is intended for tests that need to inspect the message list after
+     * a retrieval completes.
+     *
+     * @return unmodifiable list of pending messages; never {@code null}
+     */
+    public List<GuiMessageEntry> pendingMessagesSnapshot() {
+        return List.copyOf(pendingMessages);
+    }
+}
@@ -0,0 +1,64 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import de.gecheckt.pdf.umbenenner.application.port.out.PromptLoadingResult;
+import de.gecheckt.pdf.umbenenner.application.port.out.PromptSaveResult;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionOutcome;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionSuggestion;
+
+/**
+ * GUI-internes Bridge-Interface zwischen dem Prompt-Editor-Tab und dem zugehörigen
+ * Use-Case in der Application-Schicht.
+ * <p>
+ * Dieses Interface ist <em>kein</em> hexagonaler Outbound-Port der Application-Schicht.
+ * Es ist eine modul-interne Brücke, über die Bootstrap die vom Use-Case bereitgestellte
+ * Funktionalität in den GUI-Adapter einschleust, ohne dass der GUI-Adapter direkt auf
+ * {@link de.gecheckt.pdf.umbenenner.application.port.out.PromptPort} oder das Dateisystem
+ * zugreift.
+ * <p>
+ * <strong>Verantwortung:</strong>
+ * <ul>
+ *   <li>Prompt-Inhalt für die Anzeige im Editor laden.</li>
+ *   <li>Bearbeiteten Inhalt atomar speichern.</li>
+ *   <li>Standard-Prompt-Datei anlegen, wenn noch keine vorhanden ist.</li>
+ * </ul>
+ * <p>
+ * Alle Implementierungen dieses Interfaces liegen in {@code pdf-umbenenner-bootstrap}.
+ * Das GUI-Modul kennt ausschließlich den Interface-Typ.
+ */
+public interface GuiPromptEditorPort {
+
+    /**
+     * Lädt den aktuellen Prompt-Inhalt aus der konfigurierten Quelle.
+     * <p>
+     * Muss auf einem Worker-Thread aufgerufen werden; das Ergebnis wird via
+     * {@code Platform.runLater} in den JavaFX Application Thread übergeben.
+     *
+     * @return {@link PromptLoadingResult} mit Inhalt und Identifikator bei Erfolg,
+     *         oder einem klassifizierten Fehler; nie {@code null}
+     */
+    PromptLoadingResult loadCurrentPrompt();
+
+    /**
+     * Speichert den übergebenen Inhalt atomar in die konfigurierte Prompt-Datei.
+     * <p>
+     * Muss auf einem Worker-Thread aufgerufen werden; das Ergebnis wird via
+     * {@code Platform.runLater} in den JavaFX Application Thread übergeben.
+     *
+     * @param content der zu speichernde Inhalt; darf nicht {@code null} sein
+     * @return {@link PromptSaveResult} mit Erfolg oder klassifiziertem Fehler; nie {@code null}
+     * @throws NullPointerException wenn {@code content} null ist
+     */
+    PromptSaveResult save(String content);
+
+    /**
+     * Legt eine Standard-Prompt-Datei an, falls noch keine vorhanden ist.
+     * <p>
+     * Muss auf einem Worker-Thread aufgerufen werden; das Ergebnis wird via
+     * {@code Platform.runLater} in den JavaFX Application Thread übergeben.
+     *
+     * @param suggestion Korrekturvorschlag mit dem Zielpfad; darf nicht {@code null} sein
+     * @return {@link CorrectionOutcome} mit dem Ergebnis der Aktion; nie {@code null}
+     * @throws NullPointerException wenn {@code suggestion} null ist
+     */
+    CorrectionOutcome createDefaultPromptIfMissing(CorrectionSuggestion.CreatePromptFile suggestion);
+}
@@ -0,0 +1,22 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+/**
+ * Fabrik, die für einen gegebenen Prompt-Dateipfad einen {@link GuiPromptEditorPort} erzeugt.
+ * <p>
+ * Wird vom {@link GuiConfigurationEditorWorkspace} genutzt, um nach einem Konfigurations-Laden
+ * oder -Speichern einen neuen Port für den {@link GuiPromptEditorTab} zu erstellen, ohne dass
+ * der GUI-Adapter direkt von Bootstrap-internen Klassen abhängen muss.
+ * <p>
+ * Alle Implementierungen liegen in {@code pdf-umbenenner-bootstrap}.
+ */
+@FunctionalInterface
+public interface GuiPromptEditorPortFactory {
+
+    /**
+     * Erzeugt einen {@link GuiPromptEditorPort} für den angegebenen Prompt-Dateipfad.
+     *
+     * @param promptFilePath konfigurierter Pfad zur Prompt-Datei; darf nicht {@code null} sein
+     * @return vollständig verdrahteter Port; nie {@code null}
+     */
+    GuiPromptEditorPort create(String promptFilePath);
+}
@@ -0,0 +1,413 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.util.Objects;
+import java.util.Optional;
+import java.util.function.Consumer;
+import java.util.function.Function;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import de.gecheckt.pdf.umbenenner.application.port.out.PromptLoadingFailure;
+import de.gecheckt.pdf.umbenenner.application.port.out.PromptLoadingSuccess;
+import de.gecheckt.pdf.umbenenner.application.port.out.PromptSaveResult;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionOutcome;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionSuggestion;
+import javafx.application.Platform;
+import javafx.geometry.Insets;
+import javafx.geometry.Pos;
+import javafx.scene.control.Alert;
+import javafx.scene.control.Button;
+import javafx.scene.control.ButtonType;
+import javafx.scene.control.Label;
+import javafx.scene.control.Tab;
+import javafx.scene.control.TextArea;
+import javafx.scene.control.Tooltip;
+import javafx.scene.layout.BorderPane;
+import javafx.scene.layout.HBox;
+import javafx.scene.layout.Priority;
+import javafx.scene.layout.VBox;
+import javafx.scene.text.Font;
+
+/**
+ * Tab „Prompt" im Hauptfenster des GUI-Adapters.
+ * <p>
+ * Ermöglicht das Lesen, Bearbeiten und Speichern der konfigurierten KI-Prompt-Datei
+ * direkt aus der Oberfläche heraus, ohne einen externen Editor öffnen zu müssen.
+ * <p>
+ * <strong>Verhalten:</strong>
+ * <ul>
+ *   <li>Beim Öffnen des Tabs wird der aktuelle Prompt-Inhalt auf einem Worker-Thread geladen.</li>
+ *   <li>Bearbeitungen erzeugen einen Dirty-State; der Tab-Titel erhält einen Asterisk.</li>
+ *   <li>„Speichern" schreibt den Inhalt atomar via {@link GuiPromptEditorPort}.</li>
+ *   <li>„Auf Standard zurücksetzen" befüllt die TextArea mit dem Default-Template,
+ *       ohne zu speichern.</li>
+ *   <li>Bei fehlendem Prompt wird ein Hinweis und ein „Standard-Prompt erstellen"-Button
+ *       angezeigt.</li>
+ *   <li>Tab-Wechsel oder Schließen mit Dirty-State löst einen Bestätigungsdialog aus.</li>
+ * </ul>
+ * <p>
+ * <strong>Threading:</strong> Alle blockierenden Operationen (Laden, Speichern,
+ * Prompt-Datei anlegen) laufen auf einem Worker-Thread. UI-Aktualisierungen erfolgen
+ * ausschließlich via {@code Platform.runLater}.
+ */
+public class GuiPromptEditorTab {
+
+    private static final Logger LOG = LogManager.getLogger(GuiPromptEditorTab.class);
+
+    private static final String TAB_TITLE = "Prompt";
+    private static final String TAB_TITLE_DIRTY = "Prompt *";
+
+    private GuiPromptEditorPort promptEditorPort;
+    /** Konfigurierter Prompt-Dateipfad – wird für CreatePromptFile-Vorschläge benötigt. */
+    private String configuredPromptPath;
+    /** Konfigurierte maximale Titellänge – für den Default-Prompt-Inhalt. */
+    private int maxTitleLength;
+
+    // Thread-Strategie (injizierbar für Tests ohne JavaFX-Runtime)
+    /** Erzeugt Worker-Threads für blockierende Operationen. */
+    Function<Runnable, Thread> threadFactory;
+    /** Übergibt UI-Updates an den JavaFX Application Thread. */
+    Consumer<Runnable> fxDispatcher;
+
+    private final Tab tab = new Tab(TAB_TITLE);
+    private final TextArea textArea = new TextArea();
+    private final Label statusLabel = new Label();
+    private final Button saveButton = new Button("Speichern");
+    private final Button resetButton = new Button("Auf Standard zurücksetzen");
+    private final Button createDefaultButton = new Button("Standard-Prompt erstellen");
+
+    /** Zeigt an, ob der aktuelle Inhalt der TextArea vom geladenen Stand abweicht. */
+    private boolean dirty = false;
+    /** Zuletzt aus der Datei geladener Inhalt (Baseline). */
+    private String loadedContent = null;
+
+    /**
+     * Erstellt den Prompt-Editor-Tab.
+     *
+     * @param promptEditorPort    Bridge-Port zum Use-Case; darf nicht {@code null} sein
+     * @param configuredPromptPath konfigurierter Pfad zur Prompt-Datei (für CreatePromptFile);
+     *                            darf nicht {@code null} sein
+     * @param maxTitleLength      konfigurierte maximale Titellänge für den Default-Prompt
+     * @throws NullPointerException wenn {@code promptEditorPort} oder {@code configuredPromptPath} null ist
+     */
+    public GuiPromptEditorTab(GuiPromptEditorPort promptEditorPort,
+                               String configuredPromptPath,
+                               int maxTitleLength) {
+        this.promptEditorPort = Objects.requireNonNull(promptEditorPort, "promptEditorPort must not be null");
+        this.configuredPromptPath = Objects.requireNonNull(configuredPromptPath, "configuredPromptPath must not be null");
+        this.maxTitleLength = maxTitleLength;
+        // Standard-Implementierungen für den Produktionsbetrieb
+        this.threadFactory = runnable -> {
+            Thread t = new Thread(runnable, "gui-prompt-editor");
+            t.setDaemon(true);
+            return t;
+        };
+        this.fxDispatcher = Platform::runLater;
+        buildTab();
+    }
+
+    /**
+     * Liefert das JavaFX-Tab-Objekt, das dem TabPane hinzugefügt werden kann.
+     *
+     * @return das Tab; nie {@code null}
+     */
+    public Tab tab() {
+        return tab;
+    }
+
+    /**
+     * Gibt an, ob der Prompt-Editor ungespeicherte Änderungen enthält.
+     *
+     * @return {@code true}, wenn Dirty-State aktiv ist
+     */
+    public boolean hasDirtyContent() {
+        return dirty;
+    }
+
+    /**
+     * Aktualisiert den Tab auf eine neue Konfiguration.
+     * <p>
+     * Setzt Port, Prompt-Dateipfad und maximale Titellänge auf die neuen Werte.
+     * Der bisherige Lade-Baseline wird verworfen und der Dirty-State zurückgesetzt.
+     * Ist der Tab zum Zeitpunkt des Aufrufs sichtbar, wird ein erneutes Laden sofort
+     * ausgelöst; andernfalls erfolgt das Laden beim nächsten Öffnen des Tabs.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     *
+     * @param newPort           neuer Port für Prompt-Operationen; darf nicht {@code null} sein
+     * @param newPromptPath     neuer konfigurierter Prompt-Dateipfad; darf nicht {@code null} sein
+     * @param newMaxTitleLength neue konfigurierte maximale Titellänge
+     */
+    public void notifyConfigurationChanged(GuiPromptEditorPort newPort,
+                                            String newPromptPath,
+                                            int newMaxTitleLength) {
+        this.promptEditorPort = Objects.requireNonNull(newPort, "newPort must not be null");
+        this.configuredPromptPath = Objects.requireNonNull(newPromptPath, "newPromptPath must not be null");
+        this.maxTitleLength = newMaxTitleLength;
+        this.loadedContent = null;
+        this.dirty = false;
+        this.tab.setText(TAB_TITLE);
+        this.saveButton.setDisable(true);
+        if (tab.isSelected()) {
+            loadPromptAsync();
+        }
+    }
+
+    /**
+     * Verwirft alle ungespeicherten Änderungen und setzt den Tab in den Lade-Bereitschaftszustand.
+     * <p>
+     * Setzt Dirty-State und Tab-Titel zurück. Ist der Tab zum Zeitpunkt des Aufrufs sichtbar,
+     * wird der Prompt-Inhalt sofort neu geladen; andernfalls erfolgt das Laden beim nächsten
+     * Öffnen des Tabs (gesteuert durch den Tab-Selektions-Listener).
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     */
+    public void discardChanges() {
+        this.loadedContent = null;
+        this.dirty = false;
+        this.tab.setText(TAB_TITLE);
+        this.saveButton.setDisable(true);
+        if (tab.isSelected()) {
+            loadPromptAsync();
+        }
+    }
+
+    /**
+     * Zeigt einen Bestätigungsdialog, wenn ungespeicherte Änderungen vorhanden sind.
+     * Gibt {@code true} zurück, wenn die Änderungen verworfen werden dürfen.
+     *
+     * @return {@code true} zum Verwerfen, {@code false} zum Abbrechen
+     */
+    public boolean confirmDiscardIfDirty() {
+        if (!dirty) {
+            return true;
+        }
+        Alert alert = new Alert(Alert.AlertType.CONFIRMATION);
+        alert.setTitle("Ungespeicherte Änderungen");
+        alert.setHeaderText("Der Prompt-Editor enthält ungespeicherte Änderungen.");
+        alert.setContentText("Möchten Sie die Änderungen verwerfen?");
+        alert.getButtonTypes().setAll(
+                new ButtonType("Verwerfen"),
+                ButtonType.CANCEL);
+        Optional<ButtonType> result = alert.showAndWait();
+        return result.isPresent() && result.get().getText().equals("Verwerfen");
+    }
+
+    /**
+     * Lädt den aktuellen Prompt-Inhalt auf einem Worker-Thread und zeigt ihn in der TextArea an.
+     * <p>
+     * Muss vom JavaFX Application Thread aufgerufen werden. Die eigentliche I/O-Operation
+     * läuft auf einem Hintergrund-Thread; UI-Updates erfolgen via {@code fxDispatcher}.
+     */
+    public void loadPromptAsync() {
+        setStatus("Lade Prompt-Datei ...");
+        saveButton.setDisable(true);
+        resetButton.setDisable(true);
+        createDefaultButton.setVisible(false);
+        createDefaultButton.setManaged(false);
+
+        Thread worker = threadFactory.apply(() -> {
+            var result = promptEditorPort.loadCurrentPrompt();
+            fxDispatcher.accept(() -> applyLoadResult(result));
+        });
+        worker.start();
+    }
+
+    // -------------------------------------------------------------------------
+    // Private Aufbau
+    // -------------------------------------------------------------------------
+
+    private void buildTab() {
+        tab.setClosable(false);
+
+        // TextArea – monospace Font für bessere Lesbarkeit
+        textArea.setWrapText(true);
+        textArea.setFont(Font.font("Monospace", 13));
+        textArea.setPrefRowCount(20);
+        textArea.setTooltip(new Tooltip(GuiTooltipTexts.PROMPT_TEXTAREA));
+        VBox.setVgrow(textArea, Priority.ALWAYS);
+
+        // Dirty-State-Tracking
+        textArea.textProperty().addListener((obs, oldVal, newVal) -> {
+            if (loadedContent != null) {
+                boolean nowDirty = !newVal.equals(loadedContent);
+                if (nowDirty != dirty) {
+                    dirty = nowDirty;
+                    tab.setText(dirty ? TAB_TITLE_DIRTY : TAB_TITLE);
+                }
+            }
+        });
+
+        // Status-Label
+        statusLabel.setWrapText(true);
+        statusLabel.setStyle("-fx-text-fill: #555555;");
+
+        // Buttons verdrahten
+        saveButton.setTooltip(new Tooltip(GuiTooltipTexts.PROMPT_SPEICHERN));
+        saveButton.setOnAction(e -> requestSave());
+
+        resetButton.setTooltip(new Tooltip(GuiTooltipTexts.PROMPT_ZURUECKSETZEN));
+        resetButton.setOnAction(e -> resetToDefault());
+
+        createDefaultButton.setTooltip(new Tooltip(GuiTooltipTexts.PROMPT_STANDARD_ANLEGEN));
+        createDefaultButton.setOnAction(e -> requestCreateDefault());
+        createDefaultButton.setVisible(false);
+        createDefaultButton.setManaged(false);
+
+        HBox buttonBar = new HBox(8, saveButton, resetButton, createDefaultButton);
+        buttonBar.setAlignment(Pos.CENTER_LEFT);
+        buttonBar.setPadding(new Insets(6, 0, 0, 0));
+
+        VBox content = new VBox(6, textArea, statusLabel, buttonBar);
+        content.setPadding(new Insets(12));
+        VBox.setVgrow(textArea, Priority.ALWAYS);
+
+        BorderPane root = new BorderPane(content);
+        tab.setContent(root);
+
+        // Beim Öffnen des Tabs laden (falls Konfiguration bereits vorhanden)
+        tab.selectedProperty().addListener((obs, wasSelected, isSelected) -> {
+            if (Boolean.TRUE.equals(isSelected) && loadedContent == null) {
+                loadPromptAsync();
+            }
+        });
+    }
+
+    private void applyLoadResult(de.gecheckt.pdf.umbenenner.application.port.out.PromptLoadingResult result) {
+        if (result instanceof PromptLoadingSuccess success) {
+            loadedContent = success.promptContent();
+            textArea.setText(loadedContent);
+            textArea.setEditable(true);
+            saveButton.setDisable(false);
+            resetButton.setDisable(false);
+            createDefaultButton.setVisible(false);
+            createDefaultButton.setManaged(false);
+            setStatus("Prompt-Datei geladen. Identifikator: " + success.promptIdentifier().identifier());
+            dirty = false;
+            tab.setText(TAB_TITLE);
+            LOG.info("Prompt-Editor: Prompt-Datei erfolgreich geladen (Identifikator: {}).",
+                    success.promptIdentifier().identifier());
+        } else if (result instanceof PromptLoadingFailure failure) {
+            boolean fileNotFound = "FILE_NOT_FOUND".equals(failure.failureReason());
+            if (fileNotFound) {
+                // Datei fehlt – Hinweis und Anlegen-Button anzeigen
+                loadedContent = null;
+                textArea.setEditable(false);
+                textArea.clear();
+                saveButton.setDisable(true);
+                resetButton.setDisable(false);
+                createDefaultButton.setVisible(true);
+                createDefaultButton.setManaged(true);
+                setStatus("Keine Prompt-Datei vorhanden. Legen Sie eine Standard-Datei an oder "
+                        + "konfigurieren Sie den Pfad im Konfigurationstab.");
+                LOG.info("Prompt-Editor: Keine Prompt-Datei am konfigurierten Pfad vorhanden.");
+            } else {
+                // Anderer Fehler (I/O, leer usw.)
+                loadedContent = null;
+                textArea.setEditable(false);
+                textArea.clear();
+                saveButton.setDisable(true);
+                resetButton.setDisable(false);
+                createDefaultButton.setVisible(false);
+                createDefaultButton.setManaged(false);
+                setStatus("Fehler beim Laden der Prompt-Datei: " + failure.failureMessage());
+                LOG.warn("Prompt-Editor: Laden fehlgeschlagen ({}): {}",
+                        failure.failureReason(), failure.failureMessage());
+            }
+        }
+    }
+
+    private void requestSave() {
+        String currentText = textArea.getText();
+
+        // Leerer Prompt: Bestätigungsdialog
+        if (currentText.trim().isEmpty()) {
+            Alert confirm = new Alert(Alert.AlertType.CONFIRMATION);
+            confirm.setTitle("Leerer Prompt");
+            confirm.setHeaderText("Der Prompt ist leer.");
+            confirm.setContentText("Wirklich eine leere Prompt-Datei speichern?");
+            confirm.getButtonTypes().setAll(ButtonType.OK, ButtonType.CANCEL);
+            Optional<ButtonType> choice = confirm.showAndWait();
+            if (choice.isEmpty() || choice.get() != ButtonType.OK) {
+                return;
+            }
+        }
+
+        setStatus("Speichere ...");
+        saveButton.setDisable(true);
+
+        Thread worker = threadFactory.apply(() -> {
+            PromptSaveResult result = promptEditorPort.save(currentText);
+            fxDispatcher.accept(() -> applySaveResult(result, currentText));
+        });
+        worker.start();
+    }
+
+    private void applySaveResult(PromptSaveResult result, String savedContent) {
+        saveButton.setDisable(false);
+        if (result instanceof PromptSaveResult.Saved saved) {
+            loadedContent = savedContent;
+            dirty = false;
+            tab.setText(TAB_TITLE);
+            setStatus("Prompt-Datei gespeichert: " + saved.absolutePath());
+            textArea.setEditable(true);
+            LOG.info("Prompt-Editor: Prompt-Datei gespeichert unter {}.", saved.absolutePath());
+        } else if (result instanceof PromptSaveResult.TargetDirectoryMissing missing) {
+            setStatus("Fehler: " + missing.message());
+            LOG.warn("Prompt-Editor: Speichern fehlgeschlagen – Ordner fehlt: {}", missing.message());
+        } else if (result instanceof PromptSaveResult.WriteFailed failed) {
+            setStatus("Fehler beim Schreiben: " + failed.message());
+            LOG.warn("Prompt-Editor: Speichern fehlgeschlagen – Schreibfehler: {}", failed.message());
+        } else if (result instanceof PromptSaveResult.AtomicMoveFailed atomicFailed) {
+            setStatus("Fehler: Atomares Speichern fehlgeschlagen (kein Fallback). " + atomicFailed.message());
+            LOG.warn("Prompt-Editor: Atomares Verschieben fehlgeschlagen: {}", atomicFailed.message());
+        }
+    }
+
+    void resetToDefault() {
+        String defaultContent = de.gecheckt.pdf.umbenenner.application.validation
+                .technicaltest.DefaultPromptTemplate.defaultContent(maxTitleLength);
+        textArea.setText(defaultContent);
+        textArea.setEditable(true);
+        saveButton.setDisable(false);
+        setStatus("Standard-Prompt-Inhalt in den Editor geladen (noch nicht gespeichert).");
+        LOG.info("Prompt-Editor: Standard-Prompt-Inhalt in TextArea geladen (nicht gespeichert).");
+    }
+
+    private void requestCreateDefault() {
+        createDefaultButton.setDisable(true);
+        setStatus("Lege Standard-Prompt-Datei an ...");
+
+        CorrectionSuggestion.CreatePromptFile suggestion = new CorrectionSuggestion.CreatePromptFile(
+                configuredPromptPath,
+                "Standard-Prompt-Datei anlegen",
+                maxTitleLength);
+
+        Thread worker = threadFactory.apply(() -> {
+            CorrectionOutcome outcome = promptEditorPort.createDefaultPromptIfMissing(suggestion);
+            fxDispatcher.accept(() -> applyCreateDefaultResult(outcome));
+        });
+        worker.start();
+    }
+
+    private void applyCreateDefaultResult(CorrectionOutcome outcome) {
+        createDefaultButton.setDisable(false);
+        if (outcome instanceof CorrectionOutcome.Applied applied) {
+            setStatus(applied.message() + " Lade Inhalt ...");
+            LOG.info("Prompt-Editor: Standard-Prompt-Datei angelegt. Lade neu.");
+            // Inhalt sofort neu laden
+            loadPromptAsync();
+        } else if (outcome instanceof CorrectionOutcome.Failed failed) {
+            setStatus("Fehler beim Anlegen der Standard-Prompt-Datei: " + failed.errorMessage());
+            LOG.warn("Prompt-Editor: Anlegen der Standard-Prompt-Datei fehlgeschlagen: {}", failed.errorMessage());
+        } else if (outcome instanceof CorrectionOutcome.NotAttempted notAttempted) {
+            setStatus("Aktion nicht verfügbar: " + notAttempted.reason());
+            LOG.warn("Prompt-Editor: Anlegen nicht versucht: {}", notAttempted.reason());
+        }
+    }
+
+    private void setStatus(String message) {
+        statusLabel.setText(message);
+    }
+}
@@ -0,0 +1,474 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.format.DateTimeFormatter;
+import java.time.temporal.ChronoUnit;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.function.Supplier;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.SchedulerControlUseCase;
+import de.gecheckt.pdf.umbenenner.application.port.in.SchedulerSessionTotals;
+import de.gecheckt.pdf.umbenenner.application.port.in.SchedulerStartException;
+import de.gecheckt.pdf.umbenenner.application.port.in.SchedulerState;
+import de.gecheckt.pdf.umbenenner.application.port.in.SchedulerStatus;
+import de.gecheckt.pdf.umbenenner.application.port.out.RunSummary;
+import javafx.application.Platform;
+import javafx.geometry.Insets;
+import javafx.geometry.Pos;
+import javafx.scene.control.Alert;
+import javafx.scene.control.Button;
+import javafx.scene.control.Label;
+import javafx.scene.control.Separator;
+import javafx.scene.control.Tab;
+import javafx.scene.control.TextField;
+import javafx.scene.control.Tooltip;
+import javafx.scene.layout.HBox;
+import javafx.scene.layout.VBox;
+
+/**
+ * Fünfter Haupt-Tab des JavaFX-Editorfensters: die Scheduler-Steuerungsansicht.
+ * <p>
+ * Zeigt den aktuellen Zustand des automatischen Schedulers und erlaubt dessen
+ * Steuerung über {@link SchedulerControlUseCase}. Der Tab-Inhalt wird im Sekundentakt
+ * durch {@link #updateStatus(SchedulerStatus)} aktualisiert, das von der zentralen
+ * {@link GuiStatusRefreshTimeline} aufgerufen wird.
+ *
+ * <h2>Bereiche</h2>
+ * <ul>
+ *   <li><strong>Scheduler-Steuerung</strong>: Status-Anzeige (● Aktiv / ○ Gestoppt),
+ *       Start-/Stopp-Schaltflächen, Countdown bis zum nächsten Lauf,
+ *       Letzter-Lauf-Info, Fehlermeldung und Intervall-Konfiguration.</li>
+ * </ul>
+ *
+ * <h2>Threading</h2>
+ * <p>Alle öffentlichen Methoden müssen auf dem JavaFX Application Thread aufgerufen
+ * werden. Start-, Stopp- und Speichern-Aktionen werden auf einem dedizierten
+ * Hintergrund-Worker-Thread ({@code gui-scheduler-control}) ausgeführt.
+ */
+public final class GuiSchedulerTab {
+    private static final String HEADER_LABEL_STYLE = "-fx-font-size: 14px; -fx-font-weight: bold; -fx-text-fill: #7f8c8d;";
+
+
+
+    private static final Logger LOG = LogManager.getLogger(GuiSchedulerTab.class);
+
+    private static final String TAB_TITLE = "Scheduler";
+
+    /** Mindestwert für das konfigurierbare Ausführungsintervall. */
+    static final int MIN_INTERVAL_SECONDS = 30;
+
+    private static final DateTimeFormatter TIME_FORMATTER =
+            DateTimeFormatter.ofPattern("HH:mm").withZone(ZoneId.systemDefault());
+
+    private final Tab tab = new Tab(TAB_TITLE);
+    // Not final: may be updated via onSchedulerAvailable after the tab was created without a use
+    // case (e.g., when auto-load initialises the scheduler after the workspace was already built).
+    // Declared volatile so worker-thread reads (executeStart/Stop) see the write from the FX thread.
+    private volatile Optional<SchedulerControlUseCase> schedulerUseCase;
+    private final Supplier<Boolean> isConfigDirty;
+
+    // -------------------------------------------------------------------------
+    // Bereich 1: Scheduler-Steuerung
+    // -------------------------------------------------------------------------
+
+    private final Label statusLabel = new Label("○ Gestoppt");
+    private final Button startButton = new Button("Scheduler starten");
+    private final Button stopButton = new Button("Scheduler stoppen");
+    private final Label nextTickLabel = new Label();
+    private final Label lastRunLabel = new Label("Noch kein Lauf in dieser Sitzung.");
+    private final Label sessionTotalsLabel = new Label();
+    private final Label lastErrorLabel = new Label();
+    private final TextField intervalField = new TextField();
+    private final Label intervalValidationLabel = new Label();
+
+    private final ExecutorService workerExecutor = Executors.newSingleThreadExecutor(r -> {
+        Thread t = new Thread(r, "gui-scheduler-control");
+        t.setDaemon(true);
+        return t;
+    });
+
+    /**
+     * Erstellt einen neuen Scheduler-Tab.
+     *
+     * @param schedulerUseCase optionaler Use Case zur Scheduler-Steuerung;
+     *                          {@code null} wird als leer behandelt
+     * @param isConfigDirty    Supplier der {@code true} zurückgibt wenn der
+     *                          Konfigurationseditor ungespeicherte Änderungen hat;
+     *                          {@code null} wird als immer {@code false} behandelt
+     */
+    public GuiSchedulerTab(
+            Optional<SchedulerControlUseCase> schedulerUseCase,
+            Supplier<Boolean> isConfigDirty) {
+        this.schedulerUseCase = Objects.requireNonNullElse(schedulerUseCase, Optional.empty());
+        this.isConfigDirty = isConfigDirty != null ? isConfigDirty : () -> false;
+        tab.setClosable(false);
+        buildUi();
+        applyInitialState();
+    }
+
+    /**
+     * Liefert den JavaFX-Tab-Knoten für den Einhang in das {@code TabPane}.
+     *
+     * @return Tab-Knoten; nie {@code null}
+     */
+    public Tab tab() {
+        return tab;
+    }
+
+    /**
+     * Macht den Scheduler-Use-Case für diesen Tab verfügbar, nachdem er nach einem
+     * erfolgreichen Datei-Öffnen initialisiert wurde.
+     * <p>
+     * Wird vom Workspace auf dem JavaFX Application Thread aufgerufen, nachdem der
+     * {@link GuiApplicationContextInitializer} auf einem Hintergrund-Thread einen
+     * {@link SchedulerControlUseCase} geliefert hat. Hat keine Wirkung, wenn bereits
+     * ein Use Case vorhanden ist.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     *
+     * @param useCase der neu initialisierte Use Case; darf nicht {@code null} sein
+     */
+    public void onSchedulerAvailable(SchedulerControlUseCase useCase) {
+        if (schedulerUseCase.isPresent()) {
+            return;
+        }
+        schedulerUseCase = Optional.of(useCase);
+        intervalField.setText(String.valueOf(useCase.getIntervalSeconds()));
+        intervalField.setEditable(true);
+        intervalField.setDisable(false);
+        startButton.setDisable(false);
+        startButton.setTooltip(null);
+    }
+
+    /**
+     * Gibt den aktuell verdrahteten Scheduler-Use-Case zurück.
+     * <p>
+     * Wird von der zentralen Status-Refresh-Timeline benötigt, weil der Use Case
+     * erst nach erfolgreichem Datei-Öffnen verfügbar wird (z. B. durch Auto-Load
+     * der zuletzt geladenen Konfiguration) und damit nicht im
+     * unveränderlichen {@code GuiStartupContext} steht.
+     *
+     * @return aktueller Use Case oder {@code Optional.empty()} wenn keiner verdrahtet ist
+     */
+    public Optional<SchedulerControlUseCase> currentSchedulerUseCase() {
+        return schedulerUseCase;
+    }
+
+    /**
+     * Aktualisiert alle Tab-Elemente anhand des aktuellen Scheduler-Status.
+     * <p>
+     * Wird von der {@link GuiStatusRefreshTimeline} im Sekundentakt auf dem
+     * JavaFX Application Thread aufgerufen. Implementiert alle in der Spezifikation
+     * definierten Button-Zustände, Label-Texte und Sichtbarkeitsregeln.
+     *
+     * @param status aktueller Scheduler-Status; darf nicht {@code null} sein
+     */
+    public void updateStatus(SchedulerStatus status) {
+        updateStatusLabel(status);
+        updateButtons(status);
+        updateNextTickLabel(status);
+        updateLastRunLabel(status);
+        updateSessionTotalsLabel(status);
+        updateLastErrorLabel(status);
+        updateIntervalFieldEditability(status);
+    }
+
+    // -------------------------------------------------------------------------
+    // UI-Aufbau
+    // -------------------------------------------------------------------------
+
+    private void buildUi() {
+        VBox controlArea = buildControlArea();
+        tab.setContent(controlArea);
+        wireActions();
+    }
+
+    private VBox buildControlArea() {
+        statusLabel.setStyle(HEADER_LABEL_STYLE);
+
+        stopButton.setDisable(true);
+        HBox buttonBox = new HBox(10, startButton, stopButton);
+
+        nextTickLabel.setVisible(false);
+        nextTickLabel.setManaged(false);
+
+        lastRunLabel.setWrapText(true);
+
+        sessionTotalsLabel.setWrapText(true);
+        sessionTotalsLabel.setStyle("-fx-text-fill: #7f8c8d;");
+        sessionTotalsLabel.setVisible(false);
+        sessionTotalsLabel.setManaged(false);
+
+        lastErrorLabel.setStyle("-fx-text-fill: #c0392b;");
+        lastErrorLabel.setWrapText(true);
+        lastErrorLabel.setVisible(false);
+        lastErrorLabel.setManaged(false);
+
+        Label intervalLabel = new Label("Intervall (Sekunden):");
+        intervalField.setPrefColumnCount(10);
+        HBox intervalBox = new HBox(10, intervalLabel, intervalField);
+        intervalBox.setAlignment(Pos.CENTER_LEFT);
+
+        intervalValidationLabel.setStyle("-fx-text-fill: #c0392b; -fx-font-size: 11px;");
+        intervalValidationLabel.setWrapText(true);
+        intervalValidationLabel.setVisible(false);
+        intervalValidationLabel.setManaged(false);
+
+        VBox controlArea = new VBox(12,
+                statusLabel,
+                buttonBox,
+                nextTickLabel,
+                lastRunLabel,
+                sessionTotalsLabel,
+                lastErrorLabel,
+                new Separator(),
+                intervalBox,
+                intervalValidationLabel);
+        controlArea.setPadding(new Insets(16));
+        return controlArea;
+    }
+
+    private void wireActions() {
+        startButton.setOnAction(e -> executeStart());
+        stopButton.setOnAction(e -> executeStop());
+
+        intervalField.focusedProperty().addListener((obs, wasFocused, focused) -> {
+            if (!focused) {
+                validateAndSaveInterval();
+            }
+        });
+    }
+
+    private void applyInitialState() {
+        if (schedulerUseCase.isEmpty()) {
+            startButton.setDisable(true);
+            startButton.setTooltip(new Tooltip("Anwendung nicht laufbereit"));
+            stopButton.setDisable(true);
+            intervalField.setEditable(false);
+            intervalField.setDisable(true);
+        } else {
+            intervalField.setText(String.valueOf(schedulerUseCase.get().getIntervalSeconds()));
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // updateStatus-Hilfsmethoden
+    // -------------------------------------------------------------------------
+
+    private void updateStatusLabel(SchedulerStatus status) {
+        switch (status.state()) {
+            case STOPPED -> {
+                statusLabel.setText("○ Gestoppt");
+                statusLabel.setStyle(HEADER_LABEL_STYLE);
+            }
+            case STARTING -> {
+                statusLabel.setText("⟳ Wird gestartet…");
+                statusLabel.setStyle("-fx-font-size: 14px; -fx-font-weight: bold; -fx-text-fill: #e67e22;");
+            }
+            case RUNNING_IDLE -> {
+                statusLabel.setText("● Aktiv");
+                statusLabel.setStyle("-fx-font-size: 14px; -fx-font-weight: bold; -fx-text-fill: #27ae60;");
+            }
+            case RUNNING_BATCH_ACTIVE -> {
+                statusLabel.setText("● Aktiv – Lauf aktiv");
+                statusLabel.setStyle("-fx-font-size: 14px; -fx-font-weight: bold; -fx-text-fill: #27ae60;");
+            }
+            case STOPPING_BATCH_ACTIVE -> {
+                statusLabel.setText("○ Gestoppt – aktueller Lauf läuft noch");
+                statusLabel.setStyle(HEADER_LABEL_STYLE);
+            }
+        }
+    }
+
+    private void updateButtons(SchedulerStatus status) {
+        boolean noUseCase = schedulerUseCase.isEmpty();
+        boolean configDirty = Boolean.TRUE.equals(isConfigDirty.get());
+
+        switch (status.state()) {
+            case STOPPED -> {
+                stopButton.setDisable(true);
+                if (noUseCase) {
+                    startButton.setDisable(true);
+                    startButton.setTooltip(new Tooltip("Anwendung nicht laufbereit"));
+                } else if (configDirty) {
+                    startButton.setDisable(true);
+                    startButton.setTooltip(new Tooltip("Bitte Konfiguration speichern"));
+                } else {
+                    startButton.setDisable(false);
+                    startButton.setTooltip(null);
+                }
+            }
+            case STARTING -> {
+                startButton.setDisable(true);
+                stopButton.setDisable(true);
+            }
+            case RUNNING_IDLE, RUNNING_BATCH_ACTIVE -> {
+                startButton.setDisable(true);
+                startButton.setTooltip(null);
+                stopButton.setDisable(false);
+            }
+            case STOPPING_BATCH_ACTIVE -> {
+                startButton.setDisable(true);
+                stopButton.setDisable(true);
+            }
+        }
+    }
+
+    private void updateNextTickLabel(SchedulerStatus status) {
+        if (status.state() == SchedulerState.RUNNING_IDLE && status.nextTickAt().isPresent()) {
+            long remaining = ChronoUnit.SECONDS.between(Instant.now(), status.nextTickAt().get());
+            if (remaining > 0) {
+                long minutes = remaining / 60;
+                long seconds = remaining % 60;
+                nextTickLabel.setText(String.format("Nächster Lauf in: %02d:%02d", minutes, seconds));
+            } else {
+                nextTickLabel.setText("Lauf steht bevor…");
+            }
+            nextTickLabel.setVisible(true);
+            nextTickLabel.setManaged(true);
+        } else {
+            nextTickLabel.setVisible(false);
+            nextTickLabel.setManaged(false);
+        }
+    }
+
+    private void updateLastRunLabel(SchedulerStatus status) {
+        if (status.lastRunEndedAt().isPresent() && status.lastRunSummary().isPresent()) {
+            Instant endedAt = status.lastRunEndedAt().get();
+            RunSummary summary = status.lastRunSummary().get();
+            String timeStr = TIME_FORMATTER.format(endedAt);
+            boolean noDocuments = summary.successCount() == 0
+                    && summary.failedCount() == 0;
+            if (noDocuments) {
+                lastRunLabel.setText("Letzter Lauf: " + timeStr + " – keine neuen Dokumente");
+            } else {
+                lastRunLabel.setText("Letzter Lauf: " + timeStr + " – "
+                        + summary.successCount() + " verarbeitet, "
+                        + summary.failedCount() + " Fehler");
+            }
+        } else {
+            lastRunLabel.setText("Noch kein Lauf in dieser Sitzung.");
+        }
+    }
+
+    private void updateSessionTotalsLabel(SchedulerStatus status) {
+        Optional<SchedulerSessionTotals> totals = status.sessionTotals();
+        if (totals.isPresent()) {
+            SchedulerSessionTotals t = totals.get();
+            sessionTotalsLabel.setText("Seit Scheduler-Start: "
+                    + t.successCount() + " verarbeitet, "
+                    + t.failedCount() + " Fehler");
+            sessionTotalsLabel.setVisible(true);
+            sessionTotalsLabel.setManaged(true);
+        } else {
+            sessionTotalsLabel.setVisible(false);
+            sessionTotalsLabel.setManaged(false);
+        }
+    }
+
+    private void updateLastErrorLabel(SchedulerStatus status) {
+        Optional<String> lastError = status.lastError();
+        if (lastError.isPresent() && !lastError.get().isBlank()) {
+            lastErrorLabel.setText("Fehler: " + lastError.get());
+            lastErrorLabel.setVisible(true);
+            lastErrorLabel.setManaged(true);
+        } else {
+            lastErrorLabel.setVisible(false);
+            lastErrorLabel.setManaged(false);
+        }
+    }
+
+    private void updateIntervalFieldEditability(SchedulerStatus status) {
+        boolean editable = status.state() == SchedulerState.STOPPED
+                && schedulerUseCase.isPresent()
+                && !Boolean.TRUE.equals(isConfigDirty.get());
+        intervalField.setEditable(editable);
+        intervalField.setDisable(!editable);
+    }
+
+    // -------------------------------------------------------------------------
+    // Aktions-Handler
+    // -------------------------------------------------------------------------
+
+    private void executeStart() {
+        LOG.info("GUI: Scheduler-Start angefordert.");
+        startButton.setDisable(true);
+        stopButton.setDisable(true);
+        workerExecutor.submit(() -> schedulerUseCase.ifPresent(uc -> {
+            try {
+                uc.start();
+                LOG.info("GUI: Scheduler erfolgreich gestartet.");
+            } catch (SchedulerStartException e) {
+                LOG.warn("GUI: Scheduler-Start fehlgeschlagen: {}", e.getMessage());
+                Platform.runLater(() -> showStartErrorAlert(e.getMessage()));
+            } catch (RuntimeException e) {
+                LOG.error("GUI: Unerwarteter Fehler beim Starten des Schedulers.", e);
+                Platform.runLater(() -> showStartErrorAlert("Unerwarteter Fehler: " + e.getMessage()));
+            }
+        }));
+    }
+
+    private void executeStop() {
+        LOG.info("GUI: Scheduler-Stopp angefordert.");
+        startButton.setDisable(true);
+        stopButton.setDisable(true);
+        workerExecutor.submit(() -> schedulerUseCase.ifPresent(uc -> {
+            try {
+                uc.stop();
+                LOG.info("GUI: Scheduler gestoppt.");
+            } catch (RuntimeException e) {
+                LOG.error("GUI: Unerwarteter Fehler beim Stoppen des Schedulers.", e);
+            }
+        }));
+    }
+
+    private void validateAndSaveInterval() {
+        String text = intervalField.getText() == null ? "" : intervalField.getText().trim();
+        try {
+            int value = Integer.parseInt(text);
+            if (value < MIN_INTERVAL_SECONDS) {
+                showIntervalValidationError(
+                        "Mindestintervall ist " + MIN_INTERVAL_SECONDS + " Sekunden.");
+            } else {
+                hideIntervalValidationError();
+                workerExecutor.submit(() -> schedulerUseCase.ifPresent(uc -> {
+                    try {
+                        uc.saveIntervalSeconds(value);
+                    } catch (RuntimeException e) {
+                        LOG.warn("GUI: Fehler beim Speichern des Scheduler-Intervalls: {}", e.getMessage());
+                        Platform.runLater(() -> showIntervalValidationError(
+                                "Speichern fehlgeschlagen: " + e.getMessage()));
+                    }
+                }));
+            }
+        } catch (NumberFormatException e) {
+            showIntervalValidationError("Bitte eine ganze Zahl eingeben.");
+        }
+    }
+
+    private void showIntervalValidationError(String message) {
+        intervalValidationLabel.setText(message);
+        intervalValidationLabel.setVisible(true);
+        intervalValidationLabel.setManaged(true);
+    }
+
+    private void hideIntervalValidationError() {
+        intervalValidationLabel.setVisible(false);
+        intervalValidationLabel.setManaged(false);
+    }
+
+    private static void showStartErrorAlert(String message) {
+        Alert alert = new Alert(Alert.AlertType.ERROR);
+        alert.setTitle("Scheduler-Start fehlgeschlagen");
+        alert.setHeaderText("Der Scheduler konnte nicht gestartet werden.");
+        alert.setContentText(message != null ? message : "Unbekannter Fehler.");
+        alert.showAndWait();
+    }
+}
@@ -0,0 +1,655 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
+
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.GuiBatchRunLaunchOutcome;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.GuiBatchRunLauncher;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.GuiHistoricalDocumentContextPort;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.GuiManualFileCopyPort;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.GuiManualFileRenamePort;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.GuiMiniRunLauncher;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.GuiResetDocumentStatusPort;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.history.GuiDeleteDocumentHistoryPort;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.history.GuiHistoryDetailsPort;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.history.GuiHistoryOverviewPort;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.history.GuiHistoryResetDocumentStatusPort;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiConfigurationEditorState;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiConfigurationEditorStateFactory;
+import de.gecheckt.pdf.umbenenner.application.port.in.ResetDocumentStatusResult;
+import de.gecheckt.pdf.umbenenner.application.port.in.SchedulerControlUseCase;
+import de.gecheckt.pdf.umbenenner.application.port.out.ConfigurationFileLockPort;
+import de.gecheckt.pdf.umbenenner.application.port.out.modelcatalog.AiModelCatalogPort;
+import de.gecheckt.pdf.umbenenner.application.port.out.modelcatalog.EffectiveApiKeyDescriptor;
+import de.gecheckt.pdf.umbenenner.application.validation.editor.ApiKeyResolutionPort;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionExecutionService;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.PathCheckPort;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.ProviderTechnicalTestService;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.ResourceCreationPort;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.TechnicalTestOrchestrator;
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+
+/**
+ * Immutable startup data for the GUI adapter.
+ * <p>
+ * Carries the initial editor state, the optional startup notice, the file-loading callback,
+ * the file-writing callback that the workspace uses for native save actions, the
+ * {@link AiModelCatalogPort} used to retrieve available AI model lists on demand, the
+ * {@link ApiKeyResolutionPort} used by the editor validation to determine the effective
+ * API key provenance from environment variables, the {@link ProviderTechnicalTestService}
+ * used to execute provider-specific technical checks, the {@link PathCheckPort}
+ * used to verify filesystem path accessibility for configuration values, the
+ * {@link TechnicalTestOrchestrator} used by the "Technische Tests ausführen" action, the
+ * {@link CorrectionExecutionService} used to execute corrective actions after a
+ * technical test run has been confirmed by the user, the {@link GuiBatchRunLauncher} used
+ * to execute regular batch runs, the {@link GuiMiniRunLauncher} used to execute targeted
+ * mini-runs for selected documents, the {@link GuiResetDocumentStatusPort} used to
+ * reset the persistence status of selected documents, and the
+ * {@link GuiManualFileRenamePort} used to manually rename a target file from the GUI,
+ * the {@link GuiManualFileCopyPort} used to manually copy a source file to the target
+ * folder for documents that have not yet been successfully processed, and
+ * the {@link GuiHistoricalDocumentContextPort} used to retrieve the historical processing
+ * context for documents that were skipped in the current run, the resolved application
+ * version string that the status bar displays at the bottom of the main window, and the
+ * optional {@link SchedulerControlUseCase} for controlling the automatic scheduler.
+ * <p>
+ * The optional {@code applicationContextError} carries a human-readable German error
+ * message when the bootstrap-side application run context could not be initialised at
+ * startup (e.g., invalid or incomplete configuration). An empty value signals that the
+ * run context was built successfully and batch runs can be launched immediately.
+ * <p>
+ * The optional {@code schedulerControlUseCase} is present when the automatic scheduler
+ * was successfully wired at startup. An empty value means scheduler control is not
+ * available in this startup context (e.g., no valid configuration was loaded at startup).
+ * <p>
+ * The optional {@code configurationFileLockPort} is present when the GUI can acquire an
+ * OS-level exclusive lock on the configuration file before a manual batch run. When present,
+ * it is acquired by the {@link de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.GuiBatchRunCoordinator}
+ * on the worker thread before each run and released in a finally block. An empty value means
+ * no locking is performed (e.g., no valid configuration was loaded at startup, or locking is
+ * not required in this context).
+ * <p>
+ * The {@code applicationContextInitializer} is invoked on a background thread each time the
+ * workspace loads a configuration file (auto-load at startup and manual open). Bootstrap
+ * provides an implementation that builds the application run context and wires the scheduler.
+ * <p>
+ * All ports and services are supplied by Bootstrap so that the GUI adapter does not need to
+ * know about provider-specific HTTP details or adapter wiring.
+ */
+public record GuiStartupContext(
+        GuiConfigurationEditorState initialState,
+        Optional<String> startupNotice,
+        GuiConfigurationFileLoader configurationFileLoader,
+        GuiConfigurationFileWriter configurationFileWriter,
+        AiModelCatalogPort modelCatalogPort,
+        ApiKeyResolutionPort apiKeyResolutionPort,
+        ProviderTechnicalTestService providerTechnicalTestService,
+        PathCheckPort pathCheckPort,
+        TechnicalTestOrchestrator technicalTestOrchestrator,
+        CorrectionExecutionService correctionExecutionService,
+        GuiBatchRunLauncher batchRunLauncher,
+        GuiMiniRunLauncher miniRunLauncher,
+        GuiResetDocumentStatusPort resetDocumentStatusPort,
+        GuiManualFileRenamePort manualFileRenamePort,
+        GuiManualFileCopyPort manualFileCopyPort,
+        GuiHistoricalDocumentContextPort historicalDocumentContextPort,
+        String applicationVersion,
+        GuiPromptEditorPort promptEditorPort,
+        GuiHistoryOverviewPort historyOverviewPort,
+        GuiHistoryDetailsPort historyDetailsPort,
+        GuiHistoryResetDocumentStatusPort historyResetDocumentStatusPort,
+        GuiDeleteDocumentHistoryPort deleteDocumentHistoryPort,
+        GuiPromptEditorPortFactory promptEditorPortFactory,
+        GuiCreateNewDatabasePort createNewDatabasePort,
+        Optional<String> applicationContextError,
+        Optional<SchedulerControlUseCase> schedulerControlUseCase,
+        Optional<ConfigurationFileLockPort> configurationFileLockPort,
+        GuiApplicationContextInitializer applicationContextInitializer) {
+    private static final String NO_PROMPT_PORT_MSG = "Kein Prompt-Editor-Port in diesem Startkontext verfügbar.";
+    private static final String NO_PORT_MSG = "Kein Port in diesem Startkontext.";
+
+
+    /**
+     * Creates a fully wired startup context.
+     *
+     * @param initialState                initial editor state; must not be {@code null}
+     * @param startupNotice               optional startup notice; {@code null} becomes empty
+     * @param configurationFileLoader     file-loading callback; must not be {@code null}
+     * @param configurationFileWriter     file-writing callback; must not be {@code null}
+     * @param modelCatalogPort            port for retrieving AI model lists; must not be {@code null}
+     * @param apiKeyResolutionPort        port for resolving API key provenance; must not be {@code null}
+     * @param providerTechnicalTestService service for provider-specific technical checks; must not be {@code null}
+     * @param pathCheckPort               port for filesystem path accessibility checks; must not be {@code null}
+     * @param technicalTestOrchestrator   orchestrator for the full technical test run; must not be {@code null}
+     * @param correctionExecutionService  service for executing confirmed corrective actions; must not be {@code null}
+     * @param batchRunLauncher            bridge that executes a regular batch run; must not be {@code null}
+     * @param miniRunLauncher             bridge that executes a targeted mini-run for selected
+     *                                    documents; must not be {@code null}
+     * @param resetDocumentStatusPort     bridge that resets the persistence status of selected
+     *                                    documents; must not be {@code null}
+     * @param manualFileRenamePort        bridge that renames a target file manually from the GUI;
+     *                                    must not be {@code null}
+     * @param manualFileCopyPort          bridge that copies a source file to the target folder for
+     *                                    documents that have not yet been successfully processed;
+     *                                    must not be {@code null}
+     * @param historicalDocumentContextPort bridge that resolves the historical processing context
+     *                                      for skipped documents; must not be {@code null}
+     * @param applicationVersion            resolved application version string shown in the status
+     *                                      bar; {@code null} defaults to {@code "dev"}
+     * @param promptEditorPort              bridge zum Prompt-Editor-Use-Case; darf nicht
+     *                                      {@code null} sein
+     * @param promptEditorPortFactory       Fabrik für Prompt-Editor-Ports bei Konfigurationswechsel;
+     *                                      darf nicht {@code null} sein
+     * @param applicationContextError       optional error message when the application run context
+     *                                      could not be initialised at startup; {@code null} becomes empty
+     */
+    public GuiStartupContext {
+        initialState = Objects.requireNonNull(initialState, "initialState must not be null");
+        startupNotice = Objects.requireNonNullElse(startupNotice, Optional.empty());
+        applicationContextError = Objects.requireNonNullElse(applicationContextError, Optional.empty());
+        configurationFileLoader = Objects.requireNonNull(configurationFileLoader,
+                "configurationFileLoader must not be null");
+        configurationFileWriter = Objects.requireNonNull(configurationFileWriter,
+                "configurationFileWriter must not be null");
+        modelCatalogPort = Objects.requireNonNull(modelCatalogPort,
+                "modelCatalogPort must not be null");
+        apiKeyResolutionPort = Objects.requireNonNull(apiKeyResolutionPort,
+                "apiKeyResolutionPort must not be null");
+        providerTechnicalTestService = Objects.requireNonNull(providerTechnicalTestService,
+                "providerTechnicalTestService must not be null");
+        pathCheckPort = Objects.requireNonNull(pathCheckPort,
+                "pathCheckPort must not be null");
+        technicalTestOrchestrator = Objects.requireNonNull(technicalTestOrchestrator,
+                "technicalTestOrchestrator must not be null");
+        correctionExecutionService = Objects.requireNonNull(correctionExecutionService,
+                "correctionExecutionService must not be null");
+        batchRunLauncher = Objects.requireNonNull(batchRunLauncher,
+                "batchRunLauncher must not be null");
+        miniRunLauncher = Objects.requireNonNull(miniRunLauncher,
+                "miniRunLauncher must not be null");
+        resetDocumentStatusPort = Objects.requireNonNull(resetDocumentStatusPort,
+                "resetDocumentStatusPort must not be null");
+        manualFileRenamePort = Objects.requireNonNull(manualFileRenamePort,
+                "manualFileRenamePort must not be null");
+        manualFileCopyPort = Objects.requireNonNull(manualFileCopyPort,
+                "manualFileCopyPort must not be null");
+        historicalDocumentContextPort = Objects.requireNonNull(historicalDocumentContextPort,
+                "historicalDocumentContextPort must not be null");
+        // Null-Fallback für Testumgebungen ohne gepacktes JAR
+        applicationVersion = applicationVersion == null ? "dev" : applicationVersion;
+        promptEditorPort = Objects.requireNonNull(promptEditorPort, "promptEditorPort must not be null");
+        historyOverviewPort = Objects.requireNonNull(historyOverviewPort,
+                "historyOverviewPort must not be null");
+        historyDetailsPort = Objects.requireNonNull(historyDetailsPort,
+                "historyDetailsPort must not be null");
+        historyResetDocumentStatusPort = Objects.requireNonNull(historyResetDocumentStatusPort,
+                "historyResetDocumentStatusPort must not be null");
+        deleteDocumentHistoryPort = Objects.requireNonNull(deleteDocumentHistoryPort,
+                "deleteDocumentHistoryPort must not be null");
+        promptEditorPortFactory = Objects.requireNonNull(promptEditorPortFactory,
+                "promptEditorPortFactory must not be null");
+        createNewDatabasePort = Objects.requireNonNull(createNewDatabasePort,
+                "createNewDatabasePort must not be null");
+        schedulerControlUseCase = Objects.requireNonNullElse(schedulerControlUseCase, Optional.empty());
+        configurationFileLockPort = Objects.requireNonNullElse(configurationFileLockPort, Optional.empty());
+        applicationContextInitializer = applicationContextInitializer == null
+                ? GuiApplicationContextInitializer.noOp() : applicationContextInitializer;
+    }
+
+    /**
+     * Backward-compatible constructor that fills {@code schedulerControlUseCase} with
+     * {@link Optional#empty()}.
+     * <p>
+     * Preserves existing callers that were written before the scheduler was added.
+     *
+     * @param initialState                  initial editor state; must not be {@code null}
+     * @param startupNotice                 optional startup notice; {@code null} becomes empty
+     * @param configurationFileLoader       file-loading callback; must not be {@code null}
+     * @param configurationFileWriter       file-writing callback; must not be {@code null}
+     * @param modelCatalogPort              port for retrieving AI model lists; must not be {@code null}
+     * @param apiKeyResolutionPort          port for resolving API key provenance; must not be {@code null}
+     * @param providerTechnicalTestService  service for provider-specific technical checks; must not be {@code null}
+     * @param pathCheckPort                 port for filesystem path accessibility checks; must not be {@code null}
+     * @param technicalTestOrchestrator     orchestrator for the full technical test run; must not be {@code null}
+     * @param correctionExecutionService    service for executing confirmed corrective actions; must not be {@code null}
+     * @param batchRunLauncher              bridge that executes a regular batch run; must not be {@code null}
+     * @param miniRunLauncher               bridge that executes a targeted mini-run; must not be {@code null}
+     * @param resetDocumentStatusPort       bridge that resets document status; must not be {@code null}
+     * @param manualFileRenamePort          bridge that renames a target file; must not be {@code null}
+     * @param manualFileCopyPort            bridge that copies a source file; must not be {@code null}
+     * @param historicalDocumentContextPort bridge for historical processing context; must not be {@code null}
+     * @param applicationVersion            resolved application version string; {@code null} defaults to {@code "dev"}
+     * @param promptEditorPort              bridge zum Prompt-Editor-Use-Case; must not be {@code null}
+     * @param historyOverviewPort           bridge for history overview; must not be {@code null}
+     * @param historyDetailsPort            bridge for history details; must not be {@code null}
+     * @param historyResetDocumentStatusPort bridge for history reset; must not be {@code null}
+     * @param deleteDocumentHistoryPort     bridge for history deletion; must not be {@code null}
+     * @param promptEditorPortFactory       factory for prompt editor ports; must not be {@code null}
+     * @param createNewDatabasePort         bridge for new database creation; must not be {@code null}
+     * @param applicationContextError       optional error from context init; {@code null} becomes empty
+     */
+    public GuiStartupContext(
+            GuiConfigurationEditorState initialState,
+            Optional<String> startupNotice,
+            GuiConfigurationFileLoader configurationFileLoader,
+            GuiConfigurationFileWriter configurationFileWriter,
+            AiModelCatalogPort modelCatalogPort,
+            ApiKeyResolutionPort apiKeyResolutionPort,
+            ProviderTechnicalTestService providerTechnicalTestService,
+            PathCheckPort pathCheckPort,
+            TechnicalTestOrchestrator technicalTestOrchestrator,
+            CorrectionExecutionService correctionExecutionService,
+            GuiBatchRunLauncher batchRunLauncher,
+            GuiMiniRunLauncher miniRunLauncher,
+            GuiResetDocumentStatusPort resetDocumentStatusPort,
+            GuiManualFileRenamePort manualFileRenamePort,
+            GuiManualFileCopyPort manualFileCopyPort,
+            GuiHistoricalDocumentContextPort historicalDocumentContextPort,
+            String applicationVersion,
+            GuiPromptEditorPort promptEditorPort,
+            GuiHistoryOverviewPort historyOverviewPort,
+            GuiHistoryDetailsPort historyDetailsPort,
+            GuiHistoryResetDocumentStatusPort historyResetDocumentStatusPort,
+            GuiDeleteDocumentHistoryPort deleteDocumentHistoryPort,
+            GuiPromptEditorPortFactory promptEditorPortFactory,
+            GuiCreateNewDatabasePort createNewDatabasePort,
+            Optional<String> applicationContextError) {
+        this(initialState, startupNotice, configurationFileLoader, configurationFileWriter,
+                modelCatalogPort, apiKeyResolutionPort, providerTechnicalTestService, pathCheckPort,
+                technicalTestOrchestrator, correctionExecutionService, batchRunLauncher,
+                miniRunLauncher, resetDocumentStatusPort, manualFileRenamePort, manualFileCopyPort,
+                historicalDocumentContextPort, applicationVersion, promptEditorPort,
+                historyOverviewPort, historyDetailsPort, historyResetDocumentStatusPort,
+                deleteDocumentHistoryPort, promptEditorPortFactory, createNewDatabasePort,
+                applicationContextError, Optional.empty(), Optional.empty(),
+                GuiApplicationContextInitializer.noOp());
+    }
+
+    /**
+     * Backward-compatible constructor that fills {@code configurationFileLockPort} with
+     * {@link Optional#empty()}.
+     * <p>
+     * Preserves existing callers that were written before the configuration file lock port
+     * was added.
+     *
+     * @param initialState                  initial editor state; must not be {@code null}
+     * @param startupNotice                 optional startup notice; {@code null} becomes empty
+     * @param configurationFileLoader       file-loading callback; must not be {@code null}
+     * @param configurationFileWriter       file-writing callback; must not be {@code null}
+     * @param modelCatalogPort              port for retrieving AI model lists; must not be {@code null}
+     * @param apiKeyResolutionPort          port for resolving API key provenance; must not be {@code null}
+     * @param providerTechnicalTestService  service for provider-specific technical checks; must not be {@code null}
+     * @param pathCheckPort                 port for filesystem path accessibility checks; must not be {@code null}
+     * @param technicalTestOrchestrator     orchestrator for the full technical test run; must not be {@code null}
+     * @param correctionExecutionService    service for executing confirmed corrective actions; must not be {@code null}
+     * @param batchRunLauncher              bridge that executes a regular batch run; must not be {@code null}
+     * @param miniRunLauncher               bridge that executes a targeted mini-run; must not be {@code null}
+     * @param resetDocumentStatusPort       bridge that resets document status; must not be {@code null}
+     * @param manualFileRenamePort          bridge that renames a target file; must not be {@code null}
+     * @param manualFileCopyPort            bridge that copies a source file; must not be {@code null}
+     * @param historicalDocumentContextPort bridge for historical processing context; must not be {@code null}
+     * @param applicationVersion            resolved application version string; {@code null} defaults to {@code "dev"}
+     * @param promptEditorPort              bridge zum Prompt-Editor-Use-Case; must not be {@code null}
+     * @param historyOverviewPort           bridge for history overview; must not be {@code null}
+     * @param historyDetailsPort            bridge for history details; must not be {@code null}
+     * @param historyResetDocumentStatusPort bridge for history reset; must not be {@code null}
+     * @param deleteDocumentHistoryPort     bridge for history deletion; must not be {@code null}
+     * @param promptEditorPortFactory       factory for prompt editor ports; must not be {@code null}
+     * @param createNewDatabasePort         bridge for new database creation; must not be {@code null}
+     * @param applicationContextError       optional error from context init; {@code null} becomes empty
+     * @param schedulerControlUseCase       optional scheduler control use case; {@code null} becomes empty
+     */
+    public GuiStartupContext(
+            GuiConfigurationEditorState initialState,
+            Optional<String> startupNotice,
+            GuiConfigurationFileLoader configurationFileLoader,
+            GuiConfigurationFileWriter configurationFileWriter,
+            AiModelCatalogPort modelCatalogPort,
+            ApiKeyResolutionPort apiKeyResolutionPort,
+            ProviderTechnicalTestService providerTechnicalTestService,
+            PathCheckPort pathCheckPort,
+            TechnicalTestOrchestrator technicalTestOrchestrator,
+            CorrectionExecutionService correctionExecutionService,
+            GuiBatchRunLauncher batchRunLauncher,
+            GuiMiniRunLauncher miniRunLauncher,
+            GuiResetDocumentStatusPort resetDocumentStatusPort,
+            GuiManualFileRenamePort manualFileRenamePort,
+            GuiManualFileCopyPort manualFileCopyPort,
+            GuiHistoricalDocumentContextPort historicalDocumentContextPort,
+            String applicationVersion,
+            GuiPromptEditorPort promptEditorPort,
+            GuiHistoryOverviewPort historyOverviewPort,
+            GuiHistoryDetailsPort historyDetailsPort,
+            GuiHistoryResetDocumentStatusPort historyResetDocumentStatusPort,
+            GuiDeleteDocumentHistoryPort deleteDocumentHistoryPort,
+            GuiPromptEditorPortFactory promptEditorPortFactory,
+            GuiCreateNewDatabasePort createNewDatabasePort,
+            Optional<String> applicationContextError,
+            Optional<SchedulerControlUseCase> schedulerControlUseCase) {
+        this(initialState, startupNotice, configurationFileLoader, configurationFileWriter,
+                modelCatalogPort, apiKeyResolutionPort, providerTechnicalTestService, pathCheckPort,
+                technicalTestOrchestrator, correctionExecutionService, batchRunLauncher,
+                miniRunLauncher, resetDocumentStatusPort, manualFileRenamePort, manualFileCopyPort,
+                historicalDocumentContextPort, applicationVersion, promptEditorPort,
+                historyOverviewPort, historyDetailsPort, historyResetDocumentStatusPort,
+                deleteDocumentHistoryPort, promptEditorPortFactory, createNewDatabasePort,
+                applicationContextError, schedulerControlUseCase, Optional.empty(),
+                GuiApplicationContextInitializer.noOp());
+    }
+
+    /**
+     * Backward-compatible constructor that fills the manual-rename port with a no-op
+     * implementation.
+     *
+     * @param initialState                initial editor state; must not be {@code null}
+     * @param startupNotice               optional startup notice; {@code null} becomes empty
+     * @param configurationFileLoader     file-loading callback; must not be {@code null}
+     * @param configurationFileWriter     file-writing callback; must not be {@code null}
+     * @param modelCatalogPort            port for retrieving AI model lists; must not be {@code null}
+     * @param apiKeyResolutionPort        port for resolving API key provenance; must not be {@code null}
+     * @param providerTechnicalTestService service for provider-specific technical checks; must not be {@code null}
+     * @param pathCheckPort               port for filesystem path accessibility checks; must not be {@code null}
+     * @param technicalTestOrchestrator   orchestrator for the full technical test run; must not be {@code null}
+     * @param correctionExecutionService  service for executing confirmed corrective actions; must not be {@code null}
+     * @param batchRunLauncher            bridge that executes a regular batch run; must not be {@code null}
+     * @param miniRunLauncher             bridge that executes a targeted mini-run for selected
+     *                                    documents; must not be {@code null}
+     * @param resetDocumentStatusPort     bridge that resets the persistence status of selected
+     *                                    documents; must not be {@code null}
+     */
+    public GuiStartupContext(
+            GuiConfigurationEditorState initialState,
+            Optional<String> startupNotice,
+            GuiConfigurationFileLoader configurationFileLoader,
+            GuiConfigurationFileWriter configurationFileWriter,
+            AiModelCatalogPort modelCatalogPort,
+            ApiKeyResolutionPort apiKeyResolutionPort,
+            ProviderTechnicalTestService providerTechnicalTestService,
+            PathCheckPort pathCheckPort,
+            TechnicalTestOrchestrator technicalTestOrchestrator,
+            CorrectionExecutionService correctionExecutionService,
+            GuiBatchRunLauncher batchRunLauncher,
+            GuiMiniRunLauncher miniRunLauncher,
+            GuiResetDocumentStatusPort resetDocumentStatusPort) {
+        this(initialState, startupNotice, configurationFileLoader, configurationFileWriter,
+                modelCatalogPort, apiKeyResolutionPort, providerTechnicalTestService, pathCheckPort,
+                technicalTestOrchestrator, correctionExecutionService, batchRunLauncher,
+                miniRunLauncher, resetDocumentStatusPort, rejectingManualFileRenamePort(),
+                rejectingManualFileCopyPort(),
+                noOpHistoricalDocumentContextPort(), "dev", noOpPromptEditorPort(),
+                noOpHistoryOverviewPort(), noOpHistoryDetailsPort(),
+                noOpHistoryResetPort(), noOpDeleteHistoryPort(), noOpPromptEditorPortFactory(),
+                rejectingCreateNewDatabasePort(), Optional.empty());
+    }
+
+    /**
+     * Backward-compatible constructor that fills the mini-run launcher, reset port and
+     * manual-rename port with no-op implementations.
+     *
+     * @param initialState                initial editor state; must not be {@code null}
+     * @param startupNotice               optional startup notice; {@code null} becomes empty
+     * @param configurationFileLoader     file-loading callback; must not be {@code null}
+     * @param configurationFileWriter     file-writing callback; must not be {@code null}
+     * @param modelCatalogPort            port for retrieving AI model lists; must not be {@code null}
+     * @param apiKeyResolutionPort        port for resolving API key provenance; must not be {@code null}
+     * @param providerTechnicalTestService service for provider-specific technical checks; must not be {@code null}
+     * @param pathCheckPort               port for filesystem path accessibility checks; must not be {@code null}
+     * @param technicalTestOrchestrator   orchestrator for the full technical test run; must not be {@code null}
+     * @param correctionExecutionService  service for executing confirmed corrective actions; must not be {@code null}
+     * @param batchRunLauncher            bridge that executes a regular batch run; must not be {@code null}
+     */
+    public GuiStartupContext(
+            GuiConfigurationEditorState initialState,
+            Optional<String> startupNotice,
+            GuiConfigurationFileLoader configurationFileLoader,
+            GuiConfigurationFileWriter configurationFileWriter,
+            AiModelCatalogPort modelCatalogPort,
+            ApiKeyResolutionPort apiKeyResolutionPort,
+            ProviderTechnicalTestService providerTechnicalTestService,
+            PathCheckPort pathCheckPort,
+            TechnicalTestOrchestrator technicalTestOrchestrator,
+            CorrectionExecutionService correctionExecutionService,
+            GuiBatchRunLauncher batchRunLauncher) {
+        this(initialState, startupNotice, configurationFileLoader, configurationFileWriter,
+                modelCatalogPort, apiKeyResolutionPort, providerTechnicalTestService, pathCheckPort,
+                technicalTestOrchestrator, correctionExecutionService, batchRunLauncher,
+                rejectingMiniRunLauncher(), rejectingResetPort(), rejectingManualFileRenamePort(),
+                rejectingManualFileCopyPort(),
+                noOpHistoricalDocumentContextPort(), "dev", noOpPromptEditorPort(),
+                noOpHistoryOverviewPort(), noOpHistoryDetailsPort(),
+                noOpHistoryResetPort(), noOpDeleteHistoryPort(), noOpPromptEditorPortFactory(),
+                rejectingCreateNewDatabasePort(), Optional.empty());
+    }
+
+    /**
+     * Backward-compatible constructor that fills the processing-run launcher, mini-run
+     * launcher, reset port and manual-rename port with no-op implementations.
+     * <p>
+     * Preserves existing callers that were written before the processing-run tab was added.
+     *
+     * @param initialState                initial editor state; must not be {@code null}
+     * @param startupNotice               optional startup notice; {@code null} becomes empty
+     * @param configurationFileLoader     file-loading callback; must not be {@code null}
+     * @param configurationFileWriter     file-writing callback; must not be {@code null}
+     * @param modelCatalogPort            port for retrieving AI model lists; must not be {@code null}
+     * @param apiKeyResolutionPort        port for resolving API key provenance; must not be {@code null}
+     * @param providerTechnicalTestService service for provider-specific technical checks; must not be {@code null}
+     * @param pathCheckPort               port for filesystem path accessibility checks; must not be {@code null}
+     * @param technicalTestOrchestrator   orchestrator for the full technical test run; must not be {@code null}
+     * @param correctionExecutionService  service for executing confirmed corrective actions; must not be {@code null}
+     */
+    public GuiStartupContext(
+            GuiConfigurationEditorState initialState,
+            Optional<String> startupNotice,
+            GuiConfigurationFileLoader configurationFileLoader,
+            GuiConfigurationFileWriter configurationFileWriter,
+            AiModelCatalogPort modelCatalogPort,
+            ApiKeyResolutionPort apiKeyResolutionPort,
+            ProviderTechnicalTestService providerTechnicalTestService,
+            PathCheckPort pathCheckPort,
+            TechnicalTestOrchestrator technicalTestOrchestrator,
+            CorrectionExecutionService correctionExecutionService) {
+        this(initialState, startupNotice, configurationFileLoader, configurationFileWriter,
+                modelCatalogPort, apiKeyResolutionPort, providerTechnicalTestService, pathCheckPort,
+                technicalTestOrchestrator, correctionExecutionService,
+                rejectingBatchRunLauncher(), rejectingMiniRunLauncher(), rejectingResetPort(),
+                rejectingManualFileRenamePort(), rejectingManualFileCopyPort(),
+                noOpHistoricalDocumentContextPort(), "dev", noOpPromptEditorPort(),
+                noOpHistoryOverviewPort(), noOpHistoryDetailsPort(),
+                noOpHistoryResetPort(), noOpDeleteHistoryPort(), noOpPromptEditorPortFactory(),
+                rejectingCreateNewDatabasePort(), Optional.empty());
+    }
+
+    private static GuiBatchRunLauncher rejectingBatchRunLauncher() {
+        return (configPath, observer, token) -> GuiBatchRunLaunchOutcome.rejected(
+                "Kein Verarbeitungslauf-Launcher in diesem Startkontext verfügbar.");
+    }
+
+    private static GuiMiniRunLauncher rejectingMiniRunLauncher() {
+        return (configPath, filter, observer, token) -> GuiBatchRunLaunchOutcome.rejected(
+                "Kein Mini-Run-Launcher in diesem Startkontext verfügbar.");
+    }
+
+    private static GuiResetDocumentStatusPort rejectingResetPort() {
+        return (configPath, fingerprints) -> {
+            java.util.Map<DocumentFingerprint, String> failures = new java.util.HashMap<>();
+            for (DocumentFingerprint fp : fingerprints) {
+                failures.put(fp, "Kein Reset-Port in diesem Startkontext verfügbar.");
+            }
+            return new ResetDocumentStatusResult(fingerprints.size(), Set.of(), failures);
+        };
+    }
+
+    private static GuiManualFileRenamePort rejectingManualFileRenamePort() {
+        return (configPath, request) -> new de.gecheckt.pdf.umbenenner.application.port.in
+                .ManualFileRenameFileSystemFailure(
+                        "Kein Umbenennungs-Port in diesem Startkontext verfügbar.");
+    }
+
+    private static GuiManualFileCopyPort rejectingManualFileCopyPort() {
+        return (configPath, request) -> new de.gecheckt.pdf.umbenenner.application.port.in
+                .ManualFileCopyFileSystemFailure(
+                        "Kein Kopier-Port in diesem Startkontext verfügbar.");
+    }
+
+    private static GuiHistoricalDocumentContextPort noOpHistoricalDocumentContextPort() {
+        return (configPath, fingerprint) -> java.util.Optional.empty();
+    }
+
+    /**
+     * Creates a blank startup context with no-op implementations for all ports and services.
+     * <p>
+     * This is safe for environments where no Bootstrap wiring is present, such as isolated
+     * GUI tests.
+     *
+     * @param startupNotice optional startup notice; {@code null} becomes empty
+     * @return a startup context for the unloaded editor start
+     */
+    public static GuiStartupContext blank(Optional<String> startupNotice) {
+        de.gecheckt.pdf.umbenenner.application.port.out.modelcatalog.AiModelCatalogPort noOpCatalogPort =
+                request -> new de.gecheckt.pdf.umbenenner.application.port.out.modelcatalog
+                        .ModelCatalogResult.IncompleteConfiguration(
+                                request.providerIdentifier(),
+                                "Kein Modellkatalog in diesem Startkontext verfügbar.");
+        ApiKeyResolutionPort noOpApiKeyPort = (family, propertyValue) -> EffectiveApiKeyDescriptor.absent();
+        ProviderTechnicalTestService noOpTestService =
+                new ProviderTechnicalTestService(noOpCatalogPort, noOpApiKeyPort);
+        PathCheckPort noOpPathCheckPort = new PathCheckPort() {
+            @Override
+            public boolean isDirectoryReadable(String path) { return false; }
+            @Override
+            public boolean isDirectoryWritableOrCreatable(String path) { return false; }
+            @Override
+            public boolean isFileReadable(String path) { return false; }
+            @Override
+            public boolean isSqlitePathUsable(String path) { return false; }
+        };
+        TechnicalTestOrchestrator noOpOrchestrator = new TechnicalTestOrchestrator(
+                new de.gecheckt.pdf.umbenenner.application.validation.editor.EditorConfigurationValidator(),
+                noOpPathCheckPort,
+                noOpTestService,
+                () -> java.util.Optional.empty());
+        ResourceCreationPort noOpResourceCreationPort = new ResourceCreationPort() {
+            @Override
+            public de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionOutcome
+                    createDirectory(de.gecheckt.pdf.umbenenner.application.validation.technicaltest
+                            .CorrectionSuggestion.CreateDirectory suggestion) {
+                return new de.gecheckt.pdf.umbenenner.application.validation.technicaltest
+                        .CorrectionOutcome.NotAttempted(suggestion, NO_PORT_MSG);
+            }
+            @Override
+            public de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionOutcome
+                    createPromptFile(de.gecheckt.pdf.umbenenner.application.validation.technicaltest
+                            .CorrectionSuggestion.CreatePromptFile suggestion) {
+                return new de.gecheckt.pdf.umbenenner.application.validation.technicaltest
+                        .CorrectionOutcome.NotAttempted(suggestion, NO_PORT_MSG);
+            }
+            @Override
+            public de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionOutcome
+                    prepareSqlitePath(de.gecheckt.pdf.umbenenner.application.validation.technicaltest
+                            .CorrectionSuggestion.PrepareSqlitePath suggestion) {
+                return new de.gecheckt.pdf.umbenenner.application.validation.technicaltest
+                        .CorrectionOutcome.NotAttempted(suggestion, NO_PORT_MSG);
+            }
+        };
+        CorrectionExecutionService noOpCorrectionService = new CorrectionExecutionService(noOpResourceCreationPort);
+        GuiBatchRunLauncher noOpBatchRunLauncher = (configPath, observer, token) ->
+                GuiBatchRunLaunchOutcome.rejected(
+                        "Kein Verarbeitungslauf-Launcher in diesem Startkontext verfügbar.");
+        return new GuiStartupContext(
+                GuiConfigurationEditorStateFactory.createBlankStartState(),
+                startupNotice,
+                configFilePath -> GuiConfigurationEditorStateFactory.createBlankStartState(),
+                (values, path) -> GuiConfigurationSaveResult.saved(path),
+                noOpCatalogPort,
+                noOpApiKeyPort,
+                noOpTestService,
+                noOpPathCheckPort,
+                noOpOrchestrator,
+                noOpCorrectionService,
+                noOpBatchRunLauncher,
+                rejectingMiniRunLauncher(),
+                rejectingResetPort(),
+                rejectingManualFileRenamePort(),
+                rejectingManualFileCopyPort(),
+                noOpHistoricalDocumentContextPort(),
+                "dev",
+                noOpPromptEditorPort(),
+                noOpHistoryOverviewPort(),
+                noOpHistoryDetailsPort(),
+                noOpHistoryResetPort(),
+                noOpDeleteHistoryPort(),
+                noOpPromptEditorPortFactory(),
+                rejectingCreateNewDatabasePort(),
+                Optional.empty());
+    }
+
+    /**
+     * Liefert einen ablehnenden {@link GuiCreateNewDatabasePort}, der jede Anlage
+     * sofort als Fehler zurückgibt. Wird verwendet, wenn kein Bootstrap-seitig
+     * verdrahteter Port vorliegt (z. B. in Tests oder vor dem Laden einer
+     * Konfiguration).
+     *
+     * @return ein ablehnender Port; nie {@code null}
+     */
+    private static GuiCreateNewDatabasePort rejectingCreateNewDatabasePort() {
+        return (configFilePath, targetFile) -> new de.gecheckt.pdf.umbenenner.application.port.in
+                .CreateNewDatabaseUseCase.CreateNewDatabaseResult.CreationFailed(
+                        de.gecheckt.pdf.umbenenner.application.port.in
+                                .CreateNewDatabaseUseCase.CreateNewDatabaseResult.Phase.PATH_RESOLUTION,
+                        "Kein DB-Anlage-Port in diesem Startkontext verfügbar.",
+                        null);
+    }
+
+    private static GuiPromptEditorPortFactory noOpPromptEditorPortFactory() {
+        return path -> noOpPromptEditorPort();
+    }
+
+    private static GuiPromptEditorPort noOpPromptEditorPort() {
+        return new GuiPromptEditorPort() {
+            @Override
+            public de.gecheckt.pdf.umbenenner.application.port.out.PromptLoadingResult loadCurrentPrompt() {
+                return new de.gecheckt.pdf.umbenenner.application.port.out.PromptLoadingFailure(
+                        "NO_OP", NO_PROMPT_PORT_MSG);
+            }
+
+            @Override
+            public de.gecheckt.pdf.umbenenner.application.port.out.PromptSaveResult save(String content) {
+                return new de.gecheckt.pdf.umbenenner.application.port.out.PromptSaveResult.WriteFailed(
+                        NO_PROMPT_PORT_MSG, null);
+            }
+
+            @Override
+            public de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionOutcome
+                    createDefaultPromptIfMissing(
+                            de.gecheckt.pdf.umbenenner.application.validation.technicaltest
+                                    .CorrectionSuggestion.CreatePromptFile suggestion) {
+                return new de.gecheckt.pdf.umbenenner.application.validation.technicaltest
+                        .CorrectionOutcome.NotAttempted(
+                                suggestion, NO_PROMPT_PORT_MSG);
+            }
+        };
+    }
+
+    private static de.gecheckt.pdf.umbenenner.adapter.in.gui.history.GuiHistoryOverviewPort
+            noOpHistoryOverviewPort() {
+        return (configFilePath, query) -> new de.gecheckt.pdf.umbenenner.application.usecase
+                .DefaultHistoryOverviewUseCase.HistoryOverviewResult(java.util.List.of(), false);
+    }
+
+    private static de.gecheckt.pdf.umbenenner.adapter.in.gui.history.GuiHistoryDetailsPort
+            noOpHistoryDetailsPort() {
+        return (configFilePath, fingerprint) -> java.util.Optional.empty();
+    }
+
+    private static de.gecheckt.pdf.umbenenner.adapter.in.gui.history.GuiHistoryResetDocumentStatusPort
+            noOpHistoryResetPort() {
+        return (configFilePath, fingerprint) -> { /* kein Reset in diesem Startkontext */ };
+    }
+
+    private static de.gecheckt.pdf.umbenenner.adapter.in.gui.history.GuiDeleteDocumentHistoryPort
+            noOpDeleteHistoryPort() {
+        return (configFilePath, fingerprint) -> { /* kein Löschen in diesem Startkontext */ };
+    }
+}
@@ -0,0 +1,31 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.util.Optional;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Process-local holder for the next GUI startup context.
+ * <p>
+ * JavaFX creates the application class reflectively, so Bootstrap installs the context here
+ * immediately before the JavaFX launch call.
+ */
+final class GuiStartupContextHolder {
+
+    private static final AtomicReference<GuiStartupContext> CONTEXT = new AtomicReference<>();
+
+    private GuiStartupContextHolder() {
+        // Utility class.
+    }
+
+    static void install(GuiStartupContext context) {
+        CONTEXT.set(context);
+    }
+
+    static GuiStartupContext currentOrBlank() {
+        return Optional.ofNullable(CONTEXT.get()).orElseGet(() -> GuiStartupContext.blank(Optional.empty()));
+    }
+
+    static void clear() {
+        CONTEXT.set(null);
+    }
+}
@@ -0,0 +1,199 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.AiProviderFamilyStringConverter;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiConfigurationEditorState;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiProviderConfigurationState;
+import de.gecheckt.pdf.umbenenner.application.config.provider.AiProviderFamily;
+import javafx.geometry.Insets;
+import javafx.geometry.Pos;
+import javafx.scene.control.Label;
+import javafx.scene.control.Separator;
+import javafx.scene.layout.BorderPane;
+import javafx.scene.layout.HBox;
+import javafx.scene.layout.Priority;
+import javafx.scene.layout.Region;
+
+/**
+ * Permanente Statuszeile am unteren Rand des Hauptfensters.
+ * <p>
+ * Die Statuszeile zeigt immer drei Segmente:
+ * <ul>
+ *   <li><b>Links:</b> Anwendungsversion im Format {@code V<version>}, z.&nbsp;B. {@code Vdev}.</li>
+ *   <li><b>Mitte:</b> Aktiver Provider und Modellname aus der geladenen Konfiguration.</li>
+ *   <li><b>Rechts:</b> Pfad der geladenen Konfigurationsdatei.</li>
+ * </ul>
+ * Wenn keine Konfiguration geladen ist, zeigen Mitte und Rechts den Text
+ * {@value #KEIN_PROFIL_TEXT}. Die Versionsanzeige ist stets sichtbar.
+ * <p>
+ * Alle Aktualisierungen dieser Komponente müssen auf dem JavaFX Application Thread erfolgen.
+ * Die Klasse selbst erzwingt dies nicht; der Aufrufer trägt die Verantwortung.
+ */
+public final class GuiStatusBar {
+    private static final String LABEL_STYLE = "-fx-font-size: 11px; -fx-text-fill: #555555;";
+
+
+
+    /** Anzeigetext wenn keine Konfiguration geladen ist. */
+    static final String KEIN_PROFIL_TEXT = "Kein Profil geladen";
+
+    /** Präfix vor der Versionsnummer in der linken Statuszeilen-Zelle. */
+    private static final String VERSION_PREFIX = "V";
+
+    private static final AiProviderFamilyStringConverter PROVIDER_CONVERTER =
+            new AiProviderFamilyStringConverter();
+
+    private final String applicationVersion;
+    private final BorderPane root;
+    private final Label versionLabel;
+    private final Label providerLabel;
+    private final Label configPathLabel;
+
+    /**
+     * Erstellt eine neue Statuszeile mit der angegebenen Anwendungsversion.
+     *
+     * @param applicationVersion die aufgelöste Versionsnummer; {@code null} oder leer führt zum
+     *                           Fallback {@code "dev"}
+     */
+    public GuiStatusBar(String applicationVersion) {
+        this.applicationVersion = (applicationVersion == null || applicationVersion.isBlank())
+                ? "dev"
+                : applicationVersion;
+
+        // Linkes Segment: Versionsanzeige
+        this.versionLabel = new Label(VERSION_PREFIX + this.applicationVersion);
+        this.versionLabel.setStyle(LABEL_STYLE);
+
+        // Mittleres Segment: Provider und Modell
+        this.providerLabel = new Label(KEIN_PROFIL_TEXT);
+        this.providerLabel.setStyle(LABEL_STYLE);
+        this.providerLabel.setAlignment(Pos.CENTER);
+
+        // Rechtes Segment: Konfigurationspfad
+        this.configPathLabel = new Label(KEIN_PROFIL_TEXT);
+        this.configPathLabel.setStyle(LABEL_STYLE);
+        this.configPathLabel.setAlignment(Pos.CENTER_RIGHT);
+
+        // Abstandhalter zwischen den Segmenten
+        Region leftSpacer = new Region();
+        Region rightSpacer = new Region();
+        HBox.setHgrow(leftSpacer, Priority.ALWAYS);
+        HBox.setHgrow(rightSpacer, Priority.ALWAYS);
+
+        HBox content = new HBox(16,
+                versionLabel, leftSpacer,
+                providerLabel, rightSpacer,
+                configPathLabel);
+        content.setAlignment(Pos.CENTER_LEFT);
+        content.setPadding(new Insets(4, 12, 4, 12));
+        content.setStyle("-fx-background-color: #f5f5f5;");
+
+        Separator topSeparator = new Separator();
+
+        this.root = new BorderPane();
+        this.root.setTop(topSeparator);
+        this.root.setCenter(content);
+    }
+
+    /**
+     * Gibt den Wurzelknoten der Statuszeile zurück, der in das Hauptfenster eingebettet wird.
+     *
+     * @return der Wurzelknoten; nie {@code null}
+     */
+    public BorderPane root() {
+        return root;
+    }
+
+    /**
+     * Aktualisiert die Statuszeile anhand des aktuellen Editor-Zustands.
+     * <p>
+     * Ist kein Dateisnapshot vorhanden, wird {@link #clearConfiguration()} ausgeführt.
+     * Andernfalls werden Provider, Modell und Konfigurationspfad aus dem Zustand ermittelt
+     * und angezeigt.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     *
+     * @param state der aktuelle Editor-Zustand; darf nicht {@code null} sein
+     */
+    public void applyEditorState(GuiConfigurationEditorState state) {
+        if (state == null || !state.hasLoadedFileSnapshot()) {
+            clearConfiguration();
+            return;
+        }
+        String configPath = state.configurationPathText();
+        String providerText = resolveProviderText(state);
+        providerLabel.setText(providerText);
+        configPathLabel.setText(configPath.isBlank() ? KEIN_PROFIL_TEXT : configPath);
+    }
+
+    /**
+     * Setzt Mitte und Rechts der Statuszeile auf den Text {@link #KEIN_PROFIL_TEXT} zurück.
+     * <p>
+     * Die Versionsanzeige bleibt unverändert.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     */
+    public void clearConfiguration() {
+        providerLabel.setText(KEIN_PROFIL_TEXT);
+        configPathLabel.setText(KEIN_PROFIL_TEXT);
+    }
+
+    /**
+     * Gibt den aktuell angezeigten Versionstext zurück (inkl. Präfix {@code V}).
+     * <p>
+     * Für Tests zugänglich.
+     *
+     * @return der angezeigte Versionstext; nie {@code null}
+     */
+    String versionText() {
+        return versionLabel.getText();
+    }
+
+    /**
+     * Gibt den aktuell angezeigten Provider-Text zurück.
+     * <p>
+     * Für Tests zugänglich.
+     *
+     * @return der angezeigte Provider-Text; nie {@code null}
+     */
+    String providerText() {
+        return providerLabel.getText();
+    }
+
+    /**
+     * Gibt den aktuell angezeigten Konfigurationspfad-Text zurück.
+     * <p>
+     * Für Tests zugänglich.
+     *
+     * @return der angezeigte Konfigurationspfad-Text; nie {@code null}
+     */
+    String configPathText() {
+        return configPathLabel.getText();
+    }
+
+    /**
+     * Ermittelt den anzuzeigenden Provider-Text aus dem Editor-Zustand.
+     * <p>
+     * Das Format ist: {@code Provider: <AnzeigeName> · <Modellname>}, wobei der Modellname
+     * weggelassen wird, wenn er leer ist.
+     *
+     * @param state der Editor-Zustand; darf nicht {@code null} sein
+     * @return der formatierte Provider-Text; nie {@code null}
+     */
+    private static String resolveProviderText(GuiConfigurationEditorState state) {
+        String activeIdentifier = state.values().activeProviderFamily();
+        if (activeIdentifier == null || activeIdentifier.isBlank()) {
+            return KEIN_PROFIL_TEXT;
+        }
+        AiProviderFamily family = AiProviderFamily.fromIdentifier(activeIdentifier).orElse(null);
+        if (family == null) {
+            return KEIN_PROFIL_TEXT;
+        }
+        String displayName = PROVIDER_CONVERTER.toString(family);
+        GuiProviderConfigurationState providerState = state.values().providerConfiguration(family);
+        String model = providerState != null ? providerState.model() : "";
+        if (model == null || model.isBlank()) {
+            return "Provider: " + displayName;
+        }
+        return "Provider: " + displayName + " · " + model;
+    }
+}
@@ -0,0 +1,68 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.util.Objects;
+import java.util.Optional;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.SchedulerControlUseCase;
+import javafx.animation.Animation;
+import javafx.animation.KeyFrame;
+import javafx.animation.Timeline;
+import javafx.util.Duration;
+
+/**
+ * Zentrale Status-Refresh-Timeline für die GUI.
+ * <p>
+ * Startet eine JavaFX-{@link Timeline}, die im Sekundentakt einen Callback aufruft.
+ * Der Callback liest den aktuellen Scheduler-Status und aktualisiert alle betroffenen
+ * Tabs (Batch-Tab, Konfig-Tab, Scheduler-Tab) auf dem JavaFX Application Thread.
+ * <p>
+ * Die Timeline wird beim Aufbau der Haupt-GUI gestartet und beim Beenden der
+ * Anwendung gestoppt. Sie läuft unabhängig davon, welcher Tab gerade sichtbar ist.
+ * <p>
+ * Wenn kein {@link SchedulerControlUseCase} vorhanden ist, wird der Callback trotzdem
+ * aufgerufen – der Aufrufer entscheidet, wie er das leere Optional behandelt.
+ */
+public final class GuiStatusRefreshTimeline {
+
+    private final Timeline timeline;
+
+    /**
+     * Erzeugt eine neue Status-Refresh-Timeline.
+     * <p>
+     * Die Timeline ist nach der Konstruktion noch nicht aktiv; {@link #start()} muss
+     * explizit aufgerufen werden.
+     *
+     * @param schedulerControlUseCase optionaler Scheduler-Control-Use-Case;
+     *                                 {@code null} wird als leer behandelt
+     * @param onRefresh               Callback der bei jedem Tick auf dem JavaFX Application
+     *                                 Thread aufgerufen wird; darf nicht {@code null} sein
+     */
+    public GuiStatusRefreshTimeline(
+            Optional<SchedulerControlUseCase> schedulerControlUseCase,
+            Runnable onRefresh) {
+        Objects.requireNonNull(onRefresh, "onRefresh must not be null");
+        this.timeline = new Timeline(
+                new KeyFrame(Duration.seconds(1), e -> onRefresh.run()));
+        this.timeline.setCycleCount(Animation.INDEFINITE);
+    }
+
+    /**
+     * Startet die Status-Refresh-Timeline.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     * Mehrfache Aufrufe sind unschädlich.
+     */
+    public void start() {
+        timeline.play();
+    }
+
+    /**
+     * Stoppt die Status-Refresh-Timeline.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     * Mehrfache Aufrufe sind unschädlich.
+     */
+    public void stop() {
+        timeline.stop();
+    }
+}
@@ -0,0 +1,282 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import java.util.function.Supplier;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiMessageEntry;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiMessageSeverity;
+import de.gecheckt.pdf.umbenenner.application.validation.editor.EditorValidationInput;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CheckpointId;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CheckpointResult;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.TechnicalTestOrchestrator;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.TechnicalTestReport;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.TechnicalTestRequest;
+import javafx.application.Platform;
+
+/**
+ * Koordiniert die asynchrone Ausführung der Aktion „Technische Tests ausführen"
+ * für den GUI-Konfigurationseditor.
+ * <p>
+ * Dieser Koordinator ist verantwortlich für:
+ * <ul>
+ *   <li>Lesen des aktuellen GUI-Editorzustands (via {@link Supplier}).</li>
+ *   <li>Aufbau eines {@link TechnicalTestRequest} aus dem aktuellen Zustand.</li>
+ *   <li>Ausführung des {@link TechnicalTestOrchestrator} auf einem dedizierten
+ *       Daemon-Hinterground-Thread namens {@code gui-technical-test}.</li>
+ *   <li>Rückführung des {@link TechnicalTestReport} auf den JavaFX Application Thread
+ *       via {@code Platform.runLater}.</li>
+ *   <li>Einhängen der Ergebnisse als {@link GuiMessageEntry}-Einträge in die geteilte
+ *       {@code pendingMessages}-Liste (Quelle: „Technische-Tests").</li>
+ *   <li>Ersetzen vorheriger Test-Einträge (Replace-Semantik) bei jedem neuen Aufruf.</li>
+ *   <li>Weitergabe des vollständigen Berichts an den {@code postResultCallback}, damit
+ *       spätere Arbeitsschritte (z. B. Korrekturhilfen) auf das Ergebnis zugreifen können.</li>
+ * </ul>
+ * <p>
+ * <strong>Threading-Kontrakt:</strong> {@link #triggerTechnicalTests()} darf nur auf dem
+ * JavaFX Application Thread aufgerufen werden. Hintergrund-Worker-Threads dürfen nur über
+ * den injizierten {@code resultDelivery}-Verbraucher mit der UI interagieren, der in der
+ * Produktion {@code Platform.runLater} kapselt.
+ * <p>
+ * <strong>Kein implizites Speichern:</strong> Der Koordinator liest den aktuellen GUI-Zustand
+ * und führt den Test aus, ohne die Konfigurationsdatei zu schreiben oder den Dirty-Zustand
+ * des Editors zu ändern.
+ * <p>
+ * <strong>Anti-Scope:</strong> Dieser Koordinator führt keine schreibenden Korrekturen durch.
+ * Korrekturvorschläge werden als Bestandteil des {@link TechnicalTestReport} zurückgegeben,
+ * sind aber nicht ausführbar. Die Ausführung ist einem späteren Arbeitsschritt vorbehalten.
+ * <p>
+ * Die Worker-Thread-Factory und die Result-Delivery-Funktion sind injizierbar, damit Tests
+ * deterministisch ohne echten Hintergrund-Thread laufen können.
+ */
+public final class GuiTechnicalTestCoordinator {
+
+    /** Quell-Tag für Einträge in {@code pendingMessages}, die von diesem Koordinator stammen. */
+    static final String SOURCE_TAG = "Technische-Tests";
+
+    private static final Logger LOG = LogManager.getLogger(GuiTechnicalTestCoordinator.class);
+
+    private final TechnicalTestOrchestrator orchestrator;
+    private final Supplier<EditorValidationInput> inputProvider;
+    private final Supplier<String> configFilePathProvider;
+    private final Supplier<String> logDirectoryProvider;
+    private final List<GuiMessageEntry> pendingMessages;
+    private final Consumer<TechnicalTestReport> postResultCallback;
+
+    /**
+     * Factory für den Hintergrund-Worker-Thread. Paket-privat für Test-Substitution.
+     * Standard: Daemon-Thread namens {@code gui-technical-test}.
+     */
+    Function<Runnable, Thread> testThreadFactory;
+
+    /**
+     * Verbraucher zur Rückführung des Ergebnisses. In der Produktion kapselt er {@code Platform.runLater}.
+     * In Tests kann er durch einen direkten Aufruf ersetzt werden, damit das Ergebnis sofort
+     * auf dem Worker-Thread angewendet wird, ohne die FX-Warteschlange zu entwässern.
+     * Paket-privat für Test-Substitution.
+     */
+    java.util.function.Consumer<Runnable> resultDelivery = Platform::runLater;
+
+    /**
+     * Erstellt einen neuen Koordinator.
+     *
+     * @param orchestrator           Orchestrator für den vollständigen Gesamttest; darf nicht {@code null} sein
+     * @param inputProvider          Lieferant des aktuellen {@link EditorValidationInput}; darf nicht {@code null} sein
+     * @param configFilePathProvider Lieferant des aktuell geladenen Konfigurationsdateipfads als String;
+     *                               gibt eine leere Zeichenkette zurück wenn keine Datei geladen ist;
+     *                               darf nicht {@code null} sein
+     * @param logDirectoryProvider   Lieferant des konfigurierten {@code log.directory}-Rohwerts;
+     *                               gibt eine leere Zeichenkette zurück wenn kein Wert konfiguriert ist;
+     *                               darf nicht {@code null} sein
+     * @param pendingMessages        geteilte veränderliche Nachrichtenliste; darf nicht {@code null} sein
+     * @param postResultCallback     Callback nach erfolgreicher Ergebnisanwendung; darf nicht {@code null} sein
+     * @throws NullPointerException wenn einer der Parameter {@code null} ist
+     */
+    public GuiTechnicalTestCoordinator(TechnicalTestOrchestrator orchestrator,
+                                       Supplier<EditorValidationInput> inputProvider,
+                                       Supplier<String> configFilePathProvider,
+                                       Supplier<String> logDirectoryProvider,
+                                       List<GuiMessageEntry> pendingMessages,
+                                       Consumer<TechnicalTestReport> postResultCallback) {
+        this.orchestrator = Objects.requireNonNull(orchestrator, "orchestrator must not be null");
+        this.inputProvider = Objects.requireNonNull(inputProvider, "inputProvider must not be null");
+        this.configFilePathProvider = Objects.requireNonNull(configFilePathProvider, "configFilePathProvider must not be null");
+        this.logDirectoryProvider = Objects.requireNonNull(logDirectoryProvider, "logDirectoryProvider must not be null");
+        this.pendingMessages = Objects.requireNonNull(pendingMessages, "pendingMessages must not be null");
+        this.postResultCallback = Objects.requireNonNull(postResultCallback, "postResultCallback must not be null");
+        this.testThreadFactory = task -> {
+            Thread t = new Thread(task, "gui-technical-test");
+            t.setDaemon(true);
+            return t;
+        };
+    }
+
+    /**
+     * Löst die asynchrone Ausführung des vollständigen technischen Gesamttests aus.
+     * <p>
+     * Vor dem Worker-Start wird die geteilte Nachrichtenliste auf dem FX-Thread geleert;
+     * jeder Aufruf ersetzt die zuvor angefügten Einträge (Replace-Semantik).
+     * <p>
+     * Liest den aktuellen Editorzustand und den Konfigurationsdateipfad, baut einen
+     * {@link TechnicalTestRequest} und startet den {@link TechnicalTestOrchestrator} auf
+     * einem Hintergrund-Worker-Thread. Das Ergebnis wird via {@code resultDelivery} an den
+     * JavaFX Application Thread zurückgegeben.
+     * <p>
+     * Der Konfigurationsdateipfad wird genutzt, um bei fehlender Prompt-Datei-Konfiguration
+     * einen sinnvollen Standardpfad ({@code <config-parent>/prompt.txt}) zu bestimmen.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     */
+    public void triggerTechnicalTests() {
+        // Bestehende Nachrichtenliste auf dem FX-Thread leeren, bevor der Worker-Thread
+        // startet. Dadurch laufen clear() und nachfolgende add()-Aufrufe (die per
+        // Platform.runLater wieder auf dem FX-Thread landen) auf demselben Thread und
+        // es entsteht kein Race-Fenster mit der UI.
+        pendingMessages.clear();
+        EditorValidationInput input = inputProvider.get();
+        String configFilePath = configFilePathProvider.get();
+        String logDirectory = logDirectoryProvider.get();
+        TechnicalTestRequest request = new TechnicalTestRequest(input, configFilePath, logDirectory);
+
+        LOG.info("GUI-Gesamttest: Technische Tests ausführen gestartet.");
+
+        Runnable task = () -> {
+            TechnicalTestReport report = orchestrator.run(request);
+            resultDelivery.accept(() -> {
+                applyResult(report);
+                postResultCallback.accept(report);
+            });
+        };
+
+        Thread worker = testThreadFactory.apply(task);
+        worker.start();
+    }
+
+    /**
+     * Wendet das Ergebnis des vollständigen Gesamttests auf die geteilte Nachrichtenliste an.
+     * <p>
+     * Fügt für jedes Checkpoint-Ergebnis einen neuen Eintrag zur geteilten Nachrichtenliste
+     * hinzu. Die Liste wurde zuvor in {@link #triggerTechnicalTests()} geleert, sodass jeder
+     * Aufruf einen frischen Stand erzeugt. Zusätzlich wird eine Zusammenfassung angehängt.
+     * <p>
+     * Muss nur auf dem JavaFX Application Thread aufgerufen werden (via {@code resultDelivery}).
+     *
+     * @param report der vollständige Gesamttestbericht; darf nicht {@code null} sein
+     */
+    private void applyResult(TechnicalTestReport report) {
+
+        long successCount = 0;
+        long failureErrorCount = 0;
+        long failureWarnCount = 0;
+        long notApplicableCount = 0;
+
+        for (CheckpointResult result : report.results()) {
+            String label = labelFor(result.checkpointId());
+            switch (result) {
+                case CheckpointResult.Success success -> {
+                    pendingMessages.add(GuiMessageEntry.of(
+                            GuiMessageSeverity.INFO,
+                            label + ": OK – " + success.message(),
+                            SOURCE_TAG));
+                    successCount++;
+                    LOG.info("GUI-Gesamttest: {} → OK", label);
+                }
+                case CheckpointResult.Failure failure -> {
+                    GuiMessageSeverity severity = failure.severity() ==
+                            de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CheckpointSeverity.ERROR
+                            ? GuiMessageSeverity.ERROR : GuiMessageSeverity.WARNING;
+                    pendingMessages.add(GuiMessageEntry.of(
+                            severity,
+                            label + ": " + failure.message(),
+                            SOURCE_TAG));
+                    if (severity == GuiMessageSeverity.ERROR) {
+                        failureErrorCount++;
+                        LOG.warn("GUI-Gesamttest: {} → FEHLER: {}", label, failure.message());
+                    } else {
+                        failureWarnCount++;
+                        LOG.warn("GUI-Gesamttest: {} → WARNUNG: {}", label, failure.message());
+                    }
+                }
+                case CheckpointResult.NotApplicable notApplicable -> {
+                    pendingMessages.add(GuiMessageEntry.of(
+                            GuiMessageSeverity.HINT,
+                            label + ": nicht anwendbar – " + notApplicable.reason(),
+                            SOURCE_TAG));
+                    notApplicableCount++;
+                    LOG.info("GUI-Gesamttest: {} → nicht anwendbar: {}", label, notApplicable.reason());
+                }
+            }
+        }
+
+        // Zusammenfassung
+        long totalFindings = failureErrorCount + failureWarnCount;
+        String summary = buildSummaryMessage(report.results().size(),
+                successCount, failureErrorCount, failureWarnCount, notApplicableCount);
+        pendingMessages.add(GuiMessageEntry.of(GuiMessageSeverity.INFO, summary, SOURCE_TAG));
+        LOG.info("GUI-Gesamttest abgeschlossen. {} Befunde ({} Erfolg, {} Fehler, {} Warnung, {} nicht anwendbar).",
+                totalFindings, successCount, failureErrorCount, failureWarnCount, notApplicableCount);
+    }
+
+    /**
+     * Gibt das deutsche Label für einen Prüfpunkt zurück.
+     *
+     * @param id der Prüfpunkt-Bezeichner; darf nicht {@code null} sein
+     * @return das deutsche Label; nie {@code null}
+     */
+    static String labelFor(CheckpointId id) {
+        return switch (id) {
+            case CONFIGURATION_BASIC_VALIDATION -> "Konfiguration grundsätzlich validierbar";
+            case PROVIDER_CONFIGURATION -> "Provider-Konfiguration prüfbar";
+            case BASE_URL_REACHABLE -> "Basis-URL/Endpoint erreichbar";
+            case API_KEY_PRESENT -> "API-Schlüssel vorhanden";
+            case API_KEY_ACCEPTED -> "API-Schlüssel technisch akzeptiert";
+            case MODEL_LIST_AVAILABLE -> "Modellliste abrufbar";
+            case SELECTED_MODEL_PLAUSIBLE -> "Ausgewähltes Modell plausibel";
+            case PROMPT_FILE_PRESENT -> "Prompt-Datei vorhanden und lesbar";
+            case SOURCE_FOLDER_PRESENT -> "Quellordner vorhanden und lesbar";
+            case TARGET_FOLDER_USABLE -> "Zielordner vorhanden oder anlegbar sowie schreibbar";
+            case SQLITE_PATH_USABLE -> "SQLite-Pfad technisch nutzbar";
+            case LOG_DIRECTORY_USABLE -> "Log-Verzeichnis beschreibbar";
+        };
+    }
+
+    /**
+     * Baut die deutsche Zusammenfassungsmeldung des Gesamttests.
+     *
+     * @param total            Gesamtzahl der Prüfpunkte
+     * @param successCount     Anzahl der erfolgreichen Prüfpunkte
+     * @param errorCount       Anzahl der fehlgeschlagenen Prüfpunkte (Schweregrad ERROR)
+     * @param warningCount     Anzahl der Warnungs-Prüfpunkte
+     * @param notApplicable    Anzahl der nicht-anwendbaren Prüfpunkte
+     * @return deutsche Zusammenfassungsmeldung; nie {@code null}
+     */
+    private static String buildSummaryMessage(long total, long successCount, long errorCount,
+                                               long warningCount, long notApplicable) {
+        long findings = errorCount + warningCount;
+        String base = "Gesamttest abgeschlossen. " + total + " Prüfpunkte: "
+                + successCount + " Erfolg, "
+                + errorCount + " Fehler, "
+                + warningCount + " Warnung, "
+                + notApplicable + " nicht anwendbar.";
+        if (findings == 0) {
+            return base + " Keine Befunde.";
+        }
+        return base;
+    }
+
+    /**
+     * Gibt eine unveränderliche Momentaufnahme der aktuell ausstehenden Nachrichten zurück.
+     * <p>
+     * Ausschließlich für Tests gedacht.
+     *
+     * @return unveränderliche Kopie der Nachrichtenliste; nie {@code null}
+     */
+    public List<GuiMessageEntry> pendingMessagesSnapshot() {
+        return List.copyOf(pendingMessages);
+    }
+}
@@ -0,0 +1,296 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+/**
+ * Zentrale Konstantenklasse für alle Tooltip-Texte der GUI.
+ * <p>
+ * Diese Klasse ist die einzige autoritative Quelle für Tooltip-Beschriftungen aller
+ * interaktiven Elemente in der Desktop-Oberfläche. Alle Tooltip-Strings werden hier
+ * definiert und von den jeweiligen UI-Klassen referenziert. Streustrings im
+ * UI-Code sind unzulässig.
+ * <p>
+ * Tooltip-Texte für Status-Icons werden <em>nicht</em> hier gepflegt – sie stammen
+ * ausschließlich aus {@link de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.ProcessingStatusPresentation},
+ * die die autoritative Quelle für alle statusbezogenen Darstellungsinformationen ist.
+ * <p>
+ * Alle Texte sind deutschsprachig gemäß Spezifikation.
+ * Diese Klasse enthält keine JavaFX-Typen und ist nicht instanziierbar.
+ */
+public final class GuiTooltipTexts {
+
+    // -------------------------------------------------------------------------
+    // Toolbar-Buttons
+    // -------------------------------------------------------------------------
+
+    /** Tooltip für den Button „Neu". */
+    public static final String TOOLBAR_NEU =
+            "Neue Konfiguration erstellen.";
+
+    /** Tooltip für den Button „Öffnen". */
+    public static final String TOOLBAR_OEFFNEN =
+            "Bestehende Konfigurationsdatei (.properties) öffnen.";
+
+    /** Tooltip für den Button „Speichern". */
+    public static final String TOOLBAR_SPEICHERN =
+            "Aktuelle Konfiguration speichern.";
+
+    /** Tooltip für den Button „Speichern unter". */
+    public static final String TOOLBAR_SPEICHERN_UNTER =
+            "Konfiguration unter neuem Dateipfad speichern.";
+
+    /** Tooltip für den Button „Validieren". */
+    public static final String TOOLBAR_VALIDIEREN =
+            "Aktuelle Eingaben auf Vollständigkeit und Korrektheit prüfen.";
+
+    /** Tooltip für den Button „Technische Tests ausführen". */
+    public static final String TOOLBAR_TECHNISCHE_TESTS =
+            "Dateipfade, Datenbankverbindung und KI-Erreichbarkeit prüfen.";
+
+    // -------------------------------------------------------------------------
+    // Konfigurationstab – Pfade
+    // -------------------------------------------------------------------------
+
+    /** Tooltip für das Eingabefeld „Quellordner". */
+    public static final String PFADE_QUELLORDNER =
+            "Ordner mit den zu verarbeitenden PDF-Dateien. Inhalt wird nicht verändert.";
+
+    /** Tooltip für das Eingabefeld „Zielordner". */
+    public static final String PFADE_ZIELORDNER =
+            "Ordner für die umbenannten Kopien.";
+
+    /** Tooltip für das Eingabefeld „SQLite-Datei". */
+    public static final String PFADE_SQLITE =
+            "Datenbank für Verarbeitungsergebnisse und Datei-Historie.";
+
+    /** Tooltip für das Eingabefeld „Prompt-Datei". */
+    public static final String PFADE_PROMPT =
+            "Externe Textdatei mit den KI-Anweisungen.";
+
+    /** Tooltip für das Eingabefeld „Lock-Datei". */
+    public static final String PFADE_LOCK_DATEI =
+            "Pfad zur Lock-Datei, die parallele Instanzen verhindert (optional).";
+
+    /** Tooltip für das Eingabefeld „Log-Verzeichnis". */
+    public static final String PFADE_LOG_VERZEICHNIS =
+            "Verzeichnis für Log-Dateien. Leer = Standardverzeichnis logs/ im Programmverzeichnis.";
+
+    // -------------------------------------------------------------------------
+    // Konfigurationstab – Provider
+    // -------------------------------------------------------------------------
+
+    /** Tooltip für die Provider-ComboBox. */
+    public static final String PROVIDER_COMBOBOX =
+            "Der KI-Dienst, der die Dateinamen generiert.";
+
+    /** Tooltip für das Modell-Eingabefeld (ComboBox oder manuelles TextField). */
+    public static final String PROVIDER_MODELL =
+            "Das konkrete Sprachmodell des gewählten Providers.";
+
+    /** Tooltip für das Eingabefeld „Basis-URL". */
+    public static final String PROVIDER_BASIS_URL =
+            "Basis-URL des KI-Dienstes (z. B. https://api.openai.com/v1).";
+
+    /** Tooltip für das Eingabefeld „Timeout". */
+    public static final String PROVIDER_TIMEOUT =
+            "Zeitlimit für KI-Anfragen in Sekunden.";
+
+    /** Tooltip für das Eingabefeld „API-Key". */
+    public static final String PROVIDER_API_KEY =
+            "API-Schlüssel für den konfigurierten KI-Dienst. Umgebungsvariable hat Vorrang.";
+
+    // -------------------------------------------------------------------------
+    // Konfigurationstab – Verarbeitungslimits
+    // -------------------------------------------------------------------------
+
+    /** Tooltip für das Eingabefeld „max.text.characters". */
+    public static final String LIMITS_MAX_TEXT_CHARACTERS =
+            "Maximale Zeichenzahl aus dem PDF-Text. Höhere Werte = mehr Kontext, höhere Kosten.";
+
+    /** Tooltip für das Eingabefeld „max.pages". */
+    public static final String LIMITS_MAX_PAGES =
+            "Maximale Seitenzahl, die aus einem PDF gelesen wird.";
+
+    /** Tooltip für das Eingabefeld „max.title.length". */
+    public static final String LIMITS_MAX_TITLE_LENGTH =
+            "Maximale Länge des Dateinamens in Zeichen (ohne Datum und Erweiterung). Gültig: 10–120.";
+
+    /** Tooltip für das Eingabefeld „max.retries.transient". */
+    public static final String LIMITS_MAX_RETRIES =
+            "Maximale Anzahl transienter Wiederholversuche je Dokument (Ganzzahl ≥ 1).";
+
+    /** Tooltip für das Eingabefeld „Log-Level". */
+    public static final String LIMITS_LOG_LEVEL =
+            "Log-Detailstufe (z. B. INFO, DEBUG, WARN). Leer = Standardwert INFO.";
+
+    /** Tooltip für die Checkbox „Sensible KI-Ausgabe". */
+    public static final String LIMITS_SENSIBLE_KI_AUSGABE =
+            "Vollständige KI-Antworten in die Log-Datei schreiben (nur für Diagnosezwecke empfohlen).";
+
+    // -------------------------------------------------------------------------
+    // Verarbeitungslauf-Tab – Dateiname-Editor
+    // -------------------------------------------------------------------------
+
+    /** Tooltip für das Dateiname-Textfeld im Dateiname-Editor. */
+    public static final String DATEINAME_TEXTFELD =
+            "Dateiname bearbeiten. Format: JJJJ-MM-TT - Titel.pdf";
+
+    /** Tooltip für den Button „Dateiname übernehmen". */
+    public static final String DATEINAME_UEBERNEHMEN =
+            "Benennt die Zieldatei um und aktualisiert die Datenbank. Nicht rückgängig zu machen.";
+
+    /** Tooltip für den Button „Zurücksetzen auf KI-Vorschlag". */
+    public static final String DATEINAME_ZURUECKSETZEN =
+            "Stellt den KI-generierten Namen wieder her, ohne zu speichern.";
+
+    // -------------------------------------------------------------------------
+    // Verarbeitungslauf-Tab – Laufsteuerung und Tabelle
+    // -------------------------------------------------------------------------
+
+    /** Tooltip für den Button „Starten". */
+    public static final String BATCHRUN_STARTEN =
+            "Verarbeitungslauf starten: alle ausstehenden PDF-Dateien aus dem Quellordner verarbeiten.";
+
+    /** Tooltip für den Button „Abbrechen". */
+    public static final String BATCHRUN_ABBRECHEN =
+            "Laufenden Verarbeitungslauf abbrechen. Bereits abgeschlossene Dateien bleiben gespeichert.";
+
+    /** Tooltip für den Button „Erneut verarbeiten". */
+    public static final String BATCHRUN_ERNEUT_VERARBEITEN =
+            "Markierte Einträge erneut zur Verarbeitung freigeben (setzt Status auf READY_FOR_AI).";
+
+    /** Tooltip für den Button „Status zurücksetzen" im Verarbeitungslauf-Tab. */
+    public static final String BATCHRUN_STATUS_ZURUECKSETZEN =
+            "Status der markierten Einträge zurücksetzen, damit sie beim nächsten Lauf verarbeitet werden.";
+
+    /** Tooltip für die Master-Checkbox im Tabellenkopf des Verarbeitungslauf-Tabs. */
+    public static final String BATCHRUN_MASTER_CHECKBOX =
+            "Alle sichtbaren Einträge markieren oder Markierung aufheben.";
+
+    /** Tooltip für den Meldungsbereich im Verarbeitungslauf-Tab. */
+    public static final String BATCHRUN_MESSAGE_AREA =
+            "Statusmeldungen und Fortschrittsinformationen des aktuellen Verarbeitungslaufs.";
+
+    /** Tooltip für den Navigations-Button „Vorherige Seite" in der PDF-Vorschau. */
+    public static final String PREVIEW_VORHERIGE_SEITE =
+            "Vorherige Seite der Vorschau anzeigen.";
+
+    /** Tooltip für den Navigations-Button „Nächste Seite" in der PDF-Vorschau. */
+    public static final String PREVIEW_NAECHSTE_SEITE =
+            "Nächste Seite der Vorschau anzeigen.";
+
+    /** Tooltip für Spalte „Status" in der Verarbeitungslauf-Tabelle. */
+    public static final String BATCHRUN_COL_STATUS =
+            "Verarbeitungsergebnis: Erfolg, Fehler oder übersprungen.";
+
+    /** Tooltip für Spalte „Originaldateiname" in der Verarbeitungslauf-Tabelle. */
+    public static final String BATCHRUN_COL_ORIGINALDATEINAME =
+            "Ursprünglicher Dateiname der verarbeiteten PDF-Datei.";
+
+    /** Tooltip für Spalte „Neuer Dateiname" in der Verarbeitungslauf-Tabelle. */
+    public static final String BATCHRUN_COL_NEUER_DATEINAME =
+            "Von der KI vorgeschlagener, normierter Dateiname.";
+
+    /** Tooltip für Spalte „Datum" in der Verarbeitungslauf-Tabelle. */
+    public static final String BATCHRUN_COL_DATUM =
+            "Datum des Dokuments laut KI-Analyse.";
+
+    /** Tooltip für Spalte „Dauer" in der Verarbeitungslauf-Tabelle. */
+    public static final String BATCHRUN_COL_DAUER =
+            "Verarbeitungsdauer für diese Datei.";
+
+    // -------------------------------------------------------------------------
+    // Verlauf-Tab – Detailbereich
+    // -------------------------------------------------------------------------
+
+    /** Tooltip für den KI-Begründungs-Bereich im Verlauf-Tab. */
+    public static final String VERLAUF_REASONING_AREA =
+            "KI-Begründung des ausgewählten Verarbeitungsversuchs.";
+
+    /** Tooltip für den Fehlerursachen-Bereich im Verlauf-Tab. */
+    public static final String VERLAUF_FAILURE_AREA =
+            "Fehlermeldung des letzten Fehler-Versuchs für dieses Dokument.";
+
+    /** Tooltip für Spalte „Status" in der Übersichtstabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_COL_STATUS =
+            "Aktueller Gesamtstatus des Dokuments.";
+
+    /** Tooltip für Spalte „Quelldatei" in der Übersichtstabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_COL_QUELLDATEI =
+            "Ursprünglicher Dateiname der PDF-Quelldatei.";
+
+    /** Tooltip für Spalte „Zieldatei" in der Übersichtstabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_COL_ZIELDATEI =
+            "Vom System erzeugter, normierter Dateiname im Zielordner.";
+
+    /** Tooltip für Spalte „Letzter Versuch" in der Übersichtstabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_COL_LETZTER_VERSUCH =
+            "Zeitpunkt des zuletzt abgeschlossenen Verarbeitungsversuchs.";
+
+    /** Tooltip für Spalte „Versuche" in der Übersichtstabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_COL_VERSUCHE =
+            "Gesamtanzahl der Verarbeitungsversuche für dieses Dokument.";
+
+    /** Tooltip für Spalte „#" in der Versuche-Tabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_VERSUCHE_COL_NR =
+            "Laufende Nummer des Verarbeitungsversuchs.";
+
+    /** Tooltip für Spalte „Datum" in der Versuche-Tabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_VERSUCHE_COL_DATUM =
+            "Endzeitpunkt dieses Verarbeitungsversuchs.";
+
+    /** Tooltip für Spalte „Status" in der Versuche-Tabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_VERSUCHE_COL_STATUS =
+            "Ergebnis dieses Verarbeitungsversuchs.";
+
+    /** Tooltip für Spalte „Provider" in der Versuche-Tabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_VERSUCHE_COL_PROVIDER =
+            "KI-Provider, der für diesen Versuch verwendet wurde.";
+
+    /** Tooltip für Spalte „Modell" in der Versuche-Tabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_VERSUCHE_COL_MODELL =
+            "Konkretes Sprachmodell, das für diesen Versuch verwendet wurde.";
+
+    /** Tooltip für Spalte „Vorgeschlagener Name" in der Versuche-Tabelle des Verlauf-Tabs. */
+    public static final String VERLAUF_VERSUCHE_COL_VORGESCHLAGENER_NAME =
+            "Vom System erzeugter Zieldateiname für diesen Versuch.";
+
+    // -------------------------------------------------------------------------
+    // Konfigurations-Tab – Meldungsbereich und Modell-Neu-Laden
+    // -------------------------------------------------------------------------
+
+    /** Tooltip für den Button „Meldungen leeren". */
+    public static final String TOOLBAR_MELDUNGEN_LEEREN =
+            "Alle Meldungen im Meldungsbereich entfernen.";
+
+    /** Tooltip für den Button „Modelle neu laden". */
+    public static final String PROVIDER_MODELLE_NEU_LADEN =
+            "Verfügbare Modelle vom konfigurierten Provider neu abrufen.";
+
+    /** Tooltip für den Ordner-/Datei-Browser-Button. */
+    public static final String PFADE_BROWSER_BUTTON =
+            "Ordner oder Datei über den Datei-Dialog auswählen.";
+
+    // -------------------------------------------------------------------------
+    // Prompt-Tab – Textbereich
+    // -------------------------------------------------------------------------
+
+    /** Tooltip für den Prompt-Textbereich im Prompt-Editor-Tab. */
+    public static final String PROMPT_TEXTAREA =
+            "KI-Anweisungstext. Dieser Prompt wird bei jedem Verarbeitungsversuch an das Sprachmodell gesendet.";
+
+    /** Tooltip für den Button „Speichern" im Prompt-Editor-Tab. */
+    public static final String PROMPT_SPEICHERN =
+            "Prompt-Datei speichern (atomar, UTF-8).";
+
+    /** Tooltip für den Button „Auf Standard zurücksetzen" im Prompt-Editor-Tab. */
+    public static final String PROMPT_ZURUECKSETZEN =
+            "Textfeld mit dem Standard-Prompt-Inhalt befüllen, ohne zu speichern.";
+
+    /** Tooltip für den Button „Standard-Prompt erstellen" im Prompt-Editor-Tab. */
+    public static final String PROMPT_STANDARD_ANLEGEN =
+            "Standard-Prompt-Datei am konfigurierten Pfad anlegen.";
+
+    /** Nicht instanziierbar – reine Konstantenklasse. */
+    private GuiTooltipTexts() {
+        throw new UnsupportedOperationException("Nicht instanziierbar");
+    }
+}
@@ -0,0 +1,87 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.util.function.Function;
+
+/**
+ * Mediates the three-way protection dialog before any action that would discard unsaved changes.
+ * <p>
+ * The guard asks the user whether to save, discard or cancel the requested action.
+ * The dialog interaction is injected via a {@link Function} so the guard can be tested
+ * without a running JavaFX scene by substituting the real dialog with a stub.
+ *
+ * <p>Usage:
+ * <ol>
+ *   <li>Obtain an instance from the workspace.</li>
+ *   <li>Call {@link #askAndProceed(String, Runnable, Runnable)} with the intended follow-up action.</li>
+ *   <li>The guard shows the dialog when the editor is dirty and runs the follow-up only when
+ *       it is safe to proceed.</li>
+ * </ol>
+ */
+public final class GuiUnsavedChangesGuard {
+
+    /**
+     * The possible responses the user can give to the protection dialog.
+     */
+    public enum Choice {
+        /** Save the current changes and then continue with the requested action. */
+        SAVE,
+        /** Discard all unsaved changes and continue with the requested action. */
+        DISCARD,
+        /** Cancel the requested action; no state change is performed. */
+        CANCEL
+    }
+
+    /**
+     * Supplies the user's choice for a given trigger label.
+     * <p>
+     * In production the function shows a modal dialog; in tests it can be replaced with a stub.
+     */
+    private Function<String, Choice> dialogSupplier;
+
+    /**
+     * Creates a guard that delegates the dialog interaction to the supplied function.
+     *
+     * @param dialogSupplier function that maps a trigger label to the user's choice; must not be {@code null}
+     */
+    public GuiUnsavedChangesGuard(Function<String, Choice> dialogSupplier) {
+        this.dialogSupplier = dialogSupplier;
+    }
+
+    /**
+     * Replaces the dialog supplier at runtime.
+     * <p>
+     * Package-private so tests can inject stubs without exposing setter to external callers.
+     *
+     * @param dialogSupplier the replacement function; must not be {@code null}
+     */
+    void setDialogSupplier(Function<String, Choice> dialogSupplier) {
+        this.dialogSupplier = dialogSupplier;
+    }
+
+    /**
+     * Asks the user how to handle unsaved changes before the named action and invokes the
+     * appropriate callback.
+     *
+     * <ul>
+     *   <li>{@link Choice#SAVE} → {@code onSave} is called; the caller must invoke
+     *       {@code onProceed} itself after a successful save.</li>
+     *   <li>{@link Choice#DISCARD} → {@code onProceed} is called immediately.</li>
+     *   <li>{@link Choice#CANCEL} → neither callback is called.</li>
+     * </ul>
+     *
+     * @param triggerLabel a short label identifying the triggering action (e.g. "Neu", "Öffnen");
+     *                     used to give the dialog context; must not be {@code null}
+     * @param onProceed    action to run when the user chose discard; must not be {@code null}
+     * @param onSave       action to run when the user chose save; must not be {@code null}
+     */
+    public void askAndProceed(String triggerLabel, Runnable onProceed, Runnable onSave) {
+        Choice choice = dialogSupplier.apply(triggerLabel);
+        switch (choice) {
+            case SAVE -> onSave.run();
+            case DISCARD -> onProceed.run();
+            case CANCEL -> {
+                // No action – caller keeps the current state.
+            }
+        }
+    }
+}
@@ -0,0 +1,68 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiChangeState;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiConfigurationEditorState;
+
+/**
+ * Formats the window title string for the PDF-Umbenenner GUI editor.
+ * <p>
+ * The title reflects the current editor state: whether a file is loaded and whether the
+ * editor contains unsaved changes. The application name and the separator are kept in
+ * one place so every part of the GUI uses the same formatting convention.
+ *
+ * <ul>
+ *   <li>Clean state with loaded file: {@code "PDF-Umbenenner — <filename>"}</li>
+ *   <li>Clean state without file (new configuration): {@code "PDF-Umbenenner — Neue Konfiguration"}</li>
+ *   <li>Dirty state: the same formats with a leading {@code "* "} prefix</li>
+ * </ul>
+ */
+public final class GuiWindowTitleFormatter {
+
+    /** The application name shown in every window title variant. */
+    static final String APPLICATION_NAME = "PDF-Umbenenner";
+
+    /** Separator placed between the application name and the context section. */
+    static final String SEPARATOR = " \u2014 ";
+
+    /** Prefix added to the title when the editor contains unsaved changes. */
+    static final String DIRTY_PREFIX = "* ";
+
+    /** Context label used when no file has been loaded yet. */
+    static final String NEW_CONFIGURATION_LABEL = "Neue Konfiguration";
+
+    private GuiWindowTitleFormatter() {
+        // Utility class.
+    }
+
+    /**
+     * Formats the window title for the given editor state.
+     *
+     * @param editorState the current editor state; must not be {@code null}
+     * @return the formatted window title string; never {@code null}
+     */
+    public static String format(GuiConfigurationEditorState editorState) {
+        String contextPart = buildContextPart(editorState);
+        String base = APPLICATION_NAME + SEPARATOR + contextPart;
+        if (editorState.changeState() == GuiChangeState.DIRTY) {
+            return DIRTY_PREFIX + base;
+        }
+        return base;
+    }
+
+    /**
+     * Returns the context portion of the title (the part after the separator).
+     *
+     * @param editorState the current editor state; must not be {@code null}
+     * @return the context string; never {@code null}
+     */
+    private static String buildContextPart(GuiConfigurationEditorState editorState) {
+        if (editorState.isNewConfiguration()) {
+            return NEW_CONFIGURATION_LABEL;
+        }
+        String fullPath = editorState.loadedFileSnapshot()
+                .map(snapshot -> snapshot.filePath().getFileName())
+                .map(Object::toString)
+                .orElse(NEW_CONFIGURATION_LABEL);
+        return fullPath;
+    }
+}
@@ -0,0 +1,247 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import javafx.application.Application;
+import javafx.application.Platform;
+import javafx.event.EventHandler;
+import javafx.scene.Scene;
+import javafx.scene.control.Alert;
+import javafx.scene.control.Menu;
+import javafx.scene.control.MenuBar;
+import javafx.scene.control.MenuItem;
+import javafx.scene.image.Image;
+import javafx.scene.layout.BorderPane;
+import javafx.stage.Stage;
+import javafx.stage.WindowEvent;
+
+/**
+ * JavaFX application entry point for the PDF-Umbenenner GUI inbound adapter.
+ * <p>
+ * The application starts the editor shell in a clean, unloaded state unless Bootstrap
+ * has provided a preloaded startup context. The visible editor surface is delegated to
+ * {@link GuiConfigurationEditorWorkspace}.
+ *
+ * <p>The window title is kept in sync with the workspace's dirty state via the
+ * {@code titleUpdateListener} hook. The close-request handler is installed through
+ * {@link GuiConfigurationEditorWorkspace#installCloseRequestHandler(Stage)} so that
+ * unsaved changes are protected when the user tries to close the window.
+ *
+ * <p>Beim Schließen des Fensters wird die Anwendung in den Windows System-Tray minimiert.
+ * Über das Tray-Kontextmenü kann das Fenster wieder geöffnet oder die Anwendung beendet werden.
+ *
+ * <p>Nach dem Anzeigen des Hauptfensters startet eine zentrale {@link GuiStatusRefreshTimeline}
+ * (1 Hz), die den aktuellen Scheduler-Status liest und alle betroffenen Tabs aktualisiert.
+ * Die Timeline wird beim Beenden der Anwendung gestoppt.
+ */
+public class PdfUmbenennerGuiApplication extends Application {
+
+    private static final Logger LOG = LogManager.getLogger(PdfUmbenennerGuiApplication.class);
+    private static final double DEFAULT_WIDTH = 1100;
+    private static final double DEFAULT_HEIGHT = 800;
+
+    private SystemTrayManager trayManager;
+    private GuiConfigurationEditorWorkspace workspace;
+    private GuiStartupContext guiStartupContext;
+    private GuiStatusRefreshTimeline refreshTimeline;
+
+    /**
+     * Creates a new instance of the JavaFX application.
+     */
+    public PdfUmbenennerGuiApplication() {
+        // Required by JavaFX runtime for reflective instantiation.
+    }
+
+    /**
+     * Initializes and shows the primary stage.
+     * <p>
+     * Lädt die Anwendungs-Icons in allen verfügbaren Größen und setzt sie am Fenster.
+     * Wires the workspace title-update listener to the stage title so any dirty-state change
+     * causes an immediate window-title refresh. Installs the close-request handler that
+     * guards unsaved changes and minimizes the window to the system tray instead of closing.
+     * <p>
+     * Startet nach dem Anzeigen des Fensters die zentrale Status-Refresh-Timeline.
+     *
+     * @param primaryStage the primary stage provided by the JavaFX runtime; never {@code null}
+     */
+    @Override
+    public void start(Stage primaryStage) {
+        LOG.info("GUI: JavaFX-Oberfläche wird initialisiert.");
+
+        // Anwendungs-Icons laden; JavaFX wählt je nach Kontext automatisch die passende Größe
+        primaryStage.getIcons().addAll(
+                new Image(getClass().getResourceAsStream("/icons/Icon16.png")),
+                new Image(getClass().getResourceAsStream("/icons/Icon32.png")),
+                new Image(getClass().getResourceAsStream("/icons/Icon64.png")),
+                new Image(getClass().getResourceAsStream("/icons/Icon128.png"))
+        );
+
+        guiStartupContext = GuiStartupContextHolder.currentOrBlank();
+        workspace = new GuiConfigurationEditorWorkspace(guiStartupContext);
+
+        // Wire the title-update listener so the stage title stays in sync with the dirty state.
+        workspace.titleUpdateListener = primaryStage::setTitle;
+
+        // Statuszeile anlegen und mit dem Workspace verdrahten
+        GuiStatusBar statusBar = new GuiStatusBar(guiStartupContext.applicationVersion());
+        workspace.statusBarStateListener = statusBar::applyEditorState;
+
+        // Menüleiste mit Datenbank-Menü („Neue Datenbank anlegen…")
+        MenuBar menuBar = buildMenuBar(workspace);
+
+        // Statuszeile unterhalb des Workspace-Inhalts einbetten
+        BorderPane outerLayout = new BorderPane();
+        outerLayout.setTop(menuBar);
+        outerLayout.setCenter(workspace.root());
+        outerLayout.setBottom(statusBar.root());
+
+        Scene scene = new Scene(outerLayout, DEFAULT_WIDTH, DEFAULT_HEIGHT);
+        primaryStage.setTitle(GuiWindowTitleFormatter.format(workspace.editorState()));
+        primaryStage.setScene(scene);
+
+        // Install the close-request handler that protects unsaved changes.
+        workspace.installCloseRequestHandler(primaryStage);
+
+        // System-Tray aktivieren: JavaFX-Runtime nicht beenden wenn Fenster versteckt wird
+        Platform.setImplicitExit(false);
+        trayManager = new SystemTrayManager(primaryStage);
+        if (trayManager.install()) {
+            installTrayCloseHandler(primaryStage, workspace);
+        }
+
+        // Scheduler-Close-Guard als äußerste Schicht: verhindert Beenden während Scheduler aktiv
+        installSchedulerCloseGuard(primaryStage);
+
+        primaryStage.setMaximized(true);
+        primaryStage.show();
+
+        // Versuche, die zuletzt geladene Konfigurationsdatei automatisch zu laden.
+        workspace.autoLoadLastConfiguration();
+
+        // Zentrale Status-Refresh-Timeline starten (1 Hz)
+        refreshTimeline = new GuiStatusRefreshTimeline(
+                guiStartupContext.schedulerControlUseCase(),
+                this::refreshAllTabStates);
+        refreshTimeline.start();
+
+        LOG.info("GUI: Hauptfenster erfolgreich angezeigt.");
+    }
+
+    /**
+     * Called by the JavaFX runtime when the application is stopping.
+     * <p>
+     * Stoppt die Status-Refresh-Timeline, entfernt das System-Tray-Icon und loggt das Beenden.
+     */
+    @Override
+    public void stop() {
+        LOG.info("GUI: JavaFX-Anwendung wird beendet.");
+        if (refreshTimeline != null) {
+            refreshTimeline.stop();
+        }
+        if (trayManager != null) {
+            trayManager.remove();
+        }
+    }
+
+    /**
+     * Liest den aktuellen Scheduler-Status und aktualisiert alle betroffenen Tabs.
+     * <p>
+     * Wird von der {@link GuiStatusRefreshTimeline} im Sekundentakt auf dem JavaFX
+     * Application Thread aufgerufen. Wenn kein {@link SchedulerControlUseCase} vorhanden
+     * ist, wird der Aufruf ohne Fehler übersprungen.
+     */
+    private void refreshAllTabStates() {
+        // Den Use Case nicht aus dem unveränderlichen GuiStartupContext lesen, sondern
+        // den zur Laufzeit (z. B. durch Auto-Load) verdrahteten Use Case verwenden.
+        // Andernfalls bliebe der Stop-Button dauerhaft deaktiviert, weil updateStatus
+        // nie aufgerufen würde.
+        workspace.refreshSchedulerStatus();
+    }
+
+    /**
+     * Baut die Menüleiste für das Hauptfenster auf.
+     * <p>
+     * Aktuell enthält sie genau einen Eintrag: das Menü „Datenbank" mit der Aktion
+     * „Neue Datenbank anlegen…". Diese delegiert an
+     * {@link GuiConfigurationEditorWorkspace#requestCreateNewDatabase()}.
+     * <p>
+     * Der Menüpunkt ist deaktiviert, solange ein Verarbeitungslauf aktiv ist oder
+     * bereits eine DB-Anlage läuft. Die Reaktivierung erfolgt automatisch, sobald
+     * der Workspace die DB-Busy-Sperre wieder aufhebt.
+     *
+     * @param workspace der Workspace, an den die Aktionen delegieren; nie {@code null}
+     * @return die fertig konfigurierte Menüleiste
+     */
+    private MenuBar buildMenuBar(GuiConfigurationEditorWorkspace workspace) {
+        Menu databaseMenu = new Menu("Datenbank");
+        MenuItem createNewItem = new MenuItem("Neue Datenbank anlegen…");
+        createNewItem.setOnAction(event -> workspace.requestCreateNewDatabase());
+        // Sperre während eines aktiven Verarbeitungslaufs oder einer laufenden DB-Anlage
+        createNewItem.disableProperty().bind(workspace.batchRunRunningProperty()
+                .or(workspace.dbBusyForDatabaseCreationProperty()));
+        databaseMenu.getItems().add(createNewItem);
+        return new MenuBar(databaseMenu);
+    }
+
+    /**
+     * Legt den Scheduler-Close-Guard als äußerste Schicht des Close-Request-Handlers an.
+     * <p>
+     * Ist kein {@link de.gecheckt.pdf.umbenenner.application.port.in.SchedulerControlUseCase}
+     * vorhanden, bleibt der bestehende Handler unverändert. Ist der Scheduler aktiv
+     * (Zustand != {@code STOPPED}), wird das Schließen verhindert und ein
+     * Informationsdialog angezeigt. Ist der Scheduler gestoppt, wird der bisherige
+     * Handler (SystemTray + Workspace-Dirty-Guard) aufgerufen.
+     *
+     * @param stage das primäre Fenster; darf nicht {@code null} sein
+     */
+    private void installSchedulerCloseGuard(Stage stage) {
+        EventHandler<WindowEvent> existingHandler = stage.getOnCloseRequest();
+        stage.setOnCloseRequest(event -> {
+            // Use Case dynamisch über den Workspace lesen, weil der Scheduler erst
+            // nach erfolgreichem Datei-Öffnen (z. B. Auto-Load) verdrahtet wird und
+            // damit nicht zwingend im unveränderlichen GuiStartupContext steht.
+            if (workspace.isSchedulerActive()) {
+                event.consume();
+                Alert alert = new Alert(Alert.AlertType.INFORMATION);
+                alert.setTitle("Anwendung kann nicht beendet werden");
+                alert.setHeaderText(null);
+                alert.setContentText(
+                        "Ein Lauf ist aktiv oder der Scheduler läuft.\n"
+                        + "Bitte beende den Scheduler bzw. warte auf das Ende des Laufs.");
+                alert.showAndWait();
+                return;
+            }
+            if (existingHandler != null) {
+                existingHandler.handle(event);
+            }
+        });
+    }
+
+    /**
+     * Legt einen Close-Request-Handler an, der bei sauberem Zustand das Fenster in den
+     * System-Tray minimiert statt es zu schließen.
+     * <p>
+     * Der vom Workspace installierte Handler wird dabei vorrangig aufgerufen. Nur wenn
+     * er das Event nicht konsumiert (sauberer Zustand, keine laufenden Operationen),
+     * greift dieser Handler und versteckt das Fenster.
+     *
+     * @param stage     das primäre Fenster
+     * @param workspace der Workspace-Handler, der bereits installiert wurde
+     */
+    private void installTrayCloseHandler(Stage stage, GuiConfigurationEditorWorkspace workspace) {
+        EventHandler<WindowEvent> workspaceHandler = stage.getOnCloseRequest();
+        stage.setOnCloseRequest(event -> {
+            // Workspace-Handler zuerst: prüft Dirty-State, laufende Operationen usw.
+            if (workspaceHandler != null) {
+                workspaceHandler.handle(event);
+            }
+            // Wurde das Event nicht konsumiert, ist der Zustand sauber: Fenster in Tray verstecken
+            if (!event.isConsumed()) {
+                event.consume();
+                LOG.info("GUI: Fenster wird in den System-Tray minimiert.");
+                stage.hide();
+            }
+        });
+    }
+}
@@ -0,0 +1,137 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui;
+
+import java.awt.AWTException;
+import java.awt.MenuItem;
+import java.awt.PopupMenu;
+import java.awt.SystemTray;
+import java.awt.TrayIcon;
+import java.awt.image.BufferedImage;
+import java.io.IOException;
+import java.io.InputStream;
+
+import javax.imageio.ImageIO;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import javafx.application.Platform;
+import javafx.stage.Stage;
+
+/**
+ * Verwaltet das Windows System-Tray-Icon für den PDF-Umbenenner.
+ * <p>
+ * Wird das Hauptfenster geschlossen, bleibt die Anwendung im Hintergrund aktiv und zeigt
+ * ein Tray-Icon in der Windows-Taskleiste. Über das Kontextmenü kann das Fenster wieder
+ * geöffnet oder die Anwendung vollständig beendet werden.
+ * <p>
+ * Alle Stage-Operationen werden auf dem JavaFX Application Thread ausgeführt, da AWT-Events
+ * auf dem AWT Event Dispatch Thread eintreffen.
+ */
+class SystemTrayManager {
+
+    private static final Logger LOG = LogManager.getLogger(SystemTrayManager.class);
+
+    private final Stage stage;
+    private TrayIcon trayIcon;
+    private boolean installed;
+
+    /**
+     * Erstellt einen neuen {@code SystemTrayManager} für die angegebene Stage.
+     *
+     * @param stage das primäre Fenster; darf nicht {@code null} sein
+     */
+    SystemTrayManager(Stage stage) {
+        this.stage = stage;
+    }
+
+    /**
+     * Installiert das System-Tray-Icon.
+     * <p>
+     * Schlägt die Installation fehl (System-Tray nicht unterstützt oder Icon-Bild nicht ladbar),
+     * wird {@code false} zurückgegeben und kein Tray-Icon angezeigt.
+     *
+     * @return {@code true} wenn das Icon erfolgreich installiert wurde, sonst {@code false}
+     */
+    boolean install() {
+        if (!SystemTray.isSupported()) {
+            LOG.warn("GUI: System-Tray wird auf diesem System nicht unterstützt.");
+            return false;
+        }
+        BufferedImage image = loadTrayImage();
+        if (image == null) {
+            return false;
+        }
+        PopupMenu menu = buildContextMenu();
+        trayIcon = new TrayIcon(image, "PDF-Umbenenner", menu);
+        trayIcon.setImageAutoSize(true);
+        // Doppelklick öffnet das Fenster
+        trayIcon.addActionListener(e -> Platform.runLater(this::showWindow));
+        try {
+            SystemTray.getSystemTray().add(trayIcon);
+            installed = true;
+            LOG.info("GUI: System-Tray-Icon erfolgreich installiert.");
+            return true;
+        } catch (AWTException e) {
+            LOG.warn("GUI: System-Tray-Icon konnte nicht installiert werden: {}", e.getMessage(), e);
+            return false;
+        }
+    }
+
+    /**
+     * Entfernt das Tray-Icon aus dem System-Tray.
+     * Ist kein Icon installiert, wird der Aufruf ignoriert.
+     */
+    void remove() {
+        if (installed && trayIcon != null) {
+            SystemTray.getSystemTray().remove(trayIcon);
+            installed = false;
+            LOG.info("GUI: System-Tray-Icon entfernt.");
+        }
+    }
+
+    /**
+     * Gibt an, ob das Tray-Icon aktiv installiert ist.
+     *
+     * @return {@code true} wenn das Icon im System-Tray sichtbar ist
+     */
+    boolean isInstalled() {
+        return installed;
+    }
+
+    private BufferedImage loadTrayImage() {
+        try (InputStream stream = getClass().getResourceAsStream("/icons/Icon16.png")) {
+            if (stream == null) {
+                LOG.warn("GUI: Tray-Icon-Ressource '/icons/Icon16.png' nicht gefunden.");
+                return null;
+            }
+            return ImageIO.read(stream);
+        } catch (IOException e) {
+            LOG.warn("GUI: Tray-Icon-Bild konnte nicht geladen werden: {}", e.getMessage(), e);
+            return null;
+        }
+    }
+
+    private PopupMenu buildContextMenu() {
+        PopupMenu menu = new PopupMenu();
+
+        MenuItem openItem = new MenuItem("Öffnen");
+        openItem.addActionListener(e -> Platform.runLater(this::showWindow));
+
+        MenuItem exitItem = new MenuItem("Beenden");
+        exitItem.addActionListener(e -> {
+            remove();
+            Platform.exit();
+            System.exit(0);
+        });
+
+        menu.add(openItem);
+        menu.addSeparator();
+        menu.add(exitItem);
+        return menu;
+    }
+
+    private void showWindow() {
+        stage.show();
+        stage.toFront();
+    }
+}
@@ -0,0 +1,119 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+/**
+ * Übersetzt strukturierte Fehlermeldungen aus der Anwendungsschicht in
+ * benutzerfreundliche deutsche Texte für die Darstellungsschicht der GUI.
+ * <p>
+ * Die Klasse wertet die englischsprachige Fehlermeldung aus dem Verarbeitungsversuch
+ * musterbasiert aus und liefert eine für den Endbenutzer lesbare Beschreibung des
+ * Fehlergrunds. Das ursprüngliche Datenmodell bleibt unverändert; die Übersetzung
+ * findet ausschließlich in der Darstellungsschicht statt.
+ * <p>
+ * Die Mustererkennung erfolgt ohne Berücksichtigung der Groß-/Kleinschreibung
+ * und prüft die definierten Schlüsselbegriffe in festgelegter Reihenfolge,
+ * damit spezifischere Muster vor allgemeineren greifen.
+ * <p>
+ * Die Klasse wird sowohl im Verarbeitungslauf-Tab als auch im Verlauf-Tab verwendet.
+ */
+public final class AiFailureMessageTranslator {
+
+    private AiFailureMessageTranslator() {
+    }
+
+    /**
+     * Liefert eine benutzerfreundliche deutsche Fehlermeldung für die angegebene
+     * technische Fehlerbeschreibung.
+     * <p>
+     * Ist {@code technicalMessage} {@code null} oder leer, wird der allgemeine
+     * Fallback-Text zurückgegeben.
+     *
+     * @param technicalMessage die rohe technische Fehlermeldung; darf {@code null} sein
+     * @return eine nicht-leere deutsche Benutzerfehlermeldung ohne führendes Warnsymbol
+     */
+    public static String translate(String technicalMessage) {
+        if (technicalMessage == null || technicalMessage.isBlank()) {
+            return "Verarbeitung fehlgeschlagen. Bitte Konfiguration prüfen und ggf. erneut verarbeiten.";
+        }
+        String lower = technicalMessage.toLowerCase(java.util.Locale.ROOT);
+
+        // Pre-Check-Fehler: kein lesbarer Text im PDF
+        if (lower.contains("no usable text")) {
+            return "PDF enthält keinen lesbaren Text. Möglicherweise handelt es sich um einen Scan"
+                    + " ohne Texterkennung (OCR). Eine automatische Benennung ist nicht möglich.";
+        }
+
+        // KI-Validierungsfehler: Titel überschreitet die konfigurierte Maximallänge
+        if (lower.contains("title exceeds")) {
+            return buildTitleExceedsMessage(technicalMessage);
+        }
+
+        // Defekte oder strukturell nicht lesbare PDF-Datei
+        if (lower.contains("content not extractable")
+                || lower.contains("ioexception")
+                || lower.contains("end of file")
+                || lower.contains("endoffileexception")
+                || lower.contains("eof")) {
+            return "Die PDF-Datei ist ungültig oder beschädigt und kann nicht verarbeitet werden.";
+        }
+
+        // HTTP-Authentifizierungsfehler
+        if (lower.contains("http_401")) {
+            return "KI-Dienst: Ungültiger API-Schlüssel. Bitte in den Einstellungen prüfen.";
+        }
+        if (lower.contains("http_403")) {
+            return "KI-Dienst: Zugriff verweigert. Bitte API-Schlüssel und Berechtigungen prüfen.";
+        }
+        if (lower.contains("http_429")) {
+            return "KI-Dienst: Anfragelimit erreicht. Bitte später erneut versuchen.";
+        }
+        if (lower.contains("http_5")) {
+            return "KI-Dienst vorübergehend nicht erreichbar. Bitte später erneut versuchen.";
+        }
+
+        // Netzwerk- und Verbindungsfehler
+        if (lower.contains("connection") || lower.contains("timeout") || lower.contains("refused")) {
+            return "KI-Dienst nicht erreichbar. Bitte Verbindung und Konfiguration prüfen.";
+        }
+
+        return "Verarbeitung fehlgeschlagen. Bitte Konfiguration prüfen und ggf. erneut verarbeiten.";
+    }
+
+    /**
+     * Baut aus einer „Title exceeds"-Fehlermeldung einen benutzerfreundlichen Text,
+     * der Titel, tatsächliche Länge und konfiguriertes Limit nennt.
+     * <p>
+     * Erwartet wird das Format:
+     * {@code … Title exceeds N characters (base title): 'Titel' …}
+     * <p>
+     * Kann das Format nicht geparst werden, wird ein generischer Hinweis zurückgegeben.
+     *
+     * @param technicalMessage die vollständige technische Fehlermeldung
+     * @return benutzerfreundlicher Hinweis auf den zu langen Titel
+     */
+    private static String buildTitleExceedsMessage(String technicalMessage) {
+        try {
+            int exceedsIdx = technicalMessage.indexOf("Title exceeds ");
+            if (exceedsIdx >= 0) {
+                String afterExceeds = technicalMessage.substring(exceedsIdx + "Title exceeds ".length());
+                int charIdx = afterExceeds.indexOf(" characters");
+                if (charIdx > 0) {
+                    int limit = Integer.parseInt(afterExceeds.substring(0, charIdx).trim());
+                    int colonQuote = technicalMessage.indexOf(": '", exceedsIdx);
+                    if (colonQuote >= 0) {
+                        String afterQuote = technicalMessage.substring(colonQuote + 3);
+                        int closingQuote = afterQuote.lastIndexOf("'");
+                        if (closingQuote > 0) {
+                            String title = afterQuote.substring(0, closingQuote);
+                            return "KI-Vorschlag abgelehnt: '" + title + "' ist zu lang ("
+                                    + title.length() + " Zeichen, Limit: " + limit
+                                    + "). Bitte Dateinamen manuell kürzen.";
+                        }
+                    }
+                }
+            }
+        } catch (NumberFormatException | StringIndexOutOfBoundsException ignored) {
+            // Fallback unten
+        }
+        return "KI-Vorschlag abgelehnt: Titel überschreitet die maximale Länge. Bitte Dateinamen manuell kürzen.";
+    }
+}
@@ -0,0 +1,201 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.util.ArrayList;
+import java.util.EnumMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus;
+import javafx.geometry.Pos;
+import javafx.scene.control.Label;
+import javafx.scene.layout.HBox;
+
+/**
+ * Einzeilige Zusammenfassungsleiste, die nach Abschluss eines Verarbeitungslaufs
+ * die aggregierten Ergebnisse anzeigt.
+ *
+ * <p>Das Banner erscheint nach Laufabschluss unterhalb des Fortschrittsbalkens und
+ * oberhalb der Ergebnistabelle. Es zeigt nur Kategorien, deren Zähler größer als null
+ * ist. Folgende Status werden nicht gezählt und tauchen nie im Banner auf:
+ * {@code READY_FOR_AI}, {@code PROPOSAL_READY} und {@code PROCESSING} sind im
+ * Enum {@link DocumentCompletionStatus} nicht enthalten – alle enthaltenen Werte
+ * werden gezählt, außer Einträgen mit {@code resetPending=true}, da diese keinen
+ * abgeschlossenen Zustand darstellen.
+ *
+ * <p>Farbe ist niemals das einzige Unterscheidungsmerkmal: Jedes Segment enthält
+ * ein Icon und einen Text.
+ *
+ * <p>Die öffentlichen Methoden {@link #clear()} und {@link #update(Map)} sind
+ * thread-agnostisch definiert, aber müssen auf dem JavaFX Application Thread aufgerufen
+ * werden (oder das Banner muss via {@code Platform.runLater} aktualisiert werden).
+ * Die Aggregations-Hilfsmethode {@link #aggregateCounts(Iterable)} ist vollständig
+ * unabhängig von JavaFX und kann auf jedem Thread aufgerufen werden.
+ */
+public final class BatchRunSummaryBanner {
+
+    /** Trennzeichen zwischen den Kategoriesegmenten. */
+    private static final String SEGMENT_SEPARATOR = "  ·  ";
+
+    /** Abstand zwischen den Label-Segmenten in Pixeln. */
+    private static final int SPACING = 0;
+
+    /** Innerer Abstand des Containers in Pixeln (oben/unten). */
+    private static final double PADDING_V = 4.0;
+
+    /** Standardfarbe für den Summentext. */
+    private static final String STYLE_DEFAULT = "-fx-font-size: 12;";
+
+    /**
+     * Alle {@link DocumentCompletionStatus}-Werte, die im Banner angezeigt werden,
+     * in der verbindlichen Anzeigereihenfolge gemäß Spezifikation.
+     */
+    private static final List<DocumentCompletionStatus> DISPLAYED_ORDER = List.of(
+            DocumentCompletionStatus.SUCCESS,
+            DocumentCompletionStatus.FAILED_RETRYABLE,
+            DocumentCompletionStatus.FAILED_PERMANENT,
+            DocumentCompletionStatus.SKIPPED_ALREADY_PROCESSED,
+            DocumentCompletionStatus.SKIPPED_FINAL_FAILURE
+    );
+
+    /** Wurzel-Container des Banners – wird in das Tab-Layout eingebettet. */
+    private final HBox container;
+
+    /** Label, das den kompletten Bannertext als Inline-Segmente trägt. */
+    private final Label contentLabel;
+
+    /**
+     * Erstellt ein neues, initial unsichtbares Summary-Banner.
+     */
+    public BatchRunSummaryBanner() {
+        contentLabel = new Label();
+        contentLabel.setStyle(STYLE_DEFAULT);
+        contentLabel.setWrapText(false);
+
+        container = new HBox(SPACING, contentLabel);
+        container.setAlignment(Pos.CENTER_LEFT);
+        container.setStyle("-fx-padding: " + PADDING_V + " 0 " + PADDING_V + " 0;");
+
+        // Initial unsichtbar, nimmt keinen Platz ein
+        container.setVisible(false);
+        container.setManaged(false);
+    }
+
+    // -------------------------------------------------------------------------
+    // Öffentliche API
+    // -------------------------------------------------------------------------
+
+    /**
+     * Versteckt das Banner und leert seinen Inhalt.
+     *
+     * <p>Muss auf dem JavaFX Application Thread aufgerufen werden.
+     */
+    public void clear() {
+        contentLabel.setText("");
+        container.setVisible(false);
+        container.setManaged(false);
+    }
+
+    /**
+     * Aktualisiert das Banner mit den aggregierten Zählern und macht es sichtbar.
+     *
+     * <p>Zeigt nur Kategorien mit Anzahl &gt; 0. Wenn alle Zähler null sind (leerer Lauf),
+     * wird das Banner versteckt.
+     *
+     * <p>Muss auf dem JavaFX Application Thread aufgerufen werden.
+     *
+     * @param counts Zuordnung von Verarbeitungsstatus zu Anzahl;
+     *               fehlende Status werden als 0 interpretiert; darf nicht null sein
+     */
+    public void update(Map<DocumentCompletionStatus, Integer> counts) {
+        Objects.requireNonNull(counts, "counts darf nicht null sein");
+
+        String text = buildBannerText(counts);
+        if (text.isEmpty()) {
+            clear();
+            return;
+        }
+
+        contentLabel.setText(text);
+        container.setVisible(true);
+        container.setManaged(true);
+    }
+
+    /**
+     * Liefert den JavaFX-Container-Knoten zum Einbetten in das Tab-Layout.
+     *
+     * @return der Container-Knoten; nie null
+     */
+    public HBox getNode() {
+        return container;
+    }
+
+    // -------------------------------------------------------------------------
+    // Aggregations-Hilfe (thread-agnostisch, testbar ohne JavaFX)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Zählt die Anzahl jedes {@link DocumentCompletionStatus} in der übergebenen
+     * Iterable. Einträge mit {@code resetPending=true} werden ignoriert, da sie
+     * keinen abgeschlossenen Verarbeitungszustand darstellen.
+     *
+     * <p>Diese Methode ist vollständig unabhängig von JavaFX und kann auf jedem
+     * Thread aufgerufen werden.
+     *
+     * @param rows die Ergebniszeilen des Laufs; darf nicht null sein;
+     *             null-Elemente werden übersprungen
+     * @return eine Map mit der Anzahl je Status; enthält alle anzuzeigenden
+     *         Status (fehlende haben Wert 0); nie null
+     */
+    public static Map<DocumentCompletionStatus, Integer> aggregateCounts(
+            Iterable<? extends GuiBatchRunResultRow> rows) {
+        Objects.requireNonNull(rows, "rows darf nicht null sein");
+
+        Map<DocumentCompletionStatus, Integer> counts = new EnumMap<>(DocumentCompletionStatus.class);
+        // Alle anzuzeigenden Status mit 0 vorbelegen
+        for (DocumentCompletionStatus status : DISPLAYED_ORDER) {
+            counts.put(status, 0);
+        }
+
+        for (GuiBatchRunResultRow row : rows) {
+            if (row == null) {
+                continue;
+            }
+            // Reset-Pending-Zeilen zählen nicht – sie haben noch keinen abgeschlossenen Status
+            if (row.resetPending()) {
+                continue;
+            }
+            DocumentCompletionStatus status = row.status();
+            // Nur anzuzeigende Status zählen (entspricht dem Ausschluss von
+            // Übergangszuständen wie READY_FOR_AI, PROPOSAL_READY, PROCESSING)
+            if (counts.containsKey(status)) {
+                counts.merge(status, 1, Integer::sum);
+            }
+        }
+        return counts;
+    }
+
+    // -------------------------------------------------------------------------
+    // Interne Hilfsmethoden
+    // -------------------------------------------------------------------------
+
+    /**
+     * Erzeugt den angezeigten Bannertext aus den Zählern.
+     * Liefert einen leeren String wenn alle Zähler null sind.
+     *
+     * @param counts die Zähler je Status; darf nicht null sein
+     * @return der fertige Bannertext oder ein leerer String
+     */
+    static String buildBannerText(Map<DocumentCompletionStatus, Integer> counts) {
+        List<String> segments = new ArrayList<>();
+        for (DocumentCompletionStatus status : DISPLAYED_ORDER) {
+            int count = counts.getOrDefault(status, 0);
+            if (count > 0) {
+                String icon = ProcessingStatusPresentation.iconFor(status);
+                String category = ProcessingStatusPresentation.summaryCategoryFor(status);
+                segments.add(icon + " " + count + " " + category);
+            }
+        }
+        return String.join(SEGMENT_SEPARATOR, segments);
+    }
+}
@@ -0,0 +1,495 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.Consumer;
+
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.GuiTooltipTexts;
+import de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus;
+import javafx.geometry.Insets;
+import javafx.geometry.Pos;
+import javafx.scene.control.Button;
+import javafx.scene.control.Label;
+import javafx.scene.control.TextField;
+import javafx.scene.control.Tooltip;
+import javafx.scene.input.KeyCode;
+import javafx.scene.layout.HBox;
+import javafx.scene.layout.Priority;
+import javafx.scene.layout.Region;
+import javafx.scene.layout.VBox;
+import javafx.util.Duration;
+
+/**
+ * Detailbereich-Komponente für die Bearbeitung des Zieldateinamens einer selektierten
+ * Ergebnis-Zeile.
+ * <p>
+ * Die Komponente kapselt Eingabefeld, Validierungsanzeige sowie die
+ * Schaltflächen „Dateiname übernehmen" und „Zurücksetzen auf KI-Vorschlag". Sie kennt
+ * drei Zustände gemäß fachlicher Spezifikation:
+ * <ul>
+ *   <li><b>KI-Vorschlag</b> – der ursprünglich generierte Name; unveränderlich pro Zeile.</li>
+ *   <li><b>Letzter gespeicherter Name</b> – der zuletzt bestätigte Name; entspricht dem
+ *       aktuellen Stand in Dateisystem und Persistenz.</li>
+ *   <li><b>Aktuelle Eingabe</b> – der im Textfeld sichtbare Wert; kann vom letzten
+ *       gespeicherten Namen abweichen (Dirty-State).</li>
+ * </ul>
+ *
+ * <h2>Threading</h2>
+ * <p>
+ * Alle öffentlichen Methoden müssen auf dem JavaFX Application Thread aufgerufen werden.
+ * Die tatsächliche Speicher-Operation ist in der Verantwortung des aufrufenden Tabs und
+ * läuft dort auf einem Hintergrund-Worker-Thread.
+ */
+public final class FileNameEditorPane {
+
+    /** Feste PDF-Erweiterung für Zieldateien. */
+    public static final String PDF_EXTENSION = ".pdf";
+
+    /** Windows-Maximal-Pfadlänge (MAX_PATH = 260 inkl. Null-Terminator = 259 nutzbar). */
+    public static final int MAX_WINDOWS_PATH_LENGTH = 259;
+
+    private static final Set<String> RESERVED_WINDOWS_NAMES = buildReservedWindowsNames();
+    private static final String FORBIDDEN_CHARS_REGEX = ".*[\\\\/:*?\"<>|].*";
+
+    private final VBox root = new VBox(4);
+    private final TextField textField = new TextField();
+    private final Label validationLabel = new Label();
+    private final Button saveButton = new Button("Dateiname übernehmen");
+    private final Button resetButton = new Button("Zurücksetzen auf KI-Vorschlag");
+    private final Label sectionTitle = new Label("Dateiname");
+
+    private Optional<String> aiProposal = Optional.empty();
+    private Optional<String> lastSavedName = Optional.empty();
+    private String targetFolderPath = "";
+    private boolean selectionEditable = false;
+    private boolean globalEnabled = true;
+    private boolean suppressValidation = false;
+
+    private Consumer<String> onSaveRequested = name -> { };
+
+    /**
+     * Erstellt die Komponente mit leerem und deaktiviertem Zustand.
+     */
+    public FileNameEditorPane() {
+        sectionTitle.setStyle("-fx-font-weight: bold;");
+
+        textField.setId("filename-editor-text-field");
+        Tooltip textFieldTooltip = new Tooltip(GuiTooltipTexts.DATEINAME_TEXTFELD);
+        textFieldTooltip.setShowDelay(Duration.millis(300));
+        textField.setTooltip(textFieldTooltip);
+        HBox.setHgrow(textField, Priority.ALWAYS);
+
+        HBox inputRow = new HBox(4, textField);
+        inputRow.setAlignment(Pos.CENTER_LEFT);
+
+        validationLabel.setId("filename-editor-validation-label");
+        validationLabel.setStyle("-fx-font-size: 11px; -fx-text-fill: #c62828;");
+        validationLabel.setVisible(false);
+        validationLabel.setManaged(false);
+        validationLabel.setWrapText(true);
+
+        saveButton.setId("filename-editor-save-button");
+        saveButton.setOnAction(e -> fireSaveRequest());
+        Tooltip saveTooltip = new Tooltip(GuiTooltipTexts.DATEINAME_UEBERNEHMEN);
+        saveTooltip.setShowDelay(Duration.millis(300));
+        saveButton.setTooltip(saveTooltip);
+
+        resetButton.setId("filename-editor-reset-button");
+        resetButton.setOnAction(e -> resetToAiProposal());
+        Tooltip resetTooltip = new Tooltip(GuiTooltipTexts.DATEINAME_ZURUECKSETZEN);
+        resetTooltip.setShowDelay(Duration.millis(300));
+        resetButton.setTooltip(resetTooltip);
+
+        HBox buttonRow = new HBox(8, saveButton, resetButton);
+        buttonRow.setAlignment(Pos.CENTER_LEFT);
+        buttonRow.setPadding(new Insets(4, 0, 0, 0));
+
+        root.getChildren().addAll(sectionTitle, inputRow, validationLabel, buttonRow);
+        root.setPadding(new Insets(0, 0, 4, 0));
+
+        // Live-Validierung auf jeden Tastendruck.
+        textField.textProperty().addListener((obs, oldText, newText) -> {
+            if (!suppressValidation) {
+                refreshUiState();
+            }
+        });
+
+        // Enter löst Speichern aus, Escape setzt auf lastSavedName zurück.
+        textField.setOnKeyPressed(event -> {
+            if (event.getCode() == KeyCode.ENTER) {
+                if (!saveButton.isDisabled()) {
+                    fireSaveRequest();
+                    event.consume();
+                }
+            } else if (event.getCode() == KeyCode.ESCAPE) {
+                discardChanges();
+                event.consume();
+            }
+        });
+
+        clearSelection();
+    }
+
+    /**
+     * Liefert den Wurzel-Knoten der Komponente zum Einfügen in den Detailbereich.
+     *
+     * @return das Root-Control der Komponente; nie null
+     */
+    public Region getNode() {
+        return root;
+    }
+
+    /**
+     * Registriert einen Callback, der ausgelöst wird, wenn der Benutzer „Dateiname übernehmen"
+     * anfordert. Parameter ist der gewünschte Basisname ohne {@code .pdf}-Erweiterung.
+     *
+     * @param callback Callback; darf nicht null sein (leerer Consumer als No-Op möglich)
+     */
+    public void setOnSaveRequested(Consumer<String> callback) {
+        this.onSaveRequested = Objects.requireNonNull(callback, "callback must not be null");
+    }
+
+    /**
+     * Aktualisiert den Zustand für die neu selektierte Zeile.
+     * <p>
+     * Der KI-Vorschlag wird aus {@link GuiBatchRunResultRow#finalFileName()} abgeleitet,
+     * der letzte gespeicherte Name aus {@link GuiBatchRunResultRow#effectiveFileName()}.
+     * Editierbarkeitsregeln:
+     * <ul>
+     *   <li>{@code resetPending} → nicht editierbar.</li>
+     *   <li>{@code SUCCESS} und {@code SKIPPED_ALREADY_PROCESSED} → editierbar, sofern
+     *       ein bisher gespeicherter Zieldateiname vorliegt (Umbenennen einer existierenden
+     *       Zieldatei).</li>
+     *   <li>{@code FAILED_RETRYABLE}, {@code FAILED_PERMANENT} und
+     *       {@code SKIPPED_FINAL_FAILURE} → editierbar; das Eingabefeld erlaubt die
+     *       Eingabe eines manuellen Zieldateinamens auch dann, wenn (noch) kein
+     *       Vorschlag oder gespeicherter Name vorliegt (Kopieren der Quelldatei
+     *       mit manuellem Namen).</li>
+     * </ul>
+     *
+     * @param row              die neu selektierte Zeile; {@code null} führt zu {@link #clearSelection()}
+     * @param targetFolderPath Zielordner-Pfad für die Pfadlängen-Validierung; darf
+     *                         {@code null} sein (wird als leer behandelt)
+     */
+    public void loadSelection(GuiBatchRunResultRow row, String targetFolderPath) {
+        this.targetFolderPath = targetFolderPath == null ? "" : targetFolderPath;
+        if (row == null) {
+            clearSelection();
+            return;
+        }
+        this.aiProposal = stripPdfExtension(row.finalFileName());
+        this.lastSavedName = stripPdfExtension(row.effectiveFileName());
+
+        boolean editable;
+        if (row.resetPending()) {
+            editable = false;
+        } else if (requiresExistingTargetForRename(row.status())) {
+            // Umbenennen einer existierenden Zieldatei: nur sinnvoll, wenn ein
+            // gespeicherter Name vorliegt.
+            editable = lastSavedName.isPresent();
+        } else {
+            // Manuelle Kopie: das Feld ist auch ohne gespeicherten Namen editierbar.
+            editable = isRowEditable(row);
+        }
+        this.selectionEditable = editable;
+
+        suppressValidation = true;
+        try {
+            textField.setText(lastSavedName.orElse(""));
+        } finally {
+            suppressValidation = false;
+        }
+        refreshUiState();
+    }
+
+    /**
+     * Liefert {@code true}, wenn die Zeile einen Status hat, bei dem die Editierung
+     * eine bestehende Zieldatei umbenennt (im Gegensatz zur Kopie der Quelldatei).
+     *
+     * @param status der aggregierte Abschlussstatus der Zeile
+     * @return {@code true} für SUCCESS und SKIPPED_ALREADY_PROCESSED; sonst {@code false}
+     */
+    private static boolean requiresExistingTargetForRename(DocumentCompletionStatus status) {
+        return status == DocumentCompletionStatus.SUCCESS
+                || status == DocumentCompletionStatus.SKIPPED_ALREADY_PROCESSED;
+    }
+
+    /**
+     * Leert die Komponente und deaktiviert die Eingabe. Wird aufgerufen wenn keine Zeile
+     * selektiert ist.
+     */
+    public void clearSelection() {
+        this.aiProposal = Optional.empty();
+        this.lastSavedName = Optional.empty();
+        this.selectionEditable = false;
+        suppressValidation = true;
+        try {
+            textField.setText("");
+        } finally {
+            suppressValidation = false;
+        }
+        refreshUiState();
+    }
+
+    /**
+     * Setzt den Textfeldinhalt auf den zuletzt gespeicherten Namen zurück. Äquivalent zum
+     * Drücken der Escape-Taste im Textfeld.
+     */
+    public void discardChanges() {
+        suppressValidation = true;
+        try {
+            textField.setText(lastSavedName.orElse(""));
+        } finally {
+            suppressValidation = false;
+        }
+        refreshUiState();
+    }
+
+    /**
+     * Setzt den Textfeldinhalt auf den KI-Vorschlag zurück. Es erfolgt <em>kein</em>
+     * Speichervorgang – der Benutzer kann anschließend über „Dateiname übernehmen"
+     * bestätigen.
+     */
+    public void resetToAiProposal() {
+        if (aiProposal.isEmpty()) {
+            return;
+        }
+        suppressValidation = true;
+        try {
+            textField.setText(aiProposal.get());
+        } finally {
+            suppressValidation = false;
+        }
+        refreshUiState();
+    }
+
+    /**
+     * Aktiviert oder deaktiviert die gesamte Komponente. Während eines laufenden Batch-Laufs
+     * soll die Komponente deaktiviert sein.
+     *
+     * @param enabled {@code true} wenn Bedienung erlaubt ist
+     */
+    public void setEnabled(boolean enabled) {
+        this.globalEnabled = enabled;
+        refreshUiState();
+    }
+
+    /**
+     * Liefert {@code true} wenn die aktuelle Texteingabe vom letzten gespeicherten Namen
+     * abweicht.
+     *
+     * @return ob ungespeicherte Änderungen im Textfeld vorliegen
+     */
+    public boolean isDirty() {
+        if (!selectionEditable) {
+            return false;
+        }
+        String current = textField.getText() == null ? "" : textField.getText();
+        String saved = lastSavedName.orElse("");
+        return !current.equals(saved);
+    }
+
+    /**
+     * Setzt den Dirty-State zurück, ohne das Textfeld neu zu laden. Wird aufgerufen,
+     * nachdem eine Umbenennung erfolgreich abgeschlossen wurde, damit ein anschließendes
+     * Ersetzen der Tabellenzeile keinen Verwerfen-Dialog auslöst. Der angezeigte Text
+     * im Textfeld bleibt unverändert; {@code lastSavedName} wird auf den aktuellen
+     * Textfeldinhalt gesetzt.
+     */
+    public void clearDirtyState() {
+        String current = textField.getText() == null ? "" : textField.getText();
+        this.lastSavedName = current.isBlank() ? Optional.empty() : Optional.of(current);
+        refreshUiState();
+    }
+
+    /**
+     * Liefert {@code true} wenn für die aktuelle Zeile ein KI-Vorschlag vorliegt.
+     *
+     * @return ob ein KI-Vorschlag existiert
+     */
+    public boolean hasAiProposal() {
+        return aiProposal.isPresent();
+    }
+
+    /**
+     * Liefert {@code true} wenn für die aktuelle Zeile ein zuletzt gespeicherter Name
+     * existiert.
+     *
+     * @return ob ein letzter gespeicherter Name existiert
+     */
+    public boolean hasLastSaved() {
+        return lastSavedName.isPresent();
+    }
+
+    /**
+     * Aktualisiert intern den letzten gespeicherten Namen. Typisch nach erfolgreichem
+     * Speichervorgang im Tab (ohne erneut {@link #loadSelection(GuiBatchRunResultRow, String)}
+     * aufzurufen).
+     *
+     * @param newLastSavedName neuer letzter gespeicherter Name ohne {@code .pdf}; darf
+     *                         {@code null} sein
+     */
+    public void updateLastSavedName(String newLastSavedName) {
+        this.lastSavedName = newLastSavedName == null || newLastSavedName.isBlank()
+                ? Optional.empty()
+                : Optional.of(newLastSavedName);
+        suppressValidation = true;
+        try {
+            textField.setText(lastSavedName.orElse(""));
+        } finally {
+            suppressValidation = false;
+        }
+        refreshUiState();
+    }
+
+    // --- Test-Accessoren ------------------------------------------------------
+
+    /** Visible for tests. */
+    TextField textField() {
+        return textField;
+    }
+
+    /** Visible for tests. */
+    Label validationLabel() {
+        return validationLabel;
+    }
+
+    /** Visible for tests. */
+    Button saveButton() {
+        return saveButton;
+    }
+
+    /** Visible for tests. */
+    Button resetButton() {
+        return resetButton;
+    }
+
+    // --- Interne Helfer -------------------------------------------------------
+
+    private void fireSaveRequest() {
+        if (saveButton.isDisabled()) {
+            return;
+        }
+        String current = textField.getText() == null ? "" : textField.getText();
+        onSaveRequested.accept(current);
+    }
+
+    private void refreshUiState() {
+        boolean enabled = selectionEditable && globalEnabled;
+        textField.setDisable(!enabled);
+        // Button „Zurücksetzen auf KI-Vorschlag" ist nur aktiv, wenn Eingabe möglich
+        // und ein KI-Vorschlag vorliegt.
+        resetButton.setDisable(aiProposal.isEmpty() || !enabled);
+
+        if (!enabled) {
+            // Validierung und Speichern-Button unterdrücken, Rahmen neutral.
+            validationLabel.setVisible(false);
+            validationLabel.setManaged(false);
+            textField.setStyle("");
+            saveButton.setDisable(true);
+            return;
+        }
+
+        String current = textField.getText() == null ? "" : textField.getText();
+        Optional<String> error = validate(current);
+
+        if (error.isPresent()) {
+            validationLabel.setText(error.get());
+            validationLabel.setVisible(true);
+            validationLabel.setManaged(true);
+            textField.setStyle("-fx-border-color: #c62828; -fx-border-width: 1.5;");
+            saveButton.setDisable(true);
+        } else {
+            validationLabel.setVisible(false);
+            validationLabel.setManaged(false);
+            if (isDirty()) {
+                // Dirty-Markierung: orangefarbener Rand.
+                textField.setStyle("-fx-border-color: #e65100; -fx-border-width: 1.5;");
+                saveButton.setDisable(false);
+            } else {
+                textField.setStyle("");
+                saveButton.setDisable(true);
+            }
+        }
+    }
+
+    /**
+     * Führt die vollständige Dateinamen-Validierung aus und liefert gegebenenfalls den
+     * fachlichen Fehlertext. Paket-privat für Unit-Tests.
+     *
+     * @param input Eingabe aus dem Textfeld (ohne {@code .pdf})
+     * @return der Fehlertext oder {@link Optional#empty()} wenn gültig
+     */
+    Optional<String> validate(String input) {
+        if (input == null || input.isBlank()) {
+            return Optional.of("Dateiname darf nicht leer sein");
+        }
+        if (!input.equals(input.strip())) {
+            return Optional.of("Leerzeichen am Anfang oder Ende nicht erlaubt");
+        }
+        if (input.matches(FORBIDDEN_CHARS_REGEX)) {
+            return Optional.of("Unerlaubtes Zeichen (nicht erlaubt: \\ / : * ? \" < > |)");
+        }
+        if (RESERVED_WINDOWS_NAMES.contains(input.toUpperCase(java.util.Locale.ROOT))) {
+            return Optional.of("Reservierter Systemname");
+        }
+        if (input.endsWith(".")) {
+            return Optional.of("Dateiname darf nicht auf einen Punkt enden");
+        }
+        int totalLength = pathLengthEstimate(input);
+        if (totalLength > MAX_WINDOWS_PATH_LENGTH) {
+            return Optional.of("Dateipfad zu lang (Windows-Limit " + MAX_WINDOWS_PATH_LENGTH
+                    + " Zeichen, aktuell " + totalLength + ")");
+        }
+        return Optional.empty();
+    }
+
+    private int pathLengthEstimate(String baseName) {
+        String folder = targetFolderPath == null ? "" : targetFolderPath;
+        int folderLength = folder.length();
+        int separatorLength = folderLength == 0 ? 0 : 1;
+        return folderLength + separatorLength + baseName.length() + PDF_EXTENSION.length();
+    }
+
+    /**
+     * Liefert {@code true}, wenn die Zeile fachlich für eine manuelle Dateinamens-Aktion
+     * editierbar ist.
+     * <p>
+     * Editierbar sind alle nicht-resetpending-Zeilen unabhängig davon, ob die Aktion
+     * eine Zieldatei umbenennt (SUCCESS, SKIPPED_ALREADY_PROCESSED) oder die Quelldatei
+     * kopiert (FAILED_*, SKIPPED_FINAL_FAILURE). Die genaue Aktion wird vom Tab anhand
+     * des Status entschieden.
+     *
+     * @param row die Zeile, deren Editierbarkeit geprüft werden soll
+     * @return {@code true} wenn die Zeile editierbar ist; sonst {@code false}
+     */
+    private static boolean isRowEditable(GuiBatchRunResultRow row) {
+        return !row.resetPending();
+    }
+
+    private static Optional<String> stripPdfExtension(Optional<String> fileNameWithExtension) {
+        if (fileNameWithExtension.isEmpty()) {
+            return Optional.empty();
+        }
+        String raw = fileNameWithExtension.get();
+        if (raw.toLowerCase(java.util.Locale.ROOT).endsWith(PDF_EXTENSION)) {
+            return Optional.of(raw.substring(0, raw.length() - PDF_EXTENSION.length()));
+        }
+        return Optional.of(raw);
+    }
+
+    private static Set<String> buildReservedWindowsNames() {
+        Set<String> reserved = new HashSet<>();
+        reserved.add("CON");
+        reserved.add("PRN");
+        reserved.add("AUX");
+        reserved.add("NUL");
+        for (int i = 1; i <= 9; i++) {
+            reserved.add("COM" + i);
+            reserved.add("LPT" + i);
+        }
+        return Set.copyOf(reserved);
+    }
+}
@@ -0,0 +1,769 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.nio.file.Path;
+import java.time.Duration;
+import java.time.LocalDate;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
+import java.util.function.Function;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.BatchRunCancellationToken;
+import de.gecheckt.pdf.umbenenner.application.port.in.BatchRunProgressObserver;
+import de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionEvent;
+import de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus;
+import de.gecheckt.pdf.umbenenner.application.port.in.HistoricalDocumentContext;
+import de.gecheckt.pdf.umbenenner.application.port.in.ResetDocumentStatusResult;
+import de.gecheckt.pdf.umbenenner.application.port.in.RunSummary;
+import de.gecheckt.pdf.umbenenner.application.port.out.ConfigurationFileLockException;
+import de.gecheckt.pdf.umbenenner.application.port.out.ConfigurationFileLockPort;
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+import de.gecheckt.pdf.umbenenner.domain.model.RunId;
+import javafx.application.Platform;
+import javafx.scene.control.Alert;
+
+/**
+ * Coordinates a single batch run (regular or targeted mini-run) triggered from the
+ * JavaFX GUI, and optional reset-only operations on selected document fingerprints.
+ * <p>
+ * The coordinator owns the background worker thread that executes the run, maintains the
+ * cancellation flag, and translates the
+ * {@link de.gecheckt.pdf.umbenenner.application.port.in.BatchRunProgressObserver}
+ * callbacks into a GUI-friendly event stream on the JavaFX Application Thread.
+ *
+ * <h2>Threading</h2>
+ * <ul>
+ *   <li>The batch run and reset operations execute on a daemon worker thread created by
+ *       {@link #threadFactory}. No JavaFX code touches this thread.</li>
+ *   <li>Every GUI callback ({@link Listener}) is invoked on the JavaFX Application Thread
+ *       via {@link Platform#runLater(Runnable)}, so listeners may freely mutate
+ *       {@code Control}s without taking any further precautions.</li>
+ *   <li>{@link #requestCancellation()} sets a volatile flag that the use case polls
+ *       between candidates (soft-stop). It never interrupts the worker thread; the
+ *       currently-processed candidate always completes in full.</li>
+ * </ul>
+ *
+ * <h2>Lifecycle</h2>
+ * <ol>
+ *   <li>Construct with a regular launcher, a mini-run launcher, a reset port, a thread
+ *       factory and a listener.</li>
+ *   <li>Call {@link #start(Path)} to begin a regular run, or
+ *       {@link #startMiniRun(Path, Set)} for a targeted mini-run, or
+ *       {@link #startReset(Path, Set)} for a status-reset-only operation.</li>
+ *   <li>Optionally call {@link #requestCancellation()} to trigger soft-stop for runs.</li>
+ *   <li>Wait for {@link Listener#onRunEnded(RunSummary, GuiBatchRunLaunchOutcome)} or
+ *       {@link Listener#onResetCompleted(ResetDocumentStatusResult)} on the FX thread.</li>
+ *   <li>Start a new operation only after the previous one has ended.</li>
+ * </ol>
+ */
+public final class GuiBatchRunCoordinator {
+    private static final String CONFIG_FILE_NOT_NULL = "configFilePath must not be null";
+
+
+
+    private static final Logger LOG = LogManager.getLogger(GuiBatchRunCoordinator.class);
+    private static final String WORKER_THREAD_NAME = "gui-batch-run";
+
+    /**
+     * Listener interface invoked on the JavaFX Application Thread during a run or reset.
+     */
+    public interface Listener {
+
+        /**
+         * Invoked once, after the batch use case has scanned the source folder and knows
+         * the total candidate count.
+         *
+         * @param runId           the identifier of the run; never {@code null}
+         * @param totalCandidates the number of candidates detected in the source folder;
+         *                        never negative
+         */
+        void onRunStarted(RunId runId, int totalCandidates);
+
+        /**
+         * Invoked once per candidate whose processing reached a terminal resolution.
+         *
+         * @param row the row describing the candidate result; never {@code null}
+         */
+        void onDocumentCompleted(GuiBatchRunResultRow row);
+
+        /**
+         * Invoked once after the run has fully terminated on the worker thread.
+         *
+         * @param summary the final outcome counts; never {@code null}
+         * @param outcome a description of how the run terminated; never {@code null}
+         */
+        void onRunEnded(RunSummary summary, GuiBatchRunLaunchOutcome outcome);
+
+        /**
+         * Invoked once after a reset-only operation has completed on the worker thread.
+         * <p>
+         * The default implementation does nothing so existing {@link Listener}
+         * implementations need not override this method until they need reset
+         * notifications.
+         *
+         * @param result the full outcome of the reset operation; never {@code null}
+         */
+        default void onResetCompleted(ResetDocumentStatusResult result) {
+            // no-op default
+        }
+    }
+
+    private final GuiBatchRunLauncher launcher;
+    private final GuiMiniRunLauncher miniRunLauncher;
+    private final GuiResetDocumentStatusPort resetPort;
+    private final Function<Runnable, Thread> threadFactory;
+    private final Consumer<Runnable> fxDispatcher;
+    private final Listener listener;
+    private final GuiHistoricalDocumentContextPort historicalDocumentContextPort;
+    private final Optional<ConfigurationFileLockPort> configurationFileLockPort;
+    private final AtomicReference<Thread> activeWorker = new AtomicReference<>();
+    private final AtomicBoolean cancellationRequested = new AtomicBoolean();
+
+    /**
+     * Creates the coordinator with the default worker-thread factory and the default
+     * JavaFX Application Thread dispatcher.
+     * <p>
+     * Mini-run and reset capabilities are unavailable; all such requests will return
+     * {@code false}.
+     *
+     * @param launcher bridge to Bootstrap used to execute the batch; must not be null
+     * @param listener GUI listener invoked on the FX thread; must not be null
+     */
+    public GuiBatchRunCoordinator(GuiBatchRunLauncher launcher, Listener listener) {
+        this(launcher,
+                rejectingMiniRunLauncher(),
+                rejectingResetPort(),
+                defaultThreadFactory(),
+                defaultFxDispatcher(),
+                listener);
+    }
+
+    /**
+     * Creates the coordinator with all ports and the default worker-thread factory and
+     * JavaFX Application Thread dispatcher.
+     *
+     * @param launcher        bridge to Bootstrap for regular batch runs; must not be null
+     * @param miniRunLauncher bridge to Bootstrap for targeted mini-runs; must not be null
+     * @param resetPort       bridge to Bootstrap for status-reset-only operations; must
+     *                        not be null
+     * @param listener        GUI listener invoked on the FX thread; must not be null
+     */
+    public GuiBatchRunCoordinator(GuiBatchRunLauncher launcher,
+                                  GuiMiniRunLauncher miniRunLauncher,
+                                  GuiResetDocumentStatusPort resetPort,
+                                  Listener listener) {
+        this(launcher, miniRunLauncher, resetPort,
+                defaultThreadFactory(), defaultFxDispatcher(), listener);
+    }
+
+    /**
+     * Creates the coordinator with all ports and the historical file name port, using the
+     * default worker-thread factory and JavaFX Application Thread dispatcher.
+     *
+     * @param launcher               bridge to Bootstrap for regular batch runs; must not be null
+     * @param miniRunLauncher        bridge to Bootstrap for targeted mini-runs; must not be null
+     * @param resetPort              bridge to Bootstrap for status-reset-only operations; must
+     *                               not be null
+     * @param listener               GUI listener invoked on the FX thread; must not be null
+     * @param historicalDocumentContextPort port for resolving the historical AI-proposed filename for
+     *                               skipped documents; must not be null
+     */
+    public GuiBatchRunCoordinator(GuiBatchRunLauncher launcher,
+                                  GuiMiniRunLauncher miniRunLauncher,
+                                  GuiResetDocumentStatusPort resetPort,
+                                  Listener listener,
+                                  GuiHistoricalDocumentContextPort historicalDocumentContextPort) {
+        this(launcher, miniRunLauncher, resetPort,
+                defaultThreadFactory(), defaultFxDispatcher(), listener, historicalDocumentContextPort);
+    }
+
+    /**
+     * Creates the coordinator with all ports and the configuration file lock port, using
+     * the default worker-thread factory and JavaFX Application Thread dispatcher.
+     * <p>
+     * This constructor is intended for production wiring in {@code GuiBatchRunTab} where
+     * the lock port is supplied by Bootstrap.
+     *
+     * @param launcher                      bridge to Bootstrap for regular batch runs; must not be null
+     * @param miniRunLauncher               bridge to Bootstrap for targeted mini-runs; must not be null
+     * @param resetPort                     bridge to Bootstrap for status-reset-only operations; must
+     *                                      not be null
+     * @param listener                      GUI listener invoked on the FX thread; must not be null
+     * @param historicalDocumentContextPort port for resolving historical context; must not be null
+     * @param configurationFileLockPort     optional OS-lock on the configuration file; when present,
+     *                                      acquired before each run; {@code null} is treated as empty
+     */
+    public GuiBatchRunCoordinator(GuiBatchRunLauncher launcher,
+                                  GuiMiniRunLauncher miniRunLauncher,
+                                  GuiResetDocumentStatusPort resetPort,
+                                  Listener listener,
+                                  GuiHistoricalDocumentContextPort historicalDocumentContextPort,
+                                  Optional<ConfigurationFileLockPort> configurationFileLockPort) {
+        this(launcher, miniRunLauncher, resetPort,
+                defaultThreadFactory(), defaultFxDispatcher(), listener,
+                historicalDocumentContextPort, configurationFileLockPort);
+    }
+
+    /**
+     * Creates the coordinator with custom hooks for the worker-thread factory and the
+     * UI-thread dispatcher.
+     * <p>
+     * Tests use this constructor to execute batches synchronously or to verify which
+     * thread UI callbacks run on, without depending on an actual JavaFX runtime being
+     * initialised.
+     *
+     * @param launcher       bridge to Bootstrap for regular batch runs; must not be null
+     * @param miniRunLauncher bridge to Bootstrap for targeted mini-runs; must not be null
+     * @param resetPort       bridge to Bootstrap for status-reset-only operations; must
+     *                        not be null
+     * @param threadFactory  factory returning a ready-to-start worker thread; must not
+     *                       be null
+     * @param fxDispatcher   dispatcher that schedules a runnable on the JavaFX Application
+     *                       Thread; must not be null
+     * @param listener       GUI listener; must not be null
+     */
+    public GuiBatchRunCoordinator(GuiBatchRunLauncher launcher,
+                                  GuiMiniRunLauncher miniRunLauncher,
+                                  GuiResetDocumentStatusPort resetPort,
+                                  Function<Runnable, Thread> threadFactory,
+                                  Consumer<Runnable> fxDispatcher,
+                                  Listener listener) {
+        this(launcher, miniRunLauncher, resetPort, threadFactory, fxDispatcher, listener,
+                noOpHistoricalDocumentContextPort());
+    }
+
+    /**
+     * Creates the coordinator with all ports, custom thread factory, FX dispatcher,
+     * historical file name port, and an optional configuration file lock port.
+     * <p>
+     * This is the canonical constructor. All other constructors delegate here.
+     *
+     * @param launcher                      bridge to Bootstrap for regular batch runs; must not be null
+     * @param miniRunLauncher               bridge to Bootstrap for targeted mini-runs; must not be null
+     * @param resetPort                     bridge to Bootstrap for status-reset-only operations; must
+     *                                      not be null
+     * @param threadFactory                 factory returning a ready-to-start worker thread; must not
+     *                                      be null
+     * @param fxDispatcher                  dispatcher that schedules a runnable on the JavaFX Application
+     *                                      Thread; must not be null
+     * @param listener                      GUI listener; must not be null
+     * @param historicalDocumentContextPort port for resolving the historical AI-proposed filename for
+     *                                      skipped documents; must not be null
+     * @param configurationFileLockPort     optional OS-lock on the configuration file; when present,
+     *                                      acquired before each run and released in a finally block;
+     *                                      {@code null} is treated as empty
+     */
+    public GuiBatchRunCoordinator(GuiBatchRunLauncher launcher,
+                                  GuiMiniRunLauncher miniRunLauncher,
+                                  GuiResetDocumentStatusPort resetPort,
+                                  Function<Runnable, Thread> threadFactory,
+                                  Consumer<Runnable> fxDispatcher,
+                                  Listener listener,
+                                  GuiHistoricalDocumentContextPort historicalDocumentContextPort,
+                                  Optional<ConfigurationFileLockPort> configurationFileLockPort) {
+        this.launcher = Objects.requireNonNull(launcher, "launcher must not be null");
+        this.miniRunLauncher = Objects.requireNonNull(miniRunLauncher, "miniRunLauncher must not be null");
+        this.resetPort = Objects.requireNonNull(resetPort, "resetPort must not be null");
+        this.threadFactory = Objects.requireNonNull(threadFactory, "threadFactory must not be null");
+        this.fxDispatcher = Objects.requireNonNull(fxDispatcher, "fxDispatcher must not be null");
+        this.listener = Objects.requireNonNull(listener, "listener must not be null");
+        this.historicalDocumentContextPort = Objects.requireNonNull(
+                historicalDocumentContextPort, "historicalDocumentContextPort must not be null");
+        this.configurationFileLockPort =
+                Objects.requireNonNullElse(configurationFileLockPort, Optional.empty());
+    }
+
+    /**
+     * Backward-compatible constructor that omits the configuration file lock port.
+     * <p>
+     * Preserves existing callers that were written before the lock port was added.
+     * Delegates to the canonical constructor with {@code configurationFileLockPort} empty.
+     *
+     * @param launcher                      bridge to Bootstrap for regular batch runs; must not be null
+     * @param miniRunLauncher               bridge to Bootstrap for targeted mini-runs; must not be null
+     * @param resetPort                     bridge to Bootstrap for status-reset-only operations; must
+     *                                      not be null
+     * @param threadFactory                 factory returning a ready-to-start worker thread; must not
+     *                                      be null
+     * @param fxDispatcher                  dispatcher that schedules a runnable on the JavaFX Application
+     *                                      Thread; must not be null
+     * @param listener                      GUI listener; must not be null
+     * @param historicalDocumentContextPort port for resolving the historical AI-proposed filename for
+     *                                      skipped documents; must not be null
+     */
+    public GuiBatchRunCoordinator(GuiBatchRunLauncher launcher,
+                                  GuiMiniRunLauncher miniRunLauncher,
+                                  GuiResetDocumentStatusPort resetPort,
+                                  Function<Runnable, Thread> threadFactory,
+                                  Consumer<Runnable> fxDispatcher,
+                                  Listener listener,
+                                  GuiHistoricalDocumentContextPort historicalDocumentContextPort) {
+        this(launcher, miniRunLauncher, resetPort, threadFactory, fxDispatcher, listener,
+                historicalDocumentContextPort, Optional.empty());
+    }
+
+    /**
+     * Legacy constructor retained for backward compatibility with tests that do not
+     * require mini-run or reset capabilities.
+     *
+     * @param launcher       bridge to Bootstrap; must not be null
+     * @param threadFactory  factory returning a ready-to-start worker thread; must not
+     *                       be null
+     * @param fxDispatcher   dispatcher that schedules a runnable on the JavaFX Application
+     *                       Thread; must not be null
+     * @param listener       GUI listener; must not be null
+     */
+    public GuiBatchRunCoordinator(GuiBatchRunLauncher launcher,
+                                  Function<Runnable, Thread> threadFactory,
+                                  Consumer<Runnable> fxDispatcher,
+                                  Listener listener) {
+        this(launcher,
+                rejectingMiniRunLauncher(),
+                rejectingResetPort(),
+                threadFactory,
+                fxDispatcher,
+                listener);
+    }
+
+    /**
+     * Returns whether a run or reset is currently active.
+     *
+     * @return {@code true} while a worker thread is executing
+     */
+    public boolean isRunning() {
+        Thread worker = activeWorker.get();
+        return worker != null && worker.isAlive();
+    }
+
+    /**
+     * Starts a new regular run for the supplied configuration file.
+     * <p>
+     * Immediately returns once the worker thread has been started. All further progress
+     * is communicated through the configured {@link Listener} on the JavaFX Application
+     * Thread. An attempt to start a new run while another is still active is rejected
+     * with {@code false} and leaves the currently running batch untouched.
+     *
+     * @param configFilePath the configuration file the run shall read from; must not be
+     *                       {@code null}
+     * @return {@code true} when a new worker thread was started, {@code false} when a run
+     *         was already in progress
+     * @throws NullPointerException if {@code configFilePath} is {@code null}
+     */
+    public boolean start(Path configFilePath) {
+        Objects.requireNonNull(configFilePath, CONFIG_FILE_NOT_NULL);
+        if (isRunning()) {
+            return false;
+        }
+        cancellationRequested.set(false);
+        Runnable task = () -> executeRun(configFilePath);
+        return startWorker(task);
+    }
+
+    /**
+     * Starts a targeted mini-run for the supplied fingerprint filter.
+     * <p>
+     * The worker thread first delegates to the {@link GuiMiniRunLauncher} which applies
+     * the full processing pipeline to only the specified documents. Progress callbacks
+     * are forwarded to the {@link Listener} on the JavaFX Application Thread in the same
+     * way as for a regular run.
+     *
+     * @param configFilePath  the configuration file; must not be {@code null}
+     * @param fingerprintFilter the set of document fingerprints to process; must not be
+     *                          {@code null}
+     * @return {@code true} when a new worker thread was started, {@code false} when a run
+     *         was already in progress
+     * @throws NullPointerException if any argument is {@code null}
+     */
+    public boolean startMiniRun(Path configFilePath,
+                                Set<DocumentFingerprint> fingerprintFilter) {
+        Objects.requireNonNull(configFilePath, CONFIG_FILE_NOT_NULL);
+        Objects.requireNonNull(fingerprintFilter, "fingerprintFilter must not be null");
+        if (isRunning()) {
+            return false;
+        }
+        cancellationRequested.set(false);
+        Runnable task = () -> executeMiniRun(configFilePath, fingerprintFilter);
+        return startWorker(task);
+    }
+
+    /**
+     * Starts a reprocessing operation: resets the database status of the specified
+     * fingerprints and immediately launches a targeted mini-run for them.
+     * <p>
+     * This method is the preferred entry point for "Erneut verarbeiten" (reprocess)
+     * actions in the GUI. It ensures that documents marked as FAILED_FINAL or otherwise
+     * ineligible for processing are reset before the mini-run begins, so they are
+     * reprocessed rather than skipped.
+     * <p>
+     * The reset executes synchronously on the caller's thread before the worker thread
+     * is started. This guarantees that the mini-run sees the documents in a
+     * reprocessable state.
+     *
+     * @param configFilePath  the configuration file; must not be {@code null}
+     * @param fingerprintFilter the set of document fingerprints to reset and process;
+     *                          must not be {@code null}
+     * @return {@code true} when a new worker thread was started, {@code false} when a run
+     *         was already in progress or when the reset failed for all fingerprints
+     * @throws NullPointerException if any argument is {@code null}
+     */
+    public boolean startReprocessing(Path configFilePath,
+                                     Set<DocumentFingerprint> fingerprintFilter) {
+        Objects.requireNonNull(configFilePath, CONFIG_FILE_NOT_NULL);
+        Objects.requireNonNull(fingerprintFilter, "fingerprintFilter must not be null");
+        if (isRunning()) {
+            return false;
+        }
+        // Reset the database status synchronously before starting the mini-run.
+        // This ensures that documents are not skipped due to FAILED_FINAL or other
+        // terminal states.
+        LOG.info("GUI-Erneut-Verarbeiten: Starte Status-Reset für {} Dokument(e), Konfiguration={}.",
+                fingerprintFilter.size(), configFilePath);
+        ResetDocumentStatusResult resetResult = resetPort.reset(configFilePath, fingerprintFilter);
+        LOG.info("GUI-Erneut-Verarbeiten: Status-Reset abgeschlossen – {} erfolgreich, {} fehlgeschlagen.",
+                resetResult.successCount(), resetResult.failureCount());
+        if (resetResult.successCount() == 0) {
+            LOG.warn("GUI-Reprocessing: Reset für alle {} Dokumente fehlgeschlagen; "
+                    + "Mini-Lauf wird nicht gestartet.", fingerprintFilter.size());
+            return false;
+        }
+        LOG.info("GUI-Reprocessing: {} von {} Dokumenten erfolgreich zurückgesetzt.",
+                resetResult.successCount(), resetResult.requestedCount());
+        // Now start the mini-run with the reset fingerprints.
+        return startMiniRun(configFilePath, fingerprintFilter);
+    }
+
+    /**
+     * Starts a reset-only operation for the supplied fingerprint set.
+     * <p>
+     * The worker thread calls the {@link GuiResetDocumentStatusPort} to delete all
+     * persistence data for the specified fingerprints. No reprocessing run is triggered.
+     * On completion the {@link Listener#onResetCompleted(ResetDocumentStatusResult)} callback
+     * is invoked on the JavaFX Application Thread.
+     *
+     * @param configFilePath the configuration file that identifies the database; must not
+     *                       be {@code null}
+     * @param fingerprints   the set of document fingerprints to reset; must not be
+     *                       {@code null}
+     * @return {@code true} when a new worker thread was started, {@code false} when a run
+     *         was already in progress
+     * @throws NullPointerException if any argument is {@code null}
+     */
+    public boolean startReset(Path configFilePath, Set<DocumentFingerprint> fingerprints) {
+        Objects.requireNonNull(configFilePath, CONFIG_FILE_NOT_NULL);
+        Objects.requireNonNull(fingerprints, "fingerprints must not be null");
+        if (isRunning()) {
+            return false;
+        }
+        // Reset does not support cancellation; set the flag to false so the
+        // running state is consistent with the pattern used by run operations.
+        cancellationRequested.set(false);
+        Runnable task = () -> executeReset(configFilePath, fingerprints);
+        return startWorker(task);
+    }
+
+    /**
+     * Requests soft-stop cancellation of the currently running batch or mini-run.
+     * <p>
+     * The flag is honoured between candidates — the candidate that is currently being
+     * processed is always completed in full and persisted before the run ends. Calling
+     * this method when no run is active has no effect. Reset operations ignore this flag.
+     */
+    public void requestCancellation() {
+        if (isRunning()) {
+            cancellationRequested.set(true);
+        }
+    }
+
+    /**
+     * Returns whether cancellation has been requested for the current (or last) run.
+     *
+     * @return {@code true} when a cancellation request is pending or was pending when
+     *         the last run ended; {@code false} before the first run
+     */
+    public boolean isCancellationRequested() {
+        return cancellationRequested.get();
+    }
+
+    // -------------------------------------------------------------------------
+    // Worker helpers
+    // -------------------------------------------------------------------------
+
+    private boolean startWorker(Runnable task) {
+        Thread worker = threadFactory.apply(task);
+        Objects.requireNonNull(worker, "threadFactory must not return null");
+        activeWorker.set(worker);
+        worker.start();
+        return true;
+    }
+
+    private void executeRun(Path configFilePath) {
+        LOG.info("GUI-Verarbeitungslauf: Worker-Thread gestartet für Konfiguration {}.",
+                configFilePath);
+        observerSummary.set(null);
+
+        if (configurationFileLockPort.isPresent()) {
+            try {
+                configurationFileLockPort.get().acquireLock();
+            } catch (ConfigurationFileLockException e) {
+                LOG.warn("GUI-Verarbeitungslauf: Konfigurationsdatei gesperrt – Lauf abgebrochen: {}",
+                        e.getMessage());
+                fxDispatcher.accept(() -> showLockErrorAlert());
+                finishRun(GuiBatchRunLaunchOutcome.rejected(
+                        "Konfigurationsdatei gesperrt – Lauf wurde abgebrochen."));
+                return;
+            }
+        }
+
+        try {
+            BatchRunProgressObserver observer = buildDispatchingObserver(configFilePath);
+            BatchRunCancellationToken token = cancellationRequested::get;
+            GuiBatchRunLaunchOutcome outcome;
+            try {
+                outcome = launcher.launch(configFilePath, observer, token);
+                if (outcome == null) {
+                    outcome = GuiBatchRunLaunchOutcome.failedAfterStart(
+                            "Launcher hat kein Ergebnis geliefert.");
+                }
+            } catch (RuntimeException e) {
+                LOG.error("GUI-Verarbeitungslauf: Unerwarteter Fehler im Worker-Thread: {}",
+                        e.getMessage(), e);
+                outcome = GuiBatchRunLaunchOutcome.failedAfterStart(
+                        "Unerwarteter technischer Fehler: "
+                                + (e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage()));
+            }
+            finishRun(outcome);
+        } finally {
+            configurationFileLockPort.ifPresent(ConfigurationFileLockPort::releaseLock);
+        }
+    }
+
+    private void executeMiniRun(Path configFilePath, Set<DocumentFingerprint> fingerprintFilter) {
+        LOG.info("GUI-Mini-Verarbeitungslauf: Worker-Thread gestartet für {} Dokument(e), "
+                + "Konfiguration {}.", fingerprintFilter.size(), configFilePath);
+        observerSummary.set(null);
+
+        if (configurationFileLockPort.isPresent()) {
+            try {
+                configurationFileLockPort.get().acquireLock();
+            } catch (ConfigurationFileLockException e) {
+                LOG.warn("GUI-Mini-Verarbeitungslauf: Konfigurationsdatei gesperrt – Lauf abgebrochen: {}",
+                        e.getMessage());
+                fxDispatcher.accept(() -> showLockErrorAlert());
+                finishRun(GuiBatchRunLaunchOutcome.rejected(
+                        "Konfigurationsdatei gesperrt – Mini-Lauf wurde abgebrochen."));
+                return;
+            }
+        }
+
+        try {
+            BatchRunProgressObserver observer = buildDispatchingObserver(configFilePath);
+            BatchRunCancellationToken token = cancellationRequested::get;
+            GuiBatchRunLaunchOutcome outcome;
+            try {
+                outcome = miniRunLauncher.launch(configFilePath, fingerprintFilter, observer, token);
+                if (outcome == null) {
+                    outcome = GuiBatchRunLaunchOutcome.failedAfterStart(
+                            "Mini-Run-Launcher hat kein Ergebnis geliefert.");
+                }
+            } catch (RuntimeException e) {
+                LOG.error("GUI-Mini-Verarbeitungslauf: Unerwarteter Fehler im Worker-Thread: {}",
+                        e.getMessage(), e);
+                outcome = GuiBatchRunLaunchOutcome.failedAfterStart(
+                        "Unerwarteter technischer Fehler im Mini-Lauf: "
+                                + (e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage()));
+            }
+            finishRun(outcome);
+        } finally {
+            configurationFileLockPort.ifPresent(ConfigurationFileLockPort::releaseLock);
+        }
+    }
+
+    private void executeReset(Path configFilePath, Set<DocumentFingerprint> fingerprints) {
+        LOG.info("GUI-Status-Reset: Worker-Thread gestartet für {} Dokument(e), "
+                + "Konfiguration {}.", fingerprints.size(), configFilePath);
+        ResetDocumentStatusResult result;
+        try {
+            result = resetPort.reset(configFilePath, fingerprints);
+            if (result == null) {
+                result = new ResetDocumentStatusResult(fingerprints.size(),
+                        Set.of(), allFailureMap(fingerprints,
+                                "Reset-Port hat kein Ergebnis geliefert."));
+            }
+        } catch (RuntimeException e) {
+            LOG.error("GUI-Status-Reset: Unerwarteter Fehler im Worker-Thread: {}",
+                    e.getMessage(), e);
+            String msg = "Unerwarteter technischer Fehler beim Status-Reset: "
+                    + (e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage());
+            result = new ResetDocumentStatusResult(fingerprints.size(),
+                    Set.of(), allFailureMap(fingerprints, msg));
+        }
+        ResetDocumentStatusResult finalResult = result;
+        activeWorker.set(null);
+        fxDispatcher.accept(() -> listener.onResetCompleted(finalResult));
+        LOG.info("GUI-Status-Reset: Worker-Thread beendet.");
+    }
+
+    private void finishRun(GuiBatchRunLaunchOutcome outcome) {
+        RunSummary summary = observerSummary.get();
+        if (summary == null) {
+            summary = new RunSummary(0, 0, 0);
+        }
+        GuiBatchRunLaunchOutcome finalOutcome = outcome;
+        RunSummary finalSummary = summary;
+        activeWorker.set(null);
+        fxDispatcher.accept(() -> listener.onRunEnded(finalSummary, finalOutcome));
+        LOG.info("GUI-Verarbeitungslauf: Worker-Thread beendet.");
+    }
+
+    private static java.util.Map<DocumentFingerprint, String> allFailureMap(
+            Set<DocumentFingerprint> fingerprints, String message) {
+        java.util.Map<DocumentFingerprint, String> map = new java.util.HashMap<>();
+        for (DocumentFingerprint fp : fingerprints) {
+            map.put(fp, message);
+        }
+        return map;
+    }
+
+    /**
+     * Captures the final summary supplied by the application layer. Written on the
+     * worker thread; read only after the run has ended.
+     */
+    private final AtomicReference<RunSummary> observerSummary = new AtomicReference<>();
+
+    private BatchRunProgressObserver buildDispatchingObserver(Path configFilePath) {
+        return new BatchRunProgressObserver() {
+            @Override
+            public void onRunStarted(RunId runId, int totalCandidates) {
+                fxDispatcher.accept(() -> listener.onRunStarted(runId, totalCandidates));
+            }
+
+            @Override
+            public void onDocumentCompleted(DocumentCompletionEvent event) {
+                GuiBatchRunResultRow row = toRow(event, configFilePath);
+                fxDispatcher.accept(() -> listener.onDocumentCompleted(row));
+            }
+
+            @Override
+            public void onRunEnded(RunSummary summary) {
+                observerSummary.set(summary);
+                // Kein FX-Dispatch hier: der Worker-Thread ruft onRunEnded über finishRun()
+                // auf, nachdem der Launcher zurückgekehrt ist.
+            }
+        };
+    }
+
+    /**
+     * Wandelt ein {@link DocumentCompletionEvent} in eine {@link GuiBatchRunResultRow} um.
+     * <p>
+     * Für übersprungene Dokumente ({@link DocumentCompletionStatus#SKIPPED_ALREADY_PROCESSED}
+     * und {@link DocumentCompletionStatus#SKIPPED_FINAL_FAILURE}) wird der historische
+     * Verarbeitungskontext über den {@link GuiHistoricalDocumentContextPort} nachgeladen.
+     * Für SKIPPED_ALREADY_PROCESSED wird der letzte Zieldateiname aus dem Kontext als
+     * {@code finalName} übernommen. Schlägt die Abfrage fehl, bleibt der Kontext leer.
+     * Die Methode läuft auf dem Worker-Thread.
+     *
+     * @param event          das abgeschlossene Kandidatenereignis; darf nicht {@code null} sein
+     * @param configFilePath Pfad zur aktiven Konfigurationsdatei; darf nicht {@code null} sein
+     * @return eine neue {@link GuiBatchRunResultRow}; nie {@code null}
+     */
+    private GuiBatchRunResultRow toRow(DocumentCompletionEvent event, Path configFilePath) {
+        Optional<String> finalName = event.finalFileName() == null
+                ? Optional.empty() : Optional.of(event.finalFileName());
+        Optional<LocalDate> date = event.resolvedDate() == null
+                ? Optional.empty() : Optional.of(event.resolvedDate());
+        Optional<String> reasoning = event.aiReasoning() == null || event.aiReasoning().isBlank()
+                ? Optional.empty() : Optional.of(event.aiReasoning());
+        Optional<String> failureMessage = event.failureMessage() == null || event.failureMessage().isBlank()
+                ? Optional.empty() : Optional.of(event.failureMessage());
+        Duration duration = event.processingDuration();
+
+        // Historischen Kontext für übersprungene Dokumente nachladen
+        boolean isSkipped = event.status() == DocumentCompletionStatus.SKIPPED_ALREADY_PROCESSED
+                || event.status() == DocumentCompletionStatus.SKIPPED_FINAL_FAILURE;
+        Optional<HistoricalDocumentContext> historicalContext = Optional.empty();
+        if (isSkipped) {
+            try {
+                historicalContext = historicalDocumentContextPort
+                        .resolveHistoricalDocumentContext(configFilePath, event.fingerprint());
+            } catch (Exception e) {
+                LOG.warn("Historischer Kontext konnte nicht abgefragt werden für {}: {}",
+                        event.originalFileName(), e.getMessage(), e);
+            }
+            // Zieldateiname für SKIPPED_ALREADY_PROCESSED aus Kontext übernehmen
+            if (finalName.isEmpty()) {
+                finalName = historicalContext
+                        .flatMap(HistoricalDocumentContext::lastTargetFileName);
+            }
+        }
+
+        return new GuiBatchRunResultRow(
+                event.originalFileName(),
+                event.fingerprint(),
+                event.status(),
+                finalName,
+                Optional.empty(),
+                date,
+                reasoning,
+                failureMessage,
+                duration,
+                false,
+                historicalContext);
+    }
+
+    private static void showLockErrorAlert() {
+        Alert alert = new Alert(Alert.AlertType.ERROR);
+        alert.setTitle("Verarbeitungslauf nicht möglich");
+        alert.setHeaderText("Konfigurationsdatei gesperrt");
+        alert.setContentText(
+                "Der Verarbeitungslauf konnte nicht gestartet werden, da die "
+                + "Konfigurationsdatei nicht gesperrt werden konnte.\n\n"
+                + "Mögliche Ursache: Der automatische Scheduler ist aktiv oder "
+                + "ein anderer Prozess hält die Datei belegt.\n\n"
+                + "Bitte stoppen Sie den Scheduler und versuchen Sie es erneut.");
+        alert.showAndWait();
+    }
+
+    private static GuiHistoricalDocumentContextPort noOpHistoricalDocumentContextPort() {
+        return (configPath, fingerprint) -> Optional.empty();
+    }
+
+    private static Function<Runnable, Thread> defaultThreadFactory() {
+        return task -> {
+            Thread thread = new Thread(task, WORKER_THREAD_NAME);
+            thread.setDaemon(true);
+            return thread;
+        };
+    }
+
+    private static Consumer<Runnable> defaultFxDispatcher() {
+        return Platform::runLater;
+    }
+
+    private static GuiMiniRunLauncher rejectingMiniRunLauncher() {
+        return (configFilePath, fingerprintFilter, observer, cancellationToken) ->
+                GuiBatchRunLaunchOutcome.rejected(
+                        "Kein Mini-Run-Launcher in diesem Kontext verfügbar.");
+    }
+
+    private static GuiResetDocumentStatusPort rejectingResetPort() {
+        return (configFilePath, fingerprints) ->
+                new ResetDocumentStatusResult(fingerprints.size(),
+                        Set.of(), allFailureMapStatic(fingerprints,
+                                "Kein Reset-Port in diesem Kontext verfügbar."));
+    }
+
+    private static java.util.Map<DocumentFingerprint, String> allFailureMapStatic(
+            Set<DocumentFingerprint> fingerprints, String message) {
+        java.util.Map<DocumentFingerprint, String> map = new java.util.HashMap<>();
+        for (DocumentFingerprint fp : fingerprints) {
+            map.put(fp, message);
+        }
+        return map;
+    }
+}
@@ -0,0 +1,77 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * Immutable result of a single batch run launched from the GUI.
+ * <p>
+ * The outcome reports to the tab whether the run finished normally, could not even be
+ * started (hard failure), or ended because of an unexpected exception. The GUI uses this
+ * to transition between its "laufend" and "bereit"/"Fehler" states.
+ *
+ * <h2>Fields</h2>
+ * <ul>
+ *   <li>{@link #successfullyStarted()} — {@code true} when the launcher managed to enter
+ *       the batch execution phase; {@code false} when the run was rejected before any
+ *       candidate could be processed (e.g. configuration invalid, lock held, SQLite
+ *       unavailable).</li>
+ *   <li>{@link #batchCompletedNormally()} — {@code true} when the run returned from the
+ *       batch use case with a normal outcome (whether empty, partial, or full). Only
+ *       meaningful when {@link #successfullyStarted()} is also {@code true}.</li>
+ *   <li>{@link #failureMessage()} — present when either the run could not start or an
+ *       unexpected technical exception terminated it. Empty when the run completed
+ *       normally.</li>
+ * </ul>
+ */
+public record GuiBatchRunLaunchOutcome(
+        boolean successfullyStarted,
+        boolean batchCompletedNormally,
+        Optional<String> failureMessage) {
+
+    /**
+     * Compact constructor normalising the failure message holder.
+     */
+    public GuiBatchRunLaunchOutcome {
+        failureMessage = Objects.requireNonNullElse(failureMessage, Optional.empty());
+    }
+
+    /**
+     * Returns an outcome describing a run that finished normally.
+     *
+     * @return a started + completed outcome without failure message
+     */
+    public static GuiBatchRunLaunchOutcome completed() {
+        return new GuiBatchRunLaunchOutcome(true, true, Optional.empty());
+    }
+
+    /**
+     * Returns an outcome describing a run that could not start because of a hard
+     * configuration, persistence, or lock failure.
+     *
+     * @param failureMessage the user-visible German failure description; must not be blank
+     * @return a rejected-startup outcome carrying the supplied message
+     */
+    public static GuiBatchRunLaunchOutcome rejected(String failureMessage) {
+        Objects.requireNonNull(failureMessage, "failureMessage must not be null");
+        if (failureMessage.isBlank()) {
+            throw new IllegalArgumentException("failureMessage must not be blank");
+        }
+        return new GuiBatchRunLaunchOutcome(false, false, Optional.of(failureMessage));
+    }
+
+    /**
+     * Returns an outcome describing a run that started but ended due to an unexpected
+     * technical exception.
+     *
+     * @param failureMessage the user-visible German failure description; must not be blank
+     * @return an aborted-after-start outcome carrying the supplied message
+     */
+    public static GuiBatchRunLaunchOutcome failedAfterStart(String failureMessage) {
+        Objects.requireNonNull(failureMessage, "failureMessage must not be null");
+        if (failureMessage.isBlank()) {
+            throw new IllegalArgumentException("failureMessage must not be blank");
+        }
+        return new GuiBatchRunLaunchOutcome(true, false, Optional.of(failureMessage));
+    }
+}
@@ -0,0 +1,51 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.nio.file.Path;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.BatchRunCancellationToken;
+import de.gecheckt.pdf.umbenenner.application.port.in.BatchRunProgressObserver;
+
+/**
+ * Inbound bridge implemented by Bootstrap to let the GUI execute a batch run against a
+ * stored configuration file.
+ * <p>
+ * The launcher performs the complete headless startup sequence (legacy migration, config
+ * loading, validation, SQLite schema initialisation, run-lock, use-case wiring, execution)
+ * for the supplied configuration path while forwarding progress callbacks and honouring
+ * the supplied cancellation token. It reuses the very same application ports and
+ * persistence pipeline as a Task-Scheduler-triggered headless run; only the presentation
+ * side (the GUI) differs.
+ *
+ * <h2>Threading</h2>
+ * <p>
+ * Implementations must be safe to call from a non-UI worker thread. They must not touch
+ * the JavaFX Application Thread themselves; all JavaFX-specific scheduling is the
+ * caller's concern. The call blocks until the run terminates (normally, after a
+ * cancellation, or after a hard failure).
+ *
+ * <h2>Exception contract</h2>
+ * <p>
+ * Implementations must not propagate checked exceptions. Unexpected runtime exceptions
+ * should be caught, logged, and returned as a
+ * {@link GuiBatchRunLaunchOutcome#failedAfterStart(String)} outcome to keep the GUI in a
+ * well-defined terminal state.
+ */
+@FunctionalInterface
+public interface GuiBatchRunLauncher {
+
+    /**
+     * Executes exactly one batch run against the supplied configuration file.
+     *
+     * @param configFilePath    path of the {@code .properties} file to run against;
+     *                          must not be {@code null}; must exist and be readable
+     * @param observer          observer receiving start/completion/end callbacks; must
+     *                          not be {@code null}
+     * @param cancellationToken cancellation token the run polls between candidates; must
+     *                          not be {@code null}
+     * @return a description of how the run terminated; never {@code null}
+     */
+    GuiBatchRunLaunchOutcome launch(
+            Path configFilePath,
+            BatchRunProgressObserver observer,
+            BatchRunCancellationToken cancellationToken);
+}
@@ -0,0 +1,285 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.time.Duration;
+import java.time.LocalDate;
+import java.util.Objects;
+import java.util.Optional;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus;
+import de.gecheckt.pdf.umbenenner.application.port.in.HistoricalDocumentContext;
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+
+/**
+ * Immutable view model for a single row in the processing-run result list.
+ * <p>
+ * Each completed candidate becomes exactly one row. The row carries only the information
+ * that is shown in the list and the side panel; it is decoupled from the persistence
+ * model so later GUI layers can render it without reaching back into the application
+ * layer.
+ * <p>
+ * The {@code fingerprint} field is the content-based identity of the document and is
+ * used as a stable key for in-place row updates during a targeted mini-run.
+ * <p>
+ * When {@code resetPending} is {@code true} the row represents a document whose
+ * persistence status has been deleted but which has not yet been reprocessed. The status
+ * icon and label reflect this special state instead of the original processing outcome.
+ *
+ * @param originalFileName   the source filename as reported by the use case; never
+ *                           {@code null} or blank
+ * @param fingerprint        the content-based identity of the processed document; never
+ *                           {@code null}
+ * @param status             the aggregated completion status; never {@code null}
+ * @param finalFileName      the final target filename when the row represents a successful
+ *                           rename; empty otherwise
+ * @param correctedFileName  Der manuell korrigierte Zieldateiname, falls der Benutzer den
+ *                           KI-Vorschlag in der GUI bearbeitet und gespeichert hat.
+ *                           Leer bei unverändertem KI-Vorschlag.
+ * @param resolvedDate       the resolved document date when the row represents a successful
+ *                           rename; empty otherwise
+ * @param aiReasoning        the AI reasoning shown in the side panel; empty when no
+ *                           reasoning is available for this row
+ * @param aiFailureMessage   eine lesbare Fehlerbeschreibung, wenn der KI-Aufruf oder die
+ *                           Verarbeitung fehlgeschlagen ist; leer bei Erfolg und
+ *                           übersprungenen Dokumenten
+ * @param processingDuration wall-clock duration spent on the candidate in this run;
+ *                           never {@code null} and never negative
+ * @param resetPending       {@code true} when the document's persistence status has been
+ *                           reset and is awaiting the next processing run
+ * @param historicalContext  historischer Verarbeitungskontext für übersprungene Dokumente;
+ *                           leer bei nicht-übersprungenen Zeilen
+ */
+public record GuiBatchRunResultRow(
+        String originalFileName,
+        DocumentFingerprint fingerprint,
+        DocumentCompletionStatus status,
+        Optional<String> finalFileName,
+        Optional<String> correctedFileName,
+        Optional<LocalDate> resolvedDate,
+        Optional<String> aiReasoning,
+        Optional<String> aiFailureMessage,
+        Duration processingDuration,
+        boolean resetPending,
+        Optional<HistoricalDocumentContext> historicalContext) {
+
+    /**
+     * Label shown in the status column when a document's persistence status has been
+     * reset and is waiting for the next processing run.
+     */
+    static final String RESET_PENDING_LABEL = "Zurückgesetzt – wartet auf nächsten Lauf";
+
+    /**
+     * Icon shown in the status column when a document's persistence status has been reset.
+     */
+    static final String RESET_PENDING_ICON = "⟳"; // ⟳ CLOCKWISE GAPPED CIRCLE ARROW
+
+    /**
+     * Compact constructor normalising optional holders and validating mandatory fields.
+     *
+     * @throws NullPointerException     if {@code originalFileName}, {@code fingerprint},
+     *                                  {@code status} or {@code processingDuration} is
+     *                                  {@code null}
+     * @throws IllegalArgumentException if {@code originalFileName} is blank or
+     *                                  {@code processingDuration} is negative
+     */
+    public GuiBatchRunResultRow {
+        Objects.requireNonNull(originalFileName, "originalFileName must not be null");
+        if (originalFileName.isBlank()) {
+            throw new IllegalArgumentException("originalFileName must not be blank");
+        }
+        Objects.requireNonNull(fingerprint, "fingerprint must not be null");
+        Objects.requireNonNull(status, "status must not be null");
+        finalFileName = Objects.requireNonNullElse(finalFileName, Optional.empty());
+        correctedFileName = Objects.requireNonNullElse(correctedFileName, Optional.empty());
+        resolvedDate = Objects.requireNonNullElse(resolvedDate, Optional.empty());
+        aiReasoning = Objects.requireNonNullElse(aiReasoning, Optional.empty());
+        aiFailureMessage = Objects.requireNonNullElse(aiFailureMessage, Optional.empty());
+        Objects.requireNonNull(processingDuration, "processingDuration must not be null");
+        if (processingDuration.isNegative()) {
+            throw new IllegalArgumentException("processingDuration must not be negative");
+        }
+        historicalContext = Objects.requireNonNullElse(historicalContext, Optional.empty());
+    }
+
+    /**
+     * Bequem-Konstruktor für Zeilen, die weder einen manuell korrigierten Dateinamen
+     * tragen noch im reset-pending-Zustand stehen und keinen historischen Kontext haben.
+     *
+     * @param originalFileName   the source filename; never {@code null} or blank
+     * @param fingerprint        the content-based document identity; never {@code null}
+     * @param status             the aggregated completion status; never {@code null}
+     * @param finalFileName      the final target filename; may be {@code null} (treated as
+     *                           empty)
+     * @param resolvedDate       the resolved document date; may be {@code null} (treated as
+     *                           empty)
+     * @param aiReasoning        the AI reasoning text; may be {@code null} (treated as
+     *                           empty)
+     * @param aiFailureMessage   eine lesbare Fehlerbeschreibung bei Fehler; may be
+     *                           {@code null} (treated as empty)
+     * @param processingDuration the wall-clock processing duration; never {@code null}
+     */
+    public GuiBatchRunResultRow(
+            String originalFileName,
+            DocumentFingerprint fingerprint,
+            DocumentCompletionStatus status,
+            Optional<String> finalFileName,
+            Optional<LocalDate> resolvedDate,
+            Optional<String> aiReasoning,
+            Optional<String> aiFailureMessage,
+            Duration processingDuration) {
+        this(originalFileName, fingerprint, status, finalFileName, Optional.empty(),
+                resolvedDate, aiReasoning, aiFailureMessage, processingDuration, false,
+                Optional.empty());
+    }
+
+    /**
+     * Bequem-Konstruktor mit explizitem {@code resetPending}-Flag, aber ohne manuell
+     * korrigierten Dateinamen und ohne historischen Kontext.
+     *
+     * @param originalFileName   the source filename; never {@code null} or blank
+     * @param fingerprint        the content-based document identity; never {@code null}
+     * @param status             the aggregated completion status; never {@code null}
+     * @param finalFileName      the final target filename; may be {@code null} (treated as
+     *                           empty)
+     * @param resolvedDate       the resolved document date; may be {@code null} (treated as
+     *                           empty)
+     * @param aiReasoning        the AI reasoning text; may be {@code null} (treated as
+     *                           empty)
+     * @param aiFailureMessage   eine lesbare Fehlerbeschreibung bei Fehler; may be
+     *                           {@code null} (treated as empty)
+     * @param processingDuration the wall-clock processing duration; never {@code null}
+     * @param resetPending       {@code true} wenn der Stammsatz zurückgesetzt wurde
+     */
+    public GuiBatchRunResultRow(
+            String originalFileName,
+            DocumentFingerprint fingerprint,
+            DocumentCompletionStatus status,
+            Optional<String> finalFileName,
+            Optional<LocalDate> resolvedDate,
+            Optional<String> aiReasoning,
+            Optional<String> aiFailureMessage,
+            Duration processingDuration,
+            boolean resetPending) {
+        this(originalFileName, fingerprint, status, finalFileName, Optional.empty(),
+                resolvedDate, aiReasoning, aiFailureMessage, processingDuration, resetPending,
+                Optional.empty());
+    }
+
+    /**
+     * Creates a reset-pending copy of the supplied row, preserving the original filename
+     * and fingerprint while marking the row as awaiting the next processing run.
+     * <p>
+     * The returned row has {@code resetPending == true}. Its {@code statusIcon()} and
+     * {@code statusLabel()} reflect the reset state.
+     *
+     * @param previousRow the row to copy; must not be {@code null}
+     * @return a new row with the same filename and fingerprint, {@code resetPending == true}
+     * @throws NullPointerException if {@code previousRow} is {@code null}
+     */
+    public static GuiBatchRunResultRow resetMarker(GuiBatchRunResultRow previousRow) {
+        Objects.requireNonNull(previousRow, "previousRow must not be null");
+        return new GuiBatchRunResultRow(
+                previousRow.originalFileName(),
+                previousRow.fingerprint(),
+                previousRow.status(),
+                Optional.empty(),
+                Optional.empty(),
+                Optional.empty(),
+                Optional.empty(),
+                Optional.empty(),
+                Duration.ZERO,
+                true,
+                Optional.empty());
+    }
+
+    /**
+     * Gibt das Status-Icon für diese Zeile als Unicode-Zeichen zurück, das in JavaFX
+     * unter Windows zuverlässig dargestellt wird (16px, bold).
+     * <p>
+     * Wenn {@code resetPending} den Wert {@code true} hat, wird unabhängig vom
+     * eigentlichen Status das Reset-Icon zurückgegeben.
+     * <p>
+     * Die Icon-Werte stammen aus {@link ProcessingStatusPresentation}.
+     *
+     * @return das entsprechende Status-Zeichen
+     */
+    public String statusIcon() {
+        if (resetPending) {
+            return RESET_PENDING_ICON;
+        }
+        return ProcessingStatusPresentation.iconFor(status);
+    }
+
+    /**
+     * Gibt die CSS-Farbe für das Status-Icon dieser Zeile zurück.
+     * <p>
+     * Wenn {@code resetPending} den Wert {@code true} hat, wird unabhängig vom
+     * eigentlichen Status die Reset-Farbe zurückgegeben.
+     * <p>
+     * Farbe ist niemals das einzige Unterscheidungsmerkmal – {@link #statusIcon()} und
+     * {@link #statusTooltip()} beschreiben den Status auch ohne Farbwahrnehmung eindeutig.
+     * Die Farbwerte stammen aus {@link ProcessingStatusPresentation}.
+     *
+     * @return die entsprechende CSS-Hex-Farbe (z. B. {@code "#2e7d32"})
+     */
+    public String statusColor() {
+        if (resetPending) {
+            return "#757575"; // Grau für Reset-pending
+        }
+        return ProcessingStatusPresentation.cssColorFor(status);
+    }
+
+    /**
+     * Gibt den deutschsprachigen Tooltip-Text für den Verarbeitungsstatus dieser Zeile zurück.
+     * <p>
+     * Wenn {@code resetPending} den Wert {@code true} hat, wird ein Tooltip für den
+     * Reset-Zustand zurückgegeben.
+     * <p>
+     * Der Tooltip-Text beschreibt den Status vollständig ohne Farbe. Die Texte stammen
+     * aus {@link ProcessingStatusPresentation}.
+     *
+     * @return der Tooltip-Text; nie leer
+     */
+    public String statusTooltip() {
+        if (resetPending) {
+            return RESET_PENDING_LABEL;
+        }
+        return ProcessingStatusPresentation.tooltipFor(status);
+    }
+
+    /**
+     * Returns the human-readable status label for this row.
+     * <p>
+     * When {@code resetPending} is {@code true} the reset-pending label is returned
+     * regardless of the underlying status.
+     *
+     * @return a non-null German status label
+     */
+    public String statusLabel() {
+        if (resetPending) {
+            return RESET_PENDING_LABEL;
+        }
+        return switch (status) {
+            case SUCCESS -> "Erfolgreich";
+            case FAILED_RETRYABLE -> "Fehlgeschlagen (wiederholbar)";
+            case FAILED_PERMANENT -> "Fehlgeschlagen (dauerhaft)";
+            case SKIPPED_ALREADY_PROCESSED -> "Übersprungen (bereits verarbeitet)";
+            case SKIPPED_FINAL_FAILURE -> "Übersprungen (endgültig fehlgeschlagen)";
+        };
+    }
+
+    /**
+     * Liefert den aktuell wirksamen Zieldateinamen: falls der Benutzer den KI-Vorschlag
+     * manuell korrigiert und gespeichert hat, wird der korrigierte Name geliefert,
+     * ansonsten der ursprüngliche KI-Vorschlag {@link #finalFileName()}.
+     * <p>
+     * Die Tabellenspalte „Neuer Dateiname" bindet an diesen Wert.
+     *
+     * @return den aktuell anzuzeigenden Zieldateinamen; leer wenn kein Name vorliegt
+     */
+    public Optional<String> effectiveFileName() {
+        if (correctedFileName.isPresent()) {
+            return correctedFileName;
+        }
+        return finalFileName;
+    }
+}
@@ -0,0 +1,42 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.nio.file.Path;
+import java.util.Optional;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.HistoricalDocumentContext;
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+
+/**
+ * GUI-interner Port zum Abfragen des historischen Verarbeitungskontexts einer Quelldatei.
+ * <p>
+ * Wird im Verarbeitungslauf-Tab genutzt, um für übersprungene Dokumente
+ * ({@link de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus#SKIPPED_ALREADY_PROCESSED}
+ * und
+ * {@link de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus#SKIPPED_FINAL_FAILURE})
+ * den historischen Kontext nachzuschlagen. Der Kontext wird im Detailbereich des
+ * Verarbeitungslauf-Tabs angezeigt.
+ * <p>
+ * Die Bootstrap-Schicht liefert die konkrete Implementierung. Sie lädt die
+ * Konfiguration aus {@code configFilePath}, baut den zugehörigen Use-Case auf und
+ * gibt das Ergebnis zurück. Technische Fehler beim Laden oder Abfragen werden intern
+ * abgefangen und als leeres {@link Optional} zurückgegeben.
+ * <p>
+ * Die Implementierung läuft auf dem Worker-Thread des {@link GuiBatchRunCoordinator}
+ * und darf blockieren.
+ */
+@FunctionalInterface
+public interface GuiHistoricalDocumentContextPort {
+
+    /**
+     * Gibt den historischen Verarbeitungskontext für das durch {@code fingerprint}
+     * identifizierte Dokument zurück, oder ein leeres {@link Optional}, wenn kein
+     * Kontext verfügbar ist.
+     *
+     * @param configFilePath Pfad zur aktiven {@code .properties}-Konfigurationsdatei;
+     *                       darf nicht {@code null} sein
+     * @param fingerprint    inhaltsbasierte Dokumentenidentität; darf nicht {@code null} sein
+     * @return historischer Kontext des Dokuments, oder leer wenn nicht verfügbar
+     */
+    Optional<HistoricalDocumentContext> resolveHistoricalDocumentContext(
+            Path configFilePath, DocumentFingerprint fingerprint);
+}
@@ -0,0 +1,38 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.nio.file.Path;
+import java.util.Optional;
+
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+
+/**
+ * GUI-interner Port zum Abfragen des historischen KI-Dateinamens einer Quelldatei.
+ * <p>
+ * Wird im Verarbeitungslauf-Tab genutzt, um für übersprungene Dokumente
+ * ({@link de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus#SKIPPED})
+ * den aus einem früheren Lauf bekannten Zieldateinamen nachzuschlagen und in der Spalte
+ * „Neuer Dateiname" der Ergebnistabelle anzuzeigen.
+ * <p>
+ * Die Bootstrap-Schicht liefert die konkrete Implementierung. Sie lädt die Konfiguration
+ * aus {@code configFilePath}, baut den zugehörigen Use-Case auf und gibt das Ergebnis
+ * zurück. Technische Fehler beim Laden oder Abfragen dürfen nicht als Exception propagiert
+ * werden; sie werden intern behandelt und als leeres {@link Optional} zurückgegeben.
+ * <p>
+ * Die Implementierung läuft auf dem Worker-Thread des {@link GuiBatchRunCoordinator}
+ * und darf blockieren.
+ */
+@FunctionalInterface
+public interface GuiHistoricalFileNamePort {
+
+    /**
+     * Gibt den letzten erfolgreich geschriebenen Zieldateinamen für das durch
+     * {@code fingerprint} identifizierte Dokument zurück, oder ein leeres
+     * {@link Optional}, wenn kein solcher Name verfügbar ist.
+     *
+     * @param configFilePath Pfad zur aktiven {@code .properties}-Konfigurationsdatei;
+     *                       darf nicht {@code null} sein
+     * @param fingerprint    inhaltsbasierte Dokumentenidentität; darf nicht {@code null} sein
+     * @return der historische Zieldateiname, oder leer wenn nicht vorhanden
+     */
+    Optional<String> resolveHistoricalFileName(Path configFilePath, DocumentFingerprint fingerprint);
+}
@@ -0,0 +1,48 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.nio.file.Path;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.ManualFileCopyRequest;
+import de.gecheckt.pdf.umbenenner.application.port.in.ManualFileCopyResult;
+
+/**
+ * Inbound-Brücke für die manuelle Kopie der Quelldatei eines bislang nicht erfolgreich
+ * verarbeiteten Dokuments aus der GUI.
+ * <p>
+ * Wird von Bootstrap per Methoden-Referenz befüllt und vom GUI-Code aufgerufen, wenn der
+ * Benutzer für ein nicht erfolgreich verarbeitetes Dokument (Status {@code FAILED_*} oder
+ * {@code SKIPPED_FINAL_FAILURE}) einen manuellen Zieldateinamen bestätigt. Der Port
+ * kapselt das vollständige Wiring (Konfigurationsauflösung, Use-Case-Konstruktion und
+ * Ausführung), sodass der GUI-Adapter keine Kenntnis von infrastrukturellen
+ * Implementierungsdetails benötigt.
+ *
+ * <h2>Threadingmodell</h2>
+ * <p>
+ * Der Port darf auf einem beliebigen Thread aufgerufen werden. Die Implementierung ist
+ * synchron und blockierend: Sie kehrt erst zurück, wenn die Kopie abgeschlossen oder
+ * fehlgeschlagen ist. Aufrufer aus dem GUI-Layer müssen den Aufruf daher auf einem
+ * Hintergrund-Worker-Thread ausführen und das Ergebnis anschließend per
+ * {@code Platform.runLater} auf den JavaFX-Application-Thread zurückführen.
+ *
+ * <h2>Exception-Vertrag</h2>
+ * <p>
+ * Implementierungen dürfen keine geprüften Ausnahmen propagieren. Unerwartete
+ * Laufzeitausnahmen sollen abgefangen und als passendes {@link ManualFileCopyResult}
+ * zurückgegeben werden.
+ */
+@FunctionalInterface
+public interface GuiManualFileCopyPort {
+
+    /**
+     * Kopiert die Quelldatei eines Dokuments mit benutzerdefiniertem Zieldateinamen ins
+     * Zielverzeichnis und aktualisiert den Dokument-Stammsatz auf {@code SUCCESS}.
+     *
+     * @param configFilePath Pfad zur {@code .properties}-Datei, die SQLite-Datenbank,
+     *                       Quell- und Zielordner beschreibt; darf nicht {@code null} sein;
+     *                       muss existieren und lesbar sein
+     * @param request        die Kopieranfrage mit Fingerprint und gewünschtem
+     *                       Basisdateinamen; darf nicht {@code null} sein
+     * @return das Ergebnis der Kopieroperation; nie {@code null}
+     */
+    ManualFileCopyResult copy(Path configFilePath, ManualFileCopyRequest request);
+}
@@ -0,0 +1,46 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.nio.file.Path;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.ManualFileRenameRequest;
+import de.gecheckt.pdf.umbenenner.application.port.in.ManualFileRenameResult;
+
+/**
+ * Inbound-Brücke für die manuelle Dateiumbenennung aus der GUI.
+ * <p>
+ * Wird von Bootstrap per Methoden-Referenz befüllt und vom GUI-Code aufgerufen,
+ * wenn der Benutzer einen geänderten Dateinamen bestätigt. Der Port kapselt
+ * das vollständige Wiring (Konfigurationsauflösung, Use-Case-Konstruktion und
+ * Ausführung), sodass der GUI-Adapter keine Kenntnis von infrastrukturellen
+ * Implementierungsdetails benötigt.
+ *
+ * <h2>Threadingmodell</h2>
+ * <p>
+ * Der Port darf auf einem beliebigen Thread aufgerufen werden. Die Implementierung
+ * ist synchron und blockierend: Sie kehrt erst zurück, wenn die Umbenennung
+ * abgeschlossen oder fehlgeschlagen ist. Aufrufer aus dem GUI-Layer müssen den
+ * Aufruf daher auf einem Hintergrund-Worker-Thread ausführen und das Ergebnis
+ * anschließend per {@code Platform.runLater} auf den JavaFX-Application-Thread
+ * zurückführen.
+ *
+ * <h2>Exception-Vertrag</h2>
+ * <p>
+ * Implementierungen dürfen keine geprüften Ausnahmen propagieren. Unerwartete
+ * Laufzeitausnahmen sollen abgefangen und als passendes {@link ManualFileRenameResult}
+ * zurückgegeben werden.
+ */
+@FunctionalInterface
+public interface GuiManualFileRenamePort {
+
+    /**
+     * Benennt die Zieldatei eines erfolgreich verarbeiteten Dokuments manuell um.
+     *
+     * @param configFilePath Pfad zur {@code .properties}-Datei, die die SQLite-Datenbank
+     *                       und den Zielordner beschreibt; darf nicht {@code null} sein;
+     *                       muss existieren und lesbar sein
+     * @param request        die Umbenennungsanfrage mit Fingerprint und gewünschtem
+     *                       Basisdateinamen; darf nicht {@code null} sein
+     * @return das Ergebnis der Umbenennung; nie {@code null}
+     */
+    ManualFileRenameResult rename(Path configFilePath, ManualFileRenameRequest request);
+}
@@ -0,0 +1,55 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.nio.file.Path;
+import java.util.Set;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.BatchRunCancellationToken;
+import de.gecheckt.pdf.umbenenner.application.port.in.BatchRunProgressObserver;
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+
+/**
+ * Inbound bridge implemented by Bootstrap to let the GUI execute a targeted mini batch
+ * run restricted to a specific set of document fingerprints.
+ * <p>
+ * A mini-run applies the full processing pipeline — legacy migration, configuration
+ * loading, validation, SQLite schema initialisation, run-lock, use-case wiring, and
+ * execution — but limits processing to the supplied fingerprint set. Documents not in
+ * the set are silently skipped without any persistence side-effects.
+ *
+ * <h2>Threading</h2>
+ * <p>
+ * Implementations must be safe to call from a non-UI worker thread. They must not touch
+ * the JavaFX Application Thread themselves; all JavaFX-specific scheduling is the
+ * caller's concern. The call blocks until the run terminates (normally, after a
+ * cancellation, or after a hard failure).
+ *
+ * <h2>Exception contract</h2>
+ * <p>
+ * Implementations must not propagate checked exceptions. Unexpected runtime exceptions
+ * should be caught, logged, and returned as a
+ * {@link GuiBatchRunLaunchOutcome#failedAfterStart(String)} outcome to keep the GUI in a
+ * well-defined terminal state.
+ */
+@FunctionalInterface
+public interface GuiMiniRunLauncher {
+
+    /**
+     * Executes a targeted batch run restricted to the supplied fingerprint set.
+     *
+     * @param configFilePath    path of the {@code .properties} file to run against;
+     *                          must not be {@code null}; must exist and be readable
+     * @param fingerprintFilter the set of document fingerprints to process; must not be
+     *                          {@code null}; an empty set results in a completed run
+     *                          that processes nothing
+     * @param observer          observer receiving start/completion/end callbacks; must
+     *                          not be {@code null}
+     * @param cancellationToken cancellation token the run polls between candidates; must
+     *                          not be {@code null}
+     * @return a description of how the run terminated; never {@code null}
+     */
+    GuiBatchRunLaunchOutcome launch(
+            Path configFilePath,
+            Set<DocumentFingerprint> fingerprintFilter,
+            BatchRunProgressObserver observer,
+            BatchRunCancellationToken cancellationToken);
+}
@@ -0,0 +1,45 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.nio.file.Path;
+import java.util.Set;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.ResetDocumentStatusResult;
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+
+/**
+ * Inbound bridge implemented by Bootstrap to let the GUI reset the processing status
+ * of one or more documents without triggering an immediate reprocessing run.
+ * <p>
+ * A reset deletes all persistence data (attempt history and document master record)
+ * for the specified fingerprints, making them eligible for reprocessing in the next
+ * regular or targeted batch run as if they had never been processed.
+ * <p>
+ * The operation follows best-effort semantics: each fingerprint is attempted
+ * independently. Technical failures for individual fingerprints are recorded in the
+ * result and do not abort the remaining resets.
+ *
+ * <h2>Threading</h2>
+ * <p>
+ * Implementations must be safe to call from a non-UI worker thread. The call blocks
+ * until all reset operations have completed or failed.
+ *
+ * <h2>Exception contract</h2>
+ * <p>
+ * Implementations must not propagate checked exceptions. Unexpected runtime exceptions
+ * should be caught and represented as failures in the result map.
+ */
+@FunctionalInterface
+public interface GuiResetDocumentStatusPort {
+
+    /**
+     * Resets the processing status for the supplied set of document fingerprints.
+     *
+     * @param configFilePath path of the {@code .properties} file that identifies the
+     *                       SQLite database to operate on; must not be {@code null};
+     *                       must exist and be readable
+     * @param fingerprints   the set of document fingerprints to reset; must not be
+     *                       {@code null}; may be empty
+     * @return a {@link ResetDocumentStatusResult} describing the full outcome; never null
+     */
+    ResetDocumentStatusResult reset(Path configFilePath, Set<DocumentFingerprint> fingerprints);
+}
@@ -0,0 +1,840 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.awt.image.BufferedImage;
+import java.io.File;
+import java.nio.file.Path;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.concurrent.atomic.AtomicReference;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.encryption.InvalidPasswordException;
+import org.apache.pdfbox.rendering.ImageType;
+import org.apache.pdfbox.rendering.PDFRenderer;
+
+import javafx.application.Platform;
+import javafx.embed.swing.SwingFXUtils;
+import javafx.geometry.Bounds;
+import javafx.geometry.Insets;
+import javafx.geometry.Pos;
+import de.gecheckt.pdf.umbenenner.adapter.in.gui.GuiTooltipTexts;
+import javafx.scene.Cursor;
+import javafx.scene.control.Button;
+import javafx.scene.control.Label;
+import javafx.scene.control.ProgressIndicator;
+import javafx.scene.control.ScrollPane;
+import javafx.scene.control.Tooltip;
+import javafx.util.Duration;
+import javafx.scene.image.Image;
+import javafx.scene.image.ImageView;
+import javafx.scene.input.MouseEvent;
+import javafx.scene.input.ScrollEvent;
+import javafx.scene.layout.HBox;
+import javafx.scene.layout.Priority;
+import javafx.scene.layout.Region;
+import javafx.scene.layout.StackPane;
+import javafx.scene.layout.VBox;
+
+/**
+ * Detailbereich-Komponente zur asynchronen Anzeige von Seiten einer Quelldatei.
+ *
+ * <p>Die Komponente rendert PDF-Seiten direkt mit Apache PDFBox und zeigt das Ergebnis
+ * in einer {@link ImageView} an. Im Fit-to-View-Modus (Standardzustand) sind
+ * {@code fitWidth} und {@code fitHeight} der {@link ImageView} an die Größe des
+ * umgebenden {@link StackPane} gebunden, {@code preserveRatio=true} erhält das
+ * Seitenverhältnis. Die Seite füllt den verfügbaren Bereich ohne Scrollbalken.
+ *
+ * <p><strong>Mausrad-Zoom:</strong> Strg + Mausrad ändert den Zoomfaktor in Stufen von
+ * 10 % pro Raste (Bereich {@value #ZOOM_MIN}–{@value #ZOOM_MAX}, d. h. 10 %–500 %).
+ * Beim ersten manuellen Zoom wird der Fit-to-View-Modus verlassen und ein
+ * {@link ScrollPane} übernimmt das Scrollen. Das Laden einer neuen Datei setzt den
+ * Zoom automatisch auf Fit-to-View zurück.
+ *
+ * <p><strong>Grab &amp; Pan:</strong> Im manuellen Zoom-Modus kann die Vorschau durch
+ * Klicken und Ziehen (linke Maustaste) verschoben werden. Der Mauszeiger wechselt im
+ * Zoom-Modus auf {@link Cursor#OPEN_HAND} und während der Geste auf
+ * {@link Cursor#CLOSED_HAND}.
+ *
+ * <p>Das Laden der PDF-Datei und das Rendering einzelner Seiten erfolgt auf einem
+ * dedizierten Worker-Thread. UI-Updates laufen ausschließlich über den JavaFX
+ * Application Thread. Bereits gerenderte Seiten werden in einem In-Memory-Cache
+ * ({@code Map<Integer, Image>}) gehalten, sodass wiederholte Navigation kein
+ * erneutes Rendering erfordert. Der Cache wird beim Wechsel der Quelldatei geleert.
+ *
+ * <p>Es gilt das Prinzip „Latest Preview Request Wins": Veraltete Lade- und
+ * Rendering-Ergebnisse werden anhand einer Sequenznummer erkannt und verworfen,
+ * sobald eine neue Anforderung eingeht.
+ *
+ * <h2>Fehlerfälle</h2>
+ * <ul>
+ *   <li>Quelldatei nicht vorhanden → Meldungstext im Vorschaubereich</li>
+ *   <li>PDF nicht lesbar → Meldungstext im Vorschaubereich</li>
+ *   <li>PDF passwortgeschützt → Meldungstext im Vorschaubereich</li>
+ *   <li>Keine Selektion → neutraler Platzhaltertext</li>
+ * </ul>
+ *
+ * <h2>Threading</h2>
+ * <p>Alle öffentlichen Methoden müssen auf dem JavaFX Application Thread aufgerufen
+ * werden. Das PDF-Öffnen, die Speicherhaltung des {@link PDDocument} und das
+ * Rendering einzelner Seiten laufen ausschließlich auf dem Worker-Thread.
+ */
+public final class PdfPreviewPane {
+
+    private static final Logger LOG = LogManager.getLogger(PdfPreviewPane.class);
+
+    static final String PLACEHOLDER_TEXT = "Keine Datei ausgewählt";
+    static final String FILE_NOT_FOUND_TEXT = "Quelldatei nicht gefunden";
+    static final String PDF_UNREADABLE_TEXT = "PDF konnte nicht geöffnet werden";
+    static final String PDF_PASSWORD_PROTECTED_TEXT =
+            "PDF ist passwortgeschützt und kann nicht angezeigt werden";
+
+    /** Render-Auflösung in DPI. 120 DPI ist ein guter Kompromiss aus Qualität und Geschwindigkeit. */
+    private static final float RENDER_DPI = 120f;
+
+    /** Minimaler Zoomfaktor (10 %). */
+    static final double ZOOM_MIN = 0.10;
+
+    /** Maximaler Zoomfaktor (500 %). */
+    static final double ZOOM_MAX = 5.00;
+
+    /** Zoom-Schrittgröße pro Mausrad-Raste (10 %). */
+    private static final double ZOOM_STEP = 0.10;
+
+    /** Typischer vertikaler Scroll-Delta pro Mausrad-Raste. */
+    private static final double ZOOM_NOTCH_THRESHOLD = 40.0;
+
+    private final VBox root = new VBox(4);
+    private final StackPane viewStack = new StackPane();
+    private final ImageView imageView = new ImageView();
+    private final Label overlayLabel = new Label(PLACEHOLDER_TEXT);
+    private final ProgressIndicator progressIndicator = new ProgressIndicator();
+    private final Label pageLabel = new Label();
+    private final Button prevButton = new Button("◀ Vorherige");
+    private final Button nextButton = new Button("Nächste ▶");
+    private final Label sectionTitle = new Label("PDF-Vorschau");
+    private final ScrollPane scrollPane = new ScrollPane(viewStack);
+
+    /** Aktueller Zoomfaktor; 1.0 entspricht der natürlichen Viewport-Breite. */
+    private double zoomLevel = 1.0;
+
+    /** Akkumulator für sub-Rasten-Scroll-Deltas. */
+    private double zoomAccumulator = 0.0;
+
+    /**
+     * Referenzbreite für die manuelle Zoom-Skalierung; gilt
+     * {@code imageView.fitWidth = naturalViewportWidth × zoomLevel} im manuellen
+     * Zoom-Modus. Beim Verlassen des Fit-Modus wird der Wert auf die natürliche
+     * Bildbreite gesetzt, sodass {@code zoomLevel = 1.0} der pixel-genauen
+     * Originalgröße entspricht und {@code zoomLevel} damit gleich dem visuellen
+     * Skalierungsfaktor ist. {@code 0.0} bedeutet Fit-to-View-Modus ist aktiv.
+     */
+    private double naturalViewportWidth = 0.0;
+
+    /** X-Startposition der laufenden Pan-Geste in Bildschirmkoordinaten; -1 wenn inaktiv. */
+    private double panStartX = -1;
+
+    /** Y-Startposition der laufenden Pan-Geste in Bildschirmkoordinaten; -1 wenn inaktiv. */
+    private double panStartY = -1;
+
+    /** Horizontaler Scroll-Wert zu Beginn der laufenden Pan-Geste. */
+    private double panStartHvalue = 0.0;
+
+    /** Vertikaler Scroll-Wert zu Beginn der laufenden Pan-Geste. */
+    private double panStartVvalue = 0.0;
+
+    /**
+     * Sequenznummer der aktuell angeforderten Vorschau. Jede neue Anforderung
+     * (Laden oder Seitenwechsel) erhöht diesen Zähler. Lade-/Rendering-Ergebnisse
+     * mit veralteter Sequenznummer werden verworfen.
+     */
+    private final AtomicLong currentRequestSequence = new AtomicLong(0);
+
+    /**
+     * Cache bereits gerenderter Seiten für die aktuell geladene Quelldatei.
+     * Schlüssel ist die 1-basierte Seitennummer. Wird beim Wechsel der Quelldatei geleert.
+     */
+    private final Map<Integer, Image> pageCache = new ConcurrentHashMap<>();
+
+    /** Hintergrund-Thread-Pool für Lade- und Rendering-Aufgaben. */
+    private final ExecutorService executor =
+            Executors.newSingleThreadExecutor(r -> {
+                Thread t = new Thread(r, "pdf-preview-worker");
+                t.setDaemon(true);
+                return t;
+            });
+
+    /**
+     * Aktuell geöffnetes PDF-Dokument. Zugriff ausschließlich vom Worker-Thread.
+     * Leerer Referenzwert wenn kein Dokument geöffnet ist.
+     */
+    private final AtomicReference<PDDocument> currentDocument = new AtomicReference<>();
+
+    /**
+     * Renderer für das aktuell geöffnete Dokument. Zugriff ausschließlich vom Worker-Thread.
+     * Leerer Referenzwert wenn kein Dokument geöffnet ist.
+     */
+    private final AtomicReference<PDFRenderer> currentRenderer = new AtomicReference<>();
+
+    /** Aktuell geladene Quelldatei; leerer Referenzwert wenn keine Selektion vorliegt. */
+    private final AtomicReference<Path> currentSourceFile = new AtomicReference<>();
+
+    /** Aktuell angezeigte Seite (1-basiert; 0 wenn keine Datei geladen). */
+    private volatile int currentPage = 0;
+
+    /** Anzahl der Seiten der aktuell geladenen PDF; -1 wenn nicht ermittelt. */
+    private volatile int totalPages = -1;
+
+    /** Gibt an ob die Navigation bedienbar ist. */
+    private boolean enabled = true;
+
+    /**
+     * Erstellt die Komponente im deaktivierten Platzhalter-Zustand.
+     */
+    public PdfPreviewPane() {
+        sectionTitle.setStyle("-fx-font-weight: bold;");
+
+        imageView.setId("pdf-preview-image-view");
+        imageView.setPreserveRatio(true);
+        imageView.setSmooth(true);
+        // Fit-to-view: ImageView füllt den verfügbaren Bereich unter Wahrung des Seitenverhältnisses
+        imageView.fitWidthProperty().bind(viewStack.widthProperty());
+        imageView.fitHeightProperty().bind(viewStack.heightProperty());
+
+        overlayLabel.setId("pdf-preview-overlay-label");
+        overlayLabel.setStyle("-fx-text-fill: #555555;");
+        overlayLabel.setWrapText(true);
+        overlayLabel.setVisible(true);
+        overlayLabel.setManaged(true);
+
+        progressIndicator.setId("pdf-preview-progress");
+        progressIndicator.setVisible(false);
+        progressIndicator.setManaged(false);
+        progressIndicator.setMaxWidth(60);
+        progressIndicator.setMaxHeight(60);
+
+        // Stack: ImageView hinter dem Overlay; Overlay überlagert das Bild bei Fehlern/Laden
+        viewStack.getChildren().addAll(imageView, overlayLabel, progressIndicator);
+        StackPane.setAlignment(imageView, Pos.CENTER);
+        StackPane.setAlignment(overlayLabel, Pos.CENTER);
+        StackPane.setAlignment(progressIndicator, Pos.CENTER);
+
+        scrollPane.setId("pdf-preview-scroll-pane");
+        scrollPane.setFitToWidth(true);
+        scrollPane.setFitToHeight(true);
+        scrollPane.setHbarPolicy(ScrollPane.ScrollBarPolicy.AS_NEEDED);
+        scrollPane.setVbarPolicy(ScrollPane.ScrollBarPolicy.AS_NEEDED);
+        // 32c: Verhindert, dass ScrollPane und StackPane beim manuellen Zoom mitwachsen
+        scrollPane.setPrefSize(0, 0);
+        viewStack.setMinSize(0, 0);
+        VBox.setVgrow(scrollPane, Priority.ALWAYS);
+        // Strg + Mausrad → Zoom; ohne Strg → normales Scrollen
+        scrollPane.addEventFilter(ScrollEvent.SCROLL, event -> {
+            if (event.isControlDown()) {
+                accumulateAndApplyZoomDelta(event.getDeltaY());
+                event.consume();
+            }
+        });
+        // Grab & Pan – im manuellen Zoom-Modus mit Maus verschiebbar
+        viewStack.addEventHandler(MouseEvent.MOUSE_PRESSED, this::onPanMousePressed);
+        viewStack.addEventHandler(MouseEvent.MOUSE_DRAGGED, this::onPanMouseDragged);
+        viewStack.addEventHandler(MouseEvent.MOUSE_RELEASED, this::onPanMouseReleased);
+        // viewStack ist immer mindestens so groß wie der Viewport. Ist der Inhalt
+        // (ImageView) kleiner als der Viewport, sorgt diese Mindestgröße zusammen
+        // mit StackPane.Pos.CENTER dafür, dass die ImageView automatisch zentriert
+        // wird – ohne manuelle setHvalue/setVvalue-Eingriffe. Ist der Inhalt größer,
+        // bleibt die Mindestgröße wirkungslos und der ScrollPane scrollt normal.
+        scrollPane.viewportBoundsProperty().addListener((obs, old, bounds) -> {
+            viewStack.setMinWidth(bounds.getWidth());
+            viewStack.setMinHeight(bounds.getHeight());
+        });
+
+        prevButton.setId("pdf-preview-prev-button");
+        prevButton.setOnAction(e -> navigateToPreviousPage());
+        Tooltip prevTooltip = new Tooltip(GuiTooltipTexts.PREVIEW_VORHERIGE_SEITE);
+        prevTooltip.setShowDelay(Duration.millis(300));
+        prevButton.setTooltip(prevTooltip);
+
+        nextButton.setId("pdf-preview-next-button");
+        nextButton.setOnAction(e -> navigateToNextPage());
+        Tooltip nextTooltip = new Tooltip(GuiTooltipTexts.PREVIEW_NAECHSTE_SEITE);
+        nextTooltip.setShowDelay(Duration.millis(300));
+        nextButton.setTooltip(nextTooltip);
+
+        pageLabel.setId("pdf-preview-page-label");
+        pageLabel.setStyle("-fx-text-fill: #555555;");
+
+        HBox navBar = new HBox(8, prevButton, pageLabel, nextButton);
+        navBar.setAlignment(Pos.CENTER);
+        navBar.setPadding(new Insets(4, 0, 4, 0));
+
+        root.getChildren().addAll(sectionTitle, scrollPane, navBar);
+        root.setPadding(new Insets(4, 0, 0, 0));
+
+        showPlaceholder();
+        updateNavigationButtons();
+    }
+
+    /**
+     * Liefert den Wurzel-Knoten der Komponente zum Einfügen in den Detailbereich.
+     *
+     * @return das Root-Control; nie null
+     */
+    public Region getNode() {
+        return root;
+    }
+
+    /**
+     * Lädt die angegebene Quelldatei asynchron und zeigt Seite 1 an.
+     * Startet eine neue Vorschau-Anforderung und verwirft etwaige laufende Anforderungen.
+     * Der Seiten-Cache wird geleert und ein etwaiges bereits geöffnetes PDF-Dokument
+     * wird geschlossen.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     *
+     * @param sourceFile Pfad zur Quelldatei; null führt zu {@link #clear()}
+     */
+    public void loadSource(Path sourceFile) {
+        if (sourceFile == null) {
+            clear();
+            return;
+        }
+        currentSourceFile.set(sourceFile);
+        currentPage = 0;
+        totalPages = -1;
+        pageCache.clear();
+        resetToFitView();
+        requestLoad(sourceFile);
+    }
+
+    /**
+     * Leert die Komponente und zeigt den neutralen Platzhaltertext.
+     * Das aktuell geöffnete PDF-Dokument wird asynchron auf dem Worker-Thread geschlossen.
+     * <p>
+     * Muss auf dem JavaFX Application Thread aufgerufen werden.
+     */
+    public void clear() {
+        currentSourceFile.set(null);
+        currentPage = 0;
+        totalPages = -1;
+        pageCache.clear();
+        // Neue Sequenznummer: laufende Requests werden verworfen
+        currentRequestSequence.incrementAndGet();
+        // Dokument auf dem Worker-Thread schließen, da PDDocument ausschließlich dort genutzt wird
+        executor.submit(this::closeCurrentDocumentOnWorker);
+        resetToFitView();
+        imageView.setImage(null);
+        showPlaceholder();
+        updateNavigationButtons();
+    }
+
+    /**
+     * Aktiviert oder deaktiviert die Navigations-Buttons.
+     * Während eines laufenden Batch-Laufs soll die Navigation deaktiviert sein.
+     * Die Vorschau-Anzeige bleibt sichtbar.
+     *
+     * @param enabled {@code true} wenn Navigation erlaubt ist
+     */
+    public void setEnabled(boolean enabled) {
+        this.enabled = enabled;
+        updateNavigationButtons();
+    }
+
+    /**
+     * Beendet den internen Executor sauber und schließt das eventuell noch offene
+     * PDF-Dokument. Muss beim Schließen der Anwendung aufgerufen werden.
+     */
+    public void shutdown() {
+        try {
+            executor.submit(this::closeCurrentDocumentOnWorker);
+        } catch (RuntimeException ignored) {
+            // Executor wurde bereits beendet – keine Aktion erforderlich
+        }
+        executor.shutdown();
+    }
+
+    // --- Test-Accessoren ------------------------------------------------------
+
+    /** Visible for tests. */
+    Label overlayLabel() {
+        return overlayLabel;
+    }
+
+    /** Visible for tests. */
+    Button prevButton() {
+        return prevButton;
+    }
+
+    /** Visible for tests. */
+    Button nextButton() {
+        return nextButton;
+    }
+
+    /** Visible for tests. */
+    Label pageLabel() {
+        return pageLabel;
+    }
+
+    /** Visible for tests. */
+    ProgressIndicator progressIndicator() {
+        return progressIndicator;
+    }
+
+    /** Visible for tests. */
+    ScrollPane scrollPane() {
+        return scrollPane;
+    }
+
+    /** Visible for tests. */
+    double zoomLevel() {
+        return zoomLevel;
+    }
+
+    // --- Navigation -----------------------------------------------------------
+
+    private void navigateToPreviousPage() {
+        if (!enabled || currentPage <= 1) {
+            return;
+        }
+        goToPage(currentPage - 1);
+    }
+
+    private void navigateToNextPage() {
+        if (!enabled || totalPages <= 0 || currentPage >= totalPages) {
+            return;
+        }
+        goToPage(currentPage + 1);
+    }
+
+    /**
+     * Wechselt zur angegebenen Seite. Bereits gerenderte Seiten werden direkt aus dem
+     * Cache angezeigt; ansonsten wird ein Rendering-Auftrag auf den Worker-Thread gelegt.
+     *
+     * @param targetPage Ziel-Seite (1-basiert, muss im gültigen Bereich liegen)
+     */
+    private void goToPage(int targetPage) {
+        currentPage = targetPage;
+        updatePageLabel();
+        updateNavigationButtons();
+
+        Image cached = pageCache.get(targetPage);
+        if (cached != null) {
+            imageView.setImage(cached);
+            showContent();
+            return;
+        }
+
+        long seq = currentRequestSequence.incrementAndGet();
+        showLoading();
+        executor.submit(() -> renderPageOnWorker(targetPage, seq));
+    }
+
+    // --- Asynchrones Laden und Rendering --------------------------------------
+
+    /**
+     * Startet eine asynchrone Lade-Anforderung für die angegebene Datei.
+     * Erhöht die Sequenznummer, damit veraltete Ergebnisse erkannt und verworfen werden.
+     *
+     * @param file die zu ladende Quelldatei
+     */
+    private void requestLoad(Path file) {
+        long seq = currentRequestSequence.incrementAndGet();
+        LOG.debug("PDF-Vorschau: Lade {} (Anforderung #{})", file, seq);
+
+        showLoading();
+        updateNavigationButtons();
+
+        executor.submit(() -> loadAndRenderFirstPageOnWorker(file, seq));
+    }
+
+    /**
+     * Öffnet die PDF-Datei, ermittelt die Seitenzahl und rendert die erste Seite.
+     * Läuft ausschließlich auf dem Worker-Thread.
+     *
+     * @param file die zu ladende Datei
+     * @param seq  die Sequenznummer dieser Anforderung
+     */
+    private void loadAndRenderFirstPageOnWorker(Path file, long seq) {
+        File ioFile = file.toFile();
+
+        if (!ioFile.exists()) {
+            LOG.warn("PDF-Vorschau: Rendering fehlgeschlagen – Datei nicht gefunden: {}", file);
+            publishError(seq, FILE_NOT_FOUND_TEXT);
+            return;
+        }
+
+        // Vorheriges Dokument schließen bevor ein neues geöffnet wird
+        closeCurrentDocumentOnWorker();
+
+        try {
+            PDDocument doc = Loader.loadPDF(ioFile);
+            currentDocument.set(doc);
+            PDFRenderer renderer = new PDFRenderer(doc);
+            currentRenderer.set(renderer);
+
+            int pages = Math.max(1, doc.getNumberOfPages());
+            BufferedImage buffered =
+                    renderer.renderImageWithDPI(0, RENDER_DPI, ImageType.RGB);
+            Image fxImage = SwingFXUtils.toFXImage(buffered, null);
+
+            final int totalPagesFinal = pages;
+            Platform.runLater(() -> {
+                if (currentRequestSequence.get() != seq) {
+                    return; // Veraltet – verwerfen
+                }
+                totalPages = totalPagesFinal;
+                currentPage = 1;
+                pageCache.put(1, fxImage);
+                imageView.setImage(fxImage);
+                showContent();
+                updateNavigationButtons();
+                updatePageLabel();
+                LOG.debug("PDF-Vorschau: Rendering abgeschlossen – {} Seite(n)", totalPagesFinal);
+            });
+        } catch (InvalidPasswordException ipe) {
+            LOG.warn("PDF-Vorschau: PDF ist passwortgeschützt: {}", file, ipe);
+            closeCurrentDocumentOnWorker();
+            publishError(seq, PDF_PASSWORD_PROTECTED_TEXT);
+        } catch (Exception e) {
+            LOG.warn("PDF-Vorschau: Rendering fehlgeschlagen: {}", file, e);
+            closeCurrentDocumentOnWorker();
+            publishError(seq, PDF_UNREADABLE_TEXT);
+        }
+    }
+
+    /**
+     * Rendert eine einzelne Seite des aktuell geöffneten Dokuments.
+     * Läuft ausschließlich auf dem Worker-Thread.
+     *
+     * @param page 1-basierte Seitennummer
+     * @param seq  die Sequenznummer dieser Anforderung
+     */
+    private void renderPageOnWorker(int page, long seq) {
+        PDFRenderer renderer = currentRenderer.get();
+        if (renderer == null) {
+            // Dokument wurde zwischenzeitlich geschlossen – nichts zu tun
+            return;
+        }
+        try {
+            BufferedImage buffered = renderer.renderImageWithDPI(page - 1, RENDER_DPI, ImageType.RGB);
+            Image fxImage = SwingFXUtils.toFXImage(buffered, null);
+            Platform.runLater(() -> {
+                if (currentRequestSequence.get() != seq) {
+                    return; // Veraltet – verwerfen
+                }
+                pageCache.put(page, fxImage);
+                if (currentPage == page) {
+                    imageView.setImage(fxImage);
+                    showContent();
+                }
+            });
+        } catch (Exception e) {
+            LOG.warn("PDF-Vorschau: Rendering von Seite {} fehlgeschlagen", page, e);
+            publishError(seq, PDF_UNREADABLE_TEXT);
+        }
+    }
+
+    /**
+     * Schließt das aktuell geöffnete PDF-Dokument, falls vorhanden. Läuft ausschließlich
+     * auf dem Worker-Thread und ist idempotent.
+     */
+    private void closeCurrentDocumentOnWorker() {
+        PDDocument doc = currentDocument.getAndSet(null);
+        currentRenderer.set(null);
+        if (doc != null) {
+            try {
+                doc.close();
+            } catch (Exception e) {
+                LOG.debug("PDF-Vorschau: Schließen des Dokuments schlug fehl", e);
+            }
+        }
+    }
+
+    /**
+     * Übergibt eine Fehlermeldung auf den FX-Thread. Veraltete Meldungen werden verworfen.
+     *
+     * @param seq     Sequenznummer der Anforderung, zu der die Meldung gehört
+     * @param message anzuzeigende Fehlermeldung
+     */
+    private void publishError(long seq, String message) {
+        Platform.runLater(() -> {
+            if (currentRequestSequence.get() != seq) {
+                return;
+            }
+            showError(message);
+            updateNavigationButtons();
+        });
+    }
+
+    // --- Grab & Pan -----------------------------------------------------------
+
+    /**
+     * Startet die Pan-Geste. Speichert die Startposition und den aktuellen Scroll-Zustand.
+     * Nur aktiv wenn der manuelle Zoom-Modus eingeschaltet ist.
+     *
+     * @param event das Maus-Pressed-Ereignis
+     */
+    private void onPanMousePressed(MouseEvent event) {
+        if (scrollPane.isFitToWidth()) {
+            return; // Im Fit-Modus kein Pan nötig
+        }
+        panStartX = event.getScreenX();
+        panStartY = event.getScreenY();
+        panStartHvalue = scrollPane.getHvalue();
+        panStartVvalue = scrollPane.getVvalue();
+        viewStack.setCursor(Cursor.CLOSED_HAND);
+        event.consume();
+    }
+
+    /**
+     * Verschiebt den Viewport relativ zur Startposition der Pan-Geste.
+     * Die Scrolldelta wird auf die scrollbaren Bereiche des Inhalts normiert.
+     *
+     * @param event das Maus-Dragged-Ereignis
+     */
+    private void onPanMouseDragged(MouseEvent event) {
+        if (panStartX < 0 || scrollPane.isFitToWidth()) {
+            return;
+        }
+        double dx = event.getScreenX() - panStartX;
+        double dy = event.getScreenY() - panStartY;
+
+        Bounds viewport = scrollPane.getViewportBounds();
+        double contentWidth = viewStack.getWidth();
+        double contentHeight = viewStack.getHeight();
+        double viewportWidth = viewport != null ? viewport.getWidth() : 0;
+        double viewportHeight = viewport != null ? viewport.getHeight() : 0;
+
+        double scrollableWidth = contentWidth - viewportWidth;
+        double scrollableHeight = contentHeight - viewportHeight;
+
+        if (scrollableWidth > 0) {
+            double newHval = panStartHvalue - dx / scrollableWidth;
+            scrollPane.setHvalue(Math.max(0, Math.min(1, newHval)));
+        }
+        if (scrollableHeight > 0) {
+            double newVval = panStartVvalue - dy / scrollableHeight;
+            scrollPane.setVvalue(Math.max(0, Math.min(1, newVval)));
+        }
+        event.consume();
+    }
+
+    /**
+     * Beendet die Pan-Geste und stellt den OPEN_HAND-Mauszeiger wieder her.
+     *
+     * @param event das Maus-Released-Ereignis
+     */
+    private void onPanMouseReleased(MouseEvent event) {
+        panStartX = -1;
+        panStartY = -1;
+        if (!scrollPane.isFitToWidth()) {
+            viewStack.setCursor(Cursor.OPEN_HAND);
+        }
+        event.consume();
+    }
+
+    // --- Zoom -----------------------------------------------------------------
+
+    /**
+     * Akkumuliert den Scroll-Delta und wendet den Zoom schrittweise an.
+     * Pro Raste (ca. {@value #ZOOM_NOTCH_THRESHOLD} Einheiten) ändert sich der Zoom
+     * um {@value #ZOOM_STEP}. Pro ScrollEvent wird maximal eine Zoom-Stufe angewendet.
+     *
+     * <p>Der Rohwert von {@code deltaY} wird vor der Akkumulation auf einen
+     * Notch-Wert ({@value #ZOOM_NOTCH_THRESHOLD}) begrenzt. Plattformspezifische
+     * Scroll-Multiplikatoren (z. B. Windows-Mausgeschwindigkeit, hohe DPI-Mäuse)
+     * können sonst Werte wie 120 oder mehr pro Raste liefern, was einen
+     * Akkumulator-Überlauf in Folge-Events verursacht.
+     *
+     * @param deltaY vertikaler Scroll-Delta des {@link ScrollEvent}
+     */
+    private void accumulateAndApplyZoomDelta(double deltaY) {
+        // Normierung: maximal einen Notch-Wert pro Event akkumulieren, um
+        // plattformspezifische deltaY-Überhöhungen (z. B. 120 statt 40) abzufangen
+        double capped = Math.signum(deltaY) * Math.min(Math.abs(deltaY), ZOOM_NOTCH_THRESHOLD);
+        zoomAccumulator += capped;
+        if (zoomAccumulator >= ZOOM_NOTCH_THRESHOLD) {
+            zoomAccumulator -= ZOOM_NOTCH_THRESHOLD;
+            applyZoom(Math.min(ZOOM_MAX, zoomLevel + ZOOM_STEP));
+        } else if (zoomAccumulator <= -ZOOM_NOTCH_THRESHOLD) {
+            zoomAccumulator += ZOOM_NOTCH_THRESHOLD;
+            applyZoom(Math.max(ZOOM_MIN, zoomLevel - ZOOM_STEP));
+        }
+    }
+
+    /**
+     * Setzt den Zoomfaktor und verlässt beim ersten Aufruf den Fit-to-View-Modus.
+     * <p>
+     * Beim ersten Aufruf (Wechsel aus dem Fit-Modus) wird {@code zoomLevel} auf
+     * den aktuellen visuellen Skalierungsfaktor kalibriert: aktuelle visuelle
+     * Breite der ImageView (mit {@code preserveRatio} bereits aspekt-korrekt
+     * verkleinert) geteilt durch die natürliche Bildbreite. Damit entspricht
+     * {@code zoomLevel = 1.0} der pixel-genauen Originalgröße, und der erste
+     * Zoom-Schritt addiert sich auf den realen Skalierungsfaktor. Ohne diese
+     * Kalibrierung springt die ImageView abrupt auf {@code Viewport-Breite × 1.10},
+     * weil im Fit-Modus die {@code fitHeight}-Bindung das Bild aspekt-erhaltend
+     * deutlich kleiner zwingt als {@code naturalViewportWidth × 1.0} ergibt.
+     * Da der Caller den Delta-Schritt auf dem alten {@code zoomLevel = 1.0}
+     * berechnet hat, wird er nach der Kalibrierung auf den neuen, kalibrierten
+     * {@code zoomLevel} re-appliziert.
+     * <p>
+     * Beim Wechsel aus dem Fit-to-View-Modus wird die Ansicht auf die Bildmitte
+     * zentriert (H/V = 0.5). Bei weiteren Zoom-Schritten bleibt die aktuelle
+     * Scrollposition erhalten. Ein {@code layout()}-Aufruf vor der
+     * Positionswiederherstellung stellt sicher, dass die neuen Inhaltsgrenzen
+     * bereits berechnet sind.
+     *
+     * @param newZoom gewünschter Zoomfaktor, wird auf [{@link #ZOOM_MIN}, {@link #ZOOM_MAX}] begrenzt
+     */
+    private void applyZoom(double newZoom) {
+        double effective = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, newZoom));
+
+        boolean wasInFitMode = scrollPane.isFitToWidth();
+        if (wasInFitMode) {
+            Image image = imageView.getImage();
+            if (image == null || image.getWidth() <= 0) {
+                return; // Kein Bild – Zoom-Kalibrierung nicht möglich
+            }
+            double naturalImageWidth = image.getWidth();
+            double currentVisualWidth = imageView.getBoundsInLocal().getWidth();
+            if (currentVisualWidth <= 0) {
+                Bounds viewport = scrollPane.getViewportBounds();
+                currentVisualWidth = viewport != null ? viewport.getWidth() : viewStack.getWidth();
+                if (currentVisualWidth <= 0) {
+                    return; // Layout noch nicht abgeschlossen
+                }
+            }
+
+            // Vom Caller intendierten Delta-Schritt vor der Kalibrierung sichern
+            double requestedDelta = newZoom - zoomLevel;
+
+            // zoomLevel auf den aktuellen visuellen Skalierungsfaktor kalibrieren
+            naturalViewportWidth = naturalImageWidth;
+            zoomLevel = currentVisualWidth / naturalImageWidth;
+
+            // effective neu berechnen, weil zoomLevel sich geändert hat
+            effective = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, zoomLevel + requestedDelta));
+
+            scrollPane.setFitToWidth(false);
+            scrollPane.setFitToHeight(false);
+            imageView.fitWidthProperty().unbind();
+            imageView.fitHeightProperty().unbind();
+            // Mauszeiger signalisiert Pan-Modus
+            viewStack.setCursor(Cursor.OPEN_HAND);
+        }
+
+        if (effective == zoomLevel) {
+            return;
+        }
+
+        zoomLevel = effective;
+        imageView.setFitWidth(naturalViewportWidth * zoomLevel);
+        imageView.setFitHeight(0);
+        // Keine manuellen setHvalue/setVvalue-Eingriffe nötig: viewStack hat
+        // dank des viewportBoundsProperty-Listeners im Konstruktor mindestens
+        // Viewport-Größe, und Pos.CENTER sorgt für automatische Zentrierung,
+        // wenn der Inhalt kleiner als der Viewport ist.
+    }
+
+    /**
+     * Setzt Zoom, Akkumulator und Pan-Zustand zurück und reaktiviert den Fit-to-View-Modus.
+     * Wird beim Laden einer neuen Datei und beim Leeren der Komponente aufgerufen.
+     *
+     * <p>Reihenfolge der Aktionen ist kritisch:
+     * <ol>
+     *   <li>{@code setFitToWidth(true)} und {@code setFitToHeight(true)} sofort,
+     *       damit der nächste Layout-Pass den {@code viewStack} auf Viewport-Größe
+     *       zurückrechnet.</li>
+     *   <li>Property-Bindungen und H/V-Reset im {@code Platform.runLater}, damit
+     *       sie auf die bereits zurückgerechneten {@code viewStack}-Dimensionen
+     *       wirken und nicht auf die noch zoom-große Breite.</li>
+     * </ol>
+     * Ohne diese Reihenfolge würden die Bindungen die imageView kurz an die
+     * Zoom-Größe koppeln, und ein verbleibender H/V-Wert aus dem Pan-/Zoom-Modus
+     * (z. B. {@code hvalue=0.0} nach Pan zum linken Rand) würde die PDF wegen
+     * kleinster Rounding-/Border-Differenzen links/oben bündig statt zentriert
+     * anzeigen, obwohl der ScrollPane fit-aktiv ist.
+     */
+    private void resetToFitView() {
+        zoomLevel = 1.0;
+        zoomAccumulator = 0.0;
+        naturalViewportWidth = 0.0;
+        // Pan-Zustand und Mauszeiger zurücksetzen
+        panStartX = -1;
+        panStartY = -1;
+        viewStack.setCursor(null);
+        if (!scrollPane.isFitToWidth()) {
+            // 1. ScrollPane in Fit-Modus schalten, damit der nächste Layout-Pass
+            //    den viewStack auf Viewport-Größe zurückrechnet
+            scrollPane.setFitToWidth(true);
+            scrollPane.setFitToHeight(true);
+            // 2. Bindings erst nach abgeschlossenem Layout-Pass, damit sie auf
+            //    die zurückgerechneten viewStack-Dimensionen wirken
+            Platform.runLater(() -> {
+                imageView.fitWidthProperty().bind(viewStack.widthProperty());
+                imageView.fitHeightProperty().bind(viewStack.heightProperty());
+            });
+        }
+    }
+
+    // --- UI-Zustandshelfer ---------------------------------------------------
+
+    private void showPlaceholder() {
+        overlayLabel.setText(PLACEHOLDER_TEXT);
+        overlayLabel.setVisible(true);
+        overlayLabel.setManaged(true);
+        imageView.setVisible(false);
+        imageView.setManaged(false);
+        progressIndicator.setVisible(false);
+        progressIndicator.setManaged(false);
+        pageLabel.setText("");
+    }
+
+    private void showLoading() {
+        progressIndicator.setVisible(true);
+        progressIndicator.setManaged(true);
+        overlayLabel.setVisible(false);
+        overlayLabel.setManaged(false);
+        imageView.setVisible(false);
+        imageView.setManaged(false);
+    }
+
+    private void showContent() {
+        progressIndicator.setVisible(false);
+        progressIndicator.setManaged(false);
+        overlayLabel.setVisible(false);
+        overlayLabel.setManaged(false);
+        imageView.setVisible(true);
+        imageView.setManaged(true);
+    }
+
+    private void showError(String message) {
+        overlayLabel.setText(message);
+        overlayLabel.setVisible(true);
+        overlayLabel.setManaged(true);
+        imageView.setVisible(false);
+        imageView.setManaged(false);
+        progressIndicator.setVisible(false);
+        progressIndicator.setManaged(false);
+        pageLabel.setText("");
+    }
+
+    private void updateNavigationButtons() {
+        boolean canNavigate = enabled && currentSourceFile.get() != null && totalPages > 0;
+        prevButton.setDisable(!canNavigate || currentPage <= 1);
+        nextButton.setDisable(!canNavigate || currentPage >= totalPages);
+    }
+
+    private void updatePageLabel() {
+        if (totalPages > 0 && currentPage > 0) {
+            pageLabel.setText("Seite " + currentPage + " / " + totalPages);
+        } else {
+            pageLabel.setText("");
+        }
+    }
+}
@@ -0,0 +1,287 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
+
+import java.util.Objects;
+
+import de.gecheckt.pdf.umbenenner.application.port.in.DocumentCompletionStatus;
+import de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus;
+
+/**
+ * Zentrale Mapping-Klasse für die visuelle Darstellung von Verarbeitungsstatus in der GUI.
+ * <p>
+ * Diese Klasse ist die einzige autoritative Quelle für Status-Icons, CSS-Farben,
+ * Tooltip-Texte und Summary-Kategorielabels aller {@link DocumentCompletionStatus}-Werte.
+ * Alle Anzeigeorte im GUI-Adapter (Ergebnistabelle, Detailbereich, Summary-Banner)
+ * beziehen ihre Darstellungsinformationen ausschließlich über diese Klasse.
+ * <p>
+ * Farbe ist niemals das einzige Unterscheidungsmerkmal: Icon und Tooltip-Text beschreiben
+ * den Status vollständig auch ohne Farbwahrnehmung.
+ * <p>
+ * Diese Klasse enthält keine JavaFX-Typen; sie ist rein datenhaltend und zustandslos.
+ * Alle Methoden sind statisch.
+ */
+public final class ProcessingStatusPresentation {
+    private static final String STATUS_NOT_NULL = "status darf nicht null sein";
+
+
+
+    // -------------------------------------------------------------------------
+    // Icons (Unicode-Zeichen, zuverlässig darstellbar unter Windows 10+)
+    // -------------------------------------------------------------------------
+
+    /** Icon für {@link DocumentCompletionStatus#SUCCESS}. */
+    public static final String ICON_SUCCESS = "✓";           // CHECK MARK
+
+    /** Icon für {@link DocumentCompletionStatus#FAILED_RETRYABLE}. */
+    public static final String ICON_FAILED_RETRYABLE = "↻";  // CLOCKWISE OPEN CIRCLE ARROW
+
+    /** Icon für {@link DocumentCompletionStatus#FAILED_PERMANENT}. */
+    public static final String ICON_FAILED_PERMANENT = "×";  // MULTIPLICATION SIGN
+
+    /** Icon für {@link DocumentCompletionStatus#SKIPPED_ALREADY_PROCESSED}. */
+    public static final String ICON_SKIPPED_ALREADY_PROCESSED = "≡"; // IDENTICAL TO
+
+    /** Icon für {@link DocumentCompletionStatus#SKIPPED_FINAL_FAILURE}. */
+    public static final String ICON_SKIPPED_FINAL_FAILURE = "⊘"; // CIRCLED DIVISION SLASH
+
+    // -------------------------------------------------------------------------
+    // CSS-Farben (Hex-Strings für JavaFX setStyle)
+    // -------------------------------------------------------------------------
+
+    /** CSS-Farbe für {@link DocumentCompletionStatus#SUCCESS}. */
+    public static final String COLOR_SUCCESS = "#2e7d32";             // Grün
+
+    /** CSS-Farbe für {@link DocumentCompletionStatus#FAILED_RETRYABLE}. */
+    public static final String COLOR_FAILED_RETRYABLE = "#d98200";    // Orange
+
+    /** CSS-Farbe für {@link DocumentCompletionStatus#FAILED_PERMANENT}. */
+    public static final String COLOR_FAILED_PERMANENT = "#c62828";    // Rot
+
+    /** CSS-Farbe für {@link DocumentCompletionStatus#SKIPPED_ALREADY_PROCESSED}. */
+    public static final String COLOR_SKIPPED_ALREADY_PROCESSED = "#757575"; // Grau
+
+    /** CSS-Farbe für {@link DocumentCompletionStatus#SKIPPED_FINAL_FAILURE}. */
+    public static final String COLOR_SKIPPED_FINAL_FAILURE = "#424242";     // Dunkelgrau
+
+    // -------------------------------------------------------------------------
+    // Tooltip-Texte (deutsche Benutzertexte, gemäß Spezifikation)
+    // -------------------------------------------------------------------------
+
+    /** Tooltip für {@link DocumentCompletionStatus#SUCCESS}. */
+    public static final String TOOLTIP_SUCCESS =
+            "Erfolgreich verarbeitet und umbenannt.";
+
+    /** Tooltip für {@link DocumentCompletionStatus#FAILED_RETRYABLE}. */
+    public static final String TOOLTIP_FAILED_RETRYABLE =
+            "Temporärer Fehler – wird beim nächsten Lauf automatisch erneut versucht.";
+
+    /** Tooltip für {@link DocumentCompletionStatus#FAILED_PERMANENT}. */
+    public static final String TOOLTIP_FAILED_PERMANENT =
+            "Dauerhaft nicht verarbeitbar – z. B. kein Textinhalt (Foto-PDF), Passwortschutz "
+                    + "oder beschädigte Datei. Kein weiterer automatischer Versuch.";
+
+    /** Tooltip für {@link DocumentCompletionStatus#SKIPPED_ALREADY_PROCESSED}. */
+    public static final String TOOLTIP_SKIPPED_ALREADY_PROCESSED =
+            "Übersprungen – wurde bereits in einem früheren Lauf erfolgreich verarbeitet.";
+
+    /** Tooltip für {@link DocumentCompletionStatus#SKIPPED_FINAL_FAILURE}. */
+    public static final String TOOLTIP_SKIPPED_FINAL_FAILURE =
+            "Endgültig übersprungen nach wiederholten Fehlern.";
+
+    // -------------------------------------------------------------------------
+    // Detailtext für FAILED_PERMANENT (Erklärung im Detailbereich)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Erweiterter Erklärungstext, der im Detailbereich bei dauerhaft fehlgeschlagenen
+     * Dokumenten angezeigt wird.
+     */
+    public static final String DETAIL_TEXT_FAILED_PERMANENT =
+            "Diese Datei kann nicht verarbeitet werden. Mögliche Ursachen: "
+                    + "kein lesbarer Text (z. B. gescanntes Foto ohne OCR), Passwortschutz "
+                    + "oder beschädigte Datei. "
+                    + "Sie können den Status manuell zurücksetzen, wenn Sie die Ursache behoben haben.";
+
+    // -------------------------------------------------------------------------
+    // Summary-Kategorielabels
+    // -------------------------------------------------------------------------
+
+    /** Summary-Kategorie für {@link DocumentCompletionStatus#SUCCESS}. */
+    public static final String SUMMARY_CATEGORY_SUCCESS = "erfolgreich";
+
+    /** Summary-Kategorie für {@link DocumentCompletionStatus#FAILED_RETRYABLE}. */
+    public static final String SUMMARY_CATEGORY_FAILED_RETRYABLE = "wird wiederholt";
+
+    /** Summary-Kategorie für {@link DocumentCompletionStatus#FAILED_PERMANENT}. */
+    public static final String SUMMARY_CATEGORY_FAILED_PERMANENT = "fehlgeschlagen";
+
+    /** Summary-Kategorie für {@link DocumentCompletionStatus#SKIPPED_ALREADY_PROCESSED}. */
+    public static final String SUMMARY_CATEGORY_SKIPPED_ALREADY_PROCESSED = "übersprungen";
+
+    /** Summary-Kategorie für {@link DocumentCompletionStatus#SKIPPED_FINAL_FAILURE}. */
+    public static final String SUMMARY_CATEGORY_SKIPPED_FINAL_FAILURE = "endgültig übersprungen";
+
+    // -------------------------------------------------------------------------
+    // Record-Typ für gebündelte Darstellungsinformationen
+    // -------------------------------------------------------------------------
+
+    /**
+     * Gebündelte visuelle Darstellungsinformationen für einen Verarbeitungsstatus.
+     *
+     * @param icon              Unicode-Zeichen als Status-Icon; nie leer
+     * @param cssColor          CSS-Hex-Farbe für das Icon, z. B. {@code "#2e7d32"}; nie leer
+     * @param tooltipText       Deutschsprachiger Tooltip-Text; nie leer
+     * @param summaryCategoryLabel  Kategorie-Bezeichnung für das Summary-Banner; nie leer
+     */
+    public record StatusVisuals(
+            String icon,
+            String cssColor,
+            String tooltipText,
+            String summaryCategoryLabel) {
+
+        /**
+         * Kompakter Konstruktor zur Pflichtfeld-Validierung.
+         *
+         * @throws NullPointerException     wenn ein Feld {@code null} ist
+         * @throws IllegalArgumentException wenn ein String-Feld leer ist
+         */
+        public StatusVisuals {
+            Objects.requireNonNull(icon, "icon muss gesetzt sein");
+            Objects.requireNonNull(cssColor, "cssColor muss gesetzt sein");
+            Objects.requireNonNull(tooltipText, "tooltipText muss gesetzt sein");
+            Objects.requireNonNull(summaryCategoryLabel, "summaryCategoryLabel muss gesetzt sein");
+            if (icon.isBlank()) throw new IllegalArgumentException("icon darf nicht leer sein");
+            if (cssColor.isBlank()) throw new IllegalArgumentException("cssColor darf nicht leer sein");
+            if (tooltipText.isBlank()) throw new IllegalArgumentException("tooltipText darf nicht leer sein");
+            if (summaryCategoryLabel.isBlank())
+                throw new IllegalArgumentException("summaryCategoryLabel darf nicht leer sein");
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Zentrale Mapping-Methoden
+    // -------------------------------------------------------------------------
+
+    /**
+     * Liefert das Status-Icon für den angegebenen Verarbeitungsstatus.
+     *
+     * @param status der Verarbeitungsstatus; darf nicht {@code null} sein
+     * @return das zugehörige Unicode-Zeichen; nie leer
+     * @throws NullPointerException wenn {@code status} {@code null} ist
+     */
+    public static String iconFor(DocumentCompletionStatus status) {
+        Objects.requireNonNull(status, STATUS_NOT_NULL);
+        return switch (status) {
+            case SUCCESS -> ICON_SUCCESS;
+            case FAILED_RETRYABLE -> ICON_FAILED_RETRYABLE;
+            case FAILED_PERMANENT -> ICON_FAILED_PERMANENT;
+            case SKIPPED_ALREADY_PROCESSED -> ICON_SKIPPED_ALREADY_PROCESSED;
+            case SKIPPED_FINAL_FAILURE -> ICON_SKIPPED_FINAL_FAILURE;
+        };
+    }
+
+    /**
+     * Liefert die CSS-Hex-Farbe für das Status-Icon des angegebenen Verarbeitungsstatus.
+     * <p>
+     * Die Farbe ist nie das einzige Unterscheidungsmerkmal – Icon und Tooltip-Text
+     * beschreiben den Status unabhängig von der Farbe eindeutig.
+     *
+     * @param status der Verarbeitungsstatus; darf nicht {@code null} sein
+     * @return die CSS-Hex-Farbe (z. B. {@code "#2e7d32"}); nie leer
+     * @throws NullPointerException wenn {@code status} {@code null} ist
+     */
+    public static String cssColorFor(DocumentCompletionStatus status) {
+        Objects.requireNonNull(status, STATUS_NOT_NULL);
+        return switch (status) {
+            case SUCCESS -> COLOR_SUCCESS;
+            case FAILED_RETRYABLE -> COLOR_FAILED_RETRYABLE;
+            case FAILED_PERMANENT -> COLOR_FAILED_PERMANENT;
+            case SKIPPED_ALREADY_PROCESSED -> COLOR_SKIPPED_ALREADY_PROCESSED;
+            case SKIPPED_FINAL_FAILURE -> COLOR_SKIPPED_FINAL_FAILURE;
+        };
+    }
+
+    /**
+     * Liefert den deutschsprachigen Tooltip-Text für den angegebenen Verarbeitungsstatus.
+     *
+     * @param status der Verarbeitungsstatus; darf nicht {@code null} sein
+     * @return der Tooltip-Text; nie leer
+     * @throws NullPointerException wenn {@code status} {@code null} ist
+     */
+    public static String tooltipFor(DocumentCompletionStatus status) {
+        Objects.requireNonNull(status, STATUS_NOT_NULL);
+        return switch (status) {
+            case SUCCESS -> TOOLTIP_SUCCESS;
+            case FAILED_RETRYABLE -> TOOLTIP_FAILED_RETRYABLE;
+            case FAILED_PERMANENT -> TOOLTIP_FAILED_PERMANENT;
+            case SKIPPED_ALREADY_PROCESSED -> TOOLTIP_SKIPPED_ALREADY_PROCESSED;
+            case SKIPPED_FINAL_FAILURE -> TOOLTIP_SKIPPED_FINAL_FAILURE;
+        };
+    }
+
+    /**
+     * Liefert die Summary-Kategorie-Bezeichnung für den angegebenen Verarbeitungsstatus.
+     * Diese Kategorie wird im Summary-Banner nach einem Lauf angezeigt.
+     *
+     * @param status der Verarbeitungsstatus; darf nicht {@code null} sein
+     * @return die Kategorienbezeichnung; nie leer
+     * @throws NullPointerException wenn {@code status} {@code null} ist
+     */
+    public static String summaryCategoryFor(DocumentCompletionStatus status) {
+        Objects.requireNonNull(status, STATUS_NOT_NULL);
+        return switch (status) {
+            case SUCCESS -> SUMMARY_CATEGORY_SUCCESS;
+            case FAILED_RETRYABLE -> SUMMARY_CATEGORY_FAILED_RETRYABLE;
+            case FAILED_PERMANENT -> SUMMARY_CATEGORY_FAILED_PERMANENT;
+            case SKIPPED_ALREADY_PROCESSED -> SUMMARY_CATEGORY_SKIPPED_ALREADY_PROCESSED;
+            case SKIPPED_FINAL_FAILURE -> SUMMARY_CATEGORY_SKIPPED_FINAL_FAILURE;
+        };
+    }
+
+    /**
+     * Liefert alle gebündelten visuellen Darstellungsinformationen für den angegebenen
+     * Verarbeitungsstatus in einem einzigen Objekt.
+     *
+     * @param status der Verarbeitungsstatus; darf nicht {@code null} sein
+     * @return ein befülltes {@link StatusVisuals}-Record; nie {@code null}
+     * @throws NullPointerException wenn {@code status} {@code null} ist
+     */
+    public static StatusVisuals visualsFor(DocumentCompletionStatus status) {
+        Objects.requireNonNull(status, STATUS_NOT_NULL);
+        return new StatusVisuals(
+                iconFor(status),
+                cssColorFor(status),
+                tooltipFor(status),
+                summaryCategoryFor(status));
+    }
+
+    // -------------------------------------------------------------------------
+    // Mapping für ProcessingStatus (alle acht Domain-Statuswerte)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Liefert den deutschsprachigen Anzeigetext mit Icon für den angegebenen
+     * Domain-Verarbeitungsstatus. Kein Enum-Rohname darf für Endnutzer sichtbar sein.
+     *
+     * @param status der Domain-Verarbeitungsstatus; darf nicht {@code null} sein
+     * @return der Anzeigetext mit vorangestelltem Icon; nie leer
+     * @throws NullPointerException wenn {@code status} {@code null} ist
+     */
+    public static String displayTextFor(ProcessingStatus status) {
+        Objects.requireNonNull(status, STATUS_NOT_NULL);
+        return switch (status) {
+            case SUCCESS -> "✓ Erfolgreich";
+            case FAILED_RETRYABLE -> "↻ Temporärer Fehler";
+            case FAILED_FINAL -> "× Dauerhaft fehlgeschlagen";
+            case SKIPPED_ALREADY_PROCESSED -> "≡ Bereits verarbeitet";
+            case SKIPPED_FINAL_FAILURE -> "⊘ Endgültig übersprungen";
+            case READY_FOR_AI -> "⟳ Wartet auf Verarbeitung";
+            case PROPOSAL_READY -> "◇ Vorschlag vorhanden";
+            case PROCESSING -> "▶ In Bearbeitung";
+        };
+    }
+
+    /** Nicht instanziierbar – reine Utility-Klasse. */
+    private ProcessingStatusPresentation() {
+        throw new UnsupportedOperationException("Nicht instanziierbar");
+    }
+}
@@ -0,0 +1,30 @@
+/**
+ * Inbound adapter components that drive the GUI's processing-run tab.
+ * <p>
+ * The classes in this package build the second tab of the main window, translate
+ * {@link de.gecheckt.pdf.umbenenner.application.port.in.BatchRunProgressObserver}
+ * callbacks into JavaFX UI updates, and manage the worker thread that executes a
+ * single run against a stored {@code .properties} configuration.
+ *
+ * <h2>Threading contract</h2>
+ * <p>
+ * The batch run itself always executes on a dedicated background worker thread obtained
+ * from {@link de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun.GuiBatchRunCoordinator}.
+ * Every UI mutation (progress bar value, result rows, button states, tab sperre) is
+ * dispatched onto the JavaFX Application Thread via {@code Platform.runLater}. No class
+ * in this package mutates a JavaFX {@code Control} from the worker thread.
+ *
+ * <h2>Cancellation</h2>
+ * <p>
+ * The coordinator exposes a soft-stop cancellation hook: setting the cancellation flag
+ * causes the use case to stop <em>before</em> starting the next candidate; the candidate
+ * currently being processed is always completed in full so the SQLite persistence remains
+ * consistent.
+ *
+ * <h2>Configuration source</h2>
+ * <p>
+ * A run is always started against the {@code .properties} file currently on disk (the
+ * last saved state of the editor). Unsaved editor content is intentionally not forwarded
+ * to the launcher — the run must match what a parallel headless launch would see.
+ */
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.batchrun;
@@ -0,0 +1,63 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.editor;
+
+import de.gecheckt.pdf.umbenenner.application.config.provider.AiProviderFamily;
+import javafx.util.StringConverter;
+
+/**
+ * A JavaFX {@link StringConverter} that maps {@link AiProviderFamily} constants to
+ * German display labels and back.
+ * <p>
+ * Used by the provider selection {@code ComboBox} to show human-readable German names
+ * while keeping the underlying model type-safe. The reverse conversion
+ * ({@link #fromString(String)}) supports the same label strings produced by
+ * {@link #toString(AiProviderFamily)} so that a ComboBox configured as non-editable
+ * can still convert its selected text back to the enum constant when needed.
+ * <p>
+ * Returns {@code null} for inputs that do not match any known constant to signal an
+ * unrecognised display label.
+ */
+public final class AiProviderFamilyStringConverter extends StringConverter<AiProviderFamily> {
+
+    /**
+     * Creates a new converter instance.
+     */
+    public AiProviderFamilyStringConverter() {
+        // Default constructor.
+    }
+
+    /**
+     * Returns the German display label for the given provider family.
+     *
+     * @param family the provider family to convert; may be {@code null}
+     * @return the German display label, or an empty string when {@code family} is {@code null}
+     */
+    @Override
+    public String toString(AiProviderFamily family) {
+        if (family == null) {
+            return "";
+        }
+        return switch (family) {
+            case CLAUDE -> "Claude";
+            case OPENAI_COMPATIBLE -> "OpenAI-kompatibel";
+        };
+    }
+
+    /**
+     * Resolves a German display label back to its {@link AiProviderFamily} constant.
+     *
+     * @param label the display label as produced by {@link #toString(AiProviderFamily)};
+     *              may be {@code null}
+     * @return the matching constant, or {@code null} when the label is not recognised
+     */
+    @Override
+    public AiProviderFamily fromString(String label) {
+        if (label == null) {
+            return null;
+        }
+        return switch (label) {
+            case "Claude" -> AiProviderFamily.CLAUDE;
+            case "OpenAI-kompatibel" -> AiProviderFamily.OPENAI_COMPATIBLE;
+            default -> null;
+        };
+    }
+}
@@ -0,0 +1,80 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.editor;
+
+import java.util.List;
+import java.util.Objects;
+
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionPlan;
+import de.gecheckt.pdf.umbenenner.application.validation.technicaltest.CorrectionSuggestion;
+
+/**
+ * Inhalt des gesammelten Bestätigungsdialogs für schreibende Korrekturmaßnahmen.
+ * <p>
+ * Bevor schreibende Korrekturen aus einem {@link CorrectionPlan} ausgeführt werden,
+ * zeigt die GUI diesen Inhalt in einem einmaligen Bestätigungsdialog. Der Benutzer
+ * kann die Korrekturen bestätigen oder ablehnen; ohne Bestätigung werden keine
+ * Änderungen vorgenommen.
+ * <p>
+ * Dieser Record liegt bewusst im GUI-Modul, da er ausschließlich für die
+ * Darstellung im Bestätigungsdialog der JavaFX-Oberfläche genutzt wird. Er enthält
+ * selbst keine JavaFX-Typen und kann auf beliebigen Threads erzeugt werden.
+ * <p>
+ * Die Beschreibungszeilen ({@link #correctionLines}) entsprechen den
+ * {@link CorrectionSuggestion#descriptionForUser()}-Texten der im Plan enthaltenen
+ * Vorschläge in Reihenfolge.
+ *
+ * @param title            deutscher Dialogtitel; nie {@code null}
+ * @param introText        einleitender deutschsprachiger Text; nie {@code null}
+ * @param correctionLines  Liste der deutschen Beschreibungszeilen, eine pro Korrekturmaßnahme;
+ *                         nie {@code null}
+ */
+public record ConfirmationDialogContent(
+        String title,
+        String introText,
+        List<String> correctionLines) {
+
+    /**
+     * Erstellt einen neuen Bestätigungsdialog-Inhalt.
+     *
+     * @param title            Dialogtitel; darf nicht {@code null} sein
+     * @param introText        einleitender Text; darf nicht {@code null} sein
+     * @param correctionLines  Beschreibungszeilen; darf nicht {@code null} sein
+     * @throws NullPointerException wenn ein Parameter {@code null} ist
+     */
+    public ConfirmationDialogContent {
+        Objects.requireNonNull(title, "title must not be null");
+        Objects.requireNonNull(introText, "introText must not be null");
+        Objects.requireNonNull(correctionLines, "correctionLines must not be null");
+        correctionLines = List.copyOf(correctionLines);
+    }
+
+    /**
+     * Erstellt den Bestätigungsdialog-Inhalt aus einem {@link CorrectionPlan}.
+     * <p>
+     * Die Beschreibungszeilen werden aus den
+     * {@link CorrectionSuggestion#descriptionForUser()}-Texten der Vorschläge im Plan
+     * in Reihenfolge übernommen.
+     *
+     * @param plan  Korrekturplan; darf nicht {@code null} sein
+     * @return ein neuer Dialoginhalt; nie {@code null}
+     * @throws NullPointerException wenn {@code plan} {@code null} ist
+     */
+    public static ConfirmationDialogContent fromPlan(CorrectionPlan plan) {
+        Objects.requireNonNull(plan, "plan must not be null");
+        List<String> lines = plan.suggestions().stream()
+                .map(CorrectionSuggestion::descriptionForUser)
+                .toList();
+        return new ConfirmationDialogContent(
+                "Korrekturen bestätigen",
+                "Folgende technische Korrekturen werden durchgeführt:",
+                lines);
+    }
+
+    /**
+     * Gibt an, ob der Dialoginhalt mindestens eine Beschreibungszeile enthält.
+     *
+     * @return {@code true} wenn mindestens eine Korrekturmaßnahme beschrieben ist
+     */
+    public boolean hasCorrections() {
+        return !correctionLines.isEmpty();
+    }
+}
@@ -0,0 +1,121 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.editor;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import de.gecheckt.pdf.umbenenner.application.config.provider.AiProviderFamily;
+
+/**
+ * Merges the current editor API-key values against the baseline values before a file
+ * is written to disk.
+ * <p>
+ * The merge rule is:
+ * <ul>
+ *   <li>When a provider's API-key field is non-empty in the current editor values, the
+ *       current value is kept unchanged.</li>
+ *   <li>When a provider's API-key field is empty in the current editor values but the
+ *       corresponding baseline field holds a non-empty value, the baseline value is
+ *       carried into the merged result so the key is not silently deleted from the
+ *       written file.</li>
+ *   <li>When both the current and the baseline value are empty, no preservation occurs
+ *       and the merged result also contains an empty value.</li>
+ * </ul>
+ *
+ * <p>The result indicates which provider (if any) triggered a preservation event so the
+ * GUI can display a warning via later validation layers without coupling the write path
+ * to the warning display mechanism.
+ */
+public final class GuiApiKeyMerger {
+
+    private GuiApiKeyMerger() {
+        // Utility class.
+    }
+
+    /**
+     * Merges the API-key values from the given editor state and returns both the merged
+     * values and the first provider identifier for which a key was silently preserved.
+     *
+     * @param state the current editor state; must not be {@code null}
+     * @return the merge result; never {@code null}
+     */
+    public static MergeResult merge(GuiConfigurationEditorState state) {
+        return merge(state.values(), state.baselineValues());
+    }
+
+    /**
+     * Merges the API-key values from the given current and baseline configuration values.
+     *
+     * @param current  the current editor values; must not be {@code null}
+     * @param baseline the baseline values to compare against; must not be {@code null}
+     * @return the merge result; never {@code null}
+     */
+    public static MergeResult merge(GuiConfigurationValues current, GuiConfigurationValues baseline) {
+        Map<AiProviderFamily, GuiProviderConfigurationState> merged = new LinkedHashMap<>(
+                current.providerConfigurations());
+
+        String preservedProvider = null;
+
+        for (AiProviderFamily family : AiProviderFamily.values()) {
+            GuiProviderConfigurationState currentProvider = current.providerConfiguration(family);
+            if (currentProvider == null) {
+                continue;
+            }
+            String editorKey = currentProvider.apiKey().propertyValue();
+            if (!editorKey.isBlank()) {
+                continue;
+            }
+            GuiProviderConfigurationState baselineProvider = baseline.providerConfiguration(family);
+            if (baselineProvider == null) {
+                continue;
+            }
+            String baselineKey = baselineProvider.apiKey().propertyValue();
+            if (baselineKey != null && !baselineKey.isBlank()) {
+                merged.put(family, new GuiProviderConfigurationState(
+                        currentProvider.baseUrl(),
+                        currentProvider.model(),
+                        currentProvider.timeoutSeconds(),
+                        GuiProviderApiKeyState.unresolved(baselineKey)));
+                if (preservedProvider == null) {
+                    preservedProvider = family.getIdentifier();
+                }
+            }
+        }
+
+        GuiConfigurationValues mergedValues = new GuiConfigurationValues(
+                current.sourceFolder(),
+                current.targetFolder(),
+                current.sqliteFile(),
+                current.promptTemplateFile(),
+                current.runtimeLockFile(),
+                current.logDirectory(),
+                current.logLevel(),
+                current.maxRetriesTransient(),
+                current.maxPages(),
+                current.maxTextCharacters(),
+                current.maxTitleLength(),
+                current.logAiSensitive(),
+                current.activeProviderFamily(),
+                merged);
+
+        return new MergeResult(mergedValues, preservedProvider);
+    }
+
+    /**
+     * Result of an API-key merge operation.
+     *
+     * @param values                    the merged configuration values; never {@code null}
+     * @param preservedProviderIdentifier provider identifier when a key was preserved from
+     *                                   the baseline; {@code null} when no preservation occurred
+     */
+    public record MergeResult(GuiConfigurationValues values, String preservedProviderIdentifier) {
+
+        /**
+         * Returns whether at least one provider API key was silently preserved.
+         *
+         * @return {@code true} when a preservation event occurred
+         */
+        public boolean hasPreservationNote() {
+            return preservedProviderIdentifier != null;
+        }
+    }
+}
@@ -0,0 +1,25 @@
+package de.gecheckt.pdf.umbenenner.adapter.in.gui.editor;
+
+/**
+ * Derived change-state view for the editor content.
+ * <p>
+ * The value is computed from the comparison between the baseline values and the current
+ * editor values.
+ */
+public enum GuiChangeState {
+
+    /** The current editor state matches its baseline. */
+    CLEAN,
+
+    /** The current editor state has diverged from its baseline. */
+    DIRTY;
+
+    /**
+     * Returns whether this state represents unsaved changes.
+     *
+     * @return {@code true} when the editor is dirty, otherwise {@code false}
+     */
+    public boolean isDirty() {
+        return this == DIRTY;
+    }
+}
--- a/Show More
+++ b/Show More