@thallylabs/migrate 0.2.32 → 0.2.34

package/dist/index.js

@@ -230,8 +230,11 @@ var JS_GLOBALS = /* @__PURE__ */ new Set([
   "BroadcastChannel"
 ]);
 var IMPLICIT_MODULE_NAMES = /* @__PURE__ */ new Set(["React", "MintlifyComponents"]);
-function parse(source) {
-  return ts.createSourceFile("inline.tsx", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+function scriptKindFor(fileName) {
+  return /\.[cm]?ts$/.test(fileName) ? ts.ScriptKind.TS : ts.ScriptKind.TSX;
+}
+function parse(source, fileName = "inline.tsx") {
+  return ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKindFor(fileName));
 }
 function bindingNames(name, into) {
   if (ts.isIdentifier(name)) into.add(name.text);
@@ -240,20 +243,44 @@ function bindingNames(name, into) {
 function isFunctionLike(node) {
   return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node);
 }
+function hoistedVarNames(root, into) {
+  const collect = (node) => {
+    if (isFunctionLike(node) || ts.isClassLike(node) || ts.isModuleDeclaration(node)) return;
+    if (ts.isVariableDeclaration(node) && !ts.isCatchClause(node.parent) && !(ts.getCombinedNodeFlags(node) & ts.NodeFlags.BlockScoped)) bindingNames(node.name, into);
+    ts.forEachChild(node, collect);
+  };
+  collect(root);
+}
 function functionScope(fn) {
   const scope = /* @__PURE__ */ new Set();
   if ((ts.isFunctionExpression(fn) || ts.isFunctionDeclaration(fn)) && fn.name) scope.add(fn.name.text);
   for (const parameter of fn.parameters) bindingNames(parameter.name, scope);
-  function collect(node) {
-    if (ts.isVariableDeclaration(node)) bindingNames(node.name, scope);
-    if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) scope.add(node.name.text);
-    if (isFunctionLike(node)) return;
-    ts.forEachChild(node, collect);
-  }
-  if (fn.body) ts.forEachChild(fn.body, collect);
-  if (fn.body && !ts.isBlock(fn.body)) collect(fn.body);
   return scope;
 }
+function lexicalNames(statements) {
+  const names = /* @__PURE__ */ new Set();
+  for (const statement of statements) {
+    if (ts.isVariableStatement(statement)) {
+      if (statement.declarationList.flags & ts.NodeFlags.BlockScoped) for (const declaration of statement.declarationList.declarations) bindingNames(declaration.name, names);
+    } else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) names.add(statement.name.text);
+  }
+  return names;
+}
+function ownScope(node) {
+  if (ts.isBlock(node)) return lexicalNames(node.statements);
+  if (ts.isCaseBlock(node)) return lexicalNames(node.clauses.flatMap((clause) => [...clause.statements]));
+  if ((ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node)) && node.initializer && ts.isVariableDeclarationList(node.initializer)) {
+    const names = /* @__PURE__ */ new Set();
+    if (node.initializer.flags & ts.NodeFlags.BlockScoped) for (const declaration of node.initializer.declarations) bindingNames(declaration.name, names);
+    return names;
+  }
+  if (ts.isCatchClause(node) && node.variableDeclaration) {
+    const names = /* @__PURE__ */ new Set();
+    bindingNames(node.variableDeclaration.name, names);
+    return names;
+  }
+  return void 0;
+}
 function collectRefs(root) {
   const refs = [];
   const assigned = [];
@@ -268,13 +295,22 @@ function collectRefs(root) {
   function walkNode(node, scopes, inAsync) {
     if (ts.isTypeNode(node)) return;
     if (isFunctionLike(node)) {
-      const nextScopes = [...scopes, functionScope(node)];
+      const parameterScopes = [...scopes, functionScope(node)];
       const async = !!node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword);
       for (const parameter of node.parameters) {
-        if (!ts.isIdentifier(parameter.name)) walkNode(parameter.name, nextScopes, async);
-        if (parameter.initializer) walkNode(parameter.initializer, nextScopes, async);
+        if (!ts.isIdentifier(parameter.name)) walkNode(parameter.name, parameterScopes, async);
+        if (parameter.initializer) walkNode(parameter.initializer, parameterScopes, async);
+      }
+      if (node.body) {
+        const hoisted = /* @__PURE__ */ new Set();
+        hoistedVarNames(node.body, hoisted);
+        walkNode(node.body, [...parameterScopes, hoisted], async);
       }
-      if (node.body) walkNode(node.body, nextScopes, async);
+      return;
+    }
+    const own2 = ownScope(node);
+    if (own2) {
+      ts.forEachChild(node, (child) => walkNode(child, [...scopes, own2], inAsync));
       return;
     }
     if (ts.isAwaitExpression(node) && !inAsync) awaitOutsideAsync = true;
@@ -651,6 +687,23 @@ function unboundTags(moduleSource, boundNames) {
   }
   return [...tags].sort();
 }
+function unboundBuiltinTags(moduleSource, boundNames, fileName) {
+  const tags = /* @__PURE__ */ new Set();
+  const values = /* @__PURE__ */ new Set();
+  for (const statement of parse(moduleSource, fileName).statements) {
+    if (ts.isImportDeclaration(statement)) continue;
+    for (const { name, kind } of collectRefs(statement).refs) {
+      if (boundNames.has(name)) continue;
+      if (kind === "tag" || kind === "member") tags.add(name);
+      else values.add(name);
+    }
+  }
+  const isGlobal = (name) => JS_GLOBALS.has(name) || BROWSER_IDENTIFIERS.has(name) || SERVER_ONLY_IDENTIFIERS.has(name);
+  const builtinTags = [...tags].filter(isThallyBuiltinComponent);
+  const shadowed = builtinTags.filter((name) => JS_GLOBALS.has(name) && values.has(name)).sort();
+  const builtinValues = [...values].filter((name) => isThallyBuiltinComponent(name) && !isGlobal(name));
+  return { bind: [.../* @__PURE__ */ new Set([...builtinTags.filter((name) => !shadowed.includes(name)), ...builtinValues])].sort(), shadowed };
+}
 var INLINE_SAFE_GLOBALS = /* @__PURE__ */ new Set([
   "undefined",
   "NaN",
@@ -719,12 +772,14 @@ function isSelfContainedFunction(node) {
 function pageScopeNames(esmSources) {
   const names = /* @__PURE__ */ new Set();
   for (const source of esmSources) {
-    for (const statement of parse(source).statements) {
+    const sf = parse(source);
+    for (const statement of sf.statements) {
       for (const local of importLocals(statement.getText())) names.add(local);
       if (ts.isImportDeclaration(statement)) continue;
       const target2 = ts.isExportDeclaration(statement) || ts.isExportAssignment(statement) ? void 0 : statement;
       if (target2) for (const name of declaredNames(target2).names) names.add(name);
     }
+    hoistedVarNames(sf, names);
   }
   return names;
 }
@@ -2393,9 +2448,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) {
@@ -2934,13 +2989,7 @@ function sanitizeCssModuleSelectors(css) {
   return { css: root.toString(), omitted };
 }
 function sourceFile(source, filename) {
-  return ts2.createSourceFile(
-    filename,
-    source,
-    ts2.ScriptTarget.Latest,
-    true,
-    /\.[cm]?ts$/.test(filename) ? ts2.ScriptKind.TS : ts2.ScriptKind.TSX
-  );
+  return ts2.createSourceFile(filename, source, ts2.ScriptTarget.Latest, true, scriptKindFor(filename));
 }
 function walk(node, visitor) {
   visitor(node);
@@ -2997,7 +3046,7 @@ function needsClientBoundary(source) {
   visitNode(source);
   return needed;
 }
-function implicitReactImports(source) {
+function implicitReactImports(source, onShadowed) {
   const bindings = /* @__PURE__ */ new Set();
   const references = /* @__PURE__ */ new Set();
   function bind(name) {
@@ -3015,7 +3064,9 @@ function implicitReactImports(source) {
     }
     if (ts2.isVariableStatement(statement)) for (const declaration of statement.declarationList.declarations) bind(declaration.name);
     if ((ts2.isFunctionDeclaration(statement) || ts2.isClassDeclaration(statement)) && statement.name) bindings.add(statement.name.text);
+    if ((ts2.isEnumDeclaration(statement) || ts2.isModuleDeclaration(statement) || ts2.isImportEqualsDeclaration(statement)) && ts2.isIdentifier(statement.name)) bindings.add(statement.name.text);
   }
+  hoistedVarNames(source, bindings);
   function visit(node) {
     if (ts2.isIdentifier(node) && !(ts2.isPropertyAccessExpression(node.parent) && node.parent.name === node) && !(ts2.isPropertyAssignment(node.parent) && node.parent.name === node)) references.add(node.text);
     ts2.forEachChild(node, visit);
@@ -3023,26 +3074,50 @@ function implicitReactImports(source) {
   visit(source);
   const hooks = [...REACT_GLOBALS].filter((name) => references.has(name) && !bindings.has(name)).sort();
   const usesMintlifyComponents = references.has("MintlifyComponents") && !bindings.has("MintlifyComponents");
+  const leafBound = /* @__PURE__ */ new Set();
   const implicitComponents = MINTLIFY_COMPONENT_MODULES.map(({ module, names }) => {
-    const needed = names.filter((name) => references.has(name) && !bindings.has(name));
+    const needed = names.filter((name) => name !== "Note" && references.has(name) && !bindings.has(name));
+    for (const name of needed) leafBound.add(name);
     return needed.length ? `import { ${needed.join(", ")} } from '${module}';` : "";
   }).filter(Boolean);
+  const { bind: builtinTags, shadowed } = unboundBuiltinTags(source.text, bindings, source.fileName);
+  const registryNames = builtinTags.filter((name) => !leafBound.has(name));
+  if (shadowed.length) onShadowed?.(shadowed);
   return [
     references.has("React") && !bindings.has("React") ? "import * as React from 'react';" : "",
     hooks.length ? `import { ${hooks.join(", ")} } from 'react';` : "",
     ...implicitComponents,
+    registryNames.length ? builtinRegistryBindings(registryNames, identifierNames(source)) : "",
     usesMintlifyComponents ? mintlifyComponentsShim() : ""
   ].filter(Boolean).join("\n");
 }
 function resolveInlineBuiltinReferences(source, moduleNames) {
   const unresolved = unboundTags(source, moduleNames);
   if (unresolved.length === 0) return source;
+  return [builtinRegistryBindings(unresolved, identifierNames(sourceFile(source, "inline.jsx"))), source].join("\n");
+}
+function identifierNames(root) {
+  const names = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if (ts2.isIdentifier(node)) names.add(node.text);
+    ts2.forEachChild(node, visit);
+  };
+  visit(root);
+  return names;
+}
+function builtinRegistryBindings(names, used) {
+  const registry = "builtinMdxComponents";
+  let alias = registry;
+  for (let suffix = 2; used.has(alias); suffix++) alias = `${registry}${suffix}`;
   return [
-    "import { builtinMdxComponents } from '@/components/mdx/builtin-components';",
-    `const { ${unresolved.join(", ")} } = builtinMdxComponents;`,
-    source
+    `import { ${alias === registry ? registry : `${registry} as ${alias}`} } from '@/components/mdx/builtin-components';`,
+    `const { ${names.join(", ")} } = ${alias};`
   ].join("\n");
 }
+function shadowedBuiltinMessage(file, names) {
+  const tags = names.map((name) => `<${name}>`).join(", ");
+  return `${file} renders ${tags} as a Thally built-in component but also uses the JavaScript global of the same name, so the tag was left unbound. Rename the component or the global use in the source.`;
+}
 function imports(statement) {
   if (!ts2.isStringLiteral(statement.moduleSpecifier) || !statement.importClause) return [];
   const clause = statement.importClause;
@@ -3269,6 +3344,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
   function copyGraph(entry) {
     const staged = /* @__PURE__ */ new Map();
     const stagedWarnings = [];
+    const stagedShadowed = [];
     const modules = /* @__PURE__ */ new Map();
     let stagedBytes = 0;
     function stageShim(filename, content) {
@@ -3373,7 +3449,8 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
           const prologue = `// @ts-nocheck
 ${client ? "'use client';\n" : ""}
 `;
-          return shebangMatch ? shebangMatch[0] + prologue + implicitReactImports(ast) + "\n" + replaced.slice(shebangMatch[0].length) : prologue + implicitReactImports(ast) + "\n" + replaced;
+          const implicit = implicitReactImports(ast, (names) => stagedShadowed.push({ path, names }));
+          return shebangMatch ? shebangMatch[0] + prologue + implicit + "\n" + replaced.slice(shebangMatch[0].length) : prologue + implicit + "\n" + replaced;
         }
       });
     }
@@ -3391,6 +3468,7 @@ ${client ? "'use client';\n" : ""}
     }
     for (const [path, module] of modules) staged.set(path, { path, content: module.render(clientModules.has(path)) });
     for (const [path, file] of staged) copied.set(path, file);
+    for (const { path, names } of stagedShadowed) warn(shadowedBuiltinMessage(relative2(root, path).replace(/\\/g, "/"), names), path);
     for (const { path, omitted } of stagedWarnings) {
       warn(`Site-authored CSS module ${relative2(root, path).replace(/\\/g, "/")} has ${omitted} global-only selector branch(es) that cannot be copied into Thally CSS Modules; those styles were omitted.`, path);
     }
@@ -3845,8 +3923,12 @@ ${inlineSource}` });
 }`),
         ""
       ].join("\n");
+      const implicit = implicitReactImports(
+        sourceFile(inlineSource, "inline.jsx"),
+        (names) => warn(shadowedBuiltinMessage(relative2(root, currentFile).replace(/\\/g, "/"), names), currentFile)
+      );
       copied.set(path, { path, content: `'use client';
-${implicitReactImports(sourceFile(inlineSource, "inline.jsx"))}
+${implicit}
 ${inlineSource}` });
       copiedBytes += Buffer.byteLength(inlineSource);
       for (const { node, name } of extracted) {
@@ -4238,24 +4320,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 +4368,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 +4391,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 +4522,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 +4549,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 } : {}
         });
       }
     }
@@ -7177,8 +7278,49 @@ function splitOpenApiRef(raw) {
   const specRef = match[1] ? unquote(match[1]) : void 0;
   return { ...specRef ? { specRef } : {}, operation: match[2] };
 }
+function canonicalSpecRef(specRef) {
+  return specRef.trim().split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^(?:\.?\/+)+/, "");
+}
+function isRemoteSpecRef(specRef) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(specRef);
+}
 function specRefBaseName(specRef) {
-  return specRef.trim().replace(/\\/g, "/").split(/[?#]/, 1)[0].split("/").filter(Boolean).pop()?.toLowerCase() ?? "";
+  return canonicalSpecRef(specRef).split("/").filter(Boolean).pop()?.toLowerCase() ?? "";
+}
+function withoutSpecExtension(value) {
+  return value.replace(/\.(?:json|ya?ml)$/i, "");
+}
+function resolveSpecRef(specRef, candidates, anyFolder = true) {
+  const key = canonicalSpecRef(specRef);
+  const byId = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    const id = candidate.sourcePath ?? candidate.filename;
+    if (!byId.has(id)) byId.set(id, candidate);
+  }
+  const unique = [...byId.values()];
+  const exact = unique.find((candidate) => candidate.sourcePath === key);
+  if (exact) return { kind: "match", spec: exact };
+  if (!anyFolder && key.includes("/")) return { kind: "none" };
+  const name = specRefBaseName(key);
+  const names = unique.map((candidate) => specRefBaseName(candidate.sourcePath ?? candidate.filename));
+  for (const fits of [unique.filter((_, index) => names[index] === name), unique.filter((_, index) => withoutSpecExtension(names[index]) === name)]) {
+    if (fits.length === 1) return { kind: "match", spec: fits[0] };
+    if (fits.length > 1) return { kind: "ambiguous", candidates: fits };
+  }
+  return { kind: "none" };
+}
+function localSpecRef(openapi) {
+  const specRef = openapi ? splitOpenApiRef(openapi)?.specRef : void 0;
+  return specRef && !isRemoteSpecRef(specRef) ? specRef : void 0;
+}
+function specNamedByPage(openapi, specs) {
+  const specRef = localSpecRef(openapi);
+  const resolved = specRef ? resolveSpecRef(specRef, specs) : void 0;
+  return resolved?.kind === "match" ? resolved.spec : void 0;
+}
+function namesSeveralSpecs(openapi, specs) {
+  const specRef = localSpecRef(openapi);
+  return Boolean(specRef) && resolveSpecRef(specRef, specs).kind === "ambiguous";
 }
 function withSpecRef(ref, specRef) {
   return `${specRef} ${ref.operation}`;
@@ -7186,36 +7328,71 @@ function withSpecRef(ref, specRef) {
 
 // src/spec-exclude.ts
 import { parse as parseYaml4, stringify as stringifyYaml } from "yaml";
-function specRefMatches(ref, specPath, specFilename, isDefault) {
-  const prefix = /^(?:(\S+)\s+)?(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|WEBHOOK)\s/i.exec(`${ref} `)?.[1];
+function specRefMatches(ref, specPath, isDefault) {
+  const prefix = splitOpenApiRef(ref)?.specRef;
   if (!prefix) return isDefault;
-  const wanted = prefix.replace(/^\/+/, "").toLowerCase();
+  const wanted = (isRemoteSpecRef(prefix) ? prefix.trim() : canonicalSpecRef(prefix)).toLowerCase();
   const lowerPath = specPath.toLowerCase();
-  return lowerPath === wanted || lowerPath.endsWith(`/${wanted}`) || specFilename.toLowerCase() === wanted;
+  const stem = withoutSpecExtension(lowerPath);
+  return lowerPath === wanted || lowerPath.endsWith(`/${wanted}`) || stem === wanted || stem.endsWith(`/${wanted}`);
+}
+function resolvedSources(ref, specs) {
+  const specRef = splitOpenApiRef(ref)?.specRef;
+  if (!specRef || isRemoteSpecRef(specRef)) return { unique: false, sources: [] };
+  const resolved = resolveSpecRef(specRef, specs);
+  if (resolved.kind === "match") return { unique: true, sources: [resolved.spec.sourcePath] };
+  return { unique: false, sources: resolved.kind === "ambiguous" ? resolved.candidates.map((candidate) => candidate.sourcePath) : [] };
+}
+function refWithholdsFrom(ref, spec, specs) {
+  const { unique, sources } = resolvedSources(ref, specs);
+  return unique ? sources[0] === spec.sourcePath : specRefMatches(ref, spec.sourcePath, true) || sources.includes(spec.sourcePath);
+}
+function refKeepsIn(ref, spec, specs) {
+  const specRef = splitOpenApiRef(ref)?.specRef;
+  if (!specRef) return false;
+  if (isRemoteSpecRef(specRef)) return specRefMatches(ref, spec.sourcePath, false);
+  const { unique, sources } = resolvedSources(ref, specs);
+  return unique && sources[0] === spec.sourcePath;
 }
 function operationKey(operation) {
   const [first, ...rest] = operation.trim().split(/\s+/);
   return `${first.toLowerCase()} ${rest.join(" ")}`;
 }
-function keysFor(spec, refs) {
+function keysFor(refs, names) {
   return [...new Set(
-    refs.filter((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true)).map((ref) => splitOpenApiRef(ref)?.operation).filter((op) => !!op).map(operationKey)
+    refs.filter(names).map((ref) => splitOpenApiRef(ref)?.operation).filter((op) => !!op).map(operationKey)
   )];
 }
-function withheldOperationKeys(spec, withheldRefs, keptRefs) {
-  const kept = keysFor(spec, keptRefs);
-  return { withheld: keysFor(spec, withheldRefs).filter((key) => !kept.includes(key)), kept };
+function withheldOperationKeys(spec, withheldRefs, keptRefs, specs = [spec]) {
+  const kept = keysFor(keptRefs, (ref) => refKeepsIn(ref, spec, specs));
+  return { withheld: keysFor(withheldRefs, (ref) => refWithholdsFrom(ref, spec, specs)).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 +7415,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 +7646,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 +8764,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 +9012,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 +9576,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",
@@ -10294,22 +10616,56 @@ function normalizedReferenceKey(value) {
 function exactReferenceKey(value) {
   return value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/").replace(/\.(?:mdx?|rst|txt)$/i, "");
 }
-function navigationOperationRefs(config) {
-  const refs = [];
-  const visit = (node) => {
+function containerSpec(node) {
+  const value = node.openapi;
+  if (value === void 0) return void 0;
+  const source = value && typeof value === "object" && !Array.isArray(value) ? value.source : value;
+  return typeof source === "string" && source.trim() && !splitOpenApiRef(source) ? source.trim() : null;
+}
+function navigationSpecContext(config, pageIdentity) {
+  const context = { operations: [], pageOwners: /* @__PURE__ */ new Map(), pageIdentity };
+  const visit = (node, owner, listed) => {
     if (typeof node === "string") {
-      if (splitOpenApiRef(node)) refs.push(node);
-    } else if (Array.isArray(node)) node.forEach(visit);
+      if (splitOpenApiRef(node)) context.operations.push({ ref: node, owner });
+      else if (listed) {
+        const page = pageIdentity(node);
+        if (page !== null) context.pageOwners.set(page, (context.pageOwners.get(page) ?? /* @__PURE__ */ new Set()).add(owner));
+      }
+    } else if (Array.isArray(node)) node.forEach((child) => visit(child, owner, true));
     else if (node && typeof node === "object") {
       if (navigationGateReason(node)) return;
-      Object.values(node).forEach(visit);
-    }
-  };
-  visit(config?.navigation);
-  return refs;
-}
-function excludeWithheldOperations(spec, withheldRefs, keptRefs) {
-  const { withheld, kept } = withheldOperationKeys(spec, withheldRefs, keptRefs);
+      const own2 = containerSpec(node);
+      Object.values(node).forEach((child) => visit(child, own2 === void 0 ? owner : own2, false));
+    }
+  };
+  visit(config?.navigation, void 0, false);
+  return context;
+}
+function keptOperationRefs(published, navigation, defaultSpec, specs) {
+  const kept = [];
+  const unowned = [];
+  const source = (owner) => {
+    if (!owner || isRemoteSpecRef(owner)) return owner;
+    const resolved = resolveSpecRef(owner, specs);
+    return resolved.kind === "match" ? resolved.spec.sourcePath ?? resolved.spec.filename : owner;
+  };
+  const add = (raw, owner) => {
+    const ref = splitOpenApiRef(raw);
+    if (!ref) return;
+    if (ref.specRef) kept.push(raw);
+    else if (owner) kept.push(withSpecRef(ref, owner));
+    else unowned.push(ref.operation);
+  };
+  for (const { ref, file } of published) {
+    const page = navigation.pageIdentity(file);
+    const owners = new Set([...(page === null ? void 0 : navigation.pageOwners.get(page)) ?? [void 0]].map((owner) => source(owner === void 0 ? defaultSpec : owner)));
+    add(ref, owners.size === 1 ? [...owners][0] : null);
+  }
+  for (const { ref, owner } of navigation.operations) add(ref, source(owner === void 0 ? defaultSpec : owner));
+  return { kept, unowned };
+}
+function excludeWithheldOperations(spec, withheldRefs, keptRefs, specs) {
+  const { withheld, kept } = withheldOperationKeys(spec, withheldRefs, keptRefs, specs);
   return markExcluded(spec.content, withheld, kept);
 }
 var TOKEN_SEPARATORS = /[\s"'()<>[\]{}=,;:|\\/`*!?#&]+/;
@@ -10402,7 +10758,7 @@ function readSpecFile(absolutePath, relativePath, warnings) {
     });
     return void 0;
   }
-  return readFileSync6(absolutePath);
+  return withoutByteOrderMark(readFileSync6(absolutePath));
 }
 function specAssetPath(filename) {
   return `${SPEC_DIRECTORY}/${filename}`;
@@ -10410,6 +10766,23 @@ function specAssetPath(filename) {
 function specAsset(filename, content) {
   return { path: specAssetPath(filename), content, projectRelative: true };
 }
+function createSpecAssetNamer() {
+  const nameBySource = /* @__PURE__ */ new Map();
+  const sourceByName = /* @__PURE__ */ new Map();
+  return ({ sourcePath, filename, tabLabel }) => {
+    let name = nameBySource.get(sourcePath);
+    if (name === void 0) {
+      name = filename;
+      if (sourceByName.has(name.toLowerCase())) {
+        name = sourcePath.replace(/\//g, "-");
+        while (sourceByName.has(name.toLowerCase())) name = `${(tabLabel ?? "default").replace(/\W+/g, "-")}-${name}`;
+      }
+      nameBySource.set(sourcePath, name);
+      sourceByName.set(name.toLowerCase(), sourcePath);
+    }
+    return name;
+  };
+}
 function mintlifyTopLevelApiReferences(config) {
   const api = config?.api && typeof config.api === "object" && !Array.isArray(config.api) ? config.api : null;
   if (!api) return [];
@@ -10421,27 +10794,49 @@ function mintlifyTopLevelApiReferences(config) {
   }
   return references;
 }
-function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, pages = []) {
+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 = []) {
   if (!mintlifyConfig) return [];
   const references = [
     ...mintlifyTopLevelApiReferences(mintlifyConfig),
     ...mintlifyNavigationApiReferences(mintlifyConfig)
   ];
-  const specKey = (value) => value.split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^(?:\.\/)+/, "").replace(/^\/+/, "");
-  const known = new Set(references.map((reference) => specKey(reference.value)));
+  const known = new Set(references.map((reference) => canonicalSpecRef(reference.value)));
+  const specFiles = specFileCandidates(files);
+  const namedFiles = /* @__PURE__ */ new Map();
   for (const page of pages) {
     const specRef = page.openapi ? splitOpenApiRef(page.openapi)?.specRef : void 0;
     if (!specRef || /^[a-z][a-z0-9+.-]*:/i.test(specRef)) continue;
-    const key = specKey(specRef);
-    if (known.has(key) || !files.some((file) => file.relativePath === key)) continue;
+    const named = namedFiles.get(specRef) ?? resolveSpecRef(specRef, specFiles, false);
+    namedFiles.set(specRef, named);
+    const key = named.kind === "match" ? named.spec.sourcePath : "";
+    if (!key || known.has(key)) continue;
     known.add(key);
     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 +10847,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.`,
@@ -10464,7 +10862,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
       warnings.push({ code: "unsupported-config", message: `The OpenAPI spec "${reference.value}"${tabSuffix} uses insecure HTTP and was not imported.`, source: reference.value });
       continue;
     }
-    const key = reference.value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/");
+    const key = canonicalSpecRef(reference.value);
     const match = files.find((file) => file.relativePath === key);
     if (!match) {
       warnings.push({
@@ -10493,21 +10891,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
       directory: reference.directory
     });
   }
-  const filenameOwners = /* @__PURE__ */ new Map();
-  const filenameSources = /* @__PURE__ */ new Map();
-  for (const spec of specs) {
-    const groupKey = spec.tabLabel ?? "\0default";
-    const owner = filenameOwners.get(spec.filename);
-    if (owner !== void 0 && owner !== groupKey && filenameSources.get(spec.filename) !== spec.sourcePath) {
-      let disambiguated = spec.sourcePath.replace(/\//g, "-");
-      while (filenameOwners.has(disambiguated) && filenameOwners.get(disambiguated) !== groupKey) {
-        disambiguated = `${groupKey.replace(/\W+/g, "-")}-${disambiguated}`;
-      }
-      spec.filename = disambiguated;
-    }
-    filenameOwners.set(spec.filename, groupKey);
-    filenameSources.set(spec.filename, spec.sourcePath);
-  }
+  for (const spec of specs) spec.filename = nameSpec(spec);
   return specs;
 }
 function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings, explainMissing = () => "no such file was found") {
@@ -10520,12 +10904,13 @@ function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings, explain
       }
       continue;
     }
-    const key = ref.specRef.split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^(?:\.\/)+/, "").replace(/^\/+/, "");
-    const byPath = specs.find((spec) => spec.sourcePath === key);
-    const byName = specs.filter((spec) => spec.filename.toLowerCase() === specRefBaseName(key));
-    const match = byPath ?? (byName.length === 1 ? byName[0] : void 0);
-    if (match) {
-      page.openapi = withSpecRef(ref, specAssetPath(match.filename));
+    const key = canonicalSpecRef(ref.specRef);
+    const resolved = resolveSpecRef(ref.specRef, specs);
+    if (resolved.kind === "match") {
+      page.openapi = withSpecRef(ref, specAssetPath(resolved.spec.filename));
+    } else if (resolved.kind === "ambiguous") {
+      const candidates = resolved.candidates.map((spec) => spec.sourcePath ?? spec.filename).join(", ");
+      warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the OpenAPI spec "${ref.specRef}", which fits more than one spec (${candidates}), so it was left as written and the page will not render an endpoint. Write the full path of the spec in the page's openapi frontmatter.`, source: page.source });
     } else {
       warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the OpenAPI spec "${ref.specRef}", which was not migrated (${explainMissing(key)}); the page will not render an endpoint.`, source: page.source });
     }
@@ -10552,10 +10937,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 +10954,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 +10973,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 +11021,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 +11089,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 +11103,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) {
@@ -11789,9 +12241,12 @@ function injectOpenApiSpecs(config, specs, warnings) {
     const apiTab = spec.tabLabel ? tabs.find((tab) => tab.tab === spec.tabLabel) : tabs.find((tab) => tab.tab.toLowerCase().includes("api"));
     if (apiTab) {
       if (apiTab.api && warnings) {
+        const source = specAssetPath(spec.filename);
+        const pageBound = spec.pageReferenced && !tabs.some((tab) => tab.api?.source === source);
+        if (pageBound) insertApiTab(tabs, { tab: `OpenAPI: ${spec.sourcePath ?? spec.filename}`, hidden: true, api: { source } });
         warnings.push({
           code: "unsupported-config",
-          message: `Tab "${apiTab.tab}" already uses another OpenAPI spec, and Thally supports one API spec per tab, so "${specAssetPath(spec.filename)}" was not added. Put it in its own tab to include it.`
+          message: `Tab "${apiTab.tab}" already uses another OpenAPI spec, and Thally supports one API spec per tab, so "${source}" ${pageBound ? "gets no endpoint list of its own; the pages that name it still show their endpoint. Put it in its own tab to list all its endpoints." : "was not added. Put it in its own tab to include it."}`
         });
         continue;
       }
@@ -12028,6 +12483,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);
@@ -12049,6 +12505,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
   const gateByPath = /* @__PURE__ */ new Map();
   const withheldSpecRefs = [];
   const publishedSpecRefs = [];
+  const publishedSpecPages = [];
   const withheldPaths = /* @__PURE__ */ new Set();
   const isDocFile = (file) => [".md", ".mdx"].includes(extname6(file.relativePath).toLowerCase());
   const isGateCandidate = (file) => isDocFile(file) && !file.relativePath.split("/").some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase()));
@@ -12085,6 +12542,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       const verdict = classifyPageGate(file);
       gateByPath.set(file.absolutePath, verdict);
       if (verdict.openapi) (verdict.reason ? withheldSpecRefs : publishedSpecRefs).push(verdict.openapi);
+      if (verdict.openapi && !verdict.reason) publishedSpecPages.push({ ref: verdict.openapi, file: file.relativePath });
       if (verdict.reason) withheldPaths.add(file.absolutePath);
     }
     for (const file of mintignoreFilteredFiles) {
@@ -12188,6 +12646,23 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
   let discovered = files.length;
   const localeConfig = docsConfig.i18n;
   const defaultPageIds = new Set([...referenceMap.values()].filter((reference) => !reference.locale || reference.locale === localeConfig?.defaultLocale).map((reference) => reference.navigationId));
+  const resolvePageIdentity = (path) => {
+    const referenced = exactReferenceMap.get(exactReferenceKey(path)) ?? referenceMap.get(normalizedReferenceKey(path));
+    let locale = referenced?.locale;
+    let navigationId = referenced?.navigationId ?? pageIdFromReference(path, platform === "mintlify");
+    if (!referenced && localeConfig) {
+      for (const entry of localeConfig.locales) {
+        const localized = mintlifyLocalizedReference(path, entry.code, defaultPageIds);
+        if (localized === path) continue;
+        locale = entry.code;
+        navigationId = pageIdFromReference(localized, platform === "mintlify");
+        break;
+      }
+    }
+    if (!navigationId) return null;
+    const isDefaultLocale = !locale || locale === localeConfig?.defaultLocale;
+    return { locale, navigationId, id: isDefaultLocale ? navigationId : `${locale}/${navigationId}` };
+  };
   const routeAliases = [];
   const pageFiles = [...files].sort((left, right) => {
     const leftOrder = referenceOrder.get(normalizedReferenceKey(left.relativePath)) ?? Number.MAX_SAFE_INTEGER;
@@ -12283,7 +12758,6 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       }
       continue;
     }
-    const key = normalizedReferenceKey(file.relativePath);
     let pageGate;
     {
       pageGate = gateByPath.get(file.absolutePath);
@@ -12333,25 +12807,13 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       }
     }
     const isRestrictedPage = Boolean(pageGate?.reason);
-    const referenced = exactReferenceMap.get(exactReferenceKey(file.relativePath)) ?? referenceMap.get(key);
-    let locale = referenced?.locale;
-    let navigationId = referenced?.navigationId ?? pageIdFromReference(file.relativePath, platform === "mintlify");
-    if (!referenced && localeConfig) {
-      for (const entry of localeConfig.locales) {
-        const localized = mintlifyLocalizedReference(file.relativePath, entry.code, defaultPageIds);
-        if (localized === file.relativePath) continue;
-        locale = entry.code;
-        navigationId = pageIdFromReference(localized, platform === "mintlify");
-        break;
-      }
-    }
-    if (!navigationId) {
+    const identity = resolvePageIdentity(file.relativePath);
+    if (!identity) {
       skipped++;
       warnings.push({ code: "invalid-page", message: "Page path could not be normalized safely.", source: file.relativePath });
       continue;
     }
-    const isDefaultLocale = !locale || locale === localeConfig?.defaultLocale;
-    const id = isDefaultLocale ? navigationId : `${locale}/${navigationId}`;
+    const { locale, navigationId, id } = identity;
     let raw = inlineMdxSnippets(
       mintlifyProjectRoot ? importUndeclaredSnippetComponents(readFileSync6(file.absolutePath, "utf8"), file.absolutePath, repositoryDir, mintlifyProjectRoot, snippetExports, snippetAliases, inlineGate, warnings) : injectDocusaurusGlobalImports(readFileSync6(file.absolutePath, "utf8"), globalDocusaurusImports),
       file.absolutePath,
@@ -12994,14 +13456,27 @@ ${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 = []) => {
       warnings.push({ code: "gated-page", message: sharedSpecMessage(path, excluded), source: path });
     };
-    const keptSpecRefs = [...publishedSpecRefs, ...navigationOperationRefs(mintlifyConfig)];
-    const allSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs, pages.filter((page) => !restrictedPages.has(page)));
+    const nameSpec = createSpecAssetNamer();
+    const allSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs, nameSpec, pages.filter((page) => !restrictedPages.has(page)));
+    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),
+      ...remoteApiSpecs.filter((spec) => spec.tabLabel === void 0).map((spec) => spec.url)
+    ]);
+    const keptOperations = (fallbackSource) => {
+      const defaultSpec = defaultSources.size === 0 ? fallbackSource : defaultSources.size === 1 ? [...defaultSources][0] : void 0;
+      const candidates = fallbackSource ? [{ sourcePath: fallbackSource, filename: basename3(fallbackSource) }, ...allSpecs] : allSpecs;
+      const { kept, unowned } = keptOperationRefs(publishedSpecPages, navigation, defaultSpec, candidates);
+      return { kept: kept.filter((ref) => !namesSeveralSpecs(ref, allSpecs)), unowned };
+    };
+    let { kept: keptSpecRefs, unowned: unownedOperations } = keptOperations();
+    const withheldKeys = /* @__PURE__ */ new Set();
     for (const remote of remoteApiSpecs) {
       const { withheld, kept } = withheldOperationKeys({ sourcePath: remote.url, filename: remote.url }, withheldSpecRefs, keptSpecRefs);
       if (withheld.length > 0) {
@@ -13011,9 +13486,10 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
     }
     const withheldOperations = /* @__PURE__ */ new Map();
     for (const spec of allSpecs) {
-      const result = excludeWithheldOperations(spec, withheldSpecRefs, keptSpecRefs);
+      const result = excludeWithheldOperations(spec, withheldSpecRefs, keptSpecRefs, allSpecs);
       spec.content = result.content;
       withheldOperations.set(spec, result.excluded);
+      result.excluded.forEach((operation) => withheldKeys.add(operationKey(operation)));
     }
     const resolvedSpecs = allSpecs.filter((spec) => !spec.pageOnly);
     const pageOnlySpecs = allSpecs.filter((spec) => spec.pageOnly);
@@ -13021,53 +13497,41 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       if (!assets.some((asset) => asset.path === specAssetPath(spec.filename))) {
         assets.push(specAsset(spec.filename, spec.content));
       }
-      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
+      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
     }
     let pageSpecs = resolvedSpecs;
     if (resolvedSpecs.length > 0) {
+      const namedByPages = new Set(pages.filter((page) => !restrictedPages.has(page)).map((page) => specNamedByPage(page.openapi, resolvedSpecs)));
       for (const spec of resolvedSpecs) {
-        spec.generatedNavigation = Boolean(spec.directory) && !publishedSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true));
+        spec.pageReferenced = namedByPages.has(spec);
+        spec.generatedNavigation = Boolean(spec.directory) && !publishedSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, 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;
       if (fallback && fallbackContent) {
-        const filename = basename3(fallback.relativePath);
-        const matches = (ref) => specRefMatches(ref, fallback.relativePath, filename, true);
+        const matches = (ref) => specRefMatches(ref, fallback.relativePath, true);
         if (withheldSpecRefs.some(matches) && !publishedSpecRefs.some(matches)) {
-          quarantinedFiles.push({ path: `${QUARANTINE_DIRECTORY}/assets/${specAssetPath(filename)}`, content: fallbackContent });
+          quarantinedFiles.push({ path: `${QUARANTINE_DIRECTORY}/assets/${specAssetPath(basename3(fallback.relativePath))}`, content: fallbackContent });
           withheldAssetCount++;
         } else {
-          const pruned = excludeWithheldOperations({ sourcePath: fallback.relativePath, filename, content: fallbackContent }, withheldSpecRefs, keptSpecRefs);
+          const filename = nameSpec({ sourcePath: fallback.relativePath, filename: basename3(fallback.relativePath) });
+          const fallbackSpec = { sourcePath: fallback.relativePath, filename, content: fallbackContent };
+          ({ kept: keptSpecRefs, unowned: unownedOperations } = keptOperations(fallback.relativePath));
+          const pruned = excludeWithheldOperations(fallbackSpec, withheldSpecRefs, keptSpecRefs, [fallbackSpec, ...allSpecs]);
+          pruned.excluded.forEach((operation) => withheldKeys.add(operationKey(operation)));
           if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
             assets.push(specAsset(filename, pruned.content));
           }
@@ -13079,13 +13543,22 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
     }
     for (const spec of pageOnlySpecs) {
       if (!assets.some((asset) => asset.path === specAssetPath(spec.filename))) assets.push(specAsset(spec.filename, spec.content));
-      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
+      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
     }
     if (pageOnlySpecs.length > 0) {
       docsConfig = injectOpenApiSpecs(docsConfig, pageOnlySpecs, warnings);
       pageSpecs = [...pageSpecs, ...pageOnlySpecs];
     }
+    const notKeptPublic = [...new Set(unownedOperations.filter((operation) => withheldKeys.has(operationKey(operation))))];
+    if (notKeptPublic.length > 0) {
+      warnings.push({
+        code: "gated-page",
+        message: `${notKeptPublic.length} operation(s) withheld from a published OpenAPI spec (${notKeptPublic.join(", ")}) are also named by a published page or navigation entry that does not say which spec it means, so that reference did not keep them public. Write the spec in its openapi value (for example "openapi.json GET /x") to publish the operation.`
+      });
+    }
     const explainMissingSpec = (key) => {
+      const fits = resolveSpecRef(key, specFileCandidates(files), false);
+      if (fits.kind === "ambiguous") return `several spec files fit that name (${fits.candidates.map((spec) => spec.sourcePath).join(", ")}); write the full path in the page's openapi frontmatter`;
       const sameName = scannedFiles.find((file) => file.relativePath.toLowerCase() === key.toLowerCase());
       if (sameName && sameName.relativePath !== key) return `paths are case-sensitive; the file is at "${sameName.relativePath}"`;
       if (sameName && mintignoreMatcher?.ignores(sameName.relativePath)) return "the file is excluded by .mintignore";
@@ -13099,8 +13572,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 +13788,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);
@@ -13443,10 +13898,10 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
   const sourceFavicon = mintlifyConfig?.favicon ?? fernRawConfig?.favicon ?? docusaurusSettings?.favicon;
   const logo = brandVariants(sourceLogo);
   const favicon = brandVariants(sourceFavicon);
-  const logoLight = publicBrandPath(logo.light);
   const logoDark = publicBrandPath(logo.dark);
-  const faviconLight = publicBrandPath(favicon.light);
+  const logoLight = publicBrandPath(logo.light) ?? logoDark;
   const faviconDark = publicBrandPath(favicon.dark);
+  const faviconLight = publicBrandPath(favicon.light) ?? faviconDark;
   if (logoLight) docsConfig = {
     ...docsConfig,
     navbar: {
@@ -13475,15 +13930,30 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
       const decoration = background.decoration;
       const image = publicBrandPath(background.image);
       const imageDark = publicBrandPath(background.imageDark);
-      docsConfig = {
-        ...docsConfig,
-        background: {
-          ...docsConfig.background,
-          ...decoration === "none" || decoration === "grid" || decoration === "gradient" ? { decoration } : {},
-          ...image ? { image } : {},
-          ...imageDark ? { imageDark } : {}
-        }
+      const mapped = {
+        ...docsConfig.background,
+        ...decoration === "none" || decoration === "grid" || decoration === "gradient" ? { decoration } : {},
+        ...image ? { image } : {},
+        ...imageDark ? { imageDark } : {}
       };
+      if (Object.keys(mapped).length > 0) docsConfig = { ...docsConfig, background: mapped };
+      const canvas = background.color && typeof background.color === "object" ? background.color : {};
+      for (const mode of ["light", "dark"]) {
+        if (canvas[mode] === void 0) continue;
+        const hex = typeof canvas[mode] === "string" ? cssColorToHex(canvas[mode]) : void 0;
+        if (!hex) {
+          warnings.push({
+            code: "unsupported-config",
+            message: `background.color.${mode} ${JSON.stringify(canvas[mode])?.slice(0, 40)} is not a hex or rgb() colour (for example #121317) and was dropped, so that mode keeps Thally's default canvas. Use a hex value in docs.json to set it.`,
+            source: "docs.json"
+          });
+          continue;
+        }
+        docsConfig = {
+          ...docsConfig,
+          colors: { ...docsConfig.colors, [mode]: { ...docsConfig.colors?.[mode], background: hex } }
+        };
+      }
     }
   }
   if (platform === "docusaurus") {
@@ -13493,13 +13963,23 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     ...docsConfig,
     favicon: { light: faviconLight, ...faviconDark ? { dark: faviconDark } : {} }
   };
-  const missingBrand = [
-    ...[logo.light, logo.dark].filter((value) => typeof value === "string" && !publicBrandPath(value)),
-    ...[favicon.light, favicon.dark].filter((value) => typeof value === "string" && !publicBrandPath(value))
-  ];
+  const notImported = (variants) => [variants.light, variants.dark].filter((value) => typeof value === "string" && !publicBrandPath(value));
+  const missingLogo = notImported(logo);
+  const missingFavicon = notImported(favicon);
+  const missingBrand = [...missingLogo, ...missingFavicon];
+  const substituted = [
+    ...missingLogo.length > 0 && logoLight ? [`logo (${logoLight})`] : [],
+    ...missingFavicon.length > 0 && faviconLight ? [`favicon (${faviconLight})`] : []
+  ].map((asset) => ` The imported ${asset} is used for both light and dark mode.`).join("");
   if (missingBrand.length > 0) warnings.push({
     code: "unsupported-config",
-    message: `Brand asset(s) were referenced but not imported: ${[...new Set(missingBrand)].join(", ")}. Add these files under public/ or update docs.json.`
+    message: `Brand asset(s) were referenced but not imported: ${[...new Set(missingBrand)].join(", ")}. Add these files under public/ or update docs.json.${substituted}`
+  });
+  const logoHref = sourceLogo && typeof sourceLogo === "object" ? sourceLogo.href : void 0;
+  if (typeof logoHref === "string" && logoHref.trim() && logoHref.trim() !== "/") warnings.push({
+    code: "unsupported-config",
+    message: `logo.href ${JSON.stringify(logoHref.trim().slice(0, 120))} was dropped: the header logo always links to the docs home page. Add it as a navbar link in docs.json if readers need it.`,
+    source: mintlifyConfig ? "docs.json" : "docs.yml"
   });
   if (platform === "mintlify") {
     docsConfig = { ...docsConfig, markdown: { enabled: true } };
@@ -13532,7 +14012,7 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     message: `Fern global theme ${JSON.stringify(fernRawConfig["global-theme"])} could not be fetched during local migration; local overrides and Thally default styling tokens were applied.`,
     source: "global-theme"
   });
-  if (fernRawConfig?.logo && !fernRawConfig["global-theme"] && !logoLight && !logo.light) warnings.push({
+  if (fernRawConfig?.logo && !fernRawConfig["global-theme"] && !logoLight && !logo.light && !logo.dark) warnings.push({
     code: "unsupported-config",
     message: "Fern supplied a logo through its global theme without a local asset; add a logo path to docs.json after import."
   });
@@ -13546,6 +14026,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 } : {},
@@ -15314,7 +15795,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) {
@@ -15408,9 +15888,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)) {
@@ -15423,10 +15901,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(),
@@ -15441,9 +15920,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;
@@ -15453,28 +15931,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}`);
@@ -15482,21 +15964,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",
@@ -15505,11 +15973,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
   };
 }