@caoscompanybr/merlin 3.5.0

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

@@ -0,0 +1,178 @@
+# Azure Resource Visualizer - Architecture Diagram Generator
+
+A user may ask for help understanding how individual resources fit together, or to create a diagram showing their relationships. Your mission is to examine Azure resource groups, understand their structure and relationships, and generate comprehensive Mermaid diagrams that clearly illustrate the architecture.
+
+## Core Responsibilities
+
+1. **Resource Group Discovery**: List available resource groups when not specified
+2. **Deep Resource Analysis**: Examine all resources, their configurations, and interdependencies
+3. **Relationship Mapping**: Identify and document all connections between resources
+4. **Diagram Generation**: Create detailed, accurate Mermaid diagrams
+5. **Documentation Creation**: Produce clear markdown files with embedded diagrams
+
+## Workflow Process
+
+### Step 1: Resource Group Selection
+
+If the user hasn't specified a resource group:
+
+1. Use your tools to query available resource groups. If you do not have a tool for this, use `az`.
+2. Present a numbered list of resource groups with their locations
+3. Ask the user to select one by number or name
+4. Wait for user response before proceeding
+
+If a resource group is specified, validate it exists and proceed.
+
+### Step 2: Resource Discovery & Analysis
+
+For bulk resource discovery across subscriptions, use Azure Resource Graph queries. See [Azure Resource Graph Queries](references/azure-resource-graph.md) for cross-subscription inventory and relationship discovery patterns.
+
+Once you have the resource group:
+
+1. **Query all resources** in the resource group using Azure MCP tools or `az`.
+2. **Analyze each resource** type and capture:
+   - Resource name and type
+   - SKU/tier information
+   - Location/region
+   - Key configuration properties
+   - Network settings (VNets, subnets, private endpoints)
+   - Identity and access (Managed Identity, RBAC)
+   - Dependencies and connections
+
+3. **Map relationships** by identifying:
+   - **Network connections**: VNet peering, subnet assignments, NSG rules, private endpoints
+   - **Data flow**: Apps → Databases, Functions → Storage, API Management → Backends
+   - **Identity**: Managed identities connecting to resources
+   - **Configuration**: App Settings pointing to Key Vaults, connection strings
+   - **Dependencies**: Parent-child relationships, required resources
+
+### Step 3: Diagram Construction
+
+Create a **detailed Mermaid diagram** using the `graph TB` (top-to-bottom) or `graph LR` (left-to-right) format.
+
+See [example-diagram.md](./assets/example-diagram.md) for a complete sample architecture diagram.
+
+**Key Diagram Requirements:**
+
+- **Group by layer or purpose**: Network, Compute, Data, Security, Monitoring
+- **Include details**: SKUs, tiers, important settings in node labels (use `<br/>` for line breaks)
+- **Label all connections**: Describe what flows between resources (data, identity, network)
+- **Use meaningful node IDs**: Abbreviations that make sense (APP, FUNC, SQL, KV)
+- **Visual hierarchy**: Subgraphs for logical grouping
+- **Connection types**:
+  - `-->` for data flow or dependencies
+  - `-.->` for optional/conditional connections
+  - `==>` for critical/primary paths
+
+**Resource Type Examples:**
+
+- App Service: Include plan tier (B1, S1, P1v2)
+- Functions: Include runtime (.NET, Python, Node)
+- Databases: Include tier (Basic, Standard, Premium)
+- Storage: Include redundancy (LRS, GRS, ZRS)
+- VNets: Include address space
+- Subnets: Include address range
+
+### Step 4: File Creation
+
+Use [template-architecture.md](./assets/template-architecture.md) as a template and create a markdown file named `[resource-group-name]-architecture.md` with:
+
+1. **Header**: Resource group name, subscription, region
+2. **Summary**: Brief overview of the architecture (2-3 paragraphs)
+3. **Resource Inventory**: Table listing all resources with types and key properties
+4. **Architecture Diagram**: The complete Mermaid diagram
+5. **Relationship Details**: Explanation of key connections and data flows
+6. **Notes**: Any important observations, potential issues, or recommendations
+
+## Operating Guidelines
+
+### Quality Standards
+
+- **Accuracy**: Verify all resource details before including in diagram
+- **Completeness**: Don't omit resources; include everything in the resource group
+- **Clarity**: Use clear, descriptive labels and logical grouping
+- **Detail Level**: Include configuration details that matter for architecture understanding
+- **Relationships**: Show ALL significant connections, not just obvious ones
+
+### Tool Usage Patterns
+
+1. **Azure MCP Search**:
+   - Use `intent="list resource groups"` to discover resource groups
+   - Use `intent="list resources in group"` with group name to get all resources
+   - Use `intent="get resource details"` for individual resource analysis
+   - Use `command` parameter when you need specific Azure operations
+
+2. **File Creation**:
+   - Always create in workspace root or a `docs/` folder if it exists
+   - Use clear, descriptive filenames: `[rg-name]-architecture.md`
+   - Ensure Mermaid syntax is valid (test syntax mentally before output)
+
+3. **Terminal (when needed)**:
+   - Use Azure CLI for complex queries not available via MCP
+   - Example: `az resource list --resource-group <name> --output json`
+   - Example: `az network vnet show --resource-group <name> --name <vnet-name>`
+
+### Constraints & Boundaries
+
+**Always Do:**
+
+- List resource groups if not specified
+- Wait for user selection before proceeding
+- Analyze ALL resources in the group
+- Create detailed, accurate diagrams
+- Include configuration details in node labels
+- Group resources logically with subgraphs
+- Label all connections descriptively
+- Create a complete markdown file with diagram
+
+**Never Do:**
+
+- Skip resources because they seem unimportant
+- Make assumptions about resource relationships without verification
+- Create incomplete or placeholder diagrams
+- Omit configuration details that affect architecture
+- Proceed without confirming resource group selection
+- Generate invalid Mermaid syntax
+- Modify or delete Azure resources (read-only analysis)
+
+### Edge Cases & Error Handling
+
+- **No resources found**: Inform user and verify resource group name
+- **Permission issues**: Explain what's missing and suggest checking RBAC
+- **Complex architectures (50+ resources)**: Consider creating multiple diagrams by layer
+- **Cross-resource-group dependencies**: Note external dependencies in diagram notes
+- **Resources without clear relationships**: Group in "Other Resources" section
+
+## Output Format Specifications
+
+### Mermaid Diagram Syntax
+
+- Use `graph TB` (top-to-bottom) for vertical layouts
+- Use `graph LR` (left-to-right) for horizontal layouts (better for wide architectures)
+- Subgraph syntax: `subgraph "Descriptive Name"`
+- Node syntax: `ID["Display Name<br/>Details"]`
+- Connection syntax: `SOURCE -->|"Label"| TARGET`
+
+### Markdown Structure
+
+- Use H1 for main title
+- Use H2 for major sections
+- Use H3 for subsections
+- Use tables for resource inventories
+- Use bullet lists for notes and recommendations
+- Use code blocks with `mermaid` language tag for diagrams
+
+## Success Criteria
+
+A successful analysis includes:
+
+- Valid resource group identified
+- All resources discovered and analyzed
+- All significant relationships mapped
+- Detailed Mermaid diagram with proper grouping
+- Complete markdown file created
+- Clear, actionable documentation
+- Valid Mermaid syntax that renders correctly
+- Professional, architect-level output
+
+Your goal is to provide clarity and insight into Azure architectures, making complex resource relationships easy to understand through excellent visualization.

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

@@ -0,0 +1,91 @@
+# Azure Storage Services
+
+## Services
+
+| Service       | Use When                                   | MCP Tools        | CLI                |
+| ------------- | ------------------------------------------ | ---------------- | ------------------ |
+| Blob Storage  | Objects, files, backups, static content    | `azure__storage` | `az storage blob`  |
+| File Shares   | SMB file shares, lift-and-shift            | -                | `az storage file`  |
+| Queue Storage | Async messaging, task queues               | -                | `az storage queue` |
+| Table Storage | NoSQL key-value (consider Cosmos DB)       | -                | `az storage table` |
+| Data Lake     | Big data analytics, hierarchical namespace | -                | `az storage fs`    |
+
+## MCP Server (Preferred)
+
+When Azure MCP is enabled:
+
+- `azure__storage` with command `storage_account_list` - List storage accounts
+- `azure__storage` with command `storage_container_list` - List containers in account
+- `azure__storage` with command `storage_blob_list` - List blobs in container
+- `azure__storage` with command `storage_blob_get` - Download blob content
+- `azure__storage` with command `storage_blob_put` - Upload blob content
+
+**If Azure MCP is not enabled:** Run `/azure:setup` or enable via `/mcp`.
+
+## CLI Fallback
+
+```bash
+# List storage accounts
+az storage account list --output table
+
+# List containers
+az storage container list --account-name ACCOUNT --output table
+
+# List blobs
+az storage blob list --account-name ACCOUNT --container-name CONTAINER --output table
+
+# Download blob
+az storage blob download --account-name ACCOUNT --container-name CONTAINER --name BLOB --file LOCAL_PATH
+
+# Upload blob
+az storage blob upload --account-name ACCOUNT --container-name CONTAINER --name BLOB --file LOCAL_PATH
+```
+
+## Storage Account Tiers
+
+| Tier     | Use Case                | Performance     |
+| -------- | ----------------------- | --------------- |
+| Standard | General purpose, backup | Milliseconds    |
+| Premium  | Databases, high IOPS    | Sub-millisecond |
+
+## Blob Access Tiers
+
+| Tier    | Access Frequency      | Cost                                 |
+| ------- | --------------------- | ------------------------------------ |
+| Hot     | Frequent              | Higher storage, lower access         |
+| Cool    | Infrequent (30+ days) | Lower storage, higher access         |
+| Cold    | Rare (90+ days)       | Lower still                          |
+| Archive | Rarely (180+ days)    | Lowest storage, rehydration required |
+
+## Redundancy Options
+
+| Type | Durability | Use Case                   |
+| ---- | ---------- | -------------------------- |
+| LRS  | 11 nines   | Dev/test, recreatable data |
+| ZRS  | 12 nines   | Regional high availability |
+| GRS  | 16 nines   | Disaster recovery          |
+| GZRS | 16 nines   | Best durability            |
+
+## Service Details
+
+For deep documentation on specific services:
+
+- Blob storage patterns and lifecycle -> [Blob Storage documentation](https://learn.microsoft.com/azure/storage/blobs/storage-blobs-overview)
+- File shares and Azure File Sync -> [Azure Files documentation](https://learn.microsoft.com/azure/storage/files/storage-files-introduction)
+- Queue patterns and poison handling -> [Queue Storage documentation](https://learn.microsoft.com/azure/storage/queues/storage-queues-introduction)
+
+## SDK Quick References
+
+For building applications with Azure Storage SDKs, see the condensed guides:
+
+- **Blob Storage**: [Python](references/sdk/azure-storage-blob-py.md) | [TypeScript](references/sdk/azure-storage-blob-ts.md) | [Java](references/sdk/azure-storage-blob-java.md) | [Rust](references/sdk/azure-storage-blob-rust.md)
+- **Queue Storage**: [Python](references/sdk/azure-storage-queue-py.md) | [TypeScript](references/sdk/azure-storage-queue-ts.md)
+- **File Shares**: [Python](references/sdk/azure-storage-file-share-py.md) | [TypeScript](references/sdk/azure-storage-file-share-ts.md)
+- **Data Lake**: [Python](references/sdk/azure-storage-file-datalake-py.md)
+- **Tables**: [Python](references/sdk/azure-data-tables-py.md) | [Java](references/sdk/azure-data-tables-java.md)
+
+For full package listing across all languages, see [SDK Usage Guide](references/sdk-usage.md).
+
+## Azure SDKs
+
+For building applications that interact with Azure Storage programmatically, Azure provides SDK packages in multiple languages (.NET, Java, JavaScript, Python, Go, Rust). See [SDK Usage Guide](references/sdk-usage.md) for package names, installation commands, and quick start examples.

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

@@ -0,0 +1,58 @@
+# Azure Validate
+
+> **AUTHORITATIVE GUIDANCE** — Follow these instructions exactly. This supersedes prior training.
+
+> **⛔ STOP — PREREQUISITE CHECK REQUIRED**
+>
+> Before proceeding, verify this prerequisite is met:
+>
+> **azure-prepare** was invoked and completed → `.azure/plan.md` exists with status `Approved` or later
+>
+> If the plan is missing, **STOP IMMEDIATELY** and invoke **azure-prepare** first.
+>
+> The complete workflow ensures success:
+>
+> `azure-prepare` → `azure-validate` → `azure-deploy`
+
+## Triggers
+
+- Check if app is ready to deploy
+- Validate azure.yaml or Bicep
+- Run preflight checks
+- Troubleshoot deployment errors
+
+## Rules
+
+1. Run after azure-prepare, before azure-deploy
+2. All checks must pass—do not deploy with failures
+3. ⛔ **Destructive actions require `ask_user`** — [global-rules](references/global-rules.md)
+
+## Steps
+
+| #   | Action                                                                                                   | Reference                                         |
+| --- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| 1   | **Load Plan** — Read `.azure/plan.md` for recipe and configuration. If missing → run azure-prepare first | `.azure/plan.md`                                  |
+| 2   | **Run Validation** — Execute recipe-specific validation commands                                         | [recipes/README.md](references/recipes/README.md) |
+| 3   | **Build Verification** — Build the project and fix any errors before proceeding                          | See recipe                                        |
+| 4   | **Record Proof** — Populate **Section 7: Validation Proof** with commands run and results                | `.azure/plan.md`                                  |
+| 5   | **Resolve Errors** — Fix failures before proceeding                                                      | See recipe's `errors.md`                          |
+| 6   | **Update Status** — Only after ALL checks pass, set status to `Validated`                                | `.azure/plan.md`                                  |
+| 7   | **Deploy** — Invoke **azure-deploy** skill                                                               | —                                                 |
+
+> **⛔ VALIDATION AUTHORITY**
+>
+> This skill is the **ONLY** authorized way to set plan status to `Validated`. You MUST:
+>
+> 1. Run actual validation commands (azd provision --preview, bicep build, terraform validate, etc.)
+> 2. Populate **Section 7: Validation Proof** with the commands you ran and their results
+> 3. Only then set status to `Validated`
+>
+> Do NOT set status to `Validated` without running checks and recording proof.
+
+---
+
+> **⚠️ MANDATORY NEXT STEP — DO NOT SKIP**
+>
+> After ALL validations pass, you **MUST** invoke **azure-deploy** to execute the deployment. Do NOT attempt to run `azd up`, `azd deploy`, or any deployment commands directly. Let azure-deploy handle execution.
+>
+> If any validation failed, fix the issues and re-run azure-validate before proceeding.

package/.merlin-core/skills/domain/azure-cloud/references/entra-app-registration.md

@@ -0,0 +1,192 @@
+---
+
+## Overview
+
+Microsoft Entra ID (formerly Azure Active Directory) is Microsoft's cloud-based identity and access management service. App registrations allow applications to authenticate users and access Azure resources securely.
+
+### Key Concepts
+
+| Concept                     | Description                                                         |
+| --------------------------- | ------------------------------------------------------------------- |
+| **App Registration**        | Configuration that allows an app to use Microsoft identity platform |
+| **Application (Client) ID** | Unique identifier for your application                              |
+| **Tenant ID**               | Unique identifier for your Azure AD tenant/directory                |
+| **Client Secret**           | Password for the application (confidential clients only)            |
+| **Redirect URI**            | URL where authentication responses are sent                         |
+| **API Permissions**         | Access scopes your app requests                                     |
+| **Service Principal**       | Identity created in your tenant when you register an app            |
+
+### Application Types
+
+| Type                      | Use Case                      |
+| ------------------------- | ----------------------------- |
+| **Web Application**       | Server-side apps, APIs        |
+| **Single Page App (SPA)** | JavaScript/React/Angular apps |
+| **Mobile/Native App**     | Desktop, mobile apps          |
+| **Daemon/Service**        | Background services, APIs     |
+
+## Core Workflow
+
+### Step 1: Register the Application
+
+Create an app registration in the Azure portal or using Azure CLI.
+
+**Portal Method:**
+
+1. Navigate to Azure Portal → Microsoft Entra ID → App registrations
+2. Click "New registration"
+3. Provide name, supported account types, and redirect URI
+4. Click "Register"
+
+**CLI Method:** See [references/cli-commands.md](references/cli-commands.md)
+**IaC Method:** See [references/BICEP-EXAMPLE.bicep](references/BICEP-EXAMPLE.bicep)
+
+It's highly recommended to use the IaC to manage Entra app registration if you already use IaC in your project, need a scalable solution for managing lots of app registrations or need fine-grained audit history of the configuration changes.
+
+### Step 2: Configure Authentication
+
+Set up authentication settings based on your application type.
+
+- **Web Apps**: Add redirect URIs, enable ID tokens if needed
+- **SPAs**: Add redirect URIs, enable implicit grant flow if necessary
+- **Mobile/Desktop**: Use `http://localhost` or custom URI scheme
+- **Services**: No redirect URI needed for client credentials flow
+
+### Step 3: Configure API Permissions
+
+Grant your application permission to access Microsoft APIs or your own APIs.
+
+**Common Microsoft Graph Permissions:**
+
+- `User.Read` - Read user profile
+- `User.ReadWrite.All` - Read and write all users
+- `Directory.Read.All` - Read directory data
+- `Mail.Send` - Send mail as a user
+
+**Details:** See [references/api-permissions.md](references/api-permissions.md)
+
+### Step 4: Create Client Credentials (if needed)
+
+For confidential client applications (web apps, services), create a client secret, certificate or federated identity credential.
+
+**Client Secret:**
+
+- Navigate to "Certificates & secrets"
+- Create new client secret
+- Copy the value immediately (only shown once)
+- Store securely (Key Vault recommended)
+
+**Certificate:** For production environments, use certificates instead of secrets for enhanced security. Upload certificate via "Certificates & secrets" section.
+
+**Federated Identity Credential:** For dynamically authenticating the confidential client to Entra platform.
+
+### Step 5: Implement OAuth Flow
+
+Integrate the OAuth flow into your application code.
+
+**See:**
+
+- [references/oauth-flows.md](references/oauth-flows.md) - OAuth 2.0 flow details
+- [references/console-app-example.md](references/console-app-example.md) - Console app implementation
+
+## Common Patterns
+
+### Pattern 1: First-Time App Registration
+
+Walk user through their first app registration step-by-step.
+
+**Required Information:**
+
+- Application name
+- Application type (web, SPA, mobile, service)
+- Redirect URIs (if applicable)
+- Required permissions
+
+**Script:** See [references/first-app-registration.md](references/first-app-registration.md)
+
+### Pattern 2: Console Application with User Authentication
+
+Create a .NET/Python/Node.js console app that authenticates users.
+
+**Required Information:**
+
+- Programming language (C#, Python, JavaScript, etc.)
+- Authentication library (MSAL recommended)
+- Required permissions
+
+**Example:** See [references/console-app-example.md](references/console-app-example.md)
+
+### Pattern 3: Service-to-Service Authentication
+
+Set up daemon/service authentication without user interaction.
+
+**Required Information:**
+
+- Service/app name
+- Target API/resource
+- Whether to use secret or certificate
+
+**Implementation:** Use Client Credentials flow (see [references/oauth-flows.md#client-credentials-flow](references/oauth-flows.md#client-credentials-flow))
+
+## MCP Tools and CLI
+
+### Azure CLI Commands
+
+| Command                      | Purpose                     |
+| ---------------------------- | --------------------------- |
+| `az ad app create`           | Create new app registration |
+| `az ad app list`             | List app registrations      |
+| `az ad app show`             | Show app details            |
+| `az ad app permission add`   | Add API permission          |
+| `az ad app credential reset` | Generate new client secret  |
+| `az ad sp create`            | Create service principal    |
+
+**Complete reference:** See [references/cli-commands.md](references/cli-commands.md)
+
+### Microsoft Authentication Library (MSAL)
+
+MSAL is the recommended library for integrating Microsoft identity platform.
+
+**Supported Languages:**
+
+- .NET/C# - `Microsoft.Identity.Client`
+- JavaScript/TypeScript - `@azure/msal-browser`, `@azure/msal-node`
+- Python - `msal`
+
+**Examples:** See [references/console-app-example.md](references/console-app-example.md)
+
+## Security Best Practices
+
+| Practice                          | Recommendation                                                  |
+| --------------------------------- | --------------------------------------------------------------- |
+| **Never hardcode secrets**        | Use environment variables, Azure Key Vault, or managed identity |
+| **Rotate secrets regularly**      | Set expiration, automate rotation                               |
+| **Use certificates over secrets** | More secure for production                                      |
+| **Least privilege permissions**   | Request only required API permissions                           |
+| **Enable MFA**                    | Require multi-factor authentication for users                   |
+| **Use managed identity**          | For Azure-hosted apps, avoid secrets entirely                   |
+| **Validate tokens**               | Always validate issuer, audience, expiration                    |
+| **Use HTTPS only**                | All redirect URIs must use HTTPS (except localhost)             |
+| **Monitor sign-ins**              | Use Entra ID sign-in logs for anomaly detection                 |
+
+## SDK Quick References
+
+- **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) | [Rust](references/sdk/azure-identity-rust.md)
+- **Key Vault (secrets)**: [Python](references/sdk/azure-keyvault-py.md) | [TypeScript](references/sdk/azure-keyvault-secrets-ts.md)
+- **Auth Events**: [.NET](references/sdk/microsoft-azure-webjobs-extensions-authentication-events-dotnet.md)
+
+## References
+
+- [OAuth Flows](references/oauth-flows.md) - Detailed OAuth 2.0 flow explanations
+- [CLI Commands](references/cli-commands.md) - Azure CLI reference for app registrations
+- [Console App Example](references/console-app-example.md) - Complete working examples
+- [First App Registration](references/first-app-registration.md) - Step-by-step guide for beginners
+- [API Permissions](references/api-permissions.md) - Understanding and configuring permissions
+- [Troubleshooting](references/troubleshooting.md) - Common issues and solutions
+
+## External Resources
+
+- [Microsoft Identity Platform Documentation](https://learn.microsoft.com/entra/identity-platform/)
+- [OAuth 2.0 and OpenID Connect protocols](https://learn.microsoft.com/entra/identity-platform/v2-protocols)
+- [MSAL Documentation](https://learn.microsoft.com/entra/msal/)
+- [Microsoft Graph API](https://learn.microsoft.com/graph/)