feat: one-way map links, blocked paths on map, map grid startup validation, user colors for maps

1 files changed, 29 insertions, 3 deletions

diff --git a/building_guide/rooms.md b/building_guide/rooms.md
index ebdf37d..0211c33 100644
--- a/building_guide/rooms.md
+++ b/building_guide/rooms.md
@@ -15,17 +15,26 @@ exits:
   east: 3
 ```
 
+### Map color — default symbol color on the map
+
+A room may set a default `color` that tints its node on the map and the links connecting it to
+neighbouring nodes. A player's per-room `symbol` color (set via the `symbol` command) overrides it.
+
+```yaml
+color: "5E"
+```
+
 ### Inline Color Tags
 
 Room descriptions support inline color tags using `{spec}text{/}` syntax. Untagged text uses the `room_desc` color.
 
 ```yaml
-description: "On the table lies a {182 bold}mysterious vase{/} with a rose in it."
+description: "On the table lies a {B6 bold}mysterious vase{/} with a rose in it."
 ```
 
-Tag spec format: `{<0-255> [bold] [dim] [underline]}text{/}`
+Tag spec format: `{<00-FF> [bold] [dim] [underline]}text{/}`
 
-Gradients: `{g:196,82}gradient text{/}`. Multi-stop: `{g:45,39,59}three stops{/}`.
+Gradients: `{g:C4,52}gradient text{/}`. Multi-stop: `{g:2D,27,3B}three stops{/}`.
 
 ### Exits — simple vs conditional
 
@@ -79,6 +88,23 @@ exits:
       boarded_shuttle: true        # marks "left this area" on the way out
 ```
 
+### Map grid & one-way exits
+
+Horizontal exits (north/south/east/west) must form a consistent 2D grid: from any
+starting room, walking N/S/E/W should never land two different rooms on the same
+spot, and a given room must always resolve to the same spot. Up/down don't move on
+the grid — they lead to a separate plane (floor) that is laid out on its own.
+
+Startup validation enforces this, starting from `startup_validation.root_rooms`
+(see config.yaml). It reports an **overlap** (two rooms on one grid cell) or a
+**twist** (one room on two cells) as an ERROR so you can fix the wiring.
+
+Exits don't have to be reciprocal. A one-way link (e.g. room 2001 has `east: 2006`
+but 2006 has no `west` back) renders on the map as a directional arrow
+(`← ↑ → ↓`, or `< ^ > v` in ASCII) instead of a two-way bar. If a link is open in
+one direction but blocked (failing condition) in the other, the open direction's
+arrow is shown; only a link with no traversable direction shows the blocked `X`.
+
 ### Item Spawns — ground items that respawn
 
 ```yaml