add requirements for ship balancing tool

docs/requirements.md

@@ -251,3 +251,39 @@ The screen is divided into three vertical sections:
 - REQ-UI-BLUEPRINT-SAVE: A "Save" button is shown at the bottom of the blueprint panel. Clicking it serializes all current blueprints to a file named `blueprints.toml` located in the same directory as the application executable. The TOML structure matches REQ-UI-BLUEPRINT-STORAGE. If writing fails, a modal error dialog is shown describing the failure.
 
 - REQ-UI-BLUEPRINT-LOAD: A "Load" button is shown at the bottom of the blueprint panel, to the right of the "Save" button. Clicking it shows a confirmation dialog ("Load blueprints? This will replace all current blueprints.") with Confirm and Cancel buttons. Clicking Cancel closes the dialog with no effect. Clicking Confirm reads `blueprints.toml` from the same directory as the application executable, replaces all current blueprints with those from the file (in the order they appear in the file), and exits any active blueprint-related mode (blueprint placement mode, delete mode). If the file does not exist or cannot be parsed, a modal error dialog is shown describing the failure and the current blueprint list is left unchanged.
+
+## Balancing Tool
+
+A separate executable target (`balancing`) that links against `lib` but contains no main-game UI code. It provides an automated arena-based ship balancing tool. Code written exclusively for this target does not go into `lib`.
+
+### Config
+
+- REQ-BAL-CONFIG: The balancing tool reads arena definitions from a `balancing.toml` file. The file is read once at startup. If parsing fails or required fields are missing, the tool aborts with a clear error message.
+- REQ-BAL-CONFIG-GAME: Ship stats are read from `ships.toml` and defence station stats are read from `stations.toml`, using the same config loading as the main game. Formula evaluation uses the levels specified in the arena config.
+
+### Arena Definition
+
+- REQ-BAL-ARENA: Each arena in `balancing.toml` defines:
+  - A human-readable **arena name**.
+  - **Region widths** (in tiles): player buffer width, contest zone width, enemy buffer width. The arena world is pure space — no asteroid region.
+  - **World height** (in tiles).
+  - Exactly **two teams**, each with a human-readable **team name**.
+- REQ-BAL-TEAM: Each team defines:
+  - A list of **ship entries**, each specifying: ship schematic (type), level, and count.
+  - An optional list of **defence station entries**, each specifying: station type (`player_station` or `enemy_station` from `stations.toml`), level, and tile position (x, y).
+- REQ-BAL-HQ: Each team has an HQ placed automatically at the vertical center of the arena at the far end of that team's buffer zone. HQ stats are read from `stations.toml [hq]` at level 1. Team 1's HQ is at the left edge; team 2's HQ is at the right edge.
+- REQ-BAL-SPAWN: Team 1's ships spawn in team 1's buffer zone (left side); team 2's ships spawn in team 2's buffer zone (right side). Spawn positions are uniformly random within the respective buffer zone.
+
+### Simulation
+
+- REQ-BAL-SIM-ENV: Each arena simulates a pure-space environment using the same tick-based simulation as the main game. There is no asteroid, no buildings, no belts, no wave system, and no threat accumulation. Only ships, HQs, defence stations, and combat are active.
+- REQ-BAL-SIM-AI: Ships use the same AI and stats as in the main game. All ships use aggressive stance and closest-target priority. Ships with no target in sensor range advance toward the enemy team's HQ. Ships that detect an enemy in sensor range engage it as in the normal game (REQ-SHP-COMBAT, REQ-SHP-ENEMY-AI).
+- REQ-BAL-SIM-SPEED: Each arena runs its simulation at maximum tick rate (as many ticks per second as the hardware allows), with no rendering.
+- REQ-BAL-SIM-PARALLEL: All arenas are simulated in parallel, each on its own thread.
+- REQ-BAL-SIM-END: An arena fight ends when either team's HQ is destroyed or all ships of one team have been destroyed. When the fight ends, the simulation for that arena stops.
+
+### UI
+
+- REQ-BAL-UI-WINDOW: On startup the tool displays a window containing a dynamically generated vertical list of arena buttons, one per arena defined in `balancing.toml`.
+- REQ-BAL-UI-BUTTON: Each arena button displays the arena name and two columns (one per team). Each column shows the team name as a header, followed by a list of entries. The HQ is always the first entry in each column. Below the HQ, ship types are listed, followed by defence stations (if any). Each entry uses the format `surviving/total TypeName Llevel` — for example `2/3 Fighter L5` or `1/1 HQ L1`. The surviving count updates live as the simulation progresses.
+- REQ-BAL-UI-BUTTON-BORDER: While an arena's simulation is running, the button border is blue. When the fight ends, the border changes to green.