Improve balldontlie query flow and dev container write stability

README.md

@@ -73,6 +73,7 @@ docker compose up --build
 ```
 
 This starts the development-oriented topology (source bind mounts enabled).
+In development, bind-mounted app containers run as `LOCAL_UID`/`LOCAL_GID` from `.env` (set them to your host user/group IDs).
 
 3. If `AUTO_APPLY_MIGRATIONS=0`, run migrations manually:
 
@@ -118,6 +119,7 @@ Notes:
 - In release-style mode, `web`, `celery_worker`, and `celery_beat` run from the built image filesystem.
 - `tailwind` is marked as `dev` profile in release override and is not started unless `--profile dev` is used.
 - `nginx`, `postgres`, and `redis` service naming remains unchanged.
+- Release-style `web`, `celery_worker`, and `celery_beat` explicitly run as container user `10001:10001`.
 
 ## Setup and Run Notes
 
@@ -192,6 +194,12 @@ Build Tailwind once:
 docker compose run --rm web sh -lc 'npm install --no-audit --no-fund && npm run build'
 ```
 
+If you see `Permission denied` writing `static/vendor` or `static/css` in development, fix local file ownership once:
+
+```bash
+sudo chown -R "$(id -u):$(id -g)" static
+```
+
 Run Tailwind in watch mode during development:
 
 ```bash
@@ -317,6 +325,8 @@ 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[]`).
+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).