docs/developer_guide.md aktualisiert

docs/developer_guide.md

@@ -1,7 +1,7 @@
 # Mindnet v2.2 – Developer Guide
 **Datei:** `docs/mindnet_developer_guide_v2.2.md`
 **Stand:** 2025-12-08
-**Status:** **FINAL** (Inkl. RAG & LLM Setup)
+**Status:** **FINAL** (Inkl. RAG & AI-Teaching Paradigm)
 **Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`.
 
 > **Zielgruppe:** Entwickler:innen.
@@ -54,6 +54,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
 * **Vault:** Ein Ordner mit Markdown-Dateien (z.B. `./mindnet_v2_test_vault` für Tests).
 
 ### 2.2 Installation
+
     # 1. Repository klonen & Verzeichnis wechseln
     git clone <repo> mindnet
     cd mindnet
@@ -100,6 +101,7 @@ Auf dem Entwicklungsserver (Beelink) nutzen wir Systemd.
     journalctl -u mindnet-dev -f
 
 Falls du lokal auf Windows entwickelst:
+
     # 1. Qdrant starten
     docker run -p 6333:6333 qdrant/qdrant
     # 2. Ollama starten
@@ -134,6 +136,7 @@ Wir unterscheiden drei Test-Ebenen. Ein Pull Request sollte alle passieren.
 
 ### 4.1 Unit Tests (Pytest)
 Für isolierte Logik (Parsing, Scoring).
+
     pytest tests/test_retriever_basic.py
     pytest tests/test_chunking.py
     pytest tests/test_edges_all.py
@@ -141,9 +144,11 @@ Für isolierte Logik (Parsing, Scoring).
 ### 4.2 Integration / Pipeline Tests
 Prüfen den Datenfluss von Markdown bis Qdrant-JSON.
 * **Payload Dryrun:** Prüft JSON-Schema Konformität.
+
     python3 -m scripts.payload_dryrun --vault ./mindnet_v2_test_vault
 
 * **Edge Checks:** Prüft Graph-Invarianten.
+
     python3 -m scripts.edges_full_check
 
 ### 4.3 Smoke Tests (E2E)
@@ -161,32 +166,62 @@ Prüfen das laufende System (API) gegen eine echte Qdrant-Instanz und Ollama.
 
 ---
 
-## 5. Guidelines für Erweiterungen
+## 5. Das "Teach-the-AI" Paradigma (Context Intelligence)
 
-### 5.1 Neuen Note-Typ hinzufügen
-* Bearbeite `config/types.yaml`.
-* Definiere `chunk_profile`, `retriever_weight` und `edge_defaults`.
-* Führe einen **Re-Import** durch.
+Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration** und **Kontext**. Wenn du dem System ein neues Konzept (z.B. "Risiko" oder "Strategie") beibringen willst, musst du an drei Stellen eingreifen. Dies ist der **Core-Workflow** für Erweiterungen.
 
-### 5.2 Persönlichkeit anpassen (Prompt Engineering)
-* Bearbeite `config/prompts.yaml`.
-* Änderungen sind sofort aktiv (kein Neustart nötig, da pro Request geladen, sofern nicht gecached).
-* **Prompt-Regel:** Kleine Modelle (Phi-3) brauchen strikte Anweisungen (z.B. "Achte auf [DECISION]").
+### Das Dreieck der Bedeutung
+1.  **Daten-Ebene (`types.yaml`):** Definiert die Existenz und Wichtigkeit.
+2.  **Code-Ebene (`chat.py`):** Macht den Typ für das LLM sichtbar (Labeling).
+3.  **Kognitive Ebene (`prompts.yaml`):** Erklärt dem LLM, wie es den Typ interpretieren soll.
 
-### 5.3 Neue API-Endpunkte
-* Erstelle einen neuen Router in `app/routers/`.
-* Registriere den Router in `app/main.py`.
-* Denke an **Traceability**: Generiere oder durchschleife `query_id`.
+### Workflow: Einen neuen Typ implementieren (Bsp: `risk`)
+
+**Schritt 1: Physik definieren (`config/types.yaml`)**
+Definiere, wie der Typ importiert und gesucht wird.
+
+    risk:
+      chunk_profile: short       # Risiken sind oft kurze Statements
+      retriever_weight: 0.90     # Sehr wichtig, fast so hoch wie Decisions
+      edge_defaults: ["blocks"]  # Ein Risiko blockiert oft das verlinkte Projekt
+
+*Ergebnis:* Notizen werden importiert und landen bei Suchen weit oben.
+
+**Schritt 2: Labeling prüfen (`app/routers/chat.py`)**
+Der Router (Funktion `_build_enriched_context`) liest das Feld `type` automatisch aus und injiziert es als `TYP: [RISK]` in den Prompt.
+* *Prüfung:* Keine Code-Änderung nötig, da der Router generisch programmiert ist.
+* *Ausnahme:* Wenn du spezielle Logik brauchst (z.B. "Risiken immer rot markieren"), müsstest du hier den Code anpassen.
+
+**Schritt 3: Verstehen lehren (`config/prompts.yaml`)**
+Das LLM sieht nun `[RISK]`. Aber was soll es damit tun? Das definierst du hier.
+Ergänze den `system_prompt` oder das `rag_template`:
+
+    system_prompt: |
+      ...
+      REGELN FÜR TYPEN:
+      - [DECISION]: Begründung für Handlungen.
+      - [RISK]: Warnung! Wenn ein [RISK] im Kontext ist, weise den User darauf hin, bevor du eine Lösung empfiehlst.
+
+*Ergebnis:* Das System entwickelt ein "Risikobewusstsein".
+
+### Fazit
+Nur wenn **alle drei Ebenen** synchron sind, entsteht intelligente Persönlichkeit.
+* Ohne Schritt 1 findet das System die Notiz nicht.
+* Ohne Schritt 2 sieht das LLM nur Text, keinen Typ.
+* Ohne Schritt 3 ignoriert das LLM den Typ, weil es ihn nicht versteht.
 
 ---
 
 ## 6. Nützliche Einzeiler
 
 **DB komplett zurücksetzen (Vorsicht!):**
+
     python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes
 
 **Einen einzelnen File inspizieren (Parser-Sicht):**
+
     python3 tests/inspect_one_note.py --file ./vault/MeinFile.md
 
 **Live-Logs sehen (Beelink):**
+
     journalctl -u mindnet-dev -f