feat(v2): implement scoped player search and detail flows

README.md

@@ -181,6 +181,32 @@ docker compose exec web python manage.py createsuperuser
 - app health: `/health/`
 - nginx healthcheck proxies `/health/` to `web`
 
+## Player Search (v2)
+
+Public player search is server-rendered (Django templates) with HTMX partial updates.
+
+Supported filters:
+- free text name search
+- nominal position, inferred role
+- competition, season, team
+- nationality
+- age, height, weight ranges
+- stats thresholds: games, MPG, PPG, RPG, APG, SPG, BPG, TOV, FG%, 3P%, FT%
+
+Search correctness:
+- combined team/competition/season/stat filters are applied to the same `PlayerSeason` context (no cross-row false positives)
+- filtering happens at database level with Django ORM
+
+Search metric semantics:
+- result columns are labeled as **Best Eligible**
+- each displayed metric is `MAX` over eligible player-season rows for that metric in the current filter context
+- 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 `-`
+
+Pagination and sorting:
+- querystring is preserved
+- HTMX navigation keeps URL state in sync with current filters/page/sort
+
 ## GitFlow
 
 Required branch model: