fplkit 1.0.0__tar.gz → 1.2.0__tar.gz

{fplkit-1.0.0 → fplkit-1.2.0}/.agents/TOOLS.md

@@ -27,8 +27,8 @@ Errors use `emit_json_error()` with `{"command", "error"}` shape.
 | `init` | Set up fpl-cli with your FPL IDs and optional features | No | General | No | direct-api |
 | `status` | Show FPL gameweek status and upcoming deadlines | 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 |
+| `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); panel shows `xPts` (ep_next). `--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 | 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 |
@@ -38,10 +38,10 @@ Errors use `emit_json_error()` with `{"command", "error"}` shape.
 | `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 |
+| `captain` | Analyse and rank captain options for next gameweek. JSON candidates include `adjusted_npxg_per_90` and `raw_npxg_per_90` when fixture adjustment is active. Consistency tiebreaker (CV-xGI percentile) phased in GW6-10 | Yes | Classic | Yes | via-agent |
+| `differentials` | Find differential picks - high potential, low ownership. Inverted consistency bonus (volatile players score higher, phased in GW6-10) | Yes | Classic | Yes | via-agent |
+| `targets` | Find transfer targets - high performers across all ownership. Consistency bonus (CV-xGI percentile, phased in GW6-10) | Yes | Classic | Yes | via-agent |
+| `transfer-eval` | Compare transfer OUT player against IN candidates. JSON includes `adjusted_npxg_per_90` and `raw_npxg_per_90` per player when fixture adjustment is active | Yes | General | Yes | via-agent |
 | `allocate` | Select mathematically optimal 15-player squad within budget | Yes | Classic | Yes | direct-api |
 | `waivers` | Show waiver recommendations for your draft league | Yes | Draft | Yes | via-agent |
 | `squad` | Analyse your FPL squad health and fixtures | Yes | General | No | via-agent |

{fplkit-1.0.0 → fplkit-1.2.0}/.agents/skills/squad-builder/SKILL.md

@@ -119,10 +119,10 @@ Issue all reads and CLI commands in a **single parallel tool-call block**:
 - `fpl stats -p FWD -s form --min-minutes 450 -n 15 --available-only --format json`
 - `fpl stats -p DEF -s total_points --min-minutes 450 -n 15 --available-only --format json`
 - `fpl stats -p GK -s points_per_game --min-minutes 450 -n 8 --available-only --format json`
-- `fpl stats --value -p MID -s value_score --min-minutes 450 -n 15 --available-only --format json` (underpriced mids by underlying performance per £m)
-- `fpl stats --value -p FWD -s value_score --min-minutes 450 -n 15 --available-only --format json`
-- `fpl stats --value -p DEF -s value_score --min-minutes 450 -n 15 --available-only --format json`
-- `fpl stats --value -p GK -s value_score --min-minutes 450 -n 8 --available-only --format json`
+- `fpl stats --value -p MID -s quality_per_m --min-minutes 450 -n 15 --available-only --format json` (underpriced mids by underlying performance per £m)
+- `fpl stats --value -p FWD -s quality_per_m --min-minutes 450 -n 15 --available-only --format json`
+- `fpl stats --value -p DEF -s quality_per_m --min-minutes 450 -n 15 --available-only --format json`
+- `fpl stats --value -p GK -s quality_per_m --min-minutes 450 -n 8 --available-only --format json`
 - `fpl stats -s now_cost -r --min-minutes 450 -n 15 --available-only --format json` (cheapest playing options)
 - `fpl stats -s form --min-minutes 315 -n 20 --available-only --format json` (in-form across positions)
 - `fpl stats -s transfers_in_event -n 15 --format json` (transfer momentum)
@@ -144,7 +144,7 @@ Skip missing optional sources gracefully. Store all results for Phase B2.
 ## Phase B2: Candidate Shortlisting (orchestrator, inline)
 No sub-agent needed. The orchestrator already has all Phase B JSON. Extract candidate lists per position:
 
-1. Parse the 4 positional `fpl stats` outputs (MID/FWD/DEF/GK) + 4 `value_score` outputs + form + cheapest
+1. Parse the 4 positional `fpl stats` outputs (MID/FWD/DEF/GK) + 4 `quality_per_m` outputs + form + cheapest
 2. Deduplicate players appearing in multiple lists
 3. Add any player names from scout reports / previews not already in stats
 4. Note which players appear in the `fpl allocate` solver output (JSON field is `web_name`, not `name`)
@@ -152,10 +152,10 @@ No sub-agent needed. The orchestrator already has all Phase B JSON. Extract cand
 
 | Position | Target candidates | Primary stats sources |
 |----------|------------------|-----------------------|
-| GK | 4-6 | GK ppg, GK value_score |
-| DEF | 8-10 | DEF total_points, DEF value_score, cheapest |
-| MID | 8-10 | MID xGI, MID value_score, form, transfers_in |
-| FWD | 6-8 | FWD form, FWD value_score, cheapest |
+| GK | 4-6 | GK ppg, GK quality_per_m |
+| DEF | 8-10 | DEF total_points, DEF quality_per_m, cheapest |
+| MID | 8-10 | MID xGI, MID quality_per_m, form, transfers_in |
+| FWD | 6-8 | FWD form, FWD quality_per_m, cheapest |
 
 Each candidate entry: `{name, team, position, in_allocator_squad: bool}`.
 
@@ -177,10 +177,10 @@ Agent tool parameters (per agent):
 
 | Agent | Stats sources | pFDR column | Allocator picks |
 |-------|--------------|------------|-----------------|
-| GK | GK ppg, GK value_score | DEF | GK entries from allocator |
-| DEF | DEF total_points, DEF value_score | DEF | DEF entries from allocator |
-| MID | MID xGI, MID value_score | ATK | MID entries from allocator |
-| FWD | FWD form, FWD value_score | ATK | FWD entries from allocator |
+| GK | GK ppg, GK quality_per_m | DEF | GK entries from allocator |
+| DEF | DEF total_points, DEF quality_per_m | DEF | DEF entries from allocator |
+| MID | MID xGI, MID quality_per_m | ATK | MID entries from allocator |
+| FWD | FWD form, FWD quality_per_m | ATK | FWD entries from allocator |
 
 Cross-positional data (form, cheapest, transfers_in, price-history, captain) goes to Phase D assembler, not position agents.
 
@@ -207,8 +207,8 @@ Include all of this in the prompt field, populated with position-specific data:
    {this position's primary stat output}
 
    === fpl stats: {POSITION} value score ===
-   {this position's value_score output}
-   Players ranked by underlying performance (Understat xG/xA) per GBPm. High value_score = outperforming price tag.
+   {this position's quality_per_m output}
+   Players ranked by underlying performance (Understat xG/xA) per GBPm. High quality_per_m = outperforming price tag.
 
    === fpl allocate: {POSITION} picks ===
    {only this position's entries from allocator output, including effective_price}
@@ -244,13 +244,13 @@ Include all of this in the prompt field, populated with position-specific data:
    Run `fpl player "{name}" -f -H` **in parallel** for all candidates in your list.
    For season-start modes with no current-season data, also use `fpl history` data passed in context.
 
-7. **Scoring:** Score each candidate against the mode-specific criteria from rules. Use quality_score and value_score when available (null for players without Understat data - don't penalise).
+7. **Scoring:** Score each candidate against the mode-specific criteria from rules. Use quality_score and quality_per_m when available (null for players without Understat data - don't penalise).
 
 8. **Return format:** Return a structured ranked list. Per candidate:
    ```
    {rank}. {name} ({team}) - GBP{effective_price}m
       Form: {form} | PPG: {ppg} | Minutes: {minutes}
-      Quality: {quality_score}/100 | Value: {value_score}
+      Quality: {quality_score}/100 | Value: {quality_per_m}
       Fixtures (next {horizon}): {condensed fixture run}
       Flags: {injury/suspension/rotation risk, if any}
       Allocator pick: {yes/no}

{fplkit-1.0.0 → fplkit-1.2.0}/.agents/skills/squad-builder/references/rules.md

@@ -33,9 +33,9 @@ After building, note how many of the user's current players (if known) appear in
 ## Value-for-Money
 Available in `fpl player --format json` output when Understat data exists for the player:
 - **quality_score** (0-100): Player output quality normalised against positional ceiling. Form and PPG weighted heavily - measures "current FPL points production rate."
-- **value_score** (quality_score / price per GBPm): Within-position budget efficiency. Higher = more output per pound.
-- When choosing between similarly-ranked candidates at the same position, prefer higher `value_score` to free budget for other slots.
-- `value_score` is not meaningful for cross-position comparison (positional ceilings differ).
+- **quality_per_m** (quality_score / price per GBPm): Within-position budget efficiency. Higher = more output per pound.
+- When choosing between similarly-ranked candidates at the same position, prefer higher `quality_per_m` to free budget for other slots.
+- `quality_per_m` is not meaningful for cross-position comparison (positional ceilings differ).
 - Both fields are `null` for players without Understat data - do not penalise or exclude these players, use other signals instead.
 - **Free Hit note:** Free Hit uses `fpl allocate --horizon 1 --bench-discount 0.01` for a fixture-adjusted, single-GW optimal squad. The solver output is the primary starting point.
 

{fplkit-1.0.0 → fplkit-1.2.0}/.claude/output-styles/fpl-mate.md

@@ -41,7 +41,7 @@ When pulling data for comparison or field extraction, use `--format json` on com
   - `-d` GW-by-GW match performance (FPL API, always fresh)
   - `-u` Understat analysis (shot analysis + situation profile) - use with `-d` for MID/FWD
   - `-H` historical career arc - pts/90, xGI/90, cost trajectory across last 3 seasons
-- `fpl stats` - ranked player list; `-p MID` position filter, `-t ARS` team filter, `-s xGI` sort field (form, ICT, cost, transfers_in_event...), `--min-minutes` appearances filter, `--draft` adds ownership column, `-v` adds quality and value/£m columns (sorts by value by default - use with position filter for best results)
+- `fpl stats` - ranked player list; `-p MID` position filter, `-t ARS` team filter, `-s xGI` sort field (form, ICT, cost, transfers_in_event...), `--min-minutes` appearances filter, `--draft` adds ownership column, `-v` adds quality, quality/£m, and rolling pts/£m columns (sorts by quality/£m by default - use with position filter for best results), `-w N` rolling fixture window (3-10)
 - `fpl fixtures <gw>` - who plays who, difficulty
 - `fpl league` - standings context for risk calibration
 

{fplkit-1.0.0 → fplkit-1.2.0}/.github/workflows/release.yml

@@ -75,4 +75,6 @@ jobs:
           git add CHANGELOG.md
           git diff --cached --quiet && exit 0
           git commit -m "docs: update CHANGELOG.md [skip ci]"
+          # Non-fast-forward risk: if main advances in the ~30s between tag push and here,
+          # this push fails. Acceptable for a solo project - re-run the job manually if needed.
           git push origin HEAD:main

{fplkit-1.0.0 → fplkit-1.2.0}/.gitignore

@@ -1,6 +1,12 @@
-# Credentials and user config (never commit)
+# Local Claude Code instructions (personal, not committed)
+CLAUDE.local.md
+
+# Runtime caches and user secrets (never commit)
 config/*.yaml
-!config/defaults.yaml
+!config/fixture_predictions.yaml
+!config/team_managers.yaml
+!config/team_ratings.yaml
+!config/team_ratings_overrides.yaml
 .env
 
 # Generated version file (hatch-vcs)
@@ -63,9 +69,9 @@ docs/plans/
 docs/brainstorms/
 docs/solutions/
 docs/ideas/
+docs/discarded/
 docs/positioning.md
-docs/legal-risk-assessment.md
-docs/2026-03-23-security-review-pre-open-source.md
+docs/releasing.md
 
 # Local todos
 todos/
@@ -75,11 +81,14 @@ todos/
 .claude/hooks/
 .claude/worktrees/
 .claude/handoffs/
-.agents/skills/legal-risk-assessment/
-.agents/skills/update-fixture-schedule/
-
-# Agentic session logs
-agentic_logs/
 
+# Untracked skills
+.agents/skills/create-readme/
+.agents/skills/documentation-writer/
+.agents/skills/release-notes/
+.agents/skills/release/
+.agents/skills/senior-data-scientist/
+.agents/skills/data-scientist/
+.agents/skills/fpl-data-scientist/
 # OS
 .DS_Store

fplkit-1.2.0/AGENTS.md

@@ -0,0 +1,67 @@
+## Project Overview
+fpl-cli - CLI tool for Fantasy Premier League analysis (classic + draft).
+
+## Setup & Dev
+```bash
+source .venv/bin/activate && pip install -e ".[dev]"
+ruff check fpl_cli/            # Lint
+pyright fpl_cli/               # Type check
+pytest tests/                 # Tests
+```
+Entry point: `fpl_cli/cli/__init__.py:main` (Click). Config: `config/defaults.yaml` (committed) + `~/Library/Application Support/fpl-cli/settings.yaml` (user overrides, deep-merged via `platformdirs`). Override config dir with `FPL_CLI_CONFIG_DIR` env var.
+
+## Architecture
+Agents inherit `fpl_cli/agents/base.py:Agent`, implement `async run(context: dict | None) -> AgentResult`. Organised in `agents/{data,analysis,action,orchestration}/`. AgentResult statuses: SUCCESS, PARTIAL, FAILED, PENDING_APPROVAL.
+
+External consumers: `BenchOrderAgent`, `StartingXIAgent`, and `TransferEvalAgent` are imported directly by the gw-prep skill (Obsidian vault) via standalone scripts (`bench_order.py`, `starting_xi.py`, `transfer_eval.py`) that run in fpl-cli's venv. Changes to any agent's interface or import path will break those scripts.
+
+API clients in `fpl_cli/api/`: FPLClient (main API, caches `bootstrap-static/`), fpl_draft, perplexity (needs `PERPLEXITY_API_KEY`), understat (scrapes understat.com for npxG/xGChain/xGBuildup), historical data via dual-source architecture: VaastavClient (3 historical seasons 2022-25, keyed on `element_code`) + CoreInsightsClient (current season 2025-26+), composed by `HistoricalDataProvider` (`make_historical_provider()`). Shared types in `historical_types.py` (SeasonHistory, PlayerProfile, GwTrendProfile). Season helper: `season_label()` (alias `vaastav_season()`). Scraper in `fpl_cli/scraper/` (needs `FPL_EMAIL`, `FPL_PASSWORD`). Jinja2 templates in `templates/`.
+
+### Models (non-obvious aliases)
+- `Player`: `element_type` = position, `team` = team_id, `code` = stable cross-season ID (element_code). Prices in £0.1m units (100 = £10.0m)
+- `Fixture`: `gameweek` (alias "event"), `home_team_id`/`away_team_id`
+
+For a complete inventory of CLI commands, analysis agents, and skills with JSON support and format awareness, see `.agents/TOOLS.md`.
+
+## Conventions
+### CLI Patterns
+- Read-only data display commands -> direct API client usage (comment `# Pattern: direct-api`)
+- Analytical commands -> via agent (comment `# Pattern: via-agent`)
+- Help text: describe what the user sees, never reference internal components ("agent", "client")
+- Inner async function: always name `_run`
+- **Format awareness:** New commands classified in `CLASSIC_ONLY`/`DRAFT_ONLY` frozensets in `_context.py` (omit for General). Shared commands use `@click.pass_context` and `fmt = get_format(ctx)` to gate irrelevant sections (see `league.py` for pattern).
+
+### Agent Patterns
+- Primary API client: `self.client` in `__init__` (FPLClient for classic agents, FPLDraftClient for draft agents)
+- Secondary clients: qualified name (e.g. `self.perplexity_client`)
+- Position map: import `POSITION_MAP` from `fpl_cli/models/player.py`, never redefine locally
+- Understat enrichment: import `match_fpl_to_understat` from `fpl_cli/api/understat`
+
+### API Method Naming
+- Use `get_` prefix for all data-fetching methods
+- Use domain language (gameweek, player, team), never FPL jargon (event, element, bootstrap-static)
+- FPL jargon translation happens at the model boundary via Pydantic aliases
+- xG, xA, xGI, npxG, FDR, BPS - stats abbreviations acceptable as-is
+
+### Exception Handling
+- Never use bare `except Exception`. Use specific types for narrow try blocks; use `# noqa: BLE001 — <justification>` for intentional broad handlers (agent top-level, scraper resilience, graceful degradation)
+
+## FPL Domain Knowledge
+- Chips (each available **twice** per season, split at GW19 deadline): Wildcard, Free Hit, Bench Boost, Triple Captain
+- Scoring: GK/DEF clean sheet = 4pts, MID = 1pt; goals: DEF=6, MID=5, FWD=4; assist = 3pts; yellow = -1; red = -3
+- Transfers: 1 free/GW, max 5 banked; extra transfers cost 4pts each; Wildcard/Free Hit preserve banked transfers
+- Draft format has no captains, no budget, no transfers, no chips - uses waivers for player acquisition
+
+## Rules
+- Verify before asserting: don't state that a command, file, function, or data point exists without checking first (read the file, run the command, grep for the name)
+- Find-and-replace: review each replacement in context - don't blindly replace substrings in unrelated identifiers
+- Removing/replacing X: new implementation must have zero dependencies on X
+- Repeated convention violations: suggest a ruff lint rule to enforce automatically
+- README must stay in sync: any CLI command added/changed/removed requires updating the relevant job section in "What You Can Do" and, if the command has detailed flags or formulas, `docs/command-reference.md`
+- Architecture doc must stay in sync: adding a new agent, service, API client, or CLI command requires updating `docs/architecture.md`
+- TOOLS.md must stay in sync: adding, removing, or changing a CLI command, analysis agent, or skill requires updating `.agents/TOOLS.md`
+- AGENTS.md must stay in sync: any change to project instructions in CLAUDE.md requires the same change in AGENTS.md
+- CLI changes require corresponding unit tests
+- Changing a function's return format: update existing tests to match and confirm pytest passes
+- Tests: `pytest-asyncio` with `asyncio_mode = "auto"`, factories in `tests/conftest.py` (`make_player()`, `make_team()`, `make_fixture()`)
+- After any task touching Python files, run `pyright fpl_cli/` as a final check alongside ruff and pytest

fplkit-1.2.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+## [1.1.0] - 2026-04-07
+
+### Bug Fixes
+
+- wrap migration in try/except, update architecture.md paths
+- CLI hygiene batch (P10-P13) (#4)
+- Understat name matching for abbreviated/punctuated web_names
+- PR #4 code review follow-ups (#5)
+- review fixes - gather resilience, CSV field protection, test gaps
+- correct README data source count and Core-Insights repo URL
+
+### Features
+
+- add cached dataset fetcher with ETag conditional requests (#6)
+- add rolling pts/£m metric and rename value fields (#7)
+- expose ep_next/ep_this (FPL predicted points) (#8)
+- implement CoreInsightsClient for 2025-26 season data
+- add HistoricalDataProvider composition layer, update call sites
+
+### Refactoring
+
+- extract shared types, rename season helpers, separate cache dirs
+
+## [1.0.0] - 2026-04-03
+
+### Features
+
+- CI pipeline and PyPI publish for v1.0.0 (#1)
+
+

{fplkit-1.0.0 → fplkit-1.2.0}/CLAUDE.md

@@ -15,7 +15,7 @@ Agents inherit `fpl_cli/agents/base.py:Agent`, implement `async run(context: dic
 
 External consumers: `BenchOrderAgent`, `StartingXIAgent`, and `TransferEvalAgent` are imported directly by the gw-prep skill (Obsidian vault) via standalone scripts (`bench_order.py`, `starting_xi.py`, `transfer_eval.py`) that run in fpl-cli's venv. Changes to any agent's interface or import path will break those scripts.
 
-API clients in `fpl_cli/api/`: FPLClient (main API, caches `bootstrap-static/`), fpl_draft, perplexity (needs `PERPLEXITY_API_KEY`), understat (scrapes understat.com for npxG/xGChain/xGBuildup), vaastav (fetches historical CSV data from vaastav/Fantasy-Premier-League GitHub repo - 3 seasons, keyed on `element_code`). Scraper in `fpl_cli/scraper/` (needs `FPL_EMAIL`, `FPL_PASSWORD`). Jinja2 templates in `templates/`.
+API clients in `fpl_cli/api/`: FPLClient (main API, caches `bootstrap-static/`), fpl_draft, perplexity (needs `PERPLEXITY_API_KEY`), understat (scrapes understat.com for npxG/xGChain/xGBuildup), historical data via dual-source architecture: VaastavClient (3 historical seasons 2022-25, keyed on `element_code`) + CoreInsightsClient (current season 2025-26+), composed by `HistoricalDataProvider` (`make_historical_provider()`). Shared types in `historical_types.py` (SeasonHistory, PlayerProfile, GwTrendProfile). Season helper: `season_label()` (alias `vaastav_season()`). Scraper in `fpl_cli/scraper/` (needs `FPL_EMAIL`, `FPL_PASSWORD`). Jinja2 templates in `templates/`.
 
 ### Models (non-obvious aliases)
 - `Player`: `element_type` = position, `team` = team_id, `code` = stable cross-season ID (element_code). Prices in £0.1m units (100 = £10.0m)
@@ -53,12 +53,14 @@ For a complete inventory of CLI commands, analysis agents, and skills with JSON
 - Draft format has no captains, no budget, no transfers, no chips - uses waivers for player acquisition
 
 ## Rules
+- Verify before asserting: don't state that a command, file, function, or data point exists without checking first (read the file, run the command, grep for the name)
 - Find-and-replace: review each replacement in context - don't blindly replace substrings in unrelated identifiers
 - Removing/replacing X: new implementation must have zero dependencies on X
 - Repeated convention violations: suggest a ruff lint rule to enforce automatically
 - README must stay in sync: any CLI command added/changed/removed requires updating the relevant job section in "What You Can Do" and, if the command has detailed flags or formulas, `docs/command-reference.md`
 - Architecture doc must stay in sync: adding a new agent, service, API client, or CLI command requires updating `docs/architecture.md`
 - TOOLS.md must stay in sync: adding, removing, or changing a CLI command, analysis agent, or skill requires updating `.agents/TOOLS.md`
+- AGENTS.md must stay in sync: any change to project instructions in CLAUDE.md requires the same change in AGENTS.md
 - CLI changes require corresponding unit tests
 - Changing a function's return format: update existing tests to match and confirm pytest passes
 - Tests: `pytest-asyncio` with `asyncio_mode = "auto"`, factories in `tests/conftest.py` (`make_player()`, `make_team()`, `make_fixture()`)

fplkit-1.2.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: fplkit
+Version: 1.2.0
+Summary: CLI tool for Fantasy Premier League analysis - classic and draft formats
+Project-URL: Homepage, https://github.com/rossgroomio/fpl-cli
+Project-URL: Repository, https://github.com/rossgroomio/fpl-cli
+Author-email: Ross Groom <rossgroom1+tech@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: platformdirs<5,>=4.3
+Requires-Dist: pulp>=2.7
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: ruamel-yaml>=0.18.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: scraper
+Requires-Dist: playwright>=1.40.0; extra == 'scraper'
+Description-Content-Type: text/markdown
+
+# fpl-cli
+
+Fantasy Premier League analysis from the terminal. Classic and Draft formats. Six data sources, one interface.
+
+[![PyPI](https://img.shields.io/pypi/v/fplkit)](https://pypi.org/project/fplkit/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+<img src="docs/images/fpl-player-demo-v1-0.png"
+     alt="FPL player scouting table in fpl-cli showing form, xGI, expected goals, availability flags and Fantasy Premier League data"
+     width="600"
+     style="max-width: 100%; height: auto;">
+
+*Example output from `fpl player` — real-time player analysis with form, xGI and availability flags.*
+
+## Features
+
+- **Multi-source data** - FPL API, Draft API, Understat (npxG/xGChain), historical data (vaastav 2022-25 + Core-Insights 2025-26), and football-data.org in one place.
+- **Player scouting** - Filter by any stat, track xG trends, spot underperformers, check fixture runs.
+- **Fixture intelligence** - Bayesian difficulty ratings from actual match results, blank/double GW detection, squad exposure analysis.
+- **Custom analysis** - Captain picks, transfer targets, differentials, waivers, and ILP-optimal squad allocation. Opt-in, off by default.
+- **Gameweek reports** - Post-GW reviews and league recaps with optional LLM narrative.
+- **Draft parity** - Most commands work for both Classic and Draft. Waivers cover the free-agent wire.
+- **Agent-friendly** - `--format json` with a consistent envelope on key commands. Ready-made agent skills in `.agents/skills/`.
+
+## Quickstart
+
+```console
+$ pipx install fplkit
+$ fpl init
+$ fpl status
+$ fpl stats -p MID -s form --available-only
+```
+
+`fpl init` configures your FPL IDs and optional features. With just an entry ID you get the full data toolkit.
+
+## Installation
+
+Requires **Python 3.11+**.
+
+```console
+$ pipx install fplkit
+```
+
+Alternatives: `uv pip install fplkit` or `pip install fplkit`.
+
+> [!NOTE]
+> Browser scraping (`fpl squad sell-prices --refresh`) requires the scraper extra and Playwright:
+> ```console
+> $ pipx install 'fplkit[scraper]'
+> $ playwright install chromium
+> ```
+
+## Usage
+
+### After the Gameweek
+
+```console
+$ fpl status                       # GW result, deadline, rank movement, flagged players
+$ fpl review --save --summarise    # Full review with LLM narrative
+$ fpl league                       # Live league standings
+$ fpl league-recap --summarise     # Awards and editorial for the group chat
+```
+
+### Scouting Players
+
+```console
+$ fpl stats -p FWD -s form -a             # Forwards by form, excluding unavailable
+$ fpl player Rice -f -u                   # Deep dive: fixtures + Understat analysis
+$ fpl xg                                  # xG/xA analysis, over/underperformers
+$ fpl history                             # Career arc across 3 seasons
+$ fpl price-history -n 4 -s price_slope   # Bandwagon detection
+```
+
+### Before the Deadline
+
+```console
+$ fpl squad                        # Squad health: form, injuries, recommendations
+$ fpl squad grid -n 8 -w Mbeumo    # 8-GW fixture difficulty grid with a watchlist player
+$ fpl fdr --my-squad               # Your squad's blank/double GW exposure
+$ fpl preview --save --scout       # Full analysis + BUY/SELL research via LLM
+```
+
+### Strategic Planning
+
+```console
+$ fpl fdr --blanks                 # Confirmed + predicted blank/double GWs
+$ fpl chips timing                 # Rule-based Free Hit / Bench Boost / Triple Captain signals
+$ fpl fixtures                     # Next GW fixtures with FDR
+```
+
+### Custom Analysis
+
+Off by default. Enable via `fpl init` or `custom_analysis: true` in settings.yaml.
+
+```console
+$ fpl captain                      # Ranked captain picks (0-100 matchup scoring)
+$ fpl targets --min-own 30         # Transfer targets, template tier
+$ fpl differentials -t 3           # Ultra-differentials (<3% owned)
+$ fpl waivers                      # Free-agent waiver picks with drop suggestions (draft)
+$ fpl transfer-eval --out Palmer --in "Salah,Mbeumo"  # Side-by-side comparison
+$ fpl allocate --horizon 1         # Free Hit: optimal squad for a single GW
+$ fpl ratings                      # Bayesian team strength ratings from match results
+```
+
+Enabling custom analysis also enriches other commands: `fpl stats` gains `--value` columns, `fpl xg` adds Value Picks, `fpl fdr` upgrades to Bayesian FDR with ATK/DEF split.
+
+### JSON Output
+
+Commands with `--format json` emit a consistent envelope:
+
+```json
+{
+  "command": "stats",
+  "metadata": {"gameweek": null, "format": "classic", "custom_analysis": true},
+  "data": [...]
+}
+```
+
+```console
+$ fpl stats --format json -p MID -s expected_goal_involvements
+$ fpl status --format json
+$ fpl fdr --blanks --format json
+```
+
+## Configuration
+
+Run `fpl init` to configure interactively. Settings stored in your platform's config directory (override with `FPL_CLI_CONFIG_DIR`).
+
+**Required:** FPL classic entry ID or draft league + entry IDs.
+
+| Feature | What it enables |
+|---------|----------------|
+| Custom Analysis | Captain, targets, differentials, waivers, allocate, ratings, value scores, Bayesian FDR |
+| League ID | Standings, fines, league recaps |
+| LLM providers | `--summarise` and `--scout` flags (Perplexity, Anthropic, OpenAI, or any compatible API) |
+| FPL credentials | `fpl squad sell-prices` (browser scraping) |
+| `FOOTBALL_DATA_API_KEY` | League table in `fpl review` |
+
+```bash
+# LLM providers (for --summarise and --scout)
+export PERPLEXITY_API_KEY="your-key"    # Research role
+export ANTHROPIC_API_KEY="your-key"     # Synthesis role
+```
+
+See [Command Reference](docs/command-reference.md#configuration-reference) for the full settings.yaml schema and LLM provider setup.
+
+## Development
+
+```console
+$ git clone https://github.com/rossgroomio/fpl-cli.git
+$ cd fpl-cli
+$ python3 -m venv .venv && source .venv/bin/activate
+$ pip install -e ".[dev]"
+$ fpl init
+```
+
+```console
+$ ruff check fpl_cli/    # Lint
+$ pyright fpl_cli/       # Type check
+$ pytest tests/          # Tests
+```
+
+> [!NOTE]
+> Football data provided by the [Football-Data.org API](https://www.football-data.org/). Player and fixture data is property of the Premier League. Expected goals data is property of [Understat](https://understat.com). Historical data from [vaastav/Fantasy-Premier-League](https://github.com/vaastav/Fantasy-Premier-League) (MIT, 2022-25) and [olbauday/FPL-Core-Insights](https://github.com/olbauday/FPL-Core-Insights) (2025-26+). This tool fetches data at runtime and does not redistribute third-party data.
+
+> [!WARNING]
+> Browser scraping (`fpl squad sell-prices`) uses your FPL login to read sell prices. Automated access may violate FPL website terms - use at your own risk.
+
+---
+
+[Command Reference](docs/command-reference.md) | [Custom Analysis Guide](docs/custom-analysis.md) | [Architecture](docs/architecture.md) | [Agent Tools & Skills](.agents/TOOLS.md)