mtg_python_deckbuilder/docs/releases/v4.2.0.md

# MTG Python Deckbuilder v4.2.0

## Summary
Budget Mode: full price-aware deck building with live budget tracking, post-build review, pickup suggestions, and price charts. Also includes multi-copy conflict dialogs, RandomService infrastructure, and stale price warnings.

## Added

### Budget Mode
- Budget configuration in the New Deck modal: total cap, optional per-card ceiling, soft/hard enforcement mode, and pool tolerance
- Card prices shown throughout the build pipeline (list and thumbnail views) with a running budget counter chip
- Over-budget cards highlighted with a yellow/gold border; basic lands excluded from all calculations
- Budget summary bar in deck summary view; budget badge and over-budget panel on saved deck view
- Post-build budget review panel (triggered when total exceeds cap by >10%): lists over-budget cards with up to 3 cheaper alternatives, each with a live Swap button
- "Accept deck as-is" button in soft mode to bypass the review
- Pickups list page (`/decks/pickups?name=`) — affordable cards you don't own yet, sorted by priority tier
- Pool budget filter: cards over the per-card ceiling by more than the pool tolerance are excluded before building; configurable per build (default 15%)
- Controlled by `ENABLE_BUDGET_MODE` environment variable (default: enabled)

### Price Cache Infrastructure
- `price` and `price_updated` columns added to parquet card database via `refresh_prices_parquet()`
- Setup page Refresh button downloads fresh Scryfall bulk data before rebuilding the cache
- Optional auto-refresh (`PRICE_AUTO_REFRESH=1`) and lazy per-card refresh (`PRICE_LAZY_REFRESH=1`, default enabled)
- `POST /api/price/refresh` manual rebuild endpoint
- "Card Price Cache Status" section on the Setup page with last-updated date and Refresh button
- Footer shows price data date alongside Scryfall attribution
- `build-similarity-cache` CI workflow now commits `prices_cache.json` and `prices_cache.json.ts` alongside the parquet

### Price Charts
- Donut/bar chart showing deck spend by card role (9 categories: Land, Ramp, Creature, Card Draw, Removal, Wipe, Protection, Synergy, Other)
- Price histogram showing card count distribution across cost buckets
- Basic lands excluded from all chart calculations

### Stale Price Warnings
- Cards with price data older than 24 hours flagged with a clock indicator (⏱) on card tiles, hover popup, budget review panel, and Pickups page
- If >50% of deck prices are stale, a single banner replaces per-card indicators
- Controlled by `PRICE_STALE_WARNING_HOURS` (default: 24; set to 0 to disable)

### Multi-copy Dialogs
- Include conflict dialog: typing a multi-copy archetype card (e.g., Hare Apparent) in Must Include now prompts for copy count with optional Thrumming Stone checkbox
- Exclude conflict dialog: conflict popup when the same card appears in both the Multi-Copy Package selector and Must Exclude

### RandomService & Diagnostics
- `RandomService` wrapping seeded RNG operations with input validation
- `InvalidSeedError` exception for seed validation failures
- `GET /api/random/diagnostics` endpoint behind `WEB_RANDOM_DIAGNOSTICS=1` flag
- Random Mode documentation in `docs/random_mode/`

## Changed
- **Build Deck button**: "Create" renamed to "Build Deck" in the New Deck modal for consistency with "Quick Build"

## Fixed
- **Stale price banner after refresh**: Refreshing the price cache on the Setup page now correctly clears the stale warning
- **Multi-copy include count**: Archetype card count is now correctly applied when confirmed from the conflict dialog