blindzero · Nov 1, 2026 · Nov 1, 2026 · Nov 1, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/tests/Packaging/Generate-IdleStepReference.Tests.ps1 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
@@ -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')) {