blume 1.4.3 → 1.5.0

package/dist/cli/index.js

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/cli/index.ts
-import { defineCommand as defineCommand15, runMain } from "citty";
+import { defineCommand as defineCommand16, runMain } from "citty";
 
 // src/core/version.ts
 import { readFileSync } from "node:fs";
@@ -297,7 +297,7 @@ var DOCS_DEPLOYMENT = "/docs/deployment";
 var DOCS_REFERENCE_CLI = "/docs/reference/cli";
 var DOCS_CONTENT_SOURCES = "/docs/content/sources";
 var DOCS_CONTENT_NAVIGATION = "/docs/content/navigation";
-var DOCS_PATHS = {
+var DOCS_PATHS = new Map(Object.entries({
   BLUME_ADAPTER_REQUIRED: DOCS_DEPLOYMENT,
   BLUME_ASSETS_UNCHECKED: DOCS_REFERENCE_CLI,
   BLUME_ASSET_FETCH_FAILED: DOCS_CONTENT_SOURCES,
@@ -320,6 +320,7 @@ var DOCS_PATHS = {
   BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
   BLUME_NODE_VERSION: "/docs/quickstart",
   BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
+  BLUME_SIDEBAR_DISPLAY_IGNORED: DOCS_CONTENT_NAVIGATION,
   BLUME_SOURCE_FETCH_FAILED: DOCS_CONTENT_SOURCES,
   BLUME_SOURCE_MISCONFIGURED: DOCS_CONTENT_SOURCES,
   BLUME_SOURCE_OFFLINE: DOCS_CONTENT_SOURCES,
@@ -327,16 +328,17 @@ var DOCS_PATHS = {
   BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
   BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
   BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION
-};
+}));
 var resolveDocsUrl = (code) => {
-  const path = DOCS_PATHS[code];
+  const path = DOCS_PATHS.get(code);
   return path ? `${DOCS_BASE}${path}` : undefined;
 };
 var enrichDiagnostic = (diagnostic) => diagnostic.docsUrl ? diagnostic : { ...diagnostic, docsUrl: resolveDocsUrl(diagnostic.code) };
 var REGEXP_SPECIAL = /[$()*+.?[\\\]^{|}]/gu;
 var escapeRegExp = (value) => value.replaceAll(REGEXP_SPECIAL, String.raw`\$&`);
+var isKeySegment = (segment) => typeof segment === "string";
 var stepSegment = (source, segment, cursor) => {
-  if (typeof segment !== "string") {
+  if (!isKeySegment(segment)) {
     return { index: -1, next: cursor, stop: false };
   }
   const matcher = new RegExp(`(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`, "gu");
@@ -1298,10 +1300,10 @@ var GLYPH = {
   warning: "⚠"
 };
 var PREVIEW = 3;
-var TIER_FLAG = {
-  external: "--external",
-  network: "--url <origin>"
-};
+var TIER_FLAGS = [
+  { flag: "--external", tier: "external" },
+  { flag: "--url <origin>", tier: "network" }
+];
 var rollup = (diagnostics) => {
   const groups = new Map;
   for (const diagnostic of diagnostics) {
@@ -1318,12 +1320,13 @@ var rollup = (diagnostics) => {
     warning: 1
   };
   const checks = [...groups.entries()].map(([id, findings]) => {
-    const { category, severity, title } = checkMeta(id);
+    const checkId = id;
+    const { category, severity, title } = checkMeta(checkId);
     return {
       category,
       count: findings.length,
       findings,
-      id,
+      id: checkId,
       severity,
       title
     };
@@ -1335,9 +1338,9 @@ var rollup = (diagnostics) => {
   }
   return checks.toSorted((a, b) => (worst.get(a.category) ?? 0) - (worst.get(b.category) ?? 0) || a.category.localeCompare(b.category) || order[a.severity] - order[b.severity] || b.count - a.count);
 };
-var skippedTiers = (tiers) => Object.keys(TIER_FLAG).filter((tier) => !tiers[tier]).map((tier) => {
+var skippedTiers = (tiers) => TIER_FLAGS.filter(({ tier }) => !tiers[tier]).map(({ flag, tier }) => {
   const label = CHECKS.filter((check) => check.tier === tier).length;
-  return `  ${colors2.dim(`⊘ ${tier.padEnd(12)} skipped — pass ${TIER_FLAG[tier]} (${label} checks)`)}`;
+  return `  ${colors2.dim(`⊘ ${tier.padEnd(12)} skipped — pass ${flag} (${label} checks)`)}`;
 });
 var activeChecks = (tiers) => CHECKS.filter((check) => tiers[check.tier]).length;
 var auditCount = (result) => activeChecks(result.tiers) * result.pages;
@@ -1721,6 +1724,9 @@ var assetChecks = {
   tier: "static"
 };
 
+// src/audit/checks/content.ts
+import stringWidth from "string-width";
+
 // src/core/frontmatter.ts
 import baseMatter from "gray-matter";
 import { dump, load } from "js-yaml";
@@ -1746,17 +1752,21 @@ var opensWithThematicBreak = (input) => {
   return !input.includes(`
 ---`, 1);
 };
-var passthrough = (input) => ({
-  content: input,
-  data: {},
-  excerpt: "",
-  isEmpty: false,
-  language: "",
-  matter: "",
-  orig: input,
-  stringify: () => input
-});
-var matter = Object.assign((input, options) => typeof input === "string" && opensWithThematicBreak(input) ? passthrough(input) : baseMatter(input, withYamlEngine(options)), baseMatter, {
+var passthrough = (input) => {
+  const file = {
+    content: input,
+    data: {},
+    excerpt: "",
+    isEmpty: false,
+    language: "",
+    matter: "",
+    orig: input,
+    stringify: () => input
+  };
+  return file;
+};
+var isStringInput = (input) => typeof input === "string";
+var matter = Object.assign((input, options) => isStringInput(input) && opensWithThematicBreak(input) ? passthrough(input) : baseMatter(input, withYamlEngine(options)), baseMatter, {
   read: (filepath, options) => baseMatter.read(filepath, withYamlEngine(options)),
   stringify: (file, data, options) => baseMatter.stringify(file, data, withYamlEngine(options))
 });
@@ -1776,10 +1786,12 @@ var DEFAULT_THRESHOLDS = {
 };
 
 // src/audit/checks/content.ts
+var WHITESPACE = /\s+/gu;
+var isDateValue = (value) => typeof value === "string" || value instanceof Date;
 var frontmatterDate = (source) => {
   try {
     const { date } = frontmatter_default(source).data;
-    if (typeof date !== "string" && !(date instanceof Date)) {
+    if (!isDateValue(date)) {
       return null;
     }
     const parsed = date instanceof Date ? date : new Date(date);
@@ -1800,9 +1812,10 @@ var titleChecks = (context, page) => {
   if (page.titles.length > 1) {
     found.push(finding("BLUME_AUDIT_TITLE_MULTIPLE", pageSite(context, page), `Page has ${page.titles.length} <title> tags; search engines use only the first.`));
   }
-  if (title.length > titleMax || title.length < titleMin) {
-    const direction = title.length > titleMax ? "long" : "short";
-    found.push(finding("BLUME_AUDIT_TITLE_LENGTH", pageSite(context, page, ["title"]), `Title is ${title.length} characters — too ${direction} (aim for ${titleMin}–${titleMax}).`));
+  const width = stringWidth(title.replaceAll(WHITESPACE, " "));
+  if (width > titleMax || width < titleMin) {
+    const direction = width > titleMax ? "long" : "short";
+    found.push(finding("BLUME_AUDIT_TITLE_LENGTH", pageSite(context, page, ["title"]), `Title renders ${width} columns wide — too ${direction} (aim for ${titleMin}–${titleMax}).`));
   }
   return found;
 };
@@ -1821,9 +1834,10 @@ var descriptionChecks = (context, page) => {
   if (page.descriptions.length > 1) {
     found.push(finding("BLUME_AUDIT_DESCRIPTION_MULTIPLE", pageSite(context, page), `Page has ${page.descriptions.length} meta description tags.`));
   }
-  if (description.length > descriptionMax || description.length < descriptionMin) {
-    const direction = description.length > descriptionMax ? "long" : "short";
-    found.push(finding("BLUME_AUDIT_DESCRIPTION_LENGTH", pageSite(context, page, ["description"]), `Meta description is ${description.length} characters — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`));
+  const width = stringWidth(description.replaceAll(WHITESPACE, " "));
+  if (width > descriptionMax || width < descriptionMin) {
+    const direction = width > descriptionMax ? "long" : "short";
+    found.push(finding("BLUME_AUDIT_DESCRIPTION_LENGTH", pageSite(context, page, ["description"]), `Meta description renders ${width} columns wide — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`));
   }
   return found;
 };
@@ -2236,7 +2250,13 @@ var canonicalChecks = (context, page) => {
   if (redirect) {
     found.push(finding("BLUME_AUDIT_CANONICAL_BAD_TARGET", pageSite(context, page, ["seo", "canonical"]), `Canonical points at ${target}, which is a redirect to ${redirect.to}.`));
   } else if (context.byUrl.has(target)) {
-    found.push(finding("BLUME_AUDIT_CANONICAL_NOT_SELF", pageSite(context, page, ["seo", "canonical"]), `Page declares ${target} as its canonical, so it will not be indexed itself.`));
+    const version = page.route?.version;
+    const archived = version ? context.project.config.versions?.archived.find((entry) => entry.id === version) : undefined;
+    const latestAlternate = page.route?.versionAlternates.find((alternate) => alternate.version === "");
+    const intentional = archived?.canonical === "latest" && latestAlternate !== undefined && normalizePath(latestAlternate.path) === target;
+    if (!intentional) {
+      found.push(finding("BLUME_AUDIT_CANONICAL_NOT_SELF", pageSite(context, page, ["seo", "canonical"]), `Page declares ${target} as its canonical, so it will not be indexed itself.`));
+    }
   } else {
     found.push(finding("BLUME_AUDIT_CANONICAL_BAD_TARGET", pageSite(context, page, ["seo", "canonical"]), `Canonical points at ${target}, which is not a page on this site.`));
   }
@@ -2407,9 +2427,10 @@ var linkChecks = {
 };
 
 // src/audit/checks/llms.ts
+var isLlmsToggleObject = (value) => typeof value === "object" && value !== null;
 var llmsConfig = (context) => {
   const value = context.project.config.ai?.llmsTxt;
-  if (typeof value === "object" && value !== null) {
+  if (isLlmsToggleObject(value)) {
     return { enabled: value.enabled, openapi: value.openapi };
   }
   return { enabled: value !== false, openapi: true };
@@ -2946,22 +2967,22 @@ var socialChecks = {
   },
   tier: "static"
 };
+var isJsonLdNode = (value) => typeof value === "object" && value !== null;
 var jsonLdProblems = (node) => {
-  if (typeof node !== "object" || node === null) {
+  if (!isJsonLdNode(node)) {
     return ["it is not an object"];
   }
-  const record = node;
   const problems = [];
-  if (!record["@context"]) {
+  if (!node["@context"]) {
     problems.push("@context");
   }
-  const graph = record["@graph"];
+  const graph = node["@graph"];
   if (Array.isArray(graph)) {
-    const untyped = graph.filter((entry) => typeof entry !== "object" || entry === null || !entry["@type"]).length;
+    const untyped = graph.filter((entry) => !isJsonLdNode(entry) || !entry["@type"]).length;
     if (untyped > 0) {
       problems.push(`@type on ${untyped} of its ${graph.length} @graph nodes`);
     }
-  } else if (!record["@type"]) {
+  } else if (!node["@type"]) {
     problems.push("@type");
   }
   return problems;
@@ -3155,17 +3176,19 @@ var referencesFor = (kind, block, defaultLabel, renderer, display, basePath) =>
     };
   });
 };
-var NO_DISPLAY = { codeSamples: [], expandSchemas: false };
 var resolveReferences = (config) => [
   ...referencesFor("openapi", config.openapi, "API Reference", config.openapi.renderer, {
     codeSamples: config.openapi.codeSamples,
     expandSchemas: config.openapi.expandSchemas
   }, config.basePath),
-  ...referencesFor("asyncapi", config.asyncapi, "Events", "scalar", NO_DISPLAY, config.basePath)
+  ...referencesFor("asyncapi", config.asyncapi, "Events", config.asyncapi.renderer, {
+    codeSamples: config.asyncapi.codeSamples,
+    expandSchemas: config.asyncapi.expandSchemas
+  }, config.basePath)
 ];
 var referenceRoutes = (config) => resolveReferences(config).map((ref) => ref.renderer === "blume" ? withBasePath(config.basePath, ref.route) : ref.route);
 var blumeReferenceOf = (ref, seen, usedSlugs) => {
-  if (ref.kind !== "openapi" || ref.renderer !== "blume") {
+  if (ref.renderer !== "blume") {
     return null;
   }
   const kept = seen.get(ref.route);
@@ -3279,7 +3302,7 @@ var excludeDirSegments = (patterns) => patterns.map((pattern) => /^(?<dir>[^*/]+
 var ignoringWatchListener = (onChange, ignoreDirs = BLUME_WATCH_IGNORE_DIRS) => {
   const ignore = new Set(ignoreDirs);
   return (_event, filename) => {
-    if (typeof filename === "string" && filename.split(/[/\\]/u).some((segment) => ignore.has(segment))) {
+    if (filename !== null && filename.split(/[/\\]/u).some((segment) => ignore.has(segment))) {
       return;
     }
     onChange();
@@ -3492,8 +3515,9 @@ var slugifyFontName = (name) => name.toLowerCase().replaceAll(/[^a-z0-9]+/gu, "-
 var fontVar = (slug) => `--blume-ff-${slug}`;
 var SLOTS = ["display", "body", "mono"];
 var slotCategory = (slot) => slot === "mono" ? "mono" : "sans";
+var isSlugValue = (value) => typeof value === "string";
 var resolveFontValue = (slot, value) => {
-  if (typeof value === "string") {
+  if (isSlugValue(value)) {
     if (!isFontSlug(value)) {
       return null;
     }
@@ -3559,7 +3583,7 @@ var buildFontEntries = (fonts) => {
   return [...entries.values()];
 };
 var slotSlug = (value) => {
-  if (typeof value === "string") {
+  if (isSlugValue(value)) {
     return isFontSlug(value) ? value : null;
   }
   return slugifyFontName(value.name);
@@ -3626,9 +3650,9 @@ var ADAPTER_IMPORTS = {
   node: "@astrojs/node",
   vercel: "@astrojs/vercel"
 };
-var ADAPTER_OPTIONS = {
-  node: '{ mode: "standalone" }'
-};
+var ADAPTER_OPTIONS = new Map([
+  ["node", '{ mode: "standalone" }']
+]);
 var WRANGLER_CONFIG_FILES = [
   "wrangler.jsonc",
   "wrangler.json",
@@ -3790,7 +3814,7 @@ var astroConfigTemplate = (options) => {
     if (deployment.adapter === "cloudflare") {
       return resolveCloudflareAdapterArgs(context);
     }
-    return ADAPTER_OPTIONS[deployment.adapter] ?? "";
+    return ADAPTER_OPTIONS.get(deployment.adapter) ?? "";
   })();
   const adapterExpr = deployment.adapter === "vercel" ? `withAdapterRoot(adapter(${adapterArgs}), ${JSON.stringify(adapterRoot(context))})` : `adapter(${adapterArgs})`;
   const adapterOption = server && deployment.adapter ? `
@@ -3817,13 +3841,21 @@ var astroConfigTemplate = (options) => {
   ])))},` : "";
   const fontEntries = buildFontEntries(config.theme.fonts);
   const fontsOption = fontEntries.length ? `
-  fonts: [${fontEntries.map((font) => font.kind === "local" ? `{ provider: fontProviders.local(), name: ${JSON.stringify(font.name)}, cssVariable: ${JSON.stringify(font.cssVariable)}, fallbacks: ${JSON.stringify(font.fallbacks)}, options: { variants: ${JSON.stringify(font.variants.map((variant) => ({
-    ...variant.weight === undefined ? {} : { weight: variant.weight },
-    ...variant.style === undefined ? {} : { style: variant.style },
-    src: [
-      isAbsolute(variant.src) ? variant.src : join8(context.root, variant.src)
-    ]
-  })))} } }` : `{ provider: fontProviders.${font.provider}(), name: ${JSON.stringify(font.name)}, cssVariable: ${JSON.stringify(font.cssVariable)}, weights: ${JSON.stringify(font.weights)}, fallbacks: ${JSON.stringify(font.fallbacks)} }`).join(", ")}],` : "";
+  fonts: [${fontEntries.map((font) => font.kind === "local" ? `{ provider: fontProviders.local(), name: ${JSON.stringify(font.name)}, cssVariable: ${JSON.stringify(font.cssVariable)}, fallbacks: ${JSON.stringify(font.fallbacks)}, options: { variants: ${JSON.stringify(font.variants.map((variant) => {
+    const face = {};
+    if (variant.weight !== undefined) {
+      face.weight = variant.weight;
+    }
+    if (variant.style !== undefined) {
+      face.style = variant.style;
+    }
+    return {
+      ...face,
+      src: [
+        isAbsolute(variant.src) ? variant.src : join8(context.root, variant.src)
+      ]
+    };
+  }))} } }` : `{ provider: fontProviders.${font.provider}(), name: ${JSON.stringify(font.name)}, cssVariable: ${JSON.stringify(font.cssVariable)}, weights: ${JSON.stringify(font.weights)}, fallbacks: ${JSON.stringify(font.fallbacks)} }`).join(", ")}],` : "";
   const defineConfigImport = astroConfigImportLine({
     hasFonts: fontEntries.length > 0,
     hasSession: sessionOption.length > 0
@@ -4638,11 +4670,13 @@ export function getStaticPaths() {
       locale: route.locale,
       route: route.path,
       title: route.title,
+      version: route.version,
+      versionAlternates: route.versionAlternates,
     },
   }));
 }
 
-const { entryId, collection, route, title, indexable, editUrl, lastModified, locale, alternates, fallback } = Astro.props;
+const { entryId, collection, route, title, indexable, editUrl, lastModified, locale, alternates, fallback, version, versionAlternates } = Astro.props;
 const entry = await getEntry(collection as CollectionKey, entryId);
 if (!entry) {
   return new Response(null, { status: 404 });
@@ -4674,9 +4708,6 @@ const ogGenerated = !seo.image && Boolean(ogPath);
 const x = { ...data.config.x, ...(seo.x?.creator ? { creator: seo.x.creator } : {}) };
 
 const basedRoute = withBase(route);
-const canonical =
-  seo.canonical ??
-  (base ? \`\${base}\${basedRoute === "/" ? "" : encodeURI(basedRoute)}\` : null);
 
 // Locale resolution. With i18n on, pick the active locale's nav + dictionary,
 // build hreflang alternates, and derive the language-switcher targets.
@@ -4697,7 +4728,20 @@ const stripLocale = (path: string, codeArg: string) => {
   return prefix && path.startsWith(prefix) ? path.slice(prefix.length) || "/" : path;
 };
 
-const navigation = i18n ? (data.navigationByLocale[locale] ?? data.navigation) : data.navigation;
+// Version resolution. An archived page renders its snapshot's navigation tree,
+// points its canonical at the latest equivalent (unless configured otherwise),
+// and shows the old-version notice.
+const versionsConfig = data.config.versions;
+const archived = versionsConfig && version
+  ? (versionsConfig.archived.find((v) => v.id === version) ?? null)
+  : null;
+const latestVersionAlt = (versionAlternates ?? []).find((alt) => alt.version === "");
+
+const navigation = version
+  ? (data.navigationByVersion[version]?.[i18n ? locale : ""] ?? data.navigation)
+  : i18n
+    ? (data.navigationByLocale[locale] ?? data.navigation)
+    : data.navigation;
 const ui = i18n ? (data.uiByLocale[locale] ?? data.ui) : data.ui;
 const localeMeta = i18n ? i18n.locales.find((l) => l.code === locale) : null;
 const dir = localeMeta?.dir ?? "ltr";
@@ -4714,6 +4758,19 @@ const absolute = (path: string) => {
   return base + (p === "/" ? "" : p);
 };
 
+// An archived page defaults its canonical to the same page in the latest docs
+// when that page still exists — search engines treat the live page as
+// authoritative without deindexing version-only content. A page's own
+// \`seo.canonical\` always wins, and \`canonical: "self"\` keeps the default.
+const canonical =
+  seo.canonical ??
+  (archived && archived.canonical === "latest" && latestVersionAlt && base
+    ? absolute(latestVersionAlt.path)
+    : base
+      ? \`\${base}\${basedRoute === "/" ? "" : encodeURI(basedRoute)}\`
+      : null);
+const effectiveNoindex = Boolean(seo.noindex) || (archived?.noindex ?? false);
+
 const localeAlternates =
   i18n && base
     ? (alternates ?? []).map((alt) => ({ hreflang: alt.locale, href: absolute(alt.path) }))
@@ -4736,6 +4793,72 @@ const localeSwitch = i18n
     })
   : [];
 
+// Version switcher + old-version notice. The switcher auto-populates from the
+// versions config as a \`kind: "version"\` selector; a user-declared version
+// selector in \`navigation.selectors\` suppresses it (theirs renders instead).
+// Fallback version roots compose like real routes — \`{basePath}/{locale?}/{id}\`
+// (manifest \`versionAlternates\` paths arrive with the base already applied).
+const versionRootFor = (id: string) => {
+  const logical = id ? \`/\${id}\` : "/";
+  const localized = i18n ? localizeRoute(logical, locale) : logical;
+  const mount = data.config.basePath;
+  if (!mount) {
+    return localized;
+  }
+  return localized === "/" ? mount : \`\${mount}\${localized}\`;
+};
+const samePageSwitch = versionsConfig
+  ? versionsConfig.switcher.redirect === "same-page"
+  : true;
+const userHasVersionSelector = navigation.selectors.some(
+  (selector) => selector.kind === "version"
+);
+const versionSelector =
+  versionsConfig && !userHasVersionSelector
+    ? {
+        items: [
+          {
+            id: "",
+            label: versionsConfig.current.label,
+            tag: versionsConfig.current.badge,
+          },
+          ...versionsConfig.archived.map((v) => ({
+            id: v.id,
+            label: v.label ?? v.id,
+            tag: undefined,
+          })),
+        ].map((entry) => {
+          const alt = (versionAlternates ?? []).find(
+            (a) => a.version === entry.id
+          );
+          return {
+            label: entry.label,
+            path: samePageSwitch && alt ? alt.path : versionRootFor(entry.id),
+            ...(entry.tag ? { tag: entry.tag } : {}),
+          };
+        }),
+        kind: "version" as const,
+        label: ui.versions.switcher,
+      }
+    : null;
+
+const versionNotice =
+  archived && archived.banner !== false
+    ? {
+        latestHref: latestVersionAlt
+          ? latestVersionAlt.path
+          : versionRootFor(""),
+        latestLabel: ui.versions.latest,
+        message:
+          typeof archived.banner === "string"
+            ? archived.banner
+            : ui.versions.notice.replace(
+                "{version}",
+                archived.label ?? archived.id
+              ),
+      }
+    : null;
+
 // The whole page shell is overridable via \`layout.Layout\`; it receives the same
 // props as the built-in RootLayout, plus the \`layout\` map for its inner slots.
 const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
@@ -4760,6 +4883,9 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   localeAlternates={localeAlternates}
   xDefault={xDefault}
   localeSwitch={localeSwitch}
+  versionSelector={versionSelector}
+  versionNotice={versionNotice}
+  searchVersion={versionsConfig ? version : null}
   page={{ title: seo.title ?? title, description: seo.description ?? frontmatter.description, route }}
   headings={headings}
   toc={data.config.toc}
@@ -4782,7 +4908,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   pageType={frontmatter.type}
   published={frontmatter.date ?? frontmatter.changelog?.date ?? null}
   lastModified={lastModified}
-  noindex={seo.noindex}
+  noindex={effectiveNoindex}
   structuredDataEnabled={data.config.structuredData}
 >
   <h1>{title}</h1>
@@ -5467,6 +5593,9 @@ var sitemapParser = new XMLParser({
   parseTagValue: false,
   removeNSPrefix: true
 });
+var isUrlsetElement = (value) => typeof value === "object" && value !== null;
+var isUrlEntry = (value) => typeof value === "object" && value !== null;
+var isText = (value) => typeof value === "string";
 var parseSitemap = (file, xml, bytes) => {
   const doc = { bytes, file, lastmod: new Map, urls: [] };
   let parsed;
@@ -5480,19 +5609,19 @@ var parseSitemap = (file, xml, bytes) => {
     doc.error = Object.hasOwn(parsed, "sitemapindex") ? "sitemap is an index, not a urlset" : "no <urlset> element";
     return doc;
   }
-  const urlset = parsed.urlset;
-  const entries = typeof urlset === "object" && urlset !== null ? [urlset.url].flat() : [];
+  const { urlset } = parsed;
+  const entries = isUrlsetElement(urlset) ? [urlset.url].flat() : [];
   for (const entry of entries) {
-    if (typeof entry !== "object" || entry === null) {
+    if (!isUrlEntry(entry)) {
       continue;
     }
     const { loc, lastmod } = entry;
-    const locText = typeof loc === "string" ? loc.trim() : "";
+    const locText = isText(loc) ? loc.trim() : "";
     if (!locText) {
       continue;
     }
     doc.urls.push(locText);
-    if (typeof lastmod === "string" && lastmod.trim() !== "") {
+    if (isText(lastmod) && lastmod.trim() !== "") {
       doc.lastmod?.set(locText, lastmod.trim());
     }
   }
@@ -5740,6 +5869,7 @@ import { relative as relative10 } from "pathe";
 
 // src/core/config.ts
 import { existsSync as existsSync6, readFileSync as readFileSync3 } from "node:fs";
+import { z as z3 } from "zod";
 
 // src/core/load-module.ts
 import { createJiti } from "jiti";
@@ -5795,8 +5925,9 @@ var resolveProjectContext = (root, config, options) => {
 import { z as z2 } from "zod";
 
 // src/seo/x-handle.ts
+var isString = (value) => typeof value === "string";
 var normalizeXHandle = (value) => {
-  if (typeof value !== "string") {
+  if (!isString(value)) {
     return;
   }
   const handle = value.trim().replace(/^@+/u, "");
@@ -9377,6 +9508,7 @@ var uiStringsObject = z.object({
   search: z.object({
     all: z.string().default("All"),
     allLanguages: z.string().default("All languages"),
+    allVersions: z.string().default("All versions"),
     askAi: z.string().default("Ask AI"),
     askAiHint: z.string().default("Get an instant answer from AI"),
     button: z.string().default("Search"),
@@ -9393,6 +9525,11 @@ var uiStringsObject = z.object({
   }).prefault({}),
   toc: z.object({
     title: z.string().default("On this page")
+  }).prefault({}),
+  versions: z.object({
+    latest: z.string().default("Go to latest"),
+    notice: z.string().default("You're viewing documentation for {version}. It may be out of date."),
+    switcher: z.string().default("Version")
   }).prefault({})
 });
 var uiStringsSchema = uiStringsObject.prefault({});
@@ -9433,12 +9570,16 @@ var resolveUIStrings = (locale, options) => {
 var isStandardSchema = (value) => typeof value === "object" && value !== null && typeof value["~standard"]?.validate === "function";
 
 // src/core/schema.ts
+var isString2 = (value) => typeof value === "string";
+var isBoolean = (value) => typeof value === "boolean";
 var iconName = z2.string().min(1);
 var DEFAULT_CONTENT_GLOB = "**/*.{md,mdx}";
 var hydrationMode = z2.enum(["load", "idle", "visible", "media", "only"]);
 var dateSchema = z2.union([z2.string(), z2.date()]).transform((value) => value instanceof Date ? value.toISOString() : value);
+var sidebarDisplaySchema = z2.enum(["flat", "group", "page"]);
 var sidebarMetaSchema = z2.strictObject({
   badge: z2.string().optional(),
+  display: sidebarDisplaySchema.optional(),
   hidden: z2.boolean().default(false),
   icon: iconName.optional(),
   label: z2.string().optional(),
@@ -9495,11 +9636,12 @@ var pageMetaBaseSchema = z2.strictObject({
   type: z2.string().optional()
 });
 var pageMetaSchema = pageMetaBaseSchema;
+var BUILT_IN_PAGE_META_KEYS = new Set(pageMetaBaseSchema.keyof().options);
 var customKeySchemaRecord = (where) => z2.record(z2.string(), z2.custom(isStandardSchema, {
   message: "Expected a Standard Schema (e.g. a Zod schema — any Zod version works)."
 })).default({}).superRefine((value, ctx) => {
   for (const key of Object.keys(value)) {
-    if (Object.hasOwn(pageMetaBaseSchema.shape, key)) {
+    if (BUILT_IN_PAGE_META_KEYS.has(key)) {
       ctx.addIssue({
         code: z2.ZodIssueCode.custom,
         message: `"${key}" is a built-in frontmatter field and cannot be redeclared via ${where}.`,
@@ -9508,9 +9650,9 @@ var customKeySchemaRecord = (where) => z2.record(z2.string(), z2.custom(isStanda
     }
   }
 });
-var sidebarDisplaySchema = z2.enum(["flat", "group", "page"]);
 var folderMetaSchema = z2.strictObject({
   collapsed: z2.boolean().optional(),
+  display: sidebarDisplaySchema.optional(),
   icon: iconName.optional(),
   order: z2.number().optional(),
   pages: z2.array(z2.string()).optional(),
@@ -9604,7 +9746,7 @@ var githubReleasesSourceSchema = z2.strictObject({
   type: z2.literal("github-releases")
 });
 var customSourceSchema = z2.object({
-  source: z2.custom((val) => typeof val === "object" && val !== null && typeof val.load === "function" && typeof val.name === "string", { message: "custom source must be a ContentSource (with name + load)" }),
+  source: z2.custom((val) => typeof val === "object" && val !== null && ("load" in val) && typeof val.load === "function" && ("name" in val) && typeof val.name === "string", { message: "custom source must be a ContentSource (with name + load)" }),
   type: z2.literal("custom")
 });
 var contentSourceSchema = z2.discriminatedUnion("type", [
@@ -9695,7 +9837,7 @@ var localFontSchema = z2.strictObject({
   variants: z2.array(localFontVariantSchema).nonempty()
 });
 var fontValueSchema = z2.union([z2.string(), remoteFontSchema, localFontSchema]).superRefine((value, ctx) => {
-  if (typeof value === "string" && !isFontSlug(value)) {
+  if (isString2(value) && !isFontSlug(value)) {
     ctx.addIssue({
       code: z2.ZodIssueCode.custom,
       message: `Unknown font "${value}". Supported fonts: ${FONT_SLUGS.join(", ")}. For any other family, use the object form: { name: "..." } (remote provider) or { name: "...", variants: [...] } (local files).`
@@ -9708,12 +9850,12 @@ var perModeValueSchema = z2.union([
     dark: z2.string().optional(),
     light: z2.string().optional()
   })
-]).optional().transform((value) => typeof value === "string" ? { dark: value, light: value } : value);
+]).optional().transform((value) => isString2(value) ? { dark: value, light: value } : value);
 var themeConfigSchema = z2.strictObject({
   accent: z2.union([
     z2.string(),
     z2.strictObject({ dark: z2.string(), light: z2.string() })
-  ]).default("blue").transform((value) => typeof value === "string" ? { dark: value, light: value } : value),
+  ]).default("blue").transform((value) => isString2(value) ? { dark: value, light: value } : value),
   action: z2.string().optional(),
   background: perModeValueSchema,
   backgroundImage: perModeValueSchema,
@@ -9796,7 +9938,7 @@ var askAiProviders = [
 ];
 var PRIVATE_JWK_PARAMS = ["d", "p", "q", "dp", "dq", "qi", "oth", "k"];
 var publicJwkSchema = z2.record(z2.string(), z2.unknown()).superRefine((jwk, ctx) => {
-  if (typeof jwk.kty !== "string" || jwk.kty.length === 0) {
+  if (!isString2(jwk.kty) || jwk.kty.length === 0) {
     ctx.addIssue({
       code: z2.ZodIssueCode.custom,
       message: 'A JWK must declare its key type ("kty").'
@@ -9857,7 +9999,7 @@ var aiConfigSchema = z2.strictObject({
       enabled: z2.boolean().default(true),
       openapi: z2.boolean().default(true)
     })
-  ]).default(true).transform((value) => typeof value === "boolean" ? { enabled: value, openapi: true } : value),
+  ]).default(true).transform((value) => isBoolean(value) ? { enabled: value, openapi: true } : value),
   markdownComponents: z2.record(z2.string(), z2.custom((value) => typeof value === "function", {
     message: "Expected a serializer function."
   })).default({}),
@@ -9892,7 +10034,7 @@ var exportConfigSchema = z2.union([
     epub: z2.boolean().default(false),
     pdf: z2.boolean().default(false)
   })
-]).transform((value) => typeof value === "boolean" ? { epub: value, pdf: value } : value);
+]).transform((value) => isBoolean(value) ? { epub: value, pdf: value } : value);
 var localeSchema = z2.strictObject({
   code: z2.string().min(1),
   dir: z2.enum(["ltr", "rtl"]).default("ltr"),
@@ -9923,6 +10065,36 @@ var i18nConfigSchema = z2.strictObject({
     });
   }
 });
+var VERSION_ID = /^[A-Za-z][\w.-]*$/u;
+var archivedVersionSchema = z2.strictObject({
+  banner: z2.union([z2.boolean(), z2.string()]).default(true),
+  canonical: z2.enum(["latest", "self"]).default("latest"),
+  id: z2.string().regex(VERSION_ID, 'Version ids must start with a letter (e.g. "v1.0") and contain only letters, digits, dots, hyphens, and underscores.'),
+  label: z2.string().optional(),
+  noindex: z2.boolean().default(false)
+});
+var versionsConfigSchema = z2.strictObject({
+  archived: z2.array(archivedVersionSchema).default([]),
+  current: z2.strictObject({
+    badge: z2.string().optional(),
+    label: z2.string()
+  }),
+  switcher: z2.strictObject({
+    redirect: z2.enum(["same-page", "root"]).default("same-page")
+  }).prefault({})
+}).superRefine((value, ctx) => {
+  const seen = new Set;
+  for (const [position, version] of value.archived.entries()) {
+    if (seen.has(version.id)) {
+      ctx.addIssue({
+        code: z2.ZodIssueCode.custom,
+        message: `versions.archived declares "${version.id}" more than once.`,
+        path: ["archived", position, "id"]
+      });
+    }
+    seen.add(version.id);
+  }
+});
 var analyticsScriptSchema = z2.strictObject({
   attributes: z2.record(z2.string(), z2.string()).optional(),
   content: z2.string().optional(),
@@ -10036,18 +10208,18 @@ var githubConfigSchema = z2.strictObject({
   owner: z2.string(),
   repo: z2.string()
 });
+var isThemeObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var codeThemeSchema = z2.custom((value) => {
-  if (typeof value === "string") {
+  if (isString2(value)) {
     return true;
   }
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+  if (!isThemeObject(value)) {
     return false;
   }
-  const theme = value;
-  const settingsValid = theme.settings === undefined || Array.isArray(theme.settings);
-  const tokenColorsValid = theme.tokenColors === undefined || Array.isArray(theme.tokenColors);
-  const colorsValid = theme.colors === undefined || typeof theme.colors === "object" && theme.colors !== null && !Array.isArray(theme.colors);
-  const hasContent = theme.settings !== undefined || theme.tokenColors !== undefined || theme.colors !== undefined;
+  const settingsValid = value.settings === undefined || Array.isArray(value.settings);
+  const tokenColorsValid = value.tokenColors === undefined || Array.isArray(value.tokenColors);
+  const colorsValid = value.colors === undefined || isThemeObject(value.colors);
+  const hasContent = value.settings !== undefined || value.tokenColors !== undefined || value.colors !== undefined;
   return settingsValid && tokenColorsValid && colorsValid && hasContent;
 }, "Expected a Shiki theme name or custom theme object");
 var codeBlockThemeSchema = z2.strictObject({
@@ -10063,7 +10235,7 @@ var examplesConfigSchema = z2.union([
     css: z2.string().optional(),
     source: z2.string().default("examples")
   })
-]).transform((value) => typeof value === "string" ? { source: value } : value);
+]).transform((value) => isString2(value) ? { source: value } : value);
 var lastModifiedConfigSchema = z2.union([
   z2.boolean(),
   z2.strictObject({ type: z2.enum(["git", "frontmatter"]).default("git") })
@@ -10103,24 +10275,24 @@ var openapiSourceSchema = z2.strictObject({
   spec: z2.string()
 });
 var scalarConfigSchema = z2.record(z2.string(), z2.unknown()).optional();
-var openapiConfigSchema = z2.strictObject({
-  codeSamples: z2.array(z2.string()).default(["curl", "js", "python"]),
+var referenceConfigSchema = (defaults) => z2.strictObject({
+  codeSamples: z2.array(z2.string()).default(defaults.codeSamples),
   enabled: z2.boolean().default(false),
   expandSchemas: z2.boolean().default(false),
   renderer: z2.enum(["blume", "scalar"]).default("blume"),
-  route: z2.string().default("/reference"),
+  route: z2.string().default(defaults.route),
   scalar: scalarConfigSchema,
   sources: z2.array(openapiSourceSchema).default([]),
   spec: z2.string().optional(),
   theme: z2.string().optional()
 });
-var asyncapiConfigSchema = z2.strictObject({
-  enabled: z2.boolean().default(false),
-  route: z2.string().default("/events"),
-  scalar: scalarConfigSchema,
-  sources: z2.array(openapiSourceSchema).default([]),
-  spec: z2.string().optional(),
-  theme: z2.string().optional()
+var openapiConfigSchema = referenceConfigSchema({
+  codeSamples: ["curl", "js", "python"],
+  route: "/reference"
+});
+var asyncapiConfigSchema = referenceConfigSchema({
+  codeSamples: [],
+  route: "/events"
 });
 var frontmatterConfigSchema = z2.strictObject({
   extend: customKeySchemaRecord("frontmatter.extend")
@@ -10132,7 +10304,7 @@ var tocConfigSchema = z2.union([
     minHeadingLevel: z2.number().int().min(1).max(6).optional()
   })
 ]).default(true).transform((value) => {
-  if (typeof value === "boolean") {
+  if (isBoolean(value)) {
     return { enabled: value, maxLevel: 3, minLevel: 2 };
   }
   return {
@@ -10172,8 +10344,21 @@ var blumeConfigSchema = z2.strictObject({
   seo: seoConfigSchema.prefault({}),
   theme: themeConfigSchema.prefault({}),
   title: z2.string().default("Documentation"),
-  toc: tocConfigSchema
+  toc: tocConfigSchema,
+  versions: versionsConfigSchema.optional()
 }).superRefine((config, ctx) => {
+  if (config.versions && config.i18n) {
+    const localeCodes = new Set(config.i18n.locales.map((locale) => locale.code.toLowerCase()));
+    for (const [position, version] of config.versions.archived.entries()) {
+      if (localeCodes.has(version.id.toLowerCase())) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          message: `Version id "${version.id}" is also a configured locale code — rename the version (e.g. "v${version.id}").`,
+          path: ["versions", "archived", position, "id"]
+        });
+      }
+    }
+  }
   for (const [typeName, typeConfig] of Object.entries(config.content.types)) {
     for (const key of Object.keys(typeConfig.frontmatter)) {
       if (Object.hasOwn(config.frontmatter.extend, key)) {
@@ -10198,9 +10383,12 @@ var blumeConfigSchema = z2.strictObject({
 
 // src/core/config.ts
 var importConfigModule = createModuleLoader();
+var themeFontsProbeSchema = z3.looseObject({
+  theme: z3.looseObject({ fonts: z3.unknown() }).optional()
+});
 var loadConfig = async (root, options = {}) => {
   const configFile = findConfigFile(root);
-  let raw = {};
+  let raw;
   if (configFile) {
     try {
       raw = await importConfigModule(configFile);
@@ -10213,7 +10401,8 @@ var loadConfig = async (root, options = {}) => {
       });
     }
   }
-  const themeFontsConfigured = Boolean(raw && typeof raw === "object" && raw.theme?.fonts !== undefined);
+  const probe2 = themeFontsProbeSchema.safeParse(raw);
+  const themeFontsConfigured = probe2.success && probe2.data.theme?.fonts !== undefined;
   const parsed = blumeConfigSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const source = configFile && existsSync6(configFile) ? readFileSync3(configFile, "utf-8") : undefined;
@@ -10320,12 +10509,14 @@ var localeTargetPath = (rel, ext, locale, i18n) => {
   }
   return `${locale}/${rel}`;
 };
-var i18nDiagnostics = (pages, i18n) => {
+var i18nDiagnostics = (pages, i18n, versions) => {
   const configured = new Set(i18n.locales.map((locale) => locale.code.toLowerCase()));
+  const versionDirs = new Set(versions?.archived.map((version) => version.id));
   const seen = new Set;
   const diagnostics = [];
   for (const page of pages) {
-    const first = page.source.ref.split("/")[0]?.toLowerCase();
+    const parts = page.source.ref.split("/");
+    const first = (parts[0] && versionDirs.has(parts[0]) ? parts[1] : parts[0])?.toLowerCase();
     if (first && !seen.has(first) && KNOWN_LOCALES.has(first) && !configured.has(first)) {
       seen.add(first);
       diagnostics.push({
@@ -10381,7 +10572,7 @@ var resolveIcon = (name) => {
 var hasIcon = (name) => resolveIcon(name) !== null;
 
 // src/core/nav-diagnostics.ts
-var ICON_SHAPE_HINT = "Use a built-in icon name, an image path/URL, or inline SVG markup.";
+var ICON_FORMAT_HINT = "Use a built-in icon name, an image path/URL, or inline SVG markup.";
 var flattenNodes = (nodes) => nodes.flatMap((node) => node.kind === "group" ? [node, ...flattenNodes(node.children)] : [node]);
 var collectIcons = (navigation) => {
   const icons = [];
@@ -10430,10 +10621,10 @@ var unknownIconDiagnostics = (icons, suggestion) => {
   }
   return diagnostics;
 };
-var validateNavIcons = (navigation) => unknownIconDiagnostics(collectIcons(navigation), ICON_SHAPE_HINT);
+var validateNavIcons = (navigation) => unknownIconDiagnostics(collectIcons(navigation), ICON_FORMAT_HINT);
 var validateSearchPopularIcons = (popular) => {
   const icons = popular.flatMap((link) => link.icon ? [{ icon: link.icon, where: `popular link "${link.label}"` }] : []);
-  return unknownIconDiagnostics(icons, ICON_SHAPE_HINT);
+  return unknownIconDiagnostics(icons, ICON_FORMAT_HINT);
 };
 var resolvesToPages = (routes, path) => routes.has(path) || [...routes].some((route) => route.startsWith(`${path}/`));
 var validateNavTargets = (navigation, routes) => {
@@ -10537,6 +10728,8 @@ var segmentKey = (raw) => {
   return (group ?? raw).replace(NUMERIC_PREFIX, "");
 };
 var isIndexStem = (stem) => stem.replace(NUMERIC_PREFIX, "") === "index";
+var stemOf = (filename) => filename.replace(extname(filename), "");
+var navStem = (navPath) => stemOf(navPath.split("/").at(-1) ?? navPath);
 var createGroup = (key, path, label, order) => ({
   children: [],
   index: new Map,
@@ -10561,7 +10754,7 @@ var pageOrder = (page, filename) => {
   if (page.meta.sidebar.order !== undefined) {
     return { order: page.meta.sidebar.order, orderIsAuthored: true };
   }
-  if (isIndexStem(filename.replace(extname(filename), ""))) {
+  if (isIndexStem(stemOf(filename))) {
     return { order: Number.NEGATIVE_INFINITY, orderIsAuthored: false };
   }
   if (page.contentType === "changelog") {
@@ -10583,8 +10776,9 @@ var metaKey = (path, metaPrefix) => {
   }
   return path ? `${metaPrefix}/${path}` : metaPrefix;
 };
-var applyFolderMeta = (group, folderMeta, sharedMeta, metaPrefix) => {
-  const meta = folderMeta.get(metaKey(group.path, metaPrefix)) ?? sharedMeta.get(group.path);
+var applyFolderMeta = (group, folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix, indexDisplay) => {
+  const meta = folderMeta.get(metaKey(group.path, metaPrefix)) ?? sharedMeta.get(metaKey(group.path, sharedMetaPrefix));
+  group.display = indexDisplay.get(group.path) ?? meta?.display;
   if (meta) {
     group.label = meta.title ?? group.label;
     group.icon = meta.icon ?? group.icon;
@@ -10605,15 +10799,15 @@ var applyFolderMeta = (group, folderMeta, sharedMeta, metaPrefix) => {
   }
   for (const child of group.children) {
     if (child.kind === "group") {
-      applyFolderMeta(child, folderMeta, sharedMeta, metaPrefix);
+      applyFolderMeta(child, folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix, indexDisplay);
     }
   }
 };
-var indexTitleMismatchDiagnostic = (page, folderPath, folderMeta, sharedMeta, metaPrefix) => {
+var indexTitleMismatchDiagnostic = (page, folderPath, folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix) => {
   if (!page.meta.title || page.fallback || folderPath === "") {
     return;
   }
-  const meta = folderMeta.get(metaKey(folderPath, metaPrefix)) ?? sharedMeta.get(folderPath);
+  const meta = folderMeta.get(metaKey(folderPath, metaPrefix)) ?? sharedMeta.get(metaKey(folderPath, sharedMetaPrefix));
   if (!meta?.title || meta.title === page.title) {
     return;
   }
@@ -10625,6 +10819,46 @@ var indexTitleMismatchDiagnostic = (page, folderPath, folderMeta, sharedMeta, me
     suggestion: `Update the page's frontmatter title to match ("${meta.title}"), or leave it if the divergence is intentional.`
   };
 };
+var sidebarDisplayIgnoredDiagnostics = (pages, explicitSidebar) => {
+  const diagnostics = [];
+  for (const page of pages) {
+    if (!page.meta.sidebar.display) {
+      continue;
+    }
+    const isIndex = isIndexStem(navStem(page.navPath));
+    if (explicitSidebar) {
+      diagnostics.push({
+        code: "BLUME_SIDEBAR_DISPLAY_IGNORED",
+        file: page.sourcePath ?? page.id,
+        message: `"${page.navPath}" sets sidebar.display, but the explicit navigation.sidebar config owns each group's display mode — the value is ignored.`,
+        severity: "warning",
+        suggestion: "Set display on the matching group in navigation.sidebar, or remove the frontmatter key."
+      });
+      continue;
+    }
+    if (isIndex && !page.navPath.includes("/")) {
+      diagnostics.push({
+        code: "BLUME_SIDEBAR_DISPLAY_IGNORED",
+        file: page.sourcePath ?? page.id,
+        message: `"${page.navPath}" sets sidebar.display, but the content root is not a sidebar group — the value is ignored.`,
+        severity: "warning",
+        suggestion: "Set navigation.sidebar.display in blume.config to change the sidebar-wide mode."
+      });
+      continue;
+    }
+    if (isIndex) {
+      continue;
+    }
+    diagnostics.push({
+      code: "BLUME_SIDEBAR_DISPLAY_IGNORED",
+      file: page.sourcePath ?? page.id,
+      message: `"${page.navPath}" sets sidebar.display, but only a folder's index page can set its group's display mode — the value is ignored.`,
+      severity: "warning",
+      suggestion: "Move display to the folder's index page frontmatter, or set it in the folder's meta.ts."
+    });
+  }
+  return diagnostics;
+};
 var isAuthoredOrder = (node) => node.kind === "group" || node.orderIsAuthored;
 var duplicateOrderDiagnostics = (nodes) => {
   const byOrder = new Map;
@@ -10671,25 +10905,25 @@ var sortNodes = (nodes, diagnostics) => {
     }
   }
 };
-var hoistPages = (nodes, recurse) => {
-  const pages = nodes.filter((node) => node.kind === "page");
+var hoistPages = (nodes, display, hoist) => {
   const groups = nodes.filter((node) => node.kind === "group");
-  nodes.splice(0, nodes.length, ...pages, ...groups);
-  if (recurse) {
-    for (const group of groups) {
-      hoistPages(group.children, recurse);
-    }
+  if (hoist || groups.some((group) => (group.display ?? display) === "flat")) {
+    const pages = nodes.filter((node) => node.kind === "page");
+    nodes.splice(0, nodes.length, ...pages, ...groups);
+  }
+  for (const group of groups) {
+    hoistPages(group.children, display, false);
   }
 };
-var hoistTabSections = (nodes, tabPaths, recurse) => {
+var hoistTabSections = (nodes, tabPaths, display) => {
   for (const node of nodes) {
     if (node.kind !== "group") {
       continue;
     }
     if (node.routePath !== undefined && tabPaths.has(node.routePath)) {
-      hoistPages(node.children, recurse);
+      hoistPages(node.children, display, true);
     }
-    hoistTabSections(node.children, tabPaths, recurse);
+    hoistTabSections(node.children, tabPaths, display);
   }
 };
 var toNavNode = (node, display) => {
@@ -10708,25 +10942,29 @@ var toNavNode = (node, display) => {
   return {
     children: node.children.map((child) => toNavNode(child, display)),
     collapsed: node.collapsed,
-    display,
+    display: node.display ?? display,
     icon: node.icon,
     kind: "group",
     label: node.label,
     path: node.routePath
   };
 };
-var buildFileSystemSidebar = (pages, folderMeta, sharedMeta, metaPrefix, display, tabPaths, diagnostics = []) => {
+var buildFileSystemSidebar = (pages, folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix, display, tabPaths, diagnostics = []) => {
   const root = createGroup("", "", "", 0);
+  const indexDisplay = new Map;
   for (const page of pages) {
     const parts = page.navPath.split("/");
     const filename = parts.at(-1) ?? page.navPath;
-    const stem = filename.replace(extname(filename), "");
+    const stem = stemOf(filename);
     const dirs = parts.slice(0, -1);
     if (isIndexStem(stem)) {
-      const diagnostic = indexTitleMismatchDiagnostic(page, dirs.join("/"), folderMeta, sharedMeta, metaPrefix);
+      const diagnostic = indexTitleMismatchDiagnostic(page, dirs.join("/"), folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix);
       if (diagnostic) {
         diagnostics.push(diagnostic);
       }
+      if (page.meta.sidebar.display && !page.fallback) {
+        indexDisplay.set(dirs.join("/"), page.meta.sidebar.display);
+      }
     }
     if (page.meta.sidebar.hidden) {
       continue;
@@ -10760,10 +10998,10 @@ var buildFileSystemSidebar = (pages, folderMeta, sharedMeta, metaPrefix, display
       route: page.route
     });
   }
-  applyFolderMeta(root, folderMeta, sharedMeta, metaPrefix);
+  applyFolderMeta(root, folderMeta, sharedMeta, metaPrefix, sharedMetaPrefix, indexDisplay);
   sortNodes(root.children, diagnostics);
-  hoistPages(root.children, display === "flat");
-  hoistTabSections(root.children, tabPaths, display === "flat");
+  hoistPages(root.children, display, true);
+  hoistTabSections(root.children, tabPaths, display);
   return root.children.map((child) => toNavNode(child, display));
 };
 var normalizeRef = (ref) => {
@@ -10782,8 +11020,9 @@ var routeForRef = (ref, byRoute, basePath) => {
   const normalized = normalizeRef(ref);
   return byRoute.get(normalized)?.route ?? withBasePath(basePath, normalized);
 };
+var isPageRef = (item) => typeof item === "string";
 var configItemToNode = (item, byRoute, basePath) => {
-  if (typeof item === "string") {
+  if (isPageRef(item)) {
     const page = byRoute.get(normalizeRef(item));
     if (!page) {
       return null;
@@ -10826,7 +11065,7 @@ var configItemToNode = (item, byRoute, basePath) => {
 var buildConfigSidebar = (items, byRoute, display, basePath) => {
   const nodes = [];
   for (const item of items) {
-    if (typeof item !== "string" && item.items) {
+    if (!isPageRef(item) && item.items) {
       nodes.push({
         badge: item.badge,
         children: buildConfigSidebar(item.items, byRoute, display, basePath),
@@ -10870,29 +11109,46 @@ var withTabHrefs = (tabs, sidebar) => tabs.map((tab) => {
   const href = tab.href ?? resolveTabHref(sidebar, tab.path);
   return href === tab.path ? tab : { ...tab, href };
 });
+var rebaseNavChrome = (basePath, options) => {
+  const featured = options.featured ?? [];
+  const selectors = options.selectors ?? [];
+  const tabs = options.tabs ?? [];
+  if (!basePath) {
+    return { featured, selectors, tabs };
+  }
+  const rebasePath = (item) => ({
+    ...item,
+    path: withBasePath(basePath, item.path)
+  });
+  return {
+    featured: featured.map((link) => ({
+      ...link,
+      href: withBasePath(basePath, link.href)
+    })),
+    selectors: selectors.map((selector) => ({
+      ...selector,
+      items: selector.items.map(rebasePath)
+    })),
+    tabs: tabs.map((tab) => {
+      const rebased = {
+        ...tab,
+        items: tab.items?.map(rebasePath),
+        path: withBasePath(basePath, tab.path)
+      };
+      if (tab.href) {
+        rebased.href = withBasePath(basePath, tab.href);
+      }
+      return rebased;
+    })
+  };
+};
 var buildNavigation = (pages, options) => {
   const basePath = options.basePath ?? "";
   const display = options.display ?? "flat";
   const metaPrefix = options.metaPrefix ?? "";
+  const sharedMetaPrefix = options.sharedMetaPrefix ?? "";
   const sharedFolderMeta = options.sharedFolderMeta ?? new Map;
-  const rebasePath = (item) => ({
-    ...item,
-    path: withBasePath(basePath, item.path)
-  });
-  const featured = basePath ? (options.featured ?? []).map((link) => ({
-    ...link,
-    href: withBasePath(basePath, link.href)
-  })) : options.featured ?? [];
-  const selectors = basePath ? (options.selectors ?? []).map((selector) => ({
-    ...selector,
-    items: selector.items.map(rebasePath)
-  })) : options.selectors ?? [];
-  const tabs = basePath ? (options.tabs ?? []).map((tab) => ({
-    ...tab,
-    ...tab.href ? { href: withBasePath(basePath, tab.href) } : {},
-    items: tab.items?.map(rebasePath),
-    path: withBasePath(basePath, tab.path)
-  })) : options.tabs ?? [];
+  const { featured, selectors, tabs } = rebaseNavChrome(basePath, options);
   const byRoute = new Map(pages.map((page) => [
     options.refByLogical ? page.translationKey : page.route,
     page
@@ -10906,6 +11162,8 @@ var buildNavigation = (pages, options) => {
     }
   }
   const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
+  const diagnostics = options.diagnostics ?? [];
+  diagnostics.push(...sidebarDisplayIgnoredDiagnostics(pages, Boolean(options.sidebar)));
   if (options.sidebar) {
     const sidebar2 = buildConfigSidebar(options.sidebar, byRoute, display, basePath);
     return {
@@ -10916,7 +11174,7 @@ var buildNavigation = (pages, options) => {
       tabs: withTabHrefs(tabs, sidebar2)
     };
   }
-  const sidebar = buildFileSystemSidebar(pages, options.folderMeta, sharedFolderMeta, metaPrefix, display, new Set(tabs.flatMap((tab) => tab.path === rootTabPath ? [] : [tab.path])), options.diagnostics);
+  const sidebar = buildFileSystemSidebar(pages, options.folderMeta, sharedFolderMeta, metaPrefix, sharedMetaPrefix, display, new Set(tabs.flatMap((tab) => tab.path === rootTabPath ? [] : [tab.path])), diagnostics);
   return {
     featured,
     root: rootTabPath,
@@ -10926,6 +11184,44 @@ var buildNavigation = (pages, options) => {
   };
 };
 
+// src/core/versions.ts
+var VERSION_LIKE = /^v\d/iu;
+var detectVersion = (parts, versions) => {
+  const [first] = parts;
+  if (first && versions.archived.some((version) => version.id === first)) {
+    return { rest: parts.slice(1), version: first };
+  }
+  return { rest: parts, version: "" };
+};
+var detectVersionRef = (ref, versions) => {
+  const { version, rest } = detectVersion(ref.split("/"), versions);
+  return { rest: rest.join("/"), version };
+};
+var versionizeRoute = (logicalRoute, version) => {
+  if (!version) {
+    return logicalRoute;
+  }
+  return logicalRoute === "/" ? `/${version}` : `/${version}${logicalRoute}`;
+};
+var versionsDiagnostics = (pages, versions) => {
+  const configured = new Set(versions.archived.map((version) => version.id));
+  const seen = new Set;
+  const diagnostics = [];
+  for (const page of pages) {
+    const [first] = page.source.ref.split("/");
+    if (first && !seen.has(first) && VERSION_LIKE.test(first) && !configured.has(first)) {
+      seen.add(first);
+      diagnostics.push({
+        code: "BLUME_VERSIONS_UNCONFIGURED_VERSION",
+        message: `Folder "${first}/" looks like a version, but "${first}" is not in versions.archived — its pages are treated as current-version content at /${first}/….`,
+        severity: "warning",
+        suggestion: `Add { id: "${first}" } to versions.archived, or rename the folder if it isn't a snapshot.`
+      });
+    }
+  }
+  return diagnostics;
+};
+
 // src/core/graph.ts
 var collectRoutes = (pages) => {
   const routes = new Map;
@@ -10964,8 +11260,9 @@ var localePagesFor = (code, real, fallback, fallbackByKey, i18n, basePath) => {
   }
   return [...real, ...filled];
 };
+var isSingleLabel = (label) => typeof label === "string";
 var resolveLabel = (label, locale, defaultLocale) => {
-  if (typeof label === "string") {
+  if (isSingleLabel(label)) {
     return label;
   }
   return label[locale] ?? (defaultLocale === undefined ? undefined : label[defaultLocale]) ?? Object.values(label)[0] ?? "";
@@ -10978,19 +11275,25 @@ var resolveTabLabels = (tabs, locale, defaultLocale) => (tabs ?? []).map((tab) =
   })),
   label: resolveLabel(tab.label, locale, defaultLocale)
 }));
-var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n, diagnostics) => {
+var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n, diagnostics, version = "") => {
   const localizePath = (path) => path.startsWith("/") ? localizeRoute(path, code, i18n) : path;
-  const tabs = resolveTabLabels(options.navigation.tabs, code, i18n.defaultLocale).map((tab) => ({
-    ...tab,
-    ...tab.href ? { href: localizePath(tab.href) } : {},
-    items: tab.items?.map((item) => ({
-      ...item,
-      path: localizePath(item.path)
-    })),
-    path: localizePath(tab.path)
-  }));
+  const tabs = resolveTabLabels(options.navigation.tabs, code, i18n.defaultLocale).map((tab) => {
+    const localized = {
+      ...tab,
+      items: tab.items?.map((item) => ({
+        ...item,
+        path: localizePath(item.path)
+      })),
+      path: localizePath(tab.path)
+    };
+    if (localized.href) {
+      localized.href = localizePath(localized.href);
+    }
+    return localized;
+  });
   const real = pages.filter((page) => page.locale === code);
   const localePages = localePagesFor(code, real, fallback, fallbackByKey, i18n, options.basePath ?? "");
+  const localeDir = i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "";
   return buildNavigation(localePages, {
     basePath: options.basePath ?? "",
     diagnostics,
@@ -11000,16 +11303,17 @@ var buildLocaleNavigation = (code, pages, fallback, fallbackByKey, options, i18n
       href: localizePath(link.href)
     })),
     folderMeta: options.folderMeta,
-    localizedRoot: localizeRoute("/", code, i18n),
-    metaPrefix: i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "",
+    localizedRoot: localizeRoute(versionizeRoute("/", version), code, i18n),
+    metaPrefix: [version, localeDir].filter(Boolean).join("/"),
     refByLogical: true,
     selectors: options.navigation.selectors,
     sharedFolderMeta: options.sharedFolderMeta,
-    sidebar: options.navigation.sidebar.items,
+    sharedMetaPrefix: version,
+    sidebar: version ? undefined : options.navigation.sidebar.items,
     tabs
   });
 };
-var buildI18nNavigation = (pages, options, i18n, diagnostics) => {
+var buildI18nNavigation = (pages, options, i18n, diagnostics, version = "") => {
   const fallback = resolveFallbackLocale(i18n);
   const fallbackByKey = new Map;
   if (fallback) {
@@ -11023,7 +11327,7 @@ var buildI18nNavigation = (pages, options, i18n, diagnostics) => {
   const seen = new Set;
   for (const { code } of i18n.locales) {
     const localeDiagnostics = [];
-    navigationByLocale[code] = buildLocaleNavigation(code, pages, fallback, fallbackByKey, options, i18n, localeDiagnostics);
+    navigationByLocale[code] = buildLocaleNavigation(code, pages, fallback, fallbackByKey, options, i18n, localeDiagnostics, version);
     for (const diagnostic of localeDiagnostics) {
       const key = `${diagnostic.code}
 ${diagnostic.file ?? ""}
@@ -11042,11 +11346,37 @@ ${diagnostic.message}`;
   };
   return { navigation, navigationByLocale };
 };
+var buildVersionNavigation = (id2, versionPages, options, diagnostics) => {
+  const { i18n } = options;
+  if (i18n) {
+    return buildI18nNavigation(versionPages, options, i18n, diagnostics, id2).navigationByLocale;
+  }
+  return {
+    "": buildNavigation(versionPages, {
+      basePath: options.basePath ?? "",
+      diagnostics,
+      display: options.navigation.sidebar.display,
+      featured: options.navigation.featured,
+      folderMeta: options.folderMeta,
+      localizedRoot: versionizeRoute("/", id2),
+      metaPrefix: id2,
+      selectors: options.navigation.selectors,
+      sharedFolderMeta: options.sharedFolderMeta,
+      sharedMetaPrefix: id2,
+      tabs: resolveTabLabels(options.navigation.tabs, "")
+    })
+  };
+};
 var buildContentGraph = (pages, options) => {
   const { diagnostics, routes } = collectRoutes(pages);
   const { i18n } = options;
-  const { navigation, navigationByLocale } = i18n ? buildI18nNavigation(pages, options, i18n, diagnostics) : {
-    navigation: buildNavigation(pages, {
+  const currentPages = options.versions ? pages.filter((page) => page.version === "") : pages;
+  let navigationByLocale = {};
+  let navigation;
+  if (i18n) {
+    ({ navigation, navigationByLocale } = buildI18nNavigation(currentPages, options, i18n, diagnostics));
+  } else {
+    navigation = buildNavigation(currentPages, {
       basePath: options.basePath ?? "",
       diagnostics,
       display: options.navigation.sidebar.display,
@@ -11056,14 +11386,18 @@ var buildContentGraph = (pages, options) => {
       sharedFolderMeta: options.sharedFolderMeta,
       sidebar: options.navigation.sidebar.items,
       tabs: resolveTabLabels(options.navigation.tabs, "")
-    }),
-    navigationByLocale: {}
-  };
-  diagnostics.push(...validateNavIcons(navigation), ...validateNavStructure(navigation, pages));
+    });
+  }
+  const navigationByVersion = {};
+  for (const { id: id2 } of options.versions?.archived ?? []) {
+    navigationByVersion[id2] = buildVersionNavigation(id2, pages.filter((page) => page.version === id2), options, diagnostics);
+  }
+  diagnostics.push(...validateNavIcons(navigation), ...validateNavStructure(navigation, currentPages));
   return {
     diagnostics,
     navigation,
     navigationByLocale,
+    navigationByVersion,
     pages,
     routes
   };
@@ -11126,9 +11460,20 @@ var gitLastModifiedTimes = (root, contentRoots, sourcePaths) => {
 };
 
 // src/core/manifest.ts
+var versionAlternateKey = (versionKey, locale) => `${versionKey}\x00${locale}`;
+var versionAlternatesFor = (byKey, versionKey, locale) => {
+  const key = versionAlternateKey(versionKey, locale);
+  const existing = byKey.get(key);
+  if (existing) {
+    return existing;
+  }
+  const list2 = [];
+  byKey.set(key, list2);
+  return list2;
+};
 var MANIFEST_VERSION = 1;
 var contentIndexable = (page, config) => !page.meta.search.exclude && (!page.meta.sidebar.hidden || config.search.indexing.includeHiddenPages);
-var buildFallbackRoutes = (graph, i18n, alternatesByKey, basePath) => {
+var buildFallbackRoutes = (graph, i18n, alternatesByKey, basePath, versionAlternatesByKey) => {
   const fallback = resolveFallbackLocale(i18n);
   if (!fallback) {
     return [];
@@ -11144,6 +11489,11 @@ var buildFallbackRoutes = (graph, i18n, alternatesByKey, basePath) => {
       if (present.has(key)) {
         continue;
       }
+      const path = withBasePath(basePath, localizeRoute(key, code, i18n));
+      const versionAlternates = versionAlternatesByKey ? versionAlternatesFor(versionAlternatesByKey, source.versionKey, code) : [];
+      if (versionAlternatesByKey) {
+        versionAlternates.push({ path, version: source.version });
+      }
       routes.push({
         alternates: alternatesByKey.get(key) ?? [],
         collection: source.collection ?? "docs",
@@ -11157,10 +11507,12 @@ var buildFallbackRoutes = (graph, i18n, alternatesByKey, basePath) => {
         indexable: false,
         lastModified: source.lastModified,
         locale: code,
-        path: withBasePath(basePath, localizeRoute(key, code, i18n)),
+        path,
         source: source.source,
         sourcePath: source.sourcePath,
-        title: source.title
+        title: source.title,
+        version: source.version,
+        versionAlternates
       });
     }
   }
@@ -11178,6 +11530,12 @@ var buildManifest = (options) => {
       alternatesByKey.set(page.translationKey, list2);
     }
   }
+  const versionAlternatesByKey = config.versions ? new Map : undefined;
+  if (versionAlternatesByKey) {
+    for (const page of graph.pages) {
+      versionAlternatesFor(versionAlternatesByKey, page.versionKey, page.locale).push({ path: page.route, version: page.version });
+    }
+  }
   const routes = graph.pages.map((page) => ({
     alternates: alternatesByKey.get(page.translationKey) ?? [],
     collection: page.collection ?? "docs",
@@ -11193,10 +11551,18 @@ var buildManifest = (options) => {
     path: page.route,
     source: page.source,
     sourcePath: page.sourcePath,
-    title: page.title
+    title: page.title,
+    version: page.version,
+    versionAlternates: versionAlternatesByKey ? versionAlternatesFor(versionAlternatesByKey, page.versionKey, page.locale) : []
   }));
   if (i18n) {
-    routes.push(...buildFallbackRoutes(graph, i18n, alternatesByKey, config.basePath));
+    routes.push(...buildFallbackRoutes(graph, i18n, alternatesByKey, config.basePath, versionAlternatesByKey));
+  }
+  if (versionAlternatesByKey && config.versions) {
+    const rank = new Map(config.versions.archived.map((version, index) => [version.id, index + 1]));
+    for (const list2 of versionAlternatesByKey.values()) {
+      list2.sort((a, b) => (rank.get(a.version) ?? 0) - (rank.get(b.version) ?? 0));
+    }
   }
   routes.sort((a, b) => a.path.localeCompare(b.path));
   return {
@@ -11220,7 +11586,8 @@ var META_FILES = [
   "**/meta.$.js",
   "**/meta.$.mjs"
 ];
-var resolveMeta = async (mod) => typeof mod === "function" ? await mod() : mod;
+var isMetaFactory = (mod) => typeof mod === "function";
+var resolveMeta = async (mod) => isMetaFactory(mod) ? await mod() : mod;
 var metaKeyFor = (prefix, dir) => {
   const clean = prefix ? prefix.replaceAll(/^\/+|\/+$/gu, "") : "";
   if (!clean) {
@@ -11229,8 +11596,9 @@ var metaKeyFor = (prefix, dir) => {
   return dir ? `${clean}/${dir}` : clean;
 };
 var discoverFolderMeta = async (sources, options = {}) => {
-  const list2 = typeof sources === "string" ? [{ root: sources }] : sources;
+  const list2 = Array.isArray(sources) ? sources : [{ root: sources }];
   const localeDirs = new Set(options.localeDirs);
+  const versionDirs = new Set(options.versionDirs);
   const load2 = createModuleLoader();
   const meta = new Map;
   const shared = new Map;
@@ -11259,7 +11627,12 @@ var discoverFolderMeta = async (sources, options = {}) => {
     for (const entry of loaded) {
       const dir = relative8(source.root, dirname6(entry.file));
       const [head, ...tail] = dir.split("/");
-      const key = head && localeDirs.has(head) ? `${head}/${metaKeyFor(source.prefix, tail.join("/"))}`.replace(/\/$/u, "") : metaKeyFor(source.prefix, dir);
+      const version = head && versionDirs.has(head) ? head : "";
+      const afterVersion = version ? tail : [head ?? "", ...tail];
+      const [localeHead, ...localeTail] = afterVersion;
+      const locale = localeHead && localeDirs.has(localeHead) ? localeHead : "";
+      const rest = (locale ? localeTail : afterVersion).filter(Boolean).join("/");
+      const key = [version, locale, metaKeyFor(source.prefix, rest)].filter(Boolean).join("/");
       if (!entry.ok) {
         diagnostics.push({
           code: "BLUME_META_LOAD_FAILED",
@@ -11331,7 +11704,7 @@ var CODE_FENCE = /^(?<delimiter>```|~~~)/u;
 var nextFenceState = (line, fence) => {
   const trimmed = line.trimStart();
   const delimiter = trimmed.match(CODE_FENCE)?.groups?.delimiter;
-  if (delimiter === undefined) {
+  if (delimiter !== "```" && delimiter !== "~~~") {
     return fence;
   }
   if (fence === null) {
@@ -11527,13 +11900,16 @@ var deriveTitle = (meta, headings, id2) => {
   return titleCase(stripNumericPrefix(base.replace(extname2(base), "")));
 };
 var trimSlashes = (value) => value.replaceAll(/^\/+|\/+$/gu, "");
+var isStringValue = (value) => typeof value === "string";
 var withPrefix = (prefix, path) => {
   const clean = prefix ? trimSlashes(prefix) : "";
   return clean ? `${clean}/${path}` : path;
 };
+var isKeyCarrier = (segment) => typeof segment === "object" && segment !== null;
+var isSymbolKey = (key) => typeof key === "symbol";
 var segmentKey2 = (segment) => {
-  const key = typeof segment === "object" && segment !== null ? segment.key : segment;
-  return typeof key === "symbol" ? String(key) : key;
+  const key = isKeyCarrier(segment) ? segment.key : segment;
+  return isSymbolKey(key) ? String(key) : key;
 };
 var validateCustomKeys = (data, extend) => {
   const custom = {};
@@ -11564,7 +11940,7 @@ var validateCustomKeys = (data, extend) => {
   };
 };
 var parseEntryMeta = (entry, ctx) => {
-  const entryType = typeof entry.data.type === "string" ? entry.data.type : ctx.defaultType;
+  const entryType = isStringValue(entry.data.type) ? entry.data.type : ctx.defaultType;
   const typeExtend = ctx.typeFrontmatter?.[entryType];
   const extend = ctx.frontmatterExtend || typeExtend ? { ...ctx.frontmatterExtend, ...typeExtend } : undefined;
   const known = extend ? Object.fromEntries(Object.entries(entry.data).filter(([key]) => !Object.hasOwn(extend, key))) : entry.data;
@@ -11600,13 +11976,16 @@ var normalizeEntry = (entry, ctx) => {
   if (meta.noindex) {
     meta.seo.noindex = true;
   }
+  const { versions } = ctx;
+  const { version, rest: versionlessRef } = versions ? detectVersionRef(entry.ref, versions) : { rest: entry.ref, version: "" };
   const { i18n } = ctx;
-  const { navPath: rawNavPath, locales } = i18n ? localePlacement(entry.ref, ext, i18n) : { locales: [""], navPath: entry.ref };
+  const { navPath: rawNavPath, locales } = i18n ? localePlacement(versionlessRef, ext, i18n) : { locales: [""], navPath: versionlessRef };
   const navPath = withPrefix(ctx.source.prefix, rawNavPath);
   const slugInput = meta.slug ?? entry.slug;
   const slug = slugInput ? trimSlashes(slugInput) : "";
   const routeInput = withPrefix(ctx.source.prefix, slug ? `${slug}${ext}` : rawNavPath);
-  const { segments, groups, route: logicalRoute } = mapRoute(routeInput);
+  const { segments, groups, route: versionKey } = mapRoute(routeInput);
+  const logicalRoute = versionizeRoute(versionKey, version);
   const headings = extractHeadings(entry.body.text);
   const { staged } = ctx.source;
   const base = {
@@ -11630,7 +12009,9 @@ var normalizeEntry = (entry, ctx) => {
     source: { name: ctx.source.name, ref: entry.ref },
     sourcePath: entry.sourcePath,
     title: deriveTitle(meta, headings, navPath),
-    translationKey: logicalRoute
+    translationKey: logicalRoute,
+    version,
+    versionKey
   };
   const pages = locales.map((locale) => ({
     ...base,
@@ -11740,6 +12121,7 @@ var operationKey = (method, path, operationId) => {
   return fromId || slugify(`${method}-${path}`);
 };
 var isOperation = (value) => typeof value === "object" && value !== null;
+var hasTagName = (tag) => typeof tag.name === "string";
 var tagSlugger = () => {
   const assigned = new Map;
   const taken = new Set;
@@ -11758,16 +12140,45 @@ var tagSlugger = () => {
     return slug;
   };
 };
-var extractOperations = (document, baseRoute) => {
+var operationCollector = (baseRoute, tagMeta) => {
   const operations = [];
   const tagOrder = [];
   const tagsSeen = new Set;
-  const tagMeta = new Map((document.tags ?? []).map((tag) => [tag.name, tag.description ?? ""]));
   const seen = new Set;
-  const warnings = [];
   const slugForTag = tagSlugger();
-  for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
-    const item = rawItem;
+  const add2 = (entry) => {
+    const tagSlug = slugForTag(entry.tag);
+    if (!tagsSeen.has(entry.tag)) {
+      tagsSeen.add(entry.tag);
+      tagOrder.push(entry.tag);
+    }
+    let { key } = entry;
+    while (seen.has(key)) {
+      key = `${key}-${entry.method}`;
+    }
+    seen.add(key);
+    operations.push({
+      ...entry,
+      key,
+      route: `${baseRoute === "/" ? "" : baseRoute}/${tagSlug}/${key}`,
+      tagSlug
+    });
+  };
+  const finish = () => ({
+    operations,
+    tags: tagOrder.map((name) => ({
+      description: tagMeta.get(name) ?? "",
+      name,
+      slug: slugForTag(name)
+    }))
+  });
+  return { add: add2, finish };
+};
+var extractOperations = (document, baseRoute) => {
+  const warnings = [];
+  const tagMeta = new Map((document.tags ?? []).filter(hasTagName).map((tag) => [tag.name, tag.description ?? ""]));
+  const collector = operationCollector(baseRoute, tagMeta);
+  for (const [path, item] of Object.entries(document.paths ?? {})) {
     if (!item) {
       continue;
     }
@@ -11780,42 +12191,171 @@ var extractOperations = (document, baseRoute) => {
       if (!isOperation(operation)) {
         continue;
       }
-      const tag = operation.tags?.[0] ?? UNTAGGED;
-      const tagSlug = slugForTag(tag);
-      if (!tagsSeen.has(tag)) {
-        tagsSeen.add(tag);
-        tagOrder.push(tag);
-      }
-      let key = operationKey(method, path, operation.operationId);
-      while (seen.has(key)) {
-        key = `${key}-${method}`;
-      }
-      seen.add(key);
-      operations.push({
+      collector.add({
         deprecated: operation.deprecated ?? false,
         description: operation.description ?? "",
-        key,
+        key: operationKey(method, path, operation.operationId),
         method,
         operationId: operation.operationId,
         path,
-        route: `${baseRoute === "/" ? "" : baseRoute}/${tagSlug}/${key}`,
         summary: operation.summary ?? "",
-        tag,
-        tagSlug
+        tag: operation.tags?.[0] ?? UNTAGGED
       });
     }
   }
-  const tags = tagOrder.map((name) => ({
-    description: tagMeta.get(name) ?? "",
-    name,
-    slug: slugForTag(name)
-  }));
-  return { operations, tags, warnings };
+  return { ...collector.finish(), warnings };
+};
+
+// src/openapi/asyncapi.ts
+var ASYNCAPI_ACTIONS = ["send", "receive"];
+var unescapePointer = (token) => token.replaceAll("~1", "/").replaceAll("~0", "~");
+var CHANNEL_REF = /^#\/channels\/(?<id>.+)$/u;
+var isString3 = (value) => typeof value === "string";
+var channelIdOf = (channel) => {
+  const id2 = CHANNEL_REF.exec(channel?.$ref ?? "")?.groups?.id;
+  return id2 === undefined ? undefined : unescapePointer(id2);
+};
+var channelAddress = (channelId, channel) => {
+  const address = channel?.address;
+  return isString3(address) && address !== "" ? address : channelId;
+};
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var COMPONENT_SECTION_REF = /^#\/components\/(?<section>channels|operations)\/(?<name>[^/]+)$/u;
+var inlineComponentRefs = (document) => {
+  const maps = [
+    [document.channels, "channels"],
+    [document.operations, "operations"]
+  ];
+  for (const [map, section] of maps) {
+    if (!isObject(map)) {
+      continue;
+    }
+    const table = document.components?.[section];
+    for (const [id2, entry] of Object.entries(map)) {
+      if (!isObject(entry) || !isString3(entry.$ref)) {
+        continue;
+      }
+      const groups = COMPONENT_SECTION_REF.exec(entry.$ref)?.groups;
+      if (groups?.section !== section) {
+        continue;
+      }
+      const resolved = isObject(table) ? table[unescapePointer(groups.name ?? "")] : undefined;
+      if (isObject(resolved) && !isString3(resolved.$ref)) {
+        map[id2] = resolved;
+      }
+    }
+  }
+};
+var TRAIT_REF = /^#\/components\/(?<section>operationTraits|messageTraits)\/(?<name>[^/]+)$/u;
+var applyAsyncApiTraits = (document) => {
+  const resolveTrait = (trait) => {
+    if (!isObject(trait)) {
+      return;
+    }
+    if (!isString3(trait.$ref)) {
+      return trait;
+    }
+    const groups = TRAIT_REF.exec(trait.$ref)?.groups;
+    const section = groups?.section ? document.components?.[groups.section] : undefined;
+    const resolved = section?.[groups?.name ?? ""];
+    return isObject(resolved) ? resolved : undefined;
+  };
+  const mergeTraits = (node) => {
+    const { traits } = node;
+    if (!Array.isArray(traits)) {
+      return;
+    }
+    delete node.traits;
+    const merged = {};
+    for (const trait of traits) {
+      Object.assign(merged, resolveTrait(trait));
+    }
+    for (const [key, value] of Object.entries(merged)) {
+      if (!(key in node)) {
+        node[key] = value;
+      }
+    }
+  };
+  for (const operation of Object.values(document.operations ?? {})) {
+    if (isObject(operation)) {
+      mergeTraits(operation);
+    }
+  }
+  const channelMaps = [
+    ...Object.values(document.channels ?? {}),
+    ...Object.values(document.components?.channels ?? {})
+  ];
+  const messageMaps = [
+    ...channelMaps.map((channel) => isObject(channel) ? channel.messages : undefined),
+    document.components?.messages
+  ];
+  for (const messages of messageMaps) {
+    if (!isObject(messages)) {
+      continue;
+    }
+    for (const message of Object.values(messages)) {
+      if (isObject(message) && !isString3(message.$ref)) {
+        mergeTraits(message);
+      }
+    }
+  }
+  return document;
+};
+var normalizeAsyncApiDocument = (document) => {
+  inlineComponentRefs(document);
+  return applyAsyncApiTraits(document);
+};
+var operationSite = (id2, operation, channels) => {
+  const action = ASYNCAPI_ACTIONS.find((a) => a === operation.action);
+  if (!action) {
+    return `Operation "${id2}" declares no send/receive action; it is missing from the reference.`;
+  }
+  const channelId = channelIdOf(operation.channel);
+  const channel = channelId === undefined ? undefined : channels[channelId];
+  if (channelId === undefined || !isObject(channel) || isString3(channel.$ref)) {
+    return `Operation "${id2}" references a channel that isn't declared under "channels"; it is missing from the reference.`;
+  }
+  return { action, address: channelAddress(channelId, channel), channelId };
+};
+var extractAsyncApiOperations = (document, baseRoute) => {
+  const warnings = [];
+  const tagMeta = new Map((document.info?.tags ?? []).filter((tag) => typeof tag?.name === "string").map((tag) => [tag.name, tag.description ?? ""]));
+  const collector = operationCollector(baseRoute, tagMeta);
+  const channels = document.channels ?? {};
+  for (const [id2, operation] of Object.entries(document.operations ?? {})) {
+    if (!isObject(operation)) {
+      continue;
+    }
+    if (isString3(operation.$ref)) {
+      warnings.push(`Operation "${id2}" is a reference that doesn't resolve to a components operation; it is missing from the reference.`);
+      continue;
+    }
+    const site = operationSite(id2, operation, channels);
+    if (isString3(site)) {
+      warnings.push(site);
+      continue;
+    }
+    const { action, address, channelId } = site;
+    const tag = operation.tags?.find((candidate) => typeof candidate?.name === "string")?.name;
+    collector.add({
+      channelId,
+      deprecated: operation.deprecated === true,
+      description: operation.description ?? "",
+      key: operationKey(action, address, id2),
+      method: action,
+      operationId: id2,
+      path: address,
+      summary: operation.title ?? operation.summary ?? "",
+      tag: tag ?? address
+    });
+  }
+  return { ...collector.finish(), warnings };
 };
 
 // src/openapi/parse.ts
 import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile4 } from "node:fs/promises";
 import { setTimeout as sleep } from "node:timers/promises";
+import { convert } from "@asyncapi/converter";
 import { normalize as normalize2, upgrade } from "@scalar/openapi-parser";
 import pRetry, { AbortError } from "p-retry";
 import { isAbsolute as isAbsolute3, join as join12 } from "pathe";
@@ -11969,27 +12509,74 @@ var readSpecText = async (spec, root, options) => {
     throw error;
   }
 };
+var isApiDocument = (value) => typeof value === "object" && value !== null;
 var parseSpec = async (spec, root, options = {}) => {
   const { text, warnings } = await readSpecText(spec, root, options);
   const normalized = normalize2(text);
   const { specification } = upgrade(normalized);
-  if (specification === null || typeof specification !== "object") {
+  if (!isApiDocument(specification)) {
     throw new InvalidSpecError(`${spec} is not a valid OpenAPI document (expected a YAML or JSON object).`);
   }
   return { document: specification, warnings };
 };
+var isAsyncApiDocument = (value) => typeof value === "object" && value !== null && ("asyncapi" in value) && typeof value.asyncapi === "string" && value.asyncapi !== "";
+var parseAsyncApiSpec = async (spec, root, options = {}) => {
+  const { text, warnings } = await readSpecText(spec, root, options);
+  const normalized = normalize2(text);
+  if (!isAsyncApiDocument(normalized)) {
+    throw new InvalidSpecError(`${spec} is not a valid AsyncAPI document (expected a YAML or JSON object with an \`asyncapi\` version field).`);
+  }
+  const version = normalized.asyncapi;
+  let document = normalized;
+  if (!version.startsWith("3.")) {
+    const captured = [];
+    const originalWarn = console.warn;
+    console.warn = (...args) => {
+      captured.push(args.map(String).join(" "));
+    };
+    try {
+      document = convert(document, "3.0.0");
+    } catch (error) {
+      throw new InvalidSpecError(`${spec} could not be converted to AsyncAPI 3.0 (${error.message}).`);
+    } finally {
+      console.warn = originalWarn;
+    }
+    warnings.push(...captured.map((message) => `Converting ${spec} to AsyncAPI 3.0: ${message}`));
+  }
+  return { document: normalizeAsyncApiDocument(document), warnings };
+};
 
 // src/openapi/render-mdx.ts
 import { fromMarkdown as fromMarkdown2 } from "mdast-util-from-markdown";
 import { toString as mdastToString } from "mdast-util-to-string";
-var MDX_UNSAFE = /[<{}]/gu;
-var ENTITIES = {
-  "<": "&lt;",
-  "{": "&#123;",
-  "}": "&#125;"
+import stringWidth3 from "string-width";
+
+// src/core/text-width.ts
+import stringWidth2 from "string-width";
+var columnsPrefix = (text, max) => {
+  let end = 0;
+  let used = 0;
+  const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+  for (const { index, segment } of graphemes.segment(text)) {
+    const width = stringWidth2(segment);
+    if (used + width > max) {
+      break;
+    }
+    used += width;
+    end = index + segment.length;
+  }
+  return text.slice(0, end);
 };
+
+// src/openapi/render-mdx.ts
+var MDX_UNSAFE = /[<{}]/gu;
+var ENTITIES = new Map([
+  ["<", "&lt;"],
+  ["{", "&#123;"],
+  ["}", "&#125;"]
+]);
 var MDX_ESM_KEYWORD = /^(?<keyword>import|export)\b/gmu;
-var escapeProse = (text) => text.replace(MDX_UNSAFE, (char) => ENTITIES[char] ?? char).replace(MDX_ESM_KEYWORD, (keyword) => `&#${keyword.codePointAt(0)};${keyword.slice(1)}`);
+var escapeProse = (text) => text.replace(MDX_UNSAFE, (char) => ENTITIES.get(char) ?? char).replace(MDX_ESM_KEYWORD, (keyword) => `&#${keyword.codePointAt(0)};${keyword.slice(1)}`);
 var codeSpans = (text) => {
   const spans = [];
   const collect = (node) => {
@@ -12022,29 +12609,28 @@ var mdxSafe = (text) => {
   return out + escapeProse(text.slice(cursor));
 };
 var META_DESCRIPTION_MAX = 160;
-var WHITESPACE = /\s+/gu;
+var WHITESPACE2 = /\s+/gu;
 var TRAILING_WORD = /\s+\S*$/u;
 var plainProse = (markdown) => {
   const tree = fromMarkdown2(markdown);
   const first = tree.children.find((node) => node.type === "paragraph") ?? tree.children[0];
-  return first ? mdastToString(first).replace(WHITESPACE, " ").trim() : "";
+  return first ? mdastToString(first).replace(WHITESPACE2, " ").trim() : "";
 };
 var clip = (text, max) => {
   if (max <= 0) {
     return "";
   }
-  if (text.length <= max) {
+  if (stringWidth3(text) <= max) {
     return text;
   }
-  const head = text.slice(0, max - 1);
+  const head = columnsPrefix(text, max - 1);
   const onWordBoundary = head.replace(TRAILING_WORD, "");
-  return `${onWordBoundary.length >= max / 2 ? onWordBoundary : head}…`;
+  return `${stringWidth3(onWordBoundary) >= max / 2 ? onWordBoundary : head}…`;
 };
 var apiName = (spec) => spec.title || spec.label;
 var operationDescription = (spec, operation) => {
-  const endpoint = `${operation.method.toUpperCase()} ${operation.path}`;
-  const suffix = `Reference for the ${endpoint} endpoint in the ${apiName(spec)} API.`;
-  const prose = clip(plainProse(operation.description || operation.summary), META_DESCRIPTION_MAX - suffix.length - 1);
+  const suffix = spec.kind === "asyncapi" ? `Reference for the ${operation.method} operation on ${operation.path} in the ${apiName(spec)} API.` : `Reference for the ${operation.method.toUpperCase()} ${operation.path} endpoint in the ${apiName(spec)} API.`;
+  const prose = clip(plainProse(operation.description || operation.summary), META_DESCRIPTION_MAX - stringWidth3(suffix) - 1);
   return clip([prose, suffix].filter(Boolean).join(" "), META_DESCRIPTION_MAX);
 };
 var withDescription = (description, component) => description.trim() ? `${mdxSafe(description.trim())}
@@ -12054,19 +12640,29 @@ var operationMdx = (spec, operation, reference) => {
   const method = operation.method.toUpperCase();
   const title = operation.summary || `${method} ${operation.path}`;
   const description = operation.description.trim() === operation.summary.trim() ? "" : operation.description;
-  return {
-    body: withDescription(description, `<Operation source="${spec.slug}" id="${operation.key}" />`),
+  const flags = {};
+  if (reference?.includeInLlms === false) {
+    flags.ai = { exclude: true };
+  }
+  if (operation.deprecated) {
+    flags.deprecated = true;
+  }
+  const searchFlags = {};
+  if (reference?.includeInSearch === false) {
+    searchFlags.exclude = true;
+  }
+  const seo = {
+    description: operationDescription(spec, operation)
+  };
+  if (reference?.noindex) {
+    seo.noindex = true;
+  }
+  return {
+    body: withDescription(description, `<Operation source="${spec.slug}" id="${operation.key}" />`),
     data: {
-      ...reference?.includeInLlms === false ? { ai: { exclude: true } } : {},
-      ...operation.deprecated ? { deprecated: true } : {},
-      search: {
-        ...reference?.includeInSearch === false ? { exclude: true } : {},
-        tags: [operation.tag, method]
-      },
-      seo: {
-        description: operationDescription(spec, operation),
-        ...reference?.noindex ? { noindex: true } : {}
-      },
+      ...flags,
+      search: { ...searchFlags, tags: [operation.tag, method] },
+      seo,
       sidebar: { badge: method, label: operation.summary || operation.path },
       title,
       type: "openapi-operation"
@@ -12107,6 +12703,19 @@ var overviewMdx = (spec, reference) => {
 
 `));
   }
+  const flags = {};
+  if (reference?.includeInLlms === false) {
+    flags.ai = { exclude: true };
+  }
+  if (reference?.includeInSearch === false) {
+    flags.search = { exclude: true };
+  }
+  const seo = {
+    description: clip(plainProse(spec.description), META_DESCRIPTION_MAX) || `${apiName(spec)} API reference.`
+  };
+  if (reference?.noindex) {
+    seo.noindex = true;
+  }
   return {
     body: [
       withDescription(spec.description, `<ApiOverview source="${spec.slug}" />`),
@@ -12115,12 +12724,8 @@ var overviewMdx = (spec, reference) => {
 
 `),
     data: {
-      ...reference?.includeInLlms === false ? { ai: { exclude: true } } : {},
-      ...reference?.includeInSearch === false ? { search: { exclude: true } } : {},
-      seo: {
-        description: clip(plainProse(spec.description), META_DESCRIPTION_MAX) || `${apiName(spec)} API reference.`,
-        ...reference?.noindex ? { noindex: true } : {}
-      },
+      ...flags,
+      seo,
       sidebar: { label: "Overview" },
       title: apiName(spec)
     }
@@ -12128,14 +12733,14 @@ var overviewMdx = (spec, reference) => {
 };
 
 // src/openapi/source.ts
-var isOpenApiSource = (source) => source.kind === "openapi-source";
+var isOpenApiSource = (source) => ("kind" in source) && source.kind === "openapi-source";
 var routeToRef = (route) => route.replace(/^\/+/u, "");
 var toEntry = (rendered, ref) => {
   const raw = frontmatter_default.stringify(`${rendered.body}
 `, rendered.data);
   return {
     body: { format: "mdx", text: rendered.body },
-    data: rendered.data,
+    data: { ...rendered.data },
     hash: hashText(raw),
     raw,
     ref
@@ -12154,22 +12759,43 @@ var tagFolderMeta = (spec, tags) => {
     { title: tag.name }
   ]));
 };
+var parseReference = async (reference, ctx) => {
+  const options = { cacheDir: ctx.cacheDir, refresh: ctx.refresh };
+  if (reference.kind === "asyncapi") {
+    const { document: document2, warnings: warnings2 } = await parseAsyncApiSpec(reference.spec, ctx.projectRoot, options);
+    const extracted2 = extractAsyncApiOperations(document2, reference.route);
+    return {
+      document: document2,
+      extractWarnings: extracted2.warnings,
+      operations: extracted2.operations,
+      tags: extracted2.tags,
+      warnings: warnings2
+    };
+  }
+  const { document, warnings } = await parseSpec(reference.spec, ctx.projectRoot, options);
+  const extracted = extractOperations(document, reference.route);
+  return {
+    document,
+    extractWarnings: extracted.warnings,
+    operations: extracted.operations,
+    tags: extracted.tags,
+    warnings
+  };
+};
 var openApiSource = (references, ctx) => {
   let parsed = {};
   const loadReference = async (reference) => {
+    const kindLabel = reference.kind === "asyncapi" ? "AsyncAPI" : "OpenAPI";
+    const codePrefix = reference.kind === "asyncapi" ? "BLUME_ASYNCAPI" : "BLUME_OPENAPI";
     try {
-      const { document, warnings } = await parseSpec(reference.spec, ctx.projectRoot, { cacheDir: ctx.cacheDir, refresh: ctx.refresh });
-      const {
-        operations,
-        tags,
-        warnings: extractWarnings
-      } = extractOperations(document, reference.route);
+      const { document, warnings, operations, tags, extractWarnings } = await parseReference(reference, ctx);
       const info = document.info ?? { title: reference.label, version: "" };
       const spec = {
         codeSamples: reference.display.codeSamples,
         description: info.description ?? "",
         document,
         expandSchemas: reference.display.expandSchemas,
+        kind: reference.kind,
         label: reference.label,
         operations: Object.fromEntries(operations.map((operation) => [
           operation.key,
@@ -12187,21 +12813,21 @@ var openApiSource = (references, ctx) => {
       return {
         diagnostics: [
           ...warnings.map((message) => ({
-            code: "BLUME_OPENAPI_STALE",
+            code: reference.kind === "asyncapi" ? "BLUME_ASYNCAPI_SPEC_WARNING" : "BLUME_OPENAPI_STALE",
             message,
             severity: "warning"
           })),
           ...extractWarnings.map((message) => ({
-            code: "BLUME_OPENAPI_REF_PATH_ITEM",
-            message: `In OpenAPI spec "${reference.spec}": ${message}`,
+            code: reference.kind === "asyncapi" ? "BLUME_ASYNCAPI_SKIPPED_OPERATION" : "BLUME_OPENAPI_REF_PATH_ITEM",
+            message: `In ${kindLabel} spec "${reference.spec}": ${message}`,
             severity: "warning"
           })),
           ...operations.length === 0 ? [
             {
-              code: "BLUME_OPENAPI_EMPTY",
-              message: `OpenAPI spec "${reference.spec}" for ${reference.route} declares no operations; its API reference is empty.`,
+              code: `${codePrefix}_EMPTY`,
+              message: `${kindLabel} spec "${reference.spec}" for ${reference.route} declares no operations; its API reference is empty.`,
               severity: "warning",
-              suggestion: "Check the spec points at an OpenAPI document with operations under `paths`."
+              suggestion: reference.kind === "asyncapi" ? "Check the spec points at an AsyncAPI document with `channels` and `operations`." : "Check the spec points at an OpenAPI document with operations under `paths`."
             }
           ] : []
         ],
@@ -12212,10 +12838,10 @@ var openApiSource = (references, ctx) => {
       };
     } catch (error) {
       return {
-        code: "BLUME_OPENAPI_UNAVAILABLE",
-        message: `Could not load OpenAPI spec "${reference.spec}" for ${reference.route} (${error.message}); its reference pages were skipped.`,
+        code: `${codePrefix}_UNAVAILABLE`,
+        message: `Could not load ${kindLabel} spec "${reference.spec}" for ${reference.route} (${error.message}); its reference pages were skipped.`,
         severity: ctx.mode === "build" ? "error" : "warning",
-        suggestion: error instanceof InvalidSpecError ? "Point the spec at an OpenAPI document (a YAML or JSON file with an object at the top level)." : "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY."
+        suggestion: error instanceof InvalidSpecError ? `Point the spec at ${reference.kind === "asyncapi" ? "an AsyncAPI" : "an OpenAPI"} document (a YAML or JSON file with an object at the top level).` : "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY."
       };
     }
   };
@@ -12320,6 +12946,7 @@ import { fromMarkdown as fromMarkdown3 } from "mdast-util-from-markdown";
 import { gfmFromMarkdown } from "mdast-util-gfm";
 import { toString as mdastToString2 } from "mdast-util-to-string";
 import { gfm } from "micromark-extension-gfm";
+import stringWidth4 from "string-width";
 var DEFAULT_BASE_URL = "https://api.github.com";
 var DEFAULT_LIMIT = 100;
 var PER_PAGE = 100;
@@ -12329,35 +12956,24 @@ var EDGE_DASHES = /^-+|-+$/gu;
 var DESCRIPTION_MAX = 160;
 var DESCRIPTION_MIN = 110;
 var CHANGESET_HASH = /^(?<mark>\s*(?:[-*+]|\d+[.)])\s+)[0-9a-f]{7,40}:\s+/gmu;
-var WHITESPACE2 = /\s+/gu;
+var WHITESPACE3 = /\s+/gu;
 var TRAILING_FRAGMENT = /[\s,;:.—–-]+$/u;
 var NON_PROSE = new Set(["code", "heading", "html", "thematicBreak"]);
-var graphemePrefix = (text, max) => {
-  let end = 0;
-  const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
-  for (const { index, segment } of graphemes.segment(text)) {
-    if (index + segment.length > max) {
-      break;
-    }
-    end = index + segment.length;
-  }
-  return text.slice(0, end);
-};
 var releaseDescription = (body) => {
   const tree = fromMarkdown3(body.replaceAll(CHANGESET_HASH, "$<mark>"), {
     extensions: [gfm()],
     mdastExtensions: [gfmFromMarkdown()]
   });
-  const text = tree.children.filter((node) => !NON_PROSE.has(node.type)).map((node) => mdastToString2(node, { includeHtml: false, includeImageAlt: false })).join(" ").replaceAll(WHITESPACE2, " ").trim();
+  const text = tree.children.filter((node) => !NON_PROSE.has(node.type)).map((node) => mdastToString2(node, { includeHtml: false, includeImageAlt: false })).join(" ").replaceAll(WHITESPACE3, " ").trim();
   if (!text) {
     return;
   }
-  if (text.length <= DESCRIPTION_MAX) {
+  if (stringWidth4(text) <= DESCRIPTION_MAX) {
     return text;
   }
-  const slice = graphemePrefix(text, DESCRIPTION_MAX - 1);
+  const slice = columnsPrefix(text, DESCRIPTION_MAX - 1);
   const boundary = slice.lastIndexOf(" ");
-  const head = (boundary >= DESCRIPTION_MIN ? slice.slice(0, boundary) : slice).replace(TRAILING_FRAGMENT, "");
+  const head = (boundary !== -1 && stringWidth4(slice.slice(0, boundary)) >= DESCRIPTION_MIN ? slice.slice(0, boundary) : slice).replace(TRAILING_FRAGMENT, "");
   return `${head}…`;
 };
 var slugifyTag = (tag) => tag.toLowerCase().replaceAll(NON_SLUG2, "-").replaceAll(EDGE_DASHES, "");
@@ -12380,18 +12996,20 @@ var releaseToEntry = (release) => {
   const description = releaseDescription(body);
   const data = {
     changelog: { category, version },
-    date,
-    ...description ? { seo: { description } } : {},
-    title,
-    type: "changelog"
+    date
   };
+  if (description) {
+    data.seo = { description };
+  }
+  data.title = title;
+  data.type = "changelog";
   const raw = frontmatter_default.stringify(`${body}
 `, data);
   const fallbackRef = `release-${release.id}`;
   const ref = `${slugifyTag(release.tag_name) || fallbackRef}.md`;
   return {
     body: { format: "md", text: body },
-    data,
+    data: { ...data },
     editUrl: release.html_url,
     hash: hashText(raw),
     lastModified: date,
@@ -12688,7 +13306,12 @@ var richToMarkdown = (rich = []) => rich.map((node) => {
   }
   return node.href ? `[${text}](${node.href})` : text;
 }).join("");
-var blockField = (block) => block[block.type]?.rich_text ?? [];
+var isBlockPayload = (value) => typeof value === "object";
+var payloadOf = (block) => {
+  const value = block[block.type];
+  return isBlockPayload(value) ? value : undefined;
+};
+var blockField = (block) => payloadOf(block)?.rich_text ?? [];
 var RATE_LIMITED = 429;
 var MAX_RETRIES = 4;
 var BASE_DELAY_MS = 500;
@@ -12720,7 +13343,7 @@ var LIST_BLOCKS = new Set([
 ]);
 var isListItem = (block) => block !== undefined && LIST_BLOCKS.has(block.type);
 var renderLeaf = (block) => {
-  const data = block[block.type] ?? {};
+  const data = payloadOf(block) ?? {};
   const text = richToMarkdown(blockField(block));
   switch (block.type) {
     case "paragraph": {
@@ -12756,9 +13379,8 @@ ${text}
 \`\`\``;
     }
     case "image": {
-      const media = data;
-      const url = media.external?.url ?? media.file?.url;
-      return url ? `![${richToMarkdown(media.caption)}](${url})` : "";
+      const url = data.external?.url ?? data.file?.url;
+      return url ? `![${richToMarkdown(data.caption)}](${url})` : "";
     }
     default: {
       return null;
@@ -12878,7 +13500,7 @@ ${nested}`;
   };
   const orderOf = (page) => {
     const order = page.properties[props.order ?? "Order"]?.number;
-    return typeof order === "number" ? order : undefined;
+    return order === null ? undefined : order;
   };
   const frontmatter = (page) => {
     const data = {};
@@ -12965,14 +13587,14 @@ ${nested}`;
 import { join as join16 } from "pathe";
 
 // src/core/sources/portable-text.ts
-var HEADING_STYLES = {
-  h1: "# ",
-  h2: "## ",
-  h3: "### ",
-  h4: "#### ",
-  h5: "##### ",
-  h6: "###### "
-};
+var HEADING_STYLES = new Map([
+  ["h1", "# "],
+  ["h2", "## "],
+  ["h3", "### "],
+  ["h4", "#### "],
+  ["h5", "##### "],
+  ["h6", "###### "]
+]);
 var MARKDOWN_SPECIALS = /[\\`*_[\]~<]/gu;
 var escapeText = (text) => text.replaceAll(MARKDOWN_SPECIALS, String.raw`\$&`);
 var renderSpan = (span, defs) => {
@@ -13014,6 +13636,7 @@ var renderChildren = (block) => {
   const defs = new Map((block.markDefs ?? []).map((def) => [def._key, def]));
   return (block.children ?? []).map((span) => renderSpan(span, defs)).join("");
 };
+var isAltText = (value) => typeof value === "string";
 var renderBlock = (block, options) => {
   const custom = options.serializers?.[block._type];
   if (custom) {
@@ -13021,7 +13644,7 @@ var renderBlock = (block, options) => {
   }
   if (block._type === "image") {
     const url = options.imageUrl?.(block);
-    const alt = typeof block.alt === "string" ? block.alt : "";
+    const alt = isAltText(block.alt) ? block.alt : "";
     return url ? `![${alt}](${url})` : "";
   }
   if (block._type !== "block") {
@@ -13036,7 +13659,7 @@ var renderBlock = (block, options) => {
   if (block.style === "blockquote") {
     return `> ${inline}`;
   }
-  return `${HEADING_STYLES[block.style ?? "normal"] ?? ""}${inline}`;
+  return `${HEADING_STYLES.get(block.style ?? "normal") ?? ""}${inline}`;
 };
 var portableTextToMarkdown = (blocks, options = {}) => {
   const lines = blocks.map((block) => renderBlock(block, options));
@@ -13059,10 +13682,11 @@ var portableTextToMarkdown = (blocks, options = {}) => {
 
 // src/core/sources/sanity.ts
 var IMAGE_REF = /^image-(?<id>[a-f0-9]+)-(?<dims>\d+x\d+)-(?<ext>\w+)$/u;
+var isTraversable = (value) => typeof value === "object" && value !== null;
 var getPath = (doc, path) => {
   let current = doc;
   for (const key of path.split(".")) {
-    if (current && typeof current === "object") {
+    if (isTraversable(current)) {
       current = current[key];
     } else {
       return;
@@ -13070,7 +13694,8 @@ var getPath = (doc, path) => {
   }
   return current;
 };
-var asString = (value) => typeof value === "string" ? value : undefined;
+var isStringValue2 = (value) => typeof value === "string";
+var asString = (value) => isStringValue2(value) ? value : undefined;
 var imageUrlFromRef = (ref, projectId, dataset) => {
   const match = ref.match(IMAGE_REF);
   if (!match?.groups) {
@@ -13129,7 +13754,7 @@ var sanitySource = (options, ctx) => {
     const raw = frontmatter_default.stringify(markdown, data);
     return {
       body: { format: "md", text: markdown },
-      data,
+      data: { ...data },
       hash: hashText(raw),
       lastModified: asString(getPath(doc, fields.lastModified ?? "_updatedAt")),
       raw,
@@ -13354,7 +13979,8 @@ var normalizeLoadedEntries = (loaded, config) => {
           prefix: source.prefix,
           staged: source.staged
         },
-        typeFrontmatter
+        typeFrontmatter,
+        versions: config.versions
       });
       if (normalized.pages.length === 0 && normalized.diagnostics.length > 0) {
         droppedPages += 1;
@@ -13387,7 +14013,10 @@ var scanProject = async (root, options = {}) => {
   const localeDirs = config.i18n && config.i18n.parser === "dir" ? config.i18n.locales.flatMap((locale) => locale.code === config.i18n?.defaultLocale ? [] : [locale.code]) : undefined;
   const [loaded, folderMeta] = await Promise.all([
     Promise.all(sources.map(async (source) => ({ source, ...await source.load() }))),
-    discoverFolderMeta(metaSources, { localeDirs })
+    discoverFolderMeta(metaSources, {
+      localeDirs,
+      versionDirs: config.versions?.archived.map((version) => version.id)
+    })
   ]);
   const sharedFolderMeta = new Map([
     ...loaded.flatMap(({ folderMeta: sourceMeta }) => Object.entries(sourceMeta ?? {})),
@@ -13415,10 +14044,12 @@ var scanProject = async (root, options = {}) => {
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
-    sharedFolderMeta
+    sharedFolderMeta,
+    versions: config.versions
   });
   const manifest = buildManifest({ config, context, graph });
-  const i18nWarnings = config.i18n ? i18nDiagnostics(pages, config.i18n) : [];
+  const i18nWarnings = config.i18n ? i18nDiagnostics(pages, config.i18n, config.versions) : [];
+  const versionWarnings = config.versions ? versionsDiagnostics(pages, config.versions) : [];
   return {
     config,
     context,
@@ -13427,7 +14058,8 @@ var scanProject = async (root, options = {}) => {
       ...folderMeta.diagnostics,
       ...entryIdDiagnostics(pages, resolveDocsCollection(config, context).base),
       ...graph.diagnostics,
-      ...i18nWarnings
+      ...i18nWarnings,
+      ...versionWarnings
     ],
     droppedPages,
     graph,
@@ -13547,9 +14179,10 @@ var auditCommand = defineCommand2({
       return;
     }
     const root = process.cwd();
-    const gate = args["fail-on"] ?? (args.strict ? "warning" : "error");
-    if (!SEVERITIES.includes(gate)) {
-      logger.error(`Invalid --fail-on "${gate}" (use ${SEVERITIES.join(" | ")}).`);
+    const gateInput = args["fail-on"] ?? (args.strict ? "warning" : "error");
+    const gate = SEVERITIES.find((severity) => severity === gateInput);
+    if (gate === undefined) {
+      logger.error(`Invalid --fail-on "${gateInput}" (use ${SEVERITIES.join(" | ")}).`);
       process.exit(1);
     }
     const agents = Object.keys(AGENTS).filter((kind) => args[kind]);
@@ -13748,12 +14381,8 @@ var buildAgentReadability = (project) => {
     return site ? absoluteUrl(site, based) : based;
   };
   const negotiates = config.deployment.output === "server" && (config.deployment.adapter === "vercel" || config.deployment.adapter === "cloudflare");
-  const artifacts = {
-    markdown: {
-      ...negotiates ? { contentNegotiation: "text/markdown" } : {},
-      pattern: abs("/{route}.md")
-    }
-  };
+  const markdown = negotiates ? { contentNegotiation: "text/markdown", pattern: abs("/{route}.md") } : { pattern: abs("/{route}.md") };
+  const artifacts = { markdown };
   if (config.ai.llmsTxt.enabled) {
     artifacts.llmsFullTxt = abs("/llms-full.txt");
     artifacts.llmsTxt = abs("/llms.txt");
@@ -13934,6 +14563,8 @@ var parseYouTubeId = (input) => {
 };
 
 // src/ai/component-markdown.ts
+var isString4 = (value) => typeof value === "string";
+var isNumber = (value) => typeof value === "number";
 var evaluateExpression = (raw, frontmatter) => {
   try {
     const value = new Function("frontmatter", `"use strict"; return (${raw});`)(frontmatter);
@@ -13952,7 +14583,7 @@ var readProps = (node, frontmatter) => {
     }
     if (attribute.value === null || attribute.value === undefined) {
       props[attribute.name] = true;
-    } else if (typeof attribute.value === "string") {
+    } else if (isString4(attribute.value)) {
       props[attribute.name] = attribute.value;
     } else {
       const result = evaluateExpression(attribute.value.value, frontmatter);
@@ -14003,9 +14634,10 @@ var cellCode = (value) => {
   const text = cellText(value);
   return text && !text.includes("`") ? `\`${text}\`` : text;
 };
+var isTypeEntryMap = (value) => typeof value === "object" && value !== null;
 var typeTable = ({ children, props }) => {
   const { type } = props;
-  if (type === null || typeof type !== "object") {
+  if (!isTypeEntryMap(type)) {
     return null;
   }
   const entries = Object.entries(type);
@@ -14013,7 +14645,7 @@ var typeTable = ({ children, props }) => {
     const prop = cellCode(`${name}${info.required ? "" : "?"}`);
     const typeCell = info.typeDescriptionLink ? `[${cellCode(info.type)}](${cellText(info.typeDescriptionLink)})` : cellCode(info.type);
     const defaultCell = info.default === undefined ? "-" : cellCode(info.default);
-    const description = cellText([info.description, info.typeDescription].filter((part) => typeof part === "string" && part !== "").join(" "));
+    const description = cellText([info.description, info.typeDescription].filter((part) => isString4(part) && part !== "").join(" "));
     return [prop, typeCell, defaultCell, description];
   });
   const table = rows.length > 0 ? markdownTable([["Prop", "Type", "Default", "Description"], ...rows], {
@@ -14024,8 +14656,8 @@ var typeTable = ({ children, props }) => {
 `);
 };
 var callout = ({ children, props }) => {
-  const type = typeof props.type === "string" ? props.type : "info";
-  const label = typeof props.title === "string" && props.title !== "" ? props.title : type.charAt(0).toUpperCase() + type.slice(1);
+  const type = isString4(props.type) ? props.type : "info";
+  const label = isString4(props.title) && props.title !== "" ? props.title : type.charAt(0).toUpperCase() + type.slice(1);
   if (!children) {
     return `> **${label}**`;
   }
@@ -14053,7 +14685,7 @@ var steps = ({ childComponents, children }) => {
     return children;
   }
   return items.map((step, index) => {
-    const title = typeof step.props.title === "string" && step.props.title !== "" ? `**${step.props.title}**` : "";
+    const title = isString4(step.props.title) && step.props.title !== "" ? `**${step.props.title}**` : "";
     const content = [title, step.children].filter(Boolean).join(`
 
 `);
@@ -14068,7 +14700,7 @@ var tabs = ({ childComponents, children }) => {
     return children;
   }
   return items.map((tab, index) => {
-    const title = typeof tab.props.title === "string" && tab.props.title !== "" ? tab.props.title : `Tab ${index + 1}`;
+    const title = isString4(tab.props.title) && tab.props.title !== "" ? tab.props.title : `Tab ${index + 1}`;
     return tab.children ? `**${title}**
 
 ${tab.children}` : `**${title}**`;
@@ -14078,17 +14710,17 @@ ${tab.children}` : `**${title}**`;
 };
 var youtube = ({ props }) => {
   let input = "";
-  if (typeof props.id === "string") {
+  if (isString4(props.id)) {
     input = props.id;
-  } else if (typeof props.url === "string") {
+  } else if (isString4(props.url)) {
     input = props.url;
   }
   const videoId = parseYouTubeId(input);
   if (!videoId) {
     return null;
   }
-  const start = typeof props.start === "number" && props.start > 0 ? `&t=${Math.floor(props.start)}s` : "";
-  const title = typeof props.title === "string" && props.title !== "" ? props.title : "Watch on YouTube";
+  const start = isNumber(props.start) && props.start > 0 ? `&t=${Math.floor(props.start)}s` : "";
+  const title = isString4(props.title) && props.title !== "" ? props.title : "Watch on YouTube";
   return `[${title}](https://www.youtube.com/watch?v=${videoId}${start})`;
 };
 var fencedBlock = (lang, code) => {
@@ -14102,7 +14734,7 @@ ${fence}`;
 };
 var exampleComponentSerializers = (examples) => ({
   Component: ({ props }) => {
-    const path = typeof props.path === "string" ? props.path : undefined;
+    const path = isString4(props.path) ? props.path : undefined;
     const example = path === undefined ? undefined : examples[path];
     return example ? fencedBlock(example.lang, example.source) : null;
   }
@@ -14212,19 +14844,28 @@ var pageUrl = (route, site, base = "") => {
   const path = withBasePath(base, route);
   return encodeURI(site ? absoluteUrl(site, path) : path);
 };
-var eligiblePages = (project) => project.graph.pages.filter((page) => !(page.meta.ai.exclude || page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex && page.source.name !== "openapi") && (project.config.ai.llmsTxt.openapi || page.source.name !== "openapi"));
+var eligiblePages = (project, options = {}) => project.graph.pages.filter((page) => !(page.meta.ai.exclude || page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex && page.source.name !== "openapi" || options.versions === "current" && page.version !== "") && (project.config.ai.llmsTxt.openapi || page.source.name !== "openapi"));
 var indexedNavigations = (project) => {
-  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 = 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];
 };
 var buildLlmsIndex = (project) => {
   const { config } = project;
@@ -14301,7 +14942,7 @@ var buildLlmsIndex = (project) => {
 };
 var buildFull = async (project) => {
   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));
   const components = {
     ...exampleComponentSerializers(project.examples ?? {}),
     ...config.ai.markdownComponents
@@ -14446,6 +15087,7 @@ var collectEntries = async (dir, prefix = "") => {
   }
   return entries;
 };
+var isString5 = (value) => typeof value === "string";
 var skillMeta = (raw, dirName) => {
   let data;
   try {
@@ -14456,8 +15098,8 @@ var skillMeta = (raw, dirName) => {
       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 = isString5(data.name) ? data.name : "";
+  const description = isString5(data.description) ? data.description : "";
   if (!(name && description)) {
     return {
       meta: null,
@@ -14582,6 +15224,8 @@ var MAX_RULES = 100;
 var MAX_RULE_LENGTH = 100;
 var FALLBACK_RULES = ["/*", "!/_astro/*", "!/*.md", "!/*.mdx", "!/*.txt"];
 var basePrefix = (base) => base && base !== "/" ? base.replace(/\/$/u, "") : "";
+var isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isJsonString = (value) => typeof value === "string";
 var isNegativeRule = (rule) => rule.startsWith("!");
 var ruleBody = (rule) => isNegativeRule(rule) ? rule.slice(1) : rule;
 var buildRunWorkerFirstRules = (routePaths, base) => {
@@ -14836,15 +15480,15 @@ var injectWorkerNegotiation = (wranglerText, options) => {
   } catch {
     return null;
   }
-  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+  if (!isJsonObject(config)) {
     return null;
   }
   const { main } = config;
-  if (typeof main !== "string" || main.length === 0 || main === NEGOTIATION_WORKER_FILE) {
+  if (!isJsonString(main) || main.length === 0 || main === NEGOTIATION_WORKER_FILE) {
     return null;
   }
-  const assets = config.assets;
-  if (assets === null || typeof assets !== "object" || typeof assets.binding !== "string") {
+  const { assets } = config;
+  if (!isJsonObject(assets) || !isJsonString(assets.binding)) {
     return null;
   }
   const {
@@ -15059,6 +15703,16 @@ var buildSitemapFiles = (project) => {
   }
   const base = siteRoot(site);
   const deployBase = normalizeBasePath(project.config.deployment.base);
+  const { versions } = project.config;
+  const archivedById = new Map((versions?.archived ?? []).map((version) => [version.id, version]));
+  const currentKeys = versions ? new Set(project.graph.pages.flatMap((page) => page.version === "" ? [`${page.versionKey}\x00${page.locale}`] : [])) : null;
+  const archivedExcluded = (page) => {
+    if (!page.version) {
+      return false;
+    }
+    const archived = archivedById.get(page.version);
+    return Boolean(archived?.noindex || archived?.canonical === "latest" && currentKeys?.has(`${page.versionKey}\x00${page.locale}`));
+  };
   const seen = new Set;
   const urls = [];
   const pushUrl = (route, lastModified) => {
@@ -15070,7 +15724,7 @@ var buildSitemapFiles = (project) => {
     urls.push(`  <url><loc>${loc}</loc>${lastmodTag(lastModified)}</url>`);
   };
   for (const page of project.graph.pages) {
-    if (page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex || ERROR_ROUTES3.has(page.route)) {
+    if (page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex || ERROR_ROUTES3.has(page.route) || archivedExcluded(page)) {
       continue;
     }
     pushUrl(withBasePath(deployBase, page.route), page.lastModified);
@@ -15109,6 +15763,7 @@ ${references.join(`
 
 // src/deploy/vercel-negotiation.ts
 var ACCEPT_MARKDOWN_HEADER_VALUE = "(.*,)?\\s*text/(x-)?markdown(\\s*[;,].*)?$";
+var isString6 = (value) => typeof value === "string";
 var ACCEPT_MARKDOWN_CONDITION = [
   { key: "accept", type: "header", value: ACCEPT_MARKDOWN_HEADER_VALUE }
 ];
@@ -15163,7 +15818,7 @@ var buildNegotiationRoutes = (routePaths, homeTokens) => {
   return { headerRoutes, rewriteRoutes };
 };
 var HOME_SRC = "^/$";
-var isNegotiationRoute = (route) => route.has?.some((condition) => condition.value === ACCEPT_MARKDOWN_HEADER_VALUE) === true || route.continue === true && route.headers?.vary === "Accept" && typeof route.src === "string" && Object.keys(route).length === 3 || route.continue === true && typeof route.headers?.link === "string" && route.src === HOME_SRC && Object.keys(route).length === 3;
+var isNegotiationRoute = (route) => route.has?.some((condition) => condition.value === ACCEPT_MARKDOWN_HEADER_VALUE) === true || route.continue === true && route.headers?.vary === "Accept" && isString6(route.src) && Object.keys(route).length === 3 || route.continue === true && isString6(route.headers?.link) && route.src === HOME_SRC && Object.keys(route).length === 3;
 var injectNegotiationRoutes = (configText, routePaths, homeLinkHeader, contentTypeOverrides, homeTokens) => {
   const overrideEntries = Object.entries(contentTypeOverrides ?? {});
   if (routePaths.length === 0 && !homeLinkHeader && overrideEntries.length === 0) {
@@ -15220,6 +15875,7 @@ import { gfmFromMarkdown as gfmFromMarkdown2 } from "mdast-util-gfm";
 import { gfm as gfm2 } from "micromark-extension-gfm";
 
 // src/search/facets.ts
+var isFacetValue = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 var pageFacets = (page, config) => {
   const declared = config.content.types[page.contentType]?.facets;
   if (!declared || declared.length === 0 || !page.custom) {
@@ -15228,7 +15884,7 @@ var pageFacets = (page, config) => {
   const facets = {};
   for (const key of declared) {
     const value = page.custom[key];
-    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    if (isFacetValue(value)) {
       facets[key] = String(value);
     }
   }
@@ -15237,7 +15893,7 @@ var pageFacets = (page, config) => {
 
 // src/search/documents.ts
 var HTML_OR_JSX = /<\/?[a-zA-Z][^\n<>]*>|<\/?>/gu;
-var WHITESPACE3 = /\s+/gu;
+var WHITESPACE4 = /\s+/gu;
 var INLINE_PARENTS = new Set([
   "delete",
   "emphasis",
@@ -15289,7 +15945,7 @@ var toPlainText = (markdown) => {
   });
   const out = [];
   collectText(tree, out);
-  return out.join("").replaceAll(WHITESPACE3, " ").trim();
+  return out.join("").replaceAll(WHITESPACE4, " ").trim();
 };
 var buildCrumbIndex = (sidebar) => {
   const index = new Map;
@@ -15323,7 +15979,11 @@ var buildCrumbIndex = (sidebar) => {
 var buildSearchDocuments = async (project, options) => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
   const byLocale = Object.values(project.graph.navigationByLocale ?? {});
-  const sidebars = byLocale.length > 0 ? byLocale.map((nav) => nav.sidebar) : [project.graph.navigation?.sidebar ?? []];
+  const byVersion = Object.values(project.graph.navigationByVersion ?? {}).flatMap((locales) => Object.values(locales)).map((nav) => nav.sidebar);
+  const sidebars = [
+    ...byLocale.length > 0 ? byLocale.map((nav) => nav.sidebar) : [project.graph.navigation?.sidebar ?? []],
+    ...byVersion
+  ];
   const crumbs = new Map;
   for (const sidebar of sidebars) {
     for (const [route, crumb] of buildCrumbIndex(sidebar)) {
@@ -15346,18 +16006,22 @@ var buildSearchDocuments = async (project, options) => {
     const tags = page?.meta?.search?.tags;
     const crumb = crumbs.get(route.path);
     const facets = page ? pageFacets(page, project.config) : undefined;
-    return {
+    const document = {
       breadcrumb: crumb?.breadcrumb ?? [],
       content: body,
       contentType: route.contentType,
       description: page?.description ?? "",
-      ...facets ? { facets } : {},
       locale: route.locale,
       route: route.path,
       section: crumb?.section || "Docs",
       tags: tags && tags.length > 0 ? tags : undefined,
-      title: route.title
+      title: route.title,
+      version: route.version
     };
+    if (facets) {
+      document.facets = facets;
+    }
+    return document;
   }));
 };
 var toSearchRecords = (documents) => documents.map((doc) => ({
@@ -15367,7 +16031,8 @@ var toSearchRecords = (documents) => documents.map((doc) => ({
   locale: doc.locale,
   tag: doc.tags?.[0],
   title: doc.title,
-  url: doc.route
+  url: doc.route,
+  version: doc.version || "current"
 }));
 
 // src/search/sync/algolia.ts
@@ -15451,7 +16116,8 @@ var syncTypesense = async (records, config) => {
       { name: "content", type: "string" },
       { name: "url", type: "string" },
       { facet: true, name: "tag", optional: true, type: "string" },
-      { facet: true, name: "locale", optional: true, type: "string" }
+      { facet: true, name: "locale", optional: true, type: "string" },
+      { facet: true, name: "version", optional: true, type: "string" }
     ],
     name: config.collection
   });
@@ -15462,7 +16128,8 @@ var syncTypesense = async (records, config) => {
     locale: record.locale,
     tag: record.tag,
     title: record.title,
-    url: record.url
+    url: record.url,
+    version: record.version
   }));
   await client.collections(config.collection).documents().import(documents, { action: "upsert" });
 };
@@ -15500,6 +16167,8 @@ import {
 import { join as join21 } from "pathe";
 var lockPath = (outDir) => join21(outDir, "dev.lock");
 var isValidPid = (pid) => typeof pid === "number" && Number.isInteger(pid) && pid > 0;
+var isPortNumber = (port) => typeof port === "number";
+var isLockRecord = (data) => typeof data === "object" && data !== null;
 var parseLock = (raw) => {
   let data;
   try {
@@ -15510,10 +16179,10 @@ var parseLock = (raw) => {
   if (isValidPid(data)) {
     return { pid: data };
   }
-  if (typeof data === "object" && data !== null) {
+  if (isLockRecord(data)) {
     const { pid, port } = data;
     if (isValidPid(pid)) {
-      return typeof port === "number" ? { pid, port } : { pid };
+      return isPortNumber(port) ? { pid, port } : { pid };
     }
   }
   return null;
@@ -15534,10 +16203,13 @@ var readDevLock = (outDir) => {
   const lock = parseLock(readFileSync5(path, "utf-8"));
   return lock && isProcessAlive(lock.pid) ? lock : null;
 };
-var lockPayload = (port) => JSON.stringify({
-  pid: process.pid,
-  ...port === undefined ? {} : { port }
-});
+var lockPayload = (port) => {
+  const info = { pid: process.pid };
+  if (port !== undefined) {
+    info.port = port;
+  }
+  return JSON.stringify(info);
+};
 var writeLock = (outDir, port) => {
   writeFileSync(lockPath(outDir), lockPayload(port));
 };
@@ -15669,27 +16341,39 @@ var buildMcpData = async (project) => {
     }
     const page = pageById.get(route.id);
     const facets = page ? pageFacets(page, config) : undefined;
-    routes.push({
+    const entry = {
       contentType: route.contentType,
       description: page?.description,
-      ...facets ? { facets } : {},
       indexable: route.indexable,
       lastModified: route.lastModified ?? null,
+      locale: route.locale,
       route: route.path,
-      title: route.title
-    });
+      title: route.title,
+      version: route.version
+    };
+    if (facets) {
+      entry.facets = facets;
+    }
+    routes.push(entry);
   }
-  return {
+  const data = {
     base: normalizeBasePath(config.deployment.base),
     defaultLocale: config.i18n?.defaultLocale,
-    documents: documents.map((doc) => ({
-      content: doc.content,
-      contentType: doc.contentType,
-      description: doc.description,
-      ...doc.facets ? { facets: doc.facets } : {},
-      route: doc.route,
-      title: doc.title
-    })),
+    documents: documents.map((doc) => {
+      const document = {
+        content: doc.content,
+        contentType: doc.contentType,
+        description: doc.description,
+        locale: doc.locale,
+        route: doc.route,
+        title: doc.title,
+        version: doc.version
+      };
+      if (doc.facets) {
+        document.facets = doc.facets;
+      }
+      return document;
+    }),
     instructions: config.ai.mcp.instructions,
     name: config.ai.mcp.name ?? config.title,
     navigation: graph.navigation,
@@ -15698,6 +16382,14 @@ var buildMcpData = async (project) => {
     site: config.deployment.site ?? null,
     version: manifest.blumeVersion
   };
+  if (config.versions) {
+    data.archivedVersions = config.versions.archived.map((version) => version.id);
+    data.navigationByVersion = graph.navigationByVersion;
+  }
+  if (config.i18n) {
+    data.navigationByLocale = graph.navigationByLocale;
+  }
+  return data;
 };
 
 // src/ai/mcp/tools.ts
@@ -15705,7 +16397,7 @@ var READ_ONLY = { openWorldHint: false, readOnlyHint: true };
 var MCP_TOOLS = [
   {
     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.',
+    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`), `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"
   },
@@ -15717,13 +16409,13 @@ var MCP_TOOLS = [
   },
   {
     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.",
+    description: '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.",
+    description: "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"
   }
@@ -15761,12 +16453,11 @@ var reverseDnsName = (input) => {
 var HTTP_URL2 = /^https?:\/\//u;
 var buildMcpServerCard = (input) => {
   const url = serverUrl(input);
-  return {
+  const card = {
     $schema: SERVER_CARD_SCHEMA,
     capabilities: { tools: { listChanged: false } },
     description: truncate(`Model Context Protocol server for the ${input.name} documentation.`),
     name: reverseDnsName(input),
-    ...HTTP_URL2.test(url) ? { remotes: [{ type: "streamable-http", url }] } : {},
     serverInfo: { name: input.name, version: input.version },
     title: truncate(input.name),
     tools: MCP_TOOLS.map((tool) => ({
@@ -15778,9 +16469,15 @@ var buildMcpServerCard = (input) => {
     transport: "streamable-http",
     transports: [{ endpoint: url, type: "streamable-http" }],
     url,
-    version: input.version,
-    ...input.site ? { websiteUrl: siteRoot(input.site) } : {}
+    version: input.version
   };
+  if (HTTP_URL2.test(url)) {
+    card.remotes = [{ type: "streamable-http", url }];
+  }
+  if (input.site) {
+    card.websiteUrl = siteRoot(input.site);
+  }
+  return card;
 };
 
 // src/core/builtin-tags.ts
@@ -15853,12 +16550,13 @@ import { dirname as dirname8, extname as extname7, isAbsolute as isAbsolute6, re
 import ts from "typescript";
 var GROUPS = ["mdx", "layout", "islands"];
 var GROUP_SET = new Set(GROUPS);
-var FRAMEWORK_BY_EXT = {
-  jsx: "react",
-  svelte: "svelte",
-  tsx: "react",
-  vue: "vue"
-};
+var isGroup = (name) => GROUP_SET.has(name);
+var FRAMEWORK_BY_EXT = new Map([
+  ["jsx", "react"],
+  ["svelte", "svelte"],
+  ["tsx", "react"],
+  ["vue", "vue"]
+]);
 var FRAMEWORK_LABEL = {
   react: "React",
   svelte: "Svelte",
@@ -15881,6 +16579,7 @@ var HYDRATION_MODES = new Set([
   "only",
   "visible"
 ]);
+var isHydrationMode = (value) => HYDRATION_MODES.has(value);
 var emptyAnalysis = () => ({
   islands: [],
   layout: [],
@@ -15962,7 +16661,7 @@ var toImport = (specifier, imported, dir) => {
     }
   }
   return {
-    framework: FRAMEWORK_BY_EXT[extension] ?? null,
+    framework: FRAMEWORK_BY_EXT.get(extension) ?? null,
     name: imported,
     path
   };
@@ -15991,7 +16690,7 @@ var applyDescriptorProperty = (descriptor, property, imports, dir) => {
     } else if (ts.isIdentifier(init)) {
       descriptor.source = resolveIdentifier(init.text, imports, dir);
     }
-  } else if (name === "client" && ts.isStringLiteral(init) && HYDRATION_MODES.has(init.text)) {
+  } else if (name === "client" && ts.isStringLiteral(init) && isHydrationMode(init.text)) {
     descriptor.client = init.text;
   } else if (name === "media" && ts.isStringLiteral(init)) {
     descriptor.media = init.text;
@@ -16025,13 +16724,14 @@ var finalize = (key, group, descriptor, label, identifier, warnings) => {
   if (!client && source?.framework) {
     warnings.push(`Override "${key}" points to a ${FRAMEWORK_LABEL[source.framework]} component (${label}) but has no hydration mode, so it renders as static HTML with no interactivity. Add one, e.g. \`${key}: { component: ${JSON.stringify(label)}, client: "load" }\`.`);
   }
-  return {
-    identifier,
-    key,
-    ...client ? { client } : {},
-    ...media ? { media } : {},
-    source
-  };
+  const normalized = { identifier, key, source };
+  if (client) {
+    normalized.client = client;
+  }
+  if (media) {
+    normalized.media = media;
+  }
+  return normalized;
 };
 var normalizeEntry2 = (entry, group, imports, dir, warnings) => {
   const defaultClient = group === "islands" ? "visible" : undefined;
@@ -16084,14 +16784,13 @@ var collectGroupOverrides = (property, imports, dir, result) => {
     return;
   }
   const name = propName(property.name);
-  if (!(name && GROUP_SET.has(name)) || !ts.isObjectLiteralExpression(property.initializer)) {
+  if (!(name && isGroup(name)) || !ts.isObjectLiteralExpression(property.initializer)) {
     return;
   }
-  const group = name;
   for (const entry of property.initializer.properties) {
-    const normalized = normalizeEntry2(entry, group, imports, dir, result.warnings);
+    const normalized = normalizeEntry2(entry, name, imports, dir, result.warnings);
     if (normalized) {
-      result[group].push(normalized);
+      result[name].push(normalized);
     }
   }
 };
@@ -16125,9 +16824,10 @@ import { parseTsconfig } from "get-tsconfig";
 import { dirname as dirname10, join as join22, resolve as resolve7 } from "pathe";
 var CONFIG_DIR_TEMPLATE = "${configDir}";
 var substituteConfigDir = (value, configDir) => value.startsWith(CONFIG_DIR_TEMPLATE) ? join22(configDir, value.slice(CONFIG_DIR_TEMPLATE.length)) : value;
+var isPathTarget = (target) => typeof target === "string";
 var toAlias = (key, value, baseDir, configDir) => {
   const first = Array.isArray(value) ? value[0] : value;
-  if (typeof first !== "string") {
+  if (!isPathTarget(first)) {
     return null;
   }
   const find = key.endsWith("/*") ? key.slice(0, -2) : key;
@@ -16157,14 +16857,14 @@ var resolveTsconfigAliases = (root) => {
   }
   const configDir = dirname10(entry);
   const baseDir = resolve7(configDir, substituteConfigDir(options?.baseUrl ?? ".", configDir));
-  const aliases = {};
+  const entries = [];
   for (const [key, value] of Object.entries(paths)) {
     const alias = toAlias(key, value, baseDir, configDir);
     if (alias) {
-      aliases[alias.find] = alias.replacement;
+      entries.push([alias.find, alias.replacement]);
     }
   }
-  return aliases;
+  return Object.fromEntries(entries);
 };
 
 // src/og/derive.ts
@@ -16172,8 +16872,12 @@ import { existsSync as existsSync14 } from "node:fs";
 import { isAbsolute as isAbsolute7, join as join23 } from "pathe";
 var CARD_WEIGHTS = [400, 600];
 var absoluteSrc = (root, src) => isAbsolute7(src) ? src : join23(root, src);
+var isNumericWeight = (weight) => typeof weight === "number";
+var isRangeWeight = (weight) => typeof weight === "string";
+var isFontName = (value) => typeof value === "string";
+var isLocalOgFont = (font) => typeof font !== "string" && ("src" in font);
 var googleWeights = (weights) => {
-  const numbers = weights.filter((weight) => typeof weight === "number");
+  const numbers = weights.filter(isNumericWeight);
   const used = numbers.filter((weight) => CARD_WEIGHTS.includes(weight));
   if (used.length > 0) {
     return used;
@@ -16182,20 +16886,22 @@ var googleWeights = (weights) => {
     return numbers;
   }
   const [first] = weights;
-  return weights.length === 1 && typeof first === "string" ? first : undefined;
+  return weights.length === 1 && isRangeWeight(first) ? first : undefined;
 };
 var googleOgFont = (name, weights) => {
   const weight = googleWeights(weights);
   return weight === undefined ? { name } : { name, weight };
 };
-var localOgFonts = (font, root) => font.variants.map((variant) => ({
-  name: font.name,
-  src: absoluteSrc(root, variant.src),
-  ...typeof variant.weight === "number" ? { weight: variant.weight } : {},
-  ...variant.style === "normal" || variant.style === "italic" ? { style: variant.style } : {}
-}));
+var localOgFonts = (font, root) => font.variants.map((variant) => {
+  const entry = {
+    name: font.name,
+    src: absoluteSrc(root, variant.src)
+  };
+  const withWeight = isNumericWeight(variant.weight) ? { ...entry, weight: variant.weight } : entry;
+  return variant.style === "normal" || variant.style === "italic" ? { ...withWeight, style: variant.style } : withWeight;
+});
 var roleFonts = (value, root) => {
-  if (typeof value === "string") {
+  if (isFontName(value)) {
     if (!isFontSlug(value)) {
       return null;
     }
@@ -16205,14 +16911,13 @@ var roleFonts = (value, root) => {
   if ("variants" in value) {
     return localOgFonts(value, root);
   }
-  const remote = value;
-  if ((remote.provider ?? "google") !== "google") {
+  if ((value.provider ?? "google") !== "google") {
     return null;
   }
-  return [googleOgFont(remote.name, remote.weights ?? CARD_WEIGHTS)];
+  return [googleOgFont(value.name, value.weights ?? CARD_WEIGHTS)];
 };
 var roleFamily = (value) => {
-  if (typeof value === "string") {
+  if (isFontName(value)) {
     return isFontSlug(value) ? GOOGLE_FONTS[value].family : null;
   }
   return value.name;
@@ -16242,12 +16947,13 @@ var deriveOgFonts = (fonts, root) => {
       }
     }
   }
-  return {
-    fonts: derived,
-    ...families.title || families.body ? { families } : {}
-  };
+  const result = { fonts: derived };
+  if (families.title || families.body) {
+    result.families = families;
+  }
+  return result;
 };
-var resolveOgFontSources = (fonts, root) => fonts.map((font) => typeof font !== "string" && ("src" in font) ? { ...font, src: absoluteSrc(root, font.src) } : font);
+var resolveOgFontSources = (fonts, root) => fonts.map((font) => isLocalOgFont(font) ? { ...font, src: absoluteSrc(root, font.src) } : font);
 var resolveOgFonts = (options, root) => {
   if (options.ogFonts) {
     return { fonts: resolveOgFontSources(options.ogFonts, root) };
@@ -16257,12 +16963,12 @@ var resolveOgFonts = (options, root) => {
 var missingFontFiles = (options, root) => {
   const sources = [];
   for (const value of Object.values(options.themeFonts ?? {})) {
-    if (typeof value !== "string" && "variants" in value) {
+    if (!isFontName(value) && "variants" in value) {
       sources.push(...value.variants.map((variant) => absoluteSrc(root, variant.src)));
     }
   }
   for (const font of options.ogFonts) {
-    if (typeof font !== "string" && "src" in font) {
+    if (isLocalOgFont(font)) {
       sources.push(absoluteSrc(root, font.src));
     }
   }
@@ -16299,9 +17005,10 @@ var ACCENTS = {
   red: "oklch(0.58 0.22 25)",
   teal: "oklch(0.6 0.12 195)"
 };
+var isAccentPreset = (value) => Object.hasOwn(ACCENTS, value);
 var CSS_COLOR = /^[\w\s#%.,()/+-]+$/u;
 var safeColor = (value, fallback) => CSS_COLOR.test(value.trim()) ? value.trim() : fallback;
-var presetOrColor = (value) => Object.hasOwn(ACCENTS, value) ? ACCENTS[value] : safeColor(value, FALLBACK_ACCENT);
+var presetOrColor = (value) => isAccentPreset(value) ? ACCENTS[value] : safeColor(value, FALLBACK_ACCENT);
 var safeColorOrNull = (value) => value && CSS_COLOR.test(value.trim()) ? value.trim() : null;
 var RADII = {
   lg: "0.75rem",
@@ -16457,11 +17164,16 @@ var buildReferenceFiles = async (options) => {
 };
 
 // src/search/popular.ts
-var resolveSearchPopular = (popular, basePath) => popular.map(({ href, icon, label }) => ({
-  ...icon ? { icon } : {},
-  label,
-  route: withBasePath(basePath, href)
-}));
+var resolveSearchPopular = (popular, basePath) => popular.map(({ href, icon, label }) => {
+  const page = {
+    label,
+    route: withBasePath(basePath, href)
+  };
+  if (icon) {
+    page.icon = icon;
+  }
+  return page;
+});
 
 // src/theme/entry.ts
 var DARK_VARIANT = `/* Dark mode is driven by data-theme on the <html> element. */
@@ -17423,12 +18135,13 @@ var VALID_MODES = new Set([
   "only",
   "visible"
 ]);
-var FRAMEWORK_BY_EXT2 = {
-  jsx: "react",
-  svelte: "svelte",
-  tsx: "react",
-  vue: "vue"
-};
+var isClientMode = (mode) => VALID_MODES.has(mode);
+var FRAMEWORK_BY_EXT2 = new Map([
+  ["jsx", "react"],
+  ["svelte", "svelte"],
+  ["tsx", "react"],
+  ["vue", "vue"]
+]);
 var ISLAND_FILE = /\.(?<ext>jsx|svelte|tsx|vue)$/u;
 var CLIENT_EXPORT = /export\s+const\s+client\s*(?::[^=]+)?=\s*["'](?<mode>\w+)["']/u;
 var readClientMode = (source, file, warnings) => {
@@ -17436,7 +18149,7 @@ var readClientMode = (source, file, warnings) => {
   if (!mode) {
     return DEFAULT_CLIENT;
   }
-  if (!VALID_MODES.has(mode)) {
+  if (!isClientMode(mode)) {
     warnings.push(`Island "${file}" declares an unknown client mode "${mode}"; defaulting to "${DEFAULT_CLIENT}". Use "load", "idle", "visible", or "only".`);
     return DEFAULT_CLIENT;
   }
@@ -17459,7 +18172,7 @@ var discoverIslands = async (root) => {
   const collectIsland = (file, source) => {
     const base = basename2(file);
     const ext = base.match(ISLAND_FILE)?.groups?.ext;
-    const framework = ext ? FRAMEWORK_BY_EXT2[ext] : undefined;
+    const framework = ext ? FRAMEWORK_BY_EXT2.get(ext) : undefined;
     if (!framework) {
       return;
     }
@@ -17691,18 +18404,18 @@ var ensureDepsLink = async (outDir, pkgDir = packageRoot()) => {
   }
   return astroConflictWarning(blumeAstro, outDirHit?.pkg ?? null);
 };
-var ISLAND_FRAMEWORK_DEPS = {
-  svelte: "@astrojs/svelte",
-  vue: "@astrojs/vue"
-};
-var DEPLOYMENT_ADAPTER_DEPS = {
-  cloudflare: "@astrojs/cloudflare",
-  netlify: "@astrojs/netlify"
-};
+var ISLAND_FRAMEWORK_DEPS = new Map([
+  ["svelte", "@astrojs/svelte"],
+  ["vue", "@astrojs/vue"]
+]);
+var DEPLOYMENT_ADAPTER_DEPS = new Map([
+  ["cloudflare", "@astrojs/cloudflare"],
+  ["netlify", "@astrojs/netlify"]
+]);
 var islandFrameworkWarnings = (frameworks, root) => {
   const warnings = [];
   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}\`).`);
     }
@@ -17710,7 +18423,7 @@ var islandFrameworkWarnings = (frameworks, root) => {
   return warnings;
 };
 var deploymentAdapterWarnings = (deployment, root) => {
-  const dep = deployment.output === "server" && deployment.adapter ? DEPLOYMENT_ADAPTER_DEPS[deployment.adapter] : undefined;
+  const dep = deployment.output === "server" && deployment.adapter ? DEPLOYMENT_ADAPTER_DEPS.get(deployment.adapter) : undefined;
   if (dep && !(canResolveFrom(root, dep) || canResolveFrom(packageRoot(), dep))) {
     return [
       `Deployment adapter "${deployment.adapter}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`
@@ -17862,14 +18575,15 @@ var readLogoSvg = (project, source) => {
   ].find((path) => existsSync16(path));
   return file ? readFileSync8(file, "utf-8") : undefined;
 };
+var isStringShorthand = (value) => typeof value === "string";
 var resolveLogo = (project) => {
   const { logo } = project.config;
   if (!logo) {
     return null;
   }
-  const config = typeof logo === "string" ? { image: logo } : logo;
+  const config = isStringShorthand(logo) ? { image: logo } : logo;
   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 ?? "";
@@ -17892,16 +18606,16 @@ var FAVICON_CANDIDATES = [
   "favicon.ico",
   "icon.ico"
 ];
-var FAVICON_TYPES = {
-  ico: "image/x-icon",
-  jpeg: "image/jpeg",
-  jpg: "image/jpeg",
-  png: "image/png",
-  svg: "image/svg+xml"
-};
+var FAVICON_TYPES = new Map([
+  ["ico", "image/x-icon"],
+  ["jpeg", "image/jpeg"],
+  ["jpg", "image/jpeg"],
+  ["png", "image/png"],
+  ["svg", "image/svg+xml"]
+]);
 var faviconType = (name) => {
   const ext = name.split(".").pop()?.toLowerCase();
-  return ext ? FAVICON_TYPES[ext] : undefined;
+  return ext ? FAVICON_TYPES.get(ext) : undefined;
 };
 var inlineDataUri = (file, type) => `data:${type};base64,${readFileSync8(file).toString("base64")}`;
 var defaultFavicon = () => ({
@@ -17937,7 +18651,7 @@ var resolveBanner = (config) => {
   if (!banner) {
     return null;
   }
-  if (typeof banner === "string") {
+  if (isStringShorthand(banner)) {
     return { content: banner, dismissible: false, key: banner };
   }
   return {
@@ -18068,6 +18782,7 @@ var buildRuntimeData = (project) => {
       theme: config.theme,
       title: config.title,
       toc: config.toc,
+      versions: config.versions ?? null,
       webmcp: {
         enabled: config.ai.webmcp,
         llms: config.ai.llmsTxt.enabled
@@ -18081,6 +18796,13 @@ var buildRuntimeData = (project) => {
     fontCssVars: configuredCssVars(config.theme.fonts),
     navigation: withRepoUrl(graph.navigation),
     navigationByLocale,
+    navigationByVersion: Object.fromEntries(Object.entries(graph.navigationByVersion).map(([id2, byLocale]) => [
+      id2,
+      Object.fromEntries(Object.entries(byLocale).map(([code, nav]) => [
+        code,
+        withRepoUrl(nav)
+      ]))
+    ])),
     routes: manifest.routes.map((route) => ({
       alternates: route.alternates,
       collection: route.collection,
@@ -18094,7 +18816,9 @@ var buildRuntimeData = (project) => {
       lastModified: route.lastModified ?? null,
       locale: route.locale,
       path: route.path,
-      title: route.title
+      title: route.title,
+      version: route.version,
+      versionAlternates: route.versionAlternates
     })),
     ui: defaultUi,
     uiByLocale
@@ -18530,6 +19254,7 @@ var prepareProject = async (options) => {
 
 // src/cli/commands/build.ts
 var ADAPTERS = ["vercel", "node", "netlify", "cloudflare"];
+var isAdapter = (value) => ADAPTERS.some((adapter) => adapter === value);
 var BUDGET_JS = "budget-js";
 var BUDGET_CSS = "budget-css";
 var validateBudgetFlags = (args) => {
@@ -18626,10 +19351,13 @@ var emitVercelNegotiation = async (project, routePaths, root) => {
   if (!existsSync18(configPath)) {
     return;
   }
-  const overrides = {
-    ...hasApiCatalog(config2) ? { [API_CATALOG_PATH.slice(1)]: API_CATALOG_TYPE } : {},
-    ...config2.ai.webBotAuth.keys.length > 0 ? { [SIGNATURES_DIRECTORY_PATH.slice(1)]: SIGNATURES_DIRECTORY_TYPE } : {}
-  };
+  const overrides = {};
+  if (hasApiCatalog(config2)) {
+    overrides[API_CATALOG_PATH.slice(1)] = API_CATALOG_TYPE;
+  }
+  if (config2.ai.webBotAuth.keys.length > 0) {
+    overrides[SIGNATURES_DIRECTORY_PATH.slice(1)] = SIGNATURES_DIRECTORY_TYPE;
+  }
   const rawMarkdown = await buildRawMarkdown(project);
   const home = rawMarkdown["/"];
   const injected = injectNegotiationRoutes(await readFile17(configPath, "utf-8"), routePaths, buildHomeLinkHeader(config2, routePaths), overrides, home ? markdownTokenCount(agentMarkdown(home)) : undefined);
@@ -18883,7 +19611,7 @@ var buildCommand = defineCommand3({
       logger.error(`Invalid --output "${args.output}" (use static | server).`);
       process.exit(1);
     }
-    if (args.adapter && !ADAPTERS.includes(args.adapter)) {
+    if (args.adapter && !isAdapter(args.adapter)) {
       logger.error(`Invalid --adapter "${args.adapter}" (use ${ADAPTERS.join(" | ")}).`);
       process.exit(1);
     }
@@ -19295,7 +20023,7 @@ var askFiles = async (project, srcDir, genDir) => {
   const grounded = ask.provider !== "inkeep";
   const files = [
     {
-      content: askEndpointTemplate(resolveAskBackend(ask), grounded),
+      content: askEndpointTemplate(resolveAskBackend(ask), grounded, ask.instructions),
       path: join33(srcDir, "pages", "api", "ask.ts")
     }
   ];
@@ -19794,14 +20522,15 @@ var commandsFor = (pm) => ({
   exec: { bun: "bunx", npm: "npx", pnpm: "pnpm exec", yarn: "yarn" }[pm],
   install: `${pm} install`
 });
+var isPackageManager = (value) => PACKAGE_MANAGERS.some((pm) => pm === value);
 var detectPackageManager = (userAgent) => {
   const name = userAgent?.split("/")[0];
-  return name !== undefined && PACKAGE_MANAGERS.includes(name) ? name : "npm";
+  return name !== undefined && isPackageManager(name) ? name : "npm";
 };
 var detectProjectPackageManager = async (root) => {
   const detected = await detect({ cwd: root });
   const name = detected?.name;
-  return name !== undefined && PACKAGE_MANAGERS.includes(name) ? name : detectPackageManager(process.env.npm_config_user_agent);
+  return name !== undefined && isPackageManager(name) ? name : detectPackageManager(process.env.npm_config_user_agent);
 };
 var validateContentDir = (root, dir) => isAbsolute9(dir) || relative16(root, join35(root, dir)).startsWith("..") ? "Must be a relative path inside the project." : undefined;
 var titleize = (raw) => {
@@ -19865,10 +20594,16 @@ export default defineConfig({
   description: "Documentation powered by Blume.",${STARTERS[answers.template].configExtra}${contentBlockFor(answers)}
 });
 `;
-var extraDepsFor = (sources) => ({
-  ...sources.includes("notion") && { "@notionhq/client": "^2.2.15" },
-  ...sources.includes("sanity") && { "@sanity/client": "^7.25.0" }
-});
+var extraDepsFor = (sources) => {
+  const deps = {};
+  if (sources.includes("notion")) {
+    deps["@notionhq/client"] = "^2.2.15";
+  }
+  if (sources.includes("sanity")) {
+    deps["@sanity/client"] = "^7.25.0";
+  }
+  return deps;
+};
 var buildPlan = (root, answers) => {
   const files = [
     {
@@ -20166,7 +20901,7 @@ import { join as join38 } from "pathe";
 import { readFile as readFile20, writeFile as writeFile12 } from "node:fs/promises";
 import spawn2 from "cross-spawn";
 import { join as join37 } from "pathe";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var KILL_GRACE_MS = 5000;
 var MCP_TOOL_NAMES = [
   "search_docs",
@@ -20292,10 +21027,10 @@ var codexArgs = (context) => {
   return [...base, "-"];
 };
 var agentArgs = (kind, context) => kind === "claude" ? claudeArgs(context) : codexArgs(context);
-var claudeResultSchema = z3.object({
-  is_error: z3.boolean().default(false),
-  result: z3.string().default(""),
-  total_cost_usd: z3.number().optional()
+var claudeResultSchema = z4.object({
+  is_error: z4.boolean().default(false),
+  result: z4.string().default(""),
+  total_cost_usd: z4.number().optional()
 });
 var tail = (value, max = 300) => {
   const trimmed = value.trim();
@@ -20349,11 +21084,11 @@ var readAgentOutput = async (kind, result, lastMessagePath) => {
   }
   return { isError: false, text };
 };
-var verdictSchema = z3.object({
-  missing: z3.array(z3.string()).default([]),
-  notes: z3.string().default(""),
-  pass: z3.boolean(),
-  score: z3.number().min(0).max(1).optional()
+var verdictSchema = z4.object({
+  missing: z4.array(z4.string()).default([]),
+  notes: z4.string().default(""),
+  pass: z4.boolean(),
+  score: z4.number().min(0).max(1).optional()
 });
 var parseVerdict = (text) => {
   const start = text.indexOf("{");
@@ -20374,26 +21109,26 @@ var parseVerdict = (text) => {
 // src/eval/schema.ts
 import { readFile as readFile21 } from "node:fs/promises";
 import { load as load2 } from "js-yaml";
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
-var questionSchema = z4.strictObject({
-  expected: z4.array(z4.string().min(1)).min(1, "expected must list at least one fact"),
-  id: z4.string().regex(ID_PATTERN, "id must be a kebab-case slug (a-z, 0-9, dashes)"),
-  question: z4.string().min(1),
-  routes: z4.union([z4.string(), z4.array(z4.string())]).default([]).transform((value) => typeof value === "string" ? [value] : value),
-  severity: z4.enum(["error", "warning"]).default("error"),
-  skip: z4.boolean().default(false)
+var questionSchema = z5.strictObject({
+  expected: z5.array(z5.string().min(1)).min(1, "expected must list at least one fact"),
+  id: z5.string().regex(ID_PATTERN, "id must be a kebab-case slug (a-z, 0-9, dashes)"),
+  question: z5.string().min(1),
+  routes: z5.union([z5.string(), z5.array(z5.string())]).default([]).transform((value) => Array.isArray(value) ? value : [value]),
+  severity: z5.enum(["error", "warning"]).default("error"),
+  skip: z5.boolean().default(false)
 });
-var fullSchema = z4.strictObject({
-  questions: z4.array(questionSchema).min(1),
-  version: z4.literal(1).default(1)
+var fullSchema = z5.strictObject({
+  questions: z5.array(questionSchema).min(1),
+  version: z5.literal(1).default(1)
 });
 var evalsFileSchema = fullSchema.superRefine((value, context) => {
   const seen = new Set;
   for (const question of value.questions) {
     if (seen.has(question.id)) {
       context.addIssue({
-        code: z4.ZodIssueCode.custom,
+        code: z5.ZodIssueCode.custom,
         message: `duplicate question id "${question.id}"`,
         path: ["questions"]
       });
@@ -20986,13 +21721,13 @@ var initCommand = defineCommand9({
   },
   async run({ args }) {
     const cwd = process.cwd();
-    const template = args.template;
-    if (template !== undefined && !TEMPLATES.includes(template)) {
+    const template = TEMPLATES.find((candidate) => candidate === args.template);
+    if (args.template !== undefined && template === undefined) {
       logger.error(`Unknown template "${args.template}" (use ${TEMPLATES.join(" | ")}).`);
       process.exit(1);
     }
-    const pm = args["package-manager"];
-    if (pm !== undefined && !PACKAGE_MANAGERS.includes(pm)) {
+    const pm = PACKAGE_MANAGERS.find((candidate) => candidate === args["package-manager"]);
+    if (args["package-manager"] !== undefined && pm === undefined) {
       logger.error(`Unknown package manager "${args["package-manager"]}" (use ${PACKAGE_MANAGERS.join(" | ")}).`);
       process.exit(1);
     }
@@ -21065,7 +21800,7 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 
 // src/search/orama-index.ts
 import { create, insertMultiple, search } from "@orama/orama";
@@ -21076,7 +21811,8 @@ var SCHEMA = {
   facetTerms: "enum[]",
   locale: "enum",
   route: "string",
-  title: "string"
+  title: "string",
+  version: "enum"
 };
 var toFacetTerms = (facets) => Object.entries(facets).map(([key, value]) => `${key}:${value}`);
 var BOOST = { description: 2, title: 3 };
@@ -21098,12 +21834,13 @@ var addBigrams = (run, tokens) => {
     previous = character;
   }
 };
+var hasSegmenter = (segmenter) => typeof segmenter === "function";
 var segmentingTokenizer = (locale) => {
   const language = locale?.toLowerCase().split(/[-_]/u)[0] ?? "";
   if (!SEGMENTED_LANGUAGES.has(language)) {
     return;
   }
-  if (typeof Intl.Segmenter !== "function") {
+  if (!hasSegmenter(Intl.Segmenter)) {
     return;
   }
   const segmenter = new Intl.Segmenter(language, { granularity: "word" });
@@ -21152,28 +21889,33 @@ var segmentingTokenizer = (locale) => {
 };
 var buildOramaIndex = async (documents, locale) => {
   const tokenizer = segmentingTokenizer(locale);
-  const db = create({
-    schema: SCHEMA,
-    ...tokenizer ? { components: { tokenizer } } : {}
-  });
+  const db = tokenizer ? create({ components: { tokenizer }, schema: SCHEMA }) : create({ schema: SCHEMA });
   await insertMultiple(db, documents.map((doc) => doc.facets ? { ...doc, facetTerms: toFacetTerms(doc.facets) } : doc));
   return db;
 };
 var ALL_TOKENS = 0;
 var queryOramaIndex = async (db, term, limit, filters) => {
   const facetTerms = filters?.facets ? toFacetTerms(filters.facets) : [];
-  const where = {
-    ...filters?.locale ? { locale: { eq: filters.locale } } : {},
-    ...filters?.contentTypes && filters.contentTypes.length > 0 ? { contentType: { in: filters.contentTypes } } : {},
-    ...facetTerms.length > 0 ? { facetTerms: { containsAll: facetTerms } } : {}
-  };
-  const params = {
+  const where = {};
+  if (filters?.locale) {
+    where.locale = { eq: filters.locale };
+  }
+  if (filters?.version !== undefined) {
+    where.version = { eq: filters.version };
+  }
+  if (filters?.contentTypes && filters.contentTypes.length > 0) {
+    where.contentType = { in: filters.contentTypes };
+  }
+  if (facetTerms.length > 0) {
+    where.facetTerms = { containsAll: facetTerms };
+  }
+  const unfiltered = {
     boost: BOOST,
     limit,
     properties: ["title", "description", "content"],
-    term,
-    ...Object.keys(where).length > 0 ? { where } : {}
+    term
   };
+  const params = Object.keys(where).length > 0 ? { ...unfiltered, where } : unfiltered;
   const bigrammed = BIGRAM_LANGUAGES.has(db.tokenizer?.language ?? "");
   const strict = bigrammed ? await search(db, { ...params, threshold: ALL_TOKENS }) : undefined;
   const found = strict && strict.hits.length > 0 ? strict : await search(db, params);
@@ -21184,36 +21926,55 @@ var queryOramaIndex = async (db, term, limit, filters) => {
 var DEFAULT_SEARCH_LIMIT = 8;
 var MAX_SEARCH_LIMIT = 20;
 var EXCERPT_LENGTH = 200;
-var contentTypesField = z5.preprocess((value) => {
+var contentTypesField = z6.preprocess((value) => {
   const list2 = (Array.isArray(value) ? value : [value]).filter((entry) => typeof entry === "string");
   return list2.length > 0 ? list2 : undefined;
-}, z5.array(z5.string()).optional().describe('Only include pages of these content types (frontmatter `type`, e.g. `["doc", "rfc"]`). `list_pages` shows each page\'s type. Omit to include every type.'));
-var filtersField = z5.preprocess((value) => {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+}, z6.array(z6.string()).optional().describe('Only include pages of these content types (frontmatter `type`, e.g. `["doc", "rfc"]`). `list_pages` shows each page\'s type. Omit to include every type.'));
+var looseFacetObject = z6.record(z6.string(), z6.unknown());
+var filtersField = z6.preprocess((value) => {
+  const candidate = looseFacetObject.safeParse(value);
+  if (!candidate.success) {
     return;
   }
-  const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+  const entries = Object.entries(candidate.data).filter((entry) => typeof entry[1] === "string");
   return entries.length > 0 ? Object.fromEntries(entries) : undefined;
-}, z5.record(z5.string(), z5.string()).optional().describe('Only include pages matching every facet, key → required value (e.g. `{"status": "enforced"}`). Facets are metadata the site declares per content type; `list_pages` shows each page\'s facet values. Omit for no facet filtering.'));
-var limitField = z5.preprocess((value) => {
-  const num = typeof value === "number" ? value : Number(value);
+}, z6.record(z6.string(), z6.string()).optional().describe('Only include pages matching every facet, key → required value (e.g. `{"status": "enforced"}`). Facets are metadata the site declares per content type; `list_pages` shows each page\'s facet values. Omit for no facet filtering.'));
+var limitField = z6.preprocess((value) => {
+  const num = Number(value);
   return Number.isFinite(num) ? Math.min(Math.max(Math.trunc(num), 1), MAX_SEARCH_LIMIT) : undefined;
-}, z5.int().min(1).max(MAX_SEARCH_LIMIT).optional().describe(`Maximum hits to return (default ${DEFAULT_SEARCH_LIMIT}).`));
-var textField = (description) => z5.preprocess((value) => typeof value === "string" ? value : "", z5.string().describe(description));
+}, z6.int().min(1).max(MAX_SEARCH_LIMIT).optional().describe(`Maximum hits to return (default ${DEFAULT_SEARCH_LIMIT}).`));
+var textField = (description) => z6.preprocess((value) => {
+  const parsed = z6.string().safeParse(value);
+  return parsed.success ? parsed.data : "";
+}, z6.string().describe(description));
+var optionalTextField = (description) => z6.preprocess((value) => {
+  const parsed = z6.string().safeParse(value);
+  const trimmed = parsed.success ? parsed.data.trim() : "";
+  return trimmed || undefined;
+}, z6.string().optional().describe(description));
+var localeField = optionalTextField("Only include pages in this locale (e.g. `fr`). Omit for every language.");
+var 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.');
 var TOOL_INPUTS = {
-  get_navigation: z5.object({}),
-  get_page: z5.object({
+  get_navigation: z6.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: z6.object({
     route: textField("The page route, e.g. `/guides/install`.")
   }),
-  list_pages: z5.object({
+  list_pages: z6.object({
     contentTypes: contentTypesField,
-    filters: filtersField
+    filters: filtersField,
+    locale: localeField,
+    version: versionField
   }),
-  search_docs: z5.object({
+  search_docs: z6.object({
     contentTypes: contentTypesField,
     filters: filtersField,
     limit: limitField,
-    query: textField("The search query.")
+    locale: localeField,
+    query: textField("The search query."),
+    version: versionField
   })
 };
 var inputSchemaFor = (schema) => {
@@ -21221,7 +21982,7 @@ var inputSchemaFor = (schema) => {
     $schema: _dialect,
     additionalProperties: _closed,
     ...rest
-  } = z5.toJSONSchema(schema);
+  } = z6.toJSONSchema(schema);
   return rest;
 };
 var TOOL_DEFINITIONS = MCP_TOOLS.map((tool) => ({
@@ -21232,6 +21993,19 @@ var TOOL_DEFINITIONS = MCP_TOOLS.map((tool) => ({
   title: tool.title
 }));
 var matchesFacets = (facets, filters) => Object.entries(filters).every(([key, value]) => facets?.[key] === value);
+var asVersionScope = (value, data) => {
+  if (!data.archivedVersions) {
+    return;
+  }
+  if (value === "all") {
+    return;
+  }
+  if (value === undefined || value === "latest" || value === "current") {
+    return "";
+  }
+  return value;
+};
+var unknownVersionError = (versionId, data) => versionId && data.archivedVersions && !data.archivedVersions.includes(versionId) ? `Unknown version "${versionId}". Archived versions: ${data.archivedVersions.join(", ")}.` : null;
 var normalizeRoute2 = (input, data) => {
   let value = input.trim();
   if (/^https?:\/\//iu.test(value)) {
@@ -21256,10 +22030,10 @@ var excerptFor = (doc) => {
   const head = doc.content.slice(0, EXCERPT_LENGTH).trim();
   return doc.content.length > EXCERPT_LENGTH ? `${head}…` : head;
 };
-var text = (value, isError = false) => ({
-  content: [{ text: value, type: "text" }],
-  ...isError ? { isError: true } : {}
-});
+var text = (value, isError = false) => {
+  const content = [{ text: value, type: "text" }];
+  return isError ? { content, isError: true } : { content };
+};
 var createIndexProvider = (documents, locale) => {
   let dbPromise = null;
   return function provideIndex() {
@@ -21268,10 +22042,8 @@ var createIndexProvider = (documents, locale) => {
   };
 };
 var buildServer = (data, index) => {
-  const server = new Server({ name: data.name, version: data.version }, {
-    capabilities: { tools: {} },
-    ...data.instructions ? { instructions: data.instructions } : {}
-  });
+  const serverOptions = data.instructions ? { capabilities: { tools: {} }, instructions: data.instructions } : { capabilities: { tools: {} } };
+  const server = new Server({ name: data.name, version: data.version }, serverOptions);
   server.setRequestHandler(ListToolsRequestSchema, () => ({
     tools: TOOL_DEFINITIONS
   }));
@@ -21282,16 +22054,24 @@ var buildServer = (data, index) => {
       const db = await index();
       const hits = await queryOramaIndex(db, input.query, input.limit ?? DEFAULT_SEARCH_LIMIT, {
         contentTypes: input.contentTypes,
-        facets: input.filters
+        facets: input.filters,
+        locale: input.locale,
+        version: asVersionScope(input.version, data)
+      });
+      const results = hits.map((doc) => {
+        const hit = {
+          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;
       });
-      const results = hits.map((doc) => ({
-        contentType: doc.contentType,
-        excerpt: excerptFor(doc),
-        facets: doc.facets,
-        route: doc.route,
-        title: doc.title,
-        url: urlFor(doc.route, data)
-      }));
       return text(JSON.stringify(results, null, 2));
     }
     if (name === "get_page") {
@@ -21304,20 +22084,40 @@ var buildServer = (data, index) => {
       return text(markdown);
     }
     if (name === "list_pages") {
-      const { contentTypes, filters } = TOOL_INPUTS.list_pages.parse(args);
-      const routes = data.routes.filter((route) => (!contentTypes || contentTypes.includes(route.contentType)) && (!filters || matchesFacets(route.facets, filters)));
-      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)
-      })), null, 2));
+      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)) && (!locale || route.locale === locale) && (versionScope === undefined || route.version === versionScope));
+      return text(JSON.stringify(routes.map((route) => {
+        const listing = {
+          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));
     }
     if (name === "get_navigation") {
-      return text(JSON.stringify(data.navigation, null, 2));
+      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);
   });
@@ -21469,11 +22269,11 @@ var translateAgentArgs = (kind, lastMessagePath) => kind === "claude" ? claudeAr
 import { createHash as createHash5 } from "node:crypto";
 import { readFile as readFile23 } from "node:fs/promises";
 import { join as join42 } from "pathe";
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var LEDGER_FILE = "blume.translations.json";
-var ledgerSchema = z6.object({
-  files: z6.record(z6.string(), z6.record(z6.string(), z6.string())),
-  version: z6.literal(1)
+var ledgerSchema = z7.object({
+  files: z7.record(z7.string(), z7.record(z7.string(), z7.string())),
+  version: z7.literal(1)
 });
 var emptyLedger = () => ({
   files: {},
@@ -21743,6 +22543,7 @@ import { readFile as readFile24 } from "node:fs/promises";
 import { dirname as dirname15, join as join43, relative as relative19 } from "pathe";
 import { glob as glob8 } from "tinyglobby";
 var META_FILES2 = ["**/meta.ts", "**/meta.js", "**/meta.mjs"];
+var isFactoryModule = (value) => typeof value === "function";
 var metaTargetPath = (meta, locale) => join43(meta.contentRoot, locale, meta.dir, "meta.ts");
 var discoverTranslatableMeta = async (project) => {
   const { i18n } = project.config;
@@ -21771,7 +22572,7 @@ var discoverTranslatableMeta = async (project) => {
         readFile24(file, "utf-8"),
         load3(file)
       ]);
-      if (typeof mod === "function") {
+      if (isFactoryModule(mod)) {
         diagnostics.push({
           code: "BLUME_TRANSLATE_META_FACTORY",
           file,
@@ -21803,7 +22604,7 @@ var generateMetaModule = (meta, translatedTitle) => {
     ...meta,
     title: translatedTitle
   };
-  const lines = Object.keys(data).toSorted().filter((key) => data[key] !== undefined).map((key) => `  ${key}: ${JSON.stringify(data[key])},`);
+  const lines = Object.entries(data).toSorted(([a], [b]) => a < b ? -1 : 1).filter(([, value]) => value !== undefined).map(([key, value]) => `  ${key}: ${JSON.stringify(value)},`);
   return [
     "// Generated by `blume translate` — edit the default locale's meta file",
     "// and rerun the translation instead of editing this copy.",
@@ -21863,10 +22664,12 @@ var stripOuterFence = (text2) => {
 };
 var countFenceLines = (text2) => text2.split(`
 `).filter((line) => FENCE_LINE.test(line)).length;
+var isKeyedObject = (value) => typeof value === "object" && value !== null;
+var isString7 = (value) => typeof value === "string";
 var getPath2 = (data, path) => {
   let value = data;
   for (const key of path) {
-    if (typeof value !== "object" || value === null) {
+    if (!isKeyedObject(value)) {
       return;
     }
     value = value[key];
@@ -21921,7 +22724,7 @@ var validateTranslation = (sourceText, agentText) => {
   for (const path of TRANSLATABLE_KEY_PATHS) {
     const original = getPath2(source.data, path);
     const translated = getPath2(parsed.data, path);
-    if (typeof original === "string" && typeof translated === "string" && translated.trim() !== "") {
+    if (isString7(original) && isString7(translated) && translated.trim() !== "") {
       setPath(data, path, translated);
     }
   }
@@ -21941,12 +22744,12 @@ var parseMetaTitles = (agentText, expectedKeys) => {
       parsed = undefined;
     }
   }
-  const record = typeof parsed === "object" && parsed !== null ? parsed : {};
+  const record = isKeyedObject(parsed) ? parsed : {};
   const titles = {};
   const missing = [];
   for (const key of expectedKeys) {
     const value = record[key];
-    if (typeof value === "string" && value.trim() !== "") {
+    if (isString7(value) && value.trim() !== "") {
       titles[key] = value;
     } else {
       missing.push(key);
@@ -22103,7 +22906,7 @@ var translatablePages = (project, i18n) => {
   const seen = new Set;
   const universe = [];
   for (const page2 of project.graph.pages) {
-    if (page2.locale !== i18n.defaultLocale || page2.fallback || !page2.sourcePath || seen.has(page2.sourcePath)) {
+    if (page2.locale !== i18n.defaultLocale || page2.fallback || !page2.sourcePath || seen.has(page2.sourcePath) || page2.version !== "") {
       continue;
     }
     const ext = extname8(page2.sourcePath);
@@ -22673,8 +23476,249 @@ var validateCommand = defineCommand14({
   }
 });
 
+// src/cli/commands/version.ts
+import { defineCommand as defineCommand15 } from "citty";
+
+// src/core/version-cut.ts
+import { existsSync as existsSync28 } from "node:fs";
+import { cp as cp3, readdir as readdir3, readFile as readFile27, rm as rm5 } from "node:fs/promises";
+import { join as join48, relative as relative21 } from "pathe";
+class CutError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CutError";
+  }
+}
+var INLINE_CODE2 = /`[^`]*`/gu;
+var ROOT_LINK = /(?<prefix>\]\(|href="|src=")(?<target>\/[^\s"')]*)/gu;
+var buildRouteRewrites = (project, id2) => {
+  const { basePath, i18n } = project.config;
+  const { contentRoot: contentRoot2 } = project.context;
+  const rewrites = new Map;
+  for (const page2 of project.graph.pages) {
+    const { sourcePath } = page2;
+    if (page2.version !== "" || !sourcePath || relative21(contentRoot2, sourcePath).startsWith("..")) {
+      continue;
+    }
+    const logical = versionizeRoute(page2.versionKey, id2);
+    rewrites.set(stripBasePath(basePath, page2.route), i18n ? localizeRoute(logical, page2.locale, i18n) : logical);
+  }
+  return rewrites;
+};
+var rewriteLine2 = (line, rewrites) => {
+  const masked = line.replaceAll(INLINE_CODE2, (span) => " ".repeat(span.length));
+  let out = "";
+  let cursor = 0;
+  let count = 0;
+  for (const match of masked.matchAll(ROOT_LINK)) {
+    const target = match.groups?.target ?? "";
+    const hash = target.search(/[#?]/u);
+    const path = hash === -1 ? target : target.slice(0, hash);
+    const suffix = hash === -1 ? "" : target.slice(hash);
+    const bare = path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
+    const replacement = rewrites.get(bare);
+    if (replacement === undefined) {
+      continue;
+    }
+    const offset = (match.index ?? 0) + (match.groups?.prefix?.length ?? 0);
+    out += line.slice(cursor, offset) + replacement + suffix;
+    cursor = offset + target.length;
+    count += 1;
+  }
+  return count === 0 ? line : out + line.slice(cursor);
+};
+var rewriteSnapshotLinks = (source, rewrites) => {
+  let fence = null;
+  let count = 0;
+  const lines = source.split(`
+`).map((line) => {
+    const next = nextFenceState(line, fence);
+    const inFence = fence !== null || next !== null;
+    fence = next;
+    if (inFence) {
+      return line;
+    }
+    const rewrittenLine = rewriteLine2(line, rewrites);
+    if (rewrittenLine !== line) {
+      count += 1;
+    }
+    return rewrittenLine;
+  });
+  return { count, text: lines.join(`
+`) };
+};
+var snippetFor = (id2, hasVersions) => hasVersions ? `Add to versions.archived in blume.config.ts (newest first):
+
+  { id: "${id2}" },
+` : `Add to blume.config.ts:
+
+  versions: {
+    archived: [{ id: "${id2}" }],
+    current: { label: "…" },
+  },
+`;
+var insertArchivedVersion = async (configPath, id2) => {
+  let text2;
+  try {
+    text2 = await readFile27(configPath, "utf-8");
+  } catch {
+    return false;
+  }
+  const match = text2.match(/(?<lead>archived:\s*\[)/u);
+  if (!match || match.index === undefined) {
+    return false;
+  }
+  const insertAt = match.index + (match.groups?.lead?.length ?? 0);
+  const lineStart = text2.lastIndexOf(`
+`, match.index) + 1;
+  const indent = text2.slice(lineStart).match(/^\s*/u)?.[0] ?? "";
+  const rest = text2.slice(insertAt);
+  let entry;
+  if (rest.trimStart().startsWith("]")) {
+    entry = `{ id: "${id2}" }`;
+  } else if (rest.startsWith(`
+`)) {
+    entry = `
+${indent}  { id: "${id2}" },`;
+  } else {
+    entry = `{ id: "${id2}" }, `;
+  }
+  await writeTextAtomic(configPath, text2.slice(0, insertAt) + entry + rest);
+  return true;
+};
+var cutVersion = async (root, id2, options = {}) => {
+  if (!VERSION_ID.test(id2)) {
+    throw new CutError(`Version ids must start with a letter (e.g. "v1.0") and contain only letters, digits, dots, hyphens, and underscores — got "${id2}".`);
+  }
+  const project = await scanProject(root);
+  const errors = project.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+  if (errors.length > 0) {
+    throw new CutError(`The project has ${errors.length} error diagnostic(s) — fix them before cutting a version (run \`blume validate\`).`);
+  }
+  const { contentRoot: contentRoot2 } = project.context;
+  if (project.config.versions?.archived.some((version) => version.id === id2)) {
+    throw new CutError(`Version "${id2}" is already registered in versions.archived.`);
+  }
+  const dir = join48(contentRoot2, id2);
+  if (existsSync28(dir)) {
+    if (!options.force) {
+      throw new CutError(`${dir} already exists — pass --force to overwrite the snapshot.`);
+    }
+    await rm5(dir, { force: true, recursive: true });
+  }
+  const excluded = new Set([
+    id2,
+    "node_modules",
+    ...project.config.versions?.archived.map((version) => version.id) ?? []
+  ]);
+  const entries = await readdir3(contentRoot2, { withFileTypes: true });
+  let copied = 0;
+  await Promise.all(entries.map(async (entry) => {
+    if (excluded.has(entry.name) || entry.name.startsWith(".") || entry.isDirectory() && VERSION_LIKE.test(entry.name)) {
+      return;
+    }
+    await cp3(join48(contentRoot2, entry.name), join48(dir, entry.name), {
+      recursive: true
+    });
+  }));
+  const rewrites = buildRouteRewrites(project, id2);
+  const rewritten = [];
+  const walk = async (current) => {
+    const children = await readdir3(current, { withFileTypes: true });
+    await Promise.all(children.map(async (child) => {
+      const abs = join48(current, child.name);
+      if (child.isDirectory()) {
+        await walk(abs);
+        return;
+      }
+      copied += 1;
+      if (!/\.mdx?$/u.test(child.name)) {
+        return;
+      }
+      const source = await readFile27(abs, "utf-8");
+      const { text: text2, count } = rewriteSnapshotLinks(source, rewrites);
+      if (count > 0) {
+        await writeTextAtomic(abs, text2);
+        rewritten.push({ count, file: relative21(dir, abs) });
+      }
+    }));
+  };
+  await walk(dir);
+  const configPath = join48(root, "blume.config.ts");
+  const configUpdated = project.config.versions !== undefined && await insertArchivedVersion(configPath, id2);
+  return {
+    configSnippet: configUpdated ? null : snippetFor(id2, project.config.versions !== undefined),
+    configUpdated,
+    copied,
+    dir,
+    rewritten
+  };
+};
+
+// src/cli/commands/version.ts
+var versionCommand = defineCommand15({
+  args: {
+    force: {
+      description: "Overwrite an existing snapshot directory.",
+      type: "boolean"
+    },
+    id: {
+      description: 'Version id to cut (e.g. "v1.0").',
+      required: false,
+      type: "positional"
+    }
+  },
+  meta: {
+    description: "Freeze the current docs as an archived version.",
+    name: "version"
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    if (!args.id) {
+      const { config: config2 } = await loadConfig(root);
+      if (!config2.versions) {
+        logger.info("Versioning is not configured. Cut the first version with `blume version <id>` (e.g. `blume version v1.0`).");
+        return;
+      }
+      const { current, archived } = config2.versions;
+      process.stdout.write(`  ${current.label} (current)${current.badge ? ` — ${current.badge}` : ""}
+`);
+      for (const version of archived) {
+        process.stdout.write(`  ${version.label ?? version.id} — ${version.id}/
+`);
+      }
+      return;
+    }
+    try {
+      const result = await cutVersion(root, args.id, { force: args.force });
+      logger.success(`Snapshot ${result.dir} (${result.copied} file(s) copied)`);
+      const totalRewrites = result.rewritten.reduce((sum, entry) => sum + entry.count, 0);
+      if (totalRewrites > 0) {
+        logger.info(`Rewrote root-absolute links in ${result.rewritten.length} page(s) (${totalRewrites} line(s)).`);
+      }
+      if (result.configUpdated) {
+        logger.success(`Added "${args.id}" to versions.archived in blume.config.ts`);
+      } else if (result.configSnippet) {
+        logger.info(result.configSnippet);
+      }
+      logger.info("Archived versions are frozen — future edits belong in the live tree. Restart `blume dev` to pick up the snapshot.");
+    } catch (error) {
+      if (error instanceof CutError) {
+        logger.error(error.message);
+        process.exit(1);
+      }
+      if (error instanceof BlumeError) {
+        logger.error(error.diagnostic.message);
+        process.exit(1);
+      }
+      reportInternalError(error);
+      process.exit(1);
+    }
+  }
+});
+
 // src/cli/index.ts
-var main = defineCommand15({
+var main = defineCommand16({
   meta: {
     description: "Markdown-first documentation powered by Astro and Vite.",
     name: "blume",
@@ -22694,7 +23738,8 @@ var main = defineCommand15({
     preview: previewCommand,
     sync: syncCommand,
     translate: translateCommand,
-    validate: validateCommand
+    validate: validateCommand,
+    version: versionCommand
   }
 });
 loadEnvFiles(process.cwd());
@@ -22708,5 +23753,5 @@ process.on("unhandledRejection", (error) => {
 });
 runMain(main);
 
-//# debugId=07BF7082AA0A5EEC64756E2164756E21
+//# debugId=6377B095BFD3F5AE64756E2164756E21
 //# sourceMappingURL=index.js.map