diff --git a/automation/source-repo-templates/api-docs.dotnet.yml b/automation/source-repo-templates/api-docs.dotnet.yml
index bde56ae2..34c17b99 100644
--- a/automation/source-repo-templates/api-docs.dotnet.yml
+++ b/automation/source-repo-templates/api-docs.dotnet.yml
@@ -152,9 +152,15 @@ jobs:
           fi
 
       - name: Write top-level index
-        # xmldocmd emits one tree per assembly. Assemble a small
-        # README.md at the top of the api/ folder linking to each
-        # so a single nav entry can drive into all packages.
+        # DefaultDocumentation emits one tree per assembly. Assemble
+        # a small README.mdx at the top of the api/ folder linking
+        # to each so a single nav entry can drive into all packages.
+        # Emit .mdx (not .md) because Mintlify's docs.json nav
+        # resolver only matches .mdx for page ids; without this,
+        # mint dev warns "is referenced in the docs.json navigation
+        # but the file does not exist". Submodule pages stay .md
+        # since they are linked from content (where both extensions
+        # resolve) rather than from nav.
         run: |
           {
             echo "# ResQ .NET SDK"
@@ -169,7 +175,7 @@ jobs:
                 echo "- [$proj]($proj/$proj)"
               fi
             done
-          } > "$OUTPUT_DIR/README.md"
+          } > "$OUTPUT_DIR/README.mdx"
 
       - name: Prefix bare-filename intra-page links with ./
         # Same pattern as the TypeScript template: Mintlify rejects
diff --git a/automation/source-repo-templates/api-docs.python.yml b/automation/source-repo-templates/api-docs.python.yml
index 04d79c08..91757c6b 100644
--- a/automation/source-repo-templates/api-docs.python.yml
+++ b/automation/source-repo-templates/api-docs.python.yml
@@ -195,11 +195,17 @@ jobs:
 
       - name: Write top-level index
         # pydoc-markdown emits an overview.md per package. Stitch a
-        # small README.md at the top of the api/ folder linking to
+        # small README.mdx at the top of the api/ folder linking to
         # each so a single nav entry can drive into all packages.
         # Package list is sorted alphabetically by directory name so
         # it stays in sync with `_pages.json` (which `find ... | sort`
         # produces below) regardless of PUBLIC_PACKAGES env order.
+        # Emit .mdx (not .md) because Mintlify's docs.json nav
+        # resolver only matches .mdx for page ids; without this,
+        # mint dev warns "is referenced in the docs.json navigation
+        # but the file does not exist". Submodule pages stay .md
+        # since they are linked from content (where both extensions
+        # resolve) rather than from nav.
         run: |
           {
             echo "# ResQ Python SDK"
@@ -216,7 +222,7 @@ jobs:
                 echo "- [\`$pkg_dir\`]($pkg_dir/overview)"
               fi
             done
-          } > "$OUTPUT_DIR/README.md"
+          } > "$OUTPUT_DIR/README.mdx"
 
       - name: Prefix bare-filename intra-page links with ./
         # Mintlify rejects bare-filename .md links as broken;
diff --git a/automation/source-repo-templates/api-docs.typescript.yml b/automation/source-repo-templates/api-docs.typescript.yml
index f17b760a..b9b62d27 100644
--- a/automation/source-repo-templates/api-docs.typescript.yml
+++ b/automation/source-repo-templates/api-docs.typescript.yml
@@ -202,8 +202,7 @@ jobs:
         # Flat JSON array of generated Markdown paths (without
         # extension) so the docs repo can later splice them into
         # docs.json automatically. Mintlify resolves both .md and
-        # .mdx, and typedoc-plugin-markdown emits .md by default,
-        # so we keep the .md output and skip a rename step.
+        # .mdx for in-content links, so submodule files stay .md.
         working-directory: ${{ env.PKG_DIR }}/generated-docs
         run: |
           find . -name '*.md' -type f \
@@ -212,6 +211,21 @@ jobs:
           jq -R -s 'split("\n") | map(select(length > 0))' _pages.txt > _pages.json
           rm _pages.txt
 
+      - name: Rename top-level README -> .mdx (Mintlify nav)
+        # Mintlify's docs.json nav resolver only matches .mdx for
+        # page ids. Without this rename, mint dev warns:
+        #   "sdks/typescript/api/README" is referenced in the
+        #   docs.json navigation but the file does not exist.
+        # Scope is intentionally limited to the top-level entry
+        # file: in-content links to submodule .md files keep
+        # working as Mintlify treats those as page references and
+        # resolves them on-disk regardless of extension.
+        working-directory: ${{ env.PKG_DIR }}/generated-docs
+        run: |
+          if [ -f README.md ]; then
+            mv README.md README.mdx
+          fi
+
       - name: Checkout docs repo
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with: