blume 1.1.4 → 1.2.0

package/dist/cli/index.js

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/cli/index.ts
-import { defineCommand as defineCommand12, runMain } from "citty";
+import { defineCommand as defineCommand14, runMain } from "citty";
 
 // src/core/version.ts
 import { readFileSync } from "node:fs";
@@ -3090,7 +3090,12 @@ var routeSlug = (route) => slugify(trimChar(route, "/")) || "reference";
 var sourcesOf = (block) => {
   const sources = [...block.sources];
   if (block.spec) {
-    sources.unshift({ spec: block.spec });
+    sources.unshift({
+      includeInLlms: true,
+      includeInSearch: true,
+      noindex: false,
+      spec: block.spec
+    });
   }
   return sources;
 };
@@ -3114,8 +3119,11 @@ var referencesFor = (kind, block, defaultLabel, renderer, display, basePath) =>
     return {
       basePath,
       display,
+      includeInLlms: source.includeInLlms,
+      includeInSearch: source.includeInSearch,
       kind,
       label,
+      noindex: source.noindex,
       renderer,
       route,
       scalar: block.scalar,
@@ -3417,7 +3425,10 @@ var WRANGLER_CONFIG_FILES = [
   "wrangler.toml"
 ];
 var resolveCloudflareAdapterArgs = (context) => {
-  const args = ['prerenderEnvironment: "node"'];
+  const args = [
+    'prerenderEnvironment: "node"',
+    'imageService: "compile"'
+  ];
   const wranglerPath = WRANGLER_CONFIG_FILES.map((file) => join8(context.root, file)).find((file) => existsSync4(file));
   if (wranglerPath) {
     let configPath = relative5(context.outDir, wranglerPath);
@@ -3428,6 +3439,18 @@ var resolveCloudflareAdapterArgs = (context) => {
   }
   return `{ ${args.join(", ")} }`;
 };
+var resolveSessionOption = (deployment) => deployment.output === "server" && deployment.adapter === "cloudflare" ? `
+  session: { driver: sessionDrivers.memory() },` : "";
+var astroConfigImportLine = (options) => {
+  const names = ["defineConfig"];
+  if (options.hasFonts) {
+    names.push("fontProviders");
+  }
+  if (options.hasSession) {
+    names.push("sessionDrivers");
+  }
+  return `import { ${names.join(", ")} } from "astro/config";`;
+};
 var runtimeDependencies = (options) => {
   const { config, needsReact, needsSvelte, needsVue } = options;
   const deps = ["@astrojs/mdx"];
@@ -3444,7 +3467,7 @@ var runtimeDependencies = (options) => {
     deps.push("@scalar/astro");
   }
   deps.push(...searchProviderMeta(config.search.provider).runtimeDeps);
-  if (config.ai.ask?.enabled) {
+  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
     const askDep = askBackendRuntimeDep(config.ai.ask);
     if (askDep) {
       deps.push(askDep);
@@ -3487,6 +3510,29 @@ var devWatchOption = (outDir, contentWatchesRuntimeDir) => contentWatchesRuntime
       watch: {
         ignored: ${JSON.stringify([join8(outDir, ".astro", "**")])},
       },` : "";
+var renderIntegrationBridge = (bridge) => {
+  if (!bridge) {
+    return {
+      configSourceMarker: "",
+      userConfigImports: "",
+      userConfigSetup: "",
+      userIntegrationSpread: ""
+    };
+  }
+  return {
+    configSourceMarker: bridge.sourceHash ? `// Blume config source SHA-256: ${bridge.sourceHash}
+` : "",
+    userConfigImports: `import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createModuleLoader } from "blume/core/load-module.ts";
+`,
+    userConfigSetup: `const loadBlumeConfig = createModuleLoader();
+const blumeConfig = await loadBlumeConfig(resolve(dirname(fileURLToPath(import.meta.url)), ${JSON.stringify(bridge.configFile)}));
+
+`,
+    userIntegrationSpread: ", ...(blumeConfig?.integrations ?? [])"
+  };
+};
 var astroConfigTemplate = (options) => {
   const { context, config, needsReact, pages, dataPath, themePath } = options;
   const {
@@ -3517,6 +3563,7 @@ var astroConfigTemplate = (options) => {
   const adapterExpr = deployment.adapter === "vercel" ? `withAdapterRoot(adapter(${adapterArgs}), ${JSON.stringify(adapterRoot(context))})` : `adapter(${adapterArgs})`;
   const adapterOption = server && deployment.adapter ? `
   adapter: ${adapterExpr},` : "";
+  const sessionOption = resolveSessionOption(deployment);
   const siteOption = deployment.site ? `
   site: ${JSON.stringify(deployment.site)},` : "";
   const baseOption = deployment.base ? `
@@ -3538,7 +3585,10 @@ var astroConfigTemplate = (options) => {
   const fontEntries = buildFontEntries(config.theme.fonts);
   const fontsOption = fontEntries.length ? `
   fonts: [${fontEntries.map((font) => `{ provider: fontProviders.google(), name: ${JSON.stringify(font.name)}, cssVariable: ${JSON.stringify(font.cssVariable)}, weights: ${JSON.stringify(font.weights)}, fallbacks: ${JSON.stringify(font.fallbacks)} }`).join(", ")}],` : "";
-  const defineConfigImport = fontEntries.length ? `import { defineConfig, fontProviders } from "astro/config";` : `import { defineConfig } from "astro/config";`;
+  const defineConfigImport = astroConfigImportLine({
+    hasFonts: fontEntries.length > 0,
+    hasSession: sessionOption.length > 0
+  });
   const reactImport = needsReact ? `import react from "@astrojs/react";
 ` : "";
   const vueImport = needsVue ? `import vue from "@astrojs/vue";
@@ -3574,19 +3624,25 @@ var astroConfigTemplate = (options) => {
   }
   integrations.push(`blumeIntegration(${JSON.stringify({ base: deployment.base, contentRoutes, pages })})`);
   const watchOption = devWatchOption(context.outDir, options.contentWatchesRuntimeDir);
+  const {
+    configSourceMarker,
+    userConfigImports,
+    userConfigSetup,
+    userIntegrationSpread
+  } = renderIntegrationBridge(options.integrationBridge);
   return `// Generated by Blume. Do not edit; this file is recreated on each run.
-${defineConfigImport}
+${configSourceMarker}${userConfigImports}${defineConfigImport}
 import mdx from "@astrojs/mdx";
 import tailwindcss from "@tailwindcss/vite";
 import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers, blumeTwoslashTransformer } from "blume/markdown";
 ${reactImport}${vueImport}${svelteImport}${blumeImport}${adapterImport}
-export default defineConfig({
+${userConfigSetup}export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
   outDir: ${JSON.stringify(astroOutDir(context))},
   publicDir: ${JSON.stringify(`${context.root}/public`)},
-  output: ${JSON.stringify(deployment.output)},${adapterOption}${siteOption}${baseOption}${redirectsOption}${i18nOption}${fontsOption}
-  integrations: [${integrations.join(", ")}],
+  output: ${JSON.stringify(deployment.output)},${adapterOption}${sessionOption}${siteOption}${baseOption}${redirectsOption}${i18nOption}${fontsOption}
+  integrations: [${integrations.join(", ")}${userIntegrationSpread}],
   markdown: {
     processor: blumeMarkdownProcessor(${JSON.stringify({
     basePath: config.basePath,
@@ -3606,18 +3662,25 @@ export default defineConfig({
   devToolbar: { enabled: false },
   vite: {
     plugins: [tailwindcss(), prerenderDepsPlugin(), serverAppResolvePlugin()],
-    // Mermaid (lazy-loaded client-side for diagrams) statically imports dayjs as
-    // CJS (\`dayjs/dayjs.min.js\`). In dev, an un-pre-bundled dependency is served
-    // as raw ESM, and that UMD file exposes no \`default\` export, so mermaid
-    // throws on load and diagrams render blank. Forcing mermaid through the dep
-    // optimizer bundles dayjs with correct CJS interop. In a standalone install
-    // Blume's dynamic \`import("mermaid")\` lives inside \`node_modules/blume\`,
-    // which Vite's optimizer scan doesn't crawl, so mermaid is never discovered
-    // on its own — hence the explicit include. mermaid resolves through the
-    // \`blume\` package (it isn't a direct dep of the generated project), so the
-    // nested \`blume > mermaid\` form is required. Production (Rollup) already
-    // handles the interop, so this only affects dev.
-    optimizeDeps: { include: ["blume > mermaid"] },
+    // The lazy client-side imports both land on CJS/UMD files: mermaid (for
+    // diagrams) statically imports dayjs as CJS (\`dayjs/dayjs.min.js\`), and
+    // epub-gen-memory's browser bundle is a browserified UMD. In dev, an
+    // un-pre-bundled dependency is served as raw ESM, where such a file
+    // exposes no \`default\` export — mermaid throws on load and diagrams
+    // render blank, and the EPUB export throws \`epub is not a function\`
+    // (the UMD finds no \`exports\`/\`define\` and strands its callable on
+    // \`window.epubGen\` instead). Forcing them through the dep optimizer
+    // restores the CJS interop. In a standalone install these dynamic imports
+    // live inside \`node_modules/blume\`, which Vite's optimizer scan doesn't
+    // crawl, so neither is discovered on its own — hence the explicit
+    // includes. They resolve through the \`blume\` package (they aren't direct
+    // deps of the generated project), so the nested \`blume > x\` form is
+    // required, and epub-gen-memory must name the \`/bundle\` subpath that is
+    // actually imported: optimizing the package root leaves that entry out.
+    // Production (Rollup) already handles the interop, so this only affects dev.
+    optimizeDeps: {
+      include: ["blume > mermaid", "blume > epub-gen-memory/bundle"],
+    },
     // 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
@@ -3811,7 +3874,11 @@ import data from "blume:data";
 const { strings } = Astro.props;
 ---
 
-<AskAI strings={strings ?? data.ui.ask} suggestions={data.config.ask?.suggestions ?? []} />
+<AskAI
+  endpoint={data.config.ask?.endpoint ?? undefined}
+  strings={strings ?? data.ui.ask}
+  suggestions={data.config.ask?.suggestions ?? []}
+/>
 ` : `---
 // Generated by Blume. Do not edit.
 // Ask AI is off (\`ai.ask.enabled\`), so the header's Ask trigger renders nothing.
@@ -4093,6 +4160,7 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
   favicon={data.config.favicon}
   appleIcon={data.config.appleIcon}
   navigation={data.navigation}
+  noindex={${options.noindex === true}}
   pageTitle={${JSON.stringify(options.title)}}
   route={${JSON.stringify(options.route)}}
   searchEnabled={data.config.search.enabled}
@@ -7514,6 +7582,9 @@ var searchMetaSchema = z2.strictObject({
   exclude: z2.boolean().default(false),
   tags: z2.array(z2.string()).optional()
 });
+var aiMetaSchema = z2.strictObject({
+  exclude: z2.boolean().default(false)
+});
 var changelogMetaSchema = z2.strictObject({
   category: z2.string().optional(),
   date: dateSchema.optional(),
@@ -7529,6 +7600,7 @@ var authorSchema = z2.union([
   }).catchall(z2.unknown())
 ]);
 var pageMetaBaseSchema = z2.strictObject({
+  ai: aiMetaSchema.default({}),
   authors: z2.union([authorSchema, z2.array(authorSchema)]).optional(),
   changelog: changelogMetaSchema.optional(),
   date: dateSchema.optional(),
@@ -7662,6 +7734,7 @@ var contentConfigSchema = z2.strictObject({
   sources: z2.array(contentSourceSchema).optional()
 });
 var navTabSchema = z2.strictObject({
+  href: z2.string().min(1).optional(),
   icon: iconName.optional(),
   items: z2.array(z2.strictObject({
     description: z2.string().optional(),
@@ -7806,11 +7879,25 @@ var mcpConfigSchema = z2.strictObject({
   name: z2.string().optional(),
   route: z2.string().default("/mcp").transform(normalizeRoute)
 });
+var askEndpointSchema = z2.string().trim().min(1).refine((value) => {
+  if (value.startsWith("/") && !value.startsWith("//")) {
+    return true;
+  }
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}, {
+  message: "ai.ask.endpoint must be an HTTP(S) URL or a root-relative path."
+});
 var aiConfigSchema = z2.strictObject({
   ask: z2.strictObject({
     apiKeyEnv: z2.string().optional(),
     baseUrl: z2.string().url().optional(),
     enabled: z2.boolean().default(false),
+    endpoint: askEndpointSchema.optional(),
     model: z2.string().default("openai/gpt-5.5"),
     provider: z2.enum(askAiProviders).default("gateway"),
     suggestions: z2.array(z2.strictObject({
@@ -7818,7 +7905,7 @@ var aiConfigSchema = z2.strictObject({
       label: z2.string().min(1)
     })).default([])
   }).superRefine((value, ctx) => {
-    if (value.provider === "openai-compatible" && !value.baseUrl) {
+    if (value.provider === "openai-compatible" && !(value.baseUrl || value.endpoint)) {
       ctx.addIssue({
         code: z2.ZodIssueCode.custom,
         message: 'ai.ask.baseUrl is required when provider is "openai-compatible".',
@@ -8046,7 +8133,10 @@ var reactConfigSchema = z2.strictObject({
   compiler: z2.boolean().default(true)
 });
 var openapiSourceSchema = z2.strictObject({
+  includeInLlms: z2.boolean().default(true),
+  includeInSearch: z2.boolean().default(true),
   label: z2.string().optional(),
+  noindex: z2.boolean().default(false),
   route: z2.string().optional(),
   spec: z2.string()
 });
@@ -8119,6 +8209,7 @@ var blumeConfigSchema = z2.strictObject({
   frontmatter: frontmatterConfigSchema.default({}),
   github: githubConfigSchema.optional(),
   i18n: i18nConfigSchema.optional(),
+  integrations: z2.array(z2.custom()).default([]),
   lastModified: lastModifiedConfigSchema.default(false),
   logo: logoConfigSchema.optional(),
   markdown: markdownConfigSchema.default({}),
@@ -8794,7 +8885,7 @@ var resolveTabHref = (sidebar, path) => {
   return walk(sidebar) ? path : first ?? path;
 };
 var withTabHrefs = (tabs, sidebar) => tabs.map((tab) => {
-  const href = resolveTabHref(sidebar, tab.path);
+  const href = tab.href ?? resolveTabHref(sidebar, tab.path);
   return href === tab.path ? tab : { ...tab, href };
 });
 var buildNavigation = (pages, options) => {
@@ -8816,6 +8907,7 @@ var buildNavigation = (pages, options) => {
   })) : options.selectors ?? [];
   const tabs = basePath ? (options.tabs ?? []).map((tab) => ({
     ...tab,
+    ...tab.href ? { href: withBasePath(basePath, tab.href) } : {},
     items: tab.items?.map(rebasePath),
     path: withBasePath(basePath, tab.path)
   })) : options.tabs ?? [];
@@ -8894,6 +8986,7 @@ var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n
   const localizePath = (path) => path.startsWith("/") ? localizeRoute(path, code, i18n) : path;
   const tabs = options.navigation.tabs?.map((tab) => ({
     ...tab,
+    ...tab.href ? { href: localizePath(tab.href) } : {},
     items: tab.items?.map((item) => ({
       ...item,
       path: localizePath(item.path)
@@ -9918,23 +10011,30 @@ var operationDescription = (spec, operation) => {
 var withDescription = (description, component) => description.trim() ? `${mdxSafe(description.trim())}
 
 ${component}` : component;
-var operationMdx = (spec, operation) => {
+var operationMdx = (spec, operation, reference) => {
   const method = operation.method.toUpperCase();
   const title = operation.summary || `${method} ${operation.path}`;
   const description = operation.description.trim() === operation.summary.trim() ? "" : operation.description;
   return {
     body: withDescription(description, `<Operation source="${spec.slug}" id="${operation.key}" />`),
     data: {
+      ...reference?.includeInLlms === false ? { ai: { exclude: true } } : {},
       ...operation.deprecated ? { deprecated: true } : {},
-      search: { tags: [operation.tag, method] },
-      seo: { description: operationDescription(spec, operation) },
+      search: {
+        ...reference?.includeInSearch === false ? { exclude: true } : {},
+        tags: [operation.tag, method]
+      },
+      seo: {
+        description: operationDescription(spec, operation),
+        ...reference?.noindex ? { noindex: true } : {}
+      },
       sidebar: { badge: method, label: operation.summary || operation.path },
       title,
       type: "openapi-operation"
     }
   };
 };
-var overviewMdx = (spec) => {
+var overviewMdx = (spec, reference) => {
   const operations = Object.values(spec.operations);
   const sections = [];
   const known = new Set;
@@ -9976,8 +10076,11 @@ var overviewMdx = (spec) => {
 
 `),
     data: {
+      ...reference?.includeInLlms === false ? { ai: { exclude: true } } : {},
+      ...reference?.includeInSearch === false ? { search: { exclude: true } } : {},
       seo: {
-        description: clip(plainProse(spec.description), META_DESCRIPTION_MAX) || `${apiName(spec)} API reference.`
+        description: clip(plainProse(spec.description), META_DESCRIPTION_MAX) || `${apiName(spec)} API reference.`,
+        ...reference?.noindex ? { noindex: true } : {}
       },
       sidebar: { label: "Overview" },
       title: apiName(spec)
@@ -9999,10 +10102,10 @@ var toEntry = (rendered, ref) => {
     ref
   };
 };
-var specEntries = (spec, operations) => {
-  const entries = operations.map((operation) => toEntry(operationMdx(spec, operation), `${routeToRef(operation.route)}.mdx`));
+var specEntries = (spec, operations, reference) => {
+  const entries = operations.map((operation) => toEntry(operationMdx(spec, operation, reference), `${routeToRef(operation.route)}.mdx`));
   const base = routeToRef(spec.route);
-  entries.push(toEntry(overviewMdx(spec), base ? `${base}/index.mdx` : "index.mdx"));
+  entries.push(toEntry(overviewMdx(spec, reference), base ? `${base}/index.mdx` : "index.mdx"));
   return entries;
 };
 var openApiSource = (references, ctx) => {
@@ -10056,7 +10159,7 @@ var openApiSource = (references, ctx) => {
             }
           ] : []
         ],
-        entries: specEntries(spec, operations),
+        entries: specEntries(spec, operations, reference),
         slug: reference.slug,
         spec
       };
@@ -11579,6 +11682,12 @@ var usagePolicy = (signals) => {
   }
   return Object.fromEntries(USAGE_TOKENS.map(([key, token]) => [token, signals[key]]));
 };
+var askApiUrl = (endpoint, site, abs) => {
+  if (!endpoint) {
+    return abs("/api/ask");
+  }
+  return site && endpoint.startsWith("/") ? `${site.replace(/\/+$/u, "")}${endpoint}` : endpoint;
+};
 var buildAgentReadability = (project) => {
   const { config } = project;
   if (!config.seo.agentReadability) {
@@ -11607,7 +11716,7 @@ var buildAgentReadability = (project) => {
     };
   }
   if (config.ai.ask?.enabled) {
-    artifacts.askApi = abs("/api/ask");
+    artifacts.askApi = askApiUrl(config.ai.ask.endpoint, site, abs);
   }
   if (site && config.seo.sitemap) {
     artifacts.sitemap = abs("/sitemap.xml");
@@ -11950,7 +12059,7 @@ var pageUrl = (route, site, base = "") => {
   const path = withBasePath(base, route);
   return encodeURI(site ? `${site.replace(/\/$/u, "")}${path}` : path);
 };
-var eligiblePages = (project) => project.graph.pages.filter((page) => !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex) && (project.config.ai.llmsTxt.openapi || page.source.name !== "openapi"));
+var eligiblePages = (project) => project.graph.pages.filter((page) => !(page.meta.ai.exclude || page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex && page.source.name !== "openapi") && (project.config.ai.llmsTxt.openapi || page.source.name !== "openapi"));
 var indexedNavigations = (project) => {
   const { i18n } = project.config;
   if (i18n) {
@@ -12099,7 +12208,7 @@ var ensureGitignore = async (root, entries) => {
 // src/core/server-features.ts
 var serverFeatures = (config) => {
   const features = [];
-  if (config.ai.ask?.enabled) {
+  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
     features.push("Ask AI");
   }
   if (config.ai.mcp.enabled) {
@@ -12649,6 +12758,7 @@ var refuseIfDevRunning = (root, action, options = {}) => {
 };
 
 // src/astro/generate.ts
+import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync14, readFileSync as readFileSync9, realpathSync } from "node:fs";
 import {
   lstat,
@@ -13475,6 +13585,7 @@ var buildReferenceFiles = async (options) => {
           ...ref.scalar
         },
         dataImport: `${"../".repeat(depth + 1)}generated/data.json`,
+        noindex: ref.noindex,
         route: ref.route,
         title: ref.label
       }),
@@ -14765,6 +14876,16 @@ var detectUsesMath = async (root, staged = []) => {
   const contents = await Promise.all(files.map((file) => readOptional(join26(root, file))));
   return [...contents, ...staged].some(containsMath);
 };
+var hashConfigSource = (source) => createHash2("sha256").update(source).digest("hex");
+var loadIntegrationBridge = async (config, context) => {
+  if (config.integrations.length === 0 || !context.configFile) {
+    return;
+  }
+  return {
+    configFile: relative13(context.outDir, context.configFile),
+    sourceHash: hashConfigSource(await readOptional(context.configFile))
+  };
+};
 var writeIfChanged = async (path, content) => {
   let existing = null;
   try {
@@ -14983,7 +15104,10 @@ var buildRuntimeData = (project) => {
     config: {
       analytics: config.analytics ?? null,
       appleIcon: resolveAppleIcon(project),
-      ask: config.ai.ask?.enabled ? { suggestions: config.ai.ask.suggestions } : null,
+      ask: config.ai.ask?.enabled ? {
+        endpoint: config.ai.ask.endpoint ?? null,
+        suggestions: config.ai.ask.suggestions
+      } : null,
       banner: resolveBanner(config),
       basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
@@ -15115,7 +15239,7 @@ var writeMcpFiles = async (project, plan, write) => {
 };
 var writeAskFiles = async (project, srcDir, write) => {
   const { ask } = project.config.ai;
-  if (!ask?.enabled) {
+  if (!(ask?.enabled && !ask.endpoint)) {
     return;
   }
   const grounded = ask.provider !== "inkeep";
@@ -15168,6 +15292,7 @@ var generateRuntime = async (project) => {
     usesMath,
     userTheme,
     userExamplesCss,
+    integrationBridge,
     islandDiscovery,
     exampleDiscovery,
     componentSlots
@@ -15177,6 +15302,7 @@ var generateRuntime = async (project) => {
     detectUsesMath(context.root, staged.values()),
     readOptional(context.themeFile),
     readOptional(examplesCssFile(context.root, config)),
+    loadIntegrationBridge(config, context),
     discoverIslands(context.root),
     discoverExamples(context.root, config.examples.source),
     buildComponentSlots(context.componentsFile)
@@ -15214,6 +15340,7 @@ var generateRuntime = async (project) => {
         dataPath,
         examplesPath,
         examplesThemePath,
+        integrationBridge,
         needsReact,
         needsSvelte,
         needsVue,
@@ -15439,7 +15566,7 @@ var checkRequiredSecrets = (config) => {
       suggestion: `Set ${env} in .env.local for local dev, or in your host's environment for production.`
     });
   };
-  if (config.ai.ask?.enabled) {
+  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
     const backend = resolveAskBackend(config.ai.ask);
     if (backend.kind === "gateway") {
       requireSecret("Ask AI (AI Gateway)", "AI_GATEWAY_API_KEY", "on Vercel the gateway can also authenticate via OIDC");
@@ -16196,7 +16323,15 @@ var ejectOpenApiData = (project) => {
 };
 var askFiles = async (project, srcDir, genDir) => {
   const { ask } = project.config.ai;
-  if (!ask?.enabled) {
+  if (!(ask?.enabled && !ask.endpoint)) {
+    const endpointPath = join31(srcDir, "pages", "api", "ask.ts");
+    if (existsSync18(endpointPath)) {
+      const content = await readFile15(endpointPath, "utf-8");
+      if (content.startsWith("// Generated by Blume. Do not edit.")) {
+        await rm3(endpointPath, { force: true });
+      }
+    }
+    await rm3(join31(genDir, "ask-data.json"), { force: true });
     return [];
   }
   const grounded = ask.provider !== "inkeep";
@@ -16279,6 +16414,7 @@ var examplesPreviewFiles = (srcDir, basePath, hasExamples) => hasExamples ? [
     path: join31(srcDir, "pages", ...basePath.split("/").filter(Boolean), "blume-examples", "[...path].astro")
   }
 ] : [];
+var ejectIntegrationBridge = (config, root, configFile) => config.integrations.length > 0 && configFile ? { configFile: toPosix(relative14(root, configFile)) } : undefined;
 var eject = async (root) => {
   const project = await scanProject(root, { mode: "build" });
   const { context, config } = project;
@@ -16340,6 +16476,7 @@ var eject = async (root) => {
         dataPath: "./src/generated/data.json",
         examplesPath: "./src/generated/examples.ts",
         examplesThemePath: "./src/generated/examples.css",
+        integrationBridge: ejectIntegrationBridge(config, root, context.configFile),
         needsReact,
         needsSvelte,
         needsVue,
@@ -16890,9 +17027,878 @@ The blume package remains importable.`);
   }
 });
 
+// src/cli/commands/eval.ts
+import { existsSync as existsSync20 } from "node:fs";
+import { defineCommand as defineCommand8 } from "citty";
+import { join as join37 } from "pathe";
+
+// src/eval/prompts.ts
+var readerPrompt = (question) => `You are evaluating whether a product's documentation can answer a user's question.
+
+Answer the question below using ONLY the connected documentation tools (search_docs, get_page, list_pages, get_navigation). Rules:
+- Do not use prior knowledge about the product. Do not guess.
+- Do not read files, run commands, or access the network.
+- Search first, then read the most relevant pages with get_page.
+- If the documentation does not contain the answer, say exactly what information is missing instead of inventing one.
+
+Question: ${question.question}
+
+Reply with a concise answer containing the specific facts the documentation provides. Plain text only.`;
+var judgePrompt = (question, answer) => {
+  const facts = question.expected.map((fact) => `- ${fact}`).join(`
+`);
+  return `You are grading an answer against expected facts. Do not use any tools.
+
+Question: ${question.question}
+
+Expected facts — each must be present in substance (paraphrase is fine, contradiction is not):
+${facts}
+
+Answer to grade:
+"""
+${answer}
+"""
+
+An answer that states the documentation lacks the information FAILS.
+
+Reply with ONLY this JSON object on a single line, no markdown fences:
+{"pass": true|false, "score": 0.0-1.0, "missing": ["expected facts absent or contradicted"], "notes": "one sentence"}`;
+};
+var evalFixPrompt = (reportPath) => `Fix the documentation gaps found by \`blume eval\` in this project.
+
+The full report is at ${reportPath}. It is JSON: each entry in \`eval.results\` with status "fail" is one question the documentation could not answer. Each carries the \`question\`, the \`expected\` facts, the judge's \`missing\` facts, and the reader agent's \`answer\` (what the docs currently convey). The matching \`diagnostics\` entry names the source \`file\` of the page that should answer it.
+
+Work through every failed question:
+1. Read the page named in the finding (or choose the best page when none is named).
+2. Edit the documentation so it states the missing facts explicitly. Add prose, not filler; keep the page's voice.
+3. Never delete questions from the evals file or weaken expected facts.
+
+When you are done, run \`blume eval\` to verify, and repeat until every question passes.`;
+var initPrompt = (evalsPath) => `Draft a starter evals file for \`blume eval\` in this documentation project.
+
+Read the documentation source pages in this project and write ${evalsPath} with about 10 high-value questions a real user would ask — installation, configuration, deployment, and the project's headline features. For each question, list the expected facts a correct answer must state, grounded in what the documentation actually promises (never invent facts the docs don't state).
+
+The file format is YAML:
+
+questions:
+  - id: kebab-case-slug
+    question: One user question?
+    expected:
+      - a fact the answer must contain
+      - another required fact
+    routes:
+      - /route/of/the/page/that/answers/it
+
+Rules:
+- Every \`expected\` fact must be verifiable in the docs today.
+- Prefer questions whose answers live on one page; set \`routes\` to that page.
+- Keep ids unique and questions short.
+
+When you are done, print the file and suggest running \`blume eval\` to try it.`;
+
+// src/eval/report.ts
+import { mkdtemp as mkdtemp2, writeFile as writeFile12 } from "node:fs/promises";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join34, relative as relative17 } from "pathe";
+var ESC4 = String.fromCodePoint(27);
+var COLORS3 = {
+  bold: `${ESC4}[1m`,
+  cyan: `${ESC4}[36m`,
+  dim: `${ESC4}[2m`,
+  green: `${ESC4}[32m`,
+  red: `${ESC4}[31m`,
+  reset: `${ESC4}[0m`,
+  yellow: `${ESC4}[33m`
+};
+var GLYPH2 = {
+  error: "!",
+  fail: "✖",
+  pass: "✔",
+  skip: "⊘"
+};
+var STATUS_COLOR = {
+  error: COLORS3.yellow,
+  fail: COLORS3.red,
+  pass: COLORS3.green,
+  skip: COLORS3.dim
+};
+var ID_PAD = 28;
+var seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+var money = (cost) => cost === undefined ? "" : `$${cost.toFixed(2)}`;
+var duration = (ms) => {
+  if (ms < 60000) {
+    return seconds(ms);
+  }
+  const minutes = Math.floor(ms / 60000);
+  const rest = Math.round(ms % 60000 / 1000);
+  return `${minutes}m ${rest}s`;
+};
+var questionLine = (result) => {
+  const color = STATUS_COLOR[result.status];
+  const glyph = `${color}${GLYPH2[result.status]}${COLORS3.reset}`;
+  const id2 = result.id.padEnd(ID_PAD);
+  if (result.status === "skip") {
+    return `  ${glyph} ${id2} ${COLORS3.dim}skipped${COLORS3.reset}`;
+  }
+  const score = result.score === undefined ? "" : result.score.toFixed(2);
+  const cells = [
+    `${color}${result.status}${COLORS3.reset}`,
+    score,
+    `${COLORS3.dim}${seconds(result.durationMs)}${COLORS3.reset}`,
+    `${COLORS3.dim}${money(result.costUsd)}${COLORS3.reset}`
+  ].filter((cell) => cell !== "").join("  ");
+  return `  ${glyph} ${id2} ${cells}`;
+};
+var questionDetails = (result, verbose) => {
+  const lines = [];
+  if (result.status === "fail") {
+    for (const fact of result.missing) {
+      lines.push(`      ${COLORS3.dim}missing: ${fact}${COLORS3.reset}`);
+    }
+  }
+  if (result.status === "error" && result.detail) {
+    lines.push(`      ${COLORS3.dim}${result.detail}${COLORS3.reset}`);
+  }
+  if (verbose && result.answer && result.status !== "pass") {
+    lines.push(...result.answer.split(`
+`).map((line) => `      ${COLORS3.dim}> ${line}${COLORS3.reset}`));
+  }
+  return lines;
+};
+var summaryLine2 = (result) => {
+  const { counts } = result;
+  const parts = [
+    `${counts.pass} passed`,
+    counts.fail > 0 ? `${counts.fail} failed` : "",
+    counts.error > 0 ? `${counts.error} errored` : "",
+    counts.skip > 0 ? `${counts.skip} skipped` : "",
+    duration(result.durationMs),
+    money(result.costUsd)
+  ].filter((part) => part !== "");
+  return parts.join(" · ");
+};
+var headerLine = (total, agent) => `${COLORS3.bold}blume eval${COLORS3.reset}  ${total} question(s) · ${AGENTS[agent].name}`;
+var startLine = (id2, index, total) => `  ${COLORS3.dim}▸ ${id2} (${index + 1}/${total})${COLORS3.reset}`;
+var fixLines = (result, root) => result.diagnostics.filter((diagnostic) => diagnostic.code !== "BLUME_EVAL_ROUTE_UNKNOWN").map((finding2) => {
+  const site = finding2.file ? `${relative17(root, finding2.file)}${finding2.line ? `:${finding2.line}` : ""}` : "";
+  return `  ${COLORS3.cyan}fix:${COLORS3.reset} ${site} ${COLORS3.dim}${finding2.message}${COLORS3.reset}`;
+});
+var warningLines = (result, root) => result.diagnostics.filter((diagnostic) => diagnostic.code === "BLUME_EVAL_ROUTE_UNKNOWN").map((finding2) => {
+  const site = finding2.file ? ` ${relative17(root, finding2.file)}${finding2.line ? `:${finding2.line}` : ""}` : "";
+  return `  ${COLORS3.yellow}⚠${COLORS3.reset}${site} ${COLORS3.dim}${finding2.message}${COLORS3.reset}`;
+});
+var evalReportJson = (result, root, threshold) => {
+  const diagnostics = result.diagnostics.map((diagnostic) => diagnostic.file ? { ...diagnostic, file: relative17(root, diagnostic.file) } : diagnostic);
+  return `${JSON.stringify({
+    diagnostics,
+    eval: {
+      agent: result.agent,
+      costUsd: result.costUsd,
+      counts: result.counts,
+      durationMs: result.durationMs,
+      results: result.results,
+      threshold
+    },
+    summary: countBySeverity(result.diagnostics)
+  }, null, 2)}
+`;
+};
+var writeEvalReport = async (result, root, threshold) => {
+  const dir = await mkdtemp2(join34(tmpdir2(), "blume-eval-"));
+  const path = join34(dir, "report.json");
+  await writeFile12(path, evalReportJson(result, root, threshold));
+  return path;
+};
+
+// src/eval/run.ts
+import { mkdir as mkdir9, mkdtemp as mkdtemp3, writeFile as writeFile14 } from "node:fs/promises";
+import { tmpdir as tmpdir3 } from "node:os";
+import { join as join36 } from "pathe";
+
+// src/eval/agents.ts
+import { spawn as spawn2 } from "node:child_process";
+import { readFile as readFile17, writeFile as writeFile13 } from "node:fs/promises";
+import { join as join35 } from "pathe";
+import { z as z3 } from "zod";
+var KILL_GRACE_MS = 5000;
+var MCP_TOOL_NAMES = [
+  "search_docs",
+  "get_page",
+  "list_pages",
+  "get_navigation"
+];
+var MCP_SERVER_NAME = "docs";
+var DISALLOWED_TOOLS = [
+  "Bash",
+  "Read",
+  "Glob",
+  "Grep",
+  "Write",
+  "Edit",
+  "NotebookEdit",
+  "WebFetch",
+  "WebSearch",
+  "Task"
+];
+var runAgentHeadless = (bin, args, options) => new Promise((resolve9, reject) => {
+  const platform = options.platform ?? process.platform;
+  const child = spawn2(bin, args, {
+    cwd: options.cwd,
+    shell: platform === "win32",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  let stdout = "";
+  let stderr = "";
+  let timedOut = false;
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk.toString("utf-8");
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString("utf-8");
+  });
+  const deadline = setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGTERM");
+    const hardKill = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS);
+    hardKill.unref();
+  }, options.timeoutMs);
+  deadline.unref();
+  child.once("error", (error) => {
+    clearTimeout(deadline);
+    reject(error);
+  });
+  child.once("close", (code) => {
+    clearTimeout(deadline);
+    resolve9({ code: code ?? 1, stderr, stdout, timedOut });
+  });
+  child.once("exit", (code) => {
+    if (timedOut) {
+      clearTimeout(deadline);
+      resolve9({ code: code ?? 1, stderr, stdout, timedOut });
+    }
+  });
+  child.stdin.end(options.prompt);
+});
+var writeMcpConfig = async (dir, snapshotPath, launcher) => {
+  const resolved = launcher ?? {
+    args: [process.argv[1] ?? "", "mcp-stdio", "--data", snapshotPath],
+    command: process.execPath
+  };
+  const configPath = join35(dir, "mcp-config.json");
+  const config = {
+    mcpServers: {
+      [MCP_SERVER_NAME]: { args: resolved.args, command: resolved.command }
+    }
+  };
+  await writeFile13(configPath, JSON.stringify(config, null, 2));
+  return {
+    configPath,
+    serverArgs: resolved.args,
+    serverCommand: resolved.command
+  };
+};
+var CLAUDE_READER_MAX_TURNS = "25";
+var CLAUDE_JUDGE_MAX_TURNS = "1";
+var claudeArgs = (context) => {
+  const base = ["-p", "--output-format", "json", "--strict-mcp-config"];
+  if (context.mcp) {
+    const allowed = MCP_TOOL_NAMES.map((tool) => `mcp__${MCP_SERVER_NAME}__${tool}`).join(",");
+    return [
+      ...base,
+      "--mcp-config",
+      context.mcp.configPath,
+      "--allowedTools",
+      allowed,
+      "--disallowedTools",
+      DISALLOWED_TOOLS.join(","),
+      "--max-turns",
+      CLAUDE_READER_MAX_TURNS
+    ];
+  }
+  return [
+    ...base,
+    "--disallowedTools",
+    DISALLOWED_TOOLS.join(","),
+    "--max-turns",
+    CLAUDE_JUDGE_MAX_TURNS
+  ];
+};
+var codexArgs = (context) => {
+  const base = [
+    "exec",
+    "--skip-git-repo-check",
+    "--ignore-user-config",
+    "--ephemeral",
+    "--sandbox",
+    "read-only",
+    "--output-last-message",
+    context.lastMessagePath
+  ];
+  if (context.mcp) {
+    return [
+      ...base,
+      "-c",
+      `mcp_servers.${MCP_SERVER_NAME}.command=${JSON.stringify(context.mcp.serverCommand)}`,
+      "-c",
+      `mcp_servers.${MCP_SERVER_NAME}.args=${JSON.stringify(context.mcp.serverArgs)}`,
+      "-"
+    ];
+  }
+  return [...base, "-"];
+};
+var agentArgs = (kind, context) => kind === "claude" ? claudeArgs(context) : codexArgs(context);
+var claudeResultSchema = z3.object({
+  is_error: z3.boolean().default(false),
+  result: z3.string().default(""),
+  total_cost_usd: z3.number().optional()
+});
+var tail = (value, max = 300) => {
+  const trimmed = value.trim();
+  return trimmed.length > max ? trimmed.slice(-max) : trimmed;
+};
+var readAgentOutput = async (kind, result, lastMessagePath) => {
+  if (result.timedOut) {
+    return { detail: "timed out", isError: true, text: "" };
+  }
+  if (result.code !== 0) {
+    return {
+      detail: tail(result.stderr) || `exited with code ${result.code}`,
+      isError: true,
+      text: ""
+    };
+  }
+  if (kind === "claude") {
+    let parsed;
+    try {
+      parsed = JSON.parse(result.stdout);
+    } catch {
+      return {
+        detail: "unparseable --output-format json payload",
+        isError: true,
+        text: ""
+      };
+    }
+    const payload = claudeResultSchema.safeParse(parsed);
+    if (!payload.success) {
+      return {
+        detail: "unexpected --output-format json shape",
+        isError: true,
+        text: ""
+      };
+    }
+    return {
+      costUsd: payload.data.total_cost_usd,
+      isError: payload.data.is_error,
+      text: payload.data.result
+    };
+  }
+  let text;
+  try {
+    const raw = await readFile17(lastMessagePath, "utf-8");
+    text = raw.trim();
+  } catch {
+    return { detail: "no last message written", isError: true, text: "" };
+  }
+  if (text === "") {
+    return { detail: "empty last message", isError: true, text: "" };
+  }
+  return { isError: false, text };
+};
+var verdictSchema = z3.object({
+  missing: z3.array(z3.string()).default([]),
+  notes: z3.string().default(""),
+  pass: z3.boolean(),
+  score: z3.number().min(0).max(1).optional()
+});
+var parseVerdict = (text) => {
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start === -1 || end <= start) {
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return;
+  }
+  const result = verdictSchema.safeParse(parsed);
+  return result.success ? result.data : undefined;
+};
+
+// src/eval/schema.ts
+import { readFile as readFile18 } from "node:fs/promises";
+import { load as load2 } from "js-yaml";
+import { z as z4 } from "zod";
+var ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
+var questionSchema = z4.strictObject({
+  expected: z4.array(z4.string().min(1)).min(1, "expected must list at least one fact"),
+  id: z4.string().regex(ID_PATTERN, "id must be a kebab-case slug (a-z, 0-9, dashes)"),
+  question: z4.string().min(1),
+  routes: z4.union([z4.string(), z4.array(z4.string())]).default([]).transform((value) => typeof value === "string" ? [value] : value),
+  severity: z4.enum(["error", "warning"]).default("error"),
+  skip: z4.boolean().default(false)
+});
+var fullSchema = z4.strictObject({
+  questions: z4.array(questionSchema).min(1),
+  version: z4.literal(1).default(1)
+});
+var evalsFileSchema = fullSchema.superRefine((value, context) => {
+  const seen = new Set;
+  for (const question of value.questions) {
+    if (seen.has(question.id)) {
+      context.addIssue({
+        code: z4.ZodIssueCode.custom,
+        message: `duplicate question id "${question.id}"`,
+        path: ["questions"]
+      });
+    }
+    seen.add(question.id);
+  }
+});
+
+class EvalsFileError extends Error {
+  path;
+  constructor(path, message) {
+    super(message);
+    this.name = "EvalsFileError";
+    this.path = path;
+  }
+}
+var describeIssues = (error) => error.issues.map((issue) => {
+  const at = issue.path.length > 0 ? ` at ${issue.path.join(".")}` : "";
+  return `${issue.message}${at}`;
+}).join("; ");
+var loadEvalsFile = async (path) => {
+  let raw;
+  try {
+    raw = await readFile18(path, "utf-8");
+  } catch {
+    throw new EvalsFileError(path, `No evals file found at ${path}. Run \`blume eval init\` to draft one.`);
+  }
+  let parsed;
+  try {
+    parsed = load2(raw);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new EvalsFileError(path, `Invalid YAML in ${path}: ${detail}`);
+  }
+  const candidate = Array.isArray(parsed) ? { questions: parsed } : parsed;
+  const result = evalsFileSchema.safeParse(candidate);
+  if (!result.success) {
+    throw new EvalsFileError(path, `Invalid evals file at ${path}: ${describeIssues(result.error)}`);
+  }
+  return { evals: result.data, raw };
+};
+var locateQuestion = (raw, id2) => {
+  const pattern = new RegExp(`^\\s*-?\\s*id:\\s*["']?${id2}["']?\\s*$`, "u");
+  const lines = raw.split(`
+`);
+  for (const [index, line] of lines.entries()) {
+    if (pattern.test(line)) {
+      return index + 1;
+    }
+  }
+  return;
+};
+
+// src/eval/findings.ts
+var DOCS_URL = "https://useblume.dev/docs/reference/eval";
+var hintedRoute = (question, project) => {
+  for (const hint of question.routes) {
+    const route = project.manifest.routes.find((candidate) => candidate.path === hint);
+    if (route) {
+      return route;
+    }
+  }
+};
+var routeFindings = (question, project, anchor) => {
+  const known = new Set(project.manifest.routes.map((route) => route.path));
+  return question.routes.filter((hint) => !known.has(hint)).map((hint) => ({
+    code: "BLUME_EVAL_ROUTE_UNKNOWN",
+    docsUrl: DOCS_URL,
+    file: anchor.path,
+    line: locateQuestion(anchor.raw, question.id),
+    message: `Question "${question.id}" hints at route "${hint}", which matches no page.`,
+    severity: "warning",
+    suggestion: "Update the question's `routes` to the page's current route, or remove the hint."
+  }));
+};
+var questionFinding = (question, outcome, project, anchor) => {
+  const route = hintedRoute(question, project);
+  const site = route ? { file: route.sourcePath, url: route.path } : { file: anchor.path, line: locateQuestion(anchor.raw, question.id) };
+  if (outcome.status === "error") {
+    return {
+      code: "BLUME_EVAL_QUESTION_ERROR",
+      docsUrl: DOCS_URL,
+      message: `Eval run failed for "${question.question}"${outcome.detail ? ` — ${outcome.detail}` : ""}.`,
+      severity: question.severity,
+      suggestion: "Rerun `blume eval`; if it persists, check the agent CLI installation and the failure detail.",
+      ...site
+    };
+  }
+  const missing = outcome.missing.length > 0 ? ` — missing: ${outcome.missing.join("; ")}` : "";
+  return {
+    code: "BLUME_EVAL_QUESTION_FAILED",
+    docsUrl: DOCS_URL,
+    message: `Docs could not answer: "${question.question}"${missing}`,
+    severity: question.severity,
+    suggestion: "State the missing facts on this page, then rerun `blume eval`.",
+    ...site
+  };
+};
+
+// src/eval/run.ts
+var DEFAULT_READER_TIMEOUT_MS = 180000;
+var DEFAULT_JUDGE_TIMEOUT_MS = 60000;
+var errored = (question, detail, durationMs) => ({
+  detail,
+  durationMs,
+  expected: question.expected,
+  id: question.id,
+  missing: [],
+  question: question.question,
+  routes: question.routes,
+  status: "error"
+});
+var runQuestion = async (question, index, context) => {
+  const started = performance.now();
+  const elapsed = () => Math.round(performance.now() - started);
+  const workDir = join36(context.dir, `work-${index}`);
+  await mkdir9(workDir, { recursive: true });
+  const answerPath = join36(workDir, "answer.txt");
+  const reader = await context.run(context.bin, agentArgs(context.kind, { lastMessagePath: answerPath, mcp: context.mcp }), {
+    cwd: workDir,
+    prompt: readerPrompt(question),
+    timeoutMs: context.readerTimeoutMs
+  });
+  const answer = await readAgentOutput(context.kind, reader, answerPath);
+  if (answer.isError) {
+    return {
+      ...errored(question, `reader ${answer.detail ?? "failed"}`, elapsed()),
+      costUsd: answer.costUsd
+    };
+  }
+  const verdictPath = join36(workDir, "verdict.txt");
+  const judge = await context.run(context.bin, agentArgs(context.kind, { lastMessagePath: verdictPath }), {
+    cwd: workDir,
+    prompt: judgePrompt(question, answer.text),
+    timeoutMs: context.judgeTimeoutMs
+  });
+  const graded = await readAgentOutput(context.kind, judge, verdictPath);
+  const costUsd = answer.costUsd === undefined && graded.costUsd === undefined ? undefined : (answer.costUsd ?? 0) + (graded.costUsd ?? 0);
+  if (graded.isError) {
+    return {
+      ...errored(question, `judge ${graded.detail ?? "failed"}`, elapsed()),
+      answer: answer.text,
+      costUsd
+    };
+  }
+  const verdict = parseVerdict(graded.text);
+  if (!verdict) {
+    return {
+      ...errored(question, "judge returned no parseable verdict", elapsed()),
+      answer: answer.text,
+      costUsd
+    };
+  }
+  return {
+    answer: answer.text,
+    costUsd,
+    durationMs: elapsed(),
+    expected: question.expected,
+    id: question.id,
+    missing: verdict.missing,
+    notes: verdict.notes || undefined,
+    question: question.question,
+    routes: question.routes,
+    score: verdict.score,
+    status: verdict.pass ? "pass" : "fail"
+  };
+};
+var runEval = async (options) => {
+  const started = performance.now();
+  const kind = options.agent;
+  const run = options.run ?? runAgentHeadless;
+  const anchor = { path: options.evalsPath, raw: options.rawEvals };
+  const dir = await mkdtemp3(join36(tmpdir3(), "blume-eval-"));
+  const snapshotPath = join36(dir, "mcp-data.json");
+  await writeFile14(snapshotPath, JSON.stringify(await buildMcpData(options.project)));
+  const mcp = await writeMcpConfig(dir, snapshotPath);
+  const context = {
+    bin: AGENTS[kind].bin,
+    dir,
+    judgeTimeoutMs: options.judgeTimeoutMs ?? DEFAULT_JUDGE_TIMEOUT_MS,
+    kind,
+    mcp,
+    readerTimeoutMs: options.readerTimeoutMs ?? DEFAULT_READER_TIMEOUT_MS,
+    run
+  };
+  const diagnostics = [];
+  const results = [];
+  const { questions } = options.evals;
+  for (const [index, question] of questions.entries()) {
+    diagnostics.push(...routeFindings(question, options.project, anchor));
+    if (question.skip) {
+      results.push({
+        durationMs: 0,
+        expected: question.expected,
+        id: question.id,
+        missing: [],
+        question: question.question,
+        routes: question.routes,
+        status: "skip"
+      });
+      continue;
+    }
+    options.onProgress?.({
+      id: question.id,
+      index,
+      kind: "question-start",
+      total: questions.length
+    });
+    const result = await runQuestion(question, index, context);
+    results.push(result);
+    if (result.status === "fail" || result.status === "error") {
+      diagnostics.push(questionFinding(question, {
+        detail: result.detail,
+        missing: result.missing,
+        status: result.status
+      }, options.project, anchor));
+    }
+    options.onProgress?.({
+      index,
+      kind: "question-end",
+      result,
+      total: questions.length
+    });
+  }
+  const counts = {
+    error: 0,
+    fail: 0,
+    pass: 0,
+    skip: 0
+  };
+  for (const result of results) {
+    counts[result.status] += 1;
+  }
+  const costs = results.flatMap((result) => result.costUsd === undefined ? [] : [result.costUsd]);
+  return {
+    agent: kind,
+    costUsd: costs.length > 0 ? costs.reduce((total, cost) => total + cost, 0) : undefined,
+    counts,
+    diagnostics,
+    durationMs: Math.round(performance.now() - started),
+    results
+  };
+};
+
+// src/cli/commands/eval.ts
+var DEFAULT_FILE = "evals.yaml";
+var DEFAULT_TIMEOUT_S = 180;
+var isAgentKind = (value) => (value in AGENTS);
+var launchAgentCode2 = async (bin, prompt) => {
+  try {
+    return await launchAgent(bin, prompt);
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+    return WINDOWS_COMMAND_NOT_FOUND;
+  }
+};
+var notInstalled = (agent) => {
+  const cli = AGENTS[agent];
+  logger.error(`${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`);
+  return process.exit(1);
+};
+var passFraction = (result) => {
+  const ran = result.results.length - result.counts.skip;
+  return ran === 0 ? 1 : result.counts.pass / ran;
+};
+var parseFlags = (args) => {
+  if (!isAgentKind(args.agent)) {
+    logger.error(`Invalid --agent "${args.agent}" (use claude | codex).`);
+    process.exit(1);
+  }
+  if (args.action !== undefined && args.action !== "init") {
+    logger.error(`Unknown action "${args.action}" (did you mean "init"?).`);
+    process.exit(1);
+  }
+  if (args.json && args.fix) {
+    logger.error("--json and --fix are mutually exclusive.");
+    process.exit(1);
+  }
+  const threshold = args.threshold === undefined ? 1 : Number(args.threshold);
+  if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+    logger.error(`Invalid --threshold "${args.threshold}" (use 0..1).`);
+    process.exit(1);
+  }
+  const timeoutS = args.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(args.timeout);
+  if (!Number.isInteger(timeoutS) || timeoutS <= 0) {
+    logger.error(`Invalid --timeout "${args.timeout}" (whole seconds).`);
+    process.exit(1);
+  }
+  return { agent: args.agent, threshold, timeoutS };
+};
+var runFixHandoff = async (agent, result, root, threshold) => {
+  const count = result.counts.fail + result.counts.error;
+  if (count === 0) {
+    return;
+  }
+  const cli = AGENTS[agent];
+  const report = await writeEvalReport(result, root, threshold);
+  process.stderr.write(`  Handing ${count} failed question${count === 1 ? "" : "s"} to ${cli.name}…
+
+`);
+  const code = await launchAgentCode2(cli.bin, evalFixPrompt(report));
+  if (code === WINDOWS_COMMAND_NOT_FOUND) {
+    notInstalled(agent);
+  }
+  if (code !== 0) {
+    process.exit(code);
+  }
+};
+var runInit = async (agent, file) => {
+  const path = join37(process.cwd(), file);
+  if (existsSync20(path)) {
+    logger.error(`${file} already exists — edit it directly, or pass --file to draft elsewhere.`);
+    process.exit(1);
+  }
+  const code = await launchAgentCode2(AGENTS[agent].bin, initPrompt(file));
+  if (code === WINDOWS_COMMAND_NOT_FOUND) {
+    notInstalled(agent);
+  }
+  if (code !== 0) {
+    process.exit(code);
+  }
+};
+var evalCommand = defineCommand8({
+  args: {
+    action: {
+      description: 'Optional action: "init" drafts a starter evals file.',
+      required: false,
+      type: "positional"
+    },
+    agent: {
+      default: "claude",
+      description: "Agent CLI that reads and grades the docs: claude | codex.",
+      type: "string"
+    },
+    file: {
+      default: DEFAULT_FILE,
+      description: "The evals file to run.",
+      type: "string"
+    },
+    fix: {
+      description: "After a failing run, hand the report to the agent to fix the docs interactively.",
+      type: "boolean"
+    },
+    json: {
+      description: "Emit the report as JSON on stdout (for CI/editors).",
+      type: "boolean"
+    },
+    threshold: {
+      description: "Minimum passing fraction (0..1) before the run exits non-zero. Defaults to 1.",
+      type: "string"
+    },
+    timeout: {
+      description: `Reader time limit per question, in seconds. Defaults to ${DEFAULT_TIMEOUT_S}.`,
+      type: "string"
+    },
+    verbose: {
+      description: "Include the reader's full answer under each failure.",
+      type: "boolean"
+    }
+  },
+  meta: {
+    description: "Test the docs: an agent answers your questions using only the documentation.",
+    name: "eval"
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const { agent, threshold, timeoutS } = parseFlags(args);
+    if (args.action === "init") {
+      await runInit(agent, args.file);
+      return;
+    }
+    let result;
+    try {
+      const project = await scanProject(root, { mode: "build" });
+      const evalsPath = join37(root, args.file);
+      const { evals, raw } = await loadEvalsFile(evalsPath);
+      process.stderr.write(`${headerLine(evals.questions.length, agent)}
+
+`);
+      result = await runEval({
+        agent,
+        evals,
+        evalsPath,
+        onProgress: (event) => {
+          if (event.kind === "question-start") {
+            process.stderr.write(`${startLine(event.id, event.index, event.total)}
+`);
+            return;
+          }
+          const lines = [
+            questionLine(event.result),
+            ...questionDetails(event.result, Boolean(args.verbose))
+          ];
+          process.stderr.write(`${lines.join(`
+`)}
+`);
+        },
+        project,
+        rawEvals: raw,
+        readerTimeoutMs: timeoutS * 1000
+      });
+    } catch (error) {
+      if (error instanceof EvalsFileError) {
+        logger.error(error.message);
+        process.exit(1);
+      }
+      if (error instanceof BlumeError) {
+        logger.error(error.diagnostic.message);
+        process.exit(1);
+      }
+      if (error?.code === "ENOENT") {
+        notInstalled(agent);
+      }
+      reportInternalError(error);
+      process.exit(1);
+    }
+    const tail2 = [
+      "",
+      ...warningLines(result, root),
+      ...fixLines(result, root),
+      "",
+      `  ${summaryLine2(result)}`,
+      ""
+    ];
+    process.stderr.write(tail2.join(`
+`));
+    const failed = passFraction(result) < threshold;
+    if (args.fix) {
+      await runFixHandoff(agent, result, root, threshold);
+      return;
+    }
+    if (args.json) {
+      process.stdout.write(evalReportJson(result, root, threshold));
+      if (failed) {
+        await flushStdout();
+        process.exit(1);
+      }
+      return;
+    }
+    if (failed) {
+      process.exit(1);
+    }
+  }
+});
+
 // src/cli/commands/init.ts
 import * as clack from "@clack/prompts";
-import { defineCommand as defineCommand8 } from "citty";
+import { defineCommand as defineCommand9 } from "citty";
 import { resolve as resolve10 } from "pathe";
 
 // src/cli/init/questions.ts
@@ -17007,7 +18013,7 @@ var ejectScaffold = async (root, answers) => {
 `);
   }
 };
-var initCommand = defineCommand8({
+var initCommand = defineCommand9({
   args: {
     "content-dir": {
       description: "Content directory.",
@@ -17083,7 +18089,11 @@ var initCommand = defineCommand8({
     }
     const sink = interactive ? clack.log : logger;
     const { createdPackage } = await applyPlan(buildPlan(root, answers), sink);
-    const ignored = await ensureGitignore(root, [".blume/", "dist/"]);
+    const ignored = await ensureGitignore(root, [
+      "node_modules/",
+      ".blume/",
+      "dist/"
+    ]);
     if (ignored.length > 0) {
       sink.success(`Added ${ignored.join(", ")} to .gitignore`);
     }
@@ -17101,12 +18111,223 @@ var initCommand = defineCommand8({
   }
 });
 
+// src/cli/commands/mcp-stdio.ts
+import { readFile as readFile19 } from "node:fs/promises";
+import { defineCommand as defineCommand10 } from "citty";
+
+// src/ai/mcp/stdio.ts
+import { once } from "node:events";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/ai/mcp/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/search/orama-index.ts
+import { create, insertMultiple, search } from "@orama/orama";
+var SCHEMA = {
+  content: "string",
+  description: "string",
+  locale: "enum",
+  route: "string",
+  title: "string"
+};
+var BOOST = { description: 2, title: 3 };
+var buildOramaIndex = async (documents) => {
+  const db = create({ schema: SCHEMA });
+  await insertMultiple(db, documents);
+  return db;
+};
+var queryOramaIndex = async (db, term, limit, locale) => {
+  const found = await search(db, {
+    boost: BOOST,
+    limit,
+    properties: ["title", "description", "content"],
+    term,
+    ...locale ? { where: { locale: { eq: locale } } } : {}
+  });
+  return found.hits.map((hit) => hit.document);
+};
+
+// src/ai/mcp/server.ts
+var DEFAULT_SEARCH_LIMIT = 8;
+var MAX_SEARCH_LIMIT = 20;
+var EXCERPT_LENGTH = 200;
+var INPUT_SCHEMAS = {
+  get_navigation: { properties: {}, type: "object" },
+  get_page: {
+    properties: {
+      route: {
+        description: "The page route, e.g. `/guides/install`.",
+        type: "string"
+      }
+    },
+    required: ["route"],
+    type: "object"
+  },
+  list_pages: { properties: {}, type: "object" },
+  search_docs: {
+    properties: {
+      limit: {
+        description: `Maximum hits to return (default ${DEFAULT_SEARCH_LIMIT}).`,
+        maximum: MAX_SEARCH_LIMIT,
+        minimum: 1,
+        type: "integer"
+      },
+      query: { description: "The search query.", type: "string" }
+    },
+    required: ["query"],
+    type: "object"
+  }
+};
+var TOOL_DEFINITIONS = MCP_TOOLS.map((tool) => ({
+  annotations: tool.annotations,
+  description: tool.description,
+  inputSchema: INPUT_SCHEMAS[tool.name],
+  name: tool.name,
+  title: tool.title
+}));
+var asString2 = (value) => typeof value === "string" ? value : "";
+var asLimit = (value) => {
+  const num = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(num)) {
+    return DEFAULT_SEARCH_LIMIT;
+  }
+  return Math.min(Math.max(Math.trunc(num), 1), MAX_SEARCH_LIMIT);
+};
+var normalizeRoute2 = (input, data) => {
+  let value = input.trim();
+  if (/^https?:\/\//iu.test(value)) {
+    try {
+      value = new URL(value).pathname;
+    } catch {}
+  }
+  try {
+    value = decodeURI(value);
+  } catch {}
+  const noTrailing = value.replace(/\/+$/u, "");
+  const noSuffix = noTrailing.replace(/\.mdx?$/u, "");
+  const withSlash = noSuffix.startsWith("/") ? noSuffix : `/${noSuffix}`;
+  const based = stripBasePath(data.base, withSlash);
+  return based === "" ? "/" : based;
+};
+var urlFor = (route, data) => {
+  const path = withBasePath(data.base, route);
+  return data.site ? `${data.site.replace(/\/+$/u, "")}${path}` : path;
+};
+var excerptFor = (doc) => {
+  if (doc.description) {
+    return doc.description;
+  }
+  const head = doc.content.slice(0, EXCERPT_LENGTH).trim();
+  return doc.content.length > EXCERPT_LENGTH ? `${head}…` : head;
+};
+var text = (value, isError = false) => ({
+  content: [{ text: value, type: "text" }],
+  ...isError ? { isError: true } : {}
+});
+var createIndexProvider = (documents) => {
+  let dbPromise = null;
+  return () => {
+    dbPromise ??= buildOramaIndex(documents);
+    return dbPromise;
+  };
+};
+var buildServer = (data, index) => {
+  const server = new Server({ name: data.name, version: data.version }, {
+    capabilities: { tools: {} },
+    ...data.instructions ? { instructions: data.instructions } : {}
+  });
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: TOOL_DEFINITIONS
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request2) => {
+    const { arguments: args = {}, name } = request2.params;
+    if (name === "search_docs") {
+      const db = await index();
+      const hits = await queryOramaIndex(db, asString2(args.query), asLimit(args.limit));
+      const results = hits.map((doc) => ({
+        excerpt: excerptFor(doc),
+        route: doc.route,
+        title: doc.title,
+        url: urlFor(doc.route, data)
+      }));
+      return text(JSON.stringify(results, null, 2));
+    }
+    if (name === "get_page") {
+      const key = normalizeRoute2(asString2(args.route), data);
+      const markdown = data.pages[key];
+      if (markdown === undefined) {
+        return text(`No page found at "${key}". Use list_pages or search_docs to find valid routes.`, true);
+      }
+      return text(markdown);
+    }
+    if (name === "list_pages") {
+      return text(JSON.stringify(data.routes.map((route) => ({
+        contentType: route.contentType,
+        description: route.description,
+        lastModified: route.lastModified,
+        route: route.route,
+        title: route.title,
+        url: urlFor(route.route, data)
+      })), null, 2));
+    }
+    if (name === "get_navigation") {
+      return text(JSON.stringify(data.navigation, null, 2));
+    }
+    return text(`Unknown tool: ${name}`, true);
+  });
+  return server;
+};
+
+// src/ai/mcp/stdio.ts
+var serveMcpStdio = async (data, streams = {}) => {
+  const stdin = streams.stdin ?? process.stdin;
+  const stdout = streams.stdout ?? process.stdout;
+  const transport = new StdioServerTransport(stdin, stdout);
+  const server = buildServer(data, createIndexProvider(data.documents));
+  await server.connect(transport);
+  await once(stdin, "end");
+  await transport.close();
+};
+
+// src/cli/commands/mcp-stdio.ts
+var mcpStdioCommand = defineCommand10({
+  args: {
+    data: {
+      description: "Path to a serialized MCP data snapshot (JSON).",
+      required: true,
+      type: "string"
+    }
+  },
+  meta: {
+    description: "Serve an MCP data snapshot over stdio (internal, used by `blume eval`).",
+    name: "mcp-stdio"
+  },
+  async run({ args }) {
+    let data;
+    try {
+      data = JSON.parse(await readFile19(args.data, "utf-8"));
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`blume mcp-stdio: cannot load the snapshot at ${args.data}: ${detail}
+`);
+      process.exit(1);
+    }
+    await serveMcpStdio(data);
+  }
+});
+
 // src/cli/commands/preview.ts
-import { existsSync as existsSync20 } from "node:fs";
+import { existsSync as existsSync21 } from "node:fs";
 import { preview } from "astro";
-import { defineCommand as defineCommand9 } from "citty";
-import { join as join34 } from "pathe";
-var previewCommand = defineCommand9({
+import { defineCommand as defineCommand11 } from "citty";
+import { join as join38 } from "pathe";
+var previewCommand = defineCommand11({
   args: {
     host: { description: "Network host to bind.", type: "string" },
     port: { description: "Port to listen on.", type: "string" }
@@ -17119,7 +18340,7 @@ var previewCommand = defineCommand9({
     const root = process.cwd();
     const { config } = await loadConfig(root);
     const context = resolveProjectContext(root, config);
-    if (!existsSync20(join34(context.outDir, "astro.config.mjs"))) {
+    if (!existsSync21(join38(context.outDir, "astro.config.mjs"))) {
       logger.error("No build found. Run `blume build` first.");
       process.exit(1);
     }
@@ -17136,9 +18357,9 @@ var previewCommand = defineCommand9({
 
 // src/cli/commands/sync.ts
 import { rm as rm4 } from "node:fs/promises";
-import { defineCommand as defineCommand10 } from "citty";
-import { join as join35 } from "pathe";
-var syncCommand = defineCommand10({
+import { defineCommand as defineCommand12 } from "citty";
+import { join as join39 } from "pathe";
+var syncCommand = defineCommand12({
   args: {
     force: {
       description: "Clear the source cache before refetching.",
@@ -17159,7 +18380,7 @@ var syncCommand = defineCommand10({
     if (args.force) {
       const { config } = await loadConfig(root);
       const context = resolveProjectContext(root, config);
-      await rm4(join35(context.outDir, "cache"), { force: true, recursive: true });
+      await rm4(join39(context.outDir, "cache"), { force: true, recursive: true });
       logger.info("Cleared source cache.");
     }
     const lock = readDevLock(resolveRuntimeDir(root));
@@ -17177,13 +18398,13 @@ var syncCommand = defineCommand10({
 });
 
 // src/cli/commands/validate.ts
-import { existsSync as existsSync22 } from "node:fs";
-import { defineCommand as defineCommand11 } from "citty";
-import { join as join37 } from "pathe";
+import { existsSync as existsSync23 } from "node:fs";
+import { defineCommand as defineCommand13 } from "citty";
+import { join as join41 } from "pathe";
 
 // src/core/links.ts
-import { existsSync as existsSync21 } from "node:fs";
-import { basename as basename7, join as join36 } from "pathe";
+import { existsSync as existsSync22 } from "node:fs";
+import { basename as basename7, join as join40 } from "pathe";
 var HTTP = /^https?:\/\//iu;
 var PROTOCOL_RELATIVE = /^\/\//u;
 var SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
@@ -17196,7 +18417,7 @@ var decodePercent = (value) => {
 };
 var DOC_EXT = /\.(?:md|mdx)$/iu;
 var FILE_EXT = /\.[a-z0-9]+$/iu;
-var assetIsPresent = (resolved, ctx) => ctx.publicDir !== null && existsSync21(join36(ctx.publicDir, resolved));
+var assetIsPresent = (resolved, ctx) => ctx.publicDir !== null && existsSync22(join40(ctx.publicDir, resolved));
 var NUMERIC_PREFIX3 = /^\d+[-_.]/u;
 var isIndexPage = (page2) => /^index\.(?:md|mdx)$/iu.test(basename7(page2.navPath).replace(NUMERIC_PREFIX3, ""));
 var applyRelativePart = (segments, part) => {
@@ -17369,7 +18590,7 @@ var validateLinks = async (graph, options) => {
 };
 
 // src/cli/commands/validate.ts
-var validateCommand = defineCommand11({
+var validateCommand = defineCommand13({
   args: {
     external: {
       description: "Check external (HTTP) links over the network.",
@@ -17407,12 +18628,12 @@ var validateCommand = defineCommand11({
         });
         extraRoutes.push(...manifest.routes.flatMap((route) => route.fallback ? [route.path] : []));
       }
-      const publicDir = join37(root, "public");
+      const publicDir = join41(root, "public");
       diagnostics.push(...await validateLinks(project.graph, {
         basePath: project.config.basePath,
         checkExternal: Boolean(args.external),
         extraRoutes,
-        publicDir: existsSync22(publicDir) ? publicDir : null,
+        publicDir: existsSync23(publicDir) ? publicDir : null,
         redirects: project.config.redirects
       }));
     } catch (error) {
@@ -17443,7 +18664,7 @@ var validateCommand = defineCommand11({
 });
 
 // src/cli/index.ts
-var main = defineCommand12({
+var main = defineCommand14({
   meta: {
     description: "Markdown-first documentation powered by Astro and Vite.",
     name: "blume",
@@ -17457,7 +18678,9 @@ var main = defineCommand12({
     dev: devCommand,
     doctor: doctorCommand,
     eject: ejectCommand,
+    eval: evalCommand,
     init: initCommand,
+    "mcp-stdio": mcpStdioCommand,
     preview: previewCommand,
     sync: syncCommand,
     validate: validateCommand
@@ -17474,5 +18697,5 @@ process.on("unhandledRejection", (error) => {
 });
 runMain(main);
 
-//# debugId=5D342B2E16EE6E0464756E2164756E21
+//# debugId=E4DFD2C6131D546564756E2164756E21
 //# sourceMappingURL=index.js.map