blume 1.7.3 → 2.0.0

package/src/core/config-input.ts

@@ -2,19 +2,21 @@ import type { AstroIntegration } from "astro";
 import type { z } from "zod";
 
 import type { AskRetrievalOptions } from "../ai/ask-context.ts";
+import type { AskAdapter } from "../ai/ask.ts";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import type { AnalyticsAdapter } from "../analytics/schema.ts";
+import type { DeploymentInput } from "../deploy/adapters/registry.ts";
 import type { CodeTheme } from "../markdown/themes.ts";
+import type { ReferenceAdapter } from "../reference/schema.ts";
+import type { AnySearchAdapter } from "../search/adapters/registry.ts";
+import type { SourceAdapterInput } from "../sources/registry.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type {
   blumeConfigSchema,
-  GraphqlSource,
-  OpenApiSource,
   OpenInChatProvider,
-  SearchProvider,
   SidebarDisplay,
   SidebarItemConfig,
 } from "./schema.ts";
-import type { ContentSource } from "./sources/types.ts";
 import type { StandardSchema } from "./standard-schema.ts";
 
 /**
@@ -105,191 +107,34 @@ export type BannerConfig =
       };
     };
 
-// ---------------------------------------------------------------------------
-// Content sources
-// ---------------------------------------------------------------------------
-
-/** Local Markdown/MDX read from the filesystem. */
-export interface FilesystemSource {
-  type: "filesystem";
-  /** Glob patterns to ignore. Defaults to `["**\/_*", "**\/.*"]`. */
-  exclude?: string[];
-  /** Glob patterns to include. Defaults to `["**\/*.{md,mdx}"]`. */
-  include?: string[];
-  /** Namespaces this source's routes under `/<prefix>/`. */
-  prefix?: string;
-  /** Directory to read from, relative to the project root. Defaults to `docs`. */
-  root?: string;
-}
-
-/**
- * Remote Markdown/MDX fetched over HTTP. Enumerate files explicitly against a
- * raw `url` base, or from a GitHub repo subtree via `github`. A private repo's
- * token comes from `GITHUB_TOKEN` — never inline it here.
- */
-export interface MdxRemoteSource {
-  type: "mdx-remote";
-  /** Explicit list of source-relative file paths to fetch from `url`. */
-  files?: string[];
-  /** Enumerate a GitHub repo subtree via the git-trees API. */
-  github?: {
-    /** Repository owner (user or org). */
-    owner: string;
-    /** Subpath within the repo. Defaults to the repo root. */
-    path?: string;
-    /** Git ref (branch, tag, or SHA). Defaults to `main`. */
-    ref?: string;
-    /** Repository name. */
-    repo: string;
-  };
-  /** Glob patterns applied to enumerated refs. Defaults to `["**\/*.{md,mdx}"]`. */
-  include?: string[];
-  /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
-  pollInterval?: number;
-  /** Namespaces this source's routes under `/<prefix>/`. */
-  prefix?: string;
-  /** Raw base URL, e.g. `https://raw.githubusercontent.com/acme/sdk/main/docs`. */
-  url?: string;
-}
-
-/**
- * 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`; never inline it here.
- */
-export interface GithubReleasesSource {
-  type: "github-releases";
-  /** Include draft releases (needs a token with repo write access). */
-  drafts?: boolean;
-  /** Cap the number of releases materialized, newest-first. Defaults to 100. */
-  limit?: number;
-  /** Repository owner (user or org). */
-  owner: string;
-  /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
-  pollInterval?: number;
-  /** Namespaces this source's routes under `/<prefix>/`; e.g. `changelog`. */
-  prefix?: string;
-  /** Include prereleases. */
-  prereleases?: boolean;
-  /** Repository name. */
-  repo: string;
-}
-
-/** A Sanity dataset queried with GROQ; Portable Text bodies become Markdown. */
-export interface SanitySource {
-  type: "sanity";
-  /** Sanity API version (a date). Defaults to `2024-01-01`. */
-  apiVersion?: string;
-  /** Dataset name to query. */
-  dataset: string;
-  /** Field paths mapping a document onto Blume meta + body. */
-  fields?: {
-    /** Field holding the renderable body (Portable Text or Markdown). */
-    body?: string;
-    /** Field holding the page description. */
-    description?: string;
-    /** Field holding the last-modified date. */
-    lastModified?: string;
-    /** Field holding the page slug. */
-    slug?: string;
-    /** Field holding the page title. */
-    title?: string;
-  };
-  /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
-  pollInterval?: number;
-  /** Namespaces this source's routes under `/<prefix>/`. */
-  prefix?: string;
-  /** Sanity project id. */
-  projectId: string;
-  /** GROQ query selecting the documents to import. */
-  query: string;
-}
-
-/** A Notion database; pages become entries, blocks become MDX. */
-export interface NotionSource {
-  type: "notion";
-  /** Max concurrent Notion API requests; default 3 (Notion's per-integration pace). */
-  concurrency?: number;
-  /** Notion database id. */
-  database: string;
-  /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
-  pollInterval?: number;
-  /** Namespaces this source's routes under `/<prefix>/`. */
-  prefix?: string;
-  /** Notion property names mapped onto Blume meta. */
-  properties?: {
-    /** Property holding the page description. */
-    description?: string;
-    /** Property holding the sort order. */
-    order?: string;
-    /** Property holding the page slug. */
-    slug?: string;
-    /** Property holding the publish status. */
-    status?: string;
-    /** Property holding the page title. */
-    title?: string;
-  };
-  /** Status value treated as published; others map to `draft`. Defaults to `Published`. */
-  publishedValue?: string;
-}
-
-/**
- * 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.
- */
-export interface ObsidianSource {
-  type: "obsidian";
-  /** Vault folder names to skip at any depth, in addition to dot-folders. */
-  exclude?: string[];
-  /** Namespaces this source's routes under `/<prefix>/`; e.g. `vault`. */
-  prefix?: string;
-  /** Vault directory, absolute or relative to the project root. */
-  vault: string;
-}
-
-/**
- * A user-provided {@link ContentSource} instance, passed straight through. This
- * is the extension point for adapters with custom serializers or any other
- * backend, without their SDKs touching core.
- */
-export interface CustomSource {
-  type: "custom";
-  /** A `ContentSource` implementation (an object with `name` + `load`). */
-  source: ContentSource;
-}
-
-/** A single configured content source, discriminated by `type`. */
-export type ContentSourceInput =
-  | FilesystemSource
-  | MdxRemoteSource
-  | GithubReleasesSource
-  | SanitySource
-  | NotionSource
-  | ObsidianSource
-  | CustomSource;
-
 /**
- * Where content lives and how it's discovered. When `sources` is omitted, the
- * top-level `root`/`include`/`exclude` desugar to one implicit filesystem
- * source, so simple sites need nothing here.
+ * Where content lives and how it's discovered. `root`/`include`/`exclude` are
+ * zero-config shorthand for a single `filesystem()` source; set `sources` to
+ * compose adapters instead, and move those fields into its `filesystem()`
+ * entry — the two forms can't be combined.
  */
 export interface ContentConfig {
   /** Default page `type` for content that sets none. Defaults to `doc`. */
   defaultType?: string;
-  /** Glob patterns to ignore. Defaults to `["**\/_*", "**\/.*"]`. */
+  /** Glob patterns to ignore. Defaults to `["**\/_*", "**\/.*"]`. Shorthand; not allowed beside `sources`. */
   exclude?: string[];
-  /** Glob patterns to include. Defaults to `["**\/*.{md,mdx}"]`. */
+  /** Glob patterns to include. Defaults to `["**\/*.{md,mdx}"]`. Shorthand; not allowed beside `sources`. */
   include?: string[];
   /** Directory of standalone `pages` (outside the docs tree). Defaults to `pages`. */
   pages?: string;
-  /** Content root directory, relative to the project root. Defaults to `docs`. */
+  /** Content root directory, relative to the project root. Defaults to `docs`. Shorthand; not allowed beside `sources`. */
   root?: string;
   /**
-   * Pluggable content sources. Mix local files with remote MDX, GitHub
-   * Releases, Sanity, Notion, or a custom `ContentSource`.
+   * Content source adapters from `blume/sources`, read in order:
+   * `filesystem({ root })`, `mdxRemote({ github })`, `githubReleases({ owner,
+   * repo })`, `sanity({ projectId, dataset, query })`, `notion({ database })`,
+   * `contentful({ space, contentType })`, `payload({ url, collection })`,
+   * `strapi({ url, contentType })`, `obsidian({ vault })`, or `custom(source)`
+   * for any `ContentSource`
+   * implementation. When set it replaces the implicit filesystem source, so
+   * list a `filesystem()` entry for local docs.
    */
-  sources?: ContentSourceInput[];
+  sources?: SourceAdapterInput[];
   /**
    * Per-type content definitions, keyed by the frontmatter `type` they apply
    * to (including `defaultType`, for pages that set none):
@@ -564,7 +409,7 @@ type RadiusScale = RadiusScaleTight | RadiusScaleRound;
 
 export interface ThemeConfig {
   /**
-   * Accent color. A palette name (`blue`, `violet`, `green`, …) or any CSS
+   * Accent color. A palette name (`blue`, `purple`, `green`, …) or any CSS
    * color applies to both modes; the object form sets each mode. Defaults to
    * `blue`.
    */
@@ -577,8 +422,6 @@ export interface ThemeConfig {
   backgroundImage?: PerModeValue;
   /** Font selection for body, display, and mono roles. */
   fonts?: FontsConfig;
-  /** Overall page layout. Currently only `sidebar`. */
-  layout?: "sidebar";
   /** Initial color mode. Defaults to `system`. */
   mode?: "system" | "light" | "dark";
   /** Corner radius scale. Defaults to `md`. */
@@ -589,35 +432,6 @@ export interface ThemeConfig {
 // Search
 // ---------------------------------------------------------------------------
 
-/** Public credentials for the Algolia backend (the sync key stays an env var). */
-export interface AlgoliaSearch {
-  appId: string;
-  indexName: string;
-  searchApiKey: string;
-}
-
-/** Public credentials for the Orama Cloud backend. */
-export interface OramaCloudSearch {
-  apiKey: string;
-  endpoint: string;
-  /** Index id used by the build-time sync (with `ORAMA_PRIVATE_API_KEY`). */
-  indexId?: string;
-}
-
-/** Connection details for a self-hosted or cloud Typesense backend. */
-export interface TypesenseSearch {
-  collection: string;
-  host: string;
-  port?: number;
-  protocol?: "http" | "https";
-  searchApiKey: string;
-}
-
-/** Mixedbread semantic search: the store the server endpoint queries. */
-export interface MixedbreadSearch {
-  storeId: string;
-}
-
 /** A curated link for the search dialog empty state. */
 export interface SearchPopularLink {
   /** Internal route or external URL. */
@@ -632,13 +446,17 @@ export interface SearchPopularLink {
 }
 
 /**
- * Search backend. The default `orama` builds a local index at build time (and
- * runs in dev); hosted providers need their credential block below. `none`
- * disables search.
+ * The search backend: an adapter from `blume/search` — `orama()` (the
+ * default), `flexsearch()`, `pagefind()`, `algolia({…})`, `oramaCloud({…})`,
+ * `typesense({…})`, `mixedbread({…})` — or `false` to disable search. Each
+ * adapter is a plain descriptor carrying its own options, runtime dependency,
+ * and required secrets; hosted adapters take public credentials only and read
+ * their admin keys from the environment.
  */
-export interface SearchConfig {
-  /** Algolia credentials (required when `provider` is `algolia`). */
-  algolia?: AlgoliaSearch;
+export type SearchProviderConfig = AnySearchAdapter | false;
+
+/** The object form of `search`: the adapter plus adapter-independent settings. */
+export interface SearchOptions {
   /** Indexing behavior. */
   indexing?: {
     /**
@@ -650,21 +468,22 @@ export interface SearchConfig {
     /** Include pages marked `hidden` in the search index. Defaults to `false`. */
     includeHiddenPages?: boolean;
   };
-  /** Mixedbread store (required when `provider` is `mixedbread`). */
-  mixedbread?: MixedbreadSearch;
-  /** Orama Cloud credentials (required when `provider` is `orama-cloud`). */
-  oramaCloud?: OramaCloudSearch;
   /**
    * Curated links for the Cmd+K empty state. When omitted or empty, the first
    * sidebar pages are shown instead.
    */
   popular?: SearchPopularLink[];
-  /** Which backend powers search. Defaults to `orama`. */
-  provider?: SearchProvider;
-  /** Typesense credentials (required when `provider` is `typesense`). */
-  typesense?: TypesenseSearch;
+  /** Which adapter powers search. Defaults to `orama()`. */
+  provider?: SearchProviderConfig;
 }
 
+/**
+ * Search configuration. Pass an adapter directly (`search: algolia({…})`, or
+ * `false`) as shorthand for the object form, which also carries `popular`
+ * links and `indexing` settings.
+ */
+export type SearchConfig = SearchProviderConfig | SearchOptions;
+
 // ---------------------------------------------------------------------------
 // AI
 // ---------------------------------------------------------------------------
@@ -677,13 +496,6 @@ export interface AskSuggestion {
   label: string;
 }
 
-/** The Ask AI chat assistant. */
-/** Backends that can route an Ask AI request. */
-type AskProviderGateway = "gateway" | "openrouter" | "llmgateway";
-type AskProvider = AskProviderGateway | "inkeep" | "openai-compatible";
-/** How much the model reasons before answering (`ai.ask.reasoning`). */
-type AskReasoning = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
-
 /** How much retrieved documentation each Ask AI question carries. */
 export interface AskRetrievalConfig {
   /**
@@ -706,17 +518,8 @@ export interface AskRetrievalConfig {
   maxResults?: number;
 }
 
+/** The Ask AI chat assistant. */
 export interface AskConfig {
-  /**
-   * Name of the env var holding the provider API key. Each provider has a
-   * sensible default; set this only to override it.
-   */
-  apiKeyEnv?: string;
-  /**
-   * Backend base URL. Required for `openai-compatible`; for named providers it
-   * overrides the built-in preset.
-   */
-  baseUrl?: string;
   /**
    * Origins allowed to call the generated endpoint from another site — a
    * marketing page that embeds an ask box, for example — or `"*"` to allow
@@ -737,35 +540,22 @@ export interface AskConfig {
    * limiting, and streaming. Accepts an absolute URL or root-relative path.
    */
   endpoint?: string;
-  /**
-   * Static request headers sent to the provider on every call — a
-   * caller-identifying header for a shared backend, for example. Values are
-   * written into the generated route as literals, so keep secrets in
-   * `apiKeyEnv` rather than here.
-   */
-  headers?: Record<string, string>;
   /**
    * Extra system-prompt text appended to the built-in instructions — use it
    * for identity, language, or tone. The built-in grounding behavior (answer
    * from the retrieved excerpts, cite pages as Markdown links) is preserved.
    */
   instructions?: string;
-  /** Model id to use. Defaults to `openai/gpt-5.5`. */
-  model?: string;
-  /** Which backend routes the request. Defaults to `gateway`. */
-  provider?: AskProvider;
   /**
-   * How much the model reasons before answering, from `"none"` to `"xhigh"`.
-   * Sent as the backend's own reasoning-effort control: the AI SDK's
-   * `reasoning` option on the gateway, `reasoning.effort` on OpenRouter, and
-   * `reasoning_effort` on OpenAI-compatible endpoints. The model has to
-   * support the level — OpenAI rejects one a model doesn't offer — and the
-   * endpoint has to accept the parameter; Inkeep has no reasoning control,
-   * so the field is rejected there. Omitted keeps the model's default.
-   * `"none"` is the fastest and cheapest for grounded docs Q&A, where the
-   * retrieved excerpts carry the answer.
+   * Which backend answers: the descriptor an adapter factory returns —
+   * `gateway({ model })`, `openrouter({ model, reasoning })`,
+   * `llmgateway({ model })`, `inkeep({ model })`, or
+   * `openaiCompatible({ baseUrl, name, model, apiKeyEnv })`, all exported
+   * from `blume/ai`. Each adapter owns its model, key env var, reasoning
+   * mapping, and `providerOptions` passthrough. Defaults to
+   * `gateway({ model: "openai/gpt-5.5" })`.
    */
-  reasoning?: AskReasoning;
+  provider?: AskAdapter;
   /**
    * How much documentation each question carries into the model's prompt.
    * Lower values cut time-to-first-token — which dominates on a self-hosted
@@ -789,7 +579,7 @@ export interface AiCatalogConfig {
    * registries embed for semantic search.
    *
    * ```ts
-   * ai: {
+   * agents: {
    *   catalog: {
    *     queries: {
    *       "mcp:acme": ["how do I install Acme", "search the Acme docs"],
@@ -811,7 +601,7 @@ export interface LlmsTxtConfig {
    * dropped.
    *
    * ```ts
-   * ai: {
+   * agents: {
    *   llmsTxt: {
    *     details: "## When to use Acme\n\nUse Acme when…",
    *   },
@@ -841,59 +631,10 @@ export interface McpConfig {
   route?: string;
 }
 
-/**
- * AI-facing features: the Ask AI assistant, an `llms.txt` manifest, and the
- * hosted MCP server.
- */
+/** Model-facing features: the Ask AI assistant and the "Open in chat" action. */
 export interface AiConfig {
-  /**
-   * The JSON docs API — the REST twin of the MCP tools. Serves the page index
-   * (`/api/docs/pages.json`), each page as JSON (`/api/docs/pages/{route}.json`),
-   * and the navigation tree (`/api/docs/navigation.json`) as prerendered
-   * files, plus full-text search (`/api/docs/search?q=`) on server output,
-   * all described by an OpenAPI document at `/openapi.json`. Errors are RFC
-   * 9457 problem details. Defaults to `true`; set `false` to publish none of it.
-   */
-  api?: boolean;
   /** The Ask AI chat assistant. */
   ask?: AskConfig;
-  /**
-   * The AI Catalog / ARD manifest (`/.well-known/ai-catalog.json`, mirrored
-   * at `/.well-known/ard.json`): a domain-level index of the agent-facing
-   * resources the site publishes — MCP server, agent skills, the JSON docs
-   * API, API references, llms.txt — for agent registries. Needs a
-   * `deployment.site`. Defaults to `true`; the object form overrides the
-   * generated representative queries per entry.
-   */
-  catalog?: boolean | AiCatalogConfig;
-  /**
-   * Emit `llms.txt` (an index of the docs for LLMs). Defaults to `true`.
-   * The object form adds knobs for what the files include.
-   */
-  llmsTxt?: boolean | LlmsTxtConfig;
-  /**
-   * Markdown serializers for custom components in agent-facing output (the
-   * `.md` mirror, `llms-full.txt`, MCP `get_page`), keyed by JSX name. Each
-   * receives the component's statically-evaluated `props` (with the page's
-   * `frontmatter` in scope, so `prop={frontmatter.status}` resolves), its
-   * downleveled `children`, and the page's `frontmatter` data, and returns
-   * replacement Markdown — or `null` to leave the JSX verbatim. A same-name
-   * entry replaces a built-in serializer.
-   *
-   * These live in `blume.config.ts` (which is executed at build time), not in
-   * `components.tsx` (which is only statically analyzed, never run).
-   *
-   * ```ts
-   * ai: {
-   *   markdownComponents: {
-   *     Chart: ({ props }) => `![${props.title}](/charts/${props.slug}.png)`,
-   *   },
-   * }
-   * ```
-   */
-  markdownComponents?: Record<string, ComponentMarkdown>;
-  /** Expose the docs as an MCP server for agents. */
-  mcp?: McpConfig;
   /**
    * The "Open in chat" page action, which opens the current page in an AI
    * assistant pre-filled with a prompt pointing at its raw Markdown.
@@ -907,34 +648,6 @@ export interface AiConfig {
    * ```
    */
   openInChat?: boolean | OpenInChatProvider[];
-  /**
-   * Publish Agent Skills for discovery: a directory (resolved against the
-   * project root) whose subdirectories each hold a `SKILL.md`. Skills are
-   * copied under `/.well-known/agent-skills/` — single-file skills verbatim,
-   * skills with supporting resources as `.tar.gz` archives — and enumerated
-   * in a discovery index with SHA-256 digests (Agent Skills Discovery RFC).
-   *
-   * ```ts
-   * ai: {
-   *   skills: "./skills",
-   * }
-   * ```
-   */
-  skills?: string;
-  /**
-   * Web Bot Auth: publish the org's HTTP Message Signature public keys at
-   * `/.well-known/http-message-signatures-directory`, so sites receiving
-   * requests from your agents can verify them. Public keys only — a key
-   * containing private material (`d`, `p`, `q`, …) is rejected.
-   */
-  webBotAuth?: WebBotAuthConfig;
-  /**
-   * 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. The script is tiny and no-ops in
-   * browsers without the API. Defaults to `true`; set `false` to opt out.
-   */
-  webmcp?: boolean;
 }
 
 /** Web Bot Auth signature directory. Off until at least one key is listed. */
@@ -944,47 +657,6 @@ export interface WebBotAuthConfig {
   keys?: Record<string, unknown>[];
 }
 
-// ---------------------------------------------------------------------------
-// Analytics
-// ---------------------------------------------------------------------------
-
-/** An arbitrary analytics `<script>`; set exactly one of `src` or `content`. */
-export interface AnalyticsScript {
-  /** Extra attributes spread onto the `<script>` (e.g. `data-domain`, `id`). */
-  attributes?: Record<string, string>;
-  /** Inline script body. Mutually exclusive with `src`. */
-  content?: string;
-  /** External script URL. Mutually exclusive with `content`. */
-  src?: string;
-  /** Load strategy for an external script. */
-  strategy?: "async" | "defer";
-}
-
-/** Analytics providers. Configure one, several, or none. */
-export interface AnalyticsConfig {
-  /**
-   * Cloudflare Web Analytics, for a site Cloudflare doesn't proxy (manual
-   * setup). Not needed on a proxied zone with automatic RUM enabled — that
-   * injects the beacon at the edge, and configuring it here too would count
-   * every pageview twice.
-   */
-  cloudflare?: {
-    /** Site token from the Web Analytics JS snippet (`data-cf-beacon`). */
-    token: string;
-  };
-  /** PostHog product analytics. */
-  posthog?: {
-    /** API host (for self-hosted / EU). Defaults to PostHog cloud. */
-    host?: string;
-    /** Project API key. */
-    key: string;
-  };
-  /** Escape hatch for any other provider (Plausible, Fathom, GA, Umami, …). */
-  scripts?: AnalyticsScript[];
-  /** Enable Vercel Web Analytics. */
-  vercel?: boolean;
-}
-
 // ---------------------------------------------------------------------------
 // i18n
 // ---------------------------------------------------------------------------
@@ -1086,26 +758,14 @@ export interface VersionsConfig {
 // ---------------------------------------------------------------------------
 
 /**
- * Where and how the site deploys. `site` (and `adapter`) are auto-detected from
- * the platform env on Vercel, Netlify, and Cloudflare.
+ * Where and how the site deploys: a host adapter from `blume/deploy` —
+ * `vercel()`, `netlify()`, `cloudflare()`, `node()`, each taking `{ output,
+ * site, base }` plus the underlying `@astrojs/*` adapter's own options — for
+ * a server build on that host, or the plain `{ site, base }` form for a
+ * static build anywhere. `site` is detected from the platform env on Vercel,
+ * Netlify, and Cloudflare Pages when unset.
  */
-/** Astro server-output adapters, by hosting platform. */
-type CloudDeploymentAdapter = "netlify" | "cloudflare";
-type DeploymentAdapter = "vercel" | "node" | CloudDeploymentAdapter;
-
-export interface DeploymentConfig {
-  /** Astro adapter for server output. `null` (default) keeps a static build. */
-  adapter?: DeploymentAdapter | null;
-  /** Base path when the site is served from a subdirectory. */
-  base?: string;
-  /** Build output mode. Defaults to `static`. */
-  output?: "static" | "server";
-  /**
-   * Canonical site URL. Needed for absolute links, the sitemap, and OG images;
-   * auto-detected on supported platforms.
-   */
-  site?: string;
-}
+export type DeploymentConfig = DeploymentInput;
 
 /**
  * One authorized remote image source, passed through to Astro's
@@ -1170,6 +830,96 @@ export type ContentSignalsConfig =
       search?: boolean;
     };
 
+/**
+ * The machine-readable surface agents consume: the JSON API, `llms.txt`, the
+ * MCP server, published skills, discovery manifests, and the robots.txt usage
+ * policy. The reader-facing model features (Ask AI, Open in chat) live under
+ * `ai`.
+ */
+export interface AgentsConfig {
+  /**
+   * Emit `agent-readability.json`: a manifest indexing the agent-facing surface
+   * (llms.txt, Markdown mirrors, MCP, feeds). Defaults to `true`.
+   */
+  agentReadability?: boolean;
+  /**
+   * The JSON docs API — the REST twin of the MCP tools. Serves the page index
+   * (`/api/docs/pages.json`), each page as JSON (`/api/docs/pages/{route}.json`),
+   * and the navigation tree (`/api/docs/navigation.json`) as prerendered
+   * files, plus full-text search (`/api/docs/search?q=`) on server output,
+   * all described by an OpenAPI document at `/openapi.json`. Errors are RFC
+   * 9457 problem details. Defaults to `true`; set `false` to publish none of it.
+   */
+  api?: boolean;
+  /**
+   * The AI Catalog / ARD manifest (`/.well-known/ai-catalog.json`, mirrored
+   * at `/.well-known/ard.json`): a domain-level index of the agent-facing
+   * resources the site publishes — MCP server, agent skills, the JSON docs
+   * API, API references, llms.txt — for agent registries. Needs a
+   * `deployment.site`. Defaults to `true`; the object form overrides the
+   * generated representative queries per entry.
+   */
+  catalog?: boolean | AiCatalogConfig;
+  /** robots.txt `Content-Signal` usage declaration. Defaults to `true`. */
+  contentSignals?: ContentSignalsConfig;
+  /**
+   * Emit `llms.txt` (an index of the docs for LLMs). Defaults to `true`.
+   * The object form adds knobs for what the files include.
+   */
+  llmsTxt?: boolean | LlmsTxtConfig;
+  /**
+   * Markdown serializers for custom components in agent-facing output (the
+   * `.md` mirror, `llms-full.txt`, MCP `get_page`), keyed by JSX name. Each
+   * receives the component's statically-evaluated `props` (with the page's
+   * `frontmatter` in scope, so `prop={frontmatter.status}` resolves), its
+   * downleveled `children`, and the page's `frontmatter` data, and returns
+   * replacement Markdown — or `null` to leave the JSX verbatim. A same-name
+   * entry replaces a built-in serializer.
+   *
+   * These live in `blume.config.ts` (which is executed at build time), not in
+   * `components.tsx` (which is only statically analyzed, never run).
+   *
+   * ```ts
+   * agents: {
+   *   markdownComponents: {
+   *     Chart: ({ props }) => `![${props.title}](/charts/${props.slug}.png)`,
+   *   },
+   * }
+   * ```
+   */
+  markdownComponents?: Record<string, ComponentMarkdown>;
+  /** Expose the docs as an MCP server for agents. */
+  mcp?: McpConfig;
+  /**
+   * Publish Agent Skills for discovery: a directory (resolved against the
+   * project root) whose subdirectories each hold a `SKILL.md`. Skills are
+   * copied under `/.well-known/agent-skills/` — single-file skills verbatim,
+   * skills with supporting resources as `.tar.gz` archives — and enumerated
+   * in a discovery index with SHA-256 digests (Agent Skills Discovery RFC).
+   *
+   * ```ts
+   * agents: {
+   *   skills: "./skills",
+   * }
+   * ```
+   */
+  skills?: string;
+  /**
+   * Web Bot Auth: publish the org's HTTP Message Signature public keys at
+   * `/.well-known/http-message-signatures-directory`, so sites receiving
+   * requests from your agents can verify them. Public keys only — a key
+   * containing private material (`d`, `p`, `q`, …) is rejected.
+   */
+  webBotAuth?: WebBotAuthConfig;
+  /**
+   * 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. The script is tiny and no-ops in
+   * browsers without the API. Defaults to `true`; set `false` to opt out.
+   */
+  webmcp?: boolean;
+}
+
 /** RSS/Atom feed generation. */
 export interface RssConfig {
   /** Generate feeds. Defaults to `true`. */
@@ -1318,13 +1068,6 @@ export interface SoftwareConfig {
 
 /** Discoverability: OG images, feeds, sitemap, robots, and structured data. */
 export interface SeoConfig {
-  /**
-   * Emit `agent-readability.json`: a manifest indexing the agent-facing surface
-   * (llms.txt, Markdown mirrors, MCP, feeds). Defaults to `true`.
-   */
-  agentReadability?: boolean;
-  /** robots.txt `Content-Signal` usage declaration. Defaults to `true`. */
-  contentSignals?: ContentSignalsConfig;
   /** Per-page Open Graph image generation. */
   og?: OgConfig;
   /**
@@ -1412,31 +1155,35 @@ export interface GithubConfig {
 // Markdown
 // ---------------------------------------------------------------------------
 
-/** Code-block rendering options. */
+/** Code rendering options. */
 export interface CodeConfig {
   /** Show a brand language icon in the code-block header. Defaults to `true`. */
   icons?: boolean;
+  /**
+   * Syntax-highlighting themes for every code surface — fenced blocks, inline
+   * `` `code`{:lang} ``, `<CodeBlock>`, and `<Diff>` — as bundled Shiki theme
+   * names or inline custom Shiki themes per color mode.
+   */
+  theme?: {
+    /** Dark-mode theme name or custom theme. Defaults to `github-dark`. */
+    dark?: CodeTheme;
+    /** Light-mode theme name or custom theme. Defaults to `github-light`. */
+    light?: CodeTheme;
+  };
   /** Wrap long lines instead of scrolling horizontally. Defaults to `false`. */
   wrap?: boolean;
 }
 
 /** Markdown / MDX rendering behavior. */
 export interface MarkdownConfig {
-  /** Code-block rendering: language icons, line wrap. */
+  /** Code rendering: language icons, syntax themes, line wrap. */
   code?: CodeConfig;
   /**
-   * Syntax-highlighting themes for every code surface — fenced blocks, inline
-   * `` `code`{:lang} ``, `<CodeBlock>`, and `<Diff>`.
+   * Open external links (`https://…`, `//host/…`) in a new tab, with an arrow
+   * icon and a screen-reader hint, like Blume's header and sidebar links.
+   * Defaults to `false`.
    */
-  codeBlocks?: {
-    /** Bundled Shiki theme names or inline custom Shiki themes per color mode. */
-    theme?: {
-      /** Dark-mode theme name or custom theme. Defaults to `github-dark`. */
-      dark?: CodeTheme;
-      /** Light-mode theme name or custom theme. Defaults to `github-light`. */
-      light?: CodeTheme;
-    };
-  };
+  externalLinks?: boolean;
   /**
    * Wrap each `##`–`######` heading in a self-anchor link so readers can copy,
    * bookmark, or share a section permalink. Defaults to `true`.
@@ -1456,119 +1203,6 @@ export interface ReactConfig {
   compiler?: boolean;
 }
 
-// ---------------------------------------------------------------------------
-// OpenAPI / AsyncAPI
-// ---------------------------------------------------------------------------
-
-/**
- * The shared shape of both API-reference blocks (`openapi`, `asyncapi`). Only
- * the per-block defaults differ; those are documented on the extending
- * interfaces.
- */
-interface ReferenceConfig {
-  /** Turn the reference on. Defaults to `false`. */
-  enabled?: boolean;
-  /** Start nested schema rows expanded (Blume renderer). Defaults to `false`. */
-  expandSchemas?: boolean;
-  /**
-   * The interactive "Try it" panel on operation pages (Blume renderer). On by
-   * default; `false` hides it. `proxy` is the CORS escape hatch the OpenAPI
-   * Send button routes requests through: a proxy URL, or `true` for the
-   * built-in `/_api-proxy` endpoint (which requires
-   * `deployment.output: "server"`). `proxy` is OpenAPI-only — an event
-   * composer's WebSocket connect is direct.
-   */
-  playground?: boolean | { enabled?: boolean; proxy?: boolean | string };
-  /** Who renders the reference. Defaults to `blume`. */
-  renderer?: "blume" | "scalar";
-  /**
-   * Extra Scalar options forwarded verbatim to the embedded `<ScalarComponent>`
-   * (Scalar renderer only) — e.g. `localization`, `agent`,
-   * `hideTestRequestButton`, `orderSchemaPropertiesBy`. These win over Blume's
-   * derived spec/theme config, so it's a full escape hatch to Scalar's API.
-   */
-  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- mirrors the schema's `z.record(z.unknown())` (the drift guard requires it); the values are Scalar's own API surface, deliberately unmodeled.
-  scalar?: Record<string, unknown>;
-  /** One or more specs; each renders on its own route by default. */
-  sources?: OpenApiSource[];
-  /** Shorthand for a single source: `sources: [{ spec }]`. */
-  spec?: string;
-  /** Scalar theme name (Scalar renderer only). */
-  theme?: string;
-}
-
-/**
- * OpenAPI reference. By default (`renderer: "blume"`) Blume renders its own UI:
- * one real page per operation, grouped by tag in the sidebar and included in
- * search, llms.txt, and OG. Set `renderer: "scalar"` for the embedded Scalar
- * SPA (a single self-contained route).
- */
-export interface OpenApiConfig extends ReferenceConfig {
-  /**
-   * Code-sample languages shown per operation (Blume renderer). Defaults to
-   * `["curl", "js", "python"]`.
-   */
-  codeSamples?: string[];
-  /** Where the reference mounts. Defaults to `/reference`. */
-  route?: string;
-}
-
-/**
- * AsyncAPI reference. Same shape as {@link OpenApiConfig}: by default
- * (`renderer: "blume"`) Blume normalizes the spec to AsyncAPI 3.x and renders
- * its own UI — one real page per operation, grouped by tag (or channel) in the
- * sidebar and included in search, llms.txt, and OG. Set `renderer: "scalar"`
- * for the embedded Scalar SPA (a single self-contained route).
- */
-export interface AsyncApiConfig extends ReferenceConfig {
-  /**
-   * Code-sample tools shown per operation (Blume renderer). Defaults to every
-   * tool appropriate to the operation's protocol binding.
-   */
-  codeSamples?: string[];
-  /** Where the reference mounts. Defaults to `/events`. */
-  route?: string;
-}
-
-/**
- * GraphQL reference. Blume lowers the schema — SDL text or an introspection
- * JSON result, local or remote — into 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 in the sidebar,
- * search, llms.txt, and OG. Always Blume-rendered — the embedded Scalar SPA
- * reads OpenAPI documents only — so unlike the other reference blocks there
- * is no `renderer` opt-out.
- */
-export interface GraphqlConfig {
-  /**
-   * Code-sample languages shown per operation. Defaults to
-   * `["curl", "js", "python"]`.
-   */
-  codeSamples?: string[];
-  /** Turn the reference on. Defaults to `false`. */
-  enabled?: boolean;
-  /**
-   * URL of the live GraphQL endpoint the playground and code samples target —
-   * a schema, unlike an OpenAPI document, names no server. Applies to every
-   * source in the block; a per-source `endpoint` wins.
-   */
-  endpoint?: string;
-  /**
-   * The interactive "Try it" panel on operation pages. 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"`).
-   */
-  playground?: boolean | { enabled?: boolean; proxy?: boolean | string };
-  /** Where the reference mounts. Defaults to `/graphql`. */
-  route?: string;
-  /** One or more schemas; each renders on its own route by default. */
-  sources?: GraphqlSource[];
-  /** Shorthand for a single source: `sources: [{ spec }]`. */
-  spec?: string;
-}
-
 // ---------------------------------------------------------------------------
 // Misc top-level unions
 // ---------------------------------------------------------------------------
@@ -1639,16 +1273,11 @@ export interface FrontmatterConfig {
 }
 
 /**
- * "Last updated" timestamps. `false` (default) disables them; `true` derives
- * each date from git history; the object form selects the source. A page's
- * `lastModified` frontmatter always wins.
+ * "Last updated" timestamps. `false` (default) disables them; `"git"` derives
+ * each date from the repository history; `"frontmatter"` reads only the page's
+ * own field. A page's `lastModified` frontmatter always wins.
  */
-export type LastModifiedConfig =
-  | boolean
-  | {
-      /** Where the date comes from. Defaults to `git`. */
-      type?: "git" | "frontmatter";
-    };
+export type LastModifiedConfig = false | "git" | "frontmatter";
 
 /**
  * Date presentation for the "last updated" stamp and the changelog timeline —
@@ -1700,12 +1329,16 @@ export type TocConfig =
  * Markdown/MDX under `docs/` with sensible defaults.
  */
 export interface BlumeConfig {
-  /** AI-facing features: the Ask AI assistant and an `llms.txt` manifest. */
+  /** The machine-readable surface for agents: JSON API, `llms.txt`, MCP, skills, discovery. */
+  agents?: AgentsConfig;
+  /** Model-facing features: the Ask AI assistant and the "Open in chat" action. */
   ai?: AiConfig;
-  /** Analytics providers (PostHog, Vercel, or arbitrary scripts). */
-  analytics?: AnalyticsConfig;
-  /** AsyncAPI reference (native renderer by default, Scalar opt-out). */
-  asyncapi?: AsyncApiConfig;
+  /**
+   * Analytics adapters from `blume/analytics`, emitted into `<head>` of every
+   * production page in this order: `[posthog({ key }), vercel(),
+   * cloudflare({ token }), script({ src })]`. Unset or empty injects nothing.
+   */
+  analytics?: AnalyticsAdapter[];
   /** Site-wide announcement banner shown above the header. */
   banner?: BannerConfig;
   /**
@@ -1747,15 +1380,13 @@ export interface BlumeConfig {
   frontmatter?: FrontmatterConfig;
   /** Source repository (Edit-this-page links and the header repo link). */
   github?: GithubConfig;
-  /** Native GraphQL reference (root fields and named types as real pages). */
-  graphql?: GraphqlConfig;
   /** Internationalization (opt-in multi-locale). */
   i18n?: I18nConfig;
   /** Image optimization: remote-host authorization for the image service. */
   image?: ImageConfig;
   /** Astro integrations appended after Blume's built-ins, in declaration order. */
   integrations?: AstroIntegration[];
-  /** "Last updated" timestamps from git history or frontmatter. Defaults to `false`. */
+  /** "Last updated" timestamps: `"git"`, `"frontmatter"`, or `false` (default). */
   lastModified?: LastModifiedConfig;
   /** Site logo / brand mark. */
   logo?: LogoConfig;
@@ -1763,12 +1394,16 @@ export interface BlumeConfig {
   markdown?: MarkdownConfig;
   /** Header, sidebar, tabs, and switchers. */
   navigation?: NavigationConfig;
-  /** Native OpenAPI reference. */
-  openapi?: OpenApiConfig;
   /** React island behavior (compiler auto-memoization). */
   react?: ReactConfig;
   /** URL redirect rules. */
   redirects?: RedirectConfig[];
+  /**
+   * API references: adapters from `blume/reference`, each rendering one or
+   * more specs — `[openapi({ spec }), asyncapi({ spec }), graphql({ spec,
+   * endpoint })]`. Unset or empty renders none.
+   */
+  reference?: ReferenceAdapter[];
   /** Search backend and credentials. */
   search?: SearchConfig;
   /** Discoverability: OG images, feeds, sitemap, robots, structured data. */