mindnet/docs/05_Development/05_developer_guide.md

---
doc_type: developer_guide
audience: developer
scope: workflow, testing, architecture, modules, modularization, agentic_rag, lazy_prompts, agentic_validation
status: active
version: 4.5.8
context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), WP-25 Agentic Multi-Stream RAG, WP-25a MoE, WP-25b Lazy-Prompt-Orchestration, WP-24c Phase 3 Agentic Edge Validation (v4.5.8), Modul-Interna, Setup und Git-Workflow."
---

# Mindnet Developer Guide & Workflow

**Quellen:** `developer_guide.md`, `dev_workflow.md`, `Architecture_Audit_v2.6`

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)
  - [1. Einführung \& Systemüberblick](#1-einführung--systemüberblick)
    - [Was ist Mindnet?](#was-ist-mindnet)
    - [Kern-Philosophie](#kern-philosophie)
  - [2. Architektur](#2-architektur)
    - [2.1 High-Level Übersicht](#21-high-level-übersicht)
      - [B. Retrieval (Read)](#b-retrieval-read)
      - [C. Visualisierung (Graph)](#c-visualisierung-graph)
  - [3. Physische Architektur](#3-physische-architektur)
  - [4. Projektstruktur \& Modul-Referenz (Deep Dive)](#4-projektstruktur--modul-referenz-deep-dive)
    - [4.1 Verzeichnisbaum](#41-verzeichnisbaum)
    - [4.2 Frontend Architecture (`app/frontend/`)](#42-frontend-architecture-appfrontend)
      - [Frontend Design Patterns (Wichtig!)](#frontend-design-patterns-wichtig)
    - [4.3 Backend Architecture (`app/`)](#43-backend-architecture-app)
    - [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)
  - [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)
    - [Phase 1: Windows (Code)](#phase-1-windows-code)
    - [Phase 2: Beelink (Test / Dev)](#phase-2-beelink-test--dev)
    - [Phase 3: Release \& Deployment (Prod)](#phase-3-release--deployment-prod)
  - [8. Erweiterungs-Guide: "Teach-the-AI"](#8-erweiterungs-guide-teach-the-ai)
    - [Workflow A: Neuen Typ implementieren (z. B. `type: risk`)](#workflow-a-neuen-typ-implementieren-z-b-type-risk)
    - [Workflow B: Graph-Farben ändern](#workflow-b-graph-farben-ändern)
  - [9. Tests \& Debugging](#9-tests--debugging)
  - [10. Troubleshooting \& One-Liners](#10-troubleshooting--one-liners)

---

## 1. Einführung & Systemüberblick

### Was ist Mindnet?
Mindnet ist ein **Hybrides Knowledge Management System**, das klassische Notizen (Markdown) mit KI-gestützter Analyse verbindet. Es kombiniert **RAG** (Retrieval Augmented Generation) mit einer **Graphen-Datenbank** (Qdrant), um Wissen nicht nur semantisch zu finden, sondern auch strukturell zu vernetzen.

### Kern-Philosophie
1.  **Filesystem First:** Die Wahrheit liegt immer auf der Festplatte (Markdown-Dateien). Die Datenbank ist ein abgeleiteter Index.
2.  **Hybrid Retrieval:** Relevanz entsteht aus Textähnlichkeit (Semantik) + Graphen-Verbindungen (Edges) + Wichtigkeit (Centrality).
3.  **Active Intelligence:** Das System wartet nicht nur auf Anfragen, sondern schlägt beim Schreiben proaktiv Verbindungen vor ("Matrix Logic").
4.  **Local Privacy:** Alle KI-Berechnungen (Ollama) laufen lokal. Keine Cloud-Abhängigkeit für Inference.

---

## 2. Architektur

### 2.1 High-Level Übersicht
Das System folgt einer strikten Trennung zwischen Frontend (Streamlit) und Backend (FastAPI), wobei bestimmte Performance-Pfade (Graph-Visualisierung) optimiert wurden.

```mermaid
graph TD
    User((User))
    
    subgraph "Frontend Layer (Streamlit)"
        UI["ui.py Router"]
        ViewChat["Chat View"]
        ViewGraph["Graph View"]
        ViewEditor["Editor View"]
        Logic["Callbacks & State"]
    end
    
    subgraph "Backend Layer (FastAPI)"
        API["main.py"]
        RouterChat["Chat / RAG"]
        RouterIngest["Ingest / Write"]
        
        subgraph "Core Packages (WP-14)"
            PkgRet["retrieval/ (Search)"]
            PkgIng["ingestion/ (Import)"]
            PkgGra["graph/ (Logic)"]
            PkgDb["database/ (Infrastr.)"]
            Registry["registry.py (Neutral)"]
        end
    end
    
    subgraph "Infrastructure & Services"
        LLM["Ollama / Cloud (Hybrid)"]
        DB[("Qdrant Vector DB")]
        FS["File System (.md)"]
    end

    User <--> UI
    UI -- "REST Call" --> API
    PkgRet -- "Direct Query" --> PkgDb
    PkgIng -- "Process & Write" --> PkgDb
    PkgDb -- "API" --> DB
    API -- "Inference" --> LLM```

### 2.2 Datenfluss-Muster

#### A. Ingestion (Write)
Vom Markdown zur Vektor-Datenbank.
```mermaid
graph LR
    MD["Markdown File"] --> Pass1["Pass 1: Pre-Scan"]
    Pass1 --> Cache[("LocalBatchCache<br/>(Titles/Summaries)")]
    MD --> Pass2["Pass 2: Processing"]
    Cache -- "Context" --> SmartEdges{"Smart Edge<br/>Validation"}
    SmartEdges --> Embedder("Embedder")
    Embedder --> DB[("Qdrant Points")]
```

#### B. Retrieval (Read)
Die hybride Suche für Chat & RAG.
```mermaid
graph LR
    Query(["Query"]) --> Embed("Embedding")
    Embed --> Seed["Seed Search (Vector)"]
    Seed --> Expand{"Graph Expansion"}
    Expand --> Scoring["Scoring Engine (WP-22)"]
    Scoring --> Rank("Final 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"]
```

---

## 3. Physische Architektur

Mindnet läuft in einer verteilten Umgebung (Post-WP15 Setup).

* **Windows 11 (VS Code):** Entwicklungsumgebung. **Nie** direkt auf `main` arbeiten!
* **Beelink (Runtime):** Der Server hostet zwei Instanzen via Systemd:
    * **PROD:** API (Port 8001) + UI (Port 8501). Home: `~/mindnet`.
    * **DEV:** API (Port 8002) + UI (Port 8502). Home: `~/mindnet_dev`.
* **Gitea (Raspberry Pi):** Versionskontrolle ("Safe"). Speichert den Code.

---

## 4. Projektstruktur & Modul-Referenz (Deep Dive)

Das System ist modular aufgebaut. Hier ist die detaillierte Analyse aller Komponenten.

### 4.1 Verzeichnisbaum

```text
mindnet/
├── app/
│   ├── core/           # Business Logic & Algorithms
│   │   ├── database/    # WP-14: Qdrant Client & Point Mapping
│   │   ├── ingestion/   # WP-14: Pipeline, Multi-Hash, Validation
│   │   ├── retrieval/   # WP-14: Search Orchestrator & Scoring
│   │   ├── graph/       # WP-14: Subgraph-Logik & Weights
│   │   ├── registry.py  # SSOT: Circular Import Fix & Text Cleanup
│   │   └── *.py (Proxy) # Legacy Bridges für Abwärtskompatibilität
│   ├── routers/        # API Interface (FastAPI)
│   ├── services/       # External Integrations (LLM, DB)
│   ├── models/         # Pydantic DTOs
│   └── frontend/       # UI Logic (Streamlit)
├── config/             # Configuration Files (YAML)
├── scripts/            # CLI Tools (Ops & Maintenance)
└── vault/              # Local Content Storage
```

### 4.2 Frontend Architecture (`app/frontend/`)

Das Frontend ist eine Streamlit-App, die sich wie eine Single-Page-Application (SPA) verhält.

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

#### Frontend Design Patterns (Wichtig!)

1.  **Active Inspector Pattern (`ui_graph_cytoscape.py`)**
    Um Re-Renders im Graphen zu vermeiden, nutzen wir CSS-Klassen. Wird ein Knoten angeklickt, ändert sich nur die CSS-Klasse (`.inspected`), aber die Physik-Simulation startet nicht neu. Das sorgt für ein stabiles UI-Gefühl.

2.  **Resurrection Pattern (`ui_editor.py`)**
    Streamlit neigt dazu, Eingaben bei Re-Runs zu "vergessen". Der Editor synchronisiert seinen Inhalt aggressiv in den `session_state`.
    * Logik: `if widget_key not in session_state: restore_from_data_key()`.
    * Ergebnis: Texteingaben überleben Tab-Wechsel.

3.  **Filesystem First (`ui_callbacks.py`)**
    Wenn man im Graphen auf "Bearbeiten" klickt:
    1.  Versucht das System, die **echte Datei** von der Festplatte zu lesen.
    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 ist das Herzstück. Es stellt die Logik via REST-API bereit.

**Wichtig:** Seit WP-14 ist die Core-Logik in spezialisierte Pakete unterteilt:

#### Core-Pakete (Modularisierung WP-14)

| Paket | Zweck | Wichtige Module |
| :--- | :--- | :--- |
| **`app/core/chunking/`** | Text-Segmentierung | `chunking_strategies.py` (Sliding/Heading), `chunking_processor.py` (Orchestrierung) |
| **`app/core/database/`** | Qdrant-Infrastruktur | `qdrant.py` (Client), `qdrant_points.py` (Point-Mapping) |
| **`app/core/graph/`** | Graph-Logik | `graph_subgraph.py` (Expansion), `graph_weights.py` (Scoring) |
| **`app/core/ingestion/`** | Import-Pipeline | `ingestion_processor.py` (3-Phasen-Modell: Pre-Scan, Semantic Processing, Phase 3 Agentic Validation), `ingestion_validation.py` (Mistral-safe Parsing, Phase 3 Validierung) |
| **`app/core/parser/`** | Markdown-Parsing | `parsing_markdown.py` (Frontmatter/Body), `parsing_scanner.py` (File-Scan) |
| **`app/core/retrieval/`** | Suche & Scoring | `retriever.py` (Orchestrator), `retriever_scoring.py` (Mathematik) |
| **`app/core/registry.py`** | SSOT & Utilities | Text-Bereinigung, Circular-Import-Fix |

**Legacy-Bridges:** Die alten Dateien (`app/core/retriever.py`, `app/core/qdrant.py`) existieren noch als Proxy-Adapter für Abwärtskompatibilität, delegieren aber an die neuen Pakete.

| Layer | Datei | Status | Verantwortung |
| :--- | :--- | :--- | :--- |
| **Entry** | `app/main.py` | 🟢 **Core** | **Entrypoint.** Initialisiert FastAPI, CORS, und bindet alle Router ein. |
| **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 (WP-25).** Haupt-Endpunkt für Chat. Hybrid Router mit Intent-Erkennung, Multi-Stream Orchestration und Wissens-Synthese. |
| | `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 |
| :--- | :--- | :--- | :--- | :--- |
| **`import_markdown.py`** | 🟢 **Core** | **Ingestion.** Scannt den Vault und importiert Dateien asynchron in Qdrant. Beachtet Hashes. | `--vault PATH` (Quellordner)<br>`--prefix TEXT` (Collection Prefix)<br>`--force` (Erzwingt Re-Index)<br>`--apply` (Schreibt in DB; sonst Dry-Run) | `python3 scripts/import_markdown.py --vault ./vault --apply` |
| **`reset_qdrant.py`** | 🟢 **Core** | **DB-Reset.** Löscht Collections (`wipe`) oder leert sie (`truncate`). Legt Indizes neu an. | `--mode {wipe,truncate}`<br>`--prefix TEXT`<br>`--yes` (Keine Rückfrage)<br>`--no-indexes` (Skip Index-Erstellung) | `python3 -m scripts.reset_qdrant --mode wipe --yes` |
| **`health_check_mindnet.py`** | 🟢 **Ops** | **Monitoring.** Prüft API-Verfügbarkeit (`/query`) und Antwortqualität. Standalone (keine Imports). | `--url URL`<br>`--query TEXT`<br>`--top-k INT`<br>`--strict` (Exit-Code 1 bei Warnings) | `python3 scripts/health_check_mindnet.py --strict` |
| **`payload_dryrun.py`** | 🟡 **Dev** | **Debugger.** Simuliert die JSON-Erstellung (Payloads) ohne DB-Schreibzugriff. Prüft `types.yaml`. | `--vault PATH`<br>`--note-id ID` (Filter)<br>`--with-edges` (Zeigt Kanten) | `python3 -m scripts.payload_dryrun --vault ./vault --note-id "projekt-alpha"` |
| **`edges_full_check.py`** | 🟡 **Audit** | **Integritäts-Check.** Zählt Kanten in der DB und prüft logische Konsistenz (z.B. Chunk-Reihenfolge). | Keine (Liest Konfiguration nur aus Umgebungsvariablen `.env`) | `python3 -m scripts.edges_full_check` |
| **`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.
    * **`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`**: 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.

---

## 5. Maintenance & "Kill List"

Folgende Dateien wurden im Audit v2.6 als veraltet, redundant oder "Zombie-Code" identifiziert und sollten entfernt werden.

| Datei | Diagnose | Empfohlene Aktion |
| :--- | :--- | :--- |
| `app/embed_server.py` | **Zombie.** Alter Standalone-Server. | 🗑️ 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/services/llm_ollama.py` | **Veraltet.** Ersetzt durch `llm_service.py`. | 🗑️ Löschen |
| `app/core/type_registry.py` | **Redundant.** Logik in `app/core/registry.py` integriert. | 🗑️ Löschen |
| `app/core/ranking.py` | **Redundant.** Logik in `retrieval/retriever_scoring.py` integriert. | 🗑️ Löschen |

---

## 6. 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"
MINDNET_OLLAMA_URL="http://localhost:11434"
MINDNET_LLM_MODEL="phi3:mini"
MINDNET_EMBEDDING_MODEL="nomic-embed-text"
COLLECTION_PREFIX="mindnet_dev"
VECTOR_DIM=768
MINDNET_LLM_BACKGROUND_LIMIT=2
MINDNET_API_URL="http://localhost:8002"
```

---

## 7. Der Entwicklungs-Zyklus (Workflow)

### Phase 1: Windows (Code)
1.  **Basis aktualisieren:** `git checkout main && git pull`.
2.  **Branch erstellen:** `git checkout -b feature/mein-feature`.
3.  **Coden & Committen.**
4.  **Push:** `git push origin feature/mein-feature`.

### Phase 2: Beelink (Test / Dev)
Hier prüfst du, ob dein Code auf Linux läuft.
1.  **Einloggen:** `ssh user@beelink`.
2.  **Ordner:** `cd ~/mindnet_dev`.
3.  **Code holen:** `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 ...` im Terminal und chatte gleichzeitig im UI (Port 8502).
    * **API Check:** `curl -X POST "http://localhost:8002/ingest/analyze" ...`

### Phase 3: Release & Deployment (Prod)
Wenn alles getestet ist:
1.  **Gitea:** Pull Request erstellen und mergen.
2.  **Deploy auf Prod (Beelink):**
    ```bash
    cd ~/mindnet
    git pull origin main
    
    # Sicherstellen, dass Prod-Dependencies aktuell sind
    source .venv/bin/activate
    pip install -r requirements.txt
    ollama pull nomic-embed-text # Falls neue Modelle nötig sind
    
    # Restart
    sudo systemctl restart mindnet-prod
    sudo systemctl restart mindnet-ui-prod
    ```
3.  **Cleanup:** Branch löschen (lokal und remote).

---

## 8. Erweiterungs-Guide: "Teach-the-AI"

Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration** und **Vernetzung**.

### Workflow A: Neuen Typ implementieren (z. B. `type: risk`)
1.  **Physik (`config/types.yaml`):**
    ```yaml
    risk:
      chunk_profile: sliding_short
      retriever_weight: 0.90       # Sehr wichtig
      edge_defaults: ["blocks"]    # Automatische Kante
      detection_keywords: ["gefahr", "risiko"]
    ```
2.  **Strategie (`config/decision_engine.yaml` v3.2.2, WP-25/25a):**
    ```yaml
    DECISION:
      use_streams: ["values_stream", "facts_stream", "risk_stream"]  # WP-25: Multi-Stream
      llm_profile: "synthesis_pro"  # WP-25a: MoE-Profil für Synthese
      inject_types: ["value", "risk"]  # Legacy: Fallback für nicht-Stream-Typen
    ```
    *Ergebnis (WP-25/25a):* Wenn der Intent `DECISION` erkannt wird, führt das System parallele Abfragen in Values, Facts und Risk Streams aus, komprimiert überlange Streams via `compression_profile` und synthetisiert die Ergebnisse mit dem `synthesis_pro` Profil.

3.  **LLM-Profil (`config/llm_profiles.yaml` v1.3.0, WP-25a):**
    ```yaml
    synthesis_pro:
      provider: "openrouter"
      model: "google/gemini-2.0-flash-exp:free"
      temperature: 0.7
      fallback_profile: "synthesis_backup"
    ```
    *Ergebnis (WP-25a):* Zentrale Steuerung von Provider, Modell und Temperature pro Aufgabe. Automatische Fallback-Kaskade bei Fehlern.

4.  **Prompt-Template (`config/prompts.yaml` v3.2.2, WP-25b):**
    ```yaml
    decision_synthesis_v1:
      # Level 1: Modell-spezifisch (höchste Priorität)
      "google/gemini-2.0-flash-exp:free": |
        WERTE & PRINZIPIEN (Identität):
        {values_stream}
        ...
      
      # Level 2: Provider-Fallback
      openrouter: |
        WERTE & PRINZIPIEN (Identität):
        {values_stream}
        ...
      
      # Level 3: Global Default
      default: |
        Synthetisiere die folgenden Informationen für: {query}
        ...
    ```
    *Ergebnis (WP-25b):* Hierarchische Prompt-Resolution mit Lazy-Loading. Prompts werden erst zur Laufzeit geladen, basierend auf aktivem Modell. Maximale Resilienz bei Modell-Fallbacks.

5.  **Phase 3 Validierung (WP-24c v4.5.8):** Kanten mit `candidate:` Präfix werden automatisch in Phase 3 validiert:
    * **Trigger:** Kanten in Header-Zonen (konfiguriert via `MINDNET_LLM_VALIDATION_HEADERS`) erhalten `candidate:` Präfix
    * **Validierung:** Nutzt `ingest_validator` Profil (Temperature 0.0) für deterministische YES/NO Entscheidungen
    * **Kontext-Optimierung:** Note-Scope nutzt `note_summary`, Chunk-Scope nutzt spezifischen Chunk-Text
    * **Erfolg:** Entfernt `candidate:` Präfix, Kante wird persistiert
    * **Ablehnung:** Kante wird zu `rejected_edges` hinzugefügt und **nicht** in DB geschrieben
    * **Logging:** `🚀 [PHASE 3]` für Start, `✅ [PHASE 3] VERIFIED` für Erfolg, `🚫 [PHASE 3] REJECTED` für Ablehnung

### Workflow B: Graph-Farben ändern
1.  Öffne `app/frontend/ui_config.py`.
2.  Bearbeite das Dictionary `GRAPH_COLORS`.

```python
GRAPH_COLORS = {
    "project": "#FF4B4B",
    "risk": "#8B0000" # Neu
}
```

---

## 9. Tests & Debugging

**Unit Tests (Pytest):**
```bash
pytest tests/test_retriever_basic.py
pytest tests/test_chunking.py
```

**Pipeline Tests (Integration):**
```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
```

---

## 10. Troubleshooting & One-Liners

**DB komplett zurücksetzen (Vorsicht!):**
```bash
# --yes überspringt die Bestätigung
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
```

**Live-Logs sehen:**
```bash
journalctl -u mindnet-dev -f
journalctl -u mindnet-ui-dev -f
```

**"UnicodeDecodeError in .env":**
* **Ursache:** Umlaute oder Sonderzeichen in der `.env`.
* **Lösung:** Datei bereinigen (nur ASCII) und sicherstellen, dass UTF-8 ohne BOM genutzt wird.

**"Read timed out" im Frontend:**
* **Ursache:** Smart Edges brauchen länger als 60s.
* **Lösung:** `MINDNET_API_TIMEOUT=300.0` in `.env`.