recipe iteration

docs/content_design.md

@@ -1,9 +1,9 @@
 # Content Design — Ships & Modules
 
-First real-content iteration (June 2026). This pass defines ship hull grids
-and module surface masks only. Stats, materials, recipes, and threat costs in
-the config files are placeholders; the recipe pass and the balancing pass
-come later.
+First real-content iterations (June 2026). Pass 1 defined ship hull grids and
+module surface masks; pass 2 defined the production tree (recipes). Stats and
+threat costs in the config files are still placeholders for the balancing
+pass.
 
 ## Design principle: footprint gating
 
@@ -129,6 +129,48 @@ Maximum simultaneous (disjoint) placements: m guns — cruiser 2,
 battlecruiser 3, battleship 4; l guns — battleship 1, dreadnought 3;
 drone hangar — carrier 1.
 
+## Production tree
+
+Design principle: each game phase adds exactly one new base input chain, so
+factory complexity ramps alongside ship size.
+
+| Phase | New input | How acquired | Unlocks |
+|-------|-----------|--------------|---------|
+| early | iron_ore, copper_ore | mined | drone, frigate, destroyer; small guns and basic supports |
+| mid | titanium_ore | mined (3x slower than iron) | cruiser, battlecruiser; m guns, drone bay, weapon modifiers |
+| late | advanced_alloy | ONLY from reprocessing salvaged scrap | battleship, dreadnought, carrier; l guns, drone hangar |
+
+The advanced_alloy gate is the core loop hook: capital ship production
+requires fighting (salvaging scrap from kills and reprocessing it), not just
+mining. The reprocessing plant turns 5 scrap into iron/copper/titanium ingots
+or advanced_alloy probabilistically.
+
+Intermediate components, by tier:
+
+- **Tier 2 (early):** copper_wire (copper), steel_plate (iron), circuit_board
+  (iron + wire), building_block (iron).
+- **Tier 3 (mid):** mechanical_parts (steel + iron), targeting_unit (circuits
+  + wire), drive_unit (steel + mechanical_parts + circuit), titanium_frame
+  (titanium + steel).
+- **Tier 4 (late):** reinforced_plating (steel + advanced_alloy),
+  capital_core (targeting_unit + drive_unit + 2 advanced_alloy).
+
+Hulls and modules consume intermediates of their tier: early items are built
+from tier-2 parts, midgame items require tier-3 parts (deeper chains, more
+assemblers), capital items require tier-4 parts (and therefore combat). Hull
+items are named `<ship>_hull`; module items `<module>_module`. Every item has
+an `[items.*]` entry in visuals.toml; hull item outlines match the ship's
+fleet color from `[ships.*]`.
+
+Consistency is checked by `tools/verify_recipes.py` — re-run it after editing
+recipes, ship/module materials, or visuals:
+
+    python dota_factory/tools/verify_recipes.py
+
+It verifies every consumed item has a producer, every item has a visuals
+entry, flags orphaned items, and prints which items are reprocessing-only
+(currently exactly advanced_alloy).
+
 ## Deliberate placeholders / open questions for later passes
 
 - All new hulls have `threat.cost_formula = "0"` so enemy waves do not spawn
@@ -136,14 +178,12 @@ drone hangar — carrier 1.
   eligible, regardless of unlock level). The balancing pass should set real
   threat costs together with `default_modules` loadouts so waves spawn them
   armed.
-- All new hulls are `unlock_at_station_level = -1` (available from the start)
-  to make layout testing easy; the progression pass should stagger these.
-- Ship hull material items (`frigate_hull` … `carrier_hull`) and the new
-  module items (`laser_cannon_m_module`, `laser_cannon_l_module`,
-  `drone_bay_module`, `drone_hangar_module`, …) have no recipes yet — that is
-  the recipe pass. The old `laser_cannon_xs_module` recipe is orphaned (the
-  module was renamed to `laser_cannon_s`, consuming `laser_cannon_s_module`,
-  which already has a recipe).
+- All new hulls and all assembler recipes are `unlock_at_station_level = -1`
+  (available from the start) to make testing easy; the balancing pass should
+  stagger these so mid/lategame recipes drop as schematics from enemy defence
+  stations.
+- Recipe quantities and durations are a first guess, deliberately roughly
+  tiered (capital hulls ~60 s, drones 4 s); the balancing pass tunes them.
 - `drone_bay` and `drone_hangar` are footprint-only placeholders: the drone
   launching capability does not exist in the simulation yet, so they define
   no capability section.