blume 0.3.0 → 0.5.0

package/dist/cli/index.js

@@ -209,6 +209,12 @@ var CONTENT_COMPONENTS = [
     file: "Prompt.astro",
     name: "prompt",
     tag: "Prompt"
+  },
+  {
+    description: "A responsive, privacy-friendly YouTube embed.",
+    file: "YouTube.astro",
+    name: "youtube",
+    tag: "YouTube"
   }
 ];
 var registry = [
@@ -254,18 +260,22 @@ var findItem = (name) => registry.find((item) => item.name === name);
 
 // src/registry/rewrite-imports.ts
 import { dirname as dirname2, relative, resolve } from "pathe";
-var RELATIVE_IMPORT = /(?<kw>\bfrom|\bimport)(?<gap>\s+)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gu;
-var rewriteImports = (content, sourceFile, srcRoot) => content.replaceAll(RELATIVE_IMPORT, (match, kw, gap, quote, spec) => {
-  const resolved = resolve(dirname2(sourceFile), spec);
-  if (resolved === sourceFile) {
-    return match;
-  }
-  const rel = relative(srcRoot, resolved);
-  if (rel.startsWith("..")) {
-    return match;
-  }
-  return `${kw}${gap}${quote}blume/${rel}${quote}`;
-});
+var FROM_IMPORT = /(?<prefix>^[ \t]*(?:import|export)\b[^;]*?\bfrom[ \t]*)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gmu;
+var SIDE_EFFECT_IMPORT = /(?<prefix>^[ \t]*import[ \t]+)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gmu;
+var rewriteImports = (content, sourceFile, srcRoot) => {
+  const rewrite = (match, prefix, quote, spec) => {
+    const resolved = resolve(dirname2(sourceFile), spec);
+    if (resolved === sourceFile) {
+      return match;
+    }
+    const rel = relative(srcRoot, resolved);
+    if (rel.startsWith("..")) {
+      return match;
+    }
+    return `${prefix}${quote}blume/${rel}${quote}`;
+  };
+  return content.replaceAll(FROM_IMPORT, rewrite).replaceAll(SIDE_EFFECT_IMPORT, rewrite);
+};
 
 // src/cli/log.ts
 import { consola } from "consola";
@@ -326,7 +336,7 @@ var locatePath = (source, path) => {
     if (typeof segment !== "string") {
       continue;
     }
-    const matcher = new RegExp(`${escapeRegExp(segment)}\\s*[:=]`, "gu");
+    const matcher = new RegExp(`(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`, "gu");
     matcher.lastIndex = cursor;
     const match = matcher.exec(source);
     if (!match) {
@@ -408,6 +418,9 @@ var countBySeverity = (diagnostics) => {
 
 // src/cli/log.ts
 var logger = consola.withTag("blume");
+var flushStdout = () => new Promise((resolve2) => {
+  process.stdout.write("", () => resolve2());
+});
 var reportDiagnosticsJson = (diagnostics, root) => {
   const enriched = diagnostics.map((diagnostic) => {
     const withDocs = enrichDiagnostic(diagnostic);
@@ -500,11 +513,11 @@ Next steps:
 });
 
 // src/cli/commands/build.ts
-import { existsSync as existsSync15 } from "node:fs";
-import { readdir, stat, writeFile as writeFile6 } from "node:fs/promises";
+import { existsSync as existsSync17 } from "node:fs";
+import { readdir, stat, writeFile as writeFile7 } from "node:fs/promises";
 import { build } from "astro";
 import { defineCommand as defineCommand2 } from "citty";
-import { join as join24 } from "pathe";
+import { join as join28 } from "pathe";
 
 // src/core/frontmatter.ts
 import baseMatter from "gray-matter";
@@ -595,6 +608,29 @@ var buildLlmsFiles = async (project) => ({
   index: buildIndex(project)
 });
 
+// src/core/gitignore.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join5 } from "pathe";
+var gitignoreKey = (line) => line.trim().replace(/\/+$/u, "");
+var ensureGitignore = async (root, entries) => {
+  const path = join5(root, ".gitignore");
+  const existing = existsSync3(path) ? await readFile3(path, "utf-8") : "";
+  const present = new Set(existing.split(`
+`).map(gitignoreKey).filter(Boolean));
+  const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
+  if (added.length === 0) {
+    return [];
+  }
+  const gap = existing.length > 0 && !existing.endsWith(`
+`) ? `
+` : "";
+  await writeFile2(path, `${existing}${gap}${added.join(`
+`)}
+`, "utf-8");
+  return added;
+};
+
 // src/search/providers.ts
 var SEARCH_PROVIDERS = {
   algolia: {
@@ -699,14 +735,24 @@ var buildRobots = (project) => {
 `;
 };
 
+// src/deploy/xml.ts
+var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+
 // src/deploy/sitemap.ts
+var lastmodTag = (value) => {
+  if (!value) {
+    return "";
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? "" : `<lastmod>${date.toISOString().slice(0, 10)}</lastmod>`;
+};
 var buildSitemap = (project) => {
   const { site } = project.config.deployment;
   if (!(site && project.config.seo.sitemap)) {
     return null;
   }
   const base = site.replace(/\/$/u, "");
-  const urls = project.graph.pages.filter((page) => !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex)).map((page) => `  <url><loc>${base}${page.route}</loc></url>`).toSorted();
+  const urls = project.graph.pages.filter((page) => !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex)).map((page) => `  <url><loc>${escapeXml(encodeURI(`${base}${page.route}`))}</loc>${lastmodTag(page.lastModified)}</url>`).toSorted();
   return `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
 ${urls.join(`
@@ -716,7 +762,7 @@ ${urls.join(`
 };
 
 // src/search/build.ts
-import { join as join5 } from "pathe";
+import { join as join6 } from "pathe";
 var buildSearchIndex = async (outDir) => {
   const pagefind = await import("pagefind");
   const { index } = await pagefind.createIndex({});
@@ -724,7 +770,7 @@ var buildSearchIndex = async (outDir) => {
     throw new Error("Failed to create Pagefind index.");
   }
   const result = await index.addDirectory({ path: outDir });
-  await index.writeFiles({ outputPath: join5(outDir, "pagefind") });
+  await index.writeFiles({ outputPath: join6(outDir, "pagefind") });
   await pagefind.close();
   return result.page_count;
 };
@@ -2580,7 +2626,19 @@ var LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
 var HEADING_MARK = /^#{1,6}\s+/gmu;
 var MARKDOWN_PUNCT = /[*_~>]+/gu;
 var WHITESPACE = /\s+/gu;
-var toPlainText = (markdown) => markdown.replaceAll(CODE_FENCE, " ").replaceAll(IMAGE, " ").replaceAll(LINK, "$<text>").replaceAll(HTML_OR_JSX, " ").replaceAll(INLINE_CODE, "$<code>").replaceAll(HEADING_MARK, "").replaceAll(MARKDOWN_PUNCT, " ").replaceAll(WHITESPACE, " ").trim();
+var toPlainText = (markdown) => {
+  const withoutBlocks = markdown.replaceAll(CODE_FENCE, " ").replaceAll(IMAGE, " ").replaceAll(LINK, "$<text>");
+  const pieces = [];
+  let cursor = 0;
+  for (const match of withoutBlocks.matchAll(INLINE_CODE)) {
+    const start = match.index ?? 0;
+    pieces.push(withoutBlocks.slice(cursor, start).replaceAll(HTML_OR_JSX, " "));
+    pieces.push(match.groups?.code ?? "");
+    cursor = start + match[0].length;
+  }
+  pieces.push(withoutBlocks.slice(cursor).replaceAll(HTML_OR_JSX, " "));
+  return pieces.join("").replaceAll(HEADING_MARK, "").replaceAll(MARKDOWN_PUNCT, " ").replaceAll(WHITESPACE, " ").trim();
+};
 var buildCrumbIndex = (sidebar) => {
   const index = new Map;
   const walk = (nodes, trail) => {
@@ -2654,7 +2712,7 @@ var syncAlgolia = async (records, config) => {
   }
   const { algoliasearch } = await import("algoliasearch");
   const client = algoliasearch(config.appId, adminKey);
-  await client.saveObjects({
+  await client.replaceAllObjects({
     indexName: config.indexName,
     objects: records.map((record) => ({ ...record, objectID: record._id }))
   });
@@ -2706,20 +2764,21 @@ var syncTypesense = async (records, config) => {
       }
     ]
   });
-  try {
-    await client.collections(config.collection).retrieve();
-  } catch {
-    await client.collections().create({
-      fields: [
-        { name: "title", type: "string" },
-        { name: "description", optional: true, type: "string" },
-        { name: "content", type: "string" },
-        { name: "url", type: "string" },
-        { facet: true, name: "tag", optional: true, type: "string" }
-      ],
-      name: config.collection
-    });
-  }
+  const collection = client.collections(config.collection);
+  const exists = await collection.retrieve().then(() => true).catch(() => false);
+  if (exists) {
+    await collection.delete();
+  }
+  await client.collections().create({
+    fields: [
+      { name: "title", type: "string" },
+      { name: "description", optional: true, type: "string" },
+      { name: "content", type: "string" },
+      { name: "url", type: "string" },
+      { facet: true, name: "tag", optional: true, type: "string" }
+    ],
+    name: config.collection
+  });
   const documents = records.map((record) => ({
     content: record.content,
     description: record.description,
@@ -2753,20 +2812,112 @@ var syncSearchProvider = async (project, reporter) => {
   }
 };
 
+// src/cli/dev-lock.ts
+import {
+  existsSync as existsSync5,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  rmSync,
+  writeFileSync
+} from "node:fs";
+import { join as join8 } from "pathe";
+
+// src/core/project.ts
+import { existsSync as existsSync4 } from "node:fs";
+import { isAbsolute, join as join7, resolve as resolve2 } from "pathe";
+var CONFIG_FILENAMES = [
+  "blume.config.ts",
+  "blume.config.mjs",
+  "blume.config.js"
+];
+var THEME_FILENAMES = ["theme.css"];
+var COMPONENTS_FILENAMES = ["components.tsx", "components.ts"];
+var firstExisting = (root, names) => {
+  for (const name of names) {
+    const candidate = join7(root, name);
+    if (existsSync4(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+};
+var findConfigFile = (root) => firstExisting(root, CONFIG_FILENAMES);
+var resolveRuntimeDir = (root, runtimeDir = ".blume") => isAbsolute(runtimeDir) ? runtimeDir : join7(resolve2(root), runtimeDir);
+var resolveProjectContext = (root, config, options) => {
+  const absoluteRoot = resolve2(root);
+  const contentRoot = isAbsolute(config.content.root) ? config.content.root : join7(absoluteRoot, config.content.root);
+  const pagesPath = join7(absoluteRoot, config.content.pages);
+  const pagesRoot = existsSync4(pagesPath) ? pagesPath : null;
+  const outDir = resolveRuntimeDir(absoluteRoot, options?.runtimeDir);
+  const distDir = options?.runtimeDir ? join7(outDir, "dist") : join7(absoluteRoot, "dist");
+  return {
+    componentsFile: firstExisting(absoluteRoot, COMPONENTS_FILENAMES),
+    configFile: findConfigFile(absoluteRoot),
+    contentRoot,
+    distDir,
+    outDir,
+    pagesRoot,
+    root: absoluteRoot,
+    themeFile: firstExisting(absoluteRoot, THEME_FILENAMES)
+  };
+};
+
+// src/cli/dev-lock.ts
+var lockPath = (outDir) => join8(outDir, "dev.lock");
+var isDevLocked = (outDir) => {
+  const path = lockPath(outDir);
+  if (!existsSync5(path)) {
+    return false;
+  }
+  const pid = Number.parseInt(readFileSync2(path, "utf-8").trim(), 10);
+  if (!(Number.isInteger(pid) && pid > 0)) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var acquireDevLock = (outDir) => {
+  const path = lockPath(outDir);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(path, String(process.pid));
+  let released = false;
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    try {
+      if (existsSync5(path) && readFileSync2(path, "utf-8").trim() === String(process.pid)) {
+        rmSync(path, { force: true });
+      }
+    } catch {}
+  };
+};
+var refuseIfDevRunning = (root, action, runtimeDir) => {
+  if (isDevLocked(resolveRuntimeDir(root, runtimeDir))) {
+    logger.error(`A \`blume dev\` server is running against .blume; ${action} would corrupt it. Stop the dev server, or re-run with --isolated to build/verify against .blume-verify without touching it.`);
+    process.exit(1);
+  }
+};
+
 // src/astro/generate.ts
-import { existsSync as existsSync6, readFileSync as readFileSync5, realpathSync } from "node:fs";
+import { existsSync as existsSync9, readFileSync as readFileSync6, realpathSync } from "node:fs";
 import {
   lstat,
-  mkdir as mkdir2,
-  readFile as readFile7,
+  mkdir as mkdir3,
+  readFile as readFile10,
   rename,
   rm,
   symlink,
-  writeFile as writeFile2
+  writeFile as writeFile4
 } from "node:fs/promises";
-import { createRequire as createRequire4 } from "node:module";
+import { createRequire as createRequire5 } from "node:module";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
-import { basename as basename2, dirname as dirname7, join as join11, normalize, relative as relative6 } from "pathe";
+import { basename as basename2, dirname as dirname7, join as join17, normalize as normalize3, relative as relative6 } from "pathe";
 import { glob as glob4 } from "tinyglobby";
 
 // src/ai/ask-data.ts
@@ -2838,7 +2989,7 @@ var askBackendRuntimeDep = (ask) => {
 };
 
 // src/ai/markdown.ts
-import { readFile as readFile3 } from "node:fs/promises";
+import { readFile as readFile4 } from "node:fs/promises";
 var buildRawMarkdown = async (project) => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
   const readRoute = async (route) => {
@@ -2846,7 +2997,7 @@ var buildRawMarkdown = async (project) => {
     if (page) {
       return await readEntryText(project, page);
     }
-    return route.sourcePath ? await readFile3(route.sourcePath, "utf-8") : "";
+    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)]));
   return Object.fromEntries(entries);
@@ -2943,6 +3094,7 @@ var buildMcpServerCard = (input) => ({
 var BUILTIN_MDX_TAGS = new Set([
   "Accordion",
   "AccordionItem",
+  "ApiOverview",
   "AutoTypeTable",
   "Badge",
   "Callout",
@@ -2961,8 +3113,12 @@ var BUILTIN_MDX_TAGS = new Set([
   "GithubInfo",
   "Icon",
   "Math",
+  "Operation",
   "Panel",
+  "ParamField",
   "Prompt",
+  "RequestField",
+  "ResponseField",
   "Step",
   "Steps",
   "Tab",
@@ -2971,7 +3127,8 @@ var BUILTIN_MDX_TAGS = new Set([
   "Tooltip",
   "Tree",
   "TypeTable",
-  "Visibility"
+  "Visibility",
+  "YouTube"
 ]);
 
 // src/core/component-diagnostics.ts
@@ -3000,8 +3157,8 @@ var validateUsedComponents = (pages, extraTags, registryNames) => {
 };
 
 // src/core/component-overrides.ts
-import { existsSync as existsSync3 } from "node:fs";
-import { dirname as dirname4, extname, isAbsolute, resolve as resolve2 } from "pathe";
+import { existsSync as existsSync6 } from "node:fs";
+import { dirname as dirname4, extname, isAbsolute as isAbsolute2, resolve as resolve3 } from "pathe";
 import ts from "typescript";
 var GROUPS = ["mdx", "layout", "islands"];
 var FRAMEWORK_BY_EXT = {
@@ -3089,18 +3246,18 @@ var findDefaultExportObject = (sourceFile) => {
 var probeExtension = (base) => {
   for (const extension of COMPONENT_EXTS) {
     const candidate = `${base}.${extension}`;
-    if (existsSync3(candidate)) {
+    if (existsSync6(candidate)) {
       return candidate;
     }
   }
   return null;
 };
 var toImport = (specifier, imported, dir) => {
-  const relative4 = specifier.startsWith(".") || isAbsolute(specifier);
+  const relative4 = specifier.startsWith(".") || isAbsolute2(specifier);
   let path = specifier;
   let extension = extname(specifier).slice(1).toLowerCase();
   if (relative4) {
-    const absolute = isAbsolute(specifier) ? specifier : resolve2(dir, specifier);
+    const absolute = isAbsolute2(specifier) ? specifier : resolve3(dir, specifier);
     if (extension) {
       path = absolute;
     } else {
@@ -3348,147 +3505,104 @@ var resolveUIStrings = (locale, options) => {
 };
 
 // src/theme/icons.ts
-var icons = {
-  "arrow-left": '<path d="m12 19-7-7 7-7"/><path d="M19 12H5"/>',
-  "arrow-right": '<path d="M5 12h14"/><path d="m12 5 7 7-7 7"/>',
-  "arrow-up": '<path d="m5 12 7-7 7 7"/><path d="M12 19V5"/>',
-  "arrow-up-right": '<path d="M7 7h10v10"/><path d="M7 17 17 7"/>',
-  "badge-alert": '<path d="M3.85 8.62a4 4 0 0 1 4.78-4.77 4 4 0 0 1 6.74 0 4 4 0 0 1 4.78 4.78 4 4 0 0 1 0 6.74 4 4 0 0 1-4.78 4.78 4 4 0 0 1-6.74 0 4 4 0 0 1-4.78-4.78 4 4 0 0 1 0-6.75Z"/><path d="M12 8v4"/><path d="M12 16h.01"/>',
-  ban: '<circle cx="12" cy="12" r="10"/><path d="m4.93 4.93 14.14 14.14"/>',
-  "book-open": '<path d="M2 3h6a4 4 0 0 1 4 4v14a3 3 0 0 0-3-3H2z"/><path d="M22 3h-6a4 4 0 0 0-4 4v14a3 3 0 0 1 3-3h7z"/>',
-  "book-open-cover": '<path d="M12 7v14"/><path d="M3 18a2 2 0 0 1 2-2h7V5H5a2 2 0 0 0-2 2Z"/><path d="M21 18a2 2 0 0 0-2-2h-7V5h7a2 2 0 0 1 2 2Z"/>',
-  "brand-x": '<path d="m4 4 11.7 16H20L8.3 4Z"/><path d="M4 20 20 4"/>',
-  check: '<path d="M20 6 9 17l-5-5"/>',
-  "chevron-down": '<path d="m6 9 6 6 6-6"/>',
-  "chevron-right": '<path d="m9 18 6-6-6-6"/>',
-  "circle-check": '<circle cx="12" cy="12" r="10"/><path d="m9 12 2 2 4-4"/>',
-  "circle-x": '<circle cx="12" cy="12" r="10"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/>',
-  clock: '<circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/>',
-  copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
-  download: '<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="m7 10 5 5 5-5"/><path d="M12 15V3"/>',
-  "external-link": '<path d="M15 3h6v6"/><path d="M10 14 21 3"/><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/>',
-  file: '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>',
-  flag: '<path d="M4 15s1-1 4-1 5 2 8 2 4-1 4-1V3s-1 1-4 1-5-2-8-2-4 1-4 1z"/><path d="M4 22V15"/>',
-  folder: '<path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z"/>',
-  gear: '<path d="M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915"/><circle cx="12" cy="12" r="3"/>',
-  github: '<path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.4 5.4 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.3-.8 2.1-.36.16-.78.24-1.2.24-1.4 0-2.4-.7-3-2-.3-.6-.8-.9-1.2-.9-.4 0-.8.2-.8.5 0 .5.7.8 1 1.2.7 1.5 2 2.4 4 2.4.43 0 .84-.04 1.2-.13V22"/>',
-  globe: '<circle cx="12" cy="12" r="10"/><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20"/><path d="M2 12h20"/>',
-  info: '<circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/>',
-  js: '<path d="M8 8v7a2 2 0 1 1-4 0"/><path d="M16 15a2 2 0 1 0 2-2 2 2 0 1 1 2-2"/><path d="M20 8v.01"/>',
-  key: '<path d="M21 2 11.4 11.6"/><circle cx="7.5" cy="16.5" r="5.5"/><path d="m15 7 2 2"/><path d="m12 10 2 2"/>',
-  leaf: '<path d="M11 20A7 7 0 0 1 9.8 6.1C15.5 5 17 4.48 19 2c1 2 2 4.18 2 8 0 5.5-4.78 10-10 10Z"/><path d="M2 21c0-3 1.85-5.36 5.08-6C9.5 14.52 12 13 13 12"/>',
-  lightbulb: '<path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/>',
-  link: '<path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/>',
-  linkedin: '<path d="M16 8a6 6 0 0 1 6 6v7h-4v-7a2 2 0 0 0-4 0v7h-4v-7a6 6 0 0 1 6-6z"/><rect width="4" height="12" x="2" y="9"/><circle cx="4" cy="4" r="2"/>',
-  lock: '<rect width="18" height="11" x="3" y="11" rx="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/>',
-  menu: '<line x1="4" x2="20" y1="12" y2="12"/><line x1="4" x2="20" y1="6" y2="6"/><line x1="4" x2="20" y1="18" y2="18"/>',
-  "message-circle": '<path d="M7.9 20A9 9 0 1 0 4 16.1L2 22Z"/>',
-  moon: '<path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/>',
-  "panel-left": '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M9 3v18"/>',
-  "panel-left-close": '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M9 3v18"/><path d="m16 15-3-3 3-3"/>',
-  "panel-right": '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M15 3v18"/>',
-  "panel-right-close": '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M15 3v18"/><path d="m8 9 3 3-3 3"/>',
-  paperclip: '<path d="m16 6-8.41 8.41a2 2 0 0 0 2.83 2.83L18.83 8.83a4 4 0 0 0-5.66-5.66L4.76 11.59a6 6 0 0 0 8.49 8.49L21.66 11.66"/>',
-  "puzzle-piece": '<path d="M15.39 4.39a2.1 2.1 0 0 0-2.97 0L12 4.82l-.42-.43a2.1 2.1 0 1 0-2.97 2.97l.43.42L7.6 9.22H4.75A1.75 1.75 0 0 0 3 10.97v8.28C3 20.22 3.78 21 4.75 21h8.28c.97 0 1.75-.78 1.75-1.75V16.4l1.44-1.44.42.43a2.1 2.1 0 1 0 2.97-2.97l-.43-.42.43-.42a2.1 2.1 0 1 0-2.97-2.97l-.42.43-1.44-1.44.61-.61a2.1 2.1 0 0 0 0-2.97Z"/>',
-  python: '<path d="M12 2h4a4 4 0 0 1 4 4v3H8a4 4 0 0 0-4 4v1"/><path d="M12 22H8a4 4 0 0 1-4-4v-3h12a4 4 0 0 0 4-4v-1"/><path d="M9 6h.01"/><path d="M15 18h.01"/>',
-  rocket: '<path d="M4.5 16.5c-1.5 1.26-2 5-2 5s3.74-.5 5-2c.71-.84.7-2.13-.09-2.91a2.18 2.18 0 0 0-2.91-.09z"/><path d="m12 15-3-3a22 22 0 0 1 2-3.95A12.88 12.88 0 0 1 22 2c0 2.72-.78 7.5-6 11a22.35 22.35 0 0 1-4 2z"/><path d="M9 12H4s.55-3.03 2-4c1.62-1.08 5 0 5 0"/><path d="M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5"/>',
-  rss: '<path d="M4 11a9 9 0 0 1 9 9"/><path d="M4 4a16 16 0 0 1 16 16"/><circle cx="5" cy="19" r="1"/>',
-  search: '<circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>',
-  sparkles: '<path d="m12 3-1.9 5.8a2 2 0 0 1-1.3 1.3L3 12l5.8 1.9a2 2 0 0 1 1.3 1.3L12 21l1.9-5.8a2 2 0 0 1 1.3-1.3L21 12l-5.8-1.9a2 2 0 0 1-1.3-1.3Z"/><path d="M5 3v4"/><path d="M3 5h4"/><path d="M19 17v4"/><path d="M17 19h4"/>',
-  star: '<path d="m12 2 3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01Z"/>',
-  sun: '<circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/>',
-  "text-align-start": '<path d="M4 6h16"/><path d="M4 10h10"/><path d="M4 14h16"/><path d="M4 18h10"/>',
-  "thumbs-down": '<path d="M17 14V2"/><path d="M9 18.12 10 14H4.17a2 2 0 0 1-1.92-2.56l2.33-8A2 2 0 0 1 6.5 2H20a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2h-2.76a2 2 0 0 0-1.79 1.11L12 22a3.13 3.13 0 0 1-3-3.88Z"/>',
-  "thumbs-up": '<path d="M7 10v12"/><path d="M15 5.88 14 10h5.83a2 2 0 0 1 1.92 2.56l-2.33 8A2 2 0 0 1 17.5 22H4a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2h2.76a2 2 0 0 0 1.79-1.11L12 2a3.13 3.13 0 0 1 3 3.88Z"/>',
-  "triangle-alert": '<path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z"/><path d="M12 9v4"/><path d="M12 17h.01"/>',
-  x: '<path d="M18 6 6 18"/><path d="m6 6 12 12"/>'
-};
-var iconAliases = {
-  "alien-8bit": "sparkles",
-  "arrow-up-right-from-square": "external-link",
-  "book-open-reader": "book-open",
-  "circle-info": "info",
-  close: "x",
-  "external-link-alt": "external-link",
-  "fa-github": "github",
-  "fa-linkedin": "linkedin",
-  "fa-x-twitter": "brand-x",
-  "file-lines": "file",
-  javascript: "js",
-  "panel-left-open": "panel-left",
-  "panel-right-open": "panel-right",
-  times: "x",
-  "x-twitter": "brand-x"
-};
-var libraryPrefixes = [
-  "fa-brands",
-  "fa-duotone",
-  "fa-light",
-  "fa-regular",
-  "fa-sharp-solid",
-  "fa-solid",
-  "fa-thin",
-  "fa",
-  "fab",
-  "fad",
-  "fal",
-  "far",
-  "fas",
-  "fat",
-  "lucide",
-  "tabler",
-  "ti"
-];
-var normalizedIconName = (name) => name.trim().toLowerCase().replaceAll(/[\s_]+/gu, "-");
-var isString = (value) => typeof value === "string";
-var withoutLibraryPrefix = (name) => {
-  let normalized = normalizedIconName(name).replaceAll(/^icon-/gu, "");
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const prefix of libraryPrefixes) {
-      if (normalized.startsWith(`${prefix}-`)) {
-        normalized = normalized.slice(prefix.length + 1);
-        changed = true;
-      }
-      if (normalized.startsWith(`${prefix}:`)) {
-        normalized = normalized.slice(prefix.length + 1);
-        changed = true;
-      }
-    }
+import { createRequire as createRequire2 } from "node:module";
+import { getIconData, iconToSVG } from "@iconify/utils";
+var requireJson = createRequire2(import.meta.url);
+var loadSet = (pkg) => requireJson(pkg);
+var SETS = {
+  "fa6-brands": loadSet("@iconify-json/fa6-brands/icons.json"),
+  "fa6-regular": loadSet("@iconify-json/fa6-regular/icons.json"),
+  "fa6-solid": loadSet("@iconify-json/fa6-solid/icons.json"),
+  lucide: loadSet("@iconify-json/lucide/icons.json"),
+  tabler: loadSet("@iconify-json/tabler/icons.json")
+};
+var DEFAULT_SET = "lucide";
+var LIBRARY_SETS = {
+  fa: "fa6-solid",
+  "font-awesome": "fa6-solid",
+  fontawesome: "fa6-solid",
+  lucide: "lucide",
+  tabler: "tabler"
+};
+var ICON_TYPE_SETS = {
+  brands: "fa6-brands",
+  duotone: "fa6-solid",
+  light: "fa6-solid",
+  regular: "fa6-regular",
+  "sharp-solid": "fa6-solid",
+  solid: "fa6-solid",
+  thin: "fa6-solid"
+};
+var PREFIX_SETS = {
+  ...LIBRARY_SETS,
+  fa: "fa6-solid",
+  "fa-brands": "fa6-brands",
+  "fa-regular": "fa6-regular",
+  "fa-solid": "fa6-solid",
+  "fa6-brands": "fa6-brands",
+  "fa6-regular": "fa6-regular",
+  "fa6-solid": "fa6-solid",
+  fab: "fa6-brands",
+  far: "fa6-regular",
+  fas: "fa6-solid",
+  ti: "tabler"
+};
+var normalize = (name) => name.trim().toLowerCase().replaceAll(/[\s_]+/gu, "-");
+var setFor = (options) => {
+  if (options.iconType) {
+    const set = ICON_TYPE_SETS[normalize(options.iconType)];
+    if (set) {
+      return set;
+    }
+  }
+  if (options.library) {
+    const set = LIBRARY_SETS[normalize(options.library)];
+    if (set) {
+      return set;
+    }
+  }
+  return DEFAULT_SET;
+};
+var fromSet = (setName, iconName) => {
+  const set = SETS[setName];
+  const data = set && getIconData(set, iconName);
+  if (!data) {
+    return null;
   }
-  return normalized;
+  const { attributes, body } = iconToSVG(data, { height: "auto" });
+  return { body, name: iconName, viewBox: attributes.viewBox };
 };
-var resolveIcon = (name, iconType) => {
-  const normalized = normalizedIconName(name);
-  const stripped = withoutLibraryPrefix(name);
-  const type = iconType ? normalizedIconName(iconType) : null;
-  const candidates = [
-    normalized,
-    stripped,
-    type ? `${type}-${stripped}` : null,
-    iconAliases[normalized],
-    iconAliases[stripped]
-  ].filter(isString);
-  for (const candidate of candidates) {
-    const markup = icons[candidate];
-    if (markup) {
-      return { markup, name: candidate };
+var fromFaSet = (setName, name) => fromSet(setName, name) ?? fromSet("fa6-brands", name);
+var resolveInSet = (setName, name) => setName.startsWith("fa6-") ? fromFaSet(setName, name) : fromSet(setName, name);
+var resolveIcon = (name, options = {}) => {
+  const normalized = normalize(name);
+  const colon = normalized.indexOf(":");
+  if (colon > 0) {
+    const setName = PREFIX_SETS[normalized.slice(0, colon)];
+    if (setName) {
+      return resolveInSet(setName, normalized.slice(colon + 1));
     }
   }
-  return null;
+  return resolveInSet(setFor(options), normalized);
+};
+var hasIcon = (name, options = {}) => {
+  if (resolveIcon(name, options)) {
+    return true;
+  }
+  const normalized = normalize(name);
+  const bare = normalized.includes(":") ? normalized.slice(normalized.indexOf(":") + 1) : normalized;
+  return Object.values(SETS).some((set) => getIconData(set, bare) !== null);
 };
-var hasIcon = (name, iconType) => resolveIcon(name, iconType) !== null;
 
 // src/core/nav-diagnostics.ts
 var IMAGE_ICON = /^(?:https?:\/\/|data:image\/|\/|\.{1,2}\/)|\.(?:avif|gif|jpe?g|png|svg|webp)$/iu;
 var isAssetIcon = (value) => value.startsWith("<") || IMAGE_ICON.test(value);
 var flattenNodes = (nodes) => nodes.flatMap((node) => node.kind === "group" ? [node, ...flattenNodes(node.children)] : [node]);
 var collectIcons = (navigation) => {
-  const icons2 = [];
+  const icons = [];
   const push = (icon, where) => {
     if (icon) {
-      icons2.push({ icon, where });
+      icons.push({ icon, where });
     }
   };
   for (const tab of navigation.tabs) {
@@ -3511,7 +3625,7 @@ var collectIcons = (navigation) => {
       push(node.icon, `"${node.label}"`);
     }
   }
-  return icons2;
+  return icons;
 };
 var validateNavIcons = (navigation) => {
   const seen = new Set;
@@ -3621,10 +3735,10 @@ var validateNavStructure = (navigation, pages) => [
 ];
 
 // src/core/tsconfig-aliases.ts
-import { existsSync as existsSync4, readFileSync as readFileSync2, statSync } from "node:fs";
-import { createRequire as createRequire2 } from "node:module";
+import { existsSync as existsSync7, readFileSync as readFileSync3, statSync } from "node:fs";
+import { createRequire as createRequire3 } from "node:module";
 import { pathToFileURL } from "node:url";
-import { dirname as dirname5, isAbsolute as isAbsolute2, join as join6, resolve as resolve3 } from "pathe";
+import { dirname as dirname5, isAbsolute as isAbsolute3, join as join9, resolve as resolve4 } from "pathe";
 var stripJsonComments = (text) => {
   let out = "";
   let inString = false;
@@ -3678,16 +3792,16 @@ var isFile = (path) => {
   }
 };
 var resolveExtends = (spec, fromDir) => {
-  if (spec.startsWith(".") || isAbsolute2(spec)) {
-    const candidates = spec.endsWith(".json") ? [resolve3(fromDir, spec)] : [
-      resolve3(fromDir, `${spec}.json`),
-      resolve3(fromDir, spec, "tsconfig.json"),
-      resolve3(fromDir, spec)
+  if (spec.startsWith(".") || isAbsolute3(spec)) {
+    const candidates = spec.endsWith(".json") ? [resolve4(fromDir, spec)] : [
+      resolve4(fromDir, `${spec}.json`),
+      resolve4(fromDir, spec, "tsconfig.json"),
+      resolve4(fromDir, spec)
     ];
     return candidates.find(isFile) ?? null;
   }
   try {
-    const require_ = createRequire2(pathToFileURL(join6(fromDir, "_.js")).href);
+    const require_ = createRequire3(pathToFileURL(join9(fromDir, "_.js")).href);
     for (const sub of [`${spec}/tsconfig.json`, spec]) {
       try {
         return require_.resolve(sub);
@@ -3697,11 +3811,11 @@ var resolveExtends = (spec, fromDir) => {
   return null;
 };
 var loadPaths = (file, seen) => {
-  if (seen.has(file) || !existsSync4(file)) {
+  if (seen.has(file) || !existsSync7(file)) {
     return null;
   }
   seen.add(file);
-  const json = parseJsonc(readFileSync2(file, "utf-8"));
+  const json = parseJsonc(readFileSync3(file, "utf-8"));
   if (!json) {
     return null;
   }
@@ -3709,7 +3823,7 @@ var loadPaths = (file, seen) => {
   if (options.paths && typeof options.paths === "object") {
     const baseUrl = typeof options.baseUrl === "string" ? options.baseUrl : ".";
     return {
-      baseDir: resolve3(dirname5(file), baseUrl),
+      baseDir: resolve4(dirname5(file), baseUrl),
       paths: options.paths
     };
   }
@@ -3736,10 +3850,10 @@ var toAlias = (key, value, baseDir) => {
   if (find === "" || find === "*") {
     return null;
   }
-  return { find, replacement: resolve3(baseDir, target) };
+  return { find, replacement: resolve4(baseDir, target) };
 };
 var resolveTsconfigAliases = (root) => {
-  const entry = ["tsconfig.json", "jsconfig.json"].map((name) => join6(root, name)).find((file) => existsSync4(file));
+  const entry = ["tsconfig.json", "jsconfig.json"].map((name) => join9(root, name)).find((file) => existsSync7(file));
   if (!entry) {
     return {};
   }
@@ -3798,7 +3912,6 @@ var buildRssFeeds = (project) => {
   }
   return feeds;
 };
-var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
 var renderItem = (item) => {
   const parts = [
     `    <title>${escapeXml(item.title)}</title>`,
@@ -3836,13 +3949,98 @@ ${items}
 `;
 };
 
+// src/openapi/references.ts
+var NON_SLUG = /[^a-z0-9]+/gu;
+var SLUG_EDGES = /^-+|-+$/gu;
+var ROUTE_EDGES = /^\/+|\/+$/gu;
+var TRAILING_SLASH = /\/+$/u;
+var slugify = (text) => text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
+var normalizeRoute = (route) => {
+  const trimmed = route.trim();
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const noTrailing = withSlash.replace(TRAILING_SLASH, "");
+  return noTrailing === "" ? "/" : noTrailing;
+};
+var routeSlug = (route) => slugify(route.replace(ROUTE_EDGES, "")) || "reference";
+var sourcesOf = (block) => {
+  const sources = [...block.sources];
+  if (block.spec) {
+    sources.unshift({ spec: block.spec });
+  }
+  return sources;
+};
+var referencesFor = (kind, block, defaultLabel, renderer, display) => {
+  if (!block.enabled) {
+    return [];
+  }
+  const sources = sourcesOf(block);
+  const base = normalizeRoute(block.route);
+  return sources.map((source, index) => {
+    const label = source.label ?? (sources.length > 1 ? `${defaultLabel} ${index + 1}` : defaultLabel);
+    let route;
+    if (source.route) {
+      route = normalizeRoute(source.route);
+    } else if (sources.length === 1) {
+      route = base;
+    } else {
+      const suffix = source.label ? slugify(source.label) : "";
+      route = normalizeRoute(`${base}/${suffix || index + 1}`);
+    }
+    return {
+      display,
+      kind,
+      label,
+      renderer,
+      route,
+      slug: routeSlug(route),
+      spec: source.spec,
+      theme: block.theme
+    };
+  });
+};
+var NO_DISPLAY = { codeSamples: [], expandSchemas: false };
+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)
+];
+var referenceTabs = (config) => resolveReferences(config).map((ref) => ({
+  label: ref.label,
+  path: ref.route
+}));
+var blumeReferences = (config) => {
+  const seen = new Set;
+  const result = [];
+  for (const ref of resolveReferences(config)) {
+    if (ref.kind !== "openapi" || ref.renderer !== "blume") {
+      continue;
+    }
+    if (seen.has(ref.route)) {
+      continue;
+    }
+    seen.add(ref.route);
+    result.push(ref);
+  }
+  return result;
+};
+var hasScalarReferences = (config) => resolveReferences(config).some((ref) => ref.renderer === "scalar");
+
 // src/openapi/scalar.ts
-import { readFile as readFile4 } from "node:fs/promises";
-import { isAbsolute as isAbsolute3, join as join8 } from "pathe";
+import { readFile as readFile5 } from "node:fs/promises";
+import { isAbsolute as isAbsolute4, join as join12 } from "pathe";
 
 // src/astro/templates.ts
-import { existsSync as existsSync5, readFileSync as readFileSync3 } from "node:fs";
-import { dirname as dirname6, join as join7 } from "pathe";
+import { existsSync as existsSync8, readFileSync as readFileSync4 } from "node:fs";
+import { dirname as dirname6, join as join11 } from "pathe";
+
+// src/core/assets.ts
+import { join as join10 } from "pathe";
+var resolveAssetMounts = (root, assets) => assets.map((entry) => {
+  const rel = entry.replace(/^[./]+/u, "").replaceAll(/\.\.\/?/gu, "").replace(/\/+$/u, "");
+  return { dir: join10(root, rel), url: `/${rel}` };
+});
 
 // src/theme/fonts.ts
 var FALLBACKS = {
@@ -4000,17 +4198,17 @@ var WORKSPACE_MARKERS = [
   "yarn.lock"
 ];
 var hasWorkspacesField = (pkgPath) => {
-  if (!existsSync5(pkgPath)) {
+  if (!existsSync8(pkgPath)) {
     return false;
   }
   try {
-    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
     return pkg.workspaces !== undefined;
   } catch {
     return false;
   }
 };
-var hasWorkspaceMarker = (dir) => hasWorkspacesField(join7(dir, "package.json")) || WORKSPACE_MARKERS.some((marker) => existsSync5(join7(dir, marker)));
+var hasWorkspaceMarker = (dir) => hasWorkspacesField(join11(dir, "package.json")) || WORKSPACE_MARKERS.some((marker) => existsSync8(join11(dir, marker)));
 var findWorkspaceRoot = (start) => {
   let dir = start;
   for (;; ) {
@@ -4045,7 +4243,7 @@ var runtimeDependencies = (options) => {
   if (needsSvelte) {
     deps.push("@astrojs/svelte");
   }
-  if (config.openapi.enabled || config.asyncapi.enabled) {
+  if (hasScalarReferences(config)) {
     deps.push("@scalar/astro");
   }
   deps.push(...searchProviderMeta(config.search.provider).runtimeDeps);
@@ -4078,6 +4276,7 @@ var RENDER_EXTERNAL_DEPS = [
 ];
 var renderUserAliases = (aliases) => Object.entries(aliases ?? {}).toSorted(([a], [b]) => b.length - a.length).map(([find, replacement]) => `
         ${JSON.stringify(find)}: ${JSON.stringify(replacement)},`).join("");
+var astroOutDir = (context) => context.distDir ?? `${context.root}/dist`;
 var astroConfigTemplate = (options) => {
   const { context, config, needsReact, pages, dataPath, themePath } = options;
   const {
@@ -4085,6 +4284,7 @@ var astroConfigTemplate = (options) => {
     examplesPath,
     needsSvelte,
     needsVue,
+    openapiPath,
     searchClientPath
   } = options;
   const { deployment } = config;
@@ -4144,7 +4344,8 @@ var astroConfigTemplate = (options) => {
   if (needsSvelte) {
     integrations.push("svelte()");
   }
-  integrations.push(`blumeIntegration(${JSON.stringify({ contentRoutes, pages })})`);
+  const assets = resolveAssetMounts(context.root, config.content.assets);
+  integrations.push(`blumeIntegration(${JSON.stringify({ assets, base: deployment.base, contentRoutes, pages })})`);
   return `// Generated by Blume. Do not edit; this file is recreated on each run.
 ${defineConfigImport}
 import mdx from "@astrojs/mdx";
@@ -4154,7 +4355,7 @@ ${twoslashImport}${reactImport}${vueImport}${svelteImport}${blumeImport}${adapte
 export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
-  outDir: ${JSON.stringify(`${context.root}/dist`)},
+  outDir: ${JSON.stringify(astroOutDir(context))},
   publicDir: ${JSON.stringify(`${context.root}/public`)},
   output: ${JSON.stringify(deployment.output)},${adapterOption}${siteOption}${baseOption}${redirectsOption}${i18nOption}${fontsOption}
   integrations: [${integrations.join(", ")}],
@@ -4187,6 +4388,7 @@ export default defineConfig({
       alias: {
         "blume:data": ${JSON.stringify(dataPath)},
         "blume:examples": ${JSON.stringify(examplesPath)},
+        "blume:openapi": ${JSON.stringify(openapiPath)},
         "blume:search-client": ${JSON.stringify(searchClientPath)},
         "blume:theme": ${JSON.stringify(themePath)},${userAliasLines}
       },
@@ -4200,7 +4402,7 @@ export default defineConfig({
 });
 `;
 };
-var stagedContentDir = (outDir) => join7(outDir, "content");
+var stagedContentDir = (outDir) => join11(outDir, "content");
 var contentConfigTemplate = (options) => {
   const { context, config } = options;
   const stagedBase = options.stagedBase ?? stagedContentDir(context.outDir);
@@ -4257,31 +4459,44 @@ const provider = createOpenAICompatible({
     modelExpr = `provider(${JSON.stringify(backend.model)})`;
   }
   if (grounded) {
-    imports.push('import { createAskContext } from "blume/ai/ask-context.ts";', 'import askData from "../generated/ask-data.json";');
+    imports.push('import { createAskContext } from "blume/ai/ask-context.ts";', 'import askData from "../../generated/ask-data.json";');
     setup += `
 const ground = createAskContext(askData);
 `;
   }
-  const handler = grounded ? `export const POST: APIRoute = async ({ request }) => {
-  const { messages, page } = await request.json();
-  const system =
-    (await ground(messages, page)) ??
-    "You are a helpful documentation assistant. Answer using the project's documentation.";
-  const result = streamText({
-    model: ${modelExpr},
-    system,
-    messages,
-  });
-  return result.toTextStreamResponse();
-};` : `export const POST: APIRoute = async ({ request }) => {
-  const { messages } = await request.json();
-  const result = streamText({
-    model: ${modelExpr},
-    system:
-      "You are a helpful documentation assistant. Answer using the project's documentation.",
-    messages,
-  });
-  return result.toTextStreamResponse();
+  const validate = `  const body = await request.json().catch(() => null);
+  const messages = body?.messages;
+  if (
+    !Array.isArray(messages) ||
+    messages.length === 0 ||
+    messages.length > 40 ||
+    JSON.stringify(messages).length > 24_000
+  ) {
+    return new Response("Invalid request: send 1-40 messages.", {
+      status: 400,
+    });
+  }`;
+  const stream = grounded ? `    const system =
+      (await ground(messages, body.page)) ??
+      "You are a helpful documentation assistant. Answer using the project's documentation.";
+    const result = streamText({
+      model: ${modelExpr},
+      system,
+      messages,
+    });` : `    const result = streamText({
+      model: ${modelExpr},
+      system:
+        "You are a helpful documentation assistant. Answer using the project's documentation.",
+      messages,
+    });`;
+  const handler = `export const POST: APIRoute = async ({ request }) => {
+${validate}
+  try {
+${stream}
+    return result.toTextStreamResponse();
+  } catch {
+    return new Response("Failed to generate a response.", { status: 500 });
+  }
 };`;
   return `// Generated by Blume. Do not edit.
 ${imports.join(`
@@ -4593,7 +4808,10 @@ import FileTree from "blume/components/content/FileTree.astro";
 import Frame from "blume/components/content/Frame.astro";
 import GithubInfo from "blume/components/content/GithubInfo.astro";
 import Panel from "blume/components/content/Panel.astro";
+import ParamField from "blume/components/content/ParamField.astro";
 import Prompt from "blume/components/content/Prompt.astro";
+import RequestField from "blume/components/content/RequestField.astro";
+import ResponseField from "blume/components/content/ResponseField.astro";
 import Step from "blume/components/content/Step.astro";
 import Steps from "blume/components/content/Steps.astro";
 import Tab from "blume/components/content/Tab.astro";
@@ -4605,7 +4823,10 @@ import TreeFile from "blume/components/content/TreeFile.astro";
 import TreeFolder from "blume/components/content/TreeFolder.astro";
 import TypeTable from "blume/components/content/TypeTable.astro";
 import Visibility from "blume/components/content/Visibility.astro";
+import YouTube from "blume/components/content/YouTube.astro";
 import Icon from "blume/components/Icon.astro";
+import ApiOverview from "blume/components/openapi/ApiOverview.astro";
+import Operation from "blume/components/openapi/Operation.astro";
 ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../generated/components.ts";
 import { islandComponents } from "../generated/islands.ts";
 import data from "../generated/data.json";
@@ -4622,6 +4843,7 @@ export const prerender = true;
 const components = {
   Accordion,
   AccordionItem,
+  ApiOverview,
   AutoTypeTable,
   Badge,
   Callout,
@@ -4639,8 +4861,12 @@ const components = {
   Frame,
   GithubInfo,
   Icon,
+  Operation,
   Panel,
+  ParamField,
   Prompt,
+  RequestField,
+  ResponseField,
   Step,
   Steps,
   Tab,
@@ -4650,6 +4876,7 @@ const components = {
   Tree,
   TypeTable,
   Visibility,
+  YouTube,
   ${mathEntry}...islandComponents,
   ...userMdx,
 };
@@ -5039,6 +5266,11 @@ declare module "blume:data" {
   export default data;
 }
 
+declare module "blume:openapi" {
+  const specs: import("blume/openapi/model.ts").OpenApiData;
+  export default specs;
+}
+
 declare module "blume:search-client" {
   export const createSearch: () =>
     | import("blume/components/layout/search/types.ts").SearchFn
@@ -5061,8 +5293,9 @@ var runtimeTsconfigTemplate = () => `${JSON.stringify({
 `;
 
 // src/theme/palette.ts
+var FALLBACK_ACCENT = "oklch(0.62 0.16 250)";
 var ACCENTS = {
-  blue: "oklch(0.62 0.16 250)",
+  blue: FALLBACK_ACCENT,
   green: "oklch(0.6 0.16 150)",
   orange: "oklch(0.68 0.17 50)",
   pink: "oklch(0.65 0.2 350)",
@@ -5070,6 +5303,9 @@ var ACCENTS = {
   red: "oklch(0.58 0.22 25)",
   teal: "oklch(0.6 0.12 195)"
 };
+var CSS_COLOR = /^[\w\s#%.,()/+-]+$/u;
+var safeColor = (value, fallback) => CSS_COLOR.test(value.trim()) ? value.trim() : fallback;
+var safeColorOrNull = (value) => value && CSS_COLOR.test(value.trim()) ? value.trim() : null;
 var RADII = {
   lg: "0.75rem",
   md: "0.5rem",
@@ -5104,7 +5340,7 @@ var themeRootCss = (theme, options) => [
   `  --blume-accent: ${options.accent};`,
   ...cssToken("--blume-action", options.action),
   ...cssToken("--blume-action-foreground", options.action ? "oklch(1 0 0)" : null),
-  ...cssToken("--blume-background", theme.background),
+  ...cssToken("--blume-background", safeColorOrNull(theme.background)),
   ...cssToken("--blume-background-image", theme.backgroundImage ? backgroundImageCss(theme.backgroundImage) : null),
   options.backgroundDecoration.trimEnd(),
   `  --blume-radius: ${options.radius};`
@@ -5113,7 +5349,7 @@ var themeRootCss = (theme, options) => [
 var themeDarkCss = (theme, accentDark) => {
   const tokens = [
     ...cssToken("--blume-accent", accentDark),
-    ...cssToken("--blume-background", theme.backgroundDark),
+    ...cssToken("--blume-background", safeColorOrNull(theme.backgroundDark)),
     ...cssToken("--blume-background-image", theme.backgroundImageDark ? backgroundImageCss(theme.backgroundImageDark) : null)
   ];
   if (tokens.length === 0) {
@@ -5125,12 +5361,12 @@ ${tokens.join(`
 }
 `;
 };
-var resolveAccent = (theme) => ACCENTS[theme.accent] ?? theme.accent;
+var resolveAccent = (theme) => ACCENTS[theme.accent] ?? safeColor(theme.accent, FALLBACK_ACCENT);
 var resolveRadius = (theme) => RADII[theme.radius];
 var buildThemeCss = (theme) => {
-  const accent = ACCENTS[theme.accent] ?? theme.accent;
-  const accentDark = theme.accentDark ? ACCENTS[theme.accentDark] ?? theme.accentDark : null;
-  const action = theme.action ? ACCENTS[theme.action] ?? theme.action : null;
+  const accent = ACCENTS[theme.accent] ?? safeColor(theme.accent, FALLBACK_ACCENT);
+  const accentDark = theme.accentDark ? ACCENTS[theme.accentDark] ?? safeColor(theme.accentDark, FALLBACK_ACCENT) : null;
+  const action = theme.action ? ACCENTS[theme.action] ?? safeColor(theme.action, FALLBACK_ACCENT) : null;
   const backgroundDecoration = backgroundDecorationCss(theme.backgroundDecoration);
   const radius = RADII[theme.radius];
   const root = themeRootCss(theme, {
@@ -5149,57 +5385,11 @@ ${dark}`;
 
 // src/openapi/scalar.ts
 var URL_SPEC = /^https?:\/\//u;
-var NON_SLUG = /[^a-z0-9]+/gu;
-var SLUG_EDGES = /^-+|-+$/gu;
-var ROUTE_EDGES = /^\/+|\/+$/gu;
-var TRAILING_SLASH = /\/+$/u;
-var slugify = (text) => text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
-var normalizeRoute = (route) => {
-  const trimmed = route.trim();
-  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  const noTrailing = withSlash.replace(TRAILING_SLASH, "");
-  return noTrailing === "" ? "/" : noTrailing;
-};
+var ROUTE_EDGES2 = /^\/+|\/+$/gu;
 var referencePagePath = (route) => {
-  const segments = route.replace(ROUTE_EDGES, "");
+  const segments = route.replace(ROUTE_EDGES2, "");
   return `${segments === "" ? "index" : segments}.astro`;
 };
-var sourcesOf = (block) => {
-  const sources = [...block.sources];
-  if (block.spec) {
-    sources.unshift({ spec: block.spec });
-  }
-  return sources;
-};
-var referencesFor = (kind, block, defaultLabel) => {
-  if (!block.enabled) {
-    return [];
-  }
-  const sources = sourcesOf(block);
-  const base = normalizeRoute(block.route);
-  return sources.map((source, index) => {
-    const label = source.label ?? (sources.length > 1 ? `${defaultLabel} ${index + 1}` : defaultLabel);
-    let route;
-    if (source.route) {
-      route = normalizeRoute(source.route);
-    } else if (sources.length === 1) {
-      route = base;
-    } else {
-      const suffix = source.label ? slugify(source.label) : "";
-      route = normalizeRoute(`${base}/${suffix || index + 1}`);
-    }
-    return { kind, label, route, spec: source.spec, theme: block.theme };
-  });
-};
-var resolveReferences = (config) => [
-  ...referencesFor("openapi", config.openapi, "API Reference"),
-  ...referencesFor("asyncapi", config.asyncapi, "Events")
-];
-var referenceTabs = (config) => resolveReferences(config).map((ref) => ({
-  label: ref.label,
-  path: ref.route
-}));
-var hasReferences = (config) => config.openapi.enabled || config.asyncapi.enabled;
 var darkModeConfig = (mode) => {
   if (mode === "dark") {
     return { darkMode: true };
@@ -5224,9 +5414,9 @@ var specConfiguration = async (spec, root) => {
   if (URL_SPEC.test(spec)) {
     return { config: { url: spec } };
   }
-  const absolute = isAbsolute3(spec) ? spec : join8(root, spec);
+  const absolute = isAbsolute4(spec) ? spec : join12(root, spec);
   try {
-    return { config: { content: await readFile4(absolute, "utf-8") } };
+    return { config: { content: await readFile5(absolute, "utf-8") } };
   } catch {
     return {
       config: { url: spec },
@@ -5240,6 +5430,9 @@ var buildReferenceFiles = async (options) => {
   const seen = new Set;
   const accepted = [];
   for (const ref of resolveReferences(config)) {
+    if (ref.renderer !== "scalar") {
+      continue;
+    }
     if (seen.has(ref.route)) {
       warnings.push(`Two API reference sources resolve to ${ref.route}; keeping the first.`);
       continue;
@@ -5278,37 +5471,315 @@ var buildReferenceFiles = async (options) => {
   return { files, warnings };
 };
 
-// src/theme/entry.ts
-var tailwindEntryTemplate = (options) => `/* Generated by Blume. Do not edit. */
-@import "tailwindcss";
-@plugin "@tailwindcss/typography";
-
-/* Scan Blume's components and the user's project for utility classes. */
-${options.sources.map((source) => `@source "${source}";`).join(`
-`)}
-
-/* Dark mode is driven by data-theme on the <html> element. */
-@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
-
-:root {
-  --blume-background: oklch(1 0 0);
-  --blume-background-decoration: none;
-  --blume-background-decoration-repeat: no-repeat;
-  --blume-background-decoration-size: auto;
-  --blume-background-image: none;
-  --blume-background-image-repeat: no-repeat;
-  --blume-background-image-size: cover;
-  --blume-foreground: oklch(0.145 0 0);
-  --blume-muted: oklch(0.965 0 0);
-  --blume-muted-foreground: oklch(0.54 0 0);
-  --blume-border: oklch(0.88 0.006 260 / 0.72);
-  --blume-accent: oklch(0.145 0 0);
-  --blume-accent-foreground: oklch(1 0 0);
-  --blume-action: var(--blume-accent);
-  --blume-action-foreground: var(--blume-accent-foreground);
-  --blume-code-background: oklch(0.99 0 0);
-  /* Shiki notation transformers: line/word highlight, diff add/remove. */
-  --blume-code-highlight: oklch(0.55 0.16 255 / 0.1);
+// src/core/sources/cache.ts
+import { mkdir as mkdir2, readFile as readFile6, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join13 } from "pathe";
+var hashText = (text) => {
+  let hash = 5381;
+  for (let i = 0;i < text.length; i += 1) {
+    hash = (hash * 33 + (text.codePointAt(i) ?? 0)) % 2147483647;
+  }
+  return hash.toString(36);
+};
+var entriesDigest = (entries) => hashText(entries.map((entry) => `${entry.ref}:${entry.hash ?? hashText(entry.body.text)}`).join("|"));
+var pollingWatch = (load2, intervalSeconds) => (onChange) => {
+  let last = "";
+  const tick = async () => {
+    try {
+      const { entries } = await load2();
+      const next = entriesDigest(entries);
+      if (last && next !== last) {
+        onChange();
+      }
+      last = next;
+    } catch {}
+  };
+  const timer = setInterval(() => {
+    tick();
+  }, intervalSeconds * 1000);
+  return () => clearInterval(timer);
+};
+var snapshotCache = (cacheDir) => {
+  const file = join13(cacheDir, "entries.json");
+  return {
+    read: async () => {
+      try {
+        return JSON.parse(await readFile6(file, "utf-8"));
+      } catch {
+        return [];
+      }
+    },
+    write: async (entries) => {
+      try {
+        await mkdir2(cacheDir, { recursive: true });
+        await writeFile3(file, `${JSON.stringify(entries)}
+`, "utf-8");
+      } catch {}
+    }
+  };
+};
+var loadWithCache = async (name, cache, fetchEntries, refresh = true) => {
+  if (!refresh) {
+    const cached3 = await cache.read();
+    if (cached3.length > 0) {
+      return { diagnostics: [], entries: cached3 };
+    }
+  }
+  try {
+    const entries = await fetchEntries();
+    await cache.write(entries);
+    return { diagnostics: [], entries };
+  } catch (error) {
+    const fallback = await cache.read();
+    if (fallback.length > 0) {
+      const diagnostic = {
+        code: "BLUME_SOURCE_OFFLINE",
+        message: `Source "${name}" could not be fetched (${error.message}); served ${fallback.length} cached entries.`,
+        severity: "warning"
+      };
+      return { diagnostics: [diagnostic], entries: fallback };
+    }
+    throw new BlumeError({
+      code: "BLUME_SOURCE_FETCH_FAILED",
+      message: `Source "${name}" failed to load and no cache is available: ${error.message}`,
+      severity: "error"
+    });
+  }
+};
+
+// src/openapi/model.ts
+var NON_SLUG2 = /[^a-z0-9]+/gu;
+var SLUG_EDGES2 = /^-+|-+$/gu;
+var slugify2 = (text) => text.toLowerCase().replace(NON_SLUG2, "-").replace(SLUG_EDGES2, "");
+var HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace"
+];
+var UNTAGGED = "Operations";
+var operationKey = (method, path, operationId) => {
+  const fromId = operationId ? slugify2(operationId) : "";
+  return fromId || slugify2(`${method}-${path}`);
+};
+var isOperation = (value) => typeof value === "object" && value !== null;
+var extractOperations = (document, baseRoute) => {
+  const operations = [];
+  const tagOrder = [];
+  const tagMeta = new Map((document.tags ?? []).map((tag) => [tag.name, tag.description ?? ""]));
+  const seen = new Set;
+  for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
+    const item = rawItem;
+    if (!item || "$ref" in item) {
+      continue;
+    }
+    for (const method of HTTP_METHODS) {
+      const operation = item[method];
+      if (!isOperation(operation)) {
+        continue;
+      }
+      const tag = operation.tags?.[0] ?? UNTAGGED;
+      const tagSlug = slugify2(tag) || "operations";
+      if (!tagOrder.includes(tag)) {
+        tagOrder.push(tag);
+      }
+      let key = operationKey(method, path, operation.operationId);
+      while (seen.has(key)) {
+        key = `${key}-${method}`;
+      }
+      seen.add(key);
+      operations.push({
+        deprecated: operation.deprecated ?? false,
+        description: operation.description ?? "",
+        key,
+        method,
+        operationId: operation.operationId,
+        path,
+        route: `${baseRoute}/${tagSlug}/${key}`,
+        summary: operation.summary ?? "",
+        tag,
+        tagSlug
+      });
+    }
+  }
+  const tags = tagOrder.map((name) => ({
+    description: tagMeta.get(name) ?? "",
+    name,
+    slug: slugify2(name) || "operations"
+  }));
+  return { operations, tags };
+};
+
+// src/openapi/parse.ts
+import { readFile as readFile7 } from "node:fs/promises";
+import { normalize as normalize2, upgrade } from "@scalar/openapi-parser";
+import { isAbsolute as isAbsolute5, join as join14 } from "pathe";
+var URL_SPEC2 = /^https?:\/\//u;
+var readSpecText = async (spec, root) => {
+  if (URL_SPEC2.test(spec)) {
+    const response = await fetch(spec);
+    if (!response.ok) {
+      throw new Error(`${spec} -> ${response.status} ${response.statusText}`);
+    }
+    return await response.text();
+  }
+  const absolute = isAbsolute5(spec) ? spec : join14(root, spec);
+  return await readFile7(absolute, "utf-8");
+};
+var parseSpec = async (spec, root) => {
+  const text = await readSpecText(spec, root);
+  const normalized = normalize2(text);
+  const { specification } = upgrade(normalized);
+  return { document: specification, warnings: [] };
+};
+
+// src/openapi/render-mdx.ts
+var MDX_UNSAFE = /[<>{}]/gu;
+var ENTITIES = {
+  "<": "&lt;",
+  ">": "&gt;",
+  "{": "&#123;",
+  "}": "&#125;"
+};
+var mdxSafe = (text) => text.replace(MDX_UNSAFE, (char) => ENTITIES[char] ?? char);
+var withDescription = (description, component) => description.trim() ? `${mdxSafe(description.trim())}
+
+${component}` : component;
+var operationMdx = (spec, operation) => {
+  const method = operation.method.toUpperCase();
+  const title = operation.summary || `${method} ${operation.path}`;
+  const description = operation.description.trim() === operation.summary.trim() ? "" : operation.description;
+  return {
+    body: withDescription(description, `<Operation source="${spec.slug}" id="${operation.key}" />`),
+    data: {
+      ...operation.deprecated ? { deprecated: true } : {},
+      search: { tags: [operation.tag, method] },
+      sidebar: { badge: method, label: operation.summary || operation.path },
+      title,
+      type: "openapi-operation"
+    }
+  };
+};
+var overviewMdx = (spec) => ({
+  body: withDescription(spec.description, `<ApiOverview source="${spec.slug}" />`),
+  data: {
+    sidebar: { label: "Overview" },
+    title: spec.title || spec.label
+  }
+});
+
+// src/openapi/source.ts
+var isOpenApiSource = (source) => source.kind === "openapi-source";
+var routeToRef = (route) => route.replace(/^\/+/u, "");
+var toEntry = (rendered, ref) => {
+  const raw = frontmatter_default.stringify(`${rendered.body}
+`, rendered.data);
+  return {
+    body: { format: "mdx", text: rendered.body },
+    data: rendered.data,
+    hash: hashText(raw),
+    raw,
+    ref
+  };
+};
+var specEntries = (spec, operations) => {
+  const entries = operations.map((operation) => toEntry(operationMdx(spec, operation), `${routeToRef(operation.route)}.mdx`));
+  entries.push(toEntry(overviewMdx(spec), `${routeToRef(spec.route)}/index.mdx`));
+  return entries;
+};
+var openApiSource = (references, ctx) => {
+  let parsed = {};
+  const loadReference = async (reference) => {
+    try {
+      const { document } = await parseSpec(reference.spec, ctx.projectRoot);
+      const { operations, tags } = extractOperations(document, reference.route);
+      const info = document.info ?? { title: reference.label, version: "" };
+      const spec = {
+        codeSamples: reference.display.codeSamples,
+        description: info.description ?? "",
+        document,
+        expandSchemas: reference.display.expandSchemas,
+        label: reference.label,
+        operations: Object.fromEntries(operations.map((operation) => [operation.key, operation])),
+        route: reference.route,
+        slug: reference.slug,
+        tags,
+        title: info.title ?? reference.label,
+        version: info.version ?? ""
+      };
+      return {
+        entries: specEntries(spec, operations),
+        slug: reference.slug,
+        spec
+      };
+    } catch (error) {
+      return {
+        code: "BLUME_OPENAPI_UNAVAILABLE",
+        message: `Could not load OpenAPI spec "${reference.spec}" for ${reference.route} (${error.message}); its reference pages were skipped.`,
+        severity: "warning"
+      };
+    }
+  };
+  const load2 = async () => {
+    const results = await Promise.all(references.map(loadReference));
+    const entries = [];
+    const diagnostics = [];
+    const data = {};
+    for (const result of results) {
+      if ("severity" in result) {
+        diagnostics.push(result);
+        continue;
+      }
+      data[result.slug] = result.spec;
+      entries.push(...result.entries);
+    }
+    parsed = data;
+    return { diagnostics, entries };
+  };
+  return {
+    kind: "openapi-source",
+    load: load2,
+    name: "openapi",
+    openApiData: () => parsed,
+    staged: true
+  };
+};
+
+// src/theme/entry.ts
+var tailwindEntryTemplate = (options) => `/* Generated by Blume. Do not edit. */
+@import "tailwindcss";
+@plugin "@tailwindcss/typography";
+
+/* Scan Blume's components and the user's project for utility classes. */
+${options.sources.map((source) => `@source "${source}";`).join(`
+`)}
+
+/* Dark mode is driven by data-theme on the <html> element. */
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
+
+:root {
+  --blume-background: oklch(1 0 0);
+  --blume-background-decoration: none;
+  --blume-background-decoration-repeat: no-repeat;
+  --blume-background-decoration-size: auto;
+  --blume-background-image: none;
+  --blume-background-image-repeat: no-repeat;
+  --blume-background-image-size: cover;
+  --blume-foreground: oklch(0.145 0 0);
+  --blume-muted: oklch(0.965 0 0);
+  --blume-muted-foreground: oklch(0.54 0 0);
+  --blume-border: oklch(0.88 0.006 260 / 0.72);
+  --blume-accent: oklch(0.145 0 0);
+  --blume-accent-foreground: oklch(1 0 0);
+  --blume-action: var(--blume-accent);
+  --blume-action-foreground: var(--blume-accent-foreground);
+  --blume-code-background: oklch(0.99 0 0);
+  /* Shiki notation transformers: line/word highlight, diff add/remove. */
+  --blume-code-highlight: oklch(0.55 0.16 255 / 0.1);
   --blume-code-highlight-border: oklch(0.55 0.16 255 / 0.55);
   --blume-code-add: oklch(0.72 0.16 150 / 0.16);
   --blume-code-add-border: oklch(0.52 0.15 150 / 0.7);
@@ -5897,9 +6368,9 @@ ${options.userTheme}
 `;
 
 // src/theme/twoslash.ts
-import { readFileSync as readFileSync4 } from "node:fs";
-import { createRequire as createRequire3 } from "node:module";
-var require2 = createRequire3(import.meta.url);
+import { readFileSync as readFileSync5 } from "node:fs";
+import { createRequire as createRequire4 } from "node:module";
+var require2 = createRequire4(import.meta.url);
 var OVERRIDES = `
 /* Twoslash: theme the rich renderer with Blume tokens. */
 :root {
@@ -5959,7 +6430,7 @@ var OVERRIDES = `
 `;
 var twoslashCss = () => {
   const file = require2.resolve("@shikijs/twoslash/style-rich.css");
-  return `${readFileSync4(file, "utf-8")}
+  return `${readFileSync5(file, "utf-8")}
 ${OVERRIDES}`;
 };
 
@@ -6061,13 +6532,13 @@ export const layoutOverrides = { ...(overrides.layout ?? {})${layoutEntries.leng
 };
 
 // src/astro/examples.ts
-import { readFile as readFile6 } from "node:fs/promises";
-import { join as join10, relative as relative4 } from "pathe";
+import { readFile as readFile9 } from "node:fs/promises";
+import { join as join16, relative as relative4 } from "pathe";
 import { glob as glob2 } from "tinyglobby";
 
 // src/astro/islands.ts
-import { readFile as readFile5 } from "node:fs/promises";
-import { basename, join as join9 } from "pathe";
+import { readFile as readFile8 } from "node:fs/promises";
+import { basename, join as join15 } from "pathe";
 import { glob } from "tinyglobby";
 var DEFAULT_CLIENT = "visible";
 var VALID_MODES = new Set([
@@ -6096,14 +6567,14 @@ var readClientMode = (source, file, warnings) => {
   return mode;
 };
 var discoverIslands = async (root) => {
-  const dir = join9(root, "islands");
+  const dir = join15(root, "islands");
   const matches = await glob(["**/*.{jsx,svelte,tsx,vue}"], {
     absolute: true,
     cwd: dir,
     onlyFiles: true
   });
   const files = matches.toSorted();
-  const sources = await Promise.all(files.map((file) => readFile5(file, "utf-8")));
+  const sources = await Promise.all(files.map((file) => readFile8(file, "utf-8")));
   const islands = [];
   const warnings = [];
   const seen = new Map;
@@ -6115,8 +6586,8 @@ var discoverIslands = async (root) => {
       continue;
     }
     const name = base.replace(ISLAND_FILE, "");
-    if (!/^[A-Z]/u.test(name)) {
-      warnings.push(`Island "${file}" must have a PascalCase filename to be used in MDX (e.g. Counter.tsx → <Counter />); skipping it.`);
+    if (!/^[A-Z][A-Za-z0-9_]*$/u.test(name)) {
+      warnings.push(`Island "${file}" must have a PascalCase identifier filename to be used in MDX (letters, digits, and underscores only, e.g. Counter.tsx → <Counter />); skipping it.`);
       continue;
     }
     const existing = seen.get(name);
@@ -6159,14 +6630,14 @@ 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 = join10(root, base);
+  const dir = join16(root, base);
   const matches = await glob2([rest], {
     absolute: true,
     cwd: dir,
     onlyFiles: true
   });
   const files = matches.toSorted();
-  const sources = await Promise.all(files.map((file) => readFile6(file, "utf-8")));
+  const sources = await Promise.all(files.map((file) => readFile9(file, "utf-8")));
   const examples = [];
   const warnings = [];
   const seen = new Map;
@@ -6209,7 +6680,10 @@ var discoverPages = async (pagesRoot) => {
   return files.map((file) => {
     const rel = relative5(pagesRoot, file);
     const withoutExt = rel.slice(0, rel.length - extname2(rel).length);
-    const parts = withoutExt.split("/").filter((part) => part !== "index");
+    const parts = withoutExt.split("/");
+    if (parts.at(-1) === "index") {
+      parts.pop();
+    }
     const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
     return { entrypoint: file, pattern };
   });
@@ -6237,10 +6711,10 @@ var customOgRoutes = (pages, siteTitle) => {
 };
 
 // src/astro/generate.ts
-var BLUME_SRC = join11(packageRoot(), "src");
+var BLUME_SRC = join17(packageRoot(), "src");
 var canResolveFrom = (fromDir, spec) => {
   try {
-    createRequire4(pathToFileURL2(join11(fromDir, "_.js")).href).resolve(spec);
+    createRequire5(pathToFileURL2(join17(fromDir, "_.js")).href).resolve(spec);
     return true;
   } catch {
     return false;
@@ -6248,15 +6722,15 @@ var canResolveFrom = (fromDir, spec) => {
 };
 var resolvedAstroPath = (fromDir) => {
   try {
-    const pkg = createRequire4(pathToFileURL2(join11(fromDir, "_.js")).href).resolve("astro/package.json");
+    const pkg = createRequire5(pathToFileURL2(join17(fromDir, "_.js")).href).resolve("astro/package.json");
     return realpathSync(pkg);
   } catch {
     return null;
   }
 };
 var blumeDepsDir = (pkgDir = packageRoot()) => {
-  const candidates = [join11(pkgDir, "node_modules"), dirname7(pkgDir)];
-  return candidates.find((dir) => existsSync6(join11(dir, "astro"))) ?? null;
+  const candidates = [join17(pkgDir, "node_modules"), dirname7(pkgDir)];
+  return candidates.find((dir) => existsSync9(join17(dir, "astro"))) ?? null;
 };
 var linkDepsJunction = async (link, depsDir) => {
   const existing = await lstat(link).catch(() => null);
@@ -6266,7 +6740,7 @@ var linkDepsJunction = async (link, depsDir) => {
     }
     await rm(link, { force: true });
   }
-  await mkdir2(dirname7(link), { recursive: true });
+  await mkdir3(dirname7(link), { recursive: true });
   await symlink(depsDir, link, "junction");
 };
 var readPkgVersion = (pkgJsonPath) => {
@@ -6274,7 +6748,7 @@ var readPkgVersion = (pkgJsonPath) => {
     return null;
   }
   try {
-    return JSON.parse(readFileSync5(pkgJsonPath, "utf-8")).version ?? null;
+    return JSON.parse(readFileSync6(pkgJsonPath, "utf-8")).version ?? null;
   } catch {
     return null;
   }
@@ -6296,8 +6770,8 @@ var ensureDepsLink = async (outDir, pkgDir = packageRoot()) => {
   if (blumeAstro && outDirAstro === blumeAstro) {
     return null;
   }
-  if (existsSync6(join11(depsDir, "@astrojs", "mdx"))) {
-    await linkDepsJunction(join11(outDir, "node_modules"), depsDir);
+  if (existsSync9(join17(depsDir, "@astrojs", "mdx"))) {
+    await linkDepsJunction(join17(outDir, "node_modules"), depsDir);
     return null;
   }
   return astroConflictWarning(blumeAstro, outDirAstro);
@@ -6321,7 +6795,7 @@ var readOptional = async (path) => {
     return "";
   }
   try {
-    return await readFile7(path, "utf-8");
+    return await readFile10(path, "utf-8");
   } catch {
     return "";
   }
@@ -6337,16 +6811,16 @@ var detectNeedsReact = async (root) => {
 var writeIfChanged = async (path, content) => {
   let existing = null;
   try {
-    existing = await readFile7(path, "utf-8");
+    existing = await readFile10(path, "utf-8");
   } catch {
     existing = null;
   }
   if (existing === content) {
     return false;
   }
-  await mkdir2(dirname7(path), { recursive: true });
+  await mkdir3(dirname7(path), { recursive: true });
   const tmp = `${path}.${process.pid}.tmp`;
-  await writeFile2(tmp, content, "utf-8");
+  await writeFile4(tmp, content, "utf-8");
   try {
     await rename(tmp, path);
   } catch (error) {
@@ -6361,7 +6835,7 @@ var pruneOrphans = async (srcDir, written) => {
     cwd: srcDir,
     onlyFiles: true
   });
-  await Promise.all(existing.map((path) => normalize(path)).filter((path) => !written.has(path)).map((path) => rm(path, { force: true })));
+  await Promise.all(existing.map((path) => normalize3(path)).filter((path) => !written.has(path)).map((path) => rm(path, { force: true })));
 };
 var collectStaged = (project) => {
   const staged = new Map;
@@ -6376,11 +6850,11 @@ var writeStagedContent = async (out, staged) => {
   const contentDir = stagedContentDir(out);
   const written = new Set;
   await Promise.all([...staged].map(async ([entryId, text]) => {
-    const path = join11(contentDir, entryId);
-    written.add(normalize(path));
+    const path = join17(contentDir, entryId);
+    written.add(normalize3(path));
     await writeIfChanged(path, text);
   }));
-  if (existsSync6(contentDir)) {
+  if (existsSync9(contentDir)) {
     await pruneOrphans(contentDir, written);
   }
 };
@@ -6397,11 +6871,11 @@ var resolveLogo = (project) => {
   if (light && light === dark && light.toLowerCase().endsWith(".svg")) {
     const rel = light.replace(/^\//u, "");
     const file = [
-      join11(project.context.root, "public", rel),
-      join11(project.context.root, rel)
-    ].find((path) => existsSync6(path));
+      join17(project.context.root, "public", rel),
+      join17(project.context.root, rel)
+    ].find((path) => existsSync9(path));
     if (file) {
-      return { alt, href, svg: readFileSync5(file, "utf-8") };
+      return { alt, href, svg: readFileSync6(file, "utf-8") };
     }
   }
   return { alt, dark, href, light };
@@ -6425,9 +6899,9 @@ var faviconType = (name) => {
   const ext = name.split(".").pop()?.toLowerCase();
   return ext ? FAVICON_TYPES[ext] : undefined;
 };
-var inlineDataUri = (file, type) => `data:${type};base64,${readFileSync5(file).toString("base64")}`;
+var inlineDataUri = (file, type) => `data:${type};base64,${readFileSync6(file).toString("base64")}`;
 var defaultFavicon = () => ({
-  href: inlineDataUri(join11(BLUME_SRC, "assets", "icon.png"), "image/png"),
+  href: inlineDataUri(join17(BLUME_SRC, "assets", "icon.png"), "image/png"),
   type: "image/png"
 });
 var APPLE_ICON_CANDIDATES = [
@@ -6439,13 +6913,13 @@ var APPLE_ICON_CANDIDATES = [
 var resolveIconFile = (project, candidates) => {
   const { root } = project.context;
   for (const name of candidates) {
-    if (existsSync6(join11(root, "public", name))) {
+    if (existsSync9(join17(root, "public", name))) {
       return { href: `/${name}`, type: faviconType(name) };
     }
   }
   for (const name of candidates) {
-    const file = join11(root, name);
-    if (existsSync6(file)) {
+    const file = join17(root, name);
+    if (existsSync9(file)) {
       const type = faviconType(name);
       return { href: inlineDataUri(file, type ?? "image/x-icon"), type };
     }
@@ -6527,6 +7001,7 @@ var buildRuntimeData = (project) => {
           label
         }))
       } : null,
+      icons: config.icons,
       imageZoom: config.markdown.imageZoom,
       logo: resolveLogo(project),
       mcp: config.mcp.enabled ? { name: config.mcp.name ?? config.title, route: config.mcp.route } : null,
@@ -6573,7 +7048,7 @@ var buildRuntimeData = (project) => {
 var planMcp = (project, srcDir) => {
   const { config } = project;
   const { route } = config.mcp;
-  const dir = join11(srcDir, "blume-mcp");
+  const dir = join17(srcDir, "blume-mcp");
   const base = {
     dir,
     discoveryPages: [],
@@ -6597,11 +7072,11 @@ var planMcp = (project, srcDir) => {
     ...base,
     discoveryPages: [
       {
-        entrypoint: join11(dir, "discovery.ts"),
+        entrypoint: join17(dir, "discovery.ts"),
         pattern: "/.well-known/mcp.json"
       },
       {
-        entrypoint: join11(dir, "server-card.ts"),
+        entrypoint: join17(dir, "server-card.ts"),
         pattern: "/.well-known/mcp/server-card.json"
       }
     ],
@@ -6620,11 +7095,11 @@ var writeMcpFiles = async (project, plan, write) => {
     version: data.version
   };
   await Promise.all([
-    write(join11(plan.srcDir, "generated", "mcp-data.json"), `${JSON.stringify(data)}
+    write(join17(plan.srcDir, "generated", "mcp-data.json"), `${JSON.stringify(data)}
 `),
-    write(join11(plan.srcDir, "pages", mcpPageFile(plan.route)), mcpEndpointTemplate(plan.route)),
-    write(join11(plan.dir, "discovery.ts"), staticJsonEndpointTemplate(buildMcpDiscovery(discoveryInput))),
-    write(join11(plan.dir, "server-card.ts"), staticJsonEndpointTemplate(buildMcpServerCard(discoveryInput)))
+    write(join17(plan.srcDir, "pages", mcpPageFile(plan.route)), mcpEndpointTemplate(plan.route)),
+    write(join17(plan.dir, "discovery.ts"), staticJsonEndpointTemplate(buildMcpDiscovery(discoveryInput))),
+    write(join17(plan.dir, "server-card.ts"), staticJsonEndpointTemplate(buildMcpServerCard(discoveryInput)))
   ]);
 };
 var writeAskFiles = async (project, srcDir, write) => {
@@ -6634,16 +7109,16 @@ var writeAskFiles = async (project, srcDir, write) => {
   }
   const grounded = ask.provider !== "inkeep";
   if (grounded) {
-    await write(join11(srcDir, "generated", "ask-data.json"), `${JSON.stringify(await buildAskData(project))}
+    await write(join17(srcDir, "generated", "ask-data.json"), `${JSON.stringify(await buildAskData(project))}
 `);
   }
-  await write(join11(srcDir, "pages", "api", "ask.ts"), askEndpointTemplate(resolveAskBackend(ask), grounded));
+  await write(join17(srcDir, "pages", "api", "ask.ts"), askEndpointTemplate(resolveAskBackend(ask), grounded));
 };
 var writeNotFoundPage = async (write, srcDir, pages, contentPages) => {
   if (routeIsTaken(pages, contentPages, "/404")) {
     return;
   }
-  await write(join11(srcDir, "pages", "404.astro"), notFoundPageTemplate());
+  await write(join17(srcDir, "pages", "404.astro"), notFoundPageTemplate());
 };
 var shouldGenerateChangelog = (project) => {
   const hasChangelog = project.graph.pages.some((page) => page.contentType === "changelog" && !(page.meta.draft || page.meta.sidebar.hidden));
@@ -6652,7 +7127,7 @@ var shouldGenerateChangelog = (project) => {
   return (hasChangelog || hasChangelogSource) && !changelogRouteTaken;
 };
 var buildComponentSlots = async (componentsFile) => {
-  const analysis = componentsFile ? analyzeComponentOverrides(await readFile7(componentsFile, "utf-8"), componentsFile) : null;
+  const analysis = componentsFile ? analyzeComponentOverrides(await readFile10(componentsFile, "utf-8"), componentsFile) : null;
   return {
     plan: planComponentSlots(componentsFile, analysis),
     tags: analysis ? [...analysis.mdx, ...analysis.islands].map((entry) => entry.key) : [],
@@ -6662,14 +7137,15 @@ var buildComponentSlots = async (componentsFile) => {
 var generateRuntime = async (project) => {
   const { context, config } = project;
   const out = context.outDir;
-  const srcDir = join11(out, "src");
-  const dataPath = join11(srcDir, "generated", "data.json");
-  const themePath = join11(srcDir, "generated", "app.css");
-  const searchClientPath = join11(srcDir, "generated", "search-client.ts");
-  const examplesPath = join11(srcDir, "generated", "examples.ts");
+  const srcDir = join17(out, "src");
+  const dataPath = join17(srcDir, "generated", "data.json");
+  const themePath = join17(srcDir, "generated", "app.css");
+  const searchClientPath = join17(srcDir, "generated", "search-client.ts");
+  const examplesPath = join17(srcDir, "generated", "examples.ts");
+  const openapiPath = join17(srcDir, "generated", "openapi.json");
   const written = new Set;
   const write = (path, content) => {
-    written.add(normalize(path));
+    written.add(normalize3(path));
     return writeIfChanged(path, content);
   };
   const depsLinkWarning = await ensureDepsLink(out);
@@ -6702,7 +7178,7 @@ var generateRuntime = async (project) => {
   const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   const structural = await Promise.all([
-    write(join11(out, "astro.config.mjs"), astroConfigTemplate({
+    write(join17(out, "astro.config.mjs"), astroConfigTemplate({
       aliases: resolveTsconfigAliases(context.root),
       config,
       contentRoutes: project.manifest.routes.map((route) => route.path),
@@ -6712,24 +7188,25 @@ var generateRuntime = async (project) => {
       needsReact,
       needsSvelte,
       needsVue,
+      openapiPath,
       pages,
       searchClientPath,
       themePath
     })),
-    write(join11(out, "package.json"), runtimePackageTemplate(runtimeDependencies({ config, needsReact, needsSvelte, needsVue }))),
-    write(join11(out, "tsconfig.json"), runtimeTsconfigTemplate()),
-    write(join11(srcDir, "env.d.ts"), envTemplate()),
-    write(join11(srcDir, "content.config.ts"), contentConfigTemplate({ config, context, staged: hasStaged })),
-    write(join11(srcDir, "pages", "[...slug].astro"), catchAllPageTemplate({
+    write(join17(out, "package.json"), runtimePackageTemplate(runtimeDependencies({ config, needsReact, needsSvelte, needsVue }))),
+    write(join17(out, "tsconfig.json"), runtimeTsconfigTemplate()),
+    write(join17(srcDir, "env.d.ts"), envTemplate()),
+    write(join17(srcDir, "content.config.ts"), contentConfigTemplate({ config, context, staged: hasStaged })),
+    write(join17(srcDir, "pages", "[...slug].astro"), catchAllPageTemplate({
       askEnabled,
       exportEpub,
       exportPdf,
       mathEnabled: config.markdown.math,
       needsReact
     })),
-    write(join11(srcDir, "generated", "components.ts"), slotPlan.module),
-    write(join11(srcDir, "generated", "islands.ts"), islandMapTemplate(islandDiscovery.islands)),
-    write(join11(srcDir, "generated", "examples.ts"), exampleMapTemplate(exampleDiscovery.examples)),
+    write(join17(srcDir, "generated", "components.ts"), slotPlan.module),
+    write(join17(srcDir, "generated", "islands.ts"), islandMapTemplate(islandDiscovery.islands)),
+    write(join17(srcDir, "generated", "examples.ts"), exampleMapTemplate(exampleDiscovery.examples)),
     write(themePath, tailwindEntryTemplate({
       configTokens: `${buildThemeCss(config.theme)}${buildFontsCss(config.theme.fonts)}`,
       sources: [
@@ -6740,16 +7217,16 @@ var generateRuntime = async (project) => {
       userTheme
     }))
   ]);
-  await Promise.all(islandDiscovery.islands.map((island) => write(join11(srcDir, "generated", "islands", `${island.name}.astro`), islandWrapperTemplate(island))));
-  await Promise.all(slotPlan.wrappers.map((wrapper) => write(join11(srcDir, "generated", "component-slots", `${wrapper.name}.astro`), wrapper.content)));
-  await Promise.all(exampleDiscovery.examples.map((example) => write(join11(srcDir, "generated", "examples", `${exampleSlug(example.path)}.astro`), exampleWrapperTemplate(example))));
+  await Promise.all(islandDiscovery.islands.map((island) => write(join17(srcDir, "generated", "islands", `${island.name}.astro`), islandWrapperTemplate(island))));
+  await Promise.all(slotPlan.wrappers.map((wrapper) => write(join17(srcDir, "generated", "component-slots", `${wrapper.name}.astro`), wrapper.content)));
+  await Promise.all(exampleDiscovery.examples.map((example) => write(join17(srcDir, "generated", "examples", `${exampleSlug(example.path)}.astro`), exampleWrapperTemplate(example))));
   await writeAskFiles(project, srcDir, write);
   await writeMcpFiles(project, mcp, write);
   if (config.seo.og.enabled) {
-    await write(join11(srcDir, "pages", "og", "[...slug].png.ts"), ogEndpointTemplate(ogRoutes));
+    await write(join17(srcDir, "pages", "og", "[...slug].png.ts"), ogEndpointTemplate(ogRoutes));
   }
   if (shouldGenerateChangelog(project)) {
-    await write(join11(srcDir, "pages", "changelog.astro"), changelogIndexTemplate({
+    await write(join17(srcDir, "pages", "changelog.astro"), changelogIndexTemplate({
       askEnabled,
       exportEpub,
       exportPdf,
@@ -6761,27 +7238,27 @@ var generateRuntime = async (project) => {
   await write(searchClientPath, searchClientTemplate(config));
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);
-    await write(join11(srcDir, "generated", "search.json"), `${JSON.stringify(documents)}
+    await write(join17(srcDir, "generated", "search.json"), `${JSON.stringify(documents)}
 `);
-    await write(join11(srcDir, "pages", "blume-search.json.ts"), searchEndpointTemplate());
+    await write(join17(srcDir, "pages", "blume-search.json.ts"), searchEndpointTemplate());
   }
   if (config.search.provider === "mixedbread") {
-    await write(join11(srcDir, "pages", "api", "search.ts"), mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? ""));
+    await write(join17(srcDir, "pages", "api", "search.ts"), mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? ""));
   }
   const rawMarkdown = await buildRawMarkdown(project);
   await Promise.all([
-    write(join11(srcDir, "generated", "raw-markdown.json"), `${JSON.stringify(rawMarkdown)}
+    write(join17(srcDir, "generated", "raw-markdown.json"), `${JSON.stringify(rawMarkdown)}
 `),
-    write(join11(srcDir, "pages", "[...slug].md.ts"), rawMarkdownEndpointTemplate()),
-    write(join11(srcDir, "pages", "[...slug].mdx.ts"), rawMarkdownEndpointTemplate())
+    write(join17(srcDir, "pages", "[...slug].md.ts"), rawMarkdownEndpointTemplate()),
+    write(join17(srcDir, "pages", "[...slug].mdx.ts"), rawMarkdownEndpointTemplate())
   ]);
   const feeds = buildRssFeeds(project);
   if (feeds.length > 0) {
     const feedXml = Object.fromEntries(feeds.map((feed) => [feed.type, renderRssFeed(feed)]));
     await Promise.all([
-      write(join11(srcDir, "generated", "rss.json"), `${JSON.stringify(feedXml)}
+      write(join17(srcDir, "generated", "rss.json"), `${JSON.stringify(feedXml)}
 `),
-      write(join11(srcDir, "pages", "[section]", "rss.xml.ts"), rssEndpointTemplate())
+      write(join17(srcDir, "pages", "[section]", "rss.xml.ts"), rssEndpointTemplate())
     ]);
   }
   const warnings = [
@@ -6811,17 +7288,20 @@ var generateRuntime = async (project) => {
     }
   }
   warnings.push(...islandFrameworkWarnings(frameworks, context.root));
-  if (hasReferences(config)) {
+  if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
       contentRoutes: new Set(project.graph.pages.map((page) => page.route)),
       root: context.root
     });
     warnings.push(...references.warnings);
-    await Promise.all(references.files.map((file) => write(join11(srcDir, "pages", file.pagePath), file.content)));
+    await Promise.all(references.files.map((file) => write(join17(srcDir, "pages", file.pagePath), file.content)));
   }
-  await write(join11(srcDir, "generated", "data.json"), buildRuntimeData(project));
-  await write(join11(out, "blume.manifest.json"), `${JSON.stringify(project.manifest, null, 2)}
+  await write(join17(srcDir, "generated", "data.json"), buildRuntimeData(project));
+  const openApiSource2 = project.sources.find(isOpenApiSource);
+  await write(openapiPath, `${JSON.stringify(openApiSource2 ? openApiSource2.openApiData() : {})}
+`);
+  await write(join17(out, "blume.manifest.json"), `${JSON.stringify(project.manifest, null, 2)}
 `);
   await writeStagedContent(out, staged);
   await pruneOrphans(srcDir, written);
@@ -6829,16 +7309,48 @@ var generateRuntime = async (project) => {
 };
 
 // src/core/config.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6 } from "node:fs";
+import { existsSync as existsSync11, readFileSync as readFileSync7 } from "node:fs";
 
 // src/core/bridge.ts
-import { existsSync as existsSync7 } from "node:fs";
-import { readFile as readFile9 } from "node:fs/promises";
-import { join as join12 } from "pathe";
+import { existsSync as existsSync10 } from "node:fs";
+import { readFile as readFile12 } from "node:fs/promises";
+import { join as join18 } from "pathe";
+
+// src/migrate/mintlify/assets.ts
+var assetRefs = (config) => {
+  const refs = ["/images"];
+  const logo = config.logo;
+  if (typeof logo === "string") {
+    refs.push(logo);
+  } else if (logo) {
+    refs.push(logo.light, logo.dark);
+  }
+  const favicon = config.favicon;
+  if (typeof favicon === "string") {
+    refs.push(favicon);
+  } else if (favicon) {
+    refs.push(favicon.light, favicon.dark);
+  }
+  refs.push(config.theme?.backgroundImage, config.theme?.backgroundImageDark);
+  return refs;
+};
+var assetSegments = (config) => {
+  const segments = new Set;
+  for (const ref of assetRefs(config)) {
+    if (typeof ref !== "string" || !ref.startsWith("/")) {
+      continue;
+    }
+    const [segment] = ref.replace(/^\/+/u, "").split("/");
+    if (segment) {
+      segments.add(segment);
+    }
+  }
+  return [...segments];
+};
 
 // src/migrate/mintlify/config.ts
-import { readFile as readFile8 } from "node:fs/promises";
-import { dirname as dirname8, relative as relative7, resolve as resolve4 } from "pathe";
+import { readFile as readFile11 } from "node:fs/promises";
+import { dirname as dirname8, relative as relative7, resolve as resolve5 } from "pathe";
 var MINTLIFY_DEFAULT_IGNORES = [
   "**/_*",
   "**/.*",
@@ -6879,7 +7391,7 @@ var isInsideRoot = (root, candidate) => {
 };
 var readJsonFile = async (file) => {
   try {
-    return JSON.parse(await readFile8(file, "utf-8"));
+    return JSON.parse(await readFile11(file, "utf-8"));
   } catch (error) {
     throw new BlumeError({
       code: "BLUME_MINTLIFY_CONFIG_INVALID",
@@ -6899,7 +7411,7 @@ var resolveRefs = async (value, options) => {
   }
   const ref = asString(object.$ref);
   if (ref) {
-    const refFile = resolve4(dirname8(options.file), ref);
+    const refFile = resolve5(dirname8(options.file), ref);
     if (!isInsideRoot(options.root, refFile)) {
       throw new BlumeError({
         code: "BLUME_MINTLIFY_REF_OUTSIDE_ROOT",
@@ -7255,13 +7767,15 @@ var mintlifySelectors = (spec) => {
 };
 var mintignorePatterns = async (root) => {
   try {
-    const raw = await readFile8(resolve4(root, ".mintignore"), "utf-8");
+    const raw = await readFile11(resolve5(root, ".mintignore"), "utf-8");
     return raw.split(`
 `).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#")).filter((line) => !line.startsWith("!")).map((line) => line.endsWith("/") ? `${line}**` : line);
   } catch {
     return [];
   }
 };
+var REDIRECT_PARAM = /:(?<name>[A-Za-z_]\w*)(?<modifier>[*+?])?/gu;
+var toAstroRedirectPath = (path) => path.replaceAll(REDIRECT_PARAM, (_match, name, modifier) => modifier === "*" || modifier === "+" ? `[...${name}]` : `[${name}]`);
 var mintlifyRedirects = (spec) => asArray(spec.redirects).flatMap((redirect) => {
   const object = asObject(redirect);
   if (!object) {
@@ -7272,8 +7786,72 @@ var mintlifyRedirects = (spec) => asArray(spec.redirects).flatMap((redirect) =>
   if (!from || !to) {
     return [];
   }
-  return [{ from, to }];
+  return [{ from: toAstroRedirectPath(from), to: toAstroRedirectPath(to) }];
 });
+var openapiRouteFromDirectory = (value) => {
+  const directory = normalizeDirectory(asString(value) ?? "");
+  return directory.length > 0 ? `/${directory}` : undefined;
+};
+var openapiSourcesFromValue = (value, context) => {
+  if (typeof value === "string") {
+    if (value.length === 0 || API_ENDPOINT_REF.test(value)) {
+      return [];
+    }
+    return [
+      withoutUndefined({
+        label: context.label,
+        route: context.route,
+        spec: value
+      })
+    ];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => openapiSourcesFromValue(item, context));
+  }
+  const object = asObject(value);
+  if (!object) {
+    return [];
+  }
+  return openapiSourcesFromValue(object.source ?? object.openapi, {
+    label: context.label,
+    route: openapiRouteFromDirectory(object.directory) ?? context.route
+  });
+};
+var mintlifyOpenapi = (spec) => {
+  const drafts = [];
+  const visit = (node) => {
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        visit(item);
+      }
+      return;
+    }
+    const object = asObject(node);
+    if (!object) {
+      return;
+    }
+    if (hasOwn(object, "openapi")) {
+      drafts.push(...openapiSourcesFromValue(object.openapi, {
+        label: labelForNavItem(object)
+      }));
+    }
+    for (const children of childNavigationArrays(object)) {
+      visit(children);
+    }
+  };
+  visit(spec.navigation);
+  drafts.push(...openapiSourcesFromValue(spec.openapi, {}));
+  drafts.push(...openapiSourcesFromValue(asObject(spec.api)?.openapi, {}));
+  const seen = new Set;
+  const sources = drafts.flatMap((draft) => {
+    if (seen.has(draft.spec)) {
+      return [];
+    }
+    seen.add(draft.spec);
+    return [draft];
+  });
+  return sources.length > 0 ? { enabled: true, sources } : undefined;
+};
 var mintlifyLogo = (value) => {
   if (typeof value === "string") {
     return value;
@@ -7305,6 +7883,12 @@ var mintlifyFavicon = (value) => {
   }
   return withoutUndefined({ dark, light });
 };
+var mintlifyIcons = (value) => {
+  const library = asString(asObject(value)?.library);
+  return {
+    library: library === "lucide" || library === "tabler" ? library : "fontawesome"
+  };
+};
 var mintlifyBanner = (value) => {
   const object = asObject(value);
   const content = object ? asString(object.content) : undefined;
@@ -7395,6 +7979,27 @@ var mintlifyMarkdown = (value, styling) => {
     schema: object?.schema === false ? false : undefined
   });
 };
+var FAMILY_TO_SLUG = Object.fromEntries(Object.entries(GOOGLE_FONTS).map(([slug, def]) => [
+  def.family.toLowerCase(),
+  slug
+]));
+var fontSlugForFamily = (value) => {
+  const family = asString(value);
+  return family ? FAMILY_TO_SLUG[family.toLowerCase()] : undefined;
+};
+var mintlifyFonts = (value) => {
+  const object = asObject(value);
+  if (!object) {
+    return;
+  }
+  const heading = asObject(object.heading);
+  const body = asObject(object.body);
+  const fonts = withoutUndefined({
+    body: fontSlugForFamily(body?.family) ?? fontSlugForFamily(object.family),
+    display: fontSlugForFamily(heading?.family) ?? fontSlugForFamily(object.family)
+  });
+  return Object.keys(fonts).length > 0 ? fonts : undefined;
+};
 var mintlifySeo = (value) => {
   const object = asObject(value);
   const metatags = asObject(object?.metatags);
@@ -7406,8 +8011,8 @@ var mintlifySeo = (value) => {
   };
 };
 var loadMintlifyConfig = async (root, file) => {
-  const projectRoot = resolve4(root);
-  const configFile = resolve4(file);
+  const projectRoot = resolve5(root);
+  const configFile = resolve5(file);
   const spec = asObject(await resolveRefs(await readJsonFile(configFile), {
     file: configFile,
     root: projectRoot,
@@ -7440,6 +8045,7 @@ var loadMintlifyConfig = async (root, file) => {
     },
     description: asString(spec.description),
     favicon: mintlifyFavicon(spec.favicon),
+    icons: mintlifyIcons(spec.icons),
     logo: mintlifyLogo(spec.logo),
     markdown: mintlifyMarkdown(spec.markdown, styling),
     navigation: {
@@ -7449,6 +8055,7 @@ var loadMintlifyConfig = async (root, file) => {
       sidebarVariants: await mintlifySidebarVariants(spec),
       tabs: mintlifyTabs(spec)
     },
+    openapi: mintlifyOpenapi(spec),
     redirects: mintlifyRedirects(spec),
     search: {
       indexing: {
@@ -7466,6 +8073,7 @@ var loadMintlifyConfig = async (root, file) => {
       backgroundDecoration: mintlifyBackgroundDecoration(spec.background),
       backgroundImage: backgroundImage.light,
       backgroundImageDark: backgroundImage.dark,
+      fonts: mintlifyFonts(spec.fonts ?? spec.font),
       mode: appearance.default === "light" || appearance.default === "dark" || appearance.default === "system" ? appearance.default : "system",
       strict: appearance.strict === true
     },
@@ -7503,12 +8111,12 @@ var mintlifyI18n = (spec) => {
 // src/core/bridge.ts
 var MINTLIFY_CONFIG_FILES = ["docs.json", "mint.json"];
 var detectMintlifyBridge = async (root) => {
-  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join12(root, name)).find((candidate) => existsSync7(candidate));
+  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join18(root, name)).find((candidate) => existsSync10(candidate));
   if (!configFile) {
     return null;
   }
   const config = await loadMintlifyConfig(root, configFile);
-  const spec = JSON.parse(await readFile9(configFile, "utf-8"));
+  const spec = JSON.parse(await readFile12(configFile, "utf-8"));
   const i18n = mintlifyI18n(spec);
   if (i18n) {
     config.i18n = i18n;
@@ -7519,11 +8127,13 @@ var detectMintlifyBridge = async (root) => {
   const variables = config.variables ?? {};
   const root_ = config.content?.root ?? ".";
   const exclude = config.content?.exclude ?? [];
+  const assets = assetSegments(config).filter((segment) => segment !== "public" && existsSync10(join18(root, segment)));
   return {
     configFile,
     raw: {
       ...config,
       content: {
+        assets,
         exclude,
         root: root_,
         sources: [
@@ -7591,42 +8201,6 @@ var createModuleLoader = () => {
   };
 };
 
-// src/core/project.ts
-import { existsSync as existsSync8 } from "node:fs";
-import { isAbsolute as isAbsolute4, join as join13, resolve as resolve5 } from "pathe";
-var CONFIG_FILENAMES = [
-  "blume.config.ts",
-  "blume.config.mjs",
-  "blume.config.js"
-];
-var THEME_FILENAMES = ["theme.css"];
-var COMPONENTS_FILENAMES = ["components.tsx", "components.ts"];
-var firstExisting = (root, names) => {
-  for (const name of names) {
-    const candidate = join13(root, name);
-    if (existsSync8(candidate)) {
-      return candidate;
-    }
-  }
-  return null;
-};
-var findConfigFile = (root) => firstExisting(root, CONFIG_FILENAMES);
-var resolveProjectContext = (root, config) => {
-  const absoluteRoot = resolve5(root);
-  const contentRoot = isAbsolute4(config.content.root) ? config.content.root : join13(absoluteRoot, config.content.root);
-  const pagesPath = join13(absoluteRoot, config.content.pages);
-  const pagesRoot = existsSync8(pagesPath) ? pagesPath : null;
-  return {
-    componentsFile: firstExisting(absoluteRoot, COMPONENTS_FILENAMES),
-    configFile: findConfigFile(absoluteRoot),
-    contentRoot,
-    outDir: join13(absoluteRoot, ".blume"),
-    pagesRoot,
-    root: absoluteRoot,
-    themeFile: firstExisting(absoluteRoot, THEME_FILENAMES)
-  };
-};
-
 // src/core/schema.ts
 import { z as z2 } from "zod";
 var iconName = z2.string().min(1);
@@ -7656,7 +8230,17 @@ var changelogMetaSchema = z2.object({
   date: dateSchema.optional(),
   version: z2.string().optional()
 }).strict();
+var authorSchema = z2.union([
+  z2.string(),
+  z2.object({
+    avatar: z2.string().optional(),
+    image: z2.string().optional(),
+    name: z2.string(),
+    url: z2.string().optional()
+  }).passthrough()
+]);
 var pageMetaBaseSchema = z2.object({
+  authors: z2.union([authorSchema, z2.array(authorSchema)]).optional(),
   changelog: changelogMetaSchema.optional(),
   date: dateSchema.optional(),
   deprecated: z2.boolean().default(false),
@@ -7810,6 +8394,7 @@ var contentSourceSchema = z2.discriminatedUnion("type", [
   customSourceSchema
 ]);
 var contentConfigSchema = z2.object({
+  assets: z2.array(z2.string()).default([]),
   defaultType: z2.string().default("doc"),
   exclude: z2.array(z2.string()).default(["**/_*", "**/.*"]),
   include: z2.array(z2.string()).default(["**/*.{md,mdx}"]),
@@ -8096,7 +8681,10 @@ var openapiSourceSchema = z2.object({
   spec: z2.string()
 }).strict();
 var openapiConfigSchema = z2.object({
+  codeSamples: z2.array(z2.string()).default(["curl", "js", "python"]),
   enabled: z2.boolean().default(false),
+  expandSchemas: z2.boolean().default(false),
+  renderer: z2.enum(["blume", "scalar"]).default("blume"),
   route: z2.string().default("/reference"),
   sources: z2.array(openapiSourceSchema).default([]),
   spec: z2.string().optional(),
@@ -8125,6 +8713,9 @@ var tocConfigSchema = z2.union([
     minLevel: value.minHeadingLevel ?? 2
   };
 });
+var iconsConfigSchema = z2.object({
+  library: z2.enum(["lucide", "fontawesome", "tabler"]).default("lucide")
+}).strict();
 var blumeConfigSchema = z2.object({
   ai: aiConfigSchema.default({}),
   analytics: analyticsConfigSchema.optional(),
@@ -8139,6 +8730,7 @@ var blumeConfigSchema = z2.object({
   feedback: z2.boolean().default(true),
   github: githubConfigSchema.optional(),
   i18n: i18nConfigSchema.optional(),
+  icons: iconsConfigSchema.default({}),
   lastModified: lastModifiedConfigSchema.default(false),
   logo: logoConfigSchema.optional(),
   markdown: markdownConfigSchema.default({}),
@@ -8180,7 +8772,7 @@ var loadConfig = async (root, options = {}) => {
   const sourceFile = bridge?.configFile ?? configFile;
   const parsed = blumeConfigSchema.safeParse(raw ?? {});
   if (!parsed.success) {
-    const source = sourceFile && existsSync9(sourceFile) ? readFileSync6(sourceFile, "utf-8") : undefined;
+    const source = sourceFile && existsSync11(sourceFile) ? readFileSync7(sourceFile, "utf-8") : undefined;
     const diagnostics = diagnosticsFromZod(parsed.error, {
       code: "BLUME_CONFIG_INVALID",
       file: sourceFile ?? undefined,
@@ -8657,7 +9249,7 @@ var discoverFolderMeta = async (contentRoot) => {
 };
 
 // src/core/sources/normalize.ts
-import { existsSync as existsSync10, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync12, readFileSync as readFileSync8 } from "node:fs";
 import GithubSlugger from "github-slugger";
 import { extname as extname4 } from "pathe";
 var NUMERIC_PREFIX2 = /^\d+[-_.]/u;
@@ -8665,7 +9257,7 @@ var GROUP_FOLDER2 = /^\((?<label>.+)\)$/u;
 var WORD_SPLIT2 = /[-_]/u;
 var stripNumericPrefix = (segment) => segment.replace(NUMERIC_PREFIX2, "");
 var groupLabel = (segment) => segment.match(GROUP_FOLDER2)?.groups?.label ?? null;
-var slugify2 = (text) => text.toLowerCase().trim().replaceAll(/[^\w\s-]/gu, "").replaceAll(/[\s_]+/gu, "-").replaceAll(/-+/gu, "-").replaceAll(/^-|-$/gu, "");
+var slugify3 = (text) => text.toLowerCase().trim().replaceAll(/[^\w\s-]/gu, "").replaceAll(/[\s_]+/gu, "-").replaceAll(/-+/gu, "-").replaceAll(/^-|-$/gu, "");
 var titleCase = (value) => value.split(WORD_SPLIT2).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 var mapRoute = (relativePath) => {
   const withoutExt = relativePath.slice(0, relativePath.length - extname4(relativePath).length);
@@ -8731,8 +9323,9 @@ var extractLinks = (body) => {
       if (target === undefined || match.index === undefined) {
         continue;
       }
+      const targetOffset = match.index + match[0].indexOf("](") + "](".length;
       links.push({
-        column: line.indexOf(target, match.index) + 1,
+        column: targetOffset + 1,
         line: lineNumber,
         target
       });
@@ -8782,7 +9375,7 @@ var normalizeEntry2 = (entry, ctx) => {
   const ext = format === "mdx" ? ".mdx" : ".md";
   const result = pageMetaSchema.safeParse(entry.data);
   if (!result.success) {
-    const source = entry.raw ?? (entry.sourcePath && existsSync10(entry.sourcePath) ? readFileSync7(entry.sourcePath, "utf-8") : undefined);
+    const source = entry.raw ?? (entry.sourcePath && existsSync12(entry.sourcePath) ? readFileSync8(entry.sourcePath, "utf-8") : undefined);
     return {
       diagnostics: diagnosticsFromZod(result.error, {
         code: "BLUME_FRONTMATTER_INVALID",
@@ -8831,15 +9424,15 @@ var normalizeEntry2 = (entry, ctx) => {
 };
 
 // src/core/sources/resolve.ts
-import { join as join22 } from "pathe";
+import { join as join26 } from "pathe";
 
 // src/core/sources/filesystem.ts
-import { existsSync as existsSync11, watch as fsWatch } from "node:fs";
-import { readFile as readFile10 } from "node:fs/promises";
-import { extname as extname5, isAbsolute as isAbsolute5, join as join14, relative as relative10, resolve as resolve6 } from "pathe";
+import { existsSync as existsSync13, watch as fsWatch } from "node:fs";
+import { readFile as readFile13 } from "node:fs/promises";
+import { extname as extname5, isAbsolute as isAbsolute6, join as join19, relative as relative10, resolve as resolve6 } from "pathe";
 import { glob as glob6 } from "tinyglobby";
 var filesystemSource = (options) => {
-  const contentRoot = isAbsolute5(options.root) ? options.root : join14(resolve6(options.projectRoot), options.root);
+  const contentRoot = isAbsolute6(options.root) ? options.root : join19(resolve6(options.projectRoot), options.root);
   const load2 = async () => {
     const files = await glob6(options.include, {
       absolute: true,
@@ -8849,123 +9442,47 @@ var filesystemSource = (options) => {
     });
     files.sort();
     const entries = await Promise.all(files.map(async (file) => {
-      const source = await readFile10(file, "utf-8");
+      const source = await readFile13(file, "utf-8");
       const ext = extname5(file).toLowerCase();
       const format = ext === ".mdx" ? "mdx" : "md";
-      const parsed = frontmatter_default(source);
-      return {
-        body: { format, text: parsed.content },
-        data: parsed.data,
-        ref: relative10(contentRoot, file),
-        sourcePath: file
-      };
-    }));
-    return { diagnostics: [], entries };
-  };
-  const validate = () => {
-    if (!existsSync11(contentRoot)) {
-      throw new BlumeError({
-        code: options.missingCode ?? "BLUME_CONTENT_ROOT_MISSING",
-        file: contentRoot,
-        message: `Content root not found: ${options.root}`,
-        severity: "error",
-        suggestion: `Create a "${options.root}" folder with at least one .md or .mdx file, or set content.root in blume.config.ts.`
-      });
-    }
-  };
-  const watch = (onChange) => {
-    if (!existsSync11(contentRoot)) {
-      return () => {};
-    }
-    const watcher = fsWatch(contentRoot, { recursive: true }, onChange);
-    return () => watcher.close();
-  };
-  return {
-    contentRoot,
-    load: load2,
-    name: options.name,
-    prefix: options.prefix,
-    read: (ref) => readFile10(join14(contentRoot, ref), "utf-8"),
-    staged: false,
-    validate,
-    watch
-  };
-};
-
-// src/core/sources/cache.ts
-import { mkdir as mkdir3, readFile as readFile11, writeFile as writeFile3 } from "node:fs/promises";
-import { join as join15 } from "pathe";
-var hashText = (text) => {
-  let hash = 5381;
-  for (let i = 0;i < text.length; i += 1) {
-    hash = (hash * 33 + (text.codePointAt(i) ?? 0)) % 2147483647;
-  }
-  return hash.toString(36);
-};
-var entriesDigest = (entries) => hashText(entries.map((entry) => `${entry.ref}:${entry.hash ?? hashText(entry.body.text)}`).join("|"));
-var pollingWatch = (load2, intervalSeconds) => (onChange) => {
-  let last = "";
-  const tick = async () => {
-    try {
-      const { entries } = await load2();
-      const next = entriesDigest(entries);
-      if (last && next !== last) {
-        onChange();
-      }
-      last = next;
-    } catch {}
-  };
-  const timer = setInterval(() => {
-    tick();
-  }, intervalSeconds * 1000);
-  return () => clearInterval(timer);
-};
-var snapshotCache = (cacheDir) => {
-  const file = join15(cacheDir, "entries.json");
-  return {
-    read: async () => {
-      try {
-        return JSON.parse(await readFile11(file, "utf-8"));
-      } catch {
-        return [];
-      }
-    },
-    write: async (entries) => {
-      try {
-        await mkdir3(cacheDir, { recursive: true });
-        await writeFile3(file, `${JSON.stringify(entries)}
-`, "utf-8");
-      } catch {}
-    }
+      const parsed = frontmatter_default(source);
+      return {
+        body: { format, text: parsed.content },
+        data: parsed.data,
+        ref: relative10(contentRoot, file),
+        sourcePath: file
+      };
+    }));
+    return { diagnostics: [], entries };
   };
-};
-var loadWithCache = async (name, cache, fetchEntries, refresh = true) => {
-  if (!refresh) {
-    const cached3 = await cache.read();
-    if (cached3.length > 0) {
-      return { diagnostics: [], entries: cached3 };
+  const validate = () => {
+    if (!existsSync13(contentRoot)) {
+      throw new BlumeError({
+        code: options.missingCode ?? "BLUME_CONTENT_ROOT_MISSING",
+        file: contentRoot,
+        message: `Content root not found: ${options.root}`,
+        severity: "error",
+        suggestion: `Create a "${options.root}" folder with at least one .md or .mdx file, or set content.root in blume.config.ts.`
+      });
     }
-  }
-  try {
-    const entries = await fetchEntries();
-    await cache.write(entries);
-    return { diagnostics: [], entries };
-  } catch (error) {
-    const fallback = await cache.read();
-    if (fallback.length > 0) {
-      const diagnostic = {
-        code: "BLUME_SOURCE_OFFLINE",
-        message: `Source "${name}" could not be fetched (${error.message}); served ${fallback.length} cached entries.`,
-        severity: "warning"
-      };
-      return { diagnostics: [diagnostic], entries: fallback };
+  };
+  const watch = (onChange) => {
+    if (!existsSync13(contentRoot)) {
+      return () => {};
     }
-    throw new BlumeError({
-      code: "BLUME_SOURCE_FETCH_FAILED",
-      message: `Source "${name}" failed to load and no cache is available: ${error.message}`,
-      severity: "error"
-    });
-  }
+    const watcher = fsWatch(contentRoot, { recursive: true }, onChange);
+    return () => watcher.close();
+  };
+  return {
+    contentRoot,
+    load: load2,
+    name: options.name,
+    prefix: options.prefix,
+    read: (ref) => readFile13(join19(contentRoot, ref), "utf-8"),
+    staged: false,
+    validate,
+    watch
+  };
 };
 
 // src/core/sources/github-releases.ts
@@ -8973,9 +9490,9 @@ var DEFAULT_BASE_URL = "https://api.github.com";
 var DEFAULT_LIMIT = 100;
 var PER_PAGE = 100;
 var LEADING_V = /^v/iu;
-var NON_SLUG2 = /[^a-z0-9]+/gu;
+var NON_SLUG3 = /[^a-z0-9]+/gu;
 var EDGE_DASHES = /^-+|-+$/gu;
-var slugifyTag = (tag) => tag.toLowerCase().replaceAll(NON_SLUG2, "-").replaceAll(EDGE_DASHES, "");
+var slugifyTag = (tag) => tag.toLowerCase().replaceAll(NON_SLUG3, "-").replaceAll(EDGE_DASHES, "");
 var githubHeaders = () => {
   const headers = new Headers({ Accept: "application/vnd.github+json" });
   const token = process.env.GITHUB_TOKEN;
@@ -9135,11 +9652,12 @@ var enumerateGithub = async (github, include, doFetch) => {
   }
   const body = await res.json();
   const prefix = base ? `${base}/` : "";
-  return (body.tree ?? []).filter((node) => node.type === "blob" && node.path.startsWith(prefix)).map((node) => node.path.slice(prefix.length)).filter((rel) => matchesInclude(rel, include)).map((rel) => ({
+  const refs = (body.tree ?? []).filter((node) => node.type === "blob" && node.path.startsWith(prefix)).map((node) => node.path.slice(prefix.length)).filter((rel) => matchesInclude(rel, include)).map((rel) => ({
     editUrl: `https://github.com/${owner}/${repo}/edit/${ref}/${prefix}${rel}`,
     fetchUrl: `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${prefix}${rel}`,
     ref: rel
   }));
+  return { refs, truncated: body.truncated === true };
 };
 var mdxRemoteSource = (options, ctx) => {
   const doFetch = options.fetchImpl ?? globalThis.fetch;
@@ -9151,11 +9669,12 @@ var mdxRemoteSource = (options, ctx) => {
     }
     if (options.files && options.url) {
       const base = options.url.replace(/\/$/u, "");
-      return options.files.filter((ref) => matchesInclude(ref, options.include)).map((ref) => ({
+      const refs = options.files.filter((ref) => matchesInclude(ref, options.include)).map((ref) => ({
         editUrl: `${base}/${ref}`,
         fetchUrl: `${base}/${ref}`,
         ref
       }));
+      return { refs, truncated: false };
     }
     throw new BlumeError({
       code: "BLUME_SOURCE_MISCONFIGURED",
@@ -9181,12 +9700,40 @@ var mdxRemoteSource = (options, ctx) => {
     };
   };
   const load2 = async () => {
+    const skipped = [];
     const result = await loadWithCache(options.name, cache, async () => {
-      const refs = await enumerate();
-      return await Promise.all(refs.map(fetchEntry));
+      const { refs, truncated } = await enumerate();
+      if (truncated) {
+        skipped.push({
+          code: "BLUME_SOURCE_TRUNCATED",
+          message: `Source "${options.name}" hit GitHub's tree listing limit; some files were not enumerated. Narrow the source path or split the repo.`,
+          severity: "warning"
+        });
+      }
+      const settled = await Promise.all(refs.map(async (ref) => {
+        try {
+          return await fetchEntry(ref);
+        } catch (error) {
+          skipped.push({
+            code: "BLUME_SOURCE_FETCH_FAILED",
+            message: `Source "${options.name}" skipped "${ref.ref}" (${error.message}); the rest were imported.`,
+            severity: "warning"
+          });
+          return null;
+        }
+      }));
+      const entries = settled.filter((entry) => entry !== null);
+      if (refs.length > 0 && entries.length === 0) {
+        skipped.length = 0;
+        throw new Error(`all ${refs.length} remote file(s) failed to fetch`);
+      }
+      return entries;
     }, ctx.refresh ?? true);
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
-    return result;
+    return {
+      ...result,
+      diagnostics: [...result.diagnostics, ...skipped]
+    };
   };
   const read = async (ref) => {
     const cached3 = snapshot.get(ref);
@@ -9208,21 +9755,25 @@ var mdxRemoteSource = (options, ctx) => {
 };
 
 // src/core/sources/mintlify.ts
-import { existsSync as existsSync13, watch as fsWatch2 } from "node:fs";
-import { readFile as readFile13 } from "node:fs/promises";
-import { isAbsolute as isAbsolute6, join as join18, relative as relative13, resolve as resolve8 } from "pathe";
+import { existsSync as existsSync15, watch as fsWatch2 } from "node:fs";
+import { readFile as readFile15 } from "node:fs/promises";
+import { isAbsolute as isAbsolute8, join as join22, relative as relative14, resolve as resolve8 } from "pathe";
 import { glob as glob7 } from "tinyglobby";
 
 // src/migrate/shared.ts
-import { existsSync as existsSync12 } from "node:fs";
-import { readFile as readFile12, writeFile as writeFile4 } from "node:fs/promises";
-import { join as join16 } from "pathe";
+import { existsSync as existsSync14 } from "node:fs";
+import { readFile as readFile14, writeFile as writeFile5 } from "node:fs/promises";
+import { isAbsolute as isAbsolute7, join as join20, relative as relative11 } from "pathe";
+var isInsideRoot2 = (root, candidate) => {
+  const rel = relative11(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute7(rel);
+};
 var writeBlumeConfig = async (root, config) => {
   const body = `import { defineConfig } from "blume";
 
 export default defineConfig(${JSON.stringify(config, null, 2)});
 `;
-  await writeFile4(join16(root, "blume.config.ts"), body, "utf-8");
+  await writeFile5(join20(root, "blume.config.ts"), body, "utf-8");
 };
 var BLUME_SCRIPTS = {
   build: "blume build",
@@ -9230,13 +9781,13 @@ var BLUME_SCRIPTS = {
   start: "blume preview"
 };
 var rewriteFrameworkScripts = async (root, cli, remove) => {
-  const pkgPath = join16(root, "package.json");
-  if (!existsSync12(pkgPath)) {
+  const pkgPath = join20(root, "package.json");
+  if (!existsSync14(pkgPath)) {
     return false;
   }
   let pkg;
   try {
-    pkg = JSON.parse(await readFile12(pkgPath, "utf-8"));
+    pkg = JSON.parse(await readFile14(pkgPath, "utf-8"));
   } catch {
     return false;
   }
@@ -9259,30 +9810,12 @@ var rewriteFrameworkScripts = async (root, cli, remove) => {
   }
   if (changed) {
     pkg.scripts = next;
-    await writeFile4(pkgPath, `${JSON.stringify(pkg, null, 2)}
+    await writeFile5(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `, "utf-8");
   }
   return changed;
 };
-var gitignoreKey = (line) => line.trim().replace(/\/+$/u, "");
-var ensureGitignore = async (root, entries) => {
-  const path = join16(root, ".gitignore");
-  const existing = existsSync12(path) ? await readFile12(path, "utf-8") : "";
-  const present = new Set(existing.split(`
-`).map(gitignoreKey).filter(Boolean));
-  const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
-  if (added.length === 0) {
-    return [];
-  }
-  const gap = existing.length > 0 && !existing.endsWith(`
-`) ? `
-` : "";
-  await writeFile4(path, `${existing}${gap}${added.join(`
-`)}
-`, "utf-8");
-  return added;
-};
-var leftoverFiles = (root, candidates) => candidates.filter((candidate) => existsSync12(join16(root, candidate)));
+var leftoverFiles = (root, candidates) => candidates.filter((candidate) => existsSync14(join20(root, candidate)));
 var attribute = (attrs, name) => {
   const match = attrs.match(new RegExp(`\\b${name}=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')`, "u"));
   return match?.groups?.dq ?? match?.groups?.sq;
@@ -9679,7 +10212,7 @@ var isLiteralObject = (value) => typeof value === "object" && value !== null &&
 var asLiteralArray = (value) => Array.isArray(value) ? value : undefined;
 
 // src/migrate/mintlify/content.ts
-import { dirname as dirname10, join as join17, relative as relative11 } from "pathe";
+import { dirname as dirname10, join as join21, relative as relative12 } from "pathe";
 var CALLOUT_DIRECTIVES = {
   Check: "success",
   Danger: "danger",
@@ -9715,9 +10248,9 @@ var rewriteSnippetImports = (source, options) => {
     if (/\.mdx?$/u.test(importSource)) {
       return "";
     }
-    const target = join17(options.root, importSource.replace(/^\/+/u, ""));
+    const target = join21(options.root, importSource.replace(/^\/+/u, ""));
     components.push(importSource.replace(/^\/+/u, ""));
-    let rel = relative11(dirname10(options.filePath), target);
+    let rel = relative12(dirname10(options.filePath), target);
     if (!rel.startsWith(".")) {
       rel = `./${rel}`;
     }
@@ -9725,7 +10258,7 @@ var rewriteSnippetImports = (source, options) => {
   });
   return { components, source: next };
 };
-var UNSUPPORTED_COMPONENTS = ["ParamField", "ResponseField"];
+var UNSUPPORTED_COMPONENTS = ["Update"];
 var unsupportedMintlifyComponents = (source) => UNSUPPORTED_COMPONENTS.filter((name) => new RegExp(`<${name}\\b`, "u").test(source));
 
 // src/migrate/mintlify/frontmatter.ts
@@ -9907,7 +10440,7 @@ var rewriteMintlifySvgIconProps = (source) => {
 
 // src/migrate/mintlify/snippets.ts
 import { readFile as readFileFromDisk } from "node:fs/promises";
-import { dirname as dirname11, relative as relative12, resolve as resolve7 } from "pathe";
+import { dirname as dirname11, relative as relative13, resolve as resolve7 } from "pathe";
 var MARKDOWN_SNIPPET_IMPORT = /^import\s+(?<name>[$A-Z_a-z][$\w]*)\s+from\s+["'](?<source>[^"']+\.mdx?)["'];?\s*$/gmu;
 var NAMED_SNIPPET_IMPORT = /^import\s+\{(?<names>[^}]+)\}\s+from\s+["'](?<source>[^"']+\.mdx?)["'];?\s*$/gmu;
 var EXPORTED_STRING_CONST = /^export\s+const\s+(?<name>[$A-Z_a-z][$\w]*)\s*=\s*(?:"(?<double>(?:\\.|[^"\\])*)"|'(?<single>(?:\\.|[^'\\])*)'|`(?<template>(?:\\.|[^`\\])*)`)\s*;?\s*$/gmu;
@@ -9916,15 +10449,15 @@ var PLACEHOLDER = /\{(?<name>[$A-Z_a-z][$\w]*)\}/gu;
 var GLOBAL_VARIABLE = /\{\{\s*(?<name>[A-Za-z0-9-]+)\s*\}\}/gu;
 var FRONTMATTER_BLOCK = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/u;
 var USER_EXPORT = /^(?:export\s+)?(?:const|let|var)\s+user\s*=|^import\s+\{\s*user\s*\}/mu;
-var isInsideRoot2 = (root, candidate) => {
-  const rel = relative12(root, candidate);
+var isInsideRoot3 = (root, candidate) => {
+  const rel = relative13(root, candidate);
   return rel === "" || !rel.startsWith("..") && !rel.startsWith("/");
 };
 var escapeRegExp2 = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 var snippetSelfClosingTagPattern = (name) => new RegExp(`<${escapeRegExp2(name)}(?<attrs>[^>]*?)\\s*/>`, "gu");
 var snippetPairedTagPattern = (name) => new RegExp(`<${escapeRegExp2(name)}(?<attrs>[^>]*?)>[\\s\\S]*?</${escapeRegExp2(name)}>`, "gu");
 var rootRelativePath = (root, file) => {
-  const rel = relative12(root, file);
+  const rel = relative13(root, file);
   return rel ? `/${rel}` : "/";
 };
 var snippetCycleMessage = (root, file, trail) => {
@@ -9934,7 +10467,7 @@ var snippetCycleMessage = (root, file, trail) => {
 };
 var resolveSnippetPath = (options) => {
   const target = options.source.startsWith("/") ? resolve7(options.root, options.source.slice(1)) : resolve7(dirname11(options.filePath), options.source);
-  return isInsideRoot2(options.root, target) ? target : null;
+  return isInsideRoot3(options.root, target) ? target : null;
 };
 var collectImports2 = (source) => [...source.matchAll(MARKDOWN_SNIPPET_IMPORT)].flatMap((match) => {
   const name = match.groups?.name;
@@ -9996,9 +10529,9 @@ var rewriteMintlifyMarkdownSnippets = async (source, options) => {
       throw new Error(snippetCycleMessage(options.root, file, options.trail ?? []));
     }
     seen.add(file);
-    const readFile13 = options.readFile ?? readFileFromDisk;
+    const readFile15 = options.readFile ?? readFileFromDisk;
     try {
-      const raw = await readFile13(file);
+      const raw = await readFile15(file);
       const content = frontmatter_default(raw).content.trim();
       const transformed = await rewriteMintlifyMarkdownSnippets(content, {
         ...options,
@@ -10039,7 +10572,7 @@ var rewriteMintlifyMarkdownSnippets = async (source, options) => {
   return await inlineAt(0, source);
 };
 var rewriteMintlifySnippetVariables = async (source, options) => {
-  const readFile13 = options.readFile ?? readFileFromDisk;
+  const readFile15 = options.readFile ?? readFileFromDisk;
   const inlineImport = async (current, variableImport) => {
     const file = resolveSnippetPath({
       filePath: options.filePath,
@@ -10049,7 +10582,7 @@ var rewriteMintlifySnippetVariables = async (source, options) => {
     if (!file) {
       return current;
     }
-    const exports = collectStringExports(frontmatter_default(await readFile13(file)).content);
+    const exports = collectStringExports(frontmatter_default(await readFile15(file)).content);
     let next = current;
     for (const name of variableImport.names) {
       const value = exports.get(name.imported);
@@ -10127,7 +10660,7 @@ var MINTLIFY_SOURCE_IGNORES = [
   "snippets/**"
 ];
 var mintlifySource = (options) => {
-  const contentRoot = isAbsolute6(options.root) ? options.root : join18(resolve8(options.projectRoot), options.root);
+  const contentRoot = isAbsolute8(options.root) ? options.root : join22(resolve8(options.projectRoot), options.root);
   const ignore = [...new Set([...options.exclude, ...MINTLIFY_SOURCE_IGNORES])];
   const transform = (raw, file) => transformMintlifyContent(raw, {
     filePath: file,
@@ -10144,7 +10677,7 @@ var mintlifySource = (options) => {
     files.sort();
     const unsupported = new Set;
     const entries = await Promise.all(files.map(async (file) => {
-      const result = await transform(await readFile13(file, "utf-8"), file);
+      const result = await transform(await readFile15(file, "utf-8"), file);
       for (const name of result.unsupported) {
         unsupported.add(name);
       }
@@ -10153,21 +10686,21 @@ var mintlifySource = (options) => {
         body: { format: "mdx", text: parsed.content },
         data: parsed.data,
         raw: result.content,
-        ref: relative13(contentRoot, file),
+        ref: relative14(contentRoot, file),
         sourcePath: file
       };
     }));
     const diagnostics = unsupported.size > 0 ? [
       {
         code: "BLUME_MINTLIFY_UNSUPPORTED",
-        message: `Mintlify components without a Blume equivalent were left as-is: ${[...unsupported].toSorted().join(", ")}. Use the OpenAPI reference for API parameters.`,
+        message: `Mintlify components without a Blume equivalent were left as-is: ${[...unsupported].toSorted().join(", ")}. Replace them by hand or provide a matching component.`,
         severity: "warning"
       }
     ] : [];
     return { diagnostics, entries };
   };
   const validate = () => {
-    if (!existsSync13(contentRoot)) {
+    if (!existsSync15(contentRoot)) {
       throw new BlumeError({
         code: "BLUME_CONTENT_ROOT_MISSING",
         file: contentRoot,
@@ -10179,11 +10712,11 @@ var mintlifySource = (options) => {
   };
   const watch = (onChange) => {
     const disposers = [];
-    if (existsSync13(contentRoot)) {
+    if (existsSync15(contentRoot)) {
       const watcher = fsWatch2(contentRoot, { recursive: true }, onChange);
       disposers.push(() => watcher.close());
     }
-    if (options.configFile && existsSync13(options.configFile)) {
+    if (options.configFile && existsSync15(options.configFile)) {
       const watcher = fsWatch2(options.configFile, onChange);
       disposers.push(() => watcher.close());
     }
@@ -10194,8 +10727,8 @@ var mintlifySource = (options) => {
     };
   };
   const read = async (ref) => {
-    const file = join18(contentRoot, ref);
-    const result = await transform(await readFile13(file, "utf-8"), file);
+    const file = join22(contentRoot, ref);
+    const result = await transform(await readFile15(file, "utf-8"), file);
     return result.content;
   };
   return {
@@ -10211,11 +10744,12 @@ var mintlifySource = (options) => {
 };
 
 // src/core/sources/notion.ts
-import { join as join20 } from "pathe";
+import { setTimeout as sleep } from "node:timers/promises";
+import { join as join24 } from "pathe";
 
 // src/core/sources/assets.ts
-import { mkdir as mkdir4, writeFile as writeFile5 } from "node:fs/promises";
-import { extname as extname6, join as join19 } from "pathe";
+import { mkdir as mkdir4, writeFile as writeFile6 } from "node:fs/promises";
+import { extname as extname6, join as join23 } from "pathe";
 var MD_IMAGE = /!\[(?<alt>[^\]]*)\]\((?<url>[^)\s]+)\)/gu;
 var REMOTE = /^https?:\/\//u;
 var SAFE_EXT = /^\.[a-z0-9]+$/iu;
@@ -10244,7 +10778,7 @@ var materializeAssets = async (markdown, ctx) => {
       const bytes = new Uint8Array(await res.arrayBuffer());
       const file = `${hashText(url)}${extFor(url)}`;
       await mkdir4(ctx.assetsDir, { recursive: true });
-      await writeFile5(join19(ctx.assetsDir, file), bytes);
+      await writeFile6(join23(ctx.assetsDir, file), bytes);
       rewrites.set(url, `${ctx.assetsBaseUrl}/${file}`);
     } catch (error) {
       diagnostics.push({
@@ -10279,6 +10813,28 @@ var richToMarkdown = (rich = []) => rich.map((node) => {
   return node.href ? `[${text}](${node.href})` : text;
 }).join("");
 var blockField = (block) => block[block.type]?.rich_text ?? [];
+var RATE_LIMITED = 429;
+var MAX_RETRIES = 4;
+var BASE_DELAY_MS = 500;
+var SECOND_MS = 1000;
+var withNotionRetry = async (call) => {
+  let lastError;
+  for (let attempt = 0;attempt <= MAX_RETRIES; attempt += 1) {
+    try {
+      return await call();
+    } catch (error) {
+      lastError = error;
+      const { status } = error;
+      if (status !== RATE_LIMITED || attempt === MAX_RETRIES) {
+        throw error;
+      }
+      const retryAfter = Number(error.headers?.["retry-after"]);
+      const wait = retryAfter > 0 ? retryAfter * SECOND_MS : BASE_DELAY_MS * 2 ** attempt;
+      await sleep(wait);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("Notion request failed after retries.");
+};
 var collectAll = async (page, cursor, acc = []) => {
   const res = await page(cursor);
   const all = [...acc, ...res.results];
@@ -10338,8 +10894,8 @@ ${text}
 };
 var notionSource = (options, ctx) => {
   const props = options.properties ?? {};
-  const cache = snapshotCache(ctx?.cacheDir ?? join20(".blume", "cache", options.name));
-  const assetsDir = ctx?.assetsDir ?? join20(".blume", "public", "blume-assets", options.name);
+  const cache = snapshotCache(ctx?.cacheDir ?? join24(".blume", "cache", options.name));
+  const assetsDir = ctx?.assetsDir ?? join24(".blume", "public", "blume-assets", options.name);
   const assetsBaseUrl = ctx?.assetsBaseUrl ?? `/blume-assets/${options.name}`;
   let snapshot = new Map;
   const resolveClient = async () => {
@@ -10358,7 +10914,7 @@ var notionSource = (options, ctx) => {
     }
     return new Client({ auth: options.token ?? process.env.NOTION_TOKEN });
   };
-  const childrenOf = (client, blockId) => collectAll((cursor) => client.blocks.children.list({ block_id: blockId, start_cursor: cursor }));
+  const childrenOf = (client, blockId) => collectAll((cursor) => withNotionRetry(() => client.blocks.children.list({ block_id: blockId, start_cursor: cursor })));
   const renderContainer = async (client, block, render) => {
     const children = async (target) => {
       if (!target.has_children) {
@@ -10444,10 +11000,10 @@ ${rendered.join(`
       data.sidebar = { order };
     }
     const slugProp = richToMarkdown(page.properties[props.slug ?? "Slug"]?.rich_text);
-    const slug = slugify2(slugProp || title) || page.id;
+    const slug = slugify3(slugProp || title) || page.id;
     return { data, slug };
   };
-  const toEntry = async (client, page) => {
+  const toEntry2 = async (client, page) => {
     const { data, slug } = frontmatter(page);
     const mdx = await renderBlocks(client, await childrenOf(client, page.id));
     const assets = await materializeAssets(mdx, {
@@ -10472,11 +11028,11 @@ ${rendered.join(`
     const assetDiagnostics = [];
     const result = await loadWithCache(options.name, cache, async () => {
       const client = await resolveClient();
-      const pages = await collectAll((cursor) => client.databases.query({
+      const pages = await collectAll((cursor) => withNotionRetry(() => client.databases.query({
         database_id: options.database,
         start_cursor: cursor
-      }));
-      const built = await Promise.all(pages.map((page) => toEntry(client, page)));
+      })));
+      const built = await Promise.all(pages.map((page) => toEntry2(client, page)));
       for (const item of built) {
         assetDiagnostics.push(...item.diagnostics);
       }
@@ -10507,7 +11063,7 @@ ${rendered.join(`
 };
 
 // src/core/sources/sanity.ts
-import { join as join21 } from "pathe";
+import { join as join25 } from "pathe";
 
 // src/core/sources/portable-text.ts
 var HEADING_STYLES = {
@@ -10646,11 +11202,11 @@ var resolveClient = async (options, preview) => {
 };
 var sanitySource = (options, ctx) => {
   const fields = options.fields ?? {};
-  const cache = snapshotCache(ctx?.cacheDir ?? join21(".blume", "cache", options.name));
+  const cache = snapshotCache(ctx?.cacheDir ?? join25(".blume", "cache", options.name));
   let snapshot = new Map;
-  const toEntry = (doc) => {
+  const toEntry2 = (doc) => {
     const slugValue = asString2(getPath(doc, fields.slug ?? "slug.current")) ?? asString2(doc._id) ?? "untitled";
-    const slug = slugify2(slugValue) || "untitled";
+    const slug = slugify3(slugValue) || slugify3(asString2(doc._id) ?? "") || "untitled";
     const data = {};
     const title = asString2(getPath(doc, fields.title ?? "title"));
     const description = asString2(getPath(doc, fields.description ?? "description"));
@@ -10682,7 +11238,7 @@ var sanitySource = (options, ctx) => {
     const result = await loadWithCache(options.name, cache, async () => {
       const client = await resolveClient(options, ctx?.preview ?? false);
       const docs = await client.fetch(options.query);
-      return docs.map(toEntry);
+      return docs.map(toEntry2);
     }, ctx?.refresh ?? true);
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
     return result;
@@ -10721,8 +11277,8 @@ var uniqueNamer = () => {
 };
 var sourceContext = (context, name, runtime) => ({
   assetsBaseUrl: `/blume-assets/${name}`,
-  assetsDir: join22(context.outDir, "public", "blume-assets", name),
-  cacheDir: join22(context.outDir, "cache", name),
+  assetsDir: join26(context.outDir, "public", "blume-assets", name),
+  cacheDir: join26(context.outDir, "cache", name),
   mode: runtime.mode,
   preview: runtime.preview,
   projectRoot: context.root,
@@ -10804,7 +11360,7 @@ var baseName = (def) => {
   }
   return def.prefix ?? def.type;
 };
-var resolveSources = (config, context, runtime) => {
+var contentSources = (config, context, runtime) => {
   const defs = config.content.sources;
   if (!defs || defs.length === 0) {
     return [
@@ -10820,6 +11376,14 @@ var resolveSources = (config, context, runtime) => {
   const nameFor = uniqueNamer();
   return defs.map((def) => buildSource(def, nameFor(baseName(def)), context, runtime));
 };
+var resolveSources = (config, context, runtime) => {
+  const sources = contentSources(config, context, runtime);
+  const references = blumeReferences(config);
+  if (references.length > 0) {
+    sources.push(openApiSource(references, sourceContext(context, "openapi", runtime)));
+  }
+  return sources;
+};
 
 // src/core/project-graph.ts
 var applyConfigOverrides = (config, overrides) => {
@@ -10848,7 +11412,9 @@ var scanProject = async (root, options = {}) => {
   });
   const { bridge } = configResult;
   const config = applyConfigOverrides(configResult.config, options.overrides);
-  const context = resolveProjectContext(root, config);
+  const context = resolveProjectContext(root, config, {
+    runtimeDir: options.runtimeDir
+  });
   const sources = resolveSources(config, context, {
     mode,
     preview,
@@ -10916,8 +11482,8 @@ var scanProject = async (root, options = {}) => {
 };
 
 // src/cli/env.ts
-import { existsSync as existsSync14, readFileSync as readFileSync8 } from "node:fs";
-import { dirname as dirname12, join as join23, resolve as resolve9 } from "pathe";
+import { existsSync as existsSync16, readFileSync as readFileSync9 } from "node:fs";
+import { dirname as dirname12, join as join27, resolve as resolve9 } 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;
@@ -10955,8 +11521,8 @@ var applyEnv = (parsed) => {
 };
 var loadFile = (path) => {
   try {
-    if (existsSync14(path)) {
-      applyEnv(parseEnv(readFileSync8(path, "utf-8")));
+    if (existsSync16(path)) {
+      applyEnv(parseEnv(readFileSync9(path, "utf-8")));
     }
   } catch {}
 };
@@ -10964,10 +11530,10 @@ var loadEnvFiles = (startDir) => {
   let dir = resolve9(startDir);
   let done = false;
   while (!done) {
-    loadFile(join23(dir, ".env.local"));
-    loadFile(join23(dir, ".env"));
+    loadFile(join27(dir, ".env.local"));
+    loadFile(join27(dir, ".env"));
     const parent = dirname12(dir);
-    done = existsSync14(join23(dir, ".git")) || parent === dir;
+    done = existsSync16(join27(dir, ".git")) || parent === dir;
     dir = parent;
   }
 };
@@ -11040,7 +11606,8 @@ var prepareProject = async (options) => {
       mode: options.mode,
       overrides: options.overrides,
       preview: options.preview,
-      refresh: options.refresh
+      refresh: options.refresh,
+      runtimeDir: options.runtimeDir
     });
   } catch (error) {
     if (error instanceof BlumeError) {
@@ -11082,29 +11649,38 @@ var prepareProject = async (options) => {
 
 // src/cli/commands/build.ts
 var ADAPTERS = ["vercel", "node", "netlify", "cloudflare"];
+var validateBudgetFlags = (args) => {
+  for (const flag of ["budget-js", "budget-css"]) {
+    const value = args[flag];
+    if (value !== undefined && !(Number(value) > 0)) {
+      logger.error(`Invalid --${flag} "${value}" (expected a positive number of kB).`);
+      process.exit(1);
+    }
+  }
+};
 var emitRedirectFiles = async (config, distDir) => {
   const { redirects } = config;
   if (redirects.length === 0 || config.deployment.output !== "static") {
     return;
   }
-  await writeFile6(join24(distDir, "blume-redirects.json"), buildRedirectManifest(redirects), "utf-8");
+  await writeFile7(join28(distDir, "blume-redirects.json"), buildRedirectManifest(redirects), "utf-8");
   const platformFiles = [
     { content: buildNetlifyRedirects(redirects), name: "_redirects" },
     { content: buildVercelConfig(redirects), name: "vercel.json" }
   ];
-  await Promise.all(platformFiles.map((file) => existsSync15(join24(distDir, file.name)) ? Promise.resolve() : writeFile6(join24(distDir, file.name), file.content, "utf-8")));
+  await Promise.all(platformFiles.map((file) => existsSync17(join28(distDir, file.name)) ? Promise.resolve() : writeFile7(join28(distDir, file.name), file.content, "utf-8")));
   logger.success(`Emitted redirect files for ${redirects.length} redirect(s)`);
 };
 var formatBytes = (bytes) => bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(bytes < 1024 * 100 ? 1 : 0)} kB`;
 var astroAssets = async (distDir, ext) => {
-  const astroDir = join24(distDir, "_astro");
-  if (!existsSync15(astroDir)) {
+  const astroDir = join28(distDir, "_astro");
+  if (!existsSync17(astroDir)) {
     return [];
   }
   const entries = await readdir(astroDir);
   const files = entries.filter((name) => name.endsWith(`.${ext}`));
   const sized = await Promise.all(files.map(async (name) => {
-    const info = await stat(join24(astroDir, name));
+    const info = await stat(join28(astroDir, name));
     return { name, size: info.size };
   }));
   return sized.toSorted((a, b) => b.size - a.size);
@@ -11146,6 +11722,58 @@ var enforceBudget = async (distDir, args) => {
   }
   return passed ? "pass" : "fail";
 };
+var publishBuildArtifacts = async (project, distDir, args) => {
+  if (project.config.search.provider === "pagefind") {
+    logger.start("Building search index");
+    const indexed = await buildSearchIndex(distDir);
+    logger.success(`Indexed ${indexed} page(s) for search`);
+  }
+  await syncSearchProvider(project, {
+    start: (message) => logger.start(message),
+    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(join28(distDir, "llms.txt"), index, "utf-8"),
+      writeFile7(join28(distDir, "llms-full.txt"), full, "utf-8")
+    ]);
+    logger.success("Generated llms.txt and llms-full.txt");
+  }
+  const sitemap = buildSitemap(project);
+  if (sitemap && !existsSync17(join28(distDir, "sitemap.xml"))) {
+    await writeFile7(join28(distDir, "sitemap.xml"), sitemap, "utf-8");
+    logger.success("Generated sitemap.xml");
+  }
+  const robots = buildRobots(project);
+  if (robots && !existsSync17(join28(distDir, "robots.txt"))) {
+    await writeFile7(join28(distDir, "robots.txt"), robots, "utf-8");
+    logger.success("Generated robots.txt");
+  }
+  await emitRedirectFiles(project.config, distDir);
+  const { config } = project;
+  const features = serverFeatures(config);
+  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)"}`,
+    `Robots     ${robots ? "yes" : "no"}`,
+    `LLM files  ${config.ai.llmsTxt ? "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);
+  }
+  logger.success(`Built to ${distDir}`);
+};
 var buildCommand = defineCommand2({
   args: {
     adapter: {
@@ -11168,6 +11796,10 @@ var buildCommand = defineCommand2({
       description: "Fail if total client JavaScript exceeds this many kB.",
       type: "string"
     },
+    isolated: {
+      description: "Build into an isolated .blume-verify runtime (and its own dist) so a running dev server and the real dist/ are untouched. For verifying changes while `blume dev` runs.",
+      type: "boolean"
+    },
     output: {
       description: "Output mode: static | server.",
       type: "string"
@@ -11184,6 +11816,11 @@ 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);
+    if (args.isolated) {
+      await ensureGitignore(root, [".blume-verify/"]);
+    }
     if (args.output && args.output !== "static" && args.output !== "server") {
       logger.error(`Invalid --output "${args.output}" (use static | server).`);
       process.exit(1);
@@ -11192,6 +11829,7 @@ var buildCommand = defineCommand2({
       logger.error(`Invalid --adapter "${args.adapter}" (use ${ADAPTERS.join(" | ")}).`);
       process.exit(1);
     }
+    validateBudgetFlags(args);
     const project = await prepareProject({
       mode: "build",
       overrides: {
@@ -11201,6 +11839,7 @@ var buildCommand = defineCommand2({
       },
       preview: args.preview,
       root,
+      runtimeDir,
       strict: args.strict
     });
     logger.start(`Building ${project.graph.pages.length} page(s) (${project.config.deployment.output} output)`);
@@ -11208,68 +11847,27 @@ var buildCommand = defineCommand2({
       logLevel: "info",
       root: project.context.outDir
     });
-    const distDir = join24(root, "dist");
-    if (project.config.search.provider === "pagefind") {
-      logger.start("Building search index");
-      const indexed = await buildSearchIndex(distDir);
-      logger.success(`Indexed ${indexed} page(s) for search`);
-    }
-    await syncSearchProvider(project, {
-      start: (message) => logger.start(message),
-      success: (message) => logger.success(message),
-      warn: (message) => logger.warn(message)
-    });
-    if (project.config.ai.llmsTxt) {
-      const { index, full } = await buildLlmsFiles(project);
-      await Promise.all([
-        writeFile6(join24(distDir, "llms.txt"), index, "utf-8"),
-        writeFile6(join24(distDir, "llms-full.txt"), full, "utf-8")
-      ]);
-      logger.success("Generated llms.txt and llms-full.txt");
-    }
-    const sitemap = buildSitemap(project);
-    if (sitemap && !existsSync15(join24(distDir, "sitemap.xml"))) {
-      await writeFile6(join24(distDir, "sitemap.xml"), sitemap, "utf-8");
-      logger.success("Generated sitemap.xml");
-    }
-    const robots = buildRobots(project);
-    if (robots && !existsSync15(join24(distDir, "robots.txt"))) {
-      await writeFile6(join24(distDir, "robots.txt"), robots, "utf-8");
-      logger.success("Generated robots.txt");
-    }
-    await emitRedirectFiles(project.config, distDir);
-    const { config } = project;
-    const features = serverFeatures(config);
-    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)"}`,
-      `Robots     ${robots ? "yes" : "no"}`,
-      `LLM files  ${config.ai.llmsTxt ? "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);
+    const distDir = project.context.distDir ?? join28(root, "dist");
+    if (runtimeDir) {
+      logger.success(`Isolated build OK — output at ${distDir} (not published).`);
+      return;
     }
-    logger.success(`Built to ${distDir}`);
+    await publishBuildArtifacts(project, distDir, args);
   }
 });
 
 // src/cli/commands/check.ts
-import { existsSync as existsSync16 } from "node:fs";
+import { existsSync as existsSync18 } from "node:fs";
 import { check } from "@astrojs/check";
 import { sync } from "astro";
 import { defineCommand as defineCommand3 } from "citty";
-import { join as join25 } from "pathe";
+import { join as join29 } from "pathe";
 var checkCommand = defineCommand3({
   args: {
+    isolated: {
+      description: "Type-check in an isolated .blume-verify runtime so a running dev server is untouched. For verifying changes while `blume dev` runs.",
+      type: "boolean"
+    },
     preview: {
       description: "Include drafts and unpublished CMS content.",
       type: "boolean"
@@ -11285,21 +11883,27 @@ 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);
+    if (args.isolated) {
+      await ensureGitignore(root, [".blume-verify/"]);
+    }
     const project = await prepareProject({
       mode: "build",
       preview: args.preview,
       root,
+      runtimeDir,
       strict: args.strict
     });
     const { outDir } = project.context;
     await sync({ logLevel: "warn", root: outDir });
-    const tsconfig = join25(root, "tsconfig.json");
+    const tsconfig = join29(root, "tsconfig.json");
     logger.start(`Type-checking ${project.graph.pages.length} page(s)`);
     const failed = await check({
       minimumFailingSeverity: "error",
       minimumSeverity: "hint",
       root: outDir,
-      tsconfig: existsSync16(tsconfig) ? tsconfig : undefined,
+      tsconfig: existsSync18(tsconfig) ? tsconfig : undefined,
       watch: false
     });
     if (failed) {
@@ -11315,6 +11919,9 @@ import { watch } from "node:fs";
 import { dev } from "astro";
 import { defineCommand as defineCommand4 } from "citty";
 
+// src/astro/static-assets.ts
+import { extname as extname7, join as join30, relative as relative15, resolve as resolve10, sep } from "pathe";
+
 // src/astro/integration.ts
 var overlayServer = null;
 var overlayChannel = () => overlayServer?.ws ?? overlayServer?.hot;
@@ -11348,6 +11955,20 @@ ${body}`,
   });
 };
 
+// src/cli/args.ts
+var MAX_PORT = 65535;
+var parsePort = (value) => {
+  if (value === undefined) {
+    return;
+  }
+  const port = Number(value);
+  if (!(Number.isInteger(port) && port >= 1 && port <= MAX_PORT)) {
+    logger.error(`Invalid --port "${value}" (expected an integer 1-${MAX_PORT}).`);
+    process.exit(1);
+  }
+  return port;
+};
+
 // src/cli/commands/dev.ts
 var devCommand = defineCommand4({
   args: {
@@ -11376,7 +11997,8 @@ var devCommand = defineCommand4({
     const root = process.cwd();
     const preview = args.preview ?? false;
     const overrides = args["content-dir"] ? { contentRoot: args["content-dir"] } : undefined;
-    const port = args.port ? Number(args.port) : 4321;
+    const explicitPort = parsePort(args.port);
+    const port = explicitPort ?? 4321;
     const devServerUrl = `http://localhost:${port}`;
     const project = await prepareProject({
       devServerUrl,
@@ -11389,13 +12011,15 @@ var devCommand = defineCommand4({
     if (project.bridge) {
       logger.info('Detected docs.json — running in Mintlify bridge mode (no migration). Run "blume migrate mintlify" to convert permanently.');
     }
+    const releaseLock = acquireDevLock(project.context.outDir);
+    process.on("exit", releaseLock);
     const server = await dev({
       logLevel: args.debug ? "debug" : "info",
       root: project.context.outDir,
       server: {
         host: args.host ?? false,
         open: args.open ?? false,
-        port: args.port ? Number(args.port) : undefined
+        port: explicitPort
       }
     });
     showBlumeErrorOverlay(project.diagnostics);
@@ -11436,6 +12060,7 @@ var devCommand = defineCommand4({
       for (const dispose of disposers) {
         dispose();
       }
+      releaseLock();
       await server.stop();
       process.exit(0);
     };
@@ -11505,6 +12130,7 @@ var doctorCommand = defineCommand5({
     }
     if (args.json) {
       if (reportDiagnosticsJson(diagnostics, root)) {
+        await flushStdout();
         process.exit(1);
       }
       return;
@@ -11520,15 +12146,19 @@ var doctorCommand = defineCommand5({
 });
 
 // src/cli/commands/eject.ts
-import { readFile as readFile15, writeFile as writeFile8 } from "node:fs/promises";
+import { readFile as readFile17, writeFile as writeFile9 } from "node:fs/promises";
 import { defineCommand as defineCommand6 } from "citty";
-import { join as join27, relative as relative15 } from "pathe";
+import { join as join32, relative as relative17 } from "pathe";
 
 // src/registry/eject.ts
-import { existsSync as existsSync17 } from "node:fs";
-import { cp, mkdir as mkdir5, readFile as readFile14, rm as rm2, writeFile as writeFile7 } from "node:fs/promises";
-import { join as join26, relative as relative14 } from "pathe";
+import { existsSync as existsSync19 } from "node:fs";
+import { cp, mkdir as mkdir5, readFile as readFile16, rm as rm2, writeFile as writeFile8 } from "node:fs/promises";
+import { join as join31, relative as relative16 } from "pathe";
 var POSIX = (path) => path.split("\\").join("/");
+var ejectOpenApiData = (project) => {
+  const source = project.sources.find(isOpenApiSource);
+  return source ? source.openApiData() : {};
+};
 var askFiles = async (project, srcDir, genDir) => {
   const { ask } = project.config.ai;
   if (!ask?.enabled) {
@@ -11538,14 +12168,14 @@ var askFiles = async (project, srcDir, genDir) => {
   const files = [
     {
       content: askEndpointTemplate(resolveAskBackend(ask), grounded),
-      path: join26(srcDir, "pages", "api", "ask.ts")
+      path: join31(srcDir, "pages", "api", "ask.ts")
     }
   ];
   if (grounded) {
     files.push({
       content: `${JSON.stringify(await buildAskData(project))}
 `,
-      path: join26(genDir, "ask-data.json")
+      path: join31(genDir, "ask-data.json")
     });
   }
   return files;
@@ -11553,15 +12183,15 @@ var askFiles = async (project, srcDir, genDir) => {
 var eject = async (root) => {
   const project = await scanProject(root, { mode: "build" });
   const { context, config } = project;
-  const srcDir = join26(root, "src");
-  const genDir = join26(srcDir, "generated");
+  const srcDir = join31(root, "src");
+  const genDir = join31(srcDir, "generated");
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
   const [pages, needsReactRaw, userTheme, rawMarkdown, islands, examples] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(root),
-    context.themeFile ? readFile14(context.themeFile, "utf-8") : Promise.resolve(""),
+    context.themeFile ? readFile16(context.themeFile, "utf-8") : Promise.resolve(""),
     buildRawMarkdown(project),
     discoverIslands(root),
     discoverExamples(root, config.examples)
@@ -11575,13 +12205,13 @@ var eject = async (root) => {
   const needsSvelte = frameworks.has("svelte");
   const relContext = {
     ...context,
-    contentRoot: POSIX(relative14(root, context.contentRoot)),
+    contentRoot: POSIX(relative16(root, context.contentRoot)),
     outDir: ".",
     root: "."
   };
-  const componentsImport = context.componentsFile ? `../../${POSIX(relative14(root, context.componentsFile))}` : null;
+  const componentsImport = context.componentsFile ? `../../${POSIX(relative16(root, context.componentsFile))}` : null;
   const relPages = pages.map((page) => ({
-    entrypoint: POSIX(relative14(root, page.entrypoint)),
+    entrypoint: POSIX(relative16(root, page.entrypoint)),
     pattern: page.pattern
   }));
   const staged = collectStaged(project);
@@ -11598,17 +12228,19 @@ var eject = async (root) => {
         needsReact,
         needsSvelte,
         needsVue,
+        openapiPath: "./src/generated/openapi.json",
         pages: relPages,
         searchClientPath: "./src/generated/search-client.ts",
         themePath: "./src/generated/app.css"
       }),
-      path: join26(root, "astro.config.mjs")
+      path: join31(root, "astro.config.mjs")
     },
     {
       content: runtimeTsconfigTemplate(),
-      path: join26(root, "tsconfig.json")
+      path: join31(root, "tsconfig.json"),
+      skipIfExists: true
     },
-    { content: envTemplate(), path: join26(srcDir, "env.d.ts") },
+    { content: envTemplate(), path: join31(srcDir, "env.d.ts") },
     {
       content: contentConfigTemplate({
         config,
@@ -11616,7 +12248,7 @@ var eject = async (root) => {
         staged: hasStaged,
         stagedBase: stagedDir
       }),
-      path: join26(srcDir, "content.config.ts")
+      path: join31(srcDir, "content.config.ts")
     },
     {
       content: catchAllPageTemplate({
@@ -11626,19 +12258,19 @@ var eject = async (root) => {
         mathEnabled: config.markdown.math,
         needsReact
       }),
-      path: join26(srcDir, "pages", "[...slug].astro")
+      path: join31(srcDir, "pages", "[...slug].astro")
     },
     {
       content: planComponentSlots(componentsImport, null).module,
-      path: join26(genDir, "components.ts")
+      path: join31(genDir, "components.ts")
     },
     {
       content: islandMapTemplate(islands.islands),
-      path: join26(genDir, "islands.ts")
+      path: join31(genDir, "islands.ts")
     },
     {
       content: exampleMapTemplate(examples.examples),
-      path: join26(genDir, "examples.ts")
+      path: join31(genDir, "examples.ts")
     },
     {
       content: tailwindEntryTemplate({
@@ -11650,21 +12282,26 @@ var eject = async (root) => {
         twoslashCss: twoslashCss(),
         userTheme
       }),
-      path: join26(genDir, "app.css")
+      path: join31(genDir, "app.css")
+    },
+    { content: buildRuntimeData(project), path: join31(genDir, "data.json") },
+    {
+      content: `${JSON.stringify(ejectOpenApiData(project))}
+`,
+      path: join31(genDir, "openapi.json")
     },
-    { content: buildRuntimeData(project), path: join26(genDir, "data.json") },
     {
       content: `${JSON.stringify(rawMarkdown)}
 `,
-      path: join26(genDir, "raw-markdown.json")
+      path: join31(genDir, "raw-markdown.json")
     },
     {
       content: rawMarkdownEndpointTemplate(),
-      path: join26(srcDir, "pages", "[...slug].md.ts")
+      path: join31(srcDir, "pages", "[...slug].md.ts")
     },
     {
       content: rawMarkdownEndpointTemplate(),
-      path: join26(srcDir, "pages", "[...slug].mdx.ts")
+      path: join31(srcDir, "pages", "[...slug].mdx.ts")
     }
   ];
   if (askEnabled) {
@@ -11673,34 +12310,34 @@ var eject = async (root) => {
   if (config.seo.og.enabled) {
     files.push({
       content: ogEndpointTemplate(customOgRoutes(pages, config.title)),
-      path: join26(srcDir, "pages", "og", "[...slug].png.ts")
+      path: join31(srcDir, "pages", "og", "[...slug].png.ts")
     });
   }
   if (!routeIsTaken(pages, project.graph.pages, "/404")) {
     files.push({
       content: notFoundPageTemplate(),
-      path: join26(srcDir, "pages", "404.astro")
+      path: join31(srcDir, "pages", "404.astro")
     });
   }
   files.push({
     content: searchClientTemplate(config),
-    path: join26(genDir, "search-client.ts")
+    path: join31(genDir, "search-client.ts")
   });
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);
     files.push({
       content: `${JSON.stringify(documents)}
 `,
-      path: join26(genDir, "search.json")
+      path: join31(genDir, "search.json")
     }, {
       content: searchEndpointTemplate(),
-      path: join26(srcDir, "pages", "blume-search.json.ts")
+      path: join31(srcDir, "pages", "blume-search.json.ts")
     });
   }
   if (config.search.provider === "mixedbread") {
     files.push({
       content: mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? ""),
-      path: join26(srcDir, "pages", "api", "search.ts")
+      path: join31(srcDir, "pages", "api", "search.ts")
     });
   }
   const feeds = buildRssFeeds(project);
@@ -11709,13 +12346,13 @@ var eject = async (root) => {
     files.push({
       content: `${JSON.stringify(feedXml)}
 `,
-      path: join26(genDir, "rss.json")
+      path: join31(genDir, "rss.json")
     }, {
       content: rssEndpointTemplate(),
-      path: join26(srcDir, "pages", "[section]", "rss.xml.ts")
+      path: join31(srcDir, "pages", "[section]", "rss.xml.ts")
     });
   }
-  if (hasReferences(config)) {
+  if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
       contentRoutes: new Set(project.graph.pages.map((page) => page.route)),
@@ -11724,40 +12361,41 @@ var eject = async (root) => {
     for (const file of references.files) {
       files.push({
         content: file.content,
-        path: join26(srcDir, "pages", file.pagePath)
+        path: join31(srcDir, "pages", file.pagePath)
       });
     }
   }
   files.push(...islands.islands.map((island) => ({
     content: islandWrapperTemplate(island),
-    path: join26(genDir, "islands", `${island.name}.astro`)
+    path: join31(genDir, "islands", `${island.name}.astro`)
   })), ...examples.examples.map((example) => ({
     content: exampleWrapperTemplate(example),
-    path: join26(genDir, "examples", `${exampleSlug(example.path)}.astro`)
+    path: join31(genDir, "examples", `${exampleSlug(example.path)}.astro`)
   })));
   for (const [entryId, content] of staged) {
-    files.push({ content, path: join26(root, stagedDir, entryId) });
+    files.push({ content, path: join31(root, stagedDir, entryId) });
   }
-  await Promise.all(files.map(async (file) => {
-    await mkdir5(join26(file.path, ".."), { recursive: true });
-    await writeFile7(file.path, file.content, "utf-8");
+  const written = files.filter((file) => !(file.skipIfExists && existsSync19(file.path)));
+  await Promise.all(written.map(async (file) => {
+    await mkdir5(join31(file.path, ".."), { recursive: true });
+    await writeFile8(file.path, file.content, "utf-8");
   }));
-  const assetsSrc = join26(context.outDir, "public", "blume-assets");
-  if (existsSync17(assetsSrc)) {
-    await cp(assetsSrc, join26(root, "public", "blume-assets"), {
+  const assetsSrc = join31(context.outDir, "public", "blume-assets");
+  if (existsSync19(assetsSrc)) {
+    await cp(assetsSrc, join31(root, "public", "blume-assets"), {
       recursive: true
     });
   }
   await rm2(context.outDir, { force: true, recursive: true });
-  return files.map((file) => file.path);
+  return written.map((file) => file.path);
 };
 
 // src/cli/commands/eject.ts
 var updatePackageScripts = async (root) => {
-  const pkgPath = join27(root, "package.json");
+  const pkgPath = join32(root, "package.json");
   let pkg;
   try {
-    pkg = JSON.parse(await readFile15(pkgPath, "utf-8"));
+    pkg = JSON.parse(await readFile17(pkgPath, "utf-8"));
   } catch {
     return;
   }
@@ -11768,7 +12406,7 @@ var updatePackageScripts = async (root) => {
     dev: "astro dev",
     preview: "astro preview"
   };
-  await writeFile8(pkgPath, `${JSON.stringify(pkg, null, 2)}
+  await writeFile9(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `, "utf-8");
 };
 var ejectCommand = defineCommand6({
@@ -11781,8 +12419,9 @@ var ejectCommand = defineCommand6({
   },
   async run({ args }) {
     const root = process.cwd();
+    refuseIfDevRunning(root, "ejecting");
     if (!args.yes) {
-      logger.warn("Eject is one-way: it writes astro.config.mjs and src/ into your project and removes .blume.");
+      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;
     }
@@ -11790,7 +12429,7 @@ var ejectCommand = defineCommand6({
     await updatePackageScripts(root);
     logger.success(`Ejected ${files.length} file(s):`);
     for (const file of files) {
-      process.stdout.write(`  ${relative15(root, file)}
+      process.stdout.write(`  ${relative17(root, file)}
 `);
     }
     logger.box(`Your project is now a standalone Astro app.
@@ -11803,10 +12442,10 @@ The blume package remains importable.`);
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync18 } from "node:fs";
-import { mkdir as mkdir6, writeFile as writeFile9 } from "node:fs/promises";
+import { existsSync as existsSync20 } from "node:fs";
+import { mkdir as mkdir6, writeFile as writeFile10 } from "node:fs/promises";
 import { defineCommand as defineCommand7 } from "citty";
-import { basename as basename4, dirname as dirname13, join as join28 } from "pathe";
+import { basename as basename4, dirname as dirname13, isAbsolute as isAbsolute9, join as join33, relative as relative18 } from "pathe";
 var toPackageName = (raw) => raw.toLowerCase().replaceAll(/[^a-z0-9._-]+/gu, "-").replaceAll(/^[-_.]+|[-_.]+$/gu, "") || "docs";
 var packageTemplate = (name, version) => `{
   "name": ${JSON.stringify(name)},
@@ -11854,7 +12493,7 @@ var STARTERS = {
     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`."),
-        path: join28(dir, "index.mdx")
+        path: join33(dir, "index.mdx")
       }
     ]
   },
@@ -11869,7 +12508,7 @@ var STARTERS = {
     files: (dir) => [
       {
         content: page("Introduction", "Welcome to your new Blume docs.", "# Introduction\n\nWrite your docs here, and log releases under `changelog/`."),
-        path: join28(dir, "index.mdx")
+        path: join33(dir, "index.mdx")
       },
       {
         content: `---
@@ -11880,7 +12519,7 @@ date: 2026-01-01
 
 The first release. Edit \`${dir}/changelog/v1-0-0.mdx\` or add new entries beside it.
 `,
-        path: join28(dir, "changelog", "v1-0-0.mdx")
+        path: join33(dir, "changelog", "v1-0-0.mdx")
       }
     ]
   },
@@ -11893,7 +12532,7 @@ The first release. Edit \`${dir}/changelog/v1-0-0.mdx\` or add new entries besid
 Welcome to **Blume** — markdown-first docs powered by Astro and Vite.
 
 Edit \`${dir}/index.mdx\` to get started, then run \`blume dev\`.`),
-        path: join28(dir, "index.mdx")
+        path: join33(dir, "index.mdx")
       }
     ]
   },
@@ -11904,11 +12543,11 @@ Edit \`${dir}/index.mdx\` to get started, then run \`blume dev\`.`),
         content: page("Introduction", "Get started with the SDK.", `# Introduction
 
 Install the SDK and make your first call. See [Installation](/installation).`),
-        path: join28(dir, "index.mdx")
+        path: join33(dir, "index.mdx")
       },
       {
         content: page("Installation", "Install the SDK.", "# Installation\n\n```package-install\nyour-sdk\n```"),
-        path: join28(dir, "installation.mdx")
+        path: join33(dir, "installation.mdx")
       }
     ]
   }
@@ -11918,12 +12557,12 @@ var commandsFor = (pm) => ({
   install: `${pm} install`
 });
 var writeFileSafe = async (path, content) => {
-  if (existsSync18(path)) {
+  if (existsSync20(path)) {
     logger.info(`Skipped existing ${path}`);
     return false;
   }
   await mkdir6(dirname13(path), { recursive: true });
-  await writeFile9(path, content, "utf-8");
+  await writeFile10(path, content, "utf-8");
   logger.success(`Created ${path}`);
   return true;
 };
@@ -11955,6 +12594,10 @@ var initCommand = defineCommand7({
   async run({ args }) {
     const root = process.cwd();
     const contentDir = args["content-dir"] ?? "docs";
+    if (isAbsolute9(contentDir) || relative18(root, join33(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)) {
       logger.error(`Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`);
@@ -11966,9 +12609,13 @@ var initCommand = defineCommand7({
       process.exit(1);
     }
     const starter = STARTERS[template];
-    const createdPackage = await writeFileSafe(join28(root, "package.json"), packageTemplate(toPackageName(basename4(root)), getBlumeVersion()));
-    await writeFileSafe(join28(root, "blume.config.ts"), starter.config);
-    await Promise.all(starter.files(contentDir).map((file) => writeFileSafe(join28(root, file.path), file.content)));
+    const createdPackage = await writeFileSafe(join33(root, "package.json"), packageTemplate(toPackageName(basename4(root)), getBlumeVersion()));
+    await writeFileSafe(join33(root, "blume.config.ts"), starter.config);
+    await Promise.all(starter.files(contentDir).map((file) => writeFileSafe(join33(root, file.path), file.content)));
+    const ignored = await ensureGitignore(root, [".blume/", "dist/"]);
+    if (ignored.length > 0) {
+      logger.success(`Added ${ignored.join(", ")} to .gitignore`);
+    }
     const commands = commandsFor(pm);
     if (args.eject) {
       try {
@@ -12005,15 +12652,15 @@ var initCommand = defineCommand7({
 import { defineCommand as defineCommand8 } from "citty";
 
 // src/migrate/fumadocs/index.ts
-import { existsSync as existsSync22 } from "node:fs";
-import { mkdir as mkdir8, readFile as readFile17, rename as rename3, rm as rm3, writeFile as writeFile11 } from "node:fs/promises";
-import { dirname as dirname16, join as join31, relative as relative16 } from "pathe";
+import { existsSync as existsSync24 } from "node:fs";
+import { mkdir as mkdir8, readFile as readFile19, rename as rename3, rm as rm3, writeFile as writeFile12 } from "node:fs/promises";
+import { dirname as dirname16, join as join36, relative as relative19 } from "pathe";
 import { glob as glob8 } from "tinyglobby";
 
 // src/migrate/fumadocs/config.ts
-import { existsSync as existsSync19 } from "node:fs";
-import { readFile as readFile16 } from "node:fs/promises";
-import { basename as basename5, dirname as dirname14, join as join29 } from "pathe";
+import { existsSync as existsSync21 } from "node:fs";
+import { readFile as readFile18 } from "node:fs/promises";
+import { basename as basename5, dirname as dirname14, join as join34 } from "pathe";
 var SOURCE_FILES = [
   "lib/source.ts",
   "app/source.ts",
@@ -12043,7 +12690,7 @@ var GENERIC_NAMES = new Set([
 var gitRepoRoot = (start) => {
   let dir = start;
   for (;; ) {
-    if (existsSync19(join29(dir, ".git"))) {
+    if (existsSync21(join34(dir, ".git"))) {
       return dir;
     }
     const parent = dirname14(dir);
@@ -12055,12 +12702,12 @@ var gitRepoRoot = (start) => {
 };
 var bareName = (name) => name.includes("/") ? name.slice(name.lastIndexOf("/") + 1) : name;
 var readTitle = async (root) => {
-  const packageJson = join29(root, "package.json");
-  if (!existsSync19(packageJson)) {
+  const packageJson = join34(root, "package.json");
+  if (!existsSync21(packageJson)) {
     return "Documentation";
   }
   try {
-    const parsed = JSON.parse(await readFile16(packageJson, "utf-8"));
+    const parsed = JSON.parse(await readFile18(packageJson, "utf-8"));
     const { name } = parsed;
     if (typeof name !== "string" || !name.trim()) {
       return "Documentation";
@@ -12081,11 +12728,11 @@ var readTitle = async (root) => {
 };
 var scrapeBaseUrl = async (root) => {
   for (const candidate of SOURCE_FILES) {
-    const file = join29(root, candidate);
-    if (!existsSync19(file)) {
+    const file = join34(root, candidate);
+    if (!existsSync21(file)) {
       continue;
     }
-    const base = BASE_URL.exec(await readFile16(file, "utf-8"))?.groups?.base;
+    const base = BASE_URL.exec(await readFile18(file, "utf-8"))?.groups?.base;
     if (base) {
       return base;
     }
@@ -12114,9 +12761,9 @@ var loadFumadocsConfig = async (root) => {
 };
 
 // src/migrate/fumadocs/content.ts
-import { existsSync as existsSync20 } from "node:fs";
+import { existsSync as existsSync22 } from "node:fs";
 import { readFile as readFileFromDisk2 } from "node:fs/promises";
-import { dirname as dirname15, resolve as resolve10 } from "pathe";
+import { dirname as dirname15, resolve as resolve11 } from "pathe";
 var FUMADOCS_IMPORT = /^import\s+[\s\S]*?\s+from\s+["']fumadocs-(?:ui|core|mdx)(?:\/[^"']*)?["'];?[ \t]*\n?/gmu;
 var stripFumadocsImports = (source) => {
   const stripped = source.replace(FUMADOCS_IMPORT, "");
@@ -12317,12 +12964,16 @@ var inlineFumadocsIncludes = async (source, options) => {
     if (!rawPath) {
       continue;
     }
-    const target = resolve10(dirname15(options.filePath), rawPath);
+    const target = resolve11(dirname15(options.filePath), rawPath);
+    if (!isInsideRoot2(options.root, target)) {
+      warnings.push(`<include> target "${rawPath}" is outside the docs tree — left as-is.`);
+      continue;
+    }
     if (seen.has(target)) {
       warnings.push(`Circular <include> "${rawPath}" — left as-is.`);
       continue;
     }
-    if (!existsSync20(target)) {
+    if (!existsSync22(target)) {
       warnings.push(`<include> target "${rawPath}" not found — left as-is.`);
       continue;
     }
@@ -12354,9 +13005,9 @@ var normalizeFumadocsPageMeta = (value) => {
 };
 
 // src/migrate/fumadocs/groups.ts
-import { existsSync as existsSync21, statSync as statSync2 } from "node:fs";
-import { mkdir as mkdir7, rename as rename2, writeFile as writeFile10 } from "node:fs/promises";
-import { basename as basename6, join as join30 } from "pathe";
+import { existsSync as existsSync23, statSync as statSync2 } from "node:fs";
+import { mkdir as mkdir7, rename as rename2, writeFile as writeFile11 } from "node:fs/promises";
+import { basename as basename6, join as join35 } from "pathe";
 
 // src/migrate/fumadocs/meta.ts
 var SEPARATOR = /^---(?<label>.*)---$/u;
@@ -12501,13 +13152,16 @@ var isDirectory = (path) => {
   }
 };
 var resolveEntry = (docsDir, name) => {
+  if (!isInsideRoot2(docsDir, join35(docsDir, name))) {
+    return null;
+  }
   for (const ext of PAGE_EXTS) {
-    const file = join30(docsDir, `${name}${ext}`);
-    if (existsSync21(file)) {
+    const file = join35(docsDir, `${name}${ext}`);
+    if (existsSync23(file)) {
       return { kind: "file", path: file };
     }
   }
-  const folder = join30(docsDir, name);
+  const folder = join35(docsDir, name);
   return isDirectory(folder) ? { kind: "folder", path: folder } : null;
 };
 var humanize2 = (name) => name.split(WORD_SPLIT3).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
@@ -12542,8 +13196,8 @@ var moveItemIntoGroup = async (item, docsDir, groupDir, label, warnings) => {
     warnings.push(`Sidebar entry "${item.name}" in section "${label}" matched no page or folder; skipped.`);
     return null;
   }
-  const dest = join30(groupDir, basename6(resolved.path));
-  if (existsSync21(dest)) {
+  const dest = join35(groupDir, basename6(resolved.path));
+  if (existsSync23(dest)) {
     warnings.push(`Skipped moving "${item.name}" into section "${label}" (target already exists).`);
     return null;
   }
@@ -12570,7 +13224,7 @@ var reshapeSection = async (section, docsDir, order, warnings) => {
     }
     return;
   }
-  const groupDir = join30(docsDir, `(${section.label})`);
+  const groupDir = join35(docsDir, `(${section.label})`);
   const sectionKeys = [];
   for (const item of section.items) {
     const key = await moveItemIntoGroup(item, docsDir, groupDir, section.label, warnings);
@@ -12583,7 +13237,7 @@ var reshapeSection = async (section, docsDir, order, warnings) => {
   }
   order.push(section.label);
   if (sectionKeys.length > 1) {
-    await writeFile10(join30(groupDir, "meta.ts"), renderMetaModule({ pages: sectionKeys }), "utf-8");
+    await writeFile11(join35(groupDir, "meta.ts"), renderMetaModule({ pages: sectionKeys }), "utf-8");
   }
 };
 var reshapeFumadocsGroups = async (structure, docsDir) => {
@@ -12615,9 +13269,9 @@ var FUMADOCS_LEFTOVERS = [
   "app"
 ];
 var movePage = async (abs, base, root) => {
-  const rel = relative16(base, abs);
-  const dest = join31(root, "docs", rel);
-  if (existsSync22(dest)) {
+  const rel = relative19(base, abs);
+  const dest = join36(root, "docs", rel);
+  if (existsSync24(dest)) {
     return {
       includeWarnings: [],
       moved: 0,
@@ -12626,8 +13280,11 @@ var movePage = async (abs, base, root) => {
       unsupported: []
     };
   }
-  const raw = await readFile17(abs, "utf-8");
-  const included = await inlineFumadocsIncludes(raw, { filePath: abs });
+  const raw = await readFile19(abs, "utf-8");
+  const included = await inlineFumadocsIncludes(raw, {
+    filePath: abs,
+    root: base
+  });
   let text = stripFumadocsImports(included.content);
   text = rewriteFumadocsCallouts(text);
   text = rewriteFumadocsContainers(text);
@@ -12637,7 +13294,7 @@ var movePage = async (abs, base, root) => {
   const { data, removed } = normalizeFumadocsPageMeta(parsed.data);
   const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
   await mkdir8(dirname16(dest), { recursive: true });
-  await writeFile11(dest, content, "utf-8");
+  await writeFile12(dest, content, "utf-8");
   await rm3(abs, { force: true });
   return {
     includeWarnings: included.warnings,
@@ -12651,22 +13308,22 @@ var writeMeta = async (dest, meta, rel, warnings) => {
   if (Object.keys(meta).length === 0) {
     return warnings;
   }
-  if (existsSync22(dest)) {
+  if (existsSync24(dest)) {
     return [...warnings, `Skipped ${rel} (target already exists)`];
   }
   await mkdir8(dirname16(dest), { recursive: true });
-  await writeFile11(dest, renderMetaModule(meta), "utf-8");
+  await writeFile12(dest, renderMetaModule(meta), "utf-8");
   return warnings;
 };
 var convertMeta = async (abs, base, root) => {
-  const rel = relative16(base, abs);
-  const raw = await readFile17(abs, "utf-8");
+  const rel = relative19(base, abs);
+  const raw = await readFile19(abs, "utf-8");
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch {
-    const dest2 = join31(root, "docs", rel);
-    if (existsSync22(dest2)) {
+    const dest2 = join36(root, "docs", rel);
+    if (existsSync24(dest2)) {
       return [`Skipped ${rel} (target already exists)`];
     }
     await mkdir8(dirname16(dest2), { recursive: true });
@@ -12676,10 +13333,10 @@ var convertMeta = async (abs, base, root) => {
     ];
   }
   const dir = dirname16(rel) === "." ? "" : dirname16(rel);
-  const docsDir = join31(root, "docs", dir);
-  const dest = join31(docsDir, "meta.ts");
+  const docsDir = join36(root, "docs", dir);
+  const dest = join36(docsDir, "meta.ts");
   const structure = parseFumadocsPages(parsed.pages);
-  if (structure.hasSections && !existsSync22(dest)) {
+  if (structure.hasSections && !existsSync24(dest)) {
     const self = translateFumadocsSelfMeta(parsed);
     const reshape = await reshapeFumadocsGroups(structure, docsDir);
     const meta2 = { ...self.meta };
@@ -12726,8 +13383,8 @@ var summarizePages = (results) => {
   };
 };
 var cleanupSourceDirs = async (root) => {
-  const docs = join31(root, "content", "docs");
-  if (existsSync22(docs)) {
+  const docs = join36(root, "content", "docs");
+  if (existsSync24(docs)) {
     const remaining = await glob8(["**/*"], { cwd: docs, dot: true });
     if (remaining.length > 0) {
       return [
@@ -12736,8 +13393,8 @@ var cleanupSourceDirs = async (root) => {
     }
     await rm3(docs, { force: true, recursive: true });
   }
-  const content = join31(root, "content");
-  if (existsSync22(content)) {
+  const content = join36(root, "content");
+  if (existsSync24(content)) {
     const remaining = await glob8(["**/*"], { cwd: content, dot: true });
     if (remaining.length === 0) {
       await rm3(content, { force: true, recursive: true });
@@ -12747,8 +13404,8 @@ var cleanupSourceDirs = async (root) => {
 };
 var migrateFumadocsProject = async (root) => {
   const { config, warnings: configWarnings } = await loadFumadocsConfig(root);
-  const base = join31(root, SOURCE_DIR);
-  if (!existsSync22(base)) {
+  const base = join36(root, SOURCE_DIR);
+  if (!existsSync24(base)) {
     await writeBlumeConfig(root, config);
     return {
       moved: 0,
@@ -12806,10 +13463,33 @@ var migrateFumadocsProject = async (root) => {
 };
 
 // src/migrate/mintlify/index.ts
-import { existsSync as existsSync23 } from "node:fs";
-import { mkdir as mkdir9, readFile as readFile18, rename as rename4, rm as rm4, writeFile as writeFile12 } from "node:fs/promises";
-import { dirname as dirname17, join as join32 } from "pathe";
+import { existsSync as existsSync25 } from "node:fs";
+import { mkdir as mkdir9, readFile as readFile20, rename as rename4, rm as rm4, stat as stat2, writeFile as writeFile13 } from "node:fs/promises";
+import { dirname as dirname17, join as join37 } from "pathe";
 import { glob as glob9 } from "tinyglobby";
+var asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+var hasFontFamily = (value) => {
+  const object = asRecord(value);
+  if (!object) {
+    return false;
+  }
+  const named = (child) => typeof asRecord(child)?.family === "string";
+  return typeof object.family === "string" || named(object.heading) || named(object.body);
+};
+var droppedChromeWarnings = (spec, config) => {
+  const warnings = [];
+  const navbar = asRecord(spec.navbar);
+  if (navbar && (navbar.links || navbar.primary)) {
+    warnings.push("Header links (navbar.links/navbar.primary) have no blume.config equivalent and were dropped; re-add them with navigation.tabs or a Header layout override.");
+  }
+  if (asRecord(spec.footer)?.socials) {
+    warnings.push("Footer social links (footer.socials) have no blume.config equivalent and were dropped; add them with a Footer layout override.");
+  }
+  if (hasFontFamily(spec.fonts ?? spec.font) && !config.theme?.fonts) {
+    warnings.push("docs.json font family isn't in Blume's curated Google Fonts set; set theme.fonts to a supported slug or add @font-face rules in theme.css.");
+  }
+  return warnings;
+};
 var prune = (value) => {
   if (Array.isArray(value)) {
     return value.map(prune);
@@ -12838,38 +13518,48 @@ var writeBlumeConfig2 = async (root, config) => {
 
 export default defineConfig(${JSON.stringify(prune(config), null, 2)});
 `;
-  await writeFile12(join32(root, "blume.config.ts"), body, "utf-8");
+  await writeFile13(join37(root, "blume.config.ts"), body, "utf-8");
 };
-var relocateAssets = async (root, refs) => {
-  const segments = new Set;
-  for (const ref of refs) {
-    if (typeof ref !== "string" || !ref.startsWith("/")) {
-      continue;
-    }
-    const [segment] = ref.replace(/^\/+/u, "").split("/");
-    if (segment) {
-      segments.add(segment);
-    }
-  }
+var relocateAssets = async (root, segments) => {
+  const served = [];
   const moved = [];
   for (const segment of segments) {
-    const source = join32(root, segment);
-    if (!existsSync23(source) || segment === "public") {
+    const source = join37(root, segment);
+    if (!existsSync25(source) || segment === "public") {
       continue;
     }
-    const dest = join32(root, "public", segment);
-    if (existsSync23(dest)) {
+    const stats = await stat2(source);
+    if (stats.isDirectory()) {
+      served.push(segment);
       continue;
     }
-    await mkdir9(join32(root, "public"), { recursive: true });
+    const dest = join37(root, "public", segment);
+    if (existsSync25(dest)) {
+      continue;
+    }
+    await mkdir9(join37(root, "public"), { recursive: true });
     await rename4(source, dest);
     moved.push(segment);
   }
-  return moved;
+  return { moved, served };
+};
+var applyRelocatedAssets = (config, assets, warnings) => {
+  if (assets.served.length > 0) {
+    config.content = {
+      ...config.content,
+      assets: [
+        ...new Set([...config.content?.assets ?? [], ...assets.served])
+      ]
+    };
+    warnings.push(`Kept asset dir(s) in place, served via content.assets: ${assets.served.join(", ")}.`);
+  }
+  if (assets.moved.length > 0) {
+    warnings.push(`Moved assets into public/: ${assets.moved.join(", ")}.`);
+  }
 };
 var cleanupSnippets = async (root, kept, warnings) => {
-  const dir = join32(root, "snippets");
-  if (!existsSync23(dir)) {
+  const dir = join37(root, "snippets");
+  if (!existsSync25(dir)) {
     return;
   }
   const markdown = await glob9(["**/*.{md,mdx}"], { absolute: true, cwd: dir });
@@ -12887,30 +13577,13 @@ var cleanupSnippets = async (root, kept, warnings) => {
     warnings.push(`Rewrote ${kept.size} component snippet import(s) to relative paths; verify they resolve.`);
   }
 };
-var assetRefs = (config) => {
-  const refs = ["/images"];
-  const logo = config.logo;
-  if (typeof logo === "string") {
-    refs.push(logo);
-  } else if (logo) {
-    refs.push(logo.light, logo.dark);
-  }
-  const favicon = config.favicon;
-  if (typeof favicon === "string") {
-    refs.push(favicon);
-  } else if (favicon) {
-    refs.push(favicon.light, favicon.dark);
-  }
-  refs.push(config.theme?.backgroundImage, config.theme?.backgroundImageDark);
-  return refs;
-};
 var migrateMintlifyProject = async (root) => {
   const warnings = [];
-  const configFile = existsSync23(join32(root, "docs.json")) ? join32(root, "docs.json") : join32(root, "mint.json");
+  const configFile = existsSync25(join37(root, "docs.json")) ? join37(root, "docs.json") : join37(root, "mint.json");
   let config;
-  if (existsSync23(configFile)) {
+  if (existsSync25(configFile)) {
     config = await loadMintlifyConfig(root, configFile);
-    const spec = JSON.parse(await readFile18(configFile, "utf-8"));
+    const spec = JSON.parse(await readFile20(configFile, "utf-8"));
     const i18n = mintlifyI18n(spec);
     if (i18n) {
       config.i18n = i18n;
@@ -12919,6 +13592,11 @@ var migrateMintlifyProject = async (root) => {
       }
       warnings.push(`Mapped ${i18n.locales.length} languages to i18n.locales (default: ${i18n.defaultLocale}); review the locale labels.`);
     }
+    const openapiSources = config.openapi?.sources ?? [];
+    if (openapiSources.length > 0) {
+      warnings.push(`Mapped ${openapiSources.length} OpenAPI spec source(s) to openapi.sources (native reference renderer); verify each spec path or URL resolves.`);
+    }
+    warnings.push(...droppedChromeWarnings(spec, config));
   } else {
     warnings.push("No docs.json or mint.json found; writing a default config.");
     config = { content: { root: "." }, title: "Documentation" };
@@ -12941,7 +13619,7 @@ var migrateMintlifyProject = async (root) => {
   const unsupported = new Set;
   const keptComponents = new Set;
   for (const file of files) {
-    const raw = await readFile18(file, "utf-8");
+    const raw = await readFile20(file, "utf-8");
     const result = await transformMintlifyContent(raw, {
       filePath: file,
       root,
@@ -12949,7 +13627,7 @@ var migrateMintlifyProject = async (root) => {
     });
     if (result.content !== raw) {
       await mkdir9(dirname17(file), { recursive: true });
-      await writeFile12(file, result.content, "utf-8");
+      await writeFile13(file, result.content, "utf-8");
     }
     for (const key of result.removed) {
       removedKeys.add(key);
@@ -12962,32 +13640,30 @@ var migrateMintlifyProject = async (root) => {
     }
     moved += 1;
   }
-  const movedAssets = await relocateAssets(root, assetRefs(config));
+  const assets = await relocateAssets(root, assetSegments(config));
   await cleanupSnippets(root, keptComponents, warnings);
   if (config.content?.exclude) {
     config.content.exclude = [...new Set(config.content.exclude)];
   }
+  applyRelocatedAssets(config, assets, warnings);
   await writeBlumeConfig2(root, config);
   if (Object.keys(variables).length > 0) {
     warnings.push(`Inlined ${Object.keys(variables).length} docs.json variable(s) into content; Blume has no runtime variable substitution.`);
   }
-  if (movedAssets.length > 0) {
-    warnings.push(`Moved assets into public/: ${movedAssets.join(", ")}.`);
-  }
   if (removedKeys.size > 0) {
     warnings.push(`Dropped unsupported page frontmatter keys: ${[...removedKeys].join(", ")}.`);
   }
   if (unsupported.size > 0) {
-    warnings.push(`Components without a Blume equivalent need manual review (use the OpenAPI reference instead): ${[...unsupported].join(", ")}.`);
+    warnings.push(`Components without a Blume equivalent need manual review: ${[...unsupported].join(", ")}.`);
   }
   warnings.push("Review blume.config.ts; navigation, theme, and chrome were mapped from docs.json.");
   return { moved, warnings };
 };
 
 // src/migrate/nextra/index.ts
-import { existsSync as existsSync24 } from "node:fs";
-import { mkdir as mkdir10, readFile as readFile19, rename as rename5, rm as rm5, writeFile as writeFile13 } from "node:fs/promises";
-import { basename as basename7, dirname as dirname18, extname as extname7, join as join33, relative as relative17 } from "pathe";
+import { existsSync as existsSync26 } from "node:fs";
+import { mkdir as mkdir10, readFile as readFile21, rename as rename5, rm as rm5, writeFile as writeFile14 } from "node:fs/promises";
+import { basename as basename7, dirname as dirname18, extname as extname8, join as join38, relative as relative20 } from "pathe";
 import { glob as glob10 } from "tinyglobby";
 
 // src/migrate/nextra/content.ts
@@ -13222,7 +13898,7 @@ var indexFolders = (base, pageFiles, metaFiles) => {
     }
   };
   for (const abs of pageFiles) {
-    const rel = relative17(base, abs);
+    const rel = relative20(base, abs);
     const dir = normalizeDir(dirname18(rel));
     const slug = basename7(rel).replace(/\.mdx?$/u, "");
     const folder = pagesByDir.get(dir) ?? new Map;
@@ -13231,7 +13907,7 @@ var indexFolders = (base, pageFiles, metaFiles) => {
     registerDir(dir);
   }
   for (const abs of metaFiles) {
-    registerDir(normalizeDir(dirname18(relative17(base, abs))));
+    registerDir(normalizeDir(dirname18(relative20(base, abs))));
   }
   const childDirs = new Map;
   for (const dir of allDirs) {
@@ -13269,7 +13945,7 @@ var planMetas = (metas, index) => {
     plan.metaByDir.set(dir, conversion.folderMeta);
     plan.consumedMetas.push(meta.abs);
     for (const [slug, title] of Object.entries(conversion.folderTitles)) {
-      plan.folderTitleByDir.set(normalizeDir(join33(dir, slug)), title);
+      plan.folderTitleByDir.set(normalizeDir(join38(dir, slug)), title);
     }
     for (const [slug, label] of Object.entries(conversion.pageLabels)) {
       const pageAbs = index.pagesByDir.get(dir)?.get(slug);
@@ -13293,19 +13969,19 @@ var planMetas = (metas, index) => {
   return plan;
 };
 var movePage2 = async (abs, options) => {
-  const rel = relative17(options.base, abs);
-  const dest = join33(options.root, "docs", rel);
-  if (existsSync24(dest)) {
+  const rel = relative20(options.base, abs);
+  const dest = join38(options.root, "docs", rel);
+  if (existsSync26(dest)) {
     return { moved: 0, removed: [], skipped: rel, unsupported: [] };
   }
-  const raw = await readFile19(abs, "utf-8");
+  const raw = await readFile21(abs, "utf-8");
   const text = rewriteNextraCallouts(stripNextraImports(raw));
   const unsupported = unsupportedNextraComponents(text);
   const parsed = frontmatter_default(text);
   const { data, removed } = normalizeNextraPageMeta(parsed.data, options.overrides.get(abs) ?? {});
   const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
   await mkdir10(dirname18(dest), { recursive: true });
-  await writeFile13(dest, content, "utf-8");
+  await writeFile14(dest, content, "utf-8");
   await rm5(abs, { force: true });
   return { moved: 1, removed, skipped: null, unsupported };
 };
@@ -13347,9 +14023,9 @@ var writeFolderMetas = async (root, plan) => {
     if (Object.keys(finalMeta).length === 0) {
       return;
     }
-    const dest = join33(root, "docs", dir, "meta.ts");
+    const dest = join38(root, "docs", dir, "meta.ts");
     await mkdir10(dirname18(dest), { recursive: true });
-    await writeFile13(dest, `import { defineMeta } from "blume";
+    await writeFile14(dest, `import { defineMeta } from "blume";
 
 export default defineMeta(${JSON.stringify(finalMeta, null, 2)});
 `, "utf-8");
@@ -13358,8 +14034,8 @@ export default defineMeta(${JSON.stringify(finalMeta, null, 2)});
 var relocateUnparseableMetas = async (root, metas) => {
   const warnings = [];
   await Promise.all(metas.map(async ({ abs, rel }) => {
-    const dest = join33(root, "docs", rel);
-    if (existsSync24(dest)) {
+    const dest = join38(root, "docs", rel);
+    if (existsSync26(dest)) {
       warnings.push(`Skipped ${rel} (target already exists)`);
       return;
     }
@@ -13371,7 +14047,7 @@ var relocateUnparseableMetas = async (root, metas) => {
 };
 var buildConfig = (tabs) => tabs.length > 0 ? { navigation: { tabs }, title: "Documentation" } : { title: "Documentation" };
 var migrateNextraProject = async (root) => {
-  const sourceDir = SOURCE_DIRS.find((dir) => existsSync24(join33(root, dir)));
+  const sourceDir = SOURCE_DIRS.find((dir) => existsSync26(join38(root, dir)));
   if (!sourceDir) {
     await writeBlumeConfig(root, { title: "Documentation" });
     return {
@@ -13381,7 +14057,7 @@ var migrateNextraProject = async (root) => {
       ]
     };
   }
-  const base = join33(root, sourceDir);
+  const base = join38(root, sourceDir);
   const pageFiles = await glob10([PAGE_GLOB2], {
     absolute: true,
     cwd: base,
@@ -13395,9 +14071,9 @@ var migrateNextraProject = async (root) => {
   const index = indexFolders(base, pageFiles, metaFiles);
   const metas = await Promise.all(metaFiles.map(async (abs) => ({
     abs,
-    ext: extname7(abs),
-    raw: await readFile19(abs, "utf-8"),
-    rel: relative17(base, abs)
+    ext: extname8(abs),
+    raw: await readFile21(abs, "utf-8"),
+    rel: relative20(base, abs)
   })));
   const plan = planMetas(metas, index);
   const moves = await Promise.all(pageFiles.map((abs) => movePage2(abs, { base, overrides: plan.pageOverrides, root })));
@@ -13422,15 +14098,15 @@ var migrateNextraProject = async (root) => {
 };
 
 // src/migrate/starlight/index.ts
-import { existsSync as existsSync26 } from "node:fs";
-import { readFile as readFile21, writeFile as writeFile14 } from "node:fs/promises";
-import { join as join35 } from "pathe";
+import { existsSync as existsSync28 } from "node:fs";
+import { readFile as readFile23, writeFile as writeFile15 } from "node:fs/promises";
+import { join as join40 } from "pathe";
 import { glob as glob11 } from "tinyglobby";
 
 // src/migrate/starlight/config.ts
-import { existsSync as existsSync25 } from "node:fs";
-import { readFile as readFile20 } from "node:fs/promises";
-import { join as join34 } from "pathe";
+import { existsSync as existsSync27 } from "node:fs";
+import { readFile as readFile22 } from "node:fs/promises";
+import { join as join39 } from "pathe";
 var CONFIG_FILES = [
   "astro.config.mjs",
   "astro.config.mts",
@@ -13461,7 +14137,7 @@ var extractStarlightOptions = (source) => {
   return isLiteralObject(parsed) ? parsed : "unparseable";
 };
 var loadStarlightConfig = async (root) => {
-  const file = CONFIG_FILES.map((name) => join34(root, name)).find((path) => existsSync25(path));
+  const file = CONFIG_FILES.map((name) => join39(root, name)).find((path) => existsSync27(path));
   if (!file) {
     return {
       options: {},
@@ -13470,7 +14146,7 @@ var loadStarlightConfig = async (root) => {
       ]
     };
   }
-  const source = await readFile20(file, "utf-8");
+  const source = await readFile22(file, "utf-8");
   const result = extractStarlightOptions(source);
   if (result === "missing") {
     return {
@@ -13868,7 +14544,7 @@ var starlightI18n = (options) => {
 // src/migrate/starlight/index.ts
 var CONTENT_DIR = "src/content/docs";
 var transformPage = async (file) => {
-  const raw = await readFile21(file, "utf-8");
+  const raw = await readFile23(file, "utf-8");
   let text = stripStarlightImports(raw);
   text = rewriteStarlightAsides(text);
   text = rewriteStarlightComponents(text);
@@ -13878,7 +14554,7 @@ var transformPage = async (file) => {
   const { data, removed } = normalizeStarlightPageMeta(parsed.data);
   const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
   if (content !== raw) {
-    await writeFile14(file, content, "utf-8");
+    await writeFile15(file, content, "utf-8");
   }
   return { aliased, removed, unsupported };
 };
@@ -13890,8 +14566,8 @@ var migrateStarlightProject = async (root) => {
     config.i18n = i18n;
     warnings.push(`Mapped ${i18n.locales.length} locale(s) to i18n (default: ${i18n.defaultLocale}); review the locale labels.`);
   }
-  const base = join35(root, CONTENT_DIR);
-  if (!existsSync26(base)) {
+  const base = join40(root, CONTENT_DIR);
+  if (!existsSync28(base)) {
     await writeBlumeConfig(root, config);
     return {
       moved: 0,
@@ -13979,10 +14655,10 @@ var migrateCommand = defineCommand8({
 });
 
 // src/cli/commands/preview.ts
-import { existsSync as existsSync27 } from "node:fs";
+import { existsSync as existsSync29 } from "node:fs";
 import { preview } from "astro";
 import { defineCommand as defineCommand9 } from "citty";
-import { join as join36 } from "pathe";
+import { join as join41 } from "pathe";
 var previewCommand = defineCommand9({
   args: {
     host: { description: "Network host to bind.", type: "string" },
@@ -13996,7 +14672,7 @@ var previewCommand = defineCommand9({
     const root = process.cwd();
     const { config } = await loadConfig(root);
     const context = resolveProjectContext(root, config);
-    if (!existsSync27(join36(context.outDir, "astro.config.mjs"))) {
+    if (!existsSync29(join41(context.outDir, "astro.config.mjs"))) {
       logger.error("No build found. Run `blume build` first.");
       process.exit(1);
     }
@@ -14005,7 +14681,7 @@ var previewCommand = defineCommand9({
       root: context.outDir,
       server: {
         host: args.host ?? false,
-        port: args.port ? Number(args.port) : undefined
+        port: parsePort(args.port)
       }
     });
   }
@@ -14014,7 +14690,7 @@ var previewCommand = defineCommand9({
 // src/cli/commands/sync.ts
 import { rm as rm6 } from "node:fs/promises";
 import { defineCommand as defineCommand10 } from "citty";
-import { join as join37 } from "pathe";
+import { join as join42 } from "pathe";
 var syncCommand = defineCommand10({
   args: {
     force: {
@@ -14036,7 +14712,7 @@ var syncCommand = defineCommand10({
     if (args.force) {
       const { config } = await loadConfig(root);
       const context = resolveProjectContext(root, config);
-      await rm6(join37(context.outDir, "cache"), { force: true, recursive: true });
+      await rm6(join42(context.outDir, "cache"), { force: true, recursive: true });
       logger.info("Cleared source cache.");
     }
     await prepareProject({
@@ -14051,13 +14727,13 @@ var syncCommand = defineCommand10({
 });
 
 // src/cli/commands/validate.ts
-import { existsSync as existsSync29 } from "node:fs";
+import { existsSync as existsSync31 } from "node:fs";
 import { defineCommand as defineCommand11 } from "citty";
-import { join as join39 } from "pathe";
+import { join as join44 } from "pathe";
 
 // src/core/links.ts
-import { existsSync as existsSync28 } from "node:fs";
-import { join as join38 } from "pathe";
+import { existsSync as existsSync30 } from "node:fs";
+import { basename as basename8, join as join43 } from "pathe";
 var HTTP = /^https?:\/\//iu;
 var PROTOCOL_RELATIVE = /^\/\//u;
 var SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
@@ -14069,9 +14745,21 @@ var STATUS_NOT_FOUND = 404;
 var STATUS_GONE = 410;
 var STATUS_METHOD_NOT_ALLOWED = 405;
 var STATUS_NOT_IMPLEMENTED = 501;
-var resolveRelative = (pageRoute, target) => {
+var assetIsPresent = (resolved, ctx) => {
+  if (ctx.publicDir && existsSync30(join43(ctx.publicDir, resolved))) {
+    return true;
+  }
+  return ctx.assetMounts.some((mount) => (resolved === mount.url || resolved.startsWith(`${mount.url}/`)) && existsSync30(join43(mount.dir, resolved.slice(mount.url.length))));
+};
+var isIndexPage = (page2) => {
+  const ref = page2.source?.ref ?? page2.sourcePath ?? "";
+  return /^index\.(?:md|mdx)$/iu.test(basename8(ref));
+};
+var resolveRelative = (pageRoute, target, isIndex) => {
   const segments = pageRoute.split("/").filter(Boolean);
-  segments.pop();
+  if (!isIndex) {
+    segments.pop();
+  }
   for (const part of target.split("/")) {
     if (part === "" || part === ".") {
       continue;
@@ -14113,13 +14801,20 @@ var checkAnchor = (route, fragment, site, ctx) => {
   };
 };
 var checkPathLink = (resolved, fragment, target, site, ctx) => {
+  const route = toRoute(resolved);
+  if (ctx.routes.has(route)) {
+    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
+  }
+  if (ctx.redirects.has(route)) {
+    return null;
+  }
   if (FILE_EXT.test(resolved) && !DOC_EXT.test(resolved)) {
-    if (ctx.publicDir === null) {
-      return "asset-unchecked";
-    }
-    if (existsSync28(join38(ctx.publicDir, resolved))) {
+    if (assetIsPresent(resolved, ctx)) {
       return null;
     }
+    if (ctx.publicDir === null && ctx.assetMounts.length === 0) {
+      return "asset-unchecked";
+    }
     return {
       ...site,
       code: "BLUME_BROKEN_ASSET",
@@ -14128,13 +14823,6 @@ var checkPathLink = (resolved, fragment, target, site, ctx) => {
       suggestion: `Add the file at public${resolved} or fix the link.`
     };
   }
-  const route = toRoute(resolved);
-  if (ctx.routes.has(route)) {
-    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
-  }
-  if (ctx.redirects.has(route)) {
-    return null;
-  }
   return {
     ...site,
     code: "BLUME_BROKEN_LINK",
@@ -14243,12 +14931,13 @@ var classifyLink = (page2, link, ctx, onExternal) => {
   if (rawPath === "") {
     return fragment ? checkAnchor(page2.route, fragment, site, ctx) : null;
   }
-  const resolved = rawPath.startsWith("/") ? rawPath : resolveRelative(page2.route, rawPath);
+  const resolved = rawPath.startsWith("/") ? rawPath : resolveRelative(page2.route, rawPath, isIndexPage(page2));
   return checkPathLink(resolved, fragment, target, site, ctx);
 };
 var validateLinks = async (graph, options) => {
   const ctx = {
     anchors: buildAnchorIndex(graph.pages),
+    assetMounts: options.assetMounts ?? [],
     publicDir: options.publicDir,
     redirects: new Set((options.redirects ?? []).map((redirect) => toRoute(redirect.from))),
     routes: new Set(graph.routes.keys())
@@ -14305,10 +14994,11 @@ var validateCommand = defineCommand11({
     try {
       const project = await scanProject(root, { mode: "build" });
       diagnostics.push(...project.diagnostics);
-      const publicDir = join39(root, "public");
+      const publicDir = join44(root, "public");
       diagnostics.push(...await validateLinks(project.graph, {
+        assetMounts: resolveAssetMounts(root, project.config.content.assets),
         checkExternal: Boolean(args.external),
-        publicDir: existsSync29(publicDir) ? publicDir : null,
+        publicDir: existsSync31(publicDir) ? publicDir : null,
         redirects: project.config.redirects
       }));
     } catch (error) {
@@ -14322,6 +15012,7 @@ var validateCommand = defineCommand11({
     if (args.json) {
       const hadErrors2 = reportDiagnosticsJson(diagnostics, root);
       if (hadErrors2 || Boolean(args.strict) && diagnostics.length > 0) {
+        await flushStdout();
         process.exit(1);
       }
       return;
@@ -14368,5 +15059,5 @@ process.on("unhandledRejection", (error) => {
 });
 runMain(main);
 
-//# debugId=8EA79E97DE44177D64756E2164756E21
+//# debugId=432F59E1AFBFB0A064756E2164756E21
 //# sourceMappingURL=index.js.map