blume 0.2.0 → 0.3.0

package/dist/cli/index.js

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/cli/index.ts
-import { defineCommand as defineCommand11, runMain } from "citty";
+import { defineCommand as defineCommand12, runMain } from "citty";
 
 // src/core/version.ts
 import { readFileSync } from "node:fs";
@@ -72,6 +72,145 @@ var layoutComponent = (config) => {
     ]
   };
 };
+var contentComponent = (config) => {
+  const target = `components/blume/${config.file}`;
+  return {
+    description: config.description,
+    files: [
+      {
+        rewrite: true,
+        source: `components/content/${config.file}`,
+        target
+      }
+    ],
+    name: config.name,
+    postInstall: [
+      "Register it in components.ts:",
+      '  import { defineComponents } from "blume";',
+      `  import ${config.tag} from "./${target}";`,
+      "",
+      `  export default defineComponents({ mdx: { ${config.tag} } });`,
+      "",
+      "It imports the rest from `blume/*`, so it matches the built-in until you edit it."
+    ]
+  };
+};
+var CONTENT_COMPONENTS = [
+  {
+    description: "Aside for notes, tips, and warnings.",
+    file: "Callout.astro",
+    name: "callout",
+    tag: "Callout"
+  },
+  {
+    description: "A linkable card with icon, title, and body.",
+    file: "Card.astro",
+    name: "card",
+    tag: "Card"
+  },
+  {
+    description: "A responsive grid of cards.",
+    file: "CardGroup.astro",
+    name: "card-group",
+    tag: "CardGroup"
+  },
+  {
+    description: "Tabbed code blocks for multiple languages.",
+    file: "CodeGroup.astro",
+    name: "code-group",
+    tag: "CodeGroup"
+  },
+  {
+    description: "A small status/label badge.",
+    file: "Badge.astro",
+    name: "badge",
+    tag: "Badge"
+  },
+  {
+    description: "A numbered list of steps.",
+    file: "Steps.astro",
+    name: "steps",
+    tag: "Steps"
+  },
+  {
+    description: "A single step within Steps.",
+    file: "Step.astro",
+    name: "step",
+    tag: "Step"
+  },
+  {
+    description: "A tabbed content panel.",
+    file: "Tabs.astro",
+    name: "tabs",
+    tag: "Tabs"
+  },
+  {
+    description: "A single tab within Tabs.",
+    file: "Tab.astro",
+    name: "tab",
+    tag: "Tab"
+  },
+  {
+    description: "A collapsible accordion group.",
+    file: "Accordion.astro",
+    name: "accordion",
+    tag: "Accordion"
+  },
+  {
+    description: "A single item within an Accordion.",
+    file: "AccordionItem.astro",
+    name: "accordion-item",
+    tag: "AccordionItem"
+  },
+  {
+    description: "A multi-column layout.",
+    file: "Columns.astro",
+    name: "columns",
+    tag: "Columns"
+  },
+  {
+    description: "A single column within Columns.",
+    file: "Column.astro",
+    name: "column",
+    tag: "Column"
+  },
+  {
+    description: "A bordered frame around an image or embed.",
+    file: "Frame.astro",
+    name: "frame",
+    tag: "Frame"
+  },
+  {
+    description: "An inline expand/collapse disclosure.",
+    file: "Expandable.astro",
+    name: "expandable",
+    tag: "Expandable"
+  },
+  {
+    description: "A titled content panel.",
+    file: "Panel.astro",
+    name: "panel",
+    tag: "Panel"
+  },
+  {
+    description: "A hover tooltip.",
+    file: "Tooltip.astro",
+    name: "tooltip",
+    tag: "Tooltip"
+  },
+  {
+    description: "A compact linkable tile.",
+    file: "Tile.astro",
+    name: "tile",
+    tag: "Tile"
+  },
+  {
+    description: "A styled prompt / terminal block.",
+    file: "Prompt.astro",
+    name: "prompt",
+    tag: "Prompt"
+  }
+];
 var registry = [
   layoutComponent({
     description: "The top navigation bar (logo, search, nav links).",
@@ -102,7 +241,14 @@ var registry = [
     file: "Pagination.astro",
     name: "pagination",
     slot: "Pagination"
-  })
+  }),
+  layoutComponent({
+    description: 'The "Was this page helpful?" feedback rating.',
+    file: "PageFeedback.astro",
+    name: "feedback",
+    slot: "Feedback"
+  }),
+  ...CONTENT_COMPONENTS.map(contentComponent)
 ];
 var findItem = (name) => registry.find((item) => item.name === name);
 
@@ -123,6 +269,7 @@ var rewriteImports = (content, sourceFile, srcRoot) => content.replaceAll(RELATI
 
 // src/cli/log.ts
 import { consola } from "consola";
+import { relative as relative3 } from "pathe";
 
 // src/core/diagnostics.ts
 import { relative as relative2 } from "pathe";
@@ -135,12 +282,77 @@ class BlumeError extends Error {
     this.diagnostic = diagnostic;
   }
 }
+var DOCS_BASE = "https://useblume.dev";
+var DOCS_PATHS = {
+  BLUME_ADAPTER_REQUIRED: "/docs/deployment",
+  BLUME_ASSETS_UNCHECKED: "/docs/reference/cli",
+  BLUME_ASSET_FETCH_FAILED: "/docs/content/sources",
+  BLUME_BROKEN_ANCHOR: "/docs/reference/cli",
+  BLUME_BROKEN_ASSET: "/docs/reference/cli",
+  BLUME_BROKEN_LINK: "/docs/reference/cli",
+  BLUME_CONFIG_INVALID: "/docs/configuration",
+  BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
+  BLUME_CONTENT_ROOT_MISSING: "/docs/content/sources",
+  BLUME_DEAD_LINK: "/docs/reference/cli",
+  BLUME_DUPLICATE_ROUTE: "/docs/content/navigation",
+  BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
+  BLUME_META_INVALID: "/docs/content/meta",
+  BLUME_META_LOAD_FAILED: "/docs/content/meta",
+  BLUME_MISSING_SECRET: "/docs/deployment",
+  BLUME_NAV_DUPLICATE_LABEL: "/docs/content/navigation",
+  BLUME_NAV_HIDDEN_IN_SIDEBAR: "/docs/content/navigation",
+  BLUME_NAV_MISSING_PAGE: "/docs/content/navigation",
+  BLUME_NODE_VERSION: "/docs/quickstart",
+  BLUME_SERVER_FEATURE_REQUIRED: "/docs/deployment",
+  BLUME_SOURCE_FETCH_FAILED: "/docs/content/sources",
+  BLUME_SOURCE_MISCONFIGURED: "/docs/content/sources",
+  BLUME_SOURCE_OFFLINE: "/docs/content/sources",
+  BLUME_SOURCE_SDK_MISSING: "/docs/content/sources",
+  BLUME_SOURCE_UNAVAILABLE: "/docs/content/sources",
+  BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
+  BLUME_UNKNOWN_ICON: "/docs/content/navigation"
+};
+var resolveDocsUrl = (code) => {
+  const path = DOCS_PATHS[code];
+  return path ? `${DOCS_BASE}${path}` : undefined;
+};
+var enrichDiagnostic = (diagnostic) => diagnostic.docsUrl ? diagnostic : { ...diagnostic, docsUrl: resolveDocsUrl(diagnostic.code) };
+var REGEXP_SPECIAL = /[$()*+.?[\\\]^{|}]/gu;
+var escapeRegExp = (value) => value.replaceAll(REGEXP_SPECIAL, String.raw`\$&`);
+var locatePath = (source, path) => {
+  let cursor = 0;
+  let found = -1;
+  for (const segment of path) {
+    if (typeof segment !== "string") {
+      continue;
+    }
+    const matcher = new RegExp(`${escapeRegExp(segment)}\\s*[:=]`, "gu");
+    matcher.lastIndex = cursor;
+    const match = matcher.exec(source);
+    if (!match) {
+      break;
+    }
+    found = match.index;
+    cursor = matcher.lastIndex;
+  }
+  if (found < 0) {
+    return;
+  }
+  const before = source.slice(0, found);
+  const lastNewline = before.lastIndexOf(`
+`);
+  return { column: found - lastNewline, line: before.split(`
+`).length };
+};
 var diagnosticsFromZod = (error, options) => error.issues.map((issue) => {
   const schemaPath = issue.path.join(".");
   const received = "received" in issue ? ` (received: ${JSON.stringify(issue.received)})` : "";
+  const position = options.source ? locatePath(options.source, issue.path) : undefined;
   return {
     code: options.code,
+    column: position?.column,
     file: options.file,
+    line: position?.line,
     message: schemaPath ? `${schemaPath}: ${issue.message}${received}` : `${issue.message}${received}`,
     schemaPath: schemaPath || undefined,
     severity: "error"
@@ -196,12 +408,21 @@ var countBySeverity = (diagnostics) => {
 
 // src/cli/log.ts
 var logger = consola.withTag("blume");
+var reportDiagnosticsJson = (diagnostics, root) => {
+  const enriched = diagnostics.map((diagnostic) => {
+    const withDocs = enrichDiagnostic(diagnostic);
+    return withDocs.file && root ? { ...withDocs, file: relative3(root, withDocs.file) } : withDocs;
+  });
+  process.stdout.write(`${JSON.stringify({ diagnostics: enriched, summary: countBySeverity(diagnostics) }, null, 2)}
+`);
+  return hasErrors(diagnostics);
+};
 var reportDiagnostics = (diagnostics, root) => {
   if (diagnostics.length === 0) {
     return false;
   }
   for (const diagnostic of diagnostics) {
-    process.stderr.write(`${formatDiagnostic(diagnostic, root)}
+    process.stderr.write(`${formatDiagnostic(enrichDiagnostic(diagnostic), root)}
 `);
   }
   const counts = countBySeverity(diagnostics);
@@ -279,8 +500,8 @@ Next steps:
 });
 
 // src/cli/commands/build.ts
-import { existsSync as existsSync12 } from "node:fs";
-import { writeFile as writeFile6 } from "node:fs/promises";
+import { existsSync as existsSync15 } from "node:fs";
+import { readdir, stat, writeFile as writeFile6 } from "node:fs/promises";
 import { build } from "astro";
 import { defineCommand as defineCommand2 } from "citty";
 import { join as join24 } from "pathe";
@@ -443,6 +664,25 @@ var serverFeatures = (config) => {
   return features;
 };
 
+// src/deploy/redirects.ts
+var buildNetlifyRedirects = (redirects) => `${redirects.map((redirect) => `${redirect.from} ${redirect.to} ${redirect.status}`).join(`
+`)}
+`;
+var buildVercelConfig = (redirects) => `${JSON.stringify({
+  redirects: redirects.map((redirect) => ({
+    destination: redirect.to,
+    permanent: redirect.status === 301 || redirect.status === 308,
+    source: redirect.from
+  }))
+}, null, 2)}
+`;
+var buildRedirectManifest = (redirects) => `${JSON.stringify(redirects.map((redirect) => ({
+  from: redirect.from,
+  status: redirect.status,
+  to: redirect.to
+})), null, 2)}
+`;
+
 // src/deploy/robots.ts
 var buildRobots = (project) => {
   const { config } = project;
@@ -2514,7 +2754,7 @@ var syncSearchProvider = async (project, reporter) => {
 };
 
 // src/astro/generate.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5, realpathSync } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync5, realpathSync } from "node:fs";
 import {
   lstat,
   mkdir as mkdir2,
@@ -2526,9 +2766,26 @@ import {
 } from "node:fs/promises";
 import { createRequire as createRequire4 } from "node:module";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
-import { basename as basename2, dirname as dirname6, join as join11, normalize, relative as relative5 } from "pathe";
+import { basename as basename2, dirname as dirname7, join as join11, normalize, relative as relative6 } from "pathe";
 import { glob as glob4 } from "tinyglobby";
 
+// src/ai/ask-data.ts
+var buildAskData = async (project) => {
+  const documents = await buildSearchDocuments(project, {
+    includeWhenDisabled: true
+  });
+  return {
+    documents: documents.map((doc) => ({
+      content: doc.content,
+      description: doc.description,
+      locale: doc.locale,
+      route: doc.route,
+      title: doc.title
+    })),
+    site: project.config.deployment.site ?? null
+  };
+};
+
 // src/ai/ask.ts
 var ASK_PRESETS = {
   inkeep: {
@@ -2682,6 +2939,323 @@ var buildMcpServerCard = (input) => ({
   version: input.version
 });
 
+// src/core/builtin-tags.ts
+var BUILTIN_MDX_TAGS = new Set([
+  "Accordion",
+  "AccordionItem",
+  "AutoTypeTable",
+  "Badge",
+  "Callout",
+  "Card",
+  "CardGroup",
+  "CodeBlock",
+  "CodeGroup",
+  "Color",
+  "Column",
+  "Columns",
+  "Component",
+  "Diff",
+  "Expandable",
+  "FileTree",
+  "Frame",
+  "GithubInfo",
+  "Icon",
+  "Math",
+  "Panel",
+  "Prompt",
+  "Step",
+  "Steps",
+  "Tab",
+  "Tabs",
+  "Tile",
+  "Tooltip",
+  "Tree",
+  "TypeTable",
+  "Visibility"
+]);
+
+// src/core/component-diagnostics.ts
+var toKebab = (tag) => tag.replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>-$<upper>").toLowerCase();
+var validateUsedComponents = (pages, extraTags, registryNames) => {
+  const diagnostics = [];
+  const seen = new Set;
+  for (const page of pages) {
+    for (const tag of page.componentsUsed ?? []) {
+      if (BUILTIN_MDX_TAGS.has(tag) || extraTags.has(tag) || seen.has(tag)) {
+        continue;
+      }
+      seen.add(tag);
+      const name = toKebab(tag);
+      const suggestion = registryNames.has(name) ? `Run \`blume add ${name}\` to install it, or register <${tag}> in components.ts (mdx).` : `Register <${tag}> in components.ts (mdx), or add an islands/${tag}.tsx component.`;
+      diagnostics.push({
+        code: "BLUME_UNKNOWN_COMPONENT",
+        file: page.sourcePath ?? page.id,
+        message: `<${tag}> is used in ${page.route} but isn't a known component.`,
+        severity: "warning",
+        suggestion
+      });
+    }
+  }
+  return diagnostics;
+};
+
+// src/core/component-overrides.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { dirname as dirname4, extname, isAbsolute, resolve as resolve2 } from "pathe";
+import ts from "typescript";
+var GROUPS = ["mdx", "layout", "islands"];
+var FRAMEWORK_BY_EXT = {
+  jsx: "react",
+  svelte: "svelte",
+  tsx: "react",
+  vue: "vue"
+};
+var FRAMEWORK_LABEL = {
+  react: "React",
+  svelte: "Svelte",
+  vue: "Vue"
+};
+var COMPONENT_EXTS = [
+  "astro",
+  "tsx",
+  "ts",
+  "jsx",
+  "js",
+  "mjs",
+  "vue",
+  "svelte"
+];
+var HYDRATION_MODES = new Set([
+  "idle",
+  "load",
+  "media",
+  "only",
+  "visible"
+]);
+var emptyAnalysis = () => ({
+  islands: [],
+  layout: [],
+  mdx: [],
+  warnings: []
+});
+var propName = (name) => ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+var collectImports = (sourceFile) => {
+  const map = new Map;
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+      continue;
+    }
+    const specifier = statement.moduleSpecifier.text;
+    const clause = statement.importClause;
+    if (!clause) {
+      continue;
+    }
+    if (clause.name) {
+      map.set(clause.name.text, { imported: "default", specifier });
+    }
+    const named = clause.namedBindings;
+    if (named && ts.isNamedImports(named)) {
+      for (const element of named.elements) {
+        map.set(element.name.text, {
+          imported: (element.propertyName ?? element.name).text,
+          specifier
+        });
+      }
+    }
+  }
+  return map;
+};
+var unwrapObject = (expression) => {
+  if (ts.isObjectLiteralExpression(expression)) {
+    return expression;
+  }
+  if (ts.isCallExpression(expression)) {
+    const [arg] = expression.arguments;
+    return arg && ts.isObjectLiteralExpression(arg) ? arg : undefined;
+  }
+  if (ts.isAsExpression(expression) || ts.isParenthesizedExpression(expression)) {
+    return unwrapObject(expression.expression);
+  }
+  return;
+};
+var findDefaultExportObject = (sourceFile) => {
+  for (const statement of sourceFile.statements) {
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+      return unwrapObject(statement.expression);
+    }
+  }
+  return;
+};
+var probeExtension = (base) => {
+  for (const extension of COMPONENT_EXTS) {
+    const candidate = `${base}.${extension}`;
+    if (existsSync3(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+};
+var toImport = (specifier, imported, dir) => {
+  const relative4 = specifier.startsWith(".") || isAbsolute(specifier);
+  let path = specifier;
+  let extension = extname(specifier).slice(1).toLowerCase();
+  if (relative4) {
+    const absolute = isAbsolute(specifier) ? specifier : resolve2(dir, specifier);
+    if (extension) {
+      path = absolute;
+    } else {
+      const probed = probeExtension(absolute);
+      path = probed ?? absolute;
+      extension = probed ? extname(probed).slice(1).toLowerCase() : "";
+    }
+  }
+  return {
+    framework: FRAMEWORK_BY_EXT[extension] ?? null,
+    name: imported,
+    path
+  };
+};
+var resolveIdentifier = (name, imports, dir) => {
+  const binding = imports.get(name);
+  return binding ? toImport(binding.specifier, binding.imported, dir) : null;
+};
+var readDescriptor = (object, imports, dir) => {
+  const descriptor = { hadComponent: false, source: null };
+  for (const property of object.properties) {
+    if (ts.isShorthandPropertyAssignment(property)) {
+      if (property.name.text === "component") {
+        descriptor.hadComponent = true;
+        descriptor.source = resolveIdentifier(property.name.text, imports, dir);
+      }
+      continue;
+    }
+    if (!ts.isPropertyAssignment(property)) {
+      continue;
+    }
+    const name = propName(property.name);
+    const init = property.initializer;
+    if (name === "component") {
+      descriptor.hadComponent = true;
+      if (ts.isStringLiteral(init)) {
+        descriptor.source = toImport(init.text, "default", dir);
+      } else if (ts.isIdentifier(init)) {
+        descriptor.source = resolveIdentifier(init.text, imports, dir);
+      }
+    } else if (name === "client" && ts.isStringLiteral(init) && HYDRATION_MODES.has(init.text)) {
+      descriptor.client = init.text;
+    } else if (name === "media" && ts.isStringLiteral(init)) {
+      descriptor.media = init.text;
+    }
+  }
+  return descriptor;
+};
+var finalize = (key, group, descriptor, label, identifier, warnings) => {
+  const { client, media, source } = descriptor;
+  if (group === "islands") {
+    if (!source) {
+      warnings.push(`Island override "${key}" couldn't be resolved to a file. Reference it by an imported component or a path string with an extension.`);
+      return null;
+    }
+    if (!source.framework) {
+      warnings.push(`Island override "${key}" (${label}) is not a React, Vue, or Svelte component; only framework components can be islands.`);
+      return null;
+    }
+  }
+  if (client === "media" && !media) {
+    warnings.push(`Override "${key}" uses client: "media" but no \`media\` query was given; it will hydrate as if \`client: "load"\`.`);
+  }
+  if (client === "only" && source && !source.framework) {
+    warnings.push(`Override "${key}" uses client: "only" but its framework couldn't be inferred; reference a .tsx/.jsx/.vue/.svelte file.`);
+  }
+  if (client && !source) {
+    warnings.push(`Override "${key}" declares client: "${client}" but its component couldn't be resolved to a file, so it can't hydrate. Reference it by an imported component or a path string.`);
+    return { identifier, key, source: null };
+  }
+  if (!client && source?.framework) {
+    warnings.push(`Override "${key}" points to a ${FRAMEWORK_LABEL[source.framework]} component (${label}) but has no hydration mode, so it renders as static HTML with no interactivity. Add one, e.g. \`${key}: { component: ${JSON.stringify(label)}, client: "load" }\`.`);
+  }
+  return {
+    identifier,
+    key,
+    ...client ? { client } : {},
+    ...media ? { media } : {},
+    source
+  };
+};
+var normalizeEntry = (entry, group, imports, dir, warnings) => {
+  const defaultClient = group === "islands" ? "visible" : undefined;
+  if (ts.isShorthandPropertyAssignment(entry)) {
+    const name = entry.name.text;
+    return finalize(name, group, {
+      client: defaultClient,
+      hadComponent: true,
+      source: resolveIdentifier(name, imports, dir)
+    }, name, true, warnings);
+  }
+  if (!ts.isPropertyAssignment(entry)) {
+    return null;
+  }
+  const key = propName(entry.name);
+  if (!key) {
+    return null;
+  }
+  const value = entry.initializer;
+  if (ts.isIdentifier(value)) {
+    return finalize(key, group, {
+      client: defaultClient,
+      hadComponent: true,
+      source: resolveIdentifier(value.text, imports, dir)
+    }, value.text, true, warnings);
+  }
+  if (ts.isStringLiteral(value)) {
+    return finalize(key, group, {
+      client: defaultClient,
+      hadComponent: true,
+      source: toImport(value.text, "default", dir)
+    }, value.text, false, warnings);
+  }
+  if (ts.isObjectLiteralExpression(value)) {
+    const descriptor = readDescriptor(value, imports, dir);
+    if (!descriptor.hadComponent) {
+      warnings.push(`Override "${key}" is an object without a \`component\` field; expected \`{ component, client }\`.`);
+      return null;
+    }
+    if (!descriptor.source) {
+      warnings.push(`Override "${key}"'s \`component\` couldn't be resolved to a file. Reference an imported component or a path string with an extension.`);
+      return null;
+    }
+    return finalize(key, group, { ...descriptor, client: descriptor.client ?? defaultClient }, key, false, warnings);
+  }
+  return { identifier: false, key, source: null };
+};
+var analyzeComponentOverrides = (source, filePath) => {
+  const result = emptyAnalysis();
+  const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, filePath.endsWith("tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+  const object = findDefaultExportObject(sourceFile);
+  if (!object) {
+    return result;
+  }
+  const imports = collectImports(sourceFile);
+  const dir = dirname4(filePath);
+  for (const property of object.properties) {
+    if (!ts.isPropertyAssignment(property)) {
+      continue;
+    }
+    const name = propName(property.name);
+    if (!(name && GROUPS.includes(name)) || !ts.isObjectLiteralExpression(property.initializer)) {
+      continue;
+    }
+    const group = name;
+    for (const entry of property.initializer.properties) {
+      const normalized = normalizeEntry(entry, group, imports, dir, result.warnings);
+      if (normalized) {
+        result[group].push(normalized);
+      }
+    }
+  }
+  return result;
+};
+
 // src/core/i18n-ui.ts
 import { z } from "zod";
 var uiStringsObject = z.object({
@@ -2773,11 +3347,284 @@ var resolveUIStrings = (locale, options) => {
   return dict;
 };
 
+// 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;
+      }
+    }
+  }
+  return normalized;
+};
+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 };
+    }
+  }
+  return 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 push = (icon, where) => {
+    if (icon) {
+      icons2.push({ icon, where });
+    }
+  };
+  for (const tab of navigation.tabs) {
+    push(tab.icon, `tab "${tab.label}"`);
+    for (const item of tab.items ?? []) {
+      push(item.icon, `tab item "${item.label}"`);
+    }
+  }
+  for (const selector of navigation.selectors) {
+    for (const item of selector.items) {
+      push(item.icon, `selector "${item.label}"`);
+    }
+  }
+  const sidebars = [
+    navigation.sidebar,
+    ...navigation.sidebarVariants.map((variant) => variant.sidebar)
+  ];
+  for (const sidebar of sidebars) {
+    for (const node of flattenNodes(sidebar)) {
+      push(node.icon, `"${node.label}"`);
+    }
+  }
+  return icons2;
+};
+var validateNavIcons = (navigation) => {
+  const seen = new Set;
+  const diagnostics = [];
+  for (const { icon, where } of collectIcons(navigation)) {
+    if (isAssetIcon(icon) || hasIcon(icon) || seen.has(icon)) {
+      continue;
+    }
+    seen.add(icon);
+    diagnostics.push({
+      code: "BLUME_UNKNOWN_ICON",
+      message: `Unknown icon "${icon}" (${where}) — it isn't in Blume's icon set.`,
+      severity: "warning",
+      suggestion: "Use a built-in icon name, an image path/URL, or inline SVG markup."
+    });
+  }
+  return diagnostics;
+};
+var resolvesToPages = (routes, path) => routes.has(path) || [...routes].some((route) => route.startsWith(`${path}/`));
+var validateNavTargets = (navigation, routes) => {
+  const targets = [
+    ...navigation.tabs.map((tab) => ({ label: tab.label, path: tab.path })),
+    ...navigation.selectors.flatMap((selector) => selector.items.map((item) => ({ label: item.label, path: item.path })))
+  ];
+  const diagnostics = [];
+  const seen = new Set;
+  for (const { label, path } of targets) {
+    if (!path.startsWith("/") || path.startsWith("/#") || seen.has(path)) {
+      continue;
+    }
+    if (!resolvesToPages(routes, path.split("#")[0] ?? path)) {
+      seen.add(path);
+      diagnostics.push({
+        code: "BLUME_NAV_MISSING_PAGE",
+        message: `Navigation entry "${label}" points to ${path}, but no page matches it.`,
+        severity: "warning",
+        suggestion: "Fix the path, or add a page at that route."
+      });
+    }
+  }
+  return diagnostics;
+};
+var duplicateLabelDiagnostics = (navigation) => {
+  const diagnostics = [];
+  const checkLevel = (nodes, where) => {
+    const counts = new Map;
+    for (const node of nodes) {
+      counts.set(node.label, (counts.get(node.label) ?? 0) + 1);
+    }
+    for (const [label, count] of counts) {
+      if (count > 1) {
+        diagnostics.push({
+          code: "BLUME_NAV_DUPLICATE_LABEL",
+          message: `Duplicate sidebar label "${label}" appears ${count} times ${where}.`,
+          severity: "warning",
+          suggestion: "Give the entries distinct titles."
+        });
+      }
+    }
+    for (const node of nodes) {
+      if (node.kind === "group") {
+        checkLevel(node.children, `under "${node.label}"`);
+      }
+    }
+  };
+  const sidebars = [
+    { nodes: navigation.sidebar, where: "at the top level" },
+    ...navigation.sidebarVariants.map((variant) => ({
+      nodes: variant.sidebar,
+      where: `in the "${variant.path}" section`
+    }))
+  ];
+  for (const { nodes, where } of sidebars) {
+    checkLevel(nodes, where);
+  }
+  return diagnostics;
+};
+var hiddenInSidebarDiagnostics = (navigation, pages) => {
+  const hidden = new Set(pages.filter((page) => page.meta.sidebar.hidden).map((page) => page.id));
+  if (hidden.size === 0) {
+    return [];
+  }
+  const sidebars = [
+    navigation.sidebar,
+    ...navigation.sidebarVariants.map((variant) => variant.sidebar)
+  ];
+  const diagnostics = [];
+  const seen = new Set;
+  for (const sidebar of sidebars) {
+    for (const node of flattenNodes(sidebar)) {
+      if (node.kind === "page" && hidden.has(node.pageId) && !seen.has(node.pageId)) {
+        seen.add(node.pageId);
+        diagnostics.push({
+          code: "BLUME_NAV_HIDDEN_IN_SIDEBAR",
+          message: `Page "${node.label}" is marked hidden but appears in the sidebar (and its pagination).`,
+          severity: "warning",
+          suggestion: "Remove it from the navigation config, or unset sidebar.hidden."
+        });
+      }
+    }
+  }
+  return diagnostics;
+};
+var validateNavStructure = (navigation, pages) => [
+  ...duplicateLabelDiagnostics(navigation),
+  ...hiddenInSidebarDiagnostics(navigation, pages)
+];
+
 // src/core/tsconfig-aliases.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2, statSync } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync2, statSync } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import { pathToFileURL } from "node:url";
-import { dirname as dirname4, isAbsolute, join as join6, resolve as resolve2 } from "pathe";
+import { dirname as dirname5, isAbsolute as isAbsolute2, join as join6, resolve as resolve3 } from "pathe";
 var stripJsonComments = (text) => {
   let out = "";
   let inString = false;
@@ -2831,11 +3678,11 @@ var isFile = (path) => {
   }
 };
 var resolveExtends = (spec, fromDir) => {
-  if (spec.startsWith(".") || isAbsolute(spec)) {
-    const candidates = spec.endsWith(".json") ? [resolve2(fromDir, spec)] : [
-      resolve2(fromDir, `${spec}.json`),
-      resolve2(fromDir, spec, "tsconfig.json"),
-      resolve2(fromDir, spec)
+  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)
     ];
     return candidates.find(isFile) ?? null;
   }
@@ -2850,7 +3697,7 @@ var resolveExtends = (spec, fromDir) => {
   return null;
 };
 var loadPaths = (file, seen) => {
-  if (seen.has(file) || !existsSync3(file)) {
+  if (seen.has(file) || !existsSync4(file)) {
     return null;
   }
   seen.add(file);
@@ -2862,7 +3709,7 @@ var loadPaths = (file, seen) => {
   if (options.paths && typeof options.paths === "object") {
     const baseUrl = typeof options.baseUrl === "string" ? options.baseUrl : ".";
     return {
-      baseDir: resolve2(dirname4(file), baseUrl),
+      baseDir: resolve3(dirname5(file), baseUrl),
       paths: options.paths
     };
   }
@@ -2871,7 +3718,7 @@ var loadPaths = (file, seen) => {
     if (typeof base !== "string") {
       continue;
     }
-    const resolved = resolveExtends(base, dirname4(file));
+    const resolved = resolveExtends(base, dirname5(file));
     const found = resolved ? loadPaths(resolved, seen) : null;
     if (found) {
       return found;
@@ -2889,10 +3736,10 @@ var toAlias = (key, value, baseDir) => {
   if (find === "" || find === "*") {
     return null;
   }
-  return { find, replacement: resolve2(baseDir, target) };
+  return { find, replacement: resolve3(baseDir, target) };
 };
 var resolveTsconfigAliases = (root) => {
-  const entry = ["tsconfig.json", "jsconfig.json"].map((name) => join6(root, name)).find((file) => existsSync3(file));
+  const entry = ["tsconfig.json", "jsconfig.json"].map((name) => join6(root, name)).find((file) => existsSync4(file));
   if (!entry) {
     return {};
   }
@@ -2991,11 +3838,11 @@ ${items}
 
 // src/openapi/scalar.ts
 import { readFile as readFile4 } from "node:fs/promises";
-import { isAbsolute as isAbsolute2, join as join8 } from "pathe";
+import { isAbsolute as isAbsolute3, join as join8 } from "pathe";
 
 // src/astro/templates.ts
-import { existsSync as existsSync4, readFileSync as readFileSync3 } from "node:fs";
-import { dirname as dirname5, join as join7 } from "pathe";
+import { existsSync as existsSync5, readFileSync as readFileSync3 } from "node:fs";
+import { dirname as dirname6, join as join7 } from "pathe";
 
 // src/theme/fonts.ts
 var FALLBACKS = {
@@ -3153,7 +4000,7 @@ var WORKSPACE_MARKERS = [
   "yarn.lock"
 ];
 var hasWorkspacesField = (pkgPath) => {
-  if (!existsSync4(pkgPath)) {
+  if (!existsSync5(pkgPath)) {
     return false;
   }
   try {
@@ -3163,14 +4010,14 @@ var hasWorkspacesField = (pkgPath) => {
     return false;
   }
 };
-var hasWorkspaceMarker = (dir) => hasWorkspacesField(join7(dir, "package.json")) || WORKSPACE_MARKERS.some((marker) => existsSync4(join7(dir, marker)));
+var hasWorkspaceMarker = (dir) => hasWorkspacesField(join7(dir, "package.json")) || WORKSPACE_MARKERS.some((marker) => existsSync5(join7(dir, marker)));
 var findWorkspaceRoot = (start) => {
   let dir = start;
   for (;; ) {
     if (hasWorkspaceMarker(dir)) {
       return dir;
     }
-    const parent = dirname5(dir);
+    const parent = dirname6(dir);
     if (parent === dir) {
       return start;
     }
@@ -3385,7 +4232,7 @@ ${stagedBlock}
 export const collections = { docs${options.staged ? ", staged" : ""} };
 `;
 };
-var askEndpointTemplate = (backend) => {
+var askEndpointTemplate = (backend, grounded) => {
   const imports = [
     'import type { APIRoute } from "astro";',
     'import { streamText } from "ai";'
@@ -3409,13 +4256,24 @@ const provider = createOpenAICompatible({
 `;
     modelExpr = `provider(${JSON.stringify(backend.model)})`;
   }
-  return `// Generated by Blume. Do not edit.
-${imports.join(`
-`)}
-
-export const prerender = false;
-${setup}
-export const POST: APIRoute = async ({ request }) => {
+  if (grounded) {
+    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},
@@ -3424,7 +4282,14 @@ export const POST: APIRoute = async ({ request }) => {
     messages,
   });
   return result.toTextStreamResponse();
-};
+};`;
+  return `// Generated by Blume. Do not edit.
+${imports.join(`
+`)}
+
+export const prerender = false;
+${setup}
+${handler}
 `;
 };
 var searchEndpointTemplate = () => `// Generated by Blume. Do not edit.
@@ -3611,31 +4476,47 @@ const customRoutes = ${JSON.stringify(customRoutes)};
 export function getStaticPaths() {
   const seen = new Set();
   const paths = [];
-  const add = (slug, title, eyebrow) => {
+  const add = (slug, title) => {
     if (seen.has(slug)) {
       return;
     }
     seen.add(slug);
-    paths.push({ params: { slug }, props: { eyebrow, title } });
+    paths.push({ params: { slug }, props: { title } });
   };
   // A custom page wins over a content route sharing its path, so add it first.
   for (const route of customRoutes) {
-    add(route.slug, route.title, route.eyebrow);
+    add(route.slug, route.title);
   }
   for (const route of data.routes) {
-    add(
-      route.path === "/" ? "index" : route.path.slice(1),
-      route.title,
-      data.config.title
-    );
+    add(route.path === "/" ? "index" : route.path.slice(1), route.title);
   }
   return paths;
 }
 
+// Footer branding shared by every card, derived once from the resolved config.
+// The repo slug reuses the header link URL; the host comes from the site URL.
+const repoSlug = data.config.repoUrl
+  ? data.config.repoUrl.split("github.com/")[1]
+  : undefined;
+const siteHost = (() => {
+  if (!data.config.site) {
+    return undefined;
+  }
+  try {
+    return new URL(data.config.site).host;
+  } catch {
+    return undefined;
+  }
+})();
+
 export async function GET({ props }) {
   const png = await renderOgImage({
     accent: data.config.theme.accent,
-    eyebrow: props.eyebrow,
+    brand: data.config.title,
+    description: data.config.description,
+    logo: data.config.logo?.svg,
+    repo: repoSlug,
+    site: siteHost,
     title: props.title,
   });
   return new Response(png, {
@@ -3683,10 +4564,13 @@ var catchAllPageTemplate = (options) => {
 ` : "";
   const mathEntry = options.mathEnabled ? `Math,
   ` : "";
+  const clientData = options.needsReact ? `
+  clientData={{ config: data.config, navigation, page: { route, title: seo.title ?? title } }}` : "";
   return `---
 // Generated by Blume. Do not edit.
 import { getEntry, render } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
+import { resolveSlot } from "blume/components/layout/overrides.ts";
 ${askImport}
 import Accordion from "blume/components/content/Accordion.astro";
 import AccordionItem from "blume/components/content/AccordionItem.astro";
@@ -3862,11 +4746,15 @@ const localeSwitch = i18n
       };
     })
   : [];
+
+// The whole page shell is overridable via \`layout.Layout\`; it receives the same
+// props as the built-in RootLayout, plus the \`layout\` map for its inner slots.
+const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
 
-<RootLayout
+<LayoutComponent
   site={{ title: data.config.title, description: data.config.description }}
-  layout={layoutOverrides}
+  layout={layoutOverrides}${clientData}
   logo={data.config.logo}
   mcp={data.config.mcp}
   favicon={data.config.favicon}
@@ -3885,6 +4773,7 @@ const localeSwitch = i18n
   localeSwitch={localeSwitch}
   page={{ title: seo.title ?? title, description: seo.description ?? frontmatter.description, route }}
   headings={headings}
+  toc={data.config.toc}
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
@@ -3907,7 +4796,7 @@ const localeSwitch = i18n
   <h1>{title}</h1>
   {frontmatter.description && <p class="text-lg text-muted-foreground">{frontmatter.description}</p>}
   <Content components={components} />
-</RootLayout>
+</LayoutComponent>
 `;
 };
 var changelogIndexTemplate = (options) => {
@@ -3915,6 +4804,8 @@ var changelogIndexTemplate = (options) => {
 ` : "";
   const askSlot = options.askEnabled ? `
   <AskAI slot="ask" />` : "";
+  const clientData = options.needsReact ? `
+  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/changelog", title: data.config.title + " changelog" } }}` : "";
   const stagedSpread = options.staged ? `
   ...(await getCollection("staged")),` : "";
   return `---
@@ -3922,6 +4813,7 @@ var changelogIndexTemplate = (options) => {
 import { getCollection, render } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
 import Update from "blume/components/content/Update.astro";
+import { resolveSlot } from "blume/components/layout/overrides.ts";
 import { layoutOverrides } from "../generated/components.ts";
 ${askImport}import data from "../generated/data.json";
 
@@ -3993,11 +4885,13 @@ const headings = items.map((item) => ({
 
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const canonical = base ? base + "/changelog" : null;
+
+const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
 
-<RootLayout
+<LayoutComponent
   site={{ title: data.config.title, description: data.config.description }}
-  layout={layoutOverrides}
+  layout={layoutOverrides}${clientData}
   logo={data.config.logo}
   mcp={data.config.mcp}
   favicon={data.config.favicon}
@@ -4013,6 +4907,7 @@ const canonical = base ? base + "/changelog" : null;
     route: "/changelog",
   }}
   headings={headings}
+  toc={data.config.toc}
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
@@ -4041,7 +4936,7 @@ const canonical = base ? base + "/changelog" : null;
       </div>
     )
   }
-</RootLayout>
+</LayoutComponent>
 `;
 };
 var notFoundPageTemplate = () => `---
@@ -4082,19 +4977,6 @@ const nf = data.ui.notFound;
   </div>
 </PageLayout>
 `;
-var userComponentsTemplate = (componentsFile) => {
-  if (!componentsFile) {
-    return `// Generated by Blume. Do not edit.
-export const mdxComponents = {};
-export const layoutOverrides = {};
-`;
-  }
-  return `// Generated by Blume. Do not edit.
-import overrides from ${JSON.stringify(componentsFile)};
-export const mdxComponents = overrides.mdx ?? {};
-export const layoutOverrides = overrides.layout ?? {};
-`;
-};
 var islandDirective = (spec) => spec.client === "only" ? `client:only="${spec.framework}"` : `client:${spec.client}`;
 var islandWrapperTemplate = (spec) => `---
 // Generated by Blume. Do not edit.
@@ -4156,6 +5038,12 @@ declare module "blume:data" {
   const data: import("blume").BlumeData;
   export default data;
 }
+
+declare module "blume:search-client" {
+  export const createSearch: () =>
+    | import("blume/components/layout/search/types.ts").SearchFn
+    | Promise<import("blume/components/layout/search/types.ts").SearchFn>;
+}
 `;
 var runtimePackageTemplate = (dependencies = []) => `${JSON.stringify({
   dependencies: Object.fromEntries([...dependencies].toSorted().map((name) => [name, "*"])),
@@ -4336,7 +5224,7 @@ var specConfiguration = async (spec, root) => {
   if (URL_SPEC.test(spec)) {
     return { config: { url: spec } };
   }
-  const absolute = isAbsolute2(spec) ? spec : join8(root, spec);
+  const absolute = isAbsolute3(spec) ? spec : join8(root, spec);
   try {
     return { config: { content: await readFile4(absolute, "utf-8") } };
   } catch {
@@ -5075,9 +5963,106 @@ var twoslashCss = () => {
 ${OVERRIDES}`;
 };
 
+// src/astro/component-slots.ts
+var EMPTY_MODULE = `// Generated by Blume. Do not edit.
+export const mdxComponents = {};
+export const layoutOverrides = {};
+`;
+var directiveFor = (override) => {
+  const framework = override.source?.framework;
+  switch (override.client) {
+    case "idle": {
+      return "client:idle";
+    }
+    case "visible": {
+      return "client:visible";
+    }
+    case "media": {
+      return override.media ? `client:media="${override.media}"` : "client:load";
+    }
+    case "only": {
+      return framework ? `client:only="${framework}"` : "client:load";
+    }
+    default: {
+      return "client:load";
+    }
+  }
+};
+var importClause = (variable, name, path) => name === "default" ? `import ${variable} from ${JSON.stringify(path)};` : `import { ${name} as ${variable} } from ${JSON.stringify(path)};`;
+var wrapperContent = (override) => {
+  const { name, path } = override.source;
+  const clause = name === "default" ? `import Component from ${JSON.stringify(path)};` : `import { ${name} as Component } from ${JSON.stringify(path)};`;
+  return `---
+// Generated by Blume. Do not edit.
+${clause}
+---
+<Component ${directiveFor(override)} {...Astro.props}><slot /></Component>
+`;
+};
+var sanitize = (value) => value.replaceAll(/[^A-Za-z0-9]/gu, "_");
+var planComponentSlots = (componentsFile, analysis) => {
+  const frameworks = new Set;
+  if (!componentsFile) {
+    return { frameworks, module: EMPTY_MODULE, wrappers: [] };
+  }
+  if (!analysis) {
+    return {
+      frameworks,
+      module: `// Generated by Blume. Do not edit.
+import overrides from ${JSON.stringify(componentsFile)};
+export const mdxComponents = overrides.mdx ?? {};
+export const layoutOverrides = overrides.layout ?? {};
+`,
+      wrappers: []
+    };
+  }
+  const wrappers = [];
+  const importLines = [];
+  const mdxEntries = [];
+  const layoutEntries = [];
+  let counter = 0;
+  const mdxOverrides = [...analysis.mdx, ...analysis.islands];
+  const plan = (override, group, entries) => {
+    const { source } = override;
+    if (source?.framework) {
+      frameworks.add(source.framework);
+    }
+    if (override.identifier && !override.client) {
+      return;
+    }
+    if (!source) {
+      return;
+    }
+    const variable = `__blumeSlot${counter}`;
+    counter += 1;
+    if (override.client) {
+      const name = `${group}-${sanitize(override.key)}`;
+      wrappers.push({ content: wrapperContent(override), name });
+      importLines.push(importClause(variable, "default", `./component-slots/${name}.astro`));
+    } else {
+      importLines.push(importClause(variable, source.name, source.path));
+    }
+    entries.push(`${JSON.stringify(override.key)}: ${variable}`);
+  };
+  for (const override of mdxOverrides) {
+    plan(override, "mdx", mdxEntries);
+  }
+  for (const override of analysis.layout) {
+    plan(override, "layout", layoutEntries);
+  }
+  const moduleSource = `// Generated by Blume. Do not edit.
+import overrides from ${JSON.stringify(componentsFile)};
+${importLines.join(`
+`)}${importLines.length ? `
+` : ""}export const mdxComponents = { ...(overrides.mdx ?? {})${mdxEntries.length ? `, ${mdxEntries.join(", ")}` : ""} };
+export const layoutOverrides = { ...(overrides.layout ?? {})${layoutEntries.length ? `, ${layoutEntries.join(", ")}` : ""} };
+`;
+  return { frameworks, module: moduleSource, wrappers };
+};
+
 // src/astro/examples.ts
 import { readFile as readFile6 } from "node:fs/promises";
-import { join as join10, relative as relative3 } from "pathe";
+import { join as join10, relative as relative4 } from "pathe";
 import { glob as glob2 } from "tinyglobby";
 
 // src/astro/islands.ts
@@ -5091,7 +6076,7 @@ var VALID_MODES = new Set([
   "only",
   "visible"
 ]);
-var FRAMEWORK_BY_EXT = {
+var FRAMEWORK_BY_EXT2 = {
   jsx: "react",
   svelte: "svelte",
   tsx: "react",
@@ -5125,7 +6110,7 @@ var discoverIslands = async (root) => {
   for (const [index, file] of files.entries()) {
     const base = basename(file);
     const ext = base.match(ISLAND_FILE)?.groups?.ext;
-    const framework = ext ? FRAMEWORK_BY_EXT[ext] : undefined;
+    const framework = ext ? FRAMEWORK_BY_EXT2[ext] : undefined;
     if (!framework) {
       continue;
     }
@@ -5151,7 +6136,7 @@ var discoverIslands = async (root) => {
 };
 
 // src/astro/examples.ts
-var FRAMEWORK_BY_EXT2 = {
+var FRAMEWORK_BY_EXT3 = {
   astro: "astro",
   jsx: "react",
   svelte: "svelte",
@@ -5187,11 +6172,11 @@ var discoverExamples = async (root, pattern = "examples") => {
   const seen = new Map;
   for (const [index, file] of files.entries()) {
     const ext = file.match(EXAMPLE_FILE)?.groups?.ext;
-    const framework = ext ? FRAMEWORK_BY_EXT2[ext] : undefined;
+    const framework = ext ? FRAMEWORK_BY_EXT3[ext] : undefined;
     if (!(ext && framework)) {
       continue;
     }
-    const path = relative3(dir, file).slice(0, -(ext.length + 1));
+    const path = relative4(dir, file).slice(0, -(ext.length + 1));
     const existing = seen.get(path);
     if (existing) {
       warnings.push(`Two examples both resolve to "${path}" ("${existing}" and "${file}"); ignoring the second. Give them distinct paths.`);
@@ -5212,7 +6197,7 @@ var discoverExamples = async (root, pattern = "examples") => {
 };
 
 // src/astro/pages.ts
-import { extname, relative as relative4 } from "pathe";
+import { extname as extname2, relative as relative5 } from "pathe";
 import { glob as glob3 } from "tinyglobby";
 var discoverPages = async (pagesRoot) => {
   const files = await glob3(["**/*.astro"], {
@@ -5222,8 +6207,8 @@ var discoverPages = async (pagesRoot) => {
   });
   files.sort();
   return files.map((file) => {
-    const rel = relative4(pagesRoot, file);
-    const withoutExt = rel.slice(0, rel.length - extname(rel).length);
+    const rel = relative5(pagesRoot, file);
+    const withoutExt = rel.slice(0, rel.length - extname2(rel).length);
     const parts = withoutExt.split("/").filter((part) => part !== "index");
     const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
     return { entrypoint: file, pattern };
@@ -5232,7 +6217,7 @@ var discoverPages = async (pagesRoot) => {
 var routeIsTaken = (pages, contentPages, route) => pages.some((page) => page.pattern === route) || contentPages.some((page) => page.route === route);
 var PRIVATE_SEGMENT = /^[._]/u;
 var humanizeSegment = (segment) => segment.split(/[-_]/u).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
-var customOgRoutes = (pages, siteTitle, siteDescription) => {
+var customOgRoutes = (pages, siteTitle) => {
   const seen = new Set;
   const routes = [];
   for (const { pattern } of pages) {
@@ -5246,7 +6231,7 @@ var customOgRoutes = (pages, siteTitle, siteDescription) => {
     }
     seen.add(slug);
     const last = segments.at(-1);
-    routes.push(last ? { eyebrow: siteTitle, slug, title: humanizeSegment(last) } : { eyebrow: siteDescription, slug, title: siteTitle });
+    routes.push({ slug, title: last ? humanizeSegment(last) : siteTitle });
   }
   return routes;
 };
@@ -5270,8 +6255,8 @@ var resolvedAstroPath = (fromDir) => {
   }
 };
 var blumeDepsDir = (pkgDir = packageRoot()) => {
-  const candidates = [join11(pkgDir, "node_modules"), dirname6(pkgDir)];
-  return candidates.find((dir) => existsSync5(join11(dir, "astro"))) ?? null;
+  const candidates = [join11(pkgDir, "node_modules"), dirname7(pkgDir)];
+  return candidates.find((dir) => existsSync6(join11(dir, "astro"))) ?? null;
 };
 var linkDepsJunction = async (link, depsDir) => {
   const existing = await lstat(link).catch(() => null);
@@ -5281,7 +6266,7 @@ var linkDepsJunction = async (link, depsDir) => {
     }
     await rm(link, { force: true });
   }
-  await mkdir2(dirname6(link), { recursive: true });
+  await mkdir2(dirname7(link), { recursive: true });
   await symlink(depsDir, link, "junction");
 };
 var readPkgVersion = (pkgJsonPath) => {
@@ -5311,7 +6296,7 @@ var ensureDepsLink = async (outDir, pkgDir = packageRoot()) => {
   if (blumeAstro && outDirAstro === blumeAstro) {
     return null;
   }
-  if (existsSync5(join11(depsDir, "@astrojs", "mdx"))) {
+  if (existsSync6(join11(depsDir, "@astrojs", "mdx"))) {
     await linkDepsJunction(join11(outDir, "node_modules"), depsDir);
     return null;
   }
@@ -5359,7 +6344,7 @@ var writeIfChanged = async (path, content) => {
   if (existing === content) {
     return false;
   }
-  await mkdir2(dirname6(path), { recursive: true });
+  await mkdir2(dirname7(path), { recursive: true });
   const tmp = `${path}.${process.pid}.tmp`;
   await writeFile2(tmp, content, "utf-8");
   try {
@@ -5395,7 +6380,7 @@ var writeStagedContent = async (out, staged) => {
     written.add(normalize(path));
     await writeIfChanged(path, text);
   }));
-  if (existsSync5(contentDir)) {
+  if (existsSync6(contentDir)) {
     await pruneOrphans(contentDir, written);
   }
 };
@@ -5414,7 +6399,7 @@ var resolveLogo = (project) => {
     const file = [
       join11(project.context.root, "public", rel),
       join11(project.context.root, rel)
-    ].find((path) => existsSync5(path));
+    ].find((path) => existsSync6(path));
     if (file) {
       return { alt, href, svg: readFileSync5(file, "utf-8") };
     }
@@ -5454,13 +6439,13 @@ var APPLE_ICON_CANDIDATES = [
 var resolveIconFile = (project, candidates) => {
   const { root } = project.context;
   for (const name of candidates) {
-    if (existsSync5(join11(root, "public", name))) {
+    if (existsSync6(join11(root, "public", name))) {
       return { href: `/${name}`, type: faviconType(name) };
     }
   }
   for (const name of candidates) {
     const file = join11(root, name);
-    if (existsSync5(file)) {
+    if (existsSync6(file)) {
       const type = faviconType(name);
       return { href: inlineDataUri(file, type ?? "image/x-icon"), type };
     }
@@ -5493,7 +6478,7 @@ var buildRuntimeData = (project) => {
     if (!(editBase && sourcePath)) {
       return null;
     }
-    const rel = relative5(context.root, sourcePath).split("\\").join("/");
+    const rel = relative6(context.root, sourcePath).split("\\").join("/");
     return `${editBase}/${github?.dir ? `${github.dir}/${rel}` : rel}`;
   };
   const { i18n } = config;
@@ -5554,7 +6539,8 @@ var buildRuntimeData = (project) => {
       site: config.deployment.site ?? null,
       structuredData: config.seo.structuredData,
       theme: config.theme,
-      title: config.title
+      title: config.title,
+      toc: config.toc
     },
     feeds: buildRssFeeds(project).map((feed) => ({
       href: feed.path,
@@ -5641,6 +6627,18 @@ var writeMcpFiles = async (project, plan, write) => {
     write(join11(plan.dir, "server-card.ts"), staticJsonEndpointTemplate(buildMcpServerCard(discoveryInput)))
   ]);
 };
+var writeAskFiles = async (project, srcDir, write) => {
+  const { ask } = project.config.ai;
+  if (!ask?.enabled) {
+    return;
+  }
+  const grounded = ask.provider !== "inkeep";
+  if (grounded) {
+    await write(join11(srcDir, "generated", "ask-data.json"), `${JSON.stringify(await buildAskData(project))}
+`);
+  }
+  await write(join11(srcDir, "pages", "api", "ask.ts"), askEndpointTemplate(resolveAskBackend(ask), grounded));
+};
 var writeNotFoundPage = async (write, srcDir, pages, contentPages) => {
   if (routeIsTaken(pages, contentPages, "/404")) {
     return;
@@ -5653,6 +6651,14 @@ var shouldGenerateChangelog = (project) => {
   const changelogRouteTaken = project.graph.pages.some((page) => page.route === "/changelog");
   return (hasChangelog || hasChangelogSource) && !changelogRouteTaken;
 };
+var buildComponentSlots = async (componentsFile) => {
+  const analysis = componentsFile ? analyzeComponentOverrides(await readFile7(componentsFile, "utf-8"), componentsFile) : null;
+  return {
+    plan: planComponentSlots(componentsFile, analysis),
+    tags: analysis ? [...analysis.mdx, ...analysis.islands].map((entry) => entry.key) : [],
+    warnings: analysis ? analysis.warnings : []
+  };
+};
 var generateRuntime = async (project) => {
   const { context, config } = project;
   const out = context.outDir;
@@ -5677,14 +6683,20 @@ var generateRuntime = async (project) => {
     discoverIslands(context.root),
     discoverExamples(context.root, config.examples)
   ]);
+  const {
+    plan: slotPlan,
+    tags: overrideTags,
+    warnings: overrideWarnings
+  } = await buildComponentSlots(context.componentsFile);
   const frameworks = new Set([
     ...islandDiscovery.islands.map((island) => island.framework),
-    ...exampleDiscovery.examples.map((example) => example.framework)
+    ...exampleDiscovery.examples.map((example) => example.framework),
+    ...slotPlan.frameworks
   ]);
   const needsReact = detectedReact || askEnabled || frameworks.has("react");
   const needsVue = frameworks.has("vue");
   const needsSvelte = frameworks.has("svelte");
-  const ogRoutes = customOgRoutes(pages, config.title, config.description);
+  const ogRoutes = customOgRoutes(pages, config.title);
   const mcp = planMcp(project, srcDir);
   pages.push(...mcp.discoveryPages);
   const staged = collectStaged(project);
@@ -5712,9 +6724,10 @@ var generateRuntime = async (project) => {
       askEnabled,
       exportEpub,
       exportPdf,
-      mathEnabled: config.markdown.math
+      mathEnabled: config.markdown.math,
+      needsReact
     })),
-    write(join11(srcDir, "generated", "components.ts"), userComponentsTemplate(context.componentsFile)),
+    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(themePath, tailwindEntryTemplate({
@@ -5728,10 +6741,9 @@ var generateRuntime = async (project) => {
     }))
   ]);
   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))));
-  if (askEnabled) {
-    await write(join11(srcDir, "pages", "api", "ask.ts"), askEndpointTemplate(resolveAskBackend(config.ai.ask)));
-  }
+  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));
@@ -5741,6 +6753,7 @@ var generateRuntime = async (project) => {
       askEnabled,
       exportEpub,
       exportPdf,
+      needsReact,
       staged: hasStaged
     }));
   }
@@ -5775,8 +6788,23 @@ var generateRuntime = async (project) => {
     ...depsLinkWarning ? [depsLinkWarning] : [],
     ...mcp.warnings,
     ...islandDiscovery.warnings,
-    ...exampleDiscovery.warnings
+    ...exampleDiscovery.warnings,
+    ...overrideWarnings
   ];
+  const navTargetRoutes = new Set([
+    ...project.graph.routes.keys(),
+    ...pages.map((page) => page.pattern),
+    ...referenceTabs(config).map((tab) => tab.path)
+  ]);
+  if (shouldGenerateChangelog(project)) {
+    navTargetRoutes.add("/changelog");
+  }
+  warnings.push(...validateNavTargets(project.graph.navigation, navTargetRoutes).map((diagnostic) => diagnostic.suggestion ? `${diagnostic.message} ${diagnostic.suggestion}` : diagnostic.message));
+  const knownComponentTags = new Set([
+    ...islandDiscovery.islands.map((island) => island.name),
+    ...overrideTags
+  ]);
+  warnings.push(...validateUsedComponents(project.graph.pages, knownComponentTags, new Set(registry.map((item) => item.name))).map((diagnostic) => diagnostic.suggestion ? `${diagnostic.message} ${diagnostic.suggestion}` : diagnostic.message));
   for (const dep of searchProviderMeta(config.search.provider).runtimeDeps) {
     if (!(canResolveFrom(context.root, dep) || canResolveFrom(packageRoot(), dep))) {
       warnings.push(`Search provider "${config.search.provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`);
@@ -5800,14 +6828,17 @@ var generateRuntime = async (project) => {
   return { structuralChange: structural.some(Boolean), warnings };
 };
 
+// src/core/config.ts
+import { existsSync as existsSync9, readFileSync as readFileSync6 } from "node:fs";
+
 // src/core/bridge.ts
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
 import { readFile as readFile9 } from "node:fs/promises";
 import { join as join12 } from "pathe";
 
 // src/migrate/mintlify/config.ts
 import { readFile as readFile8 } from "node:fs/promises";
-import { dirname as dirname7, relative as relative6, resolve as resolve3 } from "pathe";
+import { dirname as dirname8, relative as relative7, resolve as resolve4 } from "pathe";
 var MINTLIFY_DEFAULT_IGNORES = [
   "**/_*",
   "**/.*",
@@ -5843,7 +6874,7 @@ var asDirectoryMode = (value) => value === "accordion" || value === "card" || va
 var withoutUndefined = (value) => Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
 var hasOwn = (object, key) => Object.hasOwn(object, key);
 var isInsideRoot = (root, candidate) => {
-  const rel = relative6(root, candidate);
+  const rel = relative7(root, candidate);
   return rel === "" || !rel.startsWith("..") && !rel.startsWith("/");
 };
 var readJsonFile = async (file) => {
@@ -5868,7 +6899,7 @@ var resolveRefs = async (value, options) => {
   }
   const ref = asString(object.$ref);
   if (ref) {
-    const refFile = resolve3(dirname7(options.file), ref);
+    const refFile = resolve4(dirname8(options.file), ref);
     if (!isInsideRoot(options.root, refFile)) {
       throw new BlumeError({
         code: "BLUME_MINTLIFY_REF_OUTSIDE_ROOT",
@@ -6222,53 +7253,9 @@ var mintlifySelectors = (spec) => {
     }
   ].filter((selector) => selector.items.length > 0);
 };
-var navbarTypeLabel = (type) => {
-  if (type === "github") {
-    return "GitHub";
-  }
-  if (type === "discord") {
-    return "Discord";
-  }
-  return;
-};
-var navbarLinkType = (type) => type === "github" || type === "discord" ? type : undefined;
-var navbarPrimaryType = (type) => type === "github" || type === "discord" ? type : "button";
-var mintlifyNavbar = (value) => {
-  const object = asObject(value);
-  if (!object) {
-    return { links: [] };
-  }
-  const links = asArray(object.links).flatMap((item) => {
-    const itemObject = asObject(item);
-    const href = itemObject ? asString(itemObject.href) : undefined;
-    const type = itemObject ? asString(itemObject.type) : undefined;
-    const label = itemObject ? asString(itemObject.label) ?? navbarTypeLabel(type) : undefined;
-    if (!itemObject || !href || !label) {
-      return [];
-    }
-    return [
-      withoutUndefined({
-        href,
-        icon: asString(itemObject.icon),
-        label,
-        type: navbarLinkType(type)
-      })
-    ];
-  });
-  const primaryObject = asObject(object.primary);
-  const primaryHref = primaryObject ? asString(primaryObject.href) : undefined;
-  const primaryType = primaryObject ? asString(primaryObject.type) ?? "button" : undefined;
-  const primaryLabel = primaryObject ? asString(primaryObject.label) ?? navbarTypeLabel(primaryType) : undefined;
-  const primary = primaryObject && primaryHref && primaryLabel ? withoutUndefined({
-    href: primaryHref,
-    label: primaryLabel,
-    type: navbarPrimaryType(primaryType)
-  }) : undefined;
-  return withoutUndefined({ links, primary });
-};
 var mintignorePatterns = async (root) => {
   try {
-    const raw = await readFile8(resolve3(root, ".mintignore"), "utf-8");
+    const raw = await readFile8(resolve4(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 {
@@ -6287,61 +7274,6 @@ var mintlifyRedirects = (spec) => asArray(spec.redirects).flatMap((redirect) =>
   }
   return [{ from, to }];
 });
-var mintlifyContextual = (value) => {
-  const object = asObject(value);
-  if (!object) {
-    return { options: [] };
-  }
-  const display = object.display === "toc" ? "toc" : "header";
-  const options = [];
-  for (const option of asArray(object.options)) {
-    if (typeof option === "string") {
-      options.push(option);
-      continue;
-    }
-    const optionObject = asObject(option);
-    const title = optionObject ? asString(optionObject.title) : undefined;
-    if (!optionObject || !title) {
-      continue;
-    }
-    options.push(withoutUndefined({
-      description: asString(optionObject.description),
-      href: asString(optionObject.href),
-      icon: asString(optionObject.icon),
-      title
-    }));
-  }
-  return { display, options };
-};
-var mintlifyFooter = (value) => {
-  const object = asObject(value);
-  const socials = asObject(object?.socials);
-  const links = asArray(object?.links).flatMap((group) => {
-    const groupObject = asObject(group);
-    const items = asArray(groupObject?.items).flatMap((item) => {
-      const itemObject = asObject(item);
-      const label = itemObject ? asString(itemObject.label) : undefined;
-      const href = itemObject ? asString(itemObject.href) : undefined;
-      return label && href ? [{ href, label }] : [];
-    });
-    if (!groupObject || items.length === 0) {
-      return [];
-    }
-    return [
-      withoutUndefined({
-        header: asString(groupObject.header),
-        items
-      })
-    ];
-  }).slice(0, 4);
-  return {
-    links,
-    socials: socials ? Object.fromEntries(Object.entries(socials).flatMap(([label, href]) => {
-      const hrefValue = asString(href);
-      return hrefValue ? [[label, hrefValue]] : [];
-    })) : {}
-  };
-};
 var mintlifyLogo = (value) => {
   if (typeof value === "string") {
     return value;
@@ -6406,16 +7338,12 @@ var mintlifyChromeVariants = (spec) => {
       return [];
     }
     const banner = hasOwn(object, "banner") ? mintlifyBanner(object.banner) : undefined;
-    const footer = hasOwn(object, "footer") ? mintlifyFooter(object.footer) : undefined;
-    const navbar = hasOwn(object, "navbar") ? mintlifyNavbar(object.navbar) : undefined;
-    if (!banner && !footer && !navbar) {
+    if (!banner) {
       return [];
     }
     return [
       withoutUndefined({
         banner,
-        footer,
-        navbar,
         path
       })
     ];
@@ -6467,13 +7395,6 @@ var mintlifyMarkdown = (value, styling) => {
     schema: object?.schema === false ? false : undefined
   });
 };
-var mintlifyStyling = (value) => {
-  const object = asObject(value);
-  const eyebrows = asString(object?.eyebrows);
-  return withoutUndefined({
-    eyebrows: eyebrows === "breadcrumbs" || eyebrows === "section" ? eyebrows : undefined
-  });
-};
 var mintlifySeo = (value) => {
   const object = asObject(value);
   const metatags = asObject(object?.metatags);
@@ -6484,16 +7405,9 @@ var mintlifySeo = (value) => {
     })) : {}
   };
 };
-var mintlifyIcons = (value) => {
-  const object = asObject(value);
-  const library = object?.library;
-  return withoutUndefined({
-    library: library === "fontawesome" || library === "lucide" || library === "tabler" ? library : undefined
-  });
-};
 var loadMintlifyConfig = async (root, file) => {
-  const projectRoot = resolve3(root);
-  const configFile = resolve3(file);
+  const projectRoot = resolve4(root);
+  const configFile = resolve4(file);
   const spec = asObject(await resolveRefs(await readJsonFile(configFile), {
     file: configFile,
     root: projectRoot,
@@ -6524,14 +7438,10 @@ var loadMintlifyConfig = async (root, file) => {
       ],
       root: "."
     },
-    contextual: mintlifyContextual(spec.contextual),
     description: asString(spec.description),
     favicon: mintlifyFavicon(spec.favicon),
-    footer: mintlifyFooter(spec.footer),
-    icons: mintlifyIcons(spec.icons),
     logo: mintlifyLogo(spec.logo),
     markdown: mintlifyMarkdown(spec.markdown, styling),
-    navbar: mintlifyNavbar(spec.navbar),
     navigation: {
       chromeVariants: mintlifyChromeVariants(spec),
       selectors: mintlifySelectors(spec),
@@ -6547,7 +7457,6 @@ var loadMintlifyConfig = async (root, file) => {
       prompt: asString(search.prompt)
     },
     seo: mintlifySeo(seo),
-    styling: mintlifyStyling(styling),
     theme: {
       accent: asString(colors.primary) ?? "blue",
       accentDark: asString(colors.light),
@@ -6594,7 +7503,7 @@ 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) => existsSync6(candidate));
+  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join12(root, name)).find((candidate) => existsSync7(candidate));
   if (!configFile) {
     return null;
   }
@@ -6683,8 +7592,8 @@ var createModuleLoader = () => {
 };
 
 // src/core/project.ts
-import { existsSync as existsSync7 } from "node:fs";
-import { isAbsolute as isAbsolute3, join as join13, resolve as resolve4 } from "pathe";
+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",
@@ -6695,7 +7604,7 @@ var COMPONENTS_FILENAMES = ["components.tsx", "components.ts"];
 var firstExisting = (root, names) => {
   for (const name of names) {
     const candidate = join13(root, name);
-    if (existsSync7(candidate)) {
+    if (existsSync8(candidate)) {
       return candidate;
     }
   }
@@ -6703,10 +7612,10 @@ var firstExisting = (root, names) => {
 };
 var findConfigFile = (root) => firstExisting(root, CONFIG_FILENAMES);
 var resolveProjectContext = (root, config) => {
-  const absoluteRoot = resolve4(root);
-  const contentRoot = isAbsolute3(config.content.root) ? config.content.root : join13(absoluteRoot, config.content.root);
+  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 = existsSync7(pagesPath) ? pagesPath : null;
+  const pagesRoot = existsSync8(pagesPath) ? pagesPath : null;
   return {
     componentsFile: firstExisting(absoluteRoot, COMPONENTS_FILENAMES),
     configFile: findConfigFile(absoluteRoot),
@@ -6951,26 +7860,6 @@ var sidebarVariantSchema = z2.object({
   items: z2.array(sidebarItemSchema).default([]),
   path: z2.string()
 }).strict();
-var navbarLinkTypeSchema = z2.enum(["github", "discord"]);
-var navbarLinkSchema = z2.object({
-  href: z2.string(),
-  icon: iconName.optional(),
-  label: z2.string().optional(),
-  type: navbarLinkTypeSchema.optional()
-}).strict().refine((value) => value.label !== undefined || value.type !== undefined, {
-  message: "Navbar links require either label or type."
-});
-var navbarPrimarySchema = z2.object({
-  href: z2.string(),
-  label: z2.string().optional(),
-  type: z2.enum(["button", "github", "discord"]).default("button")
-}).strict().refine((value) => value.label !== undefined || value.type !== "button", {
-  message: "Navbar primary button links require a label."
-});
-var navbarConfigSchema = z2.object({
-  links: z2.array(navbarLinkSchema).default([]),
-  primary: navbarPrimarySchema.optional()
-}).strict();
 var variablesConfigSchema = z2.record(z2.string().regex(/^[A-Za-z0-9-]+$/u), z2.string()).default({});
 var fontSlug = z2.string().refine(isFontSlug, (value) => ({
   message: `Unknown font "${value}". Supported fonts: ${FONT_SLUGS.join(", ")}.`
@@ -6994,9 +7883,6 @@ var themeConfigSchema = z2.object({
   radius: z2.enum(["none", "sm", "md", "lg"]).default("md"),
   strict: z2.boolean().default(false)
 }).strict();
-var iconsConfigSchema = z2.object({
-  library: z2.enum(["fontawesome", "lucide", "tabler"]).default("lucide")
-}).strict();
 var algoliaSearchSchema = z2.object({
   appId: z2.string(),
   indexName: z2.string(),
@@ -7078,33 +7964,8 @@ var aiConfigSchema = z2.object({
   }).optional(),
   llmsTxt: z2.boolean().default(false)
 }).strict();
-var contextualOptionSchema = z2.union([
-  z2.string(),
-  z2.object({
-    description: z2.string().optional(),
-    href: z2.string().optional(),
-    icon: iconName.optional(),
-    title: z2.string()
-  }).passthrough()
-]);
-var contextualConfigSchema = z2.object({
-  display: z2.enum(["header", "toc"]).default("header"),
-  options: z2.array(contextualOptionSchema).default([])
-}).strict();
-var footerConfigSchema = z2.object({
-  links: z2.array(z2.object({
-    header: z2.string().optional(),
-    items: z2.array(z2.object({
-      href: z2.string(),
-      label: z2.string()
-    }).strict()).default([])
-  }).strict()).max(4).default([]),
-  socials: z2.record(z2.string(), z2.string()).default({})
-}).strict();
 var chromeVariantSchema = z2.object({
   banner: bannerConfigSchema.optional(),
-  footer: footerConfigSchema.optional(),
-  navbar: navbarConfigSchema.optional(),
   path: z2.string()
 }).strict();
 var navigationConfigSchema = z2.object({
@@ -7229,9 +8090,6 @@ var markdownConfigSchema = z2.object({
   imageZoom: z2.boolean().default(true),
   math: z2.boolean().default(false)
 }).strict();
-var stylingConfigSchema = z2.object({
-  eyebrows: z2.enum(["breadcrumbs", "section"]).default("section")
-}).strict();
 var openapiSourceSchema = z2.object({
   label: z2.string().optional(),
   route: z2.string().optional(),
@@ -7251,36 +8109,48 @@ var asyncapiConfigSchema = z2.object({
   spec: z2.string().optional(),
   theme: z2.string().optional()
 }).strict();
+var tocConfigSchema = z2.union([
+  z2.boolean(),
+  z2.object({
+    maxHeadingLevel: z2.number().int().min(1).max(6).optional(),
+    minHeadingLevel: z2.number().int().min(1).max(6).optional()
+  }).strict()
+]).default(true).transform((value) => {
+  if (typeof value === "boolean") {
+    return { enabled: value, maxLevel: 3, minLevel: 2 };
+  }
+  return {
+    enabled: true,
+    maxLevel: value.maxHeadingLevel ?? 3,
+    minLevel: value.minHeadingLevel ?? 2
+  };
+});
 var blumeConfigSchema = z2.object({
   ai: aiConfigSchema.default({}),
   analytics: analyticsConfigSchema.optional(),
   asyncapi: asyncapiConfigSchema.default({}),
   banner: bannerConfigSchema.optional(),
   content: contentConfigSchema.default({}),
-  contextual: contextualConfigSchema.default({}),
   deployment: deploymentConfigSchema.default({}),
   description: z2.string().optional(),
   examples: z2.string().default("examples"),
   export: exportConfigSchema.default(false),
   favicon: faviconConfigSchema.optional(),
   feedback: z2.boolean().default(true),
-  footer: footerConfigSchema.default({}),
   github: githubConfigSchema.optional(),
   i18n: i18nConfigSchema.optional(),
-  icons: iconsConfigSchema.default({}),
   lastModified: lastModifiedConfigSchema.default(false),
   logo: logoConfigSchema.optional(),
   markdown: markdownConfigSchema.default({}),
   mcp: mcpConfigSchema.default({}),
-  navbar: navbarConfigSchema.default({}),
   navigation: navigationConfigSchema.default({}),
   openapi: openapiConfigSchema.default({}),
   redirects: z2.array(redirectSchema).default([]),
   search: searchConfigSchema.default({}),
   seo: seoConfigSchema.default({}),
-  styling: stylingConfigSchema.default({}),
   theme: themeConfigSchema.default({}),
   title: z2.string().default("Documentation"),
+  toc: tocConfigSchema,
   variables: variablesConfigSchema
 }).strict();
 
@@ -7310,9 +8180,11 @@ 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 diagnostics = diagnosticsFromZod(parsed.error, {
       code: "BLUME_CONFIG_INVALID",
-      file: sourceFile ?? undefined
+      file: sourceFile ?? undefined,
+      source
     });
     throw new BlumeError(diagnostics[0] ?? {
       code: "BLUME_CONFIG_INVALID",
@@ -7337,7 +8209,7 @@ var loadConfig = async (root, options = {}) => {
 };
 
 // src/core/navigation.ts
-import { extname as extname2 } from "pathe";
+import { extname as extname3 } from "pathe";
 var NUMERIC_PREFIX = /^(?<order>\d+)[-_.]/u;
 var GROUP_FOLDER = /^\((?<label>.+)\)$/u;
 var WORD_SPLIT = /[-_]/u;
@@ -7374,7 +8246,7 @@ var pageOrder = (page, filename) => {
   if (page.meta.sidebar.order !== undefined) {
     return page.meta.sidebar.order;
   }
-  if (filename.replace(extname2(filename), "") === "index") {
+  if (filename.replace(extname3(filename), "") === "index") {
     return Number.NEGATIVE_INFINITY;
   }
   return numericOrder(filename);
@@ -7466,7 +8338,7 @@ var buildFileSystemSidebar = (pages, folderMeta, sharedMeta, metaPrefix) => {
       deprecated: page.meta.deprecated || undefined,
       description: page.description,
       icon: page.meta.sidebar.icon,
-      key: segmentKey(filename.replace(extname2(filename), "")),
+      key: segmentKey(filename.replace(extname3(filename), "")),
       kind: "page",
       label: page.meta.sidebar.label ?? page.title,
       order: pageOrder(page, filename),
@@ -7665,6 +8537,8 @@ var buildContentGraph = (pages, options) => {
       tabs: options.navigation.tabs
     });
   }
+  diagnostics.push(...validateNavIcons(navigation));
+  diagnostics.push(...validateNavStructure(navigation, pages));
   return {
     diagnostics,
     navigation,
@@ -7676,7 +8550,7 @@ var buildContentGraph = (pages, options) => {
 
 // src/core/last-modified.ts
 import { execFileSync } from "node:child_process";
-import { relative as relative7 } from "pathe";
+import { relative as relative8 } from "pathe";
 var resolveLastModifiedConfig = (value) => {
   if (value === false) {
     return { enabled: false, source: "git" };
@@ -7716,7 +8590,7 @@ var gitLastModifiedTimes = (root, contentRoot, sourcePaths) => {
     const byRepoPath = parseGitLog(output);
     const result = new Map;
     for (const sourcePath of sourcePaths) {
-      const iso = byRepoPath.get(relative7(gitRoot, sourcePath));
+      const iso = byRepoPath.get(relative8(gitRoot, sourcePath));
       if (iso) {
         result.set(sourcePath, iso);
       }
@@ -7728,7 +8602,7 @@ var gitLastModifiedTimes = (root, contentRoot, sourcePaths) => {
 };
 
 // src/core/meta.ts
-import { basename as basename3, dirname as dirname8, relative as relative8 } from "pathe";
+import { basename as basename3, dirname as dirname9, relative as relative9 } from "pathe";
 import { glob as glob5 } from "tinyglobby";
 var META_FILES = [
   "**/meta.ts",
@@ -7758,7 +8632,7 @@ var discoverFolderMeta = async (contentRoot) => {
   const shared = new Map;
   const diagnostics = [];
   for (const entry of loaded) {
-    const dir = relative8(contentRoot, dirname8(entry.file));
+    const dir = relative9(contentRoot, dirname9(entry.file));
     if (!entry.ok) {
       diagnostics.push({
         code: "BLUME_META_LOAD_FAILED",
@@ -7783,8 +8657,9 @@ var discoverFolderMeta = async (contentRoot) => {
 };
 
 // src/core/sources/normalize.ts
+import { existsSync as existsSync10, readFileSync as readFileSync7 } from "node:fs";
 import GithubSlugger from "github-slugger";
-import { extname as extname3 } from "pathe";
+import { extname as extname4 } from "pathe";
 var NUMERIC_PREFIX2 = /^\d+[-_.]/u;
 var GROUP_FOLDER2 = /^\((?<label>.+)\)$/u;
 var WORD_SPLIT2 = /[-_]/u;
@@ -7793,7 +8668,7 @@ var groupLabel = (segment) => segment.match(GROUP_FOLDER2)?.groups?.label ?? nul
 var slugify2 = (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 - extname3(relativePath).length);
+  const withoutExt = relativePath.slice(0, relativePath.length - extname4(relativePath).length);
   const rawParts = withoutExt.split("/");
   const segments = [];
   const groups = [];
@@ -7840,10 +8715,39 @@ var MD_LINK = /\[[^\]]*\]\((?<target>[^)\s]+)(?:\s+"[^"]*")?\)/gu;
 var extractLinks = (body) => {
   const links = [];
   let inFence = false;
-  let lineNumber = 0;
+  let lineNumber = 0;
+  for (const line of body.split(`
+`)) {
+    lineNumber += 1;
+    if (CODE_FENCE2.test(line.trimStart())) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) {
+      continue;
+    }
+    for (const match of line.matchAll(MD_LINK)) {
+      const target = match.groups?.target;
+      if (target === undefined || match.index === undefined) {
+        continue;
+      }
+      links.push({
+        column: line.indexOf(target, match.index) + 1,
+        line: lineNumber,
+        target
+      });
+    }
+  }
+  return links;
+};
+var INLINE_CODE2 = /`[^`]*`/gu;
+var DOUBLE_QUOTED = /"[^"]*"/gu;
+var JSX_OPEN = /<(?<tag>[A-Z][A-Za-z0-9]*)/gu;
+var extractComponentTags = (body) => {
+  const tags = new Set;
+  let inFence = false;
   for (const line of body.split(`
 `)) {
-    lineNumber += 1;
     if (CODE_FENCE2.test(line.trimStart())) {
       inFence = !inFence;
       continue;
@@ -7851,19 +8755,15 @@ var extractLinks = (body) => {
     if (inFence) {
       continue;
     }
-    for (const match of line.matchAll(MD_LINK)) {
-      const target = match.groups?.target;
-      if (target === undefined || match.index === undefined) {
-        continue;
+    const clean = line.replaceAll(INLINE_CODE2, "").replaceAll(DOUBLE_QUOTED, "");
+    for (const match of clean.matchAll(JSX_OPEN)) {
+      const tag = match.groups?.tag;
+      if (tag) {
+        tags.add(tag);
       }
-      links.push({
-        column: line.indexOf(target, match.index) + 1,
-        line: lineNumber,
-        target
-      });
     }
   }
-  return links;
+  return [...tags];
 };
 var deriveTitle = (meta, headings, id2) => {
   if (meta.title) {
@@ -7874,18 +8774,20 @@ var deriveTitle = (meta, headings, id2) => {
     return firstHeading.text;
   }
   const base = id2.split("/").pop() ?? id2;
-  return titleCase(stripNumericPrefix(base.replace(extname3(base), "")));
+  return titleCase(stripNumericPrefix(base.replace(extname4(base), "")));
 };
 var withPrefix = (prefix, path) => prefix ? `${prefix}/${path}` : path;
-var normalizeEntry = (entry, ctx) => {
+var normalizeEntry2 = (entry, ctx) => {
   const { format } = entry.body;
   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);
     return {
       diagnostics: diagnosticsFromZod(result.error, {
         code: "BLUME_FRONTMATTER_INVALID",
-        file: entry.sourcePath ?? `${ctx.source.name}:${entry.ref}`
+        file: entry.sourcePath ?? `${ctx.source.name}:${entry.ref}`,
+        source
       }),
       pages: []
     };
@@ -7901,6 +8803,7 @@ var normalizeEntry = (entry, ctx) => {
   const base = {
     body: staged ? { format, text: entry.raw ?? entry.body.text } : undefined,
     collection: staged ? "staged" : undefined,
+    componentsUsed: format === "mdx" ? extractComponentTags(entry.body.text) : undefined,
     contentType: meta.type ?? ctx.defaultType,
     description: meta.description,
     editUrl: entry.editUrl,
@@ -7931,12 +8834,12 @@ var normalizeEntry = (entry, ctx) => {
 import { join as join22 } from "pathe";
 
 // src/core/sources/filesystem.ts
-import { existsSync as existsSync8, watch as fsWatch } from "node:fs";
+import { existsSync as existsSync11, watch as fsWatch } from "node:fs";
 import { readFile as readFile10 } from "node:fs/promises";
-import { extname as extname4, isAbsolute as isAbsolute4, join as join14, relative as relative9, resolve as resolve5 } from "pathe";
+import { extname as extname5, isAbsolute as isAbsolute5, join as join14, relative as relative10, resolve as resolve6 } from "pathe";
 import { glob as glob6 } from "tinyglobby";
 var filesystemSource = (options) => {
-  const contentRoot = isAbsolute4(options.root) ? options.root : join14(resolve5(options.projectRoot), options.root);
+  const contentRoot = isAbsolute5(options.root) ? options.root : join14(resolve6(options.projectRoot), options.root);
   const load2 = async () => {
     const files = await glob6(options.include, {
       absolute: true,
@@ -7947,20 +8850,20 @@ var filesystemSource = (options) => {
     files.sort();
     const entries = await Promise.all(files.map(async (file) => {
       const source = await readFile10(file, "utf-8");
-      const ext = extname4(file).toLowerCase();
+      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: relative9(contentRoot, file),
+        ref: relative10(contentRoot, file),
         sourcePath: file
       };
     }));
     return { diagnostics: [], entries };
   };
   const validate = () => {
-    if (!existsSync8(contentRoot)) {
+    if (!existsSync11(contentRoot)) {
       throw new BlumeError({
         code: options.missingCode ?? "BLUME_CONTENT_ROOT_MISSING",
         file: contentRoot,
@@ -7971,7 +8874,7 @@ var filesystemSource = (options) => {
     }
   };
   const watch = (onChange) => {
-    if (!existsSync8(contentRoot)) {
+    if (!existsSync11(contentRoot)) {
       return () => {};
     }
     const watcher = fsWatch(contentRoot, { recursive: true }, onChange);
@@ -8305,13 +9208,13 @@ var mdxRemoteSource = (options, ctx) => {
 };
 
 // src/core/sources/mintlify.ts
-import { existsSync as existsSync10, watch as fsWatch2 } from "node:fs";
+import { existsSync as existsSync13, watch as fsWatch2 } from "node:fs";
 import { readFile as readFile13 } from "node:fs/promises";
-import { isAbsolute as isAbsolute5, join as join18, relative as relative12, resolve as resolve7 } from "pathe";
+import { isAbsolute as isAbsolute6, join as join18, relative as relative13, resolve as resolve8 } from "pathe";
 import { glob as glob7 } from "tinyglobby";
 
 // src/migrate/shared.ts
-import { existsSync as existsSync9 } from "node:fs";
+import { existsSync as existsSync12 } from "node:fs";
 import { readFile as readFile12, writeFile as writeFile4 } from "node:fs/promises";
 import { join as join16 } from "pathe";
 var writeBlumeConfig = async (root, config) => {
@@ -8328,7 +9231,7 @@ var BLUME_SCRIPTS = {
 };
 var rewriteFrameworkScripts = async (root, cli, remove) => {
   const pkgPath = join16(root, "package.json");
-  if (!existsSync9(pkgPath)) {
+  if (!existsSync12(pkgPath)) {
     return false;
   }
   let pkg;
@@ -8364,7 +9267,7 @@ var rewriteFrameworkScripts = async (root, cli, remove) => {
 var gitignoreKey = (line) => line.trim().replace(/\/+$/u, "");
 var ensureGitignore = async (root, entries) => {
   const path = join16(root, ".gitignore");
-  const existing = existsSync9(path) ? await readFile12(path, "utf-8") : "";
+  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)));
@@ -8379,7 +9282,7 @@ var ensureGitignore = async (root, entries) => {
 `, "utf-8");
   return added;
 };
-var leftoverFiles = (root, candidates) => candidates.filter((candidate) => existsSync9(join16(root, candidate)));
+var leftoverFiles = (root, candidates) => candidates.filter((candidate) => existsSync12(join16(root, candidate)));
 var attribute = (attrs, name) => {
   const match = attrs.match(new RegExp(`\\b${name}=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')`, "u"));
   return match?.groups?.dq ?? match?.groups?.sq;
@@ -8422,7 +9325,7 @@ var findOpenTagEnd = (source, from) => {
   }
   return -1;
 };
-var directiveFor = (tag, attrs, options) => {
+var directiveFor2 = (tag, attrs, options) => {
   if (tag in options.tagDirectives) {
     return options.tagDirectives[tag];
   }
@@ -8452,7 +9355,7 @@ var rewriteCallouts = (source, options) => {
       continue;
     }
     const attrs = source.slice(start + tag.length + 1, openEnd);
-    const directive = directiveFor(tag, attrs, options);
+    const directive = directiveFor2(tag, attrs, options);
     const closeTag = `</${tag}>`;
     const selfClosing = attrs.trimEnd().endsWith("/");
     const closeIndex = selfClosing ? openEnd : source.indexOf(closeTag, openEnd + 1);
@@ -8776,7 +9679,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 dirname9, join as join17, relative as relative10 } from "pathe";
+import { dirname as dirname10, join as join17, relative as relative11 } from "pathe";
 var CALLOUT_DIRECTIVES = {
   Check: "success",
   Danger: "danger",
@@ -8814,7 +9717,7 @@ var rewriteSnippetImports = (source, options) => {
     }
     const target = join17(options.root, importSource.replace(/^\/+/u, ""));
     components.push(importSource.replace(/^\/+/u, ""));
-    let rel = relative10(dirname9(options.filePath), target);
+    let rel = relative11(dirname10(options.filePath), target);
     if (!rel.startsWith(".")) {
       rel = `./${rel}`;
     }
@@ -9004,7 +9907,7 @@ var rewriteMintlifySvgIconProps = (source) => {
 
 // src/migrate/mintlify/snippets.ts
 import { readFile as readFileFromDisk } from "node:fs/promises";
-import { dirname as dirname10, relative as relative11, resolve as resolve6 } from "pathe";
+import { dirname as dirname11, relative as relative12, 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;
@@ -9014,14 +9917,14 @@ 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 = relative11(root, candidate);
+  const rel = relative12(root, candidate);
   return rel === "" || !rel.startsWith("..") && !rel.startsWith("/");
 };
-var escapeRegExp = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-var snippetSelfClosingTagPattern = (name) => new RegExp(`<${escapeRegExp(name)}(?<attrs>[^>]*?)\\s*/>`, "gu");
-var snippetPairedTagPattern = (name) => new RegExp(`<${escapeRegExp(name)}(?<attrs>[^>]*?)>[\\s\\S]*?</${escapeRegExp(name)}>`, "gu");
+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 = relative11(root, file);
+  const rel = relative12(root, file);
   return rel ? `/${rel}` : "/";
 };
 var snippetCycleMessage = (root, file, trail) => {
@@ -9030,10 +9933,10 @@ var snippetCycleMessage = (root, file, trail) => {
   return `Circular Mintlify snippet import detected: ${cycle}`;
 };
 var resolveSnippetPath = (options) => {
-  const target = options.source.startsWith("/") ? resolve6(options.root, options.source.slice(1)) : resolve6(dirname10(options.filePath), options.source);
+  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;
 };
-var collectImports = (source) => [...source.matchAll(MARKDOWN_SNIPPET_IMPORT)].flatMap((match) => {
+var collectImports2 = (source) => [...source.matchAll(MARKDOWN_SNIPPET_IMPORT)].flatMap((match) => {
   const name = match.groups?.name;
   const importSource = match.groups?.source;
   if (!(name && importSource)) {
@@ -9081,7 +9984,7 @@ var interpolateProps = (source, props) => source.replaceAll(PLACEHOLDER, (value,
 var stripImport = (source, importText) => source.replace(importText, "").replaceAll(/\n{3,}/gu, `
 
 `);
-var replacePlaceholder = (source, name, value) => source.replaceAll(new RegExp(`\\{${escapeRegExp(name)}\\}`, "gu"), value);
+var replacePlaceholder = (source, name, value) => source.replaceAll(new RegExp(`\\{${escapeRegExp2(name)}\\}`, "gu"), value);
 var inlineSnippetTags = (options) => {
   const inline = (_value, attrs) => interpolateProps(options.snippet, parseAttributes(attrs));
   return options.source.replaceAll(snippetSelfClosingTagPattern(options.name), inline).replaceAll(snippetPairedTagPattern(options.name), inline);
@@ -9125,7 +10028,7 @@ var rewriteMintlifyMarkdownSnippets = async (source, options) => {
     });
     return next === current ? current : stripImport(next, snippetImport.importText);
   };
-  const imports = collectImports(source);
+  const imports = collectImports2(source);
   const inlineAt = async (index, current) => {
     const snippetImport = imports[index];
     if (!snippetImport) {
@@ -9224,11 +10127,11 @@ var MINTLIFY_SOURCE_IGNORES = [
   "snippets/**"
 ];
 var mintlifySource = (options) => {
-  const contentRoot = isAbsolute5(options.root) ? options.root : join18(resolve7(options.projectRoot), options.root);
+  const contentRoot = isAbsolute6(options.root) ? options.root : join18(resolve8(options.projectRoot), options.root);
   const ignore = [...new Set([...options.exclude, ...MINTLIFY_SOURCE_IGNORES])];
   const transform = (raw, file) => transformMintlifyContent(raw, {
     filePath: file,
-    root: resolve7(options.projectRoot),
+    root: resolve8(options.projectRoot),
     variables: options.variables
   });
   const load2 = async () => {
@@ -9250,7 +10153,7 @@ var mintlifySource = (options) => {
         body: { format: "mdx", text: parsed.content },
         data: parsed.data,
         raw: result.content,
-        ref: relative12(contentRoot, file),
+        ref: relative13(contentRoot, file),
         sourcePath: file
       };
     }));
@@ -9264,7 +10167,7 @@ var mintlifySource = (options) => {
     return { diagnostics, entries };
   };
   const validate = () => {
-    if (!existsSync10(contentRoot)) {
+    if (!existsSync13(contentRoot)) {
       throw new BlumeError({
         code: "BLUME_CONTENT_ROOT_MISSING",
         file: contentRoot,
@@ -9276,11 +10179,11 @@ var mintlifySource = (options) => {
   };
   const watch = (onChange) => {
     const disposers = [];
-    if (existsSync10(contentRoot)) {
+    if (existsSync13(contentRoot)) {
       const watcher = fsWatch2(contentRoot, { recursive: true }, onChange);
       disposers.push(() => watcher.close());
     }
-    if (options.configFile && existsSync10(options.configFile)) {
+    if (options.configFile && existsSync13(options.configFile)) {
       const watcher = fsWatch2(options.configFile, onChange);
       disposers.push(() => watcher.close());
     }
@@ -9312,13 +10215,13 @@ import { join as join20 } from "pathe";
 
 // src/core/sources/assets.ts
 import { mkdir as mkdir4, writeFile as writeFile5 } from "node:fs/promises";
-import { extname as extname5, join as join19 } from "pathe";
+import { extname as extname6, join as join19 } from "pathe";
 var MD_IMAGE = /!\[(?<alt>[^\]]*)\]\((?<url>[^)\s]+)\)/gu;
 var REMOTE = /^https?:\/\//u;
 var SAFE_EXT = /^\.[a-z0-9]+$/iu;
 var extFor = (url) => {
   const clean = url.split("?")[0] ?? url;
-  const ext = extname5(clean);
+  const ext = extname6(clean);
   return SAFE_EXT.test(ext) ? ext.toLowerCase() : ".png";
 };
 var materializeAssets = async (markdown, ctx) => {
@@ -9919,12 +10822,32 @@ var resolveSources = (config, context, runtime) => {
 };
 
 // src/core/project-graph.ts
+var applyConfigOverrides = (config, overrides) => {
+  if (!overrides) {
+    return config;
+  }
+  return {
+    ...config,
+    content: {
+      ...config.content,
+      root: overrides.contentRoot ?? config.content.root
+    },
+    deployment: {
+      ...config.deployment,
+      adapter: overrides.adapter ?? config.deployment.adapter,
+      base: overrides.base ?? config.deployment.base,
+      output: overrides.output ?? config.deployment.output
+    }
+  };
+};
 var scanProject = async (root, options = {}) => {
   const mode = options.mode ?? "dev";
   const preview = options.preview ?? false;
-  const { bridge, config } = await loadConfig(root, {
+  const configResult = await loadConfig(root, {
     devServerUrl: options.devServerUrl
   });
+  const { bridge } = configResult;
+  const config = applyConfigOverrides(configResult.config, options.overrides);
   const context = resolveProjectContext(root, config);
   const sources = resolveSources(config, context, {
     mode,
@@ -9943,7 +10866,7 @@ var scanProject = async (root, options = {}) => {
   for (const { source, entries, diagnostics } of loaded) {
     contentDiagnostics.push(...diagnostics);
     for (const entry of entries) {
-      const normalized = normalizeEntry(entry, {
+      const normalized = normalizeEntry2(entry, {
         defaultType: config.content.defaultType,
         i18n: config.i18n,
         source: {
@@ -9993,13 +10916,13 @@ var scanProject = async (root, options = {}) => {
 };
 
 // src/cli/env.ts
-import { existsSync as existsSync11, readFileSync as readFileSync6 } from "node:fs";
-import { dirname as dirname11, join as join23, resolve as resolve8 } from "pathe";
+import { existsSync as existsSync14, readFileSync as readFileSync8 } from "node:fs";
+import { dirname as dirname12, join as join23, 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_QUOTED = /^"(?<body>[\s\S]*)"$/u;
+var DOUBLE_QUOTED2 = /^"(?<body>[\s\S]*)"$/u;
 var SINGLE_QUOTED = /^'(?<body>[\s\S]*)'$/u;
 var unquote = (raw) => {
-  const double = raw.match(DOUBLE_QUOTED)?.groups?.body;
+  const double = raw.match(DOUBLE_QUOTED2)?.groups?.body;
   if (double !== undefined) {
     return double.replaceAll("\\n", `
 `).replaceAll("\\t", "\t").replaceAll("\\\"", '"').replaceAll("\\\\", "\\");
@@ -10032,23 +10955,81 @@ var applyEnv = (parsed) => {
 };
 var loadFile = (path) => {
   try {
-    if (existsSync11(path)) {
-      applyEnv(parseEnv(readFileSync6(path, "utf-8")));
+    if (existsSync14(path)) {
+      applyEnv(parseEnv(readFileSync8(path, "utf-8")));
     }
   } catch {}
 };
 var loadEnvFiles = (startDir) => {
-  let dir = resolve8(startDir);
+  let dir = resolve9(startDir);
   let done = false;
   while (!done) {
     loadFile(join23(dir, ".env.local"));
     loadFile(join23(dir, ".env"));
-    const parent = dirname11(dir);
-    done = existsSync11(join23(dir, ".git")) || parent === dir;
+    const parent = dirname12(dir);
+    done = existsSync14(join23(dir, ".git")) || parent === dir;
     dir = parent;
   }
 };
 
+// src/cli/internal-error.ts
+var ESC2 = String.fromCodePoint(27);
+var DIM = `${ESC2}[2m`;
+var RED = `${ESC2}[31m`;
+var BOLD = `${ESC2}[1m`;
+var RESET = `${ESC2}[0m`;
+var ISSUES_URL = "https://github.com/haydenbleasel/blume/issues";
+var BLUME_FRAME = /(?<abs>\/[^\s()]*\/\.blume\/[^\s()]*)/gu;
+var remapBlumeStack = (stack) => stack.replaceAll(BLUME_FRAME, (match) => {
+  const marker = match.indexOf("/.blume/");
+  return `${match.slice(marker + 1)} (generated)`;
+});
+var reportInternalError = (error) => {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const lines = [
+    `${RED}${BOLD}BLUME_INTERNAL${RESET} An unexpected error occurred.`,
+    `  ${err.message}`
+  ];
+  const stack = remapBlumeStack(err.stack ?? "").split(`
+`).slice(1, 5).map((line) => line.trim()).filter(Boolean);
+  if (stack.length > 0) {
+    lines.push("", `${DIM}${stack.join(`
+`)}${RESET}`);
+  }
+  lines.push("", "This is likely a bug in Blume. Please report it with the details below:", `  ${DIM}Blume:    ${getBlumeVersion()}`, `  Node:     ${process.version}`, `  Platform: ${process.platform} ${process.arch}${RESET}`, `  ${ISSUES_URL}`);
+  process.stderr.write(`${lines.join(`
+`)}
+`);
+};
+
+// src/cli/required-secrets.ts
+var checkRequiredSecrets = (config) => {
+  const diagnostics = [];
+  const requireSecret = (feature, env, note) => {
+    if (process.env[env]) {
+      return;
+    }
+    diagnostics.push({
+      code: "BLUME_MISSING_SECRET",
+      message: `${feature} is enabled but ${env} is not set${note ? ` (${note})` : ""}.`,
+      severity: "warning",
+      suggestion: `Set ${env} in .env.local for local dev, or in your host's environment for production.`
+    });
+  };
+  if (config.ai.ask?.enabled) {
+    const backend = resolveAskBackend(config.ai.ask);
+    if (backend.kind === "gateway") {
+      requireSecret("Ask AI (AI Gateway)", "AI_GATEWAY_API_KEY", "on Vercel the gateway can also authenticate via OIDC");
+    } else {
+      requireSecret("Ask AI", backend.apiKeyEnv);
+    }
+  }
+  if (config.search.provider === "mixedbread") {
+    requireSecret("Mixedbread search", "MIXEDBREAD_API_KEY");
+  }
+  return diagnostics;
+};
+
 // src/cli/prepare.ts
 var prepareProject = async (options) => {
   loadEnvFiles(options.root);
@@ -10057,15 +11038,17 @@ var prepareProject = async (options) => {
     project = await scanProject(options.root, {
       devServerUrl: options.devServerUrl,
       mode: options.mode,
+      overrides: options.overrides,
       preview: options.preview,
       refresh: options.refresh
     });
   } catch (error) {
     if (error instanceof BlumeError) {
       reportDiagnostics([error.diagnostic], options.root);
-      process.exit(1);
+    } else {
+      reportInternalError(error);
     }
-    throw error;
+    process.exit(1);
   }
   if (options.mode === "build" && project.config.deployment.output === "static") {
     const features = serverFeatures(project.config);
@@ -10093,12 +11076,102 @@ var prepareProject = async (options) => {
   for (const warning of warnings) {
     logger.warn(warning);
   }
+  reportDiagnostics(checkRequiredSecrets(project.config), options.root);
   return project;
 };
 
 // src/cli/commands/build.ts
+var ADAPTERS = ["vercel", "node", "netlify", "cloudflare"];
+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");
+  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")));
+  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)) {
+    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));
+    return { name, size: info.size };
+  }));
+  return sized.toSorted((a, b) => b.size - a.size);
+};
+var totalSize = (assets) => assets.reduce((sum, asset) => sum + asset.size, 0);
+var reportBundleSizes = async (distDir) => {
+  const sized = await astroAssets(distDir, "js");
+  if (sized.length === 0) {
+    logger.info("No client JavaScript emitted — the site ships zero JS.");
+    return;
+  }
+  const rows = sized.slice(0, 15).map((file) => `  ${formatBytes(file.size).padStart(8)}  ${file.name}`);
+  logger.box([
+    `Client JavaScript — ${sized.length} file(s), ${formatBytes(totalSize(sized))} total`,
+    "",
+    ...rows,
+    sized.length > 15 ? `  … and ${sized.length - 15} more` : null
+  ].filter((line) => line !== null).join(`
+`));
+};
+var enforceBudget = async (distDir, args) => {
+  const checks = [
+    ...args["budget-js"] ? [{ ext: "js", limitKb: Number(args["budget-js"]), name: "JavaScript" }] : [],
+    ...args["budget-css"] ? [{ ext: "css", limitKb: Number(args["budget-css"]), name: "CSS" }] : []
+  ];
+  if (checks.length === 0) {
+    return "skip";
+  }
+  let passed = true;
+  for (const check of checks) {
+    const total = totalSize(await astroAssets(distDir, check.ext));
+    const limit = check.limitKb * 1024;
+    if (total > limit) {
+      passed = false;
+      logger.error(`${check.name} budget exceeded: ${formatBytes(total)} > ${check.limitKb} kB`);
+    } else {
+      logger.success(`${check.name} budget: ${formatBytes(total)} / ${check.limitKb} kB`);
+    }
+  }
+  return passed ? "pass" : "fail";
+};
 var buildCommand = defineCommand2({
   args: {
+    adapter: {
+      description: "Server adapter: vercel | node | netlify | cloudflare.",
+      type: "string"
+    },
+    analyze: {
+      description: "Report client JavaScript bundle sizes after the build.",
+      type: "boolean"
+    },
+    base: {
+      description: "Base path the site is served under (e.g. /docs).",
+      type: "string"
+    },
+    "budget-css": {
+      description: "Fail if total client CSS exceeds this many kB.",
+      type: "string"
+    },
+    "budget-js": {
+      description: "Fail if total client JavaScript exceeds this many kB.",
+      type: "string"
+    },
+    output: {
+      description: "Output mode: static | server.",
+      type: "string"
+    },
     preview: {
       description: "Include drafts and unpublished CMS content.",
       type: "boolean"
@@ -10111,8 +11184,21 @@ var buildCommand = defineCommand2({
   },
   async run({ args }) {
     const root = process.cwd();
+    if (args.output && args.output !== "static" && args.output !== "server") {
+      logger.error(`Invalid --output "${args.output}" (use static | server).`);
+      process.exit(1);
+    }
+    if (args.adapter && !ADAPTERS.includes(args.adapter)) {
+      logger.error(`Invalid --adapter "${args.adapter}" (use ${ADAPTERS.join(" | ")}).`);
+      process.exit(1);
+    }
     const project = await prepareProject({
       mode: "build",
+      overrides: {
+        adapter: args.adapter,
+        base: args.base,
+        output: args.output
+      },
       preview: args.preview,
       root,
       strict: args.strict
@@ -10142,15 +11228,16 @@ var buildCommand = defineCommand2({
       logger.success("Generated llms.txt and llms-full.txt");
     }
     const sitemap = buildSitemap(project);
-    if (sitemap && !existsSync12(join24(distDir, "sitemap.xml"))) {
+    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 && !existsSync12(join24(distDir, "robots.txt"))) {
+    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([
@@ -10165,16 +11252,113 @@ var buildCommand = defineCommand2({
       `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}`);
   }
 });
 
+// src/cli/commands/check.ts
+import { existsSync as existsSync16 } from "node:fs";
+import { check } from "@astrojs/check";
+import { sync } from "astro";
+import { defineCommand as defineCommand3 } from "citty";
+import { join as join25 } from "pathe";
+var checkCommand = defineCommand3({
+  args: {
+    preview: {
+      description: "Include drafts and unpublished CMS content.",
+      type: "boolean"
+    },
+    strict: {
+      description: "Fail on content diagnostics as well as type errors.",
+      type: "boolean"
+    }
+  },
+  meta: {
+    description: "Type-check the docs site with astro check.",
+    name: "check"
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const project = await prepareProject({
+      mode: "build",
+      preview: args.preview,
+      root,
+      strict: args.strict
+    });
+    const { outDir } = project.context;
+    await sync({ logLevel: "warn", root: outDir });
+    const tsconfig = join25(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,
+      watch: false
+    });
+    if (failed) {
+      logger.error("Type check failed.");
+      process.exit(1);
+    }
+    logger.success("No type errors.");
+  }
+});
+
 // src/cli/commands/dev.ts
 import { watch } from "node:fs";
 import { dev } from "astro";
-import { defineCommand as defineCommand3 } from "citty";
-var devCommand = defineCommand3({
+import { defineCommand as defineCommand4 } from "citty";
+
+// src/astro/integration.ts
+var overlayServer = null;
+var overlayChannel = () => overlayServer?.ws ?? overlayServer?.hot;
+var showBlumeErrorOverlay = (diagnostics) => {
+  const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").map(enrichDiagnostic);
+  const channel = overlayChannel();
+  if (errors.length === 0 || !channel) {
+    return;
+  }
+  const body = errors.map((diagnostic) => {
+    const where = diagnostic.file ? `
+  at ${diagnostic.file}${diagnostic.line ? `:${diagnostic.line}` : ""}` : "";
+    const fix = diagnostic.suggestion ? `
+  fix: ${diagnostic.suggestion}` : "";
+    const docs = diagnostic.docsUrl ? `
+  docs: ${diagnostic.docsUrl}` : "";
+    return `[${diagnostic.code}] ${diagnostic.message}${where}${fix}${docs}`;
+  }).join(`
+
+`);
+  channel.send({
+    err: {
+      id: errors[0]?.file,
+      message: `Blume found ${errors.length} error(s):
+
+${body}`,
+      plugin: "blume",
+      stack: ""
+    },
+    type: "error"
+  });
+};
+
+// src/cli/commands/dev.ts
+var devCommand = defineCommand4({
   args: {
+    "content-dir": {
+      description: "Content folder to scan, overriding config (content.root).",
+      type: "string"
+    },
+    debug: {
+      description: "Verbose Astro/Vite logging for troubleshooting.",
+      type: "boolean"
+    },
     host: { description: "Network host to bind.", type: "string" },
     open: { description: "Open the browser on start.", type: "boolean" },
     port: { description: "Port to listen on.", type: "string" },
@@ -10191,11 +11375,13 @@ var devCommand = defineCommand3({
   async run({ args }) {
     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 devServerUrl = `http://localhost:${port}`;
     const project = await prepareProject({
       devServerUrl,
       mode: "dev",
+      overrides,
       preview,
       root,
       strict: args.strict
@@ -10204,7 +11390,7 @@ var devCommand = defineCommand3({
       logger.info('Detected docs.json — running in Mintlify bridge mode (no migration). Run "blume migrate mintlify" to convert permanently.');
     }
     const server = await dev({
-      logLevel: "info",
+      logLevel: args.debug ? "debug" : "info",
       root: project.context.outDir,
       server: {
         host: args.host ?? false,
@@ -10212,6 +11398,7 @@ var devCommand = defineCommand3({
         port: args.port ? Number(args.port) : undefined
       }
     });
+    showBlumeErrorOverlay(project.diagnostics);
     let timer = null;
     const regenerate = () => {
       if (timer) {
@@ -10222,9 +11409,11 @@ var devCommand = defineCommand3({
           const next = await scanProject(root, {
             devServerUrl,
             mode: "dev",
+            overrides,
             preview
           });
           await generateRuntime(next);
+          showBlumeErrorOverlay(next.diagnostics);
         } catch (error) {
           logger.error(`Regeneration failed: ${error.message}`);
         }
@@ -10256,14 +11445,20 @@ var devCommand = defineCommand3({
 });
 
 // src/cli/commands/doctor.ts
-import { defineCommand as defineCommand4 } from "citty";
+import { defineCommand as defineCommand5 } from "citty";
 var MIN_NODE_MAJOR = 20;
-var doctorCommand = defineCommand4({
+var doctorCommand = defineCommand5({
+  args: {
+    json: {
+      description: "Emit diagnostics as JSON on stdout (for CI/editors).",
+      type: "boolean"
+    }
+  },
   meta: {
     description: "Diagnose common configuration and content problems.",
     name: "doctor"
   },
-  async run() {
+  async run({ args }) {
     const root = process.cwd();
     const diagnostics = [];
     const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
@@ -10295,15 +11490,24 @@ var doctorCommand = defineCommand4({
           suggestion: 'Set deployment.adapter (e.g. "vercel").'
         });
       }
-      logger.info(`Pages: ${project.graph.pages.length}`);
-      logger.info(`Output: ${config.deployment.output}`);
-      logger.info(`Search: ${config.search.provider}`);
+      if (!args.json) {
+        logger.info(`Pages: ${project.graph.pages.length}`);
+        logger.info(`Output: ${config.deployment.output}`);
+        logger.info(`Search: ${config.search.provider}`);
+      }
     } catch (error) {
       if (error instanceof BlumeError) {
         diagnostics.push(error.diagnostic);
       } else {
-        throw error;
+        reportInternalError(error);
+        process.exit(1);
+      }
+    }
+    if (args.json) {
+      if (reportDiagnosticsJson(diagnostics, root)) {
+        process.exit(1);
       }
+      return;
     }
     const hadErrors = reportDiagnostics(diagnostics, root);
     if (diagnostics.length === 0) {
@@ -10317,19 +11521,40 @@ var doctorCommand = defineCommand4({
 
 // src/cli/commands/eject.ts
 import { readFile as readFile15, writeFile as writeFile8 } from "node:fs/promises";
-import { defineCommand as defineCommand5 } from "citty";
-import { join as join26, relative as relative14 } from "pathe";
+import { defineCommand as defineCommand6 } from "citty";
+import { join as join27, relative as relative15 } from "pathe";
 
 // src/registry/eject.ts
-import { existsSync as existsSync13 } from "node:fs";
+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 join25, relative as relative13 } from "pathe";
+import { join as join26, relative as relative14 } from "pathe";
 var POSIX = (path) => path.split("\\").join("/");
+var askFiles = async (project, srcDir, genDir) => {
+  const { ask } = project.config.ai;
+  if (!ask?.enabled) {
+    return [];
+  }
+  const grounded = ask.provider !== "inkeep";
+  const files = [
+    {
+      content: askEndpointTemplate(resolveAskBackend(ask), grounded),
+      path: join26(srcDir, "pages", "api", "ask.ts")
+    }
+  ];
+  if (grounded) {
+    files.push({
+      content: `${JSON.stringify(await buildAskData(project))}
+`,
+      path: join26(genDir, "ask-data.json")
+    });
+  }
+  return files;
+};
 var eject = async (root) => {
   const project = await scanProject(root, { mode: "build" });
   const { context, config } = project;
-  const srcDir = join25(root, "src");
-  const genDir = join25(srcDir, "generated");
+  const srcDir = join26(root, "src");
+  const genDir = join26(srcDir, "generated");
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
@@ -10350,13 +11575,13 @@ var eject = async (root) => {
   const needsSvelte = frameworks.has("svelte");
   const relContext = {
     ...context,
-    contentRoot: POSIX(relative13(root, context.contentRoot)),
+    contentRoot: POSIX(relative14(root, context.contentRoot)),
     outDir: ".",
     root: "."
   };
-  const componentsImport = context.componentsFile ? `../../${POSIX(relative13(root, context.componentsFile))}` : null;
+  const componentsImport = context.componentsFile ? `../../${POSIX(relative14(root, context.componentsFile))}` : null;
   const relPages = pages.map((page) => ({
-    entrypoint: POSIX(relative13(root, page.entrypoint)),
+    entrypoint: POSIX(relative14(root, page.entrypoint)),
     pattern: page.pattern
   }));
   const staged = collectStaged(project);
@@ -10377,13 +11602,13 @@ var eject = async (root) => {
         searchClientPath: "./src/generated/search-client.ts",
         themePath: "./src/generated/app.css"
       }),
-      path: join25(root, "astro.config.mjs")
+      path: join26(root, "astro.config.mjs")
     },
     {
       content: runtimeTsconfigTemplate(),
-      path: join25(root, "tsconfig.json")
+      path: join26(root, "tsconfig.json")
     },
-    { content: envTemplate(), path: join25(srcDir, "env.d.ts") },
+    { content: envTemplate(), path: join26(srcDir, "env.d.ts") },
     {
       content: contentConfigTemplate({
         config,
@@ -10391,28 +11616,29 @@ var eject = async (root) => {
         staged: hasStaged,
         stagedBase: stagedDir
       }),
-      path: join25(srcDir, "content.config.ts")
+      path: join26(srcDir, "content.config.ts")
     },
     {
       content: catchAllPageTemplate({
         askEnabled,
         exportEpub,
         exportPdf,
-        mathEnabled: config.markdown.math
+        mathEnabled: config.markdown.math,
+        needsReact
       }),
-      path: join25(srcDir, "pages", "[...slug].astro")
+      path: join26(srcDir, "pages", "[...slug].astro")
     },
     {
-      content: userComponentsTemplate(componentsImport),
-      path: join25(genDir, "components.ts")
+      content: planComponentSlots(componentsImport, null).module,
+      path: join26(genDir, "components.ts")
     },
     {
       content: islandMapTemplate(islands.islands),
-      path: join25(genDir, "islands.ts")
+      path: join26(genDir, "islands.ts")
     },
     {
       content: exampleMapTemplate(examples.examples),
-      path: join25(genDir, "examples.ts")
+      path: join26(genDir, "examples.ts")
     },
     {
       content: tailwindEntryTemplate({
@@ -10424,60 +11650,57 @@ var eject = async (root) => {
         twoslashCss: twoslashCss(),
         userTheme
       }),
-      path: join25(genDir, "app.css")
+      path: join26(genDir, "app.css")
     },
-    { content: buildRuntimeData(project), path: join25(genDir, "data.json") },
+    { content: buildRuntimeData(project), path: join26(genDir, "data.json") },
     {
       content: `${JSON.stringify(rawMarkdown)}
 `,
-      path: join25(genDir, "raw-markdown.json")
+      path: join26(genDir, "raw-markdown.json")
     },
     {
       content: rawMarkdownEndpointTemplate(),
-      path: join25(srcDir, "pages", "[...slug].md.ts")
+      path: join26(srcDir, "pages", "[...slug].md.ts")
     },
     {
       content: rawMarkdownEndpointTemplate(),
-      path: join25(srcDir, "pages", "[...slug].mdx.ts")
+      path: join26(srcDir, "pages", "[...slug].mdx.ts")
     }
   ];
   if (askEnabled) {
-    files.push({
-      content: askEndpointTemplate(resolveAskBackend(config.ai.ask)),
-      path: join25(srcDir, "pages", "api", "ask.ts")
-    });
+    files.push(...await askFiles(project, srcDir, genDir));
   }
   if (config.seo.og.enabled) {
     files.push({
-      content: ogEndpointTemplate(customOgRoutes(pages, config.title, config.description)),
-      path: join25(srcDir, "pages", "og", "[...slug].png.ts")
+      content: ogEndpointTemplate(customOgRoutes(pages, config.title)),
+      path: join26(srcDir, "pages", "og", "[...slug].png.ts")
     });
   }
   if (!routeIsTaken(pages, project.graph.pages, "/404")) {
     files.push({
       content: notFoundPageTemplate(),
-      path: join25(srcDir, "pages", "404.astro")
+      path: join26(srcDir, "pages", "404.astro")
     });
   }
   files.push({
     content: searchClientTemplate(config),
-    path: join25(genDir, "search-client.ts")
+    path: join26(genDir, "search-client.ts")
   });
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);
     files.push({
       content: `${JSON.stringify(documents)}
 `,
-      path: join25(genDir, "search.json")
+      path: join26(genDir, "search.json")
     }, {
       content: searchEndpointTemplate(),
-      path: join25(srcDir, "pages", "blume-search.json.ts")
+      path: join26(srcDir, "pages", "blume-search.json.ts")
     });
   }
   if (config.search.provider === "mixedbread") {
     files.push({
       content: mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? ""),
-      path: join25(srcDir, "pages", "api", "search.ts")
+      path: join26(srcDir, "pages", "api", "search.ts")
     });
   }
   const feeds = buildRssFeeds(project);
@@ -10486,10 +11709,10 @@ var eject = async (root) => {
     files.push({
       content: `${JSON.stringify(feedXml)}
 `,
-      path: join25(genDir, "rss.json")
+      path: join26(genDir, "rss.json")
     }, {
       content: rssEndpointTemplate(),
-      path: join25(srcDir, "pages", "[section]", "rss.xml.ts")
+      path: join26(srcDir, "pages", "[section]", "rss.xml.ts")
     });
   }
   if (hasReferences(config)) {
@@ -10501,27 +11724,27 @@ var eject = async (root) => {
     for (const file of references.files) {
       files.push({
         content: file.content,
-        path: join25(srcDir, "pages", file.pagePath)
+        path: join26(srcDir, "pages", file.pagePath)
       });
     }
   }
   files.push(...islands.islands.map((island) => ({
     content: islandWrapperTemplate(island),
-    path: join25(genDir, "islands", `${island.name}.astro`)
+    path: join26(genDir, "islands", `${island.name}.astro`)
   })), ...examples.examples.map((example) => ({
     content: exampleWrapperTemplate(example),
-    path: join25(genDir, "examples", `${exampleSlug(example.path)}.astro`)
+    path: join26(genDir, "examples", `${exampleSlug(example.path)}.astro`)
   })));
   for (const [entryId, content] of staged) {
-    files.push({ content, path: join25(root, stagedDir, entryId) });
+    files.push({ content, path: join26(root, stagedDir, entryId) });
   }
   await Promise.all(files.map(async (file) => {
-    await mkdir5(join25(file.path, ".."), { recursive: true });
+    await mkdir5(join26(file.path, ".."), { recursive: true });
     await writeFile7(file.path, file.content, "utf-8");
   }));
-  const assetsSrc = join25(context.outDir, "public", "blume-assets");
-  if (existsSync13(assetsSrc)) {
-    await cp(assetsSrc, join25(root, "public", "blume-assets"), {
+  const assetsSrc = join26(context.outDir, "public", "blume-assets");
+  if (existsSync17(assetsSrc)) {
+    await cp(assetsSrc, join26(root, "public", "blume-assets"), {
       recursive: true
     });
   }
@@ -10531,7 +11754,7 @@ var eject = async (root) => {
 
 // src/cli/commands/eject.ts
 var updatePackageScripts = async (root) => {
-  const pkgPath = join26(root, "package.json");
+  const pkgPath = join27(root, "package.json");
   let pkg;
   try {
     pkg = JSON.parse(await readFile15(pkgPath, "utf-8"));
@@ -10548,7 +11771,7 @@ var updatePackageScripts = async (root) => {
   await writeFile8(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `, "utf-8");
 };
-var ejectCommand = defineCommand5({
+var ejectCommand = defineCommand6({
   args: {
     yes: { description: "Skip the confirmation prompt.", type: "boolean" }
   },
@@ -10567,7 +11790,7 @@ var ejectCommand = defineCommand5({
     await updatePackageScripts(root);
     logger.success(`Ejected ${files.length} file(s):`);
     for (const file of files) {
-      process.stdout.write(`  ${relative14(root, file)}
+      process.stdout.write(`  ${relative15(root, file)}
 `);
     }
     logger.box(`Your project is now a standalone Astro app.
@@ -10580,10 +11803,10 @@ The blume package remains importable.`);
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync14 } from "node:fs";
+import { existsSync as existsSync18 } from "node:fs";
 import { mkdir as mkdir6, writeFile as writeFile9 } from "node:fs/promises";
-import { defineCommand as defineCommand6 } from "citty";
-import { basename as basename4, dirname as dirname12, join as join27 } from "pathe";
+import { defineCommand as defineCommand7 } from "citty";
+import { basename as basename4, dirname as dirname13, join as join28 } from "pathe";
 var toPackageName = (raw) => raw.toLowerCase().replaceAll(/[^a-z0-9._-]+/gu, "-").replaceAll(/^[-_.]+|[-_.]+$/gu, "") || "docs";
 var packageTemplate = (name, version) => `{
   "name": ${JSON.stringify(name)},
@@ -10599,41 +11822,130 @@ var packageTemplate = (name, version) => `{
   }
 }
 `;
-var CONFIG_TEMPLATE = `import { defineConfig } from "blume";
+var TEMPLATES = ["docs", "api", "sdk", "changelog"];
+var PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
+var configFor = (extra) => `import { defineConfig } from "blume";
 
 export default defineConfig({
   title: "My Docs",
-  description: "Documentation powered by Blume.",
+  description: "Documentation powered by Blume.",${extra}
 });
 `;
-var INDEX_TEMPLATE = `---
-title: Introduction
-description: Welcome to your new Blume docs.
+var page = (title, description, body) => `---
+title: ${title}
+description: ${description}
+---
+
+${body}
+`;
+var STARTERS = {
+  api: {
+    config: configFor(`
+  openapi: {
+    enabled: true,
+    route: "/api",
+    sources: [
+      {
+        label: "Petstore",
+        spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+      },
+    ],
+  },`),
+    files: (dir) => [
+      {
+        content: page("API Reference", "Explore the API.", "# API Reference\n\nYour OpenAPI spec renders at [`/api`](/api). Point `openapi.sources` at your own spec in `blume.config.ts`."),
+        path: join28(dir, "index.mdx")
+      }
+    ]
+  },
+  changelog: {
+    config: configFor(`
+  navigation: {
+    tabs: [
+      { label: "Docs", path: "/" },
+      { label: "Changelog", path: "/changelog" },
+    ],
+  },`),
+    files: (dir) => [
+      {
+        content: page("Introduction", "Welcome to your new Blume docs.", "# Introduction\n\nWrite your docs here, and log releases under `changelog/`."),
+        path: join28(dir, "index.mdx")
+      },
+      {
+        content: `---
+title: v1.0.0
+type: changelog
+date: 2026-01-01
 ---
 
-# Introduction
+The first release. Edit \`${dir}/changelog/v1-0-0.mdx\` or add new entries beside it.
+`,
+        path: join28(dir, "changelog", "v1-0-0.mdx")
+      }
+    ]
+  },
+  docs: {
+    config: configFor(""),
+    files: (dir) => [
+      {
+        content: page("Introduction", "Welcome to your new Blume docs.", `# Introduction
 
 Welcome to **Blume** — markdown-first docs powered by Astro and Vite.
 
-Edit \`docs/index.mdx\` to get started, then run \`blume dev\`.
-`;
+Edit \`${dir}/index.mdx\` to get started, then run \`blume dev\`.`),
+        path: join28(dir, "index.mdx")
+      }
+    ]
+  },
+  sdk: {
+    config: configFor(""),
+    files: (dir) => [
+      {
+        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")
+      },
+      {
+        content: page("Installation", "Install the SDK.", "# Installation\n\n```package-install\nyour-sdk\n```"),
+        path: join28(dir, "installation.mdx")
+      }
+    ]
+  }
+};
+var commandsFor = (pm) => ({
+  dev: pm === "npm" ? "npm run dev" : `${pm} dev`,
+  install: `${pm} install`
+});
 var writeFileSafe = async (path, content) => {
-  if (existsSync14(path)) {
+  if (existsSync18(path)) {
     logger.info(`Skipped existing ${path}`);
     return false;
   }
-  await mkdir6(dirname12(path), { recursive: true });
+  await mkdir6(dirname13(path), { recursive: true });
   await writeFile9(path, content, "utf-8");
   logger.success(`Created ${path}`);
   return true;
 };
-var initCommand = defineCommand6({
+var initCommand = defineCommand7({
   args: {
     "content-dir": {
       default: "docs",
       description: "Content directory.",
       type: "string"
     },
+    eject: {
+      description: "Eject to a standalone Astro project after scaffolding.",
+      type: "boolean"
+    },
+    "package-manager": {
+      description: "Package manager for the next-steps hint (npm|pnpm|yarn|bun).",
+      type: "string"
+    },
+    template: {
+      description: "Starter template: docs | api | sdk | changelog.",
+      type: "string"
+    },
     yes: { description: "Skip prompts.", type: "boolean" }
   },
   meta: {
@@ -10643,34 +11955,65 @@ var initCommand = defineCommand6({
   async run({ args }) {
     const root = process.cwd();
     const contentDir = args["content-dir"] ?? "docs";
-    const createdPackage = await writeFileSafe(join27(root, "package.json"), packageTemplate(toPackageName(basename4(root)), getBlumeVersion()));
-    await writeFileSafe(join27(root, "blume.config.ts"), CONFIG_TEMPLATE);
-    await writeFileSafe(join27(root, contentDir, "index.mdx"), INDEX_TEMPLATE);
+    const template = args.template ?? "docs";
+    if (!TEMPLATES.includes(template)) {
+      logger.error(`Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`);
+      process.exit(1);
+    }
+    const pm = args["package-manager"] ?? "npm";
+    if (!PACKAGE_MANAGERS.includes(pm)) {
+      logger.error(`Unknown package manager "${args["package-manager"]}" (use ${PACKAGE_MANAGERS.join(" | ")}).`);
+      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 commands = commandsFor(pm);
+    if (args.eject) {
+      try {
+        await eject(root);
+        logger.success("Ejected to a standalone Astro project.");
+        logger.box(`Next steps:
+
+  ${commands.install}
+  npx astro dev
+`);
+      } catch (error) {
+        logger.warn(`Scaffolded, but eject failed: ${error.message}`);
+        logger.box(`Next steps:
+
+  ${commands.install}
+  blume eject --yes
+`);
+      }
+      return;
+    }
     const nextSteps = createdPackage ? `Next steps:
 
-  npm install
-  blume dev
+  ${commands.install}
+  ${commands.dev}
 ` : `Next steps:
 
-  blume dev
+  ${commands.dev}
 `;
     logger.box(nextSteps);
   }
 });
 
 // src/cli/commands/migrate.ts
-import { defineCommand as defineCommand7 } from "citty";
+import { defineCommand as defineCommand8 } from "citty";
 
 // src/migrate/fumadocs/index.ts
-import { existsSync as existsSync18 } from "node:fs";
+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 dirname15, join as join30, relative as relative15 } from "pathe";
+import { dirname as dirname16, join as join31, relative as relative16 } from "pathe";
 import { glob as glob8 } from "tinyglobby";
 
 // src/migrate/fumadocs/config.ts
-import { existsSync as existsSync15 } from "node:fs";
+import { existsSync as existsSync19 } from "node:fs";
 import { readFile as readFile16 } from "node:fs/promises";
-import { basename as basename5, dirname as dirname13, join as join28 } from "pathe";
+import { basename as basename5, dirname as dirname14, join as join29 } from "pathe";
 var SOURCE_FILES = [
   "lib/source.ts",
   "app/source.ts",
@@ -10700,10 +12043,10 @@ var GENERIC_NAMES = new Set([
 var gitRepoRoot = (start) => {
   let dir = start;
   for (;; ) {
-    if (existsSync15(join28(dir, ".git"))) {
+    if (existsSync19(join29(dir, ".git"))) {
       return dir;
     }
-    const parent = dirname13(dir);
+    const parent = dirname14(dir);
     if (parent === dir) {
       return null;
     }
@@ -10712,8 +12055,8 @@ var gitRepoRoot = (start) => {
 };
 var bareName = (name) => name.includes("/") ? name.slice(name.lastIndexOf("/") + 1) : name;
 var readTitle = async (root) => {
-  const packageJson = join28(root, "package.json");
-  if (!existsSync15(packageJson)) {
+  const packageJson = join29(root, "package.json");
+  if (!existsSync19(packageJson)) {
     return "Documentation";
   }
   try {
@@ -10738,8 +12081,8 @@ var readTitle = async (root) => {
 };
 var scrapeBaseUrl = async (root) => {
   for (const candidate of SOURCE_FILES) {
-    const file = join28(root, candidate);
-    if (!existsSync15(file)) {
+    const file = join29(root, candidate);
+    if (!existsSync19(file)) {
       continue;
     }
     const base = BASE_URL.exec(await readFile16(file, "utf-8"))?.groups?.base;
@@ -10771,9 +12114,9 @@ var loadFumadocsConfig = async (root) => {
 };
 
 // src/migrate/fumadocs/content.ts
-import { existsSync as existsSync16 } from "node:fs";
+import { existsSync as existsSync20 } from "node:fs";
 import { readFile as readFileFromDisk2 } from "node:fs/promises";
-import { dirname as dirname14, resolve as resolve9 } from "pathe";
+import { dirname as dirname15, resolve as resolve10 } 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, "");
@@ -10974,12 +12317,12 @@ var inlineFumadocsIncludes = async (source, options) => {
     if (!rawPath) {
       continue;
     }
-    const target = resolve9(dirname14(options.filePath), rawPath);
+    const target = resolve10(dirname15(options.filePath), rawPath);
     if (seen.has(target)) {
       warnings.push(`Circular <include> "${rawPath}" — left as-is.`);
       continue;
     }
-    if (!existsSync16(target)) {
+    if (!existsSync20(target)) {
       warnings.push(`<include> target "${rawPath}" not found — left as-is.`);
       continue;
     }
@@ -11011,9 +12354,9 @@ var normalizeFumadocsPageMeta = (value) => {
 };
 
 // src/migrate/fumadocs/groups.ts
-import { existsSync as existsSync17, statSync as statSync2 } from "node:fs";
+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 join29 } from "pathe";
+import { basename as basename6, join as join30 } from "pathe";
 
 // src/migrate/fumadocs/meta.ts
 var SEPARATOR = /^---(?<label>.*)---$/u;
@@ -11159,12 +12502,12 @@ var isDirectory = (path) => {
 };
 var resolveEntry = (docsDir, name) => {
   for (const ext of PAGE_EXTS) {
-    const file = join29(docsDir, `${name}${ext}`);
-    if (existsSync17(file)) {
+    const file = join30(docsDir, `${name}${ext}`);
+    if (existsSync21(file)) {
       return { kind: "file", path: file };
     }
   }
-  const folder = join29(docsDir, name);
+  const folder = join30(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(" ");
@@ -11199,8 +12542,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 = join29(groupDir, basename6(resolved.path));
-  if (existsSync17(dest)) {
+  const dest = join30(groupDir, basename6(resolved.path));
+  if (existsSync21(dest)) {
     warnings.push(`Skipped moving "${item.name}" into section "${label}" (target already exists).`);
     return null;
   }
@@ -11227,7 +12570,7 @@ var reshapeSection = async (section, docsDir, order, warnings) => {
     }
     return;
   }
-  const groupDir = join29(docsDir, `(${section.label})`);
+  const groupDir = join30(docsDir, `(${section.label})`);
   const sectionKeys = [];
   for (const item of section.items) {
     const key = await moveItemIntoGroup(item, docsDir, groupDir, section.label, warnings);
@@ -11240,7 +12583,7 @@ var reshapeSection = async (section, docsDir, order, warnings) => {
   }
   order.push(section.label);
   if (sectionKeys.length > 1) {
-    await writeFile10(join29(groupDir, "meta.ts"), renderMetaModule({ pages: sectionKeys }), "utf-8");
+    await writeFile10(join30(groupDir, "meta.ts"), renderMetaModule({ pages: sectionKeys }), "utf-8");
   }
 };
 var reshapeFumadocsGroups = async (structure, docsDir) => {
@@ -11272,9 +12615,9 @@ var FUMADOCS_LEFTOVERS = [
   "app"
 ];
 var movePage = async (abs, base, root) => {
-  const rel = relative15(base, abs);
-  const dest = join30(root, "docs", rel);
-  if (existsSync18(dest)) {
+  const rel = relative16(base, abs);
+  const dest = join31(root, "docs", rel);
+  if (existsSync22(dest)) {
     return {
       includeWarnings: [],
       moved: 0,
@@ -11293,7 +12636,7 @@ var movePage = async (abs, base, root) => {
   const parsed = frontmatter_default(text);
   const { data, removed } = normalizeFumadocsPageMeta(parsed.data);
   const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
-  await mkdir8(dirname15(dest), { recursive: true });
+  await mkdir8(dirname16(dest), { recursive: true });
   await writeFile11(dest, content, "utf-8");
   await rm3(abs, { force: true });
   return {
@@ -11308,35 +12651,35 @@ var writeMeta = async (dest, meta, rel, warnings) => {
   if (Object.keys(meta).length === 0) {
     return warnings;
   }
-  if (existsSync18(dest)) {
+  if (existsSync22(dest)) {
     return [...warnings, `Skipped ${rel} (target already exists)`];
   }
-  await mkdir8(dirname15(dest), { recursive: true });
+  await mkdir8(dirname16(dest), { recursive: true });
   await writeFile11(dest, renderMetaModule(meta), "utf-8");
   return warnings;
 };
 var convertMeta = async (abs, base, root) => {
-  const rel = relative15(base, abs);
+  const rel = relative16(base, abs);
   const raw = await readFile17(abs, "utf-8");
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch {
-    const dest2 = join30(root, "docs", rel);
-    if (existsSync18(dest2)) {
+    const dest2 = join31(root, "docs", rel);
+    if (existsSync22(dest2)) {
       return [`Skipped ${rel} (target already exists)`];
     }
-    await mkdir8(dirname15(dest2), { recursive: true });
+    await mkdir8(dirname16(dest2), { recursive: true });
     await rename3(abs, dest2);
     return [
       `Could not parse ${rel}; moved as-is — convert it to meta.ts by hand.`
     ];
   }
-  const dir = dirname15(rel) === "." ? "" : dirname15(rel);
-  const docsDir = join30(root, "docs", dir);
-  const dest = join30(docsDir, "meta.ts");
+  const dir = dirname16(rel) === "." ? "" : dirname16(rel);
+  const docsDir = join31(root, "docs", dir);
+  const dest = join31(docsDir, "meta.ts");
   const structure = parseFumadocsPages(parsed.pages);
-  if (structure.hasSections && !existsSync18(dest)) {
+  if (structure.hasSections && !existsSync22(dest)) {
     const self = translateFumadocsSelfMeta(parsed);
     const reshape = await reshapeFumadocsGroups(structure, docsDir);
     const meta2 = { ...self.meta };
@@ -11383,8 +12726,8 @@ var summarizePages = (results) => {
   };
 };
 var cleanupSourceDirs = async (root) => {
-  const docs = join30(root, "content", "docs");
-  if (existsSync18(docs)) {
+  const docs = join31(root, "content", "docs");
+  if (existsSync22(docs)) {
     const remaining = await glob8(["**/*"], { cwd: docs, dot: true });
     if (remaining.length > 0) {
       return [
@@ -11393,8 +12736,8 @@ var cleanupSourceDirs = async (root) => {
     }
     await rm3(docs, { force: true, recursive: true });
   }
-  const content = join30(root, "content");
-  if (existsSync18(content)) {
+  const content = join31(root, "content");
+  if (existsSync22(content)) {
     const remaining = await glob8(["**/*"], { cwd: content, dot: true });
     if (remaining.length === 0) {
       await rm3(content, { force: true, recursive: true });
@@ -11404,8 +12747,8 @@ var cleanupSourceDirs = async (root) => {
 };
 var migrateFumadocsProject = async (root) => {
   const { config, warnings: configWarnings } = await loadFumadocsConfig(root);
-  const base = join30(root, SOURCE_DIR);
-  if (!existsSync18(base)) {
+  const base = join31(root, SOURCE_DIR);
+  if (!existsSync22(base)) {
     await writeBlumeConfig(root, config);
     return {
       moved: 0,
@@ -11463,9 +12806,9 @@ var migrateFumadocsProject = async (root) => {
 };
 
 // src/migrate/mintlify/index.ts
-import { existsSync as existsSync19 } from "node:fs";
+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 dirname16, join as join31 } from "pathe";
+import { dirname as dirname17, join as join32 } from "pathe";
 import { glob as glob9 } from "tinyglobby";
 var prune = (value) => {
   if (Array.isArray(value)) {
@@ -11495,7 +12838,7 @@ var writeBlumeConfig2 = async (root, config) => {
 
 export default defineConfig(${JSON.stringify(prune(config), null, 2)});
 `;
-  await writeFile12(join31(root, "blume.config.ts"), body, "utf-8");
+  await writeFile12(join32(root, "blume.config.ts"), body, "utf-8");
 };
 var relocateAssets = async (root, refs) => {
   const segments = new Set;
@@ -11510,23 +12853,23 @@ var relocateAssets = async (root, refs) => {
   }
   const moved = [];
   for (const segment of segments) {
-    const source = join31(root, segment);
-    if (!existsSync19(source) || segment === "public") {
+    const source = join32(root, segment);
+    if (!existsSync23(source) || segment === "public") {
       continue;
     }
-    const dest = join31(root, "public", segment);
-    if (existsSync19(dest)) {
+    const dest = join32(root, "public", segment);
+    if (existsSync23(dest)) {
       continue;
     }
-    await mkdir9(join31(root, "public"), { recursive: true });
+    await mkdir9(join32(root, "public"), { recursive: true });
     await rename4(source, dest);
     moved.push(segment);
   }
   return moved;
 };
 var cleanupSnippets = async (root, kept, warnings) => {
-  const dir = join31(root, "snippets");
-  if (!existsSync19(dir)) {
+  const dir = join32(root, "snippets");
+  if (!existsSync23(dir)) {
     return;
   }
   const markdown = await glob9(["**/*.{md,mdx}"], { absolute: true, cwd: dir });
@@ -11563,9 +12906,9 @@ var assetRefs = (config) => {
 };
 var migrateMintlifyProject = async (root) => {
   const warnings = [];
-  const configFile = existsSync19(join31(root, "docs.json")) ? join31(root, "docs.json") : join31(root, "mint.json");
+  const configFile = existsSync23(join32(root, "docs.json")) ? join32(root, "docs.json") : join32(root, "mint.json");
   let config;
-  if (existsSync19(configFile)) {
+  if (existsSync23(configFile)) {
     config = await loadMintlifyConfig(root, configFile);
     const spec = JSON.parse(await readFile18(configFile, "utf-8"));
     const i18n = mintlifyI18n(spec);
@@ -11605,7 +12948,7 @@ var migrateMintlifyProject = async (root) => {
       variables
     });
     if (result.content !== raw) {
-      await mkdir9(dirname16(file), { recursive: true });
+      await mkdir9(dirname17(file), { recursive: true });
       await writeFile12(file, result.content, "utf-8");
     }
     for (const key of result.removed) {
@@ -11642,9 +12985,9 @@ var migrateMintlifyProject = async (root) => {
 };
 
 // src/migrate/nextra/index.ts
-import { existsSync as existsSync20 } from "node:fs";
+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 dirname17, extname as extname6, join as join32, relative as relative16 } from "pathe";
+import { basename as basename7, dirname as dirname18, extname as extname7, join as join33, relative as relative17 } from "pathe";
 import { glob as glob10 } from "tinyglobby";
 
 // src/migrate/nextra/content.ts
@@ -11874,13 +13217,13 @@ var indexFolders = (base, pageFiles, metaFiles) => {
     let current = normalizeDir(dir);
     allDirs.add(current);
     while (current !== "") {
-      current = normalizeDir(dirname17(current));
+      current = normalizeDir(dirname18(current));
       allDirs.add(current);
     }
   };
   for (const abs of pageFiles) {
-    const rel = relative16(base, abs);
-    const dir = normalizeDir(dirname17(rel));
+    const rel = relative17(base, abs);
+    const dir = normalizeDir(dirname18(rel));
     const slug = basename7(rel).replace(/\.mdx?$/u, "");
     const folder = pagesByDir.get(dir) ?? new Map;
     folder.set(slug, abs);
@@ -11888,14 +13231,14 @@ var indexFolders = (base, pageFiles, metaFiles) => {
     registerDir(dir);
   }
   for (const abs of metaFiles) {
-    registerDir(normalizeDir(dirname17(relative16(base, abs))));
+    registerDir(normalizeDir(dirname18(relative17(base, abs))));
   }
   const childDirs = new Map;
   for (const dir of allDirs) {
     if (dir === "") {
       continue;
     }
-    const parent = normalizeDir(dirname17(dir));
+    const parent = normalizeDir(dirname18(dir));
     const children = childDirs.get(parent) ?? new Set;
     children.add(basename7(dir));
     childDirs.set(parent, children);
@@ -11913,7 +13256,7 @@ var planMetas = (metas, index) => {
     warnings: []
   };
   for (const meta of metas) {
-    const dir = normalizeDir(dirname17(meta.rel));
+    const dir = normalizeDir(dirname18(meta.rel));
     const entries = parseNextraMeta(meta.raw, meta.ext);
     if (!entries) {
       plan.unparseableMetas.push({ abs: meta.abs, rel: meta.rel });
@@ -11926,7 +13269,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(join32(dir, slug)), title);
+      plan.folderTitleByDir.set(normalizeDir(join33(dir, slug)), title);
     }
     for (const [slug, label] of Object.entries(conversion.pageLabels)) {
       const pageAbs = index.pagesByDir.get(dir)?.get(slug);
@@ -11950,9 +13293,9 @@ var planMetas = (metas, index) => {
   return plan;
 };
 var movePage2 = async (abs, options) => {
-  const rel = relative16(options.base, abs);
-  const dest = join32(options.root, "docs", rel);
-  if (existsSync20(dest)) {
+  const rel = relative17(options.base, abs);
+  const dest = join33(options.root, "docs", rel);
+  if (existsSync24(dest)) {
     return { moved: 0, removed: [], skipped: rel, unsupported: [] };
   }
   const raw = await readFile19(abs, "utf-8");
@@ -11961,7 +13304,7 @@ var movePage2 = async (abs, options) => {
   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(dirname17(dest), { recursive: true });
+  await mkdir10(dirname18(dest), { recursive: true });
   await writeFile13(dest, content, "utf-8");
   await rm5(abs, { force: true });
   return { moved: 1, removed, skipped: null, unsupported };
@@ -12004,8 +13347,8 @@ var writeFolderMetas = async (root, plan) => {
     if (Object.keys(finalMeta).length === 0) {
       return;
     }
-    const dest = join32(root, "docs", dir, "meta.ts");
-    await mkdir10(dirname17(dest), { recursive: true });
+    const dest = join33(root, "docs", dir, "meta.ts");
+    await mkdir10(dirname18(dest), { recursive: true });
     await writeFile13(dest, `import { defineMeta } from "blume";
 
 export default defineMeta(${JSON.stringify(finalMeta, null, 2)});
@@ -12015,12 +13358,12 @@ 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 = join32(root, "docs", rel);
-    if (existsSync20(dest)) {
+    const dest = join33(root, "docs", rel);
+    if (existsSync24(dest)) {
       warnings.push(`Skipped ${rel} (target already exists)`);
       return;
     }
-    await mkdir10(dirname17(dest), { recursive: true });
+    await mkdir10(dirname18(dest), { recursive: true });
     await rename5(abs, dest);
     warnings.push(`Could not parse ${rel}; moved as-is — convert it to meta.ts by hand.`);
   }));
@@ -12028,7 +13371,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) => existsSync20(join32(root, dir)));
+  const sourceDir = SOURCE_DIRS.find((dir) => existsSync24(join33(root, dir)));
   if (!sourceDir) {
     await writeBlumeConfig(root, { title: "Documentation" });
     return {
@@ -12038,7 +13381,7 @@ var migrateNextraProject = async (root) => {
       ]
     };
   }
-  const base = join32(root, sourceDir);
+  const base = join33(root, sourceDir);
   const pageFiles = await glob10([PAGE_GLOB2], {
     absolute: true,
     cwd: base,
@@ -12052,9 +13395,9 @@ var migrateNextraProject = async (root) => {
   const index = indexFolders(base, pageFiles, metaFiles);
   const metas = await Promise.all(metaFiles.map(async (abs) => ({
     abs,
-    ext: extname6(abs),
+    ext: extname7(abs),
     raw: await readFile19(abs, "utf-8"),
-    rel: relative16(base, abs)
+    rel: relative17(base, abs)
   })));
   const plan = planMetas(metas, index);
   const moves = await Promise.all(pageFiles.map((abs) => movePage2(abs, { base, overrides: plan.pageOverrides, root })));
@@ -12079,15 +13422,15 @@ var migrateNextraProject = async (root) => {
 };
 
 // src/migrate/starlight/index.ts
-import { existsSync as existsSync22 } from "node:fs";
+import { existsSync as existsSync26 } from "node:fs";
 import { readFile as readFile21, writeFile as writeFile14 } from "node:fs/promises";
-import { join as join34 } from "pathe";
+import { join as join35 } from "pathe";
 import { glob as glob11 } from "tinyglobby";
 
 // src/migrate/starlight/config.ts
-import { existsSync as existsSync21 } from "node:fs";
+import { existsSync as existsSync25 } from "node:fs";
 import { readFile as readFile20 } from "node:fs/promises";
-import { join as join33 } from "pathe";
+import { join as join34 } from "pathe";
 var CONFIG_FILES = [
   "astro.config.mjs",
   "astro.config.mts",
@@ -12118,7 +13461,7 @@ var extractStarlightOptions = (source) => {
   return isLiteralObject(parsed) ? parsed : "unparseable";
 };
 var loadStarlightConfig = async (root) => {
-  const file = CONFIG_FILES.map((name) => join33(root, name)).find((path) => existsSync21(path));
+  const file = CONFIG_FILES.map((name) => join34(root, name)).find((path) => existsSync25(path));
   if (!file) {
     return {
       options: {},
@@ -12361,9 +13704,6 @@ var mapStarlightConfig = (options, warnings) => {
     }
   }
   const social = mapSocial(options.social);
-  if (Object.keys(social.socials).length > 0) {
-    config.footer = { socials: social.socials };
-  }
   const github = mapEditLink(options.editLink) ?? social.github;
   if (github) {
     config.github = github;
@@ -12550,8 +13890,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 = join34(root, CONTENT_DIR);
-  if (!existsSync22(base)) {
+  const base = join35(root, CONTENT_DIR);
+  if (!existsSync26(base)) {
     await writeBlumeConfig(root, config);
     return {
       moved: 0,
@@ -12605,7 +13945,7 @@ var migrators = {
 };
 
 // src/cli/commands/migrate.ts
-var makeMigrateCommand = (source) => defineCommand7({
+var makeMigrateCommand = (source) => defineCommand8({
   meta: {
     description: `Migrate a ${source} project to Blume.`,
     name: source
@@ -12625,7 +13965,7 @@ var makeMigrateCommand = (source) => defineCommand7({
     logger.box("Review blume.config.ts and run `blume dev`.");
   }
 });
-var migrateCommand = defineCommand7({
+var migrateCommand = defineCommand8({
   meta: {
     description: "Migrate from another docs tool to Blume.",
     name: "migrate"
@@ -12639,11 +13979,11 @@ var migrateCommand = defineCommand7({
 });
 
 // src/cli/commands/preview.ts
-import { existsSync as existsSync23 } from "node:fs";
+import { existsSync as existsSync27 } from "node:fs";
 import { preview } from "astro";
-import { defineCommand as defineCommand8 } from "citty";
-import { join as join35 } from "pathe";
-var previewCommand = defineCommand8({
+import { defineCommand as defineCommand9 } from "citty";
+import { join as join36 } from "pathe";
+var previewCommand = defineCommand9({
   args: {
     host: { description: "Network host to bind.", type: "string" },
     port: { description: "Port to listen on.", type: "string" }
@@ -12656,7 +13996,7 @@ var previewCommand = defineCommand8({
     const root = process.cwd();
     const { config } = await loadConfig(root);
     const context = resolveProjectContext(root, config);
-    if (!existsSync23(join35(context.outDir, "astro.config.mjs"))) {
+    if (!existsSync27(join36(context.outDir, "astro.config.mjs"))) {
       logger.error("No build found. Run `blume build` first.");
       process.exit(1);
     }
@@ -12673,9 +14013,9 @@ var previewCommand = defineCommand8({
 
 // src/cli/commands/sync.ts
 import { rm as rm6 } from "node:fs/promises";
-import { defineCommand as defineCommand9 } from "citty";
-import { join as join36 } from "pathe";
-var syncCommand = defineCommand9({
+import { defineCommand as defineCommand10 } from "citty";
+import { join as join37 } from "pathe";
+var syncCommand = defineCommand10({
   args: {
     force: {
       description: "Clear the source cache before refetching.",
@@ -12696,7 +14036,7 @@ var syncCommand = defineCommand9({
     if (args.force) {
       const { config } = await loadConfig(root);
       const context = resolveProjectContext(root, config);
-      await rm6(join36(context.outDir, "cache"), { force: true, recursive: true });
+      await rm6(join37(context.outDir, "cache"), { force: true, recursive: true });
       logger.info("Cleared source cache.");
     }
     await prepareProject({
@@ -12711,13 +14051,13 @@ var syncCommand = defineCommand9({
 });
 
 // src/cli/commands/validate.ts
-import { existsSync as existsSync25 } from "node:fs";
-import { defineCommand as defineCommand10 } from "citty";
-import { join as join38 } from "pathe";
+import { existsSync as existsSync29 } from "node:fs";
+import { defineCommand as defineCommand11 } from "citty";
+import { join as join39 } from "pathe";
 
 // src/core/links.ts
-import { existsSync as existsSync24 } from "node:fs";
-import { join as join37 } from "pathe";
+import { existsSync as existsSync28 } from "node:fs";
+import { join as join38 } from "pathe";
 var HTTP = /^https?:\/\//iu;
 var PROTOCOL_RELATIVE = /^\/\//u;
 var SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
@@ -12756,8 +14096,8 @@ var toRoute = (path) => {
 };
 var buildAnchorIndex = (pages) => {
   const anchors = new Map;
-  for (const page of pages) {
-    anchors.set(page.route, new Set(page.headings.map((heading) => heading.slug)));
+  for (const page2 of pages) {
+    anchors.set(page2.route, new Set(page2.headings.map((heading) => heading.slug)));
   }
   return anchors;
 };
@@ -12777,7 +14117,7 @@ var checkPathLink = (resolved, fragment, target, site, ctx) => {
     if (ctx.publicDir === null) {
       return "asset-unchecked";
     }
-    if (existsSync24(join37(ctx.publicDir, resolved))) {
+    if (existsSync28(join38(ctx.publicDir, resolved))) {
       return null;
     }
     return {
@@ -12876,11 +14216,11 @@ var checkExternalLinks = async (refs) => {
   }
   return diagnostics;
 };
-var classifyLink = (page, link, ctx, onExternal) => {
+var classifyLink = (page2, link, ctx, onExternal) => {
   const { target } = link;
   const site = {
     column: link.column,
-    file: page.sourcePath ?? page.id,
+    file: page2.sourcePath ?? page2.id,
     line: link.line
   };
   if (HTTP.test(target) || PROTOCOL_RELATIVE.test(target)) {
@@ -12901,9 +14241,9 @@ var classifyLink = (page, link, ctx, onExternal) => {
     rawPath = rawPath.slice(0, queryIndex);
   }
   if (rawPath === "") {
-    return fragment ? checkAnchor(page.route, fragment, site, ctx) : null;
+    return fragment ? checkAnchor(page2.route, fragment, site, ctx) : null;
   }
-  const resolved = rawPath.startsWith("/") ? rawPath : resolveRelative(page.route, rawPath);
+  const resolved = rawPath.startsWith("/") ? rawPath : resolveRelative(page2.route, rawPath);
   return checkPathLink(resolved, fragment, target, site, ctx);
 };
 var validateLinks = async (graph, options) => {
@@ -12916,9 +14256,9 @@ var validateLinks = async (graph, options) => {
   const diagnostics = [];
   const external = [];
   let uncheckedAssets = 0;
-  for (const page of graph.pages) {
-    for (const link of page.links) {
-      const result = classifyLink(page, link, ctx, (ref) => external.push(ref));
+  for (const page2 of graph.pages) {
+    for (const link of page2.links) {
+      const result = classifyLink(page2, link, ctx, (ref) => external.push(ref));
       if (result === "asset-unchecked") {
         uncheckedAssets += 1;
       } else if (result) {
@@ -12940,12 +14280,16 @@ var validateLinks = async (graph, options) => {
 };
 
 // src/cli/commands/validate.ts
-var validateCommand = defineCommand10({
+var validateCommand = defineCommand11({
   args: {
     external: {
       description: "Check external (HTTP) links over the network.",
       type: "boolean"
     },
+    json: {
+      description: "Emit diagnostics as JSON on stdout (for CI/editors).",
+      type: "boolean"
+    },
     strict: {
       description: "Treat warnings as errors.",
       type: "boolean"
@@ -12961,18 +14305,26 @@ var validateCommand = defineCommand10({
     try {
       const project = await scanProject(root, { mode: "build" });
       diagnostics.push(...project.diagnostics);
-      const publicDir = join38(root, "public");
+      const publicDir = join39(root, "public");
       diagnostics.push(...await validateLinks(project.graph, {
         checkExternal: Boolean(args.external),
-        publicDir: existsSync25(publicDir) ? publicDir : null,
+        publicDir: existsSync29(publicDir) ? publicDir : null,
         redirects: project.config.redirects
       }));
     } catch (error) {
       if (error instanceof BlumeError) {
         diagnostics.push(error.diagnostic);
       } else {
-        throw error;
+        reportInternalError(error);
+        process.exit(1);
+      }
+    }
+    if (args.json) {
+      const hadErrors2 = reportDiagnosticsJson(diagnostics, root);
+      if (hadErrors2 || Boolean(args.strict) && diagnostics.length > 0) {
+        process.exit(1);
       }
+      return;
     }
     const hadErrors = reportDiagnostics(diagnostics, root);
     if (diagnostics.length === 0) {
@@ -12985,7 +14337,7 @@ var validateCommand = defineCommand10({
 });
 
 // src/cli/index.ts
-var main = defineCommand11({
+var main = defineCommand12({
   meta: {
     description: "Markdown-first documentation powered by Astro and Vite.",
     name: "blume",
@@ -12994,6 +14346,7 @@ var main = defineCommand11({
   subCommands: {
     add: addCommand,
     build: buildCommand,
+    check: checkCommand,
     dev: devCommand,
     doctor: doctorCommand,
     eject: ejectCommand,
@@ -13005,7 +14358,15 @@ var main = defineCommand11({
   }
 });
 loadEnvFiles(process.cwd());
+process.on("uncaughtException", (error) => {
+  reportInternalError(error);
+  process.exit(1);
+});
+process.on("unhandledRejection", (error) => {
+  reportInternalError(error);
+  process.exit(1);
+});
 runMain(main);
 
-//# debugId=1F31417850B615D064756E2164756E21
+//# debugId=8EA79E97DE44177D64756E2164756E21
 //# sourceMappingURL=index.js.map