football-docs 0.3.0 → 0.3.1

package/README.md

@@ -4,10 +4,20 @@ Searchable football data provider documentation for AI coding agents. Like [Cont
 
 **Who it's for:** Developers and analysts who use AI coding tools (Claude Code, Cursor, VS Code Copilot, Windsurf) to work with football data. Works with any tool that supports MCP.
 
-**What it does:** Gives your AI agent a searchable index of documentation for 16 football data providers — event types, qualifier IDs, coordinate systems, API endpoints, data models, and cross-provider comparisons. Your agent looks up the real docs instead of guessing from training data.
+**What it does:** Gives your AI agent a searchable index of documentation for 15 football data providers — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons. Your agent looks up the real docs instead of guessing from training data.
 
 **Why not just let the AI figure it out?** LLMs get football data specifics wrong constantly — Opta qualifier IDs, StatsBomb coordinate ranges, API endpoint URLs, library method signatures. These are mutable facts that change across versions. football-docs gives the agent verified, sourced documentation with provenance tracking so you know where every answer came from.
 
+## Provider identity facts
+
+football-docs is the public source for provider identity-surface facts: access
+shape, ID schemes, matching fields, provider quirks, and provenance rules.
+Curated Reep-derived notes belong here when they can be stated without private
+register state. They should say whether a fact comes from public docs, public
+page evidence, licensed feed shape, or a reviewed public-safe observation, and
+must not include private paths, credentials, scraper state, action ledgers, mint
+salts, or raw restricted payloads.
+
 MCP ([Model Context Protocol](https://modelcontextprotocol.io)) is a standard for connecting AI coding tools to external data sources.
 
 ## Quick start
@@ -92,6 +102,7 @@ Add to `claude_desktop_config.json`:
 - "What is Opta qualifier 76?" (big chance)
 - "How does StatsBomb represent shot events?"
 - "Compare Opta and Wyscout coordinate systems"
+- "Which provider IDs are safe identity bridges for Transfermarkt players?"
 - "Does SportMonks have xG data?"
 - "What event types does kloppy map to GenericEvent?"
 - "How does SPADL represent a tackle?"
@@ -100,18 +111,23 @@ Add to `claude_desktop_config.json`:
 
 | Provider | Chunks | Categories |
 |----------|--------|------------|
-| StatsBomb | 143 | event-types, data-model, coordinate-system, api-access, xg-model |
+| StatsBomb | 150 | event-types, data-model, coordinate-system, api-access, xg-model, identity-surfaces |
 | kloppy | 100 | data-model, usage, provider-mapping |
-| SportMonks | 71 | event-types, data-model, api-access |
+| SportMonks | 78 | event-types, data-model, api-access, identity-surfaces |
 | databallpy | 63 | data-model, overview, usage |
 | mplsoccer | 62 | overview, pitch-types, visualizations |
-| Wyscout | 61 | event-types, data-model, coordinate-system, api-access |
+| Wyscout | 68 | event-types, data-model, coordinate-system, api-access, identity-surfaces |
 | Free sources | 45 | overview, fbref, understat |
 | soccerdata | 40 | overview, data-sources, usage |
-| Opta | 29 | event-types, qualifiers, coordinate-system, api-access |
+| Opta | 36 | event-types, qualifiers, coordinate-system, api-access, identity-surfaces |
 | socceraction | 26 | SPADL format, VAEP, Expected Threat |
+| FotMob | 7 | identity-surfaces |
+| Impect | 7 | identity-surfaces |
+| SkillCorner | 7 | identity-surfaces |
+| Soccerdonna | 7 | identity-surfaces |
+| Transfermarkt | 7 | identity-surfaces |
 
-**640 searchable chunks** across 10 providers.
+**703 searchable chunks** across 15 providers.
 
 ## Contributing
 

package/bin/serve.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-await import(resolve(__dirname, "..", "dist", "index.js"));
+await import(pathToFileURL(resolve(__dirname, "..", "dist", "index.js")).href);

package/docs/fotmob/identity-surfaces.md

@@ -0,0 +1,62 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# FotMob Identity Surfaces
+
+FotMob is useful as a public consumer-facing corroborator for fixtures, teams,
+players, and competition pages. It should generally be treated as a bridge and
+lookup surface rather than as the canonical ontology source.
+
+## Access Surface
+
+FotMob identity evidence usually comes from public web pages or undocumented
+consumer-facing endpoints. Treat access and response shape as mutable, record
+the public URL or endpoint family and snapshot date, and avoid publishing
+scraping bypass or rate-limit evasion details.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | league or tournament ID | Useful public bridge. Check country, gender, season, and competition type. |
+| Season | season ID or season path parameter where exposed | Treat as provider-scoped and audit URL/API stability. |
+| Match | match ID | Strong public match corroborator when fixture fields align. |
+| Team | team ID | Useful for clubs and national teams. Check side type and country. |
+| Player | player ID | Useful public profile bridge. Corroborate with DOB, nationality, team, and position from stronger sources. |
+| Coach or staff | manager profile where exposed | Treat as role evidence unless profile attributes are strong enough. |
+
+## ID Scheme Notes
+
+FotMob IDs are provider-scoped numeric IDs. Match, team, player, league, and
+season IDs are useful bridges, while URL slugs and display labels are handles.
+Because the public endpoint contract is undocumented, store source URL,
+endpoint family, and snapshot date alongside any bridge evidence.
+
+## Useful Matching Fields
+
+- Match: FotMob match ID, date/time, home and away teams, score, league, season,
+  venue, status, lineups, and player stats.
+- Team: team ID, official/display name, country, league participation, squad,
+  and fixtures.
+- Player: player ID, full name, date of birth where present, nationality,
+  position, current team, shirt number, and match participation.
+
+## Known Quirks
+
+- FotMob is optimised for product display. Display names, slugs, and grouping
+  labels may change.
+- Profile and current-team surfaces are point-in-time facts. Keep a snapshot
+  date when using them.
+- Public endpoints may be undocumented. Treat access and response shape as
+  mutable unless the provider documents the contract.
+
+## Reep Next Usage
+
+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.

package/docs/impect/identity-surfaces.md

@@ -0,0 +1,61 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# Impect Identity Surfaces
+
+Impect is primarily useful as a commercial match and event data provider. Public
+documentation for identity surfaces is limited, so this page records cautious
+curated guidance for entity-resolution work that has legitimate data access.
+
+## Access Surface
+
+Access is through licensed Impect deliveries or customer APIs. Public
+football-docs examples should stay synthetic or describe field families only.
+Record delivery date, competition scope, and whether IDs are documented as
+stable across deliveries before using them as durable bridges.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | provider competition key | Check whether the feed exposes stable competition IDs or only customer-specific names. |
+| Season | provider season or competition-edition key | Treat as provider scoped until audited. |
+| Match | provider match key | Strong bridge if the key is stable in the delivered feed and fixture fields align. |
+| Team | provider team key | Corroborate with match participation, name, country, and side type. |
+| Player | provider player key | Corroborate with lineup/event participation and biographical attributes from another authority. |
+| Staff | provider staff or official key if exposed | Treat as role evidence unless profile attributes are available. |
+
+## ID Scheme Notes
+
+Treat Impect match, team, player, season, and competition keys as opaque
+provider-scoped IDs. Some deliveries may be customer-shaped; do not assume a key
+is globally stable until that is confirmed in the contract or repeated exports.
+
+## Useful Matching Fields
+
+- Match: provider match key, date, home and away teams, score, competition,
+  season, venue, and delivery snapshot.
+- Team: provider team key, names, country, competition participation, and match
+  relationship evidence.
+- Player: provider player key, display name, team in match, lineup status,
+  shirt number, position, and event participation.
+
+## Known Quirks
+
+- Commercial data extracts may be customer-shaped. Confirm whether IDs are
+  stable across deliveries before using them as durable bridges.
+- Event participation is strong relationship evidence, but it does not prove
+  person identity without attribute or external-provider corroboration.
+- If profile attributes are thin, keep Impect as a corroborator rather than a
+  canonical mint source.
+
+## Reep Next Usage
+
+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.

package/docs/opta/identity-surfaces.md

@@ -0,0 +1,71 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# Opta / Stats Perform Identity Surfaces
+
+Opta data usually has the strongest structured identity spine for professional
+football projects that have licensed access to the SDAPI feeds. Treat Opta as a
+canonical schedule and structure source only when the local entitlement and
+coverage audit prove that the relevant competition family is complete.
+
+## Access Surface
+
+Primary access is through licensed Stats Perform / Opta feeds or customer
+exports. Public-facing Opta Analyst surfaces can be useful for examples, but
+they are not a substitute for an entitlement-safe feed contract. Record the feed
+family, extraction date, and competition coverage when using Opta identity facts.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | competition or tournament identifiers | Use with tournament-calendar metadata. Names and display labels vary by locale and feed. |
+| Season | tournament calendar UUID | Strong season or tournament-edition key. Split-stage competitions may need parent and child season modelling outside Opta. |
+| Stage or round | stage, phase, group, round, or schedule metadata | Opta is often authoritative for schedule-stage shape, but label strings still need normalisation. |
+| Match | fixture or match UUID | Best canonical match key when schedule coverage is complete. Fixture tuples should corroborate, not define, identity. |
+| Team | contestant UUID | Can represent clubs, national teams, youth teams, reserve sides, or historical contestants. Use type/scope attributes. |
+| Player | person UUID | Strong person key inside Opta. Still corroborate against names, DOB, nationality, and relationship evidence before cross-provider bridging. |
+| Coach or staff | person UUID plus role surface | Person UUIDs can span player and coach roles. Keep role edges separate from person identity. |
+
+## ID Scheme Notes
+
+Opta identifiers are opaque provider keys. Do not parse semantic meaning from
+their string shape, and do not assume that display labels, stage labels, or
+contestant names are stable identifiers. Match, contestant, person, competition,
+and tournament-calendar IDs should be stored with provider, feed family, and
+snapshot metadata.
+
+## Useful Matching Fields
+
+- Match: date/time, home and away contestant UUIDs, score, competition, season,
+  stage, venue, and status.
+- Team: contestant UUID, official name, short name, country, gender, age class,
+  national-team or club scope, and active period where available.
+- Person: Opta person UUID, full name, short name, date of birth, nationality,
+  position, gender, and squad or career memberships.
+- Relationships: schedule team participation, squads, lineups, coaching staff,
+  substitutions, and career memberships.
+
+## Known Quirks
+
+- Opta labels are provider display labels, not ontology. Do not mint a separate
+  competition or team solely because the feed label differs from another
+  provider.
+- Some competitions have full schedule and squad coverage but sparse match-event
+  or lineup tables in a local mirror. Check all person substrates before
+  assuming people cannot be resolved.
+- National teams need explicit team scope and country attributes. Do not encode
+  the full national-team concept only in a club-shaped team type.
+- Some person facts are current-point-in-time surfaces, especially active squad
+  or career listings. Record the snapshot date when using them.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for Opta identity surfaces:
+access shape, ID families, matching fields, and known quirks. Reep Next
+acceptance policy, canonical-feed assignments, minting, review cases, action
+ledgers, and private feed observations belong outside football-docs.

package/docs/skillcorner/identity-surfaces.md

@@ -0,0 +1,60 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# SkillCorner Identity Surfaces
+
+SkillCorner is mainly a tracking and physical-data provider. Its identity
+surfaces are most useful for linking delivered match, team, and player rows back
+to an existing register rather than minting a full football ontology.
+
+## Access Surface
+
+Access is through licensed SkillCorner APIs or delivered tracking/physical-data
+files. Public guidance should use synthetic examples or high-level field names,
+not proprietary tracking payloads. Record delivery date, match scope, and data
+product when using SkillCorner identity evidence.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | provider competition key where present | Often secondary to match delivery scope. Audit before treating as canonical. |
+| Season | provider season or delivery context | Keep provider-scoped unless a stable season key is documented in the extract. |
+| Match | provider match key | Strong bridge when fixture fields and delivery metadata agree. |
+| Team | provider team key | Corroborate with match participation and team names. |
+| Player | provider player key | Corroborate with tracking roster, shirt number, position, and external person attributes. |
+
+## ID Scheme Notes
+
+SkillCorner IDs should be treated as opaque and provider-scoped. Match delivery
+IDs, team IDs, and player IDs are strongest when paired with the delivery
+snapshot and fixture context. A tracking roster key is not automatically a
+season membership or person identity without corroborating attributes.
+
+## Useful Matching Fields
+
+- Match: provider match key, date, competition, season, home and away teams,
+  score where present, and data delivery snapshot.
+- Team: provider team key, name, side in match, and relationship to match.
+- Player: provider player key, name, team in match, shirt number, position,
+  starter/substitute status where supplied, and tracking samples.
+
+## Known Quirks
+
+- Tracking feeds can expose matchday rosters without enough biographical detail
+  for safe person minting. Use them as relationship evidence unless another
+  source supplies the identity attributes.
+- Delivery metadata may be more reliable than display names for reproducible
+  matching.
+- A match-level tracking file is not proof of a season-long membership edge.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for SkillCorner identity
+surfaces in tracking and physical-data deliveries. Reep Next can cite the field
+families and matching cautions, but raw tracking payloads, private delivery
+examples, and register review outputs belong outside football-docs.

package/docs/soccerdonna/identity-surfaces.md

@@ -0,0 +1,66 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# Soccerdonna Identity Surfaces
+
+Soccerdonna is a useful public corroborator for women's football, particularly
+for teams, competitions, player profiles, staff pages, and match reports. Treat
+it as a public evidence provider whose coverage and structure vary by
+competition and era.
+
+## Access Surface
+
+Soccerdonna is a public website surface. Use public profile pages, competition
+pages, and match reports as corroborating evidence, with the page URL and
+snapshot date recorded. Do not publish private scraping state, retry logs, or
+local mirror paths.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | competition page ID or slug | Useful corroborator. Canonical competition shape should still follow the chosen match feed. |
+| Season | season-scoped competition URL parameters | Can corroborate season membership but may not match a register season hierarchy exactly. |
+| Stage or round | match-report round labels | Useful for stage naming after normalisation. Raw labels should not be minted directly. |
+| Match | match-report or `spielbericht` ID | Strong public match corroborator when date, teams, and score align. |
+| Team | team profile ID | Useful for women's clubs and competition participation. Check gender and side type explicitly. |
+| Player | player profile ID | Useful for names, DOB where present, nationality, position, and career/team membership evidence. |
+| Coach or staff | staff profile ID | Useful for coaching roles, but role labels need a normalised public vocabulary. |
+
+## ID Scheme Notes
+
+Treat profile, team, competition, and match-report IDs as provider-scoped
+bridges. URL text and slugs are handles, not identity. Season and competition
+URL parameters are useful context, but the target register still decides whether
+they map to a season, stage, or competition entity.
+
+## Useful Matching Fields
+
+- Match reports: date, home team, away team, score, competition, round label,
+  lineups, substitutions, and staff.
+- Player and coach profiles: full name, display name, date of birth,
+  nationality, position or role, profile URL, and career memberships.
+- Team pages: official name, competition entries, country, gender context, and
+  match participation.
+
+## Known Quirks
+
+- DOB coverage varies by era and competition. Missing DOB should create review
+  residue rather than forcing a weak name-only bridge.
+- Round labels need normalisation before stage minting. Preserve the raw label
+  as evidence where useful.
+- Soccerdonna can expose people through match reports before profile data has
+  enough identity attributes to bridge safely.
+- Some pages are better corroborators than canonical mint sources because their
+  season and competition hierarchy can differ from the schedule feed.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for Soccerdonna profile,
+team, competition, and match-report identity surfaces. Reep Next can cite those
+facts while keeping review decisions, private scrape state, action logs, and
+women's-football implementation plans outside football-docs.

package/docs/sportmonks/identity-surfaces.md

@@ -0,0 +1,65 @@
+---
+source_type: curated
+source_url: https://docs.sportmonks.com/v3
+upstream_version: null
+crawled_at: null
+---
+
+# SportMonks Identity Surfaces
+
+SportMonks exposes a broad REST API with stable numeric IDs for leagues,
+seasons, stages, fixtures, participants, players, coaches, venues, and related
+entities. It is a useful bridge and corroborator, especially where public API
+access is available.
+
+## Access Surface
+
+Primary access is the documented SportMonks football API. Include expansions can
+make identity, relationship, and event evidence available from the same request,
+but callers should still record the endpoint, include set, plan scope, and
+request date because coverage depends on subscription tier.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | league ID | Strong provider key. League names and display categories should be normalised. |
+| Season | season ID | Strong provider key under a league. Use start/end years and league relationship for review. |
+| Stage or round | stage ID, round ID, group ID | Useful provider structure, but may differ from a canonical schedule feed. |
+| Match | fixture ID | Strong match bridge when date, participants, score, and competition align. |
+| Team | participant ID | Can represent clubs or national teams. Check participant type and country. |
+| Player | player ID | Strong provider key only if not reused or contaminated by previous bridge errors. Corroborate with attributes. |
+| Coach or staff | coach ID | Treat as person identity with role-specific evidence. |
+
+## ID Scheme Notes
+
+SportMonks IDs are numeric provider IDs. Keep them provider-scoped and do not
+merge by bare number across providers. League, season, stage, round, fixture,
+participant, player, coach, and venue IDs should be stored with the source
+endpoint and include path that supplied them.
+
+## Useful Matching Fields
+
+- Fixture: `fixture.id`, league, season, stage, round, participants, start time,
+  scores, state, venue, and lineups.
+- Participant: ID, name, short code, country, gender or type where present, and
+  fixture participation.
+- Player: ID, display name, common name, date of birth, nationality, position,
+  height, weight, image URL, and team/lineup relationships.
+
+## Known Quirks
+
+- Broad APIs can carry legacy or contaminated bridges if a downstream register
+  previously joined the wrong person. Validate same-provider ID uniqueness.
+- Include-based responses can make relationship evidence easy to retrieve, but
+  consumers must still distinguish lineup, squad, current team, and historical
+  membership semantics.
+- Stages and rounds are provider shape. Keep the canonical ontology decision
+  separate from the SportMonks response nesting.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for SportMonks ID families,
+API identity surfaces, include paths, and matching cautions. Reep Next can cite
+those facts, but contaminated-bridge review, private validation output, API
+keys, paid-tier payloads, and register decisions belong outside football-docs.

package/docs/statsbomb/identity-surfaces.md

@@ -0,0 +1,65 @@
+---
+source_type: curated
+source_url: https://github.com/statsbomb/open-data
+upstream_version: null
+crawled_at: null
+---
+
+# StatsBomb Identity Surfaces
+
+StatsBomb provides strong match, lineup, event, and tactical context for covered
+competitions. Open Data is excellent for public examples and corroboration, but
+its coverage is selective and should not be treated as a full canonical register
+source unless the exact scope has been audited.
+
+## Access Surface
+
+StatsBomb identity examples can come from the public Open Data repository, the
+`statsbombpy` wrapper, or licensed commercial APIs. Public docs should prefer
+Open Data IDs and explicitly say when guidance is inferred from Open Data rather
+than a commercial entitlement.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | `competition_id` | Stable inside StatsBomb. Pair with `competition_name` and country/region for human review. |
+| Season | `season_id` under a competition | Stable inside StatsBomb. Not globally unique without competition context in some workflows. |
+| Match | `match_id` | Strong match bridge for covered matches. |
+| Team | `team_id` | Strong team bridge inside StatsBomb data. Check whether a single ID is being used across provider-side historical segmentation. |
+| Player | `player_id` | Strong player bridge inside lineups/events. Corroborate with names, DOB from another authority, and relationship evidence. |
+| Coach or manager | lineup or match metadata surfaces where present | Treat as role evidence. Coverage is less central than player/event data. |
+
+## ID Scheme Notes
+
+StatsBomb Open Data exposes numeric `competition_id`, `season_id`, `match_id`,
+`team_id`, and `player_id` fields, plus event UUIDs. The numeric IDs are stable
+inside the provider dataset but should stay provider-scoped. Do not infer global
+identity from a bare number without provider and dataset context.
+
+## Useful Matching Fields
+
+- Competitions and seasons: IDs, names, country, gender, and season label.
+- Matches: match ID, date, home and away team IDs, score, competition, season,
+  match status, and lineup availability.
+- Teams: team IDs and names from matches, lineups, and events.
+- Players: player IDs, names, team membership in lineups/events, shirt number,
+  position, and event participation.
+
+## Known Quirks
+
+- Open Data coverage is selective. Absence from open data is not evidence that
+  an entity or match does not exist.
+- StatsBomb lineups are strong match-grain relationship evidence but not the
+  same as club or national-team contract membership.
+- Public Open Data may include rich international matches but not full
+  tournament squad or call-up semantics.
+- Names can be display names. Use another attribute authority for DOB where a
+  person bridge requires it.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for StatsBomb identity
+surfaces. Reep Next can cite Open Data ID families and matching cautions, while
+commercial entitlement assumptions, register acceptance policy, private review
+evidence, and derived bridge decisions belong outside football-docs.

package/docs/transfermarkt/identity-surfaces.md

@@ -0,0 +1,69 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# Transfermarkt Identity Surfaces
+
+Transfermarkt is valuable for cross-provider corroboration and public entity
+pages, especially player biographical attributes and competition/team history.
+Its public website shape should not be copied blindly into a register ontology.
+
+## Access Surface
+
+Transfermarkt is primarily a public website surface, not an official public API.
+Use public entity pages, match reports, or licence-safe community exports as
+evidence, and record the public URL plus snapshot date. Do not publish scraper
+state, bypass details, or private mirror paths.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | `wettbewerb` code | Competition pages can model provider-specific containers that should map into a different canonical structure. |
+| Season | competition code plus season year | Usually one page per competition year. Split phases may not have distinct Transfermarkt season IDs. |
+| Match | match or game ID | Strong match bridge where coverage exists. Use date, teams, score, and competition for corroboration. |
+| Team | `verein` ID | Same real team can sometimes appear under multiple provider IDs. Distinguish supplier segmentation from real succession. |
+| Player | `spieler` ID | Useful public player bridge. Strong corroborator when DOB, nationality, birthplace, position, and career context agree. |
+| Coach | staff or manager profile ID | Treat as a person surface with role-specific career evidence, not a separate human identity. |
+
+## ID Scheme Notes
+
+The numeric IDs embedded in public URLs are the bridge surfaces. URL slugs are
+handles and can change without changing the underlying provider ID. Common URL
+families include `spieler` for players, `verein` for teams, `wettbewerb` for
+competitions, and match or game IDs for fixtures. Season query parameters and
+display labels are context, not independent canonical IDs.
+
+## Useful Matching Fields
+
+- Player: name variants, date of birth, birth place, citizenship, height,
+  position, foot, profile aliases, current club, historical clubs, and
+  national-team profile surfaces where available.
+- Team: official name, historical names, country, city, gender where inferable,
+  competition participation, and successor or predecessor context.
+- Match: date, home and away teams, score, attendance, competition, season, and
+  round label.
+- Season: competition code, season year, display label, and match membership.
+
+## Known Quirks
+
+- Transfermarkt sometimes models playoffs, cups, or provider-maintained
+  containers differently from a canonical match feed. For example, a playoff
+  container can corroborate stages without becoming a separate canonical
+  competition.
+- Same-provider duplicate player pages exist. Do not merge by name alone.
+- Team pages can represent supplier-side segmentation, historical successors,
+  phoenix clubs, youth sides, reserve sides, women's teams, or genuine
+  duplicates. Preserve relationship evidence when flattening would make history
+  ambiguous.
+- URL slugs are handles. Numeric IDs are the bridge surface.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for Transfermarkt identity
+surfaces. Reep Next can cite it for URL families, ID scheme notes, and matching
+quirks, but register decisions, mint salts, review outcomes, private mirrors,
+and scraper implementation details belong outside football-docs.

package/docs/wyscout/identity-surfaces.md

@@ -0,0 +1,64 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# Hudl Wyscout Identity Surfaces
+
+Hudl Wyscout exposes structured football entities through competitions,
+seasons, matches, teams, players, coaches, lineups, events, and career-like
+profile fields. Treat its IDs as strong provider bridges, not as proof that its
+ontology is the register ontology.
+
+## Access Surface
+
+Primary access is through licensed Hudl Wyscout APIs or delivered exports.
+Public examples should stay at field-name and shape level unless Hudl has
+published equivalent documentation. Record entitlement scope, export date, and
+whether a fact came from match, event, profile, or career metadata.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | `competitionId` | Strong provider key. Check format, gender, country, and competition type. |
+| Season | `seasonId` | Strong provider key under competition context. |
+| Match | `matchId` | Strong match bridge when date, teams, score, and competition align. |
+| Team | `teamId` | Can represent clubs, national teams, youth, or other sides. Use type/category/gender fields. |
+| Player | `playerId` | Strong person bridge when profile attributes and relationship evidence agree. |
+| Coach or referee | profile IDs in match/team metadata | Treat role-specific IDs as person or official surfaces only after attribute checks. |
+
+## ID Scheme Notes
+
+Wyscout IDs are provider-scoped keys. Store `competitionId`, `seasonId`,
+`matchId`, `teamId`, `playerId`, and profile IDs with provider and snapshot
+metadata, and treat round or stage IDs as provider structure until mapped into a
+target-register stage model.
+
+## Useful Matching Fields
+
+- Match: `matchId`, `competitionId`, `seasonId`, `roundId`, date, home/away
+  teams, score, winner, venue, status, and duration.
+- Team: `teamId`, official name, short name, area, type, category, gender, city,
+  child teams, and image/profile URL.
+- Player: `playerId`, name fields, birth date, birth area, passport area, role,
+  foot, height, gender, current team, and status.
+
+## Known Quirks
+
+- Wyscout's `currentTeamId` is point-in-time profile data. Do not use it as a
+  historical membership edge without a snapshot date.
+- Team `type`, `category`, and `gender` are useful gates, but still require
+  normalisation into the target register vocabulary.
+- Match lineup and event participation can corroborate identity, but does not
+  replace attribute evidence for person bridging.
+- Round and stage IDs are provider structure, not necessarily public ontology.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for Hudl Wyscout identity
+surfaces and field families. Reep Next can cite those facts, but entitlement
+coverage, canonical-source policy, private examples, review outputs, and
+provider-specific bridge decisions belong outside football-docs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "football-docs",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Searchable football data provider documentation for AI coding agents. Like Context7 for football data.",
   "type": "module",
   "mcpName": "io.github.withqwerty/football-docs",
@@ -10,20 +10,6 @@
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "tsc",
-    "prebuild": "npm run check",
-    "check": "tsc --noEmit",
-    "dev": "tsx src/index.ts",
-    "ingest": "tsx src/ingest.ts",
-    "crawl": "tsx src/crawl.ts",
-    "discover": "tsx src/crawl.ts --discover",
-    "lint": "biome check src/",
-    "lint:fix": "biome check --write src/",
-    "prepublishOnly": "npm run build && npm run ingest",
-    "start": "node dist/index.js",
-    "test": "vitest run"
-  },
   "keywords": [
     "football",
     "soccer",
@@ -51,7 +37,8 @@
     "@mozilla/readability": "^0.6.0",
     "better-sqlite3": "^11.9.1",
     "linkedom": "^0.18.12",
-    "turndown": "^7.2.2"
+    "turndown": "^7.2.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.9",
@@ -68,5 +55,18 @@
     "data/docs.db",
     "docs/",
     "providers.json"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prebuild": "pnpm check",
+    "check": "tsc --noEmit",
+    "dev": "tsx src/index.ts",
+    "ingest": "tsx src/ingest.ts",
+    "crawl": "tsx src/crawl.ts",
+    "discover": "tsx src/crawl.ts --discover",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  }
+}

package/providers.json

@@ -50,6 +50,51 @@
       ],
       "last_crawled": null
     },
+    "transfermarkt": {
+      "description": "Public football entity pages for players, teams, competitions, matches, transfers, and market values",
+      "version": null,
+      "package": null,
+      "sources": [
+        { "type": "curated", "note": "Public website identity surfaces and Reep-derived provider-quirk notes" }
+      ],
+      "last_crawled": null
+    },
+    "soccerdonna": {
+      "description": "Public women's football entity pages, match reports, competition pages, player profiles, and staff profiles",
+      "version": null,
+      "package": null,
+      "sources": [
+        { "type": "curated", "note": "Public website identity surfaces and Reep-derived women's football matching notes" }
+      ],
+      "last_crawled": null
+    },
+    "fotmob": {
+      "description": "Consumer-facing football fixtures, teams, competitions, player profiles, lineups, and match statistics",
+      "version": null,
+      "package": null,
+      "sources": [
+        { "type": "curated", "note": "Public website and undocumented endpoint identity-surface notes" }
+      ],
+      "last_crawled": null
+    },
+    "impect": {
+      "description": "Commercial football match and event data provider with team and player identity surfaces in delivered feeds",
+      "version": null,
+      "package": null,
+      "sources": [
+        { "type": "curated", "note": "High-level commercial-provider identity guidance; no proprietary payloads" }
+      ],
+      "last_crawled": null
+    },
+    "skillcorner": {
+      "description": "Commercial tracking and physical-data provider with match, team, and player identity surfaces in delivered feeds",
+      "version": null,
+      "package": null,
+      "sources": [
+        { "type": "curated", "note": "High-level commercial-provider identity guidance; no proprietary tracking payloads" }
+      ],
+      "last_crawled": null
+    },
     "kloppy": {
       "description": "Python library for standardising football data across providers",
       "version": "3.16.0",