feat(v2-api): expose sortable search metrics in player list responses

README.md

@@ -419,6 +419,20 @@ Search metric semantics:
 - different metric columns for one player may come from different eligible seasons
 - when no eligible value exists for a metric in the current context, the UI shows `-`
 
+### API Search Metric Transparency
+
+`GET /api/players/` now exposes sortable metric fields directly in each list row:
+- `ppg_value`
+- `mpg_value`
+
+These fields use the same **best eligible** semantics as UI search. They are computed from eligible
+player-season rows in the current filter context and may be `null` when no eligible data exists.
+
+API list responses also include:
+- `sort`: effective sort key applied
+- `metric_sort_keys`: metric-based sort keys currently supported
+- `metric_semantics`: plain-language metric contract used for sorting/interpretation
+
 Pagination and sorting:
 - querystring is preserved
 - HTMX navigation keeps URL state in sync with current filters/page/sort