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

design-doc.md

@@ -252,6 +252,39 @@ The LLM client's response is parsed to extract `PURPOSE`, `DEPS`, `CONCEPTS`, `R
 2. For architecture/system or ambiguous tasks, agent also reads the root `.pi-map.md`.
 3. Agent does **not** preload every directory map by default.
 
+In the Pi extension, this session-start consumption is assisted by automatic prompt injection:
+
+- **Before init**: only a lightweight visible startup hint is injected, telling the agent to run `project_map_init`. No synthetic map content is injected.
+- **After init**: the root pair (`.pi-map.index.md` + `.pi-map.md`) is guaranteed to be preloaded automatically. Additional directory pairs are expanded only while the configured context budget allows.
+
+### Automatic Prompt Injection
+
+The Pi extension uses event hooks (`before_agent_start`, `context`, etc.) to maintain guidance context.
+
+- The **mode ladder** controls how much is injected:
+  - `off`: no automatic injection.
+  - `advisory`: visible startup/init hints and optional root-pair preload.
+  - `strong` (default): root pair + budgeted expansion + relevant-turn reinjection checks.
+  - `strict`: same as `strong`, plus explicit bypass justification for sensitive edits/architectural claims when the protocol path is missing.
+- The **protocol path** requires both the canonical injected root-pair block and the trust-boundary instruction (`index routes, map orients, source decides`) to be present in outgoing context.
+- **Reinjection avoidance** scans actual outgoing messages (and falls back to provider payload) for a stable canonical marker before adding the root pair again.
+- **Relevant-turn triggers** are: agent start, before edits, before architecture-sensitive reasoning, after compaction, and after root-pair artifact changes.
+- **Visibility** is mixed: startup/init hints are user-visible; raw injected artifact blocks are agent-visible by default.
+
+### Context Budget
+
+Default automatic-injection budget: **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.
+
+Configurable via `.pi-project-map.json`:
+
+```json
+{
+  "promptInjectionMode": "strong",
+  "contextBudgetPercent": 15,
+  "contextBudgetMaxTokens": 100000
+}
+```
+
 ### During Session
 - Use directory indexes first to decide what to open next.
 - For **targeted queries**, run `project_map_context` (tool) or `project-map context` (CLI). The retrieval engine scores all paired metadata and returns a compact markdown bundle with the top-3 strongest matches: indexes, maps, likely files, and symbols.
@@ -262,6 +295,7 @@ The LLM client's response is parsed to extract `PURPOSE`, `DEPS`, `CONCEPTS`, `R
 - Tier 0 stays tiny and stable.
 - Tier 1 loads only likely relevant indexes/maps.
 - Tier 2 is real source, tests, config, and docs.
+- Automatic injection stays within the configured budget and avoids redundant reinjection by scanning outgoing context.
 
 ## 6. Stale Data Mitigation
 
@@ -320,9 +354,10 @@ pi-project-map/
 │   ├── llm-extract.ts       # LLM prompt templates for extraction
 │   ├── merge.ts             # Merge AST + LLM outputs
 │   ├── format.ts            # Dense markdown formatter
-│   └── config.ts            # Skill configuration (thresholds, ignore patterns)
+│   ├── config.ts            # Skill configuration (thresholds, ignore patterns)
+│   └── prompt-injection.ts  # Runtime guidance injection policy and helpers
 ├── hooks/
-│   └── on-prompt.ts         # Injects maintenance command into prompts
+│   └── on-prompt.ts         # Injects maintenance command into prompts (legacy; Pi extension uses event hooks)
 └── README.md                # Setup and usage for humans
 ```
 
@@ -333,9 +368,19 @@ pi-project-map/
 - `project-map:context <query>` — Retrieve a compact markdown bundle of the most relevant directories, files, and symbols for a natural-language query.
 - `project-map:reinit [path]` — Force re-initialization of entire project or subtree.
 
-### Prompt Hook
-- On every prompt, the skill appends a lightweight instruction:
-  > "If you modify any source file, run `project-map:patch <path>` to update the analysis. If you suspect staleness, run `project-map:validate`."
+### Prompt Injection Hooks
+
+The Pi extension registers event hooks instead of a single per-prompt append:
+
+- `before_agent_start`: emits the pre-init hint when no artifacts exist, or preloads the root pair (plus budgeted expansion) after init.
+- `context`: performs relevant-turn reinjection checks, detects compaction/artifact-change invalidation, and enforces `strict`-mode bypass guards.
+- `before_provider_request`: optional fallback for marker scanning when message-layer detection is insufficient.
+
+The injected maintenance reminder is:
+
+> Start with the root `.pi-map.index.md`, use indexes first for routing, read the local `.pi-map.md` plus source before edits, run `project_map_patch` after source edits, and run `project_map_validate` before freshness-sensitive architectural handoff.
+
+This is layered on top of the canonical root-pair block, which includes the trust boundary (`index routes, map orients, source decides`).
 
 ## 9. Risks and Tradeoffs
 
@@ -347,6 +392,19 @@ pi-project-map/
 | Expensive init on large repos | Medium | Medium | Parallelization, caching, optional incremental init |
 | Overlap with LSP/typedoc | Low | Low | This is agent-context, not IDE tooling. Different use case. |
 | AST parser unavailable | Medium | Low | Graceful fallback to LLM-only extraction |
+| Message-level marker scanning misses provider serialization quirks | Medium | Medium | Add payload fallback scanning |
+| Root-pair marker becomes brittle | Low | Medium | Stable deterministic boundaries and normalized artifact identity lines |
+| 15% / 100k default budget too aggressive for some fleets | Low | Medium | Both knobs are configurable |
+| Relevant-turn detection fuzzy | Medium | Medium | Centralized heuristics + extensive integration tests |
+| `strict` mode friction | Low | Medium | Keep `strong` as default; isolate strict-only bypass behavior |
+
+### Prompt Injection Known Limitations
+
+- Token estimation is best-effort (≈ 4 chars per token); actual provider token counts may differ.
+- Relevant-turn detection relies on explicit event types when available, with heuristic fallback for generic turns.
+- Provider payload serialization may require the fallback scan path.
+- The mode ladder is config-driven in v1; future UX may expose runtime controls.
+- Retrieval (`project_map_context`) remains separate from automatic injection.
 
 ## 10. Concrete Example: Full Project Snapshot