@thallylabs/migrate 0.2.34 → 0.2.35

package/README.md

@@ -92,6 +92,40 @@ instead of silently dropping that API tab's reference. AsyncAPI has no Thally
 renderer, so it always produces a clear warning naming the spec instead of
 disappearing.
 
+`METHOD /path` entries (`"POST /v2/keys.createKey"`) under a container that
+binds an `openapi` spec become `api.groups` on the tab that spec binds to:
+nested groups, icons and authored order are kept, and page entries stay in the
+tab's own groups (a group that mixes pages and operations is split, so the
+sidebar lists the API groups after the page groups). Operations written
+straight under a tab form a group named after the tab, at their place among the
+tab's own groups (each uninterrupted run is its own group, so authored order is
+kept). Hidden groups (and containers under one), groups under access-restricted
+containers, and groups left empty are left out. Groups nest at most 32 levels
+deep, as the renderer follows no deeper: operations below that are not migrated,
+and one warning says so. With `navigation.languages`, only the default language's
+containers contribute groups; operation entries under another language are
+reported, since its API tab is the default language's.
+When several containers bind one spec to the same tab (one API tab per product,
+say), their groups are concatenated in order and an operation already listed
+earlier in that tab is dropped (the method is compared without case, the path
+exactly), unless one of those containers lists no operation (Mintlify generated
+every operation there), in which case the tab gets no `api.groups` and keeps the
+generated, tag-grouped navigation. A container whose operations are all hidden or
+access-restricted adds no groups but still counts as listing operations; when
+every container bound to a tab is like that, the tab gets `navigation: false`
+(the source sidebar showed none of those operations, so no generated list is
+added). Operations dropped only for nesting too deep are Thally's limit, not the
+author's choice: such a container counts as listing nothing, so the tab keeps
+the generated navigation. Groups with the same title are not folded together. With `api.groups`
+the authored list is the tab's navigation, so `navigation: false` is not
+written. Operation entries with no `openapi` container above them, and every one in a
+site imported by URL, cannot be placed: one warning says they were not added to the API navigation, and the
+operations still have their pages. This is separate from a `directory`'s flat
+operation list, which still only drives the endpoint redirects.
+
+Mintlify `styling.eyebrows: "breadcrumbs"` becomes `eyebrow: "path"` (the full
+group path above the page title); `"section"` or no setting writes nothing.
+
 Page `openapi:` frontmatter with a spec prefix
 (`openapi: "specs/openapi-b.yaml GET /widgets/{id}"`) is rewritten to where the
 spec lands in the output (`/openapi-b.yaml GET /widgets/{id}`). As in Mintlify,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MigrationPage, a as MigrationAsset, b as MigrationNavigationGroup, R as RenderedMigrationFile, c as MigrationWarning, d as MigrationFetcher, e as MigrationPlatform, f as MigrationBundle, g as MigrationDocsConfig } from './url-migration-EwtII4P-.js';
-export { h as MigrationCapture, i as MigrationCaptureProvider, j as MigrationCaptureState, k as MigrationCapturedAsset, l as MigrationEvidence, m as MigrationFetchRequest, n as MigrationFetchResponse, o as MigrationJournalAsset, p as MigrationNavigationOccurrence, q as MigrationNavigationTab, U as UrlMigrationCheckpoint, r as UrlMigrationCheckpointDelta, s as UrlMigrationIssue, t as UrlMigrationRecord, u as UrlMigrationRun, v as UrlMigrationRunOptions, w as UrlMigrationValidation, x as classifyMigrationResponse, y as mergeMigrationConfig, z as renderMigrationFiles, A as runUrlMigration, B as validateUrlMigration } from './url-migration-EwtII4P-.js';
+import { M as MigrationPage, a as MigrationAsset, b as MigrationNavigationGroup, R as RenderedMigrationFile, c as MigrationWarning, d as MigrationFetcher, e as MigrationPlatform, f as MigrationBundle, g as MigrationDocsConfig } from './url-migration-peVzTLjL.js';
+export { h as MigrationCapture, i as MigrationCaptureProvider, j as MigrationCaptureState, k as MigrationCapturedAsset, l as MigrationEvidence, m as MigrationFetchRequest, n as MigrationFetchResponse, o as MigrationJournalAsset, p as MigrationNavigationOccurrence, q as MigrationNavigationTab, U as UrlMigrationCheckpoint, r as UrlMigrationCheckpointDelta, s as UrlMigrationIssue, t as UrlMigrationRecord, u as UrlMigrationRun, v as UrlMigrationRunOptions, w as UrlMigrationValidation, x as classifyMigrationResponse, y as mergeMigrationConfig, z as renderMigrationFiles, A as runUrlMigration, B as validateUrlMigration } from './url-migration-peVzTLjL.js';
 export { isPassiveSvg } from './svg-policy.js';
 
 /**
@@ -182,6 +182,11 @@ interface MintlifyProjectionOptions {
      * when the repository was not mapped with `--source-ref`.
      */
     resolveSourceRef?: (repo: string) => Array<string | MigrationNavigationGroup> | null;
+    /**
+     * Set by a caller that binds the authored operation lists (`mintlifyNavigationApiReferences`
+     * `groups`) to their API tabs. Without it every "METHOD /path" entry is reported as not carried over.
+     */
+    operationGroups?: boolean;
 }
 /** Preserve Mintlify's implicit `/section` route for section landing pages. */
 declare function addMintlifyDirectoryRedirects(config: MigrationDocsConfig, pages: Array<MigrationPage>): MigrationDocsConfig;

package/dist/index.js

@@ -4524,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 } : {}
         });
       }
     }
@@ -4568,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];
@@ -4576,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) {
@@ -4585,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)) {
@@ -4597,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) {
@@ -4637,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) {
@@ -4670,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);
@@ -4716,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);
@@ -4831,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,
@@ -4894,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 [{
@@ -5118,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 } : {},
@@ -5263,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 = [];
@@ -5273,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) {
@@ -5284,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);
@@ -5323,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
@@ -5342,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");
@@ -5361,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);
@@ -7354,13 +7478,13 @@ function refKeepsIn(ref, spec, specs) {
   const { unique, sources } = resolvedSources(ref, specs);
   return unique && sources[0] === spec.sourcePath;
 }
-function operationKey(operation) {
+function operationKey2(operation) {
   const [first, ...rest] = operation.trim().split(/\s+/);
   return `${first.toLowerCase()} ${rest.join(" ")}`;
 }
 function keysFor(refs, names) {
   return [...new Set(
-    refs.filter(names).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, specs = [spec]) {
@@ -10830,14 +10954,28 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
       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({
@@ -10847,10 +10985,11 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
       continue;
     }
     if (/^https:\/\//i.test(reference.value)) {
-      const remote = { url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {} };
+      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.`,
@@ -10879,7 +11018,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
     }
     const content = readSpecFile(match.absolutePath, match.relativePath, warnings);
     if (!content) continue;
-    specs.push({
+    const spec = {
       filename: basename3(match.relativePath),
       content,
       tabLabel: reference.tabLabel,
@@ -10888,8 +11027,14 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
       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 });
+  }
+  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;
@@ -12255,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);
     }
   }
@@ -12348,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;
@@ -13489,7 +13639,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       const result = excludeWithheldOperations(spec, withheldSpecRefs, keptSpecRefs, allSpecs);
       spec.content = result.content;
       withheldOperations.set(spec, result.excluded);
-      result.excluded.forEach((operation) => withheldKeys.add(operationKey(operation)));
+      result.excluded.forEach((operation) => withheldKeys.add(operationKey2(operation)));
     }
     const resolvedSpecs = allSpecs.filter((spec) => !spec.pageOnly);
     const pageOnlySpecs = allSpecs.filter((spec) => spec.pageOnly);
@@ -13531,7 +13681,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
           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)));
+          pruned.excluded.forEach((operation) => withheldKeys.add(operationKey2(operation)));
           if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
             assets.push(specAsset(filename, pruned.content));
           }
@@ -13549,7 +13699,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       docsConfig = injectOpenApiSpecs(docsConfig, pageOnlySpecs, warnings);
       pageSpecs = [...pageSpecs, ...pageOnlySpecs];
     }
-    const notKeptPublic = [...new Set(unownedOperations.filter((operation) => withheldKeys.has(operationKey(operation))))];
+    const notKeptPublic = [...new Set(unownedOperations.filter((operation) => withheldKeys.has(operationKey2(operation))))];
     if (notKeptPublic.length > 0) {
       warnings.push({
         code: "gated-page",
@@ -15962,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({