chore: Added docs & guides for workshop

Author: Avijit-Microsoft

.github/workflows/deploy-docs.yml

@@ -0,0 +1,53 @@
+name: Deploy Workshop Docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs mkdocs-material pymdown-extensions
+
+      - name: Build site
+        run: |
+          cd workshop
+          mkdocs build --site-dir ../site
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

workshop/README.md

@@ -0,0 +1,62 @@
+# Workshop Documentation
+
+This folder contains the MkDocs documentation for the Foundry IQ + Fabric IQ Workshop.
+
+## Local Development
+
+### Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### Serve Locally
+
+```bash
+mkdocs serve
+```
+
+Open [http://127.0.0.1:8000](http://127.0.0.1:8000) to preview.
+
+### Build Static Site
+
+```bash
+mkdocs build
+```
+
+Output is in the `site/` folder.
+
+## Deploy to GitHub Pages
+
+```bash
+mkdocs gh-deploy
+```
+
+This builds the site and pushes to the `gh-pages` branch.
+
+## Structure
+
+```
+workshop/
+├── mkdocs.yml              # MkDocs configuration
+├── requirements.txt        # Python dependencies
+├── README.md              # This file
+└── docs/
+    ├── index.md           # Overview
+    ├── get-started.md     # Prerequisites & PoC journey
+    ├── 01-deploy/         # Deploy Solution
+    │   ├── index.md
+    │   ├── infrastructure.md
+    │   ├── configure.md
+    │   └── run.md
+    ├── 02-customize/      # Customize for Your Customer
+    │   ├── index.md
+    │   ├── choose.md
+    │   ├── generate.md
+    │   └── demo.md
+    ├── 03-understand/     # Understand the Technology
+    │   ├── index.md
+    │   ├── foundry-iq.md
+    │   └── fabric-iq.md
+    └── 04-cleanup.md      # Cleanup & Next Steps
+```

workshop/docs/00-get-started/index.md

@@ -0,0 +1,30 @@
+# Get Started
+
+## Prerequisites
+
+- Azure subscription with Contributor access
+- gpt-4o-mini and text-embedding-ada-002 model capacity
+- Microsoft Fabric workspace (for Fabric IQ features)
+
+- [Visual Studio Code](https://code.visualstudio.com/download)
+- [Azure Developer CLI (azd)](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd)
+- [Python 3.10+](https://www.python.org/downloads/)
+- [Git](https://git-scm.com/downloads)
+
+
+[![Open in GitHub Codespaces](https://img.shields.io/badge/GitHub-Codespaces-blue?logo=github)](https://codespaces.new/nchandhi/nc-iq-workshop)
+[![Open in VS Code](https://img.shields.io/badge/VS%20Code-Dev%20Containers-blue?logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/nchandhi/nc-iq-workshop)
+[![Open in VS Code Web](https://img.shields.io/badge/VS%20Code-Open%20in%20Web-blue?logo=visualstudiocode)](https://vscode.dev/azure/?vscode-azure-exp=foundry&agentPayload=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9uY2hhbmRoaS9uYy1pcS13b3Jrc2hvcC9tYWluL2luZnJhL3ZzY29kZV93ZWIiLCAiaW5kZXhVcmwiOiAiL2luZGV4Lmpzb24iLCAidmFyaWFibGVzIjogeyJhZ2VudElkIjogIiIsICJjb25uZWN0aW9uU3RyaW5nIjogIiIsICJ0aHJlYWRJZCI6ICIiLCAidXNlck1lc3NhZ2UiOiAiIiwgInBsYXlncm91bmROYW1lIjogIiIsICJsb2NhdGlvbiI6ICIiLCAic3Vic2NyaXB0aW9uSWQiOiAiIiwgInJlc291cmNlSWQiOiAiIiwgInByb2plY3RSZXNvdXJjZUlkIjogIiIsICJlbmRwb2ludCI6ICIifSwgImNvZGVSb3V0ZSI6IFsiYWktcHJvamVjdHMtc2RrIiwgInB5dGhvbiIsICJkZWZhdWx0LWF6dXJlLWF1dGgiLCAiZW5kcG9pbnQiXX0=)
+
+!!! tip "Use GitHub Copilot for Help"
+    Stuck on a step? Ask GitHub Copilot Chat:
+    
+    - "Explain this error message"
+    - "What does this script do?"
+    - "How do I fix this Python error?"
+    
+    Press `Ctrl+I` in VS Code to open Copilot Chat.
+
+---
+
+[Workshop Flow →](workshop-flow.md)

workshop/docs/00-get-started/workshop-flow.md

@@ -0,0 +1,40 @@
+# Workshop Flow
+
+## Step 1: Deploy solution
+
+Deploy infrastructure and run with pre-built **sample** scenario:
+
+- Deploy **Microsoft Foundry** and Azure resources (AI Services, AI Search, Storage)
+- Configure **Microsoft Fabric** connection
+- Configure your development environment
+- See the agent working with sample data
+- Takes ~15 minutes
+
+## Step 2: Customize for your use case
+
+Generate custom data for **each use case**:
+
+| Customer Industry | Use Case Example | Sample Questions |
+|-------------------|------------------|------------------|
+| Telecommunications | Network outages + service policies | "Which outages exceeded our SLA threshold?" |
+| Manufacturing | Equipment data + maintenance docs | "Which machines are overdue for maintenance per our schedule?" |
+| Retail | Product catalog + return policies | "What's our return policy for electronics over $500?" |
+| Finance | Account data + lending policies | "Which loan applications meet our approval criteria?" |
+| Insurance | Claims data + policy documents | "What's the status of claims filed this week vs our SLA?" |
+| Energy | Grid monitoring + safety protocols | "Which substations are operating above 80% capacity?" |
+| **Customer X** | **Their data + Their docs** | **Their burning questions** |
+
+!!! tip "Pre-PoC prep"
+    Run Step 2 before your PoC. Enter the industry and a brief use case description. The AI generates realistic sample data, documents, and test questions tailored to your scenario.
+
+## Step 3: Deep dive
+
+Prepare for technical questions in customer conversations:
+
+- **Fabric IQ**: How ontology translates business questions to SQL
+- **Foundry IQ**: How agentic retrieval plans, iterates, and reflects
+- **Orchestrator Agent**: How the agent decides which source to query
+
+---
+
+[← Get Started](index.md) | [Deploy solution →](../01-deploy/index.md)

workshop/docs/01-deploy/01-deploy-azure.md

@@ -0,0 +1,47 @@
+# Deploy Infrastructure
+
+## Clone the Repository
+
+```bash
+git clone https://github.com/nchandhi/nc-iq-workshop.git
+cd nc-iq-workshop
+```
+
+## Login to Azure
+
+```bash
+azd auth login
+```
+
+This opens a browser for authentication.
+
+## Deploy Resources
+
+```bash
+azd up
+```
+
+Follow the prompts to select your environment name, subscription, and location etc.
+
+!!! warning "Wait for Completion"
+    Deployment takes 7-8 minutes. Don't proceed until you see the success message.
+
+## Verify Deployment
+
+Verify in [Azure Portal](https://portal.azure.com/) that your resource group contains all resources:
+
+- Microsoft Foundry
+- Azure AI Search
+- Storage Account
+- Application Insights
+
+## Environment Variables
+
+After deployment, Azure endpoints are automatically saved to `.azure/<env>/.env` and loaded by the scripts.
+
+!!! note "No Manual Configuration"
+    You don't need to manually set Azure connection strings. The scripts read them from the azd environment automatically.
+
+---
+
+[← Overview](index.md) | [Create Fabric workspace →](02-setup-fabric.md)

workshop/docs/01-deploy/02-setup-fabric.md

@@ -0,0 +1,34 @@
+# Create Fabric workspace
+
+Create and configure your Microsoft Fabric workspace for Fabric IQ.
+
+## Prerequisites
+
+- Microsoft Fabric capacity (F2 or higher recommended)
+- Workspace admin permissions
+
+## Create a Fabric workspace
+
+1. Go to [Microsoft Fabric](https://app.fabric.microsoft.com)
+2. Click **Workspaces** → **New workspace**
+3. Name it something like `iq-workshop`
+4. Select your Fabric capacity
+5. Click **Apply**
+
+## Configure workspace settings
+
+1. Open your new workspace
+2. Go to **Settings** → **License info**
+3. Verify the workspace is using Fabric capacity
+
+## Get workspace details
+
+You'll need these values for the next step:
+
+| Setting | Where to find it |
+|---------|------------------|
+| Workspace ID | URL after `/groups/` |
+| Workspace name | Workspace settings |
+
+
+[← Deploy Azure resources](01-deploy-azure.md) | [Configure dev environment →](03-configure.md)

workshop/docs/01-deploy/03-configure.md

@@ -0,0 +1,88 @@
+# Configure dev environment
+
+## Python Environment
+
+### Create and Activate
+
+```bash
+cd scripts
+python -m venv .venv
+```
+
+=== "Windows"
+
+    ```powershell
+    .venv\Scripts\activate
+    ```
+
+=== "macOS/Linux"
+
+    ```bash
+    source .venv/bin/activate
+    ```
+
+### Install Dependencies
+
+=== "Fast (Recommended)"
+
+    ```bash
+    pip install uv && uv pip install -r requirements.txt
+    ```
+
+=== "Standard"
+
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+### Verify Setup
+
+```bash
+python -c "import azure.ai.projects; print('Ready!')"
+```
+
+## Configure Fabric
+
+### Get Your Workspace ID
+
+1. Go to [Microsoft Fabric](https://app.fabric.microsoft.com/)
+2. Open your workspace
+3. Copy the workspace ID from the URL:
+
+```
+https://app.fabric.microsoft.com/groups/{workspace-id}/...
+```
+
+### Update Environment File
+
+Copy `.env.example` to `.env` and update your Fabric settings:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` in the project root:
+
+```env
+# --- Microsoft Fabric (required) ---
+FABRIC_WORKSPACE_ID=your-workspace-id-here
+
+# --- Data Folder (pre-populated with default scenario) ---
+DATA_FOLDER=data/default
+```
+
+## Checkpoint
+
+Before proceeding:
+
+- [x] `azd up` completed successfully
+- [x] Python environment activated
+- [x] Dependencies installed
+- [x] Fabric workspace ID configured
+
+!!! success "Ready to Run"
+    Continue to the next step to see it in action.
+
+---
+
+[← Create Fabric workspace](02-setup-fabric.md) | [Build solution →](04-run-scenario.md)