diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..8da9aeb
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,4 @@
+# Changelog API endpoint (GraphQL). REQUIRED — `pnpm dev` and `pnpm build` fail without it.
+# Ask the docs team for the value; in CI it is provided by the repository variable of the same name.
+# Note: VITE_ variables are compiled into the public browser bundle — never put secrets here.
+VITE_CHANGELOG_ENDPOINT=https://<changelog-app-host>/query
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 826f4e5..6423b3d 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -44,6 +44,8 @@ jobs:
 
       - name: Build with VitePress
         run: pnpm run build
+        env:
+          VITE_CHANGELOG_ENDPOINT: ${{ vars.VITE_CHANGELOG_ENDPOINT }}
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml
index 95f1453..dc8d295 100644
--- a/.github/workflows/pr-checks.yml
+++ b/.github/workflows/pr-checks.yml
@@ -52,6 +52,8 @@ jobs:
 
       - name: Build
         run: pnpm build
+        env:
+          VITE_CHANGELOG_ENDPOINT: ${{ vars.VITE_CHANGELOG_ENDPOINT }}
 
   typo-check:
     runs-on: ubuntu-latest
diff --git a/.gitignore b/.gitignore
index 61dffdf..6e1bfe2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@ node_modules/
 # Environment
 .env
 .env.*
+!.env.example
 
 # IDE
 .vscode/
diff --git a/.vitepress/config.mts b/.vitepress/config.mts
index 2bfa680..66bf9b8 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -1,14 +1,24 @@
-import { defineConfig } from "vitepress";
+import { defineConfig, loadEnv } from "vitepress";
 import { withMermaid } from "vitepress-plugin-mermaid";
 import path from "node:path";
 import { generateNav } from "./config/nav.js";
 import { generateAllSidebars } from "./config/sidebar.js";
 import { configureMarkdown } from "./config/markdown.js";
 import { generateSitemap } from "./config/sitemap.js";
+import {
+  CHANGELOG_ENDPOINT_VAR,
+  CHANGELOG_PROXY_PATH,
+  resolveChangelogEndpoint,
+} from "./config/changelog.js";
 import llmstxt from "vitepress-plugin-llms";
 
 const docsDir = path.join(process.cwd(), "docs");
 
+// Resolved at config load so a missing/invalid endpoint fails `pnpm dev` and
+// `pnpm build` immediately, rather than shipping a page that errors at runtime.
+const env = loadEnv("", process.cwd());
+const changelogEndpoint = resolveChangelogEndpoint(env[CHANGELOG_ENDPOINT_VAR]);
+
 export default withMermaid(
   defineConfig({
     title: "Tailor",
@@ -38,6 +48,19 @@ export default withMermaid(
       optimizeDeps: {
         include: ["mermaid"],
       },
+      // The changelog API does not allow cross-origin requests from localhost, so in
+      // `pnpm dev` the browser calls this same-origin path and Vite forwards it upstream.
+      // Production calls the API directly (see composables/useChangelogData.ts).
+      // Endpoint comes from VITE_CHANGELOG_ENDPOINT (see config/changelog.ts).
+      server: {
+        proxy: {
+          [CHANGELOG_PROXY_PATH]: {
+            target: changelogEndpoint.origin,
+            changeOrigin: true,
+            rewrite: (p) => p.replace(CHANGELOG_PROXY_PATH, ""),
+          },
+        },
+      },
       plugins: [
         llmstxt({
           domain: "https://docs.tailor.tech",
diff --git a/.vitepress/config/changelog.ts b/.vitepress/config/changelog.ts
new file mode 100644
index 0000000..4783af0
--- /dev/null
+++ b/.vitepress/config/changelog.ts
@@ -0,0 +1,26 @@
+/**
+ * Changelog API endpoint configuration, shared by the Vite dev proxy (config.mts)
+ * and the client fetcher (theme/composables/useChangelogData.ts).
+ *
+ * The endpoint is intentionally not defaulted in source. It must be supplied via
+ * `VITE_CHANGELOG_ENDPOINT` (a full URL including the GraphQL path) — locally in
+ * `.env` (see .env.example), in CI via the repository variable of the same name.
+ */
+export const CHANGELOG_ENDPOINT_VAR = "VITE_CHANGELOG_ENDPOINT";
+
+/** Same-origin path the dev server proxies to the upstream endpoint's origin. */
+export const CHANGELOG_PROXY_PATH = "/__changelog-api";
+
+export function resolveChangelogEndpoint(raw: string | undefined): URL {
+  const value = raw?.trim();
+  if (!value) {
+    throw new Error(
+      `${CHANGELOG_ENDPOINT_VAR} is not set. Add it to .env (see .env.example) or the CI environment.`,
+    );
+  }
+  try {
+    return new URL(value);
+  } catch {
+    throw new Error(`${CHANGELOG_ENDPOINT_VAR} must be a full URL, got: ${value}`);
+  }
+}
diff --git a/.vitepress/theme/components/Changelog.vue b/.vitepress/theme/components/Changelog.vue
index 030adfe..93c58ac 100644
--- a/.vitepress/theme/components/Changelog.vue
+++ b/.vitepress/theme/components/Changelog.vue
@@ -45,22 +45,41 @@
           <h3 class="entry-title">{{ entry.title }}</h3>
 
           <div v-if="entry.narrative" class="entry-narrative">
-            <div class="narrative-summary">
-              <strong>What's new:</strong> {{ entry.narrative.summary }}
-            </div>
-            <div v-if="entry.narrative.impact" class="narrative-impact">
-              <strong>Impact:</strong> {{ entry.narrative.impact }}
-            </div>
-            <div v-if="entry.narrative.details?.length" class="narrative-details">
-              <strong>Key changes:</strong>
+            <section class="narrative-section narrative-summary">
+              <h4 class="narrative-label">What's new</h4>
+              <p v-html="formatNarrativeHtml(entry.narrative.summary)" />
+            </section>
+            <section v-if="entry.narrative.impact" class="narrative-section narrative-impact">
+              <h4 class="narrative-label">Impact</h4>
+              <p v-html="formatNarrativeHtml(entry.narrative.impact)" />
+            </section>
+            <section
+              v-if="entry.narrative.details?.length"
+              class="narrative-section narrative-details"
+            >
+              <h4 class="narrative-label">Key changes</h4>
               <ul>
-                <li v-for="(detail, i) in entry.narrative.details" :key="i">{{ detail }}</li>
+                <li
+                  v-for="(detail, i) in entry.narrative.details"
+                  :key="i"
+                  v-html="formatNarrativeHtml(detail)"
+                />
               </ul>
-            </div>
-            <div v-if="entry.narrative.migration" class="narrative-migration">
-              <strong>⚠️ Migration required:</strong>
-              <div v-html="entry.narrative.migration" />
-            </div>
+            </section>
+            <section
+              v-if="entry.narrative.migration"
+              class="narrative-section narrative-migration"
+              role="note"
+            >
+              <h4 class="narrative-label">⚠️ Migration required</h4>
+              <template v-for="mig in [splitNarrativeItems(entry.narrative.migration)]" :key="0">
+                <p v-if="mig.intro" v-html="formatNarrativeHtml(mig.intro)" />
+                <p v-if="mig.items.length === 1" v-html="formatNarrativeHtml(mig.items[0])" />
+                <ol v-else>
+                  <li v-for="(item, i) in mig.items" :key="i" v-html="formatNarrativeHtml(item)" />
+                </ol>
+              </template>
+            </section>
           </div>
 
           <div v-else-if="entry.githubUrl" class="narrative-full-notes">
@@ -96,7 +115,13 @@
 <script setup lang="ts">
 import { onMounted } from "vue";
 import { useChangelogData } from "../composables/useChangelogData";
-import { useChangelog, formatDate, PRODUCTS } from "../composables/useChangelog";
+import {
+  useChangelog,
+  formatDate,
+  formatNarrativeHtml,
+  splitNarrativeItems,
+  PRODUCTS,
+} from "../composables/useChangelog";
 import FilterTabs from "./FilterTabs.vue";
 
 const { data: changelogData, loading, error, load } = useChangelogData();
diff --git a/.vitepress/theme/composables/useChangelog.ts b/.vitepress/theme/composables/useChangelog.ts
index ddba7ef..9d98396 100644
--- a/.vitepress/theme/composables/useChangelog.ts
+++ b/.vitepress/theme/composables/useChangelog.ts
@@ -40,6 +40,44 @@ export function formatDate(dateString: string): string {
   });
 }
 
+/**
+ * Renders plain-text narrative prose (as delivered by the changelog API) to safe HTML:
+ * escapes markup, turns `backtick` spans into <code>, and links bare URLs.
+ */
+export function formatNarrativeHtml(text: string): string {
+  const escaped = text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+
+  return escaped
+    .replace(/`([^`]+)`/g, "<code>$1</code>")
+    .replace(
+      /(https?:\/\/[^\s<]+?)([.,;:)]*)(?=\s|$|<)/g,
+      '<a href="$1" target="_blank" rel="noopener">$1</a>$2',
+    );
+}
+
+/**
+ * Splits a migration paragraph into list items. Prefers explicit "(1) … (2) …"
+ * markers; otherwise falls back to sentence boundaries. Returns any text that
+ * precedes the first numbered marker as `intro`.
+ */
+export function splitNarrativeItems(text: string): { intro: string; items: string[] } {
+  const trimmed = text.trim();
+  const numbered = trimmed.split(/\s*\(\d+\)\s+/);
+  if (numbered.length > 2) {
+    const [intro, ...items] = numbered;
+    return { intro: intro.trim(), items: items.map((i) => i.trim()).filter(Boolean) };
+  }
+  const sentences = trimmed
+    .split(/(?<=[.!?])\s+(?=[A-Z`(])/)
+    .map((i) => i.trim())
+    .filter(Boolean);
+  return { intro: "", items: sentences };
+}
+
 export function useChangelog(data: Ref<ChangelogData | null>) {
   const selectedProduct = ref("All");
   const currentPage = ref(1);
diff --git a/.vitepress/theme/composables/useChangelogData.ts b/.vitepress/theme/composables/useChangelogData.ts
index ae42e4d..6e18957 100644
--- a/.vitepress/theme/composables/useChangelogData.ts
+++ b/.vitepress/theme/composables/useChangelogData.ts
@@ -1,7 +1,14 @@
 import { ref } from "vue";
 import type { ChangelogData, ChangelogItem } from "./useChangelog";
+import { CHANGELOG_PROXY_PATH, resolveChangelogEndpoint } from "../../config/changelog";
 
-const ENDPOINT = "https://changelog-i0d011qixh.erp.dev/query";
+// Endpoint comes from VITE_CHANGELOG_ENDPOINT (required; validated at build time in
+// config.mts). In local dev the request goes through the Vite proxy configured there,
+// because the upstream does not send CORS headers for a localhost origin.
+const endpointUrl = resolveChangelogEndpoint(import.meta.env.VITE_CHANGELOG_ENDPOINT);
+const ENDPOINT = import.meta.env.DEV
+  ? `${CHANGELOG_PROXY_PATH}${endpointUrl.pathname}${endpointUrl.search}`
+  : endpointUrl.href;
 
 const PAGE_SIZE = 100;
 
diff --git a/.vitepress/theme/styles/changelog.css b/.vitepress/theme/styles/changelog.css
index c2c2009..4333ee3 100644
--- a/.vitepress/theme/styles/changelog.css
+++ b/.vitepress/theme/styles/changelog.css
@@ -146,12 +146,6 @@
   border-color: rgba(191, 219, 254, 0.25);
 }
 
-:root.dark .narrative-migration {
-  background: rgba(254, 242, 242, 0.08);
-  border-color: rgba(254, 202, 202, 0.25);
-  color: #fca5a5;
-}
-
 /* Footer tags */
 .entry-tag {
   padding: 0.125rem 0.5rem;
@@ -198,42 +192,90 @@
   padding: 1.5rem;
 }
 
-.narrative-summary,
-.narrative-impact,
-.narrative-details {
-  margin-bottom: 1rem;
+.narrative-section {
+  margin-bottom: 1.25rem;
 }
 
-.narrative-summary:last-child,
-.narrative-impact:last-child,
-.narrative-details:last-child {
+.narrative-section:last-child {
   margin-bottom: 0;
 }
 
-.narrative-summary strong,
-.narrative-impact strong,
-.narrative-details strong {
-  color: var(--vp-c-text-1);
+/* Section labels — Tailor brand blue eyebrow, visually distinct from body copy */
+.entry-narrative .narrative-label {
+  margin: 0 0 0.375rem;
+  font-size: 0.75rem;
+  line-height: 1.25rem;
   font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--vp-c-brand-1);
+}
+
+.entry-narrative p {
+  margin: 0;
+  font-size: 0.9375rem;
+  line-height: 1.7;
+  color: var(--vp-c-text-1);
 }
 
 .narrative-details ul {
-  margin: 0.5rem 0 0 0;
+  margin: 0;
   padding-left: 1.5rem;
 }
 
 .narrative-details li {
   margin-bottom: 0.25rem;
-  color: var(--vp-c-text-2);
+  font-size: 0.9375rem;
+  line-height: 1.7;
+  color: var(--vp-c-text-1);
 }
 
+/* Migration callout — warning-tinted background only; body copy stays in the
+   standard text colour so it remains readable, and only the label carries the
+   warning hue. Uses VitePress semantic tokens, so dark mode needs no override. */
 .narrative-migration {
-  margin-top: 1rem;
-  padding: 1rem;
-  background: #fef2f2;
-  border: 1px solid #fecaca;
+  margin-top: 1.25rem;
+  padding: 1rem 1.25rem;
+  background: var(--vp-c-warning-soft);
   border-radius: 6px;
-  color: #991b1b;
+}
+
+.narrative-migration p + ol {
+  margin-top: 0.5rem;
+}
+
+.narrative-migration ol {
+  margin: 0;
+  padding-left: 1.5rem;
+  list-style: decimal;
+}
+
+.narrative-migration li {
+  margin-bottom: 0.375rem;
+  font-size: 0.9375rem;
+  line-height: 1.7;
+  color: var(--vp-c-text-1);
+}
+
+.narrative-migration li:last-child {
+  margin-bottom: 0;
+}
+
+.narrative-migration .narrative-label {
+  color: var(--vp-c-warning-1);
+}
+
+/* Inline code inherits the site standard (.vp-doc :not(pre) > code in typography.css);
+   only allow long identifiers to wrap so they don't overflow the card. */
+.entry-narrative code {
+  overflow-wrap: anywhere;
+}
+
+.entry-narrative a {
+  color: var(--vp-c-brand-1);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  word-break: break-all;
 }
 
 /* Body (markdown rendered from GitHub release notes) */
diff --git a/CLAUDE.md b/CLAUDE.md
index 4145189..d1d9d71 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,6 +6,8 @@ Tailor Platform documentation site built with **VitePress 1.6.4**. Contains tech
 
 ## Quick Commands
 
+First run: `cp .env.example .env` and set `VITE_CHANGELOG_ENDPOINT` (required by dev and build).
+
 - `pnpm dev` — Start dev server (http://localhost:5173)
 - `pnpm build` — Production build
 - `pnpm preview` — Preview production build