feat(admin): remove unused fields from drop tables

1 files changed, 47 insertions, 10 deletions

diff --git a/building_guide/drops.md b/building_guide/drops.md
index f71f712..edac103 100644
--- a/building_guide/drops.md
+++ b/building_guide/drops.md
@@ -4,7 +4,11 @@
 (`gem_table.yaml` → `gem_table`); reference it from behaviors/mobs by that name. Do not put
 an `id:` field in the file — it is ignored.
 
-Shared drop tables can be referenced by multiple behaviors:
+### Shared drop table entries
+
+Shared drop tables in `data/drops/` are pure weighted pools of items. Each entry supports
+only three fields (four with `table`):
+
 ```yaml
 # data/drops/gem_table.yaml
 drops:
@@ -18,6 +22,34 @@ drops:
     weight: 1
 ```
 
+| Field | Required | Description |
+|-------|----------|-------------|
+| `item_id` | XOR with `table` | Item ID to drop |
+| `table` | XOR with `item_id` | Reference to another shared drop table (can nest) |
+| `weight` | yes | Relative drop weight |
+| `quantity` | no | Amount to drop (default 1) |
+
+**`item_id` and `table` are mutually exclusive per entry.** The entry drops *either* the named
+item *or* rolls on the referenced sub-table; never both.
+
+### What does NOT belong on a shared drop table
+
+The following fields are **meaningless on shared drop table entries** and are ignored by the
+engine — they belong on the *referencing* gather entry in the object config instead:
+
+- `depletes` — controls whether the gatherable node depletes (per-drop; ore vs gem). Set on
+  the `gather.drops[]` entry in the object YAML that references this table.
+- `level` — skill-level gate on a drop. Only meaningful on the outer gather entry.
+- `xp` — skill XP for this drop. Only meaningful on the outer gather entry.
+- `tool` — tool-type filter. Only meaningful on the outer gather entry.
+- `success_message` — per-drop message. Overridden by the outer entry when referenced via
+  `table:`.
+
+The admin Drop Table editor intentionally shows only `item_id`/`table` (toggle), `weight`,
+and `quantity`. Edit the raw YAML if you need niche overrides.
+
+### Examples
+
 Bird's nest drop table:
 ```yaml
 # data/drops/birds_nest_drop.yaml
@@ -39,16 +71,21 @@ drops:
     quantity: 10000
 ```
 
-Referenced from a gather behavior:
+Referenced from a gather behavior (note `depletes` lives on the **outer** entries here,
+not inside `gem_table`):
 ```yaml
-drops:
-  - item_id: copper_ore
-    weight: 90
-    depletes: true
-  - table: gem_table          # pulls from data/drops/gem_table.yaml
-    weight: 10
-    depletes: false
+gather:
+  drops:
+    - item_id: copper_ore
+      weight: 90
+      level: 1
+      xp: 17
+      depletes: true
+      success_message: "You manage to mine some copper ore."
+    - table: gem_table          # pulls from data/drops/gem_table.yaml
+      weight: 10
+      depletes: false           # gem drops don't deplete the rock
+      success_message: "You spot a glint of something valuable!"
 ```
 
 ---
-