docs: BLUEPRINT_FORMAT.md + README updates for the v2 container (terrain-water task 02)

Byte-accurate v2 contract (magic/version, tagged sections, registered
FourCC table, validation rules, re-encode sentinels, extension path)
plus the v1 legacy summary — v1 stays live per the safety-net plan.
READMEs updated additively: parser dispatch, dual-write outputs,
harness usage, server params cross-check, wire-format hazard rewording
(u8 on v2 path, range-checked; append-only rule unchanged).

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

Tools/README.md

@@ -33,7 +33,8 @@ so they only help between paths. Expect a regeneration to take minutes, or to ne
 
 | File | What it is |
 |---|---|
-| `MapData_Seed_<seed>.dat` | The binary blueprint the server reads (~512 MB at 8K) |
+| `MapData_Seed_<seed>.dat` | The binary blueprint the server reads — **v2 tagged container** (~336 MB at 8K; contract in `Core/Scripts/BLUEPRINT_FORMAT.md`) |
+| `MapData_Seed_<seed>_v1.dat` | The same content in the legacy v1 format (~512 MB), dual-written as a safety net until a future removal task |
 | `Map_Seed_<seed>.png` | Visual snapshot of the map, for reviewing and picking seeds |
 
 On Linux: `~/.local/share/godot/app_userdata/islaApocolypse/`.

Tools/Scenes/README.md

@@ -23,6 +23,19 @@ tiny or black PNG.
 Note the generator writes the `.dat` on its own — the capture wrapper only matters for the
 full-resolution image.
 
+## `RoundTripHarness.tscn`
+
+The blueprint format regression test (script: `Tools/Scripts/RoundTripHarness.cs`). Run it
+headless from a terminal — it never generates, it round-trips an existing blueprint through the
+real parser and v2 writer and asserts semantic equality:
+
+```
+Godot --headless --path <repo> res://Tools/Scenes/RoundTripHarness.tscn
+```
+
+Defaults to the preserved reference blueprint (`user://reference_1409879727/`); override with the
+`HARNESS_V1_PATH` / `HARNESS_V2_PATH` environment variables. Exit code 0 = pass.
+
 ## Generating a new world
 
 1. Open `MapPreview.tscn` (or `Scenes/MapCaptureTool.tscn` for the full-resolution PNG).

Tools/Scripts/README.md

@@ -18,7 +18,10 @@ Generates the entire 2D blueprint. Roughly in order:
 5. **Biomes and towns** — biome zoning by height and temperature; tiered town placement (Capitol,
    Hubs, Villages, Outposts, POIs) filtered by slope, water proximity and spacing.
 6. **Roads** — see below.
-7. **Export** — writes the `.dat` blueprint, then renders the PNG snapshot.
+7. **Export** — writes the `.dat` blueprint (dual-write: the v2 tagged container under the primary
+   seed name, plus the legacy v1 format beside it as `_v1.dat` — see
+   `Core/Scripts/BLUEPRINT_FORMAT.md`), then renders the PNG snapshot. The v2 file embeds the
+   resolved generation params (seed, MapSize, crater radius, density, impact centre, provenance).
 
 ### The road network
 
@@ -52,7 +55,15 @@ Road colours on the snapshot, useful for identifying a road: **red** = Highway,
 **dark brown** = Rugged, **light brown** = Trail.
 
 ### Outputs
-`MapData_Seed_<seed>.dat` and `Map_Seed_<seed>.png`, both to `user://`.
+`MapData_Seed_<seed>.dat` (v2), `MapData_Seed_<seed>_v1.dat` (legacy dual-write), and
+`Map_Seed_<seed>.png`, all to `user://`.
+
+## `RoundTripHarness.cs`
+
+The blueprint format regression test (scene: `Tools/Scenes/RoundTripHarness.tscn`). Loads a
+known-good blueprint through the real parser, re-writes it as v2 through the real writer, re-loads
+it, and asserts semantic equality (heights bitwise, biomes, towns, every road point). Headless,
+seconds per cycle, no generation. Exit code 0 = pass.
 
 ## Rules
 1. **No magic numbers.** Distances, radii and thresholds derive from `MapSize` or `scaleFactor`, so