1 files changed, 71 insertions, 0 deletions
diff --git a/worldbuilding_guide/hacking.md b/worldbuilding_guide/hacking.md
new file mode 100644
index 0000000..6f9bf9a
--- /dev/null
+++ b/worldbuilding_guide/hacking.md
@@ -0,0 +1,71 @@
+## Hacking
+
+Hacking minigames are played by jacking into terminal objects. Terminals are YAML objects that are registered in Go's `terminalDefs` map.
+
+### Terminal Object YAML
+
+```yaml
+id: terminal_basic
+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."
+```
+
+- `id` must match a key in `terminalDefs` (Go code in `internal/game/hacking.go`)
+- `name` is used for matching in the `jack` command
+- `color` controls the display color
+- `description` is shown when examining the terminal
+- `inroom_description` is shown in room listings
+- No `behavior` field — terminals are registered in Go, not YAML behaviors
+
+### Adding a New Terminal
+
+1. Create an object YAML file in `data/objects/terminal_<name>.yaml`
+2. Add an entry to `terminalDefs` in `internal/game/hacking.go`
+3. Optionally create a new minigame implementation in `internal/game/hacking_<name>.go`
+4. Place the terminal object in a room's `objects:` list
+
+### Adding a New Minigame
+
+New minigames implement the `HackingMinigame` interface:
+
+```go
+type HackingMinigame interface {
+    Init(level int) string
+    HandleInput(input string) (output string, done bool, won bool)
+    Name() string
+}
+```
+
+Optionally implement `XPBonuser` for bonus XP:
+
+```go
+type XPBonuser interface {
+    BonusXP() int
+}
+```
+
+### 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.