blume 1.4.3 → 1.5.0

package/src/ai/mcp/server.ts

@@ -1,4 +1,5 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { ServerOptions } from "@modelcontextprotocol/sdk/server/index.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import {
   CallToolRequestSchema,
@@ -33,7 +34,7 @@ const MAX_SEARCH_LIMIT = 20;
 /** Excerpt length when a page has no description. */
 const EXCERPT_LENGTH = 200;
 
-const CORS_HEADERS: Record<string, string> = {
+const CORS_HEADERS = {
   "Access-Control-Allow-Headers":
     "Content-Type, Mcp-Session-Id, Mcp-Protocol-Version",
   "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
@@ -65,11 +66,15 @@ const contentTypesField = z.preprocess((value) => {
  * The optional facet filter `search_docs` and `list_pages` share. Only
  * string-valued entries survive; an empty `{}` means "no filter".
  */
+/** Accepts any plain object, so the string-valued entries can be sifted out. */
+const looseFacetObject = z.record(z.string(), z.unknown());
+
 const filtersField = z.preprocess((value) => {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+  const candidate = looseFacetObject.safeParse(value);
+  if (!candidate.success) {
     return;
   }
-  const entries = Object.entries(value).filter(
+  const entries = Object.entries(candidate.data).filter(
     (entry): entry is [string, string] => typeof entry[1] === "string"
   );
   return entries.length > 0 ? Object.fromEntries(entries) : undefined;
@@ -78,7 +83,9 @@ const filtersField = z.preprocess((value) => {
 /** Clamped into range rather than rejected; non-numeric means the default. */
 const limitField = z.preprocess(
   (value) => {
-    const num = typeof value === "number" ? value : Number(value);
+    // `Number` is the identity on numbers, so one conversion covers both the
+    // well-typed call and a numeric string.
+    const num = Number(value);
     return Number.isFinite(num)
       ? Math.min(Math.max(Math.trunc(num), 1), MAX_SEARCH_LIMIT)
       : undefined;
@@ -93,26 +100,55 @@ const limitField = z.preprocess(
 
 /** A required text field; a missing or non-string value coerces to "". */
 const textField = (description: string) =>
-  z.preprocess(
-    (value) => (typeof value === "string" ? value : ""),
-    z.string().describe(description)
-  );
+  z.preprocess((value) => {
+    const parsed = z.string().safeParse(value);
+    return parsed.success ? parsed.data : "";
+  }, z.string().describe(description));
+
+/** An optional trimmed text field; blank or non-string means "absent". */
+const optionalTextField = (description: string) =>
+  z.preprocess((value) => {
+    const parsed = z.string().safeParse(value);
+    const trimmed = parsed.success ? parsed.data.trim() : "";
+    return trimmed || undefined;
+  }, z.string().optional().describe(description));
+
+/** The optional locale filter `search_docs` and `list_pages` share. */
+const localeField = optionalTextField(
+  "Only include pages in this locale (e.g. `fr`). Omit for every language."
+);
+
+/** The optional docs-version scope `search_docs` and `list_pages` share. */
+const versionField = optionalTextField(
+  'Docs version to scope to on a versioned site: `"latest"` (the default — current docs only), `"all"` (every version), or an archived version id (e.g. `"v1.0"`). Ignored when the site is unversioned.'
+);
 
 /** Every tool's input schema — the runtime parse and tools/list source. */
 const TOOL_INPUTS = {
-  get_navigation: z.object({}),
+  get_navigation: z.object({
+    locale: optionalTextField(
+      "Locale whose navigation tree to return (defaults to the default locale)."
+    ),
+    version: optionalTextField(
+      "Archived version id whose tree to return (defaults to the current docs)."
+    ),
+  }),
   get_page: z.object({
     route: textField("The page route, e.g. `/guides/install`."),
   }),
   list_pages: z.object({
     contentTypes: contentTypesField,
     filters: filtersField,
+    locale: localeField,
+    version: versionField,
   }),
   search_docs: z.object({
     contentTypes: contentTypesField,
     filters: filtersField,
     limit: limitField,
+    locale: localeField,
     query: textField("The search query."),
+    version: versionField,
   }),
 };
 
@@ -122,7 +158,7 @@ const TOOL_INPUTS = {
  * runtime strips unknown keys rather than rejecting them, and the advertised
  * schema shouldn't promise stricter validation than the server performs.
  */
-const inputSchemaFor = (schema: z.ZodType): Record<string, unknown> => {
+const inputSchemaFor = (schema: z.ZodType) => {
   const {
     $schema: _dialect,
     additionalProperties: _closed,
@@ -136,12 +172,37 @@ const TOOL_DEFINITIONS = MCP_TOOLS.map((tool) => ({
   annotations: tool.annotations,
   description: tool.description,
   inputSchema: inputSchemaFor(
+    // SAFETY: TOOL_INPUTS declares a schema for every MCP_TOOLS name; the two
+    // lists are maintained together so names and descriptions never drift.
     TOOL_INPUTS[tool.name as keyof typeof TOOL_INPUTS]
   ),
   name: tool.name,
   title: tool.title,
 }));
 
+/** One `search_docs` result entry; `version` only appears on versioned sites. */
+interface SearchHitPayload {
+  contentType: string | undefined;
+  excerpt: string;
+  facets: Record<string, string> | undefined;
+  route: string;
+  title: string;
+  url: string;
+  version?: string;
+}
+
+/** One `list_pages` entry; `version` only appears on versioned sites. */
+interface PageListingPayload {
+  contentType: string;
+  description: string | undefined;
+  facets: Record<string, string> | undefined;
+  lastModified: string | null;
+  route: string;
+  title: string;
+  url: string;
+  version?: string;
+}
+
 /** Whether a page's facet values satisfy every requested filter entry. */
 const matchesFacets = (
   facets: Record<string, string> | undefined,
@@ -149,6 +210,47 @@ const matchesFacets = (
 ): boolean =>
   Object.entries(filters).every(([key, value]) => facets?.[key] === value);
 
+/**
+ * Resolve the `version` scope on a versioned site: `undefined` disables the
+ * filter (`"all"`), `""` is the current docs (the default — agents almost
+ * always want the live documentation), and anything else is an archived id
+ * (an unknown id simply matches nothing). On an unversioned site the input is
+ * ignored entirely. The input arrives pre-trimmed (blank coerced to absent)
+ * from the tool's input schema.
+ */
+const asVersionScope = (
+  value: string | undefined,
+  data: McpData
+): string | undefined => {
+  if (!data.archivedVersions) {
+    return;
+  }
+  if (value === "all") {
+    return;
+  }
+  if (value === undefined || value === "latest" || value === "current") {
+    return "";
+  }
+  return value;
+};
+
+/**
+ * Error message for a `get_navigation` version id that isn't a configured
+ * archived version, or `null` when the id is valid (or the site is
+ * unversioned, where the id is ignored like the other tools' scopes). Unlike
+ * `asVersionScope`'s match-nothing filters, a bad id here would otherwise
+ * silently return the *current* tree posing as the requested snapshot.
+ */
+const unknownVersionError = (
+  versionId: string | undefined,
+  data: McpData
+): string | null =>
+  versionId &&
+  data.archivedVersions &&
+  !data.archivedVersions.includes(versionId)
+    ? `Unknown version "${versionId}". Archived versions: ${data.archivedVersions.join(", ")}.`
+    : null;
+
 /**
  * Normalize a user-supplied route to a `pages` key (`/`, `/a/b`, no suffix).
  * Accepts a full URL too — `search_docs` hits and llms.txt entries carry
@@ -196,10 +298,11 @@ const excerptFor = (doc: OramaDoc): string => {
   return doc.content.length > EXCERPT_LENGTH ? `${head}…` : head;
 };
 
-const text = (value: string, isError = false) => ({
-  content: [{ text: value, type: "text" as const }],
-  ...(isError ? { isError: true } : {}),
-});
+/** A tool call's text result, marked as an error when `isError` is set. */
+const text = (value: string, isError = false) => {
+  const content = [{ text: value, type: "text" as const }];
+  return isError ? { content, isError: true } : { content };
+};
 
 /** Lazily builds the Orama index over a snapshot's documents, once. */
 export type OramaIndexProvider = () => Promise<
@@ -227,12 +330,12 @@ export const buildServer = (
   data: McpData,
   index: OramaIndexProvider
 ): Server => {
+  const serverOptions: ServerOptions = data.instructions
+    ? { capabilities: { tools: {} }, instructions: data.instructions }
+    : { capabilities: { tools: {} } };
   const server = new Server(
     { name: data.name, version: data.version },
-    {
-      capabilities: { tools: {} },
-      ...(data.instructions ? { instructions: data.instructions } : {}),
-    }
+    serverOptions
   );
 
   server.setRequestHandler(ListToolsRequestSchema, () => ({
@@ -252,18 +355,26 @@ export const buildServer = (
         {
           contentTypes: input.contentTypes,
           facets: input.filters,
+          locale: input.locale,
+          version: asVersionScope(input.version, data),
         }
       );
       // `route` is the key `get_page` takes (the tool descriptions promise
       // it); `url` is where the page is served.
-      const results = hits.map((doc: OramaDoc) => ({
-        contentType: doc.contentType,
-        excerpt: excerptFor(doc),
-        facets: doc.facets,
-        route: doc.route,
-        title: doc.title,
-        url: urlFor(doc.route, data),
-      }));
+      const results = hits.map((doc: OramaDoc) => {
+        const hit: SearchHitPayload = {
+          contentType: doc.contentType,
+          excerpt: excerptFor(doc),
+          facets: doc.facets,
+          route: doc.route,
+          title: doc.title,
+          url: urlFor(doc.route, data),
+        };
+        if (data.archivedVersions) {
+          hit.version = doc.version ?? "";
+        }
+        return hit;
+      });
       return text(JSON.stringify(results, null, 2));
     }
 
@@ -281,23 +392,33 @@ export const buildServer = (
     }
 
     if (name === "list_pages") {
-      const { contentTypes, filters } = TOOL_INPUTS.list_pages.parse(args);
+      const input = TOOL_INPUTS.list_pages.parse(args);
+      const { contentTypes, filters, locale } = input;
+      const versionScope = asVersionScope(input.version, data);
       const routes = data.routes.filter(
         (route) =>
           (!contentTypes || contentTypes.includes(route.contentType)) &&
-          (!filters || matchesFacets(route.facets, filters))
+          (!filters || matchesFacets(route.facets, filters)) &&
+          (!locale || route.locale === locale) &&
+          (versionScope === undefined || route.version === versionScope)
       );
       return text(
         JSON.stringify(
-          routes.map((route) => ({
-            contentType: route.contentType,
-            description: route.description,
-            facets: route.facets,
-            lastModified: route.lastModified,
-            route: route.route,
-            title: route.title,
-            url: urlFor(route.route, data),
-          })),
+          routes.map((route) => {
+            const listing: PageListingPayload = {
+              contentType: route.contentType,
+              description: route.description,
+              facets: route.facets,
+              lastModified: route.lastModified,
+              route: route.route,
+              title: route.title,
+              url: urlFor(route.route, data),
+            };
+            if (data.archivedVersions) {
+              listing.version = route.version;
+            }
+            return listing;
+          }),
           null,
           2
         )
@@ -305,7 +426,31 @@ export const buildServer = (
     }
 
     if (name === "get_navigation") {
-      return text(JSON.stringify(data.navigation, null, 2));
+      // A version id selects the snapshot's tree; a locale selects its
+      // language (falling back through the default locale to any tree the
+      // snapshot has). Without a version, a locale selects the current docs'
+      // localized tree. An unknown id on a versioned site is an error — the
+      // current tree would silently masquerade as the requested snapshot.
+      const { locale, version: versionId } =
+        TOOL_INPUTS.get_navigation.parse(args);
+      const unknownVersion = unknownVersionError(versionId, data);
+      if (unknownVersion) {
+        return text(unknownVersion, true);
+      }
+      let { navigation } = data;
+      const byLocale = versionId
+        ? data.navigationByVersion?.[versionId]
+        : undefined;
+      if (byLocale) {
+        navigation =
+          (locale ? byLocale[locale] : undefined) ??
+          byLocale[data.defaultLocale ?? ""] ??
+          Object.values(byLocale)[0] ??
+          navigation;
+      } else if (locale && data.navigationByLocale?.[locale]) {
+        navigation = data.navigationByLocale[locale];
+      }
+      return text(JSON.stringify(navigation, null, 2));
     }
 
     return text(`Unknown tool: ${name}`, true);

package/src/ai/mcp/tools.ts

@@ -19,7 +19,7 @@ export const MCP_TOOLS: McpToolMeta[] = [
   {
     annotations: READ_ONLY,
     description:
-      'Full-text search across the documentation. Returns matching pages with their title, route, content type, and a short excerpt; pass `contentTypes` to search only pages of certain types (e.g. `rfc`, `changelog`), and `filters` to require facet values the site declares per type (e.g. `{"status": "enforced"}`). Use this first to discover relevant pages, then `get_page` to read one in full.',
+      'Full-text search across the documentation. Returns matching pages with their title, route, content type, and a short excerpt; pass `contentTypes` to search only pages of certain types (e.g. `rfc`, `changelog`), `filters` to require facet values the site declares per type (e.g. `{"status": "enforced"}`), and `locale` to search one language. On a versioned site results default to the current docs — pass `version` to search an archived version (e.g. `"v1.0"`) or `"all"` for every version. Use this first to discover relevant pages, then `get_page` to read one in full.',
     name: "search_docs",
     title: "Search documentation",
   },
@@ -33,14 +33,14 @@ export const MCP_TOOLS: McpToolMeta[] = [
   {
     annotations: READ_ONLY,
     description:
-      "List every documentation page with its route, title, description, content type, and any declared facet values; pass `contentTypes` and/or `filters` to narrow the list. Useful for enumerating the docs, discovering the types and facets in use, or finding a page when search is too narrow.",
+      'List every documentation page with its route, title, description, content type, and any declared facet values; pass `contentTypes`, `filters`, and/or `locale` to narrow the list. On a versioned site the list defaults to the current docs — pass `version` for an archived version or `"all"`. Useful for enumerating the docs, discovering the types and facets in use, or finding a page when search is too narrow.',
     name: "list_pages",
     title: "List pages",
   },
   {
     annotations: READ_ONLY,
     description:
-      "Return the documentation navigation tree (header tabs and the sidebar hierarchy), reflecting how the docs are organized for readers.",
+      "Return the documentation navigation tree (header tabs and the sidebar hierarchy), reflecting how the docs are organized for readers. Pass `locale` for a language's tree and, on a versioned site, `version` for an archived snapshot's tree.",
     name: "get_navigation",
     title: "Get navigation",
   },

package/src/ai/skills.ts

@@ -89,23 +89,46 @@ const collectEntries = async (
   return entries;
 };
 
+/** The two SKILL.md frontmatter fields the discovery index publishes. */
+interface SkillMeta {
+  description: string;
+  name: string;
+}
+
+interface SkillMetaResult {
+  meta: SkillMeta | null;
+  warning?: string;
+}
+
+/**
+ * What js-yaml can put in a SKILL.md frontmatter field. Rich scalars (Dates)
+ * ride along as the object arm; only strings are accepted below anyway.
+ */
+type FrontmatterField =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | FrontmatterField[]
+  | { [key: string]: FrontmatterField };
+
+const isString = (value: FrontmatterField): value is string =>
+  typeof value === "string";
+
 /** Frontmatter of a SKILL.md, or null with a warning when unusable. */
-const skillMeta = (
-  raw: string,
-  dirName: string
-): { meta: { description: string; name: string } | null; warning?: string } => {
-  let data: Record<string, unknown>;
+const skillMeta = (raw: string, dirName: string): SkillMetaResult => {
+  let data: { description?: FrontmatterField; name?: FrontmatterField };
   try {
-    ({ data } = matter(raw) as unknown as { data: Record<string, unknown> });
+    ({ data } = matter(raw));
   } catch {
     return {
       meta: null,
       warning: `Skill "${dirName}" has unparsable SKILL.md frontmatter; skipped.`,
     };
   }
-  const name = typeof data.name === "string" ? data.name : "";
-  const description =
-    typeof data.description === "string" ? data.description : "";
+  const name = isString(data.name) ? data.name : "";
+  const description = isString(data.description) ? data.description : "";
   if (!(name && description)) {
     return {
       meta: null,

package/src/ai/visibility.ts

@@ -19,10 +19,10 @@ const visibilityBlock = (audience: VisibilityAudience): RegExp =>
     "gu"
   );
 
-const BLOCKS: Record<VisibilityAudience, RegExp> = {
+const BLOCKS = {
   agents: visibilityBlock("agents"),
   web: visibilityBlock("web"),
-};
+} satisfies Record<VisibilityAudience, RegExp>;
 
 /**
  * Resolve `<Visibility>` blocks for one audience: blocks addressed to the

package/src/astro/component-slots.ts

@@ -77,6 +77,8 @@ const importClause = (variable: string, name: string, path: string): string =>
 
 /** A wrapper `.astro` that statically imports a component and hydrates it. */
 const wrapperContent = (override: NormalizedOverride): string => {
+  // SAFETY: the only caller guards `if (!source)` and bails before invoking
+  // this, so the override always carries a resolved source here.
   const { name, path } = override.source as NonNullable<
     NormalizedOverride["source"]
   >;

package/src/astro/examples.ts

@@ -33,7 +33,11 @@ export interface ExampleDiscovery {
 }
 
 /** Example extensions mapped to the framework that renders them. */
-const FRAMEWORK_BY_EXT: Record<string, ExampleFramework> = {
+interface FrameworkByExtension {
+  [extension: string]: ExampleFramework;
+}
+
+const FRAMEWORK_BY_EXT: FrameworkByExtension = {
   astro: "astro",
   jsx: "react",
   svelte: "svelte",
@@ -62,7 +66,7 @@ const GLOB_MAGIC = /[!*?[\]{}]/u;
  * discovered files can be keyed relative to that prefix (e.g.
  * `registry/x/**\/examples/*` → `{ base: "registry/x", rest: "**\/examples/*" }`).
  */
-const splitGlobBase = (pattern: string): { base: string; rest: string } => {
+const splitGlobBase = (pattern: string) => {
   const segments = pattern.split("/");
   // Only called when the pattern contains glob magic (see the caller), and `/`
   // is never magic, so the magic char always lands in a segment — `findIndex`

package/src/astro/generate.ts

@@ -489,12 +489,14 @@ export const ensureDepsLink = async (
  * (`<build.server>/.prerender/`) output — so it fires for exactly that build.
  * Inert in dev, where there is no build and `writeBundle` never runs.
  */
-export const prerenderDepsPlugin = (
-  pkgDir: string = packageRoot()
-): {
+export interface PrerenderDepsPlugin {
   name: string;
   writeBundle: (options: { dir?: string }) => Promise<void>;
-} => ({
+}
+
+export const prerenderDepsPlugin = (
+  pkgDir: string = packageRoot()
+): PrerenderDepsPlugin => ({
   name: "blume:prerender-deps",
   writeBundle: async (options) => {
     if (!options.dir || basename(options.dir) !== ".prerender") {
@@ -528,14 +530,16 @@ interface ServerAppResolveContext {
  * Stripping the spurious `.js` and delegating back to Astro's resolver lets the
  * reload complete cleanly, so the renamed route resolves without a restart.
  */
-export const serverAppResolvePlugin = (): {
+export interface ServerAppResolvePlugin {
   enforce: "pre";
   name: string;
   resolveId: (
     this: ServerAppResolveContext,
     id: string
   ) => Promise<string | null>;
-} => ({
+}
+
+export const serverAppResolvePlugin = (): ServerAppResolvePlugin => ({
   enforce: "pre",
   name: "blume:server-app-resolve",
   async resolveId(id) {
@@ -548,20 +552,20 @@ export const serverAppResolvePlugin = (): {
 });
 
 /** Astro integration package each non-React island framework needs installed. */
-const ISLAND_FRAMEWORK_DEPS: Record<string, string> = {
-  svelte: "@astrojs/svelte",
-  vue: "@astrojs/vue",
-};
+const ISLAND_FRAMEWORK_DEPS = new Map([
+  ["svelte", "@astrojs/svelte"],
+  ["vue", "@astrojs/vue"],
+]);
 
 /**
  * Adapter package the project must install itself for each deployment
  * platform whose adapter Blume doesn't ship. Node and Vercel ship with Blume,
  * so they never need this.
  */
-const DEPLOYMENT_ADAPTER_DEPS: Record<string, string> = {
-  cloudflare: "@astrojs/cloudflare",
-  netlify: "@astrojs/netlify",
-};
+const DEPLOYMENT_ADAPTER_DEPS = new Map([
+  ["cloudflare", "@astrojs/cloudflare"],
+  ["netlify", "@astrojs/netlify"],
+]);
 
 /**
  * Warn when a Vue/Svelte island is present but its Astro integration isn't
@@ -574,7 +578,7 @@ const islandFrameworkWarnings = (
 ): string[] => {
   const warnings: string[] = [];
   for (const framework of frameworks) {
-    const dep = ISLAND_FRAMEWORK_DEPS[framework];
+    const dep = ISLAND_FRAMEWORK_DEPS.get(framework);
     if (dep && !canResolveFrom(root, dep)) {
       warnings.push(
         `Islands use ${framework}, which needs "${dep}". Install it (e.g. \`npm install ${dep} ${framework}\`).`
@@ -599,7 +603,7 @@ const deploymentAdapterWarnings = (
 ): string[] => {
   const dep =
     deployment.output === "server" && deployment.adapter
-      ? DEPLOYMENT_ADAPTER_DEPS[deployment.adapter]
+      ? DEPLOYMENT_ADAPTER_DEPS.get(deployment.adapter)
       : undefined;
   if (
     dep &&
@@ -906,6 +910,10 @@ const readLogoSvg = (
   return file ? readFileSync(file, "utf-8") : undefined;
 };
 
+/** Narrows a config union's string shorthand from its object form. */
+const isStringShorthand = <T>(value: T | string): value is string =>
+  typeof value === "string";
+
 /**
  * Resolve the configured logo. A single SVG is read and inlined so a
  * `currentColor` logo follows the theme; other images keep their URL for an
@@ -916,12 +924,12 @@ const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
   if (!logo) {
     return null;
   }
-  const config = typeof logo === "string" ? { image: logo } : logo;
+  const config = isStringShorthand(logo) ? { image: logo } : logo;
   // `text` is passed through verbatim: `undefined` lets the brand fall back to
   // the site title, `""` renders the mark alone (a logo with the wordmark baked
   // in).
   const { href, image: source, text } = config;
-  const image = typeof source === "string" ? { light: source } : source;
+  const image = isStringShorthand(source) ? { light: source } : source;
   const light = image?.light ?? image?.dark;
   const dark = image?.dark ?? image?.light;
   const alt = image?.alt ?? "";
@@ -957,18 +965,18 @@ const FAVICON_CANDIDATES = [
 ];
 
 /** `<link type>` MIME for the favicon extensions we recognize. */
-const FAVICON_TYPES: Record<string, string> = {
-  ico: "image/x-icon",
-  jpeg: "image/jpeg",
-  jpg: "image/jpeg",
-  png: "image/png",
-  svg: "image/svg+xml",
-};
+const FAVICON_TYPES = new Map([
+  ["ico", "image/x-icon"],
+  ["jpeg", "image/jpeg"],
+  ["jpg", "image/jpeg"],
+  ["png", "image/png"],
+  ["svg", "image/svg+xml"],
+]);
 
 /** Infer the `<link type>` MIME from a filename, when we recognize the extension. */
 const faviconType = (name: string): string | undefined => {
   const ext = name.split(".").pop()?.toLowerCase();
-  return ext ? FAVICON_TYPES[ext] : undefined;
+  return ext ? FAVICON_TYPES.get(ext) : undefined;
 };
 
 /** Read a file and encode it as a `data:` URI of the given MIME type. */
@@ -1041,7 +1049,7 @@ const resolveBanner = (config: ResolvedConfig): BlumeBanner | null => {
   if (!banner) {
     return null;
   }
-  if (typeof banner === "string") {
+  if (isStringShorthand(banner)) {
     return { content: banner, dismissible: false, key: banner };
   }
   return {
@@ -1234,6 +1242,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       theme: config.theme,
       title: config.title,
       toc: config.toc,
+      versions: config.versions ?? null,
       webmcp: {
         enabled: config.ai.webmcp,
         llms: config.ai.llmsTxt.enabled,
@@ -1250,6 +1259,19 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     navigation: withRepoUrl(graph.navigation),
     // Per-locale navigation; the catch-all selects the active locale's tree.
     navigationByLocale,
+    // Per-archived-version navigation; the catch-all selects by the route's
+    // version, then locale.
+    navigationByVersion: Object.fromEntries(
+      Object.entries(graph.navigationByVersion).map(([id, byLocale]) => [
+        id,
+        Object.fromEntries(
+          Object.entries(byLocale).map(([code, nav]) => [
+            code,
+            withRepoUrl(nav),
+          ])
+        ),
+      ])
+    ),
     routes: manifest.routes.map((route) => ({
       alternates: route.alternates,
       collection: route.collection,
@@ -1264,6 +1286,8 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       locale: route.locale,
       path: route.path,
       title: route.title,
+      version: route.version,
+      versionAlternates: route.versionAlternates,
     })),
     // Default-locale chrome strings (English baseline when not under i18n).
     ui: defaultUi,
@@ -1861,8 +1885,9 @@ export const generateRuntime = async (
     ]);
   }
 
-  // API/AsyncAPI reference pages (Scalar). One self-contained page per source,
-  // mounted on its configured route and regenerated each run.
+  // Scalar-rendered API/AsyncAPI reference pages (`renderer: "scalar"`). One
+  // self-contained page per source, mounted on its configured route and
+  // regenerated each run.
   const warnings: string[] = [
     ...(depsLinkWarning ? [depsLinkWarning] : []),
     ...reactCompilerWarnings(config, needsReact, reactCompilerPath),