refactor: Update setup instructions and improve service startup guidance in setup scripts

Author: Abdul-Microsoft

docs/AutomatedLocalSetup.md

@@ -152,23 +152,32 @@ The script automatically grants your user account the following roles (skips if
 
 ## After Setup
 
-Once the script finishes, start the three services in separate terminals:
+Once the script finishes, start the three services in separate terminals (Backend first, then MCP, then Frontend):
 
-```bash
-# Terminal 1 — Backend (port 8000)
-cd src/backend
-source .venv/Scripts/activate   # Windows Git Bash
-# source .venv/bin/activate     # Linux / macOS
-uvicorn app:app --reload --host 0.0.0.0 --port 8000
-
-# Terminal 2 — MCP Server (port 9000)
-cd src/mcp_server
-source .venv/Scripts/activate
-python mcp_server.py
-
-# Terminal 3 — Frontend (port 3000)
-cd src/App
-npm run dev
+```
+Terminal 1 — Backend (port 8000):
+  cd src/backend
+  Activate virtual environment:
+    PowerShell : .\.venv\Scripts\Activate.ps1
+    Git Bash   : source .venv/Scripts/activate
+    Linux/macOS: source .venv/bin/activate
+  python app.py
+
+Terminal 2 — MCP Server (port 9000):
+  cd src/mcp_server
+  Activate virtual environment:
+    PowerShell : .\.venv\Scripts\Activate.ps1
+    Git Bash   : source .venv/Scripts/activate
+    Linux/macOS: source .venv/bin/activate
+  python mcp_server.py --transport streamable-http --host 0.0.0.0 --port 9000
+
+Terminal 3 — Frontend (port 3000):
+  cd src/App
+  Activate virtual environment:
+    PowerShell : .\.venv\Scripts\Activate.ps1
+    Git Bash   : source .venv/Scripts/activate
+    Linux/macOS: source .venv/bin/activate
+  python frontend_server.py
 ```
 
 Then open [http://localhost:3000](http://localhost:3000).

docs/DeployLocalChanges.md

@@ -1,6 +1,6 @@
 # Deploy Local Changes to Azure
 
-Two scripts — one for each platform — that build only the Docker images you changed, push them to ACR, and update the live Azure resources.
+Two scripts — one for each platform — that build Docker images for the services you specify (or all by default), push them to ACR, and update the live Azure resources.
 
 | Platform | Script |
 |---|---|
@@ -11,11 +11,10 @@ Two scripts — one for each platform — that build only the Docker images you
 
 ## Prerequisites
 
-| Tool | Purpose |
-|---|---|
-| [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) | Manage Azure resources |
-| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | Build and push images |
-| Git | Detect which services changed |
+| Tool | Required? | Purpose |
+|---|---|---|
+| [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) | **Yes** | Manage Azure resources, ACR login |
+| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | **Yes** | Build and push Docker images |
 
 You must be logged in before running:
 ```bash
@@ -26,12 +25,12 @@ az login
 
 ## What It Does (in order)
 
-1. **Checks prerequisites** — Docker, Azure CLI, Git
+1. **Checks prerequisites** — Azure CLI and Docker (both required)
 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. **Detects changed services** — uses `git diff` to find which of `src/backend/`, `src/mcp_server/`, `src/App/` have changed; only those services are built and deployed
-5. **Generates an image tag** — auto-generates `YYYYMMDD-HHMMSS-<git-sha>` or uses your custom tag
-6. **Builds & pushes images** — `docker build` + `docker push` to ACR for each changed service
+4. **Determines services** — deploys all services by default, or only the ones you specify with `--services`
+5. **Generates an image tag** — auto-generates `YYYYMMDD-HHMMSS` or uses your custom tag
+6. **Builds & pushes images** — builds locally with Docker, pushes to ACR
 7. **Updates Azure resources** — updates the Container App / App Service to the new image tag
 8. **Prints a summary** with rollback commands
 
@@ -41,16 +40,16 @@ az login
 
 ```bash
 # bash (Linux/macOS/WSL)
-bash infra/scripts/deploy_to_azure.sh -g <resource-group>
+bash infra/scripts/deploy_to_azure.sh --resource-group <resource-group>
 
 # PowerShell (Windows)
 .\infra\scripts\deploy_to_azure.ps1 -ResourceGroup <resource-group>
 ```
 
 The script will:
-- Auto-detect which services you changed via git
+- Deploy all services by default (use `--services` to pick specific ones)
+- Build images locally with Docker and push to ACR
 - Ask which ACR to use (or offer to create one)
-- Ask for confirmation before deploying if no changes are detected
 
 ---
 
@@ -59,14 +58,14 @@ The script will:
 ### Bash
 
 ```bash
-./infra/scripts/deploy_to_azure.sh -g <resource-group> [options]
+./infra/scripts/deploy_to_azure.sh --resource-group <resource-group> [options]
 
 Required:
   -g, --resource-group <name>   Azure Resource Group name
 
 Options:
   --acr <name>                  Skip the ACR prompt; use this ACR directly
-  --services <list>             Skip change detection; deploy only these services
+  --services <list>             Deploy only these services (default: all)
                                   Values: backend, mcp, frontend (comma-separated)
   --tag <tag>                   Use a custom image tag instead of auto-generated
   --dry-run                     Preview all steps without making any changes
@@ -86,7 +85,7 @@ Required:
 
 Options:
   -Acr <name>                   Skip the ACR prompt; use this ACR directly
-  -Services <list>              Skip change detection; deploy only these services
+  -Services <list>              Deploy only these services (default: all)
                                   Values: "backend,mcp,frontend"
   -Tag <tag>                    Use a custom image tag instead of auto-generated
   -DryRun                       Preview all steps without making any changes
@@ -100,30 +99,30 @@ Options:
 ## Examples
 
 ```bash
-# Deploy only what changed (auto-detected)
-bash infra/scripts/deploy_to_azure.sh -g rg-macae-dev
+# Deploy all services (default)
+bash infra/scripts/deploy_to_azure.sh --resource-group rg-macae-dev
 
 # Deploy only the frontend
-bash infra/scripts/deploy_to_azure.sh -g rg-macae-dev --services frontend
+bash infra/scripts/deploy_to_azure.sh --resource-group rg-macae-dev --services frontend
 
 # Deploy backend and MCP with a specific ACR
-bash infra/scripts/deploy_to_azure.sh -g rg-macae-dev --services backend,mcp --acr myregistry
+bash infra/scripts/deploy_to_azure.sh --resource-group rg-macae-dev --services backend,mcp --acr myregistry
 
 # Preview without making changes
-bash infra/scripts/deploy_to_azure.sh -g rg-macae-dev --dry-run
+bash infra/scripts/deploy_to_azure.sh --resource-group rg-macae-dev --dry-run
 
 # Build images only (no Azure update)
-bash infra/scripts/deploy_to_azure.sh -g rg-macae-dev --build-only
+bash infra/scripts/deploy_to_azure.sh --resource-group rg-macae-dev --build-only
 
 # Update Azure only (images already pushed)
-bash infra/scripts/deploy_to_azure.sh -g rg-macae-dev --deploy-only --tag 20260506-120000-abc1234
+bash infra/scripts/deploy_to_azure.sh --resource-group rg-macae-dev --deploy-only --tag 20260506-120000-abc1234
 
 # Skip AcrPull role assignment (roles already exist)
-bash infra/scripts/deploy_to_azure.sh -g rg-macae-dev --skip-role-assignment
+bash infra/scripts/deploy_to_azure.sh --resource-group rg-macae-dev --skip-role-assignment
 ```
 
 ```powershell
-# Deploy only what changed
+# Deploy all services (default)
 .\infra\scripts\deploy_to_azure.ps1 -ResourceGroup rg-macae-dev
 
 # Deploy only backend
@@ -138,25 +137,6 @@ bash infra/scripts/deploy_to_azure.sh -g rg-macae-dev --skip-role-assignment
 
 ---
 
-## Change Detection Logic
-
-When `--services` is not specified, the script runs `git diff` to determine what to build:
-
-| Files changed in | Service built |
-|---|---|
-| `src/backend/` | backend |
-| `src/mcp_server/` | mcp |
-| `src/App/` | frontend |
-
-It checks only **uncommitted changes** (staged and unstaged vs the last commit, i.e. `git diff HEAD`). Commits that are already committed but not yet pushed are intentionally excluded to avoid false positives from unrelated branch work.
-
-If no changes are detected in any service directory, the script asks:
-```
-No changes detected. Deploy all services anyway? [y/N]:
-```
-
----
-
 ## ACR Selection
 
 If `--acr` / `-Acr` is not provided, the script **always prompts first**:

infra/scripts/deploy_to_azure.ps1

@@ -80,63 +80,48 @@ function Check-Prerequisites {
 
     $missing = @()
 
-    if (Get-Command docker -ErrorAction SilentlyContinue) {
-        Write-LogSuccess "Docker found: $(docker --version)"
-    } else {
-        $missing += "docker"
-    }
-
     if (Get-Command az -ErrorAction SilentlyContinue) {
         Write-LogSuccess "Azure CLI found"
     } else {
         $missing += "azure-cli"
     }
 
-    if (Get-Command git -ErrorAction SilentlyContinue) {
-        Write-LogSuccess "Git found"
+    if (Get-Command docker -ErrorAction SilentlyContinue) {
+        $dockerInfo = docker info 2>&1
+        if ($LASTEXITCODE -eq 0) {
+            Write-LogSuccess "Docker found and running"
+        } else {
+            Write-LogError "Docker found but daemon not running. Please start Docker Desktop."
+            exit 1
+        }
     } else {
-        $missing += "git"
+        $missing += "docker"
     }
 
     if ($missing.Count -gt 0) {
         Write-LogError "Missing prerequisites: $($missing -join ', ')"
         Write-Host ""
         foreach ($tool in $missing) {
             switch ($tool) {
-                "docker" {
-                    Write-Host "  ┌─ Docker ──────────────────────────────────────────────────────"
-                    Write-Host "  │  Download: https://www.docker.com/products/docker-desktop"
-                    Write-Host "  │  Or: winget install Docker.DockerDesktop"
-                    Write-Host "  │  Verify: docker --version"
-                    Write-Host "  └──────────────────────────────────────────────────────────────"
-                }
                 "azure-cli" {
                     Write-Host "  ┌─ Azure CLI ───────────────────────────────────────────────────"
                     Write-Host "  │  Download: https://aka.ms/installazurecliwindows"
                     Write-Host "  │  Or: winget install Microsoft.AzureCLI"
                     Write-Host "  │  Verify: az --version"
                     Write-Host "  └──────────────────────────────────────────────────────────────"
                 }
-                "git" {
-                    Write-Host "  ┌─ Git ─────────────────────────────────────────────────────────"
-                    Write-Host "  │  Download: https://git-scm.com/download/win"
-                    Write-Host "  │  Or: winget install Git.Git"
-                    Write-Host "  │  Verify: git --version"
+                "docker" {
+                    Write-Host "  ┌─ Docker Desktop ──────────────────────────────────────────────"
+                    Write-Host "  │  Download: https://www.docker.com/products/docker-desktop"
+                    Write-Host "  │  Or: winget install Docker.DockerDesktop"
+                    Write-Host "  │  Verify: docker --version"
                     Write-Host "  └──────────────────────────────────────────────────────────────"
                 }
             }
         }
         exit 1
     }
 
-    # Check Docker daemon
-    $dockerInfo = docker info 2>&1
-    if ($LASTEXITCODE -ne 0) {
-        Write-LogError "Docker daemon is not running. Please start Docker Desktop and retry."
-        exit 1
-    }
-    Write-LogSuccess "Docker daemon is running"
-
     # Check Azure login
     $azAccount = az account show 2>&1
     if ($LASTEXITCODE -ne 0) {
@@ -408,20 +393,6 @@ function Assign-AcrPullRoles {
 # Step 4: Determine Services
 # ==============================================================================
 
-function Get-ChangedServices {
-    # Only detect uncommitted changes (staged + unstaged vs last commit).
-    # We intentionally skip 'commits ahead of origin/main' to avoid false positives
-    # from other work on the feature branch that the user hasn't actively changed.
-    $changed = git diff --name-only HEAD 2>$null
-    if (-not $changed) { return @() }
-
-    $services = @()
-    if ($changed -match '^src/backend/')    { $services += "backend" }
-    if ($changed -match '^src/mcp_server/') { $services += "mcp" }
-    if ($changed -match '^src/App/')        { $services += "frontend" }
-    return $services
-}
-
 function Determine-Services {
     Write-LogStep "Step 4: Determining Services to Deploy"
 
@@ -440,32 +411,10 @@ function Determine-Services {
             }
         }
     } else {
-        # Auto-detect changed services from git
-        Write-LogInfo "No -Services specified — detecting changed services via git..."
-        $detected = Get-ChangedServices
-
-        if ($detected.Count -gt 0) {
-            Write-LogInfo "Git detected changes in: $($detected -join ', ')"
-            foreach ($svc in $detected) {
-                switch ($svc) {
-                    "backend"  { $script:DeployBackend = $true }
-                    "mcp"      { $script:DeployMcp = $true }
-                    "frontend" { $script:DeployFrontend = $true }
-                }
-            }
-        } else {
-            Write-LogWarn "No service-specific changes detected (no uncommitted changes vs HEAD)."
-            Write-Host ""
-            $confirm = Read-Host "No changes detected. Deploy all services anyway? [y/N]"
-            if ($confirm -match '^[Yy](es)?$') {
-                $script:DeployBackend = $true
-                $script:DeployMcp = $true
-                $script:DeployFrontend = $true
-            } else {
-                Write-LogInfo "Nothing to deploy. Exiting."
-                exit 0
-            }
-        }
+        Write-LogInfo "No -Services specified — deploying all services"
+        $script:DeployBackend = $true
+        $script:DeployMcp = $true
+        $script:DeployFrontend = $true
     }
 
     Write-Host "  Services to deploy:"
@@ -485,9 +434,7 @@ function Generate-Tag {
         $script:ImageTag = $Tag
     } else {
         $timestamp = (Get-Date).ToString("yyyyMMdd-HHmmss")
-        $gitSha = git rev-parse --short=7 HEAD 2>$null
-        if (-not $gitSha) { $gitSha = "unknown" }
-        $script:ImageTag = "$timestamp-$gitSha"
+        $script:ImageTag = $timestamp
     }
 
     Write-LogSuccess "Image tag: $script:ImageTag"
@@ -505,7 +452,6 @@ function Build-AndPush {
         return
     }
 
-    # Login to ACR
     Write-LogInfo "Logging into ACR: $script:AcrName..."
     az acr login --name $script:AcrName
     Write-LogSuccess "ACR login successful"