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>

Client/README.md

@@ -1,19 +1,29 @@
-# Client Module - IslaApocalypse
-
-**Phase 2 Status:** Active (Mesh Rendering & Vertex Painting Online)
-
-## Overview
-The `Client` directory handles the visual representation of the 3D Voxel Engine. It is strictly responsible for receiving pre-calculated mathematical data from the `Server` and `Core` modules and translating it into Godot-native visual nodes (`MeshInstance3D`). It does not calculate collisions, densities, or terrain generation.
-
-## Key Architecture & Components
-
-### 1. The Visualizer (`ChunkRenderer.cs`)
-A script attached to a `MeshInstance3D` node that physically draws a single 32x32 chunk of the world.
-* **Mesh Generation:** Calls `MarchingCubes.GenerateMesh()` from the `Core` module, passing in the `Densities` and `BlockIDs` scalar fields.
-* **Vertex Painting:** Dynamically creates a `StandardMaterial3D` and enables `VertexColorUseAsAlbedo = true`. This tells Godot to ignore standard texture maps and instead color the mesh using the exact RGB values we assigned to the vertices based on their `BlockID` (e.g., Green for Grass, Brown for Wasteland).
-* **World Positioning:** Multiplies the `ChunkPosition` (e.g., [1, 0]) by `Constants.CHUNK_SIZE` and `Constants.VOXEL_SCALE` (1.0f) to perfectly align the chunk in the global 3D space.
-* **Backface Rendering:** `CullMode` is explicitly disabled to ensure players don't see through the bottom of the map if they clip inside a mountain.
-
-## Next Immediate Steps (Phase 2, Step 4)
-* Currently, the renderer draws the exact topography. Once the `Server` implements **Road Carving**, the `Client` will automatically inherit those flattened vertices and paint them with the `ASPHALT` vertex color without needing any code changes here.
-* Future implementations will include reading `BlockIDs` to paint different UV maps/textures instead of just raw RGB vertex colors.
+# Client Module
+
+The visual layer. Takes finished chunk data and turns it into Godot nodes. It calculates nothing —
+no densities, no terrain, no collision.
+
+## `ChunkRenderer.cs`
+
+A `MeshInstance3D` created per chunk by the server, which then calls `RenderChunk(data)`.
+
+- **Mesh generation.** Calls `MarchingCubes.GenerateMesh()`, passing the density field, the block
+  IDs, and the per-column data the mesher needs to colour correctly: the true (unrounded) surface
+  heights, the biome per column, and the road surface material per column.
+- **Vertex colouring.** Creates a `StandardMaterial3D` with `VertexColorUseAsAlbedo = true`, so Godot
+  renders the per-vertex colours the mesher assigned rather than a texture. Colours fade between
+  materials across a tunable band instead of switching at whole-metre steps.
+- **World positioning.** `ChunkPosition × CHUNK_SIZE × VOXEL_SCALE` on X and Z, `y = 0` — chunks are
+  placed by their footprint and carry their full height internally.
+- **Backface rendering.** `CullMode` is disabled, so the world is still visible from underneath or
+  from inside terrain.
+
+## Notes
+
+- **One material instance per chunk.** Each renderer builds its own `StandardMaterial3D`. Since they
+  are all identical, a single shared material would do — an easy win whenever performance work starts.
+- Chunk positioning is relative to this node's parent, so **moving the `World` node in the scene
+  moves the entire rendered world** with it.
+
+## Not here yet
+No textures or UV mapping (raw vertex colour only), no LOD, no player, no UI, no input handling.