Implement layered maps and context retrieval

README.md

@@ -4,7 +4,12 @@ Pi skill for hierarchical project analysis.
 
 ## What it does
 
-Generates `.pi-map.md` files throughout your project — one per directory — containing a dense, machine-readable summary of that directory's files, exports, dependencies, and architecture. This gives Pi agents instant project comprehension without reading every source file.
+Generates **paired** project-analysis artifacts throughout your project:
+
+- `.pi-map.index.md` — routing-first index for deciding what to open next
+- `.pi-map.md` — orientation-first rich map for understanding a directory
+
+This gives Pi agents fast navigation plus deeper architectural context without reading every source file up front.
 
 ## Quick Start
 
@@ -13,6 +18,56 @@ npm install -g pi-project-map
 project-map init
 ```
 
+## Agent operating model
+
+### Tier 0
+Always start with:
+- `Project Map Protocol`
+- root `.pi-map.index.md`
+
+### Tier 1
+Load likely relevant directory indexes first, then open the strongest-match rich maps.
+
+### Tier 2
+Read actual source, tests, config, and docs before editing or making exact runtime claims.
+
+**Trust boundary:** index routes, map orients, source decides.
+
+### Retrieval
+When you have a specific query (e.g. "authentication logic" or "routing metadata"):
+1. Run `project-map context <query>` or use the Pi tool `project_map_context`
+2. Read the returned **Context bundle** — it contains relevant indexes, maps, likely files, and symbols
+3. Always verify critical behavior from source before editing
+
+## Commands
+
+```bash
+project-map init
+project-map patch <file>
+project-map validate [--fix]
+project-map reinit
+project-map context <query>
+```
+
+### Context retrieval
+
+`project-map context <query>` searches the paired map/index artifacts and returns a compact markdown bundle with the most relevant directories, files, and symbols. No LLM call is needed — it uses deterministic metadata scoring.
+
+## Configuration
+
+Create `.pi-project-map.json` in the project root:
+
+```json
+{
+  "ignorePatterns": ["node_modules", ".git"],
+  "smallPackageThreshold": 10,
+  "contextBudget": 4000,
+  "autoInjectPrompt": true,
+  "tagCap": 8,
+  "workflowHintCap": 5
+}
+```
+
 ## Design
 
 See [design-doc.md](design-doc.md) for the full specification.