Import documentation: Shayan1/Prod/docs/superpowers/specs/2026-07-07-simulation-upgrades-design.md

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.

Shayan1/Prod/docs/superpowers/specs/2026-07-07-simulation-upgrades-design.md

@@ -0,0 +1,43 @@
+# Simulation Upgrades Design Document
+
+## Objective
+Enhance the Nash equilibrium CLI tool with better debugging, exposed advanced player models, a game inspection mode, and improved terminal UX—all without adding external dependencies like `rich`.
+
+## Architecture & CLI Interface
+
+### CLI Additions (`main.py`)
+1. **`--player <type>`**: Exposes hidden player models. Choices: `best_response` (default), `softmax`, `regret_matching`, `q_learning`.
+2. **`--inspect`**: A flag to validate a game JSON, print a readable summary (matrix and dominant strategies), and exit without running a simulation.
+3. **`--verbose`**: A flag to print internal decision-making data per round (e.g., expected payoffs, Q-values).
+
+### Terminal UX (No Dependencies)
+- Utilize standard ANSI escape codes for basic coloring (red for errors, green for success, cyan for info) to improve readability.
+- Implement robust `try/except` blocks in `main.py` around `Game.load_from_json()` to intercept standard `ValueError` exceptions. The CLI will format these into user-friendly, actionable error messages rather than raw stack traces.
+
+## Component Modifications
+
+### 1. Game Analysis (`nash/solver.py`)
+- Add `find_dominant_strategies(game) -> dict[int, int | None]`:
+  - Iterates through each player to determine if a single strategy yields a strictly higher payoff against *all* possible opponent profiles compared to every other strategy.
+  - Returns a mapping of player index to their dominant strategy index (or `None` if none exists).
+
+### 2. Player Wiring (`nash/simulation.py` & `main.py`)
+- Update `Simulation.__init__` to accept a `player_kind` string argument.
+- Use `make_player` from `nash/players.py` instead of hardcoding `BestResponsePlayer`.
+- Pass hyperparameter defaults to `make_player` (or extract them from `kwargs` if we extend CLI further, but defaults are fine for v1).
+
+### 3. Verbose Debugging (`nash/players.py`)
+- Add an optional `debug_logger` callback to `BasePlayer.__init__` (defaulting to a no-op).
+- `BestResponsePlayer`, `SoftmaxBestResponsePlayer`, `RegretMatchingPlayer`, and `QLearningPlayer` will call `self.debug_logger(round_num, player_name, internal_state_dict)` during `choose()` to expose their math (e.g., Q-values, expected payoffs).
+- `main.py` will supply a lambda to `Simulation` that formats and prints this dictionary to the terminal if `--verbose` is active.
+
+## Data Flow
+1. **Load**: `main.py` parses args. If invalid JSON, prints clean ANSI error and exits.
+2. **Inspect Mode**: If `--inspect`, print game matrix, run `find_dominant_strategies`, print results, exit.
+3. **Simulation**: Passes `--player` choice and `--verbose` logger to `Simulation`.
+4. **Execution**: During `sim.run()`, players log internal state via callback. Post-simulation cross-checks execute normally.
+
+## Testing
+- Add tests in `test_solver.py` for `find_dominant_strategies`.
+- Add tests in `test_simulation.py` to ensure `Simulation` correctly instantiates `q_learning` and other models via the factory.
+- Ensure malformed JSON triggers the expected UX error path in CLI tests.