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/spells/SPELLS.md

@@ -0,0 +1,85 @@
+# Spell TOML Reference
+
+Each file in `world/spells/` defines one spell or skill. The filename (without `.toml`) becomes the spell ID with prefix `spell:` (e.g. `magic_missile.toml` → `spell:magic_missile`). Spells are referenced from guilds in `world/guilds/*.toml`.
+
+## Top-level fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | Yes | — | Display name. |
+| `description` | string | Yes | — | Short description shown in `spells` and `guild info`. |
+| `spell_type` | string | No | `"offensive"` | One of: `"offensive"`, `"heal"`, `"utility"`. Affects when and how the spell can be used (e.g. heal/utility out of combat; offensive usually in combat). |
+| `damage` | integer | No | `0` | Base damage for offensive spells. |
+| `heal` | integer | No | `0` | HP restored for heal spells. |
+| `damage_type` | string | No | `"magical"` | Damage type (e.g. `"physical"`, `"fire"`, `"magical"`, `"holy"`, `"poison"`). |
+| `cost_mana` | integer | No | `0` | Mana cost to cast. |
+| `cost_endurance` | integer | No | `0` | Endurance cost to cast. |
+| `cooldown_ticks` | integer | No | `0` | Ticks before the spell can be used again. |
+| `casting_ticks` | integer | No | `0` | Ticks before the spell resolves (future use; currently casting is one tick). |
+| `min_guild_level` | integer | No | `0` | Minimum guild level required to know/use this spell. |
+| `effect` | string | No | — | Status effect kind applied (e.g. `"poison"`, `"regen"`, `"defense_up"`). |
+| `effect_duration` | integer | No | `0` | Duration of the effect in ticks. |
+| `effect_magnitude` | integer | No | `0` | Magnitude (e.g. damage per tick for poison, heal per tick for regen). |
+
+## Spell types
+
+- **offensive** — Deals damage to current combat target. Requires combat; blocked out of combat.
+- **heal** — Restores HP. Can be used in or out of combat; out of combat resolves immediately.
+- **utility** — Buffs, cleanses, etc. Can apply status effects; out of combat resolves immediately.
+
+## Examples
+
+**Offensive (mana):**
+
+```toml
+name = "Magic Missile"
+description = "Hurl bolts of pure arcane energy."
+spell_type = "offensive"
+damage = 15
+damage_type = "magical"
+cost_mana = 10
+cooldown_ticks = 1
+min_guild_level = 1
+```
+
+**Heal:**
+
+```toml
+name = "Heal"
+description = "Channel divine energy to mend wounds."
+spell_type = "heal"
+heal = 25
+cost_mana = 15
+cooldown_ticks = 2
+min_guild_level = 1
+```
+
+**Utility with effect:**
+
+```toml
+name = "Battle Cry"
+description = "A thunderous war shout that steels your resolve."
+spell_type = "utility"
+cost_endurance = 10
+cooldown_ticks = 10
+min_guild_level = 3
+effect = "regen"
+effect_duration = 5
+effect_magnitude = 4
+```
+
+**Offensive with DoT:**
+
+```toml
+name = "Poison Blade"
+description = "Coat your weapon with virulent toxin."
+spell_type = "offensive"
+damage = 8
+damage_type = "poison"
+cost_endurance = 10
+cooldown_ticks = 6
+min_guild_level = 3
+effect = "poison"
+effect_duration = 4
+effect_magnitude = 3
+```