diff --git a/docs/00_General/00_documentation_map.md b/docs/00_General/00_documentation_map.md
index ed2474c..fef368d 100644
--- a/docs/00_General/00_documentation_map.md
+++ b/docs/00_General/00_documentation_map.md
@@ -18,9 +18,12 @@ Das Repository ist in **logische Domänen** unterteilt.
*Zielgruppe: Alle*
| Datei | Inhalt & Zweck |
| :--- | :--- |
+| `README.md` | **Einstiegspunkt.** Übersicht über die Dokumentationsstruktur, Schnellzugriff nach Rollen und Navigation. |
+| `00_quickstart.md` | **Schnellstart.** Installation und erste Schritte in 15 Minuten. Ideal für neue Benutzer. |
| `00_vision_and_strategy.md` | **Strategie.** Warum bauen wir das? Prinzipien (Privacy, Local-First), High-Level Architektur. |
| `00_glossary.md` | **Definitionen.** Was bedeutet "Smart Edge", "Traffic Control", "Chunk"? Verhindert Begriffsverwirrung. |
| `00_documentation_map.md` | **Dieser Index.** Navigationshilfe. |
+| `00_quality_checklist.md` | **Qualitätsprüfung.** Systematische Checkliste zur Vollständigkeitsprüfung für alle Rollen. |
### 📂 01_User_Manual (Anwendung)
*Zielgruppe: Mindmaster, Autoren, Power-User*
@@ -28,7 +31,8 @@ Das Repository ist in **logische Domänen** unterteilt.
| :--- | :--- |
| `01_chat_usage_guide.md` | **Bedienung.** Wie steuere ich die Personas (Berater, Spiegel)? Wie nutze ich das Feedback? |
| `01_knowledge_design.md` | **Content-Regeln.** Die "Bibel" für den Vault. Erklärt Note-Typen, Matrix-Logik und Markdown-Syntax. |
-| `01-authoring-guidelines` | **Content strukturieren-.** primäres Werkzeug, um Wissen so zu strukturieren, so dass Mindnet die Persönlichkeit spiegelt, empathisch reagiert und strategisch berät |
+| `01_authoring_guidelines.md` | **Content strukturieren.** Primäres Werkzeug, um Wissen so zu strukturieren, dass Mindnet die Persönlichkeit spiegelt, empathisch reagiert und strategisch berät. |
+| `01_obsidian_integration_guide.md` | **Obsidian Setup.** Technische Anleitung für die Integration von Mindnet mit Obsidian (Templater, Skripte, Workflows). |
### 📂 02_Concepts (Fachliche Logik)
*Zielgruppe: Architekten, Product Owner*
@@ -36,6 +40,7 @@ Das Repository ist in **logische Domänen** unterteilt.
| :--- | :--- |
| `02_concept_graph_logic.md` | **Graph-Theorie.** Abstrakte Erklärung von Knoten, Kanten, Provenance und Idempotenz. |
| `02_concept_ai_personality.md`| **KI-Verhalten.** Konzepte hinter dem Hybrid Router, Empathie-Modell und "Teach-the-AI". |
+| `02_concept_architecture_patterns.md` | **Architektur-Patterns.** Design-Entscheidungen, modulare Struktur (WP-14), Resilienz-Patterns und Erweiterbarkeit. |
### 📂 03_Technical_Reference (Technik & Code)
*Zielgruppe: Entwickler, DevOps. (Enthält JSON/YAML Beispiele)*
@@ -47,12 +52,15 @@ Das Repository ist in **logische Domänen** unterteilt.
| `03_tech_chat_backend.md` | **API & LLM.** Implementation des Routers, Traffic Control (Semaphore) und Feedback-Traceability. |
| `03_tech_frontend.md` | **UI & Graph.** Architektur des Streamlit-Frontends, State-Management, Cytoscape-Integration und Editor-Logik. |
| `03_tech_configuration.md` | **Config.** Referenztabellen für `.env`, `types.yaml` und `retriever.yaml`. |
+| `03_tech_api_reference.md` | **API-Referenz.** Vollständige Dokumentation aller Endpunkte (`/query`, `/chat`, `/ingest`, `/graph`, etc.). |
### 📂 04_Operations (Betrieb)
*Zielgruppe: Administratoren*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `04_admin_operations.md` | **Runbook.** Installation, Docker-Setup, Backup/Restore, Troubleshooting Guide. |
+| `04_server_operation_manual.md` | **Server-Betrieb.** Detaillierte Dokumentation für den Betrieb auf llm-node (Systemd, Borgmatic, Disaster Recovery). |
+| `04_deployment_guide.md` | **Deployment.** CI/CD-Pipelines, Rollout-Strategien, Versionierung, Rollback und Pre/Post-Deployment-Checklisten. |
### 📂 05_Development (Code)
*Zielgruppe: Entwickler*
@@ -60,6 +68,7 @@ Das Repository ist in **logische Domänen** unterteilt.
| :--- | :--- |
| `05_developer_guide.md` | **Workflow.** Hardware-Setup (Win/Pi/Beelink), Git-Flow, Test-Befehle, Modul-Interna. |
| `05_genai_best_practices.md` | **AI Workflow.** Prompt-Library, Templates und Best Practices für die Entwicklung mit LLMs. |
+| `05_testing_guide.md` | **Testing.** Umfassender Test-Guide: Strategien, Frameworks, Test-Daten, Best Practices. |
### 📂 06_Roadmap & 99_Archive
*Zielgruppe: Projektleitung*
@@ -82,7 +91,9 @@ Nutze diese Matrix, wenn du ein Workpackage bearbeitest, um die Dokumentation ko
| **Retrieval / Scoring** | `03_tech_retrieval_scoring.md` (Formeln anpassen) |
| **Frontend / Visualisierung** | 1. `03_tech_frontend.md` (Technische Details)
2. `01_chat_usage_guide.md` (Bedienung) |
| **Chat-Logik / Prompts**| 1. `02_concept_ai_personality.md` (Konzept)
2. `03_tech_chat_backend.md` (Tech)
3. `01_chat_usage_guide.md` (User-Sicht) |
-| **Deployment / Server** | `04_admin_operations.md` |
+| **Architektur / Design-Patterns** | 1. `02_concept_architecture_patterns.md` (Patterns & Entscheidungen)
2. `02_concept_graph_logic.md` (Graph-Theorie)
3. `05_developer_guide.md` (Modulare Struktur) |
+| **Deployment / Server** | 1. `04_deployment_guide.md` (CI/CD, Rollout)
2. `04_admin_operations.md` (Installation, Wartung)
3. `04_server_operation_manual.md` (Server-Betrieb) |
+| **Testing / QA** | 1. `05_testing_guide.md` (Test-Strategien & Frameworks)
2. `05_developer_guide.md` (Test-Befehle) |
| **Neuen Features (Allg.)**| `06_active_roadmap.md` (Status Update) |
---
@@ -110,4 +121,38 @@ Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten
audience: developer
context: "Beschreibung der Scoring-Formel."
---
- ```
\ No newline at end of file
+ ```
+
+---
+
+## 5. Schnellzugriff & Empfehlungen
+
+### Für neue Benutzer
+1. Starte mit **[Schnellstart](00_quickstart.md)** für die Installation
+2. Lese **[Vision & Strategie](00_vision_and_strategy.md)** für das große Bild
+3. Nutze **[Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md)** für die ersten Schritte
+
+### Für Entwickler
+1. **[Developer Guide](../05_Development/05_developer_guide.md)** - Umfassender technischer Guide
+2. **[Technical References](../03_Technical_References/)** - Detaillierte API- und Architektur-Dokumentation
+3. **[GenAI Best Practices](../05_Development/05_genai_best_practices.md)** - Workflow mit LLMs
+
+### Für Administratoren
+1. **[Admin Operations](../04_Operations/04_admin_operations.md)** - Installation und Wartung
+2. **[Server Operations Manual](../04_Operations/04_server_operation_manual.md)** - Server-Betrieb und Disaster Recovery
+3. **[Troubleshooting Guide](../04_Operations/04_admin_operations.md#33-troubleshooting-guide)** - Häufige Probleme und Lösungen
+
+### Für Autoren
+1. **[Knowledge Design](../01_User_Manual/01_knowledge_design.md)** - Content-Regeln und Best Practices
+2. **[Authoring Guidelines](../01_User_Manual/01_authoring_guidelines.md)** - Strukturierung für den Digitalen Zwilling
+3. **[Obsidian Integration](../01_User_Manual/01_obsidian_integration_guide.md)** - Workflow-Optimierung
+
+---
+
+## 6. Dokumentations-Status
+
+**Aktuelle Version:** 2.9.1
+**Letzte Aktualisierung:** 2025-01-XX
+**Status:** ✅ Vollständig und aktiv gepflegt
+
+**Hinweis:** Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden.
\ No newline at end of file
diff --git a/docs/00_General/00_quality_checklist.md b/docs/00_General/00_quality_checklist.md
new file mode 100644
index 0000000..1d1c447
--- /dev/null
+++ b/docs/00_General/00_quality_checklist.md
@@ -0,0 +1,166 @@
+---
+doc_type: quality_assurance
+audience: all
+status: active
+version: 2.9.1
+context: "Qualitätsprüfung der Dokumentation für alle Rollen: Vollständigkeit, Korrektheit und Anwendbarkeit."
+---
+
+# Dokumentations-Qualitätsprüfung
+
+Diese Checkliste dient zur systematischen Prüfung, ob die Dokumentation alle Fragen jeder Rolle vollständig beantwortet.
+
+## ✅ Entwickler
+
+### Setup & Installation
+- [x] **Lokales Setup:** [Developer Guide](../05_Development/05_developer_guide.md#6-lokales-setup-development)
+- [x] **Schnellstart:** [Quickstart](00_quickstart.md)
+- [x] **Hardware-Anforderungen:** [Admin Operations](../04_Operations/04_admin_operations.md#11-voraussetzungen)
+
+### Architektur & Code
+- [x] **Modulare Struktur:** [Developer Guide - Architektur](../05_Development/05_developer_guide.md#4-projektstruktur--modul-referenz-deep-dive)
+- [x] **Design-Patterns:** [Architektur-Patterns](../02_concepts/02_concept_architecture_patterns.md)
+- [x] **API-Referenz:** [API Reference](../03_Technical_References/03_tech_api_reference.md)
+- [x] **Datenmodell:** [Data Model](../03_Technical_References/03_tech_data_model.md)
+
+### Entwicklung & Erweiterung
+- [x] **Workflow:** [Developer Guide - Workflow](../05_Development/05_developer_guide.md#7-der-entwicklungs-zyklus-workflow)
+- [x] **Erweiterungs-Guide:** [Teach-the-AI](../05_Development/05_developer_guide.md#8-erweiterungs-guide-teach-the-ai)
+- [x] **GenAI Best Practices:** [GenAI Best Practices](../05_Development/05_genai_best_practices.md)
+
+### Testing
+- [x] **Test-Strategien:** [Testing Guide](../05_Development/05_testing_guide.md)
+- [x] **Test-Frameworks:** [Testing Guide - Frameworks](../05_Development/05_testing_guide.md#3-test-frameworks--tools)
+- [x] **Test-Daten:** [Testing Guide - Test-Daten](../05_Development/05_testing_guide.md#2-test-daten--vaults)
+
+### Debugging & Troubleshooting
+- [x] **Troubleshooting:** [Developer Guide - Troubleshooting](../05_Development/05_developer_guide.md#10-troubleshooting--one-liners)
+- [x] **Debug-Tools:** [Testing Guide - Debugging](../05_Development/05_testing_guide.md#7-debugging--diagnose)
+
+---
+
+## ✅ Administratoren
+
+### Installation & Setup
+- [x] **Installation:** [Admin Operations](../04_Operations/04_admin_operations.md#1-installation--setup)
+- [x] **Docker Setup:** [Admin Operations - Qdrant](../04_Operations/04_admin_operations.md#12-qdrant-docker)
+- [x] **Systemd Services:** [Admin Operations - Deployment](../04_Operations/04_admin_operations.md#2-deployment-systemd-services)
+
+### Betrieb & Wartung
+- [x] **Monitoring:** [Admin Operations - Wartung](../04_Operations/04_admin_operations.md#3-wartung--monitoring)
+- [x] **Backup & Restore:** [Admin Operations - Backup](../04_Operations/04_admin_operations.md#4-backup--restore)
+- [x] **Troubleshooting:** [Admin Operations - Troubleshooting](../04_Operations/04_admin_operations.md#33-troubleshooting-guide)
+
+### Server-Betrieb
+- [x] **Server-Konfiguration:** [Server Operations Manual](../04_Operations/04_server_operation_manual.md)
+- [x] **Disaster Recovery:** [Server Operations - DR](../04_Operations/04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr)
+- [x] **Backup-Strategie:** [Server Operations - Backup](../04_Operations/04_server_operation_manual.md#4-backup-strategie-borgmatic)
+
+### Konfiguration
+- [x] **ENV-Variablen:** [Configuration Reference](../03_Technical_References/03_tech_configuration.md#1-environment-variablen-env)
+- [x] **YAML-Configs:** [Configuration Reference - YAML](../03_Technical_References/03_tech_configuration.md#2-typ-registry-typesyaml)
+
+---
+
+## ✅ Anwender
+
+### Erste Schritte
+- [x] **Schnellstart:** [Quickstart](00_quickstart.md)
+- [x] **Was ist Mindnet:** [Vision & Strategie](00_vision_and_strategy.md)
+- [x] **Grundlagen:** [Glossar](00_glossary.md)
+
+### Nutzung
+- [x] **Chat-Bedienung:** [Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md)
+- [x] **Graph Explorer:** [Chat Usage Guide - Graph](../01_User_Manual/01_chat_usage_guide.md#22-modus--graph-explorer-cytoscape)
+- [x] **Editor:** [Chat Usage Guide - Editor](../01_User_Manual/01_chat_usage_guide.md#23-modus--manueller-editor)
+
+### Content-Erstellung
+- [x] **Knowledge Design:** [Knowledge Design Manual](../01_User_Manual/01_knowledge_design.md)
+- [x] **Authoring Guidelines:** [Authoring Guidelines](../01_User_Manual/01_authoring_guidelines.md)
+- [x] **Obsidian-Integration:** [Obsidian Integration](../01_User_Manual/01_obsidian_integration_guide.md)
+
+### Häufige Fragen
+- [x] **Wie strukturiere ich Notizen?** → [Knowledge Design](../01_User_Manual/01_knowledge_design.md)
+- [x] **Welche Note-Typen gibt es?** → [Knowledge Design - Typ-Referenz](../01_User_Manual/01_knowledge_design.md#31-typ-referenz--stream-logik)
+- [x] **Wie verknüpfe ich Notizen?** → [Knowledge Design - Edges](../01_User_Manual/01_knowledge_design.md#4-edges--verlinkung)
+- [x] **Wie nutze ich den Chat?** → [Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md)
+
+---
+
+## ✅ Tester
+
+### Test-Strategien
+- [x] **Test-Pyramide:** [Testing Guide - Strategien](../05_Development/05_testing_guide.md#1-test-strategie--ebenen)
+- [x] **Unit Tests:** [Testing Guide - Unit Tests](../05_Development/05_testing_guide.md#11-unit-tests-pytest)
+- [x] **Integration Tests:** [Testing Guide - Integration](../05_Development/05_testing_guide.md#12-integration-tests)
+- [x] **E2E Tests:** [Testing Guide - E2E](../05_Development/05_testing_guide.md#13-e2e--smoke-tests)
+
+### Test-Frameworks
+- [x] **Pytest:** [Testing Guide - Frameworks](../05_Development/05_testing_guide.md#31-pytest-unit-tests)
+- [x] **Unittest:** [Testing Guide - Unittest](../05_Development/05_testing_guide.md#32-unittest-e2e-tests)
+- [x] **Shell-Skripte:** [Testing Guide - Shell](../05_Development/05_testing_guide.md#33-shell-skripte-e2e-roundtrip)
+
+### Test-Daten & Tools
+- [x] **Test-Vault erstellen:** [Testing Guide - Test-Daten](../05_Development/05_testing_guide.md#21-test-vault-erstellen)
+- [x] **Test-Skripte:** [Developer Guide - Scripts](../05_Development/05_developer_guide.md#44-scripts--tooling-die-admin-toolbox)
+- [x] **Test-Checkliste:** [Testing Guide - Checkliste](../05_Development/05_testing_guide.md#8-test-checkliste-für-pull-requests)
+
+---
+
+## ✅ Deployment
+
+### Deployment-Prozesse
+- [x] **Deployment-Guide:** [Deployment Guide](../04_Operations/04_deployment_guide.md)
+- [x] **CI/CD Pipeline:** [Deployment Guide - CI/CD](../04_Operations/04_deployment_guide.md#9-cicd-pipeline-details)
+- [x] **Rollout-Strategien:** [Deployment Guide - Rollout](../04_Operations/04_deployment_guide.md#4-rollout-strategien)
+
+### Versionierung & Releases
+- [x] **Version-Schema:** [Deployment Guide - Versionierung](../04_Operations/04_deployment_guide.md#51-version-schema)
+- [x] **Release-Prozess:** [Deployment Guide - Release](../04_Operations/04_deployment_guide.md#52-release-prozess)
+
+### Rollback & Recovery
+- [x] **Rollback-Strategien:** [Deployment Guide - Rollback](../04_Operations/04_deployment_guide.md#6-rollback-strategien)
+- [x] **Disaster Recovery:** [Server Operations - DR](../04_Operations/04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr)
+
+### Pre/Post-Deployment
+- [x] **Pre-Deployment Checkliste:** [Deployment Guide - Checkliste](../04_Operations/04_deployment_guide.md#7-pre-deployment-checkliste)
+- [x] **Post-Deployment Validierung:** [Deployment Guide - Validierung](../04_Operations/04_deployment_guide.md#8-post-deployment-validierung)
+
+---
+
+## 📊 Zusammenfassung
+
+### Vollständigkeit nach Rolle
+
+| Rolle | Abgedeckte Themen | Status |
+| :--- | :--- | :--- |
+| **Entwickler** | Setup, Architektur, Code, Testing, Debugging | ✅ Vollständig |
+| **Administratoren** | Installation, Betrieb, Wartung, Backup, DR | ✅ Vollständig |
+| **Anwender** | Nutzung, Content-Erstellung, Workflows | ✅ Vollständig |
+| **Tester** | Test-Strategien, Frameworks, Tools | ✅ Vollständig |
+| **Deployment** | CI/CD, Rollout, Versionierung, Rollback | ✅ Vollständig |
+
+### Neue Dokumente
+
+1. ✅ `05_testing_guide.md` - Umfassender Test-Guide
+2. ✅ `04_deployment_guide.md` - Vollständiger Deployment-Guide
+3. ✅ `02_concept_architecture_patterns.md` - Architektur-Patterns
+4. ✅ `03_tech_api_reference.md` - API-Referenz
+5. ✅ `00_quickstart.md` - Schnellstart-Anleitung
+6. ✅ `README.md` - Dokumentations-Einstiegspunkt
+
+### Aktualisierte Dokumente
+
+1. ✅ `00_documentation_map.md` - Alle neuen Dokumente aufgenommen
+2. ✅ `04_admin_operations.md` - Troubleshooting erweitert
+3. ✅ `05_developer_guide.md` - Modulare Struktur ergänzt
+4. ✅ `03_tech_ingestion_pipeline.md` - Background Tasks dokumentiert
+5. ✅ `03_tech_configuration.md` - Fehlende ENV-Variablen ergänzt
+6. ✅ `00_vision_and_strategy.md` - Design-Entscheidungen ergänzt
+
+---
+
+**Status:** ✅ Alle Rollen vollständig abgedeckt
+**Letzte Prüfung:** 2025-01-XX
+**Version:** 2.9.1
+
diff --git a/docs/00_General/00_quickstart.md b/docs/00_General/00_quickstart.md
new file mode 100644
index 0000000..d8b98a4
--- /dev/null
+++ b/docs/00_General/00_quickstart.md
@@ -0,0 +1,156 @@
+---
+doc_type: quickstart_guide
+audience: user, developer, admin
+status: active
+version: 2.9.1
+context: "Schnellstart-Anleitung für neue Benutzer von Mindnet"
+---
+
+# Mindnet Schnellstart
+
+Diese Anleitung hilft dir, in 15 Minuten mit Mindnet loszulegen.
+
+## 🎯 Was ist Mindnet?
+
+Mindnet ist ein **persönliches KI-Gedächtnis**, das:
+- Dein Wissen in Markdown-Notizen speichert
+- Semantisch verknüpft (Wissensgraph)
+- Als intelligenter Dialogpartner agiert (RAG-Chat)
+- **Lokal und privat** läuft (Privacy First)
+
+## 📋 Voraussetzungen
+
+- **Python 3.10+** installiert
+- **Docker** installiert (für Qdrant)
+- **Ollama** installiert (für lokale LLMs)
+- Optional: **Obsidian** (für komfortables Schreiben)
+
+## ⚡ Installation (5 Minuten)
+
+### Schritt 1: Repository klonen
+
+```bash
+git clone mindnet
+cd mindnet
+```
+
+### Schritt 2: Virtuelle Umgebung erstellen
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate # Windows: .venv\Scripts\activate
+```
+
+### Schritt 3: Abhängigkeiten installieren
+
+```bash
+pip install -r requirements.txt
+```
+
+### Schritt 4: Qdrant starten (Docker)
+
+```bash
+docker compose up -d qdrant
+```
+
+### Schritt 5: Ollama-Modelle laden
+
+```bash
+ollama pull phi3:mini
+ollama pull nomic-embed-text
+```
+
+### Schritt 6: Konfiguration anpassen
+
+Erstelle eine `.env`-Datei im Projektroot:
+
+```ini
+QDRANT_URL=http://localhost:6333
+MINDNET_OLLAMA_URL=http://localhost:11434
+MINDNET_LLM_MODEL=phi3:mini
+MINDNET_EMBEDDING_MODEL=nomic-embed-text
+COLLECTION_PREFIX=mindnet
+MINDNET_VAULT_ROOT=./vault
+```
+
+## 🚀 Erste Schritte (5 Minuten)
+
+### Schritt 1: Backend starten
+
+```bash
+uvicorn app.main:app --reload --port 8001
+```
+
+### Schritt 2: Frontend starten (neues Terminal)
+
+```bash
+streamlit run app/frontend/ui.py --server.port 8501
+```
+
+### Schritt 3: Browser öffnen
+
+Öffne `http://localhost:8501` im Browser.
+
+### Schritt 4: Erste Notiz importieren
+
+Erstelle eine Test-Notiz im `vault/` Ordner:
+
+```markdown
+---
+id: 20250101-test
+title: Meine erste Notiz
+type: concept
+status: active
+---
+
+# Meine erste Notiz
+
+Dies ist eine Test-Notiz für Mindnet.
+
+[[rel:related_to Mindnet]]
+```
+
+Dann importiere sie:
+
+```bash
+python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply
+```
+
+### Schritt 5: Erste Chat-Anfrage
+
+Im Browser-Chat eingeben:
+```
+Was ist Mindnet?
+```
+
+## 📚 Nächste Schritte
+
+Nach dem Schnellstart empfehle ich:
+
+1. **[Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md)** - Lerne die Chat-Funktionen kennen
+2. **[Knowledge Design](../01_User_Manual/01_knowledge_design.md)** - Verstehe, wie du Notizen strukturierst
+3. **[Authoring Guidelines](../01_User_Manual/01_authoring_guidelines.md)** - Lerne Best Practices für das Schreiben
+
+## 🆘 Hilfe & Troubleshooting
+
+**Problem:** Qdrant startet nicht
+- **Lösung:** Prüfe, ob Docker läuft: `docker ps`
+
+**Problem:** Ollama-Modell nicht gefunden
+- **Lösung:** Prüfe mit `ollama list`, ob die Modelle geladen sind
+
+**Problem:** Import schlägt fehl
+- **Lösung:** Prüfe die Logs und stelle sicher, dass Qdrant läuft
+
+Für detaillierte Troubleshooting-Informationen siehe [Admin Operations](../04_Operations/04_admin_operations.md#33-troubleshooting-guide).
+
+## 🔗 Weitere Ressourcen
+
+- **[Dokumentationskarte](00_documentation_map.md)** - Übersicht aller Dokumente
+- **[Glossar](00_glossary.md)** - Wichtige Begriffe erklärt
+- **[Vision & Strategie](00_vision_and_strategy.md)** - Die Philosophie hinter Mindnet
+
+---
+
+**Viel Erfolg mit Mindnet!** 🚀
+
diff --git a/docs/00_General/00_vision_and_strategy.md b/docs/00_General/00_vision_and_strategy.md
index 47ae456..15fead6 100644
--- a/docs/00_General/00_vision_and_strategy.md
+++ b/docs/00_General/00_vision_and_strategy.md
@@ -64,4 +64,42 @@ Die folgenden Prinzipien steuern jede technische Entscheidung:
Jeder Importlauf und jede Retriever-Anfrage ist logbar.
10. **Local First & Privacy:**
- Nutzung lokaler LLMs (Ollama) für Inference. Keine Daten verlassen den Server.
\ No newline at end of file
+ Nutzung lokaler LLMs (Ollama) für Inference. Keine Daten verlassen den Server.
+
+11. **Modulare Architektur (WP-14):**
+ Core-Logik ist in spezialisierte Pakete unterteilt (`chunking/`, `database/`, `graph/`, `ingestion/`, `parser/`, `retrieval/`). Dies ermöglicht unabhängige Entwicklung, Testbarkeit und Wartbarkeit.
+
+12. **Resilienz durch Kaskaden:**
+ System nutzt Provider-Kaskaden (Cloud → Rate-Limit-Handling → Lokaler Fallback) für hohe Verfügbarkeit. Deep Fallback erkennt auch kognitive Blockaden (Silent Refusals).
+
+---
+
+## 4. Design-Entscheidungen & Trade-offs
+
+### 4.1 Qdrant als Vektor-DB
+**Entscheidung:** Self-hosted Qdrant statt Managed Service (Pinecone/Weaviate)
+**Gründe:** Privacy First, Open Source, lokale Kontrolle
+**Trade-off:** Mehr Wartungsaufwand, aber vollständige Datenhoheit
+
+### 4.2 Hybrid Retrieval
+**Entscheidung:** Kombination von Vektor-Suche (Semantik) und Graph-Expansion
+**Gründe:** Bessere Relevanz durch strukturelle Verbindungen
+**Trade-off:** Höhere Komplexität, aber deutlich bessere Ergebnisse
+
+### 4.3 Background Tasks statt Queue-System
+**Entscheidung:** FastAPI Background Tasks statt Redis/RabbitMQ
+**Gründe:** Einfacher Setup, ausreichend für Single-User
+**Trade-off:** Keine Persistenz bei Server-Neustart, aber weniger Infrastruktur
+
+### 4.4 Markdown als Source of Truth
+**Entscheidung:** Markdown-Dateien sind primär, Datenbank ist Cache
+**Gründe:** Versionierbarkeit, Editierbarkeit, Unabhängigkeit
+**Trade-off:** Zwei Datenquellen, aber maximale Flexibilität
+
+---
+
+## 5. Weitere Informationen
+
+- **Architektur-Patterns:** Siehe [Architektur-Patterns](../02_concepts/02_concept_architecture_patterns.md)
+- **Graph-Logik:** Siehe [Graph-Logik](../02_concepts/02_concept_graph_logic.md)
+- **KI-Persönlichkeit:** Siehe [KI-Persönlichkeit](../02_concepts/02_concept_ai_personality.md)
\ No newline at end of file
diff --git a/docs/01_User_Manual/01_chat_usage_guide.md b/docs/01_User_Manual/01_chat_usage_guide.md
index a4e6eee..c560530 100644
--- a/docs/01_User_Manual/01_chat_usage_guide.md
+++ b/docs/01_User_Manual/01_chat_usage_guide.md
@@ -11,6 +11,8 @@ context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des G
**Quellen:** `user_guide.md`
+> 💡 **Tipp für Einsteiger:** Falls du noch nie mit Mindnet gearbeitet hast, starte mit dem [Schnellstart](../00_General/00_quickstart.md) und dem [Knowledge Design Manual](01_knowledge_design.md), um die Grundlagen zu verstehen.
+
## 1. Was Mindnet für dich tut
Mindnet ist ein **assoziatives Gedächtnis** mit Persönlichkeit. Es unterscheidet sich von einer reinen Suche dadurch, dass es **kontextsensitiv** agiert.
@@ -123,4 +125,86 @@ Wenn du im **manuellen Editor** schreibst, unterstützt dich Mindnet aktiv bei d
* **Exakte Treffer:** Das System erkennt Begriffe wie "KI-Gedächtnis" als Alias für "Mindnet".
* **Semantische Treffer:** Das System findet inhaltlich verwandte Notizen.
* **Klick auf "➕ Einfügen":** Fügt den Link (z.B. `[[rel:related_to Mindnet]]`) an der Cursor-Position ein.
-4. **Speichern:** Der Text wird sofort in den Vault geschrieben und indiziert.
\ No newline at end of file
+4. **Speichern:** Der Text wird sofort in den Vault geschrieben und indiziert.
+
+### 6.3 Weg C: Direktes Schreiben in Obsidian
+Wenn du Obsidian nutzt, kannst du Notizen direkt im Vault erstellen. Nach dem Speichern in Obsidian:
+
+1. **Automatischer Import (Cron):** Der stündliche Cron-Job importiert neue/geänderte Dateien automatisch.
+2. **Manueller Import:** Oder führe manuell aus:
+ ```bash
+ python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply
+ ```
+
+**Vorteil:** Du arbeitest in deiner gewohnten Obsidian-Umgebung, Mindnet synchronisiert im Hintergrund.
+
+---
+
+## 7. Häufige Anwendungsfälle (Use Cases)
+
+### 7.1 Entscheidungshilfe suchen
+**Szenario:** Du stehst vor einer schwierigen Entscheidung.
+
+**Vorgehen:**
+1. Stelle eine Frage im Chat: *"Soll ich Tool X nutzen?"*
+2. Mindnet erkennt `DECISION` Intent
+3. System lädt deine Werte, Prinzipien und Ziele
+4. Antwort berücksichtigt deine persönlichen Kriterien
+
+**Beispiel:** *"Soll ich Notion nutzen?"* → System prüft gegen dein Prinzip "Privacy First" und rät ab.
+
+### 7.2 Erfahrungen dokumentieren
+**Szenario:** Du willst ein prägendes Erlebnis festhalten.
+
+**Vorgehen:**
+1. Chat: *"Neue Erfahrung: Streit am Recyclinghof"*
+2. System erstellt strukturierte Notiz mit Feldern:
+ - Situation
+ - Reaktion
+ - Learning
+3. Verknüpfe mit relevanten Rollen: `[[rel:supports Meine Rollenlandkarte 2025#Vater]]`
+
+### 7.3 Wissen im Graph erkunden
+**Szenario:** Du willst verstehen, wie Konzepte zusammenhängen.
+
+**Vorgehen:**
+1. Wechsle zum **Graph Explorer**
+2. Suche nach einem Knoten (z.B. "Projekt Alpha")
+3. Klicke auf "🎯 Als Zentrum setzen"
+4. Erkunde die Nachbarschaft (Abhängigkeiten, Entscheidungen, ähnliche Projekte)
+
+### 7.4 Bestehende Notizen verbessern
+**Szenario:** Eine Notiz ist unvollständig oder unvernetzt.
+
+**Vorgehen:**
+1. Öffne die Notiz im **Manuellen Editor**
+2. Nutze **Intelligence-Tab** für Link-Vorschläge
+3. Füge semantische Links hinzu: `[[rel:based_on Wert X]]`
+4. Speichern → System indiziert neu
+
+---
+
+## 8. Tipps & Tricks
+
+### 8.1 Intent-Steuerung
+- **Frage mit "?":** Löst RAG-Modus aus (Wissen abrufen)
+- **Aussage ohne "?":** Löst Interview-Modus aus (Wissen speichern)
+- **Emotionale Wörter:** Aktivieren Empathie-Persona ("Ich fühle...", "Ich bin frustriert...")
+
+### 8.2 Graph-Navigation
+- **URL-Persistenz:** Graph-Einstellungen werden in der URL gespeichert → Lesezeichen für spezifische Ansichten
+- **Deep-Links:** Verlinke präzise Abschnitte: `[[Note#Abschnitt]]` statt nur `[[Note]]`
+
+### 8.3 Feedback nutzen
+- **Regelmäßiges Feedback:** Macht das System schlauer
+- **Granulares Feedback:** Bewerte einzelne Quellen, nicht nur die Gesamtantwort
+- **Konsequenz:** System lernt deine Präferenzen
+
+---
+
+## 9. Weitere Informationen
+
+- **Knowledge Design:** Siehe [Knowledge Design Manual](01_knowledge_design.md)
+- **Authoring Guidelines:** Siehe [Authoring Guidelines](01_authoring_guidelines.md)
+- **Obsidian Integration:** Siehe [Obsidian Integration Guide](01_obsidian_integration_guide.md)
+- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](../04_Operations/04_admin_operations.md#33-troubleshooting-guide)
\ No newline at end of file
diff --git a/docs/02_concepts/02_concept_architecture_patterns.md b/docs/02_concepts/02_concept_architecture_patterns.md
new file mode 100644
index 0000000..5a14806
--- /dev/null
+++ b/docs/02_concepts/02_concept_architecture_patterns.md
@@ -0,0 +1,456 @@
+---
+doc_type: concept
+audience: architect, developer
+scope: architecture, design_patterns, modularization
+status: active
+version: 2.9.1
+context: "Architektur-Patterns, Design-Entscheidungen und modulare Struktur von Mindnet. Basis für Verständnis und Erweiterungen."
+---
+
+# Architektur-Patterns & Design-Entscheidungen
+
+Dieses Dokument beschreibt die zentralen Architektur-Patterns und Design-Entscheidungen, die Mindnet prägen. Es dient als Referenz für Entwickler und Architekten, um das System zu verstehen und konsistent zu erweitern.
+
+## 1. Kern-Paradigmen
+
+### 1.1 Filesystem First (Source of Truth)
+
+**Prinzip:** Markdown-Dateien im Vault sind die einzige Quelle der Wahrheit. Die Datenbank (Qdrant) ist ein abgeleiteter Index.
+
+**Implikationen:**
+- Dateien werden immer direkt von der Festplatte gelesen (z.B. im Editor)
+- Datenbank-Inhalte können aus Markdown rekonstruiert werden
+- Änderungen erfolgen primär im Vault, nicht in der DB
+- Die Datenbank ist ein Cache, kein primärer Speicher
+
+**Code-Beispiele:**
+- `ui_callbacks.py`: Liest Dateien direkt von Disk
+- `ingestion_processor.py`: Schreibt zuerst auf Disk, dann in DB
+
+### 1.2 Late Binding (Späte Semantik)
+
+**Prinzip:** Struktur und Interpretation werden in Konfigurationen definiert, nicht im Code.
+
+**Implikationen:**
+- Neue Note-Typen werden in `types.yaml` definiert, nicht im Code
+- Prompt-Templates sind in `prompts.yaml` konfigurierbar
+- Edge-Typen werden in `edge_vocabulary.md` verwaltet
+- Die "Persönlichkeit" ist Config, kein Code
+
+**Vorteile:**
+- Erweiterbarkeit ohne Code-Änderungen
+- A/B-Testing von Prompt-Strategien
+- Anpassung an verschiedene Use-Cases
+
+### 1.3 Virtual Schema Layer
+
+**Prinzip:** Markdown-Dateien benötigen nur minimale Frontmatter-Angaben. Komplexität wird zur Laufzeit injiziert.
+
+**Beispiel:**
+```yaml
+# Minimal im Frontmatter
+---
+id: 20250101-test
+title: Test
+type: project
+---
+
+# Im Code wird zur Laufzeit ergänzt:
+# - chunking_profile aus types.yaml
+# - retriever_weight aus types.yaml
+# - edge_defaults aus types.yaml
+```
+
+**Vorteile:**
+- Robuste Markdown-Dateien (weniger Breaking Changes)
+- Zentrale Verwaltung von Logik
+- Einfache Migration zwischen Versionen
+
+---
+
+## 2. Modulare Architektur (WP-14)
+
+### 2.1 Paket-Struktur
+
+Seit WP-14 ist die Core-Logik in spezialisierte Pakete unterteilt:
+
+```
+app/core/
+├── chunking/ # Text-Segmentierung
+│ ├── chunking_strategies.py # Sliding/Heading-Strategien
+│ ├── chunking_processor.py # Orchestrierung
+│ └── chunking_propagation.py # Edge-Vererbung
+├── database/ # Qdrant-Infrastruktur
+│ ├── qdrant.py # Client & Config
+│ └── qdrant_points.py # Point-Mapping
+├── graph/ # Graph-Logik
+│ ├── graph_subgraph.py # Expansion
+│ └── graph_weights.py # Scoring
+├── ingestion/ # Import-Pipeline
+│ ├── ingestion_processor.py # Two-Pass Workflow
+│ └── ingestion_validation.py # Mistral-safe Parsing
+├── parser/ # Markdown-Parsing
+│ ├── parsing_markdown.py # Frontmatter/Body
+│ └── parsing_scanner.py # File-Scan
+└── retrieval/ # Suche & Scoring
+ ├── retriever.py # Orchestrator
+ └── retriever_scoring.py # Mathematik
+```
+
+### 2.2 Design-Pattern: Proxy-Adapter (Abwärtskompatibilität)
+
+**Problem:** Nach WP-14 Modularisierung müssen alte Import-Pfade weiter funktionieren.
+
+**Lösung:** Proxy-Module leiten Anfragen an neue Pakete weiter.
+
+**Beispiel:**
+```python
+# app/core/retriever.py (Proxy)
+from .retrieval.retriever import (
+ Retriever, hybrid_retrieve, semantic_retrieve
+)
+__all__ = ["Retriever", "hybrid_retrieve", "semantic_retrieve"]
+```
+
+**Vorteile:**
+- Keine Breaking Changes für bestehenden Code
+- Graduelle Migration möglich
+- Alte Scripts funktionieren weiter
+
+### 2.3 Design-Pattern: Singleton (Edge Registry)
+
+**Problem:** Edge Registry muss konsistent über alle Services sein.
+
+**Lösung:** Singleton-Pattern mit Lazy Loading.
+
+**Code:**
+```python
+# app/services/edge_registry.py
+class EdgeRegistry:
+ _instance = None
+
+ def __new__(cls):
+ if cls._instance is None:
+ cls._instance = super().__new__(cls)
+ return cls._instance
+```
+
+**Vorteile:**
+- Einheitliche Validierung
+- Keine Duplikation von Vokabular-Daten
+- Thread-safe Initialisierung
+
+---
+
+## 3. Asynchrone Verarbeitung
+
+### 3.1 Background Tasks Pattern
+
+**Problem:** Ingestion kann lange dauern (LLM-Calls, Embeddings). Blockiert API nicht.
+
+**Lösung:** FastAPI Background Tasks für non-blocking Verarbeitung.
+
+**Flow:**
+1. API empfängt Request (`/ingest/save`)
+2. Datei wird sofort auf Disk geschrieben
+3. API antwortet mit `status: "queued"`
+4. Background Task startet Ingestion asynchron
+5. User kann weiterarbeiten
+
+**Code:**
+```python
+@router.post("/save")
+async def save_note(req: SaveRequest, background_tasks: BackgroundTasks):
+ # Sofortige Persistenz
+ write_to_disk(req.markdown_content)
+
+ # Async Processing
+ background_tasks.add_task(run_ingestion_task, ...)
+
+ return SaveResponse(status="queued", ...)
+```
+
+**Vorteile:**
+- Keine Timeouts bei großen Dateien
+- Bessere User Experience
+- System bleibt responsiv
+
+### 3.2 Traffic Control (Semaphore Pattern)
+
+**Problem:** Parallele LLM-Calls können System überlasten.
+
+**Lösung:** Semaphore begrenzt parallele Hintergrund-Tasks.
+
+**Code:**
+```python
+# app/services/llm_service.py
+background_semaphore = asyncio.Semaphore(
+ settings.BACKGROUND_LIMIT # Default: 2
+)
+
+async def generate(...):
+ if priority == "background":
+ async with background_semaphore:
+ return await _call_llm(...)
+ else: # realtime
+ return await _call_llm(...) # Keine Limitierung
+```
+
+**Vorteile:**
+- Schutz vor API-Quoten-Überschreitung
+- Stabiler Betrieb bei hoher Last
+- Priorisierung von Echtzeit-Anfragen
+
+---
+
+## 4. Resilienz-Patterns
+
+### 4.1 Provider-Kaskade (Fallback-Kette)
+
+**Problem:** Cloud-Provider können ausfallen oder Quoten überschreiten.
+
+**Lösung:** Dreistufige Kaskade mit intelligentem Fallback.
+
+**Stufen:**
+1. **Cloud (OpenRouter/Gemini):** Schnell, aber abhängig von Provider
+2. **Rate-Limit-Handling:** Automatische Retries bei HTTP 429
+3. **Lokaler Fallback (Ollama):** Langsam, aber immer verfügbar
+
+**Code:**
+```python
+# app/services/llm_service.py
+async def generate(...):
+ try:
+ return await _call_cloud(...)
+ except RateLimitError:
+ await asyncio.sleep(LLM_RATE_LIMIT_WAIT)
+ return await _call_cloud(...) # Retry
+ except Exception:
+ return await _call_ollama(...) # Fallback
+```
+
+**Vorteile:**
+- Hohe Verfügbarkeit
+- Kostenoptimierung (Cloud für Speed, Lokal für Fallback)
+- Resilienz gegen Provider-Ausfälle
+
+### 4.2 Deep Fallback (Kognitiver Fallback)
+
+**Problem:** Cloud liefert technisch erfolgreiche, aber inhaltlich leere Antworten (Silent Refusal).
+
+**Lösung:** Validierung der Antwort-Qualität, nicht nur HTTP-Status.
+
+**Code:**
+```python
+response = await _call_cloud(...)
+if is_valid_json(response):
+ return response
+else:
+ # Deep Fallback: Cloud hat blockiert, lokaler Fallback
+ return await _call_ollama(...)
+```
+
+**Vorteile:**
+- Erkennung von Policy-Violations
+- Datenintegrität trotz Cloud-Filter
+- Lokale Souveränität
+
+---
+
+## 5. Datenfluss-Patterns
+
+### 5.1 Two-Pass Workflow (WP-15b)
+
+**Problem:** Smart Edge Validation benötigt globalen Kontext (alle Notizen).
+
+**Lösung:** Zwei-Phasen-Import mit Pre-Scan.
+
+**Pass 1: Pre-Scan**
+- Schnelles Scannen aller Dateien
+- Aufbau von `LocalBatchCache` (IDs, Titel, Summaries)
+- Keine LLM-Calls
+
+**Pass 2: Semantic Processing**
+- Nur für geänderte Dateien
+- Binäre Validierung gegen Cache
+- Effiziente Nutzung von LLM-Quoten
+
+**Vorteile:**
+- Reduktion von LLM-Calls (nur Validierung, keine Extraktion)
+- Konsistente Validierung (globaler Kontext)
+- Schnellerer Import
+
+### 5.2 Idempotenz-Pattern
+
+**Prinzip:** Mehrfache Imports derselben Datei führen zum gleichen Ergebnis.
+
+**Mechanismen:**
+- **Deterministische IDs:** UUIDv5 basierend auf Datei-Inhalt
+- **Hash-basierte Change Detection:** Multi-Hash für `body` und `full`
+- **Deduplizierung:** Kanten werden anhand Identität erkannt
+
+**Code:**
+```python
+# Deterministische ID
+note_id = uuid.uuid5(NAMESPACE_URL, f"{file_path}#{content_hash}")
+
+# Change Detection
+if current_hash == stored_hash:
+ skip_processing() # Idempotent
+```
+
+**Vorteile:**
+- Sicherheit bei Re-Imports
+- Keine Duplikate
+- Konsistente Datenbank
+
+---
+
+## 6. Frontend-Patterns
+
+### 6.1 Active Inspector Pattern
+
+**Problem:** Graph-Re-Renders bei Knoten-Selektion führen zu Flackern.
+
+**Lösung:** CSS-Klassen statt State-Änderungen für Selektion.
+
+**Code:**
+```python
+# ui_graph_cytoscape.py
+stylesheet = [
+ {
+ "selector": ".inspected",
+ "style": {"border-width": 6, "border-color": "#FFC300"}
+ }
+]
+# Selektion ändert nur CSS-Klasse, nicht React-Key
+```
+
+**Vorteile:**
+- Stabiles UI (kein Re-Render)
+- Bessere Performance
+- Smooth User Experience
+
+### 6.2 Resurrection Pattern
+
+**Problem:** Streamlit vergisst Eingaben bei Re-Runs.
+
+**Lösung:** Aggressive Synchronisation in `session_state`.
+
+**Code:**
+```python
+# ui_editor.py
+if widget_key not in st.session_state:
+ st.session_state[widget_key] = restore_from_data_key()
+```
+
+**Vorteile:**
+- Texteingaben überleben Tab-Wechsel
+- Keine Datenverluste
+- Bessere UX
+
+---
+
+## 7. Erweiterbarkeit: "Teach-the-AI" Paradigma
+
+Mindnet lernt durch **Konfiguration**, nicht durch Training.
+
+### 7.1 Drei-Ebenen-Erweiterung
+
+**1. Daten-Ebene (`types.yaml`):**
+```yaml
+risk:
+ retriever_weight: 0.90
+ edge_defaults: ["blocks"]
+```
+
+**2. Strategie-Ebene (`decision_engine.yaml`):**
+```yaml
+DECISION:
+ inject_types: ["value", "risk"]
+```
+
+**3. Kognitive Ebene (`prompts.yaml`):**
+```yaml
+risk_definition:
+ ollama: "Ein Risiko ist eine potenzielle Gefahr..."
+```
+
+**Vorteile:**
+- Keine Code-Änderungen nötig
+- Schnelle Iteration
+- A/B-Testing möglich
+
+---
+
+## 8. Design-Entscheidungen & Trade-offs
+
+### 8.1 Qdrant als Vektor-DB
+
+**Entscheidung:** Qdrant statt Pinecone/Weaviate
+
+**Gründe:**
+- Self-hosted (Privacy First)
+- Open Source
+- Gute Performance bei lokaler Installation
+
+**Trade-off:** Mehr Wartungsaufwand als Managed Service
+
+### 8.2 Hybrid Retrieval (Semantik + Graph)
+
+**Entscheidung:** Kombination von Vektor-Suche und Graph-Expansion
+
+**Gründe:**
+- Semantik findet ähnliche Inhalte
+- Graph findet strukturelle Verbindungen
+- Kombination liefert bessere Relevanz
+
+**Trade-off:** Höhere Komplexität, mehr Berechnungsaufwand
+
+### 8.3 Background Tasks statt Queue-System
+
+**Entscheidung:** FastAPI Background Tasks statt Redis/RabbitMQ
+
+**Gründe:**
+- Einfacher Setup (keine zusätzliche Infrastruktur)
+- Ausreichend für Single-User-Szenario
+- Weniger Moving Parts
+
+**Trade-off:** Keine Persistenz bei Server-Neustart (Tasks gehen verloren)
+
+---
+
+## 9. Konsistenz-Garantien
+
+### 9.1 Deterministische IDs
+
+**Prinzip:** UUIDv5 basierend auf Datei-Inhalt
+
+**Vorteile:**
+- Reproduzierbare IDs
+- Keine Duplikate bei Re-Import
+- Graph ist aus Markdown rekonstruierbar
+
+### 9.2 Provenance-Hierarchie
+
+**Prinzip:** Kanten haben Qualitätsstufen (explicit > smart > rule)
+
+**Vorteile:**
+- Menschliche Intention hat Vorrang
+- System-Heuristiken können überschrieben werden
+- Transparente Gewichtung
+
+---
+
+## 10. Weitere Informationen
+
+- **Vision & Strategie:** Siehe [Vision & Strategie](../00_General/00_vision_and_strategy.md)
+- **Graph-Logik:** Siehe [Graph-Logik](02_concept_graph_logic.md)
+- **KI-Persönlichkeit:** Siehe [KI-Persönlichkeit](02_concept_ai_personality.md)
+- **Developer Guide:** Siehe [Developer Guide](../05_Development/05_developer_guide.md)
+
+---
+
+**Letzte Aktualisierung:** 2025-01-XX
+**Version:** 2.9.1
+
diff --git a/docs/03_Technical_References/03_tech_api_reference.md b/docs/03_Technical_References/03_tech_api_reference.md
new file mode 100644
index 0000000..198f542
--- /dev/null
+++ b/docs/03_Technical_References/03_tech_api_reference.md
@@ -0,0 +1,435 @@
+---
+doc_type: technical_reference
+audience: developer, integrator
+scope: api, endpoints, integration
+status: active
+version: 2.9.1
+context: "Vollständige API-Referenz für alle Mindnet-Endpunkte. Basis für Integration und Entwicklung."
+---
+
+# API Reference
+
+Diese Dokumentation beschreibt alle verfügbaren API-Endpunkte von Mindnet. Die API basiert auf FastAPI und nutzt automatische OpenAPI-Dokumentation (verfügbar unter `/docs`).
+
+## Basis-URL
+
+```
+http://localhost:8001 # Production
+http://localhost:8002 # Development
+```
+
+## Health Check
+
+### `GET /healthz`
+
+Prüft den Status der API und der Verbindung zu Qdrant.
+
+**Response:**
+```json
+{
+ "status": "ok",
+ "qdrant": "http://localhost:6333",
+ "prefix": "mindnet"
+}
+```
+
+---
+
+## Query Endpoints
+
+### `POST /query`
+
+Führt eine hybride oder semantische Suche im Wissensgraph durch.
+
+**Request Body:**
+```json
+{
+ "query": "Was ist Mindnet?",
+ "mode": "hybrid", // "hybrid" oder "semantic"
+ "top_k": 10,
+ "expand_depth": 1,
+ "explain": true
+}
+```
+
+**Response:**
+```json
+{
+ "query_id": "uuid-v4",
+ "hits": [
+ {
+ "chunk_id": "uuid",
+ "note_id": "uuid",
+ "text": "Auszug...",
+ "score": 0.85,
+ "explanation": {
+ "reasons": [...]
+ }
+ }
+ ],
+ "stats": {
+ "total_hits": 10,
+ "query_time_ms": 45
+ }
+}
+```
+
+**Hinweis:** Das Feedback-Logging erfolgt asynchron im Hintergrund (Background Tasks).
+
+---
+
+## Chat Endpoints
+
+### `POST /chat/`
+
+Hauptendpunkt für RAG-Chat und Interview-Modus. Unterstützt Streaming.
+
+**Request Body:**
+```json
+{
+ "message": "Was ist Mindnet?",
+ "history": [], // Optional: Chat-Verlauf
+ "stream": true // Optional: SSE-Streaming
+}
+```
+
+**Response (Non-Streaming):**
+```json
+{
+ "intent": "FACT",
+ "response": "Mindnet ist ein persönliches KI-Gedächtnis...",
+ "sources": [...],
+ "query_id": "uuid"
+}
+```
+
+**Response (Streaming):**
+Server-Sent Events (SSE) mit Chunks der Antwort.
+
+**Intent-Typen:**
+- `FACT`: Wissensabfrage
+- `DECISION`: Entscheidungsfrage
+- `EMPATHY`: Emotionale Anfrage
+- `INTERVIEW`: Wissen erfassen
+
+---
+
+## Graph Endpoints
+
+### `GET /graph/{note_id}`
+
+Lädt den Subgraphen um eine Note herum.
+
+**Query Parameters:**
+- `depth` (int, default: 1): Tiefe der Graph-Expansion
+- `edge_types` (List[str], optional): Filter für Kanten-Typen
+
+**Response:**
+```json
+{
+ "center_note_id": "uuid",
+ "nodes": [
+ {
+ "id": "uuid",
+ "type": "project",
+ "title": "Projekt Alpha",
+ "tags": ["ki"],
+ "in_degree": 5,
+ "out_degree": 3
+ }
+ ],
+ "edges": [
+ {
+ "id": "uuid->uuid:depends_on",
+ "kind": "depends_on",
+ "source": "uuid",
+ "target": "uuid",
+ "weight": 1.4,
+ "direction": "out"
+ }
+ ],
+ "stats": {
+ "node_count": 10,
+ "edge_count": 15
+ }
+}
+```
+
+---
+
+## Ingest Endpoints
+
+### `POST /ingest/analyze`
+
+Analysiert einen Text-Draft und liefert Link-Vorschläge (Intelligence-Feature).
+
+**Request Body:**
+```json
+{
+ "text": "Markdown-Text...",
+ "type": "concept" // Optional: Notiz-Typ
+}
+```
+
+**Response:**
+```json
+{
+ "suggestions": [
+ {
+ "text": "Mindnet",
+ "type": "exact_match",
+ "note_id": "uuid",
+ "confidence": 0.95
+ },
+ {
+ "text": "KI-Gedächtnis",
+ "type": "semantic",
+ "note_id": "uuid",
+ "confidence": 0.82
+ }
+ ]
+}
+```
+
+### `POST /ingest/save`
+
+Speichert eine Notiz und startet die Ingestion im Hintergrund (WP-14: Background Tasks).
+
+**Request Body:**
+```json
+{
+ "markdown_content": "---\nid: ...\n---\n# Titel\n...",
+ "filename": "meine-notiz.md", // Optional
+ "folder": "00_Inbox" // Optional, default: "00_Inbox"
+}
+```
+
+**Response:**
+```json
+{
+ "status": "queued",
+ "file_path": "00_Inbox/meine-notiz.md",
+ "note_id": "pending",
+ "message": "Speicherung & Hybrid-KI-Analyse (WP-20) im Hintergrund gestartet.",
+ "stats": {
+ "chunks": -1, // -1 = Async Processing
+ "edges": -1
+ }
+}
+```
+
+**Wichtig:**
+- Die Datei wird sofort auf der Festplatte gespeichert
+- Die Ingestion (Chunking, Embedding, Smart Edges) läuft asynchron im Hintergrund
+- Dies verhindert Timeouts bei großen Dateien oder langsamen LLM-Calls
+
+---
+
+## Feedback Endpoints
+
+### `POST /feedback`
+
+Nimmt explizites User-Feedback entgegen (WP-04c).
+
+**Request Body:**
+```json
+{
+ "query_id": "uuid",
+ "rating": 5, // 1-5 Sterne
+ "feedback_type": "global", // "global" oder "granular"
+ "chunk_id": "uuid" // Optional für granular feedback
+}
+```
+
+**Response:**
+```json
+{
+ "status": "recorded",
+ "query_id": "uuid"
+}
+```
+
+---
+
+## Tools Endpoints
+
+### `GET /tools/ollama`
+
+Liefert JSON-Schemas für die Integration als Tools in externe Agenten (Ollama, OpenAI, etc.).
+
+**Response:**
+```json
+{
+ "tools": [
+ {
+ "type": "function",
+ "function": {
+ "name": "mindnet_query",
+ "description": "Hybrid-Retrieval über mindnet (Semantik + Edges).",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Freitext-Query"
+ },
+ "top_k": {
+ "type": "integer",
+ "default": 10,
+ "minimum": 1,
+ "maximum": 50
+ }
+ }
+ }
+ }
+ },
+ {
+ "type": "function",
+ "function": {
+ "name": "mindnet_subgraph",
+ "description": "Gibt die Nachbarschaft (Edges) einer Note/Seed-ID zurück.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "note_id": {
+ "type": "string"
+ },
+ "depth": {
+ "type": "integer",
+ "default": 1,
+ "minimum": 0,
+ "maximum": 3
+ }
+ },
+ "required": ["note_id"]
+ }
+ }
+ }
+ ]
+}
+```
+
+**Verwendung:** Diese Schemas können direkt in Ollama-Function-Calling oder OpenAI-Tools integriert werden.
+
+---
+
+## Admin Endpoints
+
+### `GET /admin/stats`
+
+Liefert Statistiken über die Qdrant-Collections und die aktuelle Konfiguration.
+
+**Response:**
+```json
+{
+ "collections": {
+ "notes": {
+ "name": "mindnet_notes",
+ "count": 150
+ },
+ "chunks": {
+ "name": "mindnet_chunks",
+ "count": 1250
+ },
+ "edges": {
+ "name": "mindnet_edges",
+ "count": 3200
+ }
+ },
+ "config": {
+ "qdrant": "http://localhost:6333",
+ "prefix": "mindnet",
+ "vector_size": 768,
+ "distance": "Cosine",
+ "retriever": {
+ "w_sem": 0.70,
+ "w_edge": 0.25,
+ "w_cent": 0.05,
+ "top_k": 10,
+ "expand_depth": 1
+ }
+ }
+}
+```
+
+**Hinweis:** Dieser Endpunkt ist optional und kann deaktiviert sein, wenn der `admin`-Router nicht geladen wird.
+
+---
+
+## Fehlerbehandlung
+
+Alle Endpunkte verwenden standardisierte HTTP-Status-Codes:
+
+- `200 OK`: Erfolgreiche Anfrage
+- `201 Created`: Ressource erfolgreich erstellt
+- `400 Bad Request`: Ungültige Anfrage (z.B. fehlende Parameter)
+- `500 Internal Server Error`: Server-Fehler
+
+**Fehler-Response-Format:**
+```json
+{
+ "detail": "Fehlerbeschreibung"
+}
+```
+
+---
+
+## Rate Limiting & Timeouts
+
+- **Chat-Endpunkte:** Keine Retries (max_retries=0) für schnelle Fallback-Kaskade
+- **Ingest-Endpunkte:** Background Tasks verhindern Timeouts
+- **Query-Endpunkte:** Standard-Timeout konfigurierbar via `MINDNET_API_TIMEOUT`
+
+---
+
+## OpenAPI Dokumentation
+
+Die vollständige interaktive API-Dokumentation ist verfügbar unter:
+- Swagger UI: `http://localhost:8001/docs`
+- ReDoc: `http://localhost:8001/redoc`
+- OpenAPI JSON: `http://localhost:8001/openapi.json`
+
+---
+
+## Integration Beispiele
+
+### Python (requests)
+
+```python
+import requests
+
+# Query
+response = requests.post(
+ "http://localhost:8001/query",
+ json={"query": "Was ist Mindnet?", "top_k": 5}
+)
+print(response.json())
+
+# Chat
+response = requests.post(
+ "http://localhost:8001/chat/",
+ json={"message": "Erkläre mir Mindnet"}
+)
+print(response.json())
+```
+
+### cURL
+
+```bash
+# Health Check
+curl http://localhost:8001/healthz
+
+# Query
+curl -X POST http://localhost:8001/query \
+ -H "Content-Type: application/json" \
+ -d '{"query": "Was ist Mindnet?", "top_k": 5}'
+```
+
+---
+
+## Weitere Informationen
+
+- **Chat-Backend Details:** Siehe [Chat Backend Dokumentation](03_tech_chat_backend.md)
+- **Ingestion-Pipeline:** Siehe [Ingestion Pipeline](03_tech_ingestion_pipeline.md)
+- **Retrieval & Scoring:** Siehe [Retrieval & Scoring](03_tech_retrieval_scoring.md)
+
diff --git a/docs/03_Technical_References/03_tech_chat_backend.md b/docs/03_Technical_References/03_tech_chat_backend.md
index 9752929..bb20742 100644
--- a/docs/03_Technical_References/03_tech_chat_backend.md
+++ b/docs/03_Technical_References/03_tech_chat_backend.md
@@ -3,7 +3,7 @@ doc_type: technical_reference
audience: developer, architect
scope: backend, chat, llm_service, traffic_control, resilience
status: active
-version: 2.8.1
+version: 2.9.1
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik."
---
diff --git a/docs/03_Technical_References/03_tech_configuration.md b/docs/03_Technical_References/03_tech_configuration.md
index 77d4576..8553f00 100644
--- a/docs/03_Technical_References/03_tech_configuration.md
+++ b/docs/03_Technical_References/03_tech_configuration.md
@@ -20,13 +20,15 @@ Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. Seit der
| `QDRANT_URL` | `http://localhost:6333` | URL zur Vektor-DB API. |
| `QDRANT_API_KEY` | *(leer)* | Optionaler Key für Absicherung. |
| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). |
+| `MINDNET_PREFIX` | *(leer)* | **Alternative zu COLLECTION_PREFIX.** Falls gesetzt, wird dieser Wert verwendet. |
| `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). |
+| `MINDNET_DISTANCE` | `Cosine` | Metrik für Vektor-Ähnlichkeit (`Cosine`, `Euclidean`, `Dot`). |
| `MINDNET_VECTOR_NAME` | `default` | **Neu (WP-14):** Basis-Vektorname für Named Vectors Support. |
| `NOTES_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Notes-Collection (Override). |
| `CHUNKS_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Chunks-Collection (Override). |
| `EDGES_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Edges-Collection (Override). |
| `MINDNET_VOCAB_PATH` | *(Pfad)* | **Neu (WP-22):** Absoluter Pfad zur `01_edge_vocabulary.md`. Definiert den Ort des Dictionarys. |
-| `MINDNET_VAULT_ROOT` | `./vault` | Basis-Pfad für Datei-Operationen. |
+| `MINDNET_VAULT_ROOT` | `./vault_master` | **Achtung:** Standard ist `./vault_master`, nicht `./vault`! Basis-Pfad für Datei-Operationen. |
| `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. |
| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
| `MINDNET_DECISION_CONFIG` | `config/decision_engine.yaml` | Pfad zur Router & Intent Config. |
diff --git a/docs/03_Technical_References/03_tech_ingestion_pipeline.md b/docs/03_Technical_References/03_tech_ingestion_pipeline.md
index 146baa3..ce199dd 100644
--- a/docs/03_Technical_References/03_tech_ingestion_pipeline.md
+++ b/docs/03_Technical_References/03_tech_ingestion_pipeline.md
@@ -66,7 +66,24 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc
## 2. Betrieb & CLI Befehle
-### 2.1 Standard-Betrieb (Inkrementell)
+### 2.1 API-Endpunkt: `/ingest/save` (Background Tasks)
+
+Seit WP-14 nutzt der `/ingest/save` Endpunkt **Background Tasks** für non-blocking Ingestion:
+
+**Workflow:**
+1. **Request:** Frontend sendet Markdown an `/ingest/save`
+2. **Sofortige Antwort:** API antwortet mit `status: "queued"` und `note_id: "pending"`
+3. **Datei-Persistenz:** Markdown wird sofort auf Festplatte geschrieben
+4. **Background Task:** Ingestion läuft asynchron im Hintergrund
+ - Chunking
+ - Embedding-Generierung
+ - Smart Edge Allocation (WP-15)
+ - Hybrid-Cloud-Analyse (WP-20)
+5. **Vorteil:** Keine Timeouts bei großen Dateien oder langsamen LLM-Calls
+
+**Hinweis:** Die tatsächliche `note_id` steht erst nach dem Parsing fest. Das Frontend sollte den `file_path` für Tracking nutzen.
+
+### 2.2 CLI-Betrieb (Inkrementell)
Erkennt Änderungen via Multi-Hash.
```bash
diff --git a/docs/04_Operations/04_admin_operations.md b/docs/04_Operations/04_admin_operations.md
index 962b786..3797ebc 100644
--- a/docs/04_Operations/04_admin_operations.md
+++ b/docs/04_Operations/04_admin_operations.md
@@ -131,30 +131,131 @@ Administratoren sollten regelmäßig das Log für unbekannte Kanten-Typen prüfe
### 3.3 Troubleshooting Guide
+Dieser Abschnitt hilft bei häufigen Problemen und deren Lösung.
+
+#### Allgemeine Diagnose-Schritte
+
+Bevor du spezifische Fehler behebst, führe diese Checks durch:
+
+1. **Service-Status prüfen:**
+ ```bash
+ systemctl status mindnet-prod
+ systemctl status mindnet-ui-prod
+ docker ps | grep qdrant
+ ```
+
+2. **Logs analysieren:**
+ ```bash
+ journalctl -u mindnet-prod -n 50 --no-pager
+ journalctl -u mindnet-ui-prod -n 50 --no-pager
+ docker logs qdrant --tail 50
+ ```
+
+3. **API-Verfügbarkeit testen:**
+ ```bash
+ curl http://localhost:8001/health
+ curl http://localhost:8001/query -X POST -H "Content-Type: application/json" -d '{"query": "test", "top_k": 1}'
+ ```
+
+#### Häufige Fehler & Lösungen
+
**Fehler: "Registry Initialization Failure" (Neu in v2.7)**
* **Symptom:** API startet, aber Kanten werden nicht gewichtet oder Fehlermeldung im Log.
-* **Lösung:** Prüfen Sie `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein und auf eine existierende Markdown-Tabelle zeigen.
+* **Diagnose:** Prüfe die Logs auf `EdgeRegistry`-Fehler.
+* **Lösung:**
+ 1. Prüfe `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein.
+ 2. Stelle sicher, dass die Datei `01_edge_vocabulary.md` existiert und eine gültige Markdown-Tabelle enthält.
+ 3. Prüfe Dateiberechtigungen: `ls -l $MINDNET_VOCAB_PATH`
**Fehler: "ModuleNotFoundError: No module named 'st_cytoscape'"**
-* Ursache: Alte Dependencies oder falsches Paket installiert.
-* Lösung: Environment aktualisieren.
+* **Ursache:** Alte Dependencies oder falsches Paket installiert.
+* **Lösung:** Environment aktualisieren.
```bash
source .venv/bin/activate
pip uninstall streamlit-cytoscapejs
pip install st-cytoscape
+ pip install -r requirements.txt # Vollständige Synchronisation
```
**Fehler: "Vector dimension error: expected 768, got 384"**
-* Ursache: Alte DB (v2.2), neues Modell (v2.4).
-* Lösung: **Full Reset** (siehe Kap. 4.2).
+* **Ursache:** Alte DB (v2.2), neues Modell (v2.4) oder falsches Embedding-Modell.
+* **Diagnose:** Prüfe die Collection-Konfiguration in Qdrant.
+* **Lösung:** **Full Reset** (siehe Kap. 4.2) oder Collection neu erstellen:
+ ```bash
+ python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes
+ python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply --force
+ ```
**Fehler: Import sehr langsam**
-* Ursache: Smart Edges sind aktiv und analysieren jeden Chunk.
-* Lösung: `MINDNET_LLM_BACKGROUND_LIMIT` prüfen oder Feature in `types.yaml` deaktivieren.
+* **Ursache:** Smart Edges sind aktiv und analysieren jeden Chunk mit LLM-Calls.
+* **Diagnose:** Prüfe `MINDNET_LLM_BACKGROUND_LIMIT` und LLM-Provider-Status.
+* **Lösung:**
+ 1. Erhöhe `MINDNET_LLM_BACKGROUND_LIMIT` in `.env` (Standard: 2)
+ 2. Oder deaktiviere Smart Edges temporär in `types.yaml` für bestimmte Typen
+ 3. Prüfe, ob Ollama/Cloud-Provider erreichbar ist
**Fehler: UI "Read timed out"**
-* Ursache: Backend braucht für Smart Edges länger als 60s.
-* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen (oder im Systemd Service).
+* **Ursache:** Backend braucht für Smart Edges länger als das Timeout-Limit.
+* **Diagnose:** Prüfe Backend-Logs auf langsame LLM-Calls.
+* **Lösung:**
+ 1. Erhöhe `MINDNET_API_TIMEOUT=300.0` in `.env` (oder im Systemd Service)
+ 2. Prüfe `MINDNET_LLM_TIMEOUT` für einzelne LLM-Requests
+ 3. Erwäge, Smart Edges für große Imports zu deaktivieren
+
+**Fehler: "Qdrant connection refused"**
+* **Ursache:** Qdrant-Container läuft nicht oder falsche URL.
+* **Lösung:**
+ ```bash
+ docker ps | grep qdrant # Prüfe Container-Status
+ docker start qdrant # Starte Container falls gestoppt
+ docker logs qdrant # Prüfe Container-Logs
+ # Prüfe QDRANT_URL in .env
+ ```
+
+**Fehler: "Ollama model not found"**
+* **Ursache:** Modell nicht geladen oder falscher Modellname.
+* **Lösung:**
+ ```bash
+ ollama list # Zeige geladene Modelle
+ ollama pull phi3:mini # Lade fehlendes Modell
+ ollama pull nomic-embed-text
+ # Prüfe MINDNET_LLM_MODEL und MINDNET_EMBEDDING_MODEL in .env
+ ```
+
+**Fehler: "Too many open files" (Qdrant)**
+* **Ursache:** System-Limit für offene Dateien zu niedrig (besonders bei vielen Collections).
+* **Lösung:** Erhöhe `ulimits` im Docker-Compose (siehe Kap. 1.2) oder systemweit:
+ ```bash
+ # Temporär
+ ulimit -n 65535
+ # Permanently: /etc/security/limits.conf
+ ```
+
+**Fehler: "Unknown edge type" in Logs**
+* **Ursache:** Neue Kanten-Typen im Vault, die nicht in `edge_vocabulary.md` definiert sind.
+* **Diagnose:** Prüfe `data/logs/unknown_edges.jsonl`.
+* **Lösung:**
+ 1. Füge fehlende Typen als Aliase in `01_edge_vocabulary.md` hinzu
+ 2. Oder verwende kanonische Typen aus der Registry
+
+#### Performance-Optimierung
+
+**Problem: Langsame Chat-Antworten**
+* Prüfe LLM-Provider (Cloud vs. lokal)
+* Reduziere `top_k` in Query-Requests
+* Prüfe Qdrant-Performance (Anzahl Collections, Index-Größe)
+
+**Problem: Hoher Speicherverbrauch**
+* Reduziere `MINDNET_LLM_BACKGROUND_LIMIT`
+* Prüfe Qdrant-Speicherverbrauch: `docker stats qdrant`
+* Erwäge, alte Collections zu archivieren
+
+#### Weitere Hilfe
+
+Für detaillierte Informationen zu:
+- **Server-Betrieb:** Siehe [Server Operations Manual](04_server_operation_manual.md)
+- **Entwicklung:** Siehe [Developer Guide](../05_Development/05_developer_guide.md#10-troubleshooting--one-liners)
+- **Konfiguration:** Siehe [Configuration Reference](../03_Technical_References/03_tech_configuration.md)
---
diff --git a/docs/04_Operations/04_deployment_guide.md b/docs/04_Operations/04_deployment_guide.md
new file mode 100644
index 0000000..db95ca6
--- /dev/null
+++ b/docs/04_Operations/04_deployment_guide.md
@@ -0,0 +1,474 @@
+---
+doc_type: operations_manual
+audience: devops, deployment_engineer
+scope: deployment, ci_cd, rollout, versioning
+status: active
+version: 2.9.1
+context: "Vollständiger Deployment-Guide für Mindnet: CI/CD, Rollout-Strategien, Versionierung und Rollback."
+---
+
+# Deployment Guide
+
+Dieses Dokument beschreibt die Deployment-Prozesse, CI/CD-Pipelines und Rollout-Strategien für Mindnet.
+
+## 1. Deployment-Architektur
+
+Mindnet läuft in einer **Multi-Environment-Architektur**:
+
+| Environment | Ports | Zweck | User |
+| :--- | :--- | :--- | :--- |
+| **Production** | 8001 (API), 8501 (UI) | Live-System | `llmadmin` |
+| **Development** | 8002 (API), 8502 (UI) | Test & Entwicklung | `llmadmin` |
+
+**Wichtig:** Beide Environments teilen sich die gleiche Qdrant-Instanz, nutzen aber unterschiedliche Collection-Prefixes.
+
+---
+
+## 2. Deployment-Methoden
+
+### 2.1 Automatisches Deployment (CI/CD)
+
+**Tool:** Gitea Actions (`.gitea/workflows/deploy.yml`)
+
+**Trigger:** Push auf `main` Branch
+
+**Prozess:**
+1. **Checkout:** Code wird ausgecheckt
+2. **Stop API:** Graceful Stop des API-Services
+3. **Deploy:** Rsync der whitelisted Verzeichnisse
+4. **Dependencies:** Python venv & requirements aktualisieren
+5. **Restart:** API-Service neu starten
+
+**Deployierte Verzeichnisse:**
+- `app/` - Backend-Code
+- `scripts/` - Admin-Tools
+- `config/` - Konfigurationsdateien
+- `tests/` - Test-Suite
+- `requirements.txt` - Dependencies
+
+**Ausgeschlossen:**
+- `.env*` - Umgebungsvariablen (bleiben auf Server)
+- `.venv` - Virtuelle Umgebung (wird neu erstellt)
+- `vault/` - Content (bleibt auf Server)
+
+### 2.2 Manuelles Deployment
+
+**Für:** Hotfixes, manuelle Rollouts, Debugging
+
+**Prozess:**
+```bash
+# 1. Auf Server einloggen
+ssh llmadmin@llm-node
+
+# 2. In Produktions-Verzeichnis wechseln
+cd ~/mindnet
+
+# 3. Code aktualisieren
+git fetch origin
+git checkout main
+git pull origin main
+
+# 4. Dependencies aktualisieren
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# 5. Services neu starten
+sudo systemctl restart mindnet-prod
+sudo systemctl restart mindnet-ui-prod
+
+# 6. Status prüfen
+sudo systemctl status mindnet-prod
+sudo systemctl status mindnet-ui-prod
+```
+
+---
+
+## 3. Systemd Services
+
+### 3.1 Backend Service (API)
+
+**Datei:** `/etc/systemd/system/mindnet-prod.service`
+
+```ini
+[Unit]
+Description=Mindnet API Prod (8001)
+After=network.target
+
+[Service]
+User=llmadmin
+Group=llmadmin
+WorkingDirectory=/home/llmadmin/mindnet
+ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env
+Restart=always
+RestartSec=5
+Environment="MINDNET_VOCAB_PATH=/home/llmadmin/mindnet/vault/_system/dictionary/edge_vocabulary.md"
+
+[Install]
+WantedBy=multi-user.target
+```
+
+**Wichtig:**
+- `--env-file .env` lädt Umgebungsvariablen
+- `MINDNET_VOCAB_PATH` muss absolut sein (für Edge Registry)
+
+### 3.2 Frontend Service (UI)
+
+**Datei:** `/etc/systemd/system/mindnet-ui-prod.service`
+
+```ini
+[Unit]
+Description=Mindnet UI Prod (8501)
+After=mindnet-prod.service
+
+[Service]
+User=llmadmin
+Group=llmadmin
+WorkingDirectory=/home/llmadmin/mindnet
+Environment="MINDNET_API_URL=http://localhost:8001"
+Environment="MINDNET_API_TIMEOUT=300"
+Environment="STREAMLIT_SERVER_PORT=8501"
+Environment="STREAMLIT_SERVER_ADDRESS=0.0.0.0"
+Environment="STREAMLIT_SERVER_HEADLESS=true"
+ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 3.3 Service-Management
+
+**Befehle:**
+```bash
+# Status prüfen
+sudo systemctl status mindnet-prod
+sudo systemctl status mindnet-ui-prod
+
+# Starten
+sudo systemctl start mindnet-prod
+sudo systemctl start mindnet-ui-prod
+
+# Stoppen
+sudo systemctl stop mindnet-prod
+sudo systemctl stop mindnet-ui-prod
+
+# Neustart
+sudo systemctl restart mindnet-prod
+sudo systemctl restart mindnet-ui-prod
+
+# Logs anzeigen
+sudo journalctl -u mindnet-prod -f
+sudo journalctl -u mindnet-ui-prod -f
+```
+
+---
+
+## 4. Rollout-Strategien
+
+### 4.1 Blue-Green Deployment (Empfohlen)
+
+**Konzept:** Zwei identische Environments, Switch zwischen ihnen.
+
+**Aktuell:** Prod/Dev als Blue-Green Setup
+
+**Vorgehen:**
+1. Deploy auf Dev (Port 8002/8502)
+2. Tests auf Dev durchführen
+3. Wenn erfolgreich: Deploy auf Prod (Port 8001/8501)
+4. Switch erfolgt durch Service-Restart
+
+**Vorteile:**
+- Schneller Rollback (alte Version läuft noch)
+- Keine Downtime
+- Test vor Produktion
+
+### 4.2 Canary Deployment (Zukünftig)
+
+**Konzept:** Schrittweise Rollout an einen Teil der Nutzer.
+
+**Umsetzung:**
+- Load Balancer mit Traffic-Splitting
+- Monitoring der Fehlerrate
+- Automatischer Rollback bei Fehlern
+
+**Status:** Noch nicht implementiert (Single-User-Szenario)
+
+---
+
+## 5. Versionierung & Releases
+
+### 5.1 Version-Schema
+
+**Format:** `v2.9.1`
+
+- **Major (2):** Breaking Changes
+- **Minor (9):** Neue Features, Backward Compatible
+- **Patch (1):** Bugfixes, kleine Verbesserungen
+
+### 5.2 Release-Prozess
+
+**1. Feature-Entwicklung:**
+```bash
+git checkout -b feature/neue-funktion
+# ... Entwicklung ...
+git push origin feature/neue-funktion
+```
+
+**2. Testing:**
+- Unit Tests
+- Integration Tests
+- Smoke Tests auf Dev
+
+**3. Merge:**
+```bash
+# Pull Request in Gitea
+# Review & Merge nach main
+```
+
+**4. Deployment:**
+- Automatisch via CI/CD (bei Push auf main)
+- Oder manuell (siehe 2.2)
+
+**5. Tagging (Optional):**
+```bash
+git tag -a v2.9.2 -m "Release v2.9.2: Neue Funktion X"
+git push origin v2.9.2
+```
+
+---
+
+## 6. Rollback-Strategien
+
+### 6.1 Code-Rollback
+
+**Methode 1: Git Revert**
+```bash
+cd ~/mindnet
+git log --oneline -10 # Finde letzten guten Commit
+git checkout
+sudo systemctl restart mindnet-prod
+```
+
+**Methode 2: Git Reset (Vorsicht!)**
+```bash
+cd ~/mindnet
+git reset --hard
+sudo systemctl restart mindnet-prod
+```
+
+### 6.2 Datenbank-Rollback
+
+**Problem:** Code-Rollback hilft nicht bei Schema-Änderungen.
+
+**Lösung:**
+- **Qdrant-Snapshots:** Regelmäßige Backups (siehe [Server Operations Manual](04_server_operation_manual.md))
+- **Collection-Versionierung:** Separate Collections pro Version (nicht empfohlen)
+
+**Vorgehen bei Schema-Änderung:**
+1. Snapshot vor Deployment erstellen
+2. Deployment durchführen
+3. Bei Problemen: Snapshot wiederherstellen
+
+---
+
+## 7. Pre-Deployment Checkliste
+
+Vor jedem Deployment sollten folgende Punkte geprüft werden:
+
+- [ ] **Code-Qualität:**
+ - [ ] Unit Tests bestehen
+ - [ ] Integration Tests bestehen
+ - [ ] Linting bestanden
+
+- [ ] **Dependencies:**
+ - [ ] `requirements.txt` aktualisiert
+ - [ ] Neue Dependencies dokumentiert
+ - [ ] Breaking Changes in Dependencies geprüft
+
+- [ ] **Konfiguration:**
+ - [ ] `.env` Variablen dokumentiert (falls neu)
+ - [ ] Config-Dateien (`types.yaml`, etc.) kompatibel
+ - [ ] Edge Registry Pfad korrekt
+
+- [ ] **Datenbank:**
+ - [ ] Schema-Änderungen dokumentiert
+ - [ ] Migration-Skripte vorhanden (falls nötig)
+ - [ ] Backup erstellt
+
+- [ ] **Dokumentation:**
+ - [ ] Changelog aktualisiert
+ - [ ] Dokumentation synchronisiert
+ - [ ] Breaking Changes dokumentiert
+
+---
+
+## 8. Post-Deployment Validierung
+
+Nach jedem Deployment sollten folgende Checks durchgeführt werden:
+
+### 8.1 Service-Status
+
+```bash
+# Services laufen
+sudo systemctl status mindnet-prod
+sudo systemctl status mindnet-ui-prod
+
+# Health Check
+curl http://localhost:8001/healthz
+```
+
+### 8.2 Funktionalität
+
+```bash
+# API-Test
+curl -X POST http://localhost:8001/query \
+ -H "Content-Type: application/json" \
+ -d '{"query": "test", "top_k": 1}'
+
+# UI-Test (Manuell)
+# Öffne http://localhost:8501 im Browser
+```
+
+### 8.3 Logs prüfen
+
+```bash
+# Fehler in Logs
+sudo journalctl -u mindnet-prod --since "5 minutes ago" | grep -i error
+
+# Warnings
+sudo journalctl -u mindnet-prod --since "5 minutes ago" | grep -i warning
+```
+
+---
+
+## 9. CI/CD Pipeline Details
+
+### 9.1 Gitea Actions Workflow
+
+**Datei:** `.gitea/workflows/deploy.yml`
+
+**Trigger:**
+- Push auf `main` Branch
+- Concurrency: Nur ein Deployment gleichzeitig
+
+**Schritte:**
+1. **Checkout:** Code aus Repository
+2. **Stop API:** Graceful Stop (continue-on-error)
+3. **Deploy:** Rsync der Verzeichnisse
+4. **Python Setup:** Venv & Requirements
+5. **Start API:** Service neu starten
+
+**Wichtig:**
+- `.env` wird **nicht** deployed (bleibt auf Server)
+- Vault wird **nicht** deployed (bleibt auf Server)
+
+### 9.2 Deployment-Verzeichnisse
+
+**Whitelist:**
+```
+app scripts schemas docker tests config requirements.txt README.md
+```
+
+**Excluded:**
+- `.git/`
+- `.env*`
+- `.venv/`
+- `vault/`
+- `hf_cache/`
+
+---
+
+## 10. Monitoring & Alerting
+
+### 10.1 Health Checks
+
+**API Health Endpoint:**
+```bash
+curl http://localhost:8001/healthz
+```
+
+**Response:**
+```json
+{
+ "status": "ok",
+ "qdrant": "http://localhost:6333",
+ "prefix": "mindnet"
+}
+```
+
+**Monitoring-Script:**
+```bash
+python3 -m scripts.health_check_mindnet --url http://localhost:8001 --strict
+```
+
+### 10.2 Log-Monitoring
+
+**Systemd Journal:**
+```bash
+# Live-Logs
+sudo journalctl -u mindnet-prod -f
+
+# Letzte 100 Zeilen
+sudo journalctl -u mindnet-prod -n 100
+
+# Seit gestern
+sudo journalctl -u mindnet-prod --since "yesterday"
+```
+
+### 10.3 Metriken (Zukünftig)
+
+**Geplante Metriken:**
+- Request-Rate
+- Response-Zeiten
+- Fehler-Rate
+- LLM-Call-Dauer
+- Qdrant-Performance
+
+**Tools:** Prometheus + Grafana (noch nicht implementiert)
+
+---
+
+## 11. Disaster Recovery
+
+Siehe [Server Operations Manual](04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr) für detaillierte Disaster-Recovery-Prozeduren.
+
+**Kurzfassung:**
+1. **Stage 1:** Basis-Image Restore (Bare Metal)
+2. **Stage 2:** Daten-Update via Borgmatic
+3. **Dienste:** Gitea, Qdrant, Ollama spezifisch wiederherstellen
+
+---
+
+## 12. Best Practices
+
+### 12.1 Deployment-Zeiten
+
+- **Produktion:** Während Wartungsfenstern (nachts, Wochenenden)
+- **Development:** Jederzeit (ist Test-Umgebung)
+
+### 12.2 Kommunikation
+
+- **Breaking Changes:** Vorher ankündigen
+- **Downtime:** Bei größeren Deployments kommunizieren
+- **Rollback-Plan:** Immer bereit haben
+
+### 12.3 Testing
+
+- **Immer zuerst auf Dev testen**
+- **Smoke Tests nach Deployment**
+- **Monitoring für erste Stunden nach Deployment**
+
+---
+
+## 13. Weitere Informationen
+
+- **Admin Operations:** Siehe [Admin Operations Guide](04_admin_operations.md)
+- **Server Operations:** Siehe [Server Operations Manual](04_server_operation_manual.md)
+- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](04_admin_operations.md#33-troubleshooting-guide)
+
+---
+
+**Letzte Aktualisierung:** 2025-01-XX
+**Version:** 2.9.1
+
diff --git a/docs/05_Development/05_developer_guide.md b/docs/05_Development/05_developer_guide.md
index 831f285..427d163 100644
--- a/docs/05_Development/05_developer_guide.md
+++ b/docs/05_Development/05_developer_guide.md
@@ -216,6 +216,22 @@ Das Frontend ist eine Streamlit-App, die sich wie eine Single-Page-Application (
Das Backend ist das Herzstück. Es stellt die Logik via REST-API bereit.
+**Wichtig:** Seit WP-14 ist die Core-Logik in spezialisierte Pakete unterteilt:
+
+#### Core-Pakete (Modularisierung WP-14)
+
+| Paket | Zweck | Wichtige Module |
+| :--- | :--- | :--- |
+| **`app/core/chunking/`** | Text-Segmentierung | `chunking_strategies.py` (Sliding/Heading), `chunking_processor.py` (Orchestrierung) |
+| **`app/core/database/`** | Qdrant-Infrastruktur | `qdrant.py` (Client), `qdrant_points.py` (Point-Mapping) |
+| **`app/core/graph/`** | Graph-Logik | `graph_subgraph.py` (Expansion), `graph_weights.py` (Scoring) |
+| **`app/core/ingestion/`** | Import-Pipeline | `ingestion_processor.py` (Two-Pass), `ingestion_validation.py` (Mistral-safe Parsing) |
+| **`app/core/parser/`** | Markdown-Parsing | `parsing_markdown.py` (Frontmatter/Body), `parsing_scanner.py` (File-Scan) |
+| **`app/core/retrieval/`** | Suche & Scoring | `retriever.py` (Orchestrator), `retriever_scoring.py` (Mathematik) |
+| **`app/core/registry.py`** | SSOT & Utilities | Text-Bereinigung, Circular-Import-Fix |
+
+**Legacy-Bridges:** Die alten Dateien (`app/core/retriever.py`, `app/core/qdrant.py`) existieren noch als Proxy-Adapter für Abwärtskompatibilität, delegieren aber an die neuen Pakete.
+
| Layer | Datei | Status | Verantwortung |
| :--- | :--- | :--- | :--- |
| **Entry** | `app/main.py` | 🟢 **Core** | **Entrypoint.** Initialisiert FastAPI, CORS, und bindet alle Router ein. |
diff --git a/docs/05_Development/05_testing_guide.md b/docs/05_Development/05_testing_guide.md
new file mode 100644
index 0000000..3310877
--- /dev/null
+++ b/docs/05_Development/05_testing_guide.md
@@ -0,0 +1,392 @@
+---
+doc_type: developer_guide
+audience: developer, tester
+scope: testing, quality_assurance, test_strategies
+status: active
+version: 2.9.1
+context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices."
+---
+
+# Testing Guide
+
+Dieses Dokument beschreibt die Test-Strategien, Test-Frameworks und Best Practices für die Qualitätssicherung von Mindnet.
+
+## 1. Test-Strategie & Ebenen
+
+Mindnet nutzt eine **dreistufige Test-Pyramide**:
+
+```
+ /\
+ /E2E\ ← Wenige, langsame, teure Tests
+ /------\
+ /Integration\ ← Mittlere Anzahl, mittlere Geschwindigkeit
+ /------------\
+ / Unit Tests \ ← Viele, schnelle, isolierte Tests
+ /----------------\
+```
+
+### 1.1 Unit Tests (Pytest)
+
+**Zweck:** Isolierte Logik-Tests ohne externe Abhängigkeiten.
+
+**Framework:** `pytest`
+
+**Beispiele:**
+- `tests/test_retriever_basic.py` - Scoring-Logik
+- `tests/test_chunking.py` - Chunking-Strategien
+- `tests/test_edges_all.py` - Edge-Logik
+- `tests/test_type_registry.py` - Registry-Funktionen
+
+**Ausführung:**
+```bash
+# Einzelner Test
+pytest tests/test_retriever_basic.py -v
+
+# Alle Unit Tests
+pytest tests/ -k "test_" --ignore=tests/test_*_smoke.py
+
+# Mit Coverage
+pytest tests/ --cov=app --cov-report=html
+```
+
+**Best Practices:**
+- Tests sollten isoliert sein (keine Abhängigkeiten zu Qdrant/Ollama)
+- Mock externe Services (LLM, Qdrant)
+- Schnelle Ausführung (< 1 Sekunde pro Test)
+
+### 1.2 Integration Tests
+
+**Zweck:** Prüfen den Datenfluss von Markdown bis Qdrant.
+
+**Tools:**
+- `scripts/payload_dryrun.py` - JSON-Schema-Konformität
+- `scripts/edges_full_check.py` - Graph-Integrität
+- `scripts/make_test_vault.py` - Test-Daten-Generierung
+
+**Ausführung:**
+```bash
+# Payload-Validierung
+python3 -m scripts.payload_dryrun --vault ./test_vault --with-edges
+
+# Graph-Integrität
+python3 -m scripts.edges_full_check
+
+# Test-Vault erstellen
+python3 -m scripts.make_test_vault --out ./test_vault --force
+```
+
+**Was wird geprüft:**
+- Frontmatter-Parsing
+- Chunk-Generierung
+- Edge-Erstellung
+- Payload-Schema-Konformität
+- Graph-Invarianten (keine Dangling Edges)
+
+### 1.3 E2E / Smoke Tests
+
+**Zweck:** Prüfen das laufende System gegen echte Infrastruktur (Qdrant, Ollama).
+
+**Framework:** Python `unittest` + Shell-Skripte
+
+**Beispiele:**
+- `tests/test_wp06_decision.py` - Decision Engine
+- `tests/test_feedback_smoke.py` - Feedback-Loop
+- `tests/test_dialog_full_flow.py` - Vollständiger Dialog-Flow
+- `tests/run_e2e_roundtrip.sh` - Kompletter Roundtrip (Import → Export)
+
+**Ausführung:**
+```bash
+# Decision Engine Test
+python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?"
+
+# Feedback Test
+python tests/test_feedback_smoke.py --url http://localhost:8002/query
+
+# E2E Roundtrip
+./tests/run_e2e_roundtrip.sh --vault ./test_vault --prefix mindnet_test
+```
+
+**Voraussetzungen:**
+- Qdrant läuft auf `localhost:6333`
+- Ollama läuft auf `localhost:11434`
+- API läuft auf Port 8002 (Dev)
+
+---
+
+## 2. Test-Daten & Vaults
+
+### 2.1 Test-Vault erstellen
+
+**Tool:** `scripts/make_test_vault.py`
+
+**Zweck:** Erstellt einen minimalen, nachvollziehbaren Test-Vault.
+
+**Inhalt:**
+- Verschiedene Note-Typen (`concept`, `experience`, `project`)
+- Verschiedene Edge-Szenarien (explicit, implicit, missing links)
+- Externe Links für Edge-Tests
+
+**Verwendung:**
+```bash
+# Standard
+python3 -m scripts.make_test_vault --out ./test_vault
+
+# Mit fehlenden Links (für Link-Auflösungs-Tests)
+python3 -m scripts.make_test_vault --out ./test_vault --with-missing
+
+# Überschreiben bestehenden Vault
+python3 -m scripts.make_test_vault --out ./test_vault --force
+```
+
+### 2.2 Test-Collection Prefix
+
+**Wichtig:** Nutze separate Prefixes für Tests, um Produktionsdaten nicht zu beeinflussen.
+
+```bash
+export COLLECTION_PREFIX="mindnet_test"
+python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet_test --apply
+```
+
+---
+
+## 3. Test-Frameworks & Tools
+
+### 3.1 Pytest (Unit Tests)
+
+**Installation:**
+```bash
+pip install pytest pytest-asyncio pytest-cov
+```
+
+**Konfiguration:** `pytest.ini` oder `pyproject.toml`
+
+**Async Tests:**
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_async_function():
+ result = await async_function()
+ assert result == expected
+```
+
+### 3.2 Unittest (E2E Tests)
+
+**Framework:** Python `unittest`
+
+**Beispiel:**
+```python
+import unittest
+from app.routers.ingest import save_note, SaveRequest
+
+class TestIngest(unittest.IsolatedAsyncioTestCase):
+ async def test_save_note(self):
+ req = SaveRequest(markdown_content="...", filename="test.md")
+ response = await save_note(req)
+ self.assertEqual(response.status, "queued")
+```
+
+### 3.3 Shell-Skripte (E2E Roundtrip)
+
+**Tool:** `tests/run_e2e_roundtrip.sh`
+
+**Zweck:** Vollständiger Test-Zyklus (Import → Export → Vergleich)
+
+**Schritte:**
+1. Qdrant truncate
+2. Import (Create-Fall)
+3. Import (Idempotenz-Test)
+4. Hash-Reporter
+5. Export
+6. Vergleich Vault vs. Export
+7. Sync-Deletes Test
+
+---
+
+## 4. Test-Szenarien
+
+### 4.1 Chunking-Tests
+
+**Was wird getestet:**
+- Sliding Window Strategie
+- Heading-basierte Strategie
+- Edge-Vererbung
+- Chunk-Größen-Limits
+
+**Tests:**
+- `tests/test_smart_chunking_integration.py`
+- `scripts/preview_chunks.py` (Manuelle Inspektion)
+
+### 4.2 Retrieval-Tests
+
+**Was wird getestet:**
+- Semantic Search
+- Hybrid Search (Semantik + Graph)
+- Scoring-Formel
+- Explanation Layer
+
+**Tests:**
+- `tests/test_retriever_basic.py`
+- `tests/test_retriever_edges.py`
+- `tests/test_retriever_weight.py`
+- `tests/test_explanation_smoke.py`
+
+### 4.3 Edge-Tests
+
+**Was wird getestet:**
+- Edge-Erstellung (explicit, smart, rule)
+- Edge-Validierung (Registry)
+- Edge-Vererbung
+- Unresolved References
+
+**Tests:**
+- `tests/test_edges_all.py`
+- `tests/test_edges_smoke.py`
+- `tests/test_edges_defaults_smoke.py`
+- `scripts/edges_full_check.py`
+
+### 4.4 Chat & Intent-Tests
+
+**Was wird getestet:**
+- Intent-Erkennung (FACT, DECISION, EMPATHY, INTERVIEW)
+- Decision Engine
+- Interview-Modus
+- Feedback-Loop
+
+**Tests:**
+- `tests/test_wp06_decision.py`
+- `tests/test_interview_intent.py`
+- `tests/test_chat_wp05.py`
+- `tests/test_feedback_smoke.py`
+
+### 4.5 Ingestion-Tests
+
+**Was wird getestet:**
+- Two-Pass Workflow
+- Change Detection (Hash-basiert)
+- Background Tasks
+- Smart Edge Allocation
+
+**Tests:**
+- `tests/test_dialog_full_flow.py`
+- `tests/test_WP22_intelligence.py`
+- `scripts/import_markdown.py` (mit `--dry-run`)
+
+---
+
+## 5. Continuous Integration
+
+### 5.1 Pre-Commit Checks
+
+**Empfohlene Checks:**
+```bash
+# Linting
+flake8 app/ scripts/
+
+# Type Checking (optional)
+mypy app/
+
+# Unit Tests
+pytest tests/ -k "test_" --ignore=tests/test_*_smoke.py
+```
+
+### 5.2 CI/CD Pipeline
+
+**Gitea Actions:** `.gitea/workflows/`
+
+**Typische Pipeline:**
+1. Checkout
+2. Python Setup
+3. Dependencies installieren
+4. Unit Tests
+5. Integration Tests (optional)
+6. Deployment (bei main branch)
+
+---
+
+## 6. Test-Best Practices
+
+### 6.1 Isolation
+
+- **Unit Tests:** Keine externen Abhängigkeiten (Mock alles)
+- **Integration Tests:** Echte Qdrant, aber isolierte Collections
+- **E2E Tests:** Separate Test-Umgebung (Port 8002)
+
+### 6.2 Test-Daten
+
+- Nutze `make_test_vault.py` für konsistente Test-Daten
+- Separate Collection-Prefixes für Tests
+- Cleanup nach Tests (oder isolierte Collections)
+
+### 6.3 Performance
+
+- Unit Tests sollten < 1 Sekunde dauern
+- Integration Tests können länger dauern (10-30 Sekunden)
+- E2E Tests sind langsam (1-5 Minuten)
+
+### 6.4 Wartbarkeit
+
+- Klare Test-Namen (`test__`)
+- Dokumentation in Test-Docstrings
+- Keine Hardcoded-Pfade (nutze `os.path`)
+
+---
+
+## 7. Debugging & Diagnose
+
+### 7.1 Test-Debugging
+
+**Pytest Debug-Modus:**
+```bash
+pytest tests/test_retriever_basic.py -v --pdb
+```
+
+**Einzelnen Test inspizieren:**
+```bash
+python3 -m scripts.payload_dryrun --vault ./test_vault --note-id "test-note"
+```
+
+### 7.2 Qdrant-State prüfen
+
+```bash
+# Collection-Status
+python3 -m scripts.debug_qdrant_state --prefix mindnet_test
+
+# Payload-Indexe prüfen
+python3 -m scripts.diag_payload_indexes --prefix mindnet_test
+```
+
+### 7.3 Chunk-Inspektion
+
+```bash
+# Chunks für eine Note anzeigen
+python3 -m scripts.dump_note_chunks --note-id "test-note" --prefix mindnet_test
+
+# Chunk-Text-Verifikation
+python3 -m scripts.verify_chunk_texts --prefix mindnet_test
+```
+
+---
+
+## 8. Test-Checkliste für Pull Requests
+
+Vor jedem PR sollten folgende Tests durchlaufen:
+
+- [ ] Unit Tests: `pytest tests/ -k "test_" --ignore=tests/test_*_smoke.py`
+- [ ] Payload-Validierung: `python3 -m scripts.payload_dryrun --vault ./test_vault`
+- [ ] Graph-Integrität: `python3 -m scripts.edges_full_check`
+- [ ] Smoke Test (wenn API läuft): `python tests/test_wp06_decision.py -p 8002`
+
+---
+
+## 9. Weitere Informationen
+
+- **Developer Guide:** Siehe [Developer Guide](05_developer_guide.md)
+- **Scripts-Übersicht:** Siehe [Developer Guide - Scripts](05_developer_guide.md#44-scripts--tooling-die-admin-toolbox)
+- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](../04_Operations/04_admin_operations.md#33-troubleshooting-guide)
+
+---
+
+**Letzte Aktualisierung:** 2025-01-XX
+**Version:** 2.9.1
+
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..b9d04f4
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,154 @@
+---
+doc_type: documentation_index
+audience: all
+status: active
+version: 2.9.1
+context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation"
+---
+
+# Mindnet Dokumentation
+
+Willkommen in der Dokumentation von Mindnet v2.9.1! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln.
+
+## 🚀 Schnellstart
+
+**Neu hier?** Beginne mit diesen Dokumenten:
+
+1. **[Vision & Strategie](00_General/00_vision_and_strategy.md)** - Verstehe die Ziele und Prinzipien von Mindnet
+2. **[Glossar](00_General/00_glossary.md)** - Lerne die wichtigsten Begriffe kennen
+3. **[Dokumentationskarte](00_General/00_documentation_map.md)** - Finde schnell die richtige Dokumentation
+
+**Je nach Rolle:**
+
+- **👤 Benutzer/Autor:** Starte mit [Chat Usage Guide](01_User_Manual/01_chat_usage_guide.md) und [Knowledge Design](01_User_Manual/01_knowledge_design.md)
+- **👨💻 Entwickler:** Beginne mit [Developer Guide](05_Development/05_developer_guide.md)
+- **🔧 Administrator:** Siehe [Admin Operations](04_Operations/04_admin_operations.md)
+
+## 📚 Dokumentationsstruktur
+
+Die Dokumentation ist in logische Bereiche unterteilt:
+
+### 00_General (Grundlagen)
+Grundlegende Informationen für alle Zielgruppen:
+- Vision & Strategie
+- Glossar
+- Dokumentationskarte (Navigation)
+
+### 01_User_Manual (Anwendung)
+Anleitungen für Endbenutzer und Autoren:
+- Chat-Bedienung
+- Knowledge Design (Content-Regeln)
+- Authoring Guidelines
+- Obsidian-Integration
+
+### 02_Concepts (Fachliche Logik)
+Konzeptionelle Erklärungen für Architekten:
+- Graph-Logik
+- KI-Persönlichkeit & Router
+
+### 03_Technical_Reference (Technik & Code)
+Detaillierte technische Referenzen für Entwickler:
+- Datenmodell
+- Ingestion-Pipeline
+- Retrieval & Scoring
+- Chat-Backend
+- Frontend-Architektur
+- Konfiguration
+
+### 04_Operations (Betrieb)
+Betriebsanleitungen für Administratoren:
+- Admin Operations (Installation, Backup, Troubleshooting)
+- Server Operations Manual (Systemd, Disaster Recovery)
+
+### 05_Development (Entwicklung)
+Entwickler-Ressourcen:
+- Developer Guide (Workflow, Architektur, Module)
+- GenAI Best Practices (Prompt-Library)
+
+### 06_Roadmap (Planung)
+Projektplanung und Roadmap:
+- Active Roadmap (aktuelle Workpackages)
+- Handover Prompts (Übergabe-Prompts für neue Entwickler)
+
+### 99_Archive (Archiv)
+Historische Dokumentation:
+- Legacy Workpackages (abgeschlossene WPs)
+
+## 🔍 Navigation nach Rolle
+
+### 👨💻 Entwickler
+| Frage | Dokument |
+|-------|----------|
+| Wie richte ich meine Entwicklungsumgebung ein? | [Developer Guide](05_Development/05_developer_guide.md#6-lokales-setup-development) |
+| Wie ist die Architektur aufgebaut? | [Architektur-Patterns](02_concepts/02_concept_architecture_patterns.md) |
+| Wie erweitere ich das System? | [Developer Guide - Teach-the-AI](05_Development/05_developer_guide.md#8-erweiterungs-guide-teach-the-ai) |
+| Wie teste ich meine Änderungen? | [Testing Guide](05_Development/05_testing_guide.md) |
+| Welche API-Endpunkte gibt es? | [API Reference](03_Technical_References/03_tech_api_reference.md) |
+
+### 🔧 Administratoren
+| Frage | Dokument |
+|-------|----------|
+| Wie installiere ich Mindnet? | [Admin Operations](04_Operations/04_admin_operations.md#1-installation--setup) |
+| Wie konfiguriere ich die Services? | [Admin Operations - Deployment](04_Operations/04_admin_operations.md#2-deployment-systemd-services) |
+| Wie führe ich Backups durch? | [Admin Operations - Backup](04_Operations/04_admin_operations.md#4-backup--restore) |
+| Was tun bei Problemen? | [Admin Operations - Troubleshooting](04_Operations/04_admin_operations.md#33-troubleshooting-guide) |
+| Wie betreibe ich den Server? | [Server Operations Manual](04_Operations/04_server_operation_manual.md) |
+
+### 👤 Anwender
+| Frage | Dokument |
+|-------|----------|
+| Wie starte ich mit Mindnet? | [Schnellstart](00_General/00_quickstart.md) |
+| Wie nutze ich den Chat? | [Chat Usage Guide](01_User_Manual/01_chat_usage_guide.md) |
+| Wie strukturiere ich meine Notizen? | [Knowledge Design](01_User_Manual/01_knowledge_design.md) |
+| Wie schreibe ich für den Digitalen Zwilling? | [Authoring Guidelines](01_User_Manual/01_authoring_guidelines.md) |
+| Wie integriere ich Obsidian? | [Obsidian Integration](01_User_Manual/01_obsidian_integration_guide.md) |
+
+### 🧪 Tester
+| Frage | Dokument |
+|-------|----------|
+| Welche Test-Strategien gibt es? | [Testing Guide - Strategien](05_Development/05_testing_guide.md#1-test-strategie--ebenen) |
+| Wie führe ich Tests aus? | [Testing Guide - Frameworks](05_Development/05_testing_guide.md#3-test-frameworks--tools) |
+| Wie erstelle ich Test-Daten? | [Testing Guide - Test-Daten](05_Development/05_testing_guide.md#2-test-daten--vaults) |
+| Was ist die Test-Checkliste? | [Testing Guide - Checkliste](05_Development/05_testing_guide.md#8-test-checkliste-für-pull-requests) |
+
+### 🚀 Deployment
+| Frage | Dokument |
+|-------|----------|
+| Wie deploye ich automatisch? | [Deployment Guide - CI/CD](04_Operations/04_deployment_guide.md#9-cicd-pipeline-details) |
+| Welche Rollout-Strategien gibt es? | [Deployment Guide - Rollout](04_Operations/04_deployment_guide.md#4-rollout-strategien) |
+| Wie führe ich einen Rollback durch? | [Deployment Guide - Rollback](04_Operations/04_deployment_guide.md#6-rollback-strategien) |
+| Was muss vor dem Deployment geprüft werden? | [Deployment Guide - Checkliste](04_Operations/04_deployment_guide.md#7-pre-deployment-checkliste) |
+
+## 📖 Dokumentationsprinzipien
+
+Diese Dokumentation folgt klaren Prinzipien:
+
+1. **Single Source of Truth:** Informationen werden nicht dupliziert, sondern referenziert
+2. **Konkrete Beispiele:** Technische Dokumente enthalten immer Code-Snippets
+3. **Human Readable:** Benutzerhandbücher enthalten Narrative und Szenarien
+4. **KI-Optimiert:** Jede Datei hat YAML-Frontmatter für bessere RAG-Integration
+
+## 🔄 Dokumentation aktualisieren
+
+Wenn du an einem Feature arbeitest, nutze die [Maintenance Matrix](00_General/00_documentation_map.md#3-maintenance-guide-welche-datei-muss-ich-ändern) in der Dokumentationskarte, um zu sehen, welche Dateien aktualisiert werden müssen.
+
+## ✅ Qualitätsprüfung
+
+Die Dokumentation wurde systematisch für alle Rollen geprüft:
+- **Entwickler:** Setup, Architektur, Code, Testing, Debugging ✅
+- **Administratoren:** Installation, Betrieb, Wartung, Backup, DR ✅
+- **Anwender:** Nutzung, Content-Erstellung, Workflows ✅
+- **Tester:** Test-Strategien, Frameworks, Tools ✅
+- **Deployment:** CI/CD, Rollout, Versionierung, Rollback ✅
+
+Siehe [Qualitäts-Checkliste](00_General/00_quality_checklist.md) für Details.
+
+## 💡 Feedback
+
+Falls du Verbesserungsvorschläge für die Dokumentation hast oder Fehler findest, melde diese bitte im Repository.
+
+---
+
+**Letzte Aktualisierung:** 2025-01-XX
+**Version:** 2.9.1
+