docs/05_Development/05_AI_dev_prompt_templates.md

@@ -1,76 +0,0 @@
-# SYSTEM-ANWEISUNG: SICHERS MARKDOWN-RENDERING
-
-Du agierst als technischer Dokumentations-Assistent. Deine Aufgabe ist das Erstellen von Markdown-Dateien (`.md`), die oft selbst Code-Blöcke (Python, JSON, YAML, Bash) enthalten.
-
-**DAS PROBLEM:**
-Wenn du eine Markdown-Datei generierst, die Code-Blöcke (```) enthält, und diese Ausgabe selbst in einen Code-Block packst, interpretiert das Chat-Interface das erste innere ` ``` ` oft fälschlicherweise als das Ende der Ausgabe. Das "zerreißt" die Datei und macht das Kopieren unmöglich.
-
-**DIE REGEL (STRIKT BEFOLGEN):**
-Um eine ununterbrochene Darstellung zu garantieren, musst du zwingend eine der folgenden Kapselungs-Methoden anwenden:
-
-### Methode A: Die 4-Backtick-Methode (Bevorzugt)
-Umschließe den **gesamten** Datei-Inhalt mit **4 Backticks** statt 3.
-Dies erlaubt dir, innerhalb der Datei normale 3 Backticks zu verwenden.
-
-Beispiel für deinen Output:
-````markdown
----
-title: Beispiel
----
-Hier ist Python Code:
-```python
-print("Hello")
-### Methode B: Die 4-Space-Einrückung (Alternative)
-Wenn du außen 3 Backticks verwendest, darfst du im Inneren **KEINE** Backticks verwenden.
-Stattdessen müssen alle inneren Code-Beispiele mit **4 Leerzeichen (Spaces)** eingerückt werden.
-
-Beispiel für deinen Output:
-```markdown
-Hier ist Python Code:
-
-    print("Hello")
-```
-
-**ZUSAMMENFASSUNG:**
-Generiere niemals verschachtelte 3-Backtick-Blöcke innerhalb von 3-Backtick-Blöcken. Nutze immer **4 Backticks** für den äußersten Container.
-```
-
----
-
-Du agierst als **Technical Documentation Lead**.
-
-**Kontext:**
-Wir haben soeben das Workpackage (WP) abgeschlossen. Der Code ist implementiert, getestet und die Änderungen sind im Chat-Verlauf dokumentiert.
-Jetzt müssen wir die Systemdokumentation (Mindnet v2.6 Modular Docs) aktualisieren, um den neuen Stand widerzuspiegeln.
-
-**Deine Aufgabe - Phase 1: Identifikation**
-Analysiere die durchgeführten Änderungen dieses Workpackages.
-Nutze die beiliegende `00_documentation_map.md`, um zu identifizieren, welche Dokumentations-Module von diesen Änderungen betroffen sind.
-
-**Beachte die Mapping-Logik:**
-* Haben wir neue Features/Konzepte eingeführt? -> `00_glossary.md`, `02_Concepts/*`
-* Haben wir die Datenbank/Payloads geändert? -> `03_tech_data_model.md`
-* Hat sich der Import/Algorithmus geändert? -> `03_tech_ingestion_pipeline.md`, `03_tech_retrieval_scoring.md`
-* Muss der Admin etwas Neues konfigurieren? -> `03_tech_configuration.md`, `04_admin_operations.md`
-* Ändert sich etwas für den Nutzer/Autor? -> `01_User_Manual/*`
-
-**Output für Phase 1:**
-Erstelle eine **Liste der betroffenen Dateien** mit einer kurzen Begründung pro Datei (z.B. "Muss neuen Parameter X aufnehmen").
-Fordere mich dann explizit auf, dir diese spezifischen Dateien hochzuladen.
-
----
-
-**Deine Aufgabe - Phase 2: Sequenzielle Bearbeitung (Warte auf Dateien)**
-Sobald ich die Dateien hochgeladen habe, aktualisieren wir sie **Schritt für Schritt**.
-1.  Nimm dir **eine** Datei aus der Liste vor.
-2.  Schreibe den kompletten, aktualisierten Inhalt dieser Datei als Markdown-Codeblock.
-    * *Wichtig:* Halte dich strikt an den bestehenden Stil (Frontmatter, JSON-Beispiele, Warnhinweise).
-    * *Wichtig:* Füge Änderungen nahtlos ein, lösche nichts Relevantes.
-3.  **Warte** nach der Ausgabe der Datei auf mein "OK" oder "Weiter", bevor du die nächste Datei bearbeitest.
-
-**Sonderaufgabe Roadmap:**
-Aktualisiere am Ende immer die `06_active_roadmap.md`:
-* Setze den Status des aktuellen WPs auf "Fertig/Live".
-* Verschiebe Details in die Historie-Tabelle (falls relevant).
-
-**Bist du bereit für die Analyse? (Ich habe Map und Roadmap hochgeladen).**

docs/05_Development/05_developer_guide.md

@@ -3,7 +3,7 @@ doc_type: developer_guide
 audience: developer
 scope: workflow, testing, architecture, modules
 status: active
-version: 2.6
+version: 2.6.1
 context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna (Deep Dive), Setup, Git-Workflow und Erweiterungs-Anleitungen."
 ---
 
@@ -14,6 +14,7 @@ context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna (Deep Di
 Dieser Guide ist die zentrale technische Referenz für Mindnet v2.6. Er vereint das technische Verständnis der Module mit dem operativen Workflow zwischen Windows (Dev) und Linux (Runtime).
 
 ---
+
 # Inhaltsverzeichnis
 - [Mindnet Developer Guide \& Workflow](#mindnet-developer-guide--workflow)
 - [Inhaltsverzeichnis](#inhaltsverzeichnis)
@@ -35,9 +36,6 @@ Dieser Guide ist die zentrale technische Referenz für Mindnet v2.6. Er vereint
     - [4.4 Scripts \& Tooling (Die Admin-Toolbox)](#44-scripts--tooling-die-admin-toolbox)
       - [1. Script-Übersicht](#1-script-übersicht)
       - [2. Einsatzszenarien \& Bewertung](#2-einsatzszenarien--bewertung)
-    - [🟢 Essentiell für den Betrieb (Must-Have)](#-essentiell-für-den-betrieb-must-have)
-    - [🟡 Hilfreich für Entwicklung \& Debugging (Should-Have)](#-hilfreich-für-entwicklung--debugging-should-have)
-    - [🔵 Wartung \& Spezialfälle (Nice-to-Have)](#-wartung--spezialfälle-nice-to-have)
   - [5. Maintenance \& "Kill List"](#5-maintenance--kill-list)
   - [6. Lokales Setup (Development)](#6-lokales-setup-development)
   - [7. Der Entwicklungs-Zyklus (Workflow)](#7-der-entwicklungs-zyklus-workflow)
@@ -51,6 +49,7 @@ Dieser Guide ist die zentrale technische Referenz für Mindnet v2.6. Er vereint
   - [10. Troubleshooting \& One-Liners](#10-troubleshooting--one-liners)
 
 ---
+
 ## 1. Einführung & Systemüberblick
 
 ### Was ist Mindnet?
@@ -123,29 +122,30 @@ graph LR
 Die hybride Suche für Chat & RAG.
 ```mermaid
 graph LR
-    Query([Query]) --> Embed(Embedding)
-    Embed --> Hybrid{Hybrid Search}
+    Query(["Query"]) --> Embed("Embedding")
+    Embed --> Hybrid{"Hybrid Search"}
     
     subgraph Search Components
-        Vec[Vector Score]
-        Graph[Graph/Edge Bonus]
+        Vec["Vector Score"]
+        Graph["Graph/Edge Bonus"]
     end
     
     Vec --> Hybrid
     Graph --> Hybrid
     
-    Hybrid --> Rank(Re-Ranking)
-    Rank --> Ctx[LLM Context]
+    Hybrid --> Rank("Re-Ranking")
+    Rank --> Ctx["LLM Context"]
 ```
 
 #### C. Visualisierung (Graph)
 Der optimierte Pfad für das Frontend.
 ```mermaid
 graph LR
-    UI[Frontend UI] --> Service(GraphService)
-    Service -- "Direct Read" --> DB[(Qdrant<br/>Edges Collection)]
-    DB --> Cyto[Cytoscape<br/>Rendering]
+    UI["Frontend UI"] --> Service("GraphService")
+    Service -- "Direct Read" --> DB[("Qdrant<br/>Edges Collection")]
+    DB --> Cyto["Cytoscape<br/>Rendering"]
 ```
+
 ---
 
 ## 3. Physische Architektur
@@ -185,16 +185,16 @@ Das Frontend ist eine Streamlit-App, die sich wie eine Single-Page-Application (
 
 | Modul | Status | Verantwortung |
 | :--- | :--- | :--- |
-| **`ui.py`** | 🟢 Core | **Main Router.** Initialisiert Session-State und entscheidet anhand der Sidebar-Auswahl, welche View gerendert wird. |
-| **`ui_config.py`** | 🟢 Config | **Constants.** Zentraler Ort für Farben (`GRAPH_COLORS`), API-URLs und Timeouts. Änderungen am Look & Feel passieren hier. |
-| **`ui_chat.py`** | 🟢 View | **Chat UI.** Rendert Nachrichtenverlauf, Intent-Badges, Quellen-Expanders und Feedback-Buttons. |
-| **`ui_editor.py`** | 🟢 View | **Editor UI.** Markdown-Editor mit Live-Vorschau. Integriert "Intelligence" (KI-Link-Vorschläge). |
-| **`ui_graph_cytoscape.py`**| 🟢 View | **Modern Graph.** Interaktiver Graph basierend auf Cytoscape.js (COSE Layout). |
-| **`ui_graph.py`** | 🟡 Legacy | **Graph UI (Fallback).** Alte Implementierung mittels `streamlit-agraph`. |
-| **`ui_callbacks.py`** | 🟢 Logic | **State Controller.** Handhabt komplexe State-Übergänge (z.B. Graph -> Editor). |
-| **`ui_utils.py`** | 🟢 Logic | **Helper.** Enthält den **Healing Parser** (`parse_markdown_draft`), der defektes JSON/YAML von LLMs repariert. |
-| **`ui_api.py`** | 🟢 Data | **API Client.** Wrapper für Backend REST-Calls. |
-| **`ui_graph_service.py`** | 🟢 Data | **Performance Hack.** Greift direkt auf Qdrant zu (bypass API), um Graphen schnell zu laden. |
+| **`ui.py`** | 🟢 **Core** | **Main Router.** Initialisiert Session-State und entscheidet anhand der Sidebar-Auswahl, welche View gerendert wird. |
+| **`ui_config.py`** | 🟢 **Config** | **Constants.** Zentraler Ort für Farben (`GRAPH_COLORS`), API-URLs und Timeouts. Änderungen am Look & Feel passieren hier. |
+| **`ui_chat.py`** | 🟢 **View** | **Chat UI.** Rendert Nachrichtenverlauf, Intent-Badges, Quellen-Expanders und Feedback-Buttons. |
+| **`ui_editor.py`** | 🟢 **View** | **Editor UI.** Markdown-Editor mit Live-Vorschau. Integriert "Intelligence" (KI-Link-Vorschläge). |
+| **`ui_graph_cytoscape.py`**| 🟢 **View** | **Modern Graph.** Interaktiver Graph basierend auf Cytoscape.js (COSE Layout). |
+| **`ui_graph.py`** | 🟡 **Legacy** | **Graph UI (Fallback).** Alte Implementierung mittels `streamlit-agraph`. |
+| **`ui_callbacks.py`** | 🟢 **Logic** | **State Controller.** Handhabt komplexe State-Übergänge (z.B. Graph -> Editor). |
+| **`ui_utils.py`** | 🟢 **Logic** | **Helper.** Enthält den **Healing Parser** (`parse_markdown_draft`), der defektes JSON/YAML von LLMs repariert. |
+| **`ui_api.py`** | 🟢 **Data** | **API Client.** Wrapper für Backend REST-Calls. |
+| **`ui_graph_service.py`** | 🟢 **Data** | **Performance Hack.** Greift direkt auf Qdrant zu (bypass API), um Graphen schnell zu laden. |
 
 #### Frontend Design Patterns (Wichtig!)
 
@@ -212,37 +212,35 @@ Das Frontend ist eine Streamlit-App, die sich wie eine Single-Page-Application (
     2.  Nur wenn das fehlschlägt, wird der Text aus den Datenbank-Chunks rekonstruiert ("Stitching").
     Dies verhindert, dass veraltete Datenbank-Stände die echten Dateien überschreiben.
 
----
-
 ### 4.3 Backend Architecture (`app/`)
 
-Das Backend stellt die Logik via REST-API bereit.
+Das Backend ist das Herzstück. Es stellt die Logik via REST-API bereit.
 
-| Modul | Typ | Verantwortung |
-| :--- | :--- | :--- |
-| **Core Engine** | | |
-| `core/ingestion.py` | Engine | **Pipeline Controller.** Koordiniert den 13-Schritte-Import, Parsing, Hash-Check und DB-Upserts. |
-| `core/retriever.py` | Engine | **Search Engine.** Berechnet Hybrid-Score: `(Semantic * W) + (Edge Bonus * 0.25) + (Centrality * 0.05)`. |
-| `core/chunker.py` | Engine | **Segmentation.** Zerlegt Text intelligent. Orchestriert `SemanticAnalyzer` für Smart Edges. |
-| `core/derive_edges.py`| Engine | **Link Extractor.** Findet Wikilinks, Callouts und Typed Relations im Text. |
-| `core/qdrant_points.py`| Mapper | **Object Mapper.** Wandelt Payloads in Qdrant `PointStruct`s um. |
-| `core/graph_adapter.py` | Algo | **Graph Logic.** Baut In-Memory Graphen für Re-Ranking und Pfad-Analysen. |
-| **Router (API)** | | |
-| `routers/chat.py` | Router | **Hybrid Router.** Entscheidet: RAG-Antwort vs. Interview-Modus. |
-| `routers/ingest.py` | Router | **Write API.** Nimmt Markdown entgegen, steuert Ingestion und Discovery-Analyse. |
-| `routers/query.py` | Router | **Search API.** Klassischer Hybrid-Retriever Endpunkt. |
-| `routers/graph.py` | Router | **Viz API.** Liefert Knoten/Kanten für Frontend. |
-| **Services** | | |
-| `services/llm_service.py`| Service | **Traffic Control.** Async Client für Ollama. Nutzt **Semaphore**, um Hintergrund-Jobs (Import) zu drosseln. |
-| `services/discovery.py`| Service | **Intelligence.** "Matrix Logic" für Link-Vorschläge (WP-11). |
-| `services/semantic_analyzer.py`| Service | **Filter.** KI-Validierung von Kanten im Hintergrund. |
-| `services/feedback_service.py`| Service | **Logging.** Schreibt Interaktions-Logs (JSONL). |
-
----
+| Layer | Datei | Status | Verantwortung |
+| :--- | :--- | :--- | :--- |
+| **Entry** | `app/main.py` | 🟢 **Core** | **Entrypoint.** Initialisiert FastAPI, CORS, und bindet alle Router ein. |
+| **Config** | `app/config.py` | 🟢 **Core** | **Settings.** Zentrale Konfiguration (Pydantic). Lädt Env-Vars für Qdrant, LLM und Pfade. |
+| **Router** | `app/routers/chat.py` | 🟢 **API** | **Conversation API.** Haupt-Endpunkt für Chat. Entscheidet zwischen Interview- und RAG-Modus. |
+| | `app/routers/ingest.py` | 🟢 **API** | **Write API.** Nimmt Markdown entgegen, steuert Ingestion und Discovery-Analyse. |
+| | `app/routers/query.py` | 🟢 **API** | **Search API.** Klassischer Hybrid-Retriever Endpunkt. |
+| | `app/routers/graph.py` | 🟢 **API** | **Viz API.** Liefert Knoten/Kanten für Frontend-Graphen (Cytoscape). |
+| | `app/routers/tools.py` | 🟢 **API** | **Agent Specs.** Liefert JSON-Schemas für die Integration in externe Agenten (Ollama/MCP). |
+| **Engine** | `app/core/ingestion.py` | ⚙️ **Core** | **Pipeline Controller.** Koordiniert Parsing, Hashing (Change-Detection) und DB-Upserts. |
+| | `app/core/retriever.py` | ⚙️ **Core** | **Search Engine.** Berechnet Scores (Vektor + Graph + Centrality) und baut Erklärungen. |
+| | `app/core/chunker.py` | ⚙️ **Core** | **Segmentation.** Zerlegt Text intelligent. Orchestriert `SemanticAnalyzer` für Smart Edges. |
+| | `app/core/parser.py` | ⚙️ **Core** | **I/O.** Liest Markdown robust (Encoding-Fallback), trennt Frontmatter/Body. |
+| | `app/core/derive_edges.py`| ⚙️ **Core** | **Link Extractor.** Findet Wikilinks, Callouts und Typed Relations im Text. |
+| | `app/core/note_payload.py`| ⚙️ **Core** | **Builder.** Erzeugt JSON für `mindnet_notes`. Vererbt Configs (Frontmatter > Type > Default). |
+| | `app/core/qdrant_points.py`| ⚙️ **Core** | **Object Mapper.** Wandelt Payloads in Qdrant `PointStruct`s um. Handhabt UUIDs. |
+| **Services** | `app/services/llm_service.py`| 🧠 **AI** | **AI Client.** Async Client für Ollama. Verwaltet Concurrency (Semaphore). |
+| | `app/services/embeddings_client.py`| 🧠 **AI** | **Vector Client.** Unified Client für Embeddings (Ollama/Nomic). Ersetzt lokale Modelle. |
+| | `app/services/discovery.py`| 🧠 **AI** | **Intelligence.** "Matrix Logic" für Link-Vorschläge (WP-11). |
+| | `app/services/semantic_analyzer.py`| 🧠 **AI** | **Filter.** KI-Validierung von Kanten im Hintergrund (Background Priority). |
 
 ### 4.4 Scripts & Tooling (Die Admin-Toolbox)
 
 Der Ordner `scripts/` enthält verifizierte Werkzeuge für den Betrieb.
+
 #### 1. Script-Übersicht
 
 | Skript | Status | Zweck | Argumente & Parameter | Beispielaufruf |
@@ -255,22 +253,21 @@ Der Ordner `scripts/` enthält verifizierte Werkzeuge für den Betrieb.
 | **`resolve_unresolved_references.py`** | 🔵 **Maint** | **Link-Healer.** Repariert "tote" Links in der DB nachträglich und erzeugt Backlinks. | `--prefix TEXT`<br>`--limit INT`<br>`--apply` (Schreibt Änderungen) | `python3 -m scripts.resolve_unresolved_references --apply` |
 | **`export_markdown.py`** | ⚪ **Utility** | **Reverse ETL.** Exportiert den Datenbank-Inhalt zurück in Markdown-Dateien (Backup/Recovery). | `--out PATH` (Ziel)<br>`--note-id ID`<br>`--include-edges {yaml,footer}`<br>`--flatten-paths` | `python3 -m scripts.export_markdown --out ./backup` |
 
----
-
 #### 2. Einsatzszenarien & Bewertung
 
-### 🟢 Essentiell für den Betrieb (Must-Have)
-* **`import_markdown.py`**: Das Arbeitspferd. Ohne dieses Skript kommen keine Daten ins System (außer man nutzt die API einzeln). Es ist für Cronjobs optimiert.
-* **`reset_qdrant.py`**: Zwingend notwendig für CI/CD-Pipelines oder saubere Neustarts bei Schema-Änderungen.
-* **`health_check_mindnet.py`**: Ideal für Docker-Healthchecks oder Monitoring-Tools (Nagios, Uptime Kuma), da es keine Python-Abhängigkeiten zur App hat.
+* **🟢 Essentiell für den Betrieb (Must-Have):**
+    * **`import_markdown.py`**: Das Arbeitspferd. Ohne dieses Skript kommen keine Daten ins System.
+    * **`reset_qdrant.py`**: Zwingend notwendig für CI/CD-Pipelines.
+    * **`health_check_mindnet.py`**: Ideal für Docker-Healthchecks.
 
-### 🟡 Hilfreich für Entwicklung & Debugging (Should-Have)
-* **`payload_dryrun.py`**: Sehr wertvoll, wenn man an der `config/types.yaml` oder dem `chunker.py` arbeitet. Man sieht sofort, wie das JSON aussieht, ohne die Datenbank "zuzumüllen".
-* **`edges_full_check.py`**: Wichtiges Diagnose-Tool, wenn der Graph im Frontend "komisch" aussieht oder Kanten fehlen.
+* **🟡 Hilfreich für Entwicklung & Debugging (Should-Have):**
+    * **`payload_dryrun.py`**: Wertvoll, wenn man an der `config/types.yaml` arbeitet.
+    * **`edges_full_check.py`**: Wichtiges Diagnose-Tool für den Graphen.
+
+* **🔵 Wartung & Spezialfälle (Nice-to-Have):**
+    * **`resolve_unresolved_references.py`**: Sinnvoll in einem "Knowledge Garden", wo oft Links auf noch nicht existierende Notizen gesetzt werden ("Red Links"). Dieses Skript "heilt" den Graphen nachträglich.
+    * **`export_markdown.py`**: Ein Notfall-Tool. Da Mindnet nach dem Prinzip "Filesystem First" arbeitet, ist ein Export aus der DB selten nötig, kann aber bei versehentlichem Löschen von Dateien lebensrettend sein.
 
-### 🔵 Wartung & Spezialfälle (Nice-to-Have)
-* **`resolve_unresolved_references.py`**: Sinnvoll in einem "Knowledge Garden", wo oft Links auf noch nicht existierende Notizen gesetzt werden ("Red Links"). Dieses Skript "heilt" den Graphen nachträglich.
-* **`export_markdown.py`**: Ein Notfall-Tool. Da Mindnet nach dem Prinzip "Filesystem First" arbeitet, ist ein Export aus der DB selten nötig, kann aber bei versehentlichem Löschen von Dateien lebensrettend sein.
 ---
 
 ## 5. Maintenance & "Kill List"
@@ -280,12 +277,14 @@ Folgende Dateien wurden im Audit v2.6 als veraltet, redundant oder "Zombie-Code"
 | Datei | Diagnose | Empfohlene Aktion |
 | :--- | :--- | :--- |
 | `app/embed_server.py` | **Zombie.** Alter Standalone-Server. | 🗑️ Löschen |
-| `app/embeddings.py` | **Zombie.** Veraltete lokale Lib. | 🗑️ Löschen |
+| `app/embeddings.py` | **Zombie.** Veraltete lokale Lib. **(Achtung: Erst Importe in `main.py` entfernen!)** | 🗑️ Löschen |
+| `app/routers/embed_router.py` | **Zombie.** Nutzt `embeddings.py`. | 🗑️ Löschen |
+| `app/routers/qdrant_router.py`| **Deprecated.** Keine Logik, nur CRUD. | 🗑️ Löschen |
 | `app/core/edges.py` | **Redundant.** Ersetzt durch `derive_edges.py`. | 🗑️ Löschen |
 | `app/core/ranking.py` | **Redundant.** Logik in `retriever.py` integriert. | 🗑️ Löschen |
 | `app/core/type_registry.py` | **Redundant.** Logik in `ingestion.py` integriert. | 🗑️ Löschen |
 | `app/core/env_vars.py` | **Veraltet.** Ersetzt durch `config.py`. | 🗑️ Löschen |
-| `app/routers/qdrant_router.py`| **Deprecated.** Keine Logik, nur CRUD. | 📂 Verschieben nach `scripts/archive/` |
+| `app/services/llm_ollama.py` | **Veraltet.** Ersetzt durch `llm_service.py`. | 🗑️ Löschen |
 
 ---
 
@@ -432,6 +431,12 @@ python tests/test_feedback_smoke.py --url http://localhost:8002/query
 python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes
 ```
 
+**Graphen reparieren (Red Links auflösen):**
+Nutze dies, wenn Kanten im Graphen ins Leere zeigen (weil die Notiz beim Import noch nicht da war).
+```bash
+python3 -m scripts.resolve_unresolved_references --apply
+```
+
 **Einen einzelnen File inspizieren (Parser-Sicht):**
 ```bash
 python3 tests/inspect_one_note.py --file ./vault/MeinFile.md