docs: prepare metadata-based module maintenance

docs/content/contributing/_index.md

@@ -10,6 +10,7 @@ This section lists all contribution guidance available to module owners and cont
 - [Process Overview]({{% siteparam base %}}/contributing/process/)
 - [Bicep Contribution Guide]({{% siteparam base %}}/contributing/bicep/)
 - [Terraform Contribution Guide]({{% siteparam base %}}/contributing/terraform/)
+- [Module Metadata]({{% siteparam base %}}/contributing/module-metadata/) - maintaining module details and ownership
 - [Contribution Q&A]({{% siteparam base %}}/contributing/q-and-a/)
 - [Website Contribution Guide]({{% siteparam base %}}/contributing/website/)
 - [Code of Conduct](https://opensource.microsoft.com/codeofconduct/)

docs/content/contributing/bicep/bicep-contribution-flow/child-module-publishing.md

@@ -32,7 +32,7 @@ Supporting child module publishing for other module categories, such as pattern
 Use this section for a fast overview on how to publish a child module.
 For a step-by-step explanation with detailed instructions, refer to the following sections.
 
-* **Check prerequisites**: Existing [issue in AVM](https://github.com/Azure/Azure-Verified-Modules/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Class%3A%20Child%20Module%20%3Apackage%3A%22%20label%3A%22Language%3A%20Bicep%20%3Amuscle%3A%22), telemetry ID prefix assigned in [Bicep Module Index CSV](https://github.com/Azure/Azure-Verified-Modules/blob/main/docs/static/module-indexes/BicepResourceModules.csv), module registered in the [MAR file](https://github.com/microsoft/mcr/blob/main/teams/bicep/bicep.yml).
+* **Check prerequisites**: Existing [issue in AVM](https://github.com/Azure/Azure-Verified-Modules/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Class%3A%20Child%20Module%20%3Apackage%3A%22%20label%3A%22Language%3A%20Bicep%20%3Amuscle%3A%22), [assigned telemetry ID prefix](#telemetry-id-prefix-assigned), module registered in the [MAR file](https://github.com/microsoft/mcr/blob/main/teams/bicep/bicep.yml).
 * Implement required changes in your fork:
   * **Allowed list**: If not present, add child module to [child-module-publish-allowed-list.json](https://github.com/Azure/bicep-registry-modules/blob/main/utilities/pipelines/staticValidation/compliance/helper/child-module-publish-allowed-list.json).
   * **Child module template**: Add `enableTelemetry` parameter and `avmTelemetry` deployment to child `main.bicep` template.
@@ -67,16 +67,24 @@ If the Bicep Child Module Proposal issue was just created, please allow a few da
 
 {{% /notice %}}
 
+Check `telemetryIdPrefix` in the child's own `metadata.json` and keep it consistent with the child module source. Record only the assigned identifier through [metadata review]({{% siteparam base %}}/contributing/module-metadata/). Ownership is inherited from the root.
+
+You can also look up the assigned prefix in the published index:
+
 1. Check the online [Bicep resource module index source CSV](https://github.com/Azure/Azure-Verified-Modules/blob/main/docs/static/module-indexes/BicepResourceModules.csv).
 1. Search for the child module name in the `ModuleName` field.
 1. Verify if the corresponding value exists in the `TelemetryIdPrefix` field. Note down the value as you will need it in the implementation phase.
 1. If not found, please reach out to the core team, mentioning the `@Azure/azure-verified-modules-tooling-contributors` via the Bicep Child Module Proposal issue.
 
+If the identifier is missing or conflicts with the index, ask the core team to resolve it. Do not invent an identifier or copy the parent's prefix.
+
 ### Module registered in the MAR-file
 
 Ensure that the child module is registered in the [MAR file](https://github.com/microsoft/mcr/blob/main/teams/bicep/bicep.yml).
 If not, please reach out to the core team, mentioning the `@Azure/azure-verified-modules-tooling-contributors` via the Bicep Child Module Proposal issue.
 
+Metadata approval does not replace MAR registration or approval to publish the child module.
+
 {{% notice style="note" %}}
 
 The MAR-file can only be accessed by Microsoft FTEs. If you are missing access, please reach out to the parent module owner for help.

docs/content/contributing/bicep/bicep-contribution-flow/owner-contribution-flow.md

@@ -25,9 +25,9 @@ Familiarize yourself with the responsibilities as **Module Owner** outlined in [
 
 1. Request and obtain approval for the **[Azure Verified Modules (AVM) Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor)** as outlined in [SNFR20]({{% siteparam base %}}/spec/SNFR20#bicep). This is required for every primary, secondary, or additional Bicep module owner. Only full-time Microsoft employees can be module owners.
 
-    You no longer need to create a per-module GitHub team, assign a parent team, or add the team to `CODEOWNERS`. Access is managed through the shared `@Azure/azure-verified-modules-module-contributors` team.
+    Access is managed through the shared `@Azure/azure-verified-modules-module-contributors` team.
 
-1. Ensure the [module index]({{% siteparam base %}}/indexes/bicep/) records the correct owners for your module. Coordinate ownership changes with the AVM Core Team.
+1. Maintain every approved handle in the `owners` array in your module's root `metadata.json`. Coordinate changes with the AVM Core Team and follow the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/).
 1. Ensure your module has been tested before raising a PR. You can do this your own or in another module contributor's environment - if any. Also, once a PR is raised, a GitHub workflow pipeline is required to be run successfully before the PR can be merged. This is to ensure that the module is working as expected and is compliant with the AVM specifications.
 {{% notice style="note" %}}
 
@@ -42,16 +42,16 @@ If you're the **sole owner of the module**, the **AVM core team must review and
 
 Under certain circumstances, you may find yourself unable to continue as the module owner. In such cases, it is advisable to designate a new module owner. The following steps outline this transition:
 
-- Follow the [hot-swapping module owners]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#hot-swapping-module-owners) process and wait for the AVM Core Team to confirm the ownership change in the module index.
+- Follow the [hot-swapping module owners]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#hot-swapping-module-owners) process. Transfer ownership in one root metadata change and wait for approval from either metadata code-owner team and merge before finalizing the handover.
 - Ensure every incoming owner has approved access through the [Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor).
 
-No per-module GitHub team membership or `CODEOWNERS` changes are required. Do not remove shared AVM access solely because one module changes owners; it may still be needed for other modules.
+Do not remove shared AVM access solely because one module changes owners; it may still be needed for other modules.
 
 If a new module owner cannot be identified then the module will need to be "Orphaned". Please follow the step outlined [when-a-module-becomes-orphaned]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-module-becomes-orphaned).
 
 ## 3. Adopting an Orphaned Module
 
-When adopting an orphaned module the [when-a-new-owner-is-identified]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-new-owner-is-identified) steps must be followed.
+Follow the [adoption process]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-new-owner-is-identified). Add approved owners to the root `metadata.json` through metadata code-owner review and complete the eligibility, consent, access approval, and notice-removal steps.
 
 ## 4. GitHub Notification Settings
 

docs/content/contributing/module-metadata.md

@@ -0,0 +1,99 @@
+---
+title: Module Metadata
+description: Maintaining module metadata and ownership for the Azure Verified Modules (AVM) program
+---
+
+Maintain a module's details and ownership in `metadata.json` in its source repository. Submit changes through the [review process](#submit-and-review-a-change) below.
+
+## Find the correct file
+
+| Language | Root module metadata |
+| --- | --- |
+| Bicep | `avm/{res,ptn,utl}/{group}/{module}/metadata.json` in [Azure/bicep-registry-modules](https://github.com/Azure/bicep-registry-modules). Use the existing module's actual path. |
+| Terraform | `metadata.json` at the root of the module's own repository. Find that repository through the [module indexes]({{% siteparam base %}}/indexes/). |
+
+Child modules have reduced `metadata.json` files in their own folders. They inherit ownership from the root module, including when nested more than one level deep. **Change owners only in the root file**; child files must not contain `owners`.
+
+Use the existing file as your starting point and preserve unrelated values. If metadata or an assigned value is missing, ask the AVM core team to confirm the required values.
+
+## Create metadata.json when scaffolding a new module
+
+Every new Bicep or Terraform root module, and every new child module or submodule, **MUST** have a valid `metadata.json` created as part of scaffolding, not added later.
+
+- **Root modules** get the full metadata shape, including the `owners` array.
+- **Child modules and submodules** get the reduced, inherited-owner shape described above; they must not contain `owners`.
+
+Use `avm metadata initialize` from the [`Avm.Authoring`](https://www.powershellgallery.com/packages/Avm.Authoring) PowerShell module to scaffold the file for either ecosystem. It validates the supplied values against the versioned schema and writes `metadata.json` without overwriting an existing file. Pass `--child-module` when scaffolding a child module or submodule so it produces the reduced, owner-less shape. Validate an existing file with `avm metadata validate`, or inspect one with `avm metadata show`.
+
+## Fields you can maintain
+
+The versioned schema referenced by the required `$schema` URI defines the supported fields.
+
+| Field | Guidance |
+| --- | --- |
+| `$schema` | Keep the required versioned schema URI. It identifies the module metadata schema. |
+| `moduleDisplayName`, `moduleDescription` | Maintain the module's display name and description. For Bicep, they must match the corresponding literals in `main.bicep`. |
+| `canonicalType` | The real ARM resource type, or the approved pattern/utility taxonomy. [Helper submodules](#helper-submodules) use `helper`. |
+| `owners` | Root only: a flat array of strings containing every approved owner. Use bare GitHub handles for individuals and qualified handles such as `@Azure/team-name` for approved existing teams. |
+| `telemetryIdPrefix` | Preserve the assigned identifier where required. Do not generate a replacement identifier as part of an ownership or descriptive edit. |
+| `alternativeNames`, `comments` | Optional root-module aliases and notes. These are public metadata. |
+
+Pattern and utility `canonicalType` values can have one or more segments, such as `naming` for `avm-utl-naming`. Preserve the module's approved mapping. Resource modules and non-helper resource children use their actual ARM resource type.
+
+Module identity and parent relationships come from the repository layout. Changing `moduleDisplayName` does not rename a module or move its repository.
+
+### Helper submodules
+
+Helper submodules use the exact `"canonicalType": "helper"` marker with the required `$schema`, `moduleDisplayName`, and `moduleDescription`. Ownership is inherited from the root. Use this marker only for helper children, not root modules or resource children.
+
+Helper telemetry is optional; any supplied `telemetryIdPrefix` must pass validation. Helpers appear in the JSON catalog, not in CSV outputs.
+
+## Submit and review a change
+
+1. Agree the change with the current owners and the AVM core team. For ownership changes, retain the eligibility checks, incoming owners' written consent, and handover requirements in the [owner-change process]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#changing-module-owners).
+1. Edit the relevant `metadata.json` on a branch or in your fork of the module repository. Preserve all owners and other values that are not part of the agreed change.
+1. Submit a pull request to that repository, linking the proposal or ownership-tracking issue when the process requires one. Describe the intended changes and request review from either [`@Azure/azure-verified-modules-engineering-owners`](https://github.com/orgs/Azure/teams/azure-verified-modules-engineering-owners) or [`@Azure/azure-verified-modules-module-owners`](https://github.com/orgs/Azure/teams/azure-verified-modules-module-owners).
+1. Validate metadata using the repository's approved tooling and satisfy its required reviews before merging. Approval from an eligible member of **either** team satisfies metadata code-owner review; approval from both teams is **not** required. Being listed in the module's `owners` array does not by itself authorize someone to approve. Any code changes in the same pull request still need their normal code review and tests.
+1. Follow the change through catalog generation and reviewed publication. Do not edit the generated CSV or JSON output to duplicate the metadata change.
+
+**Metadata-only changes must not trigger a module release.** Do not change version files or create a release just to update owners or other metadata. A Bicep name or description correction may also require changing `main.bicep` to keep its literals consistent; that is a source change and must follow normal validation and release rules, not be treated as metadata-only.
+
+Editing metadata does not grant or revoke repository permissions, create teams, change identities, or provision Azure access. Every incoming owner still needs the separate access approval described in [SNFR20]({{% siteparam base %}}/spec/SNFR20). Do not remove shared access solely because someone stops owning one module.
+
+## Ownership changes
+
+### Add, remove, or transfer owners
+
+Update the `owners` array in the root metadata file. Add the approved incoming handles and remove only the departing handles. Keep every continuing individual or team owner.
+
+For a direct transfer, follow [hot swapping module owners]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#hot-swapping-module-owners) and make the outgoing and incoming owner changes together, so the module does not pass through an unowned state. Do not reopen a closed module proposal.
+
+### Orphan a module
+
+Follow [when a module becomes orphaned]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-module-becomes-orphaned), including its tracking issue and required notices.
+
+In the root metadata file, set `"owners": []`, removing all individual and team handles from the array. Keep the remaining metadata intact. The catalog calculates `Orphaned` when no owner exists, while preserving an existing `Deprecated` status.
+
+### Adopt an orphaned module
+
+Follow [when a new owner is identified]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-new-owner-is-identified). After eligibility and consent are confirmed, add the approved incoming handles to the root metadata's `owners` array and obtain approval from either metadata code-owner team.
+
+Complete the separate access approval and notice-removal steps before closing the ownership issue. Adding owners does not revive a deprecated module.
+
+## Catalog updates
+
+Catalog generation and reviewed publication carry metadata changes to the [module indexes and CSV downloads]({{% siteparam base %}}/indexes/). Merging metadata does not immediately update those outputs. The AVM core team manages publication using the [catalog tooling](https://github.com/Azure/azure-verified-modules-tools/tree/main/repository-management/module-catalog).
+
+CSV owner columns show the first two individuals. Root metadata and the JSON catalog contain the full owner list. Propose corrections in the module's metadata rather than editing generated outputs.
+
+## Related processes
+
+**New proposals:** Follow the [module proposal and approval process]({{% siteparam base %}}/contributing/process/#new-module-proposal--creation). Keep approved details in the proposal issue until the repository and module source exist; do not create placeholder metadata.
+
+**Publication:** Registry publication is required before a module is available. A metadata change does not publish a module.
+
+**Deprecation:** Follow the [deprecation process]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-module-becomes-deprecated), including approval, notices, and language-specific retirement steps. The catalog derives deprecation from Bicep's `DEPRECATED.md` or the Terraform repository's `archived` flag, not an authored metadata status.
+
+A Bicep marker applies to its module and descendants, not its parent or siblings. Terraform archival applies to every module entry in that repository. Changing owners does not deprecate or reactivate a module.
+
+**Bicep child publishing:** [Telemetry assignment and Microsoft Artifact Registry (MAR) approval]({{% siteparam base %}}/contributing/bicep/bicep-contribution-flow/child-module-publishing/#prerequisites) remain required. Recording metadata does not grant permission to publish a child module.