feat: Integrate RAG-Azure-Builder agents, skills, and instructions with full English translation

.codespellrc

@@ -20,7 +20,7 @@
 
 # categor - TypeScript template literal in website/src/scripts/pages/skills.ts:70 (categor${...length > 1 ? "ies" : "y"})
 
-# aline - proper name (Aline Ávila, contributor)
+# aline - proper name (Aline Avila, contributor)
 
 # ative - part of "Declarative Agents" in TypeSpec M365 Copilot documentation (collections/typespec-m365-copilot.collection.md)
 
@@ -54,7 +54,7 @@
 
 # CAF - Microsoft Cloud Adoption Framework acronym
 
-ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX,aNULL,Wee,Sherif,queston,Vertexes,nin,FO,CAF,Parth
+ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX,aNULL,Wee,Sherif,queston,Vertexes,nin,FO,CAF,Parth,accesible,profesional,fases,diagrama,validador,Dimensiones,Comando,Comandos,caracteres,Vectores,Componentes
 
 # Skip certain files and directories
 

.github/plugin/marketplace.json

@@ -346,7 +346,7 @@
     {
       "name": "flowstudio-power-automate",
       "source": "flowstudio-power-automate",
-      "description": "Give your AI agent full visibility into Power Automate cloud flows via the FlowStudio MCP server. Connect, debug, build, monitor health, and govern flows at scale — action-level inputs and outputs, not just status codes.",
+      "description": "Give your AI agent full visibility into Power Automate cloud flows via the FlowStudio MCP server. Connect, debug, build, monitor health, and govern flows at scale ΓÇö action-level inputs and outputs, not just status codes.",
       "version": "2.0.0"
     },
     {
@@ -648,6 +648,12 @@
       "description": "Complete toolkit for building Model Context Protocol (MCP) servers in Python using the official SDK with FastMCP. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.",
       "version": "1.0.0"
     },
+    {
+      "name": "rag-azure-builder",
+      "source": "rag-azure-builder",
+      "description": "Opinionated Azure RAG starter plugin with guided onboarding, indexing strategy, and grounded QA setup patterns.",
+      "version": "1.0.0"
+    },
     {
       "name": "react18-upgrade",
       "source": "react18-upgrade",

agents/rag-azure-setup.agent.md

@@ -0,0 +1,131 @@
+---
+name: 'RAG: Azure Setup'
+description: 'Deploys Azure infrastructure for RAG: OpenAI, AI Search, Application Insights. Uses Bicep templates. Validates connectivity and generates credentials.'
+model: 'claude-haiku-4.5'
+tools: true
+skills: ['rag-deployment-templates', 'rag-agent-instrumentation']
+---
+
+**RAG Reference:** [Retrieval-augmented Generation (RAG) in Azure AI Search - Microsoft Learn](https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview?tabs=videos)
+
+
+
+
+
+## Purpose
+
+Deploy complete Azure infrastructure for RAG **in one go**:
+
+✅ Azure OpenAI Service (deployments of gpt-4o + text-embedding-3-small)
+✅ Azure AI Search (for semantic search + indexing)
+✅ Application Insights (observability and cost tracking)
+✅ Storage Account (for document staging)
+
+**Model availability verification:** Before deployment, verify that gpt-4o is available in your
+target region. Run `python .github/skills/rag-cost-analyst/cost_analyzer.py`
+or call `validate_region_models(["gpt-4o", "text-embedding-3-small"], region)`.
+
+**Validates:** All services running + credentials stored
+
+---
+
+## When to Use
+
+- `Deploy Azure infrastructure for RAG`
+- `Configure OpenAI + Search + AppInsights`
+- `Create production RAG environment`
+
+---
+
+## workflow
+
+### 1. Validate Prerequisites (1 min)
+
+```bash
+az account show  # Logged in?
+az group list    # Resource groups exist?
+```
+
+### 2. Collect configuration (2 min)
+
+From `.env` or prompt:
+```
+AZURE_SUBSCRIPTION_ID=<your-subscription>
+AZURE_RESOURCE_GROUP=rag-builder-rg
+AZURE_REGION=eastus
+OPENAI_TIER=S0
+SEARCH_TIER=standard
+SEARCH_REPLICAS=3
+```
+
+### 3. Deploy Bicep template (5-10 min)
+
+```bash
+cd infra/
+./deploy.sh \
+  --resource-group rag-builder-rg \
+  --region eastus \
+  --openai-tier S0 \
+  --search-tier standard \
+  --search-replicas 3
+```
+
+### 4. Model Deployments (created by Bicep)
+
+The Bicep template auto-creates these deployments:
+- `gpt-4o` (GlobalStandard, capacity 10) — minimum quality model for RAG
+- `text-embedding-3-small` (Standard, capacity 50) — vector embeddings
+
+If you need to add additional deployments manually:
+```bash
+az cognitiveservices account deployment create \
+  --resource-group rag-builder-rg \
+  --name <openai-resource> \
+  --deployment-name gpt-4o \
+  --model-name gpt-4o \
+  --model-version 2024-08-06 \
+  --sku-name GlobalStandard \
+  --sku-capacity 10
+```
+
+### 5. Validate connectivity (1 min)
+
+```python
+from azure.openai import AzureOpenAI
+from azure.search.documents import SearchClient
+
+client = AzureOpenAI(...)
+response = client.chat.completions.create(...)  # ✅ Working?
+
+search = SearchClient(...)
+results = search.search("test")  # ✅ Working?
+
+from azure.monitor.opentelemetry import AzureMonitorTraceExporter
+exporter = AzureMonitorTraceExporter(...)  # ✅ Working?
+```
+
+### 6. Store credentials
+
+Generate `.env` with:
+```
+AZURE_OPENAI_ENDPOINT=https://....openai.azure.com/
+AZURE_OPENAI_API_KEY=...
+OPENAI_CHAT_MODEL=gpt-4o
+OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+AZURE_SEARCH_ENDPOINT=https://....search.windows.net
+AZURE_SEARCH_KEY=...
+AZURE_SEARCH_INDEX=rag-builder-index
+APP_INSIGHTS_CONNECTION_STRING=...
+STORAGE_ACCOUNT_NAME=...
+STORAGE_ACCOUNT_KEY=...
+```
+
+---
+
+## Troubleshooting
+
+**Deployment fails with quota error**
+→ Region may have no quota. Try another region in `.env`
+
+**Cannot create OpenAI deployment**
+→ Verify that the Cognitive Services account exists and is accessible

agents/rag-chat.agent.md

@@ -0,0 +1,183 @@
+---
+name: 'RAG: Conversational Chat'
+description: 'Multi-turn conversational RAG chat. Maintains context, reformulates questions, enables follow-ups. For conversational document exploration.'
+model: 'claude-opus-4.7'
+tools: true
+skills: ['rag-agent-instrumentation']
+---
+
+**RAG Reference:** [Retrieval-augmented Generation (RAG) in Azure AI Search - Microsoft Learn](https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview?tabs=videos)
+
+## Purpose
+
+**Multi-turn RAG chat** with context memory. Perfect for:
+
+- Long conversations about documentation
+- Follow-up questions ("Why?" → "How do I change?")
+- Iterative topic exploration
+- Complex question reformulation
+
+## When to Use
+
+```
+copilot-cli run .github/agents/rag-chat.agent.md
+```
+
+Use this when you need:
+- Conversation vs. one-off queries
+- Multi-step reasoning
+- Persistent context across questions
+
+## workflow
+
+### 1. Inicializa Chat
+
+```
+System: Inicializando RAG Chat...
+✅ Conectado a Azure Search
+✅ Conectado a Azure OpenAI
+✅ Índice: rag-builder-index
+
+Eres un asistente de documentación. Ayudarás a usuarios a explorar
+políticas, procedimientos, y documentación corporativa mediante búsqueda
+semántica. Mantén conversación natural, reformula preguntas complejas,
+y sugiere temas relacionados.
+
+Escribe tu pregunta (o 'exit' para salir):
+```
+
+### 2. Conversación Multi-Turno
+
+**User:**
+```
+¿Cuál es la política de retención de datos?
+```
+
+**Assistant:**
+```
+Basado en la documentación, la política de retención es:
+
+📋 Política de Retención de Datos (Encontrado en: retention-policy.pdf)
+
+- **Datos personales**: 3 años después del último acceso
+- **Logs de auditoría**: 7 años
+- **Backups**: 30 días de retención (con 2 copias)
+- **GDPR compliance**: Eliminación segura con certificado
+
+¿Tienes preguntas adicionales? Puedo ayudarte con:
+- Excepciones a la política
+- Proceso de eliminación de datos
+- Cumplimiento regulatorio
+```
+
+**User:**
+```
+¿Cómo solicitar una excepción?
+```
+
+**Assistant:**
+```
+Para solicitar una excepción (encontrado en: data-exceptions.md):
+
+📋 Proceso de Solicitud
+
+1. Completa formulario DPA-001 (disponible en SharePoint)
+2. Justifica el motivo (legal, contractual, operacional)
+3. Envía a data-governance@empresa.com
+4. Tiempo de respuesta: 10 días hábiles
+
+El sistema recordará el contexto de tu pregunta anterior
+y mantendrá la conversación fluida.
+```
+
+### 3. Características
+
+- **Memoria de Contexto**: Recuerda preguntas anteriores
+- **Reformulación**: Interpreta preguntas ambiguas
+- **search Semántica**: Extrae documentación relevant
+- **Sugerencias Relacionadas**: Propone temas de seguimiento
+- **Métricas**: Registra latencia, tokens, coste en AppInsights
+
+### 4. Salir
+
+```
+User: exit
+Chat guardado en: outputs/chat-history-2026-05-13.json
+Tokens totales: 1,240
+Coste total: $0.31
+Session guardada en AppInsights
+```
+
+---
+
+## Arquitectura
+
+```
+User Input
+    ↓
+[Context Manager] → Mantiene histórico de conversación
+    ↓
+[Query Router] → ¿Reformular? ¿Buscar en índice? ¿Seguimiento?
+    ↓
+[Search Agent] → Búsqueda semántica en Azure Search
+    ↓
+[Context Builder] → Recupera documentos relevant + histórico
+    ↓
+[OpenAI Completion] → Genera respuesta conversacional
+    ↓
+[Metrics Logger] → AppInsights + local JSON
+    ↓
+User Response + Suggestions
+```
+
+---
+
+## configuration (`.env`)
+
+```
+RAG_CHAT_MAX_HISTORY=10         # Mantener últimas 10 interacciones
+RAG_CHAT_TIMEOUT=60              # Timeout por turno (segundos)
+RAG_CHAT_TOP_K=8                 # Documentos recuperados por búsqueda
+RAG_CHAT_TEMPERATURE=0.5         # Creatividad (0.3=factual, 0.7=creativo)
+RAG_CHAT_MAX_TOKENS=2000         # Max tokens por respuesta
+```
+
+---
+
+## Output
+
+Chat session guardada automáticamente:
+
+```json
+{
+  "session_id": "chat-20260513-143022",
+  "started_at": "2026-05-13T14:30:22Z",
+  "messages": [
+    {
+      "turn": 1,
+      "user_query": "¿Cuál es la política de retención?",
+      "search_results": 5,
+      "assistant_response": "...",
+      "tokens_used": 240,
+      "latency_ms": 1850
+    }
+  ],
+  "total_tokens": 1240,
+  "total_cost_usd": 0.31,
+  "duration_seconds": 180
+}
+```
+
+---
+
+## vs CLI Script
+
+| Aspecto | CLI | Chat |
+|---------|-----|------|
+| Latencia | 2s | 5s |
+| Coste | $0.02 | $0.05 |
+| Queries | Puntuales | Conversación |
+| Contexto | Stateless | Multi-turno |
+| Uso | searches rápidas | Exploración profunda |
+
+**Elige Chat cuando necesites seguimiento y contexto.**