mtg_python_deckbuilder/RELEASE_NOTES_TEMPLATE.md

# MTG Python Deckbuilder ${VERSION}

## Highlights
- **Quality & Observability Complete**: Comprehensive structured logging system with event tracking for include/exclude operations providing detailed diagnostics and operational insights.
- **Include/Exclude Cards Feature Complete**: Full implementation with enhanced web UI, intelligent fuzzy matching, color identity validation, and performance optimization. Users can now specify must-include and must-exclude cards with comprehensive EDH format compliance.
- **Enhanced CLI with Type Safety**: Comprehensive CLI enhancement with type indicators, ideal count arguments, and theme tag name support making headless operation more user-friendly and discoverable.
- **Theme Tag Name Selection**: Intelligent theme selection by name instead of index numbers, automatically resolving to correct choices accounting for selection ordering.
- **Enhanced Fuzzy Matching**: Advanced algorithm with 300+ Commander-legal card knowledge base, popular/iconic card prioritization, and dark theme confirmation modal for optimal user experience.
- **Mobile Responsive Design**: Optimized mobile experience with bottom-floating build controls, two-column grid layout, and horizontal scrolling prevention for improved thumb navigation.
- **Enhanced Visual Validation**: List size validation UI with warning icons (⚠️ over-limit, ⚡ approaching limit) and color coding providing clear feedback on usage limits.
- **Performance Optimized**: All operations exceed performance targets with 100% pass rate - exclude filtering 92% under target, UI operations 70% under target, full validation cycle 95% under target.
- **Dual Architecture Support**: Seamless functionality across both web interface (staging system) and CLI (direct build) with proper include injection timing.

## What's new
- **Quality & Observability**
  - Structured logging with event types: EXCLUDE_FILTER, INCLUDE_EXCLUDE_CONFLICT, STRICT_MODE_SUCCESS/FAILURE, INCLUDE_COLOR_VIOLATION
  - Comprehensive diagnostics for include/exclude operations with performance metrics and validation results
  - Enhanced error tracking and operational visibility for debugging and monitoring
- **Enhanced CLI Experience**
  - Type-safe help text with value indicators (PATH, NAME, INT, BOOL) and organized argument groups
  - Ideal count CLI arguments: `--ramp-count`, `--land-count`, `--creature-count`, etc. for deck composition control
  - Theme tag name support: `--primary-tag "Airbending"` instead of `--primary-choice 1` with intelligent resolution
  - Include/exclude CLI parity: `--include-cards`, `--exclude-cards` with semicolon support for comma-containing card names
  - Console summary output with detailed diagnostics and validation results for headless builds
  - Priority system: CLI > JSON Config > Environment Variables > Defaults
- **Enhanced Visual Validation**
  - List size validation UI with visual warning system using icons and color coding
  - Live validation badges showing count/limit status with clear visual indicators
  - Performance-optimized validation with all targets exceeded (100% pass rate)
  - Backward compatibility verification ensuring existing modals/flows unchanged
- **Include/Exclude Lists**
  - Must-include cards (max 10) and must-exclude cards (max 15) with strict/warn enforcement modes
  - Enhanced fuzzy matching algorithm with 300+ Commander-legal card knowledge base
  - Popular cards (184) and iconic cards (102) prioritization for improved matching accuracy
  - Dark theme confirmation modal with card preview and top 3 alternatives for <90% confidence matches
  - **EDH color identity validation**: Automatic checking of included cards against commander color identity with clear illegal status feedback
  - File upload support (.txt) with deduplication and user feedback
  - JSON export/import preserving all include/exclude configuration via permalink system
- **Web Interface Enhancement**
  - Two-column layout with visual distinction: green for includes, red for excludes
  - Chips/tag UI allowing per-card removal with real-time textarea synchronization
  - Enhanced validation endpoint with comprehensive diagnostics and conflict detection
  - Debounced validation (500ms) for improved performance during typing
  - Enter key handling fixes preventing accidental form submission in textareas
  - Mobile responsive design with bottom-floating build controls and two-column grid layout
  - Mobile horizontal scrolling prevention and setup status optimization
  - Expanded mobile viewport breakpoint (720px → 1024px) for broader device compatibility
- **Engine Integration**
  - Include injection after land selection, before creature/spell fill ensuring proper deck composition
  - Exclude re-entry prevention blocking filtered cards from re-entering via downstream heuristics
  - Staging system architecture with custom `__inject_includes__` runner for web UI builds
  - Comprehensive logging and diagnostics for observability and debugging

## Performance Benchmarks (Complete)
- **Exclude filtering**: 4.0ms (target: ≤50ms) - 92% under target ✅
- **Fuzzy matching**: 0.1ms (target: ≤200ms) - 99.9% under target ✅
- **Include injection**: 14.8ms (target: ≤100ms) - 85% under target ✅
- **Full validation cycle**: 26.0ms (target: ≤500ms) - 95% under target ✅
- **UI operations**: 15.0ms (target: ≤50ms) - 70% under target ✅
- **Overall pass rate**: 5/5 (100%) with excellent performance margins

## Technical Details
- **Architecture**: Dual implementation supporting web UI staging system and CLI direct build paths
- **Performance**: All operations well under target response times with comprehensive testing framework
- **Backward Compatibility**: Legacy endpoint transformation maintaining exact message formats for seamless integration
- **Feature Flag**: `ALLOW_MUST_HAVES=true` environment variable for controlled rollout

## Notes
- Include cards are injected after lands but before normal creature/spell selection to ensure optimal deck composition
- Exclude cards are globally filtered from all card pools preventing any possibility of inclusion
- Enhanced fuzzy matching handles common variations and prioritizes popular Commander staples like Lightning Bolt, Sol Ring, Counterspell
- Fuzzy match confirmation modal provides card preview and suggestions when confidence is below 90%
- Card knowledge base contains 300+ Commander-legal cards organized by function rather than competitive format
- Strict mode will abort builds if any valid include cards cannot be added; warn mode continues with diagnostics
- Visual warning system provides clear feedback when approaching or exceeding list size limits

## Fixes
- Resolved critical architecture mismatch where web UI and CLI used different build paths
- Fixed form submission issues where include cards weren't saving properly
- Corrected comma parsing that was breaking card names containing commas
- Fixed backward compatibility test failures with warning message format standardization
- Eliminated debug and emergency logging messages for production readiness