blume 1.7.3 → 2.0.0

package/dist/types/ai/ai-catalog.d.ts

@@ -0,0 +1,42 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { SkillArtifact } from "./skills.ts";
+/**
+ * The AI Catalog (Agent-Card/ai-catalog data model, `specVersion` 1.0) at
+ * `/.well-known/ai-catalog.json`, which is also the Agentic Resource
+ * Discovery (ARD) manifest: one entry per agent-facing resource the site
+ * publishes, each an `urn:air:<host>:<namespace>:<name>` identifier, a
+ * display name, the artifact's media type, a URL, and the
+ * `representativeQueries` registries embed for semantic search. Like the
+ * RFC 9727 catalog next to it, everything is derived from `blume.config.ts`
+ * and the build's published skills — nothing is hand-written.
+ *
+ * ARD v0.91 moved its manifest to `/.well-known/ard.json` and calls
+ * `ai-catalog.json` the predecessor path that consumers only *may* consult,
+ * while the ai-catalog spec and today's agent-readiness scanners key on
+ * `ai-catalog.json`. The ARD manifest is just an `entries` array (other
+ * members are ignored), so the one document is written to both paths.
+ *
+ * Served as plain `application/json`: the `.json` extension gets it from
+ * every static host with no header rule, and the scanners that gate on the
+ * file ask for exactly that type. The registered `application/ai-catalog+json`
+ * is what the `Link`/`<link>` advertisements declare the document to be.
+ */
+export declare const AI_CATALOG_PATH = "/.well-known/ai-catalog.json";
+export declare const ARD_MANIFEST_PATH = "/.well-known/ard.json";
+export declare const AI_CATALOG_TYPE = "application/ai-catalog+json";
+/**
+ * Whether the site publishes a catalog: the feature is on, a `deployment.site`
+ * anchors the identifiers, and at least one entry exists. Every entry source
+ * is a config flag, so the answer needs no build output — the same gate the
+ * header rules, the `Link` header, and the head links read.
+ */
+export declare const hasAiCatalog: (config: ResolvedConfig) => boolean;
+/**
+ * The `.well-known` documents agent registries fetch cross-origin (browser
+ * agents, hosted registries reading through a page). Each needs
+ * `Access-Control-Allow-Origin: *` on the static surface; the MCP endpoint
+ * itself already sets it at runtime.
+ */
+export declare const crossOriginDiscoveryPaths: (config: ResolvedConfig) => string[];
+/** The catalog document, or null when the site publishes none. */
+export declare const buildAiCatalog: (config: ResolvedConfig, skills: readonly SkillArtifact[]) => string | null;

package/dist/types/ai/api/paths.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Where the JSON docs API and its OpenAPI description are served. Base-less
+ * (like every route Blume emits); callers layer `deployment.base` on top.
+ * Under `/api/` alongside the Ask AI endpoint (`/api/ask`) so the namespace a
+ * Blume site reserves for live endpoints stays one prefix, and under its own
+ * `docs` segment so a search provider's proxy at `/api/search` never collides.
+ */
+export declare const OPENAPI_PATH = "/openapi.json";
+export declare const API_BASE = "/api/docs";
+export declare const API_PAGES_PATH = "/api/docs/pages.json";
+export declare const API_PAGE_PATH = "/api/docs/pages/{route}.json";
+export declare const API_NAVIGATION_PATH = "/api/docs/navigation.json";
+export declare const API_SEARCH_PATH = "/api/docs/search";
+/** The `pages/{route}.json` path segment for a route (`index` for home). */
+export declare const pageParam: (route: string) => string;
+/** The base-less served path of a route's per-page JSON document. */
+export declare const pageJsonPath: (route: string) => string;

package/dist/types/ai/api-catalog.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+/**
+ * RFC 9727 API catalog: a linkset (RFC 9264) at `/.well-known/api-catalog`
+ * enumerating the APIs a publisher offers, so agents can discover them from
+ * the domain alone. Blume already knows the site's APIs — the configured
+ * OpenAPI/AsyncAPI references and the hosted MCP server — so the catalog is
+ * generated, never hand-written: one entry per API, anchored at its docs
+ * route (the RFC's own examples anchor on developer-portal pages), with
+ * `service-doc` pointing at the rendered reference and `service-desc` at the
+ * spec when it lives at a fetchable URL. The site's own JSON docs API is an
+ * entry too, described by its generated `/openapi.json`.
+ */
+export declare const API_CATALOG_PATH = "/.well-known/api-catalog";
+export declare const API_CATALOG_TYPE = "application/linkset+json";
+/** Whether the site has anything to catalog — gates every emission surface. */
+export declare const hasApiCatalog: (config: ResolvedConfig) => boolean;
+/** The `application/linkset+json` document, or null when there are no APIs. */
+export declare const buildApiCatalog: (config: ResolvedConfig) => string | null;

package/dist/types/ai/ask.d.ts

@@ -0,0 +1,368 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+/**
+ * The `reasoning` levels the adapters accept: the AI SDK's top-level
+ * `reasoning` values minus `provider-default`, which is what omitting the
+ * option means.
+ */
+export declare const askReasoningLevels: readonly ["none", "minimal", "low", "medium", "high", "xhigh"];
+/** How much the model reasons before answering (an adapter's `reasoning`). */
+export type AskReasoning = (typeof askReasoningLevels)[number];
+/**
+ * The AI SDK's `providerOptions` shape, forwarded to `streamText` verbatim:
+ * `{ [provider]: { [option]: value } }`. The escape hatch for model controls
+ * Blume doesn't name, so a new provider knob never needs a Blume field.
+ */
+export type AskProviderOptions = Record<string, Record<string, JsonValue>>;
+/** The options every Ask AI adapter accepts. */
+export interface AskAdapterOptions {
+    /**
+     * Name of the env var holding the provider's API key. Each adapter has its
+     * own default; set this only to point at a different variable.
+     */
+    apiKeyEnv?: 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>;
+    /**
+     * Options passed to `streamText` as its `providerOptions`, untouched, in the
+     * AI SDK's own shape (`{ openai: { textVerbosity: "low" } }`, say).
+     */
+    providerOptions?: AskProviderOptions;
+}
+/** Options for {@link gateway}. */
+export interface AskGatewayOptions extends AskAdapterOptions {
+    /** A `provider/model` id routed by the gateway. Defaults to `openai/gpt-5.5`. */
+    model?: string;
+    /**
+     * How much the model reasons before answering. Sent as the AI SDK's
+     * top-level `reasoning` option, which the gateway maps to the model's own
+     * control (OpenAI's `reasoning_effort`, for example); the model has to
+     * offer the level you pick. Omitted keeps the model's default.
+     */
+    reasoning?: AskReasoning;
+}
+export type AskGatewayAdapter = AdapterDescriptor<"gateway", AskGatewayOptions>;
+export declare const gatewayAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"gateway">;
+    options: z.ZodObject<{
+        model: z.ZodDefault<z.ZodString>;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Route Ask AI through the Vercel AI Gateway (the default). `model` is a
+ * `provider/model` string; the key is `AI_GATEWAY_API_KEY`, or Vercel's OIDC
+ * token when deployed there. Needs no provider SDK beyond the `ai` package
+ * Blume ships.
+ */
+export declare const gateway: (options?: AskGatewayOptions) => AskGatewayAdapter;
+/** Options for {@link openrouter}. */
+export interface AskOpenRouterOptions extends AskAdapterOptions {
+    /** The OpenRouter model id (`anthropic/claude-sonnet-4-5`). */
+    model: string;
+    /**
+     * How much the model reasons before answering. Set on the model as
+     * OpenRouter's `reasoning.effort`, because its provider ignores the AI
+     * SDK's call-level option. Omitted keeps the model's default.
+     */
+    reasoning?: AskReasoning;
+}
+export type AskOpenRouterAdapter = AdapterDescriptor<"openrouter", AskOpenRouterOptions>;
+export declare const openrouterAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"openrouter">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Route Ask AI through OpenRouter. Reads `OPENROUTER_API_KEY` and needs
+ * `@openrouter/ai-sdk-provider` installed in the project.
+ */
+export declare const openrouter: (options: AskOpenRouterOptions) => AskOpenRouterAdapter;
+/** Options for {@link llmgateway}. */
+export interface AskLlmGatewayOptions extends AskAdapterOptions {
+    /** Overrides the preset endpoint (`https://api.llmgateway.io/v1`). */
+    baseUrl?: string;
+    /** The model id LLMGateway serves. */
+    model: string;
+    /**
+     * How much the model reasons before answering, sent in the request as
+     * `reasoning_effort`. Omitted keeps the model's default.
+     */
+    reasoning?: AskReasoning;
+}
+export type AskLlmGatewayAdapter = AdapterDescriptor<"llmgateway", AskLlmGatewayOptions>;
+export declare const llmgatewayAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"llmgateway">;
+    options: z.ZodObject<{
+        baseUrl: z.ZodDefault<z.ZodURL>;
+        model: z.ZodString;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Route Ask AI through LLMGateway's OpenAI-compatible endpoint. Reads
+ * `LLMGATEWAY_API_KEY` and needs `@ai-sdk/openai-compatible` installed.
+ */
+export declare const llmgateway: (options: AskLlmGatewayOptions) => AskLlmGatewayAdapter;
+/**
+ * Options for {@link inkeep}. No `reasoning`: Inkeep runs its own QA pipeline
+ * behind an OpenAI-compatible endpoint with no reasoning control.
+ */
+export interface AskInkeepOptions extends AskAdapterOptions {
+    /** Overrides the preset endpoint (`https://api.inkeep.com/v1`). */
+    baseUrl?: string;
+    /** The Inkeep QA model id. */
+    model: string;
+}
+export type AskInkeepAdapter = AdapterDescriptor<"inkeep", AskInkeepOptions>;
+export declare const inkeepAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"inkeep">;
+    options: z.ZodObject<{
+        baseUrl: z.ZodDefault<z.ZodURL>;
+        model: z.ZodString;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Answer with Inkeep, which retrieves from the content indexed in its own
+ * dashboard, so Blume leaves it ungrounded and it takes no `reasoning`.
+ * Reads `INKEEP_API_KEY` and needs `@ai-sdk/openai-compatible` installed.
+ */
+export declare const inkeep: (options: AskInkeepOptions) => AskInkeepAdapter;
+/** Options for {@link openaiCompatible}. */
+export interface AskOpenAICompatibleOptions extends AskAdapterOptions {
+    /** Name of the env var holding the endpoint's API key. */
+    apiKeyEnv: string;
+    /** The endpoint's base URL (`https://my-gateway.example.com/v1`). */
+    baseUrl: string;
+    /** The model id the endpoint serves. */
+    model: string;
+    /** The provider name the AI SDK reports. Defaults to `openai-compatible`. */
+    name?: string;
+    /**
+     * How much the model reasons before answering, sent in the request as
+     * `reasoning_effort`, so the endpoint has to accept that parameter.
+     * Omitted keeps the model's default.
+     */
+    reasoning?: AskReasoning;
+}
+export type AskOpenAICompatibleAdapter = AdapterDescriptor<"openai-compatible", AskOpenAICompatibleOptions>;
+export declare const openaiCompatibleAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"openai-compatible">;
+    options: z.ZodObject<{
+        apiKeyEnv: z.ZodString;
+        baseUrl: z.ZodURL;
+        model: z.ZodString;
+        name: z.ZodDefault<z.ZodString>;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Route Ask AI through any OpenAI-compatible endpoint: supply its `baseUrl`,
+ * the `model` it serves, and the env var holding its key. Needs
+ * `@ai-sdk/openai-compatible` installed.
+ */
+export declare const openaiCompatible: (options: AskOpenAICompatibleOptions) => AskOpenAICompatibleAdapter;
+/** Which backend answers Ask AI: the value of `gateway()`, `openrouter()`, … */
+export type AskAdapter = AskGatewayAdapter | AskOpenRouterAdapter | AskLlmGatewayAdapter | AskInkeepAdapter | AskOpenAICompatibleAdapter;
+/**
+ * Error params for `ai.ask`: a 1.x flat provider field (`model`, `apiKeyEnv`,
+ * `baseUrl`, `headers`, `reasoning`) names the adapter call it moves into —
+ * the one the object's `provider` picks, 1.x string or descriptor — instead
+ * of Zod's bare "Unrecognized key"; any other unknown key keeps its wording.
+ */
+export declare const askMovedFieldsHint: {
+    error: (issue: z.core.$ZodRawIssue) => string | undefined;
+};
+/**
+ * `ai.ask.provider`: the descriptor an adapter factory returned, validated
+ * against that adapter's own option schema. A value that isn't a descriptor
+ * at all (a 1.x provider name) names the factory that replaced it.
+ */
+export declare const askAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"gateway">;
+    options: z.ZodObject<{
+        model: z.ZodDefault<z.ZodString>;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"openrouter">;
+    options: z.ZodObject<{
+        model: z.ZodString;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"llmgateway">;
+    options: z.ZodObject<{
+        baseUrl: z.ZodDefault<z.ZodURL>;
+        model: z.ZodString;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"inkeep">;
+    options: z.ZodObject<{
+        baseUrl: z.ZodDefault<z.ZodURL>;
+        model: z.ZodString;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"openai-compatible">;
+    options: z.ZodObject<{
+        apiKeyEnv: z.ZodString;
+        baseUrl: z.ZodURL;
+        model: z.ZodString;
+        name: z.ZodDefault<z.ZodString>;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>], "kind">;
+/** A resolved (post-defaults) `ai.ask.provider` descriptor. */
+export type AskAdapterConfig = z.output<typeof askAdapterSchema>;
+export type AskAdapterKind = AskAdapterConfig["kind"];
+/** The provider when `ai.ask.provider` is unset: the gateway with its defaults. */
+export declare const DEFAULT_ASK_PROVIDER: AskAdapter;
+/** The route fragments an adapter contributes to `askEndpointTemplate`. */
+export interface AskBackendTemplate {
+    /**
+     * Extra `streamText` fields as `key: value` source lines: the adapter's
+     * reasoning mapping (when it is a call option) and `providerOptions`.
+     */
+    fields: string[];
+    /** Import lines after the shared `astro` and `astro:env/server` ones. */
+    imports: string[];
+    /**
+     * The up-front credential guard: a statement that returns a 503, since the
+     * endpoint exists but can't answer until the deployment sets its key.
+     */
+    keyCheck: string;
+    /** The `model:` expression passed to `streamText`. */
+    model: string;
+    /** Module-level provider setup (the provider factory call). */
+    setup: string;
+}
+/**
+ * What the endpoint template and the diagnostics read from an adapter beyond
+ * the descriptor itself (`kind`, `requiredSecrets`, `runtimeDeps` travel on
+ * the descriptor; `generate`, `eject`, the required-secrets check, and the
+ * runtime-dependency manifest read those directly).
+ */
+export interface AskBackend {
+    /** Whether Blume grounds answers in the docs (Inkeep retrieves itself). */
+    grounded: boolean;
+    kind: AskAdapterKind;
+    /** Human-readable adapter name for diagnostics ("AI Gateway"). */
+    label: string;
+    /** Appended to the missing-secret warning (an alternative credential, say). */
+    secretNote?: string;
+    template: AskBackendTemplate;
+}
+/** Resolve a parsed `ai.ask.provider` descriptor into its backend. */
+export declare const resolveAskBackend: (provider?: AskAdapterConfig) => AskBackend;

package/dist/types/ai/changelog-markdown.d.ts

@@ -0,0 +1,2 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+export declare const buildChangelogIndexMarkdown: (project: BlumeProject) => string;

package/dist/types/ai/component-markdown.d.ts

@@ -126,7 +126,7 @@ export interface DownlevelWalk {
     registry: Record<string, ComponentMarkdown>;
     source: string;
 }
-/** The serializer registry for a site: built-ins under a user's `ai.markdownComponents`. */
+/** The serializer registry for a site: built-ins under a user's `agents.markdownComponents`. */
 export declare const componentRegistry: (components?: Record<string, ComponentMarkdown>) => Record<string, ComponentMarkdown>;
 /**
  * Walk the tree collecting replacements. A replaced element's subtree is
@@ -145,7 +145,7 @@ export declare const downlevelComponentNode: (node: MdastNode, walk: DownlevelWa
  * with no supported components — and sources Satteri can't parse as MDX, e.g.
  * plain `.md` with literal `<`/`{` — are returned byte-identical.
  *
- * `components` adds user serializers from `ai.markdownComponents`, layered
+ * `components` adds user serializers from `agents.markdownComponents`, layered
  * over the built-ins: a same-name entry replaces the built-in serializer, and
  * one that always returns `null` effectively opts that component out.
  *

package/dist/types/ai/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Ask AI provider adapters for `blume.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { openrouter } from "blume/ai";
+ *
+ * export default defineConfig({
+ *   ai: {
+ *     ask: {
+ *       enabled: true,
+ *       provider: openrouter({ model: "anthropic/claude-sonnet-4-5" }),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * Each factory returns a plain descriptor (see `core/adapter.ts`) that the
+ * schema validates and the generated `/api/ask` route inlines as literals;
+ * nothing here runs at request time.
+ */
+export { gateway, inkeep, llmgateway, openaiCompatible, openrouter, } from "./ask.ts";
+export type { AskAdapter, AskAdapterOptions, AskGatewayAdapter, AskGatewayOptions, AskInkeepAdapter, AskInkeepOptions, AskLlmGatewayAdapter, AskLlmGatewayOptions, AskOpenAICompatibleAdapter, AskOpenAICompatibleOptions, AskOpenRouterAdapter, AskOpenRouterOptions, AskProviderOptions, AskReasoning, } from "./ask.ts";
+export type { AdapterDescriptor } from "../core/adapter.ts";

package/dist/types/ai/link-headers.d.ts

@@ -0,0 +1,24 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+/**
+ * The homepage `Link` response header (RFC 8288) — agent discovery for the
+ * machine-readable surface Blume already publishes. Agents probing a site read
+ * this header off `GET /` to find the resources without scraping HTML:
+ * `agent-readability.json` and `llms.txt` as `rel="describedby"`, the OpenAPI
+ * description of the JSON docs API as `rel="service-desc"`, and the
+ * homepage's raw-Markdown mirror as `rel="alternate"` (only when the home
+ * route is a content page — a user landing page has no mirror). Every rel
+ * value is IANA-registered, which agent-readiness checkers require.
+ *
+ * The header is homepage-only by design: the root response is what agents
+ * probe, and `agent-readability.json` indexes the rest of the surface (the
+ * per-route Markdown pattern, MCP, feeds) far better than per-page headers
+ * could. An agent that enters on a deep page (a search result, a shared link)
+ * never sees this header at all — that path is covered in the HTML instead:
+ * every page's `<head>` carries the same `describedby` links plus its own
+ * Markdown mirror as an `alternate` (the `DiscoveryLinks.astro` partial every
+ * layout renders), which also reaches hosts where Blume can't set response
+ * headers. Targets are
+ * root-relative under `deployment.base` — RFC 8288 resolves them against the
+ * request URL. Returns null when nothing is advertisable.
+ */
+export declare const buildHomeLinkHeader: (config: ResolvedConfig, routePaths: readonly string[]) => string | null;

package/dist/types/ai/llms.d.ts

@@ -0,0 +1,25 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { SkillArtifact } from "./skills.ts";
+/** Inputs only the build has: the published skills, collected once per build. */
+export interface LlmsIndexOptions {
+    /**
+     * The Agent Skills the build publishes under `/.well-known/agent-skills/`,
+     * listed in their own section with each skill's description — which is
+     * where a skill says when to use it. Absent (empty) for the homepage
+     * Markdown mirror, which is synthesized before the skills are collected.
+     */
+    skills?: readonly SkillArtifact[];
+}
+/**
+ * Build the compact `llms.txt` index: title and summary, then the sidebar tree
+ * rendered as sections — group labels become headings, pages become link lists —
+ * so the file mirrors how the docs are organized rather than one flat blob.
+ * Also serves as the homepage's synthesized Markdown mirror when the home
+ * route is a landing page (see `buildRawMarkdown`).
+ */
+export declare const buildLlmsIndex: (project: BlumeProject, options?: LlmsIndexOptions) => string;
+/** Build both LLM text artifacts for a project. */
+export declare const buildLlmsFiles: (project: BlumeProject, options?: LlmsIndexOptions) => Promise<{
+    index: string;
+    full: string;
+}>;

package/dist/types/ai/markdown.d.ts

@@ -0,0 +1,45 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+/** One route's raw-Markdown variants. */
+export interface RawMarkdownEntry {
+    /**
+     * The agent-facing Markdown served at `/<route>.md`: supported components
+     * downleveled to plain Markdown (`<TypeTable>` → table, `<Callout>` →
+     * blockquote, …). Present only when downleveling changed something, so
+     * component-free pages aren't stored twice.
+     */
+    md?: string;
+    /** The original source, served verbatim at `/<route>.mdx`. */
+    mdx: string;
+}
+/** The Markdown an agent should read for a route. */
+export declare const agentMarkdown: (entry: RawMarkdownEntry) => string;
+/**
+ * Estimated token count of a Markdown document, for the `x-markdown-tokens`
+ * response header (the convention Cloudflare's Markdown for Agents ships; the
+ * tokenizer is unspecified there too, so this is the common ~4-characters-
+ * per-token estimate). Kept in sync with the inline computation in
+ * `rawMarkdownEndpointTemplate`, which can't import build-time code.
+ */
+export declare const markdownTokenCount: (text: string) => number;
+/**
+ * Map every route to its raw source Markdown. Powers the `<route>.md` and
+ * `<route>.mdx` endpoints: `.mdx` serves the original source so tools can see
+ * exactly what the author wrote, while `.md` downlevels supported components
+ * to plain Markdown for consumers that can't interpret JSX. `<Visibility>`
+ * audiences are resolved for agents in both variants: web-only content is
+ * removed, agents-only unwrapped. Relative image references are rewritten to
+ * their served `/blume-assets/content/…` URLs in both variants too — an agent
+ * fetches these endpoints by URL, where a colocated `./diagram.png` resolves
+ * to nothing — and relative page links to the routes they mean, as the
+ * rendered page's are (see `relative-links.ts`).
+ */
+export declare const buildRawMarkdown: (project: BlumeProject) => Promise<Record<string, RawMarkdownEntry>>;
+/**
+ * Every route path with a raw-Markdown mirror: the manifest routes, plus the
+ * homepage when its mirror is the synthesized llms.txt fallback and the
+ * generated changelog index (see `buildRawMarkdown`). This is the route list the negotiation surfaces (dev
+ * middleware, Vercel routing config) and the homepage `Link` header build
+ * from, so `Accept: text/markdown` on `/` resolves even when the homepage is
+ * a landing page.
+ */
+export declare const markdownRoutePaths: (project: BlumeProject) => string[];

package/dist/types/ai/mcp/discovery.d.ts

@@ -0,0 +1,68 @@
+import type { McpToolMeta } from "./tools.ts";
+/** Inputs needed to describe the MCP server in discovery documents. */
+export interface McpDiscoveryInput {
+    /** Normalized `deployment.base` (`""` or `/seg`); the route is base-less. */
+    base: string;
+    name: string;
+    route: string;
+    site: string | null;
+    version: string;
+}
+/**
+ * The `/.well-known/mcp.json` discovery document: the minimal pointer agents use
+ * to find the server and its transport.
+ */
+export declare const buildMcpDiscovery: (input: McpDiscoveryInput) => {
+    servers: {
+        name: string;
+        transport: string;
+        url: string;
+    }[];
+};
+export declare const asciiSlugify: (text: string) => string;
+/**
+ * The `/.well-known/mcp/server-card.json` document. The core follows the
+ * SEP-2127 Server Card extension schema (`$schema`, reverse-DNS `name`,
+ * `remotes` — which the schema requires to be absolute, so it appears only
+ * when a `site` is configured). Alongside it ride initialize-shaped compat
+ * fields (`serverInfo`, `capabilities`, `transports`) for scanners built
+ * against the SEP's earlier revision, plus Blume's advertised tool set —
+ * schema-legal extras (`additionalProperties` is open), and the tool list is
+ * genuinely static for a docs server, unlike the dynamic servers the spec
+ * excludes primitives for. Full input schemas are served live via
+ * `tools/list`.
+ */
+export interface McpServerCard {
+    $schema: string;
+    capabilities: {
+        resources: {
+            listChanged: boolean;
+            subscribe: boolean;
+        };
+        tools: {
+            listChanged: boolean;
+        };
+    };
+    description: string;
+    name: string;
+    /** Absolute endpoints only — present when a `site` is configured. */
+    remotes?: {
+        type: string;
+        url: string;
+    }[];
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    title: string;
+    tools: McpToolMeta[];
+    transport: string;
+    transports: {
+        endpoint: string;
+        type: string;
+    }[];
+    url: string;
+    version: string;
+    websiteUrl?: string;
+}
+export declare const buildMcpServerCard: (input: McpDiscoveryInput) => McpServerCard;