# Feature: Repo Map Injection (Phase 1 Step 2.5)

**Gated by `prefs.global.repoMap.enabled`** (default: `false`). Pattern source: <https://aider.chat/docs/repomap.html>.

Before launching Explore agents, run the deterministic repo map renderer and inject the result into each Explore prompt as `${REPO_MAP}`. This gives every explorer a token-budgeted overview of the most-referenced files in the repo  -  ranked via cross-file declaration references with TF-IDF-style credit splitting so universally-shared helper names (`pass`, `fail`, `init`) don't dominate.

```bash
REPO_MAP=""
if [ "$(jq -r '.global.repoMap.enabled // false' "$PREFS")" = "true" ]; then
  BUDGET=$(jq -r '.global.repoMap.tokenBudget // 1500' "$PREFS")
  TOP=$(jq -r '.global.repoMap.topFiles // 25' "$PREFS")
  INCLUDE=$(jq -r '.global.repoMap.include // empty' "$PREFS")
  EXCLUDE=$(jq -r '.global.repoMap.exclude // empty' "$PREFS")
  args=(--root "$WORKTREE" --budget "$BUDGET" --top "$TOP" --format md)
  [ -n "$INCLUDE" ] && args+=(--include "$INCLUDE")
  [ -n "$EXCLUDE" ] && args+=(--exclude "$EXCLUDE")
  REPO_MAP=$(node $HOME/.claude/scripts/repo-map.mjs "${args[@]}" 2>/dev/null || echo "")
fi
```

## Properties

- **Deterministic**  -  same worktree state → same map. No embeddings, no network. Sub-second on monorepos.
- **Advisory**  -  Explore agents may ignore the map if they have stronger signals (Phase 0 knowledge cache, explicit user context). Never gates the pipeline.
- **Truncation-safe**  -  output is capped at `tokenBudget`; the script falls back to "no files extracted within budget" rather than over-spending.
- **Cost ledger**  -  emit `phase-1.repo_map_emitted bytes=$(wc -c <<<"$REPO_MAP") budget=$BUDGET` so Phase 7 cost summary can show the size injected.

## When to enable

Large repos (>200 source files) where Explore otherwise spends multiple rounds finding the right starting files. Skip on small repos  -  the overhead exceeds the gain.