diff --git a/Tools/Scripts/README.md b/Tools/Scripts/README.md
index 07c8662..2ae0acd 100644
--- a/Tools/Scripts/README.md
+++ b/Tools/Scripts/README.md
@@ -137,6 +137,21 @@ Generates the entire 2D blueprint. Roughly in order:
    and beds deeper (`RiverDepthScale` 1.5, `RiverWaterDepthM` 2.2 m) so the chain reads as a graded
    descent rather than a pond staircase: 1034 reaches, adjacent-reach level gaps median 0.12 m.
 
+   **Polish r2 (task 25)** — tributaries carry water their **full** promoted length
+   (`RiverTribWaterMinFlow` 0) while still fading at the tip (the taper zone is always
+   `RiverTribTaperPx` long, starting wherever water begins). The water surface is
+   `RiverFillFraction` (0.80) of the **local** bed depth rather than a fixed height, floored by
+   `RiverWaterDepthM` — a fixed height was a trickle in a 13 m mouth and over the rim at a 1.5 m
+   head. Bank shoulders flare `RiverBankFlare` (3.2) half-widths with a smootherstep so water meets
+   land as a shore, and the **shoulder** may not lower a cell more than `RiverBankMaxCutM` (3 m)
+   **measured against the pre-pass surface** — gentle ground flares, a ridge crossing keeps steep
+   walls, and max cut fell to 16.8 m with no cell past 20 m.
+
+   **FILE SAFETY** — `ISLA_BLUEPRINT_PATH` (load a specific blueprint file) and `ISLA_EXPORT_DIR`
+   (write all of a run's blueprints and snapshots into a task folder) exist so tooling never writes
+   to, or deletes from, the runtime root — the developer stages `MapData_Seed_*.dat` there to view
+   worlds in 3D. Batch drivers set both and contain no delete of any kind.
+
 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.