From 170e5ecf77bbb253ac81b81b75f6f0080fe62173 Mon Sep 17 00:00:00 2001
From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com>
Date: Sun, 1 Nov 2026 13:16:01 +0100
Subject: [PATCH 1/2] tools: look up step capabilities by the full step type in
 the reference generator (#347)

Get-IdleStepRequiredCapabilities prefixed the already-qualified step type with
'IdLE.Step.', so the catalog lookup never matched and no step page listed its
required capabilities. Add a test that runs the generator and checks every
step with declared RequiredCapabilities against its generated page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../Generate-IdleStepReference.Tests.ps1      | 66 +++++++++++++++++++
 tools/Generate-IdleStepReference.ps1          |  6 +-
 2 files changed, 69 insertions(+), 3 deletions(-)
 create mode 100644 tests/Packaging/Generate-IdleStepReference.Tests.ps1

diff --git a/tests/Packaging/Generate-IdleStepReference.Tests.ps1 b/tests/Packaging/Generate-IdleStepReference.Tests.ps1
new file mode 100644
index 00000000..4baaab05
--- /dev/null
+++ b/tests/Packaging/Generate-IdleStepReference.Tests.ps1
@@ -0,0 +1,66 @@
+# Requires -Version 7.0
+Set-StrictMode -Version Latest
+
+BeforeAll {
+    . (Join-Path (Split-Path -Path $PSScriptRoot -Parent) '_testHelpers.ps1')
+
+    $script:RepoRoot = Get-RepoRootPath
+    $script:GeneratorPath = Join-Path $script:RepoRoot 'tools/Generate-IdleStepReference.ps1'
+
+    if (-not (Test-Path -LiteralPath $script:GeneratorPath)) {
+        throw "Step reference generator not found: $script:GeneratorPath"
+    }
+
+    $script:OutputPath = Join-Path $TestDrive 'steps.md'
+    $script:DetailDirectory = Join-Path $TestDrive 'steps'
+
+    # The generator removes and re-imports all IdLE modules, so run it in a separate process to keep the
+    # module state of this test session intact.
+    $output = & pwsh -NoProfile -NonInteractive -File $script:GeneratorPath -OutputPath $script:OutputPath -DetailOutputDirectory $script:DetailDirectory 2>&1
+    if ($LASTEXITCODE -ne 0) {
+        throw "Step reference generator failed (exit code $LASTEXITCODE): $($output -join [Environment]::NewLine)"
+    }
+
+    # Map step type -> generated page content; the first line of each page is '# <StepType>'.
+    $script:PagesByStepType = @{}
+    foreach ($file in Get-ChildItem -Path $script:DetailDirectory -Filter '*.md' -File) {
+        $text = Get-Content -LiteralPath $file.FullName -Raw
+        $stepType = (($text -split "`r?`n", 2)[0] -replace '^#\s+', '').Trim()
+        $script:PagesByStepType[$stepType] = $text
+    }
+}
+
+Describe 'Generate-IdleStepReference.ps1' {
+
+    Context 'Required capabilities' {
+
+        BeforeDiscovery {
+            $repoRoot = (Resolve-Path -Path (Join-Path $PSScriptRoot '../..')).Path
+            $catalogFiles = Get-ChildItem -Path (Join-Path $repoRoot 'src') -Directory -Filter 'IdLE.Steps.*' |
+                ForEach-Object { Join-Path $_.FullName 'StepMetadataCatalog.psd1' } |
+                Where-Object { Test-Path -LiteralPath $_ }
+
+            $script:StepCases = foreach ($catalogFile in $catalogFiles) {
+                $catalog = Import-PowerShellDataFile -Path $catalogFile
+                foreach ($stepType in $catalog.Keys) {
+                    $metadata = $catalog[$stepType]
+                    if ($metadata.Contains('RequiredCapabilities') -and @($metadata['RequiredCapabilities']).Count -gt 0) {
+                        @{ StepType = $stepType; Capabilities = @($metadata['RequiredCapabilities']) }
+                    }
+                }
+            }
+        }
+
+        It 'catalogs declare at least one step with required capabilities' -ForEach @(@{ CaseCount = @($script:StepCases).Count }) {
+            # Guards against the test silently passing because no cases were discovered.
+            $CaseCount | Should -BeGreaterThan 0
+        }
+
+        It 'renders the required capabilities of <StepType>' -ForEach $script:StepCases {
+            $script:PagesByStepType.ContainsKey($StepType) | Should -BeTrue -Because "a page for '$StepType' must be generated"
+
+            $expected = ($Capabilities | ForEach-Object { "``$_``" }) -join ', '
+            $script:PagesByStepType[$StepType] | Should -Match ([regex]::Escape("- **Required Capabilities**: $expected"))
+        }
+    }
+}
diff --git a/tools/Generate-IdleStepReference.ps1 b/tools/Generate-IdleStepReference.ps1
index d3f7d5a3..8fa32738 100644
--- a/tools/Generate-IdleStepReference.ps1
+++ b/tools/Generate-IdleStepReference.ps1
@@ -440,9 +440,9 @@ function Get-IdleStepRequiredCapabilities {
             # Call Get-IdleStepMetadataCatalog in the context of the specific module
             $catalog = & $module { Get-IdleStepMetadataCatalog -ErrorAction SilentlyContinue }
             if ($catalog -is [System.Collections.IDictionary]) {
-                $fullStepTypeName = "IdLE.Step.$StepType"
-                if ($catalog.Contains($fullStepTypeName)) {
-                    $metadata = $catalog[$fullStepTypeName]
+                # StepType is already the full catalog key (e.g. 'IdLE.Step.DisableIdentity').
+                if ($catalog.Contains($StepType)) {
+                    $metadata = $catalog[$StepType]
                     if ($metadata) {
                         $requiredCapabilities = $null
                         if ($metadata -is [System.Collections.IDictionary] -and $metadata.Contains('RequiredCapabilities')) {

From 3069d39e6ffb6d0a563064fd24192ad22e326ea4 Mon Sep 17 00:00:00 2001
From: Matthias Fleschuetz <13959569+blindzero@users.noreply.github.com>
Date: Sun, 1 Nov 2026 13:16:02 +0100
Subject: [PATCH 2/2] docs: regenerate step reference with required
 capabilities (#347)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/reference/steps/step-create-identity.md                | 3 ++-
 docs/reference/steps/step-delete-identity.md                | 3 ++-
 docs/reference/steps/step-disable-identity.md               | 3 ++-
 docs/reference/steps/step-enable-identity.md                | 3 ++-
 docs/reference/steps/step-ensure-attributes.md              | 3 ++-
 docs/reference/steps/step-ensure-entitlement.md             | 3 ++-
 docs/reference/steps/step-mailbox-ensure-out-of-office.md   | 3 ++-
 docs/reference/steps/step-mailbox-ensure-permissions.md     | 3 ++-
 docs/reference/steps/step-mailbox-ensure-type.md            | 3 ++-
 docs/reference/steps/step-mailbox-get-info.md               | 3 ++-
 docs/reference/steps/step-move-identity.md                  | 3 ++-
 docs/reference/steps/step-prune-entitlements-ensure-keep.md | 3 ++-
 docs/reference/steps/step-prune-entitlements.md             | 3 ++-
 docs/reference/steps/step-revoke-identity-sessions.md       | 3 ++-
 docs/reference/steps/step-trigger-directory-sync.md         | 3 ++-
 15 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/docs/reference/steps/step-create-identity.md b/docs/reference/steps/step-create-identity.md
index f0492191..353360d7 100644
--- a/docs/reference/steps/step-create-identity.md
+++ b/docs/reference/steps/step-create-identity.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Common`
 - **Implementation**: `Invoke-IdleStepCreateIdentity`
 - **Idempotent**: `Yes`
+- **Required Capabilities**: `IdLE.Identity.Create`
 
 ## Synopsis
 
@@ -53,5 +54,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-delete-identity.md b/docs/reference/steps/step-delete-identity.md
index bb291abd..114c08f3 100644
--- a/docs/reference/steps/step-delete-identity.md
+++ b/docs/reference/steps/step-delete-identity.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Common`
 - **Implementation**: `Invoke-IdleStepDeleteIdentity`
 - **Idempotent**: `Yes`
+- **Required Capabilities**: `IdLE.Identity.Delete`
 
 ## Synopsis
 
@@ -55,5 +56,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-disable-identity.md b/docs/reference/steps/step-disable-identity.md
index 530db51a..28aa9e2a 100644
--- a/docs/reference/steps/step-disable-identity.md
+++ b/docs/reference/steps/step-disable-identity.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Common`
 - **Implementation**: `Invoke-IdleStepDisableIdentity`
 - **Idempotent**: `Yes`
+- **Required Capabilities**: `IdLE.Identity.Disable`
 
 ## Synopsis
 
@@ -51,5 +52,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-enable-identity.md b/docs/reference/steps/step-enable-identity.md
index a741bad2..f8c6bfed 100644
--- a/docs/reference/steps/step-enable-identity.md
+++ b/docs/reference/steps/step-enable-identity.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Common`
 - **Implementation**: `Invoke-IdleStepEnableIdentity`
 - **Idempotent**: `Yes`
+- **Required Capabilities**: `IdLE.Identity.Enable`
 
 ## Synopsis
 
@@ -51,5 +52,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-ensure-attributes.md b/docs/reference/steps/step-ensure-attributes.md
index d68e2f47..658a7841 100644
--- a/docs/reference/steps/step-ensure-attributes.md
+++ b/docs/reference/steps/step-ensure-attributes.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Common`
 - **Implementation**: `Invoke-IdleStepEnsureAttributes`
 - **Idempotent**: `Yes`
+- **Required Capabilities**: `IdLE.Identity.Attribute.Ensure`
 
 ## Synopsis
 
@@ -56,5 +57,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-ensure-entitlement.md b/docs/reference/steps/step-ensure-entitlement.md
index b363edf0..763f9bbb 100644
--- a/docs/reference/steps/step-ensure-entitlement.md
+++ b/docs/reference/steps/step-ensure-entitlement.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Common`
 - **Implementation**: `Invoke-IdleStepEnsureEntitlement`
 - **Idempotent**: `Yes`
+- **Required Capabilities**: `IdLE.Entitlement.List`, `IdLE.Entitlement.Grant`, `IdLE.Entitlement.Revoke`
 
 ## Synopsis
 
@@ -60,5 +61,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-mailbox-ensure-out-of-office.md b/docs/reference/steps/step-mailbox-ensure-out-of-office.md
index 1553a8e8..f73c8f23 100644
--- a/docs/reference/steps/step-mailbox-ensure-out-of-office.md
+++ b/docs/reference/steps/step-mailbox-ensure-out-of-office.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Mailbox`
 - **Implementation**: `Invoke-IdleStepMailboxOutOfOfficeEnsure`
 - **Idempotent**: `Yes`
+- **Required Capabilities**: `IdLE.Mailbox.Info.Read`, `IdLE.Mailbox.OutOfOffice.Ensure`
 
 ## Synopsis
 
@@ -200,5 +201,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-mailbox-ensure-permissions.md b/docs/reference/steps/step-mailbox-ensure-permissions.md
index 84e325b3..e509456a 100644
--- a/docs/reference/steps/step-mailbox-ensure-permissions.md
+++ b/docs/reference/steps/step-mailbox-ensure-permissions.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Mailbox`
 - **Implementation**: `Invoke-IdleStepMailboxPermissionsEnsure`
 - **Idempotent**: `Yes`
+- **Required Capabilities**: `IdLE.Mailbox.Info.Read`, `IdLE.Mailbox.Permissions.Ensure`
 
 ## Synopsis
 
@@ -114,5 +115,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-mailbox-ensure-type.md b/docs/reference/steps/step-mailbox-ensure-type.md
index d6bf0cfb..409393d9 100644
--- a/docs/reference/steps/step-mailbox-ensure-type.md
+++ b/docs/reference/steps/step-mailbox-ensure-type.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Mailbox`
 - **Implementation**: `Invoke-IdleStepMailboxTypeEnsure`
 - **Idempotent**: `Yes`
+- **Required Capabilities**: `IdLE.Mailbox.Info.Read`, `IdLE.Mailbox.Type.Ensure`
 
 ## Synopsis
 
@@ -65,5 +66,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-mailbox-get-info.md b/docs/reference/steps/step-mailbox-get-info.md
index 9eb1caf9..73f1931b 100644
--- a/docs/reference/steps/step-mailbox-get-info.md
+++ b/docs/reference/steps/step-mailbox-get-info.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Mailbox`
 - **Implementation**: `Invoke-IdleStepMailboxGetInfo`
 - **Idempotent**: `Unknown`
+- **Required Capabilities**: `IdLE.Mailbox.Info.Read`
 
 ## Synopsis
 
@@ -52,5 +53,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-move-identity.md b/docs/reference/steps/step-move-identity.md
index 344e002f..5e4264ad 100644
--- a/docs/reference/steps/step-move-identity.md
+++ b/docs/reference/steps/step-move-identity.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Common`
 - **Implementation**: `Invoke-IdleStepMoveIdentity`
 - **Idempotent**: `Yes`
+- **Required Capabilities**: `IdLE.Identity.Move`
 
 ## Synopsis
 
@@ -53,5 +54,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-prune-entitlements-ensure-keep.md b/docs/reference/steps/step-prune-entitlements-ensure-keep.md
index a754e936..5ae03e05 100644
--- a/docs/reference/steps/step-prune-entitlements-ensure-keep.md
+++ b/docs/reference/steps/step-prune-entitlements-ensure-keep.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Common`
 - **Implementation**: `Invoke-IdleStepPruneEntitlementsEnsureKeep`
 - **Idempotent**: `Unknown`
+- **Required Capabilities**: `IdLE.Entitlement.Prune`, `IdLE.Entitlement.List`, `IdLE.Entitlement.Revoke`, `IdLE.Entitlement.Grant`
 
 ## Synopsis
 
@@ -126,5 +127,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-prune-entitlements.md b/docs/reference/steps/step-prune-entitlements.md
index 20d450ff..3176e8d5 100644
--- a/docs/reference/steps/step-prune-entitlements.md
+++ b/docs/reference/steps/step-prune-entitlements.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Common`
 - **Implementation**: `Invoke-IdleStepPruneEntitlements`
 - **Idempotent**: `Unknown`
+- **Required Capabilities**: `IdLE.Entitlement.Prune`, `IdLE.Entitlement.List`, `IdLE.Entitlement.Revoke`
 
 ## Synopsis
 
@@ -118,5 +119,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-revoke-identity-sessions.md b/docs/reference/steps/step-revoke-identity-sessions.md
index d71b0fe8..2167be32 100644
--- a/docs/reference/steps/step-revoke-identity-sessions.md
+++ b/docs/reference/steps/step-revoke-identity-sessions.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.Common`
 - **Implementation**: `Invoke-IdleStepRevokeIdentitySessions`
 - **Idempotent**: `Unknown`
+- **Required Capabilities**: `IdLE.Identity.RevokeSessions`
 
 ## Synopsis
 
@@ -59,5 +60,5 @@ Validated at plan time against the step's ``WithSchema`` (see [Step metadata con
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations
diff --git a/docs/reference/steps/step-trigger-directory-sync.md b/docs/reference/steps/step-trigger-directory-sync.md
index 9a0d7838..769f55b8 100644
--- a/docs/reference/steps/step-trigger-directory-sync.md
+++ b/docs/reference/steps/step-trigger-directory-sync.md
@@ -9,6 +9,7 @@
 - **Module**: `IdLE.Steps.DirectorySync`
 - **Implementation**: `Invoke-IdleStepTriggerDirectorySync`
 - **Idempotent**: `Unknown`
+- **Required Capabilities**: `IdLE.DirectorySync.Trigger`, `IdLE.DirectorySync.Status`
 
 ## Synopsis
 
@@ -62,5 +63,5 @@ $step = @{
 
 ## See Also
 
-- [Capabilities Reference](../capabilities.md) - Overview of IdLE capabilities
+- [Capabilities Reference](../capabilities.md) - Details on required capabilities
 - [Providers](../providers.md) - Available provider implementations