docs: add AI agent codebase navigation guides

Add CLAUDE.md, AGENTS.md, and INDEX.md — all generated by the indxr
MCP tooling to give AI coding assistants a structured way to explore
the codebase without dumping entire files into context.

CLAUDE.md is the detailed version with token cost estimates and a
full tool reference. AGENTS.md is the condensed version. INDEX.md
is an auto-generated codebase index with file summaries and symbol
maps.

While at it, add .indxr-cache/ to .gitignore because nobody needs
that in the repo.

.gitignore

@@ -1 +1,2 @@
 /target
+.indxr-cache/

AGENTS.md

@@ -0,0 +1,27 @@
+# Codebase Navigation — Use indxr MCP tools
+
+An MCP server called `indxr` is available. Always use indxr tools before reading full files.
+
+## Exploration workflow
+1. `search_relevant` — find files/symbols by concept or partial name
+2. `get_tree` — see directory/file layout
+3. `get_file_summary` / `batch_file_summaries` — understand files without reading them
+4. `explain_symbol` — get signature, docs, and relationships for a symbol
+5. `get_public_api` — public API surface of a file or module
+6. `get_callers` / `get_related_tests` — find references and tests
+7. `get_token_estimate` — check cost before deciding to read a full file
+8. `read_source` — read just one function/struct by name
+9. Read (full file) — ONLY when editing or need exact formatting
+
+## When to read full files instead
+- You need to edit a file
+- You need exact formatting/whitespace
+- The file is not source code (e.g., config files, documentation)
+
+## Do NOT
+- Read full source files just to understand what's in them
+- Dump all files into context
+- Use `git diff` when `get_diff_summary` would suffice
+
+## After making code changes
+Run `regenerate_index` to keep the index current.

CLAUDE.md

@@ -0,0 +1,66 @@
+# wrkflw
+
+## Codebase Navigation — MUST USE indxr MCP tools
+
+An MCP server called `indxr` is available. **Always use indxr tools before the Read tool.** Do NOT read full source files as a first step — use the MCP tools to explore, then read only what you need.
+
+### Token savings reference
+
+| Action | Approx tokens | When to use |
+|--------|--------------|-------------|
+| `get_tree` | ~200-400 | First: understand directory layout |
+| `get_file_summary` | ~200-400 | Understand a file without reading it |
+| `batch_file_summaries` | ~400-1200 | Summarize multiple files in one call |
+| `get_file_context` | ~400-600 | Understand dependencies and reverse deps |
+| `lookup_symbol` | ~100-200 | Find a specific function/type across codebase |
+| `search_signatures` | ~100-300 | Find functions by signature pattern |
+| `search_relevant` | ~200-400 | Find files/symbols by concept or partial name (supports `kind` filter) |
+| `explain_symbol` | ~100-300 | Everything to USE a symbol without reading its body |
+| `get_public_api` | ~200-500 | Public API surface of a file or module |
+| `get_callers` | ~100-300 | Who references this symbol (imports + signatures) |
+| `get_related_tests` | ~100-200 | Find tests for a symbol by naming convention |
+| `get_diff_summary` | ~200-500 | Structural changes since a git ref (vs reading raw diffs) |
+| `get_hotspots` | ~200-500 | Most complex functions ranked by composite score |
+| `get_health` | ~200-400 | Codebase health summary with aggregate complexity metrics |
+| `get_type_flow` | ~200-500 | Track which functions produce/consume a type across the codebase |
+| `read_source` (symbol) | ~50-300 | Read one function/struct. Supports `symbols` array and `collapse`. |
+| `get_token_estimate` | ~100 | Check cost before reading. Supports `directory`/`glob`. |
+| `Read` (full file) | **500-10000+** | ONLY when editing or need exact formatting |
+
+### Exploration workflow (follow this order)
+
+1. `search_relevant` — find files/symbols related to your task by concept, partial name, or type pattern. **Start here when you know what you're looking for but not where it is.**
+2. `get_tree` — see directory/file layout. Use `path` param to scope to a subtree.
+3. `get_file_summary` — get a complete overview of any file without reading it. Use `batch_file_summaries` for multiple files.
+4. `get_file_context` — understand a file's reverse dependencies and related files.
+5. `lookup_symbol` — find declarations by name across all indexed files.
+6. `explain_symbol` — get full interface details for a symbol without reading its body.
+7. `search_signatures` — find functions/methods by signature substring.
+8. `get_callers` — find who references a symbol.
+9. `get_token_estimate` — before deciding to `Read` a file, check how many tokens it costs.
+10. `read_source` — read source code by symbol name or line range. Use `symbols` array to read multiple in one call.
+11. `get_public_api` — get only public declarations with signatures for a file or directory.
+12. `get_related_tests` — find test functions for a symbol.
+13. `list_declarations` — list all declarations in a file.
+14. `get_imports` — get import statements for a file.
+15. `get_stats` — codebase stats: file count, line count, language breakdown.
+16. `get_diff_summary` — get structural changes since a git ref.
+17. `get_hotspots` — get the most complex functions ranked by composite score.
+18. `get_health` — get codebase health summary: aggregate complexity, documentation coverage, test ratio.
+19. `get_type_flow` — track where a type flows across function boundaries. Shows producers and consumers.
+20. `regenerate_index` — re-index after code changes.
+
+### When to use the Read tool instead
+- You need to **edit** a file (Read is required before Edit)
+- You need exact formatting/whitespace that `read_source` doesn't preserve
+- The file is not a source file (e.g., config files, documentation)
+
+### DO NOT
+- Read full source files just to understand what's in them — use `get_file_summary`
+- Read full source files to review code — use `get_file_summary` to triage, then `read_source` on specific symbols
+- Dump all files into context — use MCP tools to be surgical
+- Read a file without first checking `get_token_estimate` if you're unsure about its size
+- Use `git diff` to understand changes — use `get_diff_summary` instead
+
+### After making code changes
+Run `regenerate_index` to keep INDEX.md current.