@thallylabs/migrate 0.2.31 → 0.2.33

package/dist/index.js

@@ -2393,9 +2393,9 @@ function escapeOrphanCapitalizedTags(body) {
       continue;
     }
     const start = match.index;
-    const list = opens.get(name) ?? [];
-    list.push({ start, end: start + full.length });
-    opens.set(name, list);
+    const list2 = opens.get(name) ?? [];
+    list2.push({ start, end: start + full.length });
+    opens.set(name, list2);
   }
   const edits = [];
   for (const [name, ranges] of opens) {
@@ -4238,24 +4238,25 @@ import { existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as rea
 import { dirname as dirname2, extname as extname3, relative as relative3 } from "path";
 var MAX_MINTLIFY_CONFIG_BYTES = 2e7;
 function addMintlifyDirectoryRedirects(config, pages) {
-  const pageIds = new Set(pages.map((page) => page.id));
+  const pageIds = new Set(pages.map((page) => page.id.toLowerCase()));
   const redirects = [...config.redirects ?? []];
-  const redirectSources = new Set(redirects.map((redirect) => redirect.source.replace(/\/$/, "") || "/"));
+  const redirectSources = new Set(redirects.map((redirect) => (redirect.source.replace(/\/$/, "") || "/").toLowerCase()));
   function hasAuthoredRedirect(source) {
-    if (redirectSources.has(source)) return true;
+    const route = source.toLowerCase();
+    if (redirectSources.has(route)) return true;
     return (config.redirects ?? []).some((redirect) => {
-      const match = redirect.source.match(/^(.*)\/:[A-Za-z_][A-Za-z0-9_]*\*\/?$/);
-      return match ? source === match[1] || source.startsWith(`${match[1]}/`) : false;
+      const match = redirect.source.toLowerCase().match(/^(.*)\/:[a-z_][a-z0-9_]*\*\/?$/);
+      return match ? route === match[1] || route.startsWith(`${match[1]}/`) : false;
     });
   }
   for (const page of pages) {
     if (!/\/(?:overview|introduction)$/.test(page.navigationId)) continue;
     const parent = page.id.replace(/\/(?:overview|introduction)$/, "");
-    if (!parent || pageIds.has(parent)) continue;
+    if (!parent || pageIds.has(parent.toLowerCase())) continue;
     const source = `/${parent}`;
     if (hasAuthoredRedirect(source)) continue;
     redirects.push({ source, destination: `/${page.id}`, permanent: false });
-    redirectSources.add(source);
+    redirectSources.add(source.toLowerCase());
   }
   const navigationOrder = [];
   function collectPages(nodes) {
@@ -4285,11 +4286,11 @@ function addMintlifyDirectoryRedirects(config, pages) {
     }
   }
   for (const [directory, landing] of firstDescendantByDirectory) {
-    if (pageIds.has(directory)) continue;
+    if (pageIds.has(directory.toLowerCase())) continue;
     const source = `/${directory}`;
     if (hasAuthoredRedirect(source)) continue;
     redirects.push({ source, destination: `/${landing.id}`, permanent: false });
-    redirectSources.add(source);
+    redirectSources.add(source.toLowerCase());
   }
   return redirects.length > 0 ? { ...config, redirects } : config;
 }
@@ -4308,11 +4309,11 @@ function addMintlifyHomepageRedirects(config, pages) {
   const homepage = config.tabs.filter((tab) => !tab.hidden).map((tab) => firstPage([...tab.pages ?? [], ...tab.groups ?? []])).find(Boolean);
   if (!homepage) return config;
   const redirects = [...config.redirects ?? []];
-  const sources = new Set(redirects.map((redirect) => redirect.source.replace(/\/$/, "") || "/"));
+  const sources = new Set(redirects.map((redirect) => (redirect.source.replace(/\/$/, "") || "/").toLowerCase()));
   const roots = ["", ...(config.i18n?.locales ?? []).filter((locale) => locale.code !== config.i18n?.defaultLocale).filter((locale) => homepage !== "introduction" || pages.some((page) => page.locale === locale.code && page.navigationId === homepage)).map((locale) => locale.code)];
   for (const locale of roots) {
     const source = locale ? `/${locale}` : "/";
-    if (sources.has(source)) continue;
+    if (sources.has(source.toLowerCase())) continue;
     redirects.push({ source, destination: `${locale ? `/${locale}` : ""}/${homepage}`, permanent: true });
   }
   return { ...config, redirects };
@@ -4439,6 +4440,22 @@ function specSource(value) {
   const source = typeof value === "string" ? value : objectValue2(value)?.source;
   return typeof source === "string" && source.trim() ? source.trim() : void 0;
 }
+function listedOperations(container) {
+  const operations = [];
+  const visit = (entry, root) => {
+    if (typeof entry === "string") {
+      if (OPENAPI_OPERATION_REF.test(entry)) operations.push(entry.trim());
+      return;
+    }
+    const object2 = objectValue2(entry);
+    if (!object2 || !root && (specSource(object2.openapi) || specSource(object2.asyncapi))) return;
+    for (const key of ["groups", "pages"]) {
+      if (Array.isArray(object2[key])) object2[key].forEach((child) => visit(child, false));
+    }
+  };
+  visit(container, true);
+  return operations;
+}
 var hasNavigationChildren = (node) => ["groups", "pages"].some((key) => Array.isArray(node[key]) && node[key].length > 0);
 function mintlifyNavigationApiReferences(config) {
   const navigation = objectValue2(config.navigation) ?? config;
@@ -4450,12 +4467,14 @@ function mintlifyNavigationApiReferences(config) {
       const value = specSource(node[kind]);
       const directory = objectValue2(node[kind])?.directory;
       if (value) {
+        const operations = typeof directory === "string" && directory.trim() ? listedOperations(node) : [];
         references.push({
           value,
           kind,
           tabLabel,
           ...sibling,
-          ...typeof directory === "string" && directory.trim() ? { directory: directory.trim() } : {}
+          ...typeof directory === "string" && directory.trim() ? { directory: directory.trim() } : {},
+          ...operations.length > 0 ? { operations } : {}
         });
       }
     }
@@ -7206,16 +7225,32 @@ function withheldOperationKeys(spec, withheldRefs, keptRefs) {
   const kept = keysFor(spec, keptRefs);
   return { withheld: keysFor(spec, withheldRefs).filter((key) => !kept.includes(key)), kept };
 }
+function withoutByteOrderMark(content) {
+  return content.length >= 3 && content[0] === 239 && content[1] === 187 && content[2] === 191 ? content.subarray(3) : content;
+}
+function parseSpecDocument(text3) {
+  const source = text3.replace(/^\uFEFF/, "");
+  try {
+    return { format: "json", document: JSON.parse(source) };
+  } catch (jsonError) {
+    try {
+      return { format: "yaml", document: parseYaml4(source) };
+    } catch (yamlError) {
+      throw source.trimStart().startsWith("{") ? jsonError : yamlError;
+    }
+  }
+}
 function markExcluded(content, operationKeys, keptKeys = []) {
   const untouched = { content, excluded: [] };
   if (operationKeys.length === 0) return untouched;
   const text3 = content.toString("utf8");
-  let doc;
+  let parsed;
   try {
-    doc = parseYaml4(text3);
+    parsed = parseSpecDocument(text3);
   } catch {
     return untouched;
   }
+  const doc = parsed.document;
   if (!doc || typeof doc !== "object") return untouched;
   const excluded = [];
   for (const key of operationKeys) {
@@ -7238,7 +7273,7 @@ function markExcluded(content, operationKeys, keptKeys = []) {
     }
   }
   if (excluded.length === 0) return untouched;
-  const out = text3.trimStart().startsWith("{") ? `${JSON.stringify(doc, null, 2)}
+  const out = parsed.format === "json" ? `${JSON.stringify(doc, null, 2)}
 ` : stringifyYaml(doc);
   return { content: Buffer.from(out), excluded };
 }
@@ -7469,6 +7504,150 @@ function migrationImageAttribute(value) {
   return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\{/g, "&#123;").replace(/\}/g, "&#125;").replace(/\r/g, "&#13;").replace(/\n/g, "&#10;");
 }
 
+// src/redirects.ts
+var LISTED = 10;
+function exactRoute(route) {
+  return route.startsWith("/") && !/[?:*#()[\]{}]/.test(route) ? route.replace(/\/+$/, "") || "/" : null;
+}
+function literalRoute(route) {
+  return exactRoute(route)?.toLowerCase() ?? null;
+}
+function resolveDotSegments(route) {
+  const segments = [];
+  for (const segment of route.split("/").slice(1)) {
+    const dots = segment.replace(/%2e/gi, ".");
+    if (dots === "..") segments.pop();
+    else if (dots !== ".") segments.push(segment);
+  }
+  return `/${segments.join("/")}`;
+}
+function destinationRoute(destination) {
+  const route = destination.startsWith("//") ? null : exactRoute(destination.split(/[?#]/, 1)[0]);
+  return route === null ? null : resolveDotSegments(route);
+}
+function pageRoutes(pages) {
+  return pages.flatMap((page) => [`/${page.id}`, `/${page.id.replace(/\/index$/, "")}`]);
+}
+function servedRoutes(pages) {
+  return new Set(pageRoutes(pages).map((route) => route.toLowerCase()));
+}
+function list(sources) {
+  return `${sources.slice(0, LISTED).join(", ")}${sources.length > LISTED ? ", ..." : ""}`;
+}
+var ROUTE_PATTERN_OPERATORS = /[+?()[\]{}]/;
+function dropUnroutableRedirects(config, warnings) {
+  if (!config.redirects?.length) return config;
+  const unmatchable = [];
+  const redirects = config.redirects.filter((redirect) => {
+    const source = exactRoute(redirect.source);
+    if (source && source === exactRoute(redirect.destination)) {
+      warnings.push({ code: "unsupported-config", message: `Self-redirect from ${redirect.source} to ${redirect.destination} was omitted.` });
+      return false;
+    }
+    if (!ROUTE_PATTERN_OPERATORS.test(redirect.source)) return true;
+    unmatchable.push(redirect.source);
+    return false;
+  });
+  if (unmatchable.length > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      message: `Skipped ${unmatchable.length} redirect${unmatchable.length === 1 ? "" : "s"} from ${list(unmatchable)}: ${unmatchable.length === 1 ? "that address has" : "those addresses have"} a character (+ ? ( ) [ ] { }) that Next.js reads as route syntax and cannot match literally, so visits to ${unmatchable.length === 1 ? "it" : "them"} will not redirect.`
+    });
+  }
+  if (redirects.length === config.redirects.length) return config;
+  const result = { ...config, redirects };
+  if (redirects.length === 0) delete result.redirects;
+  return result;
+}
+function redirectChains() {
+  const kept = /* @__PURE__ */ new Map();
+  const terminal = /* @__PURE__ */ new Set();
+  const has = (source) => kept.has(source) || terminal.has(source);
+  const add = (source, destination) => {
+    if (destination === null) terminal.add(source);
+    else kept.set(source, destination);
+  };
+  const closesLoop = (source, destination) => {
+    let end = destination;
+    for (let steps = 0; kept.has(end); steps++) {
+      if (steps >= kept.size) return true;
+      end = kept.get(end);
+    }
+    for (let step = destination; step !== end; ) {
+      const next = kept.get(step);
+      kept.set(step, end);
+      step = next;
+    }
+    return end === source;
+  };
+  return { has, add, closesLoop };
+}
+function dropConflictingRedirects(config, pages, warnings) {
+  if (!config.redirects?.length) return config;
+  const served = servedRoutes(pages);
+  const servedAsWritten = new Set(pageRoutes(pages));
+  const hidden = [];
+  const hiddenByCase = [];
+  const looping = [];
+  const loopingByCase = [];
+  const folded = redirectChains();
+  const asWritten = redirectChains();
+  const redirects = config.redirects.filter((redirect) => {
+    const source = literalRoute(redirect.source);
+    if (!source) return true;
+    const writtenSource = exactRoute(redirect.source);
+    if (served.has(source)) {
+      const hides = servedAsWritten.has(writtenSource) ? hidden : hiddenByCase;
+      hides.push(redirect.source);
+      return false;
+    }
+    const writtenDestination = destinationRoute(redirect.destination);
+    const destination = writtenDestination?.toLowerCase() ?? null;
+    const firesFolded = !folded.has(source);
+    const firesAsWritten = !asWritten.has(writtenSource);
+    const loopsFolded = firesFolded && destination !== null && folded.closesLoop(source, destination);
+    const loopsAsWritten = firesAsWritten && writtenDestination !== null && asWritten.closesLoop(writtenSource, writtenDestination);
+    if (loopsFolded || loopsAsWritten) {
+      const loops = loopsAsWritten ? looping : loopingByCase;
+      loops.push(`${redirect.source} -> ${redirect.destination}`);
+      return false;
+    }
+    if (firesFolded) folded.add(source, destination);
+    if (firesAsWritten) asWritten.add(writtenSource, writtenDestination);
+    return true;
+  });
+  if (hidden.length > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      message: `Skipped ${hidden.length} redirect${hidden.length === 1 ? "" : "s"} from ${list(hidden)}: ${hidden.length === 1 ? "that URL is" : "those URLs are"} also ${hidden.length === 1 ? "a page" : "pages"} in this site, and a redirect would hide ${hidden.length === 1 ? "it" : "them"}. To redirect instead, delete the page and add the redirect to docs.json.`
+    });
+  }
+  if (hiddenByCase.length > 0) {
+    const one = hiddenByCase.length === 1;
+    warnings.push({
+      code: "unsupported-config",
+      message: `Skipped ${hiddenByCase.length} redirect${one ? "" : "s"} from ${list(hiddenByCase)}: ${one ? "that URL differs" : "those URLs differ"} only in letter case from ${one ? "a page" : "pages"} in this site, so on a server that ignores letter case ${one ? "it" : "they"} would hide ${one ? "that page" : "those pages"}. If your host matches URLs case-sensitively, add ${one ? "it" : "them"} back to docs.json.`
+    });
+  }
+  if (looping.length > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      message: `Skipped ${looping.length} redirect${looping.length === 1 ? "" : "s"} that would send visitors in a circle: ${list(looping)}. Check these redirects in the source docs.`
+    });
+  }
+  if (loopingByCase.length > 0) {
+    const one = loopingByCase.length === 1;
+    warnings.push({
+      code: "unsupported-config",
+      message: `Skipped ${loopingByCase.length} redirect${one ? "" : "s"} that would send visitors in a circle on a server that ignores letter case, since the addresses involved differ only in letter case: ${list(loopingByCase)}. If your host matches URLs case-sensitively, add ${one ? "it" : "them"} back to docs.json.`
+    });
+  }
+  if (redirects.length === config.redirects.length) return config;
+  const result = { ...config, redirects };
+  if (redirects.length === 0) delete result.redirects;
+  return result;
+}
+
 // src/url.ts
 var DEFAULT_MAX_PAGES = 1e3;
 var DEFAULT_MAX_TOTAL_BYTES = 1e8;
@@ -8443,13 +8622,13 @@ function migrationHtmlArticle(body) {
     const sourceId = select.attr("id");
     if (sourceId) projection.attr("id", sourceId);
     projection.append($("<p></p>").text(select.attr("aria-label")));
-    const list = $("<ul></ul>");
+    const list2 = $("<ul></ul>");
     for (const url of urls) {
       const item = $("<li></li>").append($("<a></a>").attr("href", url.href).text(url.label));
       if (url.isSelected) item.append(" (selected)");
-      list.append(item);
+      list2.append(item);
     }
-    projection.append(list);
+    projection.append(list2);
     select.replaceWith(projection);
   });
   return { $, root };
@@ -8691,8 +8870,8 @@ function readDocusaurusSidebar(document) {
   const $ = load2(document.body);
   const sidebar = $("ul.theme-doc-sidebar-menu").first();
   if (sidebar.length === 0) return null;
-  function readList(list) {
-    return $(list).children("li").toArray().flatMap((item) => {
+  function readList(list2) {
+    return $(list2).children("li").toArray().flatMap((item) => {
       const directLink = $(item).children("a.menu__link").first();
       const collapsibleLink = $(item).children(".menu__list-item-collapsible").children("a.menu__link").first();
       const link = directLink.length > 0 ? directLink : collapsibleLink;
@@ -9255,6 +9434,7 @@ async function migrateUrl(options) {
     };
   }
   if (platform === "mintlify") docsConfig = addMintlifyDirectoryRedirects(docsConfig, pages);
+  docsConfig = dropConflictingRedirects(dropUnroutableRedirects(docsConfig, warnings), pages, warnings);
   return {
     sourceUrl: source.toString(),
     sourceKind: "url",
@@ -10402,7 +10582,7 @@ function readSpecFile(absolutePath, relativePath, warnings) {
     });
     return void 0;
   }
-  return readFileSync6(absolutePath);
+  return withoutByteOrderMark(readFileSync6(absolutePath));
 }
 function specAssetPath(filename) {
   return `${SPEC_DIRECTORY}/${filename}`;
@@ -10438,10 +10618,26 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
     references.push({ value: key, kind: "openapi", tabLabel: `OpenAPI: ${key}`, hidden: true, pageOnly: true });
   }
   const seen = /* @__PURE__ */ new Set();
+  const remoteByKey = /* @__PURE__ */ new Map();
+  const mountDirectory = (remote, reference) => {
+    const directory = reference.directory?.replace(/^\/+|\/+$/g, "");
+    if (!remote || !directory) return;
+    const mount = remote.directories?.find((existing) => existing.directory === directory);
+    if (!mount) {
+      remote.directories = [...remote.directories ?? [], { directory, ...reference.operations ? { operations: reference.operations } : {} }];
+    } else if (mount.operations && reference.operations) {
+      mount.operations = [.../* @__PURE__ */ new Set([...mount.operations, ...reference.operations])];
+    } else {
+      delete mount.operations;
+    }
+  };
   const specs = [];
   for (const reference of references) {
     const dedupeKey = `${reference.kind}:${reference.value}:${reference.tabLabel ?? ""}`;
-    if (seen.has(dedupeKey)) continue;
+    if (seen.has(dedupeKey)) {
+      mountDirectory(remoteByKey.get(dedupeKey), reference);
+      continue;
+    }
     seen.add(dedupeKey);
     const tabSuffix = reference.tabLabel ? ` (tab "${reference.tabLabel}")` : "";
     if (reference.kind === "asyncapi") {
@@ -10452,7 +10648,10 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
       continue;
     }
     if (/^https:\/\//i.test(reference.value)) {
-      remoteSpecs.push({ url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {} });
+      const remote = { url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {} };
+      mountDirectory(remote, reference);
+      remoteSpecs.push(remote);
+      remoteByKey.set(dedupeKey, remote);
       warnings.push({
         code: "unsupported-config",
         message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} requires a network download before this import is complete.`,
@@ -10552,10 +10751,15 @@ function thallyOperationSlugSegments(path, method) {
 function slugifyApiSpecId(value) {
   return value.toLowerCase().replace(/[^a-z0-9/]+/g, "-").replace(/(^-|-$)+/g, "").replace(/\//g, "-") || value.toLowerCase();
 }
+function apiTabSpecIds(tabs) {
+  return tabs.filter((tab) => !tab.hidden && tab.api).map((tab, index) => ({ tab, specId: index === 0 ? "default" : slugifyApiSpecId(tab.tab) }));
+}
+var flagged = (value) => value === true || value === "true";
+var isWithheld = (node) => flagged(node["x-hidden"]) || flagged(node["x-excluded"]);
 function parseOpenApiOperationsForLinking(content) {
   let document;
   try {
-    document = parseYaml6(content.toString("utf8"));
+    document = parseSpecDocument(content.toString("utf8")).document;
   } catch {
     return [];
   }
@@ -10564,10 +10768,13 @@ function parseOpenApiOperationsForLinking(content) {
   const operations = [];
   for (const [path, pathItem] of Object.entries(paths)) {
     if (!pathItem || typeof pathItem !== "object") continue;
+    const item = pathItem;
+    if (isWithheld(item)) continue;
     for (const method of OPENAPI_HTTP_METHODS) {
-      const operation = pathItem[method];
+      const operation = item[method];
       if (!operation || typeof operation !== "object") continue;
       const op = operation;
+      if (isWithheld(op)) continue;
       const tags = Array.isArray(op.tags) ? op.tags.filter((tag) => typeof tag === "string") : [];
       operations.push({
         method,
@@ -10580,19 +10787,39 @@ function parseOpenApiOperationsForLinking(content) {
   }
   return operations;
 }
-function apiOperationLinkMap(sources, docsConfig) {
+function servedOperations(source, parsed) {
+  let operations = parsed.get(source.filename);
+  if (!operations) {
+    operations = parseOpenApiOperationsForLinking(source.content);
+    parsed.set(source.filename, operations);
+  }
+  if (!source.operations) return operations;
+  const byKey = new Map(operations.map((operation) => [`${operation.method} ${operation.path}`, operation]));
+  return source.operations.flatMap((reference) => {
+    const [method, ...path] = reference.trim().split(/\s+/);
+    const operation = byKey.get(`${method.toLowerCase()} ${path.join(" ")}`);
+    return operation ? [operation] : [];
+  });
+}
+var mountPrefix = (directory) => directory.replace(/^\/+|\/+$/g, "").toLowerCase();
+function apiOperationLinkMap(sources, docsConfig, otherMounts = []) {
   const map = /* @__PURE__ */ new Map();
   const prefixLandings = /* @__PURE__ */ new Map();
   const mintlifyPages = /* @__PURE__ */ new Map();
   const duplicatePages = [];
-  const apiTabs = docsConfig.tabs.filter((tab) => !tab.hidden && tab.api);
-  apiTabs.forEach((tab, index) => {
-    const source = sources.find((entry) => tab.api?.source === specAssetPath(entry.filename));
-    if (!source || !source.prefix) return;
-    const specId = index === 0 ? "default" : slugifyApiSpecId(tab.tab);
-    const prefix = source.prefix.replace(/^\/+|\/+$/g, "").toLowerCase();
+  const parsedByFile = /* @__PURE__ */ new Map();
+  const bound = apiTabSpecIds(docsConfig.tabs).flatMap(({ tab, specId }) => sources.filter((entry) => tab.api?.source === specAssetPath(entry.filename) && (!entry.tab || entry.tab === tab.tab)).map((source) => ({ source, specId })));
+  const mounts = new Set([...bound.map(({ source }) => source.prefix ? mountPrefix(source.prefix) : ""), ...otherMounts.map(mountPrefix)].filter(Boolean));
+  const underDeeperMount = (route, own2) => {
+    const lower = route.toLowerCase();
+    return [...mounts].some((mount) => mount.length > own2.length && (lower === mount || lower.startsWith(`${mount}/`)));
+  };
+  bound.forEach(({ source, specId }) => {
+    if (!source.prefix) return;
+    const base = source.prefix.replace(/^\/+|\/+$/g, "");
+    const prefix = mountPrefix(source.prefix);
     if (prefix) prefixLandings.set(prefix, specId === "default" ? "/api" : `/api/${specId}`);
-    for (const operation of parseOpenApiOperationsForLinking(source.content)) {
+    for (const operation of servedOperations(source, parsedByFile)) {
       const thallyHref = `/api/${specId}/${thallyOperationSlugSegments(operation.path, operation.method).join("/")}`;
       const leafCandidates = /* @__PURE__ */ new Set();
       if (operation.operationId) {
@@ -10608,31 +10835,66 @@ function apiOperationLinkMap(sources, docsConfig) {
       const tagSegment = mintlifyOperationSlugSegment(operation.tag ?? "default");
       const mintlifyTag = mintlifyUrlSlug(operation.tag ?? "default");
       const mintlifyLeaf = mintlifyUrlSlug(operation.summary?.trim() || operation.operationId?.trim() || `${operation.method} ${operation.path}`);
-      const canonical2 = `${source.prefix}/${mintlifyTag}/${mintlifyLeaf}`.replace(/^\/+|\/+$/g, "");
-      if (mintlifyTag && mintlifyLeaf) {
+      const canonical2 = `${base}/${mintlifyTag}/${mintlifyLeaf}`.replace(/^\/+|\/+$/g, "");
+      if (mintlifyTag && mintlifyLeaf && !underDeeperMount(canonical2, prefix)) {
         if (!mintlifyPages.has(canonical2)) mintlifyPages.set(canonical2, thallyHref);
         else if (mintlifyPages.get(canonical2) !== thallyHref && !duplicatePages.includes(canonical2)) duplicatePages.push(canonical2);
+        if (!map.has(canonical2.toLowerCase())) map.set(canonical2.toLowerCase(), thallyHref);
+      }
+      const tagRoot = `${base}/${mintlifyTag}`.replace(/^\/+|\/+$/g, "");
+      if (mintlifyTag && !underDeeperMount(tagRoot, prefix)) {
+        if (!mintlifyPages.has(tagRoot)) mintlifyPages.set(tagRoot, thallyHref);
+        if (!map.has(tagRoot.toLowerCase())) map.set(tagRoot.toLowerCase(), thallyHref);
       }
-      if (mintlifyTag && mintlifyLeaf && !map.has(canonical2.toLowerCase())) map.set(canonical2.toLowerCase(), thallyHref);
-      const tagRoot = `${source.prefix}/${mintlifyTag}`.replace(/^\/+|\/+$/g, "");
-      if (mintlifyTag && !mintlifyPages.has(tagRoot)) mintlifyPages.set(tagRoot, thallyHref);
-      if (mintlifyTag && !map.has(tagRoot.toLowerCase())) map.set(tagRoot.toLowerCase(), thallyHref);
       for (const leaf of leafCandidates) {
         if (!leaf) continue;
-        const tagged = `${source.prefix}/${tagSegment}/${leaf}`.replace(/^\/+|\/+$/g, "").toLowerCase();
-        const flat = `${source.prefix}/${leaf}`.replace(/^\/+|\/+$/g, "").toLowerCase();
-        if (!map.has(tagged)) map.set(tagged, thallyHref);
-        if (!map.has(flat)) map.set(flat, thallyHref);
+        const tagged = `${base}/${tagSegment}/${leaf}`.replace(/^\/+|\/+$/g, "").toLowerCase();
+        const flat = `${base}/${leaf}`.replace(/^\/+|\/+$/g, "").toLowerCase();
+        if (!map.has(tagged) && !underDeeperMount(tagged, prefix)) map.set(tagged, thallyHref);
+        if (!map.has(flat) && !underDeeperMount(flat, prefix)) map.set(flat, thallyHref);
       }
     }
   });
   return { operationLinks: map, prefixLandings, mintlifyPages, duplicatePages };
 }
-function rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings) {
+function mintlifyEndpointRedirects(maps, pages, existing, warnings) {
+  const { mintlifyPages, duplicatePages } = maps;
+  if (duplicatePages.length > 0) {
+    const listed = duplicatePages.slice(0, 10).map((url) => `/${url}`).join(", ");
+    warnings.push({
+      code: "unsupported-config",
+      message: `${duplicatePages.length} Mintlify endpoint URL${duplicatePages.length === 1 ? " is" : "s are"} shared by more than one operation (same tag and summary), so only the first operation is redirected from each: ${listed}${duplicatePages.length > 10 ? ", ..." : ""}.`
+    });
+  }
+  const taken = servedRoutes(pages);
+  for (const redirect of existing) taken.add(literalRoute(redirect.source) ?? redirect.source);
+  const candidates = [...mintlifyPages].filter(([source]) => !taken.has(literalRoute(`/${source}`) ?? `/${source}`));
+  const redirects = candidates.slice(0, MAX_ENDPOINT_REDIRECTS).map(([source, destination]) => ({ source: `/${source}`, destination }));
+  const capped = candidates.length - redirects.length;
+  if (capped > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      message: `Created ${redirects.length} of ${candidates.length} Mintlify endpoint redirects; skipped ${capped} because a site is limited to ${MAX_ENDPOINT_REDIRECTS} generated endpoint redirects. Old links to skipped endpoint URLs will not redirect.`
+    });
+  }
+  return redirects;
+}
+function linkApiMounts(sources, docsConfig, pages, warnings, reservedMounts = []) {
+  const maps = apiOperationLinkMap(sources, docsConfig, reservedMounts);
+  rewriteApiLinksInPages(pages, maps.operationLinks, maps.prefixLandings, warnings, { mounts: reservedMounts, redirects: docsConfig.redirects });
+  return mintlifyEndpointRedirects(maps, pages, docsConfig.redirects ?? [], warnings);
+}
+function rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings, answered = {}) {
   if (operationLinks.size === 0 && prefixLandings.size === 0) return;
   const unmatched = /* @__PURE__ */ new Set();
+  const served = servedRoutes(pages);
+  for (const { source } of answered.redirects ?? []) {
+    const route = literalRoute(source);
+    if (route) served.add(route);
+  }
+  const others = (answered.mounts ?? []).map(mountPrefix).filter(Boolean);
   for (const page of pages) {
-    page.body = rewriteApiOperationLinks(page.body, operationLinks, prefixLandings, unmatched);
+    page.body = rewriteApiOperationLinks(page.body, operationLinks, prefixLandings, served, unmatched, others);
   }
   if (unmatched.size === 0) return;
   const sorted = [...unmatched].sort();
@@ -10641,7 +10903,7 @@ function rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings)
     message: `${sorted.length} link(s) to API endpoints matched no endpoint in the OpenAPI spec, so they now point to the API section's overview page instead: ${sorted.slice(0, 10).join(", ")}${sorted.length > 10 ? `, and ${sorted.length - 10} more` : ""}. Update those links if you want them to reach a specific endpoint.`
   });
 }
-function rewriteApiOperationLinks(body, linkMap, prefixLandings, unmatched) {
+function rewriteApiOperationLinks(body, linkMap, prefixLandings, served, unmatched, otherMounts) {
   if (linkMap.size === 0 && prefixLandings.size === 0) return body;
   const orderedPrefixes = [...prefixLandings.entries()].sort((a, b) => b[0].length - a[0].length);
   let codeFence = null;
@@ -10655,8 +10917,12 @@ function rewriteApiOperationLinks(body, linkMap, prefixLandings, unmatched) {
     if (codeFence) return line;
     const rewriteTarget = (target2) => {
       const suffixIndex = target2.search(/[?#]/);
-      const path = (suffixIndex >= 0 ? target2.slice(0, suffixIndex) : target2).replace(/^\/+/, "").toLowerCase();
+      const literal = suffixIndex >= 0 ? target2.slice(0, suffixIndex) : target2;
+      if (served.has(literalRoute(literal) ?? literal)) return target2;
+      const path = literal.replace(/^\/+|\/+$/g, "").toLowerCase();
       const suffix = suffixIndex >= 0 ? target2.slice(suffixIndex) : "";
+      const owner = [...prefixLandings.keys(), ...otherMounts].filter((mount) => path === mount || path.startsWith(`${mount}/`)).reduce((longest, mount) => longest === null || mount.length > longest.length ? mount : longest, null);
+      if (owner !== null && !prefixLandings.has(owner)) return target2;
       const mapped = linkMap.get(path);
       if (mapped) return `${mapped}${suffix}`;
       for (const [prefix, landing] of orderedPrefixes) {
@@ -12028,6 +12294,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
   const sourceRefPages = [];
   const sourceRefAssets = [];
   const remoteApiSpecs = [];
+  const localApiMounts = [];
   const referencedAssetPaths = /* @__PURE__ */ new Map();
   const addAssetReference = (assetPath, referencingPage) => {
     const referrers = referencedAssetPaths.get(assetPath);
@@ -12994,7 +13261,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
         resolvedSpecs.map((spec) => ({ filename: spec.filename, content: spec.content, prefix: spec.routeSegments.join("/") })),
         docsConfig
       );
-      rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings);
+      rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings, { redirects: docsConfig.redirects });
     }
   } else if (platform === "mintlify") {
     const warnSharedSpec = (path, excluded = []) => {
@@ -13029,34 +13296,17 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
         spec.generatedNavigation = Boolean(spec.directory) && !publishedSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true));
       }
       docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs, warnings);
-      const { operationLinks, prefixLandings, mintlifyPages, duplicatePages } = apiOperationLinkMap(
-        resolvedSpecs.map((spec) => ({ filename: spec.filename, content: spec.content, prefix: spec.directory })),
-        docsConfig
-      );
-      rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings);
-      if (duplicatePages.length > 0) {
-        const listed = duplicatePages.slice(0, 10).map((url) => `/${url}`).join(", ");
-        warnings.push({
-          code: "unsupported-config",
-          message: `${duplicatePages.length} Mintlify endpoint URL${duplicatePages.length === 1 ? " is" : "s are"} shared by more than one operation (same tag and summary), so only the first operation is redirected from each: ${listed}${duplicatePages.length > 10 ? ", ..." : ""}.`
-        });
-      }
-      const taken = /* @__PURE__ */ new Set([...pages.map((page) => page.id), ...(docsConfig.redirects ?? []).map((redirect) => redirect.source.replace(/^\//, ""))]);
-      const candidates = [...mintlifyPages].filter(([source]) => !taken.has(source));
-      const endpointRedirects = candidates.slice(0, MAX_ENDPOINT_REDIRECTS).map(([source, destination]) => ({ source: `/${source}`, destination }));
-      const alreadyTaken = mintlifyPages.size - candidates.length;
-      const capped = candidates.length - endpointRedirects.length;
-      if (alreadyTaken + capped > 0) {
-        const reasons = [
-          alreadyTaken > 0 ? `${alreadyTaken} because the URL already has a page or redirect` : "",
-          capped > 0 ? `${capped} because a site is limited to ${MAX_ENDPOINT_REDIRECTS} generated endpoint redirects` : ""
-        ].filter(Boolean).join(" and ");
-        warnings.push({
-          code: "unsupported-config",
-          message: `Created ${endpointRedirects.length} of ${mintlifyPages.size} Mintlify endpoint redirects; skipped ${alreadyTaken + capped}: ${reasons}. Old links to skipped endpoint URLs will not redirect.`
-        });
+      if (remoteApiSpecs.length > 0) {
+        localApiMounts.push(...resolvedSpecs.flatMap((spec) => spec.directory ? [{ filename: spec.filename, directory: spec.directory, ...spec.tabLabel ? { tab: spec.tabLabel } : {} }] : []));
+      } else {
+        const endpointRedirects = linkApiMounts(
+          resolvedSpecs.map((spec) => ({ filename: spec.filename, content: spec.content, prefix: spec.directory, ...spec.tabLabel ? { tab: spec.tabLabel } : {} })),
+          docsConfig,
+          pages,
+          warnings
+        );
+        if (endpointRedirects.length > 0) docsConfig = { ...docsConfig, redirects: [...docsConfig.redirects ?? [], ...endpointRedirects] };
       }
-      if (endpointRedirects.length > 0) docsConfig = { ...docsConfig, redirects: [...docsConfig.redirects ?? [], ...endpointRedirects] };
     } else {
       const fallback = findOpenApi(files);
       const fallbackContent = fallback ? readSpecFile(fallback.absolutePath, fallback.relativePath, warnings) : void 0;
@@ -13099,8 +13349,9 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
     if (docsConfig.tabs.some((tab) => tab.api)) docsConfig = { ...docsConfig, api: { ...docsConfig.api, specLink: false } };
   }
   if (platform === "mintlify") {
-    const sources = new Set((docsConfig.redirects ?? []).map((redirect) => redirect.source));
-    const aliases = routeAliases.filter((redirect) => !sources.has(redirect.source));
+    const sources = new Set((docsConfig.redirects ?? []).map((redirect) => redirect.source.toLowerCase()));
+    const served = servedRoutes(pages);
+    const aliases = routeAliases.filter((redirect) => !sources.has(redirect.source.toLowerCase()) && !served.has(literalRoute(redirect.source) ?? redirect.source));
     if (aliases.length > 0) docsConfig = { ...docsConfig, redirects: [...docsConfig.redirects ?? [], ...aliases] };
     docsConfig = addMintlifyHomepageRedirects(addMintlifyDirectoryRedirects(docsConfig, pages), pages);
     const reachablePaths = /* @__PURE__ */ new Set([
@@ -13314,26 +13565,7 @@ ${body}`;
     }
   }
   if (docsConfig.redirects) {
-    docsConfig = {
-      ...docsConfig,
-      redirects: docsConfig.redirects.filter((redirect) => {
-        const literalRoute = (route) => route.startsWith("/") && !/[?:*#()[\]{}]/.test(route) ? route.replace(/\/+$/, "") || "/" : null;
-        const sourceRoute = literalRoute(redirect.source);
-        if (sourceRoute && sourceRoute === literalRoute(redirect.destination)) {
-          warnings.push({
-            code: "unsupported-config",
-            message: `Self-redirect from ${redirect.source} to ${redirect.destination} was omitted.`
-          });
-          return false;
-        }
-        if (!/[+?()[\]{}]/.test(redirect.source)) return true;
-        warnings.push({
-          code: "unsupported-config",
-          message: `Redirect from ${redirect.source} contains route-pattern syntax Next.js cannot express literally and was omitted.`
-        });
-        return false;
-      })
-    };
+    docsConfig = dropConflictingRedirects(dropUnroutableRedirects(docsConfig, warnings), [...pages, ...sourceRefPages], warnings);
   }
   if (pages.length === 0) {
     const reasons = warnings.map((warning) => warning.message);
@@ -13546,6 +13778,7 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     assets,
     ...importedSourceRefs.length > 0 ? { sourceRefs: importedSourceRefs } : {},
     ...remoteApiSpecs.length > 0 ? { remoteApiSpecs } : {},
+    ...remoteApiSpecs.length > 0 && localApiMounts.length > 0 ? { localApiMounts } : {},
     ...componentMigrator ? { componentFiles: componentMigrator.files() } : {},
     ...quarantinedFiles.length > 0 ? { quarantinedFiles } : {},
     ...droppedGatedFiles.length > 0 ? { droppedGatedPages: droppedGatedFiles.length } : {},
@@ -14358,7 +14591,7 @@ function mergeSourceNavigation(existing, incoming) {
 }
 
 // src/url-run.ts
-var CONVERTER_VERSION = "url-evidence-v3";
+var CONVERTER_VERSION = "url-evidence-v4";
 var parser2 = unified4().use(remarkParse4).use(remarkMdx4);
 var ACCEPT = "text/markdown,text/html,application/xhtml+xml;q=0.9";
 var MAX_RESPONSE_BYTES = 8e6;
@@ -14617,21 +14850,22 @@ function resolveMigrationRecord(records, record) {
   }
   return record;
 }
-function navigationConfig(navigation, records) {
+function navigationConfig(checkpoint, records) {
+  const navigation = checkpoint.navigation;
+  const projection = localeProjection(checkpoint);
   const project2 = (nodes) => nodes.flatMap((node) => {
     const record = node.url ? records.get(canonical(node.url, node.url) ?? "") : void 0;
     const target2 = resolveMigrationRecord(records, record);
     const page = target2?.page;
     const children = project2(node.children ?? []);
     if (children.length) {
-      const contains = (entries) => entries.some((entry) => typeof entry === "string" ? entry === page?.navigationId : contains(entry.pages));
-      return [{ group: node.label || "Documentation", pages: [...page && !contains(children) ? [page.navigationId] : [], ...children] }];
+      const contains = (entries) => entries.some((entry) => typeof entry === "string" ? entry === (page && projection.navigationId(page)) : contains(entry.pages));
+      return [{ group: node.label || "Documentation", pages: [...page && !contains(children) ? [projection.navigationId(page)] : [], ...children] }];
     }
-    return page ? [page.navigationId] : [];
+    return page ? [projection.navigationId(page)] : [];
   });
   const tabs = navigation.filter((node) => node.kind === "tab");
   if (tabs.length) {
-    const projection = localeProjection({ records: [...records.values()] });
     const locales = [...new Set(tabs.map((tab) => tab.locale ?? projection.defaultLocale))];
     const localizedTabs = (locale) => tabs.filter((tab) => (tab.locale ?? projection.defaultLocale) === locale).flatMap((tab) => {
       const pages2 = project2(tab.children ?? []);
@@ -14649,16 +14883,16 @@ function navigationConfig(navigation, records) {
   const pages = project2(navigation);
   return pages.length ? { tabs: [{ tab: "Documentation", pages }] } : null;
 }
+function canonicalLanguage(value) {
+  if (!/^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,4}$/i.test(value)) return void 0;
+  try {
+    return Intl.getCanonicalLocales(value)[0];
+  } catch {
+    return void 0;
+  }
+}
 function observedLocale(document, id, scopePath) {
   const issues = [];
-  const canonicalLanguage = (value) => {
-    if (!/^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,4}$/i.test(value)) return void 0;
-    try {
-      return Intl.getCanonicalLocales(value)[0];
-    } catch {
-      return void 0;
-    }
-  };
   const candidates = [];
   if (document.locale) {
     const locale = canonicalLanguage(document.locale);
@@ -14680,25 +14914,60 @@ function observedLocale(document, id, scopePath) {
 }
 function localeProjection(checkpoint) {
   const pages = checkpoint.records.flatMap((record) => record.page ? [record.page] : []);
-  const canonicalLocale = (page) => {
+  const declaredLocale = (page) => {
     try {
       return page.locale ? Intl.getCanonicalLocales(page.locale)[0] : void 0;
     } catch {
       return void 0;
     }
   };
+  const declaredLocales = [...new Set(pages.map(declaredLocale).filter((locale) => Boolean(locale)))];
+  const defaultLocale = pages.some((page) => !page.locale) || declaredLocales.includes("en") ? "en" : declaredLocales[0] ?? "en";
+  const records = new Map(checkpoint.records.map((record) => [record.url, record]));
+  const memberships = /* @__PURE__ */ new Map();
+  const observe = (nodes, parentLocale) => {
+    for (const node of nodes) {
+      const locale = node.locale ? canonicalLanguage(node.locale) : parentLocale;
+      const entry = node.url ? records.get(canonical(node.url, checkpoint.sourceUrl) ?? "") : void 0;
+      const page = resolveMigrationRecord(records, entry)?.page;
+      if (page && locale) {
+        const languages = memberships.get(page) ?? /* @__PURE__ */ new Set();
+        languages.add(locale);
+        memberships.set(page, languages);
+      }
+      observe(node.children ?? [], locale);
+    }
+  };
+  observe(checkpoint.navigation);
+  const primaryIds = new Set(pages.filter((page) => !declaredLocale(page) || declaredLocale(page) === defaultLocale).filter((page) => memberships.get(page)?.has(defaultLocale)).map((page) => page.navigationId));
+  const remapped = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    const languages = memberships.get(page);
+    if (languages?.size !== 1) continue;
+    const locale = [...languages][0];
+    const prefix = `${locale.toLowerCase()}-`;
+    if (locale === defaultLocale || !page.navigationId.toLowerCase().startsWith(prefix)) continue;
+    const navigationId2 = page.navigationId.slice(prefix.length);
+    if (primaryIds.has(navigationId2)) remapped.set(page, { locale, navigationId: navigationId2 });
+  }
+  const canonicalLocale = (page) => remapped.get(page)?.locale ?? declaredLocale(page);
+  const navigationId = (page) => remapped.get(page)?.navigationId ?? page.navigationId;
   const locales = [...new Set(pages.map(canonicalLocale).filter((locale) => Boolean(locale)))];
-  const defaultLocale = pages.some((page) => !page.locale) || locales.includes("en") ? "en" : locales[0] ?? "en";
   const pageId = (page) => {
     const locale = canonicalLocale(page);
-    return locale ? `${locale === defaultLocale ? "" : `${locale}/`}${page.navigationId}` : page.id;
+    return locale ? `${locale === defaultLocale ? "" : `${locale}/`}${navigationId(page)}` : page.id;
   };
   const route = (page) => {
     const locale = canonicalLocale(page);
     const prefix = locale && locale !== defaultLocale ? `/${locale}` : "";
-    return `${prefix}${page.navigationId === "introduction" ? "/" : `/${page.navigationId}`}`;
+    return `${prefix}${navigationId(page) === "introduction" ? "/" : `/${navigationId(page)}`}`;
   };
-  return { canonicalLocale, locales, defaultLocale, pageId, route };
+  const redirects = checkpoint.records.flatMap((record) => {
+    if (!record.page || !remapped.has(record.page)) return [];
+    const source = new URL(record.url);
+    return source.search || !/^\/[A-Za-z0-9/_~.%+-]*$/.test(source.pathname) ? [] : [{ source: source.pathname, destination: route(record.page), permanent: true }];
+  });
+  return { canonicalLocale, navigationId, locales, defaultLocale, pageId, route, redirects };
 }
 function validateUrlMigration(checkpoint, cancelled = false) {
   const issues = [];
@@ -14707,7 +14976,7 @@ function validateUrlMigration(checkpoint, cancelled = false) {
   const records = new Map(checkpoint.records.map((record) => [record.url, record]));
   const source = new URL(checkpoint.sourceUrl);
   const projection = localeProjection(checkpoint);
-  const primaryIds = new Set(checkpoint.records.flatMap((record) => record.page && (!record.page.locale || projection.canonicalLocale(record.page) === projection.defaultLocale) ? [record.page.navigationId] : []));
+  const primaryIds = new Set(checkpoint.records.flatMap((record) => record.page && (!projection.canonicalLocale(record.page) || projection.canonicalLocale(record.page) === projection.defaultLocale) ? [projection.navigationId(record.page)] : []));
   const outputIds = /* @__PURE__ */ new Set();
   const resolve4 = (url) => {
     const record = records.get(canonical(url, checkpoint.sourceUrl) ?? "");
@@ -14721,8 +14990,8 @@ function validateUrlMigration(checkpoint, cancelled = false) {
     const outputId = projection.pageId(record.page);
     if (outputIds.has(outputId)) issues.push({ code: "collision", source: record.url, message: `Multiple source pages map to runtime path ${outputId}.` });
     outputIds.add(outputId);
-    if (record.page.locale && projection.canonicalLocale(record.page) !== projection.defaultLocale && !primaryIds.has(record.page.navigationId)) {
-      issues.push({ code: "missing-page", source: record.url, message: `Secondary locale ${record.page.locale} requires a primary ${projection.defaultLocale} page at ${record.page.navigationId}; the runtime cannot serve an orphan translation.` });
+    if (projection.canonicalLocale(record.page) && projection.canonicalLocale(record.page) !== projection.defaultLocale && !primaryIds.has(projection.navigationId(record.page))) {
+      issues.push({ code: "missing-page", source: record.url, message: `Secondary locale ${projection.canonicalLocale(record.page)} requires a primary ${projection.defaultLocale} page at ${projection.navigationId(record.page)}; the runtime cannot serve an orphan translation.` });
     }
     const actual = markdownCode(record.page.body);
     if (JSON.stringify(actual) !== JSON.stringify(record.evidence.code)) issues.push({ code: "code-mismatch", source: record.url, message: "Source code payloads differ from converted code payloads." });
@@ -14756,13 +15025,20 @@ function validateUrlMigration(checkpoint, cancelled = false) {
       }
     }
   }
-  const visit = (nodes) => {
+  const visit = (nodes, parentLocale) => {
     for (const node of nodes) {
+      const locale = node.locale ? canonicalLanguage(node.locale) : parentLocale;
       if (node.url) {
         const url = new URL(node.url, source);
-        if (inScope(url, source, checkpoint.scopePath) && !resolve4(url.toString())?.page) issues.push({ code: "navigation-missing", source: node.url, message: `Source navigation target ${node.label} was not imported.` });
+        if (inScope(url, source, checkpoint.scopePath)) {
+          const page = resolve4(url.toString())?.page;
+          if (!page) issues.push({ code: "navigation-missing", source: node.url, message: `Source navigation target ${node.label} was not imported.` });
+          else if (locale && locale !== projection.defaultLocale && !outputIds.has(`${locale}/${projection.navigationId(page)}`)) {
+            issues.push({ code: "navigation-missing", source: node.url, message: `The ${locale} sidebar target ${node.label} has no authored localized runtime page.` });
+          }
+        }
       }
-      visit(node.children ?? []);
+      visit(node.children ?? [], locale);
     }
   };
   visit(checkpoint.navigation);
@@ -15180,7 +15456,7 @@ ${difference}`;
     }
   };
   labelPages(checkpoint.navigation);
-  const pages = checkpoint.records.flatMap((record) => record.page ? [{ ...record.page, id: projection.pageId(record.page), ...record.page.locale ? { locale: projection.canonicalLocale(record.page) } : {}, ...navigationLabels.has(record.url) ? { navTitle: navigationLabels.get(record.url) } : {}, body: rewriteMarkdownDestinations(record.page.body, (value) => {
+  const pages = checkpoint.records.flatMap((record) => record.page ? [{ ...record.page, id: projection.pageId(record.page), navigationId: projection.navigationId(record.page), ...projection.canonicalLocale(record.page) ? { locale: projection.canonicalLocale(record.page) } : {}, ...navigationLabels.has(record.url) ? { navTitle: navigationLabels.get(record.url) } : {}, body: rewriteMarkdownDestinations(record.page.body, (value) => {
     let url;
     try {
       url = new URL(value, record.evidence.finalUrl);
@@ -15210,11 +15486,12 @@ ${difference}`;
     platform: options.platform ?? "generic",
     pages,
     assets: [...assets.values()],
-    docsConfig: navigationConfig(checkpoint.navigation, records) ?? buildNavigationFromPages(pages),
+    docsConfig: navigationConfig(checkpoint, records) ?? buildNavigationFromPages(pages),
     warnings: [...validation.issues, ...validation.warnings ?? []].map((issue) => ({ code: issue.code === "missing-page" ? "missing-page" : "unsupported-config", message: issue.message, source: issue.source })),
     urlMigrationValidation: validation,
     stats: { discovered: records.size, imported: pages.length, skipped: records.size - pages.length }
   };
+  if (projection.redirects.length) bundle.docsConfig.redirects = projection.redirects;
   if (projection.locales.length) {
     const locales = [.../* @__PURE__ */ new Set([projection.defaultLocale, ...projection.locales])];
     bundle.docsConfig.i18n = { ...bundle.docsConfig.i18n, defaultLocale: projection.defaultLocale, locales: locales.map((code) => ({ code, label: code === "en" ? "English" : code })) };
@@ -15270,7 +15547,6 @@ import { createHash as createHash4 } from "crypto";
 import { lookup } from "dns/promises";
 import { request } from "https";
 import { isIP } from "net";
-import { parse as parseYaml7 } from "yaml";
 var MAX_SPEC_BYTES2 = 25e6;
 var MAX_REDIRECTS = 3;
 function isPublicAddress(address, family) {
@@ -15364,9 +15640,7 @@ async function downloadSpec(value, fetcher) {
   }
   throw new Error("Remote OpenAPI spec redirected too many times.");
 }
-function parseOpenApi(content, extension) {
-  const text3 = content.toString("utf8");
-  const parsed = extension === "yaml" || !text3.trimStart().startsWith("{") ? parseYaml7(text3) : JSON.parse(text3);
+function parseOpenApi(parsed) {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("OpenAPI spec is not an object.");
   const document = parsed;
   if (typeof document.openapi !== "string" || !/^3\./.test(document.openapi)) {
@@ -15379,10 +15653,11 @@ function parseOpenApi(content, extension) {
   if (paths.length > 5e3) throw new Error("Remote OpenAPI spec has too many paths to import.");
   const operations = [];
   for (const [path, value] of paths) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value) || isWithheld(value)) continue;
     for (const [method, raw] of Object.entries(value)) {
       if (!/^(get|post|put|patch|delete|head|options|trace)$/i.test(method) || !raw || typeof raw !== "object" || Array.isArray(raw)) continue;
       const operation = raw;
+      if (isWithheld(operation)) continue;
       const tags = Array.isArray(operation.tags) ? operation.tags : [];
       operations.push({
         method: method.toLowerCase(),
@@ -15397,9 +15672,8 @@ function parseOpenApi(content, extension) {
 function slug(value) {
   return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
-function operationTarget(operation) {
-  const path = operation.path.split("/").filter(Boolean).map((part) => part.replace(/[{}]/g, "").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").toLowerCase());
-  return `/api/default/${[...path, operation.method].join("/")}`;
+function operationTarget(specId, operation) {
+  return `/api/${specId}/${thallyOperationSlugSegments(operation.path, operation.method).join("/")}`;
 }
 async function hydrateRemoteApiSpecs(bundle, fetcher) {
   if (!bundle.remoteApiSpecs?.length) return bundle;
@@ -15409,28 +15683,32 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
   const warnings = [...bundle.warnings];
   const pages = bundle.pages.map((page) => ({ ...page }));
   const authoredLinks = /* @__PURE__ */ new Set();
+  const served = servedRoutes(pages);
+  const endpointUrls = /* @__PURE__ */ new Map();
   for (const page of bundle.pages) {
     for (const match of page.body.matchAll(/\/[a-z0-9_/-]+/gi)) {
       const segments = match[0].split("/").filter(Boolean);
       if (segments.length < 3) continue;
       const section = segments[0].toLowerCase();
-      if (section.includes("api") || section.includes("reference")) authoredLinks.add(match[0]);
+      if (section.includes("api") || section.includes("reference")) authoredLinks.add(match[0].replace(/\/+$/, ""));
     }
   }
+  const bound = [];
   for (const reference of bundle.remoteApiSpecs) {
     for (let index = warnings.length - 1; index >= 0; index--) {
       if (warnings[index].source === reference.url && warnings[index].message.includes("requires a network download")) warnings.splice(index, 1);
     }
     try {
-      const url = validatedSpecUrl(reference.url);
-      const extension = /\.ya?ml$/i.test(url.pathname) ? "yaml" : "json";
-      const downloaded = await downloadSpec(reference.url, fetcher);
+      const downloaded = withoutByteOrderMark(await downloadSpec(reference.url, fetcher));
       const pruned = markExcluded(downloaded, reference.withheldOperations ?? [], reference.keptOperations);
       const body = pruned.content;
-      if (reference.withheldOperations?.length) warnings.push({ code: "gated-page", message: sharedSpecMessage(reference.url, pruned.excluded), source: reference.url });
-      const operations = parseOpenApi(body, extension);
+      if (reference.withheldOperations?.length && !warnings.some((warning) => warning.code === "gated-page" && warning.source === reference.url)) {
+        warnings.push({ code: "gated-page", message: sharedSpecMessage(reference.url, pruned.excluded), source: reference.url });
+      }
+      const { format: extension, document } = parseSpecDocument(body.toString("utf8"));
+      const operations = parseOpenApi(document);
       const filename = `openapi-${createHash4("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
-      assets.push({ path: `openapi/${filename}`, content: body, projectRelative: true });
+      if (!assets.some((asset) => asset.path === `openapi/${filename}`)) assets.push({ path: `openapi/${filename}`, content: body, projectRelative: true });
       for (const page of pages) {
         const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;
         if (ref?.specRef === reference.url) page.openapi = withSpecRef(ref, `openapi/${filename}`);
@@ -15438,21 +15716,7 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
       const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
       if (tab) tab.api = { source: `openapi/${filename}` };
       else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api: { source: `openapi/${filename}` } }, reference.parentTab);
-      const routes = /* @__PURE__ */ new Map();
-      for (const operation of operations) {
-        const key = `${slug(operation.tag)}/${slug(operation.summary)}`;
-        if (routes.has(key)) routes.set(key, null);
-        else routes.set(key, operationTarget(operation));
-      }
-      const existingSources = new Set(redirects.map((redirect) => redirect.source));
-      for (const source of authoredLinks) {
-        const parts = source.split("/").filter(Boolean);
-        const key = parts.slice(-2).join("/");
-        const destination = routes.get(key);
-        if (!destination || existingSources.has(source)) continue;
-        redirects.push({ source, destination, permanent: false });
-        existingSources.add(source);
-      }
+      bound.push({ reference, filename, content: body, operations, tabName: tab?.tab ?? reference.tabLabel ?? "API Reference" });
     } catch (error) {
       warnings.push({
         code: "fetch-failed",
@@ -15461,11 +15725,59 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
       });
     }
   }
+  const directories = [
+    ...(bundle.localApiMounts ?? []).map(({ directory }) => directory),
+    ...bundle.remoteApiSpecs.flatMap((reference) => (reference.directories ?? []).map(({ directory }) => directory))
+  ];
+  const endpointRedirects = linkApiMounts(
+    [
+      ...(bundle.localApiMounts ?? []).map(({ filename, directory, tab }) => ({
+        filename,
+        content: Buffer.from(assets.find((asset) => asset.path === `openapi/${filename}`)?.content ?? []),
+        prefix: directory,
+        ...tab ? { tab } : {}
+      })),
+      ...bound.flatMap(({ reference, filename, content, tabName }) => (reference.directories ?? []).map(({ directory, operations: listed }) => ({ filename, content, prefix: directory, tab: tabName, ...listed ? { operations: listed } : {} })))
+    ],
+    { ...bundle.docsConfig, tabs, redirects },
+    pages,
+    warnings,
+    directories
+  );
+  for (const redirect of endpointRedirects) {
+    redirects.push(redirect);
+    endpointUrls.set(literalRoute(redirect.source) ?? redirect.source, redirect.destination);
+  }
+  const existingSources = new Set(redirects.map((redirect) => literalRoute(redirect.source) ?? redirect.source.toLowerCase()));
+  const mounts = directories.map(mountPrefix).filter(Boolean);
+  const underMount = (source) => mounts.some((prefix) => source.toLowerCase() === `/${prefix}` || source.toLowerCase().startsWith(`/${prefix}/`));
+  const guesses = /* @__PURE__ */ new Map();
+  const specIds = apiTabSpecIds(tabs);
+  for (const { reference, filename, operations, tabName } of bound) {
+    const specId = specIds.find(({ tab }) => tab.tab === tabName && tab.api?.source === `openapi/${filename}`)?.specId;
+    const listed = reference.directories?.length && reference.directories.every((directory) => directory.operations) ? new Set(reference.directories.flatMap((directory) => directory.operations ?? []).map((name) => name.trim().split(/\s+/)).map(([method, ...path]) => `${method.toLowerCase()} ${path.join(" ")}`)) : null;
+    for (const operation of operations) {
+      if (listed && !listed.has(`${operation.method} ${operation.path}`)) continue;
+      const key = `${slug(operation.tag)}/${slug(operation.summary)}`;
+      guesses.set(key, guesses.has(key) || !specId ? null : operationTarget(specId, operation));
+    }
+  }
+  for (const source of authoredLinks) {
+    const destination = guesses.get(source.split("/").filter(Boolean).slice(-2).join("/"));
+    if (!destination || existingSources.has(literalRoute(source) ?? source.toLowerCase()) || served.has(literalRoute(source) ?? source) || underMount(source)) continue;
+    redirects.push({ source, destination, permanent: false });
+    existingSources.add(literalRoute(source) ?? source.toLowerCase());
+  }
+  const direct = redirects.map((redirect) => {
+    const endpoint = endpointUrls.get(literalRoute(redirect.destination) ?? "");
+    return endpoint ? { ...redirect, destination: endpoint } : redirect;
+  });
   return {
     ...bundle,
     pages,
     assets,
-    docsConfig: { ...bundle.docsConfig, tabs, ...redirects.length > 0 ? { redirects } : {} },
+    // Redirects added above meet the same checks as any other: none may fail the build, hide a page that exists, or loop.
+    docsConfig: dropConflictingRedirects(dropUnroutableRedirects({ ...bundle.docsConfig, tabs, ...direct.length > 0 ? { redirects: direct } : {} }, warnings), pages, warnings),
     warnings
   };
 }