From 19d0836e2bf484c73219f0117b9e224704716eb7 Mon Sep 17 00:00:00 2001
From: Jared Miller <jared@smell.flowers>
Date: Mon, 16 Feb 2026 16:21:46 -0500
Subject: [PATCH] Add crafting system documentation

---
 docs/how/crafting.rst | 86 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 docs/how/crafting.rst

diff --git a/docs/how/crafting.rst b/docs/how/crafting.rst
new file mode 100644
index 0000000..c1247c6
--- /dev/null
+++ b/docs/how/crafting.rst
@@ -0,0 +1,86 @@
+====================
+crafting and recipes
+====================
+
+the crafting system lets players combine materials to create new items. recipes
+are defined in TOML files, loaded at startup, and executed via the ``craft``
+command.
+
+recipe structure
+================
+
+recipes live in ``content/recipes/`` as TOML files. each defines:
+
+- ``name`` - unique identifier (lowercase, underscores)
+- ``description`` - what you're making (shown in recipe listings)
+- ``ingredients`` - list of thing template names (duplicates = need multiples)
+- ``result`` - thing template name to spawn
+
+example::
+
+    name = "wooden_table"
+    description = "Craft a sturdy table from planks and nails"
+    ingredients = ["plank", "plank", "plank", "nail", "nail"]
+    result = "table"
+
+all ingredient and result names must match existing thing templates in the
+``thing_templates`` registry.
+
+loading
+=======
+
+``load_recipe(path)`` parses a single TOML file into a Recipe dataclass.
+``load_recipes(dir)`` walks the directory and loads all ``.toml`` files.
+
+the global ``recipes`` dict (keyed by name) is updated at server startup in
+``server.py``. recipes are immutable after load.
+
+crafting
+========
+
+``cmd_craft(player, args)`` executes the crafting flow:
+
+1. parse recipe name from args (case-insensitive, prefix matching)
+2. find matching recipe (error if ambiguous or not found)
+3. count required ingredients via ``Counter()``
+4. count available items in player inventory
+5. check all ingredients present (list missing if not)
+6. verify result template exists in ``thing_templates``
+7. consume ingredients (remove from world)
+8. spawn result via ``spawn_thing``, add to inventory
+9. send success message
+
+ingredient counting uses python's ``Counter`` to handle duplicates. "2x plank"
+means the ingredients list contains ``"plank"`` twice.
+
+browsing recipes
+================
+
+``cmd_recipes()`` shows available recipes:
+
+- no args: lists all recipes with descriptions
+- with args: shows detailed recipe for a specific name (prefix matching)
+
+detail view shows ingredients with counts ("2x plank, 2x nail") and the result
+item. ambiguous prefixes are detected and reported.
+
+materials
+=========
+
+existing thing templates usable as materials:
+
+- ``plank`` - wooden plank
+- ``nail`` - iron nail
+- ``table`` - wooden table
+- ``chair`` - wooden chair
+
+new materials require adding thing templates to ``things.py`` and
+creating recipes that reference them.
+
+code
+====
+
+- ``src/mudlib/crafting.py`` - Recipe dataclass, loading, registry
+- ``src/mudlib/commands/crafting.py`` - craft and recipes commands
+- ``content/recipes/`` - TOML recipe definitions
+- ``src/mudlib/things.py`` - thing template registry