blume 1.4.2 → 1.5.0

package/src/ai/agent-readability.ts

@@ -1,6 +1,7 @@
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
+import { absoluteUrl } from "../core/site-url.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
 import { hasApiCatalog } from "./api-catalog.ts";
 
@@ -42,16 +43,45 @@ const askApiUrl = (
     return abs("/api/ask");
   }
   return site && endpoint.startsWith("/")
-    ? `${site.replace(/\/+$/u, "")}${endpoint}`
+    ? absoluteUrl(site, endpoint)
     : endpoint;
 };
 
+/** The `.well-known` discovery URLs a site can publish. */
+interface WellKnownArtifacts {
+  httpMessageSignaturesDirectory?: string;
+  apiCatalog?: string;
+  agentSkills?: string;
+}
+
+/** The agent-facing artifact index the manifest publishes. */
+interface AgentArtifacts extends WellKnownArtifacts {
+  markdown: { contentNegotiation?: string; pattern: string };
+  llmsFullTxt?: string;
+  llmsTxt?: string;
+  mcp?: { discovery: string; url: string };
+  askApi?: string;
+  sitemap?: string;
+  feeds?: string[];
+}
+
+/** The published `agent-readability.json` document. */
+export interface AgentReadabilityManifest {
+  artifacts: AgentArtifacts;
+  description?: string;
+  generator?: string;
+  name: string;
+  site: string | null;
+  contentUsage?: Record<string, boolean>;
+  repository?: string;
+}
+
 /** The `.well-known` discovery artifacts the site publishes, if any. */
 const wellKnownArtifacts = (
   config: BlumeProject["config"],
   abs: (path: string) => string
-): Record<string, string> => {
-  const artifacts: Record<string, string> = {};
+): WellKnownArtifacts => {
+  const artifacts: WellKnownArtifacts = {};
   if (config.ai.webBotAuth.keys.length > 0) {
     artifacts.httpMessageSignaturesDirectory = abs(
       "/.well-known/http-message-signatures-directory"
@@ -76,7 +106,7 @@ const wellKnownArtifacts = (
  */
 export const buildAgentReadability = (
   project: BlumeProject
-): Record<string, unknown> | null => {
+): AgentReadabilityManifest | null => {
   const { config } = project;
   if (!config.seo.agentReadability) {
     return null;
@@ -88,7 +118,7 @@ export const buildAgentReadability = (
   const deployBase = normalizeBasePath(config.deployment.base);
   const abs = (path: string): string => {
     const based = withBasePath(deployBase, path);
-    return site ? `${site.replace(/\/+$/u, "")}${based}` : based;
+    return site ? absoluteUrl(site, based) : based;
   };
 
   // Advertise `Accept: text/markdown` negotiation only where the deployed site
@@ -102,12 +132,10 @@ export const buildAgentReadability = (
     config.deployment.output === "server" &&
     (config.deployment.adapter === "vercel" ||
       config.deployment.adapter === "cloudflare");
-  const artifacts: Record<string, unknown> = {
-    markdown: {
-      ...(negotiates ? { contentNegotiation: "text/markdown" } : {}),
-      pattern: abs("/{route}.md"),
-    },
-  };
+  const markdown: AgentArtifacts["markdown"] = negotiates
+    ? { contentNegotiation: "text/markdown", pattern: abs("/{route}.md") }
+    : { pattern: abs("/{route}.md") };
+  const artifacts: AgentArtifacts = { markdown };
   if (config.ai.llmsTxt.enabled) {
     artifacts.llmsFullTxt = abs("/llms-full.txt");
     artifacts.llmsTxt = abs("/llms.txt");
@@ -134,7 +162,7 @@ export const buildAgentReadability = (
   }
 
   const version = project.manifest?.blumeVersion;
-  const manifest: Record<string, unknown> = {
+  const manifest: AgentReadabilityManifest = {
     artifacts,
     description: config.description,
     generator: version ? `blume@${version}` : undefined,

package/src/ai/api-catalog.ts

@@ -1,6 +1,6 @@
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
-import { trimEnd } from "../core/trim.ts";
+import { absoluteUrl } from "../core/site-url.ts";
 import { resolveReferences } from "../openapi/references.ts";
 
 /**
@@ -32,7 +32,7 @@ const linksetEntries = (config: ResolvedConfig): LinksetEntry[] => {
   const deployBase = normalizeBasePath(config.deployment.base);
   const abs = (path: string): string => {
     const based = withBasePath(deployBase, path);
-    return site ? `${trimEnd(site, "/")}${based}` : based;
+    return site ? absoluteUrl(site, based) : based;
   };
 
   const entries: LinksetEntry[] = [];

package/src/ai/ask-context.ts

@@ -1,3 +1,4 @@
+import { normalizeRoute } from "../core/base-path.ts";
 import { buildOramaIndex, queryOramaIndex } from "../search/orama-index.ts";
 import type { OramaDoc } from "../search/orama-index.ts";
 
@@ -90,11 +91,43 @@ const STOPWORDS = new Set([
   "your",
 ]);
 
+/** A run of letters, combining marks and digits inside a word-like segment. */
+const TERM = /[\p{L}\p{M}\p{N}]+/gu;
+
+/**
+ * Word-shaped pieces of a query, NFC-normalized and lowercased. Languages
+ * written without spaces (the CJK/Thai sites the Orama tokenizer goes out of
+ * its way to support) have no delimiter for a regex to split on, so the query
+ * is cut with `Intl.Segmenter` where available — otherwise every excerpt
+ * window silently degrades to the head of the page. The regex fallback covers
+ * runtimes without the segmenter and still handles spaced scripts correctly.
+ */
+const hasSegmenter = (
+  segmenter: typeof Intl.Segmenter | undefined
+): segmenter is typeof Intl.Segmenter => typeof segmenter === "function";
+
+const segmentQuery = (query: string): string[] => {
+  const lowered = query.normalize("NFC").toLowerCase();
+  if (!hasSegmenter(Intl.Segmenter)) {
+    return lowered.match(TERM) ?? [];
+  }
+  const pieces: string[] = [];
+  const segmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+  for (const segment of segmenter.segment(lowered)) {
+    if (segment.isWordLike) {
+      pieces.push(segment.segment);
+    }
+  }
+  return pieces;
+};
+
 /** Distinct, meaningful lowercase terms from a query (drops stopwords). */
-const queryTerms = (query: string): string[] =>
-  [...new Set(query.toLowerCase().match(/[a-z0-9]+/gu))].filter(
+const queryTerms = (query: string): string[] => {
+  const terms = segmentQuery(query).flatMap((piece) => piece.match(TERM) ?? []);
+  return [...new Set(terms)].filter(
     (term) => term.length >= 2 && !STOPWORDS.has(term)
   );
+};
 
 /**
  * The grounding preamble. The model is told to answer strictly from the injected
@@ -104,13 +137,6 @@ const queryTerms = (query: string): string[] =>
 const BASE_INSTRUCTION =
   "You are a helpful documentation assistant for this project. Answer the user's question using ONLY the documentation excerpts below. Each excerpt is headed by its page as `## Page Title (/route)`. If the answer is not covered by the excerpts, say you don't know and suggest where in the docs to look — do not invent details. Always cite the pages you drew from, and write every citation as a Markdown link to that page using its route, e.g. [Page Title](/route).";
 
-/** Normalize a page path to a document `route` (`/`, `/a/b`, no trailing slash). */
-const normalizeRoute = (input: string): string => {
-  const noTrailing = input.trim().replace(/\/+$/u, "");
-  const withSlash = noTrailing.startsWith("/") ? noTrailing : `/${noTrailing}`;
-  return withSlash === "" ? "/" : withSlash;
-};
-
 /** The most recent non-empty user message, used as the retrieval query. */
 const lastUserMessage = (messages: AskMessage[]): string => {
   for (let i = messages.length - 1; i >= 0; i -= 1) {
@@ -137,7 +163,9 @@ export const relevantExcerpt = (
   query: string,
   max: number
 ): string => {
-  const trimmed = content.trim();
+  // NFC to match the normalized query terms; positions are computed on (and
+  // sliced from) this same string, so offsets stay aligned.
+  const trimmed = content.normalize("NFC").trim();
   if (trimmed.length <= max) {
     return trimmed;
   }
@@ -199,9 +227,15 @@ export const relevantExcerpt = (
  * grounded system prompt — the retrieved excerpts plus the page the user is
  * 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
+ * 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.
  */
 export const createAskContext = (
-  data: AskData
+  data: AskData,
+  options?: { instructions?: string }
 ): ((
   messages: AskMessage[],
   page?: AskPage
@@ -213,6 +247,9 @@ export const createAskContext = (
     return dbPromise;
   };
   const byRoute = new Map(data.documents.map((doc) => [doc.route, doc]));
+  const instruction = options?.instructions
+    ? `${BASE_INSTRUCTION}\n\n${options.instructions}`
+    : BASE_INSTRUCTION;
 
   return async (messages, page) => {
     const list = Array.isArray(messages) ? messages : [];
@@ -257,6 +294,6 @@ export const createAskContext = (
     if (sections.length === 0) {
       return;
     }
-    return `${BASE_INSTRUCTION}\n\n<docs>\n${sections.join("\n\n")}\n</docs>`;
+    return `${instruction}\n\n<docs>\n${sections.join("\n\n")}\n</docs>`;
   };
 };

package/src/ai/ask.ts

@@ -35,7 +35,16 @@ const OPENAI_COMPATIBLE = "openai-compatible";
 /** The AI SDK provider package the OpenAI-compatible providers install. */
 const OPENAI_COMPATIBLE_DEP = "@ai-sdk/openai-compatible";
 
-const ASK_PRESETS: Record<string, AskPreset> = {
+/**
+ * Connection presets keyed by provider name. Open-keyed on purpose: lookups
+ * use the configured `ai.ask.provider`, which includes values with no preset
+ * (the generic `openai-compatible`).
+ */
+interface AskPresetRegistry {
+  [provider: string]: AskPreset;
+}
+
+const ASK_PRESETS: AskPresetRegistry = {
   inkeep: {
     apiKeyEnv: "INKEEP_API_KEY",
     baseUrl: "https://api.inkeep.com/v1",

package/src/ai/component-markdown.ts

@@ -47,10 +47,31 @@ interface Splice {
   text: string;
 }
 
+/**
+ * A statically-recovered data value. Parsed front matter and evaluated
+ * attribute literals are both plain data — scalars, dates, arrays, and
+ * nested maps — never functions or class instances.
+ */
+export type EvaluatedValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Date
+  | EvaluatedValue[]
+  | { [key: string]: EvaluatedValue };
+
+const isString = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
+const isNumber = <Value>(value: Value): value is Value & number =>
+  typeof value === "number";
+
 /** Evaluated props plus whether any attribute resisted static evaluation. */
 interface EvaluatedProps {
   lossy: boolean;
-  props: Record<string, unknown>;
+  props: Record<string, EvaluatedValue>;
 }
 
 /** A child component extracted by name (e.g. each `<Step>` under `<Steps>`). */
@@ -70,7 +91,7 @@ export interface ComponentMarkdownContext extends EvaluatedProps {
    * serializer read page metadata directly, even when a prop expression is
    * not statically evaluable.
    */
-  frontmatter: Record<string, unknown>;
+  frontmatter: Record<string, EvaluatedValue>;
 }
 
 /**
@@ -93,15 +114,16 @@ export type ComponentMarkdown = (
  */
 const evaluateExpression = (
   raw: string,
-  frontmatter: Record<string, unknown> | undefined
-): { ok: boolean; value: unknown } => {
+  frontmatter: Record<string, EvaluatedValue> | undefined
+) => {
   try {
     // Build-time eval of the author's own attribute literals; a throw falls
     // back to leaving the JSX verbatim.
     // oxlint-disable-next-line no-new-func
-    const value = new Function("frontmatter", `"use strict"; return (${raw});`)(
-      frontmatter
-    );
+    const value: EvaluatedValue = new Function(
+      "frontmatter",
+      `"use strict"; return (${raw});`
+    )(frontmatter);
     return { ok: true, value };
   } catch {
     return { ok: false, value: undefined };
@@ -111,9 +133,9 @@ const evaluateExpression = (
 /** Evaluate an element's attributes into a plain props object. */
 const readProps = (
   node: MdastNode,
-  frontmatter: Record<string, unknown> | undefined
+  frontmatter: Record<string, EvaluatedValue> | undefined
 ): EvaluatedProps => {
-  const props: Record<string, unknown> = {};
+  const props: Record<string, EvaluatedValue> = {};
   let lossy = false;
   for (const attribute of node.attributes ?? []) {
     // A spread ({...props}) can't be recovered statically.
@@ -124,7 +146,7 @@ const readProps = (
     if (attribute.value === null || attribute.value === undefined) {
       // Boolean shorthand: `<Steps compact>`.
       props[attribute.name] = true;
-    } else if (typeof attribute.value === "string") {
+    } else if (isString(attribute.value)) {
       props[attribute.name] = attribute.value;
     } else {
       const result = evaluateExpression(attribute.value.value, frontmatter);
@@ -198,35 +220,49 @@ const isJsxElement = (node: MdastNode): boolean =>
   node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement";
 
 /** Flatten a value to a single Markdown table cell (pipes escaped). */
-const cellText = (value: unknown): string =>
+const cellText = (value: EvaluatedValue): string =>
   String(value ?? "")
     .replaceAll(/\s*\n\s*/gu, " ")
     .replaceAll("|", "\\|")
     .trim();
 
 /** A cell rendered as inline code, unless the value itself uses backticks. */
-const cellCode = (value: unknown): string => {
+const cellCode = (value: EvaluatedValue): string => {
   const text = cellText(value);
   return text && !text.includes("`") ? `\`${text}\`` : text;
 };
 
-/** One `<TypeTable type={{...}}>` entry, matching the component's shape. */
+/**
+ * One `<TypeTable type={{...}}>` entry, matching the component's props. The
+ * index signature keeps the interface interchangeable with the evaluated
+ * data-value maps it is narrowed from.
+ */
 interface TypeEntry {
-  default?: unknown;
-  description?: unknown;
-  required?: unknown;
-  type?: unknown;
-  typeDescription?: unknown;
-  typeDescriptionLink?: unknown;
+  [field: string]: EvaluatedValue;
+  default?: EvaluatedValue;
+  description?: EvaluatedValue;
+  required?: EvaluatedValue;
+  type?: EvaluatedValue;
+  typeDescription?: EvaluatedValue;
+  typeDescriptionLink?: EvaluatedValue;
 }
 
+/**
+ * The `type` data prop's entry map. Structural only: each entry's fields are
+ * rendered through cellText/cellCode, which stringify any value.
+ */
+const isTypeEntryMap = (
+  value: EvaluatedValue
+): value is Record<string, TypeEntry> =>
+  typeof value === "object" && value !== null;
+
 const typeTable: ComponentMarkdown = ({ children, props }) => {
   const { type } = props;
-  if (type === null || typeof type !== "object") {
+  if (!isTypeEntryMap(type)) {
     // The data prop is missing or wasn't statically evaluable.
     return null;
   }
-  const entries = Object.entries(type as Record<string, TypeEntry>);
+  const entries = Object.entries(type);
   const rows = entries.map(([name, info]) => {
     const prop = cellCode(`${name}${info.required ? "" : "?"}`);
     const typeCell = info.typeDescriptionLink
@@ -236,7 +272,7 @@ const typeTable: ComponentMarkdown = ({ children, props }) => {
       info.default === undefined ? "-" : cellCode(info.default);
     const description = cellText(
       [info.description, info.typeDescription]
-        .filter((part) => typeof part === "string" && part !== "")
+        .filter((part) => isString(part) && part !== "")
         .join(" ")
     );
     return [prop, typeCell, defaultCell, description];
@@ -254,9 +290,9 @@ const typeTable: ComponentMarkdown = ({ children, props }) => {
 };
 
 const callout: ComponentMarkdown = ({ children, props }) => {
-  const type = typeof props.type === "string" ? props.type : "info";
+  const type = isString(props.type) ? props.type : "info";
   const label =
-    typeof props.title === "string" && props.title !== ""
+    isString(props.title) && props.title !== ""
       ? props.title
       : type.charAt(0).toUpperCase() + type.slice(1);
   if (!children) {
@@ -291,7 +327,7 @@ const steps: ComponentMarkdown = ({ childComponents, children }) => {
   return items
     .map((step, index) => {
       const title =
-        typeof step.props.title === "string" && step.props.title !== ""
+        isString(step.props.title) && step.props.title !== ""
           ? `**${step.props.title}**`
           : "";
       const content = [title, step.children].filter(Boolean).join("\n\n");
@@ -308,7 +344,7 @@ const tabs: ComponentMarkdown = ({ childComponents, children }) => {
   return items
     .map((tab, index) => {
       const title =
-        typeof tab.props.title === "string" && tab.props.title !== ""
+        isString(tab.props.title) && tab.props.title !== ""
           ? tab.props.title
           : `Tab ${index + 1}`;
       return tab.children ? `**${title}**\n\n${tab.children}` : `**${title}**`;
@@ -318,9 +354,9 @@ const tabs: ComponentMarkdown = ({ childComponents, children }) => {
 
 const youtube: ComponentMarkdown = ({ props }) => {
   let input = "";
-  if (typeof props.id === "string") {
+  if (isString(props.id)) {
     input = props.id;
-  } else if (typeof props.url === "string") {
+  } else if (isString(props.url)) {
     input = props.url;
   }
   const videoId = parseYouTubeId(input);
@@ -328,11 +364,11 @@ const youtube: ComponentMarkdown = ({ props }) => {
     return null;
   }
   const start =
-    typeof props.start === "number" && props.start > 0
+    isNumber(props.start) && props.start > 0
       ? `&t=${Math.floor(props.start)}s`
       : "";
   const title =
-    typeof props.title === "string" && props.title !== ""
+    isString(props.title) && props.title !== ""
       ? props.title
       : "Watch on YouTube";
   return `[${title}](https://www.youtube.com/watch?v=${videoId}${start})`;
@@ -355,28 +391,27 @@ const fencedBlock = (lang: string, code: string): string => {
  * the JSX verbatim, mirroring the "no example found" note the component renders
  * on the page.
  */
-export const exampleComponentSerializers = (
-  examples: ExampleLookup
-): Record<string, ComponentMarkdown> => ({
-  Component: ({ props }) => {
-    const path = typeof props.path === "string" ? props.path : undefined;
-    const example = path === undefined ? undefined : examples[path];
-    return example ? fencedBlock(example.lang, example.source) : null;
-  },
-});
+export const exampleComponentSerializers = (examples: ExampleLookup) =>
+  ({
+    Component: ({ props }) => {
+      const path = isString(props.path) ? props.path : undefined;
+      const example = path === undefined ? undefined : examples[path];
+      return example ? fencedBlock(example.lang, example.source) : null;
+    },
+  }) satisfies Record<string, ComponentMarkdown>;
 
 /**
  * The built-in serializer registry, keyed by JSX name. `Step` and `Tab` are
  * intentionally absent: they only carry meaning inside their containers,
  * which extract them via `childComponents`; a stray one stays verbatim.
  */
-const SERIALIZERS: Record<string, ComponentMarkdown> = {
+const SERIALIZERS = {
   Callout: callout,
   Steps: steps,
   Tabs: tabs,
   TypeTable: typeTable,
   YouTube: youtube,
-};
+} satisfies Record<string, ComponentMarkdown>;
 
 const escapeRegExp = (value: string): string =>
   value.replaceAll(/[$()*+.?[\\\]^{|}]/gu, String.raw`\$&`);
@@ -394,7 +429,7 @@ const BUILT_IN_HINT = componentHint(SERIALIZERS);
 
 /** One downlevel pass's inputs: the source, registry, and page metadata. */
 interface Walk {
-  frontmatter: Record<string, unknown> | undefined;
+  frontmatter: Record<string, EvaluatedValue> | undefined;
   registry: Record<string, ComponentMarkdown>;
   source: string;
 }
@@ -494,7 +529,7 @@ const collectSplices = (
 export const downlevelComponents = (
   source: string,
   components?: Record<string, ComponentMarkdown>,
-  frontmatter?: Record<string, unknown>
+  frontmatter?: Record<string, EvaluatedValue>
 ): string => {
   const custom = components && Object.keys(components).length > 0;
   const registry = custom ? { ...SERIALIZERS, ...components } : SERIALIZERS;
@@ -504,6 +539,8 @@ export const downlevelComponents = (
   }
   let tree: MdastNode;
   try {
+    // SAFETY: MdastNode is a structural subset of Satteri's mdast output —
+    // every node carries `type`, and the walk reads only optional fields.
     tree = mdxToMdast(source) as MdastNode;
   } catch {
     return source;

package/src/ai/llms.ts

@@ -2,6 +2,7 @@ import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import { rewriteRelativeImages } from "../core/content-assets.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import { absoluteUrl } from "../core/site-url.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
@@ -17,20 +18,26 @@ import { applyAgentVisibility } from "./visibility.ts";
 // spaces or non-ASCII must still yield a valid Markdown link.
 const pageUrl = (route: string, site?: string, base = ""): string => {
   const path = withBasePath(base, route);
-  return encodeURI(site ? `${site.replace(/\/$/u, "")}${path}` : path);
+  return encodeURI(site ? absoluteUrl(site, path) : path);
 };
 
 // Drafts, hidden, and ordinary `noindex` pages are excluded. Generated API
 // references keep crawler visibility (`noindex`) separate from LLM visibility
 // (`ai.exclude`), and are excluded wholesale when `ai.llmsTxt.openapi` is off.
-const eligiblePages = (project: BlumeProject): PageRecord[] =>
+// `versions: "current"` additionally drops archived-snapshot pages — the flat
+// llms-full.txt dump serves agents the live docs, not every frozen copy.
+const eligiblePages = (
+  project: BlumeProject,
+  options: { versions?: "all" | "current" } = {}
+): PageRecord[] =>
   project.graph.pages.filter(
     (page) =>
       !(
         page.meta.ai.exclude ||
         page.meta.draft ||
         page.meta.sidebar.hidden ||
-        (page.meta.seo.noindex && page.source.name !== "openapi")
+        (page.meta.seo.noindex && page.source.name !== "openapi") ||
+        (options.versions === "current" && page.version !== "")
       ) &&
       (project.config.ai.llmsTxt.openapi || page.source.name !== "openapi")
   );
@@ -38,22 +45,40 @@ const eligiblePages = (project: BlumeProject): PageRecord[] =>
 /**
  * The navigation trees the index mirrors: the site tree, or one per locale
  * under i18n (each labeled with the locale except the default, so sections
- * don't repeat ambiguously).
+ * don't repeat ambiguously). On a versioned site each archived snapshot's
+ * trees follow the current ones, labeled with the version (and locale) so an
+ * agent reading the index knows which docs are frozen.
  */
 const indexedNavigations = (
   project: BlumeProject
 ): { label?: string; nav: Navigation }[] => {
-  const { i18n } = project.config;
-  if (i18n) {
-    return i18n.locales.flatMap(({ code, label }) => {
-      const nav = project.graph.navigationByLocale[code];
-      if (!nav) {
-        return [];
-      }
-      return [{ label: code === i18n.defaultLocale ? undefined : label, nav }];
+  const { i18n, versions } = project.config;
+  const current: { label?: string; nav: Navigation }[] = i18n
+    ? i18n.locales.flatMap(({ code, label }) => {
+        const nav = project.graph.navigationByLocale[code];
+        if (!nav) {
+          return [];
+        }
+        return [
+          { label: code === i18n.defaultLocale ? undefined : label, nav },
+        ];
+      })
+    : [{ nav: project.graph.navigation }];
+
+  const archived = (versions?.archived ?? []).flatMap((version) => {
+    const byLocale = project.graph.navigationByVersion[version.id] ?? {};
+    const versionLabel = `${version.label ?? version.id} (archived)`;
+    return Object.entries(byLocale).flatMap(([code, nav]) => {
+      const locale = i18n?.locales.find((entry) => entry.code === code);
+      const label =
+        locale && code !== i18n?.defaultLocale
+          ? `${locale.label} — ${versionLabel}`
+          : versionLabel;
+      return [{ label, nav }];
     });
-  }
-  return [{ nav: project.graph.navigation }];
+  });
+
+  return [...current, ...archived];
 };
 
 /**
@@ -168,11 +193,11 @@ export const buildLlmsIndex = (project: BlumeProject): string => {
   return `${[header, ...blocks].join("\n\n")}\n`;
 };
 
-/** Build `llms-full.txt`: the full Markdown body of every page. */
+/** Build `llms-full.txt`: the full Markdown body of every current-docs page. */
 const buildFull = async (project: BlumeProject): Promise<string> => {
   const { config } = project;
-  const pages = eligiblePages(project).toSorted((a, b) =>
-    a.route.localeCompare(b.route)
+  const pages = eligiblePages(project, { versions: "current" }).toSorted(
+    (a, b) => a.route.localeCompare(b.route)
   );
   // Downlevel `<Component>` to its example's source; a same-name user
   // `markdownComponents` entry is spread last and still wins.