diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md
index f51fe9fd2..85b3d27ef 100644
--- a/docs/DeploymentGuide.md
+++ b/docs/DeploymentGuide.md
@@ -1,108 +1,125 @@
 # Deployment Guide
 
-## **Pre-requisites**
+## Overview
 
-To deploy this solution accelerator, ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the necessary permissions to create **resource groups, resources, app registrations, and assign roles at the resource group level**. This should include Contributor role at the subscription level and Role Based Access Control role on the subscription and/or resource group level. Follow the steps in [Azure Account Set Up](../docs/AzureAccountSetUp.md).
+This guide walks you through deploying the Multi Agent Custom Automation Engine Solution Accelerator to Azure. The deployment process takes approximately 10-15 minutes for the default Development/Testing configuration and includes both infrastructure provisioning and application setup.
 
-> **Note:** When you deploy this solution, you will automatically be granted access to interact with the Cosmos DB database that stores your application data. Specifically, you'll have permissions to:
-> - Read database information and settings
-> - Create, modify, and delete data storage containers (think of these as folders for organizing your data)
-> - Add, view, update, and remove individual data records within those containers
+🆘 **Need Help?** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for solutions to common problems.
 
-Check the [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/?products=all&regions=all) page and select a **region** where the following services are available:
+## Step 1: Prerequisites & Setup
 
-- [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/)
-- [Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/)
-- [Azure Container Registry](https://learn.microsoft.com/en-us/azure/container-registry/)
-- [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/)
-- [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/)
-- [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/)
-- [GPT Model Capacity](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models)
+### 1.1 Azure Account Requirements
 
-Here are some example regions where the services are available: East US, East US2, Japan East, UK South, Sweden Central.
+Ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the following permissions:
 
-### **Important Note for PowerShell Users**
+| **Required Permission/Role** | **Scope** | **Purpose** |
+|------------------------------|-----------|-------------|
+| **Contributor** | Subscription level | Create and manage Azure resources |
+| **User Access Administrator** | Subscription level | Manage user access and role assignments |
+| **Role Based Access Control** | Subscription/Resource Group level | Configure RBAC permissions |
+| **App Registration Creation** | Azure Active Directory | Create and configure authentication |
 
-If you encounter issues running PowerShell scripts due to the policy of not being digitally signed, you can temporarily adjust the `ExecutionPolicy` by running the following command in an elevated PowerShell session:
+**🔍 How to Check Your Permissions:**
 
-```powershell
-Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
-```
+1. Go to [Azure Portal](https://portal.azure.com/)
+2. Navigate to **Subscriptions** (search for "subscriptions" in the top search bar)
+3. Click on your target subscription
+4. In the left menu, click **Access control (IAM)**
+5. Scroll down to see the table with your assigned roles - you should see:
+   - **Contributor** 
+   - **User Access Administrator**
+   - **Role Based Access Control Administrator** (or similar RBAC role)
 
-This will allow the scripts to run for the current session without permanently changing your system's policy.
+**For App Registration permissions:**
+1. Go to **Microsoft Entra ID** → **Manage** → **App registrations**
+2. Try clicking **New registration** 
+3. If you can access this page, you have the required permissions
+4. Cancel without creating an app registration
 
-### **Azure Developer CLI (azd) Requirement**
+📖 **Detailed Setup:** Follow [Azure Account Set Up](./AzureAccountSetUp.md) for complete configuration.
 
-Ensure that you are using the latest version of the [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/overview).
-The `azd` version must be **1.18.0 or higher**.
+### 1.2 Check Service Availability & Quota
 
-Upgrade commands by OS:
+⚠️ **CRITICAL:** Before proceeding, ensure your chosen region has all required services available:
 
-* **Windows (using winget):**
+**Required Azure Services:**
+- [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/)
+- [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/)
+- [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/)
+- [Azure App Service](https://learn.microsoft.com/en-us/azure/app-service/)
+- [Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/)
+- [Azure Container Registry](https://learn.microsoft.com/en-us/azure/container-registry/)
+- [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/)
+- [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/)
+- [Azure Blob Storage](https://learn.microsoft.com/en-us/azure/storage/blobs/)
+- [GPT Model Capacity](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models)
 
-  ```bash
-  winget install microsoft.azd
-  ```
+**Recommended Regions:** East US, East US2, Australia East, Japan East, UK South, France Central
 
-* **Linux (using apt):**
+🔍 **Check Availability:** Use [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/) to verify service availability.
 
-  ```bash
-  curl -fsSL https://aka.ms/install-azd.sh | bash
-  ```
+### 1.3 Quota Check (Optional)
 
-* **macOS (using Homebrew):**
+💡 **RECOMMENDED:** Check your Azure OpenAI quota availability before deployment for optimal planning.
 
-  ```bash
-  brew update && brew tap azure/azd && brew install azd
-  ```
+📖 **Follow:** [Quota Check Instructions](./quota_check.md) to ensure sufficient capacity.
 
-## Deployment Options & Steps
+<!-- **Recommended Configuration:**
+- **Default:** 200k tokens (minimum)
+- **Optimal:** 500k tokens (recommended for best performance) -->
 
-### Deployment Steps 
+> **Note:** When you run `azd up`, the deployment will automatically show you regions with available quota, so this pre-check is optional but helpful for planning purposes. You can customize these settings later in [Step 3.3: Advanced Configuration](#33-advanced-configuration-optional).
 
-Pick from the options below to see step-by-step instructions for GitHub Codespaces, VS Code Dev Containers, Local Environments, and Bicep deployments.
+📖 **Adjust Quota:** Follow [Azure AI Model Quota Settings](./AzureGPTQuotaSettings.md) if needed.
 
-| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator) | [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator) | [![Open in Visual Studio Code Web](https://img.shields.io/static/v1?style=for-the-badge&label=Visual%20Studio%20Code%20(Web)&message=Open&color=blue&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/azure/?vscode-azure-exp=foundry&agentPayload=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvTXVsdGktQWdlbnQtQ3VzdG9tLUF1dG9tYXRpb24tRW5naW5lLVNvbHV0aW9uLUFjY2VsZXJhdG9yL3JlZnMvaGVhZHMvbWFpbi9pbmZyYS92c2NvZGVfd2ViIiwgImluZGV4VXJsIjogIi9pbmRleC5qc29uIiwgInZhcmlhYmxlcyI6IHsiYWdlbnRJZCI6ICIiLCAiY29ubmVjdGlvblN0cmluZyI6ICIiLCAidGhyZWFkSWQiOiAiIiwgInVzZXJNZXNzYWdlIjogIiIsICJwbGF5Z3JvdW5kTmFtZSI6ICIiLCAibG9jYXRpb24iOiAiIiwgInN1YnNjcmlwdGlvbklkIjogIiIsICJyZXNvdXJjZUlkIjogIiIsICJwcm9qZWN0UmVzb3VyY2VJZCI6ICIiLCAiZW5kcG9pbnQiOiAiIn0sICJjb2RlUm91dGUiOiBbImFpLXByb2plY3RzLXNkayIsICJweXRob24iLCAiZGVmYXVsdC1henVyZS1hdXRoIiwgImVuZHBvaW50Il19) |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+## Step 2: Choose Your Deployment Environment
 
-<details>
-  <summary><b>Deploy in GitHub Codespaces</b></summary>
+Select one of the following options to deploy the Multi Agent Custom Automation Engine Solution Accelerator:
 
-### GitHub Codespaces
+### Environment Comparison
 
-You can run this solution using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:
+| **Option** | **Best For** | **Prerequisites** | **Setup Time** |
+|------------|--------------|-------------------|----------------|
+| **GitHub Codespaces** | Quick deployment, no local setup required | GitHub account | ~3-5 minutes |
+| **VS Code Dev Containers** | Fast deployment with local tools | Docker Desktop, VS Code | ~5-10 minutes |
+| **VS Code Web** | Quick deployment, no local setup required | Azure account | ~2-4 minutes |
+| **Local Environment** | Enterprise environments, full control | All tools individually | ~15-30 minutes |
 
-1. Open the solution accelerator (this may take several minutes):
+**💡 Recommendation:** For fastest deployment, start with **GitHub Codespaces** - no local installation required.
 
-   [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator)
+---
 
-2. Accept the default values on the create Codespaces page.
-3. Open a terminal window if it is not already open.
-4. Continue with the [deployment options](#deployment-options).
+<details>
+<summary><b>Option A: GitHub Codespaces (Easiest)</b></summary>
 
-</details>
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator)
 
-<details>
-  <summary><b>Deploy in VS Code Dev Containers</b></summary>
+1. Click the badge above (may take several minutes to load)
+2. Accept default values on the Codespaces creation page
+3. Wait for the environment to initialize (includes all deployment tools)
+4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings)
 
-### VS Code Dev Containers
+</details>
 
-You can run this solution in VS Code Dev Containers, which will open the project in your local VS Code using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers):
+<details>
+<summary><b>Option B: VS Code Dev Containers</b></summary>
 
-1. Start Docker Desktop (install it if not already installed).
-2. Open the project:
+[![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator)
 
-   [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator)
+**Prerequisites:**
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running
+- [VS Code](https://code.visualstudio.com/) with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
 
-3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.
-4. Continue with the [deployment options](#deployment-options).
+**Steps:**
+1. Start Docker Desktop
+2. Click the badge above to open in Dev Containers
+3. Wait for the container to build and start (includes all deployment tools)
+4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings)
 
 </details>
 
 <details>
-  <summary><b>Deploy in VS Code Web</b></summary>
-
-### VS Code Web
+<summary><b>Option C: Visual Studio Code Web</b></summary>
 
 [![Open in Visual Studio Code Web](https://img.shields.io/static/v1?style=for-the-badge&label=Visual%20Studio%20Code%20(Web)&message=Open&color=blue&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/azure/?vscode-azure-exp=foundry&agentPayload=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvTXVsdGktQWdlbnQtQ3VzdG9tLUF1dG9tYXRpb24tRW5naW5lLVNvbHV0aW9uLUFjY2VsZXJhdG9yL3JlZnMvaGVhZHMvbWFpbi9pbmZyYS92c2NvZGVfd2ViIiwgImluZGV4VXJsIjogIi9pbmRleC5qc29uIiwgInZhcmlhYmxlcyI6IHsiYWdlbnRJZCI6ICIiLCAiY29ubmVjdGlvblN0cmluZyI6ICIiLCAidGhyZWFkSWQiOiAiIiwgInVzZXJNZXNzYWdlIjogIiIsICJwbGF5Z3JvdW5kTmFtZSI6ICIiLCAibG9jYXRpb24iOiAiIiwgInN1YnNjcmlwdGlvbklkIjogIiIsICJyZXNvdXJjZUlkIjogIiIsICJwcm9qZWN0UmVzb3VyY2VJZCI6ICIiLCAiZW5kcG9pbnQiOiAiIn0sICJjb2RlUm91dGUiOiBbImFpLXByb2plY3RzLXNkayIsICJweXRob24iLCAiZGVmYXVsdC1henVyZS1hdXRoIiwgImVuZHBvaW50Il19)
 
@@ -110,59 +127,60 @@ You can run this solution in VS Code Dev Containers, which will open the project
 2. Sign in with your Azure account when prompted
 3. Select the subscription where you want to deploy the solution
 4. Wait for the environment to initialize (includes all deployment tools)
-5. Once the solution opens, the **AI Foundry terminal** will automatically start running the following command to install the required dependencies:
+5. When prompted in the VS Code Web terminal, choose one of the available options shown below:
 
-    ```shell
-    sh install.sh
-    ```
-    During this process, you’ll be prompted with the message:
-    ```
-    What would you like to do with these files?
-    - Overwrite with versions from template
-    - Keep my existing files unchanged
-    ```
-    Choose “**Overwrite with versions from template**” and provide a unique environment name when prompted.
-6. Continue with the [deployment options](#deployment-options).
+   ![VS Code Initial Prompt](./images/vscodeweb_intialize.png)
+6. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings)
 
 </details>
 
 <details>
-  <summary><b>Deploy in your local Environment</b></summary>
-
-### Local Environment
+<summary><b>Option D: Local Environment</b></summary>
 
-If you're not using one of the above options for opening the project, then you'll need to:
+**Required Tools:**
+- [PowerShell 7.0+](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) 
+- [Azure Developer CLI (azd) 1.18.0+](https://aka.ms/install-azd)
+- [Python 3.9+](https://www.python.org/downloads/)
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+- [Git](https://git-scm.com/downloads)
 
-1. Make sure the following tools are installed:
-
-   - [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.5) <small>(v7.0+)</small> - available for Windows, macOS, and Linux.
-   - [Azure Developer CLI (azd)](https://aka.ms/install-azd) <small>(v1.18.0+)</small> - version
-   - [Python 3.9+](https://www.python.org/downloads/)
-   - [Docker Desktop](https://www.docker.com/products/docker-desktop/)
-   - [Git](https://git-scm.com/downloads)
-
-2. Clone the repository or download the project code via command-line:
+**Setup Steps:**
+1. Install all required deployment tools listed above
+2. Clone the repository:
 
    ```shell
    azd init -t microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator/
    ```
-
    > **⚠️ Warning:** The `azd init` command will download and initialize the project template. If you run this command in a directory that already contains project files, it may override your existing changes. Only run this command once when setting up the project for the first time. If you need to update an existing project, consider using `git pull` or manually downloading updates instead.
 
-3. Open the project folder in your terminal or editor.
-4. Continue with the [deployment options](#deployment-options).
+3. Open the project folder in your terminal
+4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings)
+
+**PowerShell Users:** If you encounter script execution issues, run:
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+```
 
 </details>
 
-### Deployment Options
+## Step 3: Configure Deployment Settings
+
+Review the configuration options below. You can customize any settings that meet your needs, or leave them as defaults to proceed with a standard deployment.
 
-The [`infra`](../infra) folder of the Multi Agent Solution Accelerator contains the [`main.bicep`](../infra/main.bicep) Bicep script, which defines all Azure infrastructure components for this solution.
+### 3.1 Choose Deployment Type (Optional)
 
-By default, the `azd up` command uses the [`main.parameters.json`](../infra/main.parameters.json) file to deploy the solution. This file is pre-configured for a **sandbox environment** — ideal for development and proof-of-concept scenarios, with minimal security and cost controls for rapid iteration.
+| **Aspect** | **Development/Testing (Default)** | **Production** |
+|------------|-----------------------------------|----------------|
+| **Configuration File** | `main.parameters.json` (sandbox) | Copy `main.waf.parameters.json` to `main.parameters.json` |
+| **Security Controls** | Minimal (for rapid iteration) | Enhanced (production best practices) |
+| **Cost** | Lower costs | Cost optimized |
+| **Use Case** | POCs, development, testing | Production workloads |
+| **Framework** | Basic configuration | [Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/) |
+| **Features** | Core functionality | Reliability, security, operational excellence |
 
-For **production deployments**, the repository also provides [`main.waf.parameters.json`](../infra/main.waf.parameters.json), which applies a [Well-Architected Framework (WAF) aligned](https://learn.microsoft.com/en-us/azure/well-architected/) configuration. This option enables additional Azure best practices for reliability, security, cost optimization, operational excellence, and performance efficiency, such as:
+**To use production configuration:**
 
-  **Prerequisite** — Enable the Microsoft.Compute/EncryptionAtHost feature for every subscription (and region, if required) where you plan to deploy VMs or VM scale sets with `encryptionAtHost: true`. Repeat the registration steps below for each target subscription (and for each region when applicable). This step is required for **WAF-aligned** (production) deployments.
+**Prerequisite** — Enable the Microsoft.Compute/EncryptionAtHost feature for every subscription (and region, if required) where you plan to deploy VMs or VM scale sets with `encryptionAtHost: true`. Repeat the registration steps below for each target subscription (and for each region when applicable). This step is required for **WAF-aligned** (production) deployments.
 
   Steps to enable the feature:
   1. Set the target subscription:
@@ -179,52 +197,41 @@ For **production deployments**, the repository also provides [`main.waf.paramete
 
   Reference: Azure Host Encryption — https://learn.microsoft.com/azure/virtual-machines/disks-enable-host-based-encryption-portal?tabs=azure-cli
 
-  - Enhanced network security (e.g., Network protection with private endpoints)
-  - Stricter access controls and managed identities
-  - Logging, monitoring, and diagnostics enabled by default
-  - Resource tagging and cost management recommendations
+Copy the contents from the production configuration file to your main parameters file:
 
-**How to choose your deployment configuration:**
+1. Navigate to the `infra` folder in your project
+2. Open `main.waf.parameters.json` in a text editor (like Notepad, VS Code, etc.)
+3. Select all content (Ctrl+A) and copy it (Ctrl+C)
+4. Open `main.parameters.json` in the same text editor
+5. Select all existing content (Ctrl+A) and paste the copied content (Ctrl+V)
+6. Save the file (Ctrl+S)
 
-* Use the default `main.parameters.json` file for a **sandbox/dev environment**
-* For a **WAF-aligned, production-ready deployment**, copy the contents of `main.waf.parameters.json` into `main.parameters.json` before running `azd up`
+### 3.2 Set VM Credentials (Optional - Production Deployment Only)
 
----
-
-### VM Credentials Configuration
+> **Note:** This section only applies if you selected **Production** deployment type in section 3.1. VMs are not deployed in the default Development/Testing configuration.
 
-By default, the solution sets the VM administrator username and password from environment variables.
-If you do not configure these values, a randomly generated GUID will be used for both the username and password.
+By default, random GUIDs are generated for VM credentials. To set custom credentials:
 
-To set your own VM credentials before deployment, use:
-
-```sh
+```shell
 azd env set AZURE_ENV_VM_ADMIN_USERNAME <your-username>
 azd env set AZURE_ENV_VM_ADMIN_PASSWORD <your-password>
 ```
 
-> [!TIP]
-> Always review and adjust parameter values (such as region, capacity, security settings and log analytics workspace configuration) to match your organization’s requirements before deploying. For production, ensure you have sufficient quota and follow the principle of least privilege for all identities and role assignments.
-
-
-> [!IMPORTANT]
-> The WAF-aligned configuration is under active development. More Azure Well-Architected recommendations will be added in future updates.
-
-
-Consider the following settings during your deployment to modify specific settings:
+### 3.3 Advanced Configuration (Optional)
 
 <details>
-  <summary><b>Configurable Deployment Settings</b></summary>
+<summary><b>Configurable Parameters</b></summary>
 
-When you start the deployment, most parameters will have **default values**, but you can update the following settings [here](../docs/CustomizingAzdParameters.md):
+You can customize various deployment settings before running `azd up`, including Azure regions, AI model configurations (deployment type, version, capacity), container registry settings, and resource names.
 
+📖 **Complete Guide:** See [Parameter Customization Guide](../docs/CustomizingAzdParameters.md) for the full list of available parameters and their usage.
 
 </details>
 
 <details>
   <summary><b>[Optional] Quota Recommendations</b></summary>
 
-By default, the **GPT model capacity** in deployment is set to **140k tokens**.
+By default, the **GPT model capacity** in deployment is set to **150k tokens**.
 
 To adjust quota settings, follow these [steps](./AzureGPTQuotaSettings.md).
 
@@ -233,73 +240,85 @@ To adjust quota settings, follow these [steps](./AzureGPTQuotaSettings.md).
 </details>
 
 <details>
+<summary><b>Reuse Existing Resources</b></summary>
 
-  <summary><b>Reusing an Existing Log Analytics Workspace</b></summary>
+To optimize costs and integrate with your existing Azure infrastructure, you can configure the solution to reuse compatible resources already deployed in your subscription.
 
-  Guide to get your [Existing Workspace ID](/docs/re-use-log-analytics.md)
+**Supported Resources for Reuse:**
 
-</details>
+- **Log Analytics Workspace:** Integrate with your existing monitoring infrastructure by reusing an established Log Analytics workspace for centralized logging and monitoring. [Configuration Guide](./re-use-log-analytics.md)
 
-<details>
+- **Azure AI Foundry Project:** Leverage your existing AI Foundry project and deployed models to avoid duplication and reduce provisioning time. [Configuration Guide](./re-use-foundry-project.md)
 
-  <summary><b>Reusing an Existing Azure AI Foundry Project</b></summary>
+**Key Benefits:**
+- **Cost Optimization:** Eliminate duplicate resource charges
+- **Operational Consistency:** Maintain unified monitoring and AI infrastructure
+- **Faster Deployment:** Skip resource creation for existing compatible services
+- **Simplified Management:** Reduce the number of resources to manage and monitor
 
-  Guide to get your [Existing Project ID](/docs/re-use-foundry-project.md)
+**Important Considerations:**
+- Ensure existing resources meet the solution's requirements and are in compatible regions
+- Review access permissions and configurations before reusing resources
+- Consider the impact on existing workloads when sharing resources
 
 </details>
 
-### Deploying with AZD
-
-Once you've opened the project in [Codespaces](#github-codespaces), [Dev Containers](#vs-code-dev-containers), or [locally](#local-environment), you can deploy it to Azure by following these steps:
+## Step 4: Deploy the Solution
 
-#### Important: Environment Management for Redeployments
+💡 **Before You Start:** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for common solutions.
 
-> **⚠️ Critical:** If you're redeploying or have deployed this solution before, you **must** create a fresh environment to avoid conflicts and deployment failures.
+### 4.1 Authenticate with Azure
 
-**Choose one of the following before deployment:**
+```shell
+azd auth login
+```
 
-**Option A: Create a completely new environment (Recommended)**
+**For specific tenants:**
 ```shell
-azd env new <new-environment-name>
+azd auth login --tenant-id <tenant-id>
 ```
 
-**Option B: Reinitialize in a new directory**
+> **Finding Tenant ID:** 
+   > 1. Open the [Azure Portal](https://portal.azure.com/).
+   > 2. Navigate to **Microsoft Entra ID** from the left-hand menu.
+   > 3. Under the **Overview** section, locate the **Tenant ID** field. Copy the value displayed.
+
+### 4.2 Start Deployment
+
 ```shell
-# Navigate to a new directory
-cd ../my-new-deployment
-azd init -t microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator/
+azd up
 ```
 
-> **💡 Why is this needed?** Azure resources maintain state information tied to your environment. Reusing an old environment can cause naming conflicts, permission issues, and deployment failures.
+**During deployment, you'll be prompted for:**
+1. **Environment name** (e.g., "macae1") - Must be 3-16 characters long, alphanumeric only
+2. **Azure subscription** selection
+3. **Azure AI Foundry deployment region** - Select a region with available model quota for AI operations
+4. **Primary location** - Select the region where your infrastructure resources will be deployed
+5. **Resource group** selection (create new or use existing)
 
-#### Deploy the solution
-1. Login to Azure:
+**Expected Duration:** 9-10 minutes for default configuration
 
-   ```shell
-   azd auth login
-   ```
+- **Upon successful completion**, you will see a success message indicating that all resources have been deployed, along with the application URL and next steps for uploading team configurations and sample data.
 
-   #### To authenticate with Azure Developer CLI (`azd`), use the following command with your **Tenant ID**:
+![Deployment Success message](./images/Deployment_success_message.png)
 
-   ```sh
-   azd auth login --tenant-id <tenant-id>
-   ```
+**⚠️ Deployment Issues:** If you encounter errors or timeouts, try a different region as there may be capacity constraints. For detailed error solutions, see our [Troubleshooting Guide](./TroubleShootingSteps.md).
 
-2. Provision and deploy all the resources:
+### 4.3 Get Application URL
 
-   ```shell
-   azd up
-   ```
-   > **Note:** This solution accelerator requires **Azure Developer CLI (azd) version 1.18.0 or higher**. Please ensure you have the latest version installed before proceeding with deployment. [Download azd here](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd).
+After successful deployment:
+1. Open [Azure Portal](https://portal.azure.com/)
+2. Navigate to your resource group
+3. Find the Fronted App Service
+4. Copy the **Default domain**
 
-3. Provide an `azd` environment name (e.g., "macaeapp").
-4. Select a subscription from your Azure account and choose a location that has quota for all the resources.
+⚠️ **Important:** Complete [Post-Deployment Steps](#step-5-post-deployment-configuration) before accessing the application.
 
-   - This deployment will take _4-6 minutes_ to provision the resources in your account and set up the solution with sample data.
-   - If you encounter an error or timeout during deployment, changing the location may help, as there could be availability constraints for the resources.
-   - **Upon successful completion**, you will see a success message indicating that all resources have been deployed, along with the application URL and next steps for uploading team configurations and sample data.
+## Step 5: Post-Deployment Configuration
 
-5. Upload Team Configurations using command printed in the terminal. The command will look like one of the following. Run the appropriate command for your shell from the project root:
+### 5.1 Run Post Deployment Script
+
+1. Upload Team Configurations using command printed in the terminal. The command will look like one of the following. Run the appropriate command for your shell from the project root:
 
   - **For Bash (Linux/macOS/WSL):**
     ```bash
@@ -311,7 +330,7 @@ azd init -t microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator/
     infra\scripts\Upload-Team-Config.ps1
     ```
 
-6. Index Sample Data into Search Service using command printed in the terminal. The command will look like one of the following. Run the appropriate command for your shell from the project root:
+2. Index Sample Data into Search Service using command printed in the terminal. The command will look like one of the following. Run the appropriate command for your shell from the project root:
 
   - **For Bash (Linux/macOS/WSL):**
     ```bash
@@ -323,7 +342,7 @@ azd init -t microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator/
     infra\scripts\Process-Sample-Data.ps1
     ```
 
-7. **[Alternative]** To upload team configurations and index sample data in one step, run the appropriate command for your shell from the project root:
+3. **[Alternative]** To upload team configurations and index sample data in one step, run the appropriate command for your shell from the project root:
 
   - **For Bash (Linux/macOS/WSL):**
     ```bash
@@ -335,280 +354,166 @@ azd init -t microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator/
     infra\scripts\Team-Config-And-Data.ps1
     ```
 
-8. **[Optional]** Set up authentication for your web application by following the steps in [Set Up Authentication in Azure App Service](../docs/azure_app_service_auth_setup.md).
-
-9. **Access your application:** Open the [Azure Portal](https://portal.azure.com/), go to your resource group, find the App Service that runs the frontend application, and get the application URL from the **Default domain** field.
-
-### 🛠️ Troubleshooting
- If you encounter any issues during the deployment process, please refer [troubleshooting](../docs/TroubleShootingSteps.md) document for detailed steps and solutions.
-
- ## Next Steps
-Now that you've completed your deployment, you can start using the solution. 
 
-To help you get started, here are some [Sample Questions](./SampleQuestions.md) you can follow to try it out.
+### 5.2 Configure Authentication (Optional)
 
-## Clean Up Resources
-If you are done trying out the application, you can delete all resources by running:
+1. Follow [App Authentication Configuration](./azure_app_service_auth_setup.md)
+2. Wait up to 10 minutes for authentication changes to take effect
 
-```shell
-azd down
-```
-> **Note:** If you deployed with `enableRedundancy=true` and Log Analytics workspace replication is enabled, you must first disable replication before running `azd down` else resource group delete will fail. Follow the steps in [Handling Log Analytics Workspace Deletion with Replication Enabled](./LogAnalyticsReplicationDisable.md), wait until replication returns `false`, then run `azd down`.
+### 5.2 Verify Deployment
 
-# Local setup
+1. Access your application using the URL from Step 4.3
+2. Confirm the application loads successfully
+<!-- 3. Verify you can sign in with your authenticated account -->
 
-> **Note for macOS Developers**: If you are using macOS on Apple Silicon (ARM64) the DevContainer will **not** work. This is due to a limitation with the Azure Functions Core Tools (see [here](https://github.com/Azure/azure-functions-core-tools/issues/3112)).
+### 5.3 Test the Application
 
-The easiest way to run this accelerator is in a VS Code Dev Containers, which will open the project in your local VS Code using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers):
+Follow the detailed to test the Multi agent functionality:
 
-1. Start Docker Desktop (install it if not already installed)
-1. Open the project:
-   [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator)
+📖 **Detailed Instructions:** See the complete [Sample Workflow](./SampleQuestions.md) guide for step-by-step testing procedures.
 
-1. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window
 
-## Detailed Development Container setup instructions
+## Step 6: Clean Up (Optional)
 
-The solution contains a [development container](https://code.visualstudio.com/docs/remote/containers) with all the required tooling to develop and deploy the accelerator. To deploy the Multi-Agent solutions accelerator using the provided development container you will also need:
-
-- [Visual Studio Code](https://code.visualstudio.com)
-- [Remote containers extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
-
-If you are running this on Windows, we recommend you clone this repository in [WSL](https://code.visualstudio.com/docs/remote/wsl)
-
-```cmd
-git clone https://github.com/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator
-```
-
-Open the cloned repository in Visual Studio Code and connect to the development container.
-
-```cmd
-code .
+### Remove All Resources
+```shell
+azd down
 ```
+> **Note:** If you deployed with `enableRedundancy=true` and Log Analytics workspace replication is enabled, you must first disable replication before running `azd down` else resource group delete will fail. Follow the steps in [Handling Log Analytics Workspace Deletion with Replication Enabled](./LogAnalyticsReplicationDisable.md), wait until replication returns `false`, then run `azd down`.
 
-!!! tip
-Visual Studio Code should recognize the available development container and ask you to open the folder using it. For additional details on connecting to remote containers, please see the [Open an existing folder in a container](https://code.visualstudio.com/docs/remote/containers#_quick-start-open-an-existing-folder-in-a-container) quickstart.
-
-When you start the development container for the first time, the container will be built. This usually takes a few minutes. **Please use the development container for all further steps.**
-
-The files for the dev container are located in `/.devcontainer/` folder.
-
-## Local deployment and debugging:
-
-1. **Clone the repository.**
-
-2. **Log into the Azure CLI:**
-
-   - Check your login status using:
-     ```bash
-     az account show
-     ```
-   - If not logged in, use:
-     ```bash
-     az login
-     ```
-   - To specify a tenant, use:
-     ```bash
-     az login --tenant <tenant_id>
-     ```
-
-3. **Create a Resource Group:**
-
-   - You can create it either through the Azure Portal or the Azure CLI:
-     ```bash
-     az group create --name <resource-group-name> --location EastUS2
-     ```
-
-4. **Deploy the Bicep template:**
-
-   - You can use the Bicep extension for VSCode (Right-click the `.bicep` file, then select "Show  deployment plan") or use the Azure CLI:
-     ```bash
-     az deployment group create -g <resource-group-name> -f infra/main.bicep --query 'properties.outputs'
-     ```
-   - **Note**: You will be prompted for a `principalId`, which is the ObjectID of your user in Entra ID. To find it, use the Azure Portal or run:
+### Manual Cleanup (if needed)
+If deployment fails or you need to clean up manually:
+- Follow [Delete Resource Group Guide](./DeleteResourceGroup.md)
 
-     ```bash
-     az ad signed-in-user show --query id -o tsv
-     ```
+## Managing Multiple Environments
 
-     You will also be prompted for locations for Cosmos and OpenAI services. This is to allow separate regions where there may be service quota restrictions.
+### Recover from Failed Deployment
 
-   - **Additional Notes**:
+If your deployment failed or encountered errors, here are the steps to recover:
 
-     **Role Assignments in Bicep Deployment:**
+<details>
+<summary><b>Recover from Failed Deployment</b></summary>
 
-     The **main.bicep** deployment includes the assignment of the appropriate roles to AOAI and Cosmos services. If you want to modify an existing implementation—for example, to use resources deployed as part of the simple deployment for local debugging—you will need to add your own credentials to access the Cosmos and AOAI services. You can add these permissions using the following commands:
+**If your deployment failed or encountered errors:**
 
-     ```bash
-     az cosmosdb sql role assignment create --resource-group <solution-accelerator-rg> --account-name <cosmos-db-account-name> --role-definition-name "Cosmos DB Built-in Data Contributor" --principal-id <aad-user-object-id> --scope /subscriptions/<subscription-id>/resourceGroups/<solution-accelerator-rg>/providers/Microsoft.DocumentDB/databaseAccounts/<cosmos-db-account-name>
-     ```
+1. **Try a different region:** Create a new environment and select a different Azure region during deployment
+2. **Clean up and retry:** Use `azd down` to remove failed resources, then `azd up` to redeploy
+3. **Check troubleshooting:** Review [Troubleshooting Guide](./TroubleShootingSteps.md) for specific error solutions
+4. **Fresh start:** Create a completely new environment with a different name
 
-     ```bash
-     az role assignment create --assignee <aad-user-upn> --role "Azure AI User" --scope /subscriptions/<subscription-id>/resourceGroups/<solution-accelerator-rg>/providers/Microsoft.CognitiveServices/accounts/<azure-ai-foundry-name>
-     ```
+**Example Recovery Workflow:**
+```shell
+# Remove failed deployment (optional)
+azd down
 
-     **Using a Different Database in Cosmos:**
+# Create new environment (3-16 chars, alphanumeric only)
+azd env new macaeretry
 
-     You can set the solution up to use a different database in Cosmos. For example, you can name it something like macae-dev. To do this:
+# Deploy with different settings/region
+azd up
+```
 
-   1. Change the environment variable **COSMOSDB_DATABASE** to the new database name.
-   2. You will need to create the database in the Cosmos DB account. You can do this from the Data Explorer pane in the portal, click on the drop down labeled "_+ New Container_" and provide all the necessary details.
+</details>
 
-5. **Create a `.env` file:**
+### Creating a New Environment
 
-   - Navigate to the `src\backend` folder and create a `.env` file based on the provided `.env.sample` file.
-   - Update the `.env` file with the required values from your Azure resource group in Azure Portal App Service environment variables.
-   - Alternatively, if resources were
-   provisioned using `azd provision` or `azd up`, a `.env` file is automatically generated in the `.azure/<env-name>/.env`
-   file. You can copy the contents of this file into your backend `.env` file.
+If you need to deploy to a different region, test different configurations, or create additional environments:
 
-    _**Note**: To get your `<env-name>` run `azd env list` to see which env is default._
+<details>
+<summary><b>Create a New Environment</b></summary>
 
-6. **Fill in the `.env` file:**
+**Create Environment Explicitly:**
+```shell
+# Create a new named environment (3-16 characters, alphanumeric only)
+azd env new <new-environment-name>
 
-   - Use the output from the deployment or check the Azure Portal under "Deployments" in the resource group.
-   - Make sure to set APP_ENV to "**dev**" in `.env` file.
-   - For local development, make sure to include below env variables in the `.env`
-     - `BACKEND_API_URL=http://localhost:8000`
-     - `FRONTEND_SITE_NAME=http://127.0.0.1:3000` 
-     - `MCP_SERVER_ENDPOINT=http://localhost:9000/mcp`.
+# Select the new environment
+azd env select <new-environment-name>
 
-7. **(Optional) Set up a virtual environment:**
+# Deploy to the new environment
+azd up
+```
 
-   - If you are using `venv`, create and activate your virtual environment for both the frontend and backend folders.
+**Example:**
+```shell
+# Create a new environment for production (valid: 3-16 chars)
+azd env new macaeprod
 
-8. **Install requirements - Backend:**
+# Switch to the new environment
+azd env select macaeprod
 
-   - To install the requirement for backend -
-     Open a terminal in the `src/backend` folder and run:
-     ```bash
-     pip install uv
-     uv sync
-     ```
-     
-9. **Build the frontend (important):**
+# Deploy with fresh settings
+azd up
+```
 
-    - To install the requirement for frontend -
-     Open a terminal in the `src/frontend` folder and run:
-     ```bash
-     pip install -r requirements.txt
-     ```
+> **Environment Name Requirements:**
+> - **Length:** 3-16 characters
+> - **Characters:** Alphanumeric only (letters and numbers)
+> - **Valid examples:** `macae`, `test123`, `myappdev`, `prod2025`
+> - **Invalid examples:** `co` (too short), `my-very-long-environment-name` (too long), `test_env` (underscore not allowed)
 
-    - Before running the frontend server, you must build the frontend to generate the necessary `build/assets` directory.
+</details>
 
-      From the `src/frontend` directory, run:
+<details>
+<summary><b>Switch Between Environments</b></summary>
 
-      ```bash
-      npm install
-      npm run build
-      ```
+**List Available Environments:**
+```shell
+azd env list
+```
 
-10. **Install requirements - MCP server:**
+**Switch to Different Environment:**
+```shell
+azd env select <environment-name>
+```
 
-   - To install the requirement for mcp server -
-     Open a terminal in the `src/mcp_server` folder and run:
-     ```bash
-     pip install uv
-     uv sync
-     ```
+**View Current Environment:**
+```shell
+azd env get-values
+```
 
-11. **Run the application:**
+</details>
 
-- From the `src/backend` directory activate the virtual environment created through step 8 and Run:
+### Best Practices for Multiple Environments
 
-```bash
-python app_kernel.py
-```
+- **Use descriptive names:** `macaedev`, `macaeprod`, `macaetest` (remember: 3-16 chars, alphanumeric only)
+- **Different regions:** Deploy to multiple regions for testing quota availability
+- **Separate configurations:** Each environment can have different parameter settings
+- **Clean up unused environments:** Use `azd down` to remove environments you no longer need
 
-- In a new terminal from the src/frontend directory
 
-```bash
- python frontend_server.py
-```
+## Need Help?
 
-or Run 
+- 🐛 **Issues:** Check [Troubleshooting Guide](./TroubleShootingSteps.md)
+- 💬 **Support:** Review [Support Guidelines](../SUPPORT.md)
+- 🔧 **Development:** See [Contributing Guide](../CONTRIBUTING.md)
 
-  ```bash
-  npm run dev
-  ```
+---
 
-- From the `src/mcp_server` directory activate the virtual environment created through step 10 and Run:
 
-```bash
-python mcp_server.py --transport streamable-http --host 0.0.0.0 --port 9000
-```
+## Advanced: Deploy Local Changes
 
-11. Open a browser and navigate to `http://localhost:3000`
-12. To see swagger API documentation, you can navigate to `http://localhost:8000/docs`
+If you've made local modifications to the code and want to deploy them to Azure, follow these steps to swap the configuration files:
 
-## Deploy Your local changes
-To Deploy your local changes rename the below files.
-   1. Rename `azure.yaml` to `azure_custom2.yaml` and `azure_custom.yaml` to `azure.yaml`.
-   2. Go to `infra` directory
-        - Rename `main.bicep` to `main_custom2.bicep` and `main_custom.bicep` to `main.bicep`.
-Continue with the [deploying steps](#deploying-with-azd).
+> **Note:** To set up and run the application locally for development, see the [Local Development Setup Guide](./LocalDevelopmentSetup.md).
 
+### Step 1: Rename Azure Configuration Files
 
-## Debugging the solution locally
+**In the root directory:**
+1. Rename `azure.yaml` to `azure_custom2.yaml`
+2. Rename `azure_custom.yaml` to `azure.yaml`
 
-You can debug the API backend running locally with VSCode using the following launch.json entry:
+### Step 2: Rename Infrastructure Files
 
-```
-      {
-        "name": "Debug Backend (FastAPI)",
-        "type": "debugpy",
-        "request": "launch",
-        "program": "${workspaceFolder}/src/backend/app_kernel.py",
-        "cwd": "${workspaceFolder}/src/backend",
-        "console": "integratedTerminal",
-        "justMyCode": false,
-        "python": "${workspaceFolder}/src/backend/.venv/Scripts/python.exe",
-        "env": {
-            "PYTHONPATH": "${workspaceFolder}/src/backend",
-            "UVICORN_LOG_LEVEL": "debug"
-        },
-        "args": [],
-        "serverReadyAction": {
-            "pattern": "Uvicorn running on (https?://[^\\s]+)",
-            "uriFormat": "%s",
-            "action": "openExternally"
-        }
-      }
-```
+**In the `infra` directory:**
+1. Rename `main.bicep` to `main_custom2.bicep`
+2. Rename `main_custom.bicep` to `main.bicep`
 
-To debug the python server in the frontend directory (frontend_server.py) and related, add the following launch.json entry:
+### Step 3: Deploy Changes
 
-```
-    {
-      "name": "Python Debugger: Frontend",
-      "type": "debugpy",
-      "request": "launch",
-      "cwd": "${workspaceFolder}/src/frontend",
-      "module": "uvicorn",
-      "args": ["frontend_server:app", "--port", "3000", "--reload"],
-      "jinja": true
-    }
+Run the deployment command:
+```shell
+azd up
 ```
 
-To debug the MCP server by adding the following launch.json entry:
-
-```
-     {
-        "name": "Debug MCP Server",
-        "type": "debugpy",
-        "request": "launch",
-        "program": "${workspaceFolder}/src/mcp_server/mcp_server.py",
-        "cwd": "${workspaceFolder}/src/mcp_server",
-        "console": "integratedTerminal",
-        "justMyCode": false,
-        "python": "${workspaceFolder}/src/mcp_server/.venv/Scripts/python.exe",
-        "env": {
-            "PYTHONPATH": "${workspaceFolder}/src/mcp_server"
-        },
-        "args": [
-            "--transport", "streamable-http",
-            "--host", "0.0.0.0",
-            "--port", "9000"
-        ]
-      }
-```
+> **Note:** These custom files are configured to deploy your local code changes instead of pulling from the GitHub repository.
\ No newline at end of file
diff --git a/docs/LocalDevelopmentSetup.md b/docs/LocalDevelopmentSetup.md
new file mode 100644
index 000000000..60574c6f1
--- /dev/null
+++ b/docs/LocalDevelopmentSetup.md
@@ -0,0 +1,562 @@
+# Local Development Setup Guide
+
+This guide provides comprehensive instructions for setting up the Multi Agent Custom Automation Engine Solution Accelerator for local development across Windows and Linux platforms.
+
+## Important Setup Notes
+
+### Multi-Service Architecture
+
+This application consists of **three separate services** that run independently:
+
+1. **Backend** - Backend APIs related to orchestration and Teams
+2. **Frontend** - React-based user interface
+3. **MCP Server** - MCP server to tools call
+
+> **⚠️ Critical: Each service must run in its own terminal/console window**
+>
+> - **Do NOT close terminals** while services are running
+> - Open **3 separate terminal windows** for local development
+> - Each service will occupy its terminal and show live logs
+>
+> **Terminal Organization:**
+> - **Terminal 1**: Backend - HTTP server on port 8000
+> - **Terminal 2**: Frontend - Development server on port 3000
+> - **Terminal 3**: MCP server - HTTP streamable server on port 9000
+
+### Path Conventions
+
+**All paths in this guide are relative to the repository root directory:**
+
+```bash
+Multi-Agent-Custom-Automation-Engine-Solution-Accelerator/    ← Repository root (start here)
+├── src/
+│   ├── backend/                            ← cd src/backend
+│   │   ├── .venv/                          ← Virtual environment
+│   │   └── .env                            ← Backend config file
+│   │   └── app_kernel.py                   ← Backend Entry Point
+│   ├── frontend/                           ← cd src/frontend
+│   │   ├── node_modules/                   ← npm dependencies
+│   │   ├── .venv/                          ← Virtual environment
+│   │   ├── frontend_server.py              ← Fronted entry point
+│   ├── mcp_server/                         ← cd src/mcp_server
+│   │   ├── .venv/                          ← Virtual environment
+│   │   └── mcp_server.py                   ← MCP server Entry Point
+└── docs/                                   ← Documentation (you are here)
+```
+
+**Before starting any step, ensure you are in the repository root directory:**
+
+```bash
+# Verify you're in the correct location
+pwd  # Linux/macOS - should show: .../Multi-Agent-Custom-Automation-Engine-Solution-Accelerator
+Get-Location  # Windows PowerShell - should show: ...\Multi-Agent-Custom-Automation-Engine-Solution-Accelerator
+
+# If not, navigate to repository root
+cd path/to/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator
+```
+
+### Configuration Files
+
+This project uses Backend `.env` file in Backend directory with different configuration requirements:
+
+- **Backend**: `src/backend/.env` 
+<!-- - **Frontend**: `src/frontend.env` 
+- **MCP Server**: `src/mcp_sevrer/.env`  -->
+
+
+## Step 1: Prerequisites - Install Required Tools
+
+### Windows Development
+
+#### Option 1: Native Windows (PowerShell)
+
+```powershell
+# Install Python 3.12+ and Git
+winget install Python.Python.3.12
+winget install Git.Git
+
+# Install Node.js for frontend
+winget install OpenJS.NodeJS.LTS
+
+# Install uv package manager
+py -3.12 -m pip install uv
+```
+
+**Note**: On Windows, use `py -3.12 -m uv` instead of `uv` for all commands to ensure you're using Python 3.12.
+
+#### 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 python3.12 python3.12-venv git curl nodejs npm -y
+
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source ~/.bashrc
+```
+
+### Linux Development
+
+#### Ubuntu/Debian
+
+```bash
+# Install prerequisites
+sudo apt update && sudo apt install python3.12 python3.12-venv git curl nodejs npm -y
+
+# Install uv package manager
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source ~/.bashrc
+```
+
+#### RHEL/CentOS/Fedora
+
+```bash
+# Install prerequisites
+sudo dnf install python3.12 python3.12-devel git curl gcc nodejs npm -y
+
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source ~/.bashrc
+```
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator.git
+cd Multi-Agent-Custom-Automation-Engine-Solution-Accelerator
+```
+
+## Step 2: Development Tools Setup
+
+### Visual Studio Code (Recommended)
+
+#### Required Extensions
+
+Create `.vscode/extensions.json` in the workspace root and copy the following JSON:
+
+```json
+{
+    "recommendations": [
+        "ms-python.python",
+        "ms-python.pylint",
+        "ms-python.black-formatter",
+        "ms-python.isort",
+        "ms-vscode-remote.remote-wsl",
+        "ms-vscode-remote.remote-containers",
+        "redhat.vscode-yaml",
+        "ms-vscode.azure-account",
+        "ms-python.mypy-type-checker"
+    ]
+}
+```
+
+VS Code will prompt you to install these recommended extensions when you open the workspace.
+
+#### Settings Configuration
+
+Create `.vscode/settings.json` and copy the following JSON:
+
+```json
+{
+    "python.defaultInterpreterPath": "${workspaceFolder}/src/backend/.venv/Scripts/python.exe",
+    "python.terminal.activateEnvironment": true,
+    "python.linting.enabled": true,
+    "python.linting.pylintEnabled": false,
+    "python.linting.flake8Enabled": true,
+    "python.formatting.provider": "black",
+    "python.debugging.logLevel": "Debug",
+    "debug.terminal.clearBeforeReusing": true,
+    "debug.onTaskErrors": "showErrors",
+    "debug.showBreakpointsInOverviewRuler": true,
+    "debug.inlineValues": "on",
+    "files.exclude": {
+        "**/__pycache__": true,
+        "**/*.pyc": true
+    },
+    "python.analysis.extraPaths": [
+        "${workspaceFolder}/src/backend",
+        "${workspaceFolder}/src/mcp_server"
+    ],
+    "folders": [
+        {
+            "name": "Backend",
+            "path": "./src/backend"
+        },
+        {
+            "name": "MCP Server", 
+            "path": "./src/mcp_server"
+        },
+        {
+            "name": "Frontend",
+            "path": "./src/frontend"
+        }
+    ]
+}
+```
+
+## Step 3: Azure Authentication Setup
+
+Before configuring services, authenticate with Azure:
+
+```bash
+# Login to Azure CLI
+az login
+
+# Set your subscription
+az account set --subscription "your-subscription-id"
+
+# Verify authentication
+az account show
+```
+
+
+### Required Azure RBAC Permissions
+
+To run the application locally, your Azure account needs the following role assignments on the deployed resources:
+
+The **main.bicep** deployment includes the assignment of the appropriate roles to AOAI, Storage account, Search service and Cosmos services. If you want to use resource group which is not deployed by you for local debugging—you will need to add your own credentials to access the Cosmos Storage account, Search service and AOAI services. You can add these permissions using the following commands:
+
+#### Get Principal Id
+```bash
+az ad signed-in-user show --query id -o tsv
+```
+
+#### Cosmos DB Access
+```bash
+# Assign Cosmos DB Built-in Data Contributor role
+az cosmosdb sql role assignment create --resource-group <solution-accelerator-rg> --account-name <cosmos-db-account-name> --role-definition-name "Cosmos DB Built-in Data Contributor" --principal-id <aad-user-object-id> --scope /subscriptions/<subscription-id>/resourceGroups/<solution-accelerator-rg>/providers/Microsoft.DocumentDB/databaseAccounts/<cosmos-db-account-name>
+```
+
+#### AI Foundry access
+
+```bash
+az role assignment create --assignee <aad-user-upn> --role "Azure AI User" --scope /subscriptions/<subscription-id>/resourceGroups/<solution-accelerator-rg>/providers/Microsoft.CognitiveServices/accounts/<azure-ai-foundry-name>
+```
+
+```bash
+az role assignment create --assignee <aad-user-upn> --role " Azure AI Developer " --scope /subscriptions/<subscription-id>/resourceGroups/<solution-accelerator-rg>/providers/Microsoft.CognitiveServices/accounts/<azure-ai-foundry-name> 
+```
+
+```bash
+az role assignment create --assignee <aad-user-upn> --role " Cognitive Services OpenAI User " --scope /subscriptions/<subscription-id>/resourceGroups/<solution-accelerator-rg>/providers/Microsoft.CognitiveServices/accounts/<azure-ai-foundry-name> 
+```
+
+#### Search Service Access
+
+ ```bash
+az role assignment create --assignee <aad-user-upn> --role "Search Index Data Contributor" --scope /subscriptions/ <subscription-id> /resourceGroups/ <solution-accelerator-rg> /providers/Microsoft.Search/searchServices/<Search-service-name> 
+```
+
+#### Storage Account Access
+
+```bash
+az role assignment create --assignee <aad-user-upn> --role "Storage Blob Data Contributor" --scope /subscriptions/ <subscription-id> /resourceGroups/ <solution-accelerator-rg> /providers/Microsoft.Storage/storageAccounts/<storage-account-name> 
+```
+
+
+**Note**: RBAC permission changes can take 5-10 minutes to propagate. If you encounter "Forbidden" errors after assigning roles, wait a few minutes and try again.
+
+## Step 4: Backend Setup & Run Instructions
+
+> **📋 Terminal Reminder**: Open a **dedicated terminal window (Terminal 1)** for the Backend service. All commands in this section assume you start from the **repository root directory**.
+
+### 4.1. Navigate to Backend Directory
+
+```bash
+cd src/backend
+```
+
+### 4.2. Configure Backend Environment Variables
+
+Create a `.env` file in the `src/backend` directory:
+
+```bash
+# Create .env file
+touch .env  # Linux
+# or
+New-Item .env  # Windows PowerShell
+```
+
+Add the following to the `.env` file:
+
+- Copy all the values from `.env.example` (CTRL + A) and (CTRL +C)
+- Paste all copied value to `.env` (CTRL + V)
+
+Get All the values from the Backend container app from Azure portal
+
+- Go to your resource group
+- open the backend container
+- Go to Environment varibles of conrainers
+
+For reference, see the image below:
+![Environment_varibles_example](./images/Environment_varibles_example.png)
+
+- Make sure to set APP_ENV to "**dev**"
+   - Keep Below variables as it is from `.env.example`.
+     - `BACKEND_API_URL=http://localhost:8000`
+     - `FRONTEND_SITE_NAME=http://127.0.0.1:3000` 
+     - `MCP_SERVER_ENDPOINT=http://localhost:9000/mcp`
+
+### 4.3. Install Backend Dependencies
+
+```bash
+# Create and activate virtual environment
+uv venv .venv
+
+# Activate virtual environment
+source .venv/bin/activate  # Linux/WSL2
+# or
+.\.venv\Scripts\Activate.ps1  # Windows PowerShell
+
+# Install dependencies
+uv sync --python 3.12
+```
+
+**Windows users**: If you encounter issues with the `uv` command not being found, use the Python Launcher instead:
+
+```powershell
+# Create virtual environment
+py -3.12 -m uv venv .venv
+
+# Install dependencies
+py -3.12 -m uv sync
+```
+
+> **⚠️ Important**: Always run `uv sync` (or `py -3.12 -m uv sync` on Windows) after creating the virtual environment to install all required dependencies. Missing dependencies will cause runtime errors like `ModuleNotFoundError: No module named 'pydantic'` or DNS resolution failures.
+
+### 4.4. Run the Backend
+
+```bash
+python app_kernel.py
+```
+
+The Backend API will start at:
+- API: `http://localhost:8000`
+- API Documentation: `http://localhost:8000/docs`
+
+## Step 5: MCP Server Setup & Run Instructions
+
+> **📋 Terminal Reminder**: Open a **second dedicated terminal window (Terminal 2)** for the MCP Server. Keep Terminal 1 (Backend) running. All commands assume you start from the **repository root directory**.
+
+
+### 5.1. Navigate to MCP Server Directory
+
+```bash
+# From repository root
+cd src/mcp_server
+```
+
+<!-- ### 5.2. Configure Backend API Environment Variables
+
+Create a `.env` file in the `src/backend-api/src/app` directory:
+
+```bash
+cd src/app
+
+# Copy the example file
+cp .env.example .env  # Linux
+# or
+Copy-Item .env.example .env  # Windows PowerShell
+```
+
+Edit the `.env` file with your Azure configuration values. -->
+
+### 5.2. Install MCP Server Dependencies
+
+```bash
+# Create and activate virtual environment
+uv venv .venv
+
+# Activate virtual environment
+source .venv/bin/activate  # Linux/WSL2
+# or
+.\.venv\Scripts\Activate.ps1  # Windows PowerShell
+
+# Install dependencies
+uv sync --python 3.12
+```
+
+### 5.3. Run the MCP Server
+
+```bash
+
+# Run with uvicorn
+python mcp_server.py --transport streamable-http --host 0.0.0.0 --port 9000
+```
+
+## Step 6: Frontend (UI) Setup & Run Instructions
+
+> **📋 Terminal Reminder**: Open a **third dedicated terminal window (Terminal 3)** for the Frontend. Keep Terminals 1 (Backend) and 2 (MCP Server) running. All commands assume you start from the **repository root directory**.
+
+The UI is located under `src/frontend`.
+
+### 6.1. Navigate to Frontend Directory
+
+```bash
+# From repository root
+cd src/frontend
+```
+
+
+
+### 6.3. Install UI Dependencies
+
+```bash
+
+python -m venv .venv
+
+# Activate virtual environment
+source .venv/bin/activate  # Linux/WSL2
+# or
+.\.venv\Scripts\Activate.ps1  # Windows PowerShell
+
+
+pip install -r requirements.txt
+```
+
+
+```bash
+npm install
+```
+
+### 6.4. Build the UI
+
+```bash
+npm run build
+```
+
+### 6.5. Start Development Server
+
+```bash
+python frontend_server.py
+```
+
+The app will start at:
+
+```
+http://localhost:3000
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Python Version Issues
+
+```bash
+# Check available Python versions
+python3 --version
+python3.12 --version
+
+# If python3.12 not found, install it:
+# Ubuntu: sudo apt install python3.12
+# Windows: winget install Python.Python.3.12
+```
+
+#### Virtual Environment Issues
+
+```bash
+# Recreate virtual environment
+rm -rf .venv  # Linux
+# or Remove-Item -Recurse .venv  # Windows PowerShell
+
+uv venv .venv
+# Activate and reinstall
+source .venv/bin/activate  # Linux
+# or .\.venv\Scripts\Activate.ps1  # Windows
+uv sync --python 3.12
+```
+
+#### Permission Issues (Linux)
+
+```bash
+# Fix ownership of files
+sudo chown -R $USER:$USER .
+
+# Fix uv permissions
+chmod +x ~/.local/bin/uv
+```
+
+#### Windows-Specific Issues
+
+```powershell
+# PowerShell execution policy
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+# Long path support (Windows 10 1607+, run as Administrator)
+New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
+
+# SSL certificate issues
+pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org uv
+```
+
+### Environment Variable Issues
+
+```bash
+# Check environment variables are loaded
+env | grep AZURE  # Linux
+Get-ChildItem Env:AZURE*  # Windows PowerShell
+
+# Validate .env file format
+cat .env | grep -v '^#' | grep '='  # Should show key=value pairs
+```
+
+## Step 7: Verify All Services Are Running
+
+Before using the application, confirm all three services are running in separate terminals:
+
+### Terminal Status Checklist
+
+| Terminal | Service | Command | Expected Output | URL |
+|----------|---------|---------|-----------------|-----|
+| **Terminal 1** | Backend | `python app_kernel.py` | `INFO: Application startup complete.`  | http://localhost:8000 |
+| **Terminal 2** | MCP Server | `python mcp_server.py --transport streamable-http --host 0.0.0.0 --port 9000` | `INFO: Uvicorn running on http://0.0.0.0:9000 (Press CTRL+C to quit)` | http://localhost:9000 |
+| **Terminal 3** | Frontend | `python frontend_server.py` | `Local: http://localhost:3000/` | http://localhost:3000 |
+
+### Quick Verification
+
+**1. Check Backend :**
+- Look at Terminal 1 output
+- Should see regular messages: `INFO: Application startup complete.`
+- No error messages
+
+**2. Check MCP Server:**
+- Look at Terminal 2 output
+- Should see regular polling messages: `INFO: Uvicorn running on http://0.0.0.0:9000 (Press CTRL+C to quit)`
+- No error messages
+
+**3. Check Frontend:**
+- Open browser to http://localhost:3000
+- Should see the Application UI
+
+
+### Common Issues
+
+**Service not starting?**
+- Ensure you're in the correct directory
+- Verify virtual environment is activated (Python services)
+- Check that port is not already in use (8000 for API, 3000 for frontend, 9000 for MCP server)
+- Review error messages in the terminal
+
+**Can't access services?**
+- Verify firewall isn't blocking ports 8000 or 3000 or 9000
+- Try `http://localhost:port` instead of `http://127.0.0.1:port`
+- Ensure services show "startup complete" messages
+
+## Step 8: Next Steps
+
+Once all services are running (as confirmed in Step 7), you can:
+
+1. **Access the Application**: Open `http://localhost:3000` in your browser to explore the frontend UI
+2. **Try a Sample Workflow**: Follow [SampleWorkflow.md](SampleQuestions.md) for a guided walkthrough of the Multi agent process.
+3. **Explore the Codebase**: Start with `src/app_kernel.py` to understand the code base
+
+
+## Related Documentation
+
+- [Deployment Guide](DeploymentGuide.md) - Production deployment instructions
+
+
diff --git a/docs/images/Deployment_success_message.png b/docs/images/Deployment_success_message.png
new file mode 100644
index 000000000..7d8f9d948
Binary files /dev/null and b/docs/images/Deployment_success_message.png differ
diff --git a/docs/images/Environment_varibles_example.png b/docs/images/Environment_varibles_example.png
new file mode 100644
index 000000000..47e78a14e
Binary files /dev/null and b/docs/images/Environment_varibles_example.png differ
diff --git a/docs/images/vscodeweb_intialize.png b/docs/images/vscodeweb_intialize.png
new file mode 100644
index 000000000..1ef8ce817
Binary files /dev/null and b/docs/images/vscodeweb_intialize.png differ
diff --git a/src/backend/.env.sample b/src/backend/.env.sample
index 4edd6e845..c14835118 100644
--- a/src/backend/.env.sample
+++ b/src/backend/.env.sample
@@ -3,41 +3,32 @@ COSMOSDB_DATABASE=macae
 COSMOSDB_CONTAINER=memory
 
 AZURE_OPENAI_ENDPOINT=
-AZURE_OPENAI_MODEL_NAME=gpt-4o
-AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
-AZURE_OPENAI_API_VERSION=2024-08-01-preview
+AZURE_OPENAI_MODEL_NAME=gpt-4.1-mini
+AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4.1-mini
+AZURE_OPENAI_API_VERSION=2024-12-01-preview
 
 APPLICATIONINSIGHTS_INSTRUMENTATION_KEY=
-AZURE_AI_PROJECT_ENDPOINT=
 AZURE_AI_SUBSCRIPTION_ID=
 AZURE_AI_RESOURCE_GROUP=
 AZURE_AI_PROJECT_NAME=
-AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4.1-mini
 APPLICATIONINSIGHTS_CONNECTION_STRING=
-AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME=gpt-4o
+AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME=gpt-4.1-mini
 AZURE_COGNITIVE_SERVICES="https://cognitiveservices.azure.com/.default"
 AZURE_AI_AGENT_ENDPOINT=
 # AZURE_BING_CONNECTION_NAME=
-REASONING_MODEL_NAME=o3
+REASONING_MODEL_NAME="o4-mini"
 APP_ENV=dev
-MCP_SERVER_ENDPOINT=http://localhost:8080/mcp
-MCP_SERVER_NAME=MyMC
-MCP_SERVER_DESCRIPTION=My MCP Server
-TENANT_ID=
-CLIENT_ID=
+MCP_SERVER_ENDPOINT=http://localhost:9000/mcp
+MCP_SERVER_NAME=MacaeMcpServer
+MCP_SERVER_DESCRIPTION="MCP server with greeting, HR, and planning tools"
+AZURE_TENANT_ID=
+AZURE_CLIENT_ID=
 BACKEND_API_URL=http://localhost:8000
-FRONTEND_SITE_NAME=
+FRONTEND_SITE_NAME=*
 SUPPORTED_MODELS='["o3","o4-mini","gpt-4.1","gpt-4.1-mini"]'
 AZURE_AI_SEARCH_CONNECTION_NAME=
 AZURE_AI_SEARCH_INDEX_NAME=
 AZURE_AI_SEARCH_ENDPOINT=
 AZURE_AI_SEARCH_API_KEY=
 BING_CONNECTION_NAME=
-
-# Basic application logging (default: INFO level)
-AZURE_BASIC_LOGGING_LEVEL=INFO
-# Azure package logging (default: WARNING level to suppress INFO)
-AZURE_PACKAGE_LOGGING_LEVEL=WARNING
-# Comma-separated list of specific logger names to configure (default: empty - no custom loggers)
-# Example: AZURE_LOGGING_PACKAGES=azure.identity.aio._internal,azure.monitor.opentelemetry.exporter.export._base
-AZURE_LOGGING_PACKAGES=