fplkit 2.1.0__tar.gz → 2.2.0__tar.gz

{fplkit-2.1.0 → fplkit-2.2.0}/.agents/TOOLS.md

@@ -26,7 +26,7 @@ Errors use `emit_json_error()` with `{"command", "error"}` shape.
 |---------|-------------|------|--------|-------------|---------|
 | `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, and reports which config/data/cache directories are in use. Distinguishes broken (needs a fix today) from stale (self-corrects). Exits non-zero when something is broken | 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, 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 (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 |
 | `fixtures` | Show fixtures for a gameweek | Yes | General | No | direct-api |
 | `player` | Look up a player's stats, xG, ownership and fixture run. 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`. 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 |
@@ -36,15 +36,16 @@ Errors use `emit_json_error()` with `{"command", "error"}` shape.
 | `xg` | Analyse underlying stats: xG, xA, overperformers | Yes | General | No | via-agent |
 | `price-changes` | Show price changes and transfer activity | No | General | No | via-agent |
 | `price-history` | Show price trajectory and transfer momentum | 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`, `quality_bar_available`, `quality_bar_applied` and `enrichment_requested`/`_available`/`_note`/`_count`; `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 | 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`. 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). 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` | Yes | General | No | via-agent |
-| `captain` | Analyse and rank captain options for next gameweek. 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 | Yes | Classic | Yes | via-agent |
-| `differentials` | Find differential picks - high potential, low ownership. Inverted consistency bonus (volatile players score higher, phased in GW6-10) | Yes | Classic | Yes | via-agent |
-| `targets` | Find transfer targets - high performers across all ownership. Consistency bonus (CV-xGI percentile, phased in GW6-10) | 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 | Yes | General | Yes | via-agent |
-| `allocate` | Select mathematically optimal 15-player squad within budget | Yes | Classic | Yes | direct-api |
-| `waivers` | Show waiver recommendations for your draft league | Yes | Draft | Yes | via-agent |
+| `captain` | Analyse and rank captain options for next gameweek. 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). 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 |
+| `targets` | Find transfer targets - high performers across all ownership. Consistency bonus (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 |
+| `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. 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 | General | Yes | via-agent |
+| `allocate` | Select mathematically optimal 15-player squad within budget. 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; they stay in the solver pool | 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. 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 | Draft | Yes | via-agent |
 | `squad` | Analyse your FPL squad health and fixtures | Yes | General | No | via-agent |
 | `squad grid` | Show squad fixture difficulty grid | Yes | General | No | via-agent |
 | `squad sell-prices` | Show squad sell prices and financial breakdown | Yes | Classic | No | direct-api |
@@ -54,7 +55,7 @@ Errors use `emit_json_error()` with `{"command", "error"}` shape.
 | `chips remove` | Remove a planned chip from a gameweek | No | Classic | No | direct-api |
 | `chips sync` | Sync chip usage from FPL API | No | Classic | No | direct-api |
 | `ratings` | Display team ratings | No | General | Yes | direct-api |
-| `ratings update` | Recalculate ratings from fixture results | No | General | Yes | direct-api |
+| `ratings update` | Recalculate ratings from fixture results (shrunk toward the previous-season prior before GW12; seeds from the prior when no results exist yet) | No | General | Yes | direct-api |
 | `intel` | Show season preview intel collected per team, with coverage and per-gameweek decay. JSON `metadata` carries `coverage.usable_as` (`full` / `negative_filter_only` / `none`), `section_confidence`, `sections_live`/`sections_expired`, `decay_schedule`, `team_set_warning` and `warnings`. `-g/--gameweek` ages the payload to any gameweek; `--show-decay` prints the expiry schedule | Yes | General | No | direct-api |
 | `intel schema` | Print the preview file format with every field explained | No | General | No | direct-api |
 | `intel init` | Scaffold an empty preview file per Premier League team (`--force` overwrites). Stubs never count toward coverage | No | General | No | direct-api |
@@ -79,7 +80,7 @@ Skills write their own outputs (`gw{N}-recommendations.md`, `gw{N}-squad-builder
 
 | Skill | Path | Purpose | Compatibility |
 |-------|------|---------|--------------|
-| gw-prep | `skills/gw-prep/` | Gameweek preparation recommendations for classic and draft (embed / rederive / transfer branches; Phase B9 preview intel; Phase E post-write validation) | Full: Claude Code. Partial: Codex, Cursor, Copilot |
+| gw-prep | `skills/gw-prep/` | Gameweek preparation recommendations for classic and draft (embed / rederive / transfer branches; Phase B9 preview intel; Phase B10 injury returnee radar; Phase E post-write validation) | Full: Claude Code. Partial: Codex, Cursor, Copilot |
 | update-gw-prep | `skills/update-gw-prep/` | Append GW update to existing recommendations | Full: Claude Code, Codex, Cursor, Copilot |
 | squad-builder | `skills/squad-builder/` | Build optimal 15-player squad (wildcard, free hit, season start; Phase B3 preview intel gate) | Full: Claude Code, Codex, Cursor, Copilot |
 | preview-ingest | `skills/preview-ingest/` | Convert season preview prose into structured per-team intel files, resolve player codes, verify coverage | Full: Claude Code (parallel per team), Codex, Cursor, Copilot |
@@ -107,7 +108,9 @@ Python classes in `fpl_cli/agents/` that implement `async run(context) -> AgentR
 
 **Notes:**
 - BenchOrderAgent and StartingXIAgent have no CLI command - they are invoked by gw-prep skill wrapper scripts in `.agents/skills/gw-prep/scripts/`
+- Every scoring family holds players known not to be playing out of the GW1-9 shrinkage; 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
 - `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`)
 - `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; always exits 0.
 - Both scripts 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.

{fplkit-2.1.0 → fplkit-2.2.0}/.agents/skills/gw-prep/SKILL.md

@@ -13,7 +13,7 @@ compatibility:
   copilot: fallback (sequential execution)
 ---
 
-<!-- CLI commands composed: status, chips, chips sync, chips timing, fdr, captain, waivers, squad grid, squad sell-prices, price-history, player, stats, intel -->
+<!-- CLI commands composed: status, chips, chips sync, chips timing, fdr, captain, waivers, squad grid, squad sell-prices, price-history, player, stats, intel, returnees -->
 
 # Gameweek Preparation
 
@@ -231,6 +231,31 @@ Read `metadata.coverage.usable_as` and store it as `intel_gate`:
 With partial coverage the written-up teams carry annotations and the rest carry nothing, so absence
 of a flag would read as absence of merit. Store the payload as `intel` for Phase C.
 
+### B10 -- Injury Returnee Radar
+
+```bash
+fpl returnees --enrich --format json
+```
+
+Flagged players -- injured, suspended, unavailable, doubtful -- whose expected return lands inside
+`metadata.window` gameweeks and who clear the radar's quality bar. Each entry in `data.entries`
+carries the return estimate and where it came from (`expected_return`, `return_gameweek`,
+`return_source`, `escalation_basis`), a quality verdict (`quality.passed`, `quality.meets_stash`)
+and what moved since the previous run (`transition`). `data.departures` says who left the
+watchlist and why.
+
+`--enrich` searches the web for fresher return timing on the players FPL's own news field is silent
+or stale about, which is what supplies a date for the injured majority. It needs a Perplexity API
+key; without one the command skips enrichment, records why in `metadata.enrichment_note` and still
+returns the FPL-sourced watchlist -- so this step is never a reason to abort the run.
+
+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
+like every other cited source -- so its numbers are grounded the same way every other cited number
+is.
+
 <!-- 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.
@@ -288,6 +313,13 @@ Branch on `squad_builder_result` (set in Phase A3; unset on transfer weeks):
 >   ("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)
+>   **Informational only.** Render it as the Returning Soon section of the Classic output template,
+>   one row per entry in `data.entries`, quoting only fields present in that payload. The
+>   injury/suspension rule in the analysis rules above governs what may be recommended while a
+>   player is flagged, and its classic branch is what bars transfer recommendations -- inline
+>   late-change swaps included -- from naming a tracked returnee. Do not restate or relax it here.
+>
 > <!-- ADAPT: Add your own further supplementary data sources here (newsletters, external reports) -->
 >
 > **Embedded Classic Squad (from squad-builder — insert this as the `### Classic Squad` section):**
@@ -302,7 +334,7 @@ Branch on `squad_builder_result` (set in Phase A3; unset on transfer weeks):
 >
 > For Phase C2.5 (`transfer_eval.py`): on embed mode, the OUT-candidate pool is the 15 players in the Player column of the embedded Starting XI and Bench tables (not the current `fpl squad grid`). Use this to evaluate whether any late-breaking swaps are justified.
 >
-> **Sections to produce:** Chip Timing (from B6), Momentum Alerts (from B5/B8), pFDR Overview (from B1), and the `### Classic Squad` block (embedded verbatim or swap-edited with trailing note). **Suppress:** Captain Pick top-3 table (captain is inside the embedded block), standalone Bench Order section (bench order is inside the embedded block), and Transfer Recommendations section (any swaps are applied inline in the block).
+> **Sections to produce:** Chip Timing (from B6), Momentum Alerts (from B5/B8), Returning Soon (from B10), pFDR Overview (from B1), and the `### Classic Squad` block (embedded verbatim or swap-edited with trailing note). **Suppress:** Captain Pick top-3 table (captain is inside the embedded block), standalone Bench Order section (bench order is inside the embedded block), and Transfer Recommendations section (any swaps are applied inline in the block).
 >
 > **User workflow note:** The `### Classic Squad` block is the final 15-player squad the user should enter into FPL. If a trailing `> Late change:` note is present, it explains the swap — the user can revert it in the FPL site before saving if they disagree.
 >
@@ -359,6 +391,13 @@ Proceed immediately (non-interactive).
 >   ("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)
+>   **Informational only.** Render it as the Returning Soon section of the Classic output template,
+>   one row per entry in `data.entries`, quoting only fields present in that payload. The
+>   injury/suspension rule in the analysis rules above governs what may be recommended while a
+>   player is flagged, and its classic branch is what bars transfer recommendations -- inline
+>   late-change swaps included -- from naming a tracked returnee. Do not restate or relax it here.
+>
 > <!-- ADAPT: Add your own further supplementary data sources here (newsletters, external reports) -->
 >
 > Apply squad-builder rules from `references/rules.md` for full squad selection. Prepend the fallback banner (Variant A/B/C — see `references/output-template.md` for exact wording) on the line immediately before the Classic section heading in the output file. Do not include `squad_builder_mode` in the frontmatter — the squad was re-derived, not embedded from squad-builder.
@@ -391,7 +430,13 @@ Proceed immediately (non-interactive).
 > - Squad: {B4 output}
 > - Price movements: {B5 output}
 > - Chip timing: {B6 output}
-> - Stats: {stats_form}, {stats_transfer_momentum}, {stats_mid_xgi}, {stats_fwd_xgi}, {stats_def_clean_sheets} (from B8)
+> - Stats: {stats_form}, {stats_transfer_momentum}, {stats_mid_xgi}, {stats_fwd_xgi}, {stats_def_clean_sheets} (from B8)>
+> - Returning soon: {returnee_radar} (from B10)
+>   **Informational only.** Render it as the Returning Soon section of the Classic output template,
+>   one row per entry in `data.entries`, quoting only fields present in that payload. The
+>   injury/suspension rule in the analysis rules above governs what may be recommended while a
+>   player is flagged, and its classic branch is what bars transfer recommendations -- inline
+>   late-change swaps included -- from naming a tracked returnee. Do not restate or relax it here.
 >
 > **Bench Boost instructions:**
 >
@@ -436,6 +481,13 @@ Proceed immediately (non-interactive).
 >   ("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)
+>   **Informational only.** Render it as the Returning Soon section of the Classic output template,
+>   one row per entry in `data.entries`, quoting only fields present in that payload. The
+>   injury/suspension rule in the analysis rules above governs what may be recommended while a
+>   player is flagged, and its classic branch is what bars transfer recommendations -- inline
+>   late-change swaps included -- from naming a tracked returnee. Do not restate or relax it here.
+>
 > <!-- ADAPT: Add your own further supplementary data sources here (newsletters, external reports) -->
 >
 > Produce the **Classic** section of the output template.
@@ -463,6 +515,8 @@ Proceed immediately (non-interactive).
 >
 > **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.
+>
 > - Waivers: {B3 output}
 > - Squad: {B4 output}
 > - Stats: {stats_form}, {stats_transfer_momentum}, {stats_mid_xgi}, {stats_fwd_xgi}, {stats_def_clean_sheets} (from B8)
@@ -472,6 +526,38 @@ Proceed immediately (non-interactive).
 >   ("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.
+>
+> **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.
+>
+> 1. **Elite by prior:** `quality.meets_stash` is `true`.
+> 2. **Returning soon enough:** `escalation_eligible` is `true`. The command has already applied
+>    `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.
+> 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
+>    `metadata.stash_upgrade_margin`, which already carries the effective configured value; both
+>    are quality points on the same 0-100 scale. If the script errors, or the margin is missing
+>    from the metadata, or the delta does not clear it, do not escalate. A drop-priority ordering
+>    always yields a lowest-ranked player and so can never answer "no" — the margin is what makes
+>    this gate refusable.
+>
+> Write every stash claim as a stash, never as a straight upgrade: it spends a roster slot until the
+> player is fit again, and it is bought to lock the asset before a rival can claim them. Each stash
+> row's Rationale must carry the expected return (`expected_return`, or `return_gameweek` where the
+> date is unknown) and name the provenance of that date from `escalation_basis`. The
+> injury/suspension rule in the analysis rules above is the single authority on what may be
+> recommended while a player is flagged.
+>
 > <!-- ADAPT: Add your own further supplementary data sources here (newsletters, external reports) -->
 >
 > Additionally enforce: every waiver swap must be position-for-position (MID out → MID in, DEF out → DEF in, etc.). Cross-position swaps are illegal under FPL Draft rules.

{fplkit-2.1.0 → fplkit-2.2.0}/.agents/skills/gw-prep/references/output-template.md

@@ -76,6 +76,18 @@ For each transfer, include:
 - Form summary
 - Price trend
 
+### Returning Soon
+
+_Informational only. Omit the section when the radar payload has no entries._
+
+| Player | Team | Pos | Quality | Expected Return | Chance | Change |
+|--------|------|-----|---------|-----------------|--------|--------|
+| | | | | | | |
+
+One row per entry in the `fpl returnees` payload (`data.entries`). Quality = `quality.basis` plus whether it clears the stash bar (`quality.meets_stash`). Expected Return = `expected_return`, or `return_gameweek` where only a gameweek is known, or `Unknown`. Chance = `chance_of_playing`. Change = `transition` since the previous run, blank when nothing moved.
+
+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. No transfer recommendation above may name a tracked returnee (see the injury/suspension rule in `references/rules.md`).
+
 ### Classic Squad
 
 _Embed-mode only: the orchestrator replaces this placeholder at runtime with the `{embedded_classic_squad_block}` extracted from `gw{N}-squad-builder.md`. Do not populate this section manually — it is produced by the C1 sub-agent._
@@ -124,6 +136,18 @@ Cross-referenced against current squad holdings.
 
 Outlook = multi-GW quality delta (target score). This GW = lineup impact delta. Both from `transfer_eval.py`.
 
+### Returning Soon
+
+_Tracked returnees still unowned in the league. Omit the section when nothing qualifies._
+
+| Player | Team | Pos | Quality | Expected Return | Chance | Change | Verdict |
+|--------|------|-----|---------|-----------------|--------|--------|---------|
+| | | | | | | | |
+
+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`.
+
+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.
+
 ### Starting XI
 
 Recommended lineup with formation (via lineup engine).

{fplkit-2.1.0 → fplkit-2.2.0}/.agents/skills/gw-prep/references/rules.md

@@ -45,7 +45,7 @@ When `mode = "squad-builder"`:
 4. **Fixture run** -- as with classic, weight the next 3 gameweeks of fixtures rather than just the immediate one.
 5. **Maximum 5 waiver suggestions** -- for each: player to drop, player to claim, positional context, and fixture rationale.
 6. **Position-for-position only** -- FPL Draft squads are locked at 2 GK / 5 DEF / 5 MID / 3 FWD. Every waiver swap must be position-for-position (e.g. MID out → MID in). Cross-position swaps are structurally illegal and will be rejected by Phase D1.
-7. **Waiver pool discipline** -- only recommend players returned by `fpl waivers --format json`. Players appearing in other data sources (e.g. `fpl stats`) are not necessarily available; never recommend a claim not in the waiver pool.
+7. **Waiver pool discipline** -- only recommend players returned by `fpl waivers --format json`. Players appearing in other data sources (e.g. `fpl stats`) are not necessarily available; never recommend a claim not in the waiver pool. Within that output, `data.pool` establishes availability only -- it is the full unowned roster, unranked and untruncated. Ranked claims come from `data.top_targets` and `data.targets_by_position`; the one claim that may rest on `data.pool` membership alone is a stash claim for a tracked returnee, whom the waiver scoring suppresses by design.
 
 ## Transfer/Waiver Evaluation Script
 
@@ -63,7 +63,10 @@ For all formats:
 1. **Recent form** -- last 4 GW average points, minutes played (flag rotation risks below 60 mins average).
 2. **Expected stats** -- where available, prefer xG/xA-based analysis over raw goals/assists. Flag players significantly over- or under-performing their expected stats.
 3. **Set-piece involvement** -- note players on corners, free kicks, and penalties as these provide floor-raising opportunities.
-4. **Injury/suspension flags** -- check player availability. Never recommend a player flagged as injured or suspended without explicitly noting the risk.
+4. **Injury/suspension flags** -- check player availability. Never recommend a player flagged as injured or suspended without explicitly noting the risk. A **tracked returnee** -- any entry in `data.entries` of the `fpl returnees` payload, excluding those whose `status` is `"d"` with a non-zero `chance_of_playing` -- is held to a tighter rule than that:
+   - **Draft:** a tracked returnee may be recommended only as an explicit stash claim -- a roster slot spent until the player is fit, to lock the asset before a rival claims them. Never present one as a straight upgrade for this gameweek. Every stash claim must carry the expected return (`expected_return`, or `return_gameweek` where the date is unknown) and name the provenance of that date from `escalation_basis`. SKILL.md Phase C2 holds the gates a watchlist row must clear before it becomes a claim.
+   - **Classic:** the returnee watchlist is informational. Transfer recommendations -- including any inline late-change swap on an embedded squad -- must not name a tracked returnee. Classic has no scarcity race: a returnee can be bought the week they are actually back.
+   - **Unchanged for everyone else:** a doubtful (`d`) player with a non-zero chance of playing is not a tracked returnee. They may still be recommended with the risk explicitly noted, exactly as before.
 
 ## Momentum Alerts
 

{fplkit-2.1.0 → fplkit-2.2.0}/.agents/skills/gw-prep/scripts/validate_draft_waivers.py

@@ -25,7 +25,7 @@ import json
 import re
 import sys
 import unicodedata
-from typing import TypedDict
+from typing import NotRequired, TypedDict, cast
 
 from fpl_cli.utils.markdown import HeadingMatcher, find_section, leaf_body
 
@@ -58,6 +58,7 @@ class PoolEntry(TypedDict):
     player_name: str
     position: str
     team_short: str
+    id: NotRequired[int]
 
 
 class SquadEntry(TypedDict):
@@ -125,24 +126,65 @@ def _shape_check_squad(data: dict) -> bool:
         return False
 
 
+def _entries_shape_ok(entries: object) -> bool:
+    """Return True if entries is a list of name/position records (empty is fine)."""
+    if not isinstance(entries, list):
+        return False
+    if not entries:
+        return True
+    sample = entries[0]
+    return isinstance(sample, dict) and "player_name" in sample and "position" in sample
+
+
 def _shape_check_waivers(data: dict) -> bool:
-    """Return True if waivers JSON has the expected shape."""
+    """Return True if waivers JSON has the expected shape.
+
+    `pool` is the full unowned roster and is what membership is checked against;
+    `top_targets` is the ranked subset older waivers JSON carried on its own.
+    Either satisfies the guard, so a cached file still validates.
+
+    A `pool` key that is present but unusable deliberately fails the file rather
+    than falling through to `top_targets`. The two are not interchangeable: a
+    flagged player is kept out of `top_targets` by the availability factor no
+    matter how strong the case for claiming them, so checking membership
+    against the ranked subset reports every legitimate injury claim as a miss.
+    Failing here warns once and suppresses the pool check for the run, which
+    beats a page of false positives on exactly the claims this validates.
+    """
     try:
-        targets = data["data"]["top_targets"]
-        if not isinstance(targets, list):
-            return False
-        if not targets:
-            return True
-        sample = targets[0]
-        return "player_name" in sample and "position" in sample
+        payload = data["data"]
+        if "pool" in payload:
+            return _entries_shape_ok(payload["pool"])
+        return _entries_shape_ok(payload["top_targets"])
     except (KeyError, TypeError):
         return False
 
 
 def build_pool(waivers_data: dict) -> dict[tuple[str, str], PoolEntry]:
-    """Build {(position, normalised_name) -> entry} from waivers JSON."""
+    """Build {(position, normalised_name) -> entry} from waivers JSON.
+
+    Reads the full unowned `pool` roster, so a claim for a flagged player is
+    resolvable: the availability factor in the waiver score keeps such a player
+    out of `top_targets` no matter how strong the case for claiming them. Falls
+    back to `top_targets` when `pool` is missing or empty -- an older cached
+    file then validates as it always did rather than reporting every claim as a
+    miss.
+    """
+    payload = waivers_data.get("data", {})
+    entries = payload.get("pool")
+    if not isinstance(entries, list) or not entries:
+        entries = payload.get("top_targets")
+    if not isinstance(entries, list):
+        # The shape check clears a file on either key, so the fallback can still
+        # land on a malformed value. Reporting no pool costs a missed check;
+        # raising here would exit non-zero and break the orchestrator contract.
+        entries = []
+
     pool: dict[tuple[str, str], PoolEntry] = {}
-    for entry in waivers_data.get("data", {}).get("top_targets", []):
+    for raw in entries:
+        if not isinstance(raw, dict):
+            continue
+        entry = cast(PoolEntry, raw)
         pos = entry.get("position", "")
         key = (pos, normalise(entry.get("player_name", "")))
         pool[key] = entry

{fplkit-2.1.0 → fplkit-2.2.0}/.agents/skills/release/SKILL.md

@@ -144,6 +144,27 @@ Actions run.
   repo), update the secret, re-run the job.
 - **PyPI publish fails with OIDC errors**: check the `pypi` environment on
   the repo and the trusted-publisher config on the fplkit PyPI project.
+- **PyPI publish fails on distribution metadata**
+  (`InvalidDistribution: Invalid distribution metadata: '2.5' is not a
+  valid metadata version`): toolchain drift, not a bad tag. `pyproject.toml`
+  requires `hatchling>=1.21` with no upper bound, so the build emits
+  whatever `Metadata-Version` a current hatchling produces, while
+  `pypa/gh-action-pypi-publish` is pinned to a SHA whose bundled twine and
+  packaging predate it. Bump the action pin rather than capping hatchling —
+  PyPI accepts the newer metadata, so the stale half is the action (v1.13.0
+  ships twine 6.1.0 / packaging 25.0 and rejects 2.5; v1.14.2 ships twine
+  7.0.0 / packaging 26.2 and accepts it). Prove it either way by running
+  `twine check` on the built wheel under the pins in each action tag's
+  `requirements/runtime.txt`. This fails at twine's client-side check
+  *before* any upload, so PyPI never receives the version.
+- **Fixing `release.yml` itself needs a retag, not a re-run**: a
+  `release`-triggered run uses the workflow file from the *tagged commit*,
+  so re-running a failed job replays the same broken workflow. Land the fix
+  on main, then `gh release delete vX.Y.Z --cleanup-tag` and re-create the
+  release against main so the tag moves onto the fix. Only safe while the
+  version is still free on PyPI — check `pip index versions fplkit` first.
+  Once PyPI has accepted an upload that number is gone permanently, and the
+  fix has to ship as the next version instead.
 - **Version source drift**: never reintroduce a hardcoded `version =
   "X.Y.Z"` in pyproject.toml — `dynamic = ["version"]` + hatch-vcs is the
   single source of truth. And `fallback-version` belongs under

{fplkit-2.1.0 → fplkit-2.2.0}/.agents/skills/squad-builder/SKILL.md

@@ -309,7 +309,7 @@ Include all of this in the prompt field, populated with position-specific data:
    Run `fpl player "{name}" -f -H` **in parallel** for all candidates in your list.
    For season-start modes with no current-season data, also use `fpl history` data passed in context.
 
-7. **Scoring:** Score each candidate against the mode-specific criteria from rules. Use `quality_score` and `quality_per_m` when available (null for players without Understat data — don't penalise). **Both fields are elite-within-position: never rank or compare candidates across positions by `quality_score` or `quality_per_m`.** A DEF showing 85 and a MID showing 55 is not "the DEF is better" — the ceilings differ by design. Only compare within the position you are currently filling.
+7. **Scoring:** Score each candidate against the mode-specific criteria from rules. Use `quality_score` and `quality_per_m` when available (null for players without Understat data — don't penalise). **Both fields are elite-within-position: never rank or compare candidates across positions by `quality_score` or `quality_per_m`.** A GK showing 90 is "top of the GK pool", not "better than a MID showing 85" — every position is normalised against its own calibrated ceiling, MID and FWD included. Within a position the numbers are trustworthy: elite players in every position read 80+, so a MID at 55 genuinely is mid-tier among MIDs. Only compare within the position you are currently filling.
 
 8. **Return format:** Return a structured ranked list. Per candidate:
    ```

fplkit-2.2.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Date-derived logic (the July season cutover) can break main with no
+    # commit behind it, which push/pull_request triggers never surface.
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check fpl_cli/ scripts/
+
+      - name: Type check
+        run: pyright fpl_cli/ scripts/
+
+      - name: Test
+        run: pytest
+
+      - name: Build package
+        run: pip install hatch && hatch build
+
+  provider-probe:
+    # The hermetic test suite pins our assumption of each provider's schema,
+    # not the schema -- upstream can drift with no commit behind it, which is
+    # exactly what the Monday cron exists for. This job is the one place CI
+    # talks to the live providers: it fails only on "broken" (shape drift),
+    # never on transient unreachability, which the probe reports as unchecked.
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package
+        run: pip install .
+
+      - name: Probe providers
+        env:
+          # Optional: without it the football-data checks report skipped.
+          FOOTBALL_DATA_API_KEY: ${{ secrets.FOOTBALL_DATA_API_KEY }}
+        run: fpl doctor --providers --format json

{fplkit-2.1.0 → fplkit-2.2.0}/AGENTS.md

@@ -4,13 +4,13 @@ fpl-cli - CLI tool for Fantasy Premier League analysis (classic + draft). Distri
 ## Setup & Dev
 ```bash
 source .venv/bin/activate && pip install -e ".[dev]"            # local only — web sessions install globally via setup script
-ruff check fpl_cli/            # Lint
-pyright fpl_cli/               # Type check
+ruff check fpl_cli/ scripts/   # Lint
+pyright fpl_cli/ scripts/      # Type check
 python3 -m pytest tests/       # Tests
 ```
 Run tests as `python3 -m pytest`, never bare `pytest`: in web sessions the `pytest` on PATH is a uv tool shim with its own interpreter and none of the project's dependencies, so it fails at `import pydantic`. If pytest then rejects `--disable-socket` / `--allow-unix-socket`, the dev extra is incomplete — `pip install pytest-socket`.
 
-Entry point: `fpl_cli/cli/__init__.py:main` (Click). Config: `fpl_cli/config/defaults.yaml`, shipped inside the package and resolved as `SHIPPED_CONFIG_DIR` (`paths.py`), + `settings.yaml` in the user config dir (overrides, deep-merged via `platformdirs`; `~/Library/Application Support/fpl-cli/` on macOS). Repo-root `config/` holds only examples and `team_ratings_overrides.yaml` — nothing there is loaded as defaults. All three writable dirs have env overrides: `FPL_CLI_CONFIG_DIR` (settings, managers, overrides; an optional `fixture_predictions.yaml` here overrides the shipped copy; an optional `previews/` dir holds season preview intel read by `fpl intel`), `FPL_CLI_DATA_DIR` (generated data: team ratings, priors, chip plan, sell prices, the append-only `league_history/` ledger and its rebuildable `league_history_counters/` projection — the ledger partitions by season instead of being discarded at rollover, the one store that outlives a season), `FPL_CLI_CACHE_DIR` (disposable). Overrides must be absolute — a relative one resolves against the cwd, so it is rejected with `UserDirError` rather than silently giving a different dir per invocation. Resolve them by calling `user_config_dir()` / `user_data_dir()` / `user_cache_dir()` at point of use — binding one to a module-level constant freezes the override at import time (before `.env` loads); `tests/test_paths.py` enforces this. Ephemeral environments (Claude Code on the web) must set config + data to a persistent workspace or generated data dies with the container; cache can stay local.
+Entry point: `fpl_cli/cli/__init__.py:main` (Click). Config: `fpl_cli/config/defaults.yaml`, shipped inside the package and resolved as `SHIPPED_CONFIG_DIR` (`paths.py`), + `settings.yaml` in the user config dir (overrides, deep-merged via `platformdirs`; `~/Library/Application Support/fpl-cli/` on macOS). Repo-root `config/` holds only examples and `team_ratings_overrides.yaml` — nothing there is loaded as defaults. All three writable dirs have env overrides: `FPL_CLI_CONFIG_DIR` (settings, managers, overrides; an optional `fixture_predictions.yaml` here overrides the shipped copy; an optional `previews/` dir holds season preview intel read by `fpl intel`), `FPL_CLI_DATA_DIR` (generated data: team ratings, priors, chip plan, sell prices, the returnee radar's `returnee_snapshot.json` week-over-week baseline (season-stamped, discarded on mismatch like `player_prior.yaml`), the append-only `league_history/` ledger and its rebuildable `league_history_counters/` projection — the ledger partitions by season instead of being discarded at rollover, the one store that outlives a season), `FPL_CLI_CACHE_DIR` (disposable). Overrides must be absolute — a relative one resolves against the cwd, so it is rejected with `UserDirError` rather than silently giving a different dir per invocation. Resolve them by calling `user_config_dir()` / `user_data_dir()` / `user_cache_dir()` at point of use — binding one to a module-level constant freezes the override at import time (before `.env` loads); `tests/test_paths.py` enforces this. Ephemeral environments (Claude Code on the web) must set config + data to a persistent workspace or generated data dies with the container; cache can stay local.
 
 ## Architecture
 Agents inherit `fpl_cli/agents/base.py:Agent`, implement `async run(context: dict | None) -> AgentResult`. Organised in `agents/{data,analysis,action,orchestration}/`. AgentResult statuses: SUCCESS, PARTIAL, FAILED, PENDING_APPROVAL.
@@ -76,6 +76,7 @@ For a complete inventory of CLI commands, analysis agents, and skills with JSON
 - Draft has no captains, no budget, no transfers and no chips — acquisition is via waivers and free agents
 
 ## Rules
+- This repo is public: never put real manager or league names, entry/league IDs, or FPL account details into commits, PR titles or bodies, issues, or CHANGELOG.md. Use placeholders when quoting generated reports from the configured `reports.output_dir`. Footballer and club names are fine — they are public data. Before pushing, check the branch for a pre-existing leak and flag it rather than pushing over it.
 - Verify before asserting: don't state that a command, file, function, or data point exists without checking first (read the file, run the command, grep for the name)
 - Find-and-replace: review each replacement in context - don't blindly replace substrings in unrelated identifiers
 - Removing/replacing X: new implementation must have zero dependencies on X

{fplkit-2.1.0 → fplkit-2.2.0}/CHANGELOG.md

@@ -1,6 +1,46 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [2.1.0] - 2026-08-23
+
+### Bug Fixes
+
+- survive a keyring backend that panics below Python
+- validate pre-season teams and guard pFDR against unrated seasons
+- consistent non-zero exit codes on command failure, friendly pre-season squad 404 (#47)
+- drop stale committed team_ratings.yaml seed
+- rank promoted teams against the PL, not the Championship
+- config dirs must be absolute, and gated commands name their gate (#46)
+- layer team_managers.yaml over the shipped copy per club
+- make team ratings and manager config season-aware (#56)
+- stop gw-prep squad validation failing when a heading names the formation
+- keep the new-signing flag alive until real minutes exist, not until the window shuts
+- stop gw-prep validators mislocating sections on drifted headings
+- stop review inventing fines, positions and rolled transfers at gameweek 1
+- keep the status classic section alive pre-season and stop last-place fines misreading a partial league table
+- report exact classic league size and rank in status instead of page-one figures
+- keep league recap accurate for large leagues and gameweek 1
+- cap the managers named in a tied league recap bench-haul award
+- pin PuLP below 4.0 so squad allocation keeps working (#80)
+- stop a new season's reports overwriting the previous season's (#90)
+
+### Features
+
+- add FPL_CLI_DATA_DIR override so the data dir survives ephemeral environments
+- user config dir copy of fixture_predictions.yaml overrides shipped copy
+- add `fpl intel` for season preview intel with per-gameweek decay
+- add preview-ingest skill for turning preview prose into intel files
+- wire season preview intel into squad-builder
+- wire season preview intel into gw-prep and update-gw-prep
+- point-in-time headline numbers and league positions for replays (#75)
+- record every gameweek to a durable league history store (#76)
+- surface streaks and season phase in every output (#77)
+- add `fpl doctor` to surface stale config and dead IDs (#98)
+
+### Performance
+
+- stop fpl player and fpl stats fetching data they discard (#96)
+
 ## [2.0.0] - 2026-05-25
 
 ### Bug Fixes

{fplkit-2.1.0 → fplkit-2.2.0}/CLAUDE.md

@@ -4,13 +4,13 @@ fpl-cli - CLI tool for Fantasy Premier League analysis (classic + draft). Distri
 ## Setup & Dev
 ```bash
 source .venv/bin/activate && pip install -e ".[dev]"            # local only — web sessions install globally via setup script
-ruff check fpl_cli/            # Lint
-pyright fpl_cli/               # Type check
+ruff check fpl_cli/ scripts/   # Lint
+pyright fpl_cli/ scripts/      # Type check
 python3 -m pytest tests/       # Tests
 ```
 Run tests as `python3 -m pytest`, never bare `pytest`: in web sessions the `pytest` on PATH is a uv tool shim with its own interpreter and none of the project's dependencies, so it fails at `import pydantic`. If pytest then rejects `--disable-socket` / `--allow-unix-socket`, the dev extra is incomplete — `pip install pytest-socket`.
 
-Entry point: `fpl_cli/cli/__init__.py:main` (Click). Config: `fpl_cli/config/defaults.yaml`, shipped inside the package and resolved as `SHIPPED_CONFIG_DIR` (`paths.py`), + `settings.yaml` in the user config dir (overrides, deep-merged via `platformdirs`; `~/Library/Application Support/fpl-cli/` on macOS). Repo-root `config/` holds only examples and `team_ratings_overrides.yaml` — nothing there is loaded as defaults. All three writable dirs have env overrides: `FPL_CLI_CONFIG_DIR` (settings, managers, overrides; an optional `fixture_predictions.yaml` here overrides the shipped copy; an optional `previews/` dir holds season preview intel read by `fpl intel`), `FPL_CLI_DATA_DIR` (generated data: team ratings, priors, chip plan, sell prices, the append-only `league_history/` ledger and its rebuildable `league_history_counters/` projection — the ledger partitions by season instead of being discarded at rollover, the one store that outlives a season), `FPL_CLI_CACHE_DIR` (disposable). Overrides must be absolute — a relative one resolves against the cwd, so it is rejected with `UserDirError` rather than silently giving a different dir per invocation. Resolve them by calling `user_config_dir()` / `user_data_dir()` / `user_cache_dir()` at point of use — binding one to a module-level constant freezes the override at import time (before `.env` loads); `tests/test_paths.py` enforces this. Ephemeral environments (Claude Code on the web) must set config + data to a persistent workspace or generated data dies with the container; cache can stay local.
+Entry point: `fpl_cli/cli/__init__.py:main` (Click). Config: `fpl_cli/config/defaults.yaml`, shipped inside the package and resolved as `SHIPPED_CONFIG_DIR` (`paths.py`), + `settings.yaml` in the user config dir (overrides, deep-merged via `platformdirs`; `~/Library/Application Support/fpl-cli/` on macOS). Repo-root `config/` holds only examples and `team_ratings_overrides.yaml` — nothing there is loaded as defaults. All three writable dirs have env overrides: `FPL_CLI_CONFIG_DIR` (settings, managers, overrides; an optional `fixture_predictions.yaml` here overrides the shipped copy; an optional `previews/` dir holds season preview intel read by `fpl intel`), `FPL_CLI_DATA_DIR` (generated data: team ratings, priors, chip plan, sell prices, the returnee radar's `returnee_snapshot.json` week-over-week baseline (season-stamped, discarded on mismatch like `player_prior.yaml`), the append-only `league_history/` ledger and its rebuildable `league_history_counters/` projection — the ledger partitions by season instead of being discarded at rollover, the one store that outlives a season), `FPL_CLI_CACHE_DIR` (disposable). Overrides must be absolute — a relative one resolves against the cwd, so it is rejected with `UserDirError` rather than silently giving a different dir per invocation. Resolve them by calling `user_config_dir()` / `user_data_dir()` / `user_cache_dir()` at point of use — binding one to a module-level constant freezes the override at import time (before `.env` loads); `tests/test_paths.py` enforces this. Ephemeral environments (Claude Code on the web) must set config + data to a persistent workspace or generated data dies with the container; cache can stay local.
 
 ## Architecture
 Agents inherit `fpl_cli/agents/base.py:Agent`, implement `async run(context: dict | None) -> AgentResult`. Organised in `agents/{data,analysis,action,orchestration}/`. AgentResult statuses: SUCCESS, PARTIAL, FAILED, PENDING_APPROVAL.
@@ -76,6 +76,7 @@ For a complete inventory of CLI commands, analysis agents, and skills with JSON
 - Draft has no captains, no budget, no transfers and no chips — acquisition is via waivers and free agents
 
 ## Rules
+- This repo is public: never put real manager or league names, entry/league IDs, or FPL account details into commits, PR titles or bodies, issues, or CHANGELOG.md. Use placeholders when quoting generated reports from the configured `reports.output_dir`. Footballer and club names are fine — they are public data. Before pushing, check the branch for a pre-existing leak and flag it rather than pushing over it.
 - Verify before asserting: don't state that a command, file, function, or data point exists without checking first (read the file, run the command, grep for the name)
 - Find-and-replace: review each replacement in context - don't blindly replace substrings in unrelated identifiers
 - Removing/replacing X: new implementation must have zero dependencies on X