nav-retrieval

name	nav-retrieval
description	Use when navigating this repo's code or Mind — find a definition/usage/file, trace an import, locate which note/decision explains something. Reach here BEFORE reflexive grep+Read.

Navigating with ctx_search (default retrieval)

Default to ctx_search (context-mode MCP tool) — it returns the relevant slice, far cheaper than grep+read-whole-file at equal correctness. The index (code + this repo's Mind) is kept fresh automatically by the SessionStart hook (scripts/nav-refresh-index.mjs).

Just call ctx_search with NO project param — it defaults to this repo (cwd), which is exactly where both buckets are indexed. Do NOT pass project: global or a .navidx-* path — those resolve to a different/empty store and return "Knowledge base is empty". Results are tagged Source: code:… or Source: mind:…; optionally narrow with source: code / source: mind.

Route by intent

Intent	Tool
Known file path	Read directly — no search
Exact symbol ("where is X defined / who calls X")	lsp — semantic, exact, cheap
Broad ("where is X / which note explains Y / find the invariant / which spec")	ctx_search
ctx_search empty/wrong, or exhaustive matches needed	grep + Read fallback
Reading a known file / git / listing	rtk read / rtk git / rtk ls (token-compressed)

Per-bucket mode

Mind (kryscar-mind/) — Source: mind:… hits; the snippet captures the zone/decision summary inline, usually enough — no follow-up Read for orientation.

Code (src/) — Source: code:… hits; use ctx_search to RANK, then Read the top ~3 whole hit files (snippets alone miss the answer span; parse the Source: paths and Read those files whole).

Rules

• Query with distinctive content terms, not whole questions ("pending clips sidecar", not "which note documents the pending clips sidecar").
• Retrieval is lazy + per-question — reach for it freely; NEVER preload the whole Mind or code tree (that re-pays the saved tokens).
• If results look stale: node scripts/nav-refresh-index.mjs --force then retry.