# MTG Python Deckbuilder v4.1.0

## Summary
Theme system overhaul with comprehensive badge system, advanced filtering, quality dashboard, and pool size indicators. Includes deck builder enhancements with smart theme sorting, optional pool size sections, and improved partner-aware display. Build process modernized to use parquet files with automatic theme stripping integration.

## Added
- **Theme Catalog Badge System**: Three-tier metric visualization with granular display control
  - **Quality Badges**: Editorial quality indicators (Excellent/Good/Fair/Poor) with semantic colors
  - **Pool Size Badges**: Card availability indicators (Vast/Large/Moderate/Small/Tiny) showing total cards per theme
  - **Popularity Badges**: Usage frequency indicators (Very Common/Common/Uncommon/Niche/Rare) based on theme adoption
  - **Badge Feature Flags**: Individual toggle flags for each badge type (SHOW_THEME_QUALITY_BADGES, SHOW_THEME_POOL_BADGES, SHOW_THEME_POPULARITY_BADGES)
  - **Filter Controls**: Dropdown filters and quick-select chips for all three metrics with master toggle (SHOW_THEME_FILTERS)
- **Theme Catalog Filtering**: Advanced filtering system for quality, pool size, and popularity
  - **Filter Dropdowns**: Select-based filters for precise tier selection
  - **Quick Filter Chips**: Single-click filter activation with letter-based shortcuts
  - **Combined Filtering**: Multiple filter types work together with AND logic
  - **Filter Performance**: Backend filtering in both fast path (theme_list.json) and fallback (full index) with sub-200ms response times
- **Theme Quality Dashboard**: Diagnostic dashboard for monitoring catalog health at `/diagnostics/quality`
  - **Quality Distribution**: Visual breakdown of theme counts by tier (Excellent/Good/Fair/Poor)
  - **Top/Bottom 10 Lists**: Best-curated themes and themes needing improvement with actionable suggestions
  - **Protected Access**: Dashboard gated behind SHOW_DIAGNOSTICS=1 flag for admin use
- **Theme Badge Explanations**: Detailed reasoning for quality, pool size, and popularity badges on individual theme pages
  - **Quality Explanations**: Multi-factor breakdown showing synergy breakdown, deck archetype classification, description curation status
  - **Pool Size Explanations**: Card count with contextual guidance on flexibility and optimization potential
  - **Popularity Explanations**: Adoption pattern descriptions explaining why themes have their popularity tier
- **Deck Builder Theme Selection**: Enhanced theme picker with pool size indicators and smart sorting
  - **Pool Size Badges**: Numeric card count displayed on all theme chips (recommended + general)
  - **Smart Sorting**: Themes automatically sorted by pool size (descending), then alphabetically
  - **Pool Size Sections**: Optional grouping of themes into Vast/Large/Moderate/Small/Tiny sections (THEME_POOL_SECTIONS env var)
  - **Partner-Aware Sections**: Partner themes bucketed into correct pool size section
  - **Popup Wizard Parity**: New Deck modal has full feature parity with legacy builder
- **Theme Editorial Quality & Standards**: Complete editorial system for theme catalog curation
  - **Editorial Metadata Fields**: `description_source` (tracks provenance: official/inferred/custom) and `popularity_pinned` (manual tier override)
  - **Enhanced Quality Scoring**: Four-tier system with 0.0-1.0 numerical scores based on uniqueness, duplication, description quality, and metadata completeness
  - **CLI Linter**: `validate_theme_catalog.py --lint` flag with configurable thresholds and actionable suggestions
  - **Editorial Documentation**: Comprehensive guide at `docs/theme_editorial_guide.md`
- **Theme Stripping Configuration**: Configurable minimum card threshold for theme retention
  - **THEME_MIN_CARDS Setting**: Environment variable (default: 5) to strip themes with too few cards
  - **Analysis Tooling**: Scripts to visualize theme distribution and identify stripping candidates
  - **Automatic Integration**: Theme stripping runs automatically in `run_tagging()` after tagging completes

## Changed
- **Build Process Modernization**: Theme catalog generation now reads from parquet files instead of obsolete CSV format
  - Updated `build_theme_catalog.py` and `extract_themes.py` to use parquet data
  - Added THEME_MIN_CARDS filtering directly in build pipeline
  - `theme_list.json` now auto-generated from stripped parquet data after theme stripping
  - Eliminated manual JSON stripping step (JSON is derived artifact, not source of truth)
- **Parquet Theme Stripping**: Strip low-card themes directly from card data files
  - Handles multiple themeTags formats: numpy arrays, lists, and comma/pipe-separated strings
  - Stripped 97 theme tag occurrences from 30,674 cards in `all_cards.parquet`
  - Integrated into web UI setup, CLI tagging, and CI/CD workflows

## Fixed
- **Counter Type Tags**: Fixed leading spaces in theme names for Blood and Hone counter types
  - Corrected ` Blood` to `Blood` and ` Hone` to `Hone` in `tag_constants.py` COUNTER_TYPES list
  - Prevents creation of malformed theme names like ` Blood Counters` (with leading space)

## For Users
- **Better Theme Discovery**: Visual badges help you quickly identify high-quality themes with large card pools
- **Advanced Filtering**: Find exactly what you're looking for with quality, pool size, and popularity filters
- **Informed Decisions**: Pool size badges show how many cards are available for each theme in your commander's colors
- **Quality Dashboard**: Admin tool to monitor theme catalog health and identify improvement opportunities
- **Smart Theme Sorting**: Themes automatically sorted by card availability to help you find the most flexible options first

## Infrastructure
- Theme catalog quality scoring system with four tiers
- Pool size calculation and tier assignment from parquet data
- Advanced filtering system with combined AND logic
- Editorial metadata fields for manual curation overrides
- Automated theme stripping integration in tagging pipeline
- CLI linter for theme quality validation
