blume 0.3.0 → 0.4.0

package/dist/cli/index.js

@@ -209,6 +209,12 @@ var CONTENT_COMPONENTS = [
     file: "Prompt.astro",
     name: "prompt",
     tag: "Prompt"
+  },
+  {
+    description: "A responsive, privacy-friendly YouTube embed.",
+    file: "YouTube.astro",
+    name: "youtube",
+    tag: "YouTube"
   }
 ];
 var registry = [
@@ -254,18 +260,22 @@ var findItem = (name) => registry.find((item) => item.name === name);
 
 // src/registry/rewrite-imports.ts
 import { dirname as dirname2, relative, resolve } from "pathe";
-var RELATIVE_IMPORT = /(?<kw>\bfrom|\bimport)(?<gap>\s+)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gu;
-var rewriteImports = (content, sourceFile, srcRoot) => content.replaceAll(RELATIVE_IMPORT, (match, kw, gap, quote, spec) => {
-  const resolved = resolve(dirname2(sourceFile), spec);
-  if (resolved === sourceFile) {
-    return match;
-  }
-  const rel = relative(srcRoot, resolved);
-  if (rel.startsWith("..")) {
-    return match;
-  }
-  return `${kw}${gap}${quote}blume/${rel}${quote}`;
-});
+var FROM_IMPORT = /(?<prefix>^[ \t]*(?:import|export)\b[^;]*?\bfrom[ \t]*)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gmu;
+var SIDE_EFFECT_IMPORT = /(?<prefix>^[ \t]*import[ \t]+)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gmu;
+var rewriteImports = (content, sourceFile, srcRoot) => {
+  const rewrite = (match, prefix, quote, spec) => {
+    const resolved = resolve(dirname2(sourceFile), spec);
+    if (resolved === sourceFile) {
+      return match;
+    }
+    const rel = relative(srcRoot, resolved);
+    if (rel.startsWith("..")) {
+      return match;
+    }
+    return `${prefix}${quote}blume/${rel}${quote}`;
+  };
+  return content.replaceAll(FROM_IMPORT, rewrite).replaceAll(SIDE_EFFECT_IMPORT, rewrite);
+};
 
 // src/cli/log.ts
 import { consola } from "consola";
@@ -326,7 +336,7 @@ var locatePath = (source, path) => {
     if (typeof segment !== "string") {
       continue;
     }
-    const matcher = new RegExp(`${escapeRegExp(segment)}\\s*[:=]`, "gu");
+    const matcher = new RegExp(`(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`, "gu");
     matcher.lastIndex = cursor;
     const match = matcher.exec(source);
     if (!match) {
@@ -408,6 +418,9 @@ var countBySeverity = (diagnostics) => {
 
 // src/cli/log.ts
 var logger = consola.withTag("blume");
+var flushStdout = () => new Promise((resolve2) => {
+  process.stdout.write("", () => resolve2());
+});
 var reportDiagnosticsJson = (diagnostics, root) => {
   const enriched = diagnostics.map((diagnostic) => {
     const withDocs = enrichDiagnostic(diagnostic);
@@ -500,11 +513,11 @@ Next steps:
 });
 
 // src/cli/commands/build.ts
-import { existsSync as existsSync15 } from "node:fs";
+import { existsSync as existsSync16 } 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";
+import { join as join26 } from "pathe";
 
 // src/core/frontmatter.ts
 import baseMatter from "gray-matter";
@@ -699,14 +712,24 @@ var buildRobots = (project) => {
 `;
 };
 
+// src/deploy/xml.ts
+var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+
 // src/deploy/sitemap.ts
+var lastmodTag = (value) => {
+  if (!value) {
+    return "";
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? "" : `<lastmod>${date.toISOString().slice(0, 10)}</lastmod>`;
+};
 var buildSitemap = (project) => {
   const { site } = project.config.deployment;
   if (!(site && project.config.seo.sitemap)) {
     return null;
   }
   const base = site.replace(/\/$/u, "");
-  const urls = project.graph.pages.filter((page) => !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex)).map((page) => `  <url><loc>${base}${page.route}</loc></url>`).toSorted();
+  const urls = project.graph.pages.filter((page) => !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex)).map((page) => `  <url><loc>${escapeXml(encodeURI(`${base}${page.route}`))}</loc>${lastmodTag(page.lastModified)}</url>`).toSorted();
   return `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
 ${urls.join(`
@@ -2580,7 +2603,19 @@ var LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
 var HEADING_MARK = /^#{1,6}\s+/gmu;
 var MARKDOWN_PUNCT = /[*_~>]+/gu;
 var WHITESPACE = /\s+/gu;
-var toPlainText = (markdown) => markdown.replaceAll(CODE_FENCE, " ").replaceAll(IMAGE, " ").replaceAll(LINK, "$<text>").replaceAll(HTML_OR_JSX, " ").replaceAll(INLINE_CODE, "$<code>").replaceAll(HEADING_MARK, "").replaceAll(MARKDOWN_PUNCT, " ").replaceAll(WHITESPACE, " ").trim();
+var toPlainText = (markdown) => {
+  const withoutBlocks = markdown.replaceAll(CODE_FENCE, " ").replaceAll(IMAGE, " ").replaceAll(LINK, "$<text>");
+  const pieces = [];
+  let cursor = 0;
+  for (const match of withoutBlocks.matchAll(INLINE_CODE)) {
+    const start = match.index ?? 0;
+    pieces.push(withoutBlocks.slice(cursor, start).replaceAll(HTML_OR_JSX, " "));
+    pieces.push(match.groups?.code ?? "");
+    cursor = start + match[0].length;
+  }
+  pieces.push(withoutBlocks.slice(cursor).replaceAll(HTML_OR_JSX, " "));
+  return pieces.join("").replaceAll(HEADING_MARK, "").replaceAll(MARKDOWN_PUNCT, " ").replaceAll(WHITESPACE, " ").trim();
+};
 var buildCrumbIndex = (sidebar) => {
   const index = new Map;
   const walk = (nodes, trail) => {
@@ -2654,7 +2689,7 @@ var syncAlgolia = async (records, config) => {
   }
   const { algoliasearch } = await import("algoliasearch");
   const client = algoliasearch(config.appId, adminKey);
-  await client.saveObjects({
+  await client.replaceAllObjects({
     indexName: config.indexName,
     objects: records.map((record) => ({ ...record, objectID: record._id }))
   });
@@ -2706,20 +2741,21 @@ var syncTypesense = async (records, config) => {
       }
     ]
   });
-  try {
-    await client.collections(config.collection).retrieve();
-  } catch {
-    await client.collections().create({
-      fields: [
-        { name: "title", type: "string" },
-        { name: "description", optional: true, type: "string" },
-        { name: "content", type: "string" },
-        { name: "url", type: "string" },
-        { facet: true, name: "tag", optional: true, type: "string" }
-      ],
-      name: config.collection
-    });
-  }
+  const collection = client.collections(config.collection);
+  const exists = await collection.retrieve().then(() => true).catch(() => false);
+  if (exists) {
+    await collection.delete();
+  }
+  await client.collections().create({
+    fields: [
+      { name: "title", type: "string" },
+      { name: "description", optional: true, type: "string" },
+      { name: "content", type: "string" },
+      { name: "url", type: "string" },
+      { facet: true, name: "tag", optional: true, type: "string" }
+    ],
+    name: config.collection
+  });
   const documents = records.map((record) => ({
     content: record.content,
     description: record.description,
@@ -2753,8 +2789,58 @@ var syncSearchProvider = async (project, reporter) => {
   }
 };
 
+// src/cli/dev-lock.ts
+import {
+  existsSync as existsSync3,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  rmSync,
+  writeFileSync
+} from "node:fs";
+import { join as join6 } from "pathe";
+var lockPath = (outDir) => join6(outDir, "dev.lock");
+var isDevLocked = (outDir) => {
+  const path = lockPath(outDir);
+  if (!existsSync3(path)) {
+    return false;
+  }
+  const pid = Number.parseInt(readFileSync2(path, "utf-8").trim(), 10);
+  if (!(Number.isInteger(pid) && pid > 0)) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var acquireDevLock = (outDir) => {
+  const path = lockPath(outDir);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(path, String(process.pid));
+  let released = false;
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    try {
+      if (existsSync3(path) && readFileSync2(path, "utf-8").trim() === String(process.pid)) {
+        rmSync(path, { force: true });
+      }
+    } catch {}
+  };
+};
+var refuseIfDevRunning = (root, action) => {
+  if (isDevLocked(join6(root, ".blume"))) {
+    logger.error(`A \`blume dev\` server is running against .blume; ${action} would corrupt it. Stop the dev server first.`);
+    process.exit(1);
+  }
+};
+
 // src/astro/generate.ts
-import { existsSync as existsSync6, readFileSync as readFileSync5, realpathSync } from "node:fs";
+import { existsSync as existsSync7, readFileSync as readFileSync6, realpathSync } from "node:fs";
 import {
   lstat,
   mkdir as mkdir2,
@@ -2766,7 +2852,7 @@ 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 dirname7, join as join11, normalize, relative as relative6 } from "pathe";
+import { basename as basename2, dirname as dirname7, join as join13, normalize, relative as relative6 } from "pathe";
 import { glob as glob4 } from "tinyglobby";
 
 // src/ai/ask-data.ts
@@ -2971,7 +3057,8 @@ var BUILTIN_MDX_TAGS = new Set([
   "Tooltip",
   "Tree",
   "TypeTable",
-  "Visibility"
+  "Visibility",
+  "YouTube"
 ]);
 
 // src/core/component-diagnostics.ts
@@ -3000,7 +3087,7 @@ var validateUsedComponents = (pages, extraTags, registryNames) => {
 };
 
 // src/core/component-overrides.ts
-import { existsSync as existsSync3 } from "node:fs";
+import { existsSync as existsSync4 } from "node:fs";
 import { dirname as dirname4, extname, isAbsolute, resolve as resolve2 } from "pathe";
 import ts from "typescript";
 var GROUPS = ["mdx", "layout", "islands"];
@@ -3089,7 +3176,7 @@ var findDefaultExportObject = (sourceFile) => {
 var probeExtension = (base) => {
   for (const extension of COMPONENT_EXTS) {
     const candidate = `${base}.${extension}`;
-    if (existsSync3(candidate)) {
+    if (existsSync4(candidate)) {
       return candidate;
     }
   }
@@ -3621,10 +3708,10 @@ var validateNavStructure = (navigation, pages) => [
 ];
 
 // src/core/tsconfig-aliases.ts
-import { existsSync as existsSync4, readFileSync as readFileSync2, statSync } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync3, statSync } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import { pathToFileURL } from "node:url";
-import { dirname as dirname5, isAbsolute as isAbsolute2, join as join6, resolve as resolve3 } from "pathe";
+import { dirname as dirname5, isAbsolute as isAbsolute2, join as join7, resolve as resolve3 } from "pathe";
 var stripJsonComments = (text) => {
   let out = "";
   let inString = false;
@@ -3687,7 +3774,7 @@ var resolveExtends = (spec, fromDir) => {
     return candidates.find(isFile) ?? null;
   }
   try {
-    const require_ = createRequire2(pathToFileURL(join6(fromDir, "_.js")).href);
+    const require_ = createRequire2(pathToFileURL(join7(fromDir, "_.js")).href);
     for (const sub of [`${spec}/tsconfig.json`, spec]) {
       try {
         return require_.resolve(sub);
@@ -3697,11 +3784,11 @@ var resolveExtends = (spec, fromDir) => {
   return null;
 };
 var loadPaths = (file, seen) => {
-  if (seen.has(file) || !existsSync4(file)) {
+  if (seen.has(file) || !existsSync5(file)) {
     return null;
   }
   seen.add(file);
-  const json = parseJsonc(readFileSync2(file, "utf-8"));
+  const json = parseJsonc(readFileSync3(file, "utf-8"));
   if (!json) {
     return null;
   }
@@ -3739,7 +3826,7 @@ var toAlias = (key, value, baseDir) => {
   return { find, replacement: resolve3(baseDir, target) };
 };
 var resolveTsconfigAliases = (root) => {
-  const entry = ["tsconfig.json", "jsconfig.json"].map((name) => join6(root, name)).find((file) => existsSync4(file));
+  const entry = ["tsconfig.json", "jsconfig.json"].map((name) => join7(root, name)).find((file) => existsSync5(file));
   if (!entry) {
     return {};
   }
@@ -3798,7 +3885,6 @@ var buildRssFeeds = (project) => {
   }
   return feeds;
 };
-var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
 var renderItem = (item) => {
   const parts = [
     `    <title>${escapeXml(item.title)}</title>`,
@@ -3838,11 +3924,18 @@ ${items}
 
 // src/openapi/scalar.ts
 import { readFile as readFile4 } from "node:fs/promises";
-import { isAbsolute as isAbsolute3, join as join8 } from "pathe";
+import { isAbsolute as isAbsolute3, join as join10 } from "pathe";
 
 // src/astro/templates.ts
-import { existsSync as existsSync5, readFileSync as readFileSync3 } from "node:fs";
-import { dirname as dirname6, join as join7 } from "pathe";
+import { existsSync as existsSync6, readFileSync as readFileSync4 } from "node:fs";
+import { dirname as dirname6, join as join9 } from "pathe";
+
+// src/core/assets.ts
+import { join as join8 } from "pathe";
+var resolveAssetMounts = (root, assets) => assets.map((entry) => {
+  const rel = entry.replace(/^[./]+/u, "").replaceAll(/\.\.\/?/gu, "").replace(/\/+$/u, "");
+  return { dir: join8(root, rel), url: `/${rel}` };
+});
 
 // src/theme/fonts.ts
 var FALLBACKS = {
@@ -4000,17 +4093,17 @@ var WORKSPACE_MARKERS = [
   "yarn.lock"
 ];
 var hasWorkspacesField = (pkgPath) => {
-  if (!existsSync5(pkgPath)) {
+  if (!existsSync6(pkgPath)) {
     return false;
   }
   try {
-    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
     return pkg.workspaces !== undefined;
   } catch {
     return false;
   }
 };
-var hasWorkspaceMarker = (dir) => hasWorkspacesField(join7(dir, "package.json")) || WORKSPACE_MARKERS.some((marker) => existsSync5(join7(dir, marker)));
+var hasWorkspaceMarker = (dir) => hasWorkspacesField(join9(dir, "package.json")) || WORKSPACE_MARKERS.some((marker) => existsSync6(join9(dir, marker)));
 var findWorkspaceRoot = (start) => {
   let dir = start;
   for (;; ) {
@@ -4144,7 +4237,8 @@ var astroConfigTemplate = (options) => {
   if (needsSvelte) {
     integrations.push("svelte()");
   }
-  integrations.push(`blumeIntegration(${JSON.stringify({ contentRoutes, pages })})`);
+  const assets = resolveAssetMounts(context.root, config.content.assets);
+  integrations.push(`blumeIntegration(${JSON.stringify({ assets, base: deployment.base, contentRoutes, pages })})`);
   return `// Generated by Blume. Do not edit; this file is recreated on each run.
 ${defineConfigImport}
 import mdx from "@astrojs/mdx";
@@ -4200,7 +4294,7 @@ export default defineConfig({
 });
 `;
 };
-var stagedContentDir = (outDir) => join7(outDir, "content");
+var stagedContentDir = (outDir) => join9(outDir, "content");
 var contentConfigTemplate = (options) => {
   const { context, config } = options;
   const stagedBase = options.stagedBase ?? stagedContentDir(context.outDir);
@@ -4257,31 +4351,44 @@ const provider = createOpenAICompatible({
     modelExpr = `provider(${JSON.stringify(backend.model)})`;
   }
   if (grounded) {
-    imports.push('import { createAskContext } from "blume/ai/ask-context.ts";', 'import askData from "../generated/ask-data.json";');
+    imports.push('import { createAskContext } from "blume/ai/ask-context.ts";', 'import askData from "../../generated/ask-data.json";');
     setup += `
 const ground = createAskContext(askData);
 `;
   }
-  const handler = grounded ? `export const POST: APIRoute = async ({ request }) => {
-  const { messages, page } = await request.json();
-  const system =
-    (await ground(messages, page)) ??
-    "You are a helpful documentation assistant. Answer using the project's documentation.";
-  const result = streamText({
-    model: ${modelExpr},
-    system,
-    messages,
-  });
-  return result.toTextStreamResponse();
-};` : `export const POST: APIRoute = async ({ request }) => {
-  const { messages } = await request.json();
-  const result = streamText({
-    model: ${modelExpr},
-    system:
-      "You are a helpful documentation assistant. Answer using the project's documentation.",
-    messages,
-  });
-  return result.toTextStreamResponse();
+  const validate = `  const body = await request.json().catch(() => null);
+  const messages = body?.messages;
+  if (
+    !Array.isArray(messages) ||
+    messages.length === 0 ||
+    messages.length > 40 ||
+    JSON.stringify(messages).length > 24_000
+  ) {
+    return new Response("Invalid request: send 1-40 messages.", {
+      status: 400,
+    });
+  }`;
+  const stream = grounded ? `    const system =
+      (await ground(messages, body.page)) ??
+      "You are a helpful documentation assistant. Answer using the project's documentation.";
+    const result = streamText({
+      model: ${modelExpr},
+      system,
+      messages,
+    });` : `    const result = streamText({
+      model: ${modelExpr},
+      system:
+        "You are a helpful documentation assistant. Answer using the project's documentation.",
+      messages,
+    });`;
+  const handler = `export const POST: APIRoute = async ({ request }) => {
+${validate}
+  try {
+${stream}
+    return result.toTextStreamResponse();
+  } catch {
+    return new Response("Failed to generate a response.", { status: 500 });
+  }
 };`;
   return `// Generated by Blume. Do not edit.
 ${imports.join(`
@@ -4605,6 +4712,7 @@ import TreeFile from "blume/components/content/TreeFile.astro";
 import TreeFolder from "blume/components/content/TreeFolder.astro";
 import TypeTable from "blume/components/content/TypeTable.astro";
 import Visibility from "blume/components/content/Visibility.astro";
+import YouTube from "blume/components/content/YouTube.astro";
 import Icon from "blume/components/Icon.astro";
 ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../generated/components.ts";
 import { islandComponents } from "../generated/islands.ts";
@@ -4650,6 +4758,7 @@ const components = {
   Tree,
   TypeTable,
   Visibility,
+  YouTube,
   ${mathEntry}...islandComponents,
   ...userMdx,
 };
@@ -5061,8 +5170,9 @@ var runtimeTsconfigTemplate = () => `${JSON.stringify({
 `;
 
 // src/theme/palette.ts
+var FALLBACK_ACCENT = "oklch(0.62 0.16 250)";
 var ACCENTS = {
-  blue: "oklch(0.62 0.16 250)",
+  blue: FALLBACK_ACCENT,
   green: "oklch(0.6 0.16 150)",
   orange: "oklch(0.68 0.17 50)",
   pink: "oklch(0.65 0.2 350)",
@@ -5070,6 +5180,9 @@ var ACCENTS = {
   red: "oklch(0.58 0.22 25)",
   teal: "oklch(0.6 0.12 195)"
 };
+var CSS_COLOR = /^[\w\s#%.,()/+-]+$/u;
+var safeColor = (value, fallback) => CSS_COLOR.test(value.trim()) ? value.trim() : fallback;
+var safeColorOrNull = (value) => value && CSS_COLOR.test(value.trim()) ? value.trim() : null;
 var RADII = {
   lg: "0.75rem",
   md: "0.5rem",
@@ -5104,7 +5217,7 @@ var themeRootCss = (theme, options) => [
   `  --blume-accent: ${options.accent};`,
   ...cssToken("--blume-action", options.action),
   ...cssToken("--blume-action-foreground", options.action ? "oklch(1 0 0)" : null),
-  ...cssToken("--blume-background", theme.background),
+  ...cssToken("--blume-background", safeColorOrNull(theme.background)),
   ...cssToken("--blume-background-image", theme.backgroundImage ? backgroundImageCss(theme.backgroundImage) : null),
   options.backgroundDecoration.trimEnd(),
   `  --blume-radius: ${options.radius};`
@@ -5113,7 +5226,7 @@ var themeRootCss = (theme, options) => [
 var themeDarkCss = (theme, accentDark) => {
   const tokens = [
     ...cssToken("--blume-accent", accentDark),
-    ...cssToken("--blume-background", theme.backgroundDark),
+    ...cssToken("--blume-background", safeColorOrNull(theme.backgroundDark)),
     ...cssToken("--blume-background-image", theme.backgroundImageDark ? backgroundImageCss(theme.backgroundImageDark) : null)
   ];
   if (tokens.length === 0) {
@@ -5125,12 +5238,12 @@ ${tokens.join(`
 }
 `;
 };
-var resolveAccent = (theme) => ACCENTS[theme.accent] ?? theme.accent;
+var resolveAccent = (theme) => ACCENTS[theme.accent] ?? safeColor(theme.accent, FALLBACK_ACCENT);
 var resolveRadius = (theme) => RADII[theme.radius];
 var buildThemeCss = (theme) => {
-  const accent = ACCENTS[theme.accent] ?? theme.accent;
-  const accentDark = theme.accentDark ? ACCENTS[theme.accentDark] ?? theme.accentDark : null;
-  const action = theme.action ? ACCENTS[theme.action] ?? theme.action : null;
+  const accent = ACCENTS[theme.accent] ?? safeColor(theme.accent, FALLBACK_ACCENT);
+  const accentDark = theme.accentDark ? ACCENTS[theme.accentDark] ?? safeColor(theme.accentDark, FALLBACK_ACCENT) : null;
+  const action = theme.action ? ACCENTS[theme.action] ?? safeColor(theme.action, FALLBACK_ACCENT) : null;
   const backgroundDecoration = backgroundDecorationCss(theme.backgroundDecoration);
   const radius = RADII[theme.radius];
   const root = themeRootCss(theme, {
@@ -5224,7 +5337,7 @@ var specConfiguration = async (spec, root) => {
   if (URL_SPEC.test(spec)) {
     return { config: { url: spec } };
   }
-  const absolute = isAbsolute3(spec) ? spec : join8(root, spec);
+  const absolute = isAbsolute3(spec) ? spec : join10(root, spec);
   try {
     return { config: { content: await readFile4(absolute, "utf-8") } };
   } catch {
@@ -5897,7 +6010,7 @@ ${options.userTheme}
 `;
 
 // src/theme/twoslash.ts
-import { readFileSync as readFileSync4 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 import { createRequire as createRequire3 } from "node:module";
 var require2 = createRequire3(import.meta.url);
 var OVERRIDES = `
@@ -5959,7 +6072,7 @@ var OVERRIDES = `
 `;
 var twoslashCss = () => {
   const file = require2.resolve("@shikijs/twoslash/style-rich.css");
-  return `${readFileSync4(file, "utf-8")}
+  return `${readFileSync5(file, "utf-8")}
 ${OVERRIDES}`;
 };
 
@@ -6062,12 +6175,12 @@ export const layoutOverrides = { ...(overrides.layout ?? {})${layoutEntries.leng
 
 // src/astro/examples.ts
 import { readFile as readFile6 } from "node:fs/promises";
-import { join as join10, relative as relative4 } from "pathe";
+import { join as join12, relative as relative4 } from "pathe";
 import { glob as glob2 } from "tinyglobby";
 
 // src/astro/islands.ts
 import { readFile as readFile5 } from "node:fs/promises";
-import { basename, join as join9 } from "pathe";
+import { basename, join as join11 } from "pathe";
 import { glob } from "tinyglobby";
 var DEFAULT_CLIENT = "visible";
 var VALID_MODES = new Set([
@@ -6096,7 +6209,7 @@ var readClientMode = (source, file, warnings) => {
   return mode;
 };
 var discoverIslands = async (root) => {
-  const dir = join9(root, "islands");
+  const dir = join11(root, "islands");
   const matches = await glob(["**/*.{jsx,svelte,tsx,vue}"], {
     absolute: true,
     cwd: dir,
@@ -6115,8 +6228,8 @@ var discoverIslands = async (root) => {
       continue;
     }
     const name = base.replace(ISLAND_FILE, "");
-    if (!/^[A-Z]/u.test(name)) {
-      warnings.push(`Island "${file}" must have a PascalCase filename to be used in MDX (e.g. Counter.tsx → <Counter />); skipping it.`);
+    if (!/^[A-Z][A-Za-z0-9_]*$/u.test(name)) {
+      warnings.push(`Island "${file}" must have a PascalCase identifier filename to be used in MDX (letters, digits, and underscores only, e.g. Counter.tsx → <Counter />); skipping it.`);
       continue;
     }
     const existing = seen.get(name);
@@ -6159,7 +6272,7 @@ var splitGlobBase = (pattern) => {
 };
 var discoverExamples = async (root, pattern = "examples") => {
   const { base, rest } = GLOB_MAGIC.test(pattern) ? splitGlobBase(pattern) : { base: pattern, rest: DEFAULT_EXAMPLE_GLOB };
-  const dir = join10(root, base);
+  const dir = join12(root, base);
   const matches = await glob2([rest], {
     absolute: true,
     cwd: dir,
@@ -6209,7 +6322,10 @@ var discoverPages = async (pagesRoot) => {
   return files.map((file) => {
     const rel = relative5(pagesRoot, file);
     const withoutExt = rel.slice(0, rel.length - extname2(rel).length);
-    const parts = withoutExt.split("/").filter((part) => part !== "index");
+    const parts = withoutExt.split("/");
+    if (parts.at(-1) === "index") {
+      parts.pop();
+    }
     const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
     return { entrypoint: file, pattern };
   });
@@ -6237,10 +6353,10 @@ var customOgRoutes = (pages, siteTitle) => {
 };
 
 // src/astro/generate.ts
-var BLUME_SRC = join11(packageRoot(), "src");
+var BLUME_SRC = join13(packageRoot(), "src");
 var canResolveFrom = (fromDir, spec) => {
   try {
-    createRequire4(pathToFileURL2(join11(fromDir, "_.js")).href).resolve(spec);
+    createRequire4(pathToFileURL2(join13(fromDir, "_.js")).href).resolve(spec);
     return true;
   } catch {
     return false;
@@ -6248,15 +6364,15 @@ var canResolveFrom = (fromDir, spec) => {
 };
 var resolvedAstroPath = (fromDir) => {
   try {
-    const pkg = createRequire4(pathToFileURL2(join11(fromDir, "_.js")).href).resolve("astro/package.json");
+    const pkg = createRequire4(pathToFileURL2(join13(fromDir, "_.js")).href).resolve("astro/package.json");
     return realpathSync(pkg);
   } catch {
     return null;
   }
 };
 var blumeDepsDir = (pkgDir = packageRoot()) => {
-  const candidates = [join11(pkgDir, "node_modules"), dirname7(pkgDir)];
-  return candidates.find((dir) => existsSync6(join11(dir, "astro"))) ?? null;
+  const candidates = [join13(pkgDir, "node_modules"), dirname7(pkgDir)];
+  return candidates.find((dir) => existsSync7(join13(dir, "astro"))) ?? null;
 };
 var linkDepsJunction = async (link, depsDir) => {
   const existing = await lstat(link).catch(() => null);
@@ -6274,7 +6390,7 @@ var readPkgVersion = (pkgJsonPath) => {
     return null;
   }
   try {
-    return JSON.parse(readFileSync5(pkgJsonPath, "utf-8")).version ?? null;
+    return JSON.parse(readFileSync6(pkgJsonPath, "utf-8")).version ?? null;
   } catch {
     return null;
   }
@@ -6296,8 +6412,8 @@ var ensureDepsLink = async (outDir, pkgDir = packageRoot()) => {
   if (blumeAstro && outDirAstro === blumeAstro) {
     return null;
   }
-  if (existsSync6(join11(depsDir, "@astrojs", "mdx"))) {
-    await linkDepsJunction(join11(outDir, "node_modules"), depsDir);
+  if (existsSync7(join13(depsDir, "@astrojs", "mdx"))) {
+    await linkDepsJunction(join13(outDir, "node_modules"), depsDir);
     return null;
   }
   return astroConflictWarning(blumeAstro, outDirAstro);
@@ -6376,11 +6492,11 @@ var writeStagedContent = async (out, staged) => {
   const contentDir = stagedContentDir(out);
   const written = new Set;
   await Promise.all([...staged].map(async ([entryId, text]) => {
-    const path = join11(contentDir, entryId);
+    const path = join13(contentDir, entryId);
     written.add(normalize(path));
     await writeIfChanged(path, text);
   }));
-  if (existsSync6(contentDir)) {
+  if (existsSync7(contentDir)) {
     await pruneOrphans(contentDir, written);
   }
 };
@@ -6397,11 +6513,11 @@ var resolveLogo = (project) => {
   if (light && light === dark && light.toLowerCase().endsWith(".svg")) {
     const rel = light.replace(/^\//u, "");
     const file = [
-      join11(project.context.root, "public", rel),
-      join11(project.context.root, rel)
-    ].find((path) => existsSync6(path));
+      join13(project.context.root, "public", rel),
+      join13(project.context.root, rel)
+    ].find((path) => existsSync7(path));
     if (file) {
-      return { alt, href, svg: readFileSync5(file, "utf-8") };
+      return { alt, href, svg: readFileSync6(file, "utf-8") };
     }
   }
   return { alt, dark, href, light };
@@ -6425,9 +6541,9 @@ var faviconType = (name) => {
   const ext = name.split(".").pop()?.toLowerCase();
   return ext ? FAVICON_TYPES[ext] : undefined;
 };
-var inlineDataUri = (file, type) => `data:${type};base64,${readFileSync5(file).toString("base64")}`;
+var inlineDataUri = (file, type) => `data:${type};base64,${readFileSync6(file).toString("base64")}`;
 var defaultFavicon = () => ({
-  href: inlineDataUri(join11(BLUME_SRC, "assets", "icon.png"), "image/png"),
+  href: inlineDataUri(join13(BLUME_SRC, "assets", "icon.png"), "image/png"),
   type: "image/png"
 });
 var APPLE_ICON_CANDIDATES = [
@@ -6439,13 +6555,13 @@ var APPLE_ICON_CANDIDATES = [
 var resolveIconFile = (project, candidates) => {
   const { root } = project.context;
   for (const name of candidates) {
-    if (existsSync6(join11(root, "public", name))) {
+    if (existsSync7(join13(root, "public", name))) {
       return { href: `/${name}`, type: faviconType(name) };
     }
   }
   for (const name of candidates) {
-    const file = join11(root, name);
-    if (existsSync6(file)) {
+    const file = join13(root, name);
+    if (existsSync7(file)) {
       const type = faviconType(name);
       return { href: inlineDataUri(file, type ?? "image/x-icon"), type };
     }
@@ -6573,7 +6689,7 @@ var buildRuntimeData = (project) => {
 var planMcp = (project, srcDir) => {
   const { config } = project;
   const { route } = config.mcp;
-  const dir = join11(srcDir, "blume-mcp");
+  const dir = join13(srcDir, "blume-mcp");
   const base = {
     dir,
     discoveryPages: [],
@@ -6597,11 +6713,11 @@ var planMcp = (project, srcDir) => {
     ...base,
     discoveryPages: [
       {
-        entrypoint: join11(dir, "discovery.ts"),
+        entrypoint: join13(dir, "discovery.ts"),
         pattern: "/.well-known/mcp.json"
       },
       {
-        entrypoint: join11(dir, "server-card.ts"),
+        entrypoint: join13(dir, "server-card.ts"),
         pattern: "/.well-known/mcp/server-card.json"
       }
     ],
@@ -6620,11 +6736,11 @@ var writeMcpFiles = async (project, plan, write) => {
     version: data.version
   };
   await Promise.all([
-    write(join11(plan.srcDir, "generated", "mcp-data.json"), `${JSON.stringify(data)}
+    write(join13(plan.srcDir, "generated", "mcp-data.json"), `${JSON.stringify(data)}
 `),
-    write(join11(plan.srcDir, "pages", mcpPageFile(plan.route)), mcpEndpointTemplate(plan.route)),
-    write(join11(plan.dir, "discovery.ts"), staticJsonEndpointTemplate(buildMcpDiscovery(discoveryInput))),
-    write(join11(plan.dir, "server-card.ts"), staticJsonEndpointTemplate(buildMcpServerCard(discoveryInput)))
+    write(join13(plan.srcDir, "pages", mcpPageFile(plan.route)), mcpEndpointTemplate(plan.route)),
+    write(join13(plan.dir, "discovery.ts"), staticJsonEndpointTemplate(buildMcpDiscovery(discoveryInput))),
+    write(join13(plan.dir, "server-card.ts"), staticJsonEndpointTemplate(buildMcpServerCard(discoveryInput)))
   ]);
 };
 var writeAskFiles = async (project, srcDir, write) => {
@@ -6634,16 +6750,16 @@ var writeAskFiles = async (project, srcDir, write) => {
   }
   const grounded = ask.provider !== "inkeep";
   if (grounded) {
-    await write(join11(srcDir, "generated", "ask-data.json"), `${JSON.stringify(await buildAskData(project))}
+    await write(join13(srcDir, "generated", "ask-data.json"), `${JSON.stringify(await buildAskData(project))}
 `);
   }
-  await write(join11(srcDir, "pages", "api", "ask.ts"), askEndpointTemplate(resolveAskBackend(ask), grounded));
+  await write(join13(srcDir, "pages", "api", "ask.ts"), askEndpointTemplate(resolveAskBackend(ask), grounded));
 };
 var writeNotFoundPage = async (write, srcDir, pages, contentPages) => {
   if (routeIsTaken(pages, contentPages, "/404")) {
     return;
   }
-  await write(join11(srcDir, "pages", "404.astro"), notFoundPageTemplate());
+  await write(join13(srcDir, "pages", "404.astro"), notFoundPageTemplate());
 };
 var shouldGenerateChangelog = (project) => {
   const hasChangelog = project.graph.pages.some((page) => page.contentType === "changelog" && !(page.meta.draft || page.meta.sidebar.hidden));
@@ -6662,11 +6778,11 @@ var buildComponentSlots = async (componentsFile) => {
 var generateRuntime = async (project) => {
   const { context, config } = project;
   const out = context.outDir;
-  const srcDir = join11(out, "src");
-  const dataPath = join11(srcDir, "generated", "data.json");
-  const themePath = join11(srcDir, "generated", "app.css");
-  const searchClientPath = join11(srcDir, "generated", "search-client.ts");
-  const examplesPath = join11(srcDir, "generated", "examples.ts");
+  const srcDir = join13(out, "src");
+  const dataPath = join13(srcDir, "generated", "data.json");
+  const themePath = join13(srcDir, "generated", "app.css");
+  const searchClientPath = join13(srcDir, "generated", "search-client.ts");
+  const examplesPath = join13(srcDir, "generated", "examples.ts");
   const written = new Set;
   const write = (path, content) => {
     written.add(normalize(path));
@@ -6702,7 +6818,7 @@ var generateRuntime = async (project) => {
   const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   const structural = await Promise.all([
-    write(join11(out, "astro.config.mjs"), astroConfigTemplate({
+    write(join13(out, "astro.config.mjs"), astroConfigTemplate({
       aliases: resolveTsconfigAliases(context.root),
       config,
       contentRoutes: project.manifest.routes.map((route) => route.path),
@@ -6716,20 +6832,20 @@ var generateRuntime = async (project) => {
       searchClientPath,
       themePath
     })),
-    write(join11(out, "package.json"), runtimePackageTemplate(runtimeDependencies({ config, needsReact, needsSvelte, needsVue }))),
-    write(join11(out, "tsconfig.json"), runtimeTsconfigTemplate()),
-    write(join11(srcDir, "env.d.ts"), envTemplate()),
-    write(join11(srcDir, "content.config.ts"), contentConfigTemplate({ config, context, staged: hasStaged })),
-    write(join11(srcDir, "pages", "[...slug].astro"), catchAllPageTemplate({
+    write(join13(out, "package.json"), runtimePackageTemplate(runtimeDependencies({ config, needsReact, needsSvelte, needsVue }))),
+    write(join13(out, "tsconfig.json"), runtimeTsconfigTemplate()),
+    write(join13(srcDir, "env.d.ts"), envTemplate()),
+    write(join13(srcDir, "content.config.ts"), contentConfigTemplate({ config, context, staged: hasStaged })),
+    write(join13(srcDir, "pages", "[...slug].astro"), catchAllPageTemplate({
       askEnabled,
       exportEpub,
       exportPdf,
       mathEnabled: config.markdown.math,
       needsReact
     })),
-    write(join11(srcDir, "generated", "components.ts"), slotPlan.module),
-    write(join11(srcDir, "generated", "islands.ts"), islandMapTemplate(islandDiscovery.islands)),
-    write(join11(srcDir, "generated", "examples.ts"), exampleMapTemplate(exampleDiscovery.examples)),
+    write(join13(srcDir, "generated", "components.ts"), slotPlan.module),
+    write(join13(srcDir, "generated", "islands.ts"), islandMapTemplate(islandDiscovery.islands)),
+    write(join13(srcDir, "generated", "examples.ts"), exampleMapTemplate(exampleDiscovery.examples)),
     write(themePath, tailwindEntryTemplate({
       configTokens: `${buildThemeCss(config.theme)}${buildFontsCss(config.theme.fonts)}`,
       sources: [
@@ -6740,16 +6856,16 @@ var generateRuntime = async (project) => {
       userTheme
     }))
   ]);
-  await Promise.all(islandDiscovery.islands.map((island) => write(join11(srcDir, "generated", "islands", `${island.name}.astro`), islandWrapperTemplate(island))));
-  await Promise.all(slotPlan.wrappers.map((wrapper) => write(join11(srcDir, "generated", "component-slots", `${wrapper.name}.astro`), wrapper.content)));
-  await Promise.all(exampleDiscovery.examples.map((example) => write(join11(srcDir, "generated", "examples", `${exampleSlug(example.path)}.astro`), exampleWrapperTemplate(example))));
+  await Promise.all(islandDiscovery.islands.map((island) => write(join13(srcDir, "generated", "islands", `${island.name}.astro`), islandWrapperTemplate(island))));
+  await Promise.all(slotPlan.wrappers.map((wrapper) => write(join13(srcDir, "generated", "component-slots", `${wrapper.name}.astro`), wrapper.content)));
+  await Promise.all(exampleDiscovery.examples.map((example) => write(join13(srcDir, "generated", "examples", `${exampleSlug(example.path)}.astro`), exampleWrapperTemplate(example))));
   await writeAskFiles(project, srcDir, write);
   await writeMcpFiles(project, mcp, write);
   if (config.seo.og.enabled) {
-    await write(join11(srcDir, "pages", "og", "[...slug].png.ts"), ogEndpointTemplate(ogRoutes));
+    await write(join13(srcDir, "pages", "og", "[...slug].png.ts"), ogEndpointTemplate(ogRoutes));
   }
   if (shouldGenerateChangelog(project)) {
-    await write(join11(srcDir, "pages", "changelog.astro"), changelogIndexTemplate({
+    await write(join13(srcDir, "pages", "changelog.astro"), changelogIndexTemplate({
       askEnabled,
       exportEpub,
       exportPdf,
@@ -6761,27 +6877,27 @@ var generateRuntime = async (project) => {
   await write(searchClientPath, searchClientTemplate(config));
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);
-    await write(join11(srcDir, "generated", "search.json"), `${JSON.stringify(documents)}
+    await write(join13(srcDir, "generated", "search.json"), `${JSON.stringify(documents)}
 `);
-    await write(join11(srcDir, "pages", "blume-search.json.ts"), searchEndpointTemplate());
+    await write(join13(srcDir, "pages", "blume-search.json.ts"), searchEndpointTemplate());
   }
   if (config.search.provider === "mixedbread") {
-    await write(join11(srcDir, "pages", "api", "search.ts"), mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? ""));
+    await write(join13(srcDir, "pages", "api", "search.ts"), mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? ""));
   }
   const rawMarkdown = await buildRawMarkdown(project);
   await Promise.all([
-    write(join11(srcDir, "generated", "raw-markdown.json"), `${JSON.stringify(rawMarkdown)}
+    write(join13(srcDir, "generated", "raw-markdown.json"), `${JSON.stringify(rawMarkdown)}
 `),
-    write(join11(srcDir, "pages", "[...slug].md.ts"), rawMarkdownEndpointTemplate()),
-    write(join11(srcDir, "pages", "[...slug].mdx.ts"), rawMarkdownEndpointTemplate())
+    write(join13(srcDir, "pages", "[...slug].md.ts"), rawMarkdownEndpointTemplate()),
+    write(join13(srcDir, "pages", "[...slug].mdx.ts"), rawMarkdownEndpointTemplate())
   ]);
   const feeds = buildRssFeeds(project);
   if (feeds.length > 0) {
     const feedXml = Object.fromEntries(feeds.map((feed) => [feed.type, renderRssFeed(feed)]));
     await Promise.all([
-      write(join11(srcDir, "generated", "rss.json"), `${JSON.stringify(feedXml)}
+      write(join13(srcDir, "generated", "rss.json"), `${JSON.stringify(feedXml)}
 `),
-      write(join11(srcDir, "pages", "[section]", "rss.xml.ts"), rssEndpointTemplate())
+      write(join13(srcDir, "pages", "[section]", "rss.xml.ts"), rssEndpointTemplate())
     ]);
   }
   const warnings = [
@@ -6818,10 +6934,10 @@ var generateRuntime = async (project) => {
       root: context.root
     });
     warnings.push(...references.warnings);
-    await Promise.all(references.files.map((file) => write(join11(srcDir, "pages", file.pagePath), file.content)));
+    await Promise.all(references.files.map((file) => write(join13(srcDir, "pages", file.pagePath), file.content)));
   }
-  await write(join11(srcDir, "generated", "data.json"), buildRuntimeData(project));
-  await write(join11(out, "blume.manifest.json"), `${JSON.stringify(project.manifest, null, 2)}
+  await write(join13(srcDir, "generated", "data.json"), buildRuntimeData(project));
+  await write(join13(out, "blume.manifest.json"), `${JSON.stringify(project.manifest, null, 2)}
 `);
   await writeStagedContent(out, staged);
   await pruneOrphans(srcDir, written);
@@ -6829,12 +6945,44 @@ var generateRuntime = async (project) => {
 };
 
 // src/core/config.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6 } from "node:fs";
+import { existsSync as existsSync10, readFileSync as readFileSync7 } from "node:fs";
 
 // src/core/bridge.ts
-import { existsSync as existsSync7 } from "node:fs";
+import { existsSync as existsSync8 } from "node:fs";
 import { readFile as readFile9 } from "node:fs/promises";
-import { join as join12 } from "pathe";
+import { join as join14 } from "pathe";
+
+// src/migrate/mintlify/assets.ts
+var assetRefs = (config) => {
+  const refs = ["/images"];
+  const logo = config.logo;
+  if (typeof logo === "string") {
+    refs.push(logo);
+  } else if (logo) {
+    refs.push(logo.light, logo.dark);
+  }
+  const favicon = config.favicon;
+  if (typeof favicon === "string") {
+    refs.push(favicon);
+  } else if (favicon) {
+    refs.push(favicon.light, favicon.dark);
+  }
+  refs.push(config.theme?.backgroundImage, config.theme?.backgroundImageDark);
+  return refs;
+};
+var assetSegments = (config) => {
+  const segments = new Set;
+  for (const ref of assetRefs(config)) {
+    if (typeof ref !== "string" || !ref.startsWith("/")) {
+      continue;
+    }
+    const [segment] = ref.replace(/^\/+/u, "").split("/");
+    if (segment) {
+      segments.add(segment);
+    }
+  }
+  return [...segments];
+};
 
 // src/migrate/mintlify/config.ts
 import { readFile as readFile8 } from "node:fs/promises";
@@ -7503,7 +7651,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) => existsSync7(candidate));
+  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join14(root, name)).find((candidate) => existsSync8(candidate));
   if (!configFile) {
     return null;
   }
@@ -7519,11 +7667,13 @@ var detectMintlifyBridge = async (root) => {
   const variables = config.variables ?? {};
   const root_ = config.content?.root ?? ".";
   const exclude = config.content?.exclude ?? [];
+  const assets = assetSegments(config).filter((segment) => segment !== "public" && existsSync8(join14(root, segment)));
   return {
     configFile,
     raw: {
       ...config,
       content: {
+        assets,
         exclude,
         root: root_,
         sources: [
@@ -7592,8 +7742,8 @@ var createModuleLoader = () => {
 };
 
 // src/core/project.ts
-import { existsSync as existsSync8 } from "node:fs";
-import { isAbsolute as isAbsolute4, join as join13, resolve as resolve5 } from "pathe";
+import { existsSync as existsSync9 } from "node:fs";
+import { isAbsolute as isAbsolute4, join as join15, resolve as resolve5 } from "pathe";
 var CONFIG_FILENAMES = [
   "blume.config.ts",
   "blume.config.mjs",
@@ -7603,8 +7753,8 @@ var THEME_FILENAMES = ["theme.css"];
 var COMPONENTS_FILENAMES = ["components.tsx", "components.ts"];
 var firstExisting = (root, names) => {
   for (const name of names) {
-    const candidate = join13(root, name);
-    if (existsSync8(candidate)) {
+    const candidate = join15(root, name);
+    if (existsSync9(candidate)) {
       return candidate;
     }
   }
@@ -7613,14 +7763,14 @@ var firstExisting = (root, names) => {
 var findConfigFile = (root) => firstExisting(root, CONFIG_FILENAMES);
 var resolveProjectContext = (root, config) => {
   const absoluteRoot = resolve5(root);
-  const contentRoot = isAbsolute4(config.content.root) ? config.content.root : join13(absoluteRoot, config.content.root);
-  const pagesPath = join13(absoluteRoot, config.content.pages);
-  const pagesRoot = existsSync8(pagesPath) ? pagesPath : null;
+  const contentRoot = isAbsolute4(config.content.root) ? config.content.root : join15(absoluteRoot, config.content.root);
+  const pagesPath = join15(absoluteRoot, config.content.pages);
+  const pagesRoot = existsSync9(pagesPath) ? pagesPath : null;
   return {
     componentsFile: firstExisting(absoluteRoot, COMPONENTS_FILENAMES),
     configFile: findConfigFile(absoluteRoot),
     contentRoot,
-    outDir: join13(absoluteRoot, ".blume"),
+    outDir: join15(absoluteRoot, ".blume"),
     pagesRoot,
     root: absoluteRoot,
     themeFile: firstExisting(absoluteRoot, THEME_FILENAMES)
@@ -7810,6 +7960,7 @@ var contentSourceSchema = z2.discriminatedUnion("type", [
   customSourceSchema
 ]);
 var contentConfigSchema = z2.object({
+  assets: z2.array(z2.string()).default([]),
   defaultType: z2.string().default("doc"),
   exclude: z2.array(z2.string()).default(["**/_*", "**/.*"]),
   include: z2.array(z2.string()).default(["**/*.{md,mdx}"]),
@@ -8180,7 +8331,7 @@ var loadConfig = async (root, options = {}) => {
   const sourceFile = bridge?.configFile ?? configFile;
   const parsed = blumeConfigSchema.safeParse(raw ?? {});
   if (!parsed.success) {
-    const source = sourceFile && existsSync9(sourceFile) ? readFileSync6(sourceFile, "utf-8") : undefined;
+    const source = sourceFile && existsSync10(sourceFile) ? readFileSync7(sourceFile, "utf-8") : undefined;
     const diagnostics = diagnosticsFromZod(parsed.error, {
       code: "BLUME_CONFIG_INVALID",
       file: sourceFile ?? undefined,
@@ -8657,7 +8808,7 @@ var discoverFolderMeta = async (contentRoot) => {
 };
 
 // src/core/sources/normalize.ts
-import { existsSync as existsSync10, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync11, readFileSync as readFileSync8 } from "node:fs";
 import GithubSlugger from "github-slugger";
 import { extname as extname4 } from "pathe";
 var NUMERIC_PREFIX2 = /^\d+[-_.]/u;
@@ -8731,8 +8882,9 @@ var extractLinks = (body) => {
       if (target === undefined || match.index === undefined) {
         continue;
       }
+      const targetOffset = match.index + match[0].indexOf("](") + "](".length;
       links.push({
-        column: line.indexOf(target, match.index) + 1,
+        column: targetOffset + 1,
         line: lineNumber,
         target
       });
@@ -8782,7 +8934,7 @@ var normalizeEntry2 = (entry, ctx) => {
   const ext = format === "mdx" ? ".mdx" : ".md";
   const result = pageMetaSchema.safeParse(entry.data);
   if (!result.success) {
-    const source = entry.raw ?? (entry.sourcePath && existsSync10(entry.sourcePath) ? readFileSync7(entry.sourcePath, "utf-8") : undefined);
+    const source = entry.raw ?? (entry.sourcePath && existsSync11(entry.sourcePath) ? readFileSync8(entry.sourcePath, "utf-8") : undefined);
     return {
       diagnostics: diagnosticsFromZod(result.error, {
         code: "BLUME_FRONTMATTER_INVALID",
@@ -8831,15 +8983,15 @@ var normalizeEntry2 = (entry, ctx) => {
 };
 
 // src/core/sources/resolve.ts
-import { join as join22 } from "pathe";
+import { join as join24 } from "pathe";
 
 // src/core/sources/filesystem.ts
-import { existsSync as existsSync11, watch as fsWatch } from "node:fs";
+import { existsSync as existsSync12, watch as fsWatch } from "node:fs";
 import { readFile as readFile10 } from "node:fs/promises";
-import { extname as extname5, isAbsolute as isAbsolute5, join as join14, relative as relative10, resolve as resolve6 } from "pathe";
+import { extname as extname5, isAbsolute as isAbsolute5, join as join16, relative as relative10, resolve as resolve6 } from "pathe";
 import { glob as glob6 } from "tinyglobby";
 var filesystemSource = (options) => {
-  const contentRoot = isAbsolute5(options.root) ? options.root : join14(resolve6(options.projectRoot), options.root);
+  const contentRoot = isAbsolute5(options.root) ? options.root : join16(resolve6(options.projectRoot), options.root);
   const load2 = async () => {
     const files = await glob6(options.include, {
       absolute: true,
@@ -8863,7 +9015,7 @@ var filesystemSource = (options) => {
     return { diagnostics: [], entries };
   };
   const validate = () => {
-    if (!existsSync11(contentRoot)) {
+    if (!existsSync12(contentRoot)) {
       throw new BlumeError({
         code: options.missingCode ?? "BLUME_CONTENT_ROOT_MISSING",
         file: contentRoot,
@@ -8874,7 +9026,7 @@ var filesystemSource = (options) => {
     }
   };
   const watch = (onChange) => {
-    if (!existsSync11(contentRoot)) {
+    if (!existsSync12(contentRoot)) {
       return () => {};
     }
     const watcher = fsWatch(contentRoot, { recursive: true }, onChange);
@@ -8885,7 +9037,7 @@ var filesystemSource = (options) => {
     load: load2,
     name: options.name,
     prefix: options.prefix,
-    read: (ref) => readFile10(join14(contentRoot, ref), "utf-8"),
+    read: (ref) => readFile10(join16(contentRoot, ref), "utf-8"),
     staged: false,
     validate,
     watch
@@ -8894,7 +9046,7 @@ var filesystemSource = (options) => {
 
 // src/core/sources/cache.ts
 import { mkdir as mkdir3, readFile as readFile11, writeFile as writeFile3 } from "node:fs/promises";
-import { join as join15 } from "pathe";
+import { join as join17 } from "pathe";
 var hashText = (text) => {
   let hash = 5381;
   for (let i = 0;i < text.length; i += 1) {
@@ -8921,7 +9073,7 @@ var pollingWatch = (load2, intervalSeconds) => (onChange) => {
   return () => clearInterval(timer);
 };
 var snapshotCache = (cacheDir) => {
-  const file = join15(cacheDir, "entries.json");
+  const file = join17(cacheDir, "entries.json");
   return {
     read: async () => {
       try {
@@ -9135,11 +9287,12 @@ var enumerateGithub = async (github, include, doFetch) => {
   }
   const body = await res.json();
   const prefix = base ? `${base}/` : "";
-  return (body.tree ?? []).filter((node) => node.type === "blob" && node.path.startsWith(prefix)).map((node) => node.path.slice(prefix.length)).filter((rel) => matchesInclude(rel, include)).map((rel) => ({
+  const refs = (body.tree ?? []).filter((node) => node.type === "blob" && node.path.startsWith(prefix)).map((node) => node.path.slice(prefix.length)).filter((rel) => matchesInclude(rel, include)).map((rel) => ({
     editUrl: `https://github.com/${owner}/${repo}/edit/${ref}/${prefix}${rel}`,
     fetchUrl: `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${prefix}${rel}`,
     ref: rel
   }));
+  return { refs, truncated: body.truncated === true };
 };
 var mdxRemoteSource = (options, ctx) => {
   const doFetch = options.fetchImpl ?? globalThis.fetch;
@@ -9151,11 +9304,12 @@ var mdxRemoteSource = (options, ctx) => {
     }
     if (options.files && options.url) {
       const base = options.url.replace(/\/$/u, "");
-      return options.files.filter((ref) => matchesInclude(ref, options.include)).map((ref) => ({
+      const refs = options.files.filter((ref) => matchesInclude(ref, options.include)).map((ref) => ({
         editUrl: `${base}/${ref}`,
         fetchUrl: `${base}/${ref}`,
         ref
       }));
+      return { refs, truncated: false };
     }
     throw new BlumeError({
       code: "BLUME_SOURCE_MISCONFIGURED",
@@ -9181,12 +9335,40 @@ var mdxRemoteSource = (options, ctx) => {
     };
   };
   const load2 = async () => {
+    const skipped = [];
     const result = await loadWithCache(options.name, cache, async () => {
-      const refs = await enumerate();
-      return await Promise.all(refs.map(fetchEntry));
+      const { refs, truncated } = await enumerate();
+      if (truncated) {
+        skipped.push({
+          code: "BLUME_SOURCE_TRUNCATED",
+          message: `Source "${options.name}" hit GitHub's tree listing limit; some files were not enumerated. Narrow the source path or split the repo.`,
+          severity: "warning"
+        });
+      }
+      const settled = await Promise.all(refs.map(async (ref) => {
+        try {
+          return await fetchEntry(ref);
+        } catch (error) {
+          skipped.push({
+            code: "BLUME_SOURCE_FETCH_FAILED",
+            message: `Source "${options.name}" skipped "${ref.ref}" (${error.message}); the rest were imported.`,
+            severity: "warning"
+          });
+          return null;
+        }
+      }));
+      const entries = settled.filter((entry) => entry !== null);
+      if (refs.length > 0 && entries.length === 0) {
+        skipped.length = 0;
+        throw new Error(`all ${refs.length} remote file(s) failed to fetch`);
+      }
+      return entries;
     }, ctx.refresh ?? true);
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
-    return result;
+    return {
+      ...result,
+      diagnostics: [...result.diagnostics, ...skipped]
+    };
   };
   const read = async (ref) => {
     const cached3 = snapshot.get(ref);
@@ -9208,21 +9390,25 @@ var mdxRemoteSource = (options, ctx) => {
 };
 
 // src/core/sources/mintlify.ts
-import { existsSync as existsSync13, watch as fsWatch2 } from "node:fs";
+import { existsSync as existsSync14, watch as fsWatch2 } from "node:fs";
 import { readFile as readFile13 } from "node:fs/promises";
-import { isAbsolute as isAbsolute6, join as join18, relative as relative13, resolve as resolve8 } from "pathe";
+import { isAbsolute as isAbsolute7, join as join20, relative as relative14, resolve as resolve8 } from "pathe";
 import { glob as glob7 } from "tinyglobby";
 
 // src/migrate/shared.ts
-import { existsSync as existsSync12 } from "node:fs";
+import { existsSync as existsSync13 } from "node:fs";
 import { readFile as readFile12, writeFile as writeFile4 } from "node:fs/promises";
-import { join as join16 } from "pathe";
+import { isAbsolute as isAbsolute6, join as join18, relative as relative11 } from "pathe";
+var isInsideRoot2 = (root, candidate) => {
+  const rel = relative11(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute6(rel);
+};
 var writeBlumeConfig = async (root, config) => {
   const body = `import { defineConfig } from "blume";
 
 export default defineConfig(${JSON.stringify(config, null, 2)});
 `;
-  await writeFile4(join16(root, "blume.config.ts"), body, "utf-8");
+  await writeFile4(join18(root, "blume.config.ts"), body, "utf-8");
 };
 var BLUME_SCRIPTS = {
   build: "blume build",
@@ -9230,8 +9416,8 @@ var BLUME_SCRIPTS = {
   start: "blume preview"
 };
 var rewriteFrameworkScripts = async (root, cli, remove) => {
-  const pkgPath = join16(root, "package.json");
-  if (!existsSync12(pkgPath)) {
+  const pkgPath = join18(root, "package.json");
+  if (!existsSync13(pkgPath)) {
     return false;
   }
   let pkg;
@@ -9264,25 +9450,7 @@ var rewriteFrameworkScripts = async (root, cli, remove) => {
   }
   return changed;
 };
-var gitignoreKey = (line) => line.trim().replace(/\/+$/u, "");
-var ensureGitignore = async (root, entries) => {
-  const path = join16(root, ".gitignore");
-  const existing = existsSync12(path) ? await readFile12(path, "utf-8") : "";
-  const present = new Set(existing.split(`
-`).map(gitignoreKey).filter(Boolean));
-  const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
-  if (added.length === 0) {
-    return [];
-  }
-  const gap = existing.length > 0 && !existing.endsWith(`
-`) ? `
-` : "";
-  await writeFile4(path, `${existing}${gap}${added.join(`
-`)}
-`, "utf-8");
-  return added;
-};
-var leftoverFiles = (root, candidates) => candidates.filter((candidate) => existsSync12(join16(root, candidate)));
+var leftoverFiles = (root, candidates) => candidates.filter((candidate) => existsSync13(join18(root, candidate)));
 var attribute = (attrs, name) => {
   const match = attrs.match(new RegExp(`\\b${name}=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')`, "u"));
   return match?.groups?.dq ?? match?.groups?.sq;
@@ -9679,7 +9847,7 @@ var isLiteralObject = (value) => typeof value === "object" && value !== null &&
 var asLiteralArray = (value) => Array.isArray(value) ? value : undefined;
 
 // src/migrate/mintlify/content.ts
-import { dirname as dirname10, join as join17, relative as relative11 } from "pathe";
+import { dirname as dirname10, join as join19, relative as relative12 } from "pathe";
 var CALLOUT_DIRECTIVES = {
   Check: "success",
   Danger: "danger",
@@ -9715,9 +9883,9 @@ var rewriteSnippetImports = (source, options) => {
     if (/\.mdx?$/u.test(importSource)) {
       return "";
     }
-    const target = join17(options.root, importSource.replace(/^\/+/u, ""));
+    const target = join19(options.root, importSource.replace(/^\/+/u, ""));
     components.push(importSource.replace(/^\/+/u, ""));
-    let rel = relative11(dirname10(options.filePath), target);
+    let rel = relative12(dirname10(options.filePath), target);
     if (!rel.startsWith(".")) {
       rel = `./${rel}`;
     }
@@ -9907,7 +10075,7 @@ var rewriteMintlifySvgIconProps = (source) => {
 
 // src/migrate/mintlify/snippets.ts
 import { readFile as readFileFromDisk } from "node:fs/promises";
-import { dirname as dirname11, relative as relative12, resolve as resolve7 } from "pathe";
+import { dirname as dirname11, relative as relative13, resolve as resolve7 } from "pathe";
 var MARKDOWN_SNIPPET_IMPORT = /^import\s+(?<name>[$A-Z_a-z][$\w]*)\s+from\s+["'](?<source>[^"']+\.mdx?)["'];?\s*$/gmu;
 var NAMED_SNIPPET_IMPORT = /^import\s+\{(?<names>[^}]+)\}\s+from\s+["'](?<source>[^"']+\.mdx?)["'];?\s*$/gmu;
 var EXPORTED_STRING_CONST = /^export\s+const\s+(?<name>[$A-Z_a-z][$\w]*)\s*=\s*(?:"(?<double>(?:\\.|[^"\\])*)"|'(?<single>(?:\\.|[^'\\])*)'|`(?<template>(?:\\.|[^`\\])*)`)\s*;?\s*$/gmu;
@@ -9916,15 +10084,15 @@ var PLACEHOLDER = /\{(?<name>[$A-Z_a-z][$\w]*)\}/gu;
 var GLOBAL_VARIABLE = /\{\{\s*(?<name>[A-Za-z0-9-]+)\s*\}\}/gu;
 var FRONTMATTER_BLOCK = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/u;
 var USER_EXPORT = /^(?:export\s+)?(?:const|let|var)\s+user\s*=|^import\s+\{\s*user\s*\}/mu;
-var isInsideRoot2 = (root, candidate) => {
-  const rel = relative12(root, candidate);
+var isInsideRoot3 = (root, candidate) => {
+  const rel = relative13(root, candidate);
   return rel === "" || !rel.startsWith("..") && !rel.startsWith("/");
 };
 var escapeRegExp2 = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 var snippetSelfClosingTagPattern = (name) => new RegExp(`<${escapeRegExp2(name)}(?<attrs>[^>]*?)\\s*/>`, "gu");
 var snippetPairedTagPattern = (name) => new RegExp(`<${escapeRegExp2(name)}(?<attrs>[^>]*?)>[\\s\\S]*?</${escapeRegExp2(name)}>`, "gu");
 var rootRelativePath = (root, file) => {
-  const rel = relative12(root, file);
+  const rel = relative13(root, file);
   return rel ? `/${rel}` : "/";
 };
 var snippetCycleMessage = (root, file, trail) => {
@@ -9934,7 +10102,7 @@ var snippetCycleMessage = (root, file, trail) => {
 };
 var resolveSnippetPath = (options) => {
   const target = options.source.startsWith("/") ? resolve7(options.root, options.source.slice(1)) : resolve7(dirname11(options.filePath), options.source);
-  return isInsideRoot2(options.root, target) ? target : null;
+  return isInsideRoot3(options.root, target) ? target : null;
 };
 var collectImports2 = (source) => [...source.matchAll(MARKDOWN_SNIPPET_IMPORT)].flatMap((match) => {
   const name = match.groups?.name;
@@ -10127,7 +10295,7 @@ var MINTLIFY_SOURCE_IGNORES = [
   "snippets/**"
 ];
 var mintlifySource = (options) => {
-  const contentRoot = isAbsolute6(options.root) ? options.root : join18(resolve8(options.projectRoot), options.root);
+  const contentRoot = isAbsolute7(options.root) ? options.root : join20(resolve8(options.projectRoot), options.root);
   const ignore = [...new Set([...options.exclude, ...MINTLIFY_SOURCE_IGNORES])];
   const transform = (raw, file) => transformMintlifyContent(raw, {
     filePath: file,
@@ -10153,7 +10321,7 @@ var mintlifySource = (options) => {
         body: { format: "mdx", text: parsed.content },
         data: parsed.data,
         raw: result.content,
-        ref: relative13(contentRoot, file),
+        ref: relative14(contentRoot, file),
         sourcePath: file
       };
     }));
@@ -10167,7 +10335,7 @@ var mintlifySource = (options) => {
     return { diagnostics, entries };
   };
   const validate = () => {
-    if (!existsSync13(contentRoot)) {
+    if (!existsSync14(contentRoot)) {
       throw new BlumeError({
         code: "BLUME_CONTENT_ROOT_MISSING",
         file: contentRoot,
@@ -10179,11 +10347,11 @@ var mintlifySource = (options) => {
   };
   const watch = (onChange) => {
     const disposers = [];
-    if (existsSync13(contentRoot)) {
+    if (existsSync14(contentRoot)) {
       const watcher = fsWatch2(contentRoot, { recursive: true }, onChange);
       disposers.push(() => watcher.close());
     }
-    if (options.configFile && existsSync13(options.configFile)) {
+    if (options.configFile && existsSync14(options.configFile)) {
       const watcher = fsWatch2(options.configFile, onChange);
       disposers.push(() => watcher.close());
     }
@@ -10194,7 +10362,7 @@ var mintlifySource = (options) => {
     };
   };
   const read = async (ref) => {
-    const file = join18(contentRoot, ref);
+    const file = join20(contentRoot, ref);
     const result = await transform(await readFile13(file, "utf-8"), file);
     return result.content;
   };
@@ -10211,11 +10379,12 @@ var mintlifySource = (options) => {
 };
 
 // src/core/sources/notion.ts
-import { join as join20 } from "pathe";
+import { setTimeout as sleep } from "node:timers/promises";
+import { join as join22 } from "pathe";
 
 // src/core/sources/assets.ts
 import { mkdir as mkdir4, writeFile as writeFile5 } from "node:fs/promises";
-import { extname as extname6, join as join19 } from "pathe";
+import { extname as extname6, join as join21 } from "pathe";
 var MD_IMAGE = /!\[(?<alt>[^\]]*)\]\((?<url>[^)\s]+)\)/gu;
 var REMOTE = /^https?:\/\//u;
 var SAFE_EXT = /^\.[a-z0-9]+$/iu;
@@ -10244,7 +10413,7 @@ var materializeAssets = async (markdown, ctx) => {
       const bytes = new Uint8Array(await res.arrayBuffer());
       const file = `${hashText(url)}${extFor(url)}`;
       await mkdir4(ctx.assetsDir, { recursive: true });
-      await writeFile5(join19(ctx.assetsDir, file), bytes);
+      await writeFile5(join21(ctx.assetsDir, file), bytes);
       rewrites.set(url, `${ctx.assetsBaseUrl}/${file}`);
     } catch (error) {
       diagnostics.push({
@@ -10279,6 +10448,28 @@ var richToMarkdown = (rich = []) => rich.map((node) => {
   return node.href ? `[${text}](${node.href})` : text;
 }).join("");
 var blockField = (block) => block[block.type]?.rich_text ?? [];
+var RATE_LIMITED = 429;
+var MAX_RETRIES = 4;
+var BASE_DELAY_MS = 500;
+var SECOND_MS = 1000;
+var withNotionRetry = async (call) => {
+  let lastError;
+  for (let attempt = 0;attempt <= MAX_RETRIES; attempt += 1) {
+    try {
+      return await call();
+    } catch (error) {
+      lastError = error;
+      const { status } = error;
+      if (status !== RATE_LIMITED || attempt === MAX_RETRIES) {
+        throw error;
+      }
+      const retryAfter = Number(error.headers?.["retry-after"]);
+      const wait = retryAfter > 0 ? retryAfter * SECOND_MS : BASE_DELAY_MS * 2 ** attempt;
+      await sleep(wait);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("Notion request failed after retries.");
+};
 var collectAll = async (page, cursor, acc = []) => {
   const res = await page(cursor);
   const all = [...acc, ...res.results];
@@ -10338,8 +10529,8 @@ ${text}
 };
 var notionSource = (options, ctx) => {
   const props = options.properties ?? {};
-  const cache = snapshotCache(ctx?.cacheDir ?? join20(".blume", "cache", options.name));
-  const assetsDir = ctx?.assetsDir ?? join20(".blume", "public", "blume-assets", options.name);
+  const cache = snapshotCache(ctx?.cacheDir ?? join22(".blume", "cache", options.name));
+  const assetsDir = ctx?.assetsDir ?? join22(".blume", "public", "blume-assets", options.name);
   const assetsBaseUrl = ctx?.assetsBaseUrl ?? `/blume-assets/${options.name}`;
   let snapshot = new Map;
   const resolveClient = async () => {
@@ -10358,7 +10549,7 @@ var notionSource = (options, ctx) => {
     }
     return new Client({ auth: options.token ?? process.env.NOTION_TOKEN });
   };
-  const childrenOf = (client, blockId) => collectAll((cursor) => client.blocks.children.list({ block_id: blockId, start_cursor: cursor }));
+  const childrenOf = (client, blockId) => collectAll((cursor) => withNotionRetry(() => client.blocks.children.list({ block_id: blockId, start_cursor: cursor })));
   const renderContainer = async (client, block, render) => {
     const children = async (target) => {
       if (!target.has_children) {
@@ -10472,10 +10663,10 @@ ${rendered.join(`
     const assetDiagnostics = [];
     const result = await loadWithCache(options.name, cache, async () => {
       const client = await resolveClient();
-      const pages = await collectAll((cursor) => client.databases.query({
+      const pages = await collectAll((cursor) => withNotionRetry(() => client.databases.query({
         database_id: options.database,
         start_cursor: cursor
-      }));
+      })));
       const built = await Promise.all(pages.map((page) => toEntry(client, page)));
       for (const item of built) {
         assetDiagnostics.push(...item.diagnostics);
@@ -10507,7 +10698,7 @@ ${rendered.join(`
 };
 
 // src/core/sources/sanity.ts
-import { join as join21 } from "pathe";
+import { join as join23 } from "pathe";
 
 // src/core/sources/portable-text.ts
 var HEADING_STYLES = {
@@ -10646,11 +10837,11 @@ var resolveClient = async (options, preview) => {
 };
 var sanitySource = (options, ctx) => {
   const fields = options.fields ?? {};
-  const cache = snapshotCache(ctx?.cacheDir ?? join21(".blume", "cache", options.name));
+  const cache = snapshotCache(ctx?.cacheDir ?? join23(".blume", "cache", options.name));
   let snapshot = new Map;
   const toEntry = (doc) => {
     const slugValue = asString2(getPath(doc, fields.slug ?? "slug.current")) ?? asString2(doc._id) ?? "untitled";
-    const slug = slugify2(slugValue) || "untitled";
+    const slug = slugify2(slugValue) || slugify2(asString2(doc._id) ?? "") || "untitled";
     const data = {};
     const title = asString2(getPath(doc, fields.title ?? "title"));
     const description = asString2(getPath(doc, fields.description ?? "description"));
@@ -10721,8 +10912,8 @@ var uniqueNamer = () => {
 };
 var sourceContext = (context, name, runtime) => ({
   assetsBaseUrl: `/blume-assets/${name}`,
-  assetsDir: join22(context.outDir, "public", "blume-assets", name),
-  cacheDir: join22(context.outDir, "cache", name),
+  assetsDir: join24(context.outDir, "public", "blume-assets", name),
+  cacheDir: join24(context.outDir, "cache", name),
   mode: runtime.mode,
   preview: runtime.preview,
   projectRoot: context.root,
@@ -10916,8 +11107,8 @@ var scanProject = async (root, options = {}) => {
 };
 
 // src/cli/env.ts
-import { existsSync as existsSync14, readFileSync as readFileSync8 } from "node:fs";
-import { dirname as dirname12, join as join23, resolve as resolve9 } from "pathe";
+import { existsSync as existsSync15, readFileSync as readFileSync9 } from "node:fs";
+import { dirname as dirname12, join as join25, resolve as resolve9 } from "pathe";
 var ENV_LINE = /^\s*(?:export\s+)?(?<key>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?<value>.*?)\s*$/u;
 var DOUBLE_QUOTED2 = /^"(?<body>[\s\S]*)"$/u;
 var SINGLE_QUOTED = /^'(?<body>[\s\S]*)'$/u;
@@ -10955,8 +11146,8 @@ var applyEnv = (parsed) => {
 };
 var loadFile = (path) => {
   try {
-    if (existsSync14(path)) {
-      applyEnv(parseEnv(readFileSync8(path, "utf-8")));
+    if (existsSync15(path)) {
+      applyEnv(parseEnv(readFileSync9(path, "utf-8")));
     }
   } catch {}
 };
@@ -10964,10 +11155,10 @@ var loadEnvFiles = (startDir) => {
   let dir = resolve9(startDir);
   let done = false;
   while (!done) {
-    loadFile(join23(dir, ".env.local"));
-    loadFile(join23(dir, ".env"));
+    loadFile(join25(dir, ".env.local"));
+    loadFile(join25(dir, ".env"));
     const parent = dirname12(dir);
-    done = existsSync14(join23(dir, ".git")) || parent === dir;
+    done = existsSync15(join25(dir, ".git")) || parent === dir;
     dir = parent;
   }
 };
@@ -11082,29 +11273,38 @@ var prepareProject = async (options) => {
 
 // src/cli/commands/build.ts
 var ADAPTERS = ["vercel", "node", "netlify", "cloudflare"];
+var validateBudgetFlags = (args) => {
+  for (const flag of ["budget-js", "budget-css"]) {
+    const value = args[flag];
+    if (value !== undefined && !(Number(value) > 0)) {
+      logger.error(`Invalid --${flag} "${value}" (expected a positive number of kB).`);
+      process.exit(1);
+    }
+  }
+};
 var emitRedirectFiles = async (config, distDir) => {
   const { redirects } = config;
   if (redirects.length === 0 || config.deployment.output !== "static") {
     return;
   }
-  await writeFile6(join24(distDir, "blume-redirects.json"), buildRedirectManifest(redirects), "utf-8");
+  await writeFile6(join26(distDir, "blume-redirects.json"), buildRedirectManifest(redirects), "utf-8");
   const platformFiles = [
     { content: buildNetlifyRedirects(redirects), name: "_redirects" },
     { content: buildVercelConfig(redirects), name: "vercel.json" }
   ];
-  await Promise.all(platformFiles.map((file) => existsSync15(join24(distDir, file.name)) ? Promise.resolve() : writeFile6(join24(distDir, file.name), file.content, "utf-8")));
+  await Promise.all(platformFiles.map((file) => existsSync16(join26(distDir, file.name)) ? Promise.resolve() : writeFile6(join26(distDir, file.name), file.content, "utf-8")));
   logger.success(`Emitted redirect files for ${redirects.length} redirect(s)`);
 };
 var formatBytes = (bytes) => bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(bytes < 1024 * 100 ? 1 : 0)} kB`;
 var astroAssets = async (distDir, ext) => {
-  const astroDir = join24(distDir, "_astro");
-  if (!existsSync15(astroDir)) {
+  const astroDir = join26(distDir, "_astro");
+  if (!existsSync16(astroDir)) {
     return [];
   }
   const entries = await readdir(astroDir);
   const files = entries.filter((name) => name.endsWith(`.${ext}`));
   const sized = await Promise.all(files.map(async (name) => {
-    const info = await stat(join24(astroDir, name));
+    const info = await stat(join26(astroDir, name));
     return { name, size: info.size };
   }));
   return sized.toSorted((a, b) => b.size - a.size);
@@ -11184,6 +11384,7 @@ var buildCommand = defineCommand2({
   },
   async run({ args }) {
     const root = process.cwd();
+    refuseIfDevRunning(root, "building");
     if (args.output && args.output !== "static" && args.output !== "server") {
       logger.error(`Invalid --output "${args.output}" (use static | server).`);
       process.exit(1);
@@ -11192,6 +11393,7 @@ var buildCommand = defineCommand2({
       logger.error(`Invalid --adapter "${args.adapter}" (use ${ADAPTERS.join(" | ")}).`);
       process.exit(1);
     }
+    validateBudgetFlags(args);
     const project = await prepareProject({
       mode: "build",
       overrides: {
@@ -11208,7 +11410,7 @@ var buildCommand = defineCommand2({
       logLevel: "info",
       root: project.context.outDir
     });
-    const distDir = join24(root, "dist");
+    const distDir = join26(root, "dist");
     if (project.config.search.provider === "pagefind") {
       logger.start("Building search index");
       const indexed = await buildSearchIndex(distDir);
@@ -11222,19 +11424,19 @@ var buildCommand = defineCommand2({
     if (project.config.ai.llmsTxt) {
       const { index, full } = await buildLlmsFiles(project);
       await Promise.all([
-        writeFile6(join24(distDir, "llms.txt"), index, "utf-8"),
-        writeFile6(join24(distDir, "llms-full.txt"), full, "utf-8")
+        writeFile6(join26(distDir, "llms.txt"), index, "utf-8"),
+        writeFile6(join26(distDir, "llms-full.txt"), full, "utf-8")
       ]);
       logger.success("Generated llms.txt and llms-full.txt");
     }
     const sitemap = buildSitemap(project);
-    if (sitemap && !existsSync15(join24(distDir, "sitemap.xml"))) {
-      await writeFile6(join24(distDir, "sitemap.xml"), sitemap, "utf-8");
+    if (sitemap && !existsSync16(join26(distDir, "sitemap.xml"))) {
+      await writeFile6(join26(distDir, "sitemap.xml"), sitemap, "utf-8");
       logger.success("Generated sitemap.xml");
     }
     const robots = buildRobots(project);
-    if (robots && !existsSync15(join24(distDir, "robots.txt"))) {
-      await writeFile6(join24(distDir, "robots.txt"), robots, "utf-8");
+    if (robots && !existsSync16(join26(distDir, "robots.txt"))) {
+      await writeFile6(join26(distDir, "robots.txt"), robots, "utf-8");
       logger.success("Generated robots.txt");
     }
     await emitRedirectFiles(project.config, distDir);
@@ -11263,11 +11465,11 @@ var buildCommand = defineCommand2({
 });
 
 // src/cli/commands/check.ts
-import { existsSync as existsSync16 } from "node:fs";
+import { existsSync as existsSync17 } from "node:fs";
 import { check } from "@astrojs/check";
 import { sync } from "astro";
 import { defineCommand as defineCommand3 } from "citty";
-import { join as join25 } from "pathe";
+import { join as join27 } from "pathe";
 var checkCommand = defineCommand3({
   args: {
     preview: {
@@ -11293,13 +11495,13 @@ var checkCommand = defineCommand3({
     });
     const { outDir } = project.context;
     await sync({ logLevel: "warn", root: outDir });
-    const tsconfig = join25(root, "tsconfig.json");
+    const tsconfig = join27(root, "tsconfig.json");
     logger.start(`Type-checking ${project.graph.pages.length} page(s)`);
     const failed = await check({
       minimumFailingSeverity: "error",
       minimumSeverity: "hint",
       root: outDir,
-      tsconfig: existsSync16(tsconfig) ? tsconfig : undefined,
+      tsconfig: existsSync17(tsconfig) ? tsconfig : undefined,
       watch: false
     });
     if (failed) {
@@ -11315,6 +11517,9 @@ import { watch } from "node:fs";
 import { dev } from "astro";
 import { defineCommand as defineCommand4 } from "citty";
 
+// src/astro/static-assets.ts
+import { extname as extname7, join as join28, relative as relative15, resolve as resolve10, sep } from "pathe";
+
 // src/astro/integration.ts
 var overlayServer = null;
 var overlayChannel = () => overlayServer?.ws ?? overlayServer?.hot;
@@ -11348,6 +11553,20 @@ ${body}`,
   });
 };
 
+// src/cli/args.ts
+var MAX_PORT = 65535;
+var parsePort = (value) => {
+  if (value === undefined) {
+    return;
+  }
+  const port = Number(value);
+  if (!(Number.isInteger(port) && port >= 1 && port <= MAX_PORT)) {
+    logger.error(`Invalid --port "${value}" (expected an integer 1-${MAX_PORT}).`);
+    process.exit(1);
+  }
+  return port;
+};
+
 // src/cli/commands/dev.ts
 var devCommand = defineCommand4({
   args: {
@@ -11376,7 +11595,8 @@ var devCommand = defineCommand4({
     const root = process.cwd();
     const preview = args.preview ?? false;
     const overrides = args["content-dir"] ? { contentRoot: args["content-dir"] } : undefined;
-    const port = args.port ? Number(args.port) : 4321;
+    const explicitPort = parsePort(args.port);
+    const port = explicitPort ?? 4321;
     const devServerUrl = `http://localhost:${port}`;
     const project = await prepareProject({
       devServerUrl,
@@ -11389,13 +11609,15 @@ var devCommand = defineCommand4({
     if (project.bridge) {
       logger.info('Detected docs.json — running in Mintlify bridge mode (no migration). Run "blume migrate mintlify" to convert permanently.');
     }
+    const releaseLock = acquireDevLock(project.context.outDir);
+    process.on("exit", releaseLock);
     const server = await dev({
       logLevel: args.debug ? "debug" : "info",
       root: project.context.outDir,
       server: {
         host: args.host ?? false,
         open: args.open ?? false,
-        port: args.port ? Number(args.port) : undefined
+        port: explicitPort
       }
     });
     showBlumeErrorOverlay(project.diagnostics);
@@ -11436,6 +11658,7 @@ var devCommand = defineCommand4({
       for (const dispose of disposers) {
         dispose();
       }
+      releaseLock();
       await server.stop();
       process.exit(0);
     };
@@ -11505,6 +11728,7 @@ var doctorCommand = defineCommand5({
     }
     if (args.json) {
       if (reportDiagnosticsJson(diagnostics, root)) {
+        await flushStdout();
         process.exit(1);
       }
       return;
@@ -11522,12 +11746,12 @@ var doctorCommand = defineCommand5({
 // src/cli/commands/eject.ts
 import { readFile as readFile15, writeFile as writeFile8 } from "node:fs/promises";
 import { defineCommand as defineCommand6 } from "citty";
-import { join as join27, relative as relative15 } from "pathe";
+import { join as join30, relative as relative17 } from "pathe";
 
 // src/registry/eject.ts
-import { existsSync as existsSync17 } from "node:fs";
+import { existsSync as existsSync18 } from "node:fs";
 import { cp, mkdir as mkdir5, readFile as readFile14, rm as rm2, writeFile as writeFile7 } from "node:fs/promises";
-import { join as join26, relative as relative14 } from "pathe";
+import { join as join29, relative as relative16 } from "pathe";
 var POSIX = (path) => path.split("\\").join("/");
 var askFiles = async (project, srcDir, genDir) => {
   const { ask } = project.config.ai;
@@ -11538,14 +11762,14 @@ var askFiles = async (project, srcDir, genDir) => {
   const files = [
     {
       content: askEndpointTemplate(resolveAskBackend(ask), grounded),
-      path: join26(srcDir, "pages", "api", "ask.ts")
+      path: join29(srcDir, "pages", "api", "ask.ts")
     }
   ];
   if (grounded) {
     files.push({
       content: `${JSON.stringify(await buildAskData(project))}
 `,
-      path: join26(genDir, "ask-data.json")
+      path: join29(genDir, "ask-data.json")
     });
   }
   return files;
@@ -11553,8 +11777,8 @@ var askFiles = async (project, srcDir, genDir) => {
 var eject = async (root) => {
   const project = await scanProject(root, { mode: "build" });
   const { context, config } = project;
-  const srcDir = join26(root, "src");
-  const genDir = join26(srcDir, "generated");
+  const srcDir = join29(root, "src");
+  const genDir = join29(srcDir, "generated");
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
@@ -11575,13 +11799,13 @@ var eject = async (root) => {
   const needsSvelte = frameworks.has("svelte");
   const relContext = {
     ...context,
-    contentRoot: POSIX(relative14(root, context.contentRoot)),
+    contentRoot: POSIX(relative16(root, context.contentRoot)),
     outDir: ".",
     root: "."
   };
-  const componentsImport = context.componentsFile ? `../../${POSIX(relative14(root, context.componentsFile))}` : null;
+  const componentsImport = context.componentsFile ? `../../${POSIX(relative16(root, context.componentsFile))}` : null;
   const relPages = pages.map((page) => ({
-    entrypoint: POSIX(relative14(root, page.entrypoint)),
+    entrypoint: POSIX(relative16(root, page.entrypoint)),
     pattern: page.pattern
   }));
   const staged = collectStaged(project);
@@ -11602,13 +11826,14 @@ var eject = async (root) => {
         searchClientPath: "./src/generated/search-client.ts",
         themePath: "./src/generated/app.css"
       }),
-      path: join26(root, "astro.config.mjs")
+      path: join29(root, "astro.config.mjs")
     },
     {
       content: runtimeTsconfigTemplate(),
-      path: join26(root, "tsconfig.json")
+      path: join29(root, "tsconfig.json"),
+      skipIfExists: true
     },
-    { content: envTemplate(), path: join26(srcDir, "env.d.ts") },
+    { content: envTemplate(), path: join29(srcDir, "env.d.ts") },
     {
       content: contentConfigTemplate({
         config,
@@ -11616,7 +11841,7 @@ var eject = async (root) => {
         staged: hasStaged,
         stagedBase: stagedDir
       }),
-      path: join26(srcDir, "content.config.ts")
+      path: join29(srcDir, "content.config.ts")
     },
     {
       content: catchAllPageTemplate({
@@ -11626,19 +11851,19 @@ var eject = async (root) => {
         mathEnabled: config.markdown.math,
         needsReact
       }),
-      path: join26(srcDir, "pages", "[...slug].astro")
+      path: join29(srcDir, "pages", "[...slug].astro")
     },
     {
       content: planComponentSlots(componentsImport, null).module,
-      path: join26(genDir, "components.ts")
+      path: join29(genDir, "components.ts")
     },
     {
       content: islandMapTemplate(islands.islands),
-      path: join26(genDir, "islands.ts")
+      path: join29(genDir, "islands.ts")
     },
     {
       content: exampleMapTemplate(examples.examples),
-      path: join26(genDir, "examples.ts")
+      path: join29(genDir, "examples.ts")
     },
     {
       content: tailwindEntryTemplate({
@@ -11650,21 +11875,21 @@ var eject = async (root) => {
         twoslashCss: twoslashCss(),
         userTheme
       }),
-      path: join26(genDir, "app.css")
+      path: join29(genDir, "app.css")
     },
-    { content: buildRuntimeData(project), path: join26(genDir, "data.json") },
+    { content: buildRuntimeData(project), path: join29(genDir, "data.json") },
     {
       content: `${JSON.stringify(rawMarkdown)}
 `,
-      path: join26(genDir, "raw-markdown.json")
+      path: join29(genDir, "raw-markdown.json")
     },
     {
       content: rawMarkdownEndpointTemplate(),
-      path: join26(srcDir, "pages", "[...slug].md.ts")
+      path: join29(srcDir, "pages", "[...slug].md.ts")
     },
     {
       content: rawMarkdownEndpointTemplate(),
-      path: join26(srcDir, "pages", "[...slug].mdx.ts")
+      path: join29(srcDir, "pages", "[...slug].mdx.ts")
     }
   ];
   if (askEnabled) {
@@ -11673,34 +11898,34 @@ var eject = async (root) => {
   if (config.seo.og.enabled) {
     files.push({
       content: ogEndpointTemplate(customOgRoutes(pages, config.title)),
-      path: join26(srcDir, "pages", "og", "[...slug].png.ts")
+      path: join29(srcDir, "pages", "og", "[...slug].png.ts")
     });
   }
   if (!routeIsTaken(pages, project.graph.pages, "/404")) {
     files.push({
       content: notFoundPageTemplate(),
-      path: join26(srcDir, "pages", "404.astro")
+      path: join29(srcDir, "pages", "404.astro")
     });
   }
   files.push({
     content: searchClientTemplate(config),
-    path: join26(genDir, "search-client.ts")
+    path: join29(genDir, "search-client.ts")
   });
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);
     files.push({
       content: `${JSON.stringify(documents)}
 `,
-      path: join26(genDir, "search.json")
+      path: join29(genDir, "search.json")
     }, {
       content: searchEndpointTemplate(),
-      path: join26(srcDir, "pages", "blume-search.json.ts")
+      path: join29(srcDir, "pages", "blume-search.json.ts")
     });
   }
   if (config.search.provider === "mixedbread") {
     files.push({
       content: mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? ""),
-      path: join26(srcDir, "pages", "api", "search.ts")
+      path: join29(srcDir, "pages", "api", "search.ts")
     });
   }
   const feeds = buildRssFeeds(project);
@@ -11709,10 +11934,10 @@ var eject = async (root) => {
     files.push({
       content: `${JSON.stringify(feedXml)}
 `,
-      path: join26(genDir, "rss.json")
+      path: join29(genDir, "rss.json")
     }, {
       content: rssEndpointTemplate(),
-      path: join26(srcDir, "pages", "[section]", "rss.xml.ts")
+      path: join29(srcDir, "pages", "[section]", "rss.xml.ts")
     });
   }
   if (hasReferences(config)) {
@@ -11724,37 +11949,38 @@ var eject = async (root) => {
     for (const file of references.files) {
       files.push({
         content: file.content,
-        path: join26(srcDir, "pages", file.pagePath)
+        path: join29(srcDir, "pages", file.pagePath)
       });
     }
   }
   files.push(...islands.islands.map((island) => ({
     content: islandWrapperTemplate(island),
-    path: join26(genDir, "islands", `${island.name}.astro`)
+    path: join29(genDir, "islands", `${island.name}.astro`)
   })), ...examples.examples.map((example) => ({
     content: exampleWrapperTemplate(example),
-    path: join26(genDir, "examples", `${exampleSlug(example.path)}.astro`)
+    path: join29(genDir, "examples", `${exampleSlug(example.path)}.astro`)
   })));
   for (const [entryId, content] of staged) {
-    files.push({ content, path: join26(root, stagedDir, entryId) });
+    files.push({ content, path: join29(root, stagedDir, entryId) });
   }
-  await Promise.all(files.map(async (file) => {
-    await mkdir5(join26(file.path, ".."), { recursive: true });
+  const written = files.filter((file) => !(file.skipIfExists && existsSync18(file.path)));
+  await Promise.all(written.map(async (file) => {
+    await mkdir5(join29(file.path, ".."), { recursive: true });
     await writeFile7(file.path, file.content, "utf-8");
   }));
-  const assetsSrc = join26(context.outDir, "public", "blume-assets");
-  if (existsSync17(assetsSrc)) {
-    await cp(assetsSrc, join26(root, "public", "blume-assets"), {
+  const assetsSrc = join29(context.outDir, "public", "blume-assets");
+  if (existsSync18(assetsSrc)) {
+    await cp(assetsSrc, join29(root, "public", "blume-assets"), {
       recursive: true
     });
   }
   await rm2(context.outDir, { force: true, recursive: true });
-  return files.map((file) => file.path);
+  return written.map((file) => file.path);
 };
 
 // src/cli/commands/eject.ts
 var updatePackageScripts = async (root) => {
-  const pkgPath = join27(root, "package.json");
+  const pkgPath = join30(root, "package.json");
   let pkg;
   try {
     pkg = JSON.parse(await readFile15(pkgPath, "utf-8"));
@@ -11781,8 +12007,9 @@ var ejectCommand = defineCommand6({
   },
   async run({ args }) {
     const root = process.cwd();
+    refuseIfDevRunning(root, "ejecting");
     if (!args.yes) {
-      logger.warn("Eject is one-way: it writes astro.config.mjs and src/ into your project and removes .blume.");
+      logger.warn("Eject is one-way: it writes astro.config.mjs, src/, and (if absent) tsconfig.json, rewrites your package.json scripts, and removes .blume. An existing tsconfig.json is left untouched.");
       logger.info("Re-run with --yes to proceed.");
       return;
     }
@@ -11790,7 +12017,7 @@ var ejectCommand = defineCommand6({
     await updatePackageScripts(root);
     logger.success(`Ejected ${files.length} file(s):`);
     for (const file of files) {
-      process.stdout.write(`  ${relative15(root, file)}
+      process.stdout.write(`  ${relative17(root, file)}
 `);
     }
     logger.box(`Your project is now a standalone Astro app.
@@ -11803,10 +12030,35 @@ The blume package remains importable.`);
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync18 } from "node:fs";
-import { mkdir as mkdir6, writeFile as writeFile9 } from "node:fs/promises";
+import { existsSync as existsSync20 } from "node:fs";
+import { mkdir as mkdir6, writeFile as writeFile10 } from "node:fs/promises";
 import { defineCommand as defineCommand7 } from "citty";
-import { basename as basename4, dirname as dirname13, join as join28 } from "pathe";
+import { basename as basename4, dirname as dirname13, isAbsolute as isAbsolute8, join as join32, relative as relative18 } from "pathe";
+
+// src/core/gitignore.ts
+import { existsSync as existsSync19 } from "node:fs";
+import { readFile as readFile16, writeFile as writeFile9 } from "node:fs/promises";
+import { join as join31 } from "pathe";
+var gitignoreKey = (line) => line.trim().replace(/\/+$/u, "");
+var ensureGitignore = async (root, entries) => {
+  const path = join31(root, ".gitignore");
+  const existing = existsSync19(path) ? await readFile16(path, "utf-8") : "";
+  const present = new Set(existing.split(`
+`).map(gitignoreKey).filter(Boolean));
+  const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
+  if (added.length === 0) {
+    return [];
+  }
+  const gap = existing.length > 0 && !existing.endsWith(`
+`) ? `
+` : "";
+  await writeFile9(path, `${existing}${gap}${added.join(`
+`)}
+`, "utf-8");
+  return added;
+};
+
+// src/cli/commands/init.ts
 var toPackageName = (raw) => raw.toLowerCase().replaceAll(/[^a-z0-9._-]+/gu, "-").replaceAll(/^[-_.]+|[-_.]+$/gu, "") || "docs";
 var packageTemplate = (name, version) => `{
   "name": ${JSON.stringify(name)},
@@ -11854,7 +12106,7 @@ var STARTERS = {
     files: (dir) => [
       {
         content: page("API Reference", "Explore the API.", "# API Reference\n\nYour OpenAPI spec renders at [`/api`](/api). Point `openapi.sources` at your own spec in `blume.config.ts`."),
-        path: join28(dir, "index.mdx")
+        path: join32(dir, "index.mdx")
       }
     ]
   },
@@ -11869,7 +12121,7 @@ var STARTERS = {
     files: (dir) => [
       {
         content: page("Introduction", "Welcome to your new Blume docs.", "# Introduction\n\nWrite your docs here, and log releases under `changelog/`."),
-        path: join28(dir, "index.mdx")
+        path: join32(dir, "index.mdx")
       },
       {
         content: `---
@@ -11880,7 +12132,7 @@ date: 2026-01-01
 
 The first release. Edit \`${dir}/changelog/v1-0-0.mdx\` or add new entries beside it.
 `,
-        path: join28(dir, "changelog", "v1-0-0.mdx")
+        path: join32(dir, "changelog", "v1-0-0.mdx")
       }
     ]
   },
@@ -11893,7 +12145,7 @@ The first release. Edit \`${dir}/changelog/v1-0-0.mdx\` or add new entries besid
 Welcome to **Blume** — markdown-first docs powered by Astro and Vite.
 
 Edit \`${dir}/index.mdx\` to get started, then run \`blume dev\`.`),
-        path: join28(dir, "index.mdx")
+        path: join32(dir, "index.mdx")
       }
     ]
   },
@@ -11904,11 +12156,11 @@ Edit \`${dir}/index.mdx\` to get started, then run \`blume dev\`.`),
         content: page("Introduction", "Get started with the SDK.", `# Introduction
 
 Install the SDK and make your first call. See [Installation](/installation).`),
-        path: join28(dir, "index.mdx")
+        path: join32(dir, "index.mdx")
       },
       {
         content: page("Installation", "Install the SDK.", "# Installation\n\n```package-install\nyour-sdk\n```"),
-        path: join28(dir, "installation.mdx")
+        path: join32(dir, "installation.mdx")
       }
     ]
   }
@@ -11918,12 +12170,12 @@ var commandsFor = (pm) => ({
   install: `${pm} install`
 });
 var writeFileSafe = async (path, content) => {
-  if (existsSync18(path)) {
+  if (existsSync20(path)) {
     logger.info(`Skipped existing ${path}`);
     return false;
   }
   await mkdir6(dirname13(path), { recursive: true });
-  await writeFile9(path, content, "utf-8");
+  await writeFile10(path, content, "utf-8");
   logger.success(`Created ${path}`);
   return true;
 };
@@ -11955,6 +12207,10 @@ var initCommand = defineCommand7({
   async run({ args }) {
     const root = process.cwd();
     const contentDir = args["content-dir"] ?? "docs";
+    if (isAbsolute8(contentDir) || relative18(root, join32(root, contentDir)).startsWith("..")) {
+      logger.error(`Invalid --content-dir "${contentDir}" (must be a path inside the project).`);
+      process.exit(1);
+    }
     const template = args.template ?? "docs";
     if (!TEMPLATES.includes(template)) {
       logger.error(`Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`);
@@ -11966,9 +12222,13 @@ var initCommand = defineCommand7({
       process.exit(1);
     }
     const starter = STARTERS[template];
-    const createdPackage = await writeFileSafe(join28(root, "package.json"), packageTemplate(toPackageName(basename4(root)), getBlumeVersion()));
-    await writeFileSafe(join28(root, "blume.config.ts"), starter.config);
-    await Promise.all(starter.files(contentDir).map((file) => writeFileSafe(join28(root, file.path), file.content)));
+    const createdPackage = await writeFileSafe(join32(root, "package.json"), packageTemplate(toPackageName(basename4(root)), getBlumeVersion()));
+    await writeFileSafe(join32(root, "blume.config.ts"), starter.config);
+    await Promise.all(starter.files(contentDir).map((file) => writeFileSafe(join32(root, file.path), file.content)));
+    const ignored = await ensureGitignore(root, [".blume/", "dist/"]);
+    if (ignored.length > 0) {
+      logger.success(`Added ${ignored.join(", ")} to .gitignore`);
+    }
     const commands = commandsFor(pm);
     if (args.eject) {
       try {
@@ -12005,15 +12265,15 @@ var initCommand = defineCommand7({
 import { defineCommand as defineCommand8 } from "citty";
 
 // src/migrate/fumadocs/index.ts
-import { existsSync as existsSync22 } from "node:fs";
-import { mkdir as mkdir8, readFile as readFile17, rename as rename3, rm as rm3, writeFile as writeFile11 } from "node:fs/promises";
-import { dirname as dirname16, join as join31, relative as relative16 } from "pathe";
+import { existsSync as existsSync24 } from "node:fs";
+import { mkdir as mkdir8, readFile as readFile18, rename as rename3, rm as rm3, writeFile as writeFile12 } from "node:fs/promises";
+import { dirname as dirname16, join as join35, relative as relative19 } from "pathe";
 import { glob as glob8 } from "tinyglobby";
 
 // src/migrate/fumadocs/config.ts
-import { existsSync as existsSync19 } from "node:fs";
-import { readFile as readFile16 } from "node:fs/promises";
-import { basename as basename5, dirname as dirname14, join as join29 } from "pathe";
+import { existsSync as existsSync21 } from "node:fs";
+import { readFile as readFile17 } from "node:fs/promises";
+import { basename as basename5, dirname as dirname14, join as join33 } from "pathe";
 var SOURCE_FILES = [
   "lib/source.ts",
   "app/source.ts",
@@ -12043,7 +12303,7 @@ var GENERIC_NAMES = new Set([
 var gitRepoRoot = (start) => {
   let dir = start;
   for (;; ) {
-    if (existsSync19(join29(dir, ".git"))) {
+    if (existsSync21(join33(dir, ".git"))) {
       return dir;
     }
     const parent = dirname14(dir);
@@ -12055,12 +12315,12 @@ var gitRepoRoot = (start) => {
 };
 var bareName = (name) => name.includes("/") ? name.slice(name.lastIndexOf("/") + 1) : name;
 var readTitle = async (root) => {
-  const packageJson = join29(root, "package.json");
-  if (!existsSync19(packageJson)) {
+  const packageJson = join33(root, "package.json");
+  if (!existsSync21(packageJson)) {
     return "Documentation";
   }
   try {
-    const parsed = JSON.parse(await readFile16(packageJson, "utf-8"));
+    const parsed = JSON.parse(await readFile17(packageJson, "utf-8"));
     const { name } = parsed;
     if (typeof name !== "string" || !name.trim()) {
       return "Documentation";
@@ -12081,11 +12341,11 @@ var readTitle = async (root) => {
 };
 var scrapeBaseUrl = async (root) => {
   for (const candidate of SOURCE_FILES) {
-    const file = join29(root, candidate);
-    if (!existsSync19(file)) {
+    const file = join33(root, candidate);
+    if (!existsSync21(file)) {
       continue;
     }
-    const base = BASE_URL.exec(await readFile16(file, "utf-8"))?.groups?.base;
+    const base = BASE_URL.exec(await readFile17(file, "utf-8"))?.groups?.base;
     if (base) {
       return base;
     }
@@ -12114,9 +12374,9 @@ var loadFumadocsConfig = async (root) => {
 };
 
 // src/migrate/fumadocs/content.ts
-import { existsSync as existsSync20 } from "node:fs";
+import { existsSync as existsSync22 } from "node:fs";
 import { readFile as readFileFromDisk2 } from "node:fs/promises";
-import { dirname as dirname15, resolve as resolve10 } from "pathe";
+import { dirname as dirname15, resolve as resolve11 } from "pathe";
 var FUMADOCS_IMPORT = /^import\s+[\s\S]*?\s+from\s+["']fumadocs-(?:ui|core|mdx)(?:\/[^"']*)?["'];?[ \t]*\n?/gmu;
 var stripFumadocsImports = (source) => {
   const stripped = source.replace(FUMADOCS_IMPORT, "");
@@ -12317,12 +12577,16 @@ var inlineFumadocsIncludes = async (source, options) => {
     if (!rawPath) {
       continue;
     }
-    const target = resolve10(dirname15(options.filePath), rawPath);
+    const target = resolve11(dirname15(options.filePath), rawPath);
+    if (!isInsideRoot2(options.root, target)) {
+      warnings.push(`<include> target "${rawPath}" is outside the docs tree — left as-is.`);
+      continue;
+    }
     if (seen.has(target)) {
       warnings.push(`Circular <include> "${rawPath}" — left as-is.`);
       continue;
     }
-    if (!existsSync20(target)) {
+    if (!existsSync22(target)) {
       warnings.push(`<include> target "${rawPath}" not found — left as-is.`);
       continue;
     }
@@ -12354,9 +12618,9 @@ var normalizeFumadocsPageMeta = (value) => {
 };
 
 // src/migrate/fumadocs/groups.ts
-import { existsSync as existsSync21, statSync as statSync2 } from "node:fs";
-import { mkdir as mkdir7, rename as rename2, writeFile as writeFile10 } from "node:fs/promises";
-import { basename as basename6, join as join30 } from "pathe";
+import { existsSync as existsSync23, statSync as statSync2 } from "node:fs";
+import { mkdir as mkdir7, rename as rename2, writeFile as writeFile11 } from "node:fs/promises";
+import { basename as basename6, join as join34 } from "pathe";
 
 // src/migrate/fumadocs/meta.ts
 var SEPARATOR = /^---(?<label>.*)---$/u;
@@ -12501,13 +12765,16 @@ var isDirectory = (path) => {
   }
 };
 var resolveEntry = (docsDir, name) => {
+  if (!isInsideRoot2(docsDir, join34(docsDir, name))) {
+    return null;
+  }
   for (const ext of PAGE_EXTS) {
-    const file = join30(docsDir, `${name}${ext}`);
-    if (existsSync21(file)) {
+    const file = join34(docsDir, `${name}${ext}`);
+    if (existsSync23(file)) {
       return { kind: "file", path: file };
     }
   }
-  const folder = join30(docsDir, name);
+  const folder = join34(docsDir, name);
   return isDirectory(folder) ? { kind: "folder", path: folder } : null;
 };
 var humanize2 = (name) => name.split(WORD_SPLIT3).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
@@ -12542,8 +12809,8 @@ var moveItemIntoGroup = async (item, docsDir, groupDir, label, warnings) => {
     warnings.push(`Sidebar entry "${item.name}" in section "${label}" matched no page or folder; skipped.`);
     return null;
   }
-  const dest = join30(groupDir, basename6(resolved.path));
-  if (existsSync21(dest)) {
+  const dest = join34(groupDir, basename6(resolved.path));
+  if (existsSync23(dest)) {
     warnings.push(`Skipped moving "${item.name}" into section "${label}" (target already exists).`);
     return null;
   }
@@ -12570,7 +12837,7 @@ var reshapeSection = async (section, docsDir, order, warnings) => {
     }
     return;
   }
-  const groupDir = join30(docsDir, `(${section.label})`);
+  const groupDir = join34(docsDir, `(${section.label})`);
   const sectionKeys = [];
   for (const item of section.items) {
     const key = await moveItemIntoGroup(item, docsDir, groupDir, section.label, warnings);
@@ -12583,7 +12850,7 @@ var reshapeSection = async (section, docsDir, order, warnings) => {
   }
   order.push(section.label);
   if (sectionKeys.length > 1) {
-    await writeFile10(join30(groupDir, "meta.ts"), renderMetaModule({ pages: sectionKeys }), "utf-8");
+    await writeFile11(join34(groupDir, "meta.ts"), renderMetaModule({ pages: sectionKeys }), "utf-8");
   }
 };
 var reshapeFumadocsGroups = async (structure, docsDir) => {
@@ -12615,9 +12882,9 @@ var FUMADOCS_LEFTOVERS = [
   "app"
 ];
 var movePage = async (abs, base, root) => {
-  const rel = relative16(base, abs);
-  const dest = join31(root, "docs", rel);
-  if (existsSync22(dest)) {
+  const rel = relative19(base, abs);
+  const dest = join35(root, "docs", rel);
+  if (existsSync24(dest)) {
     return {
       includeWarnings: [],
       moved: 0,
@@ -12626,8 +12893,11 @@ var movePage = async (abs, base, root) => {
       unsupported: []
     };
   }
-  const raw = await readFile17(abs, "utf-8");
-  const included = await inlineFumadocsIncludes(raw, { filePath: abs });
+  const raw = await readFile18(abs, "utf-8");
+  const included = await inlineFumadocsIncludes(raw, {
+    filePath: abs,
+    root: base
+  });
   let text = stripFumadocsImports(included.content);
   text = rewriteFumadocsCallouts(text);
   text = rewriteFumadocsContainers(text);
@@ -12637,7 +12907,7 @@ var movePage = async (abs, base, root) => {
   const { data, removed } = normalizeFumadocsPageMeta(parsed.data);
   const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
   await mkdir8(dirname16(dest), { recursive: true });
-  await writeFile11(dest, content, "utf-8");
+  await writeFile12(dest, content, "utf-8");
   await rm3(abs, { force: true });
   return {
     includeWarnings: included.warnings,
@@ -12651,22 +12921,22 @@ var writeMeta = async (dest, meta, rel, warnings) => {
   if (Object.keys(meta).length === 0) {
     return warnings;
   }
-  if (existsSync22(dest)) {
+  if (existsSync24(dest)) {
     return [...warnings, `Skipped ${rel} (target already exists)`];
   }
   await mkdir8(dirname16(dest), { recursive: true });
-  await writeFile11(dest, renderMetaModule(meta), "utf-8");
+  await writeFile12(dest, renderMetaModule(meta), "utf-8");
   return warnings;
 };
 var convertMeta = async (abs, base, root) => {
-  const rel = relative16(base, abs);
-  const raw = await readFile17(abs, "utf-8");
+  const rel = relative19(base, abs);
+  const raw = await readFile18(abs, "utf-8");
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch {
-    const dest2 = join31(root, "docs", rel);
-    if (existsSync22(dest2)) {
+    const dest2 = join35(root, "docs", rel);
+    if (existsSync24(dest2)) {
       return [`Skipped ${rel} (target already exists)`];
     }
     await mkdir8(dirname16(dest2), { recursive: true });
@@ -12676,10 +12946,10 @@ var convertMeta = async (abs, base, root) => {
     ];
   }
   const dir = dirname16(rel) === "." ? "" : dirname16(rel);
-  const docsDir = join31(root, "docs", dir);
-  const dest = join31(docsDir, "meta.ts");
+  const docsDir = join35(root, "docs", dir);
+  const dest = join35(docsDir, "meta.ts");
   const structure = parseFumadocsPages(parsed.pages);
-  if (structure.hasSections && !existsSync22(dest)) {
+  if (structure.hasSections && !existsSync24(dest)) {
     const self = translateFumadocsSelfMeta(parsed);
     const reshape = await reshapeFumadocsGroups(structure, docsDir);
     const meta2 = { ...self.meta };
@@ -12726,8 +12996,8 @@ var summarizePages = (results) => {
   };
 };
 var cleanupSourceDirs = async (root) => {
-  const docs = join31(root, "content", "docs");
-  if (existsSync22(docs)) {
+  const docs = join35(root, "content", "docs");
+  if (existsSync24(docs)) {
     const remaining = await glob8(["**/*"], { cwd: docs, dot: true });
     if (remaining.length > 0) {
       return [
@@ -12736,8 +13006,8 @@ var cleanupSourceDirs = async (root) => {
     }
     await rm3(docs, { force: true, recursive: true });
   }
-  const content = join31(root, "content");
-  if (existsSync22(content)) {
+  const content = join35(root, "content");
+  if (existsSync24(content)) {
     const remaining = await glob8(["**/*"], { cwd: content, dot: true });
     if (remaining.length === 0) {
       await rm3(content, { force: true, recursive: true });
@@ -12747,8 +13017,8 @@ var cleanupSourceDirs = async (root) => {
 };
 var migrateFumadocsProject = async (root) => {
   const { config, warnings: configWarnings } = await loadFumadocsConfig(root);
-  const base = join31(root, SOURCE_DIR);
-  if (!existsSync22(base)) {
+  const base = join35(root, SOURCE_DIR);
+  if (!existsSync24(base)) {
     await writeBlumeConfig(root, config);
     return {
       moved: 0,
@@ -12806,9 +13076,9 @@ var migrateFumadocsProject = async (root) => {
 };
 
 // src/migrate/mintlify/index.ts
-import { existsSync as existsSync23 } from "node:fs";
-import { mkdir as mkdir9, readFile as readFile18, rename as rename4, rm as rm4, writeFile as writeFile12 } from "node:fs/promises";
-import { dirname as dirname17, join as join32 } from "pathe";
+import { existsSync as existsSync25 } from "node:fs";
+import { mkdir as mkdir9, readFile as readFile19, rename as rename4, rm as rm4, stat as stat2, writeFile as writeFile13 } from "node:fs/promises";
+import { dirname as dirname17, join as join36 } from "pathe";
 import { glob as glob9 } from "tinyglobby";
 var prune = (value) => {
   if (Array.isArray(value)) {
@@ -12838,38 +13108,48 @@ var writeBlumeConfig2 = async (root, config) => {
 
 export default defineConfig(${JSON.stringify(prune(config), null, 2)});
 `;
-  await writeFile12(join32(root, "blume.config.ts"), body, "utf-8");
+  await writeFile13(join36(root, "blume.config.ts"), body, "utf-8");
 };
-var relocateAssets = async (root, refs) => {
-  const segments = new Set;
-  for (const ref of refs) {
-    if (typeof ref !== "string" || !ref.startsWith("/")) {
-      continue;
-    }
-    const [segment] = ref.replace(/^\/+/u, "").split("/");
-    if (segment) {
-      segments.add(segment);
-    }
-  }
+var relocateAssets = async (root, segments) => {
+  const served = [];
   const moved = [];
   for (const segment of segments) {
-    const source = join32(root, segment);
-    if (!existsSync23(source) || segment === "public") {
+    const source = join36(root, segment);
+    if (!existsSync25(source) || segment === "public") {
       continue;
     }
-    const dest = join32(root, "public", segment);
-    if (existsSync23(dest)) {
+    const stats = await stat2(source);
+    if (stats.isDirectory()) {
+      served.push(segment);
       continue;
     }
-    await mkdir9(join32(root, "public"), { recursive: true });
+    const dest = join36(root, "public", segment);
+    if (existsSync25(dest)) {
+      continue;
+    }
+    await mkdir9(join36(root, "public"), { recursive: true });
     await rename4(source, dest);
     moved.push(segment);
   }
-  return moved;
+  return { moved, served };
+};
+var applyRelocatedAssets = (config, assets, warnings) => {
+  if (assets.served.length > 0) {
+    config.content = {
+      ...config.content,
+      assets: [
+        ...new Set([...config.content?.assets ?? [], ...assets.served])
+      ]
+    };
+    warnings.push(`Kept asset dir(s) in place, served via content.assets: ${assets.served.join(", ")}.`);
+  }
+  if (assets.moved.length > 0) {
+    warnings.push(`Moved assets into public/: ${assets.moved.join(", ")}.`);
+  }
 };
 var cleanupSnippets = async (root, kept, warnings) => {
-  const dir = join32(root, "snippets");
-  if (!existsSync23(dir)) {
+  const dir = join36(root, "snippets");
+  if (!existsSync25(dir)) {
     return;
   }
   const markdown = await glob9(["**/*.{md,mdx}"], { absolute: true, cwd: dir });
@@ -12887,30 +13167,13 @@ var cleanupSnippets = async (root, kept, warnings) => {
     warnings.push(`Rewrote ${kept.size} component snippet import(s) to relative paths; verify they resolve.`);
   }
 };
-var assetRefs = (config) => {
-  const refs = ["/images"];
-  const logo = config.logo;
-  if (typeof logo === "string") {
-    refs.push(logo);
-  } else if (logo) {
-    refs.push(logo.light, logo.dark);
-  }
-  const favicon = config.favicon;
-  if (typeof favicon === "string") {
-    refs.push(favicon);
-  } else if (favicon) {
-    refs.push(favicon.light, favicon.dark);
-  }
-  refs.push(config.theme?.backgroundImage, config.theme?.backgroundImageDark);
-  return refs;
-};
 var migrateMintlifyProject = async (root) => {
   const warnings = [];
-  const configFile = existsSync23(join32(root, "docs.json")) ? join32(root, "docs.json") : join32(root, "mint.json");
+  const configFile = existsSync25(join36(root, "docs.json")) ? join36(root, "docs.json") : join36(root, "mint.json");
   let config;
-  if (existsSync23(configFile)) {
+  if (existsSync25(configFile)) {
     config = await loadMintlifyConfig(root, configFile);
-    const spec = JSON.parse(await readFile18(configFile, "utf-8"));
+    const spec = JSON.parse(await readFile19(configFile, "utf-8"));
     const i18n = mintlifyI18n(spec);
     if (i18n) {
       config.i18n = i18n;
@@ -12941,7 +13204,7 @@ var migrateMintlifyProject = async (root) => {
   const unsupported = new Set;
   const keptComponents = new Set;
   for (const file of files) {
-    const raw = await readFile18(file, "utf-8");
+    const raw = await readFile19(file, "utf-8");
     const result = await transformMintlifyContent(raw, {
       filePath: file,
       root,
@@ -12949,7 +13212,7 @@ var migrateMintlifyProject = async (root) => {
     });
     if (result.content !== raw) {
       await mkdir9(dirname17(file), { recursive: true });
-      await writeFile12(file, result.content, "utf-8");
+      await writeFile13(file, result.content, "utf-8");
     }
     for (const key of result.removed) {
       removedKeys.add(key);
@@ -12962,18 +13225,16 @@ var migrateMintlifyProject = async (root) => {
     }
     moved += 1;
   }
-  const movedAssets = await relocateAssets(root, assetRefs(config));
+  const assets = await relocateAssets(root, assetSegments(config));
   await cleanupSnippets(root, keptComponents, warnings);
   if (config.content?.exclude) {
     config.content.exclude = [...new Set(config.content.exclude)];
   }
+  applyRelocatedAssets(config, assets, warnings);
   await writeBlumeConfig2(root, config);
   if (Object.keys(variables).length > 0) {
     warnings.push(`Inlined ${Object.keys(variables).length} docs.json variable(s) into content; Blume has no runtime variable substitution.`);
   }
-  if (movedAssets.length > 0) {
-    warnings.push(`Moved assets into public/: ${movedAssets.join(", ")}.`);
-  }
   if (removedKeys.size > 0) {
     warnings.push(`Dropped unsupported page frontmatter keys: ${[...removedKeys].join(", ")}.`);
   }
@@ -12985,9 +13246,9 @@ var migrateMintlifyProject = async (root) => {
 };
 
 // src/migrate/nextra/index.ts
-import { existsSync as existsSync24 } from "node:fs";
-import { mkdir as mkdir10, readFile as readFile19, rename as rename5, rm as rm5, writeFile as writeFile13 } from "node:fs/promises";
-import { basename as basename7, dirname as dirname18, extname as extname7, join as join33, relative as relative17 } from "pathe";
+import { existsSync as existsSync26 } from "node:fs";
+import { mkdir as mkdir10, readFile as readFile20, rename as rename5, rm as rm5, writeFile as writeFile14 } from "node:fs/promises";
+import { basename as basename7, dirname as dirname18, extname as extname8, join as join37, relative as relative20 } from "pathe";
 import { glob as glob10 } from "tinyglobby";
 
 // src/migrate/nextra/content.ts
@@ -13222,7 +13483,7 @@ var indexFolders = (base, pageFiles, metaFiles) => {
     }
   };
   for (const abs of pageFiles) {
-    const rel = relative17(base, abs);
+    const rel = relative20(base, abs);
     const dir = normalizeDir(dirname18(rel));
     const slug = basename7(rel).replace(/\.mdx?$/u, "");
     const folder = pagesByDir.get(dir) ?? new Map;
@@ -13231,7 +13492,7 @@ var indexFolders = (base, pageFiles, metaFiles) => {
     registerDir(dir);
   }
   for (const abs of metaFiles) {
-    registerDir(normalizeDir(dirname18(relative17(base, abs))));
+    registerDir(normalizeDir(dirname18(relative20(base, abs))));
   }
   const childDirs = new Map;
   for (const dir of allDirs) {
@@ -13269,7 +13530,7 @@ var planMetas = (metas, index) => {
     plan.metaByDir.set(dir, conversion.folderMeta);
     plan.consumedMetas.push(meta.abs);
     for (const [slug, title] of Object.entries(conversion.folderTitles)) {
-      plan.folderTitleByDir.set(normalizeDir(join33(dir, slug)), title);
+      plan.folderTitleByDir.set(normalizeDir(join37(dir, slug)), title);
     }
     for (const [slug, label] of Object.entries(conversion.pageLabels)) {
       const pageAbs = index.pagesByDir.get(dir)?.get(slug);
@@ -13293,19 +13554,19 @@ var planMetas = (metas, index) => {
   return plan;
 };
 var movePage2 = async (abs, options) => {
-  const rel = relative17(options.base, abs);
-  const dest = join33(options.root, "docs", rel);
-  if (existsSync24(dest)) {
+  const rel = relative20(options.base, abs);
+  const dest = join37(options.root, "docs", rel);
+  if (existsSync26(dest)) {
     return { moved: 0, removed: [], skipped: rel, unsupported: [] };
   }
-  const raw = await readFile19(abs, "utf-8");
+  const raw = await readFile20(abs, "utf-8");
   const text = rewriteNextraCallouts(stripNextraImports(raw));
   const unsupported = unsupportedNextraComponents(text);
   const parsed = frontmatter_default(text);
   const { data, removed } = normalizeNextraPageMeta(parsed.data, options.overrides.get(abs) ?? {});
   const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
   await mkdir10(dirname18(dest), { recursive: true });
-  await writeFile13(dest, content, "utf-8");
+  await writeFile14(dest, content, "utf-8");
   await rm5(abs, { force: true });
   return { moved: 1, removed, skipped: null, unsupported };
 };
@@ -13347,9 +13608,9 @@ var writeFolderMetas = async (root, plan) => {
     if (Object.keys(finalMeta).length === 0) {
       return;
     }
-    const dest = join33(root, "docs", dir, "meta.ts");
+    const dest = join37(root, "docs", dir, "meta.ts");
     await mkdir10(dirname18(dest), { recursive: true });
-    await writeFile13(dest, `import { defineMeta } from "blume";
+    await writeFile14(dest, `import { defineMeta } from "blume";
 
 export default defineMeta(${JSON.stringify(finalMeta, null, 2)});
 `, "utf-8");
@@ -13358,8 +13619,8 @@ export default defineMeta(${JSON.stringify(finalMeta, null, 2)});
 var relocateUnparseableMetas = async (root, metas) => {
   const warnings = [];
   await Promise.all(metas.map(async ({ abs, rel }) => {
-    const dest = join33(root, "docs", rel);
-    if (existsSync24(dest)) {
+    const dest = join37(root, "docs", rel);
+    if (existsSync26(dest)) {
       warnings.push(`Skipped ${rel} (target already exists)`);
       return;
     }
@@ -13371,7 +13632,7 @@ var relocateUnparseableMetas = async (root, metas) => {
 };
 var buildConfig = (tabs) => tabs.length > 0 ? { navigation: { tabs }, title: "Documentation" } : { title: "Documentation" };
 var migrateNextraProject = async (root) => {
-  const sourceDir = SOURCE_DIRS.find((dir) => existsSync24(join33(root, dir)));
+  const sourceDir = SOURCE_DIRS.find((dir) => existsSync26(join37(root, dir)));
   if (!sourceDir) {
     await writeBlumeConfig(root, { title: "Documentation" });
     return {
@@ -13381,7 +13642,7 @@ var migrateNextraProject = async (root) => {
       ]
     };
   }
-  const base = join33(root, sourceDir);
+  const base = join37(root, sourceDir);
   const pageFiles = await glob10([PAGE_GLOB2], {
     absolute: true,
     cwd: base,
@@ -13395,9 +13656,9 @@ var migrateNextraProject = async (root) => {
   const index = indexFolders(base, pageFiles, metaFiles);
   const metas = await Promise.all(metaFiles.map(async (abs) => ({
     abs,
-    ext: extname7(abs),
-    raw: await readFile19(abs, "utf-8"),
-    rel: relative17(base, abs)
+    ext: extname8(abs),
+    raw: await readFile20(abs, "utf-8"),
+    rel: relative20(base, abs)
   })));
   const plan = planMetas(metas, index);
   const moves = await Promise.all(pageFiles.map((abs) => movePage2(abs, { base, overrides: plan.pageOverrides, root })));
@@ -13422,15 +13683,15 @@ var migrateNextraProject = async (root) => {
 };
 
 // src/migrate/starlight/index.ts
-import { existsSync as existsSync26 } from "node:fs";
-import { readFile as readFile21, writeFile as writeFile14 } from "node:fs/promises";
-import { join as join35 } from "pathe";
+import { existsSync as existsSync28 } from "node:fs";
+import { readFile as readFile22, writeFile as writeFile15 } from "node:fs/promises";
+import { join as join39 } from "pathe";
 import { glob as glob11 } from "tinyglobby";
 
 // src/migrate/starlight/config.ts
-import { existsSync as existsSync25 } from "node:fs";
-import { readFile as readFile20 } from "node:fs/promises";
-import { join as join34 } from "pathe";
+import { existsSync as existsSync27 } from "node:fs";
+import { readFile as readFile21 } from "node:fs/promises";
+import { join as join38 } from "pathe";
 var CONFIG_FILES = [
   "astro.config.mjs",
   "astro.config.mts",
@@ -13461,7 +13722,7 @@ var extractStarlightOptions = (source) => {
   return isLiteralObject(parsed) ? parsed : "unparseable";
 };
 var loadStarlightConfig = async (root) => {
-  const file = CONFIG_FILES.map((name) => join34(root, name)).find((path) => existsSync25(path));
+  const file = CONFIG_FILES.map((name) => join38(root, name)).find((path) => existsSync27(path));
   if (!file) {
     return {
       options: {},
@@ -13470,7 +13731,7 @@ var loadStarlightConfig = async (root) => {
       ]
     };
   }
-  const source = await readFile20(file, "utf-8");
+  const source = await readFile21(file, "utf-8");
   const result = extractStarlightOptions(source);
   if (result === "missing") {
     return {
@@ -13868,7 +14129,7 @@ var starlightI18n = (options) => {
 // src/migrate/starlight/index.ts
 var CONTENT_DIR = "src/content/docs";
 var transformPage = async (file) => {
-  const raw = await readFile21(file, "utf-8");
+  const raw = await readFile22(file, "utf-8");
   let text = stripStarlightImports(raw);
   text = rewriteStarlightAsides(text);
   text = rewriteStarlightComponents(text);
@@ -13878,7 +14139,7 @@ var transformPage = async (file) => {
   const { data, removed } = normalizeStarlightPageMeta(parsed.data);
   const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
   if (content !== raw) {
-    await writeFile14(file, content, "utf-8");
+    await writeFile15(file, content, "utf-8");
   }
   return { aliased, removed, unsupported };
 };
@@ -13890,8 +14151,8 @@ var migrateStarlightProject = async (root) => {
     config.i18n = i18n;
     warnings.push(`Mapped ${i18n.locales.length} locale(s) to i18n (default: ${i18n.defaultLocale}); review the locale labels.`);
   }
-  const base = join35(root, CONTENT_DIR);
-  if (!existsSync26(base)) {
+  const base = join39(root, CONTENT_DIR);
+  if (!existsSync28(base)) {
     await writeBlumeConfig(root, config);
     return {
       moved: 0,
@@ -13979,10 +14240,10 @@ var migrateCommand = defineCommand8({
 });
 
 // src/cli/commands/preview.ts
-import { existsSync as existsSync27 } from "node:fs";
+import { existsSync as existsSync29 } from "node:fs";
 import { preview } from "astro";
 import { defineCommand as defineCommand9 } from "citty";
-import { join as join36 } from "pathe";
+import { join as join40 } from "pathe";
 var previewCommand = defineCommand9({
   args: {
     host: { description: "Network host to bind.", type: "string" },
@@ -13996,7 +14257,7 @@ var previewCommand = defineCommand9({
     const root = process.cwd();
     const { config } = await loadConfig(root);
     const context = resolveProjectContext(root, config);
-    if (!existsSync27(join36(context.outDir, "astro.config.mjs"))) {
+    if (!existsSync29(join40(context.outDir, "astro.config.mjs"))) {
       logger.error("No build found. Run `blume build` first.");
       process.exit(1);
     }
@@ -14005,7 +14266,7 @@ var previewCommand = defineCommand9({
       root: context.outDir,
       server: {
         host: args.host ?? false,
-        port: args.port ? Number(args.port) : undefined
+        port: parsePort(args.port)
       }
     });
   }
@@ -14014,7 +14275,7 @@ var previewCommand = defineCommand9({
 // src/cli/commands/sync.ts
 import { rm as rm6 } from "node:fs/promises";
 import { defineCommand as defineCommand10 } from "citty";
-import { join as join37 } from "pathe";
+import { join as join41 } from "pathe";
 var syncCommand = defineCommand10({
   args: {
     force: {
@@ -14036,7 +14297,7 @@ var syncCommand = defineCommand10({
     if (args.force) {
       const { config } = await loadConfig(root);
       const context = resolveProjectContext(root, config);
-      await rm6(join37(context.outDir, "cache"), { force: true, recursive: true });
+      await rm6(join41(context.outDir, "cache"), { force: true, recursive: true });
       logger.info("Cleared source cache.");
     }
     await prepareProject({
@@ -14051,13 +14312,13 @@ var syncCommand = defineCommand10({
 });
 
 // src/cli/commands/validate.ts
-import { existsSync as existsSync29 } from "node:fs";
+import { existsSync as existsSync31 } from "node:fs";
 import { defineCommand as defineCommand11 } from "citty";
-import { join as join39 } from "pathe";
+import { join as join43 } from "pathe";
 
 // src/core/links.ts
-import { existsSync as existsSync28 } from "node:fs";
-import { join as join38 } from "pathe";
+import { existsSync as existsSync30 } from "node:fs";
+import { basename as basename8, join as join42 } from "pathe";
 var HTTP = /^https?:\/\//iu;
 var PROTOCOL_RELATIVE = /^\/\//u;
 var SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
@@ -14069,9 +14330,21 @@ var STATUS_NOT_FOUND = 404;
 var STATUS_GONE = 410;
 var STATUS_METHOD_NOT_ALLOWED = 405;
 var STATUS_NOT_IMPLEMENTED = 501;
-var resolveRelative = (pageRoute, target) => {
+var assetIsPresent = (resolved, ctx) => {
+  if (ctx.publicDir && existsSync30(join42(ctx.publicDir, resolved))) {
+    return true;
+  }
+  return ctx.assetMounts.some((mount) => (resolved === mount.url || resolved.startsWith(`${mount.url}/`)) && existsSync30(join42(mount.dir, resolved.slice(mount.url.length))));
+};
+var isIndexPage = (page2) => {
+  const ref = page2.source?.ref ?? page2.sourcePath ?? "";
+  return /^index\.(?:md|mdx)$/iu.test(basename8(ref));
+};
+var resolveRelative = (pageRoute, target, isIndex) => {
   const segments = pageRoute.split("/").filter(Boolean);
-  segments.pop();
+  if (!isIndex) {
+    segments.pop();
+  }
   for (const part of target.split("/")) {
     if (part === "" || part === ".") {
       continue;
@@ -14113,13 +14386,20 @@ var checkAnchor = (route, fragment, site, ctx) => {
   };
 };
 var checkPathLink = (resolved, fragment, target, site, ctx) => {
+  const route = toRoute(resolved);
+  if (ctx.routes.has(route)) {
+    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
+  }
+  if (ctx.redirects.has(route)) {
+    return null;
+  }
   if (FILE_EXT.test(resolved) && !DOC_EXT.test(resolved)) {
-    if (ctx.publicDir === null) {
-      return "asset-unchecked";
-    }
-    if (existsSync28(join38(ctx.publicDir, resolved))) {
+    if (assetIsPresent(resolved, ctx)) {
       return null;
     }
+    if (ctx.publicDir === null && ctx.assetMounts.length === 0) {
+      return "asset-unchecked";
+    }
     return {
       ...site,
       code: "BLUME_BROKEN_ASSET",
@@ -14128,13 +14408,6 @@ var checkPathLink = (resolved, fragment, target, site, ctx) => {
       suggestion: `Add the file at public${resolved} or fix the link.`
     };
   }
-  const route = toRoute(resolved);
-  if (ctx.routes.has(route)) {
-    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
-  }
-  if (ctx.redirects.has(route)) {
-    return null;
-  }
   return {
     ...site,
     code: "BLUME_BROKEN_LINK",
@@ -14243,12 +14516,13 @@ var classifyLink = (page2, link, ctx, onExternal) => {
   if (rawPath === "") {
     return fragment ? checkAnchor(page2.route, fragment, site, ctx) : null;
   }
-  const resolved = rawPath.startsWith("/") ? rawPath : resolveRelative(page2.route, rawPath);
+  const resolved = rawPath.startsWith("/") ? rawPath : resolveRelative(page2.route, rawPath, isIndexPage(page2));
   return checkPathLink(resolved, fragment, target, site, ctx);
 };
 var validateLinks = async (graph, options) => {
   const ctx = {
     anchors: buildAnchorIndex(graph.pages),
+    assetMounts: options.assetMounts ?? [],
     publicDir: options.publicDir,
     redirects: new Set((options.redirects ?? []).map((redirect) => toRoute(redirect.from))),
     routes: new Set(graph.routes.keys())
@@ -14305,10 +14579,11 @@ var validateCommand = defineCommand11({
     try {
       const project = await scanProject(root, { mode: "build" });
       diagnostics.push(...project.diagnostics);
-      const publicDir = join39(root, "public");
+      const publicDir = join43(root, "public");
       diagnostics.push(...await validateLinks(project.graph, {
+        assetMounts: resolveAssetMounts(root, project.config.content.assets),
         checkExternal: Boolean(args.external),
-        publicDir: existsSync29(publicDir) ? publicDir : null,
+        publicDir: existsSync31(publicDir) ? publicDir : null,
         redirects: project.config.redirects
       }));
     } catch (error) {
@@ -14322,6 +14597,7 @@ var validateCommand = defineCommand11({
     if (args.json) {
       const hadErrors2 = reportDiagnosticsJson(diagnostics, root);
       if (hadErrors2 || Boolean(args.strict) && diagnostics.length > 0) {
+        await flushStdout();
         process.exit(1);
       }
       return;
@@ -14368,5 +14644,5 @@ process.on("unhandledRejection", (error) => {
 });
 runMain(main);
 
-//# debugId=8EA79E97DE44177D64756E2164756E21
+//# debugId=114B8B7438537BD664756E2164756E21
 //# sourceMappingURL=index.js.map