@thallylabs/migrate 0.2.12 → 0.2.17

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   statSync
 } from "fs";
 import { createRequire } from "module";
-import { basename as basename3, dirname as dirname4, extname as extname5, isAbsolute as isAbsolute2, relative as relative5, resolve as resolvePath, sep as sep2 } from "path";
+import { basename as basename3, dirname as dirname4, extname as extname6, isAbsolute as isAbsolute2, posix as posix3, relative as relative5, resolve as resolvePath, sep as sep2 } from "path";
 import { parse as parseYaml4 } from "yaml";
 import * as ts3 from "typescript";
 
@@ -3104,13 +3104,96 @@ import { customComponents as ${name} } from ${JSON.stringify(registryPath)}
 
 // src/docusaurus.ts
 import { existsSync as existsSync3, lstatSync as lstatSync3, readFileSync as readFileSync3 } from "fs";
-import { extname as extname3, posix as posix2 } from "path";
+import { extname as extname4, posix as posix2 } from "path";
 import JSON5 from "json5";
 import { parse as parseYaml2 } from "yaml";
 
 // src/navigation.ts
 import { existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as readFileSync2, realpathSync } from "fs";
-import { dirname as dirname2, extname as extname2, relative as relative3 } from "path";
+import { dirname as dirname2, extname as extname3, relative as relative3 } from "path";
+
+// src/mintlify-extras.ts
+import { extname as extname2 } from "path";
+function objectValue(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+var PUBLIC_FALSE_STRINGS = /* @__PURE__ */ new Set(["false", "no", "off", "0"]);
+function isPublicFalse(value) {
+  return value === false || value === 0 || typeof value === "string" && PUBLIC_FALSE_STRINGS.has(value.trim().toLowerCase());
+}
+function isPublicTrue(value) {
+  return value === true || typeof value === "string" && value.trim().toLowerCase() === "true";
+}
+function frontmatterGateReason(data) {
+  const groups = data.groups;
+  const hasGroups = Array.isArray(groups) ? groups.length > 0 : typeof groups === "string" ? groups.trim() !== "" : groups !== void 0 && groups !== null && groups !== false;
+  if (hasGroups) return "frontmatter `groups` restricts it to authenticated groups";
+  if (isPublicFalse(data.public)) return "frontmatter `public: false`";
+  return void 0;
+}
+function navigationGateReason(node) {
+  const groups = node.groups;
+  const isContainer = (entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry) && ["group", "pages", "tab", "groups", "page", "root", "menu", "href"].some((key) => key in entry);
+  const restricted = typeof groups === "string" ? groups.trim() !== "" : Array.isArray(groups) && groups.length > 0 && !groups.every(isContainer);
+  if (restricted) return "its navigation container sets `groups`";
+  if (isPublicFalse(node.public)) return "its navigation container sets `public: false`";
+  return void 0;
+}
+var CONFIG_BASENAME = /(?:^|[.-])(?:config|rc)\.[cm]?js$|^(?:tailwind|postcss|next|eslint|prettier|babel|webpack|vite|vitest|jest|rollup|gulpfile|gruntfile|stylelint|commitlint|lint-staged|svgo|metro)[.-]/i;
+var BUILD_OUTPUT_SEGMENTS = /* @__PURE__ */ new Set(["dist", "build", "coverage"]);
+var FONT_EXTENSIONS = /* @__PURE__ */ new Set([".woff", ".woff2", ".ttf", ".otf"]);
+function isMintlifyServedScriptOrStyle(relativePath) {
+  const extension = extname2(relativePath).toLowerCase();
+  if (extension !== ".css" && extension !== ".js") return false;
+  const segments = relativePath.split("/");
+  if (segments.slice(0, -1).some((segment) => BUILD_OUTPUT_SEGMENTS.has(segment.toLowerCase()))) return false;
+  return extension === ".css" || !CONFIG_BASENAME.test(segments[segments.length - 1]);
+}
+function mintlifyFontSources(config) {
+  const fonts = objectValue(config?.fonts);
+  if (!fonts) return [];
+  const found = [];
+  for (const entry of [fonts, objectValue(fonts.heading), objectValue(fonts.body)]) {
+    if (!entry || typeof entry.source !== "string" || !entry.source.trim()) continue;
+    const source = entry.source.trim();
+    const family = typeof entry.family === "string" ? entry.family : "a font";
+    const remote = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(source);
+    const path = remote || /^[a-z]:[\\/]/i.test(source) ? null : normalizeAssetPath(source);
+    found.push({ family, source, path: path && FONT_EXTENSIONS.has(extname2(path).toLowerCase()) ? path : null, remote });
+  }
+  return found;
+}
+function mintlifyAppearance(config, warnings) {
+  const appearance = objectValue(config.appearance);
+  const legacy = objectValue(config.modeToggle);
+  const result = {};
+  const isMode = (value) => value === "system" || value === "light" || value === "dark";
+  const skip = (field, value) => {
+    warnings.push({
+      code: "unsupported-config",
+      message: `Ignored invalid ${field} value ${JSON.stringify(value)?.slice(0, 40)}; the appearance default was left unchanged.`
+    });
+  };
+  if (appearance?.default !== void 0) {
+    if (isMode(appearance.default)) result.default = appearance.default;
+    else skip("appearance.default", appearance.default);
+  } else if (legacy?.default !== void 0) {
+    if (isMode(legacy.default)) result.default = legacy.default;
+    else skip("modeToggle.default", legacy.default);
+  }
+  if (appearance?.strict !== void 0) {
+    if (typeof appearance.strict === "boolean") {
+      if (appearance.strict) result.showToggle = false;
+    } else skip("appearance.strict", appearance.strict);
+  } else if (legacy?.isHidden !== void 0) {
+    if (typeof legacy.isHidden === "boolean") {
+      if (legacy.isHidden) result.showToggle = false;
+    } else skip("modeToggle.isHidden", legacy.isHidden);
+  }
+  return result;
+}
+
+// src/navigation.ts
 var MAX_MINTLIFY_CONFIG_BYTES = 2e7;
 function addMintlifyDirectoryRedirects(config, pages) {
   const pageIds = new Set(pages.map((page) => page.id));
@@ -3210,13 +3293,13 @@ var LANGUAGE_LABELS = {
   uk: "Ukrainian",
   zh: "Chinese"
 };
-function objectValue(value) {
+function objectValue2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function withFlattenedProductGroups(container) {
   if (!Array.isArray(container.productGroups)) return container;
   const flattened = container.productGroups.flatMap((entry) => {
-    const group = objectValue(entry);
+    const group = objectValue2(entry);
     return group && Array.isArray(group.products) ? group.products : [];
   });
   if (flattened.length === 0) return container;
@@ -3235,7 +3318,7 @@ function projectedHref(value) {
   return href;
 }
 function labelFor(value, fallback) {
-  for (const key of ["tab", "group", "anchor", "product", "dropdown", "version", "menu", "label", "name", "title"]) {
+  for (const key of ["tab", "group", "anchor", "product", "dropdown", "version", "menu", "item", "label", "name", "title"]) {
     if (typeof value[key] === "string" && value[key]) return String(value[key]);
   }
   return fallback;
@@ -3251,7 +3334,7 @@ function jsonPointer(root, pointer) {
       const index = Number(token);
       return Number.isSafeInteger(index) && index >= 0 ? current[index] : void 0;
     }
-    const object = objectValue(current);
+    const object = objectValue2(current);
     if (!object) return void 0;
     return object[token.replace(/~1/g, "/").replace(/~0/g, "~")];
   }, root);
@@ -3272,7 +3355,7 @@ function resolveJsonReferences(value, currentFile, repositoryRoot, stack) {
   if (Array.isArray(value)) {
     return value.map((entry) => resolveJsonReferences(entry, currentFile, repositoryRoot, stack));
   }
-  const object = objectValue(value);
+  const object = objectValue2(value);
   if (!object) return value;
   if (typeof object.$ref === "string") {
     const [filePart, pointer = ""] = object.$ref.split("#", 2);
@@ -3292,7 +3375,7 @@ function resolveJsonReferences(value, currentFile, repositoryRoot, stack) {
         resolveJsonReferences(entry, currentFile, repositoryRoot, stack)
       ])
     );
-    return objectValue(resolved) ? { ...resolved, ...siblings } : resolved;
+    return objectValue2(resolved) ? { ...resolved, ...siblings } : resolved;
   }
   return Object.fromEntries(
     Object.entries(object).map(([key, entry]) => [
@@ -3307,34 +3390,45 @@ function readMintlifyConfig(repositoryRoot) {
   const raw = readMintlifyJson(configPath, repositoryRoot);
   return resolveJsonReferences(raw, configPath, repositoryRoot, /* @__PURE__ */ new Set());
 }
+function specSource(value) {
+  const source = typeof value === "string" ? value : objectValue2(value)?.source;
+  return typeof source === "string" && source.trim() ? source.trim() : void 0;
+}
+var hasNavigationChildren = (node) => ["groups", "pages"].some((key) => Array.isArray(node[key]) && node[key].length > 0);
 function mintlifyNavigationApiReferences(config) {
-  const navigation = objectValue(config.navigation) ?? config;
+  const navigation = objectValue2(config.navigation) ?? config;
   const references = [];
   const containerKeys = ["tabs", "anchors", "products", "dropdowns", "versions", "menus", "languages"];
   const nestedKeys = ["groups", "pages"];
-  function visit(rawNode, tabLabel) {
-    const node = withFlattenedProductGroups(rawNode);
+  function collect(node, tabLabel, sibling) {
     for (const kind of ["openapi", "asyncapi"]) {
-      const value = node[kind];
-      if (typeof value === "string" && value.trim()) {
-        references.push({ value: value.trim(), kind, tabLabel });
-        continue;
-      }
-      const object = objectValue(value);
-      if (object && typeof object.source === "string" && object.source.trim()) {
+      const value = specSource(node[kind]);
+      const directory = objectValue2(node[kind])?.directory;
+      if (value) {
         references.push({
-          value: object.source.trim(),
+          value,
           kind,
           tabLabel,
-          ...typeof object.directory === "string" && object.directory.trim() ? { directory: object.directory.trim() } : {}
+          ...sibling,
+          ...typeof directory === "string" && directory.trim() ? { directory: directory.trim() } : {}
         });
       }
     }
+  }
+  const siblingSources = /* @__PURE__ */ new Map();
+  function uniqueSiblingLabel(label, source) {
+    let candidate = label;
+    for (let n = 2; siblingSources.has(candidate) && siblingSources.get(candidate) !== source; n++) candidate = `${label} (${n})`;
+    siblingSources.set(candidate, source);
+    return candidate;
+  }
+  function visitChildren(rawNode, tabLabel) {
+    const node = withFlattenedProductGroups(rawNode);
     for (const key of containerKeys) {
       const entries = node[key];
       if (!Array.isArray(entries)) continue;
       for (const entry of entries) {
-        const object = objectValue(entry);
+        const object = objectValue2(entry);
         if (!object) continue;
         visit(object, labelFor(object, tabLabel ?? "Documentation"));
       }
@@ -3344,14 +3438,49 @@ function mintlifyNavigationApiReferences(config) {
       if (!Array.isArray(entries)) continue;
       for (const entry of entries) {
         if (typeof entry === "string") continue;
-        const object = objectValue(entry);
+        const object = objectValue2(entry);
         if (object) visit(object, tabLabel);
       }
     }
+    if (Array.isArray(node.menu)) {
+      const tab = tabLabel ?? "Documentation";
+      const items = node.menu.flatMap((entry) => {
+        const object = objectValue2(entry);
+        return object ? [object] : [];
+      });
+      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);
+        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 } : {} });
+        }
+        visitChildren(item, tabLabel);
+      });
+    }
+  }
+  function visit(node, tabLabel) {
+    collect(node, tabLabel);
+    visitChildren(node, tabLabel);
   }
   visit(navigation, void 0);
   return references;
 }
+function insertApiTab(tabs, tab, parentTab) {
+  let index = -1;
+  if (parentTab) {
+    tabs.forEach((candidate, position) => {
+      if (candidate.tab === parentTab || candidate.tab.startsWith(`${parentTab}: `)) index = position;
+    });
+  }
+  tabs.splice(index === -1 ? tabs.length : index + 1, 0, tab);
+  return tabs;
+}
 function normalizePageRef(value, pathPrefix = "") {
   if (/^(?:https?:)?\/\//i.test(value) || value.startsWith("#")) return null;
   let ref = localReference(value).split("?", 1)[0].replace(/^\/+/, "");
@@ -3362,6 +3491,23 @@ function normalizePageRef(value, pathPrefix = "") {
   ref = ref.replace(/\.(?:mdx?|rst|txt)$/i, "");
   return pageIdFromReference(ref, true);
 }
+function collectGatedReferences(node, gate, pathPrefix, out, depth = 0) {
+  if (depth > 32) return;
+  if (Array.isArray(node)) {
+    for (const item of node) collectGatedReferences(item, gate, pathPrefix, out, depth + 1);
+    return;
+  }
+  const object = objectValue2(node);
+  if (!object) return;
+  const reason = gate ?? navigationGateReason(object);
+  if (reason) {
+    const refs = [object.page, object.root, ...Array.isArray(object.pages) ? object.pages : []];
+    for (const ref of refs) {
+      if (typeof ref === "string" && normalizePageRef(ref, pathPrefix)) out.push({ ref, reason });
+    }
+  }
+  for (const value of Object.values(object)) collectGatedReferences(value, reason, pathPrefix, out, depth + 1);
+}
 function warnOnce(context, key, message) {
   if (context.warningKeys.has(key)) return;
   context.warningKeys.add(key);
@@ -3369,7 +3515,7 @@ function warnOnce(context, key, message) {
 }
 function iconName(value) {
   if (typeof value === "string" && value) return value;
-  const icon = objectValue(value);
+  const icon = objectValue2(value);
   return typeof icon?.name === "string" && icon.name ? icon.name : void 0;
 }
 function containerPresentation(value) {
@@ -3379,6 +3525,10 @@ function containerPresentation(value) {
   };
 }
 function registerReference(value, context) {
+  if (context.gateReason) {
+    if (normalizePageRef(value, context.pathPrefix)) context.gated.push({ ref: value, reason: context.gateReason });
+    return null;
+  }
   const localizedValue = context.locale ? mintlifyLocalizedReference(value, context.locale, context.defaultPageIds) : value;
   const navigationId = normalizePageRef(localizedValue, context.pathPrefix);
   if (!navigationId) return null;
@@ -3402,13 +3552,24 @@ function convertPage(value, context) {
     }
     return registerReference(value, context);
   }
-  const object = objectValue(value);
+  const object = objectValue2(value);
   if (!object) return null;
+  const outerGate = context.gateReason;
+  const gate = navigationGateReason(object);
+  if (gate && !outerGate) context.gateReason = gate;
+  try {
+    return convertPageObject(object, context);
+  } finally {
+    context.gateReason = outerGate;
+  }
+}
+function convertPageObject(object, context) {
   if (typeof object.page === "string") return registerReference(object.page, context);
   const href = projectedHref(object.href);
   if (href && !object.pages && !object.groups) {
     const page = registerReference(href, context);
     if (page) return page;
+    if (context.gateReason) return null;
     warnOnce(
       context,
       "external-page-link",
@@ -3437,6 +3598,65 @@ function convertPage(value, context) {
   }
   return null;
 }
+var KNOWN_NAVIGATION_KEYS = /* @__PURE__ */ new Set([
+  "tabs",
+  "anchors",
+  "products",
+  "dropdowns",
+  "versions",
+  "menus",
+  "languages",
+  "productGroups",
+  "groups",
+  "pages",
+  "menu",
+  "global"
+]);
+function convertMenuItems(items, context) {
+  return items.flatMap((value, index) => {
+    const item = objectValue2(value);
+    if (!item) return [];
+    const label = labelFor(item, `Menu item ${index + 1}`);
+    if (typeof item.description === "string" && item.description.trim()) {
+      warnOnce(
+        context,
+        `menu-item-description:${label}`,
+        `Mintlify menu item "${label}" has a description, which Thally groups cannot display; it was omitted.`
+      );
+    }
+    const hasUnsourcedSpec = Boolean(item.openapi || item.asyncapi) && !specSource(item.openapi) && !specSource(item.asyncapi);
+    if (hasUnsourcedSpec) {
+      warnOnce(
+        context,
+        `menu-item-spec:${label}`,
+        `Mintlify menu item "${label}" has an openapi/asyncapi value without a "source", so its API reference was not migrated.`
+      );
+    }
+    const children = convertNavigationValues([
+      ...Array.isArray(item.groups) ? item.groups : [],
+      ...Array.isArray(item.pages) ? item.pages : []
+    ], context);
+    if (typeof item.href === "string" && item.href) {
+      warnOnce(
+        context,
+        `menu-item-href:${label}`,
+        `Mintlify menu item "${label}" links to ${item.href}, which cannot be represented as a Thally group; the link was omitted.`
+      );
+    }
+    if (children.length === 0) {
+      if (!specSource(item.openapi) && !specSource(item.asyncapi) && !hasUnsourcedSpec) {
+        warnOnce(context, `menu-item-empty:${label}`, `Mintlify menu item "${label}" has no projectable pages and was omitted.`);
+      }
+      return [];
+    }
+    return [{
+      group: label,
+      ...iconName(item.icon) ? { icon: iconName(item.icon) } : {},
+      ...item.hidden === true ? { hidden: true } : {},
+      pages: children
+    }];
+  });
+}
 function convertNavigationValues(values, context) {
   return values.flatMap((value) => {
     const page = convertPage(value, context);
@@ -3444,22 +3664,29 @@ function convertNavigationValues(values, context) {
   });
 }
 function convertContainerToTabs(containerValue, context, fallbackTab, trace, depth = 0) {
-  const rawContainer = objectValue(containerValue);
+  const rawContainer = objectValue2(containerValue);
   if (!rawContainer) return [];
   const container = withFlattenedProductGroups(rawContainer);
   const containerKeys = ["tabs", "anchors", "products", "dropdowns", "versions", "menus"];
+  for (const key of Object.keys(container)) {
+    if (KNOWN_NAVIGATION_KEYS.has(key)) continue;
+    const entries = container[key];
+    if (Array.isArray(entries) && entries.some((entry) => objectValue2(entry))) {
+      warnOnce(context, `unknown-container:${key}`, `Mintlify navigation key "${key}" is not supported and its contents were not projected.`);
+    }
+  }
   for (const key of containerKeys) {
     if (!Array.isArray(container[key])) continue;
     const entries = [...container[key]];
     if (key === "versions") {
-      entries.sort((left, right) => Number(objectValue(right)?.default === true) - Number(objectValue(left)?.default === true));
+      entries.sort((left, right) => Number(objectValue2(right)?.default === true) - Number(objectValue2(left)?.default === true));
     }
     const tabs = entries.flatMap((value, index) => {
-      const object = objectValue(value);
+      const object = objectValue2(value);
       if (!object) return [];
       const tab = labelFor(object, `${fallbackTab} ${index + 1}`);
       const href = projectedHref(object.href);
-      const hasNestedContainers = containerKeys.some((containerKey) => Array.isArray(object[containerKey]));
+      const hasNestedContainers = [...containerKeys, "menu"].some((containerKey) => Array.isArray(object[containerKey]));
       if (href && !object.pages && !object.groups && !hasNestedContainers) {
         return [{
           tab,
@@ -3468,7 +3695,15 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
           ...object.hidden === true ? { hidden: true } : {}
         }];
       }
-      const nested = convertContainerToTabs(object, context, tab, trace, depth + 1);
+      const outerGate = context.gateReason;
+      const gate = navigationGateReason(object);
+      if (gate && !outerGate) context.gateReason = gate;
+      let nested;
+      try {
+        nested = convertContainerToTabs(object, context, tab, trace, depth + 1);
+      } finally {
+        context.gateReason = outerGate;
+      }
       if (nested.length > 0) {
         if (nested.length === 1) {
           return [{
@@ -3491,6 +3726,11 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
       return [];
     });
     if (tabs.length > 0) {
+      for (const sibling of ["groups", "pages", "menu"]) {
+        if (Array.isArray(container[sibling]) && container[sibling].length > 0) {
+          warnOnce(context, `container-sibling:${key}:${sibling}`, `Mintlify "${sibling}" next to "${key}" was not projected; only the "${key}" containers were kept.`);
+        }
+      }
       if (depth === 0 && trace) trace.rootContainerKind = key;
       return tabs;
     }
@@ -3503,7 +3743,10 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
     ...rawGroups,
     ...rawPages
   ];
-  const children = convertNavigationValues(values, context);
+  const children = [
+    ...convertNavigationValues(values, context),
+    ...Array.isArray(container.menu) ? convertMenuItems(container.menu, context) : []
+  ];
   return children.length > 0 ? [{
     tab: fallbackTab,
     ...hasRootNodes ? { pages: children } : { groups: children },
@@ -3519,17 +3762,17 @@ function projectedTheme(value) {
   return typeof value === "string" ? "default" : void 0;
 }
 function projectedNavbar(value) {
-  const navbar = objectValue(value);
+  const navbar = objectValue2(value);
   if (!navbar) return void 0;
   const links = Array.isArray(navbar.links) ? navbar.links.flatMap((entry) => {
-    const link = objectValue(entry);
+    const link = objectValue2(entry);
     const href = projectedHref(link?.href);
     if (!link || !href) return [];
     const label = typeof link.label === "string" ? link.label : typeof link.name === "string" ? link.name : "";
     if (!label) return [];
     return [{ label, href, ...link.type === "github" ? { type: "github" } : {} }];
   }) : [];
-  const primaryValue = objectValue(navbar.primary);
+  const primaryValue = objectValue2(navbar.primary);
   const primaryHref = projectedHref(primaryValue?.href);
   const primary = primaryValue && primaryHref ? {
     label: typeof primaryValue.label === "string" ? primaryValue.label : primaryValue.type === "github" ? "GitHub" : "Get started",
@@ -3537,8 +3780,22 @@ function projectedNavbar(value) {
   } : void 0;
   return links.length > 0 || primary ? { ...links.length > 0 ? { links } : {}, ...primary ? { primary } : {} } : void 0;
 }
+function legacyTopbarNavbar(config) {
+  const links = Array.isArray(config.topbarLinks) ? config.topbarLinks.flatMap((entry) => {
+    const link = objectValue2(entry);
+    if (!link) return [];
+    return [{
+      label: link.name ?? link.label ?? (link.type === "github" ? "GitHub" : void 0),
+      href: link.url ?? link.href,
+      ...link.type === "github" ? { type: "github" } : {}
+    }];
+  }) : [];
+  const cta = objectValue2(config.topbarCtaButton);
+  const primary = cta ? { label: cta.name ?? cta.label, href: cta.url ?? cta.href, type: cta.type } : void 0;
+  return links.length > 0 || primary ? { ...links.length > 0 ? { links } : {}, ...primary ? { primary } : {} } : void 0;
+}
 function projectedGlobalNavigationLinks(value) {
-  const global = objectValue(value);
+  const global = objectValue2(value);
   if (!global) return [];
   const links = [];
   const visit = (entry) => {
@@ -3546,14 +3803,14 @@ function projectedGlobalNavigationLinks(value) {
       entry.forEach(visit);
       return;
     }
-    const item = objectValue(entry);
+    const item = objectValue2(entry);
     if (!item) return;
     const href = projectedHref(item.href);
     if (href) {
       const label = labelFor(item, "");
       if (label) links.push({ label, href });
     }
-    for (const key of ["tabs", "anchors", "dropdowns", "products", "versions", "languages", "menus"]) {
+    for (const key of ["tabs", "anchors", "dropdowns", "products", "versions", "languages", "menus", "menu"]) {
       if (Array.isArray(item[key])) visit(item[key]);
     }
   };
@@ -3561,19 +3818,19 @@ function projectedGlobalNavigationLinks(value) {
   return links;
 }
 function projectedFooter(value) {
-  const footer = objectValue(value);
+  const footer = objectValue2(value);
   if (!footer) return void 0;
-  const socials = objectValue(footer.socials);
+  const socials = objectValue2(footer.socials);
   const socialLinks = socials ? Object.fromEntries(Object.entries(socials).flatMap(([key, value2]) => {
     const href = projectedHref(value2);
     return href ? [[key, href]] : [];
   })) : void 0;
   const links = Array.isArray(footer.links) ? footer.links.flatMap((entry) => {
-    const column = objectValue(entry);
+    const column = objectValue2(entry);
     if (!column || !Array.isArray(column.items)) return [];
     const heading = typeof column.heading === "string" ? column.heading : typeof column.header === "string" ? column.header : "";
     const items = column.items.flatMap((item) => {
-      const link = objectValue(item);
+      const link = objectValue2(item);
       const href = projectedHref(link?.href);
       return link && typeof link.label === "string" && href ? [{ label: link.label, href }] : [];
     });
@@ -3583,26 +3840,45 @@ function projectedFooter(value) {
 }
 function projectedFont(value) {
   if (typeof value === "string" && value) return { family: value };
-  const font = objectValue(value);
+  const font = objectValue2(value);
   if (!font) return void 0;
   const family = typeof font.family === "string" ? font.family : typeof font.name === "string" ? font.name : void 0;
   if (!family) return void 0;
   const weight = Array.isArray(font.weight) ? font.weight.map(String) : Array.isArray(font.weights) ? font.weights.map(String) : void 0;
   return { family, ...weight && weight.length > 0 ? { weight } : {} };
 }
-function projectedCompatibleConfig(config) {
-  const banner = objectValue(config.banner);
-  const bannerContent = banner && (typeof banner.content === "string" || objectValue(banner.content)) ? banner.content : void 0;
+function projectedCompatibleConfig(config, warnings) {
+  const banner = objectValue2(config.banner);
+  const bannerContent = banner && (typeof banner.content === "string" || objectValue2(banner.content)) ? banner.content : void 0;
   const bannerType = banner && ["info", "warning", "critical"].includes(String(banner.type ?? banner.variant)) ? String(banner.type ?? banner.variant) : void 0;
-  const bannerColor = objectValue(banner?.color);
-  const bodyFont = projectedFont(objectValue(config.fonts)?.body ?? config.fonts);
-  const headingFont = projectedFont(objectValue(config.fonts)?.heading);
-  const feedback = objectValue(config.feedback);
-  const seo = objectValue(config.seo);
-  const iconLibrary = objectValue(config.icons)?.library;
+  const bannerColor = objectValue2(banner?.color);
+  const bodyFont = projectedFont(objectValue2(config.fonts)?.body ?? config.fonts);
+  const headingFont = projectedFont(objectValue2(config.fonts)?.heading);
+  const feedback = objectValue2(config.feedback);
+  const seo = objectValue2(config.seo);
+  const iconLibrary = objectValue2(config.icons)?.library;
   const projectedIconLibrary = ["lucide", "fontawesome", "tabler"].includes(String(iconLibrary)) ? String(iconLibrary) : void 0;
-  const navbar = projectedNavbar(config.navbar);
-  const globalLinks = projectedGlobalNavigationLinks(objectValue(config.navigation)?.global);
+  const docsNavbar = projectedNavbar(config.navbar);
+  const legacyRaw = legacyTopbarNavbar(config);
+  const legacyNavbar = projectedNavbar(legacyRaw);
+  const legacyLinkCount = Array.isArray(legacyRaw?.links) ? legacyRaw.links.length : 0;
+  if (legacyNavbar?.links && legacyNavbar.links.length < legacyLinkCount) {
+    warnings.push({ code: "unsupported-config", message: `${legacyLinkCount - legacyNavbar.links.length} mint.json topbarLinks entr${legacyLinkCount - legacyNavbar.links.length === 1 ? "y" : "ies"} without a valid name and url were skipped.` });
+  }
+  if (docsNavbar?.links && legacyNavbar?.links) {
+    warnings.push({ code: "unsupported-config", message: "Both docs.json navbar.links and mint.json topbarLinks are set; the docs.json navbar.links were used and topbarLinks ignored." });
+  }
+  if (docsNavbar?.primary && legacyNavbar?.primary) {
+    warnings.push({ code: "unsupported-config", message: "Both docs.json navbar.primary and mint.json topbarCtaButton are set; navbar.primary was used and topbarCtaButton ignored." });
+  }
+  if (legacyRaw?.primary && !legacyNavbar?.primary) {
+    warnings.push({ code: "unsupported-config", message: "mint.json topbarCtaButton has no valid url and was skipped." });
+  }
+  const navbar = docsNavbar || legacyNavbar ? {
+    ...docsNavbar?.links ?? legacyNavbar?.links ? { links: docsNavbar?.links ?? legacyNavbar?.links } : {},
+    ...docsNavbar?.primary ?? legacyNavbar?.primary ? { primary: docsNavbar?.primary ?? legacyNavbar?.primary } : {}
+  } : void 0;
+  const globalLinks = projectedGlobalNavigationLinks(objectValue2(config.navigation)?.global);
   const navbarLinks = [...new Map(
     [...navbar?.links ?? [], ...globalLinks].map((link) => [`${link.label}:${link.href}`, link])
   ).values()];
@@ -3669,11 +3945,11 @@ function isRedirectPathSafe(rawSource, rawDestination) {
   return true;
 }
 function mintlifyDefaultVersionPrefixes(config) {
-  const navigation = objectValue(config.navigation) ?? config;
+  const navigation = objectValue2(config.navigation) ?? config;
   const prefixes = /* @__PURE__ */ new Set();
   function collect(container) {
     if (Array.isArray(container.versions)) {
-      const entries = container.versions.map((value) => objectValue(value)).filter((value) => value !== null);
+      const entries = container.versions.map((value) => objectValue2(value)).filter((value) => value !== null);
       const defaultEntry = entries.find((entry) => entry.default === true) ?? entries[0];
       if (defaultEntry && typeof defaultEntry.version === "string" && defaultEntry.version.trim()) {
         prefixes.add(defaultEntry.version.trim());
@@ -3681,7 +3957,7 @@ function mintlifyDefaultVersionPrefixes(config) {
     }
     if (Array.isArray(container.languages)) {
       for (const value of container.languages) {
-        const language = objectValue(value);
+        const language = objectValue2(value);
         if (language) collect(language);
       }
     }
@@ -3690,18 +3966,18 @@ function mintlifyDefaultVersionPrefixes(config) {
   return prefixes;
 }
 function mintlifyAllVersionPrefixes(config) {
-  const navigation = objectValue(config.navigation) ?? config;
+  const navigation = objectValue2(config.navigation) ?? config;
   const prefixes = /* @__PURE__ */ new Set();
   function collect(container) {
     if (Array.isArray(container.versions)) {
       for (const value of container.versions) {
-        const entry = objectValue(value);
+        const entry = objectValue2(value);
         if (entry && typeof entry.version === "string" && entry.version.trim()) prefixes.add(entry.version.trim());
       }
     }
     if (Array.isArray(container.languages)) {
       for (const value of container.languages) {
-        const language = objectValue(value);
+        const language = objectValue2(value);
         if (language) collect(language);
       }
     }
@@ -3714,9 +3990,10 @@ function projectMintlifyNavigation(config, options = {}) {
   const references = [];
   const seenReferences = /* @__PURE__ */ new Set();
   const warningKeys = /* @__PURE__ */ new Set();
-  const navigation = objectValue(config.navigation) ?? config;
+  const gated = [];
+  const navigation = objectValue2(config.navigation) ?? config;
   const languages = Array.isArray(navigation.languages) ? navigation.languages.flatMap((value) => {
-    const language = objectValue(value);
+    const language = objectValue2(value);
     if (!language) return [];
     try {
       const code = Intl.getCanonicalLocales(String(language.language ?? language.locale ?? "en"))[0];
@@ -3753,7 +4030,8 @@ function projectMintlifyNavigation(config, options = {}) {
         references,
         seenReferences,
         warnings,
-        warningKeys
+        warningKeys,
+        gated
       };
       const languageTabs = convertContainerToTabs(
         language,
@@ -3770,7 +4048,7 @@ function projectMintlifyNavigation(config, options = {}) {
     }
     if (Object.keys(localizedNavigation).length > 0) i18n.navigation = localizedNavigation;
   } else {
-    const context = { references, seenReferences, warnings, warningKeys, pathPrefix: options.pathPrefix };
+    const context = { references, seenReferences, warnings, warningKeys, gated, pathPrefix: options.pathPrefix };
     tabs = convertContainerToTabs(navigation, context, "Documentation", projectionTrace);
     if (tabs.length === 0 && Array.isArray(config.navigation)) {
       const children = convertNavigationValues(config.navigation, context);
@@ -3790,7 +4068,7 @@ function projectMintlifyNavigation(config, options = {}) {
     });
   }
   const redirects = Array.isArray(config.redirects) ? config.redirects.flatMap((value) => {
-    const redirect = objectValue(value);
+    const redirect = objectValue2(value);
     if (!redirect || typeof redirect.source !== "string" || typeof redirect.destination !== "string") return [];
     const rawSource = redirect.source.trim();
     const rawDestination = redirect.destination.trim();
@@ -3809,15 +4087,17 @@ function projectMintlifyNavigation(config, options = {}) {
       ...typeof redirect.permanent === "boolean" ? { permanent: redirect.permanent } : {}
     }];
   }) : [];
+  collectGatedReferences(navigation, void 0, options.pathPrefix, gated);
   return {
     docsConfig: {
       tabs,
       ...projectionTrace.rootContainerKind === "dropdowns" ? { navigation: { display: "dropdown" } } : {},
-      ...projectedCompatibleConfig(config),
+      ...projectedCompatibleConfig(config, warnings),
       ...i18n ? { i18n } : {},
       ...redirects.length > 0 ? { redirects } : {}
     },
     pageReferences: references,
+    gatedReferences: gated,
     warnings
   };
 }
@@ -3923,7 +4203,7 @@ function buildNavigationFromPages(pages, options = {}) {
   return { tabs: [{ tab: "Documentation", groups }] };
 }
 function isDocumentationExtension(filename) {
-  return [".md", ".mdx", ".rst", ".txt"].includes(extname2(filename).toLowerCase());
+  return [".md", ".mdx", ".rst", ".txt"].includes(extname3(filename).toLowerCase());
 }
 function pruneMissingNavigationPages(config, availableIds) {
   const pruneNodes = (nodes) => {
@@ -3963,7 +4243,7 @@ var SIDEBAR_FILENAMES = [
   "sidebars.mjs",
   "sidebars.ts"
 ];
-function objectValue2(value) {
+function objectValue3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function stripNumberPrefix(value) {
@@ -4285,7 +4565,7 @@ function parseStaticSidebarModule(source) {
         literal
       );
       const parsed = JSON5.parse(substituted);
-      const object = objectValue2(parsed);
+      const object = objectValue3(parsed);
       if (!object) continue;
       const bindingName = candidate[0].match(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)/)?.[1];
       if (bindingName) {
@@ -4390,7 +4670,7 @@ function readDocusaurusSidebars(repositoryRoot, versionedSidebarPath) {
   if (!sourcePath) return null;
   const absolutePath = resolveWithin(repositoryRoot, sourcePath);
   const source = readBoundedText(absolutePath);
-  const parsed = extname3(sourcePath).toLowerCase() === ".json" ? objectValue2(JSON5.parse(source)) : parseStaticSidebarModule(source);
+  const parsed = extname4(sourcePath).toLowerCase() === ".json" ? objectValue3(JSON5.parse(source)) : parseStaticSidebarModule(source);
   if (!parsed) throw new Error("Docusaurus sidebar config must export an object.");
   return { config: parsed, sourcePath };
 }
@@ -4416,7 +4696,7 @@ function redirectEntriesFromObjectLiteralText(objectLiteral) {
   if (!Array.isArray(parsed)) return [];
   const entries = [];
   for (const raw of parsed) {
-    const entry = objectValue2(raw);
+    const entry = objectValue3(raw);
     if (!entry || typeof entry.to !== "string") continue;
     const froms = Array.isArray(entry.from) ? entry.from : [entry.from];
     for (const from of froms) {
@@ -4468,7 +4748,7 @@ function readCategoryMetadata(contentRoot, directory) {
     try {
       const raw = readBoundedText(path);
       const parsed = filename.endsWith(".json") ? JSON5.parse(raw) : parseYaml2(raw);
-      const object = objectValue2(parsed);
+      const object = objectValue3(parsed);
       if (!object) return {};
       return {
         ...typeof object.label === "string" ? { label: object.label } : {},
@@ -4502,7 +4782,7 @@ function registerDoc(docId, context) {
   return descriptor.navigationId;
 }
 function generatedIndexPage(label, linkValue, context) {
-  const link = objectValue2(linkValue);
+  const link = objectValue3(linkValue);
   if (!link) return null;
   if (link.type === "doc" && typeof link.id === "string") return registerDoc(link.id, context);
   if (link.type !== "generated-index") return null;
@@ -4769,7 +5049,7 @@ function convertItems(value, context) {
     return page ? [page] : [];
   }
   if (Array.isArray(value)) return value.flatMap((entry) => convertItems(entry, context));
-  const object = objectValue2(value);
+  const object = objectValue3(value);
   if (!object) return [];
   if (object.type === "doc" || object.type === "ref") {
     const page = typeof object.id === "string" ? registerDoc(object.id, context) : null;
@@ -4835,7 +5115,7 @@ function projectDocusaurusNavigation(input) {
 
 // src/fern.ts
 import { existsSync as existsSync4, lstatSync as lstatSync4, readFileSync as readFileSync4, readdirSync } from "fs";
-import { basename as basename2, dirname as dirname3, extname as extname4, relative as relative4 } from "path";
+import { basename as basename2, dirname as dirname3, extname as extname5, relative as relative4 } from "path";
 import { load } from "cheerio";
 import { parse as parseYaml3 } from "yaml";
 var MAX_CONFIG_BYTES2 = 2e7;
@@ -4865,7 +5145,7 @@ function announcementMarkdown(message) {
   for (const [marker, link] of links) text = text.replaceAll(marker, link);
   return text.trim();
 }
-function objectValue3(value) {
+function objectValue4(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function titleCase3(value) {
@@ -4881,7 +5161,7 @@ function readFernConfig(fernRoot) {
   const sourcePath = "docs.yml";
   const path = resolveWithin(fernRoot, sourcePath);
   if (!existsSync4(path) || !lstatSync4(path).isFile()) return null;
-  const config = objectValue3(readBoundedYaml(path));
+  const config = objectValue4(readBoundedYaml(path));
   if (!config) throw new Error("fern/docs.yml must contain an object.");
   return { config, sourcePath };
 }
@@ -4988,8 +5268,8 @@ function registerFolder(object, parentSegments, context) {
       if (entry.isDirectory()) {
         const nested = visit(path, [...routeSegments, fernBasicSlug(entry.name)], depth + 1);
         if (nested.length) pages2.push({ group: titleCase3(entry.name), pages: nested });
-      } else if (entry.isFile() && [".md", ".mdx"].includes(extname4(entry.name).toLowerCase())) {
-        const stem = basename2(entry.name, extname4(entry.name));
+      } else if (entry.isFile() && [".md", ".mdx"].includes(extname5(entry.name).toLowerCase())) {
+        const stem = basename2(entry.name, extname5(entry.name));
         const pageSegment = stem.toLowerCase() === "index" ? null : fernBasicSlug(stem);
         const route = [...routeSegments, ...pageSegment ? [pageSegment] : []].join("/");
         const source = lstatSync4(path).size <= MAX_CONFIG_BYTES2 ? readFileSync4(path, "utf8") : "";
@@ -5014,7 +5294,7 @@ function registerPage(object, parentSegments, context) {
   return registerPageAt(object.path, base, context, label, object.hidden === true) || null;
 }
 function convertNode(node, parentSegments, context) {
-  const object = objectValue3(node);
+  const object = objectValue4(node);
   if (!object) return null;
   if (typeof object.page === "string") {
     const page = registerPage(object, parentSegments, context);
@@ -5102,7 +5382,7 @@ function resolveVersionedNavigation(config, configDir, fernRoot, context) {
   }
   if (!Array.isArray(config.versions)) return config;
   const versions = config.versions.flatMap((entry) => {
-    const version = objectValue3(entry);
+    const version = objectValue4(entry);
     return version ? [version] : [];
   });
   const chosen = versions.find((version) => version.default === true) ?? versions[0];
@@ -5121,7 +5401,7 @@ function resolveVersionedNavigation(config, configDir, fernRoot, context) {
       warnOnce2(context, "fern-version-not-file", `Fern version file "${chosen.path}" is not a regular file and was skipped.`);
       return config;
     }
-    const versionConfig = objectValue3(readBoundedYaml(versionPath));
+    const versionConfig = objectValue4(readBoundedYaml(versionPath));
     if (!versionConfig) return config;
     context.pathPrefix = relative4(fernRoot, dirname3(versionPath)).replace(/\\/g, "/");
     return { ...config, navigation: versionConfig.navigation, tabs: versionConfig.tabs ?? config.tabs };
@@ -5136,13 +5416,13 @@ function resolveVersionedNavigation(config, configDir, fernRoot, context) {
 }
 function buildTabsFromConfig(rawConfig, configDir, fernRoot, routePrefix, fallbackTabLabel, context) {
   const config = resolveVersionedNavigation(rawConfig, configDir, fernRoot, context);
-  const tabsMeta = objectValue3(config.tabs) ?? {};
+  const tabsMeta = objectValue4(config.tabs) ?? {};
   const navigation = config.navigation;
-  const isTabbedNavigation = Array.isArray(navigation) && navigation.length > 0 && navigation.every((entry) => typeof objectValue3(entry)?.tab === "string");
+  const isTabbedNavigation = Array.isArray(navigation) && navigation.length > 0 && navigation.every((entry) => typeof objectValue4(entry)?.tab === "string");
   if (isTabbedNavigation) {
     return navigation.flatMap((entry) => {
       const id = String(entry.tab);
-      const meta = objectValue3(tabsMeta[id]) ?? {};
+      const meta = objectValue4(tabsMeta[id]) ?? {};
       const label = typeof meta["display-name"] === "string" ? meta["display-name"] : titleCase3(id);
       const tabSegment = segmentFor(meta, label, context);
       const segments = [...routePrefix, ...tabSegment ? [tabSegment] : []];
@@ -5164,7 +5444,7 @@ function buildTabsFromConfig(rawConfig, configDir, fernRoot, routePrefix, fallba
           const index = visiblePages.find((page) => {
             const descriptor = descriptors.get(page);
             if (!descriptor) return false;
-            const stem = basename2(descriptor.sourcePath, extname4(descriptor.sourcePath));
+            const stem = basename2(descriptor.sourcePath, extname5(descriptor.sourcePath));
             return page === indexRoute || stem === "overview" || stem === "index";
           });
           const entries = visiblePages.filter((page) => page !== index).sort((left, right) => {
@@ -5213,7 +5493,7 @@ function buildTabsFromConfig(rawConfig, configDir, fernRoot, routePrefix, fallba
 }
 function projectFernProducts(rawProducts, fernRoot, context) {
   return rawProducts.flatMap((entry) => {
-    const product = objectValue3(entry);
+    const product = objectValue4(entry);
     const rawPath = typeof product?.path === "string" ? product.path.trim() : "";
     if (!product || !rawPath) return [];
     const label = typeof product["display-name"] === "string" && product["display-name"].trim() ? product["display-name"].trim() : "Product";
@@ -5230,7 +5510,7 @@ function projectFernProducts(rawProducts, fernRoot, context) {
     }
     let productConfig;
     try {
-      productConfig = objectValue3(readBoundedYaml(productPath));
+      productConfig = objectValue4(readBoundedYaml(productPath));
     } catch (error) {
       warnOnce2(
         context,
@@ -5284,7 +5564,7 @@ function projectFernNavigation(input) {
     });
   }
   const navbarLinks = Array.isArray(config["navbar-links"]) ? config["navbar-links"].flatMap((entry) => {
-    const link = objectValue3(entry);
+    const link = objectValue4(entry);
     const href = typeof link?.url === "string" ? link.url : typeof link?.href === "string" ? link.href : typeof link?.value === "string" ? link.value : void 0;
     const label = typeof link?.text === "string" ? link.text : typeof link?.label === "string" ? link.label : link?.type === "github" ? "GitHub" : void 0;
     return href && label ? [{ label, href, ...link?.type === "github" ? { type: "github" } : {} }] : [];
@@ -5294,11 +5574,11 @@ function projectFernNavigation(input) {
       navbarLinks.push(link);
     }
   }
-  const announcement = objectValue3(config.announcement);
+  const announcement = objectValue4(config.announcement);
   const announcementMessage = typeof announcement?.message === "string" ? announcement.message.trim() : "";
   const bannerContent = announcementMarkdown(announcementMessage);
   const redirects = Array.isArray(config.redirects) ? config.redirects.flatMap((value) => {
-    const redirect = objectValue3(value);
+    const redirect = objectValue4(value);
     if (!redirect || typeof redirect.source !== "string" || typeof redirect.destination !== "string") return [];
     const rawSource = redirect.source.trim();
     const rawDestination = redirect.destination.trim();
@@ -5384,9 +5664,16 @@ function projectFernNavigation(input) {
 // src/repository.ts
 var MAX_SOURCE_FILES = 5e3;
 var MAX_PAGE_BYTES = 2e6;
+var FRONTMATTER_HEAD_BYTES = 65536;
+var MAX_WITHHELD_SCAN_BYTES = MAX_PAGE_BYTES * 8;
+var MAX_DROPPED_GATED_WARNINGS = 20;
 var MAX_ASSET_BYTES = 25e6;
 var MAX_TOTAL_ASSET_BYTES = 5e8;
 var GIT_LFS_POINTER_PREFIX = "version https://git-lfs.github.com/spec/v1";
+function listAssetPaths(paths) {
+  const shown = paths.slice(0, 5).join(", ");
+  return paths.length > 5 ? `${shown}, and ${paths.length - 5} more` : shown;
+}
 function isGitLfsPointer(content) {
   return content.length < 1024 && content.toString("utf8", 0, GIT_LFS_POINTER_PREFIX.length) === GIT_LFS_POINTER_PREFIX;
 }
@@ -5405,6 +5692,7 @@ var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
 function isIgnoredContentDirectory(name) {
   return name.startsWith(".") || name === "node_modules";
 }
+var QUARANTINE_DIRECTORY = "migration-quarantine";
 var ASSET_DIRECTORIES = /* @__PURE__ */ new Set(["assets", "images", "img", "media", "public", "static"]);
 var ASSET_EXTENSIONS = /* @__PURE__ */ new Set([
   ".avif",
@@ -5810,17 +6098,23 @@ function parseGitHubRepositoryUrl(rawUrl) {
 }
 var CLONE_RETRY_ATTEMPTS = 3;
 var CLONE_RETRY_DELAY_MS = 1e3;
-var DEFAULT_CLONE_TIMEOUT_MS = 10 * 6e4;
+var DEFAULT_CLONE_IDLE_TIMEOUT_MS = 2 * 6e4;
+var MAX_GIT_PROCESS_MS = 60 * 6e4;
+var HARD_TIMEOUT_REASON = `still running after ${MAX_GIT_PROCESS_MS / 6e4} minutes`;
+var GIT_EXIT_DRAIN_MS = 2e3;
 var RETRYABLE_CLONE_ERROR = /RPC failed|Recv failure|early EOF|curl \d+|Could not resolve host|Connection (?:reset|refused|timed out)|The remote end hung up|SSL[_ ]?(?:read|connect|write) error|timed out|network is unreachable/i;
 function delay(ms) {
   return new Promise((resolve3) => {
     setTimeout(resolve3, ms);
   });
 }
-function gitProcessTimeoutMs() {
+function gitIdleTimeoutMs() {
   const raw = process.env.THALLY_MIGRATE_CLONE_TIMEOUT_MS;
   const parsed = raw ? Number(raw) : NaN;
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLONE_TIMEOUT_MS;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLONE_IDLE_TIMEOUT_MS;
+}
+function gitErrorTail(stderr) {
+  return stderr.split(/[\r\n]+/).map((line) => line.trim()).filter((line) => line && !/^(?:remote: )?[A-Za-z][A-Za-z ]*:\s+\d+%/.test(line)).slice(-5).join("\n");
 }
 function runGit(args, options) {
   return new Promise((resolve3, reject) => {
@@ -5830,24 +6124,66 @@ function runGit(args, options) {
       env: { ...process.env, ...options.env }
     });
     let stderr = "";
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
+    let timeoutReason = "";
+    let settled = false;
+    let exitCode;
+    let drainTimer;
+    const idleMs = gitIdleTimeoutMs();
+    const idleMessage = `no progress for ${idleMs < 1e3 ? `${idleMs}ms` : `${Math.round(idleMs / 1e3)}s`}`;
+    const clearTimers = () => {
+      clearTimeout(idleTimer);
+      clearTimeout(hardTimer);
+      clearTimeout(drainTimer);
+    };
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      child.stderr.destroy();
+      if (code === 0) resolve3();
+      else if (timeoutReason) {
+        const hint = timeoutReason === HARD_TIMEOUT_REASON ? "" : "; on a very slow link, raise THALLY_MIGRATE_CLONE_TIMEOUT_MS (milliseconds of allowed silence)";
+        reject(new Error(`${options.label}: timed out (${timeoutReason}) and was killed. Check your network connection and try again${hint}.`));
+      } else reject(new Error(`${options.label}: ${gitErrorTail(stderr) || `git exited ${code}`}`));
+    };
+    const kill = (reason) => {
+      if (exitCode !== void 0) {
+        finish(exitCode);
+        return;
+      }
+      timeoutReason = reason;
       child.kill("SIGKILL");
-    }, gitProcessTimeoutMs());
+    };
+    let idleTimer = setTimeout(() => {
+      kill(idleMessage);
+    }, idleMs);
+    const hardTimer = setTimeout(() => {
+      kill(HARD_TIMEOUT_REASON);
+    }, MAX_GIT_PROCESS_MS);
     child.stderr.setEncoding("utf8");
     child.stderr.on("data", (chunk) => {
-      if (stderr.length < 16e3) stderr += chunk;
+      stderr = (stderr + chunk).slice(-16e3);
+      if (exitCode !== void 0 || settled) return;
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => {
+        kill(idleMessage);
+      }, idleMs);
     });
     child.on("error", (error) => {
-      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      clearTimers();
       reject(error);
     });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      if (code === 0) resolve3();
-      else if (timedOut) reject(new Error(`${options.label} timed out after ${gitProcessTimeoutMs()}ms and was killed.`));
-      else reject(new Error(`${options.label}: ${stderr.trim() || `git exited ${code}`}`));
+    child.on("close", finish);
+    child.on("exit", (code) => {
+      exitCode = code;
+      clearTimeout(idleTimer);
+      clearTimeout(hardTimer);
+      if (timeoutReason) finish(code);
+      else drainTimer = setTimeout(() => {
+        finish(code);
+      }, GIT_EXIT_DRAIN_MS);
     });
   });
 }
@@ -5863,7 +6199,7 @@ var LFS_FILTER_OVERRIDE_ENV = {
   GIT_CONFIG_VALUE_3: "false"
 };
 function cloneOnce(source, targetDir) {
-  const args = ["clone", "--depth", "1", "--single-branch"];
+  const args = ["clone", "--progress", "--depth", "1", "--single-branch"];
   if (source.branch !== "HEAD") args.push("--branch", source.branch);
   args.push("--", source.cloneUrl, targetDir);
   return runGit(args, {
@@ -5912,6 +6248,7 @@ async function initSubmodules(targetDir, warnings) {
         "submodule",
         "update",
         "--init",
+        "--progress",
         "--depth",
         "1",
         "--",
@@ -5971,7 +6308,7 @@ function containsMarkdown(directory, depth = 0) {
   for (const entry of readdirSync2(directory, { withFileTypes: true })) {
     if (isIgnoredDirectory(entry.name) || entry.isSymbolicLink()) continue;
     const path = resolveWithin(directory, entry.name);
-    if (entry.isFile() && [".md", ".mdx"].includes(extname5(entry.name).toLowerCase())) return true;
+    if (entry.isFile() && [".md", ".mdx"].includes(extname6(entry.name).toLowerCase())) return true;
     if (entry.isDirectory() && containsMarkdown(path, depth + 1)) return true;
   }
   return false;
@@ -5983,10 +6320,10 @@ function detectRepositoryDocsDir(repositoryDir) {
   }
   return "";
 }
-var MAX_RANKED_WALK_FILES = MAX_SOURCE_FILES * 20;
-function scanFiles(root, confinementRoot = root, warnings, rank) {
+var RANKED_WALK_FACTOR = 20;
+function scanFiles(root, confinementRoot = root, warnings, rank, budget = MAX_SOURCE_FILES) {
   const files = [];
-  const walkCap = rank ? MAX_RANKED_WALK_FILES : MAX_SOURCE_FILES;
+  const walkCap = rank ? budget * RANKED_WALK_FACTOR : budget;
   let confinementReal;
   try {
     confinementReal = realpathSync2(confinementRoot);
@@ -6056,10 +6393,10 @@ function scanFiles(root, confinementRoot = root, warnings, rank) {
   }
   return files;
 }
-function selectGroupWithinBudget(scanned, rank, warnings, allVersionPrefixes, label) {
-  if (scanned.length <= MAX_SOURCE_FILES) return scanned;
+function selectGroupWithinBudget(scanned, rank, warnings, allVersionPrefixes, label, budget = MAX_SOURCE_FILES) {
+  if (scanned.length <= budget) return scanned;
   const ranked = scanned.map((file) => ({ file, priority: rank(file.relativePath) })).sort((left, right) => left.priority - right.priority || (left.file.relativePath < right.file.relativePath ? -1 : left.file.relativePath > right.file.relativePath ? 1 : 0));
-  const dropped = ranked.slice(MAX_SOURCE_FILES).map(({ file }) => file);
+  const dropped = ranked.slice(budget).map(({ file }) => file);
   if (warnings) {
     const droppedPages = label === "file" ? dropped.filter((file) => isDocumentationExtension(file.relativePath)) : dropped;
     const noun = label === "file" ? "page" : "image or media file";
@@ -6072,18 +6409,18 @@ function selectGroupWithinBudget(scanned, rank, warnings, allVersionPrefixes, la
     const rest = droppedPages.length - examples.length;
     warnings.push({
       code: "limit-reached",
-      message: `This repository has more than ${MAX_SOURCE_FILES} ${label === "file" ? "files" : "assets"}, so only the first ${MAX_SOURCE_FILES} (in navigation order, default version first) were migrated. ${droppedPages.length} ${noun}(s) were left out` + (examples.length > 0 ? `: ${examples.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}` : "") + (droppedVersions.size > 0 ? ` (versions: ${[...droppedVersions].slice(0, 5).join(", ")}${droppedVersions.size > 5 ? `, and ${droppedVersions.size - 5} more` : ""})` : "") + (label === "file" ? ". To include them, run the migration on a smaller part of the repository with --docs-dir." : ". Copy them into public/ manually if your pages use them.")
+      message: `This repository has more than ${budget} ${label === "file" ? "files" : "assets"}, so only the first ${budget} (in navigation order, default version first) were migrated. ${droppedPages.length} ${noun}(s) were left out` + (examples.length > 0 ? `: ${examples.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}` : "") + (droppedVersions.size > 0 ? ` (versions: ${[...droppedVersions].slice(0, 5).join(", ")}${droppedVersions.size > 5 ? `, and ${droppedVersions.size - 5} more` : ""})` : "") + (label === "file" ? ". To include them, run the migration on a smaller part of the repository with --docs-dir." : ". Copy them into public/ manually if your pages use them.")
     });
   }
-  return ranked.slice(0, MAX_SOURCE_FILES).map(({ file }) => file);
+  return ranked.slice(0, budget).map(({ file }) => file);
 }
-function selectFilesWithinBudget(scanned, rank, warnings, allVersionPrefixes) {
-  const isAsset = (file) => ASSET_EXTENSIONS.has(extname5(file.relativePath).toLowerCase());
+function selectFilesWithinBudget(scanned, rank, warnings, allVersionPrefixes, budget = MAX_SOURCE_FILES) {
+  const isAsset = (file) => ASSET_EXTENSIONS.has(extname6(file.relativePath).toLowerCase());
   const assetFiles = scanned.filter(isAsset);
   const otherFiles = scanned.filter((file) => !isAsset(file));
   return [
-    ...selectGroupWithinBudget(otherFiles, rank, warnings, allVersionPrefixes, "file"),
-    ...selectGroupWithinBudget(assetFiles, rank, warnings, allVersionPrefixes, "asset")
+    ...selectGroupWithinBudget(otherFiles, rank, warnings, allVersionPrefixes, "file", budget),
+    ...selectGroupWithinBudget(assetFiles, rank, warnings, allVersionPrefixes, "asset", budget)
   ];
 }
 function readMintignoreMatcher(mintlifyRoot) {
@@ -6128,6 +6465,45 @@ function normalizedReferenceKey(value) {
 function exactReferenceKey(value) {
   return value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/").replace(/\.(?:mdx?|rst|txt)$/i, "");
 }
+function specRefMatches(ref, specPath, specFilename, isDefault) {
+  const prefix = /^(?:(\S+)\s+)?(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|WEBHOOK)\s/i.exec(`${ref} `)?.[1];
+  if (!prefix) return isDefault;
+  const wanted = prefix.replace(/^\/+/, "").toLowerCase();
+  const lowerPath = specPath.toLowerCase();
+  return lowerPath === wanted || lowerPath.endsWith(`/${wanted}`) || specFilename.toLowerCase() === wanted;
+}
+var TOKEN_SEPARATORS = /[\s"'()<>[\]{}=,;:|\\/`*!?#&]+/;
+var PATH_SEPARATORS = /[\s"'()<>[\]{}=,;:|\\`*!?#&]+/;
+function publicAssetKey(repoRelative) {
+  return repoRelative.split("/", 1)[0].toLowerCase() === "public" ? repoRelative.slice("public/".length) : repoRelative;
+}
+function addPathReferences(text, baseDir, exact, loose) {
+  for (const word of text.split(PATH_SEPARATORS)) {
+    let token = word.replace(/\.+$/, "");
+    if (!/\.[a-z0-9]{2,5}$/i.test(token) || token.startsWith("//")) continue;
+    if (token.includes("%")) {
+      try {
+        token = decodeURIComponent(token);
+      } catch {
+      }
+    }
+    if (!token.includes("/")) {
+      loose.add(token.toLowerCase());
+      continue;
+    }
+    if (!token.startsWith("/") && baseDir === void 0) continue;
+    const resolved = normalizeAssetPath(posix3.normalize(token.startsWith("/") ? token.slice(1) : posix3.join(baseDir ?? "", token)));
+    if (!resolved) continue;
+    const key = publicAssetKey(resolved);
+    exact.add(key);
+    loose.add(key.toLowerCase());
+  }
+}
+function looselyNamed(assetPath, loose) {
+  const lower = assetPath.toLowerCase();
+  const name = lower.split("/").pop() ?? lower;
+  return loose.has(lower) || loose.has(name) || loose.has(name.split(TOKEN_SEPARATORS).filter(Boolean).pop() ?? name);
+}
 function findOpenApi(files) {
   return files.find((file) => OPENAPI_FILENAMES.has(basename3(file.relativePath).toLowerCase()) && classifyApiSpec(file.absolutePath) === "openapi") ?? null;
 }
@@ -6149,6 +6525,13 @@ function classifyApiSpec(path) {
   if (!topLevel) return "unknown";
   return /asyncapi/i.test(topLevel) ? "asyncapi" : "openapi";
 }
+var SPEC_DIRECTORY = "openapi";
+function specAssetPath(filename) {
+  return `${SPEC_DIRECTORY}/${filename}`;
+}
+function specAsset(filename, content) {
+  return { path: specAssetPath(filename), content, projectRelative: true };
+}
 function mintlifyTopLevelApiReferences(config) {
   const api = config?.api && typeof config.api === "object" && !Array.isArray(config.api) ? config.api : null;
   if (!api) return [];
@@ -6169,7 +6552,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
   const seen = /* @__PURE__ */ new Set();
   const specs = [];
   for (const reference of references) {
-    const dedupeKey = `${reference.kind}:${reference.value}`;
+    const dedupeKey = `${reference.kind}:${reference.value}:${reference.tabLabel ?? ""}`;
     if (seen.has(dedupeKey)) continue;
     seen.add(dedupeKey);
     const tabSuffix = reference.tabLabel ? ` (tab "${reference.tabLabel}")` : "";
@@ -6181,7 +6564,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
       continue;
     }
     if (/^https:\/\//i.test(reference.value)) {
-      remoteSpecs.push({ url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {} });
+      remoteSpecs.push({ url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {} });
       warnings.push({
         code: "unsupported-config",
         message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} requires a network download before this import is complete.`,
@@ -6212,15 +6595,19 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
       filename: basename3(match.relativePath),
       content: readFileSync5(match.absolutePath),
       tabLabel: reference.tabLabel,
+      parentTab: reference.parentTab,
+      icon: reference.icon,
+      hidden: reference.hidden,
       sourcePath: match.relativePath,
       directory: reference.directory
     });
   }
   const filenameOwners = /* @__PURE__ */ new Map();
+  const filenameSources = /* @__PURE__ */ new Map();
   for (const spec of specs) {
     const groupKey = spec.tabLabel ?? "\0default";
     const owner = filenameOwners.get(spec.filename);
-    if (owner !== void 0 && owner !== groupKey) {
+    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}`;
@@ -6228,6 +6615,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
       spec.filename = disambiguated;
     }
     filenameOwners.set(spec.filename, groupKey);
+    filenameSources.set(spec.filename, spec.sourcePath);
   }
   return specs;
 }
@@ -6282,7 +6670,7 @@ function apiOperationLinkMap(sources, docsConfig) {
   const prefixLandings = /* @__PURE__ */ new Map();
   const apiTabs = docsConfig.tabs.filter((tab) => !tab.hidden && tab.api);
   apiTabs.forEach((tab, index) => {
-    const source = sources.find((entry) => tab.api?.source === `/${entry.filename}`);
+    const source = sources.find((entry) => tab.api?.source === specAssetPath(entry.filename));
     if (!source || !source.prefix) return;
     const specId = index === 0 ? "default" : slugifyApiSpecId(tab.tab);
     const prefix = source.prefix.replace(/^\/+|\/+$/g, "").toLowerCase();
@@ -6450,6 +6838,31 @@ function fernDefinitionExists(fernRoot, apiName) {
   }
   return candidateDirs.some((dir) => existsSync5(dir) && lstatSync5(dir).isDirectory());
 }
+function readFrontmatterHead(path) {
+  const fd = openSync(path, "r");
+  try {
+    const buffer = Buffer.alloc(FRONTMATTER_HEAD_BYTES);
+    const head = buffer.toString("utf8", 0, readSync(fd, buffer, 0, buffer.length, 0));
+    const opening = /^\uFEFF?---([^\r\n]*)\r?\n/.exec(head);
+    if (!opening || opening[1].startsWith("-")) return head;
+    return /^---[ \t]*\r?\n/m.test(head.slice(opening[0].length)) ? head : void 0;
+  } finally {
+    closeSync(fd);
+  }
+}
+function canonicalPath(path) {
+  try {
+    return realpathSync2.native(path);
+  } catch {
+    return path;
+  }
+}
+function pageHeadGateReason(raw) {
+  const parsed = parseFrontmatter(raw);
+  const unreadable = parsed.error && /^(groups|public)\s*:/m.test(raw.slice(0, raw.length - parsed.content.length)) ? "frontmatter could not be parsed and declares `groups` or `public`" : void 0;
+  const openapi = typeof parsed.data.openapi === "string" ? parsed.data.openapi.trim() : void 0;
+  return { reason: frontmatterGateReason(parsed.data) ?? unreadable, publicTrue: isPublicTrue(parsed.data.public), openapi };
+}
 function withoutFrontmatter(value) {
   return value.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trim();
 }
@@ -6584,7 +6997,7 @@ function fernSourceSiteUrl(config) {
 function externalizeMissingFernLinks(body, pageIds, sourceSiteUrl, externalized) {
   const rewrite = (target) => {
     const path = target.split(/[?#]/, 1)[0].replace(/^\//, "").replace(/\/$/, "");
-    if (!path || pageIds.has(path) || ASSET_EXTENSIONS.has(extname5(path).toLowerCase())) return target;
+    if (!path || pageIds.has(path) || ASSET_EXTENSIONS.has(extname6(path).toLowerCase())) return target;
     try {
       const base = new URL(`${sourceSiteUrl}/`);
       const sourceLinkUrl = new URL(target.slice(1), base);
@@ -6682,7 +7095,15 @@ function preserveLinkedAnchors(pages) {
       const key = comparable(cell.text);
       candidateIndexes.set(key, [...candidateIndexes.get(key) ?? [], { index: cell.index, kind: "table" }]);
     }
-    for (const heading of headings) existing.add(heading.text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, ""));
+    const headingSlugs = /* @__PURE__ */ new Map();
+    const slugCounts = /* @__PURE__ */ new Map();
+    for (const heading of headings) {
+      const slug2 = heading.text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+      existing.add(slug2);
+      const seen = slugCounts.get(slug2) ?? 0;
+      slugCounts.set(slug2, seen + 1);
+      if (slug2) headingSlugs.set(seen === 0 ? slug2 : `${slug2}-${seen}`, heading.index);
+    }
     const headingAliases = /* @__PURE__ */ new Map();
     const tableAliases = /* @__PURE__ */ new Map();
     for (const fragment of fragments) {
@@ -6696,6 +7117,14 @@ function preserveLinkedAnchors(pages) {
         const selections = linkIndexes.map((index2) => matches.filter((candidate) => candidate.index < index2).at(-1));
         if (selections.length && selections.every((candidate) => candidate?.index === selections[0]?.index)) match = selections[0];
       }
+      if (!match && matches.length > 1) {
+        const headingMatches = matches.filter((candidate) => candidate.kind === "heading");
+        if (headingMatches.length === 1) match = headingMatches[0];
+      }
+      if (!match) {
+        const index2 = headingSlugs.get(fragment.toLowerCase());
+        if (index2 !== void 0) match = { index: index2, kind: "heading" };
+      }
       if (!match) continue;
       const { index, kind } = match;
       const aliases = kind === "heading" ? headingAliases : tableAliases;
@@ -6762,8 +7191,13 @@ function globalSnippetAliases(files, repositoryRoot, siteRoot) {
     if (conventionalAlias) aliases.set(conventionalAlias, file.absolutePath);
   }
   for (const file of files) {
-    if (![".md", ".mdx"].includes(extname5(file.relativePath).toLowerCase())) continue;
-    const raw = readFileSync5(file.absolutePath, "utf8");
+    if (![".md", ".mdx"].includes(extname6(file.relativePath).toLowerCase())) continue;
+    let raw;
+    try {
+      raw = readFileSync5(file.absolutePath, "utf8");
+    } catch {
+      continue;
+    }
     for (const match of raw.matchAll(SNIPPET_IMPORT_PATTERN)) {
       try {
         const componentName = match[1] ?? match[2];
@@ -6790,7 +7224,7 @@ function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
   } catch {
     return null;
   }
-  if (!ASSET_EXTENSIONS.has(extname5(decodedPath).toLowerCase())) return null;
+  if (!ASSET_EXTENSIONS.has(extname6(decodedPath).toLowerCase())) return null;
   try {
     const candidate = decodedPath.startsWith("/") ? resolveWithin(siteRoot, decodedPath.replace(/^\/+/, "")) : resolveWithinRoot(dirname4(currentFile), decodedPath, siteRoot);
     const realRoot = realpathSync2(siteRoot);
@@ -6802,7 +7236,9 @@ function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
     if (!existsSync5(candidate) || !lstatSync5(candidate).isFile()) return null;
     const normalized = normalizeAssetPath(siteRelative);
     if (!normalized) return null;
-    onReferenced?.(normalized);
+    const onDiskRelative = relative5(realRoot, realpathSync2.native(candidate)).replace(/\\/g, "/");
+    const onDisk = onDiskRelative.toLowerCase() === siteRelative.toLowerCase() ? normalizeAssetPath(onDiskRelative) : null;
+    onReferenced?.(normalized, onDisk ?? void 0);
     const rewritten = `/${normalized}${suffix}`;
     return isBracketed ? `<${rewritten}>` : rewritten;
   } catch {
@@ -6847,18 +7283,47 @@ function locallyDeclaredNames(raw) {
   }
   return names;
 }
-function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0, siteRoot = repositoryRoot, globalAliases = /* @__PURE__ */ new Map()) {
+function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0, siteRoot = repositoryRoot, globalAliases = /* @__PURE__ */ new Map(), gate) {
   if (depth >= 8) return raw;
   raw = normalizeIndentedFences(raw);
   const snippets = /* @__PURE__ */ new Map();
   const preservedDeclarations = /* @__PURE__ */ new Map();
-  let withoutImports = replaceOutsideCode(raw, (source) => source.replace(
+  const source = relative5(repositoryRoot, currentFile).replace(/\\/g, "/");
+  const blockInline = (candidate, shownPath, label = shownPath) => {
+    const verdict = gate?.(candidate);
+    if (!verdict) return void 0;
+    const shown = shownPath.replace(/\*\//g, "* /");
+    if (verdict.kind === "gated") {
+      warnings.push({ code: "gated-page", message: `${label} is access-restricted and was NOT inlined; it was left as a comment.`, source });
+      return `{/* Access-restricted content withheld: ${shown} */}`;
+    }
+    if (verdict.kind === "snippet-gated") {
+      warnings.push({
+        code: "gated-page",
+        message: `${label} declares access rules (${verdict.reason}). Mintlify does not enforce groups on snippets, but it was NOT inlined to be safe; it was left as a comment.`,
+        source
+      });
+      return `{/* Access-restricted content withheld: ${shown} */}`;
+    }
+    warnings.push({
+      code: "skipped-file",
+      message: `${label} ${verdict.kind === "oversized" ? "is too large to inline (over 2 MB)" : "has frontmatter that could not be read"} and was NOT inlined; it was left as a comment.`,
+      source
+    });
+    return `{/* ${verdict.kind === "oversized" ? "Oversized" : "Unreadable"} content not inlined: ${shown} */}`;
+  };
+  let withoutImports = replaceOutsideCode(raw, (source2) => source2.replace(
     SNIPPET_IMPORT_PATTERN,
     (_statement, namedComponent, defaultComponent, sourcePath) => {
       const componentName = namedComponent ?? defaultComponent;
       try {
         const candidate = resolveSnippetPath(sourcePath, currentFile, repositoryRoot, siteRoot);
         if (!existsSync5(candidate) || !lstatSync5(candidate).isFile()) throw new Error("file not found");
+        const blocked = blockInline(candidate, sourcePath, `Imported ${sourcePath}`);
+        if (blocked) {
+          snippets.set(componentName, blocked);
+          return "";
+        }
         const nested = inlineMdxSnippets(
           withoutFrontmatter(readFileSync5(candidate, "utf8")),
           candidate,
@@ -6866,7 +7331,8 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
           warnings,
           depth + 1,
           siteRoot,
-          globalAliases
+          globalAliases,
+          gate
         );
         const declaration = statefulSnippetDeclaration(nested, componentName);
         if (declaration) preservedDeclarations.set(componentName, declaration);
@@ -6883,7 +7349,7 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
       }
     }
   ));
-  withoutImports = replaceOutsideCode(withoutImports, (source) => source.replace(
+  withoutImports = replaceOutsideCode(withoutImports, (source2) => source2.replace(
     SNIPPET_VALUE_IMPORT_PATTERN,
     (statement, names, sourcePath) => {
       const bindings = names.split(",").map((name) => name.trim()).filter(Boolean).map((name) => {
@@ -6893,7 +7359,16 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
       if (bindings.length === 0 || bindings.some((binding) => !binding)) return statement;
       try {
         const candidate = resolveSnippetPath(sourcePath, currentFile, repositoryRoot, siteRoot);
-        if (!existsSync5(candidate) || !lstatSync5(candidate).isFile()) return statement;
+        if (!existsSync5(candidate) || !lstatSync5(candidate).isFile() || gate?.(candidate)?.kind === "gated") return statement;
+        const blocked = blockInline(candidate, sourcePath);
+        if (blocked) {
+          const declarations2 = [];
+          for (const binding of bindings) {
+            if (/^[A-Z]/.test(binding.exported)) snippets.set(binding.local, blocked);
+            else declarations2.push(`export const ${binding.local} = undefined;`);
+          }
+          return declarations2.join("\n");
+        }
         const snippetSource = readFileSync5(candidate, "utf8");
         const values = staticNamedSnippetValues(snippetSource);
         const declarations = [];
@@ -6918,7 +7393,12 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
   ));
   const localNames = locallyDeclaredNames(withoutImports);
   for (const [componentName, candidate] of globalAliases) {
-    if (snippets.has(componentName) || localNames.has(componentName) || !new RegExp(`<${componentName}(?:\\s|/?>)`).test(withoutImports)) continue;
+    if (snippets.has(componentName) || localNames.has(componentName) || gate?.(candidate)?.kind === "gated" || !new RegExp(`<${componentName}(?:\\s|/?>)`).test(withoutImports)) continue;
+    const blocked = blockInline(candidate, relative5(repositoryRoot, candidate).replace(/\\/g, "/"));
+    if (blocked) {
+      snippets.set(componentName, blocked);
+      continue;
+    }
     const nested = inlineMdxSnippets(
       withoutFrontmatter(readFileSync5(candidate, "utf8")),
       candidate,
@@ -6926,7 +7406,8 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
       warnings,
       depth + 1,
       siteRoot,
-      globalAliases
+      globalAliases,
+      gate
     );
     const declaration = statefulSnippetDeclaration(nested, componentName);
     if (declaration) preservedDeclarations.set(componentName, declaration);
@@ -6954,6 +7435,8 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
         }
       }).find((path) => path !== void 0 && existsSync5(path) && lstatSync5(path).isFile());
       if (!candidate) throw new Error("file not found");
+      const blocked = blockInline(candidate, filePath, `Snippet file="${filePath}"`);
+      if (blocked) return blocked;
       return inlineMdxSnippets(
         withoutFrontmatter(readFileSync5(candidate, "utf8")),
         candidate,
@@ -6961,7 +7444,8 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
         warnings,
         depth + 1,
         siteRoot,
-        globalAliases
+        globalAliases,
+        gate
       );
     } catch {
       warnings.push({
@@ -6982,25 +7466,30 @@ ${result.slice(prefix.length)}`;
   return depth === 0 ? hoistMdxImports(result) : result;
 }
 function injectOpenApiSpecs(config, specs, warnings) {
-  let tabs = config.tabs.map((tab) => ({ ...tab }));
+  const tabs = config.tabs.map((tab) => ({ ...tab }));
   for (const spec of specs) {
     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) {
         warnings.push({
           code: "unsupported-config",
-          message: `Tab "${apiTab.tab}" already uses another OpenAPI spec, and Thally supports one API spec per tab, so "/${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 "${specAssetPath(spec.filename)}" was not added. Put it in its own tab to include it.`
         });
         continue;
       }
       apiTab.api = {
-        source: `/${spec.filename}`,
+        source: specAssetPath(spec.filename),
         // An API-only tab needs generated endpoint navigation; an authored
         // page tab keeps its own groups alongside the bound spec.
         ...apiTab.groups?.length || apiTab.pages?.length ? { navigation: false } : {}
       };
     } else {
-      tabs = [...tabs, { tab: spec.tabLabel ?? "API Reference", api: { source: `/${spec.filename}` } }];
+      insertApiTab(tabs, {
+        tab: spec.tabLabel ?? "API Reference",
+        ...spec.icon ? { icon: spec.icon } : {},
+        ...spec.hidden ? { hidden: true } : {},
+        api: { source: specAssetPath(spec.filename) }
+      }, spec.parentTab);
     }
   }
   return { ...config, tabs };
@@ -7048,6 +7537,7 @@ function migrateRepository(options) {
   const referenceOrder = /* @__PURE__ */ new Map();
   let docusaurusSidebars = null;
   let mintlifyConfig = null;
+  const mintlifyGatedRefs = /* @__PURE__ */ new Map();
   let fernRawConfig = null;
   let fernBasePath = "";
   let fernVersionPath = "";
@@ -7068,6 +7558,10 @@ function migrateRepository(options) {
         const projected = projectMintlifyNavigation(config);
         docsConfig = projected.docsConfig;
         warnings.push(...projected.warnings);
+        for (const gated of projected.gatedReferences) {
+          const gatedKey = normalizedReferenceKey(gated.ref).toLowerCase();
+          if (!mintlifyGatedRefs.has(gatedKey)) mintlifyGatedRefs.set(gatedKey, gated.reason);
+        }
         for (const [index, reference] of projected.pageReferences.entries()) {
           const key = normalizedReferenceKey(reference.ref);
           if (!referenceMap.has(key)) referenceMap.set(key, reference);
@@ -7153,10 +7647,11 @@ function migrateRepository(options) {
     const versionCeiling = lastReferencedIndexByVersionLocale.get(blockKey);
     return versionCeiling !== void 0 ? versionCeiling + 1 : Number.MAX_SAFE_INTEGER;
   } : void 0;
-  const scannedFiles = scanFiles(contentRoot, repositoryDir, warnings, discoveryRank);
+  const sourceBudget = options.maxSourceFiles ?? MAX_SOURCE_FILES;
+  const scannedFiles = scanFiles(contentRoot, repositoryDir, warnings, discoveryRank, sourceBudget);
   const mintignoreFilteredFiles = mintignoreMatcher ? scannedFiles.filter((file) => !mintignoreMatcher.ignores(file.relativePath)) : scannedFiles;
-  const discoveryBudgetApplied = discoveryRank !== void 0 && mintignoreFilteredFiles.length > MAX_SOURCE_FILES;
-  const files = discoveryRank ? selectFilesWithinBudget(mintignoreFilteredFiles, discoveryRank, warnings, allVersionPrefixes) : mintignoreFilteredFiles;
+  const discoveryBudgetApplied = discoveryRank !== void 0 && mintignoreFilteredFiles.length > sourceBudget;
+  const files = discoveryRank ? selectFilesWithinBudget(mintignoreFilteredFiles, discoveryRank, warnings, allVersionPrefixes, sourceBudget) : mintignoreFilteredFiles;
   if (platform === "fern" && fernProjectRoot) {
     const discovered2 = new Set(files.map((file) => file.relativePath));
     for (const sourcePath of fernExternalSourcePaths) {
@@ -7186,6 +7681,108 @@ function migrateRepository(options) {
   const docusaurusDescriptors = [];
   const docusaurusDocCardRoutes = /* @__PURE__ */ new Set();
   const seenPageIds = /* @__PURE__ */ new Set();
+  const quarantinedFiles = [];
+  const withheldAssetPaths = /* @__PURE__ */ new Set();
+  const publishedExact = /* @__PURE__ */ new Set();
+  const publishedLoose = /* @__PURE__ */ new Set();
+  const withholdAsset = (assetPath, onDiskSpelling) => {
+    withheldAssetPaths.add(publicAssetKey(onDiskSpelling ?? assetPath));
+  };
+  let sawPublicTrue = false;
+  const gateByPath = /* @__PURE__ */ new Map();
+  const withheldSpecRefs = [];
+  const publishedSpecRefs = [];
+  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()));
+  const classifyPageGate = (file) => {
+    let head = { publicTrue: false };
+    let unreadableGate;
+    try {
+      const size = lstatSync5(file.absolutePath).size;
+      const raw = readFrontmatterHead(file.absolutePath) ?? (size > MAX_PAGE_BYTES ? void 0 : readFileSync5(file.absolutePath, "utf8"));
+      if (raw === void 0) throw new Error("frontmatter is not terminated within the bounded read");
+      head = pageHeadGateReason(raw);
+    } catch {
+      unreadableGate = "frontmatter could not be read";
+    }
+    const reason = head.reason ?? unreadableGate ?? mintlifyGatedRefs.get(normalizedReferenceKey(file.relativePath).toLowerCase());
+    return { reason, publicTrue: head.publicTrue, openapi: head.openapi };
+  };
+  const keptFiles = new Set(files);
+  const droppedGatedFiles = [];
+  const withheldDocFiles = [];
+  let droppedPageCount = 0;
+  const scanTruncated = scannedFiles.length >= (discoveryRank ? sourceBudget * RANKED_WALK_FACTOR : sourceBudget);
+  if (platform === "mintlify") {
+    for (const file of files) {
+      if (isDocFile(file) && !isGateCandidate(file)) {
+        const snippetReason = classifyPageGate(file).reason;
+        if (snippetReason) withheldDocFiles.push(file);
+        continue;
+      }
+      if (!isGateCandidate(file)) continue;
+      const verdict = classifyPageGate(file);
+      gateByPath.set(file.absolutePath, { reason: verdict.reason, publicTrue: verdict.publicTrue });
+      if (verdict.openapi) (verdict.reason ? withheldSpecRefs : publishedSpecRefs).push(verdict.openapi);
+      if (verdict.reason) withheldPaths.add(file.absolutePath);
+    }
+    for (const file of mintignoreFilteredFiles) {
+      if (keptFiles.has(file) || !isDocFile(file)) continue;
+      droppedPageCount++;
+      if (!isGateCandidate(file)) {
+        const snippetReason = classifyPageGate(file).reason;
+        if (snippetReason) {
+          withheldDocFiles.push(file);
+          warnings.push({ code: "gated-page", message: `Access-restricted snippet (${snippetReason}) was dropped by the file limit; its assets were kept out of public/.`, source: file.relativePath });
+        }
+        continue;
+      }
+      const verdict = classifyPageGate(file);
+      if (!verdict.reason) continue;
+      if (verdict.openapi) withheldSpecRefs.push(verdict.openapi);
+      withheldPaths.add(file.absolutePath);
+      droppedGatedFiles.push({ file, reason: verdict.reason });
+    }
+    for (const file of scannedFiles) {
+      if (!mintignoreMatcher?.ignores(file.relativePath) || !isDocFile(file)) continue;
+      const verdict = classifyPageGate(file);
+      if (!verdict.reason) continue;
+      if (verdict.openapi) withheldSpecRefs.push(verdict.openapi);
+      withheldDocFiles.push(file);
+    }
+  }
+  const pagesNotClassified = droppedPageCount > 0 || platform === "mintlify" && scanTruncated;
+  const hasWithheldContent = withheldPaths.size > 0 || withheldDocFiles.length > 0;
+  const trackPublishedRefs = platform === "mintlify" && (hasWithheldContent || pagesNotClassified);
+  const withheldCanonical = new Set([...withheldPaths].map(canonicalPath));
+  const verdictCache = /* @__PURE__ */ new Map();
+  const classifyInlineCandidate = (candidate, key) => {
+    if (withheldCanonical.has(key)) return { kind: "gated", reason: "access-restricted" };
+    const shown = relative5(contentRoot, candidate).replace(/\\/g, "/");
+    const inSnippetDirectory = shown.split("/").some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase()));
+    let head;
+    try {
+      head = readFrontmatterHead(candidate);
+    } catch {
+      return { kind: "unreadable", reason: "could not be read" };
+    }
+    const gated = head === void 0 ? void 0 : pageHeadGateReason(head).reason;
+    if (gated) return { kind: inSnippetDirectory ? "snippet-gated" : "gated", reason: gated };
+    const navigationGated = inSnippetDirectory ? void 0 : mintlifyGatedRefs.get(normalizedReferenceKey(shown).toLowerCase());
+    if (navigationGated) return { kind: "gated", reason: navigationGated };
+    if (lstatSync5(candidate).size > MAX_PAGE_BYTES) return { kind: "oversized", reason: "over 2 MB" };
+    return head === void 0 ? { kind: "unreadable", reason: "frontmatter not terminated in the bounded read" } : void 0;
+  };
+  const inlineGate = platform === "mintlify" ? (candidate) => {
+    const key = canonicalPath(candidate);
+    let verdict = verdictCache.get(key);
+    if (verdict === void 0) {
+      verdict = classifyInlineCandidate(candidate, key) ?? null;
+      verdictCache.set(key, verdict);
+    }
+    return verdict ?? void 0;
+  } : void 0;
   const fernIdRenames = /* @__PURE__ */ new Map();
   let skipped = 0;
   let discovered = files.length;
@@ -7198,6 +7795,47 @@ function migrateRepository(options) {
     return leftOrder - rightOrder || left.relativePath.localeCompare(right.relativePath);
   });
   const snippetAliases = platform === "mintlify" && mintlifyProjectRoot ? globalSnippetAliases(files, repositoryDir, mintlifyProjectRoot) : /* @__PURE__ */ new Map();
+  droppedGatedFiles.forEach(({ file, reason }, index) => {
+    if (index < MAX_DROPPED_GATED_WARNINGS) {
+      warnings.push({
+        code: "gated-page",
+        message: `Access-restricted page (${reason}) was dropped by the file limit, so it was NOT published and was not saved under ${QUARANTINE_DIRECTORY}/; recover it from the source repository.`,
+        source: file.relativePath
+      });
+    }
+    if (!mintlifyProjectRoot) return;
+    try {
+      if (lstatSync5(file.absolutePath).size > MAX_WITHHELD_SCAN_BYTES) throw new Error("too large to scan");
+      rewriteRepositoryAssetLinks(
+        inlineMdxSnippets(readFileSync5(file.absolutePath, "utf8"), file.absolutePath, repositoryDir, [], 0, mintlifyProjectRoot, snippetAliases, inlineGate),
+        file.absolutePath,
+        mintlifyProjectRoot,
+        withholdAsset
+      );
+    } catch {
+    }
+  });
+  for (const file of withheldDocFiles) {
+    try {
+      if (!mintlifyProjectRoot) continue;
+      if (lstatSync5(file.absolutePath).size > MAX_WITHHELD_SCAN_BYTES) {
+        warnings.push({
+          code: "gated-page",
+          message: "Access-restricted file is too large to scan, so the assets it uses could not be checked and may have been copied to public/. Review them before publishing.",
+          source: file.relativePath
+        });
+        continue;
+      }
+      rewriteRepositoryAssetLinks(readFileSync5(file.absolutePath, "utf8"), file.absolutePath, mintlifyProjectRoot, withholdAsset);
+    } catch {
+    }
+  }
+  if (droppedGatedFiles.length > MAX_DROPPED_GATED_WARNINGS) {
+    warnings.push({
+      code: "gated-page",
+      message: `${droppedGatedFiles.length - MAX_DROPPED_GATED_WARNINGS} more access-restricted page(s) were dropped by the file limit and NOT published; recover them from the source repository.`
+    });
+  }
   for (const file of pageFiles) {
     if (!isDocumentationExtension(file.relativePath)) continue;
     if (platform === "fern" && !exactReferenceMap.has(exactReferenceKey(file.relativePath)) && !referenceMap.has(normalizedReferenceKey(file.relativePath))) {
@@ -7214,7 +7852,7 @@ function migrateRepository(options) {
       skipped++;
       continue;
     }
-    if (![".md", ".mdx"].includes(extname5(file.relativePath).toLowerCase())) {
+    if (![".md", ".mdx"].includes(extname6(file.relativePath).toLowerCase())) {
       skipped++;
       warnings.push({ code: "skipped-file", message: "Only Markdown and MDX are imported without an explicit converter.", source: file.relativePath });
       continue;
@@ -7223,9 +7861,64 @@ function migrateRepository(options) {
     if (size > MAX_PAGE_BYTES) {
       skipped++;
       warnings.push({ code: "skipped-file", message: "Page exceeded the 2 MB repository import limit.", source: file.relativePath });
+      const oversizedGate = gateByPath.get(file.absolutePath)?.reason;
+      if (oversizedGate) {
+        warnings.push({
+          code: "gated-page",
+          message: `Access-restricted page (${oversizedGate}) is too large to migrate (over 2 MB), so it was NOT published and was not saved under ${QUARANTINE_DIRECTORY}/; recover it from the source repository.`,
+          source: file.relativePath
+        });
+      }
+      if (oversizedGate && mintlifyProjectRoot) {
+        if (size > MAX_WITHHELD_SCAN_BYTES) {
+          warnings.push({
+            code: "gated-page",
+            message: "Access-restricted page is too large to scan, so the assets it uses could not be checked and may have been copied to public/. Review them before publishing.",
+            source: file.relativePath
+          });
+        } else {
+          rewriteRepositoryAssetLinks(readFileSync5(file.absolutePath, "utf8"), file.absolutePath, mintlifyProjectRoot, withholdAsset);
+        }
+      }
       continue;
     }
     const key = normalizedReferenceKey(file.relativePath);
+    if (platform === "mintlify") {
+      const gate = gateByPath.get(file.absolutePath);
+      if (gate?.publicTrue) sawPublicTrue = true;
+      const gateReason = gate?.reason;
+      if (gateReason) {
+        skipped++;
+        if (file.relativePath.split("/").some((segment) => segment === "..")) {
+          warnings.push({ code: "gated-page", message: `Access-restricted page (${gateReason}) was withheld from the site, but its path could not be preserved safely; recover it from the source repository.`, source: file.relativePath });
+          continue;
+        }
+        try {
+          if (mintlifyProjectRoot) {
+            rewriteRepositoryAssetLinks(
+              inlineMdxSnippets(readFileSync5(file.absolutePath, "utf8"), file.absolutePath, repositoryDir, [], 0, mintlifyProjectRoot, snippetAliases, inlineGate),
+              file.absolutePath,
+              mintlifyProjectRoot,
+              withholdAsset
+            );
+          }
+          quarantinedFiles.push({ path: `${QUARANTINE_DIRECTORY}/${file.relativePath}`, content: readFileSync5(file.absolutePath) });
+        } catch {
+          warnings.push({
+            code: "gated-page",
+            message: `Access-restricted page (${gateReason}) was NOT published, but it could not be read, so it was not copied to ${QUARANTINE_DIRECTORY}/; recover it from the source repository.`,
+            source: file.relativePath
+          });
+          continue;
+        }
+        warnings.push({
+          code: "gated-page",
+          message: `Access-restricted on the source site (${gateReason}), so it was NOT published. The original is saved at ${QUARANTINE_DIRECTORY}/${file.relativePath}; links from other pages to it will break.`,
+          source: file.relativePath
+        });
+        continue;
+      }
+    }
     const referenced = exactReferenceMap.get(exactReferenceKey(file.relativePath)) ?? referenceMap.get(key);
     let locale = referenced?.locale;
     let navigationId = referenced?.navigationId ?? pageIdFromReference(file.relativePath, platform === "mintlify");
@@ -7252,8 +7945,11 @@ function migrateRepository(options) {
       warnings,
       0,
       mintlifyProjectRoot ?? docusaurusProjectRoot ?? fernProjectRoot ?? repositoryDir,
-      snippetAliases
+      snippetAliases,
+      inlineGate
     );
+    const publishedText = trackPublishedRefs ? raw : void 0;
+    const pageAssetReferences = [];
     if (platform === "fern" || platform === "mintlify" || platform === "docusaurus") {
       raw = normalizeExplicitHeadingIds(raw);
     }
@@ -7345,8 +8041,8 @@ function migrateRepository(options) {
     }
     if (platform === "fern" && fernHiddenIds.has(navigationId)) page.hidden = true;
     if (platform === "mintlify" && mintlifyProjectRoot) {
-      page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, mintlifyProjectRoot, (assetPath) => {
-        addAssetReference(assetPath, file.relativePath);
+      page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, mintlifyProjectRoot, (assetPath, onDiskSpelling) => {
+        pageAssetReferences.push(publicAssetKey(onDiskSpelling ?? assetPath));
       });
     }
     if (platform === "fern" && fernProjectRoot) {
@@ -7410,6 +8106,8 @@ function migrateRepository(options) {
     }
     seenPageIds.add(page.id);
     pages.push(page);
+    for (const assetPath of pageAssetReferences) addAssetReference(assetPath, file.relativePath);
+    if (publishedText !== void 0) addPathReferences(publishedText, posix3.dirname(file.relativePath).replace(/^\.$/, ""), publishedExact, publishedLoose);
     if (hasDocusaurusDocCardList) {
       docusaurusDocCardRoutes.add(page.navigationId);
     }
@@ -7452,7 +8150,7 @@ function migrateRepository(options) {
         const withinFern = relative5(fernProjectRoot, absolutePath);
         const assetRelative = withinFern !== ".." && !withinFern.startsWith(`..${sep2}`) && !isAbsolute2(withinFern) ? withinFern : relative5(repositoryDir, absolutePath);
         const assetPath = normalizeAssetPath(assetRelative.replace(/\\/g, "/"));
-        if (!assetPath || !ASSET_EXTENSIONS.has(extname5(assetPath).toLowerCase())) return;
+        if (!assetPath || !ASSET_EXTENSIONS.has(extname6(assetPath).toLowerCase())) return;
         if (source) {
           fernBrandAssetPaths.set(source, assetPath);
           addAssetReference(assetPath, "fern/docs.yml");
@@ -7483,45 +8181,131 @@ function migrateRepository(options) {
     }));
   }) : [];
   const assetCandidates = [];
+  const mintlifyFonts = platform === "mintlify" ? mintlifyFontSources(mintlifyConfig) : [];
+  const fontRelativePaths = new Set(mintlifyFonts.flatMap((font) => font.path ? [font.path] : []));
+  const importedComponentSources = new Set((componentMigrator?.files() ?? []).flatMap((file) => {
+    const source = /^src\/mdx\/migrated\/[^/]+\/source\/(.+)$/.exec(file.path)?.[1];
+    return source ? [resolvePath(repositoryDir, source)] : [];
+  }));
+  const siteAssetPaths = /* @__PURE__ */ new Map();
+  const fontAssetByRelative = /* @__PURE__ */ new Map();
   for (const file of [...files, ...repositoryAssets, ...fernReferencedAssets]) {
     const firstSegment = file.relativePath.split("/", 1)[0].toLowerCase();
-    if (!ASSET_EXTENSIONS.has(extname5(file.relativePath).toLowerCase())) continue;
+    const siteKind = platform !== "mintlify" ? void 0 : fontRelativePaths.has(file.relativePath) ? "font" : isMintlifyServedScriptOrStyle(file.relativePath) && !importedComponentSources.has(file.absolutePath) ? extname6(file.relativePath).toLowerCase() === ".css" ? "style" : "script" : void 0;
+    if (!siteKind && !ASSET_EXTENSIONS.has(extname6(file.relativePath).toLowerCase())) continue;
     if (platform !== "mintlify" && !ASSET_DIRECTORIES.has(firstSegment) && !(platform === "fern" && referencedAssetPaths.has(file.relativePath))) continue;
     const isDocusaurusStatic = platform === "docusaurus" && firstSegment === "static";
     const assetPath = normalizeAssetPath(firstSegment === "public" ? file.relativePath.slice("public/".length) : isDocusaurusStatic ? file.relativePath.slice("static/".length) : file.relativePath);
     if (!assetPath) continue;
-    assetCandidates.push({ file, assetPath, size: lstatSync5(file.absolutePath).size });
+    if (siteKind) {
+      siteAssetPaths.set(assetPath, siteKind);
+      if (siteKind === "font") fontAssetByRelative.set(file.relativePath, assetPath);
+    }
+    const candidateSize = lstatSync5(file.absolutePath).size;
+    if (siteKind === "style" || siteKind === "script") {
+      if (trackPublishedRefs && candidateSize <= MAX_PAGE_BYTES) addPathReferences(readFileSync5(file.absolutePath, "utf8"), posix3.dirname(file.relativePath).replace(/^\.$/, ""), publishedExact, publishedLoose);
+    }
+    assetCandidates.push({ file, assetPath, size: candidateSize });
   }
   const isReferenced = (candidate) => referencedAssetPaths.has(candidate.assetPath);
   const orderedAssetCandidates = [
     ...assetCandidates.filter((candidate) => isReferenced(candidate)),
     ...assetCandidates.filter((candidate) => !isReferenced(candidate))
   ];
+  const quarantinedPageCount = quarantinedFiles.length;
+  const destinationCounts = /* @__PURE__ */ new Map();
+  for (const { assetPath } of assetCandidates) destinationCounts.set(assetPath, (destinationCounts.get(assetPath) ?? 0) + 1);
+  if (trackPublishedRefs) {
+    const publishedConfig = JSON.stringify(mintlifyConfig ?? {}, (_key, value) => value && typeof value === "object" && !Array.isArray(value) && navigationGateReason(value) ? void 0 : value);
+    addPathReferences(publishedConfig, "", publishedExact, publishedLoose);
+  }
+  for (const file of componentMigrator?.files() ?? []) {
+    if (!trackPublishedRefs || typeof file.content !== "string") continue;
+    const original = /^src\/mdx\/migrated\/[^/]+\/source\/(.+)$/.exec(file.path)?.[1];
+    addPathReferences(file.content, original === void 0 ? "" : posix3.dirname(original).replace(/^\.$/, ""), publishedExact, publishedLoose);
+  }
+  const failClosedAssets = trackPublishedRefs;
+  const isPublicReachable = (assetPath) => referencedAssetPaths.has(assetPath) || publishedExact.has(assetPath);
+  const isQuarantinedAsset = (assetPath) => (withheldAssetPaths.has(assetPath) || failClosedAssets && !siteAssetPaths.has(assetPath)) && platform === "mintlify" && !(isPublicReachable(assetPath) && !(failClosedAssets && (destinationCounts.get(assetPath) ?? 0) > 1));
+  let withheldAssetCount = 0;
+  let unreferencedAssetCount = 0;
   let totalAssetBytes = 0;
+  const overBudgetAssets = [];
+  let overBudgetReferenced = 0;
+  const lfsPointerAssets = [];
+  const ambiguouslyNamedAssets = [];
   for (const { file, assetPath, size } of orderedAssetCandidates) {
     if (size > MAX_ASSET_BYTES || totalAssetBytes + size > MAX_TOTAL_ASSET_BYTES) {
-      const referencingPages = referencedAssetPaths.get(assetPath);
-      warnings.push({
-        code: "limit-reached",
-        message: "This file was not copied because it is larger than 25 MB or the copied files would exceed 500 MB in total. Add it to public/ manually" + (referencingPages ? `; it is used by ${[...referencingPages].slice(0, 3).join(", ")}${referencingPages.size > 3 ? `, and ${referencingPages.size - 3} more` : ""}.` : "."),
-        source: file.relativePath
-      });
+      overBudgetAssets.push(file.relativePath);
+      if (referencedAssetPaths.has(assetPath)) overBudgetReferenced++;
       continue;
     }
     const content = readFileSync5(file.absolutePath);
     if (isGitLfsPointer(content)) {
-      warnings.push({
-        code: "unsupported-config",
-        message: "This asset is a Git LFS pointer, not its real content (Git LFS was skipped during clone because the host has no git-lfs binary). Install git-lfs and re-run the migration, or add the real file to public/ manually.",
-        source: file.relativePath
-      });
+      lfsPointerAssets.push(file.relativePath);
+      continue;
+    }
+    if (isQuarantinedAsset(assetPath)) {
+      quarantinedFiles.push({ path: `${QUARANTINE_DIRECTORY}/assets/${assetPath}`, content });
+      if (looselyNamed(assetPath, publishedLoose) || (destinationCounts.get(assetPath) ?? 0) > 1) ambiguouslyNamedAssets.push(assetPath);
+      if (withheldAssetPaths.has(assetPath)) withheldAssetCount++;
+      else unreferencedAssetCount++;
       continue;
     }
     assets.push({ path: assetPath, content });
     totalAssetBytes += size;
   }
-  if (!discoveryBudgetApplied && files.length >= MAX_SOURCE_FILES) {
-    warnings.push({ code: "limit-reached", message: `Stopped scanning after ${MAX_SOURCE_FILES} files, so the rest of the repository was not looked at. Run the migration on a smaller part of the repository with --docs-dir.` });
+  if (ambiguouslyNamedAssets.length > 0) {
+    warnings.push({
+      code: "gated-page",
+      message: `${ambiguouslyNamedAssets.length} asset(s) were kept out of public/ because a published page names a file like ${ambiguouslyNamedAssets.length === 1 ? "it" : "them"} in a way that does not give its folder (or differs in letter case), so it cannot be matched to one file (or two files share one public path): ${listAssetPaths(ambiguouslyNamedAssets)}. Copy any that published pages need from ${QUARANTINE_DIRECTORY}/assets/ into public/ by hand.`
+    });
+  }
+  if (platform === "mintlify") {
+    const copiedSite = assets.flatMap((asset) => siteAssetPaths.has(asset.path) ? [{ path: asset.path, kind: siteAssetPaths.get(asset.path) }] : []);
+    const scripts = copiedSite.filter((entry) => entry.kind === "script");
+    if (scripts.length > 0) {
+      docsConfig = {
+        ...docsConfig,
+        customScripts: [...docsConfig.customScripts ?? [], ...scripts.map((entry) => ({ src: `/${entry.path.split("/").map(encodeURIComponent).join("/")}`, strategy: "afterInteractive" }))]
+      };
+      warnings.push({
+        code: "unsupported-config",
+        message: `${scripts.length} script(s) from the content directory (${scripts.map((entry) => entry.path).join(", ")}) now load on every page via docs.json customScripts, as they did on Mintlify. They may target Mintlify's page structure; review them.`
+      });
+    }
+    for (const entry of copiedSite.filter((item) => item.kind === "style")) {
+      warnings.push({
+        code: "unsupported-config",
+        message: `Migration gap: custom stylesheet ${entry.path} is NOT applied. It was copied to public/${entry.path} but no page loads it, Thally cannot load a stylesheet from docs.json, and Mintlify-specific selectors will not match Thally's markup. Port the styles you need by hand into src/app/globals.css.`,
+        source: entry.path
+      });
+    }
+    for (const font of mintlifyFonts) {
+      const copiedPath = font.path ? fontAssetByRelative.get(font.path) : void 0;
+      const copied = copiedPath !== void 0 && assets.some((asset) => asset.path === copiedPath);
+      const detail = font.remote ? `its source ${font.source} is a remote URL and was not downloaded` : !font.path ? `its source ${font.source} is not a safe local .woff/.woff2/.ttf/.otf path inside the docs directory and was not imported` : !copiedPath ? `its source file ${font.source} was not found in the docs directory` : copied ? `its file was copied to public/${copiedPath}` : null;
+      if (detail === null) continue;
+      warnings.push({
+        code: "unsupported-config",
+        message: `Self-hosted font "${font.family}" is not applied: Thally's fonts setting loads Google Fonts by family only; ${detail}. The family name was still mapped, which loads a Google font of that name if one exists.`
+      });
+    }
+  }
+  if (overBudgetAssets.length > 0) {
+    warnings.push({
+      code: "limit-reached",
+      message: `${overBudgetAssets.length} asset file${overBudgetAssets.length === 1 ? " was" : "s were"} not copied because files over ${MAX_ASSET_BYTES / 1e6} MB, or beyond ${MAX_TOTAL_ASSET_BYTES / 1e6} MB in total, are skipped: ${listAssetPaths(overBudgetAssets)}. ` + (overBudgetReferenced > 0 ? `${overBudgetReferenced} of them ${overBudgetReferenced === 1 ? "is" : "are"} used by pages, so those images will be broken until you copy ${overBudgetAssets.length === 1 ? "it" : "them"}. ` : "") + `Copy ${overBudgetAssets.length === 1 ? "it" : "them"} into public/ manually.`
+    });
+  }
+  if (lfsPointerAssets.length > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      message: `${lfsPointerAssets.length} asset file${lfsPointerAssets.length === 1 ? " is a Git LFS pointer" : "s are Git LFS pointers"}, not real content, and ${lfsPointerAssets.length === 1 ? "was" : "were"} not copied (Git LFS was skipped during clone because the host has no git-lfs binary): ${listAssetPaths(lfsPointerAssets)}. Install git-lfs and re-run the migration, or copy the real files into public/ manually.`
+    });
+  }
+  if (!discoveryBudgetApplied && files.length >= sourceBudget) {
+    warnings.push({ code: "limit-reached", message: `Stopped scanning after ${sourceBudget} files, so the rest of the repository was not looked at. Run the migration on a smaller part of the repository with --docs-dir.` });
   }
   if (platform === "docusaurus") {
     const projected = projectDocusaurusNavigation({
@@ -7608,8 +8392,8 @@ function migrateRepository(options) {
         }
         specFilenameSources.set(filename, spec.absolutePath);
         const specContent = readFileSync5(spec.absolutePath);
-        if (!assets.some((asset) => asset.path === filename)) {
-          assets.push({ path: filename, content: specContent });
+        if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
+          assets.push(specAsset(filename, specContent));
         }
         resolvedSpecs.push({ filename, tabLabel: section.tabLabel, content: specContent, routeSegments: section.routeSegments ?? [] });
         continue;
@@ -7648,11 +8432,19 @@ function migrateRepository(options) {
       rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings);
     }
   } else if (platform === "mintlify") {
+    const warnSharedSpec = (path) => {
+      warnings.push({
+        code: "gated-page",
+        message: `OpenAPI spec ${path} is shared with access-restricted pages and is published; it may describe restricted endpoints. Review it before publishing.`,
+        source: path
+      });
+    };
     const resolvedSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs);
     for (const spec of resolvedSpecs) {
-      if (!assets.some((asset) => asset.path === spec.filename)) {
-        assets.push({ path: spec.filename, content: spec.content });
+      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);
     }
     if (resolvedSpecs.length > 0) {
       docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs, warnings);
@@ -7665,10 +8457,17 @@ function migrateRepository(options) {
       const fallback = findOpenApi(files);
       if (fallback) {
         const filename = basename3(fallback.relativePath);
-        if (!assets.some((asset) => asset.path === filename)) {
-          assets.push({ path: filename, content: readFileSync5(fallback.absolutePath) });
+        const matches = (ref) => specRefMatches(ref, fallback.relativePath, filename, true);
+        if (withheldSpecRefs.some(matches) && !publishedSpecRefs.some(matches)) {
+          quarantinedFiles.push({ path: `${QUARANTINE_DIRECTORY}/assets/${specAssetPath(filename)}`, content: readFileSync5(fallback.absolutePath) });
+          withheldAssetCount++;
+        } else {
+          if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
+            assets.push(specAsset(filename, readFileSync5(fallback.absolutePath)));
+          }
+          docsConfig = injectOpenApiSpecs(docsConfig, [{ filename }]);
+          if (withheldSpecRefs.some(matches)) warnSharedSpec(fallback.relativePath);
         }
-        docsConfig = injectOpenApiSpecs(docsConfig, [{ filename }]);
       }
     }
   }
@@ -7979,10 +8778,9 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     docsConfig = { ...docsConfig, navbar: { ...docsConfig.navbar, logo: null } };
   }
   if (mintlifyConfig) {
-    const appearance = mintlifyConfig.appearance && typeof mintlifyConfig.appearance === "object" ? mintlifyConfig.appearance : null;
-    const defaultMode = appearance?.default;
-    if (defaultMode === "light" || defaultMode === "dark" || defaultMode === "system") {
-      docsConfig = { ...docsConfig, appearance: { ...docsConfig.appearance, default: defaultMode } };
+    const appearance = mintlifyAppearance(mintlifyConfig, warnings);
+    if (Object.keys(appearance).length > 0) {
+      docsConfig = { ...docsConfig, appearance: { ...docsConfig.appearance, ...appearance } };
     }
     const background = mintlifyConfig.background && typeof mintlifyConfig.background === "object" ? mintlifyConfig.background : null;
     if (background) {
@@ -8015,6 +8813,25 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     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.`
   });
+  if (platform === "mintlify") {
+    docsConfig = { ...docsConfig, markdown: { enabled: true } };
+    if (quarantinedPageCount > 0 || withheldAssetCount > 0 || unreferencedAssetCount > 0) {
+      const assetNote = withheldAssetCount > 0 ? `${withheldAssetCount} file(s) used only by access-restricted pages were kept out of public/ and saved under ${QUARANTINE_DIRECTORY}/assets/. ` : "";
+      const unreferencedReason = [
+        ...hasWithheldContent ? ["this site has access-restricted content"] : [],
+        ...pagesNotClassified ? ["pages were dropped by the file limit (or the file scan stopped at its cap) and could not all be checked for access restrictions"] : []
+      ].join(" and ");
+      const unreferencedNote = unreferencedAssetCount > 0 ? `${unreferencedAssetCount} unreferenced asset(s) were kept out of public/ because ${unreferencedReason}; review ${QUARANTINE_DIRECTORY}/assets/ and copy any that published pages need. ` : "";
+      warnings.push({
+        code: "gated-page",
+        message: (quarantinedPageCount > 0 ? `${quarantinedPageCount} access-restricted page(s) were withheld from the published site and saved under ${QUARANTINE_DIRECTORY}/ (local only: git-ignored, never served or deployed). ` : "") + assetNote + unreferencedNote + "Assets that published pages also use are still copied to public/. Review them before deciding how to publish or protect that content."
+      });
+    }
+    warnings.push({
+      code: "gated-page",
+      message: (sawPublicTrue ? "Some pages set `public: true`, which means the source site used Mintlify authentication and every page WITHOUT it was private. " : "") + "Access control set in the Mintlify dashboard is not visible in the repository. Check the source site's dashboard access settings before publishing: Thally will publish ALL imported pages publicly. Confirm nothing here was meant to stay private before deploying."
+    });
+  }
   if (fernRawConfig?.logo && !logoLight && !logo.light) 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."
@@ -8027,6 +8844,8 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     assets,
     ...remoteApiSpecs.length > 0 ? { remoteApiSpecs } : {},
     ...componentMigrator ? { componentFiles: componentMigrator.files() } : {},
+    ...quarantinedFiles.length > 0 ? { quarantinedFiles } : {},
+    ...droppedGatedFiles.length > 0 ? { droppedGatedPages: droppedGatedFiles.length } : {},
     docsConfig,
     ...mintlifyConfig ? {
       site: {
@@ -8157,8 +8976,9 @@ function renderMigrationFiles(bundle, options = {}) {
       path: `src/content/${page.id}.mdx`,
       content: renderPage(bundle, page)
     })),
-    ...bundle.assets.map((asset) => ({ path: `public/${asset.path}`, content: asset.content })),
+    ...bundle.assets.map((asset) => ({ path: asset.projectRelative ? asset.path : `public/${asset.path}`, content: asset.content })),
     ...(bundle.componentFiles ?? []).flatMap((file) => file.path === "src/mdx/custom-components.tsx" && options.existingComponentRegistry !== void 0 && typeof file.content === "string" ? mergeComponentRegistry(options.existingComponentRegistry, file.content) : [file]),
+    ...bundle.quarantinedFiles ?? [],
     { path: "docs.json", content: `${JSON.stringify(config, null, 2)}
 ` }
   ];
@@ -9899,10 +10719,10 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
       const body = await downloadSpec(reference.url, fetcher);
       const operations = parseOpenApi(body, extension);
       const filename = `openapi-${createHash2("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
-      assets.push({ path: filename, content: body });
+      assets.push({ path: `openapi/${filename}`, content: body, projectRelative: true });
       const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
-      if (tab) tab.api = { source: `/${filename}` };
-      else tabs.push({ tab: reference.tabLabel ?? "API Reference", api: { source: `/${filename}` } });
+      if (tab) tab.api = { source: `openapi/${filename}` };
+      else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api: { source: `openapi/${filename}` } }, reference.parentTab);
       const routes = /* @__PURE__ */ new Map();
       for (const operation of operations) {
         const key = `${slug(operation.tag)}/${slug(operation.summary)}`;