Add TOML reference docs for all world data types

- world/MANIFEST.md: manifest.toml and directory layout
- world/races/RACES.md: race schema (stats, body, natural, resistances, etc.)
- world/classes/CLASSES.md: class schema (base_stats, growth, hidden, guild)
- world/guilds/GUILDS.md: guild schema and [growth]
- world/spells/SPELLS.md: spell schema and types
- world/town/REGION.md: region.toml
- world/town/rooms/ROOMS.md: room schema and exits
- world/town/npcs/NPCS.md: NPC schema, race/class resolution
- world/town/objects/OBJECTS.md: object schema and [stats]

Made-with: Cursor

world/town/npcs/NPCS.md

@@ -0,0 +1,89 @@
+# NPC TOML Reference
+
+Each file in a region’s `npcs/` folder (e.g. `world/town/npcs/`) defines one NPC template. The NPC ID is `"<region>:<filename_stem>"` (e.g. `barkeep.toml` in region `town` → `town:barkeep`). Race and class are resolved at **spawn time** (and again on respawn if not fixed); omit them for random selection.
+
+## Top-level fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | Yes | — | Display name. |
+| `description` | string | Yes | — | Shown when the player looks at or examines the NPC. |
+| `room` | string | Yes | — | Full room ID where the NPC appears (e.g. `"town:tavern"`). |
+| `base_attitude` | string | No | `"neutral"` | One of: `friendly`, `neutral`, `wary`, `aggressive`, `hostile`. Hostile NPCs auto-engage players in the room. |
+| `faction` | string | No | — | Optional faction ID for attitude grouping. |
+| `race` | string | No | — | Race ID (e.g. `"race:beast"`, `"race:human"`). If omitted, a random non-hidden race is chosen at each spawn/respawn. |
+| `class` | string | No | — | Class ID (e.g. `"class:peasant"`, `"class:rogue"`). If omitted, the race’s `default_class` is used, or a random compatible non-hidden class. |
+| `respawn_secs` | integer | No | — | If set, the NPC respawns this many seconds after death. Race/class are re-rolled on respawn unless fixed above. |
+| `dialogue` | table | No | — | See below. |
+| `combat` | table | No | — | If set, the NPC can be attacked and has combat stats. If omitted, the NPC has default combat stats when attacked. |
+
+## `[dialogue]`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `greeting` | string | No | — | Line shown when a player uses `talk` on this NPC (only if attitude allows talking). |
+
+## `[combat]`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `max_hp` | integer | Yes | — | Maximum HP. |
+| `attack` | integer | Yes | — | Attack value. |
+| `defense` | integer | Yes | — | Defense value. |
+| `xp_reward` | integer | No | `0` | XP awarded when the NPC is killed. |
+
+## Examples
+
+**Fixed race/class (e.g. animal):**
+
+```toml
+name = "Giant Rat"
+description = "A mangy rat the size of a small dog."
+room = "town:cellar"
+base_attitude = "hostile"
+race = "race:beast"
+class = "class:creature"
+respawn_secs = 60
+
+[combat]
+max_hp = 25
+attack = 6
+defense = 2
+xp_reward = 15
+```
+
+**Random race, fixed class (e.g. barkeep):**
+
+```toml
+name = "Grizzled Barkeep"
+description = "A weathered man with thick forearms."
+room = "town:tavern"
+base_attitude = "friendly"
+
+[dialogue]
+greeting = "Welcome to The Rusty Tankard."
+```
+
+(No `race` or `class` → random race each spawn, default class from race, e.g. Peasant for humanoids.)
+
+**Fixed class, random race:**
+
+```toml
+name = "Shadowy Thief"
+description = "A cloaked figure lurking in the darkness."
+room = "town:dark_alley"
+base_attitude = "aggressive"
+faction = "underworld"
+class = "class:rogue"
+respawn_secs = 90
+
+[combat]
+max_hp = 45
+attack = 12
+defense = 6
+xp_reward = 35
+```
+
+## Display
+
+`look <npc>` and `examine <npc>` show the NPC’s **resolved** race and class (from the current spawn instance).