v0.8.2 docs: surface the custom-role Description rewrite in release notes

Following commit f578eca (which rewrote the 'Azure Stack HCI Update
Operator' custom-role Description to drop the module-internal 'Step.4'
reference), this commit promotes the change from a quiet code edit to
a documented v0.8.2 feature, since the Description is operator-visible
in the Azure portal 'Custom roles' blade.

Added matching sections in all four release-note surfaces:

- AzLocal.UpdateManagement/CHANGELOG.md (full bulleted '### ... custom-
  role Description rewritten to drop module-internal jargon' section
  with old text, new text, 'same RBAC grant' clarification, 'no
  operator action required' nudge, and the 6-site lockstep list)
- AzLocal.UpdateManagement/docs/release-history.md (single-paragraph
  v0.8.2 What's-New entry)
- AzLocal.UpdateManagement/README.md ('### ... custom-role Description
  rewritten to drop module-internal jargon' section in the top-level
  'What's New in v0.8.2' block)
- AzLocal.UpdateManagement/AzLocal.UpdateManagement.psd1
  PrivateData.PSData.ReleaseNotes (one bullet for the PSGallery module
  page)

ReleaseNotes length: 9278 / 10000 chars (was 7731 - comfortable
headroom). Test-ModuleManifest still parses clean, ModuleVersion still
'0.8.2'. No code changes; docs-only.

Author: NeilBird

AzLocal.UpdateManagement/AzLocal.UpdateManagement.psd1

@@ -230,6 +230,8 @@ Operator-experience release. No public API changes; no output-shape changes that
   2. The advisor now emits a `> **Indent tip.**` blockquote directly above the snippet. The GH snippet is intentionally at 2-space indent (so `schedule:` is a sibling of the existing `workflow_dispatch:` under `on:`); pasting with the cursor sitting inside the `# BEGIN-AZLOCAL-CUSTOMIZE:schedule-triggers` comment block causes VS Code (and JetBrains IDEs) to silently double the indent, producing the YAML error *"All mapping items must start at the same column"*. The blockquote explains the cause and how to recover.
 - **`Test-AzLocalApplyUpdatesScheduleCoverage -View Audit` `NoWindowTag` row is now actionable on its own**: the recommendation lists the first 15 affected cluster names grouped by their `UpdateRing` tag (or `(none)` when both tags are missing), e.g. `Prod -> hci-syd-01, hci-syd-02; Wave1 -> hci-mel-01 (+3 more) (showing first 15 of 42)`. The issue text is clarified to say the `UpdateStartWindow` tag is optional (the runtime gate only enforces a window when the tag is set, so untagged clusters are not a blocker), and the row sorts AFTER `Covered` (rank 10 instead of 7) so these informational rows do not push real coverage gaps off-screen.
 - **Step.3 Allow-list section trimmed in both GH and ADO scaffolds**: the `Allow-list coverage (schema v2)` subsection no longer emits the verbose `> Tip - per-ring overrides` paragraph + 3-row example block. Inheriting the top-level allow-list IS the expected steady state for most fleets; the verbose tip was misleading operators into thinking they had to add overrides. The new shape is a one-line steady-state confirmation plus a dedicated `### How to fix - edit $schedulePath` subsection (naming the schedule file) and a single-row YAML example for the case where an operator wants to PIN a ring to a specific update (e.g. keep Prod on YY04/YY10 feature drops only).
+- **Step.3 Allow-list section trimmed in both GH and ADO scaffolds**: the `Allow-list coverage (schema v2)` subsection no longer emits the verbose `> Tip - per-ring overrides` paragraph + 3-row example block. Inheriting the top-level allow-list IS the expected steady state for most fleets; the verbose tip was misleading operators into thinking they had to add overrides. The new shape is a one-line steady-state confirmation plus a dedicated `### How to fix - edit $schedulePath` subsection (naming the schedule file) and a single-row YAML example for the case where an operator wants to PIN a ring to a specific update (e.g. keep Prod on YY04/YY10 feature drops only).
+- **`Azure Stack HCI Update Operator` custom-role Description rewritten** to drop the module-internal `Step.4` reference. The Description shipped into the Azure RBAC plane (visible in the Azure portal Custom roles blade, in `az role definition list` / `Get-AzRoleDefinition`, and in RBAC audit/governance tooling) - `Step.4` was meaningless outside this module. New text: *"Can read and apply Azure Local cluster updates, manage UpdateRing tags, and read the fleet-connectivity inventory (Arc-enabled machines, edge-device NICs, Azure Resource Bridges) needed to assess pre-update connectivity."* Same RBAC grant (Actions / NotActions / DataActions / AssignableScopes byte-identical); operators with the role already deployed need no action - the next `az role definition update --role-definition ./azlocal-update-management-custom-role.json` will refresh the Description.
 - **Five new internal pipeline-host helpers added** (not exported, no user-visible effect in v0.8.2): `Get-AzLocalPipelineHost`, `Set-AzLocalPipelineOutput`, `Add-AzLocalPipelineStepSummary`, `Write-AzLocalPipelineNotice`, `Write-AzLocalPipelineWarning`. They abstract over GitHub Actions vs Azure DevOps output channels (`$env:GITHUB_OUTPUT` vs `##vso[task.setvariable]`, etc.). 23 new Pester assertions cover the three host modes (GitHub via `$env:GITHUB_ACTIONS`, AzureDevOps via `$env:TF_BUILD`, Local fallback).
 - **GENERATED_AGAINST_MODULE_VERSION** pin moves from ''0.8.1'' to ''0.8.2'' across all 20 bundled `Step.{0..9}.yml` templates.
 

AzLocal.UpdateManagement/CHANGELOG.md

@@ -26,6 +26,13 @@ Operator-experience release for `Test-AzLocalApplyUpdatesScheduleCoverage -View
 - **New `### How to fix - edit \`$schedulePath\`` subsection** names the schedule file directly and explains that `allowedUpdateVersions:` overrides are only needed when an operator wants to PIN a ring to a specific update (e.g. keep Prod on the latest feature drop only - YY04 / YY10 - and skip cumulative updates between feature drops). Followed by a single-row YAML example.
 - **6 new Pester assertions** lock in the new shape: both Step.3 scaffolds emit the trimmed one-liner and the `How to fix - edit $schedulePath` heading, AND do NOT emit `Tip - per-ring overrides` / `Showing first 3 of` (the verbose v0.8.1 markers).
 
+### `Azure Stack HCI Update Operator` custom-role Description rewritten to drop module-internal jargon
+
+- The custom-role Description shipped into the Azure RBAC plane (visible in the Azure portal **Custom roles** blade, in `az role definition list` / `Get-AzRoleDefinition` output, and in any RBAC audit/governance tooling) previously read *"...read the fleet-connectivity scopes (Arc machines, edge-device NICs, Azure Resource Bridges) required by Step.4"*. `Step.4` is a module-private concept and meaningless to anyone outside `AzLocal.UpdateManagement`.
+- **New Description**: *"Can read and apply Azure Local cluster updates, manage UpdateRing tags, and read the fleet-connectivity inventory (Arc-enabled machines, edge-device NICs, Azure Resource Bridges) needed to assess pre-update connectivity."*
+- **Same RBAC grant** - `Actions[]`, `NotActions[]`, `DataActions[]`, `AssignableScopes[]` are byte-identical. Operators with the role already deployed need no action; the next `az role definition update --role-definition ./azlocal-update-management-custom-role.json` will refresh the Description.
+- **Updated in lockstep across all 6 sites** that ship/document the role: the bundled `Automation-Pipeline-Examples/azlocal-update-management-custom-role.json` file (consumed by `az role definition create`), the two inline JSON blocks in `Automation-Pipeline-Examples/README.md` section 4.1, and the three inline JSON blocks in `docs/rbac.md` (first JSON block + Option 2 here-string + management-group-scope variant).
+
 ### Module foundations for the upcoming executable-YAML refactor
 
 - Five new internal (Private) helpers added: `Get-AzLocalPipelineHost`, `Set-AzLocalPipelineOutput`, `Add-AzLocalPipelineStepSummary`, `Write-AzLocalPipelineNotice`, `Write-AzLocalPipelineWarning`.

AzLocal.UpdateManagement/README.md

@@ -103,6 +103,10 @@ Pre-v0.8.2 the row showed a generic *"Tag clusters with `UpdateStartWindow=<days
 
 The `Allow-list coverage (schema v2)` subsection no longer emits the verbose `> Tip - per-ring overrides` paragraph + 3-row example block that v0.8.1 produced. Inheriting the top-level allow-list IS the expected steady state for most fleets (install Latest as soon as Ready); the verbose tip was misleading operators into thinking they had to add overrides. The new shape is a one-line steady-state confirmation plus a dedicated `### How to fix - edit $schedulePath` subsection (naming the schedule file) and a single-row YAML example showing how to PIN a ring to a specific update (e.g. keep Prod on the latest feature drop only - YY04 / YY10 - and skip cumulative updates between feature drops).
 
+### `Azure Stack HCI Update Operator` custom-role Description rewritten to drop module-internal jargon
+
+The custom-role Description shipped into the Azure RBAC plane (visible in the Azure portal **Custom roles** blade, in `az role definition list` / `Get-AzRoleDefinition` output, and in any RBAC audit/governance tooling) previously read *"...read the fleet-connectivity scopes (Arc machines, edge-device NICs, Azure Resource Bridges) required by Step.4"*. `Step.4` is a module-private concept and meaningless to anyone outside `AzLocal.UpdateManagement`. The new Description reads *"Can read and apply Azure Local cluster updates, manage UpdateRing tags, and read the fleet-connectivity inventory (Arc-enabled machines, edge-device NICs, Azure Resource Bridges) needed to assess pre-update connectivity."* Same RBAC grant (`Actions[]`, `NotActions[]`, `DataActions[]`, `AssignableScopes[]` byte-identical), so operators with the role already deployed need no action; the next `az role definition update --role-definition ./azlocal-update-management-custom-role.json` will refresh the Description. Updated in lockstep across all 6 sites that ship/document the role.
+
 ### Module foundations for the upcoming executable-YAML refactor
 
 Five new internal (Private) helpers - `Get-AzLocalPipelineHost`, `Set-AzLocalPipelineOutput`, `Add-AzLocalPipelineStepSummary`, `Write-AzLocalPipelineNotice`, `Write-AzLocalPipelineWarning` - abstract over the host-specific quirks of GitHub Actions vs Azure DevOps output channels (`$env:GITHUB_OUTPUT` vs `##vso[task.setvariable]`, `$env:GITHUB_STEP_SUMMARY` vs `##vso[task.uploadsummary]`, `::notice/::warning` vs `##vso[task.logissue]`). These are not exported and have no user-visible effect in v0.8.2 - they are foundations for the upcoming per-Step `Export-*` / `Invoke-*` cmdlets that will move inline `run: |` PowerShell out of the `Step.{0..9}.yml` files and into the module proper. 23 new Pester assertions cover the three host modes (GitHub auto-detect via `$env:GITHUB_ACTIONS='true'`, Azure DevOps via `$env:TF_BUILD='True'`, Local fallback) and the byte-identical contracts of each emitted logging-command syntax.

AzLocal.UpdateManagement/docs/release-history.md

@@ -23,6 +23,8 @@ v0.8.2 is an operator-experience release for `Test-AzLocalApplyUpdatesScheduleCo
 
 **Step.3 Allow-list section trimmed in both GH and ADO scaffolds.** The `Allow-list coverage (schema v2)` subsection no longer emits the verbose `> Tip - per-ring overrides` paragraph + 3-row example block that v0.8.1 produced. Inheriting the top-level allow-list IS the expected steady state for most fleets (install Latest as soon as Ready); the verbose tip was misleading operators into thinking they had to add overrides. The new shape is a one-line steady-state confirmation plus a dedicated `### How to fix - edit $schedulePath` subsection (naming the schedule file) and a single-row YAML example showing how to PIN a ring to a specific update (e.g. keep Prod on the latest feature drop only - YY04 / YY10 - and skip cumulative updates between feature drops).
 
+**`Azure Stack HCI Update Operator` custom-role Description rewritten to drop module-internal jargon.** The custom-role Description shipped into the Azure RBAC plane (visible in the Azure portal **Custom roles** blade, in `az role definition list` / `Get-AzRoleDefinition` output, and in any RBAC audit/governance tooling) previously read *"...read the fleet-connectivity scopes (Arc machines, edge-device NICs, Azure Resource Bridges) required by Step.4"* - `Step.4` is a module-private concept and meaningless to anyone outside `AzLocal.UpdateManagement`. The new Description reads *"Can read and apply Azure Local cluster updates, manage UpdateRing tags, and read the fleet-connectivity inventory (Arc-enabled machines, edge-device NICs, Azure Resource Bridges) needed to assess pre-update connectivity."* Same RBAC grant - `Actions[]`, `NotActions[]`, `DataActions[]`, `AssignableScopes[]` are byte-identical, so operators with the role already deployed need no action; the next `az role definition update` will refresh the Description. Updated in lockstep across all 6 sites that ship/document the role: the bundled JSON file plus the inline JSON blocks in `Automation-Pipeline-Examples/README.md` and `docs/rbac.md`.
+
 **Migration:** `Install-Module AzLocal.UpdateManagement -Force` (or `Update-Module`). Re-run `Test-AzLocalApplyUpdatesScheduleCoverage -View Recommend` once to pick up the new self-documenting snippet (the cron *values* are unchanged from v0.8.1; only the surrounding comment and prose changed).
 
 **All 20 bundled `Step.{0..9}.yml` templates** bump `GENERATED_AGAINST_MODULE_VERSION` from `'0.8.1'` to `'0.8.2'`.