Update from support feedback: custom domain lifecycle limitations

customize/custom-domain.mdx

@@ -118,6 +118,38 @@
 
 Only retry validation after you confirm that your DNS records are correct. Repeated retries with incorrect records do not speed up validation.
 
+## Limitations and lifecycle
+
+Custom domains have a few lifecycle constraints that are not obvious during setup. Review these before you migrate a production site.
+
+### The default `.mintlify.site` subdomain is permanent
+
+The `<subdomain>.mintlify.site` URL is assigned when the deployment is first created and cannot be changed later. Renaming your project or organization only updates the display name in the dashboard; it does not rename the URL.
+
+If you push to a deployment whose display name no longer matches the original subdomain, requests to preview URLs can return a `Disallowed origin host` error until the site rebuilds against the original subdomain.
+
+To change the `.mintlify.site` subdomain, you must:
+
+1. Back up any content and settings you want to keep. Deleting a deployment removes everything associated with it.
+2. Delete the deployment from the [Danger zone](https://app.mintlify.com/settings/organization/danger-zone). See [Delete a deployment](/deploy/deployments#delete-a-deployment).
+3. Create a new deployment and enter the desired name during setup.
+
+### The default subdomain stays live after adding a custom domain
+
+Once a custom domain is verified, your documentation is served from both the custom domain and the original `<subdomain>.mintlify.site` URL. The default subdomain cannot currently be disabled, and there is no automatic redirect from it to your custom domain.
+
+To consolidate on the custom domain in search results, set a [canonical URL](#set-a-canonical-url) so search engines index the custom domain as the primary version.
+
+### One primary custom domain per project
+
+Mintlify serves each documentation project from a single primary custom domain. Pointing multiple hostnames (for example, `developers.example.com` and `docs.example.com`) at the same project through the dashboard is not supported.
+
+If you need multiple hostnames or multiple projects under one domain, choose the option that fits your setup:
+
+- **Multiple hostnames for one project**: Configure a self-managed reverse proxy (for example, Cloudflare Workers) in front of Mintlify so each hostname rewrites to the primary custom domain. See [Reverse proxy](/deploy/reverse-proxy).
+- **Multiple projects under one domain as subpaths**: Use a [multi-repository deployment](/deploy/multi-repo) to combine several repositories into one site with dedicated URL paths. Multi-repository deployments are available on Enterprise plans.
+- **Docs under a subpath of an existing site**: See [Host docs at a /docs subpath](/deploy/docs-subpath).
+
 ## Set a canonical URL
 
 After configuring your DNS, set a canonical URL to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content.

deploy/deployments.mdx

@@ -30,6 +30,10 @@ If you have the GitHub App installed, but changes are still not deploying, manua
 
 You can permanently delete a deployment from the [Danger zone](https://app.mintlify.com/settings/organization/danger-zone) in your dashboard settings. This action is irreversible and removes all deployment data, including any associated preview deployments.
 
+<Note>
+  Deleting and recreating a deployment is currently the only way to change the `<subdomain>.mintlify.site` URL assigned at creation. See [Limitations and lifecycle](/customize/custom-domain#limitations-and-lifecycle) for details.
+</Note>
+
 <Steps>
   <Step title="Navigate to the Danger zone.">
     Go to the [Danger zone](https://app.mintlify.com/settings/organization/danger-zone) in the settings page of your dashboard.

deploy/multi-repo.mdx

@@ -5,7 +5,7 @@ keywords: ["multi-repo", "multiple repositories", "git sources", "URL path"]
 ---
 
 <Info>
-  Multi-repository deployments are available on [Enterprise plans](https://mintlify.com/pricing?ref=multi-repo).
+  Multi-repository deployments are available on [Enterprise plans](https://mintlify.com/pricing?ref=multi-repo). For other multi-domain and multi-project routing options, see [Limitations and lifecycle](/customize/custom-domain#limitations-and-lifecycle).
 </Info>
 
 Use a multi-repository deployment when one site needs content from more than one Git repository. When you configure multiple repositories as sources for the same Mintlify project, content from each repository has its own URL path.

deploy/reverse-proxy.mdx

@@ -8,6 +8,10 @@
 
 When you implement a reverse proxy, monitor for potential issues with domain verification, SSL certificate provisioning, authentication flows, performance, and analytics tracking.
 
+<Info>
+  Mintlify serves each project from a single primary custom domain. To route additional hostnames to the same documentation, or to combine multiple projects under one domain, see [Limitations and lifecycle](/customize/custom-domain#limitations-and-lifecycle).
+</Info>
+
 ## Choose your deployment approach
 
 Mintlify supports two reverse proxy configurations depending on your subpath requirements.