From 602fae8bb52c8e8afbbeb91a8462db4df9a7b050 Mon Sep 17 00:00:00 2001
From: Brendan Kellam <brendan@sourcebot.dev>
Date: Mon, 25 May 2026 14:14:13 -0700
Subject: [PATCH 1/4] changelog impl

---
 .../migration.sql                             |  14 ++
 packages/db/prisma/schema.prisma              |  15 ++
 packages/shared/src/env.server.ts             |   4 +
 .../components/changelogEntryDialog.tsx       | 168 +++++++++++++++
 .../components/defaultSidebar/index.tsx       |   1 -
 .../components/settingsSidebar/index.tsx      |   6 -
 .../(app)/@sidebar/components/sidebarBase.tsx |   3 +-
 .../components/whatsNewSidebarButton.tsx      | 194 +++++++++---------
 packages/web/src/app/api/(client)/client.ts   |  12 ++
 .../api/(server)/changelog/entries/route.ts   |  15 ++
 .../src/features/changelog/listEntriesApi.ts  |  41 ++++
 .../src/features/changelog/pollChangelog.ts   |  83 ++++++++
 packages/web/src/features/changelog/types.ts  |  17 ++
 packages/web/src/initialize.ts                |   2 +
 packages/web/src/lib/newsData.ts              |  88 --------
 15 files changed, 468 insertions(+), 195 deletions(-)
 create mode 100644 packages/db/prisma/migrations/20260525181404_add_changelog_table/migration.sql
 create mode 100644 packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx
 create mode 100644 packages/web/src/app/api/(server)/changelog/entries/route.ts
 create mode 100644 packages/web/src/features/changelog/listEntriesApi.ts
 create mode 100644 packages/web/src/features/changelog/pollChangelog.ts
 create mode 100644 packages/web/src/features/changelog/types.ts
 delete mode 100644 packages/web/src/lib/newsData.ts

diff --git a/packages/db/prisma/migrations/20260525181404_add_changelog_table/migration.sql b/packages/db/prisma/migrations/20260525181404_add_changelog_table/migration.sql
new file mode 100644
index 000000000..e3e7ee8e3
--- /dev/null
+++ b/packages/db/prisma/migrations/20260525181404_add_changelog_table/migration.sql
@@ -0,0 +1,14 @@
+-- CreateTable
+CREATE TABLE "ChangelogEntry" (
+    "slug" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "publishedAt" TIMESTAMP(3) NOT NULL,
+    "summary" TEXT,
+    "bodyMarkdown" TEXT NOT NULL,
+    "fetchedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "ChangelogEntry_pkey" PRIMARY KEY ("slug")
+);
+
+-- CreateIndex
+CREATE INDEX "ChangelogEntry_publishedAt_idx" ON "ChangelogEntry"("publishedAt");
diff --git a/packages/db/prisma/schema.prisma b/packages/db/prisma/schema.prisma
index 140c15b44..8c60236a4 100644
--- a/packages/db/prisma/schema.prisma
+++ b/packages/db/prisma/schema.prisma
@@ -623,3 +623,18 @@ model OAuthToken {
   createdAt  DateTime    @default(now())
   lastUsedAt DateTime?
 }
+
+/// Local cache of changelog entries fetched from the public feed at
+/// `CHANGELOG_FEED_URL`. Shared across all users of an instance.
+model ChangelogEntry {
+  slug         String   @id
+  title        String
+  publishedAt  DateTime
+  summary      String?
+  bodyMarkdown String
+
+  /// Updated each time the entry is upserted from the feed.
+  fetchedAt DateTime @default(now()) @updatedAt
+
+  @@index([publishedAt])
+}
diff --git a/packages/shared/src/env.server.ts b/packages/shared/src/env.server.ts
index 036655018..d9ee5cae3 100644
--- a/packages/shared/src/env.server.ts
+++ b/packages/shared/src/env.server.ts
@@ -221,6 +221,10 @@ const options = {
         // Misc UI flags
         SECURITY_CARD_ENABLED: booleanSchema.default('false'),
 
+        // Changelog feed
+        CHANGELOG_ENABLED: booleanSchema.default('true'),
+        CHANGELOG_FEED_URL: z.string().url().default('https://static.sourcebot.dev/changelog/index.json'),
+
         // EE License
         SOURCEBOT_EE_LICENSE_KEY: z.string().optional(),
         SOURCEBOT_EE_AUDIT_LOGGING_ENABLED: booleanSchema.default('true'),
diff --git a/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx b/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx
new file mode 100644
index 000000000..f985fe817
--- /dev/null
+++ b/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx
@@ -0,0 +1,168 @@
+"use client";
+
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import type { ChangelogEntryDto } from "@/features/changelog/listEntriesApi";
+import { cn } from "@/lib/utils";
+import { format } from "date-fns";
+import { useEffect, useMemo, useState } from "react";
+import { createPortal } from "react-dom";
+import Markdown from "react-markdown";
+import rehypeRaw from "rehype-raw";
+import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
+import remarkGfm from "remark-gfm";
+
+const VIDEO_EXTENSIONS_RE = /\.(mp4|webm|ogg|mov)$/i;
+const ABSOLUTE_URL_RE = /^(?:[a-z][a-z0-9+\-.]*:|\/\/|#)/i;
+
+// Allow <video> + the attributes we'll set on it. rehypeSanitize otherwise strips them.
+const SANITIZE_SCHEMA = {
+    ...defaultSchema,
+    tagNames: [...(defaultSchema.tagNames ?? []), "video", "source"],
+    attributes: {
+        ...defaultSchema.attributes,
+        video: ["src", "controls", "poster", "width", "height", "className", "preload", "loop", "muted", "playsInline"],
+        source: ["src", "type"],
+    },
+};
+
+const buildUrlTransform = (entriesBaseUrl: string) => (url: string): string => {
+    if (ABSOLUTE_URL_RE.test(url)) {
+        return url;
+    }
+    try {
+        return new URL(url, entriesBaseUrl).toString();
+    } catch {
+        return url;
+    }
+};
+
+interface ZoomableImageProps {
+    src: string;
+    alt?: string | undefined;
+}
+
+const ZoomableImage = ({ src, alt }: ZoomableImageProps) => {
+    const [zoomed, setZoomed] = useState(false);
+    const [mounted, setMounted] = useState(false);
+
+    // Portal target is only available after mount.
+    useEffect(() => {
+        setMounted(true);
+    }, []);
+
+    // Intercept Escape during zoom so the changelog dialog doesn't close along with the zoom.
+    useEffect(() => {
+        if (!zoomed) {
+            return;
+        }
+        const handleKey = (e: KeyboardEvent) => {
+            if (e.key === "Escape") {
+                e.stopPropagation();
+                setZoomed(false);
+            }
+        };
+        document.addEventListener("keydown", handleKey, true);
+        return () => document.removeEventListener("keydown", handleKey, true);
+    }, [zoomed]);
+
+    const overlay = (
+        <div
+            className={cn(
+                "fixed inset-0 z-[100] flex items-center justify-center bg-black/80 transition-opacity duration-200",
+                zoomed ? "opacity-100 pointer-events-auto cursor-zoom-out" : "opacity-0 pointer-events-none"
+            )}
+            onClick={() => setZoomed(false)}
+        >
+            {/* eslint-disable-next-line @next/next/no-img-element */}
+            <img
+                src={src}
+                alt={alt}
+                className={cn(
+                    "max-w-[90vw] max-h-[90vh] object-contain rounded-lg transition-transform duration-200",
+                    zoomed ? "scale-100" : "scale-95"
+                )}
+            />
+        </div>
+    );
+
+    return (
+        <>
+            {/* eslint-disable-next-line @next/next/no-img-element */}
+            <img
+                src={src}
+                alt={alt}
+                className="cursor-zoom-in"
+                onClick={() => setZoomed(true)}
+            />
+            {mounted && createPortal(overlay, document.body)}
+        </>
+    );
+};
+
+interface ChangelogEntryDialogProps {
+    entry: ChangelogEntryDto | null;
+    entriesBaseUrl: string;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+
+export function ChangelogEntryDialog({ entry, entriesBaseUrl, open, onOpenChange }: ChangelogEntryDialogProps) {
+    const urlTransform = useMemo(() => buildUrlTransform(entriesBaseUrl), [entriesBaseUrl]);
+
+    return (
+        <Dialog open={open} onOpenChange={onOpenChange}>
+            <DialogContent className="max-w-2xl max-h-[90vh] overflow-hidden flex flex-col gap-0 p-0 focus:outline-none">
+                {entry && (
+                    <>
+                        <DialogHeader className="px-6 pt-4 pb-4 border-b space-y-1">
+                            <p className="text-xs text-muted-foreground">
+                                {format(new Date(entry.publishedAt), "MMM d, yyyy")}
+                            </p>
+                            <DialogTitle className="sr-only">{entry.title}</DialogTitle>
+                        </DialogHeader>
+                        <div className="overflow-y-auto px-6 py-5">
+                            <div
+                                className={cn(
+                                    "prose dark:prose-invert max-w-none",
+                                    "prose-p:text-foreground prose-li:text-foreground prose-headings:text-foreground",
+                                    "prose-headings:mt-6 prose-p:my-3 prose-img:rounded-md prose-img:my-4 prose-hr:my-6",
+                                    "prose-h1:text-2xl prose-h2:text-xl prose-h3:text-lg prose-h4:text-base",
+                                    "prose-headings:font-semibold",
+                                    "prose-p:text-sm prose-li:text-sm",
+                                    "prose-p:leading-normal prose-li:leading-normal",
+                                    "prose-li:my-1 prose-ul:my-1 prose-ol:my-1 prose-li:marker:text-foreground",
+                                    "prose-a:text-link prose-a:no-underline hover:prose-a:underline",
+                                    "prose-blockquote:not-italic prose-blockquote:font-normal",
+                                    "prose-code:before:content-none prose-code:after:content-none prose-code:font-normal",
+                                    "prose-code:bg-muted prose-code:rounded prose-code:px-1.5 prose-code:py-0.5 prose-code:text-xs",
+                                    "prose-pre:bg-muted prose-pre:text-foreground prose-pre:leading-snug",
+                                    "[&_video]:rounded-md [&_video]:my-4 [&_video]:w-full",
+                                    "[&>*:first-child]:mt-0"
+                                )}
+                            >
+                                <Markdown
+                                    remarkPlugins={[remarkGfm]}
+                                    rehypePlugins={[rehypeRaw, [rehypeSanitize, SANITIZE_SCHEMA]]}
+                                    urlTransform={urlTransform}
+                                    components={{
+                                        img: ({ src, alt }) => {
+                                            if (typeof src !== "string") {
+                                                return null;
+                                            }
+                                            if (VIDEO_EXTENSIONS_RE.test(src)) {
+                                                return <video src={src} controls className="aspect-video" />;
+                                            }
+                                            return <ZoomableImage src={src} alt={alt} />;
+                                        },
+                                    }}
+                                >
+                                    {entry.bodyMarkdown}
+                                </Markdown>
+                            </div>
+                        </div>
+                    </>
+                )}
+            </DialogContent>
+        </Dialog>
+    );
+}
diff --git a/packages/web/src/app/(app)/@sidebar/components/defaultSidebar/index.tsx b/packages/web/src/app/(app)/@sidebar/components/defaultSidebar/index.tsx
index f17b2d2f0..c943e0ea5 100644
--- a/packages/web/src/app/(app)/@sidebar/components/defaultSidebar/index.tsx
+++ b/packages/web/src/app/(app)/@sidebar/components/defaultSidebar/index.tsx
@@ -54,7 +54,6 @@ export async function DefaultSidebar() {
             session={session}
             collapsible="icon"
             isValidLicenseActive={licenseActive}
-            isOwner={isOwner}
             headerContent={
                 <Nav
                     isSettingsNotificationVisible={isSettingsNotificationVisible}
diff --git a/packages/web/src/app/(app)/@sidebar/components/settingsSidebar/index.tsx b/packages/web/src/app/(app)/@sidebar/components/settingsSidebar/index.tsx
index 0089ace32..1672ac5cb 100644
--- a/packages/web/src/app/(app)/@sidebar/components/settingsSidebar/index.tsx
+++ b/packages/web/src/app/(app)/@sidebar/components/settingsSidebar/index.tsx
@@ -6,8 +6,6 @@ import { SidebarBase } from "../sidebarBase";
 import { Nav } from "./nav";
 import { SettingsSidebarHeader } from "./header";
 import { isValidLicenseActive } from "@/lib/entitlements";
-import { getAuthContext } from "@/middleware/withAuth";
-import { OrgRole } from "@prisma/client";
 
 export async function SettingsSidebar() {
     const session = await auth();
@@ -19,15 +17,11 @@ export async function SettingsSidebar() {
 
     const licenseActive = await isValidLicenseActive();
 
-    const authContext = await getAuthContext();
-    const isOwner = !isServiceError(authContext) && authContext.role === OrgRole.OWNER;
-
     return (
         <SidebarBase
             session={session}
             collapsible="none"
             isValidLicenseActive={licenseActive}
-            isOwner={isOwner}
             headerContent={<SettingsSidebarHeader />}
         >
             <Nav groups={sidebarNavGroups} />
diff --git a/packages/web/src/app/(app)/@sidebar/components/sidebarBase.tsx b/packages/web/src/app/(app)/@sidebar/components/sidebarBase.tsx
index d932fd7bb..f9694e07c 100644
--- a/packages/web/src/app/(app)/@sidebar/components/sidebarBase.tsx
+++ b/packages/web/src/app/(app)/@sidebar/components/sidebarBase.tsx
@@ -52,10 +52,9 @@ interface SidebarBaseProps {
     headerContent: ReactNode;
     children: ReactNode;
     isValidLicenseActive: boolean;
-    isOwner: boolean;
 }
 
-export function SidebarBase({ session, collapsible = "icon", headerContent, children, isValidLicenseActive, isOwner }: SidebarBaseProps) {
+export function SidebarBase({ session, collapsible = "icon", headerContent, children, isValidLicenseActive }: SidebarBaseProps) {
     const [isScrolled, setIsScrolled] = useState(false);
     const contentRef = useRef<HTMLDivElement>(null);
 
diff --git a/packages/web/src/app/(app)/@sidebar/components/whatsNewSidebarButton.tsx b/packages/web/src/app/(app)/@sidebar/components/whatsNewSidebarButton.tsx
index 6cb225ca0..9d216fe53 100644
--- a/packages/web/src/app/(app)/@sidebar/components/whatsNewSidebarButton.tsx
+++ b/packages/web/src/app/(app)/@sidebar/components/whatsNewSidebarButton.tsx
@@ -11,58 +11,26 @@ import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover
 import { Separator } from "@/components/ui/separator"
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
 import { Button } from "@/components/ui/button"
-import { newsData } from "@/lib/newsData"
-import { NewsItem } from "@/lib/types"
+import { listChangelogEntries } from "@/app/api/(client)/client"
+import { unwrapServiceError } from "@/lib/utils"
 import { env, SOURCEBOT_VERSION } from "@sourcebot/shared/client"
-import { Compass, Mail, MailOpen } from "lucide-react"
+import { useQuery } from "@tanstack/react-query"
+import { Compass, Loader2, Mail, MailOpen } from "lucide-react"
 import Link from "next/link"
-import { useCallback, useEffect, useState } from "react"
+import { useCallback, useMemo, useState } from "react"
 import { useHotkeys } from "react-hotkeys-hook"
+import { useLocalStorage } from "usehooks-ts"
 import { KeyboardShortcutHint } from "@/app/components/keyboardShortcutHint"
+import { ChangelogEntryDialog } from "./changelogEntryDialog"
 
-const COOKIE_NAME = "whats-new-read-items"
-
-const getReadItems = (): string[] => {
-    if (typeof document === "undefined") {
-        return []
-    }
-
-    const cookies = document.cookie.split(';').map(cookie => cookie.trim())
-    const targetCookie = cookies.find(cookie => cookie.startsWith(`${COOKIE_NAME}=`))
-
-    if (!targetCookie) {
-        return []
-    }
-
-    try {
-        const cookieValue = targetCookie.substring(`${COOKIE_NAME}=`.length)
-        return JSON.parse(decodeURIComponent(cookieValue))
-    } catch {
-        return []
-    }
-}
-
-const setReadItems = (readItems: string[]) => {
-    if (typeof document === "undefined") {
-        return
-    }
-
-    try {
-        const expires = new Date()
-        expires.setFullYear(expires.getFullYear() + 1)
-        const cookieValue = encodeURIComponent(JSON.stringify(readItems))
-        document.cookie = `${COOKIE_NAME}=${cookieValue}; expires=${expires.toUTCString()}; path=/; SameSite=Lax`
-    } catch {
-        // ignore
-    }
-}
+const STORAGE_KEY = "whats-new-read-items"
 
 export function WhatsNewSidebarButton() {
     const { state } = useSidebar()
     const [isOpen, setIsOpen] = useState(false)
     const [tooltipOpen, setTooltipOpen] = useState(false)
-    const [readItems, setReadItemsState] = useState<string[]>([])
-    const [isInitialized, setIsInitialized] = useState(false)
+    const [readItems, setReadItems] = useLocalStorage<string[]>(STORAGE_KEY, [], { initializeWithValue: false })
+    const [selectedSlug, setSelectedSlug] = useState<string | null>(null)
 
     const toggleOpen = useCallback(() => {
         setIsOpen(prev => !prev)
@@ -73,42 +41,56 @@ export function WhatsNewSidebarButton() {
         toggleOpen();
     });
 
-    useEffect(() => {
-        const items = getReadItems()
-        setReadItemsState(items)
-        setIsInitialized(true)
-    }, [])
-
-    useEffect(() => {
-        if (isInitialized) {
-            setReadItems(readItems)
+    const {
+        data: { entries, entriesBaseUrl } = {
+            entries: [],
+            entriesBaseUrl: ""
+        },
+        isPending
+    } = useQuery({
+        queryKey: ["changelog-entries"],
+        queryFn: () => unwrapServiceError(listChangelogEntries()),
+        select: (response) => {
+            return {
+                entries: response.entries.map((entry) => ({
+                    ...entry,
+                    read: readItems.includes(entry.slug)
+                })),
+                entriesBaseUrl: response.entriesBaseUrl,
+            }
         }
-    }, [readItems, isInitialized])
+    })
 
-    const newsItemsWithReadState = newsData.map((item) => ({
-        ...item,
-        read: readItems.includes(item.unique_id),
-    }))
+    const selectedEntry = useMemo(
+        () => entries.find((entry) => entry.slug === selectedSlug) ?? null,
+        [entries, selectedSlug]
+    )
 
-    const unreadCount = newsItemsWithReadState.filter((item) => !item.read).length
+    const unreadCount = entries.filter((item) => !item.read).length
 
-    const markAsRead = (itemId: string) => {
-        setReadItemsState((prev) => {
-            if (!prev.includes(itemId)) {
-                return [...prev, itemId]
+    const markAsRead = (slug: string) => {
+        setReadItems((prev) => {
+            if (!prev.includes(slug)) {
+                return [...prev, slug]
             }
             return prev
         })
     }
 
     const markAllAsRead = () => {
-        const allIds = newsData.map((item) => item.unique_id)
-        setReadItemsState(allIds)
+        setReadItems(entries.map((entry) => entry.slug))
     }
 
-    const handleNewsItemClick = (item: NewsItem) => {
-        window.open(item.url, "_blank", "noopener,noreferrer")
-        markAsRead(item.unique_id)
+    const handleEntryClick = (slug: string) => {
+        setIsOpen(false)
+        setSelectedSlug(slug)
+        markAsRead(slug)
+    }
+
+    const handleDialogOpenChange = (open: boolean) => {
+        if (!open) {
+            setSelectedSlug(null)
+        }
     }
 
     return (
@@ -133,51 +115,59 @@ export function WhatsNewSidebarButton() {
                             <span>{"What's new"}</span>
                         </TooltipContent>
                     </Tooltip>
-                    {isInitialized && unreadCount > 0 && (
+                    {unreadCount > 0 && (
                         <SidebarMenuBadge className="rounded-full bg-blue-500 text-white peer-hover/menu-button:text-white px-1.5">
                             {unreadCount > 9 ? "9+" : unreadCount}
                         </SidebarMenuBadge>
                     )}
                     <PopoverContent className="w-80 p-0" side="right" align="end" sideOffset={8}>
-                        <div className="border-b p-4">
-                            <div className="flex items-center justify-between">
-                                <div>
-                                    <h3 className="font-semibold text-sm">{"What's New"}</h3>
-                                    <p className="text-xs text-muted-foreground mt-1">
-                                        {unreadCount > 0 ? `${unreadCount} unread update${unreadCount === 1 ? "" : "s"}` : "All caught up"}
-                                    </p>
-                                </div>
-                                {unreadCount > 0 && (
-                                    <Button variant="ghost" size="sm" onClick={markAllAsRead} className="text-xs h-7">
-                                        Mark all read
-                                    </Button>
-                                )}
+                        {isPending ? (
+                            <div className="flex items-center justify-center p-8">
+                                <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
                             </div>
-                        </div>
-                        <div className="max-h-[32rem] overflow-y-auto scrollbar-thin scrollbar-thumb-muted-foreground/20 scrollbar-track-transparent">
-                            {newsItemsWithReadState.length === 0 ? (
-                                <div className="p-4 text-center text-sm text-muted-foreground">No recent updates</div>
-                            ) : (
-                                <div className="space-y-1 p-2">
-                                    {newsItemsWithReadState.map((item, index) => (
+                        ) : (
+                            <>
+                                <div className="border-b p-4">
+                                    <div className="flex items-center justify-between">
+                                        <div>
+                                            <h3 className="font-semibold text-sm">{"What's New"}</h3>
+                                            <p className="text-xs text-muted-foreground mt-1">
+                                                {unreadCount > 0 ? `${unreadCount} unread update${unreadCount === 1 ? "" : "s"}` : "All caught up"}
+                                            </p>
+                                        </div>
+                                        {unreadCount > 0 && (
+                                            <Button variant="ghost" size="sm" onClick={markAllAsRead} className="text-xs h-7">
+                                                Mark all read
+                                            </Button>
+                                        )}
+                                    </div>
+                                </div>
+                                <div className="max-h-[32rem] overflow-y-auto scrollbar-thin scrollbar-thumb-muted-foreground/20 scrollbar-track-transparent">
+                                    {entries.length === 0 ? (
+                                        <div className="p-4 text-center text-sm text-muted-foreground">No recent updates</div>
+                                    ) : (
+                                        <div className="space-y-1 p-2">
+                                            {entries.map((entry, index) => (
                                         <div
-                                            key={item.unique_id}
-                                            className={`relative rounded-md transition-colors ${item.read ? "opacity-60" : ""} ${index !== newsItemsWithReadState.length - 1 ? "border-b border-border/50" : ""}`}
+                                            key={entry.slug}
+                                            className={`relative rounded-md transition-colors ${entry.read ? "opacity-60" : ""} ${index !== entries.length - 1 ? "border-b border-border/50" : ""}`}
                                         >
-                                            {!item.read && <div className="absolute left-2 top-3 h-2 w-2 bg-blue-500 rounded-full" />}
+                                            {!entry.read && <div className="absolute left-2 top-3 h-2 w-2 bg-blue-500 rounded-full" />}
                                             <button
-                                                onClick={() => handleNewsItemClick(item)}
+                                                onClick={() => handleEntryClick(entry.slug)}
                                                 className="w-full text-left p-3 pl-6 rounded-md hover:bg-muted transition-colors group"
                                             >
                                                 <div className="flex items-start justify-between gap-2">
                                                     <div className="flex-1 min-w-0">
-                                                        <h4 className={`font-medium text-sm leading-tight group-hover:text-primary ${item.read ? "text-muted-foreground" : ""}`}>
-                                                            {item.header}
+                                                        <h4 className={`font-medium text-sm leading-tight group-hover:text-primary ${entry.read ? "text-muted-foreground" : ""}`}>
+                                                            {entry.title}
                                                         </h4>
-                                                        <p className="text-xs text-muted-foreground mt-1 line-clamp-2">{item.sub_header}</p>
+                                                        {entry.summary && (
+                                                            <p className="text-xs text-muted-foreground mt-1 line-clamp-2">{entry.summary}</p>
+                                                        )}
                                                     </div>
-                                                    <div className="flex items-center gap-1 flex-shrink-0">
-                                                        {item.read ? (
+                                                    <div className="flex items-center gap-1 flex-shrink-0 mt-1">
+                                                        {entry.read ? (
                                                             <MailOpen className="h-3 w-3 text-muted-foreground group-hover:text-primary" />
                                                         ) : (
                                                             <Mail className="h-3 w-3 text-muted-foreground group-hover:text-primary" />
@@ -187,9 +177,11 @@ export function WhatsNewSidebarButton() {
                                             </button>
                                         </div>
                                     ))}
+                                        </div>
+                                    )}
                                 </div>
-                            )}
-                        </div>
+                            </>
+                        )}
                         <Separator />
                         <div className="px-2 py-2 text-xs text-muted-foreground">
                             Current version: {SOURCEBOT_VERSION}
@@ -205,6 +197,12 @@ export function WhatsNewSidebarButton() {
                     </PopoverContent>
                 </Popover>
             </SidebarMenuItem>
+            <ChangelogEntryDialog
+                entry={selectedEntry}
+                entriesBaseUrl={entriesBaseUrl}
+                open={selectedSlug !== null}
+                onOpenChange={handleDialogOpenChange}
+            />
         </SidebarMenu>
     )
 }
diff --git a/packages/web/src/app/api/(client)/client.ts b/packages/web/src/app/api/(client)/client.ts
index cd7596468..0fd119050 100644
--- a/packages/web/src/app/api/(client)/client.ts
+++ b/packages/web/src/app/api/(client)/client.ts
@@ -23,6 +23,7 @@ import {
     ListCommitsQueryParams,
     ListCommitsResponse,
 } from "@/features/git";
+import type { ListChangelogEntriesResponse } from "@/features/changelog/listEntriesApi";
 import type { PermissionSyncStatusResponse } from "../(server)/ee/permissionSyncStatus/api";
 import type { AccountSyncStatusResponse } from "../(server)/ee/accountPermissionSyncJobStatus/api";
 import type {
@@ -92,6 +93,17 @@ export const getVersion = async (): Promise<GetVersionResponse> => {
     return result as GetVersionResponse;
 }
 
+export const listChangelogEntries = async (): Promise<ListChangelogEntriesResponse | ServiceError> => {
+    const result = await fetch("/api/changelog/entries", {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Sourcebot-Client-Source": "sourcebot-web-client",
+        },
+    }).then(response => response.json());
+    return result as ListChangelogEntriesResponse | ServiceError;
+}
+
 export const findSearchBasedSymbolReferences = async (body: FindRelatedSymbolsRequest): Promise<FindRelatedSymbolsResponse | ServiceError> => {
     const result = await fetch("/api/find_references", {
         method: "POST",
diff --git a/packages/web/src/app/api/(server)/changelog/entries/route.ts b/packages/web/src/app/api/(server)/changelog/entries/route.ts
new file mode 100644
index 000000000..07427981e
--- /dev/null
+++ b/packages/web/src/app/api/(server)/changelog/entries/route.ts
@@ -0,0 +1,15 @@
+import { listChangelogEntries } from "@/features/changelog/listEntriesApi";
+import { apiHandler } from "@/lib/apiHandler";
+import { serviceErrorResponse } from "@/lib/serviceError";
+import { isServiceError } from "@/lib/utils";
+
+// eslint-disable-next-line authz/require-auth-wrapper -- delegates to listChangelogEntries() which calls withOptionalAuth
+export const GET = apiHandler(async () => {
+    const response = await listChangelogEntries();
+
+    if (isServiceError(response)) {
+        return serviceErrorResponse(response);
+    }
+
+    return Response.json(response);
+});
diff --git a/packages/web/src/features/changelog/listEntriesApi.ts b/packages/web/src/features/changelog/listEntriesApi.ts
new file mode 100644
index 000000000..5a5dd8a31
--- /dev/null
+++ b/packages/web/src/features/changelog/listEntriesApi.ts
@@ -0,0 +1,41 @@
+import { sew } from "@/middleware/sew";
+import { withOptionalAuth } from "@/middleware/withAuth";
+import { env } from "@sourcebot/shared";
+
+export type ChangelogEntryDto = {
+    slug: string;
+    title: string;
+    publishedAt: string;
+    summary: string | null;
+    bodyMarkdown: string;
+};
+
+export type ListChangelogEntriesResponse = {
+    entries: ChangelogEntryDto[];
+    /// Base URL used to resolve relative media references in `bodyMarkdown`
+    /// (e.g. `../media/<slug>/foo.png`). Derived from CHANGELOG_FEED_URL.
+    entriesBaseUrl: string;
+};
+
+export const listChangelogEntries = async () =>
+    sew(() =>
+        withOptionalAuth(async ({ prisma }) => {
+            const entries = await prisma.changelogEntry.findMany({
+                orderBy: { publishedAt: "desc" },
+            });
+
+            const entriesBaseUrl = new URL("entries/", env.CHANGELOG_FEED_URL).toString();
+
+            const result: ListChangelogEntriesResponse = {
+                entries: entries.map((entry) => ({
+                    slug: entry.slug,
+                    title: entry.title,
+                    publishedAt: entry.publishedAt.toISOString(),
+                    summary: entry.summary,
+                    bodyMarkdown: entry.bodyMarkdown,
+                })),
+                entriesBaseUrl,
+            };
+            return result;
+        })
+    );
diff --git a/packages/web/src/features/changelog/pollChangelog.ts b/packages/web/src/features/changelog/pollChangelog.ts
new file mode 100644
index 000000000..5054935a9
--- /dev/null
+++ b/packages/web/src/features/changelog/pollChangelog.ts
@@ -0,0 +1,83 @@
+import { __unsafePrisma } from "@/prisma";
+import { createLogger, env } from "@sourcebot/shared";
+import { changelogFeedIndexSchema, type ChangelogFeedIndexEntry } from "./types";
+
+const logger = createLogger("changelog");
+
+const POLL_INTERVAL_MS = 6 * 60 * 60 * 1000; // 6 hours
+const FETCH_TIMEOUT_MS = 10 * 1000;
+
+const FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/;
+
+const stripFrontmatter = (markdown: string): string => markdown.replace(FRONTMATTER_RE, "").trimStart();
+
+const fetchWithTimeout = async (url: string): Promise<Response> => {
+    const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!response.ok) {
+        throw new Error(`GET ${url} failed: ${response.status} ${response.statusText}`);
+    }
+    return response;
+};
+
+const upsertEntry = async (entry: ChangelogFeedIndexEntry, baseUrl: string): Promise<void> => {
+    const bodyUrl = new URL(entry.path, baseUrl).toString();
+    const response = await fetchWithTimeout(bodyUrl);
+    const rawMarkdown = await response.text();
+    const bodyMarkdown = stripFrontmatter(rawMarkdown);
+
+    const data = {
+        slug: entry.slug,
+        title: entry.title,
+        publishedAt: new Date(entry.publishedAt),
+        summary: entry.summary ?? null,
+        bodyMarkdown,
+    };
+
+    await __unsafePrisma.changelogEntry.upsert({
+        where: { slug: entry.slug },
+        create: data,
+        update: data,
+    });
+};
+
+export const pollChangelog = async (): Promise<void> => {
+    if (env.CHANGELOG_ENABLED !== "true") {
+        return;
+    }
+
+    const feedUrl = env.CHANGELOG_FEED_URL;
+
+    let parsedIndex;
+    try {
+        const response = await fetchWithTimeout(feedUrl);
+        const json = await response.json();
+        parsedIndex = changelogFeedIndexSchema.parse(json);
+    } catch (err) {
+        // Network or parse failure — keep serving whatever is cached.
+        logger.warn(`Failed to fetch changelog index from ${feedUrl}: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+
+    let upserted = 0;
+    for (const entry of parsedIndex.entries) {
+        try {
+            await upsertEntry(entry, feedUrl);
+            upserted++;
+        } catch (err) {
+            logger.warn(`Failed to upsert changelog entry '${entry.slug}': ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+
+    logger.debug(`Changelog poll complete: ${upserted}/${parsedIndex.entries.length} entries upserted`);
+};
+
+export const startChangelogPollingJob = (): void => {
+    if (env.CHANGELOG_ENABLED !== "true") {
+        logger.info("Changelog feed disabled via CHANGELOG_ENABLED — skipping poll job");
+        return;
+    }
+    pollChangelog().catch(() => { /* logged inside */ });
+    setInterval(() => {
+        pollChangelog().catch(() => { /* logged inside */ });
+    }, POLL_INTERVAL_MS);
+};
diff --git a/packages/web/src/features/changelog/types.ts b/packages/web/src/features/changelog/types.ts
new file mode 100644
index 000000000..d2168e23a
--- /dev/null
+++ b/packages/web/src/features/changelog/types.ts
@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+export const changelogFeedIndexEntrySchema = z.object({
+    slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    title: z.string().min(1),
+    publishedAt: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+    summary: z.string().min(1).optional(),
+    path: z.string().min(1),
+});
+
+export const changelogFeedIndexSchema = z.object({
+    schemaVersion: z.literal(1),
+    entries: z.array(changelogFeedIndexEntrySchema),
+});
+
+export type ChangelogFeedIndex = z.infer<typeof changelogFeedIndexSchema>;
+export type ChangelogFeedIndexEntry = z.infer<typeof changelogFeedIndexEntrySchema>;
diff --git a/packages/web/src/initialize.ts b/packages/web/src/initialize.ts
index 1ab1ef441..c866aeaff 100644
--- a/packages/web/src/initialize.ts
+++ b/packages/web/src/initialize.ts
@@ -1,5 +1,6 @@
 import { __unsafePrisma } from "@/prisma";
 import { startServicePingCronJob } from '@/ee/features/lighthouse/servicePing';
+import { startChangelogPollingJob } from '@/features/changelog/pollChangelog';
 import { createLogger, env } from "@sourcebot/shared";
 import { hasEntitlement } from '@/lib/entitlements';
 import { SINGLE_TENANT_ORG_ID } from './lib/constants';
@@ -36,4 +37,5 @@ const init = async () => {
 (async () => {
     await init();
     startServicePingCronJob();
+    startChangelogPollingJob();
 })();
diff --git a/packages/web/src/lib/newsData.ts b/packages/web/src/lib/newsData.ts
deleted file mode 100644
index 16e71ad14..000000000
--- a/packages/web/src/lib/newsData.ts
+++ /dev/null
@@ -1,88 +0,0 @@
-import { NewsItem } from "./types";
-
-export const newsData: NewsItem[] = [
-    {
-        unique_id: "analytics-by-source",
-        header: "MCP Analytics",
-        sub_header: "We've extended analytics to include data on MCP/API usage",
-        url: "https://docs.sourcebot.dev/docs/features/analytics"
-    },
-    {
-        unique_id: "mcp-server",
-        header: "Remote MCP Server",
-        sub_header: "Sourcebot now exposes a built-in MCP server over Streamable HTTP with OAuth.",
-        url: "https://docs.sourcebot.dev/docs/features/mcp-server"
-    },
-    {
-        unique_id: "ai-search-assist",
-        header: "AI Search Assist",
-        sub_header: "Describe what you're looking for in natural language and AI will generate a code search query for you.",
-        url: "https://docs.sourcebot.dev/docs/features/search/ai-search-assist"
-    },
-    {
-        unique_id: "chat-sharing",
-        header: "Chat Sharing",
-        sub_header: "Share Ask Sourcebot chats via link or with specific team members.",
-        url: "https://docs.sourcebot.dev/docs/features/ask/chat-sharing"
-    },
-    {
-        unique_id: "ask-sourcebot",
-        header: "Ask Sourcebot",
-        sub_header: "Ask Sourcebot to search, summarize, and explain code. Bring your own LLM.",
-        url: "https://docs.sourcebot.dev/docs/features/ask/overview"
-    },
-    {
-        unique_id: "anonymous-access",
-        header: "Anonymous Access",
-        sub_header: "We've added the ability to disable the need for users to login to Sourcebot.",
-        url: "https://docs.sourcebot.dev/docs/configuration/auth/access-settings"
-    },
-    {
-        unique_id: "member-approval",
-        header: "Member Approval",
-        sub_header: "We've added a toggle to control whether new users need to be approved.",
-        url: "https://docs.sourcebot.dev/docs/configuration/auth/access-settings"
-    },
-    {
-        unique_id: "analytics",
-        header: "Analytics Dashboard",
-        sub_header: "Understand your team's Sourcebot usage",
-        url: "https://docs.sourcebot.dev/docs/features/analytics"
-    },
-    {
-        unique_id: "audit-logs",
-        header: "Audit Logs",
-        sub_header: "We've added support for audit logs",
-        url: "https://docs.sourcebot.dev/docs/configuration/audit-logs"
-    },
-    {
-        unique_id: "file-explorer",
-        header: "File Explorer",
-        sub_header: "We've added support for a file explorer when browsing files.",
-        url: "https://github.com/sourcebot-dev/sourcebot/releases/tag/v4.2.0"
-    },
-    {
-        unique_id: "structured-logging",
-        header: "Structured Logging",
-        sub_header: "We've added support for structured logging",
-        url: "https://docs.sourcebot.dev/docs/configuration/structured-logging"
-    },
-    {
-        unique_id: "code-nav",
-        header: "Code Navigation",
-        sub_header: "Built in go-to definition and find references",
-        url: "https://docs.sourcebot.dev/docs/features/code-navigation"
-    },
-    {
-        unique_id: "sso",
-        header: "SSO",
-        sub_header: "We've added support for SSO providers",
-        url: "https://docs.sourcebot.dev/docs/configuration/auth/overview",
-    },
-    {
-        unique_id: "search-contexts",
-        header: "Search Contexts",
-        sub_header: "Filter searches by groups of repos",
-        url: "https://docs.sourcebot.dev/docs/features/search/search-contexts"
-    }
-];
\ No newline at end of file

From 57b2b06b1b87c79ebe7b457741ca968d739a63a0 Mon Sep 17 00:00:00 2001
From: Brendan Kellam <brendan@sourcebot.dev>
Date: Mon, 25 May 2026 14:15:31 -0700
Subject: [PATCH 2/4] changelog

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f0c95111c..75bbef4cf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Added progress bar when navigating between pages. [#1204](https://github.com/sourcebot-dev/sourcebot/pull/1204)
+- Added a integrated changelog into the sidebar. [#1227](https://github.com/sourcebot-dev/sourcebot/pull/1227)
 
 ### Changed
 - Redesigned the app layout with a new collapsible sidebar navigation, replacing the previous top navigation bar. [#1097](https://github.com/sourcebot-dev/sourcebot/pull/1097)

From 75ef75f438737293d4cdcbefe5e117c70d295757 Mon Sep 17 00:00:00 2001
From: Brendan Kellam <brendan@sourcebot.dev>
Date: Mon, 25 May 2026 15:16:48 -0700
Subject: [PATCH 3/4] add version field & further polish

---
 .../migration.sql                             |  3 +-
 packages/db/prisma/schema.prisma              |  3 +-
 packages/shared/src/index.client.ts           |  8 +++-
 packages/shared/src/index.server.ts           |  8 +++-
 packages/shared/src/versionUtils.ts           | 36 ++++++++++++++
 .../components/changelogEntryDialog.tsx       | 47 +++++++++++++++++--
 .../src/app/(app)/components/upgradeToast.tsx | 39 ++-------------
 .../src/features/changelog/listEntriesApi.ts  |  4 +-
 .../src/features/changelog/pollChangelog.ts   |  3 +-
 packages/web/src/features/changelog/types.ts  |  3 +-
 10 files changed, 109 insertions(+), 45 deletions(-)
 rename packages/db/prisma/migrations/{20260525181404_add_changelog_table => 20260525214409_add_changelog_table}/migration.sql (87%)
 create mode 100644 packages/shared/src/versionUtils.ts

diff --git a/packages/db/prisma/migrations/20260525181404_add_changelog_table/migration.sql b/packages/db/prisma/migrations/20260525214409_add_changelog_table/migration.sql
similarity index 87%
rename from packages/db/prisma/migrations/20260525181404_add_changelog_table/migration.sql
rename to packages/db/prisma/migrations/20260525214409_add_changelog_table/migration.sql
index e3e7ee8e3..184d6656d 100644
--- a/packages/db/prisma/migrations/20260525181404_add_changelog_table/migration.sql
+++ b/packages/db/prisma/migrations/20260525214409_add_changelog_table/migration.sql
@@ -3,7 +3,8 @@ CREATE TABLE "ChangelogEntry" (
     "slug" TEXT NOT NULL,
     "title" TEXT NOT NULL,
     "publishedAt" TIMESTAMP(3) NOT NULL,
-    "summary" TEXT,
+    "summary" TEXT NOT NULL,
+    "version" TEXT NOT NULL,
     "bodyMarkdown" TEXT NOT NULL,
     "fetchedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
 
diff --git a/packages/db/prisma/schema.prisma b/packages/db/prisma/schema.prisma
index 8c60236a4..5be0a4ce9 100644
--- a/packages/db/prisma/schema.prisma
+++ b/packages/db/prisma/schema.prisma
@@ -630,7 +630,8 @@ model ChangelogEntry {
   slug         String   @id
   title        String
   publishedAt  DateTime
-  summary      String?
+  summary      String
+  version      String
   bodyMarkdown String
 
   /// Updated each time the entry is upserted from the feed.
diff --git a/packages/shared/src/index.client.ts b/packages/shared/src/index.client.ts
index 8e2a161dd..05a248168 100644
--- a/packages/shared/src/index.client.ts
+++ b/packages/shared/src/index.client.ts
@@ -4,4 +4,10 @@ export {
 } from "./env.client.js";
 export {
     SOURCEBOT_VERSION,
-} from "./version.js";
\ No newline at end of file
+} from "./version.js";
+export {
+    parseVersion,
+    formatVersion,
+    compareVersions,
+} from "./versionUtils.js";
+export type { Version } from "./versionUtils.js";
\ No newline at end of file
diff --git a/packages/shared/src/index.server.ts b/packages/shared/src/index.server.ts
index 1c45eb3cf..ce905c773 100644
--- a/packages/shared/src/index.server.ts
+++ b/packages/shared/src/index.server.ts
@@ -67,4 +67,10 @@ export {
 } from "./smtp.js";
 export {
     SOURCEBOT_VERSION,
-} from "./version.js";
\ No newline at end of file
+} from "./version.js";
+export {
+    parseVersion,
+    formatVersion,
+    compareVersions,
+} from "./versionUtils.js";
+export type { Version } from "./versionUtils.js";
\ No newline at end of file
diff --git a/packages/shared/src/versionUtils.ts b/packages/shared/src/versionUtils.ts
new file mode 100644
index 000000000..84cef78bf
--- /dev/null
+++ b/packages/shared/src/versionUtils.ts
@@ -0,0 +1,36 @@
+const SEMVER_REGEX = /^v(\d+)\.(\d+)\.(\d+)$/;
+
+export type Version = {
+    major: number;
+    minor: number;
+    patch: number;
+};
+
+export const parseVersion = (version: string): Version | null => {
+    const match = version.match(SEMVER_REGEX);
+    if (!match) {
+        return null;
+    }
+    return {
+        major: parseInt(match[1]),
+        minor: parseInt(match[2]),
+        patch: parseInt(match[3]),
+    };
+};
+
+export const formatVersion = (version: Version): string => {
+    return `v${version.major}.${version.minor}.${version.patch}`;
+};
+
+/**
+ * Returns < 0 if `a < b`, 0 if equal, > 0 if `a > b`.
+ */
+export const compareVersions = (a: Version, b: Version): number => {
+    if (a.major !== b.major) {
+        return a.major - b.major;
+    }
+    if (a.minor !== b.minor) {
+        return a.minor - b.minor;
+    }
+    return a.patch - b.patch;
+};
diff --git a/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx b/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx
index f985fe817..57eaca429 100644
--- a/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx
+++ b/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx
@@ -1,15 +1,20 @@
 "use client";
 
+import { Badge } from "@/components/ui/badge";
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 import type { ChangelogEntryDto } from "@/features/changelog/listEntriesApi";
 import { cn } from "@/lib/utils";
 import { format } from "date-fns";
+import { ArrowUpRight } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
 import { createPortal } from "react-dom";
 import Markdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
 import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
 import remarkGfm from "remark-gfm";
+import { compareVersions, parseVersion, SOURCEBOT_VERSION } from "@sourcebot/shared/client";
 
 const VIDEO_EXTENSIONS_RE = /\.(mp4|webm|ogg|mov)$/i;
 const ABSOLUTE_URL_RE = /^(?:[a-z][a-z0-9+\-.]*:|\/\/|#)/i;
@@ -109,15 +114,51 @@ interface ChangelogEntryDialogProps {
 export function ChangelogEntryDialog({ entry, entriesBaseUrl, open, onOpenChange }: ChangelogEntryDialogProps) {
     const urlTransform = useMemo(() => buildUrlTransform(entriesBaseUrl), [entriesBaseUrl]);
 
+    const upgradeAvailable = useMemo(() => {
+        if (!entry) {
+            return false;
+        }
+        const entryVersion = parseVersion(entry.version);
+        const currentVersion = parseVersion(SOURCEBOT_VERSION);
+        if (!entryVersion || !currentVersion) {
+            return false;
+        }
+        return compareVersions(entryVersion, currentVersion) > 0;
+    }, [entry]);
+
     return (
         <Dialog open={open} onOpenChange={onOpenChange}>
             <DialogContent className="max-w-2xl max-h-[90vh] overflow-hidden flex flex-col gap-0 p-0 focus:outline-none">
                 {entry && (
                     <>
                         <DialogHeader className="px-6 pt-4 pb-4 border-b space-y-1">
-                            <p className="text-xs text-muted-foreground">
-                                {format(new Date(entry.publishedAt), "MMM d, yyyy")}
-                            </p>
+                            <div className="flex items-center gap-2 text-xs text-muted-foreground">
+                                <span>{format(new Date(entry.publishedAt), "MMM d")}</span>
+                                {upgradeAvailable && (
+                                    <>
+                                        <span>·</span>
+                                        <Tooltip>
+                                            <TooltipTrigger asChild>
+                                                <a
+                                                    href={`https://github.com/sourcebot-dev/sourcebot/releases/tag/${entry.version}`}
+                                                    target="_blank"
+                                                    rel="noopener noreferrer"
+                                                >
+                                                    <Badge className="bg-purple-500/20 text-purple-400 border-purple-500/30 hover:bg-purple-500/30 gap-0.5">
+                                                        Upgrade
+                                                        <ArrowUpRight className="h-3 w-3" />
+                                                    </Badge>
+                                                </a>
+                                            </TooltipTrigger>
+                                            <TooltipPrimitive.Portal>
+                                                <TooltipContent side="bottom">
+                                                    This update requires <span className="font-mono">{entry.version}</span>. Your instance is on <span className="font-mono">{SOURCEBOT_VERSION}</span>.
+                                                </TooltipContent>
+                                            </TooltipPrimitive.Portal>
+                                        </Tooltip>
+                                    </>
+                                )}
+                            </div>
                             <DialogTitle className="sr-only">{entry.title}</DialogTitle>
                         </DialogHeader>
                         <div className="overflow-y-auto px-6 py-5">
diff --git a/packages/web/src/app/(app)/components/upgradeToast.tsx b/packages/web/src/app/(app)/components/upgradeToast.tsx
index e3b8bf29c..8aea8c806 100644
--- a/packages/web/src/app/(app)/components/upgradeToast.tsx
+++ b/packages/web/src/app/(app)/components/upgradeToast.tsx
@@ -6,17 +6,11 @@ import { useEffect } from "react";
 import { useLocalStorage } from "usehooks-ts";
 import { getVersion } from "@/app/api/(client)/client";
 import { useQuery } from "@tanstack/react-query";
+import { compareVersions, formatVersion, parseVersion } from "@sourcebot/shared/client";
 
 const GITHUB_TAGS_URL = "https://api.github.com/repos/sourcebot-dev/sourcebot/tags";
-const SEMVER_REGEX = /^v(\d+)\.(\d+)\.(\d+)$/;
 const TOAST_TIMEOUT_MS = 1000 * 60 * 60 * 24;
 
-type Version = {
-    major: number;
-    minor: number;
-    patch: number;
-};
-
 export const UpgradeToast = () => {
     const { toast } = useToast();
     const [ upgradeToastLastShownDate, setUpgradeToastLastShownDate ] = useLocalStorage<string>(
@@ -35,7 +29,7 @@ export const UpgradeToast = () => {
             return;
         }
 
-        const currentVersion = getVersionFromString(versionString);
+        const currentVersion = parseVersion(versionString);
         if (!currentVersion) {
             return;
         }
@@ -48,7 +42,7 @@ export const UpgradeToast = () => {
             .then((response) => response.json())
             .then((data: { name: string }[]) => {
                 const versions = data
-                    .map(({ name }) => getVersionFromString(name))
+                    .map(({ name }) => parseVersion(name))
                     .filter((version) => version !== null)
                     .sort((a, b) => compareVersions(a, b))
                     .reverse();
@@ -64,7 +58,7 @@ export const UpgradeToast = () => {
 
                 toast({
                     title: "New version available 📣 ",
-                    description: `Upgrade from ${getVersionString(currentVersion)} to ${getVersionString(latestVersion)}`,
+                    description: `Upgrade from ${formatVersion(currentVersion)} to ${formatVersion(latestVersion)}`,
                     duration: 10 * 1000,
                     action: (
                         <div className="flex flex-col gap-1">
@@ -87,28 +81,3 @@ export const UpgradeToast = () => {
     return null;
 }
 
-const getVersionFromString = (version: string): Version | null => {
-    const match = version.match(SEMVER_REGEX);
-    if (!match) {
-        return null;
-    }
-    return {
-        major: parseInt(match[1]),
-        minor: parseInt(match[2]),
-        patch: parseInt(match[3]),
-    } satisfies Version;
-}
-
-const getVersionString = (version: Version) => {
-    return `v${version.major}.${version.minor}.${version.patch}`;
-}
-
-const compareVersions = (a: Version, b: Version) => {
-    if (a.major !== b.major) {
-        return a.major - b.major;
-    }
-    if (a.minor !== b.minor) {
-        return a.minor - b.minor;
-    }
-    return a.patch - b.patch;
-}
diff --git a/packages/web/src/features/changelog/listEntriesApi.ts b/packages/web/src/features/changelog/listEntriesApi.ts
index 5a5dd8a31..09718f8b7 100644
--- a/packages/web/src/features/changelog/listEntriesApi.ts
+++ b/packages/web/src/features/changelog/listEntriesApi.ts
@@ -6,7 +6,8 @@ export type ChangelogEntryDto = {
     slug: string;
     title: string;
     publishedAt: string;
-    summary: string | null;
+    summary: string;
+    version: string;
     bodyMarkdown: string;
 };
 
@@ -32,6 +33,7 @@ export const listChangelogEntries = async () =>
                     title: entry.title,
                     publishedAt: entry.publishedAt.toISOString(),
                     summary: entry.summary,
+                    version: entry.version,
                     bodyMarkdown: entry.bodyMarkdown,
                 })),
                 entriesBaseUrl,
diff --git a/packages/web/src/features/changelog/pollChangelog.ts b/packages/web/src/features/changelog/pollChangelog.ts
index 5054935a9..dc6945cac 100644
--- a/packages/web/src/features/changelog/pollChangelog.ts
+++ b/packages/web/src/features/changelog/pollChangelog.ts
@@ -29,7 +29,8 @@ const upsertEntry = async (entry: ChangelogFeedIndexEntry, baseUrl: string): Pro
         slug: entry.slug,
         title: entry.title,
         publishedAt: new Date(entry.publishedAt),
-        summary: entry.summary ?? null,
+        summary: entry.summary,
+        version: entry.version,
         bodyMarkdown,
     };
 
diff --git a/packages/web/src/features/changelog/types.ts b/packages/web/src/features/changelog/types.ts
index d2168e23a..30d0c7db5 100644
--- a/packages/web/src/features/changelog/types.ts
+++ b/packages/web/src/features/changelog/types.ts
@@ -4,7 +4,8 @@ export const changelogFeedIndexEntrySchema = z.object({
     slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
     title: z.string().min(1),
     publishedAt: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
-    summary: z.string().min(1).optional(),
+    summary: z.string().min(1),
+    version: z.string().regex(/^v\d+\.\d+\.\d+$/),
     path: z.string().min(1),
 });
 

From 1b4802bf8b1a2779e48a3c544a6b16a22b7ead9d Mon Sep 17 00:00:00 2001
From: Brendan Kellam <brendan@sourcebot.dev>
Date: Mon, 25 May 2026 15:25:01 -0700
Subject: [PATCH 4/4] improve tooltip

---
 .../@sidebar/components/changelogEntryDialog.tsx   | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx b/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx
index 57eaca429..0497a25f6 100644
--- a/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx
+++ b/packages/web/src/app/(app)/@sidebar/components/changelogEntryDialog.tsx
@@ -3,7 +3,6 @@
 import { Badge } from "@/components/ui/badge";
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
-import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 import type { ChangelogEntryDto } from "@/features/changelog/listEntriesApi";
 import { cn } from "@/lib/utils";
 import { format } from "date-fns";
@@ -150,11 +149,14 @@ export function ChangelogEntryDialog({ entry, entriesBaseUrl, open, onOpenChange
                                                     </Badge>
                                                 </a>
                                             </TooltipTrigger>
-                                            <TooltipPrimitive.Portal>
-                                                <TooltipContent side="bottom">
-                                                    This update requires <span className="font-mono">{entry.version}</span>. Your instance is on <span className="font-mono">{SOURCEBOT_VERSION}</span>.
-                                                </TooltipContent>
-                                            </TooltipPrimitive.Portal>
+                                            <TooltipContent side="bottom">
+                                                <div className="grid grid-cols-[auto_auto] gap-x-3 gap-y-1 text-sm items-center">
+                                                    <span className="text-muted-foreground">Current version</span>
+                                                    <span className="font-mono text-[11px] bg-muted rounded px-1.5 py-0.5 justify-self-start">{SOURCEBOT_VERSION}</span>
+                                                    <span className="text-muted-foreground">Required version</span>
+                                                    <span className="font-mono text-[11px] bg-muted rounded px-1.5 py-0.5 justify-self-start">{entry.version}</span>
+                                                </div>
+                                            </TooltipContent>
                                         </Tooltip>
                                     </>
                                 )}