mindnet/docs/Handbuch.md

# 📘 Mindnet Skript-Handbuch

Dieses Handbuch dokumentiert die implementierten Skripte für das Projekt **mindnet Wissensnetzwerk**.  
Es beschreibt Zweck, Parameter und typische Aufrufe. Alle Beispiele sind geprüft und lauffähig.  

Alle Skripte liegen in `~/mindnet/scripts/`.  
Ausführung erfolgt **im aktivierten venv**:

    cd ~/mindnet
    source .venv/bin/activate

---

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

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

Kompatibel mit:
- note.schema.json: 'created'/'updated' müssen strings sein. (Wichtig!)

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

### `import_markdown.py`

**Zweck:**  
Importiert Notes/Chunks/Edges aus einem Vault nach Qdrant.  
- prüft Frontmatter  
- chunked Inhalte + Embeddings  
- erzeugt Edges (`references`, `references_at`, `backlink`)  
- erkennt geänderte Dateien automatisch  
- optional: Purge der alten Chunks/Edges pro Note

**Parameter:**
- `--vault PATH` : (Pflicht) Vault-Verzeichnis  
- `--apply` : Änderungen wirklich durchführen (sonst Dry-Run)  
- `--purge-before-upsert` : Vor Upsert alte Chunks/Edges **nur der geänderten Notes** löschen  
- `--note-id ID` : Nur eine bestimmte Note importieren  

**Beispiele:**

    python3 -m scripts.import_markdown --vault ./vault
    python3 -m scripts.import_markdown --vault ./vault --apply
    python3 -m scripts.import_markdown --vault ./vault --apply --purge-before-upsert

---

## 3. Konsistenzprüfungen

### `audit_vault_vs_qdrant.py`

**Zweck:**  
Vergleicht Vault-Inhalte mit Qdrant.  
- Zählt Notes/Chunks/Edges  
- Verifiziert Anzahl Wikilinks vs. Edges  
- Meldet Mismatches pro Note

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

---

### `validate_edges.py`

**Zweck:**  
Prüft die Edges-Collection in Qdrant.  
- Zählt Edges pro Typ  
- Kontrolliert Invarianten (z. B. jede Reference hat 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. Qdrant zurücksetzen

### `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  

**Parameter:**
- `--mode {wipe,truncate}` : Aktion  
- `--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 --prefix mindnet --yes
    python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes

---

## 5. Diagnose

### `diagnose_changed.py`

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

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

---

## 6. Unresolved Links nachträglich auflösen

### `resolve_unresolved_references.py`

**Zweck:**  
Prüft offene Wikilinks (`status=unresolved`) und fügt Edges nach, wenn inzwischen passende Notizen existieren.

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

---

# ✅ Typische Workflows

### A) Vault neu importieren

    python3 -m scripts.reset_qdrant --mode truncate --prefix mindnet --yes
    python3 -m scripts.import_markdown --vault ./vault --apply
    python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet

### B) Änderungen einspielen (mit Purge für geänderte Notes)

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

### C) Unresolved Links nachziehen

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

### D) Test-Vault Szenario durchspielen

    python3 -m scripts.make_test_vault --out ./test_vault --force
    python3 -m scripts.import_markdown --vault ./test_vault --apply
    python3 -m scripts.audit_vault_vs_qdrant --vault ./test_vault --prefix mindnet