fplkit 2.0.0__tar.gz → 2.1.0__tar.gz

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

@@ -25,19 +25,20 @@ Errors use `emit_json_error()` with `{"command", "error"}` shape.
 | 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 | Yes | General | No | direct-api |
+| `status` | Show FPL gameweek status and upcoming deadlines. JSON `metadata` carries `gameweek`, `format` and `season` (hyphenated label, e.g. `2026-27`) - `season` is the directory segment skills must use when writing alongside fpl-cli's own reports | 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 |
 | `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); 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 |
+| `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 |
-| `preview` | Run full pre-gameweek analysis and generate report | No | General | No | via-agent |
-| `review` | Review a completed gameweek - squad performance and standings | No | General | No | via-agent |
-| `league-recap` | Recap a completed gameweek - awards, standings, and banter | No | General | No | via-agent |
+| `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 |
@@ -54,24 +55,37 @@ Errors use `emit_json_error()` with `{"command", "error"}` shape.
 | `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 |
+| `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
+- **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 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 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) | 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
 
@@ -94,4 +108,6 @@ 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/`
 - 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 B9 + Phase E. JSON stdout; read-only; emits TypedDict-annotated payloads.
+- `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.
+- `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/.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.1.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 -->
 
 # 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,35 @@ 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.
+
+<!-- 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 +283,12 @@ 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.
+>
+> <!-- 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,7 +298,7 @@ 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.
 >
@@ -284,7 +320,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 +354,12 @@ 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.
+>
+> <!-- 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.
 >
@@ -390,7 +431,12 @@ 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.
+>
+> <!-- ADAPT: Add your own further supplementary data sources here (newsletters, external reports) -->
 >
 > Produce the **Classic** section of the output template.
 
@@ -421,7 +467,12 @@ Proceed immediately (non-interactive).
 > - 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.
+>
+> <!-- 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 +486,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 +500,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 +520,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 +545,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 +590,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:

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

@@ -2,16 +2,20 @@
 
 Template structure for the gameweek recommendations file.
 
-**Output path:** `[YOUR_OUTPUT_DIR]/gw{N}-recommendations.md`
+**Output path:** `[YOUR_OUTPUT_DIR]/{season}/gw{N}-recommendations.md`
+
+`{season}` is the hyphenated season label from `fpl status --format json` (`metadata.season`). The filename carries the gameweek but no season, so the directory segment is what stops a new season's GW21 file overwriting the previous season's.
 
 ---
 
 ## File Structure
 
-**Frontmatter fields** added at the top of the output file. `squad_builder_mode` is load-bearing for `/update-gw-prep`'s Phase C detection rule ("if `squad_builder_mode: true`, switch to squad-builder output format") — omit it on non-embed-mode runs to preserve that detection. `mode` is a forward-compat machine-readable enum for future consumers; always written.
+**Frontmatter fields** added at the top of the output file. `squad_builder_mode` is load-bearing for `/update-gw-prep`'s Phase C detection rule ("if `squad_builder_mode: true`, switch to squad-builder output format") — omit it on non-embed-mode runs to preserve that detection. `mode` is a forward-compat machine-readable enum for future consumers; always written. `season` and `gameweek` let a reader confirm which season's file it opened without inferring it from the path.
 
 ```markdown
 ---
+season: {season}  # Always present. Hyphenated label from `fpl status --format json` (metadata.season).
+gameweek: {N}     # Always present. Together with season this identifies the file independently of its path.
 squad_builder_mode: true  # Only on embed-mode wildcard/freehit runs. Omit on rederive or transfer runs.
 mode: wildcard | freehit | benchboost | transfer  # Always present. Enum value matches the active chip or "transfer".
 phase_e_ok: true | false  # Embed-mode only. Written by Phase E after post-write validation. Omit on transfer and rederive runs.
@@ -163,12 +167,12 @@ Any additional context, caveats, or follow-up actions.
 
 ## Fallback Banners (Wildcard/Free Hit re-derivation)
 
-When Phase B9 detects a wildcard/freehit week but cannot use the squad-builder file (`squad_builder_result == "rederive"`), prepend the appropriate banner on the line immediately before the Classic section heading in the output file. Choose the variant matching `squad_builder_reason`.
+When Phase A3 detects a wildcard/freehit week but cannot use the squad-builder file (`squad_builder_result == "rederive"`), prepend the appropriate banner on the line immediately before the Classic section heading in the output file. Choose the variant matching `squad_builder_reason`.
 
 `Season Start Classic`, `Season Start Draft`, and `Re-draft` mode files correctly land in Variant B's mode-mismatch branch by design — those modes cannot match an active wildcard/freehit chip.
 
 **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 has run (weaker squad selection). To use squad-builder output next time, 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 has run (weaker squad selection). To use squad-builder output next time, 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 has run. To use squad-builder output, run `/squad-builder --{wildcard|freehit}` for GW{N}, then re-run `/gw-prep`.

fplkit-2.1.0/.agents/skills/gw-prep/scripts/_bootstrap.py

@@ -0,0 +1,25 @@
+"""Shared startup for gw-prep scripts that import fpl-cli agents directly."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from fpl_cli.paths import UserDirError, ensure_legacy_migration, load_env_files
+
+
+def bootstrap_user_dirs() -> None:
+    """Run fpl-cli's legacy-file migration before any agent resolves paths.
+
+    The CLI does this in its own entry point; scripts importing agents
+    directly must do it themselves or a user with files in the legacy
+    repo-root dirs silently gets empty settings and regenerated ratings.
+    A bad FPL_CLI_* override surfaces here as a clean JSON error instead
+    of a traceback mid-agent.
+    """
+    try:
+        load_env_files()
+        ensure_legacy_migration()
+    except UserDirError as exc:
+        json.dump({"error": True, "messages": [str(exc)]}, sys.stdout, indent=2)
+        sys.exit(1)

{fplkit-2.0.0 → fplkit-2.1.0}/.agents/skills/gw-prep/scripts/bench_order.py

@@ -15,6 +15,8 @@ import asyncio
 import json
 import sys
 
+from _bootstrap import bootstrap_user_dirs
+
 from fpl_cli.agents.analysis.bench_order import BenchOrderAgent
 from fpl_cli.api.fpl import FPLClient
 from fpl_cli.models.player import resolve_player
@@ -62,6 +64,7 @@ async def _run(starting_names: list[str], bench_names: list[str]) -> None:
 
 
 def main() -> None:
+    bootstrap_user_dirs()
     parser = argparse.ArgumentParser(description="Bench order analysis")
     parser.add_argument(
         "--starting", required=True,