feat: combat health bar. color improvements.

6 files changed, 122 insertions, 52 deletions

diff --git a/worldbuilding_guide/README.md b/worldbuilding_guide/README.md
deleted file mode 100644
index 0bea82c..0000000
--- a/worldbuilding_guide/README.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# World Building Guide
-
-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
-
-| Document | Covers |
-|----------|--------|
-| [Rooms](rooms.md) | Room definitions, exits (simple and conditional), spawns, placed objects and mobs, on_enter scripts |
-| [Items](items.md) | Item definitions, stats, equip slots, weapon types, tool types, firemaking, food/healing |
-| [Mobs](mobs.md) | Mob definitions, combat stats, drops, behavior, idle descriptions |
-| [Objects](objects.md) | Interactive objects, behaviors, hidden objects, in-room descriptions |
-| [Behaviors](behaviors.md) | Gather, use, talk behaviors with full YAML reference |
-| [Recipes](recipes.md) | Recipe system for cooking, crafting, smithing — station and item-on-item |
-| [Conditions](conditions.md) | All condition types: flag, player_flag, has_item, all_of, any_of, not |
-| [Drop Tables](drops.md) | Shared weighted drop tables for mob loot and search tables |
-| [State](state.md) | World flags vs player flags — global vs per-character state |
-| [Doors](doors.md) | Door examples with world flags and player flags |
-| [Quests](quests.md) | Complete multi-room quest example with talk behaviors |
-| [Wandering Objects](wandering_objects.md) | Objects that teleport between rooms on a timer |
-| [Wandering Mobs](wandering_mobs.md) | Mobs that wander through legal exits |
-| [Search](search.md) | The search command and searchable items |
-| [Hidden Objects](hidden_objects.md) | Hidden interactive objects |
-| [Bank](bank.md) | Bank system — deposit, withdraw, browse, bank booth placement |
-| [Construction](construction.md) | Construction skill — planks, furniture, houses, sawmill, Plank Make |
-| [Tips](tips.md) | Practical tips for building a world |
diff --git a/worldbuilding_guide/behaviors.md b/worldbuilding_guide/behaviors.md
index 1934f5b..08dc2d1 100644
--- a/worldbuilding_guide/behaviors.md
+++ b/worldbuilding_guide/behaviors.md
@@ -1,8 +1,7 @@
 ## Behaviors
 
 Behaviors are **inline configs** placed directly inside object YAML (`gather:`, `talk:`,
-`use:`) or mob YAML (`talk:`). There is no separate `data/behaviors/`
-directory. Each section below shows the keys you can use under each behavior type.
+`use:`) or mob YAML (`talk:`). Each section below shows the keys you can use under each behavior type.
 
 ### Gather (mining, fishing, woodcutting)
 
diff --git a/worldbuilding_guide/construction.md b/worldbuilding_guide/construction.md
index 63249b3..2c4b7ce 100644
--- a/worldbuilding_guide/construction.md
+++ b/worldbuilding_guide/construction.md
@@ -212,7 +212,7 @@ This enables automatic support through the unified production system (`advancePr
 | `data/items/saw.yaml` | Saw tool |
 | `data/items/planks.yaml` - `mahogany_planks.yaml` | Plank items (4 tiers) |
 | `data/items/wooden_shelf.yaml` - `mahogany_table.yaml` | Furniture items (7 items) |
-| `data/recipes/construct_planks.yaml` - `construct_mahogany_table.yaml` | Construction recipes (11 recipes) |
+| Item YAMLs with `craft:` blocks (planks, furniture) | Construction recipes — inline on output item YAML |
 | `data/mobs/estate_broker.yaml` | Estate broker mob (talk inline) |
 | `data/mobs/sawmill_operator.yaml` | Sawmill operator mob (talk inline) |
 | `data/rooms/16.yaml` | Construction Site (updated) |
diff --git a/worldbuilding_guide/courses.md b/worldbuilding_guide/courses.md
new file mode 100644
index 0000000..491e2bd
--- /dev/null
+++ b/worldbuilding_guide/courses.md
@@ -0,0 +1,119 @@
+## Agility Courses
+
+Agility courses are defined in `data/courses/<id>.yaml`. Each course defines a sequence of obstacle rooms, each with a specific verb the player must type to advance. Obstacle rooms themselves are standard room YAML files (typically in `data/rooms/agility/`).
+
+### Course YAML
+
+```yaml
+id: "vent_shaft"
+name: "Ventilation Shaft Course"
+required_level: 1
+start_room: 200
+completion_xp: 40
+obstacles:
+  - room_id: 201
+    verb: scramble
+    ticks_per_phase: 2
+    xp: 8
+    fail_damage: [1, 2]
+    messages:
+      - "You approach the corroded ventilation wall..."
+      - "You find footholds in the rusted panels and begin to climb..."
+      - "You scramble up the wall and haul yourself onto the ledge!"
+  - room_id: 202
+    verb: balance
+    ticks_per_phase: 2
+    xp: 8
+    fail_damage: [1, 2]
+    messages:
+      - "You step onto the narrow coolant pipe..."
+      - "Arms outstretched, you carefully place one foot in front of the other..."
+      - "You reach the other side of the pipe and step onto solid ground!"
+```
+
+### CourseConfig Fields
+
+| Field            | Type          | Description                                          |
+| ---------------- | ------------- | ---------------------------------------------------- |
+| `id`             | string        | Unique course identifier                             |
+| `name`           | string        | Display name shown to players                        |
+| `required_level` | int           | Minimum Agility level to attempt the course          |
+| `start_room`     | int           | Hub room — teleported here on fail or lap completion |
+| `completion_xp`  | int           | Bonus XP awarded when a full lap is completed        |
+| `obstacles`      | []ObstacleDef | Ordered list of obstacles                            |
+
+### ObstacleDef Fields
+
+| Field             | Type     | Description                                                                 |
+| ----------------- | -------- | --------------------------------------------------------------------------- |
+| `room_id`         | int      | Room ID for this obstacle                                                   |
+| `verb`            | string   | Command the player types to attempt it (e.g. `scramble`, `jump`, `climb`)   |
+| `ticks_per_phase` | float64  | Ticks between each phase message (supports fractional via `engine.ToTicks`) |
+| `xp`              | int      | XP awarded for successfully completing this single obstacle                 |
+| `fail_damage`     | [2]int   | `[min, max]` damage on failure (HP clamped to minimum 1 — cannot kill)      |
+| `messages`        | []string | Exactly 3 strings for the 3-phase advancement system                        |
+
+### 3-Phase Message System
+
+Each obstacle advances through 3 phases, printing one message per phase:
+
+```
+Phase 0 (start):  messages[0] printed immediately
+Phase 1 (middle): messages[1] printed — FAILURE CHECK happens here
+Phase 2 (end):    messages[2] printed — XP awarded, teleport to next room
+```
+
+Failure only occurs at phase 1. Success chance is based on Agility level:
+- At required level: 70% success (30% fail)
+- Each level above reduces fail chance by 1% (down to minimum 5%)
+- Fail chance capped at 60%
+
+On failure, the player takes random damage in `[fail_damage[0], fail_damage[1]]`, is teleported back to `start_room`, and must restart the course.
+
+### Lap Counting
+
+Completing all obstacles in a course increments a lap counter stored as a player flag (`agility_laps_<course_id>`). The `completion_xp` bonus is awarded on the final obstacle only.
+
+### Obstacle Room YAML
+
+Each obstacle room should have an `on_enter` message telling the player which verb to use, and a `down` exit back to the course hub:
+
+```yaml
+id: 201
+name: "Ventilation Shaft - Corroded Wall"
+description: "A towering wall of corroded ventilation panels..."
+on_enter:
+  - message: "Type 'scramble' to climb the wall."
+exits:
+  down:
+    room: 200
+    blocked_message: ""
+```
+
+The hub room (e.g. room 200) links to the first obstacle of each course:
+
+```yaml
+id: 200
+name: "Agility Training Grounds"
+exits:
+  south: 17
+  north: 201      # Vent Shaft (level 1)
+  east: 210       # Rooftop (level 20)
+  west: 220       # Reactor (level 50)
+```
+
+### Supported Obstacle Verbs
+
+| Verb       | Gerund (display) |
+| ---------- | ---------------- |
+| `scramble` | scrambling       |
+| `jump`     | jumping          |
+| `swing`    | swinging         |
+| `balance`  | balancing        |
+| `climb`    | climbing         |
+| `crawl`    | crawling         |
+| `vault`    | vaulting         |
+| `leap`     | leaping          |
+| `slide`    | sliding          |
+
+Obstacle verbs are auto-registered at startup from all course YAML files. No changes to `cmd_registry.go` needed when adding new courses — any verb in a `data/courses/` file will work.
diff --git a/worldbuilding_guide/hacking.md b/worldbuilding_guide/hacking.md
index 6f9bf9a..8927b3e 100644
--- a/worldbuilding_guide/hacking.md
+++ b/worldbuilding_guide/hacking.md
@@ -46,26 +46,4 @@ type XPBonuser interface {
 }
 ```
 
-### Agility Courses
 
-Agility courses are defined in `data/courses/<id>.yaml`. Each course defines a sequence of obstacle rooms with specific verbs.
-
-```yaml
-id: "vent_shaft"
-name: "Ventilation Shaft Course"
-required_level: 1
-start_room: 200
-completion_xp: 40
-obstacles:
-  - room_id: 201
-    verb: scramble
-    ticks_per_phase: 2
-    xp: 8
-    fail_damage: [1, 2]
-    messages:
-      - "You approach the corroded ventilation wall..."
-      - "You find footholds in the rusted panels and begin to climb..."
-      - "You scramble up the wall and haul yourself onto the ledge!"
-```
-
-Each obstacle room should have an `on_enter` message telling the player which verb to use, and a `down` exit back to the course hub.
diff --git a/worldbuilding_guide/index.md b/worldbuilding_guide/index.md
index 83b3782..e79ee1b 100644
--- a/worldbuilding_guide/index.md
+++ b/worldbuilding_guide/index.md
@@ -7,7 +7,7 @@
 | A mob (NPC, monster) | `data/mobs/<id>.yaml` |
 | An interactive object (rock, lever, door) | `data/objects/<id>.yaml` |
 | A shared drop table | `data/drops/<id>.yaml` |
-| A crafting recipe | `data/recipes/<id>.yaml` |
+| A crafting recipe | In the output item's YAML under a `craft:` block |
 | A help topic | `data/help/<id>.yaml` |
 | A science module | `data/modules/<id>.yaml` |
 | An agility course | `data/courses/<id>.yaml` |