refactor docs/ folder

Author: nitya

.github/prompts/01-setup-mcp.prompt.md

@@ -0,0 +1,22 @@
+---
+mode: agent
+---
+Define the task to achieve, including specific requirements, constraints, and success criteria.
+
+# Task
+
+1. If the `.vscode` directory does not exist in the root of the repository, create it.
+2. Inside the `.vscode` directory, create a file named `mcp.json` if it does not already exist.
+3. Populate the `mcp.json` file with the following JSON content:
+
+```json
+{
+	"servers": {
+		"microsoft.docs.mcp": {
+			"url": "https://learn.microsoft.com/api/mcp",
+			"type": "http"
+		}
+	},
+	"inputs": []
+}
+```

.gitignore

@@ -418,4 +418,4 @@ FodyWeavers.xsd
 *.msp
 
 #mkdocs static site 
-site/
+site/*

data/Place data for your session into this folder

@@ -1,75 +1,114 @@
 # 1.1 Provision Infra
 
+!!! quote "BY THE END OF THIS LAB YOU SHOULD HAVE"
+
+    - [X] Set your tab preference (Instructor-Led or Self-Guided)
+    - [X] Launched GitHub Codespaces (and setup local environment)
+    - [X] Provisioned Infrastructure (to get an Azure AI Foundry project)
+
+---
+
+## Before You Begin
+
+These instructions are setup to support both instructor-led training (in-venue, with pre-provisioned subscription) and self-guided learning (at home, with your subscription). The primary difference will be in the initial setup. 
+
+**Pick the tab that best represents you right now** ⬇️
+
+=== "Instructor-Led (In Venue)"
+
+    !!! info "I am currently in the Microsoft Ignite 2025 Pre-Day Workshop (4h Session)"
+
+=== "Self-Guided (At Home)"
+
+    !!! note "I am working through the lab at home, with my subscription (Self-Paced)"
+
+---
+
+<!---
 We will provision the AZD "Get Started with AI Agents" template as our infrastructure. These notes correspond to [this commit](https://github.com/nitya/get-started-with-ai-agents/commit/c63e1384ae6a295b3d57378fab02ac4227bf835d) on the AZD template repo. My goal is to document the usage and customization of this template to support various projects - as pre-provisioned infrastructure.
+-->
+
+## Provision Infrastructure
+
+By the end of this step, you should have an Azure subscription setup with the required resources for this project - which includes an Azure AI Foundry project, AI model deployments, an Azure AI Search service resource - and a default agent with a frontend app.
+
+=== "Instructor-Led (In Venue)"
+
+    !!! success "You should have a pre-provisioned Azure subscription - check the [Azure Portal](https://portal.azure.com)"
 
-<br/>
+=== "Self-Guided (At Home)"
 
-## 0. Fork Template & Launch Codespaces
+    ??? task "STEP 1: You need to provision the infrastructure - get the template!"
 
-1. Visit the [Get Started With AI Agents](https://github.com/Azure-Samples/get-started-with-ai-agents) repo 
-1. Fork it to your profile to get a custom copy (.e., [my fork-branch](https://github.com/nitya/get-started-with-ai-agents/tree/sep2025-pdy123-infra))
-1. Launch GitHub Codespaces on your fork
-1. Wait till the browser VS Code loads - and an active terminal appears.
+        1. Visit the [Get Started With AI Agents](https://github.com/Azure-Samples/get-started-with-ai-agents) repo 
+        1. Fork it to your profile to get a custom copy (.e., [my fork-branch](https://github.com/nitya/get-started-with-ai-agents/tree/sep2025-pdy123-infra))
+        1. Launch GitHub Codespaces on your fork
+        1. Wait till the browser VS Code loads - and an active terminal appears.
 
-_You are ready to deploy the template_
+        _You are ready to deploy the template_
 
+    ??? task "STEP 2: You need customize template - setup env variables!"
 
-## 1. Set AZD Env Variables
+        The azd template can be customized in many ways - the easiest starting point is to use environment variables to customize the resource deployment paramters. Run these commands in the Codespaces terminal.  _Note: Pick unique names for the last 2 variables that set the Foundry project and resource names in Azure AI Foundry Portal_
 
-The azd template can be customized in many ways - the easiest starting point is to use environment variables to customize the resource deployment paramters. Run these commands in the Codespaces terminal.  _Note: Pick unique names for the last 2 variables that set the Foundry project and resource names in Azure AI Foundry Portal_
+        ```bash
+        azd env set AZURE_AI_AGENT_DEPLOYMENT_CAPACITY 100
+        azd env set ENABLE_AZURE_MONITOR_TRACING true
+        azd env set AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED true
+        azd env set USE_AZURE_AI_SEARCH_SERVICE true
+        azd env set USE_APPLICATION_INSIGHTS true
+        azd env set AZURE_AIPROJECT_NAME nitya-pdy123-aiproj-v1
+        azd env set AZURE_AISERVICES_NAME nitya-pdy123-aisvcs-v1
+        ```
+    ??? task "STEP 3: You are ready to deploy it - have your Azure subscription ready!"
 
-```bash
-azd env set AZURE_AI_AGENT_DEPLOYMENT_CAPACITY 100
-azd env set ENABLE_AZURE_MONITOR_TRACING true
-azd env set AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED true
-azd env set USE_AZURE_AI_SEARCH_SERVICE true
-azd env set USE_APPLICATION_INSIGHTS true
-azd env set AZURE_AIPROJECT_NAME nitya-pdy123-aiproj-v1
-azd env set AZURE_AISERVICES_NAME nitya-pdy123-aisvcs-v1
-```
+        You should already have the Azure Developer CLI (`azd`) tool installed in the GitHub Codespaces environment. Provisioning and deployment is now just a single command:
 
-## 2. Deploy it
+        ```title="" linenums="0"
+        azd up
+        ```
 
-```bash
-azd up
-```
+        Note that we did not have to authenticate beforehand! This command will prompt you to do so, using a device-code workflow that looks something like this:
 
-Note that we did not do any pre-authentication step. So we'll get prompted to login using a device-code workflow like this:
+        ```title="" linenums="0"
+        ? Would you like to log in now? Yes
 
-```bash
-? Would you like to log in now? Yes
+        Start by copying the next code: XXXXXXX
+        Then press enter and continue to log in from your browser...
+        ```
 
-Start by copying the next code: XXXXXXX
-Then press enter and continue to log in from your browser...
-```
+        Next you'll be prompted to select your subscription and the region for deployment. I used `East US2`. 
+        
+    ??? task "STEP 4: Wait for the provisioning to complete - it can take 10-15 mins!"
 
-Next you'll be prompted to select your subscription and the region for deployment. I used `East US2`. Then just let the provisioning complete. **This can take 10-15 minutes given our added requirements** - the default (basic) template provisions in 4-6 minutes. _The output looks like this - the first section provisions resources, the second deploys the app_.
+        You can track the deployments status in the Azure Portal (at the link you will see in your console logs). Wait for the **SUCCESS** message to ensure provisioning is done.
 
-```bash
-You can view detailed progress in the Azure Portal:
-<url here>
+        ```title="" linenums="0"
+        You can view detailed progress in the Azure Portal:
+        <url here>
 
-(✓) Done: Resource group: rg-nitya-pdy123-azd-v1 (447ms)
-(✓) Done: Log Analytics workspace: log-vchqcvq7rwoju (22.557s)
-(✓) Done: Storage account: stvchqcvq7rwoju (20.675s)
-(✓) Done: Application Insights: appi-vchqcvq7rwoju (3.537s)
-(✓) Done: Azure AI Services: nitya-pdy123-aisvcs-v1 (1m8.574s)
-(✓) Done: Azure AI Services Model Deployment: nitya-pdy123-aisvcs-v1/text-embedding-3-small (1m10.589s)
-(✓) Done: Azure AI Services Model Deployment: nitya-pdy123-aisvcs-v1/gpt-4o-mini (1m10.027s)
-(✓) Done: Search service: srch-vchqcvq7rwoju (4m50.479s)
-(✓) Done: Container Registry: crvchqcvq7rwoju (19.98s)
-(✓) Done: Container Apps Environment: containerapps-env-vchqcvq7rwoju (1m24.269s)
-(✓) Done: Container App: ca-api-vchqcvq7rwoju (17.742s)
+        (✓) Done: Resource group: rg-nitya-pdy123-azd-v1 (447ms)
+        (✓) Done: Log Analytics workspace: log-vchqcvq7rwoju (22.557s)
+        (✓) Done: Storage account: stvchqcvq7rwoju (20.675s)
+        (✓) Done: Application Insights: appi-vchqcvq7rwoju (3.537s)
+        (✓) Done: Azure AI Services: nitya-pdy123-aisvcs-v1 (1m8.574s)
+        (✓) Done: Azure AI Services Model Deployment: nitya-pdy123-aisvcs-v1/text-embedding-3-small (1m10.589s)
+        (✓) Done: Azure AI Services Model Deployment: nitya-pdy123-aisvcs-v1/gpt-4o-mini (1m10.027s)
+        (✓) Done: Search service: srch-vchqcvq7rwoju (4m50.479s)
+        (✓) Done: Container Registry: crvchqcvq7rwoju (19.98s)
+        (✓) Done: Container Apps Environment: containerapps-env-vchqcvq7rwoju (1m24.269s)
+        (✓) Done: Container App: ca-api-vchqcvq7rwoju (17.742s)
 
-Deploying services (azd deploy)
+        Deploying services (azd deploy)
 
-Deploying service api_and_frontend (Running remote build)
-- Endpoint: https://......eastus2.azurecontainerapps.io/
-────────────── Docker Output ─────────────────────────
+        Deploying service api_and_frontend (Running remote build)
+        - Endpoint: https://......eastus2.azurecontainerapps.io/
+        ────────────── Docker Output ─────────────────────────
 
-──────────────────────────────────────────────────────
+        ──────────────────────────────────────────────────────
 
-💡 (Optional) To setup username and password for the web application, run './scripts/setup_credential.sh'.
+        💡 (Optional) To setup username and password for the web application, run './scripts/setup_credential.sh'.
 
-SUCCESS: Your up workflow to provision and deploy to Azure completed in 11 minutes 50 seconds.
-```
+        SUCCESS: Your up workflow to provision and deploy to Azure completed in 11 minutes 50 seconds.
+        ```
+    !!! success "You should have a pre-provisioned Azure subscription - check the [Azure Portal](https://portal.azure.com)"

docs/Core-Labs/1-Get-Started/01.md

@@ -1,45 +1,10 @@
 # 1.2 Validate Infra
 
-## 1. Test Container App
+!!! quote "BY THE END OF THIS LAB YOU SHOULD HAVE"
 
-Click on the **Endpoint** URL provided in the output - or visit the Azure Portal and look for the Azure Container Apps resource and click the _Application Url_. You should see an agent application like this:
+    - [X] Verified that your Azure AI Foundry project is setup
+    - [X] Ensured that your Azure AI Search index is created
+    - [X] Configured your local `.env` file to reflect deployments
 
-🌟 | Try asking a question like `Tell me about camping tents` - and see what happens.
+---
 
-![Deploy](./img/01-azd-deploy.png)
-
-
-## 2. Visit Agent Dashboard
-
-Click the `Build & deploy agents with Azure AI Foundry` link (bottom left) to navigate to the underlying Agent on the Azure AI Foundry portal. You should see something like this:
-
-🌟 | Select the agent name to see its details. Explore the integrated tools (Knowledge & Actions). Update the Agent description and instructions.
-- Agent name is helpful identification. _Change from "agent-template-assistant" to "cora-for-zava"_. Note how the changes are automatically saved. However, the container app will need to be updated separately.
-- Description is for human users. It does not affect agent behavior. Example: _Cora is a customer support agent for the Zava retail enterprise. Cora helps DIY enthusiasts find and purchase home improvement products in Zava stores._
-- Instructions are for agents. They guide agent actions. Example: _Use AI Search always. Avoid to use base knowledge._ - we'll modify this later.
-
-![Deploy](./img/02-agent-dashboard.png)
-
-Click **Try in playground** to activate the agent for interactive exploration. 
-- See how changes made to description or instructions here are _automatically saved_ so they will be visible to agent detailed view in earlier dashboard.
-- Try asking [a sample question](https://github.com/Azure-Samples/get-started-with-ai-agents/blob/main/docs/sample_questions.md) like _What's the best tent under $200 for two people, and what features does it include?_ 🚨 - fix Azure AI Search. It is not grounded.
-
-![Playground](./img/03-agent-playground.png)
-
-Click the **View Run Info** button. 
-- Note how this opens up a view into the traces for agent execution
-- Explore the waterfall diagram - see how each step provides token counts & time
-- Click on a _Run step_ and a _Tool_ item - how is the output different?
-- Click the _Evaluations_ tab - what does it tell us about quality & safety?
-
-![Tracing](./img/04-agent-tracing.png)
-
-- Close the tracing view - can you see the same token counts and latency metrics in the main view?
-- Hover over one of the numbers e.g., tokens - see the breakdown in token costs
-
-![Metrics](./img/05-agent-metrics.png)
-
-
-![Deploy](./img/06-view-code.png)
-![Deploy](./img/07-open-vscode.png)
-![Deploy](./img/08-explore-project.png)

docs/Core-Labs/1-Get-Started/02.md

@@ -1 +1,54 @@
-# 2.1 Define Agent
+# 2.1 Define Agent
+
+!!! quote "BY THE END OF THIS LAB YOU SHOULD HAVE"
+
+    - [X] Completed Task 1
+    - [X] Completed Task 2
+    - [X] Completed Task 3
+
+---
+
+
+## 1. Test Container App
+
+Click on the **Endpoint** URL provided in the output - or visit the Azure Portal and look for the Azure Container Apps resource and click the _Application Url_. You should see an agent application like this:
+
+🌟 | Try asking a question like `Tell me about camping tents` - and see what happens.
+
+![Deploy](./img/01-azd-deploy.png)
+
+
+## 2. Visit Agent Dashboard
+
+Click the `Build & deploy agents with Azure AI Foundry` link (bottom left) to navigate to the underlying Agent on the Azure AI Foundry portal. You should see something like this:
+
+🌟 | Select the agent name to see its details. Explore the integrated tools (Knowledge & Actions). Update the Agent description and instructions.
+- Agent name is helpful identification. _Change from "agent-template-assistant" to "cora-for-zava"_. Note how the changes are automatically saved. However, the container app will need to be updated separately.
+- Description is for human users. It does not affect agent behavior. Example: _Cora is a customer support agent for the Zava retail enterprise. Cora helps DIY enthusiasts find and purchase home improvement products in Zava stores._
+- Instructions are for agents. They guide agent actions. Example: _Use AI Search always. Avoid to use base knowledge._ - we'll modify this later.
+
+![Deploy](./img/02-agent-dashboard.png)
+
+Click **Try in playground** to activate the agent for interactive exploration. 
+- See how changes made to description or instructions here are _automatically saved_ so they will be visible to agent detailed view in earlier dashboard.
+- Try asking [a sample question](https://github.com/Azure-Samples/get-started-with-ai-agents/blob/main/docs/sample_questions.md) like _What's the best tent under $200 for two people, and what features does it include?_ 🚨 - fix Azure AI Search. It is not grounded.
+
+![Playground](./img/03-agent-playground.png)
+
+Click the **View Run Info** button. 
+- Note how this opens up a view into the traces for agent execution
+- Explore the waterfall diagram - see how each step provides token counts & time
+- Click on a _Run step_ and a _Tool_ item - how is the output different?
+- Click the _Evaluations_ tab - what does it tell us about quality & safety?
+
+![Tracing](./img/04-agent-tracing.png)
+
+- Close the tracing view - can you see the same token counts and latency metrics in the main view?
+- Hover over one of the numbers e.g., tokens - see the breakdown in token costs
+
+![Metrics](./img/05-agent-metrics.png)
+
+
+![Deploy](./img/06-view-code.png)
+![Deploy](./img/07-open-vscode.png)
+![Deploy](./img/08-explore-project.png)

docs/Core-Labs/2-Explore-Agent/01.md

@@ -1 +1,9 @@
-# 2.2 Run Agent
+# 2.2 Run Agent
+
+!!! quote "BY THE END OF THIS LAB YOU SHOULD HAVE"
+
+    - [X] Completed Task 1
+    - [X] Completed Task 2
+    - [X] Completed Task 3
+
+---

docs/Core-Labs/2-Explore-Agent/02.md

@@ -1 +1,9 @@
-# 2.3 Analyze Run
+# 2.3 Analyze Run
+
+!!! quote "BY THE END OF THIS LAB YOU SHOULD HAVE"
+
+    - [X] Completed Task 1
+    - [X] Completed Task 2
+    - [X] Completed Task 3
+
+---