feat: new type of non-violent 'combat': work

1 files changed, 119 insertions, 0 deletions

diff --git a/building_guide/courses.md b/building_guide/courses.md
new file mode 100644
index 0000000..491e2bd
--- /dev/null
+++ b/building_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.