feat: smart subtree-aware reinit and validate --fix

- project_map_reinit now regenerates only the target subtree + ancestors
  by default, falling back to full reinit when subtree file count exceeds
  reinitFullThresholdPercent (default 10%).
- Add reinitFullThresholdPercent config option.
- Expose fix=true on project_map_validate Pi tool for localized repair.
- Update docs and runtime guidance to prefer patch / validate --fix
  before full reinit.
- Add integration tests for smart reinit and update typebox mock.

troubleshooting.md

@@ -10,7 +10,7 @@ A source file was edited, added, or deleted without running `project_map_patch`
 
 ### What to do
 1. run `project_map_validate` to inspect discrepancies
-2. if the list is small and localized, run `project_map_patch <changed-file>`
+2. if the list is small and localized, run `project_map_patch <changed-file>` or `project_map_validate` with `fix=true`
 3. if the list is large or structural, run `project_map_reinit`
 4. re-run `project_map_validate` to confirm clean state
 
@@ -38,14 +38,14 @@ Many `stale-signature` discrepancies appear.
 AST exports no longer match listed exports, or generated signatures are stale.
 
 ### Fix
-- patch the changed file/directory
+- patch the changed file/directory, or run `project-map validate --fix`
 - if widespread, reinit and validate again
 
 ### Symptom
 `broken-link` appears after moving directories.
 
 ### Fix
-Run `project_map_reinit`.
+Run `project-map validate --fix` first. If the damage spans many directories, run `project_map_reinit`.
 
 ## Prompt injection mode surprises
 
@@ -67,12 +67,13 @@ No project-map context appears in a Pi session.
 Root pair is injected repeatedly.
 
 ### Likely cause
-Marker scanning failed or artifact invalidation forced reinjection.
+Marker scanning failed or artifact invalidation forced reinjection, often because `project_map_reinit` is being used instead of `project_map_patch` or `project_map_validate --fix`.
 
 ### Fix
 - inspect whether `<!-- PI_MAP_ROOT_PAIR_START -->` is present in outgoing context
 - check whether root artifacts changed on disk
 - confirm payload/message serialization still exposes marker text
+- prefer `project_map_patch <file>` for edits and `project_map_validate` with `fix=true` for localized discrepancies
 
 ### Symptom
 `advisory` mode shows a reminder but no maps are loaded.