feat: major xterm256 color overhaul, see worldbuilding docs.

7 files changed, 54 insertions, 41 deletions

diff --git a/worldbuilding_guide/README.md b/worldbuilding_guide/README.md
index 8555e49..b6f6de8 100644
--- a/worldbuilding_guide/README.md
+++ b/worldbuilding_guide/README.md
@@ -1,6 +1,6 @@
 # World Building Guide
 
-Third Collapse is data-driven. Everything — rooms, items, mobs, objects, behaviors, drop tables, and recipes — is defined in YAML files under `data/`. No code changes needed to build a world.
+The House of Icarus is data-driven. Everything — rooms, items, mobs, objects, behaviors, drop tables, and recipes — is defined in YAML files under `data/`. No code changes needed to build a world.
 
 ## Files
 
diff --git a/worldbuilding_guide/behaviors.md b/worldbuilding_guide/behaviors.md
index a275c60..8e47883 100644
--- a/worldbuilding_guide/behaviors.md
+++ b/worldbuilding_guide/behaviors.md
@@ -21,7 +21,7 @@ drops:
   - 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 copper ore."
+    message: "You manage to mine some {178}copper ore{/}."
   - table: gem_table           # reference a shared drop table
     weight: 10
     depletes: false            # gem drops don't deplete the rock
@@ -31,6 +31,8 @@ respawn_message: "You see more ore in the rock."
 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{/}`.
+
 Non-depleting gather (fishing):
 ```yaml
 id: fish_trout
@@ -50,7 +52,7 @@ drops:
   - item_id: raw_trout
     weight: 100
     depletes: false            # never depletes
-    message: "You catch a trout!"
+    message: "You catch a {69}raw trout{/}!"
 ```
 
 Woodcutting with shared depletion and bird's nests:
@@ -72,7 +74,7 @@ drops:
   - item_id: oak_logs
     weight: 100
     depletes: false            # depletion is timer-based (deplete_timer)
-    message: "You get some oak logs."
+    message: "You get some {113}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
@@ -99,7 +101,7 @@ drops:
   - item_id: logs
     weight: 100
     depletes: true             # regular tree depletes on first successful gather
-    message: "You get some logs."
+    message: "You get some {107}logs{/}."
 respawn_timer: 80
 respawn_message: "A new tree grows in its place."
 respawn_broadcast: "A {name} grows back."
diff --git a/worldbuilding_guide/items.md b/worldbuilding_guide/items.md
index 73f497b..e9e4352 100644
--- a/worldbuilding_guide/items.md
+++ b/worldbuilding_guide/items.md
@@ -3,6 +3,7 @@
 ```yaml
 id: bronze_pickaxe
 name: bronze pickaxe
+color: "178"                   # xterm-256 color index (0-255)
 aliases: ["pick", "pickaxe"]
 description: "A sturdy bronze pickaxe."
 value: 10
@@ -17,6 +18,18 @@ tool_type: pickaxe            # used by gather behaviors that require "tool: pic
 tool_speed: 2                 # reduces gather wait time
 ```
 
+### Color
+
+The `color` field accepts xterm-256 palette indices (0-255) with optional modifiers:
+
+```yaml
+color: "178"                   # bronze/gold
+color: "75 bold"               # bold steel blue
+color: "g:196,208,226"         # 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.
+
 Key item (quest token, not equippable):
 ```yaml
 id: pass_stub
@@ -43,7 +56,7 @@ burn_ticks: 24        # how long the fire burns
 ```yaml
 id: bread
 name: bread
-color: "fg=bright_yellow"
+color: "222"
 description: "A fresh loaf of bread, still warm from the oven."
 value: 5
 heal_value: 5         # positive = heal, negative = damage
@@ -57,7 +70,7 @@ Define what items combine to make this item. Used by the `use` command.
 ```yaml
 id: bread_dough
 name: bread dough
-color: "fg=bright_yellow"
+color: "222"
 made_from:
   - items: [pot_of_flour]
     qty: 1
diff --git a/worldbuilding_guide/objects.md b/worldbuilding_guide/objects.md
index 94aead7..6929606 100644
--- a/worldbuilding_guide/objects.md
+++ b/worldbuilding_guide/objects.md
@@ -4,6 +4,7 @@ Object defined — links to a behavior:
 ```yaml
 id: copper_rock
 name: copper rock
+color: "178"                   # xterm-256 color index (0-255)
 behavior: mine_copper
 ```
 
@@ -11,9 +12,12 @@ Tree object:
 ```yaml
 id: oak_tree
 name: oak tree
+color: "113"
 behavior: chop_oak
 ```
 
+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 ANSI color.
+
 Hidden object — doesn't appear in room's object list, only discoverable via description or experimentation:
 ```yaml
 id: iron_gate
diff --git a/worldbuilding_guide/recipes.md b/worldbuilding_guide/recipes.md
index f40a9a7..500954f 100644
--- a/worldbuilding_guide/recipes.md
+++ b/worldbuilding_guide/recipes.md
@@ -1,4 +1,4 @@
-# Third Collapse - World Building Guide
+# The House of Icarus - World Building Guide
 
 ## Recipes
 
@@ -13,21 +13,21 @@ Recipe files live in `data/recipes/<id>.yaml`.
 
 ### Recipe YAML Reference
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | string | Unique recipe identifier |
-| `type` | string | Recipe type (cooking, smithing, crafting, etc.) |
-| `skill` | string | Skill checked for success |
-| `level` | int | Required skill level |
-| `xp` | int | XP awarded on success |
-| `wait` | float64 | Ticks per craft cycle (default 6) |
-| `station` | []string | Station object IDs required |
-| `consume` | []ConsumeEntry | Ingredients consumed (see below) |
-| `output` | string | ItemID produced on success |
-| `fail` | string | ItemID produced on failure (optional) |
-| `message` | string | Success message |
-| `fail_message` | string | Failure message |
-| `success` | SuccessFormula | Optional skill check formula (see Behaviors) |
+| Field          | Type           | Description                                     |
+| -------------- | -------------- | ----------------------------------------------- |
+| `id`           | string         | Unique recipe identifier                        |
+| `type`         | string         | Recipe type (cooking, smithing, crafting, etc.) |
+| `skill`        | string         | Skill checked for success                       |
+| `level`        | int            | Required skill level                            |
+| `xp`           | int            | XP awarded on success                           |
+| `wait`         | float64        | Ticks per craft cycle (default 6)               |
+| `station`      | []string       | Station object IDs required                     |
+| `consume`      | []ConsumeEntry | Ingredients consumed (see below)                |
+| `output`       | string         | ItemID produced on success                      |
+| `fail`         | string         | ItemID produced on failure (optional)           |
+| `message`      | string         | Success message                                 |
+| `fail_message` | string         | Failure message                                 |
+| `success`      | SuccessFormula | Optional skill check formula (see Behaviors)    |
 
 The recipe's name in menus comes from the output item's `name` field, colored using the output item's `color`.
 
diff --git a/worldbuilding_guide/rooms.md b/worldbuilding_guide/rooms.md
index 95e1972..f6e74ea 100644
--- a/worldbuilding_guide/rooms.md
+++ b/worldbuilding_guide/rooms.md
@@ -11,6 +11,18 @@ exits:
   east: 3
 ```
 
+### 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."
+```
+
+Tag spec format: `{<0-255> [bold] [dim] [underline]}text{/}`
+
+Gradients: `{g:196,82}gradient text{/}`. Multi-stop: `{g:45,39,59}three stops{/}`.
+
 ### Exits — simple vs conditional
 
 Simple exit — always passable:
diff --git a/worldbuilding_guide/toggles.md b/worldbuilding_guide/toggles.md
deleted file mode 100644
index 00b48ba..0000000
--- a/worldbuilding_guide/toggles.md
+++ /dev/null
@@ -1,18 +0,0 @@
-## Player Toggles
-
-Players can toggle personal settings with the `toggle` command:
-
-| Toggle | Effect |
-|---|---|
-| `description` | Show full room description when moving |
-| `tiny_map` | Mini-map display: `off`/`right`/`left` |
-| `xp_drops` | Show XP gained in gather/craft/combat messages |
-| `exits` | Show exit destinations inline in look output |
-| `mob_enter` | Notify when a mob enters the room |
-| `mob_leave` | Notify when a mob leaves the room |
-| `mob_spawn` | Notify when a mob spawns in the area |
-| `reserve` | Show full reserved item details in look |
-| `depletion` | Show depletion and despawn timers on objects |
-
----
-