docs: qualify TSP framing, soften optimality claims, reframe defensibility

[IanMayo]

Handles the three documentation/framing issues raised in review. No engine changes — wording only, plus one small UI note and an optional docs link. typecheck, lint, test:run (139 passing) and build are all green.

Fix 1 — qualify the TSP framing

The engine runs A* independently between consecutive waypoint pairs and concatenates the legs (the optional reorder is a greedy nearest-neighbour pass) — multi-leg shortest path, not tour optimisation. Owned explicitly rather than renaming the project.

• README: describes the engine as multi-leg risk-aware shortest path; a short Origins line keeps the TSP heritage.
• Approaches §10: legs are routed independently, so the combined route carries no global visit-once guarantee and may revisit cells across legs.
• Approaches glossary: new Multi-leg routing entry.
• Demo (WaypointsPanel): for 3+ stops, the waypoint-ordering note now adds that legs are planned independently and may overlap. (Gated to 3+ stops because the clause is only meaningful with 2+ legs.)
• Pages index: no change — it doesn't reference TSP.

Fix 2 — soften the "optimal" guarantees

A* is optimal on a static per-leg graph, but not once the temporal layer is active (true search state is (cell, time)), and tailwind reduces cost so the distance heuristic is no longer strictly admissible under wind.

• Approaches §10: optimality sentence rewritten — admissible/optimal per-leg on a static map; a high-quality time-aware heuristic, not a proof of optimality, once temporal modifiers are active. h(n) reworded from "admissible" → "distance-based" to match.
• Approaches §6: Dynamic speed flagged as a greedy, locally-cheapest-not-globally-optimal choice.
• Approaches §9: tailwind lowers cost below the straight-line floor → heuristic no longer strictly admissible under wind.
• Approaches §10 (COA fan-out): COA discovery is heuristic by design, but COA ranking is exact (re-scored under real settings).
• Deck Proof ②: "find the cheapest route is a solved problem" → "finding a cheapest route is a well-understood problem"; speaker notes armed for the optimality question. Determinism claim kept.
• Deck Proof ③: unchanged (already honest).

Fix 3 — defensibility ≠ correctness

The architecture earns auditability and reproducibility, not objective accuracy — the risk scores and multipliers are modelling judgements.

• Approaches: new §13 "Assumptions & Limitations" ("model, not measurement") as the one place to point sceptics at (Glossary becomes §14); §1 notes that "risk" means encoded judgement, not measurement.
• Deck: Defensible card → "the assumptions are explicit, auditable and repeatable"; the honest "the metrics don't make the decision, they make your decision explainable" line promoted from speaker notes onto the closing slide; Proof ④ notes add "under your stated assumptions … doesn't certify them".
• Demo: an About the model link in the header points at the new Assumptions section.

https://claude.ai/code/session_0179WpdHYU3kt4txMiHqMmUG

---

Generated by Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-06 18:36 UTC