fix(namespace): set location as top-level attribute on azapi_resource

.agents/skills/AVM-Terraform-Development/SKILL.md → .agents/skills/avm-terraform-module-development/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: AVM-Terraform-Development
+name: avm-terraform-module-development
 description: Azure Verified Modules (AVM) Terraform development workflow for fixing issues and adding features
 glob: "**/*.terraform,**/*.tf,**/*.tfvars,**/*.tfstate,**/*.tflint.hcl,**/*.tf.json,**/*.tfvars.json"
 ---
@@ -29,23 +29,23 @@ git checkout -b fix/<issue-number>-<short-description>
 
 ### Step 3: Implement the change
 
-All Azure resources MUST be deployed using the **AzAPI provider** (`Azure/azapi`). For AzAPI resource patterns, schema lookups, and the `azure-schema` CLI tool, read [AzAPI.md](AzAPI.md).
+All Azure resources MUST be deployed using the **AzAPI provider** (`Azure/azapi`). For AzAPI resource patterns, schema lookups, and the `azure-schema` CLI tool, read [AzAPI.md](references/AzAPI.md).
 
-To query Terraform provider schemas (resources, data sources, functions, ephemeral resources), use the `tfpluginschema` CLI. See [tfpluginschema.md](tfpluginschema.md).
+To query Terraform provider schemas (resources, data sources, functions, ephemeral resources), use the `tfpluginschema` CLI. See [tfpluginschema.md](references/tfpluginschema.md).
 
 Make the necessary code changes to add the feature or fix the issue.
 
 ### Step 4: Add unit tests (if justified)
 
-Unit tests use **provider mocking** and live in the `tests/unit` directory. Add or update unit tests when your change introduces new logic, variables, or outputs that can be validated without deploying real infrastructure. For test writing guidance, syntax, and patterns, read [terraform-test.md](terraform-test.md).
+Unit tests use **provider mocking** and live in the `tests/unit` directory. Add or update unit tests when your change introduces new logic, variables, or outputs that can be validated without deploying real infrastructure. For test writing guidance, syntax, and patterns, read [terraform-test.md](references/terraform-test.md).
 
 ```bash
 PORCH_NO_TUI=1 ./avm tf-test-unit
 ```
 
 ### Step 5: Add integration tests (if justified)
 
-Integration tests do **not** use provider mocking and live in the `tests/integration` directory. Add or update integration tests when your change requires validation against real Azure infrastructure. For test writing guidance, syntax, and patterns, read [terraform-test.md](terraform-test.md).
+Integration tests do **not** use provider mocking and live in the `tests/integration` directory. Add or update integration tests when your change requires validation against real Azure infrastructure. For test writing guidance, syntax, and patterns, read [terraform-test.md](references/terraform-test.md).
 
 ```bash
 PORCH_NO_TUI=1 ./avm tf-test-integration
@@ -59,6 +59,8 @@ If your change affects module usage or introduces new functionality, add or upda
 PORCH_NO_TUI=1 AVM_EXAMPLE="<ExampleDir>" ./avm test-examples
 ```
 
+When running on Windows, distributing tests across multiple Azure subscriptions, or retaining deployed resources for manual validation, see [example-test.md](references/example-test.md) for manual local testing of examples (init, plan, apply, idempotency check, and optional destroy).
+
 ### Step 7: Update documentation (if justified)
 
 If documentation changes are needed, edit `_header.md`. **NEVER edit README.md directly** -- it is auto-generated and will be overwritten.
@@ -118,8 +120,9 @@ If any issues arise during testing or PR checks, refer to the official AVM testi
 
 ### Tool Integration
 
-- **AzAPI Provider & Schema Lookup**: See [AzAPI.md](AzAPI.md) for resource patterns and the `azure-schema` CLI tool
-- **Terraform Provider Schemas**: See [tfpluginschema.md](tfpluginschema.md) for querying resource, data source, function, and ephemeral schemas from any provider
-- **Terraform Tests**: See [terraform-test.md](terraform-test.md) for writing unit and integration tests
+- **AzAPI Provider & Schema Lookup**: See [AzAPI.md](references/AzAPI.md) for resource patterns and the `azure-schema` CLI tool
+- **Terraform Provider Schemas**: See [tfpluginschema.md](references/tfpluginschema.md) for querying resource, data source, function, and ephemeral schemas from any provider
+- **Terraform Tests**: See [terraform-test.md](references/terraform-test.md) for writing unit and integration tests
+- **Example Testing**: See [example-test.md](references/example-test.md) for manually testing examples against real Azure infrastructure
 - **Deployment Guidance**: Use `azure_get_deployment_best_practices` tool
 - **Service Documentation**: Use `microsoft.docs.mcp` tool for Azure service-specific guidance

.agents/skills/AVM-Terraform-Development/AzAPI.md → .agents/skills/avm-terraform-module-development/references/AzAPI.md

@@ -79,34 +79,57 @@ mock_provider "azapi" {}
 
 ## Azure Resource Schema Lookup
 
-Use the `azure-schema` CLI tool (bundled at `.agents/skills/AVM-Terraform-Development/azure-schema`) to look up resource type schemas, properties, constraints, and available API versions. This is essential for knowing the correct `type` and `body` structure for `azapi_resource`.
+Use the `azure-schema` CLI tool to look up resource type schemas, properties, constraints, and available API versions. This is essential for knowing the correct `type` and `body` structure for `azapi_resource`.
+
+- **Bash**: `.agents/skills/avm-terraform-module-development/scripts/azure-schema`
+- **PowerShell**: `.agents/skills/avm-terraform-module-development/scripts/azure-schema.ps1`
 
 ### List available API versions
 
 ```bash
-.agents/skills/AVM-Terraform-Development/azure-schema versions Microsoft.Storage
+.agents/skills/avm-terraform-module-development/scripts/azure-schema versions Microsoft.Storage
+```
+
+```powershell
+.agents/skills/avm-terraform-module-development/scripts/azure-schema.ps1 versions Microsoft.Storage
 ```
 
 ### Get a resource schema (human-readable)
 
 ```bash
-.agents/skills/AVM-Terraform-Development/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01
+.agents/skills/avm-terraform-module-development/scripts/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01
+```
+
+```powershell
+.agents/skills/avm-terraform-module-development/scripts/azure-schema.ps1 get Microsoft.Storage/storageAccounts 2023-01-01
 ```
 
 ### Get a resource schema (resolved JSON)
 
 ```bash
-.agents/skills/AVM-Terraform-Development/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01 --json
+.agents/skills/avm-terraform-module-development/scripts/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01 --json
+```
+
+```powershell
+.agents/skills/avm-terraform-module-development/scripts/azure-schema.ps1 get Microsoft.Storage/storageAccounts 2023-01-01 -Json
 ```
 
 ### Control depth
 
 ```bash
 # Shallow view (top-level properties only)
-.agents/skills/AVM-Terraform-Development/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01 --depth 2
+.agents/skills/avm-terraform-module-development/scripts/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01 --depth 2
+
+# Deep view (default is 5)
+.agents/skills/avm-terraform-module-development/scripts/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01 --depth 8
+```
+
+```powershell
+# Shallow view (top-level properties only)
+.agents/skills/avm-terraform-module-development/scripts/azure-schema.ps1 get Microsoft.Storage/storageAccounts 2023-01-01 -Depth 2
 
 # Deep view (default is 5)
-.agents/skills/AVM-Terraform-Development/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01 --depth 8
+.agents/skills/avm-terraform-module-development/scripts/azure-schema.ps1 get Microsoft.Storage/storageAccounts 2023-01-01 -Depth 8
 ```
 
 ## Sensitive attributes

.agents/skills/avm-terraform-module-development/references/example-test.md

@@ -0,0 +1,69 @@
+# Testing Examples Manually
+
+> **When to use this reference:**
+>
+> - You are running on **Windows** (on non-Windows systems, use the `avm` command instead).
+> - You want to **distribute tests across multiple Azure subscriptions**.
+> - You want to **retain deployed resources** after testing for manual validation (skip destroy).
+
+Each subfolder under `examples/` is a standalone Terraform root module. Test each one independently.
+
+## Testing Workflow
+
+For each example directory, run these steps in order. Stop and fix any errors before proceeding.
+
+1. Run Terraform init
+2. Run Terraform plan
+3. Run Terraform apply
+4. Run Terraform plan again (idempotency check)
+
+The idempotency check (step 4) must show **"No changes"**. If it reports drift, that is a bug - fix it. Common causes:
+
+- **Server-side defaults**: A property not set in config gets a default from Azure. Set it explicitly. Use `ignore_changes` only as a last resort.
+- **Computed attributes**: An output or reference that changes on every read.
+- **Provider bugs**: Check for known issues in the provider repository.
+
+### Destroy
+
+**Ask the user before destroying.** They may want to inspect resources in the Azure portal or keep them for debugging.
+
+```powershell
+terraform destroy
+```
+
+Some resources (e.g., soft-delete enabled Key Vaults) may require manual purging.
+
+## Distributing Examples Across Subscriptions
+
+To avoid quota limits or reduce blast radius, distribute examples across multiple subscriptions.
+
+**Always ask the user before changing the subscription.**
+
+Set `ARM_SUBSCRIPTION_ID` before running each example:
+
+```powershell
+$env:ARM_SUBSCRIPTION_ID = "<subscription-id>"
+```
+
+### Round-Robin Example
+
+```powershell
+$subscriptions = @(
+  "00000000-0000-0000-0000-000000000001"
+  "00000000-0000-0000-0000-000000000002"
+  "00000000-0000-0000-0000-000000000003"
+)
+
+$i = 0
+foreach ($dir in Get-ChildItem -Path examples -Directory) {
+  $env:ARM_SUBSCRIPTION_ID = $subscriptions[$i % $subscriptions.Count]
+  Write-Host "=== Testing $($dir.Name) on subscription $env:ARM_SUBSCRIPTION_ID ==="
+  Push-Location $dir.FullName
+  terraform init -upgrade
+  terraform plan -out=tfplan
+  terraform apply tfplan
+  terraform plan  # idempotency check
+  Pop-Location
+  $i++
+}
+```

.agents/skills/AVM-Terraform-Development/tfpluginschema.md → .agents/skills/avm-terraform-module-development/references/tfpluginschema.md

@@ -19,6 +19,18 @@ curl -sSfL https://github.com/matt-FFFFFF/tfpluginschema/releases/latest/downloa
 curl -sSfL https://github.com/matt-FFFFFF/tfpluginschema/releases/latest/download/tfpluginschema_0.8.0_darwin_amd64.tar.gz | tar -xz -C /usr/local/bin tfpluginschema
 ```
 
+```powershell
+# Windows (amd64)
+$url = "https://github.com/matt-FFFFFF/tfpluginschema/releases/latest/download/tfpluginschema_0.8.0_windows_amd64.zip"
+$dest = Join-Path $HOME ".tfpluginschema"
+New-Item -ItemType Directory -Path $dest -Force | Out-Null
+Invoke-WebRequest -Uri $url -OutFile (Join-Path $dest "tfpluginschema.zip")
+Expand-Archive -Path (Join-Path $dest "tfpluginschema.zip") -DestinationPath $dest -Force
+Remove-Item (Join-Path $dest "tfpluginschema.zip")
+# Add to PATH if not already present
+if ($env:PATH -notlike "*$dest*") { $env:PATH += ";$dest" }
+```
+
 Check latest version at: <https://github.com/matt-FFFFFF/tfpluginschema/releases>
 
 ## Global Options
@@ -34,13 +46,13 @@ Check latest version at: <https://github.com/matt-FFFFFF/tfpluginschema/releases
 
 ### List available provider versions
 
-```bash
+```sh
 tfpluginschema -n Azure -p azapi version list
 ```
 
 ### List resources, data sources, functions, or ephemeral resources
 
-```bash
+```sh
 tfpluginschema -n Azure -p azapi resource list
 tfpluginschema -n Azure -p azapi datasource list
 tfpluginschema -n Azure -p azapi function list
@@ -49,43 +61,43 @@ tfpluginschema -n Azure -p azapi ephemeral list
 
 ### Get a resource schema
 
-```bash
+```sh
 tfpluginschema -n Azure -p azapi resource schema azapi_resource
 ```
 
 ### Get a data source schema
 
-```bash
+```sh
 tfpluginschema -n Azure -p azapi datasource schema azapi_client_config
 ```
 
 ### Get a function schema
 
-```bash
+```sh
 tfpluginschema -n Azure -p azapi function schema build_resource_id
 ```
 
 ### Get an ephemeral resource schema
 
-```bash
+```sh
 tfpluginschema -n Azure -p azapi ephemeral schema azapi_resource_action
 ```
 
 ### Get the provider configuration schema
 
-```bash
+```sh
 tfpluginschema -n Azure -p azapi provider schema
 ```
 
 ### Pin to a specific provider version
 
-```bash
+```sh
 tfpluginschema -n Azure -p azapi --pv 2.5.0 resource schema azapi_resource
 ```
 
 ### Use a version constraint
 
-```bash
+```sh
 tfpluginschema -n hashicorp -p azurerm --pv "~>4.0" resource list
 ```