football-docs 0.6.0 → 0.6.2

package/docs/fotmob/identity-surfaces.md

@@ -54,9 +54,8 @@ endpoint family, and snapshot date alongside any bridge evidence.
 - Public endpoints may be undocumented. Treat access and response shape as
   mutable unless the provider documents the contract.
 
-## Reep Next Usage
+## Implementation Notes
 
 Use this page as the public provider-fact reference for FotMob identity
-surfaces, public URL families, and matching cautions. Reep Next can cite those
-facts, but private endpoint handling, scrape internals, rate-limit tactics,
-review outcomes, and register decisions belong outside football-docs.
+surfaces, public URL families, and matching cautions. Keep access implementation
+details, review outcomes, and register decisions outside football-docs.

package/docs/free-sources/contextual-story-joins.md

@@ -0,0 +1,110 @@
+# Contextual Story Joins
+
+Use free and public sources to enrich football fixture data with context that
+commercial event feeds do not always provide: opponent strength, travel distance,
+weather, venue geography, historical baselines, and independent xG.
+
+## Base fixture authority
+
+Choose one provider as the authority for fixture identity, final scores, and match
+status before joining context.
+
+| Need | Good base source |
+|---|---|
+| in-season fixture ids and live status | SportMonks, Opta, TheSportsDB, Sportradar |
+| historical result grids | football-data.co.uk, engsoccerdata |
+| shot-level xG enrichment | Understat, StatsBomb Open Data where covered |
+| broad season stats | FBref / soccerdata |
+
+Do not let an enrichment source silently override the base fixture score or status.
+If an enrichment feed lags behind the fixture authority, preserve the base fixture
+and mark the enrichment fields unavailable.
+
+## Strength controls with ClubElo
+
+ClubElo is useful for match-day team-strength controls and fixture-difficulty
+stories. Join by the fixture date and a maintained team-name map:
+
+```text
+home_elo = ClubElo(home_team, fixture_date)
+away_elo = ClubElo(away_team, fixture_date)
+elo_diff = home_elo - away_elo
+```
+
+ClubElo names are not guaranteed to match provider team labels. Keep the alias
+map in project code, and treat promoted, renamed, and abbreviated clubs as normal
+data-quality cases.
+
+## Weather and climate context
+
+Weather can be joined at venue and kickoff time:
+
+| Field | Join key |
+|---|---|
+| observed match weather | venue latitude/longitude + kickoff timestamp |
+| climate normal | venue latitude/longitude + month |
+| weather anomaly | observed value minus climate normal |
+| condition bucket | rain, snow, fog, clear, wind, heat, cold |
+
+For public weather APIs, store the fetched timestamp, timezone, and units. Weather
+observations are contextual features, not football-provider facts, so label them
+separately from official match data.
+
+## Travel and venue geography
+
+For travel-distance stories, maintain a venue table with club, stadium,
+latitude/longitude, city, and country. Calculate away travel with a geodesic
+distance such as haversine:
+
+```text
+away_travel_km = distance(away_venue_lat_lon, home_venue_lat_lon)
+```
+
+Use travel bands for stable charts, for example `<50 km`, `50-100 km`, `100-200 km`,
+`200-300 km`, and `300+ km`. Distances are approximations of geography, not actual
+team travel logistics.
+
+## Independent xG enrichment
+
+Understat can add independent xG to result stories for the top European leagues.
+Join by date plus home/away team aliases, not by Understat match id alone. Keep
+fields such as:
+
+| Field | Meaning |
+|---|---|
+| `xg` | team's Understat expected goals |
+| `xga` | opponent Understat expected goals |
+| `xg_model` | `understat` |
+| `xg_join_status` | exact, alias, manual, missing |
+
+If the base provider also supplies expected goals, do not average the values unless
+the chart explicitly describes a blended model. Expose both model names instead.
+
+## Additive factor stories
+
+For home-advantage, away-day, and match-context stories, build factors from
+explicit rules:
+
+| Factor | Example rule |
+|---|---|
+| long away trip | `away_travel_km >= 300` |
+| local derby | `away_travel_km < 30` |
+| evening kickoff | kickoff hour `>= 18` |
+| midweek fixture | Tuesday, Wednesday, or Thursday |
+| severe weather | heavy rain, snow, fog, high wind, or extreme heat/cold |
+| strength control | Elo difference at fixture date |
+
+Keep the raw fields and the factor flags. This lets users inspect the story logic
+and lets agents reproduce the chart without guessing which thresholds were used.
+
+## Join hygiene
+
+For public data-story pipelines:
+
+- keep provider ids, team aliases, and venue aliases as explicit mapping tables;
+- record whether each joined field came from exact id, alias, date/team match, or
+  manual override;
+- never overwrite official scores with scraped enrichment data;
+- cache public-source responses and respect rate limits;
+- label sample-size limits when slicing by rare conditions such as snow or fog;
+- separate observed facts from modelled controls such as Elo-adjusted residuals.

package/docs/free-sources/overview.md

@@ -9,6 +9,7 @@
 | Understat | xG, shot-level | Web scrape / soccerdata | Top 5 European leagues | Moderate |
 | ClubElo | Historical Elo ratings | HTTP API | All top European leagues, 1946-present | Generous |
 | football-data.co.uk | Match results + odds | CSV download | 25+ leagues, 20+ seasons | None |
+| engsoccerdata | Historical league results | R package / GitHub data | England 1888+, Spain 1928+, other leagues | None |
 | Transfermarkt | Market values, transfers, injuries | Web scrape | All professional leagues | Strict |
 | WhoScored | Match ratings, event-level (limited) | Web scrape (headed browser) | Top leagues | Strict, requires JS rendering |
 | European Football Statistics | Historical results | CSV download | Many European leagues | None |
@@ -97,7 +98,11 @@ Rank,Club,Country,Level,Elo,From,To
 1,Liverpool,ENG,1,2050,2024-11-30,2024-12-07
 ```
 
-**Used in**: myTeam's PL Era Champions story page (`scripts/fetch-elo-history.ts`).
+**Project use**: For run-in, fixture-difficulty, and season-story surfaces,
+ClubElo is useful as a lightweight strength prior. Join by a maintained club
+name map rather than assuming site labels match your canonical team labels.
+ClubElo is a rating source, not a fixture/result source, so combine it with
+fixtures from Opta, SportMonks, football-data.co.uk, or another schedule feed.
 
 ## football-data.co.uk
 
@@ -118,6 +123,50 @@ Season format: `2425` for 2024/25. League codes: `E0` (Premier League), `E1` (Ch
 - `HC`, `AC` (Corners), `HF`, `AF` (Fouls), `HY`, `AY` (Yellows), `HR`, `AR` (Reds)
 - Betting odds from multiple bookmakers (B365H, B365D, B365A, etc.)
 
+**Project use**: Excellent for scorigami, scoreline grids, baseline baking,
+result-history charts, odds-history backfills, and simple match-stat trend
+stories. For scorigami baselines, use full-time fields (`FTHG`, `FTAG`, `FTR`)
+and ignore half-time or bookmaker columns unless the chart explicitly needs
+them. Keep a league-code map in project code (`E0`, `E1`, `SP1`, etc.) and a
+team-name map because historical labels and promoted/relegated club names can
+drift from canonical names.
+
+## engsoccerdata
+
+**What it provides**: Historical football result datasets packaged for R by
+James P. Curley. The GitHub package includes English league data, FA Cup data,
+playoff data, and several European leagues including Spain, Germany, Italy,
+France, Netherlands, Belgium, Portugal, Turkey, Scotland, Greece, South Africa,
+and MLS.
+
+**Useful datasets**:
+
+| Dataset | Notes |
+|---|---|
+| `england` | English league results, top four tiers, from 1888/89 in the classic package docs |
+| `englandplayoffs` | English playoff matches |
+| `facup` | FA Cup results |
+| `spain` | Spanish league results from 1928/29 in the classic package docs |
+
+**Common fields**:
+
+| Field | Meaning |
+|---|---|
+| `Date` | match date |
+| `Season` | season start year |
+| `home` / `visitor` | home and away teams |
+| `FT` | full-time score string |
+| `hgoal` / `vgoal` | home and away full-time goals |
+| `division` | division label |
+| `tier` | football pyramid tier |
+| `result` | `H`, `A`, or `D` |
+
+**Project use**: Useful as a deep historical baseline for scorigami and
+marcadorigami-style scoreline grids. Pair with football-data.co.uk for recent
+season gap fills or in-season updates. The package was formerly on CRAN and is
+now best treated as a GitHub/open-data source; cite James P. Curley when using
+it in public analysis.
+
 ## Transfermarkt
 
 **What it provides**: Player market values, transfer history, contract details, injury history, squad information, manager history.
@@ -156,8 +205,6 @@ Season format: `2425` for 2024/25. League codes: `E0` (Premier League), `E1` (Ch
 - Rate limiting is strict; adding delays between requests is essential
 - Data is Opta-sourced, so event types and qualifier IDs match Opta's system
 
-**Used in**: myTeam's passmap data pipeline (`scripts/fetch-whoscored-events.ts` stores events in Postgres, `scripts/generate-passmap-data.ts` processes them).
-
 ## European Football Statistics
 
 **What it provides**: Historical match results for European leagues.
@@ -168,13 +215,13 @@ Season format: `2425` for 2024/25. League codes: `E0` (Premier League), `E1` (Ch
 
 ## Comparison Matrix
 
-| Feature | StatsBomb Open | FBref | Understat | ClubElo | football-data.co.uk | Transfermarkt | WhoScored |
-|---|---|---|---|---|---|---|---|
-| Event-level data | Full | No | Shot-level | No | No | No | Full |
-| Aggregated stats | Via events | Yes | Yes | No | Basic | No | Yes |
-| xG | Yes | Yes (Opta) | Yes (own model) | No | No | No | No |
-| Coordinates | Yes | No | Shot coords | No | No | No | Yes |
-| Historical depth | Limited | 2017+ detailed | 2014+ | 1946+ | 1993+ | 2004+ | ~2010+ |
-| League coverage | Select | Top 5+ | Top 5 | Europe | 25+ | Global | Top 5+ |
-| Commercial use | No | No | Unclear | Yes | Yes | No | No |
-| API available | GitHub | No | No | Yes (CSV) | CSV download | No | No |
+| Feature | StatsBomb Open | FBref | Understat | ClubElo | football-data.co.uk | engsoccerdata | Transfermarkt | WhoScored |
+|---|---|---|---|---|---|---|---|---|
+| Event-level data | Full | No | Shot-level | No | No | No | No | Full |
+| Aggregated stats | Via events | Yes | Yes | No | Basic | No | No | Yes |
+| xG | Yes | Yes (Opta) | Yes (own model) | No | No | No | No | No |
+| Coordinates | Yes | No | Shot coords | No | No | No | No | Yes |
+| Historical depth | Limited | 2017+ detailed | 2014+ | 1946+ | 1993+ | 1888+ England | 2004+ | ~2010+ |
+| League coverage | Select | Top 5+ | Top 5 | Europe | 25+ | England + selected global leagues | Global | Top 5+ |
+| Commercial use | No | No | Unclear | Yes | Yes | Non-commercial attribution expected | No | No |
+| API available | GitHub | No | No | Yes (CSV) | CSV download | R/GitHub data | No | No |

package/docs/free-sources/understat.md

@@ -197,12 +197,21 @@ Their xG model is independent from StatsBomb and Opta. Values will differ. The m
 - xG model methodology is not fully published. It's a black box.
 - No event data beyond shots. No passes, tackles, etc.
 - Data updates can lag 1-2 days after matches.
-- Match IDs are internal and don't map to other providers. Match by teams + date.
+- Match IDs are source-specific and don't map to other providers. Match by teams + date.
 - Player names may differ from other sources (transliterations, shortened forms).
 
-## Used In
+## Project use
 
-The myTeam project uses Understat data:
-- `scripts/fetch-season-story.ts` references Understat xG data
-- `src/data/game-state/understat-xg.json` stores cached xG values
-- The `--skip-xg` flag on `fetch-season-story.ts` reuses existing Understat xG data
+Understat is useful as an xG enrichment source for match-result, season-story,
+and game-state surfaces when the primary fixture provider does not include
+shot-level or match-level xG. Cache by competition, season, team names, and match
+date rather than by Understat match ID alone, because Understat IDs are not
+portable across providers.
+
+When joining to Opta, SportMonks, football-data.co.uk, or another fixture source:
+
+- match by date plus home/away team aliases;
+- keep the provider's final score as the fixture authority;
+- store Understat `xG` and `xGA` as an enrichment layer;
+- expose the xG model name so it is not confused with StatsBomb, Opta, or
+  provider-supplied expected-goals values.

package/docs/free-sources/xg-timelines.md

@@ -0,0 +1,123 @@
+# xG Timeline Recipes
+
+Use an xG timeline when the product question is "when did each team create
+danger?" rather than only "what was the final xG total?". The chart should be a
+cumulative step view built from shot-level xG rows plus match-state annotations.
+
+## Required shot fields
+
+Normalise provider shots into one row per shot before building the timeline:
+
+| Field | Required | Notes |
+|---|---|---|
+| `minute` | yes | Regular match minute; exclude shots without a usable time |
+| `second` | optional | Tie-breaker within a minute when available |
+| `added_time` | optional | Preserve stoppage time for labels such as `45+2` |
+| `period` | optional | Needed for extra-time guides and precise halftime handling |
+| `team_id` | yes | Must resolve to home or away team |
+| `player_name` | optional | Tooltip/label only |
+| `xg` | yes | Provider/model xG value for the shot |
+| `outcome` | optional | Goal, saved, post, missed, blocked, etc. |
+| `is_penalty` | optional | Useful for filters or marker styling |
+| `shot_id` | optional | Stable ordering and deduplication |
+| `xg_model` | yes | `understat`, `statsbomb`, `opta`, or another named model |
+
+Do not mix xG models silently. Understat, StatsBomb, Opta, and FBref/Opta values
+come from different models and can disagree for the same shot. If a story blends
+or compares models, expose the model name in the data and chart notes.
+
+## Source-specific inputs
+
+| Source | Timeline inputs |
+|---|---|
+| Understat | `minute`, `X`, `Y`, `xG`, `result`, `h_a`, `player`, `situation`, `shotType` |
+| StatsBomb | shot event `minute`/`second`, `team`, `shot.statsbomb_xg`, `shot.outcome`, `shot.type`, `shot.body_part` |
+| Opta / WhoScored-style events | shot event types `13`-`16`, xG qualifier where licensed, body-part/context qualifiers, goal-mouth qualifiers where available |
+| FBref | season/match aggregates only; not enough for a shot-by-shot timeline |
+
+For Opta-derived feeds, distinguish shot outcomes from score attribution. Type
+`16` with own-goal qualifier `28` should update the score for the opposing team,
+not the event contestant. Disallowed goals should be marked but should not change
+the running scoreline.
+
+## Cumulative step construction
+
+Sort shots by period, minute, second, and a stable shot id if available. For each
+shot, add the current xG value only to the shooting team's cumulative total and
+carry the other team's total forward:
+
+```text
+home_cum_xg_after_shot =
+  previous_home_cum_xg + (shot.team_id == home_team_id ? shot.xg : 0)
+away_cum_xg_after_shot =
+  previous_away_cum_xg + (shot.team_id == away_team_id ? shot.xg : 0)
+```
+
+Render the lines as steps, not smoothed curves. A shot changes the value at a
+specific match moment; smoothing implies chance quality accrued continuously.
+
+For a static chart, emit enough points to draw flat sections:
+
+```text
+(time_before_shot, previous_total)
+(shot_time, previous_total)
+(shot_time, new_total)
+```
+
+This keeps long quiet periods visible and avoids diagonal interpolation between
+unrelated shots.
+
+## Match-time guides
+
+Add guide marks from match structure, not from shot distribution:
+
+| Guide | Typical position |
+|---|---|
+| halftime | 45 minutes |
+| full time | 90 minutes |
+| extra-time halftime | 105 minutes |
+| extra-time full time | 120 minutes |
+
+If stoppage-time placement is flattened into minute values, say so in the output
+or chart notes. Do not invent precise stoppage-time spacing when the source only
+has minute-level timing.
+
+## Running score strip
+
+A score strip helps readers connect chance quality to actual goals. Build it from
+goal events, not from xG values:
+
+| Case | Score handling |
+|---|---|
+| normal goal | increment scoring team |
+| own goal | increment the opponent of the event contestant when the provider encodes own goals that way |
+| penalty goal | increment scoring team and optionally style the marker |
+| disallowed goal | annotate separately; do not increment score |
+| shootout penalty | keep outside the regular xG timeline unless the chart explicitly covers shootouts |
+
+Keep goal markers visually distinct from all-shot dots. A goal is an outcome, not
+a larger xG value.
+
+## Sparse and empty matches
+
+The fallback behaviour should be honest:
+
+| Input state | Recommended output |
+|---|---|
+| no shots with xG | empty state; do not invent a flat 0-0 narrative |
+| one team's shots only | that team's step line plus a flat zero baseline for the opponent |
+| very sparse match | preserve the stepped geometry and show the low-event nature |
+| missing team assignment | exclude the affected shot and record a data-quality warning |
+| missing xG value | exclude from xG totals or render as an unvalued shot marker, but do not add `0` silently |
+
+## Data contract for agents
+
+When generating data for a reusable xG timeline, include:
+
+- `match_id`, `home_team_id`, `away_team_id`;
+- a sorted `shots[]` array with raw provider id where available;
+- `xg_model` and provider/source for every xG value;
+- `score_events[]` for running score reconstruction;
+- `time_guides[]` for halftime/full-time/extra-time markers;
+- `data_quality[]` warnings for excluded shots, missing xG, missing teams, or
+  source/model mismatches.

package/docs/impect/identity-surfaces.md

@@ -78,9 +78,8 @@ is globally stable until that is confirmed in the contract or repeated exports.
 - If profile attributes are thin, keep Impect as a corroborator rather than a
   canonical mint source.
 
-## Reep Next Usage
+## Implementation Notes
 
 Use this page as the public provider-fact reference for Impect identity field
-families and matching cautions. Reep Next can cite those public-safe field
-shapes, but customer deliveries, private IDs, raw feed payloads, and register
-review outcomes belong outside football-docs.
+families and matching cautions. Keep customer deliveries, non-public IDs, raw feed
+payloads, and register review outcomes outside football-docs.