feat(themes): whitelist governance, synergy cap, docs + tests; feat(random): laid roadwork for random implementation, testing in headless confirmed

DOCKER.md

@@ -88,6 +88,7 @@ Docker Hub (PowerShell) example:
 docker run --rm `
     -p 8080:8080 `
     -e SHOW_LOGS=1 -e SHOW_DIAGNOSTICS=1 -e ENABLE_THEMES=1 -e THEME=system `
+    -e RANDOM_MODES=1 -e RANDOM_UI=1 -e RANDOM_MAX_ATTEMPTS=5 -e RANDOM_TIMEOUT_MS=5000 `
     -v "${PWD}/deck_files:/app/deck_files" `
     -v "${PWD}/logs:/app/logs" `
     -v "${PWD}/csv_files:/app/csv_files" `
@@ -127,6 +128,29 @@ GET http://localhost:8080/healthz  ->  { "status": "ok", "version": "dev", "upti
 
 Theme preference reset (client-side): use the header’s Reset Theme control to clear the saved browser preference; the server default (THEME) applies on next paint.
 
+### Random Modes (alpha) and test dataset override
+
+Enable experimental Random Modes and UI controls in Web runs by setting:
+
+```yaml
+services:
+    web:
+        environment:
+            - RANDOM_MODES=1
+            - RANDOM_UI=1
+            - RANDOM_MAX_ATTEMPTS=5
+            - RANDOM_TIMEOUT_MS=5000
+```
+
+For deterministic tests or development, you can point the app to a frozen dataset snapshot:
+
+```yaml
+services:
+    web:
+        environment:
+            - CSV_FILES_DIR=/app/csv_files/testdata
+```
+
 ## Volumes
 - `/app/deck_files` ↔ `./deck_files`
 - `/app/logs` ↔ `./logs`
@@ -160,6 +184,13 @@ Theme preference reset (client-side): use the header’s Reset Theme control to
 - WEB_TAG_WORKERS=<N> (process count; set based on CPU/memory)
 - WEB_VIRTUALIZE=1 (enable virtualization)
 - SHOW_DIAGNOSTICS=1 (enables diagnostics pages and overlay hotkey `v`)
+- RANDOM_MODES=1 (enable random build endpoints)
+- RANDOM_UI=1 (show Surprise/Theme/Reroll/Share controls)
+- RANDOM_MAX_ATTEMPTS=5 (cap retry attempts)
+- RANDOM_TIMEOUT_MS=5000 (per-build timeout in ms)
+
+Testing/determinism helper (dev):
+- CSV_FILES_DIR=csv_files/testdata — override CSV base dir to a frozen set for tests
 
 ## Manual build/run
 ```powershell