docs: bring all READMEs current with actual code (post-sweep-10 truth pass)

Every README was read first, checked against the code in its directory, then
rewritten to describe what the code actually does now.

Corrected throughout: map size is config-driven (8192 default) not a fixed
4096; chunks are 24x24x256 not 32x32; road carving is implemented for all four
tiers, not a 'next step'; Data/ and Resources/ are empty, not populated.

Also fixed MATH_MARCHING_CUBES.md, which documented the density sign convention
exactly backwards — it claimed positive was underground, where the code treats
positive as above the surface and counts a corner inside when density < iso.
Getting that backwards inverts every normal, a bug this project has hit before.

The root README now carries accurate run steps: F5 runs the map generator (not
the game), F6 on Scenes/Main.tscn runs the 3D world, and ChunkRadius is a load
radius that should be dropped to 4-8 while iterating.

Docs only. No code changed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Data/README.md

@@ -1,49 +1,41 @@
-# 🗄️ Data Directory - Isla Apocalypse
-
-## Overview
-The `/Data` directory is the static repository for all generated world files, visual previews, and configuration structures. It acts as the handoff point between the offline `/Tools` (which write the data) and the live `/Server` (which reads the data).
-
-**Core Philosophy: "The Immutable Source of Truth."**
-Files stored in this primary directory are considered *Base Blueprints*. They are the starting point of the world before any player interacts with it. The Game Client should almost never read from this folder directly; it receives this data via the Server.
-
----
-
-## 📦 Current Contents (Phase 1)
-
-### 1. Binary Blueprints (`.dat`)
-* **Format:** Custom serialized binary (`MapData_Seed_[X].dat`).
-* **Purpose:** Contains the highly compressed, raw mathematical output of the 2D Generator (Map Size, Height floats, Biome IDs, POI coordinates, Highway vectors).
-* **Usage:** Read by the Server's Chunk Manager at startup to construct the untouched 3D voxel world.
-
-### 2. Map Previews (`.png`)
-* **Format:** 1024x1024 RGBA Images (`Map_Seed_[X]_[Time].png`).
-* **Purpose:** High-resolution visual snapshots of the generated seeds. 
-* **Usage:** Used by the developer/server admin to visually review and select the best island layout before spinning up the 3D server.
-
----
-
-## 🚀 Future Roadmap & Planned Additions
-
-As the game expands, this folder will be subdivided to organize different types of static game data:
-
-### 3. /Prefabs (Planned - Phase 2/3)
-* **Format:** `.json` or custom `.prefab` binaries.
-* **Purpose:** 3D building templates (e.g., `GasStation_Tier3.json`) created by the Prefab Editor. The Server uses these files to spawn structures at the coordinates dictated by the master `.dat` blueprint.
-
-### 4. /Configs (Planned - Phase 3)
-* **Format:** `.json` or `.cfg`.
-* **Purpose:** Human-readable configuration files for game balance.
-    * `LootTables.json`: Defines what items spawn in which containers based on POI Tier.
-    * `VoxelPalette.json`: Maps the 2D Biome IDs to 3D Voxel types.
-    * `SpawnRates.json`: Defines zombie/animal spawn limits and Blood Moon horde scaling.
-
----
-
-## ⚠️ Directory Rules & Best Practices
-
-1.  **NO Scripts or Code:** This directory must strictly contain data files (`.dat`, `.png`, `.json`, `.csv`). It contains zero executable logic.
-2.  **Live Saves vs. Base Data:** * This folder holds the **Base Game Data**. 
-    * *Live Player Saves* and *Terrain Deformation Diff Files* should generally be saved to Godot's safe `user://` path on the host machine, NOT in this project folder. This prevents live server saves from accidentally being bundled into the game's base code.
-3.  **Version Control (Git) Warnings:**
-    * `.dat` and `.png` files can become very large. 
-    * **Rule:** Only commit the "Official Release" seed files to your repository. Use a `.gitignore` file to ignore random test generations so you don't bloat your project repository with gigabytes of discarded test maps.
+# /Data
+
+Intended handoff point for static world data written by `/Tools` and read by `/Server`.
+
+## ⚠️ Currently empty
+
+**This directory holds nothing but this README.** The generator does **not** write here.
+
+Generated world data goes to Godot's `user://` path instead — outside the project entirely. On Linux
+that is:
+
+```
+~/.local/share/godot/app_userdata/islaApocolypse/
+    MapData_Seed_<seed>.dat     the blueprint (~512 MB at 8K)
+    Map_Seed_<seed>.png         visual snapshot of the map
+```
+
+That is a good arrangement and worth keeping: it means a 512 MB blueprint can never be committed by
+accident, and regenerating a world never dirties the repo.
+
+## The blueprint format, for reference
+
+`MapData_Seed_<seed>.dat` is custom binary, written by `MapGenerator.ExportMapData` and read by
+`Core/Scripts/MapDataParser.cs`. Order is fixed and the two sides must match exactly:
+
+1. `"ISLA_V1"` — length-prefixed magic string
+2. map size (int32)
+3. for every pixel, x-major: height (float32) + biome (int32)
+4. town count, then per town: x, y (float32), tier (int32)
+5. the four road tiers in order — Highway, Branch, Rugged, Trail — each as a path count, then per
+   path a point count and its x/y float pairs
+
+**Enum ordinals are the serialized values** and there is no version gate beyond the magic string and
+no range validation on read. See the warning in `Core/Scripts/README.md` before touching `Enums.cs`.
+
+## If this folder ever does hold data
+
+- **Data files only** — no scripts, no logic.
+- **Keep large generated `.dat`/`.png` files out of git.** Commit only a deliberately chosen release
+  seed, if any.
+- Live player saves and terrain edits belong in `user://`, never in the project folder.