blume 1.7.3 → 2.0.1

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 assistantReasoningLevels: readonly ["none", "minimal", "low", "medium", "high", "xhigh"];
+/** How much the model reasons before answering (an adapter's `reasoning`). */
+export type AssistantReasoning = (typeof assistantReasoningLevels)[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 AssistantProviderOptions = Record<string, Record<string, JsonValue>>;
+/** The options every assistant adapter accepts. */
+export interface AssistantAdapterOptions {
+    /**
+     * 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?: AssistantProviderOptions;
+}
+/** Options for {@link gateway}. */
+export interface AssistantGatewayOptions extends AssistantAdapterOptions {
+    /** 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?: AssistantReasoning;
+}
+export type AssistantGatewayAdapter = AdapterDescriptor<"gateway", AssistantGatewayOptions>;
+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 the assistant 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?: AssistantGatewayOptions) => AssistantGatewayAdapter;
+/** Options for {@link openrouter}. */
+export interface AssistantOpenRouterOptions extends AssistantAdapterOptions {
+    /** 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?: AssistantReasoning;
+}
+export type AssistantOpenRouterAdapter = AdapterDescriptor<"openrouter", AssistantOpenRouterOptions>;
+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 the assistant through OpenRouter. Reads `OPENROUTER_API_KEY` and needs
+ * `@openrouter/ai-sdk-provider` installed in the project.
+ */
+export declare const openrouter: (options: AssistantOpenRouterOptions) => AssistantOpenRouterAdapter;
+/** Options for {@link llmgateway}. */
+export interface AssistantLlmGatewayOptions extends AssistantAdapterOptions {
+    /** 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?: AssistantReasoning;
+}
+export type AssistantLlmGatewayAdapter = AdapterDescriptor<"llmgateway", AssistantLlmGatewayOptions>;
+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 the assistant through LLMGateway's OpenAI-compatible endpoint. Reads
+ * `LLMGATEWAY_API_KEY` and needs `@ai-sdk/openai-compatible` installed.
+ */
+export declare const llmgateway: (options: AssistantLlmGatewayOptions) => AssistantLlmGatewayAdapter;
+/**
+ * Options for {@link inkeep}. No `reasoning`: Inkeep runs its own QA pipeline
+ * behind an OpenAI-compatible endpoint with no reasoning control.
+ */
+export interface AssistantInkeepOptions extends AssistantAdapterOptions {
+    /** Overrides the preset endpoint (`https://api.inkeep.com/v1`). */
+    baseUrl?: string;
+    /** The Inkeep QA model id. */
+    model: string;
+}
+export type AssistantInkeepAdapter = AdapterDescriptor<"inkeep", AssistantInkeepOptions>;
+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: AssistantInkeepOptions) => AssistantInkeepAdapter;
+/** Options for {@link openaiCompatible}. */
+export interface AssistantOpenAICompatibleOptions extends AssistantAdapterOptions {
+    /** 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?: AssistantReasoning;
+}
+export type AssistantOpenAICompatibleAdapter = AdapterDescriptor<"openai-compatible", AssistantOpenAICompatibleOptions>;
+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 the assistant 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: AssistantOpenAICompatibleOptions) => AssistantOpenAICompatibleAdapter;
+/** Which backend answers the assistant: the value of `gateway()`, `openrouter()`, … */
+export type AssistantAdapter = AssistantGatewayAdapter | AssistantOpenRouterAdapter | AssistantLlmGatewayAdapter | AssistantInkeepAdapter | AssistantOpenAICompatibleAdapter;
+/**
+ * Error params for `ai.assistant`: 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 assistantMovedFieldsHint: {
+    error: (issue: z.core.$ZodRawIssue) => string | undefined;
+};
+/**
+ * `ai.assistant.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 assistantAdapterSchema: 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.assistant.provider` descriptor. */
+export type AssistantAdapterConfig = z.output<typeof assistantAdapterSchema>;
+export type AssistantAdapterKind = AssistantAdapterConfig["kind"];
+/** The provider when `ai.assistant.provider` is unset: the gateway with its defaults. */
+export declare const DEFAULT_ASSISTANT_PROVIDER: AssistantAdapter;
+/** 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: AssistantAdapterKind;
+    /** 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.assistant.provider` descriptor into its backend. */
+export declare const resolveAskBackend: (provider?: AssistantAdapterConfig) => 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 @@
+/**
+ * Assistant provider adapters for `blume.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { openrouter } from "blume/ai";
+ *
+ * export default defineConfig({
+ *   ai: {
+ *     assistant: {
+ *       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 { AssistantAdapter, AssistantAdapterOptions, AssistantGatewayAdapter, AssistantGatewayOptions, AssistantInkeepAdapter, AssistantInkeepOptions, AssistantLlmGatewayAdapter, AssistantLlmGatewayOptions, AssistantOpenAICompatibleAdapter, AssistantOpenAICompatibleOptions, AssistantOpenRouterAdapter, AssistantOpenRouterOptions, AssistantProviderOptions, AssistantReasoning, } 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;

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

@@ -0,0 +1,16 @@
+/**
+ * Static metadata for the MCP tools Blume exposes. Shared by the server (which
+ * pairs each entry with a Zod input schema and handler) and the `.well-known`
+ * discovery documents, so tool names and descriptions never drift between the
+ * live server and its advertised capabilities.
+ */
+export interface McpToolMeta {
+    annotations: {
+        openWorldHint: boolean;
+        readOnlyHint: boolean;
+    };
+    description: string;
+    name: string;
+    title: string;
+}
+export declare const MCP_TOOLS: McpToolMeta[];

package/dist/types/ai/openapi-components.d.ts

@@ -0,0 +1,43 @@
+import type { OpenApiData } from "../openapi/model.ts";
+/**
+ * Agent-facing Markdown for the components a generated reference page is made
+ * of: `<Operation>`, `<ApiTagOperations>` and `<ApiOverview>`.
+ *
+ * `render-mdx.ts` builds each reference page as the operation's description in
+ * the body plus one of these components, deliberately: the structured UI is the
+ * component's job, and the prose stays Markdown so it indexes. That split is
+ * right for the rendered page and lossy everywhere else — `<route>.md`,
+ * llms-full.txt, MCP `get_page` and the assistant corpus all downlevel components
+ * to Markdown, and these three had no serializer, so an operation page reached
+ * an agent as its description followed by a bare tag. On a site whose reference
+ * is most of the corpus, that is most of the corpus: measured on one 449-page
+ * site, 266 pages and 266 raw `<Operation>` in llms-full.txt, so "which
+ * endpoint do I call?" had no answer anywhere in the agent surface.
+ *
+ * Each serializer emits what its component renders and no more: the endpoint
+ * in the spec kind's own notation ({@link operationSignature}), the version and
+ * addresses the overview shows ({@link specAddresses}), the linked list a tag
+ * section shows. Parameters, schemas and responses are deliberately left out:
+ * those are `operation-model.ts` plus each component's own preparation, and a
+ * second implementation here would be free to disagree with the page. The
+ * endpoint and what it does is the part that was missing altogether.
+ *
+ * `specs` is the parsed `blume:openapi` data — empty when the project has no
+ * API reference, in which case every serializer declines.
+ */
+export declare const openapiComponentSerializers: (specs: OpenApiData) => {
+    /**
+     * The spec-level block at the top of the overview page: its version and
+     * where the API lives. The tag sections that follow are real Markdown
+     * headings over `<ApiTagOperations>`, so they downlevel on their own.
+     */
+    ApiOverview: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
+    /** One tag's operations, mirroring the list the rendered page shows. */
+    ApiTagOperations: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
+    /**
+     * One operation. Declines when the spec carries no such key — Blume's own
+     * fallback, which leaves the JSX visible rather than publishing a page that
+     * silently lost its endpoint.
+     */
+    Operation: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
+};

package/dist/types/ai/relative-links.d.ts

@@ -0,0 +1,26 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+/**
+ * Relative page links on the agent surfaces — the `.md`/`.mdx` mirrors,
+ * llms-full.txt, MCP `get_page` and `resources/read`. An agent resolves
+ * `[Install](./install)` against the URL it fetched (`/guides.md`), so the
+ * link lands on `/install`; the rendered page rewrites it to the route it
+ * means (`markdown/relative-links.ts`), and the Markdown an agent reads gets
+ * the same rewrite from the same resolver (`resolveRelativeHref`), so both
+ * point at one page. Inline links and reference definitions are rewritten;
+ * fenced and inline code, images, and anything not a relative page link are
+ * left as written.
+ */
+/** The page a Markdown text was written for. */
+export interface LinkedPage {
+    route: string;
+    sourcePath?: string;
+}
+/** Rewrite a page's relative page links to the routes they mean. */
+export type RelativeLinkRewriter = (text: string, page: LinkedPage) => string;
+/**
+ * Build the rewriter for a project: the file → route lookup a `.md`/`.mdx`
+ * link resolves through is built once. A file shared by every locale
+ * publishes once per locale, and the default locale's route stands for it;
+ * fallback copies render another locale's file, so they never stand for one.
+ */
+export declare const relativeLinkRewriter: (project: BlumeProject) => RelativeLinkRewriter;