blume 1.7.3 → 2.0.1

package/src/core/schema.ts

@@ -1,19 +1,41 @@
 import type { AstroIntegration } from "astro";
 import { z } from "zod";
 
+import {
+  assistantAdapterSchema,
+  assistantMovedFieldsHint,
+  DEFAULT_ASSISTANT_PROVIDER,
+} from "../ai/ask.ts";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import { analyticsConfigSchema } from "../analytics/schema.ts";
+import { resolvedDeploymentSchema } from "../deploy/adapters/registry.ts";
 import type { CodeTheme } from "../markdown/themes.ts";
 import { normalizeRoute } from "../openapi/references.ts";
+import {
+  referenceConfigSchema,
+  removedReferenceKeysHint,
+} from "../reference/schema.ts";
+import { orama } from "../search/adapters/orama.ts";
+import {
+  NONE_SEARCH_ADAPTER,
+  resolvedSearchAdapterSchema,
+} from "../search/adapters/registry.ts";
+import type { SearchAdapterInput } from "../search/adapters/registry.ts";
 import { normalizeXHandle } from "../seo/x-handle.ts";
+import { filesystem } from "../sources/filesystem.ts";
+import {
+  contentSourcesSchema,
+  resolvedSourceAdapterSchema,
+} from "../sources/registry.ts";
 import { FONT_SLUGS, isFontSlug } from "../theme/fonts.ts";
 import { normalizeBasePath } from "./base-path.ts";
 import { PUBLIC_HOST_URL } from "./github.ts";
 import { uiLocaleOverridesSchema } from "./i18n-ui.ts";
 import { openInChatProviders } from "./open-in-chat.ts";
-import type { ContentSource } from "./sources/types.ts";
 import { isStandardSchema } from "./standard-schema.ts";
 import type { StandardSchema } from "./standard-schema.ts";
 import { trimEnd } from "./trim.ts";
+import { unrecognizedKeysMessage } from "./unrecognized-keys.ts";
 
 /**
  * An absolute HTTP(S) URL, for any field that lands verbatim in an `href` —
@@ -42,12 +64,40 @@ const isString = <Value>(value: Value): value is Value & string =>
 const isBoolean = <Value>(value: Value): value is Value & boolean =>
   typeof value === "boolean";
 
+const isObjectLike = <Value>(value: Value): value is Value & object =>
+  typeof value === "object" && value !== null;
+
 /** Icon inputs in serializable contexts (frontmatter, meta files). */
 const iconName = z.string().min(1);
 
-/** Default include glob for filesystem-backed content sources. */
-const DEFAULT_CONTENT_GLOB = "**/*.{md,mdx}";
+/**
+ * Error params for a strict object whose keys were removed or moved in a
+ * major release. A config still carrying one of `hints`' keys fails with
+ * the message that names its replacement, instead of Zod's bare
+ * "Unrecognized key"; any other unknown key keeps the default message.
+ */
+const removedKeysHint = (hints: Record<string, string>) => ({
+  error: (issue: z.core.$ZodRawIssue): string | undefined => {
+    if (issue.code !== "unrecognized_keys") {
+      return;
+    }
+    const messages = issue.keys.flatMap((key) =>
+      Object.hasOwn(hints, key) ? [hints[key]] : []
+    );
+    if (messages.length === 0) {
+      return;
+    }
+    // A hinted key beside a plain unknown one: keep Zod's wording for the
+    // latter so it isn't silently dropped from the diagnostic.
+    const others = issue.keys.filter((key) => !Object.hasOwn(hints, key));
+    if (others.length > 0) {
+      messages.push(unrecognizedKeysMessage(others));
+    }
+    return messages.join(" ");
+  },
+});
 
+/** Default include glob for filesystem-backed content sources. */
 const hydrationMode = z.enum(["load", "idle", "visible", "media", "only"]);
 export type HydrationMode = z.infer<typeof hydrationMode>;
 
@@ -105,11 +155,16 @@ const seoMetaSchema = z.strictObject({
   x: z.strictObject({ creator: xHandleSchema }).optional(),
 });
 
-const searchMetaSchema = z.strictObject({
-  boost: z.number().optional(),
-  exclude: z.boolean().default(false),
-  tags: z.array(z.string()).optional(),
-});
+const searchMetaSchema = z.strictObject(
+  {
+    exclude: z.boolean().default(false),
+    tags: z.array(z.string()).optional(),
+  },
+  removedKeysHint({
+    boost:
+      "search.boost was removed: search never read it, so the page ranked the same without it. Delete the field.",
+  })
+);
 
 const aiMetaSchema = z.strictObject({
   /** Exclude this page from llms.txt and llms-full.txt. */
@@ -291,161 +346,8 @@ const bannerConfigSchema = z.union([
   }),
 ]);
 
-/** A local filesystem content source. */
-const filesystemSourceSchema = z.strictObject({
-  exclude: z.array(z.string()).default(["**/_*", "**/.*"]),
-  include: z.array(z.string()).default([DEFAULT_CONTENT_GLOB]),
-  /** Namespaces the source's routes under `/<prefix>/`. */
-  prefix: z.string().optional(),
-  root: z.string().default("docs"),
-  type: z.literal("filesystem"),
-});
-
-/**
- * Remote Markdown/MDX fetched over HTTP. Enumerate files either explicitly
- * (`files` against a raw `url` base) or from a GitHub repo subtree (`github`).
- * The token, when needed, comes from `GITHUB_TOKEN` — never inlined here.
- */
-const mdxRemoteSourceSchema = z.strictObject({
-  /** Explicit list of source-relative file paths to fetch from `url`. */
-  files: z.array(z.string()).optional(),
-  /** Enumerate a GitHub repo subtree via the git-trees API. */
-  github: z
-    .strictObject({
-      owner: z.string(),
-      path: z.string().default(""),
-      ref: z.string().default("main"),
-      repo: z.string(),
-    })
-    .optional(),
-  /** Glob patterns applied to enumerated refs. */
-  include: z.array(z.string()).default([DEFAULT_CONTENT_GLOB]),
-  /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
-  pollInterval: z.number().positive().optional(),
-  /** Namespaces the source's routes under `/<prefix>/`. */
-  prefix: z.string().optional(),
-  type: z.literal("mdx-remote"),
-  /** Raw base URL, e.g. `https://raw.githubusercontent.com/acme/sdk/main/docs`. */
-  url: z.string().optional(),
-});
-
-/** A Sanity dataset queried with GROQ; Portable Text bodies become Markdown. */
-const sanitySourceSchema = z.object({
-  /** Sanity API version (a date); default `2024-01-01`. */
-  apiVersion: z.string().optional(),
-  dataset: z.string(),
-  /** Field paths mapping a document onto Blume meta + body. */
-  fields: z
-    .strictObject({
-      body: z.string().optional(),
-      description: z.string().optional(),
-      lastModified: z.string().optional(),
-      slug: z.string().optional(),
-      title: z.string().optional(),
-    })
-    .optional(),
-  /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
-  pollInterval: z.number().positive().optional(),
-  prefix: z.string().optional(),
-  projectId: z.string(),
-  /** GROQ query selecting the documents to import. */
-  query: z.string(),
-  type: z.literal("sanity"),
-});
-
-/** A Notion database; pages become entries, blocks become MDX. */
-const notionSourceSchema = z.object({
-  /** Max concurrent Notion API requests; default 3 (Notion's per-integration pace). */
-  concurrency: z.number().positive().optional(),
-  database: z.string(),
-  /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
-  pollInterval: z.number().positive().optional(),
-  prefix: z.string().optional(),
-  /** Notion property names mapped onto Blume meta. */
-  properties: z
-    .strictObject({
-      description: z.string().optional(),
-      order: z.string().optional(),
-      slug: z.string().optional(),
-      status: z.string().optional(),
-      title: z.string().optional(),
-    })
-    .optional(),
-  /** Status value treated as published; others map to `draft`. Default `Published`. */
-  publishedValue: z.string().optional(),
-  type: z.literal("notion"),
-});
-
-/**
- * An Obsidian vault, read in place. Wikilinks become route links and
- * `%%comments%%` are stripped at load time, so the vault stays the source of
- * truth — no export step and no generated notes in the repo.
- */
-const obsidianSourceSchema = z.strictObject({
-  /** Vault folder names to skip at any depth, in addition to dot-folders. */
-  exclude: z.array(z.string()).optional(),
-  /** Namespaces the source's routes under `/<prefix>/`; e.g. `vault`. */
-  prefix: z.string().optional(),
-  type: z.literal("obsidian"),
-  /** Vault directory, absolute or relative to the project root. */
-  vault: z.string().min(1),
-});
-
-/**
- * A repo's GitHub Releases, materialized as `type: changelog` entries — release
- * notes become the changelog with no files to maintain. A private repo reads a
- * token from `GITHUB_TOKEN`; it is never inlined here.
- */
-const githubReleasesSourceSchema = z.strictObject({
-  /** Include draft releases (needs a token with repo write access). */
-  drafts: z.boolean().optional(),
-  /** Cap the number of releases materialized, newest-first. Default 100. */
-  limit: z.number().positive().optional(),
-  /** Repository owner (user or org). */
-  owner: z.string(),
-  /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
-  pollInterval: z.number().positive().optional(),
-  /** Namespaces the source's routes under `/<prefix>/`; e.g. `changelog`. */
-  prefix: z.string().optional(),
-  /** Include prereleases. */
-  prereleases: z.boolean().optional(),
-  /** Repository name. */
-  repo: z.string(),
-  type: z.literal("github-releases"),
-});
-
-/**
- * A user-provided `ContentSource` instance, passed straight through from
- * `blume.config.ts`. This is the extension point that lets adapters with custom
- * serializers (or any backend) ship without their SDKs touching core.
- */
-const customSourceSchema = z.object({
-  source: z.custom<ContentSource>(
-    (val): val is ContentSource =>
-      typeof val === "object" &&
-      val !== null &&
-      "load" in val &&
-      typeof val.load === "function" &&
-      "name" in val &&
-      typeof val.name === "string",
-    { message: "custom source must be a ContentSource (with name + load)" }
-  ),
-  type: z.literal("custom"),
-});
-
-/** A single configured content source. */
-const contentSourceSchema = z.discriminatedUnion("type", [
-  filesystemSourceSchema,
-  mdxRemoteSourceSchema,
-  githubReleasesSourceSchema,
-  sanitySourceSchema,
-  notionSourceSchema,
-  obsidianSourceSchema,
-  customSourceSchema,
-]);
-
-/** A resolved content-source config entry (post-defaults). */
-export type ContentSourceConfig = z.infer<typeof contentSourceSchema>;
+/** A validated `content.sources` entry: an adapter descriptor from `blume/sources`. */
+export type { ContentSourceAdapter } from "../sources/registry.ts";
 
 /**
  * Per-type content definition. An object (rather than a bare frontmatter map)
@@ -471,24 +373,51 @@ const contentTypeConfigSchema = z.strictObject({
   frontmatter: customKeySchemaRecord("content.types"),
 });
 
-const contentConfigSchema = z.strictObject({
-  defaultType: z.string().default("doc"),
-  exclude: z.array(z.string()).default(["**/_*", "**/.*"]),
-  include: z.array(z.string()).default([DEFAULT_CONTENT_GLOB]),
-  pages: z.string().default("pages"),
-  root: z.string().default("docs"),
-  /**
-   * Pluggable content sources. When omitted, the top-level
-   * `root`/`include`/`exclude` desugar to one implicit filesystem source, so
-   * existing projects are unchanged.
-   */
-  sources: z.array(contentSourceSchema).optional(),
-  /**
-   * Per-type content definitions, keyed by the frontmatter `type` they apply
-   * to (including `defaultType`, for pages that set none).
-   */
-  types: z.record(z.string(), contentTypeConfigSchema).default({}),
-});
+/** The top-level fields that are shorthand for a single `filesystem()` source. */
+const FILESYSTEM_SHORTHAND_KEYS = ["exclude", "include", "root"] as const;
+
+/**
+ * `content`: where pages come from. `sources` lists adapters from
+ * `blume/sources`; the top-level `root`/`include`/`exclude` are zero-config
+ * shorthand that desugars to exactly one `filesystem()` entry when `sources`
+ * is absent, and are rejected beside it — so after parse, `sources` is the
+ * one source of truth and nothing downstream picks between the two.
+ */
+const contentConfigSchema = z
+  .strictObject({
+    defaultType: z.string().default("doc"),
+    exclude: z.array(z.string()).optional(),
+    include: z.array(z.string()).optional(),
+    pages: z.string().default("pages"),
+    root: z.string().optional(),
+    sources: contentSourcesSchema.optional(),
+    /**
+     * Per-type content definitions, keyed by the frontmatter `type` they apply
+     * to (including `defaultType`, for pages that set none).
+     */
+    types: z.record(z.string(), contentTypeConfigSchema).default({}),
+  })
+  .superRefine((value, ctx) => {
+    if (!value.sources) {
+      return;
+    }
+    for (const key of FILESYSTEM_SHORTHAND_KEYS) {
+      if (value[key] !== undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `content.${key} is shorthand for a single filesystem() source and can't be combined with content.sources — move it into a filesystem({ ${key} }) entry in content.sources.`,
+          path: [key],
+        });
+      }
+    }
+  })
+  .transform(({ exclude, include, root, sources, ...rest }) => ({
+    ...rest,
+    sources: sources ?? [
+      // The shorthand's defaults are the adapter's own, applied by its schema.
+      resolvedSourceAdapterSchema.parse(filesystem({ exclude, include, root })),
+    ],
+  }));
 
 /**
  * A header label that may localize: a plain string, or a map of locale code to
@@ -655,7 +584,7 @@ const perModeValueSchema = z
     isString(value) ? { dark: value, light: value } : value
   );
 
-const themeConfigSchema = z.strictObject({
+const themeConfigFields = {
   accent: z
     .union([
       z.string(),
@@ -675,58 +604,17 @@ const themeConfigSchema = z.strictObject({
       mono: fontValueSchema.default("ibm-plex-mono"),
     })
     .prefault({}),
-  layout: z.enum(["sidebar"]).default("sidebar"),
   mode: z.enum(["system", "light", "dark"]).default("system"),
   radius: z.enum(["none", "sm", "md", "lg"]).default("md"),
-});
-
-/** Public credentials for the Algolia search backend (sync key is an env var). */
-const algoliaSearchSchema = z.strictObject({
-  appId: z.string(),
-  indexName: z.string(),
-  searchApiKey: z.string(),
-});
-
-/** Public credentials for the Orama Cloud search backend. */
-const oramaCloudSearchSchema = z.strictObject({
-  apiKey: z.string(),
-  endpoint: z.string(),
-  /** Index id used by the build-time sync (with `ORAMA_PRIVATE_API_KEY`). */
-  indexId: z.string().optional(),
-});
-
-/** Public credentials for a (self-hosted or cloud) Typesense backend. */
-const typesenseSearchSchema = z.strictObject({
-  collection: z.string(),
-  host: z.string(),
-  port: z.number().int().positive().optional(),
-  protocol: z.enum(["http", "https"]).optional(),
-  searchApiKey: z.string(),
-});
-
-/** Mixedbread semantic search: the store the server endpoint queries. */
-const mixedbreadSearchSchema = z.strictObject({
-  storeId: z.string(),
-});
-
-export const searchProviders = [
-  "orama",
-  "pagefind",
-  "flexsearch",
-  "algolia",
-  "orama-cloud",
-  "typesense",
-  "mixedbread",
-  "none",
-] as const;
+};
 
-/** Providers that need a config block, mapped to its `search.*` key. */
-const PROVIDER_CONFIG_KEY = {
-  algolia: "algolia",
-  mixedbread: "mixedbread",
-  "orama-cloud": "oramaCloud",
-  typesense: "typesense",
-} as const;
+const themeConfigSchema = z.strictObject(
+  themeConfigFields,
+  removedKeysHint({
+    layout:
+      "theme.layout was removed: the sidebar layout is the only one, so delete the field.",
+  })
+);
 
 /** Curated link for the search dialog empty state (internal route or external URL). */
 const searchPopularLinkSchema = z.strictObject({
@@ -735,59 +623,82 @@ const searchPopularLinkSchema = z.strictObject({
   label: z.string(),
 });
 
-const searchConfigSchema = z
+/**
+ * The search backend: an adapter descriptor from `blume/search` (`algolia({…})`,
+ * `orama()`, …) or `false` to disable search. Resolves to a descriptor either
+ * way — `false` becomes the `none` adapter — so consumers read `kind`,
+ * `runtimeDeps`, and `requiredSecrets` without a special case.
+ */
+const searchProviderSchema = z
+  .custom<false | SearchAdapterInput>(
+    // A 1.x provider name (`"algolia"`, `"none"`) fails here with the adapter
+    // that replaces it, rather than the pipe's bare "expected object".
+    (value) => value === false || isObjectLike(value),
+    {
+      message:
+        'search.provider takes an adapter from "blume/search" — algolia({…}), pagefind(), … — not a provider name. The 1.x provider string was removed, and "none" is now `search: false`.',
+    }
+  )
+  .transform((value) => (value === false ? NONE_SEARCH_ADAPTER : value))
+  .pipe(resolvedSearchAdapterSchema);
+
+/** Indexing behavior shared by every source-built index. */
+const searchIndexingSchema = z
   .strictObject({
-    algolia: algoliaSearchSchema.optional(),
-    indexing: z
-      .strictObject({
-        includeCodeBlocks: z.boolean().default(false),
-        includeHiddenPages: z.boolean().default(false),
-      })
-      .prefault({}),
-    mixedbread: mixedbreadSearchSchema.optional(),
-    oramaCloud: oramaCloudSearchSchema.optional(),
+    includeCodeBlocks: z.boolean().default(false),
+    includeHiddenPages: z.boolean().default(false),
+  })
+  .prefault({});
+
+/** The object form of `search`: the adapter plus its adapter-independent settings. */
+const searchOptionsSchema = z.strictObject(
+  {
+    indexing: searchIndexingSchema,
     /** Curated links for the Cmd+K empty state; defaults to the first sidebar pages. */
     popular: z.array(searchPopularLinkSchema).default([]),
-    provider: z.enum(searchProviders).default("orama"),
-    typesense: typesenseSearchSchema.optional(),
+    provider: searchProviderSchema.default(() => orama()),
+  },
+  // The 1.x credential blocks, each now its adapter's options.
+  removedKeysHint({
+    algolia:
+      'search.algolia moved into its adapter: `search: algolia({ appId, indexName, apiKey })` from "blume/search", where the 1.x `searchApiKey` is now `apiKey`.',
+    mixedbread:
+      'search.mixedbread moved into its adapter: `search: mixedbread({ storeId })` from "blume/search".',
+    oramaCloud:
+      'search.oramaCloud moved into its adapter: `search: oramaCloud({ endpoint, apiKey, indexId })` from "blume/search".',
+    typesense:
+      'search.typesense moved into its adapter: `search: typesense({ host, collection, apiKey })` from "blume/search", where the 1.x `searchApiKey` is now `apiKey`.',
   })
-  .superRefine((value, ctx) => {
-    // Hosted providers can't work without their credentials; flag a missing
-    // block with a path so the diagnostic points at `search.<provider>`.
-    // SAFETY: providers without a config block (orama, pagefind, …) miss the
-    // map and read undefined, which the `field &&` guard below absorbs.
-    const field =
-      PROVIDER_CONFIG_KEY[value.provider as keyof typeof PROVIDER_CONFIG_KEY];
-    if (field && !value[field]) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: `search.${field} is required when provider is "${value.provider}".`,
-        path: [field],
-      });
-    }
-  });
+);
+
+type SearchOptionsInput = z.input<typeof searchOptionsSchema>;
+
+/** What `search` accepts: an adapter (or `false`) directly, or the object form. */
+type SearchConfigInput = false | SearchAdapterInput | SearchOptionsInput;
 
 /**
- * The `ai.ask.reasoning` levels: the AI SDK's top-level `reasoning` values
- * minus `provider-default`, which is what omitting the field means.
+ * `search` takes an adapter directly (`search: algolia({…})`, or `false`) as
+ * shorthand for the object form (`search: { provider: algolia({…}), popular,
+ * indexing }`). The shorthand is lifted into `provider` before the object
+ * schema validates, rather than through a union: a union reports whichever
+ * branch fails "softest", which for a descriptor missing an option is the
+ * object form's "unrecognized keys" — pointing at the wrong problem. A
+ * descriptor is recognized by its `kind`; the object form never has one.
  */
-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",
-  "openrouter",
-  "llmgateway",
-  "inkeep",
-  "openai-compatible",
-] as const;
+const searchConfigSchema = z
+  .custom<SearchConfigInput>(
+    // Anything else (a 1.x provider string, null, true) must become a
+    // diagnostic here: the `in` check below would throw a TypeError on it.
+    (value) => value === false || isObjectLike(value),
+    {
+      message:
+        'search must be an adapter from "blume/search" (orama(), algolia({…}), …), false, or { provider, popular, indexing }. The 1.x provider string was removed.',
+    }
+  )
+  .transform((value): SearchOptionsInput =>
+    value === false || "kind" in value ? { provider: value } : value
+  )
+  .pipe(searchOptionsSchema);
 
 /**
  * JWK parameters that carry private or secret key material (RFC 7518): the
@@ -833,7 +744,7 @@ const mcpConfigSchema = z.strictObject({
   route: z.string().default("/mcp").transform(normalizeRoute),
 });
 
-const askEndpointSchema = z
+const assistantEndpointSchema = z
   .string()
   .trim()
   .min(1)
@@ -851,11 +762,11 @@ const askEndpointSchema = z
     },
     {
       message:
-        "ai.ask.endpoint must be an HTTP(S) URL or a root-relative path.",
+        "ai.assistant.endpoint must be an HTTP(S) URL or a root-relative path.",
     }
   );
 
-/** The object form of `ai.llmsTxt`; a bare boolean normalizes onto it. */
+/** The object form of `agents.llmsTxt`; a bare boolean normalizes onto it. */
 const llmsTxtObjectSchema = z.strictObject({
   /**
    * Markdown inserted after the title and summary, before the page sections:
@@ -869,7 +780,7 @@ const llmsTxtObjectSchema = z.strictObject({
 
 type LlmsTxtResolved = z.output<typeof llmsTxtObjectSchema>;
 
-/** The object form of `ai.catalog`; a bare boolean normalizes onto it. */
+/** The object form of `agents.catalog`; a bare boolean normalizes onto it. */
 const aiCatalogObjectSchema = z.strictObject({
   enabled: z.boolean().default(true),
   /**
@@ -886,168 +797,104 @@ const aiCatalogObjectSchema = z.strictObject({
 
 type AiCatalogResolved = z.output<typeof aiCatalogObjectSchema>;
 
-const aiConfigSchema = z.strictObject({
-  /**
-   * The JSON docs API: the page index, per-page JSON, and navigation under
-   * `/api/docs/` (prerendered, so a static site serves them from files), the
-   * live search endpoint on server output, and the OpenAPI description of
-   * the whole machine-readable surface at `/openapi.json`. On by default.
-   */
-  api: z.boolean().default(true),
-  ask: z
-    .strictObject({
-      // Name of the env var holding the provider's API key; each provider has
-      // a sensible default, so this only needs setting to override it.
-      apiKeyEnv: z.string().optional(),
-      // 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
-      // paths are both valid; the built-in request/stream contract is unchanged.
-      endpoint: askEndpointSchema.optional(),
-      // Static request headers the generated endpoint sends the provider on
-      // every call (a caller-identifying header for a shared backend, say).
-      // Values are inlined into the generated route as literals, so the API
-      // key stays in `apiKeyEnv`; these are for non-secret metadata.
-      headers: z.record(z.string(), z.string()).optional(),
-      // Extra system-prompt text (identity, language, tone) appended to the
-      // built-in instructions, so the grounding contract — answer from the
-      // retrieved excerpts, cite pages as Markdown links — stays intact.
-      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
-      // user set reaches the generated (and ejected) endpoint, so omitted
-      // fields keep tracking the installed package's built-in defaults in
-      // `ai/ask-context.ts` instead of pinning today's numbers as literals.
-      retrieval: z
-        .strictObject({
-          contextBudget: z.number().int().positive().optional(),
-          excerptChars: z.number().int().positive().optional(),
-          maxResults: z.number().int().positive().optional(),
-        })
-        .optional(),
-      // Empty-state prompts shown before the first question. Each renders as a
-      // clickable suggestion; `icon` is an optional Lucide name beside it.
-      suggestions: z
-        .array(
-          z.strictObject({
-            icon: iconName.optional(),
-            label: z.string().min(1),
+/**
+ * The keys that moved from `ai` to `agents`: `ai` now holds only what faces a
+ * model at read time (the assistant, Open in chat), and the machine-readable surface
+ * agents consume lives under `agents`.
+ */
+const MOVED_TO_AGENTS = [
+  "api",
+  "catalog",
+  "llmsTxt",
+  "markdownComponents",
+  "mcp",
+  "skills",
+  "webBotAuth",
+  "webmcp",
+] as const;
+
+const movedToAgentsHints = (from: string): Record<string, string> =>
+  Object.fromEntries(
+    MOVED_TO_AGENTS.map((key) => [
+      key,
+      `${from}.${key} moved to agents.${key}.`,
+    ])
+  );
+
+/** Model-facing config: the assistant and the "Open in chat" action. */
+const aiConfigFields = {
+  assistant: z
+    .strictObject(
+      {
+        // 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 the assistant in an existing backend. Absolute URLs and root-relative
+        // paths are both valid; the built-in request/stream contract is unchanged.
+        endpoint: assistantEndpointSchema.optional(),
+        // Extra system-prompt text (identity, language, tone) appended to the
+        // built-in instructions, so the grounding contract — answer from the
+        // retrieved excerpts, cite pages as Markdown links — stays intact.
+        instructions: z.string().trim().min(1).optional(),
+        // The adapter descriptor a `gateway()`/`openrouter()`/... factory
+        // returns; each adapter validates its own options (model, key env var,
+        // reasoning mapping, `providerOptions` passthrough) in `ai/ask.ts`.
+        // Unset means the gateway with its default model, so the zero-config assistant
+        // is unchanged.
+        provider: assistantAdapterSchema.prefault(DEFAULT_ASSISTANT_PROVIDER),
+        // 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
+        // user set reaches the generated (and ejected) endpoint, so omitted
+        // fields keep tracking the installed package's built-in defaults in
+        // `ai/ask-context.ts` instead of pinning today's numbers as literals.
+        retrieval: z
+          .strictObject({
+            contextBudget: z.number().int().positive().optional(),
+            excerptChars: z.number().int().positive().optional(),
+            maxResults: z.number().int().positive().optional(),
           })
-        )
-        .default([]),
-    })
+          .optional(),
+        // Empty-state prompts shown before the first question. Each renders as a
+        // clickable suggestion; `icon` is an optional Lucide name beside it.
+        suggestions: z
+          .array(
+            z.strictObject({
+              icon: iconName.optional(),
+              label: z.string().min(1),
+            })
+          )
+          .default([]),
+      },
+      assistantMovedFieldsHint
+    )
     .superRefine((value, ctx) => {
-      // A generic OpenAI-compatible backend has no preset URL, so the user
-      // must supply one; the named providers fall back to their preset.
-      if (
-        value.provider === "openai-compatible" &&
-        !(value.baseUrl || value.endpoint)
-      ) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message:
-            'ai.ask.baseUrl is required when provider is "openai-compatible".',
-          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.",
+            "ai.assistant.cors only applies to the generated route; with ai.assistant.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
-   * both files (e.g. when the configured spec is example content) and
-   * `details`, free-form Markdown placed after the summary — the llms.txt
-   * spec's details block, where a site tells agents when to reach for it.
-   */
-  llmsTxt: z
-    .union([z.boolean(), llmsTxtObjectSchema])
-    .default(true)
-    .transform((value): LlmsTxtResolved =>
-      isBoolean(value) ? { enabled: value, openapi: true } : value
-    ),
-  // Serializers for the agent-facing Markdown downlevel (the `.md` mirror,
-  // llms-full.txt, MCP get_page), keyed by JSX name. Functions live here —
-  // not in components.tsx — because the config file is executed at build
-  // time while the components file is only statically analyzed. A same-name
-  // entry replaces the built-in serializer.
-  // Two-argument `z.record` — the single-argument form throws at
-  // schema-construction time under Zod 4 (see uiStringsOverrideSchema).
-  markdownComponents: z
-    .record(
-      z.string(),
-      z.custom<ComponentMarkdown>(
-        (value): value is ComponentMarkdown => typeof value === "function",
-        {
-          message: "Expected a serializer function.",
-        }
-      )
-    )
-    .default({}),
-  /** Expose the docs as an MCP server for connecting agents. */
-  mcp: mcpConfigSchema.prefault({}),
   /**
    * The "Open in chat" page action. `true` (the default) lists every
    * provider, `false` hides the action entirely, and an array of provider
@@ -1070,35 +917,15 @@ const aiConfigSchema = z.strictObject({
       }
       return value;
     }),
-  /**
-   * Publish Agent Skills for discovery: a directory (resolved against the
-   * project root) whose subdirectories each hold a `SKILL.md`. The build
-   * copies each skill under `/.well-known/agent-skills/` — a lone `SKILL.md`
-   * verbatim, a skill with supporting files as a `.tar.gz` — and emits the
-   * discovery index (`index.json`) with SHA-256 digests per the Agent Skills
-   * Discovery RFC.
-   */
-  skills: z.string().min(1).optional(),
-  /**
-   * Web Bot Auth (IETF `webbotauth`): publish the org's HTTP Message
-   * Signature public keys at `/.well-known/http-message-signatures-directory`
-   * so sites receiving requests from the org's agents can verify them.
-   * Opt-in and public-keys-only — the private keys live wherever the signing
-   * agents run, never in the site.
-   */
-  webBotAuth: z
-    .strictObject({
-      keys: z.array(publicJwkSchema).default([]),
-    })
-    .prefault({}),
-  /**
-   * WebMCP: register in-page tools (search, page Markdown, the docs index)
-   * on the browser's model context so agentic browsers can drive the docs
-   * without a separate MCP connection. A tiny script that no-ops in browsers
-   * without the API; on by default.
-   */
-  webmcp: z.boolean().default(true),
-});
+};
+
+const aiConfigSchema = z.strictObject(
+  aiConfigFields,
+  removedKeysHint({
+    ...movedToAgentsHints("ai"),
+    ask: "ai.ask was renamed to ai.assistant.",
+  })
+);
 
 /**
  * A pinned link rendered above the sidebar sections — a blog, changelog, or
@@ -1164,9 +991,11 @@ const navigationConfigSchema = z.strictObject({
   tabs: z.array(navTabSchema).default([]),
 });
 
-export type AskAiProvider = (typeof askAiProviders)[number];
-export type AskReasoning = (typeof askReasoningLevels)[number];
-export type AskAiConfig = NonNullable<z.infer<typeof aiConfigSchema>["ask"]>;
+export { assistantReasoningLevels } from "../ai/ask.ts";
+export type { AssistantReasoning } from "../ai/ask.ts";
+export type AssistantConfig = NonNullable<
+  z.infer<typeof aiConfigSchema>["assistant"]
+>;
 export { openInChatProviders } from "./open-in-chat.ts";
 export type { OpenInChatProvider } from "./open-in-chat.ts";
 
@@ -1316,57 +1145,28 @@ const versionsConfigSchema = z
     }
   });
 
-const analyticsScriptSchema = z
-  .strictObject({
-    // Extra attributes (e.g. `data-domain`, `id`) spread onto the <script>.
-    attributes: z.record(z.string(), z.string()).optional(),
-    // Inline script body, mutually exclusive with `src`.
-    content: z.string().optional(),
-    // External script URL, mutually exclusive with `content`.
-    src: z.string().optional(),
-    // Load strategy for an external script.
-    strategy: z.enum(["async", "defer"]).optional(),
-  })
-  .refine((value) => Boolean(value.src) !== Boolean(value.content), {
-    message: "An analytics script must set exactly one of `src` or `content`.",
-  });
-
-const analyticsConfigSchema = z.strictObject({
-  // Cloudflare Web Analytics in manual (JS snippet) mode; the token comes from
-  // the site's snippet in the dashboard. A zone Cloudflare proxies with
-  // automatic RUM injection on needs no config at all.
-  cloudflare: z
-    .strictObject({
-      token: z.string().min(1),
-    })
-    .optional(),
-  posthog: z
-    .strictObject({
-      host: z.string().optional(),
-      key: z.string(),
-    })
-    .optional(),
-  // Escape hatch for any other provider (Plausible, Fathom, GA, Umami, …).
-  scripts: z.array(analyticsScriptSchema).optional(),
-  vercel: z.boolean().optional(),
-});
+/**
+ * A pattern segment in a redirect path: a named `:param` segment or a `*`
+ * splat. `from` is matched as an exact path, and hosts disagree on patterns —
+ * a static build would even write a literal `:slug` folder — so both ends are
+ * checked. An absolute `to` URL's own scheme and host are skipped.
+ */
+const REDIRECT_PATTERN = /(?:^|\/):[A-Za-z_]|\*/u;
+const URL_ORIGIN = /^[a-z][\d+.a-z-]*:\/\/[^/]*/iu;
 
-const deploymentConfigSchema = z.strictObject({
-  adapter: z
-    .enum(["vercel", "node", "netlify", "cloudflare"])
-    .nullable()
-    .default(null),
-  base: z.string().optional(),
-  output: z.enum(["static", "server"]).default("static"),
-  site: z.url().optional(),
-});
+const exactRedirectPath = (end: "from" | "to") =>
+  z
+    .string()
+    .refine((path) => !REDIRECT_PATTERN.test(path.replace(URL_ORIGIN, "")), {
+      message: `redirects take exact paths: \`${end}\` can't hold a \`:param\` segment or a \`*\` wildcard. Add one redirect per path, or put pattern rules in your host's redirect config (vercel.json, _redirects).`,
+    });
 
 const redirectSchema = z.strictObject({
-  from: z.string(),
+  from: exactRedirectPath("from"),
   status: z
     .union([z.literal(301), z.literal(302), z.literal(307), z.literal(308)])
     .default(301),
-  to: z.string(),
+  to: exactRedirectPath("to"),
 });
 
 /**
@@ -1584,15 +1384,7 @@ const softwareConfigSchema = z.strictObject({
 type SoftwareResolved = z.output<typeof softwareConfigSchema>;
 
 /** Discoverability features: OG images, feeds, sitemap, structured data. */
-const seoConfigSchema = z.strictObject({
-  /**
-   * Emit `agent-readability.json` at the site root: a manifest that indexes
-   * the agent-facing surface (llms.txt, Markdown mirrors, MCP server, feeds)
-   * so agents can discover it without scraping HTML.
-   */
-  agentReadability: z.boolean().default(true),
-  /** robots.txt `Content-Signal` usage declaration (on by default). */
-  contentSignals: contentSignalsSchema.prefault(true),
+const seoConfigFields = {
   og: ogConfigSchema.default({}),
   /** The organization behind the site, as an `Organization` JSON-LD node. */
   organization: organizationConfigSchema.optional(),
@@ -1615,6 +1407,114 @@ const seoConfigSchema = z.strictObject({
   structuredData: z.boolean().default(true),
   /** X (Twitter) account attribution for share cards. */
   x: xConfigSchema.default({}),
+};
+
+const seoConfigSchema = z.strictObject(
+  seoConfigFields,
+  removedKeysHint({
+    agentReadability: "seo.agentReadability moved to agents.agentReadability.",
+    contentSignals: "seo.contentSignals moved to agents.contentSignals.",
+  })
+);
+
+/**
+ * The machine-readable surface agents consume: the JSON API, `llms.txt`, the
+ * MCP server, published skills, discovery manifests, and the robots.txt
+ * usage policy. Everything reader-facing that talks to a model (the assistant, Open
+ * in chat) stays under `ai`.
+ */
+const agentsConfigSchema = z.strictObject({
+  /**
+   * Emit `agent-readability.json` at the site root: a manifest that indexes
+   * the agent-facing surface (llms.txt, Markdown mirrors, MCP server, feeds)
+   * so agents can discover it without scraping HTML.
+   */
+  agentReadability: z.boolean().default(true),
+  /**
+   * The JSON docs API: the page index, per-page JSON, and navigation under
+   * `/api/docs/` (prerendered, so a static site serves them from files), the
+   * live search endpoint on server output, and the OpenAPI description of
+   * the whole machine-readable surface at `/openapi.json`. On by default.
+   */
+  api: z.boolean().default(true),
+  /**
+   * 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
+    ),
+  /** robots.txt `Content-Signal` usage declaration (on by default). */
+  contentSignals: contentSignalsSchema.prefault(true),
+  /**
+   * `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
+   * both files (e.g. when the configured spec is example content) and
+   * `details`, free-form Markdown placed after the summary — the llms.txt
+   * spec's details block, where a site tells agents when to reach for it.
+   */
+  llmsTxt: z
+    .union([z.boolean(), llmsTxtObjectSchema])
+    .default(true)
+    .transform((value): LlmsTxtResolved =>
+      isBoolean(value) ? { enabled: value, openapi: true } : value
+    ),
+  // Serializers for the agent-facing Markdown downlevel (the `.md` mirror,
+  // llms-full.txt, MCP get_page), keyed by JSX name. Functions live here —
+  // not in components.tsx — because the config file is executed at build
+  // time while the components file is only statically analyzed. A same-name
+  // entry replaces the built-in serializer.
+  // Two-argument `z.record` — the single-argument form throws at
+  // schema-construction time under Zod 4 (see uiStringsOverrideSchema).
+  markdownComponents: z
+    .record(
+      z.string(),
+      z.custom<ComponentMarkdown>(
+        (value): value is ComponentMarkdown => typeof value === "function",
+        {
+          message: "Expected a serializer function.",
+        }
+      )
+    )
+    .default({}),
+  /** Expose the docs as an MCP server for connecting agents. */
+  mcp: mcpConfigSchema.prefault({}),
+  /**
+   * Publish Agent Skills for discovery: a directory (resolved against the
+   * project root) whose subdirectories each hold a `SKILL.md`. The build
+   * copies each skill under `/.well-known/agent-skills/` — a lone `SKILL.md`
+   * verbatim, a skill with supporting files as a `.tar.gz` — and emits the
+   * discovery index (`index.json`) with SHA-256 digests per the Agent Skills
+   * Discovery RFC.
+   */
+  skills: z.string().min(1).optional(),
+  /**
+   * Web Bot Auth (IETF `webbotauth`): publish the org's HTTP Message
+   * Signature public keys at `/.well-known/http-message-signatures-directory`
+   * so sites receiving requests from the org's agents can verify them.
+   * Opt-in and public-keys-only — the private keys live wherever the signing
+   * agents run, never in the site.
+   */
+  webBotAuth: z
+    .strictObject({
+      keys: z.array(publicJwkSchema).default([]),
+    })
+    .prefault({}),
+  /**
+   * WebMCP: register in-page tools (search, page Markdown, the docs index)
+   * on the browser's model context so agentic browsers can drive the docs
+   * without a separate MCP connection. A tiny script that no-ops in browsers
+   * without the API; on by default.
+   */
+  webmcp: z.boolean().default(true),
 });
 
 /**
@@ -1691,10 +1591,6 @@ const codeBlockThemeSchema = z.strictObject({
   light: codeThemeSchema.default("github-light"),
 });
 
-const codeBlocksConfigSchema = z.strictObject({
-  theme: codeBlockThemeSchema.prefault({}),
-});
-
 /**
  * `<Component />` example previews. A string is shorthand for `{ source }`:
  * where examples live, relative to the project root (default `examples`).
@@ -1726,13 +1622,20 @@ const examplesConfigSchema = z
 
 /**
  * "Last updated" timestamps for content pages. `false` (default) disables the
- * feature; `true` derives each page's date from git history; an object selects
- * the source explicitly. A page's `lastModified` frontmatter always wins.
+ * feature; `"git"` derives each page's date from the repository history;
+ * `"frontmatter"` never runs git and reads only the page's own field. A page's
+ * `lastModified` frontmatter always wins. The 1.x `true` and `{ type }` forms
+ * fail with the hint below.
  */
-const lastModifiedConfigSchema = z.union([
-  z.boolean(),
-  z.strictObject({ type: z.enum(["git", "frontmatter"]).default("git") }),
-]);
+const lastModifiedConfigSchema = z.union(
+  [z.literal(false), z.enum(["git", "frontmatter"])],
+  {
+    error: (issue) =>
+      issue.code === "invalid_union"
+        ? 'lastModified takes false, "git", or "frontmatter": `true` became "git" and `{ type: "…" }` became the bare string.'
+        : undefined,
+  }
+);
 
 /**
  * How the "last updated" stamp and the changelog timeline render their dates —
@@ -1777,13 +1680,18 @@ const dateFormatConfigSchema = z
     }
   );
 
-/** Code-block rendering options (`markdown.code`). */
+/** Code rendering options (`markdown.code`). */
 const codeConfigSchema = z.strictObject({
   /**
    * Show a brand language icon in the code-block header (TypeScript, Python,
    * …). On by default; recognized languages only.
    */
   icons: z.boolean().default(true),
+  /**
+   * Light/dark Shiki themes for every code surface: fenced blocks, inline
+   * `` `code`{:lang} ``, `<CodeBlock>`, and `<Diff>`.
+   */
+  theme: codeBlockThemeSchema.prefault({}),
   /**
    * Wrap long lines instead of scrolling horizontally. Off by default, so
    * code keeps its original line breaks and overflows into a scroll area.
@@ -1791,10 +1699,17 @@ const codeConfigSchema = z.strictObject({
   wrap: z.boolean().default(false),
 });
 
-const markdownConfigSchema = z.strictObject({
-  /** Code-block rendering: language icons and line wrapping. */
+const markdownConfigFields = {
+  /** Code rendering: language icons, syntax themes, and line wrapping. */
   code: codeConfigSchema.prefault({}),
-  codeBlocks: codeBlocksConfigSchema.prefault({}),
+  /**
+   * Open external Markdown links (absolute `http(s)://` and `//host` URLs) in
+   * a new tab, like Blume's own header and sidebar links: `target="_blank"`,
+   * `rel="noreferrer"`, an arrow icon, and a screen-reader "Opens in a new
+   * tab" hint. Off by default; site routes, fragments, and `mailto:`/`tel:`
+   * links are never affected.
+   */
+  externalLinks: z.boolean().default(false),
   /**
    * Wrap each `##`–`######` heading in a link to its own anchor so readers can
    * click to copy, bookmark, or share a permalink to that section. On by
@@ -1806,176 +1721,27 @@ const markdownConfigSchema = z.strictObject({
    * opt a single image out with `data-no-zoom`.
    */
   imageZoom: z.boolean().default(true),
-});
+};
+
+const markdownConfigSchema = z.strictObject(
+  markdownConfigFields,
+  removedKeysHint({
+    codeBlocks:
+      "markdown.codeBlocks was merged into markdown.code: move theme: { light, dark } under markdown.code.",
+  })
+);
 
 /** React island behavior (`react`). */
 const reactConfigSchema = z.strictObject({
   /**
    * Auto-memoize React components/hooks with the React Compiler
    * (`babel-plugin-react-compiler`). On by default whenever React is enabled
-   * (a project `.tsx`/`.jsx`, a React island/example/override, or Ask AI); set
+   * (a project `.tsx`/`.jsx`, a React island/example/override, or the assistant); set
    * to `false` to skip the compiler's babel pass.
    */
   compiler: z.boolean().default(true),
 });
 
-/**
- * A single spec rendered by the API reference. `spec` is a local path or an
- * `http(s)` URL (an OpenAPI document under `openapi`, an AsyncAPI document
- * under `asyncapi`).
- */
-const openapiSourceSchema = z.strictObject({
-  /** Include generated pages from this spec in llms.txt/llms-full.txt. */
-  includeInLlms: z.boolean().default(true),
-  /** Include generated pages from this spec in site search. */
-  includeInSearch: z.boolean().default(true),
-  /** Nav/section label for this source. */
-  label: z.string().optional(),
-  /** Emit noindex metadata and omit generated pages from the sitemap. */
-  noindex: z.boolean().default(false),
-  /** Per-source route; defaults to the block's `route` (or a derived path). */
-  route: z.string().optional(),
-  /**
-   * Append the English "Reference for the … endpoint in the … API." sentence
-   * to every generated operation page's meta description. On by default, so
-   * terse specs still ship distinct, snippet-length descriptions; set to
-   * `false` on a non-English site to describe pages with the spec's own prose
-   * alone (falling back to the page title when an operation has none).
-   */
-  seoDescriptionSuffix: z.boolean().default(true),
-  /** Local path or `http(s)` URL to the spec. */
-  spec: z.string(),
-});
-
-export type OpenApiSource = z.input<typeof openapiSourceSchema>;
-
-/**
- * Arbitrary Scalar API-reference options forwarded verbatim to the generated
- * `<ScalarComponent>` (Scalar renderer only). A passthrough map — Blume doesn't
- * mirror Scalar's full config surface — so keys like `localization`, `agent`,
- * `hideTestRequestButton`, or `orderSchemaPropertiesBy` all flow through. These
- * take precedence over Blume's own derived config (spec, theme), so this is a
- * full escape hatch; the dedicated `theme` field is the ergonomic shorthand.
- */
-const scalarConfigSchema = z.record(z.string(), z.unknown()).optional();
-
-/**
- * The interactive "Try it" panel on operation pages (Blume renderer). On by
- * default; `false` hides it. The object form keeps it on and sets `proxy`,
- * the CORS escape hatch the Send button routes requests through: a proxy URL,
- * or `true` for the built-in `/_api-proxy` endpoint (which requires
- * `deployment.output: "server"`). Booleans normalize to the object shape so
- * consumers read `{ enabled, proxy }` directly. `proxy` applies to the
- * HTTP-posting playgrounds (OpenAPI, GraphQL) — an event composer's WebSocket
- * connect is direct. One schema for every reference block, so the
- * normalization can never drift between them.
- */
-const playgroundConfigSchema = z
-  .union([
-    z.boolean(),
-    z.strictObject({
-      enabled: z.boolean().default(true),
-      proxy: z.union([z.boolean(), z.string()]).default(false),
-    }),
-  ])
-  .default(true)
-  .transform((value) =>
-    isBoolean(value) ? { enabled: value, proxy: false } : value
-  );
-
-/**
- * The shared shape of the API-reference blocks — only the mount route and
- * code-sample defaults differ per spec kind, so each block declares just
- * those (the GraphQL block derives from this via omit/extend below).
- */
-const referenceConfigSchema = (defaults: {
-  codeSamples: string[];
-  route: string;
-}) =>
-  z.strictObject({
-    /** Code-sample languages/tools shown per operation (Blume renderer). */
-    codeSamples: z.array(z.string()).default(defaults.codeSamples),
-    enabled: z.boolean().default(false),
-    /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
-    expandSchemas: z.boolean().default(false),
-    /** The "Try it" panel; see {@link playgroundConfigSchema}. */
-    playground: playgroundConfigSchema,
-    /** Who renders the reference: Blume's own UI, or the embedded Scalar SPA. */
-    renderer: z.enum(["blume", "scalar"]).default("blume"),
-    /** Where the reference mounts. */
-    route: z.string().default(defaults.route),
-    /** Extra Scalar config forwarded to `<ScalarComponent>` (Scalar renderer only). */
-    scalar: scalarConfigSchema,
-    /** One or more specs; each renders on its own route by default. */
-    sources: z.array(openapiSourceSchema).default([]),
-    /** Shorthand for a single source: `sources: [{ spec }]`. */
-    spec: z.string().optional(),
-    /** Scalar theme name (Scalar renderer only). */
-    theme: z.string().optional(),
-  });
-
-/**
- * OpenAPI reference. By default (`renderer: "blume"`) Blume parses the spec with
- * Scalar's parser and renders its own UI: one real page per operation, grouped
- * by tag in the sidebar and included in site search, llms.txt, and OG. Set
- * `renderer: "scalar"` to fall back to the embedded Scalar SPA (a single
- * self-contained route that doesn't weave into the sidebar or search).
- */
-const openapiConfigSchema = referenceConfigSchema({
-  codeSamples: ["curl", "js", "python"],
-  route: "/reference",
-});
-
-/**
- * AsyncAPI reference. Same shape as {@link openapiConfigSchema}: by default
- * (`renderer: "blume"`) Blume normalizes the spec to AsyncAPI 3.x and renders
- * its own UI — one real page per operation — with `renderer: "scalar"` as the
- * embedded-SPA opt-out. Only the defaults differ: the reference mounts at
- * `/events`, and empty `codeSamples` means every tool the operation's protocol
- * binding suggests.
- */
-const asyncapiConfigSchema = referenceConfigSchema({
-  codeSamples: [],
-  route: "/events",
-});
-
-/**
- * A single GraphQL schema rendered by the reference. `spec` is a local path or
- * an `http(s)` URL to SDL text or an introspection JSON result; `endpoint` is
- * the live GraphQL API URL the playground and code samples target (a schema,
- * unlike an OpenAPI document, names no server).
- */
-const graphqlSourceSchema = openapiSourceSchema.extend({
-  /** URL of the live GraphQL endpoint (playground + code samples). */
-  endpoint: z.string().optional(),
-});
-
-export type GraphqlSource = z.input<typeof graphqlSourceSchema>;
-
-/**
- * GraphQL reference. Blume lowers the schema (SDL or introspection JSON) to
- * one real page per root field — grouped as Queries/Mutations/Subscriptions —
- * plus one page per named type (Objects, Input Objects, Enums, Interfaces,
- * Unions, Scalars), all included in the sidebar, search, llms.txt, and OG.
- * Always Blume-rendered: the Scalar SPA reads OpenAPI documents only, so the
- * block declares no `renderer`/`scalar`/`theme` escape hatches.
- */
-const graphqlConfigSchema = referenceConfigSchema({
-  codeSamples: ["curl", "js", "python"],
-  route: "/graphql",
-})
-  // No `renderer`/`scalar`/`theme` escape hatches (the Scalar SPA reads
-  // OpenAPI documents only) and no `expandSchemas` (GraphQL field tables have
-  // no nesting) — everything else, the playground normalization included, is
-  // the shared reference shape.
-  .omit({ expandSchemas: true, renderer: true, scalar: true, theme: true })
-  .extend({
-    /** Default live endpoint URL for every source (per-source `endpoint` wins). */
-    endpoint: z.string().optional(),
-    /** One or more schemas; each renders on its own route by default. */
-    sources: z.array(graphqlSourceSchema).default([]),
-  });
-
 /**
  * Opt-in custom frontmatter keys. `extend` maps each extra key a project's
  * pages may carry (e.g. `owner`, `reviewedAt`) to a validation schema; the
@@ -2025,60 +1791,77 @@ const tocConfigSchema = z
   });
 
 export const blumeConfigSchema = z
-  .strictObject({
-    ai: aiConfigSchema.prefault({}),
-    analytics: analyticsConfigSchema.optional(),
-    asyncapi: asyncapiConfigSchema.prefault({}),
-    banner: bannerConfigSchema.optional(),
-    /**
-     * Site-wide mount point prepended to every generated route (e.g. `/docs`),
-     * while staying invisible to the sidebar/nav tree. Distinct from a per-source
-     * `prefix` (which creates a group) and from `deployment.base` (Astro's
-     * host-subdirectory base); the two compose. Normalized to `""` or `/seg`.
-     */
-    basePath: z
-      .string()
-      .optional()
-      .transform((value) => normalizeBasePath(value)),
-    content: contentConfigSchema.prefault({}),
-    /**
-     * Date presentation for the "last updated" stamp and the changelog timeline.
-     * Pass-through `Intl.DateTimeFormat` options; defaults to `{ dateStyle: "long" }`.
-     */
-    dateFormat: dateFormatConfigSchema.default({ dateStyle: "long" }),
-    deployment: deploymentConfigSchema.prefault({}),
-    description: z.string().optional(),
-    /**
-     * Where `<Component path>` resolves live previews and their source from.
-     * A string is shorthand for `{ source }` — the directory (or glob, for
-     * colocated registry layouts) under the project root that holds example
-     * files. The object form adds `css`: a stylesheet injected into every
-     * preview frame (design tokens, shadcn variables, `@theme` mappings).
-     */
-    examples: examplesConfigSchema.prefault("examples"),
-    export: exportConfigSchema.prefault(false),
-    feedback: z.boolean().default(true),
-    /** Opt-in custom frontmatter keys, validated by user-supplied schemas. */
-    frontmatter: frontmatterConfigSchema.prefault({}),
-    github: githubConfigSchema.optional(),
-    graphql: graphqlConfigSchema.prefault({}),
-    i18n: i18nConfigSchema.optional(),
-    image: imageConfigSchema.prefault({}),
-    integrations: z.array(z.custom<AstroIntegration>()).default([]),
-    lastModified: lastModifiedConfigSchema.default(false),
-    logo: logoConfigSchema.optional(),
-    markdown: markdownConfigSchema.prefault({}),
-    navigation: navigationConfigSchema.prefault({}),
-    openapi: openapiConfigSchema.prefault({}),
-    react: reactConfigSchema.prefault({}),
-    redirects: z.array(redirectSchema).default([]),
-    search: searchConfigSchema.prefault({}),
-    seo: seoConfigSchema.prefault({}),
-    theme: themeConfigSchema.prefault({}),
-    title: z.string().default("Documentation"),
-    toc: tocConfigSchema,
-    versions: versionsConfigSchema.optional(),
-  })
+  .strictObject(
+    {
+      agents: agentsConfigSchema.prefault({}),
+      ai: aiConfigSchema.prefault({}),
+      // Adapters from `blume/analytics`, each a serializable descriptor.
+      analytics: analyticsConfigSchema,
+      banner: bannerConfigSchema.optional(),
+      /**
+       * Site-wide mount point prepended to every generated route (e.g. `/docs`),
+       * while staying invisible to the sidebar/nav tree. Distinct from a per-source
+       * `prefix` (which creates a group) and from `deployment.base` (Astro's
+       * host-subdirectory base); the two compose. Normalized to `""` or `/seg`.
+       */
+      basePath: z
+        .string()
+        .optional()
+        .transform((value) => normalizeBasePath(value)),
+      content: contentConfigSchema.prefault({}),
+      /**
+       * Date presentation for the "last updated" stamp and the changelog timeline.
+       * Pass-through `Intl.DateTimeFormat` options; defaults to `{ dateStyle: "long" }`.
+       */
+      dateFormat: dateFormatConfigSchema.default({ dateStyle: "long" }),
+      /**
+       * A host adapter from `blume/deploy` (`vercel()`, `netlify()`,
+       * `cloudflare()`, `node()`) for a server build on that host, or the plain
+       * `{ site, base }` form for a static build anywhere. Resolves to the
+       * adapter's descriptor with `output` filled in; `static` when unset.
+       */
+      deployment: resolvedDeploymentSchema.prefault({}),
+      description: z.string().optional(),
+      /**
+       * Where `<Component path>` resolves live previews and their source from.
+       * A string is shorthand for `{ source }` — the directory (or glob, for
+       * colocated registry layouts) under the project root that holds example
+       * files. The object form adds `css`: a stylesheet injected into every
+       * preview frame (design tokens, shadcn variables, `@theme` mappings).
+       */
+      examples: examplesConfigSchema.prefault("examples"),
+      export: exportConfigSchema.prefault(false),
+      feedback: z.boolean().default(true),
+      /** Opt-in custom frontmatter keys, validated by user-supplied schemas. */
+      frontmatter: frontmatterConfigSchema.prefault({}),
+      github: githubConfigSchema.optional(),
+      i18n: i18nConfigSchema.optional(),
+      image: imageConfigSchema.prefault({}),
+      integrations: z.array(z.custom<AstroIntegration>()).default([]),
+      lastModified: lastModifiedConfigSchema.default(false),
+      logo: logoConfigSchema.optional(),
+      markdown: markdownConfigSchema.prefault({}),
+      navigation: navigationConfigSchema.prefault({}),
+      react: reactConfigSchema.prefault({}),
+      redirects: z.array(redirectSchema).default([]),
+      /** API references: adapters from `blume/reference`, each a serializable descriptor. */
+      reference: referenceConfigSchema,
+      search: searchConfigSchema.prefault({}),
+      seo: seoConfigSchema.prefault({}),
+      theme: themeConfigSchema.prefault({}),
+      title: z.string().default("Documentation"),
+      toc: tocConfigSchema,
+      versions: versionsConfigSchema.optional(),
+    },
+    {
+      // The 1.x `openapi`/`asyncapi`/`graphql` blocks name the `reference` list
+      // that replaced them, alongside every other issue in the config.
+      error: (issue) =>
+        issue.code === "unrecognized_keys"
+          ? removedReferenceKeysHint(issue.keys)
+          : undefined,
+    }
+  )
   .superRefine((config, ctx) => {
     // A version id that is also a configured locale code would make a leading
     // `<id>/` directory ambiguous between the two axes — refuse it outright so
@@ -2150,8 +1933,8 @@ export type ArchivedVersionConfig = z.infer<typeof archivedVersionSchema>;
  * guard keeps structurally identical to this.
  */
 export type BlumeConfigInput = z.input<typeof blumeConfigSchema>;
-/** A configured search backend. */
-export type SearchProvider = (typeof searchProviders)[number];
+/** The resolved search backend: an adapter descriptor, or `none`. */
+export type { ResolvedSearchAdapter } from "../search/adapters/registry.ts";
 /** Resolved robots.txt `Content-Signal` preferences (`null` when disabled). */
 export type ContentSignals = z.infer<typeof contentSignalsSchema>;
 /** The resolved per-signal policy object (present when signals are enabled). */