fplkit 2.0.0__tar.gz → 2.2.0__tar.gz

fplkit-2.2.0/.agents/TOOLS.md

@@ -0,0 +1,116 @@
+# Tools & Capabilities
+
+Complete inventory of fpl-cli's composable surface. For architectural diagrams and data flow, see [docs/architecture.md](../docs/architecture.md). For FPL-context usage guidance, see [.claude/output-styles/fpl-mate.md](../.claude/output-styles/fpl-mate.md).
+
+## JSON Envelope
+
+All `--format json` commands emit a standard envelope via `emit_json()` in `fpl_cli/cli/_json.py`:
+
+```json
+{
+  "command": "<command-name>",
+  "metadata": { ... },
+  "data": [ ... ]
+}
+```
+
+- `command` - the CLI command name (e.g. `"captain"`, `"chips-timing"`)
+- `metadata` - command-specific context (typically includes `gameweek`)
+- `data` - the payload (list or dict, varies per command)
+
+Errors use `emit_json_error()` with `{"command", "error"}` shape.
+
+## 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, 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 |
+| `history` | Show historical player performance across seasons | Yes | General | No | direct-api |
+| `league` | Show live league standings for Classic and Draft leagues | No | General | No | direct-api |
+| `fdr` | Analyse fixture difficulty - easy runs, blanks, doubles | Yes | General | No | via-agent |
+| `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. 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 |
+| `chips` | View and plan FPL chip usage | Yes | Classic | No | direct-api |
+| `chips timing` | Recommend chip timing based on blank/double GW exposure | Yes | Classic | No | via-agent |
+| `chips add` | Plan a chip for a gameweek | No | Classic | No | direct-api |
+| `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 (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 |
+| `intel show` | Show one team's preview, aged to the current gameweek | Yes | General | No | direct-api |
+| `intel resolve` | Match preview player names to FPL `element_code`s; `--write` saves them back with comments preserved (never touching an existing code), `--all` re-resolves coded players and with `--write` saves corrections over them. Ambiguity is reported, never guessed | Yes | General | No | direct-api |
+| `credentials set` | Store FPL email and password in system keyring | No | Classic | No | direct-api |
+| `credentials clear` | Remove FPL credentials from system keyring | No | Classic | No | direct-api |
+
+**Column key:**
+- **JSON** - supports `--format json` output
+- **Format** - Classic (classic league only), Draft (draft league only), General (both)
+- **Experimental** - requires `custom_analysis: true` in settings; hidden from `--help` by default, and invoking one while it is off reports the toggle and the settings.yaml being read
+- **Pattern** - `direct-api` (API client only), `via-agent` (uses analysis agent), `mixed` (both patterns in subcommands)
+
+**Report paths are season-partitioned.** Every command that saves a report writes to `<dir>/<season>/gw{N}-*.md`, where `<season>` is the hyphenated label (`2026-27`). Report filenames carry a gameweek but no season, so a flat directory lets one season's GW21 file overwrite the previous season's. This applies to an explicit `--output` too. Any skill or script writing alongside these reports must use the same season directory, and must take the label from `fpl status --format json` (`metadata.season`) rather than hardcoding it — a hardcoded label silently rots at the July rollover.
+
+## Skills
+
+Agent playbooks in `.agents/skills/`. Each has a `SKILL.md` entry point. Claude Code discovers them via the `.claude/skills/` symlink.
+
+Skills write their own outputs (`gw{N}-recommendations.md`, `gw{N}-squad-builder.md`, `season-start-squad.md`) into the same `<output dir>/<season>/` directory, for the same reason.
+
+| 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 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 |
+| release-notes | `skills/release-notes/` | Draft release notes and suggest the next semver (read-only preview; never tags or publishes) | Full: Claude Code, Codex, Cursor, Copilot |
+| release | `skills/release/` | Cut a release end-to-end: preflight, notes via release-notes, approval gate, publish GitHub release (tag drives PyPI publish + changelog automation) | Full: Claude Code (local), Codex, Cursor, Copilot. Partial: Claude Code web (publish step handed to user) |
+| create-pr | `skills/create-pr/` | Open a PR for the current branch: conventional-commit title (the changelog line) + why-first prose body in the fpl-cli PR description style | Full: Claude Code, Codex, Cursor, Copilot |
+
+## Analysis Agents
+
+Python classes in `fpl_cli/agents/` that implement `async run(context) -> AgentResult`.
+
+| Agent | Module | Category | CLI Commands | External Consumers |
+|-------|--------|----------|-------------|-------------------|
+| FixtureAgent | `agents/data/fixture.py` | Data | `fdr`, `player -f`, `chips timing`, `preview` | - |
+| PriceAgent | `agents/data/price.py` | Data | `price-changes`, `preview` | - |
+| ScoutAgent | `agents/data/scout.py` | Data | `preview` | - |
+| StatsAgent | `agents/analysis/stats.py` | Analysis | `xg`, `targets`, `differentials`, `preview` | - |
+| CaptainAgent | `agents/analysis/captain.py` | Analysis | `captain`, `differentials` | - |
+| SquadAnalyzerAgent | `agents/analysis/squad_analyzer.py` | Analysis | `squad` | - |
+| BenchOrderAgent | `agents/analysis/bench_order.py` | Analysis | - | gw-prep skill |
+| StartingXIAgent | `agents/analysis/starting_xi.py` | Analysis | - | gw-prep skill |
+| TransferEvalAgent | `agents/analysis/transfer_eval.py` | Analysis | `transfer-eval` | gw-prep skill |
+| WaiverAgent | `agents/action/waiver.py` | Action | `waivers` | - |
+| 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/`
+- 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.2.0/.agents/skills/create-pr/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: create-pr
+description: >
+  Use when the user asks to create a pull request or PR for the current
+  branch — "create a PR", "open a PR", "raise a PR", "push and create a
+  PR", "ship this branch". Writes the title as the changelog line
+  (conventional commits) and the body in the fpl-cli PR description style:
+  first-person prose, why-first, no boilerplate sections. Also the style
+  reference whenever a session writes a PR title or body outside the skill.
+model: sonnet
+compatibility:
+  claude-code: full (gh locally, GitHub MCP tools on the web)
+  codex: full (gh)
+  cursor: full (gh)
+  copilot: full (gh)
+---
+
+# Create Pull Request
+
+Opens a PR for the current branch against main: pushes the branch, writes
+a conventional-commit title, and a prose description in the fpl-cli PR
+description style. Solo repo — there are no reviewers, squads, or labels
+to assign, and the PR is created ready (not draft) unless asked otherwise.
+
+## Title: the changelog line
+
+PRs squash-merge with the title as the commit subject on main, and
+git-cliff publishes `feat:`/`fix:`/`refactor:`/`perf:` subjects verbatim in
+CHANGELOG.md and the GitHub release notes. The `PR Title` CI check rejects
+anything non-conventional. So:
+
+- Format `type(scope)?!?: subject` — types as in `cliff.toml` (`feat`,
+  `fix`, `refactor`, `perf` are changelog-visible; `chore`, `docs`, `ci`,
+  `test`, `style` are skipped). `!` marks a breaking CLI change and drives
+  a major bump.
+- A changelog-visible title must read as the standalone user-facing change
+  ("fix: pin PuLP below 4.0 so squad allocation keeps working"), never the
+  implementation ("fix: address review feedback").
+- Keep it ≤ 72 characters — GitHub appends ` (#N)` on squash.
+- No issue references in the title; `Closes #N` lives in the body, so the
+  changelog line stays clean.
+- One purpose per PR, so one title can describe it. If no single
+  conventional subject covers the diff, the branch wants splitting, not a
+  vaguer title.
+
+## Description: the fpl-cli PR description style
+
+The body is **flowing first-person prose**, as if explaining the change to
+a colleague. No `## Summary`/`## Changes`/`## Testing` headings, no
+file-by-file changelog, no checklists.
+
+### Tone
+
+First person, conversational, proper sentence casing. Reads like an
+explanation, not a filled-in template.
+
+Good: "The changelog job pushes straight to main, which the new ruleset
+would block — so it now authenticates as the repo admin, who is a bypass
+actor."
+Bad: "## Summary\nThis PR updates the changelog job's authentication."
+
+### Content
+
+- **Open with why, not what.** Start with the problem or context that
+  motivated the change. The diff already shows what changed.
+- **Explain the approach when it is non-obvious.** Natural phrasing ("the
+  general strategy is"), not a formal section.
+- **`Closes #N`** inline when the PR resolves an issue — GitHub closes it
+  on merge. The branch name often carries the number (`claude/issue-46-…`).
+- **Use italics for caveats, scope notes, and verification gaps.**
+  Deliberate omissions, known limitations, and anything you could not
+  verify — and why — go in `_italics_`. In this repo that is usually
+  behaviour needing live FPL API data, LLM provider keys, or the scraper's
+  FPL credentials, none of which a web session has.
+- **Include stats when relevant.** Test counts, performance numbers,
+  migration sizes — plainly stated, at the end.
+
+### Structure and length
+
+No fixed sections. Bullets only where you are genuinely listing items
+(rules, scenarios, per-command effects) — never as the default shape.
+
+Pick the budget before writing, and stay inside it:
+
+| Change | Body |
+|---|---|
+| Dependency bump, config/data refresh, docs, cleanup, test-only | 1–2 sentences |
+| Bug fix, small feature, new flag, refactor | 2–3 sentences |
+| New agent, new data source, scoring change, or a strategy the diff cannot show | up to 3 short paragraphs |
+
+Break the body up at every length: at 2–3 sentences, one sentence per
+line; beyond that, paragraphs of two-three sentences with blank lines
+between. Then one editing pass — delete every sentence that only tells the
+reviewer something the diff or the title already tells them.
+
+### What to leave out
+
+- No "Test Plan"/"How to verify"/"Acceptance Criteria" sections
+- No "Changes" lists that duplicate the diff
+- No empty validation ("great improvement to the codebase")
+- No restating the title or narrating commits
+- No extra AI-attribution lines — remote Claude Code sessions append a
+  "Generated with Claude Code" footer automatically; that platform footer
+  stays, and nothing more gets added
+
+## Workflow
+
+### Step 1: Branch and push
+
+```bash
+BRANCH=$(git branch --show-current)   # never main
+git push -u origin "$BRANCH"
+```
+
+Target is always `main`. If the branch's previous PR was already merged,
+restart the branch from `origin/main` first and carry only unmerged
+commits.
+
+### Step 2: Gather the why
+
+If the branch or session references an issue, read it (`gh issue view N`,
+or the GitHub MCP `issue_read` tool) for motivation. `git log
+origin/main..HEAD --oneline` shows scope — use it to understand intent,
+never to write a commit list into the body.
+
+### Step 3: Write title and body
+
+Title per the rules above; body inside the length budget. Sanity-check the
+title against the lint regex:
+`^(feat|fix|refactor|perf|chore|docs|ci|test|style)(\([a-zA-Z0-9._/ -]+\))?!?: .+`
+
+### Step 4: Create the PR
+
+Local session:
+
+```bash
+gh pr create --title "<title>" --base main --body "$(cat <<'EOF'
+<body prose>
+EOF
+)"
+```
+
+Web/remote session: the GitHub MCP `create_pull_request` tool (load via
+ToolSearch) with the same title/body, `base: main`.
+
+Pass `--draft` (or `draft: true`) only if the user asked to open it as a
+draft to keep working on the branch.
+
+### Step 5: Report
+
+Print the PR URL. If the user asked for auto-merge, arm it (`gh pr merge
+--auto --squash`, or the MCP `enable_pr_auto_merge` tool) — it merges once
+the required `check` and `lint` checks pass.
+
+## Stacked PRs
+
+When this branch builds on another open PR, target that PR's branch
+instead of main and end the body with `Stacked on #N.` Sanity-check with
+`git log origin/<target>..HEAD --oneline` — only this PR's commits should
+appear. When the base PR squash-merges and its branch auto-deletes, GitHub
+retargets this PR to main and the diff inherits the base PR's commits:
+rebase onto main before review continues.
+
+## Common Mistakes
+
+- Issue number in the title (belongs in the body as `Closes #N`)
+- A changelog-visible title describing the implementation or the review
+  process instead of the user-facing change
+- Narrating the diff or padding the body to look thorough
+- Describing only what changed and never why — even a two-sentence body
+  carries the motivation
+- Bundling unrelated changes so no single title can describe the PR
+- Forgetting to push before creating the PR
+- Adding attribution lines beyond the automatic platform footer
+
+## Validation
+
+- The branch is pushed and the PR targets `main` (or a stacked base per
+  the rules above), created ready unless the user asked for a draft.
+- The title matches the lint regex, is ≤ 72 characters, carries no issue
+  ref, and — if changelog-visible — reads as the standalone user-facing
+  change.
+- The body is why-first first-person prose within its length budget: no
+  boilerplate headings, no diff narration, no empty validation, and no
+  sentence restating the title or the diff.
+- `Closes #N` appears when the PR resolves an issue; caveats and
+  verification gaps are in italics; any stats are plainly stated at the
+  end.
+- The PR URL was reported to the user.

{fplkit-2.0.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 -->
+<!-- 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
 
@@ -48,6 +48,9 @@ Extract:
 - `deadline` -- the transfer deadline timestamp
 - `phase` -- current status (e.g. "Fixture day 1 of 2", "Between gameweeks")
 - `metadata.format` -- `"classic"`, `"draft"`, or `"both"`. This determines which sub-agents to dispatch and which Phase B commands to run. If format is not present (no entry IDs configured), ask the user.
+- `metadata.season` -- the hyphenated season label (e.g. `"2026-27"`). Referred to below as `{season}`.
+
+**Every file this skill reads or writes lives under `[YOUR_OUTPUT_DIR]/{season}/`.** Report filenames carry the gameweek but no season, so a flat output directory lets 2026-27's GW21 file overwrite 2025-26's. Take `{season}` from this command rather than hardcoding it -- a hardcoded label silently rots at the July rollover, which is the failure this partition exists to prevent. `fpl` writes its own reports to the same season directory.
 
 ### A1.5 -- Chip Status
 
@@ -82,7 +85,7 @@ _Skip unless `mode == "squad-builder"` AND `active_chip ∈ {wildcard, freehit}`
 
 Locate a matching squad-builder output file and extract the Classic Squad block for embedding. Sets `squad_builder_result = "embed"` on success, or `"rederive"` with a `squad_builder_reason` code on failure. Resolving mode in Phase A (before Phase B) lets sub-agents know up-front which Phase B outputs will actually feed them, and prints the rederive warning banner before any data-gather commands run. All steps are synchronous and must complete before Phase B begins.
 
-1. Look for `[YOUR_OUTPUT_DIR]/gw{N}-squad-builder.md`.
+1. Look for `[YOUR_OUTPUT_DIR]/{season}/gw{N}-squad-builder.md`.
    - Not found → `squad_builder_result = "rederive"`, `squad_builder_reason = "file-missing"`. Done.
 2. Parse the file's YAML frontmatter. Required fields: `mode`, `gameweek`.
    - Missing or malformed → `squad_builder_result = "rederive"`, `squad_builder_reason = "frontmatter-malformed"`. Done.
@@ -103,7 +106,7 @@ Locate a matching squad-builder output file and extract the Classic Squad block
 5. Call the extraction helper:
 
    ```bash
-   python3 "${CLAUDE_SKILL_DIR}/scripts/extract_classic_squad.py" --file "[YOUR_OUTPUT_DIR]/gw{N}-squad-builder.md"
+   python3 "${CLAUDE_SKILL_DIR}/scripts/extract_classic_squad.py" --file "[YOUR_OUTPUT_DIR]/{season}/gw{N}-squad-builder.md"
    ```
 
    Parse stdout as JSON regardless of exit code. If JSON parse fails, treat as extraction-failed with a generic error message.
@@ -200,7 +203,60 @@ fpl stats -p DEF -s clean_sheets --min-minutes 450 -n 10 --available-only --form
 
 Store each result under a distinct key (e.g. `stats_form`, `stats_transfer_momentum`, `stats_mid_xgi`, `stats_fwd_xgi`, `stats_def_clean_sheets`) and inline them into Phase C prompts as labelled sections.
 
-<!-- ADAPT: Add your own supplementary data sources here. Examples:
+### B9 -- Season Preview Intel
+
+```bash
+fpl intel --format json
+```
+
+Hand-curated pre-season notes on minutes, injuries, role and set-piece duty. Optional: most setups
+have none, and every downstream step is unchanged when there is nothing to read.
+
+**This is an early-season source by design.** Each section expires at the point real data
+supersedes it -- projected XIs once actual minutes exist, everything eventually. Do not assume the
+schedule: the response's `metadata.decay_schedule` carries the live expiry table and
+`metadata.sections_live` what still counts at this gameweek. Once `sections_live` is empty, expect
+an empty payload -- that is the decay working, not a failure. Its value is concentrated in the
+opening gameweeks, when `starting_xi.py` and `bench_order.py` are ranking players who have not
+played yet.
+
+Read `metadata.coverage.usable_as` and store it as `intel_gate`:
+
+| `intel_gate` | What sub-agents may do with intel |
+|---|---|
+| `full` | Support **or** oppose a pick |
+| `negative_filter_only` | Only downgrade: injuries, rotation risk, "not nailed on". Never promote. |
+| `none` | Ignore entirely; omit the intel block from every Phase C prompt |
+
+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.
   - Newsletter extracts (e.g. community tips, model projections) saved as markdown files
@@ -252,7 +308,19 @@ Branch on `squad_builder_result` (set in Phase A3; unset on transfer weeks):
 > - Chip timing: {B6 output}
 > - Stats: {stats_form}, {stats_transfer_momentum}, {stats_mid_xgi}, {stats_fwd_xgi}, {stats_def_clean_sheets} (from B8)
 >
-> <!-- ADAPT: Add your own supplementary data sources here (newsletters, external reports) -->
+> - Preview intel: {intel} (from B9 - omit this line entirely when `intel_gate` is `none`)
+>   Gate: {intel_gate}. Governs **minutes and role only**, never how good a player is. Attribute it
+>   ("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):**
 >
@@ -262,11 +330,11 @@ Branch on `squad_builder_result` (set in Phase A3; unset on transfer weeks):
 >
 > Default: insert the embedded `### Classic Squad` block above **verbatim** as the Classic Squad section of the recommendations file. This is the expected path for nearly every embed-mode run.
 >
-> Late-changes path (use only when clearly warranted): if Phase B data reveals a material change squad-builder could not have seen (a starter ruled out after the file was written, an injury confirmed, a price move materially shifting affordability), you may apply a swap inline. To apply a swap: replace the relevant Starting XI or Bench row, update Captain/Vice if affected, adjust the Budget table (subtract OUT price, add IN price, update Total and Remaining) and Team Exposure table accordingly. Immediately after the block's `#### Alternatives` section, append a blockquote note: `> Late change: {OUT name} → {IN name} — {one-line reason, named source e.g. "ruled out per Thursday presser"}`. One note per swap. **Default is verbatim pass-through. Only deviate for a specific named reason. Never rewrite tables to "improve" formatting or fix perceived typos in squad-builder's output.**
+> Late-changes path (use only when clearly warranted): if Phase B data reveals a material change squad-builder could not have seen (a starter ruled out after the file was written, an injury confirmed, a price move materially shifting affordability), you may apply a swap inline. To apply a swap: replace the relevant Starting XI or Bench row, update Captain/Vice if affected, adjust the Budget table (subtract OUT price, add IN price, update Total and Remaining) and Team Exposure table accordingly. Immediately after the block's `#### Alternatives` section, append a blockquote note: `> Late change: {OUT name} → {IN name} — {one-line reason, named source e.g. "ruled out per Thursday presser"}`. One note per swap. **Default is verbatim pass-through. Only deviate for a specific named reason. Never rewrite tables to "improve" formatting or fix perceived typos in squad-builder's output, and never fold an annotation (formation, notes) into a heading line — if squad-builder wrote `#### Starting XI`, keep the heading exactly as `#### Starting XI`; the formation belongs only on the `**Formation:**` line beneath it.**
 >
 > 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.
 >
@@ -284,7 +352,7 @@ Branch on `squad_builder_result` (set in Phase A3; unset on transfer weeks):
 Before dispatching, print the in-chat warning (variant by `squad_builder_reason`):
 
 **Variant A** (`squad_builder_reason == "file-missing"`):
-> ⚠️ **Wildcard/Free Hit detected for GW{N}, but no squad-builder file was found.** Expected `gw{N}-squad-builder.md` in `[YOUR_OUTPUT_DIR]`. Re-derivation will run (weaker squad selection). To use squad-builder output, run `/squad-builder --{wildcard|freehit}` first, then re-run `/gw-prep`.
+> ⚠️ **Wildcard/Free Hit detected for GW{N}, but no squad-builder file was found.** Expected `gw{N}-squad-builder.md` in `[YOUR_OUTPUT_DIR]/{season}`. Re-derivation will run (weaker squad selection). To use squad-builder output, run `/squad-builder --{wildcard|freehit}` first, then re-run `/gw-prep`.
 
 **Variant B** (`squad_builder_reason ∈ {"gameweek-mismatch", "mode-mismatch"}`):
 > ⚠️ **Squad-builder file found but does not match this run.** Found `gw{N}-squad-builder.md` with `mode: {file.mode}` / `gameweek: {file.gameweek}`. Expected mode `{active_chip}` / gameweek `{N}`. Re-derivation will run. To use squad-builder output, run `/squad-builder --{wildcard|freehit}` for GW{N}, then re-run `/gw-prep`.
@@ -318,7 +386,19 @@ Proceed immediately (non-interactive).
 > - Chip timing: {B6 output}
 > - Stats: {stats_form}, {stats_transfer_momentum}, {stats_mid_xgi}, {stats_fwd_xgi}, {stats_def_clean_sheets} (from B8)
 >
-> <!-- ADAPT: Add your own supplementary data sources here (newsletters, external reports) -->
+> - Preview intel: {intel} (from B9 - omit this line entirely when `intel_gate` is `none`)
+>   Gate: {intel_gate}. Governs **minutes and role only**, never how good a player is. Attribute it
+>   ("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.
 >
@@ -350,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:**
 >
@@ -390,7 +476,19 @@ Proceed immediately (non-interactive).
 > - Chip timing: {B6 output}
 > - Stats: {stats_form}, {stats_transfer_momentum}, {stats_mid_xgi}, {stats_fwd_xgi}, {stats_def_clean_sheets} (from B8)
 >
-> <!-- ADAPT: Add your own supplementary data sources here (newsletters, external reports) -->
+> - Preview intel: {intel} (from B9 - omit this line entirely when `intel_gate` is `none`)
+>   Gate: {intel_gate}. Governs **minutes and role only**, never how good a player is. Attribute it
+>   ("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.
 
@@ -417,11 +515,50 @@ 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)
 >
-> <!-- ADAPT: Add your own supplementary data sources here (newsletters, external reports) -->
+> - Preview intel: {intel} (from B9 - omit this line entirely when `intel_gate` is `none`)
+>   Gate: {intel_gate}. Governs **minutes and role only**, never how good a player is. Attribute it
+>   ("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.
 >
@@ -435,7 +572,7 @@ After each sub-agent identifies OUT candidates and an IN shortlist (from squad a
 python3 "${CLAUDE_SKILL_DIR}/scripts/transfer_eval.py" --out "{out_player_name}" --in "{comma-separated IN candidate names}"
 ```
 
-The script outputs JSON with Outlook (multi-GW quality) and This GW (lineup impact) deltas for each IN candidate vs the OUT player. Use these scores as the quantitative baseline for transfer/waiver recommendations. Sub-agents may override with qualitative reasons (press conference intel, newsletter signals) using the same `⚡ Override: {reason}` pattern as starting XI overrides.
+The script outputs JSON with Outlook (multi-GW quality) and This GW (lineup impact) deltas for each IN candidate vs the OUT player. Use these scores as the quantitative baseline for transfer/waiver recommendations. Sub-agents may override with qualitative reasons (press conference intel, newsletter signals, season preview intel from B9) using the same `⚡ Override: {reason}` pattern as starting XI overrides. Name the source in the reason.
 
 If the script fails (exit 1), fall back to LLM-driven transfer reasoning and note the failure.
 
@@ -449,7 +586,9 @@ python3 "${CLAUDE_SKILL_DIR}/scripts/starting_xi.py" --squad "{comma-separated 1
 
 <!-- ADAPT: Replace with your squad player names from the squad grid output -->
 
-Use the script's recommended XI as the default lineup. Sub-agents may override specific picks with stated qualitative reasons (press conference intel, newsletter signals, rotation predictions). Mark any overrides with `⚡ Override: {reason}` in the output. If the script fails (exit 1), fall back to manual selection and note the failure.
+Use the script's recommended XI as the default lineup. Sub-agents may override specific picks with stated qualitative reasons (press conference intel, newsletter signals, rotation predictions, season preview intel from B9). Mark any overrides with `⚡ Override: {reason}` in the output, naming the source. If the script fails (exit 1), fall back to manual selection and note the failure.
+
+**Preview intel is at its most useful here in GW1-3**, when the lineup engine is ranking players with no minutes on the board and a projected XI is the only nailed-on signal available. It feeds this override channel deliberately rather than the scoring inside `starting_xi.py`: an override is visible and attributed in the output, whereas a scoring input would move picks invisibly. Respect `intel_gate` -- under `negative_filter_only`, intel may bench a player but never promote one into the XI.
 
 ### C4 -- Bench Ordering (skip if `squad_builder_result == "embed"` OR `mode == "benchboost"` — embed has bench order inside block, bench boost has no bench ordering)
 
@@ -467,8 +606,8 @@ Incorporate the bench ordering output into the relevant sections of each sub-age
 
 Combine the outputs from whichever sub-agents were dispatched into a single recommendations file. If only one format is active, the file contains only that format's section.
 
-<!-- ADAPT: Set your output directory -->
-**Output path:** `[YOUR_OUTPUT_DIR]/gw{N}-recommendations.md`
+<!-- ADAPT: Set your output directory. Keep the `/{season}/` segment -- it is what stops a new season overwriting the last one's reports. -->
+**Output path:** `[YOUR_OUTPUT_DIR]/{season}/gw{N}-recommendations.md`
 
 The file should follow the structure defined in `references/output-template.md`, with both Classic and Draft sections populated.
 
@@ -492,7 +631,7 @@ _Runs after Phase D file write, before Phase E. Not embed-gated._
 
    ```bash
    cd "$FPL_CLI_DIR" && source .venv/bin/activate && python "$FPL_CLI_DIR/.agents/skills/gw-prep/scripts/validate_draft_waivers.py" \
-     --recommendations-file "[YOUR_OUTPUT_DIR]/gw{N}-recommendations.md" \
+     --recommendations-file "[YOUR_OUTPUT_DIR]/{season}/gw{N}-recommendations.md" \
      --waivers-json /tmp/gw-prep-waivers-{N}.json \
      --squad-grid-json /tmp/gw-prep-squad-grid-{N}.json
    ```
@@ -537,7 +676,7 @@ _Skip unless `squad_builder_result == "embed"`. Transfer and rederive runs do no
 1. Run:
 
    ```bash
-   python3 "${CLAUDE_SKILL_DIR}/scripts/extract_classic_squad.py" --from-recommendations --file "[YOUR_OUTPUT_DIR]/gw{N}-recommendations.md"
+   python3 "${CLAUDE_SKILL_DIR}/scripts/extract_classic_squad.py" --from-recommendations --file "[YOUR_OUTPUT_DIR]/{season}/gw{N}-recommendations.md"
    ```
 
    Parse stdout as JSON regardless of exit code. If exit is non-zero → emit warning and proceed: