# Proposal: Map Context Retrieval

## Status

| Field | Value |
|---|---|
| Phase | **Proposal** |
| Based on | Follow-up to `layered-map-protocol` |
| Next | Spec |

## Problem

After the layered map protocol lands, the agent will know it should load root protocol + root index first, then route through per-directory indexes and rich maps. But the repo will still lack an ergonomic retrieval primitive that can turn a natural-language task into a compact context bundle.

Without that helper, the agent still has to manually inspect directory indexes, rank candidate areas, and expand to rich maps/files. That weakens the value of the new routing layer.

## Proposed change

Add a retrieval tool and command shape:

```bash
project-map context "<user task>"
```

The first-class surface should be a Pi tool. CLI support can follow the same shape.

The retrieval result should return a compact context bundle containing:
- relevant indexes,
- strongest-match rich maps,
- likely source files,
- relevant symbols when useful,
- short instructions on what to read next.

This remains a local metadata-driven retrieval feature, not a vector-store or Engram-backed memory system.
## In scope

- [ ] Add Pi tool support for `project-map context <query>`
- [ ] Add CLI support using the same shape after the tool contract is stable
- [ ] Rank results using paired index/map metadata from the layered protocol
- [ ] Return a compact, markdown-first, agent-friendly context bundle
- [ ] Document recommended usage from prompts and docs
## Out of scope

- [ ] Full semantic search across arbitrary source contents
- [ ] Replacing source verification with map-based answers
- [ ] Building a heavyweight external indexer or vector database

## Success criteria

- [ ] A natural-language task can resolve to likely indexes/maps/files/symbols without manual repo scanning
- [ ] Output is compact enough to inject directly into the next step
- [ ] Retrieval builds on generated paired metadata rather than bypassing it
- [ ] The first version is tool-first and markdown-first