copilot review fixes and readme updates

Author: Ragini-Microsoft

.env.sample

@@ -53,6 +53,7 @@ AZURE_OPENAI_MAX_TOKENS=2000
 # =============================================================================
 # Azure Cosmos DB
 # =============================================================================
+COSMOSDB_ACCOUNT_NAME=your-cosmos-account
 AZURE_COSMOS_ENDPOINT=https://your-cosmos.documents.azure.com:443/
 AZURE_COSMOS_DATABASE_NAME=content-generation
 AZURE_COSMOS_PRODUCTS_CONTAINER=products
@@ -106,6 +107,7 @@ BRAND_REQUIRED_DISCLOSURES=
 # =============================================================================
 # Application Settings
 # =============================================================================
+RESOURCE_GROUP_NAME=your-resource-group
 # Server configuration
 PORT=5000
 WORKERS=4

docs/LocalDevelopmentSetup.md

@@ -36,38 +36,68 @@ content-generation-solution-accelerator/    ← Repository root (start here)
 
 ## Step 1: Prerequisites - Install Required Tools
 
-### Windows (PowerShell)
+### Windows Development
+
+#### Option 1: Native Windows (PowerShell)
 
 ```powershell
-# Install Python 3.11+, Node.js 18+, Git, and Azure CLI
-winget install Python.Python.3.12
-winget install OpenJS.NodeJS.LTS
+# Install Git
 winget install Git.Git
+
+# Install Node.js for frontend
+winget install OpenJS.NodeJS.LTS
+
+# Install Python 3.11+
+winget install Python.Python.3.12
+
+# Install Azure CLI and Azure Developer CLI
 winget install Microsoft.AzureCLI
 winget install Microsoft.Azd
+```
 
-# Verify installations
-python --version
-node --version
-git --version
-az --version
-azd version
+#### Option 2: Windows with WSL2 (Recommended)
+
+```bash
+# Install WSL2 first (run in PowerShell as Administrator):
+# wsl --install -d Ubuntu
+
+# Then in WSL2 Ubuntu terminal:
+sudo apt update && sudo apt install git curl python3.11 python3.11-venv -y
+
+# Install Node.js 20+ from NodeSource
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# Install Azure CLI
+curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
+
+# Install Azure Developer CLI
+curl -fsSL https://aka.ms/install-azd.sh | bash
 ```
 
-### Linux (Ubuntu/Debian)
+### Linux Development
+
+#### Ubuntu/Debian
 
 ```bash
 # Install prerequisites
-sudo apt update && sudo apt install python3.11 python3.11-venv git curl nodejs npm -y
+sudo apt update && sudo apt install git curl python3.11 python3.11-venv -y
+
+# Install Node.js 20+ from NodeSource
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
 
 # Install Azure CLI
 curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
 
 # Install Azure Developer CLI
 curl -fsSL https://aka.ms/install-azd.sh | bash
+```
+
+### Verify Installations
 
-# Verify installations
-python3 --version
+```bash
+python3 --version    # or python --version on Windows
 node --version
 git --version
 az --version

scripts/local_dev.ps1

@@ -293,9 +293,9 @@ function Invoke-Setup {
     # Check for .env file
     if (-not (Test-Path ".env")) {
         Write-Warning ".env file not found"
-        if (Test-Path ".env.template") {
-            Write-Info "Copying .env.template to .env..."
-            Copy-Item ".env.template" ".env"
+        if (Test-Path ".env.sample") {
+            Write-Info "Copying .env.sample to .env..."
+            Copy-Item ".env.sample" ".env"
             Write-Warning "Please update .env with your Azure resource values"
         }
     } else {
@@ -357,9 +357,9 @@ function Invoke-EnvGeneration {
         Write-Warning "Azure Developer CLI not found or no azure.yaml"
         Write-Info "Please manually update .env with your Azure resource values"
 
-        if (-not (Test-Path ".env") -and (Test-Path ".env.template")) {
-            Copy-Item ".env.template" ".env"
-            Write-Info "Created .env from template"
+        if (-not (Test-Path ".env") -and (Test-Path ".env.sample")) {
+            Copy-Item ".env.sample" ".env"
+            Write-Info "Created .env from .env.sample"
         }
     }
 
@@ -423,6 +423,8 @@ function Start-Backend {
     Push-Location $BackendDir
     try {
         # Use hypercorn for async support
+        # Output filter suppresses benign Ctrl+C shutdown noise from Python (InterruptedError tracebacks,
+        # sys.exit, frozen importlib). Real startup/runtime errors appear before these patterns.
         if (Test-Command "hypercorn") {
             hypercorn app:app --bind "0.0.0.0:$BackendPort" --reload 2>&1 | ForEach-Object {
                 if ($_ -notmatch "Traceback|File.*frozen|InterruptedError|sys\.exit") {
@@ -437,7 +439,7 @@ function Start-Backend {
             }
         }
     } catch {
-        # Suppress Ctrl+C exceptions
+        # Suppress Ctrl+C PipelineStoppedException — not a real error
     } finally {
         Pop-Location
     }
@@ -481,6 +483,33 @@ function Start-All {
 
     Set-Location $ProjectRoot
 
+    # Handle .env: generate if missing, or prompt to refresh if exists
+    if (-not (Test-Path ".env")) {
+        Write-Warning ".env file not found. Generating from Azure resources..."
+        Invoke-EnvGeneration
+        # Fallback to .env.sample if generation didn't produce .env
+        if (-not (Test-Path ".env") -and (Test-Path ".env.sample")) {
+            Write-Warning "Env generation did not create .env. Copying .env.sample as fallback..."
+            Copy-Item ".env.sample" ".env"
+            Write-Info "Created .env from .env.sample. Update the file with your Azure resource values."
+        }
+        if (-not (Test-Path ".env")) {
+            Write-Error "Failed to create .env. Run '.\scripts\local_dev.ps1 -Command env' or create .env manually from .env.sample."
+            exit 1
+        }
+    } else {
+        Write-Success "Found existing .env file"
+        $overwrite = Read-Host "Do you want to overwrite it with fresh values from Azure deployment? (y/N)"
+        if ($overwrite -eq 'y' -or $overwrite -eq 'Y') {
+            Write-Info "Regenerating .env from Azure resources..."
+            Remove-Item ".env" -Force
+            Invoke-EnvGeneration
+            Write-Success "Environment variables refreshed."
+        } else {
+            Write-Info "Preserving existing .env. Using local configuration."
+        }
+    }
+    
     # Auto-run setup if prerequisites are missing
     $needsSetup = $false
     if (-not (Test-Path ".venv")) {
@@ -495,12 +524,6 @@ function Start-All {
         Invoke-Setup
     }
 
-    # Auto-run env generation if .env is missing
-    if (-not (Test-Path ".env")) {
-        Write-Warning ".env file not found. Generating from Azure resources..."
-        Invoke-EnvGeneration
-    }
-    
     # Ensure Azure roles
     Ensure-AzureLogin
     Ensure-AzureAIUserRole
@@ -572,8 +595,15 @@ function Start-All {
                 }
             }
 
-            if ($backendJob.State -eq 'Failed' -or $frontendJob.State -eq 'Failed') {
-                Write-Error "One of the services failed"
+            # Break if either job is no longer running
+            $backendState = $backendJob.State
+            $frontendState = $frontendJob.State
+            if ($backendState -ne 'Running' -or $frontendState -ne 'Running') {
+                if ($backendState -eq 'Failed' -or $frontendState -eq 'Failed') {
+                    Write-Error "One of the services failed (backend: $backendState, frontend: $frontendState)"
+                } else {
+                    Write-Warning "A service has stopped (backend: $backendState, frontend: $frontendState)"
+                }
                 break
             }
 

scripts/local_dev.sh

@@ -283,9 +283,9 @@ setup() {
     # Check for .env file
     if [ ! -f ".env" ]; then
         print_warning ".env file not found"
-        if [ -f ".env.template" ]; then
-            print_info "Copying .env.template to .env..."
-            cp .env.template .env
+        if [ -f ".env.sample" ]; then
+            print_info "Copying .env.sample to .env..."
+            cp .env.sample .env
             print_warning "Please update .env with your Azure resource values"
         fi
     else
@@ -340,8 +340,9 @@ generate_env() {
         print_warning "Azure Developer CLI not found or no azure.yaml"
         print_info "Please manually update .env with your Azure resource values"
 
-        if [ ! -f ".env" ] && [ -f ".env.template" ]; then
-            cp .env.template .env
+        if [ ! -f ".env" ] && [ -f ".env.sample" ]; then
+            cp .env.sample .env
+            print_info "Created .env from .env.sample"
             print_info "Created .env from template"
         fi
     fi
@@ -437,6 +438,33 @@ start_all() {
 
     cd "$PROJECT_ROOT"
 
+    # Handle .env: generate if missing, or prompt to refresh if exists
+    if [ ! -f ".env" ]; then
+        print_warning ".env file not found. Generating from Azure resources..."
+        generate_env
+        # Fallback to .env.sample if generation didn't produce .env
+        if [ ! -f ".env" ] && [ -f ".env.sample" ]; then
+            print_warning "Env generation did not create .env. Copying .env.sample as fallback..."
+            cp .env.sample .env
+            print_info "Created .env from .env.sample. Update the file with your Azure resource values."
+        fi
+        if [ ! -f ".env" ]; then
+            print_error "Failed to create .env. Run './scripts/local_dev.sh env' or create .env manually from .env.sample."
+            exit 1
+        fi
+    else
+        print_success "Found existing .env file"
+        read -p "Do you want to overwrite it with fresh values from Azure deployment? (y/N): " overwrite
+        if [ "$overwrite" = "y" ] || [ "$overwrite" = "Y" ]; then
+            print_info "Regenerating .env from Azure resources..."
+            rm -f .env
+            generate_env
+            print_success "Environment variables refreshed."
+        else
+            print_info "Preserving existing .env. Using local configuration."
+        fi
+    fi
+    
     # Auto-run setup if prerequisites are missing
     local needs_setup=false
     if [ ! -d ".venv" ]; then
@@ -451,12 +479,6 @@ start_all() {
         setup
     fi
 
-    # Auto-run env generation if .env is missing
-    if [ ! -f ".env" ]; then
-        print_warning ".env file not found. Generating from Azure resources..."
-        generate_env
-    fi
-    
     # Ensure Azure authentication and role assignments
     ensure_azure_login
     ensure_azure_ai_user_role