docs: document theory-aligned pathing workflow

docs/guide/pathfinding-research.md

@@ -277,6 +277,28 @@ The checked-in contract files live here:
 
 For unit tests, `PathingContractAssert` reports planner mismatches, replans, route totals, and per-segment tick overruns directly in the xUnit failure. For live runs, `tools/pathing_contract_report.py` reads the `[PathMetric]` lines emitted by MCC and prints the same route-level and segment-level view, so the offline and live harnesses fail for the same reasons.
 
+## Theory-Aligned Regression Workflow
+
+The first-wave theory authority now comes from `tools/sim_jump_reach.py`, which writes:
+
+- `tools/pathing_data/theory-matrix.json`
+- `tools/pathing_data/theory-matrix.csv`
+- `tools/pathing_data/theory-matrix.md`
+- `tools/pathing_data/canonical-live-cases.json`
+
+Regenerate them with:
+
+```bash
+python3 tools/sim_jump_reach.py --write-artifacts tools/pathing_data
+```
+
+The theory-aligned live suites read the canonical manifest instead of embedding their own pass and reject expectations:
+
+- `tools/test-parkour.sh`
+- `tools/test-pathing-theory-neo-ceiling.sh`
+
+That split matters. The theory matrix stays broad and machine-readable. The canonical manifest stays small enough to run live, and the shell suites only need to care about case setup, execution, and recording the outcome.
+
 ## Deterministic live route contract
 
 For the short-route and long-route `1.21.11-Vanilla` live harnesses, accepted routes must complete with all of the following:

tools/pathing_data/theory-matrix.md

@@ -1,5 +1,10 @@
 # Theory Matrix
 
+## Canonical live coverage
+
+This file is generated from `tools/sim_jump_reach.py` and is the first-wave authority
+for theory-aligned linear, neo, and headhitter live suites.
+
 | family | subfamily | movement_mode | case_id | expected_reachable | margin |
 | --- | --- | --- | --- | --- | --- |
 | linear | flat | walk | linear-flat-walk-mm12-gap0-dy0p0 | True | 5.422586344756974 |

tools/pathing_theory/renderers.py

@@ -36,6 +36,11 @@ def write_theory_artifacts(
     lines = [
         "# Theory Matrix",
         "",
+        "## Canonical live coverage",
+        "",
+        "This file is generated from `tools/sim_jump_reach.py` and is the first-wave authority",
+        "for theory-aligned linear, neo, and headhitter live suites.",
+        "",
         "| family | subfamily | movement_mode | case_id | expected_reachable | margin |",
         "| --- | --- | --- | --- | --- | --- |",
     ]

tools/tests/test_pathing_theory_matrix.py

@@ -1,4 +1,5 @@
 import unittest
+from pathlib import Path
 
 from tools.pathing_theory.simulator import build_theory_cases
 
@@ -22,6 +23,10 @@ class PathingTheoryMatrixTests(unittest.TestCase):
         self.assertTrue(linear_boundary.expected_reachable)
         self.assertGreater(linear_boundary.margin, 0.0)
 
+    def test_theory_markdown_mentions_canonical_live_coverage(self) -> None:
+        markdown = Path("tools/pathing_data/theory-matrix.md").read_text(encoding="utf-8")
+        self.assertIn("Canonical live coverage", markdown)
+
 
 if __name__ == "__main__":
     unittest.main()