blume 1.7.3 → 2.0.1

package/dist/types/core/config-input.d.ts

@@ -1,9 +1,14 @@
 import type { AstroIntegration } from "astro";
+import type { AssistantAdapter } 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 { GraphqlSource, OpenApiSource, OpenInChatProvider, SearchProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
-import type { ContentSource } from "./sources/types.ts";
+import type { OpenInChatProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
 import type { StandardSchema } from "./standard-schema.ts";
 /**
  * The public, hand-documented authoring type for `blume.config.ts`.
@@ -76,172 +81,34 @@ export type BannerConfig = string | {
         text: string;
     };
 };
-/** 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):
@@ -484,7 +351,7 @@ type RadiusScaleRound = "md" | "lg";
 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`.
      */
@@ -500,38 +367,11 @@ 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`. */
     radius?: RadiusScale;
 }
-/** 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. */
@@ -545,13 +385,16 @@ export interface SearchPopularLink {
     label: string;
 }
 /**
- * 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?: {
         /**
@@ -563,35 +406,29 @@ 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;
 }
-/** An empty-state prompt shown before the first Ask AI question. */
-export interface AskSuggestion {
+/**
+ * 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;
+/** An empty-state prompt shown before the first question to the assistant. */
+export interface AssistantSuggestion {
     /** Lucide icon name shown beside the suggestion. */
     icon?: string;
     /** The clickable suggestion text. */
     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 {
+/** How much retrieved documentation each question to the assistant carries. */
+export interface AssistantRetrievalConfig {
     /**
      * Total injected documentation characters, across all excerpts. Defaults to
      * `10000`. The single biggest lever on time-to-first-token — the model reads
@@ -611,17 +448,8 @@ export interface AskRetrievalConfig {
      */
     maxResults?: number;
 }
-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;
+/** The chat assistant. */
+export interface AssistantConfig {
     /**
      * Origins allowed to call the generated endpoint from another site — a
      * marketing page that embeds an ask box, for example — or `"*"` to allow
@@ -634,51 +462,38 @@ export interface AskConfig {
      * combined with it.
      */
     cors?: string[];
-    /** Turn Ask AI on. Defaults to `false`. */
+    /** Turn the assistant on. Defaults to `false`. */
     enabled?: boolean;
     /**
-     * Existing Ask AI endpoint to call instead of generating one. This keeps a
+     * Existing assistant endpoint to call instead of generating one. This keeps a
      * Blume site static while an API backend owns retrieval, model access, rate
      * 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?: AssistantAdapter;
     /**
      * How much documentation each question carries into the model's prompt.
      * Lower values cut time-to-first-token — which dominates on a self-hosted
      * backend — at the cost of recall. Defaults keep the built-in behavior.
      */
-    retrieval?: AskRetrievalConfig;
+    retrieval?: AssistantRetrievalConfig;
     /** Starter prompts shown before the first question. */
-    suggestions?: AskSuggestion[];
+    suggestions?: AssistantSuggestion[];
 }
 /** What the AI Catalog (ARD) manifest carries. */
 export interface AiCatalogConfig {
@@ -693,7 +508,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"],
@@ -714,7 +529,7 @@ export interface LlmsTxtConfig {
      * dropped.
      *
      * ```ts
-     * ai: {
+     * agents: {
      *   llmsTxt: {
      *     details: "## When to use Acme\n\nUse Acme when…",
      *   },
@@ -742,59 +557,10 @@ export interface McpConfig {
     /** Route the server mounts at. Defaults to `/mcp`. */
     route?: string;
 }
-/**
- * AI-facing features: the Ask AI assistant, an `llms.txt` manifest, and the
- * hosted MCP server.
- */
+/** Model-facing features: the 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 chat assistant. */
+    assistant?: AssistantConfig;
     /**
      * 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.
@@ -808,75 +574,12 @@ 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. */
 export interface WebBotAuthConfig {
     /** Public JWKs to publish (e.g. an Ed25519 key: `kty: "OKP"`, `crv: "Ed25519"`, `x: …`). */
     keys?: Record<string, unknown>[];
 }
-/** 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;
-}
 /** A configured locale plus display metadata for the switcher. */
 export interface LocaleConfigInput {
     /** Locale code, e.g. `en`, `fr`, `pt-BR`. */
@@ -962,25 +665,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
  * `image.remotePatterns`. Hostnames accept `*.` (one level) and `**.` (any
@@ -1033,6 +725,95 @@ export type ContentSignalsConfig = boolean | {
     /** Allow traditional and AI search indexing (`search`). Defaults to `true`. */
     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 (the assistant, 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`. */
@@ -1171,13 +952,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;
     /**
@@ -1255,30 +1029,34 @@ export interface GithubConfig {
     /** Repository name. */
     repo: string;
 }
-/** 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`.
@@ -1296,116 +1074,6 @@ export interface ReactConfig {
      */
     compiler?: boolean;
 }
-/**
- * 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.
-     */
-    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;
-}
 /** `<Component />` example previews (the object form of `examples`). */
 export interface ExamplesConfig {
     /**
@@ -1467,14 +1135,11 @@ export interface FrontmatterConfig {
     extend?: Record<string, StandardSchema>;
 }
 /**
- * "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 —
  * a curated pass-through to `Intl.DateTimeFormat`, shared by both surfaces.
@@ -1517,12 +1182,16 @@ export type TocConfig = boolean | {
  * 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 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;
     /**
@@ -1564,15 +1233,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;
@@ -1580,12 +1247,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. */