@ivannxbt/ai-config 0.1.0

package/.agents/skills/microsoft-foundry/quota/references/ptu-guide.md

@@ -0,0 +1,150 @@
+# Provisioned Throughput Units (PTU) Guide
+
+## Understanding PTU vs Standard TPM
+
+Microsoft Foundry offers two quota types:
+
+### Standard TPM (Tokens Per Minute)
+- Pay-as-you-go model, charged per token
+- Each deployment consumes capacity units (e.g., 10K TPM, 50K TPM)
+- Total regional quota shared across all deployments
+- Subject to rate limiting during high demand (429 errors possible)
+- Best for: Variable workloads, development, testing, bursty traffic
+
+### Provisioned Throughput Units (PTU)
+- Monthly commitment for guaranteed throughput
+- No rate limiting, consistent latency
+- Measured in PTU units (not TPM)
+- Best for: Predictable, high-volume production workloads
+- More cost-effective when consistent token usage justifies monthly commitment
+
+## When to Use PTU
+
+| Factor | Standard (TPM) | Provisioned (PTU) |
+|--------|----------------|-------------------|
+| **Best For** | Variable workloads, development, testing | Predictable production workloads |
+| **Pricing** | Pay-per-token | Monthly commitment (hourly rate per PTU) |
+| **Rate Limits** | Yes (429 errors possible) | No (guaranteed throughput) |
+| **Latency** | Variable | Consistent |
+| **Cost Decision** | Lower upfront commitment | More economical for consistent, high-volume usage |
+| **Flexibility** | Scale up/down instantly | Requires planning and commitment |
+| **Use Case** | Prototyping, bursty traffic | Production apps, high-volume APIs |
+
+**Use PTU when:**
+- Consistent, predictable token usage where monthly commitment is cost-effective
+- Need guaranteed throughput (no 429 rate limit errors)
+- Require consistent latency with performance SLA
+- High-volume production workloads with stable traffic patterns
+
+**Decision Guidance:**
+Compare your current pay-as-you-go costs with PTU pricing. PTU may be more economical when consistent usage justifies the monthly commitment.
+
+## PTU Capacity Planning
+
+### Official Calculation Methods
+
+> **Agent Instruction:** Only present official Azure capacity calculator methods below. Do NOT generate or suggest estimated PTU formulas, TPM-per-PTU conversion tables, or reference deprecated calculators (oai.azure.com/portal/calculator).
+
+Calculate PTU requirements using these official methods:
+
+**Method 1: Microsoft Foundry Portal**
+1. Navigate to Microsoft Foundry portal
+2. Go to **Operate** → **Quota**
+3. Select **Provisioned throughput unit** tab
+4. Click **Capacity calculator** button
+5. Enter workload parameters (model, tokens/call, RPM, latency target)
+6. Calculator returns exact PTU count needed
+
+**Method 2: Using Azure REST API**
+```bash
+# Calculate required PTU capacity
+curl -X POST "https://management.azure.com/subscriptions/<subscription-id>/providers/Microsoft.CognitiveServices/calculateModelCapacity?api-version=2024-10-01" \
+  -H "Authorization: Bearer <access-token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": {
+      "format": "OpenAI",
+      "name": "gpt-4o",
+      "version": "2024-05-13"
+    },
+    "workload": {
+      "requestPerMin": 100,
+      "tokensPerMin": 50000,
+      "peakRequestsPerMin": 150
+    }
+  }'
+```
+
+## Deploy Model with PTU
+
+### Step 1: Calculate PTU Requirements
+
+Use the official capacity calculator methods above to determine required PTU capacity.
+
+### Step 2: Deploy with PTU
+
+```bash
+# Deploy model with calculated PTU capacity
+az cognitiveservices account deployment create \
+  --name <resource-name> \
+  --resource-group <rg> \
+  --deployment-name gpt-4o-ptu-deployment \
+  --model-name gpt-4o \
+  --model-version "2024-05-13" \
+  --model-format OpenAI \
+  --sku-name ProvisionedManaged \
+  --sku-capacity 100
+
+# Check PTU deployment status
+az cognitiveservices account deployment show \
+  --name <resource-name> \
+  --resource-group <rg> \
+  --deployment-name gpt-4o-ptu-deployment
+```
+
+**Key Differences from Standard TPM:**
+- SKU name: `ProvisionedManaged` (not `Standard`)
+- Capacity: Measured in PTU units (not K TPM)
+- Billing: Monthly commitment regardless of usage
+- No rate limiting (guaranteed throughput)
+
+## Request PTU Quota Increase
+
+PTU quota is separate from TPM quota and requires specific justification:
+
+1. Navigate to Azure Portal → Foundry resource → **Quotas**
+2. Select **Provisioned throughput unit** tab
+3. Identify model needing PTU increase (e.g., "GPT-4o PTU")
+4. Click **Request quota increase**
+5. Fill form:
+   - Model name
+   - Requested PTU quota
+   - Include capacity calculator results in business justification
+   - Explain workload characteristics (volume, latency requirements)
+6. Submit and monitor status
+
+**Processing Time:** Typically 3-5 business days (longer than standard quota requests)
+**Note:** PTU quota requests typically require stronger business justification due to commitment nature
+
+**Alternative:** Deploy to different region with available PTU quota
+
+## Understanding Region and Deployment Quotas
+
+### Region Quota
+- Maximum PTU capacity available in an Azure region
+- Varies by model type (GPT-4, GPT-4o, etc.)
+- Shared across subscription resources in same region
+- Separate from TPM quota (you have both TPM and PTU quotas)
+
+### Deployment Slots
+- Number of concurrent model deployments allowed
+- Typically 10-20 slots per resource
+- Each PTU deployment uses one slot (same as TPM deployments)
+- Deployment count limit is independent of capacity
+
+## External Resources
+
+- [Understanding PTU Costs](https://learn.microsoft.com/azure/ai-foundry/openai/how-to/provisioned-throughput-onboarding)
+- [What Is Provisioned Throughput](https://learn.microsoft.com/azure/ai-foundry/openai/concepts/provisioned-throughput)
+- [Calculate Model Capacity API](https://learn.microsoft.com/rest/api/aiservices/accountmanagement/calculate-model-capacity/calculate-model-capacity?view=rest-aiservices-accountmanagement-2024-10-01&tabs=HTTP)
+- [PTU Overview](https://learn.microsoft.com/azure/ai-services/openai/concepts/provisioned-throughput)

package/.agents/skills/microsoft-foundry/quota/references/troubleshooting.md

@@ -0,0 +1,209 @@
+# Troubleshooting Quota Errors
+
+## Common Quota Errors
+
+| Error | Cause | Quick Fix |
+|-------|-------|-----------|
+| `QuotaExceeded` | Regional quota consumed (TPM or PTU) | Delete unused deployments or request increase |
+| `InsufficientQuota` | Not enough available for requested capacity | Reduce deployment capacity or free quota |
+| `DeploymentLimitReached` | Too many deployment slots used | Delete unused deployments to free slots |
+| `429 Rate Limit` | TPM capacity too low for traffic (Standard only) | Increase TPM capacity or migrate to PTU |
+| `PTU capacity unavailable` | No PTU quota in region | Request PTU quota or try different region |
+| `SKU not supported` | PTU not available for model/region | Check model availability or use Standard TPM |
+
+## Detailed Error Resolution
+
+### QuotaExceeded Error
+
+All available TPM or PTU quota consumed in the region.
+
+**Resolution:**
+
+1. **Check current quota usage:**
+   ```bash
+   subId=$(az account show --query id -o tsv)
+   region="eastus"
+   az rest --method get \
+     --url "https://management.azure.com/subscriptions/$subId/providers/Microsoft.CognitiveServices/locations/$region/usages?api-version=2023-05-01" \
+     --query "value[?contains(name.value,'OpenAI')].{Model:name.value, Used:currentValue, Limit:limit}" -o table
+   ```
+
+2. **Choose resolution:**
+   - **Option A**: Delete unused deployments to free quota
+   - **Option B**: Reduce requested deployment capacity
+   - **Option C**: Deploy to different region with available quota
+   - **Option D**: Request quota increase through Azure Portal
+
+### InsufficientQuota Error
+
+Available quota less than requested capacity.
+
+**Resolution:**
+
+1. **Check available quota:**
+   ```bash
+   # Calculate available: limit - currentValue
+   subId=$(az account show --query id -o tsv)
+   region="eastus"
+   az rest --method get \
+     --url "https://management.azure.com/subscriptions/$subId/providers/Microsoft.CognitiveServices/locations/$region/usages?api-version=2023-05-01" \
+     --query "value[?name.value=='OpenAI.Standard.gpt-4o'].{Model:name.value, Used:currentValue, Limit:limit, Available:(limit-currentValue)}" -o table
+   ```
+
+2. **Options:**
+   - Reduce deployment capacity to fit available quota
+   - Delete existing deployments to free capacity
+   - Try different region with more available quota
+   - Request quota increase
+
+### DeploymentLimitReached Error
+
+Resource reached maximum deployment slot limit (10-20 slots).
+
+**Resolution:**
+
+1. **List existing deployments:**
+   ```bash
+   az cognitiveservices account deployment list \
+     --name <resource-name> \
+     --resource-group <rg> \
+     --query '[].{Name:name, Model:properties.model.name, Capacity:sku.capacity}' \
+     --output table
+   ```
+
+2. **Delete unused deployments:**
+   ```bash
+   az cognitiveservices account deployment delete \
+     --name <resource-name> \
+     --resource-group <rg> \
+     --deployment-name <unused-deployment-name>
+   ```
+
+3. **Verify slot freed:**
+   ```bash
+   az cognitiveservices account deployment list \
+     --name <resource-name> \
+     --resource-group <rg> \
+     --query 'length([])'
+   ```
+
+### 429 Rate Limit Errors
+
+TPM capacity insufficient for traffic volume (Standard TPM only).
+
+**Resolution:**
+
+1. **Check deployment capacity:**
+   ```bash
+   az cognitiveservices account deployment show \
+     --name <resource-name> \
+     --resource-group <rg> \
+     --deployment-name <deployment-name> \
+     --query '{Name:name, Model:properties.model.name, Capacity:sku.capacity, SKU:sku.name}'
+   ```
+
+2. **Options:**
+   - **Option A**: Increase TPM capacity on existing deployment
+     ```bash
+     az cognitiveservices account deployment update \
+       --name <resource-name> \
+       --resource-group <rg> \
+       --deployment-name <deployment-name> \
+       --sku-capacity <higher-capacity>
+     ```
+   - **Option B**: Migrate to PTU for guaranteed throughput (no rate limits)
+   - **Option C**: Implement retry logic with exponential backoff in application
+
+### PTU Capacity Unavailable Error
+
+No PTU quota allocated in region, or PTU not available for model/region.
+
+**Resolution:**
+
+1. **Check PTU quota:**
+   ```bash
+   subId=$(az account show --query id -o tsv)
+   region="eastus"
+   az rest --method get \
+     --url "https://management.azure.com/subscriptions/$subId/providers/Microsoft.CognitiveServices/locations/$region/usages?api-version=2023-05-01" \
+     --query "value[?contains(name.value,'ProvisionedManaged')].{Model:name.value, Used:currentValue, Limit:limit}" -o table
+   ```
+
+2. **Options:**
+   - Request PTU quota increase through Azure Portal (include capacity calculator results)
+   - Try different region where PTU is available
+   - Use Standard TPM instead
+
+### SKU Not Supported Error
+
+PTU not available for specific model or region combination.
+
+**Resolution:**
+
+1. **Check model availability:**
+   - Review [PTU model availability by region](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#provisioned-deployment-model-availability)
+
+2. **Options:**
+   - Deploy with Standard TPM SKU instead
+   - Choose different region where PTU is supported
+   - Use alternative model that supports PTU in your region
+
+## Request Quota Increase Process
+
+### For Standard TPM Quota
+
+1. Navigate to Azure Portal → Your Foundry resource → **Quotas**
+2. Identify model needing increase (e.g., "GPT-4o Standard")
+3. Click **Request quota increase**
+4. Fill form:
+   - Model name
+   - Requested quota (in TPM)
+   - Business justification (required)
+5. Submit and monitor status
+
+**Processing Time:** Typically 1-2 business days
+
+### For PTU Quota
+
+1. Navigate to Azure Portal → Your Foundry resource → **Quotas**
+2. Select **Provisioned throughput unit** tab
+3. Identify model needing PTU increase
+4. Click **Request quota increase**
+5. Fill form:
+   - Model name
+   - Requested PTU quota
+   - Include capacity calculator results
+   - Detailed business justification (workload characteristics)
+6. Submit and monitor status
+
+**Processing Time:** Typically 3-5 business days (requires stronger justification)
+
+## Diagnostic Commands
+
+```bash
+# Check deployment status
+az cognitiveservices account deployment show \
+  --name <resource-name> \
+  --resource-group <rg> \
+  --deployment-name <deployment-name>
+
+# Verify available quota
+subId=$(az account show --query id -o tsv)
+az rest --method get \
+  --url "https://management.azure.com/subscriptions/$subId/providers/Microsoft.CognitiveServices/locations/eastus/usages?api-version=2023-05-01" \
+  --query "value[?contains(name.value,'OpenAI')].{Model:name.value, Used:currentValue, Limit:limit, Available:(limit-currentValue)}" \
+  --output table
+
+# List all deployments
+az cognitiveservices account deployment list \
+  --name <resource-name> \
+  --resource-group <rg> \
+  --query '[].{Name:name, Model:properties.model.name, Capacity:sku.capacity, SKU:sku.name}' \
+  --output table
+```
+
+## External Resources
+
+- [Quota Management Documentation](https://learn.microsoft.com/azure/ai-services/openai/how-to/quota)
+- [Rate Limits Documentation](https://learn.microsoft.com/azure/ai-services/openai/quotas-limits)
+- [Troubleshooting Guide](https://learn.microsoft.com/azure/ai-services/openai/troubleshooting)

package/.agents/skills/microsoft-foundry/quota/references/workflows.md

@@ -0,0 +1,174 @@
+# Detailed Workflows: Quota Management
+
+## Workflow 1: View Current Quota Usage - Detailed Steps
+
+### Step 1: Show Regional Quota Summary (REQUIRED APPROACH)
+
+> **CRITICAL AGENT INSTRUCTION:**
+> - When showing quota: Query REGIONAL quota summary, NOT individual resources
+> - DO NOT run `az cognitiveservices account list` for quota queries
+> - DO NOT filter resources by username or name patterns
+> - ONLY check specific resource deployments if user provides resource name
+> - Quotas are managed at SUBSCRIPTION + REGION level, NOT per-resource
+
+**Show Regional Quota Summary:**
+
+```bash
+# Get subscription ID
+subId=$(az account show --query id -o tsv)
+
+# Check quota for key regions
+regions=("eastus" "eastus2" "westus" "westus2")
+for region in "${regions[@]}"; do
+  echo "=== Region: $region ==="
+  az rest --method get \
+    --url "https://management.azure.com/subscriptions/$subId/providers/Microsoft.CognitiveServices/locations/$region/usages?api-version=2023-05-01" \
+    --query "value[?contains(name.value,'OpenAI.Standard')].{Model:name.value, Used:currentValue, Limit:limit, Available:(limit-currentValue)}" \
+    --output table
+  echo ""
+done
+```
+
+### Step 2: If User Asks for Specific Resource (ONLY IF EXPLICITLY REQUESTED)
+
+```bash
+# User must provide resource name
+az cognitiveservices account deployment list \
+  --name <user-provided-resource-name> \
+  --resource-group <user-provided-rg> \
+  --query '[].{Name:name, Model:properties.model.name, Capacity:sku.capacity, SKU:sku.name}' \
+  --output table
+```
+
+**Alternative - Use MCP Tools (Optional Wrappers):**
+```
+foundry_models_deployments_list(
+  resource-group="<rg>",
+  azure-ai-services="<resource-name>"
+)
+```
+*Note: MCP tools are convenience wrappers around the same control plane APIs shown above.*
+
+**Interpreting Results:**
+- `Used` (currentValue): Currently allocated quota
+- `Limit`: Maximum quota available in region
+- `Available`: Calculated as `limit - currentValue`
+
+## Workflow 2: Find Best Region for Model Deployment - Detailed Steps
+
+### Step 1: Check Single Region
+
+```bash
+# Get subscription ID
+subId=$(az account show --query id -o tsv)
+
+# Check quota for GPT-4o Standard in a specific region
+region="eastus"  # Change to your target region
+az rest --method get \
+  --url "https://management.azure.com/subscriptions/$subId/providers/Microsoft.CognitiveServices/locations/$region/usages?api-version=2023-05-01" \
+  --query "value[?name.value=='OpenAI.Standard.gpt-4o'].{Model:name.value, Used:currentValue, Limit:limit, Available:(limit-currentValue)}" \
+  -o table
+```
+
+### Step 2: Check Multiple Regions (Common Regions)
+
+Check these regions in sequence by changing the `region` variable:
+- `eastus`, `eastus2` - US East Coast
+- `westus`, `westus2`, `westus3` - US West Coast
+- `swedencentral` - Europe (Sweden)
+- `canadacentral` - Canada
+- `uksouth` - UK
+- `japaneast` - Asia Pacific
+
+**Alternative - Use MCP Tool:**
+```
+model_quota_list(region="eastus")
+```
+Repeat for each target region.
+
+**Key Points:**
+- Query returns `currentValue` (used), `limit` (max), and calculated `Available`
+- Standard SKU format: `OpenAI.Standard.<model-name>`
+- For PTU: `OpenAI.ProvisionedManaged.<model-name>`
+- Focus on 2-3 regions relevant to your location rather than checking all regions
+
+## Workflow 3: Check Quota Before Deployment - Detailed Steps
+
+**Steps:**
+1. Check current usage (workflow #1)
+2. Calculate available: `limit - currentValue`
+3. Compare: `available >= required_capacity`
+4. If insufficient: Use workflow #2 to find region with capacity, or request increase
+
+## Workflow 4: Monitor Quota Across Deployments - Detailed Steps
+
+**Recommended Approach - Regional Quota Overview:**
+
+Show quota by region (better than listing all resources):
+
+```bash
+subId=$(az account show --query id -o tsv)
+regions=("eastus" "eastus2" "westus" "westus2" "swedencentral")
+
+for region in "${regions[@]}"; do
+  echo "=== Region: $region ==="
+  az rest --method get \
+    --url "https://management.azure.com/subscriptions/$subId/providers/Microsoft.CognitiveServices/locations/$region/usages?api-version=2023-05-01" \
+    --query "value[?contains(name.value,'OpenAI')].{Model:name.value, Used:currentValue, Limit:limit, Available:(limit-currentValue)}" \
+    --output table
+  echo ""
+done
+```
+
+**Alternative - Check Specific Resource:**
+
+If user wants to monitor a specific resource, ask for resource name first:
+
+```bash
+# List deployments for specific resource
+az cognitiveservices account deployment list \
+  --name <resource-name> \
+  --resource-group <rg> \
+  --query '[].{Name:name, Model:properties.model.name, Capacity:sku.capacity}' \
+  --output table
+```
+
+> **Note:** Don't automatically iterate through all resources in the subscription. Show regional quota summary or ask for specific resource name.
+
+## Quick Command Reference
+
+```bash
+# View quota for specific model using REST API
+subId=$(az account show --query id -o tsv)
+region="eastus"  # Change to your region
+az rest --method get \
+  --url "https://management.azure.com/subscriptions/$subId/providers/Microsoft.CognitiveServices/locations/$region/usages?api-version=2023-05-01" \
+  --query "value[?contains(name.value,'gpt-4')].{Name:name.value, Used:currentValue, Limit:limit, Available:(limit-currentValue)}" \
+  --output table
+
+# List all deployments with capacity
+az cognitiveservices account deployment list \
+  --name <resource-name> \
+  --resource-group <rg> \
+  --query '[].{Name:name, Model:properties.model.name, Capacity:sku.capacity}' \
+  --output table
+
+# Delete deployment to free quota
+az cognitiveservices account deployment delete \
+  --name <resource-name> \
+  --resource-group <rg> \
+  --deployment-name <deployment-name>
+```
+
+## MCP Tools Reference (Optional Wrappers)
+
+**Note:** All quota operations are control plane (management) operations. MCP tools are optional convenience wrappers around Azure CLI commands.
+
+| Tool | Purpose | Equivalent Azure CLI |
+|------|---------|---------------------|
+| `foundry_models_deployments_list` | List all deployments with capacity | `az cognitiveservices account deployment list` |
+| `model_quota_list` | List quota and usage across regions | `az rest` (Management API) |
+| `model_catalog_list` | List available models from catalog | `az rest` (Management API) |
+| `foundry_resource_get` | Get resource details and endpoint | `az cognitiveservices account show` |
+
+**Recommended:** Use Azure CLI commands directly for control plane operations.

package/.agents/skills/microsoft-foundry/rbac/rbac.md

@@ -0,0 +1,156 @@
+# Microsoft Foundry RBAC Management
+
+Reference for managing RBAC for Microsoft Foundry resources: user permissions, managed identity configuration, and service principal setup for CI/CD.
+
+## Quick Reference
+
+| Property | Value |
+|----------|-------|
+| **CLI Extension** | `az role assignment`, `az ad sp` |
+| **Resource Type** | `Microsoft.CognitiveServices/accounts` |
+| **Best For** | Permission management, access auditing, CI/CD setup |
+
+## When to Use
+
+- Grant user access to Foundry resources or projects
+- Set up developer permissions (Project Manager, Owner roles)
+- Audit role assignments or validate permissions
+- Configure managed identity roles for connected resources
+- Create service principals for CI/CD pipeline automation
+- Troubleshoot permission errors
+
+## Azure AI Foundry Built-in Roles
+
+| Role | Create Projects | Data Actions | Role Assignments |
+|------|-----------------|--------------|------------------|
+| Azure AI User | No | Yes | No |
+| Azure AI Project Manager | Yes | Yes | Yes (AI User only) |
+| Azure AI Account Owner | Yes | No | Yes (AI User only) |
+| Azure AI Owner | Yes | Yes | Yes |
+
+> ⚠️ **Warning:** Azure AI User is auto-assigned via Portal but NOT via SDK/CLI. Automation must explicitly assign roles.
+
+## Workflows
+
+All scopes follow the pattern: `/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<foundry-resource-name>`
+
+For project-level scoping, append `/projects/<project-name>`.
+
+### 1. Assign User Permissions
+
+```bash
+az role assignment create --role "Azure AI User" --assignee "<user-email-or-object-id>" --scope "<foundry-scope>"
+```
+
+### 2. Assign Developer Permissions
+
+```bash
+# Project Manager (create projects, assign AI User roles)
+az role assignment create --role "Azure AI Project Manager" --assignee "<user-email-or-object-id>" --scope "<foundry-scope>"
+
+# Full ownership including data actions
+az role assignment create --role "Azure AI Owner" --assignee "<user-email-or-object-id>" --scope "<foundry-scope>"
+```
+
+### 3. Audit Role Assignments
+
+```bash
+# List all assignments
+az role assignment list --scope "<foundry-scope>" --output table
+
+# Detailed with principal names
+az role assignment list --scope "<foundry-scope>" --query "[].{Principal:principalName, PrincipalType:principalType, Role:roleDefinitionName}" --output table
+
+# Azure AI roles only
+az role assignment list --scope "<foundry-scope>" --query "[?contains(roleDefinitionName, 'Azure AI')].{Principal:principalName, Role:roleDefinitionName}" --output table
+```
+
+### 4. Validate Permissions
+
+```bash
+# Current user's roles on resource
+az role assignment list --assignee "$(az ad signed-in-user show --query id -o tsv)" --scope "<foundry-scope>" --query "[].roleDefinitionName" --output tsv
+
+# Check actions available to a role
+az role definition list --name "Azure AI User" --query "[].permissions[].actions" --output json
+```
+
+**Permission Requirements by Action:**
+
+| Action | Required Role(s) |
+|--------|------------------|
+| Deploy models | Azure AI User, Azure AI Project Manager, Azure AI Owner |
+| Create projects | Azure AI Project Manager, Azure AI Account Owner, Azure AI Owner |
+| Assign Azure AI User role | Azure AI Project Manager, Azure AI Account Owner, Azure AI Owner |
+| Full data access | Azure AI User, Azure AI Project Manager, Azure AI Owner |
+
+### 5. Configure Managed Identity Roles
+
+```bash
+# Get managed identity principal ID
+PRINCIPAL_ID=$(az cognitiveservices account show --name <foundry-resource-name> --resource-group <resource-group> --query identity.principalId --output tsv)
+
+# Assign roles to connected resources (repeat pattern for each)
+az role assignment create --role "<role-name>" --assignee "$PRINCIPAL_ID" --scope "<resource-scope>"
+```
+
+**Common Managed Identity Role Assignments:**
+
+| Connected Resource | Role | Purpose |
+|--------------------|------|---------|
+| Azure Storage | Storage Blob Data Reader | Read files/documents |
+| Azure Storage | Storage Blob Data Contributor | Read/write files |
+| Azure Key Vault | Key Vault Secrets User | Read secrets |
+| Azure AI Search | Search Index Data Reader | Query indexes |
+| Azure AI Search | Search Index Data Contributor | Query and modify indexes |
+| Azure Cosmos DB | Cosmos DB Account Reader | Read data |
+
+### 6. Create Service Principal for CI/CD
+
+```bash
+# Create SP with minimal role
+az ad sp create-for-rbac --name "foundry-cicd-sp" --role "Azure AI User" --scopes "<foundry-scope>" --output json
+# Output contains: appId, password, tenant — store securely
+
+# For project management permissions
+az ad sp create-for-rbac --name "foundry-cicd-admin-sp" --role "Azure AI Project Manager" --scopes "<foundry-scope>" --output json
+
+# Add Contributor for resource provisioning
+SP_APP_ID=$(az ad sp list --display-name "foundry-cicd-sp" --query "[0].appId" -o tsv)
+az role assignment create --role "Contributor" --assignee "$SP_APP_ID" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>"
+```
+
+> 💡 **Tip:** Use least privilege — start with `Azure AI User` and add roles as needed.
+
+| CI/CD Scenario | Recommended Role | Additional Roles |
+|----------------|------------------|------------------|
+| Deploy models only | Azure AI User | None |
+| Manage projects | Azure AI Project Manager | None |
+| Full provisioning | Azure AI Owner | Contributor (on RG) |
+| Read-only monitoring | Reader | Azure AI User (for data) |
+
+**CI/CD Pipeline Login:**
+
+```bash
+az login --service-principal --username "<app-id>" --password "<client-secret>" --tenant "<tenant-id>"
+az account set --subscription "<subscription-id>"
+```
+
+## Error Handling
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| "Authorization failed" when deploying | Missing Azure AI User role | Assign Azure AI User role at resource scope |
+| Cannot create projects | Missing Project Manager or Owner role | Assign Azure AI Project Manager role |
+| "Access denied" on connected resources | Managed identity missing roles | Assign appropriate roles to MI on each resource |
+| Portal works but CLI fails | Portal auto-assigns roles, CLI doesn't | Explicitly assign Azure AI User via CLI |
+| Service principal cannot access data | Wrong role or scope | Verify Azure AI User is assigned at correct scope |
+| "Principal does not exist" | User/SP not found in directory | Verify the assignee email or object ID is correct |
+| Role assignment already exists | Duplicate assignment attempt | Use `az role assignment list` to verify existing assignments |
+
+## Additional Resources
+
+- [Azure AI Foundry RBAC Documentation](https://learn.microsoft.com/azure/ai-foundry/concepts/rbac-ai-foundry)
+- [Azure Built-in Roles](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles)
+- [Managed Identities Overview](https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview)
+- [Service Principal Authentication](https://learn.microsoft.com/azure/developer/github/connect-from-azure)