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.

usage-guide.md

@@ -9,7 +9,8 @@ For Pi agents and advanced users who want predictable, low-friction navigation a
 | New project, no `.pi-map.md` files yet, or artifacts are severely outdated | `project_map_init` / `project-map init` |
 | You just edited one or more source files | `project_map_patch <file>` / `project-map patch <file>` |
 | You suspect stale data, or you are about to make an architectural decision | `project_map_validate` / `project-map validate` |
-| Validation shows widespread staleness, or you pulled major changes from version control | `project_map_reinit` / `project-map reinit` |
+| Localized discrepancies detected by validate | `project_map_validate` with `fix=true` / `project-map validate --fix` |
+| Widespread structural staleness, or you pulled major changes from version control | `project_map_reinit` / `project-map reinit` |
 | You have a specific question like "where is auth handled?" | `project_map_context <query>` / `project-map context <query>` |
 
 ## Command behavior
@@ -18,11 +19,11 @@ For Pi agents and advanced users who want predictable, low-friction navigation a
 Run once when you start work on a repo, or after large restructuring. It discovers every non-ignored directory, analyzes files with LLM + AST, and writes both `.pi-map.md` and `.pi-map.index.md` for every directory.
 
 ### patch
-Run **immediately after editing a source file**. The command regenerates the pair for that file’s directory and refreshes ancestor artifacts.
+Run **immediately after editing a source file**. The command regenerates the pair for that file's directory and refreshes ancestor artifacts.
 
 Patch mode is chosen automatically:
-- **small** — refresh ancestor indexes only
-- **structural** — refresh ancestor map/index pairs
+- **small** - refresh ancestor indexes only
+- **structural** - refresh ancestor map/index pairs
 
 You can force a mode with `project-map patch <file> --patch-mode=small|structural`.
 `auto` remains the default.
@@ -38,7 +39,9 @@ Run before architectural decisions, broad refactors, or final handoff. It checks
 Use `project-map validate --fix` to repair affected chains. `--fix` requires an LLM client.
 
 ### reinit
-Use sparingly. It regenerates every pair from scratch and is the blunt instrument for widespread staleness.
+Use as a last resort. By default, `project_map_reinit` (or `project-map reinit [path]`) regenerates only the target subtree plus its ancestor directories up to the root. It falls back to full regeneration only when the target subtree covers more than `reinitFullThresholdPercent` of the project's files (default: 10%).
+
+Reach for reinit when `project_map_patch` and `project_map_validate --fix` cannot repair widespread structural damage (e.g. broken parent/child links across many directories) or after a large merge.
 
 ### context
 Use when you know what you are looking for:
@@ -57,12 +60,14 @@ The returned bundle is deterministic and ranked. Read indexes first, then strong
 
 1. read the root `.pi-map.index.md` and the `Project Map Protocol`
 2. use the root index to find the relevant child directory
-3. read that directory’s `.pi-map.index.md`, then its `.pi-map.md`
+3. read that directory's `.pi-map.index.md`, then its `.pi-map.md`
 4. read the relevant source files
 5. edit source
 6. run `project_map_patch <changed-file>`
 7. run tests/build
 8. run `project_map_validate` before architectural summary or handoff
+9. if validation reports localized discrepancies, run `project_map_validate` with `fix=true` (or `project-map validate --fix`)
+10. only if discrepancies are widespread or structural, run `project_map_reinit`
 
 ### Exploring an unfamiliar area
 
@@ -76,7 +81,9 @@ Treat the returned bundle as a ranked entry point, not as truth.
 
 ```bash
 project-map validate
-# if many discrepancies:
+# if localized discrepancies:
+project-map validate --fix
+# if widespread structural damage:
 project-map reinit
 ```
 
@@ -84,7 +91,9 @@ project-map reinit
 
 ```bash
 project-map validate
-# if needed:
+# if localized discrepancies:
+project-map validate --fix
+# if widespread structural damage:
 project-map reinit
 ```
 
@@ -155,9 +164,10 @@ Use bypass markers sparingly.
 
 ```text
 1. project-map validate
-2. If clean, read root .pi-map.md and key directory maps
-3. Cross-check claims against source
-4. If stale, run project-map reinit first
+2. If localized discrepancies: project-map validate --fix
+3. If clean, read root .pi-map.md and key directory maps
+4. Cross-check claims against source
+5. Only if widespread: run project-map reinit
 ```
 
 ## Retrieval vs automatic injection
@@ -175,7 +185,8 @@ Use both together: injection for baseline orientation, retrieval for focused ent
 
 - patch after every edit
 - validate before architectural claims
-- reinit when many artifacts are stale or after large merges
+- use `validate --fix` for localized discrepancies
+- use reinit only for widespread structural staleness or after large merges
 - watch for the Pi extension warning about dirty packages on session start
 
 ## Configuration quick reference
@@ -187,6 +198,7 @@ Use both together: injection for baseline orientation, retrieval for focused ent
   "contextBudgetMaxTokens": 100000,
   "tagCap": 8,
   "workflowHintCap": 5,
+  "reinitFullThresholdPercent": 10,
   "ignorePatterns": ["node_modules", ".git", "dist", "build"]
 }
 ```
@@ -195,4 +207,5 @@ Providing `ignorePatterns` replaces the built-in default list, so include any de
 
 - lower `contextBudgetPercent` / `contextBudgetMaxTokens` to reduce token use
 - raise them if you want deeper auto-loaded context in large projects
+- `reinitFullThresholdPercent` controls when `project-map reinit [path]` falls back to full regeneration
 - `strict` is the safest enforcement mode; `strong` is the best default for everyday work