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/objects/OBJECTS.md

@@ -0,0 +1,80 @@
+# Object TOML Reference
+
+Each file in a region’s `objects/` folder (e.g. `world/town/objects/`) defines one object type. The object ID is `"<region>:<filename_stem>"` (e.g. `rusty_sword.toml` in region `town` → `town:rusty_sword`).
+
+## 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 object. |
+| `room` | string | No | — | Full room ID where the object is placed (e.g. `"town:forge"`). If omitted, the object does not appear in the world until given by script or placed elsewhere. |
+| `kind` | string | No | — | Flavour/legacy: e.g. `"weapon"`, `"armor"`, `"consumable"`. If `slot` is not set, `weapon` → `main_hand`, `armor` → `torso` for equip. |
+| `slot` | string | No | — | Equipment slot name (e.g. `"main_hand"`, `"off_hand"`, `"torso"`, `"head"`). Must be a slot the equipper’s race has. If set, overrides `kind` for slot choice. |
+| `takeable` | boolean | No | `false` | If `true`, players can take the object and put it in inventory. |
+| `stats` | table | No | — | See `[stats]` below. |
+
+## `[stats]`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `damage` | integer | No | — | Weapon damage bonus when equipped in a weapon slot. |
+| `armor` | integer | No | — | Armor bonus when equipped in an armor slot. |
+| `heal_amount` | integer | No | — | HP restored when the object is **used** (consumable). The object is consumed on use. |
+
+## Examples
+
+**Weapon (explicit slot):**
+
+```toml
+name = "Rusty Sword"
+description = "A battered iron blade with a cracked leather grip."
+room = "town:cellar"
+kind = "weapon"
+slot = "main_hand"
+takeable = true
+
+[stats]
+damage = 6
+```
+
+**Shield:**
+
+```toml
+name = "Iron Shield"
+description = "A dented but serviceable round shield."
+room = "town:forge"
+slot = "off_hand"
+takeable = true
+
+[stats]
+armor = 4
+```
+
+**Consumable:**
+
+```toml
+name = "Healing Potion"
+description = "A small glass vial filled with a shimmering red liquid."
+room = "town:temple"
+kind = "consumable"
+takeable = true
+
+[stats]
+heal_amount = 30
+```
+
+**Non-takeable (e.g. scenery):**
+
+```toml
+name = "Stone Fountain"
+description = "A worn fountain, water trickling quietly."
+room = "town:town_square"
+takeable = false
+```
+
+## Equipment and races
+
+- A race defines which slots it has (see `world/races/RACES.md`). Equipping fails if the race does not have the object’s `slot`.
+- If `slot` is omitted, `kind = "weapon"` defaults to `main_hand`, `kind = "armor"` to `torso`; other kinds have no default slot.
+- Items are treated as fitting any race that has the slot (no size restriction).