docs(v2): align runtime and operations documentation with compose behavior

docs/runtime-consistency-checklist.md

@@ -0,0 +1,58 @@
+# Runtime Consistency Checklist (v2)
+
+Use this checklist when runtime/docs changes are made.
+
+## Compose and Runtime
+
+- `docker-compose.yml` contains only v2 default runtime services:
+  - `web`, `nginx`, `postgres`
+  - optional `scheduler` profile service
+- `docker-compose.dev.yml` is mutable (source bind mounts allowed for dev only).
+- `docker-compose.release.yml` is settings-focused and keeps release runtime immutable.
+
+## Image/Registry Strategy
+
+- `web` image: `registry.younerd.org/hoopscout/web:${APP_IMAGE_TAG:-latest}`
+- `nginx` image: `registry.younerd.org/hoopscout/nginx:${NGINX_IMAGE_TAG:-latest}`
+- optional scheduler image: `registry.younerd.org/hoopscout/scheduler:${APP_IMAGE_TAG:-latest}`
+
+## Entrypoints
+
+- `entrypoint.sh`:
+  - waits for PostgreSQL
+  - creates snapshot directories
+  - optionally runs `migrate` and `collectstatic` when booting gunicorn
+- `scripts/scheduler.sh`:
+  - runs `run_daily_orchestration` loop
+  - idle-sleeps when `SCHEDULER_ENABLED=0`
+
+## Snapshot Lifecycle
+
+1. Extractor writes snapshots to `incoming`.
+2. `import_snapshots` validates + upserts into PostgreSQL.
+3. Success => file moved to `archive`.
+4. Failure => file moved to `failed`.
+
+## Source Identity Rule
+
+Raw IDs are not global. Imported identities are namespaced by source:
+
+- `Competition`: `(source_name, source_uid)`
+- `Team`: `(source_name, source_uid)`
+- `Player`: `(source_name, source_uid)`
+
+## Legacy Isolation
+
+- `LEGACY_PROVIDER_STACK_ENABLED=0` by default.
+- With default setting:
+  - `apps.providers` is not installed
+  - `/providers/` routes are not mounted
+  - legacy provider settings are not required
+
+## Verification Commands
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.release.yml config
+./scripts/verify_release_topology.sh
+docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm web sh -lc "export PYTHONUSERBASE=/tmp/pyuser && python -m pip install --user -r requirements/dev.txt && python -m pytest -q"
+```