From 3d18139fd34db0084608dfad094bc457dc020bc1 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Tue, 12 May 2026 20:26:44 +0200
Subject: [PATCH 1/2] feat(releases): add changelog and release feeds

---
 .github/workflows/publish.yml                |  57 +--
 CHANGELOG.md                                 | 222 ++++++++++-
 apps/registry/app/atom.xml/route.ts          |  66 ++++
 apps/registry/app/changelog/page.tsx         | 235 ++++++++++++
 apps/registry/app/docs/changelog/page.tsx    |   5 +
 apps/registry/app/layout.tsx                 |  12 +
 apps/registry/app/llms-full.txt/route.ts     | 195 ++++++----
 apps/registry/app/llms.txt/route.ts          | 182 +++++----
 apps/registry/app/releases/page.tsx          | 213 +++++++++++
 apps/registry/app/rss.xml/route.ts           |  68 ++++
 apps/registry/app/sitemap.ts                 | 113 +++---
 apps/registry/components/footer/footer.tsx   |  15 +-
 apps/registry/components/header/header.tsx   |  34 +-
 apps/registry/components/landing/landing.tsx |  86 ++++-
 apps/registry/lib/changelog.ts               | 378 +++++++++++++++++++
 cliff.toml                                   |  45 +++
 docs/RELEASING.md                            |   6 +-
 packages/ui/CHANGELOG.md                     |   1 +
 18 files changed, 1666 insertions(+), 267 deletions(-)
 create mode 100644 apps/registry/app/atom.xml/route.ts
 create mode 100644 apps/registry/app/changelog/page.tsx
 create mode 100644 apps/registry/app/docs/changelog/page.tsx
 create mode 100644 apps/registry/app/releases/page.tsx
 create mode 100644 apps/registry/app/rss.xml/route.ts
 create mode 100644 apps/registry/lib/changelog.ts
 create mode 100644 cliff.toml

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 913ef548..c37dcdb5 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -5,6 +5,8 @@ on:
     branches: [main]
     paths:
       - "packages/ui/**"
+      - "CHANGELOG.md"
+      - "cliff.toml"
       - "pnpm-lock.yaml"
       - ".github/workflows/publish.yml"
   workflow_dispatch: {}
@@ -118,43 +120,42 @@ jobs:
             exit 1
           fi
 
-      - name: Generate changelog
+      - name: Read changelog release notes
         id: changelog
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
         run: |
-          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-          if [ -z "$LAST_TAG" ]; then
-            RANGE="HEAD"
-          else
-            RANGE="${LAST_TAG}..HEAD"
+          awk -v version="$VERSION" '
+            /^## / {
+              if (capture) exit
+              if ($0 ~ "^## \\[?" version "\\]?") {
+                capture = 1
+                next
+              }
+            }
+            capture { print }
+          ' CHANGELOG.md > /tmp/release-notes.md
+
+          if [ ! -s /tmp/release-notes.md ]; then
+            echo "::error::CHANGELOG.md must include a ${VERSION} release section before dispatch."
+            exit 1
           fi
 
           {
             echo "body<<CHANGELOG_EOF"
-
-            FEATS=$(git log "$RANGE" --pretty=format:"%s" --grep="^feat" 2>/dev/null || true)
-            if [ -n "$FEATS" ]; then
-              echo "### Features"
-              echo "$FEATS" | sed 's/^/- /'
-              echo ""
-            fi
-
-            FIXES=$(git log "$RANGE" --pretty=format:"%s" --grep="^fix" 2>/dev/null || true)
-            if [ -n "$FIXES" ]; then
-              echo "### Bug Fixes"
-              echo "$FIXES" | sed 's/^/- /'
-              echo ""
-            fi
-
-            OTHERS=$(git log "$RANGE" --pretty=format:"%s" --invert-grep --grep="^feat" --grep="^fix" 2>/dev/null || true)
-            if [ -n "$OTHERS" ]; then
-              echo "### Other Changes"
-              echo "$OTHERS" | sed 's/^/- /'
-              echo ""
-            fi
-
+            cat /tmp/release-notes.md
             echo "CHANGELOG_EOF"
           } >> "$GITHUB_OUTPUT"
 
+      - name: Confirm changelog entry exists
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          if ! grep -Eq "^## \\[?${VERSION}\\]?|^## \\[?v${VERSION}\\]?" CHANGELOG.md packages/ui/CHANGELOG.md; then
+            echo "::error::CHANGELOG.md or packages/ui/CHANGELOG.md must include a ${VERSION} release section before dispatch."
+            exit 1
+          fi
+
       - name: Tag release
         run: |
           git config user.name "github-actions[bot]"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 315cc69d..d8a35fa6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,32 +1,214 @@
 # Changelog
 
-The canonical changelog for the published `@vllnt/ui` package lives at [`packages/ui/CHANGELOG.md`](./packages/ui/CHANGELOG.md). It follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+All notable changes to `@vllnt/ui` and the public registry site are documented
+in this file.
 
-This root file is a **pointer** — it tracks repo-wide events that don't ship in a published package (CI workflows, registry build pipeline, ROADMAP changes, agent-surface routes like `/llms.txt`, `/r/<name>.json` schema additions).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Release automation can regenerate this file from Conventional Commits with
+`git-cliff`.
 
-## Where to look
+## [Unreleased]
 
-| Looking for… | File / source |
-|---|---|
-| Published package changes (`@vllnt/ui`) | [`packages/ui/CHANGELOG.md`](./packages/ui/CHANGELOG.md) |
-| Roadmap toward the next release | [`ROADMAP.md`](./ROADMAP.md) |
-| Per-release notes | [GitHub Releases](https://github.com/vllnt/ui/releases) |
-| Live registry index | [`/r/registry.json`](https://ui.vllnt.ai/r/registry.json) (carries `version` + `generatedAt`) |
-| Per-component descriptors | [`/r/<name>.json`](https://ui.vllnt.ai/r/registry.json) (each carries `version` + `stability`) |
+> Target version: **`0.3.0`** - canary only; not yet published. See
+> [ROADMAP.md](./ROADMAP.md) for shipping criteria.
 
-## [Unreleased] — repo-wide
+### Added
 
-> Target version: `0.3.0`. Tracks ROADMAP.md, see [#252](https://github.com/vllnt/ui/issues/252).
+- **Release intelligence surface** - `/changelog`, `/releases`, `/rss.xml`, and
+  `/atom.xml` expose one changelog source through HTML, GitHub release cards, and
+  feed readers. `/docs/changelog` redirects to `/changelog`.
+- **Agent-first surface** - `/robots.txt` allowing 11 AI crawlers,
+  `/sitemap.xml`, `/llms.txt`, `/llms-full.txt`, JSON-LD on every page, PWA
+  manifest, breadcrumbs, custom 404, canonical URLs per route, expanded root
+  metadata (keywords, robots tuning, OG/Twitter site-level config).
+- **Codebase health gate** - `react-doctor` CI workflow with PR annotations and
+  score artifact, `pnpm doctor*` script suite, type-enforcement workflow on every
+  issue.
+- **Registry-item richness** - every `/r/<name>.json` now carries `version`,
+  `stability`, optional `a11y` schema, optional inline `examples`. Top-level
+  `/r/registry.json` carries `version` and `generatedAt`.
+- **Site UX** - Header GitHub link, `/request-component` and `/report` pages with
+  prefilled-GitHub-issue forms, per-component "Report a bug" button.
+- **Brand** - `DESIGN.md` at repo root with the canonical brand and design
+  guideline (color tokens, typography, motion, anti-patterns).
+- **Hooks + utility primitives** - `CopyButton` with `useCopyToClipboard`,
+  `Banner` with `BannerAction`, `Kbd`, `EmptyState`, `DocumentSiblingNav`.
+- **Pricing + identity cards** - `PricingTable`, `PricingPlan`,
+  `HistoricalFigureCard`, `CivilizationCard`, and `CivilizationComparison`.
+- **Newsletter** - `NewsletterSignup` with a state-machine driven submit flow.
+- **AI compound families** - `ModelComparison`, `PromptTemplates`,
+  `AgentActivity`, `AISidebar`, and `AIArtifact`.
+- **Era / financial** - `EraComparison` and `TransactionList`.
+- **Forms** - `Form`, `MultiSelect`, `SegmentedControl`, `TagsInput`, and
+  `AutoReload`.
+- **Educational** - `KnowledgeCheck` inline question runner.
+- **Charts + timelines** - `GanttChart`, `ParallelTimeline`, `Timeline`,
+  `TimelineItem`, `HistoricTimeline`, `InteractiveTimeline`,
+  `ChronologicalTimeline`, and `TreeView`.
+- **Document + reading** - `PrimarySourceViewer` compound family.
+- **Maps + geography** - `Map2D`, `ChoroplethMap`, `RouteMap`, `HeatMapOverlay`,
+  `GeographyQuizMap`, `MapTimeline`, `StoryMap`, and `Globe3D`.
+- **Canvas foundation** - `CanvasShell`, `CanvasView`, `InfinitePlane`,
+  `ViewportBookmarks`, `WorldBreadcrumbs`, `TopBar`, `LeftRail`, `RightDock`,
+  `ZoomHud`, `MiniMapPanel`, and `WorkspaceSwitcher`.
+- **Canvas selection + manipulation** - `SelectionHalo`, `SnapGuides`,
+  `FloatingToolbar`, `MultiSelectLasso`, `FollowMode`, and `HandoffBeacon`.
+- **Canvas spatial objects** - `ObjectCard`, `ObjectHandle`, `AnchorPort`,
+  `ConnectorEdge`, `EdgeLabel`, and `GroupHull`.
+- **Canvas collaboration primitives** - `LiveCursor`, `CommentPin`,
+  `PresenceSyncIndicator`, `PresenceStack`, `SelectionPresence`, and
+  `ThreadBubble`.
+- **Inspector + dock panels** - `PropertySection`, `ObjectInspector`,
+  `RelationshipInspector`, `RuntimeOverviewPanel`, `RoutingAssignmentPanel`, and
+  `PolicyDeliveryPanel`.
+- **Runtime overlays** - `AlertPulse`, `ThresholdRing`, `StickyMetric`,
+  `HeatOverlay`, `StateBadgeOverlay`, `MetricCluster`, `JarvisDock`, and
+  `ContextLens`.
+- **Time navigation** - `TimelineScrubber`, `PlaybackGhost`,
+  `BottomActivityStrip`, and `RunTimeline`.
+- Total component count: **225** (up from 140).
 
-### Added
+### Changed
 
-- **Agent-first surface** — `/robots.txt` allowing 11 AI crawlers, `/sitemap.xml`, `/llms.txt`, `/llms-full.txt`, JSON-LD on every page, PWA manifest, breadcrumbs, custom 404, canonical URLs per route, expanded root metadata (keywords, robots tuning, OG/Twitter site-level config).
-- **Codebase health gate** — `react-doctor` CI workflow with PR annotations + score artifact, `pnpm doctor*` script suite, type-enforcement workflow on every issue.
-- **Registry-item richness** — every `/r/<name>.json` now carries `version`, `stability`, optional `a11y` schema, optional inline `examples`. Top-level `/r/registry.json` carries `version` + `generatedAt`.
-- **Site UX** — Header GitHub icon, `/request-component` and `/report` pages with prefilled-GitHub-issue forms, per-component "Report a bug" button.
-- **Brand** — `DESIGN.md` at repo root with the canonical brand + design guideline (color tokens, typography, motion, anti-patterns).
+- Registry installs use a **hybrid CLI strategy** - leaf component source is
+  inlined, sibling registry items resolve via `@vllnt/ui` to keep installs
+  minimal and dedupe shared primitives.
 
 ### Notes
 
-- Site routes `/changelog`, `/releases`, and `/rss.xml` ship in a follow-up — this PR scopes #260 to the root pointer file.
-- Once `0.3.0` is cut, the `Unreleased` heading flips to `0.3.0` and this section moves into [`packages/ui/CHANGELOG.md`](./packages/ui/CHANGELOG.md).
+- `ROADMAP.md` tracks the open work gating the `0.3.0` cut.
+- `0.3.0` requires the codebase-health gate (`react-doctor` CI + 0 errors), the
+  agent-first surface (`/llms.txt`, `/mcp`, sitemap, JSON-LD), and the rebuilt
+  landing page before shipping.
+
+## [0.2.1] - 2026-04-21
+
+### Fixed
+
+- **Public API:** `ProgressCard` now re-exported from `@vllnt/ui` - it shipped
+  in `0.2.0`'s tarball but was missing from the barrel, so
+  `import { ProgressCard } from "@vllnt/ui"` resolved to `undefined`.
+
+### Docs
+
+- Correct casing for the AI family (`AIChatInput`, `AIMessageBubble`,
+  `AISourceCitation`, `AIStreamingText`, `AIToolCallDisplay`) and `SocialFAB`
+  across README, package README, CHANGELOG, and `llms-full.txt`.
+
+## [0.2.0] - 2026-04-21
+
+### Added
+
+- **AI family** - `AIChatInput`, `AIMessageBubble`, `AISourceCitation`,
+  `AIStreamingText`, `AIToolCallDisplay`, `ThinkingBlock`, `ModelSelector`.
+- **Financial family** - `CandlestickChart`, `MarketTreemap`, `OrderBook`,
+  `TickerTape`, `SparklineGrid`, `WalletCard`, `Watchlist`.
+- **Ops / Status family** - `StatusBoard`, `StatusIndicator`, `LiveFeed`,
+  `WorldClockBar`, `SeverityBadge`, `RoleBadge`, `ScopeSelector`.
+- **Billing & Plans family** - `SubscriptionCard`, `PlanBadge`, `CreditBadge`,
+  `UsageBreakdown`.
+- **Animation family** - `AnimatedText`, `BorderBeam`, `Marquee`,
+  `NumberTicker`, and a standalone spinner library exported via `Spinner`.
+- **Educational family** - `Flashcard`, `Stepper`, `Tour`, `Annotation`,
+  `CompletionDialog`, `TruncatedText`, `TableOfContentsPanel`.
+- **Form additions** - `DatePicker`, `FileUpload`, `NumberInput`,
+  `PasswordInput`, `InlineInput`, `Combobox`, `Rating`.
+- **Data / metric additions** - `DataTable`, `DataList`, `StatCard`,
+  `MetricGauge`, `ActivityHeatmap`, `ActivityLog`.
+- **App shell additions** - `CategoryFilter`, `FilterBar`, `CookieConsent`,
+  `Slideshow`, `CountdownTimer`, `AvatarGroup`, `FloatingActionButton`,
+  `SocialFab`, `KeyboardShortcutsHelp`, `ShareDialog`, `HorizontalScrollRow`,
+  `ViewSwitcher`.
+- Total component count: **144** (up from 93).
+- Full Storybook integration with E2E smoke tests in CI.
+- OG image generation for every registry page.
+- Signed provenance attestations on every published artifact (sigstore).
+
+### Changed
+
+- Documentation domain moved to `ui.vllnt.ai` / `storybook.vllnt.ai`.
+- Default package registry is the public npm registry (no longer GitHub
+  Packages).
+- README component tables expanded to cover all 144 components organized by
+  family.
+
+### Fixed
+
+- Publish workflow now uses `npx --yes npm@latest publish` so OIDC trusted
+  publishing survives GitHub runners that ship pre-11.5.1 npm.
+
+## [0.1.11] - 2026-04
+
+### Fixed
+
+- Re-extract tarball path from `pnpm pack` output for publish step.
+
+## [0.1.10]
+
+### Changed
+
+- Switched to `pnpm pack` and `npm publish` flow to support `publishConfig` with
+  OIDC auth.
+
+## [0.1.9]
+
+### Fixed
+
+- Use `pnpm publish` and repair release creation step in CI.
+
+## [0.1.8]
+
+### Fixed
+
+- Annotated tags and `--notes-file` for release creation.
+
+## [0.1.7]
+
+### Added
+
+- `HorizontalScrollRow`, `ViewSwitcher`, and `useHorizontalScroll` hook.
+
+### Fixed
+
+- `Comparison`: defensive prop validation to prevent runtime crash on malformed
+  input.
+
+## [0.1.6]
+
+### Fixed
+
+- Bundle-free build to preserve per-file `"use client"` directives in published
+  chunks.
+
+## [0.1.5]
+
+### Fixed
+
+- Add `"use client"` to all dist JS including `index.js`.
+
+## [0.1.4]
+
+### Fixed
+
+- Exclude `index.js` from `"use client"` banner.
+
+## [0.1.3]
+
+### Fixed
+
+- Add `"use client"` directive to published dist chunks.
+
+## [0.1.2]
+
+### Added
+
+- Initial public publish to the public npm registry.
+
+[0.2.1]: https://github.com/vllnt/ui/releases/tag/v0.2.1
+[0.2.0]: https://github.com/vllnt/ui/releases/tag/v0.2.0
+[0.1.11]: https://github.com/vllnt/ui/releases/tag/v0.1.11
+[0.1.10]: https://github.com/vllnt/ui/releases/tag/v0.1.10
+[0.1.9]: https://github.com/vllnt/ui/releases/tag/v0.1.9
+[0.1.8]: https://github.com/vllnt/ui/releases/tag/v0.1.8
+[0.1.2]: https://github.com/vllnt/ui/releases/tag/v0.1.2
diff --git a/apps/registry/app/atom.xml/route.ts b/apps/registry/app/atom.xml/route.ts
new file mode 100644
index 00000000..e55cd706
--- /dev/null
+++ b/apps/registry/app/atom.xml/route.ts
@@ -0,0 +1,66 @@
+import {
+  feedUpdatedAt,
+  getReleaseRecords,
+  releasePageUrl,
+} from "@/lib/changelog";
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+const ATOM_HEADERS = new Headers([
+  [
+    "Cache-Control",
+    "public, max-age=0, s-maxage=3600, stale-while-revalidate=86400",
+  ],
+  ["Content-Type", "application/atom+xml; charset=utf-8"],
+]);
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function buildAtomDate(value?: string): string {
+  return new Date(value ?? Date.now()).toISOString();
+}
+
+async function buildAtomXml(): Promise<string> {
+  const releases = await getReleaseRecords();
+  const entries = releases
+    .map((release) => {
+      const link = releasePageUrl(release);
+      return [
+        "  <entry>",
+        `    <title>${escapeXml(release.title)}</title>`,
+        `    <id>${escapeXml(link)}</id>`,
+        `    <link href="${escapeXml(link)}" />`,
+        `    <updated>${escapeXml(buildAtomDate(release.date))}</updated>`,
+        `    <summary>${escapeXml(release.summary)}</summary>`,
+        "  </entry>",
+      ].join("\n");
+    })
+    .join("\n");
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<feed xmlns="http://www.w3.org/2005/Atom">',
+    "  <title>VLLNT UI Releases</title>",
+    `  <id>${SITE_URL}/releases</id>`,
+    `  <link href="${SITE_URL}/releases" />`,
+    `  <link rel="self" href="${SITE_URL}/atom.xml" />`,
+    `  <updated>${escapeXml(feedUpdatedAt(releases))}</updated>`,
+    entries,
+    "</feed>",
+  ].join("\n");
+}
+
+export const revalidate = 3600;
+
+async function getAtomXml(): Promise<Response> {
+  const body = await buildAtomXml();
+  return new Response(body, { headers: ATOM_HEADERS });
+}
+
+export { getAtomXml as GET };
diff --git a/apps/registry/app/changelog/page.tsx b/apps/registry/app/changelog/page.tsx
new file mode 100644
index 00000000..d79f9a34
--- /dev/null
+++ b/apps/registry/app/changelog/page.tsx
@@ -0,0 +1,235 @@
+import { Badge, Breadcrumb, Button, MDXContent, Sidebar } from "@vllnt/ui";
+import type { Metadata } from "next";
+import Link from "next/link";
+
+import { type ChangelogTypeFilter, getChangelogEntries } from "@/lib/changelog";
+import { breadcrumbLd, jsonLdScript } from "@/lib/jsonld";
+import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
+import { canonical } from "@/lib/seo";
+import { getSidebarSections } from "@/lib/sidebar-sections";
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+
+type SearchParameters = {
+  readonly from?: string;
+  readonly to?: string;
+  readonly type?: string;
+};
+
+const CHANGELOG_TYPES: readonly {
+  readonly label: string;
+  readonly value: ChangelogTypeFilter;
+}[] = [
+  { label: "All changes", value: "all" },
+  { label: "Features", value: "feat" },
+  { label: "Fixes", value: "fix" },
+  { label: "Breaking", value: "breaking" },
+];
+
+const DESCRIPTION =
+  "Browse VLLNT UI release notes from the canonical Keep a Changelog source, with filters for features, fixes, breaking changes, and release date.";
+
+export const metadata: Metadata = {
+  alternates: { canonical: canonical("/changelog") },
+  description: DESCRIPTION,
+  openGraph: generateOGMetadata({
+    description: DESCRIPTION,
+    title: "Changelog · VLLNT UI",
+    type: "docs",
+  }),
+  title: "Changelog · VLLNT UI",
+  twitter: generateTwitterMetadata({
+    description: DESCRIPTION,
+    title: "Changelog · VLLNT UI",
+    type: "docs",
+  }),
+};
+
+function normalizeType(value?: string): ChangelogTypeFilter {
+  if (value === "breaking" || value === "feat" || value === "fix") {
+    return value;
+  }
+  return "all";
+}
+
+function FilterControls({
+  from,
+  to,
+  type,
+}: {
+  readonly from?: string;
+  readonly to?: string;
+  readonly type: ChangelogTypeFilter;
+}) {
+  return (
+    <form
+      action="/changelog"
+      className="mt-8 grid gap-3 border border-border p-4 sm:grid-cols-[minmax(12rem,1fr)_minmax(10rem,0.7fr)_minmax(10rem,0.7fr)_auto]"
+    >
+      <div className="grid gap-2">
+        <label className="text-sm font-medium" htmlFor="changelog-type">
+          Type
+        </label>
+        <select
+          className="h-10 rounded-md border border-input bg-background px-3 text-sm font-normal"
+          defaultValue={type}
+          id="changelog-type"
+          name="type"
+        >
+          {CHANGELOG_TYPES.map((option) => (
+            <option key={option.value} value={option.value}>
+              {option.label}
+            </option>
+          ))}
+        </select>
+      </div>
+      <div className="grid gap-2">
+        <label className="text-sm font-medium" htmlFor="changelog-from">
+          From
+        </label>
+        <input
+          className="h-10 rounded-md border border-input bg-background px-3 text-sm font-normal"
+          defaultValue={from}
+          id="changelog-from"
+          name="from"
+          type="date"
+        />
+      </div>
+      <div className="grid gap-2">
+        <label className="text-sm font-medium" htmlFor="changelog-to">
+          To
+        </label>
+        <input
+          className="h-10 rounded-md border border-input bg-background px-3 text-sm font-normal"
+          defaultValue={to}
+          id="changelog-to"
+          name="to"
+          type="date"
+        />
+      </div>
+      <div className="flex items-end gap-2">
+        <Button className="w-full sm:w-auto" type="submit">
+          Apply
+        </Button>
+      </div>
+    </form>
+  );
+}
+
+export default async function ChangelogPage({
+  searchParams,
+}: {
+  readonly searchParams: Promise<SearchParameters>;
+}) {
+  const parameters = await searchParams;
+  const type = normalizeType(parameters.type);
+  const entries = await getChangelogEntries({
+    from: parameters.from,
+    to: parameters.to,
+    type,
+  });
+
+  return (
+    <>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: jsonLdScript([
+            breadcrumbLd([
+              { name: "Home", url: SITE_URL },
+              { name: "Changelog", url: `${SITE_URL}/changelog` },
+            ]),
+            {
+              "@context": "https://schema.org",
+              "@type": "Article",
+              dateModified: new Date().toISOString(),
+              description: DESCRIPTION,
+              headline: "VLLNT UI Changelog",
+              mainEntityOfPage: `${SITE_URL}/changelog`,
+              publisher: {
+                "@type": "Organization",
+                name: "VLLNT",
+              },
+            },
+          ]),
+        }}
+        type="application/ld+json"
+      />
+      <Sidebar sections={getSidebarSections()} />
+      <main className="flex-1 overflow-y-auto bg-background">
+        <div className="container mx-auto max-w-5xl px-4 py-16 lg:px-8">
+          <Breadcrumb
+            className="mb-4 text-muted-foreground"
+            items={[{ href: "/", label: "Home" }, { label: "Changelog" }]}
+          />
+          <div className="flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between">
+            <div>
+              <p className="text-sm font-medium uppercase tracking-wide text-muted-foreground">
+                Release history
+              </p>
+              <h1 className="mt-2 text-4xl font-semibold">Changelog</h1>
+              <p className="mt-4 max-w-2xl text-lg text-muted-foreground">
+                The canonical release log for VLLNT UI, generated from
+                Conventional Commits into Keep a Changelog format.
+              </p>
+            </div>
+            <Button asChild variant="outline">
+              <Link href="/rss.xml">RSS feed</Link>
+            </Button>
+          </div>
+
+          <FilterControls
+            from={parameters.from}
+            to={parameters.to}
+            type={type}
+          />
+
+          <div className="mt-10 space-y-10">
+            {entries.length > 0 ? (
+              entries.map((entry) => (
+                <article
+                  className="border-b border-border pb-10 last:border-b-0 last:pb-0"
+                  id={entry.anchor}
+                  key={entry.anchor}
+                >
+                  <div className="flex flex-wrap items-center gap-3">
+                    <h2 className="text-2xl font-semibold">{entry.title}</h2>
+                    {entry.date ? (
+                      <Badge variant="secondary">{entry.date}</Badge>
+                    ) : null}
+                    <Link
+                      aria-label={`Permalink to ${entry.title}`}
+                      className="text-sm text-muted-foreground hover:text-foreground"
+                      href={`/changelog#${entry.anchor}`}
+                    >
+                      #{entry.anchor}
+                    </Link>
+                  </div>
+                  <div className="mt-6 space-y-8">
+                    {entry.sections.map((section) => (
+                      <section key={`${entry.anchor}-${section.title}`}>
+                        <div className="mb-3 flex items-center gap-2">
+                          <h3 className="text-lg font-semibold">
+                            {section.title}
+                          </h3>
+                          <Badge variant="outline">{section.type}</Badge>
+                        </div>
+                        <MDXContent content={section.body} enableMDX={false} />
+                      </section>
+                    ))}
+                  </div>
+                </article>
+              ))
+            ) : (
+              <div className="border border-border p-8">
+                <h2 className="text-xl font-semibold">No changes found</h2>
+                <p className="mt-2 text-muted-foreground">
+                  Adjust the filters to include more release notes.
+                </p>
+              </div>
+            )}
+          </div>
+        </div>
+      </main>
+    </>
+  );
+}
diff --git a/apps/registry/app/docs/changelog/page.tsx b/apps/registry/app/docs/changelog/page.tsx
new file mode 100644
index 00000000..3c653d76
--- /dev/null
+++ b/apps/registry/app/docs/changelog/page.tsx
@@ -0,0 +1,5 @@
+import { permanentRedirect } from "next/navigation";
+
+export default function DocumentationChangelogRedirect() {
+  permanentRedirect("/changelog");
+}
diff --git a/apps/registry/app/layout.tsx b/apps/registry/app/layout.tsx
index 0153efe7..d06029d5 100644
--- a/apps/registry/app/layout.tsx
+++ b/apps/registry/app/layout.tsx
@@ -82,6 +82,18 @@ export default function RootLayout({
   return (
     <html lang="en" suppressHydrationWarning>
       <head>
+        <link
+          href="/rss.xml"
+          rel="alternate"
+          title="VLLNT UI releases"
+          type="application/rss+xml"
+        />
+        <link
+          href="/atom.xml"
+          rel="alternate"
+          title="VLLNT UI releases"
+          type="application/atom+xml"
+        />
         <script
           dangerouslySetInnerHTML={{ __html: jsonLdScript(organizationLd()) }}
           type="application/ld+json"
diff --git a/apps/registry/app/llms-full.txt/route.ts b/apps/registry/app/llms-full.txt/route.ts
index c1c5fb42..a0c52310 100644
--- a/apps/registry/app/llms-full.txt/route.ts
+++ b/apps/registry/app/llms-full.txt/route.ts
@@ -1,26 +1,39 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 
+import { getLatestReleaseRecords } from "@/lib/changelog";
+
 import registry from "../../registry.json";
 
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+const TEXT_HEADERS = new Headers([
+  [
+    "Cache-Control",
+    "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
+  ],
+  ["Content-Type", "text/plain; charset=utf-8"],
+]);
 
 type RegistryItem = {
-  readonly name: string;
-  readonly title: string;
-  readonly description: string;
   readonly category: string;
   readonly dependencies?: readonly string[];
+  readonly description: string;
+  readonly name: string;
   readonly registryDependencies?: readonly string[];
+  readonly title: string;
 };
 
-const DOC_PAGES: ReadonlyArray<{ slug: string; title: string }> = [
+const DOC_PAGES: readonly { slug: string; title: string }[] = [
   { slug: "home", title: "Get Started" },
   { slug: "docs", title: "Documentation" },
   { slug: "philosophy", title: "Philosophy" },
   { slug: "components", title: "Components Overview" },
 ];
 
+function getRegistryItems(): readonly RegistryItem[] {
+  return (registry as { readonly items: readonly RegistryItem[] }).items;
+}
+
 function stripFrontmatter(source: string): string {
   if (!source.startsWith("---")) return source;
   const end = source.indexOf("\n---", 3);
@@ -28,13 +41,8 @@ function stripFrontmatter(source: string): string {
   return source.slice(end + 4).replace(/^\n+/, "");
 }
 
-async function readDocPage(slug: string): Promise<string> {
-  const file = path.join(
-    process.cwd(),
-    "content",
-    "pages",
-    `${slug}.mdx`,
-  );
+async function readDocumentPage(slug: string): Promise<string> {
+  const file = path.join(process.cwd(), "content", "pages", `${slug}.mdx`);
   try {
     const raw = await readFile(file, "utf8");
     return stripFrontmatter(raw).trim();
@@ -43,78 +51,119 @@ async function readDocPage(slug: string): Promise<string> {
   }
 }
 
-async function buildLlmsFullTxt(): Promise<string> {
-  const items = (registry as { readonly items: readonly RegistryItem[] }).items;
-
-  const lines: string[] = [];
-
-  lines.push("# VLLNT UI — Full Reference");
-  lines.push("");
-  lines.push(
+function buildIntroLines(items: readonly RegistryItem[]): readonly string[] {
+  return [
+    "# VLLNT UI - Full Reference",
+    "",
     "> One-fetch, complete agent context for the VLLNT UI registry. " +
       `${items.length} components, install via shadcn CLI against /r/<name>.json. ` +
       `Site: ${SITE_URL}`,
+    "",
+  ];
+}
+
+function buildInstallLines(): readonly string[] {
+  return [
+    "## Install",
+    "",
+    "```bash",
+    `pnpm dlx shadcn@latest add ${SITE_URL}/r/<name>.json`,
+    `# Or with npm: npx shadcn@latest add ${SITE_URL}/r/<name>.json`,
+    "```",
+    "",
+  ];
+}
+
+async function buildDocumentLines(): Promise<readonly string[]> {
+  const pageSections = await Promise.all(
+    DOC_PAGES.map(async (page) => {
+      const body = await readDocumentPage(page.slug);
+      if (!body) return [];
+      const source = `${SITE_URL}/${page.slug === "home" ? "" : page.slug}`;
+      return [`## ${page.title}`, "", `Source: ${source}`, "", body, ""];
+    }),
   );
-  lines.push("");
-
-  lines.push("## Install");
-  lines.push("");
-  lines.push("```bash");
-  lines.push(`pnpm dlx shadcn@latest add ${SITE_URL}/r/<name>.json`);
-  lines.push(`# Or with npm: npx shadcn@latest add ${SITE_URL}/r/<name>.json`);
-  lines.push("```");
-  lines.push("");
-
-  for (const page of DOC_PAGES) {
-    const body = await readDocPage(page.slug);
-    if (!body) continue;
-    lines.push(`## ${page.title}`);
-    lines.push("");
-    lines.push(`Source: ${SITE_URL}/${page.slug === "home" ? "" : page.slug}`);
-    lines.push("");
-    lines.push(body);
-    lines.push("");
-  }
 
-  lines.push("## Components");
-  lines.push("");
-  lines.push(
+  return pageSections.flat();
+}
+
+async function buildReleaseLines(): Promise<readonly string[]> {
+  const releases = await getLatestReleaseRecords(5);
+  if (releases.length === 0) return [];
+
+  return [
+    "## Latest Release Notes",
+    "",
+    `Full release cards are available at ${SITE_URL}/releases and feeds at ${SITE_URL}/rss.xml or ${SITE_URL}/atom.xml.`,
+    "",
+    ...releases.flatMap((release) => [
+      `### ${release.title}`,
+      "",
+      `- Version: \`${release.version}\``,
+      `- Page: ${SITE_URL}/releases#${release.anchor}`,
+      `- GitHub: ${release.url}`,
+      ...(release.date ? [`- Date: ${release.date}`] : []),
+      "",
+      release.notes,
+      "",
+    ]),
+  ];
+}
+
+function buildComponentLines(item: RegistryItem): readonly string[] {
+  return [
+    `### ${item.title}`,
+    "",
+    `- Slug: \`${item.name}\``,
+    `- Category: \`${item.category}\``,
+    `- Description: ${item.description}`,
+    `- Page: ${SITE_URL}/components/${item.name}`,
+    `- Schema: ${SITE_URL}/r/${item.name}.json`,
+    ...(item.dependencies?.length
+      ? [`- npm deps: ${item.dependencies.join(", ")}`]
+      : []),
+    ...(item.registryDependencies?.length
+      ? [`- registry deps: ${item.registryDependencies.join(", ")}`]
+      : []),
+    `- Install: \`pnpm dlx shadcn@latest add ${SITE_URL}/r/${item.name}.json\``,
+    "",
+  ];
+}
+
+function buildComponentsReferenceLines(
+  items: readonly RegistryItem[],
+): readonly string[] {
+  return [
+    "## Components",
+    "",
     `${items.length} components total. Each entry links to a machine-readable JSON descriptor at /r/<name>.json.`,
-  );
-  lines.push("");
-
-  for (const item of [...items].sort((a, b) => a.name.localeCompare(b.name))) {
-    lines.push(`### ${item.title}`);
-    lines.push("");
-    lines.push(`- Slug: \`${item.name}\``);
-    lines.push(`- Category: \`${item.category}\``);
-    lines.push(`- Description: ${item.description}`);
-    lines.push(`- Page: ${SITE_URL}/components/${item.name}`);
-    lines.push(`- Schema: ${SITE_URL}/r/${item.name}.json`);
-    if (item.dependencies && item.dependencies.length > 0) {
-      lines.push(`- npm deps: ${item.dependencies.join(", ")}`);
-    }
-    if (item.registryDependencies && item.registryDependencies.length > 0) {
-      lines.push(`- registry deps: ${item.registryDependencies.join(", ")}`);
-    }
-    lines.push(
-      `- Install: \`pnpm dlx shadcn@latest add ${SITE_URL}/r/${item.name}.json\``,
-    );
-    lines.push("");
-  }
+    "",
+    ...[...items]
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .flatMap(buildComponentLines),
+  ];
+}
 
-  return lines.join("\n");
+async function buildLlmsFullTxt(): Promise<string> {
+  const items = getRegistryItems();
+  const documentLines = await buildDocumentLines();
+  const releaseLines = await buildReleaseLines();
+
+  return [
+    ...buildIntroLines(items),
+    ...buildInstallLines(),
+    ...documentLines,
+    ...releaseLines,
+    ...buildComponentsReferenceLines(items),
+  ].join("\n");
 }
 
 export const dynamic = "force-static";
-export const revalidate = 86400;
+export const revalidate = 86_400;
 
-export async function GET(): Promise<Response> {
+async function getLlmsFullTxt(): Promise<Response> {
   const body = await buildLlmsFullTxt();
-  return new Response(body, {
-    headers: {
-      "Content-Type": "text/plain; charset=utf-8",
-      "Cache-Control": "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
-    },
-  });
+  return new Response(body, { headers: TEXT_HEADERS });
 }
+
+export { getLlmsFullTxt as GET };
diff --git a/apps/registry/app/llms.txt/route.ts b/apps/registry/app/llms.txt/route.ts
index 32130fb2..1f8005dc 100644
--- a/apps/registry/app/llms.txt/route.ts
+++ b/apps/registry/app/llms.txt/route.ts
@@ -1,12 +1,19 @@
 import registry from "../../registry.json";
 
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+const TEXT_HEADERS = new Headers([
+  [
+    "Cache-Control",
+    "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
+  ],
+  ["Content-Type", "text/plain; charset=utf-8"],
+]);
 
 type RegistryItem = {
+  readonly category: string;
+  readonly description: string;
   readonly name: string;
   readonly title: string;
-  readonly description: string;
-  readonly category: string;
 };
 
 const CATEGORY_ORDER: readonly string[] = [
@@ -24,103 +31,126 @@ const CATEGORY_ORDER: readonly string[] = [
   "utility",
 ];
 
-const CATEGORY_LABEL: Record<string, string> = {
-  ai: "AI",
-  billing: "Billing & Plans",
-  content: "Content",
-  core: "Core primitives",
-  data: "Data",
-  "data-display": "Data display",
-  educational: "Educational",
-  form: "Form",
-  learning: "Learning",
-  navigation: "Navigation",
-  overlay: "Overlay",
-  utility: "Utility",
-};
+const CATEGORY_LABEL = new Map<string, string>([
+  ["ai", "AI"],
+  ["billing", "Billing & Plans"],
+  ["content", "Content"],
+  ["core", "Core primitives"],
+  ["data", "Data"],
+  ["data-display", "Data display"],
+  ["educational", "Educational"],
+  ["form", "Form"],
+  ["learning", "Learning"],
+  ["navigation", "Navigation"],
+  ["overlay", "Overlay"],
+  ["utility", "Utility"],
+]);
 
-function buildLlmsTxt(): string {
-  const items = (registry as { readonly items: readonly RegistryItem[] }).items;
+function getRegistryItems(): readonly RegistryItem[] {
+  return (registry as { readonly items: readonly RegistryItem[] }).items;
+}
 
-  const grouped = new Map<string, RegistryItem[]>();
-  for (const item of items) {
-    const bucket = grouped.get(item.category) ?? [];
-    bucket.push(item);
-    grouped.set(item.category, bucket);
-  }
+function groupItems(
+  items: readonly RegistryItem[],
+): ReadonlyMap<string, readonly RegistryItem[]> {
+  return items.reduce((groups, item) => {
+    const bucket = groups.get(item.category) ?? [];
+    groups.set(item.category, [...bucket, item]);
+    return groups;
+  }, new Map<string, readonly RegistryItem[]>());
+}
 
-  const sortedCategories = [
-    ...CATEGORY_ORDER.filter((c) => grouped.has(c)),
+function getSortedCategories(
+  grouped: ReadonlyMap<string, readonly RegistryItem[]>,
+): readonly string[] {
+  return [
+    ...CATEGORY_ORDER.filter((category) => grouped.has(category)),
     ...[...grouped.keys()]
-      .filter((c) => !CATEGORY_ORDER.includes(c))
+      .filter((category) => !CATEGORY_ORDER.includes(category))
       .sort(),
   ];
+}
 
-  const lines: string[] = [];
-
-  lines.push("# VLLNT UI");
-  lines.push("");
-  lines.push(
+function buildIntroLines(items: readonly RegistryItem[]): readonly string[] {
+  return [
+    "# VLLNT UI",
+    "",
     "> Agent-first React component registry. " +
       `${items.length} accessible components built on Radix UI, Tailwind CSS, and CVA. ` +
       "Install via the shadcn CLI against any /r/<name>.json endpoint.",
-  );
-  lines.push("");
+    "",
+  ];
+}
 
-  lines.push("## Docs");
-  lines.push("");
-  lines.push(`- [Get Started](${SITE_URL}/): install and use any component`);
-  lines.push(
+function buildDocumentationLines(): readonly string[] {
+  return [
+    "## Docs",
+    "",
+    `- [Get Started](${SITE_URL}/): install and use any component`,
     `- [Documentation](${SITE_URL}/docs): theming, registry usage, conventions`,
-  );
-  lines.push(
     `- [Philosophy](${SITE_URL}/philosophy): design principles and component patterns`,
-  );
-  lines.push(
     `- [Components index](${SITE_URL}/components): browse all components by category`,
-  );
-  lines.push("");
+    `- [Changelog](${SITE_URL}/changelog): canonical Keep a Changelog release history`,
+    `- [Releases](${SITE_URL}/releases): versioned release cards, GitHub notes, and RSS links`,
+    `- [RSS feed](${SITE_URL}/rss.xml): release feed for notification and agent polling`,
+    "",
+  ];
+}
 
-  lines.push("## Registry API");
-  lines.push("");
-  lines.push(
+function buildRegistryLines(): readonly string[] {
+  return [
+    "## Registry API",
+    "",
     `- [Registry index](${SITE_URL}/r/registry.json): full machine-readable list of all components`,
-  );
-  lines.push(
     `- [Sitemap](${SITE_URL}/sitemap.xml): every public route, refreshed per deploy`,
-  );
-  lines.push(
     "- Install command: `pnpm dlx shadcn@latest add " +
       `${SITE_URL}/r/<name>.json` +
       "`",
-  );
-  lines.push("");
-
-  for (const category of sortedCategories) {
-    const bucket = grouped.get(category);
-    if (!bucket || bucket.length === 0) continue;
-    const label = CATEGORY_LABEL[category] ?? category;
-    lines.push(`## Components — ${label}`);
-    lines.push("");
-    for (const item of [...bucket].sort((a, b) => a.name.localeCompare(b.name))) {
-      lines.push(
+    "",
+  ];
+}
+
+function buildCategoryLines(
+  category: string,
+  grouped: ReadonlyMap<string, readonly RegistryItem[]>,
+): readonly string[] {
+  const bucket = grouped.get(category);
+  if (!bucket || bucket.length === 0) return [];
+  const label = CATEGORY_LABEL.get(category) ?? category;
+  const itemLines = [...bucket]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(
+      (item) =>
         `- [${item.title}](${SITE_URL}/components/${item.name}): ${item.description}`,
-      );
-    }
-    lines.push("");
-  }
+    );
 
-  return lines.join("\n");
+  return [`## Components - ${label}`, "", ...itemLines, ""];
+}
+
+function buildComponentLines(
+  items: readonly RegistryItem[],
+): readonly string[] {
+  const grouped = groupItems(items);
+  return getSortedCategories(grouped).flatMap((category) =>
+    buildCategoryLines(category, grouped),
+  );
+}
+
+function buildLlmsTxt(): string {
+  const items = getRegistryItems();
+  return [
+    ...buildIntroLines(items),
+    ...buildDocumentationLines(),
+    ...buildRegistryLines(),
+    ...buildComponentLines(items),
+  ].join("\n");
 }
 
 export const dynamic = "force-static";
-export const revalidate = 86400;
-
-export function GET(): Response {
-  return new Response(buildLlmsTxt(), {
-    headers: {
-      "Content-Type": "text/plain; charset=utf-8",
-      "Cache-Control": "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
-    },
-  });
+export const revalidate = 86_400;
+
+function getLlmsTxt(): Response {
+  return new Response(buildLlmsTxt(), { headers: TEXT_HEADERS });
 }
+
+export { getLlmsTxt as GET };
diff --git a/apps/registry/app/releases/page.tsx b/apps/registry/app/releases/page.tsx
new file mode 100644
index 00000000..f1157c31
--- /dev/null
+++ b/apps/registry/app/releases/page.tsx
@@ -0,0 +1,213 @@
+import { Badge, Breadcrumb, Button, MDXContent, Sidebar } from "@vllnt/ui";
+import type { Metadata } from "next";
+import Link from "next/link";
+
+import { getReleaseRecords } from "@/lib/changelog";
+import { breadcrumbLd, jsonLdScript } from "@/lib/jsonld";
+import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
+import { canonical } from "@/lib/seo";
+import { getSidebarSections } from "@/lib/sidebar-sections";
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+
+const DESCRIPTION =
+  "Read VLLNT UI releases, including latest notes, component count deltas, breaking change counts, migration links, and GitHub release links.";
+
+export const metadata: Metadata = {
+  alternates: { canonical: canonical("/releases") },
+  description: DESCRIPTION,
+  openGraph: generateOGMetadata({
+    description: DESCRIPTION,
+    title: "Releases · VLLNT UI",
+    type: "docs",
+  }),
+  title: "Releases · VLLNT UI",
+  twitter: generateTwitterMetadata({
+    description: DESCRIPTION,
+    title: "Releases · VLLNT UI",
+    type: "docs",
+  }),
+};
+
+function formatComponentDelta(value?: number): string {
+  if (value === undefined) {
+    return "Not recorded";
+  }
+  return value > 0 ? `+${value} components` : `${value} components`;
+}
+
+function ReleaseCard({
+  isLatest,
+  release,
+}: {
+  readonly isLatest: boolean;
+  readonly release: Awaited<ReturnType<typeof getReleaseRecords>>[number];
+}) {
+  return (
+    <article className="border border-border p-6" id={release.anchor}>
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between">
+        <div>
+          <div className="flex flex-wrap items-center gap-2">
+            <a
+              className="inline-flex"
+              href={release.url}
+              rel="noreferrer"
+              target="_blank"
+            >
+              <Badge>{release.version}</Badge>
+            </a>
+            {isLatest ? (
+              <Badge variant="secondary">What&apos;s new</Badge>
+            ) : null}
+            {release.date ? (
+              <span className="text-sm text-muted-foreground">
+                {release.date}
+              </span>
+            ) : null}
+          </div>
+          <h2 className="mt-4 text-2xl font-semibold">{release.title}</h2>
+          <p className="mt-3 max-w-3xl text-muted-foreground">
+            {release.summary}
+          </p>
+        </div>
+        <Button asChild variant="outline">
+          <a href={release.url} rel="noreferrer" target="_blank">
+            View on GitHub
+          </a>
+        </Button>
+      </div>
+
+      <dl className="mt-6 grid gap-3 sm:grid-cols-3">
+        <div className="border border-border p-4">
+          <dt className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Components
+          </dt>
+          <dd className="mt-1 text-sm font-medium">
+            {formatComponentDelta(release.componentDelta)}
+          </dd>
+        </div>
+        <div className="border border-border p-4">
+          <dt className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Breaking changes
+          </dt>
+          <dd className="mt-1 text-sm font-medium">
+            {release.breakingChanges}
+          </dd>
+        </div>
+        <div className="border border-border p-4">
+          <dt className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Migration
+          </dt>
+          <dd className="mt-1 text-sm font-medium">
+            {release.migrationUrl ? (
+              <a
+                className="underline underline-offset-4"
+                href={release.migrationUrl}
+                rel="noreferrer"
+                target="_blank"
+              >
+                Open guide
+              </a>
+            ) : (
+              "None"
+            )}
+          </dd>
+        </div>
+      </dl>
+
+      <details className="mt-6">
+        <summary className="cursor-pointer text-sm font-medium">
+          Full release notes
+        </summary>
+        <div className="mt-4">
+          <MDXContent content={release.notes} enableMDX={false} />
+        </div>
+      </details>
+    </article>
+  );
+}
+
+function releaseJsonLdItem(
+  release: Awaited<ReturnType<typeof getReleaseRecords>>[number],
+  index: number,
+) {
+  return {
+    "@type": "ListItem",
+    item: {
+      "@type": "SoftwareSourceCode",
+      codeRepository: "https://github.com/vllnt/ui",
+      ...(release.date ? { datePublished: release.date } : {}),
+      name: release.version,
+      programmingLanguage: "TypeScript",
+      runtimePlatform: "React",
+      url: `${SITE_URL}/releases#${release.anchor}`,
+    },
+    position: index + 1,
+  };
+}
+
+export default async function ReleasesPage() {
+  const releases = await getReleaseRecords();
+
+  return (
+    <>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: jsonLdScript([
+            breadcrumbLd([
+              { name: "Home", url: SITE_URL },
+              { name: "Releases", url: `${SITE_URL}/releases` },
+            ]),
+            {
+              "@context": "https://schema.org",
+              "@type": "ItemList",
+              itemListElement: releases.map(releaseJsonLdItem),
+              name: "VLLNT UI Releases",
+              numberOfItems: releases.length,
+            },
+          ]),
+        }}
+        type="application/ld+json"
+      />
+      <Sidebar sections={getSidebarSections()} />
+      <main className="flex-1 overflow-y-auto bg-background">
+        <div className="container mx-auto max-w-5xl px-4 py-16 lg:px-8">
+          <Breadcrumb
+            className="mb-4 text-muted-foreground"
+            items={[{ href: "/", label: "Home" }, { label: "Releases" }]}
+          />
+          <div className="flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between">
+            <div>
+              <p className="text-sm font-medium uppercase tracking-wide text-muted-foreground">
+                What&apos;s new
+              </p>
+              <h1 className="mt-2 text-4xl font-semibold">Releases</h1>
+              <p className="mt-4 max-w-2xl text-lg text-muted-foreground">
+                Versioned release cards from GitHub Releases, backed by the
+                canonical changelog when the API is unavailable.
+              </p>
+            </div>
+            <div className="flex flex-wrap gap-2">
+              <Button asChild variant="outline">
+                <Link href="/changelog">Changelog</Link>
+              </Button>
+              <Button asChild variant="outline">
+                <Link href="/atom.xml">Atom</Link>
+              </Button>
+            </div>
+          </div>
+
+          <div className="mt-10 space-y-6">
+            {releases.map((release, index) => (
+              <ReleaseCard
+                isLatest={index === 0}
+                key={release.anchor}
+                release={release}
+              />
+            ))}
+          </div>
+        </div>
+      </main>
+    </>
+  );
+}
diff --git a/apps/registry/app/rss.xml/route.ts b/apps/registry/app/rss.xml/route.ts
new file mode 100644
index 00000000..668cff15
--- /dev/null
+++ b/apps/registry/app/rss.xml/route.ts
@@ -0,0 +1,68 @@
+import {
+  feedUpdatedAt,
+  getReleaseRecords,
+  releasePageUrl,
+} from "@/lib/changelog";
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+const RSS_HEADERS = new Headers([
+  [
+    "Cache-Control",
+    "public, max-age=0, s-maxage=3600, stale-while-revalidate=86400",
+  ],
+  ["Content-Type", "application/rss+xml; charset=utf-8"],
+]);
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function buildRssDate(value?: string): string {
+  return new Date(value ?? Date.now()).toUTCString();
+}
+
+async function buildRssXml(): Promise<string> {
+  const releases = await getReleaseRecords();
+  const items = releases
+    .map((release) => {
+      const link = releasePageUrl(release);
+      return [
+        "    <item>",
+        `      <title>${escapeXml(release.title)}</title>`,
+        `      <link>${escapeXml(link)}</link>`,
+        `      <guid isPermaLink="true">${escapeXml(link)}</guid>`,
+        `      <pubDate>${escapeXml(buildRssDate(release.date))}</pubDate>`,
+        `      <description>${escapeXml(release.summary)}</description>`,
+        "    </item>",
+      ].join("\n");
+    })
+    .join("\n");
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<rss version="2.0">',
+    "  <channel>",
+    "    <title>VLLNT UI Releases</title>",
+    `    <link>${SITE_URL}/releases</link>`,
+    "    <description>Versioned VLLNT UI release notes.</description>",
+    `    <lastBuildDate>${buildRssDate(feedUpdatedAt(releases))}</lastBuildDate>`,
+    "    <language>en-US</language>",
+    items,
+    "  </channel>",
+    "</rss>",
+  ].join("\n");
+}
+
+export const revalidate = 3600;
+
+async function getRssXml(): Promise<Response> {
+  const body = await buildRssXml();
+  return new Response(body, { headers: RSS_HEADERS });
+}
+
+export { getRssXml as GET };
diff --git a/apps/registry/app/sitemap.ts b/apps/registry/app/sitemap.ts
index 816f585b..a583b66f 100644
--- a/apps/registry/app/sitemap.ts
+++ b/apps/registry/app/sitemap.ts
@@ -8,59 +8,88 @@ type RegistryItem = {
   readonly name: string;
 };
 
-export default function sitemap(): MetadataRoute.Sitemap {
-  const lastModified = new Date();
+type SitemapEntry = MetadataRoute.Sitemap[number];
+type ChangeFrequency = NonNullable<SitemapEntry["changeFrequency"]>;
+type SitemapEntryInput = {
+  readonly changeFrequency: ChangeFrequency;
+  readonly lastModified: Date;
+  readonly priority: number;
+  readonly url: string;
+};
 
-  const staticRoutes: MetadataRoute.Sitemap = [
-    {
-      url: SITE_URL,
-      lastModified,
-      changeFrequency: "weekly",
-      priority: 1.0,
-    },
-    {
-      url: `${SITE_URL}/components`,
-      lastModified,
-      changeFrequency: "weekly",
-      priority: 1.0,
-    },
-    {
-      url: `${SITE_URL}/docs`,
-      lastModified,
-      changeFrequency: "weekly",
-      priority: 0.8,
-    },
+function getRegistryItems(): readonly RegistryItem[] {
+  return (registry as { readonly items: readonly RegistryItem[] }).items;
+}
+
+function entry({
+  changeFrequency,
+  lastModified,
+  priority,
+  url,
+}: SitemapEntryInput): SitemapEntry {
+  return { changeFrequency, lastModified, priority, url };
+}
+
+function staticRoutes(lastModified: Date): MetadataRoute.Sitemap {
+  const routes = [
+    { changeFrequency: "weekly", priority: 1, url: SITE_URL },
+    { changeFrequency: "weekly", priority: 1, url: `${SITE_URL}/components` },
+    { changeFrequency: "weekly", priority: 0.8, url: `${SITE_URL}/changelog` },
+    { changeFrequency: "weekly", priority: 0.8, url: `${SITE_URL}/docs` },
     {
-      url: `${SITE_URL}/philosophy`,
-      lastModified,
       changeFrequency: "monthly",
       priority: 0.6,
+      url: `${SITE_URL}/philosophy`,
     },
-  ];
-
-  const items = (registry as { readonly items: readonly RegistryItem[] }).items;
+    { changeFrequency: "weekly", priority: 0.8, url: `${SITE_URL}/releases` },
+  ] satisfies readonly Omit<SitemapEntryInput, "lastModified">[];
 
-  const componentRoutes: MetadataRoute.Sitemap = items.map((item) => ({
-    url: `${SITE_URL}/components/${item.name}`,
-    lastModified,
-    changeFrequency: "weekly",
-    priority: 0.7,
-  }));
+  return routes.map((route) => entry({ ...route, lastModified }));
+}
 
-  const registryEndpoints: MetadataRoute.Sitemap = [
-    {
-      url: `${SITE_URL}/r/registry.json`,
+function componentRoutes(
+  items: readonly RegistryItem[],
+  lastModified: Date,
+): MetadataRoute.Sitemap {
+  return items.map((item) =>
+    entry({
+      changeFrequency: "weekly",
       lastModified,
+      priority: 0.7,
+      url: `${SITE_URL}/components/${item.name}`,
+    }),
+  );
+}
+
+function registryRoutes(
+  items: readonly RegistryItem[],
+  lastModified: Date,
+): MetadataRoute.Sitemap {
+  return [
+    entry({
       changeFrequency: "weekly",
-      priority: 0.3,
-    },
-    ...items.map((item) => ({
-      url: `${SITE_URL}/r/${item.name}.json`,
       lastModified,
-      changeFrequency: "weekly" as const,
       priority: 0.3,
-    })),
+      url: `${SITE_URL}/r/registry.json`,
+    }),
+    ...items.map((item) =>
+      entry({
+        changeFrequency: "weekly",
+        lastModified,
+        priority: 0.3,
+        url: `${SITE_URL}/r/${item.name}.json`,
+      }),
+    ),
   ];
+}
 
-  return [...staticRoutes, ...componentRoutes, ...registryEndpoints];
+export default function sitemap(): MetadataRoute.Sitemap {
+  const lastModified = new Date();
+  const items = getRegistryItems();
+
+  return [
+    ...staticRoutes(lastModified),
+    ...componentRoutes(items, lastModified),
+    ...registryRoutes(items, lastModified),
+  ];
 }
diff --git a/apps/registry/components/footer/footer.tsx b/apps/registry/components/footer/footer.tsx
index 1f4787bb..6e9691aa 100644
--- a/apps/registry/components/footer/footer.tsx
+++ b/apps/registry/components/footer/footer.tsx
@@ -12,50 +12,53 @@ const LICENSE_URL = "https://github.com/vllnt/ui/blob/main/LICENSE";
 const COC_URL = "https://github.com/vllnt/ui/blob/main/CODE_OF_CONDUCT.md";
 
 type FooterLink = {
+  readonly external?: boolean;
   readonly href: string;
   readonly label: string;
-  readonly external?: boolean;
 };
 
 type FooterColumn = {
-  readonly title: string;
   readonly links: readonly FooterLink[];
+  readonly title: string;
 };
 
 const COLUMNS: readonly FooterColumn[] = [
   {
-    title: "Library",
     links: [
       { href: "/components", label: "Components" },
       { href: "/docs", label: "Docs" },
       { href: "/philosophy", label: "Philosophy" },
     ],
+    title: "Library",
   },
   {
-    title: "Resources",
     links: [
       { external: true, href: STORYBOOK_URL, label: "Storybook" },
       { href: "/r/registry.json", label: "Registry JSON" },
+      { href: "/changelog", label: "Changelog" },
+      { href: "/releases", label: "Releases" },
+      { href: "/rss.xml", label: "RSS feed" },
       { href: "/llms.txt", label: "llms.txt" },
       { href: "/mcp", label: "MCP" },
       { external: true, href: GITHUB_URL, label: "GitHub" },
     ],
+    title: "Resources",
   },
   {
-    title: "Community",
     links: [
       { external: true, href: REQUEST_URL, label: "Request a component" },
       { external: true, href: REPORT_URL, label: "Report a bug" },
       { external: true, href: DISCUSSIONS_URL, label: "Discussions" },
       { external: true, href: SPONSOR_URL, label: "Sponsor" },
     ],
+    title: "Community",
   },
   {
-    title: "Legal",
     links: [
       { external: true, href: LICENSE_URL, label: "License (MIT)" },
       { external: true, href: COC_URL, label: "Code of Conduct" },
     ],
+    title: "Legal",
   },
 ];
 
diff --git a/apps/registry/components/header/header.tsx b/apps/registry/components/header/header.tsx
index 54842b4b..e963131b 100644
--- a/apps/registry/components/header/header.tsx
+++ b/apps/registry/components/header/header.tsx
@@ -1,7 +1,16 @@
 "use client";
 
-import { NavbarSaas, SearchDialog } from "@vllnt/ui";
-import { Github } from "lucide-react";
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  NavbarSaas,
+  SearchDialog,
+} from "@vllnt/ui";
+import { ChevronDown, ExternalLink } from "lucide-react";
+import Link from "next/link";
 import { useRouter } from "next/navigation";
 
 import registryData from "@/registry.json";
@@ -46,6 +55,25 @@ export function Header() {
             }}
             searchPlaceholder="Search components..."
           />
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button size="sm" variant="outline">
+                What&apos;s new
+                <ChevronDown className="size-4" />
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end">
+              <DropdownMenuItem asChild>
+                <Link href="/releases">Releases</Link>
+              </DropdownMenuItem>
+              <DropdownMenuItem asChild>
+                <Link href="/changelog">Changelog</Link>
+              </DropdownMenuItem>
+              <DropdownMenuItem asChild>
+                <Link href="/rss.xml">RSS feed</Link>
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
           <a
             aria-label="VLLNT UI on GitHub"
             className="inline-flex h-9 w-9 items-center justify-center rounded-md text-muted-foreground hover:bg-muted hover:text-foreground"
@@ -53,7 +81,7 @@ export function Header() {
             rel="noreferrer"
             target="_blank"
           >
-            <Github className="h-4 w-4" />
+            <ExternalLink className="size-4" />
           </a>
         </div>
       }
diff --git a/apps/registry/components/landing/landing.tsx b/apps/registry/components/landing/landing.tsx
index 14aa6d5c..48e790b5 100644
--- a/apps/registry/components/landing/landing.tsx
+++ b/apps/registry/components/landing/landing.tsx
@@ -1,13 +1,9 @@
-import { CodeBlock } from "@vllnt/ui";
-import {
-  ArrowRight,
-  Github,
-  Sparkles,
-  Terminal,
-} from "lucide-react";
+import { Badge, CodeBlock } from "@vllnt/ui";
+import { ArrowRight, ExternalLink, Sparkles, Terminal } from "lucide-react";
 import Link from "next/link";
 
 import { Footer } from "@/components/footer/footer";
+import { getLatestReleaseRecords } from "@/lib/changelog";
 import {
   getCategoryCount,
   getComponentCount,
@@ -54,7 +50,7 @@ function Hero({
 
         <div className="mt-8">
           <CodeBlock language="bash">
-            {`pnpm dlx shadcn@latest add https://ui.vllnt.ai/r/button.json`}
+            pnpm dlx shadcn@latest add https://ui.vllnt.ai/r/button.json
           </CodeBlock>
         </div>
 
@@ -78,7 +74,7 @@ function Hero({
             rel="noreferrer"
             target="_blank"
           >
-            <Github className="h-4 w-4" />
+            <ExternalLink className="size-4" />
             GitHub
           </a>
         </div>
@@ -147,10 +143,9 @@ function AgentCallout() {
           Built so AI coding agents can use it directly.
         </h2>
         <p className="mt-4 max-w-2xl text-lg text-muted-foreground">
-          Every component ships as a machine-readable JSON descriptor with
-          name, version, stability, accessibility schema, usage examples,
-          and prop definitions. Agents discover the registry through three
-          surfaces.
+          Every component ships as a machine-readable JSON descriptor with name,
+          version, stability, accessibility schema, usage examples, and prop
+          definitions. Agents discover the registry through three surfaces.
         </p>
 
         <div className="mt-8 grid gap-4 md:grid-cols-3">
@@ -213,7 +208,10 @@ function FeaturedComponents() {
         <h2 className="text-2xl font-semibold">Featured components</h2>
         <p className="mt-2 text-muted-foreground">
           A few favourites. Browse all {getComponentCount()} from{" "}
-          <Link className="font-medium text-foreground underline" href="/components">
+          <Link
+            className="font-medium text-foreground underline"
+            href="/components"
+          >
             /components
           </Link>
           .
@@ -239,6 +237,61 @@ function FeaturedComponents() {
   );
 }
 
+async function ReleasesStrip() {
+  const releases = await getLatestReleaseRecords(3);
+  if (releases.length === 0) return null;
+
+  return (
+    <section className="border-b border-border bg-muted/20">
+      <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
+        <div className="flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between">
+          <div>
+            <h2 className="text-2xl font-semibold">Latest releases</h2>
+            <p className="mt-2 max-w-2xl text-muted-foreground">
+              Follow what changed across the component library, registry, and
+              release pipeline.
+            </p>
+          </div>
+          <Link
+            className="inline-flex h-10 items-center gap-2 rounded-md border border-border px-4 text-sm font-medium hover:bg-muted"
+            href="/releases"
+          >
+            View all releases
+            <ArrowRight className="size-4" />
+          </Link>
+        </div>
+
+        <ul className="mt-8 grid gap-3 lg:grid-cols-3">
+          {releases.map((release, index) => (
+            <li
+              className="border border-border bg-background p-5"
+              key={release.anchor}
+            >
+              <div className="flex flex-wrap items-center gap-2">
+                <Badge>{release.version}</Badge>
+                {index === 0 ? (
+                  <Badge variant="secondary">What&apos;s new</Badge>
+                ) : null}
+              </div>
+              <h3 className="mt-4 font-semibold">{release.title}</h3>
+              <p className="mt-2 line-clamp-3 text-sm text-muted-foreground">
+                {release.summary}
+              </p>
+              <Link
+                className="mt-4 inline-flex items-center gap-1 text-sm font-medium"
+                href={`/releases#${release.anchor}`}
+              >
+                Read notes
+                <ArrowRight className="size-3" />
+              </Link>
+            </li>
+          ))}
+        </ul>
+      </div>
+    </section>
+  );
+}
+
 function CommunityCTA() {
   return (
     <section>
@@ -255,7 +308,7 @@ function CommunityCTA() {
             rel="noreferrer"
             target="_blank"
           >
-            <Github className="h-4 w-4" />
+            <ExternalLink className="size-4" />
             Star on GitHub
           </a>
           <a
@@ -280,7 +333,7 @@ function CommunityCTA() {
   );
 }
 
-export function Landing() {
+export async function Landing() {
   const componentCount = getComponentCount();
   const categoryCount = getCategoryCount();
   const version = getLibraryVersion();
@@ -295,6 +348,7 @@ export function Landing() {
         generatedAt={generatedAt}
         version={version}
       />
+      <ReleasesStrip />
       <AgentCallout />
       <FeaturedComponents />
       <CommunityCTA />
diff --git a/apps/registry/lib/changelog.ts b/apps/registry/lib/changelog.ts
new file mode 100644
index 00000000..710f607a
--- /dev/null
+++ b/apps/registry/lib/changelog.ts
@@ -0,0 +1,378 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { z } from "zod";
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+const GITHUB_REPO_URL = "https://github.com/vllnt/ui";
+const GITHUB_RELEASES_API = "https://api.github.com/repos/vllnt/ui/releases";
+const GITHUB_HEADERS = new Headers([["Accept", "application/vnd.github+json"]]);
+
+export type ChangelogTypeFilter = "all" | "breaking" | "feat" | "fix";
+
+export type ChangelogFilters = {
+  readonly from?: string;
+  readonly to?: string;
+  readonly type: ChangelogTypeFilter;
+};
+
+export type ChangelogSection = {
+  readonly body: string;
+  readonly title: string;
+  readonly type: ChangelogTypeFilter;
+};
+
+export type ChangelogEntry = {
+  readonly anchor: string;
+  readonly date?: string;
+  readonly sections: readonly ChangelogSection[];
+  readonly title: string;
+  readonly version: string;
+};
+
+export type ReleaseRecord = {
+  readonly anchor: string;
+  readonly breakingChanges: number;
+  readonly componentDelta?: number;
+  readonly date?: string;
+  readonly migrationUrl?: string;
+  readonly notes: string;
+  readonly summary: string;
+  readonly title: string;
+  readonly url: string;
+  readonly version: string;
+};
+
+type Heading = {
+  readonly date?: string;
+  readonly title: string;
+  readonly version: string;
+};
+
+const githubReleasesSchema = z.array(z.record(z.string(), z.unknown()));
+const urlSchema = z.url();
+
+function normalizeVersion(version: string): string {
+  return version.replace(/^v/i, "");
+}
+
+export function versionToAnchor(version: string): string {
+  const normalized = version.trim().toLowerCase().replace(/^v/, "");
+  if (normalized === "unreleased") {
+    return "unreleased";
+  }
+  return `v${normalized.replaceAll(".", "-").replaceAll(/[^\da-z-]/g, "-")}`;
+}
+
+function sectionTypeFromTitle(title: string): ChangelogTypeFilter {
+  const lower = title.toLowerCase();
+  if (lower.includes("breaking")) return "breaking";
+  if (lower.includes("fix")) return "fix";
+  if (lower.includes("added") || lower.includes("feature")) return "feat";
+  return "all";
+}
+
+function isWithinDateRange(
+  entry: ChangelogEntry,
+  from?: string,
+  to?: string,
+): boolean {
+  if (!entry.date) return true;
+  if (from && entry.date < from) return false;
+  if (to && entry.date > to) return false;
+  return true;
+}
+
+function extractSummary(notes: string): string {
+  const firstBullet = notes
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => line.startsWith("- "));
+  if (firstBullet) {
+    return firstBullet.replace(/^-+\s*/, "").replaceAll(/[*_`]/g, "");
+  }
+  return (
+    notes
+      .split(/\n{2,}/)
+      .map((paragraph) => paragraph.trim().replaceAll(/\s+/g, " "))
+      .find(
+        (paragraph) => paragraph.length > 0 && !paragraph.startsWith("###"),
+      ) ?? "Release notes are available in the changelog."
+  );
+}
+
+function countBreakingChanges(entry: ChangelogEntry): number {
+  return entry.sections
+    .filter((section) => section.type === "breaking")
+    .reduce((count, section) => {
+      const bullets = section.body
+        .split("\n")
+        .filter((line) => line.trim().startsWith("- "));
+      return count + Math.max(1, bullets.length);
+    }, 0);
+}
+
+function extractComponentDelta(notes: string): number | undefined {
+  const match =
+    /total component count:\s*\*\*(\d+)\*\*\s*\(up from\s*(\d+)\)/i.exec(notes);
+  if (!match) return undefined;
+  return Number(match[1]) - Number(match[2]);
+}
+
+function extractMigrationUrl(notes: string): string | undefined {
+  return /\[migration(?: guide)?]\(([^)]+)\)/i.exec(notes)?.[1];
+}
+
+function changelogCandidates(): readonly string[] {
+  return [
+    path.join(process.cwd(), "CHANGELOG.md"),
+    path.join(process.cwd(), "..", "..", "CHANGELOG.md"),
+    path.join(process.cwd(), "packages", "ui", "CHANGELOG.md"),
+    path.join(process.cwd(), "..", "..", "packages", "ui", "CHANGELOG.md"),
+  ];
+}
+
+async function readChangelog(): Promise<string> {
+  return Promise.any(
+    changelogCandidates().map((candidate) => readFile(candidate, "utf8")),
+  ).catch(() => "");
+}
+
+function parseHeading(line: string): Heading | undefined {
+  const match =
+    /^##\s+\[?([^\n\]]+)]?(?:\s+-\s+(\d{4}-\d{2}-\d{2}|\d{4}-\d{2}))?/.exec(
+      line,
+    );
+  if (!match) return undefined;
+  const rawVersion = match[1];
+  if (!rawVersion) return undefined;
+  const version = rawVersion.replace(/\s+-\s+repo-wide$/i, "").trim();
+  const date = match[2];
+  return { date, title: date ? `${version} - ${date}` : version, version };
+}
+
+function parseSection(lines: readonly string[]): ChangelogSection | undefined {
+  const [heading, ...bodyLines] = lines;
+  const body = bodyLines.join("\n").trim();
+  if (!heading || !body) return undefined;
+  const title = heading.replace(/^###\s+/, "").trim();
+  return { body, title, type: sectionTypeFromTitle(title) };
+}
+
+function appendSectionBlock(
+  blocks: readonly (readonly string[])[],
+  line: string,
+): readonly (readonly string[])[] {
+  if (line.startsWith("### ")) return [...blocks, [line]];
+  const last = blocks.at(-1);
+  if (!last) return blocks;
+  return [...blocks.slice(0, -1), [...last, line]];
+}
+
+function parseSections(lines: readonly string[]): readonly ChangelogSection[] {
+  return lines
+    .reduce(appendSectionBlock, [])
+    .map(parseSection)
+    .filter((section): section is ChangelogSection => section !== undefined);
+}
+
+function parseEntry(block: readonly string[]): ChangelogEntry | undefined {
+  const [heading, ...lines] = block;
+  const parsedHeading = heading ? parseHeading(heading) : undefined;
+  if (!parsedHeading) return undefined;
+  const sections = parseSections(lines);
+  return {
+    anchor: versionToAnchor(parsedHeading.version),
+    date: parsedHeading.date,
+    sections,
+    title: parsedHeading.title,
+    version: parsedHeading.version,
+  };
+}
+
+function appendEntryBlock(
+  blocks: readonly (readonly string[])[],
+  line: string,
+): readonly (readonly string[])[] {
+  if (line.startsWith("## ")) return [...blocks, [line]];
+  const last = blocks.at(-1);
+  if (!last) return blocks;
+  return [...blocks.slice(0, -1), [...last, line]];
+}
+
+async function parseChangelogEntries(): Promise<readonly ChangelogEntry[]> {
+  const changelog = await readChangelog();
+  return changelog
+    .split("\n")
+    .reduce(appendEntryBlock, [])
+    .map(parseEntry)
+    .filter((entry): entry is ChangelogEntry => entry !== undefined)
+    .filter((entry) => entry.sections.length > 0);
+}
+
+function filterEntry(
+  entry: ChangelogEntry,
+  filters: ChangelogFilters,
+): ChangelogEntry | undefined {
+  if (!isWithinDateRange(entry, filters.from, filters.to)) return undefined;
+  if (filters.type === "all") return entry;
+  const sections = entry.sections.filter(
+    (section) => section.type === filters.type,
+  );
+  return sections.length > 0 ? { ...entry, sections } : undefined;
+}
+
+export async function getChangelogEntries(
+  filters?: ChangelogFilters,
+): Promise<readonly ChangelogEntry[]> {
+  const entries = await parseChangelogEntries();
+  const normalizedFilters = filters ?? { type: "all" };
+  return entries
+    .map((entry) => filterEntry(entry, normalizedFilters))
+    .filter((entry): entry is ChangelogEntry => entry !== undefined);
+}
+
+function entryToReleaseRecord(entry: ChangelogEntry): ReleaseRecord {
+  const notes = entry.sections
+    .map((section) => `### ${section.title}\n\n${section.body}`)
+    .join("\n\n");
+  const version = entry.version === "Unreleased" ? "0.3.0" : entry.version;
+  const tag = `v${normalizeVersion(version)}`;
+
+  return {
+    anchor: versionToAnchor(version),
+    breakingChanges: countBreakingChanges(entry),
+    componentDelta: extractComponentDelta(notes),
+    date: entry.date,
+    migrationUrl: extractMigrationUrl(notes),
+    notes,
+    summary: extractSummary(notes),
+    title: entry.version === "Unreleased" ? "0.3.0 preview" : `v${version}`,
+    url: `${GITHUB_REPO_URL}/releases/tag/${tag}`,
+    version: tag,
+  };
+}
+
+async function getLocalReleaseRecords(): Promise<readonly ReleaseRecord[]> {
+  const entries = await parseChangelogEntries();
+  return entries.map(entryToReleaseRecord);
+}
+
+function stringField(
+  record: Readonly<Record<string, unknown>>,
+  key: string,
+): string | undefined {
+  const value = record[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function githubRecordToReleaseRecord(
+  record: Readonly<Record<string, unknown>>,
+): ReleaseRecord | undefined {
+  const version = stringField(record, "tag_name");
+  const url = stringField(record, "html_url");
+  const notes = stringField(record, "body") ?? "";
+  if (!version || !url || !urlSchema.safeParse(url).success) return undefined;
+
+  return {
+    anchor: versionToAnchor(version),
+    breakingChanges: /breaking/i.test(notes) ? 1 : 0,
+    componentDelta: extractComponentDelta(notes),
+    date: stringField(record, "published_at")?.slice(0, 10),
+    migrationUrl: extractMigrationUrl(notes),
+    notes: notes || "Release notes are available on GitHub.",
+    summary: extractSummary(notes),
+    title: stringField(record, "name") ?? version,
+    url,
+    version,
+  };
+}
+
+async function fetchGithubReleaseData(): Promise<readonly ReleaseRecord[]> {
+  const response = await fetch(GITHUB_RELEASES_API, {
+    headers: GITHUB_HEADERS,
+    next: { revalidate: 3600 },
+  });
+  if (!response.ok) return [];
+
+  const parsed = githubReleasesSchema.safeParse(await response.json());
+  if (!parsed.success) return [];
+  return parsed.data
+    .map(githubRecordToReleaseRecord)
+    .filter((release): release is ReleaseRecord => release !== undefined);
+}
+
+async function getGithubReleaseRecords(): Promise<readonly ReleaseRecord[]> {
+  return fetchGithubReleaseData().catch(() => []);
+}
+
+function mergeLocalRelease(
+  localRelease: ReleaseRecord,
+  githubByVersion: ReadonlyMap<string, ReleaseRecord>,
+): ReleaseRecord {
+  const version = normalizeVersion(localRelease.version);
+  const githubRelease = githubByVersion.get(version);
+  if (!githubRelease) return localRelease;
+  return {
+    ...localRelease,
+    date: githubRelease.date ?? localRelease.date,
+    title: githubRelease.title,
+    url: githubRelease.url,
+  };
+}
+
+function githubOnlyReleases(
+  githubReleases: readonly ReleaseRecord[],
+  localReleases: readonly ReleaseRecord[],
+): readonly ReleaseRecord[] {
+  const localVersions = new Set(
+    localReleases.map((release) => normalizeVersion(release.version)),
+  );
+  return githubReleases.filter(
+    (release) => !localVersions.has(normalizeVersion(release.version)),
+  );
+}
+
+export async function getReleaseRecords(): Promise<readonly ReleaseRecord[]> {
+  const [localReleases, githubReleases] = await Promise.all([
+    getLocalReleaseRecords(),
+    getGithubReleaseRecords(),
+  ]);
+
+  if (githubReleases.length === 0) return localReleases;
+  const githubByVersion = new Map(
+    githubReleases.map((release) => [
+      normalizeVersion(release.version),
+      release,
+    ]),
+  );
+
+  return [
+    ...localReleases.map((release) =>
+      mergeLocalRelease(release, githubByVersion),
+    ),
+    ...githubOnlyReleases(githubReleases, localReleases),
+  ];
+}
+
+export async function getLatestReleaseRecords(
+  limit: number,
+): Promise<readonly ReleaseRecord[]> {
+  const releases = await getReleaseRecords();
+  return releases
+    .filter(
+      (release) => release.date !== undefined || release.anchor === "v0-3-0",
+    )
+    .slice(0, limit);
+}
+
+export function feedUpdatedAt(releases: readonly ReleaseRecord[]): string {
+  const firstDated = releases.find((release) => release.date);
+  return firstDated?.date
+    ? new Date(firstDated.date).toISOString()
+    : new Date().toISOString();
+}
+
+export function releasePageUrl(release: ReleaseRecord): string {
+  return `${SITE_URL}/releases#${release.anchor}`;
+}
diff --git a/cliff.toml b/cliff.toml
new file mode 100644
index 00000000..91b20a48
--- /dev/null
+++ b/cliff.toml
@@ -0,0 +1,45 @@
+[changelog]
+header = """
+# Changelog
+
+All notable changes to `@vllnt/ui` and the public registry site are documented
+in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Release automation can regenerate this file from Conventional Commits with
+`git-cliff`.
+"""
+body = """
+{% if version %}
+## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}
+## [Unreleased]
+{% endif %}
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | upper_first }}
+{% for commit in commits %}
+
+- {{ commit.message | upper_first }}
+{% endfor %}
+{% endfor %}
+"""
+trim = true
+
+[git]
+conventional_commits = true
+filter_unconventional = false
+split_commits = false
+tag_pattern = "v[0-9]*"
+
+commit_parsers = [
+  { message = "^feat", group = "Added" },
+  { message = "^fix", group = "Fixed" },
+  { message = "BREAKING CHANGE", group = "Breaking" },
+  { message = "^perf", group = "Changed" },
+  { message = "^refactor", group = "Changed" },
+  { message = "^docs", group = "Docs" },
+  { message = "^ci", group = "CI" },
+  { message = "^chore", group = "Chores" },
+  { message = "^test", group = "Tests" },
+]
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 95e77a7e..e6117cbc 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -23,7 +23,7 @@ The release workflow does not push commits to `main`. Version bumps land via nor
 Open a PR that:
 
 - Updates `packages/ui/package.json` `"version"` to the new target (follow SemVer — see below).
-- Moves the matching entry in `packages/ui/CHANGELOG.md` from `[Unreleased]` to a dated `[x.y.z]` section.
+- Moves the matching entry in root `CHANGELOG.md` and `packages/ui/CHANGELOG.md` from `[Unreleased]` to a dated `[x.y.z]` section. Root `CHANGELOG.md` is the source used for the website, feeds, and GitHub Release notes.
 
 Merge the PR normally. The canary workflow on `main` will immediately publish `@vllnt/ui@{x.y.z}-canary.{sha}` — a dress-rehearsal of the release tarball.
 
@@ -35,7 +35,7 @@ CI will:
 
 - Run quality gates (lint / typecheck / build / test).
 - Read the version from `packages/ui/package.json`. **Fails fast** if a matching `v{x.y.z}` tag already exists — catches dispatches against stale main.
-- Generate release notes grouped by `feat` / `fix` / other, aggregating commit subjects since the previous tag.
+- Read the `CHANGELOG.md` section for the package version and use it as the GitHub Release notes.
 - Push an annotated tag `v{x.y.z}` (tags are not blocked by branch protection; `GITHUB_TOKEN` is sufficient).
 - `pnpm pack` and `npx --yes npm@latest publish --tag latest --provenance --access public`. OIDC trusted publishing signs the provenance attestation.
 - Create the GitHub Release for the new tag.
@@ -47,7 +47,7 @@ CI will:
 
 ## Before requesting a release
 
-- `CHANGELOG.md` has an `[Unreleased]` section describing user-facing changes.
+- `CHANGELOG.md` has an `[Unreleased]` section describing user-facing changes. Use `cliff.toml` with git-cliff if you need to regenerate it from Conventional Commits.
 - The canary built from the same commit passes and lists the expected components (check logs for the tarball manifest).
 - Docs are in sync: component count in `README.md`, family tables in `packages/ui/README.md`, domain references (`ui.vllnt.ai` / `storybook.vllnt.ai`).
 
diff --git a/packages/ui/CHANGELOG.md b/packages/ui/CHANGELOG.md
index 18d96a27..4bf3327f 100644
--- a/packages/ui/CHANGELOG.md
+++ b/packages/ui/CHANGELOG.md
@@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Added
 
+- **Release intelligence surface** — `/changelog`, `/releases`, `/rss.xml`, and `/atom.xml` expose one changelog source through HTML, GitHub release cards, and feed readers. `/docs/changelog` redirects to `/changelog`.
 - **Hooks + utility primitives** — `CopyButton` (+ `useCopyToClipboard` hook), `Banner` + `BannerAction`, `Kbd`, `EmptyState`, `DocumentSiblingNav`.
 - **Pricing + identity cards** — `PricingTable` + `PricingPlan`, `HistoricalFigureCard`, `CivilizationCard` (+ `CivilizationComparison`).
 - **Newsletter** — `NewsletterSignup` (state-machine driven submit flow).

From 48e3dd090f3d530eb6e80c8955d11070f262e1d9 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Sat, 16 May 2026 00:32:59 +0200
Subject: [PATCH 2/2] fix(registry): stabilize release feed dates

---
 apps/registry/app/atom.xml/route.ts | 30 ++++++++++++++++-------------
 apps/registry/app/rss.xml/route.ts  | 30 ++++++++++++++++-------------
 2 files changed, 34 insertions(+), 26 deletions(-)

diff --git a/apps/registry/app/atom.xml/route.ts b/apps/registry/app/atom.xml/route.ts
index e55cd706..fa9dc032 100644
--- a/apps/registry/app/atom.xml/route.ts
+++ b/apps/registry/app/atom.xml/route.ts
@@ -12,6 +12,7 @@ const ATOM_HEADERS = new Headers([
   ],
   ["Content-Type", "application/atom+xml; charset=utf-8"],
 ]);
+type ReleaseRecord = Awaited<ReturnType<typeof getReleaseRecords>>[number];
 
 function escapeXml(value: string): string {
   return value
@@ -23,24 +24,27 @@ function escapeXml(value: string): string {
 }
 
 function buildAtomDate(value?: string): string {
-  return new Date(value ?? Date.now()).toISOString();
+  return new Date(value ?? 0).toISOString();
+}
+
+function buildAtomEntry(release: ReleaseRecord): string {
+  const link = releasePageUrl(release);
+  return [
+    "  <entry>",
+    `    <title>${escapeXml(release.title)}</title>`,
+    `    <id>${escapeXml(link)}</id>`,
+    `    <link href="${escapeXml(link)}" />`,
+    `    <updated>${escapeXml(buildAtomDate(release.date))}</updated>`,
+    `    <summary>${escapeXml(release.summary)}</summary>`,
+    "  </entry>",
+  ].join("\n");
 }
 
 async function buildAtomXml(): Promise<string> {
   const releases = await getReleaseRecords();
   const entries = releases
-    .map((release) => {
-      const link = releasePageUrl(release);
-      return [
-        "  <entry>",
-        `    <title>${escapeXml(release.title)}</title>`,
-        `    <id>${escapeXml(link)}</id>`,
-        `    <link href="${escapeXml(link)}" />`,
-        `    <updated>${escapeXml(buildAtomDate(release.date))}</updated>`,
-        `    <summary>${escapeXml(release.summary)}</summary>`,
-        "  </entry>",
-      ].join("\n");
-    })
+    .filter((release) => release.date !== undefined)
+    .map(buildAtomEntry)
     .join("\n");
 
   return [
diff --git a/apps/registry/app/rss.xml/route.ts b/apps/registry/app/rss.xml/route.ts
index 668cff15..0bd23a2a 100644
--- a/apps/registry/app/rss.xml/route.ts
+++ b/apps/registry/app/rss.xml/route.ts
@@ -12,6 +12,7 @@ const RSS_HEADERS = new Headers([
   ],
   ["Content-Type", "application/rss+xml; charset=utf-8"],
 ]);
+type ReleaseRecord = Awaited<ReturnType<typeof getReleaseRecords>>[number];
 
 function escapeXml(value: string): string {
   return value
@@ -23,24 +24,27 @@ function escapeXml(value: string): string {
 }
 
 function buildRssDate(value?: string): string {
-  return new Date(value ?? Date.now()).toUTCString();
+  return new Date(value ?? 0).toUTCString();
+}
+
+function buildRssItem(release: ReleaseRecord): string {
+  const link = releasePageUrl(release);
+  return [
+    "    <item>",
+    `      <title>${escapeXml(release.title)}</title>`,
+    `      <link>${escapeXml(link)}</link>`,
+    `      <guid isPermaLink="true">${escapeXml(link)}</guid>`,
+    `      <pubDate>${escapeXml(buildRssDate(release.date))}</pubDate>`,
+    `      <description>${escapeXml(release.summary)}</description>`,
+    "    </item>",
+  ].join("\n");
 }
 
 async function buildRssXml(): Promise<string> {
   const releases = await getReleaseRecords();
   const items = releases
-    .map((release) => {
-      const link = releasePageUrl(release);
-      return [
-        "    <item>",
-        `      <title>${escapeXml(release.title)}</title>`,
-        `      <link>${escapeXml(link)}</link>`,
-        `      <guid isPermaLink="true">${escapeXml(link)}</guid>`,
-        `      <pubDate>${escapeXml(buildRssDate(release.date))}</pubDate>`,
-        `      <description>${escapeXml(release.summary)}</description>`,
-        "    </item>",
-      ].join("\n");
-    })
+    .filter((release) => release.date !== undefined)
+    .map(buildRssItem)
     .join("\n");
 
   return [