Balance: easy AI stays smaller; balance runs documented

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/BALANCE.md

@@ -0,0 +1,51 @@
+# Balance runs
+
+Whole games played headless by the AI brain on every side (`src/balance.rs`), deterministic per seed:
+
+```bash
+cargo test --release balance_ -- --ignored --nocapture --test-threads=3
+BALANCE_SEEDS=16 cargo test --release balance_difficulty -- --ignored --nocapture   # more seeds
+BALANCE_PAIR=0,1 ...       # one difficulty pairing only (0 easy, 1 medium, 2 hard)
+BALANCE_TRACE=1 ...        # wave runs: a status line every two minutes
+```
+
+- **balance_difficulty** – duels of two AI masters (112x112, no hero waves, 45 min); the sides swap
+  every other seed. Undecided games count as draws.
+- **balance_talents** – four AI masters (medium), each held to one talent branch, the branches moving
+  round the four starts; placement by survival and strength.
+- **balance_waves** – one AI master alone against the hero waves (96x96, 40 min).
+
+## Findings and changes (2026-11-06)
+
+First runs showed:
+- AI masters stopped growing after their build order (99 room tiles, 24 creatures from minute 10).
+- They mined one vein at a time and only below 1500 gold.
+- They fought hero waves piecemeal and never cast spells.
+- "Hard" attacked even when weaker (boldness 0.9) and was no stronger than "easy".
+
+Changes:
+- AI masters keep building lairs and gardens up to 24 / 50 / 80 beds (easy / medium / hard), and a
+  bigger treasury when the old one is nearly full.
+- They mine several veins (one per three imps) whenever gold is below 1.5 paydays + 1000.
+- Defence: with intruders in the dungeon the rally flag goes on them, the master casts lightning on
+  them and heals his hurt creatures; an attack is called off to defend.
+- Boldness (own army / enemy army needed to attack): easy 1.0, medium 1.2, hard 1.35.
+- Builder talent: imps dig +15% and rooms cost -10% per level (was +10% / -6%).
+
+Results after the changes:
+
+| | before | after |
+|---|---|---|
+| one master vs waves: fallen of 8 (easy/medium/hard) | 2 / 3 / 4 | 2 / 2 / 2 |
+| duels, 16 seeds: easy vs medium | 6 : 6 | 3 : 6 |
+| medium vs hard | 5 : 6 (8 seeds 3 : 2) | 5 : 6 |
+| easy vs hard | 3 : 7 | 3 : 7 |
+| talents, average place (builder / warlord / warlock / merchant) | 3.3 / 1.9 / 3.0 / 1.9 | 3.1 / 2.1 / 2.5 / 2.3 |
+
+Notes:
+- The noise is about ±2 wins at 16 seeds; medium vs medium ended 5 : 7.
+- The AI uses only lightning and heal, so Warlock is still worth more to a human player than the
+  tournament shows.
+- Builder pays off where space, not gold, limits building; AI dungeons are bounded by their radius.
+- One map seed (1333) never brings heroes to the master. It shows as "wave 11, heroes 0" in the
+  wave table and is a map outlier.