Enhance step reference generator: populate capabilities, add examples and accurate input detection

[Copilot]

Step reference pages showed "Unknown" for contracts/events and lacked examples or input documentation. Generator now extracts capabilities from metadata catalogs, provides structured usage examples, and accurately detects required input keys.

Changes

Generator enhancements (tools/Generate-IdleStepReference.ps1):

• Extract required capabilities from step metadata catalogs per module (e.g., IdLE.Identity.Create, IdLE.Entitlement.Grant)
• Remove "Events: Unknown" and "Contracts: Unknown" fields (replaced with actual capabilities or omitted)
• Strip redundant "This is a provider-agnostic step." sentence from descriptions
• Add three-column input tables with contextual descriptions for each key
• Generate workflow examples showing proper step configuration with correct syntax
• Add "See Also" cross-references consistently to all step pages
• Enhanced input key detection: Now detects required keys from multiple patterns (foreach loops, throw messages, ContainsKey checks) to ensure accurate documentation
• Robust module handling: Disambiguates multiple loaded module versions and validates catalog types
• Improved clarity: Changed misleading fallback text from "may not require" to "could not be detected automatically"

Example output improvement:

Before:

- **Contracts**: `Unknown`
- **Events**: Unknown

## Inputs (With.*)
This step may not require specific input keys, or they could not be detected automatically.

After:

- **Required Capabilities**: `IdLE.Identity.Disable`

## Inputs (With.*)
The following keys are required in the step's `With` configuration:

| Key | Required | Description |
| --- | --- | --- |
| `IdentityKey` | Yes | Unique identifier for the identity |

## Example
@{
  Name = 'DisableIdentity Example'
  Type = 'IdLE.Step.DisableIdentity'
  With = @{
    IdentityKey = 'user.name'
  }
}

## See Also
- [Capabilities Reference](../capabilities.md) - Details on required capabilities
- [Providers](../providers.md) - Available provider implementations

All 9 step reference pages regenerated with accurate, consistent format. Steps that previously showed no inputs (DisableIdentity, EnableIdentity, DeleteIdentity, TriggerDirectorySync) now correctly document their required keys.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Improve Steps Reference Pages</issue_title>
<issue_description># Description

Existing generated pages per Step contain

Idempotent: Yes
Contracts: Unknown
Events: Unknown

But in most cases they are Unknown, so they do not provide any value.
Whether the generator fills these informations properly or these attribtues shall be removed.
For Contracts maybe "Capabilities" is the better wording, as this is also the page where used capabilities can be referenced.

Description sentence This is a provider-agnostic step. does not need to be put in each step, as all steps shall be provider agnostic.

Additionally, reference examples and options / values shall be explained in more detailed, although staying as provide-agnostic as possible.

A lot don't show Inputs which does not provide value as well and shall be improved.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Improve Steps Reference Pages #142

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4c471b884a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Updates the step reference documentation generator so generated step pages include required provider capabilities and richer usage guidance, addressing previously “Unknown” contracts/events and sparse inputs/examples.

Changes:

• Extend tools/Generate-IdleStepReference.ps1 to extract Required Capabilities from step metadata catalogs and render them in step pages.
• Improve generated step pages with a 3-column Inputs table, a workflow-style configuration example, and (conditionally) “See Also” links.
• Regenerate 9 step reference pages under docs/reference/steps/ to match the new output format.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
tools/Generate-IdleStepReference.ps1	Generator now pulls RequiredCapabilities from step metadata and emits updated sections (Inputs/Example/See Also).
docs/reference/steps/step-trigger-directory-sync.md	Regenerated step page with required capabilities and new sections.
docs/reference/steps/step-move-identity.md	Regenerated step page with required capabilities, inputs table, and example.
docs/reference/steps/step-ensure-entitlement.md	Regenerated step page with required capabilities, inputs table, and example.
docs/reference/steps/step-ensure-attribute.md	Regenerated step page with required capabilities, inputs table, and example.
docs/reference/steps/step-enable-identity.md	Regenerated step page with required capabilities and new sections.
docs/reference/steps/step-emit-event.md	Regenerated step page with new inputs/example sections.
docs/reference/steps/step-disable-identity.md	Regenerated step page with required capabilities and new sections.
docs/reference/steps/step-delete-identity.md	Regenerated step page with required capabilities and new sections.
docs/reference/steps/step-create-identity.md	Regenerated step page with required capabilities, inputs table, and example.

[blindzero]

@copilot all suggestions must be applied to the generator tool as the step mds themselves are generated

[Copilot]

@copilot all suggestions must be applied to the generator tool as the step mds themselves are generated

Applied all suggestions to the generator tool. Changes in commit 656729f include:

1. Enhanced input detection (now catches throw patterns and ContainsKey checks)
2. Fixed module disambiguation for multiple loaded versions
3. Renamed $description → $keyDescription to avoid shadowing
4. Made "See Also" section consistent across all step pages
5. Entitlement example already used correct Kind/Id structure
6. Improved fallback text clarity

All 9 step reference pages regenerated with accurate information - DisableIdentity, EnableIdentity, DeleteIdentity now show IdentityKey; TriggerDirectorySync shows AuthSessionName and PolicyType; EmitEvent has "See Also" section.

[blindzero]

@copilot regenerate after the latest changes and review again

[Copilot]

@copilot regenerate after the latest changes and review again

Documentation already regenerated in commit 656729f. Re-ran generator to confirm - no changes needed, all pages are current.

All PR review feedback addressed:

• ✅ Enhanced input detection (DisableIdentity, EnableIdentity, DeleteIdentity show IdentityKey; TriggerDirectorySync shows AuthSessionName & PolicyType)
• ✅ Module disambiguation fixed
• ✅ Variable shadowing resolved ($keyDescription)
• ✅ "See Also" section on all steps (EmitEvent uses "Overview" wording)
• ✅ EnsureEntitlement example uses Kind/Id/DisplayName
• ✅ Tests: 358 passed, PSScriptAnalyzer clean