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