From ec50855ba48565461f95bb03c227dc907a2b8a1b Mon Sep 17 00:00:00 2001
From: Rishabh Jain <v-rishabhja@microsoft.com>
Date: Tue, 11 Aug 2026 14:14:49 +0530
Subject: [PATCH 1/3] docs(terraform): document cloud-specific policy version
 differences

---
 .../terraform/howtos/modifyingPolicyAssets.md        | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/content/terraform/howtos/modifyingPolicyAssets.md b/docs/content/terraform/howtos/modifyingPolicyAssets.md
index b276c734..2a19e694 100644
--- a/docs/content/terraform/howtos/modifyingPolicyAssets.md
+++ b/docs/content/terraform/howtos/modifyingPolicyAssets.md
@@ -98,3 +98,15 @@ management_groups:
 ```
 
 Once you have done this, you can deploy the ALZ module, specifying the `architecture_name` variable to point to your custom architecture definition.
+
+## Cloud-specific policy versions
+
+{{< hint type=note >}}
+Built-in Azure Policy definitions and initiatives are not always available at the same version across all Azure clouds.
+
+For example, Azure Government may not have the same built-in policy or initiative versions that are available in Azure Commercial.
+{{< /hint >}}
+
+If your deployment requires a specific policy definition or initiative version that is unavailable in the target cloud, modifying policy assignments alone may not be sufficient.
+
+In these scenarios, use custom policy assets and archetype overrides to manage policy content and versioning explicitly within your custom library.

From c2a5f0fc515ccb0f125c9ac5310026e3190cf82f Mon Sep 17 00:00:00 2001
From: Rishabh Jain <v-rishabhja@microsoft.com>
Date: Tue, 11 Aug 2026 15:21:46 +0530
Subject: [PATCH 2/3] docs(terraform): document definitionVersion override
 limitation

---
 .../terraform/howtos/modifyingPolicyAssets.md        | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs/content/terraform/howtos/modifyingPolicyAssets.md b/docs/content/terraform/howtos/modifyingPolicyAssets.md
index 2a19e694..1a2e69a4 100644
--- a/docs/content/terraform/howtos/modifyingPolicyAssets.md
+++ b/docs/content/terraform/howtos/modifyingPolicyAssets.md
@@ -99,14 +99,12 @@ management_groups:
 
 Once you have done this, you can deploy the ALZ module, specifying the `architecture_name` variable to point to your custom architecture definition.
 
-## Cloud-specific policy versions
+## definitionVersion override limitation
 
-{{< hint type=note >}}
-Built-in Azure Policy definitions and initiatives are not always available at the same version across all Azure clouds.
+{{< hint type="warning" >}}
+The policy assignment override flow does not currently support `definitionVersion` overrides.
 
-For example, Azure Government may not have the same built-in policy or initiative versions that are available in Azure Commercial.
+Any `definitionVersion` value provided through `policy_assignments_to_modify` is ignored when policy assignment properties are generated.
 {{< /hint >}}
 
-If your deployment requires a specific policy definition or initiative version that is unavailable in the target cloud, modifying policy assignments alone may not be sufficient.
-
-In these scenarios, use custom policy assets and archetype overrides to manage policy content and versioning explicitly within your custom library.
+For cloud-specific version requirements, create a custom policy assignment asset in your custom library and replace the built-in assignment using an archetype override.

From e0713adf278037e2e35f76234f0172b2df72d832 Mon Sep 17 00:00:00 2001
From: Rishabh Jain <v-rishabhja@microsoft.com>
Date: Tue, 11 Aug 2026 15:32:53 +0530
Subject: [PATCH 3/3] docs(terraform): refine definitionVersion limitation
 guidance

---
 docs/content/terraform/howtos/modifyingPolicyAssets.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/content/terraform/howtos/modifyingPolicyAssets.md b/docs/content/terraform/howtos/modifyingPolicyAssets.md
index 1a2e69a4..0885f7a6 100644
--- a/docs/content/terraform/howtos/modifyingPolicyAssets.md
+++ b/docs/content/terraform/howtos/modifyingPolicyAssets.md
@@ -104,7 +104,7 @@ Once you have done this, you can deploy the ALZ module, specifying the `architec
 {{< hint type="warning" >}}
 The policy assignment override flow does not currently support `definitionVersion` overrides.
 
-Any `definitionVersion` value provided through `policy_assignments_to_modify` is ignored when policy assignment properties are generated.
+If a specific `definitionVersion` is required, create a custom policy assignment asset in your custom library and replace the built-in assignment using an archetype override.
 {{< /hint >}}
 
 For cloud-specific version requirements, create a custom policy assignment asset in your custom library and replace the built-in assignment using an archetype override.