From bf2149bbeb0cebf276df4dd15112ab266a31a06c Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Sun, 7 Sep 2025 07:46:39 +0200
Subject: [PATCH] =?UTF-8?q?docs/Handbuch.md=20hinzugef=C3=BCgt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/Handbuch.md | 180 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 180 insertions(+)
 create mode 100644 docs/Handbuch.md

diff --git a/docs/Handbuch.md b/docs/Handbuch.md
new file mode 100644
index 0000000..cadb207
--- /dev/null
+++ b/docs/Handbuch.md
@@ -0,0 +1,180 @@
+# 📘 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  
+
+**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