@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/domain/azure-cloud/references/azure-cost-optimization.md

@@ -0,0 +1,419 @@
+# Azure Cost Optimization Skill
+
+Analyze Azure subscriptions to identify cost savings through orphaned resource cleanup, rightsizing, and optimization recommendations based on actual usage data.
+
+## When to Use This Skill
+
+Use this skill when the user asks to:
+
+- Optimize Azure costs or reduce spending
+- Analyze Azure subscription for cost savings
+- Generate cost optimization report
+- Find orphaned or unused resources
+- Rightsize Azure VMs, containers, or services
+- Identify where they're overspending in Azure
+- **Optimize Redis costs specifically** - See [Azure Redis Cost Optimization](./references/azure-redis.md) for Redis-specific analysis
+
+## Instructions
+
+Follow these steps in conversation with the user:
+
+### Step 0: Validate Prerequisites
+
+Before starting, verify these tools and permissions are available:
+
+**Required Tools:**
+
+- Azure CLI installed and authenticated (`az login`)
+- Azure CLI extensions: `costmanagement`, `resource-graph`
+- Azure Quick Review (azqr) installed - See [Azure Quick Review](./references/azure-quick-review.md) for details
+
+**Required Permissions:**
+
+- Cost Management Reader role
+- Monitoring Reader role
+- Reader role on subscription/resource group
+
+**Verification commands:**
+
+```powershell
+az --version
+az account show
+az extension show --name costmanagement
+azqr version
+```
+
+### Step 1: Load Best Practices
+
+Get Azure cost optimization best practices to inform recommendations:
+
+```javascript
+// Use Azure MCP best practices tool
+mcp_azure_mcp_get_azure_bestpractices({
+  intent: "Get cost optimization best practices",
+  command: "get_bestpractices",
+  parameters: { resource: "cost-optimization", action: "all" },
+});
+```
+
+### Step 1.5: Redis-Specific Analysis (Conditional)
+
+**If the user specifically requests Redis cost optimization**, use the specialized Redis skill:
+
+**Reference**: [Azure Redis Cost Optimization](./references/azure-redis.md)
+
+**When to use Redis-specific analysis:**
+
+- User mentions "Redis", "Azure Cache for Redis", or "Azure Managed Redis"
+- Focus is on Redis resource optimization, not general subscription analysis
+- User wants Redis-specific recommendations (SKU downgrade, failed caches, etc.)
+
+**Key capabilities:**
+
+- Interactive subscription filtering (prefix, ID, or "all subscriptions")
+- Redis-specific optimization rules (failed caches, oversized tiers, missing tags)
+- Pre-built report templates for Redis cost analysis
+- Uses `redis_list` command
+
+**Report templates available:**
+
+- [Subscription-level Redis summary](./templates/redis-subscription-level-report.md)
+- [Detailed Redis cache analysis](./templates/redis-detailed-cache-analysis.md)
+
+> **Note**: For general subscription-wide cost optimization (including Redis), continue with Step 2. For Redis-only focused analysis, follow the instructions in the Redis-specific reference document.
+
+### Step 1.6: Choose Analysis Scope (for Redis-specific analysis)
+
+**If performing Redis cost optimization**, ask the user to select their analysis scope:
+
+**Prompt the user with these options:**
+
+1. **Specific Subscription ID** - Analyze a single subscription
+2. **Subscription Name** - Use display name instead of ID
+3. **Subscription Prefix** - Analyze all subscriptions starting with a prefix (e.g., "CacheTeam")
+4. **All My Subscriptions** - Scan all accessible subscriptions
+5. **Tenant-wide** - Analyze entire organization
+
+Wait for user response before proceeding to Step 2.
+
+### Step 2: Run Azure Quick Review
+
+Run azqr to find orphaned resources (immediate cost savings):
+
+**Reference**: [Azure Quick Review](./references/azure-quick-review.md) - Detailed instructions for running azqr scans
+
+```javascript
+// Use Azure MCP extension_azqr tool
+extension_azqr({
+  subscription: "<SUBSCRIPTION_ID>",
+  "resource-group": "<RESOURCE_GROUP>", // optional
+});
+```
+
+**What to look for in azqr results:**
+
+- Orphaned resources: unattached disks, unused NICs, idle NAT gateways
+- Over-provisioned resources: excessive retention periods, oversized SKUs
+- Missing cost tags: resources without proper cost allocation
+
+> **Note**: The Azure Quick Review reference document includes instructions for creating filter configurations, saving output to the `output/` folder, and interpreting results for cost optimization.
+
+### Step 3: Discover Resources
+
+For efficient cross-subscription resource discovery, use Azure Resource Graph. See [Azure Resource Graph Queries](references/azure-resource-graph.md) for orphaned resource detection and cost optimization patterns.
+
+List all resources in the subscription using Azure MCP tools or CLI:
+
+```powershell
+# Get subscription info
+az account show
+
+# List all resources
+az resource list --subscription "<SUBSCRIPTION_ID>" --resource-group "<RESOURCE_GROUP>"
+
+# Use MCP tools for specific services (preferred):
+# - Storage accounts, Cosmos DB, Key Vaults: use Azure MCP tools
+# - Redis caches: use mcp_azure_mcp_redis tool (see ./references/azure-redis.md)
+# - Web apps, VMs, SQL: use az CLI commands
+```
+
+### Step 4: Query Actual Costs
+
+Get actual cost data from Azure Cost Management API (last 30 days):
+
+**Create cost query file:**
+
+Create `temp/cost-query.json` with:
+
+```json
+{
+  "type": "ActualCost",
+  "timeframe": "Custom",
+  "timePeriod": {
+    "from": "<START_DATE>",
+    "to": "<END_DATE>"
+  },
+  "dataset": {
+    "granularity": "None",
+    "aggregation": {
+      "totalCost": {
+        "name": "Cost",
+        "function": "Sum"
+      }
+    },
+    "grouping": [
+      {
+        "type": "Dimension",
+        "name": "ResourceId"
+      }
+    ]
+  }
+}
+```
+
+> **Action Required**: Calculate `<START_DATE>` (30 days ago) and `<END_DATE>` (today) in ISO 8601 format (e.g., `2025-11-03T00:00:00Z`).
+
+**Execute cost query:**
+
+```powershell
+# Create temp folder
+New-Item -ItemType Directory -Path "temp" -Force
+
+# Query using REST API (more reliable than az costmanagement query)
+az rest --method post `
+  --url "https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.CostManagement/query?api-version=2023-11-01" `
+  --body '@temp/cost-query.json'
+```
+
+**Important:** Save the query results to `output/cost-query-result<timestamp>.json` for audit trail.
+
+### Step 5: Validate Pricing
+
+Fetch current pricing from official Azure pricing pages using `fetch_webpage`:
+
+```javascript
+// Validate pricing for key services
+fetch_webpage({
+  urls: ["https://azure.microsoft.com/en-us/pricing/details/container-apps/"],
+  query: "pricing tiers and costs",
+});
+```
+
+**Key services to validate:**
+
+- Container Apps: https://azure.microsoft.com/pricing/details/container-apps/
+- Virtual Machines: https://azure.microsoft.com/pricing/details/virtual-machines/
+- App Service: https://azure.microsoft.com/pricing/details/app-service/
+- Log Analytics: https://azure.microsoft.com/pricing/details/monitor/
+
+> **Important**: Check for free tier allowances - many Azure services have generous free limits that may explain $0 costs.
+
+### Step 6: Collect Utilization Metrics
+
+Query Azure Monitor for utilization data (last 14 days) to support rightsizing recommendations:
+
+```powershell
+# Calculate dates for last 14 days
+$startTime = (Get-Date).AddDays(-14).ToString("yyyy-MM-ddTHH:mm:ssZ")
+$endTime = Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ"
+
+# VM CPU utilization
+az monitor metrics list `
+  --resource "<RESOURCE_ID>" `
+  --metric "Percentage CPU" `
+  --interval PT1H `
+  --aggregation Average `
+  --start-time $startTime `
+  --end-time $endTime
+
+# App Service Plan utilization
+az monitor metrics list `
+  --resource "<RESOURCE_ID>" `
+  --metric "CpuTime,Requests" `
+  --interval PT1H `
+  --aggregation Total `
+  --start-time $startTime `
+  --end-time $endTime
+
+# Storage capacity
+az monitor metrics list `
+  --resource "<RESOURCE_ID>" `
+  --metric "UsedCapacity,BlobCount" `
+  --interval PT1H `
+  --aggregation Average `
+  --start-time $startTime `
+  --end-time $endTime
+```
+
+### Step 7: Generate Optimization Report
+
+Create a comprehensive cost optimization report in the `output/` folder:
+
+**Use the `create_file` tool** with path `output/costoptimizereport<YYYYMMDD_HHMMSS>.md`:
+
+**Report Structure:**
+
+```markdown
+# Azure Cost Optimization Report
+
+**Generated**: <timestamp>
+
+## Executive Summary
+
+- Total Monthly Cost: $X (ACTUAL DATA)
+- Top Cost Drivers: [List top 3 resources with Azure Portal links]
+
+## Cost Breakdown
+
+[Table with top 10 resources by cost, including Azure Portal links]
+
+## Free Tier Analysis
+
+[Resources operating within free tiers showing $0 cost]
+
+## Orphaned Resources (Immediate Savings)
+
+[From azqr - resources that can be deleted immediately]
+
+- Resource name with Portal link - $X/month savings
+
+## Optimization Recommendations
+
+### Priority 1: High Impact, Low Risk
+
+[Example: Delete orphaned resources]
+
+- ACTUAL cost: $X/month
+- ESTIMATED savings: $Y/month
+- Commands to execute (with warnings)
+
+### Priority 2: Medium Impact, Medium Risk
+
+[Example: Rightsize VM from D4s_v5 to D2s_v5]
+
+- ACTUAL baseline: D4s_v5, $X/month
+- ACTUAL metrics: CPU 8%, Memory 30%
+- VALIDATED pricing: D4s_v5 $Y/hr, D2s_v5 $Z/hr
+- ESTIMATED savings: $S/month
+- Commands to execute
+
+### Priority 3: Long-term Optimization
+
+[Example: Reserved Instances, Storage tiering]
+
+## Total Estimated Savings
+
+- Monthly: $X
+- Annual: $Y
+
+## Implementation Commands
+
+[Safe commands with approval warnings]
+
+## Validation Appendix
+
+### Data Sources and Files
+
+- **Cost Query Results**: `output/cost-query-result<timestamp>.json`
+  - Raw cost data from Azure Cost Management API
+  - Audit trail proving actual costs at report generation time
+  - Keep for at least 12 months for historical comparison
+  - Contains every resource's exact cost over the analysis period
+- **Pricing Sources**: [Links to Azure pricing pages]
+- **Free Tier Allowances**: [Applicable allowances]
+
+> **Note**: The `temp/cost-query.json` file (if present) is a temporary query template and can be safely deleted. All permanent audit data is in the `output/` folder.
+```
+
+**Portal Link Format:**
+
+```
+https://portal.azure.com/#@<TENANT_ID>/resource/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/<RESOURCE_PROVIDER>/<RESOURCE_TYPE>/<RESOURCE_NAME>/overview
+```
+
+### Step 8: Save Audit Trail
+
+Save all cost query results for validation:
+
+**Use the `create_file` tool** with path `output/cost-query-result<YYYYMMDD_HHMMSS>.json`:
+
+```json
+{
+  "timestamp": "<ISO_8601>",
+  "subscription": "<SUBSCRIPTION_ID>",
+  "resourceGroup": "<RESOURCE_GROUP>",
+  "queries": [
+    {
+      "queryType": "ActualCost",
+      "timeframe": "MonthToDate",
+      "query": {},
+      "response": {}
+    }
+  ]
+}
+```
+
+### Step 9: Clean Up Temporary Files
+
+Remove temporary query files and folder after the report is generated:
+
+```powershell
+# Delete entire temp folder (no longer needed)
+Remove-Item -Path "temp" -Recurse -Force -ErrorAction SilentlyContinue
+```
+
+> **Note**: The `temp/cost-query.json` file is only needed during API execution. The actual query and results are preserved in `output/cost-query-result*.json` for audit purposes.
+
+## Output
+
+The skill generates:
+
+1. **Cost Optimization Report** (`output/costoptimizereport<timestamp>.md`)
+   - Executive summary with total costs and top drivers
+   - Detailed cost breakdown with Azure Portal links
+   - Prioritized recommendations with actual data and estimated savings
+   - Implementation commands with safety warnings
+
+2. **Cost Query Results** (`output/cost-query-result<timestamp>.json`)
+   - Audit trail of all cost queries and responses
+   - Validation evidence for recommendations
+
+## Important Notes
+
+### Data Classification
+
+- ACTUAL DATA = Retrieved from Azure Cost Management API
+- ACTUAL METRICS = Retrieved from Azure Monitor
+- VALIDATED PRICING = Retrieved from official Azure pricing pages
+- ESTIMATED SAVINGS = Calculated based on actual data and validated pricing
+
+### Best Practices
+
+- Always query actual costs first - never estimate or assume
+- Validate pricing from official sources - account for free tiers
+- Use REST API for cost queries (more reliable than `az costmanagement query`)
+- Save audit trail - include all queries and responses
+- Include Azure Portal links for all resources
+- Use UTF-8 encoding when creating report files
+- For costs < $10/month, emphasize operational improvements over financial savings
+- Never execute destructive operations without explicit approval
+
+### Common Pitfalls
+
+- **Assuming costs**: Always query actual data from Cost Management API
+- **Ignoring free tiers**: Many services have generous allowances (e.g., Container Apps: 180K vCPU-sec free/month)
+- **Using wrong date ranges**: 30 days for costs, 14 days for utilization
+- **Broken Portal links**: Verify tenant ID and resource ID format
+- **Cost query failures**: Use `az rest` with JSON body, not `az costmanagement query`
+
+### Safety Requirements
+
+- Get approval before deleting resources
+- Test changes in non-production first
+- Provide dry-run commands for validation
+- Include rollback procedures
+- Monitor impact after implementation
+
+## SDK Quick References
+
+- **Redis Management**: [.NET](references/sdk/azure-resource-manager-redis-dotnet.md)

package/.merlin-core/skills/domain/azure-cloud/references/azure-deploy.md

@@ -0,0 +1,82 @@
+---
+
+# Azure Deploy
+
+> **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE**
+>
+> **PREREQUISITE**: The **azure-validate** skill **MUST** be invoked and completed with status `Validated` BEFORE executing this skill.
+
+> **⛔ STOP — PREREQUISITE CHECK REQUIRED**
+> Before proceeding, verify BOTH prerequisites are met:
+>
+> 1. **azure-prepare** was invoked and completed → `.azure/plan.md` exists
+> 2. **azure-validate** was invoked and passed → plan status = `Validated`
+>
+> If EITHER is missing, **STOP IMMEDIATELY**:
+> - No plan? → Invoke **azure-prepare** skill first
+> - Status not `Validated`? → Invoke **azure-validate** skill first
+>
+> **⛔ DO NOT MANUALLY UPDATE THE PLAN STATUS**
+>
+> You are **FORBIDDEN** from changing the plan status to `Validated` yourself. Only the **azure-validate** skill is authorized to set this status after running actual validation checks. If you update the status without running validation, deployments will fail.
+>
+> **DO NOT ASSUME** the app is ready. **DO NOT SKIP** validation to save time. Skipping steps causes deployment failures. The complete workflow ensures success:
+>
+> `azure-prepare` → `azure-validate` → `azure-deploy`
+
+## Triggers
+
+Activate this skill when user wants to:
+- Execute deployment of an already-prepared application (azure.yaml and infra/ exist)
+- Push updates to an existing Azure deployment
+- Run `azd up`, `azd deploy`, or `az deployment` on a prepared project
+- Ship already-built code to production
+- Deploy an application that already includes API Management (APIM) gateway infrastructure
+
+> **Scope**: This skill executes deployments. It does not create applications, generate infrastructure code, or scaffold projects. For those tasks, use **azure-prepare**.
+
+> **APIM / AI Gateway**: Use this skill to deploy applications whose APIM/AI gateway infrastructure was already created during **azure-prepare**. For creating or changing APIM resources, see [APIM deployment guide](https://learn.microsoft.com/azure/api-management/get-started-create-service-instance). For AI governance policies, invoke **azure-aigateway** skill.
+
+## Rules
+
+1. Run after azure-prepare and azure-validate
+2. `.azure/plan.md` must exist with status `Validated`
+3. **Pre-deploy checklist required** — [Pre-Deploy Checklist](references/pre-deploy-checklist.md)
+4. ⛔ **Destructive actions require `ask_user`** — [global-rules](references/global-rules.md)
+5. **Scope: deployment execution only** — This skill owns execution of `azd up`, `azd deploy`, `terraform apply`, and `az deployment` commands. These commands are run through this skill's error recovery and verification pipeline.
+
+---
+
+## Steps
+
+| #   | Action                                                                                                            | Reference                                                    |
+| --- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| 1   | **Check Plan** — Read `.azure/plan.md`, verify status = `Validated` AND **Validation Proof** section is populated | `.azure/plan.md`                                             |
+| 2   | **Pre-Deploy Checklist** — MUST complete ALL steps                                                                | [Pre-Deploy Checklist](references/pre-deploy-checklist.md)   |
+| 3   | **Load Recipe** — Based on `recipe.type` in `.azure/plan.md`                                                      | [recipes/README.md](references/recipes/README.md)            |
+| 4   | **Execute Deploy** — Follow recipe steps                                                                          | Recipe README                                                |
+| 5   | **Post-Deploy** — Configure SQL managed identity and apply EF migrations if applicable                            | [Post-Deployment](references/recipes/azd/post-deployment.md) |
+| 6   | **Handle Errors** — See recipe's `errors.md`                                                                      | —                                                            |
+| 7   | **Verify Success** — Confirm deployment completed and endpoints are accessible                                    | [Verification](references/recipes/azd/verify.md)             |
+
+> **⛔ VALIDATION PROOF CHECK**
+>
+> When checking the plan, verify the **Validation Proof** section (Section 7) contains actual validation results with commands run and timestamps. If this section is empty, validation was bypassed — invoke **azure-validate** skill first.
+
+## SDK Quick References
+
+- **Azure Developer CLI**: [azd](references/sdk/azd-deployment.md)
+- **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md)
+
+## MCP Tools
+
+| Tool                              | Purpose                              |
+| --------------------------------- | ------------------------------------ |
+| `mcp_azure_mcp_subscription_list` | List available subscriptions         |
+| `mcp_azure_mcp_group_list`        | List resource groups in subscription |
+| `mcp_azure_mcp_azd`               | Execute AZD commands                 |
+
+## References
+
+- [Troubleshooting](references/troubleshooting.md) - Common issues and solutions
+- [Post-Deployment Steps](references/recipes/azd/post-deployment.md) - SQL + EF Core setup

package/.merlin-core/skills/domain/azure-cloud/references/azure-diagnostics.md

@@ -0,0 +1,130 @@
+# Azure Diagnostics
+
+> **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE**
+>
+> This document is the **official source** for debugging and troubleshooting Azure production issues. Follow these instructions to diagnose and resolve common Azure service problems systematically.
+
+## Triggers
+
+Activate this skill when user wants to:
+
+- Debug or troubleshoot production issues
+- Diagnose errors in Azure services
+- Analyze application logs or metrics
+- Fix image pull, cold start, or health probe issues
+- Investigate why Azure resources are failing
+- Find root cause of application errors
+- Troubleshoot Azure Function Apps (invocation failures, timeouts, binding errors)
+- Find the App Insights or Log Analytics workspace linked to a Function App
+
+## Rules
+
+1. Start with systematic diagnosis flow
+2. Use AppLens (MCP) for AI-powered diagnostics when available
+3. Check resource health before deep-diving into logs
+4. Select appropriate troubleshooting guide based on service type
+5. Document findings and attempted remediation steps
+
+---
+
+## Quick Diagnosis Flow
+
+1. **Identify symptoms** - What's failing?
+2. **Check resource health** - Is Azure healthy?
+3. **Review logs** - What do logs show?
+4. **Analyze metrics** - Performance patterns?
+5. **Investigate recent changes** - What changed?
+
+---
+
+## Troubleshooting Guides by Service
+
+| Service            | Common Issues                                                                                 | Reference                                              |
+| ------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| **Container Apps** | Image pull failures, cold starts, health probes, port mismatches                              | [container-apps/](references/container-apps/README.md) |
+| **Function Apps**  | App details, invocation failures, timeouts, binding errors, cold starts, missing app settings | [functions/](references/functions/README.md)           |
+
+---
+
+## Quick Reference
+
+### Common Diagnostic Commands
+
+```bash
+# Check resource health
+az resource show --ids RESOURCE_ID
+
+# View activity log
+az monitor activity-log list -g RG --max-events 20
+
+# Container Apps logs
+az containerapp logs show --name APP -g RG --follow
+
+# Function App logs (query App Insights traces)
+az monitor app-insights query --apps APP-INSIGHTS -g RG \
+  --analytics-query "traces | where timestamp > ago(1h) | order by timestamp desc | take 50"
+```
+
+### AppLens (MCP Tools)
+
+For AI-powered diagnostics, use:
+
+```
+mcp_azure_mcp_applens
+  intent: "diagnose issues with <resource-name>"
+  command: "diagnose"
+  parameters:
+    resourceId: "<resource-id>"
+
+Provides:
+- Automated issue detection
+- Root cause analysis
+- Remediation recommendations
+```
+
+### Azure Monitor (MCP Tools)
+
+For querying logs and metrics:
+
+```
+mcp_azure_mcp_monitor
+  intent: "query logs for <resource-name>"
+  command: "logs_query"
+  parameters:
+    workspaceId: "<workspace-id>"
+    query: "<KQL-query>"
+```
+
+See [kql-queries.md](references/kql-queries.md) for common diagnostic queries.
+
+---
+
+## Check Azure Resource Health
+
+### Using MCP
+
+```
+mcp_azure_mcp_resourcehealth
+  intent: "check health status of <resource-name>"
+  command: "get"
+  parameters:
+    resourceId: "<resource-id>"
+```
+
+### Using CLI
+
+```bash
+# Check specific resource health
+az resource show --ids RESOURCE_ID
+
+# Check recent activity
+az monitor activity-log list -g RG --max-events 20
+```
+
+---
+
+## References
+
+- [KQL Query Library](references/kql-queries.md)
+- [Azure Resource Graph Queries](references/azure-resource-graph.md)
+- [Function Apps Troubleshooting](references/functions/README.md)