refactor: added docs, split up some components in game package

1 files changed, 27 insertions, 13 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 624034b..2897be8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,18 +21,32 @@ Dependencies: `gopkg.in/yaml.v3`, `github.com/gorilla/websocket`.
 
 ```
 cmd/mud/main.go         Entry point — config loading, multi-listener, tick engine
-internal/config/        YAML config (telnet, http, https listeners)
-internal/net/           Conn interface (tcp + websocket), session state, hub, IAC echo
-internal/game/          Login flow, command dispatch, input sanitization, all game logic
-internal/action/        Behavior structs (GatherConfig, TalkConfig, etc.), Action, drop tables
-internal/player/        Player struct, skills, inventory, XP, name/password validation
-internal/world/         Room, MobDef, MobInstance, ObjState, ground items, wandering
-internal/combat/        Combat state tracking, OSRS-style combat formulas
-internal/object/        ItemDef, ObjectDef, item/object YAML loaders
-internal/engine/        Tick scheduler — 600ms interval, subscriber pattern
+internal/config/        YAML config (telnet, http, https listeners) + doc.go
+internal/net/           Conn interface (tcp + websocket), session state, hub, IAC echo + doc.go
+internal/game/          Login flow, command dispatch, input sanitization, all game logic + doc.go
+internal/action/        Behavior structs (GatherConfig, TalkConfig, etc.), Action, drop tables + doc.go
+internal/player/        Player struct, skills, inventory, XP, name/password validation + doc.go
+internal/world/         Room, MobDef, MobInstance, ObjState, ground items, wandering + doc.go
+internal/combat/        Combat state tracking, OSRS-style combat formulas + doc.go
+internal/object/        ItemDef, ObjectDef, item/object YAML loaders + doc.go
+internal/engine/        Tick scheduler — 600ms interval, subscriber pattern + doc.go
 ```
 
-`internal/game/` is the largest package and contains most command implementations as `cmd_*.go` and `action_*.go` files.
+`internal/game/` is the largest package. Key files:
+
+| File | Purpose |
+|---|---|
+| `game.go` | Game struct, HandleSession state machine, command dispatch |
+| `login_account.go` | Account auth, creation, password handling, main menu, account rename/purge |
+| `login_char.go` | Character creation, connection, rename, delete |
+| `cmd_*.go` | Command handlers (see Adding a New Command below) |
+| `action.go` | StartAction, CancelAction, AdvanceActions, checkCondition |
+| `action_*.go` | Action lifecycle per behavior type (gather, talk, use, toggle, burn) |
+| `tick.go` | DisconnectTick, RegenTick, WanderTick, WoodcuttingTick |
+| `map.go` | BFS graph builder, tiny map, full map, display utilities (strip, trim) |
+| `types.go` | Shared types (EquipSlots, itemMatch, xpGain, deathDrop) |
+| `utils.go` | Helper functions (plural, parseQty, parseChoiceIndex, formatPickupList, etc.) |
+| `help.go` | Help topic YAML loading and display |
 
 ## Key Conventions
 
@@ -44,7 +58,7 @@ internal/engine/        Tick scheduler — 600ms interval, subscriber pattern
 
 **Transport-agnostic.** The `Conn` interface (`internal/net/conn.go`) abstracts the transport layer. `tcpConn` wraps a raw `net.Conn` for telnet. `wsConn` wraps `gorilla/websocket.Conn` for the web client. Game code works with `*Session` regardless of transport.
 
-**Input sanitization.** `HandleSession` strips Unicode control characters (ANSI escapes, nulls, etc.) from every input line before dispatch. Account/character names validated to `[A-Za-z0-9 ]{1,30}`. Input truncated to 1024 bytes. Password echo suppressed via IAC ECHO (telnet) and OSC sequences (web). WebSocket origin checked against host header.
+**Input sanitization.** `HandleSession` strips Unicode control characters from every input line via `player.StripControlCharacters` before dispatch. Account/character names validated to `[A-Za-z0-9 ]{1,30}`. Input truncated to 1024 bytes. Password echo suppressed via IAC ECHO (telnet) and OSC sequences (web). WebSocket origin checked against host header.
 
 **Tick-driven.** The world runs on a 600ms tick. Combat, gathering, regen, wandering, respawns, shared depletion, woodcutting timers all advance per tick. See `cmd/mud/main.go` for the subscription loop.
 
@@ -78,7 +92,7 @@ Actions that interact with objects/mobs route through `StartAction()` in `action
 5. Place the object in a room YAML in `data/rooms/`
 6. Create any resource items in `data/items/`
 
-Set `xp` on the behavior to award XP on successful gathers. Set `shared_deplete` for tree-style depletion, or use per-drop `depletes: true` for rock-style depletion.
+Set `xp` on the behavior to award XP on successful gathers. Set `deplete_timer` for tree-style depletion, or use per-drop `depletes: true` for rock-style depletion.
 
 ## Adding a New Production Skill
 
@@ -134,7 +148,7 @@ Firemaking is implemented as standalone actions (not behavior-YAML-driven) in `i
 
 **Per-drop depletion** (mining, regular trees): Set `depletes: true` on a drop entry. The resource depletes on first successful gather of that drop. Rocks don't show despawn timers when not depleted.
 
-**Shared depletion** (higher-tier trees): Set `shared_deplete: <ticks>` on the behavior. A shared timer counts down while anyone is chopping; when it hits 0, the next successful gather depletes the tree for all players. The timer regenerates back to max when no one is chopping. `WoodcuttingTick` manages this in `internal/game/tick.go`.
+**Shared depletion** (higher-tier trees): Set `deplete_timer: <ticks>` on the behavior. A shared timer counts down while anyone is chopping; when it hits 0, the next successful gather depletes the tree for all players. The timer regenerates back to max when no one is chopping. `WoodcuttingTick` manages this in `internal/game/tick.go`.
 
 ## Data Files