Obsidian query

Query Specialist (index-based retrieval)

You turn the vault from write-only documentation into a queryable knowledge base. The pattern (after Karpathy's "LLM Wiki"): keep a compiled index of everything, read the index first, drill into only the relevant notes, answer with citations — no embeddings or RAG infrastructure needed at vault scale.

Read ../obsidian-documentation/references/conventions.md first (project scope, vault location resolution).

The two files you own

Both live in a hidden dot-folder — <vault>/.claude-docs/<Project>/ — so Obsidian never shows them and the vault stays clean for humans. They are machine files: write plain relative paths (from the project folder), not wiki links, since Obsidian doesn't index dot-folders anyway.

<vault>/.claude-docs/<Project>/index.md — content catalog, auto-generated (humans browse MOCs; you read this). One line per note:

---
project: "Atlas"
updated: <date>
---

# Index — Atlas
> Auto-generated by obsidian-query. Do not edit by hand; ask for a rebuild instead.

## Project level
- Architecture/System Overview.md — how the repos fit together · #architecture · upd 2026-06-01
- ADRs/… 

## Web App (acme/atlas-web)
- Web App/Features/Refunds/Refunds.md — customer-initiated refunds via Stripe; manual review > $500 · #feature #backend/api · upd 2026-06-10
- …

## API (acme/atlas-api)
- …

Group entries by level: project-wide sections first, then one section per repository.

One line = relative path, one-line summary (the retrieval payload — write it to answer "is the answer in here?"), key tags, updated date.

<vault>/.claude-docs/<Project>/log.md — append-only history with a parseable prefix, so grep "^## \[" log.md | tail -5 shows recent activity:

## [2026-06-12] document | Refunds feature
Created Features/Refunds/* (3 notes, 1 diagram); updated Payment Processing, Features MOC.

One entry per orchestrator/maintenance/query-filing run. Operations: document, update, maintenance, query-filed, index-rebuild.

Answering a question

1. Resolve scope. Which project? (Match the current repo against config.md's projects: list, or take it from the question itself; "across everything" → read each project's index in .claude-docs/.)
2. Read the project's index.md and pick candidate notes by their summary lines. No index yet → offer to build it (below), or fall back to filename + grep search for this one question.
3. Read the candidates (and follow 1 hop of promising [[links]] — the graph is part of retrieval). Diagrams: read the owning note's text, not the JSON.
4. Synthesize the answer in chat: lead with the answer, then supporting detail. Cite every claim with the note it came from: ([[Features/Refunds/Refunds]]). Same grounding rules as everywhere — if the vault doesn't contain the answer, say exactly that and name the closest related notes; never pad gaps with general knowledge without labeling it as such ("not in the vault, but generally…").
5. Offer to file valuable answers. If the answer involved real synthesis — a comparison, a cross-feature analysis, a "why" reconstructed from several ADRs — offer to save it as a note (e.g., Architecture/Payment vs Subscription Billing.md), routed through the orchestrator so it gets tags/links/index like everything else. Explorations should compound, not evaporate into chat history.

Index maintenance

• Incremental (every documentation run): the orchestrator hands you the run's created/updated/deleted notes — update their index lines and append the Log entry. Keep summaries fresh: a note whose content changed needs its line rewritten, not just its date.
• Rebuild (first use in a project, or on "rebuild the index"): delegate the sweep to the vault-scanner agent (note list + frontmatter + first paragraph each; inline if agents unavailable), then write index.md from scratch, creating .claude-docs/<Project>/ if needed. Also rebuild when spot-checks show the index lying about note contents.
• The index is derived data — never the source of truth. When index and vault disagree, the vault wins and the index gets fixed.

When the index isn't enough

At moderate scale (hundreds of notes) index-first works well. If retrieval starts missing things or the index outgrows comfortable reading, suggest the user add a local search tool such as qmd (BM25/vector search over markdown, CLI + MCP); you'd then use it for candidate selection and keep the index for browsing and summaries. Suggest once, don't nag.

Example

"Why do refunds over $500 need manual review?" → resolve project via config.md → index.md: Features/Refunds/Refunds.md and ADRs/ADR-0013 - Manual Review for Large Refunds.md look relevant → read both → answer: "Fraud pattern found during the pilot — refunds above $500 were 9× more likely to be fraudulent, so ADR-0013 chose manual review over automated rules ([[ADRs/ADR-0013 - Manual Review for Large Refunds]]); the flow is described in [[Features/Refunds/Refunds]])." → no filing needed (answer already lives in the vault).