fplkit 2.8.0__tar.gz → 2.9.0__tar.gz

{fplkit-2.8.0 → fplkit-2.9.0}/.agents/TOOLS.md

@@ -28,17 +28,25 @@ Table mode is the mirror image: the table on stdout, and warnings, progress and
 for a nonzero exit on stderr — so a script reading table output can silence the commentary
 with `2>/dev/null` without losing the table, whichever command it runs.
 
+Every scoring command's `metadata.warnings` can carry a feed coverage entry — one of
+`understat_coverage_low`, `adjusted_npxg_coverage_low`, `consistency_coverage_low`,
+`history_prior_coverage_low`, `gw_history_coverage_low`, `fixture_ratings_coverage_low` —
+saying a data feed reached too little of the player pool and what the scores fall back to;
+`fpl waivers`, and the draft columns of `fpl player` and `fpl stats`, add `draft_squads_unread`
+for a rival squad the ownership read could not fetch. Read them before trusting a ranking:
+see [Feed coverage warnings](../docs/command-reference.md#json-output).
+
 ## CLI Commands
 
 | Command | Description | JSON | Format | Experimental | Pattern |
 |---------|-------------|------|--------|-------------|---------|
 | `init` | Set up fpl-cli with your FPL IDs and optional features | No | General | No | direct-api |
-| `status` | Show FPL gameweek status and upcoming deadlines. JSON `metadata` carries `gameweek`, `format` and `season` (hyphenated label, e.g. `2026-27`) - `season` is the directory segment skills must use when writing alongside fpl-cli's own reports | Yes | General | No | direct-api |
-| `doctor` | Check the setup for dead IDs, stale data, and config problems: resolves each configured ID against the live API (reporting the team/league name back so a wrong-but-valid ID is visible), verifies per-team data files (team ratings, managers, season preview intel, finances, player prior) describe the current season's clubs, reports whether the calibrated quality ceilings were measured against the newest completed season (the one season-derived artefact frozen in code, so a rollover with no recalibration leaves the scoring scale anchored to a cohort that has turned over), and reports which config/data/cache directories are in use. With `--providers`, probes the external data sources instead: live shape-and-volume checks against the FPL and Draft APIs, the vaastav and Core-Insights datasets, Understat, and football-data.org, including that every club resolves across sources and that players actually join by name (both Understat checks call the enrichment's own gate and matcher on the payload the scoring commands scan, so probe and runtime cannot disagree; a club resolving does not mean its players' names line up) and that the Core-Insights per-gameweek files parse to records through the parsers the scoring commands use (the drift that otherwise surfaces as plausible but wrong output). Distinguishes broken (needs a fix today) from stale (self-corrects). Exits non-zero when something is broken | Yes | General | No | direct-api |
+| `status` | Show FPL gameweek status and upcoming deadlines. JSON `metadata` carries `gameweek`, `format` and `season` (hyphenated label, e.g. `2026-27`) - `season` is the directory segment skills must use when writing alongside fpl-cli's own reports. `data.gameweek_info` carries `finished` beside `bonus_confirmed` and `league_tables_updated`, read from FPL's processing feed (`event-status`) for each game shown (the classic one alone when no format is configured): `true` only when every game's feed says so, `false` as soon as one says otherwise, and `null` otherwise - always `null` while the gameweek is in progress (the feed can report the days played so far as settled), and also whenever some game's feed could not answer and none said no, so with both formats `null` can mean one confirmed and the other was unreadable. `finished` comes hours before the league-table refresh (issue #424), so a skill gating a league recap should wait on `league_tables_updated` being `true`, and table mode prints both beside "Finished" | Yes | General | No | direct-api |
+| `doctor` | Check the setup for dead IDs, stale data, and config problems: resolves each configured ID against the live API (reporting the team/league name back so a wrong-but-valid ID is visible), verifies per-team data files (team ratings, managers, season preview intel, finances, player prior) describe the current season's clubs, reports whether the calibrated quality ceilings were measured against the newest completed season (the one season-derived artefact frozen in code, so a rollover with no recalibration leaves the scoring scale anchored to a cohort that has turned over), and reports which config/data/cache directories are in use. With `--providers`, probes the external data sources instead: live shape-and-volume checks against the FPL and Draft APIs (including that the draft game's club list agrees with the main game's by club code, since every draft path translates club ids through it), the vaastav and Core-Insights datasets, Understat, and football-data.org, including that every club resolves across sources and that players actually join by name (both Understat checks call the enrichment's own gate and matcher on the payload the scoring commands scan, so probe and runtime cannot disagree; a club resolving does not mean its players' names line up) and that the Core-Insights per-gameweek files parse to records through the parsers the scoring commands use (the drift that otherwise surfaces as plausible but wrong output). Distinguishes broken (needs a fix today) from stale (self-corrects, or waits on an upstream fix the tool works around). Exits non-zero when something is broken | Yes | General | No | direct-api |
 | `fixtures` | Show fixtures for a gameweek. With custom analysis on, FDR is the venue-aware ATK/DEF mean `fpl fdr` and `fpl preview` show, so one match reads the same on all three; `-m/--mode` picks `difference` (default) or `opponent`, an unrated club scores a neutral 4.0 rather than the FPL API's 1-5 difficulty, and when the ratings cannot support difficulty at all, table mode warns on stderr and JSON adds a `team_ratings_unusable` entry to `metadata.warnings` (always present, empty or not). With it off, the raw FPL API 1-5 difficulty, and an explicitly passed `-m` reports on stderr that it does not apply. JSON `metadata` carries `custom_analysis`, `fdr_scale` (`team_ratings_1_7` / `fpl_api_1_5`) and `fdr_mode` (null when it does not apply) | Yes | General | No | direct-api |
 | `player` | Look up a player's stats, xG, ownership and fixture run. Before GW10 `quality_score` blends last season's pedigree in and JSON `metadata.warnings` says so (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded), same as `fpl stats --value`; `understat_team_unmatched` joins it for any club Understat carried no players for, whose whole squad loses xG enrichment. JSON includes `ep_next` (predicted pts next GW) and `ep_this` (current GW), emitting `null` when FPL has no projection; panel shows `xPts` (ep_next) when available, omits the segment when FPL has no projection. `--detail` (`-d`) shows GW-by-GW performance and, for FWD/MID with sufficient history, xGI sustainability (per-match GI-xGI divergence -> form modifier). With `custom_analysis`: JSON adds `info.adjusted_npxg_per_90` (fixture-adjusted) and `info.raw_npxg_per_90` (Understat season avg); panel shows `adj. npxG/90: X.XXX (raw: Y.YYY)` | Yes | General | No | direct-api |
 | `stats` | List players with filtering and sorting. `--value` adds quality/value per £m columns; `--window N` sets rolling lookback (3-10) for `rolling_pts_per_m`. Before GW10, `--value` quality scores blend last season's pts/90 pedigree with this season's observation and the command says so (stderr notice quoting the observation's weight band; JSON `metadata.warnings` code `early_season_prior_informed`); when last season's history cannot be loaded they are pure observation and the notice says that instead (`early_season_small_sample`, before GW6). `understat_team_unmatched` is raised once per club Understat carried no players for, whose whole squad scores without xG. GK ceilings scale with the calendar-possible sample, reaching full scale at GW6. Sortable by `ep_next`/`ep_this` (FPL predicted points; `ep_this` is only meaningful before the gameweek's first kickoff — FPL rolls it forward to `ep_next` as each player's match finishes); both in JSON output (emit `null` when FPL has no projection; table renders `—`). Players with no projection sort to the bottom in either direction | Yes | General | No | direct-api |
-| `history` | Show historical player performance across seasons. A provider that refuses exits 1 in both output formats, carrying the upstream's own reason: the error envelope used to say only `Failed to fetch historical data` while the cause went to stderr, and table mode printed the cause to stdout and exited 0 | Yes | General | No | direct-api |
+| `history` | Show historical player performance across seasons. JSON `seasons[].team_code` is the permanent club code, not a season's 1-20 team id; `seasons[].team` carries the same number and is deprecated. A provider that refuses exits 1 in both output formats, carrying the upstream's own reason: the error envelope used to say only `Failed to fetch historical data` while the cause went to stderr, and table mode printed the cause to stdout and exited 0 | Yes | General | No | direct-api |
 | `league` | Show live league standings for Classic and Draft leagues. Classic positions are competition-ranked from cumulative totals — managers level on points share a place and the next distinct total skips the places they consumed — matching `fpl review` and the league history ledger rather than the standings API's sequential rank, which splits such a tie on fewest transfers season-to-date, a figure no column shows. Draft keeps the league's own rank, which already applies the head-to-head points-for tie-break. The Best/Worst GW Performers lists (top three; bottom five classic, bottom three draft) are the ones `fpl review` prints: managers level on the gameweek share a place (`3=`) and a tie at the cut keeps every manager in it, a hit reads `29 net pts (33 gross, -4 hit)`, and a classic user above the bottom five gets a `Your GW rank: R of N` line beside the list | No | General | No | direct-api |
 | `fdr` | Analyse fixture difficulty - easy runs, blanks, doubles. Three payloads, not one: the default call runs the agent and returns the full analysis plus `data.ratings_warning` (the team-ratings quality verdict, and with `--my-squad` also `data.predictions_stale` / `data.prediction_warnings` / `data.squad_exposure`); with custom analysis off it returns raw 1-5 FPL API difficulty (`data.easy_fixture_runs` only, `metadata.custom_analysis: false`, no ratings and so no warning); `--blanks` bypasses the agent for a schedule-only payload carrying neither the FDR analysis nor `ratings_warning`. `--blanks` mixes confirmed fixtures with predictions; when those predictions are stale, table mode warns on stderr and JSON adds a `fixture_predictions_stale` entry to `metadata.warnings` | Yes | General | No | via-agent |
 | `xg` | Analyse underlying stats: xG, xA, overperformers. The minutes floor and the window scale to the gameweeks played (`min(60 x window, 45 x gameweeks played)`, so 90 minutes over 2 GWs rather than an unreachable 360 over 6); the configured bar binds from GW9, or GW11 for `--all`. JSON `metadata` carries `window_label`, `gameweeks_played` and `min_minutes`, and `metadata.warnings` an `early_season_minutes_floor` notice while the bar is scaled, plus `understat_team_unmatched` for any club Understat carried no players for. When nothing qualifies, `data.empty_reason` says whether the floor (`below_minutes_floor`) or the data (`no_minutes_played`) caused it | Yes | General | No | via-agent |
@@ -46,18 +54,18 @@ with `2>/dev/null` without losing the table, whichever command it runs.
 | `price-history` | Show price trajectory and transfer momentum. A trend provider that refuses exits 1 in both output formats with the upstream's own reason — the error envelope used to say only `Failed to fetch price history data` while the table path named the cause | Yes | General | No | direct-api |
 | `returnees` | Track injured and suspended players due back soon, so a returnee can be claimed in draft before they are fit or planned around in classic. Reads the FPL availability news, filters to returns inside a window (`--window N`, 1-38) and through a source-aware quality bar, and diffs against the stored watchlist for week-over-week changes. Most flagged players carry no parseable return date, so date-unknown entries are the norm rather than the exception; `--enrich` searches the web for fresher timing on those and on stale-news entries (needs a Perplexity key; skips with a note without one) and shows it beside the FPL news, never over it. `--all` bypasses the quality bar and deliberately does not persist the snapshot. JSON `metadata` carries `window`, `escalation_window`, `stash_upgrade_margin`, `transitions_available`, `transitions_baseline_gameweek` (the gameweek `transition` is measured against — every run in a gameweek diffs against the last state stored before it, so a repeat run reports the same changes), `quality_bar_available`, `quality_bar_applied` and `enrichment_requested`/`_available`/`_note`/`_count`/`_rate_limited` (true when the search provider rate-limited the run even after retrying — the one failure a re-run is likely to clear); `data` is `{entries, departures}`, each entry carrying `quality.basis`/`quality.meets_stash`, `expected_return`/`return_gameweek`/`return_source`, `escalation_eligible`/`escalation_basis`, `transition`, and `enrichment` (null unless enriched) | Yes | General | No | direct-api |
 | `preview` | Run full pre-gameweek analysis and generate report. `--save` writes to `<output dir>/<season>/gw{N}-preview.md`; `--scout` writes to `<research dir>/ai-scout-reports/<season>/gw{N}-scout-preview[-referenced].md` | No | General | No | via-agent |
-| `review` | Review a completed gameweek - squad performance and standings. `--save` writes to `<output dir>/<season>/gw{N}-review.md`; `--compare-recs` reads `gw{N}-recommendations.md` from the same season directory and grades the captain, each transfer and each waiver or free-agent move against it; the captain line sets the recommended captain against the armband in captain points (raw score times that week's multiplier, Triple Captain included), the armband being the vice's when the captain played no minutes, and adds the change to the team total when the recommended captain was in the side that scored; one who was not in the squad or played no minutes is labelled so rather than priced at 0; on a wildcard or free hit week, where the recommendation is a squad, each player brought in is graded against the recommended 15 instead, and a recommended name that fits more than one player is left ungraded with a warning on stderr rather than matched to the first; a part of the file it could not read (the captain, the transfers or the waivers) is left ungraded the same way, the warning naming the file, rather than grading every move unadvised, and a file nothing could be read from is not compared at all. Under `--summarise` the personal analysis is handed next gameweek's fixtures — every club's opponent and venue plus each squad player's positional FDR (1-7 team ratings with custom analysis on, the FPL API's 1-5 difficulty with it off, carrying the same scale footer and unrated-club caveat the FDR tables print, plus any warning that the ratings cannot support difficulty) — so its "Next Week" calls are grounded in fixtures rather than in one week of points; with no next gameweek to look at, that section is narrowed to fixture-independent observations and points at `fpl gw-prep`, and a gameweek already played is marked retrospective. The answer is then checked back against that block — a cited FDR the block never printed, or any fixture claim made without one — and against the sections its prompt asked for: an answer missing a `## ` heading, ending mid-sentence, or that the provider cut off at its token ceiling is retried once, told what the last draft lacked (a refused answer is flagged but never retried, and a retry that errors keeps the first attempt), and a still-incomplete one is warned about on stderr (detail in `data/debug/synthesis_corrections.txt` under `--debug`) and carries the same list as a callout in the saved report. The summary is an add-on the review does not depend on: the two provider roles resolve independently, and a role with no usable key is skipped with the reason on stderr (`Community narrative skipped: ...` / `Personal analysis skipped: ...`) while the review prints, saves and exits 0 — so one key produces that half rather than nothing, and a saved report names each skipped half in a warning callout of its own. A gameweek it cannot resolve - one still being played, an id the season does not have, a season with nothing finished yet - is refused with the specific reason on stderr and exit 1; stdout carries the review or nothing | No | General | No | via-agent |
-| `league-recap` | Recap a completed gameweek - awards, standings, and banter. Saves to `<output dir>/<season>/gw{N}-league-recap[-draft].md`, opening on a fixed `# Gameweek N Recap: <league name>` title the report writes itself, editorial or not; the editorial is asked for a `## ` headline beneath it and never a title, and whatever heading it opens with anyway is demoted to that level or, when it only restates the title, dropped, so the model's heading is never the document's (issue #349). Records every run into the league history ledger (`<data dir>/league_history/`) as a side effect, backfilling classic gaps at a coarse tier automatically; `--backfill-detail` rebuilds earlier gameweeks in full (one request per manager per gameweek). A rebuild keeps the name and position already recorded for each player instead of restamping them from today's bootstrap, and never drops a code the gameweek already resolved; it reads the earliest recorded row rather than the newest, so a gameweek an older version already restamped is repaired rather than re-copied. The club is not carried but *derived*, from the gameweek's own fixtures: FPL's live data records which fixtures each player's club played, so a double gameweek settles his club outright and a single narrows it to two, with one `element-summary` request spent only where today's club is absent from that pair (proof he has moved); today's club being one of the two is left unanswered rather than assumed, so a recorded club still wins there. That reaches the two cases a carry structurally cannot — a first capture and a coarse-to-detailed upgrade, neither of which has a recorded squad — and it supersedes a stale recorded club rather than preserving it, with `league_history_club_rederived` naming how many were replaced. A club that blanked has no fixture to intersect and falls back to the recorded club, then today's; name and position are not derivable from fixtures at all and stay carry-only. Everything the gameweek itself answers (points, cards, pick flags, blank status) is still re-derived, and a `league_history_identity_carried` warning names how many players were kept. A rebuild likewise never writes away a league position or cumulative total it cannot re-derive: draft has no per-manager history endpoint and its standings describe a later gameweek, so a replayed draft gameweek keeps the figures already recorded (`league_history_standings_carried`) instead of nulling them, which used to cost the ledger every position that gameweek held and collapse the streaks built on them. Where they were already lost, every run restores them from the ledger itself — the last superseded line that recorded them (a gameweek captured repeatedly while it was still settling holds a stale position in its first capture and the settled one in its last), or a cumulative total re-summed from earlier gameweeks — with no flag and no request (`league_history_standings_repaired`); a draft gameweek's table is derivable from `gross_points` alone at the league's start gameweek. A draft row also records the waiver claims its manager lost to a rival (`lost_claims`, kept apart from `transactions` because nothing moved — no points, no net, and never the denial that is the cascade of the manager's own accepted claim), so an outbid manager is not written into the permanent record as one who never tried; a gameweek captured before that field existed reads it back as unrecorded rather than as "lost none", is named by the coverage report, and is re-recorded by `--backfill-detail` while the league's transaction feed still serves it; a replay that finds fewer claims than the gameweek recorded keeps the recorded list (`league_history_claims_carried`). Those claims also make the waiver wire's races visible (issue #330): the editorial's waiver roster closes with every player more than one manager claimed, who won him and who was beaten to him at what priority, and a week where at least three managers claimed the same player (`MOST_CONTESTED_MIN_CLAIMANTS`) and one of them can be seen to have won him gets a Most Contested award beside Waiver Genius and Waiver Disaster — derived from the manager rows by `contested_draft_claims()`, never recorded, never a report section of its own, and absent from `--format json`, whose rows already carry the `lost_claims` and `transactions` they are regrouped from. The editorial is told to write each race as its own clause and never fold two into one ("respectively"), and is checked against the races afterwards (issue #357): a manager it names as beaten to, or winning, a contested player in a role that player's line does not give them triggers one regeneration told which claims were wrong (a retry that errors keeps the first attempt), and a kept editorial that still fails is saved as written with the wrong claims named on stderr, in a `synthesis_contested_misattribution` JSON warning, and in a callout above the editorial in the report. The same retry and reporting cover two checks on either format (issue #359): a manager's net overall, pre-hit swing or another move's swing pinned on one named move (`synthesis_net_misattribution`), and a tie word ("joint-lowest", "tied for last", "joint-seventh") on a gameweek score or league position no two managers hold (`synthesis_unsupported_tie`); and a third on draft (issue #390): the net overall, or the other kind's figure, said of one kind of a manager's moves ("his waiver moves netted +3 overall" of a -1 waiver and a +4 free-agent pickup, `synthesis_kind_net_misattribution`), for which a roster line that mixes kinds now gives each kind's net beside the net overall. The prompt's GW Standings section names the week's highest and lowest scores, every shared score and position (Pos, and Prev where any is shared) and any season totals the league's tie-break placed apart, so "joint" has a line to be held to, and the roster lines call the manager's net "overall". Biggest Bench Haul (both formats) ranks on the best legal XI's gain over the XI that counted — one keeper, the eight legal formations, the doubled player held in place — never on the bench's raw sum, which counted a keeper who could not have played and outfielders no formation had room for (issue #350); its detail names the swap, a manager with bench points but no better XI is no candidate, and the raw sum stays on the row as `bench_points` (the API's `points_on_bench`) because the coarse tier can record nothing else. Coverage gaps and capture warnings go to stderr; the command exits 0 even when the store is unreadable. `--format json` emits one row per manager (the captured ledger row shape) plus `metadata.coverage`, `season_phase`, `notes_pack`, `synthesis_summary`, `warnings` (always present, each entry a stable `code` plus rewritable `message` - codes listed in [Command Reference](../docs/command-reference.md#league-history)) and `first_capture_store_path` (always present; the partition directory on a first capture, `null` after). Fines are ruled *and recorded* against every captured gameweek, backfilled ones included: the detailed replay rules every configured rule, the coarse tier rules only what cohort points support (`last-place`, `below-threshold`) and records that `red-card` went unruled. `last-place` is ruled against every manager level on the gameweek's lowest score rather than whichever of them the cohort's arrival order reached first; because rulings are frozen at capture and the ledger is append-only, gameweeks recorded before that was true are swept on every run and the recorded ruling appended against the managers they left out, with no flag and no request (`league_history_tied_last_place_repaired`) — and where the row data cannot settle who was level, since the gameweek does not record whether it was ruled on gross or net points, the manager is named by `league_history_tied_last_place_ambiguous` rather than fined on a guess. Season totals print under `Season Fines` on console and as a `# Season Fines` report section, but only at the two milestone gameweeks (GW19 and the finale) - every other week those surfaces stay a this-week view and `league-fines` answers the season question on demand. The `## Season Fines` prompt section and `metadata.season_fines` are ungated: the editorial gets the running totals every week as optional colour (never a required beat), and a scripted consumer sees no calendar-driven appearance and disappearance. Bottom-half gameweeks and green-arrow droughts no longer surface as streaks at all (their run only drives the season count). Streak conditions also keep reset-surviving season occurrence counts ("their sixth gameweek win of the season"), each surfaced on its own rule (see [Command Reference](../docs/command-reference.md#league-recap) for the per-count table): wins and last places on multiples of 3 plus any second-half first, captain blanks and waiver hauls/backfires on multiples of 5, hits on multiples of 3, weeks on top on multiples of 5, bottom-half gameweeks on multiples of 10 in the second half only, and green-arrow droughts on an unbroken run of 5 or 10 (gameweeks spent leading the league never count towards a drought — the leader could not have climbed). Some counts carry same-week peers alongside the milestone — past a fixed floor for counts that stay small, or within a relative window for counts that climb all season. A firing count reaches the report's `## Season Counts` subsection and the editorial's League History section; at the two milestone gameweeks both surfaces carry every nonzero count as the season set-piece. Every line states its span and any not-judged gameweeks beside the number, and every nonzero count is emitted in `metadata.notes_pack.season_count_entries` regardless. A recap of the most recently finished gameweek keeps working once the next gameweek has started: the league table describes that later gameweek from its deadline onward, so the run takes the replay path (figures from each manager's own gameweek history, positions and cumulative totals derived rather than read off the table) and raises a `league_standings_moved_on` warning, instead of reconciling two different gameweeks' numbers against each other and exiting 1 with the ledger row unwritten. `--summarise` with no usable synthesis key no longer aborts the run: the recap, report and ledger capture all proceed, and a `synthesis_provider_unavailable` warning says the editorial was skipped; an editorial the provider cut off at its token ceiling is regenerated once, told it was cut off (a refused editorial is never regenerated, even with a wrong claim in it), and one the provider stopped early on that is still the one kept is written out as it stands with the reason on stderr, a `synthesis_stopped_early` warning in JSON, and a line in the report's warning callout above the editorial (issue #372). A gameweek that cannot be resolved at all exits 1 in both output formats - it used to exit 1 under `--format json` with a generic `"Could not resolve a gameweek to recap."` and 0 in table mode - and the resolver's own reason (`Gameweek 7 is not yet finished`) now reaches the error envelope and the stderr prose alike. On the league's opening gameweek only (GW1, or its own `start_event`), each classic manager's FPL-wide prior-season record — seasons played, last season's points/rank/top-% finish, best season — is fetched from the manager-history endpoint (one request per manager, that gameweek only, and only with `--save`/`--output` or `--summarise`; a league created after GW1 shares the fetch with its league-start offset) and rendered as a `# Prior Seasons` report section and a locked `## Prior Seasons` prompt section with an explicit count; tenure is phrased FPL-wide because entry and league IDs are reissued each season, and a manager with no record or a failed fetch is named as such rather than omitted. Nothing of it reaches the ledger or the JSON rows; draft has no such endpoint and no such section | Yes | General | No | via-agent |
+| `review` | Review a completed gameweek - squad performance and standings. `--save` writes to `<output dir>/<season>/gw{N}-review.md`; `--compare-recs` reads `gw{N}-recommendations.md` from the same season directory and grades the captain, each transfer and each waiver or free-agent move against it; transfer rows that sell the same player are read as ranked alternatives for one sale and graded once, as followed if any candidate was bought and as one miss otherwise; waiver rows that share a drop are read as one conditional chain, each claim keeping its own row: the move made is credited to the claim it filled wherever that claim sits in the chain, a claim below the one that landed is marked not needed rather than not executed, a claim skipped above one that was made is a miss, and a chain abandoned part-way is one miss where it was left, the claims below that marked as fallbacks not reached; the captain line sets the recommended captain against the armband in captain points (raw score times that week's multiplier, Triple Captain included), the armband being the vice's when the captain played no minutes, and adds the change to the team total when the recommended captain was in the side that scored; one who was not in the squad or played no minutes is labelled so rather than priced at 0; on a wildcard or free hit week, where the recommendation is a squad, each player brought in is graded against the recommended 15 instead, and a recommended name that fits more than one player is left ungraded with a warning on stderr rather than matched to the first; a part of the file it could not read (the captain, the transfers or the waivers) is left ungraded the same way, the warning naming the file, rather than grading every move unadvised, and a file nothing could be read from is not compared at all. Under `--summarise` the personal analysis is handed next gameweek's fixtures — every club's opponent and venue plus each squad player's positional FDR (1-7 team ratings with custom analysis on, the FPL API's 1-5 difficulty with it off, carrying the same scale footer and unrated-club caveat the FDR tables print, plus any warning that the ratings cannot support difficulty) — so its "Next Week" calls are grounded in fixtures rather than in one week of points; with no next gameweek to look at, that section is narrowed to fixture-independent observations and points at `fpl gw-prep`, and a gameweek already played is marked retrospective. The answer is then checked back against that block — a cited FDR the block never printed, or any fixture claim made without one — and against the sections its prompt asked for: an answer missing a `## ` heading, ending mid-sentence, or that the provider cut off at its token ceiling is retried once, told what the last draft lacked (a refused answer is flagged but never retried, and a retry that errors keeps the first attempt), and a still-incomplete one is warned about on stderr (detail in `data/debug/synthesis_corrections.txt` under `--debug`, where `synthesis_meta.json` also records how many answers were judged, which was kept, and the tokens they spent between them) and carries the same list as a callout in the saved report. The summary is an add-on the review does not depend on: the two provider roles resolve independently, and a role with no usable key is skipped with the reason on stderr (`Community narrative skipped: ...` / `Personal analysis skipped: ...`) while the review prints, saves and exits 0 — so one key produces that half rather than nothing, and a saved report names each skipped half in a warning callout of its own. A gameweek it cannot resolve - one still being played, an id the season does not have, a season with nothing finished yet - is refused with the specific reason on stderr and exit 1; stdout carries the review or nothing | No | General | No | via-agent |
+| `league-recap` | Recap a completed gameweek - awards, standings, and banter. Saves to `<output dir>/<season>/gw{N}-league-recap[-draft].md`, opening on a fixed `# Gameweek N Recap: <league name>` title the report writes itself, editorial or not; the editorial is asked for a `## ` headline beneath it and never a title, and whatever heading it opens with anyway is demoted to that level or, when it only restates the title, dropped, so the model's heading is never the document's (issue #349). Records every run into the league history ledger (`<data dir>/league_history/`) as a side effect, for draft alongside each held draft's picks (`drafts/draft-{id}.json` in the draft partition, saved once while the API still serves them, since a scheduled redraft drops them for good; `league_history_draft_picks_conflict`, `_lost` (once per draft), `_unsaved` and `_unchecked` name a disagreement with the API, a draft held before anything saved it, a run that could not save, and a `league.drafts` list it could not read), backfilling classic gaps at a coarse tier automatically; `--backfill-detail` rebuilds earlier gameweeks in full (one request per manager per gameweek). A rebuild keeps the name and position already recorded for each player instead of restamping them from today's bootstrap, and never drops a code the gameweek already resolved; it reads the earliest recorded row rather than the newest, so a gameweek an older version already restamped is repaired rather than re-copied. The club is not carried but *derived*, from the gameweek's own fixtures: FPL's live data records which fixtures each player's club played, so a double gameweek settles his club outright and a single narrows it to two, with one `element-summary` request spent only where today's club is absent from that pair (proof he has moved); today's club being one of the two is left unanswered rather than assumed, so a recorded club still wins there. That reaches the two cases a carry structurally cannot — a first capture and a coarse-to-detailed upgrade, neither of which has a recorded squad — and it supersedes a stale recorded club rather than preserving it, with `league_history_club_rederived` naming how many were replaced. A club that blanked has no fixture to intersect and falls back to the recorded club, then today's; name and position are not derivable from fixtures at all and stay carry-only. Everything the gameweek itself answers (points, cards, pick flags, blank status) is still re-derived, and a `league_history_identity_carried` warning names how many players were kept. A rebuild likewise never writes away a league position or cumulative total it cannot re-derive: draft has no per-manager history endpoint and its standings describe a later gameweek, so a replayed draft gameweek keeps the figures already recorded (`league_history_standings_carried`) instead of nulling them, which used to cost the ledger every position that gameweek held and collapse the streaks built on them. Where they were already lost, every run restores them from the ledger itself — the last superseded line that recorded them (a gameweek captured repeatedly while it was still settling holds a stale position in its first capture and the settled one in its last), or a cumulative total re-summed from earlier gameweeks — with no flag and no request (`league_history_standings_repaired`); a draft gameweek's table is derivable from `gross_points` alone at the league's start gameweek. A draft row also records the waiver claims its manager lost to a rival (`lost_claims`, kept apart from `transactions` because nothing moved — no points, no net, and never the denial that is the cascade of the manager's own accepted claim), so an outbid manager is not written into the permanent record as one who never tried; a gameweek captured before that field existed reads it back as unrecorded rather than as "lost none", is named by the coverage report, and is re-recorded by `--backfill-detail` while the league's transaction feed still serves it; a replay that finds fewer claims than the gameweek recorded keeps the recorded list (`league_history_claims_carried`). Those claims also make the waiver wire's races visible (issue #330): the editorial's waiver roster closes with every player more than one manager claimed, who won him and who was beaten to him at what priority, and a week where at least three managers claimed the same player (`MOST_CONTESTED_MIN_CLAIMANTS`) and one of them can be seen to have won him gets a Most Contested award beside Waiver Genius and Waiver Disaster — derived from the manager rows by `contested_draft_claims()`, never recorded, never a report section of its own, and absent from `--format json`, whose rows already carry the `lost_claims` and `transactions` they are regrouped from. The editorial is told to write each race as its own clause and never fold two into one ("respectively"), and is checked against the races afterwards (issue #357): a manager it names as beaten to, or winning, a contested player in a role that player's line does not give them triggers one regeneration told which claims were wrong (a retry that errors keeps the first attempt), and a kept editorial that still fails is saved as written with the wrong claims named on stderr, in a `synthesis_contested_misattribution` JSON warning, and in a callout above the editorial in the report. The same retry and reporting cover two checks on either format (issue #359): a manager's net overall, pre-hit swing or another move's swing pinned on one named move (`synthesis_net_misattribution`), and a tie word ("joint-lowest", "tied for last", "joint-seventh") on a gameweek score or league position no two managers hold (`synthesis_unsupported_tie`); and a third on draft (issue #390): the net overall, or the other kind's figure, said of one kind of a manager's moves ("his waiver moves netted +3 overall" of a -1 waiver and a +4 free-agent pickup, `synthesis_kind_net_misattribution`), for which a roster line that mixes kinds now gives each kind's net beside the net overall. A fourth, on draft (issue #459), holds the editorial to not reciting a race as a list: a paragraph naming the race's player and three or more of its beaten managers (`synthesis_contested_roll_call`) earns the same retry and reporting, but as a broken brief rather than a contradiction of the data, since the sentence is true, so the retry, stderr and the report callout say that instead. The prompt's GW Standings section names the week's highest and lowest scores, every shared score and position (Pos, and Prev where any is shared) and any season totals the league's tie-break placed apart, so "joint" has a line to be held to, and the roster lines call the manager's net "overall". Biggest Bench Haul (both formats) ranks on the best legal XI's gain over the XI that counted — one keeper, the eight legal formations, the doubled player held in place — never on the bench's raw sum, which counted a keeper who could not have played and outfielders no formation had room for (issue #350); its detail names the swap, a manager with bench points but no better XI is no candidate, and the raw sum stays on the row as `bench_points` (the API's `points_on_bench`) because the coarse tier can record nothing else. Coverage gaps and capture warnings go to stderr; the command exits 0 even when the store is unreadable. `--format json` emits one row per manager (the captured ledger row shape) plus `metadata.coverage`, `season_phase`, `notes_pack`, `synthesis_summary`, `synthesis_attempts` (answers judged: 1, or 2 after a retry), `synthesis_shipped_attempt` (which of them shipped) and `synthesis_usage` (input and output tokens summed over every answer judged; all three `null` when no editorial came back), `warnings` (always present, each entry a stable `code` plus rewritable `message` - codes listed in [Command Reference](../docs/command-reference.md#league-history)) `first_capture_store_path` (always present; the partition directory on a first capture, `null` after) and `draft_picks_saved` (always present; the draft-picks snapshots this run wrote, empty on classic). Fines are ruled *and recorded* against every captured gameweek, backfilled ones included: the detailed replay rules every configured rule, the coarse tier rules only what cohort points support (`last-place`, `below-threshold`) and records that `red-card` went unruled. `last-place` is ruled against every manager level on the gameweek's lowest score rather than whichever of them the cohort's arrival order reached first; because rulings are frozen at capture and the ledger is append-only, gameweeks recorded before that was true are swept on every run and the recorded ruling appended against the managers they left out, with no flag and no request (`league_history_tied_last_place_repaired`) — and where the row data cannot settle who was level, since the gameweek does not record whether it was ruled on gross or net points, the manager is named by `league_history_tied_last_place_ambiguous` rather than fined on a guess. Season totals print under `Season Fines` on console and as a `# Season Fines` report section, but only at the two milestone gameweeks (GW19 and the finale) - every other week those surfaces stay a this-week view and `league-fines` answers the season question on demand. The `## Season Fines` prompt section and `metadata.season_fines` are ungated: the editorial gets the running totals every week as optional colour (never a required beat), and a scripted consumer sees no calendar-driven appearance and disappearance. Bottom-half gameweeks and green-arrow droughts no longer surface as streaks at all (their run only drives the season count). Streak conditions also keep reset-surviving season occurrence counts ("their sixth gameweek win of the season"), each surfaced on its own rule (see [Command Reference](../docs/command-reference.md#league-recap) for the per-count table): wins and last places on multiples of 3 plus any second-half first, captain blanks and waiver hauls/backfires on multiples of 5, hits on multiples of 3, weeks on top on multiples of 5, bottom-half gameweeks on multiples of 10 in the second half only, and green-arrow droughts on an unbroken run of 5 or 10 (gameweeks spent leading the league never count towards a drought — the leader could not have climbed). Some counts carry same-week peers alongside the milestone — past a fixed floor for counts that stay small, or within a relative window for counts that climb all season. A firing count reaches the report's `## Season Counts` subsection and the editorial's League History section; at the two milestone gameweeks both surfaces carry every nonzero count as the season set-piece. Every line states its span and any not-judged gameweeks beside the number, and every nonzero count is emitted in `metadata.notes_pack.season_count_entries` regardless. A recap of the most recently finished gameweek keeps working once the next gameweek has started: the league table describes that later gameweek from its deadline onward, so the run takes the replay path (figures from each manager's own gameweek history, positions and cumulative totals derived rather than read off the table) and raises a `league_standings_moved_on` warning, instead of reconciling two different gameweeks' numbers against each other and exiting 1 with the ledger row unwritten. `--summarise` with no usable synthesis key no longer aborts the run: the recap, report and ledger capture all proceed, and a `synthesis_provider_unavailable` warning says the editorial was skipped; an editorial the provider cut off at its token ceiling is regenerated once, told it was cut off (a refused editorial is never regenerated, even with a wrong claim in it), and one the provider stopped early on that is still the one kept is written out as it stands with the reason on stderr, a `synthesis_stopped_early` warning in JSON, and a line in the report's warning callout above the editorial (issue #372). A gameweek that cannot be resolved at all exits 1 in both output formats - it used to exit 1 under `--format json` with a generic `"Could not resolve a gameweek to recap."` and 0 in table mode - and the resolver's own reason (`Gameweek 7 is not yet finished`) now reaches the error envelope and the stderr prose alike. On the league's opening gameweek only (GW1, or its own `start_event`), each classic manager's FPL-wide prior-season record — seasons played, last season's points/rank/top-% finish, best season — is fetched from the manager-history endpoint (one request per manager, that gameweek only, and only with `--save`/`--output` or `--summarise`; a league created after GW1 shares the fetch with its league-start offset) and rendered as a `# Prior Seasons` report section and a locked `## Prior Seasons` prompt section with an explicit count; tenure is phrased FPL-wide because entry and league IDs are reissued each season, and a manager with no record or a failed fetch is named as such rather than omitted. Nothing of it reaches the ledger or the JSON rows; draft has no such endpoint and no such section. Every recap, classic and draft, also carries a Standout Players section (issue #455), read off the squads and live points the bench haul already uses: the week's top scorers in any manager's squad and its costliest blanks (2 points or fewer; in classic the one that counted for the most managers first, in draft the best by FPL's pre-season draft rank and, on a live recap from GW19, by season points per game, since the rank is never updated; a draft player neither can rank is left off, and no line states the rank or average, which only the heading and JSON carry), each with the managers he counted for, how long a blank played when it was under the hour, and any who left him on the bench, as one sentence per player that the console, a `# Standout Players` report section and a `## Standout Players` prompt section all print; `--format json` carries it as `metadata.standout_players`, every player row with the main game's `id` (under `--draft` too) and `code` beside it. A draft recap's lines also say how each player came to the manager they name (issue #458): the draft pick, the waiver or free-agent move, or the trade, the latest as of the recapped gameweek (a `-g` replay shows its own week), from a replay of the league's draft, accepted transactions and processed trades that must end where FPL's own ownership list does and match the week's squads, with the draft's picks read from the choices feed or, once it serves another draft, the saved snapshot, or, where neither has them, who drafted whom rebuilt from each manager's squad at the draft's gameweek with the earlier moves undone (the line then says "who drafted him" with no round, `round_unknown` in the JSON, and a `draft_rounds_unknown` notice replaces the warning). If the history cannot be shown complete (or a read fails, a failed trades read included once a trade has happened) the lines read without it and a `draft_provenance_unavailable` warning says why; draft rows carry `acquisition` in the JSON, classic rows do not. Before a live capture collects, it reads the recapped game's processing feed (`event-status/` on `FPLClient`, `pl/event-status` on `FPLDraftClient`, both `get_gameweek_status()`): when the feed's match days for the recapped gameweek show bonus unconfirmed or the league tables still "Updating" (`GameweekStatus.still_processing()`), it warns on stderr, in a `league_tables_updating` JSON warning and in a callout at the top of a saved report that positions and totals may be stale, and records the gameweek anyway, since a later run supersedes it and a missed draft gameweek cannot be recaptured; a reconciliation failure in that window keeps its own diagnosis and adds that it may be timing. Only a definite signal warns: an unreadable, slow (5s), reshaped or unrecognised feed is a debug log, and a replay never reads it (issue #424) | Yes | General | No | via-agent |
 | `league-fines` | Show who has been fined this season and how much of it was actually ruled, folded out of the league history ledger. Reads local files only - no network - so it works for any season still on disk (`--season 2025-26`). Nothing is re-ruled: a fine is counted exactly as its gameweek recorded it — including one `league-recap` appended against a manager who tied for last and was left out at capture. Counts, never money (`penalty` is free text; settlement and escalation are not modelled). Every gameweek that could not be ruled is named beneath the table - never captured, unreadable, captured before rulings were recorded, captured with no rules configured, or captured at a fidelity that could not rule a given rule. `--format json` emits one entry per recorded manager, fined or not, each with `counts` (zero included), `total`, `fined_gameweeks`, `ruled_gameweeks`, `unruled_gameweeks`, `first_recorded_gameweek`, `last_recorded_gameweek` and `is_fully_ruled`; `metadata` carries `season`, `fpl_format`, `league_id`, `gameweek`, `start_gameweek`, `rule_types`, `total_fines` and `qualifiers`. Exits 1 with the shared error envelope when no league id is configured for the format | Yes | General | No | direct-api |
 | `captain` | Analyse and rank captain options for next gameweek. Your squad is the default, so an absent `classic_entry_id` exits 1 with an `error` envelope naming `--global` rather than returning the global list as though it were your options; `metadata.my_squad_mode` says which list the payload holds, and `metadata.warnings` carries `captain_global_fallback` when there is no squad to rank yet (before the first deadline) or `captain_no_next_gameweek` when there is no next gameweek at all (finished season, or the next one unpublished). An entry ID that does not resolve is a failure, not a fallback, worded exactly as `squad` words it (`get_own_squad_picks`, `agents/common.py`). JSON candidates include `adjusted_npxg_per_90` and `raw_npxg_per_90` when fixture adjustment is active. Consistency tiebreaker (CV-xGI percentile) phased in GW6-10. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the GW1-9 shrinkage rather than pulled toward the position mean | Yes | Classic | Yes | via-agent |
 | `differentials` | Find differential picks - high potential, low ownership. Inverted consistency bonus (volatile players score higher, phased in GW6-10). Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage, so a quiet-starting elite is not ranked below a one-game wonder; the ownership, matchup and consistency bonuses stay pure observation; JSON `metadata.warnings` carries the early-season notice while the blend is live (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded) plus `understat_team_unmatched` for any club Understat carried no players for, table mode prints them to stderr. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing. The gameweek stamped into JSON `metadata` is fetched after the agent succeeds, not before it runs, so an unreachable API is reported as the agent's failure in both output formats rather than as a client error under `--format json` and an agent error in table mode | Yes | Classic | Yes | via-agent |
 | `targets` | Find transfer targets - high performers across all ownership. Consistency bonus (CV-xGI percentile, phased in GW6-10). Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage, so a quiet-starting elite is not ranked below a one-game wonder; the matchup and consistency bonuses stay pure observation, and the score agrees with `fpl transfer-eval`'s Outlook column; JSON `metadata.warnings` carries the early-season notice while the blend is live (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded) plus `understat_team_unmatched` for any club Understat carried no players for, table mode prints them to stderr. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing | Yes | Classic | Yes | via-agent |
 | `transfer-eval` | Compare transfer OUT player against IN candidates. JSON includes `adjusted_npxg_per_90` and `raw_npxg_per_90` per player when fixture adjustment is active. Before GW10 `quality_score` carries the value family's prior blend (matching `fpl player` and `fpl stats --value`) and `target_score` the target family's (matching `fpl targets`); the single-GW `lineup_score` keeps position-mean shrinkage. JSON `metadata.warnings` carries the early-season notice naming both blended columns, or only `target_score` when no Understat match produced a quality score. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of whichever device applies, rather than pulled toward the position mean or handed last season's standing. A name two players answer to exactly (`Henderson`) exits 1 with an `error` envelope naming both, rather than resolving to whichever the API lists first; `Name (TEAM)` or a player ID picks one | Yes | General | Yes | via-agent |
 | `allocate` | Select mathematically optimal 15-player squad within budget. At `--horizon >= 2` the solver ranks on the value family's GW1-9 prior blend (last season's pedigree weighted by confidence); players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of it rather than handed last season's standing, and stay in the solver pool; JSON `metadata.warnings` carries the early-season notice at `--horizon >= 2` (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded), plus `understat_team_unmatched` for any club Understat carried no players for, whose squad therefore scored without xG | Yes | Classic | Yes | direct-api |
-| `waivers` | Show waiver recommendations for your draft league. JSON `data` carries `top_targets` and `targets_by_position` (ranked claims) plus `pool` — the full unowned roster, one `{id, player_name, position, team_short}` row each, unranked and untruncated, so a consumer can answer "is this player claimable at all" without inferring it from the ranked lists. Keeper scores carry the GK signal block (saves/90, defensive quality, clean-sheet rate), read from the main-game player each draft element is joined to on `code` because the draft bootstrap publishes none of it, so draft keepers rank on what separates them rather than on form and ppg alone. Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage; the matchup, position-need, team-stacking and consistency terms stay pure observation; JSON `metadata.warnings` carries the early-season notice while the blend is live, and reports `early_season_small_sample` both when history could not be loaded and when no draft element found a main-game counterpart to take a prior from. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing. No `draft_league_id` configured exits 1 in both output formats — table mode used to warn and exit 0 | Yes | Draft | Yes | via-agent |
+| `waivers` | Show waiver recommendations for your draft league. JSON `data` carries `top_targets` and `targets_by_position` (ranked claims) plus `pool` — the full unowned roster, one `{id, code, player_name, position, team_short}` row each, unranked and untruncated, so a consumer can answer "is this player claimable at all" without inferring it from the ranked lists. On every player row the command emits `id` is the draft game's element id and `code` the cross-game key: the gw-prep skill joins the returnee radar's main-game rows to the pool on `code`, since a mid-season addition holds a different id in each game (#418). Keeper scores carry the GK signal block (saves/90, defensive quality, clean-sheet rate), read from the main-game player each draft element is joined to on `code` because the draft bootstrap publishes none of it, so draft keepers rank on what separates them rather than on form and ppg alone. Defender scores carry DC/90 through the same join, since the draft bootstrap has defensive contribution only as a season total; every row's `dc_per_90` (pool, `current_squad`, `recent_releases`) is the main-game rate, weighted only in the defender score and display-only for other positions, and a defender the join misses stays at 0. A keeper or defender in the unowned pool that the join misses is reported as one `draft_player_unjoined` entry in `metadata.warnings` (stderr in table mode) with the count of each and the first three names, since the player ranks against an anchor calibrated with the term it lacks. Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage; the matchup, position-need, team-stacking and consistency terms stay pure observation; JSON `metadata.warnings` carries the early-season notice while the blend is live, and reports `early_season_small_sample` both when history could not be loaded and when no draft element found a main-game counterpart to take a prior from. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing. Each row's `team_id` is the main game's team id, translated from the draft game's own club numbering by club code (null for a club the main game does not list, which `metadata.warnings` reports as `draft_club_untranslated`; the row keeps the club's draft name), since fixtures, form and FDR are all keyed by it. No `draft_league_id` configured exits 1 in both output formats — table mode used to warn and exit 0 | Yes | Draft | Yes | via-agent |
 | `squad` | Analyse your FPL squad health and fixtures. Exits 1 with an `error` envelope when no entry ID is configured for the active format. `--classic` / `--draft` (mutually exclusive) pin the format instead of inferring it from the configured IDs, so a caller that means classic gets the missing-ID error rather than the draft roster; with neither, single-format configs still auto-select. A picks 404 is checked against `entry/<id>/` before it is reported as "no squad submitted yet", so a reissued or wrong entry ID says so; `squad grid` and `captain` share that diagnosis through `agents/common.py` | Yes | General | No | via-agent |
 | `squad grid` | Show squad fixture difficulty grid. Exits 1 with an `error` envelope when no entry ID is configured for the active format, or when the squad fetch fails. Takes the same `--classic` / `--draft` pinning as `squad`, before or after the subcommand, and the same stale-entry diagnosis. A `--watch` name that does not resolve is non-fatal either way: unmatched, or matching two players exactly, it warns on stderr and is skipped, and the grid still renders | Yes | General | No | via-agent |
-| `squad sell-prices` | Show squad sell prices and financial breakdown. Nothing cached and no `--refresh`, a failed scrape, draft format, or a scrape the extraction heuristics distrust each exit 1 with an `error` envelope under `--format json`; table mode still renders a suspect scrape under a `Squad Budget (Suspect)` panel, since a reader can judge it and `fpl allocate --sell-prices` cannot | Yes | Classic | No | direct-api |
+| `squad sell-prices` | Show squad sell prices and financial breakdown. A cached run recomputes each sell price at today's price, applying FPL's rule only to a player whose cached sell price it reproduces at the price stored with the scrape; JSON rows carry `scraped_sell_price` beside `sell_price`, and a player it cannot check keeps the scraped price under a `sell_prices_as_scraped` warning, on stderr in both modes (also given, with exit 0, when today's prices cannot be fetched). `transfer-eval` budgets on the same recomputed price and warns when the OUT player's is unchecked or not cached; `allocate --sell-prices` repeats the file's warning. Nothing cached and no `--refresh`, a failed scrape, draft format, or a scrape the extraction heuristics distrust each exit 1 with an `error` envelope under `--format json`; table mode still renders a suspect scrape under a `Squad Budget (Suspect)` panel, since a reader can judge it and `fpl allocate --sell-prices` cannot | Yes | Classic | No | direct-api |
 | `chips` | View and plan FPL chip usage | Yes | Classic | No | direct-api |
 | `chips timing` | Recommend chip timing based on blank/double GW exposure. No `classic_entry_id` configured, and no completed gameweek to measure exposure against, each exit 1 in both output formats — table mode used to print the reason and exit 0. The missing-ID message is the shared one `fpl squad` and `fpl squad grid` give, and a failed fixture agent reports the agent's own reason in the same words either way (`Fixture agent failed: <reason>`), where the envelope and the terminal used to word it differently and neither passed the reason on | Yes | Classic | No | via-agent |
 | `chips add` | Plan a chip for a gameweek | No | Classic | No | direct-api |
@@ -117,17 +125,18 @@ Python classes in `fpl_cli/agents/` that implement `async run(context) -> AgentR
 | ReportAgent | `agents/orchestration/report.py` | Orchestration | `preview`, `review`, `league-recap` | - |
 
 **Notes:**
-- BenchOrderAgent and StartingXIAgent have no CLI command - they are invoked by gw-prep skill wrapper scripts in `.agents/skills/gw-prep/scripts/`
+- BenchOrderAgent and StartingXIAgent have no CLI command - they are invoked by gw-prep skill wrapper scripts in `.agents/skills/gw-prep/scripts/`. Both payloads carry `warnings` as `{code, message}` entries: the feed coverage codes above, and for bench order `bench_cover_missing` per position the bench cannot cover
 - Every scoring family holds players known not to be playing out of its GW1-9 early-season device — the prior blend for the value family (`quality_score`, `fpl allocate`) and the ownership family (`targets`, `differentials`, `waivers`, transfer-eval's Outlook), position-mean shrinkage for the single-GW family (`captain`, `bench-order`, `starting-xi`, transfer-eval's This GW); bench and lineup order on raw scores, so for those two it changes the displayed score only
 - TransferEvalAgent is used by both `transfer-eval` CLI command and gw-prep skill
-- `bench_order.py`, `starting_xi.py` and `transfer_eval.py` (`.agents/skills/gw-prep/scripts/`) take player names, accept the `Name (TEAM)` disambiguator, and exit 1 naming both candidates when a name matches two players exactly (Dean and Jordan Henderson are both `Henderson`) rather than resolving to whichever the API lists first. Pass `Name (CLUB)` from the squad grid's `player`/`team` pair (issue #180). All three share that resolution with the `transfer-eval` CLI command through `resolve_player_or_report` / `resolve_players_or_report` (`fpl_cli/models/player.py`)
+- `bench_order.py`, `starting_xi.py` and `transfer_eval.py` (`.agents/skills/gw-prep/scripts/`) take player names, accept the `Name (TEAM)` disambiguator, and exit 1 naming both candidates when a name matches two players exactly (Dean and Jordan Henderson are both `Henderson`) rather than resolving to whichever the API lists first. Pass `Name (CLUB)` from the squad grid's `player`/`team` pair (issue #180). All three share that resolution with the `transfer-eval` CLI command through `resolve_player_or_report` / `resolve_players_or_report` (`fpl_cli/models/player.py`). Every player row they emit carries the main-game `id` and `code`, the cross-game key, beside it (#419), so a phase that combines one with a draft payload joins on `code`
 - Every gw-prep script that runs an agent (`bench_order.py`, `starting_xi.py`, `transfer_eval.py`) runs it inside `json_output_mode()`, so a phase can parse stdout from byte 0 on the success path as well as the failure one. Until #226 the agent's two progress lines landed ahead of the payload and only the error envelopes were clean — the reverse of what a lenient reader would guess. `Agent.log` now writes to stderr for every agent, so the same holds for `fpl transfer-eval --format json`; `tests/test_cli_json_contract.py` guards all four
 - `extract_classic_squad.py` (`.agents/skills/gw-prep/scripts/`) — deterministic Classic Squad block extractor used by gw-prep Phase A3 + Phase E. JSON stdout; read-only; emits TypedDict-annotated payloads.
-- gw-prep Phase B10 runs `fpl returnees --enrich --format json` and inlines the payload into both Phase C prompts, rendering a Returning Soon section in the classic and draft output templates. In draft a row can escalate into a stash claim; in classic the watchlist is informational and transfer recommendations may not name a tracked returnee (`references/rules.md`)
+- gw-prep Phase B10 runs `fpl returnees --enrich --format json` and inlines the payload into both Phase C prompts, rendering a Returning Soon section in the classic and draft output templates. In draft, `claimable_returnees.py` first narrows the payload to the entries still in the waiver pool, joined on `code` (#418), and a row of that list can escalate into a stash claim; in classic the watchlist is informational and transfer recommendations may not name a tracked returnee (`references/rules.md`)
 - gw-prep Phase B1 and squad-builder Phase B each run the `fpl fdr` analysis call alongside `fpl fdr --blanks --format json`, and read the quality signals both return -- `data.ratings_warning`, `metadata.custom_analysis`, the blanks payload's `metadata.warnings`, plus `data.predictions_stale` / `data.prediction_warnings` where `--my-squad` resolved a squad. `--blanks` bypasses the fixture agent for a schedule-only payload carrying none of the analysis and none of those fields, so the skills that issued only it were promising pFDR they never received (gw-prep's pFDR Overview, squad-builder's per-position `{ATK|DEF} column` blocks) and silently accepting whatever rating quality they got (issue #135). Whatever fires becomes `data_caveat`, inlined into every sub-agent prompt and written to the output's Data Quality section, messages quoted verbatim so the remedy they name (`fpl ratings update`, `fpl init`) survives. gw-prep passes `--my-squad` (it also wants squad blank/double exposure); squad-builder deliberately does not, since it is replacing the 15 and its season-start modes have no squad to resolve. Enforced by `tests/test_skill_fdr_quality_signals.py`
 - StatsAgent (`fpl xg`, `fpl preview`) clamps its own window and minutes floor to the gameweeks played, scaling the floor by the same 45 minutes per gameweek the skills apply to `fpl stats --min-minutes` below -- off a different anchor, though: the skills scale off `(N - 1)` for the upcoming gameweek, this off the gameweeks the API reports finished, which diverges under a postponement and only downwards. The default 360-minute floor is arithmetically impossible until four gameweeks have finished and out of reach for all but ever-presents for several more, so it emptied every table through the opening weeks (issue #227); the configured bar binds again from 8 finished gameweeks, 10 for `--all`. `data.min_minutes` / `data.gameweeks_played` / `data.window_label` report what was applied, `data.empty_reason` says whether the floor or the data emptied the result, and `warnings` carries `early_season_minutes_floor` while the bar is scaled. A floor a caller passes explicitly (`fpl targets --min-minutes`, `fpl differentials --min-minutes`) is applied verbatim. Every surface renders the reason where its reader is: `fpl xg`, `fpl targets` and `fpl differentials` in place of their tables, `fpl preview` under a Performance Stats heading that now carries the analysed window rather than a hardcoded six gameweeks (console, `templates/gw_preview.md.j2`, and ReportAgent's inline fallback alike). Enforced by `tests/test_stats.py::TestStatsAgentMinutesFloor` and `::TestStatsAgentWindowPrefilter`
 - gw-prep Phase B8 and squad-builder Phase B derive the `fpl stats --min-minutes` floor from the current gameweek (`min(cap, (N - 1) * 45)`, caps 315/450) rather than hardcoding it. A fixed floor is unreachable until GW8/GW11 and empties the result silently -- `fpl stats` returns a well-formed envelope with `"data": []`. Both also rank on `ep_next` before GW6 -- the positional sorts (xGI, form, total_points, ppg) order mostly on sample that early -- and label each block with the sort and floor it used, so a downstream agent knows what ordered it; an empty block is annotated rather than left bare. Both also say what that sort is *not*: before FPL's fixture factor moves off 1.0, `ep_next` tracks `form` almost exactly (at GW4, every row of all four positional shortlists), so the ordering is a form ordering with doubtful players scaled down by chance of playing, and a sub-agent must not be told it is a projection rather than observed output (issue #236). Enforced by `tests/test_skill_stats_thresholds.py`
+- `claimable_returnees.py` (`.agents/skills/gw-prep/scripts/`) — joins the `fpl returnees` payload to the `fpl waivers` pool on `code` (gw-prep Phase B10, draft runs) and emits the radar narrowed to the entries still unowned, with the rest under `excluded` as `owned` or `no-code`. The radar's `id` is the main game's element id and the pool's the draft's, and the two differ for mid-season additions, so the C2 sub-agent is handed a claimable list rather than left to match two payloads itself (#418). JSON stdout; read-only; `ok: false` with no entries when the pool has no usable `code` (an older fpl-cli) or the radar has no `data.entries` (a failed `fpl returnees` run), with a warning naming which side failed, so the stash path fails closed and an unreadable radar never reads as nobody returning (#432); exits 0 whatever it finds — the one non-zero exit is the startup guard below.
 - `validate_draft_waivers.py` (`.agents/skills/gw-prep/scripts/`) — cross-checks the Draft waiver table against the live waiver pool and squad grid (gw-prep Phase D1). JSON stdout; read-only; exits 0 whatever the validation finds — the one non-zero exit is the startup guard below.
 - `normalise_entities.py` (`.agents/skills/gw-prep/scripts/`) — decodes HTML-escaped text in a report assembled from sub-agent output and reports the entity references it deliberately leaves alone. JSON stdout; rewrites its `--file` in place; shared by gw-prep Phase D, squad-builder Phase E and update-gw-prep Phase D, all of which warn rather than block on its findings. Contract and warn posture live once, in `.agents/skills/gw-prep/references/entity-normalisation.md`.
 - Every script under `.agents/skills/gw-prep/scripts/` imports the `fpl_cli` package, so it runs on the interpreter fpl-cli is installed on — every SKILL.md that calls one (gw-prep, squad-builder, update-gw-prep) writes that interpreter as `[YOUR_PYTHON]`, and squad-builder/update-gw-prep reach gw-prep's `scripts/` cross-skill via `[YOUR_SKILLS_DIR]` since `${CLAUDE_SKILL_DIR}` resolves to the *calling* skill's own directory (issue #221). A standalone `fpl` on `PATH` (uv tool, pipx) provides the command but not the package; `_bootstrap.py` catches that case ahead of the fpl_cli imports and exits 1 with `{"error": true, "messages": [...]}` on stdout, which the phases parsing that stdout surface as a warning instead of a traceback
-- The extractor and the waiver validator locate markdown sections via `fpl_cli.utils.markdown` (`HeadingMatcher`, `find_section`, `section_body`, `leaf_body`, `fence_flags`), tolerating LLM heading drift (qualifiers, case, leading annotations, opt-in aliases) without matching a different heading that shares a prefix. Also used by `fpl_cli/prompts/review.py` for the GW Narrative section boundary. Both scripts read the tables inside those sections with `iter_tables`, the reader `fpl review --compare-recs` uses, so a `| - | - |` placeholder row never ends a table early. The waiver validator also cleans its cells with `split_name_team`, so a `(LIV, MID)` suffix comes off a name as `(LIV)` does, skips the same placeholder cells as the review (`No claim`, `-`), and reports rows under Waiver Recommendations that no table took in (`waiver-rows-unread`, via `pipe_rows`) rather than passing them unchecked. It still matches the template's column names exactly, where the review takes aliases: it checks gw-prep's fresh output, not older files.
+- The extractor and the waiver validator locate markdown sections via `fpl_cli.utils.markdown` (`HeadingMatcher`, `find_section`, `section_body`, `leaf_body`, `fence_flags`), tolerating LLM heading drift (qualifiers, case, leading annotations, opt-in aliases) without matching a different heading that shares a prefix. Also used by `fpl_cli/prompts/review.py` for the GW Narrative section boundary. Both scripts read the tables inside those sections with `iter_tables`, the reader `fpl review --compare-recs` uses, so a `| - | - |` placeholder row never ends a table early. The waiver validator also cleans its cells with `split_name_team`, so a `(LIV, MID)` suffix comes off a name as `(LIV)` does, skips the same placeholder cells as the review (`No claim`, `-`), picks the waiver table by its `Drop`/`Claim` headers rather than its place, and reports rows under Waiver Recommendations that it did not take in (via `pipe_rows` and the table's `span`, counting fenced and blockquoted rows too) rather than passing them unchecked, naming the first few: when no waiver row was read at all it fails closed with a `waiver-table-unreadable` flag that blocks Phase D1, and when some were it warns with `waiver-rows-unread`. An empty waiver table is a week with no claims, so beside it only rows no table took in block. `tests/test_validate_draft_waivers.py` holds Phase D1's stop-or-proceed prose in SKILL.md to the flag types the validator emits. It still matches the template's column names exactly, where the review takes aliases: it checks gw-prep's fresh output, not older files.

{fplkit-2.8.0 → fplkit-2.9.0}/.agents/skills/gw-prep/SKILL.md

@@ -174,6 +174,8 @@ Store the analysis as `pfdr`, the schedule as `blanks_schedule` and the draft va
 
 `data_caveat` goes into every Phase C prompt and into the report's `## Notes` section in Phase D, so a reader can see why the recommendations leaned away from fixtures.
 
+**Feed coverage entries from the scoring payloads join `data_caveat` too.** Every scoring command gathered below (`fpl captain`, `fpl waivers`, `fpl targets`, `fpl differentials`, `fpl transfer-eval`, `fpl stats --value`) and the `bench_order.py` / `starting_xi.py` / `transfer_eval.py` scripts carry `warnings` entries whose `code` ends in `_coverage_low` when a data feed reached too little of the player pool -- Understat down, Core-Insights match files missing, per-gameweek history throttled, last season's history gone, clubs unrated -- and `fpl waivers` (with the draft columns of `fpl stats`) carries `draft_squads_unread` when a rival squad could not be read. Each message says what the scores fell back to. Add every such entry to `data_caveat` verbatim, once per distinct `code` across all payloads, and treat the affected scores the way the Data quality rule treats pFDR: still shown, not decisive on their own.
+
 ### B2 -- Captain Candidates (classic only - skip if format is "draft")
 
 ```bash
@@ -335,13 +337,37 @@ returns the FPL-sourced watchlist -- so this step is never a reason to abort the
 own retries; the answers it did get are cached, so re-run the command once before settling for the
 partial payload.
 
-Store the payload as `returnee_radar` and inline it into both Phase C prompts as a labelled
-section. C1 renders it as an informational watchlist and is barred from naming its players in
-transfer recommendations; C2 renders the subset still in the waiver pool and may escalate an entry
-to a stash claim. The Returning Soon section quotes this payload, which is inlined into the prompt
+Store the payload as `returnee_radar` and inline it into the C1 prompt as a labelled section. C1
+renders it as an informational watchlist and is barred from naming its players in transfer
+recommendations. The Returning Soon section quotes this payload, which is inlined into the prompt
 like every other cited source -- so its numbers are grounded the same way every other cited number
 is.
 
+On a draft run (format `draft` or `both`), join the radar to the waiver pool here rather than
+leaving the match to the C2 sub-agent: the radar's `id` is the main game's element id and the
+pool's is the draft's, and the two differ for players added mid-season, so a model matching the two
+payloads by eye is the step that failed in #418. Write B10's payload to
+`/tmp/gw-prep-returnees-{N}.json` and B3's to `/tmp/gw-prep-waivers-{N}.json` (the file Phase D1
+reads), then:
+
+```bash
+[YOUR_PYTHON] "${CLAUDE_SKILL_DIR}/scripts/claimable_returnees.py" \
+  --returnees-json /tmp/gw-prep-returnees-{N}.json \
+  --waivers-json /tmp/gw-prep-waivers-{N}.json
+```
+
+Store its output as `returnee_radar_draft`. It carries the radar's `metadata` and the subset of its
+`entries` whose `code` matches a pool row -- joined on `code`, never on `id` -- with everyone else
+under `excluded` and why (`owned`, or `no-code`). `ok: false` means the join could not run and
+`entries` is then empty, so no stash claim can be made from it; `warnings` says which side failed:
+`radar-unreadable` when the radar has no `data.entries` (for example the `{command, error}` envelope
+of a failed `fpl returnees` run), `pool-unreadable` or `pool-without-code` when the pool could not be
+read (no `data.pool`, or rows without `code` from an older fpl-cli), `envelope-unreadable` when
+either file is not a JSON object at all. An empty list with `ok: false`
+is never "nobody is returning". If the script fails (exit 1) treat it the same way: Returning Soon
+says the radar and pool could not be joined, lists nobody, and C2 makes no stash claim. Never fall
+back to matching the raw payloads yourself.
+
 <!-- ADAPT: Add your own further supplementary data sources here. Examples:
   - `fpl preview --save --scout` generates a GW preview with fixture analysis and scout insights.
     Read the saved file and inject its content into Phase C sub-agents as additional context.
@@ -625,7 +651,7 @@ Agent tool parameters:
 >
 > **WAIVER POOL IS AUTHORITATIVE:** `fpl waivers` output is the only source for available players. All other data (stats, form tables, squad context) is for analysis only. Never recommend a claim not present in the waivers output — Phase D1 will flag pool misses as a warning. Cross-position recommendations (e.g. dropping a MID to claim a DEF) are structurally illegal and will be blocked by Phase D1.
 >
-> **`data.pool` is an availability roster, not a shortlist.** It lists every unowned player in the league — one `{id, player_name, position, team_short}` row each, unranked and untruncated — so membership answers only "may this player be claimed at all". Ranked claims come from `data.top_targets` and `data.targets_by_position`; presence in `data.pool` is never on its own a reason to recommend someone. The single claim allowed to rest on pool membership alone is a stash claim for a tracked returnee, which the waiver scoring suppresses by design and which therefore cannot reach the ranked targets.
+> **`data.pool` is an availability roster, not a shortlist.** It lists every unowned player in the league — one `{id, code, player_name, position, team_short}` row each, unranked and untruncated — so membership answers only "may this player be claimed at all". Its `id` is the draft game's element id; `code` is the key every other command's player rows share, and the only field to match another payload on. Ranked claims come from `data.top_targets` and `data.targets_by_position`; presence in `data.pool` is never on its own a reason to recommend someone. The single claim allowed to rest on pool membership alone is a stash claim for a tracked returnee, which the waiver scoring suppresses by design and which therefore cannot reach the ranked targets.
 >
 > - Waivers: {B3 output}
 > - Squad: {B4 output}
@@ -637,11 +663,20 @@ Agent tool parameters:
 >   ("Transfer Flow projects him starting"), never assert it. Under `negative_filter_only` use it
 >   only to downgrade. A player with no intel is not a worse player.
 >
-> - Returning soon: {returnee_radar} (from B10)
->   Render the Returning Soon section of the Draft output template from this payload, restricted to
->   tracked returnees whose `id` appears in the waivers `data.pool` list. A returnee missing from
->   the pool is already owned by a rival and is not actionable — leave it out rather than listing it
->   as unavailable. Quote only fields present in this payload.
+> - Returning soon: {returnee_radar_draft} (from B10, the radar joined to the waiver pool by
+>   `claimable_returnees.py`)
+>   Render the Returning Soon section of the Draft output template from its `entries`. Every entry
+>   there is a tracked returnee whose `code` matches a row in the waivers `data.pool`, so each one
+>   is claimable and no returnee outside the list is. Do not re-derive membership from the waivers
+>   payload, and never match on `id`: the radar's `id` is the main game's element id and the pool's
+>   is the draft's, and the two differ for players added mid-season. The `excluded` list names the
+>   returnees a rival already owns — leave them out rather than listing them as unavailable. If `ok`
+>   is false the join could not run: name what failed from `warnings` in the section ("the
+>   returnee radar could not be read" for `radar-unreadable`, "the waiver pool could not be read"
+>   for `pool-unreadable` or `pool-without-code`; both when both appear; "the returnee data could
+>   not be read" for any other warning type, or none), list nobody, and make no stash claim.
+>   Never render an empty section as nobody returning when `ok` is false. Quote only fields
+>   present in this payload.
 >
 > **STASH CLAIMS:** a Returning Soon row escalates into the Waiver Recommendations table only when
 > **all four** gates below hold. Any one failing means watchlist only — no claim.
@@ -651,8 +686,9 @@ Agent tool parameters:
 >    `metadata.escalation_window` and the citation gate, so do not re-derive the timing yourself:
 >    an enrichment date counts here only when it arrived cited, and `escalation_basis` names which
 >    source the verdict rests on (`fpl-news` or `ai-search`).
-> 3. **Claimable and position-for-position:** the returnee's `id` is in the waivers `data.pool`, and
->    the player dropped for them plays the returnee's own position.
+> 3. **Claimable and position-for-position:** the returnee is one of `returnee_radar_draft`'s
+>    `entries` (the script has already joined on `code`; never re-match on `id`), and the player
+>    dropped for them plays the returnee's own position.
 > 4. **Beats the incumbent by the configured margin:** take the drop candidate your squad analysis
 >    already ranks lowest at that position, run C2.5's `transfer_eval.py --out "{that player}"
 >    --in "{returnee}"`, and require `outlook_delta` to exceed the radar's
@@ -745,7 +781,7 @@ Present a brief summary to the user:
 
 _Runs after Phase D file write, before Phase E. Not embed-gated._
 
-1. Write Phase B's waivers JSON (from orchestrator context, B3 output) to `/tmp/gw-prep-waivers-{N}.json`.
+1. Write Phase B's waivers JSON (from orchestrator context, B3 output) to `/tmp/gw-prep-waivers-{N}.json` (B10 already wrote it on a draft run; writing it again is harmless).
 2. Write Phase B's draft squad-grid JSON (from orchestrator context, B4 draft output) to `/tmp/gw-prep-squad-grid-{N}.json`.
    - For draft-only runs, this is the `fpl squad grid --format json` output from B4.
    - For `both` format runs, this is the `fpl squad grid --draft --format json` output from B4.
@@ -759,7 +795,7 @@ _Runs after Phase D file write, before Phase E. Not embed-gated._
    ```
 
    Parse stdout as JSON: `{"ok": bool, "flags": [...], "warnings": [...]}`.
-   If the script cannot be found or exits non-zero unexpectedly, emit a warning and proceed to Phase E (fail-open for infrastructure errors, fail-closed only for confirmed rule violations). A non-zero exit whose stdout parses as `{"error": true, ...}` is the script reporting its own startup failure — quote `messages[0]` verbatim in that warning; it names the cause (a wrong interpreter is the common one).
+   If the script cannot be found or exits non-zero unexpectedly, emit a warning and proceed to Phase E (fail-open for infrastructure errors, fail-closed only for confirmed rule violations and for a waiver table the validator could not read at all). A non-zero exit whose stdout parses as `{"error": true, ...}` is the script reporting its own startup failure — quote `messages[0]` verbatim in that warning; it names the cause (a wrong interpreter is the common one).
 
 4. **Managed block update:** locate the sentinel block in the recommendations file:
    ```
@@ -774,6 +810,7 @@ _Runs after Phase D file write, before Phase E. Not embed-gated._
      > - {one line per flag/warning, e.g. "Row 1: cross-position-claim (Drop: João Pedro FWD → Claim: Pedro Porro DEF)"}
      <!-- phase-d1:end -->
      ```
+     For `waiver-table-unreadable` and `waiver-rows-unread`, the line names the unchecked rows rather than giving a count: `{type} ({rows} line(s) unchecked): {lines joined with "; "}`, then ` and {rows - len(lines)} more` when `rows` exceeds the lines quoted. Quote each line as it comes, without adding code spans: the lines are LLM-written rows that can carry backticks of their own.
    - If both are empty: remove the block entirely (including sentinels) if present.
 
 5. **Split posture:**
@@ -783,8 +820,16 @@ _Runs after Phase D file write, before Phase E. Not embed-gated._
      > Edit the file to fix the flagged row(s), then re-run `/gw-prep` to continue.
      
      **Stop the pipeline.** Do not proceed to Phase E. Do not mark the run as complete.
-   - Else, if a warning has `type == "waiver-rows-unread"` → emit this in-chat warning, followed by the pool-miss one below if any `waiver-not-in-pool` flags are present too:
-     > ⚠️ Phase D1: {rows} row(s) under Waiver Recommendations in `gw{N}-recommendations.md` were not read as waiver rows, so they were not checked for cross-position swaps. A table needs a `|---|` row straight under its header, no blank line inside it, and nothing stacked beneath it. Fix the table and re-run `/gw-prep` before submitting waivers.
+   - Any flag with `type == "waiver-table-unreadable"` present → emit a **red error** in chat. The validator read no waiver row at all -- rows with no `Drop`/`Claim` table to hold them, or an empty one beside rows no table took in -- so no claim was checked for a cross-position swap; this fails closed like the swap itself:
+     > ❌ Phase D1 blocked: the Waiver Recommendations table in `gw{N}-recommendations.md` could not be read, so no claim in it was checked for a cross-position swap. Unread line(s):
+     > - {line} (one per entry in `lines`, as it comes; then "and {rows - len(lines)} more" if `rows` is larger)
+     > A waiver table needs `Drop` and `Claim` columns, a `|---|` row straight under its header, no blank line inside it, nothing stacked beneath it, and no code fence or blockquote around it. Fix the table, then re-run `/gw-prep` to continue.
+
+     **Stop the pipeline.** Do not proceed to Phase E. Do not mark the run as complete.
+   - Else, if a warning has `type == "waiver-rows-unread"` → the table was read and its rows checked, but other rows beside it were not. Emit this in-chat warning, followed by the pool-miss one below if any `waiver-not-in-pool` flags are present too:
+     > ⚠️ Phase D1: {rows} row(s) under Waiver Recommendations in `gw{N}-recommendations.md` were not read as waiver rows, so they were not checked for cross-position swaps:
+     > - {line} (one per entry in `lines`, as it comes; then "and {rows - len(lines)} more" if `rows` is larger)
+     > A table needs a `|---|` row straight under its header, no blank line inside it, and nothing stacked beneath it. Fix the table and re-run `/gw-prep` before submitting waivers.
 
      Proceed to Phase E.
    - Else (only warnings and/or `waiver-not-in-pool` flags) → emit an in-chat warning:

{fplkit-2.8.0 → fplkit-2.9.0}/.agents/skills/gw-prep/references/output-template.md

@@ -144,7 +144,7 @@ _Tracked returnees still unowned in the league. Omit the section when nothing qu
 |--------|------|-----|---------|-----------------|--------|--------|---------|
 | | | | | | | | |
 
-Rows are the `fpl returnees` payload (`data.entries`) intersected with the waivers `data.pool` by `id` — a returnee already owned by a rival is not listed at all. Columns as Classic. Verdict = `Stash` when every escalation gate in SKILL.md Phase C2 is met, in which case the player also appears in Waiver Recommendations above with their expected return and its `escalation_basis` in the Rationale; otherwise `Watch`.
+Rows are the `entries` of `returnee_radar_draft`: the `fpl returnees` payload joined to the waivers `data.pool` on `code` by `claimable_returnees.py`, never by `id` (the radar's `id` is a main-game element id, the pool's a draft one, and they differ for mid-season additions) — a returnee already owned by a rival is not listed at all. Columns as Classic. Verdict = `Stash` when every escalation gate in SKILL.md Phase C2 is met, in which case the player also appears in Waiver Recommendations above with their expected return and its `escalation_basis` in the Rationale; otherwise `Watch`.
 
 Every number here comes from the radar payload inlined into the sub-agent prompt, so the Momentum Alerts grounding rule is satisfied by citing it — but nothing beyond those fields may be asserted.
 
@@ -195,7 +195,7 @@ The **Data quality** sub-section carries `data_caveat` from gw-prep Phase B1 --
 
 Every recommendation in this file that leans on fixture difficulty rests on those ratings, so this belongs with the recommendations rather than only in the terminal scrollback the run scrolled past.
 
-**Read back by `fpl review --compare-recs`.** The review grades what was done against this file, through the column headers of Transfer Recommendations (`Out`, `In`) and Waiver Recommendations (`Drop`, `Claim`), the `**Recommended captain:**` line, and on embed-mode runs the Classic Squad's `#### Starting XI` and `#### Bench` tables. Write them exactly as above, with the club code in brackets after each player (`Tzolis (ARS)`) and the initial left on (`B.Fernandes`, not `Fernandes`): a renamed column leaves every move in that table ungraded, and a bare surname cannot be told apart from a same-club namesake. When there is nothing to recommend, say so in words ("Roll the free transfer", "No waiver claims this week") rather than leaving the table's rows blank: a blank table reads the same as one the review could not parse. `tests/test_recommendations_parser.py` parses this template, so change it and `fpl_cli/parsers/recommendations.py` together.
+**Read back by `fpl review --compare-recs`.** The review grades what was done against this file, through the column headers of Transfer Recommendations (`Out`, `In`) and Waiver Recommendations (`Drop`, `Claim`), the `**Recommended captain:**` line, and on embed-mode runs the Classic Squad's `#### Starting XI` and `#### Bench` tables. Write them exactly as above, with the club code in brackets after each player (`Tzolis (ARS)`) and the initial left on (`B.Fernandes`, not `Fernandes`): a renamed column leaves every move in that table ungraded, and a bare surname cannot be told apart from a same-club namesake. Rows that share an Out player are read as ranked alternatives for one sale, so list each candidate on its own row with the same Out cell; an alternative between two different sales ("sell Tzolis, or else Ballard") reads as two separate moves and is graded as both. Waiver rows that share a Drop are read as one conditional chain, in the order listed, so write each fallback claim as its own row with the same Drop cell, below the claim it backs up: the claim that landed is graded as followed, and the claims below it are not counted as misses. When there is nothing to recommend, say so in words ("Roll the free transfer", "No waiver claims this week") rather than leaving the table's rows blank: a blank table reads the same as one the review could not parse. `tests/test_recommendations_parser.py` parses this template, so change it and `fpl_cli/parsers/recommendations.py` together.
 
 ---
 

fplkit-2.9.0/.agents/skills/gw-prep/scripts/claimable_returnees.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Join the returnee radar to the draft waiver pool on `code`.
+
+Reads `fpl returnees --format json` and `fpl waivers --format json` and emits
+the radar narrowed to the tracked returnees a draft manager can actually
+claim: those whose `code` matches a row in the waivers `data.pool`.
+
+This is the one step of the Draft stash path that used to be left to the
+sub-agent reading two payloads, and when it did the two had no key in common
+(#418): the radar's `id` is the main game's element id, the pool's is the
+draft's, and a player added mid-season holds a different one in each. Done
+here the join is deterministic and testable, and the sub-agent receives a
+list it cannot mis-read.
+
+Emits JSON to stdout:
+  {"ok": bool,
+   "metadata": {...the radar's, plus "pool_size"...},
+   "entries": [...the claimable radar entries, unchanged...],
+   "excluded": [{"web_name": ..., "code": ..., "reason": "owned" | "no-code"}],
+   "warnings": [{"type": ...}]}
+
+`ok` is false only when the join could not run -- no usable `data.pool`, a
+pool whose rows carry no `code` (an older fpl-cli), or a radar with no
+`data.entries` (such as the `{command, error}` envelope a failed `fpl
+returnees` run saves) -- and `entries` is then empty: a join that cannot run
+offers nothing to claim rather than everything, so the stash path fails
+closed. `warnings` says which side failed (`radar-unreadable`, or
+`pool-unreadable` / `pool-without-code`), so an unreadable radar is never
+reported as nobody returning (#432). Exit code is 0 whatever the join finds; the
+startup guard in `_bootstrap` is the one non-zero exit, and reports itself as
+{"error": true, "messages": [...]}.
+
+Runs on the interpreter fpl-cli is installed on (activate its venv first,
+or invoke that venv's Python directly).
+
+Usage:
+    python3 claimable_returnees.py \\
+        --returnees-json /tmp/returnees.json \\
+        --waivers-json /tmp/waivers.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, TypedDict
+
+# Imported first and for its side effect: _bootstrap reaches for the fpl_cli
+# package on its own, turning a wrong interpreter into this script's JSON error
+# envelope instead of a ModuleNotFoundError traceback.
+import _bootstrap  # noqa: F401 — import guard, see module docstring
+
+from fpl_cli.models.player import usable_code
+
+
+class Excluded(TypedDict):
+    web_name: str
+    code: int | None
+    reason: str
+
+
+class JoinWarning(TypedDict):
+    type: str
+
+
+class JoinResult(TypedDict):
+    ok: bool
+    metadata: dict[str, Any]
+    entries: list[dict[str, Any]]
+    excluded: list[Excluded]
+    warnings: list[JoinWarning]
+
+
+def pool_codes(waivers: dict[str, Any]) -> tuple[set[int] | None, JoinWarning | None]:
+    """The `code` of every row in the waivers `data.pool`, or None with the reason.
+
+    None means the join cannot run: there is no pool list to read, or there
+    is one and not a row of it carries `code`, which is what `fpl waivers`
+    emitted before #418. An empty pool is readable and matches nobody.
+    """
+    data = waivers.get("data")
+    pool = data.get("pool") if isinstance(data, dict) else None
+    if not isinstance(pool, list):
+        return None, JoinWarning(type="pool-unreadable")
+    rows = [row for row in pool if isinstance(row, dict)]
+    codes = {code for row in rows if (code := usable_code(row.get("code"))) is not None}
+    if rows and not codes:
+        return None, JoinWarning(type="pool-without-code")
+    return codes, None
+
+
+def radar_entries(radar: dict[str, Any]) -> tuple[list[dict[str, Any]], JoinWarning | None]:
+    """The radar's `data.entries`, or an empty list with the reason."""
+    data = radar.get("data")
+    entries = data.get("entries") if isinstance(data, dict) else None
+    if not isinstance(entries, list):
+        return [], JoinWarning(type="radar-unreadable")
+    return [entry for entry in entries if isinstance(entry, dict)], None
+
+
+def join(radar: dict[str, Any], waivers: dict[str, Any]) -> JoinResult:
+    """Narrow the radar to the entries whose `code` is in the waiver pool."""
+    metadata = radar.get("metadata")
+    result: JoinResult = {
+        "ok": True,
+        "metadata": dict(metadata) if isinstance(metadata, dict) else {},
+        "entries": [],
+        "excluded": [],
+        "warnings": [],
+    }
+
+    entries, radar_warning = radar_entries(radar)
+    codes, pool_warning = pool_codes(waivers)
+    result["warnings"].extend(w for w in (radar_warning, pool_warning) if w is not None)
+    if codes is not None:
+        result["metadata"]["pool_size"] = len(codes)
+    if radar_warning is not None or codes is None:
+        # Nothing to claim rather than everything: the stash path fails closed,
+        # and an unreadable radar is a failure, not an empty watchlist (#432).
+        result["ok"] = False
+        return result
+
+    for entry in entries:
+        code = usable_code(entry.get("code"))
+        web_name = str(entry.get("web_name", ""))
+        if code is None:
+            result["excluded"].append(Excluded(web_name=web_name, code=None, reason="no-code"))
+        elif code in codes:
+            result["entries"].append(entry)
+        else:
+            result["excluded"].append(Excluded(web_name=web_name, code=code, reason="owned"))
+    return result
+
+
+def _run(returnees_json: str, waivers_json: str) -> None:
+    with open(returnees_json, encoding="utf-8") as f:
+        radar = json.load(f)
+    with open(waivers_json, encoding="utf-8") as f:
+        waivers = json.load(f)
+    if not isinstance(radar, dict) or not isinstance(waivers, dict):
+        # Neither file is an envelope at all; say so in the same shape rather
+        # than raise, since the orchestrator parses stdout either way.
+        json.dump(
+            JoinResult(ok=False, metadata={}, entries=[], excluded=[], warnings=[JoinWarning(type="envelope-unreadable")]),
+            sys.stdout,
+        )
+        return
+    json.dump(join(radar, waivers), sys.stdout)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Narrow the returnee radar to the players still in the draft waiver pool, joined on code.",
+    )
+    parser.add_argument(
+        "--returnees-json",
+        required=True,
+        metavar="PATH",
+        dest="returnees_json",
+        help="Path to fpl returnees --format json output.",
+    )
+    parser.add_argument(
+        "--waivers-json",
+        required=True,
+        metavar="PATH",
+        dest="waivers_json",
+        help="Path to fpl waivers --format json output.",
+    )
+    args = parser.parse_args()
+    _run(args.returnees_json, args.waivers_json)
+
+
+if __name__ == "__main__":
+    main()