blume 1.7.1 → 1.7.3

package/src/core/schema.ts

@@ -767,6 +767,19 @@ const searchConfigSchema = z
     }
   });
 
+/**
+ * The `ai.ask.reasoning` levels: the AI SDK's top-level `reasoning` values
+ * minus `provider-default`, which is what omitting the field means.
+ */
+export const askReasoningLevels = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+
 /** Ask AI backends. `gateway` (default) routes through the Vercel AI Gateway. */
 export const askAiProviders = [
   "gateway",
@@ -856,6 +869,23 @@ const llmsTxtObjectSchema = z.strictObject({
 
 type LlmsTxtResolved = z.output<typeof llmsTxtObjectSchema>;
 
+/** The object form of `ai.catalog`; a bare boolean normalizes onto it. */
+const aiCatalogObjectSchema = z.strictObject({
+  enabled: z.boolean().default(true),
+  /**
+   * Representative queries per catalog entry, keyed by the entry's
+   * `<namespace>:<name>` (the identifier minus its `urn:air:<host>:` prefix,
+   * e.g. `mcp:docs`, `skill:blume`, `api:docs`). Replaces the generated
+   * defaults for that entry; 2–5 short natural-language questions the
+   * resource can answer, which registries embed for semantic search.
+   */
+  queries: z
+    .record(z.string().min(1), z.array(z.string().trim().min(1)).min(1))
+    .default({}),
+});
+
+type AiCatalogResolved = z.output<typeof aiCatalogObjectSchema>;
+
 const aiConfigSchema = z.strictObject({
   /**
    * The JSON docs API: the page index, per-page JSON, and navigation under
@@ -872,6 +902,21 @@ const aiConfigSchema = z.strictObject({
       // Base URL of the backend. Required for `openai-compatible` only when no
       // external endpoint is supplied; for named providers it overrides the preset.
       baseUrl: z.url().optional(),
+      // Origins allowed to call the generated `/api/ask` from another site (a
+      // marketing page that embeds an ask box, say), or `"*"` for every
+      // origin. Each URL is reduced to its origin so a trailing slash or path
+      // can't defeat the exact match the route performs. Read by the
+      // generated route only; an external `endpoint` owns its own CORS.
+      cors: z
+        .array(
+          z.union([
+            z.literal("*"),
+            z
+              .url({ protocol: /^https?$/u })
+              .transform((value) => new URL(value).origin),
+          ])
+        )
+        .optional(),
       enabled: z.boolean().default(false),
       // Optional external endpoint for projects that keep their docs static
       // and host Ask AI in an existing backend. Absolute URLs and root-relative
@@ -888,6 +933,12 @@ const aiConfigSchema = z.strictObject({
       instructions: z.string().trim().min(1).optional(),
       model: z.string().default("openai/gpt-5.5"),
       provider: z.enum(askAiProviders).default("gateway"),
+      // How much the model reasons before answering, sent as the backend's
+      // own reasoning-effort control (see `askEndpointTemplate`). Omitted
+      // keeps the provider's default; `none` is the fastest and cheapest for
+      // grounded docs Q&A, where the excerpts carry the answer. Not for
+      // Inkeep, which has no such control (refined below).
+      reasoning: z.enum(askReasoningLevels).optional(),
       // How much documentation each question carries. Injected characters are
       // the dominant term in time-to-first-token on a self-hosted backend, so
       // these trade recall for latency. No zod defaults here: only what the
@@ -926,8 +977,44 @@ const aiConfigSchema = z.strictObject({
           path: ["baseUrl"],
         });
       }
+      // `cors` configures the generated route, which an external `endpoint`
+      // replaces; accepting both would silently do nothing.
+      if (value.cors && value.endpoint) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "ai.ask.cors only applies to the generated route; with ai.ask.endpoint, CORS is that backend's job.",
+          path: ["cors"],
+        });
+      }
+      // Inkeep runs its own QA pipeline behind an OpenAI-compatible endpoint
+      // with no reasoning control; a level would only reach it as an
+      // unsupported `reasoning_effort`, so refuse it up front.
+      if (value.provider === "inkeep" && value.reasoning) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            'ai.ask.reasoning is not supported when provider is "inkeep".',
+          path: ["reasoning"],
+        });
+      }
     })
     .optional(),
+  /**
+   * The AI Catalog / ARD manifest at `/.well-known/ai-catalog.json` (mirrored
+   * at `/.well-known/ard.json`): one entry per agent-facing resource the site
+   * publishes — the MCP server card, each agent skill, the JSON docs API's
+   * OpenAPI document, each rendered API reference, and llms.txt — so agent
+   * registries can index the site from its domain alone. Needs a
+   * `deployment.site` (identifiers are domain-anchored URNs). On by default;
+   * the object form overrides the generated representative queries.
+   */
+  catalog: z
+    .union([z.boolean(), aiCatalogObjectSchema])
+    .default(true)
+    .transform((value): AiCatalogResolved =>
+      isBoolean(value) ? { enabled: value, queries: {} } : value
+    ),
   /**
    * `llms.txt`/`llms-full.txt` emission. A bare boolean toggles it; the object
    * form adds `openapi: false` to keep generated API reference pages out of
@@ -1078,6 +1165,7 @@ const navigationConfigSchema = z.strictObject({
 });
 
 export type AskAiProvider = (typeof askAiProviders)[number];
+export type AskReasoning = (typeof askReasoningLevels)[number];
 export type AskAiConfig = NonNullable<z.infer<typeof aiConfigSchema>["ask"]>;
 export { openInChatProviders } from "./open-in-chat.ts";
 export type { OpenInChatProvider } from "./open-in-chat.ts";

package/src/core/types.ts

@@ -220,6 +220,11 @@ export type NavNode =
        */
       display: SidebarDisplay;
       icon?: string;
+      /**
+       * The group row's link: an explicit-config group's `root`, or the
+       * generated folder's index page route. Absent when there is no page at
+       * the group's own path, so the row never links to a 404.
+       */
       route?: string;
       /**
        * The group's URL path (its folder route prefix), even when the folder

package/src/deploy/artifacts.ts

@@ -4,6 +4,11 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "pathe";
 
 import { buildAgentReadability } from "../ai/agent-readability.ts";
+import {
+  AI_CATALOG_PATH,
+  ARD_MANIFEST_PATH,
+  buildAiCatalog,
+} from "../ai/ai-catalog.ts";
 import { API_CATALOG_PATH, buildApiCatalog } from "../ai/api-catalog.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
 import { buildLlmsFiles } from "../ai/llms.ts";
@@ -234,8 +239,12 @@ const emitAgentSkills = async (
 const emitWellKnownFiles = async (
   config: ResolvedConfig,
   distDir: string,
+  skills: readonly SkillArtifact[],
   logger: ArtifactLogger
 ): Promise<void> => {
+  // One document, two paths: the ai-catalog spec's well-known URI and the
+  // ARD v0.91 one (see `ai/ai-catalog.ts`).
+  const aiCatalog = buildAiCatalog(config, skills);
   const files = [
     {
       content: buildSignaturesDirectory(config),
@@ -247,6 +256,8 @@ const emitWellKnownFiles = async (
       label: "RFC 9727",
       path: API_CATALOG_PATH,
     },
+    { content: aiCatalog, label: "AI Catalog", path: AI_CATALOG_PATH },
+    { content: aiCatalog, label: "ARD manifest", path: ARD_MANIFEST_PATH },
   ];
   for (const file of files) {
     const target = join(distDir, file.path.slice(1));
@@ -362,7 +373,7 @@ export const publishBuildArtifacts = async (
     logger.info("Generated agent-readability.json");
   }
 
-  await emitWellKnownFiles(project.config, distDir, logger);
+  await emitWellKnownFiles(project.config, distDir, skills, logger);
   await emitAgentSkills(project, distDir, skills, logger);
 
   await emitRedirectFiles(project.config, distDir, logger);

package/src/deploy/headers.ts

@@ -1,3 +1,4 @@
+import { crossOriginDiscoveryPaths } from "../ai/ai-catalog.ts";
 import {
   API_CATALOG_PATH,
   API_CATALOG_TYPE,
@@ -95,6 +96,11 @@ export const buildNetlifyHeaders = (
       `${deployBase}${SIGNATURES_DIRECTORY_PATH}\n  Content-Type: ${SIGNATURES_DIRECTORY_TYPE}`
     );
   }
+  // Agent registries fetch the discovery documents cross-origin; a static
+  // host sends no CORS header unless told to.
+  for (const path of crossOriginDiscoveryPaths(config)) {
+    rules.push(`${deployBase}${path}\n  Access-Control-Allow-Origin: *`);
+  }
   // Published skills live at the deployment base, outside `basePath` — the
   // `.md` charset rule above misses them whenever a basePath is set, and the
   // RFC wants archives served as application/gzip explicitly.

package/src/deploy/vercel-negotiation.ts

@@ -235,6 +235,26 @@ export const buildNegotiationRoutes = (
 /** The `src` of the injected homepage `Link` header route. */
 const HOME_SRC = "^/$";
 
+const ALLOW_ANY_ORIGIN = "*";
+
+/**
+ * A main-phase `continue` route stamping `Access-Control-Allow-Origin: *` on
+ * one static discovery document (see `crossOriginDiscoveryPaths`), so a
+ * registry reading it from another origin isn't refused by the browser.
+ */
+const corsRoute = (path: string): VercelRoute => ({
+  continue: true,
+  headers: { "access-control-allow-origin": ALLOW_ANY_ORIGIN },
+  src: `^${routePattern(path)}$`,
+});
+
+/** Whether a route is a `corsRoute` — the same three-field shape test as the others. */
+const isCorsRoute = (route: VercelRoute): boolean =>
+  route.continue === true &&
+  route.headers?.["access-control-allow-origin"] === ALLOW_ANY_ORIGIN &&
+  isString(route.src) &&
+  Object.keys(route).length === 3;
+
 /**
  * Whether a route is one this module previously injected, so re-injection
  * replaces rather than duplicates. Rewrites are identified by their `accept`
@@ -258,7 +278,8 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
   (route.continue === true &&
     isString(route.headers?.link) &&
     route.src === HOME_SRC &&
-    Object.keys(route).length === 3);
+    Object.keys(route).length === 3) ||
+  isCorsRoute(route);
 
 /**
  * Splice the negotiation routes into a Build Output `config.json`, plus — when
@@ -287,7 +308,8 @@ export const injectNegotiationRoutes = (
   homeLinkHeader?: string | null,
   contentTypeOverrides?: Record<string, string>,
   homeTokens?: number,
-  notFound: NotFoundVariants = {}
+  notFound: NotFoundVariants = {},
+  corsPaths: readonly string[] = []
 ): string | null => {
   const overrideEntries = Object.entries(contentTypeOverrides ?? {});
   let config: {
@@ -325,6 +347,7 @@ export const injectNegotiationRoutes = (
       src: HOME_SRC,
     });
   }
+  headerRoutes.push(...corsPaths.map(corsRoute));
   // Headers first: `continue` routes accumulate, so a request the rewrite
   // route then terminates (Markdown negotiation on the homepage) still carries
   // the Link header.

package/src/registry/eject.ts

@@ -137,7 +137,9 @@ const askFiles = async (
   const files = [
     {
       content: askEndpointTemplate(resolveAskBackend(ask), grounded, {
+        cors: ask.cors,
         instructions: ask.instructions,
+        reasoning: ask.reasoning,
         retrieval: ask.retrieval,
       }),
       path: join(srcDir, "pages", "api", "ask.ts"),

package/src/search/build.ts

@@ -1,4 +1,6 @@
-import { join } from "pathe";
+import { mkdir, writeFile } from "node:fs/promises";
+
+import { dirname, join } from "pathe";
 
 /**
  * Build a local Pagefind search index over the built site. Pagefind indexes
@@ -6,6 +8,15 @@ import { join } from "pathe";
  * `data-pagefind-ignore`, which Blume stamps on non-indexable pages
  * (search-excluded, or hidden without the opt-in), so those stay out.
  *
+ * The index files are fetched with `getFiles()` and written here rather than
+ * with Pagefind's `writeFiles()`: in service mode Pagefind acknowledges
+ * `writeFiles()` once tokio has buffered the writes, not once they are on
+ * disk, and `close()` kills the backend, so a loaded CI host can ship a
+ * truncated `pagefind-entry.json` (Pagefind/pagefind#1271). Writing the bytes
+ * ourselves puts them on disk before the backend goes away. Fixed upstream in
+ * Pagefind/pagefind#1272; switch back to `writeFiles()` once a release ships
+ * that fix.
+ *
  * Returns the number of pages indexed.
  */
 export const buildSearchIndex = async (outDir: string): Promise<number> => {
@@ -17,11 +28,22 @@ export const buildSearchIndex = async (outDir: string): Promise<number> => {
   }
 
   // These awaits are strictly ordered, not independent: the directory must be
-  // indexed before its files are written, and the index closed only after.
+  // indexed before its files are read, and the index closed only after.
   // oxlint-disable-next-line react-doctor/async-parallel
   const result = await index.addDirectory({ path: outDir });
-  await index.writeFiles({ outputPath: join(outDir, "pagefind") });
+  const { files } = await index.getFiles();
   await pagefind.close();
 
+  const searchDir = join(outDir, "pagefind");
+  const directories = new Set(
+    files.map((file) => dirname(join(searchDir, file.path)))
+  );
+  await Promise.all(
+    [...directories].map((directory) => mkdir(directory, { recursive: true }))
+  );
+  await Promise.all(
+    files.map((file) => writeFile(join(searchDir, file.path), file.content))
+  );
+
   return result.page_count;
 };

package/src/theme/entry.ts

@@ -298,6 +298,11 @@ ${THEME_MAPPING}
   --tw-prose-pre-bg: var(--blume-code-background);
   --tw-prose-th-borders: var(--blume-border);
   --tw-prose-td-borders: var(--blume-border);
+  /* Neutralized: the plugin defaults are near-black text and shadow with no
+     dark counterpart (Blume never applies prose-invert), and the kbd rule
+     below draws the badge with Blume tokens instead. */
+  --tw-prose-kbd: inherit;
+  --tw-prose-kbd-shadows: transparent;
   color: var(--blume-muted-foreground);
   font-size: 0.875rem;
   line-height: 1.7;
@@ -827,6 +832,24 @@ pre:has(.line.focused):hover .line:not(.focused) {
   content: none;
 }
 
+/* Keyboard keys (<kbd>) render as the same bordered badge the search dialog
+   uses for its shortcut hints. Typography's own kbd rule is scoped with
+   :not(.not-prose *), so it never reaches a key inside <Steps>, <Callout>,
+   <Card>, or any other not-prose component; this rule is deliberately
+   unscoped from that exclusion so a key looks the same everywhere in the
+   content column. Unlayered, so it outranks the plugin's layered rule. */
+.prose kbd {
+  background: var(--blume-muted);
+  border: 1px solid var(--blume-border);
+  border-radius: 0.25rem;
+  box-shadow: none;
+  color: inherit;
+  font-family: var(--font-mono);
+  font-size: 0.85em;
+  font-weight: 500;
+  padding: 0.125rem 0.25rem;
+}
+
 /* Inline code highlighting: Shiki colors the tokens of a \`code\`{:lang} snippet
    via the same dual-theme CSS variables as fenced blocks, keeping the inline
    pill background. Always on — it only fires on the trailing {:lang} marker. */

package/dist/cli/chunk-2aj8ddew.js

@@ -1,72 +0,0 @@
-#!/usr/bin/env node
-import { createRequire } from "node:module";
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/cli/command-meta.ts
-var commandMeta = {
-  add: {
-    description: "Install a source component or template from the registry.",
-    name: "add"
-  },
-  audit: {
-    description: "Audit the built site for SEO and site-health issues.",
-    name: "audit"
-  },
-  build: {
-    description: "Build the docs site for production.",
-    name: "build"
-  },
-  check: {
-    description: "Type-check the docs site with astro check.",
-    name: "check"
-  },
-  dev: {
-    description: "Start the Blume development server.",
-    name: "dev"
-  },
-  doctor: {
-    description: "Diagnose common configuration and content problems.",
-    name: "doctor"
-  },
-  eject: {
-    description: "Promote the generated runtime into an owned Astro project.",
-    name: "eject"
-  },
-  eval: {
-    description: "Test the docs: an agent answers your questions using only the documentation.",
-    name: "eval"
-  },
-  init: {
-    description: "Scaffold a minimal Blume project.",
-    name: "init"
-  },
-  "mcp-stdio": {
-    description: "Serve an MCP data snapshot over stdio (internal, used by `blume eval`).",
-    name: "mcp-stdio"
-  },
-  preview: {
-    description: "Preview the last production build.",
-    name: "preview"
-  },
-  sync: {
-    description: "Re-fetch remote content sources and regenerate the runtime.",
-    name: "sync"
-  },
-  translate: {
-    description: "Translate docs into the configured locales with a local agent CLI.",
-    name: "translate"
-  },
-  validate: {
-    description: "Validate internal, anchor, asset, and external links.",
-    name: "validate"
-  },
-  version: {
-    description: "Freeze the current docs as an archived version.",
-    name: "version"
-  }
-};
-
-export { __require, commandMeta };
-
-//# debugId=3DF60EB79641093164756E2164756E21
-//# sourceMappingURL=chunk-2aj8ddew.js.map

package/dist/cli/chunk-2aj8ddew.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/cli/command-meta.ts"],
-  "sourcesContent": [
-    "import type { CommandMeta } from \"citty\";\n\n/**\n * Every command's `meta`, held apart from the command modules themselves.\n *\n * The CLI entry loads each command lazily (see `lazy-command.ts`), but citty\n * still reads every subcommand's `meta` to render `blume --help` and to match\n * an unknown name against aliases. Keeping that table here lets those paths\n * run without importing a single command module — `dev` alone drags in Astro,\n * `mcp-stdio` the MCP SDK. The command modules read their `meta` from this\n * table too, so the entry and the command can't drift.\n */\nexport const commandMeta = {\n  add: {\n    description: \"Install a source component or template from the registry.\",\n    name: \"add\",\n  },\n  audit: {\n    description: \"Audit the built site for SEO and site-health issues.\",\n    name: \"audit\",\n  },\n  build: {\n    description: \"Build the docs site for production.\",\n    name: \"build\",\n  },\n  check: {\n    description: \"Type-check the docs site with astro check.\",\n    name: \"check\",\n  },\n  dev: {\n    description: \"Start the Blume development server.\",\n    name: \"dev\",\n  },\n  doctor: {\n    description: \"Diagnose common configuration and content problems.\",\n    name: \"doctor\",\n  },\n  eject: {\n    description: \"Promote the generated runtime into an owned Astro project.\",\n    name: \"eject\",\n  },\n  eval: {\n    description:\n      \"Test the docs: an agent answers your questions using only the documentation.\",\n    name: \"eval\",\n  },\n  init: {\n    description: \"Scaffold a minimal Blume project.\",\n    name: \"init\",\n  },\n  \"mcp-stdio\": {\n    description:\n      \"Serve an MCP data snapshot over stdio (internal, used by `blume eval`).\",\n    name: \"mcp-stdio\",\n  },\n  preview: {\n    description: \"Preview the last production build.\",\n    name: \"preview\",\n  },\n  sync: {\n    description: \"Re-fetch remote content sources and regenerate the runtime.\",\n    name: \"sync\",\n  },\n  translate: {\n    description:\n      \"Translate docs into the configured locales with a local agent CLI.\",\n    name: \"translate\",\n  },\n  validate: {\n    description: \"Validate internal, anchor, asset, and external links.\",\n    name: \"validate\",\n  },\n  version: {\n    description: \"Freeze the current docs as an archived version.\",\n    name: \"version\",\n  },\n} satisfies Record<string, CommandMeta>;\n"
-  ],
-  "mappings": ";;;;;AAYO,IAAM,cAAc;AAAA,EACzB,KAAK;AAAA,IACH,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,OAAO;AAAA,IACL,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,OAAO;AAAA,IACL,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,OAAO;AAAA,IACL,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,KAAK;AAAA,IACH,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,QAAQ;AAAA,IACN,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,OAAO;AAAA,IACL,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,MAAM;AAAA,IACJ,aACE;AAAA,IACF,MAAM;AAAA,EACR;AAAA,EACA,MAAM;AAAA,IACJ,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,aAAa;AAAA,IACX,aACE;AAAA,IACF,MAAM;AAAA,EACR;AAAA,EACA,SAAS;AAAA,IACP,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,MAAM;AAAA,IACJ,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,WAAW;AAAA,IACT,aACE;AAAA,IACF,MAAM;AAAA,EACR;AAAA,EACA,UAAU;AAAA,IACR,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA,SAAS;AAAA,IACP,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AACF;",
-  "debugId": "3DF60EB79641093164756E2164756E21",
-  "names": []
-}