mindnet/docs/Handbuch.md

# 📘 Mindnet Skript-Handbuch (aktualisiert)

Dieses Handbuch dokumentiert die Skripte und Tests für das Projekt **mindnet Wissensnetzwerk**.  
Es beschreibt Zweck, Parameter, typische Aufrufe sowie aktuelle Verhaltensweisen (Hash-Modi, Parser-Robustheit, `window`/`text`-Trennung in Chunks, Export-Fixes).  
Alle Beispiele sind so formatiert, dass sie direkt kopierbar sind. **Code/CLI-Beispiele sind eingerückt**, damit die Markdown-Darstellung nicht abbricht.

---

## 0) Umgebung & Konfiguration

**Wichtige ENV-Variablen**

- `QDRANT_URL` – z. B. `http://localhost:6333`  
- `QDRANT_API_KEY` – API-Key (falls aktiviert)  
- `COLLECTION_PREFIX` – Prefix der drei Collections, Standard: `mindnet` → `mindnet_notes`, `mindnet_chunks`, `mindnet_edges`  
- `VECTOR_DIM` – Embedding-Dimension (Chunks), Standard: `384`

**Hash-Vergleich & Änderungs­erkennung**

- `MINDNET_HASH_COMPARE` – steuert, **welcher Anteil** für „changed“ verglichen wird  
  Werte: `Body` (Standard), `Frontmatter`, `Full`
- `MINDNET_HASH_SOURCE` – Quelle: `parsed` (Standard), `raw`, `file`
- `MINDNET_HASH_NORMALIZE` – Normalisierung: `canonical` (Standard) oder `none`

**Beispiel (nur Body berücksichtigen, kanonisch, geparst):**

    export MINDNET_HASH_COMPARE=Body
    export MINDNET_HASH_SOURCE=parsed
    export MINDNET_HASH_NORMALIZE=canonical
    source .venv/bin/activate

**Baseline-Signaturen (mehrere Modi):**  
Der Importer kann **Signaturen aller Modi** (Body/Frontmatter/Full) vorhalten, damit spätere Moduswechsel deterministisch sind (keine „Mass-Changes“). Siehe `--baseline-modes` unter **Importer**.

---

## 1) Vault anlegen (für Tests)

### `scripts/make_test_vault.py`

**Zweck:**  
Erstellt einen kleinen, nachvollziehbaren Test-Vault mit Markdown-Dateien.  
Szenarien: offene Links, nachträgliche Anlage fehlender Notes, geänderte Chunk-Grenzen.

**Parameter:**
- `--out PATH` : Zielverzeichnis (Default: `./test_vault`)  
- `--force` : Existierenden Ordner löschen und neu anlegen  
- `--with-missing` : Optional – auch die `missing-note` gleich anlegen

**Hinweise für Tests**
1. Erster Import (dry-run oder `--apply`): Es gibt einen „leeren“ Link `[[missing-note]]`.  
2. Lege danach eine Datei für „missing-note“ an (mit gleicher `id` im YAML) und importiere erneut:  
   → Erwartung: Edges für ehemals leeren Link werden korrekt nachgezogen (`references` + `backlink`).  
3. Ändere den Body von `exp-one.md` so, dass andere Chunk-Grenzen entstehen und importiere erneut:  
   → Erwartung: Chunks/Edges/Note werden für betroffene Noten aktualisiert.

**Kompatibilität:**  
- `note.schema.json`: `created`/`updated` sind Strings.

**Beispiele:**

    python3 -m scripts.make_test_vault --out ./test_vault --force
    python3 -m scripts.make_test_vault --out ./test_vault --force --with-missing

---

## 2) Import in Qdrant

### `scripts/import_markdown.py`

**Zweck:**  
Importiert Notes/Chunks/Edges aus einem Vault nach Qdrant.
- validiert Frontmatter
- chunked Inhalte + Embeddings
- erzeugt Edges (`references`, `references_at`, `backlink`, `next`, `prev`, `belongs_to`)
- erkennt geänderte Dateien **modusgesteuert** (Body/Frontmatter/Full)
- optional: Purge der alten Chunks/Edges pro Note

**Parameter:**
- `--vault PATH` : (Pflicht) Vault-Verzeichnis  
- `--apply` : Änderungen wirklich durchführen (ohne: Dry-Run)  
- `--purge-before-upsert` : Vor Upsert alte Chunks/Edges **nur der geänderten Notes** löschen  
- `--prefix STR` : überschreibt `COLLECTION_PREFIX`  
- `--note-id ID` : nur eine bestimmte Note importieren  
- `--note-scope-refs` : zusätzlich **note-weite** `references` erzeugen (nicht nur chunk-weise)  
- `--baseline-modes` : berechne & speichere Hash-Signaturen für **alle** Modi (`Body`, `Frontmatter`, `Full`) als Baseline

**Erwartetes Verhalten:**
- Unveränderte Notes → `"changed": false`, Entscheidung: `apply-skip-unchanged` (bei `--apply`)
- Geänderte Notes → `"changed": true` (abhängig von `MINDNET_HASH_COMPARE`)
- Idempotenz: mehrfacher Lauf ohne Änderungen erzeugt **keine** neuen Punkte
- Baseline: Bei `--baseline-modes` erscheinen Felder wie `hash_signature`, `hash_fulltext`, ggf. `hash_frontmatter` und `needs_baseline_for_mode: false` bei Folgeläufen.

**Beispiele:**

    # Dry-Run (zeigt Änderungen, schreibt NICHT)
    python3 -m scripts.import_markdown --vault ./vault --prefix mindnet

    # Apply + gezielte Vorreinigung pro geänderter Note
    python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply --purge-before-upsert

    # Baseline-Signaturen aller Modi vorhalten
    python3 -m scripts.import_markdown --vault ./vault --apply --baseline-modes

**Hash-Modi in der Praxis:**
- `MINDNET_HASH_COMPARE=Body`  → Änderungen im Body werden erkannt; reine Frontmatter-Änderungen bleiben **ohne Effekt**.
- `MINDNET_HASH_COMPARE=Frontmatter` → nur Frontmatter maßgeblich.
- `MINDNET_HASH_COMPARE=Full` → beide Anteile zählen.

---

## 3) Konsistenzprüfungen

### `scripts/audit_vault_vs_qdrant.py`

**Zweck:**  
Vergleicht Vault-Inhalte mit Qdrant.
- Zählt Notes/Chunks/Edges
- Verifiziert Anzahl Wikilinks vs. Edges
- Meldet Deltas (z. B. `references` im Vault vs. in Qdrant)

**Parameter:**
- `--vault PATH` : Vault-Verzeichnis  
- `--prefix STR` : Prefix für Qdrant-Collections (Default: `mindnet`)

**Beispiel:**

    python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet

### `scripts/validate_edges.py`

**Zweck:**  
Prüft die Edges-Collection in Qdrant.
- Zählt Edges pro Typ (`references`, `references_at`, `backlink`, `next`, `prev`, `belongs_to`)
- Kontrolliert Invarianten (z. B. jede `references` hat einen `backlink`)
- Listet `unresolved` Edges auf

**Parameter:**
- `--prefix STR` : Prefix für Qdrant-Collections  
- `--details` : Detailausgabe mit Beispielen

**Beispiel:**

    python3 -m scripts.validate_edges --prefix mindnet --details

---

## 4) Export Qdrant → Markdown (Vault)

### `scripts/export_markdown.py`

**Zweck:**  
Exportiert Notes + rekonstruierten Body in einen Zielordner.
- Pfade werden **relativ** aus `note.payload.path` abgeleitet (führende `/` entfernt, Backslashes → Slashes; Unicode-NFC empfohlen)
- **Body-Rekonstruktion** priorisiert:
  1. `fulltext` (falls in Note-Payload vorhanden)  
  2. sonst **Chunks**: Sortierung `seq` → `chunk_index` → Nummer in `chunk_id`; **nur `text`** (Overlap bereits entfernt)
- `--prefix` (CLI) wird unterstützt (oder ENV `COLLECTION_PREFIX`)

**Parameter:**
- `--out PATH` : Ziel-Root (muss existieren)  
- `--overwrite` : vorhandene Dateien überschreiben  
- `--note-id ID` : nur eine bestimmte Note exportieren  
- `--prefix STR` : überschreibt `COLLECTION_PREFIX`  
- `--include-edges {none,footer,yaml}` *(optional, falls aktiviert)*: Edges als YAML-Liste im Frontmatter oder im Footer beilegen

**Beispiele:**

    export COLLECTION_PREFIX="mindnet"
    python3 -m scripts.export_markdown --out ./_exportVault

    # Nur eine bestimmte Note:
    python3 -m scripts.export_markdown --out ./_exportVault --note-id 20250821-architektur-ki-trainerassistent-761cfe

    # Existierende Dateien überschreiben:
    python3 -m scripts.export_markdown --out ./_exportVault --overwrite

---

## 5) Qdrant zurücksetzen

### `scripts/reset_qdrant.py`

**Zweck:**  
Setzt die Qdrant-Collections zurück.
- `wipe`: löscht Collections komplett (inkl. Schema)
- `truncate`: löscht nur Inhalte, behält Collections
- `truncate-edges`: löscht nur Punkte in `*_edges`

**Parameter:**
- `--mode {wipe,truncate,truncate-edges}`
- `--prefix STR` : Prefix der Collections (Default: `mindnet`)
- `--yes` : Automatische Bestätigung
- `--dry-run` : Nur anzeigen, nicht ausführen

**Beispiele:**

    python3 -m scripts.reset_qdrant --mode truncate-edges --prefix mindnet
    python3 -m scripts.reset_qdrant --mode truncate --prefix mindnet --yes
    python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes

---

## 6) Diagnose & Tools

### `scripts/diagnose_changed.py`

**Zweck:**  
Prüft, ob Datei-Hashes (`sha256`) mit gespeicherten `hash_*` in Qdrant übereinstimmen.  
Hilft, wenn der Importer zu viele Dateien als „changed“ erkennt oder Moduswechsel geplant sind.

**Parameter:**
- `--vault PATH` : Vault-Verzeichnis  
- `--prefix STR` : Prefix (Default: `mindnet`)  
- `--note-id ID` : Nur bestimmte Note prüfen  
- `--all` : Alle Notes prüfen

**Beispiel:**

    python3 -m scripts.diagnose_changed --vault ./vault --prefix mindnet --all

### `scripts/resolve_unresolved_references.py`

**Zweck:**  
Prüft offene Wikilinks (`status=unresolved`) und fügt Edges nach, wenn inzwischen passende Notizen existieren.  
Ersetzt `unresolved` durch gültige `references`/`backlink`.

**Parameter:**
- `--prefix STR` : Prefix für Qdrant-Collections  
- `--apply` : Änderungen wirklich ausführen (sonst nur Vorschau)

**Beispiele:**

    python3 -m scripts.resolve_unresolved_references --prefix mindnet
    python3 -m scripts.resolve_unresolved_references --prefix mindnet --apply

---

## 7) Parser-Verhalten (robust & abwärtskompatibel)

- Der Parser liest Markdown **fehlertolerant** (UTF-8 mit Fallbacks), extrahiert YAML-Frontmatter und Body.  
- Keine harten Abhängigkeiten von alten Regex-Symbolen (`FRONTMATTER_RE` entfällt zugunsten interner Marker).  
- `read_markdown(path)` gibt `(frontmatter_dict, body_str)` zurück.  
- **Sonderfälle aus Fremd-Tools** (z. B. Silverbullet-Dateien wie `CONFIG.md`, `index.md`) werden **nicht importiert**, sofern sie nicht zum Vault gehören.

---

## 8) Chunk-Payload (Fenster vs. Kern)

- **`window`** = kontextualisierter Fenster-Text (mit linkem Overlap)  
- **`text`** = **Kerntext** ohne das vom vorherigen Chunk übernommene Overlap  
- Felder: `start`, `end`, `overlap_left`, `overlap_right`, `chunk_index`, `seq`, `path`, `section_title`, `section_path`, `token_count` (falls vorhanden)  
- **Fallback (synthetisch):** Falls der Chunker **keinen** Overlap-Fenstertext liefert, erzeugt die Payload-Schicht Fenster mit typgerechtem Overlap aus `chunk_config.get_sizes(type)['overlap']` (unterer Wert).  
- **Edges** werden aus `window` abgeleitet (um Links an Chunk-Grenzen nicht zu verlieren); der **Export** rekonstruiert den Body aus `text` (Overlap-frei).

---

## 9) Edge-Modell & IDs

- Collections:  
  `*_notes` (optional Vektor / Nullvektor), `*_chunks` (384-d Embeddings), `*_edges` (1-d Dummy-Vektor)
- **Deterministische IDs** (UUIDv5 / stabile Keys):  
  - `note_id` stabil aus Frontmatter/Slug  
  - `chunk_id` i. d. R. `note_id#<n>`  
  - `edge_id` stabil aus `(kind, source_id, target_id, seq)`
- Kantenarten: `references`, `references_at`, `backlink`, `next`, `prev`, `belongs_to`
- `unresolved` wird gekennzeichnet und kann per Resolver später aufgelöst werden.

---

## 10) Tests & Qualitätssicherung

**Tests unter `tests/`**

- `check_chunks_window_vs_text.py` – vergleicht je Chunk `window` vs. `text`, schätzt Overlap  
- `compare_vaults.py` – rekursiver Vault-Vergleich (Body/Frontmatter/All, Key: auto/id/title/filename), Unicode-NFC-robust  
- `verify_chunks_integrity.py` – prüft, ob Rekonstruktion aus Chunks (`text`) zu `fulltext` bzw. zum Vault-Body passt  
- `list_md_seen_by_importer.py` – zeigt, welche `.md` der Importer sieht (inkl. Gründe/Filter)  
- `inspect_one_note.py` – Parser-Diagnose für eine konkrete Datei  
- `run_e2e_roundtrip.sh` – End-to-End: Reset → Import → Audit → (optional) Hash-Reporter → Export → Vergleich

**Typische Aufrufe:**

    # Overlap-Qualität (Fenster vs. Kern)
    python3 tests/check_chunks_window_vs_text.py --prefix "$COLLECTION_PREFIX"

    # Roundtrip-Vergleich (rekursiv)
    python3 tests/compare_vaults.py --src ./vault --dst ./_exportVault --focus body

    # Chunks-Rekonstruktion (gegen Vault-Body)
    python3 tests/verify_chunks_integrity.py --prefix "$COLLECTION_PREFIX" --vault ./vault

---

## 11) Typische Workflows

**A) Clean-Start mit Test-Vault**

    python3 -m scripts.make_test_vault --out ./test_vault --force
    python3 -m scripts.reset_qdrant --mode truncate --prefix mindnet --yes
    python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet
    python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet --apply --purge-before-upsert
    python3 -m scripts.audit_vault_vs_qdrant --vault ./test_vault --prefix mindnet
    python3 -m scripts.validate_edges --prefix mindnet --details
    export COLLECTION_PREFIX="mindnet"
    python3 -m scripts.export_markdown --out ./_exportVault

**B) Änderungs-Propagation & Idempotenz**

    python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet
    python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet --apply --purge-before-upsert
    python3 -m scripts.audit_vault_vs_qdrant --vault ./test_vault --prefix mindnet
    python3 -m scripts.validate_edges --prefix mindnet --details
    python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet

**C) Unresolved Links lösen**

    python3 -m scripts.import_markdown --vault ./test_vault --apply --prefix mindnet
    python3 -m scripts.resolve_unresolved_references --prefix mindnet --apply
    python3 -m scripts.validate_edges --prefix mindnet --details

**D) Export & Roundtrip (Produkt-Vault)**

    export COLLECTION_PREFIX="mindnet"
    python3 -m scripts.import_markdown --vault ./vault --apply --purge-before-upsert --prefix "$COLLECTION_PREFIX"
    python3 -m scripts.export_markdown --out ./_exportVault --prefix "$COLLECTION_PREFIX"
    python3 tests/compare_vaults.py --src ./vault --dst ./_exportVault --focus body

---

## 12) Troubleshooting (kurz)

- **Importer markiert alle als changed (Moduswechsel):**  
  → `--baseline-modes` einmalig laufen lassen; sicherstellen: `MINDNET_HASH_COMPARE` passt zum Ziel.
- **Edges verschwinden / nur 1 Edge sichtbar:**  
  → `app/core/qdrant_points.py` muss Edge-Payload normalisieren (Schema Alt/Neu) und `edge_id` eindeutig bilden.
- **Export ohne Body / falsches Zielverzeichnis:**  
  → Exporter nutzt relativierte Pfade und rekonstruiert Body aus `fulltext` oder Chunks (`text`). ENV/CLI `--prefix` beachten.
- **Parser-Fehler (UTF-8):**  
  → Neuer Parser arbeitet mit Fallbacks; mit `tests/inspect_one_note.py` prüfen, was ankommt.
- **„Fehlende“ Dateien im Vergleich:**  
  → Prüfe, ob Dateien **wirklich zum Vault gehören** (z. B. Silverbullet-Artefakte `CONFIG.md`, `index.md` ausblenden).

---

## 13) Hinweise zu Silverbullet-Dateien

- Dateien wie `CONFIG.md` oder `index.md`, die **nicht** zum inhaltlichen Vault gehören, werden **nicht importiert** und erscheinen daher nicht im Export-Roundtrip.  
- Diese Dateien bitte vom produktiven Vault trennen oder im Vergleich (`tests/compare_vaults.py