docs: river carving pass in the generator README (terrain-water task 22)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Tools/Scripts/README.md

@@ -98,6 +98,19 @@ Generates the entire 2D blueprint. Roughly in order:
    section, so a plan can never masquerade as realized water. Part 2 (task 22) carves and waters
    the gated plan. Pure analysis: the source blueprint is never written.
 
+   **River carving (task 22, C0b part 2a)** — with `Rivers: "v1"` (default **"off"**, pending the
+   routing-style gate) the frozen task-21b plan is executed as real terrain (`RiverCarvePass.cs`):
+   the drainage analysis reruns in-pipeline (deterministic), each routed giant gets a lowland
+   route to the nearest ocean by deterministic Dijkstra — `RiverRoutingStyle: "short"` (direct,
+   uphill-penalised) or `"lowground"` (cost ≈ elevation; follows the lowest ground and meanders;
+   the provisional default) — and every promoted course is carved as a parabolic channel with a
+   smoothstep shoulder, width/depth growing downstream with drainage (`RiverWidthScale`/
+   `RiverDepthScale`), bed made monotone non-increasing toward the outlet and clamped to
+   sea + `RiverSeaMargin` everywhere (the erosion flood-guard discipline: below-sea cells
+   read-only, zero new below-sea cells, coastline provably fixed; asserted per generation).
+   Slots AFTER towns (town placement reads the render map and must not shift) and BEFORE roads.
+   Crater core excluded. **NO WATER yet** — part 2b waters the gated routing style.
+
 3. **Sea level and water** — sea level per the configured model (`SeaLevelModel`: `"flat"` scalar
    — the default, `SeaLevelValue` 0.15 — or the legacy `"field"` latitude Lerp); flood fill
    separates true ocean from inland lakes; a mainland fill guarantees one contiguous landmass.