blume 1.7.3 → 2.0.1

package/dist/types/sources/sanity.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { SharedSourceOptions } from "./shared.ts";
+/** Options for {@link sanity}. */
+export interface SanityOptions extends SharedSourceOptions {
+    /** Sanity API version (a date). Defaults to `2024-01-01`. */
+    apiVersion?: string;
+    /** Dataset name to query. */
+    dataset: string;
+    /** Field paths mapping a document onto Blume meta + body. */
+    fields?: {
+        /** Field holding the renderable body (Portable Text or Markdown). */
+        body?: string;
+        /** Field holding the page description. */
+        description?: string;
+        /** Field holding the last-modified date. */
+        lastModified?: string;
+        /** Field holding the page slug. */
+        slug?: string;
+        /** Field holding the page title. */
+        title?: string;
+    };
+    /** Sanity project id. */
+    projectId: string;
+    /** GROQ query selecting the documents to import. */
+    query: string;
+}
+export declare const sanityOptionsSchema: z.ZodObject<{
+    pollInterval: z.ZodOptional<z.ZodNumber>;
+    prefix: z.ZodOptional<z.ZodString>;
+    apiVersion: z.ZodOptional<z.ZodString>;
+    dataset: z.ZodString;
+    fields: z.ZodOptional<z.ZodObject<{
+        body: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        lastModified: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    projectId: z.ZodString;
+    query: z.ZodString;
+}, z.core.$strict>;
+export type SanityAdapter = AdapterDescriptor<"sanity", SanityOptions>;
+export declare const sanityAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"sanity">;
+    options: z.ZodObject<{
+        pollInterval: z.ZodOptional<z.ZodNumber>;
+        prefix: z.ZodOptional<z.ZodString>;
+        apiVersion: z.ZodOptional<z.ZodString>;
+        dataset: z.ZodString;
+        fields: z.ZodOptional<z.ZodObject<{
+            body: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            lastModified: z.ZodOptional<z.ZodString>;
+            slug: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        projectId: z.ZodString;
+        query: z.ZodString;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * A Sanity dataset queried with GROQ; Portable Text bodies become Markdown.
+ * `@sanity/client` is the declared runtime dependency, and a private dataset's
+ * read token comes from `SANITY_TOKEN`.
+ */
+export declare const sanity: (options: SanityOptions) => SanityAdapter;

package/dist/types/sources/shared.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+/** The glob every content-reading adapter defaults `include` to. */
+export declare const DEFAULT_CONTENT_GLOB = "**/*.{md,mdx}";
+/**
+ * Options every built-in content source shares. They ride on the descriptor
+ * beside the adapter's own options, so an adapter declares only what is
+ * specific to it.
+ */
+export interface SharedSourceOptions {
+    /**
+     * Opt-in dev polling interval (seconds) for a remote source; omit to fetch
+     * once and freeze for the session. Local sources (`filesystem()`,
+     * `obsidian()`) watch the filesystem instead and ignore it.
+     */
+    pollInterval?: number;
+    /** Namespaces the source's routes under `/<prefix>/`. */
+    prefix?: string;
+}
+/** The schema for {@link SharedSourceOptions}; each adapter extends it. */
+export declare const sharedSourceOptionsSchema: z.ZodObject<{
+    pollInterval: z.ZodOptional<z.ZodNumber>;
+    prefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Field paths mapping a CMS document onto Blume meta + body. */
+export interface SourceFieldMap {
+    /** Field holding the renderable body (rich text, or a Markdown string). */
+    body?: string;
+    /** Field holding the page description. */
+    description?: string;
+    /** Field holding the last-modified date. */
+    lastModified?: string;
+    /** Field holding the page slug. */
+    slug?: string;
+    /** Field holding the page title. */
+    title?: string;
+}
+/** The schema for {@link SourceFieldMap}. */
+export declare const sourceFieldMapSchema: z.ZodObject<{
+    body: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    lastModified: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Extra query parameters a REST-backed adapter appends to its request. */
+export declare const queryParamsSchema: z.ZodRecord<z.ZodString, z.ZodString>;

package/dist/types/sources/strapi.d.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { SharedSourceOptions, SourceFieldMap } from "./shared.ts";
+/** Options for {@link strapi}. */
+export interface StrapiOptions extends SharedSourceOptions {
+    /** The content type's plural API id (`articles`). */
+    contentType: string;
+    /**
+     * Field paths mapping an entry onto Blume meta + body. Defaults to
+     * `title` / `description` / `slug` / `content` / `updatedAt`.
+     */
+    fields?: SourceFieldMap;
+    /** Locale code to fetch, for a localized content type. */
+    locale?: string;
+    /** Extra query parameters for the request (`"filters[section][$eq]": "sdk"`). */
+    params?: Record<string, string>;
+    /** The `populate` parameter. Defaults to `*`, which fills media and relations. */
+    populate?: string;
+    /** The Strapi origin (`https://cms.acme.dev`); its REST API is at `/api`. */
+    url: string;
+}
+export declare const strapiOptionsSchema: z.ZodObject<{
+    pollInterval: z.ZodOptional<z.ZodNumber>;
+    prefix: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodString;
+    fields: z.ZodOptional<z.ZodObject<{
+        body: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        lastModified: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    locale: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    populate: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+}, z.core.$strict>;
+export type StrapiAdapter = AdapterDescriptor<"strapi", StrapiOptions>;
+export declare const strapiAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"strapi">;
+    options: z.ZodObject<{
+        pollInterval: z.ZodOptional<z.ZodNumber>;
+        prefix: z.ZodOptional<z.ZodString>;
+        contentType: z.ZodString;
+        fields: z.ZodOptional<z.ZodObject<{
+            body: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            lastModified: z.ZodOptional<z.ZodString>;
+            slug: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        locale: z.ZodOptional<z.ZodString>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        populate: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * A Strapi content type read through its REST API; Blocks bodies become
+ * Markdown. The API token comes from `STRAPI_API_TOKEN`, and `--preview`
+ * reads drafts. Nothing to install: the adapter speaks the REST API
+ * directly.
+ */
+export declare const strapi: (options: StrapiOptions) => StrapiAdapter;

package/dist/types/theme/icon-kind.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Classify author-supplied icon strings — built-in Lucide names vs image
+ * paths/URLs vs inline SVG. Shared by nav diagnostics, `<Icon>`, and the
+ * Cmd+K popular-icon resolver so the three shapes stay in sync.
+ */
+/** Image path, remote URL, or data URI — not a Lucide name or inline SVG. */
+export declare const isImageIcon: (value: string) => boolean;
+/** Full `<svg>…</svg>` markup (whitespace-tolerant). */
+export declare const isInlineSvg: (value: string) => boolean;
+/** Image or inline SVG — anything that is not a built-in icon name. */
+export declare const isAssetIcon: (value: string) => boolean;

package/dist/types/theme/icons.d.ts

@@ -0,0 +1,20 @@
+export interface ResolvedIcon {
+    /** Inner SVG markup (self-styled: carries its own fill/stroke). */
+    body: string;
+    /** The resolved icon name. */
+    name: string;
+    /** The icon's viewBox (Lucide is 24×24). */
+    viewBox: string;
+}
+/**
+ * Resolve an icon name to inline SVG. Honors an explicit `lucide:name` prefix;
+ * a bare name resolves against Lucide.
+ */
+export declare const resolveIcon: (name: string) => ResolvedIcon | null;
+/**
+ * Whether a name resolves to a renderable icon. Exactly mirrors
+ * {@link resolveIcon}: a laxer check (e.g. matching the bare name under an
+ * unknown prefix) would let callers suppress their fallback and diagnostics
+ * for a name `<Icon>` then renders as nothing.
+ */
+export declare const hasIcon: (name: string) => boolean;

package/docs/01-quickstart.mdx

@@ -11,49 +11,49 @@ Go from an empty folder to a running docs site in a few commands. Blume needs **
 ## Install and run
 
 <Steps>
-  <Step title="Install Blume">
-    Add the package to a new or existing project.
-
-    ```package-install
-    npm i blume
-    ```
-
-  </Step>
-  <Step title="Scaffold a project">
+  <Step title="Create a project">
     `blume init` asks a few questions — where to create the project, what your
     docs site is called, which template, and where your content lives — then
-    scaffolds the minimum surface: a content folder and a config file. Pass
-    `--yes` to skip the prompts and take the defaults.
+    scaffolds the minimum surface: a content folder, a config file, and a
+    `package.json` with `dev` and `build` scripts. It installs the dependencies
+    with the package manager that ran it. Pass `--yes` to skip the prompts and
+    take the defaults, or `--no-install` to only write the files.
 
-    ```bash
-    blume init
+    ```package-install
+    npx blume init
     ```
 
+    On pnpm 12, add `--allow-build=esbuild` after `pnpm dlx` (`pnpm dlx --allow-build=esbuild blume init`): pnpm 12 refuses to run the install script of esbuild, which Astro depends on, unless you approve it. Inside an existing pnpm workspace, add `allowBuilds: { esbuild: true }` to the workspace's `pnpm-workspace.yaml`; `init` reminds you. With Yarn 2 or later, `init` writes a `.yarnrc.yml` that switches Yarn to a `node_modules` install, which Blume needs; on Yarn 1, run `npx blume init`.
+
     ```txt
     docs/
       index.mdx
     blume.config.ts
+    package.json
     ```
 
   </Step>
   <Step title="Start the dev server">
-    Blume generates the runtime and serves your docs with hot reload.
+    From the project directory, Blume generates the runtime and serves your
+    docs with hot reload.
 
-    ```bash
-    blume dev
+    ```package-install
+    npm run dev
     ```
 
   </Step>
   <Step title="Build for production">
     Static HTML is written to `dist/`, with a local search index built over it.
 
-    ```bash
-    blume build
+    ```package-install
+    npm run build
     ```
 
   </Step>
 </Steps>
 
+Adding Blume to a project that already has a `package.json`? `blume init` leaves existing files alone, so add `"dev": "blume dev"` and `"build": "blume build"` to its scripts, or run `npx blume dev` directly.
+
 :::tip
 Blume works with any package manager and never requires you to set up Astro or Tailwind yourself.
 :::

package/docs/02-deployment.mdx

@@ -1,6 +1,6 @@
 ---
 title: Deployment
-description: Deploy static docs to any host with zero configuration, or switch to server-side rendering with an adapter when you need dynamic behavior.
+description: Deploy static docs to any host with zero configuration, or name a host adapter from blume/deploy to switch to server rendering when you need dynamic behavior.
 sidebar:
   label: Deployment
   order: 2
@@ -22,7 +22,7 @@ A static build includes:
 
 - every docs and custom page as static HTML
 - a local search index (Orama by default, Pagefind opt-in)
-- a [`sitemap.xml`](/docs/discoverability/sitemap-and-robots#sitemap) and [`robots.txt`](/docs/discoverability/sitemap-and-robots#robots) when `deployment.site` is set
+- a [`sitemap.xml`](/docs/discoverability/sitemap-and-robots#sitemap) and [`robots.txt`](/docs/discoverability/sitemap-and-robots#robots) when the site URL is known
 - `llms.txt` and `llms-full.txt` for AI tools
 - redirect pages
 - prerendered [Open Graph images](/docs/discoverability/open-graph) when `seo.og.enabled` is on
@@ -31,7 +31,7 @@ A static build includes:
 
 Sitemaps, canonical tags, RSS, and Open Graph images need an absolute origin. On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume detects it from the platform's environment at build time — no config required.
 
-Set `deployment.site` to override the detected value, or to provide one on hosts that don't expose it (GitHub Pages, S3, a custom CDN):
+Set `site` to override the detected value, or to provide one on hosts that don't expose it (GitHub Pages, S3, a custom CDN). For a static build that's the plain `deployment` object:
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -54,7 +54,7 @@ blume preview
 
 ## Subpath deploys
 
-Serving docs under a path like `example.com/docs`? Set `deployment.base` — common for GitHub Pages project sites. The whole site, root included, moves under the base, and internal links and assets are rewritten to include it.
+Serving docs under a path like `example.com/docs`? Set `base` — common for GitHub Pages project sites. The whole site, root included, moves under the base, and internal links and assets are rewritten to include it.
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -62,6 +62,8 @@ deployment: {
 }
 ```
 
+`base` (and `site`) are options of every host adapter too: `vercel({ base: "/docs" })`.
+
 ## Mount the docs under a path
 
 `basePath` mounts every generated route under a segment (`/docs/getting-started`) while leaving the sidebar untouched — the top level is your sections, not a wrapper group. Use it when the docs live at `/docs/*` but the site root stays yours (like Docusaurus `routeBasePath` or Fumadocs `baseUrl`).
@@ -74,37 +76,59 @@ Write links as if mounted at root (`/getting-started`); Blume rewrites them, alo
 
 This is a distinct concept from the two paths above:
 
-- A per-source [`prefix`](/docs/content/sources#multiple-sources) namespaces **one** source and **does** add a sidebar group.
+- A per-source [`prefix`](/docs/content/sources#adapters) namespaces **one** source and **does** add a sidebar group.
 - `deployment.base` is the host subdirectory the **whole** app is served from. The two compose — with both set, a page lands at `{deployment.base}/{basePath}/page`.
 
 ## Server rendering
 
-Static output covers most docs. Switch to server output when you need request-time features — most notably the [Ask AI](/docs/configuration/ask-ai) endpoint:
+Static output covers most docs. Switch to server output when you need request-time features — most notably the [assistant](/docs/configuration/assistant) endpoint and the [MCP server](/docs/discoverability/mcp). You do that by naming the host: `deployment` takes an adapter imported from `blume/deploy`.
 
 ```ts blume.config.ts lineNumbers
-deployment: {
-  output: "server",
-  adapter: "vercel",
-}
+import { defineConfig } from "blume";
+import { vercel } from "blume/deploy";
+
+export default defineConfig({
+  deployment: vercel(),
+});
+```
+
+Every adapter takes the same named options — `site`, `base`, and `output` — and forwards anything else verbatim to the underlying `@astrojs/*` adapter, so an option Blume doesn't name still reaches it:
+
+```ts blume.config.ts lineNumbers
+deployment: vercel({
+  site: "https://docs.example.com",
+  // Passed straight to @astrojs/vercel.
+  isr: { expiration: 60 },
+}),
 ```
 
-The `vercel` and `node` adapters ship with Blume — choosing one just works. The `netlify` and `cloudflare` adapters must be installed in your project (e.g. `bun add -d @astrojs/netlify`); the CLI warns you if the package is missing:
+| Adapter | Package | Use for |
+| --- | --- | --- |
+| `vercel()` | `@astrojs/vercel` | Vercel — the most polished path |
+| `netlify()` | `@astrojs/netlify` | Netlify Functions |
+| `node()` | `@astrojs/node` | Self-hosted Node servers, containers |
+| `cloudflare()` | `@astrojs/cloudflare` | Cloudflare Workers and Pages |
+
+`vercel()` and `node()` ship with Blume — choosing one just works. `netlify()` and `cloudflare()` need their package installed in your project (e.g. `bun add -d @astrojs/netlify`). If it's missing, `blume build` stops with the install command for your package manager, `blume dev` warns, and [`blume doctor`](/docs/cli/doctor) reports it. With pnpm 10 or later, also approve the build scripts those packages bring (`sharp`, and `workerd` for Cloudflare) under `allowBuilds` in `pnpm-workspace.yaml`, or pnpm stops the install.
+
+Naming an adapter switches the build to server output. To keep a static build on that host — with its site detection and the platform files it reads — pass `output: "static"`:
+
+```ts blume.config.ts lineNumbers
+deployment: netlify({ output: "static" }),
+```
 
-| Adapter      | Package               | Use for                              |
-| ------------ | --------------------- | ------------------------------------ |
-| `vercel`     | `@astrojs/vercel`     | Vercel — the most polished path      |
-| `netlify`    | `@astrojs/netlify`    | Netlify Functions                    |
-| `node`       | `@astrojs/node`       | Self-hosted Node servers, containers |
-| `cloudflare` | `@astrojs/cloudflare` | Cloudflare Workers and Pages         |
+A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node()` adapter produces a standalone server you can run directly with `node dist/server/entry.mjs`. The server resolves its packages through links into your project's `node_modules`, so deploy the project with its installed dependencies, not `dist/` alone. When the site publishes discovery files, Blume puts a small wrapper in front of Astro's entry (moved to `astro-entry.mjs` beside it) so the `.well-known` discovery files go out with their media types and CORS headers, which the standalone server's static handler can't set on its own.
 
-On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching adapter automatically for server output — set `output: "server"` and deploy (on Netlify and Cloudflare, install the adapter package too). Set `adapter` explicitly to override the detected value, or when self-hosting with `node`.
+A `cloudflare()` server build deploys with `npx wrangler deploy` from the project root after `blume build`: Blume writes the redirected Wrangler config to `.wrangler/deploy/` (and adds `.wrangler/` to `.gitignore`), and names the Worker after your project — the `package.json` `name`, else the site's hostname, else the folder — unless a `wrangler.jsonc` of your own at the project root sets `name`.
 
-A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node` adapter produces a standalone server you can run directly.
+On Vercel and Cloudflare, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/discoverability/markdown#content-negotiation), so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL. On Vercel, Blume splices header-conditional rewrites into the deploy's routing config; on Cloudflare, it generates a small Worker in front of the Astro one and points `assets.run_worker_first` at every path except the fingerprinted build assets and the raw `.md`, `.txt`, `.json`, and `.well-known` files, since the platform would otherwise serve the prerendered pages — and its `404.html` for a URL no page backs — before any server code runs; those exempted files keep their zero-Worker fast path. That Worker also answers the prerendered per-page JSON documents (`/api/docs/pages/{route}.json`) from the asset binding when a request for one reaches it, because Astro would otherwise route it to the `/api/` catch-all.
 
-On Vercel and Cloudflare, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/discoverability/markdown#content-negotiation), so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL. On Vercel, Blume splices header-conditional rewrites into the deploy's routing config; on Cloudflare, it generates a small Worker in front of the Astro one and scopes `assets.run_worker_first` to the content routes, since the platform would otherwise serve the prerendered pages before any server code runs — other assets keep their zero-Worker fast path. That Worker also answers the prerendered per-page JSON documents (`/api/docs/pages/{route}.json`) from the asset binding when a request for one reaches it, because Astro would otherwise route it to the `/api/` catch-all.
+:::note
+`vercel` and `cloudflare` are also the names of two [analytics adapters](/docs/configuration/analytics). When one config uses both, alias one of the imports: `import { cloudflare as cloudflareDeploy } from "blume/deploy"`.
+:::
 
 :::note
-Server features have their own configuration — for example, Ask AI needs a model API key. See the [Ask AI guide](/docs/configuration/ask-ai) for setup.
+Server features have their own configuration — for example, the assistant needs a model API key. See the [assistant guide](/docs/configuration/assistant) for setup.
 :::
 
 ## Redirects
@@ -112,22 +136,22 @@ Server features have their own configuration — for example, Ask AI needs a mod
 Map old URLs to new ones in `blume.config.ts`:
 
 ```ts blume.config.ts
-redirects: [{ from: "/old", to: "/new", status: 301 }];
+redirects: [{ from: "/old", to: "/new", status: 301 }],
 ```
 
-`status` accepts `301`, `302`, `307`, or `308` (default `301`). Server builds handle redirects at request time. Static builds emit redirect pages **and** platform files so your host issues a real HTTP redirect: `_redirects` (Netlify, Cloudflare Pages), `vercel.json` (Vercel), and `blume-redirects.json` — a structured manifest for anything else (nginx/Apache rules, an edge worker). A `_redirects` or `vercel.json` you ship in `public/` is left untouched.
+`status` accepts `301`, `302`, `307`, or `308` (default `301`). Server builds handle redirects at request time. Static builds emit redirect pages **and** the platform files your host reads, so it issues a real HTTP redirect: `_redirects` for `netlify()` and `cloudflare()`, `vercel.json` for `vercel()`, and — when no host is named — both of those plus `blume-redirects.json`, a structured manifest for anything else (nginx/Apache rules, an edge worker). A `_redirects` or `vercel.json` you ship in `public/` is left untouched.
 
 :::note
-`from` is matched as an exact path — wildcards and pattern matching (e.g. `/blog/:slug` or `/old/*`) aren't supported. If you need pattern-based rules, handle them in an infrastructure file like `vercel.json` (which supports wildcard `source` patterns) or your host's redirect config instead. A `vercel.json` you ship in `public/` is preserved as-is.
+`from` and `to` are exact paths — a `:param` segment or `*` wildcard (e.g. `/blog/:slug` or `/old/*`) fails config validation, since hosts disagree on patterns. If you need pattern-based rules, handle them in an infrastructure file like `vercel.json` (which supports wildcard `source` patterns) or your host's redirect config instead. A `vercel.json` you ship in `public/` is preserved as-is.
 :::
 
 :::note
-Write both `from` and `to` as if mounted at root — under [`deployment.base`](#subpath-deploys) and [`basePath`](#mount-the-docs-under-a-path) alike, Blume rewrites both sides for you, so a redirect lands inside the base. A base you've already written into `to` by hand is preserved rather than doubled.
+Write both `from` and `to` as if mounted at root — under [`base`](#subpath-deploys) and [`basePath`](#mount-the-docs-under-a-path) alike, Blume rewrites both sides for you, so a redirect lands inside the base. A base you've already written into `to` by hand is preserved rather than doubled.
 :::
 
 ## Content types
 
-A static build also emits a `_headers` file that pins `charset=utf-8` onto the raw AI-ready endpoints — `/<route>.md`, `/<route>.mdx`, and the `.txt` files (`llms.txt`, `llms-full.txt`). Those responses are valid UTF-8, but many static hosts serve them as `text/markdown` / `text/plain` with **no** charset, and browsers then fall back to Windows-1252 — so non-ASCII docs (Japanese, accented Latin, …) render as mojibake when the raw URL is opened directly. HTML pages are unaffected because they carry `<meta charset>`. Netlify and Cloudflare (Pages/Workers static assets) read `_headers`; hosts that don't (Vercel, S3) ignore the file harmlessly. A `_headers` you ship in `public/` is left untouched.
+Where the host reads one, a build also emits a `_headers` file that pins `charset=utf-8` onto the raw AI-ready endpoints — `/<route>.md`, `/<route>.mdx`, and the `.txt` files (`llms.txt`, `llms-full.txt`). Those responses are valid UTF-8, but many static hosts serve them as `text/markdown` / `text/plain` with **no** charset, and browsers then fall back to Windows-1252 — so non-ASCII docs (Japanese, accented Latin, …) render as mojibake when the raw URL is opened directly. HTML pages are unaffected because they carry `<meta charset>`. Netlify reads `_headers` on a static deploy and Cloudflare (Pages, and Workers static assets) on both static and server builds, so those adapters and an unnamed static host get the file; Vercel (whose headers ride the routing config) and Node (whose server ignores the file) don't. A `_headers` you ship in `public/` is left untouched.
 
 ## Environment variables
 
@@ -135,8 +159,8 @@ When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it'
 
 | Feature | Variable |
 | --- | --- |
-| Ask AI (AI Gateway) | `AI_GATEWAY_API_KEY` (or Vercel OIDC) |
-| Ask AI (other providers) | the provider's default key env var (`OPENROUTER_API_KEY`, `LLMGATEWAY_API_KEY`, `INKEEP_API_KEY`), or your configured `apiKeyEnv` |
+| Assistant (AI Gateway) | `AI_GATEWAY_API_KEY` (or Vercel OIDC) |
+| Assistant (other adapters) | the adapter's default key env var (`OPENROUTER_API_KEY`, `LLMGATEWAY_API_KEY`, `INKEEP_API_KEY`), or the `apiKeyEnv` you passed it |
 | Mixedbread search | `MIXEDBREAD_API_KEY` |
 
 Set them in `.env.local` for local dev and in your host's environment for production. Build-time secrets for search-index sync (Algolia, Orama Cloud, Typesense) are warned about separately during the sync step.