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

README.md

@@ -9,9 +9,8 @@ Current v2 foundation scope in this branch:
 - management-command-driven runtime operations
 - static snapshot directories persisted via Docker named volumes
 - strict JSON snapshot schema + import management command
-
-Out of scope in this step:
-- extractor implementation
+- extractor framework with LBA/BCL/public JSON adapters
+- daily orchestration command and optional scheduler profile
 
 ## Runtime Architecture (v2)
 
@@ -48,6 +47,7 @@ Reserved for future optional scheduler use:
 - `docker-compose.yml`: production-minded baseline runtime (immutable image filesystem)
 - `docker-compose.dev.yml`: development override with source bind mount for `web`
 - `docker-compose.release.yml`: production settings override (`DJANGO_SETTINGS_MODULE=config.settings.production`)
+- `scripts/verify_release_topology.sh`: validates merged release compose has no source-code bind mounts for runtime services
 
 ### Start development runtime
 
@@ -74,6 +74,31 @@ For development override:
 docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile scheduler up -d scheduler
 ```
 
+### Runtime Modes At A Glance
+
+- development (`docker-compose.yml` + `docker-compose.dev.yml`):
+  - mutable source bind mounts for `web` and `scheduler`
+  - optimized for local iteration
+- release-style (`docker-compose.yml` + `docker-compose.release.yml`):
+  - immutable app filesystem for runtime services
+  - production settings enabled for Django
+- scheduler profile:
+  - only starts when `--profile scheduler` is used
+  - if started with `SCHEDULER_ENABLED=0`, scheduler stays in idle sleep mode (no restart loop exit behavior)
+
+### Release Topology Verification
+
+Verify merged release config and immutability:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.release.yml config
+./scripts/verify_release_topology.sh
+```
+
+Verification expectation:
+- `web` and `scheduler` must not bind-mount repository source code in release mode.
+- named volumes for DB/static/media/snapshots remain mounted.
+
 ## Named Volumes
 
 v2 runtime uses named volumes for persistence:
@@ -86,6 +111,11 @@ v2 runtime uses named volumes for persistence:
 
 Development override uses separate dev-prefixed volumes to avoid ownership collisions.
 
+Snapshot volume intent:
+- `snapshots_incoming`: extractor output waiting for import
+- `snapshots_archive`: successfully imported files
+- `snapshots_failed`: schema/processing failures for operator inspection
+
 ## Environment Variables
 
 Use `.env.example` as the source of truth.
@@ -99,6 +129,9 @@ Core groups:
 - daily orchestration vars (`DAILY_ORCHESTRATION_*`)
 - optional legacy provider-sync toggle (`LEGACY_PROVIDER_STACK_ENABLED`)
 
+Operational reference:
+- `docs/runtime-consistency-checklist.md`
+
 ## Snapshot Storage Convention
 
 Snapshot files are expected under:
@@ -199,6 +232,12 @@ Command behavior:
 - moves valid files to archive
 - moves invalid files to failed
 
+Import lifecycle summary:
+1. extractor writes normalized snapshots to `incoming`
+2. `import_snapshots` validates + upserts to PostgreSQL
+3. imported files move to `archive`
+4. invalid files move to `failed` with error details in `ImportFile`
+
 ### Source Identity Namespacing
 
 Raw external IDs are **not globally unique** across basketball data sources. HoopScout v2 uses a namespaced identity for imported entities:
@@ -338,6 +377,7 @@ Notes:
 ## Testing
 
 - runtime `web` image stays lean and may not include `pytest` tooling
+- runtime containers (`web`/`nginx`/`scheduler`) are for serving/orchestration, not preloaded test tooling
 - run tests with the development compose stack (or a dedicated test image/profile) and install dev dependencies first
 - local example (one-off):