fplkit 1.0.0__tar.gz

fplkit-1.0.0/.agents/README.md

@@ -0,0 +1,26 @@
+# .agents/
+
+Agent skills for fpl-cli. Each subdirectory in `skills/` is a self-contained skill with a `SKILL.md` entry point.
+
+## Discovery
+
+Claude Code discovers skills via the `.claude/skills/` symlink, which points here. Other agent tools can read `skills/` directly.
+
+For a complete inventory of CLI commands, analysis agents, and skills, see [TOOLS.md](TOOLS.md).
+
+## Adapting Skills
+
+Skills are showcase examples - they work out of the box but are designed to be customised:
+
+- `<!-- ADAPT: ... -->` comments mark sections you'll want to change for your setup
+- Output paths use `[YOUR_OUTPUT_DIR]` placeholders - replace with your preferred location
+- Supplementary data sources (newsletters, external reports) are noted but not required
+- All CLI data gathering uses `--format json` for structured output
+
+## Private Skills
+
+To add a private skill that shouldn't be committed, create it under `skills/` and add the path to `.gitignore`:
+
+```
+.agents/skills/my-private-skill/
+```

fplkit-1.0.0/.agents/TOOLS.md

@@ -0,0 +1,96 @@
+# 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 | 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 | Yes | General | No | direct-api |
+| `stats` | List players with filtering and sorting | 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 |
+| `captain` | Analyse and rank captain options for next gameweek | Yes | Classic | Yes | via-agent |
+| `differentials` | Find differential picks - high potential, low ownership | Yes | Classic | Yes | via-agent |
+| `targets` | Find transfer targets - high performers across all ownership | Yes | Classic | Yes | via-agent |
+| `transfer-eval` | Compare transfer OUT player against IN candidates | Yes | General | Yes | via-agent |
+| `allocate` | Select mathematically optimal 15-player squad within budget | Yes | Classic | Yes | direct-api |
+| `waivers` | Show waiver recommendations for your draft league | Yes | Draft | Yes | via-agent |
+| `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 | No | General | Yes | 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
+- **Pattern** - `direct-api` (API client only), `via-agent` (uses analysis agent), `mixed` (both patterns in subcommands)
+
+## Skills
+
+Agent playbooks in `.agents/skills/`. Each has a `SKILL.md` entry point. Claude Code discovers them via the `.claude/skills/` symlink.
+
+| Skill | Path | Purpose | Compatibility |
+|-------|------|---------|--------------|
+| gw-prep | `skills/gw-prep/` | Gameweek preparation recommendations for classic and draft | 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 |
+
+## 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/`
+- TransferEvalAgent is used by both `transfer-eval` CLI command and gw-prep skill

fplkit-1.0.0/.agents/skills/gw-prep/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: gw-prep
+description: >
+  Generate gameweek preparation recommendations for FPL classic and draft leagues.
+  Runs data gathering via fpl-cli, then dispatches parallel sub-agent analysis for
+  each league format. Use when the user asks to prepare for the next gameweek,
+  get transfer/waiver recommendations, or review their squad.
+model: opus
+compatibility:
+  claude-code: full (parallel Classic + Draft sub-agents via Agent tool)
+  codex: partial (sequential execution - no sub-agent spawning)
+  cursor: partial (sequential execution)
+  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 -->
+
+# Gameweek Preparation
+
+Generate transfer/waiver recommendations and squad analysis for the upcoming FPL gameweek across classic and draft formats.
+
+## Environment
+
+```bash
+cd "$FPL_CLI_DIR" && source .venv/bin/activate
+```
+
+## Execution Strategy
+
+**Claude Code:** Launch Phase C sub-agents in parallel (classic + draft simultaneously) using the `Agent tool parameters:` blocks shown in Phase C.
+
+**Codex / Cursor / Copilot / other agents:** Do not attempt to spawn sub-agents. Run Phase C-classic then Phase C-draft sequentially in the same context. Use the same prompts and output templates - just one after the other.
+
+**In all cases** the final output format is identical: Classic section followed by Draft section (or whichever formats are active).
+
+---
+
+## Phase A: Context Detection
+
+### A1 -- Gameweek and Deadline
+
+```bash
+fpl status --format json
+```
+
+Extract:
+- `gameweek` -- the upcoming GW number (N)
+- `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.
+
+### A1.5 -- Chip Status
+
+```bash
+fpl chips sync
+fpl chips --format json
+```
+
+`chips sync` ensures the local chip plan reflects any changes made via the FPL website. Run it silently before reading chip status.
+
+Extract active chip status. If **Wildcard** or **Free Hit** is active for GW N:
+- Set `mode = "squad-builder"` (full squad selection, not incremental transfers)
+- Otherwise `mode = "transfer"` (normal incremental recommendations)
+
+This mode switch affects which rules apply in Phase C sub-agents.
+
+### A2 -- Budget Data (classic only - skip if format is "draft")
+
+```bash
+fpl squad sell-prices --refresh
+```
+
+Scrapes current sell prices from the FPL website. Requires `FPL_EMAIL` and `FPL_PASSWORD` in `.env`. If credentials are not configured, skip this step - affordability analysis in Phase C will be limited to the data available from other commands.
+
+<!-- ADAPT: If you don't use FPL website credentials, remove this step -->
+
+---
+
+## Phase B: Data Gathering
+
+Run all applicable commands below. Every command uses `--format json`. Skip commands marked with a format condition that doesn't match `metadata.format` from A1.
+
+### B1 -- Fixture Difficulty
+
+```bash
+fpl fdr --format json
+```
+
+Returns fixture difficulty runs (pFDR, positional ATK/DEF ratings, upcoming fixtures) plus BGW/DGW predictions with confidence levels.
+
+### B2 -- Captain Candidates (classic only - skip if format is "draft")
+
+```bash
+fpl captain --format json
+```
+
+### B3 -- Waiver Targets (draft only - skip if format is "classic")
+
+```bash
+fpl waivers --format json
+```
+
+### B4 -- Current Squad
+
+```bash
+fpl squad grid --format json
+```
+
+If format is `"both"`, also run:
+
+```bash
+fpl squad grid --draft --format json
+```
+
+### B5 -- Price Movements
+
+```bash
+fpl price-history --format json
+```
+
+### B6 -- Chip Timing Analysis (classic only - skip if format is "draft")
+
+```bash
+fpl chips timing --format json
+```
+
+### B7 -- Player Detail (on-demand)
+
+For deeper analysis of specific players flagged by other commands:
+
+```bash
+fpl player "{player_name}" --format json
+```
+
+### B8 -- Statistical Leaders
+
+```bash
+fpl stats --format json
+```
+
+<!-- ADAPT: Add your own 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
+-->
+
+---
+
+## Phase C: Analysis Sub-agents
+
+Dispatch sub-agents based on `metadata.format` from A1:
+- `"classic"` -- dispatch C1 only
+- `"draft"` -- dispatch C2 only
+- `"both"` -- dispatch C1 and C2 in parallel (or sequentially if parallel is unsupported)
+
+Each sub-agent receives the JSON output from Phase B commands as context.
+
+### C1 -- Classic League Analysis (skip if format is "draft")
+
+- **model**: opus
+- **subagent_type**: general-purpose
+
+**Prompt structure:**
+
+> You are an FPL analyst preparing gameweek {N} recommendations for a classic league.
+>
+> **Mode: {mode}** (transfer | squad-builder)
+>
+> Refer to `references/rules.md` for analysis rules and `references/output-template.md` for the output format.
+>
+> **Data (JSON):**
+> - Status: {A1 output}
+> - Chips: {A1.5 output}
+> - pFDR: {B1 output}
+> - Captain candidates: {B2 output}
+> - Squad: {B4 output}
+> - Price movements: {B5 output}
+> - Chip timing: {B6 output}
+> - Stats leaders: {B8 output}
+>
+> <!-- ADAPT: Add your own supplementary data sources here (newsletters, external reports) -->
+>
+> If mode is `squad-builder`, apply squad-builder rules from `references/rules.md` instead of transfer rules.
+>
+> Produce the **Classic** section of the output template.
+
+### C2 -- Draft League Analysis (skip if format is "classic")
+
+- **model**: sonnet
+- **subagent_type**: general-purpose
+
+**Prompt structure:**
+
+> You are an FPL analyst preparing gameweek {N} recommendations for a draft league.
+>
+> Refer to `references/rules.md` for analysis rules and `references/output-template.md` for the output format.
+>
+> **Data (JSON):**
+> - Status: {A1 output}
+> - pFDR: {B1 output}
+> - Waivers: {B3 output}
+> - Squad: {B4 output}
+> - Stats leaders: {B8 output}
+>
+> <!-- ADAPT: Add your own supplementary data sources here (newsletters, external reports) -->
+>
+> Produce the **Draft** section of the output template.
+
+### C2.5 -- Transfer/Waiver Evaluation
+
+After each sub-agent identifies OUT candidates and an IN shortlist (from squad analysis, `fpl targets`, `fpl waivers`), run the transfer evaluation script for each OUT/shortlist pair:
+
+```bash
+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.
+
+If the script fails (exit 1), fall back to LLM-driven transfer reasoning and note the failure.
+
+### C3 -- Starting XI Selection
+
+Run the lineup engine for each active format's squad **before** bench ordering:
+
+```bash
+python3 "${CLAUDE_SKILL_DIR}/scripts/starting_xi.py" --squad "{comma-separated 15 squad player names from squad grid}"
+```
+
+<!-- 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.
+
+### C4 -- Bench Ordering
+
+Using the starting XI from C3 (or the sub-agent's overridden version), run the bench order script:
+
+```bash
+python3 "${CLAUDE_SKILL_DIR}/scripts/bench_order.py" --starting "{comma-separated starter names}" --bench "{comma-separated bench names}"
+```
+
+Incorporate the bench ordering output into the relevant sections of each sub-agent's recommendations.
+
+---
+
+## Phase D: Output
+
+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`
+
+The file should follow the structure defined in `references/output-template.md`, with both Classic and Draft sections populated.
+
+Present a brief summary to the user:
+- GW number and deadline
+- Mode (transfer or squad-builder)
+- Key highlights (top captain pick, priority transfer/waiver, chip timing note)
+- Output file path

fplkit-1.0.0/.agents/skills/gw-prep/references/output-template.md

@@ -0,0 +1,161 @@
+# GW-Prep Output Template
+
+Template structure for the gameweek recommendations file.
+
+**Output path:** `[YOUR_OUTPUT_DIR]/gw{N}-recommendations.md`
+
+---
+
+## File Structure
+
+```markdown
+# Gameweek {N} Recommendations
+
+**Deadline:** {deadline}
+**Mode:** {transfer | squad-builder}
+**Generated:** {timestamp}
+
+---
+
+## Classic League
+
+### Chip Timing
+
+Summary of chip timing analysis. Note if any chip is recommended for this GW or upcoming GWs, with rationale.
+
+### Captain Pick
+
+| Rank | Player | Team | Opponent (pFDR) | Key Stat | Rationale |
+|------|--------|------|-----------------|----------|-----------|
+| 1 | | | | | |
+| 2 | | | | | |
+| 3 | | | | | |
+
+**Recommended captain:** {player} -- {one-line rationale}
+
+### Transfer Recommendations
+
+_If mode is `squad-builder`, replace this section with Squad Builder below._
+
+| Priority | Out | In | Outlook | This GW | Net Cost | Rationale |
+|----------|-----|----|---------|---------|----------|-----------|
+| 1 | | | | | | |
+| 2 | | | | | | |
+| 3 | | | | | | |
+
+Outlook = multi-GW quality delta (target score). This GW = lineup impact delta. Both from `transfer_eval.py`.
+
+**Total hits:** {0 or -4/-8} | **Net expected gain:** {points}
+
+For each transfer, include:
+- Upcoming fixtures (next 3 GWs)
+- Form summary
+- Price trend
+
+### Squad Builder (Wildcard/Free Hit only)
+
+_Replace Transfer Recommendations when mode is `squad-builder`._
+
+**Budget:** {available} | **Formation:** {primary} / {secondary}
+
+#### Recommended XV
+
+| Pos | Player | Team | Price | Next 3 Fixtures | Rationale |
+|-----|--------|------|-------|-----------------|-----------|
+| GK | | | | | |
+| GK | | | | | |
+| DEF | | | | | |
+| DEF | | | | | |
+| DEF | | | | | |
+| DEF | | | | | |
+| DEF | | | | | |
+| MID | | | | | |
+| MID | | | | | |
+| MID | | | | | |
+| MID | | | | | |
+| MID | | | | | |
+| FWD | | | | | |
+| FWD | | | | | |
+| FWD | | | | | |
+
+**Total cost:** {total} | **Remaining budget:** {remaining}
+
+### Bench Order
+
+BenchOrderAgent recommended order:
+
+| Bench Slot | Player | Score | Rationale |
+|------------|--------|-------|-----------|
+| GK | | | |
+| 1st sub | | | |
+| 2nd sub | | | |
+| 3rd sub | | | |
+
+Coverage notes (sole-coverage positions, rotation risks).
+
+### Momentum Alerts
+
+- **Hot streaks:** {players}
+- **Cold streaks:** {players}
+- **Minutes risks:** {players}
+- **Price alerts:** {players}
+
+### pFDR Overview
+
+Best and worst fixture runs by position for the next 5 GWs.
+Cross-referenced against current squad holdings.
+
+---
+
+## Draft League
+
+### Waiver Recommendations
+
+| Priority | Drop | Claim | Position | Outlook | This GW | Fixture Run | Rationale |
+|----------|------|-------|----------|---------|---------|-------------|-----------|
+| 1 | | | | | | | |
+| 2 | | | | | | | |
+| 3 | | | | | | | |
+| 4 | | | | | | | |
+| 5 | | | | | | | |
+
+Outlook = multi-GW quality delta (target score). This GW = lineup impact delta. Both from `transfer_eval.py`.
+
+### Starting XI
+
+Recommended lineup with formation (via lineup engine).
+
+| Pos | Player | Score | Opponent (pFDR) | Form | Rationale |
+|-----|--------|-------|----------------|------|-----------|
+| GK | | | | | |
+| DEF | | | | | |
+| DEF | | | | | |
+| ... | | | | | |
+
+Score = lineup engine score (0-100). If a player was overridden into/out of the XI, append: `⚡ Override: {reason}`
+
+**Formation:** {e.g. 3-4-3}
+
+### Bench Order
+
+BenchOrderAgent recommended order:
+
+| Bench Slot | Player | Score | Rationale |
+|------------|--------|-------|-----------|
+| GK | | | |
+| 1st sub | | | |
+| 2nd sub | | | |
+| 3rd sub | | | |
+
+### Momentum Alerts
+
+- **Hot streaks:** {players}
+- **Cold streaks:** {players}
+- **Minutes risks:** {players}
+
+---
+
+## Notes
+
+Any additional context, caveats, or follow-up actions.
+```

fplkit-1.0.0/.agents/skills/gw-prep/references/rules.md

@@ -0,0 +1,137 @@
+# GW-Prep Analysis Rules
+
+Rules governing how sub-agents should analyse data and produce recommendations.
+
+---
+
+## Transfer Recommendations (Classic -- Transfer Mode)
+
+When `mode = "transfer"`:
+
+1. **Prioritise by horizon** -- rank transfers by expected point gain over the next 3 gameweeks, not just the immediate fixture.
+2. **FDR weighting** -- weight upcoming fixture difficulty using the pFDR data. Players facing a run of low-pFDR fixtures (2-3 range) are preferred over those with a single good fixture followed by hard ones.
+3. **Form vs fixtures** -- blend recent form (last 4 GW points, minutes) with fixture difficulty. A player in strong form facing medium fixtures can outperform a cold player facing easy ones.
+4. **Price trajectory** -- flag players whose price is rising (buy pressure) or falling (sell pressure). Prioritise transfers that protect squad value.
+5. **Maximum 3 transfer suggestions** -- rank by priority. For each transfer, state: player out, player in, rationale, net cost, and expected point swing.
+6. **Hit threshold** -- only recommend a points hit (-4) if the expected gain across the planning horizon exceeds 8 points.
+
+## Squad-Builder Rules (Classic -- Wildcard/Free Hit Mode)
+
+When `mode = "squad-builder"`:
+
+1. **Full squad optimisation** -- evaluate all 15 slots, not incremental changes.
+2. **Budget constraint** -- the total squad must fit within the available budget (selling price of current squad + bank).
+3. **Formation flexibility** -- build a squad that supports at least two viable formations (e.g. 3-4-3 and 4-4-2).
+4. **Fixture spread** -- avoid more than 3 players from a single team. Distribute across favourable fixture runs.
+5. **Captaincy ceiling** -- ensure at least 2 premium captaincy options with high expected output over the chip horizon.
+6. **Bench playability** -- bench players should have a realistic chance of returning points (avoid £4.0m non-players).
+
+## Waiver Recommendations (Draft)
+
+1. **Waiver priority order** -- rank targets by expected impact. The top waiver claim should be the highest-confidence improvement.
+2. **Positional need** -- prioritise positions where the current squad is weakest (fewest viable starters, worst upcoming fixtures).
+3. **Availability likelihood** -- consider whether high-value targets are likely to be claimed by opponents with higher waiver priority.
+4. **Fixture run** -- as with classic, weight the next 3 gameweeks of fixtures rather than just the immediate one.
+5. **Maximum 5 waiver suggestions** -- for each: player to drop, player to claim, positional context, and fixture rationale.
+
+## Transfer/Waiver Evaluation Script
+
+The `transfer_eval.py` script provides quantitative **Outlook** (multi-GW quality, target score 0-100) and **This GW** (lineup impact, lineup score 0-100) deltas for each IN candidate vs the OUT player. Use these as the baseline for transfer and waiver recommendations.
+
+- **Positive Outlook delta:** the IN candidate is a better long-term hold
+- **Positive This GW delta:** the IN candidate is a better starter this week
+- **Override only with stated qualitative reasons** (press conference intel, newsletter signals, rotation predictions)
+- All existing transfer rules still apply (hit threshold > 8pts, max 3 suggestions, 3-GW horizon priority, affordability check)
+
+## Blended Analysis
+
+For all formats:
+
+1. **Recent form** -- last 4 GW average points, minutes played (flag rotation risks below 60 mins average).
+2. **Expected stats** -- where available, prefer xG/xA-based analysis over raw goals/assists. Flag players significantly over- or under-performing their expected stats.
+3. **Set-piece involvement** -- note players on corners, free kicks, and penalties as these provide floor-raising opportunities.
+4. **Injury/suspension flags** -- check player availability. Never recommend a player flagged as injured or suspended without explicitly noting the risk.
+
+## Momentum Alerts
+
+Flag the following situations prominently:
+
+- **Hot streak**: 3+ consecutive GWs returning 6+ points
+- **Cold streak**: 3+ consecutive GWs returning 2 or fewer points
+- **Minutes risk**: started fewer than 2 of last 4 matches
+- **Price crash**: lost 0.2+ in value over the last 5 days
+
+## pFDR (Positional FDR) Analysis
+
+For each position (GK, DEF, MID, FWD):
+
+1. Identify the 3 best fixture runs over the next 5 GWs (lowest average pFDR).
+2. Identify the 3 worst fixture runs (highest average pFDR).
+3. Cross-reference with the user's current squad to surface mismatches (e.g. holding defenders with terrible upcoming fixtures).
+
+## Selection Requirements
+
+Every recommendation must include:
+
+- **Player name and team**
+- **Position**
+- **Upcoming fixtures** (next 3 GWs with opponent and pFDR)
+- **Key stat** (the single most compelling number supporting the recommendation)
+- **Risk factor** (the primary reason the recommendation could go wrong)
+
+For starting XI selection:
+- **11 players exactly:** 1 GK + 10 outfield
+- **Valid formations:** 3-4-3, 3-5-2, 4-3-3, 4-4-2, 4-5-1, 5-3-2, 5-4-1
+- **Positions are fixed:** Each player's Pos must match their actual position. Never reassign a player to fit a formation.
+- **Bench:** 4 players for both Classic and Draft
+- **Bench ordering:** Must use the bench-order script output. Do not manually order bench players.
+
+## Team Exposure Management
+
+When making selection decisions, account for team stacking and use pFDR:
+
+**High-risk scenarios (consider benching one):**
+- 2+ attackers from a team with ATK pFDR 5+
+- 2+ defenders from a team with DEF pFDR 5+
+- 2+ players from a team facing a blank GW
+- 3 players from any team in an away fixture
+
+**Low-risk/opportunity scenarios:**
+- Double-up attackers on team with ATK pFDR 1-2
+- Double-up defenders on team with DEF pFDR 1-2
+- Triple-up in a DGW (returns spread across both games)
+
+In squad-builder mode, hard-cap at 3 players per team unless there is an exceptional fixture/form case (state it explicitly).
+
+<!-- ADAPT: Adjust exposure thresholds based on your league's scoring system -->
+
+## Lineup Engine Overrides
+
+The starting XI is determined by the lineup engine (`starting_xi.py`). Override only when you have qualitative information the engine cannot access:
+- Press conference intel (confirmed fit/injured/rested)
+- Newsletter rotation predictions
+- Injury updates not yet reflected in FPL data
+
+**Rules:**
+- State the reason for every override
+- Mark overrides with `⚡ Override: {reason}` in the Selection table
+- Do not override based on vague preference - the engine accounts for form, fixtures, availability, and team exposure
+- If you override more than 2 players, reconsider whether the engine input (squad grid) was correct
+
+<!-- ADAPT: Adjust override rules based on your data sources and confidence level -->
+
+## Affordability Analysis
+
+If budget data is available (e.g. from `fpl squad sell-prices`), verify affordability for every classic transfer recommendation. Flag any transfer that requires selling another player to fund it.
+
+<!-- ADAPT: Add your own supplementary data sources or rules here -->
+
+## Troubleshooting
+
+Common issues when running analysis:
+
+- **Stale data**: If CLI output looks outdated, re-run `fpl status --format json` to confirm the current GW.
+- **Missing players**: If a recommended player does not appear in stats output, use `fpl player "{name}" --format json` for direct lookup.
+- **Budget discrepancies**: Cross-check squad sell prices against available budget if transfers seem unaffordable.
+
+<!-- ADAPT: Add project-specific troubleshooting notes here -->