mtg_python_deckbuilder/RELEASE_NOTES_TEMPLATE.md

# MTG Python Deckbuilder ${VERSION}

## Highlights
- Dynamic misc utility land variety: EDHREC keep percentage now randomly rolls between configurable min/max each build (defaults 75%–100%).
- Land alternatives overhaul: land-aware suggestions (basics→basics, non-basics→non-basics) plus randomized 12-card window (random slice of top 60–100) for per-request variety.
- Cleaner mono-color utility land pools: rainbow/any-color filler and fetch lands excluded after their dedicated phases; explicit allow-list preserves strategic exceptions.
- Theme-aware misc land weighting with configurable multipliers (base + per-extra + cap) via new environment overrides.
- Production-friendly diagnostics: misc land debug CSVs gated behind `MISC_LAND_DEBUG` or diagnostics flag (off by default).
- UI polish & stability: eliminated Step 5 bottom-of-grid scroll flicker (overscroll containment + skip virtualization for small grids <80 items).
- Documentation & compose updates: all new tuning variables surfaced in README, compose files, and sample env.

## Added
- Land alternatives: land-only mode with parity filtering (mono-color exclusions, rainbow text heuristics, fetch exclusion, World Tree legality check).
- Randomized land alternative selection: 12 suggestions from a random window size inside the top 60–100 ranked candidates (uncached for variety).
- Dynamic EDHREC keep range: `MISC_LAND_EDHREC_KEEP_PERCENT_MIN/MAX` (falls back to legacy single `MISC_LAND_EDHREC_KEEP_PERCENT` if min/max unset).
- Misc land theme weighting overrides: `MISC_LAND_THEME_MATCH_BASE`, `MISC_LAND_THEME_MATCH_PER_EXTRA`, `MISC_LAND_THEME_MATCH_CAP`.
- Debug gating: `MISC_LAND_DEBUG=1` to emit misc land candidate/post-filter CSVs (otherwise only when diagnostics enabled).

## Changed
- Fetch lands fully excluded from misc land (utility) step; they are handled earlier and no longer appear as filler.
- Mono-color pass prunes broad rainbow/any-color lands (except allow-list) using expanded text phrase heuristics.
- Alternatives endpoint skips caching for land role to preserve per-request randomness; non-land roles retain cache.
- Compose / README / .env example updated with new land tuning variables.
- Virtualization system now skips small grids (<80 items) to reduce overhead and prevent layout-induced scroll snapping.

## Fixed
- Step 5 scroll flicker / bounce when reaching bottom of short grids (overscroll containment + virtualization threshold).
- Random land alternatives previously surfacing excluded or fetch lands—now aligned with misc step filters.

## Environment Variables (new / updated)
| Variable | Purpose | Default |
|----------|---------|---------|
| MISC_LAND_EDHREC_KEEP_PERCENT_MIN | Lower bound for dynamic EDHREC keep % (0–1) | 0.75 |
| MISC_LAND_EDHREC_KEEP_PERCENT_MAX | Upper bound for dynamic EDHREC keep % (0–1) | 1.0 |
| MISC_LAND_EDHREC_KEEP_PERCENT | Legacy single fixed keep % (fallback) | 0.80 |
| MISC_LAND_DEBUG | Emit misc land debug CSVs | Off |
| MISC_LAND_THEME_MATCH_BASE | Base multiplier for first theme match | 1.4 |
| MISC_LAND_THEME_MATCH_PER_EXTRA | Increment per additional matching theme | 0.15 |
| MISC_LAND_THEME_MATCH_CAP | Cap on total theme multiplier | 2.0 |

## Upgrade Notes
1. No migration steps required; defaults mirror prior behavior but introduce controlled randomness for utility land variety.
2. To restore pre-random behavior, set MIN=MAX=1.0 (or rely on legacy `MISC_LAND_EDHREC_KEEP_PERCENT`).
3. If deterministic land alternatives are needed for testing, consider temporarily disabling randomness (future flag can be added).
4. To analyze utility land selection, enable diagnostics or set `MISC_LAND_DEBUG=1` before running a build; CSVs appear under `logs/` (or diagnostic export path) only when enabled.

## Testing & Quality
- Existing fast test suite passes (include/exclude + summary utilities). Additional targeted tests for randomized window selection can be added in a follow-up if deterministic mode is introduced.
- Manual validation: multiple builds confirm varied utility land pools and land alternatives without fetch/rainbow leakage.

## Future Follow-ups (Optional)
- Deterministic toggle for land alternative randomization (e.g., `LAND_ALTS_DETERMINISTIC=1`).
- Unit tests focusing on edge-case mono-color filtering and theme weighting bounds.
- Potential adaptive virtualization row-height measurement per column for further smoothness (currently fixed estimate works acceptably).