ffl-bigquery 0.1.0__tar.gz

ffl_bigquery-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install
+        run: uv sync --extra dev
+      # -m "not network" is load-bearing: FFC/MFL/nflverse must never be hit in
+      # CI. Those are third-party live services (FFC's terms ask callers not to
+      # poll frequently) and CI has no business calling them on every push.
+      - name: Test
+        run: uv run pytest -m "not network" -q --cov=ffl_bigquery
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type check
+        run: uv run pyright ffl_bigquery

ffl_bigquery-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install 3.13
+      - name: Install
+        run: uv sync --extra dev
+      # Same network exclusion as ci.yml: a release build must never depend on
+      # FFC/MFL/nflverse being reachable at publish time.
+      - name: Test
+        run: uv run pytest -m "not network" -q
+      - name: Build
+        run: uv run python -m build
+      # Installs the actual built artifact into a throwaway venv (not the
+      # `uv sync --extra dev` env the test step used, which has ffl_bigquery
+      # importable from the repo checkout and would never catch this) and
+      # runs it from outside the repo. This is exactly the check that would
+      # have caught the pre-tag Critical 1 bug: six table modules read a
+      # parquet schema-sample via `Path(__file__).parents[3] / "tests/..."`,
+      # which resolves inside a repo checkout but not from a real `pip
+      # install` into site-packages -- FileNotFoundError on every
+      # sync-nflverse invocation, dry-run included. A passing `pytest` run
+      # from the repo root cannot detect that class of bug; only installing
+      # the wheel and running it somewhere `tests/` doesn't exist can.
+      - name: Smoke-test the built wheel
+        run: |
+          uv venv /tmp/wheel-smoke
+          uv pip install --python /tmp/wheel-smoke/bin/python dist/*.whl
+          cd /tmp
+          /tmp/wheel-smoke/bin/ffl-bigquery --version
+          /tmp/wheel-smoke/bin/ffl-bigquery sync-nflverse --dataset p.d --dry-run
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ffl_bigquery-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+dist/
+*.egg-info/
+.pytest_cache/
+uv.lock

ffl_bigquery-0.1.0/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 — 2026-07-30
+
+Initial release: the fantasy layer on top of `nfl-bigquery`. 13 tables plus 2 run logs,
+covering fantasy ADP/rankings, nine season-chunked nflverse/derived tables, and an
+opt-in coordinators table. Still the first public release — Plan 1's ADP-only surface was
+never published, so there is no 0.0.x history to account for.
+
+### Added
+
+**ADP + id bridge**
+- `ff_adp` — historical ADP at snapshot grain from Fantasy Football Calculator (2010→,
+  no 2025) and MyFantasyLeague (2011→), MERGE-upserted on
+  `(source, season, scoring_format, teams, snapshot_date, source_player_id)` so a
+  repeated daily sync is a no-op.
+- `ff_player_xref` — the 20-system nflverse id bridge, MERGE-upserted on `mfl_id`.
+- `gsis_id` resolution on `ff_adp`: exact `mfl_id` join for MFL; normalized-name join
+  for FFC, which publishes an id present in no nflverse id system. Ambiguous name
+  matches are refused rather than guessed.
+- `_ffl_ingest_runs` — chunk-keyed run log powering `sync-adp --resume`.
+- `sync-xref` — standalone `ff_player_xref` upsert.
+
+**nine season-chunked nflverse/derived tables, one shared driver (`sync-nflverse`)**
+- `ff_opportunity` — weekly fantasy opportunity/usage metrics (2006–2025, 159 cols).
+- `snap_counts` — weekly offense/defense/special-teams snap counts (2013–2025), joining
+  `ff_player_xref` via `pfr_id`.
+- `injuries` — weekly injury reports (2009–2025).
+- `depth_charts` — two disjoint upstream schemas (legacy 2001–2024 season-keyed, modern
+  2025+ timestamp-keyed) reconciled into one normalized table with a `source_era`
+  discriminator (2001–2026).
+- `participation` — play-level offense/defense personnel and coverage (2016–2025), with
+  `season`/`week` derived from `nflverse_game_id` (upstream publishes neither directly).
+- `ftn_charting` — FTN's manually-charted play-level features: play action, motion, RPO,
+  screen, blitz (2022–2025).
+- `nfl_coaches` — one row per `(game_id, team)`, unpivoted from `load_schedules()`'s
+  side-by-side home/away coach columns so a mid-season firing is just two different
+  values across two weeks (1999–2026).
+- `ff_points_weekly` — half-PPR + positional rank derived from `load_player_stats()`.
+  `fantasy_points_ppr` is carried through unchanged from upstream (never recomputed) so
+  it stays a correctness oracle a `verify` check can compare a recomputed total against.
+- `team_scheme_week` — the marquee derived table: per-`(season, week, team)` scheme
+  fingerprint (shotgun/no-huddle/pass rate/PROE/EPA from `load_pbp()`, personnel
+  groupings, coverage/pressure, FTN's play-action/motion/RPO/blitz) joined to that
+  week's head coach. Every charted-metric rate ships beside its own denominator column
+  and is `pd.NA` — never `0.0` — when that denominator is zero.
+- `_ffl_nflverse_runs` — a second, separately-keyed `(table_name, season)` run log
+  powering `sync-nflverse --resume`; kept independent of ADP's run log rather than
+  generalized, since that one is tested and already in production use.
+
+**opt-in**
+- `nfl_coordinators` — offensive/defensive coordinator by `(season, team)`, scraped from
+  Wikipedia team-season infobox pages (Pro Football Reference returns HTTP 403 and is
+  unusable). Every row carries its own provenance (`source`, `confidence`,
+  `retrieved_at`) rather than presenting silence as completeness. Deliberately never
+  part of `sync-nflverse` — only the explicit `sync-coordinators` command.
+- `ff_rankings` — FantasyPros ECR, current snapshot only (not season-chunked).
+
+**verify**
+- `--checks adp` — `gsis_id` resolution rate (floor `--min-resolution-rate`, default a
+  conservative 0.60), plus grain uniqueness (which, since the grain includes
+  `snapshot_date`, also guarantees same-day MERGE idempotency — the same underlying
+  fact, reported as two checks for clearer failure messages).
+- `--checks points-weekly` — recomputes full-PPR from `fantasy_points_standard +
+  receptions` and asserts it still agrees with upstream's carried-through
+  `fantasy_points_ppr`.
+- `--checks scheme-denominators` — asserts every charted rate in `team_scheme_week` has
+  a populated denominator and never exceeds 1.0.
+- `--checks participation-coverage` — a whole-table regression guard: measured
+  per-season coverage-charting fill still matches the documented shape (0.000 in
+  2016–2017, never above .496 afterward), catching an upstream backfill that silently
+  changes the data under a shipped chart.
+
+### Known limitations
+
+- **FFC ignores `start_date`/`end_date`**, so intra-preseason ADP drift is
+  forward-capture-only and cannot be backfilled.
+- **FFC has no 2025 data.** Both `ppr` and `standard` return empty for 2025 while
+  2010–2024 and 2026 return normally. This is an upstream gap, not a client bug — the
+  sync records those chunks as `empty` and continues.
+- FFC `half-ppr` history is shallow; pre-recent seasons return no data.
+- **MFL starts at 2011** (2010 and earlier return empty). An earlier probe had this
+  wrong as 2012 — it tested 2010 and 2012 and never tried 2011, which turns out to have
+  812 rows; corrected once a real backfill was run.
+- **`gsis_id` is NULL for 37.9% of `ff_playerids` rows** (66.9% filled among rostered
+  QB/RB/WR/TE/K), which caps resolution everywhere it's used. Measured on the real
+  2010–2026 backfill (18,309 `ff_adp` rows): FFC resolves 89.9%, MFL 91.8%; the worst
+  legitimate `(source, season)` is MFL 2026 at 63.1%, where unresolved rookies have no
+  `gsis_id` yet. `--min-resolution-rate`'s 0.60 default sits just below that floor.
+- **Coordinators are partially available — 46.2% measured.** A 24-team-season sample
+  (6 teams x 2005/2012/2019/2024) suggested ~37%; the actual 2010-2025 backfill
+  produced **473 rows of a possible 1,024** (16 seasons x 32 teams x 2 roles) =
+  **46.2%**. Head coach, by contrast, was 24/24 in that sample and is already
+  first-class in `nfl_coaches` at per-game grain — only coordinators are sparse.
+  All six 2005 team-seasons sampled had neither coordinator field. Pro Football
+  Reference returns HTTP 403 to automated fetches and is unusable, leaving Wikipedia
+  team-season infoboxes as the only fetchable source. Hence `sync-coordinators` is
+  never part of `sync-nflverse` — it is a separate, explicit, opt-in command. Also:
+  the team-abbreviation to Wikipedia-page-title map uses each franchise's current
+  name, so pre-relocation/rename seasons resolve poorly.
+- **`offense_personnel` is unreliable from 2023 on** — it reports 100% fill while
+  carrying defensive players in the offense column (a real 2023 row reads "2 CB, 2 ILB,
+  1 OLB, 1 RB, 1 SS, 2 TE, 2 WR"). `team_scheme_week` therefore parses personnel from
+  `offense_positions` for 2023+, and from `offense_personnel` for 2016–2022 (where
+  `offense_positions` is 0% filled). `personnel_source` records which parser ran.
+- **Charted coverage/pressure/FTN metrics are a sample, never a census.**
+  `defense_man_zone_type`/`defense_coverage_type` fill is 0.000 in 2016–2017 and never
+  exceeds .496 thereafter; `was_pressure` fill is ~.38 pre-2023 and 1.000 from 2023 on.
+  Every derived rate in `team_scheme_week` ships beside its own denominator column, and
+  a zero denominator yields `pd.NA`, never `0.0`. Out-of-era columns are NULL, not 0.
+- **Upstream dtypes are vintage-dependent** — `season`, `week`, `play_id`, and
+  `pos_slot` each change type between years across the nflverse feeds this library
+  reads (e.g. `injuries.season` is Float64 for older seasons, Int32 for others;
+  `participation.play_id` is Float64 in some seasons, Int32 in others). Every one is
+  normalized to a stable BigQuery type before writing; a float↔int join left uncast
+  silently under-matches rather than erroring, so casts are applied even where a single
+  sampled season looks fine on its own.

ffl_bigquery-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Blahovec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ffl_bigquery-0.1.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: ffl-bigquery
+Version: 0.1.0
+Summary: Historical fantasy football ADP, usage, and coaching/scheme data → BigQuery: the fantasy layer on top of nfl-bigquery
+Project-URL: Homepage, https://github.com/blahovec-labs/ffl-bigquery
+Project-URL: Issues, https://github.com/blahovec-labs/ffl-bigquery/issues
+Project-URL: Changelog, https://github.com/blahovec-labs/ffl-bigquery/blob/main/CHANGELOG.md
+Author: Jason Blahovec
+License: MIT
+License-File: LICENSE
+Keywords: adp,bigquery,data-engineering,fantasy-football,nfl,nflverse
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Requires-Python: >=3.11
+Requires-Dist: db-dtypes<2.0,>=1.0
+Requires-Dist: google-cloud-bigquery<4.0,>=3.20
+Requires-Dist: nflreadpy<1.0,>=0.1
+Requires-Dist: pandas<3.0,>=2.0
+Requires-Dist: pyarrow<19.0,>=15.0
+Requires-Dist: requests<3.0,>=2.31
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: truststore>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ffl-bigquery
+
+Historical fantasy football ADP, usage, and coaching/scheme data → BigQuery. The fantasy
+layer on top of [`nfl-bigquery`](https://github.com/blahovec-labs/nfl-bigquery). Sixth in
+the `*-bigquery` family (`statcast-bigquery`, `yfinance-bigquery`, `nhl-bigquery`,
+`nhl-hut-bigquery`, `nfl-bigquery`).
+
+## Install
+
+    pip install ffl-bigquery
+
+Requires Python 3.11+. Writing to BigQuery needs Application Default Credentials with
+permission to create/query tables in the target dataset.
+
+## Quickstart
+
+    ffl-bigquery --version
+
+    ffl-bigquery sync-adp \
+      --adp-table PROJECT.DATASET.ff_adp \
+      --xref-table PROJECT.DATASET.ff_player_xref \
+      --seasons 2010-2026 --sources ffc,mfl --formats ppr,standard --teams 12 \
+      --resume
+
+    ffl-bigquery sync-nflverse --dataset PROJECT.DATASET --seasons 1999-2025 --resume
+
+    ffl-bigquery verify --checks adp --season 2026 --adp-table PROJECT.DATASET.ff_adp
+
+Every `sync-*` command fans its work into independent chunks (by source/season/format for
+ADP, by table/season for the nflverse surface) and records each attempt in a run log, so
+one bad upstream season or source degrades coverage instead of aborting the whole run.
+Pass `--resume` to skip chunks already recorded `success` or `empty`.
+
+## What it writes
+
+13 tables plus 2 run logs. Row counts below are measured from a real backfill against
+live BigQuery (not estimates); `nfl_coordinators` is opt-in and its count depends on what
+you choose to fetch.
+
+| Table | Rows (measured) | Seasons | Written by |
+| --- | --- | --- | --- |
+| `ff_adp` | 18,309 | 2010–2026 | `sync-adp` |
+| `ff_player_xref` | 12,468 | snapshot | `sync-xref` |
+| `ff_rankings` | 6,391 | snapshot, forward-only | `sync-rankings` |
+| `ff_opportunity` | 112,297 | 2006–2025 | `sync-nflverse` |
+| `snap_counts` | 324,611 | 2013–2025 | `sync-nflverse` |
+| `injuries` | 90,752 | 2009–2025 | `sync-nflverse` |
+| `depth_charts` | 1,771,856 | 2001–2026 | `sync-nflverse` |
+| `participation` | 478,989 | 2016–2025 | `sync-nflverse` |
+| `ftn_charting` | 185,215 | 2022–2025 | `sync-nflverse` |
+| `nfl_coaches` | 15,096 | 1999–2026 | `sync-nflverse` |
+| `ff_points_weekly` | 476,156 | 1999–2025 | `sync-nflverse` |
+| `team_scheme_week` | 14,546 | 1999–2025 | `sync-nflverse` |
+| `nfl_coordinators` | opt-in, 46.2% measured fill | 2010–2025 (as backfilled) | `sync-coordinators` |
+| `_ffl_ingest_runs` | run log, keyed `(source, season, scoring_format, teams)` | — | `sync-adp` |
+| `_ffl_nflverse_runs` | run log, keyed `(table_name, season)` | — | `sync-nflverse` |
+
+That's ~3.5M rows across the twelve non-opt-in tables. Nine of the thirteen
+(`ff_opportunity`, `snap_counts`, `injuries`, `depth_charts`, `participation`,
+`ftn_charting`, `nfl_coaches`, `ff_points_weekly`, `team_scheme_week`) share one driver —
+`sync-nflverse` — because they're all the same shape: load a frame for season *S*, align
+it to a schema, replace that season. `ff_adp` and `nfl_coordinators` are chunked
+differently (by source/format and by team-season respectively) because their upstreams
+are; `ff_player_xref` and `ff_rankings` aren't season-chunked at all — they're
+whole-table/current-snapshot syncs.
+
+`team_scheme_week` is the marquee derived table: a per-`(season, week, team)` scheme
+fingerprint (shotgun/no-huddle/pass rate/PROE/EPA, personnel groupings, coverage/pressure,
+FTN's play-action/motion/RPO/blitz) joined to that week's head coach from `nfl_coaches` —
+built for "what changed when the coach changed." Every `gsis_id` column resolves against
+`ff_player_xref` (via `pfr_id` for `snap_counts`, directly elsewhere); see Known
+limitations for the resolution ceiling that imposes.
+
+## Known limitations
+
+Every one of these was measured against the real feeds, not assumed:
+
+- **FFC ignores `start_date`/`end_date`.** Requests for different date windows return the
+  identical current window, so intra-preseason ADP drift is forward-capture-only and
+  cannot be backfilled — it exists only if a sync actually ran that day.
+- **FFC has no 2025 data.** Both `ppr` and `standard` return empty for 2025 while
+  2010–2024 and 2026 return normally. This is an upstream gap, not a client bug — the
+  sync records those chunks as `empty` and continues.
+- **MFL starts at 2011.** 2010 and earlier return `{"adp": {"totalPicks": "0", ...}}`
+  with no player data.
+- **`gsis_id` is NULL for 37.9% of `ff_playerids` rows** (66.9% filled among rostered
+  QB/RB/WR/TE/K; the rest are college prospects and players who never reached an NFL
+  roster), which caps every downstream resolution rate. Measured on the real 2010–2026
+  backfill (18,309 `ff_adp` rows): **FFC resolves 89.9%, MFL 91.8%**; the worst legitimate
+  `(source, season)` is **MFL 2026 at 63.1%** (current-year rookies without a `gsis_id`
+  yet). `verify`'s `--min-resolution-rate` defaults to a conservative **0.60**, just below
+  that floor.
+- **Coordinators are partially available — 46.2% measured.** A 24-team-season sample
+  (6 teams x 2005/2012/2019/2024) suggested ~37%; the actual 2010-2025 backfill
+  produced **473 rows of a possible 1,024** (16 seasons x 32 teams x 2 roles) =
+  **46.2%**. Head coach, by contrast, was 24/24 in that sample and is already
+  first-class in `nfl_coaches` at per-game grain — only coordinators are sparse.
+  All six 2005 team-seasons sampled had neither coordinator field. Pro Football
+  Reference returns HTTP 403 to automated fetches and is unusable, leaving Wikipedia
+  team-season infoboxes as the only fetchable source. Hence `sync-coordinators` is
+  never part of `sync-nflverse` — it is a separate, explicit, opt-in command. Also:
+  the team-abbreviation to Wikipedia-page-title map uses each franchise's current
+  name, so pre-relocation/rename seasons resolve poorly.
+- **`offense_personnel` is unreliable from 2023 on.** It still reports 100% fill for
+  2023–2025, but its content changed without notice — a real 2023 row reads
+  `"2 CB, 2 ILB, 1 OLB, 1 RB, 1 SS, 2 TE, 2 WR"`, defensive players inside the offense
+  column. `team_scheme_week` therefore parses personnel from `offense_positions` (a
+  per-player position list) for 2023+, and falls back to `offense_personnel` for
+  2016–2022, where `offense_positions` is 0% filled. Each row's `personnel_source` column
+  records which parser ran.
+- **Charted coverage/pressure/FTN metrics are a sample, never a census.** Coverage
+  charting fill (`defense_man_zone_type`/`defense_coverage_type`) is **0.000 in
+  2016–2017** and never exceeds **.496** afterward; `was_pressure` fill is ~.38 pre-2023
+  and 1.000 from 2023 on. Every derived rate in `team_scheme_week` therefore ships beside
+  its own denominator column (e.g. `plays_charted_coverage` next to `man_rate`), and the
+  rate is `pd.NA` — never `0.0` — when that denominator is 0, so "nobody charted it" never
+  reads as "this team never blitzed." Out-of-era columns are NULL, not 0, for the same
+  reason.
+- **Upstream dtypes are vintage-dependent.** `season`, `week`, `play_id`, and `pos_slot`
+  each change type between years in the raw nflverse feeds (e.g. `season` arrives as a
+  string in some tables, a float in others; `play_id` is Float64 in some seasons and
+  Int32 in others). This library normalizes every one of them to a stable BigQuery type
+  before writing — consumers reading nflverse directly should expect the raw dtype to
+  vary by season and cast defensively before joining.
+
+See `CHANGELOG.md` for the full per-release list, including two claims an earlier probe
+got wrong and this backfill corrected (MFL's true start season, and FFC's missing 2025).
+
+## CLI
+
+    ffl-bigquery --version
+
+    # ADP + the id bridge it resolves against
+    ffl-bigquery sync-adp \
+      --adp-table PROJECT.DATASET.ff_adp --xref-table PROJECT.DATASET.ff_player_xref \
+      --seasons 2010-2026 --sources ffc,mfl --formats ppr,standard --teams 12 \
+      --min-interval 1.0 --resume
+
+    ffl-bigquery sync-xref --xref-table PROJECT.DATASET.ff_player_xref
+
+    # the nine season-chunked nflverse/derived tables, one dataset, one command
+    ffl-bigquery sync-nflverse --dataset PROJECT.DATASET --seasons 1999-2025 --resume
+
+    # a subset, if you only want a few
+    ffl-bigquery sync-nflverse --dataset PROJECT.DATASET --seasons latest \
+      --tables ff_opportunity,snap_counts,injuries --resume
+
+    # current ECR snapshot -- not season-chunked
+    ffl-bigquery sync-rankings --rankings-table PROJECT.DATASET.ff_rankings
+
+    # opt-in, 46.2% measured fill -- never part of sync-nflverse
+    ffl-bigquery sync-coordinators \
+      --coordinators-table PROJECT.DATASET.nfl_coordinators \
+      --seasons 2019-2024 --teams all --min-interval 1.0
+
+    ffl-bigquery verify --checks adp --season 2026 --adp-table PROJECT.DATASET.ff_adp
+    ffl-bigquery verify --checks points-weekly --season 2025 \
+      --points-weekly-table PROJECT.DATASET.ff_points_weekly
+    ffl-bigquery verify --checks scheme-denominators --season 2025 \
+      --scheme-week-table PROJECT.DATASET.team_scheme_week
+    ffl-bigquery verify --checks participation-coverage \
+      --participation-table PROJECT.DATASET.participation
+
+Notes:
+
+- `sync-adp` fans a season/source/format/teams matrix into independent chunks, so one dead
+  upstream source degrades coverage instead of aborting the run; `--resume` skips chunks
+  already recorded `success` or `empty` in `_ffl_ingest_runs`.
+- `sync-nflverse` derives each table's ref as `project.dataset.<name>` from a single
+  `--dataset` — no per-table flags needed. `--tables` defaults to all nine and is
+  validated against the known registry before any fetch, so a typo fails fast. Its
+  `--resume` reads `_ffl_nflverse_runs`, a second run log keyed `(table_name, season)`
+  — deliberately separate from ADP's `(source, season, scoring_format, teams)` log rather
+  than a shared generalization of it.
+- `sync-rankings` takes `--rankings-table` (not `--dataset`) because `ff_rankings` is a
+  single current-snapshot table, not a season matrix.
+- `sync-coordinators` takes `--coordinators-table`, `--seasons`, `--teams` (comma-separated
+  abbreviations, or `all` for all 32), and `--min-interval`. A missing or unparseable
+  Wikipedia page is a normal, exception-free outcome here (not every team-season has an
+  infobox with the fields populated), so there's no separate failed/empty run log — just a
+  fetched/missing/unavailable tally in the final log line.
+- `--min-interval` (seconds, default `1.0`, both `sync-adp` and `sync-coordinators`)
+  throttles the delay between requests to third-party sources — the minimum respectful
+  spacing backing FFC's "do not poll frequently" terms and general politeness toward
+  Wikipedia's API; see Data sources & attribution below.
+- `verify --checks` accepts a comma-separated subset of `adp`, `points-weekly`,
+  `scheme-denominators`, `participation-coverage`. Each group validates its own required
+  flags at dispatch time (e.g. `scheme-denominators` needs `--scheme-week-table` and
+  `--season`) rather than making every flag globally required. `--min-resolution-rate`
+  (default `0.60`) and `--ppr-tolerance` (default `0.01`) are the two numeric knobs.
+- `sync-adp`, `sync-xref`, `sync-nflverse`, and `sync-coordinators` all accept `--dry-run`
+  to print what would happen without writing or fetching.
+
+## Data sources & attribution
+
+- **nflverse** via [`nflreadpy`](https://nflreadpy.nflverse.com/) — player IDs, usage,
+  snap counts, injuries, depth charts, participation, FTN charting, schedules/coaches, and
+  weekly player stats.
+- **[Fantasy Football Calculator](https://fantasyfootballcalculator.com/)** — historical
+  ADP (2010→present, no 2025). Their ADP REST API is free for personal and commercial use;
+  this project provides attribution as requested. Data updates once daily — do not poll
+  frequently (`--min-interval` backs this).
+- **[MyFantasyLeague](https://www.myfantasyleague.com/)** — historical ADP
+  (2011→present) via the free `export?TYPE=adp` endpoint.
+- **Wikipedia** — offensive/defensive coordinator names, via the `action=parse` API
+  against team-season infobox pages (`nfl_coordinators`, opt-in, 46.2% measured fill; see Known
+  limitations).
+
+## Local development (Windows / TLS interception)
+
+If HTTPS requests fail with `unable to get local issuer certificate` or
+`CERTIFICATE_VERIFY_FAILED`, a local security product (e.g. Norton) is intercepting TLS
+and re-signing it with a certificate that OpenSSL's bundled trust store doesn't trust,
+even though the OS does. `--native-tls` alone does **not** fix this — it only affects
+uv's own downloads of packages/pythons, not certificate validation inside the Python
+process that makes the actual HTTP requests.
+
+Running the test suite already handles this automatically: `tests/conftest.py` calls
+`truststore.inject_into_ssl()` (which validates against the OS-native trust store
+instead of OpenSSL's) for `network`-marked tests only. You just need `truststore`
+installed, which the `dev` extra provides:
+
+    uv run --native-tls --extra dev pytest -m network -v
+
+Outside the test suite (e.g. exploring interactively), you have to invoke that
+injection yourself, since it isn't compiled into the shipped package:
+
+    uv run --native-tls --extra dev python -c "import truststore; truststore.inject_into_ssl(); ..."
+
+MIT licensed.