feature/align documentation standards

AGENTS.md

@@ -192,6 +192,12 @@ description: One-sentence description of what the module provisions.
 - Usage motivation and examples (1–2 developer scenarios).
 - Shared responsibility matrix (platform team vs. application team) as a markdown table with ✅ / ❌ emojis.
 
+**`backplane/README.md`** — documentation relevant to platform engineers deploying the backplane. Include an overview of what the backplane provisions, required permissions/roles, and operational notes.
+
+**Anti-pattern: `documentation_md` output** — do **not** add a `documentation_md` output to backplane modules. This is a legacy pattern. Documentation must instead be split into:
+- User-facing content → BBD `readme` field in `meshstack_integration.tf`
+- Platform-engineer-facing content → `backplane/README.md`
+
 ---
 
 ## Hub as a Shim for IaC Runtimes
@@ -369,5 +375,6 @@ Pass `module.<name>.building_block_definition.version_ref` **directly** — do n
 - [ ] `terraform { required_providers { ... } }` block is at the **bottom** of `meshstack_integration.tf`
 - [ ] `meshstack` and `hub` variables are at the end of the variable section
 - [ ] `logo.png` included in `buildingblock/`
+- [ ] No `documentation_md` output in `backplane/` — use BBD `readme` field and `backplane/README.md` instead
 - [ ] No trailing whitespace
 - [ ] **Azure modules**: also follow the [Azure Backplane Checklist](.github/instructions/azure-backplane.instructions.md#checklist-for-azure-backplanes)

modules/azure/aks/backplane/README.md

@@ -68,7 +68,6 @@ No modules.
 | <a name="output_created_hub_application"></a> [created\_hub\_application](#output\_created\_hub\_application) | Information about the created hub Azure AD application. |
 | <a name="output_created_hub_service_principal"></a> [created\_hub\_service\_principal](#output\_created\_hub\_service\_principal) | Information about the created hub service principal. |
 | <a name="output_created_service_principal"></a> [created\_service\_principal](#output\_created\_service\_principal) | Information about the created service principal. |
-| <a name="output_documentation_md"></a> [documentation\_md](#output\_documentation\_md) | Markdown documentation with information about the AKS Building Block building block backplane |
 | <a name="output_hub_application_password"></a> [hub\_application\_password](#output\_hub\_application\_password) | Information about the created hub application password (excludes the actual password value for security). |
 | <a name="output_hub_role_assignment_ids"></a> [hub\_role\_assignment\_ids](#output\_hub\_role\_assignment\_ids) | The IDs of the hub role assignments for all service principals. |
 | <a name="output_hub_role_assignment_principal_ids"></a> [hub\_role\_assignment\_principal\_ids](#output\_hub\_role\_assignment\_principal\_ids) | The principal IDs of all service principals that have been assigned the hub role. |

modules/azure/azure-virtual-machine/backplane/README.md

@@ -102,7 +102,6 @@ No modules.
 | <a name="output_application_password"></a> [application\_password](#output\_application\_password) | Information about the created application password (excludes the actual password value for security). |
 | <a name="output_created_application"></a> [created\_application](#output\_created\_application) | Information about the created Azure AD application. |
 | <a name="output_created_service_principal"></a> [created\_service\_principal](#output\_created\_service\_principal) | Information about the created service principal. |
-| <a name="output_documentation_md"></a> [documentation\_md](#output\_documentation\_md) | Markdown documentation with information about the Azure Virtual Machine Building Block backplane |
 | <a name="output_role_assignment_ids"></a> [role\_assignment\_ids](#output\_role\_assignment\_ids) | The IDs of the role assignments for all service principals. |
 | <a name="output_role_assignment_principal_ids"></a> [role\_assignment\_principal\_ids](#output\_role\_assignment\_principal\_ids) | The principal IDs of all service principals that have been assigned the role. |
 | <a name="output_role_definition_id"></a> [role\_definition\_id](#output\_role\_definition\_id) | The ID of the role definition that enables deployment of the building block to subscriptions. |

modules/azure/container-registry/backplane/README.md

@@ -183,7 +183,6 @@ No modules.
 | <a name="output_created_hub_application"></a> [created\_hub\_application](#output\_created\_hub\_application) | Information about the created hub Azure AD application. |
 | <a name="output_created_hub_service_principal"></a> [created\_hub\_service\_principal](#output\_created\_hub\_service\_principal) | Information about the created hub service principal. |
 | <a name="output_created_service_principal"></a> [created\_service\_principal](#output\_created\_service\_principal) | Information about the created service principal. |
-| <a name="output_documentation_md"></a> [documentation\_md](#output\_documentation\_md) | Markdown documentation with information about the Container Registry Building Block backplane |
 | <a name="output_hub_application_password"></a> [hub\_application\_password](#output\_hub\_application\_password) | Information about the created hub application password (excludes the actual password value for security). |
 | <a name="output_hub_role_assignment_ids"></a> [hub\_role\_assignment\_ids](#output\_hub\_role\_assignment\_ids) | The IDs of the hub role assignments for all service principals. |
 | <a name="output_hub_role_assignment_principal_ids"></a> [hub\_role\_assignment\_principal\_ids](#output\_hub\_role\_assignment\_principal\_ids) | The principal IDs of all service principals that have been assigned the hub role. |

modules/azure/github-actions-terraform-setup/backplane/README.md

@@ -199,6 +199,5 @@ No modules.
 
 | Name | Description |
 |------|-------------|
-| <a name="output_documentation_md"></a> [documentation\_md](#output\_documentation\_md) | n/a |
 | <a name="output_provider_config"></a> [provider\_config](#output\_provider\_config) | ENVIRONMENT VARIABLES for the AzureRM and AzureAD Providers, which you can use to configure your Building Block Definition. |
 <!-- END_TF_DOCS -->

modules/azure/key-vault/backplane/README.md

@@ -72,7 +72,6 @@ No modules.
 | <a name="output_created_hub_application"></a> [created\_hub\_application](#output\_created\_hub\_application) | Information about the created hub Azure AD application. |
 | <a name="output_created_hub_service_principal"></a> [created\_hub\_service\_principal](#output\_created\_hub\_service\_principal) | Information about the created hub service principal. |
 | <a name="output_created_service_principal"></a> [created\_service\_principal](#output\_created\_service\_principal) | Information about the created service principal. |
-| <a name="output_documentation_md"></a> [documentation\_md](#output\_documentation\_md) | Markdown documentation with information about the Key Vault Building Block building block backplane |
 | <a name="output_hub_application_password"></a> [hub\_application\_password](#output\_hub\_application\_password) | Information about the created hub application password (excludes the actual password value for security). |
 | <a name="output_hub_role_assignment_ids"></a> [hub\_role\_assignment\_ids](#output\_hub\_role\_assignment\_ids) | The IDs of the hub role assignments for all service principals. |
 | <a name="output_hub_role_assignment_principal_ids"></a> [hub\_role\_assignment\_principal\_ids](#output\_hub\_role\_assignment\_principal\_ids) | The principal IDs of all service principals that have been assigned the hub role. |

modules/azure/postgresql/backplane/README.md

@@ -1,10 +1,14 @@
-# Azure Subscription Postgresql
+# Azure PostgreSQL Building Block — Backplane
 
-This documentation is intended as a reference documentation for cloud foundation or platform engineers using this module.
+This documentation is intended as a reference for platform engineers deploying the PostgreSQL Building Block backplane.
+
+## Overview
+
+The backplane provisions the automation identity and permissions required to deploy Azure Database for PostgreSQL on behalf of application teams.
 
 ## Permissions
 
-This is a very simple building block, which means we let the SPN have access to Key Vault
+This is a simple building block backplane that grants the automation principal access to PostgreSQL
 across all subscriptions underneath a management group (typically the top-level management group for landing zones).
 
 <!-- BEGIN_TF_DOCS -->
@@ -39,7 +43,6 @@ No modules.
 
 | Name | Description |
 |------|-------------|
-| <a name="output_documentation_md"></a> [documentation\_md](#output\_documentation\_md) | Markdown documentation with information about the Key Vault Building Block building block backplane |
 | <a name="output_role_assignment_ids"></a> [role\_assignment\_ids](#output\_role\_assignment\_ids) | The IDs of the role assignments for the service principals. |
 | <a name="output_role_assignment_principal_ids"></a> [role\_assignment\_principal\_ids](#output\_role\_assignment\_principal\_ids) | The principal IDs of the service principals that have been assigned the role. |
 | <a name="output_role_definition_id"></a> [role\_definition\_id](#output\_role\_definition\_id) | The ID of the role definition that enables deployment of the building block to subscriptions. |