[Feature] Generate Cmdlet Reference Docs from Code (auto-updated)

[blindzero]

Problem Statement

IdLE exposes public cmdlets that form a stable contract and must be documented via comment-based help.
However, we currently don’t provide a complete, always-up-to-date reference section that lists all exported commands and their parameters/examples.

Proposed Solution

Provide a statically generated reference section under docs/reference/ that is generated from the module’s help metadata (comment-based help) and stays in sync automatically with code changes.

This supports the project documentation principle “keep docs short and linkable” by moving detailed cmdlet/parameter documentation into a generated reference area.

Proposed Approach (default)

Add a tooling script (e.g. tools/Generate-ReferenceDocs.ps1) that:

• Imports the relevant IdLE modules (IdLE, IdLE.Core, optional step modules)
• Enumerates exported commands
• Generates/updates markdown reference files under docs/reference/
• Produces deterministic output (stable ordering, consistent formatting)

Add a CI job (GitHub Actions) that runs on PRs and:

• Executes the generator
• Fails if generated docs are out-of-date (diff detected)
• Optionally uploads generated docs as an artifact for review
• Optional enhancement (if we want “hands-off updates”): a workflow that auto-commits regenerated docs to the PR branch (bot commit) or opens a bot PR. (We can decide later.)

Acceptance Criteria

• docs/reference/ exists and contains generated markdown pages for all exported public functions/cmdlets.
• The generator can be run locally (single command) and is deterministic.
• CI verifies docs are up-to-date (fails if not regenerated).
• docs/00-index.md links to the reference section.
• No architecture rules are violated (core remains headless/host-agnostic).

Tasks

• Decide generator strategy (e.g., PlatyPS-based vs custom markdown generator)
• Implement tools/Generate-ReferenceDocs.ps1
• Create/adjust docs/reference/ output structure (index + per-cmdlet pages)
• Add GitHub Action workflow: docs-reference.yml
• Update docs/00-index.md with a “Reference” link entry
• Add a short note in README pointing to the reference docs (optional; keep README high-level)
• Add/adjust tests or CI checks as needed (Definition of Done applies)

Notes / Constraints

• Public APIs must include comment-based help (.SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE, .OUTPUTS).
• Keep docs short and linkable; the reference docs are the “deep dive.”