docs(prompt): align prompt injection guidance and runtime copy

README.md

@@ -33,12 +33,76 @@ Read actual source, tests, config, and docs before editing or making exact runti
 
 **Trust boundary:** index routes, map orients, source decides.
 
-### Retrieval
+## Prompt Injection Policy
+
+The Pi extension can automatically inject lightweight project-map guidance into the agent context according to the configured `promptInjectionMode`.
+
+### Before init
+When no `.pi-map.md` / `.pi-map.index.md` artifacts exist, only a visible startup hint is injected. It tells the agent that the project-map extension is active and to run `project_map_init`. No synthetic or fake map content is ever injected before real artifacts exist.
+
+### After init
+Once real artifacts exist, the runtime guarantees that the root pair is loaded before any budgeted expansion:
+
+- root `.pi-map.index.md`
+- root `.pi-map.md`
+
+Additional directory pairs are expanded only while the configured context budget allows, in shallow-first order.
+
+### Trust boundary
+Injected maps and indexes are navigation and orientation aids, not final authority:
+
+> **index routes, map orients, source decides**
+
+If an injected artifact and the source disagree, source wins. Always verify critical behavior from source before editing or making exact runtime claims.
+
+### Mode ladder
+- `off`: no automatic injection beyond existing tool/docs discovery.
+- `advisory`: inject startup/init hints and allow optional root-pair preload; use light reminders.
+- `strong` (default): inject the root pair, expand under the configured budget, run reinjection checks on relevant turns, and remind before edits or architecture-sensitive reasoning.
+- `strict`: same as `strong`, plus require an explicit bypass justification before sensitive edits or architectural claims when the protocol path is missing.
+
+The **protocol path** is present when the outgoing context contains the canonical injected root-pair block and the trust-boundary instruction. In `strict` mode, sensitive actions without it are blocked unless the agent includes `[PI_MAP_BYPASS: <brief justification>]`.
+
+### Context budget
+The default budget is **15% of the active model context window**, capped at **100k tokens**. The smaller of the relative and absolute values wins. If the runtime cannot discover the active model's context window, it falls back to the absolute cap.
+
+Configure it in `.pi-project-map.json`:
+
+```json
+{
+  "promptInjectionMode": "strong",
+  "contextBudgetPercent": 15,
+  "contextBudgetMaxTokens": 100000
+}
+```
+
+## 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
 
+Retrieval via `project_map_context` (tool) or `project-map context` (CLI) remains a separate, on-demand path. Use it for targeted navigation when you have a specific query; automatic injection does not replace it.
+
+### Integration-test expectations and known limitations
+The implementation is validated by integration tests covering:
+
+- pre-init hint behavior,
+- post-init root-pair preload,
+- budgeted expansion behavior,
+- canonical-marker dedupe,
+- reinjection after compaction,
+- reinjection after root-pair artifact changes,
+- mixed visibility behavior,
+- guidance-mode differences,
+- strict-mode bypass behavior.
+
+Known limitations:
+
+- Token estimation is best-effort (≈ 4 chars per token); actual provider token counts may differ.
+- Relevant-turn detection uses explicit event types when available and falls back to heuristics on generic turns.
+- Message-layer scanning is preferred; provider-payload serialization quirks require a fallback scan path.
+
 ## Commands
 
 ```bash
@@ -64,10 +128,17 @@ Create `.pi-project-map.json` in the project root:
   "contextBudget": 4000,
   "autoInjectPrompt": true,
   "tagCap": 8,
-  "workflowHintCap": 5
+  "workflowHintCap": 5,
+  "promptInjectionMode": "strong",
+  "contextBudgetPercent": 15,
+  "contextBudgetMaxTokens": 100000
 }
 ```
 
+- `promptInjectionMode`: `off`, `advisory`, `strong` (default), or `strict`.
+- `contextBudgetPercent`: relative share of the active model context window used for automatic map/index injection.
+- `contextBudgetMaxTokens`: hard absolute cap on the injection budget.
+
 ## Design
 
 See [design-doc.md](design-doc.md) for the full specification.