blume 2.0.2 → 2.1.0

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

@@ -34,9 +34,24 @@ export interface AssistantAdapterOptions {
      */
     providerOptions?: AssistantProviderOptions;
 }
+/** The shared option schema, with the adapter's own key env var default. */
+export declare const sharedOptions: (apiKeyEnv: string) => {
+    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>>>;
+};
+export declare const GATEWAY_API_KEY_ENV = "AI_GATEWAY_API_KEY";
 /** Options for {@link gateway}. */
 export interface AssistantGatewayOptions extends AssistantAdapterOptions {
-    /** A `provider/model` id routed by the gateway. Defaults to `openai/gpt-5.5`. */
+    /**
+     * Narration only: how the voice should sound, for speech models that take
+     * instructions ("Read calmly, like a teacher").
+     */
+    instructions?: string;
+    /**
+     * A `provider/model` id routed by the gateway. Defaults to `openai/gpt-5.5`
+     * for the assistant and `openai/tts-1-hd` for narration.
+     */
     model?: string;
     /**
      * How much the model reasons before answering. Sent as the AI SDK's
@@ -45,6 +60,8 @@ export interface AssistantGatewayOptions extends AssistantAdapterOptions {
      * offer the level you pick. Omitted keeps the model's default.
      */
     reasoning?: AssistantReasoning;
+    /** Narration only: the speech model's voice. Defaults to `alloy`. */
+    voice?: string;
 }
 export type AssistantGatewayAdapter = AdapterDescriptor<"gateway", AssistantGatewayOptions>;
 export declare const gatewayAdapterSchema: z.ZodObject<{
@@ -67,12 +84,193 @@ export declare const gatewayAdapterSchema: z.ZodObject<{
     runtimeDeps: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
 /**
- * Route the assistant through the Vercel AI Gateway (the default). `model` is a
+ * Route the assistant through the Vercel AI Gateway (the default), or generate
+ * narration audio with one of its speech models. `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 openai}. */
+export interface AssistantOpenAIOptions extends AssistantAdapterOptions {
+    /**
+     * An OpenAI-compatible endpoint to call instead of OpenAI
+     * (`https://llm.internal.example.com/v1`): a self-hosted model or an
+     * internal gateway. The route then talks Chat Completions through
+     * `@ai-sdk/openai-compatible`, and the docs tools are off unless
+     * `ai.assistant.tools` turns them on, since the model may not call tools.
+     */
+    baseUrl?: string;
+    /** The model id (`gpt-5.5`). */
+    model: string;
+    /**
+     * The provider name the AI SDK reports, which a custom endpoint also reads
+     * its `providerOptions` under. Defaults to `openai`, or `openai-compatible`
+     * with a `baseUrl`.
+     */
+    name?: string;
+    /**
+     * How much the model reasons before answering, sent as `reasoning_effort`;
+     * with a `baseUrl`, the endpoint has to accept that parameter. Omitted
+     * keeps the model's default.
+     */
+    reasoning?: AssistantReasoning;
+}
+export type AssistantOpenAIAdapter = AdapterDescriptor<"openai", AssistantOpenAIOptions>;
+export declare const openaiAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"openai">;
+    options: z.ZodObject<{
+        baseUrl: z.ZodOptional<z.ZodURL>;
+        model: z.ZodString;
+        name: z.ZodOptional<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 to OpenAI, or to any OpenAI-compatible endpoint with
+ * `baseUrl`. Reads `OPENAI_API_KEY` and needs `@ai-sdk/openai` installed; a
+ * custom endpoint needs `@ai-sdk/openai-compatible` instead, since most
+ * don't serve OpenAI's Responses API.
+ */
+export declare const openai: (options: AssistantOpenAIOptions) => AssistantOpenAIAdapter;
+/**
+ * Options for the deprecated {@link openaiCompatible}: {@link openai}'s, with
+ * the endpoint and its key env var required.
+ *
+ * @deprecated Use {@link AssistantOpenAIOptions}.
+ */
+export interface AssistantOpenAICompatibleOptions extends AssistantOpenAIOptions {
+    apiKeyEnv: string;
+    baseUrl: string;
+}
+/** @deprecated Use {@link AssistantOpenAIAdapter}. */
+export type AssistantOpenAICompatibleAdapter = AssistantOpenAIAdapter;
+/**
+ * Route the assistant through an OpenAI-compatible endpoint.
+ *
+ * @deprecated Use `openai({ baseUrl, model, apiKeyEnv })`, which this calls.
+ */
+export declare const openaiCompatible: (options: AssistantOpenAICompatibleOptions) => AssistantOpenAIAdapter;
+/** Options for {@link anthropic}. */
+export interface AssistantAnthropicOptions extends AssistantAdapterOptions {
+    /** The Claude model id (`claude-sonnet-5`). */
+    model: string;
+    /**
+     * How much the model reasons before answering. The Anthropic provider
+     * maps the level to the model's thinking: an effort on models with
+     * adaptive thinking, a thinking budget on older ones, and thinking off for
+     * `"none"`. Omitted keeps the model's default.
+     */
+    reasoning?: AssistantReasoning;
+}
+export type AssistantAnthropicAdapter = AdapterDescriptor<"anthropic", AssistantAnthropicOptions>;
+export declare const anthropicAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"anthropic">;
+    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 to Anthropic's Claude API. Reads `ANTHROPIC_API_KEY`
+ * and needs `@ai-sdk/anthropic` installed.
+ */
+export declare const anthropic: (options: AssistantAnthropicOptions) => AssistantAnthropicAdapter;
+/** Options for {@link gemini}. */
+export interface AssistantGeminiOptions extends AssistantAdapterOptions {
+    /** The Gemini model id (`gemini-3.5-flash`). */
+    model: string;
+    /**
+     * How much the model reasons before answering. The Google provider maps
+     * the level to the model's thinking level, or to a thinking budget on
+     * models that take one. Omitted keeps the model's default.
+     */
+    reasoning?: AssistantReasoning;
+}
+export type AssistantGeminiAdapter = AdapterDescriptor<"gemini", AssistantGeminiOptions>;
+export declare const geminiAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"gemini">;
+    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 to Google's Gemini API. Reads `GEMINI_API_KEY` and
+ * needs `@ai-sdk/google` installed.
+ */
+export declare const gemini: (options: AssistantGeminiOptions) => AssistantGeminiAdapter;
+/** Options for {@link grok}. */
+export interface AssistantGrokOptions extends AssistantAdapterOptions {
+    /** The Grok model id (`grok-4.7`). */
+    model: string;
+    /**
+     * How much the model reasons before answering, sent as xAI's reasoning
+     * effort on the models that take one. Omitted keeps the model's default.
+     */
+    reasoning?: AssistantReasoning;
+}
+export type AssistantGrokAdapter = AdapterDescriptor<"grok", AssistantGrokOptions>;
+export declare const grokAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"grok">;
+    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 to xAI's Grok models. Reads `XAI_API_KEY` and needs
+ * `@ai-sdk/xai` installed.
+ */
+export declare const grok: (options: AssistantGrokOptions) => AssistantGrokAdapter;
 /** Options for {@link openrouter}. */
 export interface AssistantOpenRouterOptions extends AssistantAdapterOptions {
     /** The OpenRouter model id (`anthropic/claude-sonnet-4-5`). */
@@ -176,53 +374,8 @@ export declare const inkeepAdapterSchema: z.ZodObject<{
  * 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;
+/** Which backend answers the assistant: the value of `gateway()`, `openai()`, … */
+export type AssistantAdapter = AssistantGatewayAdapter | AssistantOpenAIAdapter | AssistantAnthropicAdapter | AssistantGeminiAdapter | AssistantGrokAdapter | AssistantOpenRouterAdapter | AssistantLlmGatewayAdapter | AssistantInkeepAdapter;
 /**
  * Error params for `ai.assistant`: a 1.x flat provider field (`model`, `apiKeyEnv`,
  * `baseUrl`, `headers`, `reasoning`) names the adapter call it moves into —
@@ -256,9 +409,11 @@ export declare const assistantAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     requiredSecrets: z.ZodArray<z.ZodString>;
     runtimeDeps: z.ZodArray<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"openrouter">;
+    kind: z.ZodLiteral<"openai">;
     options: z.ZodObject<{
+        baseUrl: z.ZodOptional<z.ZodURL>;
         model: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
         reasoning: z.ZodOptional<z.ZodEnum<{
             none: "none";
             minimal: "minimal";
@@ -274,9 +429,8 @@ export declare const assistantAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     requiredSecrets: z.ZodArray<z.ZodString>;
     runtimeDeps: z.ZodArray<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"llmgateway">;
+    kind: z.ZodLiteral<"anthropic">;
     options: z.ZodObject<{
-        baseUrl: z.ZodDefault<z.ZodURL>;
         model: z.ZodString;
         reasoning: z.ZodOptional<z.ZodEnum<{
             none: "none";
@@ -293,10 +447,35 @@ export declare const assistantAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     requiredSecrets: z.ZodArray<z.ZodString>;
     runtimeDeps: z.ZodArray<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"inkeep">;
+    kind: z.ZodLiteral<"gemini">;
+    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<"grok">;
     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>>>;
@@ -304,12 +483,9 @@ export declare const assistantAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     requiredSecrets: z.ZodArray<z.ZodString>;
     runtimeDeps: z.ZodArray<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"openai-compatible">;
+    kind: z.ZodLiteral<"openrouter">;
     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";
@@ -318,6 +494,37 @@ export declare const assistantAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
             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>;
@@ -357,6 +564,12 @@ export interface AskBackendTemplate {
 export interface AskBackend {
     /** Whether Blume grounds answers in the docs (Inkeep retrieves itself). */
     grounded: boolean;
+    /**
+     * Whether the docs tools are on when `ai.assistant.tools` is unset: yes for
+     * the hosted model catalogs, whose models call tools, and no for an
+     * OpenAI-compatible backend, which may be a local model that can't.
+     */
+    toolsByDefault: boolean;
     kind: AssistantAdapterKind;
     /** Human-readable adapter name for diagnostics ("AI Gateway"). */
     label: string;

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

@@ -19,6 +19,6 @@
  * 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 { anthropic, gateway, gemini, grok, inkeep, llmgateway, openai, openaiCompatible, openrouter, } from "./ask.ts";
+export type { AssistantAdapter, AssistantAdapterOptions, AssistantAnthropicAdapter, AssistantAnthropicOptions, AssistantGatewayAdapter, AssistantGatewayOptions, AssistantGeminiAdapter, AssistantGeminiOptions, AssistantGrokAdapter, AssistantGrokOptions, AssistantInkeepAdapter, AssistantInkeepOptions, AssistantLlmGatewayAdapter, AssistantLlmGatewayOptions, AssistantOpenAIAdapter, AssistantOpenAICompatibleAdapter, AssistantOpenAICompatibleOptions, AssistantOpenAIOptions, AssistantOpenRouterAdapter, AssistantOpenRouterOptions, AssistantProviderOptions, AssistantReasoning, } from "./ask.ts";
 export type { AdapterDescriptor } from "../core/adapter.ts";

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

@@ -20,5 +20,12 @@ import type { ResolvedConfig } from "../core/schema.ts";
  * headers. Targets are
  * root-relative under `deployment.base` — RFC 8288 resolves them against the
  * request URL. Returns null when nothing is advertisable.
+ *
+ * `surface` is where the header is sent. A deployed site (`"build"`) serves
+ * every target. The dev server (`"dev"`) serves the routes — the JSON API's
+ * OpenAPI document and the Markdown mirror — but not the files `blume build`
+ * writes after the build (the API and AI catalogs, `agent-readability.json`,
+ * `llms.txt`), so its header leaves those out rather than point agents at
+ * 404s.
  */
-export declare const buildHomeLinkHeader: (config: ResolvedConfig, routePaths: readonly string[]) => string | null;
+export declare const buildHomeLinkHeader: (config: ResolvedConfig, routePaths: readonly string[], surface?: "build" | "dev") => string | null;

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

@@ -23,9 +23,12 @@ import type { OpenApiData } from "../openapi/model.ts";
  * 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.
+ * API reference, in which case every serializer declines. `deployBase` is the
+ * configured `deployment.base`: operation routes carry `basePath` but not it,
+ * and the links written here are made after the agent surfaces rebase the
+ * page's own links, so they take it here, as the rendered page's do.
  */
-export declare const openapiComponentSerializers: (specs: OpenApiData) => {
+export declare const openapiComponentSerializers: (specs: OpenApiData, deployBase?: string) => {
     /**
      * 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

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

@@ -6,14 +6,16 @@ import type { BlumeProject } from "../core/project-graph.ts";
  * 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. Root-relative page links (`[x](/guide)`,
- * `<Card href="/guide">`) get what the rendered page gives them too: the
- * `deployment.base` + `basePath` prefix (`markdown/base-links.ts`,
- * `components/content/base-href.ts`) and, on a page in a prefixed locale,
+ * point at one page. Root-relative links (`[x](/guide)`,
+ * `<Card href="/guide">`, `![logo](/logo.png)`) get what the rendered page
+ * gives them too (`markdown/base-links.ts`,
+ * `components/content/base-href.ts`): a page link the `deployment.base` +
+ * `basePath` prefix, a public file (`/spec.pdf`) or image the
+ * `deployment.base` alone, and, on a page in a prefixed locale, a page link
  * that locale's copy of the route when it is served
- * (`components/layout/LocaleLinks.astro`). Inline links, component `href`s,
- * and reference definitions are rewritten; fenced and inline code, images,
- * asset links, and external URLs are left as written.
+ * (`components/layout/LocaleLinks.astro`). Inline links, images, component
+ * `href`s, and reference definitions are rewritten; fenced and inline code,
+ * relative images and asset links, and external URLs are left as written.
  */
 /** The page a Markdown text was written for. */
 export interface LinkedPage {

package/dist/types/ai/site-skill.d.ts

@@ -0,0 +1,26 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { SkillArtifact } from "./skills.ts";
+/**
+ * The site's own agent skill (`agents.skillMd`): a `SKILL.md` in the Agent
+ * Skills format, built from what the build already knows — the site's title
+ * and description, how to read any page as Markdown, llms.txt and the MCP
+ * server, the API references, and a map of the docs with each page's one-line
+ * description. No model writes it, so it costs nothing and is current with
+ * every build: a guide to the docs rather than a summary of the product. A
+ * hand-written skill of the same name in `agents.skills` replaces it.
+ */
+/** The most pages the map lists; llms.txt holds the rest. */
+export declare const MAX_SKILL_PAGES = 200;
+/** Where the site skill is served besides the discovery index. */
+export declare const SKILL_MD_PATH = "/skill.md";
+/**
+ * The site skill's name: the title as a skill name (lowercase alphanumerics
+ * and single hyphens), else the site's host, for a title with no Latin
+ * letters in it.
+ */
+export declare const siteSkillName: (project: BlumeProject) => string;
+/**
+ * The generated site skill, or `null` when `agents.skillMd` is off or there
+ * is no `deployment.site` to make its links absolute.
+ */
+export declare const buildSiteSkill: (project: BlumeProject) => SkillArtifact | null;

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

@@ -10,6 +10,8 @@ import type { ResolvedConfig } from "../core/schema.ts";
  */
 export declare const AGENT_SKILLS_DIR = "/.well-known/agent-skills";
 export declare const AGENT_SKILLS_INDEX_PATH = "/.well-known/agent-skills/index.json";
+/** The Agent Skills spec caps `description` at 1024 characters. */
+export declare const SKILL_DESCRIPTION_MAX = 1024;
 /** One publishable skill artifact plus its index entry. */
 export interface SkillArtifact {
     /** Raw bytes to publish (the digest is computed over exactly these). */
@@ -32,9 +34,26 @@ export interface CollectedSkills {
  * hold a `SKILL.md` (the layout `npx skills add` consumes). Subdirectories
  * without one are ignored silently — the directory may hold other assets —
  * while a present-but-invalid skill earns a warning so it isn't dropped
- * behind the publisher's back.
+ * behind the publisher's back. Two directories declaring the same `name`
+ * would publish to the same artifact path under two index entries, so the
+ * first directory in sorted order keeps the name and the other is skipped
+ * with a warning naming both.
  */
 export declare const collectSkills: (dir: string) => Promise<CollectedSkills>;
+/** A skill that is one `SKILL.md`, published verbatim. */
+export declare const skillMdArtifact: (name: string, description: string, markdown: string) => SkillArtifact;
+/**
+ * Whether the build generates the site's own skill (`agents.skillMd`): on,
+ * and with a `deployment.site` to make its links absolute, since an installed
+ * skill is read away from the site.
+ */
+export declare const generatesSiteSkill: (config: ResolvedConfig) => boolean;
+/**
+ * Whether a skills discovery index is served: from `agents.skills`, or for
+ * the generated site skill alone. On an advertised config (see
+ * `advertisedConfig`), both are already switched off when nothing published.
+ */
+export declare const servesSkillsIndex: (config: ResolvedConfig) => boolean;
 /**
  * The discovery index (v0.2.0 schema). Artifact URLs are path-absolute under
  * `deployment.base` — the RFC resolves them against the index origin.

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

@@ -18,8 +18,6 @@ export interface TarEntry {
 }
 /**
  * Build a gzipped ustar archive of the given files, in the given order. Paths
- * longer than the ustar `name` field or escaping the archive root throw to
- * surface a programming error — nanotar would silently truncate an oversized
- * name into a corrupt archive, so the validation stays here.
+ * escaping the archive root throw to surface a programming error.
  */
 export declare const buildTarGz: (entries: readonly TarEntry[]) => Uint8Array;

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

@@ -48,6 +48,8 @@ export { logrocket } from "./logrocket.ts";
 export type { LogrocketAdapter, LogrocketOptions } from "./logrocket.ts";
 export { mixpanel } from "./mixpanel.ts";
 export type { MixpanelAdapter, MixpanelOptions, MixpanelRegion, } from "./mixpanel.ts";
+export { oneDollarStats } from "./one-dollar-stats.ts";
+export type { OneDollarStatsAdapter, OneDollarStatsOptions, } from "./one-dollar-stats.ts";
 export { pirsch } from "./pirsch.ts";
 export type { PirschAdapter, PirschOptions } from "./pirsch.ts";
 export { plausible } from "./plausible.ts";

package/dist/types/analytics/one-dollar-stats.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** The script OneDollarStats' install snippet loads. */
+export declare const ONE_DOLLAR_STATS_SCRIPT_SRC = "https://assets.onedollarstats.com/stonks.js";
+/** The options {@link oneDollarStats} checks itself. */
+export interface OneDollarStatsNamedOptions {
+    /**
+     * A bare host name, e.g. `docs.example.com`. The tracker reports every
+     * event under it on every host, not just `localhost`.
+     */
+    hostname?: string;
+}
+/**
+ * Options for {@link oneDollarStats}: any tracker setting, forwarded as a
+ * `data-` attribute on the tag (`hostname` → `data-hostname`, `devmode`,
+ * `url`, `autocollect`, `"hash-routing"`, …).
+ */
+export type OneDollarStatsOptions = OneDollarStatsNamedOptions & {
+    [setting: string]: string;
+};
+export declare const oneDollarStatsOptionsSchema: z.ZodObject<{
+    hostname: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodString>>;
+export type OneDollarStatsAdapter = AdapterDescriptor<"one-dollar-stats", OneDollarStatsOptions>;
+export declare const oneDollarStatsAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"one-dollar-stats">;
+    options: z.ZodObject<{
+        hostname: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodString>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * OneDollarStats. Needs no keys — the dashboard matches events to a site by
+ * the domain they come from.
+ */
+export declare const oneDollarStats: (options?: OneDollarStatsOptions) => OneDollarStatsAdapter;
+/**
+ * The deferred tag from the install instructions, with every option as its
+ * own `data-` attribute. The tracker reads them from `document.currentScript`,
+ * so the tag stays a classic external script. It hooks `pushState` and
+ * `popstate` itself, so client-router navigations need no extra hook.
+ *
+ * The tracker turns hash routing on whenever `data-hash-routing` is present,
+ * whatever its value, so `"hash-routing": "false"` leaves the attribute off.
+ */
+export declare const oneDollarStatsHead: (options: OneDollarStatsOptions) => HeadScript[];

package/dist/types/analytics/schema.d.ts

@@ -106,6 +106,13 @@ export declare const analyticsAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     }, z.core.$catchall<z.ZodJSONSchema>>;
     requiredSecrets: z.ZodArray<z.ZodString>;
     runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"one-dollar-stats">;
+    options: z.ZodObject<{
+        hostname: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodString>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"pirsch">;
     options: z.ZodObject<{
@@ -275,6 +282,13 @@ export declare const analyticsConfigSchema: z.ZodDefault<z.ZodArray<z.ZodDiscrim
     }, z.core.$catchall<z.ZodJSONSchema>>;
     requiredSecrets: z.ZodArray<z.ZodString>;
     runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"one-dollar-stats">;
+    options: z.ZodObject<{
+        hostname: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodString>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"pirsch">;
     options: z.ZodObject<{