feat: recipe system, combining items, cooking skill

1 files changed, 68 insertions, 0 deletions

diff --git a/worldbuilding_guide/items.md b/worldbuilding_guide/items.md
new file mode 100644
index 0000000..73f497b
--- /dev/null
+++ b/worldbuilding_guide/items.md
@@ -0,0 +1,68 @@
+## Items
+
+```yaml
+id: bronze_pickaxe
+name: bronze pickaxe
+aliases: ["pick", "pickaxe"]
+description: "A sturdy bronze pickaxe."
+value: 10
+stackable: false
+equip_slot: main_hand        # optional — where it equips
+weapon_type: melee            # optional — melee or ranged
+stats:                        # optional — combat bonuses
+  attack_bonus: 2
+  strength_bonus: 1
+speed: 5                      # ticks between attacks
+tool_type: pickaxe            # used by gather behaviors that require "tool: pickaxe"
+tool_speed: 2                 # reduces gather wait time
+```
+
+Key item (quest token, not equippable):
+```yaml
+id: pass_stub
+name: pass stub
+description: "A crumpled slip of paper stamped with the guard's seal."
+value: 0
+stackable: false
+```
+
+---
+
+## Firemaking
+
+```yaml
+id: logs
+name: logs
+fire_level: 1         # firemaking level required
+fire_xp: 40           # XP for burning/stoking
+burn_ticks: 24        # how long the fire burns
+```
+
+## Food / Healing
+
+```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         # positive = heal, negative = damage
+eat_message: "You eat the bread. Warm and satisfying."
+```
+
+## MadeFrom — Item Combinations
+
+Define what items combine to make this item. Used by the `use` command.
+
+```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]
+    qty: 1
+```
+
+Each entry is an ingredient slot. Multiple `items` means any of them works. The first matching item found in inventory is consumed. See also `recipes.md` for station-based recipes.