blume 2.0.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "The open-source docs framework for humans and agents.",
   "keywords": [
     "agents",

package/skills/blume/SKILL.md

@@ -12,7 +12,7 @@ The core idea: **the framework _is_ the template.** There's no starter to clone
 ## What makes it different
 
 - **Fast by default** — Static HTML on Astro/Vite. The core theme ships no client framework JS so pages score well on Core Web Vitals out of the box. You opt into server features only when you need them.
-- **AI-ready out of the box** — Emits `llms.txt`/`llms-full.txt`, serves any page's raw Markdown by appending `.md` to its URL, publishes a JSON docs API (`/api/docs/…`) described by an OpenAPI document at `/openapi.json`, offers **Copy as Markdown** and **Open in chat** on every page, and can host an optional **Ask AI** assistant or an **MCP server** so coding agents read your docs directly.
+- **AI-ready out of the box** — Emits `llms.txt`/`llms-full.txt`, serves any page's raw Markdown by appending `.md` to its URL, publishes a JSON docs API (`/api/docs/…`) described by an OpenAPI document at `/openapi.json`, offers **Copy as Markdown** and **Open in chat** on every page, and can host an optional in-page **assistant** or an **MCP server** so coding agents read your docs directly.
 - **Zero configuration — even the template** — A folder of docs is a complete project. Navigation is inferred from files, search works in dev and production with no hosted service, and theming is a handful of tokens.
 - **Type-safe to the core** — `blume.config.ts` and every `meta.ts` are real TypeScript, validated by a schema and authored with `defineConfig` and `defineMeta`. Your editor autocompletes options and catches mistakes before a build.
 
@@ -49,23 +49,23 @@ Navigation, search, and page metadata are inferred from your files as you add th
 
 ## Upgrading from Blume 1
 
-Blume 2 changes configuration, not content: search, deployment, content sources, API references, analytics, and the Ask AI backend become adapters imported from `blume/*` subpaths (`search: algolia({ … })` from `blume/search`), the machine-readable settings move from `ai` to `agents`, and `components.ts` entries must be static. From the folder with `blume.config.ts`, run:
+Blume 2 changes configuration, not content: search, deployment, content sources, API references, analytics, and the assistant's model backend become adapters imported from `blume/*` subpaths (`search: algolia({ … })` from `blume/search`), Ask AI is renamed the assistant (`ai.ask` becomes `ai.assistant`), the machine-readable settings move from `ai` to `agents`, and `components.ts` entries must be static. From the folder with `blume.config.ts`, run:
 
 ```bash
 npx blume@latest upgrade
 ```
 
-It bumps `blume` in `package.json`, installs, and lists every config change still needed with its file, line, and replacement (plus `package.json` scripts that pass removed `blume build` flags, and pages whose frontmatter sets a removed field), exiting non-zero until none are left — rerun it after each round of fixes. (`--claude` or `--codex` hands that list to an agent CLI from a terminal.) When you are the agent doing the upgrade, work from that list and the upgrade guide, `docs/03-upgrading.mdx` in the installed package, which has before-and-after examples for every change. Keep the site's behavior the same, and verify with `blume doctor` and `blume build`.
+It bumps `blume` in `package.json`, installs, and lists every config change still needed with its file, line, and replacement (plus `package.json` scripts that pass removed `blume build` flags, and pages whose frontmatter sets a removed field), exiting non-zero until none are left — rerun it after each round of fixes. (`--codex` or `--claude` hands that list to an agent CLI from a terminal.) When you are the agent doing the upgrade, work from that list and the upgrade guide, `docs/03-upgrading.mdx` in the installed package, which has before-and-after examples for every change. Keep the site's behavior the same, and verify with `blume doctor` and `blume build`.
 
 ## Migrating from another framework
 
-To move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume, the user runs `npx blume migrate [source] --claude` (or `--codex`) from that project, which opens an agent on the `blume-migrate` skill. When you are that agent, or the user asks you to migrate directly, follow `skills/blume-migrate/SKILL.md` in the installed package instead of this file.
+To move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume, the user runs `npx blume migrate [source] --codex` (or `--claude`) from that project, which opens an agent on the `blume-migrate` skill. When you are that agent, or the user asks you to migrate directly, follow `skills/blume-migrate/SKILL.md` in the installed package instead of this file.
 
 ## What's included
 
 - **Components** — callouts, cards, steps, tabs, accordions, badges, file trees, and parameter tables, usable in MDX with no imports.
 - **Local search** — Orama in dev and production, with no hosted index; Pagefind, Algolia, and other backends are one adapter away (`search: pagefind()` from `blume/search`).
-- **AI** — `llms.txt`, raw Markdown URLs, a JSON docs API with an OpenAPI description, Copy as Markdown, Open in chat, an Ask AI assistant, and an MCP server endpoint served by the docs site itself.
+- **AI** — `llms.txt`, raw Markdown URLs, a JSON docs API with an OpenAPI description, Copy as Markdown, Open in chat, an in-page assistant, and an MCP server endpoint served by the docs site itself.
 - **Navigation** — inferred from files, refined with `meta.ts` or config.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD.
 - **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.

package/skills/blume-migrate/SKILL.md

@@ -69,8 +69,8 @@ The single biggest shift for most sources — especially Mintlify — is that **
 - **`content`:** `root` (default `"docs"`, relative to the project dir where `blume` runs), `include`/`exclude` (arrays of globs **relative to `content.root`**; defaults `["**/*.{md,mdx}"]` / `["**/_*", "**/.*"]`), `sources` (an array of **adapters imported from `blume/sources`**: `filesystem({ root, include, exclude })`, `obsidian({ vault })`, `githubReleases({ owner, repo })`, `notion({ database })`, `sanity({ projectId, dataset, query })`, `contentful({ space, contentType })`, `payload({ url, collection })`, `strapi({ url, contentType })`, `mdxRemote({ github })`, `custom(source)`; every factory with an options object also takes `prefix` and `pollInterval`, while `custom(source)` takes a `ContentSource` instance that sets its own `prefix`. The 1.x `{ type: "…" }` objects were removed — rename `type` to the factory call and pass the other fields as its options — except `{ type: "custom", source }`, which becomes `custom(source)` with the instance as the only argument. `root`/`include`/`exclude` are shorthand for a single `filesystem()` and are **rejected beside `sources`** — move them into the `filesystem()` entry. OpenAPI/AsyncAPI/GraphQL are **not** among these; they're adapters in the top-level `reference` list), `pages` (custom `.astro` dir), `defaultType`. When docs sit directly under the project dir (no `docs/` subfolder), set `root` there and **scope `include` to the real content folders** instead of scanning everything — `references/monorepo.md` §1.
 - **`basePath`** (top-level): a site-wide mount point (e.g. `"/docs"`) prepended to **every** route while staying invisible to the sidebar (no wrapper group). This is the right target for a source that served all docs under a prefix (Docusaurus `routeBasePath`, a Fumadocs `baseUrl` of `/docs`) — distinct from a per-source `prefix` (which adds a nav group) and from `deployment.base` (host subdirectory).
 - **`navigation`:** `tabs`, `selectors`, `actions` and `cta` (header links and the one filled button), `featured` (links pinned above the sidebar on every route), `sidebar` (`{ display, items }` — `display` is the global render mode above; `items` is an explicit tree), `repo` (`true`/`false`, or an absolute GitHub URL for the header mark when the docs repo is private and `github` must stay unset). **Avoid an explicit `navigation.sidebar` unless you have to** — lean on the filesystem-derived sidebar. It only works when the file tree roughly matches the intended sidebar layout, so reshape folders to match first; reach for `sidebar.items` only for a shape files genuinely can't express (see "Config-declared nesting" above).
-- **`search`** — an adapter imported from `blume/search`: `orama()` (default, so omit `search` entirely for it), `flexsearch()`, `pagefind()`, `algolia({ appId, apiKey, indexName })`, `oramaCloud({ endpoint, apiKey, indexId? })`, `typesense({ host, collection, apiKey })`, `mixedbread({ storeId })`, or `false` to disable. Pass the adapter directly (`search: algolia({…})`) or as `search: { provider, popular, indexing }` when you also set curated links or indexing options. **Blume 1.x's `search.provider` string and its `search.algolia`/`oramaCloud`/`typesense`/`mixedbread` credential blocks are gone** — when a source config (or an older `blume.config.ts`) has `provider: "algolia", algolia: { appId, indexName, searchApiKey }`, rewrite it as `search: algolia({ appId, indexName, apiKey: searchApiKey })` (the search-only key is now `apiKey` in every adapter that takes one; admin keys stay in env vars). **`ai`** (Ask AI, Open in chat — `ai.ask.provider` takes an **adapter descriptor** imported from `blume/ai`: `gateway({ model })` (the default, `openai/gpt-5.5`), `openrouter({ model, reasoning })`, `llmgateway({ model })`, `inkeep({ model })`, or `openaiCompatible({ baseUrl, name, model, apiKeyEnv })`. Each adapter owns `model`, `apiKeyEnv`, `headers`, `reasoning`, and a verbatim `providerOptions` passthrough (`headers` values are written into the generated route source as-is, so they are for non-secret static headers only — a bearer token or any other credential belongs in the env var `apiKeyEnv` names, never in `headers`); there are **no** flat `provider`/`model`/`apiKeyEnv`/`baseUrl`/`headers`/`reasoning` fields on `ai.ask` — a source that configured Ask AI that way (Blume < 2.0 included) maps onto one adapter call. `enabled`, `instructions`, `retrieval`, `suggestions`, `cors`, and `endpoint` stay on `ai.ask`), **`agents`** (llms.txt, the JSON API, the MCP server, published skills, discovery manifests, robots content signals), **`reference`** (a list of adapters imported from `blume/reference` — `openapi({ spec | sources, route, … })`, `asyncapi({ … })`, `graphql({ spec, endpoint, … })` — never the 1.x `openapi`/`asyncapi`/`graphql` blocks), **`redirects`**, **`seo`**, **`markdown`**, **`analytics`** (a list of adapters imported from `blume/analytics` — one factory per provider (`posthog({ key, host })`, `googleAnalytics({ id })`, `plausible({ domain, host })`, `mixpanel({ token, region })`, `segment({ key })`, …; the docs page lists them all), `vercel()`, and `script({ src | content, strategy, attributes })` for anything without one — never an object keyed by provider), **`deployment`**, **`i18n`**, **`toc`**, **`lastModified`**, **`github`** (`{ owner, repo, branch?, dir?, host?, api? }` — set `host` whenever the source's edit URL is on a GitHub Enterprise origin rather than `github.com`).
-- **`deployment`** is a host adapter from `blume/deploy` — `vercel()`, `netlify()`, `cloudflare()`, or `node()` — or a plain `{ site, base }` for a static build on any host (the default is a static build). Naming a host adapter switches the build to **server output** on that host (pass `output: "static"` to stay static there); `site`, `base`, and `output` are the named options, and anything else is forwarded verbatim to the underlying `@astrojs/*` adapter. There is **no** `deployment.adapter` string and **no** `deployment.output` field: a source that needs server rendering (Ask AI, the MCP server, Mixedbread search, the API playground proxy) gets `import { vercel } from "blume/deploy"` and `deployment: vercel()`; a static source gets nothing — unless it served its docs under a subpath, which becomes `deployment: { base: "/docs" }` (leave `site` unset; see below). Note that `cloudflare` and `vercel` are also exported from `blume/analytics` — alias one (`import { cloudflare as cloudflareDeploy } from "blume/deploy"`) when a config uses both.
+- **`search`** — an adapter imported from `blume/search`: `orama()` (default, so omit `search` entirely for it), `flexsearch()`, `pagefind()`, `algolia({ appId, apiKey, indexName })`, `oramaCloud({ endpoint, apiKey, indexId? })`, `typesense({ host, collection, apiKey })`, `mixedbread({ storeId })`, or `false` to disable. Pass the adapter directly (`search: algolia({…})`) or as `search: { provider, popular, indexing }` when you also set curated links or indexing options. **Blume 1.x's `search.provider` string and its `search.algolia`/`oramaCloud`/`typesense`/`mixedbread` credential blocks are gone** — when a source config (or an older `blume.config.ts`) has `provider: "algolia", algolia: { appId, indexName, searchApiKey }`, rewrite it as `search: algolia({ appId, indexName, apiKey: searchApiKey })` (the search-only key is now `apiKey` in every adapter that takes one; admin keys stay in env vars). **`ai`** (the assistant, Open in chat — `ai.assistant.provider` takes an **adapter descriptor** imported from `blume/ai`: `gateway({ model })` (the default, `openai/gpt-5.5`), `openrouter({ model, reasoning })`, `llmgateway({ model })`, `inkeep({ model })`, or `openaiCompatible({ baseUrl, name, model, apiKeyEnv })`. Each adapter owns `model`, `apiKeyEnv`, `headers`, `reasoning`, and a verbatim `providerOptions` passthrough (`headers` values are written into the generated route source as-is, so they are for non-secret static headers only — a bearer token or any other credential belongs in the env var `apiKeyEnv` names, never in `headers`); there are **no** flat `provider`/`model`/`apiKeyEnv`/`baseUrl`/`headers`/`reasoning` fields on `ai.assistant` — a source that configured an AI assistant that way (Blume < 2.0 included) maps onto one adapter call. `enabled`, `instructions`, `retrieval`, `suggestions`, `cors`, and `endpoint` sit on `ai.assistant` itself; there is **no** `ai.ask` — Blume 2.0.0 and earlier used that name, so an older `blume.config.ts` moves the whole block to `ai.assistant`), **`agents`** (llms.txt, the JSON API, the MCP server, published skills, discovery manifests, robots content signals), **`reference`** (a list of adapters imported from `blume/reference` — `openapi({ spec | sources, route, … })`, `asyncapi({ … })`, `graphql({ spec, endpoint, … })` — never the 1.x `openapi`/`asyncapi`/`graphql` blocks), **`redirects`**, **`seo`**, **`markdown`**, **`analytics`** (a list of adapters imported from `blume/analytics` — one factory per provider (`posthog({ key, host })`, `googleAnalytics({ id })`, `plausible({ domain, host })`, `mixpanel({ token, region })`, `segment({ key })`, …; the docs page lists them all), `vercel()`, and `script({ src | content, strategy, attributes })` for anything without one — never an object keyed by provider), **`deployment`**, **`i18n`**, **`toc`**, **`lastModified`**, **`github`** (`{ owner, repo, branch?, dir?, host?, api? }` — set `host` whenever the source's edit URL is on a GitHub Enterprise origin rather than `github.com`).
+- **`deployment`** is a host adapter from `blume/deploy` — `vercel()`, `netlify()`, `cloudflare()`, or `node()` — or a plain `{ site, base }` for a static build on any host (the default is a static build). Naming a host adapter switches the build to **server output** on that host (pass `output: "static"` to stay static there); `site`, `base`, and `output` are the named options, and anything else is forwarded verbatim to the underlying `@astrojs/*` adapter. There is **no** `deployment.adapter` string and **no** `deployment.output` field: a source that needs server rendering (the assistant, the MCP server, Mixedbread search, the API playground proxy) gets `import { vercel } from "blume/deploy"` and `deployment: vercel()`; a static source gets nothing — unless it served its docs under a subpath, which becomes `deployment: { base: "/docs" }` (leave `site` unset; see below). Note that `cloudflare` and `vercel` are also exported from `blume/analytics` — alias one (`import { cloudflare as cloudflareDeploy } from "blume/deploy"`) when a config uses both.
 - **Don't set `deployment.site`.** Blume auto-fills it: the dev server's `localhost` URL in dev, and the deployment URL (`VERCEL_PROJECT_PRODUCTION_URL`/`VERCEL_URL`) on Vercel. Hardcoding it in `blume.config.ts` overrides that auto-detection and pins the wrong absolute URL (canonical links, sitemap, OG, llms.txt) everywhere but the one host you typed — so leave it unset even when a source config had a `url`/`site` field. (Sitemap still generates in production because the deploy URL is present there.)
 - **Favicon is a filename convention, not config.** Drop `icon.{svg,png,ico}` or `favicon.{svg,png,ico}` (and `apple-icon.png`) in the project root or `public/` — Blume auto-detects it. There is **no** `favicon` config field. A source favicon given as `{ light, dark }` maps to a filename pair: copy the light file to a conventional name (e.g. `public/icon.png`) and the dark file to its `-dark` sibling — same directory and extension, `-dark` before the extension (`public/icon-dark.png`). If the two files have different formats, convert one so the extensions match; only an exact sibling of the resolved icon is picked up.
 

package/src/ai/agent-readability.ts

@@ -34,7 +34,7 @@ const usagePolicy = (
 };
 
 /**
- * The advertised Ask AI URL. An external endpoint is not served under
+ * The advertised assistant URL. An external endpoint is not served under
  * `deployment.base`, so a root-relative one absolutizes against the site
  * origin alone; the built-in route gets site and base via `abs`.
  */
@@ -154,7 +154,7 @@ const wellKnownArtifacts = (
 /**
  * Build `agent-readability.json`: a root manifest that indexes the project's
  * agent-facing surface — llms.txt, the raw-Markdown mirrors, the JSON docs
- * API and its OpenAPI description, the MCP server, Ask AI, sitemap, and feeds
+ * API and its OpenAPI description, the MCP server, the assistant, sitemap, and feeds
  * — so agents can discover and cite the docs without
  * scraping HTML. URLs are absolute when a `site` is configured and root-relative
  * (still under `deployment.base`) otherwise. Returns null when the manifest is
@@ -194,8 +194,8 @@ export const buildAgentReadability = (
       url: abs(config.agents.mcp.route),
     };
   }
-  if (config.ai.ask?.enabled) {
-    artifacts.askApi = askApiUrl(config.ai.ask.endpoint, site, abs);
+  if (config.ai.assistant?.enabled) {
+    artifacts.askApi = askApiUrl(config.ai.assistant.endpoint, site, abs);
   }
   Object.assign(artifacts, wellKnownArtifacts(config, abs));
   if (site && config.seo.sitemap) {

package/src/ai/api/paths.ts

@@ -1,7 +1,7 @@
 /**
  * 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
+ * Under `/api/` alongside the assistant 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.
  */

package/src/ai/ask-context.ts

@@ -4,7 +4,7 @@ import type { FenceState } from "../core/code-fences.ts";
 import { buildOramaIndex, queryOramaIndex } from "../search/orama-index.ts";
 import type { OramaDoc } from "../search/orama-index.ts";
 
-/** A chat message as posted by the Ask AI island (`{ role, content }`). */
+/** A chat message as posted by the assistant island (`{ role, content }`). */
 export interface AskMessage {
   content: string;
   role: string;
@@ -16,7 +16,7 @@ export interface AskPage {
 }
 
 /**
- * The self-contained snapshot the grounded Ask AI endpoint imports. Bundles the
+ * The self-contained snapshot the assistant's grounded endpoint imports. Bundles the
  * search documents so retrieval works regardless of the configured search
  * provider and needs no filesystem access at request time. Serialized to
  * `generated/ask-data.json` and built by {@link buildAskData}.
@@ -47,7 +47,7 @@ const CONTEXT_BUDGET = 10_000;
 const MIN_EXCERPT_CHARS = 200;
 
 /**
- * How much retrieved documentation a question carries (the `ai.ask.retrieval`
+ * How much retrieved documentation a question carries (the `ai.assistant.retrieval`
  * config). Every field falls back to the built-in default, so a partial object
  * only changes what it names. Injected characters dominate time-to-first-token
  * on a self-hosted backend, and the three knobs aren't interchangeable: the
@@ -309,7 +309,7 @@ const interleave = (lists: OramaDoc[][], limit: number): OramaDoc[] => {
  *
  * Pages are indexed whole (one document each), so a naive head slice of a long
  * page returns its intro and misses sections below the fold — the exact failure
- * where "How does Ask AI work?" retrieves the right page but only sees its
+ * where "How does the assistant work?" retrieves the right page but only sees its
  * opening paragraph. This centers the window on the densest cluster of query
  * terms so the injected text is the part that actually answers the question.
  * Exported for testing; {@link createAskContext} is the runtime entry point.
@@ -585,7 +585,7 @@ export const sectionExcerpt = (
 ): string => excerptPage(parsePage(content), query, max);
 
 /**
- * Build the request-time grounding function for the Ask AI endpoint.
+ * Build the request-time grounding function for the assistant endpoint.
  *
  * Lexical retrieval over Orama (the same index/ranking the search dialog and MCP
  * server use). The index is built once and memoized across requests. Returns a
@@ -593,12 +593,12 @@ export const sectionExcerpt = (
  * viewing — or `undefined` when there is nothing to ground on, so the endpoint
  * can fall back to its plain prompt.
  *
- * `options.instructions` (the `ai.ask.instructions` config) is appended after
+ * `options.instructions` (the `ai.assistant.instructions` config) is appended after
  * the base instruction rather than replacing it: the base carries the
  * functional contract (answer only from the excerpts, cite pages as Markdown
  * links) that the panel's citation rendering depends on.
  *
- * `options.retrieval` (the `ai.ask.retrieval` config) sizes how much
+ * `options.retrieval` (the `ai.assistant.retrieval` config) sizes how much
  * documentation each question carries; omitted fields keep today's defaults.
  */
 export const createAskContext = (

package/src/ai/ask-data.ts

@@ -3,8 +3,8 @@ import { buildSearchDocuments } from "../search/documents.ts";
 import type { AskData } from "./ask-context.ts";
 
 /**
- * Build the grounding snapshot the Ask AI endpoint serves. Like the MCP server,
- * Ask AI is independent of on-page search, so documents are indexed even when the
+ * Build the grounding snapshot the assistant endpoint serves. Like the MCP server,
+ * the assistant is independent of on-page search, so documents are indexed even when the
  * search provider is `none` (`includeWhenDisabled`). `locale` is kept (unlike the
  * MCP snapshot) so retrieval can be filtered to the current page's language, and
  * content is kept as Markdown so grounding sees fenced code examples — the model

package/src/ai/ask.ts

@@ -9,7 +9,7 @@ import { unrecognizedKeysMessage } from "../core/unrecognized-keys.ts";
  * `reasoning` values minus `provider-default`, which is what omitting the
  * option means.
  */
-export const askReasoningLevels = [
+export const assistantReasoningLevels = [
   "none",
   "minimal",
   "low",
@@ -19,14 +19,17 @@ export const askReasoningLevels = [
 ] as const;
 
 /** How much the model reasons before answering (an adapter's `reasoning`). */
-export type AskReasoning = (typeof askReasoningLevels)[number];
+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 AskProviderOptions = Record<string, Record<string, JsonValue>>;
+export type AssistantProviderOptions = Record<
+  string,
+  Record<string, JsonValue>
+>;
 
 /** The AI SDK provider package the OpenAI-compatible adapters install. */
 const OPENAI_COMPATIBLE_DEP = "@ai-sdk/openai-compatible";
@@ -35,8 +38,8 @@ const OPENAI_COMPATIBLE_DEP = "@ai-sdk/openai-compatible";
 // Shared options
 // ---------------------------------------------------------------------------
 
-/** The options every Ask AI adapter accepts. */
-export interface AskAdapterOptions {
+/** 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.
@@ -53,7 +56,7 @@ export interface AskAdapterOptions {
    * Options passed to `streamText` as its `providerOptions`, untouched, in the
    * AI SDK's own shape (`{ openai: { textVerbosity: "low" } }`, say).
    */
-  providerOptions?: AskProviderOptions;
+  providerOptions?: AssistantProviderOptions;
 }
 
 /**
@@ -72,7 +75,7 @@ const sharedOptions = (apiKeyEnv: string) => ({
   providerOptions: providerOptionsSchema.optional(),
 });
 
-const reasoningOption = z.enum(askReasoningLevels).optional();
+const reasoningOption = z.enum(assistantReasoningLevels).optional();
 
 // ---------------------------------------------------------------------------
 // gateway()
@@ -83,7 +86,7 @@ const GATEWAY_API_KEY_ENV = "AI_GATEWAY_API_KEY";
 const DEFAULT_GATEWAY_MODEL = "openai/gpt-5.5";
 
 /** Options for {@link gateway}. */
-export interface AskGatewayOptions extends AskAdapterOptions {
+export interface AssistantGatewayOptions extends AssistantAdapterOptions {
   /** A `provider/model` id routed by the gateway. Defaults to `openai/gpt-5.5`. */
   model?: string;
   /**
@@ -92,7 +95,7 @@ export interface AskGatewayOptions extends AskAdapterOptions {
    * control (OpenAI's `reasoning_effort`, for example); the model has to
    * offer the level you pick. Omitted keeps the model's default.
    */
-  reasoning?: AskReasoning;
+  reasoning?: AssistantReasoning;
 }
 
 const gatewayOptionsSchema = z.strictObject({
@@ -101,7 +104,10 @@ const gatewayOptionsSchema = z.strictObject({
   reasoning: reasoningOption,
 });
 
-export type AskGatewayAdapter = AdapterDescriptor<"gateway", AskGatewayOptions>;
+export type AssistantGatewayAdapter = AdapterDescriptor<
+  "gateway",
+  AssistantGatewayOptions
+>;
 
 export const gatewayAdapterSchema = adapterDescriptorSchema(
   "gateway",
@@ -109,14 +115,14 @@ export const gatewayAdapterSchema = adapterDescriptorSchema(
 );
 
 /**
- * Route Ask AI through the Vercel AI Gateway (the default). `model` is a
+ * 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 const gateway = (
-  options: AskGatewayOptions = {}
-): AskGatewayAdapter => ({
+  options: AssistantGatewayOptions = {}
+): AssistantGatewayAdapter => ({
   kind: "gateway",
   options,
   requiredSecrets: [options.apiKeyEnv ?? GATEWAY_API_KEY_ENV],
@@ -130,7 +136,7 @@ export const gateway = (
 const OPENROUTER_API_KEY_ENV = "OPENROUTER_API_KEY";
 
 /** Options for {@link openrouter}. */
-export interface AskOpenRouterOptions extends AskAdapterOptions {
+export interface AssistantOpenRouterOptions extends AssistantAdapterOptions {
   /** The OpenRouter model id (`anthropic/claude-sonnet-4-5`). */
   model: string;
   /**
@@ -138,7 +144,7 @@ export interface AskOpenRouterOptions extends AskAdapterOptions {
    * OpenRouter's `reasoning.effort`, because its provider ignores the AI
    * SDK's call-level option. Omitted keeps the model's default.
    */
-  reasoning?: AskReasoning;
+  reasoning?: AssistantReasoning;
 }
 
 const openrouterOptionsSchema = z.strictObject({
@@ -147,9 +153,9 @@ const openrouterOptionsSchema = z.strictObject({
   reasoning: reasoningOption,
 });
 
-export type AskOpenRouterAdapter = AdapterDescriptor<
+export type AssistantOpenRouterAdapter = AdapterDescriptor<
   "openrouter",
-  AskOpenRouterOptions
+  AssistantOpenRouterOptions
 >;
 
 export const openrouterAdapterSchema = adapterDescriptorSchema(
@@ -158,12 +164,12 @@ export const openrouterAdapterSchema = adapterDescriptorSchema(
 );
 
 /**
- * Route Ask AI through OpenRouter. Reads `OPENROUTER_API_KEY` and needs
+ * Route the assistant through OpenRouter. Reads `OPENROUTER_API_KEY` and needs
  * `@openrouter/ai-sdk-provider` installed in the project.
  */
 export const openrouter = (
-  options: AskOpenRouterOptions
-): AskOpenRouterAdapter => ({
+  options: AssistantOpenRouterOptions
+): AssistantOpenRouterAdapter => ({
   kind: "openrouter",
   options,
   requiredSecrets: [options.apiKeyEnv ?? OPENROUTER_API_KEY_ENV],
@@ -177,7 +183,7 @@ export const openrouter = (
 const LLMGATEWAY_API_KEY_ENV = "LLMGATEWAY_API_KEY";
 
 /** Options for {@link llmgateway}. */
-export interface AskLlmGatewayOptions extends AskAdapterOptions {
+export interface AssistantLlmGatewayOptions extends AssistantAdapterOptions {
   /** Overrides the preset endpoint (`https://api.llmgateway.io/v1`). */
   baseUrl?: string;
   /** The model id LLMGateway serves. */
@@ -186,7 +192,7 @@ export interface AskLlmGatewayOptions extends AskAdapterOptions {
    * How much the model reasons before answering, sent in the request as
    * `reasoning_effort`. Omitted keeps the model's default.
    */
-  reasoning?: AskReasoning;
+  reasoning?: AssistantReasoning;
 }
 
 const llmgatewayOptionsSchema = z.strictObject({
@@ -196,9 +202,9 @@ const llmgatewayOptionsSchema = z.strictObject({
   reasoning: reasoningOption,
 });
 
-export type AskLlmGatewayAdapter = AdapterDescriptor<
+export type AssistantLlmGatewayAdapter = AdapterDescriptor<
   "llmgateway",
-  AskLlmGatewayOptions
+  AssistantLlmGatewayOptions
 >;
 
 export const llmgatewayAdapterSchema = adapterDescriptorSchema(
@@ -207,12 +213,12 @@ export const llmgatewayAdapterSchema = adapterDescriptorSchema(
 );
 
 /**
- * Route Ask AI through LLMGateway's OpenAI-compatible endpoint. Reads
+ * Route the assistant through LLMGateway's OpenAI-compatible endpoint. Reads
  * `LLMGATEWAY_API_KEY` and needs `@ai-sdk/openai-compatible` installed.
  */
 export const llmgateway = (
-  options: AskLlmGatewayOptions
-): AskLlmGatewayAdapter => ({
+  options: AssistantLlmGatewayOptions
+): AssistantLlmGatewayAdapter => ({
   kind: "llmgateway",
   options,
   requiredSecrets: [options.apiKeyEnv ?? LLMGATEWAY_API_KEY_ENV],
@@ -229,7 +235,7 @@ const INKEEP_API_KEY_ENV = "INKEEP_API_KEY";
  * 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 {
+export interface AssistantInkeepOptions extends AssistantAdapterOptions {
   /** Overrides the preset endpoint (`https://api.inkeep.com/v1`). */
   baseUrl?: string;
   /** The Inkeep QA model id. */
@@ -242,7 +248,10 @@ const inkeepOptionsSchema = z.strictObject({
   model: z.string().min(1),
 });
 
-export type AskInkeepAdapter = AdapterDescriptor<"inkeep", AskInkeepOptions>;
+export type AssistantInkeepAdapter = AdapterDescriptor<
+  "inkeep",
+  AssistantInkeepOptions
+>;
 
 export const inkeepAdapterSchema = adapterDescriptorSchema(
   "inkeep",
@@ -254,7 +263,9 @@ export const inkeepAdapterSchema = adapterDescriptorSchema(
  * dashboard, so Blume leaves it ungrounded and it takes no `reasoning`.
  * Reads `INKEEP_API_KEY` and needs `@ai-sdk/openai-compatible` installed.
  */
-export const inkeep = (options: AskInkeepOptions): AskInkeepAdapter => ({
+export const inkeep = (
+  options: AssistantInkeepOptions
+): AssistantInkeepAdapter => ({
   kind: "inkeep",
   options,
   requiredSecrets: [options.apiKeyEnv ?? INKEEP_API_KEY_ENV],
@@ -266,7 +277,7 @@ export const inkeep = (options: AskInkeepOptions): AskInkeepAdapter => ({
 // ---------------------------------------------------------------------------
 
 /** Options for {@link openaiCompatible}. */
-export interface AskOpenAICompatibleOptions extends AskAdapterOptions {
+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`). */
@@ -280,7 +291,7 @@ export interface AskOpenAICompatibleOptions extends AskAdapterOptions {
    * `reasoning_effort`, so the endpoint has to accept that parameter.
    * Omitted keeps the model's default.
    */
-  reasoning?: AskReasoning;
+  reasoning?: AssistantReasoning;
 }
 
 const openaiCompatibleOptionsSchema = z.strictObject({
@@ -293,9 +304,9 @@ const openaiCompatibleOptionsSchema = z.strictObject({
   reasoning: reasoningOption,
 });
 
-export type AskOpenAICompatibleAdapter = AdapterDescriptor<
+export type AssistantOpenAICompatibleAdapter = AdapterDescriptor<
   "openai-compatible",
-  AskOpenAICompatibleOptions
+  AssistantOpenAICompatibleOptions
 >;
 
 export const openaiCompatibleAdapterSchema = adapterDescriptorSchema(
@@ -304,13 +315,13 @@ export const openaiCompatibleAdapterSchema = adapterDescriptorSchema(
 );
 
 /**
- * Route Ask AI through any OpenAI-compatible endpoint: supply its `baseUrl`,
+ * 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 const openaiCompatible = (
-  options: AskOpenAICompatibleOptions
-): AskOpenAICompatibleAdapter => ({
+  options: AssistantOpenAICompatibleOptions
+): AssistantOpenAICompatibleAdapter => ({
   kind: "openai-compatible",
   options,
   requiredSecrets: [options.apiKeyEnv],
@@ -318,16 +329,16 @@ export const openaiCompatible = (
 });
 
 // ---------------------------------------------------------------------------
-// The `ai.ask.provider` schema
+// The `ai.assistant.provider` schema
 // ---------------------------------------------------------------------------
 
-/** Which backend answers Ask AI: the value of `gateway()`, `openrouter()`, … */
-export type AskAdapter =
-  | AskGatewayAdapter
-  | AskOpenRouterAdapter
-  | AskLlmGatewayAdapter
-  | AskInkeepAdapter
-  | AskOpenAICompatibleAdapter;
+/** Which backend answers the assistant: the value of `gateway()`, `openrouter()`, … */
+export type AssistantAdapter =
+  | AssistantGatewayAdapter
+  | AssistantOpenRouterAdapter
+  | AssistantLlmGatewayAdapter
+  | AssistantInkeepAdapter
+  | AssistantOpenAICompatibleAdapter;
 
 // ---------------------------------------------------------------------------
 // Blume 1 hints
@@ -354,29 +365,29 @@ const MOVED_TO_PROVIDER: ReadonlySet<string> = new Set([
   "reasoning",
 ]);
 
-/** The provider an `ai.ask` object names: a 1.x string or a descriptor's `kind`. */
-const askProviderNameProbe = z.looseObject({
+/** The provider an `ai.assistant` object names: a 1.x string or a descriptor's `kind`. */
+const assistantProviderNameProbe = z.looseObject({
   provider: z.union([
     z.string(),
     z.looseObject({ kind: z.string() }).transform(({ kind }) => kind),
   ]),
 });
 
-/** The factory a failing `ai.ask` object's provider names, or the gateway. */
+/** The factory a failing `ai.assistant` object's provider names, or the gateway. */
 const providerFactory = (issue: z.core.$ZodRawIssue): string => {
-  const probe = askProviderNameProbe.safeParse(issue.input);
+  const probe = assistantProviderNameProbe.safeParse(issue.input);
   return (
     (probe.success && FACTORY_BY_PROVIDER.get(probe.data.provider)) || "gateway"
   );
 };
 
 /**
- * Error params for `ai.ask`: a 1.x flat provider field (`model`, `apiKeyEnv`,
+ * 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 const askMovedFieldsHint = {
+export const assistantMovedFieldsHint = {
   error: (issue: z.core.$ZodRawIssue): string | undefined => {
     if (issue.code !== "unrecognized_keys") {
       return;
@@ -385,7 +396,7 @@ export const askMovedFieldsHint = {
     if (moved.length === 0) {
       return;
     }
-    const fields = moved.map((key) => `ai.ask.${key}`).join(", ");
+    const fields = moved.map((key) => `ai.assistant.${key}`).join(", ");
     const hint = `${fields} moved into the provider adapter: \`provider: ${providerFactory(issue)}({ ${moved.join(", ")} })\`, imported from "blume/ai".`;
     const others = issue.keys.filter((key) => !MOVED_TO_PROVIDER.has(key));
     return others.length > 0
@@ -394,27 +405,27 @@ export const askMovedFieldsHint = {
   },
 };
 
-/** A value that is a 1.x provider name, for the `ai.ask.provider` hint. */
+/** A value that is a 1.x provider name, for the `ai.assistant.provider` hint. */
 const providerNameProbe = z.string();
 
 /**
- * The message for an `ai.ask.provider` that isn't a descriptor: a 1.x
+ * The message for an `ai.assistant.provider` that isn't a descriptor: a 1.x
  * provider name names the factory that replaced it; anything else lists them.
  */
 const providerNotAdapterMessage = (issue: z.core.$ZodRawIssue): string => {
   const name = providerNameProbe.safeParse(issue.input);
   const factory = name.success ? FACTORY_BY_PROVIDER.get(name.data) : undefined;
   return factory
-    ? `ai.ask.provider takes an adapter from "blume/ai", not a provider name: \`provider: ${factory}({ model })\`. The 1.x model, apiKeyEnv, baseUrl, headers, and reasoning fields move into the call.`
-    : 'ai.ask.provider takes an adapter from "blume/ai": gateway(), openrouter(), llmgateway(), inkeep(), or openaiCompatible().';
+    ? `ai.assistant.provider takes an adapter from "blume/ai", not a provider name: \`provider: ${factory}({ model })\`. The 1.x model, apiKeyEnv, baseUrl, headers, and reasoning fields move into the call.`
+    : 'ai.assistant.provider takes an adapter from "blume/ai": gateway(), openrouter(), llmgateway(), inkeep(), or openaiCompatible().';
 };
 
 /**
- * `ai.ask.provider`: the descriptor an adapter factory returned, validated
+ * `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 const askAdapterSchema = z.discriminatedUnion(
+export const assistantAdapterSchema = z.discriminatedUnion(
   "kind",
   [
     gatewayAdapterSchema,
@@ -434,12 +445,12 @@ export const askAdapterSchema = z.discriminatedUnion(
   }
 );
 
-/** A resolved (post-defaults) `ai.ask.provider` descriptor. */
-export type AskAdapterConfig = z.output<typeof askAdapterSchema>;
-export type AskAdapterKind = AskAdapterConfig["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.ask.provider` is unset: the gateway with its defaults. */
-export const DEFAULT_ASK_PROVIDER: AskAdapter = gateway();
+/** The provider when `ai.assistant.provider` is unset: the gateway with its defaults. */
+export const DEFAULT_ASSISTANT_PROVIDER: AssistantAdapter = gateway();
 
 // ---------------------------------------------------------------------------
 // Resolved backend
@@ -474,7 +485,7 @@ export interface AskBackendTemplate {
 export interface AskBackend {
   /** Whether Blume grounds answers in the docs (Inkeep retrieves itself). */
   grounded: boolean;
-  kind: AskAdapterKind;
+  kind: AssistantAdapterKind;
   /** Human-readable adapter name for diagnostics ("AI Gateway"). */
   label: string;
   /** Appended to the missing-secret warning (an alternative credential, say). */
@@ -499,7 +510,7 @@ const headersLine = (headers?: Record<string, string>): string =>
 /** Refuse a request up front when the adapter's key env var is unset. */
 const keyCheck = (env: string): string => `  if (!${secretExpr(env)}) {
     return new Response(
-      ${JSON.stringify(`Ask AI is not configured: set ${env}.`)},
+      ${JSON.stringify(`The assistant is not configured: set ${env}.`)},
       { status: 503 }
     );
   }`;
@@ -510,7 +521,7 @@ const keyCheck = (env: string): string => `  if (!${secretExpr(env)}) {
  */
 const callFields = (options: {
   providerOptions?: z.output<typeof providerOptionsSchema>;
-  reasoning?: AskReasoning;
+  reasoning?: AssistantReasoning;
 }): string[] => {
   const fields: string[] = [];
   if (options.reasoning) {
@@ -542,7 +553,7 @@ const gatewayBackend = (
     keyCheck: `  // The AI Gateway authenticates with an API key or Vercel's OIDC token.
   if (!(${secretExpr(options.apiKeyEnv)} || getSecret("VERCEL_OIDC_TOKEN"))) {
     return new Response(
-      ${JSON.stringify(`Ask AI is not configured: set ${options.apiKeyEnv} (or deploy on Vercel with OIDC).`)},
+      ${JSON.stringify(`The assistant is not configured: set ${options.apiKeyEnv} (or deploy on Vercel with OIDC).`)},
       { status: 503 }
     );
   }`,
@@ -587,7 +598,7 @@ const openrouterBackend = (
  * option as `reasoning_effort`.
  */
 const openaiCompatibleBackend = (
-  kind: AskAdapterKind,
+  kind: AssistantAdapterKind,
   label: string,
   grounded: boolean,
   options: {
@@ -597,7 +608,7 @@ const openaiCompatibleBackend = (
     model: string;
     name: string;
     providerOptions?: z.output<typeof providerOptionsSchema>;
-    reasoning?: AskReasoning;
+    reasoning?: AssistantReasoning;
   }
 ): AskBackend => ({
   grounded,
@@ -621,9 +632,11 @@ const openaiCompatibleBackend = (
   },
 });
 
-/** Resolve a parsed `ai.ask.provider` descriptor into its backend. */
+/** Resolve a parsed `ai.assistant.provider` descriptor into its backend. */
 export const resolveAskBackend = (
-  provider: AskAdapterConfig = askAdapterSchema.parse(DEFAULT_ASK_PROVIDER)
+  provider: AssistantAdapterConfig = assistantAdapterSchema.parse(
+    DEFAULT_ASSISTANT_PROVIDER
+  )
 ): AskBackend => {
   switch (provider.kind) {
     case "gateway": {