1 files changed, 112 insertions, 0 deletions
diff --git a/worldbuilding_guide/recipes.md b/worldbuilding_guide/recipes.md
new file mode 100644
index 0000000..f40a9a7
--- /dev/null
+++ b/worldbuilding_guide/recipes.md
@@ -0,0 +1,112 @@
+# Third Collapse - World Building Guide
+
+## Recipes
+
+Recipes define how items are processed on stations to produce new items. They are the foundation for cooking, smithing, crafting, and fletching.
+
+Recipe files live in `data/recipes/<id>.yaml`.
+
+### Recipe vs MadeFrom
+
+- **Recipes** (`data/recipes/`) use a station (fire, range, furnace, anvil, etc.). The player must be near the station object.
+- **MadeFrom** (on the item YAML directly) is for item-on-item combinations that need no station. The player combines ingredients from their inventory.
+
+### Recipe YAML Reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique recipe identifier |
+| `type` | string | Recipe type (cooking, smithing, crafting, etc.) |
+| `skill` | string | Skill checked for success |
+| `level` | int | Required skill level |
+| `xp` | int | XP awarded on success |
+| `wait` | float64 | Ticks per craft cycle (default 6) |
+| `station` | []string | Station object IDs required |
+| `consume` | []ConsumeEntry | Ingredients consumed (see below) |
+| `output` | string | ItemID produced on success |
+| `fail` | string | ItemID produced on failure (optional) |
+| `message` | string | Success message |
+| `fail_message` | string | Failure message |
+| `success` | SuccessFormula | Optional skill check formula (see Behaviors) |
+
+The recipe's name in menus comes from the output item's `name` field, colored using the output item's `color`.
+
+### ConsumeEntry — Multi-Item Ingredient Slots
+
+Each consume entry defines an ingredient slot with multiple valid items. The first matching item found in the player's inventory is consumed.
+
+```yaml
+consume:
+  - items: [item_id, alternative_id, ...]
+    qty: 1
+```
+
+### Station-based recipe (cooking on a fire)
+
+```yaml
+id: cook_trout
+type: cooking
+skill: cooking
+level: 15
+xp: 70
+wait: 6
+station: [fire, cooking_range]
+consume:
+  - items: [raw_trout]
+    qty: 1
+output: trout
+fail: burnt_fish
+message: "Cooked to perfection. It looks great!"
+fail_message: "You accidentally burn the trout."
+```
+
+### Station-specific recipe (range only, not fire)
+
+```yaml
+id: cook_bread
+type: cooking
+skill: cooking
+level: 1
+xp: 40
+wait: 6
+station: [cooking_range]
+consume:
+  - items: [bread_dough]
+    qty: 1
+output: bread
+fail: burnt_meat
+message: "You bake the dough into a fresh loaf of bread."
+fail_message: "You burn the bread to a crisp."
+```
+
+### MadeFrom — Item-on-item combinations
+
+Item-on-item combinations are defined directly on the output item via the `made_from` field. No recipe file needed.
+
+```yaml
+# data/items/bread_dough.yaml
+id: bread_dough
+name: bread dough
+color: "fg=bright_yellow"
+made_from:
+  - items: [pot_of_flour]
+    qty: 1
+  - items: [bucket_of_water, pitcher_of_water, vial_of_water]
+    qty: 1
+```
+
+The player uses `use flour on water` to combine them. The system finds that `bread_dough` can be made from these ingredients and produces it.
+
+### Food/Healing Items
+
+Items with `heal_value` and `eat_message` can be consumed via the `eat` command.
+
+```yaml
+id: bread
+name: bread
+color: "fg=bright_yellow"
+description: "A fresh loaf of bread, still warm from the oven."
+value: 5
+heal_value: 5
+eat_message: "You eat the bread. Warm and satisfying."
+```