Erste Fassung: Claude-Werkzeuge aus dem Vault

.vault-tools (ohne trading-plattform-pruefung und watermarks-remover), .claude/agents, .claude/skills, .claude/workflows, .claude/settings.json. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-14 11:27:59 +02:00
commit fa1c26b407
@@ -0,0 +1,128 @@
+# Die Referenzschicht
+
+## Warum überhaupt ein Index
+
+Ein Agent, der eine Frage an einen Vault mit 500 Notizen stellt, hat drei
+Möglichkeiten: alles lesen (sprengt den Kontext), grep (findet Wortformen, aber
+nicht Bedeutung, und liefert Treffer ohne Einordnung), oder eine
+Zwischenschicht, die pro Notiz genau so viel weiß, dass sich entscheiden lässt,
+ob man sie aufmacht. Die dritte Variante ist der Index.
+
+Größenordnung: 500 Notizen à 800 Wörter sind rund 500.000 Token. Der Index
+derselben 500 Notizen liegt bei etwa 25.000 Token — und eine typische Abfrage
+gibt davon 10–40 Zeilen aus, also ein paar hundert Token. Deshalb: nie den Index
+komplett lesen, immer `vault_query.py` fragen.
+
+## Erzeugte Dateien
+
+### `_index/vault-index.json`
+Kompaktes JSON ohne Einrückung, Kurzschlüssel zur Platzersparnis:
+
+| Schlüssel | Bedeutung |
+|---|---|
+| `p` | Pfad relativ zum Vault |
+| `u` | uid |
+| `t` | type |
+| `s` | status |
+| `n` | Titel |
+| `m` | summary |
+| `g` | tags |
+| `r` | Projekt-Slug |
+| `c` / `d` | created / updated |
+| `h` | Überschriften (max. 12) |
+| `l` | ausgehende Links |
+| `w` | Wortzahl (bei Assets: Dateigröße) |
+
+Leere Felder fehlen ganz. Der `meta`-Block enthält Zählungen, Typverteilung,
+Statusverteilung, Top-Tags und die Zahl toter Links.
+
+Das Feld `h` ist der zweite Hebel nach `m`: Bei einer langen Notiz zeigen die
+Überschriften, welcher Abschnitt gebraucht wird — statt 3.000 Wörter zu lesen,
+liest man 300.
+
+### `_index/INDEX.md`
+Menschenlesbare Übersicht, nach Typ gruppiert, jede Zeile ein Wikilink plus
+Zusammenfassung. In Obsidian direkt navigierbar. Bei über 200 Notizen enthält
+die Datei selbst den Hinweis, sie nicht komplett zu lesen.
+
+### `_index/backlinks.json`
+`{ "pfad/zur/notiz.md": ["pfad/quelle1.md", …] }`. Basis für `--links-to` und
+die Waisen-Erkennung.
+
+## Wann neu bauen
+
+- nach dem Anlegen, Verschieben, Umbenennen oder Löschen von Notizen
+- nach Frontmatter-Änderungen
+- vor einer Arbeitssitzung, wenn zwischendurch in Obsidian gearbeitet wurde
+
+`vault_query.py` vergleicht die Änderungszeiten und warnt auf stderr, wenn
+Notizen neuer sind als der Index. Der Lauf über einige tausend Dateien dauert
+Sekunden, also im Zweifel neu bauen.
+
+Automatisieren geht per Git-Hook (`.git/hooks/pre-commit`) oder Cron:
+
+```bash
+python3 .claude/skills/obsidian-vault-navigator/scripts/build_index.py --vault . --quiet
+```
+
+## Abfrage-Rezepte
+
+```bash
+Q=".claude/skills/obsidian-vault-navigator/scripts/vault_query.py"
+
+# Womit habe ich mich zu Thema X beschäftigt?
+python3 $Q --text x
+
+# Laufende Code-Projekte, als fertige Wikilink-Liste für eine Antwort
+python3 $Q --type project-code --status active --format md
+
+# Alles zu einem Projekt, inklusive Unternotizen und Anhängen
+python3 $Q --project auth-service
+
+# Passendes Template-Projekt finden, ohne eines zu öffnen
+python3 $Q --type template-project
+
+# Was hat sich diese Woche getan?
+python3 $Q --since 7 --sort updated
+
+# Kandidaten fürs Archiv
+python3 $Q --status active --stale 180
+
+# Wer verweist auf diese Notiz?
+python3 $Q --links-to 30_Research/rate-limiting.md
+
+# Pflegeliste: Notizen ohne summary
+python3 $Q --no-summary --limit 100 --format paths
+
+# Struktur einer langen Notiz sehen, bevor man sie liest
+python3 $Q --text "kubernetes netzwerk" --format headings
+```
+
+Mehrere `--text` werden UND-verknüpft, mehrere `--type`/`--tag`/`--status`
+ODER-verknüpft (bei `--tag` müssen alle angegebenen Tags vorhanden sein).
+
+## Wenn der Index nichts findet
+
+1. Filter lockern — oft ist `--type` zu eng gesetzt.
+2. Anderes Wort probieren; der Index kennt nur Titel, Summary, Tags,
+   Überschriften und Pfad, keinen Fließtext.
+3. Erst dann Volltext: `grep -ril "begriff" --include="*.md" .`
+4. Findet grep etwas, das der Index nicht hatte, ist das ein Befund: Der Notiz
+   fehlt ein Tag oder eine bessere `summary`. Gleich nachziehen — der Index wird
+   dadurch mit jedem Miss besser.
+
+## Grenzen
+
+Der Index ist Metadaten, keine Semantik. Er findet nichts, was nirgends benannt
+ist, und er versteht keine Synonyme. Für semantische Suche im großen Vault gibt
+es lokale Werkzeuge (z. B. Obsidians eigene Suche mit Operatoren oder externe
+Embedding-Indizes) — die ersetzen diese Schicht nicht, sondern ergänzen sie: Der
+Index bleibt die billige erste Stufe.
+
+## Verhältnis zu Obsidian Bases
+
+Obsidian Bases (`.base`-Dateien) erzeugen Tabellen- und Kartenansichten aus
+Properties — dieselben Felder, die auch der Index nutzt. Wer im Obsidian-UI
+dieselben Übersichten will, legt Bases an; für den Agenten bleibt der
+JSON-Index der billigere Weg. Für die korrekte `.base`-Syntax den offiziellen
+Skill `obsidian-bases` verwenden.