[docs] Document WithUniqueResourceNaming for Azure Container App environments

src/frontend/config/sidebar/reference.topics.ts

@@ -716,6 +716,10 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
               link: '/diagnostics/aspireacadomains001',
             },
             { label: 'ASPIRECOMPUTE001', link: '/diagnostics/aspirecompute001' },
+            {
+              label: 'ASPIREACANAMING002',
+              link: '/diagnostics/aspireacanaming002',
+            },
             {
               label: 'ASPIRECSHARPAPPS001',
               link: '/diagnostics/aspirecsharpapps001',

src/frontend/src/content/docs/diagnostics/aspireacanaming002.mdx

@@ -0,0 +1,50 @@
+---
+title: Compiler Error ASPIREACANAMING002
+seoTitle: "ASPIREACANAMING002: WithUniqueResourceNaming is for evaluation"
+description: Learn what causes the Aspire compiler error ASPIREACANAMING002 and how to fix it so your AppHost builds cleanly.
+---
+
+import { Badge } from '@astrojs/starlight/components';
+
+<Badge
+  text="Version introduced: 13.5"
+  variant="note"
+  size="large"
+  class:list={'mb-1'}
+/>
+
+> WithUniqueResourceNaming is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+
+## Example
+
+The following code generates `ASPIREACANAMING002`:
+
+```csharp title="AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+var env1 = builder.AddAzureContainerAppEnvironment("cae1")
+    .WithUniqueResourceNaming();
+```
+
+## To correct this error
+
+Suppress the error with either of the following methods:
+
+- Set the severity of the rule in the _.editorconfig_ file.
+
+  ```ini title=".editorconfig"
+  [*.{cs,vb}]
+  dotnet_diagnostic.ASPIREACANAMING002.severity = none
+  ```
+
+  For more information about editor config files, see [Configuration files for code analysis rules](/diagnostics/overview/#suppress-in-the-editorconfig-file).
+
+- Add the following `PropertyGroup` to your project file:
+
+  ```xml title="C# project file"
+  <PropertyGroup>
+      <NoWarn>$(NoWarn);ASPIREACANAMING002</NoWarn>
+  </PropertyGroup>
+  ```
+
+- Suppress in code with the `#pragma warning disable ASPIREACANAMING002` directive.

src/frontend/src/content/docs/integrations/cloud/azure/configure-container-apps.mdx

@@ -393,6 +393,38 @@ await acaEnv.withAzdResourceNaming();
 
 Calling this API ensures your existing Azure resources remain consistent and prevents duplication.
 
+## Avoid managed environment name collisions
+
+By default, the generated managed environment `name` keeps only lowercase letters from the resource name, so `AddAzureContainerAppEnvironment("cae1")` and `AddAzureContainerAppEnvironment("cae2")` both produce the same Bicep expression once digits are stripped. If you deploy both environments to the *same resource group*, they collapse onto a single physical Azure Container Apps environment and concurrent deployments can fail with `ManagedEnvironmentOperationInProgress`.
+
+Publish and deploy detect this collision up front and fail with guidance to call `WithUniqueResourceNaming` on the colliding environments:
+
+<Tabs syncKey="aspire-lang">
+<TabItem id="csharp" label="C#">
+```csharp title="AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+var env1 = builder.AddAzureContainerAppEnvironment("cae1")
+    .WithUniqueResourceNaming();
+
+var env2 = builder.AddAzureContainerAppEnvironment("cae2")
+    .WithUniqueResourceNaming();
+
+// Omitted for brevity...
+
+builder.Build().Run();
+```
+</TabItem>
+</Tabs>
+
+`WithUniqueResourceNaming` preserves digits in the resource name when computing the managed environment `name`, so `cae1` and `cae2` produce distinct names and can coexist in the same resource group.
+
+<Aside type="caution">
+  This method is marked with `[Experimental("ASPIREACANAMING002")]` and changes the managed environment `name` for the environment it's applied to. Applying it to an *already-deployed* single environment changes its name, which causes Azure to recreate the resource. Apply it only when deploying more than one environment to a single resource group, or to new deployments. For more information, see [ASPIREACANAMING002](/diagnostics/aspireacanaming002/).
+</Aside>
+
+`WithUniqueResourceNaming` acts as a fallback after any name resolver you configure explicitly through `AzureProvisioningOptions.ProvisioningBuildOptions`, and it has no effect when `WithAzdResourceNaming` is used, since `azd` naming sets the environment name explicitly.
+
 ## Customize provisioning infrastructure
 
 All Azure resources are subclasses of the `AzureProvisioningResource` type. This enables customization of the generated Bicep by providing a fluent API to configure the Azure resources — using the `ConfigureInfrastructure` API: