Align balldontlie OpenAPI integration and clarify search metric semantics

README.md

@@ -135,7 +135,11 @@ Notes:
 
 - The server-rendered player search page (`/players/`) and read-only players API (`/api/players/`) use the same search form and ORM filter service.
 - Sorting/filter semantics are aligned across UI, HTMX partial refreshes, and API responses.
-- Statistical metric annotations are always computed for UI result tables, and only computed for API requests when metric-based sorting is requested.
+- Search result metrics in the UI table use **best eligible semantics**:
+  - each metric (Games, MPG, PPG, RPG, APG) is the maximum value across eligible player-season rows
+  - eligibility is scoped by the active season/team/competition/stat filters
+  - different displayed metrics for one player can come from different eligible rows
+- Metric-based API sorting (`ppg_*`, `mpg_*`) uses the same best-eligible semantics as UI search.
 
 ## Docker Volumes and Persistence
 
@@ -325,7 +329,7 @@ Provider backend is selected via environment variables:
 - `PROVIDER_DEFAULT_NAMESPACE` can override backend mapping explicitly
 
 The balldontlie adapter is NBA-centric and intended as MVP ingestion only. The provider abstraction remains ready for future multi-league providers (for example Sportradar or FIBA GDAP).
-The adapter uses balldontlie getting-started query style (`/nba/v1`, cursor pagination, stats by `game_ids[]`).
+The adapter follows the published balldontlie OpenAPI contract: server `https://api.balldontlie.io`, NBA endpoints under `/nba/v1/*`, cursor pagination via `meta.next_cursor`, and `stats` ingestion filtered by `seasons[]`.
 Some balldontlie plans do not include stats endpoints; set `PROVIDER_BALLDONTLIE_STATS_STRICT=0` (default) to ingest players/teams/seasons even when stats are unauthorized.
 
 Provider normalization details and explicit adapter assumptions are documented in [docs/provider-normalization.md](docs/provider-normalization.md).