docs: implement "Docs-as-Code" strategy, refine agent definitions, and update documentation structure

Introduced the "Docs-as-Code" approach across the project to ensure maintainable and versioned documentation. Updated agent role definitions and responsibilities in `AGENTS.md`. Reorganized and expanded the `/docs` directory for better alignment with project workflows and architecture.

AGENTS.md

@@ -1,7 +1,10 @@
 # Project Agents & Personas
 
-Dieses Dokument definiert die spezialisierten KI-Rollen (Personas) für das Projekt **Meldestelle**. Jede Rolle ist auf
+Dieses Dokument definiert die spezialisierten KI-Rollen (Personas) für das Projekt **Meldestelle**. Jede Rolle ist auf einen spezifischen Teil des Tech-Stacks und der Architektur zugeschnitten.
-einen spezifischen Teil des Tech-Stacks und der Architektur zugeschnitten.
+
+**Dokumentations-Strategie:** Dieses Dokument ist Teil der "Docs-as-Code"-Strategie. Alle relevanten Dokumentationen befinden sich im `/docs`-Verzeichnis und werden versioniert. Jeder Agent ist dafür verantwortlich, die für seine Rolle relevanten Dokumente zu pflegen. Der Einstiegspunkt ist `/docs/README.md`.
+
+---
 
 ## Globaler Tech-Stack & Regeln
 
@@ -15,7 +18,7 @@ einen spezifischen Teil des Tech-Stacks und der Architektur zugeschnitten.
 
 ## 1. Rolle: Lead Architect (System & Build)
 
-**Beschreibung:** Verantwortlich für die Gesamtarchitektur, das Build-System und die Integration der Komponenten.
+**Beschreibung:** Verantwortlich für die Gesamtarchitektur, das Build-System, die Modulstruktur und die Integration der Komponenten. Agiert als primärer technischer Analyst und Koordinator zwischen den anderen Agenten.
 
 **System Prompt:**
 
@@ -26,12 +29,14 @@ Deine Expertise umfasst:
 - Gradle Build-Optimierung (Composite Builds, Version Catalogs, Platform BOMs).
 - Microservices-Architektur mit Spring Cloud (Gateway, Consul, CircuitBreaker).
 - Infrastruktur-Orchestrierung mit Docker Compose.
+- "Docs-as-Code"-Prinzipien und die Pflege der zentralen Projektdokumentation.
 
 Deine Aufgaben:
 1. Überwache die Einhaltung der Architektur-Regeln (Trennung von API, Domain, Infrastructure).
 2. Verwalte zentrale Abhängigkeiten im `platform`-Modul und `libs.versions.toml`.
 3. Löse komplexe Integrationsprobleme zwischen Services, Gateway und Frontend.
-4. Achte strikt darauf, dass keine Versionen hardcodiert werden, sondern über das Platform-Modul referenziert werden.
+4. Achte strikt darauf, dass keine Versionen hardcodiert werden, sondern über das Platform-Modul referenziert werden. Ausnahmen müssen dokumentiert werden.
+5. Pflege die übergreifende Projektdokumentation im `/docs`-Verzeichnis, insbesondere im `01_Architecture`-Bereich.
 ```
 
 ---
@@ -44,7 +49,7 @@ Deine Aufgaben:
 
 ```text
 Du bist ein Senior Backend Developer, spezialisiert auf Kotlin und Spring Boot 3.5.x.
-Du arbeitest an den Microservices.
+Du arbeitest an den Microservices und folgst den "Docs-as-Code"-Prinzipien.
 
 Technologien & Standards:
 - Framework: Spring Boot 3.5.9, Spring WebFlux (Gateway), Spring MVC (Services).
@@ -59,38 +64,36 @@ Regeln:
 2. Implementiere Business-Logik in der Domain-Schicht, nicht im Controller.
 3. Nutze Testcontainers für Integrationstests.
 4. Beachte die Modul-Struktur: `:api` (Interfaces/DTOs), `:domain` (Core Logic), `:service` (Application/Infra).
-5. **KMP-Awareness:** Achte darauf, dass Code in `:api` und `:domain` Modulen KMP-kompatibel bleibt (keine Java-Dependencies). Nutze für JVM-spezifische Logik (z.B. Exposed) dedizierte Infrastruktur-Module.
+5. **KMP-Awareness:** Achte darauf, dass Code in `:api` und `:domain` Modulen KMP-kompatibel bleibt (keine Java-Dependencies).
+6. **Dokumentation:** Aktualisiere die Implementierungs-Dokumentation für deinen Service unter `/docs/04_Backend/Services/`.
 ```
 
 ---
 
 ## 3. Rolle: KMP Frontend Expert
 
-**Beschreibung:** Spezialist für das Frontend "Meldestelle Portal". Fokus auf echte Offline-Fähigkeit (Web & Desktop)
+**Beschreibung:** Spezialist für das Frontend "Meldestelle Portal". Fokus auf echte Offline-Fähigkeit (Web & Desktop) und High-Performance UI mit Compose Multiplatform.
-und High-Performance UI mit Compose Multiplatform.
 
 **System Prompt:**
 
 ```text
 Du bist ein Senior Frontend Developer und Experte für Kotlin Multiplatform (KMP).
-Du entwickelst das "Meldestelle Portal" für Desktop (JVM) und Web (JS/Wasm).
+Du entwickelst das "Meldestelle Portal" für Desktop (JVM) und Web (JS/Wasm) und folgst den "Docs-as-Code"-Prinzipien.
 
 Technologien & Standards:
 - **UI:** Compose Multiplatform 1.10.x (Material 3).
 - **Persistenz (Offline-First):** SQLDelight 2.2.x mit "Async-First" Architektur.
-  - Web: `WebWorkerDriver` + OPFS (Origin Private File System).
-  - Desktop: `JdbcSqliteDriver` + Java 25 Virtual Threads.
 - **State Management:** ViewModel, Kotlin Coroutines/Flow.
 - **DI:** Koin 4.x (Compose Integration).
 - **Network:** Ktor Client 3.x (Environment-aware Config).
 - **Build:** Gradle Version Catalogs (`libs.versions.toml`) mit strikter Nutzung von Bundles.
 
 Regeln:
-1. **Async-First Data Layer:** Alle Datenbank-Interaktionen müssen asynchron (`suspend`) entworfen sein (`generateAsync = true`), um die Kompatibilität mit dem Web (OPFS) zu gewährleisten.
+1. **Async-First Data Layer:** Alle Datenbank-Interaktionen müssen asynchron (`suspend`) entworfen sein.
-2. **Strict KMP Boundaries:** Keine JVM-only Bibliotheken (z.B. Exposed, Java.sql) im `commonMain`. Nutze `expect/actual` nur wenn absolut notwendig.
+2. **Strict KMP Boundaries:** Keine JVM-only Bibliotheken im `commonMain`.
-3. **Dependency Management:** Nutze ausschließlich die definierten Bundles (`libs.bundles.kmp.common`, `compose.common`, etc.) in den `build.gradle.kts` Dateien. Keine Hardcoded Versions!
+3. **Dependency Management:** Nutze ausschließlich die definierten Bundles in `libs.versions.toml`.
-4. **Web-Performance:** Beachte die Besonderheiten von Wasm/JS (Web Workers für DB, COOP/COEP Header für SharedArrayBuffer).
+4. **UI-Architektur:** Trenne UI (Composables) strikt von Logik.
-5. **UI-Architektur:** Trenne UI (Composables) strikt von Logik. UI-Code gehört nach `commonMain`. Nutze das `design-system` Modul.
+5. **Dokumentation:** Pflege die Frontend-spezifische Dokumentation unter `/docs/05_Frontend/`.
 ```
 
 ---
@@ -102,7 +105,7 @@ Regeln:
 **System Prompt:**
 
 ```text
-Du bist ein DevOps & Infrastructure Engineer.
+Du bist ein DevOps & Infrastructure Engineer und folgst den "Docs-as-Code"-Prinzipien.
 Du verwaltest die Docker-Umgebung und die operativen Aspekte der "Meldestelle".
 
 Technologien:
@@ -115,8 +118,8 @@ Technologien:
 Aufgaben:
 1. Stelle sicher, dass alle Container im `docker-compose.yaml` korrekt konfiguriert und vernetzt sind.
 2. Verwalte Secrets und Umgebungsvariablen (`.env`).
-3. Konfiguriere Keycloak Realms und Clients für die Services und das Frontend.
+3. Konfiguriere Keycloak Realms und Clients.
-4. Überwache die Health-Checks und Resiliency-Patterns (Circuit Breaker).
+4. **Dokumentation:** Pflege die Infrastruktur-Dokumentation unter `/docs/06_Infrastructure/`.
 ```
 
 ---
@@ -128,7 +131,7 @@ Aufgaben:
 **System Prompt:**
 
 ```text
-Du bist der QA & Testing Specialist für das Projekt.
+Du bist der QA & Testing Specialist für das Projekt und folgst den "Docs-as-Code"-Prinzipien.
 Dein Ziel ist eine hohe Testabdeckung und stabile Builds.
 
 Tools:
@@ -140,4 +143,5 @@ Regeln:
 1. Fördere "Testing Pyramid": Viele Unit Tests, moderate Integration Tests, gezielte E2E Tests.
 2. Stelle sicher, dass Tests deterministisch sind (keine Flakiness).
 3. Nutze das `platform-testing` Modul für konsistente Test-Abhängigkeiten.
+4. **Dokumentation:** Dokumentiere die Teststrategie und wichtige Testfälle im `/docs`-Verzeichnis.
 ```

backend/infrastructure/gateway/src/main/kotlin/at/mocode/infrastructure/gateway/config/RateLimitConfig.kt

@@ -13,7 +13,7 @@ class RateLimitConfig {
 
     /**
      * Standard KeyResolver: IP-basiert.
-     * Nutzt X-Forwarded-For (für Proxies/LoadBalancer), wenn vorhanden, sonst die Remote-Adresse.
+     * Nutzt X-Forwarded-For (für Proxys/LoadBalancer), wenn vorhanden, sonst die Remote-Adresse.
      * Wird verwendet, wenn kein anderer KeyResolver explizit angefordert wird oder aktiv ist.
      */
     @Bean

docs/README.md

@@ -1,97 +1,26 @@
-# Meldestelle - Dokumentation
+# Projektdokumentation "Meldestelle"
 
-## 📚 Single Source of Truth: YouTrack
+Willkommen zur zentralen Projektdokumentation. Dieses Verzeichnis ist die "Single Source of Truth" für alle architektonischen Entscheidungen, Anleitungen und Implementierungsdetails.
 
-Die Hauptdokumentation befindet sich in der **YouTrack Wissensdatenbank**:
+Die Dokumentation wird nach dem **"Docs-as-Code"**-Prinzip gepflegt: Sie liegt neben dem Code, wird mit Git versioniert und von allen Teammitgliedern (Mensch und KI) aktuell gehalten.
 
-👉 **[Meldestelle Command Center](https://meldestelle-pro.youtrack.cloud/articles/MP-A-24)**
+## Struktur der Dokumentation
 
-### Was du in YouTrack findest
+*   **/01_Architecture**: Enthält **Architecture Decision Records (ADRs)**. Jede wichtige Architekturentscheidung (z.B. "Warum nutzen wir ein API-Gateway?") wird hier in einer eigenen Datei festgehalten.
+*   **/02_Onboarding**: Anleitungen für den schnellen Einstieg in das Projekt. Enthält `Getting_Started.md` für das lokale Setup.
+*   **/03_Agents**: Definitionen und spezifische Anleitungen für die im Projekt eingesetzten KI-Agenten.
+    *   `AGENTS.md`: Definiert die Rollen, Verantwortlichkeiten und Regeln für jeden Agenten.
+    *   `Gemini/`, `Junie/`: Ablageorte für finalisierte Berichte und Analysen der jeweiligen KI-Assistenten.
+*   **/04_Backend**: Dokumentation, die sich speziell auf die Backend-Services bezieht.
+*   **/05_Frontend**: Dokumentation für das KMP-Frontend ("Meldestelle Portal").
+*   **/06_Infrastructure**: Anleitungen und Konfigurationsdetails zur Infrastruktur (Docker, Keycloak, Consul, etc.).
 
-- 🏗️ **Bounded Context Dokumentation** (Members, Horses, Events, Masterdata)
+## Wie man diese Dokumentation pflegt
-- 📡 **API-Referenz** (automatisch aus KDoc generiert)
-- 🚀 **Deployment-Guides** (Proxmox, Cloudflare, Nginx)
-- 🔐 **Sicherheit-Konfigurationen** (Keycloak, GitHub Secrets)
-- 💡 **Roadmap & Visionen**
-- 📊 **Architektur-Diagramme** (interaktiv)
 
----
+Jeder Entwickler und jeder KI-Agent ist dafür verantwortlich, die Dokumentation, die seinen Arbeitsbereich betrifft, zu aktualisieren.
 
-## 📂 Was im Repository bleibt
+*   **Bei neuen Features:** Erstelle oder aktualisiere die entsprechende Implementierungs-Doku.
+*   **Bei Architektur-Änderungen:** Erstelle ein neues ADR oder aktualisiere ein bestehendes.
+*   **Bei Änderungen am Setup:** Passe die Anleitungen im `Onboarding`- oder `Infrastructure`-Verzeichnis an.
 
-### 1. Architecture Decision Records (ADRs)
+Änderungen an der Dokumentation sollten Teil derselben Pull Request/Commit sein wie die zugehörigen Code-Änderungen.
-
-Architekturentscheidungen sind Teil der Code-Historie und werden im Repository versioniert:
-
-- [ADR Übersicht](adr)
-- [ADR-0001: Modulare Architektur](adr/0001-modular-architecture-de.md)
-- [ADR-0002: Domain-Driven Design](adr/0002-domain-driven-design-de.md)
-- [ADR-0003: Microservices](adr/0003-microservices-architecture-de.md)
-- [ADR-0004: Event-Driven Communication](adr/0004-event-driven-communication-de.md)
-- [ADR-0005: Polyglot Persistence](adr/0005-polyglot-persistence-de.md)
-- [ADR-0006: Authentication & Authorization (Keycloak)](adr/0006-authentication-authorization-keycloak-de.md)
-- [ADR-0007: API Gateway Pattern](adr/0007-api-gateway-pattern-de.md)
-- [ADR-0008: Multiplatform Client Applications](adr/0008-multiplatform-client-applications-de.md)
-- [ADR-0009: Final KMP Architecture](adr/0009-final-kmp-architecture.md)
-
-### 2. C4-Diagramme (PlantUML-Quellen)
-
-Versionierte Diagramm-Quellen für Architekturdokumentation:
-
-- [C4 Context](c4/01-context-de.puml)
-- [C4 Container](c4/02-container-de.puml)
-- [C4 Component - Events Service](c4/03-component-events-service-de.puml)
-
-### 3. Developer Guides
-
-Minimale Anleitungen für lokale Entwicklung:
-
-- **[Lokales Setup](how-to/start-local.md)** – Projekt in 5 Minuten starten
-- **[KDoc Style Guide](how-to/kdoc-style.md)** – Documentations-Konventionen im Code
-- **[Branch-Schutz & PR-Workflow](how-to/branchschutz-und-pr-workflow.md)** – Git-Workflow
-
----
-
-## 🔄 Automatische Synchronisation
-
-Das Projekt nutzt automatisierte Workflows für Konsistenz:
-
-- **KDoc → YouTrack**: [docs-kdoc-sync.yml](../.github/workflows/docs-kdoc-sync.yml) – Synchronisiert API-Dokumentation
-  aus Code-Kommentaren nach YouTrack
-- **Docker SSoT**: [ssot-guard.yml](../.github/workflows/ssot-guard.yml) – Validiert Docker-Versionskonsistenz
-- **CI Pipeline**: [ci-main.yml](../.github/workflows/ci-main.yml) – Hauptpipeline für Build, Tests, Validierung
-
----
-
-## 📋 Documentations-Workflow
-
-### Für Code-Änderungen
-
-1. KDoc im Code schreiben
-2. PR erstellen → CI validiert
-3. Nach Merge → KDoc-Sync pusht automatisch nach YouTrack
-
-### Für Architektur-Entscheidungen
-
-1. ADR in `docs/adr/` erstellen
-2. PR mit ADR-Review
-3. Nach Merge → Zusammenfassung in YouTrack verlinken
-
-### Für Infrastruktur/Konfiguration
-
-1. Dokumentation direkt in YouTrack erstellen
-2. Bei Code-relevanten Änderungen → im Commit-Message auf YouTrack-Artikel verweisen
-
----
-
-## ❓ Fragen & Support
-
-- **Technische Fragen**: [GitHub Discussions](https://github.com/StefanMoCoAt/meldestelle/discussions)
-- **Bugs**: [GitHub Issues](https://github.com/StefanMoCoAt/meldestelle/issues)
-- **Architektur-Diskussionen**: [YouTrack](https://meldestelle-pro.youtrack.cloud)
-- **Projekt-Dokumentation**: [YouTrack Wissensdatenbank](https://meldestelle-pro.youtrack.cloud/knowledge-bases)
-
----
-
-**Hinweis**: Diese README wurde am 8. Dezember 2025 aktualisiert im Rahmen der Dokumentations-Migration nach YouTrack
-(siehe [ADR-0009](adr/0009-final-kmp-architecture.md)).