blume 2.0.0 → 2.0.1

package/docs/03-upgrading.mdx

@@ -1,12 +1,12 @@
 ---
 title: Upgrade to Blume 2
-description: Move a Blume 1 site to Blume 2 with one command, then use this guide for each config change — or hand the whole upgrade to Claude Code or Codex.
+description: Move a Blume 1 site to Blume 2 with one command, then use this guide for each config change — or hand the whole upgrade to Codex or Claude Code.
 sidebar:
   label: Upgrade to Blume 2
   order: 2.5
 ---
 
-Blume 2 changes configuration, not content: your Markdown and MDX pages need no edits, unless one sets the removed `search.boost` frontmatter field (see [Frontmatter](#frontmatter)). Settings that used to be a named string or a keyed block — the search provider, the deployment target, content sources, API references, analytics, and the Ask AI backend — are now **adapters** you import from a `blume/*` subpath and call. The machine-readable settings move from `ai` to a new `agents` key, and `components.ts` overrides are checked before the build. A zero-config site, or one that sets none of these, only needs the version bump.
+Blume 2 changes configuration, not content: your Markdown and MDX pages need no edits, unless one sets the removed `search.boost` frontmatter field (see [Frontmatter](#frontmatter)). Settings that used to be a named string or a keyed block — the search provider, the deployment target, content sources, API references, analytics, and the assistant's model backend — are now **adapters** you import from a `blume/*` subpath and call. Ask AI is renamed the assistant, so `ai.ask` becomes `ai.assistant`. The machine-readable settings move from `ai` to a new `agents` key, and `components.ts` overrides are checked before the build. A zero-config site, or one that sets none of these, only needs the version bump.
 
 ## Upgrade with one command
 
@@ -18,10 +18,10 @@ npx blume@latest upgrade
 
 It bumps `blume` in your `package.json` to 2, installs it with the package manager your project uses, then checks your config and `components.ts` against Blume 2. Every change that's still needed is listed with its file, line, and replacement — including `package.json` scripts that still pass the removed `blume build` flags — and the command exits non-zero until none are left. Run from a folder with neither a config nor a `blume` dependency, it stops with an error instead. Run it through `npx blume@latest` rather than `blume`: the command ships in Blume 2, so a project still on 1 doesn't have it yet. On pnpm 12, add `--allow-build=esbuild` after `pnpm dlx`, since pnpm 12 won't run esbuild's install script unapproved.
 
-To hand the changes to a coding agent instead, add `--claude` or `--codex`:
+To hand the changes to a coding agent instead, add `--codex` or `--claude`:
 
 ```package-install
-npx blume@latest upgrade --claude
+npx blume@latest upgrade --codex
 ```
 
 The agent opens interactively with the findings and this guide, applies each change, and runs `blume doctor` and `blume build` until both pass, so you review every edit through its own permission flow. Pass `--no-install` to bump `package.json` without installing.
@@ -201,9 +201,9 @@ export default defineConfig({
 
 `cloudflare: { token }` becomes `cloudflare({ token })`, and each `scripts[]` entry becomes `script({ … })`.
 
-## Ask AI
+## Assistant
 
-`ai.ask.provider` takes an adapter from `blume/ai`, which owns the model and the fields that went with it.
+Ask AI is now called the assistant, and its config moves with the name: `ai.ask` becomes `ai.assistant`. Its `provider` takes an adapter from `blume/ai`, which owns the model and the fields that went with it.
 
 <CodeGroup>
 
@@ -226,7 +226,7 @@ import { openrouter } from "blume/ai";
 
 export default defineConfig({
   ai: {
-    ask: {
+    assistant: {
       enabled: true,
       provider: openrouter({
         model: "anthropic/claude-sonnet-4-5",
@@ -239,7 +239,20 @@ export default defineConfig({
 
 </CodeGroup>
 
-The adapters are `gateway()`, `openrouter()`, `llmgateway()`, `inkeep()`, and `openaiCompatible({ baseUrl, name, model, apiKeyEnv })`. `model`, `apiKeyEnv`, `baseUrl`, `headers`, and `reasoning` move into the adapter; `enabled`, `instructions`, `retrieval`, `suggestions`, `cors`, and `endpoint` stay on `ai.ask`. Leaving `provider` unset still uses the AI Gateway.
+The adapters are `gateway()`, `openrouter()`, `llmgateway()`, `inkeep()`, and `openaiCompatible({ baseUrl, name, model, apiKeyEnv })`. `model`, `apiKeyEnv`, `baseUrl`, `headers`, and `reasoning` move into the adapter; `enabled`, `instructions`, `retrieval`, `suggestions`, `cors`, and `endpoint` move to `ai.assistant` unchanged. Leaving `provider` unset still uses the AI Gateway.
+
+The rename reaches every name that said Ask AI:
+
+- `i18n.ui` overrides: the `ask` group becomes `assistant`, and `search.askAi` and `search.askAiHint` become `search.assistant` and `search.assistantHint`.
+- `useAskAI` from `blume/hooks` becomes `useAssistant`, with its `UseAssistant` and `UseAssistantOptions` types.
+- The `askEnabled` prop on `PageLayout`, `RootLayout`, `Header`, and a `Search` override becomes `assistantEnabled`.
+- In the [`blume:data`](/docs/advanced/custom-pages) module, `config.ask` becomes `config.assistant` and `ui.ask` becomes `ui.assistant`, and the `UIStrings` type from `blume` follows.
+- The adapter types from `blume/ai` swap their `Ask` prefix for `Assistant` (`AskAdapter` becomes `AssistantAdapter`, `AskGatewayOptions` becomes `AssistantGatewayOptions`), and `askReasoningLevels` and `AskReasoning` from `blume/schema` become `assistantReasoningLevels` and `AssistantReasoning`.
+- The `blume:open-ask-ai` window event becomes `blume:open-assistant`, and the `data-blume-ask` attribute on `<body>` becomes `data-blume-assistant`.
+
+The generated `/api/ask` route and the `ask`, `ask_answer`, and `ask_error` [analytics events](/docs/configuration/assistant#analytics) keep their names, so callers and dashboards need no change. `blume upgrade` and `blume doctor` name each old config key they find, `ai.ask` and the `i18n.ui` keys alike, with its replacement.
+
+Upgraded to Blume 2.0.0 already? It still read `ai.ask`, so update `blume` as usual and make the same rename.
 
 ## Agents and other config moves
 
@@ -270,7 +283,7 @@ export default defineConfig({
 
 </CodeGroup>
 
-- `ai.api`, `ai.catalog`, `ai.llmsTxt`, `ai.markdownComponents`, `ai.mcp`, `ai.skills`, `ai.webBotAuth`, and `ai.webmcp` become `agents.*`, and so do `seo.agentReadability` and `seo.contentSignals`. `ai` keeps only `ask` and `openInChat`.
+- `ai.api`, `ai.catalog`, `ai.llmsTxt`, `ai.markdownComponents`, `ai.mcp`, `ai.skills`, `ai.webBotAuth`, and `ai.webmcp` become `agents.*`, and so do `seo.agentReadability` and `seo.contentSignals`. `ai` keeps only `assistant` (formerly `ask`) and `openInChat`.
 - `lastModified` is a flat value: `true` becomes `"git"`, and `{ type: "git" }` or `{ type: "frontmatter" }` becomes the bare string.
 - `markdown.codeBlocks` merges into `markdown.code`.
 - `theme.layout` is gone. Nothing read it, so delete it.

package/docs/04-migrating.mdx

@@ -1,6 +1,6 @@
 ---
 title: Migrate to Blume
-description: Move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume with one command that hands the migration to Claude Code or Codex.
+description: Move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume with one command that hands the migration to Codex or Claude Code.
 sidebar:
   label: Migrate to Blume
   order: 2.4
@@ -13,10 +13,10 @@ Moving a docs site to idiomatic Blume takes judgment a codemod can't make: which
 Run it from the root of the docs project you're migrating:
 
 ```package-install
-npx blume migrate fumadocs --claude
+npx blume migrate fumadocs --codex
 ```
 
-Swap `fumadocs` for your framework, and `--claude` for `--codex` to use Codex. With pnpm 12, add `--allow-build=esbuild` after `pnpm dlx`, since pnpm 12 won't run esbuild's install script unapproved. The agent opens interactively in your terminal, so every edit goes through its own permission flow. It works in place, so start from a clean working tree and review the whole migration as one diff.
+Swap `fumadocs` for your framework, and `--codex` for `--claude` to use Claude Code. With pnpm 12, add `--allow-build=esbuild` after `pnpm dlx`, since pnpm 12 won't run esbuild's install script unapproved. The agent opens interactively in your terminal, so every edit goes through its own permission flow. It works in place, so start from a clean working tree and review the whole migration as one diff.
 
 ## Sources
 
@@ -47,7 +47,7 @@ It finishes with a summary of what it migrated, dropped, or approximated, such a
 
 ## Other agents
 
-Without `--claude` or `--codex`, the command reports the source it detected, prints the path to the playbook — the `blume-migrate` [skill](/docs/advanced/skills) bundled in the package — and exits without changing anything. Point any other agent at that `SKILL.md`, or install the skill where your agent looks for skills, with the command it prints:
+Without `--codex` or `--claude`, the command reports the source it detected, prints the path to the playbook — the `blume-migrate` [skill](/docs/advanced/skills) bundled in the package — and exits without changing anything. Point any other agent at that `SKILL.md`, or install the skill where your agent looks for skills, with the command it prints:
 
 ```bash
 npx skills add haydenbleasel/blume --skill blume-migrate

package/docs/08-faq.mdx

@@ -20,13 +20,13 @@ Blume takes a third path: **the framework is the template.** You point it at a f
 | **Hosting** | Anywhere — static or a server function | Their managed infrastructure | Anywhere; you build and deploy |
 | **You maintain** | Your Markdown | Your Markdown + platform config | Your Markdown + the app around it |
 | **Rendering** | Astro; core theme ships zero client JS | Their runtime | React/Next.js runtime |
-| **AI features** | `llms.txt`, raw Markdown, Ask AI, MCP — built in, no hosted service | Built in (hosted) | Bring your own |
+| **AI features** | `llms.txt`, raw Markdown, an in-page assistant, MCP — built in, no hosted service | Built in (hosted) | Bring your own |
 
 A few consequences worth calling out:
 
 - **You own the output.** `blume build` produces a plain site you host on Vercel, Netlify, Cloudflare, S3, or your own box. Nothing phones home.
 - **No lock-in, two ways out.** Your content is portable Markdown, and `blume eject` turns the project into a standalone Astro app that still uses the `blume` package when you want full control.
-- **Fast by default.** The core theme is React-free and renders static HTML, so pages score well on Core Web Vitals without tuning. You opt into server features (Ask AI, MCP) only when you need them.
+- **Fast by default.** The core theme is React-free and renders static HTML, so pages score well on Core Web Vitals without tuning. You opt into server features (the assistant, MCP) only when you need them.
 - **Type-safe configuration.** `blume.config.ts` and every `meta.ts` are real TypeScript validated by a schema — not loosely-typed YAML.
 
 :::note
@@ -49,7 +49,7 @@ Yes. Any page can be `.md` or `.mdx`, and MDX lets you drop in the [built-in com
 
 ## Where can I deploy it?
 
-Anywhere. `blume build` outputs static HTML by default, which you can serve from any static host or CDN — Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3, or your own server. Server-only features (Ask AI, the MCP server, on-demand rendering) need server output: name a host adapter from `blume/deploy` — `vercel()`, `netlify()`, `cloudflare()`, or `node()` — as `deployment`. See [Deployment](/docs/deployment).
+Anywhere. `blume build` outputs static HTML by default, which you can serve from any static host or CDN — Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3, or your own server. Server-only features (the assistant, the MCP server, on-demand rendering) need server output: name a host adapter from `blume/deploy` — `vercel()`, `netlify()`, `cloudflare()`, or `node()` — as `deployment`. See [Deployment](/docs/deployment).
 
 ## Does search need a hosted service?
 

package/docs/advanced/custom-pages.mdx

@@ -76,7 +76,7 @@ The module exposes:
       type: "BlumeDataConfig",
       required: true,
       description:
-        "Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, github (owner, repo, host, and the REST api base — null when unset), search, i18n, mcp, ask, og, analytics, feedback, structuredData, toc, codeThemes, codeWrap, and imageZoom.",
+        "Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, github (owner, repo, host, and the REST api base — null when unset), search, i18n, mcp, assistant, og, analytics, feedback, structuredData, toc, codeThemes, codeWrap, and imageZoom.",
     },
     navigation: {
       type: "Navigation",
@@ -230,7 +230,7 @@ const { config } = data;
 </PageLayout>
 ```
 
-The header a custom page gets is the same one the docs pages get, so the chrome that lives in it comes along: search, the theme toggle, the language switcher, and — when [Ask AI](/docs/configuration/ask-ai) is configured — the Ask AI trigger. None of it needs wiring up per page. Pass `askEnabled={false}` to leave the Ask trigger off one page while keeping it everywhere else.
+The header a custom page gets is the same one the docs pages get, so the chrome that lives in it comes along: search, the theme toggle, the language switcher, and — when the [assistant](/docs/configuration/assistant) is configured — its trigger. None of it needs wiring up per page. Pass `assistantEnabled={false}` to leave the assistant trigger off one page while keeping it everywhere else.
 
 The [agent-discovery head links](/docs/discoverability/agent-discovery#discovery-link-header) come along too: the layout reads the resolved config, so a custom page carries the same `describedby`, `ai-catalog`, and `ard` links the docs pages do without passing a prop. The homepage also advertises its `/index.md` Markdown mirror as a `text/markdown` alternate, since that mirror always exists; other custom pages have none, so none is advertised. Pass `discovery={null}` to drop the links from one page.
 

package/docs/advanced/skills.mdx

@@ -15,7 +15,7 @@ npx skills add haydenbleasel/blume
 
 ## Migration
 
-`blume-migrate` moves an existing docs site to Blume: Mintlify, Fumadocs, Docusaurus, Starlight, Nextra, or any other framework. It targets idiomatic Blume rather than a line-by-line port, with a mapping reference for each named framework, a redirect for every URL that moves, and a report of anything it drops. The quickest way to run it is [`blume migrate`](/docs/migrating), which detects your framework and opens Claude Code or Codex on the copy bundled in the package. To use it from another agent, install it:
+`blume-migrate` moves an existing docs site to Blume: Mintlify, Fumadocs, Docusaurus, Starlight, Nextra, or any other framework. It targets idiomatic Blume rather than a line-by-line port, with a mapping reference for each named framework, a redirect for every URL that moves, and a report of anything it drops. The quickest way to run it is [`blume migrate`](/docs/migrating), which detects your framework and opens Codex or Claude Code on the copy bundled in the package. To use it from another agent, install it:
 
 ```bash
 npx skills add haydenbleasel/blume --skill blume-migrate

package/docs/cli/audit.mdx

@@ -31,7 +31,7 @@ Findings are grouped by check rather than listed per page, so the report reads a
 - `--list-checks` — print every check the audit can report, then exit.
 - `--verbose` — list every affected page with each finding's full detail, instead of the first few.
 - `--json` — emit the report as JSON on stdout.
-- `--claude` / `--codex` — hand the findings to Claude Code or Codex to fix interactively.
+- `--codex` / `--claude` — hand the findings to Codex or Claude Code to fix interactively.
 
 ## Failing CI
 
@@ -55,10 +55,10 @@ Outbound links are graded rather than flatly failed: a 404 is a broken link you
 
 ## Fixing the findings with an agent
 
-If you use [Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli), the audit can hand its findings straight to it:
+If you use [Codex](https://developers.openai.com/codex/cli) or [Claude Code](https://claude.com/claude-code), the audit can hand its findings straight to it:
 
 ```bash
-blume audit --claude   # or --codex
+blume audit --codex   # or --claude
 ```
 
 This writes the complete JSON report — every affected page, not the terminal's three-page preview — to a file and opens the agent interactively with a prompt that walks it through the findings: edit the source file each finding names, apply its suggested fix, then run `blume build` and `blume audit` again until the report is clean. The session is interactive by design: you review the edits through the agent's own permission flow, and the agent is told never to fix a finding by deleting content.

package/docs/cli/doctor.mdx

@@ -14,15 +14,15 @@ blume doctor
 - **The Node version** against the range the installed `blume` package supports, read from its own `engines` field. A version outside it is a warning: things may work, but it isn't a combination Blume tests.
 - **`blume.config.ts`**, with the same validation a build runs. A removed or renamed key fails with a hint naming its replacement rather than a bare "unrecognized key".
 - **Every content page and folder meta**: the diagnostics `blume dev` and `blume build` print as they load the project — invalid frontmatter, navigation problems, missing include targets, and the rest — collected in one report.
-- **Features that need a server** on a site configured for static output — Ask AI, the MCP server, or the Try it playground's built-in proxy: an error naming the feature, with the deployment adapter to switch to (or, when a host adapter is set to `output: "static"`, telling you to drop that option).
-- **Packages your config needs** that aren't installed — the SDK a search, content source, or Ask AI adapter imports, a deployment adapter's `@astrojs/*` package, or the renderer for Vue or Svelte islands: an error naming each package, with the install command for your package manager. `blume build` stops on the same check.
+- **Features that need a server** on a site configured for static output — the assistant, the MCP server, or the Try it playground's built-in proxy: an error naming the feature, with the deployment adapter to switch to (or, when a host adapter is set to `output: "static"`, telling you to drop that option).
+- **Packages your config needs** that aren't installed — the SDK a search, content source, or assistant adapter imports, a deployment adapter's `@astrojs/*` package, or the renderer for Vue or Svelte islands: an error naming each package, with the install command for your package manager. `blume build` stops on the same check.
 - **`components.ts` overrides** Blume can't plan — an inline or computed entry, or an import whose file doesn't exist: an error for each, at its line.
 - **A version-shaped folder** (`v1.0/`) on a site with no `versions` configured, which would otherwise build as ordinary content: a warning pointing at [`blume version`](/docs/cli/version).
 - **Secrets an enabled feature reads** that aren't set, such as `ALGOLIA_ADMIN_API_KEY` or `OPENROUTER_API_KEY`: a warning naming the variable. Doctor loads `.env` and `.env.local` first, like `blume dev` and `blume build`.
 
 ## The summary
 
-After the diagnostics, doctor prints what the project resolved to, so a mismatch between what you think is configured and what Blume sees is visible at a glance: the page count, the output mode and deployment adapter, the search provider, the configured reference, analytics, and content source adapters, and whether Ask AI is on and which backend it uses.
+After the diagnostics, doctor prints what the project resolved to, so a mismatch between what you think is configured and what Blume sees is visible at a glance: the page count, the output mode and deployment adapter, the search provider, the configured reference, analytics, and content source adapters, and whether the assistant is on and which backend it uses.
 
 ## Exit code and JSON
 

package/docs/cli/evals.mdx

@@ -10,22 +10,22 @@ blume eval
 ```
 
 ```
-blume eval  4 question(s) · Claude Code
+blume eval  4 question(s) · Codex
 
-  ✔ install-node-version         pass  1.00  14.2s  $0.14
-  ✔ custom-domain                pass  0.92  21.3s  $0.19
-  ✖ deploy-vercel                fail  0.40  38.9s  $0.31
+  ✔ install-node-version         pass  1.00  14.2s
+  ✔ custom-domain                pass  0.92  21.3s
+  ✖ deploy-vercel                fail  0.40  38.9s
       missing: deployment: vercel() from blume/deploy
   ⊘ search-providers             skipped
 
   fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: deployment: vercel() from blume/deploy
 
-  2 passed · 1 failed · 1 skipped · 1m 42s · $0.64
+  2 passed · 1 failed · 1 skipped · 1m 42s
 ```
 
 ## How it works
 
-Each question runs through two agent sessions, using an agent CLI you already have installed — [Claude Code](https://claude.com/claude-code) by default, or [Codex](https://developers.openai.com/codex/cli) with `--agent codex`. Blume holds no API keys and calls no model itself. With `--agent codex`, both sessions also run without Codex's shell, command, and image tools, and inherit none of your environment variables.
+Each question runs through two agent sessions, using an agent CLI you already have installed — [Codex](https://developers.openai.com/codex/cli) by default, or [Claude Code](https://claude.com/claude-code) with `--agent claude`. Blume holds no API keys and calls no model itself. With Codex, both sessions also run without Codex's shell, command, and image tools, and inherit none of your environment variables.
 
 1. **The reader** answers the question using _only_ your documentation. It runs in an empty directory with its file, shell, and web tools disabled, connected to a private [MCP server](/docs/discoverability/mcp) that serves your docs — the same `search_docs`/`get_page` tools a real agent uses against your deployed site. It cannot read your repo, so it experiences the docs exactly like a fresh user: what isn't written doesn't exist.
 2. **The judge** grades the answer against the facts you listed, with no tools at all. Paraphrase passes; a missing or contradicted fact fails — and so does "the documentation doesn't say."
@@ -98,7 +98,7 @@ This writes the full JSON report to a file and opens the agent interactively wit
 
 ## Flags
 
-- `--agent claude|codex` — which agent CLI runs the reader and judge. Defaults to `claude`.
+- `--agent codex|claude` — which agent CLI runs the reader and judge. Defaults to `codex`.
 - `--file <path>` — the evals file. Defaults to `evals.yaml`.
 - `--threshold <0..1>` — minimum passing fraction before the run exits non-zero. Defaults to `1`.
 - `--timeout <seconds>` — reader time limit per question. Defaults to `180`.

package/docs/cli/index.mdx

@@ -25,8 +25,8 @@ blume <command> [options]
 | [`blume eval`](/docs/cli/evals) | Test the docs: an agent answers your questions using only the documentation. |
 | [`blume translate`](/docs/cli/translate) | Translate docs into the configured locales with a local agent CLI. |
 | [`blume version [id]`](/docs/cli/version) | Freeze the current docs as an archived version (no id lists configured versions). |
-| [`blume migrate [source]`](/docs/migrating) | Move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume with Claude Code or Codex. |
-| [`blume upgrade`](/docs/upgrading) | Move to a new major: bump `blume`, then list the config changes left or hand them to Claude Code or Codex. |
+| [`blume migrate [source]`](/docs/migrating) | Move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume with Codex or Claude Code. |
+| [`blume upgrade`](/docs/upgrading) | Move to a new major: bump `blume`, then list the config changes left or hand them to Codex or Claude Code. |
 
 ## Common flags
 

package/docs/cli/translate.mdx

@@ -6,22 +6,22 @@ description: blume translate fills in your locales with an AI agent — it finds
 Once [i18n](/docs/content/i18n) is on, every edit to a source page quietly outdates its translations. `blume translate` closes that loop: it computes exactly which pages are missing or stale in each locale, translates them headlessly with a local agent CLI, and records what it did in a committed ledger so the next run — and CI — knows what's current.
 
 ```bash
-blume translate --claude
+blume translate --codex
 ```
 
 ```
-blume translate  3 item(s) · 2 locale(s) · Claude Code
+blume translate  3 item(s) · 2 locale(s) · Codex
 
-  ✔ docs/guides/install.mdx → fr 24.2s $0.11
-  ✔ docs/guides/install.mdx → de 22.8s $0.10
-  ✔ meta titles (2) → de 4.1s $0.01
+  ✔ docs/guides/install.mdx → fr 24.2s
+  ✔ docs/guides/install.mdx → de 22.8s
+  ✔ meta titles (2) → de 4.1s
 
-  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s · $0.22
+  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s
 ```
 
 ## How it works
 
-Blume owns the pipeline; the agent only translates text. For each file that needs work, Blume builds a translation prompt, runs the agent CLI headlessly with its file, shell, and web tools disabled, validates the reply's structure, and writes the target file itself — [Claude Code](https://claude.com/claude-code) with `--claude`, or [Codex](https://developers.openai.com/codex/cli) with `--codex`. Blume holds no API keys and calls no model itself.
+Blume owns the pipeline; the agent only translates text. For each file that needs work, Blume builds a translation prompt, runs the agent CLI headlessly with its file, shell, and web tools disabled, validates the reply's structure, and writes the target file itself — [Codex](https://developers.openai.com/codex/cli) with `--codex`, or [Claude Code](https://claude.com/claude-code) with `--claude`. Blume holds no API keys and calls no model itself.
 
 Every validated write is recorded in `blume.translations.json` at the project root: for each source file and locale, a hash of the source at the moment it was translated. **Commit this file.** It's how a rerun knows the difference between "already translated" and "translated, but the source changed since" — and it's what makes the CI gate possible.
 
@@ -72,7 +72,7 @@ The JSON report carries the same `diagnostics` + `summary` shape as `blume valid
 
 ## Flags
 
-- `--claude` / `--codex` — which agent CLI translates. Exactly one is required (except with `--check`).
+- `--codex` / `--claude` — which agent CLI translates. Exactly one is required (except with `--check`).
 - `--check` — report drift and exit non-zero, without writing anything.
 - `--concurrency <n>` — parallel agent sessions. Defaults to `4`, max `16`.
 - `--locale <codes>` — comma-separated target locales (defaults to every non-default locale).

package/docs/configuration/{ask-ai.mdx → assistant.mdx}

@@ -1,5 +1,5 @@
 ---
-title: Ask AI
+title: Assistant
 description: An in-page assistant grounded in your docs — suggested questions, custom instructions, retrieval sizing, provider adapters from the Vercel AI Gateway to any OpenAI-compatible endpoint, and the server output it needs.
 ---
 
@@ -7,7 +7,7 @@ Add an assistant that answers reader questions in an in-page chat panel, backed
 
 ```ts blume.config.ts lineNumbers
 ai: {
-  ask: {
+  assistant: {
     enabled: true,
   },
 }
@@ -21,7 +21,7 @@ Seed the empty state with a few starter prompts. Each renders as a clickable sug
 
 ```ts blume.config.ts lineNumbers
 ai: {
-  ask: {
+  assistant: {
     enabled: true,
     suggestions: [
       { label: "What is Blume?", icon: "rocket" },
@@ -40,7 +40,7 @@ Add your own system-prompt text with `instructions` — identity, language, tone
 
 ```ts blume.config.ts lineNumbers
 ai: {
-  ask: {
+  assistant: {
     enabled: true,
     instructions:
       "You are Bloomy, the Acme docs assistant. Answer in the language the question was asked in, and keep answers under three paragraphs.",
@@ -52,7 +52,7 @@ Your text is **appended to** the built-in instructions rather than replacing the
 
 ## Grounding
 
-Ask AI is **grounded in your docs**. For each question it retrieves the most relevant pages — using the same lexical [Orama](/docs/configuration/search) index that powers on-page search — and injects them into the model's system prompt, so answers come from your content instead of the model's own knowledge. The assistant is told to answer only from the retrieved pages, to say when something isn't covered, and to cite the pages it drew from.
+The assistant is **grounded in your docs**. For each question it retrieves the most relevant pages — using the same lexical [Orama](/docs/configuration/search) index that powers on-page search — and injects them into the model's system prompt, so answers come from your content instead of the model's own knowledge. The assistant is told to answer only from the retrieved pages, to say when something isn't covered, and to cite the pages it drew from.
 
 The page the reader is currently on is added to the context first and used to scope retrieval to that page's language, so answers stay relevant to where they are in the docs. Retrieval runs at request time from a snapshot baked into the build, so it works regardless of your [search](/docs/configuration/search) provider — even with `search: false` — and needs no configuration.
 
@@ -64,7 +64,7 @@ How much documentation a question carries is the biggest lever on how long the r
 
 ```ts blume.config.ts lineNumbers
 ai: {
-  ask: {
+  assistant: {
     enabled: true,
     retrieval: {
       maxResults: 3, // fewer pages retrieved per question
@@ -91,7 +91,7 @@ Already have an API backend for AI? Point the panel at it and keep the docs buil
 
 ```ts blume.config.ts lineNumbers
 ai: {
-  ask: {
+  assistant: {
     enabled: true,
     endpoint: "https://api.example.com/v1/docs/ask",
   },
@@ -115,7 +115,7 @@ The generated endpoint answers the in-page assistant on its own origin. To call
 
 ```ts blume.config.ts lineNumbers
 ai: {
-  ask: {
+  assistant: {
     enabled: true,
     cors: ["https://www.example.com"],
   },
@@ -142,7 +142,7 @@ The content type matters: Astro's cross-site request check rejects a cross-origi
 
 ## Server output required
 
-Blume's built-in Ask AI backend is a server route (`POST /api/ask`), so it can't run on a static build. Name a host adapter from `blume/deploy` to switch to server output:
+Blume's built-in assistant backend is a server route (`POST /api/ask`), so it can't run on a static build. Name a host adapter from `blume/deploy` to switch to server output:
 
 ```ts blume.config.ts lineNumbers
 import { vercel } from "blume/deploy";
@@ -152,7 +152,7 @@ export default defineConfig({
 });
 ```
 
-A static build with Ask AI enabled and no external `endpoint` fails fast with a message telling you to set a host adapter. See [Deployment](/docs/deployment) for the adapters.
+A static build with the assistant enabled and no external `endpoint` fails fast with a message telling you to set a host adapter. See [Deployment](/docs/deployment) for the adapters.
 
 ## Adapters
 
@@ -164,7 +164,7 @@ import { openrouter } from "blume/ai";
 
 export default defineConfig({
   ai: {
-    ask: {
+    assistant: {
       enabled: true,
       provider: openrouter({ model: "anthropic/claude-sonnet-4-5" }),
     },
@@ -194,7 +194,7 @@ import { gateway } from "blume/ai";
 
 export default defineConfig({
   ai: {
-    ask: {
+    assistant: {
       enabled: true,
       provider: gateway({ model: "anthropic/claude-sonnet-4-5" }),
     },
@@ -214,7 +214,7 @@ import { openrouter } from "blume/ai";
 
 export default defineConfig({
   ai: {
-    ask: {
+    assistant: {
       enabled: true,
       provider: openrouter({
         model: "anthropic/claude-sonnet-4-5",
@@ -235,7 +235,7 @@ import { llmgateway } from "blume/ai";
 
 export default defineConfig({
   ai: {
-    ask: {
+    assistant: {
       enabled: true,
       provider: llmgateway({ model: "openai/gpt-5.5" }),
     },
@@ -255,7 +255,7 @@ import { inkeep } from "blume/ai";
 
 export default defineConfig({
   ai: {
-    ask: {
+    assistant: {
       enabled: true,
       provider: inkeep({ model: "inkeep-qa-expert" }),
     },
@@ -275,7 +275,7 @@ import { openaiCompatible } from "blume/ai";
 
 export default defineConfig({
   ai: {
-    ask: {
+    assistant: {
       enabled: true,
       provider: openaiCompatible({
         baseUrl: "https://my-gateway.example.com/v1",
@@ -314,7 +314,7 @@ provider: gateway({
 }),
 ```
 
-Blume maps only the options it names (`model`, `reasoning`, `apiKeyEnv`, `headers`) and forwards `providerOptions` verbatim, so it has to be JSON — it's inlined into the route — and it has to use the key the underlying provider expects (`openai` for an OpenAI model behind the gateway, `openrouter` on OpenRouter). Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
+Blume maps only the options it names (`model`, `reasoning`, `apiKeyEnv`, `headers`) and forwards `providerOptions` verbatim, so it has to be JSON — it's inlined into the route — and it has to use the key the underlying provider expects (`openai` for an OpenAI model behind the gateway, `openrouter` on OpenRouter). Enabling the assistant also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
 
 ## Reasoning
 
@@ -324,7 +324,7 @@ Reasoning models think before they answer, and how much they do so by default va
 provider: gateway({ model: "openai/gpt-5.5", reasoning: "none" }),
 ```
 
-Each adapter sends the level as its backend's own reasoning control, which is why it lives on the adapter rather than on `ask`:
+Each adapter sends the level as its backend's own reasoning control, which is why it lives on the adapter rather than on `assistant`:
 
 | Adapter | What the level becomes |
 | --- | --- |
@@ -348,7 +348,7 @@ With an [analytics provider](/docs/configuration/analytics) configured, the assi
 
 `path` is the page the reader asked from (the served pathname, so it matches the feedback widget and your pageviews under a `base`), `questionChars` the question's length, `ms` the time from sending the question to the last chunk, and `chars` the answer's length. `status` is the HTTP status: `0` when no response arrived at all (offline, DNS, CORS), and `200` when the response was fine but its stream broke mid-answer — how a provider or credential error surfaces, since the backend has already sent its headers — or delivered nothing. Clearing the conversation mid-answer reports neither outcome.
 
-The question's text never reaches a provider: it is free-form reader input (pasted keys, error logs, names) that would breach most providers' terms and per-value size limits. It travels only on the `blume:track` DOM event, as `question` in `detail.props`, so a listener you write can forward it wherever you decide it belongs. A custom chat UI built on `useAskAI` from `blume/hooks` reports the same events. With no provider configured the built-in provider calls are no-ops, but the `blume:track` event still fires, so a custom integration listening for it receives them.
+The question's text never reaches a provider: it is free-form reader input (pasted keys, error logs, names) that would breach most providers' terms and per-value size limits. It travels only on the `blume:track` DOM event, as `question` in `detail.props`, so a listener you write can forward it wherever you decide it belongs. A custom chat UI built on `useAssistant` from `blume/hooks` reports the same events. With no provider configured the built-in provider calls are no-ops, but the `blume:track` event still fires, so a custom integration listening for it receives them.
 
 ## Rate limiting
 

package/docs/configuration/customization.mdx

@@ -91,7 +91,7 @@ Wired slots:
 | `Layout` | The entire page shell (`RootLayout`) | Everything the built-in layout receives, plus the `layout` map |
 | `Header` | The top navigation bar | `site`, `logo`, `navigation`, `route`, `searchEnabled`, … |
 | `Logo` | The brand link (mark + title) in the header | `site`, `logo`, `locale` |
-| `Search` | The header search trigger + modal | `navigation`, `strings`, `locale`, `askEnabled` |
+| `Search` | The header search trigger + modal | `navigation`, `strings`, `locale`, `assistantEnabled` |
 | `Sidebar` | The primary navigation tree | `items`, `currentRoute` |
 | `MobileNav` | The nav inside the mobile drawer (defaults to `Sidebar`) | `items`, `currentRoute` |
 | `Breadcrumbs` | The breadcrumb trail | `crumbs` |
@@ -184,7 +184,7 @@ npx blume eject --yes
 
 Eject is a one-way step: the hidden `.blume/` runtime becomes a normal Astro app you own and can modify directly. The `blume` package stays importable, so you keep its components, theme, and Markdown processors.
 
-Eject points your `package.json` scripts at `astro dev` and `astro build`, and adds the packages the Astro app imports by name — `astro`, `@tailwindcss/vite`, the search client, integrations, and adapter the config wires in, React when an island, example, or Ask AI uses it, `ai` for the Ask AI route, and `epub-gen-memory` for EPUB export — at the ranges Blume itself uses. Run an install before `dev` or `build`; eject lists what it added. Every path in the ejected app is relative, so it builds from any checkout, CI included.
+Eject points your `package.json` scripts at `astro dev` and `astro build`, and adds the packages the Astro app imports by name — `astro`, `@tailwindcss/vite`, the search client, integrations, and adapter the config wires in, React when an island, example, or the assistant uses it, `ai` for the assistant route, and `epub-gen-memory` for EPUB export — at the ranges Blume itself uses. Run an install before `dev` or `build`; eject lists what it added. Every path in the ejected app is relative, so it builds from any checkout, CI included.
 
 From then on, run the app through its own scripts (`npm run dev`, `npm run build`): `blume dev` and `blume build` stop in an ejected project and point you there. Running `blume eject` again refuses too, since it would overwrite your edits; pass `--force` to regenerate the app anyway.
 

package/docs/configuration/index.mdx

@@ -366,7 +366,7 @@ dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },
 
 ## SEO and agents
 
-Metadata, Open Graph images, RSS feeds, JSON-LD, the sitemap, and `robots.txt` live under `seo`; `llms.txt`, raw Markdown, the JSON API, the MCP server, and the discovery manifests live under `agents`. Both are covered page by page in the [Discoverability](/docs/discoverability) section, which treats search engines and AI agents as two audiences for the same machine-readable layer. The reader-facing model features — the Ask AI assistant and the Open in chat action — live under `ai`.
+Metadata, Open Graph images, RSS feeds, JSON-LD, the sitemap, and `robots.txt` live under `seo`; `llms.txt`, raw Markdown, the JSON API, the MCP server, and the discovery manifests live under `agents`. Both are covered page by page in the [Discoverability](/docs/discoverability) section, which treats search engines and AI agents as two audiences for the same machine-readable layer. The reader-facing model features — the assistant and the Open in chat action — live under `ai`.
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -431,7 +431,7 @@ Each of these has its own guide. The config field is the entry point:
 | `search` | Provider (Orama, Pagefind, Algolia, and more) and indexing | [Search](/docs/configuration/search) |
 | `markdown` | Markdown rendering options — code blocks, heading anchors, image zoom | [Syntax](/docs/content/syntax) |
 | `agents` | `llms.txt`, Markdown mirrors, the JSON API, the hosted MCP server, skills, and discovery manifests for coding agents | [SEO and AEO](/docs/discoverability) |
-| `ai` | The in-page Ask AI assistant and the Open in chat action | [Ask AI](/docs/configuration/ask-ai) |
+| `ai` | The in-page assistant and the Open in chat action | [Assistant](/docs/configuration/assistant) |
 | `reference` | API references: `openapi()`, `asyncapi()`, `graphql()`, and `scalar()` adapters from `blume/reference` | [OpenAPI](/docs/references/openapi), [AsyncAPI](/docs/references/asyncapi), [GraphQL](/docs/references/graphql), [Scalar](/docs/references/scalar) |
 | `analytics` | Adapters from `blume/analytics` — PostHog, Google Analytics, Plausible, Mixpanel, Segment, and more — plus custom scripts | [Analytics](/docs/configuration/analytics) |
 | `seo` | Metadata, OG images, feeds, structured data, sitemap, robots | [SEO and AEO](/docs/discoverability) |

package/docs/configuration/meta.ts

@@ -6,7 +6,7 @@ export default defineMeta({
     "theming",
     "customization",
     "search",
-    "ask-ai",
+    "assistant",
     "analytics",
     "export",
   ],

package/docs/configuration/search.mdx

@@ -115,7 +115,7 @@ i18n: {
 }
 ```
 
-The same tokenizer serves the search dialog, the MCP server's `search_docs` tool, and Ask AI grounding. The script is what decides, not the language name — `az-Cyrl` is segmented while `sr-Latn` is not — and it is the default locale that decides for the whole index: on a mixed-language site every page shares the default locale's tokenizer. With a non-Latin default that's safe, because Latin words survive segmentation intact, so pages in English stay searchable alongside the default language. The reverse doesn't hold: non-Latin translations on a Latin-default site aren't searchable. Latin-script languages that lean heavily on diacritics (Vietnamese, or Serbian in Latin script) also fare worse on the standard tokenizer, which folds only a few accented vowels and splits words on the rest.
+The same tokenizer serves the search dialog, the MCP server's `search_docs` tool, and assistant grounding. The script is what decides, not the language name — `az-Cyrl` is segmented while `sr-Latn` is not — and it is the default locale that decides for the whole index: on a mixed-language site every page shares the default locale's tokenizer. With a non-Latin default that's safe, because Latin words survive segmentation intact, so pages in English stay searchable alongside the default language. The reverse doesn't hold: non-Latin translations on a Latin-default site aren't searchable. Latin-script languages that lean heavily on diacritics (Vietnamese, or Serbian in Latin script) also fare worse on the standard tokenizer, which folds only a few accented vowels and splits words on the rest.
 
 Japanese and Chinese go one step further. Segmenting alone indexes a compound term as its parts — 資金決済法 as 資金, 決済 and 法 — which lets a page mentioning each part somewhere outrank the page the term is actually about. Han, Hiragana and Katakana are therefore indexed as overlapping character pairs, and queries on those indexes prefer pages carrying a term's pairs together, loosening to any-pair matching when no page carries them all, so typing a whole sentence still returns its closest pages. Korean and Thai keep their segmented words.
 

package/docs/content/i18n.mdx

@@ -112,10 +112,10 @@ Anchors travel with the link, so heading ids have to agree across languages. [`b
 
 ## Translating with an agent
 
-You don't have to fill in the locales by hand. [`blume translate`](/docs/cli/translate) finds every page that's missing or outdated in each locale and translates it with a local agent CLI ([Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli)):
+You don't have to fill in the locales by hand. [`blume translate`](/docs/cli/translate) finds every page that's missing or outdated in each locale and translates it with a local agent CLI ([Codex](https://developers.openai.com/codex/cli) or [Claude Code](https://claude.com/claude-code)):
 
 ```bash
-blume translate --claude
+blume translate --codex
 ```
 
 Blume validates each result's structure — frontmatter, code fences, links — and writes the files itself; the agent only translates text. A committed ledger (`blume.translations.json`) tracks which source revision each translation came from, so reruns only touch what changed, and translations you wrote by hand are adopted as-is, never overwritten. In CI, `blume translate --check` fails when a source page has drifted ahead of its translations.

package/docs/content/islands.mdx

@@ -143,7 +143,7 @@ export default function PageInfo() {
 | `useBlume()` | `{ config, navigation }` for the site, or `null` before mount |
 | `usePage()` | `{ route, title }` for the current page, or `null` before mount |
 | `useSearch()` | `{ search, results, loading }` — query the configured search provider |
-| `useAskAI()` | `{ ask, messages, loading, reset }` — stream from the Ask AI endpoint |
+| `useAssistant()` | `{ ask, messages, loading, reset }` — stream from the assistant endpoint |
 
 `useBlume()` and `usePage()` return `null` until the island mounts (so server and client render the same first frame) — guard for it. The snapshot is emitted only on pages that ship React, so a fully static site pays nothing.
 

package/docs/discoverability/agent-discovery.mdx

@@ -15,7 +15,7 @@ agents: {
 }
 ```
 
-The manifest lists only what you've enabled — the [raw Markdown](/docs/discoverability/markdown) mirror pattern, the [JSON API](/docs/discoverability/json-api) and its OpenAPI description, [`llms.txt`](/docs/discoverability/llms-txt) and `llms-full.txt`, the [MCP server](/docs/discoverability/mcp) and its discovery document, the [Ask AI](/docs/configuration/ask-ai) endpoint, the [sitemap](/docs/discoverability/sitemap-and-robots#sitemap), and [RSS feeds](/docs/discoverability/rss) — alongside your site name, description, source repository, and the [content-signal](/docs/discoverability/sitemap-and-robots#content-signals) usage policy. URLs are absolute when [`deployment.site`](/docs/deployment) is set and root-relative otherwise:
+The manifest lists only what you've enabled — the [raw Markdown](/docs/discoverability/markdown) mirror pattern, the [JSON API](/docs/discoverability/json-api) and its OpenAPI description, [`llms.txt`](/docs/discoverability/llms-txt) and `llms-full.txt`, the [MCP server](/docs/discoverability/mcp) and its discovery document, the [assistant](/docs/configuration/assistant) endpoint, the [sitemap](/docs/discoverability/sitemap-and-robots#sitemap), and [RSS feeds](/docs/discoverability/rss) — alongside your site name, description, source repository, and the [content-signal](/docs/discoverability/sitemap-and-robots#content-signals) usage policy. URLs are absolute when [`deployment.site`](/docs/deployment) is set and root-relative otherwise:
 
 ```json agent-readability.json
 {

package/docs/discoverability/index.mdx

@@ -41,7 +41,7 @@ Most of this is sharper with an absolute site URL — set [`deployment.site`](/d
 
 Every generated file yields to one you ship yourself: drop a `robots.txt`, `sitemap.xml`, `llms.txt`, `openapi.json`, or `agent-readability.json` in `public/` and Blume serves yours in its place.
 
-The in-page **Ask AI** assistant is the one AI feature documented elsewhere: it's a reader-facing product feature rather than a discovery surface, so it's configured under `ai` and lives under [Configuration](/docs/configuration/ask-ai).
+The in-page **assistant** is the one AI feature documented elsewhere: it's a reader-facing product feature rather than a discovery surface, so it's configured under `ai` and lives under [Configuration](/docs/configuration/assistant).
 
 ## Checking your work
 

package/docs/index.mdx

@@ -31,7 +31,7 @@ Blume builds on Astro and Vite and renders static HTML by default — fast, cach
 
 ### AI-ready out of the box
 
-Every Blume site speaks fluent machine. It emits [`llms.txt` and `llms-full.txt`](/docs/discoverability/llms-txt), serves any page's raw Markdown by appending `.md` to its URL, exposes a [JSON API described by OpenAPI](/docs/discoverability/json-api), and gives readers **Copy as Markdown** and **Open in chat** actions on every page. Add an optional in-page **Ask AI** assistant, or host an [**MCP server**](/docs/discoverability/mcp) so coding agents like Claude Code and Cursor can search and read your docs directly — no scraping, no hosted service. Your Markdown is the source of truth for both humans and models.
+Every Blume site speaks fluent machine. It emits [`llms.txt` and `llms-full.txt`](/docs/discoverability/llms-txt), serves any page's raw Markdown by appending `.md` to its URL, exposes a [JSON API described by OpenAPI](/docs/discoverability/json-api), and gives readers **Copy as Markdown** and **Open in chat** actions on every page. Add an optional in-page **assistant**, or host an [**MCP server**](/docs/discoverability/mcp) so coding agents like Claude Code and Cursor can search and read your docs directly — no scraping, no hosted service. Your Markdown is the source of truth for both humans and models.
 
 ### Zero configuration — even the template
 
@@ -45,7 +45,7 @@ Your [`blume.config.ts`](/docs/configuration) and every [`meta.ts`](/docs/conten
 
 - **Components** — callouts, cards, steps, tabs, accordions, badges, file trees, and parameter tables, usable in MDX with [no imports](/docs/content/components).
 - **Local search** — Orama works in dev and production; for large sites, Pagefind is one adapter away (`search: pagefind()`). No hosted index.
-- **AI** — [`llms.txt`, raw Markdown URLs, a JSON API with an OpenAPI description, Copy as Markdown, Open in chat, and a hosted MCP server](/docs/discoverability), plus an optional [Ask AI assistant](/docs/configuration/ask-ai).
+- **AI** — [`llms.txt`, raw Markdown URLs, a JSON API with an OpenAPI description, Copy as Markdown, Open in chat, and a hosted MCP server](/docs/discoverability), plus an optional [in-page assistant](/docs/configuration/assistant).
 - **Navigation** — inferred from files, refined with `meta.ts` or config.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD, [built in](/docs/discoverability).
 - **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.