Feat/manual lineup selection

README.md

@@ -20,6 +20,8 @@ player data from SofaScore, FotMob, Transfermarkt, KBStats, and Analyst.
   KBStats last-five-match-slot analysis.
 - `notebooks/05_predicted_lineups`: live predicted and confirmed lineup
   collectors.
+- `notebooks/07_squad_optimisation`: optimizer notebooks for Bundesliga Arena
+  and KickbaseKIS Arena, plus `manually_create_lineup.ipynb` for manual entry.
 - `notebooks/tests`: diagnostic notebooks that are not production pipeline steps.
 - `data/reference/kickbase`: curated Kickbase scoring and event-frequency rules.
 - `outputs/sofascore`: SofaScore match IDs, odds, team reference, form, team
@@ -32,9 +34,15 @@ player data from SofaScore, FotMob, Transfermarkt, KBStats, and Analyst.
   and are not resolved to canonical identities.
 - `outputs/kbstats`: KBStats player snapshots.
 - `outputs/derived`: multi-source normalized outputs.
+- `outputs/optimized_squad`: timestamped optimizer exports.
+- `outputs/selected_lineups`: canonical per-arena selected-lineup JSON snapshots.
+  A newer confirmed selection replaces only that arena's file.
 - `archive`: superseded notebooks, historical data, and any unique recovered
   Jupyter checkpoints.
 - `project_paths.py`: the authoritative filesystem interface used by notebooks.
+- `selected_lineups.py`: shared selected-lineup persistence and replacement prompts.
+- `manual_lineup_helpers.py`: shared non-solver player-pool, rule, and validation
+  logic used by the manual lineup notebook.
 
 Generated JSON, CSV, and debug HTML must be written through `project_paths.py`;
 do not write generated files beside a notebook or into the project root.
@@ -49,6 +57,12 @@ python -m pip install -r requirements.txt
 jupyter lab
 ```
 
+Run the automated checks with:
+
+```powershell
+python -m pytest
+```
+
 The existing `.venv` stays at the root because moving a virtual environment can
 invalidate absolute paths stored inside it. The scraping notebooks expect a
 compatible Chrome installation; their current configuration targets Chrome 150.
@@ -61,7 +75,9 @@ are intentionally excluded because they are machine-specific or reproducible.
 
 Do not commit credentials, API tokens, browser profiles, cookies, screenshots,
 or other sensitive local material. Keep each code change and its related output
-refresh in a small, descriptive commit.
+refresh in a small, descriptive commit. A selected-lineup file represents the
+current canonical choice for one arena; replacing it is intentional rather than
+creating a timestamped history.
 
 ## Recommended pipeline
 
@@ -75,6 +91,10 @@ refresh in a small, descriptive commit.
    the newest valid timestamped file in `outputs/sofascore/team_form`.
 6. Run `notebooks/05_predicted_lineups/01_rotowire_lineups.ipynb` whenever a
    fresh RotoWire Bundesliga lineup snapshot is needed.
+7. Create the required expected-points score file in `notebooks/06_score_creation`.
+8. Run an optimizer in `notebooks/07_squad_optimisation`, or run
+   `manually_create_lineup.ipynb` to enter a formation, players, and captain
+   interactively. A confirmed selection is stored in `outputs/selected_lineups`.
 
 The Transfermarkt, KBStats, and FotMob collectors can run independently of the
 SofaScore team-reference pipeline when their own inputs are available.
@@ -97,6 +117,8 @@ SofaScore team-reference pipeline when their own inputs are available.
 | High-rated players | Latest team-form snapshot | `outputs/sofascore/high_rated_players` |
 | KBStats high-average players | Latest KBStats player snapshot | `outputs/derived/kbstats_high_average_players` |
 | KBStats last-five high-average players | Latest KBStats player snapshot | `outputs/derived/kbstats_last_5_high_average_players` |
+| Squad optimizers | Latest expected-points CSV and matchday matches | Timestamped optimizer CSV and optional selected-lineup JSON |
+| Manual lineup | Latest expected-points CSV, matchday matches, arena, formation, and player choices | Optional canonical JSON in `outputs/selected_lineups` |
 
 Missing required inputs raise errors that include the exact expected path. Start
 Jupyter from the project root for the simplest path discovery; VS Code notebook