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

SKILL.md

@@ -41,6 +41,32 @@ Read actual source before editing or asserting exact behavior.
 
 **Trust boundary:** index routes, map orients, source decides.
 
+## Prompt Injection Policy
+
+This skill can automatically inject lightweight project-map guidance into your context. The behavior is controlled by `promptInjectionMode` in `.pi-project-map.json`.
+
+### Before init
+When no `.pi-map.md` / `.pi-map.index.md` artifacts exist, you see a visible startup hint telling you to run `project_map_init`. No synthetic map content is injected before real artifacts exist.
+
+### After init
+Once artifacts exist, the runtime guarantees that the root pair is loaded first:
+
+- root `.pi-map.index.md`
+- root `.pi-map.md`
+
+Additional directory pairs may be added while the configured context budget allows.
+
+### Mode ladder
+- `off`: no automatic injection beyond existing tool/docs discovery.
+- `advisory`: startup/init hints are shown; you may read the root pair manually when you want routing/orientation context.
+- `strong` (default): the root pair is injected automatically, expansion stays within the context budget, and reinjection checks run on relevant turns (agent start, before edits, before architecture-sensitive reasoning, after compaction, after root-pair artifact changes).
+- `strict`: same as `strong`, but before sensitive edits or architectural claims you must either have the protocol path in context or include an explicit bypass marker: `[PI_MAP_BYPASS: <brief justification>]`.
+
+The **protocol path** means the outgoing context contains the canonical injected root-pair block and the trust-boundary instruction (`index routes, map orients, source decides`).
+
+### Context budget
+Default 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 uses the absolute cap.
+
 ## Configuration
 
 Create `.pi-project-map.json` in the project root:
@@ -48,10 +74,17 @@ Create `.pi-project-map.json` in the project root:
 ```json
 {
   "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 to use for automatic map/index injection.
+- `contextBudgetMaxTokens`: hard absolute cap on the injection budget.
+
 ## Agent Instructions
 
 When project map artifacts exist in the repo:
@@ -61,7 +94,8 @@ When project map artifacts exist in the repo:
 3. Read the local `.pi-map.md` plus source before editing
 4. Run `project-map patch <path>` after editing source
 5. Run `project-map validate` before freshness-sensitive architectural decisions
-6. For **targeted navigation**, use `project_map_context` (Pi tool) or `project-map context` (CLI) with a natural-language query. It returns a compact markdown bundle with the strongest-match indexes, maps, likely files, and symbols.
+6. In `strict` mode, include `[PI_MAP_BYPASS: <brief justification>]` only when you deliberately need to proceed without the protocol path
+7. For **targeted navigation**, use `project_map_context` (Pi tool) or `project-map context` (CLI) with a natural-language query. It returns a compact markdown bundle with the strongest-match indexes, maps, likely files, and symbols.
 
 ## Retrieval Model