blume 0.1.0 → 0.1.2

package/dist/cli/index.js

@@ -279,14 +279,30 @@ Next steps:
 });
 
 // src/cli/commands/build.ts
-import { existsSync as existsSync9 } from "node:fs";
+import { existsSync as existsSync11 } from "node:fs";
 import { writeFile as writeFile6 } from "node:fs/promises";
 import { build } from "astro";
 import { defineCommand as defineCommand2 } from "citty";
-import { join as join21 } from "pathe";
+import { join as join23 } from "pathe";
 
-// src/ai/llms.ts
-import matter from "gray-matter";
+// src/core/frontmatter.ts
+import baseMatter from "gray-matter";
+import { dump, load } from "js-yaml";
+var yamlEngine = {
+  parse: (input) => load(input) ?? {},
+  stringify: (data) => dump(data)
+};
+var withYamlEngine = (options) => ({
+  ...options,
+  engines: {
+    yaml: yamlEngine,
+    ...options?.engines
+  }
+});
+var matter = Object.assign((input, options) => baseMatter(input, withYamlEngine(options)), baseMatter, {
+  stringify: (file, data, options) => baseMatter.stringify(file, data, withYamlEngine(options))
+});
+var frontmatter_default = matter;
 
 // src/core/sources/read.ts
 import { readFile as readFile2 } from "node:fs/promises";
@@ -335,7 +351,7 @@ var buildFull = async (project) => {
   const pages = orderedPages(project);
   const sections = await Promise.all(pages.map(async (page) => {
     const raw = await readEntryText(project, page);
-    const body = matter(raw).content.trim();
+    const body = frontmatter_default(raw).content.trim();
     const url = pageUrl(page.route, config.deployment.site);
     return [`# ${page.title}`, `Source: ${url}`, "", body].join(`
 `);
@@ -473,9 +489,6 @@ var buildSearchIndex = async (outDir) => {
   return result.page_count;
 };
 
-// src/search/documents.ts
-import matter2 from "gray-matter";
-
 // src/core/ui-packs/ar.ts
 var ar = {
   actions: {
@@ -2365,7 +2378,7 @@ var buildSearchDocuments = async (project, options) => {
   return await Promise.all(indexable.map(async (route) => {
     const page = pageById.get(route.id);
     const raw = page ? await readEntryText(project, page) : "";
-    const body = raw ? toPlainText(matter2(raw).content) : "";
+    const body = raw ? toPlainText(frontmatter_default(raw).content) : "";
     const tags = page?.meta?.search?.tags;
     const crumb = crumbs.get(route.path);
     return {
@@ -2501,19 +2514,20 @@ var syncSearchProvider = async (project, reporter) => {
 };
 
 // src/astro/generate.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync5, realpathSync } from "node:fs";
 import {
+  lstat,
   mkdir as mkdir2,
-  readFile as readFile6,
+  readFile as readFile7,
   rename,
   rm,
   symlink,
   writeFile as writeFile2
 } from "node:fs/promises";
-import { createRequire as createRequire3 } from "node:module";
-import { pathToFileURL } from "node:url";
-import { dirname as dirname5, join as join9, normalize, relative as relative4 } from "pathe";
-import { glob as glob3 } from "tinyglobby";
+import { createRequire as createRequire4 } from "node:module";
+import { pathToFileURL as pathToFileURL2 } from "node:url";
+import { basename as basename2, dirname as dirname6, join as join11, normalize, relative as relative5 } from "pathe";
+import { glob as glob4 } from "tinyglobby";
 
 // src/ai/ask.ts
 var ASK_PRESETS = {
@@ -2754,6 +2768,143 @@ var resolveUIStrings = (locale, options) => {
   return dict;
 };
 
+// src/core/tsconfig-aliases.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2, statSync } from "node:fs";
+import { createRequire as createRequire2 } from "node:module";
+import { pathToFileURL } from "node:url";
+import { dirname as dirname4, isAbsolute, join as join6, resolve as resolve2 } from "pathe";
+var stripJsonComments = (text) => {
+  let out = "";
+  let inString = false;
+  for (let index = 0;index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      out += char;
+      if (char === "\\") {
+        out += text[index + 1] ?? "";
+        index += 1;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      out += char;
+      continue;
+    }
+    if (char === "/" && text[index + 1] === "/") {
+      const newline = text.indexOf(`
+`, index + 2);
+      index = newline === -1 ? text.length : newline - 1;
+      continue;
+    }
+    if (char === "/" && text[index + 1] === "*") {
+      const end = text.indexOf("*/", index + 2);
+      index = end === -1 ? text.length : end + 1;
+      continue;
+    }
+    out += char;
+  }
+  return out;
+};
+var TRAILING_COMMA = /,(?<rest>\s*[}\]])/gu;
+var parseJsonc = (text) => {
+  try {
+    const cleaned = stripJsonComments(text).replaceAll(TRAILING_COMMA, "$<rest>");
+    const value = JSON.parse(cleaned);
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+};
+var isFile = (path) => {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+};
+var resolveExtends = (spec, fromDir) => {
+  if (spec.startsWith(".") || isAbsolute(spec)) {
+    const candidates = spec.endsWith(".json") ? [resolve2(fromDir, spec)] : [
+      resolve2(fromDir, `${spec}.json`),
+      resolve2(fromDir, spec, "tsconfig.json"),
+      resolve2(fromDir, spec)
+    ];
+    return candidates.find(isFile) ?? null;
+  }
+  try {
+    const require_ = createRequire2(pathToFileURL(join6(fromDir, "_.js")).href);
+    for (const sub of [`${spec}/tsconfig.json`, spec]) {
+      try {
+        return require_.resolve(sub);
+      } catch {}
+    }
+  } catch {}
+  return null;
+};
+var loadPaths = (file, seen) => {
+  if (seen.has(file) || !existsSync3(file)) {
+    return null;
+  }
+  seen.add(file);
+  const json = parseJsonc(readFileSync2(file, "utf-8"));
+  if (!json) {
+    return null;
+  }
+  const options = json.compilerOptions ?? {};
+  if (options.paths && typeof options.paths === "object") {
+    const baseUrl = typeof options.baseUrl === "string" ? options.baseUrl : ".";
+    return {
+      baseDir: resolve2(dirname4(file), baseUrl),
+      paths: options.paths
+    };
+  }
+  const bases = Array.isArray(json.extends) ? json.extends : [json.extends].filter(Boolean);
+  for (const base of bases) {
+    if (typeof base !== "string") {
+      continue;
+    }
+    const resolved = resolveExtends(base, dirname4(file));
+    const found = resolved ? loadPaths(resolved, seen) : null;
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+};
+var toAlias = (key, value, baseDir) => {
+  const first = Array.isArray(value) ? value[0] : value;
+  if (typeof first !== "string") {
+    return null;
+  }
+  const find = key.endsWith("/*") ? key.slice(0, -2) : key;
+  const target = first.endsWith("/*") ? first.slice(0, -2) : first;
+  if (find === "" || find === "*") {
+    return null;
+  }
+  return { find, replacement: resolve2(baseDir, target) };
+};
+var resolveTsconfigAliases = (root) => {
+  const entry = ["tsconfig.json", "jsconfig.json"].map((name) => join6(root, name)).find((file) => existsSync3(file));
+  if (!entry) {
+    return {};
+  }
+  const loaded = loadPaths(entry, new Set);
+  if (!loaded) {
+    return {};
+  }
+  const aliases = {};
+  for (const [key, value] of Object.entries(loaded.paths)) {
+    const alias = toAlias(key, value, loaded.baseDir);
+    if (alias) {
+      aliases[alias.find] = alias.replacement;
+    }
+  }
+  return aliases;
+};
+
 // src/deploy/rss.ts
 var capitalize = (value) => value.charAt(0).toUpperCase() + value.slice(1);
 var pageDate = (page) => {
@@ -2835,11 +2986,11 @@ ${items}
 
 // src/openapi/scalar.ts
 import { readFile as readFile4 } from "node:fs/promises";
-import { isAbsolute, join as join7 } from "pathe";
+import { isAbsolute as isAbsolute2, join as join8 } from "pathe";
 
 // src/astro/templates.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "node:fs";
-import { dirname as dirname4, join as join6 } from "pathe";
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "node:fs";
+import { dirname as dirname5, join as join7 } from "pathe";
 
 // src/theme/fonts.ts
 var FALLBACKS = {
@@ -2997,24 +3148,24 @@ var WORKSPACE_MARKERS = [
   "yarn.lock"
 ];
 var hasWorkspacesField = (pkgPath) => {
-  if (!existsSync3(pkgPath)) {
+  if (!existsSync4(pkgPath)) {
     return false;
   }
   try {
-    const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
     return pkg.workspaces !== undefined;
   } catch {
     return false;
   }
 };
-var hasWorkspaceMarker = (dir) => hasWorkspacesField(join6(dir, "package.json")) || WORKSPACE_MARKERS.some((marker) => existsSync3(join6(dir, marker)));
+var hasWorkspaceMarker = (dir) => hasWorkspacesField(join7(dir, "package.json")) || WORKSPACE_MARKERS.some((marker) => existsSync4(join7(dir, marker)));
 var findWorkspaceRoot = (start) => {
   let dir = start;
   for (;; ) {
     if (hasWorkspaceMarker(dir)) {
       return dir;
     }
-    const parent = dirname4(dir);
+    const parent = dirname5(dir);
     if (parent === dir) {
       return start;
     }
@@ -3061,10 +3212,31 @@ var runtimeDependencies = (options) => {
   }
   return deps;
 };
+var RENDER_EXTERNAL_DEPS = [
+  "@astrojs/markdown-satteri",
+  "@pierre/diffs",
+  "@shikijs/transformers",
+  "@takumi-rs/core",
+  "@takumi-rs/helpers",
+  "github-slugger",
+  "katex",
+  "shiki",
+  "simple-icons",
+  "zod"
+];
+var renderUserAliases = (aliases) => Object.entries(aliases ?? {}).toSorted(([a], [b]) => b.length - a.length).map(([find, replacement]) => `
+        ${JSON.stringify(find)}: ${JSON.stringify(replacement)},`).join("");
 var astroConfigTemplate = (options) => {
   const { context, config, needsReact, pages, dataPath, themePath } = options;
-  const { contentRoutes, needsSvelte, needsVue, searchClientPath } = options;
+  const {
+    contentRoutes,
+    examplesPath,
+    needsSvelte,
+    needsVue,
+    searchClientPath
+  } = options;
   const { deployment } = config;
+  const userAliasLines = renderUserAliases(options.aliases);
   const server = deployment.output === "server";
   const fsAllow = [...new Set([findWorkspaceRoot(context.root), context.root])];
   const adapterImport = server && deployment.adapter ? `import adapter from "${ADAPTER_IMPORTS[deployment.adapter]}";
@@ -3099,7 +3271,7 @@ var astroConfigTemplate = (options) => {
 ` : "";
   const svelteImport = needsSvelte ? `import svelte from "@astrojs/svelte";
 ` : "";
-  const blumeImport = `import { blumeIntegration } from "blume/astro";
+  const blumeImport = `import { blumeIntegration, prerenderDepsPlugin } from "blume/astro";
 `;
   const twoslashImport = `import { transformerTwoslash } from "@shikijs/twoslash";
 `;
@@ -3150,25 +3322,21 @@ export default defineConfig({
   },
   devToolbar: { enabled: false },
   vite: {
-    plugins: [tailwindcss()],
-    // @takumi-rs/core (OG image rendering) is a native NAPI addon that loads a
-    // platform-specific .node binding via createRequire(import.meta.url). Astro's
-    // build bundles it into the per-environment output by default, which
-    // relocates import.meta.url and breaks the binding lookup ("Cannot find
-    // native binding") on other platforms (e.g. the Linux CI runner). Astro 7
-    // configures externalization per Vite environment, so it must be forced
-    // external on the prerender (static) and ssr (server) environments -- a
-    // top-level ssr.external only reaches the latter -- so the binding resolves
-    // from node_modules at runtime instead.
+    plugins: [tailwindcss(), prerenderDepsPlugin()],
+    // Blume's render-time deps are forced external on both build environments so
+    // native bindings resolve at runtime and isolated linkers don't bundle
+    // symlinked store copies (which would surface their children as unresolvable
+    // imports). See RENDER_EXTERNAL_DEPS / prerenderDepsPlugin.
     environments: {
-      prerender: { resolve: { external: ["@takumi-rs/core"] } },
-      ssr: { resolve: { external: ["@takumi-rs/core"] } },
+      prerender: { resolve: { external: ${JSON.stringify(RENDER_EXTERNAL_DEPS)} } },
+      ssr: { resolve: { external: ${JSON.stringify(RENDER_EXTERNAL_DEPS)} } },
     },
     resolve: {
       alias: {
         "blume:data": ${JSON.stringify(dataPath)},
+        "blume:examples": ${JSON.stringify(examplesPath)},
         "blume:search-client": ${JSON.stringify(searchClientPath)},
-        "blume:theme": ${JSON.stringify(themePath)},
+        "blume:theme": ${JSON.stringify(themePath)},${userAliasLines}
       },
     },
     server: {
@@ -3180,7 +3348,7 @@ export default defineConfig({
 });
 `;
 };
-var stagedContentDir = (outDir) => join6(outDir, "content");
+var stagedContentDir = (outDir) => join7(outDir, "content");
 var contentConfigTemplate = (options) => {
   const { context, config } = options;
   const stagedBase = options.stagedBase ?? stagedContentDir(context.outDir);
@@ -3426,24 +3594,44 @@ export function GET({ props }) {
   });
 }
 `;
-var ogEndpointTemplate = () => `// Generated by Blume. Do not edit.
+var ogEndpointTemplate = (customRoutes = []) => `// Generated by Blume. Do not edit.
 import { renderOgImage } from "blume/og";
 import data from "../../generated/data.json";
 
 export const prerender = true;
 
+// Custom (non-content) pages opted into a generated card, baked in at build.
+const customRoutes = ${JSON.stringify(customRoutes)};
+
 export function getStaticPaths() {
-  return data.routes.map((route) => ({
-    params: { slug: route.path === "/" ? "index" : route.path.slice(1) },
-    props: { title: route.title },
-  }));
+  const seen = new Set();
+  const paths = [];
+  const add = (slug, title, eyebrow) => {
+    if (seen.has(slug)) {
+      return;
+    }
+    seen.add(slug);
+    paths.push({ params: { slug }, props: { eyebrow, title } });
+  };
+  // A custom page wins over a content route sharing its path, so add it first.
+  for (const route of customRoutes) {
+    add(route.slug, route.title, route.eyebrow);
+  }
+  for (const route of data.routes) {
+    add(
+      route.path === "/" ? "index" : route.path.slice(1),
+      route.title,
+      data.config.title
+    );
+  }
+  return paths;
 }
 
 export async function GET({ props }) {
   const png = await renderOgImage({
-    title: props.title,
-    eyebrow: data.config.title,
     accent: data.config.theme.accent,
+    eyebrow: props.eyebrow,
+    title: props.title,
   });
   return new Response(png, {
     headers: {
@@ -3470,6 +3658,7 @@ const configuration = ${JSON.stringify(options.configuration, null, 2)};
   fontCssVars={data.fontCssVars}
   logo={data.config.logo}
   favicon={data.config.favicon}
+  appleIcon={data.config.appleIcon}
   navigation={data.navigation}
   pageTitle={${JSON.stringify(options.title)}}
   route={${JSON.stringify(options.route)}}
@@ -3501,12 +3690,15 @@ import Badge from "blume/components/content/Badge.astro";
 import Callout from "blume/components/content/Callout.astro";
 import Card from "blume/components/content/Card.astro";
 import CardGroup from "blume/components/content/CardGroup.astro";
+import CodeBlock from "blume/components/content/CodeBlock.astro";
 import CodeGroup from "blume/components/content/CodeGroup.astro";
 import ColorRoot from "blume/components/content/Color.astro";
 import ColorItem from "blume/components/content/ColorItem.astro";
 import ColorRow from "blume/components/content/ColorRow.astro";
 import Column from "blume/components/content/Column.astro";
 import Columns from "blume/components/content/Columns.astro";
+import Component from "blume/components/content/Component.astro";
+import Diff from "blume/components/content/Diff.astro";
 import Expandable from "blume/components/content/Expandable.astro";
 import FileTree from "blume/components/content/FileTree.astro";
 import Frame from "blume/components/content/Frame.astro";
@@ -3546,10 +3738,13 @@ const components = {
   Callout,
   Card,
   CardGroup,
+  CodeBlock,
   CodeGroup,
   Color,
   Column,
   Columns,
+  Component,
+  Diff,
   Expandable,
   FileTree,
   Frame,
@@ -3670,6 +3865,7 @@ const localeSwitch = i18n
   logo={data.config.logo}
   mcp={data.config.mcp}
   favicon={data.config.favicon}
+  appleIcon={data.config.appleIcon}
   banner={data.config.banner}
   analytics={data.config.analytics}
   imageZoom={data.config.imageZoom}
@@ -3796,6 +3992,7 @@ const canonical = base ? base + "/changelog" : null;
   logo={data.config.logo}
   mcp={data.config.mcp}
   favicon={data.config.favicon}
+  appleIcon={data.config.appleIcon}
   banner={data.config.banner}
   analytics={data.config.analytics}
   imageZoom={data.config.imageZoom}
@@ -3875,8 +4072,43 @@ ${entries}
 };
 `;
 };
+var exampleDirective = (spec) => {
+  if (spec.framework === "astro" || !spec.client) {
+    return "";
+  }
+  return spec.client === "only" ? `client:only="${spec.framework}" ` : `client:${spec.client} `;
+};
+var exampleSlug = (path) => path.replaceAll("/", "__").replaceAll(/[^a-zA-Z0-9_]+/gu, "-");
+var exampleWrapperTemplate = (spec) => `---
+// Generated by Blume. Do not edit.
+import Example from ${JSON.stringify(spec.file)};
+---
+<Example ${exampleDirective(spec)}{...Astro.props}><slot /></Example>
+`;
+var exampleMapTemplate = (specs) => {
+  if (specs.length === 0) {
+    return `// Generated by Blume. Do not edit.
+export const examples = {};
+`;
+  }
+  const imports = specs.map((spec, index) => `import E${index} from "./examples/${exampleSlug(spec.path)}.astro";`).join(`
+`);
+  const entries = specs.map((spec, index) => `  ${JSON.stringify(spec.path)}: { Component: E${index}, code: ${JSON.stringify(spec.source)}, lang: ${JSON.stringify(spec.lang)} },`).join(`
+`);
+  return `// Generated by Blume. Do not edit.
+${imports}
+export const examples = {
+${entries}
+};
+`;
+};
 var envTemplate = () => `/// <reference path="../.astro/types.d.ts" />
 /// <reference types="astro/client" />
+
+declare module "blume:data" {
+  const data: import("blume").BlumeData;
+  export default data;
+}
 `;
 var runtimePackageTemplate = (dependencies = []) => `${JSON.stringify({
   dependencies: Object.fromEntries([...dependencies].toSorted().map((name) => [name, "*"])),
@@ -4057,7 +4289,7 @@ var specConfiguration = async (spec, root) => {
   if (URL_SPEC.test(spec)) {
     return { config: { url: spec } };
   }
-  const absolute = isAbsolute(spec) ? spec : join7(root, spec);
+  const absolute = isAbsolute2(spec) ? spec : join8(root, spec);
   try {
     return { config: { content: await readFile4(absolute, "utf-8") } };
   } catch {
@@ -4419,6 +4651,19 @@ ${options.sources.map((source) => `@source "${source}";`).join(`
   text-decoration: var(--shiki-dark-text-decoration, inherit);
 }
 
+/* The Diff component (@pierre/diffs) renders into a declarative shadow root and
+   themes itself with light-dark(). Drive that from Blume's data-theme instead
+   of the OS, scoped to the diff host: the custom property pierces the shadow
+   boundary, where the appended host color-scheme rule consumes it. */
+blume-diff {
+  --blume-diff-color-scheme: light;
+  display: block;
+}
+
+:root[data-theme="dark"] blume-diff {
+  --blume-diff-color-scheme: dark;
+}
+
 .prose :where(pre[data-language]) {
   padding-top: 3.75rem;
 }
@@ -4492,6 +4737,22 @@ blume-tabs pre,
   background: var(--blume-code-background);
 }
 
+/* The Component source pane fills its tab's fixed height (set inline to match the
+   preview tab) and scrolls the inner code element, leaving the pre static so the
+   copy button — absolute, pinned to the pre — doesn't drift while it scrolls. */
+pre.blume-source {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  overflow: hidden;
+}
+
+pre.blume-source > code {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
 /* Code blocks inside tabs sit flush; the tab container owns the frame. These
    rules are unlayered like the base \`pre\` styles, so they win over Tailwind's
    layered utilities (which a class on the panel cannot). The second selector
@@ -4701,9 +4962,9 @@ ${options.userTheme}
 `;
 
 // src/theme/twoslash.ts
-import { readFileSync as readFileSync3 } from "node:fs";
-import { createRequire as createRequire2 } from "node:module";
-var require2 = createRequire2(import.meta.url);
+import { readFileSync as readFileSync4 } from "node:fs";
+import { createRequire as createRequire3 } from "node:module";
+var require2 = createRequire3(import.meta.url);
 var OVERRIDES = `
 /* Twoslash: theme the rich renderer with Blume tokens. */
 :root {
@@ -4763,13 +5024,18 @@ var OVERRIDES = `
 `;
 var twoslashCss = () => {
   const file = require2.resolve("@shikijs/twoslash/style-rich.css");
-  return `${readFileSync3(file, "utf-8")}
+  return `${readFileSync4(file, "utf-8")}
 ${OVERRIDES}`;
 };
 
+// src/astro/examples.ts
+import { readFile as readFile6 } from "node:fs/promises";
+import { join as join10, relative as relative3 } from "pathe";
+import { glob as glob2 } from "tinyglobby";
+
 // src/astro/islands.ts
 import { readFile as readFile5 } from "node:fs/promises";
-import { basename, join as join8 } from "pathe";
+import { basename, join as join9 } from "pathe";
 import { glob } from "tinyglobby";
 var DEFAULT_CLIENT = "visible";
 var VALID_MODES = new Set([
@@ -4798,7 +5064,7 @@ var readClientMode = (source, file, warnings) => {
   return mode;
 };
 var discoverIslands = async (root) => {
-  const dir = join8(root, "islands");
+  const dir = join9(root, "islands");
   const matches = await glob(["**/*.{jsx,svelte,tsx,vue}"], {
     absolute: true,
     cwd: dir,
@@ -4837,50 +5103,157 @@ var discoverIslands = async (root) => {
   return { islands, warnings };
 };
 
+// src/astro/examples.ts
+var FRAMEWORK_BY_EXT2 = {
+  astro: "astro",
+  jsx: "react",
+  svelte: "svelte",
+  tsx: "react",
+  vue: "vue"
+};
+var EXAMPLE_FILE = /\.(?<ext>astro|jsx|svelte|tsx|vue)$/u;
+var discoverExamples = async (root, subdir = "examples") => {
+  const dir = join10(root, subdir);
+  const matches = await glob2(["**/*.{astro,jsx,svelte,tsx,vue}"], {
+    absolute: true,
+    cwd: dir,
+    onlyFiles: true
+  });
+  const files = matches.toSorted();
+  const sources = await Promise.all(files.map((file) => readFile6(file, "utf-8")));
+  const examples = [];
+  const warnings = [];
+  const seen = new Map;
+  for (const [index, file] of files.entries()) {
+    const ext = file.match(EXAMPLE_FILE)?.groups?.ext;
+    const framework = ext ? FRAMEWORK_BY_EXT2[ext] : undefined;
+    if (!(ext && framework)) {
+      continue;
+    }
+    const path = relative3(dir, file).slice(0, -(ext.length + 1));
+    const existing = seen.get(path);
+    if (existing) {
+      warnings.push(`Two examples both resolve to "${path}" ("${existing}" and "${file}"); ignoring the second. Give them distinct paths.`);
+      continue;
+    }
+    seen.set(path, file);
+    const source = sources[index] ?? "";
+    examples.push({
+      client: framework === "astro" ? undefined : readClientMode(source, file, warnings),
+      file,
+      framework,
+      lang: ext,
+      path,
+      source
+    });
+  }
+  return { examples, warnings };
+};
+
 // src/astro/pages.ts
-import { extname, relative as relative3 } from "pathe";
-import { glob as glob2 } from "tinyglobby";
+import { extname, relative as relative4 } from "pathe";
+import { glob as glob3 } from "tinyglobby";
 var discoverPages = async (pagesRoot) => {
-  const files = await glob2(["**/*.astro"], {
+  const files = await glob3(["**/*.astro"], {
     absolute: true,
     cwd: pagesRoot,
     onlyFiles: true
   });
   files.sort();
   return files.map((file) => {
-    const rel = relative3(pagesRoot, file);
+    const rel = relative4(pagesRoot, file);
     const withoutExt = rel.slice(0, rel.length - extname(rel).length);
     const parts = withoutExt.split("/").filter((part) => part !== "index");
     const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
     return { entrypoint: file, pattern };
   });
 };
+var PRIVATE_SEGMENT = /^[._]/u;
+var humanizeSegment = (segment) => segment.split(/[-_]/u).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+var customOgRoutes = (pages, siteTitle, siteDescription) => {
+  const seen = new Set;
+  const routes = [];
+  for (const { pattern } of pages) {
+    const segments = pattern.split("/").filter(Boolean);
+    if (segments.some((part) => PRIVATE_SEGMENT.test(part) || part.includes("["))) {
+      continue;
+    }
+    const slug = segments.length === 0 ? "index" : segments.join("/");
+    if (seen.has(slug)) {
+      continue;
+    }
+    seen.add(slug);
+    const last = segments.at(-1);
+    routes.push(last ? { eyebrow: siteTitle, slug, title: humanizeSegment(last) } : { eyebrow: siteDescription, slug, title: siteTitle });
+  }
+  return routes;
+};
 
 // src/astro/generate.ts
-var BLUME_SRC = join9(packageRoot(), "src");
-var BLUME_NODE_MODULES = join9(packageRoot(), "node_modules");
+var BLUME_SRC = join11(packageRoot(), "src");
 var canResolveFrom = (fromDir, spec) => {
   try {
-    createRequire3(pathToFileURL(join9(fromDir, "_.js")).href).resolve(spec);
+    createRequire4(pathToFileURL2(join11(fromDir, "_.js")).href).resolve(spec);
     return true;
   } catch {
     return false;
   }
 };
-var canResolveAstro = (fromDir) => canResolveFrom(fromDir, "astro/package.json");
-var ensureDepsLink = async (outDir) => {
-  if (canResolveAstro(outDir)) {
-    return;
+var resolvedAstroPath = (fromDir) => {
+  try {
+    const pkg = createRequire4(pathToFileURL2(join11(fromDir, "_.js")).href).resolve("astro/package.json");
+    return realpathSync(pkg);
+  } catch {
+    return null;
   }
-  if (!existsSync4(join9(BLUME_NODE_MODULES, "astro"))) {
-    return;
+};
+var blumeDepsDir = (pkgDir = packageRoot()) => {
+  const candidates = [join11(pkgDir, "node_modules"), dirname6(pkgDir)];
+  return candidates.find((dir) => existsSync5(join11(dir, "astro"))) ?? null;
+};
+var linkDepsJunction = async (link, depsDir) => {
+  const existing = await lstat(link).catch(() => null);
+  if (existing) {
+    if (!existing.isSymbolicLink()) {
+      return;
+    }
+    await rm(link, { force: true });
   }
-  const link = join9(outDir, "node_modules");
-  if (existsSync4(link)) {
-    return;
+  await mkdir2(dirname6(link), { recursive: true });
+  await symlink(depsDir, link, "junction");
+};
+var readPkgVersion = (pkgJsonPath) => {
+  if (!pkgJsonPath) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync5(pkgJsonPath, "utf-8")).version ?? null;
+  } catch {
+    return null;
+  }
+};
+var astroConflictWarning = (blumeAstroPkg, shadowAstroPkg) => {
+  const blume = readPkgVersion(blumeAstroPkg);
+  const shadow = readPkgVersion(shadowAstroPkg);
+  const versions = blume && shadow ? `astro@${shadow} shadowing Blume's astro@${blume}` : "a second copy of Astro shadowing Blume's";
+  const pin = blume ?? "<Blume's astro version>";
+  return `Astro version conflict: another dependency hoisted ${versions} to the project root, so @astrojs/mdx binds to the wrong copy and the build fails on a missing export (e.g. "chunkToString"). A single symlink can't reconcile a split install — pin Blume's Astro by adding a package.json "overrides" (npm/bun/pnpm) or "resolutions" (yarn) entry { "astro": "${pin}" }, then reinstall. Run \`npm ls astro\` to find the dependency pulling the older copy.`;
+};
+var ensureDepsLink = async (outDir, pkgDir = packageRoot()) => {
+  const depsDir = blumeDepsDir(pkgDir);
+  if (!depsDir) {
+    return null;
+  }
+  const blumeAstro = resolvedAstroPath(depsDir);
+  const outDirAstro = resolvedAstroPath(outDir);
+  if (blumeAstro && outDirAstro === blumeAstro) {
+    return null;
+  }
+  if (existsSync5(join11(depsDir, "@astrojs", "mdx"))) {
+    await linkDepsJunction(join11(outDir, "node_modules"), depsDir);
+    return null;
   }
-  await mkdir2(outDir, { recursive: true });
-  await symlink(BLUME_NODE_MODULES, link, "junction");
+  return astroConflictWarning(blumeAstro, outDirAstro);
 };
 var ISLAND_FRAMEWORK_DEPS = {
   svelte: "@astrojs/svelte",
@@ -4901,13 +5274,13 @@ var readOptional = async (path) => {
     return "";
   }
   try {
-    return await readFile6(path, "utf-8");
+    return await readFile7(path, "utf-8");
   } catch {
     return "";
   }
 };
 var detectNeedsReact = async (root) => {
-  const matches = await glob3(["**/*.{tsx,jsx}"], {
+  const matches = await glob4(["**/*.{tsx,jsx}"], {
     cwd: root,
     ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
     onlyFiles: true
@@ -4917,14 +5290,14 @@ var detectNeedsReact = async (root) => {
 var writeIfChanged = async (path, content) => {
   let existing = null;
   try {
-    existing = await readFile6(path, "utf-8");
+    existing = await readFile7(path, "utf-8");
   } catch {
     existing = null;
   }
   if (existing === content) {
     return false;
   }
-  await mkdir2(dirname5(path), { recursive: true });
+  await mkdir2(dirname6(path), { recursive: true });
   const tmp = `${path}.${process.pid}.tmp`;
   await writeFile2(tmp, content, "utf-8");
   try {
@@ -4936,7 +5309,7 @@ var writeIfChanged = async (path, content) => {
   return true;
 };
 var pruneOrphans = async (srcDir, written) => {
-  const existing = await glob3("**/*", {
+  const existing = await glob4("**/*", {
     absolute: true,
     cwd: srcDir,
     onlyFiles: true
@@ -4956,11 +5329,11 @@ var writeStagedContent = async (out, staged) => {
   const contentDir = stagedContentDir(out);
   const written = new Set;
   await Promise.all([...staged].map(async ([entryId, text]) => {
-    const path = join9(contentDir, entryId);
+    const path = join11(contentDir, entryId);
     written.add(normalize(path));
     await writeIfChanged(path, text);
   }));
-  if (existsSync4(contentDir)) {
+  if (existsSync5(contentDir)) {
     await pruneOrphans(contentDir, written);
   }
 };
@@ -4977,11 +5350,11 @@ var resolveLogo = (project) => {
   if (light && light === dark && light.toLowerCase().endsWith(".svg")) {
     const rel = light.replace(/^\//u, "");
     const file = [
-      join9(project.context.root, "public", rel),
-      join9(project.context.root, rel)
-    ].find((path) => existsSync4(path));
+      join11(project.context.root, "public", rel),
+      join11(project.context.root, rel)
+    ].find((path) => existsSync5(path));
     if (file) {
-      return { alt, href, svg: readFileSync4(file, "utf-8") };
+      return { alt, href, svg: readFileSync5(file, "utf-8") };
     }
   }
   return { alt, dark, href, light };
@@ -4996,6 +5369,8 @@ var FAVICON_CANDIDATES = [
 ];
 var FAVICON_TYPES = {
   ico: "image/x-icon",
+  jpeg: "image/jpeg",
+  jpg: "image/jpeg",
   png: "image/png",
   svg: "image/svg+xml"
 };
@@ -5003,27 +5378,35 @@ var faviconType = (name) => {
   const ext = name.split(".").pop()?.toLowerCase();
   return ext ? FAVICON_TYPES[ext] : undefined;
 };
-var inlineDataUri = (file, type) => `data:${type};base64,${readFileSync4(file).toString("base64")}`;
+var inlineDataUri = (file, type) => `data:${type};base64,${readFileSync5(file).toString("base64")}`;
 var defaultFavicon = () => ({
-  href: inlineDataUri(join9(BLUME_SRC, "assets", "icon.png"), "image/png"),
+  href: inlineDataUri(join11(BLUME_SRC, "assets", "icon.png"), "image/png"),
   type: "image/png"
 });
-var resolveFavicon = (project) => {
+var APPLE_ICON_CANDIDATES = [
+  "apple-icon.png",
+  "apple-icon.jpg",
+  "apple-icon.jpeg",
+  "apple-touch-icon.png"
+];
+var resolveIconFile = (project, candidates) => {
   const { root } = project.context;
-  for (const name of FAVICON_CANDIDATES) {
-    if (existsSync4(join9(root, "public", name))) {
+  for (const name of candidates) {
+    if (existsSync5(join11(root, "public", name))) {
       return { href: `/${name}`, type: faviconType(name) };
     }
   }
-  for (const name of FAVICON_CANDIDATES) {
-    const file = join9(root, name);
-    if (existsSync4(file)) {
+  for (const name of candidates) {
+    const file = join11(root, name);
+    if (existsSync5(file)) {
       const type = faviconType(name);
       return { href: inlineDataUri(file, type ?? "image/x-icon"), type };
     }
   }
-  return defaultFavicon();
+  return null;
 };
+var resolveFavicon = (project) => resolveIconFile(project, FAVICON_CANDIDATES) ?? defaultFavicon();
+var resolveAppleIcon = (project) => resolveIconFile(project, APPLE_ICON_CANDIDATES);
 var resolveBanner = (config) => {
   const { banner } = config;
   if (!banner) {
@@ -5048,7 +5431,7 @@ var buildRuntimeData = (project) => {
     if (!(editBase && sourcePath)) {
       return null;
     }
-    const rel = relative4(context.root, sourcePath).split("\\").join("/");
+    const rel = relative5(context.root, sourcePath).split("\\").join("/");
     return `${editBase}/${github?.dir ? `${github.dir}/${rel}` : rel}`;
   };
   const { i18n } = config;
@@ -5081,6 +5464,7 @@ var buildRuntimeData = (project) => {
   const data = {
     config: {
       analytics: config.analytics ?? null,
+      appleIcon: resolveAppleIcon(project),
       banner: resolveBanner(config),
       codeWrap: config.markdown.code.wrap,
       description: config.description,
@@ -5099,7 +5483,7 @@ var buildRuntimeData = (project) => {
       imageZoom: config.markdown.imageZoom,
       logo: resolveLogo(project),
       mcp: config.mcp.enabled ? { name: config.mcp.name ?? config.title, route: config.mcp.route } : null,
-      og: { enabled: config.seo.og.enabled },
+      og: { enabled: config.seo.og.enabled ?? false },
       repoUrl,
       search: {
         enabled: config.search.provider !== "none",
@@ -5141,7 +5525,7 @@ var buildRuntimeData = (project) => {
 var planMcp = (project, srcDir) => {
   const { config } = project;
   const { route } = config.mcp;
-  const dir = join9(srcDir, "blume-mcp");
+  const dir = join11(srcDir, "blume-mcp");
   const base = {
     dir,
     discoveryPages: [],
@@ -5165,11 +5549,11 @@ var planMcp = (project, srcDir) => {
     ...base,
     discoveryPages: [
       {
-        entrypoint: join9(dir, "discovery.ts"),
+        entrypoint: join11(dir, "discovery.ts"),
         pattern: "/.well-known/mcp.json"
       },
       {
-        entrypoint: join9(dir, "server-card.ts"),
+        entrypoint: join11(dir, "server-card.ts"),
         pattern: "/.well-known/mcp/server-card.json"
       }
     ],
@@ -5188,49 +5572,57 @@ var writeMcpFiles = async (project, plan, write) => {
     version: data.version
   };
   await Promise.all([
-    write(join9(plan.srcDir, "generated", "mcp-data.json"), `${JSON.stringify(data)}
+    write(join11(plan.srcDir, "generated", "mcp-data.json"), `${JSON.stringify(data)}
 `),
-    write(join9(plan.srcDir, "pages", mcpPageFile(plan.route)), mcpEndpointTemplate(plan.route)),
-    write(join9(plan.dir, "discovery.ts"), staticJsonEndpointTemplate(buildMcpDiscovery(discoveryInput))),
-    write(join9(plan.dir, "server-card.ts"), staticJsonEndpointTemplate(buildMcpServerCard(discoveryInput)))
+    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)))
   ]);
 };
 var generateRuntime = async (project) => {
   const { context, config } = project;
   const out = context.outDir;
-  const srcDir = join9(out, "src");
-  const dataPath = join9(srcDir, "generated", "data.json");
-  const themePath = join9(srcDir, "generated", "app.css");
-  const searchClientPath = join9(srcDir, "generated", "search-client.ts");
+  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 written = new Set;
   const write = (path, content) => {
     written.add(normalize(path));
     return writeIfChanged(path, content);
   };
-  await ensureDepsLink(out);
+  const depsLinkWarning = await ensureDepsLink(out);
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
-  const [pages, detectedReact, userTheme, islandDiscovery] = await Promise.all([
+  const [pages, detectedReact, userTheme, islandDiscovery, exampleDiscovery] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(context.root),
     readOptional(context.themeFile),
-    discoverIslands(context.root)
+    discoverIslands(context.root),
+    discoverExamples(context.root, config.examples)
+  ]);
+  const frameworks = new Set([
+    ...islandDiscovery.islands.map((island) => island.framework),
+    ...exampleDiscovery.examples.map((example) => example.framework)
   ]);
-  const islandFrameworks = new Set(islandDiscovery.islands.map((island) => island.framework));
-  const needsReact = detectedReact || askEnabled || islandFrameworks.has("react");
-  const needsVue = islandFrameworks.has("vue");
-  const needsSvelte = islandFrameworks.has("svelte");
+  const needsReact = detectedReact || askEnabled || frameworks.has("react");
+  const needsVue = frameworks.has("vue");
+  const needsSvelte = frameworks.has("svelte");
+  const ogRoutes = customOgRoutes(pages, config.title, config.description);
   const mcp = planMcp(project, srcDir);
   pages.push(...mcp.discoveryPages);
   const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   const structural = await Promise.all([
-    write(join9(out, "astro.config.mjs"), astroConfigTemplate({
+    write(join11(out, "astro.config.mjs"), astroConfigTemplate({
+      aliases: resolveTsconfigAliases(context.root),
       config,
       contentRoutes: project.manifest.routes.map((route) => route.path),
       context,
       dataPath,
+      examplesPath,
       needsReact,
       needsSvelte,
       needsVue,
@@ -5238,18 +5630,19 @@ var generateRuntime = async (project) => {
       searchClientPath,
       themePath
     })),
-    write(join9(out, "package.json"), runtimePackageTemplate(runtimeDependencies({ config, needsReact, needsSvelte, needsVue }))),
-    write(join9(out, "tsconfig.json"), runtimeTsconfigTemplate()),
-    write(join9(srcDir, "env.d.ts"), envTemplate()),
-    write(join9(srcDir, "content.config.ts"), contentConfigTemplate({ config, context, staged: hasStaged })),
-    write(join9(srcDir, "pages", "[...slug].astro"), catchAllPageTemplate({
+    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({
       askEnabled,
       exportEpub,
       exportPdf,
       mathEnabled: config.markdown.math
     })),
-    write(join9(srcDir, "generated", "components.ts"), userComponentsTemplate(context.componentsFile)),
-    write(join9(srcDir, "generated", "islands.ts"), islandMapTemplate(islandDiscovery.islands)),
+    write(join11(srcDir, "generated", "components.ts"), userComponentsTemplate(context.componentsFile)),
+    write(join11(srcDir, "generated", "islands.ts"), islandMapTemplate(islandDiscovery.islands)),
+    write(join11(srcDir, "generated", "examples.ts"), exampleMapTemplate(exampleDiscovery.examples)),
     write(themePath, tailwindEntryTemplate({
       configTokens: `${buildThemeCss(config.theme)}${buildFontsCss(config.theme.fonts)}`,
       sources: [
@@ -5260,52 +5653,58 @@ var generateRuntime = async (project) => {
       userTheme
     }))
   ]);
-  await Promise.all(islandDiscovery.islands.map((island) => write(join9(srcDir, "generated", "islands", `${island.name}.astro`), islandWrapperTemplate(island))));
+  await Promise.all(islandDiscovery.islands.map((island) => write(join11(srcDir, "generated", "islands", `${island.name}.astro`), islandWrapperTemplate(island))));
+  await Promise.all(exampleDiscovery.examples.map((example) => write(join11(srcDir, "generated", "examples", `${exampleSlug(example.path)}.astro`), exampleWrapperTemplate(example))));
   if (askEnabled) {
-    await write(join9(srcDir, "pages", "api", "ask.ts"), askEndpointTemplate(resolveAskBackend(config.ai.ask)));
+    await write(join11(srcDir, "pages", "api", "ask.ts"), askEndpointTemplate(resolveAskBackend(config.ai.ask)));
   }
   await writeMcpFiles(project, mcp, write);
   if (config.seo.og.enabled) {
-    await write(join9(srcDir, "pages", "og", "[...slug].png.ts"), ogEndpointTemplate());
+    await write(join11(srcDir, "pages", "og", "[...slug].png.ts"), ogEndpointTemplate(ogRoutes));
   }
   const hasChangelog = project.graph.pages.some((page) => page.contentType === "changelog" && !(page.meta.draft || page.meta.sidebar.hidden));
   const changelogRouteTaken = project.graph.pages.some((page) => page.route === "/changelog");
   if (hasChangelog && !changelogRouteTaken) {
-    await write(join9(srcDir, "pages", "changelog.astro"), changelogIndexTemplate({ askEnabled, exportEpub, exportPdf }));
+    await write(join11(srcDir, "pages", "changelog.astro"), changelogIndexTemplate({ askEnabled, exportEpub, exportPdf }));
   }
   await write(searchClientPath, searchClientTemplate(config));
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);
-    await write(join9(srcDir, "generated", "search.json"), `${JSON.stringify(documents)}
+    await write(join11(srcDir, "generated", "search.json"), `${JSON.stringify(documents)}
 `);
-    await write(join9(srcDir, "pages", "blume-search.json.ts"), searchEndpointTemplate());
+    await write(join11(srcDir, "pages", "blume-search.json.ts"), searchEndpointTemplate());
   }
   if (config.search.provider === "mixedbread") {
-    await write(join9(srcDir, "pages", "api", "search.ts"), mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? ""));
+    await write(join11(srcDir, "pages", "api", "search.ts"), mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? ""));
   }
   const rawMarkdown = await buildRawMarkdown(project);
   await Promise.all([
-    write(join9(srcDir, "generated", "raw-markdown.json"), `${JSON.stringify(rawMarkdown)}
+    write(join11(srcDir, "generated", "raw-markdown.json"), `${JSON.stringify(rawMarkdown)}
 `),
-    write(join9(srcDir, "pages", "[...slug].md.ts"), rawMarkdownEndpointTemplate()),
-    write(join9(srcDir, "pages", "[...slug].mdx.ts"), rawMarkdownEndpointTemplate())
+    write(join11(srcDir, "pages", "[...slug].md.ts"), rawMarkdownEndpointTemplate()),
+    write(join11(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(join9(srcDir, "generated", "rss.json"), `${JSON.stringify(feedXml)}
+      write(join11(srcDir, "generated", "rss.json"), `${JSON.stringify(feedXml)}
 `),
-      write(join9(srcDir, "pages", "[section]", "rss.xml.ts"), rssEndpointTemplate())
+      write(join11(srcDir, "pages", "[section]", "rss.xml.ts"), rssEndpointTemplate())
     ]);
   }
-  const warnings = [...mcp.warnings, ...islandDiscovery.warnings];
+  const warnings = [
+    ...depsLinkWarning ? [depsLinkWarning] : [],
+    ...mcp.warnings,
+    ...islandDiscovery.warnings,
+    ...exampleDiscovery.warnings
+  ];
   for (const dep of searchProviderMeta(config.search.provider).runtimeDeps) {
     if (!canResolveFrom(context.root, dep)) {
       warnings.push(`Search provider "${config.search.provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`);
     }
   }
-  warnings.push(...islandFrameworkWarnings(islandFrameworks, context.root));
+  warnings.push(...islandFrameworkWarnings(frameworks, context.root));
   if (hasReferences(config)) {
     const references = await buildReferenceFiles({
       config,
@@ -5313,10 +5712,10 @@ var generateRuntime = async (project) => {
       root: context.root
     });
     warnings.push(...references.warnings);
-    await Promise.all(references.files.map((file) => write(join9(srcDir, "pages", file.pagePath), file.content)));
+    await Promise.all(references.files.map((file) => write(join11(srcDir, "pages", file.pagePath), file.content)));
   }
-  await write(join9(srcDir, "generated", "data.json"), buildRuntimeData(project));
-  await write(join9(out, "blume.manifest.json"), `${JSON.stringify(project.manifest, null, 2)}
+  await write(join11(srcDir, "generated", "data.json"), buildRuntimeData(project));
+  await write(join11(out, "blume.manifest.json"), `${JSON.stringify(project.manifest, null, 2)}
 `);
   await writeStagedContent(out, staged);
   await pruneOrphans(srcDir, written);
@@ -5324,13 +5723,13 @@ var generateRuntime = async (project) => {
 };
 
 // src/core/bridge.ts
-import { existsSync as existsSync5 } from "node:fs";
-import { readFile as readFile8 } from "node:fs/promises";
-import { join as join10 } from "pathe";
+import { existsSync as existsSync6 } from "node:fs";
+import { readFile as readFile9 } from "node:fs/promises";
+import { join as join12 } from "pathe";
 
 // src/migrate/mintlify/config.ts
-import { readFile as readFile7 } from "node:fs/promises";
-import { dirname as dirname6, relative as relative5, resolve as resolve2 } from "pathe";
+import { readFile as readFile8 } from "node:fs/promises";
+import { dirname as dirname7, relative as relative6, resolve as resolve3 } from "pathe";
 var MINTLIFY_DEFAULT_IGNORES = [
   "**/_*",
   "**/.*",
@@ -5366,12 +5765,12 @@ var asDirectoryMode = (value) => value === "accordion" || value === "card" || va
 var withoutUndefined = (value) => Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
 var hasOwn = (object, key) => Object.hasOwn(object, key);
 var isInsideRoot = (root, candidate) => {
-  const rel = relative5(root, candidate);
+  const rel = relative6(root, candidate);
   return rel === "" || !rel.startsWith("..") && !rel.startsWith("/");
 };
 var readJsonFile = async (file) => {
   try {
-    return JSON.parse(await readFile7(file, "utf-8"));
+    return JSON.parse(await readFile8(file, "utf-8"));
   } catch (error) {
     throw new BlumeError({
       code: "BLUME_MINTLIFY_CONFIG_INVALID",
@@ -5391,7 +5790,7 @@ var resolveRefs = async (value, options) => {
   }
   const ref = asString(object.$ref);
   if (ref) {
-    const refFile = resolve2(dirname6(options.file), ref);
+    const refFile = resolve3(dirname7(options.file), ref);
     if (!isInsideRoot(options.root, refFile)) {
       throw new BlumeError({
         code: "BLUME_MINTLIFY_REF_OUTSIDE_ROOT",
@@ -5791,7 +6190,7 @@ var mintlifyNavbar = (value) => {
 };
 var mintignorePatterns = async (root) => {
   try {
-    const raw = await readFile7(resolve2(root, ".mintignore"), "utf-8");
+    const raw = await readFile8(resolve3(root, ".mintignore"), "utf-8");
     return raw.split(`
 `).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#")).filter((line) => !line.startsWith("!")).map((line) => line.endsWith("/") ? `${line}**` : line);
   } catch {
@@ -6015,8 +6414,8 @@ var mintlifyIcons = (value) => {
   });
 };
 var loadMintlifyConfig = async (root, file) => {
-  const projectRoot = resolve2(root);
-  const configFile = resolve2(file);
+  const projectRoot = resolve3(root);
+  const configFile = resolve3(file);
   const spec = asObject(await resolveRefs(await readJsonFile(configFile), {
     file: configFile,
     root: projectRoot,
@@ -6117,12 +6516,12 @@ var mintlifyI18n = (spec) => {
 // src/core/bridge.ts
 var MINTLIFY_CONFIG_FILES = ["docs.json", "mint.json"];
 var detectMintlifyBridge = async (root) => {
-  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join10(root, name)).find((candidate) => existsSync5(candidate));
+  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join12(root, name)).find((candidate) => existsSync6(candidate));
   if (!configFile) {
     return null;
   }
   const config = await loadMintlifyConfig(root, configFile);
-  const spec = JSON.parse(await readFile8(configFile, "utf-8"));
+  const spec = JSON.parse(await readFile9(configFile, "utf-8"));
   const i18n = mintlifyI18n(spec);
   if (i18n) {
     config.i18n = i18n;
@@ -6206,8 +6605,8 @@ var createModuleLoader = () => {
 };
 
 // src/core/project.ts
-import { existsSync as existsSync6 } from "node:fs";
-import { isAbsolute as isAbsolute2, join as join11, resolve as resolve3 } from "pathe";
+import { existsSync as existsSync7 } from "node:fs";
+import { isAbsolute as isAbsolute3, join as join13, resolve as resolve4 } from "pathe";
 var CONFIG_FILENAMES = [
   "blume.config.ts",
   "blume.config.mjs",
@@ -6217,8 +6616,8 @@ var THEME_FILENAMES = ["theme.css"];
 var COMPONENTS_FILENAMES = ["components.tsx", "components.ts"];
 var firstExisting = (root, names) => {
   for (const name of names) {
-    const candidate = join11(root, name);
-    if (existsSync6(candidate)) {
+    const candidate = join13(root, name);
+    if (existsSync7(candidate)) {
       return candidate;
     }
   }
@@ -6226,15 +6625,15 @@ var firstExisting = (root, names) => {
 };
 var findConfigFile = (root) => firstExisting(root, CONFIG_FILENAMES);
 var resolveProjectContext = (root, config) => {
-  const absoluteRoot = resolve3(root);
-  const contentRoot = isAbsolute2(config.content.root) ? config.content.root : join11(absoluteRoot, config.content.root);
-  const pagesPath = join11(absoluteRoot, config.content.pages);
-  const pagesRoot = existsSync6(pagesPath) ? pagesPath : null;
+  const absoluteRoot = resolve4(root);
+  const contentRoot = isAbsolute3(config.content.root) ? config.content.root : join13(absoluteRoot, config.content.root);
+  const pagesPath = join13(absoluteRoot, config.content.pages);
+  const pagesRoot = existsSync7(pagesPath) ? pagesPath : null;
   return {
     componentsFile: firstExisting(absoluteRoot, COMPONENTS_FILENAMES),
     configFile: findConfigFile(absoluteRoot),
     contentRoot,
-    outDir: join11(absoluteRoot, ".blume"),
+    outDir: join13(absoluteRoot, ".blume"),
     pagesRoot,
     root: absoluteRoot,
     themeFile: firstExisting(absoluteRoot, THEME_FILENAMES)
@@ -6772,6 +7171,7 @@ var blumeConfigSchema = z2.object({
   contextual: contextualConfigSchema.default({}),
   deployment: deploymentConfigSchema.default({}),
   description: z2.string().optional(),
+  examples: z2.string().default("examples"),
   export: exportConfigSchema.default(false),
   favicon: faviconConfigSchema.optional(),
   feedback: z2.boolean().default(true),
@@ -7183,7 +7583,7 @@ var buildContentGraph = (pages, options) => {
 
 // src/core/last-modified.ts
 import { execFileSync } from "node:child_process";
-import { relative as relative6 } from "pathe";
+import { relative as relative7 } from "pathe";
 var resolveLastModifiedConfig = (value) => {
   if (value === false) {
     return { enabled: false, source: "git" };
@@ -7223,7 +7623,7 @@ var gitLastModifiedTimes = (root, contentRoot, sourcePaths) => {
     const byRepoPath = parseGitLog(output);
     const result = new Map;
     for (const sourcePath of sourcePaths) {
-      const iso = byRepoPath.get(relative6(gitRoot, sourcePath));
+      const iso = byRepoPath.get(relative7(gitRoot, sourcePath));
       if (iso) {
         result.set(sourcePath, iso);
       }
@@ -7235,8 +7635,8 @@ var gitLastModifiedTimes = (root, contentRoot, sourcePaths) => {
 };
 
 // src/core/meta.ts
-import { basename as basename2, dirname as dirname7, relative as relative7 } from "pathe";
-import { glob as glob4 } from "tinyglobby";
+import { basename as basename3, dirname as dirname8, relative as relative8 } from "pathe";
+import { glob as glob5 } from "tinyglobby";
 var META_FILES = [
   "**/meta.ts",
   "**/meta.js",
@@ -7247,16 +7647,16 @@ var META_FILES = [
 ];
 var resolveMeta = async (mod) => typeof mod === "function" ? await mod() : mod;
 var discoverFolderMeta = async (contentRoot) => {
-  const files = await glob4(META_FILES, {
+  const files = await glob5(META_FILES, {
     absolute: true,
     cwd: contentRoot,
     ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
     onlyFiles: true
   });
-  const load = createModuleLoader();
+  const load2 = createModuleLoader();
   const loaded = await Promise.all(files.map(async (file) => {
     try {
-      return { file, ok: true, value: await resolveMeta(await load(file)) };
+      return { file, ok: true, value: await resolveMeta(await load2(file)) };
     } catch (error) {
       return { error, file, ok: false };
     }
@@ -7265,7 +7665,7 @@ var discoverFolderMeta = async (contentRoot) => {
   const shared = new Map;
   const diagnostics = [];
   for (const entry of loaded) {
-    const dir = relative7(contentRoot, dirname7(entry.file));
+    const dir = relative8(contentRoot, dirname8(entry.file));
     if (!entry.ok) {
       diagnostics.push({
         code: "BLUME_META_LOAD_FAILED",
@@ -7277,7 +7677,7 @@ var discoverFolderMeta = async (contentRoot) => {
     }
     const result = folderMetaSchema.safeParse(entry.value);
     if (result.success) {
-      const target = basename2(entry.file).startsWith("meta.$.") ? shared : meta;
+      const target = basename3(entry.file).startsWith("meta.$.") ? shared : meta;
       target.set(dir, result.data);
     } else {
       diagnostics.push(...diagnosticsFromZod(result.error, {
@@ -7290,6 +7690,7 @@ var discoverFolderMeta = async (contentRoot) => {
 };
 
 // src/core/sources/normalize.ts
+import GithubSlugger from "github-slugger";
 import { extname as extname3 } from "pathe";
 var NUMERIC_PREFIX2 = /^\d+[-_.]/u;
 var GROUP_FOLDER2 = /^\((?<label>.+)\)$/u;
@@ -7322,6 +7723,7 @@ var CODE_FENCE2 = /^```/u;
 var ATX_HEADING = /^(?<hashes>#{1,6})\s+(?<text>.+?)\s*#*$/u;
 var extractHeadings = (body) => {
   const headings = [];
+  const slugger = new GithubSlugger;
   let inFence = false;
   for (const line of body.split(`
 `)) {
@@ -7336,7 +7738,7 @@ var extractHeadings = (body) => {
     if (match?.groups) {
       const depth = match.groups.hashes?.length ?? 1;
       const text = (match.groups.text ?? "").trim();
-      headings.push({ depth, slug: slugify2(text), text });
+      headings.push({ depth, slug: slugger.slug(text), text });
     }
   }
   return headings;
@@ -7433,18 +7835,17 @@ var normalizeEntry = (entry, ctx) => {
 };
 
 // src/core/sources/resolve.ts
-import { join as join20 } from "pathe";
+import { join as join22 } from "pathe";
 
 // src/core/sources/filesystem.ts
-import { existsSync as existsSync7, watch as fsWatch } from "node:fs";
-import { readFile as readFile9 } from "node:fs/promises";
-import matter3 from "gray-matter";
-import { extname as extname4, isAbsolute as isAbsolute3, join as join12, relative as relative8, resolve as resolve4 } from "pathe";
-import { glob as glob5 } from "tinyglobby";
+import { existsSync as existsSync8, watch as fsWatch } from "node:fs";
+import { readFile as readFile10 } from "node:fs/promises";
+import { extname as extname4, isAbsolute as isAbsolute4, join as join14, relative as relative9, resolve as resolve5 } from "pathe";
+import { glob as glob6 } from "tinyglobby";
 var filesystemSource = (options) => {
-  const contentRoot = isAbsolute3(options.root) ? options.root : join12(resolve4(options.projectRoot), options.root);
-  const load = async () => {
-    const files = await glob5(options.include, {
+  const contentRoot = isAbsolute4(options.root) ? options.root : join14(resolve5(options.projectRoot), options.root);
+  const load2 = async () => {
+    const files = await glob6(options.include, {
       absolute: true,
       cwd: contentRoot,
       ignore: options.exclude,
@@ -7452,21 +7853,21 @@ var filesystemSource = (options) => {
     });
     files.sort();
     const entries = await Promise.all(files.map(async (file) => {
-      const source = await readFile9(file, "utf-8");
+      const source = await readFile10(file, "utf-8");
       const ext = extname4(file).toLowerCase();
       const format = ext === ".mdx" ? "mdx" : "md";
-      const parsed = matter3(source);
+      const parsed = frontmatter_default(source);
       return {
         body: { format, text: parsed.content },
         data: parsed.data,
-        ref: relative8(contentRoot, file),
+        ref: relative9(contentRoot, file),
         sourcePath: file
       };
     }));
     return { diagnostics: [], entries };
   };
   const validate = () => {
-    if (!existsSync7(contentRoot)) {
+    if (!existsSync8(contentRoot)) {
       throw new BlumeError({
         code: options.missingCode ?? "BLUME_CONTENT_ROOT_MISSING",
         file: contentRoot,
@@ -7477,7 +7878,7 @@ var filesystemSource = (options) => {
     }
   };
   const watch = (onChange) => {
-    if (!existsSync7(contentRoot)) {
+    if (!existsSync8(contentRoot)) {
       return () => {};
     }
     const watcher = fsWatch(contentRoot, { recursive: true }, onChange);
@@ -7485,22 +7886,19 @@ var filesystemSource = (options) => {
   };
   return {
     contentRoot,
-    load,
+    load: load2,
     name: options.name,
     prefix: options.prefix,
-    read: (ref) => readFile9(join12(contentRoot, ref), "utf-8"),
+    read: (ref) => readFile10(join14(contentRoot, ref), "utf-8"),
     staged: false,
     validate,
     watch
   };
 };
 
-// src/core/sources/mdx-remote.ts
-import matter4 from "gray-matter";
-
 // src/core/sources/cache.ts
-import { mkdir as mkdir3, readFile as readFile10, writeFile as writeFile3 } from "node:fs/promises";
-import { join as join13 } from "pathe";
+import { mkdir as mkdir3, readFile as readFile11, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join15 } from "pathe";
 var hashText = (text) => {
   let hash = 5381;
   for (let i = 0;i < text.length; i += 1) {
@@ -7509,11 +7907,11 @@ var hashText = (text) => {
   return hash.toString(36);
 };
 var entriesDigest = (entries) => hashText(entries.map((entry) => `${entry.ref}:${entry.hash ?? hashText(entry.body.text)}`).join("|"));
-var pollingWatch = (load, intervalSeconds) => (onChange) => {
+var pollingWatch = (load2, intervalSeconds) => (onChange) => {
   let last = "";
   const tick = async () => {
     try {
-      const { entries } = await load();
+      const { entries } = await load2();
       const next = entriesDigest(entries);
       if (last && next !== last) {
         onChange();
@@ -7527,11 +7925,11 @@ var pollingWatch = (load, intervalSeconds) => (onChange) => {
   return () => clearInterval(timer);
 };
 var snapshotCache = (cacheDir) => {
-  const file = join13(cacheDir, "entries.json");
+  const file = join15(cacheDir, "entries.json");
   return {
     read: async () => {
       try {
-        return JSON.parse(await readFile10(file, "utf-8"));
+        return JSON.parse(await readFile11(file, "utf-8"));
       } catch {
         return [];
       }
@@ -7663,7 +8061,7 @@ var mdxRemoteSource = (options, ctx) => {
       throw new Error(`${item.fetchUrl} -> ${res.status}`);
     }
     const text = await res.text();
-    const parsed = matter4(text);
+    const parsed = frontmatter_default(text);
     const format = item.ref.toLowerCase().endsWith(".mdx") ? "mdx" : "md";
     return {
       body: { format, text: parsed.content },
@@ -7674,7 +8072,7 @@ var mdxRemoteSource = (options, ctx) => {
       ref: item.ref
     };
   };
-  const load = async () => {
+  const load2 = async () => {
     const result = await loadWithCache(options.name, cache, async () => {
       const refs = await enumerate();
       return await Promise.all(refs.map(fetchEntry));
@@ -7692,35 +8090,91 @@ var mdxRemoteSource = (options, ctx) => {
     return entry?.raw ?? entry?.body.text ?? "";
   };
   return {
-    load,
+    load: load2,
     name: options.name,
     prefix: options.prefix,
     read,
     staged: true,
-    watch: options.pollInterval ? pollingWatch(load, options.pollInterval) : undefined
+    watch: options.pollInterval ? pollingWatch(load2, options.pollInterval) : undefined
   };
 };
 
 // src/core/sources/mintlify.ts
-import { existsSync as existsSync8, watch as fsWatch2 } from "node:fs";
-import { readFile as readFile11 } from "node:fs/promises";
-import matter7 from "gray-matter";
-import { isAbsolute as isAbsolute4, join as join16, relative as relative11, resolve as resolve6 } from "pathe";
-import { glob as glob6 } from "tinyglobby";
-
-// src/migrate/mintlify/transform.ts
-import matter6 from "gray-matter";
+import { existsSync as existsSync10, watch as fsWatch2 } from "node:fs";
+import { readFile as readFile13 } from "node:fs/promises";
+import { isAbsolute as isAbsolute5, join as join18, relative as relative12, resolve as resolve7 } from "pathe";
+import { glob as glob7 } from "tinyglobby";
 
 // src/migrate/shared.ts
-import { writeFile as writeFile4 } from "node:fs/promises";
-import { join as join14 } from "pathe";
+import { existsSync as existsSync9 } from "node:fs";
+import { readFile as readFile12, writeFile as writeFile4 } from "node:fs/promises";
+import { join as join16 } from "pathe";
 var writeBlumeConfig = async (root, config) => {
   const body = `import { defineConfig } from "blume";
 
 export default defineConfig(${JSON.stringify(config, null, 2)});
 `;
-  await writeFile4(join14(root, "blume.config.ts"), body, "utf-8");
+  await writeFile4(join16(root, "blume.config.ts"), body, "utf-8");
+};
+var BLUME_SCRIPTS = {
+  build: "blume build",
+  dev: "blume dev",
+  start: "blume preview"
+};
+var rewriteFrameworkScripts = async (root, cli, remove) => {
+  const pkgPath = join16(root, "package.json");
+  if (!existsSync9(pkgPath)) {
+    return false;
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile12(pkgPath, "utf-8"));
+  } catch {
+    return false;
+  }
+  const { scripts } = pkg;
+  if (!scripts || typeof scripts !== "object") {
+    return false;
+  }
+  const next = {};
+  let changed = false;
+  for (const [name, command] of Object.entries(scripts)) {
+    const blume = BLUME_SCRIPTS[name];
+    if (typeof command === "string" && remove?.test(command)) {
+      changed = true;
+    } else if (typeof command === "string" && blume && cli.test(command) && command !== blume) {
+      next[name] = blume;
+      changed = true;
+    } else {
+      next[name] = command;
+    }
+  }
+  if (changed) {
+    pkg.scripts = next;
+    await writeFile4(pkgPath, `${JSON.stringify(pkg, null, 2)}
+`, "utf-8");
+  }
+  return changed;
 };
+var gitignoreKey = (line) => line.trim().replace(/\/+$/u, "");
+var ensureGitignore = async (root, entries) => {
+  const path = join16(root, ".gitignore");
+  const existing = existsSync9(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) => existsSync9(join16(root, candidate)));
 var attribute = (attrs, name) => {
   const match = attrs.match(new RegExp(`\\b${name}=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')`, "u"));
   return match?.groups?.dq ?? match?.groups?.sq;
@@ -8117,7 +8571,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 dirname8, join as join15, relative as relative9 } from "pathe";
+import { dirname as dirname9, join as join17, relative as relative10 } from "pathe";
 var CALLOUT_DIRECTIVES = {
   Check: "success",
   Danger: "danger",
@@ -8153,9 +8607,9 @@ var rewriteSnippetImports = (source, options) => {
     if (/\.mdx?$/u.test(importSource)) {
       return "";
     }
-    const target = join15(options.root, importSource.replace(/^\/+/u, ""));
+    const target = join17(options.root, importSource.replace(/^\/+/u, ""));
     components.push(importSource.replace(/^\/+/u, ""));
-    let rel = relative9(dirname8(options.filePath), target);
+    let rel = relative10(dirname9(options.filePath), target);
     if (!rel.startsWith(".")) {
       rel = `./${rel}`;
     }
@@ -8345,8 +8799,7 @@ var rewriteMintlifySvgIconProps = (source) => {
 
 // src/migrate/mintlify/snippets.ts
 import { readFile as readFileFromDisk } from "node:fs/promises";
-import matter5 from "gray-matter";
-import { dirname as dirname9, relative as relative10, resolve as resolve5 } from "pathe";
+import { dirname as dirname10, relative as relative11, resolve as resolve6 } 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;
@@ -8356,14 +8809,14 @@ var GLOBAL_VARIABLE = /\{\{\s*(?<name>[A-Za-z0-9-]+)\s*\}\}/gu;
 var FRONTMATTER_BLOCK = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/u;
 var USER_EXPORT = /^(?:export\s+)?(?:const|let|var)\s+user\s*=|^import\s+\{\s*user\s*\}/mu;
 var isInsideRoot2 = (root, candidate) => {
-  const rel = relative10(root, candidate);
+  const rel = relative11(root, candidate);
   return rel === "" || !rel.startsWith("..") && !rel.startsWith("/");
 };
 var escapeRegExp = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 var snippetSelfClosingTagPattern = (name) => new RegExp(`<${escapeRegExp(name)}(?<attrs>[^>]*?)\\s*/>`, "gu");
 var snippetPairedTagPattern = (name) => new RegExp(`<${escapeRegExp(name)}(?<attrs>[^>]*?)>[\\s\\S]*?</${escapeRegExp(name)}>`, "gu");
 var rootRelativePath = (root, file) => {
-  const rel = relative10(root, file);
+  const rel = relative11(root, file);
   return rel ? `/${rel}` : "/";
 };
 var snippetCycleMessage = (root, file, trail) => {
@@ -8372,7 +8825,7 @@ var snippetCycleMessage = (root, file, trail) => {
   return `Circular Mintlify snippet import detected: ${cycle}`;
 };
 var resolveSnippetPath = (options) => {
-  const target = options.source.startsWith("/") ? resolve5(options.root, options.source.slice(1)) : resolve5(dirname9(options.filePath), options.source);
+  const target = options.source.startsWith("/") ? resolve6(options.root, options.source.slice(1)) : resolve6(dirname10(options.filePath), options.source);
   return isInsideRoot2(options.root, target) ? target : null;
 };
 var collectImports = (source) => [...source.matchAll(MARKDOWN_SNIPPET_IMPORT)].flatMap((match) => {
@@ -8435,10 +8888,10 @@ var rewriteMintlifyMarkdownSnippets = async (source, options) => {
       throw new Error(snippetCycleMessage(options.root, file, options.trail ?? []));
     }
     seen.add(file);
-    const readFile11 = options.readFile ?? readFileFromDisk;
+    const readFile13 = options.readFile ?? readFileFromDisk;
     try {
-      const raw = await readFile11(file);
-      const content = matter5(raw).content.trim();
+      const raw = await readFile13(file);
+      const content = frontmatter_default(raw).content.trim();
       const transformed = await rewriteMintlifyMarkdownSnippets(content, {
         ...options,
         filePath: file,
@@ -8478,7 +8931,7 @@ var rewriteMintlifyMarkdownSnippets = async (source, options) => {
   return await inlineAt(0, source);
 };
 var rewriteMintlifySnippetVariables = async (source, options) => {
-  const readFile11 = options.readFile ?? readFileFromDisk;
+  const readFile13 = options.readFile ?? readFileFromDisk;
   const inlineImport = async (current, variableImport) => {
     const file = resolveSnippetPath({
       filePath: options.filePath,
@@ -8488,7 +8941,7 @@ var rewriteMintlifySnippetVariables = async (source, options) => {
     if (!file) {
       return current;
     }
-    const exports = collectStringExports(matter5(await readFile11(file)).content);
+    const exports = collectStringExports(frontmatter_default(await readFile13(file)).content);
     let next = current;
     for (const name of variableImport.names) {
       const value = exports.get(name.imported);
@@ -8544,10 +8997,10 @@ var transformMintlifyContent = async (raw, options) => {
   text = rewriteMintlifyExampleBlocks(text);
   text = rewriteMintlifyCallouts(text);
   const unsupported = unsupportedMintlifyComponents(text);
-  const parsed = matter6(text);
+  const parsed = frontmatter_default(text);
   const mapped = normalizeMintlifyPageMeta(parsed.data);
   const { data, removed } = stripUnknownPageMeta(mapped);
-  const content = Object.keys(data).length > 0 ? matter6.stringify(parsed.content, data) : parsed.content;
+  const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
   return {
     components: snippetImports.components,
     content,
@@ -8566,15 +9019,15 @@ var MINTLIFY_SOURCE_IGNORES = [
   "snippets/**"
 ];
 var mintlifySource = (options) => {
-  const contentRoot = isAbsolute4(options.root) ? options.root : join16(resolve6(options.projectRoot), options.root);
+  const contentRoot = isAbsolute5(options.root) ? options.root : join18(resolve7(options.projectRoot), options.root);
   const ignore = [...new Set([...options.exclude, ...MINTLIFY_SOURCE_IGNORES])];
   const transform = (raw, file) => transformMintlifyContent(raw, {
     filePath: file,
-    root: resolve6(options.projectRoot),
+    root: resolve7(options.projectRoot),
     variables: options.variables
   });
-  const load = async () => {
-    const files = await glob6(options.include, {
+  const load2 = async () => {
+    const files = await glob7(options.include, {
       absolute: true,
       cwd: contentRoot,
       ignore,
@@ -8583,16 +9036,16 @@ var mintlifySource = (options) => {
     files.sort();
     const unsupported = new Set;
     const entries = await Promise.all(files.map(async (file) => {
-      const result = await transform(await readFile11(file, "utf-8"), file);
+      const result = await transform(await readFile13(file, "utf-8"), file);
       for (const name of result.unsupported) {
         unsupported.add(name);
       }
-      const parsed = matter7(result.content);
+      const parsed = frontmatter_default(result.content);
       return {
         body: { format: "mdx", text: parsed.content },
         data: parsed.data,
         raw: result.content,
-        ref: relative11(contentRoot, file),
+        ref: relative12(contentRoot, file),
         sourcePath: file
       };
     }));
@@ -8606,7 +9059,7 @@ var mintlifySource = (options) => {
     return { diagnostics, entries };
   };
   const validate = () => {
-    if (!existsSync8(contentRoot)) {
+    if (!existsSync10(contentRoot)) {
       throw new BlumeError({
         code: "BLUME_CONTENT_ROOT_MISSING",
         file: contentRoot,
@@ -8618,11 +9071,11 @@ var mintlifySource = (options) => {
   };
   const watch = (onChange) => {
     const disposers = [];
-    if (existsSync8(contentRoot)) {
+    if (existsSync10(contentRoot)) {
       const watcher = fsWatch2(contentRoot, { recursive: true }, onChange);
       disposers.push(() => watcher.close());
     }
-    if (options.configFile && existsSync8(options.configFile)) {
+    if (options.configFile && existsSync10(options.configFile)) {
       const watcher = fsWatch2(options.configFile, onChange);
       disposers.push(() => watcher.close());
     }
@@ -8633,13 +9086,13 @@ var mintlifySource = (options) => {
     };
   };
   const read = async (ref) => {
-    const file = join16(contentRoot, ref);
-    const result = await transform(await readFile11(file, "utf-8"), file);
+    const file = join18(contentRoot, ref);
+    const result = await transform(await readFile13(file, "utf-8"), file);
     return result.content;
   };
   return {
     contentRoot,
-    load,
+    load: load2,
     name: options.name,
     prefix: options.prefix,
     read,
@@ -8650,12 +9103,11 @@ var mintlifySource = (options) => {
 };
 
 // src/core/sources/notion.ts
-import matter8 from "gray-matter";
-import { join as join18 } from "pathe";
+import { join as join20 } from "pathe";
 
 // src/core/sources/assets.ts
 import { mkdir as mkdir4, writeFile as writeFile5 } from "node:fs/promises";
-import { extname as extname5, join as join17 } from "pathe";
+import { extname as extname5, join as join19 } from "pathe";
 var MD_IMAGE = /!\[(?<alt>[^\]]*)\]\((?<url>[^)\s]+)\)/gu;
 var REMOTE = /^https?:\/\//u;
 var SAFE_EXT = /^\.[a-z0-9]+$/iu;
@@ -8684,7 +9136,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(join17(ctx.assetsDir, file), bytes);
+      await writeFile5(join19(ctx.assetsDir, file), bytes);
       rewrites.set(url, `${ctx.assetsBaseUrl}/${file}`);
     } catch (error) {
       diagnostics.push({
@@ -8778,8 +9230,8 @@ ${text}
 };
 var notionSource = (options, ctx) => {
   const props = options.properties ?? {};
-  const cache = snapshotCache(ctx?.cacheDir ?? join18(".blume", "cache", options.name));
-  const assetsDir = ctx?.assetsDir ?? join18(".blume", "public", "blume-assets", options.name);
+  const cache = snapshotCache(ctx?.cacheDir ?? join20(".blume", "cache", options.name));
+  const assetsDir = ctx?.assetsDir ?? join20(".blume", "public", "blume-assets", options.name);
   const assetsBaseUrl = ctx?.assetsBaseUrl ?? `/blume-assets/${options.name}`;
   let snapshot = new Map;
   const resolveClient = async () => {
@@ -8895,7 +9347,7 @@ ${rendered.join(`
       assetsDir,
       fetchImpl: options.fetchImpl
     });
-    const raw = matter8.stringify(assets.markdown, data);
+    const raw = frontmatter_default.stringify(assets.markdown, data);
     return {
       diagnostics: assets.diagnostics,
       entry: {
@@ -8908,7 +9360,7 @@ ${rendered.join(`
       }
     };
   };
-  const load = async () => {
+  const load2 = async () => {
     const assetDiagnostics = [];
     const result = await loadWithCache(options.name, cache, async () => {
       const client = await resolveClient();
@@ -8937,18 +9389,17 @@ ${rendered.join(`
     return all.find((e) => e.ref === ref)?.raw ?? "";
   };
   return {
-    load,
+    load: load2,
     name: options.name,
     prefix: options.prefix,
     read,
     staged: true,
-    watch: options.pollInterval ? pollingWatch(load, options.pollInterval) : undefined
+    watch: options.pollInterval ? pollingWatch(load2, options.pollInterval) : undefined
   };
 };
 
 // src/core/sources/sanity.ts
-import matter9 from "gray-matter";
-import { join as join19 } from "pathe";
+import { join as join21 } from "pathe";
 
 // src/core/sources/portable-text.ts
 var HEADING_STYLES = {
@@ -9087,7 +9538,7 @@ var resolveClient = async (options, preview) => {
 };
 var sanitySource = (options, ctx) => {
   const fields = options.fields ?? {};
-  const cache = snapshotCache(ctx?.cacheDir ?? join19(".blume", "cache", options.name));
+  const cache = snapshotCache(ctx?.cacheDir ?? join21(".blume", "cache", options.name));
   let snapshot = new Map;
   const toEntry = (doc) => {
     const slugValue = asString2(getPath(doc, fields.slug ?? "slug.current")) ?? asString2(doc._id) ?? "untitled";
@@ -9109,7 +9560,7 @@ var sanitySource = (options, ctx) => {
       },
       serializers: options.serializers
     }) : "";
-    const raw = matter9.stringify(markdown, data);
+    const raw = frontmatter_default.stringify(markdown, data);
     return {
       body: { format: "md", text: markdown },
       data,
@@ -9119,7 +9570,7 @@ var sanitySource = (options, ctx) => {
       ref: `${slug}.md`
     };
   };
-  const load = async () => {
+  const load2 = async () => {
     const result = await loadWithCache(options.name, cache, async () => {
       const client = await resolveClient(options, ctx?.preview ?? false);
       const docs = await client.fetch(options.query);
@@ -9137,12 +9588,12 @@ var sanitySource = (options, ctx) => {
     return all.find((e) => e.ref === ref)?.raw ?? "";
   };
   return {
-    load,
+    load: load2,
     name: options.name,
     prefix: options.prefix,
     read,
     staged: true,
-    watch: options.pollInterval ? pollingWatch(load, options.pollInterval) : undefined
+    watch: options.pollInterval ? pollingWatch(load2, options.pollInterval) : undefined
   };
 };
 
@@ -9162,8 +9613,8 @@ var uniqueNamer = () => {
 };
 var sourceContext = (context, name, runtime) => ({
   assetsBaseUrl: `/blume-assets/${name}`,
-  assetsDir: join20(context.outDir, "public", "blume-assets", name),
-  cacheDir: join20(context.outDir, "cache", name),
+  assetsDir: join22(context.outDir, "public", "blume-assets", name),
+  cacheDir: join22(context.outDir, "cache", name),
   mode: runtime.mode,
   preview: runtime.preview,
   projectRoot: context.root,
@@ -9396,7 +9847,7 @@ var buildCommand = defineCommand2({
       logLevel: "info",
       root: project.context.outDir
     });
-    const distDir = join21(root, "dist");
+    const distDir = join23(root, "dist");
     if (project.config.search.provider === "pagefind") {
       logger.start("Building search index");
       const indexed = await buildSearchIndex(distDir);
@@ -9410,19 +9861,19 @@ var buildCommand = defineCommand2({
     if (project.config.ai.llmsTxt) {
       const { index, full } = await buildLlmsFiles(project);
       await Promise.all([
-        writeFile6(join21(distDir, "llms.txt"), index, "utf-8"),
-        writeFile6(join21(distDir, "llms-full.txt"), full, "utf-8")
+        writeFile6(join23(distDir, "llms.txt"), index, "utf-8"),
+        writeFile6(join23(distDir, "llms-full.txt"), full, "utf-8")
       ]);
       logger.success("Generated llms.txt and llms-full.txt");
     }
     const sitemap = buildSitemap(project);
-    if (sitemap && !existsSync9(join21(distDir, "sitemap.xml"))) {
-      await writeFile6(join21(distDir, "sitemap.xml"), sitemap, "utf-8");
+    if (sitemap && !existsSync11(join23(distDir, "sitemap.xml"))) {
+      await writeFile6(join23(distDir, "sitemap.xml"), sitemap, "utf-8");
       logger.success("Generated sitemap.xml");
     }
     const robots = buildRobots(project);
-    if (robots && !existsSync9(join21(distDir, "robots.txt"))) {
-      await writeFile6(join21(distDir, "robots.txt"), robots, "utf-8");
+    if (robots && !existsSync11(join23(distDir, "robots.txt"))) {
+      await writeFile6(join23(distDir, "robots.txt"), robots, "utf-8");
       logger.success("Generated robots.txt");
     }
     const { config } = project;
@@ -9590,39 +10041,47 @@ var doctorCommand = defineCommand4({
 });
 
 // src/cli/commands/eject.ts
-import { readFile as readFile13, writeFile as writeFile8 } from "node:fs/promises";
+import { readFile as readFile15, writeFile as writeFile8 } from "node:fs/promises";
 import { defineCommand as defineCommand5 } from "citty";
-import { join as join23, relative as relative13 } from "pathe";
+import { join as join25, relative as relative14 } from "pathe";
 
 // src/registry/eject.ts
-import { existsSync as existsSync10 } from "node:fs";
-import { cp, mkdir as mkdir5, readFile as readFile12, rm as rm2, writeFile as writeFile7 } from "node:fs/promises";
-import { join as join22, relative as relative12 } from "pathe";
+import { existsSync as existsSync12 } from "node:fs";
+import { cp, mkdir as mkdir5, readFile as readFile14, rm as rm2, writeFile as writeFile7 } from "node:fs/promises";
+import { join as join24, relative as relative13 } from "pathe";
 var POSIX = (path) => path.split("\\").join("/");
 var eject = async (root) => {
   const project = await scanProject(root, { mode: "build" });
   const { context, config } = project;
-  const srcDir = join22(root, "src");
-  const genDir = join22(srcDir, "generated");
+  const srcDir = join24(root, "src");
+  const genDir = join24(srcDir, "generated");
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
-  const [pages, needsReactRaw, userTheme, rawMarkdown] = await Promise.all([
+  const [pages, needsReactRaw, userTheme, rawMarkdown, islands, examples] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(root),
-    context.themeFile ? readFile12(context.themeFile, "utf-8") : Promise.resolve(""),
-    buildRawMarkdown(project)
+    context.themeFile ? readFile14(context.themeFile, "utf-8") : Promise.resolve(""),
+    buildRawMarkdown(project),
+    discoverIslands(root),
+    discoverExamples(root)
+  ]);
+  const frameworks = new Set([
+    ...islands.islands.map((island) => island.framework),
+    ...examples.examples.map((example) => example.framework)
   ]);
-  const needsReact = needsReactRaw || askEnabled;
+  const needsReact = needsReactRaw || askEnabled || frameworks.has("react");
+  const needsVue = frameworks.has("vue");
+  const needsSvelte = frameworks.has("svelte");
   const relContext = {
     ...context,
-    contentRoot: POSIX(relative12(root, context.contentRoot)),
+    contentRoot: POSIX(relative13(root, context.contentRoot)),
     outDir: ".",
     root: "."
   };
-  const componentsImport = context.componentsFile ? `../../${POSIX(relative12(root, context.componentsFile))}` : null;
+  const componentsImport = context.componentsFile ? `../../${POSIX(relative13(root, context.componentsFile))}` : null;
   const relPages = pages.map((page) => ({
-    entrypoint: POSIX(relative12(root, page.entrypoint)),
+    entrypoint: POSIX(relative13(root, page.entrypoint)),
     pattern: page.pattern
   }));
   const staged = collectStaged(project);
@@ -9635,18 +10094,21 @@ var eject = async (root) => {
         contentRoutes: project.manifest.routes.map((route) => route.path),
         context: relContext,
         dataPath: "./src/generated/data.json",
+        examplesPath: "./src/generated/examples.ts",
         needsReact,
+        needsSvelte,
+        needsVue,
         pages: relPages,
         searchClientPath: "./src/generated/search-client.ts",
         themePath: "./src/generated/app.css"
       }),
-      path: join22(root, "astro.config.mjs")
+      path: join24(root, "astro.config.mjs")
     },
     {
       content: runtimeTsconfigTemplate(),
-      path: join22(root, "tsconfig.json")
+      path: join24(root, "tsconfig.json")
     },
-    { content: envTemplate(), path: join22(srcDir, "env.d.ts") },
+    { content: envTemplate(), path: join24(srcDir, "env.d.ts") },
     {
       content: contentConfigTemplate({
         config,
@@ -9654,7 +10116,7 @@ var eject = async (root) => {
         staged: hasStaged,
         stagedBase: stagedDir
       }),
-      path: join22(srcDir, "content.config.ts")
+      path: join24(srcDir, "content.config.ts")
     },
     {
       content: catchAllPageTemplate({
@@ -9663,11 +10125,19 @@ var eject = async (root) => {
         exportPdf,
         mathEnabled: config.markdown.math
       }),
-      path: join22(srcDir, "pages", "[...slug].astro")
+      path: join24(srcDir, "pages", "[...slug].astro")
     },
     {
       content: userComponentsTemplate(componentsImport),
-      path: join22(genDir, "components.ts")
+      path: join24(genDir, "components.ts")
+    },
+    {
+      content: islandMapTemplate(islands.islands),
+      path: join24(genDir, "islands.ts")
+    },
+    {
+      content: exampleMapTemplate(examples.examples),
+      path: join24(genDir, "examples.ts")
     },
     {
       content: tailwindEntryTemplate({
@@ -9679,54 +10149,54 @@ var eject = async (root) => {
         twoslashCss: twoslashCss(),
         userTheme
       }),
-      path: join22(genDir, "app.css")
+      path: join24(genDir, "app.css")
     },
-    { content: buildRuntimeData(project), path: join22(genDir, "data.json") },
+    { content: buildRuntimeData(project), path: join24(genDir, "data.json") },
     {
       content: `${JSON.stringify(rawMarkdown)}
 `,
-      path: join22(genDir, "raw-markdown.json")
+      path: join24(genDir, "raw-markdown.json")
     },
     {
       content: rawMarkdownEndpointTemplate(),
-      path: join22(srcDir, "pages", "[...slug].md.ts")
+      path: join24(srcDir, "pages", "[...slug].md.ts")
     },
     {
       content: rawMarkdownEndpointTemplate(),
-      path: join22(srcDir, "pages", "[...slug].mdx.ts")
+      path: join24(srcDir, "pages", "[...slug].mdx.ts")
     }
   ];
   if (askEnabled) {
     files.push({
       content: askEndpointTemplate(resolveAskBackend(config.ai.ask)),
-      path: join22(srcDir, "pages", "api", "ask.ts")
+      path: join24(srcDir, "pages", "api", "ask.ts")
     });
   }
   if (config.seo.og.enabled) {
     files.push({
-      content: ogEndpointTemplate(),
-      path: join22(srcDir, "pages", "og", "[...slug].png.ts")
+      content: ogEndpointTemplate(customOgRoutes(pages, config.title, config.description)),
+      path: join24(srcDir, "pages", "og", "[...slug].png.ts")
     });
   }
   files.push({
     content: searchClientTemplate(config),
-    path: join22(genDir, "search-client.ts")
+    path: join24(genDir, "search-client.ts")
   });
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);
     files.push({
       content: `${JSON.stringify(documents)}
 `,
-      path: join22(genDir, "search.json")
+      path: join24(genDir, "search.json")
     }, {
       content: searchEndpointTemplate(),
-      path: join22(srcDir, "pages", "blume-search.json.ts")
+      path: join24(srcDir, "pages", "blume-search.json.ts")
     });
   }
   if (config.search.provider === "mixedbread") {
     files.push({
       content: mixedbreadSearchEndpointTemplate(config.search.mixedbread?.storeId ?? ""),
-      path: join22(srcDir, "pages", "api", "search.ts")
+      path: join24(srcDir, "pages", "api", "search.ts")
     });
   }
   const feeds = buildRssFeeds(project);
@@ -9735,10 +10205,10 @@ var eject = async (root) => {
     files.push({
       content: `${JSON.stringify(feedXml)}
 `,
-      path: join22(genDir, "rss.json")
+      path: join24(genDir, "rss.json")
     }, {
       content: rssEndpointTemplate(),
-      path: join22(srcDir, "pages", "[section]", "rss.xml.ts")
+      path: join24(srcDir, "pages", "[section]", "rss.xml.ts")
     });
   }
   if (hasReferences(config)) {
@@ -9750,20 +10220,27 @@ var eject = async (root) => {
     for (const file of references.files) {
       files.push({
         content: file.content,
-        path: join22(srcDir, "pages", file.pagePath)
+        path: join24(srcDir, "pages", file.pagePath)
       });
     }
   }
+  files.push(...islands.islands.map((island) => ({
+    content: islandWrapperTemplate(island),
+    path: join24(genDir, "islands", `${island.name}.astro`)
+  })), ...examples.examples.map((example) => ({
+    content: exampleWrapperTemplate(example),
+    path: join24(genDir, "examples", `${exampleSlug(example.path)}.astro`)
+  })));
   for (const [entryId, content] of staged) {
-    files.push({ content, path: join22(root, stagedDir, entryId) });
+    files.push({ content, path: join24(root, stagedDir, entryId) });
   }
   await Promise.all(files.map(async (file) => {
-    await mkdir5(join22(file.path, ".."), { recursive: true });
+    await mkdir5(join24(file.path, ".."), { recursive: true });
     await writeFile7(file.path, file.content, "utf-8");
   }));
-  const assetsSrc = join22(context.outDir, "public", "blume-assets");
-  if (existsSync10(assetsSrc)) {
-    await cp(assetsSrc, join22(root, "public", "blume-assets"), {
+  const assetsSrc = join24(context.outDir, "public", "blume-assets");
+  if (existsSync12(assetsSrc)) {
+    await cp(assetsSrc, join24(root, "public", "blume-assets"), {
       recursive: true
     });
   }
@@ -9773,10 +10250,10 @@ var eject = async (root) => {
 
 // src/cli/commands/eject.ts
 var updatePackageScripts = async (root) => {
-  const pkgPath = join23(root, "package.json");
+  const pkgPath = join25(root, "package.json");
   let pkg;
   try {
-    pkg = JSON.parse(await readFile13(pkgPath, "utf-8"));
+    pkg = JSON.parse(await readFile15(pkgPath, "utf-8"));
   } catch {
     return;
   }
@@ -9809,7 +10286,7 @@ var ejectCommand = defineCommand5({
     await updatePackageScripts(root);
     logger.success(`Ejected ${files.length} file(s):`);
     for (const file of files) {
-      process.stdout.write(`  ${relative13(root, file)}
+      process.stdout.write(`  ${relative14(root, file)}
 `);
     }
     logger.box(`Your project is now a standalone Astro app.
@@ -9822,10 +10299,10 @@ The blume package remains importable.`);
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync11 } from "node:fs";
+import { existsSync as existsSync13 } from "node:fs";
 import { mkdir as mkdir6, writeFile as writeFile9 } from "node:fs/promises";
 import { defineCommand as defineCommand6 } from "citty";
-import { basename as basename3, dirname as dirname10, join as join24 } from "pathe";
+import { basename as basename4, dirname as dirname11, join as join26 } from "pathe";
 var toPackageName = (raw) => raw.toLowerCase().replaceAll(/[^a-z0-9._-]+/gu, "-").replaceAll(/^[-_.]+|[-_.]+$/gu, "") || "docs";
 var packageTemplate = (name, version) => `{
   "name": ${JSON.stringify(name)},
@@ -9860,11 +10337,11 @@ Welcome to **Blume** — markdown-first docs powered by Astro and Vite.
 Edit \`docs/index.mdx\` to get started, then run \`blume dev\`.
 `;
 var writeFileSafe = async (path, content) => {
-  if (existsSync11(path)) {
+  if (existsSync13(path)) {
     logger.info(`Skipped existing ${path}`);
     return false;
   }
-  await mkdir6(dirname10(path), { recursive: true });
+  await mkdir6(dirname11(path), { recursive: true });
   await writeFile9(path, content, "utf-8");
   logger.success(`Created ${path}`);
   return true;
@@ -9885,9 +10362,9 @@ var initCommand = defineCommand6({
   async run({ args }) {
     const root = process.cwd();
     const contentDir = args["content-dir"] ?? "docs";
-    const createdPackage = await writeFileSafe(join24(root, "package.json"), packageTemplate(toPackageName(basename3(root)), getBlumeVersion()));
-    await writeFileSafe(join24(root, "blume.config.ts"), CONFIG_TEMPLATE);
-    await writeFileSafe(join24(root, contentDir, "index.mdx"), INDEX_TEMPLATE);
+    const createdPackage = await writeFileSafe(join26(root, "package.json"), packageTemplate(toPackageName(basename4(root)), getBlumeVersion()));
+    await writeFileSafe(join26(root, "blume.config.ts"), CONFIG_TEMPLATE);
+    await writeFileSafe(join26(root, contentDir, "index.mdx"), INDEX_TEMPLATE);
     const nextSteps = createdPackage ? `Next steps:
 
   npm install
@@ -9904,16 +10381,15 @@ var initCommand = defineCommand6({
 import { defineCommand as defineCommand7 } from "citty";
 
 // src/migrate/fumadocs/index.ts
-import { existsSync as existsSync14 } from "node:fs";
-import { mkdir as mkdir7, readFile as readFile15, rename as rename2, rm as rm3, writeFile as writeFile10 } from "node:fs/promises";
-import matter11 from "gray-matter";
-import { dirname as dirname12, join as join26, relative as relative14 } from "pathe";
-import { glob as glob7 } from "tinyglobby";
+import { existsSync as existsSync17 } 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 dirname14, join as join29, relative as relative15 } from "pathe";
+import { glob as glob8 } from "tinyglobby";
 
 // src/migrate/fumadocs/config.ts
-import { existsSync as existsSync12 } from "node:fs";
-import { readFile as readFile14 } from "node:fs/promises";
-import { join as join25 } from "pathe";
+import { existsSync as existsSync14 } from "node:fs";
+import { readFile as readFile16 } from "node:fs/promises";
+import { basename as basename5, dirname as dirname12, join as join27 } from "pathe";
 var SOURCE_FILES = [
   "lib/source.ts",
   "app/source.ts",
@@ -9930,25 +10406,62 @@ var prettifyTitle = (name) => {
   }
   return words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 };
+var GENERIC_NAMES = new Set([
+  "api",
+  "app",
+  "client",
+  "frontend",
+  "server",
+  "site",
+  "web",
+  "www"
+]);
+var gitRepoRoot = (start) => {
+  let dir = start;
+  for (;; ) {
+    if (existsSync14(join27(dir, ".git"))) {
+      return dir;
+    }
+    const parent = dirname12(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+};
+var bareName = (name) => name.includes("/") ? name.slice(name.lastIndexOf("/") + 1) : name;
 var readTitle = async (root) => {
-  const packageJson = join25(root, "package.json");
-  if (!existsSync12(packageJson)) {
+  const packageJson = join27(root, "package.json");
+  if (!existsSync14(packageJson)) {
     return "Documentation";
   }
   try {
-    const parsed = JSON.parse(await readFile14(packageJson, "utf-8"));
-    return typeof parsed.name === "string" && parsed.name.trim() ? prettifyTitle(parsed.name) : "Documentation";
+    const parsed = JSON.parse(await readFile16(packageJson, "utf-8"));
+    const { name } = parsed;
+    if (typeof name !== "string" || !name.trim()) {
+      return "Documentation";
+    }
+    if (GENERIC_NAMES.has(bareName(name).toLowerCase())) {
+      const repoRoot = gitRepoRoot(root);
+      if (repoRoot && repoRoot !== root) {
+        const repoTitle = prettifyTitle(basename5(repoRoot));
+        if (repoTitle !== "Documentation") {
+          return repoTitle;
+        }
+      }
+    }
+    return prettifyTitle(name);
   } catch {
     return "Documentation";
   }
 };
 var scrapeBaseUrl = async (root) => {
   for (const candidate of SOURCE_FILES) {
-    const file = join25(root, candidate);
-    if (!existsSync12(file)) {
+    const file = join27(root, candidate);
+    if (!existsSync14(file)) {
       continue;
     }
-    const base = BASE_URL.exec(await readFile14(file, "utf-8"))?.groups?.base;
+    const base = BASE_URL.exec(await readFile16(file, "utf-8"))?.groups?.base;
     if (base) {
       return base;
     }
@@ -9977,10 +10490,9 @@ var loadFumadocsConfig = async (root) => {
 };
 
 // src/migrate/fumadocs/content.ts
-import { existsSync as existsSync13 } from "node:fs";
+import { existsSync as existsSync15 } from "node:fs";
 import { readFile as readFileFromDisk2 } from "node:fs/promises";
-import matter10 from "gray-matter";
-import { dirname as dirname11, resolve as resolve7 } from "pathe";
+import { dirname as dirname13, resolve as resolve8 } 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, "");
@@ -10181,18 +10693,18 @@ var inlineFumadocsIncludes = async (source, options) => {
     if (!rawPath) {
       continue;
     }
-    const target = resolve7(dirname11(options.filePath), rawPath);
+    const target = resolve8(dirname13(options.filePath), rawPath);
     if (seen.has(target)) {
       warnings.push(`Circular <include> "${rawPath}" — left as-is.`);
       continue;
     }
-    if (!existsSync13(target)) {
+    if (!existsSync15(target)) {
       warnings.push(`<include> target "${rawPath}" not found — left as-is.`);
       continue;
     }
     seen.add(target);
     const raw = await read(target);
-    const nested = await inlineFumadocsIncludes(matter10(raw).content.trim(), {
+    const nested = await inlineFumadocsIncludes(frontmatter_default(raw).content.trim(), {
       ...options,
       filePath: target,
       seen
@@ -10217,10 +10729,16 @@ var normalizeFumadocsPageMeta = (value) => {
   return stripUnknownPageMeta(data);
 };
 
+// src/migrate/fumadocs/groups.ts
+import { existsSync as existsSync16, 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 join28 } from "pathe";
+
 // src/migrate/fumadocs/meta.ts
 var SEPARATOR = /^---(?<label>.*)---$/u;
 var LINK2 = /^(?:\[[^\]]*\])?\[(?<text>[^\]]*)\]\((?<href>[^)]*)\)$/u;
 var REST = "...";
+var EXTRACT = /^\.\.\.(?<folder>.+)$/u;
 var filterPages = (raw) => {
   if (!Array.isArray(raw)) {
     return { pages: [], warnings: [] };
@@ -10235,6 +10753,15 @@ var filterPages = (raw) => {
     if (value === REST || value === "") {
       continue;
     }
+    const extract = EXTRACT.exec(value);
+    if (extract) {
+      const folder = extract.groups?.folder?.trim() ?? "";
+      if (folder) {
+        pages.push(folder);
+        warnings.push(`Sidebar extract "...${folder}" became a normal "${folder}" group (its pages are not flattened into the parent).`);
+      }
+      continue;
+    }
     const separator = SEPARATOR.exec(value);
     if (separator) {
       const label = separator.groups?.label?.trim();
@@ -10250,7 +10777,11 @@ var filterPages = (raw) => {
   }
   return { pages, warnings };
 };
-var translateFumadocsMeta = (value) => {
+var renderMetaModule = (meta) => `import { defineMeta } from "blume";
+
+export default defineMeta(${JSON.stringify(meta, null, 2)});
+`;
+var translateFumadocsSelfMeta = (value) => {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return { meta: {}, warnings: [] };
   }
@@ -10272,23 +10803,197 @@ var translateFumadocsMeta = (value) => {
   if (typeof source.description === "string") {
     warnings.push("Dropped folder `description` — Blume folders have no description field.");
   }
-  const { pages, warnings: pageWarnings } = filterPages(source.pages);
-  if (pages.length > 0) {
-    meta.pages = pages;
+  return { meta, warnings };
+};
+var translateFumadocsMeta = (value) => {
+  const { meta, warnings } = translateFumadocsSelfMeta(value);
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const { pages, warnings: pageWarnings } = filterPages(value.pages);
+    if (pages.length > 0) {
+      meta.pages = pages;
+    }
+    warnings.push(...pageWarnings);
   }
-  warnings.push(...pageWarnings);
   return { meta, warnings };
 };
+var parseFumadocsPages = (raw) => {
+  const lead = [];
+  const sections = [];
+  if (!Array.isArray(raw)) {
+    return { hasSections: false, lead, sections };
+  }
+  let current = null;
+  const push = (item) => {
+    (current ? current.items : lead).push(item);
+  };
+  for (const entry of raw) {
+    if (typeof entry !== "string") {
+      continue;
+    }
+    const value = entry.trim();
+    if (value === REST || value === "") {
+      continue;
+    }
+    const separator = SEPARATOR.exec(value);
+    if (separator) {
+      current = {
+        items: [],
+        label: separator.groups?.label?.trim() || "Section"
+      };
+      sections.push(current);
+      continue;
+    }
+    const extract = EXTRACT.exec(value);
+    if (extract) {
+      const name = extract.groups?.folder?.trim();
+      if (name) {
+        push({ kind: "extract", name });
+      }
+      continue;
+    }
+    const link = LINK2.exec(value);
+    if (link) {
+      push({
+        href: link.groups?.href ?? "",
+        kind: "link",
+        text: link.groups?.text ?? ""
+      });
+      continue;
+    }
+    push({ kind: "ref", name: value });
+  }
+  return { hasSections: sections.length > 0, lead, sections };
+};
+
+// src/migrate/fumadocs/groups.ts
+var PAGE_EXTS = [".mdx", ".md"];
+var WORD_SPLIT3 = /[-_]/u;
+var PATH_SEP = /[/\\]/u;
+var isDirectory = (path) => {
+  try {
+    return statSync2(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
+var resolveEntry = (docsDir, name) => {
+  for (const ext of PAGE_EXTS) {
+    const file = join28(docsDir, `${name}${ext}`);
+    if (existsSync16(file)) {
+      return { kind: "file", path: file };
+    }
+  }
+  const folder = join28(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(" ");
+var linkWarning = (item) => `Dropped sidebar link "${item.text}" (${item.href}) — add it to navbar.links manually.`;
+var extractWarning = (name) => `Sidebar extract "...${name}" became a normal "${name}" group (its pages are not flattened into the parent).`;
+var addUngroupedItem = (item, order, warnings) => {
+  if (item.kind === "link") {
+    warnings.push(linkWarning(item));
+    return;
+  }
+  if (item.kind === "extract") {
+    warnings.push(extractWarning(item.name));
+  }
+  order.push(item.name);
+};
+var reshapeSingleFolderSection = (section, only, order, warnings) => {
+  order.push(only.name);
+  if (humanize2(only.name).toLowerCase() !== section.label.toLowerCase()) {
+    warnings.push(`Section "${section.label}" wraps folder "${only.name}"; set that folder's meta title to "${section.label}" to make the heading match.`);
+  }
+  if (only.kind === "extract") {
+    warnings.push(extractWarning(only.name));
+  }
+};
+var moveItemIntoGroup = async (item, docsDir, groupDir, label, warnings) => {
+  if (item.kind === "link") {
+    warnings.push(linkWarning(item));
+    return null;
+  }
+  const resolved = resolveEntry(docsDir, item.name);
+  if (!resolved) {
+    warnings.push(`Sidebar entry "${item.name}" in section "${label}" matched no page or folder; skipped.`);
+    return null;
+  }
+  const dest = join28(groupDir, basename6(resolved.path));
+  if (existsSync16(dest)) {
+    warnings.push(`Skipped moving "${item.name}" into section "${label}" (target already exists).`);
+    return null;
+  }
+  await mkdir7(groupDir, { recursive: true });
+  await rename2(resolved.path, dest);
+  if (item.kind === "extract") {
+    warnings.push(extractWarning(item.name));
+  }
+  return item.name;
+};
+var reshapeSection = async (section, docsDir, order, warnings) => {
+  const movable = section.items.filter((item) => item.kind !== "link");
+  if (movable.length === 1) {
+    const [only] = movable;
+    if (resolveEntry(docsDir, only.name)?.kind === "folder") {
+      reshapeSingleFolderSection(section, only, order, warnings);
+      return;
+    }
+  }
+  if (PATH_SEP.test(section.label)) {
+    warnings.push(`Section "${section.label}" has a slash in its name and can't become a group folder; its pages stay ungrouped.`);
+    for (const item of section.items) {
+      addUngroupedItem(item, order, warnings);
+    }
+    return;
+  }
+  const groupDir = join28(docsDir, `(${section.label})`);
+  const sectionKeys = [];
+  for (const item of section.items) {
+    const key = await moveItemIntoGroup(item, docsDir, groupDir, section.label, warnings);
+    if (key) {
+      sectionKeys.push(key);
+    }
+  }
+  if (sectionKeys.length === 0) {
+    return;
+  }
+  order.push(section.label);
+  if (sectionKeys.length > 1) {
+    await writeFile10(join28(groupDir, "meta.ts"), renderMetaModule({ pages: sectionKeys }), "utf-8");
+  }
+};
+var reshapeFumadocsGroups = async (structure, docsDir) => {
+  const order = [];
+  const warnings = [];
+  for (const item of structure.lead) {
+    addUngroupedItem(item, order, warnings);
+  }
+  for (const section of structure.sections) {
+    await reshapeSection(section, docsDir, order, warnings);
+  }
+  return { order, warnings };
+};
 
 // src/migrate/fumadocs/index.ts
 var SOURCE_DIR = "content/docs";
 var PAGE_GLOB = "**/*.{md,mdx}";
 var META_GLOB = "**/meta.json";
 var IGNORE = ["**/node_modules/**"];
+var FUMADOCS_LEFTOVERS = [
+  "next.config.ts",
+  "next.config.mjs",
+  "next.config.js",
+  "source.config.ts",
+  "source.config.mjs",
+  "source.config.js",
+  "mdx-components.tsx",
+  "next-env.d.ts",
+  "app"
+];
 var movePage = async (abs, base, root) => {
-  const rel = relative14(base, abs);
-  const dest = join26(root, "docs", rel);
-  if (existsSync14(dest)) {
+  const rel = relative15(base, abs);
+  const dest = join29(root, "docs", rel);
+  if (existsSync17(dest)) {
     return {
       includeWarnings: [],
       moved: 0,
@@ -10297,18 +11002,18 @@ var movePage = async (abs, base, root) => {
       unsupported: []
     };
   }
-  const raw = await readFile15(abs, "utf-8");
+  const raw = await readFile17(abs, "utf-8");
   const included = await inlineFumadocsIncludes(raw, { filePath: abs });
   let text = stripFumadocsImports(included.content);
   text = rewriteFumadocsCallouts(text);
   text = rewriteFumadocsContainers(text);
   text = rewriteFumadocsTabs(text);
   const unsupported = unsupportedFumadocsComponents(text);
-  const parsed = matter11(text);
+  const parsed = frontmatter_default(text);
   const { data, removed } = normalizeFumadocsPageMeta(parsed.data);
-  const content = Object.keys(data).length > 0 ? matter11.stringify(parsed.content, data) : parsed.content;
-  await mkdir7(dirname12(dest), { recursive: true });
-  await writeFile10(dest, content, "utf-8");
+  const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
+  await mkdir8(dirname14(dest), { recursive: true });
+  await writeFile11(dest, content, "utf-8");
   await rm3(abs, { force: true });
   return {
     includeWarnings: included.warnings,
@@ -10318,39 +11023,56 @@ var movePage = async (abs, base, root) => {
     unsupported
   };
 };
+var writeMeta = async (dest, meta, rel, warnings) => {
+  if (Object.keys(meta).length === 0) {
+    return warnings;
+  }
+  if (existsSync17(dest)) {
+    return [...warnings, `Skipped ${rel} (target already exists)`];
+  }
+  await mkdir8(dirname14(dest), { recursive: true });
+  await writeFile11(dest, renderMetaModule(meta), "utf-8");
+  return warnings;
+};
 var convertMeta = async (abs, base, root) => {
-  const rel = relative14(base, abs);
-  const raw = await readFile15(abs, "utf-8");
+  const rel = relative15(base, abs);
+  const raw = await readFile17(abs, "utf-8");
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch {
-    const dest = join26(root, "docs", rel);
-    if (existsSync14(dest)) {
+    const dest2 = join29(root, "docs", rel);
+    if (existsSync17(dest2)) {
       return [`Skipped ${rel} (target already exists)`];
     }
-    await mkdir7(dirname12(dest), { recursive: true });
-    await rename2(abs, dest);
+    await mkdir8(dirname14(dest2), { recursive: true });
+    await rename3(abs, dest2);
     return [
       `Could not parse ${rel}; moved as-is — convert it to meta.ts by hand.`
     ];
   }
-  const { meta, warnings } = translateFumadocsMeta(parsed);
-  const dir = dirname12(rel) === "." ? "" : dirname12(rel);
-  if (Object.keys(meta).length > 0) {
-    const dest = join26(root, "docs", dir, "meta.ts");
-    if (existsSync14(dest)) {
-      await rm3(abs, { force: true });
-      return [...warnings, `Skipped ${rel} (target already exists)`];
-    }
-    await mkdir7(dirname12(dest), { recursive: true });
-    await writeFile10(dest, `import { defineMeta } from "blume";
-
-export default defineMeta(${JSON.stringify(meta, null, 2)});
-`, "utf-8");
+  const dir = dirname14(rel) === "." ? "" : dirname14(rel);
+  const docsDir = join29(root, "docs", dir);
+  const dest = join29(docsDir, "meta.ts");
+  const structure = parseFumadocsPages(parsed.pages);
+  if (structure.hasSections && !existsSync17(dest)) {
+    const self = translateFumadocsSelfMeta(parsed);
+    const reshape = await reshapeFumadocsGroups(structure, docsDir);
+    const meta2 = { ...self.meta };
+    if (reshape.order.length > 0) {
+      meta2.pages = reshape.order;
+    }
+    const result2 = await writeMeta(dest, meta2, rel, [
+      ...self.warnings,
+      ...reshape.warnings
+    ]);
+    await rm3(abs, { force: true });
+    return result2;
   }
+  const { meta, warnings } = translateFumadocsMeta(parsed);
+  const result = await writeMeta(dest, meta, rel, warnings);
   await rm3(abs, { force: true });
-  return warnings;
+  return result;
 };
 var summarizePages = (results) => {
   let moved = 0;
@@ -10380,9 +11102,9 @@ var summarizePages = (results) => {
   };
 };
 var cleanupSourceDirs = async (root) => {
-  const docs = join26(root, "content", "docs");
-  if (existsSync14(docs)) {
-    const remaining = await glob7(["**/*"], { cwd: docs, dot: true });
+  const docs = join29(root, "content", "docs");
+  if (existsSync17(docs)) {
+    const remaining = await glob8(["**/*"], { cwd: docs, dot: true });
     if (remaining.length > 0) {
       return [
         `Kept ${remaining.length} non-page file(s) under content/docs; move them into docs/ manually.`
@@ -10390,9 +11112,9 @@ var cleanupSourceDirs = async (root) => {
     }
     await rm3(docs, { force: true, recursive: true });
   }
-  const content = join26(root, "content");
-  if (existsSync14(content)) {
-    const remaining = await glob7(["**/*"], { cwd: content, dot: true });
+  const content = join29(root, "content");
+  if (existsSync17(content)) {
+    const remaining = await glob8(["**/*"], { cwd: content, dot: true });
     if (remaining.length === 0) {
       await rm3(content, { force: true, recursive: true });
     }
@@ -10401,8 +11123,8 @@ var cleanupSourceDirs = async (root) => {
 };
 var migrateFumadocsProject = async (root) => {
   const { config, warnings: configWarnings } = await loadFumadocsConfig(root);
-  const base = join26(root, SOURCE_DIR);
-  if (!existsSync14(base)) {
+  const base = join29(root, SOURCE_DIR);
+  if (!existsSync17(base)) {
     await writeBlumeConfig(root, config);
     return {
       moved: 0,
@@ -10411,22 +11133,28 @@ var migrateFumadocsProject = async (root) => {
       ]
     };
   }
-  const pageFiles = await glob7([PAGE_GLOB], {
+  const pageFiles = await glob8([PAGE_GLOB], {
     absolute: true,
     cwd: base,
     ignore: IGNORE
   });
-  const metaFiles = await glob7([META_GLOB], {
+  const metaFiles = await glob8([META_GLOB], {
     absolute: true,
     cwd: base,
     ignore: IGNORE
   });
   const pageResults = await Promise.all(pageFiles.map((abs) => movePage(abs, base, root)));
   const pages = summarizePages(pageResults);
-  const metaResults = await Promise.all(metaFiles.map((abs) => convertMeta(abs, base, root)));
-  const metaWarnings = metaResults.flat();
+  const orderedMetas = metaFiles.toSorted((a, b) => b.split("/").length - a.split("/").length);
+  const metaWarnings = [];
+  for (const abs of orderedMetas) {
+    metaWarnings.push(...await convertMeta(abs, base, root));
+  }
   await writeBlumeConfig(root, config);
   const cleanupWarnings = await cleanupSourceDirs(root);
+  const scriptsRewritten = await rewriteFrameworkScripts(root, /\bnext\b/u, /fumadocs/u);
+  const gitignoreAdded = await ensureGitignore(root, [".blume/", "dist/"]);
+  const leftovers = leftoverFiles(root, FUMADOCS_LEFTOVERS);
   const warnings = [
     ...configWarnings,
     ...metaWarnings,
@@ -10440,15 +11168,24 @@ var migrateFumadocsProject = async (root) => {
   if (pages.unsupported.length > 0) {
     warnings.push(`Components without a drop-in Blume equivalent need manual review: ${pages.unsupported.join(", ")}.`);
   }
+  if (scriptsRewritten) {
+    warnings.push("Repointed the dev/build/start scripts at the Blume CLI.");
+  }
+  if (gitignoreAdded.length > 0) {
+    warnings.push(`Added ${gitignoreAdded.join(", ")} to .gitignore.`);
+  }
+  if (leftovers.length > 0) {
+    warnings.push(`Safe to delete once the migration looks right: ${leftovers.join(", ")}. Also drop the \`next\` plugin from tsconfig.json and the \`.next\`/\`.source\` lines from .gitignore.`);
+  }
   warnings.push("Review blume.config.ts and the generated meta.ts files.");
   return { moved: pages.moved, warnings };
 };
 
 // src/migrate/mintlify/index.ts
-import { existsSync as existsSync15 } from "node:fs";
-import { mkdir as mkdir8, readFile as readFile16, rename as rename3, rm as rm4, writeFile as writeFile11 } from "node:fs/promises";
-import { dirname as dirname13, join as join27 } from "pathe";
-import { glob as glob8 } from "tinyglobby";
+import { existsSync as existsSync18 } 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 dirname15, join as join30 } from "pathe";
+import { glob as glob9 } from "tinyglobby";
 var prune = (value) => {
   if (Array.isArray(value)) {
     return value.map(prune);
@@ -10477,7 +11214,7 @@ var writeBlumeConfig2 = async (root, config) => {
 
 export default defineConfig(${JSON.stringify(prune(config), null, 2)});
 `;
-  await writeFile11(join27(root, "blume.config.ts"), body, "utf-8");
+  await writeFile12(join30(root, "blume.config.ts"), body, "utf-8");
 };
 var relocateAssets = async (root, refs) => {
   const segments = new Set;
@@ -10492,30 +11229,30 @@ var relocateAssets = async (root, refs) => {
   }
   const moved = [];
   for (const segment of segments) {
-    const source = join27(root, segment);
-    if (!existsSync15(source) || segment === "public") {
+    const source = join30(root, segment);
+    if (!existsSync18(source) || segment === "public") {
       continue;
     }
-    const dest = join27(root, "public", segment);
-    if (existsSync15(dest)) {
+    const dest = join30(root, "public", segment);
+    if (existsSync18(dest)) {
       continue;
     }
-    await mkdir8(join27(root, "public"), { recursive: true });
-    await rename3(source, dest);
+    await mkdir9(join30(root, "public"), { recursive: true });
+    await rename4(source, dest);
     moved.push(segment);
   }
   return moved;
 };
 var cleanupSnippets = async (root, kept, warnings) => {
-  const dir = join27(root, "snippets");
-  if (!existsSync15(dir)) {
+  const dir = join30(root, "snippets");
+  if (!existsSync18(dir)) {
     return;
   }
-  const markdown = await glob8(["**/*.{md,mdx}"], { absolute: true, cwd: dir });
+  const markdown = await glob9(["**/*.{md,mdx}"], { absolute: true, cwd: dir });
   for (const file of markdown) {
     await rm4(file, { force: true });
   }
-  const remaining = await glob8(["**/*"], { cwd: dir, dot: true });
+  const remaining = await glob9(["**/*"], { cwd: dir, dot: true });
   if (remaining.length === 0) {
     await rm4(dir, { force: true, recursive: true });
     warnings.push("Inlined and removed the /snippets directory.");
@@ -10545,11 +11282,11 @@ var assetRefs = (config) => {
 };
 var migrateMintlifyProject = async (root) => {
   const warnings = [];
-  const configFile = existsSync15(join27(root, "docs.json")) ? join27(root, "docs.json") : join27(root, "mint.json");
+  const configFile = existsSync18(join30(root, "docs.json")) ? join30(root, "docs.json") : join30(root, "mint.json");
   let config;
-  if (existsSync15(configFile)) {
+  if (existsSync18(configFile)) {
     config = await loadMintlifyConfig(root, configFile);
-    const spec = JSON.parse(await readFile16(configFile, "utf-8"));
+    const spec = JSON.parse(await readFile18(configFile, "utf-8"));
     const i18n = mintlifyI18n(spec);
     if (i18n) {
       config.i18n = i18n;
@@ -10564,7 +11301,7 @@ var migrateMintlifyProject = async (root) => {
   }
   const variables = config.variables ?? {};
   config.variables = undefined;
-  const files = await glob8(["**/*.{md,mdx}"], {
+  const files = await glob9(["**/*.{md,mdx}"], {
     absolute: true,
     cwd: root,
     ignore: [
@@ -10580,15 +11317,15 @@ var migrateMintlifyProject = async (root) => {
   const unsupported = new Set;
   const keptComponents = new Set;
   for (const file of files) {
-    const raw = await readFile16(file, "utf-8");
+    const raw = await readFile18(file, "utf-8");
     const result = await transformMintlifyContent(raw, {
       filePath: file,
       root,
       variables
     });
     if (result.content !== raw) {
-      await mkdir8(dirname13(file), { recursive: true });
-      await writeFile11(file, result.content, "utf-8");
+      await mkdir9(dirname15(file), { recursive: true });
+      await writeFile12(file, result.content, "utf-8");
     }
     for (const key of result.removed) {
       removedKeys.add(key);
@@ -10624,11 +11361,10 @@ var migrateMintlifyProject = async (root) => {
 };
 
 // src/migrate/nextra/index.ts
-import { existsSync as existsSync16 } from "node:fs";
-import { mkdir as mkdir9, readFile as readFile17, rename as rename4, rm as rm5, writeFile as writeFile12 } from "node:fs/promises";
-import matter12 from "gray-matter";
-import { basename as basename4, dirname as dirname14, extname as extname6, join as join28, relative as relative15 } from "pathe";
-import { glob as glob9 } from "tinyglobby";
+import { existsSync as existsSync19 } 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 dirname16, extname as extname6, join as join31, relative as relative16 } from "pathe";
+import { glob as glob10 } from "tinyglobby";
 
 // src/migrate/nextra/content.ts
 var CALLOUT_TYPE_DIRECTIVES3 = {
@@ -10857,30 +11593,30 @@ var indexFolders = (base, pageFiles, metaFiles) => {
     let current = normalizeDir(dir);
     allDirs.add(current);
     while (current !== "") {
-      current = normalizeDir(dirname14(current));
+      current = normalizeDir(dirname16(current));
       allDirs.add(current);
     }
   };
   for (const abs of pageFiles) {
-    const rel = relative15(base, abs);
-    const dir = normalizeDir(dirname14(rel));
-    const slug = basename4(rel).replace(/\.mdx?$/u, "");
+    const rel = relative16(base, abs);
+    const dir = normalizeDir(dirname16(rel));
+    const slug = basename7(rel).replace(/\.mdx?$/u, "");
     const folder = pagesByDir.get(dir) ?? new Map;
     folder.set(slug, abs);
     pagesByDir.set(dir, folder);
     registerDir(dir);
   }
   for (const abs of metaFiles) {
-    registerDir(normalizeDir(dirname14(relative15(base, abs))));
+    registerDir(normalizeDir(dirname16(relative16(base, abs))));
   }
   const childDirs = new Map;
   for (const dir of allDirs) {
     if (dir === "") {
       continue;
     }
-    const parent = normalizeDir(dirname14(dir));
+    const parent = normalizeDir(dirname16(dir));
     const children = childDirs.get(parent) ?? new Set;
-    children.add(basename4(dir));
+    children.add(basename7(dir));
     childDirs.set(parent, children);
   }
   return { childDirs, pagesByDir };
@@ -10896,7 +11632,7 @@ var planMetas = (metas, index) => {
     warnings: []
   };
   for (const meta of metas) {
-    const dir = normalizeDir(dirname14(meta.rel));
+    const dir = normalizeDir(dirname16(meta.rel));
     const entries = parseNextraMeta(meta.raw, meta.ext);
     if (!entries) {
       plan.unparseableMetas.push({ abs: meta.abs, rel: meta.rel });
@@ -10909,7 +11645,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(join28(dir, slug)), title);
+      plan.folderTitleByDir.set(normalizeDir(join31(dir, slug)), title);
     }
     for (const [slug, label] of Object.entries(conversion.pageLabels)) {
       const pageAbs = index.pagesByDir.get(dir)?.get(slug);
@@ -10933,19 +11669,19 @@ var planMetas = (metas, index) => {
   return plan;
 };
 var movePage2 = async (abs, options) => {
-  const rel = relative15(options.base, abs);
-  const dest = join28(options.root, "docs", rel);
-  if (existsSync16(dest)) {
+  const rel = relative16(options.base, abs);
+  const dest = join31(options.root, "docs", rel);
+  if (existsSync19(dest)) {
     return { moved: 0, removed: [], skipped: rel, unsupported: [] };
   }
-  const raw = await readFile17(abs, "utf-8");
+  const raw = await readFile19(abs, "utf-8");
   const text = rewriteNextraCallouts(stripNextraImports(raw));
   const unsupported = unsupportedNextraComponents(text);
-  const parsed = matter12(text);
+  const parsed = frontmatter_default(text);
   const { data, removed } = normalizeNextraPageMeta(parsed.data, options.overrides.get(abs) ?? {});
-  const content = Object.keys(data).length > 0 ? matter12.stringify(parsed.content, data) : parsed.content;
-  await mkdir9(dirname14(dest), { recursive: true });
-  await writeFile12(dest, content, "utf-8");
+  const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
+  await mkdir10(dirname16(dest), { recursive: true });
+  await writeFile13(dest, content, "utf-8");
   await rm5(abs, { force: true });
   return { moved: 1, removed, skipped: null, unsupported };
 };
@@ -10987,9 +11723,9 @@ var writeFolderMetas = async (root, plan) => {
     if (Object.keys(finalMeta).length === 0) {
       return;
     }
-    const dest = join28(root, "docs", dir, "meta.ts");
-    await mkdir9(dirname14(dest), { recursive: true });
-    await writeFile12(dest, `import { defineMeta } from "blume";
+    const dest = join31(root, "docs", dir, "meta.ts");
+    await mkdir10(dirname16(dest), { recursive: true });
+    await writeFile13(dest, `import { defineMeta } from "blume";
 
 export default defineMeta(${JSON.stringify(finalMeta, null, 2)});
 `, "utf-8");
@@ -10998,20 +11734,20 @@ 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 = join28(root, "docs", rel);
-    if (existsSync16(dest)) {
+    const dest = join31(root, "docs", rel);
+    if (existsSync19(dest)) {
       warnings.push(`Skipped ${rel} (target already exists)`);
       return;
     }
-    await mkdir9(dirname14(dest), { recursive: true });
-    await rename4(abs, dest);
+    await mkdir10(dirname16(dest), { recursive: true });
+    await rename5(abs, dest);
     warnings.push(`Could not parse ${rel}; moved as-is — convert it to meta.ts by hand.`);
   }));
   return warnings;
 };
 var buildConfig = (tabs) => tabs.length > 0 ? { navigation: { tabs }, title: "Documentation" } : { title: "Documentation" };
 var migrateNextraProject = async (root) => {
-  const sourceDir = SOURCE_DIRS.find((dir) => existsSync16(join28(root, dir)));
+  const sourceDir = SOURCE_DIRS.find((dir) => existsSync19(join31(root, dir)));
   if (!sourceDir) {
     await writeBlumeConfig(root, { title: "Documentation" });
     return {
@@ -11021,13 +11757,13 @@ var migrateNextraProject = async (root) => {
       ]
     };
   }
-  const base = join28(root, sourceDir);
-  const pageFiles = await glob9([PAGE_GLOB2], {
+  const base = join31(root, sourceDir);
+  const pageFiles = await glob10([PAGE_GLOB2], {
     absolute: true,
     cwd: base,
     ignore: IGNORE2
   });
-  const metaFiles = await glob9([META_GLOB2], {
+  const metaFiles = await glob10([META_GLOB2], {
     absolute: true,
     cwd: base,
     ignore: IGNORE2
@@ -11036,8 +11772,8 @@ var migrateNextraProject = async (root) => {
   const metas = await Promise.all(metaFiles.map(async (abs) => ({
     abs,
     ext: extname6(abs),
-    raw: await readFile17(abs, "utf-8"),
-    rel: relative15(base, abs)
+    raw: await readFile19(abs, "utf-8"),
+    rel: relative16(base, abs)
   })));
   const plan = planMetas(metas, index);
   const moves = await Promise.all(pageFiles.map((abs) => movePage2(abs, { base, overrides: plan.pageOverrides, root })));
@@ -11062,16 +11798,15 @@ var migrateNextraProject = async (root) => {
 };
 
 // src/migrate/starlight/index.ts
-import { existsSync as existsSync18 } from "node:fs";
-import { readFile as readFile19, writeFile as writeFile13 } from "node:fs/promises";
-import matter13 from "gray-matter";
-import { join as join30 } from "pathe";
-import { glob as glob10 } from "tinyglobby";
+import { existsSync as existsSync21 } from "node:fs";
+import { readFile as readFile21, writeFile as writeFile14 } from "node:fs/promises";
+import { join as join33 } from "pathe";
+import { glob as glob11 } from "tinyglobby";
 
 // src/migrate/starlight/config.ts
-import { existsSync as existsSync17 } from "node:fs";
-import { readFile as readFile18 } from "node:fs/promises";
-import { join as join29 } from "pathe";
+import { existsSync as existsSync20 } from "node:fs";
+import { readFile as readFile20 } from "node:fs/promises";
+import { join as join32 } from "pathe";
 var CONFIG_FILES = [
   "astro.config.mjs",
   "astro.config.mts",
@@ -11102,7 +11837,7 @@ var extractStarlightOptions = (source) => {
   return isLiteralObject(parsed) ? parsed : "unparseable";
 };
 var loadStarlightConfig = async (root) => {
-  const file = CONFIG_FILES.map((name) => join29(root, name)).find((path) => existsSync17(path));
+  const file = CONFIG_FILES.map((name) => join32(root, name)).find((path) => existsSync20(path));
   if (!file) {
     return {
       options: {},
@@ -11111,7 +11846,7 @@ var loadStarlightConfig = async (root) => {
       ]
     };
   }
-  const source = await readFile18(file, "utf-8");
+  const source = await readFile20(file, "utf-8");
   const result = extractStarlightOptions(source);
   if (result === "missing") {
     return {
@@ -11512,17 +12247,17 @@ var starlightI18n = (options) => {
 // src/migrate/starlight/index.ts
 var CONTENT_DIR = "src/content/docs";
 var transformPage = async (file) => {
-  const raw = await readFile19(file, "utf-8");
+  const raw = await readFile21(file, "utf-8");
   let text = stripStarlightImports(raw);
   text = rewriteStarlightAsides(text);
   text = rewriteStarlightComponents(text);
   const unsupported = unsupportedStarlightComponents(text);
   const aliased = hasAliasedAssets(text);
-  const parsed = matter13(text);
+  const parsed = frontmatter_default(text);
   const { data, removed } = normalizeStarlightPageMeta(parsed.data);
-  const content = Object.keys(data).length > 0 ? matter13.stringify(parsed.content, data) : parsed.content;
+  const content = Object.keys(data).length > 0 ? frontmatter_default.stringify(parsed.content, data) : parsed.content;
   if (content !== raw) {
-    await writeFile13(file, content, "utf-8");
+    await writeFile14(file, content, "utf-8");
   }
   return { aliased, removed, unsupported };
 };
@@ -11534,8 +12269,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 = join30(root, CONTENT_DIR);
-  if (!existsSync18(base)) {
+  const base = join33(root, CONTENT_DIR);
+  if (!existsSync21(base)) {
     await writeBlumeConfig(root, config);
     return {
       moved: 0,
@@ -11545,7 +12280,7 @@ var migrateStarlightProject = async (root) => {
       ]
     };
   }
-  const files = await glob10(["**/*.{md,mdx}"], { absolute: true, cwd: base });
+  const files = await glob11(["**/*.{md,mdx}"], { absolute: true, cwd: base });
   const results = await Promise.all(files.map(transformPage));
   await writeBlumeConfig(root, config);
   const removedKeys = new Set;
@@ -11623,10 +12358,10 @@ var migrateCommand = defineCommand7({
 });
 
 // src/cli/commands/preview.ts
-import { existsSync as existsSync19 } from "node:fs";
+import { existsSync as existsSync22 } from "node:fs";
 import { preview } from "astro";
 import { defineCommand as defineCommand8 } from "citty";
-import { join as join31 } from "pathe";
+import { join as join34 } from "pathe";
 var previewCommand = defineCommand8({
   args: {
     host: { description: "Network host to bind.", type: "string" },
@@ -11640,7 +12375,7 @@ var previewCommand = defineCommand8({
     const root = process.cwd();
     const { config } = await loadConfig(root);
     const context = resolveProjectContext(root, config);
-    if (!existsSync19(join31(context.outDir, "astro.config.mjs"))) {
+    if (!existsSync22(join34(context.outDir, "astro.config.mjs"))) {
       logger.error("No build found. Run `blume build` first.");
       process.exit(1);
     }
@@ -11658,7 +12393,7 @@ var previewCommand = defineCommand8({
 // src/cli/commands/sync.ts
 import { rm as rm6 } from "node:fs/promises";
 import { defineCommand as defineCommand9 } from "citty";
-import { join as join32 } from "pathe";
+import { join as join35 } from "pathe";
 var syncCommand = defineCommand9({
   args: {
     force: {
@@ -11680,7 +12415,7 @@ var syncCommand = defineCommand9({
     if (args.force) {
       const { config } = await loadConfig(root);
       const context = resolveProjectContext(root, config);
-      await rm6(join32(context.outDir, "cache"), { force: true, recursive: true });
+      await rm6(join35(context.outDir, "cache"), { force: true, recursive: true });
       logger.info("Cleared source cache.");
     }
     await prepareProject({
@@ -11695,13 +12430,13 @@ var syncCommand = defineCommand9({
 });
 
 // src/cli/commands/validate.ts
-import { existsSync as existsSync21 } from "node:fs";
+import { existsSync as existsSync24 } from "node:fs";
 import { defineCommand as defineCommand10 } from "citty";
-import { join as join34 } from "pathe";
+import { join as join37 } from "pathe";
 
 // src/core/links.ts
-import { existsSync as existsSync20 } from "node:fs";
-import { join as join33 } from "pathe";
+import { existsSync as existsSync23 } from "node:fs";
+import { join as join36 } from "pathe";
 var HTTP = /^https?:\/\//iu;
 var PROTOCOL_RELATIVE = /^\/\//u;
 var SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
@@ -11761,7 +12496,7 @@ var checkPathLink = (resolved, fragment, target, site, ctx) => {
     if (ctx.publicDir === null) {
       return "asset-unchecked";
     }
-    if (existsSync20(join33(ctx.publicDir, resolved))) {
+    if (existsSync23(join36(ctx.publicDir, resolved))) {
       return null;
     }
     return {
@@ -11773,16 +12508,19 @@ var checkPathLink = (resolved, fragment, target, site, ctx) => {
     };
   }
   const route = toRoute(resolved);
-  if (!ctx.routes.has(route)) {
-    return {
-      ...site,
-      code: "BLUME_BROKEN_LINK",
-      message: `Broken link to ${target}: no page resolves to ${route}.`,
-      severity: "error",
-      suggestion: "Check the path, or create the target page."
-    };
+  if (ctx.routes.has(route)) {
+    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
+  }
+  if (ctx.redirects.has(route)) {
+    return null;
   }
-  return fragment ? checkAnchor(route, fragment, site, ctx) : null;
+  return {
+    ...site,
+    code: "BLUME_BROKEN_LINK",
+    message: `Broken link to ${target}: no page resolves to ${route}.`,
+    severity: "error",
+    suggestion: "Check the path, or create the target page."
+  };
 };
 var request = async (url, method) => {
   const controller = new AbortController;
@@ -11891,6 +12629,7 @@ var validateLinks = async (graph, options) => {
   const ctx = {
     anchors: buildAnchorIndex(graph.pages),
     publicDir: options.publicDir,
+    redirects: new Set((options.redirects ?? []).map((redirect) => toRoute(redirect.from))),
     routes: new Set(graph.routes.keys())
   };
   const diagnostics = [];
@@ -11941,10 +12680,11 @@ var validateCommand = defineCommand10({
     try {
       const project = await scanProject(root, { mode: "build" });
       diagnostics.push(...project.diagnostics);
-      const publicDir = join34(root, "public");
+      const publicDir = join37(root, "public");
       diagnostics.push(...await validateLinks(project.graph, {
         checkExternal: Boolean(args.external),
-        publicDir: existsSync21(publicDir) ? publicDir : null
+        publicDir: existsSync24(publicDir) ? publicDir : null,
+        redirects: project.config.redirects
       }));
     } catch (error) {
       if (error instanceof BlumeError) {
@@ -11985,5 +12725,5 @@ var main = defineCommand11({
 });
 runMain(main);
 
-//# debugId=6F4400D6CD52CE0064756E2164756E21
+//# debugId=C5E764B7F3B6157B64756E2164756E21
 //# sourceMappingURL=index.js.map