Document the in-game smoke harness

The UI hooks are no longer an untested surface: BalatroSmoke boots the
real game and asserts the tooltip, clash, caution, discovery and card
materialize paths against live game state. All 7 pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -176,5 +176,30 @@ Three-layer split; `JCA` is the single global namespace:
   in `before`, so every enhancement payoff that reads them in `individual` —
   Golden Ticket, Glass, Stone, Driver's License — is looking at cards it has
   already eaten.
-- The UI hooks are the only untested-in-game surface; if a tooltip regression is
+- The UI hooks used to be the untested surface. They are now covered in the real
-  reported, suspect the `aut.info` entry format first and check the lovely log.
+  game by the smoke harness (see below). If a tooltip regression is reported,
+  run it, then suspect the `aut.info` entry format and check the lovely log.
+
+## In-game smoke tests
+
+`lua test.lua` stubs the game, so it cannot tell you that vanilla accepted the
+tooltip format or that a card is actually animating. The smoke harness runs the
+real engine — real `Card` objects, the real `Card:generate_UIBox_ability_table`
+pipeline, a real overlay `UIBox` — with no clicking:
+
+```sh
+~/Documents/BalatroSmoke/run.sh JokerComboAdvisor
+```
+
+It boots the game, runs `scenarios/JokerComboAdvisor.lua`, quits, and prints a
+pass/fail report (non-zero exit on failure). Close Balatro first; it needs a clean
+boot. Scenarios live in the harness repo, not here.
+
+It covers the surfaces this repo's tests cannot reach: the hover tooltip naming a
+partner, the clash and caution lines, discovery on emplace, and — the reason it
+exists — that catalog cards really do `start_materialize` on tab build *and* on
+page switch (asserted via `card.dissolve > 0` in the live UIBox).
+
+The harness suppresses every save path and verifies from outside that no discovery
+state leaked, so running it can never spoil the catalog. Do not "fix" that by
+reversing writes after the fact — a crashed scenario would skip the reversal.