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

8 files changed, 62 insertions, 36 deletions

diff --git a/building_guide/bank.md b/building_guide/bank.md
index ec03a5a..acf9954 100644
--- a/building_guide/bank.md
+++ b/building_guide/bank.md
@@ -10,7 +10,7 @@ A bank terminal that players can interact with. Has no special behavior — the
 
 ```yaml
 name: bank booth
-color: "226"
+color: "E2"
 description: "..."
 inroom_description: "A bank booth is set into the wall."
 ```
diff --git a/building_guide/behaviors.md b/building_guide/behaviors.md
index 60428d6..b8668d8 100644
--- a/building_guide/behaviors.md
+++ b/building_guide/behaviors.md
@@ -10,7 +10,7 @@ The examples below are object/mob files; remember the filename is the ID for the
 Mining — per-drop depletion on a rock object:
 ```yaml
 name: copper rock
-color: "178"
+color: "B2"
 gather:
     skill: mining
     level: 1
@@ -28,7 +28,7 @@ gather:
         - item_id: copper_ore
           weight: 90                # 90% chance when roll succeeds
           depletes: true            # rock becomes depleted after this drop
-          message: "You manage to mine some {178}copper ore{/}."
+          message: "You manage to mine some {B2}copper ore{/}."
         - table: gem_table          # reference a shared drop table
           weight: 10
           depletes: false           # gem drops don't deplete the rock
@@ -37,8 +37,8 @@ gather:
     respawn_broadcast: "A glint of copper catches your eye from some {name}."
 ```
 
-Drop messages support inline color tags: `{<0-255>}text{/}`. Use the item's color
-index to match its display color. Gradients also work: `{g:196,82}text{/}`.
+Drop messages support inline color tags: `{<00-FF>}text{/}`. Use the item's color
+index to match its display color. Gradients also work: `{g:C4,52}text{/}`.
 
 Non-depleting gather (fishing on a fishing spot object):
 ```yaml
@@ -61,13 +61,13 @@ gather:
         - item_id: raw_trout
           weight: 100
           depletes: false          # never depletes
-          message: "You catch a {69}raw trout{/}!"
+          message: "You catch a {45}raw trout{/}!"
 ```
 
 Woodcutting with shared depletion and bird's nests:
 ```yaml
 name: oak tree
-color: "113"
+color: "71"
 gather:
     skill: woodcutting
     level: 15
@@ -85,7 +85,7 @@ gather:
         - item_id: oak_logs
           weight: 100
           depletes: false          # depletion is timer-based (deplete_timer)
-          message: "You get some {113}oak logs{/}."
+          message: "You get some {71}oak logs{/}."
     respawn_timer: 14              # ticks until tree respawns after being cut down
     deplete_timer: 45              # max ticks before next gather depletes (counts down while chopping)
     nest_chance: 256               # 1/256 chance for a bird's nest on each successful gather
@@ -112,7 +112,7 @@ gather:
         - item_id: logs
           weight: 100
           depletes: true           # regular tree depletes on first successful gather
-          message: "You get some {107}logs{/}."
+          message: "You get some {6B}logs{/}."
     respawn_timer: 80
     respawn_broadcast: "A {name} grows back."
 ```
@@ -530,7 +530,7 @@ Use configs go under the `use:` key on objects (e.g. furnaces, ranges):
 
 ```yaml
 name: furnace
-color: "208"
+color: "D0"
 use:
     message: "You place the ore in the furnace..."
     wait: 4
diff --git a/building_guide/construction.md b/building_guide/construction.md
index 40e4b9f..dd63fd7 100644
--- a/building_guide/construction.md
+++ b/building_guide/construction.md
@@ -27,7 +27,7 @@ The primary construction station. Placed in rooms to enable construction.
 
 ```yaml
 name: workbench
-color: "172"
+color: "AC"
 description: "A sturdy wooden workbench..."
 inroom_description: "A workbench stands against the wall..."
 ```
@@ -38,7 +38,7 @@ A terminal that shows registered homeowners and lets them enter their house. Han
 
 ```yaml
 name: Estate Directory
-color: "39"
+color: "27"
 description: "A holographic terminal displaying property records..."
 inroom_description: "An estate directory terminal..."
 ```
diff --git a/building_guide/hacking.md b/building_guide/hacking.md
index c17d11a..dc4372b 100644
--- a/building_guide/hacking.md
+++ b/building_guide/hacking.md
@@ -8,9 +8,9 @@ Hacking minigames are played by jacking into terminal objects. Terminals are YAM
 
 ```yaml
 name: basic terminal
-color: "40"
-description: "A battered terminal with a cracked screen. {40}[Level 1 Hacking]{/}"
-inroom_description: "A {40}basic terminal{/} hums quietly against the wall."
+color: "28"
+description: "A battered terminal with a cracked screen. {28}[Level 1 Hacking]{/}"
+inroom_description: "A {28}basic terminal{/} hums quietly against the wall."
 ```
 
 - `id` must match a key in `terminalDefs` (Go code in `internal/game/hacking.go`)
diff --git a/building_guide/items.md b/building_guide/items.md
index 658acb9..8f8d87d 100644
--- a/building_guide/items.md
+++ b/building_guide/items.md
@@ -7,7 +7,7 @@ tables, craft `consume`, room `item_spawns`) uses that filename.
 
 ```yaml
 name: bronze pickaxe
-color: "178"                   # xterm-256 color index (0-255)
+color: "B2"                   # xterm-256 color index (00-FF)
 aliases: ["pick", "pickaxe"]
 description: "A sturdy bronze pickaxe."
 value: 10
@@ -98,15 +98,15 @@ stats:
 
 ### Color
 
-The `color` field accepts xterm-256 palette indices (0-255) with optional modifiers:
+The `color` field accepts xterm-256 palette indices (00-FF, hex) with optional modifiers:
 
 ```yaml
-color: "178"                   # bronze/gold
-color: "75 bold"               # bold steel blue
-color: "g:196,208,226"         # gradient red → orange → gold
+color: "B2"                   # bronze/gold
+color: "4B bold"               # bold steel blue
+color: "g:C4,D0,E2"         # gradient red → orange → gold
 ```
 
-In ANSI mode, extended colors (16-255) automatically downgrade to the nearest ANSI color. Use `colortable` in-game to see all 256 colors.
+In ANSI mode, extended colors (10-FF) automatically downgrade to the nearest ANSI color. Use `colortable` in-game to see all 256 colors.
 
 Key item (quest token, not equippable):
 ```yaml
@@ -131,7 +131,7 @@ burn_ticks: 24        # how long the fire burns
 
 ```yaml
 name: bread
-color: "222"
+color: "DE"
 description: "A fresh loaf of bread, still warm from the oven."
 value: 5
 heal_value: 5         # positive = heal, negative = damage
@@ -144,7 +144,7 @@ Define what items combine to make this item. Used by the `use` command. Combinat
 
 ```yaml
 name: bread dough
-color: "222"
+color: "DE"
 ticks: 2
 made_from:
   - items: [pot_of_flour]
diff --git a/building_guide/objects.md b/building_guide/objects.md
index 87b9710..aaa13e8 100644
--- a/building_guide/objects.md
+++ b/building_guide/objects.md
@@ -27,7 +27,7 @@ signage/scenery so it doesn't appear in room listings.
 Gathering object (mining):
 ```yaml
 name: copper rock
-color: "178"                   # xterm-256 color index (0-255)
+color: "B2"                   # xterm-256 color index (00-FF)
 gather:
     skill: mining
     level: 1
@@ -45,7 +45,7 @@ gather:
         - item_id: copper_ore
           weight: 90
           depletes: true
-          message: "You manage to mine some {178}copper ore{/}."
+          message: "You manage to mine some {B2}copper ore{/}."
         - table: gem_table
           weight: 10
           depletes: false
@@ -57,7 +57,7 @@ gather:
 Tree object (woodcutting with shared depletion):
 ```yaml
 name: oak tree
-color: "113"
+color: "71"
 gather:
     skill: woodcutting
     level: 15
@@ -75,7 +75,7 @@ gather:
         - item_id: oak_logs
           weight: 100
           depletes: false
-          message: "You get some {113}oak logs{/}."
+          message: "You get some {71}oak logs{/}."
     respawn_timer: 14
     deplete_timer: 45
     nest_chance: 256
@@ -83,7 +83,7 @@ gather:
 ```
 
 Color accepts xterm-256 indices with optional modifiers (`bold`, `dim`, `underline`)
-and gradients (`g:196,82`). In ANSI mode, extended colors downgrade to the nearest
+and gradients (`g:C4,52`). In ANSI mode, extended colors downgrade to the nearest
 ANSI color.
 
 Object interaction (gate, lever — uses `use_interactions:` key):
@@ -260,7 +260,7 @@ out of cover.
 
 ```yaml
 name: rock outcrop
-color: "248"
+color: "F8"
 hidden: true
 inroom_description: "A jagged rock outcrop juts from the floor."
 description: "A large, jagged rock formation providing natural cover."
@@ -409,8 +409,8 @@ player flags via talk node actions:
 
 Players can customize the message shown when forced out of a safespot:
 
-    option safespot_alert "{196 bold}** DANGER **{/} Cover blown!"
-Default: `"{196 bold}** Your safespot has been compromised! **{/}"`
+    option safespot_alert "{C4 bold}** DANGER **{/} Cover blown!"
+Default: `"{C4 bold}** Your safespot has been compromised! **{/}"`
 
 ---
 
diff --git a/building_guide/recipes.md b/building_guide/recipes.md
index 43b1cf4..364d375 100644
--- a/building_guide/recipes.md
+++ b/building_guide/recipes.md
@@ -41,7 +41,7 @@ All message fields (`message`, `fail_message`, `start_message`, `end_message`, a
 
 Numbering follows YAML consume/byproduct order. If a consume entry has multiple alternative items (`items: [a, b]`), the variable expands to whichever the player actually possesses, colored with that item's `color:` field.
 
-Variables work alongside inline color tags (`{196}text{/}`) which are expanded after variable substitution.
+Variables work alongside inline color tags (`{C4}text{/}`) which are expanded after variable substitution.
 
 ### Message Defaults
 
@@ -258,7 +258,7 @@ Items with `heal_value` and `eat_message` can be consumed via the `eat` command.
 
 ```yaml
 name: bread
-color: "222"
+color: "DE"
 description: "A fresh loaf of bread, still warm from the oven."
 value: 5
 heal_value: 5
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