blume 0.7.0 → 0.8.0

package/dist/cli/index.js

@@ -48,7 +48,6 @@ import { dirname as dirname3, join as join4 } from "pathe";
 // src/registry/registry.ts
 import { join as join3 } from "pathe";
 var packageSrc = join3(packageRoot(), "src");
-var itemsRoot = join3(packageRoot(), "src", "registry", "items");
 var layoutComponent = (config) => {
   const target = `components/blume/${config.file}`;
   return {
@@ -663,14 +662,17 @@ var buildAgentReadability = (project) => {
   }
   const site = config.deployment.site ?? null;
   const deployBase = normalizeBasePath(config.deployment.base);
-  const abs = (path) => site ? `${site.replace(/\/+$/u, "")}${withBasePath(deployBase, path)}` : path;
+  const abs = (path) => {
+    const based = withBasePath(deployBase, path);
+    return site ? `${site.replace(/\/+$/u, "")}${based}` : based;
+  };
   const artifacts = {
     markdown: {
       contentNegotiation: "text/markdown",
       pattern: abs("/{route}.md")
     }
   };
-  if (config.ai.llmsTxt) {
+  if (config.ai.llmsTxt.enabled) {
     artifacts.llmsFullTxt = abs("/llms-full.txt");
     artifacts.llmsTxt = abs("/llms.txt");
   }
@@ -744,37 +746,376 @@ var readEntryText = async (ctx, page) => {
   return "";
 };
 
+// src/ai/component-markdown.ts
+import { mdxToMdast } from "satteri";
+
+// src/components/content/youtube.ts
+var BARE_ID = /^[\w-]{11}$/u;
+var URL_ID = /(?:youtu\.be\/|\/embed\/|\/shorts\/|\/live\/|[?&]v=)(?<id>[\w-]{11})/u;
+var parseYouTubeId = (input) => {
+  const value = input.trim();
+  if (!value) {
+    return null;
+  }
+  if (BARE_ID.test(value)) {
+    return value;
+  }
+  return URL_ID.exec(value)?.groups?.id ?? null;
+};
+
+// src/ai/component-markdown.ts
+var evaluateExpression = (raw) => {
+  try {
+    const value = new Function(`"use strict"; return (${raw});`)();
+    return { ok: true, value };
+  } catch {
+    return { ok: false, value: undefined };
+  }
+};
+var readProps = (node) => {
+  const props = {};
+  let lossy = false;
+  for (const attribute of node.attributes ?? []) {
+    if (attribute.type !== "mdxJsxAttribute" || !attribute.name) {
+      lossy = true;
+      continue;
+    }
+    if (attribute.value === null || attribute.value === undefined) {
+      props[attribute.name] = true;
+    } else if (typeof attribute.value === "string") {
+      props[attribute.name] = attribute.value;
+    } else {
+      const result = evaluateExpression(attribute.value.value);
+      if (result.ok) {
+        props[attribute.name] = result.value;
+      } else {
+        lossy = true;
+      }
+    }
+  }
+  return { lossy, props };
+};
+var hasOffsets = (node) => typeof node.position?.start?.offset === "number" && typeof node.position?.end?.offset === "number";
+var applySplices = (text, splices) => {
+  let result = text;
+  for (const splice of [...splices].toSorted((a, b) => b.start - a.start)) {
+    const lineStart = result.lastIndexOf(`
+`, splice.start - 1) + 1;
+    const prefix = result.slice(lineStart, splice.start);
+    const indent = /^[\t ]+$/u.test(prefix) ? prefix : "";
+    const replacement = indent ? splice.text.split(`
+`).map((line, index) => index === 0 || line === "" ? line : `${indent}${line}`).join(`
+`) : splice.text;
+    result = result.slice(0, splice.start) + replacement + result.slice(splice.end);
+  }
+  return result;
+};
+var dedent = (text) => {
+  const lines = text.split(`
+`);
+  const rest = lines.slice(1).filter((line) => line.trim() !== "");
+  if (rest.length === 0) {
+    return text;
+  }
+  const indent = Math.min(...rest.map((line) => line.length - line.trimStart().length));
+  if (indent === 0) {
+    return text;
+  }
+  return [
+    lines[0],
+    ...lines.slice(1).map((line) => line.trim() === "" ? "" : line.slice(indent))
+  ].join(`
+`);
+};
+var isJsxElement = (node) => node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement";
+var cellText = (value) => String(value ?? "").replaceAll(/\s*\n\s*/gu, " ").replaceAll("|", "\\|").trim();
+var cellCode = (value) => {
+  const text = cellText(value);
+  return text && !text.includes("`") ? `\`${text}\`` : text;
+};
+var typeTable = ({ children, props }) => {
+  const { type } = props;
+  if (type === null || typeof type !== "object") {
+    return null;
+  }
+  const entries = Object.entries(type);
+  const rows = entries.map(([name, info]) => {
+    const prop = cellCode(`${name}${info.required ? "" : "?"}`);
+    const typeCell = info.typeDescriptionLink ? `[${cellCode(info.type)}](${cellText(info.typeDescriptionLink)})` : cellCode(info.type);
+    const defaultCell = info.default === undefined ? "-" : cellCode(info.default);
+    const description = cellText([info.description, info.typeDescription].filter((part) => typeof part === "string" && part !== "").join(" "));
+    return `| ${prop} | ${typeCell} | ${defaultCell} | ${description} |`;
+  });
+  const table = rows.length > 0 ? [
+    "| Prop | Type | Default | Description |",
+    "| --- | --- | --- | --- |",
+    ...rows
+  ].join(`
+`) : "";
+  return [table, children].filter(Boolean).join(`
+
+`);
+};
+var callout = ({ children, props }) => {
+  const type = typeof props.type === "string" ? props.type : "info";
+  const label = typeof props.title === "string" && props.title !== "" ? props.title : type.charAt(0).toUpperCase() + type.slice(1);
+  if (!children) {
+    return `> **${label}**`;
+  }
+  const body = children.split(`
+`).map((line) => line.trim() === "" ? ">" : `> ${line}`).join(`
+`);
+  return `> **${label}**
+>
+${body}`;
+};
+var listItem = (index, content) => {
+  const marker = `${index}. `;
+  return content.split(`
+`).map((line, lineIndex) => {
+    if (lineIndex === 0) {
+      return `${marker}${line}`;
+    }
+    return line === "" ? "" : `    ${line}`;
+  }).join(`
+`);
+};
+var steps = ({ childComponents, children }) => {
+  const items = childComponents("Step");
+  if (items.length === 0) {
+    return children;
+  }
+  return items.map((step, index) => {
+    const title = typeof step.props.title === "string" && step.props.title !== "" ? `**${step.props.title}**` : "";
+    const content = [title, step.children].filter(Boolean).join(`
+
+`);
+    return listItem(index + 1, content);
+  }).join(`
+
+`);
+};
+var tabs = ({ childComponents, children }) => {
+  const items = childComponents("Tab");
+  if (items.length === 0) {
+    return children;
+  }
+  return items.map((tab, index) => {
+    const title = typeof tab.props.title === "string" && tab.props.title !== "" ? tab.props.title : `Tab ${index + 1}`;
+    return tab.children ? `**${title}**
+
+${tab.children}` : `**${title}**`;
+  }).join(`
+
+`);
+};
+var youtube = ({ props }) => {
+  let input = "";
+  if (typeof props.id === "string") {
+    input = props.id;
+  } else if (typeof props.url === "string") {
+    input = props.url;
+  }
+  const videoId = parseYouTubeId(input);
+  if (!videoId) {
+    return null;
+  }
+  const start = typeof props.start === "number" && props.start > 0 ? `&t=${Math.floor(props.start)}s` : "";
+  const title = typeof props.title === "string" && props.title !== "" ? props.title : "Watch on YouTube";
+  return `[${title}](https://www.youtube.com/watch?v=${videoId}${start})`;
+};
+var SERIALIZERS = {
+  Callout: callout,
+  Steps: steps,
+  Tabs: tabs,
+  TypeTable: typeTable,
+  YouTube: youtube
+};
+var escapeRegExp2 = (value) => value.replaceAll(/[$()*+.?[\\\]^{|}]/gu, String.raw`\$&`);
+var componentHint = (registry2) => new RegExp(`<(?:${Object.keys(registry2).map(escapeRegExp2).join("|")})[\\s/>]`, "u");
+var BUILT_IN_HINT = componentHint(SERIALIZERS);
+var renderChildren = (walk, node) => {
+  const children = (node.children ?? []).filter(hasOffsets);
+  const [first] = children;
+  if (!first) {
+    return "";
+  }
+  const start = first.position.start.offset;
+  const end = children.at(-1)?.position.end.offset ?? start;
+  const splices = [];
+  collectSplices(walk, children, splices);
+  const spliced = applySplices(walk.source.slice(start, end), splices.map((splice) => ({
+    ...splice,
+    end: splice.end - start,
+    start: splice.start - start
+  })));
+  return dedent(spliced).trim();
+};
+var serializeElement = (serializer, walk, node) => serializer({
+  ...readProps(node),
+  childComponents: (name) => (node.children ?? []).filter((child) => isJsxElement(child) && child.name === name).map((child) => ({
+    ...readProps(child),
+    children: renderChildren(walk, child)
+  })),
+  children: renderChildren(walk, node)
+});
+var collectSplices = (walk, nodes, out) => {
+  for (const node of nodes) {
+    const serializer = node.type === "mdxJsxFlowElement" && node.name ? walk.registry[node.name] : undefined;
+    if (serializer && hasOffsets(node)) {
+      const text = serializeElement(serializer, walk, node);
+      if (text !== null) {
+        out.push({
+          end: node.position.end.offset,
+          start: node.position.start.offset,
+          text
+        });
+        continue;
+      }
+    }
+    collectSplices(walk, node.children ?? [], out);
+  }
+};
+var downlevelComponents = (source, components) => {
+  const custom = components && Object.keys(components).length > 0;
+  const registry2 = custom ? { ...SERIALIZERS, ...components } : SERIALIZERS;
+  const hint = custom ? componentHint(registry2) : BUILT_IN_HINT;
+  if (!hint.test(source)) {
+    return source;
+  }
+  let tree;
+  try {
+    tree = mdxToMdast(source);
+  } catch {
+    return source;
+  }
+  const splices = [];
+  collectSplices({ registry: registry2, source }, tree.children ?? [], splices);
+  return splices.length > 0 ? applySplices(source, splices) : source;
+};
+
+// src/ai/visibility.ts
+var CODE_FENCE_BLOCK = /^(?<fence>`{3,}|~{3,})[^\n]*\n[\s\S]*?^\k<fence>[^\n]*(?=\n|$)/gmu;
+var FENCE_TOKEN = /\u0000blume-fence-(?<index>\d+)\u0000/gu;
+var visibilityBlock = (audience) => new RegExp(`<Visibility\\s+for\\s*=\\s*(?:"${audience}"|'${audience}')\\s*>(?<inner>[\\s\\S]*?)</Visibility\\s*>`, "gu");
+var BLOCKS = {
+  agents: visibilityBlock("agents"),
+  web: visibilityBlock("web")
+};
+var applyAudienceVisibility = (markdown, audience) => {
+  const fences = [];
+  const masked = markdown.replace(CODE_FENCE_BLOCK, (block) => {
+    fences.push(block);
+    return `\x00blume-fence-${fences.length - 1}\x00`;
+  });
+  let touched = false;
+  const filtered = masked.replaceAll(BLOCKS[audience === "agents" ? "web" : "agents"], () => {
+    touched = true;
+    return "";
+  }).replaceAll(BLOCKS[audience], (_match, inner) => {
+    touched = true;
+    return inner;
+  });
+  const tidied = touched ? filtered.replaceAll(/\n{3,}/gu, `
+
+`) : filtered;
+  return tidied.replaceAll(FENCE_TOKEN, (token, index) => fences[Number(index)] ?? token);
+};
+var applyAgentVisibility = (markdown) => applyAudienceVisibility(markdown, "agents");
+
 // src/ai/llms.ts
 var pageUrl = (route, site, base = "") => {
-  if (!site) {
-    return route;
+  const path = withBasePath(base, route);
+  return encodeURI(site ? `${site.replace(/\/$/u, "")}${path}` : path);
+};
+var eligiblePages = (project) => project.graph.pages.filter((page) => !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex) && (project.config.ai.llmsTxt.openapi || page.source.name !== "openapi"));
+var indexedNavigations = (project) => {
+  const { i18n } = project.config;
+  if (i18n) {
+    return i18n.locales.flatMap(({ code, label }) => {
+      const nav = project.graph.navigationByLocale[code];
+      if (!nav) {
+        return [];
+      }
+      return [{ label: code === i18n.defaultLocale ? undefined : label, nav }];
+    });
   }
-  return `${site.replace(/\/$/u, "")}${withBasePath(base, route)}`;
+  return [{ nav: project.graph.navigation }];
 };
-var orderedPages = (project) => [...project.graph.pages].filter((page) => !page.meta.draft).sort((a, b) => a.route.localeCompare(b.route));
 var buildIndex = (project) => {
   const { config } = project;
   const { site } = config.deployment;
-  const lines = [`# ${config.title}`];
-  if (config.description) {
-    lines.push("", `> ${config.description}`);
-  }
-  lines.push("", "## Docs", "");
-  for (const page of orderedPages(project)) {
-    const url = pageUrl(page.route, site, normalizeBasePath(config.deployment.base));
+  const base = normalizeBasePath(config.deployment.base);
+  const eligible = eligiblePages(project);
+  const byRoute = new Map(eligible.map((page) => [page.route, page]));
+  const seen = new Set;
+  const line = (page) => {
+    seen.add(page.route);
     const summary = page.description ? `: ${page.description}` : "";
-    lines.push(`- [${page.title}](${url})${summary}`);
+    return `- [${page.title}](${pageUrl(page.route, site, base)})${summary}`;
+  };
+  const renderLevel = (nodes, depth) => {
+    const list = [];
+    const groupBlocks = [];
+    for (const node of nodes) {
+      if (node.kind === "page") {
+        const page = byRoute.get(node.route);
+        if (page && !seen.has(page.route)) {
+          list.push(line(page));
+        }
+        continue;
+      }
+      const rootPage = node.route ? byRoute.get(node.route) : undefined;
+      const blocks2 = renderLevel(node.children, depth + 1);
+      if (rootPage && !seen.has(rootPage.route)) {
+        blocks2.unshift(line(rootPage));
+      }
+      if (blocks2.length > 0) {
+        groupBlocks.push(`${"#".repeat(Math.min(depth, 6))} ${node.label}`, ...blocks2);
+      }
+    }
+    return list.length > 0 ? [list.join(`
+`), ...groupBlocks] : groupBlocks;
+  };
+  const renderNav = (nav, depth) => {
+    const loose = nav.sidebar.filter((node) => node.kind === "page");
+    const groups = nav.sidebar.filter((node) => node.kind === "group");
+    const looseBlocks = renderLevel(loose, depth + 1);
+    return [
+      ...looseBlocks.length > 0 ? [`${"#".repeat(depth)} Docs`, ...looseBlocks] : [],
+      ...renderLevel(groups, depth)
+    ];
+  };
+  const blocks = [];
+  for (const { label, nav } of indexedNavigations(project)) {
+    if (label) {
+      const localized = renderNav(nav, 3);
+      if (localized.length > 0) {
+        blocks.push(`## ${label}`, ...localized);
+      }
+      continue;
+    }
+    blocks.push(...renderNav(nav, 2));
   }
-  return `${lines.join(`
+  const leftover = eligible.filter((page) => !seen.has(page.route)).toSorted((a, b) => a.route.localeCompare(b.route));
+  if (leftover.length > 0) {
+    blocks.push(blocks.length > 0 ? "## Other" : "## Docs", leftover.map(line).join(`
+`));
+  }
+  const header = config.description ? `# ${config.title}
+
+> ${config.description}` : `# ${config.title}`;
+  return `${[header, ...blocks].join(`
+
 `)}
 `;
 };
 var buildFull = async (project) => {
   const { config } = project;
-  const pages = orderedPages(project);
+  const pages = eligiblePages(project).toSorted((a, b) => a.route.localeCompare(b.route));
   const sections = await Promise.all(pages.map(async (page) => {
     const raw = await readEntryText(project, page);
-    const body = frontmatter_default(raw).content.trim();
+    const body = downlevelComponents(applyAgentVisibility(frontmatter_default(raw).content), config.ai.markdownComponents).trim();
     const url = pageUrl(page.route, config.deployment.site, normalizeBasePath(config.deployment.base));
     return [`# ${page.title}`, `Source: ${url}`, "", body].join(`
 `);
@@ -897,7 +1238,7 @@ import { existsSync as existsSync4 } from "node:fs";
 import { cp, mkdir as mkdir2, rm } from "node:fs/promises";
 import { dirname as dirname4, join as join6 } from "pathe";
 var ADAPTER_OUTPUT_PATHS = {
-  netlify: ".netlify",
+  netlify: ".netlify/v1",
   vercel: ".vercel/output"
 };
 var deployStaticDir = (config, context) => {
@@ -905,7 +1246,11 @@ var deployStaticDir = (config, context) => {
   if (output === "server" && adapter === "vercel") {
     return join6(context.root, ".vercel", "output", "static");
   }
-  return context.distDir ?? join6(context.root, "dist");
+  const dist = context.distDir ?? join6(context.root, "dist");
+  if (output === "server" && adapter === "node") {
+    return join6(dist, "client");
+  }
+  return dist;
 };
 var surfaceAdapterOutput = async (config, context) => {
   const { adapter, output } = config.deployment;
@@ -940,8 +1285,8 @@ var buildNetlifyRedirects = (redirects) => `${redirects.map((redirect) => `${red
 var buildVercelConfig = (redirects) => `${JSON.stringify({
   redirects: redirects.map((redirect) => ({
     destination: redirect.to,
-    permanent: redirect.status === 301 || redirect.status === 308,
-    source: redirect.from
+    source: redirect.from,
+    statusCode: redirect.status
   }))
 }, null, 2)}
 `;
@@ -986,7 +1331,71 @@ var buildRobots = (project) => {
 `;
 };
 
+// src/astro/pages.ts
+import { extname, relative as relative4 } from "pathe";
+import { glob, globSync } from "tinyglobby";
+var PAGE_GLOB = ["**/*.astro"];
+var toPageRoutes = (pagesRoot, files) => {
+  files.sort();
+  return files.map((file) => {
+    const rel = relative4(pagesRoot, file);
+    const withoutExt = rel.slice(0, rel.length - extname(rel).length);
+    const parts = withoutExt.split("/");
+    if (parts.at(-1) === "index") {
+      parts.pop();
+    }
+    const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
+    return { entrypoint: file, pattern };
+  });
+};
+var discoverPages = async (pagesRoot) => toPageRoutes(pagesRoot, await glob(PAGE_GLOB, { absolute: true, cwd: pagesRoot, onlyFiles: true }));
+var discoverPagesSync = (pagesRoot) => toPageRoutes(pagesRoot, globSync(PAGE_GLOB, { absolute: true, cwd: pagesRoot, onlyFiles: true }));
+var routeIsTaken = (pages, contentPages, route) => pages.some((page) => page.pattern === route) || contentPages.some((page) => page.route === route);
+var PRIVATE_SEGMENT = /^[._]/u;
+var staticSegments = (pattern) => {
+  const segments = pattern.split("/").filter(Boolean);
+  return segments.some((part) => PRIVATE_SEGMENT.test(part) || part.includes("[")) ? null : segments;
+};
+var customStaticRoutes = (pages) => {
+  const routes = new Set;
+  for (const { pattern } of pages) {
+    const segments = staticSegments(pattern);
+    if (segments !== null) {
+      routes.add(segments.length === 0 ? "/" : `/${segments.join("/")}`);
+    }
+  }
+  return [...routes];
+};
+var hasGeneratedChangelog = (project, userPages) => {
+  const hasChangelog = project.graph.pages.some((page) => page.contentType === "changelog" && !(page.meta.draft || page.meta.sidebar.hidden));
+  const hasChangelogSource = (project.config.content.sources ?? []).some((source) => source.type === "github-releases");
+  return (hasChangelog || hasChangelogSource) && !routeIsTaken(userPages, project.graph.pages, "/changelog");
+};
+var humanizeSegment = (segment) => segment.split(/[-_]/u).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+var customOgRoutes = (pages, siteTitle) => {
+  const seen = new Set;
+  const routes = [];
+  const collectRoute = (pattern) => {
+    const segments = staticSegments(pattern);
+    if (segments === null) {
+      return;
+    }
+    const slug = segments.length === 0 ? "index" : segments.join("/");
+    if (seen.has(slug)) {
+      return;
+    }
+    seen.add(slug);
+    const last = segments.at(-1);
+    routes.push({ slug, title: last ? humanizeSegment(last) : siteTitle });
+  };
+  for (const { pattern } of pages) {
+    collectRoute(pattern);
+  }
+  return routes;
+};
+
 // src/deploy/sitemap.ts
+var ERROR_ROUTES = new Set(["/404", "/500"]);
 var lastmodTag = (value) => {
   if (!value) {
     return "";
@@ -1001,13 +1410,29 @@ var buildSitemap = (project) => {
   }
   const base = site.replace(/\/$/u, "");
   const deployBase = normalizeBasePath(project.config.deployment.base);
+  const seen = new Set;
   const urls = [];
+  const pushUrl = (route, lastModified) => {
+    const loc = escapeXml(encodeURI(`${base}${route}`));
+    if (seen.has(loc)) {
+      return;
+    }
+    seen.add(loc);
+    urls.push(`  <url><loc>${loc}</loc>${lastmodTag(lastModified)}</url>`);
+  };
   for (const page of project.graph.pages) {
-    if (page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex) {
+    if (page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex || ERROR_ROUTES.has(page.route)) {
       continue;
     }
-    const loc = escapeXml(encodeURI(`${base}${withBasePath(deployBase, page.route)}`));
-    urls.push(`  <url><loc>${loc}</loc>${lastmodTag(page.lastModified)}</url>`);
+    pushUrl(withBasePath(deployBase, page.route), page.lastModified);
+  }
+  const userPages = project.context.pagesRoot ? discoverPagesSync(project.context.pagesRoot) : [];
+  const extraRoutes = customStaticRoutes(userPages).filter((route) => !ERROR_ROUTES.has(route));
+  if (hasGeneratedChangelog(project, userPages)) {
+    extraRoutes.push("/changelog");
+  }
+  for (const route of extraRoutes) {
+    pushUrl(withBasePath(deployBase, route));
   }
   urls.sort();
   return `<?xml version="1.0" encoding="UTF-8"?>
@@ -1055,6 +1480,7 @@ var ar = {
     send: "إرسال",
     title: "اسأل الذكاء الاصطناعي"
   },
+  banner: { dismiss: "إغلاق الإعلان" },
   feedback: {
     no: "لا",
     question: "هل كانت هذه الصفحة مفيدة؟",
@@ -1101,6 +1527,7 @@ var bg = {
     send: "Изпрати",
     title: "Попитай ИИ"
   },
+  banner: { dismiss: "Затваряне на съобщението" },
   feedback: {
     no: "Не",
     question: "Беше ли полезна тази страница?",
@@ -1147,6 +1574,7 @@ var bn = {
     send: "পাঠান",
     title: "AI-কে জিজ্ঞাসা করুন"
   },
+  banner: { dismiss: "ঘোষণা বন্ধ করুন" },
   feedback: {
     no: "না",
     question: "এই পৃষ্ঠাটি কি সহায়ক ছিল?",
@@ -1193,6 +1621,7 @@ var ca = {
     send: "Envia",
     title: "Pregunta a la IA"
   },
+  banner: { dismiss: "Tanca l'anunci" },
   feedback: {
     no: "No",
     question: "Aquesta pàgina t'ha estat útil?",
@@ -1239,6 +1668,7 @@ var cs = {
     send: "Odeslat",
     title: "Zeptat se AI"
   },
+  banner: { dismiss: "Zavřít oznámení" },
   feedback: {
     no: "Ne",
     question: "Byla tato stránka užitečná?",
@@ -1285,6 +1715,7 @@ var da = {
     send: "Send",
     title: "Spørg AI"
   },
+  banner: { dismiss: "Luk meddelelsen" },
   feedback: {
     no: "Nej",
     question: "Var denne side nyttig?",
@@ -1331,6 +1762,7 @@ var de = {
     send: "Senden",
     title: "KI fragen"
   },
+  banner: { dismiss: "Ankündigung schließen" },
   feedback: {
     no: "Nein",
     question: "War diese Seite hilfreich?",
@@ -1377,6 +1809,7 @@ var el = {
     send: "Αποστολή",
     title: "Ρωτήστε την AI"
   },
+  banner: { dismiss: "Κλείσιμο ανακοίνωσης" },
   feedback: {
     no: "Όχι",
     question: "Σας φάνηκε χρήσιμη αυτή η σελίδα;",
@@ -1423,6 +1856,7 @@ var es = {
     send: "Enviar",
     title: "Preguntar a la IA"
   },
+  banner: { dismiss: "Cerrar el anuncio" },
   feedback: {
     no: "No",
     question: "¿Te ha resultado útil esta página?",
@@ -1469,6 +1903,7 @@ var fa = {
     send: "ارسال",
     title: "از هوش مصنوعی بپرسید"
   },
+  banner: { dismiss: "بستن اطلاعیه" },
   feedback: {
     no: "خیر",
     question: "آیا این صفحه مفید بود؟",
@@ -1515,6 +1950,7 @@ var fi = {
     send: "Lähetä",
     title: "Kysy tekoälyltä"
   },
+  banner: { dismiss: "Sulje ilmoitus" },
   feedback: {
     no: "Ei",
     question: "Oliko tästä sivusta apua?",
@@ -1543,7 +1979,7 @@ var fr = {
   actions: {
     addToCursor: "Ajouter à Cursor",
     addToVscode: "Ajouter à VS Code",
-    askAI: "Demander à l'IA",
+    askAI: "Demander à l'IA à propos de cette page",
     connectMcp: "Se connecter à MCP",
     copied: "Copié !",
     copyClaudeCode: "Copier la commande Claude Code",
@@ -1561,6 +1997,7 @@ var fr = {
     send: "Envoyer",
     title: "Demander à l'IA"
   },
+  banner: { dismiss: "Fermer l'annonce" },
   feedback: {
     no: "Non",
     question: "Cette page vous a-t-elle été utile ?",
@@ -1607,6 +2044,7 @@ var he = {
     send: "שלח",
     title: "שאל את ה-AI"
   },
+  banner: { dismiss: "סגירת ההודעה" },
   feedback: {
     no: "לא",
     question: "האם העמוד הזה היה מועיל?",
@@ -1653,6 +2091,7 @@ var hi = {
     send: "भेजें",
     title: "AI से पूछें"
   },
+  banner: { dismiss: "घोषणा बंद करें" },
   feedback: {
     no: "नहीं",
     question: "क्या यह पेज सहायक था?",
@@ -1699,6 +2138,7 @@ var hr = {
     send: "Pošalji",
     title: "Pitaj AI"
   },
+  banner: { dismiss: "Zatvori obavijest" },
   feedback: {
     no: "Ne",
     question: "Je li vam ova stranica bila korisna?",
@@ -1745,6 +2185,7 @@ var hu = {
     send: "Küldés",
     title: "Kérdezd az AI-t"
   },
+  banner: { dismiss: "Közlemény bezárása" },
   feedback: {
     no: "Nem",
     question: "Hasznos volt ez az oldal?",
@@ -1791,6 +2232,7 @@ var id = {
     send: "Kirim",
     title: "Tanya AI"
   },
+  banner: { dismiss: "Tutup pengumuman" },
   feedback: {
     no: "Tidak",
     question: "Apakah halaman ini membantu?",
@@ -1837,6 +2279,7 @@ var it = {
     send: "Invia",
     title: "Chiedi all'IA"
   },
+  banner: { dismiss: "Chiudi l'annuncio" },
   feedback: {
     no: "No",
     question: "Questa pagina ti è stata utile?",
@@ -1883,6 +2326,7 @@ var ja = {
     send: "送信",
     title: "AI に質問"
   },
+  banner: { dismiss: "お知らせを閉じる" },
   feedback: {
     no: "いいえ",
     question: "このページは役に立ちましたか？",
@@ -1929,6 +2373,7 @@ var ko = {
     send: "보내기",
     title: "AI에게 질문"
   },
+  banner: { dismiss: "공지 닫기" },
   feedback: {
     no: "아니요",
     question: "이 페이지가 도움이 되었나요?",
@@ -1975,6 +2420,7 @@ var nl = {
     send: "Verzenden",
     title: "AI vragen"
   },
+  banner: { dismiss: "Aankondiging sluiten" },
   feedback: {
     no: "Nee",
     question: "Was deze pagina nuttig?",
@@ -2021,6 +2467,7 @@ var no = {
     send: "Send",
     title: "Spør AI"
   },
+  banner: { dismiss: "Lukk kunngjøringen" },
   feedback: {
     no: "Nei",
     question: "Var denne siden nyttig?",
@@ -2067,6 +2514,7 @@ var pl = {
     send: "Wyślij",
     title: "Zapytaj AI"
   },
+  banner: { dismiss: "Zamknij ogłoszenie" },
   feedback: {
     no: "Nie",
     question: "Czy ta strona była pomocna?",
@@ -2113,6 +2561,7 @@ var ptBR = {
     send: "Enviar",
     title: "Perguntar à IA"
   },
+  banner: { dismiss: "Fechar o anúncio" },
   feedback: {
     no: "Não",
     question: "Esta página foi útil?",
@@ -2159,6 +2608,7 @@ var pt = {
     send: "Enviar",
     title: "Perguntar à IA"
   },
+  banner: { dismiss: "Fechar o anúncio" },
   feedback: {
     no: "Não",
     question: "Esta página foi útil?",
@@ -2205,6 +2655,7 @@ var ro = {
     send: "Trimite",
     title: "Întreabă AI"
   },
+  banner: { dismiss: "Închide anunțul" },
   feedback: {
     no: "Nu",
     question: "Ți-a fost utilă această pagină?",
@@ -2251,6 +2702,7 @@ var ru = {
     send: "Отправить",
     title: "Спросить ИИ"
   },
+  banner: { dismiss: "Закрыть объявление" },
   feedback: {
     no: "Нет",
     question: "Эта страница была полезной?",
@@ -2297,6 +2749,7 @@ var sk = {
     send: "Odoslať",
     title: "Opýtať sa AI"
   },
+  banner: { dismiss: "Zavrieť oznámenie" },
   feedback: {
     no: "Nie",
     question: "Bola táto stránka užitočná?",
@@ -2343,6 +2796,7 @@ var sr = {
     send: "Пошаљи",
     title: "Питајте AI"
   },
+  banner: { dismiss: "Затвори обавештење" },
   feedback: {
     no: "Не",
     question: "Да ли вам је ова страница помогла?",
@@ -2389,6 +2843,7 @@ var sv = {
     send: "Skicka",
     title: "Fråga AI"
   },
+  banner: { dismiss: "Stäng meddelandet" },
   feedback: {
     no: "Nej",
     question: "Var den här sidan till hjälp?",
@@ -2435,6 +2890,7 @@ var th = {
     send: "ส่ง",
     title: "ถาม AI"
   },
+  banner: { dismiss: "ปิดประกาศ" },
   feedback: {
     no: "ไม่",
     question: "หน้านี้มีประโยชน์หรือไม่?",
@@ -2481,6 +2937,7 @@ var tr = {
     send: "Gönder",
     title: "Yapay zekâya sor"
   },
+  banner: { dismiss: "Duyuruyu kapat" },
   feedback: {
     no: "Hayır",
     question: "Bu sayfa yardımcı oldu mu?",
@@ -2527,6 +2984,7 @@ var uk = {
     send: "Надіслати",
     title: "Запитати ШІ"
   },
+  banner: { dismiss: "Закрити оголошення" },
   feedback: {
     no: "Ні",
     question: "Чи була ця сторінка корисною?",
@@ -2573,6 +3031,7 @@ var vi = {
     send: "Gửi",
     title: "Hỏi AI"
   },
+  banner: { dismiss: "Đóng thông báo" },
   feedback: {
     no: "Không",
     question: "Trang này có hữu ích không?",
@@ -2619,6 +3078,7 @@ var zhTW = {
     send: "傳送",
     title: "向 AI 提問"
   },
+  banner: { dismiss: "關閉公告" },
   feedback: {
     no: "沒有幫助",
     question: "這個頁面有幫助嗎？",
@@ -2665,6 +3125,7 @@ var zh = {
     send: "发送",
     title: "向 AI 提问"
   },
+  banner: { dismiss: "关闭公告" },
   feedback: {
     no: "没有帮助",
     question: "这个页面有帮助吗？",
@@ -2903,9 +3364,16 @@ var toPlainText = (markdown) => {
 };
 var buildCrumbIndex = (sidebar) => {
   const index = new Map;
+  const groupRoutes = new Map;
   const walk = (nodes, trail) => {
     for (const node of nodes) {
       if (node.kind === "group") {
+        if (node.route && !groupRoutes.has(node.route)) {
+          groupRoutes.set(node.route, {
+            breadcrumb: [...trail, node.label],
+            section: node.label
+          });
+        }
         walk(node.children, [...trail, node.label]);
       } else if (node.route) {
         index.set(node.route, {
@@ -2916,6 +3384,11 @@ var buildCrumbIndex = (sidebar) => {
     }
   };
   walk(sidebar, []);
+  for (const [route, crumbs] of groupRoutes) {
+    if (!index.has(route)) {
+      index.set(route, crumbs);
+    }
+  }
   return index;
 };
 var buildSearchDocuments = async (project, options) => {
@@ -2939,7 +3412,8 @@ var buildSearchDocuments = async (project, options) => {
     const page = pageById.get(route.id);
     const raw = page ? await readEntryText(project, page) : "";
     const source = raw ? frontmatter_default(raw).content : "";
-    const body = options?.content === "markdown" ? source.trim() : toPlainText(source);
+    const visible = applyAudienceVisibility(source, options?.audience ?? "web");
+    const body = options?.content === "markdown" ? visible.trim() : toPlainText(visible);
     const tags = page?.meta?.search?.tags;
     const crumb = crumbs.get(route.path);
     return {
@@ -3235,10 +3709,11 @@ var updateDevLockPort = (outDir, port) => {
   }
 };
 var describeDevLock = (lock) => lock.port === undefined ? "" : ` at http://localhost:${lock.port}`;
-var refuseIfDevRunning = (root, action, runtimeDir) => {
-  const lock = readDevLock(resolveRuntimeDir(root, runtimeDir));
+var refuseIfDevRunning = (root, action, options = {}) => {
+  const lock = readDevLock(resolveRuntimeDir(root, options.runtimeDir));
   if (lock) {
-    logger.error(`A \`blume dev\` server is running${describeDevLock(lock)}; ${action} would corrupt its .blume runtime. Reuse that server, stop it first, or re-run with --isolated to build/verify against .blume-verify without touching it.`);
+    const remedies = options.isolatedHint ? "Reuse that server, stop it first, or re-run with --isolated to build/verify against .blume-verify without touching it." : "Reuse that server or stop it first.";
+    logger.error(`A \`blume dev\` server is running${describeDevLock(lock)}; ${action} would corrupt its .blume runtime. ${remedies}`);
     process.exit(1);
   }
 };
@@ -3262,6 +3737,7 @@ import { glob as glob5 } from "tinyglobby";
 // src/ai/ask-data.ts
 var buildAskData = async (project) => {
   const documents = await buildSearchDocuments(project, {
+    audience: "agents",
     content: "markdown",
     includeWhenDisabled: true
   });
@@ -3332,6 +3808,7 @@ var askBackendRuntimeDep = (ask) => {
 
 // src/ai/markdown.ts
 import { readFile as readFile4 } from "node:fs/promises";
+var agentMarkdown = (entry) => entry.md ?? entry.mdx;
 var buildRawMarkdown = async (project) => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
   const readRoute = async (route) => {
@@ -3341,17 +3818,29 @@ var buildRawMarkdown = async (project) => {
     }
     return route.sourcePath ? await readFile4(route.sourcePath, "utf-8") : "";
   };
-  const entries = await Promise.all(project.manifest.routes.map(async (route) => [route.path, await readRoute(route)]));
+  const entries = await Promise.all(project.manifest.routes.map(async (route) => {
+    const source = applyAgentVisibility(await readRoute(route));
+    const md = downlevelComponents(source, project.config.ai.markdownComponents);
+    const entry = md === source ? { mdx: source } : { md, mdx: source };
+    return [route.path, entry];
+  }));
   return Object.fromEntries(entries);
 };
 
 // src/ai/mcp/data.ts
 var buildMcpData = async (project) => {
   const { config, graph, manifest } = project;
-  const [documents, pages] = await Promise.all([
-    buildSearchDocuments(project, { includeWhenDisabled: true }),
+  const [documents, rawMarkdown] = await Promise.all([
+    buildSearchDocuments(project, {
+      audience: "agents",
+      includeWhenDisabled: true
+    }),
     buildRawMarkdown(project)
   ]);
+  const pages = Object.fromEntries(Object.entries(rawMarkdown).map(([route, entry]) => [
+    route,
+    agentMarkdown(entry)
+  ]));
   const descriptionById = new Map(graph.pages.map((page) => [page.id, page.description]));
   const routes = [];
   for (const route of manifest.routes) {
@@ -3368,6 +3857,7 @@ var buildMcpData = async (project) => {
     });
   }
   return {
+    base: normalizeBasePath(config.deployment.base),
     documents: documents.map((doc) => ({
       content: doc.content,
       description: doc.description,
@@ -3414,7 +3904,10 @@ var MCP_TOOLS = [
 ];
 
 // src/ai/mcp/discovery.ts
-var serverUrl = (input) => input.site ? `${input.site.replace(/\/+$/u, "")}${input.route}` : input.route;
+var serverUrl = (input) => {
+  const path = withBasePath(input.base, input.route);
+  return input.site ? `${input.site.replace(/\/+$/u, "")}${path}` : path;
+};
 var buildMcpDiscovery = (input) => ({
   servers: [
     {
@@ -3504,7 +3997,7 @@ var validateUsedComponents = (pages, extraTags, registryNames) => {
 
 // src/core/component-overrides.ts
 import { existsSync as existsSync7 } from "node:fs";
-import { dirname as dirname5, extname, isAbsolute as isAbsolute2, resolve as resolve3 } from "pathe";
+import { dirname as dirname5, extname as extname2, isAbsolute as isAbsolute2, resolve as resolve3 } from "pathe";
 import ts from "typescript";
 var GROUPS = ["mdx", "layout", "islands"];
 var GROUP_SET = new Set(GROUPS);
@@ -3603,17 +4096,17 @@ var probeExtension = (base) => {
   return null;
 };
 var toImport = (specifier, imported, dir) => {
-  const relative4 = specifier.startsWith(".") || isAbsolute2(specifier);
+  const relative5 = specifier.startsWith(".") || isAbsolute2(specifier);
   let path = specifier;
-  let extension = extname(specifier).slice(1).toLowerCase();
-  if (relative4) {
+  let extension = extname2(specifier).slice(1).toLowerCase();
+  if (relative5) {
     const absolute = isAbsolute2(specifier) ? specifier : resolve3(dir, specifier);
     if (extension) {
       path = absolute;
     } else {
       const probed = probeExtension(absolute);
       path = probed ?? absolute;
-      extension = probed ? extname(probed).slice(1).toLowerCase() : "";
+      extension = probed ? extname2(probed).slice(1).toLowerCase() : "";
     }
   }
   return {
@@ -3779,14 +4272,20 @@ var uiStringsObject = z.object({
     connectMcp: z.string().default("Connect to MCP"),
     copied: z.string().default("Copied!"),
     copyClaudeCode: z.string().default("Copy Claude Code command"),
+    copyCode: z.string().default("Copy code"),
     copyCodex: z.string().default("Copy Codex command"),
     copyMarkdown: z.string().default("Copy as Markdown"),
     copyServerUrl: z.string().default("Copy server URL"),
     edit: z.string().default("Edit on GitHub"),
+    export: z.string().default("Export"),
+    exportEpub: z.string().default("Export to EPUB"),
+    exportPdf: z.string().default("Export to PDF"),
+    generating: z.string().default("Generating…"),
     openInChat: z.string().default("Open in chat"),
     scrollToTop: z.string().default("Scroll to top")
   }).default({}),
   ask: z.object({
+    ai: z.string().default("AI"),
     clear: z.string().default("Clear conversation"),
     close: z.string().default("Close"),
     copy: z.string().default("Copy conversation"),
@@ -3796,7 +4295,17 @@ var uiStringsObject = z.object({
     placeholder: z.string().default("Ask a question…"),
     send: z.string().default("Send"),
     tip: z.string().default("Tip: You can open and close chat with"),
-    title: z.string().default("Ask AI")
+    title: z.string().default("Ask AI"),
+    you: z.string().default("You")
+  }).default({}),
+  banner: z.object({
+    dismiss: z.string().default("Dismiss announcement")
+  }).default({}),
+  changelog: z.object({
+    showReleases: z.string().default("Show {version} releases")
+  }).default({}),
+  content: z.object({
+    diagramError: z.string().default("Could not render this diagram.")
   }).default({}),
   feedback: z.object({
     no: z.string().default("No"),
@@ -3808,6 +4317,18 @@ var uiStringsObject = z.object({
     label: z.string().default("Language"),
     untranslated: z.string().default("Not translated")
   }).default({}),
+  nav: z.object({
+    back: z.string().default("Back"),
+    closeNavigation: z.string().default("Close navigation"),
+    deprecated: z.string().default("deprecated"),
+    featured: z.string().default("Featured"),
+    githubRepository: z.string().default("GitHub repository"),
+    navigation: z.string().default("Navigation"),
+    primary: z.string().default("Primary"),
+    sections: z.string().default("Sections"),
+    toggleNavigation: z.string().default("Toggle navigation"),
+    toggleTheme: z.string().default("Toggle color theme")
+  }).default({}),
   notFound: z.object({
     description: z.string().default("We couldn't find the page you're looking for."),
     home: z.string().default("Back to home"),
@@ -3821,11 +4342,19 @@ var uiStringsObject = z.object({
   }).default({}),
   search: z.object({
     allLanguages: z.string().default("All languages"),
+    askAi: z.string().default("Ask AI"),
+    askAiHint: z.string().default("Get an instant answer from AI"),
     button: z.string().default("Search"),
     devOnly: z.string().default("Search is available in the production build."),
+    error: z.string().default("Something went wrong. Please try again."),
     label: z.string().default("Search docs"),
+    navigate: z.string().default("navigate"),
     noResults: z.string().default("No results found."),
-    placeholder: z.string().default("Search documentation…")
+    open: z.string().default("open"),
+    placeholder: z.string().default("Search documentation…"),
+    popular: z.string().default("Popular"),
+    preview: z.string().default("preview"),
+    results: z.string().default("Results")
   }).default({}),
   toc: z.object({
     title: z.string().default("On this page")
@@ -4060,7 +4589,7 @@ var sourcesOf = (block) => {
   }
   return sources;
 };
-var referencesFor = (kind, block, defaultLabel, renderer, display) => {
+var referencesFor = (kind, block, defaultLabel, renderer, display, basePath) => {
   if (!block.enabled) {
     return [];
   }
@@ -4078,6 +4607,7 @@ var referencesFor = (kind, block, defaultLabel, renderer, display) => {
       route = normalizeRoute(`${base}/${suffix || index + 1}`);
     }
     return {
+      basePath,
       display,
       kind,
       label,
@@ -4094,8 +4624,8 @@ var resolveReferences = (config) => [
   ...referencesFor("openapi", config.openapi, "API Reference", config.openapi.renderer, {
     codeSamples: config.openapi.codeSamples,
     expandSchemas: config.openapi.expandSchemas
-  }),
-  ...referencesFor("asyncapi", config.asyncapi, "Events", "scalar", NO_DISPLAY)
+  }, config.basePath),
+  ...referencesFor("asyncapi", config.asyncapi, "Events", "scalar", NO_DISPLAY, config.basePath)
 ];
 var referenceTabs = (config) => resolveReferences(config).map((ref) => ({
   label: ref.label,
@@ -4105,10 +4635,11 @@ var blumeReferenceOf = (ref, seen, usedSlugs) => {
   if (ref.kind !== "openapi" || ref.renderer !== "blume") {
     return null;
   }
-  if (seen.has(ref.route)) {
+  const kept = seen.get(ref.route);
+  if (kept) {
+    (kept.collisions ??= []).push(`Two API reference sources resolve to ${ref.route}; keeping the first.`);
     return null;
   }
-  seen.add(ref.route);
   let { slug } = ref;
   let n = 2;
   while (usedSlugs.has(slug)) {
@@ -4116,10 +4647,12 @@ var blumeReferenceOf = (ref, seen, usedSlugs) => {
     n += 1;
   }
   usedSlugs.add(slug);
-  return slug === ref.slug ? ref : { ...ref, slug };
+  const accepted = slug === ref.slug ? ref : { ...ref, slug };
+  seen.set(ref.route, accepted);
+  return accepted;
 };
 var blumeReferences = (config) => {
-  const seen = new Set;
+  const seen = new Map;
   const usedSlugs = new Set;
   const result = [];
   for (const ref of resolveReferences(config)) {
@@ -4243,9 +4776,14 @@ var extractOperations = (document, baseRoute) => {
   const tagsSeen = new Set;
   const tagMeta = new Map((document.tags ?? []).map((tag) => [tag.name, tag.description ?? ""]));
   const seen = new Set;
+  const warnings = [];
   for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
     const item = rawItem;
-    if (!item || "$ref" in item) {
+    if (!item) {
+      continue;
+    }
+    if ("$ref" in item) {
+      warnings.push(`Path "${path}" is a $ref to a shared path item; referenced path items are not resolved, so its operations are missing from the reference. Inline the path item under "paths" to render it.`);
       continue;
     }
     for (const method of HTTP_METHODS) {
@@ -4283,7 +4821,7 @@ var extractOperations = (document, baseRoute) => {
     name,
     slug: slugify2(name) || "operations"
   }));
-  return { operations, tags };
+  return { operations, tags, warnings };
 };
 
 // src/openapi/parse.ts
@@ -4307,6 +4845,13 @@ var PROXY_ENV_VARS = [
   "ALL_PROXY",
   "all_proxy"
 ];
+
+class InvalidSpecError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidSpecError";
+  }
+}
 var proxyInstalled = false;
 var ensureProxyDispatcher = async () => {
   if (proxyInstalled || !PROXY_ENV_VARS.some((name) => process.env[name])) {
@@ -4417,6 +4962,9 @@ var parseSpec = async (spec, root, options = {}) => {
   const { text, warnings } = await readSpecText(spec, root, options);
   const normalized = normalize2(text);
   const { specification } = upgrade(normalized);
+  if (specification === null || typeof specification !== "object") {
+    throw new InvalidSpecError(`${spec} is not a valid OpenAPI document (expected a YAML or JSON object).`);
+  }
   return { document: specification, warnings };
 };
 
@@ -4533,7 +5081,11 @@ var openApiSource = (references, ctx) => {
   const loadReference = async (reference) => {
     try {
       const { document, warnings } = await parseSpec(reference.spec, ctx.projectRoot, { cacheDir: ctx.cacheDir, refresh: ctx.refresh });
-      const { operations, tags } = extractOperations(document, reference.route);
+      const {
+        operations,
+        tags,
+        warnings: extractWarnings
+      } = extractOperations(document, reference.route);
       const info = document.info ?? { title: reference.label, version: "" };
       const spec = {
         codeSamples: reference.display.codeSamples,
@@ -4541,7 +5093,13 @@ var openApiSource = (references, ctx) => {
         document,
         expandSchemas: reference.display.expandSchemas,
         label: reference.label,
-        operations: Object.fromEntries(operations.map((operation) => [operation.key, operation])),
+        operations: Object.fromEntries(operations.map((operation) => [
+          operation.key,
+          {
+            ...operation,
+            route: withBasePath(reference.basePath, operation.route)
+          }
+        ])),
         route: reference.route,
         slug: reference.slug,
         tags,
@@ -4549,11 +5107,26 @@ var openApiSource = (references, ctx) => {
         version: info.version ?? ""
       };
       return {
-        diagnostics: warnings.map((message) => ({
-          code: "BLUME_OPENAPI_STALE",
-          message,
-          severity: "warning"
-        })),
+        diagnostics: [
+          ...warnings.map((message) => ({
+            code: "BLUME_OPENAPI_STALE",
+            message,
+            severity: "warning"
+          })),
+          ...extractWarnings.map((message) => ({
+            code: "BLUME_OPENAPI_REF_PATH_ITEM",
+            message: `In OpenAPI spec "${reference.spec}": ${message}`,
+            severity: "warning"
+          })),
+          ...operations.length === 0 ? [
+            {
+              code: "BLUME_OPENAPI_EMPTY",
+              message: `OpenAPI spec "${reference.spec}" for ${reference.route} declares no operations; its API reference is empty.`,
+              severity: "warning",
+              suggestion: "Check the spec points at an OpenAPI document with operations under `paths`."
+            }
+          ] : []
+        ],
         entries: specEntries(spec, operations),
         slug: reference.slug,
         spec
@@ -4563,14 +5136,18 @@ var openApiSource = (references, ctx) => {
         code: "BLUME_OPENAPI_UNAVAILABLE",
         message: `Could not load OpenAPI spec "${reference.spec}" for ${reference.route} (${error.message}); its reference pages were skipped.`,
         severity: ctx.mode === "build" ? "error" : "warning",
-        suggestion: "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY."
+        suggestion: error instanceof InvalidSpecError ? "Point the spec at an OpenAPI document (a YAML or JSON file with an object at the top level)." : "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY."
       };
     }
   };
   const load2 = async () => {
     const results = await Promise.all(references.map(loadReference));
     const entries = [];
-    const diagnostics = [];
+    const diagnostics = references.flatMap((reference) => (reference.collisions ?? []).map((message) => ({
+      code: "BLUME_OPENAPI_ROUTE_COLLISION",
+      message,
+      severity: "warning"
+    })));
     const data = {};
     for (const result of results) {
       if ("severity" in result) {
@@ -4596,8 +5173,8 @@ var openApiSource = (references, ctx) => {
 // src/core/sources/filesystem.ts
 import { existsSync as existsSync8, watch as fsWatch } from "node:fs";
 import { readFile as readFile7 } from "node:fs/promises";
-import { extname as extname2, isAbsolute as isAbsolute4, join as join12, relative as relative4, resolve as resolve4 } from "pathe";
-import { glob } from "tinyglobby";
+import { extname as extname3, isAbsolute as isAbsolute4, join as join12, relative as relative5, resolve as resolve4 } from "pathe";
+import { glob as glob2 } from "tinyglobby";
 
 // src/core/sources/watch.ts
 var BLUME_IGNORE_DIRS = [
@@ -4627,7 +5204,7 @@ var ignoringWatchListener = (onChange, ignoreDirs = BLUME_WATCH_IGNORE_DIRS) =>
 var filesystemSource = (options) => {
   const contentRoot = isAbsolute4(options.root) ? options.root : join12(resolve4(options.projectRoot), options.root);
   const load2 = async () => {
-    const files = await glob(options.include, {
+    const files = await glob2(options.include, {
       absolute: true,
       cwd: contentRoot,
       ignore: [...options.exclude, ...baselineScanIgnore()],
@@ -4636,13 +5213,14 @@ var filesystemSource = (options) => {
     files.sort();
     const entries = await Promise.all(files.map(async (file) => {
       const source = await readFile7(file, "utf-8");
-      const ext = extname2(file).toLowerCase();
+      const ext = extname3(file).toLowerCase();
       const format = ext === ".mdx" ? "mdx" : "md";
       const parsed = frontmatter_default(source);
       return {
         body: { format, text: parsed.content },
         data: parsed.data,
-        ref: relative4(contentRoot, file),
+        raw: source,
+        ref: relative5(contentRoot, file),
         sourcePath: file
       };
     }));
@@ -4878,14 +5456,9 @@ var mdxRemoteSource = (options, ctx) => {
   const doFetch = options.fetchImpl ?? globalThis.fetch;
   const cache = snapshotCache(ctx.cacheDir);
   let snapshot = new Map;
-  const enumerate = async () => {
-    if (options.github) {
-      return await enumerateGithub(options.github, options.include, doFetch);
-    }
-    if (options.files && options.url) {
-      const base = options.url.replace(/\/$/u, "");
-      const refs = options.files.flatMap((ref) => matchesInclude(ref, options.include) ? [{ editUrl: `${base}/${ref}`, fetchUrl: `${base}/${ref}`, ref }] : []);
-      return { refs, truncated: false };
+  const assertConfigured = () => {
+    if (options.github || options.files && options.url) {
+      return;
     }
     throw new BlumeError({
       code: "BLUME_SOURCE_MISCONFIGURED",
@@ -4893,6 +5466,14 @@ var mdxRemoteSource = (options, ctx) => {
       severity: "error"
     });
   };
+  const enumerate = async () => {
+    if (options.github) {
+      return await enumerateGithub(options.github, options.include, doFetch);
+    }
+    const base = (options.url ?? "").replace(/\/$/u, "");
+    const refs = (options.files ?? []).flatMap((ref) => matchesInclude(ref, options.include) ? [{ editUrl: `${base}/${ref}`, fetchUrl: `${base}/${ref}`, ref }] : []);
+    return { refs, truncated: false };
+  };
   const fetchEntry = async (item) => {
     const res = await doFetch(item.fetchUrl, {
       headers: githubHeaders2(item.fetchUrl)
@@ -4913,6 +5494,7 @@ var mdxRemoteSource = (options, ctx) => {
     };
   };
   const load2 = async (refresh = ctx.refresh ?? true) => {
+    assertConfigured();
     const skipped = [];
     const result = await loadWithCache(options.name, cache, async () => {
       const { refs, truncated } = await enumerate();
@@ -4973,22 +5555,22 @@ import { join as join14 } from "pathe";
 
 // src/core/sources/assets.ts
 import { mkdir as mkdir5, writeFile as writeFile5 } from "node:fs/promises";
-import { extname as extname3, join as join13 } from "pathe";
+import { extname as extname4, join as join13 } from "pathe";
 var MD_IMAGE = /!\[(?<alt>[^\]]*)\]\((?<url>[^)\s]+)\)/gu;
 var REMOTE = /^https?:\/\//u;
 var SAFE_EXT = /^\.[a-z0-9]+$/iu;
-var CODE_FENCE_BLOCK = /^(?<fence>`{3,}|~{3,})[^\n]*\n[\s\S]*?^\k<fence>[^\n]*(?=\n|$)/gmu;
-var FENCE_TOKEN = /\u0000blume-fence-(?<index>\d+)\u0000/gu;
+var CODE_FENCE_BLOCK2 = /^(?<fence>`{3,}|~{3,})[^\n]*\n[\s\S]*?^\k<fence>[^\n]*(?=\n|$)/gmu;
+var FENCE_TOKEN2 = /\u0000blume-fence-(?<index>\d+)\u0000/gu;
 var extFor = (url) => {
   const clean = url.split("?")[0] ?? url;
-  const ext = extname3(clean);
+  const ext = extname4(clean);
   return SAFE_EXT.test(ext) ? ext.toLowerCase() : ".png";
 };
 var materializeAssets = async (markdown, ctx) => {
   const doFetch = ctx.fetchImpl ?? globalThis.fetch;
   const diagnostics = [];
   const fences = [];
-  const masked = markdown.replace(CODE_FENCE_BLOCK, (block) => {
+  const masked = markdown.replace(CODE_FENCE_BLOCK2, (block) => {
     fences.push(block);
     return `\x00blume-fence-${fences.length - 1}\x00`;
   });
@@ -5007,7 +5589,7 @@ var materializeAssets = async (markdown, ctx) => {
         throw new Error(`${res.status}`);
       }
       const bytes = new Uint8Array(await res.arrayBuffer());
-      const file = `${hashText(url)}${extFor(url)}`;
+      const file = `${hashText(url.split("?")[0] ?? url)}${extFor(url)}`;
       await mkdir5(ctx.assetsDir, { recursive: true });
       await writeFile5(join13(ctx.assetsDir, file), bytes);
       rewrites.set(url, `${ctx.assetsBaseUrl}/${file}`);
@@ -5022,14 +5604,14 @@ var materializeAssets = async (markdown, ctx) => {
   const rewritten = masked.replaceAll(MD_IMAGE, (match, alt, url) => {
     const local = rewrites.get(url);
     return local ? `![${alt}](${local})` : match;
-  }).replaceAll(FENCE_TOKEN, (token, index) => fences[Number(index)] ?? token);
+  }).replaceAll(FENCE_TOKEN2, (token, index) => fences[Number(index)] ?? token);
   return { diagnostics, markdown: rewritten };
 };
 
 // src/core/sources/normalize.ts
 import { existsSync as existsSync9, readFileSync as readFileSync3 } from "node:fs";
 import GithubSlugger from "github-slugger";
-import { extname as extname4 } from "pathe";
+import { extname as extname5 } from "pathe";
 
 // src/core/schema.ts
 import { z as z2 } from "zod";
@@ -5503,7 +6085,16 @@ var aiConfigSchema = z2.strictObject({
       });
     }
   }).optional(),
-  llmsTxt: z2.boolean().default(true)
+  llmsTxt: z2.union([
+    z2.boolean(),
+    z2.strictObject({
+      enabled: z2.boolean().default(true),
+      openapi: z2.boolean().default(true)
+    })
+  ]).default(true).transform((value) => typeof value === "boolean" ? { enabled: value, openapi: true } : value),
+  markdownComponents: z2.record(z2.custom((value) => typeof value === "function", {
+    message: "Expected a serializer function."
+  })).default({})
 });
 var featuredLinkSchema = z2.strictObject({
   href: z2.string(),
@@ -5534,7 +6125,7 @@ var mcpConfigSchema = z2.strictObject({
   enabled: z2.boolean().default(false),
   instructions: z2.string().optional(),
   name: z2.string().optional(),
-  route: z2.string().default("/mcp")
+  route: z2.string().default("/mcp").transform(normalizeRoute)
 });
 var localeSchema = z2.strictObject({
   code: z2.string().min(1),
@@ -5751,7 +6342,7 @@ var addRouteSegment = (part, segments, groups) => {
   segments.push(clean);
 };
 var mapRoute = (relativePath) => {
-  const withoutExt = relativePath.slice(0, relativePath.length - extname4(relativePath).length);
+  const withoutExt = relativePath.slice(0, relativePath.length - extname5(relativePath).length);
   const rawParts = withoutExt.split("/");
   const segments = [];
   const groups = [];
@@ -5761,41 +6352,78 @@ var mapRoute = (relativePath) => {
   const route = segments.length === 0 ? "/" : `/${segments.join("/")}`;
   return { groups, route, segments };
 };
-var CODE_FENCE2 = /^```/u;
-var ATX_HEADING = /^(?<hashes>#{1,6})\s+(?<text>.+?)(?:\s+#+)?\s*$/u;
-var scanHeadingLine = (line, inFence, slugger, headings) => {
-  if (CODE_FENCE2.test(line.trimStart())) {
-    return !inFence;
+var CODE_FENCE2 = /^(?<delimiter>```|~~~)/u;
+var nextFenceState = (line, fence) => {
+  const delimiter = line.trimStart().match(CODE_FENCE2)?.groups?.delimiter;
+  if (delimiter === undefined) {
+    return fence;
+  }
+  if (fence === null) {
+    return delimiter;
+  }
+  return fence === delimiter ? null : fence;
+};
+var ATX_HEADING = /^ {0,3}(?<hashes>#{1,6})\s+(?<text>.+?)(?:\s+#+)?\s*$/u;
+var SETEXT_UNDERLINE = /^ {0,3}(?<marker>=+|-+)\s*$/u;
+var PARAGRAPH_INTERRUPT = /^ {0,3}(?:[-+*][ \t]|\d{1,9}[.)][ \t]|>)/u;
+var THEMATIC_BREAK = /^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})$/u;
+var FRONT_MATTER_CLOSE = /^(?:-{3}|\.{3})\s*$/u;
+var linesWithoutFrontMatter = (body) => {
+  const lines = body.split(`
+`);
+  if (!/^-{3}\s*$/u.test(lines[0] ?? "")) {
+    return lines;
   }
-  if (inFence) {
-    return inFence;
+  const close = lines.findIndex((line, index) => index > 0 && FRONT_MATTER_CLOSE.test(line));
+  return close === -1 ? lines : lines.slice(close + 1);
+};
+var scanHeadingLine = (line, state, slugger, headings) => {
+  const next = nextFenceState(line, state.fence);
+  if (state.fence !== null || next !== null) {
+    state.fence = next;
+    state.paragraph = [];
+    return;
   }
-  const match = line.match(ATX_HEADING);
-  if (match?.groups) {
-    const depth = match.groups.hashes?.length ?? 1;
-    const text = (match.groups.text ?? "").trim();
+  const atx = line.match(ATX_HEADING);
+  if (atx?.groups) {
+    const depth = atx.groups.hashes?.length ?? 1;
+    const text = (atx.groups.text ?? "").trim();
     headings.push({ depth, slug: slugger.slug(text), text });
+    state.paragraph = [];
+    return;
+  }
+  const setext = line.match(SETEXT_UNDERLINE);
+  if (setext?.groups && state.paragraph.length > 0) {
+    const text = state.paragraph.join(" ").trim();
+    headings.push({
+      depth: setext.groups.marker?.startsWith("=") ? 1 : 2,
+      slug: slugger.slug(text),
+      text
+    });
+    state.paragraph = [];
+    return;
   }
-  return inFence;
+  if (line.trim() === "" || THEMATIC_BREAK.test(line) || PARAGRAPH_INTERRUPT.test(line)) {
+    state.paragraph = [];
+    return;
+  }
+  state.paragraph.push(line.trim());
 };
 var extractHeadings = (body) => {
   const headings = [];
   const slugger = new GithubSlugger;
-  let inFence = false;
-  for (const line of body.split(`
-`)) {
-    inFence = scanHeadingLine(line, inFence, slugger, headings);
+  const state = { fence: null, paragraph: [] };
+  for (const line of linesWithoutFrontMatter(body)) {
+    scanHeadingLine(line, state, slugger, headings);
   }
   return headings;
 };
 var MD_LINK = /\[[^\]]*\]\((?<target>[^)\s]+)(?:\s+"[^"]*")?\)/gu;
 var INLINE_CODE2 = /`[^`]*`/gu;
-var scanLinkLine = (line, lineNumber, inFence, links) => {
-  if (CODE_FENCE2.test(line.trimStart())) {
-    return !inFence;
-  }
-  if (inFence) {
-    return inFence;
+var scanLinkLine = (line, lineNumber, fence, links) => {
+  const next = nextFenceState(line, fence);
+  if (fence !== null || next !== null) {
+    return next;
   }
   const masked = line.replaceAll(INLINE_CODE2, (span) => " ".repeat(span.length));
   for (const match of masked.matchAll(MD_LINK)) {
@@ -5810,27 +6438,25 @@ var scanLinkLine = (line, lineNumber, inFence, links) => {
       target
     });
   }
-  return inFence;
+  return next;
 };
-var extractLinks = (body) => {
+var extractLinks = (body, lineOffset = 0) => {
   const links = [];
-  let inFence = false;
-  let lineNumber = 0;
+  let fence = null;
+  let lineNumber = lineOffset;
   for (const line of body.split(`
 `)) {
     lineNumber += 1;
-    inFence = scanLinkLine(line, lineNumber, inFence, links);
+    fence = scanLinkLine(line, lineNumber, fence, links);
   }
   return links;
 };
 var DOUBLE_QUOTED = /"[^"]*"/gu;
 var JSX_OPEN = /<(?<tag>[A-Z][A-Za-z0-9]*)/gu;
-var scanTagLine = (line, inFence, tags) => {
-  if (CODE_FENCE2.test(line.trimStart())) {
-    return !inFence;
-  }
-  if (inFence) {
-    return inFence;
+var scanTagLine = (line, fence, tags) => {
+  const next = nextFenceState(line, fence);
+  if (fence !== null || next !== null) {
+    return next;
   }
   const clean = line.replaceAll(INLINE_CODE2, "").replaceAll(DOUBLE_QUOTED, "");
   for (const match of clean.matchAll(JSX_OPEN)) {
@@ -5839,17 +6465,20 @@ var scanTagLine = (line, inFence, tags) => {
       tags.add(tag);
     }
   }
-  return inFence;
+  return next;
 };
 var extractComponentTags = (body) => {
   const tags = new Set;
-  let inFence = false;
+  let fence = null;
   for (const line of body.split(`
 `)) {
-    inFence = scanTagLine(line, inFence, tags);
+    fence = scanTagLine(line, fence, tags);
   }
   return [...tags];
 };
+var strippedLineOffset = (raw, body) => raw ? Math.max(0, raw.split(`
+`).length - body.split(`
+`).length) : 0;
 var deriveTitle = (meta, headings, id2) => {
   if (meta.title) {
     return meta.title;
@@ -5859,7 +6488,7 @@ var deriveTitle = (meta, headings, id2) => {
     return firstHeading.text;
   }
   const base = id2.split("/").pop() ?? id2;
-  return titleCase(stripNumericPrefix(base.replace(extname4(base), "")));
+  return titleCase(stripNumericPrefix(base.replace(extname5(base), "")));
 };
 var trimSlashes = (value) => value.replaceAll(/^\/+|\/+$/gu, "");
 var withPrefix = (prefix, path) => {
@@ -5910,7 +6539,7 @@ var normalizeEntry2 = (entry, ctx) => {
     headings,
     id: `${ctx.source.name}:${entry.ref}`,
     lastModified: meta.lastModified ?? entry.lastModified,
-    links: extractLinks(entry.body.text),
+    links: extractLinks(entry.body.text, strippedLineOffset(entry.raw, entry.body.text)),
     meta,
     navPath,
     segments,
@@ -6129,12 +6758,9 @@ ${nested}`;
     return Object.values(page.properties).find((p) => p.type === "title");
   };
   const isDraft = (page) => {
-    if (!options.publishedValue) {
-      return false;
-    }
     const prop = page.properties[props.status ?? "Status"];
     const status = prop?.status?.name ?? prop?.select?.name;
-    return Boolean(status && status !== options.publishedValue);
+    return Boolean(status && status !== (options.publishedValue ?? "Published"));
   };
   const orderOf = (page) => {
     const order = page.properties[props.order ?? "Order"]?.number;
@@ -6267,7 +6893,7 @@ var renderSpan = (span, defs) => {
   }
   return link?.href ? `[${text}](${link.href})` : text;
 };
-var renderChildren = (block) => {
+var renderChildren2 = (block) => {
   const defs = new Map((block.markDefs ?? []).map((def) => [def._key, def]));
   return (block.children ?? []).map((span) => renderSpan(span, defs)).join("");
 };
@@ -6284,7 +6910,7 @@ var renderBlock = (block, options) => {
   if (block._type !== "block") {
     return `<!-- unsupported Portable Text block: ${block._type} -->`;
   }
-  const inline = renderChildren(block);
+  const inline = renderChildren2(block);
   if (block.listItem) {
     const indent = "  ".repeat(Math.max(0, (block.level ?? 1) - 1));
     const marker = block.listItem === "number" ? "1." : "-";
@@ -6708,7 +7334,7 @@ import { isAbsolute as isAbsolute8, join as join19 } from "pathe";
 // src/astro/templates.ts
 import { existsSync as existsSync11, readFileSync as readFileSync5 } from "node:fs";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
-import { dirname as dirname7, isAbsolute as isAbsolute7, join as join18, relative as relative5 } from "pathe";
+import { dirname as dirname7, isAbsolute as isAbsolute7, join as join18, relative as relative6 } from "pathe";
 var WORKSPACE_MARKERS = [
   ".git",
   "bun.lock",
@@ -6852,11 +7478,12 @@ var astroConfigTemplate = (options) => {
   const twoslashImport = `import { transformerTwoslash } from "@shikijs/twoslash";
 `;
   const twoslashTransformer = "transformerTwoslash({ explicitTrigger: true }), ";
-  const contentLinkBase = normalizeBasePath(deployment.base) + config.basePath;
+  const deployBase = normalizeBasePath(deployment.base);
   const integrations = [
     `mdx({ processor: blumeMdxProcessor(${JSON.stringify({
-      basePath: contentLinkBase,
+      basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
+      deployBase,
       headingAnchors: config.markdown.headingAnchors
     })}) })`
   ];
@@ -6885,8 +7512,9 @@ export default defineConfig({
   integrations: [${integrations.join(", ")}],
   markdown: {
     processor: blumeMarkdownProcessor(${JSON.stringify({
-    basePath: contentLinkBase,
+    basePath: config.basePath,
     codeThemes: config.markdown.codeBlocks.theme,
+    deployBase,
     headingAnchors: config.markdown.headingAnchors
   })}),
     shikiConfig: {
@@ -6953,7 +7581,7 @@ var contentConfigTemplate = (options) => {
   const collectionBase = options.collection?.base ?? context.contentRoot;
   const includeGlobs = options.collection?.include ?? config.content.include;
   const excludeGlobs = options.collection?.exclude ?? config.content.exclude;
-  const outDirRel = relative5(collectionBase, context.outDir);
+  const outDirRel = relative6(collectionBase, context.outDir);
   const outDirIgnore = outDirRel && !outDirRel.startsWith("..") && !isAbsolute7(outDirRel) ? [`!${outDirRel}/**`] : [];
   const filesystem = options.filesystem ?? true;
   const docsPattern = filesystem ? [
@@ -7041,6 +7669,21 @@ const ground = createAskContext(askData);
     content: m.content,
     role: m.role,
   }));`;
+  const keyCheck = backend.kind === "gateway" ? `  // The AI Gateway authenticates with an API key or Vercel's OIDC token.
+  if (!(process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN)) {
+    return new Response(
+      "Ask AI is not configured: set AI_GATEWAY_API_KEY (or deploy on Vercel with OIDC).",
+      { status: 500 }
+    );
+  }` : `  if (!process.env[${JSON.stringify(backend.apiKeyEnv)}]) {
+    return new Response(
+      ${JSON.stringify(`Ask AI is not configured: set ${backend.apiKeyEnv}.`)},
+      { status: 500 }
+    );
+  }`;
+  const onError = `      onError({ error }) {
+        console.error("Ask AI provider error:", error);
+      },`;
   const stream = grounded ? `    const system =
       (await ground(messages, body.page)) ??
       "You are a helpful documentation assistant. Answer using the project's documentation.";
@@ -7048,14 +7691,17 @@ const ground = createAskContext(askData);
       model: ${modelExpr},
       system,
       messages,
+${onError}
     });` : `    const result = streamText({
       model: ${modelExpr},
       system:
         "You are a helpful documentation assistant. Answer using the project's documentation.",
       messages,
+${onError}
     });`;
   const handler = `export const POST: APIRoute = async ({ request }) => {
 ${validate}
+${keyCheck}
   try {
 ${stream}
     return result.toTextStreamResponse();
@@ -7182,7 +7828,7 @@ export const POST: APIRoute = async ({ request }) => {
   });
 };
 `;
-var rawMarkdownEndpointTemplate = () => `// Generated by Blume. Do not edit.
+var rawMarkdownEndpointTemplate = (kind) => `// Generated by Blume. Do not edit.
 import raw from "../generated/raw-markdown.json";
 
 export const prerender = true;
@@ -7195,7 +7841,8 @@ export function getStaticPaths() {
 }
 
 export function GET({ props }) {
-  return new Response(raw[props.route] ?? "", {
+  const entry = raw[props.route];
+  return new Response(entry ? ${kind === "md" ? "(entry.md ?? entry.mdx)" : "entry.mdx"} : "", {
     headers: { "Content-Type": "text/markdown; charset=utf-8" },
   });
 }
@@ -7335,6 +7982,7 @@ const configuration = ${JSON.stringify(options.configuration, null, 2)};
   searchEnabled={data.config.search.enabled}
   site={{ title: data.config.title, description: data.config.description }}
   themeMode={data.config.theme.mode}
+  ui={data.ui}
 >
   <ScalarComponent configuration={configuration} renderMode="client" />
 </ReferenceLayout>
@@ -7615,6 +8263,7 @@ var changelogIndexTemplate = (options) => {
 import { getCollection, render } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
 import Update from "blume/components/content/Update.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 import { layoutOverrides } from "../generated/components.ts";
 ${askImport}import data from "../generated/data.json";
@@ -7695,6 +8344,20 @@ const items = await Promise.all(
   })
 );
 
+// Repeated labels slug to the same id (e.g. two entries with neither a title
+// nor a version both falling back to "update"); suffix the later ones -2, -3,
+// ... so every heading deep-links to its own entry. The first keeps the plain
+// slug, and the rendered ids stay in lockstep with the \`headings\` list below.
+const seenIds = new Set();
+for (const item of items) {
+  let uniqueId = item.id;
+  for (let n = 2; seenIds.has(uniqueId); n += 1) {
+    uniqueId = item.id + "-" + n;
+  }
+  seenIds.add(uniqueId);
+  item.id = uniqueId;
+}
+
 // A changelog is semver-paginated only when every visible release parses as
 // semver and they span more than one major line. Older majors then collapse
 // into groups the reader reveals one at a time; otherwise the timeline is flat.
@@ -7715,7 +8378,20 @@ const headings = items.map((item) => ({
 }));
 
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
-const canonical = base ? base + "/changelog" : null;
+// The canonical URL carries the deployment base (the page is served under it),
+// matching how the catch-all canonicalizes via \`withBase(route)\`.
+const basedRoute = withBase("/changelog");
+const canonical = base ? base + basedRoute : null;
+
+// The changelog is an unlocalized route, so its chrome renders in the default
+// locale's dictionary and direction (\`data.ui\` is the default locale's resolved
+// dictionary), mirroring the catch-all's locale wiring.
+const i18n = data.config.i18n;
+const localeMeta = i18n
+  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
+  : null;
+const dir = localeMeta?.dir ?? "ltr";
+const htmlLang = i18n ? i18n.defaultLocale : "en";
 
 const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
@@ -7732,7 +8408,10 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   imageZoom={data.config.imageZoom}
   codeWrap={data.config.codeWrap}
   navigation={data.navigation}
-  page={{
+  locale={htmlLang}
+  dir={dir}
+  ui={data.ui}
+  page={{
     title: data.config.title + " changelog",
     description: "Product updates and release notes.",
     route: "/changelog",
@@ -7759,7 +8438,10 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
     items.length === 0 ? (
       <p>No changelog entries yet.</p>
     ) : paginate ? (
-      <blume-changelog class="not-prose mt-8 block">
+      <blume-changelog
+        class="not-prose mt-8 block"
+        data-i18n-more={data.ui.changelog?.showReleases}
+      >
         {majorGroups[0].items.map(({ Content, href, id, label, date, tags }) => (
           <Update description={date} href={href} id={id} label={label} tags={tags}>
             <Content />
@@ -7808,11 +8490,22 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 var notFoundPageTemplate = () => `---
 // Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
 import PageLayout from "blume/components/layout/PageLayout.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
 import data from "../generated/data.json";
 
 export const prerender = true;
 
 const nf = data.ui.notFound;
+
+// The 404 page is an unlocalized route, so its chrome renders in the default
+// locale's dictionary and direction (\`data.ui\` is the default locale's resolved
+// dictionary), mirroring the catch-all's locale wiring.
+const i18n = data.config.i18n;
+const localeMeta = i18n
+  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
+  : null;
+const dir = localeMeta?.dir ?? "ltr";
+const htmlLang = i18n ? i18n.defaultLocale : "en";
 ---
 
 <PageLayout
@@ -7827,6 +8520,8 @@ const nf = data.ui.notFound;
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
+  locale={htmlLang}
+  dir={dir}
   ui={data.ui}
   noindex={true}
 >
@@ -7838,7 +8533,7 @@ const nf = data.ui.notFound;
     <p class="text-muted-foreground">{nf.description}</p>
     <a
       class="mt-2 rounded-md bg-accent px-4 py-2 text-sm font-medium text-accent-foreground"
-      href="/">{nf.home}</a
+      href={withBase("/")}>{nf.home}</a
     >
   </div>
 </PageLayout>
@@ -8948,7 +9643,7 @@ ${clause}
 <Component ${directiveFor(override)} {...Astro.props}><slot /></Component>
 `;
 };
-var sanitize = (value) => value.replaceAll(/[^A-Za-z0-9]/gu, "_");
+var sanitize = (value) => value.replaceAll(/[^A-Za-z0-9]/gu, (char) => `_${(char.codePointAt(0) ?? 0).toString(16)}_`);
 var planComponentSlots = (componentsFile, analysis) => {
   const frameworks = new Set;
   if (!componentsFile) {
@@ -9011,13 +9706,13 @@ export const layoutOverrides = { ...(overrides.layout ?? {})${layoutEntries.leng
 
 // src/astro/examples.ts
 import { readFile as readFile10 } from "node:fs/promises";
-import { join as join21, relative as relative6 } from "pathe";
-import { glob as glob3 } from "tinyglobby";
+import { join as join21, relative as relative7 } from "pathe";
+import { glob as glob4 } from "tinyglobby";
 
 // src/astro/islands.ts
 import { readFile as readFile9 } from "node:fs/promises";
 import { basename, join as join20 } from "pathe";
-import { glob as glob2 } from "tinyglobby";
+import { glob as glob3 } from "tinyglobby";
 var DEFAULT_CLIENT = "visible";
 var VALID_MODES = new Set([
   "idle",
@@ -9046,7 +9741,7 @@ var readClientMode = (source, file, warnings) => {
 };
 var discoverIslands = async (root) => {
   const dir = join20(root, "islands");
-  const matches = await glob2(["**/*.{jsx,svelte,tsx,vue}"], {
+  const matches = await glob3(["**/*.{jsx,svelte,tsx,vue}"], {
     absolute: true,
     cwd: dir,
     onlyFiles: true
@@ -9109,7 +9804,7 @@ var splitGlobBase = (pattern) => {
 var discoverExamples = async (root, pattern = "examples") => {
   const { base, rest } = GLOB_MAGIC.test(pattern) ? splitGlobBase(pattern) : { base: pattern, rest: DEFAULT_EXAMPLE_GLOB };
   const dir = join21(root, base);
-  const matches = await glob3([rest], {
+  const matches = await glob4([rest], {
     absolute: true,
     cwd: dir,
     onlyFiles: true
@@ -9125,7 +9820,7 @@ var discoverExamples = async (root, pattern = "examples") => {
     if (!(ext && framework)) {
       return;
     }
-    const path = relative6(dir, file).slice(0, -(ext.length + 1));
+    const path = relative7(dir, file).slice(0, -(ext.length + 1));
     const existing = seen.get(path);
     if (existing) {
       warnings.push(`Two examples both resolve to "${path}" ("${existing}" and "${file}"); ignoring the second. Give them distinct paths.`);
@@ -9147,52 +9842,6 @@ var discoverExamples = async (root, pattern = "examples") => {
   return { examples, warnings };
 };
 
-// src/astro/pages.ts
-import { extname as extname5, relative as relative7 } from "pathe";
-import { glob as glob4 } from "tinyglobby";
-var discoverPages = async (pagesRoot) => {
-  const files = await glob4(["**/*.astro"], {
-    absolute: true,
-    cwd: pagesRoot,
-    onlyFiles: true
-  });
-  files.sort();
-  return files.map((file) => {
-    const rel = relative7(pagesRoot, file);
-    const withoutExt = rel.slice(0, rel.length - extname5(rel).length);
-    const parts = withoutExt.split("/");
-    if (parts.at(-1) === "index") {
-      parts.pop();
-    }
-    const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
-    return { entrypoint: file, pattern };
-  });
-};
-var routeIsTaken = (pages, contentPages, route) => pages.some((page) => page.pattern === route) || contentPages.some((page) => page.route === route);
-var PRIVATE_SEGMENT = /^[._]/u;
-var humanizeSegment = (segment) => segment.split(/[-_]/u).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
-var customOgRoutes = (pages, siteTitle) => {
-  const seen = new Set;
-  const routes = [];
-  const collectRoute = (pattern) => {
-    const segments = pattern.split("/").filter(Boolean);
-    if (segments.some((part) => PRIVATE_SEGMENT.test(part) || part.includes("["))) {
-      return;
-    }
-    const slug = segments.length === 0 ? "index" : segments.join("/");
-    if (seen.has(slug)) {
-      return;
-    }
-    seen.add(slug);
-    const last = segments.at(-1);
-    routes.push({ slug, title: last ? humanizeSegment(last) : siteTitle });
-  };
-  for (const { pattern } of pages) {
-    collectRoute(pattern);
-  }
-  return routes;
-};
-
 // src/astro/generate.ts
 var BLUME_SRC = join22(packageRoot(), "src");
 var canResolveFrom = (fromDir, spec) => {
@@ -9281,6 +9930,10 @@ var ISLAND_FRAMEWORK_DEPS = {
   svelte: "@astrojs/svelte",
   vue: "@astrojs/vue"
 };
+var DEPLOYMENT_ADAPTER_DEPS = {
+  cloudflare: "@astrojs/cloudflare",
+  netlify: "@astrojs/netlify"
+};
 var islandFrameworkWarnings = (frameworks, root) => {
   const warnings = [];
   for (const framework of frameworks) {
@@ -9291,6 +9944,15 @@ var islandFrameworkWarnings = (frameworks, root) => {
   }
   return warnings;
 };
+var deploymentAdapterWarnings = (deployment, root) => {
+  const dep = deployment.output === "server" && deployment.adapter ? DEPLOYMENT_ADAPTER_DEPS[deployment.adapter] : undefined;
+  if (dep && !(canResolveFrom(root, dep) || canResolveFrom(packageRoot(), dep))) {
+    return [
+      `Deployment adapter "${deployment.adapter}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`
+    ];
+  }
+  return [];
+};
 var examplesCssFile = (root, config) => config.examples.css ? join22(root, config.examples.css) : null;
 var writeExamplesPreview = async (options) => {
   const { config, hasExamples, root, srcDir, write } = options;
@@ -9320,14 +9982,15 @@ var detectNeedsReact = async (root) => {
   });
   return matches.length > 0;
 };
-var detectUsesMath = async (root) => {
-  const files = await glob5(["**/*.mdx"], {
+var containsMath = (content) => content.includes("$$") || content.includes("<Math");
+var detectUsesMath = async (root, staged = []) => {
+  const files = await glob5(["**/*.{md,mdx}"], {
     cwd: root,
     ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
     onlyFiles: true
   });
   const contents = await Promise.all(files.map((file) => readOptional(join22(root, file))));
-  return contents.some((content) => content.includes("$$"));
+  return [...contents, ...staged].some(containsMath);
 };
 var writeIfChanged = async (path, content) => {
   let existing = null;
@@ -9518,6 +10181,7 @@ var buildRuntimeData = (project) => {
       appleIcon: resolveAppleIcon(project),
       ask: config.ai.ask?.enabled ? { suggestions: config.ai.ask.suggestions } : null,
       banner: resolveBanner(config),
+      basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
       codeWrap: config.markdown.code.wrap,
       description: config.description,
@@ -9620,6 +10284,7 @@ var writeMcpFiles = async (project, plan, write) => {
   }
   const data = await buildMcpData(project);
   const discoveryInput = {
+    base: data.base,
     name: data.name,
     route: plan.route,
     site: data.site,
@@ -9651,11 +10316,6 @@ var writeNotFoundPage = async (write, srcDir, pages, contentPages) => {
   }
   await write(join22(srcDir, "pages", "404.astro"), notFoundPageTemplate());
 };
-var shouldGenerateChangelog = (project, userPages) => {
-  const hasChangelog = project.graph.pages.some((page) => page.contentType === "changelog" && !(page.meta.draft || page.meta.sidebar.hidden));
-  const hasChangelogSource = (project.config.content.sources ?? []).some((source) => source.type === "github-releases");
-  return (hasChangelog || hasChangelogSource) && !routeIsTaken(userPages, project.graph.pages, "/changelog");
-};
 var buildComponentSlots = async (componentsFile) => {
   const analysis = componentsFile ? analyzeComponentOverrides(await readFile11(componentsFile, "utf-8"), componentsFile) : null;
   return {
@@ -9683,6 +10343,7 @@ var generateRuntime = async (project) => {
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
+  const staged = collectStaged(project);
   const [
     pages,
     detectedReact,
@@ -9695,7 +10356,7 @@ var generateRuntime = async (project) => {
   ] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(context.root),
-    detectUsesMath(context.root),
+    detectUsesMath(context.root, staged.values()),
     readOptional(context.themeFile),
     readOptional(examplesCssFile(context.root, config)),
     discoverIslands(context.root),
@@ -9719,7 +10380,6 @@ var generateRuntime = async (project) => {
   const ogRoutes = customOgRoutes(pages, config.title);
   const mcp = planMcp(project, srcDir, pages);
   pages.push(...mcp.discoveryPages);
-  const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   const hasFilesystemSource = project.sources.some((source) => !source.staged);
   const [structural] = await Promise.all([
@@ -9785,7 +10445,7 @@ var generateRuntime = async (project) => {
   if (config.seo.og.enabled) {
     await write(join22(srcDir, "pages", "og", "[...slug].png.ts"), ogEndpointTemplate(ogRoutes));
   }
-  if (shouldGenerateChangelog(project, pages)) {
+  if (hasGeneratedChangelog(project, pages)) {
     await write(join22(srcDir, "pages", "changelog.astro"), changelogIndexTemplate({
       askEnabled,
       exportEpub,
@@ -9818,8 +10478,8 @@ var generateRuntime = async (project) => {
   await Promise.all([
     write(join22(srcDir, "generated", "raw-markdown.json"), `${JSON.stringify(rawMarkdown)}
 `),
-    write(join22(srcDir, "pages", "[...slug].md.ts"), rawMarkdownEndpointTemplate()),
-    write(join22(srcDir, "pages", "[...slug].mdx.ts"), rawMarkdownEndpointTemplate())
+    write(join22(srcDir, "pages", "[...slug].md.ts"), rawMarkdownEndpointTemplate("md")),
+    write(join22(srcDir, "pages", "[...slug].mdx.ts"), rawMarkdownEndpointTemplate("mdx"))
   ]);
   const feeds = buildRssFeeds(project);
   if (feeds.length > 0) {
@@ -9844,7 +10504,7 @@ var generateRuntime = async (project) => {
     ...pages.map((page) => page.pattern),
     ...referenceTabs(config).map((tab) => tab.path)
   ]);
-  if (shouldGenerateChangelog(project, pages)) {
+  if (hasGeneratedChangelog(project, pages)) {
     navTargetRoutes.add("/changelog");
   }
   warnings.push(...validateNavTargets(project.graph.navigation, navTargetRoutes).map((diagnostic) => diagnostic.suggestion ? `${diagnostic.message} ${diagnostic.suggestion}` : diagnostic.message));
@@ -9858,7 +10518,7 @@ var generateRuntime = async (project) => {
       warnings.push(`Search provider "${config.search.provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`);
     }
   }
-  warnings.push(...islandFrameworkWarnings(frameworks, context.root));
+  warnings.push(...deploymentAdapterWarnings(config.deployment, context.root), ...islandFrameworkWarnings(frameworks, context.root));
   if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
@@ -10005,6 +10665,7 @@ var segmentKey = (raw) => {
   const group = raw.match(GROUP_FOLDER2)?.groups?.label;
   return (group ?? raw).replace(NUMERIC_PREFIX2, "");
 };
+var isIndexStem = (stem) => stem.replace(NUMERIC_PREFIX2, "") === "index";
 var createGroup = (key, path, label, order) => ({
   children: [],
   index: new Map,
@@ -10029,7 +10690,7 @@ var pageOrder = (page, filename) => {
   if (page.meta.sidebar.order !== undefined) {
     return page.meta.sidebar.order;
   }
-  if (filename.replace(extname6(filename), "") === "index") {
+  if (isIndexStem(filename.replace(extname6(filename), ""))) {
     return Number.NEGATIVE_INFINITY;
   }
   if (page.contentType === "changelog") {
@@ -10138,7 +10799,7 @@ var buildFileSystemSidebar = (pages, folderMeta, sharedMeta, metaPrefix, display
     const stem = filename.replace(extname6(filename), "");
     const dirs = parts.slice(0, -1);
     const routeSegments = page.route.split("/").filter(Boolean);
-    const folderParts = stem === "index" ? routeSegments : routeSegments.slice(0, -1);
+    const folderParts = isIndexStem(stem) ? routeSegments : routeSegments.slice(0, -1);
     const routeDirCount = dirs.filter((dir) => !GROUP_FOLDER2.test(dir)).length;
     const offset = Math.max(0, folderParts.length - routeDirCount);
     let parent = root;
@@ -10266,7 +10927,7 @@ var buildNavigation = (pages, options) => {
     ...selector,
     items: selector.items.map(rebasePath)
   })) : options.selectors ?? [];
-  const tabs = basePath ? (options.tabs ?? []).map((tab) => ({
+  const tabs2 = basePath ? (options.tabs ?? []).map((tab) => ({
     ...tab,
     items: tab.items?.map(rebasePath),
     path: withBasePath(basePath, tab.path)
@@ -10288,14 +10949,15 @@ var buildNavigation = (pages, options) => {
       featured,
       selectors,
       sidebar: buildConfigSidebar(options.sidebar, byRoute, display, basePath),
-      tabs
+      tabs: tabs2
     };
   }
+  const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
   return {
     featured,
     selectors,
-    sidebar: buildFileSystemSidebar(pages, options.folderMeta, sharedFolderMeta, metaPrefix, display, new Set(tabs.flatMap((tab) => tab.path === "/" ? [] : [tab.path]))),
-    tabs
+    sidebar: buildFileSystemSidebar(pages, options.folderMeta, sharedFolderMeta, metaPrefix, display, new Set(tabs2.flatMap((tab) => tab.path === rootTabPath ? [] : [tab.path]))),
+    tabs: tabs2
   };
 };
 
@@ -10337,9 +10999,14 @@ var localePagesFor = (code, real, fallback, fallbackByKey, i18n, basePath) => {
   return [...real, ...filled];
 };
 var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n) => {
-  const tabs = options.navigation.tabs?.map((tab) => ({
+  const localizePath = (path) => path.startsWith("/") ? localizeRoute(path, code, i18n) : path;
+  const tabs2 = options.navigation.tabs?.map((tab) => ({
     ...tab,
-    path: tab.path.startsWith("/") ? localizeRoute(tab.path, code, i18n) : tab.path
+    items: tab.items?.map((item) => ({
+      ...item,
+      path: localizePath(item.path)
+    })),
+    path: localizePath(tab.path)
   }));
   const real = pages.filter((page) => page.locale === code);
   const localePages = localePagesFor(code, real, fallback, fallbackByKey, i18n, options.basePath ?? "");
@@ -10348,12 +11015,13 @@ var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n
     display: options.navigation.sidebar.display,
     featured: options.navigation.featured,
     folderMeta: options.folderMeta,
+    localizedRoot: localizeRoute("/", code, i18n),
     metaPrefix: i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "",
     refByLogical: true,
     selectors: options.navigation.selectors,
     sharedFolderMeta: options.sharedFolderMeta,
     sidebar: options.navigation.sidebar.items,
-    tabs
+    tabs: tabs2
   });
 };
 var buildI18nNavigation = (pages, options, i18n) => {
@@ -10429,7 +11097,10 @@ var parseGitLog = (output) => {
   }
   return times;
 };
-var gitLastModifiedTimes = (root, contentRoot, sourcePaths) => {
+var gitLastModifiedTimes = (root, contentRoots, sourcePaths) => {
+  if (sourcePaths.length === 0) {
+    return new Map;
+  }
   try {
     const gitRoot = execFileSync("git", ["-C", root, "rev-parse", "--show-toplevel"], { encoding: "utf-8" }).trim();
     const output = execFileSync("git", [
@@ -10441,7 +11112,7 @@ var gitLastModifiedTimes = (root, contentRoot, sourcePaths) => {
       "--format=%x00%cI",
       "--name-only",
       "--",
-      contentRoot
+      ...contentRoots
     ], { encoding: "utf-8", maxBuffer: 256 * 1024 * 1024 });
     const byRepoPath = parseGitLog(output);
     const result = new Map;
@@ -10567,7 +11238,7 @@ var entryIdDiagnostics = (pages, collectionBase) => {
         file: page.sourcePath,
         message: `Content source "${page.source.name}" is rooted outside the docs collection base, so ${page.route} resolves entry id "${entryId}" but the collection would generate "${expected}" — the page would 404 at runtime.`,
         severity: "error",
-        suggestion: "Give each filesystem source a root under content.root, or use a single filesystem source so the collection can root at it."
+        suggestion: "Use a single filesystem source (the docs collection roots at it), or root every filesystem source at content.root and partition them with include globs — a root at a subdirectory of content.root still mismatches."
       });
     }
   }
@@ -10579,7 +11250,7 @@ var scanProject = async (root, options = {}) => {
   const configResult = await loadConfig(root, {
     devServerUrl: options.devServerUrl
   });
-  const config = applyConfigOverrides(configResult.config, options.overrides);
+  const config = applyDeploymentEnv(applyConfigOverrides(configResult.config, options.overrides));
   const context = resolveProjectContext(root, config, {
     runtimeDir: options.runtimeDir
   });
@@ -10620,7 +11291,8 @@ var scanProject = async (root, options = {}) => {
   const lastModified = resolveLastModifiedConfig(config.lastModified);
   if (lastModified.enabled && lastModified.source === "git") {
     const fsPaths = pages.map((page) => page.sourcePath).filter((path) => path !== undefined);
-    const gitTimes = gitLastModifiedTimes(context.root, context.contentRoot, fsPaths);
+    const contentRoots = sources.flatMap((source) => source.staged || !source.contentRoot ? [] : [source.contentRoot]);
+    const gitTimes = gitLastModifiedTimes(context.root, contentRoots, fsPaths);
     for (const page of pages) {
       if (!page.lastModified && page.sourcePath) {
         page.lastModified = gitTimes.get(page.sourcePath);
@@ -10659,11 +11331,18 @@ import { dirname as dirname10, join as join23, resolve as resolve7 } from "pathe
 var ENV_LINE = /^\s*(?:export\s+)?(?<key>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?<value>.*?)\s*$/u;
 var DOUBLE_QUOTED2 = /^"(?<body>[\s\S]*)"$/u;
 var SINGLE_QUOTED = /^'(?<body>[\s\S]*)'$/u;
+var ESCAPE = /\\(?<char>[\\nt"])/gu;
+var UNESCAPED = {
+  '"': '"',
+  "\\": "\\",
+  n: `
+`,
+  t: "\t"
+};
 var unquote = (raw) => {
   const double = raw.match(DOUBLE_QUOTED2)?.groups?.body;
   if (double !== undefined) {
-    return double.replaceAll("\\n", `
-`).replaceAll("\\t", "\t").replaceAll("\\\"", '"').replaceAll("\\\\", "\\");
+    return double.replaceAll(ESCAPE, (match, char) => UNESCAPED[char] ?? match);
   }
   const single = raw.match(SINGLE_QUOTED)?.groups?.body;
   if (single !== undefined) {
@@ -10905,6 +11584,47 @@ var enforceBudget = async (distDir, args) => {
   }
   return passed ? "pass" : "fail";
 };
+var runClientAssetChecks = async (staticDir, args) => {
+  if (args.analyze) {
+    await reportBundleSizes(staticDir);
+  }
+  if (await enforceBudget(staticDir, args) === "fail") {
+    process.exit(1);
+  }
+};
+var isolatedStaticDir = (config, context) => {
+  const { adapter, output } = config.deployment;
+  if (output === "server" && adapter === "vercel") {
+    return join24(context.outDir, ".vercel", "output", "static");
+  }
+  const dist = context.distDir ?? join24(context.outDir, "dist");
+  if (output === "server" && adapter === "node") {
+    return join24(dist, "client");
+  }
+  return dist;
+};
+var publishLlmsFiles = async (project, distDir) => {
+  const indexPath = join24(distDir, "llms.txt");
+  const fullPath = join24(distDir, "llms-full.txt");
+  const writeIndex = !existsSync15(indexPath);
+  const writeFull = !existsSync15(fullPath);
+  if (!(writeIndex || writeFull)) {
+    return;
+  }
+  const { index, full } = await buildLlmsFiles(project);
+  const writes = [];
+  if (writeIndex) {
+    writes.push(writeFile7(indexPath, index, "utf-8"));
+  }
+  if (writeFull) {
+    writes.push(writeFile7(fullPath, full, "utf-8"));
+  }
+  await Promise.all(writes);
+  logger.success(`Generated ${[
+    writeIndex ? "llms.txt" : null,
+    writeFull ? "llms-full.txt" : null
+  ].filter(Boolean).join(" and ")}`);
+};
 var publishBuildArtifacts = async (project, distDir, args) => {
   if (project.config.search.provider === "pagefind") {
     logger.start("Building search index");
@@ -10916,13 +11636,8 @@ var publishBuildArtifacts = async (project, distDir, args) => {
     success: (message) => logger.success(message),
     warn: (message) => logger.warn(message)
   });
-  if (project.config.ai.llmsTxt) {
-    const { index, full } = await buildLlmsFiles(project);
-    await Promise.all([
-      writeFile7(join24(distDir, "llms.txt"), index, "utf-8"),
-      writeFile7(join24(distDir, "llms-full.txt"), full, "utf-8")
-    ]);
-    logger.success("Generated llms.txt and llms-full.txt");
+  if (project.config.ai.llmsTxt.enabled) {
+    await publishLlmsFiles(project, distDir);
   }
   const sitemap = buildSitemap(project);
   if (sitemap && !existsSync15(join24(distDir, "sitemap.xml"))) {
@@ -10943,25 +11658,21 @@ var publishBuildArtifacts = async (project, distDir, args) => {
   await emitRedirectFiles(project.config, distDir);
   const { config } = project;
   const features = serverFeatures(config);
+  const sitemapNote = config.seo.sitemap ? "no (set deployment.site)" : "no (seo.sitemap is false)";
   logger.box([
     `Output     ${config.deployment.output}`,
     `Adapter    ${config.deployment.adapter ?? "none"}`,
     `Site       ${config.deployment.site ?? "not set"}`,
     `Search     ${config.search.provider}`,
     `Redirects  ${config.redirects.length}`,
-    `Sitemap    ${sitemap ? "yes" : "no (set deployment.site)"}`,
+    `Sitemap    ${sitemap ? "yes" : sitemapNote}`,
     `Robots     ${robots ? "yes" : "no"}`,
     `Agent JSON ${agentReadability ? "yes" : "no"}`,
-    `LLM files  ${config.ai.llmsTxt ? "yes" : "no"}`,
+    `LLM files  ${config.ai.llmsTxt.enabled ? "yes" : "no"}`,
     `Server features  ${features.length > 0 ? features.join(", ") : "none"}`
   ].join(`
 `));
-  if (args.analyze) {
-    await reportBundleSizes(distDir);
-  }
-  if (await enforceBudget(distDir, args) === "fail") {
-    process.exit(1);
-  }
+  await runClientAssetChecks(distDir, args);
   logger.success(`Built to ${distDir}`);
 };
 var buildCommand = defineCommand2({
@@ -11007,7 +11718,7 @@ var buildCommand = defineCommand2({
   async run({ args }) {
     const root = process.cwd();
     const runtimeDir = args.isolated ? ".blume-verify" : process.env.BLUME_RUNTIME_DIR;
-    refuseIfDevRunning(root, "building", runtimeDir);
+    refuseIfDevRunning(root, "building", { isolatedHint: true, runtimeDir });
     if (args.isolated) {
       await ensureGitignore(root, [".blume-verify/"]);
     }
@@ -11039,6 +11750,7 @@ var buildCommand = defineCommand2({
     });
     const distDir = project.context.distDir ?? join24(root, "dist");
     if (runtimeDir) {
+      await runClientAssetChecks(isolatedStaticDir(project.config, project.context), args);
       logger.success(`Isolated build OK — output at ${distDir} (not published).`);
       return;
     }
@@ -11079,7 +11791,7 @@ var checkCommand = defineCommand3({
   async run({ args }) {
     const root = process.cwd();
     const runtimeDir = args.isolated ? ".blume-verify" : process.env.BLUME_RUNTIME_DIR;
-    refuseIfDevRunning(root, "checking", runtimeDir);
+    refuseIfDevRunning(root, "checking", { isolatedHint: true, runtimeDir });
     if (args.isolated) {
       await ensureGitignore(root, [".blume-verify/"]);
     }
@@ -11191,6 +11903,7 @@ var coalescedRunner = (task) => {
 };
 
 // src/cli/commands/dev.ts
+var normalizeHost = (host) => host === "" ? true : host ?? false;
 var routeSignature = (routes) => routes.map((route) => `${route.path} ${route.entryId}`).toSorted().join(`
 `);
 var devCommand = defineCommand4({
@@ -11246,7 +11959,7 @@ var devCommand = defineCommand4({
     const createServer = (listenPort, open) => dev({
       logLevel: args.debug ? "debug" : "info",
       root: project.context.outDir,
-      server: { host: args.host ?? false, open, port: listenPort }
+      server: { host: normalizeHost(args.host), open, port: listenPort }
     });
     let server = await createServer(explicitPort, args.open ?? false);
     const boundPort = server.address.port;
@@ -11266,7 +11979,6 @@ var devCommand = defineCommand4({
         });
         const nextSignature = routeSignature(next.manifest.routes);
         const structural = nextSignature !== lastSignature;
-        lastSignature = nextSignature;
         if (structural) {
           await server.stop();
           await generateRuntime(next);
@@ -11274,6 +11986,8 @@ var devCommand = defineCommand4({
         } else {
           await generateRuntime(next);
         }
+        lastSignature = nextSignature;
+        reportDiagnostics(next.diagnostics, root);
         showBlumeErrorOverlay(next.diagnostics);
       } catch (error) {
         logger.error(`Regeneration failed: ${error.message}`);
@@ -11415,15 +12129,27 @@ var doctorCommand = defineCommand5({
 });
 
 // src/cli/commands/eject.ts
-import { readFile as readFile13, writeFile as writeFile9 } from "node:fs/promises";
 import { defineCommand as defineCommand6 } from "citty";
-import { join as join28, relative as relative13 } from "pathe";
+import { relative as relative14 } from "pathe";
 
 // src/registry/eject.ts
 import { existsSync as existsSync17 } from "node:fs";
 import { cp as cp2, mkdir as mkdir7, readFile as readFile12, rm as rm3, writeFile as writeFile8 } from "node:fs/promises";
 import { join as join27, relative as relative12 } from "pathe";
 var toPosix = (path) => path.split("\\").join("/");
+var LOCAL_BLUME_SOURCE = "../../node_modules/blume/src/**/*.{astro,ts,tsx}";
+var blumeSourceGlob = (root, genDir, resolveBlumeRoot = packageRoot) => {
+  if (existsSync17(join27(root, "node_modules", "blume"))) {
+    return LOCAL_BLUME_SOURCE;
+  }
+  try {
+    const src = join27(resolveBlumeRoot(), "src");
+    return `${toPosix(relative12(genDir, src))}/**/*.{astro,ts,tsx}`;
+  } catch {
+    console.warn('blume: could not locate the installed blume package; src/generated/app.css keeps its default `@source "../../node_modules/blume/..."` glob. If blume is hoisted elsewhere, point that glob at its install location or Blume\'s utility classes will be missing.');
+    return LOCAL_BLUME_SOURCE;
+  }
+};
 var ejectOpenApiData = (project) => {
   const source = project.sources.find(isOpenApiSource);
   return source ? source.openApiData() : {};
@@ -11449,6 +12175,63 @@ var askFiles = async (project, srcDir, genDir) => {
   }
   return files;
 };
+var hostsMcp = (project, userPages) => project.config.mcp.enabled && !routeIsTaken(userPages, project.graph.pages, project.config.mcp.route);
+var mcpDiscoveryPages = (project, userPages) => hostsMcp(project, userPages) ? [
+  {
+    entrypoint: "src/blume-mcp/discovery.ts",
+    pattern: "/.well-known/mcp.json"
+  },
+  {
+    entrypoint: "src/blume-mcp/server-card.ts",
+    pattern: "/.well-known/mcp/server-card.json"
+  }
+] : [];
+var mcpFiles = async (project, userPages, srcDir, genDir) => {
+  if (!hostsMcp(project, userPages)) {
+    return [];
+  }
+  const { route } = project.config.mcp;
+  const data = await buildMcpData(project);
+  const discoveryInput = {
+    base: data.base,
+    name: data.name,
+    route,
+    site: data.site,
+    version: data.version
+  };
+  return [
+    {
+      content: `${JSON.stringify(data)}
+`,
+      path: join27(genDir, "mcp-data.json")
+    },
+    {
+      content: mcpEndpointTemplate(route),
+      path: join27(srcDir, "pages", mcpPageFile(route))
+    },
+    {
+      content: staticJsonEndpointTemplate(buildMcpDiscovery(discoveryInput)),
+      path: join27(srcDir, "blume-mcp", "discovery.ts")
+    },
+    {
+      content: staticJsonEndpointTemplate(buildMcpServerCard(discoveryInput)),
+      path: join27(srcDir, "blume-mcp", "server-card.ts")
+    }
+  ];
+};
+var changelogFiles = (project, userPages, srcDir, options) => {
+  const hasChangelog = project.graph.pages.some((page) => page.contentType === "changelog" && !(page.meta.draft || page.meta.sidebar.hidden));
+  const hasChangelogSource = (project.config.content.sources ?? []).some((source) => source.type === "github-releases");
+  if (!(hasChangelog || hasChangelogSource) || routeIsTaken(userPages, project.graph.pages, "/changelog")) {
+    return [];
+  }
+  return [
+    {
+      content: changelogIndexTemplate(options),
+      path: join27(srcDir, "pages", "changelog.astro")
+    }
+  ];
+};
 var readExamplesCss = (root, css) => css && existsSync17(join27(root, css)) ? readFile12(join27(root, css), "utf-8") : Promise.resolve("");
 var examplesPreviewFiles = (srcDir, basePath, hasExamples) => hasExamples ? [
   {
@@ -11497,10 +12280,13 @@ var eject = async (root) => {
     root: "."
   };
   const componentsImport = context.componentsFile ? `../../${toPosix(relative12(root, context.componentsFile))}` : null;
-  const relPages = pages.map((page) => ({
-    entrypoint: toPosix(relative12(root, page.entrypoint)),
-    pattern: page.pattern
-  }));
+  const relPages = [
+    ...pages.map((page) => ({
+      entrypoint: toPosix(relative12(root, page.entrypoint)),
+      pattern: page.pattern
+    })),
+    ...mcpDiscoveryPages(project, pages)
+  ];
   const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   const stagedDir = "blume-staged";
@@ -11572,7 +12358,7 @@ var eject = async (root) => {
       content: tailwindEntryTemplate({
         configTokens: buildThemeCss(config.theme),
         sources: [
-          "../../node_modules/blume/src/**/*.{astro,ts,tsx}",
+          blumeSourceGlob(root, genDir),
           "../../**/*.{astro,mdx,ts,tsx}"
         ],
         twoslashCss: twoslashCss(),
@@ -11592,11 +12378,11 @@ var eject = async (root) => {
       path: join27(genDir, "raw-markdown.json")
     },
     {
-      content: rawMarkdownEndpointTemplate(),
+      content: rawMarkdownEndpointTemplate("md"),
       path: join27(srcDir, "pages", "[...slug].md.ts")
     },
     {
-      content: rawMarkdownEndpointTemplate(),
+      content: rawMarkdownEndpointTemplate("mdx"),
       path: join27(srcDir, "pages", "[...slug].mdx.ts")
     }
   ];
@@ -11609,6 +12395,13 @@ var eject = async (root) => {
       path: join27(srcDir, "pages", "og", "[...slug].png.ts")
     });
   }
+  files.push(...await mcpFiles(project, pages, srcDir, genDir), ...changelogFiles(project, pages, srcDir, {
+    askEnabled,
+    exportEpub,
+    exportPdf,
+    needsReact,
+    staged: hasStaged
+  }));
   if (!routeIsTaken(pages, project.graph.pages, "/404")) {
     files.push({
       content: notFoundPageTemplate(),
@@ -11648,12 +12441,14 @@ var eject = async (root) => {
       path: join27(srcDir, "pages", "[section]", "rss.xml.ts")
     });
   }
+  const warnings = [];
   if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
       contentRoutes: new Set(project.graph.pages.map((page) => page.route)),
       root
     });
+    warnings.push(...references.warnings);
     for (const file of references.files) {
       files.push({
         content: file.content,
@@ -11683,10 +12478,37 @@ var eject = async (root) => {
     });
   }
   await rm3(context.outDir, { force: true, recursive: true });
-  return written.map((file) => file.path);
+  return { files: written.map((file) => file.path), warnings };
 };
 
-// src/cli/commands/eject.ts
+// src/cli/eject-scripts.ts
+import { readFile as readFile13, writeFile as writeFile9 } from "node:fs/promises";
+import { join as join28 } from "pathe";
+var droppedArtifactNotices = (config) => {
+  const notices = [];
+  if (config.search.provider === "pagefind") {
+    notices.push('the Pagefind search index — the search UI loads it from the built site, so search will break in production. Add a post-build step: `"build": "astro build && pagefind --site dist"` (with `pagefind` installed as a devDependency).');
+  }
+  if (searchProviderMeta(config.search.provider).syncs) {
+    notices.push(`the hosted ${config.search.provider} index sync — new and updated pages stop being pushed; re-upload your search records after each build with the provider's API or CLI.`);
+  }
+  if (config.ai.llmsTxt.enabled) {
+    notices.push("llms.txt and llms-full.txt");
+  }
+  if (config.deployment.site && config.seo.sitemap) {
+    notices.push("sitemap.xml — recreate it with the @astrojs/sitemap integration.");
+  }
+  if (config.seo.robots) {
+    notices.push("robots.txt — recreate it as a public/robots.txt file.");
+  }
+  if (config.seo.agentReadability) {
+    notices.push("agent-readability.json");
+  }
+  if (config.redirects.length > 0 && config.deployment.output === "static") {
+    notices.push("the platform redirect files (_redirects, vercel.json) — your redirects still work as Astro-generated meta-refresh pages.");
+  }
+  return notices;
+};
 var updatePackageScripts = async (root) => {
   const pkgPath = join28(root, "package.json");
   let pkg;
@@ -11705,47 +12527,21 @@ var updatePackageScripts = async (root) => {
   await writeFile9(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `, "utf-8");
 };
-var ejectCommand = defineCommand6({
-  args: {
-    yes: { description: "Skip the confirmation prompt.", type: "boolean" }
-  },
-  meta: {
-    description: "Promote the generated runtime into an owned Astro project.",
-    name: "eject"
-  },
-  async run({ args }) {
-    const root = process.cwd();
-    refuseIfDevRunning(root, "ejecting");
-    if (!args.yes) {
-      logger.warn("Eject is one-way: it writes astro.config.mjs, src/, and (if absent) tsconfig.json, rewrites your package.json scripts, and removes .blume. An existing tsconfig.json is left untouched.");
-      logger.info("Re-run with --yes to proceed.");
-      return;
-    }
-    const files = await eject(root);
-    await updatePackageScripts(root);
-    logger.success(`Ejected ${files.length} file(s):`);
-    for (const file of files) {
-      process.stdout.write(`  ${relative13(root, file)}
-`);
-    }
-    logger.box(`Your project is now a standalone Astro app.
-
-  bun run dev
-  bun run build
 
-The blume package remains importable.`);
-  }
-});
-
-// src/cli/commands/init.ts
+// src/cli/init/scaffold.ts
 import { existsSync as existsSync18 } from "node:fs";
 import { mkdir as mkdir8, writeFile as writeFile10 } from "node:fs/promises";
-import { defineCommand as defineCommand7 } from "citty";
-import { basename as basename4, dirname as dirname11, isAbsolute as isAbsolute9, join as join29, relative as relative14 } from "pathe";
+import { basename as basename4, dirname as dirname11, isAbsolute as isAbsolute9, join as join29, relative as relative13 } from "pathe";
 
 // src/core/package-json.ts
 var toPackageName = (raw) => raw.toLowerCase().replaceAll(/[^a-z0-9._-]+/gu, "-").replaceAll(/^[-_.]+|[-_.]+$/gu, "") || "docs";
-var blumePackageJson = (name) => `{
+var blumePackageJson = (name, extraDeps = {}) => {
+  const dependencies = Object.entries({
+    blume: `^${getBlumeVersion()}`,
+    ...extraDeps
+  }).toSorted(([a], [b]) => a < b ? -1 : 1).map(([dep, range]) => `    ${JSON.stringify(dep)}: ${JSON.stringify(range)}`).join(`,
+`);
+  return `{
   "name": ${JSON.stringify(name)},
   "private": true,
   "type": "module",
@@ -11755,21 +12551,22 @@ var blumePackageJson = (name) => `{
     "doctor": "blume doctor"
   },
   "dependencies": {
-    "blume": "^${getBlumeVersion()}"
+${dependencies}
   }
 }
 `;
+};
 
-// src/cli/commands/init.ts
+// src/cli/init/scaffold.ts
 var TEMPLATES = ["docs", "api", "sdk", "changelog"];
 var PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
-var configFor = (extra) => `import { defineConfig } from "blume";
-
-export default defineConfig({
-  title: "My Docs",
-  description: "Documentation powered by Blume.",${extra}
-});
-`;
+var SOURCE_KINDS = [
+  "filesystem",
+  "github-releases",
+  "notion",
+  "sanity",
+  "mdx-remote"
+];
 var page = (title, description, body) => `---
 title: ${title}
 description: ${description}
@@ -11779,7 +12576,7 @@ ${body}
 `;
 var STARTERS = {
   api: {
-    config: configFor(`
+    configExtra: `
   openapi: {
     enabled: true,
     route: "/api",
@@ -11789,7 +12586,7 @@ var STARTERS = {
         spec: "https://petstore3.swagger.io/api/v3/openapi.json",
       },
     ],
-  },`),
+  },`,
     files: (dir) => [
       {
         content: page("API Reference", "Explore the API.", "# API Reference\n\nYour OpenAPI spec renders at [`/api`](/api). Point `openapi.sources` at your own spec in `blume.config.ts`."),
@@ -11798,13 +12595,13 @@ var STARTERS = {
     ]
   },
   changelog: {
-    config: configFor(`
+    configExtra: `
   navigation: {
     tabs: [
       { label: "Docs", path: "/" },
       { label: "Changelog", path: "/changelog" },
     ],
-  },`),
+  },`,
     files: (dir) => [
       {
         content: page("Introduction", "Welcome to your new Blume docs.", "# Introduction\n\nWrite your docs here, and log releases under `changelog/`."),
@@ -11824,7 +12621,7 @@ The first release. Edit \`${dir}/changelog/v1-0-0.mdx\` or add new entries besid
     ]
   },
   docs: {
-    config: configFor(""),
+    configExtra: "",
     files: (dir) => [
       {
         content: page("Introduction", "Welcome to your new Blume docs.", `# Introduction
@@ -11837,7 +12634,7 @@ Edit \`${dir}/index.mdx\` to get started, then run \`blume dev\`.`),
     ]
   },
   sdk: {
-    config: configFor(""),
+    configExtra: "",
     files: (dir) => [
       {
         content: page("Introduction", "Get started with the SDK.", `# Introduction
@@ -11853,26 +12650,331 @@ Install the SDK and make your first call. See [Installation](/installation).`),
   }
 };
 var commandsFor = (pm) => ({
+  build: pm === "npm" || pm === "bun" ? `${pm} run build` : `${pm} build`,
   dev: pm === "npm" ? "npm run dev" : `${pm} dev`,
+  exec: { bun: "bunx", npm: "npx", pnpm: "pnpm exec", yarn: "yarn" }[pm],
   install: `${pm} install`
 });
-var writeFileSafe = async (path, content) => {
-  if (existsSync18(path)) {
-    logger.info(`Skipped existing ${path}`);
+var detectPackageManager = (userAgent) => {
+  const name = userAgent?.split("/")[0];
+  return name !== undefined && PACKAGE_MANAGERS.includes(name) ? name : "npm";
+};
+var validateContentDir = (root, dir) => isAbsolute9(dir) || relative13(root, join29(root, dir)).startsWith("..") ? "Must be a relative path inside the project." : undefined;
+var titleize = (raw) => {
+  const words = raw.replaceAll(/[-_.]+/gu, " ").split(/\s+/u).filter(Boolean);
+  return words.length === 0 ? "My Docs" : words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+};
+var hasRemoteSource = (sources) => sources.some((source) => source !== "filesystem");
+var sourceSnippetFor = (kind) => {
+  switch (kind) {
+    case "github-releases": {
+      return `      // Changelog entries from GitHub Releases. Private repos read
+      // GITHUB_TOKEN from the environment.
+      {
+        type: "github-releases",
+        owner: "your-org",
+        repo: "your-repo",
+        prefix: "changelog",
+      },`;
+    }
+    case "notion": {
+      return `      // Pages from a Notion database. Reads NOTION_TOKEN from the environment.
+      {
+        type: "notion",
+        database: "your-database-id",
+        prefix: "notion",
+      },`;
+    }
+    case "sanity": {
+      return `      // Documents from a Sanity dataset. Private datasets read SANITY_TOKEN
+      // from the environment.
+      {
+        type: "sanity",
+        projectId: "your-project-id",
+        dataset: "production",
+        query: \`*[_type == "doc"]\`,
+        prefix: "sanity",
+      },`;
+    }
+    case "mdx-remote": {
+      return `      // MDX fetched from a GitHub repo. Private repos read GITHUB_TOKEN
+      // from the environment.
+      {
+        type: "mdx-remote",
+        github: { owner: "your-org", repo: "your-repo", path: "docs" },
+        prefix: "remote",
+      },`;
+    }
+    default: {
+      return kind;
+    }
+  }
+};
+var contentBlockFor = (answers) => {
+  const sources = answers.sources.length === 0 ? ["filesystem"] : answers.sources;
+  if (!hasRemoteSource(sources)) {
+    return answers.contentDir === "docs" ? "" : `
+  content: {
+    root: ${JSON.stringify(answers.contentDir)},
+  },`;
+  }
+  const entries = SOURCE_KINDS.filter((kind) => sources.includes(kind)).map((kind) => kind === "filesystem" ? `      { type: "filesystem", root: ${JSON.stringify(answers.contentDir)} },` : sourceSnippetFor(kind));
+  return `
+  content: {
+    sources: [
+${entries.join(`
+`)}
+    ],
+  },`;
+};
+var buildConfig = (answers) => `import { defineConfig } from "blume";
+
+export default defineConfig({
+  title: ${JSON.stringify(answers.title)},
+  description: "Documentation powered by Blume.",${STARTERS[answers.template].configExtra}${contentBlockFor(answers)}
+});
+`;
+var extraDepsFor = (sources) => ({
+  ...sources.includes("notion") && { "@notionhq/client": "^2.2.15" },
+  ...sources.includes("sanity") && { "@sanity/client": "^6.21.0" }
+});
+var buildPlan = (root, answers) => {
+  const files = [
+    {
+      content: blumePackageJson(toPackageName(basename4(root)), extraDepsFor(answers.sources)),
+      path: join29(root, "package.json")
+    },
+    { content: buildConfig(answers), path: join29(root, "blume.config.ts") }
+  ];
+  if (answers.sources.length === 0 || answers.sources.includes("filesystem")) {
+    files.push(...STARTERS[answers.template].files(answers.contentDir).map((file) => ({ ...file, path: join29(root, file.path) })));
+  }
+  return files;
+};
+var writeFileSafe = async (file, log) => {
+  if (existsSync18(file.path)) {
+    log.info(`Skipped existing ${file.path}`);
     return false;
   }
-  await mkdir8(dirname11(path), { recursive: true });
-  await writeFile10(path, content, "utf-8");
-  logger.success(`Created ${path}`);
+  await mkdir8(dirname11(file.path), { recursive: true });
+  await writeFile10(file.path, file.content, "utf-8");
+  log.success(`Created ${file.path}`);
   return true;
 };
+var applyPlan = async (files, log) => {
+  const created = await Promise.all(files.map((file) => writeFileSafe(file, log)));
+  const createdPackage = files.some((file, index) => created[index] && basename4(file.path) === "package.json");
+  return { createdPackage };
+};
+var envVarsFor = (sources) => [
+  ["GITHUB_TOKEN", ["github-releases", "mdx-remote"]],
+  ["NOTION_TOKEN", ["notion"]],
+  ["SANITY_TOKEN", ["sanity"]]
+].filter(([, kinds]) => kinds.some((kind) => sources.includes(kind))).map(([envVar]) => envVar);
+var nextSteps = (answers, createdPackage) => {
+  const commands = commandsFor(answers.packageManager);
+  const lines = [];
+  if (answers.directory !== ".") {
+    lines.push(`cd ${answers.directory}`);
+  }
+  if (createdPackage) {
+    lines.push(commands.install);
+  }
+  lines.push(commands.dev);
+  const envVars = envVarsFor(answers.sources);
+  const auth = envVars.length > 0 ? `
+Set ${envVars.join(" and ")} in .env.local so your sources can authenticate.
+` : "";
+  return `Next steps:
+
+  ${lines.join(`
+  `)}
+${auth}`;
+};
+
+// src/cli/commands/eject.ts
+var reportDroppedArtifacts = (notices) => {
+  if (notices.length === 0) {
+    return;
+  }
+  logger.warn([
+    "The ejected build script runs plain `astro build`, which stops producing these `blume build` artifacts:",
+    ...notices.map((notice) => `  - ${notice}`)
+  ].join(`
+`));
+};
+var ejectCommand = defineCommand6({
+  args: {
+    yes: { description: "Skip the confirmation prompt.", type: "boolean" }
+  },
+  meta: {
+    description: "Promote the generated runtime into an owned Astro project.",
+    name: "eject"
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    refuseIfDevRunning(root, "ejecting");
+    let notices = [];
+    try {
+      const { config } = await loadConfig(root);
+      notices = droppedArtifactNotices(config);
+    } catch {}
+    if (!args.yes) {
+      logger.warn("Eject is one-way: it writes astro.config.mjs, src/, and (if absent) tsconfig.json, rewrites your package.json scripts, and removes .blume. An existing tsconfig.json is left untouched.");
+      reportDroppedArtifacts(notices);
+      logger.info("Re-run with --yes to proceed.");
+      return;
+    }
+    const { files, warnings } = await eject(root);
+    await updatePackageScripts(root);
+    for (const warning of warnings) {
+      logger.warn(warning);
+    }
+    logger.success(`Ejected ${files.length} file(s):`);
+    for (const file of files) {
+      process.stdout.write(`  ${relative14(root, file)}
+`);
+    }
+    reportDroppedArtifacts(notices);
+    const pm = detectPackageManager(process.env.npm_config_user_agent);
+    const { build: build2, dev: dev2 } = commandsFor(pm);
+    logger.box(`Your project is now a standalone Astro app.
+
+  ${dev2}
+  ${build2}
+
+The blume package remains importable.`);
+  }
+});
+
+// src/cli/commands/init.ts
+import * as clack from "@clack/prompts";
+import { defineCommand as defineCommand7 } from "citty";
+import { resolve as resolve9 } from "pathe";
+
+// src/cli/init/questions.ts
+import { basename as basename5, resolve as resolve8 } from "pathe";
+var cancelled = (value) => typeof value === "symbol";
+var collectAnswers = async (prompter, flags, defaults) => {
+  const directory = flags.directory ?? await prompter.text({
+    defaultValue: ".",
+    message: "Where should we create your project?",
+    placeholder: "./my-docs"
+  });
+  if (cancelled(directory)) {
+    return null;
+  }
+  const root = resolve8(defaults.cwd, directory);
+  const title = await prompter.text({
+    initialValue: titleize(basename5(root)),
+    message: "What's your docs site called?",
+    validate: (value) => value?.trim() ? undefined : "Give your docs site a name."
+  });
+  if (cancelled(title)) {
+    return null;
+  }
+  const template = flags.template ?? await prompter.select({
+    message: "Which template?",
+    options: [
+      { hint: "Markdown docs site", label: "docs", value: "docs" },
+      { hint: "OpenAPI reference at /api", label: "api", value: "api" },
+      { hint: "SDK docs with an install page", label: "sdk", value: "sdk" },
+      {
+        hint: "Docs plus a changelog tab",
+        label: "changelog",
+        value: "changelog"
+      }
+    ]
+  });
+  if (cancelled(template)) {
+    return null;
+  }
+  const picked = await prompter.multiselect({
+    initialValues: ["filesystem"],
+    message: "Where does your content live?",
+    options: [
+      { hint: "Local .mdx files", label: "filesystem", value: "filesystem" },
+      {
+        hint: "Changelog from GitHub Releases",
+        label: "github-releases",
+        value: "github-releases"
+      },
+      { hint: "A Notion database", label: "notion", value: "notion" },
+      { hint: "A Sanity dataset", label: "sanity", value: "sanity" },
+      {
+        hint: "MDX fetched from a GitHub repo",
+        label: "mdx-remote",
+        value: "mdx-remote"
+      }
+    ],
+    required: false
+  });
+  if (cancelled(picked)) {
+    return null;
+  }
+  const sources = picked.length === 0 ? ["filesystem"] : picked;
+  let contentDir = flags.contentDir ?? "docs";
+  if (flags.contentDir === undefined && sources.includes("filesystem")) {
+    const answer = await prompter.text({
+      defaultValue: "docs",
+      message: "Content directory?",
+      placeholder: "docs",
+      validate: (value) => validateContentDir(root, value || "docs")
+    });
+    if (cancelled(answer)) {
+      return null;
+    }
+    contentDir = answer;
+  }
+  return {
+    contentDir,
+    directory,
+    packageManager: flags.packageManager ?? detectPackageManager(defaults.userAgent),
+    sources,
+    template,
+    title
+  };
+};
+
+// src/cli/commands/init.ts
+var ejectScaffold = async (root, answers) => {
+  const commands = commandsFor(answers.packageManager);
+  const cd = answers.directory === "." ? [] : [`cd ${answers.directory}`];
+  try {
+    await eject(root);
+    await updatePackageScripts(root);
+    logger.success("Ejected to a standalone Astro project.");
+    const steps2 = [...cd, commands.install, commands.dev];
+    logger.box(`Next steps:
+
+  ${steps2.join(`
+  `)}
+`);
+  } catch (error) {
+    logger.warn(`Scaffolded, but eject needs the project's dependencies installed to load blume.config.ts: ${error.message}`);
+    const steps2 = [
+      ...cd,
+      commands.install,
+      `${commands.exec} blume eject --yes`
+    ];
+    logger.box(`Next steps:
+
+  ${steps2.join(`
+  `)}
+`);
+  }
+};
 var initCommand = defineCommand7({
   args: {
     "content-dir": {
-      default: "docs",
       description: "Content directory.",
       type: "string"
     },
+    dir: {
+      description: "Directory to scaffold into (default: current directory).",
+      required: false,
+      type: "positional"
+    },
     eject: {
       description: "Eject to a standalone Astro project after scaffolding.",
       type: "boolean"
@@ -11885,66 +12987,74 @@ var initCommand = defineCommand7({
       description: "Starter template: docs | api | sdk | changelog.",
       type: "string"
     },
-    yes: { description: "Skip prompts.", type: "boolean" }
+    yes: {
+      description: "Skip prompts and scaffold with defaults.",
+      type: "boolean"
+    }
   },
   meta: {
     description: "Scaffold a minimal Blume project.",
     name: "init"
   },
   async run({ args }) {
-    const root = process.cwd();
-    const contentDir = args["content-dir"] ?? "docs";
-    if (isAbsolute9(contentDir) || relative14(root, join29(root, contentDir)).startsWith("..")) {
-      logger.error(`Invalid --content-dir "${contentDir}" (must be a path inside the project).`);
-      process.exit(1);
-    }
-    const template = args.template ?? "docs";
-    if (!TEMPLATES.includes(template)) {
+    const cwd = process.cwd();
+    const template = args.template;
+    if (template !== undefined && !TEMPLATES.includes(template)) {
       logger.error(`Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`);
       process.exit(1);
     }
-    const pm = args["package-manager"] ?? "npm";
-    if (!PACKAGE_MANAGERS.includes(pm)) {
+    const pm = args["package-manager"];
+    if (pm !== undefined && !PACKAGE_MANAGERS.includes(pm)) {
       logger.error(`Unknown package manager "${args["package-manager"]}" (use ${PACKAGE_MANAGERS.join(" | ")}).`);
       process.exit(1);
     }
-    const starter = STARTERS[template];
-    const createdPackage = await writeFileSafe(join29(root, "package.json"), blumePackageJson(toPackageName(basename4(root))));
-    await writeFileSafe(join29(root, "blume.config.ts"), starter.config);
-    await Promise.all(starter.files(contentDir).map((file) => writeFileSafe(join29(root, file.path), file.content)));
+    const interactive = !args.yes && process.stdin.isTTY === true && clack.isTTY(process.stdout) && !clack.isCI();
+    let answers;
+    if (interactive) {
+      clack.intro("blume init");
+      const collected = await collectAnswers(clack, {
+        contentDir: args["content-dir"],
+        directory: args.dir,
+        packageManager: pm,
+        template
+      }, { cwd, userAgent: process.env.npm_config_user_agent });
+      if (collected === null) {
+        clack.cancel("Cancelled — nothing was written.");
+        process.exit(0);
+      }
+      answers = collected;
+    } else {
+      answers = {
+        contentDir: args["content-dir"] ?? "docs",
+        directory: args.dir ?? ".",
+        packageManager: pm ?? detectPackageManager(process.env.npm_config_user_agent),
+        sources: ["filesystem"],
+        template: template ?? "docs",
+        title: "My Docs"
+      };
+    }
+    const root = resolve9(cwd, answers.directory);
+    if (validateContentDir(root, answers.contentDir) !== undefined) {
+      logger.error(`Invalid --content-dir "${answers.contentDir}" (must be a path inside the project).`);
+      process.exit(1);
+    }
+    const sink = interactive ? clack.log : logger;
+    const { createdPackage } = await applyPlan(buildPlan(root, answers), sink);
     const ignored = await ensureGitignore(root, [".blume/", "dist/"]);
     if (ignored.length > 0) {
-      logger.success(`Added ${ignored.join(", ")} to .gitignore`);
+      sink.success(`Added ${ignored.join(", ")} to .gitignore`);
     }
-    const commands = commandsFor(pm);
     if (args.eject) {
-      try {
-        await eject(root);
-        logger.success("Ejected to a standalone Astro project.");
-        logger.box(`Next steps:
-
-  ${commands.install}
-  npx astro dev
-`);
-      } catch (error) {
-        logger.warn(`Scaffolded, but eject failed: ${error.message}`);
-        logger.box(`Next steps:
-
-  ${commands.install}
-  blume eject --yes
-`);
-      }
+      await ejectScaffold(root, answers);
       return;
     }
-    const nextSteps = createdPackage ? `Next steps:
-
-  ${commands.install}
-  ${commands.dev}
-` : `Next steps:
-
-  ${commands.dev}
-`;
-    logger.box(nextSteps);
+    const steps2 = nextSteps(answers, createdPackage);
+    if (interactive) {
+      clack.note(steps2.trimEnd());
+      clack.outro("You're all set.");
+    } else {
+      logger.box(steps2);
+    }
   }
 });
 
@@ -11974,7 +13084,7 @@ var previewCommand = defineCommand8({
       logLevel: "info",
       root: context.outDir,
       server: {
-        host: args.host ?? false,
+        host: normalizeHost(args.host),
         port: parsePort(args.port)
       }
     });
@@ -12030,7 +13140,7 @@ import { join as join33 } from "pathe";
 
 // src/core/links.ts
 import { existsSync as existsSync20 } from "node:fs";
-import { basename as basename5, join as join32 } from "pathe";
+import { basename as basename6, join as join32 } from "pathe";
 var HTTP = /^https?:\/\//iu;
 var PROTOCOL_RELATIVE = /^\/\//u;
 var SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
@@ -12050,10 +13160,8 @@ var STATUS_GONE = 410;
 var STATUS_METHOD_NOT_ALLOWED = 405;
 var STATUS_NOT_IMPLEMENTED = 501;
 var assetIsPresent = (resolved, ctx) => ctx.publicDir !== null && existsSync20(join32(ctx.publicDir, resolved));
-var isIndexPage = (page2) => {
-  const ref = page2.source?.ref ?? page2.sourcePath ?? "";
-  return /^index\.(?:md|mdx)$/iu.test(basename5(ref));
-};
+var NUMERIC_PREFIX3 = /^\d+[-_.]/u;
+var isIndexPage = (page2) => /^index\.(?:md|mdx)$/iu.test(basename6(page2.navPath).replace(NUMERIC_PREFIX3, ""));
 var applyRelativePart = (segments, part) => {
   if (part === "" || part === ".") {
     return;
@@ -12107,6 +13215,9 @@ var checkPathLink = (resolved, fragment, target, site, ctx) => {
   if (ctx.routes.has(route)) {
     return fragment ? checkAnchor(route, fragment, site, ctx) : null;
   }
+  if (ctx.extraRoutes.has(route)) {
+    return null;
+  }
   if (ctx.redirects.has(route)) {
     return null;
   }
@@ -12244,6 +13355,7 @@ var validateLinks = async (graph, options) => {
   const ctx = {
     anchors: buildAnchorIndex(graph.pages),
     basePath,
+    extraRoutes: new Set((options.extraRoutes ?? []).map(toRoute)),
     publicDir: options.publicDir,
     redirects: new Set((options.redirects ?? []).map((redirect) => toRoute(withBasePath(basePath, redirect.from)))),
     routes: new Set(graph.routes.keys())
@@ -12300,10 +13412,24 @@ var validateCommand = defineCommand10({
     try {
       const project = await scanProject(root, { mode: "build" });
       diagnostics.push(...project.diagnostics);
+      const userPages = project.context.pagesRoot ? await discoverPages(project.context.pagesRoot) : [];
+      const extraRoutes = customStaticRoutes(userPages);
+      if (hasGeneratedChangelog(project, userPages)) {
+        extraRoutes.push("/changelog");
+      }
+      if (project.config.i18n) {
+        const manifest = buildManifest({
+          config: project.config,
+          context: project.context,
+          graph: project.graph
+        });
+        extraRoutes.push(...manifest.routes.flatMap((route) => route.fallback ? [route.path] : []));
+      }
       const publicDir = join33(root, "public");
       diagnostics.push(...await validateLinks(project.graph, {
         basePath: project.config.basePath,
         checkExternal: Boolean(args.external),
+        extraRoutes,
         publicDir: existsSync21(publicDir) ? publicDir : null,
         redirects: project.config.redirects
       }));
@@ -12315,9 +13441,10 @@ var validateCommand = defineCommand10({
         process.exit(1);
       }
     }
+    const strictFailure = Boolean(args.strict) && diagnostics.some((diagnostic) => diagnostic.severity !== "info");
     if (args.json) {
       const hadErrors2 = reportDiagnosticsJson(diagnostics, root);
-      if (hadErrors2 || Boolean(args.strict) && diagnostics.length > 0) {
+      if (hadErrors2 || strictFailure) {
         await flushStdout();
         process.exit(1);
       }
@@ -12327,7 +13454,7 @@ var validateCommand = defineCommand10({
     if (diagnostics.length === 0) {
       logger.success("No broken links found.");
     }
-    if (hadErrors || Boolean(args.strict) && diagnostics.length > 0) {
+    if (hadErrors || strictFailure) {
       process.exit(1);
     }
   }
@@ -12364,5 +13491,5 @@ process.on("unhandledRejection", (error) => {
 });
 runMain(main);
 
-//# debugId=8E29DA45BB5B37C564756E2164756E21
+//# debugId=0106CF055BC5BCA264756E2164756E21
 //# sourceMappingURL=index.js.map