fix: address Copilot PR review feedback

Resolves 12 inline comments from Copilot reviewer on PR #1009:

setup_local_dev.sh:
* Add Bash 4+ requirement check at top (macOS ships 3.2 — `declare -A`
  is not available there). Fail with actionable Homebrew install hint.
* Remove silent fallback to Python <3.12 in interpreter detection; rely on
  check_prerequisites to fail loudly when 3.12+ is missing.
* Make generated .vscode/settings.json `python.defaultInterpreterPath`
  OS-aware (bin/python on Linux/macOS, Scripts/python.exe on Windows).

setup_local_dev.ps1:
* Add `#Requires -Version 7.0` plus runtime guard — `??` and
  `Out-File -Encoding utf8NoBOM` aren't supported on Windows PowerShell 5.1.
* Remember the detected Python invocation (e.g., `py -3.12`) and reuse it
  when creating the frontend venv, instead of unconditionally calling
  `python -m venv` (which fails when `python` isn't on PATH).

deploy_to_azure.sh:
* Fix az_retry comment to say "up to 4 attempts" to match the loop bound.
* Correct step header in update_azure_resources from "Step 7" to "Step 8"
  so log output matches docs/section structure.
* Add `_has_az_executable` helper using `type -P az` so the prereq check
  isn't satisfied by the `az()` wrapper function defined earlier in the
  script when the real Azure CLI isn't installed.

deploy_to_azure.ps1:
* In Configure-AcrOnResources, capture exit code of BOTH frontend
  `az webapp config` calls. Previously only the second was checked, so a
  failure to set DOCKER_REGISTRY_SERVER_URL could be silently masked by
  a successful acrUseManagedIdentityCreds update.

docs:
* DeployLocalChanges.md — add Step 1b (Azure roles & permissions check)
  to the "What It Does (in order)" list.
* AutomatedLocalSetup.md — add Step 2b (Azure roles & permissions check)
  to the "What It Does (in order)" list.

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

Author: Rafi-Microsoft

docs/AutomatedLocalSetup.md

@@ -31,6 +31,7 @@ az login
 
 1. **Checks prerequisites** — Python 3.12+, Node.js, npm, uv, Azure CLI, Git
 2. **Azure authentication** — logs you in if needed, confirms the active subscription
+2b. **Checks Azure roles & permissions** — verifies you have role-assignment permission (Owner / User Access Administrator / RBAC Administrator) before attempting RBAC step (non-fatal warning)
 3. **Fetches Azure configuration** — reads deployment outputs or queries resources individually to build `src/backend/.env`
 4. **Assigns RBAC roles** — grants your user account the roles needed to run the app locally:
    - Cosmos DB Built-in Data Contributor

docs/DeployLocalChanges.md

@@ -26,6 +26,7 @@ az login
 ## What It Does (in order)
 
 1. **Checks prerequisites** — Azure CLI and Docker (both required)
+1b. **Checks Azure roles & permissions** — verifies you have Contributor + role-assignment permission on the resource group (non-fatal warning)
 2. **Discovers Azure resources** — finds the backend/MCP Container Apps and frontend App Service in your resource group
 3. **Resolves ACR** — lists ACRs in the resource group and asks which one to use; prompts to create a new one if needed
 4. **Determines services** — deploys all services by default, or only the ones you specify with `--services`

infra/scripts/deploy_to_azure.ps1

@@ -646,12 +646,17 @@ function Configure-AcrOnResources {
         if ($DryRun) { Write-LogInfo "[DRY RUN] Would update frontend App Service registry config" }
         else {
             Write-LogInfo "Updating frontend App Service registry config..."
+            # Capture exit codes from BOTH commands — without this, a failure in the
+            # first call (DOCKER_REGISTRY_SERVER_URL) would be masked if the second
+            # call succeeds, leaving the Web App with a half-configured registry.
             az webapp config appsettings set --name $script:FrontendApp --resource-group $ResourceGroup `
                 --settings DOCKER_REGISTRY_SERVER_URL="https://$($script:AcrLoginServer)" --output none
+            $appsettingsRc = $LASTEXITCODE
             az webapp config set --name $script:FrontendApp --resource-group $ResourceGroup `
                 --generic-configurations '{\"acrUseManagedIdentityCreds\": true}' --output none
-            if ($LASTEXITCODE -ne 0) {
-                Write-LogError "Frontend registry config FAILED — image pull may fail."
+            $configRc = $LASTEXITCODE
+            if ($appsettingsRc -ne 0 -or $configRc -ne 0) {
+                Write-LogError "Frontend registry config FAILED (appsettings rc=$appsettingsRc, config rc=$configRc) — image pull may fail."
             } else {
                 Write-LogSuccess "Frontend registry config updated"
             }

infra/scripts/deploy_to_azure.sh

@@ -25,6 +25,11 @@ set -euo pipefail
 # See: https://github.com/Azure/azure-cli/issues/13009
 az() { MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL="*" command az "$@"; }
 
+# Probe for the real az executable that ignores the wrapper function above.
+# Used in check_prerequisites so an uninstalled Azure CLI doesn't pass the check
+# merely because `command -v az` matches our shell function.
+_has_az_executable() { type -P az >/dev/null 2>&1; }
+
 # Convert a path to Windows-native format for tools like docker.exe that need it.
 # On non-MSYS systems (Linux/macOS) this is a no-op.
 _winpath() {
@@ -73,7 +78,7 @@ log_warn()    { echo -e "${YELLOW}[!]${NC} $*"; }
 log_error()   { echo -e "${RED}[✗]${NC} $*"; }
 log_step()    { echo -e "\n${CYAN}━━━ $* ━━━${NC}\n"; }
 
-# Retry an az command up to 3 times on transient network errors
+# Retry an az command up to 4 attempts on transient network/operation-in-progress errors
 az_retry() {
     local attempt=1 out rc delay
     while [[ $attempt -le 4 ]]; do
@@ -160,7 +165,7 @@ check_prerequisites() {
 
     local missing=()
 
-    if command -v az &>/dev/null; then
+    if _has_az_executable; then
         log_success "Azure CLI found"
     else
         missing+=("azure-cli")
@@ -808,7 +813,7 @@ configure_acr_on_resources() {
 # ==============================================================================
 
 update_azure_resources() {
-    log_step "Step 7: Updating Azure Resources"
+    log_step "Step 8: Updating Azure Resources"
 
     if [[ "$BUILD_ONLY" == true ]]; then
         return

infra/scripts/setup_local_dev.ps1

@@ -13,6 +13,8 @@
 #   .\setup_local_dev.ps1 -ResourceGroup "rg-macae-dev" -SkipPrereqs
 # ==============================================================================
 
+#Requires -Version 7.0
+
 param(
     [string]$ResourceGroup = "",
     [string]$Subscription = "",
@@ -22,6 +24,16 @@ param(
 
 $ErrorActionPreference = "Stop"
 
+# PowerShell 7+ is required because this script uses the null-coalescing operator (`??`)
+# and `Out-File -Encoding utf8NoBOM`, neither of which exist in Windows PowerShell 5.1.
+# `#Requires -Version 7.0` aborts with a clear error on older hosts before parsing fails.
+if ($PSVersionTable.PSVersion.Major -lt 7) {
+    Write-Host "[ERROR] This script requires PowerShell 7 or newer. Detected: $($PSVersionTable.PSVersion)" -ForegroundColor Red
+    Write-Host "        Install from https://aka.ms/powershell or 'winget install Microsoft.PowerShell'" -ForegroundColor Red
+    Write-Host "        Then re-run with 'pwsh.exe' instead of 'powershell.exe'." -ForegroundColor Red
+    exit 1
+}
+
 # Resolve repo root (script lives in infra/scripts/)
 $ScriptDir = $PSScriptRoot
 if (-not $ScriptDir) { $ScriptDir = Get-Location }
@@ -67,21 +79,32 @@ function Check-Prerequisites {
     $missing = @()
 
     # Python 3.12+
+    # Detect a Python 3.12+ interpreter and remember the exact invocation so later
+    # steps (venv creation) use the same interpreter. Without this, `py -3.12` may pass
+    # prereqs while a later `python -m venv` call fails because `python` isn't on PATH.
+    $script:PythonInvocation = $null
     if (Test-CommandExists "py") {
         $pyVersion = & py -3.12 --version 2>$null
         if ($pyVersion) {
             Write-LogSuccess "Python 3.12 found: $pyVersion"
-        } else {
-            $missing += "Python.Python.3.12"
+            $script:PythonInvocation = @("py", "-3.12")
         }
-    } elseif (Test-CommandExists "python") {
+    }
+    if (-not $script:PythonInvocation -and (Test-CommandExists "python")) {
         $pyVersion = & python --version 2>$null
         if ($pyVersion -match "3\.1[2-9]") {
             Write-LogSuccess "Python found: $pyVersion"
-        } else {
-            $missing += "Python.Python.3.12"
+            $script:PythonInvocation = @("python")
         }
-    } else {
+    }
+    if (-not $script:PythonInvocation -and (Test-CommandExists "python3")) {
+        $pyVersion = & python3 --version 2>$null
+        if ($pyVersion -match "3\.1[2-9]") {
+            Write-LogSuccess "Python found: $pyVersion"
+            $script:PythonInvocation = @("python3")
+        }
+    }
+    if (-not $script:PythonInvocation) {
         $missing += "Python.Python.3.12"
     }
 
@@ -840,7 +863,14 @@ function Setup-Frontend {
     if (-not (Test-Path ".venv\Scripts\activate")) {
         if (Test-Path ".venv") { Write-LogWarn "Existing .venv is incomplete (no activate script), recreating..." }
         Write-LogInfo "Creating Python virtual environment..."
-        python -m venv --clear .venv
+        # Use the same interpreter Check-Prerequisites detected (handles 'py -3.12'
+        # on Windows machines where 'python' isn't on PATH).
+        $pyExe = if ($script:PythonInvocation) { $script:PythonInvocation[0] } else { "python" }
+        $pyArgs = @()
+        if ($script:PythonInvocation -and $script:PythonInvocation.Count -gt 1) {
+            $pyArgs = $script:PythonInvocation[1..($script:PythonInvocation.Count - 1)]
+        }
+        & $pyExe @pyArgs -m venv --clear .venv
     } else {
         Write-LogInfo "Python virtual environment already exists"
     }

infra/scripts/setup_local_dev.sh

@@ -17,6 +17,19 @@
 
 set -euo pipefail
 
+# ==============================================================================
+# Bash version check (associative arrays require Bash 4+; macOS ships Bash 3.2)
+# ==============================================================================
+if [[ -z "${BASH_VERSION:-}" ]] || [[ "${BASH_VERSINFO[0]:-0}" -lt 4 ]]; then
+    echo "[ERROR] This script requires Bash 4 or newer (associative arrays)." >&2
+    echo "        Detected: ${BASH_VERSION:-unknown}" >&2
+    echo "        macOS ships with Bash 3.2 by default — install Bash 4+ via Homebrew:" >&2
+    echo "          brew install bash" >&2
+    echo "        Then re-run with the new interpreter, e.g.:" >&2
+    echo "          /opt/homebrew/bin/bash infra/scripts/setup_local_dev.sh ..." >&2
+    exit 1
+fi
+
 # ==============================================================================
 # Paths
 # ==============================================================================
@@ -50,15 +63,8 @@ for _cmd in python3.12 python3 python py; do
         fi
     fi
 done
-# Fallback: use whatever python3/python is available even if version check failed
-if [[ -z "$PYTHON_CMD" ]]; then
-    for _cmd in python3 python py; do
-        if command -v "$_cmd" &>/dev/null; then
-            PYTHON_CMD="$_cmd"
-            break
-        fi
-    done
-fi
+# No silent fallback to <3.12 — later steps (uv sync --python 3.12, venv) require 3.12+.
+# If nothing suitable is found, leave PYTHON_CMD empty; check_prerequisites will fail loudly.
 
 # ==============================================================================
 # Colors
@@ -979,9 +985,17 @@ EXTEOF
 
     local settings_file="$vscode_dir/settings.json"
     if [[ ! -f "$settings_file" ]]; then
-        cat > "$settings_file" << 'SETEOF'
+        # Choose an OS-appropriate interpreter sub-path (Windows uses Scripts\python.exe,
+        # Linux/macOS use bin/python). Detect by checking what activate script exists.
+        local interp_path
+        if [[ -f "$BACKEND_DIR/.venv/Scripts/python.exe" ]] || [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" || "$OSTYPE" == "win32" ]]; then
+            interp_path='${workspaceFolder}/src/backend/.venv/Scripts/python.exe'
+        else
+            interp_path='${workspaceFolder}/src/backend/.venv/bin/python'
+        fi
+        cat > "$settings_file" << SETEOF
 {
-    "python.defaultInterpreterPath": "${workspaceFolder}/src/backend/.venv/Scripts/python.exe",
+    "python.defaultInterpreterPath": "$interp_path",
     "python.terminal.activateEnvironment": true,
     "python.linting.enabled": true,
     "python.formatting.provider": "black",