Merge dev → main (automated)

CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## v0.1.8 (2026-07-29)
+### Features
+- E-1: Add per-run card ownership tracking to MonteCarloRunSummary (CG-0MRYZT4ID008PFFT)
+- E-2: Add strategy×difficulty batch runner to Monte Carlo harness (CG-0MRYZTD5Z003P4CF)
+- E-3: Add per-run market offer tracking to MonteCarloRunSummary (CG-0MRYZTLAN00958S0)
+- E-4: Add getHistory() method to EconomyLedger (CG-0MRYZTUBJ0074DJZ)
+- If two patrons are atracted in one turn, only one arrives (CG-0MRDL8YUE00007KY)
+- Golf AI: should only take cards from discard if it will use them in a swap (CG-0MR6UAKB9005I6OT)
+- Detect when running in developer mode and provide debug tools (CG-0MQZYFG3C0063DN3)
+- Dev mode detection & Debug section framework (CG-0MS217X1F0089SAM)
+- State inspector overlay with filter (CG-0MS1QC3E1003G5S4)
+- Game Event Log debug tool (CG-0MS1QC3KR004C7UQ)
+- AI Decision Viewer debug tool (CG-0MS1QC4SC006FPFM)
+- Session export in Debug section (CG-0MS1QC3RR004J4Y5)
+- Add game version to menu screen and Main Street settings panel (CG-0MR89YKN0000FK5W)
+- Improve Lost Cities AI with probabilistic card evaluation (CG-0MRAGVDL90004RVJ)
+- Gym button bar (CG-0MRDGW0DH001AA58)
+- Feudalism new card animation (CG-0MRDKXBAK001GRH0)
+- Patron animation in Feudalism (CG-0MRDL6LSS001LPCG)
+- Game over / bankruptcy has no menu button (SA-0MQW8D9BI000116A)
+### Bug Fixes
+- Ensure game servers are killed after test runs — start a new server for every test (CG-0MS35J1FX005QYDV)
+- [test-failure] EconomyLedger — Main Street integration parity > Purchase parity > purchaseUpgrade: ledger matches state after upgrade purchase — failing test (CG-0MS4B2VJV0017IMD)
+- Take Screenshot in Save / Load State (CG-0MRDJB77F0057FJG)
+### Other
+- Game Balance Process & Tooling for CSV-Driven Card Data (CG-0MRBDPFPH009Y8M0)
+- Phase 4: CI Integration for Balance Checks (CG-0MRZ0YBJ2009VFTM)
+- CI-1: Add balance-check to CI pipeline (CG-0MRZ0YMTJ0026RRB)
+- CI-2: Document baseline management in contributing guide (CG-0MRZ0YN2T0075QVT)
+- CI-3: Add balance report generation to release checklist (CG-0MRZ0YNCO003J5CN)
+- link back to the github page from the game home page (CG-0MS5BSKMX002IGW8)
+- Remove Attempt Shader button and code from Shader & Blend Spike gym scene (CG-0MR4RP7T60038NOQ)
+- Documentation update for dev mode debug tools (CG-0MS1QBONV0082TIQ)
+- Further Lost Cities AI improvements (CG-0MS0BTM8P0061VM4)
+- Implement Opponent Card Denial (Block Play) (CG-0MS4AD8G9006T5DZ)
+- Implement Optimal Investment Timing (CG-0MS4ADGX800349J0)
+- Implement Opponent Expedition Blocking (CG-0MS4ADOVB001762L)
+- Implement Endgame / Deck-Count Awareness (CG-0MS4ADXEC009MRIY)
+- Implement Score-Aware Multi-Column Strategy (CG-0MS4AE5W1009VEF5)
+- Migrate remaining legacy addButton calls in GymAudioFeedbackScene and GymTokenPileViewScene (CG-0MS16TPI9002HLLH)
+- Create GymButtonBar component (CG-0MS0ZJEE5003TVDA)
+- Integrate GymButtonBar into GymSceneBase (CG-0MS0ZJPGY0086Z4O)
+- Remove legacy addButton/addButtonAtAnchor from GymSceneBase and add per-scene tests (CG-0MS16UGQP009W0GH)
+- Migrate Gym scenes to use GymButtonBar (batch 1: simple scenes) (CG-0MS0ZJPH4006CB7A)
+- Migrate Gym scenes to use GymButtonBar (batch 2: multi-row scenes) (CG-0MS0ZJPH4008UY1U)
+- Update documentation for GymButtonBar (CG-0MS16UOBZ007RPBZ)
+- Generalize Flu epidemic game logic and move configuration into CSV (CG-0MR91VWHG005Q2E7)
+- Tests: generalized duration-mitigation for all DurationEventCards (CG-0MS0Z9XDF001TAD4)
+- Tests: second DurationEventCard CSV loading and resolution (CG-0MS0ZAOUP00257Y0)
+- Add second DurationEventCard to CSV (CG-0MS0ZAXTD004QV59)
+- Implement: generalize duration-mitigation logic (CG-0MS0ZAF6M0061FPX)
+- Range of arc needs to be from 1 to 360 (CG-0MRDHN5VW0008IIF)
+- HUD Components Demo polish (CG-0MRDJRUF2003L6PI)
+
 ## v0.1.7 (2026-07-23)
 ### Features
 - Narrow Main Street HUD header to avoid overlapping undo button (CG-0MQS25QSO0031OHU)

README.md

@@ -64,8 +64,10 @@ tableau-card-engine/
 The engine provides a reusable HUD component library under `src/ui/` that
 standardises overlay, sidebar, and button UI across all example games.
 Components include HelpPanel, SettingsPanel, OverlayManager, Parameterized
-Overlay, CardGameScene base class with initHelpPanel/initSettingsPanel
-helpers, and depth conventions for consistent layering.
+Overlay, GymButtonBar (reusable button bar with left/center/right zones
+and automatic row wrapping), CardGameScene base class with
+initHelpPanel/initSettingsPanel helpers, and depth conventions for
+consistent layering.
 
 See [Shared HUD Components](docs/DEVELOPER.md#shared-hud-components) in the
 Developer Guide for full documentation and usage examples.
@@ -89,7 +91,7 @@ Developer Guide for full documentation and usage examples.
 | Sushi Go! | `example-games/sushi-go/` | Card drafting game (human vs. AI). Pick and pass hands over 3 rounds, collect sets of sushi dishes, and score the most points |
 | Feudalism | `example-games/feudalism/` | Engine-building card game (human vs. AI). Collect gem tokens, purchase development cards for bonuses, attract nobles, and reach 15 prestige to win. Checkpoint autosaves after each turn (human + AI) with startup recovery |
 | Lost Cities | `example-games/lost-cities/` | Two-player expedition card game (human vs. AI). Bet on up to 5 colored expeditions across a 3-round match with investment multipliers, ascending-play rules, and cumulative scoring |
-| Main Street | `example-games/main-street/` | Single-player tableau builder. Buy businesses/upgrades/events, place businesses on a 10-slot street rendered as a responsive 2x5 grid, and optimize score over 20 turns. **Multi-Use Card Economy**: cards can be held in hand for synergy bonuses; staff cards expand hand capacity with ongoing costs. Market cycles each turn. Tutorial overlay zones are defined in a separate SLL layout file (`main-street-tutorial.layout.json`) composed with the base layout. |
+| Main Street | `example-games/main-street/` | Single-player tableau builder. Buy businesses/upgrades/events, place businesses on a 10-slot street rendered as a responsive 2x5 grid, and optimize score over 20 turns. **Multi-Use Card Economy**: cards can be held in hand for synergy bonuses; staff cards expand hand capacity with ongoing costs. Market cycles each turn. Tutorial overlay zones are defined in a separate SLL layout file (`main-street-tutorial.layout.json`) composed with the base layout. Balance analysis tools are specified in the [Balance Process & Tooling PRD](docs/main-street/prd-balance-process-and-tooling.md). |
 | Scenario: Tutorial | `example-games/main-street/scenes/MainStreetTutorialScene.ts` | Guided introduction to Main Street. Non-interactive tutorial overlays walk through the market, street placement, synergies, events, and scoring. Easy difficulty, 25 turns. Accessible from the Game Selector. |
 
 More games are planned: Coloretto.
@@ -130,6 +132,12 @@ Main Street can optionally route mapped SFX keys through a ToneForge-backed modu
 
 For detailed development guidance, see [`docs/DEVELOPER.md`](docs/DEVELOPER.md).
 
+## Main Street Balance Documentation
+
+- **[Balance Process & Tooling PRD](docs/main-street/prd-balance-process-and-tooling.md)** — Comprehensive specification for game balance review process, micro/macro metrics, CLI tools, baseline management, and implementation roadmap.
+- **[Balancing Methodology](docs/main-street/balancing-methodology.md)** — Technical description of the `run-balance-cards` balancing algorithm.
+- **[Monte Carlo Sample Results](docs/main-street/monte-carlo-sample-results.md)** — Example output from the Monte Carlo balance simulation harness.
+
 ## AI Assisted Development
 
 To use pi to assist with Phaser development, clone the Phaser repository into the parent directory and install it as a pi package. For example, from this repository root: