diff --git a/README.md b/README.md
index 35f02d3..7cc124f 100644
--- a/README.md
+++ b/README.md
@@ -55,118 +55,39 @@ RUST_LOG=debug ./target/release/mudserver   # verbose
 
 ## World Data
 
-The world is defined entirely in TOML files under a `world/` directory. The server reads this at startup — no recompilation needed to change content.
+The world is defined in TOML files under `world/`. The server loads them at startup — no recompilation needed to change content.
 
-### Directory Structure
+### Directory structure
 
 ```
 world/
-├── manifest.toml              # world name and spawn room
-├── races/                     # playable races
-│   ├── dwarf.toml
-│   ├── elf.toml
-│   └── ...
-├── classes/                   # playable classes
-│   ├── warrior.toml
-│   ├── mage.toml
-│   └── ...
-└── <region>/                  # one directory per region
-    ├── region.toml            # region metadata
+├── manifest.toml
+├── races/
+├── classes/
+├── guilds/
+├── spells/
+└── <region>/
+    ├── region.toml
     ├── rooms/
-    │   ├── town_square.toml
-    │   └── ...
     ├── npcs/
-    │   ├── barkeep.toml
-    │   └── ...
     └── objects/
-        ├── rusty_sword.toml
-        └── ...
 ```
 
-### manifest.toml
+### Schema reference
 
-```toml
-name = "The Shattered Realm"
-spawn_room = "town:town_square"
-```
+Each folder contains a reference doc listing every TOML option:
 
-### Room
-
-```toml
-name = "Town Square"
-description = "A cobblestone square with a fountain."
-
-[exits]
-north = "town:tavern"
-south = "town:gate"
-east = "town:market"
-```
-
-Room IDs are `<region>:<filename_stem>`.
-
-### NPC
-
-```toml
-name = "Town Guard"
-description = "A bored guard."
-room = "town:gate"
-base_attitude = "neutral"   # friendly, neutral, wary, aggressive, hostile
-faction = "guards"           # optional — attitude shifts propagate to faction
-respawn_secs = 90            # optional — respawn timer after death
-
-[dialogue]
-greeting = "Move along."
-
-[combat]                     # optional — omit for weak default stats (20hp/4atk/2def/5xp)
-max_hp = 60
-attack = 10
-defense = 8
-xp_reward = 25
-```
-
-### Object
-
-```toml
-name = "Rusty Sword"
-description = "A battered iron blade."
-room = "town:cellar"
-kind = "weapon"              # weapon, armor, consumable, treasure, or omit
-takeable = true
-
-[stats]
-damage = 5                   # for weapons
-# armor = 4                  # for armor
-# heal_amount = 30           # for consumables
-```
-
-### Race
-
-```toml
-name = "Dwarf"
-description = "Stout and unyielding."
-
-[stats]
-strength = 1
-dexterity = -1
-constitution = 2
-```
-
-### Class
-
-```toml
-name = "Warrior"
-description = "Masters of arms and armor."
-
-[base_stats]
-max_hp = 120
-attack = 14
-defense = 12
-
-[growth]
-hp_per_level = 15
-attack_per_level = 3
-defense_per_level = 2
-```
+| Location | Reference |
+|----------|-----------|
+| `world/` | [MANIFEST.md](world/MANIFEST.md) — world name, spawn room, layout |
+| `world/races/` | [RACES.md](world/races/RACES.md) — stats, body, natural attacks, resistances, etc. |
+| `world/classes/` | [CLASSES.md](world/classes/CLASSES.md) — base stats, growth, hidden, guild |
+| `world/guilds/` | [GUILDS.md](world/guilds/GUILDS.md) — spells, growth, race restrictions |
+| `world/spells/` | [SPELLS.md](world/spells/SPELLS.md) — damage, cost, cooldown, effects |
+| `world/<region>/` | [REGION.md](world/town/REGION.md) — region metadata |
+| `world/<region>/rooms/` | [ROOMS.md](world/town/rooms/ROOMS.md) — name, description, exits |
+| `world/<region>/npcs/` | [NPCS.md](world/town/npcs/NPCS.md) — attitude, race/class, combat, dialogue |
+| `world/<region>/objects/` | [OBJECTS.md](world/town/objects/OBJECTS.md) — slot, stats, takeable |
 
 ## Game Mechanics