chore: prepare release 4.1.0

.env.example

@@ -13,7 +13,7 @@
 # HOST=0.0.0.0                       # Uvicorn bind host (only when APP_MODE=web).
 # PORT=8080                          # Uvicorn port.
 # WORKERS=1                          # Uvicorn worker count.
-APP_VERSION=v4.0.1                 # Matches dockerhub compose.
+APP_VERSION=v4.1.0                 # Matches dockerhub compose.
 
 ############################
 # Theming

CHANGELOG.md

@@ -9,6 +9,19 @@ This format follows Keep a Changelog principles and aims for Semantic Versioning
 
 ## [Unreleased]
 ### Added
+_No unreleased changes yet_
+
+### Changed
+_No unreleased changes yet_
+
+### Fixed
+_No unreleased changes yet_
+
+### Removed
+_No unreleased changes yet_
+
+## [4.1.0] - 2026-03-20
+### Added
 - **Deck Builder Theme Selection**: Enhanced theme picker with pool size indicators, smart sorting, and optional grouping
   - **Pool Size Badges**: Numeric card count displayed on all theme chips (recommended + general)
   - **Smart Sorting**: Themes automatically sorted by pool size (descending), then alphabetically
@@ -85,7 +98,10 @@ This format follows Keep a Changelog principles and aims for Semantic Versioning
   - Integrated into web UI setup, CLI tagging, and CI/CD workflows (build-similarity-cache)
 
 ### Fixed
-_No unreleased changes yet_
+- **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)
+  - Requires re-tagging to regenerate parquet files and theme catalog with corrected names
 
 ### Removed
 _No unreleased changes yet_

RELEASE_NOTES_TEMPLATE.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 ### Added
+_No unreleased changes yet_
+
+### Changed
+_No unreleased changes yet_
+
+### Fixed
+_No unreleased changes yet_
+
+### Removed
+_No unreleased changes yet_
+
+## [4.1.0] - 2026-03-20
+### Added
 - **Deck Builder Theme Selection**: Enhanced theme picker with pool size indicators, smart sorting, and optional grouping
   - **Pool Size Badges**: Numeric card count displayed on all theme chips (recommended + general)
   - **Smart Sorting**: Themes automatically sorted by pool size (descending), then alphabetically
@@ -78,7 +91,10 @@
   - Integrated into web UI setup, CLI tagging, and CI/CD workflows (build-similarity-cache)
 
 ### Fixed
-_No unreleased changes yet_
+- **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)
+  - Requires re-tagging to regenerate parquet files and theme catalog with corrected names
 
 ### Removed
 _No unreleased changes yet_

docker-compose.yml

@@ -135,7 +135,7 @@ services:
       # WEB_THEME_FILTER_PREWARM: "0"
       WEB_AUTO_ENFORCE: "0"         # 1=auto-run compliance export after builds
       WEB_CUSTOM_EXPORT_BASE: ""    # Optional: custom base dir for deck export artifacts
-      APP_VERSION: "v4.0.1"         # Displayed version label (set per release/tag)
+      APP_VERSION: "v4.1.0"         # Displayed version label (set per release/tag)
 
       # ------------------------------------------------------------------
       # Misc / Land Selection (Step 7) Environment Tuning

dockerhub-docker-compose.yml

@@ -137,7 +137,7 @@ services:
       # WEB_THEME_FILTER_PREWARM: "0"
       WEB_AUTO_ENFORCE: "0"         # 1=auto-run compliance export after builds
       WEB_CUSTOM_EXPORT_BASE: ""    # Optional: custom base dir for deck export artifacts
-      APP_VERSION: "v4.0.1"         # Displayed version label (set per release/tag)
+      APP_VERSION: "v4.1.0"         # Displayed version label (set per release/tag)
 
       # ------------------------------------------------------------------
       # Misc / Land Selection (Step 7) Environment Tuning

docs/releases/v4.1.0.md

@@ -0,0 +1,71 @@
+# 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

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mtg-deckbuilder"
-version = "4.0.1"
+version = "4.1.0"
 description = "A command-line tool for building and analyzing Magic: The Gathering decks"
 readme = "README.md"
 license = {file = "LICENSE"}