blume 2.0.0 → 2.0.2

package/skills/blume-migrate/references/mintlify.md

@@ -92,7 +92,7 @@ The codemod touches **only frontmatter**. Icons in MDX **body** (`<Icon icon="
 | `life-ring` | `life-buoy` |  | `shield-halved` | `shield` |
 | `rocket`/`book`/`book-open`/`code`/`terminal`/`key`/`lock`/`user`/`users`/`database`/`server`/`cloud`/`bell`/`calendar`/`star`/`heart`/`tag`/`folder`/`globe`/`link`/`download`/`upload`/`check`/`copy`/`play`/`filter` | _(same name — verify)_ |
 
-**Rules:** verify each Lucide name exists at [lucide.dev/icons](https://lucide.dev/icons) before writing it. **Brand icons** (`fa6-brands:*` — github, discord, x, slack, linkedin…) mostly have **no** Lucide equivalent: for GitHub use the `github` config (renders the header repo link); for other socials, drop the icon and report it (or add via a Footer override after `blume eject`). Where no Lucide counterpart exists, **drop the icon and report it** — an unknown icon name is a build error.
+**Rules:** verify each Lucide name exists at [lucide.dev/icons](https://lucide.dev/icons) before writing it. **Brand icons** (`fa6-brands:*` — github, discord, x, slack, linkedin…) mostly have **no** Lucide equivalent: for GitHub use the `github` config (renders the header repo link); for other socials, drop the icon and report it (or add via a Footer override after `blume eject`). Where no Lucide counterpart exists, **drop the icon and report it**. The build won't catch a wrong name for you: an unknown icon renders nothing, and it's only a warning (`BLUME_UNKNOWN_ICON`) for navigation icons — an icon prop on a component like `<Card>` fails silently — so check every name.
 
 ## Navigation: `docs.json` `navigation` → filesystem + tabs
 
@@ -143,7 +143,7 @@ Mintlify page frontmatter → Blume's strict schema. **`scripts/mintlify-codemod
 | `canonical` | `seo.canonical` | renames |
 | `og:image` | `seo.image` | renames |
 | `hidden: true` | valid top-level in Blume — **kept as-is**; add `noindex: true` yourself if the page must also leave the search index | left (do by hand) |
-| `openapi`/`asyncapi`/`api` | usually an endpoint stub → **delete the page** (Blume generates operation pages); else `type: api` | **flags** for review — never auto-deletes a page |
+| `openapi`/`asyncapi`/`api` | usually an endpoint stub → **delete the page** (Blume generates operation pages); else drop the key and keep it as a normal page (there's no built-in `api` page type) | **flags** for review — never auto-deletes a page |
 | `mode`, `public`, `rss`, `groups`, `keywords`, `hideApiMarker`, `hideFooterPagination`, `iconType` | **drop** (report) | drops |
 
 The codemod leaves the source key in place and reports a conflict rather than clobbering data when a rename target already exists (e.g. a page already has `sidebar.label`) or the value is too structured to move safely — resolve those by hand. Remove any duplicate H1 in the body — `title` renders the H1. (The codemod only edits frontmatter; it never touches the body.)
@@ -153,7 +153,7 @@ The codemod leaves the source key in place and reports a conflict rather than cl
 Top-level `openapi`, `api.openapi`, or a per-group/per-tab `openapi` → `reference: [openapi({ sources: [{ spec, label?, route? }] })]`, with `openapi` imported from `blume/reference` (`spec` alone is the single-source shorthand; several per-tab specs become several sources, or several `openapi()` entries when they need different routes; a spec the source embedded with Scalar becomes a `scalar({ spec })` entry). A Mintlify `{ source, directory }` object: `directory` → the source's `route`. An `asyncapi` field maps the same way to `asyncapi({ … })` in the list. **Delete every per-endpoint stub page** (frontmatter `openapi: "GET /path"` or a `"GET /path"` nav entry) — Blume's native renderer generates one real page per operation. **Add a `navigation.tabs` entry pointing at the reference `route` yourself** (Mintlify's API tab maps to it); the reference does not create a header tab automatically.
 
 - **Vendor the spec.** Mintlify usually points at a spec **URL**. Copying that straight into `spec:` makes every build fetch it at build time — a single point of failure in CI/offline/behind a proxy, and a failed fetch silently drops the reference (leaving the tab pointing at a route that 404s). Prefer downloading it into the repo (`curl … -o openapi/<name>.json`) and pointing `spec` at that local path. If you keep the URL, report the dependency and consider a `prebuild` refresh-with-fallback.
-- **Fix endpoint links.** Blume operation routes are `<route>/<slugified-tag>/<slugified-operationId>` (tag `Models` + id `listModels` → `/api-reference/models/listmodels`) — this differs from Mintlify's endpoint URLs, so **rewrite every inbound link to an operation**. `blume validate` resolves operation pages like any other route and flags the ones you miss.
+- **Fix endpoint links.** Blume operation routes are `<route>/<slugified-tag>/<slugified-operationId>` (tag `Models` + id `listModels` → `/api-reference/models/list-models`: a camelCase id is split into kebab-case, not just lowercased — see SKILL.md "OpenAPI") — this differs from Mintlify's endpoint URLs, so **rewrite every inbound link to an operation**. `blume validate` resolves operation pages like any other route and flags the ones you miss.
 - **Keep the "Introduction" page.** Mintlify commonly has a written intro/auth page in an "Introduction" group beside the "Endpoints" (openapi) group in the same tab. Keep it: a normal content page placed under the `openapi()` adapter's `route` (e.g. `<root>/api-reference/introduction.mdx`) merges into the reference tab's sidebar alongside the generated operations. Delete only the per-endpoint stubs, not the conceptual pages.
 
 ## Assets

package/skills/blume-migrate/references/monorepo.md

@@ -112,7 +112,7 @@ This is a **copyable template**, not prose. Three pieces:
     "preview": "blume preview"
   },
   "dependencies": {
-    "blume": "^1"
+    "blume": "^2"
   }
 }
 ```

package/skills/blume-migrate/references/nextra.md

@@ -56,7 +56,7 @@ Most Nextra pages have **no frontmatter**; the title falls back `_meta` title
 
 ## Code fences
 
-Nextra's fence meta differs from Blume's — rewrite it: `filename="app.js"` → a space-separated title (` ```js app.js `); `showLineNumbers` → `lineNumbers`; line highlighting `{1,4-5}` carries over unchanged; **drop** word-highlight `/word/`, `copy`/`copy=false`, and inline-code `{:lang}` suffixes. ` ```sh npm2yarn ` fences → ` ```package-install `.
+Nextra's fence meta differs from Blume's — rewrite it: `filename="app.js"` → a space-separated title (` ```js app.js `); `showLineNumbers` → `lineNumbers`; line highlighting `{1,4-5}` carries over unchanged; **drop** word-highlight `/word/` and `copy`/`copy=false`. **Keep** inline-code `{:lang}` suffixes (`` `useState(){:js}` ``) — Blume highlights them natively. ` ```sh npm2yarn ` fences → ` ```package-install `.
 
 ## Math
 

package/skills/blume-migrate/references/starlight.md

@@ -12,7 +12,7 @@ Keep content where it is — set `content.root: "src/content/docs"`.
 
 ## Config: `starlight({…})` → `blume.config.ts`
 
-**Harvest the surrounding `astro.config.*` too, not just the `starlight()` call:** top-level Astro `redirects` → Blume `redirects`; `site` → leave unset (Blume auto-detects); other integrations → report.
+**Harvest the surrounding `astro.config.*` too, not just the `starlight()` call:** top-level Astro `redirects` → Blume `redirects`; `site` → `deployment.site`, unless the target host is Vercel, Netlify, or Cloudflare Pages, which Blume auto-detects (see SKILL.md); other integrations → report.
 
 | Starlight option | Blume |
 | --- | --- |
@@ -70,7 +70,7 @@ Starlight's primary callout syntax is the `:::note`/`:::tip`/`:::caution`/`:::da
 
 ## Components
 
-- **Renames:** `<CardGrid>` → `<CardGroup>`; `<LinkCard>` → `<Card>` (its `description` prop drops — fold into the body); `<TabItem label="…">` → `<Tab title="…">`. `<Tabs>` and `<Card>` stay; a `<Tabs syncKey="…">` → strip the prop (Blume tabs sync by default).
+- **Renames:** `<CardGrid>` → `<CardGroup>`; `<LinkCard>` → `<Card>` (its `description` prop drops — fold into the body); `<TabItem label="…">` → `<Tab title="…">`. `<Tabs>` and `<Card>` stay; **keep** a `<Tabs syncKey="…">` prop as is — Blume's `Tabs` takes `syncKey` with the same scoping (only groups sharing the key switch together). One difference: Blume groups without a key also sync, page-wide, by tab title, where Starlight leaves them independent — add `sync={false}` to a keyless group whose same-titled tabs must stay unlinked.
 - **`<Badge>` needs conversion, not pass-through:** Starlight puts content in a `text` prop and uses variants `note`/`tip`/`caution`/`danger`/`success`/`default` with sizes `small`/`medium`/`large`. Blume's `<Badge>` renders **children** with variants `default`/`accent`/`success`/`warning`/`danger` and sizes `xs`/`sm`/`md`/`lg`. Move `text` into the children; remap variant (`note`→`default`, `tip`→`accent`, `caution`→`warning`, `danger`→`danger`, `success`→`success`) and size (`small`→`sm`, `medium`→`md`, `large`→`lg`).
 - **Convert yourself:** `<Steps>` → Blume `<Steps>`/`<Step>`; `<FileTree>` → Blume `<FileTree>`; `<Code code={…}>` → a fenced code block; `<LinkButton>` → a Markdown link or `<Card>`.
 - Strip `import … from "@astrojs/starlight/*"` and `astro:assets` lines.
@@ -88,8 +88,8 @@ Starlight content is full of Expressive Code fence meta; Blume understands some
 ## Plugins — map, don't drop
 
 - `starlight-openapi` → an `openapi({ sources })` entry in Blume's `reference` list, imported from `blume/reference` (delete any generated pages; add the `navigation.tabs` entry).
-- `starlight-blog` → `type: blog` pages.
-- `starlight-versions` → `navigation.selectors` with `kind: "version"`.
+- `starlight-blog` → `type: blog` pages (RSS at `/blog/rss.xml`). Blume generates **no** blog index, tag, or author pages: write a `blog/index.mdx` whose `CardGroup` links each post (see `docs/advanced/blog.mdx` in the installed package), and report the tag and author pages as dropped.
+- `starlight-versions` → Blume's native versioning, not a `navigation.selectors` dropdown: each archived version's content goes in a top-level folder under `content.root` named for its id, listed in `versions.archived` (newest first), and Blume adds the switcher, the old-version notice, and version-scoped search. Ids must start with a letter (`1.0/` → `v1.0/`, with `redirects` from the old URLs), and a version-shaped folder left out of `versions.archived` only warns (`BLUME_VERSIONS_UNCONFIGURED_VERSION`) and publishes as current content. Full reference: `docs/content/versioning.mdx` in the installed package.
 - `starlight-image-zoom` → delete (Blume zooms content images by default).
 - `starlight-links-validator` → delete (`blume validate` covers it).
 - Anything else → report.
@@ -113,4 +113,4 @@ Remove `@astrojs/starlight` (and plugin deps) from deps, delete the Starlight bi
 
 ## Dropped — report these
 
-Non-GitHub socials, badge variants, sidebar/item `attrs` + `translations`, `customCss` beyond `theme.css`, `head` entries, `routeMiddleware`, splash/hero pages (rebuild as custom pages), aside custom icons, EC frames/collapse/text markers, prev/next toggles, unmapped plugins, any `<Icon>` name with no Lucide equivalent.
+Non-GitHub socials, badge variants, sidebar/item `attrs` + `translations`, `customCss` beyond `theme.css`, `head` entries, `routeMiddleware`, splash/hero pages (rebuild as custom pages), starlight-blog's tag and author pages, aside custom icons, EC frames/collapse/text markers, prev/next toggles, unmapped plugins, any `<Icon>` name with no Lucide equivalent.

package/skills/blume-migrate/scripts/mintlify-codemod.mjs

@@ -177,8 +177,8 @@ const RENAME = {
 };
 
 // Keys we deliberately do NOT auto-transform — they usually mean the page is an
-// OpenAPI endpoint stub that should be deleted (Blume generates operation pages)
-// or converted to `type: api`. Flag for the human; never guess.
+// OpenAPI endpoint stub that should be deleted (Blume generates operation pages),
+// or else a normal page that just loses the key. Flag for the human; never guess.
 const FLAG = new Set(["api", "asyncapi", "openapi"]);
 
 // Which change kinds actually edit the file. Report-only kinds (flags,

package/skills/blume-update-docs/references/audit-checklist.md

@@ -32,7 +32,7 @@ Skip the edit when the only available change is subjective polish, wording prefe
 - Preserve existing page order and `defineMeta` style; update `pages` arrays when adding, renaming, or removing pages.
 - Use the Blume components already present in the docs (callout directives, steps, cards) instead of inventing new markup patterns.
 - Match nearby code fences: filenames, language tags, and line numbers where the surrounding docs use them.
-- Keep internal links root-relative (`/docs/...`).
+- Keep internal links root-relative (`/guides/setup`), in the form nearby pages already use.
 - Do not edit generated `.blume/` or `dist/` output.
 
 ## PR notes

package/src/ai/agent-readability.ts

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

package/src/ai/agent-surface.ts

@@ -0,0 +1,56 @@
+import { routeIsTaken } from "../astro/pages.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+
+/**
+ * What a build actually serves of the agent surfaces whose config flag alone
+ * doesn't guarantee them.
+ */
+export interface EmittedAgentSurface {
+  /** The MCP server was generated (see {@link servesMcp}). */
+  mcp: boolean;
+  /**
+   * A skills discovery index is served: generated from `agents.skills` (at
+   * least one valid skill), or shipped by the user in `public/`.
+   */
+  skills: boolean;
+}
+
+/**
+ * Whether the build generates the MCP server: it is enabled and no content
+ * or custom page owns its route. When one does, the generator skips the
+ * server with a warning rather than collide with the page (`planMcp`).
+ */
+export const servesMcp = (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): boolean =>
+  project.config.agents.mcp.enabled &&
+  !routeIsTaken(
+    userPages,
+    project.graph.pages,
+    project.config.agents.mcp.route
+  );
+
+/**
+ * The config the discovery documents are built from: `agents.mcp` and
+ * `agents.skills` switched off when the build didn't emit them, so llms.txt,
+ * agent-readability.json, the catalogs, and the header rules only point at
+ * what is there. A config flag says what was asked for; the MCP server is
+ * skipped when a page owns its route, and skills publish nothing when their
+ * directory is missing or holds no valid skill.
+ */
+export const advertisedConfig = (
+  config: ResolvedConfig,
+  emitted: EmittedAgentSurface
+): ResolvedConfig => ({
+  ...config,
+  agents: {
+    ...config.agents,
+    mcp: {
+      ...config.agents.mcp,
+      enabled: config.agents.mcp.enabled && emitted.mcp,
+    },
+    skills: emitted.skills ? config.agents.skills : undefined,
+  },
+});

package/src/ai/api/paths.ts

@@ -1,7 +1,7 @@
 /**
  * Where the JSON docs API and its OpenAPI description are served. Base-less
  * (like every route Blume emits); callers layer `deployment.base` on top.
- * Under `/api/` alongside the Ask AI endpoint (`/api/ask`) so the namespace a
+ * Under `/api/` alongside the assistant endpoint (`/api/ask`) so the namespace a
  * Blume site reserves for live endpoints stays one prefix, and under its own
  * `docs` segment so a search provider's proxy at `/api/search` never collides.
  */

package/src/ai/api/spec.ts

@@ -113,6 +113,7 @@ export interface ApiSpecDocument {
 }
 
 const JSON_TYPE = "application/json";
+const EVENT_STREAM_TYPE = "text/event-stream";
 const MARKDOWN_TYPE = "text/markdown";
 const TEXT_TYPE = "text/plain";
 
@@ -623,14 +624,26 @@ export const buildApiSpec = (input: ApiSpecInput): ApiSpecDocument => {
       {
         post: {
           description:
-            "The Model Context Protocol server (Streamable HTTP, stateless, JSON responses). Tools: `search_docs`, `get_page`, `list_pages`, `get_navigation` — the same operations this API exposes — plus every page as a `text/markdown` resource. Discovery document at `/.well-known/mcp.json`.",
+            "The Model Context Protocol server (Streamable HTTP, stateless, JSON responses). Send `Accept: application/json, text/event-stream`: the Streamable HTTP transport requires a client to accept both and answers `406` otherwise, though this server always replies with JSON. Tools: `search_docs`, `get_page`, `list_pages`, `get_navigation` — the same operations this API exposes — plus every page as a `text/markdown` resource. Discovery document at `/.well-known/mcp.json`.",
           operationId: "mcp",
           requestBody: {
             content: { [JSON_TYPE]: { schema: ref("JsonRpcRequest") } },
             required: true,
           },
           responses: {
-            "200": jsonResponse("The JSON-RPC response.", "JsonRpcResponse"),
+            // Both media types, so a generated client sends the Accept header
+            // the transport requires; OpenAPI ignores an `Accept` parameter.
+            "200": {
+              content: {
+                [JSON_TYPE]: { schema: ref("JsonRpcResponse") },
+                [EVENT_STREAM_TYPE]: { schema: { type: "string" } },
+              },
+              description: "The JSON-RPC response.",
+            },
+            "406": jsonResponse(
+              "The request's `Accept` header doesn't list both `application/json` and `text/event-stream`.",
+              "JsonRpcResponse"
+            ),
           },
           summary: "Call the MCP server",
           tags: ["MCP"],

package/src/ai/api-catalog.ts

@@ -17,7 +17,13 @@ import { API_BASE, OPENAPI_PATH } from "./api/paths.ts";
  */
 
 export const API_CATALOG_PATH = "/.well-known/api-catalog";
-export const API_CATALOG_TYPE = "application/linkset+json";
+/** The profile URI RFC 9727 registers for an API catalog linkset. */
+export const API_CATALOG_PROFILE = "https://www.rfc-editor.org/info/rfc9727";
+/**
+ * The catalog's media type: a linkset carrying the RFC 9727 profile
+ * parameter, which the RFC says an API catalog SHOULD be served with.
+ */
+export const API_CATALOG_TYPE = `application/linkset+json; profile="${API_CATALOG_PROFILE}"`;
 
 /** An RFC 9264 linkset entry, restricted to the relations Blume emits. */
 interface LinksetEntry {

package/src/ai/ask-context.ts

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

package/src/ai/ask-data.ts

@@ -1,14 +1,17 @@
 import type { BlumeProject } from "../core/project-graph.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
+import type { OramaDoc } from "../search/orama-index.ts";
 import type { AskData } from "./ask-context.ts";
 
 /**
- * Build the grounding snapshot the Ask AI endpoint serves. Like the MCP server,
- * Ask AI is independent of on-page search, so documents are indexed even when the
- * search provider is `none` (`includeWhenDisabled`). `locale` is kept (unlike the
- * MCP snapshot) so retrieval can be filtered to the current page's language, and
- * content is kept as Markdown so grounding sees fenced code examples — the model
- * answers "what does the config look like?" from the docs instead of declining.
+ * Build the grounding snapshot the assistant endpoint serves. Like the MCP server,
+ * the assistant is independent of on-page search, so documents are indexed even when the
+ * search provider is `none` (`includeWhenDisabled`). `locale` is kept so
+ * retrieval can be filtered to the current page's language, and on a
+ * versioned site `version` too, so archived snapshots don't crowd the docs
+ * being read out of the answer. Content is kept as Markdown so grounding sees
+ * fenced code examples — the model answers "what does the config look like?"
+ * from the docs instead of declining.
  * The reader is an AI agent, so `<Visibility>` resolves for the agents audience
  * (web-only content removed, agents-only unwrapped) and components downlevel to
  * Markdown, both matching llms-full.txt.
@@ -19,15 +22,26 @@ export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
     content: "markdown",
     includeWhenDisabled: true,
   });
-  return {
+  const versioned = Boolean(project.config.versions);
+  const data: AskData = {
     defaultLocale: project.config.i18n?.defaultLocale,
-    documents: documents.map((doc) => ({
-      content: doc.content,
-      description: doc.description,
-      locale: doc.locale,
-      route: doc.route,
-      title: doc.title,
-    })),
+    documents: documents.map((doc) => {
+      const document: OramaDoc = {
+        content: doc.content,
+        description: doc.description,
+        locale: doc.locale,
+        route: doc.route,
+        title: doc.title,
+      };
+      if (versioned) {
+        document.version = doc.version;
+      }
+      return document;
+    }),
     site: project.config.deployment.options.site ?? null,
   };
+  if (versioned) {
+    data.versioned = true;
+  }
+  return data;
 };