@thallylabs/migrate 0.2.40 → 0.2.42

package/dist/index.js

@@ -1370,8 +1370,29 @@ ${trimmed.slice(0, marker).trimEnd()}`;
 function headingIdMarker(id) {
   return `{/* #${id} */}`;
 }
+var HEADING_ID_WORD = /[\p{L}\p{M}\p{N}_+&/@\u2019\u201c\u201d\u2014\u2013\u2192]/u;
 function mintlifyHeadingSlug(text3) {
-  return text3.replace(/\u200b/g, "").normalize("NFC").trim().toLowerCase().replace(/[.\s]+/g, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "").replace(/[^\p{L}\p{M}\p{N}_\-+&/\u2019\u201c\u201d\u2014\u2013\u2192]/gu, "");
+  const chars = [...text3.replace(/[\u200b*]/g, "").normalize("NFC").trim().toLowerCase()];
+  const isWord = (char) => char !== void 0 && HEADING_ID_WORD.test(char);
+  let id = "";
+  let afterDash = false;
+  let endsWithDash = false;
+  chars.forEach((char, index) => {
+    const before = chars[index - 1];
+    const after = chars[index + 1];
+    endsWithDash = false;
+    if (isWord(char)) {
+      id += char;
+      afterDash = false;
+    } else if (/[\s-]/.test(char) || char === "." && isWord(after) || char === "(" && isWord(before) && (isWord(after) || after === "{") || char === ")" && after !== void 0 && !/\s/.test(after)) {
+      if (id && !afterDash) id += "-";
+      afterDash = true;
+      endsWithDash = true;
+    } else if (char === "{" || char === ":" || char === '"') {
+      afterDash = false;
+    }
+  });
+  return endsWithDash ? id.replace(/-$/, "") : id;
 }
 function thallyHeadingSlug(text3) {
   return text3.normalize("NFC").toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/(^-|-$)/g, "");
@@ -1383,7 +1404,7 @@ function typesetQuotes(text3) {
   }).join("");
 }
 function plainHeadingText(source) {
-  return source.replace(/\{\/\*[\s\S]*?\*\/\}/g, " ").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<\/?[A-Za-z][^>]*>/g, "").replace(/`([^`]*)`/g, "$1").replace(/(\*\*|__|~~|\*)/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/\\([\\`*_{}[\]()#+.!&<>|~-])/g, "$1");
+  return source.replace(/\{\/\*[\s\S]*?\*\/\}/g, " ").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<\/?[A-Za-z][^>]*>/g, "").replace(/`([^`]*)`/g, "$1").replace(/(?<!\\)(\*\*|__|~~|\*)/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/\\([\\`*_{}[\]()#+.!&<>|~-])/g, "$1");
 }
 function markMintlifyHeadings(body) {
   let fence;
@@ -2587,7 +2608,7 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   }
   if (runMintlify) rewritten = normalizeMintlifyParameterAnchors(rewritten);
   rewritten = replaceOutsideCode(rewritten, (segment) => {
-    let result = convertHtmlStyleAttributes(segment).replace(/<!--([\s\S]*?)-->/g, (_match, content) => mdxComment(content)).replace(/<Danger(\s[^>]*)?>/g, "<Error$1>").replace(/<\/Danger>/g, "</Error>").replace(/<Warn(\s[^>]*)?>/g, "<Warning$1>").replace(/<\/Warn>/g, "</Warning>").replace(/<Check(\s[^>]*)?>/g, "<Note$1>").replace(/<\/Check>/g, "</Note>").replace(/<Tree\.Folder/g, "<Folder").replace(/<\/Tree\.Folder>/g, "</Folder>").replace(/<Tree\.File/g, "<File").replace(/<\/Tree\.File>/g, "</File>");
+    let result = convertHtmlStyleAttributes(segment).replace(/<!--([\s\S]*?)-->/g, (_match, content) => mdxComment(content)).replace(/<Danger(\s[^>]*)?>/g, "<Error$1>").replace(/<\/Danger>/g, "</Error>").replace(/<Warn(\s[^>]*)?>/g, "<Warning$1>").replace(/<\/Warn>/g, "</Warning>").replace(/<Tree\.Folder/g, "<Folder").replace(/<\/Tree\.Folder>/g, "</Folder>").replace(/<Tree\.File/g, "<File").replace(/<\/Tree\.File>/g, "</File>");
     if (runDocusaurus) {
       result = result.replace(/<TabItem\b([^<>]*)>/g, (_match, attributes) => {
         const title = attributes.match(/\blabel=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean) ?? attributes.match(/\bvalue=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean) ?? "Tab";
@@ -2596,7 +2617,7 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
       result = normalizeDocusaurusLinkTags(result).replace(/<(?:DocCardList|TOCInline)\b[^<>]*\/>/g, "");
     }
     if (runMintlify) {
-      result = normalizeMintlifyUpdateLabels(result).replace(/<FileTree(\s[^>]*)?>/g, "<Tree$1>").replace(/<\/FileTree>/g, "</Tree>").replace(/<GitHub\.Repo/g, "<GitHub").replace(/<\/GitHub\.Repo>/g, "</GitHub>").replace(/<Column(\s[^>]*)?>/g, "<div$1>").replace(/<\/Column>/g, "</div>");
+      result = normalizeMintlifyUpdateLabels(result).replace(/<FileTree(\s[^>]*)?>/g, "<Tree$1>").replace(/<\/FileTree>/g, "</Tree>").replace(/<GitHub\.Repo/g, "<GitHub").replace(/<\/GitHub\.Repo>/g, "</GitHub>").replace(/<Callout(\s[^<>]*)?>/g, (tag) => tag.replace(/(\s)type=(?:"[^"]*"|'[^']*'|\{[^{}]*\})/, '$1type="info"')).replace(/<Column(\s[^>]*)?>/g, "<div$1>").replace(/<\/Column>/g, "</div>");
       result = pinStepsTitleSize(result);
     }
     if (runFern) {
@@ -2615,6 +2636,16 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   }
   return normalizeFlowParagraphContainers(normalized);
 }
+function externalPageUrl(value) {
+  const url = typeof value === "string" ? value.trim() : "";
+  if (!/^https?:\/\/[^\s]+$/i.test(url)) return void 0;
+  try {
+    new URL(url);
+    return url;
+  } catch {
+    return void 0;
+  }
+}
 function parseMarkdownPage(input) {
   const parsed = parseFrontmatter(input.raw);
   const fallbackIdentity = {
@@ -2639,6 +2670,7 @@ function parseMarkdownPage(input) {
   const badge = typeof parsed.data.tag === "string" && parsed.data.tag.trim() ? parsed.data.tag.trim() : typeof parsed.data.badge === "string" && parsed.data.badge.trim() ? parsed.data.badge.trim() : void 0;
   const sourceMode = typeof parsed.data.mode === "string" ? parsed.data.mode : void 0;
   const mode = sourceMode === "frame" ? "wide" : ["default", "wide", "custom", "center", "home"].includes(sourceMode ?? "") ? sourceMode : void 0;
+  const externalUrl = input.platform === "mintlify" ? externalPageUrl(parsed.data.url) : void 0;
   const description = typeof parsed.data.description === "string" && parsed.data.description.trim() ? parsed.data.description.trim() : typeof parsed.data.openapi === "string" && parsed.data.openapi.trim() ? "" : firstParagraph(body);
   const page = {
     id: identity.id,
@@ -2654,7 +2686,9 @@ function parseMarkdownPage(input) {
     keywords,
     mode,
     hidden: parsed.data.hidden === true ? true : void 0,
-    noindex: parsed.data.noindex === true || parsed.data.noindex === "true" ? true : void 0,
+    // The path of a page that links elsewhere redirects, so it has no business in a sitemap.
+    noindex: parsed.data.noindex === true || parsed.data.noindex === "true" || externalUrl ? true : void 0,
+    ...externalUrl ? { externalUrl } : {},
     ...Object.keys(meta).length > 0 ? { meta } : {},
     openapi: typeof parsed.data.openapi === "string" ? parsed.data.openapi.trim() : void 0,
     ...apiFrontmatter(parsed.data, input.warn),
@@ -4391,12 +4425,17 @@ 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(/\/$/, "") || "/").toLowerCase()));
+  const routeKey = (route) => (route.split(/[?#]/, 1)[0].replace(/\/$/, "") || "/").toLowerCase();
+  const sources = new Set(redirects.map((redirect) => routeKey(redirect.source)));
   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)];
+  const homeLinksElsewhere = pages.some((page) => page.id === "introduction" && page.externalUrl);
   for (const locale of roots) {
+    if (!locale && homeLinksElsewhere) continue;
     const source = locale ? `/${locale}` : "/";
     if (sources.has(source.toLowerCase())) continue;
-    redirects.push({ source, destination: `${locale ? `/${locale}` : ""}/${homepage}`, permanent: true });
+    const destination = `${locale ? `/${locale}` : ""}/${homepage}`;
+    if (redirects.some((redirect) => routeKey(redirect.source) === destination.toLowerCase() && routeKey(redirect.destination) === source.toLowerCase())) continue;
+    redirects.push({ source, destination, permanent: true });
   }
   return { ...config, redirects };
 }
@@ -4593,7 +4632,7 @@ function mergeApiGroups(existing, incoming) {
   return merged.length > 0 ? merged : void 0;
 }
 var hasNavigationChildren = (node) => ["groups", "pages"].some((key) => Array.isArray(node[key]) && node[key].length > 0);
-function mintlifyNavigationApiReferences(config) {
+function mintlifyNavigationApiReferences(config, tabFor) {
   const navigation = objectValue2(config.navigation) ?? config;
   const references = [];
   const defaultLanguage = pickDefaultLanguage(
@@ -4617,7 +4656,7 @@ function mintlifyNavigationApiReferences(config) {
         references.push({
           value,
           kind,
-          tabLabel,
+          tabLabel: tabFor?.(node) ?? tabLabel,
           ...sibling,
           ...typeof directory2 === "string" && directory2.trim() ? { directory: directory2.trim() } : {},
           ...operations.length > 0 ? { operations } : {},
@@ -4972,6 +5011,21 @@ function convertNavigationValues(values, context) {
     return page ? [page] : [];
   });
 }
+var API_TAB_CONTAINER = /* @__PURE__ */ Symbol("apiTabContainer");
+function takeApiTabSlots(tabs) {
+  const slots = [];
+  const real = [];
+  tabs.forEach((tab, index) => {
+    const container = tab[API_TAB_CONTAINER];
+    if (!container) {
+      real.push(tab);
+      return;
+    }
+    const template = Object.fromEntries(Object.entries(tab).filter(([key]) => key !== "groups"));
+    slots.push({ container, slot: { tab: template, preceding: tabs.slice(0, index).map((earlier) => earlier.tab).reverse() } });
+  });
+  return { tabs: real, slots };
+}
 function convertContainerToTabs(containerValue, context, fallbackTab, trace, depth = 0) {
   const rawContainer = objectValue2(containerValue);
   if (!rawContainer) return [];
@@ -5048,6 +5102,17 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
     ...convertNavigationValues(values, context),
     ...Array.isArray(container.menu) ? convertMenuItems(container.menu, context) : []
   ];
+  if (children.length === 0 && depth > 0 && context.operationGroups && !context.otherLanguage && !context.operations.gated && !context.operations.hidden && specSource(rawContainer.openapi) && operationGroups(rawContainer).length > 0) {
+    const placeholder2 = {
+      tab: fallbackTab,
+      groups: [],
+      ...containerPresentation(container),
+      ...projectedHref(container.href) ? { href: projectedHref(container.href) } : {},
+      ...container.hidden === true ? { hidden: true } : {},
+      [API_TAB_CONTAINER]: rawContainer
+    };
+    return [placeholder2];
+  }
   return children.length > 0 ? [{
     tab: fallbackTab,
     ...hasRootNodes ? { pages: children } : { groups: children },
@@ -5228,6 +5293,8 @@ function projectedCompatibleConfig(config, warnings) {
   return {
     // Mintlify pages show a group eyebrow above the title and no breadcrumb trail.
     breadcrumbs: false,
+    // Mintlify typesets straight quotes in prose as curly ones.
+    smartQuotes: true,
     // `styling.eyebrows: "breadcrumbs"` shows the whole group path; "section" (the default) shows the nearest group.
     ...objectValue2(config.styling)?.eyebrows === "breadcrumbs" ? { eyebrow: "path" } : {},
     ...projectedTheme(config.theme) ? { theme: projectedTheme(config.theme) } : {},
@@ -5479,6 +5546,9 @@ function projectMintlifyNavigation(config, options = {}) {
       }
     }
   }
+  const taken = takeApiTabSlots(tabs);
+  tabs = taken.tabs;
+  const apiTabSlots = taken.slots;
   if (tabs.length === 0) {
     warnings.push({
       code: "unsupported-config",
@@ -5524,6 +5594,7 @@ function projectMintlifyNavigation(config, options = {}) {
   }) : [];
   if (versions.length > 1) {
     tabs = annotateVersions(tabs);
+    for (const entry of apiTabSlots) [entry.slot.tab] = annotateVersions([entry.slot.tab]);
     for (const [locale, items] of Object.entries(localizedNavigation)) localizedNavigation[locale] = annotateVersions(items);
   }
   const redirects = Array.isArray(config.redirects) ? config.redirects.flatMap((value) => {
@@ -5547,11 +5618,13 @@ function projectMintlifyNavigation(config, options = {}) {
     }];
   }) : [];
   collectReferenceAccess(navigation, OPEN_NAVIGATION_ACCESS, options.pathPrefix, appearances);
+  const keepsCollectionNamedGroup = [tabs, ...Object.values(localizedNavigation)].some((items) => items.some((item) => item.groups?.some((group) => group.group === (item.displayLabel ?? item.tab))));
   return {
     docsConfig: {
       tabs,
-      ...projectionTrace.rootContainerKind === "dropdowns" || versions.length > 1 || shortcuts.length > 0 ? { navigation: {
+      ...projectionTrace.rootContainerKind === "dropdowns" || versions.length > 1 || shortcuts.length > 0 || keepsCollectionNamedGroup ? { navigation: {
         ...projectionTrace.rootContainerKind === "dropdowns" ? { display: "dropdown" } : {},
+        ...keepsCollectionNamedGroup ? { groupHeadings: "all" } : {},
         ...versions.length > 1 ? { versions } : {},
         ...shortcuts.length > 0 ? { shortcuts } : {}
       } } : {},
@@ -5563,6 +5636,7 @@ function projectMintlifyNavigation(config, options = {}) {
     pageReferences: references,
     referenceAccess: appearances,
     gatedSourceRefs,
+    apiTabSlots,
     warnings
   };
 }
@@ -7786,7 +7860,10 @@ var VIDEO_ATTRIBUTES = /* @__PURE__ */ new Set([
   "width",
   "height",
   "preload",
-  "aria-label"
+  "aria-label",
+  // Publisher asset provenance does not change playback and is never emitted.
+  // Keep this explicit: arbitrary data attributes may drive custom controls.
+  "data-path"
 ]);
 var YOUTUBE_ATTRIBUTES = /* @__PURE__ */ new Set([
   "src",
@@ -9074,6 +9151,9 @@ function destinationRoute(destination) {
 function pageRoutes(pages) {
   return pages.flatMap((page) => [`/${page.id}`, `/${page.id.replace(/\/index$/, "")}`]);
 }
+function pageEntryRoutes(page) {
+  return [.../* @__PURE__ */ new Set([...pageRoutes([page]), ...page.id === "introduction" ? ["/"] : []])];
+}
 function servedRoutes(pages) {
   return new Set(pageRoutes(pages).map((route) => route.toLowerCase()));
 }
@@ -9138,11 +9218,13 @@ function dropConflictingRedirects(config, pages, warnings) {
   const loopingByCase = [];
   const folded = redirectChains();
   const asWritten = redirectChains();
+  const rootRedirected = config.redirects.some((redirect) => literalRoute(redirect.source) === "/");
   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 retiresRootAlias = source === "/introduction" && !rootRedirected && destinationRoute(redirect.destination) === "/";
+    if (served.has(source) && !retiresRootAlias) {
       const hides = servedAsWritten.has(writtenSource) ? hidden : hiddenByCase;
       hides.push(redirect.source);
       return false;
@@ -12337,12 +12419,19 @@ function mintlifyTopLevelApiReferences(config) {
 function specFileCandidates(files) {
   return files.filter((file) => /\.(?:json|ya?ml)$/i.test(file.relativePath)).map((file) => ({ sourcePath: file.relativePath, filename: specRefBaseName(file.relativePath) }));
 }
-function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, nameSpec, pages = []) {
+function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, nameSpec, pages = [], apiTabSlots = []) {
   if (!mintlifyConfig) return [];
+  const slotByContainer = new Map(apiTabSlots.map(({ container, slot }) => [container, slot]));
+  const slotByLabel = new Map(apiTabSlots.map(({ slot }) => [slot.tab.tab, slot]));
   const references = [
     ...mintlifyTopLevelApiReferences(mintlifyConfig),
-    ...mintlifyNavigationApiReferences(mintlifyConfig)
+    ...mintlifyNavigationApiReferences(mintlifyConfig, (container) => slotByContainer.get(container)?.tab.tab)
   ];
+  const endpointPagesOf = (reference) => {
+    const directory2 = reference.groups ? endpointDirectory(reference.directory) : void 0;
+    const slot = reference.tabLabel ? slotByLabel.get(reference.tabLabel) : void 0;
+    return directory2 === void 0 ? void 0 : { directory: directory2, ...slot ? { slot } : {} };
+  };
   const known = new Set(references.map((reference) => canonicalSpecRef(reference.value)));
   const specFiles = specFileCandidates(files);
   const namedFiles = /* @__PURE__ */ new Map();
@@ -12383,6 +12472,14 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
         if (reference.groups) {
           const merged = mergeApiGroups(shared.target.groups, reference.groups);
           if (merged) shared.target.groups = merged;
+          const own2 = endpointPagesOf(reference);
+          if (shared.directory === void 0) {
+            shared.directory = own2?.directory ?? null;
+            if (own2) shared.target.endpointPages = own2;
+          } else if (shared.directory !== (own2?.directory ?? null)) {
+            shared.directory = null;
+            delete shared.target.endpointPages;
+          }
         } else if (listsNothing(reference)) {
           shared.unlisted = true;
           delete shared.target.groups;
@@ -12401,11 +12498,12 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
       continue;
     }
     if (/^https:\/\//i.test(reference.value)) {
-      const remote = { url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, ...groups ? { groups } : {} };
+      const pagesTarget = endpointPagesOf(reference);
+      const remote = { url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, ...groups ? { groups } : {}, ...groups && pagesTarget ? { endpointPages: pagesTarget } : {} };
       mountDirectory(remote, reference);
       remoteSpecs.push(remote);
       remoteByKey.set(dedupeKey, remote);
-      groupTargets.set(dedupeKey, { target: remote, unlisted: listsNothing(reference), withheld: reference.operationsWithheld === true });
+      groupTargets.set(dedupeKey, { target: remote, unlisted: listsNothing(reference), withheld: reference.operationsWithheld === true, ...groups ? { directory: pagesTarget?.directory ?? null } : {} });
       warnings.push({
         code: "unsupported-config",
         message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} requires a network download before this import is complete.`,
@@ -12426,12 +12524,12 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
       });
       continue;
     }
-    if (reference.directory) {
-      warnings.push({
-        code: "unsupported-config",
-        message: `The OpenAPI spec "${reference.value}"${tabSuffix} was limited to pages under "${reference.directory}" in the source, but Thally's API reference always covers a whole tab, so it was migrated as the tab's full API reference. Links in page bodies and Mintlify endpoint URLs under "${reference.directory}/<tag>/<operation>" are redirected to the matching endpoints where one exists (a separate warning counts any endpoint redirects that were skipped); check any other links to "${reference.directory}/..." manually.`
-      });
-    }
+    const directoryWarning = reference.directory ? {
+      code: "unsupported-config",
+      message: `The OpenAPI spec "${reference.value}"${tabSuffix} was limited to pages under "${reference.directory}" in the source, but Thally's API reference always covers a whole tab, so it was migrated as the tab's full API reference. Links in page bodies and Mintlify endpoint URLs under "${reference.directory}/<tag>/<operation>" are redirected to the matching endpoints where one exists (a separate warning counts any endpoint redirects that were skipped); check any other links to "${reference.directory}/..." manually.`
+    } : void 0;
+    const deferWarning = Boolean(groups && endpointPagesOf(reference));
+    if (directoryWarning && !deferWarning) warnings.push(directoryWarning);
     const content = readSpecFile(match.absolutePath, match.relativePath, warnings);
     if (!content) continue;
     const spec = {
@@ -12444,10 +12542,11 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
       ...reference.pageOnly ? { pageOnly: true } : {},
       sourcePath: match.relativePath,
       directory: reference.directory,
-      ...groups ? { groups } : {}
+      ...groups ? { groups } : {},
+      ...deferWarning ? { endpointPages: endpointPagesOf(reference), directoryWarning } : {}
     };
     specs.push(spec);
-    groupTargets.set(dedupeKey, { target: spec, unlisted: listsNothing(reference), withheld: reference.operationsWithheld === true });
+    groupTargets.set(dedupeKey, { target: spec, unlisted: listsNothing(reference), withheld: reference.operationsWithheld === true, ...groups ? { directory: endpointPagesOf(reference)?.directory ?? null } : {} });
   }
   for (const { target: target2, unlisted, withheld } of groupTargets.values()) {
     if (withheld && !unlisted && !target2.groups) target2.navigation = false;
@@ -12503,20 +12602,52 @@ function apiTabSpecIds(tabs) {
 }
 var flagged = (value) => value === true || value === "true";
 var isWithheld = (node) => flagged(node["x-hidden"]) || flagged(node["x-excluded"]);
+var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+function resolveLocalSpecRef(document, ref) {
+  if (ref !== "#" && !ref.startsWith("#/")) return void 0;
+  let node = document;
+  for (const segment of ref.slice(2).split("/").filter(Boolean)) {
+    if (!isRecord2(node) && !Array.isArray(node)) return void 0;
+    let decoded = segment;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+    }
+    node = node[decoded.replace(/~1/g, "/").replace(/~0/g, "~")];
+  }
+  return node;
+}
+function viewSpecPathItem(document, entry) {
+  const chain = [entry];
+  let current = entry;
+  while (typeof current.$ref === "string") {
+    const target2 = resolveLocalSpecRef(document, current.$ref);
+    if (!isRecord2(target2) || chain.includes(target2)) break;
+    chain.push(target2);
+    current = target2;
+  }
+  const item = Object.assign({}, ...[...chain].reverse());
+  delete item.$ref;
+  return { item, withheld: chain.some(isWithheld) };
+}
 function parseOpenApiOperationsForLinking(content) {
-  let document;
+  const document = readSpecDocument(content);
+  return visibleOperations(document, isRecord2(document) ? document.paths : void 0);
+}
+function readSpecDocument(content) {
   try {
-    document = parseSpecDocument(content.toString("utf8")).document;
+    return parseSpecDocument(content.toString("utf8")).document;
   } catch {
-    return [];
+    return void 0;
   }
-  const paths = document && typeof document === "object" ? document.paths : null;
-  if (!paths || typeof paths !== "object") return [];
+}
+function visibleOperations(document, entries) {
+  if (!isRecord2(entries)) return [];
   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 [path, pathItem] of Object.entries(entries)) {
+    if (!isRecord2(pathItem)) continue;
+    const { item, withheld } = viewSpecPathItem(document, pathItem);
+    if (withheld) continue;
     for (const method of OPENAPI_HTTP_METHODS) {
       const operation = item[method];
       if (!operation || typeof operation !== "object") continue;
@@ -12528,7 +12659,8 @@ function parseOpenApiOperationsForLinking(content) {
         path,
         tag: tags[0],
         summary: typeof op.summary === "string" ? op.summary : void 0,
-        operationId: typeof op.operationId === "string" ? op.operationId : void 0
+        operationId: typeof op.operationId === "string" ? op.operationId : void 0,
+        description: typeof op.description === "string" ? op.description : void 0
       });
     }
   }
@@ -12549,13 +12681,26 @@ function servedOperations(source, parsed) {
   });
 }
 var mountPrefix = (directory2) => directory2.replace(/^\/+|\/+$/g, "").toLowerCase();
+function mintlifyEndpointUrl(directory2, operation) {
+  const tag = mintlifyUrlSlug(operation.tag ?? "default");
+  const leaf = mintlifyUrlSlug(operation.summary?.trim() || operation.operationId?.trim() || `${operation.method} ${operation.path}`);
+  return {
+    tag,
+    leaf,
+    url: `${directory2}/${tag}/${leaf}`.replace(/^\/+|\/+$/g, ""),
+    title: operation.summary?.trim() || operation.operationId?.trim() || `${operation.method.toUpperCase()} ${operation.path}`
+  };
+}
 function apiOperationLinkMap(sources, docsConfig, otherMounts = []) {
   const map = /* @__PURE__ */ new Map();
   const prefixLandings = /* @__PURE__ */ new Map();
   const mintlifyPages = /* @__PURE__ */ new Map();
   const duplicatePages = [];
   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 bound = [
+    ...apiTabSpecIds(docsConfig.tabs).flatMap(({ tab, specId }) => sources.filter((entry) => !entry.endpointPages && tab.api?.source === specAssetPath(entry.filename) && (!entry.tab || entry.tab === tab.tab)).map((source) => ({ source, specId }))),
+    ...sources.filter((entry) => entry.endpointPages).map((source) => ({ source }))
+  ];
   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();
@@ -12565,9 +12710,12 @@ function apiOperationLinkMap(sources, docsConfig, otherMounts = []) {
     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}`);
+    if (prefix && specId !== void 0) prefixLandings.set(prefix, specId === "default" ? "/api" : `/api/${specId}`);
     for (const operation of servedOperations(source, parsedByFile)) {
-      const thallyHref = `/api/${specId}/${thallyOperationSlugSegments(operation.path, operation.method).join("/")}`;
+      const endpoint = mintlifyEndpointUrl(base, operation);
+      if (specId === void 0 && (!endpoint.tag || !endpoint.leaf)) continue;
+      const thallyHref = specId === void 0 ? `/${endpoint.url}` : `/api/${specId}/${thallyOperationSlugSegments(operation.path, operation.method).join("/")}`;
+      if (specId === void 0 && prefix && !prefixLandings.has(prefix)) prefixLandings.set(prefix, thallyHref);
       const leafCandidates = /* @__PURE__ */ new Set();
       if (operation.operationId) {
         const parts = operation.operationId.split(/[_.]/).filter(Boolean);
@@ -12580,17 +12728,17 @@ function apiOperationLinkMap(sources, docsConfig, otherMounts = []) {
       if (operation.operationId) leafCandidates.add(mintlifyOperationSlugSegment(operation.operationId));
       leafCandidates.add(mintlifyOperationSlugSegment(`${operation.method} ${operation.path}`));
       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 = `${base}/${mintlifyTag}/${mintlifyLeaf}`.replace(/^\/+|\/+$/g, "");
+      const { tag: mintlifyTag, leaf: mintlifyLeaf, url: canonical2 } = endpoint;
       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 (specId !== void 0) {
+          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 (specId !== void 0 && !mintlifyPages.has(tagRoot)) mintlifyPages.set(tagRoot, thallyHref);
         if (!map.has(tagRoot.toLowerCase())) map.set(tagRoot.toLowerCase(), thallyHref);
       }
       for (const leaf of leafCandidates) {
@@ -12631,6 +12779,150 @@ function linkApiMounts(sources, docsConfig, pages, warnings, reservedMounts = []
   rewriteApiLinksInPages(pages, maps.operationLinks, maps.prefixLandings, warnings, { mounts: reservedMounts, redirects: docsConfig.redirects });
   return mintlifyEndpointRedirects(maps, pages, docsConfig.redirects ?? [], warnings);
 }
+var DEFAULT_ENDPOINT_DIRECTORY = "api-reference";
+function endpointDirectory(directory2) {
+  const value = (directory2 ?? DEFAULT_ENDPOINT_DIRECTORY).replace(/^\/+|\/+$/g, "");
+  const plain = (segment) => /^[\p{L}\p{N}_&-][\p{L}\p{N}_&.-]*$/u.test(segment) && Buffer.byteLength(`${segment}.mdx`) <= 255;
+  return value && value.split("/").every(plain) ? value : void 0;
+}
+function createEndpointPageLedger(pages) {
+  return { owners: new Map(pages.map((page) => [page.id.toLowerCase(), { id: page.id, operation: null }])), duplicates: [], unnamed: [] };
+}
+function reportEndpointPages(ledger, warnings) {
+  const names = (urls) => `${urls.slice(0, 10).join(", ")}${urls.length > 10 ? ", ..." : ""}`;
+  if (ledger.duplicates.length > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      message: `${ledger.duplicates.length} Mintlify endpoint URL${ledger.duplicates.length === 1 ? " is" : "s are"} shared by more than one operation (same tag and summary), so only the first operation has a page at each: ${names(ledger.duplicates.map((url) => `/${url}`))}.`
+    });
+  }
+  if (ledger.unnamed.length > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      message: `${ledger.unnamed.length} listed operation${ledger.unnamed.length === 1 ? " has" : "s have"} no page because ${ledger.unnamed.length === 1 ? "its" : "their"} tag or title leaves no usable page name: ${names(ledger.unnamed)}.`
+    });
+  }
+}
+function endpointDescription(description, title) {
+  const text3 = (description ?? "").split(/\r?\n\s*\r?\n/, 1)[0].replace(/<[^>]*>/g, " ").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[`*~]|__/g, "").replace(/^\s*#+\s*/, "").replace(/\s+/g, " ").trim();
+  const sentence = /^(.+?[.!?])(?=\s|$)/.exec(text3)?.[1] ?? text3;
+  const limited = sentence.length > 300 ? `${sentence.slice(0, 297).replace(/\s+\S*$/, "")}...` : sentence;
+  return limited || title;
+}
+function insertEndpointTab(tabs, tab, preceding) {
+  if (preceding.length === 0) {
+    tabs.unshift(tab);
+    return;
+  }
+  for (const label of preceding) {
+    const index = tabs.findIndex((candidate) => candidate.tab === label);
+    if (index !== -1) {
+      tabs.splice(index + 1, 0, tab);
+      return;
+    }
+  }
+  tabs.push(tab);
+}
+function addEndpointPages(options) {
+  const { tabs, pages, ledger, spec } = options;
+  const operations = parseOpenApiOperationsForLinking(spec.content);
+  if (operations.length === 0) return null;
+  const existing = spec.tabLabel ? tabs.find((tab) => tab.tab === spec.tabLabel) : tabs.find((tab) => !tab.hidden && tab.tab.toLowerCase().includes("api"));
+  if (existing?.api) return null;
+  const byKey = new Map(operations.map((operation) => [`${operation.method} ${operation.path}`, operation]));
+  const listed = [];
+  const pageFor = (reference) => {
+    const [method, ...path] = reference.trim().split(/\s+/);
+    const operation = byKey.get(`${method.toLowerCase()} ${path.join(" ")}`);
+    if (!operation) return void 0;
+    const key = `${operation.method.toUpperCase()} ${operation.path}`;
+    const endpoint = mintlifyEndpointUrl(spec.target.directory, operation);
+    if (!endpoint.tag || !endpoint.leaf || Buffer.byteLength(`${endpoint.tag}.mdx`) > 255 || Buffer.byteLength(`${endpoint.leaf}.mdx`) > 255) {
+      if (!ledger.unnamed.includes(key)) ledger.unnamed.push(key);
+      return void 0;
+    }
+    const identity = `${spec.assetPath} ${key}`;
+    const owner = ledger.owners.get(endpoint.url.toLowerCase());
+    if (owner && owner.operation !== null && owner.operation !== identity) {
+      if (!ledger.duplicates.includes(endpoint.url)) ledger.duplicates.push(endpoint.url);
+      return void 0;
+    }
+    if (!owner) {
+      pages.push({
+        id: endpoint.url,
+        navigationId: endpoint.url,
+        title: endpoint.title,
+        description: endpointDescription(operation.description, endpoint.title),
+        // The summary belongs to metadata; keep full spec prose in the safe
+        // operation Markdown renderer rather than copying it into executable MDX.
+        descriptionPlacement: "operation",
+        keywords: [],
+        body: "",
+        source: "docs.json",
+        openapi: `${spec.assetPath} ${key}`
+      });
+      ledger.owners.set(endpoint.url.toLowerCase(), { id: endpoint.url, operation: identity });
+    }
+    listed.push(key);
+    return owner?.id ?? endpoint.url;
+  };
+  const convert2 = (nodes) => nodes.flatMap((node) => {
+    if (typeof node === "string") {
+      const id = pageFor(node);
+      return id ? [id] : [];
+    }
+    const pagesOf = convert2(node.pages);
+    return pagesOf.length > 0 ? [{ group: node.group, ...node.icon ? { icon: node.icon } : {}, pages: pagesOf }] : [];
+  });
+  const groups = convert2(spec.groups);
+  if (groups.length === 0) return null;
+  if (existing) {
+    if (existing.groups || !existing.pages) existing.groups = [...existing.groups ?? [], ...groups];
+    else existing.pages = [...existing.pages, ...groups];
+  } else {
+    const { slot } = spec.target;
+    const tab = {
+      ...slot?.tab ?? { tab: spec.tabLabel ?? "API Reference", ...spec.icon ? { icon: spec.icon } : {}, ...spec.hidden ? { hidden: true } : {} },
+      groups
+    };
+    if (slot) insertEndpointTab(tabs, tab, slot.preceding);
+    else insertApiTab(tabs, tab, spec.parentTab);
+  }
+  if (!tabs.some((tab) => tab.api?.source === spec.assetPath)) {
+    insertApiTab(tabs, { tab: `OpenAPI: ${spec.source}`, hidden: true, api: { source: spec.assetPath } });
+  }
+  return { operations: listed };
+}
+function specLookupOrder(tabs, versions = []) {
+  const collected = (tab) => !tab.hidden || Boolean(tab.version && versions.some((version) => version.label === tab.version));
+  const sources = [...tabs.filter(collected), ...tabs.filter((tab) => !collected(tab))].flatMap((tab) => tab.api ? [tab.api.source] : []);
+  return [...new Set(sources)];
+}
+function publishedOperationKeys(content) {
+  const document = readSpecDocument(content);
+  const table = (field) => visibleOperations(document, isRecord2(document) ? document[field] : void 0);
+  return /* @__PURE__ */ new Set([
+    ...table("paths").map((operation) => `${operation.method} ${operation.path}`),
+    ...table("webhooks").map((operation) => `webhook ${operation.path}`)
+  ]);
+}
+function qualifyDisplacedBareRefs(options) {
+  const { pages, before, after, content, qualifier } = options;
+  if (before.join("\n") === after.join("\n")) return;
+  const published = /* @__PURE__ */ new Map();
+  const firstPublishing = (order, key) => order.find((source) => {
+    if (!published.has(source)) published.set(source, publishedOperationKeys(content(source) ?? Buffer.alloc(0)));
+    return published.get(source).has(key);
+  });
+  for (const page of pages) {
+    const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;
+    if (!ref || ref.specRef) continue;
+    const [method, ...rest] = ref.operation.trim().split(/\s+/);
+    const key = `${method.toLowerCase()} ${rest.join(" ")}`;
+    const reached = firstPublishing(before, key);
+    if (reached !== void 0 && reached !== firstPublishing(after, key)) page.openapi = withSpecRef(ref, qualifier(reached));
+  }
+}
 function rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings, answered = {}) {
   if (operationLinks.size === 0 && prefixLandings.size === 0) return;
   const unmatched = /* @__PURE__ */ new Set();
@@ -13878,6 +14170,7 @@ function migrateRepository(options) {
   const referenceOrder = /* @__PURE__ */ new Map();
   let docusaurusSidebars = null;
   let mintlifyConfig = null;
+  let mintlifyApiTabSlots = [];
   const mintlifyNavigationAccess = /* @__PURE__ */ new Map();
   let fernRawConfig = null;
   let fernBasePath = "";
@@ -13922,6 +14215,7 @@ function migrateRepository(options) {
           }
         });
         docsConfig = projected.docsConfig;
+        mintlifyApiTabSlots = projected.apiTabSlots;
         warnings.push(...projected.warnings);
         for (const repo of projected.gatedSourceRefs) gatedSourceRepos.add(repo.toLowerCase());
         for (const appearance of projected.referenceAccess) {
@@ -15029,7 +15323,8 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       warnings.push({ code: "gated-page", message: sharedSpecMessage(path, excluded), source: path });
     };
     const nameSpec = createSpecAssetNamer();
-    const allSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs, nameSpec, pages.filter((page) => !restrictedPages.has(page)));
+    const generatedEndpointPages = /* @__PURE__ */ new Set();
+    const allSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs, nameSpec, pages.filter((page) => !restrictedPages.has(page)), mintlifyApiTabSlots);
     const navigation = navigationSpecContext(mintlifyConfig, (path) => resolvePageIdentity(path)?.id ?? null);
     const defaultSources = /* @__PURE__ */ new Set([
       ...allSpecs.filter((spec) => !spec.pageOnly && spec.tabLabel === void 0).map((spec) => spec.sourcePath),
@@ -15072,12 +15367,61 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
         spec.pageReferenced = namedByPages.has(spec);
         spec.generatedNavigation = Boolean(spec.directory) && !publishedSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, true));
       }
-      docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs, warnings);
+      const listingSpecs = resolvedSpecs.filter((spec) => spec.groups && spec.endpointPages);
+      const unbound = docsConfig;
+      docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs.filter((spec) => !listingSpecs.includes(spec)), warnings);
+      const ledger = createEndpointPageLedger(pages);
+      const tabs = docsConfig.tabs.map((tab) => ({ ...tab }));
+      const pagesBefore = pages.length;
+      const endpointSpecs = /* @__PURE__ */ new Set();
+      for (const spec of listingSpecs) {
+        if (!spec.groups || !spec.endpointPages) continue;
+        const added = addEndpointPages({
+          tabs,
+          pages,
+          ledger,
+          spec: {
+            assetPath: specAssetPath(spec.filename),
+            source: spec.sourcePath,
+            content: spec.content,
+            groups: spec.groups,
+            target: spec.endpointPages,
+            tabLabel: spec.tabLabel,
+            parentTab: spec.parentTab,
+            icon: spec.icon,
+            hidden: spec.hidden
+          }
+        });
+        if (!added) continue;
+        spec.endpointOperations = added.operations;
+        endpointSpecs.add(spec);
+      }
+      reportEndpointPages(ledger, warnings);
+      for (const spec of resolvedSpecs) if (spec.directoryWarning && !endpointSpecs.has(spec)) warnings.push(spec.directoryWarning);
+      for (const page of pages.slice(pagesBefore)) generatedEndpointPages.add(page);
+      docsConfig = injectOpenApiSpecs({ ...docsConfig, tabs }, listingSpecs.filter((spec) => !endpointSpecs.has(spec)), warnings);
+      if (remoteApiSpecs.length === 0 && endpointSpecs.size > 0) {
+        const bySource = new Map(resolvedSpecs.map((spec) => [specAssetPath(spec.filename), spec]));
+        qualifyDisplacedBareRefs({
+          pages,
+          before: specLookupOrder(injectOpenApiSpecs(unbound, resolvedSpecs).tabs, docsConfig.navigation?.versions),
+          after: specLookupOrder(docsConfig.tabs, docsConfig.navigation?.versions),
+          content: (source) => bySource.get(source)?.content,
+          qualifier: (source) => bySource.get(source)?.sourcePath ?? source
+        });
+      }
+      const mountOf = (spec) => endpointSpecs.has(spec) ? { prefix: spec.endpointPages?.directory, operations: spec.endpointOperations } : { prefix: spec.directory };
       if (remoteApiSpecs.length > 0) {
-        localApiMounts.push(...resolvedSpecs.flatMap((spec) => spec.directory ? [{ filename: spec.filename, directory: spec.directory, ...spec.tabLabel ? { tab: spec.tabLabel } : {} }] : []));
+        localApiMounts.push(...resolvedSpecs.flatMap((spec) => {
+          const { prefix, operations } = mountOf(spec);
+          return prefix ? [{ filename: spec.filename, directory: prefix, ...spec.tabLabel ? { tab: spec.tabLabel } : {}, ...operations ? { endpointOperations: operations } : {} }] : [];
+        }));
       } else {
         const endpointRedirects = linkApiMounts(
-          resolvedSpecs.map((spec) => ({ filename: spec.filename, content: spec.content, prefix: spec.directory, ...spec.tabLabel ? { tab: spec.tabLabel } : {} })),
+          resolvedSpecs.map((spec) => {
+            const { prefix, operations } = mountOf(spec);
+            return { filename: spec.filename, content: spec.content, prefix, ...operations ? { endpointPages: true, operations } : {}, ...spec.tabLabel ? { tab: spec.tabLabel } : {} };
+          }),
           docsConfig,
           pages,
           warnings
@@ -15134,7 +15478,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       }
       return sameName ? "the file could not be read as an OpenAPI document" : `no file exists at "${key}"`;
     };
-    rewriteMintlifyPageSpecRefs(pages, pageSpecs, new Set(remoteApiSpecs.map((spec) => spec.url)), warnings, explainMissingSpec);
+    rewriteMintlifyPageSpecRefs(pages.filter((page) => !generatedEndpointPages.has(page)), pageSpecs, new Set(remoteApiSpecs.map((spec) => spec.url)), warnings, explainMissingSpec);
     if (docsConfig.tabs.some((tab) => tab.api)) docsConfig = { ...docsConfig, api: { ...docsConfig.api, specLink: false } };
   }
   if (platform === "mintlify") {
@@ -15356,6 +15700,24 @@ ${body}`;
   if (docsConfig.redirects) {
     docsConfig = dropConflictingRedirects(dropUnroutableRedirects(docsConfig, warnings), [...pages, ...sourceRefPages], warnings);
   }
+  const redirectSources = new Map((docsConfig.redirects ?? []).map((redirect) => [(redirect.source.replace(/\/+$/, "") || "/").toLowerCase(), redirect.destination]));
+  const linkRedirects = [];
+  for (const page of [...pages, ...sourceRefPages]) {
+    if (!page.externalUrl) continue;
+    for (const source of pageEntryRoutes(page)) {
+      const existing = redirectSources.get(source.toLowerCase());
+      if (existing !== void 0) {
+        warnings.push({
+          code: "unsupported-config",
+          message: `Page "${page.id}" links to ${stripControlCharacters(page.externalUrl)}, but "${source}" already redirects to ${stripControlCharacters(existing)}; that redirect was kept, so "${source}" does not open the link.`
+        });
+        continue;
+      }
+      redirectSources.set(source.toLowerCase(), page.externalUrl);
+      linkRedirects.push({ source, destination: page.externalUrl, permanent: false });
+    }
+  }
+  if (linkRedirects.length > 0) docsConfig = { ...docsConfig, redirects: [...docsConfig.redirects ?? [], ...linkRedirects] };
   if (pages.length === 0) {
     const reasons = warnings.map((warning) => warning.message);
     throw new Error(reasons.length ? `No importable Markdown or MDX pages were found in the repository. Warnings encountered during migration:
@@ -15439,7 +15801,7 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     });
   }
   if (!docsConfig.navigation?.display && docsConfig.tabs.filter((tab) => !tab.hidden).length > 6) {
-    docsConfig = { ...docsConfig, navigation: { display: "dropdown" } };
+    docsConfig = { ...docsConfig, navigation: { display: "dropdown", ...docsConfig.navigation?.groupHeadings ? { groupHeadings: docsConfig.navigation.groupHeadings } : {} } };
   }
   const themeColors = mintlifyConfig ? mintlifyThemeColors(mintlifyConfig.colors) : fernRawConfig ? fernThemeColors(fernRawConfig.colors) ?? (fernRawConfig["global-theme"] === "nvidia" ? { primary: "#76B900" } : void 0) : isTopLevelDocusaurus ? presentation?.colors ?? readDocusaurusThemeColor(docusaurusProjectRoot) : void 0;
   const assetPaths = new Set(assets.map((asset) => asset.path));
@@ -15635,7 +15997,7 @@ function renderPage(bundle, page) {
     page.icon ? `icon: ${yamlString(page.icon)}` : null,
     page.iconType ? `iconType: ${yamlString(page.iconType)}` : null,
     `description: ${yamlString(page.description)}`,
-    page.descriptionPlacement === "body" ? "descriptionPlacement: body" : null,
+    page.descriptionPlacement === "body" || page.descriptionPlacement === "operation" ? `descriptionPlacement: ${page.descriptionPlacement}` : null,
     page.badge ? `badge: ${yamlString(page.badge)}` : null,
     page.keywords.length > 0 ? `keywords: [${page.keywords.map(yamlString).join(", ")}]` : null,
     page.mode ? `mode: ${yamlString(page.mode)}` : null,
@@ -15760,6 +16122,7 @@ function renderMigrationFiles(bundle, options = {}) {
 // src/url-run.ts
 import { createHash as createHash6 } from "crypto";
 import { load as load8 } from "cheerio";
+import { parse as parse2, postprocess, preprocess } from "micromark";
 import remarkParse5 from "remark-parse";
 import remarkMdx5 from "remark-mdx";
 import { unified as unified5 } from "unified";
@@ -16838,9 +17201,9 @@ function apiOperationCodeControls(body, specification, operation) {
 }
 
 // src/url-run.ts
-var CONVERTER_VERSION = "url-evidence-v6";
+var CONVERTER_VERSION = "url-evidence-v7";
 var parser3 = unified5().use(remarkParse5).use(remarkMdx5);
-var ACCEPT = "text/markdown,text/html,application/xhtml+xml;q=0.9";
+var ACCEPT = "text/html,application/xhtml+xml";
 var MAX_RESPONSE_BYTES = 8e6;
 var MAX_ASSET_BYTES2 = 1e7;
 var MAX_RECORDS = 1e5;
@@ -16870,6 +17233,11 @@ function canonical(value, base) {
     return null;
   }
 }
+function sameRouteMarkdownRepresentation(alternate, primary) {
+  const target2 = new URL(alternate), source = new URL(primary);
+  const directory2 = (path) => path.replace(/\.mdx?$/i, "").replace(/\/index\/?$/i, "").replace(/\/$/, "");
+  return target2.origin === source.origin && target2.search === source.search && directory2(target2.pathname) === directory2(source.pathname) && /\.mdx?$/i.test(target2.pathname);
+}
 function classifyMigrationResponse(document) {
   if (document.status && document.status >= 400) return "unsupported";
   if (/\/(?:llms(?:-full)?|robots)\.txt$|\/sitemap[^/]*\.xml$|\/search(?:\.html)?$/i.test(document.finalUrl.pathname) || /\.(?:json|ya?ml)$/i.test(document.finalUrl.pathname) || /(?:xml|json)/i.test(document.contentType)) return "index";
@@ -17120,7 +17488,7 @@ function resolveMigrationRecord(records, record) {
   }
   return record;
 }
-function navigationConfig(checkpoint, records) {
+function navigationConfig(checkpoint, records, occurrencePages = /* @__PURE__ */ new Map()) {
   const navigation = checkpoint.navigation;
   const shortcuts = [];
   const collectShortcuts = (nodes) => {
@@ -17145,7 +17513,7 @@ function navigationConfig(checkpoint, records) {
   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 page = occurrencePages.get(node) ?? target2?.page;
     const children = project2(node.children ?? []);
     if (children.length) {
       const contains = (entries) => entries.some((entry) => typeof entry === "string" ? entry === (page && projection.navigationId(page)) : contains(entry.pages));
@@ -17445,8 +17813,19 @@ async function runUrlMigration(options) {
     if (!record.evidence) continue;
     const final = canonical(record.evidence.finalUrl, sourceUrl);
     if (!final) continue;
-    if (record.outcome === "imported") enqueueArticleLinks(record.evidence.links, final, record.url);
-    else if (record.outcome === "excluded") {
+    if (record.outcome === "imported") {
+      enqueueArticleLinks(record.evidence.links, final, record.url);
+      for (const reference of record.evidence.markdownRepresentations ?? []) {
+        const alternate = canonical(reference, final);
+        if (!alternate || !sameRouteMarkdownRepresentation(alternate, final)) continue;
+        enqueue(alternate, final, "declared-markdown-representation");
+        const sibling = records.get(alternate);
+        if (sibling && sibling.representationOf !== record.url) {
+          sibling.representationOf = record.url;
+          changed.push(sibling);
+        }
+      }
+    } else if (record.outcome === "excluded") {
       if (classifyMigrationResponse({ finalUrl: new URL(final), contentType: record.evidence.contentType, body: "" }) === "index") {
         for (const link of record.evidence.links) enqueue(link, final, record.url);
       }
@@ -17529,6 +17908,7 @@ async function runUrlMigration(options) {
     let claimedId;
     let claimedFinal;
     let markdownRepresentation;
+    const markdownRepresentations = [];
     let exactKey;
     try {
       delete record.reason;
@@ -17621,13 +18001,13 @@ async function runUrlMigration(options) {
         $('link[rel="alternate"][type="text/markdown"][href]').each((_index, node) => {
           const alternate = canonical($(node).attr("href"), final);
           if (!alternate) return;
-          const target2 = new URL(alternate), primary = new URL(final);
-          const directory2 = (path) => path.replace(/\.mdx?$/i, "").replace(/\/index\/?$/i, "").replace(/\/$/, "");
-          if (target2.origin !== primary.origin || target2.search !== primary.search || directory2(target2.pathname) !== directory2(primary.pathname) || !/\.mdx?$/i.test(target2.pathname)) return;
+          if (!sameRouteMarkdownRepresentation(alternate, final)) return;
           enqueue(alternate, final, "declared-markdown-representation");
           const sibling = records.get(alternate);
+          if (!sibling) return;
           sibling.representationOf = record.url;
           markdownRepresentation ??= alternate;
+          markdownRepresentations.push(alternate);
           changed.push(sibling);
         });
       }
@@ -17640,7 +18020,8 @@ async function runUrlMigration(options) {
         }
         enqueueNavigation(observedNavigation, final);
       }
-      if (imported >= maxPages) {
+      const replacesRepresentation = imported >= maxPages && markdownRepresentations.some((url) => records.get(url)?.page);
+      if (imported >= maxPages && !replacesRepresentation) {
         record.outcome = "excluded";
         record.reason = "A discovery endpoint resolved to an article after the selected page limit.";
         return;
@@ -17659,14 +18040,17 @@ async function runUrlMigration(options) {
       const locale = language.locale;
       const navigationId = locale ? id.split("/").filter((segment) => segment.toLowerCase() !== locale.toLowerCase()).join("/") || "introduction" : id;
       const identityId = locale ? `${locale}/${navigationId}` : id;
-      if (usedIds.has(identityId) && usedIds.get(identityId) !== record.url) {
+      const owner = records.get(usedIds.get(identityId) ?? "");
+      const sharesDeclaredRepresentation = owner && (owner.representationOf === record.url || record.representationOf === owner.url);
+      if (owner && owner !== record && !sharesDeclaredRepresentation) {
         record.outcome = "failed";
         record.reason = `Destination collision for ${identityId}.`;
         return;
       }
-      usedIds.set(identityId, record.url);
+      if (!owner || owner === record || owner.representationOf === record.url) usedIds.set(identityId, record.url);
       claimedId = identityId;
       const evidence = evidenceOf(document);
+      if (markdownRepresentations.length) evidence.markdownRepresentations = markdownRepresentations;
       const page = convert(document, id);
       if (!page) {
         record.outcome = "failed";
@@ -17877,6 +18261,7 @@ ${difference}`;
       if (!primary || primary === record) continue;
       const winner = primary.outcome === "imported" ? primary : record.outcome === "imported" && primary.outcome === "failed" ? record : void 0;
       if (!winner) continue;
+      if (winner.page) usedIds.set(winner.page.id, winner.url);
       const alternate = winner === primary ? record : primary;
       if (alternate.outcome === "alias" && alternate.aliasOf === winner.url) continue;
       if (alternate.outcome === "imported") {
@@ -17898,7 +18283,17 @@ ${difference}`;
   settleArticleIdentities();
   while (cursor < pending.length && !options.signal?.aborted && !budgetExhausted && cursor < (options.maxCaptures ?? Infinity)) {
     if (imported >= maxPages) {
-      const index = pending.findIndex((record, position) => position >= cursor && isDiscoveryIndex(new URL(record.url), source));
+      const index = pending.findIndex((record, position) => {
+        if (position < cursor || record.outcome !== "pending") return false;
+        const url = new URL(record.url);
+        if (isDiscoveryIndex(url, source)) return true;
+        if (/\.mdx?$/i.test(url.pathname)) return false;
+        return [".md", ".mdx", "/index.md", "/index.mdx"].some((extension) => {
+          const alternate = new URL(url);
+          alternate.pathname = alternate.pathname.replace(/\/index$/i, "") + extension;
+          return records.get(alternate.href)?.outcome === "imported";
+        });
+      });
       if (index < 0) break;
       pending.splice(cursor, 0, pending.splice(index, 1)[0]);
     }
@@ -17922,19 +18317,60 @@ ${difference}`;
   }
   const navigationLabels = /* @__PURE__ */ new Map();
   const navigationIssues = [];
+  const navigationOccurrences = /* @__PURE__ */ new Map();
   const labelPages = (nodes) => {
     for (const node of nodes) {
       const entry = node.url ? records.get(canonical(node.url, sourceUrl) ?? "") : void 0;
       const target2 = resolveMigrationRecord(records, entry);
-      if (target2?.page && node.label && !node.children?.length && !entry?.aliasAnchor) {
-        const previous = navigationLabels.get(target2.url);
-        if (previous && previous !== node.label) navigationIssues.push({ code: "unsupported-component", source: target2.url, message: `This page has multiple source navigation labels (${previous}, ${node.label}); review the shared sidebar title.` });
-        else navigationLabels.set(target2.url, node.label);
+      if (entry && target2?.page && node.label && !node.children?.length && !entry.aliasAnchor) {
+        const occurrences = navigationOccurrences.get(target2) ?? [];
+        occurrences.push({ node, entry });
+        navigationOccurrences.set(target2, occurrences);
       }
       labelPages(node.children ?? []);
     }
   };
   labelPages(checkpoint.navigation);
+  const occurrencePages = /* @__PURE__ */ new Map();
+  const navigationAliases = /* @__PURE__ */ new Map();
+  const occupiedPageIds = new Set(checkpoint.records.flatMap((record) => record.page ? [projection.pageId(record.page)] : []));
+  const navigationRedirects = [];
+  for (const [target2, occurrences] of navigationOccurrences) {
+    const final = target2.evidence && canonical(target2.evidence.finalUrl, sourceUrl);
+    const primary = occurrences.find(({ entry }) => entry.url === final) ?? occurrences.find(({ entry }) => entry === target2) ?? occurrences[0];
+    navigationLabels.set(target2.url, primary.node.label);
+    for (const { node, entry } of occurrences) {
+      if (node.label === primary.node.label) continue;
+      const existing = navigationAliases.get(entry.url);
+      if (existing?.page.navTitle === node.label && existing.target === target2) {
+        occurrencePages.set(node, existing.page);
+        continue;
+      }
+      const sourceRoute = new URL(entry.url);
+      const id = inScope(sourceRoute, source, scopePath) ? idForUrl(sourceRoute, scopePath) : null;
+      const locale = projection.canonicalLocale(target2.page);
+      let navigationId = id && (locale ? id.split("/").filter((segment) => segment.toLowerCase() !== locale.toLowerCase()).join("/") || "introduction" : id);
+      const legacyPrefix = locale && `${locale.toLowerCase()}-`;
+      if (navigationId && legacyPrefix && projection.navigationId(target2.page) !== target2.page.navigationId && navigationId.toLowerCase().startsWith(legacyPrefix)) navigationId = navigationId.slice(legacyPrefix.length);
+      const page = navigationId ? {
+        ...target2.page,
+        id: locale ? `${locale}/${navigationId}` : navigationId,
+        navigationId,
+        ...locale ? { locale } : {},
+        navTitle: node.label,
+        source: entry.url,
+        noindex: true
+      } : void 0;
+      if (!page || existing || occupiedPageIds.has(projection.pageId(page))) {
+        navigationIssues.push({ code: "unsupported-component", source: target2.url, message: `This page has multiple source navigation labels (${primary.node.label}, ${node.label}); their source routes cannot retain distinct sidebar titles safely.` });
+        continue;
+      }
+      occupiedPageIds.add(projection.pageId(page));
+      navigationAliases.set(entry.url, { page, target: target2 });
+      occurrencePages.set(node, page);
+      navigationRedirects.push({ source: projection.route(page), destination: projection.route(target2.page), permanent: true });
+    }
+  }
   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 {
@@ -17955,6 +18391,10 @@ ${difference}`;
     const hasBrokenSourceAnchor = Boolean(url.hash && destination?.outcome === "imported" && destination.evidence && !destination.evidence.anchors.includes(anchor));
     return `${route}${hasBrokenSourceAnchor ? "" : effectiveHash}`;
   }) }] : []);
+  const projectedPages = new Map(pages.map((page) => [page.id, page]));
+  for (const { page, target: target2 } of navigationAliases.values()) {
+    pages.push({ ...page, id: projection.pageId(page), body: projectedPages.get(projection.pageId(target2.page)).body });
+  }
   const validation = validateUrlMigration(checkpoint, Boolean(options.signal?.aborted));
   validation.issues.push(...navigationIssues);
   if (navigationIssues.length && validation.status === "passed") validation.status = "partial";
@@ -17975,12 +18415,12 @@ ${difference}`;
     platform: options.platform ?? "generic",
     pages,
     assets: [...assets.values()],
-    docsConfig: navigationConfig(checkpoint, records) ?? buildNavigationFromPages(pages),
+    docsConfig: navigationConfig(checkpoint, records, occurrencePages) ?? 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.redirects.length || navigationRedirects.length) bundle.docsConfig.redirects = [...projection.redirects, ...navigationRedirects];
   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 })) };
@@ -17998,9 +18438,11 @@ function rewriteMarkdownDestinations(body, rewrite) {
     const original = body.slice(start, end);
     const replacement = rewrite(node.url);
     if (replacement === node.url) return null;
-    const index = original.lastIndexOf(node.url);
-    if (index < 0) return null;
-    return { start: start + index, end: start + index + node.url.length, replacement };
+    const destinations = postprocess(parse2().document().write(preprocess()(original, void 0, true))).filter(([event, token]) => event === "enter" && ["resourceDestinationString", "definitionDestinationString", "autolinkProtocol", "autolinkEmail"].includes(token.type));
+    const destination = destinations.at(-1)?.[1];
+    if (!destination) return null;
+    const escaped = replacement.replace(/[\\&()<>]/g, "\\$&").replace(/[\t\n\r ]/g, (character) => encodeURIComponent(character));
+    return { start: start + destination.start.offset, end: start + destination.end.offset, replacement: escaped };
   }).filter((edit) => edit !== null).sort((a, b) => b.start - a.start);
   for (const node of markdownNodes(body)) for (const attribute of node.attributes ?? []) {
     if (!attribute.name || !["src", "poster", "href", "srcSet", "srcset", "img", "primaryHref", "secondaryHref"].includes(attribute.name) || !attribute.position) continue;
@@ -18164,6 +18606,12 @@ function slug(value) {
 function operationTarget(specId, operation) {
   return `/api/${specId}/${thallyOperationSlugSegments(operation.path, operation.method).join("/")}`;
 }
+function bindApiTab(tabs, reference, api) {
+  const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
+  if (tab) tab.api = api;
+  else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api }, reference.parentTab);
+  return tab?.tab ?? reference.tabLabel ?? "API Reference";
+}
 async function hydrateRemoteApiSpecs(bundle, fetcher) {
   if (!bundle.remoteApiSpecs?.length) return bundle;
   const assets = [...bundle.assets];
@@ -18172,7 +18620,8 @@ 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 ledger = createEndpointPageLedger(pages);
+  const pagesBefore = pages.length;
   const endpointUrls = /* @__PURE__ */ new Map();
   for (const page of bundle.pages) {
     for (const match of page.body.matchAll(/\/[a-z0-9_/-]+/gi)) {
@@ -18183,6 +18632,10 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
     }
   }
   const bound = [];
+  const apiTabs = bundle.docsConfig.tabs.map((tab) => ({ ...tab }));
+  for (const mount of bundle.localApiMounts ?? []) {
+    if (mount.endpointOperations) bindApiTab(apiTabs, { tabLabel: mount.tab }, { source: `openapi/${mount.filename}` });
+  }
   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);
@@ -18202,11 +18655,29 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
         const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;
         if (ref?.specRef === reference.url) page.openapi = withSpecRef(ref, `openapi/${filename}`);
       }
-      const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
+      bindApiTab(apiTabs, reference, { source: `openapi/${filename}` });
+      const endpoint = reference.groups && reference.endpointPages ? addEndpointPages({
+        tabs,
+        pages,
+        ledger,
+        spec: {
+          assetPath: `openapi/${filename}`,
+          source: reference.url,
+          content: body,
+          groups: reference.groups,
+          target: reference.endpointPages,
+          tabLabel: reference.tabLabel,
+          parentTab: reference.parentTab,
+          icon: reference.icon,
+          hidden: reference.hidden
+        }
+      }) : null;
+      if (endpoint) {
+        bound.push({ reference, filename, content: body, operations, tabName: reference.tabLabel ?? "API Reference", endpointOperations: endpoint.operations });
+        continue;
+      }
       const api = { source: `openapi/${filename}`, ...reference.navigation === false ? { navigation: false } : {}, ...reference.groups ? { groups: reference.groups } : {} };
-      if (tab) tab.api = api;
-      else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api }, reference.parentTab);
-      bound.push({ reference, filename, content: body, operations, tabName: tab?.tab ?? reference.tabLabel ?? "API Reference" });
+      bound.push({ reference, filename, content: body, operations, tabName: bindApiTab(tabs, reference, api) });
     } catch (error) {
       warnings.push({
         code: "fetch-failed",
@@ -18215,19 +18686,22 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
       });
     }
   }
+  const pageMounts = bound.flatMap(({ reference, endpointOperations }) => endpointOperations && reference.endpointPages ? [reference.endpointPages.directory] : []);
   const directories = [
     ...(bundle.localApiMounts ?? []).map(({ directory: directory2 }) => directory2),
-    ...bundle.remoteApiSpecs.flatMap((reference) => (reference.directories ?? []).map(({ directory: directory2 }) => directory2))
+    ...bundle.remoteApiSpecs.flatMap((reference) => (reference.directories ?? []).map(({ directory: directory2 }) => directory2)),
+    ...pageMounts
   ];
   const endpointRedirects = linkApiMounts(
     [
-      ...(bundle.localApiMounts ?? []).map(({ filename, directory: directory2, tab }) => ({
+      ...(bundle.localApiMounts ?? []).map(({ filename, directory: directory2, tab, endpointOperations }) => ({
         filename,
         content: Buffer.from(assets.find((asset) => asset.path === `openapi/${filename}`)?.content ?? []),
         prefix: directory2,
+        ...endpointOperations ? { endpointPages: true, operations: endpointOperations } : {},
         ...tab ? { tab } : {}
       })),
-      ...bound.flatMap(({ reference, filename, content, tabName }) => (reference.directories ?? []).map(({ directory: directory2, operations: listed }) => ({ filename, content, prefix: directory2, tab: tabName, ...listed ? { operations: listed } : {} })))
+      ...bound.flatMap(({ reference, filename, content, tabName, endpointOperations }) => endpointOperations && reference.endpointPages ? [{ filename, content, prefix: reference.endpointPages.directory, tab: tabName, endpointPages: true, operations: endpointOperations }] : (reference.directories ?? []).map(({ directory: directory2, operations: listed }) => ({ filename, content, prefix: directory2, tab: tabName, ...listed ? { operations: listed } : {} })))
     ],
     { ...bundle.docsConfig, tabs, redirects },
     pages,
@@ -18238,6 +18712,18 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
     redirects.push(redirect);
     endpointUrls.set(literalRoute(redirect.source) ?? redirect.source, redirect.destination);
   }
+  reportEndpointPages(ledger, warnings);
+  qualifyDisplacedBareRefs({
+    pages,
+    before: specLookupOrder(apiTabs, bundle.docsConfig.navigation?.versions),
+    after: specLookupOrder(tabs, bundle.docsConfig.navigation?.versions),
+    content: (source) => {
+      const asset = assets.find((entry) => entry.path === source);
+      return asset ? Buffer.from(asset.content) : void 0;
+    },
+    qualifier: (source) => source
+  });
+  const served = servedRoutes(pages);
   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}/`));
@@ -18262,12 +18748,19 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
     const endpoint = endpointUrls.get(literalRoute(redirect.destination) ?? "");
     return endpoint ? { ...redirect, destination: endpoint } : redirect;
   });
+  const boundConfig = { ...bundle.docsConfig, tabs, ...direct.length > 0 ? { redirects: direct } : {} };
+  const newPages = pages.slice(pagesBefore);
+  const withDirectories = bundle.platform === "mintlify" && newPages.length > 0 ? addMintlifyDirectoryRedirects(boundConfig, newPages) : boundConfig;
+  const linkRedirects = new Set(pages.flatMap((page) => page.externalUrl ? pageEntryRoutes(page).map((source) => `${source} ${page.externalUrl}`) : []));
+  const isLinkRedirect = (redirect) => linkRedirects.has(`${redirect.source} ${redirect.destination}`);
+  const links = (withDirectories.redirects ?? []).filter(isLinkRedirect);
+  const unchecked = links.length > 0 ? { ...withDirectories, redirects: withDirectories.redirects.filter((redirect) => !isLinkRedirect(redirect)) } : withDirectories;
+  const checked = dropConflictingRedirects(dropUnroutableRedirects(unchecked, warnings), pages, warnings);
   return {
     ...bundle,
     pages,
     assets,
-    // 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),
+    docsConfig: links.length > 0 ? { ...checked, redirects: [...checked.redirects ?? [], ...links] } : checked,
     warnings
   };
 }