Use PowerForge native cmdlet documentation

[PrzemyslawKlys]

PowerForge now owns the binary cmdlet documentation pipeline from compiler XML through Markdown and external MAML. This removes the redundant MatejKafka.XmlDoc2CmdletDoc package and its package-specific MSBuild copy target.

The module build now enables PowerForge documentation, publishes generated external help with the module, and exposes explicit documentation/build gates. Generated command reference pages and MAML are committed, stale project links are corrected, meaningful optional defaults are declared with PSDefaultValue, and CI fails when regeneration changes tracked files or introduces untracked documentation artifacts.

Public PSPublishModule 3.0.83 is the current minimum because it contains the corrected wildcard metadata extractor. Final default-value regeneration remains intentionally gated on PSPublishModule #652 and the public package containing that fix; this PR's minimum version and generated help will be updated together before merge.

[Copilot]

Pull request overview

This PR migrates the module’s cmdlet documentation pipeline to PowerForge (compiler XML → Markdown + external help), removing the legacy XmlDoc2CmdletDoc dependency and adding CI gates to ensure generated documentation is committed and kept up to date.

Changes:

• Removed MatejKafka.XmlDoc2CmdletDoc and its MSBuild publish-copy target from the PowerShell binary module project.
• Enabled PowerForge documentation generation during module build, committed generated command reference pages, and added a CI check that fails on doc drift/untracked outputs.
• Updated cmdlet XML doc <seealso> links to the correct GitHub repository URL.

Reviewed changes

Copilot reviewed 48 out of 49 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
SectigoCertificateManager.PowerShell/WaitSectigoOrderCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/UpdateSectigoCertificateCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/StopSectigoOrderCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/RenewSectigoCertificateCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/RemoveSectigoCertificateCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/NewSectigoOrganizationCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/NewSectigoOrderCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/GetSectigoProfilesCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/GetSectigoProfileCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/GetSectigoOrganizationsCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/GetSectigoOrdersPageCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/GetSectigoOrdersCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/GetSectigoOrderHistoryCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/GetSectigoCertificateTypesCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/GetSectigoCertificateStatusCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/GetSectigoCertificateRevocationCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/GetSectigoCertificateCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/ExportSectigoCertificateCommand.cs	Updates cmdlet doc link to correct repo URL.
SectigoCertificateManager.PowerShell/SectigoCertificateManager.PowerShell.csproj	Removes XmlDoc2CmdletDoc package and legacy help publish copy target; relies on compiler XML for PowerForge.
Module/SectigoCertificateManager.psd1	Manifest formatting refresh (no functional export changes implied by diff).
Module/Build/Build-Module.ps1	Enables PowerForge doc generation + adds explicit gate modes and doc sync behavior.
AGENTS.MD	Updates contributor guidance to PowerForge-native cmdlet documentation rules.
.github/workflows/powershell.yml	Adds CI step to verify generated docs are up to date (fails on drift/untracked files).
Module/Docs/Connect-Sectigo.md	Adds generated cmdlet reference page.
Module/Docs/Disconnect-Sectigo.md	Adds generated cmdlet reference page.
Module/Docs/Export-SectigoCertificate.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoCertificate.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoCertificateKeystoreLink.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoCertificateRevocation.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoCertificateStatus.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoCertificateTypes.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoEnrollCertificates.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoInventory.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoOrderHistory.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoOrders.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoOrdersPage.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoOrganizations.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoProfile.md	Adds generated cmdlet reference page.
Module/Docs/Get-SectigoProfiles.md	Adds generated cmdlet reference page.
Module/Docs/Invoke-SectigoCertificateRenewal.md	Adds generated cmdlet reference page.
Module/Docs/New-SectigoCsr.md	Adds generated cmdlet reference page.
Module/Docs/New-SectigoOrder.md	Adds generated cmdlet reference page.
Module/Docs/New-SectigoOrganization.md	Adds generated cmdlet reference page.
Module/Docs/Remove-SectigoCertificate.md	Adds generated cmdlet reference page.
Module/Docs/Stop-SectigoOrder.md	Adds generated cmdlet reference page.
Module/Docs/Update-SectigoCertificate.md	Adds generated cmdlet reference page.
Module/Docs/Wait-SectigoOrder.md	Adds generated cmdlet reference page.
Module/Docs/Readme.md	Adds generated docs index page.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 73dcbc8009

ℹ️ 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".

[chatgpt-codex-connector]

Emit actual defaults in generated help

When users consult the newly committed Markdown or external Get-Help content, optional parameters are reported as having no default even though the cmdlets initialize them explicitly. For example, ConnectSectigoCommand.cs:51 defaults ApiVersion to V25_6, while this page and the corresponding MAML say None; the same occurs for BaseUrl, Instance, export format, polling interval, and numerous other parameters. Ensure the generation pipeline captures these initializer values or supplies equivalent documentation metadata so omitting a parameter is documented accurately.

Useful? React with 👍 / 👎.

[PrzemyslawKlys]

The reusable fix is now in EvotecIT/PSPublishModule#652: PowerForge reads explicit PSDefaultValue metadata and gives it precedence over stale generated help. Sectigo declares its meaningful optional defaults in 3a8caf0 and the exact extractor probe covers strings, enums, integers, and TimeSpan. Keeping this thread open until the new public PSPublishModule release regenerates and commits the final Markdown/MAML values.

[Copilot]

Pull request overview

Copilot reviewed 48 out of 49 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (6)

Module/Docs/Export-SectigoCertificate.md:25

• The example omits the mandatory -CertificateId parameter. As written, Export-SectigoCertificate -Path ... will fail because CertificateId is [Parameter(Mandatory = true, Position = 0)] in SectigoCertificateManager.PowerShell/ExportSectigoCertificateCommand.cs. Consider adding an XML <example> to the cmdlet docs (and regenerating) so the generated markdown includes a runnable invocation (e.g., Export-SectigoCertificate -CertificateId 123 -Path ...).

### EXAMPLE 1
```powershell
Export-SectigoCertificate -Path 'C:\Path'

**Module/Docs/Get-SectigoCertificateStatus.md:25**
* The example omits the mandatory `-CertificateId` parameter. In `SectigoCertificateManager.PowerShell/GetSectigoCertificateStatusCommand.cs`, `CertificateId` is `[Parameter(Mandatory = true, Position = 0)]`, so this example will fail when copied/pasted. Add an XML `<example>` to the cmdlet docs and regenerate so the generated markdown includes a valid invocation (e.g., `Get-SectigoCertificateStatus -CertificateId 123`).

EXAMPLE 1

Get-SectigoCertificateStatus -ApiVersion 'Value'

**Module/Docs/Get-SectigoCertificateRevocation.md:25**
* The example omits the mandatory `-CertificateId` parameter. In `SectigoCertificateManager.PowerShell/GetSectigoCertificateRevocationCommand.cs`, `CertificateId` is `[Parameter(Mandatory = true, Position = 0)]`, so this example will fail when copied/pasted. Add an XML `<example>` to the cmdlet docs and regenerate so the generated markdown includes a valid invocation (e.g., `Get-SectigoCertificateRevocation -CertificateId 123`).

EXAMPLE 1

Get-SectigoCertificateRevocation -ApiVersion 'Value'

**Module/Docs/Get-SectigoOrganizations.md:18**
* This cmdlet currently throws when an Admin (OAuth2) connection is active (`GetSectigoOrganizationsCommand` checks `SectigoAdminApiConfig` and raises `PSInvalidOperationException`). The generated docs don’t mention this limitation, so users will likely be confused if they follow the docs while connected via `Connect-Sectigo -ClientId/-ClientSecret`. Consider adding a note/alert in the cmdlet XML docs (and regenerating) indicating it is legacy-connection only.

DESCRIPTION

Builds an API client and lists all organizations for the account.

**Module/Docs/Update-SectigoCertificate.md:25**
* The example omits the mandatory `-CertificateId` (position 0) parameter, and uses placeholder values for `-DcvMode` that aren’t valid enum values. Since `CertificateId`, `Csr`, and `DcvMode` are all mandatory in `SectigoCertificateManager.PowerShell/UpdateSectigoCertificateCommand.cs`, this example won’t run as-is. Add an XML `<example>` to the cmdlet docs and regenerate so the generated page shows a valid invocation (e.g., include `-CertificateId 123` and a real `-DcvMode Email`).

EXAMPLE 1

Update-SectigoCertificate -Csr 'Value' -DcvMode 'Value'

**.github/workflows/powershell.yml:55**
* The PR description notes PSPublishModule 3.0.83+ is required, but the workflow installs whatever the gallery returns at runtime. To keep CI deterministic and to ensure the documentation gate doesn’t run against an older incompatible module (e.g., due to caching or transient gallery issues), it would be safer to enforce a minimum (or exact) version in the install step.

  - name: Verify generated documentation
    run: |
      ./Module/Build/Build-Module.ps1 -ConfigurationGateMode Documentation
      $documentationChanges = @(git status --porcelain --untracked-files=all -- Module/Docs Module/en-US)
      if ($documentationChanges.Count -gt 0) {
        $documentationChanges | Write-Host
        throw 'Generated documentation is not up to date.'
      }

</details>

[Copilot]

Pull request overview

Copilot reviewed 53 out of 54 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (7)

Module/Docs/Update-SectigoCertificate.md:24

• This example is not runnable: it omits the mandatory -CertificateId parameter and uses an invalid DcvMode value ('Value'). Update the example to include a certificate id and a valid DCV mode.

Update-SectigoCertificate -Csr 'Value' -DcvMode 'Value'

Module/Docs/Export-SectigoCertificate.md:24

• This example is not runnable: it omits the mandatory -CertificateId parameter. Update it to include a certificate id (and optionally an explicit format) so users can copy/paste it.

Export-SectigoCertificate -Path 'C:\Path'

Module/Docs/Connect-Sectigo.md:31

• The example command is malformed (it contains "-Username "user"******" and omits the required -Password parameter), so users cannot copy/paste it successfully. Replace it with a valid legacy connection example.

PS> Connect-Sectigo -BaseUrl "https://cert-manager.com/api" -Username "user" -Password "pass" -CustomerUri "tenant" -ApiVersion V25_6

Module/Docs/Get-SectigoOrganizations.md:24

• The example passes an invalid ApiVersion value ('Value'), so it will fail if copy/pasted. Use a valid ApiVersion (e.g. V25_6) or omit the parameter to rely on the default.

Get-SectigoOrganizations -ApiVersion 'Value'

Module/Docs/Get-SectigoCertificateStatus.md:24

• The example omits the mandatory -CertificateId parameter and also passes an invalid ApiVersion value ('Value'), so it cannot run as written. Update it to include a certificate id (and optionally omit ApiVersion to use the default).

Get-SectigoCertificateStatus -ApiVersion 'Value'

Module/Docs/Get-SectigoCertificateRevocation.md:24

• The example omits the mandatory -CertificateId parameter and also passes an invalid ApiVersion value ('Value'), so it cannot run as written. Update it to include a certificate id (and optionally omit ApiVersion to use the default).

Get-SectigoCertificateRevocation -ApiVersion 'Value'

Module/Docs/Invoke-SectigoCertificateRenewal.md:30

• This example is not runnable: it omits the mandatory identifier parameter (-OrderNumber for Legacy or -CertificateId for AdminById) and uses an invalid DcvMode value ('Value'). Update it to match one of the documented parameter sets.

Invoke-SectigoCertificateRenewal -Csr 'Value' -DcvMode 'Value'

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3a8caf0953

ℹ️ 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".

[chatgpt-codex-connector]

Replace synthesized examples with invocable commands

When users copy this newly published example, it cannot run: 'Value' is not a valid ApiVersion, and the mandatory CertificateId is omitted. The generated Status, renewal, update, and export examples have the same problem, so add explicit XML <example> blocks for these cmdlets and regenerate both the Markdown and MAML help. AGENTS.MDL165-L173

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Document no-output cmdlets as returning nothing

When callers consult the new output contract, this claims that Disconnect-Sectigo emits an object even though ProcessRecord only clears session variables and never writes pipeline output. The same incorrect System.Object output is generated for Export-SectigoCertificate, Remove-SectigoCertificate, and Stop-SectigoOrder, whose implementations likewise perform side effects without calling WriteObject; mark these outputs as None in both Markdown and MAML.

Useful? React with 👍 / 👎.