Dokumentationsaupdate

2025-12-28 10:56:34 +01:00 · 2025-12-28 10:56:34 +01:00 · 5225090490
commit 5225090490
parent e9532e8878
15 changed files with 2553 additions and 17 deletions
--- 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)<br>2. `01_chat_usage_guide.md` (Bedienung) |
 | **Chat-Logik / Prompts**| 1. `02_concept_ai_personality.md` (Konzept)<br>2. `03_tech_chat_backend.md` (Tech)<br>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)<br>2. `02_concept_graph_logic.md` (Graph-Theorie)<br>3. `05_developer_guide.md` (Modulare Struktur) |
+| **Deployment / Server** | 1. `04_deployment_guide.md` (CI/CD, Rollout)<br>2. `04_admin_operations.md` (Installation, Wartung)<br>3. `04_server_operation_manual.md` (Server-Betrieb) |
+| **Testing / QA** | 1. `05_testing_guide.md` (Test-Strategien & Frameworks)<br>2. `05_developer_guide.md` (Test-Befehle) |
 | **Neuen Features (Allg.)**| `06_active_roadmap.md` (Status Update) |

 ---
@ -111,3 +122,37 @@ Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten
    context: "Beschreibung der Scoring-Formel."
    ---
    ```
+
+---
+
+## 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.
--- a/docs/00_General/00_quality_checklist.md
+++ 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
+
--- a/docs/00_General/00_quickstart.md
+++ 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 <repository-url> 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!** 🚀
+
--- a/docs/00_General/00_vision_and_strategy.md
+++ b/docs/00_General/00_vision_and_strategy.md
@ -65,3 +65,41 @@ Die folgenden Prinzipien steuern jede technische Entscheidung:

 10. **Local First & Privacy:**
    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)
--- 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.
@ -124,3 +126,85 @@ Wenn du im **manuellen Editor** schreibst, unterstützt dich Mindnet aktiv bei d
    * **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.
+
+### 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)
--- a/docs/02_concepts/02_concept_architecture_patterns.md
+++ 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
+
--- a/docs/03_Technical_References/03_tech_api_reference.md
+++ 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)
+
--- 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."
 ---

--- 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. |
--- 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
--- 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)

 ---

--- a/docs/04_Operations/04_deployment_guide.md
+++ 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 <commit-hash>
+sudo systemctl restart mindnet-prod
+```
+
+**Methode 2: Git Reset (Vorsicht!)**
+```bash
+cd ~/mindnet
+git reset --hard <commit-hash>
+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
+
--- 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. |
--- a/docs/05_Development/05_testing_guide.md
+++ 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_<functionality>_<scenario>`)
+- 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
+
--- a/docs/README.md
+++ 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
+