@thallylabs/migrate 0.2.33 → 0.2.35

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;
 }
@@ -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) {
@@ -4442,39 +4524,106 @@ function specSource(value) {
 }
 function listedOperations(container) {
   const operations = [];
-  const visit = (entry, root) => {
+  const visit = (entry, depth) => {
     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;
+    if (!object2 || depth > SWEEP_DEPTH_LIMIT || depth > 0 && (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));
+      if (Array.isArray(object2[key])) object2[key].forEach((child) => visit(child, depth + 1));
     }
   };
-  visit(container, true);
+  visit(container, 0);
   return operations;
 }
+var bindsSpec = (node) => Boolean(specSource(node.openapi) || specSource(node.asyncapi));
+var hasGroupShape = (node) => "group" in node || Array.isArray(node.pages);
+var API_GROUPS_MAX_DEPTH = 32;
+var operationKey = (entry) => entry.trim().replace(/^(\S+)\s+/, "$1 ");
+function operationGroups(container, maxLevel = API_GROUPS_MAX_DEPTH) {
+  const entries = (node, level) => ["groups", "pages"].flatMap((key) => (Array.isArray(node[key]) ? node[key] : []).flatMap((entry) => {
+    if (typeof entry === "string") return OPENAPI_OPERATION_REF.test(entry) ? [operationKey(entry)] : [];
+    const object2 = objectValue2(entry);
+    const group = object2 && !bindsSpec(object2) ? groupOf(object2, level + 1) : void 0;
+    return group ? [group] : [];
+  }));
+  const groupOf = (node, level) => {
+    if (level > maxLevel || node.hidden === true || navigationGateReason(node)) return void 0;
+    if (!hasGroupShape(node)) return void 0;
+    const pages = entries(node, level);
+    const icon = iconName(node.icon);
+    return pages.length > 0 ? { group: labelFor(node, "Documentation"), ...icon ? { icon } : {}, pages } : void 0;
+  };
+  if (typeof container.group === "string") {
+    const group = groupOf(container, 1);
+    return group ? [group] : [];
+  }
+  const label = labelFor(container, "API reference");
+  const groups = [];
+  let run;
+  for (const entry of entries(container, 0)) {
+    if (typeof entry !== "string") {
+      groups.push(entry);
+      run = void 0;
+    } else if (run) {
+      run.push(entry);
+    } else {
+      run = [entry];
+      groups.push({ group: label, pages: run });
+    }
+  }
+  return groups;
+}
+var groupOperationKeys = (groups) => groups.flatMap(({ pages }) => pages.flatMap((page) => typeof page === "string" ? [page] : groupOperationKeys([page])));
+function mergeApiGroups(existing, incoming) {
+  const identity = (key) => key.replace(/^(\S+)/, (method) => method.toLowerCase());
+  const seen = new Set(groupOperationKeys(existing ?? []).map(identity));
+  const unseen = (groups) => groups.flatMap((group) => {
+    const pages = group.pages.flatMap((page) => {
+      if (typeof page !== "string") return unseen([page]);
+      if (seen.has(identity(page))) return [];
+      seen.add(identity(page));
+      return [page];
+    });
+    return pages.length > 0 ? [{ ...group, pages }] : [];
+  });
+  const merged = [...existing ?? [], ...unseen(incoming ?? [])];
+  return merged.length > 0 ? merged : void 0;
+}
 var hasNavigationChildren = (node) => ["groups", "pages"].some((key) => Array.isArray(node[key]) && node[key].length > 0);
 function mintlifyNavigationApiReferences(config) {
   const navigation = objectValue2(config.navigation) ?? config;
   const references = [];
+  const defaultLanguage = pickDefaultLanguage(
+    (Array.isArray(navigation.languages) ? navigation.languages : []).flatMap((value) => {
+      const language = objectValue2(value);
+      return language && withLanguageCode(language) ? [language] : [];
+    })
+  );
   const containerKeys = ["tabs", "anchors", "products", "dropdowns", "versions", "menus", "languages"];
   const nestedKeys = ["groups", "pages"];
-  function collect(node, tabLabel, sibling) {
+  function collect(node, tabLabel, gated, otherLanguage, hidden, sibling) {
     for (const kind of ["openapi", "asyncapi"]) {
       const value = specSource(node[kind]);
       const directory = objectValue2(node[kind])?.directory;
       if (value) {
-        const operations = typeof directory === "string" && directory.trim() ? listedOperations(node) : [];
+        const listed = listedOperations(node);
+        const operations = typeof directory === "string" && directory.trim() ? listed : [];
+        const groups = gated || otherLanguage || hidden ? [] : operationGroups(node);
+        const tooDeepOnly = groups.length === 0 && listed.length > 0 && !gated && !hidden && groupOperationKeys(operationGroups(node, SWEEP_DEPTH_LIMIT)).length === listed.length;
+        const operationsWithheld = !otherLanguage && (hidden || groups.length === 0 && listed.length > 0 && !tooDeepOnly);
         references.push({
           value,
           kind,
           tabLabel,
           ...sibling,
           ...typeof directory === "string" && directory.trim() ? { directory: directory.trim() } : {},
-          ...operations.length > 0 ? { operations } : {}
+          ...operations.length > 0 ? { operations } : {},
+          ...groups.length > 0 ? { groups } : {},
+          ...operationsWithheld ? { operationsWithheld: true } : {},
+          ...otherLanguage ? { otherLanguage: true } : {}
         });
       }
     }
@@ -4486,7 +4635,7 @@ function mintlifyNavigationApiReferences(config) {
     siblingSources.set(candidate, source);
     return candidate;
   }
-  function visitChildren(rawNode, tabLabel) {
+  function visitChildren(rawNode, tabLabel, gated, otherLanguage, hidden) {
     const node = withFlattenedProductGroups(rawNode);
     for (const key of containerKeys) {
       const entries = node[key];
@@ -4494,7 +4643,7 @@ function mintlifyNavigationApiReferences(config) {
       for (const entry of entries) {
         const object2 = objectValue2(entry);
         if (!object2) continue;
-        visit(object2, labelFor(object2, tabLabel ?? "Documentation"));
+        visit(object2, labelFor(object2, tabLabel ?? "Documentation"), gated, otherLanguage || key === "languages" && rawNode === navigation && object2 !== defaultLanguage, hidden);
       }
     }
     for (const key of nestedKeys) {
@@ -4503,7 +4652,7 @@ function mintlifyNavigationApiReferences(config) {
       for (const entry of entries) {
         if (typeof entry === "string") continue;
         const object2 = objectValue2(entry);
-        if (object2) visit(object2, tabLabel);
+        if (object2) visit(object2, tabLabel, gated, otherLanguage, hidden || object2.hidden === true);
       }
     }
     if (Array.isArray(node.menu)) {
@@ -4515,24 +4664,26 @@ function mintlifyNavigationApiReferences(config) {
       const apiItems = items.filter((item) => specSource(item.openapi) || specSource(item.asyncapi));
       const soleContent = apiItems.length === 1 && !hasNavigationChildren(node) && !items.some(hasNavigationChildren);
       items.forEach((item, index) => {
-        if (soleContent && apiItems[0] === item) collect(item, tab);
+        const itemGated = gated || Boolean(navigationGateReason(item));
+        if (soleContent && apiItems[0] === item) collect(item, tab, itemGated, otherLanguage, hidden);
         else if (apiItems.includes(item)) {
           const label = uniqueSiblingLabel(
             `${tab}: ${labelFor(item, `Menu item ${index + 1}`)}`,
             `${specSource(item.openapi) ?? ""}|${specSource(item.asyncapi) ?? ""}`
           );
           const icon = iconName(item.icon);
-          collect(item, label, { parentTab: tab, ...icon ? { icon } : {}, ...item.hidden === true ? { hidden: true } : {} });
+          collect(item, label, itemGated, otherLanguage, hidden, { parentTab: tab, ...icon ? { icon } : {}, ...item.hidden === true ? { hidden: true } : {} });
         }
-        visitChildren(item, tabLabel);
+        visitChildren(item, tabLabel, itemGated, otherLanguage, hidden);
       });
     }
   }
-  function visit(node, tabLabel) {
-    collect(node, tabLabel);
-    visitChildren(node, tabLabel);
+  function visit(node, tabLabel, outerGated, otherLanguage, hidden) {
+    const gated = outerGated || Boolean(navigationGateReason(node));
+    collect(node, tabLabel, gated, otherLanguage, hidden);
+    visitChildren(node, tabLabel, gated, otherLanguage, hidden);
   }
-  visit(navigation, void 0);
+  visit(navigation, void 0, false, false, false);
   return references;
 }
 function insertApiTab(tabs, tab, parentTab) {
@@ -4555,6 +4706,17 @@ function normalizePageRef(value, pathPrefix = "") {
   ref = ref.replace(/\.(?:mdx?|rst|txt)$/i, "");
   return pageIdFromReference(ref, true);
 }
+var UNBOUND_OPERATIONS = { bound: false, gated: false, hidden: false, level: 0 };
+function descendOperationScope(scope, node, nested) {
+  const binds = bindsSpec(node);
+  return {
+    bound: !nested && scope.bound || binds,
+    gated: scope.gated || Boolean(navigationGateReason(node)),
+    hidden: scope.hidden || !nested && node.hidden === true,
+    // A container that binds a spec roots a tree of its own, where it is the first level when it is a group (as `operationGroups` reads it).
+    level: binds ? typeof node.group === "string" ? 1 : 0 : !nested && scope.bound && hasGroupShape(node) ? scope.level + 1 : scope.level
+  };
+}
 var SWEEP_DEPTH_LIMIT = 256;
 function collectGatedSourceRefs(node, gate, out, limits, depth = 0) {
   if (depth > SWEEP_DEPTH_LIMIT) {
@@ -4588,15 +4750,24 @@ function collectReferenceAccess(node, access, pathPrefix, out, depth = 0) {
   }
   for (const value of Object.values(object2)) collectReferenceAccess(value, nested, pathPrefix, out, depth + 1);
 }
-function withContainerAccess(object2, context, walk2) {
+function withContainerAccess(object2, context, walk2, nested = false) {
   const outer = context.access;
   context.access = descendNavigationAccess(outer, navigationAccess(object2));
   try {
-    return walk2();
+    return withOperationScope(object2, context, nested, walk2);
   } finally {
     context.access = outer;
   }
 }
+function withOperationScope(object2, context, nested, walk2) {
+  const outer = context.operations;
+  context.operations = descendOperationScope(outer, object2, nested);
+  try {
+    return walk2();
+  } finally {
+    context.operations = outer;
+  }
+}
 function warnOnce(context, key, message) {
   if (context.warningKeys.has(key)) return;
   context.warningKeys.add(key);
@@ -4634,11 +4805,32 @@ var OPENAPI_OPERATION_REF = /^(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+\S/;
 function convertPage(value, context) {
   if (typeof value === "string") {
     if (OPENAPI_OPERATION_REF.test(value)) {
-      warnOnce(
-        context,
-        "openapi-operation-list",
-        'One or more navigation groups hand-pick or reorder individual OpenAPI operations (e.g. "GET /users"); Thally always renders every operation of a bound spec and has no manual-selection equivalent, so that list was dropped. The operations themselves are still available through the bound API reference.'
-      );
+      const { bound, gated, hidden, level } = context.operations;
+      if (!context.operationGroups || !bound) {
+        warnOnce(
+          context,
+          "openapi-operation-list",
+          'Navigation lists individual OpenAPI operations (e.g. "GET /users") that were not added to the API navigation: an operation list is carried over only from a tab or group that names an openapi spec in a migrated docs.json. The operations themselves still have pages in the API reference.'
+        );
+      } else if (gated) {
+        warnOnce(
+          context,
+          "openapi-operation-list-gated",
+          'Navigation lists individual OpenAPI operations (e.g. "GET /users") under access-restricted groups, so they were not added to the API navigation. The operations themselves still have pages in the API reference.'
+        );
+      } else if (context.otherLanguage) {
+        warnOnce(
+          context,
+          "openapi-operation-list-language",
+          'Navigation lists individual OpenAPI operations (e.g. "GET /users") under a language other than the default, so they were not added to the API navigation: the API tab follows the default language. The operations themselves still have pages in the API reference.'
+        );
+      } else if (!hidden && level > API_GROUPS_MAX_DEPTH) {
+        warnOnce(
+          context,
+          "openapi-operation-list-depth",
+          `Navigation lists individual OpenAPI operations (e.g. "GET /users") in groups nested more than ${API_GROUPS_MAX_DEPTH} levels deep, so they were not added to the API navigation: the API navigation follows no deeper groups. The operations themselves still have pages in the API reference.`
+        );
+      }
       return null;
     }
     return registerReference(value, context);
@@ -4749,10 +4941,10 @@ function convertMenuItems(items, context) {
         `Mintlify menu item "${label}" has an openapi/asyncapi value without a "source", so its API reference was not migrated.`
       );
     }
-    const children = convertNavigationValues([
+    const children = withOperationScope(item, context, true, () => convertNavigationValues([
       ...Array.isArray(item.groups) ? item.groups : [],
       ...Array.isArray(item.pages) ? item.pages : []
-    ], context);
+    ], context));
     if (typeof item.href === "string" && item.href) {
       warnOnce(
         context,
@@ -4812,7 +5004,7 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
           ...object2.hidden === true ? { hidden: true } : {}
         }];
       }
-      const nested = withContainerAccess(object2, context, () => convertContainerToTabs(object2, context, tab, trace, depth + 1));
+      const nested = withContainerAccess(object2, context, () => convertContainerToTabs(object2, context, tab, trace, depth + 1), true);
       if (nested.length > 0) {
         if (nested.length === 1) {
           return [{
@@ -5036,6 +5228,8 @@ function projectedCompatibleConfig(config, warnings) {
   return {
     // Mintlify pages show a group eyebrow above the title and no breadcrumb trail.
     breadcrumbs: false,
+    // `styling.eyebrows: "breadcrumbs"` shows the whole group path; "section" (the default) shows the nearest group.
+    ...objectValue2(config.styling)?.eyebrows === "breadcrumbs" ? { eyebrow: "path" } : {},
     ...projectedTheme(config.theme) ? { theme: projectedTheme(config.theme) } : {},
     ...projectedContextual.length > 0 ? { contextual: { options: projectedContextual } } : {},
     ...projectedColorsValue ? { colors: projectedColorsValue } : {},
@@ -5181,6 +5375,16 @@ function mintlifyAllVersionPrefixes(config) {
   collect(navigation);
   return prefixes;
 }
+function withLanguageCode(language) {
+  try {
+    return { ...language, language: Intl.getCanonicalLocales(String(language.language ?? language.locale ?? "en"))[0] };
+  } catch {
+    return void 0;
+  }
+}
+function pickDefaultLanguage(languages) {
+  return languages.find((entry) => entry.default === true) ?? languages[0];
+}
 function projectMintlifyNavigation(config, options = {}) {
   const warnings = [];
   const references = [];
@@ -5191,6 +5395,8 @@ function projectMintlifyNavigation(config, options = {}) {
   const gatedNodes = /* @__PURE__ */ new Map();
   const navigation = objectValue2(config.navigation) ?? config;
   const rootAccess = descendNavigationAccess(OPEN_NAVIGATION_ACCESS, navigationAccess(navigation));
+  const rootOperations = descendOperationScope(UNBOUND_OPERATIONS, navigation, true);
+  const operationGroups2 = options.operationGroups === true;
   const limits = { tooDeep: false };
   collectGatedSourceRefs(navigation, void 0, gatedNodes, limits);
   if (limits.tooDeep) {
@@ -5202,20 +5408,16 @@ function projectMintlifyNavigation(config, options = {}) {
   const languages = Array.isArray(navigation.languages) ? navigation.languages.flatMap((value) => {
     const language = objectValue2(value);
     if (!language) return [];
-    try {
-      const code = Intl.getCanonicalLocales(String(language.language ?? language.locale ?? "en"))[0];
-      return [{ ...language, language: code }];
-    } catch {
-      warnings.push({ code: "unsupported-config", message: "A navigation language with an invalid locale code was skipped." });
-      return [];
-    }
+    const withCode = withLanguageCode(language);
+    if (!withCode) warnings.push({ code: "unsupported-config", message: "A navigation language with an invalid locale code was skipped." });
+    return withCode ? [withCode] : [];
   }) : [];
+  const defaultLanguage = pickDefaultLanguage(languages);
   let tabs = [];
   let i18n;
   const localizedNavigation = {};
   const projectionTrace = {};
-  if (languages.length > 0) {
-    const defaultLanguage = languages.find((entry) => entry.default === true) ?? languages[0];
+  if (defaultLanguage) {
     const defaultLocale = String(defaultLanguage.language);
     const locales = languages.map((entry) => {
       const code = String(entry.language);
@@ -5241,6 +5443,9 @@ function projectMintlifyNavigation(config, options = {}) {
         warningKeys,
         appearances,
         access: descendNavigationAccess(rootAccess, navigationAccess(language)),
+        operations: descendOperationScope(rootOperations, language, true),
+        operationGroups: operationGroups2,
+        otherLanguage: language !== defaultLanguage,
         gatedSourceRefs,
         gatedNodes,
         limits
@@ -5260,9 +5465,10 @@ function projectMintlifyNavigation(config, options = {}) {
     }
     if (Object.keys(localizedNavigation).length > 0) i18n.navigation = localizedNavigation;
   } else {
-    const context = { references, seenReferences, warnings, warningKeys, appearances, access: rootAccess, gatedSourceRefs, gatedNodes, limits, pathPrefix: options.pathPrefix, resolveSourceRef: options.resolveSourceRef };
+    const context = { references, seenReferences, warnings, warningKeys, appearances, access: rootAccess, operations: rootOperations, operationGroups: operationGroups2, gatedSourceRefs, gatedNodes, limits, pathPrefix: options.pathPrefix, resolveSourceRef: options.resolveSourceRef };
     tabs = convertContainerToTabs(navigation, context, "Documentation", projectionTrace);
     if (tabs.length === 0 && Array.isArray(config.navigation)) {
+      context.operations = UNBOUND_OPERATIONS;
       const children = convertNavigationValues(config.navigation, context);
       if (children.length > 0) {
         const hasRootPages = children.some((page) => typeof page === "string");
@@ -5279,7 +5485,7 @@ function projectMintlifyNavigation(config, options = {}) {
       message: "Mintlify navigation could not be projected; generated navigation will be used."
     });
   }
-  const versionOwner = languages.length > 0 ? languages.find((entry) => entry.default === true) ?? languages[0] : navigation;
+  const versionOwner = defaultLanguage ?? navigation;
   const globalNavigation = objectValue2(versionOwner.global) ?? objectValue2(navigation.global);
   const shortcuts = Array.isArray(globalNavigation?.anchors) ? globalNavigation.anchors.flatMap((value) => {
     const anchor = objectValue2(value);
@@ -7196,8 +7402,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}`;
@@ -7205,25 +7452,44 @@ 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;
-}
-function operationKey(operation) {
+  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 operationKey2(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(operationKey2)
   )];
 }
-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;
@@ -10474,22 +10740,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"'()<>[\]{}=,;:|\\/`*!?#&]+/;
@@ -10590,6 +10890,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 [];
@@ -10601,19 +10918,25 @@ 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 });
   }
@@ -10631,14 +10954,28 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
       delete mount.operations;
     }
   };
+  const listsNothing = (reference) => !reference.groups && !reference.operationsWithheld && !reference.otherLanguage;
+  const groupTargets = /* @__PURE__ */ new Map();
   const specs = [];
   for (const reference of references) {
     const dedupeKey = `${reference.kind}:${reference.value}:${reference.tabLabel ?? ""}`;
     if (seen.has(dedupeKey)) {
       mountDirectory(remoteByKey.get(dedupeKey), reference);
+      const shared = groupTargets.get(dedupeKey);
+      if (shared && !shared.unlisted) {
+        if (reference.operationsWithheld) shared.withheld = true;
+        if (reference.groups) {
+          const merged = mergeApiGroups(shared.target.groups, reference.groups);
+          if (merged) shared.target.groups = merged;
+        } else if (listsNothing(reference)) {
+          shared.unlisted = true;
+          delete shared.target.groups;
+        }
+      }
       continue;
     }
     seen.add(dedupeKey);
+    const groups = mergeApiGroups(void 0, reference.groups);
     const tabSuffix = reference.tabLabel ? ` (tab "${reference.tabLabel}")` : "";
     if (reference.kind === "asyncapi") {
       warnings.push({
@@ -10648,10 +10985,11 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
       continue;
     }
     if (/^https:\/\//i.test(reference.value)) {
-      const remote = { url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {} };
+      const remote = { url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, ...groups ? { groups } : {} };
       mountDirectory(remote, reference);
       remoteSpecs.push(remote);
       remoteByKey.set(dedupeKey, remote);
+      groupTargets.set(dedupeKey, { target: remote, unlisted: listsNothing(reference), withheld: reference.operationsWithheld === true });
       warnings.push({
         code: "unsupported-config",
         message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} requires a network download before this import is complete.`,
@@ -10663,7 +11001,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({
@@ -10680,7 +11018,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
     }
     const content = readSpecFile(match.absolutePath, match.relativePath, warnings);
     if (!content) continue;
-    specs.push({
+    const spec = {
       filename: basename3(match.relativePath),
       content,
       tabLabel: reference.tabLabel,
@@ -10689,24 +11027,16 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
       hidden: reference.hidden,
       ...reference.pageOnly ? { pageOnly: true } : {},
       sourcePath: match.relativePath,
-      directory: reference.directory
-    });
+      directory: reference.directory,
+      ...groups ? { groups } : {}
+    };
+    specs.push(spec);
+    groupTargets.set(dedupeKey, { target: spec, unlisted: listsNothing(reference), withheld: reference.operationsWithheld === true });
   }
-  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 { target: target2, unlisted, withheld } of groupTargets.values()) {
+    if (withheld && !unlisted && !target2.groups) target2.navigation = false;
   }
+  for (const spec of specs) spec.filename = nameSpec(spec);
   return specs;
 }
 function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings, explainMissing = () => "no such file was found") {
@@ -10719,12 +11049,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 });
     }
@@ -12055,9 +12386,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;
       }
@@ -12066,15 +12400,18 @@ function injectOpenApiSpecs(config, specs, warnings) {
         // An API-only tab needs generated endpoint navigation; an authored
         // page tab keeps its own groups alongside the bound spec, unless
         // Mintlify generated the endpoint pages (the renderer appends the
-        // endpoint groups after the authored ones).
-        ...(apiTab.groups?.length || apiTab.pages?.length) && !spec.generatedNavigation ? { navigation: false } : {}
+        // endpoint groups after the authored ones) or docs.json lists the
+        // operations itself (those authored groups are the API navigation).
+        // A spec whose listed operations are all withheld has no endpoint navigation either way.
+        ...spec.navigation === false || (apiTab.groups?.length || apiTab.pages?.length) && !spec.generatedNavigation && !spec.groups ? { navigation: false } : {},
+        ...spec.groups ? { groups: spec.groups } : {}
       };
     } else {
       insertApiTab(tabs, {
         tab: spec.tabLabel ?? "API Reference",
         ...spec.icon ? { icon: spec.icon } : {},
         ...spec.hidden ? { hidden: true } : {},
-        api: { source: specAssetPath(spec.filename) }
+        api: { source: specAssetPath(spec.filename), ...spec.navigation === false ? { navigation: false } : {}, ...spec.groups ? { groups: spec.groups } : {} }
       }, spec.parentTab);
     }
   }
@@ -12159,6 +12496,8 @@ function migrateRepository(options) {
         defaultVersionPrefixes = mintlifyDefaultVersionPrefixes(config);
         allVersionPrefixes = mintlifyAllVersionPrefixes(config);
         const projected = projectMintlifyNavigation(config, {
+          // injectOpenApiSpecs / hydrateRemoteApiSpecs bind the authored operation lists to their API tabs.
+          operationGroups: true,
           resolveSourceRef: (repo) => {
             const ref = activeSourceRefs.find((candidate) => candidate.repo.toLowerCase() === repo.toLowerCase());
             if (!ref) return null;
@@ -12316,6 +12655,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()));
@@ -12352,6 +12692,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) {
@@ -12455,6 +12796,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;
@@ -12550,7 +12908,6 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       }
       continue;
     }
-    const key = normalizedReferenceKey(file.relativePath);
     let pageGate;
     {
       pageGate = gateByPath.get(file.absolutePath);
@@ -12600,25 +12957,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,
@@ -13267,8 +13612,21 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
     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) {
@@ -13278,9 +13636,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(operationKey2(operation)));
     }
     const resolvedSpecs = allSpecs.filter((spec) => !spec.pageOnly);
     const pageOnlySpecs = allSpecs.filter((spec) => spec.pageOnly);
@@ -13288,12 +13647,14 @@ ${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);
       if (remoteApiSpecs.length > 0) {
@@ -13311,13 +13672,16 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       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(operationKey2(operation)));
           if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
             assets.push(specAsset(filename, pruned.content));
           }
@@ -13329,13 +13693,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(operationKey2(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";
@@ -13675,10 +14048,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: {
@@ -13707,15 +14080,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") {
@@ -13725,13 +14113,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 } };
@@ -13764,7 +14162,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."
   });
@@ -15714,8 +16112,9 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
         if (ref?.specRef === reference.url) page.openapi = withSpecRef(ref, `openapi/${filename}`);
       }
       const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
-      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 api = { source: `openapi/${filename}`, ...reference.navigation === false ? { navigation: false } : {}, ...reference.groups ? { groups: reference.groups } : {} };
+      if (tab) tab.api = api;
+      else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api }, reference.parentTab);
       bound.push({ reference, filename, content: body, operations, tabName: tab?.tab ?? reference.tabLabel ?? "API Reference" });
     } catch (error) {
       warnings.push({