chore(release): v2.2.9 misc land variety, land alternatives randomization, scroll flicker fix

.env.example

@@ -1,28 +1,106 @@
-# Copy this file to `.env` and adjust values to your needs.
+######################################################################
+# MTG Python Deckbuilder – Environment Variables Reference
+#
+# Copy this file to `.env` and uncomment the lines you want to override.
+# All lines are commented so copying it is safe; defaults apply otherwise.
+######################################################################
 
-# Set to 'headless' to auto-run the non-interactive mode on container start
-# DECK_MODE=headless
+############################
+# Core Application Modes
+############################
+# DECK_MODE=headless                 # headless|auto|<blank>. When set to 'headless' (or 'auto'), runs non-interactive build on start (CLI entrypoint).
+# APP_MODE=web                       # (Not explicitly set in dockerhub compose; uncomment to force.)
+# HOST=0.0.0.0                       # Uvicorn bind host (only when APP_MODE=web).
+# PORT=8080                          # Uvicorn port.
+# WORKERS=1                          # Uvicorn worker count.
+APP_VERSION=v2.2.9                  # Matches dockerhub compose.
 
-# Optional JSON config path (inside the container)
-# If you mount ./config to /app/config, use:
-# DECK_CONFIG=/app/config/deck.json
+############################
+# Theming
+############################
+THEME=system                        # system|light|dark (initial default; user preference persists in browser).
 
-# Common knobs
-# DECK_COMMANDER=Pantlaza
-# DECK_PRIMARY_CHOICE=2
+############################
+# Paths & Directories (override discovery)
+############################
+# DECK_CONFIG=/app/config/deck.json  # File OR directory. File: run that config. Dir: discover JSON configs. CLI>ENV precedence.
+# DECK_EXPORTS=/app/deck_files       # Where finished deck exports are read by Web UI.
+# OWNED_CARDS_DIR=/app/owned_cards   # Preferred directory for owned inventory uploads.
+# CARD_LIBRARY_DIR=/app/owned_cards  # Back-compat alias for OWNED_CARDS_DIR.
+
+############################
+# Web UI Feature Flags
+############################
+SHOW_SETUP=1                        # dockerhub: SHOW_SETUP="1"
+SHOW_LOGS=1                         # dockerhub: SHOW_LOGS="1"
+SHOW_DIAGNOSTICS=1                  # dockerhub: SHOW_DIAGNOSTICS="1"
+ENABLE_THEMES=1                     # dockerhub: ENABLE_THEMES="1"
+ENABLE_PWA=0                        # dockerhub: ENABLE_PWA="0"
+ENABLE_PRESETS=0                    # dockerhub: ENABLE_PRESETS="0"
+WEB_VIRTUALIZE=1                    # dockerhub: WEB_VIRTUALIZE="1"
+ALLOW_MUST_HAVES=1                  # dockerhub: ALLOW_MUST_HAVES="1"
+
+############################
+# Automation & Performance (Web)
+############################
+WEB_AUTO_SETUP=1                    # dockerhub: WEB_AUTO_SETUP="1"
+WEB_AUTO_REFRESH_DAYS=7             # dockerhub: WEB_AUTO_REFRESH_DAYS="7"
+WEB_TAG_PARALLEL=1                  # dockerhub: WEB_TAG_PARALLEL="1"
+WEB_TAG_WORKERS=2                   # dockerhub: WEB_TAG_WORKERS="4"
+WEB_AUTO_ENFORCE=0                  # dockerhub: WEB_AUTO_ENFORCE="0"
+# WEB_CUSTOM_EXPORT_BASE=           # Custom basename for exports (optional).
+
+############################
+# Headless Export Options
+############################
+# HEADLESS_EXPORT_JSON=1             # 1=export resolved run config JSON alongside CSV/TXT (headless runs only).
+
+############################
+# Commander & Theme Selection (Headless / Env Overrides)
+############################
+# DECK_COMMANDER=Pantlaza, Sun-Favored          # Commander name query.
+# (Index-based theme choices – mutually exclusive with *_TAG names per slot):
+# DECK_PRIMARY_CHOICE=1
 # DECK_SECONDARY_CHOICE=2
-# DECK_TERTIARY_CHOICE=2
-# DECK_ADD_CREATURES=true
-# DECK_ADD_NON_CREATURE_SPELLS=true
-# DECK_ADD_RAMP=true
-# DECK_ADD_REMOVAL=true
-# DECK_ADD_WIPES=true
-# DECK_ADD_CARD_ADVANTAGE=true
-# DECK_ADD_PROTECTION=true
-# DECK_USE_MULTI_THEME=true
-# DECK_ADD_LANDS=true
-# DECK_FETCH_COUNT=3
-# DECK_DUAL_COUNT=
-# DECK_TRIPLE_COUNT=
-# DECK_UTILITY_COUNT=
+# DECK_TERTIARY_CHOICE=3
+# (Name-based theme tags – preferred; resolved to indices automatically):
+# DECK_PRIMARY_TAG=Tokens
+# DECK_SECONDARY_TAG=Treasure
+# DECK_TERTIARY_TAG=Sacrifice
+# DECK_BRACKET_LEVEL=3               # 1–5 Power/Bracket selection.
+
+############################
+# Category Toggles (Spell / Creature / Land Inclusion)
+############################
+# DECK_ADD_LANDS=1                   # Include land-building sequence.
+# DECK_ADD_CREATURES=1               # Add creatures.
+# DECK_ADD_NON_CREATURE_SPELLS=1     # Bulk add for non-creatures (if supported); else individual toggles below.
+# DECK_ADD_RAMP=1
+# DECK_ADD_REMOVAL=1
+# DECK_ADD_WIPES=1
+# DECK_ADD_CARD_ADVANTAGE=1
+# DECK_ADD_PROTECTION=1
+
+############################
+# Land Count Requests / Adjustments
+############################
+# DECK_FETCH_COUNT=3                 # Requested fetch land count.
+# DECK_DUAL_COUNT=                   # Requested dual land count (optional).
+# DECK_TRIPLE_COUNT=                 # Requested triple land count (optional).
+# DECK_UTILITY_COUNT=                # Requested utility land count (optional).
+
+############################
+# Optional Convenience / Misc (normally container-set or not required)
+############################
+PYTHONUNBUFFERED=1                  # Improves real-time log flushing.
+TERM=xterm-256color                 # Terminal color capability.
+DEBIAN_FRONTEND=noninteractive      # Suppress apt UI in Docker builds.
+
+######################################################################
+# Notes
+# - CLI arguments override env vars; env overrides JSON config; JSON overrides defaults.
+# - For include/exclude card functionality enable ALLOW_MUST_HAVES=1 (Web) and use UI or CLI flags.
+# - Path overrides must point to mounted volumes inside the container.
+# - Remove a value or leave it commented to fall back to internal defaults.
+######################################################################