From 547be7fa6eb701737be2c55b8956be368603bd57 Mon Sep 17 00:00:00 2001
From: Anukiran <anukiransolur@gmail.com>
Date: Thu, 10 Sep 2026 13:44:59 -0500
Subject: [PATCH 1/3] feat(changelog): restyle release card narrative sections

- Render section labels (What's new, Impact, Key changes, Migration
  required) as brand-blue eyebrow headings, distinct from body copy
- Turn the migration note into a warning-tinted callout with a numbered
  step list instead of a single red paragraph
- Escape API narrative text and render backtick spans as inline code
  (site standard style) and bare URLs as links
- Add a Vite dev proxy for the changelog API so the page loads under
  `pnpm dev` (the upstream sends no CORS headers for localhost)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .vitepress/config.mts                         | 12 +++
 .vitepress/theme/components/Changelog.vue     | 55 ++++++++----
 .vitepress/theme/composables/useChangelog.ts  | 38 ++++++++
 .../theme/composables/useChangelogData.ts     |  6 +-
 .vitepress/theme/styles/changelog.css         | 90 ++++++++++++++-----
 5 files changed, 161 insertions(+), 40 deletions(-)

diff --git a/.vitepress/config.mts b/.vitepress/config.mts
index 2bfa680..f0cb243 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -38,6 +38,18 @@ 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).
+      server: {
+        proxy: {
+          "/__changelog-api": {
+            target: "https://changelog-i0d011qixh.erp.dev",
+            changeOrigin: true,
+            rewrite: (p) => p.replace(/^\/__changelog-api/, ""),
+          },
+        },
+      },
       plugins: [
         llmstxt({
           domain: "https://docs.tailor.tech",
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..3892c5c 100644
--- a/.vitepress/theme/composables/useChangelogData.ts
+++ b/.vitepress/theme/composables/useChangelogData.ts
@@ -1,7 +1,11 @@
 import { ref } from "vue";
 import type { ChangelogData, ChangelogItem } from "./useChangelog";
 
-const ENDPOINT = "https://changelog-i0d011qixh.erp.dev/query";
+// In local dev the API is reached through the Vite proxy configured in config.mts,
+// because the upstream does not send CORS headers for a localhost origin.
+const ENDPOINT = import.meta.env.DEV
+  ? "/__changelog-api/query"
+  : "https://changelog-i0d011qixh.erp.dev/query";
 
 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) */

From 7ce07a913e1a90919a66d687c5ff2cb591162742 Mon Sep 17 00:00:00 2001
From: Anukiran <anukiransolur@gmail.com>
Date: Fri, 11 Sep 2026 13:24:44 -0500
Subject: [PATCH 2/3] feat(changelog): make API endpoint configurable via
 VITE_CHANGELOG_ENDPOINT

Both the client fetcher and the dev proxy now derive from a single
VITE_CHANGELOG_ENDPOINT value (default: production endpoint) defined in
.vitepress/config/changelog.ts, so a dev or preview deployment of the
changelog app can be targeted without code changes. Adds .env.example.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .env.example                                  |  4 ++++
 .gitignore                                    |  1 +
 .vitepress/config.mts                         | 13 +++++++----
 .vitepress/config/changelog.ts                | 22 +++++++++++++++++++
 .../theme/composables/useChangelogData.ts     | 11 ++++++----
 5 files changed, 43 insertions(+), 8 deletions(-)
 create mode 100644 .env.example
 create mode 100644 .vitepress/config/changelog.ts

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..aab5340
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,4 @@
+# Changelog API endpoint (GraphQL). Optional; defaults to the production endpoint.
+# Point this at a dev/preview deployment of the changelog app to test against it.
+# Used by the changelog page and, under `pnpm dev`, by the Vite proxy in .vitepress/config.mts.
+VITE_CHANGELOG_ENDPOINT=https://changelog-i0d011qixh.erp.dev/query
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 f0cb243..f3327cc 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -1,14 +1,18 @@
-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_PROXY_PATH, resolveChangelogEndpoint } from "./config/changelog.js";
 import llmstxt from "vitepress-plugin-llms";
 
 const docsDir = path.join(process.cwd(), "docs");
 
+const env = loadEnv("", process.cwd());
+const changelogEndpoint = resolveChangelogEndpoint(env.VITE_CHANGELOG_ENDPOINT);
+
 export default withMermaid(
   defineConfig({
     title: "Tailor",
@@ -41,12 +45,13 @@ export default withMermaid(
       // 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 is configurable via VITE_CHANGELOG_ENDPOINT (see config/changelog.ts).
       server: {
         proxy: {
-          "/__changelog-api": {
-            target: "https://changelog-i0d011qixh.erp.dev",
+          [CHANGELOG_PROXY_PATH]: {
+            target: changelogEndpoint.origin,
             changeOrigin: true,
-            rewrite: (p) => p.replace(/^\/__changelog-api/, ""),
+            rewrite: (p) => p.replace(CHANGELOG_PROXY_PATH, ""),
           },
         },
       },
diff --git a/.vitepress/config/changelog.ts b/.vitepress/config/changelog.ts
new file mode 100644
index 0000000..17339b3
--- /dev/null
+++ b/.vitepress/config/changelog.ts
@@ -0,0 +1,22 @@
+/**
+ * Changelog API endpoint configuration, shared by the Vite dev proxy (config.mts)
+ * and the client fetcher (theme/composables/useChangelogData.ts).
+ *
+ * Override with `VITE_CHANGELOG_ENDPOINT` (see .env.example). Must be a full URL
+ * including the GraphQL path.
+ */
+export const DEFAULT_CHANGELOG_ENDPOINT = "https://changelog-i0d011qixh.erp.dev/query";
+
+/** 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() || DEFAULT_CHANGELOG_ENDPOINT;
+  try {
+    return new URL(value);
+  } catch {
+    throw new Error(
+      `VITE_CHANGELOG_ENDPOINT must be a full URL (e.g. ${DEFAULT_CHANGELOG_ENDPOINT}), got: ${value}`,
+    );
+  }
+}
diff --git a/.vitepress/theme/composables/useChangelogData.ts b/.vitepress/theme/composables/useChangelogData.ts
index 3892c5c..292d820 100644
--- a/.vitepress/theme/composables/useChangelogData.ts
+++ b/.vitepress/theme/composables/useChangelogData.ts
@@ -1,11 +1,14 @@
 import { ref } from "vue";
 import type { ChangelogData, ChangelogItem } from "./useChangelog";
+import { CHANGELOG_PROXY_PATH, resolveChangelogEndpoint } from "../../config/changelog";
 
-// In local dev the API is reached through the Vite proxy configured in config.mts,
-// because the upstream does not send CORS headers for a localhost origin.
+// Endpoint comes from VITE_CHANGELOG_ENDPOINT (default in config/changelog.ts). In local
+// dev the request goes through the Vite proxy configured in config.mts, 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-api/query"
-  : "https://changelog-i0d011qixh.erp.dev/query";
+  ? `${CHANGELOG_PROXY_PATH}${endpointUrl.pathname}${endpointUrl.search}`
+  : endpointUrl.href;
 
 const PAGE_SIZE = 100;
 

From d88143d2137f85d59e443be16fcf2896e233fbed Mon Sep 17 00:00:00 2001
From: Anukiran <anukiransolur@gmail.com>
Date: Fri, 11 Sep 2026 13:45:26 -0500
Subject: [PATCH 3/3] feat(changelog): require VITE_CHANGELOG_ENDPOINT, drop
 hardcoded endpoint

Remove the production changelog API URL from source. The endpoint must now
be supplied via VITE_CHANGELOG_ENDPOINT: locally through .env, in CI through
the repository variable of the same name (wired into the PR-check and Pages
deploy build steps). A missing or malformed value fails `pnpm dev` and
`pnpm build` at config load with a clear message.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .env.example                                   |  8 ++++----
 .github/workflows/deploy-docs.yml              |  2 ++
 .github/workflows/pr-checks.yml                |  2 ++
 .vitepress/config.mts                          | 12 +++++++++---
 .vitepress/config/changelog.ts                 | 18 +++++++++++-------
 .../theme/composables/useChangelogData.ts      |  6 +++---
 CLAUDE.md                                      |  2 ++
 7 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/.env.example b/.env.example
index aab5340..8da9aeb 100644
--- a/.env.example
+++ b/.env.example
@@ -1,4 +1,4 @@
-# Changelog API endpoint (GraphQL). Optional; defaults to the production endpoint.
-# Point this at a dev/preview deployment of the changelog app to test against it.
-# Used by the changelog page and, under `pnpm dev`, by the Vite proxy in .vitepress/config.mts.
-VITE_CHANGELOG_ENDPOINT=https://changelog-i0d011qixh.erp.dev/query
+# 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/.vitepress/config.mts b/.vitepress/config.mts
index f3327cc..66bf9b8 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -5,13 +5,19 @@ 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_PROXY_PATH, resolveChangelogEndpoint } from "./config/changelog.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.VITE_CHANGELOG_ENDPOINT);
+const changelogEndpoint = resolveChangelogEndpoint(env[CHANGELOG_ENDPOINT_VAR]);
 
 export default withMermaid(
   defineConfig({
@@ -45,7 +51,7 @@ export default withMermaid(
       // 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 is configurable via VITE_CHANGELOG_ENDPOINT (see config/changelog.ts).
+      // Endpoint comes from VITE_CHANGELOG_ENDPOINT (see config/changelog.ts).
       server: {
         proxy: {
           [CHANGELOG_PROXY_PATH]: {
diff --git a/.vitepress/config/changelog.ts b/.vitepress/config/changelog.ts
index 17339b3..4783af0 100644
--- a/.vitepress/config/changelog.ts
+++ b/.vitepress/config/changelog.ts
@@ -2,21 +2,25 @@
  * Changelog API endpoint configuration, shared by the Vite dev proxy (config.mts)
  * and the client fetcher (theme/composables/useChangelogData.ts).
  *
- * Override with `VITE_CHANGELOG_ENDPOINT` (see .env.example). Must be a full URL
- * including the GraphQL path.
+ * 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 DEFAULT_CHANGELOG_ENDPOINT = "https://changelog-i0d011qixh.erp.dev/query";
+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() || DEFAULT_CHANGELOG_ENDPOINT;
+  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(
-      `VITE_CHANGELOG_ENDPOINT must be a full URL (e.g. ${DEFAULT_CHANGELOG_ENDPOINT}), got: ${value}`,
-    );
+    throw new Error(`${CHANGELOG_ENDPOINT_VAR} must be a full URL, got: ${value}`);
   }
 }
diff --git a/.vitepress/theme/composables/useChangelogData.ts b/.vitepress/theme/composables/useChangelogData.ts
index 292d820..6e18957 100644
--- a/.vitepress/theme/composables/useChangelogData.ts
+++ b/.vitepress/theme/composables/useChangelogData.ts
@@ -2,9 +2,9 @@ import { ref } from "vue";
 import type { ChangelogData, ChangelogItem } from "./useChangelog";
 import { CHANGELOG_PROXY_PATH, resolveChangelogEndpoint } from "../../config/changelog";
 
-// Endpoint comes from VITE_CHANGELOG_ENDPOINT (default in config/changelog.ts). In local
-// dev the request goes through the Vite proxy configured in config.mts, because the
-// upstream does not send CORS headers for a localhost origin.
+// 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}`
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