From c4ab4a9153ce3c101f4322d0560a5428e3a7f338 Mon Sep 17 00:00:00 2001
From: neon <18559658+neonsolstice@users.noreply.github.com>
Date: Thu, 18 Jun 2026 03:36:10 +0000
Subject: [PATCH] feat: add in-app release notes viewer

Introduces a new feature to fetch, parse, and display app release notes
and update highlights directly within the UI.

- Backend: Adds the `release-notes` module to fetch GitHub releases
  and parse markdown highlight sections.
- Frontend: Adds the `WhatsNew` dialog and view, including custom
  markdown rendering and an image lightbox for update media.
- Tools: Adds validation scripts (`whats-new-lint`, `whats-new-preview`)
  to ensure release content parses correctly before publication.
---
 client/src/App.vue                            |  26 +-
 client/src/components/AppHeader.vue           |  76 +++--
 client/src/components/AppSidebar.vue          |  14 +-
 client/src/composables/useModal.ts            |  76 +++++
 .../src/features/auth/composables/useAuth.ts  |   2 +
 .../components/NotificationPreferences.vue    |  40 ++-
 .../src/features/whats-new/WhatsNewDialog.vue | 157 ++++++++++
 .../src/features/whats-new/WhatsNewView.vue   | 283 ++++++++++++++++++
 .../whats-new/components/HighlightIcon.vue    |  20 ++
 .../whats-new/components/HighlightItem.vue    |  93 ++++++
 .../whats-new/components/ImageLightbox.vue    |  92 ++++++
 .../whats-new/composables/useWhatsNew.test.ts |  25 ++
 .../whats-new/composables/useWhatsNew.ts      | 154 ++++++++++
 .../features/whats-new/lib/lightbox-state.ts  |  13 +
 .../features/whats-new/lib/markdown.test.ts   |  34 +++
 client/src/features/whats-new/lib/markdown.ts | 118 ++++++++
 .../whats-new/lib/whats-new.logic.test.ts     |  64 ++++
 .../features/whats-new/lib/whats-new.logic.ts |  58 ++++
 client/src/router/index.ts                    |   6 +
 docs/RELEASE_PROCESS.md                       |   6 +
 docs/whats-new-authoring-guide.md             | 128 ++++++++
 docs/whats-new-template.md                    |   8 +
 packages/types/src/index.ts                   |   1 +
 packages/types/src/release-notes.ts           |  39 +++
 release.config.js                             |  42 ++-
 server/package.json                           |   4 +
 server/src/app.module.ts                      |   2 +
 server/src/config/config.test.ts              |   6 +
 server/src/config/config.ts                   |   2 +
 server/src/config/env.validation.ts           |   8 +
 .../dto/release-notes-query.dto.ts            |  13 +
 .../release-notes/highlights.lint.test.ts     |  87 ++++++
 .../modules/release-notes/highlights.lint.ts  |  75 +++++
 .../release-notes/highlights.parser.test.ts   | 207 +++++++++++++
 .../release-notes/highlights.parser.ts        | 186 ++++++++++++
 .../release-notes/lucide-icon-names.ts        |  11 +
 .../release-notes/release-notes.constants.ts  |  26 ++
 .../release-notes/release-notes.controller.ts |  22 ++
 .../release-notes/release-notes.module.ts     |  12 +
 .../release-notes.service.test.ts             | 116 +++++++
 .../release-notes/release-notes.service.ts    | 254 ++++++++++++++++
 .../user-preferences.controller.ts            |  12 +
 .../user-preferences.service.test.ts          |  26 ++
 .../user-preferences.service.ts               |  49 +++
 server/src/scripts/README.md                  |  37 +++
 server/src/scripts/whats-new-check.ts         |  50 ++++
 server/src/scripts/whats-new-images.ts        | 133 ++++++++
 server/src/scripts/whats-new-lint.ts          |  92 ++++++
 server/src/scripts/whats-new-preview.ts       | 136 +++++++++
 49 files changed, 3110 insertions(+), 31 deletions(-)
 create mode 100644 client/src/composables/useModal.ts
 create mode 100644 client/src/features/whats-new/WhatsNewDialog.vue
 create mode 100644 client/src/features/whats-new/WhatsNewView.vue
 create mode 100644 client/src/features/whats-new/components/HighlightIcon.vue
 create mode 100644 client/src/features/whats-new/components/HighlightItem.vue
 create mode 100644 client/src/features/whats-new/components/ImageLightbox.vue
 create mode 100644 client/src/features/whats-new/composables/useWhatsNew.test.ts
 create mode 100644 client/src/features/whats-new/composables/useWhatsNew.ts
 create mode 100644 client/src/features/whats-new/lib/lightbox-state.ts
 create mode 100644 client/src/features/whats-new/lib/markdown.test.ts
 create mode 100644 client/src/features/whats-new/lib/markdown.ts
 create mode 100644 client/src/features/whats-new/lib/whats-new.logic.test.ts
 create mode 100644 client/src/features/whats-new/lib/whats-new.logic.ts
 create mode 100644 docs/whats-new-authoring-guide.md
 create mode 100644 docs/whats-new-template.md
 create mode 100644 packages/types/src/release-notes.ts
 create mode 100644 server/src/modules/release-notes/dto/release-notes-query.dto.ts
 create mode 100644 server/src/modules/release-notes/highlights.lint.test.ts
 create mode 100644 server/src/modules/release-notes/highlights.lint.ts
 create mode 100644 server/src/modules/release-notes/highlights.parser.test.ts
 create mode 100644 server/src/modules/release-notes/highlights.parser.ts
 create mode 100644 server/src/modules/release-notes/lucide-icon-names.ts
 create mode 100644 server/src/modules/release-notes/release-notes.constants.ts
 create mode 100644 server/src/modules/release-notes/release-notes.controller.ts
 create mode 100644 server/src/modules/release-notes/release-notes.module.ts
 create mode 100644 server/src/modules/release-notes/release-notes.service.test.ts
 create mode 100644 server/src/modules/release-notes/release-notes.service.ts
 create mode 100644 server/src/scripts/README.md
 create mode 100644 server/src/scripts/whats-new-check.ts
 create mode 100644 server/src/scripts/whats-new-images.ts
 create mode 100644 server/src/scripts/whats-new-lint.ts
 create mode 100644 server/src/scripts/whats-new-preview.ts

diff --git a/client/src/App.vue b/client/src/App.vue
index 38112bda3..93c1b9f15 100644
--- a/client/src/App.vue
+++ b/client/src/App.vue
@@ -1,16 +1,39 @@
 <script setup lang="ts">
-import { computed, provide } from 'vue'
+import { computed, provide, watch } from 'vue'
+import { useRoute } from 'vue-router'
 import { INIT_OPTIONS_KEY, THEME_KEY } from 'vue-echarts'
 import { useChangePasswordDialog } from '@/composables/useChangePasswordDialog'
 import { useThemeStore } from '@/stores/theme'
 import { getBookorbitThemeName, initChartThemes } from '@/lib/echarts'
 import ChangePasswordDialog from '@/features/auth/ChangePasswordDialog.vue'
+import WhatsNewDialog from '@/features/whats-new/WhatsNewDialog.vue'
+import { useWhatsNew } from '@/features/whats-new/composables/useWhatsNew'
+import { useAuth } from '@/features/auth/composables/useAuth'
 import { Toaster } from '@/components/ui/sonner'
 import { TooltipProvider } from '@/components/ui/tooltip'
 
 const { isOpen } = useChangePasswordDialog()
 const themeStore = useThemeStore()
 
+const route = useRoute()
+const { user } = useAuth()
+const { popupOpen, evaluate, syncPopup } = useWhatsNew()
+
+watch(
+  () => user.value,
+  async (current) => {
+    if (!current) return
+    await evaluate()
+    syncPopup(route.name as string | undefined)
+  },
+  { immediate: true },
+)
+
+watch(
+  () => route.name,
+  (name) => syncPopup(name as string | undefined),
+)
+
 initChartThemes()
 
 provide(INIT_OPTIONS_KEY, { renderer: 'svg' })
@@ -28,6 +51,7 @@ provide(
       </Transition>
     </router-view>
     <ChangePasswordDialog v-if="isOpen" />
+    <WhatsNewDialog v-if="popupOpen" />
     <Toaster rich-colors position="bottom-right" :visible-toasts="5" :gap="8" />
   </TooltipProvider>
 </template>
diff --git a/client/src/components/AppHeader.vue b/client/src/components/AppHeader.vue
index cd97ae30b..126923f7f 100644
--- a/client/src/components/AppHeader.vue
+++ b/client/src/components/AppHeader.vue
@@ -17,6 +17,7 @@ import {
   BadgeQuestionMark,
   Star,
   ExternalLink,
+  Sparkles,
 } from 'lucide-vue-next'
 import { useRouter, useRoute } from 'vue-router'
 import { toast } from 'vue-sonner'
@@ -50,6 +51,7 @@ import { useLibraryUploadEvents } from '@/features/library/composables/useLibrar
 import { useBookDockSummary } from '@/features/book-dock/composables/useBookDockSummary'
 import NotificationSheet from '@/features/notifications/components/NotificationSheet.vue'
 import { useNotifications } from '@/features/notifications/composables/useNotifications'
+import { useWhatsNew } from '@/features/whats-new/composables/useWhatsNew'
 import UserAvatar from '@/components/UserAvatar.vue'
 import { DEFAULT_FORMAT_PRIORITY } from '@bookorbit/types'
 import { useThemeStore } from '@/stores/theme'
@@ -63,6 +65,7 @@ const { hasPermission, isDemoRestrictedAccount } = usePermissions()
 const { onLibraryUploadCompleted } = useLibraryUploadEvents()
 const { summary: bookDockSummary, fetchSummary: fetchBookDockSummary, subscribe: subscribeBookDockSummary } = useBookDockSummary()
 const { subscribe: subscribeNotifications } = useNotifications()
+const { hasUnseen: hasUnseenWhatsNew } = useWhatsNew()
 const themeStore = useThemeStore()
 const documentationUrl = 'https://bookorbit.app/what-is-bookorbit.html'
 const githubRepositoryUrl = 'https://github.com/bookorbit/bookorbit'
@@ -98,6 +101,10 @@ function navigateToSettings() {
   router.push({ name: 'settings-libraries' })
 }
 
+function navigateToWhatsNew() {
+  router.push({ name: 'whats-new' })
+}
+
 const uploadOpen = ref(false)
 
 const searchFocused = ref(false)
@@ -547,6 +554,21 @@ function formatBadgeStyle(fmt: string) {
               <Settings :size="15" class="mr-2 text-muted-foreground" />
               Settings
             </DropdownMenuItem>
+
+            <DropdownMenuSeparator />
+
+            <DropdownMenuItem @click="navigateToWhatsNew">
+              <Sparkles :size="15" class="mr-2 text-muted-foreground" />
+              What's New
+              <span v-if="hasUnseenWhatsNew" class="ml-auto h-1.5 w-1.5 rounded-full bg-primary" aria-label="New" />
+            </DropdownMenuItem>
+            <DropdownMenuItem as-child>
+              <a :href="documentationUrl" target="_blank" rel="noopener noreferrer">
+                <BadgeQuestionMark :size="15" class="mr-2 text-muted-foreground" />
+                Documentation
+                <ExternalLink :size="12" class="ml-auto text-muted-foreground" />
+              </a>
+            </DropdownMenuItem>
           </DropdownMenuContent>
         </DropdownMenu>
 
@@ -650,23 +672,43 @@ function formatBadgeStyle(fmt: string) {
         <div class="hidden md:block h-4 w-px bg-foreground/20" />
         <div class="hidden md:flex items-center gap-2.5">
           <Tooltip>
-            <TooltipTrigger as-child>
-              <Button
-                as-child
-                data-tour="documentation-link"
-                variant="ghost"
-                size="icon"
-                :class="[
-                  'h-8 w-8 border border-primary/35 text-foreground/70 hover:border-primary/70 hover:text-foreground transition-colors',
-                  iconRadiusClass,
-                ]"
-              >
-                <a :href="documentationUrl" target="_blank" rel="noopener noreferrer">
-                  <BadgeQuestionMark :size="15" />
-                </a>
-              </Button>
-            </TooltipTrigger>
-            <TooltipContent>Documentation</TooltipContent>
+            <DropdownMenu>
+              <TooltipTrigger as-child>
+                <DropdownMenuTrigger as-child>
+                  <Button
+                    data-tour="documentation-link"
+                    variant="ghost"
+                    size="icon"
+                    :class="[
+                      'relative h-8 w-8 border border-primary/35 text-foreground/70 hover:border-primary/70 hover:text-foreground transition-colors',
+                      iconRadiusClass,
+                    ]"
+                  >
+                    <BadgeQuestionMark :size="15" />
+                    <span
+                      v-if="hasUnseenWhatsNew"
+                      class="absolute -right-0.5 -top-0.5 h-2 w-2 rounded-full bg-primary ring-2 ring-background"
+                      aria-label="New release notes available"
+                    />
+                  </Button>
+                </DropdownMenuTrigger>
+              </TooltipTrigger>
+              <DropdownMenuContent align="end" class="w-48">
+                <DropdownMenuItem as-child>
+                  <a :href="documentationUrl" target="_blank" rel="noopener noreferrer">
+                    <BadgeQuestionMark :size="14" class="mr-2 text-muted-foreground" />
+                    Documentation
+                    <ExternalLink :size="12" class="ml-auto text-muted-foreground" />
+                  </a>
+                </DropdownMenuItem>
+                <DropdownMenuItem @click="navigateToWhatsNew">
+                  <Sparkles :size="14" class="mr-2 text-muted-foreground" />
+                  What's New
+                  <span v-if="hasUnseenWhatsNew" class="ml-auto h-1.5 w-1.5 rounded-full bg-primary" aria-label="New" />
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+            <TooltipContent>Help</TooltipContent>
           </Tooltip>
 
           <Tooltip>
diff --git a/client/src/components/AppSidebar.vue b/client/src/components/AppSidebar.vue
index 078d68a45..191733afc 100644
--- a/client/src/components/AppSidebar.vue
+++ b/client/src/components/AppSidebar.vue
@@ -32,6 +32,7 @@ import { useLibraryCreationRedirect } from '@/features/library/composables/useLi
 import { useThemeStore } from '@/stores/theme'
 import { useAppInfo } from '@/features/settings/composables/useAppInfo'
 import { buildSidebarVersionUi } from '@/components/sidebar/versionUi'
+import { useWhatsNew } from '@/features/whats-new/composables/useWhatsNew'
 
 function resolveIcon(name: string | null | undefined, fallback: Component): Component {
   if (name && name in Icons) return (Icons as Record<string, unknown>)[name] as Component
@@ -58,6 +59,7 @@ const { subscribeLibrary, getProgress, progressMap } = useScanProgress()
 const { handleLibraryCreated } = useLibraryCreationRedirect()
 const themeStore = useThemeStore()
 const { version, updateAvailable, latestVersion, loadAppInfo } = useAppInfo()
+const { hasUnseen: hasUnseenWhatsNew } = useWhatsNew()
 
 const iconRadiusClass = computed(() => (themeStore.radius === 'sharp' ? 'rounded-none' : 'rounded-full'))
 const versionUi = computed(() => {
@@ -441,16 +443,10 @@ onUnmounted(() => stopLibraryUploadListener())
     <SidebarFooter v-if="versionUi.currentLabel" class="border-t border-sidebar-border/60">
       <div class="px-2 py-2 group-data-[collapsible=icon]:hidden">
         <div class="flex flex-wrap items-center justify-center gap-2 text-center text-[12px] font-medium leading-none text-sidebar-foreground/80">
-          <a
-            v-if="versionUi.currentHref"
-            :href="versionUi.currentHref"
-            target="_blank"
-            rel="noopener noreferrer"
-            class="transition-colors hover:text-sidebar-foreground"
-          >
+          <RouterLink to="/whats-new" class="inline-flex items-center gap-1.5 transition-colors hover:text-sidebar-foreground">
             {{ versionUi.currentLabel }}
-          </a>
-          <span v-else>{{ versionUi.currentLabel }}</span>
+            <span v-if="hasUnseenWhatsNew" class="h-1.5 w-1.5 rounded-full bg-primary" aria-label="New release notes available" />
+          </RouterLink>
 
           <span v-if="versionUi.showLatest" class="text-sidebar-foreground/45">•</span>
 
diff --git a/client/src/composables/useModal.ts b/client/src/composables/useModal.ts
new file mode 100644
index 000000000..b35ae756d
--- /dev/null
+++ b/client/src/composables/useModal.ts
@@ -0,0 +1,76 @@
+import { nextTick, onBeforeUnmount, onMounted, type Ref } from 'vue'
+
+interface UseModalOptions {
+  /** The modal panel root. The focus trap cycles within it and it receives initial focus as a fallback. */
+  container: Ref<HTMLElement | null>
+  /** Invoked when Escape is pressed (unless `disabled` returns true). */
+  onClose: () => void
+  /** Makes this modal inert (no Escape, no focus trap) while true, e.g. when a nested modal is open above it. */
+  disabled?: () => boolean
+  /** Element to focus on open; falls back to the first focusable element in the container. */
+  initialFocus?: Ref<HTMLElement | null>
+}
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',')
+
+/**
+ * Shared modal behaviour for hand-rolled dialogs: body scroll lock, focus save/restore,
+ * Escape-to-close, and a Tab focus trap. Wire it once per modal component in setup.
+ */
+export function useModal(options: UseModalOptions): void {
+  let previouslyFocused: HTMLElement | null = null
+  let previousOverflow = ''
+
+  function focusable(): HTMLElement[] {
+    const root = options.container.value
+    if (!root) return []
+    return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter((el) => el.getClientRects().length > 0)
+  }
+
+  function handleKeydown(event: KeyboardEvent): void {
+    if (options.disabled?.()) return
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      options.onClose()
+      return
+    }
+    if (event.key !== 'Tab') return
+    const elements = focusable()
+    const first = elements[0]
+    const last = elements[elements.length - 1]
+    if (!first || !last) return
+    const active = document.activeElement as HTMLElement | null
+    const outside = !options.container.value?.contains(active)
+    if (event.shiftKey && (active === first || outside)) {
+      event.preventDefault()
+      last.focus()
+    } else if (!event.shiftKey && (active === last || outside)) {
+      event.preventDefault()
+      first.focus()
+    }
+  }
+
+  onMounted(() => {
+    previouslyFocused = document.activeElement as HTMLElement | null
+    previousOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    window.addEventListener('keydown', handleKeydown)
+    void nextTick(() => {
+      const target = options.initialFocus?.value ?? focusable()[0] ?? options.container.value
+      target?.focus()
+    })
+  })
+
+  onBeforeUnmount(() => {
+    window.removeEventListener('keydown', handleKeydown)
+    document.body.style.overflow = previousOverflow
+    previouslyFocused?.focus?.()
+  })
+}
diff --git a/client/src/features/auth/composables/useAuth.ts b/client/src/features/auth/composables/useAuth.ts
index a066faca9..d2bc327df 100644
--- a/client/src/features/auth/composables/useAuth.ts
+++ b/client/src/features/auth/composables/useAuth.ts
@@ -7,6 +7,7 @@ import { cancelPendingThemeSync, initThemeSync, loadFromServer } from '@/composa
 import { useSetupStatus } from './useSetupStatus'
 import { disconnectAuthorEnrichmentSocket } from '@/features/settings/composables/useAuthorEnrichmentStatus'
 import { disconnectBookMetadataFetchSocket } from '@/features/book-metadata-fetch/composables/useBookMetadataFetchStatus'
+import { resetWhatsNew } from '@/features/whats-new/composables/useWhatsNew'
 
 const SESSION_REFRESH_INTERVAL_MS = 5 * 60 * 1000
 
@@ -52,6 +53,7 @@ function clearAuth() {
   setAccessToken(null)
   disconnectAuthorEnrichmentSocket()
   disconnectBookMetadataFetchSocket()
+  resetWhatsNew()
 }
 
 setOnAuthFailure(() => {
diff --git a/client/src/features/notifications/components/NotificationPreferences.vue b/client/src/features/notifications/components/NotificationPreferences.vue
index b2c21634c..c21df2b74 100644
--- a/client/src/features/notifications/components/NotificationPreferences.vue
+++ b/client/src/features/notifications/components/NotificationPreferences.vue
@@ -1,18 +1,32 @@
 <script setup lang="ts">
-import { computed, ref } from 'vue'
+import { computed, onMounted, ref } from 'vue'
 import { toast } from 'vue-sonner'
 import { Save } from 'lucide-vue-next'
 import { NOTIFICATION_CATEGORIES, NOTIFICATION_CATEGORY_LABELS, type NotificationCategory, type NotificationPreferences } from '@bookorbit/types'
 import { useAuth } from '@/features/auth/composables/useAuth'
+import { useWhatsNew } from '@/features/whats-new/composables/useWhatsNew'
 import { api } from '@/lib/api'
 import SettingsPageHeader from '@/features/settings/SettingsPageHeader.vue'
 
 const props = withDefaults(defineProps<{ embedded?: boolean }>(), { embedded: false })
 
 const { user, me } = useAuth()
+const { popupEnabled, setPopupEnabled, loadPrefs } = useWhatsNew()
 
 const saving = ref(false)
 
+onMounted(() => {
+  void loadPrefs()
+})
+
+async function handleWhatsNewToggle() {
+  try {
+    await setPopupEnabled(!popupEnabled.value)
+  } catch {
+    toast.error('Failed to save preference')
+  }
+}
+
 const preferences = ref<NotificationPreferences>({})
 
 function loadFromUser() {
@@ -122,5 +136,29 @@ async function handleSave() {
         <span v-if="hasChanges" class="text-xs text-muted-foreground">Unsaved changes</span>
       </div>
     </section>
+
+    <section class="rounded-lg border border-border bg-card p-4 md:p-5 shadow-xs">
+      <div class="flex items-center justify-between gap-4 py-1.5">
+        <div class="min-w-0">
+          <p class="text-sm text-foreground">Show "What's New" after updates</p>
+          <p class="text-xs text-muted-foreground">
+            A popup highlighting new features after the app updates. The archive stays available either way.
+          </p>
+        </div>
+        <button
+          type="button"
+          role="switch"
+          :aria-checked="popupEnabled"
+          class="relative inline-flex h-5 w-9 shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50 focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+          :class="popupEnabled ? 'bg-primary' : 'bg-muted-foreground/30'"
+          @click="handleWhatsNewToggle"
+        >
+          <span
+            class="pointer-events-none block h-4 w-4 rounded-full bg-white shadow-xs ring-0 transition-transform"
+            :class="popupEnabled ? 'translate-x-4' : 'translate-x-0'"
+          />
+        </button>
+      </div>
+    </section>
   </div>
 </template>
diff --git a/client/src/features/whats-new/WhatsNewDialog.vue b/client/src/features/whats-new/WhatsNewDialog.vue
new file mode 100644
index 000000000..a2bf21d0c
--- /dev/null
+++ b/client/src/features/whats-new/WhatsNewDialog.vue
@@ -0,0 +1,157 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { ArrowRight, ChevronDown, ExternalLink, Sparkles, X } from 'lucide-vue-next'
+import { useModal } from '@/composables/useModal'
+import { useWhatsNew } from './composables/useWhatsNew'
+import { formatReleaseDate } from './lib/whats-new.logic'
+import { anyLightboxOpen } from './lib/lightbox-state'
+import HighlightItem from './components/HighlightItem.vue'
+
+const { version, releases, hasMore, acknowledge, remindLater } = useWhatsNew()
+
+const expanded = ref(new Set<string>(releases.value[0] ? [releases.value[0].version] : []))
+const panel = ref<HTMLElement | null>(null)
+const ackButton = ref<HTMLButtonElement | null>(null)
+
+function isExpanded(version: string): boolean {
+  return expanded.value.has(version)
+}
+
+function toggle(version: string): void {
+  const next = new Set(expanded.value)
+  if (next.has(version)) next.delete(version)
+  else next.add(version)
+  expanded.value = next
+}
+
+function handleAck(): void {
+  void acknowledge()
+}
+
+function handleLater(): void {
+  remindLater()
+}
+
+useModal({
+  container: panel,
+  onClose: remindLater,
+  disabled: () => anyLightboxOpen.value,
+  initialFocus: ackButton,
+})
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      class="fixed inset-0 z-[75] flex items-end justify-center bg-black/50 motion-safe:animate-in motion-safe:fade-in sm:items-center sm:px-4"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="whats-new-title"
+      @click.self="handleLater"
+    >
+      <div
+        ref="panel"
+        class="flex max-h-[90vh] w-full max-w-2xl flex-col rounded-t-2xl border border-border bg-card shadow-xl motion-safe:animate-in motion-safe:slide-in-from-bottom-4 sm:rounded-2xl"
+      >
+        <header class="relative overflow-hidden border-b border-border px-5 pb-4 pt-5">
+          <div
+            class="pointer-events-none absolute inset-0"
+            style="
+              background-image: radial-gradient(ellipse 90% 70% at 0% -20%, color-mix(in oklch, var(--primary) 14%, transparent) 0%, transparent 70%);
+            "
+          />
+          <div class="relative flex items-start justify-between gap-3">
+            <div class="flex items-center gap-3">
+              <span class="flex h-10 w-10 items-center justify-center rounded-full bg-primary/15 text-primary">
+                <Sparkles :size="22" />
+              </span>
+              <div>
+                <h2 id="whats-new-title" class="text-lg font-semibold tracking-tight text-foreground">What's New</h2>
+                <p class="text-sm text-muted-foreground">
+                  <template v-if="version">Version {{ version }} · </template>{{ releases.length }} new update{{ releases.length === 1 ? '' : 's' }}
+                </p>
+              </div>
+            </div>
+            <button
+              type="button"
+              class="-mr-1 -mt-1 shrink-0 text-muted-foreground transition-colors hover:text-foreground"
+              aria-label="Remind me later"
+              @click="handleLater"
+            >
+              <X :size="18" />
+            </button>
+          </div>
+        </header>
+
+        <div class="flex-1 space-y-3 overflow-y-auto px-5 py-4">
+          <section v-for="(release, index) in releases" :key="release.version" class="rounded-lg border border-border bg-background p-4">
+            <button type="button" class="flex w-full items-center justify-between gap-3 text-left" @click="toggle(release.version)">
+              <div class="flex flex-wrap items-center gap-2">
+                <span class="rounded-full bg-primary/10 px-2 py-0.5 text-xs font-medium text-primary">{{ release.version }}</span>
+                <span
+                  v-if="index === 0"
+                  class="rounded-full bg-primary px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-primary-foreground"
+                >
+                  Latest
+                </span>
+                <span v-if="formatReleaseDate(release.date)" class="text-xs text-muted-foreground">{{ formatReleaseDate(release.date) }}</span>
+              </div>
+              <ChevronDown
+                :size="16"
+                class="shrink-0 text-muted-foreground transition-transform motion-reduce:transition-none"
+                :class="isExpanded(release.version) ? 'rotate-180' : ''"
+              />
+            </button>
+
+            <template v-if="isExpanded(release.version) && release.highlights.length">
+              <ul class="mt-3 divide-y divide-border/60">
+                <li v-for="(highlight, hIndex) in release.highlights" :key="hIndex" class="py-4 first:pt-0 last:pb-0">
+                  <HighlightItem :highlight="highlight" :show-media="index === 0" compact />
+                </li>
+              </ul>
+            </template>
+
+            <a
+              v-if="isExpanded(release.version)"
+              :href="release.changelogUrl"
+              target="_blank"
+              rel="noopener noreferrer"
+              class="mt-3 inline-flex items-center gap-1 text-xs font-medium text-primary transition-colors hover:text-primary/85"
+            >
+              Full changelog
+              <ExternalLink :size="12" />
+            </a>
+          </section>
+
+          <RouterLink
+            v-if="hasMore"
+            to="/whats-new"
+            class="inline-flex items-center gap-1 text-sm font-medium text-primary transition-colors hover:text-primary/85"
+            @click="handleLater"
+          >
+            See all releases
+            <ArrowRight :size="14" />
+          </RouterLink>
+        </div>
+
+        <footer class="flex items-center justify-end gap-3 border-t border-border px-5 py-4">
+          <button
+            type="button"
+            class="rounded-md border border-border px-4 py-2 text-sm font-medium text-foreground transition-colors hover:bg-muted"
+            @click="handleLater"
+          >
+            Remind me later
+          </button>
+          <button
+            ref="ackButton"
+            type="button"
+            class="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90"
+            @click="handleAck"
+          >
+            Got it
+          </button>
+        </footer>
+      </div>
+    </div>
+  </Teleport>
+</template>
diff --git a/client/src/features/whats-new/WhatsNewView.vue b/client/src/features/whats-new/WhatsNewView.vue
new file mode 100644
index 000000000..eaffb7fbc
--- /dev/null
+++ b/client/src/features/whats-new/WhatsNewView.vue
@@ -0,0 +1,283 @@
+<script setup lang="ts">
+import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue'
+import { toast } from 'vue-sonner'
+import { ChevronDown, ExternalLink, Search, Sparkles } from 'lucide-vue-next'
+import type { ReleaseNote, ReleaseNotesResponse } from '@bookorbit/types'
+import { api } from '@/lib/api'
+import { useWhatsNew } from './composables/useWhatsNew'
+import { formatReleaseDate } from './lib/whats-new.logic'
+import { renderChangelogMarkdown } from './lib/markdown'
+import HighlightItem from './components/HighlightItem.vue'
+
+const { version, markArchiveSeen } = useWhatsNew()
+
+const releases = ref<ReleaseNote[]>([])
+const page = ref(1)
+const hasMore = ref(false)
+const loading = ref(false)
+const loadingMore = ref(false)
+const error = ref<string | null>(null)
+const search = ref('')
+const expandedChangelogs = ref(new Set<string>())
+const activeVersion = ref<string | null>(null)
+
+const filtered = computed(() => {
+  const q = search.value.trim().toLowerCase()
+  if (!q) return releases.value
+  return releases.value.filter((release) => {
+    if (release.version.toLowerCase().includes(q)) return true
+    if (release.name?.toLowerCase().includes(q)) return true
+    return release.highlights.some((h) => h.title.toLowerCase().includes(q) || h.body.toLowerCase().includes(q))
+  })
+})
+
+async function loadPage(target: number): Promise<void> {
+  const res = await api(`/api/v1/release-notes?page=${target}`)
+  if (!res.ok) throw new Error(`HTTP ${res.status}`)
+  const data = (await res.json()) as ReleaseNotesResponse
+  releases.value = target === 1 ? data.releases : [...releases.value, ...data.releases]
+  hasMore.value = data.hasMore
+  page.value = target
+}
+
+async function loadFirst(): Promise<void> {
+  loading.value = true
+  error.value = null
+  try {
+    await loadPage(1)
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : 'Failed to load releases'
+  } finally {
+    loading.value = false
+  }
+}
+
+async function loadMore(): Promise<void> {
+  loadingMore.value = true
+  try {
+    await loadPage(page.value + 1)
+  } catch {
+    // Keep the releases already loaded; surface the failure so the button isn't a no-op.
+    toast.error('Could not load more releases. Please try again.')
+  } finally {
+    loadingMore.value = false
+  }
+}
+
+function retry(): void {
+  void loadFirst()
+}
+
+function toggleChangelog(release: ReleaseNote): void {
+  const next = new Set(expandedChangelogs.value)
+  if (next.has(release.version)) next.delete(release.version)
+  else next.add(release.version)
+  expandedChangelogs.value = next
+}
+
+function isChangelogOpen(release: ReleaseNote): boolean {
+  return expandedChangelogs.value.has(release.version)
+}
+
+function isCurrent(release: ReleaseNote): boolean {
+  return !!version.value && release.version === version.value
+}
+
+function anchorId(versionTag: string): string {
+  return 'release-' + versionTag.replace(/[^a-zA-Z0-9]+/g, '-')
+}
+
+// Scrollspy: highlight the rail entry whose card the user has scrolled to.
+let scrollEl: EventTarget | null = null
+
+function updateActiveVersion(): void {
+  const first = filtered.value[0]
+  if (!first) return
+  const offset = 120
+  let current = first.version
+  for (const release of filtered.value) {
+    const el = document.getElementById(anchorId(release.version))
+    if (!el) continue
+    if (el.getBoundingClientRect().top - offset <= 0) current = release.version
+    else break
+  }
+  activeVersion.value = current
+}
+
+watch(
+  () => filtered.value.map((r) => r.version).join(','),
+  () => nextTick(updateActiveVersion),
+)
+
+onMounted(() => {
+  void loadFirst().then(() => nextTick(updateActiveVersion))
+  void markArchiveSeen()
+  scrollEl = document.querySelector<HTMLElement>('.app-shell-scroll') ?? window
+  scrollEl.addEventListener('scroll', updateActiveVersion, { passive: true })
+  window.addEventListener('resize', updateActiveVersion)
+})
+
+onUnmounted(() => {
+  scrollEl?.removeEventListener('scroll', updateActiveVersion)
+  window.removeEventListener('resize', updateActiveVersion)
+})
+</script>
+
+<template>
+  <div class="w-full max-w-6xl px-4 py-6">
+    <header class="mb-5 flex items-center gap-3">
+      <span class="flex h-9 w-9 items-center justify-center rounded-full bg-primary/10 text-primary">
+        <Sparkles :size="20" />
+      </span>
+      <div>
+        <h1 class="text-xl font-semibold tracking-tight text-foreground">What's New</h1>
+        <p class="text-sm text-muted-foreground">Everything that's shipped, newest first.</p>
+      </div>
+    </header>
+
+    <div class="lg:flex lg:gap-6">
+      <nav v-if="!loading && !error && filtered.length" class="hidden w-48 shrink-0 lg:order-last lg:block">
+        <div class="sticky top-2 space-y-1">
+          <p class="px-2 pb-1 text-xs font-semibold uppercase tracking-wider text-muted-foreground">Versions</p>
+          <a
+            v-for="release in filtered"
+            :key="release.version"
+            :href="'#' + anchorId(release.version)"
+            :aria-current="activeVersion === release.version ? 'location' : undefined"
+            class="flex items-center gap-1.5 rounded-md px-2 py-1.5 text-sm transition-colors"
+            :class="
+              activeVersion === release.version
+                ? 'bg-muted font-semibold text-foreground'
+                : 'text-muted-foreground hover:bg-muted/60 hover:text-foreground'
+            "
+          >
+            <span class="truncate">{{ release.version }}</span>
+            <span v-if="isCurrent(release)" class="h-1.5 w-1.5 shrink-0 rounded-full bg-primary" aria-label="Current version" />
+          </a>
+        </div>
+      </nav>
+
+      <div class="min-w-0 flex-1">
+        <div class="relative mb-5">
+          <Search :size="16" class="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground" />
+          <input
+            v-model="search"
+            type="search"
+            placeholder="Search releases…"
+            class="w-full rounded-md border border-input bg-background py-2 pl-9 pr-3 text-sm text-foreground focus:outline-none focus:ring-2 focus:ring-primary/50"
+          />
+        </div>
+
+        <div v-if="loading" class="space-y-3">
+          <div v-for="n in 4" :key="n" class="h-28 animate-pulse rounded-lg border border-border bg-card" />
+        </div>
+
+        <div v-else-if="error" class="rounded-lg border border-border bg-card p-6 text-center">
+          <p class="text-sm text-muted-foreground">Couldn't load releases. Check your connection and try again.</p>
+          <button
+            type="button"
+            class="mt-3 rounded-md border border-border px-4 py-2 text-sm font-medium text-foreground hover:bg-muted"
+            @click="retry"
+          >
+            Retry
+          </button>
+        </div>
+
+        <div v-else-if="filtered.length === 0" class="rounded-lg border border-border bg-card p-6 text-center text-sm text-muted-foreground">
+          No releases found.
+        </div>
+
+        <div v-else class="space-y-4">
+          <article
+            v-for="release in filtered"
+            :id="anchorId(release.version)"
+            :key="release.version"
+            class="scroll-mt-4 rounded-lg border border-border bg-card p-4 shadow-xs md:p-5"
+          >
+            <div class="flex flex-wrap items-center gap-2">
+              <h2 class="text-base font-semibold text-foreground">{{ release.version }}</h2>
+              <span v-if="isCurrent(release)" class="rounded-full bg-primary/10 px-2 py-0.5 text-xs font-medium text-primary">You're here</span>
+              <span v-if="formatReleaseDate(release.date)" class="text-xs text-muted-foreground">{{ formatReleaseDate(release.date) }}</span>
+            </div>
+
+            <template v-if="release.highlights.length">
+              <ul class="mt-3 divide-y divide-border/60">
+                <li v-for="(highlight, hIndex) in release.highlights" :key="hIndex" class="py-4 first:pt-0 last:pb-0">
+                  <HighlightItem :highlight="highlight" />
+                </li>
+              </ul>
+            </template>
+
+            <p v-else class="mt-3 text-sm text-muted-foreground">No highlights for this release.</p>
+
+            <div class="mt-4 flex flex-wrap items-center gap-4">
+              <button
+                v-if="release.changelogBody"
+                type="button"
+                class="inline-flex items-center gap-1 text-xs font-medium text-foreground transition-colors hover:text-primary"
+                @click="toggleChangelog(release)"
+              >
+                <ChevronDown
+                  :size="14"
+                  class="transition-transform motion-reduce:transition-none"
+                  :class="isChangelogOpen(release) ? 'rotate-180' : ''"
+                />
+                {{ isChangelogOpen(release) ? 'Hide' : 'Show' }} full changelog
+              </button>
+              <a
+                :href="release.changelogUrl"
+                target="_blank"
+                rel="noopener noreferrer"
+                class="inline-flex items-center gap-1 text-xs font-medium text-primary transition-colors hover:text-primary/85"
+              >
+                Open on GitHub
+                <ExternalLink :size="12" />
+              </a>
+            </div>
+
+            <!-- eslint-disable-next-line vue/no-v-html -- sanitized by renderChangelogMarkdown (DOMPurify) -->
+            <div
+              v-if="isChangelogOpen(release) && release.changelogBody"
+              class="whats-new-changelog mt-3 border-t border-border/60 pt-3 text-sm text-muted-foreground"
+              v-html="renderChangelogMarkdown(release.changelogBody)"
+            />
+          </article>
+
+          <div v-if="hasMore && !search.trim()" class="pt-1 text-center">
+            <button
+              type="button"
+              :disabled="loadingMore"
+              class="rounded-md border border-border px-4 py-2 text-sm font-medium text-foreground hover:bg-muted disabled:opacity-50"
+              @click="loadMore"
+            >
+              {{ loadingMore ? 'Loading…' : 'Load more' }}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.whats-new-changelog :deep(h1),
+.whats-new-changelog :deep(h2),
+.whats-new-changelog :deep(h3) {
+  font-weight: 600;
+  color: var(--foreground);
+  margin: 0.75rem 0 0.25rem;
+  font-size: 0.875rem;
+}
+.whats-new-changelog :deep(ul) {
+  list-style: disc;
+  padding-left: 1.25rem;
+  margin: 0.25rem 0;
+}
+.whats-new-changelog :deep(a) {
+  color: var(--primary);
+}
+.whats-new-changelog :deep(code) {
+  font-family: ui-monospace, monospace;
+  font-size: 0.8em;
+}
+</style>
diff --git a/client/src/features/whats-new/components/HighlightIcon.vue b/client/src/features/whats-new/components/HighlightIcon.vue
new file mode 100644
index 000000000..5a5b618ab
--- /dev/null
+++ b/client/src/features/whats-new/components/HighlightIcon.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import { computed, type Component } from 'vue'
+import * as Icons from 'lucide-vue-next'
+import { Sparkles } from 'lucide-vue-next'
+import { isIconNameShape } from '../lib/whats-new.logic'
+
+const props = withDefaults(defineProps<{ name: string | null; size?: number }>(), { size: 18 })
+
+const iconComponent = computed<Component>(() => {
+  const name = props.name
+  if (isIconNameShape(name) && name! in Icons) {
+    return (Icons as Record<string, unknown>)[name!] as Component
+  }
+  return Sparkles
+})
+</script>
+
+<template>
+  <component :is="iconComponent" :size="size" />
+</template>
diff --git a/client/src/features/whats-new/components/HighlightItem.vue b/client/src/features/whats-new/components/HighlightItem.vue
new file mode 100644
index 000000000..9680e1ec3
--- /dev/null
+++ b/client/src/features/whats-new/components/HighlightItem.vue
@@ -0,0 +1,93 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import type { ReleaseHighlight, ReleaseMedia } from '@bookorbit/types'
+import { isAllowedImageHost } from '../lib/whats-new.logic'
+import HighlightIcon from './HighlightIcon.vue'
+import ImageLightbox from './ImageLightbox.vue'
+
+const props = withDefaults(defineProps<{ highlight: ReleaseHighlight; showMedia?: boolean; compact?: boolean }>(), {
+  showMedia: true,
+  compact: false,
+})
+
+// Local copy so a media item that fails to load can be removed without mutating the prop.
+const items = ref<ReleaseMedia[]>([...props.highlight.media])
+watch(
+  () => props.highlight.media,
+  (media) => {
+    items.value = [...media]
+  },
+)
+
+const visibleMedia = computed(() => items.value.filter((m) => isAllowedImageHost(m.url)))
+const images = computed(() => visibleMedia.value.filter((m) => m.type === 'image').map((m) => m.url))
+
+// Every image sits in an identical-size frame and is letterboxed inside it (object-contain), so
+// highlights with very different screenshot shapes line up uniformly. The frame background fills
+// the leftover space; nothing is cropped or distorted.
+const mediaFrameClass = computed(() => (props.compact ? 'h-36 w-56' : 'h-48 w-72'))
+
+const lightboxOpen = ref(false)
+const lightboxIndex = ref(0)
+
+function openLightbox(item: ReleaseMedia): void {
+  const idx = images.value.indexOf(item.url)
+  if (idx === -1) return
+  lightboxIndex.value = idx
+  lightboxOpen.value = true
+}
+
+function closeLightbox(): void {
+  lightboxOpen.value = false
+}
+
+function handleMediaError(item: ReleaseMedia): void {
+  items.value = items.value.filter((m) => m !== item)
+}
+</script>
+
+<template>
+  <div class="flex gap-3">
+    <span class="mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-primary/10 text-primary">
+      <HighlightIcon :name="highlight.icon" :size="16" />
+    </span>
+
+    <div class="min-w-0 flex-1">
+      <p class="line-clamp-2 text-sm font-semibold text-foreground">{{ highlight.title }}</p>
+      <p v-if="highlight.body" class="mt-1 line-clamp-4 text-sm leading-relaxed text-muted-foreground">{{ highlight.body }}</p>
+
+      <div v-if="props.showMedia && visibleMedia.length" class="relative mt-3">
+        <span
+          v-if="visibleMedia.length > 1"
+          class="pointer-events-none absolute right-1 top-1 z-10 rounded-full bg-background/80 px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground"
+        >
+          {{ visibleMedia.length }}
+        </span>
+        <div class="flex gap-2 overflow-x-auto pb-1 snap-x">
+          <template v-for="m in visibleMedia" :key="m.url">
+            <button
+              v-if="m.type === 'image'"
+              type="button"
+              class="block shrink-0 snap-start overflow-hidden rounded-lg border border-border bg-muted/40 transition-opacity hover:opacity-90"
+              :class="mediaFrameClass"
+              @click="openLightbox(m)"
+            >
+              <img :src="m.url" :alt="highlight.title" loading="lazy" class="h-full w-full object-contain" @error="handleMediaError(m)" />
+            </button>
+            <video
+              v-else
+              :src="m.url"
+              controls
+              preload="metadata"
+              class="block shrink-0 snap-start rounded-lg border border-border bg-black object-contain"
+              :class="mediaFrameClass"
+              @error="handleMediaError(m)"
+            />
+          </template>
+        </div>
+      </div>
+    </div>
+
+    <ImageLightbox v-if="lightboxOpen && images.length" :images="images" :start-index="lightboxIndex" :alt="highlight.title" @close="closeLightbox" />
+  </div>
+</template>
diff --git a/client/src/features/whats-new/components/ImageLightbox.vue b/client/src/features/whats-new/components/ImageLightbox.vue
new file mode 100644
index 000000000..c1c2bb853
--- /dev/null
+++ b/client/src/features/whats-new/components/ImageLightbox.vue
@@ -0,0 +1,92 @@
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref } from 'vue'
+import { ChevronLeft, ChevronRight, X } from 'lucide-vue-next'
+import { useModal } from '@/composables/useModal'
+import { registerLightbox } from '../lib/lightbox-state'
+
+const props = withDefaults(defineProps<{ images: string[]; startIndex?: number; alt?: string }>(), {
+  startIndex: 0,
+})
+const emit = defineEmits<{ close: [] }>()
+
+const current = ref(props.startIndex)
+const panel = ref<HTMLElement | null>(null)
+
+function handleClose() {
+  emit('close')
+}
+
+function next() {
+  current.value = (current.value + 1) % props.images.length
+}
+
+function prev() {
+  current.value = (current.value - 1 + props.images.length) % props.images.length
+}
+
+function handleArrowKeys(event: KeyboardEvent) {
+  if (event.key === 'ArrowRight') next()
+  else if (event.key === 'ArrowLeft') prev()
+}
+
+let unregister: (() => void) | null = null
+
+useModal({ container: panel, onClose: handleClose })
+
+onMounted(() => {
+  unregister = registerLightbox()
+  window.addEventListener('keydown', handleArrowKeys)
+})
+onUnmounted(() => {
+  unregister?.()
+  window.removeEventListener('keydown', handleArrowKeys)
+})
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      ref="panel"
+      class="fixed inset-0 z-[90] flex items-center justify-center bg-black/80 p-4 motion-safe:animate-in motion-safe:fade-in"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Image viewer"
+      @click.self="handleClose"
+    >
+      <button
+        type="button"
+        class="absolute right-4 top-4 text-white/80 transition-colors hover:text-white"
+        aria-label="Close image"
+        @click="handleClose"
+      >
+        <X :size="24" />
+      </button>
+
+      <button
+        v-if="images.length > 1"
+        type="button"
+        class="absolute left-4 top-1/2 -translate-y-1/2 rounded-full bg-white/10 p-2 text-white/80 transition-colors hover:bg-white/20 hover:text-white"
+        aria-label="Previous image"
+        @click="prev"
+      >
+        <ChevronLeft :size="28" />
+      </button>
+
+      <img :src="images[current]" :alt="alt ?? ''" class="max-h-[90vh] max-w-[90vw] rounded-lg object-contain shadow-2xl" />
+
+      <button
+        v-if="images.length > 1"
+        type="button"
+        class="absolute right-4 top-1/2 -translate-y-1/2 rounded-full bg-white/10 p-2 text-white/80 transition-colors hover:bg-white/20 hover:text-white"
+        aria-label="Next image"
+        @click="next"
+      >
+        <ChevronRight :size="28" />
+      </button>
+
+      <span v-if="images.length > 1" class="absolute bottom-4 left-1/2 -translate-x-1/2 rounded-full bg-black/60 px-3 py-1 text-sm text-white/90">
+        {{ current + 1 }} / {{ images.length }}
+      </span>
+    </div>
+  </Teleport>
+</template>
diff --git a/client/src/features/whats-new/composables/useWhatsNew.test.ts b/client/src/features/whats-new/composables/useWhatsNew.test.ts
new file mode 100644
index 000000000..83d641e53
--- /dev/null
+++ b/client/src/features/whats-new/composables/useWhatsNew.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+
+import type { ReleaseNote } from '@bookorbit/types'
+
+import { resetWhatsNew, useWhatsNew } from './useWhatsNew'
+
+describe('resetWhatsNew', () => {
+  it('clears module-scope state so a user switch cannot inherit the previous user state', () => {
+    const { releases, popupEnabled, popupOpen, hasMore, error } = useWhatsNew()
+
+    releases.value = [{ version: 'v1.2.0' } as ReleaseNote]
+    popupEnabled.value = false
+    popupOpen.value = true
+    hasMore.value = true
+    error.value = 'boom'
+
+    resetWhatsNew()
+
+    expect(releases.value).toEqual([])
+    expect(popupEnabled.value).toBe(true)
+    expect(popupOpen.value).toBe(false)
+    expect(hasMore.value).toBe(false)
+    expect(error.value).toBeNull()
+  })
+})
diff --git a/client/src/features/whats-new/composables/useWhatsNew.ts b/client/src/features/whats-new/composables/useWhatsNew.ts
new file mode 100644
index 000000000..eb34ac7ae
--- /dev/null
+++ b/client/src/features/whats-new/composables/useWhatsNew.ts
@@ -0,0 +1,154 @@
+import { computed, ref } from 'vue'
+import type { ReleaseNote, ReleaseNotesResponse, WhatsNewPreferences } from '@bookorbit/types'
+import { api } from '@/lib/api'
+import { useAppInfo } from '@/features/settings/composables/useAppInfo'
+import { isNewer, isSemverTag, shouldShowPopup } from '../lib/whats-new.logic'
+
+const lastSeenVersion = ref<string | null>(null)
+const popupEnabled = ref(true)
+const releases = ref<ReleaseNote[]>([])
+const hasMore = ref(false)
+const popupOpen = ref(false)
+const loading = ref(false)
+const error = ref<string | null>(null)
+
+let prefsLoaded = false
+let evaluated = false
+let evaluating = false
+let dismissedThisSession = false
+
+/**
+ * Clears the module-scope singleton so a user switch in the same SPA session can't inherit the
+ * previous user's seen-state. Call from auth teardown (see clearAuth in useAuth).
+ */
+export function resetWhatsNew(): void {
+  lastSeenVersion.value = null
+  popupEnabled.value = true
+  releases.value = []
+  hasMore.value = false
+  popupOpen.value = false
+  loading.value = false
+  error.value = null
+  prefsLoaded = false
+  evaluated = false
+  evaluating = false
+  dismissedThisSession = false
+}
+
+export function useWhatsNew() {
+  const { version, loadAppInfo } = useAppInfo()
+
+  const hasUnseen = computed(() => releases.value.length > 0)
+
+  async function loadPrefs(): Promise<void> {
+    if (prefsLoaded) return
+    const res = await api('/api/v1/user-preferences/whats-new')
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const data = (await res.json()) as { settings: WhatsNewPreferences }
+    lastSeenVersion.value = data.settings.lastSeenVersion
+    popupEnabled.value = data.settings.popupEnabled
+    prefsLoaded = true
+  }
+
+  async function persist(settings: Partial<WhatsNewPreferences>): Promise<Response> {
+    return api('/api/v1/user-preferences/whats-new', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ settings }),
+    })
+  }
+
+  async function saveLastSeen(value: string): Promise<void> {
+    lastSeenVersion.value = value
+    releases.value = []
+    hasMore.value = false
+    await persist({ lastSeenVersion: value }).catch(() => {})
+  }
+
+  async function evaluate(): Promise<void> {
+    if (evaluated || evaluating) return
+    evaluating = true
+    loading.value = true
+    error.value = null
+    try {
+      await loadAppInfo()
+      await loadPrefs()
+
+      const current = version.value
+      if (!isSemverTag(current)) return
+
+      if (lastSeenVersion.value === null) {
+        await saveLastSeen(current)
+        return
+      }
+
+      if (!isNewer(current, lastSeenVersion.value)) return
+
+      const res = await api(`/api/v1/release-notes?since=${encodeURIComponent(lastSeenVersion.value)}`)
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const data = (await res.json()) as ReleaseNotesResponse
+      releases.value = data.releases
+      hasMore.value = data.hasMore
+      evaluated = true
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to load release notes'
+    } finally {
+      evaluating = false
+      loading.value = false
+    }
+  }
+
+  function syncPopup(routeName: string | null | undefined): void {
+    if (
+      shouldShowPopup({ hasUnseen: hasUnseen.value, popupEnabled: popupEnabled.value, dismissedThisSession, routeName, alreadyOpen: popupOpen.value })
+    ) {
+      popupOpen.value = true
+    }
+  }
+
+  async function acknowledge(): Promise<void> {
+    popupOpen.value = false
+    if (isSemverTag(version.value)) await saveLastSeen(version.value)
+  }
+
+  function remindLater(): void {
+    dismissedThisSession = true
+    popupOpen.value = false
+  }
+
+  async function markArchiveSeen(): Promise<void> {
+    await loadAppInfo()
+    await loadPrefs().catch(() => {})
+    const current = version.value
+    if (isSemverTag(current) && (lastSeenVersion.value === null || isNewer(current, lastSeenVersion.value))) {
+      await saveLastSeen(current)
+    }
+  }
+
+  async function setPopupEnabled(enabled: boolean): Promise<void> {
+    popupEnabled.value = enabled
+    const res = await persist({ popupEnabled: enabled })
+    if (!res.ok) {
+      popupEnabled.value = !enabled
+      throw new Error(`HTTP ${res.status}`)
+    }
+  }
+
+  return {
+    version,
+    releases,
+    hasMore,
+    hasUnseen,
+    popupOpen,
+    popupEnabled,
+    loading,
+    error,
+    evaluate,
+    syncPopup,
+    acknowledge,
+    remindLater,
+    markArchiveSeen,
+    setPopupEnabled,
+    loadPrefs,
+  }
+}
diff --git a/client/src/features/whats-new/lib/lightbox-state.ts b/client/src/features/whats-new/lib/lightbox-state.ts
new file mode 100644
index 000000000..b0fa9ca34
--- /dev/null
+++ b/client/src/features/whats-new/lib/lightbox-state.ts
@@ -0,0 +1,13 @@
+import { computed, ref } from 'vue'
+
+const openCount = ref(0)
+
+/** Returns an unregister fn; lets the popup know not to also close on Escape. */
+export function registerLightbox(): () => void {
+  openCount.value++
+  return () => {
+    openCount.value = Math.max(0, openCount.value - 1)
+  }
+}
+
+export const anyLightboxOpen = computed(() => openCount.value > 0)
diff --git a/client/src/features/whats-new/lib/markdown.test.ts b/client/src/features/whats-new/lib/markdown.test.ts
new file mode 100644
index 000000000..5f2735979
--- /dev/null
+++ b/client/src/features/whats-new/lib/markdown.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+
+import { renderChangelogMarkdown } from './markdown'
+
+describe('renderChangelogMarkdown', () => {
+  it('renders headings, lists, bold, code and links', () => {
+    const md = ['### Features', '- add **two-way** sync', '- speed up `jumpRail`', '', '[issue](https://example.com/1)'].join('\n')
+    const html = renderChangelogMarkdown(md)
+    expect(html).toContain('<h3>Features</h3>')
+    expect(html).toContain('<ul>')
+    expect(html).toContain('<strong>two-way</strong>')
+    expect(html).toContain('<code>jumpRail</code>')
+    expect(html).toMatch(/<a [^>]*href="https:\/\/example\.com\/1"[^>]*>issue<\/a>/)
+    expect(html).toContain('target="_blank"')
+    expect(html).toContain('rel="noopener noreferrer"')
+  })
+
+  it('renders fenced code blocks and horizontal rules', () => {
+    const html = renderChangelogMarkdown(['---', '```bash', 'docker pull x', '```'].join('\n'))
+    expect(html).toContain('<hr>')
+    expect(html).toContain('<pre><code>docker pull x</code></pre>')
+  })
+
+  it('strips dangerous markup', () => {
+    const html = renderChangelogMarkdown('<script>alert(1)</script>\n[x](javascript:alert(1))')
+    expect(html).not.toContain('<script>')
+    expect(html).not.toContain('javascript:')
+  })
+
+  it('returns empty string for empty input', () => {
+    expect(renderChangelogMarkdown(null)).toBe('')
+    expect(renderChangelogMarkdown('')).toBe('')
+  })
+})
diff --git a/client/src/features/whats-new/lib/markdown.ts b/client/src/features/whats-new/lib/markdown.ts
new file mode 100644
index 000000000..2c2ff3e5e
--- /dev/null
+++ b/client/src/features/whats-new/lib/markdown.ts
@@ -0,0 +1,118 @@
+import DOMPurify from 'dompurify'
+
+// Minimal markdown renderer for the technical changelog (semantic-release output:
+// headings, bullet lists, links, bold, inline code, fenced code, horizontal rules).
+// Kept dependency-free on purpose; DOMPurify is the security backstop.
+
+const ALLOWED_TAGS = [
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'p',
+  'br',
+  'hr',
+  'ul',
+  'ol',
+  'li',
+  'strong',
+  'em',
+  'b',
+  'i',
+  'del',
+  'code',
+  'pre',
+  'blockquote',
+  'a',
+]
+
+DOMPurify.addHook('afterSanitizeAttributes', (node) => {
+  if (node.tagName === 'A') {
+    node.setAttribute('target', '_blank')
+    node.setAttribute('rel', 'noopener noreferrer')
+  }
+})
+
+function escapeHtml(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+function renderInline(text: string): string {
+  let out = escapeHtml(text)
+  out = out.replace(/`([^`]+)`/g, (_, code: string) => `<code>${code}</code>`)
+  out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+  out = out.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, label: string, url: string) => `<a href="${escapeHtml(url)}">${label}</a>`)
+  return out
+}
+
+function toHtml(md: string): string {
+  const lines = md.split('\n')
+  const out: string[] = []
+  let inList = false
+  let inCode = false
+  let code: string[] = []
+
+  const closeList = () => {
+    if (inList) {
+      out.push('</ul>')
+      inList = false
+    }
+  }
+
+  for (const line of lines) {
+    if (/^```/.test(line)) {
+      if (inCode) {
+        out.push(`<pre><code>${escapeHtml(code.join('\n'))}</code></pre>`)
+        inCode = false
+        code = []
+      } else {
+        closeList()
+        inCode = true
+      }
+      continue
+    }
+    if (inCode) {
+      code.push(line)
+      continue
+    }
+
+    const heading = line.match(/^(#{1,6})\s+(.*)$/)
+    if (heading) {
+      closeList()
+      const level = (heading[1] ?? '#').length
+      out.push(`<h${level}>${renderInline(heading[2] ?? '')}</h${level}>`)
+      continue
+    }
+    if (/^\s*([-*_])\1{2,}\s*$/.test(line)) {
+      closeList()
+      out.push('<hr>')
+      continue
+    }
+    const item = line.match(/^\s*[-*]\s+(.*)$/)
+    if (item) {
+      if (!inList) {
+        out.push('<ul>')
+        inList = true
+      }
+      out.push(`<li>${renderInline(item[1] ?? '')}</li>`)
+      continue
+    }
+    if (line.trim() === '') {
+      closeList()
+      continue
+    }
+    closeList()
+    out.push(`<p>${renderInline(line)}</p>`)
+  }
+
+  if (inCode) out.push(`<pre><code>${escapeHtml(code.join('\n'))}</code></pre>`)
+  closeList()
+  return out.join('\n')
+}
+
+export function renderChangelogMarkdown(md: string | null | undefined): string {
+  if (!md) return ''
+  return DOMPurify.sanitize(toHtml(md), { ALLOWED_TAGS, ALLOWED_ATTR: ['href', 'target', 'rel'] })
+}
diff --git a/client/src/features/whats-new/lib/whats-new.logic.test.ts b/client/src/features/whats-new/lib/whats-new.logic.test.ts
new file mode 100644
index 000000000..1c3b720cb
--- /dev/null
+++ b/client/src/features/whats-new/lib/whats-new.logic.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+
+import { isAllowedImageHost, isIconNameShape, isNewer, isSemverTag, shouldShowPopup } from './whats-new.logic'
+
+describe('isSemverTag', () => {
+  it('accepts release tags and rejects dev builds', () => {
+    expect(isSemverTag('v1.2.0')).toBe(true)
+    expect(isSemverTag('v1.2.0-rc.1')).toBe(true)
+    expect(isSemverTag('Local build')).toBe(false)
+    expect(isSemverTag(null)).toBe(false)
+    expect(isSemverTag('')).toBe(false)
+  })
+})
+
+describe('isNewer', () => {
+  it('compares semver precedence', () => {
+    expect(isNewer('v1.2.0', 'v1.1.0')).toBe(true)
+    expect(isNewer('v2.0.0', 'v1.9.9')).toBe(true)
+    expect(isNewer('v1.1.0', 'v1.1.0')).toBe(false)
+    expect(isNewer('v1.0.0', 'v1.1.0')).toBe(false)
+    expect(isNewer('Local build', 'v1.0.0')).toBe(false)
+  })
+})
+
+describe('isAllowedImageHost', () => {
+  it('allows GitHub attachment hosts only', () => {
+    expect(isAllowedImageHost('https://github.com/user-attachments/assets/x')).toBe(true)
+    expect(isAllowedImageHost('https://user-images.githubusercontent.com/1/x.png')).toBe(true)
+    expect(isAllowedImageHost('https://evil.example.com/x.png')).toBe(false)
+    expect(isAllowedImageHost('http://github.com/user-attachments/assets/x')).toBe(false)
+    expect(isAllowedImageHost('https://github.com/o/r/raw/main/x.png')).toBe(false)
+    expect(isAllowedImageHost('nonsense')).toBe(false)
+  })
+})
+
+describe('isIconNameShape', () => {
+  it('accepts PascalCase icon names and rejects utility exports', () => {
+    expect(isIconNameShape('BookHeart')).toBe(true)
+    expect(isIconNameShape('Zap')).toBe(true)
+    expect(isIconNameShape('createLucideIcon')).toBe(false)
+    expect(isIconNameShape('icons')).toBe(false)
+    expect(isIconNameShape('book-heart')).toBe(false)
+    expect(isIconNameShape(null)).toBe(false)
+  })
+})
+
+describe('shouldShowPopup', () => {
+  const base = { hasUnseen: true, popupEnabled: true, dismissedThisSession: false, routeName: 'dashboard', alreadyOpen: false }
+
+  it('shows when there is unseen content and conditions allow', () => {
+    expect(shouldShowPopup(base)).toBe(true)
+  })
+
+  it('suppresses while in the reader', () => {
+    expect(shouldShowPopup({ ...base, routeName: 'reader' })).toBe(false)
+  })
+
+  it('suppresses when disabled, dismissed, already open, or nothing unseen', () => {
+    expect(shouldShowPopup({ ...base, popupEnabled: false })).toBe(false)
+    expect(shouldShowPopup({ ...base, dismissedThisSession: true })).toBe(false)
+    expect(shouldShowPopup({ ...base, alreadyOpen: true })).toBe(false)
+    expect(shouldShowPopup({ ...base, hasUnseen: false })).toBe(false)
+  })
+})
diff --git a/client/src/features/whats-new/lib/whats-new.logic.ts b/client/src/features/whats-new/lib/whats-new.logic.ts
new file mode 100644
index 000000000..2c663bcf4
--- /dev/null
+++ b/client/src/features/whats-new/lib/whats-new.logic.ts
@@ -0,0 +1,58 @@
+export function isSemverTag(value: string | null | undefined): boolean {
+  return !!value && /^v\d+\.\d+\.\d+/.test(value.trim())
+}
+
+export function parseSemver(value: string): [number, number, number] | null {
+  const match = value
+    .trim()
+    .replace(/^v/, '')
+    .match(/^(\d+)\.(\d+)\.(\d+)/)
+  if (!match) return null
+  return [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+export function isNewer(candidate: string, baseline: string): boolean {
+  const a = parseSemver(candidate)
+  const b = parseSemver(baseline)
+  if (!a || !b) return false
+  if (a[0] !== b[0]) return a[0] > b[0]
+  if (a[1] !== b[1]) return a[1] > b[1]
+  return a[2] > b[2]
+}
+
+/** Mirror of the server allowlist: only render GitHub-hosted attachment images. */
+export function isAllowedImageHost(url: string): boolean {
+  try {
+    const u = new URL(url)
+    if (u.protocol !== 'https:') return false
+    const host = u.hostname.toLowerCase()
+    if (host === 'github.com') return u.pathname.startsWith('/user-attachments/')
+    return host === 'githubusercontent.com' || host.endsWith('.githubusercontent.com')
+  } catch {
+    return false
+  }
+}
+
+/** Lucide icon names are PascalCase; reject anything else so we never resolve a non-icon export. */
+export function isIconNameShape(name: string | null | undefined): boolean {
+  return !!name && /^[A-Z][A-Za-z0-9]*$/.test(name)
+}
+
+export function formatReleaseDate(date: string | null): string {
+  if (!date) return ''
+  const parsed = new Date(date)
+  if (Number.isNaN(parsed.getTime())) return ''
+  return new Intl.DateTimeFormat(undefined, { year: 'numeric', month: 'short', day: 'numeric' }).format(parsed)
+}
+
+export function shouldShowPopup(opts: {
+  hasUnseen: boolean
+  popupEnabled: boolean
+  dismissedThisSession: boolean
+  routeName: string | null | undefined
+  alreadyOpen: boolean
+}): boolean {
+  if (opts.alreadyOpen) return false
+  if (!opts.hasUnseen || !opts.popupEnabled || opts.dismissedThisSession) return false
+  return opts.routeName !== 'reader'
+}
diff --git a/client/src/router/index.ts b/client/src/router/index.ts
index c2ac3e15a..e4d2b5284 100644
--- a/client/src/router/index.ts
+++ b/client/src/router/index.ts
@@ -232,6 +232,12 @@ export const routes: RouteRecordRaw[] = [
         component: () => import('@/views/BookDockView.vue'),
         meta: { title: 'Book Dock' },
       },
+      {
+        path: '/whats-new',
+        name: 'whats-new',
+        component: () => import('@/features/whats-new/WhatsNewView.vue'),
+        meta: { title: "What's New" },
+      },
       {
         path: '/statistics',
         name: 'statistics',
diff --git a/docs/RELEASE_PROCESS.md b/docs/RELEASE_PROCESS.md
index 71de1c696..cf9d949db 100644
--- a/docs/RELEASE_PROCESS.md
+++ b/docs/RELEASE_PROCESS.md
@@ -114,6 +114,12 @@ The workflow will:
 
 If all commits since the last release are non-releasable types (`chore`, `docs`, `test`, `build`, `ci`, `refactor`), semantic-release will skip the release. The Docker publish job will also be skipped.
 
+### Authoring the "What's New" highlights
+
+semantic-release creates the GitHub release as a **draft** with a `## Highlights` scaffold (added by `release.config.js`) that lists this release's `feat` commits as candidate highlights. Open the draft, curate those candidates into user-facing highlight bullets (with optional icons and dragged-in media), validate with `cd server && pnpm whats-new:check <tag>`, then click **Publish release**. The highlights power the in-app "What's New" popup and the `/whats-new` archive; the draft stays hidden in the app until you publish (even though the `:latest` Docker image is pushed beforehand).
+
+Full step-by-step walkthrough, format reference, and pre-publish checklist: [docs/whats-new-authoring-guide.md](whats-new-authoring-guide.md).
+
 ---
 
 ## Docker Image Publishing
diff --git a/docs/whats-new-authoring-guide.md b/docs/whats-new-authoring-guide.md
new file mode 100644
index 000000000..42c347715
--- /dev/null
+++ b/docs/whats-new-authoring-guide.md
@@ -0,0 +1,128 @@
+# Authoring the "What's New" highlights
+
+This is the end-to-end guide for writing the `## Highlights` section of a GitHub release so it
+powers BookOrbit's in-app **What's New** popup and the `/whats-new` archive. It is the single
+source of truth for both the workflow and the format.
+
+## How it shows up in the app
+
+- **Popup:** when a user opens the app on a newer version than they last saw, a popup shows the
+  highlights for the versions they missed (newest expanded, up to 4 versions cumulatively).
+- **Archive:** the `/whats-new` page lists every release (highlights + full changelog).
+- **Caching:** the server fetches and caches releases for about 10 minutes, so edits appear
+  within a few minutes (immediately on a server restart). No redeploy is needed.
+- **No highlights, no popup:** a release with no `## Highlights` section (or the scaffold left in
+  place with no bullets) simply shows no popup. Its changelog still appears in the archive. That
+  is fine for patch releases with nothing user-facing to call out.
+
+## Walkthrough (every release)
+
+1. **Cut the release.** Run the release workflow (Actions -> Release -> Run workflow on `main`).
+   semantic-release creates the GitHub release as a **draft** and the Docker images
+   (`:latest` and `:<version>`) are built and pushed. The draft is not visible in the app yet.
+2. **Open the draft to edit.** Go to the repo's Releases, click the draft (or open
+   `https://github.com/bookorbit/bookorbit/releases/edit/<tag>`), and click the edit (pencil) icon.
+3. **Review the candidate highlights.** The `## Highlights` scaffold contains a commented list of
+   this release's `feat` commits as starting candidates. Curate them: keep the user-facing ones,
+   reword them into friendly benefit-focused lines, and delete the rest.
+4. **Write the bullets** above the comment block, one per highlight (see the format below).
+5. **Add an icon** to a bullet by ending the line with `<!-- icon: Name -->` (optional).
+6. **Add media** by dragging an image or video into the editor (see the media rules below).
+7. **Delete the scaffold comment block** once you are done with it.
+8. **Validate:** from `server/`, run `pnpm whats-new:check <tag>` (lints, then previews exactly
+   what the app will render and checks media reachability). Fix any warnings.
+9. **Publish.** Click **Publish release**. Within ~10 minutes the popup appears for users on this
+   version. (Until you publish, the draft stays hidden in the app even though `:latest` is already
+   live, so do not leave it unpublished.)
+
+## Copy-paste starter
+
+```markdown
+## Highlights
+
+- **Two-way Kobo highlight sync** - Your highlights now sync both ways with Kobo, so a note on the device shows up on the web and vice versa. <!-- icon: BookHeart -->
+- **Instant library scroll** - The alphabet jump rail is now instant on libraries with thousands of books. <!-- icon: Zap -->
+- **Audiobook chapters** - Chapter markers are extracted and shown in the player; jump straight to any chapter. <!-- icon: Headphones -->
+
+  <img width="800" alt="chapters" src="https://github.com/user-attachments/assets/REPLACE-WITH-DROPPED-IMAGE" />
+
+- **Smaller fixes** - A batch of polish across the reader and library grid.
+```
+
+## Format reference
+
+**Heading**
+
+- The section heading must be exactly `## Highlights`.
+- Everything after the next heading (`##` / `###`) or a `---` rule is treated as the technical
+  changelog, not a highlight.
+
+**Bullets**
+
+- One highlight per line, starting with `- `.
+- Shape: `- **Title** - one or two friendly sentences.`
+- `**Title**` is the bold headline; the text after the `-` is the description.
+
+**Icons** (optional)
+
+- End the bullet with an HTML comment GitHub renders as nothing: `<!-- icon: Name -->`. It can
+  also sit on its own indented line right below the bullet.
+- `Name` is a PascalCase [lucide](https://lucide.dev/icons) icon name (e.g. `BookHeart`, `Zap`,
+  `ShieldCheck`, `Headphones`, `Film`). Omit the comment for the default icon (`Sparkles`).
+- Unknown names fall back to the default; the lint warns so you can fix a typo.
+- The old `- [Icon] **Title** ...` prefix still parses but renders as literal `[Icon]` text on the
+  GitHub page, so the lint warns against it. Use the comment form.
+
+**Media** (optional)
+
+- Drag an image or video into the GitHub release editor. GitHub uploads it and inserts either an
+  `<img ... src="https://github.com/user-attachments/assets/...">` tag (images) or a bare
+  `https://github.com/user-attachments/assets/...` URL (videos). Leave whatever it inserts as-is.
+- Only **GitHub-hosted** media renders: `github.com/user-attachments/...` or any
+  `*.githubusercontent.com` host. Media from other hosts (imgur, etc.) is dropped (the text is
+  kept) and the lint warns.
+- Image vs video is detected by file extension (`.mp4`, `.webm`, `.mov`, `.m4v`, `.ogv`, `.ogg`
+  are video); GitHub's extension-less attachment URLs are probed for their content type.
+- You can attach **several** media to one bullet (put each on its own line under it). They render
+  as a horizontal gallery; clicking an image opens a carousel. At most **6** media per highlight
+  render; extras are dropped (the lint warns).
+
+**Soft limits** (the app clamps and the lint warns; nothing breaks)
+
+- Title up to **120** characters, body up to **400** characters (visually line-clamped in the
+  popup; the full text stays in the archive and search).
+- Up to **12** highlights per release.
+
+## Validate before publishing
+
+Run from `server/`:
+
+- `pnpm whats-new:check <tag>` - the one-stop check: lints, then previews exactly what the app
+  renders (including a media reachability probe). Exits non-zero if the lint fails.
+- `pnpm whats-new:lint <file.md>` / `pnpm whats-new:lint --tag <tag>` - static validation only.
+  Add `--strict` to treat warnings as failures.
+- `pnpm whats-new:preview [tag]` - render preview only.
+
+Point these at a different repo for testing with the `GITHUB_RELEASES_REPO` env var (and
+`GITHUB_RELEASES_TOKEN` for private repos / rate limits), or pass `--repo owner/name` to preview.
+
+## Pre-publish checklist
+
+- [ ] `pnpm whats-new:check <tag>` is clean (no errors; warnings addressed).
+- [ ] Each bullet is `- **Title** - benefit.`, short and user-facing.
+- [ ] Icons are valid PascalCase lucide names (no typos), or omitted for the default.
+- [ ] Media was dragged in (GitHub-hosted), no more than 6 per highlight.
+- [ ] Titles <= 120 chars, bodies <= 400 chars.
+- [ ] The scaffold candidate/instruction comment block is deleted.
+- [ ] Clicked **Publish release** (the draft is not enough).
+
+## Common mistakes
+
+| Symptom                                   | Cause                                                  | Fix                                                          |
+| ----------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
+| Highlight shows the default Sparkles icon | Icon name typo / not a lucide name                     | Correct the PascalCase name (lint says which)                |
+| `[Icon]` text shows on the GitHub page    | Legacy `[Icon]` prefix                                 | Move the icon into a `<!-- icon: Name -->` comment           |
+| Image/video does not appear               | Media not GitHub-hosted                                | Drag the file into the editor (do not paste an external URL) |
+| Only 6 of N images show                   | Over the per-highlight media cap                       | Keep the best 6                                              |
+| Title/body looks cut off in the popup     | Over the soft length cap                               | Shorten it (full text stays in the archive)                  |
+| No popup for the release                  | No `## Highlights` bullets, or release left as a draft | Add bullets and click Publish                                |
diff --git a/docs/whats-new-template.md b/docs/whats-new-template.md
new file mode 100644
index 000000000..501c91d31
--- /dev/null
+++ b/docs/whats-new-template.md
@@ -0,0 +1,8 @@
+# Moved
+
+The "What's New" highlights format and template now live in the consolidated guide:
+
+**[docs/whats-new-authoring-guide.md](whats-new-authoring-guide.md)**
+
+It covers the end-to-end workflow, a copy-paste starter, the full format reference (icons,
+media, length caps), validation commands, and a pre-publish checklist.
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index 17aaf168b..e9041a4d4 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -33,6 +33,7 @@ export * from "./user-statistics";
 export * from "./migration";
 export * from "./notification";
 export * from "./app-info";
+export * from "./release-notes";
 export * from "./series";
 export * from "./table-layout";
 export * from "./series-collapse";
diff --git a/packages/types/src/release-notes.ts b/packages/types/src/release-notes.ts
new file mode 100644
index 000000000..b58695e48
--- /dev/null
+++ b/packages/types/src/release-notes.ts
@@ -0,0 +1,39 @@
+/** A single allowlisted (GitHub-hosted) media item attached to a highlight. */
+export interface ReleaseMedia {
+  url: string;
+  type: 'image' | 'video';
+}
+
+export interface ReleaseHighlight {
+  /** Lucide icon name parsed from an `<!-- icon: Name -->` comment (or legacy `[Name]` token), or null for the default icon. */
+  icon: string | null;
+  title: string;
+  body: string;
+  /** Allowlisted (GitHub-hosted) media in author order; images and videos interleaved. Empty if none. */
+  media: ReleaseMedia[];
+}
+
+export interface ReleaseNote {
+  /** Git tag, e.g. "v1.2.0". */
+  version: string;
+  /** Release title, or null. */
+  name: string | null;
+  /** ISO-8601 published date, or null. */
+  date: string | null;
+  highlights: ReleaseHighlight[];
+  /** Link to the full GitHub release page. */
+  changelogUrl: string;
+  /** Raw markdown changelog with the Highlights section removed, for inline rendering. */
+  changelogBody: string | null;
+}
+
+export interface ReleaseNotesResponse {
+  releases: ReleaseNote[];
+  /** Whether more releases exist beyond what was returned. */
+  hasMore: boolean;
+}
+
+export interface WhatsNewPreferences {
+  lastSeenVersion: string | null;
+  popupEnabled: boolean;
+}
diff --git a/release.config.js b/release.config.js
index 2d4ec8854..3757df6e5 100644
--- a/release.config.js
+++ b/release.config.js
@@ -51,6 +51,19 @@ const commitPartial = `\
 // strips the warning emoji from breaking-changes headings, and appends a
 // Docker pull block after the commit groups.
 const mainTemplate = [
+  "## Highlights",
+  "",
+  "<!-- Author: write 1 line per user-facing highlight ABOVE this comment, then delete this block.",
+  "     Full guide: docs/whats-new-authoring-guide.md",
+  "     Format:  - **Title** - short user benefit  {icon comment}",
+  "       - Optional icon: end the line with an HTML comment GitHub hides, using a PascalCase",
+  "         lucide.dev name, e.g. BookHeart. Omit it for the default icon. Literal syntax in the guide.",
+  "       - Image/video: drag the file in; leave GitHub's inserted <img> tag or bare URL as-is.",
+  "     Example:  - **Kobo highlight sync** - your highlights now sync both ways.  {icon: BookHeart}",
+  "     Validate before publishing: cd server && pnpm whats-new:check <tag>",
+  "     Leaving this comment in place (no bullets) means no What's New popup for this release.",
+  "{{{highlightCandidatesBlock}}}-->",
+  "",
   "{{#if noteGroups}}",
   "{{#each noteGroups}}",
   "",
@@ -142,15 +155,34 @@ function finalizeContext(ctx) {
           const githubUser = shaToGithubUser.get(commit.hash);
           if (githubUser) commit.githubUser = githubUser;
         }
-        // Pre-compute commit URL — {{commitUrlFormat}} does not resolve inside
+        // Pre-compute commit URL: {{commitUrlFormat}} does not resolve inside
         // Handlebars partials because partials don't walk the parent context chain.
         if (commit.hash && ctx.host && ctx.owner && ctx.repository) {
           commit.commitUrl = `${ctx.host}/${ctx.owner}/${ctx.repository}/commit/${commit.hash}`;
         }
       }
     }
+
+    // Collect this release's feat commits as candidate highlights for the author
+    // to curate. Rendered inside the scaffold's HTML comment (never shown publicly)
+    // as a pre-built string, so the comment never gains an inner "-->".
+    const candidates = [];
+    for (const group of ctx.commitGroups ?? []) {
+      if (group.title !== "Features") continue;
+      for (const commit of group.commits ?? []) {
+        const text = (commit.subject || commit.header || "").trim();
+        if (!text || text.includes("-->")) continue;
+        candidates.push(text.charAt(0).toUpperCase() + text.slice(1));
+        if (candidates.length >= 8) break;
+      }
+    }
+    ctx.highlightCandidatesBlock = candidates.length
+      ? "\n     Candidates from this release (curate the good ones into real bullets above, then delete):\n" +
+        candidates.map((c) => `       - **${c}**`).join("\n") +
+        "\n"
+      : "";
   } catch {
-    // non-fatal: commits render without author attribution
+    // non-fatal: commits render without author attribution / candidates
   }
   return ctx;
 }
@@ -188,6 +220,10 @@ module.exports = {
         },
       },
     ],
-    "@semantic-release/github",
+    // Create the GitHub release as a DRAFT so the maintainer can author the
+    // "## Highlights" section (see docs/whats-new-authoring-guide.md) before it
+    // goes public, then click "Publish release". The git tag and Docker images
+    // are still produced; BookOrbit hides draft releases until they are published.
+    ["@semantic-release/github", { draftRelease: true }],
   ],
 };
diff --git a/server/package.json b/server/package.json
index ddd0c7e4e..cc5d9da8f 100644
--- a/server/package.json
+++ b/server/package.json
@@ -33,6 +33,10 @@
     "e2e:db:prepare": "tsx src/scripts/db-prepare-e2e.ts",
     "db:studio": "drizzle-kit studio",
     "db:seed": "tsx src/scripts/db-seed.ts",
+    "whats-new:preview": "tsx src/scripts/whats-new-preview.ts",
+    "whats-new:lint": "tsx src/scripts/whats-new-lint.ts",
+    "whats-new:check": "tsx src/scripts/whats-new-check.ts",
+    "whats-new:images": "tsx src/scripts/whats-new-images.ts",
     "pretype-check": "pnpm --filter @bookorbit/types build",
     "type-check": "tsc --noEmit -p tsconfig.build.json",
     "lint": "pnpm run lint:check",
diff --git a/server/src/app.module.ts b/server/src/app.module.ts
index b6bc17076..9d5f72e69 100644
--- a/server/src/app.module.ts
+++ b/server/src/app.module.ts
@@ -60,6 +60,7 @@ import { EntityManagerModule } from './modules/entity-manager/entity-manager.mod
 import { FontModule } from './modules/font/font.module';
 import { KoreaderModule } from './modules/koreader/koreader.module';
 import { AppInfoModule } from './modules/app-info/app-info.module';
+import { ReleaseNotesModule } from './modules/release-notes/release-notes.module';
 import { AchievementModule } from './modules/achievement/achievement.module';
 import { HardcoverModule } from './modules/hardcover/hardcover.module';
 
@@ -130,6 +131,7 @@ import { HardcoverModule } from './modules/hardcover/hardcover.module';
     FontModule,
     KoreaderModule,
     AppInfoModule,
+    ReleaseNotesModule,
     AchievementModule,
     HardcoverModule,
   ],
diff --git a/server/src/config/config.test.ts b/server/src/config/config.test.ts
index 236c544fb..f5271fd77 100644
--- a/server/src/config/config.test.ts
+++ b/server/src/config/config.test.ts
@@ -43,6 +43,8 @@ describe('config', () => {
       nodeEnv: 'development',
       appUrl: 'http://localhost:5173',
       version: 'Local build',
+      githubReleasesRepo: 'bookorbit/bookorbit',
+      githubReleasesToken: undefined,
       oidcAllowLocalIssuers: false,
       koboCloudscraperPython: undefined,
     });
@@ -54,11 +56,15 @@ describe('config', () => {
     process.env.APP_VERSION = 'v2.3.4';
     process.env.OIDC_ALLOW_LOCAL_ISSUERS = 'true';
     process.env.KOBO_CLOUDSCRAPER_PYTHON = '/opt/bookorbit-python/bin/python';
+    process.env.GITHUB_RELEASES_REPO = 'acme/app';
+    process.env.GITHUB_RELEASES_TOKEN = 'ghp_example';
 
     expect(appConfig()).toEqual({
       nodeEnv: 'production',
       appUrl: 'https://bookorbit.local',
       version: 'v2.3.4',
+      githubReleasesRepo: 'acme/app',
+      githubReleasesToken: 'ghp_example',
       oidcAllowLocalIssuers: true,
       koboCloudscraperPython: '/opt/bookorbit-python/bin/python',
     });
diff --git a/server/src/config/config.ts b/server/src/config/config.ts
index f38ffd4ac..683ff5145 100644
--- a/server/src/config/config.ts
+++ b/server/src/config/config.ts
@@ -5,6 +5,8 @@ export const appConfig = registerAs('app', () => ({
   nodeEnv: process.env.NODE_ENV ?? 'development',
   appUrl: process.env.APP_URL ?? 'http://localhost:5173',
   version: process.env.APP_VERSION ?? 'Local build',
+  githubReleasesRepo: process.env.GITHUB_RELEASES_REPO?.trim() || 'bookorbit/bookorbit',
+  githubReleasesToken: process.env.GITHUB_RELEASES_TOKEN?.trim() || undefined,
   oidcAllowLocalIssuers: parseBooleanFlag(process.env.OIDC_ALLOW_LOCAL_ISSUERS, false),
   koboCloudscraperPython: process.env.KOBO_CLOUDSCRAPER_PYTHON?.trim() || undefined,
 }));
diff --git a/server/src/config/env.validation.ts b/server/src/config/env.validation.ts
index 60c01a20a..e3a5b7f80 100644
--- a/server/src/config/env.validation.ts
+++ b/server/src/config/env.validation.ts
@@ -63,6 +63,14 @@ const envSchema = z.object({
     .string()
     .transform((val) => val.trim())
     .optional(),
+  GITHUB_RELEASES_REPO: z
+    .string()
+    .transform((val) => val.trim())
+    .optional(),
+  GITHUB_RELEASES_TOKEN: z
+    .string()
+    .transform((val) => val.trim())
+    .optional(),
 });
 
 export function validateEnv(config: Record<string, unknown>) {
diff --git a/server/src/modules/release-notes/dto/release-notes-query.dto.ts b/server/src/modules/release-notes/dto/release-notes-query.dto.ts
new file mode 100644
index 000000000..8e41abb86
--- /dev/null
+++ b/server/src/modules/release-notes/dto/release-notes-query.dto.ts
@@ -0,0 +1,13 @@
+import { IsNumberString, IsOptional, IsString, MaxLength } from 'class-validator';
+
+export class ReleaseNotesQueryDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(50)
+  since?: string;
+
+  @IsOptional()
+  @IsNumberString()
+  @MaxLength(10)
+  page?: string;
+}
diff --git a/server/src/modules/release-notes/highlights.lint.test.ts b/server/src/modules/release-notes/highlights.lint.test.ts
new file mode 100644
index 000000000..d27e8317a
--- /dev/null
+++ b/server/src/modules/release-notes/highlights.lint.test.ts
@@ -0,0 +1,87 @@
+import { lintHighlights } from './highlights.lint';
+import { MAX_BODY_LENGTH, MAX_MEDIA_PER_HIGHLIGHT, MAX_TITLE_LENGTH } from './release-notes.constants';
+
+describe('lintHighlights', () => {
+  it('passes a well-formed section with no errors or warnings', () => {
+    const body = [
+      '## Highlights',
+      '- **Kobo sync** - syncs both ways now. <!-- icon: BookHeart -->',
+      '- **Faster scroll** - instant now. <!-- icon: Zap -->',
+    ].join('\n');
+    const r = lintHighlights(body);
+    expect(r.errors).toEqual([]);
+    expect(r.warnings).toEqual([]);
+    expect(r.highlightCount).toBe(2);
+  });
+
+  it('warns when a highlight uses the legacy [Icon] prefix', () => {
+    const body = '## Highlights\n- [BookHeart] **Kobo sync** - syncs both ways now.';
+    const r = lintHighlights(body);
+    expect(r.warnings.some((w) => w.includes('legacy') && w.includes('icon: BookHeart'))).toBe(true);
+    expect(r.highlightCount).toBe(1);
+  });
+
+  it('errors when there is no Highlights section', () => {
+    const r = lintHighlights('### Features\n- a fix');
+    expect(r.errors[0]).toContain('No "## Highlights" section');
+    expect(r.highlightCount).toBe(0);
+  });
+
+  it('errors when the section exists but no bullets parse', () => {
+    const r = lintHighlights('## Highlights\n\nsome prose but no bullets');
+    expect(r.errors.some((e) => e.includes('no valid bullets'))).toBe(true);
+  });
+
+  it('warns when an explicit image uses a non-allowlisted host', () => {
+    const body = ['## Highlights', '- **Thing** - body.', '![](https://imgur.com/x.png)'].join('\n');
+    const r = lintHighlights(body);
+    expect(r.warnings.some((w) => w.includes('dropped') && w.includes('imgur.com'))).toBe(true);
+  });
+
+  it('does not warn for an allowlisted image', () => {
+    const body = ['## Highlights', '- **Thing** - body.', '![](https://github.com/user-attachments/assets/abc)'].join('\n');
+    expect(lintHighlights(body).warnings).toEqual([]);
+  });
+
+  it('warns on a malformed icon token left in the title', () => {
+    const body = '## Highlights\n- [book heart] **Sync** - body.';
+    const r = lintHighlights(body);
+    expect(r.warnings.some((w) => w.includes('PascalCase'))).toBe(true);
+  });
+
+  it('warns on a highlight with no body text', () => {
+    const body = '## Highlights\n- **Title only** <!-- icon: Zap -->';
+    const r = lintHighlights(body);
+    expect(r.warnings.some((w) => w.includes('no description'))).toBe(true);
+  });
+
+  it('warns when an icon name is not a known lucide icon', () => {
+    const body = '## Highlights\n- **Sync** - body. <!-- icon: BookHart -->';
+    const r = lintHighlights(body);
+    expect(r.warnings.some((w) => w.includes('BookHart') && w.includes('not a known lucide icon'))).toBe(true);
+  });
+
+  it('does not warn for a valid lucide icon name', () => {
+    const body = '## Highlights\n- **Sync** - body. <!-- icon: BookHeart -->';
+    expect(lintHighlights(body).warnings).toEqual([]);
+  });
+
+  it('warns when a title exceeds the length cap', () => {
+    const body = `## Highlights\n- **${'a'.repeat(MAX_TITLE_LENGTH + 10)}** - body.`;
+    const r = lintHighlights(body);
+    expect(r.warnings.some((w) => w.includes('title is') && w.includes('clamped'))).toBe(true);
+  });
+
+  it('warns when a body exceeds the length cap', () => {
+    const body = `## Highlights\n- **Title** - ${'b'.repeat(MAX_BODY_LENGTH + 10)}`;
+    const r = lintHighlights(body);
+    expect(r.warnings.some((w) => w.includes('body is') && w.includes('clamped'))).toBe(true);
+  });
+
+  it('warns when a highlight has more media than the cap', () => {
+    const lines = ['## Highlights', '- **Many** - lots of shots.'];
+    for (let i = 0; i < MAX_MEDIA_PER_HIGHLIGHT + 2; i++) lines.push(`![](https://github.com/user-attachments/assets/img-${i})`);
+    const r = lintHighlights(lines.join('\n'));
+    expect(r.warnings.some((w) => w.includes('media items') && w.includes(`first ${MAX_MEDIA_PER_HIGHLIGHT}`))).toBe(true);
+  });
+});
diff --git a/server/src/modules/release-notes/highlights.lint.ts b/server/src/modules/release-notes/highlights.lint.ts
new file mode 100644
index 000000000..9143ea572
--- /dev/null
+++ b/server/src/modules/release-notes/highlights.lint.ts
@@ -0,0 +1,75 @@
+import { extractHighlightsBlock, findExplicitMediaUrls, isAllowedImageHost, parseHighlightEntries } from './highlights.parser';
+import { LUCIDE_ICON_NAMES } from './lucide-icon-names';
+import { MAX_BODY_LENGTH, MAX_MEDIA_PER_HIGHLIGHT, MAX_TITLE_LENGTH } from './release-notes.constants';
+
+const LEGACY_ICON_BULLET_RE = /^\s*[-*]\s+\[[A-Za-z][A-Za-z0-9]*\]/;
+
+export interface HighlightsLintResult {
+  errors: string[];
+  warnings: string[];
+  highlightCount: number;
+}
+
+/**
+ * Validate the `## Highlights` text of a release body (static, no network), using the same
+ * parser the app uses. Errors mean "the popup won't render correctly"; warnings are likely mistakes.
+ */
+export function lintHighlights(body: string | null | undefined): HighlightsLintResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const block = extractHighlightsBlock(body ?? '');
+  if (block === null) {
+    errors.push('No "## Highlights" section found. Add a heading exactly like "## Highlights".');
+    return { errors, warnings, highlightCount: 0 };
+  }
+
+  const entries = parseHighlightEntries(body);
+  if (entries.length === 0) {
+    errors.push('A "## Highlights" section exists but no valid bullets were parsed. Each highlight must be a line starting with "- ".');
+  }
+
+  for (const url of findExplicitMediaUrls(block.join('\n'))) {
+    if (!isAllowedImageHost(url)) {
+      warnings.push(
+        `Media will be dropped (host not allowed): ${url}. Use a GitHub user-attachments or githubusercontent URL (drag-drop into the release).`,
+      );
+    }
+  }
+
+  if (block.some((line) => LEGACY_ICON_BULLET_RE.test(line))) {
+    warnings.push(
+      'A highlight uses the legacy "[Icon]" prefix, which renders as literal "[Icon]" text on the GitHub release page. Move the icon into a trailing comment instead, e.g. "- **Title** - body. <!-- icon: BookHeart -->".',
+    );
+  }
+
+  entries.forEach(({ highlight: h, mediaCount }, i) => {
+    const n = i + 1;
+    if (h.icon && !LUCIDE_ICON_NAMES.has(h.icon)) {
+      warnings.push(
+        `Highlight ${n} icon "${h.icon}" is not a known lucide icon; it will fall back to the default Sparkles icon. Check the spelling/casing at lucide.dev/icons.`,
+      );
+    }
+    if (/\[[A-Za-z][^\]]*\]/.test(h.title)) {
+      warnings.push(`Highlight ${n} title contains an unrecognized "[...]" token: "${h.title}". Icon tokens must be PascalCase, e.g. [BookHeart].`);
+    }
+    if (!h.body.trim()) {
+      warnings.push(`Highlight ${n} ("${h.title}") has a title but no description text after " - ".`);
+    }
+    if (h.title.length > MAX_TITLE_LENGTH) {
+      warnings.push(
+        `Highlight ${n} title is ${h.title.length} chars (cap ${MAX_TITLE_LENGTH}); it will be visually clamped in the popup. Consider shortening it.`,
+      );
+    }
+    if (h.body.length > MAX_BODY_LENGTH) {
+      warnings.push(
+        `Highlight ${n} body is ${h.body.length} chars (cap ${MAX_BODY_LENGTH}); it will be visually clamped in the popup. Consider shortening it.`,
+      );
+    }
+    if (mediaCount > MAX_MEDIA_PER_HIGHLIGHT) {
+      warnings.push(`Highlight ${n} has ${mediaCount} media items; only the first ${MAX_MEDIA_PER_HIGHLIGHT} will render. Remove the extras.`);
+    }
+  });
+
+  return { errors, warnings, highlightCount: entries.length };
+}
diff --git a/server/src/modules/release-notes/highlights.parser.test.ts b/server/src/modules/release-notes/highlights.parser.test.ts
new file mode 100644
index 000000000..5b420cf99
--- /dev/null
+++ b/server/src/modules/release-notes/highlights.parser.test.ts
@@ -0,0 +1,207 @@
+import { isAllowedImageHost, parseHighlights, stripHighlightsSection } from './highlights.parser';
+import { MAX_MEDIA_PER_HIGHLIGHT } from './release-notes.constants';
+
+const ATTACH = 'https://github.com/user-attachments/assets';
+
+describe('parseHighlights', () => {
+  it('parses a well-formed bullet with a trailing icon comment, title and body', () => {
+    const body = ['## Highlights', '- **Kobo sync** - syncs both ways now. <!-- icon: BookHeart -->', '', '### Features', '- something'].join('\n');
+    expect(parseHighlights(body)).toEqual([{ icon: 'BookHeart', title: 'Kobo sync', body: 'syncs both ways now.', media: [] }]);
+  });
+
+  it('reads an icon comment on a continuation line', () => {
+    const body = ['## Highlights', '- **Kobo sync** - syncs both ways now.', '  <!-- icon: BookHeart -->'].join('\n');
+    expect(parseHighlights(body)[0]).toEqual({ icon: 'BookHeart', title: 'Kobo sync', body: 'syncs both ways now.', media: [] });
+  });
+
+  it('matches the icon comment case-insensitively and trims whitespace', () => {
+    const body = '## Highlights\n- **Thing** - body. <!--   ICON:  Zap   -->';
+    expect(parseHighlights(body)[0].icon).toBe('Zap');
+  });
+
+  it('never leaks the icon comment into the rendered title or body', () => {
+    const body = '## Highlights\n- **Hardened** - safer now. <!-- icon: ShieldCheck -->';
+    const result = parseHighlights(body)[0];
+    expect(result.title).toBe('Hardened');
+    expect(result.body).toBe('safer now.');
+    expect(result.icon).toBe('ShieldCheck');
+  });
+
+  it('still parses the legacy leading [Icon] token (old published releases)', () => {
+    const body = ['## Highlights', '- [BookHeart] **Kobo sync** - syncs both ways now.'].join('\n');
+    expect(parseHighlights(body)).toEqual([{ icon: 'BookHeart', title: 'Kobo sync', body: 'syncs both ways now.', media: [] }]);
+  });
+
+  it('prefers the icon comment over a legacy token when both are present', () => {
+    const body = '## Highlights\n- [Zap] **Thing** - body. <!-- icon: BookHeart -->';
+    expect(parseHighlights(body)[0].icon).toBe('BookHeart');
+  });
+
+  it('returns [] when there is no Highlights section', () => {
+    expect(parseHighlights('### Features\n- a fix')).toEqual([]);
+    expect(parseHighlights('')).toEqual([]);
+    expect(parseHighlights(null)).toEqual([]);
+    expect(parseHighlights(undefined)).toEqual([]);
+  });
+
+  it('defaults a missing icon token to null', () => {
+    const body = '## Highlights\n- **Minor polish** - small tweaks.';
+    expect(parseHighlights(body)).toEqual([{ icon: null, title: 'Minor polish', body: 'small tweaks.', media: [] }]);
+  });
+
+  it('passes an unknown icon name through (the lint and client safelist it)', () => {
+    const body = '## Highlights\n- [TotallyNotALucideIcon] **Thing** - body.';
+    expect(parseHighlights(body)[0].icon).toBe('TotallyNotALucideIcon');
+  });
+
+  it('is tolerant of a bullet without a bold title', () => {
+    const body = '## Highlights\n- just some plain text';
+    expect(parseHighlights(body)).toEqual([{ icon: null, title: 'just some plain text', body: '', media: [] }]);
+  });
+
+  it('keeps an allowlisted image as a single media item', () => {
+    const body = ['## Highlights', '- [Zap] **Fast** - speed.', `  ![](${ATTACH}/abc-123)`].join('\n');
+    expect(parseHighlights(body)[0]).toEqual({
+      icon: 'Zap',
+      title: 'Fast',
+      body: 'speed.',
+      media: [{ url: `${ATTACH}/abc-123`, type: 'image' }],
+    });
+  });
+
+  it('classifies an allowlisted media URL with a video extension as a video media item', () => {
+    const body = ['## Highlights', '- [Film] **Demo** - watch it.', '  ![](https://raw.githubusercontent.com/o/r/main/demo.mp4)'].join('\n');
+    const result = parseHighlights(body)[0];
+    expect(result.media).toEqual([{ url: 'https://raw.githubusercontent.com/o/r/main/demo.mp4', type: 'video' }]);
+    expect(result.title).toBe('Demo');
+  });
+
+  it('extracts the clean src from a GitHub <img> HTML tag (no trailing quote)', () => {
+    const body = [
+      '## Highlights',
+      '- [Shield] **Hardened** - safer now.',
+      '',
+      `<img width="800" height="450" alt="x" src="${ATTACH}/b7a04eef" />`,
+    ].join('\n');
+    const result = parseHighlights(body)[0];
+    expect(result.media).toEqual([{ url: `${ATTACH}/b7a04eef`, type: 'image' }]);
+    expect(result.title).toBe('Hardened');
+    expect(result.body).toBe('safer now.');
+  });
+
+  it('collects multiple media under one bullet in document order, classifying each', () => {
+    const body = [
+      '## Highlights',
+      '- **Gallery** - three shots.',
+      `  <img src="${ATTACH}/one" />`,
+      `  ![](${ATTACH}/two)`,
+      `  ${ATTACH}/three.mp4`,
+    ].join('\n');
+    expect(parseHighlights(body)[0].media).toEqual([
+      { url: `${ATTACH}/one`, type: 'image' },
+      { url: `${ATTACH}/two`, type: 'image' },
+      { url: `${ATTACH}/three.mp4`, type: 'video' },
+    ]);
+  });
+
+  it('de-duplicates a markdown image (markdown link + bare URL match the same URL)', () => {
+    const body = ['## Highlights', '- **One** - x.', `  ![](${ATTACH}/abc)`].join('\n');
+    expect(parseHighlights(body)[0].media).toEqual([{ url: `${ATTACH}/abc`, type: 'image' }]);
+  });
+
+  it('drops non-allowlisted media while keeping allowlisted media (and the text)', () => {
+    const body = ['## Highlights', '- **Fast** - speed. ![](https://evil.example.com/tracker.png)', `  ![](${ATTACH}/good)`].join('\n');
+    const result = parseHighlights(body)[0];
+    expect(result.media).toEqual([{ url: `${ATTACH}/good`, type: 'image' }]);
+    expect(result.title).toBe('Fast');
+    expect(result.body).toBe('speed.');
+  });
+
+  it('strips media markup from the title/body when media shares the bullet line', () => {
+    const body = `## Highlights\n- **Fast** - speed. ![](${ATTACH}/abc)`;
+    const result = parseHighlights(body)[0];
+    expect(result.title).toBe('Fast');
+    expect(result.body).toBe('speed.');
+    expect(result.media).toEqual([{ url: `${ATTACH}/abc`, type: 'image' }]);
+  });
+
+  it(`caps media per highlight at MAX_MEDIA_PER_HIGHLIGHT (${MAX_MEDIA_PER_HIGHLIGHT}), keeping the first in order`, () => {
+    const lines = ['## Highlights', '- **Many** - lots of shots.'];
+    for (let i = 0; i < MAX_MEDIA_PER_HIGHLIGHT + 3; i++) lines.push(`  ![](${ATTACH}/img-${i})`);
+    const media = parseHighlights(lines.join('\n'))[0].media;
+    expect(media).toHaveLength(MAX_MEDIA_PER_HIGHLIGHT);
+    expect(media[0].url).toBe(`${ATTACH}/img-0`);
+    expect(media[MAX_MEDIA_PER_HIGHLIGHT - 1].url).toBe(`${ATTACH}/img-${MAX_MEDIA_PER_HIGHLIGHT - 1}`);
+  });
+
+  it('ignores an unfilled HTML-comment scaffold', () => {
+    const body = [
+      '## Highlights',
+      '<!-- Author: 1 line per highlight, then delete this comment.',
+      '     - [LucideIcon] **Title** - short user benefit -->',
+      '',
+      '### Features',
+      '- x',
+    ].join('\n');
+    expect(parseHighlights(body)).toEqual([]);
+  });
+
+  it('fully strips a multi-line author comment even when it mentions an icon marker', () => {
+    const body = [
+      '## Highlights',
+      '<!-- Author: 1 line per highlight; end a line with an icon comment, e.g.',
+      '       - Add an icon like icon: BookHeart',
+      '       - Image/video: drag the file in -->',
+      '',
+      '### Features',
+      '- x',
+    ].join('\n');
+    expect(parseHighlights(body)).toEqual([]);
+  });
+
+  it('stops at the next heading or horizontal rule', () => {
+    const body = ['## Highlights', '- **One** - first.', '', '---', '**Docker**', '- not a highlight'].join('\n');
+    expect(parseHighlights(body)).toEqual([{ icon: null, title: 'One', body: 'first.', media: [] }]);
+  });
+
+  it('parses CRLF bodies (GitHub web-editor line endings)', () => {
+    const body = ['## Highlights', '- [BookHeart] **Kobo sync** - both ways now.', '', `${ATTACH}/abc`, '', '### Features', '- f'].join('\r\n');
+    const result = parseHighlights(body);
+    expect(result).toHaveLength(1);
+    expect(result[0].title).toBe('Kobo sync');
+    expect(result[0].body).toBe('both ways now.');
+    expect(result[0].media).toEqual([{ url: `${ATTACH}/abc`, type: 'image' }]);
+  });
+
+  it('parses multiple highlights in order', () => {
+    const body = ['## Highlights', '- [BookHeart] **A** - one.', '- [Zap] **B** - two.', '- **C** - three.'].join('\n');
+    expect(parseHighlights(body).map((h) => h.title)).toEqual(['A', 'B', 'C']);
+  });
+});
+
+describe('stripHighlightsSection', () => {
+  it('removes the Highlights block but keeps the changelog', () => {
+    const body = ['## Highlights', '- **A** - one.', '', '### Features', '- a feature'].join('\n');
+    expect(stripHighlightsSection(body)).toBe('### Features\n- a feature');
+  });
+
+  it('returns null when nothing remains', () => {
+    expect(stripHighlightsSection('## Highlights\n- **A** - one.')).toBeNull();
+    expect(stripHighlightsSection(null)).toBeNull();
+  });
+});
+
+describe('isAllowedImageHost', () => {
+  it('allows GitHub attachment hosts', () => {
+    expect(isAllowedImageHost('https://github.com/user-attachments/assets/x')).toBe(true);
+    expect(isAllowedImageHost('https://user-images.githubusercontent.com/1/x.png')).toBe(true);
+    expect(isAllowedImageHost('https://private-user-images.githubusercontent.com/1/x.png')).toBe(true);
+  });
+
+  it('rejects other hosts, non-https, and github non-attachment paths', () => {
+    expect(isAllowedImageHost('https://evil.example.com/x.png')).toBe(false);
+    expect(isAllowedImageHost('http://github.com/user-attachments/assets/x')).toBe(false);
+    expect(isAllowedImageHost('https://github.com/bookorbit/bookorbit/raw/main/x.png')).toBe(false);
+    expect(isAllowedImageHost('not a url')).toBe(false);
+  });
+});
diff --git a/server/src/modules/release-notes/highlights.parser.ts b/server/src/modules/release-notes/highlights.parser.ts
new file mode 100644
index 000000000..7cbe458af
--- /dev/null
+++ b/server/src/modules/release-notes/highlights.parser.ts
@@ -0,0 +1,186 @@
+import type { ReleaseHighlight, ReleaseMedia } from '@bookorbit/types';
+
+import { MAX_HIGHLIGHTS_PER_RELEASE, MAX_MEDIA_PER_HIGHLIGHT } from './release-notes.constants';
+
+const HEADING_RE = /^#{1,6}\s+/;
+const HEADING_TEXT_RE = /^#{1,6}\s+(.+?)\s*$/;
+const HR_RE = /^\s*([-*_])\1{2,}\s*$/;
+const BULLET_RE = /^\s*[-*]\s+(.+)$/;
+// Primary icon carrier: an HTML comment GitHub renders as nothing, e.g. `<!-- icon: BookHeart -->`.
+const ICON_COMMENT_RE = /<!--\s*icon:\s*([A-Za-z][A-Za-z0-9]*)\s*-->/i;
+// Anchored form: the whole comment IS an icon marker (not a larger comment that merely mentions one).
+const ICON_COMMENT_ONLY_RE = /^<!--\s*icon:\s*[A-Za-z][A-Za-z0-9]*\s*-->$/i;
+// Legacy carrier: a leading `[BookHeart]` token (renders as literal text on GitHub; kept for old releases).
+const ICON_TOKEN_RE = /^\[([A-Za-z][A-Za-z0-9]*)\]\s*/;
+const BOLD_TITLE_RE = /^\*\*(.+?)\*\*\s*/;
+// Matches both `![alt](url)` and `[label](url)`.
+const MEDIA_LINK_RE = /!?\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+// Explicit image/video markup only (`![](url)`), used by the linter to flag dropped media.
+const IMAGE_MD_RE = /!\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+// GitHub's web editor inserts dropped images as `<img ... src="...">` (and video sources similarly).
+const HTML_MEDIA_SRC_RE = /<(?:img|video|source)\b[^>]*?\bsrc=["']([^"']+)["']/gi;
+const HTML_TAG_RE = /<[^>]+>/g;
+const BARE_URL_RE = /https?:\/\/[^\s)"'<>\]]+/g;
+const VIDEO_EXT_RE = /\.(mp4|webm|mov|m4v|ogv|ogg)(?:[?#].*)?$/i;
+const LEADING_SEP_RE = /^\s*[-:–—]\s*/;
+
+/** Strip HTML comments but preserve standalone `<!-- icon: X -->` markers so the parser can read the icon. */
+function stripHtmlComments(text: string): string {
+  return text.replace(/<!--[\s\S]*?-->/g, (m) => (ICON_COMMENT_ONLY_RE.test(m.trim()) ? m : ''));
+}
+
+function isHighlightsHeading(line: string): boolean {
+  const m = line.match(HEADING_TEXT_RE);
+  if (!m) return false;
+  return m[1].replace(/[^a-zA-Z]/g, '').toLowerCase() === 'highlights';
+}
+
+/** Only render media served from GitHub's own attachment hosts. */
+export function isAllowedImageHost(url: string): boolean {
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'https:') return false;
+    const host = u.hostname.toLowerCase();
+    if (host === 'github.com') return u.pathname.startsWith('/user-attachments/');
+    return host === 'githubusercontent.com' || host.endsWith('.githubusercontent.com');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * All allowlisted media in a block, in source order, de-duplicated, classified image/video by
+ * extension. Ordering is by position in the text so interleaved `<img>`, `![](url)`, and bare URLs
+ * keep the order the author wrote them. The three syntaxes can each match the same URL (e.g. a bare
+ * URL inside a markdown image); the earliest-positioned occurrence wins via the `seen` set.
+ */
+function orderedAllowlistedMedia(text: string): ReleaseMedia[] {
+  const found: { url: string; index: number }[] = [];
+  for (const m of text.matchAll(HTML_MEDIA_SRC_RE)) found.push({ url: m[1], index: m.index ?? 0 });
+  for (const m of text.matchAll(MEDIA_LINK_RE)) found.push({ url: m[1], index: m.index ?? 0 });
+  for (const m of text.matchAll(BARE_URL_RE)) found.push({ url: m[0], index: m.index ?? 0 });
+  found.sort((a, b) => a.index - b.index);
+
+  const media: ReleaseMedia[] = [];
+  const seen = new Set<string>();
+  for (const { url } of found) {
+    if (seen.has(url) || !isAllowedImageHost(url)) continue;
+    seen.add(url);
+    media.push({ url, type: VIDEO_EXT_RE.test(url) ? 'video' : 'image' });
+  }
+  return media;
+}
+
+/** URLs from explicit media markup (`<img>/<video>` tags and `![](url)`), for lint host-validation. */
+export function findExplicitMediaUrls(text: string): string[] {
+  const urls: string[] = [];
+  for (const m of text.matchAll(HTML_MEDIA_SRC_RE)) urls.push(m[1]);
+  for (const m of text.matchAll(IMAGE_MD_RE)) urls.push(m[1]);
+  return urls;
+}
+
+export function extractHighlightsBlock(body: string): string[] | null {
+  const lines = stripHtmlComments(body).split(/\r?\n/);
+  const start = lines.findIndex(isHighlightsHeading);
+  if (start === -1) return null;
+
+  const block: string[] = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (HEADING_RE.test(line) || HR_RE.test(line)) break;
+    block.push(line);
+  }
+  return block;
+}
+
+/** A parsed highlight plus its uncapped allowlisted media count, used by the linter for cap warnings. */
+export interface ParsedHighlight {
+  highlight: ReleaseHighlight;
+  /** Total allowlisted media on the bullet before the `MAX_MEDIA_PER_HIGHLIGHT` cap is applied. */
+  mediaCount: number;
+}
+
+/**
+ * Parse the `## Highlights` section into highlights paired with their uncapped media count.
+ * Tolerant: missing section -> []; missing/unknown icon -> null; malformed bullet -> skipped;
+ * non-allowlisted image -> dropped (text kept); HTML-comment scaffold -> ignored.
+ */
+export function parseHighlightEntries(body: string | null | undefined): ParsedHighlight[] {
+  if (!body) return [];
+  const block = extractHighlightsBlock(body);
+  if (!block) return [];
+
+  const entries: { text: string; cont: string }[] = [];
+  for (const line of block) {
+    const bullet = line.match(BULLET_RE);
+    if (bullet) {
+      entries.push({ text: bullet[1].trim(), cont: '' });
+    } else if (entries.length > 0) {
+      entries[entries.length - 1].cont += `\n${line}`;
+    }
+  }
+
+  const result: ParsedHighlight[] = [];
+  for (const entry of entries) {
+    const combined = `${entry.text}\n${entry.cont}`;
+    const allMedia = orderedAllowlistedMedia(combined);
+    const media = allMedia.slice(0, MAX_MEDIA_PER_HIGHLIGHT);
+
+    // Prefer the `<!-- icon: X -->` comment (invisible on GitHub); fall back to a legacy `[X]` token.
+    let icon: string | null = null;
+    const iconComment = combined.match(ICON_COMMENT_RE);
+    if (iconComment) icon = iconComment[1];
+
+    let text = entry.text.replace(HTML_TAG_RE, '').replace(MEDIA_LINK_RE, '').replace(BARE_URL_RE, '').trim();
+
+    const tokenMatch = text.match(ICON_TOKEN_RE);
+    if (tokenMatch) {
+      if (!icon) icon = tokenMatch[1];
+      text = text.slice(tokenMatch[0].length);
+    }
+
+    let title: string;
+    let highlightBody = '';
+    const boldMatch = text.match(BOLD_TITLE_RE);
+    if (boldMatch) {
+      title = boldMatch[1].trim();
+      highlightBody = text.slice(boldMatch[0].length).replace(LEADING_SEP_RE, '').trim();
+    } else {
+      title = text.replace(/\*\*/g, '').replace(LEADING_SEP_RE, '').trim();
+    }
+
+    if (!title) continue;
+
+    result.push({ highlight: { icon, title, body: highlightBody, media }, mediaCount: allMedia.length });
+    if (result.length >= MAX_HIGHLIGHTS_PER_RELEASE) break;
+  }
+
+  return result;
+}
+
+/** Structured highlights for the `## Highlights` section of a release body. */
+export function parseHighlights(body: string | null | undefined): ReleaseHighlight[] {
+  return parseHighlightEntries(body).map((e) => e.highlight);
+}
+
+/** Return the release body with the Highlights section removed, for the inline changelog. */
+export function stripHighlightsSection(body: string | null | undefined): string | null {
+  if (!body) return null;
+  const lines = body.split(/\r?\n/);
+  const out: string[] = [];
+  let removed = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (!removed && isHighlightsHeading(lines[i])) {
+      i++;
+      while (i < lines.length && !HEADING_RE.test(lines[i]) && !HR_RE.test(lines[i])) i++;
+      i--;
+      removed = true;
+      continue;
+    }
+    out.push(lines[i]);
+  }
+
+  const result = out.join('\n').trim();
+  return result.length ? result : null;
+}
diff --git a/server/src/modules/release-notes/lucide-icon-names.ts b/server/src/modules/release-notes/lucide-icon-names.ts
new file mode 100644
index 000000000..f030a7101
--- /dev/null
+++ b/server/src/modules/release-notes/lucide-icon-names.ts
@@ -0,0 +1,11 @@
+// AUTO-GENERATED from lucide-vue-next@1.0.0 (the version the client renders icons from).
+// The lint validates authored icon names against this set so typos are caught before publishing.
+// Do not edit by hand. Regenerate after bumping lucide-vue-next by re-running the generator
+// that reads `client/node_modules/lucide-vue-next/dist/lucide-vue-next.d.ts` and extracts every
+// `declare const <Name>: vue.FunctionalComponent` entry (see PR adding this feature).
+
+/** PascalCase lucide icon component names (1704 icons). */
+const NAMES =
+  'AArrowDown AArrowUp ALargeSmall Accessibility Activity AirVent Airplay AlarmClock AlarmClockCheck AlarmClockMinus AlarmClockOff AlarmClockPlus AlarmSmoke Album AlignCenterHorizontal AlignCenterVertical AlignEndHorizontal AlignEndVertical AlignHorizontalDistributeCenter AlignHorizontalDistributeEnd AlignHorizontalDistributeStart AlignHorizontalJustifyCenter AlignHorizontalJustifyEnd AlignHorizontalJustifyStart AlignHorizontalSpaceAround AlignHorizontalSpaceBetween AlignStartHorizontal AlignStartVertical AlignVerticalDistributeCenter AlignVerticalDistributeEnd AlignVerticalDistributeStart AlignVerticalJustifyCenter AlignVerticalJustifyEnd AlignVerticalJustifyStart AlignVerticalSpaceAround AlignVerticalSpaceBetween Ambulance Ampersand Ampersands Amphora Anchor Angry Annoyed Antenna Anvil Aperture AppWindow AppWindowMac Apple Archive ArchiveRestore ArchiveX Armchair ArrowBigDown ArrowBigDownDash ArrowBigLeft ArrowBigLeftDash ArrowBigRight ArrowBigRightDash ArrowBigUp ArrowBigUpDash ArrowDown ArrowDown01 ArrowDown10 ArrowDownAZ ArrowDownFromLine ArrowDownLeft ArrowDownNarrowWide ArrowDownRight ArrowDownToDot ArrowDownToLine ArrowDownUp ArrowDownWideNarrow ArrowDownZA ArrowLeft ArrowLeftFromLine ArrowLeftRight ArrowLeftToLine ArrowRight ArrowRightFromLine ArrowRightLeft ArrowRightToLine ArrowUp ArrowUp01 ArrowUp10 ArrowUpAZ ArrowUpDown ArrowUpFromDot ArrowUpFromLine ArrowUpLeft ArrowUpNarrowWide ArrowUpRight ArrowUpToLine ArrowUpWideNarrow ArrowUpZA ArrowsUpFromLine Asterisk AtSign Atom AudioLines AudioWaveform Award Axe Axis3d Baby Backpack Badge BadgeAlert BadgeCent BadgeCheck BadgeDollarSign BadgeEuro BadgeIndianRupee BadgeInfo BadgeJapaneseYen BadgeMinus BadgePercent BadgePlus BadgePoundSterling BadgeQuestionMark BadgeRussianRuble BadgeSwissFranc BadgeTurkishLira BadgeX BaggageClaim Balloon Ban Banana Bandage Banknote BanknoteArrowDown BanknoteArrowUp BanknoteX Barcode Barrel Baseline Bath Battery BatteryCharging BatteryFull BatteryLow BatteryMedium BatteryPlus BatteryWarning Beaker Bean BeanOff Bed BedDouble BedSingle Beef Beer BeerOff Bell BellDot BellElectric BellMinus BellOff BellPlus BellRing BetweenHorizontalEnd BetweenHorizontalStart BetweenVerticalEnd BetweenVerticalStart BicepsFlexed Bike Binary Binoculars Biohazard Bird Birdhouse Bitcoin Blend Blinds Blocks Bluetooth BluetoothConnected BluetoothOff BluetoothSearching Bold Bolt Bomb Bone Book BookA BookAlert BookAudio BookCheck BookCopy BookDashed BookDown BookHeadphones BookHeart BookImage BookKey BookLock BookMarked BookMinus BookOpen BookOpenCheck BookOpenText BookPlus BookSearch BookText BookType BookUp BookUp2 BookUser BookX Bookmark BookmarkCheck BookmarkMinus BookmarkPlus BookmarkX BoomBox Bot BotMessageSquare BotOff BottleWine BowArrow Box Boxes Braces Brackets Brain BrainCircuit BrainCog BrickWall BrickWallFire BrickWallShield Briefcase BriefcaseBusiness BriefcaseConveyorBelt BriefcaseMedical BringToFront Brush BrushCleaning Bubbles Bug BugOff BugPlay Building Building2 Bus BusFront Cable CableCar Cake CakeSlice Calculator Calendar Calendar1 CalendarArrowDown CalendarArrowUp CalendarCheck CalendarCheck2 CalendarClock CalendarCog CalendarDays CalendarFold CalendarHeart CalendarMinus CalendarMinus2 CalendarOff CalendarPlus CalendarPlus2 CalendarRange CalendarSearch CalendarSync CalendarX CalendarX2 Calendars Camera CameraOff Candy CandyCane CandyOff Cannabis CannabisOff Captions CaptionsOff Car CarFront CarTaxiFront Caravan CardSim Carrot CaseLower CaseSensitive CaseUpper CassetteTape Cast Castle Cat Cctv CctvOff ChartArea ChartBar ChartBarBig ChartBarDecreasing ChartBarIncreasing ChartBarStacked ChartCandlestick ChartColumn ChartColumnBig ChartColumnDecreasing ChartColumnIncreasing ChartColumnStacked ChartGantt ChartLine ChartNetwork ChartNoAxesColumn ChartNoAxesColumnDecreasing ChartNoAxesColumnIncreasing ChartNoAxesCombined ChartNoAxesGantt ChartPie ChartScatter ChartSpline Check CheckCheck CheckLine ChefHat Cherry ChessBishop ChessKing ChessKnight ChessPawn ChessQueen ChessRook ChevronDown ChevronFirst ChevronLast ChevronLeft ChevronRight ChevronUp ChevronsDown ChevronsDownUp ChevronsLeft ChevronsLeftRight ChevronsLeftRightEllipsis ChevronsRight ChevronsRightLeft ChevronsUp ChevronsUpDown Chromium Church Cigarette CigaretteOff Circle CircleAlert CircleArrowDown CircleArrowLeft CircleArrowOutDownLeft CircleArrowOutDownRight CircleArrowOutUpLeft CircleArrowOutUpRight CircleArrowRight CircleArrowUp CircleCheck CircleCheckBig CircleChevronDown CircleChevronLeft CircleChevronRight CircleChevronUp CircleDashed CircleDivide CircleDollarSign CircleDot CircleDotDashed CircleEllipsis CircleEqual CircleFadingArrowUp CircleFadingPlus CircleGauge CircleMinus CircleOff CircleParking CircleParkingOff CirclePause CirclePercent CirclePile CirclePlay CirclePlus CirclePoundSterling CirclePower CircleQuestionMark CircleSlash CircleSlash2 CircleSmall CircleStar CircleStop CircleUser CircleUserRound CircleX CircuitBoard Citrus Clapperboard Clipboard ClipboardCheck ClipboardClock ClipboardCopy ClipboardList ClipboardMinus ClipboardPaste ClipboardPen ClipboardPenLine ClipboardPlus ClipboardType ClipboardX Clock Clock1 Clock10 Clock11 Clock12 Clock2 Clock3 Clock4 Clock5 Clock6 Clock7 Clock8 Clock9 ClockAlert ClockArrowDown ClockArrowUp ClockCheck ClockFading ClockPlus ClosedCaption Cloud CloudAlert CloudBackup CloudCheck CloudCog CloudDownload CloudDrizzle CloudFog CloudHail CloudLightning CloudMoon CloudMoonRain CloudOff CloudRain CloudRainWind CloudSnow CloudSun CloudSunRain CloudSync CloudUpload Cloudy Clover Club Code CodeXml Codepen Codesandbox Coffee Cog Coins Columns2 Columns3 Columns3Cog Columns4 Combine Command Compass Component Computer ConciergeBell Cone Construction Contact ContactRound Container Contrast Cookie CookingPot Copy CopyCheck CopyMinus CopyPlus CopySlash CopyX Copyleft Copyright CornerDownLeft CornerDownRight CornerLeftDown CornerLeftUp CornerRightDown CornerRightUp CornerUpLeft CornerUpRight Cpu CreativeCommons CreditCard Croissant Crop Cross Crosshair Crown Cuboid CupSoda Currency Cylinder Dam Database DatabaseBackup DatabaseSearch DatabaseZap DecimalsArrowLeft DecimalsArrowRight Delete Dessert Diameter Diamond DiamondMinus DiamondPercent DiamondPlus Dice1 Dice2 Dice3 Dice4 Dice5 Dice6 Dices Diff Disc Disc2 Disc3 DiscAlbum Divide Dna DnaOff Dock Dog DollarSign Donut DoorClosed DoorClosedLocked DoorOpen Dot Download DraftingCompass Drama Dribbble Drill Drone Droplet DropletOff Droplets Drum Drumstick Dumbbell Ear EarOff Earth EarthLock Eclipse Egg EggFried EggOff Ellipse Ellipsis EllipsisVertical Equal EqualApproximately EqualNot Eraser EthernetPort Euro EvCharger Expand ExternalLink Eye EyeClosed EyeOff Facebook Factory Fan FastForward Feather Fence FerrisWheel Figma File FileArchive FileAxis3d FileBadge FileBox FileBraces FileBracesCorner FileChartColumn FileChartColumnIncreasing FileChartLine FileChartPie FileCheck FileCheckCorner FileClock FileCode FileCodeCorner FileCog FileDiff FileDigit FileDown FileExclamationPoint FileHeadphone FileHeart FileImage FileInput FileKey FileLock FileMinus FileMinusCorner FileMusic FileOutput FilePen FilePenLine FilePlay FilePlus FilePlusCorner FileQuestionMark FileScan FileSearch FileSearchCorner FileSignal FileSliders FileSpreadsheet FileStack FileSymlink FileTerminal FileText FileType FileTypeCorner FileUp FileUser FileVideoCamera FileVolume FileX FileXCorner Files Film FingerprintPattern FireExtinguisher Fish FishOff FishSymbol FishingHook FishingRod Flag FlagOff FlagTriangleLeft FlagTriangleRight Flame FlameKindling Flashlight FlashlightOff FlaskConical FlaskConicalOff FlaskRound FlipHorizontal2 FlipVertical2 Flower Flower2 Focus FoldHorizontal FoldVertical Folder FolderArchive FolderCheck FolderClock FolderClosed FolderCode FolderCog FolderDot FolderDown FolderGit FolderGit2 FolderHeart FolderInput FolderKanban FolderKey FolderLock FolderMinus FolderOpen FolderOpenDot FolderOutput FolderPen FolderPlus FolderRoot FolderSearch FolderSearch2 FolderSymlink FolderSync FolderTree FolderUp FolderX Folders Footprints Forklift Form Forward Frame Framer Frown Fuel Fullscreen Funnel FunnelPlus FunnelX GalleryHorizontal GalleryHorizontalEnd GalleryThumbnails GalleryVertical GalleryVerticalEnd Gamepad Gamepad2 GamepadDirectional Gauge Gavel Gem GeorgianLari Ghost Gift GitBranch GitBranchMinus GitBranchPlus GitCommitHorizontal GitCommitVertical GitCompare GitCompareArrows GitFork GitGraph GitMerge GitMergeConflict GitPullRequest GitPullRequestArrow GitPullRequestClosed GitPullRequestCreate GitPullRequestCreateArrow GitPullRequestDraft Github Gitlab GlassWater Glasses Globe GlobeLock GlobeOff GlobeX Goal Gpu GraduationCap Grape Grid2x2 Grid2x2Check Grid2x2Plus Grid2x2X Grid3x2 Grid3x3 Grip GripHorizontal GripVertical Group Guitar Ham Hamburger Hammer Hand HandCoins HandFist HandGrab HandHeart HandHelping HandMetal HandPlatter Handbag Handshake HardDrive HardDriveDownload HardDriveUpload HardHat Hash HatGlasses Haze Hd HdmiPort Heading Heading1 Heading2 Heading3 Heading4 Heading5 Heading6 HeadphoneOff Headphones Headset Heart HeartCrack HeartHandshake HeartMinus HeartOff HeartPlus HeartPulse Heater Helicopter Hexagon Highlighter History Hop HopOff Hospital Hotel Hourglass House HouseHeart HousePlug HousePlus HouseWifi IceCreamBowl IceCreamCone IdCard IdCardLanyard Image ImageDown ImageMinus ImageOff ImagePlay ImagePlus ImageUp ImageUpscale Images Import Inbox IndianRupee Infinity Info InspectionPanel Instagram Italic IterationCcw IterationCw JapaneseYen Joystick Kanban Kayak Key KeyRound KeySquare Keyboard KeyboardMusic KeyboardOff Lamp LampCeiling LampDesk LampFloor LampWallDown LampWallUp LandPlot Landmark Languages Laptop LaptopMinimal LaptopMinimalCheck Lasso LassoSelect Laugh Layers Layers2 LayersPlus LayoutDashboard LayoutGrid LayoutList LayoutPanelLeft LayoutPanelTop LayoutTemplate Leaf LeafyGreen Lectern LensConcave LensConvex Library LibraryBig LifeBuoy Ligature Lightbulb LightbulbOff LineDotRightHorizontal LineSquiggle Link Link2 Link2Off Linkedin List ListCheck ListChecks ListChevronsDownUp ListChevronsUpDown ListCollapse ListEnd ListFilter ListFilterPlus ListIndentDecrease ListIndentIncrease ListMinus ListMusic ListOrdered ListPlus ListRestart ListStart ListTodo ListTree ListVideo ListX Loader LoaderCircle LoaderPinwheel Locate LocateFixed LocateOff Lock LockKeyhole LockKeyholeOpen LockOpen LogIn LogOut Logs Lollipop Luggage Magnet Mail MailCheck MailMinus MailOpen MailPlus MailQuestionMark MailSearch MailWarning MailX Mailbox Mails Map MapMinus MapPin MapPinCheck MapPinCheckInside MapPinHouse MapPinMinus MapPinMinusInside MapPinOff MapPinPen MapPinPlus MapPinPlusInside MapPinX MapPinXInside MapPinned MapPlus Mars MarsStroke Martini Maximize Maximize2 Medal Megaphone MegaphoneOff Meh MemoryStick Menu Merge MessageCircle MessageCircleCheck MessageCircleCode MessageCircleDashed MessageCircleHeart MessageCircleMore MessageCircleOff MessageCirclePlus MessageCircleQuestionMark MessageCircleReply MessageCircleWarning MessageCircleX MessageSquare MessageSquareCheck MessageSquareCode MessageSquareDashed MessageSquareDiff MessageSquareDot MessageSquareHeart MessageSquareLock MessageSquareMore MessageSquareOff MessageSquarePlus MessageSquareQuote MessageSquareReply MessageSquareShare MessageSquareText MessageSquareWarning MessageSquareX MessagesSquare Metronome Mic MicOff MicVocal Microchip Microscope Microwave Milestone Milk MilkOff Minimize Minimize2 Minus MirrorRectangular MirrorRound Monitor MonitorCheck MonitorCloud MonitorCog MonitorDot MonitorDown MonitorOff MonitorPause MonitorPlay MonitorSmartphone MonitorSpeaker MonitorStop MonitorUp MonitorX Moon MoonStar Motorbike Mountain MountainSnow Mouse MouseLeft MouseOff MousePointer MousePointer2 MousePointer2Off MousePointerBan MousePointerClick MouseRight Move Move3d MoveDiagonal MoveDiagonal2 MoveDown MoveDownLeft MoveDownRight MoveHorizontal MoveLeft MoveRight MoveUp MoveUpLeft MoveUpRight MoveVertical Music Music2 Music3 Music4 Navigation Navigation2 Navigation2Off NavigationOff Network Newspaper Nfc NonBinary Notebook NotebookPen NotebookTabs NotebookText NotepadText NotepadTextDashed Nut NutOff Octagon OctagonAlert OctagonMinus OctagonPause OctagonX Omega Option Orbit Origami Package Package2 PackageCheck PackageMinus PackageOpen PackagePlus PackageSearch PackageX PaintBucket PaintRoller Paintbrush PaintbrushVertical Palette Panda PanelBottom PanelBottomClose PanelBottomDashed PanelBottomOpen PanelLeft PanelLeftClose PanelLeftDashed PanelLeftOpen PanelLeftRightDashed PanelRight PanelRightClose PanelRightDashed PanelRightOpen PanelTop PanelTopBottomDashed PanelTopClose PanelTopDashed PanelTopOpen PanelsLeftBottom PanelsRightBottom PanelsTopLeft Paperclip Parentheses ParkingMeter PartyPopper Pause PawPrint PcCase Pen PenLine PenOff PenTool Pencil PencilLine PencilOff PencilRuler Pentagon Percent PersonStanding PhilippinePeso Phone PhoneCall PhoneForwarded PhoneIncoming PhoneMissed PhoneOff PhoneOutgoing Pi Piano Pickaxe PictureInPicture PictureInPicture2 PiggyBank Pilcrow PilcrowLeft PilcrowRight Pill PillBottle Pin PinOff Pipette Pizza Plane PlaneLanding PlaneTakeoff Play Plug Plug2 PlugZap Plus Pocket PocketKnife Podcast Pointer PointerOff Popcorn Popsicle PoundSterling Power PowerOff Presentation Printer PrinterCheck PrinterX Projector Proportions Puzzle Pyramid QrCode Quote Rabbit Radar Radiation Radical Radio RadioReceiver RadioTower Radius RailSymbol Rainbow Rat Ratio Receipt ReceiptCent ReceiptEuro ReceiptIndianRupee ReceiptJapaneseYen ReceiptPoundSterling ReceiptRussianRuble ReceiptSwissFranc ReceiptText ReceiptTurkishLira RectangleCircle RectangleEllipsis RectangleGoggles RectangleHorizontal RectangleVertical Recycle Redo Redo2 RedoDot RefreshCcw RefreshCcwDot RefreshCw RefreshCwOff Refrigerator Regex RemoveFormatting Repeat Repeat1 Repeat2 Replace ReplaceAll Reply ReplyAll Rewind Ribbon Rocket RockingChair RollerCoaster Rose Rotate3d RotateCcw RotateCcwKey RotateCcwSquare RotateCw RotateCwSquare Route RouteOff Router Rows2 Rows3 Rows4 Rss Ruler RulerDimensionLine RussianRuble Sailboat Salad Sandwich Satellite SatelliteDish SaudiRiyal Save SaveAll SaveOff Scale Scale3d Scaling Scan ScanBarcode ScanEye ScanFace ScanHeart ScanLine ScanQrCode ScanSearch ScanText School Scissors ScissorsLineDashed Scooter ScreenShare ScreenShareOff Scroll ScrollText Search SearchAlert SearchCheck SearchCode SearchSlash SearchX Section Send SendHorizontal SendToBack SeparatorHorizontal SeparatorVertical Server ServerCog ServerCrash ServerOff Settings Settings2 Shapes Share Share2 Sheet Shell ShelvingUnit Shield ShieldAlert ShieldBan ShieldCheck ShieldEllipsis ShieldHalf ShieldMinus ShieldOff ShieldPlus ShieldQuestionMark ShieldUser ShieldX Ship ShipWheel Shirt ShoppingBag ShoppingBasket ShoppingCart Shovel ShowerHead Shredder Shrimp Shrink Shrub Shuffle Sigma Signal SignalHigh SignalLow SignalMedium SignalZero Signature Signpost SignpostBig Siren SkipBack SkipForward Skull Slack Slash Slice SlidersHorizontal SlidersVertical Smartphone SmartphoneCharging SmartphoneNfc Smile SmilePlus Snail Snowflake SoapDispenserDroplet Sofa SolarPanel Soup Space Spade Sparkle Sparkles Speaker Speech SpellCheck SpellCheck2 Spline SplinePointer Split Spool Spotlight SprayCan Sprout Square SquareActivity SquareArrowDown SquareArrowDownLeft SquareArrowDownRight SquareArrowLeft SquareArrowOutDownLeft SquareArrowOutDownRight SquareArrowOutUpLeft SquareArrowOutUpRight SquareArrowRight SquareArrowRightEnter SquareArrowRightExit SquareArrowUp SquareArrowUpLeft SquareArrowUpRight SquareAsterisk SquareBottomDashedScissors SquareCenterlineDashedHorizontal SquareCenterlineDashedVertical SquareChartGantt SquareCheck SquareCheckBig SquareChevronDown SquareChevronLeft SquareChevronRight SquareChevronUp SquareCode SquareDashed SquareDashedBottom SquareDashedBottomCode SquareDashedKanban SquareDashedMousePointer SquareDashedTopSolid SquareDivide SquareDot SquareEqual SquareFunction SquareKanban SquareLibrary SquareM SquareMenu SquareMinus SquareMousePointer SquareParking SquareParkingOff SquarePause SquarePen SquarePercent SquarePi SquarePilcrow SquarePlay SquarePlus SquarePower SquareRadical SquareRoundCorner SquareScissors SquareSigma SquareSlash SquareSplitHorizontal SquareSplitVertical SquareSquare SquareStack SquareStar SquareStop SquareTerminal SquareUser SquareUserRound SquareX SquaresExclude SquaresIntersect SquaresSubtract SquaresUnite Squircle SquircleDashed Squirrel Stamp Star StarHalf StarOff StepBack StepForward Stethoscope Sticker StickyNote Stone Store StretchHorizontal StretchVertical Strikethrough Subscript Sun SunDim SunMedium SunMoon SunSnow Sunrise Sunset Superscript SwatchBook SwissFranc SwitchCamera Sword Swords Syringe Table Table2 TableCellsMerge TableCellsSplit TableColumnsSplit TableOfContents TableProperties TableRowsSplit Tablet TabletSmartphone Tablets Tag Tags Tally1 Tally2 Tally3 Tally4 Tally5 Tangent Target Telescope Tent TentTree Terminal TestTube TestTubeDiagonal TestTubes TextAlignCenter TextAlignEnd TextAlignJustify TextAlignStart TextCursor TextCursorInput TextInitial TextQuote TextSearch TextSelect TextWrap Theater Thermometer ThermometerSnowflake ThermometerSun ThumbsDown ThumbsUp Ticket TicketCheck TicketMinus TicketPercent TicketPlus TicketSlash TicketX Tickets TicketsPlane Timer TimerOff TimerReset ToggleLeft ToggleRight Toilet ToolCase Toolbox Tornado Torus Touchpad TouchpadOff TowelRack TowerControl ToyBrick Tractor TrafficCone TrainFront TrainFrontTunnel TrainTrack TramFront Transgender Trash Trash2 TreeDeciduous TreePalm TreePine Trees Trello TrendingDown TrendingUp TrendingUpDown Triangle TriangleAlert TriangleDashed TriangleRight Trophy Truck TruckElectric TurkishLira Turntable Turtle Tv TvMinimal TvMinimalPlay Twitch Twitter Type TypeOutline Umbrella UmbrellaOff Underline Undo Undo2 UndoDot UnfoldHorizontal UnfoldVertical Ungroup University Unlink Unlink2 Unplug Upload Usb User UserCheck UserCog UserKey UserLock UserMinus UserPen UserPlus UserRound UserRoundCheck UserRoundCog UserRoundKey UserRoundMinus UserRoundPen UserRoundPlus UserRoundSearch UserRoundX UserSearch UserStar UserX Users UsersRound Utensils UtensilsCrossed UtilityPole Van Variable Vault VectorSquare Vegan VenetianMask Venus VenusAndMars Vibrate VibrateOff Video VideoOff Videotape View Voicemail Volleyball Volume Volume1 Volume2 VolumeOff VolumeX Vote Wallet WalletCards WalletMinimal Wallpaper Wand WandSparkles Warehouse WashingMachine Watch Waves WavesArrowDown WavesArrowUp WavesLadder Waypoints Webcam Webhook WebhookOff Weight WeightTilde Wheat WheatOff WholeWord Wifi WifiCog WifiHigh WifiLow WifiOff WifiPen WifiSync WifiZero Wind WindArrowDown Wine WineOff Workflow Worm Wrench X XLineTop Youtube Zap ZapOff ZodiacAquarius ZodiacAries ZodiacCancer ZodiacCapricorn ZodiacGemini ZodiacLeo ZodiacLibra ZodiacOphiuchus ZodiacPisces ZodiacSagittarius ZodiacScorpio ZodiacTaurus ZodiacVirgo ZoomIn ZoomOut';
+
+export const LUCIDE_ICON_NAMES: ReadonlySet<string> = new Set(NAMES.split(' '));
diff --git a/server/src/modules/release-notes/release-notes.constants.ts b/server/src/modules/release-notes/release-notes.constants.ts
new file mode 100644
index 000000000..74c335c6f
--- /dev/null
+++ b/server/src/modules/release-notes/release-notes.constants.ts
@@ -0,0 +1,26 @@
+export const RELEASE_NOTES_ROUTE = 'release-notes';
+export const RELEASE_NOTES_TIMEOUT_MS = 10_000;
+export const RELEASE_NOTES_LIST_TTL_MS = 600_000;
+export const RELEASE_NOTES_PER_PAGE = 30;
+
+/** Max number of versions shown cumulatively in the popup. */
+export const CUMULATIVE_VERSION_CAP = 4;
+
+/** Max highlights parsed from a single release (abuse guard). */
+export const MAX_HIGHLIGHTS_PER_RELEASE = 12;
+
+/** Max media items rendered per highlight; extras are dropped (the lint warns). */
+export const MAX_MEDIA_PER_HIGHLIGHT = 6;
+
+/** Soft caps for highlight text. Over-cap text is line-clamped in the UI; the lint warns. */
+export const MAX_TITLE_LENGTH = 120;
+export const MAX_BODY_LENGTH = 400;
+
+/** Max concurrent media content-type probes, so a media-heavy page doesn't fan out unbounded. */
+export const MEDIA_PROBE_CONCURRENCY = 6;
+
+/** Cap the in-memory caches so repeated paging or media-heavy bodies can't grow memory unbounded. */
+export const PAGE_CACHE_MAX = 10;
+export const MEDIA_TYPE_CACHE_MAX = 1000;
+
+export const SEMVER_RE = /^v\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?$/;
diff --git a/server/src/modules/release-notes/release-notes.controller.ts b/server/src/modules/release-notes/release-notes.controller.ts
new file mode 100644
index 000000000..f32ff3470
--- /dev/null
+++ b/server/src/modules/release-notes/release-notes.controller.ts
@@ -0,0 +1,22 @@
+import { Controller, Get, Query } from '@nestjs/common';
+
+import type { ReleaseNotesResponse } from '@bookorbit/types';
+
+import { ReleaseNotesQueryDto } from './dto/release-notes-query.dto';
+import { RELEASE_NOTES_ROUTE } from './release-notes.constants';
+import { ReleaseNotesService } from './release-notes.service';
+
+@Controller(RELEASE_NOTES_ROUTE)
+export class ReleaseNotesController {
+  constructor(private readonly releaseNotesService: ReleaseNotesService) {}
+
+  @Get()
+  async get(@Query() query: ReleaseNotesQueryDto): Promise<ReleaseNotesResponse> {
+    if (query.page !== undefined) {
+      const pageNum = Number(query.page);
+      return this.releaseNotesService.getAll(Number.isFinite(pageNum) ? pageNum : 1);
+    }
+    const trimmed = query.since?.trim();
+    return this.releaseNotesService.getSince(trimmed ? trimmed : null);
+  }
+}
diff --git a/server/src/modules/release-notes/release-notes.module.ts b/server/src/modules/release-notes/release-notes.module.ts
new file mode 100644
index 000000000..5ac95f42f
--- /dev/null
+++ b/server/src/modules/release-notes/release-notes.module.ts
@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+
+import { AppSettingsModule } from '../app-settings/app-settings.module';
+import { ReleaseNotesController } from './release-notes.controller';
+import { ReleaseNotesService } from './release-notes.service';
+
+@Module({
+  imports: [AppSettingsModule],
+  controllers: [ReleaseNotesController],
+  providers: [ReleaseNotesService],
+})
+export class ReleaseNotesModule {}
diff --git a/server/src/modules/release-notes/release-notes.service.test.ts b/server/src/modules/release-notes/release-notes.service.test.ts
new file mode 100644
index 000000000..40fa1e58a
--- /dev/null
+++ b/server/src/modules/release-notes/release-notes.service.test.ts
@@ -0,0 +1,116 @@
+import { ConfigService } from '@nestjs/config';
+
+import { AppSettingsService } from '../app-settings/app-settings.service';
+import { ReleaseNotesService } from './release-notes.service';
+
+function ghRelease(tag: string, highlights: boolean) {
+  return {
+    tag_name: tag,
+    name: tag,
+    published_at: '2026-06-14T00:00:00Z',
+    html_url: `https://github.com/o/r/releases/tag/${tag}`,
+    draft: false,
+    body: highlights ? `## Highlights\n- **${tag} thing** - did stuff.\n\n### Features\n- f` : '### Features\n- f',
+  };
+}
+
+function makeService(releases: unknown[], enabled = true, currentVersion?: string) {
+  const config = {
+    get: (key: string) => {
+      if (key === 'app.githubReleasesRepo') return 'o/r';
+      if (key === 'app.version') return currentVersion;
+      return undefined;
+    },
+  } as unknown as ConfigService;
+  const appSettings = { isUpdateCheckEnabled: vi.fn().mockResolvedValue(enabled) } as unknown as AppSettingsService;
+  vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true, json: () => Promise.resolve(releases) }));
+  return new ReleaseNotesService(config, appSettings);
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('ReleaseNotesService.getSince', () => {
+  it('returns only versions newer than the baseline that have highlights, newest first', async () => {
+    const service = makeService([ghRelease('v1.2.0', true), ghRelease('v1.1.0', true), ghRelease('v1.0.0', true)]);
+    const res = await service.getSince('v1.0.0');
+    expect(res.releases.map((r) => r.version)).toEqual(['v1.2.0', 'v1.1.0']);
+    expect(res.hasMore).toBe(false);
+  });
+
+  it('excludes releases without a Highlights section', async () => {
+    const service = makeService([ghRelease('v1.2.0', false), ghRelease('v1.1.0', true)]);
+    const res = await service.getSince('v1.0.0');
+    expect(res.releases.map((r) => r.version)).toEqual(['v1.1.0']);
+  });
+
+  it('caps the cumulative list and flags hasMore', async () => {
+    const service = makeService([
+      ghRelease('v1.5.0', true),
+      ghRelease('v1.4.0', true),
+      ghRelease('v1.3.0', true),
+      ghRelease('v1.2.0', true),
+      ghRelease('v1.1.0', true),
+    ]);
+    const res = await service.getSince('v1.0.0');
+    expect(res.releases).toHaveLength(4);
+    expect(res.hasMore).toBe(true);
+  });
+
+  it('never announces versions newer than the running build', async () => {
+    const service = makeService([ghRelease('v1.3.0', true), ghRelease('v1.2.0', true), ghRelease('v1.1.0', true)], true, 'v1.2.0');
+    const res = await service.getSince('v1.0.0');
+    expect(res.releases.map((r) => r.version)).toEqual(['v1.2.0', 'v1.1.0']);
+  });
+
+  it('returns an empty list when update checks are disabled', async () => {
+    const service = makeService([ghRelease('v1.2.0', true)], false);
+    const res = await service.getSince('v1.0.0');
+    expect(res.releases).toEqual([]);
+  });
+
+  it('reclassifies extensionless GitHub media as video via a content-type probe, once per unique URL', async () => {
+    const sharedUrl = 'https://github.com/user-attachments/assets/abc';
+    const releases = [
+      {
+        tag_name: 'v1.2.0',
+        name: 'v1.2.0',
+        published_at: '2026-06-14T00:00:00Z',
+        html_url: 'https://github.com/o/r/releases/tag/v1.2.0',
+        draft: false,
+        body: `## Highlights\n- **Demo** - watch this.\n  ![](${sharedUrl})\n- **Again** - same clip.\n  ![](${sharedUrl})`,
+      },
+    ];
+    const config = {
+      get: (key: string) => (key === 'app.githubReleasesRepo' ? 'o/r' : key === 'app.githubReleasesToken' ? 'tkn' : undefined),
+    } as unknown as ConfigService;
+    const appSettings = { isUpdateCheckEnabled: vi.fn().mockResolvedValue(true) } as unknown as AppSettingsService;
+    const fetchMock = vi.fn((url: string) =>
+      url.includes('api.github.com')
+        ? Promise.resolve({ ok: true, json: () => Promise.resolve(releases) })
+        : Promise.resolve({ headers: { get: () => 'video/mp4' } }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+    const service = new ReleaseNotesService(config, appSettings);
+    const highlights = (await service.getSince('v1.0.0')).releases[0].highlights;
+    expect(highlights[0].media).toEqual([{ url: sharedUrl, type: 'video' }]);
+    expect(highlights[1].media).toEqual([{ url: sharedUrl, type: 'video' }]);
+    const probeCalls = fetchMock.mock.calls.filter(([u]) => !String(u).includes('api.github.com'));
+    expect(probeCalls).toHaveLength(1);
+  });
+
+  it('ignores releases whose tag is not a clean vX.Y.Z (extra segments / trailing garbage)', async () => {
+    const service = makeService([ghRelease('v1.2.0.4', true), ghRelease('v1.2.0-nope-extra', true), ghRelease('v1.1.0', true)]);
+    const res = await service.getSince('v1.0.0');
+    expect(res.releases.map((r) => r.version)).toEqual(['v1.1.0']);
+  });
+
+  it('strips the Highlights section from the changelog body', async () => {
+    const service = makeService([ghRelease('v1.2.0', true)]);
+    const res = await service.getSince('v1.0.0');
+    expect(res.releases[0].changelogBody).toBe('### Features\n- f');
+    expect(res.releases[0].highlights).toHaveLength(1);
+  });
+});
diff --git a/server/src/modules/release-notes/release-notes.service.ts b/server/src/modules/release-notes/release-notes.service.ts
new file mode 100644
index 000000000..2b55f1f6a
--- /dev/null
+++ b/server/src/modules/release-notes/release-notes.service.ts
@@ -0,0 +1,254 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+
+import type { ReleaseNote, ReleaseNotesResponse } from '@bookorbit/types';
+
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { AppSettingsService } from '../app-settings/app-settings.service';
+import { parseHighlights, stripHighlightsSection } from './highlights.parser';
+import {
+  CUMULATIVE_VERSION_CAP,
+  MEDIA_PROBE_CONCURRENCY,
+  MEDIA_TYPE_CACHE_MAX,
+  PAGE_CACHE_MAX,
+  RELEASE_NOTES_LIST_TTL_MS,
+  RELEASE_NOTES_PER_PAGE,
+  RELEASE_NOTES_TIMEOUT_MS,
+  SEMVER_RE,
+} from './release-notes.constants';
+
+@Injectable()
+export class ReleaseNotesService {
+  private readonly logger = new Logger(ReleaseNotesService.name);
+  private readonly pageCache = new Map<number, { releases: ReleaseNote[]; fetchedAt: number }>();
+  private readonly mediaTypeCache = new Map<string, 'image' | 'video' | 'other'>();
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly appSettingsService: AppSettingsService,
+  ) {}
+
+  async getSince(since: string | null): Promise<ReleaseNotesResponse> {
+    const all = await this.getPage(1);
+    const current = this.config.get<string>('app.version') ?? '';
+    const capByCurrent = SEMVER_RE.test(current);
+
+    const eligible = all.filter((r) => {
+      if (r.highlights.length === 0) return false;
+      if (since && !this.isNewer(r.version, since)) return false;
+      // Never announce versions newer than the running build (not yet installed here).
+      if (capByCurrent && this.isNewer(r.version, current)) return false;
+      return true;
+    });
+
+    const releases = eligible.slice(0, CUMULATIVE_VERSION_CAP);
+    return { releases, hasMore: eligible.length > releases.length };
+  }
+
+  async getAll(page: number): Promise<ReleaseNotesResponse> {
+    const safePage = Number.isInteger(page) && page > 0 ? page : 1;
+    const releases = await this.getPage(safePage);
+    return { releases, hasMore: releases.length >= RELEASE_NOTES_PER_PAGE };
+  }
+
+  private async getPage(page: number): Promise<ReleaseNote[]> {
+    const cached = this.pageCache.get(page);
+    if (cached && Date.now() - cached.fetchedAt < RELEASE_NOTES_LIST_TTL_MS) {
+      return cached.releases;
+    }
+
+    const fetched = await this.fetchPage(page);
+    if (fetched) {
+      this.setCapped(this.pageCache, page, { releases: fetched, fetchedAt: Date.now() }, PAGE_CACHE_MAX);
+      return fetched;
+    }
+
+    return cached?.releases ?? [];
+  }
+
+  /** Insert into a cache map, evicting the oldest entry first when at capacity (FIFO). */
+  private setCapped<K, V>(map: Map<K, V>, key: K, value: V, max: number): void {
+    if (!map.has(key) && map.size >= max) {
+      const oldest = map.keys().next();
+      if (!oldest.done) map.delete(oldest.value);
+    }
+    map.set(key, value);
+  }
+
+  private async fetchPage(page: number): Promise<ReleaseNote[] | null> {
+    const enabled = await this.appSettingsService.isUpdateCheckEnabled();
+    if (!enabled) return [];
+
+    const repo = this.config.get<string>('app.githubReleasesRepo') ?? 'bookorbit/bookorbit';
+    const token = this.config.get<string>('app.githubReleasesToken');
+    const url = `https://api.github.com/repos/${repo}/releases?per_page=${RELEASE_NOTES_PER_PAGE}&page=${page}`;
+    const start = Date.now();
+    this.logger.log(`[release_notes.fetch] [start] repo="${sanitizeLogValue(repo)}" page=${page} - fetching releases`);
+
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), RELEASE_NOTES_TIMEOUT_MS);
+
+      const headers: Record<string, string> = { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28' };
+      if (token) headers.Authorization = `Bearer ${token}`;
+
+      let response: Response;
+      try {
+        response = await fetch(url, { headers, signal: controller.signal });
+      } finally {
+        clearTimeout(timer);
+      }
+
+      if (!response.ok) {
+        const durationMs = Date.now() - start;
+        this.logger.warn(
+          `[release_notes.fetch] [fail] repo="${sanitizeLogValue(repo)}" page=${page} durationMs=${durationMs} errorClass=${this.httpErrorClass(response.status)} error="GitHub API returned ${response.status}" - fetch releases failed`,
+        );
+        return null;
+      }
+
+      let data: unknown;
+      try {
+        data = await response.json();
+      } catch {
+        const durationMs = Date.now() - start;
+        this.logger.warn(
+          `[release_notes.fetch] [fail] repo="${sanitizeLogValue(repo)}" page=${page} durationMs=${durationMs} errorClass=ParseError error="invalid JSON response" - fetch releases failed`,
+        );
+        return null;
+      }
+      if (!Array.isArray(data)) {
+        const durationMs = Date.now() - start;
+        this.logger.warn(
+          `[release_notes.fetch] [fail] repo="${sanitizeLogValue(repo)}" page=${page} durationMs=${durationMs} errorClass=ParseError error="unexpected response shape" - fetch releases failed`,
+        );
+        return null;
+      }
+
+      const releases = data.map((raw) => this.toReleaseNote(raw, repo)).filter((r): r is ReleaseNote => r !== null);
+      await this.resolveMediaTypes(releases, token);
+      const durationMs = Date.now() - start;
+      this.logger.log(
+        `[release_notes.fetch] [end] repo="${sanitizeLogValue(repo)}" page=${page} durationMs=${durationMs} count=${releases.length} - fetch releases completed`,
+      );
+      return releases;
+    } catch (error) {
+      const durationMs = Date.now() - start;
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.warn(
+        `[release_notes.fetch] [fail] repo="${sanitizeLogValue(repo)}" page=${page} durationMs=${durationMs} errorClass=${errorClass} error="${sanitizeLogValue(message)}" - fetch releases failed`,
+      );
+      return null;
+    }
+  }
+
+  private toReleaseNote(raw: unknown, repo: string): ReleaseNote | null {
+    if (typeof raw !== 'object' || raw === null) return null;
+    const r = raw as Record<string, unknown>;
+    if (r.draft === true) return null;
+
+    const version = typeof r.tag_name === 'string' ? r.tag_name : null;
+    if (!version) return null;
+
+    const body = typeof r.body === 'string' ? r.body : null;
+    const name = typeof r.name === 'string' && r.name.trim() ? r.name : null;
+
+    return {
+      version,
+      name,
+      date: typeof r.published_at === 'string' ? r.published_at : null,
+      highlights: parseHighlights(body),
+      changelogUrl: typeof r.html_url === 'string' ? r.html_url : `https://github.com/${repo}/releases/tag/${version}`,
+      changelogBody: stripHighlightsSection(body),
+    };
+  }
+
+  /**
+   * GitHub drag-drop media (user-attachments) has no file extension, so the parser defaults it to
+   * 'image'. Probe the content-type once per URL and reclassify the ones that are actually video.
+   */
+  private async resolveMediaTypes(releases: ReleaseNote[], token?: string): Promise<void> {
+    const pending = new Set<string>();
+    for (const release of releases) {
+      for (const highlight of release.highlights) {
+        for (const item of highlight.media) {
+          if (item.type === 'image' && this.needsContentTypeProbe(item.url) && !this.mediaTypeCache.has(item.url)) {
+            pending.add(item.url);
+          }
+        }
+      }
+    }
+    if (pending.size === 0) return;
+
+    const urls = [...pending];
+    for (let i = 0; i < urls.length; i += MEDIA_PROBE_CONCURRENCY) {
+      await Promise.all(urls.slice(i, i + MEDIA_PROBE_CONCURRENCY).map((url) => this.probeMediaType(url, token)));
+    }
+
+    for (const release of releases) {
+      for (const highlight of release.highlights) {
+        for (const item of highlight.media) {
+          if (item.type === 'image' && this.mediaTypeCache.get(item.url) === 'video') {
+            item.type = 'video';
+          }
+        }
+      }
+    }
+  }
+
+  private needsContentTypeProbe(url: string): boolean {
+    return !/\.(png|jpe?g|gif|webp|svg|avif)(?:[?#].*)?$/i.test(url);
+  }
+
+  private async probeMediaType(url: string, token?: string): Promise<void> {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), RELEASE_NOTES_TIMEOUT_MS);
+      // GitHub user-attachments redirect to a presigned S3 URL that only allows GET, so HEAD
+      // returns 403. A single-byte ranged GET gets the real content-type without downloading.
+      const headers: Record<string, string> = { Range: 'bytes=0-0' };
+      if (token) headers.Authorization = `Bearer ${token}`;
+
+      let response: Response;
+      try {
+        response = await fetch(url, { method: 'GET', headers, signal: controller.signal });
+      } finally {
+        clearTimeout(timer);
+      }
+
+      const type = (response.headers.get('content-type') ?? '').toLowerCase();
+      this.setCapped(
+        this.mediaTypeCache,
+        url,
+        type.startsWith('video/') ? 'video' : type.startsWith('image/') ? 'image' : 'other',
+        MEDIA_TYPE_CACHE_MAX,
+      );
+    } catch {
+      this.setCapped(this.mediaTypeCache, url, 'other', MEDIA_TYPE_CACHE_MAX);
+    }
+  }
+
+  private httpErrorClass(status: number): string {
+    if (status === 401 || status === 403) return 'AuthError';
+    if (status === 404) return 'NotFoundError';
+    if (status === 429) return 'RateLimitError';
+    return 'HttpError';
+  }
+
+  private isNewer(candidate: string, baseline: string): boolean {
+    if (!SEMVER_RE.test(candidate)) return false;
+    const a = this.parseSemver(candidate.replace(/^v/, ''));
+    const b = this.parseSemver(baseline.replace(/^v/, ''));
+    if (!a || !b) return false;
+    if (a[0] !== b[0]) return a[0] > b[0];
+    if (a[1] !== b[1]) return a[1] > b[1];
+    return a[2] > b[2];
+  }
+
+  private parseSemver(version: string): [number, number, number] | null {
+    const parts = version.split('.').map(Number);
+    if (parts.length < 3 || parts.some((p) => isNaN(p))) return null;
+    return [parts[0], parts[1], parts[2]];
+  }
+}
diff --git a/server/src/modules/user-preferences/user-preferences.controller.ts b/server/src/modules/user-preferences/user-preferences.controller.ts
index 1b3474811..71904d15a 100644
--- a/server/src/modules/user-preferences/user-preferences.controller.ts
+++ b/server/src/modules/user-preferences/user-preferences.controller.ts
@@ -32,4 +32,16 @@ export class UserPreferencesController {
   async upsertDisplayPreferences(@Body() dto: UpsertUserPreferenceDto, @CurrentUser() user: RequestUser) {
     await this.userPreferencesService.upsertDisplayPreferences(user.id, dto.settings);
   }
+
+  @Get('whats-new')
+  async getWhatsNewPreferences(@CurrentUser() user: RequestUser) {
+    const settings = await this.userPreferencesService.getWhatsNewPreferences(user.id);
+    return { settings };
+  }
+
+  @Put('whats-new')
+  @HttpCode(204)
+  async upsertWhatsNewPreferences(@Body() dto: UpsertUserPreferenceDto, @CurrentUser() user: RequestUser) {
+    await this.userPreferencesService.upsertWhatsNewPreferences(user.id, dto.settings);
+  }
 }
diff --git a/server/src/modules/user-preferences/user-preferences.service.test.ts b/server/src/modules/user-preferences/user-preferences.service.test.ts
index 268aaedc5..deee04e2e 100644
--- a/server/src/modules/user-preferences/user-preferences.service.test.ts
+++ b/server/src/modules/user-preferences/user-preferences.service.test.ts
@@ -336,4 +336,30 @@ describe('UserPreferencesService', () => {
     await expect(service.upsertDisplayPreferences(11, withoutSecondary as unknown as Record<string, unknown>)).resolves.toBeUndefined();
     expect(repo.upsert).toHaveBeenCalledWith(11, 'display', expect.objectContaining({ gridCardSecondaryLabel: 'hidden' }));
   });
+
+  it('getWhatsNewPreferences returns defaults when repository has no row', async () => {
+    await expect(service.getWhatsNewPreferences(7)).resolves.toEqual({ lastSeenVersion: null, popupEnabled: true });
+    expect(repo.findByCategory).toHaveBeenCalledWith(7, 'whats-new');
+  });
+
+  it('getWhatsNewPreferences fills missing fields with defaults', async () => {
+    repo.findByCategory.mockResolvedValueOnce({ data: { lastSeenVersion: 'v1.2.0' } } as never);
+    await expect(service.getWhatsNewPreferences(7)).resolves.toEqual({ lastSeenVersion: 'v1.2.0', popupEnabled: true });
+  });
+
+  it('upsertWhatsNewPreferences merges a partial update onto existing values', async () => {
+    repo.findByCategory.mockResolvedValueOnce({ data: { lastSeenVersion: 'v1.0.0', popupEnabled: true } } as never);
+    await expect(service.upsertWhatsNewPreferences(11, { popupEnabled: false })).resolves.toBeUndefined();
+    expect(repo.upsert).toHaveBeenCalledWith(11, 'whats-new', { lastSeenVersion: 'v1.0.0', popupEnabled: false });
+  });
+
+  it('upsertWhatsNewPreferences rejects unknown fields', async () => {
+    await expect(service.upsertWhatsNewPreferences(11, { lastSeenVersion: 'v1.0.0', nope: true })).rejects.toBeInstanceOf(BadRequestException);
+    expect(repo.upsert).not.toHaveBeenCalled();
+  });
+
+  it('upsertWhatsNewPreferences rejects a non-boolean popupEnabled', async () => {
+    await expect(service.upsertWhatsNewPreferences(11, { popupEnabled: 'yes' })).rejects.toBeInstanceOf(BadRequestException);
+    expect(repo.upsert).not.toHaveBeenCalled();
+  });
 });
diff --git a/server/src/modules/user-preferences/user-preferences.service.ts b/server/src/modules/user-preferences/user-preferences.service.ts
index 6641a8031..f48d511a9 100644
--- a/server/src/modules/user-preferences/user-preferences.service.ts
+++ b/server/src/modules/user-preferences/user-preferences.service.ts
@@ -17,6 +17,7 @@ import {
   THEME_IDS,
   type DisplayPreferences,
   type ThemePreferences,
+  type WhatsNewPreferences,
 } from '@bookorbit/types';
 import { BadRequestException, Injectable, Logger } from '@nestjs/common';
 import { z } from 'zod';
@@ -70,12 +71,60 @@ const DISPLAY_PREFERENCES_SCHEMA = z
     }
   });
 
+const WHATS_NEW_PREFERENCES_SCHEMA = z
+  .object({
+    lastSeenVersion: z.string().min(1).max(50).optional(),
+    popupEnabled: z.boolean().optional(),
+  })
+  .strict();
+
+const WHATS_NEW_DEFAULTS: WhatsNewPreferences = { lastSeenVersion: null, popupEnabled: true };
+
 @Injectable()
 export class UserPreferencesService {
   private readonly logger = new Logger(UserPreferencesService.name);
 
   constructor(private readonly repo: UserPreferencesRepository) {}
 
+  async getWhatsNewPreferences(userId: number): Promise<WhatsNewPreferences> {
+    const row = await this.repo.findByCategory(userId, 'whats-new');
+    if (!row) return { ...WHATS_NEW_DEFAULTS };
+    const stored = row.data as Partial<WhatsNewPreferences>;
+    return {
+      lastSeenVersion: stored.lastSeenVersion ?? null,
+      popupEnabled: stored.popupEnabled ?? true,
+    };
+  }
+
+  async upsertWhatsNewPreferences(userId: number, data: Record<string, unknown>): Promise<void> {
+    const start = Date.now();
+    this.logger.log(`[user_preferences.upsert_whats_new] [start] userId=${userId} - upsert whats-new preferences started`);
+
+    const result = WHATS_NEW_PREFERENCES_SCHEMA.safeParse(data);
+    if (!result.success) {
+      const firstIssue = result.error.issues[0];
+      const issuePath = firstIssue?.path.length ? firstIssue.path.join('.') : 'settings';
+      const issueMessage = firstIssue?.message ?? 'Invalid settings payload';
+      throw new BadRequestException(`Invalid whats-new preferences at "${issuePath}": ${issueMessage}`);
+    }
+
+    try {
+      const existing = await this.getWhatsNewPreferences(userId);
+      const merged: WhatsNewPreferences = { ...existing, ...result.data };
+      await this.repo.upsert(userId, 'whats-new', { ...merged });
+      const durationMs = Date.now() - start;
+      this.logger.log(`[user_preferences.upsert_whats_new] [end] userId=${userId} durationMs=${durationMs} - upsert whats-new preferences completed`);
+    } catch (err) {
+      const durationMs = Date.now() - start;
+      const errorClass = err instanceof Error ? err.constructor.name : 'UnknownError';
+      const error = sanitizeLogValue(err instanceof Error ? err.message : String(err));
+      this.logger.error(
+        `[user_preferences.upsert_whats_new] [fail] userId=${userId} durationMs=${durationMs} errorClass=${errorClass} error="${error}" - upsert whats-new preferences failed`,
+      );
+      throw err;
+    }
+  }
+
   async getThemePreferences(userId: number): Promise<ThemePreferences | null> {
     const row = await this.repo.findByCategory(userId, 'theme');
     return row ? (row.data as ThemePreferences) : null;
diff --git a/server/src/scripts/README.md b/server/src/scripts/README.md
new file mode 100644
index 000000000..b53bcde13
--- /dev/null
+++ b/server/src/scripts/README.md
@@ -0,0 +1,37 @@
+# server scripts
+
+One-off and operational scripts, run from the `server/` directory via the `pnpm` scripts in
+`server/package.json` (or directly with `tsx src/scripts/<file>.ts`).
+
+## What's New release tooling
+
+These validate and preview a release's `## Highlights` section before you publish it. Full
+authoring walkthrough and format reference: [docs/whats-new-authoring-guide.md](../../../docs/whats-new-authoring-guide.md).
+
+| Command                                                       | What it does                                                                               |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `pnpm whats-new:check <tag>`                                  | One-stop: lints, then previews, the release for `<tag>`. Exits non-zero if the lint fails. |
+| `pnpm whats-new:lint <file.md>` \| `--tag <tag>` `[--strict]` | Static validation with the same parser the app uses. `--strict` fails on warnings too.     |
+| `pnpm whats-new:preview [tag]` `[--repo owner/name]`          | Renders exactly what the app will show and probes each media URL for reachability.         |
+
+Each accepts `--help`. They read `GITHUB_RELEASES_REPO`, `GITHUB_RELEASES_TOKEN`, and
+`APP_VERSION` from `server/.env`; point them at another repo with `GITHUB_RELEASES_REPO=owner/name`
+(or `--repo owner/name` for `preview`).
+
+```bash
+cd server
+pnpm whats-new:check v4.5.0                                   # lint + preview the release
+pnpm whats-new:lint notes.md --strict                        # validate a draft locally
+GITHUB_RELEASES_REPO=neonsolstice/playground pnpm whats-new:preview v4.2.0
+```
+
+## Other scripts
+
+| File                                 | Run with                                             | Purpose                                       |
+| ------------------------------------ | ---------------------------------------------------- | --------------------------------------------- |
+| `db-seed.ts`                         | `pnpm db:seed`                                       | Seed the dev database.                        |
+| `db-prepare-e2e.ts`                  | `pnpm e2e:db:prepare`                                | Prepare the e2e test database.                |
+| `migrate.ts`                         | `pnpm db:migrate:runtime` (compiled)                 | Apply database migrations at runtime/startup. |
+| `setup-kobo-cloudscraper.ts`         | `pnpm setup:kobo-cloudscraper`                       | Set up the Kobo cloudscraper integration.     |
+| `backfill-reading-session-events.ts` | `tsx src/scripts/backfill-reading-session-events.ts` | One-off backfill of reading-session events.   |
+| `bench-user-statistics.ts`           | `tsx src/scripts/bench-user-statistics.ts`           | Benchmark the user-statistics queries.        |
diff --git a/server/src/scripts/whats-new-check.ts b/server/src/scripts/whats-new-check.ts
new file mode 100644
index 000000000..82b230aef
--- /dev/null
+++ b/server/src/scripts/whats-new-check.ts
@@ -0,0 +1,50 @@
+/**
+ * One-stop check for a release's "What's New" highlights: lint, then preview.
+ *
+ *   pnpm whats-new:check <tag>      # e.g. pnpm whats-new:check v4.5.0
+ *
+ * Runs whats-new:lint --tag <tag> followed by whats-new:preview <tag>, sharing
+ * GITHUB_RELEASES_REPO / GITHUB_RELEASES_TOKEN from server/.env. Exits non-zero
+ * if the lint fails; the preview is informational and always runs.
+ */
+import { execFileSync } from 'node:child_process';
+
+function printHelp(): void {
+  console.log(
+    [
+      'Usage: pnpm whats-new:check <tag>',
+      '',
+      'Lints, then previews, the release for <tag> (runs whats-new:lint --tag then',
+      'whats-new:preview). Exits non-zero if the lint fails.',
+      '',
+      'Env (server/.env): GITHUB_RELEASES_REPO, GITHUB_RELEASES_TOKEN',
+    ].join('\n'),
+  );
+}
+
+const tag = process.argv[2];
+if (tag === '--help' || tag === '-h') {
+  printHelp();
+  process.exit(0);
+}
+if (!tag || tag.startsWith('-')) {
+  printHelp();
+  process.exit(1);
+}
+
+let lintOk = true;
+try {
+  execFileSync('tsx', ['src/scripts/whats-new-lint.ts', '--tag', tag], { stdio: 'inherit' });
+} catch {
+  lintOk = false;
+}
+
+console.log('');
+
+try {
+  execFileSync('tsx', ['src/scripts/whats-new-preview.ts', tag], { stdio: 'inherit' });
+} catch {
+  // The preview is informational; do not let its exit status mask the lint result.
+}
+
+process.exit(lintOk ? 0 : 1);
diff --git a/server/src/scripts/whats-new-images.ts b/server/src/scripts/whats-new-images.ts
new file mode 100644
index 000000000..d39b643f1
--- /dev/null
+++ b/server/src/scripts/whats-new-images.ts
@@ -0,0 +1,133 @@
+/**
+ * Normalize "What's New" highlight screenshots before dragging them into a GitHub release:
+ * convert to webp, cap the largest dimension, strip metadata. Aspect ratio is preserved
+ * (no cropping) - the app normalizes display size in CSS; this only trims file weight so the
+ * popup loads fast and stays sharp in the lightbox.
+ *
+ *   pnpm whats-new:images <folder>                 # process every image into <folder>/processed
+ *   pnpm whats-new:images <file.png>               # process a single file (handy for the webp test)
+ *   pnpm whats-new:images <folder> --out <dir>     # custom output directory
+ *   pnpm whats-new:images <folder> --max 1600      # custom max dimension (default 1280)
+ *   pnpm whats-new:images <folder> --quality 82    # custom webp quality (default 80)
+ *
+ * Output filenames keep the original basename (extension swapped to .webp) so it stays obvious
+ * which processed file maps to which highlight in the release markdown.
+ */
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+
+import sharp from 'sharp';
+
+const INPUT_EXT_RE = /\.(png|jpe?g|webp|tiff?)$/i;
+const DEFAULT_MAX = 1280;
+const DEFAULT_QUALITY = 90;
+
+interface Options {
+  input: string;
+  out: string;
+  max: number;
+  quality: number;
+}
+
+const VALUE_FLAGS = new Set(['--out', '--max', '--quality']);
+
+function parseArgs(args: string[]): Options {
+  const flag = (name: string): string | undefined => {
+    const i = args.indexOf(name);
+    return i !== -1 ? args[i + 1] : undefined;
+  };
+
+  const positionals = args.filter((a, i) => !a.startsWith('--') && !VALUE_FLAGS.has(args[i - 1]));
+  const input = positionals[0];
+  if (!input) throw new Error('Provide a folder or image file. See: pnpm whats-new:images --help');
+
+  const resolvedInput = resolve(input);
+  if (!existsSync(resolvedInput)) throw new Error(`Path not found: ${resolvedInput}`);
+
+  const isDir = statSync(resolvedInput).isDirectory();
+  const defaultOut = isDir ? join(resolvedInput, 'processed') : join(resolve(resolvedInput, '..'), 'processed');
+
+  const max = Number(flag('--max') ?? DEFAULT_MAX);
+  const quality = Number(flag('--quality') ?? DEFAULT_QUALITY);
+  if (!Number.isFinite(max) || max < 64) throw new Error('--max must be a number >= 64');
+  if (!Number.isFinite(quality) || quality < 1 || quality > 100) throw new Error('--quality must be 1-100');
+
+  return { input: resolvedInput, out: resolve(flag('--out') ?? defaultOut), max, quality };
+}
+
+function collectImages(input: string): string[] {
+  if (statSync(input).isFile()) return INPUT_EXT_RE.test(input) ? [input] : [];
+  return readdirSync(input)
+    .filter((f) => INPUT_EXT_RE.test(f))
+    .map((f) => join(input, f))
+    .filter((f) => statSync(f).isFile())
+    .sort();
+}
+
+function formatKb(bytes: number): string {
+  return `${(bytes / 1024).toFixed(0)} KB`;
+}
+
+function printHelp(): void {
+  console.log(
+    [
+      'Usage: pnpm whats-new:images <folder|file> [--out <dir>] [--max <px>] [--quality <1-100>]',
+      '',
+      'Converts highlight screenshots to webp, caps the largest dimension, strips metadata.',
+      'Aspect ratio is preserved (no cropping). Output basenames match the input (.webp).',
+      '',
+      `  --out <dir>       output directory (default: <input>/processed)`,
+      `  --max <px>        cap the largest dimension (default: ${DEFAULT_MAX})`,
+      `  --quality <n>     webp quality 1-100 (default: ${DEFAULT_QUALITY})`,
+    ].join('\n'),
+  );
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.length === 0) {
+    printHelp();
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+
+  const opts = parseArgs(args);
+  const images = collectImages(opts.input);
+  if (images.length === 0) {
+    console.log('No images found (png, jpg, jpeg, webp, tiff).');
+    process.exit(1);
+  }
+
+  mkdirSync(opts.out, { recursive: true });
+  console.log(`\nProcessing ${images.length} image(s) -> ${opts.out}`);
+  console.log(`webp q${opts.quality} · max ${opts.max}px · aspect preserved\n${'─'.repeat(72)}`);
+
+  let totalIn = 0;
+  let totalOut = 0;
+
+  for (const src of images) {
+    const inSize = statSync(src).size;
+    const outName = `${basename(src, extname(src))}.webp`;
+    const dest = join(opts.out, outName);
+
+    const pipeline = sharp(src)
+      .rotate()
+      .resize({ width: opts.max, height: opts.max, fit: 'inside', withoutEnlargement: true })
+      .webp({ quality: opts.quality });
+    const info = await pipeline.toFile(dest);
+
+    totalIn += inSize;
+    totalOut += info.size;
+    const pct = ((1 - info.size / inSize) * 100).toFixed(0);
+    console.log(`  ${basename(src)}\n    -> ${outName}  ${info.width}x${info.height}  ${formatKb(inSize)} -> ${formatKb(info.size)}  (-${pct}%)`);
+  }
+
+  console.log(`${'─'.repeat(72)}`);
+  const savedPct = totalIn > 0 ? ((1 - totalOut / totalIn) * 100).toFixed(0) : '0';
+  console.log(`Total: ${formatKb(totalIn)} -> ${formatKb(totalOut)}  (-${savedPct}%)`);
+  console.log('✓ Done. Drag the .webp files from the output folder into the release editor.');
+}
+
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+});
diff --git a/server/src/scripts/whats-new-lint.ts b/server/src/scripts/whats-new-lint.ts
new file mode 100644
index 000000000..88da9cb53
--- /dev/null
+++ b/server/src/scripts/whats-new-lint.ts
@@ -0,0 +1,92 @@
+/**
+ * Lint a "What's New" Highlights section before (or after) publishing: static, no network.
+ * Uses the same parser the app uses, so a clean lint means it will parse correctly.
+ *
+ *   pnpm whats-new:lint path/to/notes.md      # lint a local markdown file (before pasting)
+ *   pnpm whats-new:lint --tag v3.2.0          # fetch + lint a published release
+ *   pnpm whats-new:lint notes.md --strict     # treat warnings as failures too
+ *
+ * Exits 1 if there are errors (or warnings under --strict), so it can gate CI.
+ */
+import { readFileSync } from 'node:fs';
+
+import { lintHighlights } from '../modules/release-notes/highlights.lint';
+
+function loadEnv(): Record<string, string> {
+  try {
+    const raw = readFileSync('.env', 'utf8');
+    const out: Record<string, string> = {};
+    for (const line of raw.split(/\r?\n/)) {
+      const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+      if (m && !line.startsWith('#')) out[m[1]] = m[2].trim();
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+async function resolveBody(args: string[]): Promise<{ source: string; body: string }> {
+  const tagIdx = args.indexOf('--tag');
+  if (tagIdx !== -1) {
+    const tag = args[tagIdx + 1];
+    if (!tag) throw new Error('--tag requires a value, e.g. --tag v3.2.0');
+    const env = { ...process.env, ...loadEnv() };
+    const repo = env.GITHUB_RELEASES_REPO ?? 'bookorbit/bookorbit';
+    const token = env.GITHUB_RELEASES_TOKEN;
+    const res = await fetch(`https://api.github.com/repos/${repo}/releases/tags/${tag}`, {
+      headers: { Accept: 'application/vnd.github+json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+    });
+    if (!res.ok) throw new Error(`GitHub API ${res.status} for ${repo}@${tag}`);
+    const body = ((await res.json()) as { body: string | null }).body ?? '';
+    return { source: `${repo}@${tag}`, body };
+  }
+
+  const file = args.find((a) => !a.startsWith('--'));
+  if (!file) throw new Error('Provide a file path or --tag <tag>. See: pnpm whats-new:lint --help');
+  return { source: file, body: readFileSync(file, 'utf8') };
+}
+
+function printHelp(): void {
+  console.log(
+    [
+      'Usage: pnpm whats-new:lint <file.md> | --tag <tag> [--strict]',
+      '',
+      'Validates a Highlights section with the same parser the app uses',
+      '(no network for a file; one GitHub fetch for --tag).',
+      '',
+      '  <file.md>      lint a local markdown file',
+      '  --tag <tag>    fetch + lint a release by tag',
+      '  --strict       treat warnings as failures too',
+      '',
+      'Env (server/.env): GITHUB_RELEASES_REPO, GITHUB_RELEASES_TOKEN',
+    ].join('\n'),
+  );
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.length === 0) {
+    printHelp();
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+  const strict = args.includes('--strict');
+
+  const { source, body } = await resolveBody(args);
+  const { errors, warnings, highlightCount } = lintHighlights(body);
+
+  console.log(`\nLinting Highlights · ${source}\n${'─'.repeat(56)}`);
+  for (const e of errors) console.log(`  ✗ ERROR   ${e}`);
+  for (const w of warnings) console.log(`  ⚠ WARN    ${w}`);
+  console.log(`${'─'.repeat(56)}`);
+  console.log(`${highlightCount} highlight(s) · ${errors.length} error(s) · ${warnings.length} warning(s)`);
+
+  const failed = errors.length > 0 || (strict && warnings.length > 0);
+  console.log(failed ? '✗ FAILED' : '✓ OK');
+  process.exit(failed ? 1 : 0);
+}
+
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+});
diff --git a/server/src/scripts/whats-new-preview.ts b/server/src/scripts/whats-new-preview.ts
new file mode 100644
index 000000000..c7b34c378
--- /dev/null
+++ b/server/src/scripts/whats-new-preview.ts
@@ -0,0 +1,136 @@
+/**
+ * Preview exactly what BookOrbit's "What's New" will render for a repo's releases,
+ * using the SAME parser + media content-type probe the app uses (no drift).
+ *
+ *   pnpm whats-new:preview                 # all releases on page 1 of the configured repo
+ *   pnpm whats-new:preview v3.2.0          # just that tag
+ *   pnpm whats-new:preview --repo owner/r  # override the repo
+ *
+ * Reads GITHUB_RELEASES_REPO / GITHUB_RELEASES_TOKEN / APP_VERSION from server/.env.
+ */
+import { readFileSync } from 'node:fs';
+
+import { Logger } from '@nestjs/common';
+import type { ConfigService } from '@nestjs/config';
+
+import type { AppSettingsService } from '../modules/app-settings/app-settings.service';
+import { ReleaseNotesService } from '../modules/release-notes/release-notes.service';
+
+Logger.overrideLogger(false);
+
+function loadEnv(): Record<string, string> {
+  try {
+    const raw = readFileSync('.env', 'utf8');
+    const out: Record<string, string> = {};
+    for (const line of raw.split(/\r?\n/)) {
+      const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+      if (m && !line.startsWith('#')) out[m[1]] = m[2].trim();
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+async function checkReachable(url: string): Promise<{ ok: boolean; detail: string }> {
+  try {
+    const res = await fetch(url, { method: 'GET', headers: { Range: 'bytes=0-0' } });
+    const type = (res.headers.get('content-type') ?? '').split(';')[0];
+    return { ok: res.status >= 200 && res.status < 300, detail: `${res.status} ${type}` };
+  } catch {
+    return { ok: false, detail: 'unreachable' };
+  }
+}
+
+function printHelp(): void {
+  console.log(
+    [
+      'Usage: pnpm whats-new:preview [tag] [--repo owner/name]',
+      '',
+      "Renders exactly what the app will show for the configured repo's releases,",
+      'and probes each media URL for reachability.',
+      '',
+      '  [tag]         preview a single release (e.g. v4.5.0); omit for all on page 1',
+      '  --repo o/n    override the source repo',
+      '',
+      'Env (server/.env): GITHUB_RELEASES_REPO, GITHUB_RELEASES_TOKEN, APP_VERSION',
+    ].join('\n'),
+  );
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+  const env = { ...process.env, ...loadEnv() };
+  let repoOverride: string | undefined;
+  let tag: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--repo') repoOverride = args[++i];
+    else tag = args[i];
+  }
+
+  const repo = repoOverride ?? env.GITHUB_RELEASES_REPO ?? 'bookorbit/bookorbit';
+  const token = env.GITHUB_RELEASES_TOKEN;
+  const version = env.APP_VERSION;
+
+  const config = {
+    get: (key: string) =>
+      key === 'app.githubReleasesRepo' ? repo : key === 'app.githubReleasesToken' ? token : key === 'app.version' ? version : undefined,
+  } as unknown as ConfigService;
+  const appSettings = { isUpdateCheckEnabled: () => Promise.resolve(true) } as unknown as AppSettingsService;
+  const service = new ReleaseNotesService(config, appSettings);
+
+  console.log(`\nWhat's New preview  ·  repo=${repo}${tag ? `  tag=${tag}` : ''}\n${'─'.repeat(60)}`);
+
+  const { releases } = await service.getAll(1);
+  const shown = tag ? releases.filter((r) => r.version === tag) : releases;
+
+  if (shown.length === 0) {
+    if (releases.length === 0) {
+      const probe = await fetch(`https://api.github.com/repos/${repo}/releases?per_page=1`, {
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+      }).catch(() => null);
+      console.log(`No releases returned. GitHub API status: ${probe?.status ?? 'unreachable'} (check GITHUB_RELEASES_REPO / token).`);
+    } else {
+      console.log(`No release "${tag}" on page 1 (only the 30 most recent are checked).`);
+    }
+    return;
+  }
+
+  let warnings = 0;
+  for (const rel of shown) {
+    console.log(`\n■ ${rel.version}   ${rel.date?.slice(0, 10) ?? ''}`);
+
+    if (rel.highlights.length === 0) {
+      console.log('  ⚠ 0 highlights parsed - popup is skipped for this version (only the changelog shows).');
+      console.log('    If you wrote a "## Highlights" section, check the heading spelling and that bullets start with "- ".');
+      warnings++;
+    }
+
+    for (const h of rel.highlights) {
+      console.log(`  • ${h.icon ? `[${h.icon}]` : '[default icon]'}  ${h.title}`);
+      if (h.body) console.log(`      ${h.body.length > 96 ? `${h.body.slice(0, 96)}…` : h.body}`);
+      else {
+        console.log('      ⚠ no body text');
+        warnings++;
+      }
+
+      for (const m of h.media) {
+        const { ok, detail } = await checkReachable(m.url);
+        console.log(`      ${ok ? '✓' : '⚠'} ${m.type}: ${detail}  ${m.url}`);
+        if (!ok) warnings++;
+      }
+    }
+  }
+
+  console.log(`\n${'─'.repeat(60)}`);
+  console.log(warnings === 0 ? '✓ No problems detected - this is what BookOrbit will render.' : `⚠ ${warnings} warning(s) above.`);
+}
+
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+});