From 1a360b4cbc5acc56ac97d8aef24d13d1e695d168 Mon Sep 17 00:00:00 2001
From: Tony Dou <ydou@microsoft.com>
Date: Fri, 31 Jul 2026 13:44:19 -0700
Subject: [PATCH] Document Context Cache preflight workaround

Add the temporary ARM template-level validation workaround to the customer guidance and apply it in the deployment helper.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 4436d4c4-59e7-4ea8-9a6a-84104db9d1ae
---
 README.md          | 12 ++++++++++++
 scripts/deploy.ps1 | 12 +++++++++++-
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d88dd88..6aef4d6 100644
--- a/README.md
+++ b/README.md
@@ -224,6 +224,17 @@ A pure CLI flow is also provided:
 ./scripts/deploy.ps1 -ResourceGroup rg-cc-demo -UseBicep           # Bicep
 ```
 
+The script uses ARM template-level validation as a temporary workaround for a
+private-preview preflight issue. If you deploy the template directly with Azure
+CLI, include the same validation setting:
+
+```powershell
+az deployment group create `
+  --resource-group rg-cc-demo `
+  --template-file azuredeploy.json `
+  --validation-level Template
+```
+
 ---
 
 ## Repository layout
@@ -257,6 +268,7 @@ A pure CLI flow is also provided:
 | `FeatureNotRegistered` on deploy | Run the three `az feature register` commands above and wait until each reports `Registered`. Email azurecontextcacherp@microsoft.com if state stays `Pending`. |
 | `LocationNotAvailableForResourceType` | Only `centralus` (launch) and `swedencentral` are supported today. |
 | `InvalidResourceName` | `namePrefix` must be 3–12 lowercase letters/digits. |
+| `The context cache container could not be found or accessed` during preflight validation | Deploy with `az deployment group create ... --validation-level Template`, or use `scripts/deploy.ps1`, which applies this temporary private-preview workaround automatically. |
 | Cache appears not to be used (no latency / cost improvement) | Confirm your prefix is **byte-identical** across requests, longer than a few hundred tokens, and that traffic is hitting the deployment created by this template (not a sibling deployment without `contextCacheContainerId`). |
 | Need to unlink the cache later | PUT the same deployment with `properties.contextCacheContainerId` omitted (keep `sku` and `model` identical). |
 
diff --git a/scripts/deploy.ps1 b/scripts/deploy.ps1
index 715bf17..e7daac4 100644
--- a/scripts/deploy.ps1
+++ b/scripts/deploy.ps1
@@ -24,7 +24,17 @@ if (-not (az group show --name $ResourceGroup 2>$null)) {
 
 $template = if ($UseBicep) { Join-Path $root 'bicep/main.bicep' } else { Join-Path $root 'azuredeploy.json' }
 
-$azArgs = @('deployment','group','create','--resource-group',$ResourceGroup,'--template-file',$template)
+$azArgs = @(
+    'deployment',
+    'group',
+    'create',
+    '--resource-group',
+    $ResourceGroup,
+    '--template-file',
+    $template,
+    '--validation-level',
+    'Template'
+)
 if ($NamePrefix) { $azArgs += @('--parameters',"namePrefix=$NamePrefix") }
 
 az @azArgs