diff --git a/.env.example b/.env.example
index 38e83f2..43dbd8c 100644
--- a/.env.example
+++ b/.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=v2.5.1                 # Matches dockerhub compose.
+APP_VERSION=v2.5.2                 # Matches dockerhub compose.
 
 ############################
 # Theming
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 71cde8f..954e339 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,19 @@ This format follows Keep a Changelog principles and aims for Semantic Versioning
 
 ## [Unreleased]
 ### Summary
+- _No unreleased changes yet_
+
+### Added
+- _None_
+
+### Changed
+- _None_
+
+### Fixed
+- _None_
+
+## [2.5.2] - 2025-10-08
+### Summary
 - Responsiveness tweaks: shared HTMX debounce helper, deferred skeleton microcopy, and containment rules for long card lists.
 - Optimistic include/exclude experience with HTMX caching, prefetch hints, and telemetry instrumentation for must-have interactions.
 - Commander catalog skeleton placeholders and lazy commander art loading to smooth catalog fetch latency.
@@ -24,7 +37,7 @@ This format follows Keep a Changelog principles and aims for Semantic Versioning
 - Commander catalog results wrap in a deferred skeleton list, and commander art lazy-loads via a new `IntersectionObserver` helper in `code/web/static/app.js`.
 - Collapsible accordions for Mana Overview and Test Hand sections defer content loading until expanded.
 - Click-to-pin chart tooltips with consistent corner positioning (lower-left desktop, lower-right mobile) and working copy buttons.
-- Virtualized card lists automatically render only visible items when 12+ cards are present.changes to this project will be documented in this file.
+- Virtualized card lists automatically render only visible items when 12+ cards are present.
 
 ### Changed
 - Commander search and theme picker now intelligently debounce keystrokes, preventing redundant requests while you type.
diff --git a/RELEASE_NOTES_TEMPLATE.md b/RELEASE_NOTES_TEMPLATE.md
index d581a63..1c99b55 100644
--- a/RELEASE_NOTES_TEMPLATE.md
+++ b/RELEASE_NOTES_TEMPLATE.md
@@ -1,13 +1,26 @@
 # MTG Python Deckbuilder ${VERSION}
 
 ### Summary
-- Alternative suggestions in the build wizard now surface the replacement card preview immediately and reload the list after a swap.
+- Builder responsiveness upgrades: smarter HTMX caching, shared debounce helpers, and virtualization hints keep long card lists responsive.
+- Commander catalog now ships skeleton placeholders, lazy commander art loading, and cached default results for faster repeat visits.
+- Deck summary streams via an HTMX fragment while virtualization powers summary lists without loading every row up front.
+- Mana analytics load on demand with collapsible sections and interactive chart tooltips that support click-to-pin comparisons.
 
 ### Added
-- Alternatives panel includes a "New pool" button so you can request a fresh batch of suggestions without rerunning the stage.
+- Skeleton placeholders accept `data-skeleton-label` microcopy and only surface after ~400 ms across the build wizard, stage navigator, and alternatives panel.
+- Must-have toggle API (`/build/must-haves/toggle`), telemetry ingestion route (`/telemetry/events`), and structured logging helpers capture include/exclude beacons.
+- Commander catalog results wrap in a deferred skeleton list while commander art lazy-loads via a new `IntersectionObserver` helper in `code/web/static/app.js`.
+- Collapsible accordions for Mana Overview and Test Hand sections defer heavy analytics until they are expanded.
+- Click-to-pin chart tooltips keep comparisons anchored and add copy-friendly working buttons.
+- Virtualized card lists automatically render only visible items once 12+ cards are present.
 
 ### Changed
-- Alternative suggestion buttons expose role, mana, and rarity metadata to hover previews for better at-a-glance context.
+- Commander search and theme picker now share an intelligent debounce to prevent redundant requests while typing.
+- Card grids adopt modern containment rules to minimize layout recalculations on large decks.
+- Include/exclude buttons respond immediately with optimistic updates, reconciling gracefully if the server disagrees.
+- Frequently accessed views, like the commander catalog default, now pull from an in-memory cache for sub-200 ms reloads.
+- Deck review loads in focused chunks, keeping the initial page lean while analytics stream progressively.
+- Chart hover zones expand to full column width for easier interaction.
 
 ### Fixed
-- Previewing an alternative card now shows the replacement instead of the currently slotted card, and the list refreshes automatically after choosing an alternative.
\ No newline at end of file
+- _None_
diff --git a/docker-compose.yml b/docker-compose.yml
index 6fac0a4..f2c6106 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -107,7 +107,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: "2.5.1"          # Displayed version label (set per release/tag)
+      APP_VERSION: "2.5.2"          # Displayed version label (set per release/tag)
 
       # ------------------------------------------------------------------
       # Misc / Land Selection (Step 7) Environment Tuning
diff --git a/dockerhub-docker-compose.yml b/dockerhub-docker-compose.yml
index 4c841dd..47b2c7f 100644
--- a/dockerhub-docker-compose.yml
+++ b/dockerhub-docker-compose.yml
@@ -109,7 +109,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: "2.5.1"          # Displayed version label (set per release/tag)
+      APP_VERSION: "2.5.2"          # Displayed version label (set per release/tag)
 
       # ------------------------------------------------------------------
       # Misc / Land Selection (Step 7) Environment Tuning
diff --git a/docs/releases/v2.5.2.md b/docs/releases/v2.5.2.md
new file mode 100644
index 0000000..19ab5c1
--- /dev/null
+++ b/docs/releases/v2.5.2.md
@@ -0,0 +1,26 @@
+# MTG Python Deckbuilder v2.5.2
+
+## Summary
+- Builder responsiveness upgrades: smarter HTMX caching, shared debounce helpers, and virtualization hints keep long card lists responsive.
+- Commander catalog now ships skeleton placeholders, lazy commander art loading, and cached default results for faster repeat visits.
+- Deck summary streams via an HTMX fragment while virtualization powers summary lists without loading every row up front.
+- Mana analytics load on demand with collapsible sections and interactive chart tooltips that support click-to-pin comparisons.
+
+## Added
+- Skeleton placeholders accept `data-skeleton-label` microcopy and only surface after ~400 ms across the build wizard, stage navigator, and alternatives panel.
+- Must-have toggle API (`/build/must-haves/toggle`), telemetry ingestion route (`/telemetry/events`), and structured logging helpers capture include/exclude beacons.
+- Commander catalog results wrap in a deferred skeleton list while commander art lazy-loads via a new `IntersectionObserver` helper in `code/web/static/app.js`.
+- Collapsible accordions for Mana Overview and Test Hand sections defer heavy analytics until they are expanded.
+- Click-to-pin chart tooltips keep comparisons anchored and add copy-friendly working buttons.
+- Virtualized card lists automatically render only visible items once 12+ cards are present.
+
+## Changed
+- Commander search and theme picker now share an intelligent debounce to prevent redundant requests while typing.
+- Card grids adopt modern containment rules to minimize layout recalculations on large decks.
+- Include/exclude buttons respond immediately with optimistic updates, reconciling gracefully if the server disagrees.
+- Frequently accessed views, like the commander catalog default, now pull from an in-memory cache for sub-200 ms reloads.
+- Deck review loads in focused chunks, keeping the initial page lean while analytics stream progressively.
+- Chart hover zones expand to full column width for easier interaction.
+
+## Fixed
+- _None_
diff --git a/pyproject.toml b/pyproject.toml
index c27f96e..6c7d729 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mtg-deckbuilder"
-version = "2.5.1"
+version = "2.5.2"
 description = "A command-line tool for building and analyzing Magic: The Gathering decks"
 readme = "README.md"
 license = {file = "LICENSE"}