docs: prepare metadata-based module maintenance

[Jared Holgate (jaredfholgate)]

Overview/Summary

Document module details and ownership changes through reviewed metadata.json updates. Keep this change in draft; all six rollout gates below remain unchecked. The owner pages describe the intended approved workflow in the present tense; this is not evidence of production adoption. Maintainer rollout and security prerequisites stay here and in the existing operator references.

This PR fixes/adds/changes/removes

1. Explains which root or child metadata file to edit, supported fields, and normal validation and review. Root owners is a flat array containing every approved owner; children inherit it. Either eligible metadata code-owner team can approve. Metadata does not grant access or review rights.
2. Covers ownership changes, transfers, orphaning ("owners": []), and adoption while retaining eligibility, written consent, handover, access approval, tracking issues, and required notices. Metadata-only changes do not trigger module releases.
3. Preserves real resource types, approved pattern/utility taxonomy, Bicep paths and source-literal consistency, assigned telemetry, proposal approval, MAR approval, and language-specific retirement steps. The child-only helper contract retains JSON records and omits CSV rows; compatible helper tooling remains gated below.
4. Keeps generated public module indexes and CSV downloads as valid lookup references. Metadata corrections go to the source repository; catalog generation and reviewed publication update outputs separately.
5. Simplifies the existing owner guidance across contribution pages, FAQs, specifications, triage instructions, and reusable messages. Removes obsolete inventory/registration references and migration, backfill, preview, and bootstrap implementation narratives. Repository setup keeps the current planning example and links the repository-creation README for operator prerequisites, options, and recovery.

Latest cleanup

Pushed commit: 9dc260f14c5efe1911c3b54f6354adda4101d50a (docs: simplify module owner metadata guidance).

The cleanup changes 28 Markdown files already in this review: 91 insertions and 196 deletions. The metadata guide is about 60% shorter (2,801 to 1,119 words). No generated index data, workflow, module source, permission, or tools checkout changed. Existing full-sync backfill and automatic inference remain supported; omitting their operator details from owner pages does not remove or redefine those facilities.

Breaking Changes

1. Documentation only. No schema, tooling behavior, production setting, or authorization changes.
2. Normal metadata code-owner review, separate access approval, and source-change validation/release requirements remain.
3. Helper support, per-target adoption, and canonical catalog publication remain subject to the unchecked gates below.

Verified implementation dependencies

• Azure/azure-verified-modules-tools#138 merged at 2026-09-18T12:06:14Z, merge commit 9004c3b577626b717520e3130a7d827d4a7f043b. All 17 checks succeeded on reviewed head 56986ed6dd86c6d73fd8532b2c725729276944a9, including the full CI run. Current creation, metadata/backfill, and catalog references were inspected as text. The merge and CI are not proof of release, installation, initial-push policy approval, or production adoption.
• Azure/azure-verified-modules-tools#134 remains OPEN and unmerged at a565bdd633d345c572c31b130e0915430fe1332b, with previously verified successful exact-head checks. The child-only helper contract still needs normal approval and compatible release/adoption; it is not supported by the previously verified Oracle-compatible v0.15.1 release.
• Normal repository validation requires a compatible, separately approved installed/released schema. Source or worker compatibility does not establish consumer installation or rollout readiness. No fetched code or examples were executed.

Rollout gates - do not merge yet

• Obtain successful exact-head hosted-CI results and normal approvals for Azure/azure-verified-modules-tools#134 at a565bdd633d345c572c31b130e0915430fe1332b. The child-only marker, strict child fields, inherited owners, optional validated telemetry, JSON identity/null ARM fields, CSV omission, and source-removal guards were verified in source, and exact-head hosted checks have passed; approval, release, and adoption remain separate. Recheck the contract if the head changes. Do not treat v0.15.1 as helper-compatible or invent a release version. The repository-discovery/creation implementation in Azure/azure-verified-modules-tools#138 is merged with successful exact-head checks; its release, installation, policy approval, and adoption are still separate requirements.
• Confirm compatible tooling, metadata files, human review protection, and release guards are adopted for each affected target. Apply the helper addition only to reviewed helper submodules; preserve existing valid metadata/source and separate excluded roots. Verify stable collision-checked telemetry identifiers where required. Non-helper migration progress does not prove helper readiness or universal installation; ordinary validation still requires a compatible separately approved installed/released schema. No full settings/Azure sync is authorized for the one-off exercise. Verify adoption of default-branch root-metadata discovery and the new first-commit creation flow separately; the draft does not establish either.
• Authorized administrators verify both metadata code-owner teams' visible write access and the App installation/authorization for the particular target. Either eligible team can satisfy normal human review. The user's specific existing-App bypass authorization for this migration is not normal review/test success, a general contributor exemption, or permission to change protections/statuses. Keep per-target access/operation checks; this documentation session grants no new access or authority. New repository creation also requires create/push/custom-property rights and the narrowly scoped, verified restoration/recovery procedure; it is not an established-repository or global bypass. Obtain maintainer/SFI sign-off and an approved canary for the initial-push exception before production use; this review does not supply that approval.
• Resolve proposals without repository/source files. Preserve proposal approval, #RFRC, and issue tracking; keep excluded roots, archived review-only repositories, and missing/proposed/private targets separate. Catalog rows require valid metadata. Missing source CSV rows, including helper CSV omissions where a source row existed, block default publication unless explicitly authorized under the existing removal-only override. No invented metadata home, synthetic ARM type, full legacy fallback, or discarded proposal issue.
• Catalog publication and the separate canonical CSV changeover are ready. Verify helpers remain in JSON only, with stable identity and inherited ownership, and do not appear in CSV outputs. Source CSVs alone remain the removal baseline for preview/future overwrite destinations; JSON retention does not bypass this guard. Catalog updates stay reviewed and separate from target metadata publication. Keep test-*.csv previews separate from canonical CSVs and retain v1/modules.json until reviewed cutover. Generation and publication each require their own explicit removal-only force authorization; neither bypasses invalid metadata or other safeguards. The current catalog operator reference retains these procedures.
• Align public documentation adoption with rollout and update the internal Azure-Verified-Modules-Docs runbook. Record reviewed helper selection, compatible installed schema, JSON-versus-CSV behavior, and source-row removal review. Keep the scoped App authorization/audit trail distinct from normal human reviews, full-sync authorization, and catalog publication overrides. Include default-branch discovery, removal of the internal inventory fallback, and new-repository-only custom-property restoration, retained recovery data, and interruption handling. Add to an existing open documentation change where possible. BAMI activation remains independent.

Validation

• Passed locally on the cleanup: Markdownlint 0.41.0 with repository rules on all 28 changed files; Hugo Extended 0.136.5 with --gc --minify --ignoreCache (934 pages, 394 static files); whitespace/LF and documentation-only scope checks.
• Links and examples: 55 added internal links/anchors across the complete review, including 5 from this cleanup; all 13 references to metadata-guide anchors across the docs resolve. All 5 added external links return HTTP 200 using the existing Markdown link checker and repository configuration. All three repository-creation PowerShell examples parse without execution.
• Preserved behavior: root ownership and child inheritance, either-team review, access separation, metadata-only release guard, helper semantics, Bicep literal/path rules, telemetry assignment, proposal/MAR approval, and retirement requirements checked in source and rendered pages. Public index data and download pages are untouched.
• Hosted snapshot after push: CLA passed; five checks were running across Hugo, lint/link checks, and CodeQL. No terminal result is claimed for 9dc260f14c5efe1911c3b54f6354adda4101d50a; no polling loop or workflow dispatch was started.

No production repository creation, fleet sync, custom-property write, credential access, site publication, release, or merge was performed by this documentation session.

As part of this Pull Request I have

• Read the Contribution Guide and ensured this PR is compliant with the guide
• Checked for duplicate Pull Requests
• Associated it with relevant GitHub Issues or ADO Work Items (Internal Only)
• Ensured my code/branch is up-to-date with the latest changes in the main branch
• Ensured PR tests are passing
• Updated relevant and associated documentation (e.g. Contribution Guide, Docs etc.)