neue Dokumentationstruktur - (QS geprüft)

docs/00_General/00_documentation_map.md

@@ -0,0 +1,109 @@
+# Mindnet v2.6 – Documentation Map & Governance
+**Status:** Active
+**Context:** Central Navigation & Maintenance Guide
+
+## 1. Zweck dieses Dokuments
+
+Diese Karte dient Entwicklern, dem Mindmaster und KI-Agenten als **zentraler Einstiegspunkt**. Sie beantwortet zwei Fragen:
+1.  **Navigation:** In welcher Datei finde ich Informationen zu Thema X?
+2.  **Wartung:** Ich arbeite an Feature Y – welche Dateien muss ich aktualisieren?
+
+---
+
+## 2. Verzeichnisstruktur & Inhalte
+
+Das Repository ist in **logische Domänen** unterteilt.
+
+### 📂 00_General (Grundlagen)
+*Zielgruppe: Alle*
+| Datei | Inhalt & Zweck |
+| :--- | :--- |
+| `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. |
+
+### 📂 01_User_Manual (Anwendung)
+*Zielgruppe: Mindmaster, Autoren, Power-User*
+| Datei | Inhalt & Zweck |
+| :--- | :--- |
+| `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. |
+
+### 📂 02_Concepts (Fachliche Logik)
+*Zielgruppe: Architekten, Product Owner*
+| Datei | Inhalt & Zweck |
+| :--- | :--- |
+| `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". |
+
+### 📂 03_Technical_Reference (Technik & Code)
+*Zielgruppe: Entwickler, DevOps. (Enthält JSON/YAML Beispiele)*
+| Datei | Inhalt & Zweck |
+| :--- | :--- |
+| `03_tech_data_model.md` | **Datenbank.** Exakte Qdrant-Schemas (Payloads) und Index-Anforderungen. |
+| `03_tech_ingestion_pipeline.md`| **Import.** Ablauflogik (13 Schritte), Chunker-Profile, Smart Edge Allocation. |
+| `03_tech_retrieval_scoring.md` | **Suche.** Die mathematischen Formeln für Scoring, Hybrid Search und Explanation Layer. |
+| `03_tech_chat_backend.md` | **API & LLM.** Implementation des Routers, Traffic Control (Semaphore) und Feedback-Traceability. |
+| `03_tech_configuration.md` | **Config.** Referenztabellen für `.env`, `types.yaml` und `retriever.yaml`. |
+
+### 📂 04_Operations (Betrieb)
+*Zielgruppe: Administratoren*
+| Datei | Inhalt & Zweck |
+| :--- | :--- |
+| `04_admin_operations.md` | **Runbook.** Installation, Docker-Setup, Backup/Restore, Troubleshooting Guide. |
+
+### 📂 05_Development (Code)
+*Zielgruppe: Entwickler*
+| Datei | Inhalt & Zweck |
+| :--- | :--- |
+| `05_developer_guide.md` | **Workflow.** Hardware-Setup (Win/Pi/Beelink), Git-Flow, Test-Befehle, Modul-Interna. |
+
+### 📂 06_Roadmap & 99_Archive
+*Zielgruppe: Projektleitung*
+| Datei | Inhalt & Zweck |
+| :--- | :--- |
+| `06_active_roadmap.md` | **Zukunft.** Aktive Workpackages (WP16+), Release-Planung und WP-Historie (Tabelle). |
+| `99_legacy_workpackages.md` | **Vergangenheit.** Detaillierte Archivdaten zu abgeschlossenen WPs (WP01–WP15). |
+
+---
+
+## 3. Maintenance Guide: "Welche Datei muss ich ändern?"
+
+Nutze diese Matrix, wenn du ein Workpackage bearbeitest, um die Dokumentation konsistent zu halten.
+
+| Wenn du arbeitest an... | ...aktualisiere diese Dateien: |
+| :--- | :--- |
+| **Neuen Note-Typen** | 1. `01_knowledge_design.md` (Für Autoren)<br>2. `03_tech_configuration.md` (Technische Referenz)<br>3. `05_developer_guide.md` (Erweiterungs-How-To) |
+| **Importer / Parsing** | `03_tech_ingestion_pipeline.md` |
+| **Datenbank-Schema** | `03_tech_data_model.md` (Payloads anpassen) |
+| **Retrieval / Scoring** | `03_tech_retrieval_scoring.md` (Formeln anpassen) |
+| **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` |
+| **Neuen Features (Allg.)**| `06_active_roadmap.md` (Status Update) |
+
+---
+
+## 4. Prinzipien für die Dokumentation (Governance)
+
+Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten folgende Regeln:
+
+1.  **Single Source of Truth:**
+    Kopiere keine Informationen. Referenziere sie.
+    * *Ausnahme:* Konkrete JSON-Beispiele in `03_Technical_Reference`. Diese müssen dort stehen, damit Entwickler nicht suchen müssen.
+
+2.  **Konkrete Beispiele:**
+    Technische Dokumente (`03_*`) müssen **immer** Code-Snippets (JSON, YAML, Shell) enthalten. Abstrakte Beschreibungen reichen nicht für die Implementierung.
+
+3.  **Human Readable:**
+    User Manuals (`01_*`) müssen Narrative und Szenarien enthalten ("Stell dir vor..."), keine technischen Auflistungen.
+
+4.  **KI-Optimiert (Context Header):**
+    Jede Datei muss mit einem YAML-Frontmatter beginnen, der `context`, `audience` und `scope` definiert. Dies hilft RAG-Systemen, den Inhalt korrekt einzuordnen.
+
+    ```yaml
+    ---
+    doc_type: technical_reference
+    audience: developer
+    context: "Beschreibung der Scoring-Formel."
+    ---
+    ```

docs/00_General/00_glossary.md

@@ -0,0 +1,42 @@
+---
+doc_type: glossary
+audience: all
+status: active
+version: 2.6
+context: "Definitionen zentraler Begriffe und Entitäten im Mindnet-System."
+---
+
+# Mindnet Glossar
+
+**Quellen:** `appendix.md`, `Overview.md`
+
+## Kern-Entitäten
+
+* **Note:** Repräsentiert eine Markdown-Datei. Die fachliche Haupteinheit.
+* **Chunk:** Ein Textabschnitt einer Note (meist 512 Tokens). Die technische Sucheinheit (Vektor).
+* **Edge:** Eine gerichtete Verbindung zwischen zwei Knoten (Chunks oder Notes).
+* **Vault:** Der lokale Ordner mit den Markdown-Dateien (Source of Truth).
+* **Frontmatter:** Der YAML-Header am Anfang einer Notiz (enthält `id`, `type`, `title`).
+
+## Komponenten
+
+* **Importer:** Das Python-Skript (`ingestion.py`), das Markdown liest und in Qdrant schreibt.
+* **Retriever:** Die Komponente, die sucht. Nutzt hybrides Scoring (Semantik + Graph).
+* **Decision Engine:** Teil des Routers, der entscheidet, wie auf eine Anfrage reagiert wird (z.B. Strategie wählen).
+* **Hybrid Router v5:** Die Logik, die erkennt, ob der User eine Frage stellt (`RAG`) oder einen Befehl gibt (`INTERVIEW`).
+* **Draft Editor:** Die Web-UI-Komponente, in der generierte Notizen bearbeitet werden.
+* **Traffic Control:** Ein Mechanismus im `LLMService`, der Chat-Anfragen priorisiert und Hintergrund-Jobs (wie Import) drosselt.
+
+## Konzepte & Features
+
+* **Active Intelligence:** Feature im Web-Editor, das während des Schreibens automatisch Links vorschlägt.
+* **Smart Edge Allocation (WP15):** Ein KI-Verfahren, das prüft, ob ein Link in einer Notiz für einen spezifischen Textabschnitt relevant ist.
+* **Healing Parser:** UI-Funktion, die fehlerhaften Output des LLMs (z.B. defektes YAML) automatisch repariert.
+* **Explanation Layer:** Die Schicht, die dem Nutzer erklärt, *warum* ein Suchergebnis gefunden wurde (z.B. "Weil Projekt X davon abhängt").
+* **Provenance:** Die Herkunft einer Kante.
+    * `explicit`: Vom Mensch geschrieben.
+    * `smart`: Vom LLM validiert.
+    * `rule`: Durch Config-Regel erzeugt.
+* **Matrix Logic:** Regelwerk, das den Typ einer Kante basierend auf Quell- und Ziel-Typ bestimmt (z.B. Erfahrung -> Wert = `based_on`).
+* **Idempotenz:** Die Eigenschaft des Importers, bei mehrfacher Ausführung dasselbe Ergebnis zu liefern ohne Duplikate.
+* **Resurrection Pattern:** UI-Technik, um User-Eingaben beim Tab-Wechsel zu erhalten.

docs/00_General/00_vision_and_strategy.md

@@ -0,0 +1,67 @@
+---
+doc_type: strategy
+audience: all
+status: active
+version: 2.6
+context: "Vision, Mission und Architekturprinzipien von Mindnet."
+---
+
+# Mindnet Vision & Strategie
+
+**Quellen:** `Programmplan_V2.2.md`
+
+## 1. Programmauftrag
+
+Mindnet v2.6 entwickelt ein persönliches, wachsendes KI-Gedächtnis. Es ist ein **Digitaler Zwilling**, der:
+- Wissen, Erfahrungen und Werte speichert.
+- Semantisch verknüpft (Graphen-basiert).
+- Als Dialogpartner agiert (RAG-Chat).
+- **Lokal und privat** läuft (Privacy First).
+
+Es ist **kein statisches Archiv**, sondern ein lebendes System, das durch Interaktion (Feedback, Smart Edges) besser wird.
+
+## 2. Vision
+
+> „Ein persönliches semantisches Gedächtnis, das mit mir wächst, meine Persönlichkeit spiegelt und mir als intelligenter, erklärbarer, lernender Begleiter dient.“
+
+**Kernprinzipien der Vision:**
+* **Erklärbarkeit:** Jede Antwort muss begründbar sein ("Why-Layer").
+* **Wachstum:** Das System startet klein und verdichtet sich.
+* **Autonomie:** Es schlägt fehlende Kanten selbstständig vor (Smart Edges).
+* **Persönlichkeit:** Es entscheidet basierend auf *deinen* Werten.
+
+---
+
+## 3. Architekturprinzipien
+
+Die folgenden Prinzipien steuern jede technische Entscheidung:
+
+1.  **Late Binding (Späte Semantik):**
+    Struktur und Interpretation werden in Konfigurationen (`types.yaml`, `prompts.yaml`) definiert, nicht direkt in den Vault-Dateien. Die "Persönlichkeit" ist Config, kein Code.
+
+2.  **Virtual Schema Layer:**
+    Markdown-Dateien benötigen nur minimale, robuste Angaben (Frontmatter). Komplexität (Chunk-Größe, Gewichte) wird zur Laufzeit injiziert.
+
+3.  **Self-Healing Graph:**
+    Der Graph wird regelmäßig auf Konsistenz geprüft. "Dangling Edges" werden bereinigt, fehlende Links durch Smart Edges ergänzt.
+
+4.  **Deterministische IDs:**
+    Notes und Chunks erhalten stabile IDs (UUIDv5). Der Graph ist jederzeit aus dem Markdown wiederaufbaubar.
+
+5.  **Full Explainability:**
+    Keine Blackbox. Jede Antwort liefert Metadaten (`[DECISION]`, `[PROJECT]`) und Begründungen.
+
+6.  **Persistence First:**
+    Obsidian (Markdown) bleibt die **einzige Quelle der Wahrheit**. Die Datenbank ist nur ein abgeleiteter Cache.
+
+7.  **Minimalinvasives Schreiben:**
+    Mindnet schreibt nie ungefragt in deine Notizen. Änderungen erfolgen nur über den Draft Editor oder mit expliziter Zustimmung.
+
+8.  **Incremental Growth:**
+    Das System muss bereits mit wenigen Notizen nützlich sein.
+
+9.  **Observability:**
+    Jeder Importlauf und jede Retriever-Anfrage ist logbar.
+
+10. **Local First & Privacy:**
+    Nutzung lokaler LLMs (Ollama) für Inference. Keine Daten verlassen den Server.

docs/01_User_Manual/01_chat_usage_guide.md

@@ -0,0 +1,111 @@
+---
+doc_type: user_manual
+audience: user, mindmaster
+scope: chat, ui, feedback
+status: active
+version: 2.6
+context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des Feedbacks."
+---
+
+# Chat Usage Guide
+
+**Quellen:** `user_guide.md`
+
+## 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.
+
+**Das Gedächtnis (Der Graph):**
+Wenn du nach "Projekt Alpha" suchst, findet Mindnet auch:
+* **Abhängigkeiten:** "Technologie X wird benötigt".
+* **Entscheidungen:** "Warum nutzen wir X?".
+* **Ähnliches:** "Projekt Beta war ähnlich".
+
+**Der Zwilling (Die Personas):**
+Mindnet passt seinen Charakter an: Mal ist es der neutrale Bibliothekar, mal der strategische Berater, mal der empathische Spiegel.
+
+---
+
+## 2. Die Oberfläche (Web UI)
+
+Seit Version 2.3.1 bedienst du Mindnet über eine grafische Oberfläche im Browser.
+
+### 2.1 Der Chat-Bereich
+* **Intent-Badge:** Über jeder Antwort siehst du ein Label (z.B. **⚖️ Intent: DECISION**).
+* **Quellen-Karten:** Unter der Antwort findest du ausklappbare Karten ("Expanders").
+    * **Grüner Punkt:** Hohe Relevanz (Score > 0.8).
+    * **Klick darauf:** Zeigt den Textauszug und die **Begründung** (Explanation Layer).
+
+### 2.2 Die Sidebar
+* **Modus-Wahl:** Umschalten zwischen "💬 Chat" und "📝 Manueller Editor".
+    * *Feature:* Der Editor nutzt ein "Resurrection Pattern" – deine Eingaben bleiben erhalten, auch wenn du den Tab wechselst.
+* **Settings:** Hier kannst du `Top-K` (Anzahl der Quellen) und `Explanation Layer` steuern.
+
+---
+
+## 3. Den Chat steuern (Intents)
+
+Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Der **Hybrid Router v5** unterscheidet intelligent:
+
+### 3.1 Frage-Modus (Wissen abrufen)
+Ausgelöst durch `?` oder W-Wörter.
+
+* **Entscheidung ("Soll ich?"):** Der **Berater**.
+    * Mindnet lädt deine Werte (`type: value`) und Ziele (`type: goal`).
+    * *Beispiel:* "Soll ich Tool X nutzen?" -> "Nein, Tool X speichert Daten in den USA. Das verstößt gegen dein Prinzip 'Privacy First'."
+* **Empathie ("Ich fühle..."):** Der **Spiegel**.
+    * Mindnet lädt deine Erfahrungen (`type: experience`).
+    * *Beispiel:* "Ich bin frustriert." -> "Das erinnert mich an Projekt Y, da ging es uns ähnlich..."
+* **Fakten ("Was ist?"):** Der **Bibliothekar**.
+    * Liefert präzise Definitionen.
+
+### 3.2 Befehls-Modus (Interview)
+Ausgelöst durch Aussagen wie "Neues Projekt", "Ich will festhalten".
+
+* **Was passiert:** Mindnet sucht nicht, sondern öffnet den **Draft-Editor**.
+* **Beispiel:** "Neue Erfahrung: Streit am Recyclinghof." -> Das System erstellt sofort eine strukturierte Notiz mit den Feldern "Situation", "Reaktion" und "Learning".
+
+---
+
+## 4. Ergebnisse interpretieren (Explanation Layer)
+
+Mindnet liefert eine **Begründung** ("Reasons"), warum es etwas gefunden hat.
+Öffne eine Quellen-Karte, um zu sehen:
+* *"Hohe textuelle Übereinstimmung."* (Semantik)
+* *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit)
+* *"Verweist auf 'Projekt X' via 'depends_on'."* (Graph-Kontext)
+
+---
+
+## 5. Feedback & Lernen
+
+Mindnet wird schlauer, wenn du es pflegst.
+
+* **Globales Feedback (Sterne):** Bewertet die generierte Antwort (Prompting, Tonfall).
+* **Granulares Feedback (Smileys):** Bewertet die einzelne Quelle.
+    * 😞 (Sad): Irrelevant. (Senkt das Gewicht dieser Verbindung).
+    * 😀 (Grin): Perfekter Treffer! (Stärkt diesen Typ/Kante).
+
+---
+
+## 6. Neues Wissen beisteuern (Authoring & Intelligence)
+
+Mindnet lebt von deinem Input. Du hast drei Wege, Wissen einzugeben:
+
+### 6.1 Weg A: Der Interview-Assistent (Auto-Drafting)
+1.  **Start:** Schreibe im Chat: *"Ich möchte ein neues Projekt 'Apollo' starten."*
+2.  **Generierung:** Mindnet erkennt `INTERVIEW`, wählt das Schema und erstellt einen Entwurf.
+3.  **Editor:** Die UI zeigt den Entwurf (`status: draft`).
+    * *Healing UI:* Falls das LLM Syntax-Fehler gemacht hat, hat der Editor sie bereits repariert.
+4.  **Speichern:** Klicke auf "💾 Speichern".
+
+### 6.2 Weg B: Der Intelligence-Workflow
+Wenn du im **manuellen Editor** schreibst, unterstützt dich Mindnet aktiv bei der Vernetzung:
+
+1.  **Schreiben:** Tippe deinen Text im Tab **"✏️ Inhalt"**.
+2.  **Analysieren:** Wechsle zum Tab **"🧠 Intelligence"** und klicke auf **"🔍 Analyse starten"**. Das System scannt deinen Text (Vektor-Suche & Exact Match).
+3.  **Vorschläge nutzen:**
+    * **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.

docs/01_User_Manual/01_knowledge_design.md

@@ -0,0 +1,192 @@
+---
+doc_type: user_manual
+audience: user, author
+scope: vault, markdown, schema
+status: active
+version: 2.6
+context: "Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren."
+---
+
+# Knowledge Design Manual
+
+**Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.md`
+
+## ⚡ Die 5 Goldenen Regeln (TL;DR)
+
+Damit Mindnet als dein Digitaler Zwilling funktioniert, beachte beim Schreiben diese Grundsätze:
+
+1.  **Atomare Gedanken:** Eine Notiz = Ein Thema. Wenn du über zwei Projekte schreibst, mach zwei Notizen draus.
+2.  **Explizite Typen:** Setze immer den `type` im Frontmatter. Mindnet behandelt eine `decision` ("Wir machen X") völlig anders als ein `concept` ("Was ist X").
+3.  **Semantische Links:** Schreibe nicht nur `[[Link]]`, sondern `[[rel:depends_on Link]]`. Sag dem System *wie* Dinge zusammenhängen.
+4.  **Werte & Ziele definieren:** Damit die **Decision Engine** dich beraten kann, musst du deine Kriterien (`type: value`, `type: goal`) explizit als Notizen anlegen.
+5.  **Emotionales Bridging:** Damit die **Empathie** funktioniert, nutze in Erfahrungsberichten (`type: experience`) emotionale Schlüsselwörter ("Krise", "Freude", "Angst").
+
+---
+
+## 1. Zweck & Scope
+
+Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit abbildet. Die Markdown-Dateien in deinem Vault sind die **einzige Quelle der Wahrheit** ("Source of Truth"). Was nicht im Markdown steht, existiert für das System nicht.
+
+---
+
+## 2. Note-Struktur & Frontmatter
+
+Jede Notiz benötigt einen YAML-Header (Frontmatter).
+
+**Pflichtfelder:**
+
+```yaml
+---
+id: 20251212-projekt-alpha     # Eindeutige Kennung (YYYYMMDD-slug empfohlen)
+title: Projekt Alpha           # Sprechender Titel
+type: project                  # Steuert Chunking & Wichtigkeit
+status: active                 # active, archived, draft
+created: 2025-12-12            # ISO 8601
+tags: [ki, entwicklung]        # Taxonomie
+---
+```
+
+**Optionale Felder:**
+* `aliases`: [Alpha Projekt] – Wichtig für "Active Intelligence" (Exact Match).
+* `visibility`: internal (default) / public.
+
+> **Wichtig:** Felder wie `retriever_weight` oder `chunk_profile` werden zentral über `types.yaml` gesteuert und müssen nicht mehr manuell gesetzt werden (Virtual Schema Layer).
+
+---
+
+## 3. Typ-Referenz & Verhalten
+
+Wähle den Typ, der die **Rolle** der Notiz am besten beschreibt. Der Typ steuert Chunking, Gewichtung und Kanten-Logik.
+
+| Typ | Beschreibung & Einsatzzweck | Rolle im Chat (Intent) | Matrix-Logik |
+| :--- | :--- | :--- | :--- |
+| **`concept`** | Fachbegriffe, Theorien. Zeitloses Wissen. | **FACT** | Ziel für `uses` |
+| **`project`** | Ein Vorhaben mit Ziel, Dauer und Aufgaben. | **FACT / DECISION** | Quelle für `depends_on` |
+| **`experience`** | Persönliche Erfahrung, Lektion oder Erkenntnis. | **EMPATHY** | Quelle für `based_on` |
+| **`decision`** | Eine bewusst getroffene Entscheidung (ADR). | **DECISION** | Quelle für `caused_by` |
+| **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** | Ziel für `based_on` |
+| **`principle`** | Handlungsleitlinie. | **DECISION** | Quelle für `derived_from` |
+| **`goal`** | Ein strategisches Ziel. | **DECISION** | Ziel für `related_to` |
+| **`risk`** | Ein identifiziertes Risiko. | **DECISION** | Quelle für `blocks` |
+| **`journal`** | Zeitbezogener Log-Eintrag. | **FACT** | - |
+
+---
+
+## 4. Edges & Verlinkung
+
+Mindnet versteht Zusammenhänge durch Kanten.
+
+### 4.1 Inline-Relationen (Semantische Verknüpfung)
+Dies ist die **mächtigste** Methode. Du sagst dem System explizit, **wie** Dinge zusammenhängen.
+
+> "Daher [[rel:depends_on Qdrant]]."
+> "Dieses Konzept ist [[rel:similar_to Pinecone]]."
+
+**Gültige Relationen:**
+* `depends_on`: Hängt ab von / Benötigt.
+* `blocks`: Blockiert oder gefährdet (z.B. Risiko -> Projekt).
+* `caused_by`: Wurde verursacht durch (Kausalität).
+* `similar_to`: Ähnelt / Ist vergleichbar mit.
+* `solves`: Löst (Problem).
+* `based_on`: Basiert auf (Fundament).
+
+### 4.2 Callout-Edges
+Für Zusammenfassungen am Ende einer Notiz:
+
+```markdown
+> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]
+```
+
+---
+
+## 5. Schreiben für den KI-Zwilling (Szenarien)
+
+Damit der **RAG-Chat** dich berät, musst du "Futter" für die Decision Engine liefern.
+
+### Szenario A: Decision Engine (`DECISION`)
+* **Ziel:** Das System soll abwägen: "Passt Tool X zu mir?"
+* **Vorgehen:** Erstelle Notizen mit `type: value` oder `type: goal`.
+
+**Beispiel Notiz:**
+```yaml
+---
+type: value
+title: Prinzip: Datensparsamkeit
+---
+Wir speichern nur das Minimum an Daten. Cloud-Uploads persönlicher Daten sind verboten, es sei denn, sie sind E2E-verschlüsselt.
+```
+
+* **Effekt:** Wenn du fragst "Soll ich Notion nutzen?", lädt die Engine diese Notiz und antwortet: *"Nein, Notion ist SaaS ohne E2E. Das verletzt dein Prinzip der Datensparsamkeit."*
+
+### Szenario B: Empathie (`EMPATHY`)
+* **Ziel:** Das System soll dich verstehen.
+* **Vorgehen:** Erstelle `type: experience` mit **emotionalen Brückenwörtern**.
+
+**Beispiel Notiz:**
+```yaml
+---
+type: experience
+title: Erfahrung: Der Durchbruch nach der Krise
+tags: [krise, hoffnung, grau, angst]
+---
+Es gibt Projektphasen, da wirkt alles **sinnlos** und **grau**.
+Ich habe gelernt: Das ist oft das Zeichen kurz vor dem Durchbruch.
+```
+* **Effekt:** Bei "Alles ist grau" findet das System diese Notiz und spiegelt die Lektion zurück.
+
+---
+
+## 6. Best Practices & Beispiele (Klassik)
+
+Hier sind vollständige Vorlagen für häufige Typen.
+
+### 6.1 Beispiel: Projekt-Notiz
+Projekte profitieren von `depends_on`, um Abhängigkeiten zu klären.
+
+```markdown
+---
+id: 20251115-proj-mindnet
+title: Mindnet Implementierung
+type: project
+status: active
+---
+
+# Mindnet Implementierung
+
+Wir bauen ein persönliches Wissensnetz.
+
+## Tech Stack
+Wir nutzen [[rel:depends_on Qdrant]] für die Vektorsuche und [[rel:depends_on FastAPI]] für das Backend.
+
+## Architektur
+Das Konzept basiert auf [[RAG Architecture]]. (Automatisch 'depends_on' durch Typ-Default, falls konfiguriert).
+```
+
+### 6.2 Beispiel: Entscheidung (Decision Record)
+Entscheidungen sind hoch gewichtet (`retriever_weight: 1.0`).
+
+```markdown
+---
+id: 20251120-adr-vektordb
+title: ADR: Wahl von Qdrant
+type: decision
+status: final
+tags: [architektur, db]
+---
+
+# Entscheidung: Qdrant
+
+Wir haben uns für Qdrant entschieden.
+
+## Alternativen
+Wir haben auch [[rel:similar_to Pinecone]] und [[rel:similar_to Weaviate]] betrachtet.
+
+## Begründung
+Qdrant erlaubt lokalen Betrieb und [[rel:solves Payload Filtering Requirements]].
+```
+
+---
+
+## 7. Langfristige Stabilität
+
+Wir nutzen das Prinzip des **Virtual Schema Layers**. Wir kodieren keine Logik (wie `chunk_size`) in die Notizen. Das wird zentral in der `types.yaml` verwaltet. Das bedeutet für dich: Du kannst dich rein auf den Inhalt konzentrieren. Wenn wir die Chunking-Strategie ändern, müssen wir nicht 1000 Markdown-Dateien anfassen.

docs/02_concepts/02_concept_ai_personality.md

@@ -0,0 +1,92 @@
+---
+doc_type: concept
+audience: architect, product_owner
+scope: ai, router, personas
+status: active
+version: 2.6
+context: "Fachkonzept der KI-Persönlichkeit, der Decision Engine und Erweiterungsstrategien."
+---
+
+# Konzept: KI-Persönlichkeit & Router
+
+**Quellen:** `mindnet_functional_architecture.md`, `Programmplan_V2.2.md`
+
+Mindnet soll nicht wie eine Suchmaschine wirken, sondern wie ein **Digitaler Zwilling**. Dazu muss das System erkennen, **was** der Nutzer will, und seine "Persönlichkeit" anpassen.
+
+## 1. Der Hybrid Router (Das Gehirn)
+
+Jede Eingabe durchläuft den **Hybrid Router**. Er entscheidet über die Strategie.
+
+### Modus A: RAG (Retrieval Augmented Generation)
+* *Intent:* Der Nutzer hat eine Frage oder ein Problem (`FACT`, `DECISION`, `EMPATHY`).
+* *Aktion:* Das System sucht im Gedächtnis und generiert eine Antwort.
+
+### Modus B: Interview (Knowledge Capture)
+* *Intent:* Der Nutzer will Wissen speichern (`INTERVIEW`).
+* *Aktion:* Das System sucht **nicht**, sondern fragt ab und erstellt einen Draft.
+
+---
+
+## 2. Die Personas (Strategien)
+
+Mindnet wechselt den Hut, je nach Situation.
+
+### 2.1 Der Berater (Strategy: DECISION)
+* **Auslöser:** Fragen wie "Soll ich...?", "Was ist besser?".
+* **Strategic Retrieval:** Lädt aktiv Notizen der Typen `value` (Werte), `goal` (Ziele) und `risk` (Risiken), auch wenn sie im Text nicht direkt vorkommen.
+* **Reasoning:** *"Wäge die Fakten gegen meine Werte ab. Sei strikt bei Risiken."*
+
+### 2.2 Der Spiegel (Strategy: EMPATHY)
+* **Auslöser:** Emotionale Aussagen ("Ich bin frustriert").
+* **Strategic Retrieval:** Lädt `experience` (Erfahrungen) und `belief` (Glaubenssätze).
+* **Reasoning:** *"Nutze meine eigenen Erfahrungen, um die Situation einzuordnen."*
+
+### 2.3 Der Bibliothekar (Strategy: FACT)
+* **Auslöser:** Sachfragen ("Was ist Qdrant?").
+* **Behavior:** Präzise, neutral, kurz.
+
+---
+
+## 3. Future Concepts: The Empathic Digital Twin
+
+Um Mindnet von einer Maschine zu einem echten Spiegel der Persönlichkeit zu entwickeln, sind folgende Konzepte in der Architektur angelegt:
+
+### 3.1 Antizipation durch Erfahrung
+* **Konzept:** Das System soll Konsequenzen vorhersagen ("Was passiert, wenn...?").
+* **Logik:** *"In einer ähnlichen Situation (Projekt A) hat Entscheidung X zu Ergebnis Y geführt."* (Analogie-Schluss).
+
+### 3.2 Empathie & "Ich"-Modus
+* **Konzept:** Das System antwortet im Tonfall des Nutzers.
+* **Umsetzung:** Few-Shot Prompting mit eigenen E-Mails/Texten als Stilvorlage.
+
+### 3.3 Glaubenssätze & Rituale
+* **Konzept:** Berücksichtigung weicher Faktoren.
+* **Szenario:** Bei Terminplanungen werden Rituale ("Keine Meetings vor 10 Uhr") automatisch als harte Restriktion gegen Anfragen geprüft.
+
+---
+
+## 4. Erweiterbarkeit: Das "Teach-the-AI" Paradigma
+
+Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration** und **Vernetzung**. Wenn du dem System ein neues Konzept beibringen willst, musst du an drei Stellen eingreifen.
+
+**Beispiel: Du willst den Typ `risk` einführen.**
+
+**1. Daten-Ebene (Physik)**
+In `types.yaml`: Definiere Gewicht und Verhalten.
+```yaml
+risk:
+  retriever_weight: 0.90    # Hohe Priorität
+  edge_defaults: ["blocks"] # Automatische Kante zu Projekten
+```
+
+**2. Strategie-Ebene (Router)**
+In `decision_engine.yaml`: Wann soll das geladen werden?
+```yaml
+DECISION:
+  inject_types: ["value", "risk"] # Füge 'risk' hinzu
+```
+
+**3. Kognitive Ebene (Verständnis)**
+In `prompts.yaml`: Erkläre dem LLM, was ein Risiko ist.
+
+**Fazit:** Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.

docs/02_concepts/02_concept_graph_logic.md

@@ -0,0 +1,99 @@
+---
+doc_type: concept
+audience: architect, product_owner
+scope: graph, logic, provenance
+status: active
+version: 2.6
+context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance und Matrix-Logik."
+---
+
+# Konzept: Die Graph-Logik
+
+**Quellen:** `mindnet_functional_architecture.md`, `chunking_strategy.md`
+
+Mindnet ist keine reine Dokumentablage, sondern ein **semantischer Graph**. Dieses Dokument beschreibt, wie aus statischen Textdateien ein vernetztes Wissensobjekt wird.
+
+## 1. Die Knoten (Nodes)
+
+Der Graph besteht aus zwei Ebenen von Knoten.
+
+### 1.1 Die Note (Das Fachobjekt)
+Eine Note repräsentiert ein atomares Konzept (z.B. "Projekt Alpha").
+* **Eigenschaften:** Titel, Typ, Tags, Erstellungsdatum.
+* **Rolle:** Sie ist der Container für Metadaten und steuert via `type`, wie der Inhalt verarbeitet wird (siehe `types.yaml`).
+* **Identität:** Definiert durch eine deterministische UUIDv5.
+
+### 1.2 Der Chunk (Das Suchobjekt)
+Da LLMs (Large Language Models) nicht unendlich viel Text auf einmal lesen können, werden Notes in kleinere Segmente (**Chunks**) zerlegt.
+* **Eigenschaften:** Vektor (Embedding 768d), Textfenster, Link zum Vorgänger/Nachfolger.
+* **Rolle:** Dies sind die eigentlichen Treffer bei einer Suche.
+* **Hierarchie:** Jeder Chunk gehört streng zu einer Note (`belongs_to`).
+
+---
+
+## 2. Die Kanten (Edges)
+
+Kanten machen aus isolierten Informationen Wissen. Mindnet nutzt gerichtete Kanten mit semantischer Bedeutung.
+
+### 2.1 Semantische Typen
+
+| Kanten-Typ | Frage, die er beantwortet | Beispiel |
+| :--- | :--- | :--- |
+| `references` | Worüber wird gesprochen? | Text erwähnt "Python". |
+| `depends_on` | Was ist Voraussetzung? | Projekt braucht "Budget". |
+| `caused_by` | Warum ist das passiert? | Bug durch "Commit X". |
+| `blocks` | Was steht im Weg? | Risiko blockiert "Release". |
+| `based_on` | Worauf fußt das? | Erfahrung basiert auf "Wert Y". |
+| `derived_from` | Woher kommt das? | Prinzip stammt aus "Buch Z". |
+| `related_to` | Was ist ähnlich? | "Hund" ist verwandt mit "Wolf". |
+| `solves` | Was ist die Lösung? | "Qdrant" löst "Vektorsuche". |
+
+### 2.2 Provenance (Herkunft & Vertrauen)
+
+Nicht alle Kanten sind gleich viel wert. Mindnet unterscheidet in v2.6 drei Qualitätsstufen (**Provenance**), um Konflikte aufzulösen.
+
+**1. Explicit (Der Mensch hat es gesagt)**
+* *Quelle:* Inline-Links (`[[rel:...]]`) oder Wikilinks im Text.
+* *Vertrauen:* **Hoch (1.0)**.
+* *Bedeutung:* Dies ist hartes Faktenwissen. "Ich habe diesen Link bewusst gesetzt."
+
+**2. Smart (Die KI hat es bestätigt)**
+* *Quelle:* Smart Edge Allocation (WP15).
+* *Vertrauen:* **Mittel (0.9)**.
+* *Bedeutung:* Ein LLM hat geprüft, ob der Link im Kontext dieses Textabschnitts wirklich relevant ist. Dies filtert "Rauschen" heraus (z.B. Links im Footer, die nichts mit dem Absatz zu tun haben).
+
+**3. Rule (Die Regel hat es vermutet)**
+* *Quelle:* `types.yaml` Defaults.
+* *Vertrauen:* **Niedrig (0.7)**.
+* *Bedeutung:* Eine Heuristik. "Weil es ein Projekt ist, nehmen wir an, dass es von allen erwähnten Technologien abhängt."
+
+---
+
+## 3. Matrix-Logik (Kontext-Sensitivität)
+
+Mit WP11 wurde eine Intelligenz eingeführt, die Kanten-Typen nicht nur anhand des Quell-Typs, sondern auch anhand des Ziel-Typs bestimmt ("Matrix").
+
+**Logik-Beispiele:**
+
+* **Quelle `experience` → Ziel `value`**
+  * *Standard:* `references`
+  * *Matrix:* `based_on` (Erfahrungen basieren auf Werten).
+  
+* **Quelle `principle` → Ziel `source` (Buch)**
+  * *Standard:* `references`
+  * *Matrix:* `derived_from` (Prinzipien stammen aus Quellen).
+
+* **Quelle `project` → Ziel `tool`**
+  * *Standard:* `references`
+  * *Matrix:* `uses` (Projekte nutzen Tools).
+
+*Nutzen:* Dies erlaubt im Chat präzise Fragen wie: *"Auf welchen Werten basiert diese Entscheidung?"* (Suche nach eingehenden `based_on` Kanten).
+
+---
+
+## 4. Idempotenz & Konsistenz
+
+Das System garantiert fachliche Konsistenz auch bei mehrfachen Importen.
+* **Stabile IDs:** Importiert man dieselbe Datei zweimal, ändern sich die IDs der Knoten nicht.
+* **Keine Duplikate:** Kanten werden dedupliziert. Die "stärkere" Quelle (Explicit > Smart > Rule) gewinnt.
+* **Lösch-Garantie:** Wenn eine Notiz gelöscht wird, verschwinden auch alle ihre Chunks und ausgehenden Kanten (via `--sync-deletes`).

docs/03_Technical_References/03_tech_chat_backend.md

@@ -0,0 +1,78 @@
+---
+doc_type: technical_reference
+audience: developer, architect
+scope: backend, chat, ollama, traffic_control
+status: active
+version: 2.6
+context: "Technische Implementierung des FastAPI-Routers, der Decision Engine und des Traffic Control Systems."
+---
+
+# Chat Backend & Traffic Control
+
+## 1. Hybrid Router (Decision Engine)
+
+Der zentrale Einstiegspunkt für jede Chatanfrage ist der **Hybrid Router** (`app/routers/chat.py`). Er entscheidet dynamisch, welche Strategie gewählt wird, basierend auf dem User-Input.
+
+### 1.1 Intent-Erkennung (Logik)
+
+Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip):
+
+1.  **Question Detection (Regelbasiert):**
+    * Prüfung auf Vorhandensein von `?` oder W-Wörtern (Wer, Wie, Was, Soll ich).
+    * Wenn positiv: **RAG Modus** (Interview wird blockiert).
+2.  **Keyword Scan (Fast Path):**
+    * Lädt `types.yaml` (Objekte, z.B. "Projekt") und `decision_engine.yaml` (Handlungen, z.B. "neu").
+    * Wenn Match (z.B. "Projekt" + "neu"): **INTERVIEW Modus**.
+3.  **LLM Fallback (Slow Path):**
+    * Wenn unklar: Anfrage an LLM zur Klassifizierung.
+
+### 1.2 RAG Flow (Technisch)
+
+Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt:
+
+1.  **Pre-Processing:** Query Rewriting (optional).
+2.  **Context Enrichment:**
+    * Abruf via `retriever.py` (Hybrid Search).
+    * Injection von Metadaten (`[TYPE]`, `[SCORE]`) in den Prompt.
+3.  **Prompt Construction:** Assembly aus System-Prompt (Persona) + Context + Query.
+4.  **Streaming:** LLM-Antwort wird via **SSE (Server-Sent Events)** an den Client gestreamt.
+5.  **Post-Processing:** Anhängen des `Explanation` Layers (JSON-Breakdown) an das Ende des Streams.
+
+---
+
+## 2. Traffic Control (WP-15)
+
+Das Traffic Control System (`app/core/llm_service.py`) schützt das System vor Überlastung, wenn rechenintensive Hintergrundprozesse (Smart Edge Import) und Latenz-kritische Chat-Anfragen gleichzeitig laufen.
+
+### 2.1 Prioritäts-Semaphor
+
+Jeder LLM-Request muss ein `priority`-Flag setzen.
+
+**Prioritäten-Levels:**
+
+| Priority | Verwendung | Limitierung |
+| :--- | :--- | :--- |
+| **realtime** | Chat-Anfragen | Keine (Hardware-Limit) |
+| **background** | Smart Edge Allocation, Drafts | `MINDNET_LLM_BACKGROUND_LIMIT` |
+
+**Funktionsweise:**
+* Hintergrund-Tasks nutzen `asyncio.Semaphore`.
+* Wenn das Limit (Default: 2) erreicht ist, warten weitere Import-Tasks.
+* Chat-Tasks umgehen die Semaphore und werden sofort bearbeitet.
+
+### 2.2 Timeout-Konfiguration
+
+Deadlocks werden durch strikte Timeouts verhindert, die in der `.env` definiert sind.
+
+* **Chat:** `MINDNET_LLM_TIMEOUT` (Default: 300s).
+* **Frontend:** `MINDNET_API_TIMEOUT` (Default: 300s).
+
+---
+
+## 3. Feedback Traceability
+
+Unterstützt das geplante Self-Tuning (WP08).
+
+1.  **Query ID:** Generiert bei jedem `/query` Call eine `UUIDv4`.
+2.  **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context).
+3.  **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id`.

docs/03_Technical_References/03_tech_configuration.md

@@ -0,0 +1,132 @@
+---
+doc_type: technical_reference
+audience: developer, admin
+scope: configuration, env
+status: active
+version: 2.6
+context: "Referenztabellen für Umgebungsvariablen und YAML-Konfigurationen."
+---
+
+# Konfigurations-Referenz
+
+Dieses Dokument beschreibt die Steuerungsdateien von Mindnet.
+
+## 1. Environment Variablen (`.env`)
+
+Diese Variablen steuern die Infrastruktur, Timeouts und Feature-Flags.
+
+| Variable | Default | Beschreibung |
+| :--- | :--- | :--- |
+| `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). |
+| `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). |
+| `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. |
+| `MINDNET_PROMPTS_PATH` | `config/prompts.yaml` | Pfad zu LLM Prompts. |
+| `MINDNET_LLM_MODEL` | `phi3:mini` | Name des Chat-Modells (Ollama). |
+| `MINDNET_EMBEDDING_MODEL` | `nomic-embed-text` | Name des Embedding-Modells (Ollama). |
+| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum LLM-Server. |
+| `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden (Erhöht für CPU Cold-Starts). |
+| `MINDNET_API_TIMEOUT` | `300.0` | Frontend Timeout (Erhöht für Smart Edge Wartezeiten). |
+| `MINDNET_LLM_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Import-Tasks. |
+| `MINDNET_VAULT_ROOT` | `./vault` | Pfad für Write-Back Operationen (Drafts). |
+| `MINDNET_HASH_COMPARE` | `Body` | Import-Strategie: `Body`, `Frontmatter` oder `Full`. |
+| `MINDNET_HASH_SOURCE` | `parsed` | Hash-Quelle: `parsed`, `raw` oder `file`. |
+
+---
+
+## 2. Typ-Registry (`types.yaml`)
+
+Steuert das Import-Verhalten, Chunking und die Kanten-Logik pro Typ.
+
+**Referenztabelle (Stand v2.6):**
+
+| Typ (`type`) | Chunk Profile | Retriever Weight | Smart Edges? | Beschreibung |
+| :--- | :--- | :--- | :--- | :--- |
+| **concept** | `sliding_smart_edges` | 0.60 | Ja | Abstrakte Begriffe. |
+| **project** | `sliding_smart_edges` | 0.97 | Ja | Aktive Vorhaben. |
+| **decision** | `structured_smart_edges` | 1.00 | Ja | Entscheidungen (ADRs). |
+| **experience** | `sliding_smart_edges` | 0.90 | Ja | Persönliche Learnings. |
+| **journal** | `sliding_standard` | 0.80 | Nein | Logs / Dailies. |
+| **value** | `structured_smart_edges` | 1.00 | Ja | Werte/Prinzipien. |
+| **risk** | `sliding_short` | 0.90 | Nein | Risiken. |
+| **person** | `sliding_standard` | 0.50 | Nein | Profile. |
+| **source** | `sliding_standard` | 0.50 | Nein | Externe Quellen. |
+| **event** | `sliding_standard` | 0.60 | Nein | Meetings. |
+| **goal** | `sliding_standard` | 0.95 | Nein | Strategische Ziele. |
+| **belief** | `sliding_short` | 0.90 | Nein | Glaubenssätze. |
+| **default** | `sliding_standard` | 1.00 | Nein | Fallback. |
+
+*Hinweis: `Smart Edges?` entspricht dem YAML-Key `enable_smart_edge_allocation: true`.*
+
+---
+
+## 3. Retriever Config (`retriever.yaml`)
+
+Steuert die Gewichtung der Scoring-Formel (WP04a).
+
+**Beispielkonfiguration:**
+
+```yaml
+scoring:
+  semantic_weight:   1.0  # Basis-Relevanz (Cosine Similarity)
+  edge_weight:       0.7  # Einfluss des Graphen (Bonus)
+  centrality_weight: 0.5  # Einfluss von Hubs
+  
+edge_weights:
+  # Multiplikatoren für den Edge-Bonus
+  depends_on: 1.5         # Harte Abhängigkeiten stark gewichten
+  blocks: 1.5             # Risiken stark gewichten
+  caused_by: 1.2          # Kausalitäten stärken
+  related_to: 0.5         # Weiche Themen schwächer gewichten
+  references: 0.8         # Standard-Referenzen
+  based_on: 1.3           # Werte-Bezug
+```
+
+---
+
+## 4. Edge Typen Referenz
+
+Definiert die Semantik der `kind`-Felder in der Edge-Collection.
+
+| Kind | Symmetrisch? | Herkunft (Primär) | Bedeutung |
+| :--- | :--- | :--- | :--- |
+| `references` | Nein | Wikilink | Standard-Verweis. "Erwähnt X". |
+| `belongs_to` | Nein | Struktur | Chunk gehört zu Note. |
+| `next` / `prev` | Ja | Struktur | Lesereihenfolge. |
+| `depends_on` | Nein | Inline / Default | Harte Abhängigkeit. |
+| `related_to` | Ja | Callout / Default | Thematische Nähe. |
+| `similar_to` | Ja | Inline | Inhaltliche Ähnlichkeit. |
+| `caused_by` | Nein | Inline | Kausalität. |
+| `solves` | Nein | Inline | Lösung für ein Problem. |
+| `blocks` | Nein | Inline | Blockade / Risiko. |
+| `derived_from` | Nein | Matrix | Herkunft (z.B. Prinzip -> Buch). |
+| `based_on` | Nein | Matrix | Fundament (z.B. Erfahrung -> Wert). |
+| `uses` | Nein | Matrix | Nutzung (z.B. Projekt -> Tool). |
+
+---
+
+## 5. Decision Engine (`decision_engine.yaml`)
+
+Steuert den Hybrid Router (WP06). Definiert, welche Keywords welche Strategie auslösen.
+
+**Beispielauszug:**
+
+```yaml
+# Strategie-Definitionen
+strategies:
+  DECISION:
+    description: "Hilfe bei Entscheidungen"
+    inject_types: ["value", "principle", "goal", "risk"] # Strategic Retrieval
+    llm_fallback_enabled: true
+
+  INTERVIEW:
+    description: "Wissenserfassung"
+    trigger_keywords: ["erstellen", "neu", "anlegen", "festhalten"]
+    
+  EMPATHY:
+    description: "Emotionaler Support"
+    inject_types: ["experience", "belief"]
+```

docs/03_Technical_References/03_tech_data_model.md

@@ -0,0 +1,114 @@
+---
+doc_type: technical_reference
+audience: developer, architect
+scope: database, qdrant, schema
+status: active
+version: 2.6
+context: "Exakte Definition der Datenmodelle (Payloads) in Qdrant und Index-Anforderungen."
+---
+
+# Technisches Datenmodell (Qdrant Schema)
+
+## 1. Collections & Namenskonvention
+
+Mindnet speichert Daten in drei getrennten Qdrant-Collections. Der Prefix ist via ENV `COLLECTION_PREFIX` konfigurierbar (Default: `mindnet`).
+
+Das System nutzt folgende drei Collections:
+* `{prefix}_notes`: Metadaten der Dateien.
+* `{prefix}_chunks`: Vektorisierte Textsegmente.
+* `{prefix}_edges`: Gerichtete Graph-Kanten.
+
+---
+
+## 2. Note Payload (`mindnet_notes`)
+
+Repräsentiert die Metadaten einer Markdown-Datei (1:1 Beziehung).
+
+**JSON-Schema:**
+
+```json
+{
+  "note_id": "string (keyword)",       // UUIDv5 (deterministisch) oder Slug
+  "title": "string (text)",            // Titel aus Frontmatter
+  "type": "string (keyword)",          // Logischer Typ (z.B. 'project', 'concept')
+  "retriever_weight": "float",         // Numerische Wichtigkeit (0.0-1.0), aus types.yaml
+  "chunk_profile": "string",           // Genutztes Profil (z.B. 'sliding_smart_edges')
+  "edge_defaults": ["string"],         // Liste der aktiven Default-Kanten
+  "tags": ["string"],                  // Liste von Tags aus Frontmatter
+  "created": "string (iso-date)",      // Erstellungsdatum
+  "updated": "integer",                // Timestamp (File Modification Time)
+  "fulltext": "string (no-index)"      // Gesamter Text (nur für Recovery/Export)
+}
+```
+
+**Erforderliche Indizes:**
+Es müssen Payload-Indizes für folgende Felder existieren:
+* `note_id`
+* `type`
+* `tags`
+
+---
+
+## 3. Chunk Payload (`mindnet_chunks`)
+
+Die atomare Sucheinheit. Enthält den Vektor.
+
+**Vektor-Konfiguration:**
+* Modell: `nomic-embed-text`
+* Dimension: **768**
+* Metrik: Cosine Similarity
+
+**JSON-Schema:**
+
+```json
+{
+  "chunk_id": "string (keyword)",      // Format: {note_id}#c{index} (z.B. 'abc-123#c01')
+  "note_id": "string (keyword)",       // Foreign Key zur Note
+  "type": "string (keyword)",          // Kopie aus Note (Denormalisiert für Filterung)
+  "text": "string (text)",             // Reintext für Anzeige (ohne Overlap)
+  "window": "string (text)",           // Text + Overlap (Basis für Embedding)
+  "ord": "integer",                    // Laufende Nummer (1..N) für Sortierung
+  "retriever_weight": "float",         // Kopie aus Note (für Query-Speed)
+  "chunk_profile": "string",           // Vererbt von Note
+  "neighbors_prev": ["string"],        // ID des Vorgängers (Linked List)
+  "neighbors_next": ["string"]         // ID des Nachfolgers
+}
+```
+
+**Erforderliche Indizes:**
+Es müssen Payload-Indizes für folgende Felder existieren:
+* `note_id`
+* `chunk_id`
+* `type`
+
+---
+
+## 4. Edge Payload (`mindnet_edges`)
+
+Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Tracking.
+
+**JSON-Schema:**
+
+```json
+{
+  "edge_id": "string (keyword)",       // Deterministischer Hash aus (src, dst, kind)
+  "source_id": "string (keyword)",     // Chunk-ID (Start)
+  "target_id": "string (keyword)",     // Chunk-ID oder Note-Titel (bei Unresolved)
+  "kind": "string (keyword)",          // Beziehungsart (z.B. 'depends_on')
+  "scope": "string (keyword)",         // Immer 'chunk' (Legacy-Support: 'note')
+  "note_id": "string (keyword)",       // Owner Note ID (Ursprung der Kante)
+  
+  // Provenance & Quality (WP03/WP15)
+  "provenance": "keyword",             // 'explicit', 'rule', 'smart' (NEU)
+  "rule_id": "string (keyword)",       // Traceability: 'inline:rel', 'explicit:wikilink', 'smart:llm'
+  "confidence": "float"                // Vertrauenswürdigkeit (0.0 - 1.0)
+}
+```
+
+**Erforderliche Indizes:**
+Es müssen Payload-Indizes für folgende Felder existieren:
+* `source_id`
+* `target_id`
+* `kind`
+* `scope`
+* `note_id`

docs/03_Technical_References/03_tech_ingestion_pipeline.md

@@ -0,0 +1,122 @@
+---
+doc_type: technical_reference
+audience: developer, devops
+scope: backend, ingestion, smart_edges
+status: active
+version: 2.6
+context: "Detaillierte technische Beschreibung der Import-Pipeline, Quality Gates und CLI-Befehle."
+---
+
+# Ingestion Pipeline & Smart Processing
+
+**Quellen:** `pipeline_playbook.md`, `Handbuch.md`
+
+Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py`.
+
+## 1. Der Import-Prozess (13-Schritte-Workflow)
+
+Der Prozess ist **asynchron** und **idempotent**.
+
+1.  **Markdown lesen:** Rekursives Scannen des Vaults.
+2.  **Frontmatter extrahieren:** Validierung von Pflichtfeldern (`id`, `type`, `title`).
+3.  **Typauflösung:** Bestimmung des `type` via `types.yaml`.
+4.  **Note-Payload generieren:** Erstellen des JSON-Objekts für `mindnet_notes`.
+5.  **Chunking anwenden:** Zerlegung des Textes basierend auf dem `chunk_profile` (siehe unten).
+6.  **Smart Edge Allocation (WP15):**
+    * Wenn `enable_smart_edge_allocation: true`: Der `SemanticAnalyzer` sendet Chunks an das LLM.
+    * **Traffic Control:** Request nutzt `priority="background"`. Semaphore (Limit: 2) drosselt die Last.
+    * **Resilienz:** Bei Timeout (Ollama) greift ein Fallback (Broadcasting an alle Chunks).
+7.  **Inline-Kanten finden:** Parsing von `[[rel:...]]`.
+8.  **Callout-Kanten finden:** Parsing von `> [!edge]`.
+9.  **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus Registry.
+10. **Strukturkanten erzeugen:** `belongs_to`, `next`, `prev`.
+11. **Embedding (Async):** Generierung via `nomic-embed-text` (768d).
+12. **Strict Mode:** Abbruch bei leeren Embeddings oder Dimension 0.
+13. **Diagnose:** Integritäts-Check nach dem Lauf.
+
+---
+
+## 2. Betrieb & CLI Befehle
+
+### 2.1 Standard-Betrieb (Inkrementell)
+Für regelmäßige Updates (Cronjob). Erkennt Änderungen via Hash.
+
+```bash
+export QDRANT_URL="http://localhost:6333"
+export COLLECTION_PREFIX="mindnet"
+
+# Nutzt das Venv der Produktionsumgebung
+/home/llmadmin/mindnet/.venv/bin/python3 -m scripts.import_markdown \
+    --vault ./vault \
+    --prefix "$COLLECTION_PREFIX" \
+    --apply \
+    --purge-before-upsert \
+    --sync-deletes
+```
+
+> **[!WARNING] Purge-Before-Upsert**
+> Das Flag `--purge-before-upsert` ist kritisch. Es löscht vor dem Schreiben einer Note ihre alten Chunks/Edges. Ohne dieses Flag entstehen **"Geister-Chunks"** (alte Textabschnitte, die im Markdown gelöscht wurden, aber im Index verbleiben).
+
+### 2.2 Full Rebuild (Clean Slate)
+Notwendig bei Änderungen an `types.yaml` oder Modell-Wechsel.
+
+```bash
+# 0. Modell sicherstellen
+ollama pull nomic-embed-text
+
+# 1. Qdrant Collections löschen (Wipe)
+python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
+
+# 2. Vollständiger Import (Force)
+python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
+```
+
+---
+
+## 3. Chunking & Payload
+
+Das Chunking ist profilbasiert.
+
+| Profil | Max Token | Overlap | Einsatz |
+| :--- | :--- | :--- | :--- |
+| `sliding_short` | 128 | 20 | Logs, Chats. |
+| `sliding_standard` | 512 | 50 | Massendaten. |
+| `sliding_smart_edges`| 512 | 50 | Wichtige Inhalte (Experience, Project). |
+| `structured_smart` | n/a | n/a | Trennt strikt an Headings (für ADRs). |
+
+**Payload-Felder:**
+* `text`: Der reine Inhalt (Anzeige).
+* `window`: Inhalt plus Overlap (für Embedding).
+
+---
+
+## 4. Edge-Erzeugung & Prioritäten
+
+Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere Prio gewinnt.
+
+| Prio | Quelle | Rule ID | Confidence |
+| :--- | :--- | :--- | :--- |
+| **1** | Inline | `inline:rel` | 0.95 |
+| **2** | Callout | `callout:edge` | 0.90 |
+| **3** | Wikilink | `explicit:wikilink` | 1.00 |
+| **4** | Smart Edge | `smart:llm_filter` | 0.90 |
+| **5** | Type Default | `edge_defaults` | 0.70 |
+| **6** | Struktur | `structure` | 1.00 |
+
+---
+
+## 5. Quality Gates & Tests
+
+Diese Tests garantieren die Stabilität der Pipeline.
+
+**1. Payload Dryrun (Schema-Check):**
+Simuliert Import, prüft JSON-Schema Konformität.
+```bash
+python3 -m scripts.payload_dryrun --vault ./test_vault
+```
+
+**2. Full Edge Check (Graph-Integrität):**
+Prüft Invarianten (z.B. `next` muss reziprok zu `prev` sein).
+```bash
+python3 -m scripts.edges_full_check
+```

docs/03_Technical_References/03_tech_retrieval_scoring.md

@@ -0,0 +1,113 @@
+---
+doc_type: technical_reference
+audience: developer, data_scientist
+scope: backend, retrieval, scoring
+status: active
+version: 2.6
+context: "Formeln und Algorithmen des Hybrid Retrievers und Explanation Layer."
+---
+
+# Retrieval & Scoring Algorithmen
+
+Der Retriever (`app/core/retriever.py`) unterstützt **Semantic Search** und **Hybrid Search**. Seit v2.4 (WP04a) nutzt Mindnet ein gewichtetes Scoring-Modell, das Semantik, Graphentheorie und Metadaten kombiniert.
+
+## 1. Scoring Formel (WP04a)
+
+Der Gesamtscore eines Treffers berechnet sich als gewichtete Summe. Alle Gewichte ($W$) sind in `retriever.yaml` konfigurierbar.
+
+$$
+TotalScore = (W_{sem} \cdot S_{sem} \cdot \max(W_{type}, 0)) + (W_{edge} \cdot B_{edge}) + (W_{cent} \cdot B_{cent})
+$$
+
+### Die Komponenten
+
+**1. Semantic Score ($S_{sem}$):**
+* **Basis:** Cosine Similarity des Vektors.
+* **Modell:** `nomic-embed-text` (768d).
+* **Wertebereich:** 0.0 bis 1.0.
+
+**2. Type Weight ($W_{type}$):**
+* **Herkunft:** Feld `retriever_weight` aus der Note/Chunk Payload.
+* **Zweck:** Priorisierung bestimmter Dokumententypen unabhängig vom Inhalt.
+* **Beispiel:** Eine `decision` (Gewicht 1.0) schlägt ein `concept` (Gewicht 0.6) bei gleicher textueller Ähnlichkeit.
+
+**3. Edge Bonus ($B_{edge}$):**
+* **Kontext:** Berechnet im lokalen Subgraphen (Expansion Tiefe 1).
+* **Logik:** Summe der `confidence` aller eingehenden Kanten, die von Knoten stammen, die *ebenfalls* im aktuellen Result-Set (oder dem übergebenen Kontext) enthalten sind.
+* **Zweck:** Belohnt Chunks, die "im Thema" vernetzt sind.
+
+**4. Centrality Bonus ($B_{cent}$):**
+* **Kontext:** Berechnet im lokalen Subgraphen.
+* **Logik:** Eine vereinfachte PageRank-Metrik (Degree Centrality) im temporären Graphen.
+* **Zweck:** Belohnt "Hubs", die viele Verbindungen zu anderen Treffern haben.
+
+---
+
+## 2. Hybrid Retrieval Flow
+
+Der Hybrid-Modus ist der Standard für den Chat (`/chat`). Er läuft in drei Phasen ab:
+
+**Phase 1: Vector Search (Seed Generation)**
+* Suche die Top-K (z.B. 20) Kandidaten via Embeddings in Qdrant.
+* Dies sind die "Seeds" für den Graphen.
+
+**Phase 2: Graph Expansion**
+* Nutze `graph_adapter.expand(seeds, depth=1)`.
+* Lade alle direkten Nachbarn (Incoming & Outgoing) der Seeds aus der `_edges` Collection.
+* Konstruiere einen temporären `NetworkX`-Graphen im Speicher (`Subgraph`).
+
+**Phase 3: Re-Ranking**
+* Berechne für jeden Knoten im Subgraphen die Boni ($B_{edge}$, $B_{cent}$).
+* Wende die Scoring-Formel an.
+* Sortiere die Liste neu absteigend nach `TotalScore`.
+* Schneide die Liste beim finalen Limit (z.B. 5) ab.
+
+---
+
+## 3. Explanation Layer (WP04b)
+
+Wenn der Parameter `explain=True` an die API übergeben wird, generiert der Retriever ein `Explanation` Objekt für jeden Treffer.
+
+**JSON-Struktur der Erklärung:**
+
+```json
+{
+  "score_breakdown": {
+    "semantic": 0.85,
+    "type_boost": 1.0,
+    "edge_bonus": 0.4,
+    "centrality": 0.1
+  },
+  "reasons": [
+    "Hohe textuelle Übereinstimmung (>0.85).",
+    "Bevorzugt, da Typ 'decision' (Gewicht 1.0).",
+    "Wird referenziert von 'Projekt Alpha' via 'depends_on'."
+  ]
+}
+```
+
+**Logik der Text-Generierung:**
+* **Semantik:** Wenn $S_{sem} > 0.8$: "Hohe Übereinstimmung".
+* **Typ:** Wenn $W_{type} > 0.8$: "Bevorzugt, da Typ X".
+* **Graph:** Listet bis zu 3 eingehende Kanten mit hoher Konfidenz auf ("Wird referenziert von...").
+
+---
+
+## 4. Konfiguration (`retriever.yaml`)
+
+Diese Datei steuert die Balance der Formel.
+
+```yaml
+scoring:
+  semantic_weight:   1.0  # Basis-Relevanz (sollte immer ca. 1.0 sein)
+  edge_weight:       0.7  # Einfluss des Graphen (0.5 - 1.0 empfohlen)
+  centrality_weight: 0.5  # Einfluss der Zentralität (Hub-Bonus)
+
+# Kanten-spezifische Gewichtung für den Edge-Bonus
+edge_weights:
+  depends_on: 1.5         # Harte Abhängigkeiten sehr stark gewichten
+  blocks: 1.5             # Risiken/Blocker stark gewichten
+  caused_by: 1.2          # Kausalitäten moderat stärken
+  related_to: 0.5         # Weiche Themen schwächer gewichten
+  references: 0.8         # Standard-Referenzen
+```

docs/04_Operations/04_admin_operations.md

@@ -0,0 +1,148 @@
+---
+doc_type: operations_manual
+audience: admin, devops
+scope: deployment, maintenance, backup
+status: active
+version: 2.6
+context: "Installationsanleitung, Systemd-Units und Wartungsprozesse."
+---
+
+# Admin Operations Guide
+
+## 1. Installation & Setup
+
+### 1.1 Voraussetzungen
+* **OS:** Ubuntu 22.04+ (empfohlen).
+* **Tools:** Python 3.10+, Docker, Ollama.
+* **Hardware:** Min. 8GB RAM, 4 CPU Cores (für Async Import).
+
+### 1.2 Qdrant (Docker)
+Startet die Vektor-DB mit persistentem Storage auf Port 6333.
+
+```bash
+docker run -d \
+  --name mindnet_qdrant \
+  --restart always \
+  -p 6333:6333 \
+  -v $(pwd)/qdrant_storage:/qdrant/storage \
+  qdrant/qdrant
+```
+
+### 1.3 Ollama (Modelle)
+**Wichtig:** Seit v2.4 ist `nomic-embed-text` Pflicht für Embeddings.
+
+```bash
+# Modelle laden
+ollama pull phi3:mini
+ollama pull nomic-embed-text
+
+# Testen
+curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}'
+```
+
+---
+
+## 2. Deployment (Systemd Services)
+
+Wir unterscheiden strikt zwischen **Prod** (Port 8001/8501) und **Dev** (Port 8002/8502).
+
+### 2.1 Backend Service (`/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
+# Startet Uvicorn (Async Server)
+ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 2.2 UI Service (`/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 für Streamlit Port & API-Ziel
+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. Wartung & Cronjobs
+
+### 3.1 Regelmäßiger Import (Cron)
+Führt den Sync stündlich durch. Nutzt `--purge-before-upsert` für Sauberkeit.
+
+```bash
+# Crontab Eintrag (user: llmadmin)
+0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1
+```
+
+### 3.2 Troubleshooting Guide
+
+**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).
+
+**Fehler: "500 Internal Server Error" (Ollama)**
+* Ursache: Timeout bei Cold-Start des Modells.
+* Lösung: `MINDNET_LLM_TIMEOUT=300.0` in `.env` setzen.
+
+**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.
+
+**Fehler: UI "Read timed out"**
+* Ursache: Backend braucht für Smart Edges länger als 60s.
+* Lösung: `MINDNET_API_TIMEOUT=300.0` setzen.
+
+---
+
+## 4. Backup & Restore
+
+### 4.1 Qdrant Snapshot
+Sichert den Vektor-Index.
+
+```bash
+docker stop mindnet_qdrant
+tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage
+docker start mindnet_qdrant
+```
+
+### 4.2 Notfall-Rebuild (Clean Slate)
+Wenn alles inkonsistent ist oder Dimensionen sich ändern:
+
+```bash
+# 1. DB löschen
+python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
+
+# 2. Neu importieren (Force Hash recalculation)
+python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
+```

docs/05_Development/05_developer_guide.md

@@ -0,0 +1,231 @@
+---
+doc_type: developer_guide
+audience: developer
+scope: workflow, testing, architecture, modules
+status: active
+version: 2.6
+context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna, Setup, Git-Workflow und Erweiterungs-Anleitungen."
+---
+
+# Mindnet Developer Guide & Workflow
+
+**Quellen:** `developer_guide.md`, `dev_workflow.md`
+
+Dieser Guide vereint das technische Verständnis der Module mit dem operativen Workflow zwischen Windows (Dev) und Linux (Runtime).
+
+---
+
+## 1. Die physische Architektur
+
+Mindnet läuft in einer verteilten Umgebung (Post-WP15 Setup).
+
+* **Windows 11 (VS Code):** Hier schreibst du Code. **Nie** direkt auf `main` arbeiten!
+* **Raspberry Pi (Gitea):** Der "Safe". Speichert den Code und verwaltet Versionen.
+* **Beelink (Runtime):** Der Server. Hier läuft die Software. Wir nutzen **Systemd-Services**:
+    * **PROD:** API (8001) + UI (8501). Ordner: `~/mindnet`.
+    * **DEV:** API (8002) + UI (8502). Ordner: `~/mindnet_dev`.
+
+---
+
+## 2. Projektstruktur & Core-Module
+
+Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt.
+
+### 2.1 Verzeichnisbaum
+```text
+mindnet/
+├── app/
+│   ├── core/           # Kernlogik
+│   │   ├── ingestion.py        # Async Ingestion Service mit Change Detection
+│   │   ├── chunker.py          # Smart Chunker Orchestrator
+│   │   ├── derive_edges.py     # Edge-Erzeugung (WP03 Logik)
+│   │   ├── retriever.py        # Scoring & Hybrid Search
+│   │   └── qdrant.py           # DB-Verbindung
+│   ├── routers/        # FastAPI Endpoints
+│   │   ├── query.py    # Suche
+│   │   ├── chat.py     # Hybrid Router v5 & Interview Logic
+│   │   └── feedback.py # Feedback (WP04c)
+│   ├── services/       # Interne & Externe Dienste
+│   │   ├── llm_service.py      # Ollama Client mit Traffic Control
+│   │   ├── semantic_analyzer.py# LLM-Filter für Edges (WP15)
+│   │   ├── embeddings_client.py# Async Embeddings (HTTPX)
+│   │   └── discovery.py        # Intelligence Logic (WP11)
+│   ├── frontend/       
+│   │   └── ui.py       # Streamlit App inkl. Healing Parser
+│   └── main.py         # Entrypoint der API
+├── config/             # YAML-Konfigurationen (Single Source of Truth)
+├── scripts/            # CLI-Tools (Import, Diagnose, Reset)
+├── tests/              # Pytest Suite & Smoke Scripts
+└── vault/              # Dein lokaler Markdown-Content
+```
+
+### 2.2 Modul-Details (Wie es funktioniert)
+
+**Der Importer (`scripts.import_markdown`)**
+* Das komplexeste Modul.
+* Nutzt `app.core.chunker` und `app.services.semantic_analyzer` (Smart Edges).
+* **Idempotenz:** Nutzt deterministische UUIDv5 IDs. Kann beliebig oft laufen.
+* **Robustheit:** Implementiert Change Detection (Hash) und Retry-Logik.
+
+**Der Hybrid Router (`app.routers.chat`)**
+* Hier liegt die Logik für Intent Detection (WP06).
+* **Question Detection:** Prüft auf `?` und W-Wörter.
+* **Priority:** Ruft `llm_service` mit `priority="realtime"` auf (umgeht Import-Warteschlange).
+
+**Der Retriever (`app.core.retriever`)**
+* Implementiert die Scoring-Formel (`Semantik + Graph + Typ`).
+* **Hybrid Search:** Lädt dynamisch den Subgraphen (`graph_adapter.expand`).
+
+**Das Frontend (`app.frontend.ui`)**
+* **Resurrection Pattern:** Nutzt `st.session_state`, um Eingaben bei Tab-Wechseln zu erhalten.
+* **Healing Parser:** Die Funktion `parse_markdown_draft` repariert defekte YAML-Frontmatter vom LLM automatisch.
+
+**Traffic Control (`app.services.llm_service`)**
+* Stellt sicher, dass der Chat responsive bleibt, auch wenn ein Import läuft.
+* Nutzt `asyncio.Semaphore` (`MINDNET_LLM_BACKGROUND_LIMIT`), um Hintergrund-Jobs zu drosseln.
+
+---
+
+## 3. Lokales Setup (Development)
+
+**Voraussetzungen:** Python 3.10+, Docker, Ollama.
+
+**Installation:**
+```bash
+# 1. Repo & Venv
+git clone <repo> mindnet
+cd mindnet
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 2. Dependencies
+pip install -r requirements.txt
+
+# 3. Ollama (Nomic ist Pflicht!)
+ollama pull phi3:mini
+ollama pull nomic-embed-text
+```
+
+**Konfiguration (.env):**
+```ini
+QDRANT_URL="http://localhost:6333"
+COLLECTION_PREFIX="mindnet_dev"
+VECTOR_DIM=768
+MINDNET_LLM_BACKGROUND_LIMIT=2
+MINDNET_API_URL="http://localhost:8002"
+MINDNET_LLM_TIMEOUT=300.0
+```
+
+---
+
+## 4. Der Entwicklungs-Zyklus
+
+### Phase 1: Windows (Code)
+1.  **Basis holen:** `git checkout main && git pull`.
+2.  **Branch:** `git checkout -b feature/mein-feature`.
+3.  **Code & Push:** `git push origin feature/mein-feature`.
+
+### Phase 2: Beelink (Test)
+1.  **SSH:** `ssh user@beelink`.
+2.  **Ordner:** `cd ~/mindnet_dev`.
+3.  **Checkout:** `git fetch && git checkout feature/mein-feature && git pull`.
+4.  **Dependencies:** `pip install -r requirements.txt`.
+5.  **Restart:** `sudo systemctl restart mindnet-dev`.
+6.  **Validierung (Smoke Tests):**
+    * **Last-Test:** Starte `python3 -m scripts.import_markdown ...` und chatte gleichzeitig im UI (Port 8502).
+    * **API Check:** `curl -X POST "http://localhost:8002/ingest/analyze" ...`
+
+### Phase 3: Release & Deploy
+1.  **Gitea:** Pull Request erstellen und mergen.
+2.  **Beelink (Prod):**
+    ```bash
+    cd ~/mindnet
+    git pull origin main
+    sudo systemctl restart mindnet-prod
+    ```
+3.  **Cleanup:** Branch löschen.
+
+---
+
+## 5. Erweiterungs-Guide: "Teach-the-AI"
+
+Mindnet lernt durch Konfiguration, nicht durch Training.
+
+### Workflow A: Neuen Typ implementieren (z. B. `type: risk`)
+1.  **Physik (`types.yaml`):**
+    ```yaml
+    risk:
+      retriever_weight: 0.90
+      edge_defaults: ["blocks"]
+      detection_keywords: ["gefahr", "risiko"]
+    ```
+2.  **Strategie (`decision_engine.yaml`):**
+    ```yaml
+    DECISION:
+      inject_types: ["value", "risk"] # Füge 'risk' hinzu
+    ```
+3.  **Kognition (`prompts.yaml`):** (Optional) Passe den System-Prompt an, falls nötig.
+
+### Workflow B: Interview-Schema anpassen (WP07)
+Wenn Mindnet neue Fragen stellen soll (z.B. "Budget" bei Projekten):
+1.  **Schema (`types.yaml`):**
+    ```yaml
+    project:
+      schema:
+        - "Titel"
+        - "Ziel"
+        - "Budget (Neu)"
+    ```
+2.  **Kein Code nötig:** Der `One-Shot Extractor` liest dies dynamisch.
+
+---
+
+## 6. Tests & Debugging
+
+**Unit Tests:**
+```bash
+pytest tests/test_retriever_basic.py
+pytest tests/test_chunking.py
+```
+
+**Pipeline Tests:**
+```bash
+# JSON-Schema prüfen
+python3 -m scripts.payload_dryrun --vault ./test_vault
+
+# Graph-Integrität prüfen
+python3 -m scripts.edges_full_check
+```
+
+**E2E Smoke Tests:**
+```bash
+# Decision Engine
+python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?"
+
+# Feedback
+python tests/test_feedback_smoke.py --url http://localhost:8002/query
+```
+
+---
+
+## 7. Troubleshooting & One-Liners
+
+**DB komplett zurücksetzen (Vorsicht!):**
+```bash
+python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes
+```
+
+**Einen einzelnen File inspizieren (Parser-Sicht):**
+```bash
+python3 tests/inspect_one_note.py --file ./vault/MeinFile.md
+```
+
+**Live-Logs sehen:**
+```bash
+journalctl -u mindnet-dev -f
+journalctl -u mindnet-ui-dev -f
+```
+
+**"Read timed out" im Frontend:**
+* Ursache: Smart Edges brauchen länger als 60s.
+* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env`.

docs/06_Roadmap/06_active_roadmap.md

@@ -0,0 +1,108 @@
+---
+doc_type: roadmap
+audience: product_owner, developer
+status: active
+version: 2.6
+context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs."
+---
+
+# Mindnet Active Roadmap
+
+**Aktueller Stand:** v2.6.0 (Post-WP15)
+**Fokus:** Usability, Memory & Visualisierung.
+
+## 1. Programmstatus
+
+Wir haben Phase D (Interaktion) weitgehend abgeschlossen. Das System ist stabil, verfügt über Traffic Control und Smart Edges. Der Fokus verschiebt sich nun auf **Phase E (Maintenance & Scaling)** sowie die Vertiefung der KI-Fähigkeiten.
+
+| Phase | Fokus | Status |
+| :--- | :--- | :--- |
+| **Phase A** | Fundament & Import | ✅ Fertig |
+| **Phase B** | Semantik & Graph | ✅ Fertig |
+| **Phase C** | Persönlichkeit | ✅ Fertig |
+| **Phase D** | Interaktion & Tools | 🟡 Abschlussphase |
+| **Phase E** | Maintenance & Visualisierung | 🚀 Start |
+
+---
+
+## 2. Historie: Abgeschlossene Workpackages
+
+Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktionen. Details siehe `99_legacy_workpackages.md`.
+
+| WP | Titel | Ergebnis / Kern-Feature |
+| :--- | :--- | :--- |
+| **WP-01** | Knowledge Design | Definition von `types.yaml` und Note-Typen (Project, Concept, etc.). |
+| **WP-02** | Chunking Strategy | Implementierung von Sliding-Window und Hash-basierter Änderungserkennung. |
+| **WP-03** | Import-Pipeline | Asynchroner Importer, der Markdown in Qdrant (Notes/Edges) schreibt. |
+| **WP-04a**| Retriever Scoring | Hybride Suche: `Score = Semantik + GraphBonus + TypGewicht`. |
+| **WP-04b**| Explanation Layer | Transparenz: API liefert "Reasons" (Warum wurde das gefunden?). |
+| **WP-04c**| Feedback Loop | Logging von User-Feedback (JSONL) als Basis für Learning. |
+| **WP-05** | RAG-Chat | Integration von Ollama (`phi3`) und Context-Enrichment im Prompt. |
+| **WP-06** | Decision Engine | Hybrid Router unterscheidet Frage (`RAG`) vs. Handlung (`Interview`). |
+| **WP-07** | Interview-Assistent | One-Shot Extraction: Erzeugt Markdown-Drafts aus User-Input. |
+| **WP-10** | Web UI | Streamlit-Frontend als Ersatz für das Terminal. |
+| **WP-10a**| Draft Editor | GUI-Komponente zum Bearbeiten und Speichern generierter Notizen. |
+| **WP-11** | Backend Intelligence | `nomic-embed-text` (768d) und Matrix-Logik für Kanten-Typisierung. |
+| **WP-15** | Smart Edge Allocation | LLM-Filter für Kanten in Chunks + Traffic Control (Semaphore). |
+
+---
+
+## 3. Offene Workpackages (Planung)
+
+Diese Features stehen als nächstes an.
+
+### WP-16 – Auto-Discovery & Enrichment
+**Status:** 🟡 Geplant
+**Ziel:** Automatisches Erkennen von fehlenden Kanten in "dummem" Text *vor* der Speicherung.
+* **Problem:** Nutzer vergessen Wikilinks.
+* **Lösung:** Ein "Enricher" scannt Text vor dem Import, findet Keywords (z.B. "Mindnet") und schlägt Links vor (`[[Mindnet]]`).
+* **Abgrenzung:** Anders als *Active Intelligence* (WP11, UI-basiert) läuft dies im Backend (Importer).
+
+### WP-17 – Conversational Memory (Gedächtnis)
+**Status:** 🟡 Geplant
+**Ziel:** Echte Dialoge statt Request-Response.
+* **Tech:** Erweiterung des `ChatRequest` DTO um `history`.
+* **Logik:** Token-Management (Context Window Balancing zwischen RAG-Doks und Chat-Verlauf).
+* **Nutzen:** Rückfragen ("Was meinst du damit?") werden möglich.
+
+### WP-18 – Graph Health & Maintenance
+**Status:** 🟡 Geplant (Prio 2)
+**Ziel:** Konsistenzprüfung ("Garbage Collection").
+* **Feature:** Cronjob `check_graph_integrity.py`.
+* **Funktion:** Findet "Dangling Edges" (Links auf gelöschte Notizen) und repariert/löscht sie.
+
+### WP-19 – Graph Visualisierung & Explorer
+**Status:** 🟡 Geplant (Prio 1)
+**Ziel:** Vertrauen durch Transparenz.
+* **UI:** Neuer Tab "🕸️ Graph" in Streamlit.
+* **Tech:** `streamlit-agraph` oder `pyvis`.
+* **Nutzen:** Visuelle Kontrolle der *Smart Edge Allocation* ("Hat das LLM die Kante wirklich hierhin gesetzt?").
+
+### WP-20 – Cloud Hybrid Mode (Optional)
+**Status:** ⚪ Optional
+**Ziel:** "Turbo-Modus" für Massen-Imports.
+* **Konzept:** Switch in `.env`, um statt Ollama (Lokal) auf Google Gemini (Cloud) umzuschalten, wenn Datenschutz-unkritische Daten verarbeitet werden.
+
+---
+
+## 4. Abhängigkeiten & Release-Plan
+
+```mermaid
+graph TD
+    WP15(Smart Edges) --> WP19(Visualisierung)
+    WP15 --> WP16(Auto-Discovery)
+    WP10(Chat UI) --> WP17(Memory)
+    WP03(Import) --> WP18(Health Check)
+```
+
+**Nächstes Release (v2.7):**
+* Ziel: Visualisierung (WP19) + Conversational Memory (WP17).
+* ETA: Q1 2026.
+
+---
+
+## 5. Governance
+
+* **Versionierung:** Semantic Versioning via Gitea Tags.
+* **Feature-Branches:** Jedes WP erhält einen Branch `feature/wpXX-name`.
+* **Sync First:** Bevor ein neuer Branch erstellt wird, muss `main` gepullt werden.

docs/99_Archive/99_legacy_workpackages.md

@@ -0,0 +1,82 @@
+---
+doc_type: archive
+audience: historian, architect
+status: archived
+context: "Archivierte Details zu abgeschlossenen Workpackages (WP01-WP15). Referenz für historische Design-Entscheidungen."
+---
+
+# Legacy Workpackages (Archiv)
+
+**Quellen:** `Programmplan_V2.2.md`
+
+**Status:** Abgeschlossen / Implementiert.
+Dieses Dokument dient als Referenz für die Entstehungsgeschichte von Mindnet v2.6.
+
+## Phase A: Fundament (WP01-03)
+
+### WP-01 – Wissensdesign
+* **Ziel:** Definition der Datenstruktur.
+* **Ergebnis:** Entscheidung gegen komplexe Ontologien (RDF/OWL), für pragmatische Typen (`project`, `concept`). Definition der YAML-Frontmatter-Pflichtfelder.
+* **Artefakt:** `01_knowledge_design.md`.
+
+### WP-02 – Chunking & Hash-Strategie
+* **Ziel:** Texte suchbar machen und Änderungen erkennen.
+* **Ergebnis:** Implementierung des `SlidingWindowChunker`. Einführung von UUIDv5 für deterministische IDs.
+* **Learning:** Starre Chunking-Grenzen zerschneiden oft den Kontext. Daher Einführung von Overlap (50 Tokens).
+
+### WP-03 – Import-Pipeline & Edge-System
+* **Ziel:** Markdown in Vektoren wandeln.
+* **Ergebnis:** Der "Importer" (`import_markdown.py`). Entscheidung, Kanten (`_edges`) als eigene Collection zu führen statt als Payload in Chunks (für bessere Graphen-Algorithmen wie Centrality).
+
+---
+
+## Phase B: Semantik (WP04)
+
+### WP-04a – Retriever & Graph-Scoring
+* **Ziel:** Bessere Suchergebnisse als reines Vektor-Matching.
+* **Ergebnis:** Die Formel `Score = Semantik + GraphBonus + TypGewicht`.
+* **Learning:** Reine Vektorsuche reichte nicht, um den Kontext ("Warum ist das wichtig?") zu erfassen. Der "Graph Bonus" war der Durchbruch für assoziatives Finden.
+
+### WP-04b – Explanation Layer ("Why-Layer")
+* **Ziel:** Transparenz.
+* **Ergebnis:** `explain=True` Parameter. Die API liefert menschenlesbare Gründe ("Gefunden, weil Projekt Alpha davon abhängt").
+
+### WP-04c – Feedback Logging
+* **Ziel:** Datenbasis für zukünftiges Lernen schaffen.
+* **Ergebnis:** Das "Data Flywheel". Jede Suche und Bewertung wird in JSONL-Dateien geloggt (`search_history.jsonl`, `feedback.jsonl`).
+
+---
+
+## Phase C: Persönlichkeit (WP05-07)
+
+### WP-05 – RAG-Chat
+* **Ziel:** Natürliche Sprache statt Suchergebnisse.
+* **Ergebnis:** Integration von Ollama (`phi3`).
+* **Tech:** Prompt-Engineering (`prompts.yaml`) statt Fine-Tuning, um flexibel zu bleiben.
+
+### WP-06 – Decision Engine
+* **Ziel:** Strategische Beratung statt nur Fakten.
+* **Ergebnis:** Der Hybrid Router.
+* **Konzept:** Unterscheidung von *Fragen* (RAG) und *Handlungen* (Interview). Strategisches Laden von Werten (`type: value`), um Entscheidungen moralisch zu begründen.
+
+### WP-07 – Interview-Assistent
+* **Ziel:** Bekämpfung des "Writer's Block".
+* **Ergebnis:** One-Shot Extraction. Der Chatbot generiert aus einem losen Satz ("Neues Projekt Alpha") einen strukturierten Markdown-Draft.
+
+---
+
+## Phase D: Interaktion (WP10-15)
+
+### WP-10/10a – Web UI & Draft Editor
+* **Ziel:** Usability für Nicht-Techniker.
+* **Ergebnis:** Streamlit App. Ablösung des Terminals.
+* **Feature:** "Healing Parser", der defektes JSON vom LLM repariert.
+
+### WP-11 – Backend Intelligence
+* **Ziel:** Automatisierung der Vernetzung.
+* **Ergebnis:** AsyncIO Umstellung für Performance. Einführung von `nomic-embed-text` (768d) für präzise Semantik. Matrix-Logik für automatische Kanten-Typisierung.
+
+### WP-15 – Smart Edge Allocation (Meilenstein)
+* **Problem:** "Broadcasting". Ein Chunk erbte alle Links der Note, auch irrelevante. Das verwässerte die Suchergebnisse.
+* **Lösung:** LLM prüft jeden Chunk auf Link-Relevanz.
+* **Tech:** Einführung von **Traffic Control** (Semaphore), um Import und Chat zu parallelisieren, ohne die Hardware zu überlasten.