blume 1.6.2 → 1.6.4

package/dist/types/ai/component-markdown.d.ts

@@ -46,6 +46,7 @@ interface MdxAttribute {
 export type EvaluatedValue = string | number | boolean | null | undefined | Date | EvaluatedValue[] | {
     [key: string]: EvaluatedValue;
 };
+export declare const isString: <Value>(value: Value) => value is Value & string;
 /** Evaluated props plus whether any attribute resisted static evaluation. */
 interface EvaluatedProps {
     lossy: boolean;
@@ -94,6 +95,19 @@ export interface ComponentMarkdownContext extends EvaluatedProps {
  * fallback when the props can't be recovered statically).
  */
 export type ComponentMarkdown = (context: ComponentMarkdownContext) => string | null;
+/**
+ * A link destination. Whitespace ends one, and a `)` ends one unless it is
+ * part of a balanced pair — so an href carrying either goes in the angle
+ * bracket form, where only `<` and `>` are special.
+ */
+export declare const linkDestination: (href: string) => string;
+/**
+ * `text` as an inline code span whose delimiter outlengths any backtick run
+ * inside it, padded with a space when the content starts or ends with a
+ * backtick (CommonMark strips one such pair) — so a spec path or address
+ * carrying a backtick cannot close the span early.
+ */
+export declare const inlineCode: (text: string) => string;
 /**
  * Build the `<Component>` serializer for a project's discovered examples. The
  * live preview can't survive the trip to Markdown, so the agent-facing output

package/docs/01-quickstart.mdx

@@ -86,8 +86,8 @@ Save it, and the dev server reloads instantly. Navigation, search, and page meta
   <Card title="Components" href="/docs/content/components" icon="folder">
     Explore the built-in component library.
   </Card>
-  <Card title="AI" href="/docs/configuration/ai" icon="lightbulb">
-    Ship `llms.txt` and an Ask AI assistant.
+  <Card title="Discoverability" href="/docs/discoverability" icon="lightbulb">
+    Ship `llms.txt`, social cards, and an MCP server.
   </Card>
   <Card title="Deployment" href="/docs/deployment" icon="rocket">
     Go live on any static host.

package/docs/02-deployment.mdx

@@ -22,10 +22,10 @@ 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/configuration/seo#sitemap) and [`robots.txt`](/docs/configuration/seo#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 `deployment.site` is set
 - `llms.txt` and `llms-full.txt` for AI tools
 - redirect pages
-- prerendered [Open Graph images](/docs/configuration/seo#open-graph-images) when `seo.og.enabled` is on
+- prerendered [Open Graph images](/docs/discoverability/open-graph) when `seo.og.enabled` is on
 
 ### Set your site URL
 
@@ -79,7 +79,7 @@ This is a distinct concept from the two paths above:
 
 ## Server rendering
 
-Static output covers most docs. Switch to server output when you need request-time features — most notably the [Ask AI](/docs/configuration/ai) endpoint:
+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:
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -101,10 +101,10 @@ On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching a
 
 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/configuration/ai#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.
+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.
 
 :::note
-Server features have their own configuration — for example, Ask AI needs a model API key. See the [AI guide](/docs/configuration/ai) for setup.
+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.
 :::
 
 ## Redirects

package/docs/{07-faq.mdx → 08-faq.mdx}

@@ -87,13 +87,13 @@ We reported it upstream in [oxc-project/oxc#24096](https://github.com/oxc-projec
 
 Patch oxfmt so it preserves the line break that sits directly against a `:::` fence. Blume ships the same fix in its own repo, and you can apply it in any project.
 
-1. Save the patch as `patches/oxfmt@0.66.0.patch`:
+1. Save the patch as `patches/oxfmt@0.67.0.patch`:
 
-   ```diff patches/oxfmt@0.66.0.patch
-   diff --git a/dist/markdown-BgZGxhM2.js b/dist/markdown-BgZGxhM2.js
-   index 859231f9387a50df16419bc22b5268c4e446ddbc..dcc0ffda6f71adb27a03e3918a3db6fc7a58ffe9 100644
-   --- a/dist/markdown-BgZGxhM2.js
-   +++ b/dist/markdown-BgZGxhM2.js
+   ```diff patches/oxfmt@0.67.0.patch
+   diff --git a/dist/markdown-BMigo7Hm.js b/dist/markdown-BMigo7Hm.js
+   index bc9037f6c0de5516b139d8cdb195b1e25cd33bc0..a02c284e28bb535f9964a8a086ebb6549657e416 100644
+   --- a/dist/markdown-BMigo7Hm.js
+   +++ b/dist/markdown-BMigo7Hm.js
    @@ -4872,7 +4872,43 @@ function lu(e, t, r) {
     		case "sentence": return Oh(e, r);
     		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
@@ -146,7 +146,7 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    ```json package.json
    {
      "patchedDependencies": {
-       "oxfmt@0.66.0": "patches/oxfmt@0.66.0.patch"
+       "oxfmt@0.67.0": "patches/oxfmt@0.67.0.patch"
      }
    }
    ```

package/docs/advanced/blog.mdx

@@ -26,7 +26,7 @@ Give every post a `date` so feed items sort newest-first and carry a `pubDate`,
 
 Blume builds a blog feed at **`/blog/rss.xml`**, sorted newest-first by `date`. Feeds need an absolute site URL, so set [`deployment.site`](/docs/deployment); Blume then injects a `<link rel="alternate">` tag on every page so readers discover it automatically.
 
-The feed is on by default. Tune it under [`seo.rss`](/docs/configuration/seo#rss-feeds):
+The feed is on by default. Tune it under [`seo.rss`](/docs/discoverability/rss):
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -42,7 +42,7 @@ Remove `"blog"` from `rss.types` to skip the feed.
 
 ## Structured data
 
-When [structured data](/docs/configuration/seo#structured-data) is on, each post is emitted as a schema.org **`BlogPosting`** with its description and publish date — the richer article type search engines expect for blog content.
+When [structured data](/docs/discoverability/structured-data) is on, each post is emitted as a schema.org **`BlogPosting`** with its description and publish date — the richer article type search engines expect for blog content.
 
 ## Building an index
 
@@ -99,7 +99,7 @@ See [Custom Pages](/docs/advanced/custom-pages#using-the-site-layout) for wrappi
   <Card title="Custom Pages" href="/docs/advanced/custom-pages" icon="folder">
     Mount the blog index and read from blume:data.
   </Card>
-  <Card title="SEO" href="/docs/configuration/seo" icon="file">
+  <Card title="Discoverability" href="/docs/discoverability" icon="file">
     Feeds, Open Graph images, and structured data.
   </Card>
 </CardGroup>

package/docs/advanced/changelog.mdx

@@ -103,7 +103,7 @@ The release name becomes the title, its tag becomes `changelog.version`, and its
 
 Blume also builds a changelog feed at **`/changelog/rss.xml`**, sorted newest-first by `date`. Feeds need an absolute site URL, so set [`deployment.site`](/docs/deployment); Blume then injects a `<link rel="alternate">` tag on every page so readers discover it automatically.
 
-The feed is on by default. Tune it under [`seo.rss`](/docs/configuration/seo#rss-feeds):
+The feed is on by default. Tune it under [`seo.rss`](/docs/discoverability/rss):
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -119,7 +119,7 @@ Remove `"changelog"` from `rss.types` to skip the feed while keeping the timelin
 
 ## Structured data
 
-When [structured data](/docs/configuration/seo#structured-data) is on, each changelog entry is emitted as a schema.org **`TechArticle`** with its description and publish date, so search engines can index releases as dated articles.
+When [structured data](/docs/discoverability/structured-data) is on, each changelog entry is emitted as a schema.org **`TechArticle`** with its description and publish date, so search engines can index releases as dated articles.
 
 <CardGroup cols={2}>
   <Card

package/docs/advanced/custom-pages.mdx

@@ -222,7 +222,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/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 [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.
 
 Passing `siteUrl` (and `ogEnabled`) derives the page's `canonical` and a generated `og:image` automatically: Blume renders an Open Graph card for every static custom page — the home included, the most-shared URL — served at `/og/<route>.png` (`/og/index.png` for `/`). The home card uses the site title with the description as its eyebrow; a deeper page is titled from its last path segment. Set `ogImage` or `canonical` explicitly to override either. `ogImage` takes a root-relative path — a file in `public/`, resolved against [`deployment.site`](/docs/deployment) to the absolute URL crawlers need — or an external URL, which passes through untouched:
 
@@ -241,7 +241,7 @@ Passing `siteUrl` (and `ogEnabled`) derives the page's `canonical` and a generat
 
 Only this page changes — every other route keeps its generated card — so it's how you give the home page alone a bespoke share image. The generated card declares its size and alt text to crawlers on its own; for your own `ogImage`, pass `ogImageAlt` and `ogImageSize` alongside so the share card gets the same treatment.
 
-The page also emits schema.org JSON-LD — the same `WebSite` graph the docs pages carry, so the home page (usually a custom page) isn't the one URL without structured data. Pass `structuredDataEnabled={config.structuredData}` to keep it in sync with the [`structuredData`](/docs/configuration/seo) config, or `structuredDataEnabled={false}` to turn it off for one page.
+The page also emits schema.org JSON-LD — the same `WebSite` graph the docs pages carry, so the home page (usually a custom page) isn't the one URL without structured data. Pass `structuredDataEnabled={config.structuredData}` to keep it in sync with the [`structuredData`](/docs/discoverability/structured-data) config, or `structuredDataEnabled={false}` to turn it off for one page.
 
 `page.title` is used verbatim as the document title (no `- siteTitle` suffix), since marketing pages usually set their own. To give a custom page the full docs chrome instead — sidebar, TOC, and all — wrap it in `RootLayout`, the layout the generated pages use. Pull the required props straight from `blume:data`:
 
@@ -272,9 +272,9 @@ import data from "blume:data";
 
 ## 404 page
 
-Blume ships a default **not found** page out of the box: a centered "404" message wrapped in the site chrome (header, search, theme), served for any unmatched URL. `blume build` writes it to `404.html`, which static hosts serve automatically, and `blume dev` shows it for unknown routes. Under the message, a **Where to look next** list links every top-level section plus the `sitemap.xml` and [`llms.txt`](/docs/configuration/ai#llmstxt) indexes when they exist, so a reader — or an agent that followed a stale URL — has a way back.
+Blume ships a default **not found** page out of the box: a centered "404" message wrapped in the site chrome (header, search, theme), served for any unmatched URL. `blume build` writes it to `404.html`, which static hosts serve automatically, and `blume dev` shows it for unknown routes. Under the message, a **Where to look next** list links every top-level section plus the `sitemap.xml` and [`llms.txt`](/docs/discoverability/llms-txt) indexes when they exist, so a reader — or an agent that followed a stale URL — has a way back.
 
-The page also has a Markdown twin at `/404.md` and a JSON twin at `/404.json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details) with the same recovery links (absolute URLs once [`deployment.site`](/docs/deployment) is set), plus the [`openapi.json`](/docs/configuration/ai#json-api) description when the JSON API is on. On a [Vercel server build](/docs/deployment#server-rendering), a request for a missing page that sends [`Accept: text/markdown`](/docs/configuration/ai#content-negotiation), or asks for a `.md` URL no page backs, gets the Markdown body with the `404` status instead of the HTML shell; one that sends `Accept: application/json`, or asks for a `.json` URL no file backs, gets the problem document — so an agent never has to parse a page of chrome to learn where to go next.
+The page also has a Markdown twin at `/404.md` and a JSON twin at `/404.json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details) with the same recovery links (absolute URLs once [`deployment.site`](/docs/deployment) is set), plus the [`openapi.json`](/docs/discoverability/json-api) description when the JSON API is on. On a [Vercel server build](/docs/deployment#server-rendering), a request for a missing page that sends [`Accept: text/markdown`](/docs/discoverability/markdown#content-negotiation), or asks for a `.md` URL no page backs, gets the Markdown body with the `404` status instead of the HTML shell; one that sends `Accept: application/json`, or asks for a `.json` URL no file backs, gets the problem document — so an agent never has to parse a page of chrome to learn where to go next.
 
 To replace it with your own, add a `pages/404.astro`. It owns the `/404` route the same way `pages/changelog.astro` takes over the changelog — your page wins and the default is dropped. Build it like any other custom page, in `PageLayout` or `RootLayout`:
 

package/docs/advanced/meta.ts

@@ -1,7 +1,7 @@
 import { defineMeta } from "blume";
 
 export default defineMeta({
-  order: 5,
+  order: 6,
   pages: [
     "skills",
     "custom-pages",

package/docs/configuration/ask-ai.mdx

@@ -0,0 +1,179 @@
+---
+title: Ask AI
+description: An in-page assistant grounded in your docs — suggested questions, custom instructions, retrieval sizing, backends from the Vercel AI Gateway to any OpenAI-compatible endpoint, and the server output it needs.
+---
+
+Add an assistant that answers reader questions in an in-page chat panel, backed by a streaming server endpoint and the [AI SDK](https://ai-sdk.dev). It's opt-in, and static docs stay fully static until you turn it on:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    provider: "gateway", // default
+    model: "openai/gpt-5.5",
+  },
+}
+```
+
+## Suggested questions
+
+Seed the empty state with a few starter prompts. Each renders as a clickable suggestion — click one to send it — with an optional [Lucide icon](/docs/content/components#icon) beside the label:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    suggestions: [
+      { label: "What is Blume?", icon: "rocket" },
+      { label: "How do I write a docs page?", icon: "file-text" },
+      { label: "How do I configure the theme?", icon: "settings" },
+    ],
+  },
+}
+```
+
+`label` is the question that gets asked; `icon` is optional. Leave `suggestions` unset (or empty) and the panel opens to a plain input.
+
+## Custom instructions
+
+Add your own system-prompt text with `instructions` — identity, language, tone, or anything else the assistant should keep in mind:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    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.",
+  },
+}
+```
+
+Your text is **appended to** the built-in instructions rather than replacing them: the built-in part carries the [grounding](#grounding) contract — answer only from the retrieved pages, cite them as Markdown links — that the chat panel's citations depend on, so it stays intact whatever you add.
+
+## 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 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 when search is set to `none` — and needs no configuration.
+
+Grounding is on for every backend except **[Inkeep](#backends)**, which runs its own retrieval over the content you've indexed in its dashboard.
+
+## Retrieval size
+
+How much documentation a question carries is the biggest lever on how long the reader waits for the first word: the model reads every injected character before it emits a token. On a hosted frontier model that's invisible, but on a self-hosted backend it dominates. `retrieval` sizes it:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    retrieval: {
+      maxResults: 3, // fewer pages retrieved per question
+      excerptChars: 1200, // shorter excerpt from each one
+      contextBudget: 3000, // smaller total injection
+    },
+  },
+}
+```
+
+| Option          | Default | Description                                     |
+| --------------- | ------- | ----------------------------------------------- |
+| `maxResults`    | `6`     | Documents retrieved per question.               |
+| `excerptChars`  | `2000`  | Characters kept from each retrieved page.       |
+| `contextBudget` | `10000` | Total injected characters, across all excerpts. |
+
+The three aren't interchangeable. `contextBudget` caps the whole injection, `excerptChars` decides how deep into a single long page its excerpt reaches — raise it when one page holds the whole answer and the excerpt cuts it off — and `maxResults` caps how many pages retrieval adds. The page the reader is viewing is injected on top of the retrieved ones, so an answer can cite up to one page more than `maxResults`.
+
+The defaults suit a hosted model. Lower them when you're serving from your own hardware and time-to-first-token matters more than recall; answers stay grounded either way, and the assistant is told to say when something isn't covered rather than fill the gap.
+
+## External endpoint
+
+Already have an API backend for AI? Point the panel at it and keep the docs build static:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    endpoint: "https://api.example.com/v1/docs/ask",
+  },
+}
+```
+
+Blume sends the same `POST` body as its built-in route:
+
+```json
+{
+  "messages": [{ "role": "user", "content": "How do I deploy?" }],
+  "page": { "path": "/deployment" }
+}
+```
+
+Return a successful response whose body is a plain UTF-8 text stream. If the endpoint is on another origin, allow the docs origin with CORS: accept `OPTIONS` and `POST`, permit the `content-type` request header, and return the CORS headers on both the preflight and streamed response. With `endpoint` set, Blume generates the chat UI but no server route, grounding snapshot, provider dependency, or provider-secret warning; your backend owns retrieval, authentication, rate limiting, model access, and citations.
+
+## 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. Switch to server output and pick an adapter:
+
+```ts blume.config.ts lineNumbers
+deployment: {
+  output: "server",
+  adapter: "vercel",
+}
+```
+
+A static build with Ask AI enabled and no external `endpoint` fails fast with a message telling you to set `deployment.output` to `server`. See [Deployment](/docs/deployment) for the adapters.
+
+## Backends
+
+By default Ask AI routes through the **Vercel AI Gateway**: `model` is a `provider/model` string, so you switch models by changing it (`openai/gpt-5.5`, `anthropic/claude-sonnet-4-5`, and so on) with no provider SDK to install. The gateway reads `AI_GATEWAY_API_KEY` from your environment and is wired up automatically when you deploy on Vercel.
+
+Set `provider` to point Ask AI somewhere else. Each backend reads its API key from an environment variable and streams through a provider SDK you install in your project — only the one you use:
+
+| `provider` | `model` | API key env var | SDK to install |
+| --- | --- | --- | --- |
+| `gateway` (default) | a `provider/model` string via the AI Gateway | `AI_GATEWAY_API_KEY` | none — ships with Blume |
+| `openrouter` | any [OpenRouter](https://openrouter.ai) model | `OPENROUTER_API_KEY` | `@openrouter/ai-sdk-provider` |
+| `llmgateway` | any [LLMGateway](https://llmgateway.io) model | `LLMGATEWAY_API_KEY` | `@ai-sdk/openai-compatible` |
+| `inkeep` | an [Inkeep](https://inkeep.com) QA model | `INKEEP_API_KEY` | `@ai-sdk/openai-compatible` |
+| `openai-compatible` | whatever your endpoint serves | set with `apiKeyEnv` | `@ai-sdk/openai-compatible` |
+
+The SDKs are optional peer dependencies, so add the one your backend needs to your project (e.g. `npm install @openrouter/ai-sdk-provider`). If it's missing, the build warns with the exact package name before Vite would fail to resolve the import.
+
+For example, to use OpenRouter:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    provider: "openrouter",
+    model: "anthropic/claude-sonnet-4-5",
+  },
+}
+```
+
+Any OpenAI-compatible endpoint works through `openai-compatible` — supply the `baseUrl` and the env var holding its key:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    provider: "openai-compatible",
+    baseUrl: "https://my-gateway.example.com/v1",
+    apiKeyEnv: "MY_GATEWAY_API_KEY",
+    model: "gpt-4o",
+  },
+}
+```
+
+Set `apiKeyEnv` (and, for the named providers, `baseUrl`) on any backend to point at a different env var or proxy.
+
+:::note
+**Inkeep** answers from the content you've indexed in the Inkeep dashboard — it runs its own retrieval — so Blume leaves it ungrounded. Every other backend is [grounded](#grounding) in this site's pages.
+:::
+
+Keys are read with `process.env`, which covers the Node, Vercel, and Netlify adapters. On Cloudflare, expose the key through the platform's [runtime binding](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets). Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
+
+## Rate limiting
+
+The `POST /api/ask` endpoint is **unauthenticated** — it has to be, so the in-page assistant can call it. Blume validates each request — rejecting malformed bodies, capping it to 1–40 messages, and accepting only `user`/`assistant` roles so a caller can't inject their own system prompt and repurpose the route as a general LLM proxy — to bound how much a single call can spend against your model, but it can't stop someone from calling the endpoint repeatedly. If cost abuse is a concern, put the route behind a rate limiter — your host's (e.g. Vercel's) edge rate limiting, a middleware, or your model provider's per-key spend limits.
+
+The endpoint is advertised in the [agent readability manifest](/docs/discoverability/agent-discovery#agent-readability) alongside the rest of the site's machine-readable surface.

package/docs/configuration/index.mdx

@@ -65,7 +65,7 @@ export default defineConfig({
     },
   },
 
-  // AI — see the AI guide
+  // AI — llms.txt, MCP; see the Discoverability section
   ai: {
     llmsTxt: true,
     // MCP server (needs server output)
@@ -75,7 +75,7 @@ export default defineConfig({
     },
   },
 
-  // SEO — OG images, feeds, sitemap, structured data; see the SEO guide
+  // SEO — OG images, feeds, sitemap, structured data; see the Discoverability section
   seo: {
     og: { enabled: true },
     rss: { enabled: true, types: ["blog", "changelog"] },
@@ -266,7 +266,7 @@ export default defineConfig({
 
 A key can be declared site-wide or per-type, not both. See [Per-type keys](/docs/reference/frontmatter#per-type-keys) for how the scoping resolves.
 
-`facets` names the custom keys whose values become filterable metadata: they ride along on search documents (`blume-search.json` and the MCP index), and the [MCP tools](/docs/configuration/ai#mcp-server) accept a `filters` input matching against them, so an agent can retrieve, say, only `enforced` RFCs in the `architecture` domain. Each facet must be a declared custom key — per-type or site-wide — and only string (or stringified number/boolean) values facet.
+`facets` names the custom keys whose values become filterable metadata: they ride along on search documents (`blume-search.json` and the MCP index), and the [MCP tools](/docs/discoverability/mcp) accept a `filters` input matching against them, so an agent can retrieve, say, only `enforced` RFCs in the `architecture` domain. Each facet must be a declared custom key — per-type or site-wide — and only string (or stringified number/boolean) values facet.
 
 ## GitHub
 
@@ -363,9 +363,9 @@ dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },
 | `timeZone` | IANA time zone. Defaults to `UTC`, so a date reads the same regardless of where the site builds. |
 | `calendar`, `numberingSystem` | Calendar system (e.g. `"japanese"`) and numbering system (e.g. `"arab"`). |
 
-## SEO
+## SEO and AI
 
-Open Graph images, RSS feeds, and JSON-LD structured data, grouped under `seo`. See the [SEO guide](/docs/configuration/seo) for metadata, frontmatter overrides, and the full reference.
+Metadata, Open Graph images, RSS feeds, JSON-LD, the sitemap, and `robots.txt` live under `seo`; `llms.txt`, raw Markdown, the JSON API, and the MCP server live under `ai`. 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.
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -417,9 +417,10 @@ Each of these has its own guide. The config field is the entry point:
 | `navigation` | Explicit sidebar and header tabs | [Navigation](/docs/content/navigation) |
 | `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) |
-| `ai` | `llms.txt`, Ask AI, and the hosted MCP server for coding agents | [AI](/docs/configuration/ai) |
+| `ai` | `llms.txt`, Markdown mirrors, the JSON API, and the hosted MCP server for coding agents | [SEO and AEO](/docs/discoverability) |
+| `ai.ask` | The in-page Ask AI assistant | [Ask AI](/docs/configuration/ask-ai) |
 | `analytics` | Vercel, PostHog, and custom scripts | [Analytics](/docs/configuration/analytics) |
-| `seo` | Metadata, OG images, feeds, structured data | [SEO](/docs/configuration/seo) |
+| `seo` | Metadata, OG images, feeds, structured data, sitemap, robots | [SEO and AEO](/docs/discoverability) |
 | `deployment` | Output mode, adapter, and site URL | [Deployment](/docs/deployment) |
 | `redirects` | Permanent and temporary redirects | [Deployment](/docs/deployment#redirects) |
 | `integrations` | Astro integrations appended after Blume's built-ins | [Customization](/docs/configuration/customization#astro-integrations) |

package/docs/configuration/meta.ts

@@ -6,10 +6,9 @@ export default defineMeta({
     "theming",
     "customization",
     "search",
-    "ai",
+    "ask-ai",
     "analytics",
     "export",
-    "seo",
   ],
   title: "Configuration",
 });

package/docs/configuration/search.mdx

@@ -52,7 +52,7 @@ search: {
 },
 ```
 
-Each fence's body and title (`blume.config.ts` above) become searchable; the language and fence markers don't. On `.mdx` pages the index reads components as the text they show — a Card's title, a Tab's label, a TypeTable's descriptions — using the same serializers as the [agent surfaces](/docs/configuration/ai), so an `ai.markdownComponents` entry covers your own components too. The option has no effect on Pagefind or Mixedbread. Expect the index to grow with your fenced content — the client index ships to every reader, hosted providers cap record size (Algolia rejects the sync batch when one page's record exceeds its plan's limit, leaving the previous index live), and a hit inside a fence shows flattened code in the result excerpt.
+Each fence's body and title (`blume.config.ts` above) become searchable; the language and fence markers don't. On `.mdx` pages the index reads components as the text they show — a Card's title, a Tab's label, a TypeTable's descriptions — using the same serializers as the [agent surfaces](/docs/discoverability/markdown), so an `ai.markdownComponents` entry covers your own components too. The option has no effect on Pagefind or Mixedbread. Expect the index to grow with your fenced content — the client index ships to every reader, hosted providers cap record size (Algolia rejects the sync batch when one page's record exceeds its plan's limit, leaving the previous index live), and a hit inside a fence shows flattened code in the result excerpt.
 
 On a [versioned](/docs/content/versioning) site, results default to the version being viewed, with an "All versions" toggle in the dialog footer (remembered per reader). Cross-version hits name their version on the row. Orama, FlexSearch, Algolia, and Typesense honor the scoping — hosted records carry a `version` facet, with the current docs uploaded as `"current"` — while Pagefind stays unscoped, matching its locale behavior.
 

package/docs/configuration/theming.mdx

@@ -145,7 +145,7 @@ theme: {
 Paths resolve from the project root. `weight` and `style` (`normal`, `italic`, `oblique`) are optional — Astro reads them from the font file when omitted.
 
 :::note
-When you set `theme.fonts` explicitly, your display and body fonts also style the generated [Open Graph cards](/docs/configuration/seo#card-fonts) automatically, so shared links match the site. Non-Google provider families are skipped there (the card renderer can only fetch from Google Fonts); local files work everywhere.
+When you set `theme.fonts` explicitly, your display and body fonts also style the generated [Open Graph cards](/docs/discoverability/open-graph#card-fonts) automatically, so shared links match the site. Non-Google provider families are skipped there (the card renderer can only fetch from Google Fonts); local files work everywhere.
 :::
 
 Want to drop back to the system stack? Override the `--blume-font-*` tokens directly in [`theme.css`](#themecss).

package/docs/content/components.mdx

@@ -251,7 +251,7 @@ Lay cards or blocks out in a responsive grid of equal columns that reflows on mo
 
 ## CodeGroup
 
-Group several code blocks into one tabbed switcher — a tab per language or file. The tab label is each block's title (the text after the language). Add `dropdown` to switch with a menu instead of a tab bar.
+Group several code blocks into one tabbed switcher — a tab per language or file. The tab label is each block's title (the text after the language), and the group's copy button sits in the tab bar and copies the block that is showing. Add `dropdown` to switch with a menu instead of a tab bar.
 
 <CodeGroup>
 

package/docs/content/i18n.mdx

@@ -102,6 +102,12 @@ Fallback pages are excluded from the search index and aren't advertised as real
 Start by translating your most important pages — the homepage, quickstart, and top guides — and let the rest fall back. You can fill in translations over time without breaking any links.
 :::
 
+## Links across locales
+
+Write internal links the way you would in the default locale — `[Setup](/guides/setup)`, `<Card href="/guides/setup">` — in every language, including translated pages. When a page renders under a locale prefix, Blume moves each root-relative page link into that locale (`/fr/guides/setup`) as long as the route is served there, as a real translation or as a fallback page. A link with no per-locale variant — a custom page, a generated route, or a missing translation on a site with fallbacks disabled — keeps its authored target rather than pointing at a 404, and a link that already carries a locale prefix (`/de/guides/setup`) is left alone, so cross-locale links stay explicit.
+
+Anchors travel with the link, so heading ids have to agree across languages. [`blume translate`](/docs/reference/translate) takes care of that: every translated heading is pinned to its source heading's id with a trailing `[#id]` marker. In a translation you write by hand, pin the headings yourself with the same [`[#custom-id]` marker](/docs/content/syntax#custom-anchors) — otherwise `#ordering` won't match the French page's auto-generated `#ordre`, and `blume validate` reports the mismatch against the translated page a reader actually lands on.
+
 ## Translating with an agent
 
 You don't have to fill in the locales by hand. [`blume translate`](/docs/reference/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)):
@@ -160,7 +166,7 @@ Set `dir: "rtl"` on a locale and Blume mirrors the whole interface — the sideb
   <Card title="Navigation" href="/docs/content/navigation" icon="menu">
     Shape each locale's sidebar, ordering, and tabs.
   </Card>
-  <Card title="SEO" href="/docs/configuration/seo" icon="rocket">
+  <Card title="Discoverability" href="/docs/discoverability" icon="rocket">
     Sitemaps, Open Graph, and structured data.
   </Card>
 </CardGroup>

package/docs/content/index.mdx

@@ -82,7 +82,7 @@ The type is independent of where the file lives, but by convention blog posts go
 
 ## Feeds
 
-Blume generates an RSS feed automatically for each content type listed in [`rss.types`](/docs/configuration/seo#rss-feeds) — `blog` and `changelog` by default — as long as it has at least one page. Feeds are served at `/<type>/rss.xml`:
+Blume generates an RSS feed automatically for each content type listed in [`rss.types`](/docs/discoverability/rss) — `blog` and `changelog` by default — as long as it has at least one page. Feeds are served at `/<type>/rss.xml`:
 
 | Type        | Feed                 |
 | ----------- | -------------------- |

package/docs/content/navigation.mdx

@@ -275,7 +275,7 @@ navigation: {
 }
 ```
 
-That's for a project whose docs repo is private. `github` drives the per-page edit link, the header mark and the [agent manifest](/docs/configuration/ai)'s repository together, so such a project has to leave `github` unset — and a URL is what lets it still show a mark pointing somewhere public. The icon stays the GitHub mark, so a link to another host belongs in [`actions`](#header-actions).
+That's for a project whose docs repo is private. `github` drives the per-page edit link, the header mark and the [agent manifest](/docs/discoverability/agent-discovery)'s repository together, so such a project has to leave `github` unset — and a URL is what lets it still show a mark pointing somewhere public. The icon stays the GitHub mark, so a link to another host belongs in [`actions`](#header-actions).
 
 ## Breadcrumbs and pagination
 
@@ -296,6 +296,6 @@ Below the table of contents, every page shows a set of quick actions:
 - **Scroll to top** — smoothly returns to the top of long pages.
 - **Give feedback** — opens a prefilled GitHub issue with an optional reaction and note (also requires `github`).
 
-Others hand the page to AI tools — **Copy as Markdown** and **Open in chat** — covered in [AI](/docs/configuration/ai#copy-as-markdown).
+Others hand the page to AI tools — **Copy as Markdown** and **Open in chat** — covered in [AI](/docs/discoverability/markdown#copy-as-markdown).
 
 With [`export`](/docs/configuration/export) on, an **Export** action also lets readers download the page as a PDF or EPUB.

package/docs/content/syntax.mdx

@@ -359,7 +359,7 @@ Hide the language icons or wrap long lines instead of scrolling with `markdown:
 
 ## Package install
 
-A `package-install` block turns a single install command into a tabbed snippet for npm, pnpm, yarn, and bun — so readers copy the one that matches their setup. Like diagrams and math, this is an MDX-only feature — in a `.md` file the block renders as a plain code fence.
+A `package-install` block turns a single install command into a tabbed snippet for npm, pnpm, yarn, bun, nub, and aube — so readers copy the one that matches their setup. Like diagrams and math, this is an MDX-only feature — in a `.md` file the block renders as a plain code fence.
 
 ```package-install
 npm i blume